|
|
| |
|
|
|
SCSI Driver Requirements & Bindings
2.1 General Requirements
2.1.1 Versioning
All functions and structures defined in the UDI SCSI Driver Specification are part of the "udi_scsi" interface, currently at version "0x101". A driver that conforms to and uses the UDI SCSI Driver Specification, Version 1.01, must include the following declaration in its udiprops.txt file (see Chapter 30, "Static Driver Properties", of the UDI Core Specification):
requires udi_scsi 0x101In each UDI SCSI driver source file, before including any UDI header files, the driver must define the preprocessor symbol, UDI_SCSI_VERSION, to indicate the version of the UDI SCSI Driver Specification to which it conforms, which must be the same as the interface version defined above:
#define UDI_SCSI_VERSION0x101A portable implementation of the SCSI Metalanguage Library must include a corresponding "provides" declaration in its udiprops.txt file, must define UDI_SCSI_VERSION, and must conform to the requirements specified in the Metalanguage-to-Environment (MEI) interface defined in Chapters Chapter 27 and Chapter 28 of the UDI Core Specification.
As defined in Section 30.4.6, "Requires Declaration," on page 30-6 of the UDI Core Specification, the two least-significant hexadecimal digits of the interface version represent the minor number; the rest of the hex digits represent the major number. Versions that have the same "major version number" as an earlier version shall be backward compatible with that earlier version (i.e. a strict superset).
2.1.2 Header Files
Each UDI SCSI driver source file must include the file "udi_scsi.h" after it includes "udi.h", as follows:
#include <udi.h> #include <udi_scsi.h>The "udi_scsi.h" header file contains function prototypes and other definitions needed to use the UDI SCSI interfaces.1
2.2 SCSI Metalanguage Model
The SCSI Metalanguage is designed to allow for exactly one HD instance attached to a given HBA, but multiple instances of a PD may be attached to a given LUN. A PD is either a multi-lun PD (see the definition of the "scsi_multi_lun" attribute in Section 2.5.2.1, "Enumeration Attributes" below), or a single-lun PD which controls a single LUN. PDs are generally single-lun in nature, but special PDs can be configured which control multiple LUNs.
While there is a 1-to-1 correspondence between an HD and an HBA (as defined in Section 1.5, "Terminology"), there isn't necessarily a 1-to-1 correspondence between HDs and SCSI buses or interconnects. For example, a non-independent multi-port HBA (an HBA with multiple SCSI buses that can't be controlled independently) will have a single instance of an HD which controls multiple SCSI buses/links. This is the reason for the "scsi_bus" enumeration attribute.
For purposes of exclusive access (see the exclusive bind flags in the udi_scsi_bind_cb_t below) and SCSI event notification, unless stated otherwise in the SCSI interfaces, a multi-lun PD is treated as if there is a single-lun PD attached to each possible LUN. Thus, a multi-lun PD which is exclusively bound prohibits all other PD bindings to the HD, effectively giving the multi-lun PD exclusive access to the HD. A multi-lun PD which is non-exclusively bound prevents any other PD from binding exclusively (although another PD could in this case still do a "temporary exclusive bind"). If a SCSI event occurs which affects the PDs on a given LUN, any multi-lun PDs which have the event enabled will be notified along with the single-lun PDs attached to the LUN.
2.3 SCSI I/O Addressing
The SCSI Metalanguage recognizes 4 levels of SCSI I/O addressing: Bus Number, Target ID, LUN, and Tag. The Tag is not strictly an addressing component (it is a request identifier within a LUN from a given initiator) and is therefore not described in detail in this section. Tag use and assignment is typically HD and/or SCSI interconnect dependent. However, the PD is allowed to specify Tag types (Head of Queue, Ordered, etc) for each SCSI I/O issued to the HD.
The SCSI Metalanguage is designed to set up bindings between the PDs and HDs such that I/O request packets passed between the PD and HD need not specify Bus Number, Target ID, or LUN values (with the single exception of the multi-lun PD). The addressing values are a property of the enumerated PD instance and are inherent in the channel used for communication between the PD and the HD. For the multi-lun PD, the Bus Number, Target ID, and LUN values are encoded into the SCSI I/O control block.
2.3.1 Bus Number
The Bus Number represents a SCSI bus/link interface on an HBA. Typical HBA's are single ported (containing a single SCSI interface) or if multi-ported, enumerate their hardware such that separate and independent hardware instances are created for each SCSI interface. In these cases, the Bus Number is zero. For the multi-ported HBA's that contain interdependent SCSI interfaces (e.g. only one HD instance is enumerated for multiple SCSI interfaces), the Bus Number represents which of the SCSI interfaces on the HBA the I/O should be issued on. The Bus Number values are relative to the HBA's HD. Multiple HDs whose hardware is connected to the same SCSI interconnect, may export different Bus Numbers for the same SCSI interconnect.
The Bus Number addressing component is specified by the HD as an enumeration attribute when it enumerates the PD instances. On a per-request basis, the Bus Number is specified only in SCSI I/O requests made by a multi-lun PD; I/O requests from all other PDs have the Bus Number inherent in the channel that the I/O request is issued on.
2.3.2 Target ID
The Target ID represents a hardware entity attached to the SCSI interconnect. The value is assigned by the HD and, depending on the HD implementation, may or may not be persistent across driver restarts. As the Target ID value is HD dependent, multiple HD's attached to the same SCSI interconnect may export different Target ID values for the same hardware entity.
Although the Target ID value has historically been set to the physical value of the hardware entity on the interconnect, the SCSI Metalanguage recognizes that there are inherent problems in doing so, especially with new SCSI-3 interconnects where physical addresses are temporal, much larger, sparsely populated, and may be changed while I/O is in flight. Historical mappings also suffer from additional issues regarding delays and interconnect utilization when I/O is sent to Target IDs that are non-existent.
The SCSI Metalanguage expects an HD to support a maximum number (N) of Target IDs, whose values range from 0 to N-1. During enumeration, an HD may enumerate devices that it detects are present at some subset of the Target IDs. All N Target IDs can be addressed by the multi-lun PD (even if not enumerated), with the value of N being given to the multi-lun PD during the binding sequence via an enumeration attribute (see the scsi_max_targets attribute).
The Target ID addressing component is specified by the HD as an enumeration attribute on all non-multi-lun PD instances that it enumerates. On a per-request basis, the Target ID component is specified only in SCSI I/O requests made by a multi-lun PD. I/O requests from all other PDs have the Target ID inherent in the channel that the I/O request is issued on.
2.3.3 LUN - Logical Unit Number
As per the SCSI Architecture Model - 2 (SAM-2) specification: the LUN represents a target-resident entity which implements a device model and executes SCSI commands sent by an application client. The LUN value is an encoded 64 bit (8 byte) identifier for a SCSI logical unit. A detailed definition of a logical unit number may be found in the SAM-2 specification.
Logical Unit values are typically obtained from the Target ID (e.g. the physical device) via the use of the SCSI-3 REPORT LUNS SCSI command issued to LUN zero. However, some SCSI device hardware and interconnects do not fully support the SCSI-3 concept of an 8-byte LUN value or do not support the use of the SCSI-3 REPORT LUNS command. In such cases, it is expected that the HD will support 256 logical units or less, and report it's maximum LUN value during the binding process. All LUN values between 0 and the maximum can be addressed by the multi-lun PD (even if not enumerated). When specifying or interpreting the 8-byte LUN value for these non-SCSI-3 cases, the LUN value shall conform to the Single Level LUN Structure as per SAM-2 (i.e, byte 0 is zero, byte 1 contains the LUN value, and the remaining 6 bytes are zero).
The LUN addressing component is specified by the HD as an enumeration attribute on all non-multi-lun PD instances that it enumerates. On a per-request basis, the LUN component is specified only in SCSI I/O requests made by a multi-lun PD. I/O requests from all other PDs have the LUN value inherent in the channel that the I/O request is issued on.
2.4 Peripheral Driver & HBA Driver Responsibilities
The SCSI Metalanguage divides operation and decision-making between PDs and HDs. In general, PDs make decisions specific to a particular SCSI device, and HDs make decisions that apply to an entire SCSI bus. This section provides some clarifications on each driver's responsibilities.
2.4.1 Retries
Both the PD and the HD may retry I/Os. However, any request that can affect device state must not be retried by the HD. The HD guarantees that it is immediately ready to accept a retry attempt from the PD, but, as with other operations, it may not be committed to the hardware instantly.
2.4.2 Timeouts
Both the PD and the HD may time I/Os or other requests. However, as defined in the udi_scsi_io_cb_t definition on page 3-16, the HD must time I/O requests received via a udi_scsi_io_req if the PD specifies a nonzero timeout value in the request. If the request doesn't complete within the specified timeout period the HD must abort the request and complete it with status UDI_STAT_TIMEOUT.
The timeout value specified by the PD in the udi_scsi_io_req should be much longer than the longest time that the specified request is expected to physically take in the device. To reduce variability, the HD must time the request only from the time it starts the request on the SCSI interconnect (not from the time it first receives the request from the PD); the HD must guarantee forward progress of internally queued requests. If a condition exists that prohibits forward progress, the HD must abort the request, returning it to the PD with the appropriate error indication. Even with the HD guaranteeing forward progress, there can still be significant variability in the delivery time across the interconnect to the device, so when specifying a timeout on a udi_scsi_io_req operation the PD must include the hd_timeout_increase value as defined in the udi_scsi_bind_ack definition on p. 3-11.
2.4.3 Aborts
The PD aborts individual SCSI I/O requests by using udi_channel_op_abort, passing the control block pointer for the original request. If the original request is still in the HD, the HD will receive a udi_channel_event_ind of type UDI_CHANNEL_OP_ABORTED, with the pointer to the original request. The HD is to then abort and then ack (or nak as appropriate) the original request to the PD. If the original request is no longer pending in the HD, the udi_channel_op_abort request will be discarded.
Control requests, which affect multiple SCSI I/O requests (Target Reset, etc), shall result in the desired function performed by the HD, followed by the the HD generating an ack (or nak as appropriate) of all affected I/O requests back to the PD. The HD will not respond with the corresponding ack for the control request until the function is performed and all affected requests have been returned to the PD.
2.4.4 Transfer Negotiation
The HD is responsible for maintaining the current state of transfer parameter negotiation (e.g., synchronous and wide parameters on parallel SCSI). It will renegotiate with the device whenever it believes that the negotiation has been lost, such as after a Unit Attention indicating SCSI bus reset. The HD will always negotiate for the maximum transfer rate the device and HBA are capable of, unless limited by the per-PD instance attribute "@scsi_max_xfer_rate" having been set on any of the PDs associated with the device, or by the "%scsi_max_xfer_rate" parameter.
2.4.5 Task/Queue Management
The HD generates and maintains the tag values associated with tagged SCSI commands. Since multiple PDs can be bound to the same LUN, the HD must keep track of these tags on a per-LUN basis (or higher level of granularity such as per-target or per-bus), not merely on a per-PD basis.
The HD is responsible for ensuring that the task ordering rules of SCSI are followed; this includes ensuring that tagged and untagged requests are not pending for the same device simultaneously.
The PD specifies its device's queue depth to the HD in the scsi bind request, and it is then the responsibility of the HD to guarantee that the queue depth to the device (i.e., the minimum of the queue depths specified by the PDs attached to a given LUN, with the exception of the multi-lun PDs which are excluded from this minimum calculation as noted below) is not exceeded. In this model the PD can send as many requests as it likes to the HD and the HD must manage per-LUN request queues to make sure that the number of requests outstanding on the device is not exceeded.
The PD can dynamically adjust its queue depth via the scsi_ctl request, in which case the queue depth change takes effect with respect to subsequent requests received from the PD.
It is the responsibility of the PD to handle QUEUE FULL conditions by reducing its queue depth as necessary to reduce the likelihood of QUEUE FULLs. This can occur for example in the presence of PDs on other initiators attached to the same LUN.
Note - multi-lun PDs are excluded from the minimum calculation of queue depth for a given LUN since a multi-LUN PD is effectively a generic SCSI pass-through driver which can address any target and LUN. Therefore, the HD must ignore the queue depth specified by multi-lun PDs (so as to not affect the queue depth requirements of more specific PDs).
2.4.6 SCSI Bus/Link Errors
The HD is responsible for detecting bus hangs or link errors, and responding appropriately to alleviate or recover from the condition where possible. Any affected I/O requests or control operations not recoverable at the link level will be returned to the requesting PD, with appropriate status, whether started at the device or not.
2.5 Bindings to the UDI Core Specification
2.5.1 Static Driver Properties Bindings
Some of the bindings for the static driver properties are defined in Section 2.1.1, "Versioning". This includes the definition of the relevant interface name(s) (i.e., the <interface_name> parameter on the "requires" and "provides" and other property declarations), and the definition of the interface version number for this version of this Specification.
The driver category to be used with the "category" declaration (see Section 30.5.3, "Category Declaration," on page 30-11 of the UDI Core Specification) by a portable implementation of the SCSI Metalanguage Library shall be "SCSI Host Bus Adapters".
The <attr_name> parameter values defined for use with the "custom" declaration (see Section 30.6.10, "Custom Declaration," on page 30-20 of the UDI Core Specification) are specified in Section 2.5.2.5, "Custom Parameters for HD Drivers" below.
2.5.2 Instance Attributes Bindings
In each of the attribute tables below, the ATTRIBUTE NAME is a null-terminated string (see "Instance Attribute Names" on page 15-1 of the UDI Core Specification); the TYPE column specifies an attribute data type as defined in "udi_instance_attr_type_t" on page 15-7 of the UDI Core Specification; and the SIZE column specifies the valid sizes, in bytes, for each attribute.
2.5.2.1 Enumeration Attributes
The enumeration attributes specified in Table 2-1 are defined for the enumeration of SCSI devices, including the multi-lun pseudo-device and the HBA's initiator devices. Prior to enumerating any other devices, the SCSI HD must first enumerate exactly one multi-lun pseudo device using an attr_list containing only the scsi_multi_lun, scsi_max_buses, scsi_max_tgts, and scsi_max_luns attributes. Note that only one multi-lun enumeration is needed per HD instance, even if the HD instance controls multiple SCSI buses.
The HBA's initiator devices, one for each applicable scsi_bus value, must be enumerated as part of an enumeration START/NEXT cycle, with scsi_target equal to the corresponding initiator id, and scsi_lun equal to zero. If the %scsi_initiator_id attribute (or its nonzero bus number flavors) exists and is programmable by the driver in its hardware, its value must be used in enumerating the corresponding initiator device node. If the device isn't programmable the HD must compare the device's initiator id value (whether hard-coded or mechanically switchable) to the value of the %scsi_initiator_id attribute (or its default value if the attribute doesn't exist) and if not equal the HD must fail its parent binding with status UDI_STAT_ATTR_MISMATCH as described in Section 2.5.2.5. If and only if enumerating an initiator device node, the scsi_target_mode_supported attribute must also be present, and in this version of the Specification its value must be FALSE.
Table 2-1 SCSI Enumeration Attributes ATTRIBUTE NAME TYPE SIZE DESCRIPTION As the enumeration values describe the end device explicitly, including it's addressing components, if a hot plug event takes place, which is detected by the driver and results in the change of any enumeration parameters, the previous device is to be denumerated (potentially causing it to be unbound) and the newly detected device enumerated.
SCSI-3 architecturally allows for Target IDs and LUNs up to 64 bits in size. The LUN value follows the format as described in SAM-2. The Target ID value is a logical value, 32 bits in size, constructed by the HD. It is the HD's responsibility to map this to larger Target address spaces, where applicable. Refer to Section 2.3, "SCSI I/O Addressing" for additional details.
The "scsi_bus" attribute specifies the peripheral device's SCSI bus number, which is needed to distinguish among buses attached to non-independently-controlled multi-port SCSI HBAs (i.e., HBAs that have multiple SCSI buses which, due to hardware inter-dependencies, must be controlled by a single SCSI HD instance). The range of this value is from 0 to 255.
The "scsi_dev_pqual" attribute is equivalent to the Peripheral Qualifier field in the high-order 3 bits of the first byte (byte 0) of the INQUIRY data. Note that it is a 4 byte integer attribute even though only the high order 3 bits are needed for the data. The high-order 3 bits of the first byte of the INQUIRY data are masked and the result, unshifted, is set using the UDI_ATTR32_SET or UDI_ATTR32_INIT utilities.
The "scsi_dev_type" attribute is equivalent to the Peripheral Device Type field in the low-order 5 bits of the first byte (byte 0) of the INQUIRY data. Note that it is a 4 byte integer attribute even though only the low order 5 bits are needed for the data.
The "scsi_vendor_id" attribute provides an up to 9-byte vendor ID string (including a null terminator). The contents of this attribute are the 8 bytes of vendor ID in the SCSI INQUIRY data with trailing blanks and null characters removed and a null terminator appended. If the device does not provide a vendor ID string, this attribute shall be set to a null string.
The "scsi_product_id" attribute provides an up to 17-byte product ID string (including a null terminator). The contents of this attribute are the 16 bytes of product ID in the SCSI INQUIRY data with trailing blanks and null characters removed and a null terminator appended. If the device does not provide a product ID string, this attribute shall be set to a null string.
The "scsi_product_rev" attribute provides an up to 5-byte product revision string (including a null terminator). The contents of this attribute are the 4 bytes of product revision in the SCSI INQUIRY data with trailing blanks and null characters removed and a null terminator appended. If the device does not provide a product revision string, this attribute shall be set to a null string.
Note - The utility function, udi_strncpy_rtrim, can be used to convert the corresponding character arrays in the SCSI INQUIRY data to the null-terminated strings required in the "scsi_vendor_id", "scsi_product_id", and "scsi_product_rev" attributes.
The "scsi_inquiry" attribute provides the first 36 bytes of SCSI INQUIRY data associated with the peripheral device, or as many bytes as received from the device if less than 36 bytes were received.
The "scsi_tgt_wwid" attribute provides an up to 32-byte world-wide ID string associated with the target device the logical unit is connected to. In many SCSI-3 interconnects, the target has a unique interconnect-specific world-wide identifier. For Fibre Channel, this attribute shall be set to the 16-byte N*_Port <PortName,NodeName> pair (in that order). For SIP (SCSI-3 Interlocked Protocol), this shall be the 32-byte SCAM (SCSI Configured Auto-Matically) identification string, as defined in Annex B of the SCSI-3 Parallel Interface specification (SPI). For SBP (the IEEE 1394 Serial Bus Protocol), this shall be the 2-byte Node ID, as defined by IEEE 1394-1995. If the interconnect does not support one of these world-wide identifiers, or if the identifier cannot be obtained, then this attribute must not be enumerated.
The "scsi_lun_wwid" attribute provides the world-wide ID string associated with the logical unit. Although there are several potential device identifiers, only two types of world-wide ID values shall be valid for use with this attribute. The first is the 8-byte FC-PH IEEE Registered value obtained via the Vital Product Data Device Identification page (page 0x83) of the SCSI INQUIRY command. The second is the 16-byte FC-PH IEEE Registered Extended value obtained via the Vital Product Data Device Identification page (page 0x83) of the SCSI INQUIRY command. If the device does not support either of these identifiers or the Vital Products Data page, or if the identifier cannot otherwise be obtained, the attribute must not be enumerated.
The "scsi_target_mode_supported" attribute indicates whether or not an initiator device node supports responding as a target device. It is only applicable to initiator device node enumerations, and in this version of the Specification must always be set to FALSE.
The "scsi_multi_lun" attribute is used to enumerate a multi-lun pseudo-device for use in instantiating multi-lun PD instances. Multi-lun PD instances pass the Bus Number, Target ID and LUN on each I/O request, in the CDB memory area. As a result, multi-lun PDs must include 16 additional bytes in cdb_mem_size when initializing their SCSI I/O control block properties. See the cdb_ptr definition in the udi_scsi_io_cb_t for additional details.
The "scsi_max_buses", "scsi_max_tgts", and "scsi_max_luns" attributes must be used when doing the multi-lun enumeration, and are only applicable in that case. The scsi_max_buses attribute specifies the maximum number of buses that the HD can enumerate. This attribute must have a non-zero value and must have the value one if the HBA's attached buses are independently controlled buses that are each controlled by separate instances of the HD. The scsi_max_tgts attribute specifies the maximum number of targets that the HD can enumerate per bus. This can be an interconnect-specific limit or an HBA or driver-specific limit, and must be non-zero. The scsi_max_luns attribute specifies the maximum number of LUNs per target addressable by the HD and its associated hardware, if in the range 1..256; otherwise scsi_max_luns must be set to zero indicating that the HD and its associated hardware support full SCSI-3 LUN addressing per the SAM-2 Eight Byte LUN structure definition.
The remaining SCSI enumeration attributes are generic enumeration attributes, described below.
2.5.2.2 Generic Enumeration Attributes
2.5.2.2.1 identifier attribute
For SCSI peripheral devices, the "identifier" attribute encodes the device's LUN WWID value, if present, or its INQUIRY data, as a null-terminated string.
If the device has a "scsi_lun_wwid" value, then "identifier" encodes this value as a string of upper-case hexidecimal digits, two for each byte of the 8-byte value, with the first byte of data corresponding to the first two characters in the string, and so on.
If the device does not have a "scsi_lun_wwid" value, then "identifier" encodes up to 36 bytes of the SCSI INQUIRY data, with the first 8 bytes encoded as upper-case hexidecimal digits (two for each byte, starting with the first byte), followed by the next 28 bytes forced to be printable ASCII characters by replacing any byte outside the range 33..126 with the value 46 (ASCII for the period character, `.'). If there are fewer than 36 INQUIRY bytes, the "identifier" string is truncated accordingly.
Note - The utility function, udi_scsi_inquiry_to_string, can be used to convert SCSI INQUIRY to an "identifier" string.
2.5.2.2.2 address_locator attribute
For SCSI peripheral devices, the "address_locator" attribute encodes a concatentation of the bus, target, and lun attributes using the following syntax:
address_locator = BBTTTTTTTTLLLLLLLLLLLLLLLL
where BB is a two-digit upper-case hexidecimal-encoded ASCII representation of scsi_bus, TTTTTTTT is a four-digit upper-case hexidecimal-encoded ASCII representing scsi_target (first two digits encode the most significant byte, and so on), and LLLLLLLLLLLLLLLL is an 8-digit upper-case hexidecimal-encoded ASCII representation of scsi_lun (first two digits encode the first byte, and so on), respectively.
2.5.2.2.3 physical_locator attribute
No "physical_locator" attribute is defined for the SCSI metalanguage.
2.5.2.2.4 physical_label attribute
No "physical_label" attribute is defined generically for the SCSI metalanguage. Platforms that have access to such information may set physical_label attributes.
2.5.2.3 Enumeration Attribute Ranking
To support the ranking of enumerated devices against available drivers for the udi_mei_enumerate_rank_func_t, the following combinations of enumeration attribute matches yield the corresponding ranking values. Attribute combinations not specified return a relative rank of 0 (the lowest possible rank). The combinations are unchanged by matches of non-rankable attributes.
Table 2-2 SCSI Enumeration Attribute Ranking Rank Value Rankable Attributes1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 identifier Y scsi_lun_wwid Y Y scsi_tgt_wwid Y Y scsi_inquiry Y scsi_product_rev Y Y Y Y scsi_product_id Y Y Y Y Y Y Y Y scsi_vendor_id Y Y Y Y Y Y Y Y Y Y Y Y scsi_dev_type Y Y Y Y Y Y Y Y scsi_dev_pqual Y Y Y Y Y Y Y Y
1Y indicates the valid match of the attribute. Only the attributes listed are rankable; all other enumeration attributes have no effect on the ranking value. The matching of some attributes may imply the matching of others. For example, a match of vendor id and product id typically implies a specific type of device (i.e., a specific value of scsi_dev_type), so a driver may very well decide to specify just those two attributes in a "device" line in its udiprops.txt file without specifying scsi_dev_type. But since this may not always be the case, a higher rank is assigned if all three match.
2.5.2.4 Filter Attributes
Of the above listed enumeration attributes, the following shall be supported as filter attributes for enumeration filtering:
scsi_bus
scsi_target
scsi_lun
Excepting scsi_lun, the attr_stride in the filter element structure (see udi_filter_element_t) is interpreted linearly; that is, the stride value is simply added to the numeric value of these attributes. For scsi_lun, the attr_stride in the filter element structure will only apply to SCSI LUN values that conform to the Single Level LUN Structure as per SAM-2. In which case, the stride will be interpreted linearly on the encapsulated LUN value.
2.5.2.5 Custom Parameters for HD Drivers
For appropriate configuration and operation of the HD, the following well-known attributes must be included, if applicable to the SCSI interconnect or to any of the HBAs controllable by the HD, as "custom" declarations with device scope in the HD's udiprops.txt static driver properties file (see Section 30.6.10, "Custom Declaration," on page 30-20 of the UDI Core Specification). HDs controlling parallel SCSI buses must provide custom declarations for each of the attributes specified in this section, regardless of whether or not the attribute is programmable by the HD, as long as the attribute is applicable to the HBA (even if only as a hard-coded or mechanically switchable value). It is expected that each of the attributes in this section should be applicable in that sense to all parallel SCSI HBAs, with the exception of auto-termination whose requirements are defined below.
There are two categories of custom attributes used by HDs: per HD instance attributes, defined in the next section (2.5.2.5.1) below, and per-PD attributes that are visible to the HD (also known as parent-visible attributes), defined in Section 2.5.2.5.2 below. A third sub-section (2.5.2.5.3) specifies the subset of the HD's custom attributes that are dynamically changeable, and defines the requirements on the HD for re-reading these attributes.
For each custom attribute defined below, the default value specified must be used if the attribute doesn't exist. Boolean attributes are enabled with a value of TRUE (1), and disabled with a value of FALSE (0).
2.5.2.5.1 Custom Parameters for HDs (per-HD instance)
The attributes in this sub-section are set by the environment on each instance of the HD. The following such attributes are defined:
Each of the attributes in Table 2-3 applies to bus number 0 on the HBA. If the HBA has multiple buses, the above attribute names must be suffixed with an underscore followed by an ASCII-encoded decimal string representing the bus number, for bus numbers greater than zero.
Unless otherwise indicated below, the following rules apply with respect to the programmability of these attributes.
If the above attribute values are programmable on the device, the driver must obtain them and, if they exist, use the values of these parameters to set in the HBA device when it's initialized.
If an attribute is not programmable then the device's value for the attribute (whether hard-coded or mechanically switchable) must be compared to the value of the attribute (or its default value if the attribute doesn't exist) and if not equal the HD must fail its parent binding with status UDI_STAT_ATTR_MISMATCH on the corresponding udi_channel_event_complete and make a call to udi_log_write detailing the mismatched attribute names and values. These attribute comparisons must be done after receiving the UDI_CHANNEL_BOUND indication on the parent bind channel and, if the HBA device needs to be accessed (e.g., to read the device's attribute setting), would need to be done after a successful metalanguage-specific binding has been completed with the parent.
The %scsi_bus_width provides the width of the physical SCSI bus/connector attached to the corresponding SCSI port on the HBA. When it exists, the HD's initiator device must neither accept nor request negotiations for data transfer of a greater width than is specified by the %scsi_bus_width attribute.
A common case where %scsi_bus_width is needed is when a narrow port is connected to a wide-capable SCSI controller and there's no programmatically readable indicator on the HBA for this. Without such an attribute (indicating in this case that the %scsi_bus_width is 8 rather than the 16 that the SCSI protocol chip is capable of) the HD could inappropriately negotiate for wide transfers.
Auto-termination on a parallel SCSI HBA can be implemented in various ways, but typically auto-termination operates by sensing a pin on the internal and external connectors to see if a powered device (or a physical terminator) is connected. If both connectors have devices connected then the HBA will disable its on-board termination circuits; otherwise the on-board termination is enabled. The auto-termination mechanism can be affected by programmatic controls or by mechanical controls (e.g., jumpers) on the card.
The auto-termination attributes are only applicable to HBAs that either support on-board auto-termination or provide a mechanism to programmatically determine if physical termination has been applied. In the latter case (an HBA that doesn't provide on-board auto-termination but does allow the HD to programmatically determine if physical termination has been applied to the connectors), an attribute mismatch must be indicated if %scsi_auto_termination is TRUE (or defaults to enabled) and physical termination has not been applied, or if %scsi_auto_termination is FALSE and physical termination has been applied. If auto-termination is not applicable to the HBA, the HD must not include any corresponding custom declarations in its udiprops.txt file. With such HBAs, if physical termination has not been appropriately applied, there will be no indication of anything being wrong at configuration time; any resulting improper operation of the SCSI bus will only be noticed later.
The %scsi_auto_term_internal and %scsi_auto_term_external attributes are used to provide more fine-grained control of the on-board termination for special types of configurations. These attributes only need to be requested for HBAs which have the corresponding fine-grained controls (or some useful subset thereof), and then only if the %scsi_auto_termination attribute doesn't exist. In that case, if only one of the two attributes exists, the non-existent one defaults to enabled.
2.5.2.5.2 Custom Parameters for HDs (per-PD instance)
The second category of custom attributes for HDs are Parent-Visible instance attributes. As defined in Chapter 15, "Instance Attribute Management", of the UDI Core Specification, these are attributes that the system sets on a PD instance, but are only visible to the HD. The following such attributes are defined:
These attributes must be requested by the HD during child binding. For each of these, on parallel SCSI, the attribute is expected to be programmable on the bus and should therefore not require any attribute mismatch errors as described for the attributes in Table 2-3. If attribute mismatch errors are needed for these attributes for any reason they must be indicated via a UDI_STAT_ATTR_MISMATCH status on the scsi_bind_ack, along with a call to udi_log_write detailing the mismatched attribute names and values.
If the "@scsi_max_xfer_rate" attribute exists for a given child, the HD must not attempt to negotiate with respect to that child's device for a transfer rate, in Mega-transfers per second, that is greater than the value of "@scsi_max_xfer_rate".
2.5.2.5.3 Dynamically Changeable HD Custom Parameters
Most of the HD's custom attributes can change dynamically during the operation of the HD. The following, called dynamically changeable attributes, can change at any time:
- %scsi_max_xfer_rate
- %scsi_disconnect_allowed
- %scsi_parity_checking
- @scsi_max_xfer_rate
- @scsi_disconnect_allowed
HDs must be prepared to receive a udi_usage_ind at any time indicating that one or more of these attributes have changed and then re-read them and change the corresponding operating parameters in the device.
Additionally, the following attributes may change across a hot-plug event. HDs must re-read the dynamically changeable attributes as well as the following, called hot-plug changeable attributes, during the handling of a udi_devmgmt_req of type UDI_DMGMT_RESUME:
- %scsi_initiator_id
- %scsi_bus_width
- %scsi_auto_termination
- %scsi_auto_term_internal
- %scsi_auto_term_external
- %scsi_wdtr_allowed
When re-reading, the specified attribute dependency rules still apply. So, for example, the %scsi_auto_term_internal and %scsi_auto_term_external attributes only need to be read if the %scsi_auto_termination attribute doesn't exist.
2.5.2.6 Custom Parameters for PD Drivers
The following well-known attributes must be included, if applicable to the PD or its device, as "custom" declarations in the PD's udiprops.txt static driver properties file for appropriate configuration and operation of the PD.
The "%scsi_pd_no_bus_reset" attribute must be requested by the PD before attempting to perform a BUS RESET operation. If the attribute exists and is set to TRUE, the PD must not send any BUS RESET control requests to its HD parents.
The "%scsi_pd_max_temp_bind_excl" attribute must be requested by the PD before attempting a temporary exclusive binding to an HD parent. If the attribute doesn't exist, the environment is placing no restriction on the length of time that a temporary exclusive binding can be held. If the attribute exists and is zero, such bindings are disallowed and it is illegal for the PD to request such bindings. Otherwise, the PD must not hold such a binding for longer than the specified number of milliseconds.
Warning - To avoid potential system problems the PD must minimize the length of time it holds a temporary exclusive binding and be judicious in its use even when no time limit is imposed (i.e., when the %scsi_pd_max_temp_bind_excl attribute doesn't exist).
The "%scsi_pd_wce" attribute must be requested by the PD before sending any I/O requests to the device. If the attribute exists the write cache must be enabled or disabled on the device, as indicated by the value of the attribute, prior to doing any I/O to the device.
2.5.2.6.1 Dynamically Changeable PD Custom Parameters
Most of the PD's custom attributes can change dynamically during the operation of the PD. The following, called dynamically changeable attributes, can change at any time:
PDs must be prepared to receive a udi_usage_ind at any time indicating that one or more of these attributes have changed and then re-read them and change the corresponding operating parameters in the device. Additionally, the PD must re-read the dynamically changeable attributes during the handling of a UDI_DMGMT_RESUME device management request.
2.5.3 Trace Event Bindings
The following defines the rules and conventions in the SCSI Metalanguage for the use of the metalanguage-selectable trace events (see the "Metalanguage-Selectable Trace Events" #defines in udi_trevent_t).
- UDI_TREVENT_IO_SCHEDULED
- The HD should trace at least the size of the buffer (data_buf->buf_size) and the contents of the first byte of the CDB for udi_scsi_io_req operations, or the ctrl_func field for udi_scsi_ctl_req operations, as well as the corresponding control block pointer in either case.
- UDI_TREVENT_IO_COMPLETED
- The HD should trace at least the contents of the first byte of the CDB and the udi_scsi_status_t structure (if non-zero) for udi_scsi_io_req operations, or the ctrl_func field for udi_scsi_ctl_req operations, as well as the corresponding control block pointer in either case. If an I/O request returns sense data, the trace should also include the sense key, additional sense code (ASC), and additional sense code qualifier (ASCQ) bytes. If an I/O request has an underrun, the number of bytes transferred should also be traced.
- UDI_TREVENT_META_SPECIFIC_1
- The HD should trace the point at which a bus hang is detected, and should include at least the state of the SCSI bus lines if available. Both the PD and the HD should trace the sending or receiving of enabled SCSI events (from the events listed in the udi_scsi_bind_req), and should include at least the event code.
- UDI_TREVENT_META_SPECIFIC_2,
UDI_TREVENT_META_SPECIFIC_3,
UDI_TREVENT_META_SPECIFIC_4,
UDI_TREVENT_META_SPECIFIC_5Note - All returned status values other than UDI_OK that indicate exceptional conditions must be logged and, when enabled, may also be traced, even if such events are expected.
2.6 Metalanguage State Diagram
See "Driver Instantiation" on page 24-2 of the UDI Core Specification for the general configuration sequence of UDI drivers. See "Management Metalanguage States" on page 24-37 of the UDI Core Specification for details on the Management Metalanguage states.
The following state diagram shows the SCSI metalanguage state diagram, which illustrates the set of states specific to use of the SCSI metalanguage. This same state diagram applies to both the PD and HD.
2.6.1 SCSI Metalanguage States
UNBOUND A SCSI channel in the unbound state has been established between the two regions but has not yet been initialized in those regions for general use. The PD side of the SCSI channel should initiate the SCSI bind operation when in this state.
BINDING This state occurs when the PD side of the SCSI channel has initiated a bind operation and is waiting for the HD side of the SCSI channel to complete its initialization and acknowledge that bind request.
ACTIVE This state occurs when the SCSI channel is fully bound between the two regions. The channel may be used for SCSI I/O and control operations or event indications.
BINDLOST This state occurs when the PD has bound with the HD with the UDI_SCSI_TEMP_BIND_EXCLUSIVE indicator set, and has not initiated an unbind request within the time frame allowable by the %scsi_pd_max_temp_bind_excl attribute. When this state is encountered, the HD will reject all PD I/O and control requests with a UDI_STAT_INVALID_STATE status code, and will not post SCSI events to the PD.
UNBINDING This indicates that the SCSI channel is being shut down. The PD can cause this state to be entered by issuing a udi_scsi_unbind_req. When the unbind operation is acknowledged, both the PD and the HD return to the UNBOUND state.
1As an exception to this version compatibility, version 1.0 (0x100) is not forward compatible with any other versions bearing the major number of 1; version 1.0 of the specification cannot be wholly implemented as a functional product.
| |
|
|
|
