C Summary Tables

This appendix presents tables that summarize:

Header files
Kernel interfaces
ioctl commands
Global variables
Data structures
Device driver interfaces
Bus configuration interfaces

C.1 List of Header Files

Table C-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>

Chapter 1 of Writing Device Drivers: Reference provides reference descriptions of the header files listed in Table C-1.

Table C-1: Summary Descriptions of Header Files
Header File	Contents
`<sys/buf.h>`	Defines the `buf` structure.
`<sys/conf.h>`	Defines the `dsent` structure.
`<machine/cpu.h>`	Defines structures and constants related to the CPU.
`<io/common/devdriver.h>`	Defines the structures, constants, and external interfaces that device drivers and the autoconfiguration software use.
`<io/common/devdriver_loadable.h>`	Defines constants and declares external functions associated with dynamically configured drivers.
`<io/common/devgetinfo.h>`	Defines various data structures used by the `DEVGETINFO` `ioctl` command.
`<io/common/devio.h>`	Defines common structures and definitions for device drivers and `ioctl` commands.
`<sys/disklabel.h>`	Defines structures and macros that operate on Digital UNIX disk labels.
`<sys/errno.h>`	Defines the error codes that a device driver returns to a user process.
`<sys/fcntl.h>`	Defines I/O mode flags that user programs supply to `open` and `fcntl` system calls.
`<sys/ioctl.h>`	Defines commands for `ioctl` interfaces in different device drivers.
`<io/common/iotypes.h>`	Defines constants that 64-bit conversions use.
`<sys/kernel.h>`	Defines global variables that the kernel uses.
`<kern/lock.h>`	Defines simple and complex lock structures.
`<sys/malloc.h>`	Defines kernel memory allocator-related information.
`<sys/map.h>`	Defines structures associated with resource allocation maps.
`<sys/mman.h>`	Defines constants associated with the `mmap` kernel interface.
`<sys/mode.h>`	Defines constants that driver interfaces use.
`<sys/mtio.h>`	Defines commands and structures for magnetic tape operations.
`<sys/param.h>`	Defines constants and interfaces that the kernel uses.
`<sys/poll.h>`	Defines polling bit masks.
`<sys/proc.h>`	Defines the `proc` structure, which defines a user process.
`<kern/sched_prim.h>`	Defines scheduling interfaces.
`<sys/security.h>`	Defines structures, constants, and data types that UNIX security software uses.
`<sys/select.h>`	Defines select-related data structures and interfaces.
`<sys/sysconfig.h>`	Defines `cfgmgr` framework operation codes and data structures used in the device driver's `configure` interface.
`<sys/systm.h>`	Defines generic kernel global variables.
`<kern/task.h>`	Defines structures that tasks use.
`<kern/thread.h>`	Defines structures that kernel threads use.
`<sys/time.h>`	Contains structures and symbolic names that time-related interfaces use.
`<sys/types.h>`	Defines system data types and major and minor device interfaces.
`<sys/uio.h>`	Contains the definition of the `uio` structure.
`<sys/user.h>`	Defines the `user` structure.
`<sys/vm.h>`	Contains a sequence of include statements that includes all of the virtual memory-related files.
`<sys/vmmac.h>`	Contains definitions for byte conversions.

C.2 List of Kernel Support Interfaces

Chapter 2 of Writing Device Drivers: Reference provides reference descriptions of the kernel interfaces listed in Table C-2.

Note
Device drivers use the following header files most frequently:

#include <sys/types.h>
#include <sys/errno.h>
#include <io/common/devdriver.h>
#include <sys/uio.h>
#include <machine/cpu.h>
#include <sys/conf.h>
#include <sys/sysconfig.h>

