11.1 HACB Completion Codes

The tables in this section describes the completion codes in the HACB's hacbCompletion field (see Host Adapter Control Block).

Upper WORD (16 bits)

Lower WORD (16 bits)

Description

State of HAM's Device Queue

0x0000

0x0000

Successful Completion: The HACB completed without error.

The HAM does not freeze the device queue. (MSB=0)

0x8000

0x0000

Successful Completion: The HACB completed without error, but the HAM was told to freeze the queue upon completion of the current HACB by the CDM. The CDM indicated this to the HAM by setting the Freeze_Queue_Flag in the HACB's controlInfo field prior to issuing (executing) the HACB.

The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)

SCSI Device Error (0x8001) MSB=1 for all device errors

An error occurred on the device, not on the adapter or within the HAM. The lower WORD of the hacbCompletion field contains the device error code as specified by the interface. For the SCSI interface, the lower 8 bits of the field must be set to the SCSI Status Byte Code. The remaining high-order 8 bits of the lower WORD are zero extended

For the SCSI interface, the HAM places one of the following SCSI status values in the lower WORD of the hacbCompletion field when the respective event occurs.

0x8001

0x0002

Check Condition: If the HAM does not support Auto Request Sense, the CDM must issue a Request Sense command to retrieve the actual cause of the check condition.

The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)

0x8001

0x0008

Busy: The HAM must retry commands when the Status is BUSY. If after a small, finite number of retries the condition does not clear, the HAM may place the BUSY Status code in the lower WORD of the hacbCompletion field.

The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)

0x8001

0x0018

Reservation Conflict: The device has been reserved by some other initiator. The HAM returns this Status code to the CDM level, which then deactivates the device.

The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)

The following SCSI Status Byte values are not returned to the CDM. Rather, the HAM must handle their respective conditions: CONDITION MET, INTERMEDIATE, INTERMEDIATE-CONDITION MET, COMMAND TERMINATED, QUEUE FULL.

IDE Device Error (0x8001) MSB=1

An error occurred on the device, not on the adapter or within the HAM. The lower WORD of the hacbCompletion field contains the device error code as specified by the interface. For the IDE-ATA interface, the lower 8 bits of the field shall be set to the ATA Status Register Code. The remaining high-order 8 bits of the lower WORD are zero extended.

NWPA support for IDE-ATA requires that the HAM copy the contents of the ATA Status register into the HACB's hacbCompletion field. This value should be set during the HAM's ISR for each completed HACB request.

For the IDE-ATA interface, the HAM places one of the following IDE-ATA status values in the lower WORD of the hacbCompletion field when the respective event occurs. The HAM also places the values of the current bus, drive, alt-status register, and error register in the controlInfo field, according to the pattern described in HAM_Return_Device_Status (Function 0x0B).

0x8001

0x0001

0x0020

0x0080

Error: ATA equivalent of a check condition.

Drive Write Fault: A write-fault error has occurred.

Busy: The device is busy.

For the current HACB, the HAM places the appropriate information in the HACB hacbCompletion and controlInfo fields, as described above. The CDM can determine the cause of the error by reading these bits, and attempting to recover and/or reset the device, as appropriate.

In each case, the CDM must retry the command following a device recovery attempt. If the retried command fails, the CDM should complete the corresponding CDM message with Device Error (0x00000012) as the npaCompletionCode and deactivate the device.

If the error is the result of a media error, the CDM should not retry the command but should complete the CDM message with Media Error (0x00000011) as the npaCompletionCode and should not deactivate the device.

The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time (MSB=1).

0x8002

xxxx is ignored

Timeout Error: HAM timeout processing was enabled because the CDM placed a non-zero value in the timeoutAmount field of the HACB. Then, when the HAM's timeout thread (HAM_Timeout) became active, it determined that the HACB request currently being executed by the device exceeded the time allotment specified in the HACB's timeoutAmount field. The timeout countdown begins after the HACB is processed and sent to the device by the HAM. The CDM can spawn an error handling thread to attempt to diagnose and remedy the problem by issuing priority HACBs. However, if the timeout error persists after a few remedy attempts, the CDM should complete this HACB with Device Error (0x00000012) as the npaCompletionCode.

The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1) The HAM needs to ensure that the HACB positioned immediately after the HACB that caused the timeout is the next one to be processed by the device when the queue unfreezes.

Malformed Error: (0x8003) MSB=1 (0x0003) MSB=0

