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 angle brackets surround the filename,
to indicate that the file is in the
/usr/include directory tree
(or alternate tree that might be identified to the compiler).
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 double quotes indicate that the header file
is located in the current directory
when the driver code is compiled.
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.
© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 6 and UnixWare (SVR5) HDK - June 2005