DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
HDK Technical Reference

DDI interface versioning

Device Driver Interface (DDI) versioning standardizes the kernel interfaces used for writing device drivers. An interface version is a set of defined service interfaces for:

This has the following benefits:

On SVR5 systems, interface versions are enforced by the software. The interface versions defined for SCO OpenServer 5 are pseudo-versions that are not enforced by the software. See ``ODDI driver interface version for SCO OpenServer 5''.

The DDI interface version is the primary interface used for all kernel level drivers on SVR5 systems. It includes all the entry point routines used for drivers plus functions and structures for autoconfiguration, synchronization, memory allocation, and other general purpose functions. DDI also includes the STREAMS entry points, functions, and structures. The ODDI interface (see ``ODDI driver interface version for SCO OpenServer 5'') is the SCO OpenServer 5 equivalent of DDI.

DDI is documented in the following manual page sections:

Support for an interface version is retained for at least three years after its introduction to provide compatibility for drivers written to use them. The manual pages retain information about an obsoleted version for one operating system release past where it is supported. SCO recommends that drivers be ported to newer interface versions to take advantage of new features and to extend the life of the drivers.

SVR5 DDI interface version support

O/S release Supported versions
SVR4.0 ddi 1, 2
SVR4.1 ES ddi 1, 2
SVR4MP ddi 1, 2, 3
SVR4.2 ddi 1, 2, 4
SVR4.2MP ddi 1, 2, 3, 4, 5, 5mp
SCO SVR5 1.X ddi 1, 2, 4
SCO SVR5 2.X ddi 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp; psm 1
SVR5 ddi 5, 5mp, 6, 6mp, 7, 7mp, 8, 8mp
mdi 2
psm 2; i2omsg 1
SVR5, Release 7.0.1
and Release 7.1.*
ddi 5, 5mp, 6, 6mp, 7, 7mp, 8, 8mp
mdi 2, 2.1
hpci 1; psm 2; i2omsg 1

For information about versions of other SVR5 interfaces, see:


SDI
``SDI''

MDI
``MDI''

HPCI
``HPCI (Hot Plug Controller Interface)''.

For information about pseudo-versions of SCO OpenServer 5 interfaces, see:


ODDI
``ODDI driver interface version for SCO OpenServer 5''

OSDI
``MDI''

MDI
``MDI''

When a driver is installed on the system, it declares the DDI version(s) being used in the ``$interface'' field of the Master(DSP/4dsp) file. Drivers that use one of the mp ddi sets must also use $version 2 in the Master file and set the D_MP flag in the drvinfo(D4) structure or, for DDI versions prior to DDI versions before DDI 8, in devflag(D1).

The contents of a SVR5 versioned interface are defined by the Interface(DSP/4dsp) files.

For information about porting drivers to DDI 8, see ``Porting drivers to DDI 8''. For a general description of the structure of a DDI 8 driver, see ``Driver structure''.

Non-conforming functionality

The DDI discipline allows you to declare a driver to be $interface nonconforming, which allows it to access symbols beyond the bounds of the versioned interfaces. Generally, this should be done as an intermediate step when porting. Released drivers should avoid using $interface nonconforming.


WARNING: Non-conforming drivers are not guaranteed to work without modifications on any version of the operating system, and require extra testing to confirm that they are truly safe even for the current operating system version. These drivers must be tested with as many configurations as possible. Even installing a kernel PTF may change the behavior of a non-conforming driver.

SCO recommends that $interface nonconforming be used only as an interim step while porting a driver and not for a driver that is released to customers.


A few drivers may require access to some functionality that is not part of the standardized interfaces. SCO is working to remove the need for this through the use of the non-portable system versioned interface (see Section D3sys manual pages). If it is necessary to use non-conforming symbols, you must also populate the $contact lines in the Master(DSP/4dsp) file. In other words, the Master file includes the following:

   $interface nonconforming
   $contact line 1 of text
   $contact line 2 and up of text
The $contact lines define who to contact for support issues relating to this driver, especially to determine whether a particular version of the driver works with a particular version of the operating system. Include the company name, phone number, email address, and the street address or post office box. Failure to provide this information in the Master file may result in build errors for the driver. SCO may require justification statement when submitting a driver for certification that is $interface nonconforming.

A common porting situation is that the driver is using sleep(D3), wakeup(D3), and timeout(D3) for synchronization. These functions are not supported beyond DDI 6, yet the driver also needs access to some functionality that was added in DDI 7.1, such as the cm_params(D5) parameters like CM_DEVNUM and CM_BUSNUM.

The driver should be rewritten to use synchronization primitives that are supported in DDI 7.1 and later versions, but $interface nonconforming can be used as an intermediate step to get the driver up and running.

The best approach is to select a primary versioned interface for the driver and then use the minimal set of nonconforming symbols that are needed to gain access to the functionality that is not included. For example, the driver that needs to use sleep( ) and wakeup( ) as well as the DDI 7.1 parameters would use the following $interface lines in its Master file:

   $interface ddi 7.1
   $interface nonconforming
   $contact Company Name
   $contact Complete mailing address
   $contact International phone number
   $contact Email address
The driver is written primarily as a DDI 7.1 driver, but can access the sleep( ), wakeup( ), and timeout( ) calls that are not included in DDI 7.1. Because sleep( ) and wakeup( ) do not properly handle synchronization on a multiprocessing configuration, the driver should not try to use an ``mp'' DDI version such as DDI 7.1mp with these functions.

Using $interface nonconforming with a defined interface version allows access to additional symbols but does not change the behavior of functions that are part of the explicitly specified interface versions. For example, if the above driver were declared to be $interface ddi 6, it would access the DDI 6 version of cm_getval( ) which does not support the CM_DEVNUM paramter.

$interface base is used only for core kernel modules that are distributed by SCO, to allow access to system functionality that is not included in DDI versions. It should not be used by any third-party device drivers.

Identifying interface versions being used

A simple awk script can identify all drivers using certain interface versions that are installed on your system. For example, the following script reports all drivers that use DDI version 5/5mp and earlier:

   # cd /etc/conf/mdevice.d
   # awk '$1 == "$interface" && $2 == "ddi" && $3 ~ /^[0-5]/ { \
   	printf("%s: %s\n", FILENAME, $0); }' *

© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 6 and UnixWare (SVR5) HDK - June 2005