sbin/atactl/atactl.8

   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.
 105 .El
 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.
 130 .Pp
 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.
 136 .Pp
 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.
 145 .Pp
 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.
 162 .El
 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
 182 .El
 183 .El
 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.
 192 .El
 193 .Sh SEE ALSO
 194 .Xr ioctl 2 ,
 195 .Xr wd 4 ,
 196 .Xr dkctl 8 ,
 197 .Xr scsictl 8
 198 .Sh HISTORY
 199 The
 200 .Nm
 201 command first appeared in
 202 .Nx 1.4 .
 203 .Sh AUTHORS
 204 The
 205 .Nm
 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.