Intro

- introduction to DDI/DKI functions

Description

Section 9F describes the kernel functions available for use by device drivers. See Intro(9E) for an overview of device driver interfaces.

In this section, the information for each driver function is organized under the following headings:

• NAME summarizes the function's purpose.

• SYNOPSIS shows the syntax of the function's entry point in the source code. #include directives are shown for required headers.

• INTERFACE LEVEL describes any architecture dependencies.

• ARGUMENTS describes any arguments required to invoke the function.

• DESCRIPTION describes general information about the function.

• RETURN VALUES describes the return values and messages that can result from invoking the function.

• CONTEXT indicates from which driver context (user, kernel, interrupt, or high-level interrupt) the function can be called.

• A driver function has user context if it was directly invoked because of a user thread. The read(9E) entry point of the driver, invoked by a read(2) system call, has user context.

• A driver function has kernel context if was invoked by some other part of the kernel. In a block device driver, the strategy(9E) entry point may be called by the page daemon to write pages to the device. The page daemon has no relation to the current user thread, so in this case strategy(9E) has kernel context.

• Interrupt context is kernel context, but also has an interrupt level associated with it. Driver interrupt routines have interrupt context.

  Note that a mutex acquired in user or kernel context that can also be acquired in interrupt context means that the user or kernel context thread holding that mutex is subject to all the restrictions imposed by interrupt context, for the duration of the ownership of that mutex. Please see the mutex(9F) man page for a more complete discussion of proper mutex handling for drivers.

• High-level interrupt context is a more restricted form of interrupt context. If a driver interrupt priority returned from ddi_intr_get_pri(9F) is greater than the priority returned from ddi_intr_get_hilevel_pri(9F) this indicates the interrupt handler will run in high-level interrupt context. These interrupt routines are only allowed to call ddi_intr_trigger_softint(9F), mutex_enter(9F), and mutex_exit(9F). Furthermore, mutex_enter(9F) and mutex_exit(9F) may only be called on mutexes initialized with the interrupt priority returned by ddi_intr_get_pri(9F).

• SEE ALSO indicates functions that are related by usage and sources, and which can be referred to for further information.

• EXAMPLES shows how the function can be used in driver code.

Every driver MUST include <sys/ddi.h> and <sys/sunddi.h>, in that order, and as the last files the driver includes.

STREAMS Kernel Function Summary

The following table summarizes the STREAMS functions described in this section.

The following table summarizes the functions not specific to STREAMS.

See Also

Intro(9E), mutex(9F)