ErrorSenseInfoStruct
Defines the data format of the HACB's auto error sense buffer.
struct ErrorSenseInfoStruct { LONG numberBytesRequested; LONG numberBytesReturned; LONG reserved[2]; BYTE errorSenseData[1]; };
When auto error sense is active for a target device, the CDM assigns the desired value in this field prior to executing the HACB request.
For SCSI, the minimum value a CDM can place in this field is 8. Otherwise, no error sense information will be returned.
The HAM sets this value when a HACB request results in an error with a check condition and the target host adapter has auto error sense turned on.
The HAM should set this field according to the following formula:
The following assumptions apply to the formula:
The CDM decides the actual size of this byte array at run-time, when it allocates the auto error sense buffer during the building of the HACB. To get an auto error sense buffer of suitable size, the CDM allocates a buffer the size of the ErrorSenseInfoStruct plus however many bytes of auto error sense data it wants returned. This amount is the value that the CDM assigns to the numberBytesRequested field; thus, this field specifies the array's total number of elements.
In building a HACB for a target device with auto error sense active, the CDM assigns the total byte length (sizeof (struct ErrorSenseInfoStruct) + numberBytesRequested) of the auto error sense buffer to the HACB's errorSenseBufferLength field.
The CDM and HAM should go through a pointer to an ErrorSenseInfoStruct to access information in the auto error sense buffer. This pointer implies an ErrorSenseInfoStruct format on the buffer's data, allowing the CDM or HAM to correctly dereference its fields. The HAM knows the full size of the buffer from the value the CDM places in the numberBytesRequested field and adding the 17 header bytes. The CDM knows exactly how much return data to read by the value the HAM places in the numberBytesReturned field.
The CDM allocates and fills in one of these buffers for each HACB request targeted to a device attached to an adapter using auto error sense. The CDM links one of these buffers to a HACB by assigning the buffer's NetWare® logical (virtual) address to the HACB's vErrorSenseBufferPtr field. The CDM might want to create a reusable pool of these buffers for the sake of performance. Additionally, the buffer must be allocated as I/O contiguous memory, and as explained under the structure's errorSenseData field presented below, the CDM can vary the size of this buffer according to the number of sense bytes it wants returned. The CDM specifies this number in the numberBytesRequested field.
The HAM copies the auto error sense data into the errorSenseData field of this buffer. Also, the HAM returns to the numberBytesReturned field, the lesser of the value in the numberBytesRequested field or the actual number of sense bytes the device will provide.
If the number of sense bytes returned by the device is fewer than what the CDM requested (numberBytesReturned < numberBytesRequested), the CDM should use the value in the numberBytesReturned field as the index for the errorSenseData array.