1 '\" te
   2 .\" Copyright (c) 2007 by Sun Microsystems, Inc.  All rights reserved.
   3 .\" Copyright 2016 Joyent, Inc.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH USCSI 7I "Sep 23, 2016"
   8 .SH NAME
   9 uscsi \- user SCSI command interface
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/scsi/impl/uscsi.h>
  14 
  15 \fB\fR\fBioctl\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIrequest\fR, \fBstruct uscsi_cmd *\fR\fIcmd\fR);
  16 .fi
  17 
  18 .SH DESCRIPTION
  19 .LP
  20 The \fBuscsi\fR command is very powerful and somewhat dangerous; therefore it
  21 has some permission restrictions. See \fBWARNINGS\fR for more details.
  22 .sp
  23 .LP
  24 Drivers supporting this \fBioctl\fR(2) provide a general interface allowing
  25 user-level applications to cause individual \fBSCSI\fR commands to be directed
  26 to a particular \fBSCSI\fR or \fBATAPI\fR device under control of that driver.
  27 The \fBuscsi\fR command is supported by the \fBsd\fR driver for \fBSCSI\fR
  28 disks and \fBATAPI\fR CD-ROM drives, and by the \fBst\fR driver for \fBSCSI\fR
  29 tape drives. \fBuscsi\fR may also be supported by other device drivers; see the
  30 specific device driver manual page for complete information.
  31 .sp
  32 .LP
  33 Applications must not assume that all Solaris disk device drivers support the
  34 \fBuscsi\fR ioctl command. The \fBSCSI\fR command may include a data transfer
  35 to or from that device, if appropriate for that command. Upon completion of the
  36 command, the user application can determine how many bytes were transferred and
  37 the status returned by the device. Also, optionally, if the command returns a
  38 Check Condition status, the driver will automatically issue a Request Sense
  39 command and return the sense data along with the original status. See the
  40 \fBUSCSI_RQENABLE\fR flag below for this Request Sense processing. The
  41 \fBuscsi_cmd\fR structure is defined in \fB<sys/scsi/impl/uscsi.h>\fR and
  42 includes the following members:
  43 .sp
  44 .in +2
  45 .nf
  46 int uscsi_flags;               /* read, write, etc. see below */
  47 short uscsi_status;           /* resulting status */
  48 short uscsi_timeout;          /* Command Timeout */
  49 caddr_t uscsi_cdb             /* CDB to send to target */
  50 caddr_t uscsi_bufaddr;        /* i/o source/destination */
  51 size_t uscsi_buflen;          /* size of i/o to take place*/
  52 size_t uscsi_resid;           /* resid from i/o operation */
  53 uchar_t uscsi_cdblen;         /* # of valid CDB bytes */
  54 uchar_t uscsi_rqlen;          /* size of uscsi_rqbuf */
  55 uchar_t uscsi_rqstatus;       /* status of request sense cmd */
  56 uchar_t uscsi_rqresid;        /* resid of request sense cmd */
  57 caddr_t uscsi_rqbuf;          /* request sense buffer */
  58 void *uscsi_reserved_5;       /* Reserved for future use */
  59 .fi
  60 .in -2
  61 
  62 .sp
  63 .LP
  64 The fields of the \fBuscsi_cmd\fR structure have the following meanings:
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fBuscsi_flags\fR\fR
  69 .ad
  70 .RS 20n
  71 The \fBI/O\fR direction and other details of how to carry out the \fBSCSI\fR
  72 command. Possible values are described below.
  73 .RE
  74 
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fBuscsi_status\fR\fR
  79 .ad
  80 .RS 20n
  81 The \fBSCSI\fR status byte returned by the device is returned in this field.
  82 .RE
  83 
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fBuscsi_timeout\fR\fR
  88 .ad
  89 .RS 20n
  90 Time in seconds to allow for completion of the command.
  91 .RE
  92 
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fBuscsi_cdb\fR\fR
  97 .ad
  98 .RS 20n
  99 A pointer to the \fBSCSI\fR CDB (command descriptor block) to be transferred to
 100 the device in command phase.
 101 .RE
 102 
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fBuscsi_bufaddr\fR\fR
 107 .ad
 108 .RS 20n
 109 The user buffer containing the data to be read from or written to the device.
 110 .RE
 111 
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fBuscsi_buflen\fR\fR
 116 .ad
 117 .RS 20n
 118 The length of \fBuscsi_bufaddr\fR.
 119 .RE
 120 
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fBuscsi_resid\fR\fR
 125 .ad
 126 .RS 20n
 127 If a data transfer terminates without transferring the entire requested amount,
 128 the remainder, or residue, is returned in this field.
 129 .RE
 130 
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fBuscsi_cdblen\fR\fR
 135 .ad
 136 .RS 20n
 137 The length of the \fBSCSI\fR CDB to be transferred to the device in command
 138 phase.
 139 .RE
 140 
 141 .sp
 142 .ne 2
 143 .na
 144 \fB\fBuscsi_rqlen\fR\fR
 145 .ad
 146 .RS 20n
 147 The length of \fBuscsi_rqbuf\fR, the application's Request Sense buffer.
 148 .RE
 149 
 150 .sp
 151 .ne 2
 152 .na
 153 \fB\fBuscsi_rqstatus\fR\fR
 154 .ad
 155 .RS 20n
 156 The \fBSCSI\fR status byte returned for the Request Sense command executed
 157 automatically by the driver in response to a Check Condition status return.
 158 .RE
 159 
 160 .sp
 161 .ne 2
 162 .na
 163 \fB\fBuscsi_rqresid\fR\fR
 164 .ad
 165 .RS 20n
 166 The residue, or untransferred data length, of the Request Sense data transfer
 167 (the number of bytes, less than or equal to \fBuscsi_rqlen\fR, which were not
 168 filled with sense data).
 169 .RE
 170 
 171 .sp
 172 .ne 2
 173 .na
 174 \fB\fBuscsi_rqbuf\fR\fR
 175 .ad
 176 .RS 20n
 177 Points to a buffer in application address space to which the results of an
 178 automatic Request Sense command are written.
 179 .RE
 180 
 181 .sp
 182 .ne 2
 183 .na
 184 \fB\fBuscsi_reserved_5\fR\fR
 185 .ad
 186 .RS 20n
 187 Reserved for future use.
 188 .RE
 189 
 190 .sp
 191 .LP
 192 The \fBuscsi_flags\fR field defines the following:
 193 .sp
 194 .in +2
 195 .nf
 196 USCSI_WRITE                   /* send data to device */
 197 USCSI_SILENT                  /* no error messages */
 198 USCSI_DIAGNOSE                /* fail if any error occurs */
 199 USCSI_ISOLATE                 /* isolate from normal commands */
 200 USCSI_READ                    /* get data from device */
 201 USCSI_ASYNC                   /* set bus to asynchronous mode */
 202 USCSI_SYNC                    /* return bus to sync mode if possible */
 203 USCSI_RESET                   /* reset target */
 204 USCSI_RESET_TARGET            /* reset target */
 205 USCSI_RESET_LUN               /* reset logical unit */
 206 USCSI_RESET_ALL               /* reset all targets */
 207 USCSI_RQENABLE                /* enable request sense extensions */
 208 USCSI_RENEGOT                 /* renegotiate wide/sync on next I/O */
 209 .fi
 210 .in -2
 211 
 212 .sp
 213 .LP
 214 The \fBuscsi_flags\fR bits have the following interpretation:
 215 .sp
 216 .ne 2
 217 .na
 218 \fB\fBUSCSI_WRITE\fR\fR
 219 .ad
 220 .RS 22n
 221 Data will be written from the initiator to the target.
 222 .RE
 223 
 224 .sp
 225 .ne 2
 226 .na
 227 \fB\fBUSCSI_SILENT\fR\fR
 228 .ad
 229 .RS 22n
 230 The driver should not print any console error messages or warnings regarding
 231 failures associated with this \fBSCSI\fR command.
 232 .RE
 233 
 234 .sp
 235 .ne 2
 236 .na
 237 \fB\fBUSCSI_DIAGNOSE\fR\fR
 238 .ad
 239 .RS 22n
 240 The driver should not attempt any retries or other recovery mechanisms if this
 241 \fBSCSI\fR command terminates abnormally in any way.
 242 .RE
 243 
 244 .sp
 245 .ne 2
 246 .na
 247 \fB\fBUSCSI_ISOLATE\fR\fR
 248 .ad
 249 .RS 22n
 250 This \fBSCSI\fR command should not be executed with other commands.
 251 .RE
 252 
 253 .sp
 254 .ne 2
 255 .na
 256 \fB\fBUSCSI_READ\fR\fR
 257 .ad
 258 .RS 22n
 259 Data will be read from the target to the initiator.
 260 .RE
 261 
 262 .sp
 263 .ne 2
 264 .na
 265 \fB\fBUSCSI_ASYNC\fR\fR
 266 .ad
 267 .RS 22n
 268 Set the \fBSCSI\fR bus to asynchronous mode before running this command.
 269 .RE
 270 
 271 .sp
 272 .ne 2
 273 .na
 274 \fB\fBUSCSI_SYNC\fR\fR
 275 .ad
 276 .RS 22n
 277 Set the \fBSCSI\fR bus to synchronous mode before running this command.
 278 .RE
 279 
 280 .sp
 281 .ne 2
 282 .na
 283 \fB\fBUSCSI_RESET\fR\fR
 284 .ad
 285 .RS 22n
 286 Send a \fBSCSI\fR bus device reset message to this target.
 287 .RE
 288 
 289 .sp
 290 .ne 2
 291 .na
 292 \fB\fBUSCSI_RESET_TARGET\fR\fR
 293 .ad
 294 .RS 22n
 295 Same as USCSI_RESET. Use this flag to request TARGET RESET. (USCSI_RESET is
 296 maintained only for compatibility with old applications).
 297 .RE
 298 
 299 .sp
 300 .ne 2
 301 .na
 302 \fB\fBUSCSI_RESET_LUN\fR\fR
 303 .ad
 304 .RS 22n
 305 Send a \fBSCSI\fR logical unit reset message to this target.
 306 .RE
 307 
 308 .sp
 309 .ne 2
 310 .na
 311 \fB\fBUSCSI_RESET_ALL\fR\fR
 312 .ad
 313 .RS 22n
 314 USCSI_RESET_ALL, USCSI_RESET/USCSI_RESET_TARGET and USCSI_RESET_LUN are
 315 mutually exclusive options and issuing them in any simultaneous combination
 316 will result in implementation-dependent behavior
 317 .sp
 318 When a USCSI reset request is combined with other \fBSCSI\fR commands, the
 319 following semantics take effect:
 320 .sp
 321 If the USCSI RESET flag is specified, the other fields (other than uscsi_flags)
 322 in the uscsi_cmd are ignored. The uscsi_cdblen \fBmust\fR be set to zero.
 323 .RE
 324 
 325 .sp
 326 .ne 2
 327 .na
 328 \fB\fBUSCSI_RQENABLE\fR\fR
 329 .ad
 330 .RS 22n
 331 Enable Request Sense extensions. If the user application is prepared to receive
 332 sense data, this bit must be set, the fields \fBuscsi_rqbuf\fR and
 333 \fBuscsi_rqbuflen\fR must be non-zero, and the \fBuscsi_rqbuf\fR must point to
 334 memory writable by the application.
 335 .RE
 336 
 337 .sp
 338 .ne 2
 339 .na
 340 \fB\fBUSCSI_RENEGOT\fR\fR
 341 .ad
 342 .RS 22n
 343 Tells USCSI to renegotiate wide mode and synchronous transfer speed before the
 344 transmitted SCSI command is executed. This flag in effects tells the target
 345 driver to pass the \fBFLAG_RENEGOTIATE_WIDE_SYNC\fR flag in the SCSI packet
 346 before passing the command to an adapter driver for transport.
 347 .sp
 348 See the \fBscsi_pkt\fR(9S) flag \fBFLAG_RENEGOTIATE_WIDE_SYNC\fR for more
 349 information.
 350 .RE
 351 
 352 The \fBuscsi_xfer_t\fR is a type definition that corresponds to a 64-bit
 353 unsigned integer. It should be used for the \fBUSCSIMAXXFER\fR ioctls. This is
 354 used for determining the maximum transfer size that can be performed in a single
 355 \fBUSCSICMD\fR ioctl. If the SCSI request is larger than the specified size,
 356 then it may not work, depending on the hardware platform.
 357 
 358 .SH IOCTLS
 359 .LP
 360 The \fBioctl\fR supported by drivers providing the \fBuscsi\fR interface is:
 361 .sp
 362 .ne 2
 363 .na
 364 \fB\fBUSCSICMD\fR\fR
 365 .ad
 366 .RS 12n
 367 The argument is a pointer to a \fBuscsi_cmd\fR structure. The \fBSCSI\fR device
 368 addressed by that driver is selected, and given the \fBSCSI\fR command
 369 addressed by \fBuscsi_cdb\fR. If this command requires a data phase, the
 370 \fBuscsi_buflen\fR and \fBuscsi_bufaddr\fR fields must be set appropriately; if
 371 data phase occurs, the \fBuscsi_resid\fR is returned as the number of bytes not
 372 transferred. The status of the command, as returned by the device, is returned
 373 in the \fBuscsi_status\fR field. If the command terminates with Check Condition
 374 status, and Request Sense is enabled, the sense data itself is returned in
 375 \fBuscsi_rqbuf\fR. The \fBuscsi_rqresid\fR provides the residue of the Request
 376 Sense data transfer.
 377 .RE
 378 
 379 .sp
 380 .ne 2
 381 .na
 382 .B USCSIMAXXFER
 383 .ad
 384 .RS 12n
 385 The argument is a pointer to a \fBuscsi_xfer_t\fR value. The maximum transfer
 386 size that can be used with the \fBUSCSICMD\fR ioctl for the current device will
 387 be returned in the \fBuscsi_xfer_t\fR.
 388 .sp
 389 .LP
 390 Not all devices which support the \fBUSCSICMD\fR ioctl also support the
 391 \fBUSCSIMAXXFER\fR ioctl.
 392 .RE
 393 
 394 .SH ERRORS
 395 .ne 2
 396 .na
 397 \fB\fBEINVAL\fR\fR
 398 .ad
 399 .RS 10n
 400 A parameter has an incorrect, or unsupported, value.
 401 .RE
 402 
 403 .sp
 404 .ne 2
 405 .na
 406 \fB\fBEIO\fR\fR
 407 .ad
 408 .RS 10n
 409 An error occurred during the execution of the command.
 410 .RE
 411 
 412 .sp
 413 .ne 2
 414 .na
 415 \fB\fBEPERM\fR\fR
 416 .ad
 417 .RS 10n
 418 A process without root credentials tried to execute the \fBUSCSICMD\fR or
 419 \fBUSCSIMAXXFER\fR ioctl.
 420 .RE
 421 
 422 .sp
 423 .ne 2
 424 .na
 425 \fB\fBEFAULT\fR\fR
 426 .ad
 427 .RS 10n
 428 The \fBuscsi_cmd\fR itself, the \fBuscsi_cdb\fR, the \fBuscsi_buf\fR, the
 429 \fBuscsi_rqbuf\fR, or the \fBuscsi_xfer_t\fR point to an invalid address.
 430 .RE
 431 
 432 .SH ATTRIBUTES
 433 .LP
 434 See \fBattributes\fR(5) for descriptions of the following attributes:
 435 .sp
 436 
 437 .sp
 438 .TS
 439 box;
 440 c | c
 441 l | l .
 442 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 443 _
 444 Interface Stability     Committed
 445 .TE
 446 
 447 .SH SEE ALSO
 448 .LP
 449 \fBioctl\fR(2), \fBattributes\fR(5), \fBsd\fR(7D), \fBst\fR(7D)
 450 .sp
 451 .LP
 452 \fIANSI Small Computer System Interface-2 (SCSI-2)\fR
 453 .SH WARNINGS
 454 .LP
 455 The \fBuscsi\fR command is very powerful, but somewhat dangerous, and so its
 456 use is restricted to processes running as root, regardless of the file
 457 permissions on the device node. The device driver code expects to own the
 458 device state, and \fBuscsi\fR commands can change the state of the device and
 459 confuse the device driver. It is best to use \fBuscsi\fR commands only with no
 460 side effects, and avoid commands such as Mode Select, as they may cause damage
 461 to data stored on the drive or system panics. Also, as the commands are not
 462 checked in any way by the device driver, any block may be overwritten, and the
 463 block numbers are absolute block numbers on the drive regardless of which slice
 464 number is used to send the command.
 465 .sp
 466 .LP
 467 The \fBuscsi\fR interface is not recommended for very large data transfers
 468 (typically more than 16MB). If the requested transfer size exceeds the maximum
 469 transfer size of the DMA engine, it will not be broken up into multiple
 470 transfers and DMA errors may result. The \fBUSCSIMAXXFER\fR ioctl can be used
 471 to determine the maximum transfer size.
 472 .sp
 473 .LP
 474 The \fBUSCSICMD\fR ioctl associates a \fBstruct uscsi_cmd\fR with a device by
 475 using an open file descriptor to the device. Other APIs might provide the same
 476 \fBstruct uscsi_cmd\fR programming interface, but perform device association in
 477 some other manner.