Diagnostics Support

26

It is recommended, but not required, that UDI drivers support some level of diagnostics capability. The following recommendations provide a framework for executing diagnostics tests and reporting the results, but the semantics and descriptions of the tests are necessarily specific to the driver and adapter being tested. In usage, these tests will probably be executed from an application that will assist in directing the user to configure the hardware, run the tests, and interpret the results.

26.1 Diagnostics State

Since diagnostics tests may be destructive to the state of the device, and normal device operation may cause a diagnostic to report an erroneous failure on a functional device, the diagnostic test sessions are bracketed by UDI_GIO_OP_DIAG_ENABLE and UDI_GIO_OP_DIAG_DISABLE requests. The test session must start by the driver receiving a UDI_GIO_OP_DIAG_ENABLE request. If the driver is in a state such that either running diagnostics tests might cause the device to lose state or data, or continued normal operation of the device might cause a spurious failure of a diagnostic test, the driver must reject the request with a status of UDI_STAT_BUSY until such time as it is in a state to run the diagnostics. For example, a network device driver may reject an attempt to run diagnostics while any network interface is enabled. Other devices may need to be taken completely offline or be unbound from child devices. In most cases, external action beyond the control of the driver needs to be taken before diagnostics can be run. The driver is only responsible for answering the question "is it safe to run diagnostics?".

If the device does not support any diagnostics capability, it must return a status of UDI_STAT_NOT_SUPPORTED to the UDI_GIO_OP_DIAG_ENABLE request.

When a driver receives the UDI_GIO_OP_DIAG_ENABLE request and it is in a state to run its defined set of diagnostics tests safely, it will acknowledge the request with a status of UDI_OK and set its internal state to prevent the initiation of any activities that might not complete successfully due to the execution of diagnostics tests or that might interfere with the results of the diagnostics tests. For example, a network driver currently running diagnostics might refuse to allow any network interfaces to be enabled until the tests are concluded. Other devices might refuse new child bindings. Once the driver has agreed to allow the diagnostics session to begin, it must not allow normal activities that would interfere with diagnostics (or vice versa) to resume until it has received the UDI_GIO_OP_DIAG_DISABLE request.

If a driver receives an UDI_GIO_OP_DIAG_RUN_TEST request without first having responded to a UDI_GIO_OP_DIAG_ENABLE request with UDI_OK, the driver is not in the proper state to run diagnostics and must respond with a status of UDI_STAT_INVALID_STATE.

If a driver receives another UDI_GIO_OP_DIAG_ENABLE request after having responded to a UDI_GIO_OP_DIAG_ENABLE request with UDI_OK but without an intervening UDI_GIO_OP_DIAG_DISABLE, the driver is not in the proper state to enter diagnostics mode and must respond to the UDI_GIO_OP_DIAG_ENABLE with a status of UDI_STAT_INVALID_STATE.

When the driver receives a UDI_GIO_OP_DIAG_DISABLE request, it must clear the internal state set by UDI_GIO_OP_DIAG_ENABLE, terminate any tests running with a status of UDI_STAT_ABORTED, and prepare the device to resume normal operations. The driver must always return a status of UDI_OK to a UDI_GIO_OP_DIAG_DISABLE request, regardless of driver state.

NAME udi_gio_op_t (Diagnostics)

Diagnostics control operations

SYNOPSIS

#include <udi.h>

typedef udi_ubit8_t udi_gio_op_t;
 
/* Diagnostics values for udi_gio_op_t */

#define UDI_GIO_OP_DIAG_ENABLE   1

#define UDI_GIO_OP_DIAG_DISABLE  2

#define UDI_GIO_OP_DIAG_RUN_TEST \

			        (3 | UDI_GIO_DIR_READ)
 

DESCRIPTION The following optional Generic I/O standard operations are defined to support diagnostics operations on drivers. These supplement the operations defined for udi_gio_op_t.

UDI_GIO_OP_DIAG_ENABLE is used to enable diagnostics mode for a particular device. If the device is in a state where it can safely run diagnostics, the driver shall return a status of UDI_OK and set its state to reject any attempts at normal device usage with a status of UDI_STAT_BUSY until the driver receives a UDI_GIO_OP_DIAG_DISABLE request. If the device is not in a state where it is safe to run diagnostics, the driver must respond to the UDI_GIO_OP_DIAG_ENABLE request with a status of UDI_STAT_BUSY. If the device does not support any diagnostics capability, it must return a status of UDI_STAT_NOT_SUPPORTED. If the device is currently in its internal diagnostics mode, it must reject any subsequent UDI_GIO_OP_DIAG_ENABLE requests with a status of UDI_STAT_INVALID_STATE.

