ChorusOS man pages section 9DDI: Device Driver Interfaces

diag(9DDI)

NAME

diag- Diagnostic Driver Interface

SYNOPSIS

#include <ddi/mngt/diag.h>

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

FEATURES

DDI

DESCRIPTION

Provides device driver off-line diagnostic services.

EXTENDED DESCRIPTION

The diagnostic DDI allows a client to perform off-line tests on devices. This interface is typically provided by special diagnostic drivers to be started on inactive device nodes (failed or backup devices). The diagnostic DDI is the same for all classes of bus and device drivers. Typically, a device driver component's manager client would bind the diagnostic driver to the device node by swapping the PROP_DRIVER and PROP_DIAG_DRIVER property values in the inactive device node, saving the initial device/driver binding. The manager would then use the device's parent bus/nexus management DDI (MNGT_CLASS) to start the diagnostic driver on that node (child_init). Once the diagnostic driver is started, the manager client can lookup the device registry to get a pointer to the diagnostic driver's operations. Such a component manager would then be able to execute diagnostics on the device and act on test results (like restoring the initial binding or restarting the normal driver on the device).

The diagnostic DDI provides the following services to manager clients:

Execution of a predefined class of diagnostics on the device.

The diagnostic service routines are defined by the DiagOps structure. A pointer to the DiagOps structure is exported by a diagnostic device driver via the svDeviceRegister microkernel call. A manager client invokes the svDeviceLookup and svDeviceEntry microkernel calls in order to obtain a pointer to the diagnostic service routine vector. Once the pointer is obtained, the driver client is able to invoke the driver service routines (via indirect function calls).

The DiagOps structure is:

typedef struct DiagOps {

     DiagVersion version;

        KnError
    (*diag_exec) (DiagId       devId,
                  DiagAttr*    reqPassed,
                  char*        result,
                  unsigned int resultSz);

} DiagOps;

The version field specifies the diagnostic API version number. The version number is incremented each time one of the DDI structures is extended in order to include new service routines.

`diag_exec` operation

The diag_exec operation performs offline tests on an inactive device. These tests may use all of the device's resources and may even be destructive. Thus, they must only be performed on inactive devices (those not currently being used by the system). The devId argument specifies the diagnostic device driver instance. The reqPassed argument, on input, specifies which tests need to be passed. On output, reqPassed indicates which tests successfully passed. reqPassed may be built by or-ing the following values:

DIAG_ATTR_HARDWARE: Requires execution of built-in hardware self tests.
DIAG_ATTR_SOFTWARE: Requires execution of driver, non-destructive, software tests.
DIAG_ATTR_DESTRUCTIVE: Enables execution of driver destructive tests.
DIAG_ATTR_ALL: Requires execution of all available tests.

The result buffer stores a comprehensive status of passed tests intended to be displayed to an operator. The resultSz argument specifies the maximum available size of the result buffer. result text is truncated to resultSz bytes.

Upon successful completion K_OK is returned. Otherwise, an error code is returned as described below:

K_ENOTIMP: The reqPassed value requires tests which are not supported. On output, reqPassed indicates all supported tests.
K_EBUSY: Tests are already running.
K_ENOMEM: Not enough system memory.
K_EINVAL: The reqPassed value is invalid.
K_EFAIL: Some tests failed. The reqPassed output values indicate which tests were successfully passed. In addition, result contains a text description of the passed and/or failed tests.

Allowed Calling Contexts

The following table specifies the contexts in which a caller is allowed to invoke each service:

Services	Base level	DKI thread	Interrupt	Blocking
DiagOps.diag_exec	+	+	-	+

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving