Sync usage with man page.
[netbsd-mini2440.git] / sbin / atactl / atactl.8
blobde72c09efa85f41bd07d0c5d961b38ae78cd790c
1 .\"     $NetBSD: atactl.8,v 1.22 2007/11/18 17:48:21 christos Exp $
2 .\"
3 .\" Copyright (c) 1998 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Ken Hornstein.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\"    notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\"    notice, this list of conditions and the following disclaimer in the
16 .\"    documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd November 18, 2007
31 .Dt ATACTL 8
32 .Os
33 .Sh NAME
34 .Nm atactl
35 .Nd a program to manipulate ATA (IDE) devices and busses
36 .Sh SYNOPSIS
37 .Nm
38 .Ar device
39 .Ar command
40 .Oo
41 .Ar arg Oo ...
42 .Oc
43 .Oc
44 .Sh DESCRIPTION
45 .Nm
46 allows a user or system administrator to issue commands to and otherwise
47 control devices which reside on standard IDE and ATA controllers, or
48 the ATA bus itself.
49 It is used by specifying a device or bus to manipulate,
50 the command to perform, and any arguments the command may require.
51 .Sh DEVICE COMMANDS
52 The following commands may be used on IDE and ATA devices.
53 Note that not all devices support all commands.
54 .Bl -tag -width setidleXX
55 .It Cm identify
56 Identify the specified device, displaying the device's vendor, product,
57 revision strings, and the device's capabilities.
58 .It Cm idle
59 Place the specified device into Idle mode.
60 This mode may consume less power than Active mode.
61 .It Cm standby
62 Place the specified device into Standby mode.
63 This mode will consume less power than Idle mode.
64 .It Cm sleep
65 Place the specified device into Sleep mode.
66 This mode will consume less power than Standby mode,
67 but requires a device reset to resume operation.
68 Typically the
69 .Xr wd 4
70 driver performs this reset automatically,
71 but this should still be used with caution.
72 .It Cm setidle Ar idle-timer
73 Places the specified device into Idle mode,
74 and sets the Idle timer to
75 .Ar idle-timer
76 seconds.
77 A value of 0 will disable the Idle timer.
78 .It Cm setstandby Ar standby-timer
79 Places the specified device into Standby mode,
80 and sets the Standby timer to
81 .Ar standby-timer
82 seconds.
83 A value of 0 will disable the Standby timer.
84 .It Cm checkpower
85 Will print out if the device is in Active, Idle, or Standby power
86 management mode.
87 .It Cm apm Bq Ar disable | set #
88 Controls the Advanced Power Management feature of the specified device.
89 Advanced Power Management is an optional feature used to specify a power
90 management level to balance between device performance and power consumption.
91 .Bl -tag -width selftestXlogXX
92 .It Ar disable
93 Disable the Advanced Power Management.
94 .It Ar set #
95 Enable the Advanced Power Management feature and set its level to the value #,
96 where # is an integer within the scale 0-253; being 0 the mode with the
97 lowest power consumption (and thus the worse performance) and 253 the mode
98 which provides the better performance at a cost of more power consumption.
99 .Pp
100 It should be noted that the effect of the value need not be continous.
101 For example, a device might provide only two modes: one from 0 to 126
102 and other from 127 to 253.
103 Per the specification, values of 127 and higher do not permit the device
104 to spin down to save power.
106 .It Cm smart Bq Ar enable | disable | status | offline # | error-log | selftest-log
107 Controls SMART feature set of the specified device.
108 SMART stands for Self-Monitoring, Analysis, and Reporting Technology.
109 It provides an early warning system by comparing subtle operation
110 characteristics to those determined in vendor testing
111 to precede device failures.
112 .Bl -tag -width selftestXlogXX
113 .It Ar enable
114 Enables access to SMART capabilities within the device.
115 Prior to being enabled, a SMART capable device neither
116 monitors nor saves SMART attribute values.
117 The state of SMART, either enabled or disabled, will
118 be preserved by the device across power cycles.
119 .It Ar disable
120 Disables access to SMART capabilities within the device.
121 Attribute values will be saved, and will no longer be monitored.
122 .It Ar status
123 Reports whether SMART is supported by the device, and whether SMART is
124 enabled on the device (can only be determined on ATA6 or better devices).
125 If SMART is enabled, then a table of attribute information is printed.
126 Attributes are the specific performance or calibration parameters that
127 are used in analyzing the status of the device.
128 The specific set of attributes being used and the identity of
129 these attributes is vendor specific and proprietary.
131 Attribute values are used to represent the relative reliability of
132 individual performance or calibration parameters.
133 The valid range of attribute values is from 1 to 253 decimal.
134 Lower values indicate that the analysis algorithms being used by the device
135 are predicting a higher probability of a degrading or faulty condition.
137 Each attribute value has a corresponding threshold limit which is used for
138 direct comparison to the attribute value to indicate the existence of a
139 degrading or faulty condition.
140 The numerical value of the attribute thresholds are determined by the
141 device manufacturer through design and reliability testing and analysis.
142 Each attribute threshold represents the lowest limit to which its
143 corresponding attribute value can equal while still retaining a
144 positive reliability status.
146 If the crit field is
147 .Dq yes
148 then negative reliability of this attribute
149 predicts imminent data loss.
150 Otherwise it merely indicates that the intended design life period
151 of usage or age has been exceeded.
152 The collect field indicates whether this attribute is updated while the
153 device is online.
154 The reliability field indicates whether the attribute
155 value is within the acceptable threshold.
156 .It Ar offline #
157 Runs the numbered offline self-test on the drive.
158 .It Ar error-log
159 Prints the error log.
160 .It Ar selftest-log
161 Prints the self-test log.
163 .It Cm security Bq Ar freeze | status
164 Controls
165 .Dq security
166 (password protection) features of modern ATA drives.
167 The security commands are intended to be issued by low-level
168 software (firmware / BIOS) only.
169 Generally, the security status should be
170 .Dq frozen
171 before the operating system is started so that misbehaving or malicious
172 software cannot set or change a password.
173 Older and buggy BIOSes neglect to do so; in these cases it might make
174 sense to issue the
175 .Dq freeze
176 command early in the boot process.
177 .Bl -tag -width freezeXX
178 .It Ar freeze
179 freezes the drive's security status
180 .It Ar status
181 displays the drive's security status
184 .Sh BUS COMMANDS
185 The following commands may be used on IDE and ATA busses.
186 Note that not all devices support all commands.
187 .Bl -tag -width resetXX
188 .It Cm reset
189 Reset the bus.
190 This will reset all ATA devices present on the bus.
191 Any ATAPI device with pending commands will also be reset.
193 .Sh SEE ALSO
194 .Xr ioctl 2 ,
195 .Xr wd 4 ,
196 .Xr dkctl 8 ,
197 .Xr scsictl 8
198 .Sh HISTORY
201 command first appeared in
202 .Nx 1.4 .
203 .Sh AUTHORS
206 command was written by Ken Hornstein.
207 It was based heavily on the
208 .Xr scsictl 8
209 command written by Jason R. Thorpe.
210 .Sh BUGS
211 The output from the
212 .Cm identify
213 command is rather ugly.