1.1 Introduction

1.2 NMS OAM Overview

1.3 NMS OAM Components

1.3.1 NMS OAM Supervisor

1.3.2 Board Plug-Ins

1.3.3 Extended Management Components (EMCs)

1.4 Managed Objects

1.4.1 The Configuration Database

1.4.2 Board Identification Methods

1.5 NMS OAM and Natural Access

1.5.1 Natural Access Services

1.5.2 Natural Access Contexts

1.5.3 Event Queues

1.5.4 Natural Access Modes and NMS OAM

1.6 OAM Service Architecture

1.7 Hot Swap

1.7.1 Hot Swap Software Architecture

1.7.2 Hot Swap EMC

1.7.3 Hot Swap Manager

1.7.4 Hot Swap Drivers

1.7.5 Hot Swap Library

1.7.6 Hot Swap Driver

1.7.7 Layered Architecture of the Hot Swap Driver Under UNIX

1.1 Introduction

NMS Operations, Administration, and Maintenance (NMS OAM) service is a Natural Access extension that administers, maintains, and performs operations on NMS resources in a system. NMS OAM can manage hardware components, such as NMS boards, or software components, such as the NMS Hot Swap process. Since these components are being managed by NMS OAM, they are called managed components.

NMS OAM functionality can be accessed in either of the following ways:

• Using the OAM service API. The NMS OAM service is a standard Natural Access service, with an API similar to the APIs of other Natural Access services. This manual describes how to access NMS OAM this way.

• Using the oamsys, oamcfg, oammon, and oaminfo utilities included with the NMS OAM software. For more information on these utilities, refer to the NMS OAM System User's Manual.

This manual is targeted to developers who are using Natural Access. This manual defines terms where applicable, but assumes that the reader is familiar with the C programming language.

1.2 NMS OAM Overview

Using NMS OAM, you can:

• Create, delete, and query the configuration of a board managed component

• Start (boot), stop (shut down), and test a managed component

• Receive notifications from managed components

In addition, the OAM service functions allow you to:

• Detect boards in a system

• Perform detailed management of configuration settings

• Export or import configuration data

1.3 NMS OAM Components

NMS OAM software is made up of the following components (see Figure 1):

• NMS OAM Supervisor

• Board plug-ins

• Extended management components (EMCs)
  
  
  Figure 1. NMS Components

The following sections describe each component.

1.3.1 NMS OAM Supervisor

This component provides the main NMS OAM logic. It does the following:

• Loads all board plug-ins and EMCs when it starts up.

• Coordinates the activities of managed components.

• Manages a database containing configuration information for managed components (described in Section 1.4.1).

The NMS OAM Supervisor is an integral part of the Natural Access server process (ctdaemon). To use the NMS OAM software, Natural Access must be installed on your system, and ctdaemon must be running. To learn how to start ctdaemon, refer to Section 3.5.

1.3.2 Board Plug-Ins

NMS OAM communicates with boards through software extensions called board plug-ins, one for each board family. The board plug-ins included with NMS OAM support the following NMS PCI and CompactPCI board models: AG, CG, CX, and QX. TX boards are not supported.

When the Supervisor starts up, it loads all plug-ins that it finds. The Supervisor looks for these modules in the nms\bin directory (/opt/nms/lib under UNIX). Plug-in files have the extension .bpi.

1.3.3 Extended Management Components (EMCs)

Extended management components (EMCs) are software modules which add functionality to NMS OAM. The following EMCs are currently included with NMS OAM:

• The Hot Swap EMC allows you to insert and extract Hot Swap-compatible CompactPCI boards without powering down the system. Hot Swap improves system availability by reducing down-time due to routine configuration changes and board replacements.

• The Clock Management EMC manages H.100 and H.110 bus clock configuration.

When the Supervisor starts up, it loads all EMCs that it finds. The Supervisor looks for these modules in the nms\bin directory (/opt/nms/lib under UNIX). EMC files have the extension .emc.

1.4 Managed Objects

All components (board plug-ins and EMCs) logically exist as managed objects within NMS OAM. (See Figure 2.) A managed object is the logical representation of a managed component to NMS OAM.

Boards are also logically represented as managed objects. A board must exist as a managed object in order for NMS OAM to configure or start it.

You can use NMS OAM utilities or the OAM service to access, query, and configure any managed object. You can also create and delete board managed objects.

Figure 2. Managed Objects and Managed Components

