Header files

A header file is an ASCII file that contains C language constructs. UNIX systems use header files to define information in a single spot that can be included in different software, including kernel drivers and user-level applications. Defining common information in a header file enhances the portability of code and ensures that all programs compiled with the header file use the same definitions for specific entities. If information changes in the header file, all programs that reference that header file incorporate those changes when they are recompiled. Without the header files, each source file would have to declare these structures and then be recoded when the definitions change. The use of header files is a major help when porting programs from one system to another and when two or more programs must agree on the meaning of a variable.

For technical users, header files also provide a quick reference to data structures, defined constants, and function prototypes that are implemented on the system.

System header files used in driver code

Driver source code must contain some standard ``#include'' files that allow the driver access to system utilities and data structures used to return information to the kernel.

The header files that are included with the operating system are under the /usr/include directory. This directory contains definitions that are generally of interest to user-level programs. The /usr/include/sys subdirectory contains header files with structure definitions, kernel macros, I/O controls commands, and function prototypes that are used by drivers and other kernel-level code.

The description of each kernel function in the HDK manual pages indicates which header files must be included in a driver that uses that function. These header files are called at the beginning of the driver source code in the following format:

   #include <sys/stream.h>
   #include <sys/mdi.h>
   #include <sys/ddi.h>

The lists below identify a few of the more commonly used #include files, in the order they should be #included in driver source code.

DDI header files

<sys/types.h>

Defines basic system data types. This is usually the first header file to be included.

<sys/param.h>

Defines fundamental system parameters.

<sys/signal.h>

Defines system signals.

If the driver sends signals to user processes, it must include this file.

<sys/conf.h>

Defines device configuration structures.

This file is needed for the driver to define its devflag value.

<sys/file.h>

Defines file structures.

This file is needed if the driver uses control flags such as ``no delay'' (FNDELAY).

<sys/buf.h>

Defines the buf(D4) buffer header structure.

This file is needed if the driver uses buffered I/O and for all drivers that call the biostart(D2) entry point routine.

<sys/kmem.h>

Defines the Kernel Memory Allocator interfaces such as kmem_alloc(D3).

This file is needed if the driver allocates memory for buffers out of the common memory pool.

<sys/ksync.h>

Includes prototypes, structures, and definitions used with the synchronization primitives listed in ``Synchronization primitives''.

<sys/stream.h>

Defines the STREAMS interface. Required in all STREAMS module and driver code, including MDI drivers.

<sys/stropts.h>

Contains definitions of the arguments to the M_FLUSH(D7str) message type. Required for all STREAMS drivers and modules.

<sys/strlog.h>

Definitions for STREAMS logging.

<sys/log.h>

Definitions for STREAMS logging.

<sys/errno.h>

Defines the errno values that are returned by drivers and other kernel-level code. See errnos(D5).

<sys/moddefs.h>

Defines the MOD_ wrappers used in the _load(D2) entry point routine for pre-DDI 8 autoconfigurable drivers.

<sys/confmgr.h>

Defines the configuration manager used for autoconfiguration; required in all DDI 8 drivers and autoconfigurable drivers written for DDI versions prior to version 8.

<sys/debug.h>

Defines functionality used when debugging the driver. Required if the code uses the ASSERT(D3) macro for debugging.

<sys/cmn_err.h>

Defines functionality used by the cmn_err(D3) function; required in all DDI drivers.

<sys/dlpi.h>

<sys/scodlpi.h>

<sys/mdi.h>

Defines MAC Driver Interface (MDI). Required in all MDI driver code.

<sys/ddi.h>

Defines Device Driver Interface (DDI) routines.

This header file is required. For DDI 8 and later drivers, it can be anywhere in the list of header files, but for earlier DDI versions, it must come last in the list of included header files (see exceptions below).

<sys/f_ddi.h>

Refines the DDI definition for specific functions. It is required in drivers that call functions such as inb(D3) that access machine instructions directly, and is #included after <sys/ddi.h>.

<sys/cm_i386.h>

<sys/ddi_i386at.h>

Defines functions and symbols specific to the operating system for AT-compatible architectures, and is used for the drv_gethardware(D3) function. It is valid only for DDI version prior to version 8 and must not be used in DDI 8 drivers. If this platform-specific include file is used, it must come last in the list of included header files, after the ddi.h header file.

