sbin/natacontrol/natacontrol.8

   1 .\"
   2 .\" Copyright (c) 2000,2001,2002 Søren Schmidt <sos@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD: src/sbin/atacontrol/atacontrol.8,v 1.28 2005/11/18 10:32:09 ru Exp $
  27 .\"
  28 .Dd March 23, 2013
  29 .Dt NATACONTROL 8
  30 .Os
  31 .Sh NAME
  32 .Nm natacontrol
  33 .Nd NATA device driver control program
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Aq Ar command
  37 .Ar args
  38 .Pp
  39 .Nm
  40 .Ic attach
  41 .Ar channel
  42 .Nm
  43 .Ic detach
  44 .Ar channel
  45 .Nm
  46 .Ic reinit
  47 .Ar channel
  48 .Nm
  49 .Ic create
  50 .Ar type Oo Ar interleave Oc Ar disk0 ... diskN
  51 .Nm
  52 .Ic delete
  53 .Ar raid
  54 .Nm
  55 .Ic addspare
  56 .Ar raid disk
  57 .Nm
  58 .Ic rebuild
  59 .Ar raid
  60 .Nm
  61 .Ic status
  62 .Ar raid
  63 .Nm
  64 .Ic mode
  65 .Ar device
  66 .Nm
  67 .Ic info
  68 .Ar channel
  69 .Nm
  70 .Ic cap
  71 .Ar device
  72 .Nm
  73 .Ic feature
  74 .Ar device acoustic soundsupplevel
  75 .Nm
  76 .Ic feature
  77 .Ar device apm apmlevel
  78 .Nm
  79 .Ic list
  80 .Sh DESCRIPTION
  81 The
  82 .Nm
  83 utility is a control program that provides the user access and control to the
  84 .Dx
  85 .Xr nata 4
  86 subsystem.
  87 .Pp
  88 The
  89 .Nm
  90 utility
  91 can cause severe system crashes and loss of data if used improperly.
  92 Please
  93 exercise caution when using this command!
  94 .Pp
  95 The
  96 .Ar channel
  97 argument is the ATA channel device (e.g., ata0) on which to operate.
  98 The following commands are supported:
  99 .Bl -tag -width "rebuild"
 100 .It Ic attach
 101 Attach an ATA
 102 .Ar channel .
 103 Devices on the channel are probed and attached as
 104 is done on boot.
 105 .It Ic detach
 106 Detach an ATA
 107 .Ar channel .
 108 Devices on the channel are removed from the kernel,
 109 and all outstanding transfers etc.\& are returned back to the system marked
 110 as failed.
 111 .It Ic reinit
 112 Reinitialize an ATA
 113 .Ar channel .
 114 Both devices on the channel are reset and
 115 initialized to the parameters the ATA driver has stored internally.
 116 Devices that have gone bad and no longer respond to the probe, or devices
 117 that have physically been removed, are removed from the kernel.
 118 Likewise are devices that show up during a reset, probed and attached.
 119 .It Ic create
 120 Create a
 121 .Ar type
 122 ATA RAID.
 123 The type can be
 124 .Cm RAID0
 125 (stripe),
 126 .Cm RAID1
 127 (mirror),
 128 .Cm RAID0+1 ,
 129 .Cm SPAN
 130 or
 131 .Cm JBOD .
 132 In case the RAID has a
 133 .Cm RAID0
 134 component,
 135 the
 136 .Ar interleave
 137 must be specified in number of sectors.
 138 The RAID will be created
 139 of the individual disks named
 140 .Bk -words
 141 .Ar disk0 ... diskN .
 142 .Ek
 143 .Pp
 144 Although the
 145 .Xr nata 4
 146 driver allows for creating an ATA RAID on disks with any controller,
 147 there are restrictions.
 148 It is only possible to boot on an array if it is either located on a
 149 .Dq real
 150 ATA RAID controller like
 151 the Promise or Highpoint controllers, or if the RAID declared is of
 152 .Cm RAID1
 153 or
 154 .Cm SPAN
 155 type; in case of a
 156 .Cm SPAN ,
 157 the partition to boot must
 158 reside on the first disk in the SPAN.
 159 .It Ic delete
 160 Delete a RAID array on a RAID capable ATA controller.
 161 .It Ic addspare
 162 Add a spare disk to an existing RAID.
 163 .It Ic rebuild
 164 Rebuild a RAID1 array on a RAID capable ATA controller.
 165 .It Ic status
 166 Get the status of an ATA RAID.
 167 .It Ic mode
 168 Without the mode argument, the current transfer modes of the
 169 device are printed.
 170 If the mode argument is given, the
 171 .Xr nata 4
 172 driver is asked to change the transfer mode to the one given.
 173 The
 174 .Xr nata 4
 175 driver will reject modes that are not supported by the hardware.
 176 Modes are given like
 177 .Dq Li PIO3 ,
 178 .Dq Li udma2 ,
 179 .Dq Li udma100 ,
 180 case does not matter.
 181 .Pp
 182 Currently supported modes are:
 183 .Cm PIO0 , PIO1 , PIO2 , PIO3 , PIO4 ,
 184 .Cm WDMA2 ,
 185 .Cm UDMA2
 186 (alias
 187 .Cm UDMA33 ) ,
 188 .Cm UDMA4
 189 (alias
 190 .Cm UDMA66 ) ,
 191 .Cm UDMA5
 192 (alias
 193 .Cm UDMA100 )
 194 and
 195 .Cm UDMA6
 196 (alias
 197 .Cm UDMA133 ) .
 198 The device name and manufacture/version strings are shown.
 199 .It Ic cap
 200 Show detailed info about the device on
 201 .Ar device .
 202 .It Ic feature
 203 Set disk drive features.
 204 Currently,
 205 .Ar acoustic
 206 and
 207 .Ar apm
 208 features are supported.
 209 .Bl -tag -width "acoustic"
 210 .It Ar acoustic soundsupplevel
 211 Controls the disk drive Acoustic Management level.
 212 The
 213 .Ar soundsupplevel
 214 may be set to
 215 .Cm off
 216 which will turn off acoustic management,
 217 .Cm maxperf
 218 to optimize for maximum performance,
 219 .Cm maxquiet
 220 to optimize for maximum quiet, or a numeric level
 221 from 0 to 124.
 222 The higher the numeric level, the higher the
 223 theoretical sound level emitted from the drive.
 224 Note that few devices support this command and even fewer will allow the
 225 range of levels supported.
 226 .It Ar apm apmlevel
 227 Sets the disk drive Advanced Power Management (APM) level.
 228 This command is generally used on laptop (notebook) hard disks to control
 229 the power level consumed by the drive (at the expense of performance).
 230 .Pp
 231 The
 232 .Ar apmlevel
 233 may be set to one of:
 234 .Cm off
 235 (turn off APM),
 236 .Cm maxperf
 237 or
 238 .Cm minpower
 239 (optimize for maximum performance or minimum power, respectively), or
 240 a numeric level which can be 0 to 127 inclusive indicating an increasing
 241 level of performance over power savings.
 242 The numeric levels may be prefixed by
 243 .Cm s
 244 which will allow the drive to include suspension as part of the
 245 power savings.
 246 Note that not all hard drives will support the
 247 .Cm off
 248 command, and that the number of incremental power savings levels
 249 do not typically have as wide of a range as this command will
 250 support.
 251 .El
 252 .It Ic info
 253 Show info about the attached devices on the
 254 .Ar channel .
 255 .It Ic list
 256 Show info about all attached devices on all active controllers.
 257 .El
 258 .Sh EXAMPLES
 259 To get information on devices attached to a channel,
 260 use the command line:
 261 .Pp
 262 .Dl "natacontrol info ata0"
 263 .Pp
 264 To see the devices' current access modes, use the command line:
 265 .Pp
 266 .Dl "natacontrol mode ad0"
 267 .Pp
 268 which results in the modes of the devices being displayed as a string
 269 like this:
 270 .Pp
 271 .Dl "current mode = UDMA100"
 272 .Pp
 273 You can set the mode with
 274 .Nm
 275 and a string like the above,
 276 for example:
 277 .Pp
 278 .Dl "natacontrol mode ad0 PIO4"
 279 .Pp
 280 The new modes are set as soon as the
 281 .Nm
 282 command returns.
 283 .Sh SEE ALSO
 284 .Xr nata 4
 285 .Sh HISTORY
 286 The
 287 .Nm
 288 utility first appeared in
 289 .Fx 4.6
 290 and was imported into
 291 .Dx 1.7 .
 292 .Sh AUTHORS
 293 .An -nosplit
 294 The
 295 .Nm
 296 utility was written by
 297 .An S\(/oren Schmidt Aq Mt sos@FreeBSD.org .
 298 .Pp
 299 This manual page was written by
 300 .An S\(/oren Schmidt Aq Mt sos@FreeBSD.org .