NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | Allowed Calling Contexts | ATTRIBUTES | SEE ALSO
#include <dki/dki.h>KnError svDkiOpen(DevNode dev_node, DkiEventHandler dev_evt_handler, DkiLoadHandler dev_load_handler, void * dev_cookie, DkiDevId * dev_id);
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.
DKI
The system event management services are provided by the microkernel to the lowest layer drivers. They are used mainly to register event handlers for all running drivers, and to start propagating an event from the microkernel.
A system reboot starts propagating a specific event from the microkernel to the lowest-layer level drivers. Those drivers then recursively propagate the event to the upper layer drivers by calling their BusEventHandler handler, which is registered at open time.
svDkiOpen() must be issued by the lowest layer level drivers. It establishes a connection between the device driver and DKI .
The dev_node argument specifies the device node (in the device tree), which is serviced by the device driver instance. In case of an initialization, the device node is given as an argument of drv_init by the parent bus driver. In case of a probing, the device node is either found (among existing child nodes attached to the parent node) or created (and attached to the parent node) by the device driver.
The dev_evt_handler argument specifies the device driver handler, which is invoked by the DKI when an event occurs. It takes three arguments. The first argument is the dev_cookie . The second one specifies the DKI event type. The third argument points to a structure that is event type specific.
Notifies a device driver that the system is going to be shut down. If it is a bus driver, the device driver should propagate the event to all client drivers. Otherwise, it should reset the device hardware and return from the event handler.
The driver must neither notify clients nor free allocated resources.
dev_evt_handler is called an interrupt handler and therefore, the handler implementation must be restricted to the API allowed at interrupt level.
The dev_load_handler argument specifies the device driver handler that is invoked by the DKI when a new driver has been dynamically loaded. It is invoked passing dev_cookie as the only argument.
This dev_load_handler handler is optional.
It should be used only by bus drivers supporting dynamically loadable device drivers, and should be set to NULL by all other drivers. This type of bus driver handler should manage the newly loaded driver in a way similar to the driver's initialization at boot time. That is, to associate the driver with a device node, and initialize it, in order to create a running instance of the newly loaded driver.
The dev_load_handler routine is invoked in the DKI thread context.
The dev_cookie argument specifies a device driver cookie. It is opaque for the DKI . The dev_cookie is passed back to the driver when dev_evt_handler or dev_load_handler is invoked.
On successful completion, svDkiOpen() returns K_OK and an identifier designating the DKI/device connection is returned in the dev_id argument. The dev_id is opaque for the driver and must be passed back to the DKI as an argument of the svDkiClose() service routine. In case of failure, an error code is returned as described below:
The dev_node argument provided is not a valid device tree node.
The dev_node device tree node provided is already in use, that is, associated to another driver.
The system is out of memory.
The svDkiClose() routine releases the DKI/driver connection. It must be the last call issued by the driver.
svDkiEvent() is used to start propagating a given event to the device driver hierarchy. It calls all DkiEventHandler handlers registered through svDkiOpen() to signal all running drivers that the given event occurred. The event argument specifies the event to propagate. The arg argument specifies the specific parameter associated with the event type.
The following table specifies the contexts in which a caller is allowed to invoke each service.
Services | Base level | DKI thread | Interrupt | Blocking |
svDkiOpen() | - | + | - | + |
svDkiClose() | - | + | - | + |
svDkiEvent() | + | + | + | - |
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | Allowed Calling Contexts | ATTRIBUTES | SEE ALSO