Table C-2: Summary Descriptions of Kernel Support Interfaces
Kernel Interface	Summary Description
`assert_wait_mesg`	Asserts that the current kernel thread is about to block (sleep).
`atoi`	Converts an ASCII string to an integer.
`BADADDR`	Probes the address during device autoconfiguration.
`bcmp`	Compares two byte strings.
`bcopy`	Copies a series of bytes with a specified limit.
`biodone`	Indicates that block I/O is complete.
`blkclr`	Zeros a block of memory.
`brelse`	Deallocates a `buf` structure.
`btop`	Converts bytes to number of pages.
`BUF_LOCK`	Locks the specified I/O buffer.
`BUF_UNLOCK`	Unlocks the specified I/O buffer.
`busphys_to_iohandle`	Converts a valid bus physical address to an I/O handle base.
`bzero`	Zeros a block of memory.
`cfgmgr_get_state`	Determines the configuration state.
`cfgmgr_set_status`	Reports failure to the `cfgmgr` framework.
`clear_wait`	Clears the wait condition.
`configure_driver`	Configures a device driver that is in the dynamic state.
`contig_free`	Frees a block of memory previously allocated by `contig_malloc`.
`contig_malloc`	Allocates physically contiguous memory.
`copyin`	Copies data from a user address space to a kernel address space.
`copyinstr`	Copies a null-terminated string from a user address space to a kernel address space.
`copyout`	Copies data from a kernel address space to a user address space.
`copyoutstr`	Copies a null-terminated string from a kernel address space to a user address space.
`copystr`	Copies a null-terminated character string with a specified limit.
`copy_to_phys`	Copies data from a virtual address to a physical address.
`create_controller_struct`	Creates a `controller` structure for the system (hardware) configuration tree.
`create_device_struct`	Creates a `device` structure for the system (hardware) configuration tree.
`current_task`	Returns a pointer to the `task` structure associated with the currently running kernel thread.
`current_thread`	Is a pointer to the currently running kernel thread.
`decl_simple_lock_data`	Declares a simple lock structure.
`DELAY`	Delays the calling interface a specified number of microseconds.
`devsw_add`	Registers driver entry points and reserves a major number.
`devsw_del`	Clears entry points from the device switch table.
`devsw_get`	Obtains a previously reserved major number.
`dma_get_curr_sgentry`	Returns a pointer to the current `sg_entry`.
`dma_get_next_sgentry`	Returns a pointer to the next `sg_entry`.
`dma_get_private`	Gets a data element from the DMA private storage space.
`dma_kmap_buffer`	Returns a kernel segment (kseg) address of a DMA buffer.
`dma_map_alloc`	Allocates resources for DMA data transfers.
`dma_map_dealloc`	Releases and deallocates the DMA resources previously allocated for DMA data transfers.
`dma_map_load`	Loads and sets allocated DMA resources and sets up a DMA data path for DMA data transfers.
`dma_map_unload`	Unloads the system DMA resources.
`dma_min_boundary`	Returns system-level information.
`dma_put_curr_sgentry`	Puts a new bus address/byte count pair in the linked list of `sg_entry` structures.
`dma_put_prev_sgentry`	Updates an internal pointer index to the linked list of `sg_entry` structures.
`dma_put_private`	Stores a data element in the DMA private storage space.
`do_config`	Initializes the device to its assigned configuration.
`drvr_register_flush`	Registers or deregisters a flush interface.
`drvr_register_shutdown`	Registers or deregisters a shutdown interface.
`ffs`	Finds the first set bit in a mask.
`FREE`	Deallocates (frees) the allocated kernel virtual memory.
`fubyte`	Returns a byte from user address space.
`fuibyte`	Returns a byte from user instruction address space.
`fuiword`	Returns a word from user instruction address space.
`fuword`	Returns a word from user instruction address space.
`get_config`	Returns assigned configuration data for a device.
`get_def_partitionmap`	Calculates a default partition map.
`get_info`	Returns system-specific information.
`getnewbuf`	Allocates a `buf` structure.
`gsignal`	Sends a signal to a process group.
`handler_add`	Registers a device driver's interrupt handler.
`handler_del`	Deregisters a device driver's interrupt handler.
`handler_disable`	Disables a previously registered interrupt handler.
`handler_enable`	Enables a previously registered interrupt handler.
`htonl`	Converts longword values from host-to-network byte order.
`htons`	Converts word values from host-to-network byte order.
`insque`	Adds an element to the queue.
`io_copyin`	Copies data from bus address space to system memory.
`io_copyio`	Copies data from bus address space to bus address space.
`io_copyout`	Copies data from system memory to bus address space.
`iodone`	Indicates that I/O is complete.
`iohandle_to_phys`	Converts an I/O handle to a valid system physical address.
`io_zero`	Zeros a block of memory in bus address space.
`IS_KSEG_VA`	Determines if the specified address is located in the kernel-unmapped address space.
`IS_SEG0_VA`	Determines if the specified address is located in the user-mapped address space.
`IS_SEG1_VA`	Determines if the specified address is located in the kernel-mapped address space.
`kernel_isrthread`	Starts a fixed priority kernel thread dedicated to interrupt service.
`kernel_thread_w_arg`	Starts a kernel thread with a calling argument passed in.
`KSEG_TO_PHYS`	Converts a kernel-unmapped virtual address to a physical address.
`lock_done`	Releases a complex lock.
`lock_init`	Initializes a complex lock.
`lock_read`	Asserts a complex lock with read-only access.
`lock_terminate`	Terminates, using a complex lock.
`lock_try_read`	Tries to assert a complex lock with read-only access.
`lock_try_write`	Tries to assert a complex lock with write access.
`lock_write`	Asserts a complex lock with write access.
`major`	Returns the device major number.
`makedev`	Returns a CWdev_t\fP.
`MALLOC`	Allocates a variable-size section of kernel virtual memory.
`mb`	Performs a memory barrier.
`minor`	Returns the device minor number.
`minphys`	Bounds the data transfer size.
`mpsleep`	Blocks (puts to sleep) the current kernel thread.
`ntohl`	Converts longword values from network-to-host byte order.
`ntohs`	Converts word values from network-to-host byte order.
`ovbcopy`	Copies a byte string with a specified limit.
`panic`	Causes a system crash.
`physio`	Implements raw I/O.
`PHYS_TO_KSEG`	Converts a physical address to a kernel-unmapped virtual address.
`pmap_extract`	Extracts a physical page address.
`pmap_kernel`	Returns the physical map handle for the kernel.
`pmap_set_modify`	Sets the modify bits of the specified physical page.
`printf`	Prints text to the console and the error logger.
`privileged`	Checks for proper privileges.
`psignal`	Sends a signal to a process.
`queue_init`	Initializes the specified queue.
`READ_BUS_D8`	Reads a byte (8 bits) from a device register.
`READ_BUS_D16`	Reads a word (16 bits) from a device register.
`READ_BUS_D32`	Reads a longword (32 bits) from a device register.
`READ_BUS_D64`	Reads a quadword (64 bits) from a device register.
`readdisklabel`	Reads a disk label from a device.
`read_io_port`	Reads data from a device register.
`register_callback`	Registers a callback request (interface).
`remque`	Removes an element from the queue.
`rmalloc`	Allocates size units from the given resource map.
`rmfree`	Frees space previously allocated into the specified resource map.
`rmget`	Allocates size units from the given resource map.
`rminit`	Initializes a resource map.
`round_page`	Rounds the specified address.
`rt_post_callout`	Posts an interface to be called at a lower IPL.
`rt_post_callout_ipl`	Posts an interface to be called at a specified IPL.
`select_dequeue`	Removes the last kernel thread waiting for an event.
`select_dequeue_all`	Removes all kernel threads waiting for an event.
`select_enqueue`	Adds the current kernel thread.
`select_wakeup`	Wakes up a kernel thread.
`setdisklabel`	Sets a disk label.
`simple_lock`	Asserts a simple lock.
`simple_lock_init`	Initializes a simple lock structure.
`simple_lock_terminate`	Terminates, using a simple lock.
`simple_lock_try`	Tries to assert a simple lock.
`simple_unlock`	Releases a simple lock.
`sleep`	Puts a calling process to sleep.
`spl`	Sets the processor priority to mask different levels of interrupts.
`strcmp`	Compares two null-terminated character strings.
`strcpy`	Copies a null-terminated character string.
`strlen`	Returns the number of characters in a null-terminated string.
`strncmp`	Compares two strings, using a specified number of characters.
`strncpy`	Copies a null-terminated character string with a specified limit.
`subyte`	Writes a byte into user address space.
`suibyte`	Writes a byte into user instruction address space.
`suiword`	Writes a word into user instruction address space.
`suser`	Checks whether the current user is the superuser.
`suword`	Writes a word into user address space.
`svatophys`	Converts a system virtual address to a physical address.
`swap_lw_bytes`	Performs a longword byte swap.
`swap_word_bytes`	Performs a short word byte swap.
`swap_words`	Performs a word byte swap.
`thread_block`	Blocks (puts to sleep) the current kernel thread.
`thread_halt_self`	Handles asynchronous traps for self-terminating kernel threads.
`thread_set_timeout`	Sets a timer for the current kernel thread.
`thread_terminate`	Prepares to stop or stops execution of the specified kernel thread.
`thread_wakeup`	Wakes up all kernel threads waiting for the specified event.
`thread_wakeup_one`	Wakes up the first kernel thread waiting on a channel.
`timeout`	Initializes a callout queue element.
`trunc_page`	Truncates the specified address.
`uiomove`	Moves data between user and system virtual space.
`unconfigure_driver`	Unconfigures a device driver that was dynamically configured.
`unix_master`	Forces execution onto the master CPU.
`unix_release`	Releases binding of the kernel thread.
`unregister_callback`	Deregisters a callback request (interface).
`untimeout`	Removes the scheduled interface from the callout queues.
`uprintf`	Is a nonsleeping kernel printf function.
`vm_map_pageable`	Sets pageability of the specified address range.
`vtop`	Converts any virtual address to a physical address.
`wakeup`	Wakes up all processes sleeping on a specified address.
`WRITE_BUS_D8`	Writes a byte (8 bits) to a device register.
`WRITE_BUS_D16`	Writes a word (16 bits) to a device register.
`WRITE_BUS_D32`	Writes a longword (32 bits) to a device register.
`WRITE_BUS_D64`	Writes a quadword (64 bits) to a device register.
`writedisklabel`	Writes a disk label.
`write_io_port`	Writes data to a device register.

