scb(D4I) scb(D4I)
NAME
scb - command control block structure
SYNOPSIS
#include <sys/sdi.h>
DESCRIPTION
The command control block structure, scb, is used to send a
command to a PDI 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(D4I). The CDB contains the operation code of
the instruction you wish to send and other command-specific
data.
Return Values
The following table is an alphabetic list of the values that
may be returned in the sc_comp_code field of the scb
structure. The third column indicates the hexadecimal value
associated with the completion code value. The fourth column
indicates on which computer type the use of the completion
code is supported. The fifth column describes which flags in
bit positions 28-31 of sc_comp_code are enabled by the
completion code. E is SDI_ERROR, M is SDI_MESS, R is
SDI_RETRY, S is SDI_SUSPEND, and ``-'' indicates that the
respective flag is not enabled.)
| | Hex | Computer |
sc_comp_code| Description | Value| Type | Flags
____________|________________________________|______|_______________|______
SDI_ABORT | Command was aborted | 0x05 | unsupported | EMRS
____________|________________________________|______|_______________|______
SDI_ASW | Job completed normally | 0x01 | 3B2, 386, i860| ----
____________|________________________________|______|_______________|______
SDI_CKSTAT | Check the status byte | 0x0e | 3B2, 386, i860| E-RS
____________|________________________________|______|_______________|______
SDI_CRESET | Reset caused by this unit | 0x07 | 386 | E-RS
____________|________________________________|______|_______________|______
SDI_HAERR | Host adapter error | 0x0b | 3B2, 386, i860| EM-S
____________|________________________________|______|_______________|______
SDI_LINKF0 | Linked cmd done without flag | 0x02 | unsupported | ----
____________|________________________________|______|_______________|______
SDI_LINKF1 | Linked cmd done with flag | 0x03 | unsupported | ----
____________|________________________________|______|_______________|______
Copyright 1994 Novell, Inc. Page 1
scb(D4I) scb(D4I)
| | Hex | Computer |
sc_comp_code| Description | Value| Type | Flags
SDI_MEMERR | Memory fault | 0x0c | unsupported | E-R-
____________|________________________________|______|_______________|______
SDI_MISMAT | Parameter mismatch | 0x12 | unsupported | EMRS
____________|________________________________|______|_______________|______
SDI_NOALLOC | This block not allocated | 0x00 | 3B2, 386 | ----
____________|________________________________|______|_______________|______
SDI_NOSELE | SCSI bus select failed | 0x11 | 3B2, 386, i860| E--S
____________|________________________________|______|_______________|______
SDI_NOTEQ | Addressed device not present | 0x08 | 386 | EM--
____________|________________________________|______|_______________|______
SDI_ONEIC | More than one immediate request| 0x17 | 3B2, 386 | E---
____________|________________________________|______|_______________|______
SDI_OOS | Device out of service | 0x10 | 3B2, 386, i860| EM--
____________|________________________________|______|_______________|______
SDI_PROGRES | Job in progress | 0x13 | 3B2, 386, i860| ----
____________|________________________________|______|_______________|______
SDI_QFLUSH | Job was flushed | 0x04 | 3B2, 386 | EMR-
____________|________________________________|______|_______________|______
SDI_RESET | Reset detected on the bus | 0x06 | 3B2, 386, i860| EMRS
____________|________________________________|______|_______________|______
SDI_SBUSER | SCSI bus error | 0x0d | None | E-RS
____________|________________________________|______|_______________|______
SDI_SCBERR | SCB error | 0x0f | 3B2, i860 | E---
____________|________________________________|______|_______________|______
SDI_SFBERR | SFB error | 0x19 | 3B2, 386, i860| E---
____________|________________________________|______|_______________|______
SDI_SHORT | TC did not transfer all data | 0x1b | unsupported | E-RS
____________|________________________________|______|_______________|______
SDI_TCERR | Target protocol error detected | 0x1a | unsupported | E--S
____________|________________________________|______|_______________|______
SDI_TIME | Job timed out | 0x09 | 3B2 | E-RS
____________|________________________________|______|_______________|______
SDI_UNUSED | Job not in use | 0x14 | 3B2, i860 | ----
____________|________________________________|______|_______________|______
SDI_V2PERR | vtop failed | 0x08 | unsupported | EM--
The supported sc_comp_code values are defined as follows:
SDI_ASW All seems well. The job completed without an
error.
SDI_CKSTAT Check the status byte. This value is set when
the target controller returns a status other
than good.
Copyright 1994 Novell, Inc. Page 2
scb(D4I) scb(D4I)
SDI_HAERR A problem occurred between PDI and the host
adapter controller. Possible causes are I/O
bus parity or a failed host adapter.
SDI_NOALLOC The requested block was not allocated to a
target driver by PDI. If a target driver
detects this value, panic the system (using
the cmn_err(D3) function). sc_comp_code is
set to this value when the command block is
released from the target driver.
SDI_NOSELE SDI timed out trying to select the controller.
SDI_ONEIC More than one immediate request has been sent.
SDI_OOS The firmware is not operational.
SDI_PROGRES The job is not complete (set by PDI in the
sdi_icmd and sdi_send functions).
SDI_QFLUSH When the target driver requested a job queue
flush for a device, all jobs in the queue are
returned with this completion code set.
SDI_RESET PDI detected a reset on the HBA bus. All
outstanding or jobs queued at the target
controller are returned to the target drivers
with this condition code set. If the job is
being controlled by PDI, but has not been sent
out on the bus, the job is not returned. This
code is also returned if a target driver
requests that a target controller be reset.
SDI_SCBERR The control block contains an error or an
invalid type.
SDI_SFBERR There is an error in one of the fields in the
sfb structure.
SDI_TIME SDI timed out a job.
SDI_UNUSED The host adapter is not using the control
structure. SDI sets the sc_comp_code to this
value when it allocates a block for a target
driver.
Copyright 1994 Novell, Inc. Page 3
scb(D4I) scb(D4I)
The following values are listed in sdi.h but are not supported
at this time:
SDI_LINKF0 This linked command completed normally and the
command value bit was zero.
SDI_LINKF1 This linked command completed normally and the
command value bit was one.
SDI_MISMAT A controller attempted to perform an operation
that did not agree with the data supplied in
the SCB. For example, this error can occur
when the controller attempts to transfer data
in and the SCB_READ value is not set in the
sc_mode member.
SDI_SBUSER The host adapter encountered a problem on the
SCSI bus and all recovery action failed. A
controller with a faulty bus driver can cause
such an error.
SDI_TCERR The host adapter detected a protocol error
while performing this request.
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 sdi_icmd(D3I)
or by sdi_send(D3I).
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
Copyright 1994 Novell, Inc. Page 4
scb(D4I) scb(D4I)
fields to NULL.
5 Call sdi_translate(D3I) to resolve virtual to physical
addressing. Before calling this function, these fields
must be set: sb_type, sc_cmdpt, sc_cmdsz, sc_datapt,
sc_datasz, and sc_link.
6 Call either sdi_send or sdi_icmd to send the CDB to the
PDI device.
On successful job completion, sc_comp_code is set to SDI_ASW
(all seems well).
For an error condition, check sc_comp_code for SDI_CKSTAT,
then check sc_status to determine the type of error that was
returned by the target controller. (When an error occurs on a
PDI device, the error is passed to the controller and then
through the firmware of the host adapter. PDI acknowledges
this interaction and sets the error code from the target
controller in sc_status and sets sc_comp_code to SDI_CKSTAT.)
If sc_comp_code is not SDI_CKSTAT or SDI_ASW, then the value
in bits 0-27 of sc_comp_code indicates the nature of the error
and the value in bits 28-31 indicates how to process the
error. As an alternative, you may wish to check bits 28-31
for SDI_ERROR, and then test bits 0-27 for more specific
information.
A scenario for this usage is shown in the structure members
explanation for sc_comp_code, earlier in this manual page.
Structure Members
The scb structure is defined as follows:
unsigned long sc_comp_code; /* Current job status */
void (*sc_int)(); /* Target driver intr handler */
caddr_t sc_cmdpt; /* Target command */
caddr_t sc_datapt; /* Data area */
long sc_wd; /* Target driver word */
time_t sc_time; /* Time limit for job */
struct scsi_ad sc_dev; /* PDI device address */
unsigned short sc_mode; /* Mode flags for current job */
unsigned char sc_status; /* Target status byte */
char sc_fill; /* Fill byte */
struct sb *sc_link; /* Link to next scb command */
long sc_cmdsz; /* Size of command */
Copyright 1994 Novell, Inc. Page 5
scb(D4I) scb(D4I)
long sc_datasz; /* Size of data */
long sc_resid; /* Bytes to transfer after data */
The fields that the host adapter can change are: sc_comp_code,
sc_status, and sc_time.
More information on each member of the scb structure follows:
sc_comp_code The job completion status. This member is
tested in the interrupt routine after the job
has completed. Use sc_comp_code by testing for
SDI_ASW (normal return). If SDI_ASW is not
present, test bits 28-31 to determine if
SDI_ERROR was set to indicate an error
occurred. The remaining values in bits 28-31
indicate how to process the error. The values
for bits 28-31 are covered in the following
text. Values for bits 0-27 are covered at the
end of the scb structure section. Refer to the
header file for more information on how to
extract the values in each bit position.
Values for bits 28-31 are:
SDI_ERROR An error occurred.
SDI_RETRY The error is unrelated to this
job, and the job should be
retried (device dependent).
SDI_MESS A message describing this event
has been printed on the console
and logged.
SDI_SUSPEND The host adapter has suspended
sending normal commands to the
logical unit and the target
driver is responsible for
resuming the queue. Immediate
commands can still be sent with
the sdi_icmd function, but the
SCSI device cannot be opened for
pass-through.
sc_int A pointer to a target driver interrupt routine.
This routine is called when the job associated
with the control block completes. The
Copyright 1994 Novell, Inc. Page 6
scb(D4I) scb(D4I)
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 not call sleep(D3), have
user context, or run in the context of any
particular process. sc_int is called when the
job sending the information to the PDI 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.
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 PDI; you
can use this member for any purpose.
sc_time The maximum number of milliseconds PDI 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 and the
resolution is in minutes.
sc_dev Device address (an instance of the scsi_ad(D4I)
structure).
Copyright 1994 Novell, Inc. Page 7
scb(D4I) scb(D4I)
sc_mode (Not supported.) This member specifies any
special modes for this job. The SCB_HAAD bit
in the sc_mode field refers to the data
address, pointed to by the sc_datapt element.
If the SCB_HAAD bit is set in the sc_mode
field, the data address was supplied by PDI,
otherwise it was supplied by the target driver.
When SCB_PARTBLK is set in the mode field, it
should indicate that the data area does not
define the complete transfer. In this case,
the sc_resid field 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 PDI.
REFERENCES
scb(D4I), scm(D4I), sdi_icmd(D3I), sdi_send(D3I)
Copyright 1994 Novell, Inc. Page 8