unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 sioc_io(7)							  sioc_io(7)




 NAME
      sioc_io - SCSI pass-through interface

 DESCRIPTION
      SCSI devices are controlled by a device-specific driver, when one
      exists.  Device-specific drivers, such as those for SCSI direct access
      (disk) and sequential access (tape) devices, coordinate device and
      driver states to accomplish correct logical device behavior.  The
      sioc_io pass-through interface enables the use of SCSI devices and
      commands not normally supported by these device-specific drivers.

      Superuser privileges or device write permissions are required to use
      the SIOC_IO ioctl. All reserved fields in the sioc_io data structure
      must be zero-filled.

      The SIOC_IO ioctl allows an arbitrary SCSI command to be sent to a
      device.  All details of the SCSI command protocol are handled
      automatically.

      The data structure for the SIOC_IO ioctl is included from
      <sys/scsi.h>:

	   /* SCSI device control ioctls */
	   #define SIOC_IO	       _IOWR('S', 22, struct sctl_io)

	   /* Structure for SIOC_IO ioctl */
	   struct sctl_io
	   {
		   unsigned	   flags;
		   unsigned char   cdb_length;
		   unsigned char   cdb[16];
		   void		   *data;
		   unsigned	   data_length;
		   unsigned	   max_msecs;
		   unsigned	   data_xfer;
		   unsigned	   cdb_status;
		   unsigned char   sense[256];
		   unsigned	   sense_status;
		   unsigned char   sense_xfer;
		   unsigned char   reserved[64];
	   };

      The following flags can be used to specify the flags field value:

	   SCTL_READ	       Data-in phase expected if the data_length
			       field is non-zero.  The absence of this flag
			       implies that a data-out phase is expected if
			       the data_length field is non-zero.

      The cdb field specifies the SCSI command bytes.  The number of command
      bytes is specified by the cdb_length field.  These command bytes are



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 sioc_io(7)							  sioc_io(7)




      sent to the target device during the SCSI command phase.

      The address of the data area for the data phase of the SCSI command is
      specified by the data field.  The data_length field specifies the
      maximum number of data bytes to be transferred.  A zero-valued
      data_length indicates that no data phase should occur.  Most SCSI
      commands with a data phase expect the data length information to be
      included somewhere in the command bytes.	The caller is responsible
      for correctly specifying both the data_length field and any cdb data
      length values.  The length may not be larger than SCSI_MAXPHYS and
      some implementations further restrict this length.

      The max_msecs field specifies the maximum time, in milliseconds, that
      the device should need to complete the command.  If this period of
      time expires without command completion, the system might attempt
      recovery procedures to regain the device's attention.  These recovery
      procedures might include abort tag, abort, and device and bus reset
      operations.  A zero value in the max_msec field indicates that the
      timeout period is infinite and the system should wait indefinitely for
      command completion.

      When the SIOC_IO ioctl call returns, all command processing has been
      completed.  Most SIOC_IO ioctl calls will return zero (success).	The
      resulting detailed ioctl data should be used to evaluate ``success''
      or ``failure'' from the caller's perspective.  The cdb_status field
      indicates the results of the cdb command.	 If the cdb_status field
      indicates a S_CHECK_CONDITION status, the sense_status field indicates
      the results of the SCSI REQUEST SENSE command used to collect the
      associated sense data.  These status fields will contain one of the
      following values:

      SCTL_INVALID_REQUEST	    The SCSI command request is invalid and
				    thus not attempted.

      SCTL_SELECT_TIMEOUT	    The target device does not answer to
				    selection by the host SCSI interface
				    (the device does not exist or does not
				    respond).

      SCTL_INCOMPLETE		    The device answered selection but the
				    command is not completed (the device
				    took too long or a communication failure
				    occurred).

      S_GOOD			    Device successfully completed the
				    command.

      S_CHECK_CONDITION		    Device indicated sense data is
				    available.





 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 sioc_io(7)							  sioc_io(7)




      S_CONDITION_MET		    Device successfully completed the
				    command and the requested (search or
				    pre-fetch) operation is satisfied.

      S_BUSY			    Device indicated it is unable to accept
				    the command because it is busy doing
				    other operations.

      S_INTERMEDIATE		    Device successfully completed this
				    command, which is one in a series of
				    linked commands (not supported, see
				    WARNINGS).

      S_I_CONDITION_MET		    Device indicated both S_INTERMEDIATE and
				    S_CONDITION_MET (not supported, see
				    WARNINGS).

      S_RESV_CONFLICT		    Device indicated the command conflicted
				    with an existing reservation.

      S_COMMAND_TERMINATED	    Device indicated the command is
				    terminated early by the host system.

      S_QUEUE_FULL		    Device indicated it is unable to accept
				    the command because its command queue is
				    currently full.

      The data_xfer field indicates the number of data bytes actually
      transferred during the data phase of the cdb command.  This field is
      valid only when the cdb_status field contains one of the following
      values: S_GOOD or S_CHECK_CONDITION.  The sense_xfer field indicates
      the number of valid sense data bytes.  This field is valid only when
      the cdb_status field contains the value S_CHECK_CONDITION and the
      sense_status field contains the value S_GOOD.

 EXAMPLES
      Assume that fildes is a valid file descriptor for a SCSI device.	The
      first example attempts a SCSI INQUIRY command:

	   #include <sys/scsi.h>

	   struct sctl_io sctl_io;
	   #define MAX_LEN 255
	   unsigned char inquiry_data[MAX_LEN];

	   memset(sctl_io, 0, sizeof(sctl_io)); /* clear reserved fields */
	   sctl_io.flags = SCTL_READ;		/* input data expected */
	   sctl_io.cdb[0] = 0x12;		/* can use scsi.h CMDinquiry */
	   sctl_io.cdb[1] = 0x00;
	   sctl_io.cdb[2] = 0x00;
	   sctl_io.cdb[3] = 0x00;



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 sioc_io(7)							  sioc_io(7)




	   sctl_io.cdb[4] = MAX_LEN;		/* allocation length */
	   sctl_io.cdb[5] = 0x00;
	   sctl_io.cdb_length = 6;		/* 6 byte command */
	   sctl_io.data = &inquiry_data[0];	/* data buffer location */
	   sctl_io.data_length = MAX_LEN;	/* maximum transfer length */
	   sctl_io.max_msecs = 10000;		/* allow 10 seconds for cmd */
	   if (ioctl(fildes, SIOC_IO, &sctl_io) < 0)
	   {
		   /* request is invalid */
	   }

      The following example attempts a SCSI TEST UNIT READY command and
      checks to see if the device is ready, not ready, or in some other
      state.

	   #include <sys/scsi.h>

	   struct sctl_io sctl_io;

	   memset(sctl_io, 0, sizeof(sctl_io)); /* clear reserved fields */
	   sctl_io.flags = 0;			/* no data transfer expected */
	   sctl_io.cdb[0] = 0x00;		/* can use CMDtest_unit_ready */
	   sctl_io.cdb[1] = 0x00;
	   sctl_io.cdb[2] = 0x00;
	   sctl_io.cdb[3] = 0x00;
	   sctl_io.cdb[4] = 0x00;
	   sctl_io.cdb[5] = 0x00;
	   sctl_io.cdb_length = 6;		/* 6 byte command */
	   sctl_io.data = NULL;			/* no data buffer is provided */
	   sctl_io.data_length = 0;		/* do not transfer data */
	   sctl_io.max_msecs = 10000;		/* allow 10 seconds for cmd */
	   if (ioctl(fildes, SIOC_IO, &sctl_io) < 0)
	   {
		   /* request is invalid */
	   }
	   else if (sctl_io.cdb_status == S_GOOD)
	   {
		   /* device is ready */
	   }
	   else if (sctl_io.cdb_status == S_BUSY ||
		    (sctl_io.cdb_status == S_CHECK_CONDITION &&
		     sctl_io.sense_status == S_GOOD &&
		     sctl_io.sense_xfer > 2 &&
		     (sctl_io.sense[2] & 0x0F) == 2))  /* can use sense_data */
	   {
		   /* device is not ready */
	   }
	   else
	   {
		   /* unknown state */
	   }



 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 sioc_io(7)							  sioc_io(7)




 WARNINGS
      Incorrect use of sioc_io operations (even those attempting access to
      non-existent devices) can cause data loss, system panics, and device
      damage.

      The SIOC_EXCLUSIVE ioctl should be used to gain exclusive access to a
      device prior to attempting SIOC_IO commands.  If exclusive access is
      not obtained, SIOC_IO commands will be intermixed with device-specific
      driver commands, which can lead to undesirable results.

      Device-specific drivers can reject inappropriate or troublesome
      SIOC_IO commands.	 However, since not all such operations are known
      and detected, care should be exercised to avoid disrupting device-
      specific drivers when using commands that modify internal device
      states.

      It is very easy to cause system deadlock through incorrect use of the
      SIOC_PRIORITY_MODE ioctl.	 Normally it is necessary to lock the
      calling process into memory (see plock(2)) prior to enabling priority
      mode.

      Most SCSI commands have a logical unit number (LUN) field.  Parallel
      SCSI implementations on the HP-UX operating system select logical
      units via the SCSI IDENTIFY message.  The LUN portion of the cdb
      should normally be set to zero, even when the LUN being accessed is
      not zero.

      Use of linked commands is not supported.

      Most SCSI commands with a data phase expect the data length
      information to be included somewhere in the command bytes.  Both the
      data_length field and any cdb data length values must be correctly
      specified to get correct command results.

      Very large (or infinite) timeout values can cause a parallel SCSI bus
      (potentially the entire system) to hang.

      Device and/or bus reset operations can be used to regain a device's
      attention when a timeout expires.

      Resetting a device can cause I/O errors and/or loss of cached data.
      This can result in loss of data and/or system panics.

      Obtaining SCSI INQUIRY data by use of the SIOC_INQUIRY ioctl instead
      of by use of the SIOC_IO ioctl is generally preferable since SCSI
      implementations on the HP-UX operating system synchronize access of
      inquiry data during driver open calls.

      Since communication parameters can be affected by device-specific
      driver capabilities, device-specific driver use might result in
      communication parameter changes.



 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000






 sioc_io(7)							  sioc_io(7)




 FILES
      /usr/include/sys/scsi.h
      /usr/include/sys/scsi_ctl.h

 SEE ALSO
      ioctl(2), scsi(7), scsi_ctl(7), scsi_pt(7).
















































 Hewlett-Packard Company	    - 6 -   HP-UX Release 11i: November 2000