C.3 ioctl Commands

When defining ioctl commands that your driver supports, use a set of macros defined in /usr/sys/include/sys/ioctl.h to construct these definitions. These macros instruct the kernel on how much data, if any, is transferred between the application program making the ioctl system call and the device driver. Table C-3 describes the macros defined in /usr/sys/include/sys/ioctl.h as well as some ioctl commands defined in /usr/sys/include/sys/ioctl_compat.h. Chapter 2 of Writing Device Drivers: Reference provides reference descriptions of the ioctls listed in the table.

Table C-3: Summary Descriptions of ioctl Commands
ioctl Macro/Command	Summary Description
`DEVGETGEOM`	Obtains device geometry information.
`DEVIOCGET`	Obtains information about a device.
`_IO`	Defines `ioctl` types for device control operations.
`_IOR`	Defines `ioctl` types for device control operations.
`_IOW`	Defines `ioctl` types for device control operations.
`_IOWR`	Defines `ioctl` types for device control operations.

C.4 List of Global Variables

Table C-4 summarizes the global variables that device drivers use. Chapter 2 of Writing Device Drivers: Reference provides reference descriptions of the global variables listed in Table C-4.

Table C-4: Summary Descriptions of Global Variables
Global Variable	Summary Description
`cpu`	Provides a unique logical processor-type family identifier.
`hz`	Stores the number of clock ticks per second.
`lbolt`	Is a periodic wakeup mechanism.
`page_size`	Is the virtual page size.