NMS OAM can have managed objects that do not correspond to active or present managed components in the system. For example, you can have a managed object for an NMS board that is not in the chassis, although an error will result if an attempt is made to start that component. Conversely, not all NMS resources in the system may exist as managed objects within NMS OAM.

The NMS OAM Supervisor has a managed object. You can access the Supervisor managed object to query and configure various system-level parameters. For more information, refer to Chapter 11.

1.4.1 The Configuration Database

NMS OAM maintains a configuration database to facilitate the management of the components under its control. Each hardware and software managed object has its own record in the database containing configuration parameters and parameter values. (See Figure 3.)

Figure 3. NMS OAM Configuration Database

In the database, each parameter and value is expressed as a keyword name/value pair (for example, AutoStart = YES). You can query the OAM service for keyword values for any managed object. Keywords and values can be added, modified, or deleted.

1.4.2 Board Identification Methods

In the NMS OAM system, each board is referenced using these identifiers:

• A unique name.

• A board number. This is the typical way to identify a board in most NMS software products. Each board in a chassis has a unique board number.

• A unique PCI bus and slot in which the board is located.

The following secondary ID information is also available:

• A driver name/driver board ID combination. The driver name is unique among all driver names in the system. The driver board ID is unique among all boards accessed by a given driver. However, two boards accessed by different drivers may have the same driver board ID. The driver name/driver board ID together make up an ID for the board which is unique within the system.

• A serial number (if supported). This number is factory-configured, and may not be present for all boards.
  
  Figure 4. Board Identification Options

1.5 NMS OAM and Natural Access

NMS OAM is an integral part of Natural Access. Natural Access is a development environment providing standard programming interfaces for hardware-independent functions. You must have Natural Access installed on your system to build applications using the OAM service.

This section provides background information about Natural Access, and describes how the OAM service fits into the Natural Access environment. For detailed information about Natural Access, see the Natural Access Developer's Reference Manual.

1.5.1 Natural Access Services

NMS OAM is implemented as a Natural Access service. A service is a group of logically related functions. The OAM service provides operations, administration, and monitoring functions for NMS resources. Other services address other aspects of an application (for example, the Switching service controls circuit switching. The NaturalFax service provides fax functionality).

1.5.2 Natural Access Contexts

A CTA context organizes services and accompanying resources around a single processing context. To access OAM service functionality, each client application creates a CTA context and attaches the OAM service, along with any other services it requires.

The OAM service is available only to contexts created in Server or Multi mode. For more information, refer to Section 1.5.4.

1.5.3 Event Queues

An event queue is the communication path from a service to an application. A service generates events indicating certain conditions or state changes. An application retrieves the events from the event queue.

When creating a context, you specify an event queue. All events from the services on the context are sent to the event queue attached to the context.

1.5.4 Natural Access Modes and NMS OAM

Natural Access can operate in either of two configurations:

• Library. In this configuration, each application maintains a separate Natural Access programming environment. Processing resources are created, managed, and destroyed independently.

• Client/Server. In this configuration, a separate Natural Access server process (ctdaemon) is running. The server process manages common processing resources on behalf of client applications. (See Figure 5.)

NMS OAM is designed to interact with Natural Access only in its Client/Server configuration. Any contexts used by a Natural Access application to communicate with the OAM service must access Natural Access in this configuration. The service was designed this way because its fundamental purpose (to perform central management of system-wide configuration data) makes sense only in a client/server environment.

You determine which configuration Natural Access will use, and the configuration in which contexts will be created, by specifying a mode when you initialize Natural Access with ctaInitialize (see Section 3.6.2). Since NMS OAM contexts must be created in Client/Server configuration, NMS OAM applications should initialize Natural Access in Server mode.

A third mode, Multi mode, is available in Natural Access 4.0. Use this mode if your application will use Natural Access primarily in Library configuration, but must also have the option to create Client/Server contexts for NMS OAM. When Natural Access is running in Multi mode, you specify the mode (Library or Server) for each context as you create it.

To determine which mode is suitable for your application, see Section 3.6.1.

Figure 5. Natural Access Server (ctdaemon)

1.6 OAM Service Architecture

Figure 6 illustrates the architecture of NMS OAM:

Figure 6. OAM Service Architecture

The client side contains one or more CTA client applications that communicate with NMS OAM through its API, using one or more Natural Access contexts. An OAM service instance has been started on each context. Each instance communicates with the OAM Service Manager component of the Natural Access Server (ctdaemon) on the server side.

