Appendix B Handling HACB Completion Errors

The tables in this Appendix describe the completion codes in the HACB's hacbCompletion field (see Chapter 3).

Table B-1 HACB Completion Code Error Descriptions

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 Control_Info 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)

(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 shall be set to the SCSI Status Byte Code 2. 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: This is a device error. 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)
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.

When this error is detected, the CDM may spawn a thread to attempt recovery, but if the condition persists, the CDM should complete the corresponding message with device error (0x0012) as the MMCompletionCode.	The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)
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.
Device Error:

IDE/ATA

(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 3. The remaining high-order 8 bits of the lower WORD are zero extended.

NWPA support for IDE/ATA requires that the HAM read the contents of the ATA Status, Drive Head, and Error registers and pack them into the HACB's hacbCompletion field. These values should be placed during the HAM's ISR for each completed HACB request using a macro.

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.
0x8001	0x0001	Error: This is a device error. For the current HACB the HAM places the appropriate information in the HACB fields specified in the description above. The CDM determines the cause of the error by reading the bits from the HACB's hacbCompletion field corresponding to the ATA Error register.	The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)
0x0020	Drive Write Fault: This indicates a write-fault error.	The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)
0x0080	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. When this error is detected, the CDM may spawn a thread to attempt recovery, but if the condition persists, the CDM should complete the corresponding message with device error (0x00000012) as the MMCompletionCode.	The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)
0x8002	xxxx*	Time-Out 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 time-out countdown begins after the HACB is processed and sent to the device by the HAM. 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. The CDM can spawn an error handling thread to attempt to diagnose and remedy the problem by issuing priority HACBs. However, if the time-out error persists after a few remedy attempts, the CDM should complete this HACB with device error (0x00000012) as the MMCompletionCode.	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 time-out is the next one to be processed by the device when the queue unfreezes.
* xxxx = value is ignored.
Malformed Error: (0x8003) MSB=1 (0x0003) MSB=0	The HAM determined that the HACB is malformed, meaning the HACB may contain an invalid device address, a bad function code, a bad 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.
(0x8003) MSB=1	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)
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 MMCompletionCode.	The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)
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 MMCompletionCode.	The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)
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 Control_Info field before completing the HACB. When the CDM detects this error, it should complete the corresponding message with Parameter Error (0x00000016) as the MMCompletionCode and the transfer count in the HACB's Control_Info 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)
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 Control_Info field before completing the HACB. WHEN the CDM detects this error, it should complete the corresponding message with Parameter Error (0x00000016) as the MMCompletionCode and the transfer count in the HACB's Control_Info 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)
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.	The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)
0x0006	Bad Command Length: Indicates an illegal, interface-specific command length.	The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)
0x0007	Bad Command: Indicates an illegal, interface- specific command	The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)
0x0008	Bad Direction Bit: Indicates that the data direction flag in the HACB's Control_Info field, set by the CDM, is not consistent with the I/O request.	The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)
0x0009	Bad Buffer Pointer: Indicates that the buffer pointer in the HACB is illegal.	The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)
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 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	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 HAM does not freeze this device queue. (MSB=0)
0x0041	Bad HAM Info Buffer: The buffer passed to the HAM's HACB Type Zero function, HAM_Return_HAM_Info, is too small.	The HAM does not freeze this device queue. (MSB=0)
0x0042	Bad Device Info Buffer: The buffer passed to the HAM's HACB Type Zero function, HAM_Return_Device_Info, is too small.	The HAM does not freeze this device queue. (MSB=0)
0x0043	Unsupported HACB Type Zero Function: The HAM was directed to perform a HACB Type Zero function that it does not support. Since the NWPA expects all HAMs to implement HACB Type Zero functions as they apply to their respective adapters, this error is only valid if the function is clearly not applicable to a specific adapter type. For example, the function HAM_Set_IDE_Drive_Config is clearly not applicable to SCSI adapters.	The HAM does not freeze this device queue. (MSB=0)
0x0044	Unsupported Interface Type: The HAM detected that the adapter interface type specified in the HACB's HACB TYPE 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 MMCompletionCode.	The HAM does not freeze this device queue. (MSB=0)
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 MMCompletionCode.	The HAM does not freeze this device queue because there is no valid queue to freeze. (MSB=0)
0x0046	Bad DeviceHandle: The device handle contained in the HACB's DeviceHandle field does not map to any device being supported by the HAM. When the CDM detects this error, it should complete the corresponding message with Parameter Error (0x00000016) as the MMCompletionCode.	The HAM does not freeze this device queue because there is no valid queue to freeze. (MSB=0)
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 Control_Info 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 HACB Type Zero function.	The HAM does not freeze this device queue. (MSB=0)
0x0004	xxxx*	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)
* xxxx = value is ignored.
0x8005	xxxx* **	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 MMCompletionCode and deactivate the device.	The HAM must freeze this device queue. (MSB=1)
* xxxx = value is ignored
** 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 may be ignored (which is the usual case), used in HAM/CDM development, or filtered through a special adapter-knowledgeable CDM. Since adapters differ so greatly in error codes, as far as the 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 MMCompletionCode 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 MMCompletionCode.	The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)
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 MMCompletionCode.	The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)
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 MMCompletionCode.	The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)
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 MMCompletionCode.	The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)
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 re-issue the request at least once to see if the problem gets corrected. If the request is a scatter/gather request, the CDM may 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 MMCompletionCode.	The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)
0x0005 to 0x7FFF	RESERVED FOR NWPA	Ignored, No action.
0x8000 to 0xFFFF	Reserved for third-party development; undefined in the NWPA. Developers must register for these codes with Novell Labs.	Device-queue action is left to developer's discretion.
0x0007	xxxx*	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 may 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 (0x00000028) as the MMCompletionCode.	The HAM must freeze this device queue until notified by the CDM to unfreeze it at a later time. (MSB=1)
* xxxx = value is ignored.
0x8008	xxxx*	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 Control_Info 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 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 Control_Info 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)
* xxxx = value is ignored.
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.
0x0001	AEN HACB: The aborted HACB was an asynchronous event notification HACB.	(MSB=0) Device Queue is going away.
0x0000	0x0000	Successful Completion: The current scan operation completed successfully. This completion code applies to all scan cases. For Case 1 and Case 2 scans, this completion code indicates that a device responded at the specified Target ID and LUN, and the information returned in the HACB's data buffer is valid.	Not applicable
0x000A	0x0000	General Failure: Default scan-error category. The cause of the error is unknown, and any information contained in the HACB's data buffer is invalid.

This completion code applies to all scan cases.	Not applicable
0x0001	Device Not Found: No device responded at the specified Target ID and LUN. Any information contained in the HACB's data buffer is invalid.

This completion code applies to Case 1 and Case 2 scans.	Not applicable
0x0002	Bad Target ID/LUN: The Target ID and/or LUN specified in the HACB's host adapter command block was/were invalid. Any information contained in the HACB's data buffer is invalid.

This completion code applies to all scan cases.	Not applicable
0x0003	Target In Use: The target object is owned by another CDM. Therefore, the current scan request could not be executed.

This completion code applies to Case 1, Case 2, and Case 3 scans.	Not applicable
0x0004	Object Not Found: A CDM issued a Case 3 scan to remove a device object from the HAM's device list that does not exist. The object does not exist because no previous Case 1 or Case 2 scan was issued on the specified Target ID and LUN to create it. Any information contained in the HACB's data buffer is invalid.

This completion code applies to Case 3 scans.	Not applicable
Novell reserves the right to add additional completion codes.