lib/libcam/cam_cdbparse.3

   1 .\"
   2 .\" Copyright (c) 1998 Kenneth D. Merry.
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. The name of the author may not be used to endorse or promote products
  14 .\"    derived from this software without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD: src/lib/libcam/cam_cdbparse.3,v 1.3.2.11 2002/12/29 16:35:35 schweikh Exp $
  29 .\"
  30 .\" This man page borrows heavily from the old scsi(3) man page, which had
  31 .\" the following copyright:
  32 .\"
  33 .\" Copyright (c) 1994 HD Associates (hd@world.std.com)
  34 .\" All rights reserved.
  35 .\"
  36 .\" Redistribution and use in source and binary forms, with or without
  37 .\" modification, are permitted provided that the following conditions
  38 .\" are met:
  39 .\" 1. Redistributions of source code must retain the above copyright
  40 .\"    notice, this list of conditions and the following disclaimer.
  41 .\" 2. Redistributions in binary form must reproduce the above copyright
  42 .\"    notice, this list of conditions and the following disclaimer in the
  43 .\"    documentation and/or other materials provided with the distribution.
  44 .\" 3. All advertising materials mentioning features or use of this software
  45 .\"    must display the following acknowledgement:
  46 .\"     This product includes software developed by HD Associates
  47 .\" 4. Neither the name of the HD Associates nor the names of its contributors
  48 .\"    may be used to endorse or promote products derived from this software
  49 .\"    without specific prior written permission.
  50 .\"
  51 .\" THIS SOFTWARE IS PROVIDED BY HD ASSOCIATES``AS IS'' AND
  52 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  53 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  54 .\" ARE DISCLAIMED.  IN NO EVENT SHALL HD ASSOCIATES OR CONTRIBUTORS BE LIABLE
  55 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  56 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  57 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  58 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  59 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  60 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  61 .\" SUCH DAMAGE.
  62 .\"
  63 .Dd October 13, 1998
  64 .Dt CAM_CDBPARSE 3
  65 .Os
  66 .Sh NAME
  67 .Nm csio_build ,
  68 .Nm csio_build_visit ,
  69 .Nm csio_decode ,
  70 .Nm csio_decode_visit ,
  71 .Nm buff_decode ,
  72 .Nm buff_decode_visit ,
  73 .Nm csio_encode ,
  74 .Nm csio_encode_visit ,
  75 .Nm buff_encode_visit
  76 .Nd CAM user library SCSI buffer parsing routines
  77 .Sh LIBRARY
  78 .Lb libcam
  79 .Sh SYNOPSIS
  80 .In stdio.h
  81 .In camlib.h
  82 .Ft int
  83 .Fo csio_build
  84 .Fa "struct ccb_scsiio *csio"
  85 .Fa "u_int8_t *data_ptr"
  86 .Fa "u_int32_t dxfer_len"
  87 .Fa "u_int32_t flags"
  88 .Fa "int retry_count"
  89 .Fa "int timeout"
  90 .Fa "const char *cmd_spec"
  91 .Fa "..."
  92 .Fc
  93 .Ft int
  94 .Fo csio_build_visit
  95 .Fa "struct ccb_scsiio *csio"
  96 .Fa "u_int8_t *data_ptr"
  97 .Fa "u_int32_t dxfer_len"
  98 .Fa "u_int32_t flags"
  99 .Fa "int retry_count"
 100 .Fa "int timeout"
 101 .Fa "const char *cmd_spec"
 102 .Fa "int (*arg_get)(void *hook, char *field_name)"
 103 .Fa "void *gethook"
 104 .Fc
 105 .Ft int
 106 .Fo csio_decode
 107 .Fa "struct ccb_scsiio *csio"
 108 .Fa "const char *fmt"
 109 .Fa "..."
 110 .Fc
 111 .Ft int
 112 .Fo csio_decode_visit
 113 .Fa "struct ccb_scsiio *csio"
 114 .Fa "const char *fmt"
 115 .Fa "void (*arg_put)(void *hook"
 116 .Fa "int letter"
 117 .Fa "void *val"
 118 .Fa "int count"
 119 .Fa "char *name)"
 120 .Fa "void *puthook"
 121 .Fc
 122 .Ft int
 123 .Fo buff_decode
 124 .Fa "u_int8_t *buff"
 125 .Fa "size_t len"
 126 .Fa "const char *fmt"
 127 .Fa "..."
 128 .Fc
 129 .Ft int
 130 .Fo buff_decode_visit
 131 .Fa "u_int8_t *buff"
 132 .Fa "size_t len"
 133 .Fa "const char *fmt"
 134 .Fa "void (*arg_put)(void *, int, void *, int, char *)"
 135 .Fa "void *puthook"
 136 .Fc
 137 .Ft int
 138 .Fo csio_encode
 139 .Fa "struct ccb_scsiio *csio"
 140 .Fa "const char *fmt"
 141 .Fa "..."
 142 .Fc
 143 .Ft int
 144 .Fo csio_encode_visit
 145 .Fa "struct ccb_scsiio *csio"
 146 .Fa "const char *fmt"
 147 .Fa "int (*arg_get)(void *hook, char *field_name)"
 148 .Fa "void *gethook"
 149 .Fc
 150 .Ft int
 151 .Fo buff_encode_visit
 152 .Fa "u_int8_t *buff"
 153 .Fa "size_t len"
 154 .Fa "const char *fmt"
 155 .Fa "int (*arg_get)(void *hook, char *field_name)"
 156 .Fa "void *gethook"
 157 .Fc
 158 .Sh DESCRIPTION
 159 The CAM buffer/CDB encoding and decoding routines provide a relatively easy
 160 migration path for userland
 161 .Tn SCSI
 162 applications written with the similarly-named
 163 .Va scsireq_ Ns *
 164 functions from the old
 165 .Fx
 166 .Tn SCSI
 167 layer.
 168 .Pp
 169 These functions may be used in new applications, but users may find it
 170 easier to use the various SCSI CCB building functions included with the
 171 .Xr cam 3
 172 library.  (e.g.\&
 173 .Fn cam_fill_csio ,
 174 .Fn scsi_start_stop ,
 175 and
 176 .Fn scsi_read_write )
 177 .Pp
 178 .Fn csio_build
 179 builds up a
 180 .Va ccb_scsiio
 181 structure based on the information provided in
 182 the variable argument list.
 183 It gracefully handles a NULL
 184 .Fa data_ptr
 185 argument passed to it.
 186 .Pp
 187 .Fa dxfer_len
 188 is the length of the data phase; the data transfer direction is
 189 determined by the
 190 .Fa flags
 191 argument.
 192 .Pp
 193 .Fa data_ptr
 194 is the data buffer used during the
 195 .Tn SCSI
 196 data phase.  If no data is to be
 197 transferred for the
 198 .Tn SCSI
 199 command in question, this should be set to NULL.  If there is data to
 200 transfer for the command, this buffer must be at least
 201 .Fa dxfer_len
 202 long.
 203 .Pp
 204 .Fa flags
 205 are the flags defined in
 206 .In bus/cam/cam_ccb.h :
 207 .Bd -literal
 208 /* Common CCB header */
 209 /* CAM CCB flags */
 210 typedef enum {
 211      CAM_CDB_POINTER       = 0x00000001,/* The CDB field is a pointer    */
 212      CAM_QUEUE_ENABLE      = 0x00000002,/* SIM queue actions are enabled */
 213      CAM_CDB_LINKED        = 0x00000004,/* CCB contains a linked CDB     */
 214      CAM_SCATTER_VALID     = 0x00000010,/* Scatter/gather list is valid  */
 215      CAM_DIS_AUTOSENSE     = 0x00000020,/* Disable autosense feature     */
 216      CAM_DIR_RESV          = 0x00000000,/* Data direction (00:reserved)  */
 217      CAM_DIR_IN            = 0x00000040,/* Data direction (01:DATA IN)   */
 218      CAM_DIR_OUT           = 0x00000080,/* Data direction (10:DATA OUT)  */
 219      CAM_DIR_NONE          = 0x000000C0,/* Data direction (11:no data)   */
 220      CAM_DIR_MASK          = 0x000000C0,/* Data direction Mask           */
 221      CAM_SOFT_RST_OP       = 0x00000100,/* Use Soft reset alternative    */
 222      CAM_ENG_SYNC          = 0x00000200,/* Flush resid bytes on complete */
 223      CAM_DEV_QFRZDIS       = 0x00000400,/* Disable DEV Q freezing        */
 224      CAM_DEV_QFREEZE       = 0x00000800,/* Freeze DEV Q on execution     */
 225      CAM_HIGH_POWER        = 0x00001000,/* Command takes a lot of power  */
 226      CAM_SENSE_PTR         = 0x00002000,/* Sense data is a pointer       */
 227      CAM_SENSE_PHYS        = 0x00004000,/* Sense pointer is physical addr*/
 228      CAM_TAG_ACTION_VALID  = 0x00008000,/* Use the tag action in this ccb*/
 229      CAM_PASS_ERR_RECOVER  = 0x00010000,/* Pass driver does err. recovery*/
 230      CAM_DIS_DISCONNECT    = 0x00020000,/* Disable disconnect            */
 231      CAM_SG_LIST_PHYS      = 0x00040000,/* SG list has physical addrs.   */
 232      CAM_MSG_BUF_PHYS      = 0x00080000,/* Message buffer ptr is physical*/
 233      CAM_SNS_BUF_PHYS      = 0x00100000,/* Autosense data ptr is physical*/
 234      CAM_DATA_PHYS         = 0x00200000,/* SG/Buffer data ptrs are phys. */
 235      CAM_CDB_PHYS          = 0x00400000,/* CDB pointer is physical       */
 236      CAM_ENG_SGLIST        = 0x00800000,/* SG list is for the HBA engine */
 237
 238 /* Phase cognizant mode flags */
 239      CAM_DIS_AUTOSRP       = 0x01000000,/* Disable autosave/restore ptrs */
 240      CAM_DIS_AUTODISC      = 0x02000000,/* Disable auto disconnect       */
 241      CAM_TGT_CCB_AVAIL     = 0x04000000,/* Target CCB available          */
 242      CAM_TGT_PHASE_MODE    = 0x08000000,/* The SIM runs in phase mode    */
 243      CAM_MSGB_VALID        = 0x20000000,/* Message buffer valid          */
 244      CAM_STATUS_VALID      = 0x40000000,/* Status buffer valid           */
 245      CAM_DATAB_VALID       = 0x80000000,/* Data buffer valid             */
 246
 247 /* Host target Mode flags */
 248      CAM_TERM_IO           = 0x20000000,/* Terminate I/O Message sup.    */
 249      CAM_DISCONNECT        = 0x40000000,/* Disconnects are mandatory     */
 250      CAM_SEND_STATUS       = 0x80000000,/* Send status after data phase  */
 251 } ccb_flags;
 252 .Ed
 253 .Pp
 254 Multiple flags should be ORed together.  Any of the CCB flags may be used,
 255 although it is worth noting several important ones here:
 256 .Bl -tag -width CAM_PASS_ERR_RECOVER
 257 .It Dv CAM_DIR_IN
 258 This indicates that the operation in question is a read operation.  i.e.,
 259 data is being read from the
 260 .Tn SCSI
 261 device to the user-supplied buffer.
 262 .It Dv CAM_DIR_OUT
 263 This indicates that the operation is a write operation.  i.e. data is being
 264 written from the user-supplied buffer to the device.
 265 .It Dv CAM_DIR_NONE
 266 This indicates that there is no data to be transferred for this command.
 267 .It Dv CAM_DEV_QFRZDIS
 268 This flag disables device queue freezing as an error recovery mechanism.
 269 .It Dv CAM_PASS_ERR_RECOVER
 270 This flag tells the
 271 .Xr pass 4
 272 driver to enable error recovery.  The default is to not perform error
 273 recovery, which means that the retry count won't be honored without this
 274 flag, among other things.
 275 .It Dv CAM_DATA_PHYS
 276 This indicates that the address contained in
 277 .Fa data_ptr
 278 is a physical address, not a virtual address.
 279 .El
 280 .Pp
 281 The
 282 .Fa retry_count
 283 tells the kernel how many times to retry the command in question.  The
 284 retry count is ignored unless the
 285 .Xr pass 4
 286 driver is told to enable error recovery via the
 287 .Dv CAM_PASS_ERR_RECOVER
 288 flag.
 289 .Pp
 290 The
 291 .Fa timeout
 292 tells the kernel how long to wait for the given command to complete.  If
 293 the timeout expires and the command hasn't completed, the CCB will be
 294 returned from the kernel with an appropriate error status.
 295 .Pp
 296 .Fa cmd_spec
 297 is a CDB format specifier used to build up the SCSI CDB.
 298 This text string is made up of a list of field specifiers.  Field
 299 specifiers specify the value for each CDB field (including indicating
 300 that the value be taken from the next argument in the
 301 variable argument list), the width
 302 of the field in bits or bytes, and an optional name.  White space is
 303 ignored, and the pound sign ('#') introduces a comment that ends at the
 304 end of the current line.
 305 .Pp
 306 The optional name is the first part of a field specifier and
 307 is in curly braces.  The text in curly braces in this example are
 308 the names:
 309 .Dl "{PS} v:b1 {Reserved} 0:b1 {Page Code} v:b6 # Mode select page"
 310 .Pp
 311 This field specifier has two one bit fields and one six bit field.
 312 The second one bit field is the constant value 0 and the first
 313 one bit field and the six bit field are taken from the variable
 314 argument list.
 315 Multi byte fields are swapped into the SCSI byte order in the
 316 CDB and white space is ignored.
 317 .Pp
 318 When the field is a hex value or the letter v, (e.g.,
 319 .Fa "1A"
 320 or
 321 .Fa "v" )
 322 then a single byte value
 323 is copied to the next unused byte of the CDB.
 324 When the letter
 325 .Fa v
 326 is used the next integer argument is taken from the variable argument list
 327 and that value used.
 328 .Pp
 329 A constant hex value followed by a field width specifier or the letter
 330 .Fa v
 331 followed by a field width specifier (e.g.,
 332 .Fa 3:4 ,
 333 .Fa 3:b4 ,
 334 .Fa 3:i3 ,
 335 .Fa v:i3 )
 336 specifies a field of a given bit or byte width.
 337 Either the constant value or (for the V specifier) the next integer value from
 338 the variable argument list is copied to the next unused
 339 bits or bytes of the CDB.
 340 .Pp
 341 A decimal number or the letter
 342 .Fa b
 343 followed by a decimal number field width indicates a bit field of that width.
 344 The bit fields are packed as tightly as possible beginning with the
 345 high bit (so that it reads the same as the SCSI spec), and a new byte of
 346 the CDB is started whenever a byte fills completely or when an
 347 .Fa i
 348 field is encountered.
 349 .Pp
 350 A field width specifier consisting of the letter
 351 .Fa i
 352 followed by either
 353 1, 2, 3 or 4 indicates a 1, 2, 3 or 4 byte integral value that must
 354 be swapped into SCSI byte order (MSB first).
 355 .Pp
 356 For the
 357 .Fa v
 358 field specifier the next integer argument is taken from the variable argument
 359 list and that value is used swapped into SCSI byte order.
 360 .Pp
 361 .Fn csio_build_visit
 362 operates similarly to
 363 .Fn csio_build ,
 364 except that the values to substitute for variable arguments in
 365 .Fa cmd_spec
 366 are retrieved via the
 367 .Fn arg_get
 368 function passed in to
 369 .Fn csio_build_visit
 370 instead of via
 371 .Xr stdarg 3 .
 372 The
 373 .Fn arg_get
 374 function takes two arguments:
 375 .Bl -tag -width field_name
 376 .It Fa gethook
 377 is passed into the
 378 .Fn arg_get
 379 function at each invocation.  This enables the
 380 .Fn arg_get
 381 function to keep some state in between calls without using global or static
 382 variables.
 383 .It Fa field_name
 384 is the field name supplied in
 385 .Fa fmt ,
 386 if any.
 387 .El
 388 .Pp
 389 .Fn csio_decode
 390 is used to decode information from the data in phase of the SCSI
 391 transfer.
 392 .Pp
 393 The decoding is similar to
 394 the command specifier processing of
 395 .Fn csio_build
 396 except that the data is extracted from the data pointed to by
 397 .Fa csio->data_ptr .
 398 The stdarg list should be pointers to integers instead of integer
 399 values.
 400 A seek field type and a suppression modifier are added.
 401 The
 402 .Fa *
 403 suppression modifier (e.g.,
 404 .Fa *i3
 405 or
 406 .Fa *b4 )
 407 suppresses assignment from the field and can be used to skip
 408 over bytes or bits in the data, without having to copy
 409 them to a dummy variable in the arg list.
 410 .Pp
 411 The seek field type
 412 .Fa s
 413 permits you to skip over data.
 414 This seeks to an absolute position
 415 .Pq Fa s3
 416 or a relative position
 417 .Pq Fa s+3
 418 in the data, based on whether or not the presence of the '+' sign.
 419 The seek value can be specified as
 420 .Fa v
 421 and the next integer value from the argument list will be
 422 used as the seek value.
 423 .Pp
 424 .Fn csio_decode_visit
 425 operates like
 426 .Fn csio_decode
 427 except that instead of placing the decoded contents of the buffer in
 428 variadic arguments, the decoded buffer contents are returned to the user
 429 via the
 430 .Fn arg_put
 431 function that is passed in.
 432 The
 433 .Fn arg_put
 434 function takes several arguments:
 435 .Bl -tag -width letter
 436 .It Fa hook
 437 The "hook" is a mechanism to allow the
 438 .Fn arg_put
 439 function to save state in between calls.
 440 .It Fa letter
 441 is the letter describing the format of the argument being passed into the
 442 function.
 443 .It Fa val
 444 is a void pointer to the value being passed into the function.
 445 .It Fa count
 446 is the size of the value being passed into the
 447 .Fn arg_put
 448 function.  The argument format determines the unit of measure.
 449 .It Fa name
 450 This is a text description of the field, if one was provided in the
 451 .Fa fmt .
 452 .El
 453 .Pp
 454 .Fn buff_decode
 455 decodes an arbitrary data buffer using the method
 456 described above for
 457 .Fn csio_decode .
 458 .Pp
 459 .Fn buff_decode_visit
 460 decodes an arbitrary data buffer using the method described above for
 461 .Fn csio_decode_visit .
 462 .Pp
 463 .Fn csio_encode
 464 encodes the
 465 .Fa data_ptr
 466 portion (not the CDB!) of a
 467 .Va ccb_scsiio
 468 structure, using the method described above for
 469 .Fn csio_build .
 470 .Pp
 471 .Fn csio_encode_visit
 472 encodes the
 473 .Fa data_ptr
 474 portion (not the CDB!) of a
 475 .Va ccb_scsiio
 476 structure, using the method described above for
 477 .Fn csio_build_visit .
 478 .Pp
 479 .Fn buff_encode_visit
 480 encodes an arbitrary data pointer, using the method described
 481 above for
 482 .Fn csio_build_visit .
 483 .Sh RETURN VALUES
 484 .Fn csio_build ,
 485 .Fn csio_build_visit ,
 486 .Fn csio_encode ,
 487 .Fn csio_encode_visit ,
 488 and
 489 .Fn buff_encode_visit
 490 return the number of fields processed.
 491 .Pp
 492 .Fn csio_decode ,
 493 .Fn csio_decode_visit ,
 494 .Fn buff_decode ,
 495 and
 496 .Fn buff_decode_visit
 497 return the number of assignments performed.
 498 .Sh SEE ALSO
 499 .Xr cam 3 ,
 500 .Xr pass 4 ,
 501 .Xr camcontrol 8
 502 .Sh HISTORY
 503 The CAM versions of these functions are based upon similar functions
 504 implemented for the old
 505 .Fx
 506 .Tn SCSI
 507 layer.  The encoding/decoding functions in the old
 508 .Tn SCSI
 509 code were written by Peter Dufault.
 510 .Pp
 511 Many systems have comparable interfaces to permit a user to construct a
 512 SCSI command in user space.
 513 .Pp
 514 The old
 515 .Va scsireq
 516 data structure was almost identical to the SGI /dev/scsi data
 517 structure.  If anyone knows the name of the authors it should
 518 go here; Peter Dufault first read about it in a 1989 Sun Expert magazine.
 519 .Pp
 520 The new CCB data structures are derived from the CAM-2 and CAM-3
 521 specifications.
 522 .Pp
 523 .An Peter Dufault
 524 implemented a clone of SGI's interface in
 525 .Bx 386
 526 that
 527 led to the original
 528 .Fx
 529 .Tn SCSI
 530 library and the related kernel ioctl.
 531 If anyone needs that for compatibility contact dufault@hda.com.
 532 .Sh AUTHORS
 533 Kenneth Merry implemented the CAM versions of these encoding and decoding
 534 functions.  This current work is based upon earlier work by Peter Dufault.
 535 .Sh BUGS
 536 There should probably be a function that encodes both the CDB and the data
 537 buffer portions of a
 538 .Tn SCSI
 539 CCB.  I discovered this while implementing the arbitrary command execution
 540 code in
 541 .Xr camcontrol 8 ,
 542 but I haven't yet had time to implement such a function.
 543 .Pp
 544 Some of the CCB flag descriptions really don't belong here.  Rather they
 545 belong in a generic CCB man page.  Since that man page hasn't yet been
 546 written, the shorter descriptions here will have to suffice.