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