VAX/VMS Guide to Writing a Device Driver

This document, the VAX/VMS Guide to Writing a Device Driver (Order No. AA-H499B-TE, March 1980), is a technical manual for system programmers.

Purpose: It explains how to write custom device drivers for hardware devices not natively supported by the VAX/VMS operating system (specifically version V02) and how to load these drivers into the system.

Target Audience: System programmers already familiar with the VAX-11 processor and the VAX/VMS operating system. The manual primarily focuses on writing drivers for devices attached to the UNIBUS, with additional information for MASSBUS devices.

Key Content Areas:

1. Introduction to Device Drivers: Covers fundamental concepts like the asynchronous nature of drivers, fork processes, process and interrupt contexts, the VAX/VMS I/O data base (including control blocks like DDB, UCB, CRB, IDB, ADP, CCB, and I/O Request Packets), and synchronization mechanisms (Interrupt Priority Levels, Fork Queues, Resource Wait Queues). It also distinguishes between programmed I/O and Direct Memory Access (DMA) I/O, and buffered vs. direct I/O.
2. Functions of a Device Driver: Details the various routines a driver comprises, such as Initialization, Function Decision Table (FDT) routines for I/O preprocessing, Start I/O routines for device activation, Interrupt Service Routines, Device Timeout Handlers, Cancel I/O routines, and Error-Logging routines.
3. UNIBUS Adapter Considerations: Explains how the UNIBUS adapter facilitates DMA transfers, including reading/writing device registers, mapping UNIBUS and SBI addresses, and using buffered and direct data paths.
4. I/O Processing Overview: Provides a high-level view of how VAX/VMS processes I/O requests, from user process requests and system preprocessing to device activation and I/O completion.
5. Coding Guidelines: Offers practical "how-to" chapters on coding:
   • Driver Tables: How to create the Driver Prologue Table (DPT), Driver Dispatch Table (DDT), and Function Decision Table (FDT) using VAX/VMS macros.
   • FDT Routines: Details the context, conventions, and exit methods for FDT routines, including VAX/VMS-provided routines for direct and buffered I/O.
   • Start I/O Routine: Describes how this routine activates devices, obtains resources (like controller access, UNIBUS map registers), and waits for interrupts.
   • Interrupt Service Routines: Explains how drivers handle solicited and unsolicited interrupts.
   • I/O Completion and Timeout: Discusses postprocessing and timeout handler functions.
   • Initialization, Cancel I/O, and Error-Logging Routines: Provides specifics on these essential driver components.
6. Loading and Debugging: Covers the process of loading a device driver into the system using the SYSGEN utility (LOAD, CONNECT, RELOAD commands) and outlines techniques for debugging drivers using the XDELTA debugging tool.

The manual includes numerous diagrams, tables, and code examples to illustrate concepts and best practices for writing robust VAX/VMS device drivers.