About This Manual

This book discusses topics related to writing kernel modules for computer systems running the Compaq Tru64^TM UNIX^® (formerly DIGITAL UNIX) operating system.

Audience

This book is intended for systems engineers who:

Understand the design and implementation of the Tru64 UNIX operating system and desire to enhance the functionality of the /vmunix kernel with kernel modules that they write

Understand the basics of the CPU hardware architecture, including interrupts, direct memory access (DMA) operations, and I/O

Use standard library routines to develop programs in the C language

Know the Bourne or some other shell based on the UNIX operating system

Understand basic UNIX operating system concepts, such as kernel, shell, process, configuration, and autoconfiguration

Understand how to use the Tru64 UNIX programming tools, compilers, and debuggers

Develop programs in an environment that involves dynamic memory allocation, linked list data structures, and multitasking

This book assumes that you have a strong background in operating systems based on the UNIX operating system. It also assumes that you have a strong background in systems and C programming. In addition, the book assumes that you have no source code licenses.

New and Changed Features

Writing Kernel Modules is a new book. However, it contains information incorporated from the last released version of Writing Device Drivers: Advanced Topics. The following list summarize changes and additions made since the last release of Writing Device Drivers: Advanced Topics:

New chapters on module initialization, module attributes, dispatch point callbacks, kernel-mode capabilities, and building kernel modules have been added.

Information on locking mechanisms and kernel threads has been revised.

Device driver-specific information previously in Writing Device Drivers: Advanced Topics has been moved to the Writing Device Drivers book, including:
- Using interfaces related to the I/O handle
- Using funnels
- Writing a disk device driver

Scope of the Book

This book is for users of the Tru64 UNIX operating system on computer systems developed by Compaq Computer Corporation. It describes how to develop a kernel module and presents examples where kernel modules can be used. The book also presents examples that show how to use routines associated with symmetric multiprocessing and kernel threads.

The book assumes that you are new to writing kernel modules but may have experience writing device drivers or programming in the UNIX kernel.

Organization

The book contains the following chapters:

Introduction to Kernel Modules

Provides an overview of the chapters in this book. Defines kernel modules, presents a high-level model for using kernel modules, presents reasons for writing a kernel module, and describes general rules for writing a kernel module.

Module Initialization

Describes how to initialize a kernel module using the configure routine.

Module Attributes

Describes setting module attributes and the module attribute table.

Dispatch Point Callbacks

Describes the boot timeline and how to implement callbacks in a kernel module.

Kernel-Mode Capabilities

Describes programming capabilities available in kernel mode.

Symmetric Multiprocessing and Locking Methods

Provides an overview of the SMP environment, including guidelines for selecting a locking method.

Simple Lock Routines

Describes how to define and use simple locks in an SMP environment.

Complex Lock Routines

Describes how to define and use complex locks in an SMP environment.

Kernel Threads

Provides an introduction to multithreaded programming for kernel modules and discusses using kernel threads.

Building and Testing a Kernel Module

Describes key steps for creating a single binary module (.mod file) and testing the module.

Related Documentation

Icons on Tru64 UNIX Printed Books

The printed version of the Tru64 UNIX documentation uses letter icons on the spines of the books to help specific audiences quickly find the books that meet their needs. (You can order the printed documentation from Compaq.) The following list describes this convention:

G	Books for general users
S	Books for system and network administrators
P	Books for programmers
D	Books for device driver writers
R	Books for reference page users

Some books in the documentation 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 provides information on all of the books in the Tru64 UNIX documentation set.

Writing kernel modules is a complex task; 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

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

Hardware Documentation

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

Bus-Specific Device Driver Documentation

Writing Device Drivers is the core book for developing device driver kernel modules on the Tru64 UNIX Version 5.0A operating system. It contains information needed for developing modules on any bus that operates on Compaq platforms.

Reference Pages, Section 9r, Device Drivers (Volume 1) and Reference Pages, Section 9s, 9u, and 9v, Device Drivers (Volume 2) describe the routines, data structures, and global variables that device drivers use.

The following books provide information about writing device drivers for a specific bus:

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 routines. The manual provides an overview of the Tru64 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 routine that the operating system supplies 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 routines 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 routines that VMEbus device drivers use.

Operating System Overview Documentation

Refer to the Technical Overview for a technical introduction to the Tru64 UNIX operating system.

This manual provides a technical overview of the Tru64 UNIX system, focusing on the networking subsystem, the file system, virtual memory, and the development environment. This manual does not supersede the Software Product Description (SPD), which is the definitive description of the Tru64 UNIX system.

Programming Tools Documentation

To create your kernel modules, 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 Tru64 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 Tru64 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 Tru64 UNIX operating system, with an emphasis on the C programming language. This manual is for all programmers who use the Tru64 UNIX operating system to create or maintain programs in any supported language.

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 Tru64 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.

Reader's Comments

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

You can send your comments in the following ways:

Fax: 603-884-0120 Attn: UBPG Publications, ZKO3-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:
Compaq Computer Corporation
UBPG Publications Manager
ZKO3-3/Y32
110 Spit Brook Road
Nashua, NH 03062-2698

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 Tru64 UNIX that you are using.

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

The Tru64 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 Compaq technical support office. Information provided with the software media explains how to send problem reports to Compaq.

Conventions

This book uses the following conventions:

. . .: A vertical ellipsis indicates that a portion of an example that would normally be present is not shown.
. . .: In syntax definitions, a horizontal ellipsis indicates that the preceding item can be repeated one or more times.
file: Italic type indicates variable values, placeholders, and function argument names.
buf: In function definitions and syntax definitions used in module configuration, this typeface is used to indicate names that you must type exactly as shown.
[ ]: In formal parameter declarations in function definitions and in structure declarations, brackets indicate arrays. Brackets are also used to specify ranges for device minor numbers and device special files in file fragments. However, for syntax definitions, these brackets indicate items that are optional.
|: Vertical bars separating items that appear in syntax definitions indicate that you choose one item from among those listed.