scsi_hba_tran(9S) Structure
Each instance of an HBA driver must allocate a scsi_hba_tran(9S) structure using scsi_hba_tran_alloc(9F) in the attach(9E) entry point. scsi_hba_tran_alloc(9F) initializes the scsi_hba_tran(9S) structure before it returns. The HBA driver must initialize specific vectors in the transport structure to point to entry points within the HBA driver. Once initialized, the HBA driver exports the transport structure to SCSA by calling scsi_hba_attach_setup(9F).
Caution - Because SCSA keeps a pointer to the transport structure in the driver-private field on the devinfo node, HBA drivers must not use ddi_set_driver_private(9F). They can, however, use ddi_get_driver_private(9F) to retrieve the pointer to the transport
structure.
The scsi_hba_tran(9S) structure contains the following fields:
struct scsi_hba_tran {
dev_info_t *tran_hba_dip;
void *tran_hba_private; /* HBA softstate */
void *tran_tgt_private; /* target-specific info */
struct scsi_device *tran_sd;
int (*tran_tgt_init)();
int (*tran_tgt_probe)();
void (*tran_tgt_free)();
int (*tran_start)();
int (*tran_reset)();
int (*tran_abort)();
int (*tran_getcap)();
int (*tran_setcap)();
struct scsi_pkt *(*tran_init_pkt)();
void (*tran_destroy_pkt)();
void (*tran_dmafree)();
void (*tran_sync_pkt)();
int (*tran_reset_notify)();
int (*tran_quiesce)();
int (*tran_unquiesce)();
int (*tran_bus_reset)();
};
|
Note - Code fragments presented subsequently in this chapter use these fields to describe practical HBA driver operations. See "SCSA HBA Entry Points" for more information.
where:
| tran_hba_dip | Pointer to the HBA device instance dev_info structure. The function scsi_hba_attach_setup(9F) sets this field. |
| tran_hba_private | Pointer to private data maintained by the HBA driver. Usually, tran_hba_private contains a pointer to the state structure of the HBA driver. |
| tran_tgt_private | Pointer to private data maintained by the HBA driver when using cloning. By specifying SCSI_HBA_TRAN_CLONE when calling scsi_hba_attach_setup(9F), the scsi_hba_tran(9S) structure is cloned once per target, permitting the HBA to initialize this field to point to a per-target instance data structure in the tran_tgt_init(9E) entry point. If SCSI_HBA_TRAN_CLONE is not specified, tran_tgt_private is NULL and must not be referenced. See "Transport Structure Cloning" for more information. |
| tran_sd | Pointer to a per-target instance scsi_device(9S) structure used when cloning. If SCSI_HBA_TRAN_CLONE is passed to scsi_hba_attach_setup(9F), tran_sd is initialized to point to the per-target scsi_device structure before any HBA functions are called on behalf of that target. If SCSI_HBA_TRAN_CLONE is not specified, tran_sd is NULL and must not be referenced. See "Transport Structure Cloning" for more information. |
| tran_tgt_init | Pointer to the HBA driver entry point called when initializing a target device instance. If no per-target initialization is required, the HBA can leave tran_tgt_init set to NULL. |
| tran_tgt_probe | Pointer to the HBA driver entry point called when a target driver instance calls scsi_probe(9F) to probe for the existence of a target device. If no target probing customization is required for this HBA, the HBA should set tran_tgt_probe to scsi_hba_probe(9F). |
| tran_tgt_free | Pointer to the HBA driver entry point called when a target device instance is destroyed. If no per-target deallocation is necessary, the HBA can leave tran_tgt_free set to NULL. |
| tran_start | Pointer to the HBA driver entry point called when a target driver calls scsi_transport(9F). |
| tran_reset | Pointer to the HBA driver entry point called when a target driver calls scsi_reset(9F). |
| tran_abort | Pointer to the HBA driver entry point called when a target driver calls scsi_abort(9F). |
| tran_getcap | Pointer to the HBA driver entry point called when a target driver calls scsi_ifgetcap(9F). |
| tran_setcap | Pointer to the HBA driver entry point called when a target driver calls scsi_ifsetcap(9F). |
| tran_init_pkt | Pointer to the HBA driver entry point called when a target driver calls scsi_init_pkt(9F). |
| tran_destroy_pkt | Pointer to the HBA driver entry point called when a target driver calls scsi_destroy_pkt(9F). |
| tran_dmafree | Pointer to the HBA driver entry point called when a target driver calls scsi_dmafree(9F). |
| tran_sync_pkt | Pointer to the HBA driver entry point called when a target driver calls scsi_sync_pkt(9F). |
| tran_reset_notify | Pointer to the HBA driver entry point called when a target driver calls tran_reset_notify(9E). |
scsi_address Structure
The scsi_address(9S) structure provides transport and addressing information for each SCSI command allocated and transported by a target driver instance.
The scsi_address structure contains the following fields:
struct scsi_address {
struct scsi_hba_tran *a_hba_tran; /* Transport vectors */
ushort_t a_target; /* Target identifier */
uchar_t a_lun; /* Lun on that Target */
uchar_t a_sublun; /* Sublun on that Lun */
/* Not used */
};
|
| a_hba_tran | Pointer to the scsi_hba_tran(9S) structure, as allocated and initialized by the HBA driver. If SCSI_HBA_TRAN_CLONE was specified as the flag to scsi_hba_attach_setup(9F), a_hba_tran points to a copy of that structure. |
| a_target | Identifies the SCSI target on the SCSI bus. |
| a_lun | Identifies the SCSI logical unit on the SCSI target. |
scsi_device Structure
The HBA framework allocates and initializes a scsi_device(9S) structure for each instance of a target device before calling an HBA driver's tran_tgt_init(9E) entry point. This structure stores information about each SCSI logical unit, including pointers to information areas that contain both generic and device-specific information. There is one scsi_device(9S) structure for each target device instance attached to the system.
If the per-target initialization is successful (in other words, if either tran_tgt_init(9E) returns success or the vector is NULL), the HBA framework will set the target driver's per-instance private data to point to the scsi_device(9S) structure, using ddi_set_driver_private(9F).
The scsi_device(9S) structure contains the following fields:
struct scsi_device {
struct scsi_address sd_address; /* routing information */
dev_info_t *sd_dev; /* device dev_info node */
kmutex_t sd_mutex; /* mutex used by device */
void *sd_reserved;
struct scsi_inquiry *sd_inq;
struct scsi_extended_sense *sd_sense;
caddr_t sd_private; /* for driver's use */
};
|
| sd_address | Data structure that is passed to the SCSI resource allocation routines. |
| sd_dev | Pointer to the target's dev_info structure. |
| sd_mutex | Mutex for use by the target driver. This is initialized by the HBA framework and can be used by the target driver as a per-device mutex. This mutex should not be held 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 it in, and attaches it to this field. |
| sd_sense | Pointer to a buffer to contain Request Sense data from the device. The target driver must allocate and manage this buffer itself. See the target driver's attach(9E) routine in "The attach() Entry Point" for more information. |
| sd_private | Pointer field for use by the target driver. It is commonly used to store a pointer to a private target driver state structure. |