DeviceInfoStruct
Contains specific information about a device attached to a host adapter bus.
typedef struct DeviceInfoStruct { LONG deviceHandle; BYTE deviceType; BYTE unitNumber; BYTE busID; BYTE cardNo; LONG attributeFlags; LONG maxDataPerTransfer; LONG maxLengthSGElement; BYTE maxSGElements; BYTE reserved[2]; BYTE elevatorThreshold; LONG maxUnitsPerTransfer; WORD haType; union { struct { BYTE transferPeriodFactor; BYTE offset; } SCSI; struct { BYTE reserved[2]; } other; } timingInfo; union { struct InquiryInfoStruct inquiryInfo; struct IdentifyInfoStruct identifyInfo; } info; } DeviceInfoDef;
NWPA treats the value in this field as a byte value.
If a transfer size limit exists for the adapter, the HAM must place the byte limit in this field and set the Max_Data_Per_Transfer_Flag.
If the adapter can handle any transfer size the bus protocol supports, the HAM should set this field to zero and clear the Max_Data_Per_Transfer_Flag.
If the Elevator_Threshold_Flag is cleared, any value in this field is ignored.
This field has a minimum of 2 and defaults to 3. This value can be adjusted dynamically using HAI_Object_Update.
For a more detailed explanation, see the Remarks section for this structure.
If a unit transfer limit exists for the adapter, the HAM must place the unit limit in this field and set the Max_Units_Per_Transfer_Flag.
If the adapter can handle any unit transfer amount the bus protocol supports, the HAM should set this field to zero and clear the Max_Units_Per_Transfer_Flag.
Value |
Description |
---|---|
00h |
Asynchronous transfer. |
FFh |
Infinite (No limit to the number of outstanding pulses, which means that memory is fast enough to keep up with synchronous transfer). |
This field applies to SCSI devices only and is not used for other device types, and is valid only if the Timing_Info_Flag is set.
The HAM maintains an instance of this structure for each device it supports and is responsible for filling in field information when it receives a HAM_Return_Device_Info (Function 0x02) command. The HAM determines the information for some of the fields by probing the hardware (such as unitNumber, busID, etc.). The information for the remaining fields (such as deviceHandle) is generated by the HAM.
The HAM uses the information in this structure to report a device and set its attributes.
The CDM uses this structure to obtain device information to determine if it will bind to the device. When a device comes online that is of the type for which a CDM has registered, the Media Manager calls that CDM's CDM_Inquiry, passing it a pointer to this structure. It is from this structure that a CDM can determine a device's type and obtain its handle for routing I/O.
The elevatorThreshold field . In NWPA, an elevator refers to the way requests are moved up and down. After NWPA receives a request, it places the request into its elevator in LBA order (elevator sorting). When NWPA notices that the LBA ranges of two requests are consecutive and the target adapter driver has indicated that it supports the scatter/gather action, it attempts to combine them into a single request.
Simultaneously, NWPA checks the number of requests that have been sent to the particular device and have not yet been completed (outstanding requests) to ensure (if possible) that this number meets the amount specified by the driver's elevatorThreshold value for this device. This value represents the maximum number of requests that NWPA keeps outstanding at the HAM driver and might more properly be defined as a device request threshold. If the number of outstanding requests falls below the elevator threshold level and there are requests pending in the elevator, NWPA sends the HAM driver enough requests to meet the elevator threshold or until the elevator is exhausted, whichever comes first. The elevator threshold was implemented primarily for RAID and adapters or devices that support command pipelining.
If the elevator threshold is set too high, it might not be possible to combine requests because so many requests are being sent to the driver. However, leaving the requests in the elevator for as long as possible increases the opportunity for NWPA to create scatter/gather requests. Because it is more cost effective for a driver to process a single, large request than many smaller requests that total the same data transfer size (due to error checking, bookkeeping, general request handling, and the amount of ISR time in which interrupts are disabled), you should allow NWPA as many scatter/gather opportunities as possible.
Conversely, the elevator threshold should be set to the number of requests that the adapter and HAM driver can process simultaneously for the particular device. If the elevator threshold is set too low, the adapter might spend unnecessary idle time while waiting for requests to process (which is referred to as starving the adapter).
Because the optimum value of the elevator threshold is dependent upon adapter capabilities, NWPA allows the adapter driver to specify this value. You might need to use various combinations of reads and writes in real-world configurations and data sets to discover the best value.