About This Book

This book provides reference page-style descriptions of the header files and interfaces related to writing device drivers for computer systems running the Digital UNIX® operating system. It is a companion volume to Writing Device Drivers: Tutorial and Writing Device Drivers: Advanced Topics.

Audience

This book is for systems engineers who want reference page descriptions of the header files, kernel interfaces, ioctl commands, global variables, data structures, and device driver interfaces that device driver writers use. Some of these interfaces are discussed and used in the examples in Writing Device Drivers: Tutorial and Writing Device Drivers: Advanced Topics.

A secondary audience is systems engineers who need to implement a new bus or make changes to the implementation of an existing bus. Topics of interest to this audience include descriptions of the bus structure members and the bus configuration interfaces.

New and Changed Features

The following sections summarize the changes and additions made to this version of the book.

Chapter 1: Header Files Related to Device Drivers

The devgetinfo.h header file now has an associated reference page.

Chapter 2: Kernel Interfaces, ioctls, and Global Variables That Device Drivers Use

The following list provides the names of the kernel interfaces that now have an associated reference page:

• atoi

• biodone

• cfgmgr_get_state

• cfgmgr_set_status

• configure_driver

• contig_free

• contig_malloc

• create_controller_struct

• create_device_struct

• current_thread

• drvr_register_flush

• get_def_partitionmap

• readdisklabel

• register_callback

• setdisklabel

• thread_halt_self

• thread_terminate

• unconfigure_driver

• unregister_callback

• writedisklabel

The following list provides the names of the STREAMS-related kernel interfaces that now have an associated reference page:

• allocb

• backq

• bcanput

• bufcall

• canput

• copyb

• copymsg

• datamsg

• dupb

• dupmsg

• enableok

• esballoc

• flushband

• flushq

• freeb

• freemsg

• getq

• insq

• linkb

• msgdsize

• noenable

• OTHERQ

• pullupmsg

• putbq

• putctl

• putctl1

• putnext

• putq

• qenable

• qreply

• qsize

• RD

• rmvb

• rmvq

• strlog

• strqget

• strqset

• testb

• unbufcall

• unlinkb

• WR

The following list provides the names of the kernel interfaces that will be retired in a future release. These interfaces no longer have an associated reference page:

• bdevsw_add

• bdevsw_del

• cdevsw_add

• cdevsw_del

• disable_option

• dualdevsw_add

• dualdevsw_del

• enable_option

• kalloc

• kfree

• kget

• ldbl_ctlr_configure

• ldbl_ctlr_unconfigure

• ldbl_stanza_resolver

• zalloc

• zchange

• zfree

• zget

• zinit

Chapter 3: Structures Related to Device Drivers

The following list provides the name of the structures that now have an associated reference page:

• device_info_t

• disklabel

• pt_tbl

• v1_devtype_info_t

• v1_device_info_t

• v1_devtype_info_t

• v1_disk_dev_info_t

• v1_tape_dev_info_t

The zone data structure will be retired in a future release. It no longer has an associated reference page.

Chapter 4: Device Driver and Bus Configuration Interfaces

The following list provides the names of the device driver interfaces that now have an associated reference page:

• xxcallback

• xxflush

• xxshutdown

The following list provides the names of the bus configuration interfaces that no longer have an associated reference page:

• config_resolver

• ctlr_configure

• ctlr_unconfigure

Organization

The book contains the following chapters.

Chapter 1	Header Files Related to Device Drivers
	Presents, in reference page style, descriptions of the header files that device drivers most commonly use.
Chapter 2	Kernel Interfaces, ioctls, and Global Variables That Device Drivers Use
	Presents, in reference page style, descriptions of the kernel support interfaces, ioctl commands, and global variables that device drivers use.
Chapter 3	Structures Related to Device Drivers
	Presents, in reference page style, descriptions of the data structures that device drivers initialize and reference.
Chapter 4	Device Driver and Bus Configuration Interfaces
	Presents, in reference page style, descriptions of the device driver and bus configuration interfaces.

Related Documentation

The printed version of the Digital UNIX documentation set is color coded to help specific audiences quickly find the books that meet their needs. (You can order the printed documentation from Digital.) This color coding is reinforced with the use of an icon on the spines of books. The following list describes this convention:

Audience	Icon	Color Code
General users	G	Blue
System and network administrators	S	Red
Programmers	P	Purple
Device driver writers	D	Orange
Reference page users	R	Green

Some books in the documentation set help meet the needs of several audiences. For example, the information in some system books is also used by programmers. Keep this in mind when searching for information on specific topics.

