NAME | SYNOPSIS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | Allowed Calling Contexts | ATTRIBUTES
#include <dki/dki.h>void svDkiThreadCall(DkiCallToken * token, DkiCallHandler handler, void * cookie);
DKI
Provides synchronization services through the DKI thread.
The DKI thread is launched by the microkernel at initialization time.
The purpose of this thread is to synchronize identical calls to DKI and DDI services issued from different threads at drivers' initialization time as well as at runtime. This is typically used for initialization and shutdown of drivers. By ensuring such synchronization, the DKI thread avoids using any other synchronization mechanism (locks) in the driver implementations.
Refer to the tables in each section, that indicate the allowed calling level, to know which services should to be called in the context of the DKI thread to ensure coherency. The DKI thread is involved as a synchronization mechanism in the following two cases:
Normal case
In the normal case, all calls related to initialization / shutdown of the drivers are done implicitly in the context of the DKI thread. That means that drivers should not worry about synchronization, and do nothing, because their routines are called directly from the DKI thread.
Specific cases
There are two special cases in which a driver should use DKI thread services explicitly to ensure synchronization:
Hot-pluggable device drivers
In the case of a hot-pluggable device driver, the initialization/shutdown process has to be executed at runtime and not as part of the kernel/drivers initialization process. In this type of case, drivers should use the DKI thread services below to synchronize explicitly with drivers already running.
Deferred driver initialization
In some cases, a driver may defer its device initialization until it is opened. This is a way to resolve conflicts about usage of the same resource by multiple drivers. In that way, drivers sharing a resource can be loaded at same time, if they are not opened at the same time. In this type of deferred initialization scheme, the initialization/shutdown process must be executed at runtime (at time of open/close) and not as part of the kernel/drivers initialization process. Thus, these kinds of drivers should also use the DKI thread services below to synchronize explicitly with drivers already running.
svDkiThreadCall synchronously invokes a routine in the context of the DKI thread. Synchronously means that the caller is blocked until the invoked routine returns.
The token argument is the address of a DkiCallToken structure which must be allocated by the caller. This structure is opaque for the driver, and is used only by the DKI thread. Note that the same structure may be reused for subsequent calls. The handler argument specifies the routine to call. The cookie argument specifies the argument to pass to the handler routine when called.
svDkiThreadTrigger asynchronously invokes a routine in the context of the DKI thread. Asynchronously means that the function immediately returns to the caller without waiting for the invoked routine to return. If the driver needs to know when the handler returns, it should use any synchronization mechanism inside the handler itself. The token argument is the address of a DkiCallToken structure which must be allocated by the caller. This structure is opaque to the driver, and is used only by the DKI thread. Note that the same structure may be reused for subsequent calls, once the handler is invoked. The handler argument specifies the routine to call. The cookie argument specifies the argument to pass to the handler routine when called.
The following table specifies the contexts in which a caller is allowed to invoke each service:
Services | Base level | DKI thread | Interrupt | Blocking |
svDkiThreadCall | + | + | - | + |
svDkiThreadTrigger | + | + | + | - |
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