C.5 List of Data Structures

Table C-5 summarizes the structures that device drivers use. Chapter 3 of Writing Device Drivers: Reference provides reference descriptions of the structures listed in Table C-5.

Table C-5: Summary Descriptions of Data Structures
Structure Name	Meaning
`Assign_table`	Defines members used in device special file creation.
`buf`	Describes arbitrary I/O.
`bus`	Represents an instance of a bus entity to which other buses or controllers are logically attached.
`cfg_attr_t`	Contains information for managing the loading and unloading of drivers.
`cfg_subsys_attr_t`	Contains attribute information for drivers.
`controller`	Contains members that store information about hardware resources and store data for communication between the kernel and the device driver.
`controller_config`	Contains information needed to create a `controller` structure.
`DEVGEOMST`	Stores disk device geometry.
`devget`	Contains information about a device.
`device`	Contains information that identifies the device. There is one `device` data structure for each device connected to the controller.
`device_config`	Contains information needed to create a `device` structure.
`device_info_t`	Is the top-level union that stores bus- and device-type information.
`disklabel`	Stores disk device label information.
`driver`	Defines driver entry points and other driver-specific information. You initialize this data structure in the device driver.
`dsent`	Defines a device driver's entry points and other information.
`handler_intr_info`	Contains interrupt handler information.
`ihandler_t`	Contains information associated with device driver interrupt handling.
`item_list`	Contains hardware platform-specific information.
`lock`	Contains complex lock-specific information.
`port`	Contains information about a port.
`pt_tbl`	Stores a disk partition map.
`sel_queue`	Defines a queue of select events.
`sg_entry`	Contains bus address/byte count pairs.
`slock`	Contains simple lock-specific information.
`task`	Contains task-specific information.
`thread`	Contains kernel threads-related information.
`uio`	Describes I/O, either single vector or multiple vectors.
`v1_bustype_info_t`	Stores bus information.
`v1_device_info_t`	Is the top-level union that stores bus- and device-type information.
`v1_devtype_info_t`	Stores device-type information.
`v1_disk_dev_info_t`	Stores disk information.
`v1_tape_dev_info_t`	Stores tape information.

