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

NPA_Register_HAM_Module

Registers a HAM with NWPA.

Thread Context:Non-Blocking
Requirements:This function is the first API called during HAM_Load. Additionally, the module must provide the storage locations for the outputs it receives during this call.

Syntax

    LONG NPA_Register_HAM_Module (
       LONG  *npaHandle,
       LONG   novellAssignedModuleID,
       LONG   loadHandle,
       LONG   (*HAM_Check_Option)(),
       LONG   (*HAM_Software_Hot_Replace)(),
       LONG   (*HAM_ISR)(),
       LONG   (*HAM_Execute_HACB)(),
       LONG   (*HAM_Abort_HACB)() 
       LONG   instance
       );

Parameters

npaHandle: (OUT) Receives a unique NWPA handle for the HAM module. This handle is a tag NWPA uses to track the HAM module, and it is a required argument for using the NPA APIs.
NWPA recognizes reentrant modules, meaning that a single code image of the HAM manages multiple adapters. Therefore, if a reentrant HAM calls NPA_Register_HAM_Module again to assign a new instance number to the new adapter board instance, NWPA ensures that the value output to this variable is the same for each call.
novellAssignedModuleID: (IN) Unique ID for this HAM. These IDs are assigned to a vendor upon request from Developer Services.
loadHandle: (IN) Handle that the OS assigned to the HAM at load time. The value for this parameter was passed into the HAM's load-time entry point, HAM_Load.
HAM_Check_Option: (IN) Points to the HAM_Check_Option entry point called during the parsing of load-time command line options and again at option registration.
HAM_Software_Hot_Replace: (IN) Points to the HAM_Software_Hot_Replace entry point used in dynamically updating versions of a HAM.
Hot replacement is an optional feature for a HAM. If the HAM does not support hot replacement, it should set this parameter to zero. Doing so forces NWPA to never allow hot replacement of this HAM.

HAM_ISR: (IN) Points to the HAM_ISR function, which is the HAM's Interrupt Service Routine (ISR).
HAM_Execute_HACB: (IN) Points to the HAM_Execute_HACB function, which is the HAM's main entry point for receiving HACB I/O requests.
HAM_Abort_HACB: (IN) Points to the HAM_Abort_HACB function, which is the HAM's main entry point for receiving aborts on HACB I/O requests.
instance: (IN) A HAM-generated number identifying an adapter board instance. NWPA uses this number to associate different groups of registered hardware options with a particular adapter board being managed by the HAM.
This value must be ORed with 0x00010000 if the HAM is multi processor enabled.

Return Values

The following table lists return values and descriptions.

zero	Successful and not a hot replace case.
1	Successful and hot replace case.
Other than 0 or 1	Unsuccessful.
2	The module being loaded has the same novellAssignedModuleID as a module that is already loaded.

Remarks

The driver being loaded has a novellAssignedModuleID identical to that of a driver that is already loaded.

NPA_Register_HAM_Module is used to register the HAM module with NWPA, along with the application's entry points. This function should be the first API called during the module's load-time entry point, HAM_Load. It is during the context of this API that the HAM receives its unique NWPA handle. This handle is a necessary argument for using the other NPA APIs that provide system resources to the module

NPA_Register_HAM_Module also determines if a version of a HAM currently loaded in server memory is to be hot replaced with a newer HAM version. NPA_Register_HAM_Module makes this determination by comparing the novellAssignedModuleID and the loadHandle of a newly loaded HAM with other HAMs that are already loaded. If there is a match in novellAssignedModuleID values between the newly loaded HAM and an already loaded HAM, but their respective loadHandle values differ, then NWPA determines that the newly loaded HAM is hot replacing the already loaded HAM.