1    Header Files Related to Device Drivers

This chapter describes:

• Conventions for header files that device drivers use

• Header files that device drivers use

1.1    Conventions for Header Files

The descriptions of the header files associated with device drivers are presented in alphabetical order and in reference (man) page style. The descriptions can include the following sections.

Name

This section lists the name of the header file along with a summary description of its contents.

Location

This section presents the pathname for the header file. The pathname makes it easier for you to locate specific header files.

Description

This section briefly describes the contents of the header file.

When to Include

This section explains when to include a header file for block and character drivers.

Of Special Interest

This section lists specific structures, macros, constant values, and so forth that are of interest to device driver writers.

Related Information

This section lists related kernel interfaces, structures, system calls, and so forth.

1.2    Header Files

Table 1-1 lists the header files related to device drivers, along with short descriptions of their contents. For convenience, the header files are listed in alphabetical order. Note that device drivers should include header files that use the relative pathname instead of the explicit pathname. For example, although buf.h resides in /usr/sys/include/sys/buf.h, device drivers should include it as:

<sys/buf.h>

Not all of the header files reside in <sys>. The following include files reside in other directories:

<kern/lock.h>
<machine/cpu.h>
<io/common/devdriver.h>

Table 1-1: Summary Descriptions of Header Files

buf.h

Defines the buf structure

Location

/usr/sys/include/sys/buf.h

Description

The buf.h file defines the buf structure used to pass I/O requests to the strategy interface of a block device driver. Character device drivers can also use the buf structure, typically in the xxstrategy interface.

When to Include

You include the buf.h file in block device drivers because they use file system block-sized buffers from a buffer cache supplied by the kernel to perform I/O.

Of Special Interest

Items of interest to device driver writers are:

• The buf structure

• The BUF_LOCK macro

• The BUF_UNLOCK macro

• Flag definitions for the b_flags member of the buf structure

Related Information

buf, BUF_LOCK, BUF_UNLOCK

conf.h

Defines the dsent structure

Location

/usr/sys/include/sys/conf.h

Description

The conf.h file defines the dsent structure (for block and character device drivers).

When to Include

You should include the conf.h file in block and character device drivers because these drivers declare an instance of and set the associated members of the dsent structure.

Of Special Interest

Items of interest to device driver writers are:

• The dsent structure

• The define for DEV_FUNNEL_NULL

• The define for DEV_FUNNEL

You use the defines to initialize the d_funnel member of the dsent structure.

Related Information

dsent

cpu.h

Defines structures and constants related to the CPU

Location

/usr/sys/include/machine/cpu.h

Description

The cpu.h file defines a variety of structures and constants related to the CPU.

When to Include

You include the cpu.h file in block and character device drivers when calling any of the spl interfaces. The reason for this is that the spl interfaces map to an assembler interface.

Of Special Interest

The items contained in cpu.h are opaque to device driver writers. In other words, device driver writers need not know the details of how the spl interfaces map to the assembler-specific interface.

Related Information

spl

devdriver.h

Defines the structures, constants, and external interfaces that device drivers and the autoconfiguration software use

Location

/usr/sys/include/io/common/devdriver.h

Description

The devdriver.h file defines the structures, constants, and external interfaces that device drivers and the autoconfiguration software use.

When to Include

You must include the devdriver.h file in block and character device drivers because you initialize the driver structure and reference the controller, device, and bus structures.

Of Special Interest

Items of interest to device driver writers are:

• The bus, controller, device, and driver structures

• The port structure

• Bus type constants

• Bit constants for the alive member of the bus, controller, and device structures

• The typedefs io_handle_t and dma_handle_t

Related Information

bus, controller, device, driver

devdriver_loadable.h

Defines constants and declares external functions associated with dynamically configured drivers

Location

/usr/sys/include/io/common/devdriver_loadable.h

Description

The devdriver_loadable.h file defines constants and declares external functions associated with drivers that are dynamically configured into the kernel. The file also defines constants and declares external functions associated with bus support.

When to Include

You do not need to include this file in your device driver.

