SVR5

Intro(D2)

Intro -- introduction to driver entry point routines

Synopsis

   #include <sys/types.h>
   #include <sys/ddi.h>

Description

This section describes the entry-point routines a developer needs to include in a DDI device driver. Parallel sections list the entry point routines that are used in SDI, MDI, and STREAMS drivers. Each specialized section lists all entry point routines that can be used in a driver that conforms to that interface; look to those pages for specific usage information relevant to the specialized interfaces.

Usage

A driver's main structure is formed by the entry-point routines, each of which should include a driver's unique prefix(D1). The only exceptions are the _load(D2) and _unload(D2) entry-point routines which, beginning with DDI version 8, must not include the driver's prefix but instead be named _load( ) and _unload( ).

Beginning with DDI version 8, entry-point routines are located through the driver's drvops(D4) structure rather than by naming convention, but retaining the naming conventions makes the driver easier to maintain. Some interface-specific entry-point routines are identified through other structures, such as streamtab(D4str) for STREAMS drivers and the hba_info(D4sdi) structure for SDI HBA drivers.

Any number of instances of the same driver (or module) entry point routine can be running concurrently. It is the responsibility of the driver or module to synchronize access to its private data structures.

Device instance and channel

Beginning with DDI 8, many of the entry point routines take an idata/channelp parameter pair to identify the device being accessed. In DDI versions prior to DDI 8 and for all SCO OpenServer versions, the device being accessed is identified by the dev_t parameter that contains the major/minor number pair.

For a hardware device, the idata corresponds to the actual physical device, and the channelp corresponds to an operating mode. The idata value is returned by the CFG_ADD subfunction to the config(D2) entry point routine. See ``Device instance'' in HDK Technical Reference and ``Channel number'' in HDK Technical Reference.

Entry point versioning

The set of supported entry points in DDI 8 is different from the set of entry points supported in earlier DDI versions and SCO OpenServer: some routines that were required are not supported in DDI 8, and some new entry point routines have been introduced. The following table compares the entry point routine set in DDI 7 and DDI 8.

NOTE: In DDI 8, there is no distinction between block and character drivers.

Comparison of DDI 7 and DDI 8 entry point routines (non-STREAMS drivers)

          |                ||DDI 7 |           ||DDI 8 |
 Routine  | Context        ||Block | Character ||All   | Notes
 biostart | blockable      ||      |           ||      |
 chpoll   | blockable      ||      | o         ||      |
 close    | blockable      ||rn    | rn        ||r*    | changed syntax
 config   | blockable      ||      |           ||rh    |
 devinfo  | blockable      ||on    | on        ||      | changed syntax
 halt     | non-blockable  ||on    | on        ||      | see config(D2)
 init     | initialization ||on    | on        ||      | see load(D2)
 intr     | interrupt      ||oh    | oh        ||oh    | changed syntax
 ioctl    | user           ||      | on        ||o*    | changed syntax
 drvctl   | blockable      ||      |           ||o     |
 _load    | blockable      ||o     | o         ||r     |
 mmap     | user           ||      | on        ||o     | changed syntax
 open     | blockable      ||rn    | rn        ||r*    | changed syntax
 read     | user           ||      | on        ||      | see biostart(D2)
 size     | blockable      ||rn    |           ||      | see devinfo(D2)
 start    | non-blockable  ||on    | on        ||      | see _load(D2)
 strategy | blockable      ||on    |           ||      | see biostart(D2)
 _unload  | blockable      ||o     | o         ||r     |
 _verify  | blockable      ||oh    | oh        ||      | see config(D2)
 write    | user           ||      | on        ||      |

KEY:

o: Optional
r: Required
+: Required for DDI 8 drivers that use a DDI 8 style open( ) entry point routine. This includes all drivers other than SDI HBA drivers.
*: Used for DDI 8 drivers that are configured to have device file names configured through the Node(DSP/4dsp) file.
SDI drivers use these routines for their pass-through interface, but those are a different interface that are attached through the hba_info(D4sdi) structure and the sdi_register(D3sdi) routine. See ``SDI pass-through interface'' in HDK Technical Reference.
h: Used only for hardware drivers; not used for software-only drivers
n: Named entry point in DDI versions prior to version 8. Named entry point routines are referenced implicitly by specific names and must be global symbols that follow a strict naming convention. On SCO SVR5 1 and 2 systems, named entry points must be declared in the driver's Master(DSP/4dsp) file for the ``$entry'' field. The manual page for each routine gives the specific string that is required in the Master file for each routine.

DDI 8 introduces entry point versioning so that the operating system knows how to invoke the appropriate set of entry point routines for the specified DDI version. All communication of driver entry points for DDI 8 drivers takes place at run time, using the drv_attach(D3) function. drv_attach( ) is called from a driver's _load(D2) routine during driver initialization. The driver passes in a pointer to a drvinfo(D4) structure that includes a pointer to another structure that lists the driver entry point routines. The set of entry point routines in a driver must conform to those documented for the declared DDI version.

The beginning of every DDI 8 driver source file must include the following lines before any header files are #included:

   #define _KERNEL
   #define _DDI 8

The _DDI line gives the ``major'' version number, such as 7 or 8; it does not use full version numbers such as 8.1 or 8mp. These definitions can instead be given as arguments to the -D option of the cc line to compile the driver:

   cc -D_KERNEL -D_DDI=8

The _DDI=version definition is optional for DDI versions prior to version 8.

External dependencies

Drivers must declare the version of the DDI interface to which they conform via the ``$interface'' line in their Master(DSP/4dsp) file, using the interface name ``ddi''. Multithreaded drivers must use a version name that ends with mp (such as 7mp or 8mp). Multithreaded drivers must also set the D_MP flag in either drvinfo(D4) (for DDI 8mp) or devflag(D1) (for drivers using DDI versions earlier than DDI 8).

References

Intro(D2mdi), Intro(D2sdi), Intro(D2str)

Intro(D2oddi)

``Entry-point routines'' in HDK Technical Reference

``Context of a driver'' in HDK Technical Reference
``DDI interface versioning'' in HDK Technical Reference
``Device instance'' in HDK Technical Reference
``Channel number'' in HDK Technical Reference

``Driver structure'' in Developing device drivers