About This Manual

This manual contains information needed by systems programmers who write device drivers for the SCSI/CAM Architecture interfaces.

Audience

This manual is for systems programmers who:

Use standard library routines to develop programs in the C language
Know one or more UNIX® shells, other than csh
Understand basic Digital UNIX components such as the kernel, shells, processes, configuration, autoconfiguration, and so forth
Understand how to use the Digital UNIX programming tools, compilers, and debuggers
Develop programs in an environment that includes dynamic memory allocation, linked list data structures, multitasking, and symmetric multiprocessing (SMP)
Understand the hardware device for which the driver is being written

New and Changed Features

The information in this manual has not changed since Version 3.0.

Organization

This manual is organized as follows:

Chapter 1 SCSI/CAM Software Architecture

Presents an overview of the Digital UNIX SCSI/CAM Architecture (S/CA).

Chapter 2 CAM User Agent Modules

Describes the User Agent routines that Digital provides for SCSI/CAM peripheral device driver writers.

Chapter 3 S/CA Common Modules

Describes the common data structures, routines, and macros that Digital provides for SCSI/CAM peripheral device driver writers.

Chapter 4 S/CA Generic Modules

Describes the generic routines that Digital provides for SCSI/CAM peripheral device driver writers.

Chapter 5 CAM Data Structures

Describes members of the CAM data structures that SCSI device drivers use.

Chapter 6 SCSI/CAM Configuration Driver Modules

Describes the CAM Configuration driver data structures and routines that call the initialization routines in all the CAM subsystem modules.

Chapter 7 CAM XPT I/O Support Routines

Discusses the Transport (XPT) layer routines used with SCSI device drivers.

Chapter 8 CAM SIM Modules

Discusses the data structures and routines used with the SCSI Interface Module (SIM) layers that interface with the CAM subsystem.

Chapter 9 S/CA Error Handling

Discusses the macro, data structures, and routines that Digital supplies for error handling in SCSI/CAM device drivers.

Chapter 10 S/CA Debugging Facilities

Describes the debugging routines that Digital supplies for SCSI/CAM peripheral device driver writers.

Chapter 11 Programmer-Defined SCSI/CAM Device Drivers

Describes and provides examples of how programmers can define SCSI/CAM device drivers.

Chapter 12 SCSI/CAM Special I/O Interface

Describes and provides examples of the SCSI/CAM special I/O interface that Digital supplies to process special SCSI I/O commands.

Appendix A Header Files That SCSI/CAM Device Drivers Use

Summarizes the header files that SCSI/CAM device drivers use.

Appendix B SCSI/CAM Routines in Reference Page Format

Provides more detailed descriptions of the S/CA routines in reference page format.

Appendix C Sample Generic CAM Peripheral Driver

Contains the header file and source file for a sample generic CAM peripheral driver.

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.

Readers of this guide are assumed to be familiar with the following documents:

American National Standard for Information Systems, SCSI-2 Common Access Method: Transport and SCSI Interface Module, working draft, X3T9.2/90-186
Terms used throughout this guide, such as CAM Control Block (CCB), are defined in the American National Standard document. Copies can be purchased from Global Engineering, 2805 McGaw St, Irvine, CA 92714. (Telephone: 800-854-7179)
American National Standard for Information Systems, Small Computer Systems Interface - 2 (SCSI - 2), X3.131-199X

The following documents contain information that pertains to writing device drivers:

Writing Device Drivers: Tutorial
This manual provides information for systems engineers who write device drivers for hardware that runs the Digital UNIX operating system. Systems engineers can find information on driver concepts, device driver interfaces, kernel interfaces used by device drivers, kernel data structures, configuration of device drivers, and header files related to device drivers.
Writing Device Drivers: Reference
This manual contains descriptions of the header files, kernel support interfaces, ioctl commands, global variables, data structures, device driver interfaces, and bus configuration interfaces associated with device drivers. The descriptions are formatted similarly to the Digital UNIX reference pages.
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.
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.

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.

Conventions

This document uses the following conventions:

% A percent sign represents the C shell system prompt.

$ A dollar sign represents the system prompt for the Bourne and Korn shells.

% cat Boldface type in interactive examples indicates typed user input.

file Italic (slanted) type indicates variable values, placeholders, and function argument names.

[ | ]
{ | } In syntax definitions, brackets indicate items that are optional and braces indicate items that are required. Vertical bars separating items inside brackets or braces indicate that you choose one item from among those listed.

Chapter 1	SCSI/CAM Software Architecture
	Presents an overview of the Digital UNIX SCSI/CAM Architecture (S/CA).
Chapter 2	CAM User Agent Modules
	Describes the User Agent routines that Digital provides for SCSI/CAM peripheral device driver writers.
Chapter 3	S/CA Common Modules
	Describes the common data structures, routines, and macros that Digital provides for SCSI/CAM peripheral device driver writers.
Chapter 4	S/CA Generic Modules
	Describes the generic routines that Digital provides for SCSI/CAM peripheral device driver writers.
Chapter 5	CAM Data Structures
	Describes members of the CAM data structures that SCSI device drivers use.
Chapter 6	SCSI/CAM Configuration Driver Modules
	Describes the CAM Configuration driver data structures and routines that call the initialization routines in all the CAM subsystem modules.
Chapter 7	CAM XPT I/O Support Routines
	Discusses the Transport (XPT) layer routines used with SCSI device drivers.
Chapter 8	CAM SIM Modules
	Discusses the data structures and routines used with the SCSI Interface Module (SIM) layers that interface with the CAM subsystem.
Chapter 9	S/CA Error Handling
	Discusses the macro, data structures, and routines that Digital supplies for error handling in SCSI/CAM device drivers.
Chapter 10	S/CA Debugging Facilities
	Describes the debugging routines that Digital supplies for SCSI/CAM peripheral device driver writers.
Chapter 11	Programmer-Defined SCSI/CAM Device Drivers
	Describes and provides examples of how programmers can define SCSI/CAM device drivers.
Chapter 12	SCSI/CAM Special I/O Interface
	Describes and provides examples of the SCSI/CAM special I/O interface that Digital supplies to process special SCSI I/O commands.
Appendix A	Header Files That SCSI/CAM Device Drivers Use
	Summarizes the header files that SCSI/CAM device drivers use.
Appendix B	SCSI/CAM Routines in Reference Page Format
	Provides more detailed descriptions of the S/CA routines in reference page format.
Appendix C	Sample Generic CAM Peripheral Driver
	Contains the header file and source file for a sample generic CAM peripheral driver.

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

%	A percent sign represents the C shell system prompt.
$	A dollar sign represents the system prompt for the Bourne and Korn shells.
`%` `cat`	Boldface type in interactive examples indicates typed user input.
`file`	Italic (slanted) type indicates variable values, placeholders, and function argument names.
[ \| ] { \| }	In syntax definitions, brackets indicate items that are optional and braces indicate items that are required. Vertical bars separating items inside brackets or braces indicate that you choose one item from among those listed.