The HAM determined that the HACB is malformed, meaning the HACB might contain an invalid device handle, an unsupported function code, an invalid interface packet value, or a mismatch in buffer size and amount of data transferred (data overrun/underrun).The state of the device queue depends on the different conditions that qualify this general error category. Hence, the value in the upper WORD that indicates a malformed error can be 0x8003 (MSB=1) if the condition warranted the freezing of the device queue, or it can be 0x0003 (MSB=0) if the condition did not warrant the freezing of the device queue. Both conditions are listed in this table.

The following set of qualifiers indicate conditions that require the HAM to freeze the device queue. The HAM then places the qualifier that describes the malformation in the lower WORD of the hacbCompletion field. The following are possible qualifier values.

0x8003

0x0000

Unspecific Malformed HACB: The HAM has detected a command protocol that it does not recognize, and the problem is significant enough for the HAM to freeze the device queue.

The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)

0x8003

0x0001

Data Overrun - No Transfer Count Available: The HAM detects an overrun condition reported by the adapter, meaning that the buffer size allocated for the request was smaller than needed to physically transfer the data. When the CDM detects this error, it can either request sense to find out the residual byte count and recover, or it can complete the corresponding message with Parameter Error (0x00000016) as the npaCompletionCode.

The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)

0x8003

0x0002

Data Underrun - No Transfer Count Available: The HAM detects an underrun condition reported by the adapter, meaning that the buffer size allocated for the request was larger than needed to physically transfer the data. When the CDM detects this error, it can either request sense to find out the actual byte count and recover, or it can complete the corresponding message with Parameter Error (0x00000016) as the npaCompletionCode.

The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)

0x8003

0x0003

Data Overrun - Actual Transfer Count Available: The HAM detects an overrun condition reported by the adapter, meaning that the buffer size allocated for the request was smaller than needed to physically transfer the data. However, the HAM can provide the actual number of data bytes that were transferred. The HAM places this value in the HACB's controlInfo field before completing the HACB. When the CDM detects this error, it should complete the corresponding message with Parameter Error (0x00000016) as the npaCompletionCode and the transfer count in the HACB's controlInfo field as the AppReturnCode.

The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)

0x8003

0x0004

Data Underrun - Actual Transfer Count Available: The HAM detects an underrun condition reported by the adapter, meaning that the buffer size allocated for the request was larger than needed to physically transfer the data. However, the HAM can provide the actual number of data bytes that were transferred. The HAM places this value in the HACB's controlInfo field before completing the HACB. WHEN the CDM detects this error, it should complete the corresponding message with Parameter Error (0x00000016) as the npaCompletionCode and the transfer count in the HACB's controlInfo field as the AppReturnCode.

The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)

(0x0003) MSB=0

The following set of qualifiers indicate conditions that do not require the HAM to freeze the device queue. The HAM then places the qualifier that describes the malformation in the lower WORD of the hacbCompletion field. The following are possible qualifier values.

0x0003

0x0005

Bad Scatter/Gather List: The HAM either did not recognize the structure of the scatter/gather list or the list contained a bad parameter. WHEN the CDM detects this error, it should complete the corresponding message with Parameter Error (0x00000016) as the npaCompletionCode.

The HAM does not freeze this device queue. (MSB=0)

0x0003

0x0006

Bad Command Length: Indicates an illegal, interface-specific command length.

The CDM should correct the problem and resend the message, or return a Parameter Error (0x00000016) as the npaCompletionCode.

The HAM does not freeze this device queue. (MSB=0)

0x0003

0x0007

Bad Command: Indicates an illegal, interface-specific command

The CDM should correct the problem and resend the message, or return a Parameter Error (0x00000016) as the npaCompletionCode.

The HAM does not freeze this device queue. (MSB=0)

0x0003

0x0008

Bad Direction Bit: Indicates that the data direction flag in the HACB's controlInfo field, set by the CDM, is not consistent with the I/O request. The CDM should correct the problem and resend the message, or return a Parameter Error (0x00000016) as the npaCompletionCode.

The HAM does not freeze this device queue. (MSB=0)

0x0003

0x0009

Bad Buffer Pointer: Indicates that the buffer pointer in the HACB is illegal.

The CDM should correct the problem and resend the message, or return a Parameter Error (0x00000016) as the npaCompletionCode.

The HAM does not freeze this device queue. (MSB=0)

0x0003

0x000A

Bad Auto Error Sense Buffer: Indicates either a bad pointer to an auto error sense buffer or that a buffer wasn’t provided when one was required. The CDM should correct the problem and resend the message, or return a Parameter Error (0x00000016) as the npaCompletionCode.

The HAM does not freeze this device queue. (MSB=0)

0x0003

0x000B

Invalid Control Bit Set: Indicates that within controlInfo field some bits are set to invalid states. The CDM should correct the problem and resend the message, or return a Parameter Error (0x00000016) as the npaCompletionCode.

The HAM does not freeze this device queue. (MSB=0)

0x0003

0x0040

Unspecific Malformed HACB: The HAM has detected a command protocol that it does not recognize, and the problem is not significant enough for the HAM to freeze the device queue. The CDM should correct the problem and resend the message, or return a Parameter Error (0x00000016) as the npaCompletionCode.

The HAM does not freeze this device queue. (MSB=0)

0x0003

0x0041

Bad HAM Info Buffer: The buffer passed to the HAM's HACB Type Zero function, HAM_Return_Bus_Info (Function 0x00), is too small. The CDM should correct the problem and resend the message, or return a Parameter Error (0x00000016) as the npaCompletionCode.

The HAM does not freeze this device queue. (MSB=0)

0x0003

0x0042

Bad Device Info Buffer: The buffer passed to the HAM's HACB Type Zero function, HAM_Return_Device_Info (Function 0x02), is too small. The CDM should correct the problem and resend the message, or return a Parameter Error (0x00000016) as the npaCompletionCode.

The HAM does not freeze this device queue. (MSB=0)

0x0003

0x0043

Unsupported HACB Type Zero Function: The HAM was directed to perform a HACB Type Zero function that it does not support. Since NWPA expects all HAMs to implement HACB Type Zero functions as they apply to their respective adapters, this error is valid only if the function is clearly not applicable to a specific adapter type. For example, the function HAM_Set_IDE_Device_Config (Function 0x04) is clearly not applicable to SCSI adapters. The CDM should correct the problem and resend the message, or return a Parameter Error (0x00000016) as the npaCompletionCode.

The HAM does not freeze this device queue. (MSB=0)

0x0003

0x0044

Unsupported Interface Type: The HAM detected that the adapter interface type specified in the HACB's hacbType field does not match the interface type supported by the HAM. When the CDM detects this error, it should complete the corresponding message with Parameter Error (0x00000016) as the npaCompletionCode.

The HAM does not freeze this device queue. (MSB=0)

0x0003

0x0045

Bad HAMHandle: The HAM does not recognize the HAMHandle passed to its I/O entry point, HAM_Execute_HACB. When the CDM detects this error, it should complete the corresponding message with Parameter Error (0x00000016) as the npaCompletionCode.

The HAM does not freeze this device queue because there is no valid queue to freeze. (MSB=0)

0x0003

0x0046

Bad deviceHandle: The device handle contained in the HACBs deviceHandle field does not map to any device being supported by the HAM. The CDM should correct the problem and resend the message, or return a Parameter Error (0x00000016) as the npaCompletionCode.

The HAM does not freeze this device queue because there is no valid queue to freeze. (MSB=0)

0x0003

0x0047

Bad AEN Mask: The CDM issued a request to the HAM for asynchronous event notification (AEN), placing an invalid mask value in the parameter0 field of the HACB's host adapter command structure. When the HAM posts this completion code, it should also return a mask value in the HACB's controlInfo field indicating which event(s) was(were) not supported.

The CDM registers for AENs by issuing a HACB that invokes the HAM's HAM_Queue_AEN_HACB (Function 0x05) HACB Type Zero function.

The HAM does not freeze this device queue. (MSB=0)

0x0004

xxxx is ignored

Abort Completed: the HAM was issued an abort on this HACB, and now the HAM is posting completion of the abort.

The HAM does not freeze this device queue. (MSB=0)

0x8005

xxxx is ignored

Internal Adapter Error: This indicates that an adapter error occurred from which the HAM could not recover; therefore, all devices attached to this adapter can no longer be accessed. Before the HAM completes a HACB with this error code, it must reclaim all outstanding HACBs in its "issued-to-device" queues and place them back in their respective "to-be-issued" queues. When the CDM detects this error, it should complete the corresponding message with Adapter Error (0x00000013) as the npaCompletionCode and deactivate the device.

The HAM must freeze this device queue. (MSB=1)

The lower WORD (16 bits) of the hacbCompletion field can be used to provide more information as to the cause of this error. This information can be ignored (which is the usual case), used in HAM/CDM development, or filtered through a special adapter-knowledgeable CDM. Because adapters differ so greatly in error codes, as far as NWPA is concerned, the lower WORD of the hacbCompletion field is undefined for this error. If a CDM does not know how to deal with the specifics of this error, it should complete the corresponding message with Adapter Error (0x00000013) as the npaCompletionCode and deactivate the device.

