Print this page
10564 Convert uscsi(7I) to mandoc

Split Close
Expand all
Collapse all
          --- old/usr/src/man/man7i/uscsi.7i
          +++ new/usr/src/man/man7i/uscsi.7i
   1      -'\" te
   2    1  .\" 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
        2 +.\" Copyright 2017 Joyent, Inc.
        3 +.\" The contents of this file are subject to the terms of the
        4 +.\" Common Development and Distribution License (the "License").
        5 +.\" You may not use this file except in compliance with the License.
        6 +.\"
        7 +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
        8 +.\" or http://www.opensolaris.org/os/licensing.
        9 +.\" See the License for the specific language governing permissions
       10 +.\" and limitations under the License.
       11 +.\"
       12 +.\" When distributing Covered Code, include this CDDL HEADER in each
       13 +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
       14 +.\" If applicable, add the following below this CDDL HEADER, with the
       15 +.\" fields enclosed by brackets "[]" replaced with your own identifying
       16 +.\" information: Portions Copyright [yyyy] [name of copyright owner]
       17 +.Dd October 23, 2017
       18 +.Dt USCSI 7I
       19 +.Os
       20 +.Sh NAME
       21 +.Nm uscsi
       22 +.Nd user SCSI command interface
       23 +.Sh SYNOPSIS
       24 +.In sys/scsi/impl/uscsi.h
       25 +.Fo ioctl
       26 +.Fa "int filedes"
       27 +.Fa "int request"
       28 +.Fa "struct uscsi_cmd *cmd"
       29 +.Fc
       30 +.Sh DESCRIPTION
       31 +The
       32 +.Nm
       33 +command is very powerful and somewhat dangerous; therefore it
       34 +has some permission restrictions.
       35 +See
       36 +.Sx WARNINGS
       37 +for more details.
       38 +.Pp
       39 +Drivers supporting this
       40 +.Xr ioctl 2
       41 +provide a general interface allowing user-level applications to cause individual
       42 +.Sy SCSI
       43 +commands to be directed to a particular
       44 +.Sy SCSI
       45 +or
       46 +.Sy ATAPI
       47 +device under control of that driver.
       48 +The
       49 +.Nm
       50 +command is supported by the
       51 +.Xr sd 7D
       52 +driver for
       53 +.Sy SCSI
       54 +disks and
       55 +.Sy ATAPI
       56 +CD-ROM drives, and by the
       57 +.Xr st 7D
       58 +driver for
       59 +.Sy SCSI
       60 +tape drives.
       61 +.Nm
       62 +may also be supported by other device drivers; see the
  30   63  specific device driver manual page for complete information.
  31      -.sp
  32      -.LP
       64 +.Pp
  33   65  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
       66 +.Nm
       67 +ioctl command.
       68 +The
       69 +.Sy SCSI
       70 +command may include a data transfer
       71 +to or from that device, if appropriate for that command.
       72 +Upon completion of the command, the user application can determine how many
       73 +bytes were transferred and the status returned by the device.
       74 +Also, optionally, if the command returns a
  38   75  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 */
       76 +command and return the sense data along with the original status.
       77 +See the
       78 +.Sy USCSI_RQENABLE
       79 +flag below for this Request Sense processing.
       80 +The
       81 +.Vt uscsi_cmd
       82 +structure is defined in
       83 +.In sys/scsi/impl/uscsi.h
       84 +and includes the following members:
       85 +.Bd -literal -offset 2n
       86 +int uscsi_flags;              /* read, write, etc. see below */
  47   87  short uscsi_status;           /* resulting status */
  48   88  short uscsi_timeout;          /* Command Timeout */
  49   89  caddr_t uscsi_cdb             /* CDB to send to target */
  50   90  caddr_t uscsi_bufaddr;        /* i/o source/destination */
  51   91  size_t uscsi_buflen;          /* size of i/o to take place*/
  52   92  size_t uscsi_resid;           /* resid from i/o operation */
  53   93  uchar_t uscsi_cdblen;         /* # of valid CDB bytes */
  54   94  uchar_t uscsi_rqlen;          /* size of uscsi_rqbuf */
  55   95  uchar_t uscsi_rqstatus;       /* status of request sense cmd */
  56   96  uchar_t uscsi_rqresid;        /* resid of request sense cmd */
  57   97  caddr_t uscsi_rqbuf;          /* request sense buffer */
  58   98  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
       99 +.Ed
      100 +.Pp
      101 +The fields of the
      102 +.Vt uscsi_cmd
      103 +structure have the following meanings:
      104 +.Bl -tag -width uscsi_reserved_5
      105 +.It Sy uscsi_flags
      106 +The
      107 +.Sy I/O
      108 +direction and other details of how to carry out the
      109 +.Sy SCSI
      110 +command.
      111 +Possible values are described below.
      112 +.It Fa uscsi_status
      113 +The
      114 +.Sy SCSI
      115 +status byte returned by the device is returned in this field.
      116 +.It Fa uscsi_timeout
  90  117  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
      118 +.It Fa uscsi_cdb
      119 +A pointer to the
      120 +.Sy SCSI
      121 +CDB (command descriptor block) to be transferred to the device in command phase.
      122 +.It Fa uscsi_bufaddr
 109  123  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
      124 +.It Sy uscsi_buflen
      125 +The length of
      126 +.Fa uscsi_bufaddr .
      127 +.It Fa uscsi_resid
 127  128  If a data transfer terminates without transferring the entire requested amount,
 128  129  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
      130 +.It Fa uscsi_cdblen
      131 +The length of the
      132 +.Sy SCSI
      133 +CDB to be transferred to the device in command phase.
      134 +.It Fa uscsi_rqlen
      135 +The length of
      136 +.Fa uscsi_rqbuf ,
      137 +the application's Request Sense buffer.
      138 +.It Fa uscsi_rqstatus
      139 +The
      140 +.Sy SCSI
      141 +status byte returned for the Request Sense command executed
 157  142  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
      143 +.It Fa uscsi_rqresid
 166  144  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
      145 +(the number of bytes, less than or equal to
      146 +.Fa uscsi_rqlen ,
      147 +which were not filled with sense data).
      148 +.It Fa uscsi_rqbuf
 177  149  Points to a buffer in application address space to which the results of an
 178  150  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
      151 +.It Fa uscsi_reserved_5
 187  152  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
      153 +.El
      154 +.Pp
      155 +The
      156 +.Fa uscsi_flags
      157 +field defines the following:
      158 +.Bd -literal -offset 2n
 196  159  USCSI_WRITE                   /* send data to device */
 197  160  USCSI_SILENT                  /* no error messages */
 198  161  USCSI_DIAGNOSE                /* fail if any error occurs */
 199  162  USCSI_ISOLATE                 /* isolate from normal commands */
 200  163  USCSI_READ                    /* get data from device */
 201  164  USCSI_ASYNC                   /* set bus to asynchronous mode */
 202  165  USCSI_SYNC                    /* return bus to sync mode if possible */
 203  166  USCSI_RESET                   /* reset target */
 204  167  USCSI_RESET_TARGET            /* reset target */
 205  168  USCSI_RESET_LUN               /* reset logical unit */
 206  169  USCSI_RESET_ALL               /* reset all targets */
 207  170  USCSI_RQENABLE                /* enable request sense extensions */
 208  171  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
      172 +.Ed
      173 +.Pp
      174 +The
      175 +.Fa uscsi_flags
      176 +bits have the following interpretation:
      177 +.Bl -tag -width USCSI_RESET_TARGET
      178 +.It Dv USCSI_WRITE
 221  179  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
      180 +.It Dv USCSI_SILENT
 230  181  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
      182 +failures associated with this
      183 +.Sy SCSI
      184 +command.
      185 +.It Dv USCSI_DIAGNOSE
 240  186  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
      187 +.Sy SCSI
      188 +command terminates abnormally in any way.
      189 +.It Dv USCSI_ISOLATE
      190 +This
      191 +.Sy SCSI
      192 +command should not be executed with other commands.
      193 +.It Dv USCSI_READ
 259  194  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
      195 +.It Dv USCSI_ASYNC
      196 +Set the
      197 +.Sy SCSI
      198 +bus to asynchronous mode before running this command.
      199 +.It Dv USCSI_SYNC
      200 +Set the
      201 +.Sy SCSI
      202 +bus to synchronous mode before running this command.
      203 +.It Dv USCSI_RESET
      204 +Send a
      205 +.Sy SCSI
      206 +bus device reset message to this target.
      207 +.It Dv USCSI_RESET_TARGET
      208 +Same as USCSI_RESET.
      209 +Use this flag to request TARGET RESET.
      210 +.Po
      211 +.Dv USCSI_RESET
      212 +is maintained only for compatibility with old applications
      213 +.Pc .
      214 +.It Dv USCSI_RESET_LUN
      215 +Send a
      216 +.Sy SCSI
      217 +logical unit reset message to this target.
      218 +.It Dv USCSI_RESET_ALL
      219 +.Dv USCSI_RESET_ALL ,
      220 +.Dv USCSI_RESET/USCSI_RESET_TARGET ,
      221 +and
      222 +.Dv USCSI_RESET_LUN
      223 +are
 315  224  mutually exclusive options and issuing them in any simultaneous combination
 316  225  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
      226 +When a USCSI reset request is combined with other
      227 +.Sy SCSI
      228 +commands, the following semantics take effect:
      229 +If the
      230 +.Dv USCSI RESET
      231 +flag is specified, the other fields (other than
      232 +.Fa uscsi_flags )
      233 +in the
      234 +.Vt uscsi_cmd
      235 +are ignored.
      236 +The
      237 +.Fa uscsi_cdblen
      238 +field
      239 +.Em must
      240 +be set to zero.
      241 +.It Dv USCSI_RQENABLE
      242 +Enable Request Sense extensions.
      243 +If the user application is prepared to receive
      244 +sense data, this bit must be set, the fields
      245 +.Fa uscsi_rqbuf
      246 +and
      247 +.Fa uscsi_rqbuflen
      248 +must be non-zero, and the
      249 +.Fa uscsi_rqbuf
      250 +must point to memory writable by the application.
      251 +.It Dv USCSI_RENEGOT
 343  252  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
      253 +transmitted SCSI command is executed.
      254 +This flag in effects tells the target driver to pass the
      255 +.Dv FLAG_RENEGOTIATE_WIDE_SYNC
      256 +flag in the SCSI packet
 346  257  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
      258 +See the
      259 +.Xr scsi_pkt 9S
      260 +flag
      261 +.Dv FLAG_RENEGOTIATE_WIDE_SYNC
      262 +for more information.
      263 +.El
      264 +.Pp
      265 +The
      266 +.Vt uscsi_xfer_t
      267 +is a type definition that corresponds to a 64-bit unsigned integer.
      268 +It should be used for the
      269 +.Dv USCSIMAXXFER
      270 +ioctls.
      271 +This is
 354  272  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,
      273 +.Dv USCSICMD
      274 +ioctl.
      275 +If the SCSI request is larger than the specified size,
 356  276  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
      277 +.Sh IOCTLS
      278 +The
      279 +.Fn ioctl
      280 +supported by drivers providing the
      281 +.Nm
      282 +interface is:
      283 +.Bl -tag -width USCSIMAXXFER
      284 +.It Dv USCSICMD
      285 +The argument is a pointer to a
      286 +.Vt uscsi_cmd
      287 +structure.
      288 +The
      289 +.Sy SCSI
      290 +device addressed by that driver is selected, and given the
      291 +.Sy SCSI
      292 +command addressed by
      293 +.Fa uscsi_cdb .
      294 +If this command requires a data phase, the
      295 +.Fa uscsi_buflen
      296 +and
      297 +.Fa uscsi_bufaddr
      298 +fields must be set appropriately; if data phase occurs, the
      299 +.Fa uscsi_resid
      300 +is returned as the number of bytes not transferred.
      301 +The status of the command, as returned by the device, is returned in the
      302 +.Fa uscsi_status
      303 +field.
      304 +If the command terminates with Check Condition
 374  305  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
      306 +.Fa uscsi_rqbuf .
      307 +The
      308 +.Fa uscsi_rqresid
      309 +provides the residue of the Request Sense data transfer.
      310 +.It Dv USCSIMAXXFER
      311 +The argument is a pointer to a
      312 +.Vt uscsi_xfer_t
      313 +value.
      314 +The maximum transfer size that can be used with the
      315 +.Dv USCSICMD
      316 +ioctl for the current device will be returned in the
      317 +.Vt uscsi_xfer_t .
      318 +.Pp
      319 +Not all devices which support the
      320 +.Dv USCSICMD
      321 +ioctl also support the
      322 +.Dv USCSIMAXXFER
      323 +ioctl.
      324 +.El
      325 +.Sh ERRORS
      326 +.Bl -tag -width EINVAL
      327 +.It Er EINVAL
 400  328  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
      329 +.It Er EIO
 409  330  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
      331 +.It Er EPERM
      332 +A process without root credentials tried to execute the
      333 +.Dv USCSICMD
      334 +or
      335 +.Dv USCSIMAXXFER
      336 +ioctl.
      337 +.It Er EFAULT
      338 +The
      339 +.Vt uscsi_cmd
      340 +itself, the
      341 +.Fa uscsi_cdb ,
      342 +the
      343 +.Fa uscsi_buf ,
      344 +the
      345 +.Fa uscsi_rqbuf ,
      346 +or the
      347 +.Vt uscsi_xfer_t
      348 +point to an invalid address.
      349 +.El
      350 +.Sh STABILITY
      351 +Committed
      352 +.Sh SEE ALSO
      353 +.Xr ioctl 2 ,
      354 +.Xr attributes 5 ,
      355 +.Xr sd 7D ,
      356 +.Xr st 7D
      357 +.Rs
      358 +.%T ANSI Small Computer System Interface-2 (SCSI-2)
      359 +.Re
      360 +.Sh WARNINGS
      361 +The
      362 +.Nm
      363 +command is very powerful, but somewhat dangerous, and so its
 456  364  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.
      365 +permissions on the device node.
      366 +The device driver code expects to own the device state, and
      367 +.Nm
      368 +commands can change the state of the device and confuse the device driver.
      369 +It is best to use
      370 +.Nm
      371 +commands only with no side effects, and avoid commands such as Mode Select, as
      372 +they may cause damage to data stored on the drive or system panics.
      373 +Also, as the commands are not checked in any way by the device driver, any block
      374 +may be overwritten, and the block numbers are absolute block numbers on the
      375 +drive regardless of which slice number is used to send the command.
      376 +.Pp
      377 +The
      378 +.Nm
      379 +interface is not recommended for very large data transfers
      380 +(typically more than 16MB).
      381 +If the requested transfer size exceeds the maximum transfer size of the DMA
      382 +engine, it will not be broken up into multiple transfers and DMA errors may
      383 +result.
      384 +The
      385 +.Dv USCSIMAXXFER
      386 +ioctl can be used to determine the maximum transfer size.
      387 +.Pp
      388 +The
      389 +.Dv USCSICMD
      390 +ioctl associates a
      391 +.Vt struct uscsi_cmd
      392 +with a device by using an open file descriptor to the device.
      393 +Other APIs might provide the same
      394 +.Vt struct uscsi_cmd
      395 +programming interface, but perform device association in some other manner.
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX