DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

scb(D4sdi)


scb -- SCSI command control block structure

Synopsis

   #include <sys/sdi.h>

Description

scb is the command control block structure that is used to send a command to an SDI device. The scb contains a pointer to a command descriptor block (CDB) that describes the command to the target controller. The CDB command information is created using either the scm structure or the scs structure, both described in scm(D4sdi). The CDB contains the operation code of the instruction you to be sent and other command-specific data.

Structure definition

The scb structure is defined as follows:
   unsigned long   sc_comp_code;
   void            *sc_extra;
   void            (*sc_int)();
   caddr_t         sc_cmdpt;
   caddr_t         sc_datapt;
   long            sc_wd;
   time_t          sc_time;
   struct scsi_ad  sc_dev;
   unsigned short  sc_mode;
   unsigned char   sc_status;
   char            sc_fill;
   struct sb       *sc_link;
   long            sc_cmdsz;
   long            sc_datasz;
   long            sc_resid;
   clock_t         sc_start;

Structure members

The HBA can modify the following members: sc_comp_code, sc_status, and sc_time.

The members of the scb structure that drivers can modify are defined as:


sc_comp_code
The job completion status. See sc_comp_code(D5sdi).

sc_extra
Pointer to structure with new information. Drivers may not access this information in any way.

sc_int
A pointer to a target driver's intr(D2sdi) interrupt routine. This routine is called when the job associated with the control block completes. The interrupt routine is called with a single argument which is a pointer to the address of the sb of the job. The functions in the interrupt routine must be appropriate for the interrupt context. The intr( ) routie specified in sc_int is called when the job sending the information to the SDI device completes. If sc_int is NULL, no interrupt routine is called when the job completes.

sc_cmdpt
A virtual address pointing to the start of a target controller command, with the size indicated by the sc_cmdsz member. The command pointed to by sc_cmdpt is sent with no interpretation by the SDI software. The command area must be in kernel space and contiguous in physical memory. You must allocate your own data structure to ensure contiguous physical memory; see ``Memory allocation'' in HDK Technical Reference.

sc_datapt
A virtual address pointer pointing to the start of the data area for the given command, with the size indicated by the sc_datasz member.

sc_wd
Provided for use by the target drivers. This member is not examined or changed by SDI; you can use this member for any purpose.

sc_time
The maximum number of seconds that SDI should wait for the job to complete. The timing begins when the command is sent to the controller. The completion status must be returned before the timer runs out. If a time-out occurs, the processing of queued jobs for that controller is suspended until resumed by the target driver. If the sc_time member is zero, the job is not timed. This timing should only be used to ensure the completion of the job and not for performance measurements. The returned value of sc_time indicates the actual amount of time that the job took; the resolution is in minutes.

sc_dev
Device address (an instance of the scsi_ad(D4sdi) structure).

sc_mode
(Not supported.) This member specifies any special modes for this job. Valid values are:

SCB_HAAD
If set, the data address pointed to by the sc_datapt member was supplied by SDI; otherwise it was supplied by the target driver.

SCB_PARTBLK
Indicates that the data area pointed to by the sc_datapt member does not define the complete transfer. In this case, the sc_resid member indicates how many more bytes to expect in the transfer. These extra bytes are not transferred between system memory and the HBA bus. If the transfer is a write, zeros are sent to the controller.

sc_status
Contains the value returned by the target controller. If a CHECK CONDITION status is returned, the host adapter suspends processing of commands to that device.

sc_fill
(Not supported.) A character with which an incomplete data block is padded. All incomplete data blocks are always padded with zeros.

sc_link
(Not supported.) You must set this member to NULL before calling sdi_translate.

sc_cmdsz
Command size in bytes.

sc_datasz
Data size in bytes of the requested input or output buffer.

sc_resid
(Not supported.) The number of bytes not transferred to or from the target controller. This is used for partial block transfers. Residue bytes which are received from the target controller are discarded by SDI.

sc_start
Start time of the operation, defined as the time the job was delivered to the controller.

Usage

After the scb is sent, do not change the information in this structure or anything referenced by it (for example, in the structure that describes the CDB) until after the job completes.

The method of using the scb structure is:

  1. Fill in the appropriate information in the CDB, and put the address of the CDB in the sc_cmdpt member of the scb structure, and set sc_cmdsz.

  2. Set the sb_type member of the sb structure to indicate whether this structure is being used by the sdi_icmd(D3sdi) or sdi_xicmd(D3sdi) function, or by the sdi_send(D3sdi) or sdi_xsend(D3sdi) function.

  3. Set the sc_link member of the scb structure to NULL.

  4. Set the sc_datapt member of the scb structure to the virtual address of the data area, and set sc_datasz. Always assign values to sc_datapt and sc_datasz if the command requires a data area. You must set these two fields to NULL.

  5. Call the sdi_translate(D3sdi) or sdi_xtranslate(D3sdi) function to resolve virtual to physical addressing. Before calling this function, the sb_type, sc_cmdpt, sc_cmdsz, sc_datapt, sc_datasz, and sc_link members must be set.

  6. Call either the sdi_send(D3sdi) or sdi_xsend(D3sdi) function, or the sdi_icmd(D3sdi) or sdi_xicmd(D3sdi) function to send the CDB to the SDI device.

On successful job completion, sc_comp_code is set to SDI_ASW (all seems well).

Applicable hardware

All

Version applicability

sdi: 2, 3, 4

References

sc_comp_code(D5sdi) scm(D4sdi), sdi_icmd(D3sdi), sdi_xicmd(D3sdi), sdi_send(D3sdi), sdi_xsend(D3sdi), sdi_translate(D3sdi), sdi_xtranslate(D3sdi)
19 June 2005
© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 6 and UnixWare (SVR5) HDK - June 2005