1.\" $NetBSD: scsictl.8,v 1.32 2022/08/21 12:44:16 mlelstv Exp $ 2.\" 3.\" Copyright (c) 1998, 2002 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility, 8.\" NASA Ames Research Center. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd November 19, 2016 32.Dt SCSICTL 8 33.Os 34.Sh NAME 35.Nm scsictl 36.Nd a program to manipulate SCSI devices and busses 37.Sh SYNOPSIS 38.Nm 39.Ar device 40.Ar command 41.Oo 42.Ar arg Oo ... 43.Oc 44.Oc 45.Sh DESCRIPTION 46.Nm 47allows a user or system administrator to issue commands to and otherwise 48control SCSI devices and busses. 49It is used by specifying a device or bus to manipulate, 50the command to perform, and any arguments the command may require. 51.Nm 52determines if the specified device is an actual device or a SCSI bus 53automatically, and selects the appropriate command set. 54.Pp 55For commands which 56.Nm 57issues a SCSI command to the device directly, any returned sense information 58will be decoded by 59.Nm 60and displayed to the standard output. 61.Sh DEVICE COMMANDS 62The following commands are supported for SCSI devices: 63.Bl -tag -width flushcacheXX 64.It Cm debug Ar level 65Set the debugging level for the given device; the following flags are 66supported: 67.Pp 68.Bl -tag -compact -width xx -offset indent 69.It Ar 1 70Show scsi commands, errors, data. 71.It Ar 2 72Routine flow tracking. 73.It Ar 4 74Internal info from routine flows. 75.It Ar 8 76Device specific debugging. 77.El 78.Pp 79This option is only supported with kernels compiled with 80.Dv SCSIPI_DEBUG . 81.It Cm defects Oo primary Oc Oo grown Oc Oo block|byte|physical Oc 82Read the primary and/or grown defect lists from the specified device 83in block, byte from index, or physical sector format. 84The default is to return both the primary and grown defect lists 85in physical sector format. 86This command is only supported on direct access devices. 87.It Cm format Oo blocksize Oo immediate Oc Oc 88(Low level) format the named device. 89If the optional 90.Li blocksize 91parameter is provided, the device geometry will be modified to 92use the specified 93.Li blocksize . 94If this parameter is different form the Current or Default Mode Page 3 95parameters, the device will update Mode Page 3 at the successful 96completion of the Format. 97Device geometry may change as a result of using a new device 98.Li blocksize . 99When the optional 100.Li blocksize 101parameter is specified, the Defect List on the drive will revert to 102the original primary defect list created at the time of manufacture 103if available. 104The drive will usually recertify itself during the Format 105and add any other defective blocks to the new Defect List. 106Some disks may not support the ability to change the blocksize and 107may enter a Degraded Mode when fed a Format command of this type. 108If this happens the standard recovery for the drive requires issuing 109a correct Format command, i.e. one without the blocksize parameter. 110.Pp 111When the 112.Li immediate 113parameter is also specified, the disk is instructed to return from the 114format command right away. 115It continues to format, and every ten seconds 116.Nm 117issues a TEST UNIT READY command to check the associated sense data. 118This associated sense data has a progress indicator which indicates 119how far the format is progressing. 120Note well that most SCSI disk drives prior to 121a few years ago do not support this option. 122.It Cm identify 123Identify the specified device, displaying the device's SCSI 124bus, target, and lun, as well as the device's vendor, product, 125and revision strings. 126.It Cm reassign Ar blkno Oo blkno Oo ... Oc Oc 127Issues a 128.Li REASSIGN BLOCKS 129command to the device, adding the specified blocks to the 130grown defect list. 131This command is only supported on direct access devices. 132.It Cm release 133Send a 134.Dq RELEASE 135command to the device to release a reservation on it. 136.It Cm reserve 137Send a 138.Dq RESERVE 139command to the device to place a reservation on it. 140.It Cm reset 141Reset the device. 142This command is only supported for devices which support the 143.Li SCIOCRESET 144ioctl. 145.It Cm start 146Send a 147.Dq START 148command to the device. 149This is useful typically only for disk devices. 150.It Cm stop 151Send a 152.Dq STOP 153command to the device. 154This is useful typically only for disk devices. 155.It Cm tur 156Send a 157.Dq TEST UNIT READY 158command to the device. 159This is useful for generating current device status. 160.It Cm getcache 161Returns basic cache parameters for the device. 162.It Cm setcache Ar none|r|w|rw Op Ar save 163Set basic cache parameters for the device. 164The cache may be disabled 165.Pq none , 166the read cache enabled 167.Pq r , 168the write cache enabled 169.Pq w , 170or both read and write cache enabled 171.Pq rw . 172If the drive's cache parameters are savable, specifying 173.Ar save 174after the cache enable state will cause the parameters to be saved in 175non-volatile storage. 176.It Cm flushcache 177Explicitly flushes the write cache. 178.It Cm setspeed Ar speed 179Set the highest speed that the optical drive should use for reading 180data. 181The units are multiples of a single speed CDROM (150 KB/s). 182Specify 0 to use the drive's fastest speed. 183.It Cm getrealloc 184Returns automatic reallocation parameters for the device. 185.It Cm setrealloc Ar none|r|w|rw Op Ar save 186Set automatic reallocation parameters for the device. 187Automatic reallocation may be disabled 188.Pq none , 189the automatic read reallocation enabled 190.Pq r , 191the automatic write reallocation enabled 192.Pq w , 193or both automatic read and write reallocation enabled 194.Pq rw . 195If the drive's automatic reallocation parameters are savable, specifying 196.Ar save 197after the automatic reallocation enable state will cause the parameters to be 198saved in non-volatile storage. 199.It Cm reportluns Ar normal|wellknown|all|# 200Report Logical Units provided by the drive. 201.Bl -hang -compact 202.It normal 203report all but well-known logical units. 204This is also the default. 205.It wellknown 206report the well known logical units instead. E.g., 207.Bl -inset -compact 208.It 0xc101h 209Addressable objects 210.It 0xc102h 211Addressable objects associations 212.It 0xc103h 213SCSI target device identification 214.El 215.It all 216report all logical units. 217.It # 218Use the given numeric select report value (0-255). 219.El 220.El 221.Sh BUS COMMANDS 222The following commands are supported for SCSI busses: 223.Bl -tag width scanXtargetXlunXX 224.It Cm reset 225Reset the SCSI bus. 226This command is only supported if the host adapter supports the 227.Li SCBUSIORESET 228ioctl. 229.It Cm scan Ar target Ar lun 230Scan the SCSI bus for devices. 231This is useful if a device was not connected or powered 232on when the system was booted. 233The 234.Ar target 235and 236.Ar lun 237arguments specify which SCSI target and lun on the bus is to be scanned. 238Either may be wildcarded by specifying the keyword 239.Dq any 240or 241.Dq all . 242.It Cm detach Ar target Ar lun 243Detach the specified device from the bus. 244Useful if a device is powered down after use. 245The 246.Ar target 247and 248.Ar lun 249arguments have the same meaning as for the 250.Cm scan 251command, and may also be wildcarded. 252.El 253.Sh NOTES 254When scanning the SCSI bus, information about newly recognized devices 255is printed to console. 256No information is printed for already probed devices. 257.Sh FILES 258.Pa /dev/scsibus* 259- for commands operating on SCSI busses 260.Sh SEE ALSO 261.Xr ioctl 2 , 262.Xr cd 4 , 263.Xr ch 4 , 264.Xr scsi 4 , 265.Xr sd 4 , 266.Xr se 4 , 267.Xr ss 4 , 268.Xr st 4 , 269.Xr uk 4 , 270.Xr atactl 8 , 271.Xr dkctl 8 272.Sh HISTORY 273The 274.Nm 275command first appeared in 276.Nx 1.4 . 277.Sh AUTHORS 278.An -nosplit 279The 280.Nm 281command was written by 282.An Jason R. Thorpe 283of the Numerical Aerospace Simulation Facility, NASA Ames Research Center. 284