2 .\" Copyright (c) 2000,2001,2002 Søren Schmidt <sos@FreeBSD.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
33 .Nd ATA device driver control program
57 .Ar type Oo Ar interleave Oc Ar disk0 ... diskN
89 utility is a control program that provides the user access and control to the
97 can cause severe system crashes and loss of data if used improperly.
99 exercise caution when using this command!
103 argument is the ATA channel device (e.g., ata0) on which to operate.
104 The following commands are supported:
105 .Bl -tag -width ".Ic addspare"
109 Devices on the channel are probed and attached as
114 Devices on the channel are removed from the kernel,
115 and all outstanding transfers etc.\& are returned back to the system marked
120 Both devices on the channel are reset and
121 initialized to the parameters the ATA driver has stored internally.
122 Devices that have gone bad and no longer respond to the probe, or devices
123 that have physically been removed, are removed from the kernel.
124 Likewise are devices that show up during a reset, probed and attached.
138 In case the RAID has a
143 must be specified in number of sectors.
144 The RAID will be created
145 of the individual disks named
147 .Ar disk0 ... diskN .
150 Although the ATA driver allows for creating an ATA RAID on disks with any
151 controller, there are restrictions.
152 It is only possible to boot on
153 an array if it is either located on a
155 ATA RAID controller like
156 the Promise or Highpoint controllers, or if the RAID declared is of
162 the partition to boot must
163 reside on the first disk in the SPAN.
165 Delete a RAID array on a RAID capable ATA controller.
167 Add a spare disk to an existing RAID.
169 Rebuild a RAID1 array on a RAID capable ATA controller.
171 Get the status of an ATA RAID.
175 argument, the current transfer mode of the
179 argument is given, the ATA driver
180 is asked to change the transfer mode to the one given.
182 will reject modes that are not supported by the hardware.
187 case does not matter.
189 Currently supported modes are:
190 .Cm BIOSPIO , PIO0 , PIO1 , PIO2 , PIO3 , PIO4 , WDMA2 , UDMA2
202 .Cm SATA150 , SATA300 , USB , USB1 , USB2
206 Show detailed info about the device on
209 Set or report timeout after which the
212 To arm the timeout the device needs at least one more request after
214 To disable spindown, set the timeout to zero.
215 No further actions are needed in this case.
217 Show info about the attached devices on the
219 The device name and manufacture/version strings are shown.
221 Show info about all attached devices on all active controllers.
224 To get information on devices attached to a channel,
225 use the command line:
227 .Dl "atacontrol info ata0"
229 To see the devices' current access modes, use the command line:
231 .Dl "atacontrol mode ad0"
233 which results in the modes of the devices being displayed as a string
236 .Dl "current mode = UDMA100"
238 You can set the mode with
240 and a string like the above,
243 .Dl "atacontrol mode ad0 PIO4"
245 The new modes are set as soon as the
249 The atacontrol command can also be used to create purely software
250 RAID arrays in systems that do NOT have a "real" hardware RAID card
251 such as a Highpoint or Promise card.
252 A common scenario is a 1U server such as the HP DL320 G4 or G5.
253 These servers contain a SATA controller that has 2 channels that can
254 contain 2 disks per channel, but the servers are wired to only place
255 a single SATA drive on each channel.
256 These servers do have a "pseudo" RAID BIOS but it uses a proprietary
257 format that is not compatible with the ata driver, and thus their
258 RAID bios must be switched off.
259 Another common scenario would be a Promise UDMA100 controller card
260 that did not contain the Fasttrack RAID BIOS, but did contain 2
262 1 disk would be attached to one channel and the other disk would be
263 attached to the other channel.
264 It is NOT recommended to create such arrays on a primary/secondary
265 pair on a SINGLE channel since the throughput of the mirror would be
266 severely compromised, the ability to rebuild the array in the event
267 of a disk failure would be greatly complicated, and if a disk
268 controller electronics failed it could wedge the channel and take
269 both disks in the mirror offline.
270 (which would defeat the purpose of having a mirror in the first place)
272 A quick and dirty way to create such a mirrored array on a new
273 system is to boot off the FreeBSD install CD, do a minimal scratch
274 install, abort out of the post install questions, and at the command
275 line issue the command:
277 .Dl "atacontrol create RAID1 ad4 ad6"
279 then immediately issue a reboot and boot from the installation CD
280 again, and during the installation, you will now see "ar0" listed
281 as a disk to install on, and install on that instead of ad4, ad6, etc.
283 To get information about the status of a RAID array in the system
284 use the command line:
286 .Dl "atacontrol status ar0"
288 A typical output showing good health on a RAID array might be as
291 .Dl "ar0: ATA RAID1 subdisks: ad4 ad6 status: READY"
293 If a disk drive in a RAID1 array dies the system will mark the disk
294 in a DOWN state and change the array status to DEGRADED.
295 This can ALSO happen in rare instances due to a power fluctuation or
296 other event causing the system to not shutdown properly.
297 In that case the output will look like the following:
299 .Dl "ar0: ATA RAID1 subdisks: ad4 DOWN status: DEGRADED"
301 For a mirrored RAID1 system the server WILL ALLOW you to remove a
302 dead SATA disk drive (if the drive is in a hot-swap tray) without
303 freezing up the system, so you can remove the disk and while you are
304 obtaining a replacement the server can run from the active disk.
305 The only caveat is that if the active disk is ad6, the system most
306 likely will NOT be able to be rebooted since most systems only
307 support booting from the first disk drive.
309 To deactivate the DOWN disk ad6 to allow for it to be ejected, use
312 .Dl "atacontrol detach ata3"
314 then eject or remove the disk.
315 Note that this only works if the 2 disks in the mirror are on separate
316 channels (which is the standard setup for 1-U servers like the HP DL320).
317 When the new disk drive is obtained, make sure it is blank, then shut
319 At this point, if the system has a RAID array card like a Highpoint or
320 Promise controller, you may then boot it into the BIOS of the card and use
321 the manufacturers RAID array rebuild utilities to rebuild the array.
323 If the system has a pure software array and is not using a "real" ATA
324 RAID controller, then shut the system down, make sure that the disk
325 that was still working is moved to the bootable position (channel 0
326 or whatever the BIOS allows the system to boot from) and the blank disk
327 is placed in the secondary position, then boot the system into
328 single-user mode and issue the command:
330 .Dl "atacontrol addspare ar0 ad6"
331 .Dl "atacontrol rebuild ar0"
333 If the disk drive did NOT fail and the RAID array became unmirrored due
334 to a software glitch or improper shutdown, then a slightly different
335 process must be followed.
336 Begin by issuing the detach command (this shows the detach for disk ad6,
337 the primary master on channel 3):
339 .Dl "atacontrol detach ata3"
341 then reboot the system into single-user mode.
342 (don't just init the system, reboot it so that both disks get probed)
343 You will probably see TWO mirrored RAID arrays appear during the boot
344 messages, ar0 and ar1.
347 .Dl "atacontrol delete ar1"
348 .Dl "atacontrol addspare ar0 ad6"
350 Now a status command will show the array rebuilding.
352 To spin down a disk after 30 minutes run
354 .Dl "atacontrol spindown ad6 1800"
355 .Dl "dd if=/dev/ad6 of=/dev/null count=1"
357 While any IO on the disk will arm the timer, using
359 on the raw device will work in all cases, as when the disk is not
361 You can check the current setting with
363 .Dl "atacontrol spindown ad6"
365 You should not set a spindown timeout on a disk with
367 or syslog logging on it as the disk will be worn out spinning down and
376 utility first appeared in
386 utility was written by
388 .Aq sos@FreeBSD.org .
390 This manual page was written by
392 .Aq sos@FreeBSD.org .
396 utility was deprecated in
399 .Bd -ragged -offset indent
400 .Cd "options ATA_CAM"
403 is compiled into the kernel, then
405 must be used instead.