Of Special Interest

Items of interest to systems engineers who implement a new bus or make changes to an existing bus are the external declarations for interfaces used in bus adapter driver development. Examples of these external declarations are ldbl_find_bus, ldbl_search_bus_local, and ldbl_find_ctlr.

devgetinfo.h

Defines various data structures used by the DEVGETINFO ioctl command

Location

/usr/sys/include/io/common/devgetinfo.h

Description

The devgetinfo.h file defines various data structures that the DEVGETINFO ioctl command uses.

When to Include

You include the devgetinfo.h file in disk device drivers.

Of Special Interest

Items of interest to device driver writers are the following data structures:

• v1_bustype_info_t

• v1_device_info_t

• v1_devtype_info_t

• v1_disk_dev_info_t

• v1_tape_dev_info_t

Related Information

DEVGETINFO, v1_bustype_info_t, v1_device_info_t, v1_devtype_info_t, v1_disk_dev_info_t, v1_tape_dev_info_t

devio.h

Defines common structures and definitions for device drivers and ioctl commands

Location

/usr/sys/include/io/common/devio.h

Description

The devio.h file defines common structures and definitions for device drivers and ioctl commands, such as DEVGETGEOM. This file also contains descriptions of device types, attributes, and names.

When to Include

You include the devio.h file in your device driver if you plan to use any of the ioctl commands such as DEVGETGEOM.

Of Special Interest

Items of interest to device driver writers are:

• The devget and DEVGEOMST structures

• Status constant definitions for the category and bus members of the devget structure

• Constant definitions for the interface and the device character array members of the devget structure

• Constant definitions for the stat and category_stat members of the devget structure

• Constant definitions for the attributes member of the DEVGEOMST structure

Related Information

DEVGETGEOM, DEVIOCGET

disklabel.h

Defines structures and macros that operate on Digital UNIX disk labels

Location

/usr/sys/include/sys/disklabel.h

Description

The disklabel.h file defines structures and macros that operate on Digital UNIX disk labels. Each disk has a label that includes information about the hardware disk geometry, file system partitions, and drive-specific information.

When to Include

You include the disklabel.h file if your block device driver needs to operate on disk labels.

Of Special Interest

Items of interest to device driver writers are:

• The disklabel structure

• Constant values for the d_type member of the disklabel structure

  The values for this member can be set to describe the drive type. Some examples are DTYPE_MSCP (the drive type is an MSCP) and DTYPE_SCSI (the drive type is a SCSI).

Related Information

disklabel

Reference Pages Section 4: disktab

errno.h

Defines the error codes that a device driver returns to a user process

Location

/usr/sys/include/sys/errno.h

Description

The errno.h file defines the error codes returned to a user process by a device driver. Some of the error codes that a device driver can use are EIO, ENXIO, EACCES, EBUSY, ENODEV, and EINVAL.

When to Include

You include the errno.h file in both block and character device drivers to use the systemwide error codes.

fcntl.h

Defines I/O mode flags that user programs supply to open and fcntl system calls

Location

/usr/sys/include/sys/fcntl.h

Description

The fcntl.h file defines I/O mode flags supplied by user programs to the open and fcntl system calls.

When to Include

You include the fcntl.h file in both block and character device drivers because these I/O mode flags get passed to the driver's open, close, and ioctl interfaces.

Related Information

Reference Pages Section 2: fcntl, open

ioctl.h

Defines commands for ioctl interfaces in different device drivers

Location

/usr/sys/include/sys/ioctl.h

Description

The ioctl.h file defines commands for ioctl interfaces in different device drivers. The ioctl commands are driver entry points that perform tasks other than the general I/O operations such as read and write. Thus, you can consider ioctl operations as a way to perform any task other than read and write tasks.

When to Include

You include the ioctl.h file in both block and character device drivers only when there is an ioctl entry point; that is, the driver has an ioctl interface that uses I/O control commands.

iotypes.h

Defines constants that 64-bit conversions use

Location

/usr/sys/include/io/common/iotypes.h

Description