C.6 List of Device Driver Interfaces

Table C-6 summarizes the interfaces that device drivers use. Chapter 4 of Writing Device Drivers: Reference provides reference descriptions of the driver interfaces listed in Table C-6. The table has the following columns:

Interface
This column lists the driver interface name.
Entry point
This column lists the structure (or file) where the driver writer defines the entry point for the device driver interface.
Character
A Yes appears in this column if the interface is applicable to a character device. Otherwise, N/A (not applicable) appears.
Block
A Yes appears in this column if the interface is applicable to a block device. Otherwise, N/A (not applicable) appears.

Table C-6: Summary of Block and Character Device Driver Interfaces
Interface	Entry Point	Character	Block
`callback`	N/A	Yes	Yes
`cattach`	`driver`	Yes	Yes
`close`	`dsent`	Yes	Yes
`configure`	N/A	Yes	Yes
`ctrl_unattach`	`driver`	Yes	Yes
`dattach`	`driver`	Yes	Yes
`dev_unattach`	`driver`	Yes	Yes
`dump`	`dsent`	N/A	Yes
`flush`	N/A	Yes	Yes
`intr`	Use the `handler_add` and `handler_enable` interfaces for registration of interrupt handlers	Yes	Yes
`ioctl`	`dsent`	Yes	Yes
`mmap`	`dsent`	Yes	N/A
`open`	`dsent`	Yes	Yes
`probe`	`driver`	Yes	Yes
`psize`	`dsent`	N/A	Yes
`read`	`dsent`	Yes	N/A
`reset`	`dsent`	Yes	N/A
`select`	`dsent`	Yes	N/A
`shutdown`	N/A	Yes	Yes
`slave`	`driver`	Yes	Yes
`stop`	`dsent`	Yes	N/A
`strategy`	`dsent`	N/A °	Yes
`write`	`dsent`	Yes	N/A

C.7 List of Bus Configuration Interfaces

Table C-7 summarizes the bus configuration interfaces related to device drivers. Chapter 4 of Writing Device Drivers: Reference provides reference descriptions of the bus configuration interfaces listed in Table C-7.

Table C-7: Summary Descriptions of Bus Configuration Interfaces
Bus Interface	Summary Description
`adp_handler_add`	Registers a driver's interrupt handler.
`adp_handler_del`	Deregisters a driver's interrupt handler.
`adp_handler_disable`	Signifies that the driver's interrupt handler is not callable.
`adp_handler_enable`	Signifies that the driver's interrupt handler is now callable.
`adp_unattach`	Cleans up any in-memory data structures.
`bus_search`	Searches a `bus` structure for specified values.
`conn_bus`	Connects `bus` structures.
`conn_ctlr`	Connects a `controller` structure to a `bus` structure.
`conn_device`	Connects a `device` structure to a `controller` structure.
`ctlr_search`	Searches for a `controller` structure connected to a specific bus.
`get_bus`	Searches the static `bus_list` array for a `bus` structure.
`get_ctlr`	Searches the static `ctlr_list` array for a `controller` structure.
`get_ctlr_num`	Gets a `controller` structure that matches the specified controller name and number.
`get_device`	Searches for the next device in a `controller` structure.
`get_sys_bus`	Returns a pointer to a system `bus` structure.
`perf_init`	Initializes the performance structure for a disk device.
`xxconfl1`	Configures the specified bus.
`xxconfl2`	Configures the specified bus.