ODDI header files

sys/types.h

Defines basic system data types. This is usually the first header file to be included.

sys/param.h

Defines fundamental system parameters.

sys/sysmacros.h

Macros for data and memory conversion as well as major/minor number manipulation.

sys/systm.h

Defines the sysent table.

sys/buf.h

Defines the buf buffer data structure that is used for all buffered I/O; see ``Block device drivers''.

sys/iobuf.h

Defines the iobuf structure that is used for controller-specific buffered I/O information.

sys/conf.h

Defines device configuration structures.

sys/signal.h

Defines system signals. If the driver sends signals to user processes, it must include this file.

sys/dma.h

Definitions used for DMA.

sys/stream.h

Defines the STREAMS interface. Required in all STREAMS module and driver code, including MDI drivers.

sys/stropts.h

Contains definitions of the arguments to the M_FLUSH(D7str) message type. Required for all STREAMS drivers and modules.

sys/errno.h

Defines the errno values that are returned by drivers and other kernel-level code.

sys/ipl.h

Interrupt priority level (IPL) definitions.

sys/mdi.h

Defines MAC Driver Interface (MDI). Required in all MDI driver code.

sys/user.h

Defines the user structure that is used to return error messages to the calling user-level program; required in most ODDI drivers.

sys/immu.h

Defines hardware-specific memory management facilities. Note that drivers being build on SCO OpenServer Release 5.0.4 and later versions that need to run on SCO OpenServer 5 Release 5.0.0 and SCO OpenServer 5 Release 50.2 must include the following before the #include line for the immu.h header file:

   #define ODDI3_COMPAT

See the phystokv(D3oddi) manual page for more information.

sys/dio.h

Definitions for disk bad block handling; required for drivers that control disk devices.

sys/disk.h

Definitions for disk management; required for drivers that control disk devices.

sys/select.h

Definitions used for the select(D3oddi) functions.

sys/cmn_err.h

Defines functionality used by the cmn_err(D3oddi) function; required in all ODDI drivers.

sys/debug.h

Defines functionality used by the ASSERT(D3oddi) function.

sys/cram.h

Definitions for accessing the CMOS RAM.

sys/rom.h

Hard disk parameter block as organized in ROM BIOS.

sys/elog.h

Definitions used for kernel error logging facilities.

sys/arch.h

Defines the machine architectures to be supported to the C preprocessor.

sys/open.h

Defines the flags used for the open(D2oddi) and close(D2oddi) functions.

sys/xdebug.h

Defines macros used for kernel debugging levels.

sys/ci/cidriver.h

Definitions used with the archtobus(D3oddi) function.

sys/devreg.h

Definitions used for registering SCSI devices; required in all SCSI HA and target drivers.

sys/vendor.h

Definitions for major platform vendors; required in drivers that behave differently on different platforms.

sys/bootinfo.h

Definition of system information stored at boot time.

sys/probe.h

Definitions used with the probe(D2oddi) entry point routine to support DQI.

sys/kmem.h

Defines the Kernel memory Allocator interfaces such as kmem_alloc(D3oddi). This file is needed if the drver allocates memory for buffers out of the common memory pool.

sys/ci/ciintr.h

Defines the driver_info(D4oddi) structure used to dynamically register interrupts for ODDI drivers.

sys/ci/ciattr.h

Bit-field definitions used for bdevsw and cdevsw entries for SCO OpenServer 5 multithreaded drivers.

sys/strg.h

Definitions used with the getbsvalue(D3oddi) functions; required in drivers that call these functions.

sys/pci.h

Defines configuration of devices on a PCI bus; required in all ODDI drivers that support PCI devices.

Driver-specific header files

Each driver and driver interface should include its own header file(s), which are usually kept in the same directory as the driver source code. These header files are referenced after the other #include lines in the following format:

   #include "my_head.h"

The driver-specific header file should include the following information:

• Structure definitions for any driver-specific drivers

• Definition (with comments) of each supported I/O control command (ioctl).

• Declarations for all variables and constants that are defined for use with this device.

• Function prototypes for all functions that are defined for this driver.