NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | Allowed Calling Contexts | ATTRIBUTES | SEE ALSO
#include <ddi/mngt/mngt.h>
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.
DDI
Provides device driver management services.
The management DDI provides services allowing a client to manage device/driver pairs as components. This interface is the same for all classes of bus and device drivers. Typically, a device/driver component's client manager would look at all entries in the device registry to find those of MNGT_CLASS type . Such a component manager would then be able to access basic management services for all associated device/driver pairs in order to implement high-level management policies (like redundancy and failover) required in Highly Available systems. Having the same interface for all device classes allows client managers to handle the relationships between the device drivers they control.
To be manageable, a device or bus driver should provide two interfaces:
Its own class DDI, allowing clients to use the device (or bus).
A management DDI, allowing a client manager to take control and obtain information about the device/driver component.
The management DDI provides the following services to manager clients:
Identification of the device/driver pair class.
Ability to obtain current statistics.
Audit a running device driver (for example, by performing online checks).
For bus/nexus drivers only, the management DDI provides the additional following services:
Shut-down of a given active child device driver.
Initialization of a given stopped child device driver
The management service routines are defined by the MngtOps structure. A pointer to the MngtOps structure is exported by a manageable 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 management service routines vector. Once the pointer is obtained, the driver client is able to invoke the driver service routines (via indirect function calls).
The MngtOps structure is:
typedef struct MngtOps { MngtVersion version; KnError (*open) (MngtId devId); void (*close) (MngtId devId); char* (*class_get) (MngtId devId)); KnError (*child_shutdown) (MngtId devId, DevNode child, MngtDownHandler handler, void* cookie); KnError (*child_init) (MngtId devId, DevNode child); KnError (*stat_get) (MngtId devId, void* stat); KnError (*audit) (MngtId devId, MngtAudit* reqPassed, char* result, unsigned int resultSz)); } MngtOps;
The version field specifies the management API version number. The version number is incremented each time one of the DDI structures is extended in order to include new service routines.
open must be the first call issued by the client to the driver. It establishes a connection between the driver and its manager. The devId argument specifies the manageable device driver instance.
Upon successful completion, open returns K_OK. Otherwise, an error code is returned as described below:
The system is out of memory.
The close routine releases the connection between the manager and the driver. It must be the last call issued.
The class_get service returns the class name of the device being managed . This name may be used by the manager to identify the device's type and to manage redundancy and/or failover between devices of the same class. The devId argument specifies the manageable device driver instance.
Only bus/nexus device drivers implement the child_shutdown service routine. This operation raises a DEV_SHUTDOWN event in the driver bound to the specified child device node. This is typically done by calling the associated child driver's bus event handler. The devId argument specifies the manageable bus/nexus driver instance. The child argument specifies the child device node to be stopped. The handler argument contains a down handler to be called back once the asynchronous shutdown processes of the child driver are complete. Typically, this handler is called when the child driver closes the connection to its parent bus (close). cookie is passed back as an argument to handler.
child_shutdown returns K_OK if a driver is bound to the given child node and if this driver handles the DEV_SHUTDOWN event. Otherwise, an error code is returned as described below:
The managed driver does not implement the operation or the specified child driver does not handle the DEV_SHUTDOWN event.
Only bus/nexus drivers implement the child_init operation. This operation executes the drv_init method of the driver bound to the specified child device node. The devId argument specifies the manageable bus/nexus driver instance. The child argument specifies the child device node to be initialized.
The child device node must not be active (no driver started on that node). If a driver is bound to the child device node, its drv_init method is called. If the child driver has started successfully, K_OK is returned. Otherwise, an error code is returned as described below:
The managed driver does not implement the operation.
child is not a valid child device node of the bus/nexus managed driver.
child is already active (bound driver is running).
child device node resources are not allocated, there is no driver bound to that node or the bound driver failed to initialize.
The stat_get operation reads the current statistics of the managed device driver. The devId argument specifies the manageable device driver instance. The stat argument points to a buffer used to return current statistical values. The stat buffer size must be at least the size of the managed device's class specific statistics structure. For each device class, a specific statistics structure is defined in a separate header file.
See diskStat(9DDI), etherStat(9DDI), flashStat(9DDI), uartStat(9DDI) for a complete description of the statistics structures.
Upon successful completion, K_OK is returned. Otherwise, one of the following error codes is returned:
The managed driver does not implement the operation.
Statistical values are not currently available.
The audit operation performs online tests on a running device driver. These tests do not perturb the active device driver and may be called periodically while the driver is in use. It may be useful for a manager to detect that a device has failed or is frozen. The devId argument specifies the manageable device driver instance. The reqPassed argument, as input, specifies which online tests need to be passed. On output, reqPassed indicates which tests actually passed. reqPassed may be built by or-ing the following values:
Checks that the device has some activity (is not frozen). Typically this test should be required periodically by the manager.
The result buffer used to store a comprehensible 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, one of the following error codes are returned:
The reqPassed value requires tests which are not supported. On output, reqPassed indicates all supported tests.
Tests are already running.
Not enough system memory.
The reqPassed value is invalid.
Some tests failed. The reqPassed output values indicate which tests were successful. In addition, result contains a textual description of the passed and/or failed tests.
The following table specifies the contexts in which a caller is allowed to invoke each service:
Services | Base level | DKI thread | Interrupt | Blocking |
---|---|---|---|---|
MngtOps.open | - | + | - | + |
MngtOps.close | - | + | - | + |
MngtOps.class_get | + | + | + | - |
MngtOps.child_shutdown | + | + | + | - |
MngtOps.child_init | - | + | - | + |
MngtOps.stat_get | + | + | + | - |
MngtOps.audit | + | + | + | - |
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
svDeviceRegister(9DKI), svDeviceLookup(9DKI), svDeviceEntry(9DKI), diskStat(9DDI), etherStat(9DDI), flashStat(9DDI), uartStat(9DDI)
NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | Allowed Calling Contexts | ATTRIBUTES | SEE ALSO