1.\" $NetBSD: atactl.8,v 1.32 2022/05/24 06:27:59 andvar Exp $ 2.\" 3.\" Copyright (c) 1998, 2019 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 and Matthew R. Green. 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 March 2, 2019 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 46allows a user or system administrator to issue commands to and otherwise 47control devices which reside on standard IDE and ATA controllers, or 48the ATA bus itself. 49It is used by specifying a device or bus to manipulate, 50the command to perform, and any arguments the command may require. 51.Pp 52You may also control devices which are inside a SCSI enclosure, this 53includes many USB disks. 54In this case ATA commands are passed through 55the SCSI layer using SATL commands. 56.Sh DEVICE COMMANDS 57The following commands may be used on IDE and ATA devices. 58Note that not all devices support all commands. 59.Bl -tag -width setidleXX 60.It Cm identify 61Identify the specified device, displaying the device's vendor, product, 62revision strings, and the device's capabilities. 63.It Cm idle 64Place the specified device into Idle mode. 65This mode may consume less power than Active mode. 66.It Cm standby 67Place the specified device into Standby mode. 68This mode will consume less power than Idle mode. 69.It Cm sleep 70Place the specified device into Sleep mode. 71This mode will consume less power than Standby mode, 72but requires a device reset to resume operation. 73Typically the 74.Xr wd 4 75driver performs this reset automatically, 76but this should still be used with caution. 77.It Cm setidle Ar idle-timer 78Places the specified device into Idle mode, 79and sets the Idle timer to 80.Ar idle-timer 81seconds. 82A value of 0 will disable the Idle timer. 83.It Cm setstandby Ar standby-timer 84Places the specified device into Standby mode, 85and sets the Standby timer to 86.Ar standby-timer 87seconds. 88A value of 0 will disable the Standby timer. 89.It Cm checkpower 90Will print out if the device is in Active, Idle, or Standby power 91management mode. 92.It Cm apm Oo Ar disable | set # Oc 93Controls the Advanced Power Management feature of the specified device. 94Advanced Power Management is an optional feature used to specify a power 95management level to balance between device performance and power consumption. 96.Bl -tag -width selftestXlogXX 97.It Ar disable 98Disable the Advanced Power Management. 99.It Ar set # 100Enable the Advanced Power Management feature and set its level to the value #, 101where # is an integer within the scale 0-253; being 0 the mode with the 102lowest power consumption (and thus the worse performance) and 253 the mode 103which provides the better performance at a cost of more power consumption. 104.Pp 105It should be noted that the effect of the value need not be continuous. 106For example, a device might provide only two modes: one from 0 to 126 107and other from 127 to 253. 108Per the specification, values of 127 and higher do not permit the device 109to spin down to save power. 110.El 111.It Cm smart Oo Ar enable | disable | status Oo vendor Oc | offline # | error-log | selftest-log Oc 112Controls SMART feature set of the specified device. 113SMART stands for Self-Monitoring, Analysis, and Reporting Technology. 114It provides an early warning system by comparing subtle operation 115characteristics to those determined in vendor testing 116to precede device failures. 117.Bl -tag -width selftestXlogXX 118.It Ar enable 119Enables access to SMART capabilities within the device. 120Prior to being enabled, a SMART capable device neither 121monitors nor saves SMART attribute values. 122The state of SMART, either enabled or disabled, will 123be preserved by the device across power cycles. 124.It Ar disable 125Disables access to SMART capabilities within the device. 126Attribute values will be saved, and will no longer be monitored. 127.It Ar status Op Ar vendor 128Reports whether SMART is supported by the device, and whether SMART is 129enabled on the device (can only be determined on ATA6 or better devices). 130If SMART is enabled, then a table of attribute information is printed. 131Attributes are the specific performance or calibration parameters that 132are used in analyzing the status of the device. 133The specific set of attributes being used and the identity of 134these attributes is vendor specific and proprietary. 135.Pp 136Attribute values are used to represent the relative reliability of 137individual performance or calibration parameters. 138The valid range of attribute values is from 1 to 253 decimal. 139Lower values indicate that the analysis algorithms being used by the device 140are predicting a higher probability of a degrading or faulty condition. 141.Pp 142Each attribute value has a corresponding threshold limit which is used for 143direct comparison to the attribute value to indicate the existence of a 144degrading or faulty condition. 145The numerical value of the attribute thresholds are determined by the 146device manufacturer through design and reliability testing and analysis. 147Each attribute threshold represents the lowest limit to which its 148corresponding attribute value can equal while still retaining a 149positive reliability status. 150.Pp 151If the crit field is 152.Dq yes 153then negative reliability of this attribute 154predicts imminent data loss. 155Otherwise it merely indicates that the intended design life period 156of usage or age has been exceeded. 157The collect field indicates whether this attribute is updated while the 158device is online. 159The reliability field indicates whether the attribute 160value is within the acceptable threshold. 161.Pp 162If the 163.Ar vendor 164argument is supplied, a vendor-specific table will be used for SMART 165information if known to 166.Nm . 167Currently, only 168.Dq micron 169has a vendor-specific table. 170If the vendor is not supplied, it may be guessed from devices' model 171or other data available. 172.It Ar offline # 173Runs the numbered offline self-test on the drive. 174.It Ar error-log 175Prints the error log. 176.It Ar selftest-log 177Prints the self-test log. 178.El 179.It Cm security Oo Ar status | freeze | setpass | unlock | disable | erase Oc 180Controls 181.Dq security 182(password protection) features of modern ATA drives. 183The security commands are intended to be issued by low-level 184software (firmware / BIOS) only. 185Generally, the security status should be 186.Dq frozen 187before the operating system is started so that misbehaving or malicious 188software cannot set or change a password. 189Older and buggy BIOSes neglect to do so; in these cases it might make 190sense to issue the 191.Dq freeze 192command early in the boot process. 193.Bl -tag -width freezeXX 194.It Ar status 195displays the drive's security status 196.It Ar freeze 197freezes the drive's security status 198.It Ar setpass Oo user | master Oc 199sets the drive's user or master password 200.It Ar unlock Oo user | master Oc 201unlocks a password-protected drive 202.It Ar disable Oo user | master Oc 203disables password protection 204.It Ar erase Oo user | master Oc 205erases the device and clears security state, using enhanced erasure if 206the drive supports it; may take a long time to run 207.El 208.Pp 209Note that to erase a drive, it must have a password set and be 210unfrozen. 211If you can't persuade your firmware to leave the drive unfrozen on 212boot, but it is a SATA drive, say 213.Pa wd2 214at 215.Pa atabus3 , 216that you can safely physically disconnect and reconnect, then you may 217be able to use SATA hot-plug to work around this: first run 218.Bd -literal -offset indent 219# drvctl -d wd2 220.Ed 221.Pp 222Then physically disconnect and reconnect the drive, and run 223.Bd -literal -offset indent 224# drvctl -r -a ata_hl atabus3 225.Ed 226.Pp 227After this, check that the security status does not list 228.Dq frozen : 229.Bd -literal -offset indent 230# atactl wd2 security status 231 supported 232# 233.Ed 234.El 235.Sh BUS COMMANDS 236The following commands may be used on IDE and ATA busses. 237Note that not all devices support all commands. 238.Bl -tag -width resetXX 239.It Cm reset 240Reset the bus. 241This will reset all ATA devices present on the bus. 242Any ATAPI device with pending commands will also be reset. 243.El 244.Sh EXAMPLES 245To erase 246.Pa wd2 247which is currently unfrozen and has no password set: 248.Bd -literal -offset indent 249# atactl wd2 security status 250 supported 251# atactl wd2 security setpass user 252Password: 253Confirm password: 254# atactl wd2 security status 255 supported 256 enabled 257# atactl wd2 security erase user 258Password: 259Erasing may take up to 0h 2m 0s... 260# 261.Ed 262.Sh SEE ALSO 263.Xr ioctl 2 , 264.Xr wd 4 , 265.Xr dkctl 8 , 266.Xr drvctl 8 , 267.Xr scsictl 8 268.Sh HISTORY 269The 270.Nm 271command first appeared in 272.Nx 1.4 . 273.Sh AUTHORS 274.An -nosplit 275The 276.Nm 277command was written by 278.An Ken Hornstein . 279It was based heavily on the 280.Xr scsictl 8 281command written by 282.An Jason R. Thorpe . 283.An Matthew R. Green 284significantly enhanced the 285.Cm smart status 286support. 287.An Michael van Elst 288added support for SATL. 289.Sh BUGS 290The output from the 291.Cm identify 292command is rather ugly. 293.Pp 294Support for master passwords is not implemented. 295.Pp 296The 297.Nx 298kernel behaves poorly with drives that have passwords set and are 299locked. 300.Pp 301The 302.Cm smart status 303command currently guesses the vendor attribute name table to use, 304and may be wrong or miss supported devices. 305.Pp 306SATL bus commands don't work yet. 307