|
|
udi_gio_op_t_diag(3udi)
Diagnostics control operations
#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.