The Documentation Overview, Glossary, and Master Index provides information on all of the books in the Digital UNIX documentation set.

Writing device drivers is a complex task; driver writers require knowledge in a variety of areas. One way to acquire this knowledge is to have at least the following categories of documentation available:

• Hardware documentation

• Bus-specific device driver documentation

• Operating system overview documentation

• Programming tools documentation

• Network programming documentation

• System management documentation

• Porting documentation

• Kernel kits product documentation

• Reference pages

The following sections list the documentation associated with each of these categories.

Hardware Documentation

You should have available the hardware manual associated with the device for which you are writing the device driver. You should also have access to the manual that describes the architecture associated with the CPU that the driver operates on, for example, the Alpha Architecture Reference Manual.

Bus-Specific Device Driver Documentation

Writing Device Drivers: Tutorial is the core manual for developing device drivers on the Digital UNIX operating system. It contains information needed for developing drivers on any bus that operates on Digital platforms. Writing Device Drivers: Advanced Topics and Writing Device Drivers: Reference are companion volumes to the tutorial.

Writing Device Drivers: Advanced Topics describes topics that are beyond the scope of the core tutorial. Systems engineers can find information on such advanced topics as kernel threads and writing device drivers in a symmetric multiprocessing (SMP) environment. This book also provides information on how to write disk device drivers.

Writing Device Drivers: Reference describes, in reference-page style, the header files, kernel interfaces, data structures, and other interfaces that device drivers use.

The following books provide information about writing device drivers for a specific bus that is beyond the scope of the core tutorial, advanced topics, and reference:

• Writing EISA and ISA Bus Device Drivers

  This manual provides information for systems engineers who write device drivers for the EISA/ISA bus. The manual describes EISA/ISA bus-specific topics, including EISA/ISA bus architecture and data structures that EISA/ISA bus device drivers use.
  

• Writing PCI Bus Device Drivers

  This manual provides information for systems engineers who write device drivers for the PCI bus. The manual describes PCI bus-specific topics, including PCI bus architecture and data structures that PCI bus device drivers use.

• Writing Device Drivers for the SCSI/CAM Architecture Interfaces

  This manual provides information for systems engineers who write device drivers for the SCSI/CAM Architecture interfaces.

  The manual provides an overview of the Digital UNIX SCSI/CAM Architecture and describes User Agent routines, data structures, common and generic routines and macros, error handling and debugging routines.

  The manual includes information on configuration and installation. Examples show how programmers can define SCSI/CAM device drivers and write to the SCSI/CAM special I/O interface supplied by Digital to process special SCSI I/O commands.

• Writing TURBOchannel Device Drivers

  This manual contains information systems engineers need to write device drivers that operate on the TURBOchannel bus. The manual describes TURBOchannel-specific topics, including TURBOchannel kernel interfaces that TURBOchannel device drivers use.
  

• Writing VMEbus Device Drivers

  This manual contains information systems engineers need to write device drivers that operate on the VMEbus. The manual describes VMEbus-specific topics, including VMEbus architecture and kernel interfaces that VMEbus device drivers use. A VMEbus device driver example illustrates the use of these kernel interfaces.

Operating System Overview Documentation

Refer to the Technical Overview for a technical introduction to the Digital UNIX operating system. This manual provides a technical overview of the Digital UNIX system, focusing on the networking subsystem, the file system, virtual memory, and the development environment. In addition, the manual lists all system limits.

This manual does not supersede the Software Product Description (SPD), which is the definitive description of the Digital UNIX system.

Programming Tools Documentation

To create your device drivers, you use a number of programming development tools and should have on hand the manuals that describe how to use these tools. The following manuals provide information related to programming tools used in the Digital UNIX operating system environment:

• Kernel Debugging

  This manual provides information about debugging kernels. The manual describes using the dbx, kdbx, and kdebug debuggers to find problems in kernel code. It also describes how to write a kdbx utility extension and how to create and analyze a crash dump file.

  This manual is for system administrators responsible for modifying, rebuilding, and debugging the kernel configuration. It is also for system programmers who need to debug their kernel space programs.

• Programming Support Tools

  This manual describes several commands and utilities in the Digital UNIX system, including facilities for text manipulation, macro and program generation, and source file management.

  The commands and utilities described in this manual are primarily for programmers, but some of them (such as grep, awk, sed, and the Source Code Control System (SCCS)) are useful for other users. This manual assumes that you are a moderately experienced user of UNIX systems.
  

• Programmer's Guide

  This manual describes the programming environment of the Digital UNIX operating system, with an emphasis on the C programming language.

  This manual is for all programmers who use the Digital UNIX operating system to create or maintain programs in any supported language.

