--- scsi_address.9s.orig Tue Oct 21 19:12:37 2008 +++ scsi_address.9s Mon Oct 27 20:34:36 2008 @@ -8,45 +8,107 @@ INTERFACE LEVEL Solaris architecture specific (Solaris DDI) DESCRIPTION - A scsi_address structure defines the addressing components - for a SCSI target device. The address of the target device - is separated into two components: target number and logical - unit number. The two addressing components are used to - uniquely identify any type of SCSI device; however, most - devices can be addressed with the target component of the - address. - - In the case where only the target component is used to - address the device, the logical unit should be set to 0. If - the SCSI target device supports logical units, then the HBA - must interpret the logical units field of the data struc- - ture. - - The pkt_address member of a scsi_pkt(9S) is initialized by - scsi_init_pkt(9F). + A scsi_address structure stores the host routing and device + unit-address information necessary to reference a specific SCSI + target device logical unit function. + + Host routing information is used by the system to identify the + HBA and initiator port. + + Device unit-address information is SCSA's representation of the + "@unit-address" portion of a SCSI target driver scsi_device node + in the the /devices tree. Separate portions of the device + unit-address information define the target port address, the + logical unit address on the target, and (optionally) a + subfunction implemented by a logical unit. Device scsi_device + unit-address information is used exclusively by the host adapter + driver (with the legacy exception of target drivers communicating + with SCSI Parallel Interconnect (SPI) SCSI-1 devices that embed + SCSI logical unit addressing in the CDB). + + Two forms of scsi_device unit-address representation are + supported within the scsi_address structure: a host adapter + driver chooses the form by its hba_flags argument to + scsi_hba_attach_setup(9F): SCSI_HBA_ADDR_SPI or + SCSI_HBA_ADDR_COMPLEX. For SCSI interconnects that have a complex + scsi_device unit-address space, like fibre-channel, + SCSI_HBA_ADDR_COMPLEX should be selected. To support legacy host + adapter drivers that don't explicitly choose a form, + SCSI_HBA_ADDR_SPI is assumed. + + For host adapter drivers that choose SCSI_HBA_ADDR_SPI, two + scsi_device unit-address portions, target number (a_target) and + logical unit number (a_lun), are directly represented within the + scsi_address structure. + + For host adapter drivers that choose SCSI_HBA_ADDR_COMPLEX, the + tran_tgt_init(9E) implementation is expected to store a + per-scsi_device(9S) HBA private data pointer, based on its + interpretation of the scsi(9P) device unit-address properties, + using scsi_device_hba_private_set(9F). This approach allows SCSI + interconnects to have their own private scsi_device unit-address + representation, which is particularly important for the target + portion of the unit-address, which is transport-specific. During + tran_start(9E), an HBA driver can locate the scsi_device(9S) + structure using scsi_address_device(9F), and obtain the + per-scsi_device(9S) HBA private data pointer using + scsi_device_hba_private_get(9F). The HBA private data should be + freed by tran_tgt_free(9E). + + The pkt_address member of a scsi_pkt(9S) is initialized after + scsi_init_pkt(9F) as a result of the host adapter driver + performing a structure assignment in its tran_init_pkt(9E) + implementation. STRUCTURE MEMBERS - scsi_hba_tran_t *a_hba_tran; /* Transport vectors for the SCSI bus */ - ushort_t a_target; /* SCSI target id */ - uchar_t a_lun; /* SCSI logical unit */ - - a_hba_tran is a pointer to the controlling HBA's transport - vector structure. The SCSA interface uses this field to pass - any transport requests from the SCSI target device drivers - to the HBA driver. - - a_target is the target component of the SCSI address. - - a_lun is the logical unit component of the SCSI address. The - logical unit is used to further distinguish a SCSI target - device that supports multiple logical units from one that - does not. The makecom(9F) family of functions use the a_lun - field to set the logical unit field in the SCSI CDB, for - compatibility with SCSI-1. + + scsi_hba_tran_t *a_hba_tran; /* Transport vector */ + ushort_t a_target; /* SPI: SCSI target id */ + uchar_t a_lun; /* SPI: SCSI logical unit */ + scsi_device *a_sd; /* COMPLEX: pointer to scsi_device */ + + a_hba_tran Pointer to the controlling host adapter driver + transport vector structure. The SCSA interface + uses this field to pass any transport requests + from the SCSI target device drivers to the host + adapter driver. + + For SCSI_HBA_ADDR_COMPLEX: + + a_sd A pointer to the scsi_device(9S) structure. + This field is set by SCSA library code. An HBA + driver should not access this field directly - + use scsi_address_device(9F) instead. + + For SCSI_HBA_ADDR_SPI: + + a_target target component of the device unit-address, + limited to the range 0-65535). + + a_lun logical unit component of the device + unit-address, limited to the range 0-255. The + logical unit is used to further distinguish a + SCSI target device that supports multiple + logical units from one that does not. In the + case where only the target component is defined + in the device unit-address, the logical unit is + assumed to be 0. If the SCSI target device + supports logical units, then the host adapter + driver must interpret the logical units field + of the data structure. A scsi target driver + that supports SCSI-1 devices also needs to + access a_lun to embed logical unit addressing + in the scsi CDBs it constructs. SEE ALSO - makecom(9F), scsi_init_pkt(9F), scsi_hba_tran(9S), - scsi_pkt(9S) + makecom(9F), scsi_address_device(9F), scsi_init_pkt(9F), scsi_hba_tran(9S), + scsi_pkt(9S), tran_get_bus_addr(9E), tran_tgt_init(9E), Writing Device Drivers + + NOTES: A host adapter driver with complex addressing requirements + should use SCSI_HBA_ADDR_COMPLEX and + scsi_device_hba_private_get(9F) instead of the older, more + wasteful, SCSI_HBA_TRAN_CLONE scsi_hba_tran(9S) + tran_tgt_private approach.