Interface(DSP)

Description

The name of each file determines the interface name and version that it describes. The filenames must be in the following form:

name.version

The idbuild(ADM) command uses these files to determine which symbols, if any, in the Driver.o files should be remapped to different symbol names before linking. The idbuild(ADM) command uses the set of $interface lines in a module's Master(DSP) file to determine which Interface files to use. The module is not accepted if it references symbols not covered by its $interface lines.

Interface checking is done at idbuild time for static modules and at load time for loadable modules.

Each interface file contains lines with the following whitespace-separated fields:

``symbol-name''
``new-symbol-name''

The ``new-symbol-name'' field is optional. If present, it specifies the alternate symbol to use in place of ``symbol-name''.

If the same ``symbol-name'' appears on multiple lines, the last one is used. The special ``new-symbol-name'', $dropped, can be used to drop a previouslylisted symbol from the interface. This is most useful with $replace.

The following special lines also can appear in Interface files:

$replace version
$depend module-name-list
$entrytype type

The description of each line follows:

$replace

Specifies that this interface is based on a previous version with the same name. This acts as if the corresponding name.version file were directly included at this point. Also, it establishes an ordering between versions of an interface. This ordering is used by idinstall(ADM), when converting old Master files that do not have $interface lines, if symbols match multiple interface versions. In this case, the ``oldest'' version is used.

$depend

Specifies the kernel modules that implement the interface. These modules are loaded automatically whenever a module that uses this interface is loaded.

$entrytype

Specifies the entry-point model for the modules that use this interface. Newer interfaces use entry-type 1, which uses exactly two global entry-point routines, named _load( ) and _unload( ). Entry-type 1 modules are dynamically loadable by default, and always have their _load(D2) entry-point routine called, even when linked statically into the base kernel.

Entry-type 0 modules use named entry points, identified by $entry lines in the Master files. The Section D2 manual pages in Section D2 manual pages define the $entry values used to identify each named entry point routine used with DDI versions prior to version 8. Named entry point names are constructed by prepending a module's prefix(D1) to the standard entry-point suffix. Entry-type 0 modules are only dynamically loadable if they contain an L in the characteristics field of their Master(DSP) files and they use the appropriate MOD_xxx_WRAPPER macros. When linked statically into the base kernel, their (optional) init(D2) and start(D2) entry-point routines are called instead of _load(D2).

$entrytype lines apply only to the Interface file(s) directly referenced by $interface lines in a module's Master file; they are not inherited by $replace. If none of the directly-referenced files contain a $entrytype line, entry-type 0 is assumed.

References

``DDI interface versioning'' in HDK Technical Reference.