3.6 Software Hot Replacement

This feature is available in NetWare 5.x and later versions.

Software hot replacement is an NWPA feature that provides for dynamic replacement of one version of a HAM driver with an updated version. Replacement is dynamic because the swap can be done without having to dismount any volumes or disrupt the I/O channel for a lengthy period of time. For an overview, see Flow of Events.

Software hot replacement applies only to HAMs from the same manufacturer, which means that the HAM being replaced (old HAM) and the new HAM must have the same novellAssignedModuleID. A block of these IDs are assigned to a manufacturer by Novell DeveloperNet Labs and must be unique (except as noted below) for each module.

The same module name must be used, with the following constraints:

  1. The major versions, minor versions, or revision numbers must be different.
  2. The following line must be added to the link.def file when linking the HAM:

    FLAG_ON 0x04000000

  3. Both the module that is being replaced and the replacement module must be reentrant.

We highly recommend that HAMs implement software hot replacement.

The objective in software hot replacement is to establish an I/O channel in the new HAM that looks logically identical to the one in the old HAM, from the perspective of NWPA. Logically identical means that the new HAM must show all the same devices, adapters, hardware resources, and handles that were used in the old HAM. Details on the I/O channel are discussed later in this section.

The method used to get configuration information is for the new HAM to pass a series of vendor-specific messages to the old HAM and the old HAM responding to each message by returning the appropriate configuration information in a buffer provided in each message. The structure of these messages is not defined in NWPA. Their structure and meaning are defined by the manufacturer of the HAMs.

The new HAM sends a vendor-specific message by calling NPA_Exchange_Message. This routine routes the message to the old HAM by calling its HAM_Software_Hot_Replace routine. The old HAM must provide this entry point for hot replace to work. The old HAM keys off of some field (or fields) in the message to determine what information is being asked for, and then copies it into the message buffer. All of this message exchanging is done during the context of the new HAM's HAM_Load (initialization) routine. After the new HAM successfully gets all the channel information it needs to be operational, it completes its HAM_Load routine by giving a return value of zero. At that point, NWPA routes I/O through the new HAM.

To understand the general details of software hot replacement, it is necessary to review the elements that constitute an I/O channel in the perspective of NWPA.

NWPA routes I/O by identifying the target device and the bus to which the target device is attached. The identification is done through a series of handles, some generated by the NWPA module and some generated by the HAM. The following is a list of these handles as discussed in this specification:

NWPA Generated

HAM Generated

npaBusHandle

hamBusHandle

 

deviceHandle

The npaBusHandle and the hamBusHandle are the handles used to identify a target bus. There are two handles given to guarantee uniqueness, and they are exchanged during HAI_Activate_Bus. As indicated above, the HAM generates one of the handles and NWPA generates the other. When NWPA passes HACBs to any of the HAM's entry points, it will pass the HAM-generated handle to identify the target bus. In the reverse direction, when the HAM indicates a target bus to any of the NWPA routines, it passes the NWPA-generated handle.

The third handle in the I/O channel is the HAM-generated deviceHandle. This is the HAM's unique identifier for a particular device on a given bus. The deviceHandle only needs to be unique within the devices attached to its bus. All HACBs targeted for specific devices will supply the corresponding HAM-generated deviceHandle.

For software hot replacement to work, the new HAM must use all the same handle values (except for the load handle) that the old HAM used so that NWPA's perspective of the channel does not change. Otherwise, the channel will be disrupted to the point where NetWare volumes associated with the channel will dismount. This is an extremely important point. Since all handle values in the I/O channel must be maintained between the swapping modules, and since the two modules are exchanging configuration information across separate, protected memory domains, these handles cannot be implemented as memory pointers.

In addition to these handles, hardware resources such as ports, IRQs, and DMA channels are components to the NWPA-HAM I/O channel. When a HAM registers for a hardware resource using NPA_Register_Options, NWPA registers the resources in behalf of the HAM. As far as NetWare is concerned, NWPA owns the resources and merely lends them to the HAM. This facilitates software hot replacement, because neither HAM has to worry about unregistering or registering hardware resources during the swap. Doing so would dissolve the I/O channel from the OS's perspective, and dismount any volumes associated with the channel. The new HAM only needs to find out what resources the old HAM was operating with and configure itself the same way. Once the hot swap is finished, NWPA redirects the use of those hardware resources to the new HAM. As far as the OS is concerned, nothing has changed.

3.6.1 Flow of Events

Figure 3-5 Flow of Events

  1. The HAM is loaded, invoking HAM_Load. At the beginning of this routine, the HAM calls NPA_Register_HAM_Module. All of the remaining steps occur during the context of the new HAM's HAM_Load routine.
  2. NWPA checks its list of existing modules to determine if this is a new load of a module or a reentrant load. A new load means that the module's loadHandle does not match the loadHandle of any other module in the list.
  3. If this is a new load, NWPA checks for a possible hot replace candidate. A hot replace candidate is an existing module that has the same novellAssignedModuleID as the module that is being loaded.
        (newModule->LoadHandle!=candidateModule->LoadHandle)&&
    (newModule->novellAssignedModuleID==candidateModule->
    novellAssignedModuleID)

    IMPORTANT:Currently, the NetWare NLM loader assigns the HAM's loadHandle and uses the name of the module to assign it. In order for hot replace to work, the name can be the same as the old HAM as long as the version number is different and the flag described in Section 3.6, Software Hot Replacement is set. Otherwise, loadHandle is not unique, and the load of the new HAM is mistakenly taken as a reentrant load of the existing HAM.

  4. If a candidate is found, NPA_Register_HAM_Module returns a value of 1.
  5. The new HAM then determines if it will do hot replace or fail its load, leaving the existing HAM in the I/O channel. If the HAM decides to do hot replace, it should check the command line for any possible options and then start requesting configuration information using its vendor-specific messaging scheme. The new HAM sends these messages to the existing HAM by calling NPA_Exchange_Message. Each message should include a buffer space sufficient to receive the requested information.
  6. The existing (or old) HAM receives these messages through its HAM_Software_Hot_Replace entry point. The old HAM determines what information is being requested and copies it into the message buffer.

    In the IDEATA.HAM example, there are fields at the beginning of the message that indicate the functions to perform. IDEATA.HAM, when it acts as a new HAM that is initiating a hot replace, first asks for all the adapters being supported on a find-first-find-next basis.

  7. The new HAM continues passing messages until it gets all the information it needs to be operational. The new HAM needs to make sure that it is using all the handle values that the old HAM used and the same hardware resources. The new HAM does not need to register for these resources because NWPA automatically redirects them to the new HAM. When the new HAM is ready to take over the old HAM, the new HAM must call NPA_Register_Options to actually perform the module switch.
  8. When the new HAM calls NPA_Register_Options, all I/O to the old HAM halts. NWPA then waits for the old HAM to normally complete all queued items to the old HAM, while storing any new requests in a postponed message queue. The old HAM must continue to complete all requests normally. When all HACBs are completed, NWPA then returns from the NPA_Register_Options call.

    During this process, the old HAM must not freeze the queue except through normal operation.

  9. After the new HAM is in place, it succeeds its HAM_Load routine by returning zero. At that point, the new HAM is in the I/O channel and handling HACB requests. The old HAM is dormant and can be unloaded by a user. It is important that the old HAM does not try to unregister its hardware resources by calling NPA_Unregister_Options during its HAM_Unload routine. NWPA manages and directs its hardware resources appropriately.