sbin/scsictl/scsictl.8

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