svDkiThreadCall(9DKI)

NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | Allowed Calling Contexts | ATTRIBUTES

NAME

svDkiThreadCall, svDkiThreadTrigger, svDkiThreadCancel- call a routine in the DKI thread context; trigger a routine in the DKI thread context; cancel a routine in the DKI thread context

SYNOPSIS

#include <dki/dki.h>

void svDkiThreadCall(DkiCallToken * token, DkiCallHandler handler, void * cookie);
void svDkiThreadTrigger(DkiCallToken * token, DkiCallHandler handler, void * cookie);
void svDkiThreadCancel(DkiCallToken * token);

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

DKI

DESCRIPTION

Provides synchronization services through the DKI thread.

EXTENDED DESCRIPTION

The DKI thread is launched by the microkernel at initialization time.

This thread synchronizes identical calls to DKI and DDI services issued from different threads at drivers' initialization time as well as at runtime. This is 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.

To ensure coherency, the services should be called in the context of the DKI thread. The tables in each section indicate the allowed calling level. 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. Driver routines are called directly from the DKI thread and so the drivers do not perform the synchronization.

• Specific cases

  There are two special cases when 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 microkernel/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 microkernel /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 -

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 -

The same structure may be reused for subsequent calls, after 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.

svDkiThreadCancel() cancels a handler invocation request previously posted by svDkiThreadTrigger() . The token argument is the address of a DkiCallToken structure specified in the svDkiThreadTrigger() call being canceled.

---

Note -

It is not an error to cancel an invocation request that is not pending. In other words, if svDkiThreadCancel() does not detect a pending invocation request corresponding to a given token, it does nothing and simply returns to the caller. Such a situation typically occurs when a given invocation request has been already processed, that is, a handler has been already invoked.

---

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
svDkiThreadCall()	+	+	-	+
svDkiThreadTrigger()	+	+	+	-
svDkiThreadCancel()	+	+	+	-

ATTRIBUTES

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