The iotypes.h file defines constants that 64-bit conversions use.

When to Include

You include the iotypes.h file if you use the constants defined for 64-bit conversions in your device driver.

Of Special Interest

The following table lists some of the 64-bit conversion constants:

Constant	Meaning
I8	char
U8	unsigned char
I16	short
U16	unsigned short
I32	int
U32	unsigned int
I64	long long
U64	unsigned long long
I_WORD	long
U_WORD	unsigned long

kernel.h

Defines global variables that the kernel uses

Location

/usr/sys/include/sys/kernel.h

Description

The kernel.h file defines global variables that the kernel uses.

When to Include

You include the kernel.h file in both block and character device drivers to make use of the kernel global variables.

Of Special Interest

The kernel global variables that are of particular interest to device driver writers are:

• The hz variable

• The lbolt variable

• The time structure

  This structure is defined as an external structure. This structure is defined in the file time.h.

Related Information

hz, lbolt

lock.h

Defines simple and complex lock structures

Location

/usr/sys/include/kern/lock.h

Description

The lock.h file defines the simple spin lock and complex lock structures that device drivers use for synchronization on single processor and multiprocessor systems.

When to Include

You include the lock.h file in device drivers if you use simple or complex locks to synchronize access to device driver structures and device registers.

Of Special Interest

Items of interest to the device driver writer are:

• The slock structure

  This is the simple spin lock structure.

• The typedefs simple_lock_data_t and simple_lock_t

  The simple_lock_data_t typedef is an alternate name for the slock structure and the simple_lock_t typedef is an alternate name for a pointer to the slock structure.

• The lock structure

  This is the complex lock structure.

• The typedefs lock_data_t and lock_t

  The lock_data_t typedef is an alternate name for the lock structure and the lock_t typedef is an alternate name for a pointer to the lock structure.

Related Information

lock, slock

malloc.h

Defines kernel memory allocator-related information

Location

/usr/sys/include/sys/malloc.h

Description

The malloc.h file defines the constants, data structures, and interfaces associated with the kernel memory allocator interfaces MALLOC and FREE.

When to Include

You include the malloc.h file in block and character device drivers when calling the interfaces associated with the kernel memory allocator.

Of Special Interest

Items of interest to device driver writers are the defines for the different memory types that device drivers can pass to the type argument of the MALLOC interface. For example, you can pass the M_DEVBUF constant to indicate that device driver memory is being allocated (or freed).

Related Information

FREE, MALLOC

map.h

Defines structures associated with resource allocation maps

Location

/usr/sys/include/sys/map.h

Description

The map.h file defines structures associated with resource allocation maps.

When to Include

You include the map.h file in both block and character device drivers when you need to make reference to the members of the map and mapent structures.

mman.h

Defines constants associated with the mmap kernel interface

Location

/usr/sys/include/sys/mman.h

Description

The mman.h file defines constants associated with the mmap kernel interface. It also defines protection bits that the mmap system call uses.

When to Include

You include the mman.h file in any character device driver that needs to call the mmap kernel interface.

Of Special Interest

Items of interest to device driver writers are the following protection bits:

• PROT_READ

• PROT_WRITE

Related Information

xxmmap

Reference Pages Section 2: mmap, munmap

mode.h

Defines constants that driver interfaces use

Location

/usr/sys/include/sys/mode.h

Description

The mode.h file defines constants that driver interfaces use.

When to Include

You include the mode.h file when you use any of the constants defined in this file in your device driver.

Of Special Interest

Items of interest to device driver writers are:

• The S_IFBLK constant

• The S_IFCHR constant

Driver writers can use these constants to check the format argument for the xxclose and xxopen interfaces to determine whether the request is for a block or character device special file.

mtio.h

Defines commands and structures for magnetic tape operations

Location

/usr/sys/include/sys/mtio.h

Description

The mtio.h file defines commands and structures for magnetic tape operations.

When to Include

You include the mtio.h file in tape device drivers. Commands defined in this file are used to communicate with the device driver's ioctl interface.

Of Special Interest

Items of interest to device driver writers are:

