diff options
Diffstat (limited to 'usr/src/man/man7i/uscsi.7i')
| -rw-r--r-- | usr/src/man/man7i/uscsi.7i | 395 |
1 files changed, 0 insertions, 395 deletions
diff --git a/usr/src/man/man7i/uscsi.7i b/usr/src/man/man7i/uscsi.7i deleted file mode 100644 index 874b07e7e0..0000000000 --- a/usr/src/man/man7i/uscsi.7i +++ /dev/null @@ -1,395 +0,0 @@ -.\" Copyright (c) 2007 by Sun Microsystems, Inc. All rights reserved. -.\" Copyright 2017 Joyent, Inc. -.\" 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. -.\" -.\" 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. -.\" -.\" 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] -.Dd October 23, 2017 -.Dt USCSI 7I -.Os -.Sh NAME -.Nm uscsi -.Nd user SCSI command interface -.Sh SYNOPSIS -.In sys/scsi/impl/uscsi.h -.Fo ioctl -.Fa "int filedes" -.Fa "int request" -.Fa "struct uscsi_cmd *cmd" -.Fc -.Sh DESCRIPTION -The -.Nm -command is very powerful and somewhat dangerous; therefore it -has some permission restrictions. -See -.Sx WARNINGS -for more details. -.Pp -Drivers supporting this -.Xr ioctl 2 -provide a general interface allowing user-level applications to cause individual -.Sy SCSI -commands to be directed to a particular -.Sy SCSI -or -.Sy ATAPI -device under control of that driver. -The -.Nm -command is supported by the -.Xr sd 7D -driver for -.Sy SCSI -disks and -.Sy ATAPI -CD-ROM drives, and by the -.Xr st 7D -driver for -.Sy SCSI -tape drives. -.Nm -may also be supported by other device drivers; see the -specific device driver manual page for complete information. -.Pp -Applications must not assume that all Solaris disk device drivers support the -.Nm -ioctl command. -The -.Sy SCSI -command may include a data transfer -to or from that device, if appropriate for that command. -Upon completion of the command, the user application can determine how many -bytes were transferred and the status returned by the device. -Also, optionally, if the command returns a -Check Condition status, the driver will automatically issue a Request Sense -command and return the sense data along with the original status. -See the -.Sy USCSI_RQENABLE -flag below for this Request Sense processing. -The -.Vt uscsi_cmd -structure is defined in -.In sys/scsi/impl/uscsi.h -and includes the following members: -.Bd -literal -offset 2n -int uscsi_flags; /* read, write, etc. see below */ -short uscsi_status; /* resulting status */ -short uscsi_timeout; /* Command Timeout */ -caddr_t uscsi_cdb /* CDB to send to target */ -caddr_t uscsi_bufaddr; /* i/o source/destination */ -size_t uscsi_buflen; /* size of i/o to take place*/ -size_t uscsi_resid; /* resid from i/o operation */ -uchar_t uscsi_cdblen; /* # of valid CDB bytes */ -uchar_t uscsi_rqlen; /* size of uscsi_rqbuf */ -uchar_t uscsi_rqstatus; /* status of request sense cmd */ -uchar_t uscsi_rqresid; /* resid of request sense cmd */ -caddr_t uscsi_rqbuf; /* request sense buffer */ -void *uscsi_reserved_5; /* Reserved for future use */ -.Ed -.Pp -The fields of the -.Vt uscsi_cmd -structure have the following meanings: -.Bl -tag -width uscsi_reserved_5 -.It Sy uscsi_flags -The -.Sy I/O -direction and other details of how to carry out the -.Sy SCSI -command. -Possible values are described below. -.It Fa uscsi_status -The -.Sy SCSI -status byte returned by the device is returned in this field. -.It Fa uscsi_timeout -Time in seconds to allow for completion of the command. -.It Fa uscsi_cdb -A pointer to the -.Sy SCSI -CDB (command descriptor block) to be transferred to the device in command phase. -.It Fa uscsi_bufaddr -The user buffer containing the data to be read from or written to the device. -.It Sy uscsi_buflen -The length of -.Fa uscsi_bufaddr . -.It Fa uscsi_resid -If a data transfer terminates without transferring the entire requested amount, -the remainder, or residue, is returned in this field. -.It Fa uscsi_cdblen -The length of the -.Sy SCSI -CDB to be transferred to the device in command phase. -.It Fa uscsi_rqlen -The length of -.Fa uscsi_rqbuf , -the application's Request Sense buffer. -.It Fa uscsi_rqstatus -The -.Sy SCSI -status byte returned for the Request Sense command executed -automatically by the driver in response to a Check Condition status return. -.It Fa uscsi_rqresid -The residue, or untransferred data length, of the Request Sense data transfer -(the number of bytes, less than or equal to -.Fa uscsi_rqlen , -which were not filled with sense data). -.It Fa uscsi_rqbuf -Points to a buffer in application address space to which the results of an -automatic Request Sense command are written. -.It Fa uscsi_reserved_5 -Reserved for future use. -.El -.Pp -The -.Fa uscsi_flags -field defines the following: -.Bd -literal -offset 2n -USCSI_WRITE /* send data to device */ -USCSI_SILENT /* no error messages */ -USCSI_DIAGNOSE /* fail if any error occurs */ -USCSI_ISOLATE /* isolate from normal commands */ -USCSI_READ /* get data from device */ -USCSI_ASYNC /* set bus to asynchronous mode */ -USCSI_SYNC /* return bus to sync mode if possible */ -USCSI_RESET /* reset target */ -USCSI_RESET_TARGET /* reset target */ -USCSI_RESET_LUN /* reset logical unit */ -USCSI_RESET_ALL /* reset all targets */ -USCSI_RQENABLE /* enable request sense extensions */ -USCSI_RENEGOT /* renegotiate wide/sync on next I/O */ -.Ed -.Pp -The -.Fa uscsi_flags -bits have the following interpretation: -.Bl -tag -width USCSI_RESET_TARGET -.It Dv USCSI_WRITE -Data will be written from the initiator to the target. -.It Dv USCSI_SILENT -The driver should not print any console error messages or warnings regarding -failures associated with this -.Sy SCSI -command. -.It Dv USCSI_DIAGNOSE -The driver should not attempt any retries or other recovery mechanisms if this -.Sy SCSI -command terminates abnormally in any way. -.It Dv USCSI_ISOLATE -This -.Sy SCSI -command should not be executed with other commands. -.It Dv USCSI_READ -Data will be read from the target to the initiator. -.It Dv USCSI_ASYNC -Set the -.Sy SCSI -bus to asynchronous mode before running this command. -.It Dv USCSI_SYNC -Set the -.Sy SCSI -bus to synchronous mode before running this command. -.It Dv USCSI_RESET -Send a -.Sy SCSI -bus device reset message to this target. -.It Dv USCSI_RESET_TARGET -Same as USCSI_RESET. -Use this flag to request TARGET RESET. -.Po -.Dv USCSI_RESET -is maintained only for compatibility with old applications -.Pc . -.It Dv USCSI_RESET_LUN -Send a -.Sy SCSI -logical unit reset message to this target. -.It Dv USCSI_RESET_ALL -.Dv USCSI_RESET_ALL , -.Dv USCSI_RESET/USCSI_RESET_TARGET , -and -.Dv USCSI_RESET_LUN -are -mutually exclusive options and issuing them in any simultaneous combination -will result in implementation-dependent behavior -When a USCSI reset request is combined with other -.Sy SCSI -commands, the following semantics take effect: -If the -.Dv USCSI RESET -flag is specified, the other fields (other than -.Fa uscsi_flags ) -in the -.Vt uscsi_cmd -are ignored. -The -.Fa uscsi_cdblen -field -.Em must -be set to zero. -.It Dv USCSI_RQENABLE -Enable Request Sense extensions. -If the user application is prepared to receive -sense data, this bit must be set, the fields -.Fa uscsi_rqbuf -and -.Fa uscsi_rqbuflen -must be non-zero, and the -.Fa uscsi_rqbuf -must point to memory writable by the application. -.It Dv USCSI_RENEGOT -Tells USCSI to renegotiate wide mode and synchronous transfer speed before the -transmitted SCSI command is executed. -This flag in effects tells the target driver to pass the -.Dv FLAG_RENEGOTIATE_WIDE_SYNC -flag in the SCSI packet -before passing the command to an adapter driver for transport. -See the -.Xr scsi_pkt 9S -flag -.Dv FLAG_RENEGOTIATE_WIDE_SYNC -for more information. -.El -.Pp -The -.Vt uscsi_xfer_t -is a type definition that corresponds to a 64-bit unsigned integer. -It should be used for the -.Dv USCSIMAXXFER -ioctls. -This is -used for determining the maximum transfer size that can be performed in a single -.Dv USCSICMD -ioctl. -If the SCSI request is larger than the specified size, -then it may not work, depending on the hardware platform. -.Sh IOCTLS -The -.Fn ioctl -supported by drivers providing the -.Nm -interface is: -.Bl -tag -width USCSIMAXXFER -.It Dv USCSICMD -The argument is a pointer to a -.Vt uscsi_cmd -structure. -The -.Sy SCSI -device addressed by that driver is selected, and given the -.Sy SCSI -command addressed by -.Fa uscsi_cdb . -If this command requires a data phase, the -.Fa uscsi_buflen -and -.Fa uscsi_bufaddr -fields must be set appropriately; if data phase occurs, the -.Fa uscsi_resid -is returned as the number of bytes not transferred. -The status of the command, as returned by the device, is returned in the -.Fa uscsi_status -field. -If the command terminates with Check Condition -status, and Request Sense is enabled, the sense data itself is returned in -.Fa uscsi_rqbuf . -The -.Fa uscsi_rqresid -provides the residue of the Request Sense data transfer. -.It Dv USCSIMAXXFER -The argument is a pointer to a -.Vt uscsi_xfer_t -value. -The maximum transfer size that can be used with the -.Dv USCSICMD -ioctl for the current device will be returned in the -.Vt uscsi_xfer_t . -.Pp -Not all devices which support the -.Dv USCSICMD -ioctl also support the -.Dv USCSIMAXXFER -ioctl. -.El -.Sh ERRORS -.Bl -tag -width EINVAL -.It Er EINVAL -A parameter has an incorrect, or unsupported, value. -.It Er EIO -An error occurred during the execution of the command. -.It Er EPERM -A process without root credentials tried to execute the -.Dv USCSICMD -or -.Dv USCSIMAXXFER -ioctl. -.It Er EFAULT -The -.Vt uscsi_cmd -itself, the -.Fa uscsi_cdb , -the -.Fa uscsi_buf , -the -.Fa uscsi_rqbuf , -or the -.Vt uscsi_xfer_t -point to an invalid address. -.El -.Sh STABILITY -Committed -.Sh SEE ALSO -.Xr ioctl 2 , -.Xr attributes 5 , -.Xr sd 7D , -.Xr st 7D -.Rs -.%T ANSI Small Computer System Interface-2 (SCSI-2) -.Re -.Sh WARNINGS -The -.Nm -command is very powerful, but somewhat dangerous, and so its -use is restricted to processes running as root, regardless of the file -permissions on the device node. -The device driver code expects to own the device state, and -.Nm -commands can change the state of the device and confuse the device driver. -It is best to use -.Nm -commands only with no side effects, and avoid commands such as Mode Select, as -they may cause damage to data stored on the drive or system panics. -Also, as the commands are not checked in any way by the device driver, any block -may be overwritten, and the block numbers are absolute block numbers on the -drive regardless of which slice number is used to send the command. -.Pp -The -.Nm -interface is not recommended for very large data transfers -(typically more than 16MB). -If the requested transfer size exceeds the maximum transfer size of the DMA -engine, it will not be broken up into multiple transfers and DMA errors may -result. -The -.Dv USCSIMAXXFER -ioctl can be used to determine the maximum transfer size. -.Pp -The -.Dv USCSICMD -ioctl associates a -.Vt struct uscsi_cmd -with a device by using an open file descriptor to the device. -Other APIs might provide the same -.Vt struct uscsi_cmd -programming interface, but perform device association in some other manner. |