# Starting, stopping, and testing boards

Applications use NMS OAM service functions to start, stop, and test boards.

## Starting boards

A board must exist as a managed object before you can start it using NMS OAM.

Use oamStartBoard to start a board. Pass the context handle of the host managing the board and the name of the board to start. To start all boards in a resource host at once, pass NULL as the name. To start boards on multiple resource hosts, invoke this function at least once per host.

oamStartBoard is an asynchronous function that sends a return code to the application indicating if it was successfully initiated. If the return value is SUCCESS, the actual results of the board-starting attempt arrive later as events. As the Supervisor attempts to start each board, it returns OAMEVN_STARTBOARD_DONE to the application. The value field returned with the event indicates if the board started successfully:

- OAM_REASON_FINISHED indicates that the board started successfully.

- OAM_REASON_FAILED indicates that the board start attempt failed.

Further information is available in the OAM_MSG message buffer (in its text portion), as well as in other alert notifications generated during the start process.

## Stopping boards

A board must exist as a managed object before you can stop it using NMS OAM.

Use oamStopBoard to stop one or more boards on a resource host. Pass the context handle of the host managing the board and the name of the board to stop. To stop all boards in a resource host at once, pass NULL as the name. To stop boards on multiple resource hosts, invoke this function at least once per host.

oamStopBoard is an asynchronous function that sends a return code to the application indicating if it was successfully initiated. If the return value is SUCCESS, the results of the board stop attempt arrive later as events. When a request to stop a board is made, the Supervisor generates OAMEVN_STOPBOARD_REQ to inform all registered clients that the board will be stopped in 150 ms. This event allows applications to perform clean up before the board is stopped. As the Supervisor attempts to stop each board, it returns OAMEVN_STOPBOARD_DONE to the application. The value field returned with the event indicates if the board stopped successfully:

- OAM_REASON_FINISHED indicates that the board stopped successfully.

- OAM_REASON_FAILED indicates that the board stop attempt failed.

Further information is available in the OAM_MSG message buffer (text portion), as well as in other alert notifications generated during the board stop attempt.

Note: oamStopBoard stops boards regardless of any tasks they are currently performing. To avoid problems, ensure that a board is idle before stopping it.

## Testing boards

Once a CG board is started, a client application can test it and report results. Three levels of tests can be performed on a board:

- A basic test (test level 1).

- An extended test (test level 2). This is the test level automatically run on powerup.

- An exhaustive test (test level 3). Level 3 tests can take time to run.

A client application can use oamTestBoard to test one or more CG boards. Pass this function the following information:

- A context handle to the resource host on which NMS OAM is managing the board.

- The name of the board to test. To test all boards in a resource host at once, pass NULL as the name.

- A 32-bit mask describing the test level to perform and the board components to test.

To test boards on multiple resource hosts, invoke oamTestBoard at least once per host.

Note: Testing can interrupt current board activities. For this reason, do not use a board for any other operations during testing.

### Test level bit mask

For CG boards, the bits in the test level bit mask are interpreted as follows:

- Bit 0 (0x0): if set, oamTestBoard scans all testable on-board components and lists them to stdout. If bit 0 is not set, no list is generated.

- Bits 1 (0x2) through 3 (0x8) indicate the level of test to perform:

  Bit | Test
  --- | ---
  1 (0x2) | Perform test level 1 on specified components.
  2 (0x4) | Perform test level 2 on specified components.
  3 (0x8) | Perform test level 3 on specified components.

- Bits 4 (0x10) through 7 (0x80) are reserved.

- Bits 8 (0x100) through 15 (0x8000) indicate the components to test at the test level indicated using bits 1 through 3. The following table lists the components specified by each bit and the tests performed on the components depending upon the test level:

  Bit | Component tested
  --- | ---
  8 (0x100) | PCI bridges
  9 (0x200) | On-board CPU chips
  10 (0x400) | DSP chips
  11 (0x800) | Framer chips
  12 (0x1000) | Ethernet chips
  13 (0x2000) | HMIC chips
  14 (0x4000) | Memory
  15 (0x8000) | HDLC chips

- Bits 16 (0x10000) through 29 (0x20000000) are not used.

- Bit 30 (0x40000000): if set, all tests immediately stop if an error is reported. If not set, an error does not stop ongoing tests.

- Bit 31 (0x80000000): if set, status information for each component test is reported in OAMEVN_ALERT_INFO events. If not set, status information is not reported.

Here are some examples:

dwOptions setting | Test performed
--- | ---
0x103 | Test level 3 of PCI bridges only.
0x301 | Test level 1 of PCI bridges, on-board CPU chip, and DSP chips.
0x80000301 | Test level 1 of PCI bridges, on-board CPU, and DSPs. Displays status information and test information for each component tested.

oamTestBoard is an asynchronous function that sends a return code to the application. A return value of SUCCESS indicates if the function was successfully initiated. As the Supervisor attempts to test each board, it returns OAMEVN_TESTBOARD_DONE to the application. The value field returned with the event indicates if the board tested successfully:

- OAM_REASON_FINISHED indicates that the board tested successfully.

- OAM_REASON_FAILED indicates that the board test attempt failed.

Further information is available in the OAM_MSG message buffer (in its text portion), as well as in other alert notifications generated during the test attempt if bit 31 is set in the test bit mask.