• The mtget structure

• The mtop structure

Related Information

Reference Pages Section 4: mtio

param.h

Defines constants and interfaces that the kernel uses

Location

/usr/sys/include/sys/param.h

Description

The param.h file defines constants and interfaces that the kernel uses.

When to Include

You include the param.h file in block and character device drivers when calling the sleep interface. The reason for this is that the sleep interface maps to another kernel interface.

Of Special Interest

One item of interest to device driver writers is the PCATCH constant.

Related Information

sleep

poll.h

Defines polling bit masks

Location

/usr/sys/include/sys/poll.h

Description

The poll.h file defines bit polling bit masks that a device driver's xxselect interface uses.

When to Include

You include the poll.h file in character device drivers if you want to use the polling bit masks to determine the state of the specified device.

Of Special Interest

Items of interest to device driver writers are the following polling bit masks:

• POLLNORM

• POLLOUT

• POLLPRI

• POLLNVAL

• POLLHUP

Related Information

select_dequeue, select_dequeue_all, select_enqueue, select_wakeup, xxselect

Reference Pages Section 2: select

proc.h

Defines the proc structure, which defines a user process

Location

/usr/sys/include/sys/proc.h

Description

The proc.h file defines the proc structure, which defines a user process.

When to Include

You include the proc.h file in block and character device drivers if you want to access different members of the user's process structure.

sched_prim.h

Defines scheduling interfaces

Location

/usr/sys/include/kern/sched_prim.h

Description

The sched_prim.h file defines scheduling interfaces (macros) and kernel threads-related constants.

When to Include

You include the sched_prim.h file when your driver references any kernel threads-related constants or scheduling interfaces.

Of Special Interest

Items of interest to driver writers are the following interfaces:

• assert_wait_mesg

• thread_block

• thread_wakeup

• thread_wakeup_one

Related Information

assert_wait_mesg, thread_block, thread_wakeup, thread_wakeup_one

security.h

Defines structures, constants, and data types that UNIX security software uses

Location

/usr/sys/include/sys/security.h

Description

The security.h file defines structures, constants, and data types that UNIX security software uses.

When to Include

You include the security.h file in block and character device drivers if you call the privileged kernel interface.

Of Special Interest

Items of interest to device driver writers are the privilege constants. Examples of these constants include:

• SEC_FILESYS

• SEC_OWNER

• SEC_CHPRIV

Related Information

privileged

select.h

Defines select-related data structures and interfaces

Location

/usr/sys/include/sys/select.h

Description

The select.h file defines the data structure and interfaces that device drivers use with the select_enqueue and select_dequeue interfaces.

When to Include

You include the select.h file when your device driver uses the sel_queue data structure and calls the select_enqueue and select_dequeue interfaces.

Of Special Interest

Items of interest to device driver writers are:

• The sel_queue data structure

• The typedef sel_queue_t, which is an alternate name for struct sel_queue

Related Information

select_dequeue, select_enqueue, sel_queue

sysconfig.h

Defines cfgmgr framework operation codes and data structures used in the device driver's configure interface

Location

/usr/sys/include/sys/sysconfig.h

Description

The sysconfig.h file defines operation codes and data structures used in the device driver's configure interface. The operation codes define the action to be performed by the configure interface. Examples of the operation types include configure, unconfigure, and query. This file also defines many of the constants that are shared between the cfgmgr framework and device drivers. The definition of the cfg_attr_t data structure that the device driver method of cfgmgr passes to the driver's configure interface appears in this file. The definition of the cfg_subsys_attr_t data structure that a driver's configure interface initializes also appears in this file.

When to Include

You include the sysconfig.h file in block and character device drivers.

Of Special Interest

Items of interest to device driver writers are the following constants:

• CFG_OP_CONFIGURE

• CFG_OP_UNCONFIGURE

• CFG_OP_QUERY

You use these constants as follows:

• In the op argument of the driver's configure interface

• In the operations member of the cfg_subsys_attr_t structure

The following constants are used with the point argument of the register_callback interface:

• CFG_PT_PRECONFIG

