6.1 Introduction

6.2 Hot Swap Operation

6.2.1 Closing Resources

6.3 Hot Swap Utilities

6.3.1 Initiating Insertion and Extraction

Using the hsmon Utility

Using the Board.<boardname>.Command Keyword

6.3.2 Debugging with the Hot Swap Manager

6.4 Hot Swap State Machine

6.4.1 Determining the Hot Swap State of a Board

6.5 Hot Swap Events

6.5.1 Handling Surprise Extraction

6.1 Introduction

The Natural Access OAM service receives event notification for board insertion or impending board extraction of all Hot Swap boards in the chassis. All Hot Swap events are sent to the queues on which the OAM service is opened.

6.2 Hot Swap Operation

When a Hot Swap board is inserted:

1. The Hot Swap driver software assigns resources to the board and initializes the configuration space registers.

2. Once the Hot Swap driver successfully configures the board, it sends notification to the Hot Swap Manager.

3. The Hot Swap Manager notifies the Hot Swap EMC to prepare the board.

4. The Hot Swap EMC directs the OAM service to initialize the board.

5. The Hot Swap EMC notifies the Hot Swap Manager that the board is prepared.

6. Once board initialization is complete, the Hot Swap Manager sends an event through the Hot Swap EMC to Natural Access applications, indicating that the board is ready.

The board is ready for use by Natural Access applications.

When the ejector handles are opened:

1. The Hot Swap driver notifies the Hot Swap Manager.

2. The Hot Swap Manager sends an event through the Hot Swap EMC to Natural Access applications, indicating that the board is requesting extraction.

3. Applications should close all channels to the board. This is accomplished by closing CTA contexts associated with the board. (For more information, see Section 6.2.1.)

4. The board device driver notifies the Hot Swap Manager when all channels are closed.

5. The Hot Swap Manager notifies the Hot Swap driver to release system resources allocated to the board (such as address space).

6. The Hot Swap driver unconfigures the board and turns on the Hot Swap LED to inform the operator that the board can be safely removed.
   
   
   Figure 14. Natural Access Hot Swap Operation

6.2.1 Closing Resources

The following table lists the actions required for specific Natural Access services in order to close resources to a board requesting removal:

For this service...	To release board resources, you must...
ADI service	Close the service.
Natural Call Control (NCC) service	Close the service.
Switching service (SWI)	Close the switch handle.
NaturalFax service (NFX)	Close the service.
Digital Trunk Monitor service (DTM)	Stop monitoring all trunks on the board.
ISDN service	Close the service.

There are no timeouts or other time-related limitations for releasing resources. However, resources should be released as soon as possible since some operators may remove boards within a few seconds of opening the ejector handles.

Once all resources for the board have been released, the Hot Swap LED on the board indicates that the board can be removed.

6.3 Hot Swap Utilities

The following utilities are provided to assist you in developing Hot Swap applications:

Program	Description
hssrv	Hot Swap Driver service (UNIX only)
hsmgr	Hot Swap Manager
hsmon	Utility to monitor the Hot Swap Manager. Can also initiate management-driven insertion and extraction.
biostest	Utility to verify that the PCI BIOS is Hot Swap compatible

6.3.1 Initiating Insertion and Extraction

You can initiate insertion or extraction in software, using

• The hsmon utility, or

• The Hot Swap EMC managed object keyword Board.<boardname>.Command.

These actions correspond to the user actions of opening and closing the board ejector handles.

Using the hsmon Utility

To start hsmon in console mode, enter:

hsmon

Once hsmon is started, you can initiate extraction by entering:

e bus,slot

... where bus and slot are the PCI bus and slot location of the board.

To initiate insertion, enter:

i bus,slot

Using the Board.<boardname>.Command Keyword

To initiate extraction, set the keyword as follows:

Board.<boardname>.Command=Extract

... where <boardname> is the name of the board to extract.

To initiate insertion, set the keyword as follows:

Board.<boardname>.Command=Insert

Board.<boardname>.Command is a write-only keyword: you cannot query it to learn if a board is inserted or extracted. To determine the Hot Swap state of a board, use Board.<boardname>.State.

For details on Hot Swap EMC managed object keywords, refer to Chapter 12.

6.3.2 Debugging with the Hot Swap Manager

For debugging purposes, you can use the hsmgr utility to run the Hot Swap Manager in console mode. In this mode, Hot Swap Manager messages are displayed as boards are inserted and extracted. To learn more about the hsmgr utility, refer to the NMS OAM System User's Manual.

6.4 Hot Swap State Machine

A managed board can be in any of the following Hot Swap states (see Figure 15):

State	Description
Extracted	The board is not present in the chassis.
OffLine	The board is present, but is not yet configured on the PCI bus.
OnLinePending	The board is being started.
Failed	The board start attempt failed.
OnLine	The board start attempt succeeded. The board can now support normal operation.
OffLinePending	The board's ejector handles were opened, and the system is preparing to allow the board to be extracted.
Unsupported	The board does not support Hot Swap.

Figure 15. Hot Swap State Machine

6.4.1 Determining the Hot Swap State of a Board

To determine the current Hot Swap state of a board:

1. Open the Hot Swap EMC managed object, using oamOpenObject. The managed object name is hotswap.emc.

