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 December 31, 2017
  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 spindown
  80 .Ar device
  81 .Op Ar seconds
  82 .Nm
  83 .Ic list
  84 .Sh DESCRIPTION
  85 The
  86 .Nm
  87 utility is a control program that provides the user access and control to the
  88 .Dx
  89 .Xr nata 4
  90 subsystem.
  91 .Pp
  92 The
  93 .Nm
  94 utility
  95 can cause severe system crashes and loss of data if used improperly.
  96 Please
  97 exercise caution when using this command!
  98 .Pp
  99 The
 100 .Ar channel
 101 argument is the ATA channel device (e.g., ata0) on which to operate.
 102 The following commands are supported:
 103 .Bl -tag -width "rebuild"
 104 .It Ic attach
 105 Attach an ATA
 106 .Ar channel .
 107 Devices on the channel are probed and attached as
 108 is done on boot.
 109 .It Ic detach
 110 Detach an ATA
 111 .Ar channel .
 112 Devices on the channel are removed from the kernel,
 113 and all outstanding transfers etc.\& are returned back to the system marked
 114 as failed.
 115 .It Ic reinit
 116 Reinitialize an ATA
 117 .Ar channel .
 118 Both devices on the channel are reset and
 119 initialized to the parameters the ATA driver has stored internally.
 120 Devices that have gone bad and no longer respond to the probe, or devices
 121 that have physically been removed, are removed from the kernel.
 122 Likewise are devices that show up during a reset, probed and attached.
 123 .It Ic create
 124 Create a
 125 .Ar type
 126 ATA RAID.
 127 The type can be
 128 .Cm RAID0
 129 (stripe),
 130 .Cm RAID1
 131 (mirror),
 132 .Cm RAID0+1 ,
 133 .Cm SPAN
 134 or
 135 .Cm JBOD .
 136 In case the RAID has a
 137 .Cm RAID0
 138 component,
 139 the
 140 .Ar interleave
 141 must be specified in number of sectors.
 142 The RAID will be created
 143 of the individual disks named
 144 .Bk -words
 145 .Ar disk0 ... diskN .
 146 .Ek
 147 .Pp
 148 Although the
 149 .Xr nata 4
 150 driver allows for creating an ATA RAID on disks with any controller,
 151 there are restrictions.
 152 It is only possible to boot on an array if it is either located on a
 153 .Dq real
 154 ATA RAID controller like
 155 the Promise or Highpoint controllers, or if the RAID declared is of
 156 .Cm RAID1
 157 or
 158 .Cm SPAN
 159 type; in case of a
 160 .Cm SPAN ,
 161 the partition to boot must
 162 reside on the first disk in the SPAN.
 163 .It Ic delete
 164 Delete a RAID array on a RAID capable ATA controller.
 165 .It Ic addspare
 166 Add a spare disk to an existing RAID.
 167 .It Ic rebuild
 168 Rebuild a RAID1 array on a RAID capable ATA controller.
 169 .It Ic status
 170 Get the status of an ATA RAID.
 171 .It Ic mode
 172 Without the mode argument, the current transfer modes of the
 173 device are printed.
 174 If the mode argument is given, the
 175 .Xr nata 4
 176 driver is asked to change the transfer mode to the one given.
 177 The
 178 .Xr nata 4
 179 driver will reject modes that are not supported by the hardware.
 180 Modes are given like
 181 .Dq Li PIO3 ,
 182 .Dq Li udma2 ,
 183 .Dq Li udma100 ,
 184 case does not matter.
 185 .Pp
 186 Currently supported modes are:
 187 .Cm PIO0 , PIO1 , PIO2 , PIO3 , PIO4 ,
 188 .Cm WDMA2 ,
 189 .Cm UDMA2
 190 (alias
 191 .Cm UDMA33 ) ,
 192 .Cm UDMA4
 193 (alias
 194 .Cm UDMA66 ) ,
 195 .Cm UDMA5
 196 (alias
 197 .Cm UDMA100 )
 198 and
 199 .Cm UDMA6
 200 (alias
 201 .Cm UDMA133 ) .
 202 The device name and manufacture/version strings are shown.
 203 .It Ic cap
 204 Show detailed info about the device on
 205 .Ar device .
 206 .It Ic feature
 207 Set disk drive features.
 208 Currently,
 209 .Ar acoustic
 210 and
 211 .Ar apm
 212 features are supported.
 213 .Bl -tag -width "acoustic"
 214 .It Ar acoustic soundsupplevel
 215 Controls the disk drive Acoustic Management level.
 216 The
 217 .Ar soundsupplevel
 218 may be set to
 219 .Cm off
 220 which will turn off acoustic management,
 221 .Cm maxperf
 222 to optimize for maximum performance,
 223 .Cm maxquiet
 224 to optimize for maximum quiet, or a numeric level
 225 from 0 to 124.
 226 The higher the numeric level, the higher the
 227 theoretical sound level emitted from the drive.
 228 Note that few devices support this command and even fewer will allow the
 229 range of levels supported.
 230 .It Ar apm apmlevel
 231 Sets the disk drive Advanced Power Management (APM) level.
 232 This command is generally used on laptop (notebook) hard disks to control
 233 the power level consumed by the drive (at the expense of performance).
 234 .Pp
 235 The
 236 .Ar apmlevel
 237 may be set to one of:
 238 .Cm off
 239 (turn off APM),
 240 .Cm maxperf
 241 or
 242 .Cm minpower
 243 (optimize for maximum performance or minimum power, respectively), or
 244 a numeric level which can be 0 to 127 inclusive indicating an increasing
 245 level of performance over power savings.
 246 The numeric levels may be prefixed by
 247 .Cm s
 248 which will allow the drive to include suspension as part of the
 249 power savings.
 250 Note that not all hard drives will support the
 251 .Cm off
 252 command, and that the number of incremental power savings levels
 253 do not typically have as wide of a range as this command will
 254 support.
 255 .El
 256 .It Ic spindown
 257 Set or report timeout after which the
 258 .Ar device
 259 will be spun down.
 260 To arm the timeout the device needs at least one more request after
 261 setting the timeout.
 262 To disable spindown, set the timeout to zero.
 263 No further actions are needed in this case.
 264 .It Ic info
 265 Show info about the attached devices on the
 266 .Ar channel .
 267 .It Ic list
 268 Show info about all attached devices on all active controllers.
 269 .El
 270 .Sh EXAMPLES
 271 To get information on devices attached to a channel,
 272 use the command line:
 273 .Pp
 274 .Dl "natacontrol info ata0"
 275 .Pp
 276 To see the devices' current access modes, use the command line:
 277 .Pp
 278 .Dl "natacontrol mode ad0"
 279 .Pp
 280 which results in the modes of the devices being displayed as a string
 281 like this:
 282 .Pp
 283 .Dl "current mode = UDMA100"
 284 .Pp
 285 You can set the mode with
 286 .Nm
 287 and a string like the above,
 288 for example:
 289 .Pp
 290 .Dl "natacontrol mode ad0 PIO4"
 291 .Pp
 292 The new modes are set as soon as the
 293 .Nm
 294 command returns.
 295 .Sh SEE ALSO
 296 .Xr nata 4
 297 .Sh HISTORY
 298 The
 299 .Nm
 300 utility first appeared in
 301 .Fx 4.6
 302 and was imported into
 303 .Dx 1.7 .
 304 .Sh AUTHORS
 305 .An -nosplit
 306 The
 307 .Nm
 308 utility was written by
 309 .An S\(/oren Schmidt Aq Mt sos@FreeBSD.org .
 310 .Pp
 311 This manual page was written by
 312 .An S\(/oren Schmidt Aq Mt sos@FreeBSD.org .