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