2. Use oamGetKeyword to get the value of the Board.<boardname>.State keyword, where name is the board name of the board (for example, Board.MyBoard.State). The value is a string containing one of the state names listed in Section 6.4 (for example, OnLine).

If a board does not support Hot Swap, the returned state is always Unsupported.

For details on Hot Swap EMC managed object keywords, refer to Chapter 12.

6.5 Hot Swap Events

After the OAM service is initialized, a client application can receive Hot Swap events in the associated queues.

To determine the name of the managed object associated with a Hot Swap event, examine the OAM_MSG structure that the buffer field in the CTA_EVENT structure points to. The name of the managed object is appended to the OAM_MSG structure. The dwOfsSzName field in the OAM_MSG structure indicates an offset to the name. For more information, refer to Section 2.4.

Event	Description
HSWEVN_BOARD_REMOVED	Occurs when the board is physically extracted from the chassis. The state changes from OffLine to Extracted.
HSWEVN_BOARD_INSERTED	Occurs when a board is physically inserted. No board resources are yet available for the application. The state changes from Extracted to OffLine, and the Hot Swap driver starts to configure the board on the PCI bus. If the board was successfully configured on the PCI bus, the application receives the HSWEVN_ONLINE_PENDING event and the state changes to OnLinePending. Otherwise, the application receives HSWEVN_PCI_CONFIG_FAILED and the state stays OffLine.
HSWEVN_ONLINE_PENDING	Occurs when the Hot Swap manager creates a device instance for the board and notifies the OAM service to boot it. The state changes to OnLinePending. If the device instance is successfully created and the board is booted, the application receives HSWEVN_BOARD_READY and the state changes to OnLine. Otherwise, it receives HSWEVN_PREPARATION_FAILED and the state changes to Failed. If extraction was initiated by hsmon or with the Board.boardname.Command keyword, and the board handles are open in the Failed state, the application receives HSWEVN_BOARD_OFFLINE and the state changes to OffLine. If insertion was initiated in the Failed state by hsmon or with the Board.boardname.Command keyword, the application receives HSWEVN_ONLINE_PENDING and the process repeats as previously described.
HSWEVN_PCI_CONFIG_FAILED	Occurs when the board enters the OffLine state and the PCI configuration process has failed. There are three ways to make another configuration attempt: · Open and close the handles on the board · Initiate insertion from hsmon. (See Section 6.3.1.) · Initiate insertion using the Board.boardname.Command keyword. (See Section 6.3.1.)
HSWEVN_PREPARATION_FAILED	The application receives this event in the OnLinePending state when the device instance creation or booting has failed. The state changes to Failed. There are three ways to retry booting: · Open and close the handles on the board · Initiate insertion from hsmon. (See Section 6.3.1.) · Initiate insertion using the Board.boardname.Command keyword. (See Section 6.3.1.) If extraction was initiated by hsmon or with the Board.boardname.Command keyword, and the board handles are open in the Failed state, the application receives HSWEVN_BOARD_OFFLINE and the state changes to OffLine. If insertion was initiated in the Failed state by hsmon or with the Board.boardname.Command keyword, the application receives HSWEVN_ONLINE_PENDING and the preparation process repeats. A board boot will fail with this event if the Supervisor keyword AutoStartEnabled or the board keyword AutoStart is set to No.
HSWEVN_BOARD_OFFLINE	Occurs when the board goes to the OffLine state and can be extracted. If the board was removed from the OffLinePending state without waiting for HSWEVN_BOARD_OFFLINE (surprise extraction), then the HSWEVN_BOARD_REMOVED event immediately follows.
HSWEVN_BOARD_READY	The application receives HSWEVN_BOARD_READY if the board was inserted and successfully configured and booted by the OAM service. The state of the board changes to OnLine. After receiving this event, an application can freely use an inserted board. All resources are accessible.
HSWEVN_REMOVAL_REQUESTED	Occurs when the ejector handles are opened or extraction is initiated from hsmon. Warns the application that the board will be removed. After receiving this event, an application must close all resources associated with the board. The state changes to OffLinePending. When an application closes all resources, it receives HSWEVN_BOARD_OFFLINE and the state changes to OffLine.

6.5.1 Handling Surprise Extraction

Surprise extraction occurs when the user opens the ejector handles and extracts a board before the Hot Swap LED is turned on. When this occurs, the event notifying closing the service (or CTA context) may not be received.

CTA contexts that cannot be closed should be ignored. Attempts to use them (or close them) cause an error: CTAERR_INVALID_SEQUENCE.

The following scenario describes how surprise extraction can be detected by a Natural Access application:

1. The application receives the HSWEVN_REMOVAL_REQUESTED event and begins closing all context or services on the board that generated the event.

2. The application receives the CTAEVN_DESTROY_CONTEXT_DONE event or the CTAEVN_CLOSE_SERVICES_DONE event, depending on which CTA function was used to close services on the board. The application saves information for each context if the close/destroy event is received.

3. The HSWEVN_BOARD_OFFLINE and/or the HSWEVN_BOARD_REMOVED events occur. The application checks if all contexts have received the close/destroy event. If some contexts are in the pending state, the application should not try to use them again.