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