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:
-
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
.
-
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.
-
Set the
sc_link
member of the
scb structure to NULL.
-
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.
-
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.
-
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