General Error

(0x8006)

MSB=1

Either a miscellaneous, unknown error occurred, or an error occurred during the transport of the request to the device. Errors such as transport parity, phase mismatches, etc. should be mapped to this error value. In this error condition, the HAM places the qualifier that describes the general error in the lower WORD of the hacbCompletion field. The following are possible qualifier values.

0x8006

0x0000

Unknown: Errors that do not fit into any of the other categories are mapped to this error value. HAMs post this error value to indicate that some type of error occurred that prevented processing of the HACB. When the CDM detects this error, it should complete the corresponding message with Unknown Completion (0x00000024) as the npaCompletionCode.

The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)

0x8006

0x0001

Transport Protocol Error at Device: The HAM posts this completion code if it detects a protocol error originating at the target device. When the CDM detects this error, it should complete the corresponding message with Device Error (0x00000012) as the npaCompletionCode.

The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)

0x8006

0x0002

Transport Protocol Error at Adapter: The HAM posts this completion code if it detects a protocol error originating at the adapter. When the CDM detects this error, it should complete the corresponding message with Adapter Error (0x00000013) as the npaCompletionCode.

The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)

0x8006

0x0003

Transport Protocol Error, Origin Unknown: The HAM posts this completion code if it detects a protocol error and cannot determine if the error stems from the device or the adapter. When the CDM detects this error, it should complete the corresponding message with Unknown Completion (0x00000024) as the npaCompletionCode.

The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)

0x8006

0x0004

General Media Error: The HAM posts this completion code when it detects a problem in completing a request, but the problem is not due to a device error or an adapter error. When the CDM detects this error, it should reissue the request at least once to see if the problem gets corrected. If the request is a scatter/gather request, the CDM might want to break up the scatter/gather list into individual requests, although this action is not required of the CDM. If the problem persists, the CDM should complete the corresponding CDM message with Media Error (0x00000011) as the npaCompletionCode.

The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)

0x8006

0x0005

Resource Allocation Error: The HAM was unable to allocate the necessary resources to execute this request. The Request should be retried later; otherwise, return with an ERROR_MESSAGE_POSTPONED Error. If the problem persists, the CDM should complete the corresponding CDM message with Message Postponed (0x00000002) as the npaCompletionCode.

The HAM should not freeze the queue.

0x8006

0x0006 to 0x7FFF

RESERVED FOR NWPA

Ignored, No action.

0x8006

0x8000 to 0xFFFF

Reserved for third-party development; undefined in NWPA. Developers must register for these codes with Developer Services.

Device-queue action is left to the developer's discretion.

0x8007

xxxx is ignored

Device Not Active: This error is posted to the HACB if a device goes inactive during the course of issuing requests to it. For example, the device might time out while the adapter is trying to select it. When this error is detected, the CDM should complete the corresponding message with I/O error (0x00000012) as the npaCompletionCode.

The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)

0x8008

xxxx is ingored

Asynchronous Event Notification (AEN): This value is posted to the HACB when the HAM notifies the CDM that an asynchronous event, which the CDM registered for, has occurred. The HAM posts a bit mask value indicating which event occurred to the HACB's controlInfo field. Examples of asynchronous events are bus resets, device resets, device attentions, etc. The CDM registers for asynchronous event notification by issuing a HACB that invokes the HAM's HAM_Queue_AEN_HACB (Function 0x05) HACB Type Zero function.

When this notification HACB is detected, the CDM determines the event by reading the bit mask returned in the HACB's controlInfo field. The CDM should either reuse the AEN HACB to register for future events or return the HACB to the message pool by calling CDI_Return_HACB. For either case, the CDM should follow up by doing whatever it deems necessary to recover from the state caused by the event.

The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)

HAM Abort Due to Unload

(0x0009)

MSB=0

The HAM is being unloaded; therefore, it is aborting any stray HACBs that were not aborted by the system. In this error condition, the HAM places the qualifier that describes the category of the aborted HACB in the lower WORD of the hacbCompletion field. The following are possible qualifier values.

0x0009

0x0000

I/O or Control HACB: The aborted HACB was a request to execute a normal I/O or control function. When the CDM detects this error it should return the HACB to the system pool using CDI_Return_HACB.

(MSB=0) Device Queue is going away.

0x0009

0x0001

AEN HACB: The aborted HACB was an asynchronous event notification HACB.

(MSB=0) Device Queue is going away.

Novell reserves the right to add additional completion codes.