Test Unit Code Device Open and Close

Before a device can be tested by one of the test units, it must be opened for access through the interfaces defined in "Programming Interfaces for TUs and Interrupt Handlers" . Also, when testing is complete, the device must be closed and restored to its original state. The opening and closing of the device for testing presents some problems that must be accounted for in the design of the Test Unit library for the device:

• Errors may occur on the open and close operation, and these must be presented back to the calling applications in a form those applications know how to handle; that is, test unit results.
• Since the calling application will typically run through all or most of the Test Units for a given device, the performance penalty of opening and closing the device for each call to a Test Unit is prohibitive.
• Under different conditions, test units may be run in different combinations and sequences, so the calling application must be able to call the functions which do device open and close independent of the other test functions.

Test Unit Conventions

To provide a standard solution for handling the above problems, the following conventions for Test Units within a specific device library are required:

1. There must be a Test Unit number 1, referred to as TU_OPEN, which includes functions to initialize data structures, place the device in the correct state for diagnostics, and open the device for testing. It does not perform any other test functions. Any error conditions are returned as diagnostic results. The define value TU_OPEN should be used as the numerical identifier for this Test Unit.

   Specifically, TU_OPEN performs the following:

   1. Sees that the TU_INFO_HANDLE parameter is set to NULL, allocates a memory buffer to hold persistent data, and assigns TU_INFO_HANDLE to that address. For more information, see "Persistent Data and the TU_INFO_HANDLE".
   2. Reads needed device attribute information by making calls to the configuration services (pdiag_cs_get_attr), and places appropriate information into the pdiagex_dds_t structure that is passed as a parameter on the pdiag_open call.
   3. Calls pdiag_diagnose_state to place the device into a testable state.
   4. Calls pdiag_open to open the device for testing, and loads the interrupt handler, if one exists.
   5. Assuming all the above functions are performed without error, returns a value of "0" as the major return code.

2. There must be a Test Unit number 61439 (0xEFFF hex), referred to as TU_CLOSE, which closes the device and restores the device to the original state it was in prior to diagnostics being invoked. The define value TU_CLOSE should be used as the numerical identifier for this test unit.

   Specifically, TU_CLOSE performs the following:

   1. Calls pdiag_close to close the device, and unloads the interrupt handler.
   2. Calls pdiag_restore_state to return the device to the state it was in prior to TU_OPEN.
   3. Frees any memory buffers that were allocated by TU_OPEN. For the most part, the buffers that need to be freed are "secondary" persistent data buffers, pointed to by pointers in TU_INFO_HANDLE.
   4. Assuming all the above functions are performed without error, returns a value of "0" as the major return code.
   5. A valid diagnostic sequence consists of a call to Test Unit TU_OPEN, some arbitrary number of calls to Test Units other than TU_OPEN or TU_CLOSE, and then a final call to Test Unit TU_CLOSE.