unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



 scsi_pt(7)							  scsi_pt(7)
			       Series 800 Only



 NAME
      scsi_pt - SCSI pass-through device driver for Series 800 NIO based
      systems

 DESCRIPTION
      SCSI devices are normally controlled by a device-type-specific driver
      when the appropriate device-type-specific driver exists.	Device-
      type-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 SCSI pass-through
      driver (also called spt) enables use of SCSI devices and commands that
      are not supported by these device-type-specific drivers.

      A successful scsi_pt open() call requires no device I/O operations.
      Once open, ioctl() calls can be used to change SCSI communication
      parameters, attempt SCSI commands, or other SCSI operations.  Since
      the SCSI pass-through driver does not attempt to logically understand
      the target device, read() and write() calls are not supported.
      Super-user privileges or device write permissions are required to use
      these ioctls.  All reserved fields in the data structures associated
      with these ioctls must be zero-filled.

      Since the SCSI pass-through driver is a separate device driver, the
      default device-type-specific driver cannot be used for the same device
      at the same time as the pass-through driver.

    SCSI Commands and Operations
      Only two ioctl commands are supported by the NIO SCSI pass through
      driver; the SIOC_EXCLUSIVE command and the SIOC_IO command.

      The SIOC_EXCLUSIVE ioctl provides a mechanism to prevent other opens
      of a device.  This allows exclusive access by the locking application.
      There are two different levels of locks supported; SCSI target level
      and SCSI lun level.  These levels are specified via the data field of
      the ioctl() call:

	   0	release exclusive access to SCSI lun
	   1	gain exclusive access to SCSI lun
	   2	release exclusive access to SCSI target
	   3	gain exclusive access to SCSI target

      For example, to lock the device (SCSI target):

	   three = 3;
	   if (err = ioctl(fd, SIOC_EXCLUSIVE, &three)) {
	      /* Could not lock the device -- check err */
	   }

      NOTE:  The corresponding unlock must be made for the acquired lock.
      An unlock of the SCSI target (data == 2) will NOT unlock all of the
      individual SCSI luns (data == 0).



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






 scsi_pt(7)							  scsi_pt(7)
			       Series 800 Only



      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.  See EXAMPLE mentioned below.

      The header file <sys/scsi.h> has useful information for SCSI device
      control.	The following is an excerpt from it:

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

	   /* 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	   reserved[16];
	   };

      The flags field can have the following values (if supported):

	   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.

	   SCTL_INIT_SDTR		 synchronous data transfer request
					 negotiations should be attempted
					 with this command.

	   SCTL_INIT_WDTR		 wide data transfer request
					 negotiations should be attempted
					 with this command.

	   SCTL_NO_ATN			 device should be selected without
					 attention (ATN).  This implies that
					 no SCSI message phase should be
					 attempted with this command. (Not
					 supported)





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






 scsi_pt(7)							  scsi_pt(7)
			       Series 800 Only



	   SCTL_2BYTE			 device maintains 2-byte alignment.
					 (Not supported)

	   SCTL_4BYTE			 device maintains 4-byte alignment.
					 (Not supported)

      The cdb_length field specifies the number of valid command bytes in
      the cdb field.

      The cdb field specifies the SCSI command bytes.  These command bytes
      are sent to the target device during the SCSI command phase.

      The data field specifies the address of the data area for the data
      phase of the SCSI command.

      The data_length field specifies the maximum number of data bytes to be
      transferred.  A zero value in the data_length field 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 field data length values.  Unexpected
      system behavior occurs if these fields are not consistent.  The
      data_length value may not be larger than 1 Megabyte.

      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 attempts recovery
      procedures to regain the device's attention.  These recovery
      procedures may include 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.  Note
      that very large (or infinite) timeout values can cause the SCSI bus
      (potentially the entire system) to ``hang''.

      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, S_CHECK_CONDITION or, S_CONDITION_MET.

      The cdb_status field indicates the results of the cdb command.  When
      the SIOC_IO ioctl call returns, all command processing has been
      completed.  Most SIOC_IO ioctl calls will return zero (success).	It
      is important, however, to always check the return value from the ioctl
      to ensure that an unexpected error has not occurred.  The resulting
      detailed ioctl data should be used to evaluate ``success'' or
      ``failure'' from the caller's perspective.  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:




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






 scsi_pt(7)							  scsi_pt(7)
			       Series 800 Only



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

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

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

      SCTL_POWERFAIL		    A system power recovery occurred.  Error
				    handling and retrying the command may be
				    necessary. The pass-through driver does
				    not perform any powerfail recovery.

      S_GOOD			    Device successfully completed the
				    command.

      S_CHECK_CONDITION		    Device indicated sense data was
				    available.

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

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

      S_RESV_CONFLICT		    Device indicated the command conflicted
				    with an existing reservation.

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

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

      S_INTERMEDIATE		    Device successfully completed this
				    command, which was one in a series of
				    linked commands. (Not supported)

      S_I_CONDITION_MET		    Both S_INTERMEDIATE and S_CONDITION_MET
				    indicated by the device.  (Not
				    supported)





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






 scsi_pt(7)							  scsi_pt(7)
			       Series 800 Only



      The sense field indicates the sense data of the SCSI REQUEST SENSE
      command.	It is only valid if the sense_status field indicates
      successful status.

      The sense_status field indicates the results of the SCSI REQUEST SENSE
      command used to collect the associated sense data.  It is only valid
      if the cdb_status field indicates a S_CHECK_CONDITION status.

      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.

 EXAMPLE
      The configuration test program provided with the SCSI pass-through
      driver product can be used as an example.	 It sends a SCSI INQUIRY
      command to the device referenced by the required special device file
      and prints out the returned inquiry data.	 The source for this program
      can be found in the file: /usr/contrib/src/scsi_io.c.

 WARNINGS
      +	   Incorrect use of SCSI device-control operations can easily cause
	   data loss, resulting in a corrupted system.

      +	   Only two ioctl commands are supported; the SIOC_EXCLUSIVE command
	   and the SIOC_IO command.  Any other commands attempted will
	   return the EINVAL error.

      +	   It is recommended that the SIOC_EXCLUSIVE ioctl be used to gain
	   exclusive access to a device prior to attempting SIOC_IO
	   commands.  This will protect against other device opens from
	   external sources (for example, from another user program).  If
	   exclusive access is not obtained, SIOC_IO commands may be
	   intermixed between a number of different applications which can
	   lead to undesirable results.

      +	   Most SCSI commands have a logical unit number (LUN) field.  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.

      +	   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 timeout values can cause the SCSI bus and potentially
	   the entire system to appear to be ``hung''.





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






 scsi_pt(7)							  scsi_pt(7)
			       Series 800 Only



      +	   Unlike on the S700, the NIO SCSI pass-through driver is
	   implemented as a stand-alone driver.	 To ensure system integrity,
	   certain restrictions exist with its use of the bus and its
	   interactions with other drivers.

	   Any device accessed via the NIO SCSI pass-through driver must be
	   on a STAND-ALONE APPLICATION BUS.  Therefore, no boot, dump, or
	   swap devices can be connected to this bus.  While a NIO SCSI
	   pass-through driver application is running, it should have
	   exclusive use of the application bus.  There should be no other
	   accesses to this bus, be it from the operating system, a user, or
	   another application.

	   The controlling application can access its device(s) via the NIO
	   SCSI pass-through driver and other HP standard driver(s) as long
	   as the application handles the coordination between the various
	   drivers.  Thus, the application is responsible for initiating all
	   communications to device(s) on this bus.  For example, a tar
	   command can not be directly used to a device on the exclusive
	   application bus while the owning application is running.  Any
	   problems encountered must be displayed on this supported
	   configuration (a stand-alone application bus) before support can
	   be extended.

 INSTALLATION AND CONFIGURATION
      The SCSI pass-through file set comes with the core system and will
      exist after an install or an update.  The files in this set (and their
      proper destinations) are:

	    Filename	   Protections	    Full path
	    ========	   ===========	    =========
	    libspt.a	   -r--r--r--	    /usr/conf/lib/libspt.a
	    scsi_io.c	   -r--r--r--	    /usr/contrib/src/scsi_io.c
	    scsi_pt.7	   -r--r--r--	    /usr/share/man/man7.Z/scsi_pt.7
	    spt		   -r--r--r--	    /usr/conf/master.d/spt

      The following configuration steps need to be completed to successfully
      use the NIO SCSI pass-through driver.  This driver does not auto-
      configure.

      Go to the build area:

	   $ cd /stand/build

      Create a system file from your existing kernel:

	   $ /usr/lbin/sysadm/system_prep -s system

      Get information about peripherals attached to your system:





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






 scsi_pt(7)							  scsi_pt(7)
			       Series 800 Only



	   $ ioscan -f

      Check if the SCSI pass-through driver is already configured into your
      current kernel:

	   $ grep spt system

      If no ``spt'' line was printed, add a line to the ``SCSI drivers''
      area of the system file:

	   spt

      A driver statement is needed to override the standard driver which
      gets autoconfigured for any device.  One statement is required for
      each desired NIO SCSI pass-through device (be it a SCSI target, or a
      SCSI lun).  Append the driver line(s) to the system file:

	   $ cat >&gt&gt&gt;>&gt&gt&gt; system
	   driver <path> spt
		...
	   ^D	  # control-D to exit the cat command

      where <path> is the complete hardware path of desired device (from
      ioscan cmd)

      Create the conf.c and config.mk files:

	   $ /usr/sbin/config -s system

      Build a new kernel:

	   $ make -f config.mk

      Verify that the pass-through driver has been built into the new
      kernel.  (A line giving the revision information should be printed):

	   $ what ./vmunix_test | grep scsi_pt

      Save the old system file:

	   $ mv /stand/system /stand/system.prev

      Move the new system file to be the current one:

	   $ mv ./system /stand/system









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






 scsi_pt(7)							  scsi_pt(7)
			       Series 800 Only



      Save the old kernel:

	   $ mv /stand/vmunix /stand/vmunix.prev

      Move the new kernel to be the current one:

	   $ mv ./vmunix_test /stand/vmunix

      Boot the system from the new kernel:

	   $ exec reboot

    ONCE THE SYSTEM REBOOTS:
      Verify the peripheral configuration:

	   $ ioscan -f

      Determine the major number for the SCSI pass-through driver:

	   $ lsdev -d spt

      Create the special device file to access the scsi_pt peripheral (refer
      to the example in the TROUBLESHOOTING section):

	   $ mknod /dev/<devfilename> c	 <major #>  <minor #>

      where

	   <devfilename>  name of the special device file

	   <major #>	  character major number (from lsdev cmd)

	   <minor #>	  minor number in the format 0xIITL00

			  where

			       II   2 digit card instance number (from
				    ioscan command; proper ext_bus entry)

			       T    Target ID number (SCSI ID)

			       L    Lun number (SCSI LUN)

			       00   Reserved fields, must be zero

      All ready for use,try the sample program:

      Compile the sample program:

	   $ cc /usr/contrib/src/scsi_io.c




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






 scsi_pt(7)							  scsi_pt(7)
			       Series 800 Only



      Execute the sample program:

	   $ ./a.out /dev/<devfilename>

      The sample program should have returned the inquiry data of the target
      device.  If this did not happen, refer to the TROUBLESHOOTING section.

 TROUBLESHOOTING
      If the NIO SCSI pass-through driver is not working:

      +	   Verify the proper configuration of the SCSI pass-through driver
	   into the kernel.

      +	   Verify that the hardware is set up properly.

	   -	Check that the device is connected, and that its SCSI Bus
		address is set properly.

	   -	Check the reference manual for the device to verify that it
		is configured properly.

	   -	Check that the SCSI Bus is properly terminated.

	   -	Verify that the device is operational using some other
		driver if possible.  If a hardware problem is suspected, the
		SCSI pass-through driver must be unconfigured for that
		device and the HP specific device driver must be configured
		before any diagnostic software can be run.

      +	   Verify the special device file.

	   -	Execute lsdev -d spt to find the major number for the SCSI
		pass-through driver.  For example, lsdev -d spt might show:

			Character     Block	  Driver	  Class
			  136	       -1	  spt		  spt

	   -	Run ioscan -kf to find the card instance number, target SCSI
		ID and SCSI LUN for the desired device.	 For example ioscan
		-kf might show:

	   Class    I  H/W Path	 Driver	 S/W State H/W Type  Description
	   ==============================================================
	   bc	    0		 root	 CLAIMED   BUS_NEXUS
	   ext_bus  2  8	 scsi1	 CLAIMED   INTERFACE HP 28655A - SC
	   target   0  8.3	 target	 CLAIMED   DEVICE
	   spt	    0  8.3.0	 spt	 CLAIMED   DEVICE    HP	     C1718T
	   target   1  8.4	 target	 CLAIMED   DEVICE
	   spt	    1  8.4.0	 spt	 CLAIMED   DEVICE    HP	     C1716T
	   ...




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






 scsi_pt(7)							  scsi_pt(7)
			       Series 800 Only



		In this example there are two desired devices:

		Device #1			   Device #2
		=========			   =========
		card instance number = 2	   card instance number = 2
		target SCSI ID = 3		   target SCSI ID = 4
		SCSI LUN = 0			   SCSI LUN = 0

	   -	Verify that these are the same values used in the special
		device files. For example, ll /dev/c2t*d0 might show:

		crw-rw-rw-   1 root   sys  136 0x023000 Dec 14 15:10 c2t3d0
		crw-rw-rw-   1 root   sys  136 0x024000 Dec 14 15:10 c2t4d0

 SEE ALSO
      scsi(7), mknod(1M), reboot(2).






































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