• CFG_PT_POSTCONFIG

• CFG_PT_ROOTFS_AVAIL

The following constants are used with the order argument of the register_callback interface:

• CFG_ORD_NOMINAL

• CFG_ORD_MAXIMUM

You may also find the following interfaces (macros) useful for setting and checking dispatch points (through the register_callback interface): SET_CFGPOINT, BEFORE_CFGPOINT, and PAST_CFGPOINT.

Related Information

cfg_attr_t, cfg_subsys_attr_t, register_callback, unregister_callback, xxcallback, xxconfigure

systm.h

Defines generic kernel global variables

Location

/usr/sys/include/sys/systm.h

Description

The systm.h file defines generic kernel global variables that some kernel interfaces use.

When to Include

You include the systm.h file in character and block device drivers only if you need to reference one of the generic kernel global variables. Most device drivers will not need this file.

Of Special Interest

Items of interest to device driver writers are:

• The physmem global variable

  This global variable specifies the physical memory on this CPU.

• The version global variable

  This global variable is a character array that specifies the system version.

• Casts for the insque and remque kernel interfaces

  These casts are made to satisfy the lint program.

Related Information

insque

task.h

Defines structures that tasks use

Location

/usr/sys/include/kern/task.h

Description

The task.h file defines structures that tasks use.

When to Include

You include the task.h file when your driver references any of the data structures related to tasks.

Of Special Interest

One item of interest to the device driver writer is the typedef task_t, which is an alternate name for struct task *.

Related Information

task

thread.h

Defines structures that kernel threads use

Location

/usr/sys/include/kern/thread.h

Description

The thread.h file defines structures that kernel threads use.

When to Include

You include the thread.h file when your driver references any of the data structures related to kernel threads.

Of Special Interest

One item of interest to the device driver writer is the typedef thread_t, which is an alternate name for struct thread *.

Related Information

thread

time.h

Contains structures and symbolic names that time-related interfaces use

Location

/usr/sys/include/sys/time.h

Description

The time.h file contains structures and symbolic names that time-related interfaces use.

When to Include

You include the time.h file in block and character device drivers if the driver needs to look at:

• The system time

• A process's timeval structures

Of Special Interest

Items of interest to device driver writers are:

• The tm structure

• The timeval structure

types.h

Defines system data types and major and minor device interfaces

Location

/usr/sys/include/sys/types.h

Description

The types.h file defines system data types and major and minor device interfaces.

When to Include

You include the types.h file in most block and character device drivers in order to use the defined data types.

uio.h

Contains the definition of the uio structure

Location

/usr/sys/include/sys/uio.h

Description

The uio.h file contains the definition of the uio structure.

When to Include

You include the uio.h file in character device drivers that access the uio structure.

Of Special Interest

Items of interest to device driver writers are:

• The uio structure

• The uio structure member uio_rw

  This member is an enumerated data type that can be set to the flag UIO_READ or UIO_WRITE.

• The uio structure member uio_segflg

  This member is an enumerated data type that can be set to the flag UIO_USERSPACE, UIO_SYSSPACE, or UIO_USERISPACE.

Related Information

uio

user.h

Defines the user structure

Location

/usr/sys/include/sys/user.h

Description

The user.h file defines the user structure.

When to Include

You include the user.h file in block and character device drivers only if the driver needs to access different members of the user's user context structure.

Of Special Interest

Items of interest to device driver writers are:

• The user structure

• The utask structure

vm.h

Contains a sequence of include statements that includes all of the virtual memory-related files

Location

/usr/sys/include/sys/vm.h

Description

The vm.h file contains a sequence of include statements that includes all of the virtual memory-related files.

When to Include

Including the vm.h file is a quick way of including all of the virtual memory-related files.

vmmac.h

Contains definitions for byte conversions

Location

/usr/sys/include/sys/vmmac.h

Description

The vmmac.h file contains definitions for converting from bytes to pages and from pages to bytes.

When to Include

You include the vmmac.h file in device drivers if the driver needs to perform virtual memory calculations directly.