The oamcfg, oammon, and oaminfo utilities are CTA client applications. (oamsys is not, since it uses multiple calls to oamcfg to perform its functions.) For more information about these utilities, refer to the NMS OAM System User's Manual.

The server side contains the Natural Access server (ctdaemon) which has the following components:

• The OAM Service Manager. This component provides the glue logic between OAM service instances and the Supervisor.

• The Supervisor. This component manages the configuration database, board plug-ins and extended management components (EMCs).

1.7 Hot Swap

Hot Swap functionality is an integral part of the OAM service. Hot Swap is designed for use with Hot Swap-compliant boards. These boards contain a switch built into the ejector handle and a front panel Hot Swap LED. When the board is inserted, the switch signals that the board is fully seated (with the handle closed) and that software connection can be initiated. When the board is extracted, the switch signals that the operator is beginning to extract the board and that software disconnection should be initiated.

When lit, the Hot Swap LED informs the operator that software disconnection is complete and extraction is permitted. The operator can open the handle the rest of the way, ejecting the board.

1.7.1 Hot Swap Software Architecture

The following software components make up NMS OAM Hot Swap:

• The Hot Swap EMC

• The Hot Swap Manager

• The Hot Swap Library

• The Hot Swap Driver

Each of these components is illustrated in Figure 7:

Figure 7. Hot Swap Components

The following sections describe each of the Hot Swap components.

1.7.2 Hot Swap EMC

The glue logic between the Hot Swap Manager Library and the NMS OAM Supervisor is implemented as a standard NMS OAM extended management component (EMC). The Hot Swap EMC exists as a managed object in the NMS OAM database. This allows an application to access Hot Swap information programmatically.

1.7.3 Hot Swap Manager

The Hot Swap Manager maintains the states of all the Hot Swap boards in the system. Under Windows NT, the Hot Swap Manager is a native NT service.

The Hot Swap Manager coordinates the insertion and extraction of boards and informs applications through the OAM service of the corresponding state of the Hot Swap boards. The OAM service uses the Hot Swap Manager to know when to load CompactPCI boards.

The Hot Swap Manager also provides the interface between applications and device drivers that monitor Hot Swap boards.

1.7.4 Hot Swap Drivers

There are two drivers: the Hot Swap driver and the board device driver.

The Hot Swap driver handles the board-independent aspects of interfacing to the Hot Swap hardware (for example, monitoring HS_CSR).

The board device driver manages all board-specific Hot Swap aspects (for example, detecting when all channels are closed on the board).

1.7.5 Hot Swap Library

The OAM service invokes Hot Swap Manager (HSM) library functions to interface to the Hot Swap Manager.

You can also use the HSM library to write applications that monitor detailed activities of the Hot Swap process. For a complete reference of the HSM functions and details about the Hot Swap Manager operation, see the Hot Swap Manager Developer's Reference Manual on the NMS web site (www.nmss.com).

1.7.6 Hot Swap Driver

The Hot Swap driver is responsible for:

• Tracking the arrival and departure of boards with hot swap capability.

• Handling PCI configuration of boards inserted in the system.

• Handling the unconfiguration of boards being prepared for extraction.

• Setting the board's Hot Swap LED.

The Hot Swap driver is implemented differently for Windows NT and for UNIX:

• For Windows NT, the Hot Swap driver is a single native Windows NT kernel driver.

• For UNIX, the Hot Swap driver is a set of kernel drivers: PCI BIOS driver, Hot Swap hardware driver, and Resource Manager driver. One user level application, the Hot Swap Driver service, coordinates these drivers (see Section 1.7.7 for details).

The Hot Swap driver handles hardware aspects only. Any software aspects are handled by the Hot Swap Manager.

1.7.7 Layered Architecture of the Hot Swap Driver Under UNIX

In UNIX systems, the Hot Swap driver is a user-level application that coordinates a set of Hot Swap drivers. Figure 8 illustrates this architecture.

Figure 8. UNIX Hot Swap Driver Architecture

The following table describes the Hot Swap drivers:

Driver	Description
Resource Manager Driver	· Implements the interface to the OS resource database (resmgr, registry, device tree, etc.). · Used to request information about the current system configuration, allocated memory, and IRQs. · Used to update the resource database in conjunction with insertions and extractions.
PCI BIOS Driver	· Allows access to the PCI BIOS (or PCI BIOS-like) functions. · Used for PCI configuration space read and write operations.
Hot Swap Hardware Driver	· Implements the interface to the Hot Swap hardware (ENUM, on board HS_CSR, etc.). · Uses the HSBIOS driver to access PCI configuration space.