NAME | SYNOPSIS | 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);
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.
Typically, 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, 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 initialization, the device node is given as an argument of drv_init by the parent bus driver. In case of 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 which is event type specific.
Notifies a device driver that the system is going to be shut down. The device driver should propagate the event to all client drivers if it is a bus driver. Otherwise, it should reset the device hardware and return from the event handler. Note that the driver must neither notify clients nor free allocated resources.
Typically, dev_evt_handler is called as 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 which is invoked by the DKI when a new driver has been dynamically loaded. It is invoked passing dev_cookie as the only argument. Note that this dev_load_handler handler is optional.
Typically, 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 similar way to the driver's initialization at boot time. That is, associate the driver with a device node, and initialize it, in order to create a running instance of the newly loaded driver. Note that 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. dev_cookie is passed back to the driver when dev_evt_handler or dev_load_handler is invoked.
Upon 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, it 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 (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 | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | Allowed Calling Contexts | ATTRIBUTES | SEE ALSO