Network Programming Documentation

Writing Device Drivers: Tutorial does not discuss how to write streams device drivers. However, Writing Device Drivers: Reference contains reference pages for kernel interfaces that STREAMS device drivers use. Refer to the Network Programmer's Guide for general information on STREAMS programming. This manual describes the Digital UNIX network programming environment. It describes in depth the X/Open Transport Interface (XTI) and the sockets and STREAMS programming frameworks, including information about system calls, header files, and libraries. Additionally, it provides information about porting sockets-based applications to XTI.

This manual also describes the software bridge ifnet (STREAMS module and DLPI STREAMS pseudodevice driver) that the Digital UNIX operating system supports. This bridge allows programs that use sockets-based protocol stacks to access STREAMS drivers, and programs that use STREAMS-based protocol stacks to access BSD-based drivers.

This manual is for experienced UNIX programmers and assumes you are familiar with the following:

• C language

• Programming interfaces for UNIX operating systems

• Basic data communications concepts, including the Open System Interconnection 7-layer model

• Typical software interfaces at each layer of the OSI model

• Requirements for writing communications applications

System Management Documentation

Refer to the System Administration manual for information about building a kernel and for general information on system administration. This manual describes how to configure, use, and maintain the Digital UNIX operating system. It includes information on general day-to-day activities and tasks, changing your system configuration, and locating and eliminating sources of trouble.

This manual is for the system administrators responsible for managing the operating system. It assumes a knowledge of operating system concepts, commands, and configurations.

Porting Documentation

Refer to the Digital UNIX Migration Guide for a discussion of the differences between the Digital UNIX and ULTRIX operating systems. This manual compares the Digital UNIX operating system to the ULTRIX operating system by describing the differences between the two systems.

This manual has three audiences, as follows:

• General users can read this manual to determine the differences between using an ULTRIX system and using the Digital UNIX system.

• System and network administrators can read this manual to determine the differences between ULTRIX and Digital UNIX system administration.

• Programmers can read this manual to determine the differences between the ULTRIX programming environment and the Digital UNIX programming environment.

This manual assumes you are familiar with the ULTRIX operating system.

Reference Pages

The following reference pages are of interest to device driver writers:

• Reference Pages Section 2

  This section defines system calls (entries into the Digital UNIX kernel) that programmers use. The introduction to Section 2, intro(2), lists error numbers with brief descriptions of their meanings. The introduction also defines many of the terms used in this section. This section is for programmers.

• Reference Pages Section 3

  This section describes the routines available in Digital UNIX programming libraries, including the C library, Motif library, and X library. This section is for programmers. In printed format, this section is divided into six volumes.

• Reference Pages Section 4

  Section 4 describes the format of system files and how the files are used. The files described include assembler and link editor output, system accounting, and file system formats. This section is for programmers and system administrators. In printed format, this section is divided into two volumes.

• Reference Pages Section 5

  Section 5 contains miscellaneous information, including ASCII character codes, mail-addressing formats, text-formatting macros, and a description of the root file system. This section is for programmers and system administrators.

• Reference Pages Section 7

  Section 7 describes special files, related device driver functions, databases, and network support. This section is for programmers and system administrators.

• Reference Pages Section 8 and 1m

  This section describes commands for system operation and maintenance. It is for system administrators. In printed format, this section is divided into two volumes.

Reader's Comments

Digital welcomes any comments and suggestions you have on this and other Digital UNIX manuals.

You can send your comments in the following ways:

• Fax: 603-881-0120 Attn: UEG Publications, ZK03-3/Y32

• Internet electronic mail: readers_comment@zk3.dec.com

  A Reader's Comment form is located on your system in the following location:

  /usr/doc/readers_comment.txt
  

• Mail:

  Digital Equipment Corporation
  UEG Publications Manager
  ZK03-3/Y32
  110 Spit Brook Road
  Nashua, NH 03062-9987

  A Reader's Comment form is located in the back of each printed manual. The form is postage paid if you mail it in the United States.

Please include the following information along with your comments:

• The full title of the book and the order number. (The order number is printed on the title page of this book and on its back cover.)

• The section numbers and page numbers of the information on which you are commenting.

• The version of Digital UNIX that you are using.

• If known, the type of processor that is running the Digital UNIX software.

The Digital UNIX Publications group cannot respond to system problems or technical support inquiries. Please address technical questions to your local system vendor or to the appropriate Digital technical support office. Information provided with the software media explains how to send problem reports to Digital.