[0m


SD(4)		    UNIX Programmer's Manual		    SD(4)



[1mNAME
     [0msd*, rsd*, rct* - SCSI Device Driver

[1mDESCRIPTION
     [0mThis is a driver for SCSI peripheral devices connected to
     the host computer through a SCSI Expansion Card. The files
     /_d_e_v/_s_d* and /_d_e_v/_r{_s_d,_c_t}* are block and character devices
     respectively to peripherals attached to the [1mSCSI [0mBus: _s_d is
     the name conventionally used for Direct Access class dev-
     ices, (typically winchester discs), and _c_t refers to Sequen-
     tial Access devices (e.g. cartridge tapes).

     Explicit support is provided for _D_i_r_e_c_t and _S_e_q_u_e_n_t_i_a_l
     Access devices which conform to the ANSI standard, although
     facilities exist to handle other SCSI peripherals.

     SCSI Expansion Cards may be fitted in any expansion slot.
     Each Expansion Card may be used to address up to seven SCSI
     Peripherals.  The SCSI Device Driver reserves for itself the
     ID of 7; attached peripherals may take IDs between 0 and 6.

     Individual target devices are addressed through the major
     and minor device numbers according to the following rules:

     SCSI devices are addressed via a contiguous block of 28
     major device numbers. Using the first target as a base

	  logical expansion slot number = (major(dev) - base) / 7
	  target = (major(dev) - base) % 7

     For block devices the base number is 12, while character
     devices have a base of 21.  See the _R_I_S_C _i_X _S_y_s_t_e_m
     _A_d_m_i_n_i_s_t_r_a_t_o_r'_s _G_u_i_d_e for more information about setting up
     SCSI devices.

     The minor device number of a file is arranged as a bitmap.
     This bitmap encodes the _L_o_g_i_c_a_l _U_n_i_t _N_u_m_b_e_r, an _E_s_c_a_p_e flag
     and an _E_x_c_l_u_s_i_v_e _A_c_c_e_s_s flag.


	  LUN = (minor(dev) >> 5) & 7
	  Escape = minor(dev) & 0x08
	  Exclusive = minor(dev) & 0x10

     Meanings for bits 0 - 2 are assigned by individual SCSI Dev-
     ice Class Handlers.  If the Escape bit is set, then these
     bits must all be clear for an open on the device to succeed.

     A generic _i_o_c_t_l(_2) call is provided. The file must be opened
     for at least WRITE.

     #define SCSI_CDB	    12



Printed 18/6/99     Revision 1.9 of 26/11/90			1






SD(4)		    UNIX Programmer's Manual		    SD(4)



     #define SCSI_SENSE     20

     struct scsiop {
       char  cdb[SCSI_CDB];	   /* control block for the operation */
       int   xfer;	      /* transfer count in bytes	 */
       char *addr;	      /* transfer address		 */
       int   timeout;	      /* timeout value in centiseconds	 */
       int   flags;	      /* Read/Write etc.		 */
       char  sense[SCSI_SENSE];    /* Extended Sense Information      */
       char  status;		   /* completion status               */
     };

     #define SCSIDO	 _IOWR(s, 0, struct scsiop)	 /* generic scsi operation */

     /* SCSI Status Codes */
     #define SCSI_GOOD_STATUS		0x00
     #define SCSI_CHECK_CONDITION	0x02
     #define SCSI_TIMEOUT		0x04
     #define SCSI_BUSY			0x08
     #define SCSI_RESERVATION_CONFLICT	0x10
     #define SCSI_EXPIRED		0x20
     #define SCSI_PARITY_ERROR		0x40

     /* flags for SCSIDO */
     #define SC_READ		 (1<<0)
     #define SC_WRITE		 (1<<1)
     #define SC_SENSE_VALID	 (1<<2)   /* returned to indicate the	     */
					  /* condition of the sense bytes    */
     #define SC_NO_SENSE	 (1<<3)   /* set to indicate that the driver */
					  /* should not perform a REQUEST    */
					  /* SENSE should the command fail   */
     #define SC_ALLOW_DISCONNECT (1<<11)  /* set to indicate that the driver */
					  /* should always allow target */
					  /* disconnection */

     /* Special timeout value to indicate "do not timeout" */
     #define NO_TIMEOUT     (-1)

     /* Escape flag for generic device, held in minor device */
     #define SCSI_ESCAPE  (1<<3)

     /* Exclusive Access flag for generic device, held in minor device */
     #define SCSI_EXCL	  (1<<4)


     If the transfer count is zero, then the transfer address
     should still reference a valid data buffer.  In this situa-
     tion, NULL is not classed as an acceptable address.

     There is a difference between the status codes SC_TIMEOUT,
     and SC_EXPIRED: SC_TIMEOUT is returned on a selection
     timeout, i.e. when no device responded to the selection



Printed 18/6/99     Revision 1.9 of 26/11/90			2






SD(4)		    UNIX Programmer's Manual		    SD(4)



     phase; SC_EXPIRED is returned when a device _d_i_d respond to
     the selection phase, but failed to complete the command
     within the timeout period specified.

     Usually, when only a single device is open, the driver will
     inhibit device disconnection in an attempt to avoid unneces-
     sary bus overhead.  This optimisation is undesirable for
     "long-lived" commands e.g. mag. tape rewinds, as no new dev-
     ice may be opened until the command has finished and the bus
     is idle.  The SC_ALLOW_DISCONNECT flag forces the driver to
     allow disconnection, even when only one device is open.

     If the _E_s_c_a_p_e flag is set in the minor device number, then
     the SCSIDO ioctl() is the only operation that may be per-
     formed on that device, apart from open() and close().

[1mDEVICE CLASS HANDLERS
     [0mTwo _S_C_S_I _D_e_v_i_c_e _C_l_a_s_s_e_s are currently supported. These are
     the _D_i_r_e_c_t and _S_e_q_u_e_n_t_i_a_l Access Classes. Each Device Class
     Handler provides its own _i_o_c_t_l(_2) interfaces and the style
     of interface which is conventional for that family of peri-
     pherals.

[1mDIRECT ACCESS CLASS HANDLER
     [0mThe [1mDirect [0mAccess Class Handler implements a partitioning
     scheme as found in other device drivers. The partition table
     is written on the disc medium during initialisation and read
     from the driver on the initial open. Up to eight partitions
     are defined, although some may be left _i_n_v_a_l_i_d.

     /* Partition Table Information */

     #define MAX_PARTITION	       (8)
     #define TEXT		      (16)
     #define END_OF_DISC      (0xFFFFFFFF)
     #define ID_MARK	      (0x4A657320)

     typedef struct {
       unsigned int	start;	   /* offset of partition from block 0 */
       unsigned int	length;    /* length of partition in blocks    */
       unsigned int	flags;	   /* flags to indicate state	       */
	       char	text[TEXT];	/* identifying text for partition   */
     } Partition;

     typedef struct {
       long	 time_stamp;	   /* monotonic id for table */
       Partition pt[MAX_PARTITION];	/* array of partitions	  */
     } Table;

     typedef struct {
       unsigned int	id;	   /* marker to indicate UNIX Info */
       Table		pt;	   /* partition table */



Printed 18/6/99     Revision 1.9 of 26/11/90			3






SD(4)		    UNIX Programmer's Manual		    SD(4)



     } UNIX_Info;

     /* Flags for Partition Table */
     #define PT_VALID		   (1<<0)
     #define PT_READ_ONLY	   (1<<1)

     /* Names for partitions */
     #define P_ROOT		       (0)
     #define P_SWAP		       (1)
     #define P_BOOT		       (6)
     #define P_ALL		       (7)

     /*
      * Reading and Writing the Partition Table (RAM copy)
      */

     #define WRITEPART	   _IOW(d, 0, Table *)
     #define READPART	   _IOW(d, 1, Table *)

     /*
      * Writing the Block size (RAM copy)
      */

     #define WRITEBLOCK    _IOW(d, 2, int)

     /* Partition Indication bits */

     #define PARTITION_BITS (0x07)


     The _s_c_s_i_d_m(_8) program, used to create a partition table on a
     raw disc, supplies default values for P_ALL (the whole
     disc), and P_BOOT (the portion of the disc reserved for RISC
     OS).  Any attempt to access the RISC OS area through a par-
     tition other than P_BOOT will be logged, and any write
     attempt will be refused with ENXIO.

[1mSEQUENTIAL ACCESS CLASS HANDLER
     [0mThe [1mSequential [0mAccess Class Handler administers devices such
     as Streaming Tapes. It supports the standard ioctl inter-
     faces defined in <_s_y_s/_m_t_i_o._h>.  Two device types are pro-
     vided, one a vanilla device, the other offering automatic
     rewind when the device is closed.

     /* Flags set in the minor device number */
     #define REWIND_ON_CLOSE   (1<<0)

[1mERRORS
     [0mThe following errors may be returned by the driver:

     [ENXIO] No expansion card found, illegal attempt to write
	  P_BOOT, or the card is not a SCSI card or the card is



Printed 18/6/99     Revision 1.9 of 26/11/90			4






SD(4)		    UNIX Programmer's Manual		    SD(4)



	  malfunctioning.  Attempt to open device with combina-
	  tion of Escape bit and device class specific bits (0-2)
	  set in minor number.

     [ENODEV] The addressed peripheral is not present or powered
	  on. The specified partition may not be opened.  The
	  addressed peripheral is returning a NOT READY condi-
	  tion.


     [EIO] An error occurred during the request. The request may
	  be retried although the condition is probably not tran-
	  sient.

     [EROFS] Attempt to write to a device which is READ ONLY.

     [EBUSY] The target device is currently active. This condi-
	  tion is usually transient.

     [EBADF] Attempt to call an ioctl which may perform a write
	  operation without the appropriate permissions.

     [EINVAL] Attempt to access a block oriented device in a non
	  block-aligned manner.  Transfer count passed to SCSIDO
	  ioctl() too large.

     [ENOTBLK] The block size of the target device is incompati-
	  ble with DEV_BSIZE.

[1mDIAGNOSTICS
     [0mSerious hardware errors are logged under the following
     categories.
     LOG_NOTICE
     SCSI: Recovered Error for device#%x.%x%x, info bytes [0..3] %x %x %x
     SCSI: Recovered Error for device#%x.%x%x, no info returned

     LOG_ALERT
     SCSI: Unexpected UNIT ATTENTION for device #%x:%x%x

     LOG_CRIT
     SCSI: Medium Error for device#%x.%x%x, info bytes [0..3] %x %x %x
     SCSI: Medium Error for device#%x.%x%x, no info returned
     SCSI: Unable to initialise expansion card#%x

     LOG_WARNING
     SCSI: Device %x:%x%x timed out

     LOG_ERROR
     SCSI: Cannot read boot block on device #%x:%x%x
     SCSI: Cannot read partition table on device #%x:%x%x
     SCSI: read BOOT area: block %x partition %d on device #%x:%x%
     SCSI: write BOOT area: block %x partition %d on device #%x:%x%



Printed 18/6/99     Revision 1.9 of 26/11/90			5






SD(4)		    UNIX Programmer's Manual		    SD(4)



     SCSI: device #%x.%x%x offline



[1mFILES
     [0m/dev/sd*
     /dev/rsd*
     /dev/rct*


[1mSEE ALSO
     [0mscsidm(8), RISC iX System Administrator's Guide.











































Printed 18/6/99     Revision 1.9 of 26/11/90			6



[0m