Novell Documentation: Storage Architecture Components (incl. Media Manager & NWPA)

HAM_Abort_HACB

Aborts HACB requests received by a HAM.

Thread Context:Non-Blocking, Interrupts disabled

Syntax

    LONG HAM_Abort_HACB (
       LONG                hamBusHandle,
       struct HACBStruct  *HACB,
       LONG                flag
       );

Parameters

hamBusHandle: (IN) NWPA passes the value of this parameter, which is the HAM-generated handle to the target bus instance the HAM is managing. From this handle, the HAM must be able to locate its list of devices attached to the bus. The HAM passed this parameter to HAI_Activate_Bus when the bus was activated.
HACB: (IN) NWPA passes a pointer to the HACB request that is to be aborted. See Host Adapter Control Block for a definition and description of this structure.
flag: (IN) NWPA passes the value of this parameter. The value of this parameter indicates the type of abort to perform. Its possible values are:

Value	Description
0x00000000	This value tells the HAM to unconditionally abort the HACB even if it has already been sent to the device.
0x00000001	This value tells the HAM to conditionally abort the HACB if aborting entails only the unlinking of the HACB from the device queue. This is a clean abort.
0x00000002	This value tells the HAM to check if the HACB can be cleanly aborted, but not to perform an abort.

Return Values

The following table indicates the proper return value associated with each input flag value:

Input Flag —Return Value	Unconditional Abort 0x00000000	Conditional Abort 0x00000001	Check Abort Status 0x00000002
0	Indicates the HACB was cleanly aborted. The HCAB was completed with the Abort completion code within the context of this function.	Same as Unconditional Abort.	Indicates a clean abort if an abort was to be issued on the HACB.
-1	Indicates that the HACB could not be aborted cleanly within the current thread context. The HAM flags the HACB and abort it later during its ISR. This means the HAM completes the HACB with the Abort completion code in the ISR.	Indicates that the HACB could not be aborted cleanly during the context of this function. Therefore, the HAM took no action on the HACB.	Indicates a dirty abort if an abort was to be issued on the HACB.
-2	The HAM could not find the target HACB. Essentially, the HAM lost the HACB request. As a result of the HAM reporting the lost HACB, NWPA abends the server to prevent possible data corruption.

Remarks

HAM_Abort_HACB is the HAM's entry point for aborting I/O requests, and it is a non-blocking function. This function is registered with NWPA during NPA_Register_HAM_Module.

NWPA passes three arguments to HAM_Abort_HACB. The first two arguments are exactly the same as those passed to HAM_Execute_HACB. The third argument is the flags parameter, and its value indicates the conditions that determine the abort type.

When an unconditional abort is indicated, HAM_Abort_HACB is required to cancel the indicated HACB request no matter what. If the HACB is currently in the device queue, the abort merely entails unlinking the HACB from the queue, placing the abort code (0x0004) in its hacbCompletion field, calling HAI_Complete_HACB, and returning a zero. This abort case is referred to as a clean abort. If the HACB has already been sent to the device, then the value in flags must be visible to HAM_ISR so that it can abort the HACB request even after it was processed by the device.

NWPA guarantees that aborts are done during a single thread with interrupts disabled; therefore, no new requests are pulled from the device queue and issued to the device during an abort sequence. This ensures that a calling process can issue a clean abort check, and if the abort can be done cleanly, issue the abort without entering a critical-race window where the request gets sent to the device somewhere between the check request and the abort request.