openSolaris 2008 - Declarations and Data Structures

Declarations and Data Structures

Target drivers must include the header file <sys/scsi/scsi.h>.

SCSI target drivers must use the following command to generate a binary module:

ld -r xx xx.o -N"misc/scsi"

`scsi_device` Structure

The host bus adapter driver allocates and initializes a scsi_device(9S) structure for the target driver before either the probe(9E) or attach(9E) routine is called. This structure stores information about each SCSI logical unit, including pointers to information areas that contain both generic and device-specific information. One scsi_device(9S) structure exists for each logical unit that is attached to the system. The target driver can retrieve a pointer to this structure by calling ddi_get_driver_private(9F).

Caution - Because the host bus adapter driver uses the private field in the target device's dev_info structure, target drivers must not use ddi_set_driver_private(9F).

The scsi_device(9S) structure contains the following fields:

struct scsi_device {
    struct scsi_address           sd_address;    /* opaque address */
    dev_info_t                    *sd_dev;       /* device node */
    kmutex_t                      sd_mutex;
    void                          *sd_reserved;
    struct scsi_inquiry           *sd_inq;
    struct scsi_extended_sense    *sd_sense;
    caddr_t                       sd_private;
};

where:

sd_address: Data structure that is passed to the routines for SCSI resource allocation.
sd_dev: Pointer to the target's dev_info structure.
sd_mutex: Mutex for use by the target driver. This mutex is initialized by the host bus adapter driver and can be used by the target driver as a per-device mutex. Do not hold this mutex across a call to scsi_transport(9F) or scsi_poll(9F). See Chapter 3, Multithreading for more information on mutexes.
sd_inq: Pointer for the target device's SCSI inquiry data. The scsi_probe(9F) routine allocates a buffer, fills the buffer in with inquiry data, and attaches the buffer to this field.
sd_sense: Pointer to a buffer to contain SCSI request sense data from the device. The target driver must allocate and manage this buffer. See attach() Entry Point (SCSI Target Drivers).
sd_private: Pointer field for use by the target driver. This field is commonly used to store a pointer to a private target driver state structure.

`scsi_pkt` Structure (Target Drivers)

The scsi_pkt structure contains the following fields:

struct scsi_pkt {
    opaque_t  pkt_ha_private;         /* private data for host adapter */
    struct scsi_address pkt_address;  /* destination packet is for */
    opaque_t  pkt_private;            /* private data for target driver */
    void     (*pkt_comp)(struct scsi_pkt *);  /* completion routine */
    uint_t   pkt_flags;               /* flags */
    int      pkt_time;                /* time allotted to complete command */
    uchar_t  *pkt_scbp;               /* pointer to status block */
    uchar_t  *pkt_cdbp;               /* pointer to command block */
    ssize_t  pkt_resid;               /* data bytes not transferred */
    uint_t   pkt_state;               /* state of command */
    uint_t   pkt_statistics;          /* statistics */
    uchar_t  pkt_reason;              /* reason completion called */
};

where:

pkt_address: Target device's address set by scsi_init_pkt(9F).
pkt_private: Place to store private data for the target driver. pkt_private is commonly used to save the buf(9S) pointer for the command.
pkt_comp: Address of the completion routine. The host bus adapter driver calls this routine when the driver has transported the command. Transporting the command does not mean that the command succeeded. The target might have been busy. Another possibility is that the target might not have responded before the time out period elapsed. See the description for pkt_time field. The target driver must supply a valid value in this field. This value can be NULL if the driver does not want to be notified.

Note - Two different SCSI callback routines are provided. The pkt_comp field identifies a completion callback routine, which is called when the host bus adapter completes its processing. A resource callback routine is also available, which is called when currently unavailable resources are likely to be available. See the scsi_init_pkt(9F) man page.

pkt_flags

Provides additional control information, for example, to transport the command without disconnect privileges (FLAG_NODISCON) or to disable callbacks (FLAG_NOINTR). See the scsi_pkt(9S) man page for details.

pkt_time

Time out value in seconds. If the command is not completed within this time, the host bus adapter calls the completion routine with pkt_reason set to CMD_TIMEOUT. The target driver should set this field to longer than the maximum time the command might take. If the timeout is zero, no timeout is requested. Timeout starts when the command is transmitted on the SCSI bus.

pkt_scbp

Pointer to the block for SCSI status completion. This field is filled in by the host bus adapter driver.

pkt_cdbp

Pointer to the SCSI command descriptor block, the actual command to be sent to the target device. The host bus adapter driver does not interpret this field. The target driver must fill the field in with a command that the target device can process.

pkt_resid

Residual of the operation. The pkt_resid field has two different uses depending on how pkt_resid is used. When pkt_resid is used to allocate DMA resources for a command scsi_init_pkt(9F), pkt_resid indicates the number of unallocable bytes. DMA resources might not be allocated due to DMA hardware scatter-gather or other device limitations. After command transport, pkt_resid indicates the number of non-transferable data bytes. The field is filled in by the host bus adapter driver before the completion routine is called.

pkt_state

Indicates the state of the command. The host bus adapter driver fills in this field as the command progresses. One bit is set in this field for each of the five following command states:

STATE_GOT_BUS – Acquired the bus
STATE_GOT_TARGET – Selected the target
STATE_SENT_CMD – Sent the command
STATE_XFERRED_DATA – Transferred data, if appropriate
STATE_GOT_STATUS – Received status from the device

pkt_statistics

Contains transport-related statistics set by the host bus adapter driver.

pkt_reason

Gives the reason the completion routine was called. The completion routine decodes this field. The routine then takes the appropriate action. If the command completes, that is, no transport errors occur, this field is set to CMD_CMPLT. Other values in this field indicate an error. After a command is completed, the target driver should examine the pkt_scbp field for a check condition status. See the scsi_pkt(9S) man page for more information.

Declarations and Data Structures

scsi_device Structure

scsi_pkt Structure (Target Drivers)

`scsi_device` Structure

`scsi_pkt` Structure (Target Drivers)