No data payload is used with this operation, so data_buf must be NULL.

UDI_GIO_OP_DIAG_DISABLE clears the driver internal state set by a previous UDI_GIO_OP_DIAG_ENABLE operation and terminates any diagnostics tests that may be running. The only status returned is UDI_OK. At the conclusion of this operation the device is assumed to be ready for normal usage.

No data payload is used with this operation, so data_buf must be NULL.

UDI_GIO_OP_DIAG_RUN_TEST causes the driver to execute a selected diagnostics test. Drivers that support diagnostics must support at least one test. Test numbers start from zero. By convention, the lower-numbered tests are usually device self-tests which require no intervention, while the higher-numbered tests are more complicated tests which may require operator intervention to prepare for or recover from the test. Test number zero must be a self-test.

In the udi_gio_xfer_ack returned in response to the UDI_GIO_OP_DIAG_RUN_TEST operation, the status may be UDI_OK if the test passed, UDI_STAT_HW_PROBLEM if the test failed due to a hardware problem, UDI_STAT_NOT_SUPPORTED if the specified test is not supported on this device, UDI_STAT_ABORTED if the test was aborted, or UDI_STAT_INVALID_STATE if the driver is not in the proper state for running diagnostics.

In the case of UDI_STAT_HW_PROBLEM, the buffer pointed to by data_buf is filled in with a message string containing additional information to help isolate the failure to a specific field replaceable unit. The data_buf->buf_size field must be set to the length of that string (without any null terminator). The buffer returned in the data_buf parameter of udi_gio_xfer_ack must be the same buffer as received in the udi_gio_xfer_req or a direct decendent of that buffer (i.e. a dst_buf of the original buffer as processed by udi_buf_copy or udi_buf_write).

STATUS VALUES UDI_OK - The operation completed successfully.

UDI_STAT_BUSY - The device or driver is not in a safe state for diagnostics.

UDI_STAT_NOT_SUPPORTED - The specified test number, or diagnostics in general, are not supported by this driver.

UDI_STAT_INVALID_STATE - The driver is not in diagnostics mode when requestes to run tests or disable diagnostics, or is already in diagnostics mode when requested to enable diagnostics.

UDI_STAT_HW_PROBLEM - The requested diagnostics test failed.

UDI_STAT_ABORTED - A test in progress was aborted.

NAME udi_gio_diag_params_t

Parameters for standard GIO diagnostic ops

SYNOPSIS

#include <udi.h>

typedef struct {

	udi_ubit8_t test_num;

	udi_ubit8_t test_params_size;

} udi_gio_diag_params_t;
 

MEMBERS test_num is the number of the diagnostic test to run. This value is ignored if the op member of the gio_xfer_cb is not set to UDI_GIO_OP_DIAG_RUN_TEST.

test_params_size is the number of bytes of additional parameters, if any, for the test specified by test_num. This number may be zero, and must not be greater than two less than the params_size specified in udi_gio_xfer_cb_init. The semantics and structure of these additional parameters are defined by each driver; the corresponding params_layout must include the structure of the additional parameters. This value is ignored if the op member of the gio_xfer_cb is not set to UDI_GIO_OP_DIAG_RUN_TEST.

DESCRIPTION This structure is used to hold additional parameters for the GIO device diagnostics operation UDI_GIO_OP_DIAG_RUN_TEST. It is passed to a udi_gio_xfer_req operation using the tr_params inline array of the udi_gio_xfer_cb_t.

The tr_params pointer itself must not be changed; instead it should be cast to (udi_gio_diag_params_t *) and then the structure may be read or written through the resulting pointer.

Any control block allocated for use with udi_gio_diag_params_t must result from a udi_gio_xfer_cb_init call with params_size set to at least sizeof(udi_gio_diag_params_t).

REFERENCES udi_gio_xfer_cb_t, udi_gio_xfer_req, udi_gio_xfer_ack, udi_gio_xfer_cb_init