Digital PDFs

AA-PBPWA-TE

December 1990

573 pages

Original

26MB

Document:	. VMS VMS Device Support Manual
Order Number:	AA-PBPWA-TE
Revision:
Pages:	573
Original Filename:	http://bitsavers.org/pdf/dec/vax/vms/5.4/AA-PBPWA-TE_VMS_5.4_Device_Support_Manual_199006.pdf

OCR Text

. VMS

digital

VMS Device Support Manual

Order Number: AA-PBPWA-TE

VMS Device Support
Manual
Order Number: AA-PBPWA-TE

June 1990
This manual describes how to write a driver for a device connected to a VAX
processor. It discusses the required and optional components of a driver and
explains their functions. It details the requirements VMS imposes upon driver
code and includes guidelines for creating, loading, and debugging a driver that
can run on VMS uniprocessing and multiprocessing systems.

Revision/Update Information:

This book supersedes the VMS Device
Support Manual, Version 5.0. The
reference material that was in the original
appendixes is now in the VMS Device
Support Reference Manual, Version 5.4.

Software Version:

VMS Version 5.4

digital equipment corporation
maynard, massachusetts

June 1990

The information in this document is subject to change without notice and should
not be construed as a commitment by Digital Equipment Corporation. Digital
Equipment Corporation assumes no responsibility for any errors that may appear
in this document.
The software described in this document is furnished under a license and may be
used or copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is
not supplied by Digital Equipment Corporation or its affiliated companies.
Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject
to restrictions as set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data
and Computer Software clause at DFARS 252.227-7013.

© Digital Equipment Corporation 1990.
All Rights Reserved.
Printed in U.S.A.
The postpaid Reader's Comments forms at the end of this document request your
critical evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
CDA
DDIF
DEC
DECdtm
DECnet
DECUS
DECwindows
DECwriter

DEQNA
Desktop-VMS
DIGITAL
GIGI
HSC
Live link
LN03
MASS BUS

MicroVAX
PrintServer 40
Q-bus
ReGIS
ULTRIX
UNIBUS
VAX
VAXcluster

VAX RMS
VAXserver
VAXstation
VMS
VT
XUI

mamnnma™

The following is a third-party trademark:
Postscript is a registered trademark of Adobe Systems Incorporated.

ZK5502

Production Note
This book was produced with the VAX DOCUMENT electronic publishing
system, a software tool developed and sold by Digital. In this system,
writers use an ASCII text editor to create source files containing text and
English-like code; this code labels the structural elements of the document,
such as chapters, paragraphs, and tables. The VAX DOCUMENT software,
which runs on the VMS operating system, interprets the code to format
the text, generate a table of contents and index, and paginate the entire
document. Writers can print the document on the terminal or line printer,
or they can use Digital-supported devices, such as the LN03 laser printer
and PostScript printers (PrintServer 40 or LN03R ScriptPrinter), to
produce a typeset-quality copy containing integrated graphics.

Contents
xxv

PREFACE

Part I

THE VMS DEVICE DRIVER ENVIRONMENT

CHAPTER 1 INTRODUCTION TO DEVICE DRIVERS

1-1

1.1

DRIVER FUNCTIONS

1-2

1.2
1.2.1
1.2.2

DRIVER COMPONENTS
Driver Tables
Driver Routines

1-2
1-2
1-3

1.3
1.3.1
1.3.2
1.3.3

THE 1/0 DATABASE
Driver Tables
Data Structures
1/0 Request Packets

1-4
1-4
1-5
1-6

1.4

SYNCHRONIZATION OF DRIVER ACTIVITY

1-7

1.5
1.5.1

DRIVER CONTEXT
Example of Driver Context-Switching

1-7
1-9

1.6
1.6.1

HARDWARE CONSIDERATIONS
Driver Dependency on VAX Processing Systems
VAX-11/780, VAX-11/785, and VAX 8600/8650 Systems• 1-11
The VAX-11/750 System • 1-11
The VAX-11/730 System • 1-13
VAX 82x0/83x0, VAX 85x0/8700/88x0, and VAX 6000-Series
Systems • 1-13
The VAX 9000 Series System • 1-16
The MicroVAX 3400/3600/3900 Series, MicroVAX/VAXstation II,
and VAX 4000 Series Systems • 1-16
The MicroVAX/VAXstation 3100 and VAXstation 3520/3540
Systems • 1-18

1-10
1-10

1.6.1.1
1.6.1.2
1.6.1.3
1.6.1.4
1.6.1.5
1.6.1.6
1.6.1.7

Contents

1.7.1
1.7.2

PROGRAMMED-1/0 AND DIRECT-MEMORY-ACCESS
TRANSFERS
Programmed 1/0
Direct-Memory-Access 1/0

1-21
1-21
1-22

1.8

BUFFERED AND DIRECT 1/0

1-22

1.9

EXAMPLE OF AN 1/0 REQUEST

1-23

1.7

CHAPTER 2 DISCUSSION OF A $QIO REQUEST

2-1

2.1

DRIVER CODE FOR THE LP11 WRITE FUNCTION

2-1

2.2

A USER PROCESS 1/0 REQUEST

2-2

2.3

DEVICE-INDEPENDENT 1/0 PREPROCESSING BY VMS

2-3

2.4

DEVICE-DEPENDENT 1/0 PREPROCESSING BY THE DRIVER

2-3

2.5

QUEUING THE 1/0 REQUEST PACKET TO THE DRIVER

2-4

2.6

ACTIVATING THE PRINTER

2-5

2.7

WAITING FOR A DEVICE INTERRUPT

2-5

2.8

HANDLING INTERRUPTS

2-6

2.9

1/0 POSTPROCESSING BY THE DRIVER

2-7

2.10

1/0 POSTPROCESSING BY VMS

2-7

Contents

CHAPTER 3 SYNCHRONIZATION OF 1/0 REQUEST PROCESSING
3.1
3.1.1
3.1.2

3.1.2.1
3.1.2.2
3.1.2.3
3.1.2.4
3.1.2.5
3.1.3

3.1.3.1
3.1.3.2
3.1.3.3
3.1.3.4
3.1.3.5
3.1.3.6
3.1.3.7
3.1.4

INTERRUPT PRIORITY LEVELS
Interrupt Service Routines
IPL Use During 1/0 Processing
IPL 2 (IPL$_ASTDEL) • 3-4
IPL 4 (IPL$_10POST) • 3-5
IPL 8 to IPL 11 (Fork IPLs) • 3-5

3-1
3-1
3-3
3-4

IPL 20 to IPL 23 (Device IPLs) • 3-6
IPL 31 (IPL$_POWER) • 3-7

Additional IPLs

3-7

IPL 3 (IPL$_RESCHED) • 3-7
IPL 6 (IPL$_QUEUEAST) • 3-7
IPL 7 (IPL$_TIMERFORK) • 3-8
IPL 8 (IPL$_SYNCH) • 3-8
IPL 11 (IPL$_MAILBOX) • 3-8
IPL 14 (XDELTA Entry IPL) • 3-9
IPL 22 or IPL 24 (Interval Clock IPLs) • 3-9

Modifying IPL in Driver Code
Raising IPL• 3-10
Lowering IPL • 3-12

3-9

3.1.4.1
3.1.4.2
3.2
3.2.1
3.2.2

SPIN LOCKS
Fork Locks
Device Locks

3-12
3-16
3-16

3.3
3.3.1
3.3.2
3.3.3

3-17
3-17
3-22
3-22

3.3.3.1
3.3.3.2

DEVICE DRIVER SYNCHRONIZATION
Overview of the Synchronization of an 1/0 Operation
Synchronizing the Device Database
Synchronizing at Driver Fork Level
Forking and the VMS Fork Dispatcher • 3-23
Restrictions on Fork Processes • 3-24

3.4
3.4.1

RESOURCE WAIT QUEUES
Competing for a Controller's Data Channel

3-25
3-26

vii

Contents

CHAPTER 4 OVERVIEW OF 1/0 PROCESSING
4.1
4.1.1
4.1.2

4-4

4.1.3
4.1.4
4.1.5
4.1.6
4.1.7

PREPROCESSING AN 1/0 REQUEST
Process 1/0 Channel Assignment
Locating a Device Driver in the 1/0 Database
Channel Request Block • 4-6
Interrupt Dispatch Block • 4-7
Device Data Block • 4-8
Validating the 1/0 Function
Checking Process 1/0 Request Quotas
Validating the 1/0 Status Block
Allocating and Setting Up an 1/0 Request Packet
FDT Processing

4-8
4-9
4-9
4-9
4-10

4.2
4.2.1
4.2.2
4.2.3
4.2.4
4.2 ..5

HANDLING DEVICE ACTIVITY
Creating a Driver Fork Process to Start 1/0
Activating a Device and Waiting for an Interrupt
Handling a Device Interrupt
Switching from Interrupt to Fork Process Context
Activating a Fork Process from a Fork Queue

4-13
4-13
4-15
4-16
4-17
4-18

4.3
4.3.1

COMPLETING AN 1/0 REQUEST
1/0 Postprocessing

4-19
4-20

4.1.2.1
4.1.2.2
4.1.2.3

Part II

4-5
4-5

WRITING A DEVICE DRIVER

CHAPTER 5 DEVICE DRIVER CODING FORMAT

viii

4-1

5-1

5.1

CODING CONVENTIONS

5-1

5.2

RESTRICTIONS ON THE USE OF DEVICE-REGISTER 1/0 SPACE

5-3

5.3

IMPLEMENTING CONDITIONAL CODE IN A DRIVER

5-5

Contents

CHAPTER6 WRITING DEVICE-DRIVER TABLES

6-1

6.1

DRIVER PROLOGUE TABLE

6-1

6.2

DRIVER DISPATCH TABLE

6-3

6.3
6.3.1
6.3.2

FUNCTION DECISION TABLE
Defining Buffered-110 Functions
Defining Device-Specific Function Codes

6-4
6-7
6-8

CHAPTER 7 WRITING FDT ROUTINES

7-1

7.1

CONTEXT OF FDT ROUTINE EXECUTION

7-1

7.2
7.2.1

7-2
7-3

7.2.1.1
7.2.1.2
7.2.1.3
7.2.1.4
7.2.1.5

FDT ROUTINES AND THEIR EXIT PATHS
FDT Exit Paths
RSB • 7-4
JMP G"EXE$QIODRVPKT • 7-4
JMP G"EXE$FINISHIO or JMP G"EXE$FINISHIOC • 7-4
JMP G"EXE$ABORTIO • 7-5
JSB G"EXE$ALTQUEPKT • 7-5

7.3

FDT ROUTINES FOR VMS DIRECT 1/0

7-6

7.4
7.4.1
7.4.2
7.4.3

FDT ROUTINES FOR VMS BUFFERED 1/0
Checking Accessibility of the User's Buffer
Allocating the System Buffer
Buffered-1/0 Postprocessing

7-6
7-6
7-6
7-8

7.5

FDT ROUTINES PROVIDED BY VMS

7-8

CHAPTER 8 WRITING A START-1/0 ROUTINE
8.1

TRANSFERRING CONTROL TO THE START-1/0 ROUTINE

8-1

Contents

8.2

CONTEXT OF A DRIVER FORK PROCESS

8-1

8.3
8.3.1
8.3.2

8-2
8-2

8.3.3
8.3.4
8.3.5
8.3.6

FUNCTIONS OF A START-1/0 ROUTINE
Obtaining Controller Access
Obtaining and Converting the 110 Function Code and Its
Modifiers
Preparing the Device Activation Bit Mask
Synchronizing Access to the Device Database
Checking for a Local Processor Power Failure
Activating the Device

8.4
8.4.1
8.4.2

WAITING FOR AN INTERRUPT OR TIMEOUT
Expansion of WFIKPCH Macro
IOC$WFIKPCH Routine

8-6
8-6
8-7

CHAPTER 9 WRITING AN INTERRUPT SERVICE ROUTINE

8-5
8-5
8-5

9-1

9.1

INTERRUPT CONTEXT

9-3

9.2

SERVICING A SOLICITED INTERRUPT

9-3

9.3
9.3.1

SERVICING AN UNSOLICITED INTERRUPT
Examples of Unsolicited Interrupts

9-4
9-6

CHAPTER 10 COMPLETING AN 1/0 REQUEST AND HANDLING
TIMEOUTS

10-1
10-1
10-1
10-2

10.1.2.1
10.1.2.2
10.1.2.3

1/0 POSTPROCESSING
EXE$10FORK
Completing an 1/0 Request
Releasing the Controller • 10-2
Saving Status, Count, and Device-Dependent Status • 10-3
Returning Control to the Operating System • 10-3

10.2
10.2.1
10.2.2
10.2.3

TIMEOUT HANDLING ROUTINES
Retrying an 110 Operation
Aborting an 1/0 Request
Sending a Message to the Operator

10-4

10.1
10.1.1
10.1.2

8-4
8-4

10-5
10-6
10-6

Contents

CHAPTER 11 OTHER DRIVER ROUTINES

11-1

11.1
11.1.1
11.1.2
11.1.3
11.1.4
11.1.5

INITIALIZATION ROUTINES
Controller Initialization Routine
Unit Initialization Routine
Initialization During Driver Loading
Initialization During Recovery from a Power Failure
Forking from a Driver Initialization Routine

11-1
11-1
11-3
11-3
11-5
11-6

11.2
11.2.1
11.2.2
11.2.3
11.2.4

CANCEL-1/0 ROUTINE
Context of a Cancel-1/0 Routine
Drivers That Need No Cancel-1/0 Routine
Device-Independent Cancel-1/0 Routine
Device-Dependent Cancel-1/0 Routine

11-6
11-7
11-8
11-8
11-9

11.3
11.3.1
11.3.2
11.3.3

ERROR LOGGING ROUTINES
Error Logging Routines Supplied by VMS
Register Dumping Routine
Interpreting Error Log Entries

11-9
11-10
11-11
11-12

11.4

CLONED UCB ROUTINE

11-12

Part Ill

LOADING AND DEBUGGING A DRIVER

CHAPTER 12 LOADING A DEVICE DRIVER
12.1

12.2
12.2.1
12.2.2
12.2.3
12.2.4
12.2.5
12.2.6
12.2.7
12.2.8

12-1

PREPARING A DRIVER FOR LOADING INTO THE OPERATING
SYSTEM

12-1

LOADING A DRIVER
LOAD Command
CONNECT Command
RELOAD Command
SHOW/ADAPTER Command
SHOW/Bl Command
SHOW/BUS Command
SHOW/XMI Command
SHOW/CONFIGURATION Command

12-2
12-2
12-3
12-7
12-8
12-9
12-10
12-11
12-11
xi

Contents

12.2.9

SHOW/DEVICE Command

12-12

12.3

LOADING UNIPROCESSING AND MULTIPROCESSING DRIVERS

12-13

12.4
12.4.1
12.4.2
12.4.3
12.4.4
12.4.5

THE SYSGEN AUTOCONFIGURATION FACILITY
SVSGEN Device Table
Device Driver Control of Autoconfiguration
Floating-Vector Address Calculation
Floating-CSR Address Calculation
Rules for Configuration

12-13
12-14
12-21
12-22
12-22
12-22

CHAPTER13 DEBUGGING A DEVICE DRIVER

xii

13-1

13.1

BOOTSTRAPPING THE SYSTEM WITH XDELTA

13-1

13.2

PROCEEDING FROM THE INITIAL BREAKPOINTS

13-5

13.3

LOADING THE DRIVER

13-5

13.4

INSERTING BREAKPOINTS IN DRIVER SOURCE CODE

13-6

13.5

CALCULATING THE BASE OF DRIVER CODE

13-7

13.6

REQUESTING AN XDELTA SOFTWARE INTERRUPT

13-7

13.7

EXAMINING THE VECTOR-JUMP TABLE

13-9

13.8

SETTING AN XDELTA BASE REGISTER

13-9

13.9

EXAMINING THE UCB, IRP, OR PSL

13-10

13.10
13.10.1
13.10.2
13.10.2.1
13.10.2.2
13.10.2.3

XDELTA COMMANDS
Values and Expressions
Special Symbols

13-10
13-12
13-13

Stored Base Registers • 13-13
Stored Command Strings • 13-13
Setting Base Registers • 13-14

Contents

13-14
13-14
13-15

13.10.8.1

Display Names and Locations of Loaded Executive Images
Set Display Mode
Open, Examine, and Close Location
Open and Display Value Command • 13-15
Display Instruction Command • 13-16
Close and Display Next Location Command • 13-16
Display Range Command • 13-16
Indirect Command • 13-17
Display Previous Location Command • 13-17
Breakpoints
Setting Breakpoints • 13-17
Clearing Breakpoints • 13-18
Displaying Breakpoint List • 13-18
Proceeding from Breakpoints • 13-18
Setting Complex Breakpoints • 13-18
Step, Set Location, and Execute Instruction Commands
Loading PC and Continuing • 13-18
Execute Instruction and Step Command • 13-19
Step Instruction over Subroutine Command • 13-19
Execute String Command
Locating Nonpaged System Patch Space • 13-20

13.11
13.11.1
13.11.2
13.11.3

GUIDELINES FOR DEBUGGING DEVICE DRIVERS
Opening Device Registers in XDELTA
Adjusting the Device Timeout Value
XDELTA and System Failures

13-21
13-21
13-21
13-21

13.12
13.12.1
13.12.2
13.12.3

COMMON DRIVER ERRORS
References to System Addresses
Incorrect References to Device Registers
Destroying Register Contents

13-22
13-22
13-22
13-22

13.13

POOL CHECKING MECHANISM

13-23

13.14

DETECTING DRIVER PROBLEMS IN A MULTIPROCESSING
SYSTEM

13-28

13.10.3
13.10.4
13.10.5

13.10.5.1
13.10.5.2
13.10.5.3
13.10.5.4
13.10.5.5
13.10.5.6
13.10.6

13.10.6.1
13.10.6.2
13.10.6.3
13.10.6.4
13.10.6.5
13.10.7

13.10.7.1
13.10.7.2
13.10.7.3
13.10.8

13-17

13-18

13-19

xiii

Contents

Part IV

BUS SPECIFICS AND ADVANCED TOPICS

CHAPTER14 UNIBUS AND Q22 BUS DEVICE SUPPORT
14.1
14.1.1
14.1.2
14.1.3
14.1.3.1
14.1.3.2
14.1.3.3
14.1.3.4
14.1.3.5

14.2

xiv

FUNCTIONS OF THE UNIBUS ADAPTER AND Q22 BUS
INTERFACE
Reading and Writing Device Registers
Map Registers
UNIBUS Adapter Data Transfer Paths
Direct Data Path • 14-10
Buffered Data Paths • 14-11
Byte-Offset Data Transfers • 14-13
Purging a Buffered Data Path • 14-14
Longword-Aligned, 32-Bit, Random-Access Mode • 14-14

14.2.1
14.2.1.1
14.2.1.2
14.2.1.3
14.2.1.4
14.2.2
14.2.2.1
14.2.2.2
14.2.3
14.2.4
14.2.5
14.2.6
14.2.7
14.2.7.1
14.2.7.2
14.2.7.3

WRITING DRIVER CODE FOR UNIBUS/Q22 BUS OMA
TRANSFERS
Selecting and Requesting a Data Path
Requesting a Buffered Data Path • 14-17
Requesting a Permanent Buffered Data Path • 14-18
Requesting the Direct Data Path • 14-18
Mixed Use of Direct and Buffered Data Paths • 14-19
Requesting Map Registers
Allocating Map Registers • 14-19
Permanently Allocating Map Registers • 14-20
Loading Map Registers
Computing the Starting Address of a Transfer
Computing the Transfer Length
Activating the Device
Completing a OMA Transfer
Purging the Data Path • 14-24
Releasing a Buffered Data Path • 14-25
Releasing Map Registers • 14-26

14.3
14.3.1
14.3.2
14.3.3
14.3.4
14.3.4.1

INTERRUPT DISPATCHING IN A UNIBUS/Q22 BUS SYSTEM
Direct-Vector and Non-Direct-Vector Interrupt Dispatching
Adapter Dispatch Table
Interrupt Transfer Vector and Interrupt Transfer Routine
Multilevel Device Interrupt Dispatching for Q22 Bus Devices
Ensuring That the 022 Bus Is Properly Configured • 14-34

14-1

14-1
14-4
14-4
14-7

14-15
14-17

14-19

14-21
14-22
14-23
14-23
14-24

14-26
14-28
14-30
14-30
14-33

Contents

14.3.4.2

Effects of Enabling Multilevel Device Interrupt
Dispatching • 14-35

CHAPTER15 MASSBUS DEVICE SUPPORT

15-1

15.1
15.1.1
15.1.2
15.1.3

MASSBUS ADAPTER REGISTERS
Loading MASSBUS Adapter Registers
MASSBUS Adapter Registers and Offsets
Modifying MASSBUS Adapter Registers

15-1
15-3
15-4
15-6

15.2

1/0 DATABASE FOR MASSBUS DEVICES

15-7

15.3

MASSBUS ADAPTER OPERATIONS

15-9

15.4
15.4.1
15.4.2

MASSBUS ADAPTER'S INTERRUPT DISPATCHING
Checking for MASSBUS Adapter Ownership
Dispatching a Device Interrupt

15-10
15-10
15-11

15.5
15.5.1
15.5.2
15.5.3

15-12
15-12
15-13
15-13

15.5.4

SPECIAL CONSIDERATIONS FOR MASSBUS DEVICE DRIVERS
Unit Initialization Routine
The MASSBUS Adapter and the 1/0 Database
Start-1/0 Routine
Requesting Controller Data Channels • 15-14
Loading Map Registers • 15-14
Releasing Controller Data Channels • 15-15
DPTAB Macro

15.6
15.6.1
15.6.2
15.6.3

INTERRUPT SERVICE ROUTINES FOR MASSBUS DEVICES
Transferring Control to the Interrupt Service Routine
Returning Control to MBA$1NT
Considerations for Interrupt Service Routines

15-15
15-16
15-16
15-17

15.5.3.1
15.5.3.2
15.5.3.3

CHAPTER 16 GENERIC VAXBI DEVICE SUPPORT
16.1

OVERVIEW

15-15

16-1

Contents

16.2
16.2.1
16.2.2

VAXBI CONCEPTS
VAXBI Address Space
Backplane Interconnect Interface Chip (BllC)

16-1
16-2
16-5

16.3

SCU/XMI CONCEPTS

16-5

16.4
16.4.1
16.4.2

INITIALIZATION PERFORMED BY VMS
Data Structures
System Control Block

16-7
16-8
16-10

16.5
16.5.1
16.5.2

16-11
16-13

16.5.2.1
16.5.2.2
16.5.2.3
16.5.2.4
16.5.2.5
16.5.3

INITIALIZATION PERFORMED BY THE VAXBI DEVICE DRIVER
Examining BllC Self-Test Status
Clearing BllC Errors, Setting Interrupts, and Enabling
Interrupts
Clearing the Bus Error Register • 16-15
Loading the Interrupt Destination Register • 16-15
Setting Interrupt Vectors • 16-15
Enabling Error Interrupts • 16-16
Enabling BllC Options • 16-16
Mapping Window Space

16.6
16.6.1

OMA TRANSFERS
Example: DMB32 Asynchronous/Synchronous Multiplexer

16-18
16-20

16.7

UNIT INITIALIZATION ROUTINE

16-22

16.8

16-22

16.9

LOADING A VAXBI DEVICE DRIVER

16-23

16.10

BllC REGISTER DEFINITIONS

16-23

CHAPTER 17 SCSI CLASS DRIVER SUPPORT
17.1

xvi

VAX SYSTEMS WITH SCSI BUS CONCEPTS

16-14

16-16

17-1

Contents

17.2
17.2.1
17.2.2
17.2.3

SCSI CLASS/PORT ARCHITECTURE
SCSI Port Interface
SCSI-Specific Data Structures
SCSI Class Driver Template

17-2
17-5
17-7
17-9

17.3

CONNECTING TO A SCSI DEVICE

17-9

17.4
17.4.1
17.4.2
17.4.3

SETTING UP A SCSI COMMAND
Preparing a SCSI Command Descriptor Block
Setting Command Timeouts
Disabling Command Retry

17-10
17-10
17-12
17-12

17.5
17.5.1
17.5.2
17.5.3
17.5.4

17-13
17-13
17-14
17-14

17.5.5
17.5.6
17.5.6.1
17.5.6.2
17.5.6.3

PERFORMING A SCSI DATA TRANSFER
Setting the Data Transfer Mode
Enabling Disconnection and Reselection
Determining the Maximum Data Transfer Size
Initializing the SCDRP to Reflect Class Driver Data Buffering
Mechanisms
Making a Class Driver Data Buffer Accessible to the Port
Examining Port and SCSI Status
Examining Port Status • 17-17
Examining the SCSI Status Byte • 17-18
Testing for Incomplete Transfers • 17-19

17.6
17.6.1
17.6.2

OTHER SCSI CLASS DRIVER ISSUES
Preserving Local Context
Error Logging

17.7

FLOW OF A READ 1/0 REQUEST THROUGH THE SCSI CLASS AND PORT
DRIVERS
17-22

17.8
17.8.1
17.8.2
17.8.3
17.8.4
17.8.5
17.8.6
17.8.7
17.8.8
17.8.9

COMPONENTS OF A SCSI CLASS DRIVER
Data Definitions
Driver Prologue Table
Driver Dispatch Table
Function Decision Table and FDT Routines
Controller Initialization Routine
Unit Initialization Routine
Start-1/0 Routine
Cancel-1/0 Routine
Register Dumping Routine

17-15
17-16
17-17

17-19
17-19
17-20

17-24
17-24
17-25
17-25
17-25
17-25
17-26
17-27
17-28
17-28
xvii

Contents

17.9

SERVICING ASYNCHRONOUS EVENTS FROM A SCSI DEVICE

17-28

17.10
17.10.1

CONFIGURING A SCSI THIRD-PARTY DEVICE
Disabling the Autoconfiguration of a SCSI Device

17-30
17-31

17.11
17.11.1
17.11.2

DEBUGGING A SCSI CLASS DRIVER
Selecting a SCSI Bus Analyzer
Interpreting SCSI Error Log Entries
SCSI Port Driver Error Log Entries • 17-33
SCSI Class Driver Error Log Entries • 17-38

17-31
17-32
17-33

17.11.2.1
17.11.2.2
17.12

RESOLVING SCSI CLASS DRIVER PROBLEMS USING ERROR
LOGS

CHAPTER18 TERMINAL CLASS AND PORT DRIVERS

18-1

18.1

OVERVIEW

18-2

18.2
18.2.1
18.2.2
18.2.3
18.2.4

18-2
18-2
18-4
18-5
18-6

18.2.4.1
18.2.4.2
18.2.4.3

DATA STRUCTURES
Terminal UCB
Port Driver Vector Table
Class Driver Vector Table
Vector Table Generation Macros
$VECINI Macro • 18-6
$VEC Macro • 18-6
$VECEND Macro • 18-6

18.3
18.3.1

STRUCTURE OF PORT AND CLASS DRIVERS
Binding Class and Port Drivers

18-7
18-9

18.4
18.4.1

PORT DRIVER ROUTINES
Port Startup Routines
Controller Initialization Routine • 18-12
Unit Initialization Routine • 18-12
Port Initiate Routines
PORT_DISCONNECT • 18-13
PORT_DS_SET • 18-13
PORT_FDT • 18-14
PORT_FORKRET • 18-14
PORT_MAINT • 18-15

18-11
18-12

18.4.1.1
18.4.1.2
18.4.2

18.4.2.1
18.4.2.2
18.4.2.3
18.4.2.4
18.4.2.5
xviii

17-39

18-13

Contents

18.4.2.6
18.4.2.7
18.4.2.8
18.4.3
18.4.3.1
18.4.3.2
18.4.3.3
18.4.3.4
18.4.3.5
18.4.3.6
18.4.3.7

PORT_SET_LINE • 18-15
PORT_SET_MODEM • 18-15
PORT_STARTIO • 18-16
Port Service Routines
PORT_ABORT • 18-16
PORT_CANCEL • 18-17
PORT_RESUME • 18-17
PORT_STOP • 18-17
PORT_XOFF • 18-17
PORT_XON • 18-18
Port Interrupt Service Routines • 18-18

18.5
18.5.1
18.5.2
18.5.3
18.5.4
18.5.5
18.5.6
18.5.7
18.5.8
18.5.9

CLASS DRIVER ROUTINES
CLASS_DDT
CLASS_DISCONNECT
CLASS_DS_TRANS
CLASS_FORK
CLASS_GETNXT
CLASS_PUTNXT
CLASS_SETUP_UCB
CLASS_POWERFAIL
CLASS_READERROR

18-16

18-19
18-19
18-19
18-20
18-20
18-20
18-21
18-22
18-22
18-22

CHAPTER 19 MAPPING TO 1/0 SPACE AND THE CONNECT-TO-INTERRUPT
FACILITY
19-1
19.1

1/0 ADDRESS SPACE

19-1

19.2
19.2.1

PFN MAPPING
Notes on PFN Mapping

19-5
19-7

19.3
19.3.1
19.3.2
19.3.3
19.3.4
19.3.4.1
19.3.4.2
19.3.4.3
19.3.4.4
19.3.5

CONNECTING TO AN INTERRUPT VECTOR
Performing the Connect-to-Interrupt
$QIO Connect-to-Interrupt Request to Driver
The Connect-to-Interrupt Driver (CONINTERR.EXE)
Process-Specified Routines
Unit Initialization Routine • 19-15
Start-110 Routine • 19-15
Interrupt Service Routine • 19-16
Cancel-1/0 Routine • 19-18
AST Procedure

19-7
19-8
19-9
19-13
19-13

19-19

xix

Contents

19.4
19.4.1
19.4.2
19.4.3

Part V

REAL-TIME APPLICATIONS EXAMPLES
Example 1: KW11-W Watchdog Timer
Example 2: AD11-K, AM11-K A/D Converter with Multiplexer
Connected to the UNIBUS
Example 3: KW11-P Real-Time Clock and AD11-K Converter
Connected to the UNIBUS

19-19
19-20
19-21
19-23

DRIVER TEMPLATES AND EXAMPLES

APPENDIX A VMS DRIVER TEMPLATE

A-1

APPENDIX B VMS SCSI CLASS DRIVER TEMPLATE

B-1

APPENDIX C SAMPLE DRIVER FOR THE RL11, RL01, AND RL02 DISK
DRIVES

C-1

APPENDIX D SAMPLE DRIVER FOR THE DR11-W AND DRV11-WA
INTERFACES

0-1

APPENDIX E MULTIPROCESSING REQUIREMENTS ON KERNEL-MODE
CODE

E-1

E.1
E.1.1
E.1.2
E.1.3

UNIPROCESSOR AND MULTIPROCESSOR DEVICE DRIVERS
MULTIPROCESSING System Parameter
Device Driver Loading
VMS Synchronization Macros

E.2

CHANGES REQUIRED TO DRIVERS WRITTEN BEFORE
VMS VERSION 5.0
Address of the Driver's Interrupt Service Routine in the DPT
Checking, Debiting, and Crediting a Process's Byte Count
Quota
Referring to the Current PCB
Allocating System Page-Table Entries
Referring to a System Process Mailbox

E.2.1
E.2.2
E.2.3
E.2.4
E.2.5
xx

E-1
E-2
E-3
E-4

E-4
E-5
E-5
E-6
E-7
E-7

Contents

E-7

E.2.6

Reassembling and Relinking the Driver

E.3

ADAPTING DEVICE DRIVERS TO RUN ON A VMS MULTIPROCESSING
E-8
SYSTEM
E-8
Specifying the Fork Lock Index
Synchronizing Access to the Device Database with the Interrupt
E-9
Service Routine
Synchronizing at Device IPL• E-9
Raising IPL to IPL$_POWER • E-10
Synchronization Within the Interrupt Service Routine • E-11
E-11
Controller and Unit Initialization Routines

E.3.1
E.3.2
E.3.2.1
E.3.2.2
E.3.2.3

E.3.3
E.3.3.1

E.3.4
E.3.5
E.3.5.1
E.3.5.2

E.3.6
E.3.6.1
E.3.6.2
E.3.6.3
E.3.6.4
E.3.6.5

E.3.7
E.3.7.1
E.3.7.2
E.3.7.3

Permanently Allocating Map Registers and Buffered Data
Paths• E-12

Timeout Handling Routine
General Methods for Synchronizing Kernel-Mode Code
Using the Spin Lock Synchronization Macros • E-13
Interlocking Access to Data Cells and Queues • E-13
Miscellaneous Conversion Tasks
Reading the System Time • E-15
Calling the Driver Fork Process from a TOE • E-15
Invalidating Translation Buffer Entries • E-15
Unsupported Use of the IRP • E-16
Poor Man's Lockdown • E-16
Troubleshooting a Device Driver in a Multiprocessing System Multiprocessing Bugchecks .• E-18
Analyzing a Multiprocessing System Failure • E-19

E-12
E-12

E-15

E-17

E.3.7.2.1
Investigating the Status of Spin Locks • E-20
Using XDELTA on SMP Systems• E-20

GLOSSARY

Glossary-1

INDEX

EXAMPLES
13-1

Loading a Driver

13-6

17-1

SCSI Bus Phase Error Port Driver Error Log Entry

17-40

17-2

SCSI Bus Reset Port Driver Error Log Entry

17-41

17-3

SCSI Bus Reset Class Driver Error Log Entry

17-42

19-1

Locating the Adapter Address Space of a UNIBUS Adapter on
a VAXBI Bus

19-4
xxi

Contents

FIGURES

xx ii

1-1

The 1/0 Database

1-5

1-2

SBl-Based System Configurations

1-12

1-3
1-4

VAXBl-Based System Configurations
SCU/XMl-Based Systems Architecture

1-14
1-17

1-5

Q22 Bus Based Systems

1-18

1-6
1-7

MicroVAX/VAXstation 3100 System Architecture
VAXstation 3520/3540 System Architecture

1-19
1-20

1-8

Example of 1/0 Request Processing

1-23

2-1
3-1

A Printer Write Function
Synchronizing 1/0 Request Processing

2-2
3-18

3-2

Synchronizing 1/0 Request Completion

3-20

3-3
4-1

Processor-Specific Fork Queue Structure

3-25
4-2

4-2

Sequence of Driver Execution
Detailed Sequence of VMS 1/0 Processing

4-3

Data Structures for Three Devices on One Controller

4-6

4-4

1/0 Database for Two Controllers

4-8

4-5

Layout of a Function Decision Table

4-11

4-6

FDT Routines and 1/0 Preprocessing

4-14

4-7

Creating a Fork Process After an Interrupt

4-18

4-8
5-1
7-1

Reactivation of a Driver Fork Process
Driver Organization

4-19

$QIO Scan of a Function Decision Table

7-3

7-2

Format of System Buffer for a Buffered-110 Read Function

7-7

8-1

Inserting a UCB into the Channel Wait Queue

8-3

9-1

Flow of Interrupt Servicing

9-2

13-1

Format of the POOLCHECK System Parameter

13-24

13-2
14-1

Poisoned Pool Packet
UNIBUS and Q22 Bus Map Registers

13-26
14-5

14-2

Mapping a UNIBUS Address to a Physical Address

14-7

14-3

Mapping a Q22 Bus Address to a Physical Address

14-8

14-4

UNIBUS Data Path Registers

14-9

14-5

Direct-Vector Interrupt Dispatching

14-27

14-6

Non-Direct-Vector Interrupt Dispatching

14-28

14-7

VEC Structures Within a CRB

14-31

14-8

Interrupt Transfer Vector Block (VEC)

14-32

15-1

MASSBUS Configuration

15-2

MASSBUS External-Register Longword

15-3

4-4

5-2

Contents

15-3
15-4
15-5
15-6
16-1
16-2
16-3
16-4
16-5
16-6
17-1
17-2
17-3
17-4
17-5
18-1
18-2
18-3
18-4
18-5
18-6
19-1

TABLES
3-1
3-2
3-3
4-1
6-1
7-1
7-2
12-1
12-2
13-1
13-2
13-3
13-4

Location of MASSBUS Registers in Physical Address
Space
1/0 Database for MASSBUS Disk Unit
1/0 Database for MASSBUS Disk and Tape Units
1/0 Data Structures Used in Dispatching a MASSBUS Device
Interrupt
VAXBI Address Space
Description of VAXBI 1/0 Address Space
Physical Addresses in VAXBI 1/0 Address Space
SCU/XMI Systems 1/0 Address Space
VAXBI Device Vectors
Backplane Interconnect Interface Chip (BllC) Registers
VMS SCSI Class/Port Interface
VMS SCSI Port Driver Configuration
VMS SCSI Class Driver Configuration
SCSI Class/Port Data Structures
SCSl_NOAUTO System Parameter
UCB Structure for Terminal Class/Port Drivers
Port Driver Vector Table
Class Driver Vector Table
Port Driver Structure
Class Driver Structure
Terminal Class/Port Driver Binding
Format of a Physical Address

IPLs Defined by VMS
VMS Macros That Change a Processor IPL
Static Spin Locks
IRP Data Fields
1/0 Function Codes
Registers Loaded by the $QIO System Service
FDT Routines Provided by VMS
Conventional Nexus Assignments
SYSGEN Device Table
Boot Flags That Control the Loading of XDELTA
Recommended Methods for Bootstrapping with XDELTA
Requesting an XDELTA Software Interrupt
XDELTA Command Summary

15-6
15-7
15-8
15-9
16-2
16-3
16-4
16-6
16-12
16-23
17-3
17-4
17-5
17-8
17-31
18-3
18-4
18-5
18-7
18-8
18-10
19-5

3-2
3-10
3-13
4-10
6-5
7-2
7-9
12-5
12-16
13-2
13-2
13-8
13-11
xx iii

Contents

13-5

Settings of MULTIPROCESSING System Parameter

13-28

13-6

Bugchecks Produced by Full-Checking Multiprocessing

13-28

14-1

Features of the UNIBUS Adapters/Q22 Bus Interfaces of VAX
Systems

14-3

14-2

VAX System UNIBUS/Q22 Bus Interrupt Dispatching

14-29

15-1

Major Offsets Defined by $MBADEF

15-4

16-1

16-24

17-1

Contents of the BllC Registers
SCSI Port Interface (SPI) Macros

17-2

Data Structures

17-8

17-3
17-4

SCSI Status Byte Format
Error Message Buffer Extension for SCSI Class Drivers

17-18
17-20

17-5

SPI Extension Macros Supporting Asynchronous Event
Notification

17-29

17-6
17-7

Key to Port Driver Error Log Entries
Key to Class Driver Error Log Entries

17-35
17-38

18-1

Port Driver Routines

18-11

18-2

Class Driver Routines

18-19

19-1

Symbols Defined by the $10xxxDEF Macros

19-2

19-2
E-1

UNIBUS and Q22 Bus Adapter Address Space

19-4

VMS Synchronization Images

E-2

Settings of MULTIPROCESSING System Parameter

E-3

Converting IPL Synchronization to Spin Lock
Synchronization

E-13

Bugchecks Produced Within Full-Checking Synchronization

E-18

E-4

xx iv

17-6

Preface
The VMS Device Support Manual provides information needed to write
a device driver that runs under VMS Version 5.4 and to load it into the
operating system. Digital makes no guarantee that drivers written for
earlier versions of VMS will execute without modification on this version
of the operating system. Although the intent is to maintain the existing
interface, some unavoidable changes might occur as new features are
added.
The use of internal executive interfaces other than those described in this
manual is discouraged.

Intended Audience
This manual is intended for system programmers who are already familiar
with VAX processors and the VMS operating system.

Document Structure
This manual contains five parts.
Part I describes the components and environment of a device driver and
provides explanations of VMS concepts critical to an understanding of a
device driver's functions and role in the operating system. Part I contains
four chapters.
•

Chapter 1 describes the role of a device driver in the VMS operating
system, introduces the components of a typical driver and the data
structures it uses, and provides an overview of system concepts critical
to driver operation. It concludes with an examination of the I/O
subsystems of VAX processing systems.

•

Chapter 2 provides an example of a device driver-the VMS line
printer driver. It illustrates the functions of the various components of
this driver and describes the driver's interaction with VMS.

•

Chapter 3 discusses VMS synchronization mechanisms: interrupt
priority levels; spin locks, fork locks, and device locks; fork processes
and fork queues; and resource-wait queues.

•

Chapter 4 provides an overview of I/O processing and discusses the
interaction of device drivers with VMS.

Part II of this document describes how to code each part of a driver. It
includes seven chapters.
•

Chapter 5 explains some general driver coding rules and conventions
and describes a device driver.

•

Chapter 6 describes how to create driver tables, including the driver
prologue table, driver dispatch table, and function decision table
(FDT).

xxv

Preface

•

Chapter 7 explains how to write FDT routines, how to use VMSsupplied FDT routines, and how to transfer control out of I/O request
preprocessing.

•

Chapter 8 discusses the components of a driver's start-I/O routine.

•

Chapter 9 discusses the functions performed by an interrupt service
routine (ISR).

•

Chapter 10 describes how to perform device-dependent I/O completion
and to write timeout handling routines.

•

Chapter 11 describes unit and controller initialization routines, cancelI/O routines, error logging routines, register dumping routines, and
cloned unit control block (UCB) routines.

Part III of this document describes how to load and debug a device driver.
This part contains two chapters.
•

Chapter 12 examines the methods by which a device is logically
connected to the processor and by which a driver is loaded into the
operating system.

•

Chapter 13 describes the use of XDELTA as a device driver debugging
tool.

Part IV contains discussions of bus-specific and processor-specific details
that affect the composition and operation of a device driver. The chapters
in this part also discuss advanced topics relating to the writing of specific
types of drivers.
•

Chapter 14 discusses I/O bus features that govern the operation of
direct-memory-access (DMA) transfers and that affect the code of DMA
device drivers for UNIBUS and Q22 bus devices.

•

Chapter 15 describes strategies for producing a MASSBUS device
driver.

•

Chapter 16 describes special coding considerations for generic VAXBI
devices.

•

Chapter 17 provides information on creating a third-party SCSI
class driver to support a non-Digital-supplied small computer system
interface (SCSI) device.

•

Chapter 18 discusses the components of terminal class and port
drivers.

•

Chapter 19 describes the connect-to-interrupt driver interface that is
available to real-time users.

Part V contains driver program templates and code examples of drivers for
devices connected to a SCSI bus, a UNIBUS, and a Q22 bus.

xx vi

•

Appendix A includes a template for a UNIBUS or Q22 bus device
driver.

•

Appendix B includes a template for a SCSI class driver.

•

Appendix C includes a sample driver that operates an RL01/RL02-type
disk on the UNIBUS or Q22 bus.

Preface

•

Appendix D contains a sample driver for two connected DRll
controllers on the UNIBUS or Q22 bus.

•

Appendix E describes the differences between drivers intended for
a VMS uniprocessing environment and those intended for a VMS
multiprocessing environment. It further describes those changes
required for the upgrade of non-Digital-supplied drivers written
before VMS Version 5.0 and also discusses the means by which a
uniprocessing driver can be converted to a multiprocessing driver.

The Glossary defines vocabulary that pertains to device drivers and their
environment.

Associated Documents
Before reading the VMS Device Support Manual, you should have an
understanding of the material discussed in the following documents:
•

The VMS Device Support Reference Manual, a companion document,
which describes the required reference material for driver
programming

•

VAX Hardware Handbook

•

1/0-related portions of the VMS System Services Reference Manual

•

The section on VMS naming conventions in the Guide to Creating VMS
Modular Procedures

•

VMS I I 0 User's Reference Manual: Part I and VMS I I 0 User's
Reference Manual: Part II

You may also find useful some of the material in your processor's hardware
documentation, as well as that in the following books:

•

VMS System Dump Analyzer Utility Manual

•

Guide to Maintaining a VMS System

•

VAX/VMS Internals and Data Structures

•

VMS Delta/XDelta Utility Manual

Before reading the SCSI information in Chapters 1 and 17, you should
have an understanding of the material discussed in the following
documents:
•

American National Standard for Information Systems-Small
Computer System lnterface-2 (SCSl-2) specification (X3T9.2/86-109)
The SCSI-2 specification is a draft of a proposed standard. Until it
is approved, copies of this document may be purchased from Global
Engineering Documents, 1990 M Street NW, Suite 400, Washington,
D. C., 20036, United States; or by calling telephone number
(800) 854-7179. Please refer to document X3.131-199X.

•

American National Standard for Information Systems-Small
Computer System Interface specification (X3.131-1986)

xxvii

Preface

Copies of this document may be obtained from the American National
Standards Institute, Inc., 1430 Broadway, New York, New York, 10018.
This document is now known as the SCSI-1 standard.
Digital publishes two additional documents to help third-party vendors
prepare SCSI peripherals and peripheral software for use with Digital's
workstations and MicroVAX systems:
•

The Small Computer System Interface: An Overview
(EK-SCSIS-OV-001) provides a general description of Digital's SCSI
third-party support program.

•

The Small Computer System Interface: A Developer's Guide
(EK-SCSIS-SP-001) presents the details of Digital's implementation
of SCSI within its operating systems.

Conventions
This manual describes code transfer operations in three ways:
1

The phrase "issues a system service call" implies the use of a CALL
instruction.

The phrase "calls a routine" implies the use of a JSB or BSB
instruction.

The phrase "transfers control to" implies the use of a BRB, BRW, or
JMP instruction.

Typographical conventions used in this book include the following:
•

Generally, terms that are further explained in the glossary of this
manual first appear in bold print. For example:
Under the VMS operating system, a device driver is a set of routines
and tables that the system uses to process an I/O request for a
particular device type.

•

Terms that serve as arguments to macros appear in boldface in the
text of the manual. For example:
If an at sign ( @) character precedes the oper argument, then the exp
argument describes the address of the data with which to initialize the
field.

•

In examples, a key name is shown enclosed to indicate that you press
a named key on the terminal. For instance:
driver-base-address,O;X

•

A sequence such as Ctrl/x indicates that you must hold down the key
labeled Ctrl while you simultaneously press another key. For instance:
$ CREATE MYDRIVER.OPT
BASE=O
ICtrl/ZI

xxviii

Preface

•

A horizontal ellipsis indicates that additional parameters, values, or
information can be entered. For example:
$

•

LINK /NOTRACE MYDRIVER1[,MYDRIVER2, ... ],MYDRIVER.OPT/OPTIONS,SYS$SYSTEM:SYS.STB/SELECTIVE_SEARCH

Brackets indicate that the enclosed item is optional. For example:
DSBINT [ipl] [,dst]

However, brackets are not optional in the syntax of a directory name
in a file specification or in the syntax of a substring specification in an
assignment statement.
•

In interactive examples in printed editions of this book, all output lines
or prompting characters that the system prints or displays appear in
black type. User-entered commands are shown in red type. In online
editions of this book, user-entered commands are shown in boldface
type.
For example:
>>> DEPOSIT R3 0
>>> @DMAXDT
SYSBOOT>
SYSBOOT> CONTINUE

•

A vertical ellipsis means either that not all data that the system would
display in response to the particular command is shown or that not all
data a user would enter is shown. For example:
JSB

@UCB$L_FPC (RS)

; Restore the driver process.

;Between these instructions, the interrupt service routine
;can make no assumptions about the contents of RO through R4.

POPR

•

#AM<RO,Rl,R2,R3,R4,R5> ; Restore interrupt registers.

In text, an arrow ( --+)between abbreviated names .or objects functions
as a pointer to illustrate a pointing chain between structures in the
database. In the following example, the UCB points to the DDT data
structure, which points to the FDT address.
UCB--+ DDT--+ FDT address

xx ix

Introduction to Device Drivers

Under the VMS operating system, a device driver is a set of routines
and tables that the system uses to process an 1/0 request for a particular
device type.
The VMS operating system's approach to 1/0 is that the system should
perform as much of the processing of an 1/0 request as possible and that
drivers should restrict themselves to the device-specific aspects of 1/0
processing. To accomplish this, the VMS operating system provides drivers
with the following services:
•

A Queue 1/0 request ($QIO) system service that preprocesses an 1/0
request by performing those functions and checks that are common to
all devices; for example, validating those arguments of the 1/0 request
that are not device specific

•

Many operating system routines that drivers can call to perform 1/0
preprocessing, allocate and deallocate resources, and synchronize
driver execution

•

Macros that drivers can invoke to accomplish tasks that would
otherwise require many lines of code

•

A VMS 1/0 postprocessing routine that performs device-independent
1/0 postprocessing for all 1/0 requests

Thus, drivers can leave the device-independent 1/0 processing to the
operating system and can concentrate on servicing those aspects of an 1/0
operation that vary from device type to device type. In addition, drivers
can call VMS system routines to perform many functions that are common
to several, but not all, devices.
A device driver does not run sequentially from beginning to end. Rather,
the operating system uses driver tables and other information maintained
by itself and the driver to determine which driver routines to activate and
when they should be activated. Because little sequential processing
of driver code occurs, the VMS operating system must assume the
responsibility for synchronizing the execution of the various driver
routines, as well as the execution of all drivers in the system. A major
purpose of this book is to describe the conventions that all VMS drivers
must follow to maintain this synchronization and cooperate with the
operating system in 1/0 request processing.
This section first defines the general functions and purposes of a VMS
device driver. It then introduces VMS concepts crucial to an understanding
of how device drivers work within the operating system and integral to the
process of successfully writing one. It concludes with a brief description of
the flow of driver activity in servicing an 1/0 request, using the VMS line
printer driver as an example.

1-1

Introduction to Device Drivers
1.1 Driver Functions

1.1

Driver Functions
A system utility loads a VMS device driver into system virtual address
space and creates its associated data structures. Once loaded, a device
driver controls I/O operations on a peripheral device by performing the
following functions:

1.2

•

Defining the peripheral device for the rest of the operating system

•

Preparing a device unit and its controller (or both) for operation at
system start-up and during recovery from a power failure

•

Performing device-dependent I/O preprocessing

•

Translating programmed requests for I/O operations into devicespecific commands

•

Activating a device unit

•

Responding to hardware interrupts generated by a device unit

•

Responding to device timeout conditions

•

Responding to requests to cancel I/O on a device unit

•

Reporting device errors to an error logging program

•

Returning status from a device unit to the process that requested the
I/O operation

Driver Components
Normally, a device driver module can consist of the routines and tables
discussed in this section. With a few exceptions, which are noted
throughout Chapter 6, the order of the various routines and tables within
the driver module is not important.

1.2.1

Driver Tables
The following tables appear in every driver.
The driver prologue table (DPT) defines the identity and size of the
driver to the system utility that loads the driver into virtual memory and
creates the associated data structures. With the information provided in
the DPT, the driver-loading procedure can both load and reload drivers
and perform the I/O database initialization that is appropriate to either
situation.
Section 6.1 describes the procedure for creating a DPT and further
discusses its functions. The DPT contents are shown and described in
the VMS Device Support Reference Manual.
The driver dispatch table (DDT) lists the addresses of the entry
points of standard routines within the driver, and records the size of
the diagnostic and error message buffers for drivers that perform error
logging. You can find additional information and instructions on how to
specify a DDT in Section 6.2. The structure and contents of the DDT are
shown and described in the VMS Device Support Reference Manual.

1-2

Introduction to Device Drivers
1.2 Driver Components

The function decision table (FDT) lists all valid function codes for the
device, and associates valid codes with the addresses of I/O preprocessing
routines, called FDT routines. The driver contains device-dependent FDT
routines, and the VMS operating system itself provides routines (described
in Section 7.5) that perform request preprocessing common to many I/O
functions.
When a user process calls the $QIO system service, the system service
uses the I/O function code specified in the request to traverse the FDT
and select one or more of these preprocessing routines for execution, as
appropriate to the function. To prepare for the actual I/O operation, FDT
routines perform such tasks as allocating buffers in system space, locking
pages in memory, and validating the device-dependent arguments (pl to
p6) of the $QIO request. Section 6.3 provides further discussion of the
FDT, and Chapter 7 details strategies and rules for writing, specifying,
and exiting from an FDT routine.

1.2.2

Driver Routines
In addition to any FDT routines it may contain, a device driver generally
contains both a start-I/0 routine and an interrupt service routine.
The start-1/0 routine performs such additional device-dependent tasks as
translating the I/O function code into a device-specific command, storing
the details of the user request in the device's unit control block (UCB)
in the I/O database and, if necessary, obtaining access to controller and
adapter resources. Whenever the start-I/O routine must wait for these
resources to become available, the VMS operating system suspends the
routine, reactivating it when the resources become free.
The start-I/O routine ultimately activates the device by suitably loading
the device's registers. At this stage, the start-I/0 routine invokes a VMS
macro that causes its execution to be suspended until the device completes
the I/O operation and posts an interrupt to the processor. The start-I/O
routine remains suspended until the driver's interrupt service routine
handles the interrupt.
When a device posts an interrupt, its driver's interrupt service routine
determines whether the interrupt is expected or unexpected, and takes
appropriate action. If the interrupt is expected, the interrupt service
routine reactivates the driver's start-I/0 routine at the point of suspension.
The general course of action of driver mainline code at this time is to
perform device-dependent I/O postprocessing and to transfer control to the
VMS operating system for device-independent I/O postprocessing.
Details on writing a start-I/O routine appear in Chapter 8. A description
of a driver interrupt service routine appears in Chapter 9.
You can also include any of the following routines in a device driver.
The unit initialization routine and controller initialization routine
prepare a device or controller for operation when the VMS driver-loading
procedure loads the driver into memory and when the VMS system
recovers from a power failure. The amount and type of initialization
needed by devices and controllers vary according to the device type and

1-3

Introduction to Device Drivers
1.2 Driver Components

the 1/0 bus to which the device or controller is attached. Section 11.1
provides additional information about device driver initialization routines.
A timeout handling routine retries 1/0 operations and performs other
error handling when a device fails to complete a request in a reasonable
period of time. Once every second, the VMS system timer checks all
devices in the system for device timeout. When it locates a device that
has timed out, because it is off line or some error has occurred, the system
timer calls the driver's timeout handling routine.
Depending upon the reason for the timeout, the timeout handling routine
may call a VMS error logging routine to allocate and fill an error message
buffer with information about the error. In turn, the error logging routine
can call a register dumping routine in the driver that also loads into
the buffer the contents of device registers at the time of the error.
Timeout handling routines are discussed in Section 10.2. Register
dumping routines and driver error handling are discussed in Section 11.3.
The VMS operating system calls a driver's cancel-1/0 routine when a
user process issues a Cancel I/O on Channel ($CANCEL) system service
for the device. It may also call the routine when the device's reference
count goes to zero, which occurs when all users with assigned channels to
the device have deassigned them. The discussion of the cancel-I/O routine
appears in Section 11.2.

1.3

The 1/0 Database
Because a driver and the operating system cooperate to process an I/O
request, they must have a common and current source of information
about the request. This is the function of the 1/0 database. Under the
VMS operating system, the I/O database consists of the following three
parts:
•

Driver tables that allow the system to load drivers, to validate device
functions, and to call driver routines at their entry points

•

Data structures that describe I/O bus adapters, device types, device
units, device controllers, and logical paths from processes to devices

•

I/O request packets that define individual requests for I/O activity

Illustrations of I/O database structures and detailed descriptions of their
fields appear in the data structure chapter of the VMS Device Support
Reference Manual. Figure 1-1 illustrates some of the relationships among
VMS 1/0 routines, the I/O database, and a device driver.

1.3.1

Driver Tables
The three driver tables-driver prologue table, driver dispatch table, and
function decision table-are defined in every driver. Section 1.2 lists these
tables among the other components of a device driver, and Chapter 6
discusses their contents.

1-4

Introduction to Device Drivers
1.3 The 1/0 Database

Figure 1-1

The 1/0 Database

I
I
I
I

Process
Control
Block
Describes
Requesting
Process
~

1/0
Request
Packet
Describes
1/0
Request

1--'

.......,

UCB
Describes
Device

.....

Driver
FDTRoutine

t----'

1 ru

CCB
Describes
Logical Path
to Device

DDT
Locates Driver

....

DOB for
Device
Type

I
I
I
I

Driver
Start 1/0 Routine

....
-...

CRB
Synchronizes
Controller

.....
-...

I
IDB
Describes
Controller

ADP
Describes
Adapter

I
I
I
I

......_

Driver
Interrupt Service
Routine
Driver
Controller Initialization
Routine
I
I

I
I

Device
Registers

ZK-1766-GE

1.3.2

Data Structures
1/0 database data structures describe peripheral hardware and are used
by the operating system to synchronize access to devices. VMS creates
these data structures either at system startup or when a driver is loaded
into the system.
The system defines a unit control block (UCB) for each device unit
attached to the system. A UCB defines the characteristics and current
state of an individual device unit.
UCBs are the focal point of the 1/0 database. When a driver is suspended
or interrupted, the UCB keeps the context of the driver in a set of fields
collectively known as a fork block. 1 In addition, the UCB contains the
listhead for the queue of pending 1/0 request packets (IRPs) for the unit.

Other structures, such as the CRB, also include a fork block. The discussion of fork blocks and fork processes
in Section 1.5 explains the role of fork blocks in driver processing.

1-5

Introduction to Device Drivers
1.3 The 1/0 Database

A device data block (DDB) contains information common to all devices
of the same type that are connected to a particular controller. It records
the generic device name concatenated with the controller designator (for
example, LPA, DBB), and the name and location of the associated device
driver. In addition, the DDB contains a pointer to the first UCB for the
device units attached to the controller.
The operating system creates a channel request block (CRB) for each
controller. A CRB defines the current state of the controller and lists the
devices waiting for the controller's data channel. It also contains the code
that dispatches a device interrupt to the interrupt service routine (ISR) for
that unit's driver.
The system also creates for each controller an interrupt dispatch block
(IDB). An IDB lists the device units associated with a controller and points
to the UCB of the device unit that the controller is currently servicing. In
addition, an IDB points to device registers and the controller's I/O adapter.
An adapter control block (ADP) defines the characteristics and current
state of an I/O adapter, such as the VAX UNIBUS and MASSBUS
adapters, the Q22 bus interface of MicroVAX systems, or a device attached
to the VAXBI bus. An ADP contains the queues and allocation bitmaps
necessary to allocate the adapter's resources. VMS provides routines that
drivers can call to interface with the appropriate adapter.

The channel control block (CCB) describes the logical path between
a process and the UCB of a specific device unit. 2 Each process owns
a number of CCBs. When a process issues the Assign I/O Channel
($ASSIGN) system service, the system writes a description of the assigned
device to the CCB.
Unlike the data structures mentioned earlier, a CCB is not located in
nonpaged system space, but in the process's control region (Pl space).

1.3.3

1/0 Request Packets
The third part of the I/O database is a set of I/O request packets. When
a process requests I/O activity, the operating system constructs an 1/0
request packet (!RP), that describes the I/O request in a standard form.
The IRP contains fields into which the system and driver I/O preprocessing
routines can write information: for instance, the device-dependent
arguments specified in the call to the $QIO system service. The packet
also includes buffer addresses, a pointer to the target device's UCB, an
I/O function code, and pointers to the I/O database. After preprocessing,
the IRP can be queued to a list originating in the device's UCB to await
processing by the driver.

channel request blocks (CRBs) and channel control blocks (CCBs) are two separate data structures. To help
distinguish the two, it may be helpful to think of the channel request block as the "controller request" block
because it describes the hardware controller. In contrast, the channel control block is used by a process
and a device unit to manage the logical channel (the channel argument to the $ASSIGN and $QIO system
services) in accomplishing I/O operations.

1-6

Introduction to Device Drivers
1.3 The 1/0 Database

When the device unit is free and the IRP is next in line to be processed on
the unit, the system sends it to the device driver's start-1/0 routine. The
start-110 routine uses the IRP as its source of detailed instructions about
the operation to be performed.

1.4

Synchronization of Driver Activity
Device drivers and other kernel-mode code must maintain
synchronization with other priority operating system activities. The
term synchronization refers to the means by which such code accesses
shared data in a consistent, orderly, and predictable fashion. Because
there may be more than one processor active in a VMS system, systemlevel code must synchronize its actions with other code threads it may
have preempted on the same (or local) processor, as well as with those
that are active (or to be activated) on other processors in the system. The
VMS operating system uses hardware and software interrupt priority
levels (IPLs) to order system events on each local processor in a VAX
system. The VAX hardware defines 32 interrupt priority levels (IPLs). The
higher numbered IPLs (16 to 31) are reserved for hardware interrupts,
such as those posted by devices. The VMS operating system uses the
lower numbered IPLs (0 to 15). Code that executes at a higher IPL takes
precedence over code that executes at a lower IPL.
A driver, in concert with the operating system, ensures that it maintains
system synchronization by performing certain activities and by accessing
certain data only at the appropriate IPL. In a VMS multiprocessing
system, the driver extends the synchronization it achieves by executing
locally at a given IPL by acquiring ownership of the spin lock associated
with the operation it is performing. (IPL, spin locks, and other forms of
synchronization in a VMS system are discussed fully in Chapter 3.)

1.5

Driver Context
As indicated in Section 1.2.2, a driver may have several routines to which
the VMS operating system may pass control in certain situations. The
context in which any one routine receives control from VMS may differ
substantially from that in which another receives control. It is essential
that a driver routine not attempt to exceed the limitations of the context
in which it executes.
In general, context is characterized by the following factors:
•

The current IPL of the executing processor

•

The IPL at which the thread of execution that resulted in the call to
the driver began

•

The currently owned spin locks of the executing processor

•

The data structures available to the routine

•

Data available to the routine in registers,· in data structure fields, and
on the stack

1-7

Introduction to Device Drivers
1.5 Driver Context

•

The condition of the registers, data structure fields, and stack when
the routine exits

•

The ability or inability to access process space

A complete description of the context of each driver routine appears in the
entry points chapter of the VMS Device Support Reference Manual. The
following are some general observations:
•

All device driver routines execute in kernel mode at an elevated IPL.

•

Only driver FDT routines execute within process context and can
access process space (PO and Pl).

•

The majority of driver routines execute in interrupt (or system context):
that is, in the sequence of execution that follows a processor's grant of
an interrupt request at a given IPL. Such code can refer only to system
(SO) space. Moreover, it cannot incur exceptions, including page faults,
without causing a fatal bugcheck. Code executing in interrupt context
is serviced on the interrupt stack, and must synchronize its execution
with other priority code threads by using IPLs, spin locks, and resource
wait queues, all of which are described in Chapter 3.

Most driver processing of an I/O request (before and after the device
acknowledges the servicing of the request by requesting an interrupt from
the processor) occurs at a fork IPL. This portion of driver code, which
includes most of the start-I/O routine, is commonly known as the driver's
fork process.
There are several instances in the processing of an I/O request when
a driver fork process must suspend execution to wait for a resource or
a device interrupt. To make the matter of saving and restoring fork
process context as efficient as possible, the VMS operating system places a
restriction on the context of a driver fork process, in addition to those that
apply to any process in interrupt context. Fork context consists of the
following:
•

Two general purpose registers (R3 and R4)

•

The program counter (PC)

•

A fork block (usually the unit control block, the address of which is
presumed to be in R5 at the time of the suspension) that can contain
additional fork process context

VMS places the fork block of a suspended fork process in either a
processor-specific fork queue or a resource wait queue where it waits
to be resumed. When it resumes the fork process, VMS ensures that the
fork context is restored. Fork blocks, fork processes, and fork queues are
discussed fully in Section 3.3.3.

1-8

Introduction to Device Drivers
1.5 Driver Context

1.5.1

Example of Driver Context-Switching
Because a device driver consists of a number of routines that are activated
by VMS, the operating system for the most part determines the context in
which the routines execute.
As an example, consider the following write request that occurs without
error:
1

A user process executing in user mode calls the $QIO system service
to write data to a device.

The $QIO system service gains control in process context but in kernel
mode. It performs device-independent preprocessing of the I/O request.

The system service uses the driver's function decision table (FDT)
to call the appropriate FDT routines to perform device-dependent
preprocessing. These FDT routines execute in full process context in
kernel mode.

When preprocessing is complete, a VMS routine creates a fork process
to execute the driver's start-I/O routine in kernel mode.

The start-I/O routine activates the device unit and suspends itself.
At this point, VMS suspends the fork process executing the start-I/O
routine and saves sufficient context to reactivate the start-I/O routine
at the point of suspension.

When the device completes the data transfer, it requests an interrupt.
The interrupt causes the system to activate the driver's interrupt
service routine.

The interrupt service routine executes to handle the device interrupt.
It then causes the start-1/0 routine to resume in interrupt context.

The start-I/0 routine regains control in interrupt context but almost
immediately issues a request to the operating system to transform its
context to that of a fork process. This action dismisses the interrupt.

When reactivated in fork process context, the start-I/O routine
performs device-specific 1/0 completion and passes control to the
system for additional I/O postprocessing.

10 VMS I/O postprocessing runs in interrupt context at a lower IPL and

issues a special kernel-mode asynchronous system trap (AST) for the
user process requesting 1/0.
11 When the special kernel-mode AST is delivered, the AST routine
executes in full process context in kernel mode to deliver data and
status to the process. If the original request specified a user-mode
AST, the special kernel-mode AST queues it.
12 When the user process gains control, the user's AST routine executes

in full process context in user mode.

1-9

Introduction to Device Drivers
1.6 Hardware Considerations

1.6

Hardware Considerations
The VMS operating system runs on any of the following VAX systems. It
can also support non-Digital-supplied devices.

•
•

VAX.-111780 and VAX.-11/785
VAX.-111730 and VAX.-111750

• VAX 8600/8650
• VAX 82x0/83x0

•
•
•

VAX 85x0 and VAX 8700/88x0
VAX 6000 series
VAX 9000 series

• MicroVAX. 3400/3600/3900 series

•
•

MicroVAX/VAX.station II and VAX 4000 series
MicroVAX/VAX.station 3100

• VAX.station 3520/3540
Although these system configurations em ploy the same operating system
and conform to the VAX. architecture, there are some differences in
design among the machines that merit consideration in device driver
coding, installation, and debugging. For instance, VAX systems differ
in the amount of available physical address space and in the location
of device registers. Some VAX systems are available in multiprocessor
configurations. Also, VAX systems support different and various
combinations of 1/0 buses to which a nonstandard device can be connected.
If you follow the conventions described in this manual when writing your
driver, your driver should, with little modification, drive the same device
attached to a corresponding 1/0 bus of another VAX system. For specific
system design and device configuration information, refer to your system's
technical reference or hardware manual or the VAX Hardware Handbook.

1.6.1

Driver Dependency on VAX Processing Systems
This section outlines some of the general differences among the VAX
processing systems that have a bearing upon the development of driver
code. The main thrust of the discussion is to provide a brief summary of
the layout of the I/O subsystems of the VAX processing systems, to define
a general terminology, and, when necessary, to direct device driver writers
to documentation particular to the I/O configuration of their device.

1-10

Introduction to Device Drivers
1.6 Hardware Considerations

1.6.1.1

VAX-11 /780, VAX-11 /785, and VAX 8600/8650 Systems

The VAX-11/780, VAX-11/785, VAX 8600 and VAX 8650 systems, from
the viewpoint of I/O architecture, are SBI-based systems. That is, the
synchronous backplane interconnect (SB!) is the bus by which I/O
adapters communicate with main memory and the central processor (see
Figure 1-2). I/O adapters supported by the SBI include the UNIBUS
adapter (UBA), the MASSBUS adapter (MBA), and the DR780 interface
adapter. Correspondingly, peripheral devices attach to either the UNIBUS,
MASSBUS, or DR32 device interconnect (DD!) of the DR780 adapter.
Main memory shares the SBI with the I/O adapters on the VAX-11/780
and VAX-11/785. The VAX 8600 and VAX 8650 employ a separate bus to
which main memory is attached and can each be configured with up to two
SBis for I/O adapters.
For these systems, nonstandard devices are commonly attached to the
UNIBUS, although some nonstandard devices connect to the MASSBUS
and DDI. The components of UNIBUS and MASSBUS drivers are nearly
identical and the strategies for producing driver code are similar;
writers of either type of driver will profit from reading the bulk of
this manual. Writers of UNIBUS drivers can find specific information
about the UNIBUS adapter and VMS support for UNIBUS drivers in
Chapter 14. MASSBUS driver writers should refer to Chapter 15 for
similar information about the MASSBUS. Digital supplies a device driver
and an application library for DDI devices; the VMS I I 0 User's Reference
Manual: Part II discusses the DR32 interface driver in detail.
A final note on terminology regarding these systems is pertinent. For the
purposes of the discussion in this book, the term VAX-11I780 refers to the
family of VAX systems that includes the VAX-11/780 and VAX-11/785; the
term VAX 8600 refers to the VAX 8600 and VAX 8650.
1.6.1.2

The VAX-111750 System

The VAX-11/750 system resembles the VAX-11/780-type systems in
that it supports UNIBUS, MASSBUS, and DDI peripheral devices (see
Figure 1-2). The backplane, or CPU-to-memory interconnect (CMI), by
which I/O adapters communicate with the central processor and main
memory, is integral to the processor, as are the UNIBUS interface (UBI)
and MASSBUS adapter (MBA). The DR750 interface adapter connects the
CMI to the DDI subsystem. Peripheral devices connect to the UNIBUS,
MASSBUS, and DDI. A separate memory interconnect provides an
interface between main memory and the rest of the system.

1-11

Introduction to Device Drivers
1.6 Hardware Considerations

Figure 1-2

SBl-Based System Configurations

VAX-11/780
VAX-11/785

CPU

USA

MBA

VAX 8600
VAX 8650

Memory

SBI

Adapter
CPU

MBA

USA

Memory
Controller
A
r
r

a
y

B
u

.___A_d~-~-~e_r___.~ ~@ ~
ZK-4838-GE

1-12

Introduction to Device Drivers
1.6 Hardware Considerations

For the VAX-11/750, nonstandard devices are commonly connected to the
UNIBUS, although some nonstandard devices attach to the MASSBUS.
The components of UNIBUS and MASSBUS drivers are identical, and
the strategies for developing driver code are similar. Writers of either
type of driver will profit from reading this manual. Writers of UNIBUS
drivers can find specific information about the UNIBUS adapter and VMS
support for UNIBUS drivers in Chapter 14. MASSBUS driver writers
should refer to Chapter 15 for similar information about the MASSBUS.
Digital supplies a device driver and an application library for DDI devices
device; the VMS I I 0 User's Reference Manual: Part II discusses the DR32
interface driver in detail.
1.6.1.3

The VAX-11 /730 System

The VAX-11/730 system, like the VAX-11/750 system, incorporates an
integral UNIBUS adapter to control transactions between UNIBUS
peripheral devices, the processor, and the main memory interface. The
VAX-11/730 does not, however, support MASSBUS devices. Writers of
UNIBUS drivers can find specific information about the UNIBUS adapter
and VMS support for UNIBUS drivers in Chapter 14.
1.6.1.4

VAX 82x0/83x0, VAX 85x0/8700/88x0, and VAX 6000-Series Systems
The VAX 82x0/83x0, VAX 85x0/8700/88x0, and VAX 6000 series are

VAXBI-based systems; that is, the VAXBI is the bus by which I/O
adapters communicate with main memory and the central processor
(see Figure 1-3 ).
In a VAX 82x0/83x0 configuration, main memory, the DWBUA, and
other devices are all connected directly to the VAXBI bus. By contrast,
the VAX 85x0/8700/88x0 and VAX 6000-series configurations employ
separate memory interconnects (known as the NMI, PBI, or XMI), as
illustrated in Figure 1-3, to service main memory. The VAX 85x0/8700
/88x0 provides multiple VAXBI buses to which I/O adapters and devices
can be attached. The VAX 83x0, VAX 8800/8820/8830, and VAX 6000 series
are multiprocessor systems.
The VAXBI bus supports UNIBUS peripherals by means of the VAXBI-toUNIBUS adapter (DWBUA or DWMUA). Writers of UNIBUS drivers can
find specific information about the UNIBUS adapter and VMS support for
UNIBUS drivers in Chapter 14.
The VAXBI also supports non-Digital-supplied devices designed according
to specifications established by Digital and a license granted by Digital.
Writers of drivers for such devices, referred to as generic VAXBI devices
in this manual, can find specific information in Chapter 16.
For the purposes of the discussion in this book, the term UNIBUS
adapter includes the DWBUA and DWMUA, and the term backplane
interconnect represents the VAXBI bus.

1-13

Introduction to Device Drivers
1.6 Hardware Considerations

Figure 1-3 VAXBl-Based System Configurations
VAX 8200

Memory

CPU

UNIBUS

VAX 6000

XMI
Memory
Controller

Memory
Controller

ZK-4839.1-GE

(continued on next page)

1-14

Introduction to Device Drivers
1.6 Hardware Considerations

Figure 1-3 (Cont.)

VAXBl-Based System Configurations

VAX 8800

NBIA

CPU

Memory

Controller

VAX8830

Memory

Controller

c:J

PBIA

NMI

CPU

NBW

CPU

NBW
PBIA

PBIA

ZK-4839.2-GE

1-15

Introduction to Device Drivers
1.6 Hardware Considerations

1.6.1.5

The VAX 9000 Series System
The VAX 9000 Series system employs the SCU/XMI bus architecture
illustrated in Figure 1-4. It features a two-level I/O subsystem supporting
up to four XMI buses.

A system control unit (SCU) and an I/O control unit translate each
address and connect a VAX 9000 CPU or memory bus to a target XMI and
device or bus adapter. The primary I/O bus is the XML It is reserved to
devices and adapters supplied by Digital.
The SCU and I/O control unit connect to each XMI through an XJA
adapter. Each XMI-to-VAXBI adapter (DWMBA/A) provides connection
to the second level I/O subsystem. At the second level, device support is
provided for non-Digital-supplied devices connected to the VAXBI bus.
Writers of drivers for such devices, referred to as generic VAXBI devices
in this manual, can find specific information in Chapter 16.
1.6.1.6

The MicroVAX 3400/3600/3900 Series, MicroVAX/VAXstation II, and VAX 4000
Series Systems
The MicroVAX 3400/3600/3900 series, the MicroVAX/VAXstation II, and
the VAX 4000 series are Q22 bus-based systems. On these systems, the
Q22 bus is the bus by which peripheral devices communicate with main
memory and the processor. 3 Q22 bus device drivers are similar enough to
those that drive UNIBUS devices that most of the discussion of UNIBUS
drivers in this book can equally pertain to the writing of Q22 bus device
drivers (see Chapter 14 for a discussion of the similarities and differences).

As you can see in Figure 1-5, in these systems main memory and I/O
devices reside on separate interconnects. MicroVAX systems implement a
scatter-gather map containing 8192 map registers that allows devices to
perform multiple-block, direct-memory-access (DMA) transfers. 4
For the purposes of discussion in this manual, the term backplane
interconnect represents the Q22 bus in the MicroVAX systems. The
term Q22 bus interface represents those functions performed by these
processors that resemble those performed by the UNIBUS adapter of other
VAX systems. In most instances, you can assume that discussions of the
UNIBUS adapter apply as well to the Q22 bus.

3
4

DMA controllers attached to the Q22 bus must be capable of 22-bit addressing.
In these systems, the 4Mb of Q22 bus memory is located from physical address 3000000016 to 303F000016 •
If you must install controllers that contain local memory on the Q22 bus, it is best to install them in the
last 3. 75Mb of Q22 bus memory (after physical address 3004000016 ). The first 0.25Mb (256Kb) of Q22 bus
memory contains 496 map registers, 127 of which must be free for use by VMS in booting. If you must
place a controller containing memory in this address region, it cannot occupy more than 369 pages. If the
controller exceeds this space, VMS will probably boot but will not be able to take crash dumps.

1-16

Introduction to Device Drivers
1.6 Hardware Considerations

Figure 1-4 SCU/XMl-Based Systems Architecture
VAX 9000
CPU

CPU

Memory

System Control Unit

110 Control Unit

L~~~J
.-,/' ,,...

'\.

lXJAl
--~-~

~// ',~

, ...

Console

L~~J

..~ ' ~'\.
/

Disk
SI
KDM70

M
I

Tapes

NI
DEM NA

Ethernet

Cl
CIXCD

ZK-1599A-GE

1-17

Introduction to Device Drivers
1.6 Hardware Considerations

Figure 1-5 Q22 Bus Based Systems

CPU

r----------------------------------1I

Memory

I
I
I
I
I

OBI

Memory
Controller

Array Bus

ZK-4840-GE

1.6.1.7

The MicroVAX/VAXstation 3100 and VAXstation 3520/3540 Systems

The VMS operating system offers a native mode implementation
of the ANSI Small Computer System Interface (SCSI) bus on its
MicroVAX/VAXstation 3100 and VAXstation 3520/3540 system
configurations.
MicroVAX/VAXstation 3100 systems are uniprocessing systems, providing
access to one or two SCSI buses, each under the control of an NCR
5380 SCSI controller chip that supports asynchronous data transfers.
MicroVAX/VAXstation 3100 systems support the SCSI asynchronous event
notification feature. Figure 1-6 shows a representative configuration of a
MicroVAX/VAXstation 3100 system.

1-18

Introduction to Device Drivers
1.6 Hardware Considerations

Figure 1-6

MicroVAX/VAXstation 3100 System Architecture

Main Memory
(Up to 32Mb)

128Kb

OMA
Buffer
SCSI Port PKBO
(Optional)

SCSI Port PKAO

SCSI
Disk
(Target)

SCSI

Tape

Other
SCSI

(Target)

SCSI

Tape
(Target)

Logical
Unit
(Target)

SCSI
Disk
(Target)

Logical
Unit
(Target)
ZK-1367A-GE

The VAXstation 3520/3540 systems are multiprocessing systems, providing
access to a single SCSI bus by means of Digital's Sil SCSI controller chip.
The SU chip supports both asynchronous and synchronous data transfers.
VAXstation 3520/3540 systems do not support the SCSI asynchronous
event notification feature. Figure 1-7 shows a representative configuration
of the VAXstation 3520/3540 system.

1-19

Introduction to Device Drivers
1.6 Hardware Considerations

Figure 1-7 VAXstation 3520/3540 System Architecture

Main Memory
(Up to 64Mb)

CPU
128Kb

OMA
Buffer

I
SCSI
Disk Device
(Target)

Other
SCSI Device

SCSI
Disk Device
(Target)

SCSI
Tape Device
(Target)

Logical
Unit
(Target)
ZK-1368A-G E

Although VAX VMS SCSI implementation is currently based on the
SCSI-1 standard, the SCSI-1 standard is upwardly compatible with
SCSI-2. SCSI-2 clarifies many of the details specified in the SCSI-1
standard. Any non-Digital-supplied device to be attached to the SCSI
bus of a MicroVAX/VAXstation system must implement all mandatory
features of the SCSI-2 standard as described in the specification. The
device is permitted to implement any optional features, as long as they
are implemented according to the SCSI-2 standard. The device may
implement vendor-unique features, as long as they are implemented in
areas clearly designated as such by the standard.

1-20

Introduction to Device Drivers
1.6 Hardware Considerations

The ANSI SCSI specification is, in places, very broad and flexible. In some
cases, it is possible for a SCSI device to conform to the specification but
be unsupported by the VMS operating system. For instance, it is possible
that a SCSI device may implement a maximum timeout value that is
incompatible with a value required by the VMS operating system. For
additional information on VMS SCSI device support, see Chapter 17.

1.7

Programmed-110 and Direct-Memory-Access Transfers
Devices are equipped with various registers that initiate, control, and
monitor the progress of data transfer, seek operation, or other requests for
device activity. When it completes a request, the device posts an interrupt
to the processor. The size of the transfer concluded by a device interrupt
depends upon the capabilities of the device.

1.7.1

Programmed 1/0
Drivers for relatively slow devices, such as printers, card readers,
terminals, and some disk and tape drives, must transfer data to a device
register a byte or a word at a time. These drivers must themselves keep
a record of the location of the data buffer in memory, as well as a running
count of the amount of data that has been transferred to or from the
device. Thus, these devices perform programmed 1/0 (PIO) in that the
transfer is largely conducted by the driver program.
Examples of UNIBUS devices that do PIO transfers are the LPll and the
DZll. Corresponding Q22 bus devices that perform PIO transfers are the
LPVll and the DZVll.
Chapter 2 outlines the action of the LPll driver. The LPll driver
transfers data from a system buffer to the line printer data buffer register
a byte at a time, while maintaining a count of the number of bytes left to
transfer. When the line printer data buffer is full, the line printer sets a
"not ready" bit in its status register. If the driver, while examining this
register, sees this bit set, it enables interrupts from the printer and then
suspends itself in the expectation that the printer will post an interrupt
to the processor. While the driver remains suspended, the printer prints
the data from its buffer and interrupts the processor when it is done. With
the interrupt handled by the system interrupt dispatcher and the driver
interrupt service routine, driver execution resumes. The driver repeats
both its byte-by-byte transfer to the printer data buffer, as well as the
entire routine described previously, until it determines that all the data
has been transferred as requested.
Drivers performing PIO transfers are generally not concerned with the
operation of 1/0 adapters. However, drivers that perform direct-memoryaccess (DMA) transfers must take into account I/O adapter functions, as
discussed in Section 1. 7.2.

1-21

Introduction to Device Drivers
1.7 Programmed-1/0 and Direct-Memory-Access Transfers

1.7.2

Direct-Memory-Access 1/0
Devices that perform direct-memory-access CDMA) transfers do not
require the central processor so frequently. Once the driver activates the
device, the device can transfer a large amount of data without requesting
an interrupt after each of the smaller amounts. The responsibilities of
a driver for a DMA device involve supplying a device register with the
starting address of the buffer containing the data to be transferred, a
byte offset into the buffer, and the size of the transfer. By setting the
appropriate bit or bits in the device control and status register (CSR), the
driver activates the device. The device then automatically transfers the
specified amount of data to or from the specified address. The VMS drivers
DLDRIVER and XADRIVER are examples of DMA drivers. They appear
in full in the appendixes of the VMS Device Support Reference Manual.
For DMA transfers, UNIBUS and Q22 bus drivers must first map the
transfer from main memory to I/O bus memory space. The result of
this mapping is a set of contiguous addresses in UNIBUS or Q22 bus
space that the DMA device can access to successfully perform a DMA
transfer. To accomplish this, a driver must first obtain map registers,
and, optionally for UNIBUS drivers, a buffered data path. The driver
calls VMS routines that interface with the I/O adapter to allocate these
resources on behalf of the driver. Chapter 14 discusses the operation of
the UNIBUS adapter and the Q22 bus. Section 14.2 provides instructions
on how to write a DMA driver for UNIBUS and Q22 bus devices.
Some controllers that can do DMA transfers on the Q22 bus have
microcode that allows the controller itself to do physical-to-virtual address
mapping. This allows such controllers to do scatter-gather mapping,
eliminating the need for transfers to be made to or from physically
contiguous main memory.
The method by which a generic VAXBI device capable of DMA transfers
accomplishes such a transfer depends upon the characteristics of the
device. Several methods are discussed in Section 16.6.

1.8

Buffered and Direct 1/0
A separate issue, but one related to the data transfer capabilities of a
device, results from the fact that the original buffer, as specified in the
user $QIO request, is in process space and is mapped by process pagetable entries. Because the driver cannot rely on process context existing at
the time the device is ready to service the I/O request, it must have some
means of guaranteeing that it can access both the data involved in the
transfer and the page-table entries that map the buffer.
The VMS operating system provides the following two techniques that are
employed by device drivers:

•

1-22

Direct 110, the technique used most commonly by drivers of DMA
devices, locks the user buffer in memory as well as the page-table
entries that map it. The function decision table (FDT) of such a driver
calls a VMS-supplied FDT routine that prepares the user buffer for
direct I/O.

Introduction to Device Drivers
1.8 Buffered and Direct 1/0

•

Buffered 1/0 is the strategy whereby the driver FDT dispatches to
an FDT routine in the driver that allocates a buffer from nonpaged
pool. It is this intermediate buffer that is involved in the transfer.
The driver later refers to the buffer using addresses in system space.
Driver preprocessing routines copy the data from the user buffer to the
system buffer for a write request; VMS I/O postprocessing (by means
of a special kernel-mode AST) delivers data from the system buffer to
the user buffer for a read request. Drivers most often use buffered I/O
for PIO devices such as line printers and card readers.

The trade-off between buffered 1/0 and direct I/O is the time required to
move the data into the user's buffer as against the time required to lock
the buffer pages in memory. Sections 6.3.1 and 7.4 provide additional
information.

1.9

Example of an 1/0 Request
Figure 1-8 illustrates how the VMS operating system and the device
driver process a user request for a read I/O operation for a DMA device
attached to a UNIBUS or Q22 bus.
Figure 1-8 Example of 1/0 Request Processing

User
process
requests

1/0.

Device
generates
interrupt.

Driver
read
function
validates
request.

Driver
collects
status.

010

service
routine
validates
request.

Driver
interrupt
handler
restores
driver state.

i--.

Operating
system
calls
driver.

Driver
starts
device
and waits for
interrupt.

f--1-

Operating
system
copies
dataand
status.

User
process
reads data
and status.

Operating
system
saves
driver
state.

ZK-0909-GE

The processing of the sample 1/0 request illustrated in Figure 1-8 occurs
in the following steps:

A process requests an 1/0 operation.
A user process initiates an 1/0 request by issuing either a $QIO
system service call or an RMS call resulting in a call to the $QIO
system service.
The user process specifies the target device, a read function code, and
the address of a buffer into which the data is to be read.

1-23

Introduction to Device Drivers
1.9 Example of an 1/0 Request

The operating system performs 1/0 preprocessing.
The $QIO system service validates the request and locates data
structures in the I/O database that describe the device and its driver.
The system service also allocates and initializes an I/O request packet
to contain a description of the I/O request. The system service then
calls a reading routine in the driver.

The driver performs 1/0 preprocessing.
The driver FDT routine verifies that the user buffer resides in virtual
memory pages that can be modified by the requesting process, locks
the buffer pages in memory, and adds details of the I/O operation to
the I/O request packet. The read FDT routine then calls the operating
system to send the I/O request packet to the driver.

VMS creates a driver's fork process.
A VMS routine creates a fork process in which the device driver can
execute. The routine activates the driver's fork process by transferring
control to the driver's start-I/O routine.

The driver readies the 1/0 adapter.
For DMA transfers, the driver's fork process calls VMS routines
that enable the I/O adapter hardware to map I/O bus addresses into
physical addresses for the transfer.

The driver activates the device.
The fork process activates the device by setting bits in device registers.

The driver waits for an interrupt.
A VMS routine saves the c9ntext of the driver's fork process and
relinquishes the processor until an interrupt occurs.

The device requests an interrupt.
When the data transfer is complete, the device requests a hardware
interrupt that causes the system to dispatch to the driver's interrupt
service routine.

The driver services the interrupt.
The driver's interrupt service routine handles the interrupt and
reactivates the driver, which reads device registers to obtain status
information about the transfer.

10 The operating system inserts the driver in a fork queue.
The driver requests that it again be suspended, to be reactivated later
at a lower software interrupt priority level (IPL).
11 The fork dispatcher reactivates the driver's fork process.
When processor priority permits, the VMS fork dispatcher reactivates
the driver as a fork process.

12 The driver completes the 1/0 operation.
The driver's fork process completes device-dependent processing of the
IIO request and returns the I/O status to VMS.

1-24

Introduction to Device Drivers
1.9 Example of an 1/0 Request

13 VMS completes the 1/0 operation.
The VMS I/O postprocessing routines copy the I/O status into process
address space, general registers, or both, and return control to the user
process.
Only four of these 13 steps describe the driver's I/O preprocessing and fork
processing. The VMS I/0-support routines perform I/O processing common
to many I/O requests. Driver writing is further simplified by the use of
VMS routines that handle device-independent functions.
This example simplifies the processing of an I/O operation by ignoring
such issues as
•

The association of a device with a process, which is to say, device
assignment

•

Simultaneous I/O requests for one device

•

System synchronization issues, such as IPLs and spin locks

•

Driver competition for shared system and I/O adapter resources

•

Driver competition for a multiunit controller

•

Driver recovery from device errors or power failure

Subsequent chapters discuss each of these issues in relation to device
drivers.

1-25

Discussion of a $QIO Request

This chapter outlines the series of activities performed by the VMS
operating system and a simple device driver in order to process an 1/0
request. The LPll line printer driver (LPDRIVER) was selected for this
discussion because it is a simple driver but still illustrates many driver
principles. The first-time reader of this document might not understand
all of the points made in this chapter; however, the chapter should provide
some insight into driver flow and 1/0 processing.
The LPll printer is a programmed 1/0 (PIO) device (see Section 1.7.1).
Although the LPll is usually spooled, this discussion assumes it is not.
A user process can request the following functions on this printer:
•

Write data to the printer

•

Read the printer's device characteristics

•

Alter the printer's device characteristics

This chapter describes two aspects of printer 1/0 processing:
•

The portions of the line printer driver that are used in servicing a
write request

•

The VMS components with which the driver interacts to process the
write request

Figure 2-1 illustrates the flow of execution through the VMS executive
routines and printer driver code that satisfies an 1/0 request. Boxes above
the solid line indicate processing in user-process context. Boxes below the
line indicate processing in fork or interrupt context.

2.1

Driver Code for the LP11 Write Function
The VMS device driver for an LPll printer implements a write function
using the following parts of the driver:
·
•

A function decision table (FDT) routine that reformats the usersupplied data

•

A start-1/0 routine that writes data to the printer data buffer register
until the printer enters a busy state as it prints the contents of its
internal print silo

•

Code that modifies a device register to enable interrupts from the
printer

2-1

Discussion of a $QIO Request
2.1 Driver Code for the LP11 Write Function

Figure 2-1

•

An interrupt service routine that returns control to the driver's fork
process after a hardware interrupt from the printer

•

Code that returns I/O status to a VMS I/O completion routine

A Printer Write Function

010
Validation

1
Kernel
Mode

FDT
Subroutine

AST

I
_i_

User
Context
System
Context

Deliver
IRPto
Driver

1
Suspend
Driver

I+-

Device
Goes
into Busy
State

Driver
Writes to
Device

I
Queue

IRPto
Post
Processor

I+-

Driver
Returns
Status

Interrupt
Handler

Operating
System
Dispatches
Interrupt

I+-

Device
Generates
Interrupt

1
110
Post
Processor

I
ZK-0911-GE

2.2

A User Process 1/0 Request
A user process writes a line to the printer by calling the Queue I/O
Request ($QIO) system service, specifying the write-virtual-block function
code as follows:
$QIO_S

chan = CHANNEL_NUMBER,func = #IO$ WRITEVBLK,efn = #6,iosb = STATUS_BLOCK,pl
BUFFER ADDRESS,p2 = #BUFFER_SIZE,p4 = #AX30
;Carriage control character

Note that pl, p2, and p4 are device-dependent arguments.

2-2

Discussion of a $QIO Request
2.3 Device-Independent 1/0 Preprocessing by VMS

2.3

Device-Independent 1/0 Preprocessing by VMS
The $QIO system service first validates that the 1/0 request is correctly
specified. The 1/0 request must meet the following criteria:
•

The location CHANNEL_NUMBER must contain a number that serves
as a valid index into the process's channel list. This means that the
process must have previously assigned the printer to this process
channel using the Assign 1/0 Channel ($ASSIGN) system service.
Once $QIO locates the assigned channel control block, it can retrieve
the address of the unit control block (UCB) of the target device of the
request. Ultimately, it obtains the address of the driver's function
decision table (FDT), by way of a chain of longword pointers within the
1/0 database:
CCB ~ UCB ~ DDT ~ FDT address

•

The driver FDT must list 10$_WRITEVBLK as a valid function for the
device.

•

The event flag number must be valid.

•

The process's remaining buffered 1/0 count (BIOCNT) must permit the
$QIO system service to perform a buffered-1/0 request.

•

The process must have write access to location STATUS_BLOCK,
specified in the request for use as an 1/0 status block (IOSB).

If all of these checks succeed, the $QIO system service creates an 1/0
request packet (IRP) in nonpaged system address space. The service then
writes all known details about the 1/0 request into the IRP.
If the target device for the 1/0 request is not file structured, the $QIO
system service changes any virtual-function code to its equivalent logicalfunction code when it builds the IRP. Thus, for a printer device, 10$_
WRITEVBLK is translated to 10$_WRITELBLK.

2.4

Device-Dependent 1/0 Preprocessing by the Driver
Once it has validated the 1/0 request, the $QIO system service scans the
FDT for an entry that associates the 10$_WRITELBLK function code with
an FDT routine. The system service calls the routine, which in the case of
the printer driver is a device-specific routine located in the printer device
driver.
The FDT routine confirms that the requesting process has read access to
the buffer starting at BUFFER_ADDRESS. Then, the FDT routine buffers
data from the process address space into system address space in the
following steps:
1

It calculates the length of the required system space buffer.

If the job byte count quota for buffered 1/0 (JIB$L_BYTCNT) permits,

the routine allocates a buffer from system address space, stores the
address of the buffer in the IRP, and decreases the current job byte
count quota.

2-3

Discussion of a $QIO Request
2.4 Device-Dependent 1/0 Preprocessing by the Driver

It then synchronizes access to the printer's UCB by obtaining its
mutex semaphore (UCB$L_LP_MUTEX) for write access. It can thus
reliably preprocess the write request, depending upon information
contained in the UCB.

By obtaining the line printer mutex semaphore, the driver FDT routine
effectively prevents processes active in a VMS multiprocessing system
from initiating simultaneous functions on the printer. Also, in a
VMS uniprocessing system, this action prevents contention between
a process that has allocated the printer (and has been preempted in
the midst of a write function) and any of its subprocesses that, when
scheduled, may attempt to start a concurrent function that alters
device characteristics.
4

It reads the description of the printer's current line and page position
from the device's UCB.

It reformats the data from the process buffer into the system buffer,
adding carriage-control characters, as specified in argument p4 to the
I/O request, before and after the data.
Formatting includes such functions as the replacement of horizontal
tabs with multiple spaces and the replacement of lowercase characters
with uppercase characters, if necessary.

It rewrites updated line and page positions into the device's UCB.
This information indicates what the current location on the page being
printed will be when the request completes.

Finally, the routine transfers control to a VMS routine that queues the
IRP to the device driver.

All of the I/O processing described to this point occurs in the context of the
user's process. The user address space is mapped, and the processor's IPL
is still low enough to permit process scheduling and paging. Subsequent
queuing of the transfer request to the driver and all resulting driver
processing occur at higher IPLs-and with ownership of the appropriate
fork lock and device lock in a VMS multiprocessing environment-that
synchronize the driver's handling of the device. (See Chapter 3 for a
discussion of the concept of synchronization.)

2.5

Queuing the 1/0 Request Packet to the Driver
Before queuing the IRP to the printer driver, the VMS queuing routine
raises the IPL to the driver's fork level and obtains the associated fork
lock in a VMS multiprocessing environment. These actions synchronize
access to those fields of the UCB referenced by driver routines at fork IPL.
If the device is idle, which is to say that if the busy bit in the UCB status
longword (UCB$V_BSY in UCB$L_STS) of the UCB is clear, VMS can
transfer control to the driver. The driver dispatch table (DDT) contains
the entry point to the driver's start-I/O routine. To find the proper entry
point, the queuing routine chains through the I/O database to the DDT, as
follows:

UCB-+ DDT-+ start-I/0 routine address

2-4

Discussion of a $QIO Request
2.5 Queuing the 1/0 Request Packet to the Driver

If the device unit is busy with another transfer, VMS inserts the IRP in
a queue of packets waiting for the unit. The UCB contains the head of
the queue. The packet's position in the queue depends on the scheduling
priority of the process issuing the request.

2.6

Activating the Printer
The LPll printer controller accepts data into an internal print silo until
the silo is full or the driver writes a carriage-control character to the
printer's data buffer register. When either event occurs, the printer sets a
busy bit in the device's control and status register (CSR). Then the device
driver sets the interrupt-enable bit in the device's CSR and waits for the
printer to interrupt. When the printer requests a hardware interrupt, the
driver can resume writing characters to the printer's data buffer register.
The driver routine delivers characters to the printer according to the
following sequence:
1

The driver clears the device lock and locates the LPll device registers
using a chain of pointers starting at the device's UCB.
UCB--+ CRB--+ IDB--+ CSR address
The CSR address is always the address of the printer's CSR, and all
other device registers are at fixed offsets from this address. In contrast
to many other devices, such as disks, the LPll printer does not share
a controller with other devices; therefore, no arbitration for ownership
of the controller is required.

The driver examines the device's CSR to see if the device is ready to
accept characters.

If the device is ready, the driver writes a byte of data to the printer's
data buffer register. The printer controller moves the byte from the
register to the controller's internal print silo.

The driver decreases the count of bytes to transfer and repeats step 2.

If the device is not ready (that is, its print silo is full), the driver raises
IPL to device IPL and obtains the corresponding device lock in a VMS
multiprocessing system. These actions allow it to set the interruptenable bit in the device's CSR in synchronization with other routines
in the driver that may access the CSR.

After setting the interrupt-enable bit, the driver invokes a VMS waitfor-interrupt macro to release the device lock and suspend driver
processing until the printer requests an interrupt or the device times
out.

2.7

Waiting for a Device Interrupt
The VMS wait-for-interrupt routine suspends the driver by performing the
following functions:
•

Saving driver context (R3, R4, and the address of the next instruction
in the driver) in the device's UCB

2-5

Discussion of a $QIO Request
2.7 Waiting for a Device Interrupt

•

Calculating the time at which the device will time out

•

Setting bits in the device's UCB to indicate that the driver expects a
device interrupt within a specified time period

•

Releasing the device lock in a VMS multiprocessing system, restoring
IPL to fork level, and returning control to the caller of the driver's
start-I/O routine

The driver remains in a suspended state until one of the following two
events occurs:
•

The printer requests a hardware interrupt.

•

VMS reports a device timeout because the printer did not request a
hardware interrupt within a specified period of time.

Normally, the LPll prints the contents of its data buffer and requests the
interrupt.

2.8

Handling Interrupts
When the LPll printer requests a hardware interrupt, the interrupt
dispatcher passes the interrupt to the LPll driver's interrupt service
routine.
The driver's interrupt service routine restores control to the driver, as
follows:
1

Restores the address of the UCB in R5

Obtains the appropriate device lock to ensure synchronization in a
VMS multiprocessing environment

Confirms that the interrupt was expected by examining bits in the
device's UCB

Restores the saved registers (R3 and R4) from the device's UCB

Transfers control to the driver program counter (PC) address stored in
the device's UCB

Rather than execute in interrupt context, the reactivated driver routine
calls a VMS routine to create a fork process. As a result of this action,
VMS again suspends driver processing by performing the following steps:
1

Saving driver context (R3, R4, and the driver PC address) in the
device's UCB

Inserting the UCB address in the appropriate fork queue in the local
processor's CPU database

The driver suspension allows the operating system to reschedule driver
processing at its fork IPL and permits higher priority code to execute and
device interrupts to be serviced while driver processing of the 1/0 request
concludes. The VMS fork dispatcher reactivates the driver when the IPL
of the local processor drops to fork level.

2-6

Discussion of a $QIO Request
2.8 Handling Interrupts

After creating the fork process, the system returns control to the driver's
interrupt service routine, which restores the registers saved at the time of
the device interrupt, releases the device lock, and dismisses the interrupt.

2.9

1/0 Postprocessing by the Driver
When the VMS fork dispatcher reactivates the driver's fork process, the
driver obtains the number of characters left to transfer from the UCB.
If there are still characters to transfer, the driver and printer repeat the
procedures outlined in Sections 2.6 to 2.8, until the transfer is complete.
When all characters have been transferred, the driver code branches to the
driver's I/0-completion code.
The driver's 110-completion code stores a success status code and the
number of bytes transferred in RO, then transfers control to VMS to
complete the I/O request.

2.10

1/0 Postprocessing by VMS
The operating system inserts the IRP into the systemwide 110
postprocessing queue and requests an interrupt from the processor
at IPL$_IOPOST. If another IRP is queued to the UCB for the device
unit, VMS dequeues that packet and calls the driver start-110 routine to
process it. When IPL drops to IPL$_IOPOST, the processor grants the
110 postprocessing interrupt request. The I/O postprocessing dispatcher
dequeues the packet for the printer 110 request and performs the following
steps:
1

Increases the use count (PHD$L_BIOCNT) of the process's buffered
110 requests because the current operation is complete. The use count
is maintained for accounting purposes.

Decreases the process's buffered I/O count (PCB$W_BIOCNT) to
reflect a completed buffered I/O operation. This operation restores
buffered-110 quota to the process.

Deallocates the system buffer used for the reformatted user data.

Increases the job's byte count quota.

Sets an event flag to indicate that the 110 operation is complete.

Queues a special kernel-mode asynchronous system trap (AST) routine
that will deallocate the IRP and stores I/O status in the user's 110
status block (IOSB).

The user process determines when the I/O operation is complete by the
setting of the event flag or the filling of the (IOSB), or both, according to
the method defined in the I/O request. The Queue 1/0 Request and Wait
($QIOW) system service completes synchronously and returns control and
status to the user process only after the I/O operation has been completed.
The Synchronize ($SYNCH) system service waits for the completion of
an 110 request, initiated by the $QIO system service, that completes
asynchronously to user process activity.

2-7

Synchronization of 1/0 Request Processing

Because a device driver executes as kernel-mode code, it can preempt core
system tasks and access critical system data. As a result, it must adhere
to a set of rules that governs the priority of system activities and controls
the flow of system events. These synchronization rules ensure that both
the operating system and the device driver access memory in an orderly
and consistent fashion.
This chapter contains the following discussions:

3.1

•

Section 3.1 discusses the interrupt priority levels (IPLs), focusing
on those IPLs and interrupt service routines that participate in the
processing of an 1/0 request. It briefly examines the roles of the other
IPLs in the operating system. Whether you are writing a driver for a
VMS uniprocessor or multiprocessor environment, you must adhere to
the synchronization rules discussed in this section.

•

Section 3.2 discusses the various VMS spin lock semaphores, including
when and how they ensure proper multiprocessing operation.

•

Section 3.3 illustrates how system synchronization is maintained
during the processing of an I/O request on any VAX system. As part of
this discussion, this section describes the driver fork process and the
activity of forking. Finally, it examines the methods by which a driver
synchronizes at fork level and device interrupt level.

•

Section 3.4 discusses the mechanism by which driver code stalls
to wait for an available adapter or controller resource on any VAX
system.

Interrupt Priority Levels
The VAX architecture defines 32 levels of hardware priority, called
interrupt priority levels (IPLs). These IPLs govern the sequence of
system events that occur on each processor in a VAX system. The highernumbered IPLs (16 to 31) are reserved for hardware interrupts, and the
lower-numbered IPLs (1 to 15) are reserved for software interrupts. Most
process-based software runs at IPL 0.
The hardware IPLs (16 to 31) are used for device interrupts (IPLs 20
to 23), interprocessor interrupts in a multiprocessing system, interval
timer interrupts, urgent conditions like power failure, and such serious
errors as a machine check. Those IPLs that have a bearing on driver
execution are discussed in Sections 3.1.2 and 3.1.3. For specific hardware
IPL information, see your VAX system's hardware documentation or the
VAX Hardware Handbook.

3-1

Synchronization of 1/0 Request Processing
3.1 Interrupt Priority Levels

The software IPLs (1 to 15) are defined by VMS as illustrated in
Table 3-1.
Table 3-1
IPL

IPLs Defined by VMS
Symbolic Name

Use
Execution of most process-based software

Reserved
IPL$_ASTDEL

Servicing of AST-delivery interrupts

IPL$_RESCHED

Servicing of scheduler interrupts

IPL$_10POST

Servicing of 1/0-postprocessing interrupts
Reserved

IPL$_QUEUEAST

Fork level processing for queuing ASTs

IPL$_TIMERFORK

Entry level for software timer interrupt servicing

IPL$_SYNCH

Synchronization of access-to-system
databases in a uniprocessor system 1

IPL$_MAILBOX
IPL$_POOL

Fork level processing for access to mailboxes
Allocation of nonpaged pool

8-11

Fork level processing for executing driver code

Recalculation of quorum; cancellation of mount
verification (IPC)

Reserved

Entry level for XDelta debugger

Reserved

1 IPL$_TIMER, IPL$_SCHED, IPL$_JIB, IPL$_MMG, IPL$_FILSYS, and IPL$_10LOCK8 are all
synonyms for IPL$_SYNCH (see Table 3-3).

Because a higher IPL takes precedence over a lower IPL, a routine
executing at one IPL can block interrupts on a processor at that IPL
and all lower IPLs. This scheme allows VMS to assign the higher IPLs to
system activities that must be dispatched quickly and with little chance
of interruption. In a general sense, each processor services interrupts
according to the following priorities:

• Power failure

•
•
•
•

Processor errors
Device interrupts
Device driver fork processing
1/0 postprocessing

• Process rescheduling
• AST delivery

3-2

Synchronization of 1/0 Request Processing
3.1 Interrupt Priority Levels

As a result of blocking events on and ordering the activities of a single
VAX processor, VMS use of IPLs ensures that kernel-mode code accesses
data in memory in a cooperative and predictable manner. The mechanism
by which synchronized access to data is ensured is twofold. First, VMS
associates a given IPL with the access of one or more data structures
or databases. Secondly, VMS defines an ordered set of semaphores,
called spin locks, that extend IPL synchronization throughout a VMS
multiprocessing system. A processor must obtain one or more of these
spin locks before executing any code thread that must make use of the
resources the spin lock protects. Spin locks thus allow each processor in
a VMS multiprocessing system to share common system data and block
events systemwide.
For example, consider a code thread running at IPL 4 that intends to
access the memory management database. To do so, it raises IPL to IPL$_
MMG. This action gives it the exclusive right to access the database from
the local processor, effectively preventing access by other code threads
on the same processor. After raising IPL, this code thread requests the
memory management (MMG) spin lock. Ownership of the MMG spin lock
gives the processor executing this thread the exclusive right to access the
database systemwide, and bars access from any other code thread running
on any other processor in the VAX system.
Although discussions in this book treat IPL and spin lock synchronization
as conceptually separate tasks for a device driver, VMS synchronization
macros make adjustment of IPL and disposition of spin locks appear as a
single operation.
A full description of spin locks appears in Section 3.2.

3.1.1

Interrupt Service Routines
VMS associates certain IPLs with the execution of certain tasks. Moreover,
when a processor in a VAX system grants an interrupt at a given IPL, the
grant actually triggers the execution of a specific piece of code, called an
interrupt service routine, that performs the task.
Device drivers themselves contain an interrupt service routine that
handles device interrupts at an appropriate device IPL (IPLs 20 to 23).
In addition, drivers rely heavily upon the VMS interrupt service routine
known as the fork dispatcher that runs at several IPLs, including driver
fork IPLs 8 to 11. When the local processor's IPL drops to fork IPL, it is
the fork dispatcher that restores the context of the driver fork process and
places it into execution. (See Sections 3.1.2.4 and 3.3.2 for discussions of
the device IPLs and interrupt dispatching, respectively. Sections 3.1.2.3
and 3.3.3 discuss the fork IPLs and driver fork processes.)

3-3

Synchronization of 1/0 Request Processing
3.1 Interrupt Priority Levels

3.1.2

IPL Use During 1/0 Processing
The activities essential to the processing of an 1/0 request occur only
at certain IPLs. VMS performs some of these tasks in system routines
and interrupt service routines; drivers perform others. This section
describes those IPLs and interrupt service routines that are most
involved in 1/0 processing. Section 3.1.3 discusses the IPLs at which
other system activities transpire that may influence the coding of a driver.
For additional information on the pattern of synchronization throughout
the servicing of an 1/0 request, see Section 3.3.
3.1.2.1

IPL 2 (IPL$_ASTDEL)
The asynchronous system trap (AST) delivery interrupt service routine
(SCH$ASTDEL) is associated with IPL$_ASTDEL.

When an AST is specified for delivery to a process, the AST queuing
routine (SCH$QAST) queues the AST to the specified process's process
control block (PCB ). 1 When an AST is delivered is determined by the mode
of the AST, the current mode of the processor, and the mode contained
in the processor's ASTLVL register. The VAX hardware, by means of the
REI instruction, requests a software interrupt on the local processor at
IPL$_ASTDEL whenever the processor's mode becomes less privileged
than that specified as its ASTLVL. 2
The AST delivery interrupt service routine gains control when the
processor's IPL drops below IPL$_ASTDEL, and delivers all deliverable
ASTs to the currently scheduled process. Any code executing at IPL$_
ASTDEL or higher blocks the execution of this interrupt service routine.
To block the delivery of ASTs-specifically the kernel-mode AST that
causes process deletion-1/0 preprocessing, from the time that the $QIO
system service allocates an IRP through the execution of the last FDT
routine, occurs at IPLs no lower than IPL$_ASTDEL. The VMS allocation
routine records the address of the system memory allocated for the IRP
in a process register; if an AST that deletes the process were to occur, the
allocated memory would be lost from the pool.
In addition, some 1/0 postprocessing occurs in a special kernel-mode
AST servicing routine that also executes at IPL$_ASTDEL. The special
kernel-mode AST, running in the context of a process whose 1/0 has been
completed, writes status information into an 1/0 status block, copies
buffered input into process space, and deallocates system buffers. The
completion of these tasks depends on the availability of process context.

Because the VMS AST queuing and delivery routines access the scheduler database, they synchronize
within a VMS multiprocessing environment by obtaining the SCHED spin lock before modifying system
data.
2
In the event that a processor queues an AST to a process currently executing on another processor in a
multiprocessing system, the local processor generates an interprocessor interrupt to the other processor to
change its ASTLVL.

3-4

Synchronization of 1/0 Request Processing
3.1 Interrupt Priority Levels

Page faults may be taken by code that executes at IPL$_ASTDEL.
However, this is not the case with code executing at higher IPLs. Thus,
programs that are sensitive to the contents of pageable data structures
run at IPL$_ASTDEL to take page faults. For example, the allocation of
paged pool is one such program code thread; paged pool, as a result, is
protected by a mutex.
3.1.2.2

IPL 4 (IPL$_10POST)

The IPL$_IOPOST interrupt service routine (IOC$IOPOST) performs
device-independent postprocessing of an I/O request. As appropriate to the
I/O request, it adjusts process quota use and deallocates system memory.
IOC$IOPOST also queues a special kernel-mode AST to the process's PCB
that, once process context is restored, writes status and data into the
process's address space.
After it has completed whatever device-dependent postprocessing is
required, a driver fork process requests I/O postprocessing by calling a
VMS routine (IOC$REQCOM) that inserts an IRP in the systemwide I/O
postprocessing queue and requests a software interrupt at IPL$_IOPOST.
When IPL drops below IPL 4, the IPL$_IOPOST interrupt service routine
dequeues an IRP from the I/O postprocessing queue, performs all I/0completion tasks that can occur without reference to the device's unit
control block (UCB) and, thus, at an IPL lower than fork IPL.
I/O postprocessing runs at an IPL higher than IPL$_RESCHED so that all
pending I/0-completion processing is finished before the scheduler looks for
a new process to schedule. The ability of a process to execute can depend
on the completion of the postprocessing of an I/O request. Additionally,
I/O postprocessing can queue ASTs to certain processes, thus changing
their state to computable and resulting in a priority boost. Because all I/O
completions are accomplished before rescheduling activities, the scheduler
can select from a potentially larger set of computable processes, using
more up-to-date information about these processes.
3.1.2.3

IPL 8 to IPL 11 (Fork IPLs)

On each processor in a VAX system-for each of the IPLs from 8 to 11there exists a queue for fork blocks waiting to be processed. Each fork
block contains the context of a suspended fork process. The interrupt
service routine that executes at each of these IPLs (EXE$FORKDSPTH)
is known as the fork dispatcher. The fork dispatcher dequeues a fork
block, obtains the appropriate fork lock, restores the context of the fork
process, and resumes its execution at the PC location saved in the fork
block (at FKB$L_FPC). (Refer to Section 3.3.3 for a discussion of fork
blocks and fork processes.)
All driver routines, except most FDT routines, execute at fork IPL or
higher. Usually driver routines should not read or alter UCB fields
without taking steps to ensure synchronization. Because such UCB
fields can be shared among driver fork processes and VMS system
tasks executing on other processors in a VMS multiprocessing system,
a processor must first secure the corresponding fork lock to execute at
that fork IPL. Furthermore, the drivers for all devices on a single I/O
adapter must use the same fork lock if they actively compete for shared
1/0 adapter resources such as map registers and data paths. The VMS

3-5

Synchronization of 1/0 Request Processing
3.1 Interrupt Priority Levels

routine that initiates an I/O request on an idle device unit, as well as
the fork dispatcher, transfers control to the driver with the appropriate
synchronization.
A driver places a fork lock index in UCB$B_FLCK using the DPT_STORE
macro. (See Section 6.1.) VMS determines the appropriate fork IPL from
the contents of the SPL$B_IPL field in the fork lock's structure. (See
Section 3.2 for a discussion of spin locks.)
3.1.2.4

IPL 20 to IPL 23 (Device IPLs)

VAX peripheral devices request interrupts at IPLs 20 to 23 because device
interrupts usually need to preempt most user and VMS software functions.
When a device requests an interrupt at one of these IPLs and the processor
is executing at a lower IPL, the processor grants the interrupt, and then
transfers control to an interrupt service routine for the device located in its
driver. If the processor is executing at a higher or equal IPL, the interrupt
remains pending.
The interrupt dispatcher routes interrupts from devices to the
appropriate device driver's interrupt service routine. A driver specifies
the address of its interrupt service routine in the driver prologue table
(DPT). The interrupt dispatcher's routing mechanism works differently
depending upon the VAX processor and 1/0 subsystem in use. (For
additional information on device interrupt dispatching, see the general
discussion of interrupt dispatching in Chapter 9. Information specific to a
given 1/0 subsystem configuration appears in Sections 14.3 (UNIBUS/Q22
bus), 15.4 (MASSBUS), and 16.4.1 (VAX.BI bus).)
Data in a device's registers and in various fields of the UCB that record
device status is synchronized on the local processor at device IPL, at which
its driver's interrupt service routine executes. This value is stored by the
driver in the UCB$B_DIPL field of the UCB. It is the responsibility of the
interrupt service routine to secure the corresponding device lock. This
action allows it to synchronize with other code threads that access the
same resources in a VMS multiprocessing system.
The driver's start-1/0 routine is one such code thread and must similarly
synchronize. In a VMS uniprocessing environment, the routine raises IPL
to device IPL before writing data in device registers and database fields.
In a VMS multiprocessor environment, the start-1/0 routine must secure
the appropriate device lock to achieve systemwide synchronization of the
device database. The act of acquiring the device lock automatically sets
IPL to device IPL.
Because code executing at IPLs 20 to 23 blocks most other hardware
interrupts and all software interrupts on the local processor, driver
code lowers its IPL as soon as possible. Interrupts from devices on a
MicroVAX system, VAX 82x0/83x0, VAX 85x0/8700/88x0, VAX 6000-series,
or a VAX 9000-series system, in fact, can block hardware interrupts from
the processor's interval clock if these device interrupts occur at or above
IPL 22. To prevent the loss of an interval clock interrupt, these drivers,
when executing at IPL 22 or above, should lower IPL below 22 as soon as
possible (within 9 milliseconds).

3--6

Synchronization of 1/0 Request Processing
3.1 Interrupt Priority Levels

3.1.2.5

IPL 31 (IPL$_POWER)
The highest IPL, IPL$_POWER (IPL 31 ), locks out all other interrupts on
the local processor. Many VMS routines and drivers raise IPL to IPL$_
POWER to execute code sequences that cannot tolerate interruption. For
example, much of system initialization occurs at IPL$_POWER. In a VMS
multiprocessing system, these routines often need to acquire additional
synchronization, as described in Section 3.2.

When a device driver needs to execute a series of instructions without
interruption, the driver raises IPL to IPL$_POWER. The driver should
never remain at IPL$_POWER for more than a few instructions. The
most common instance of a driver's raising IPL to IPL$_POWER is to
determine whether a power failure has occurred on the local processor
between the time that the driver writes setup data into device registers
and the time that the driver starts the device by writing into the device's
control register.

3.1.3

Additional IPLs
In addition to the IPLs that are directly involved in the processing of an
1/0 request, VMS defines the IPLs described in this section.
3.1.3.1

IPL 3 (IPL$_RESCHED)
When an event occurs that requires that a process be rescheduled, a VMS
routine requests a software interrupt on the local processor at IPL$_
RESCHED. The scheduler interrupt service routine (SCH$RESCHED)
gains control at this IPL, but immediately obtains the SCHED spin lock
(as a result, raising IPL to IPL$_SYNCH). This action synchronizes the
processor's access to the scheduler's database with other system activities.

Drivers never explicitly reference IPL$_RESCHED. Most driver processing
occurs at higher IPLs. When a process raises IPL to or above IPL$_
RESCHED, the scheduler cannot reschedule the process. The process runs
until an interrupt occurs at a higher IPL or the process lowers IPL below
IPL$_RESCHED.
3.1.3.2

IPL 6 (IPL$_QUEUEAST)
IPL$_QUEUEAST is a fork-level IPL used predominantly by drivers
written before Version 4.0 of the VMS operating system. A driver
fork process originating at an IPL between 8 and 11 would use IPL$_
QUEUEAST when it needed to synchronize access to the scheduler's
database at IPL$_SYNCH-for instance, to queue an AST. Prior to
VMS Version 4.0, the only way that such a fork process could maintain
proper synchronization was to first call a system routine that creates yet
another fork process to be dispatched at IPL$_QUEUEAST. Once the fork
dispatcher dequeued the fork block and resumed execution of the driver,
the driver fork process could then raise IPL to IPL$_SYNCH and access
the system database.

Because versions of the VMS operating system after Version 4.0 implement
IPL$_SYNCH as a fork IPL, a driver fork process can fork directly to
IPL$_SYNCH. Since VMS Version 5.0, the fork dispatcher obtains the IPL
8 fork lock (10LOCK8), dequeues the driver fork block, restores driver

3-7

Synchronization of 1/0 Request Processing
3.1 Interrupt Priority Levels

context, and resumes execution of the driver. To maintain synchronization
in a VMS multiprocessing environment, the driver then must obtain the
spin lock that corresponds to the data structure it is accessing.
3.1.3.3

IPL 7 (IPL$_TIMERFORK)

The interval clock's interrupt service routine (EXE$HWCLKINT),
executing at IPL 22 or IPL 24 depending upon the VAX system, posts
interrupts at IPL$_TIMERFORK. A processor requests such an interrupt
when the current process has exceeded its processor time quantum. The
software. timer interrupt service routine (EXE$SWTIMINT) gets control
when the IPL drops below IPL$_TIMERFORK, services quantum end
events by immediately raising IPL to IPL$_SYNCH (obtaining the SCHED
spin lock, if needed), and calls the appropriate scheduler routine.
The primary processor in a VMS .multiprocessor system, when executing
the interval clock's interrupt service routine, requests an IPL$_
TIMERFORK interrupt when the first entry in the timer queue (EXE$GQ_
lST_TIME) is due. The software timer interrupt service routine contains
special code that allows the primary processor to service the expiration
of a timer queue element (TQE). The routine raises IPL to IPL$_SYNCH,
synchronizes access to the timer queue (except for the first TQE) by
obtaining the TIMER spin lock, and secures the interval clock database
(the system time at EXE$GQ_SYSTIME and the expiration time of the
first TQE at EXE$GQ_1ST_TIME) by obtaining the HWCLK spin lock.
Thus synchronized, it determines which TQEs have expired, dequeues
them, and transfers control to the appropriate timeout handlers. Device
timeouts are dispatched in this manner.
3.1.3.4

IPL 8 (IPL$_SYNCH)

IPL$_SYNCH is the level at which the databases that record and control
system functions are synchronized. Individual spin locks, such as the JIB,
SCHED, MMG, and TIMER spin locks, provide synchronized access to
individual databases in a VMS multiprocessing environment. 3 When a
VMS subroutine or a driver needs to modify or read a dynamic portion of a
system database, the routine always executes at IPL$_SYNCH, holding an
appropriate system spin lock, to ensure that the database does not change
because of some interrupt service routine or process action.
3.1.3.5

IPL 11 (IPL$_MAILBOX)

IPL$_MAILBOX is the highest fork IPL. When a VMS or driver routine
writes into a mailbox, the executing processor must be at IPL$_MAILBOX
holding the MAILBOX spin lock. Because other readers or writers to the
mailbox must similarly pursue synchronization, these actions prevent
other writers from modifying incomplete data in the mailbox and readers
from reading invalid data.

IPL$_TIMER, IPL$_SCHED, IPL$_SCS, IPL$_JIB, IPL$_MMG, IPL$_FILSYS, and IPL$_IOLOCK8 are all
synonyms for IPL$_SYNCH (see Table 3-3).

3-8

Synchronization of 1/0 Request Processing
3.1 Interrupt Priority Levels

3.1.3.6

IPL 14 {XDELTA Entry IPL)
For debugging purposes, you can halt a processor from the console
terminal and request a software interrupt to invoke the XDelta debugger.
You accomplish this by depositing OE16 in the processor's Software
Interrupt Request Register (PR$_SIRR). (The procedure for requesting
a software interrupt to invoke XDELTA is described in Table 13-3.)

After you issue the console's CONTINUE command and return to program
mode, the processor grants an interrupt at IPL 14. The processor must be
executing below the requested IPL for the interrupt to take effect.
3.1.3.7

IPL 22 or IPL 24 {Interval Clock IPLs)
Every 10 milliseconds, the interval clock interrupts at IPL 22 or 24,
depending upon the VAX system. A system cell points to the IPL field
(SPL$B_IPL) in the HWCLK spin lock, identifying the IPL at which the
processor's interval clock interrupts.

The interval clock's interrupt service routine performs the functions
described in Section 3.1.3.3. Note that the interval clock's interrupt service
routine obtains the HWCLK spin lock to synchronize its operations on the
system time quadword (EXE$GQ_SYSTIME) and the quadword containing
the due time of the first timer queue element (EXE$GQ_1ST_TIME).

3.1.4

Modifying IPL in Driver Code
Kernel-mode code can modify the IPL of the local processor by either
explicitly setting the processor's IPL to a specific value or by requesting a
software interrupt at a specific level. Driver code can change the IPL at
which it executes by invoking a VMS-supplied macro to request a change
in IPL. Because the DEVICELOCK, FORKLOCK, and LOCK macros
(and their counterparts) raise .(or lower) IPL in a VMS uniprocessing
environment, and achieve full synchronization in a VMS multiprocessing
system, Digital recommends their use instead of the SETIPL, DSBINT,
and ENBINT macros.
Table 3-2 lists the macros that set, store, or restore a processor's IPL.
See the macro chapter of the VMS Device Support Reference Manual for a
further explanation of the functions of these macros and a full description
of their arguments.

3-9

Synchronization of 1/0 Request Processing
3.1 Interrupt Priority Levels

Table 3-2

VMS Macros That Change a Processor IPL

Macro

Function

Raising IPL
DEVICELOCK [lockaddr] [,/ockipl]
{, savipl] {,condition] {,preserve= YES]

Raises IPL on the local processor to the device IPL associated with the
device lock's lockaddr, obtains the device lock, and saves the current IPL
at savipl 1

DSBINT [ip/=31} {,dst=-(SP)]
{,environ=MULTIPROCESSORJ

Raises IPL on the local processor to the specified ipl, saving the current
IPL at dst 2

FORKLOCK [lock] [,lockipl} [,savipl]
[,preserve= YES] [,fipl=NO]

Raises IPL on the local processor to lockipl, obtains the fork lock, and
saves the current IPL at savipl 1

LOCK lockname [,/ockipl] [,savipl]
[,condition] {,preserve= YES]

Raises IPL on the local processor to the lockipl, obtains the lock indicated
by lockname, and saves the current IPL at savipl 1

SETIPL [ip/=31]
{,environ=MULTIPROCESSOR}

Raises IPL on the local processor to the specified ipl 2

Lowering IPL
DEVICEUNLOCK [lockaddr] [,newipl]
[,condition] [,preserve= YES]

Releases or restores the device lock indicated by lockaddr, lowering the
local processor's IPL to newipl, thus permitting interrupts to occur at or
beneath the current IPL1

ENBINT [src=(SP+)]

Lowers the local processor's IPL to src, thus permitting interrupts to occur
at or beneath the current IPL2

FORKUNLOCK [lock] [,newipl]
[,condition] [,preserve= YES]

Releases or restores the fork lock indicated by lock, lowering the local
processor's IPL to newipl, thus permitting interrupts to occur at or beneath
the current IPL1

UNLOCK lockname [,newipl]
{,condition] [,preserve= YES]

Releases or restores the spin lock indicated by lockname and lowers IPL
to newipl, thus permitting interrupts to occur at or beneath the current IPL1

Miscellaneous Functions
SAVIPL [dst=-(SP)]

Saves the local processor's IPL at the specified location

SOFTINT ipl

Requests a software interrupt on the local processor at the specified ipl

When used in a uniprocessing environment, the DEVICELOCK, DEVICEUNLOCK, FORKLOCK, FORKUNLOCK, LOCK, and
UNLOCK macros generate only the code that manipulates IPL.
2
Use of the SETIPL, ENBINT, and DSBINT macros is not sufficient to guarantee systemwide synchronization of events and
data in a VMS multiprocessing system. The DEVICELOCK, FORKLOCK, and LOCK macros have been designed to achieve
appropriate synchronization in either a uniprocessing or multiprocessing environment.

3.1.4.1

3-10

Raising IPL
To block certain activities on a local processor in a VAX system, it is
sometimes useful to raise IPL explicitly. Driver code should not raise IPL
for more than a few instructions, for doing so prevents the local processor
from servicing interrupts at the current IPL and all lower IPLs.

Synchronization of 1/0 Request Processing
3.1 Interrupt Priority Levels

In a uniprocessor environment, raising IPL provides sufficient systemwide
synchronization to both block events and also protects data customarily
accessed at a given IPL. Drivers typically raise a processor's IPL to check
for a local processor power failure, to send a message to a mailbox, or to
access device registers. For instance, a driver running exclusively in a
VMS uniprocessor environment can set IPL to its device IPL (UCB$B_
DIPL) to access device registers. While the driver executes at device IPL,
no other code thread can execute at the same device IPL and thereby read
or write the same device registers. (See Section 3.1.4.2 for a description of
the rules for lowering IPL that enforce the synchronization.) VMS supplies
the SETIPL and DSBINT macros to effect the change in IPL.
In a multiprocessing environment, as in a uniprocessing environment, a
driver can block activities on the local processor by raising IPL. However,
in a multiprocessing environment, simply raising IPL is not sufficient to
protect shared data structures from other processors that may attempt
to access them concurrently. To achieve synchronization in a VMS
multiprocessing system, VMS associates a series of semaphores, called
spin locks, with such shared databases. (See Section 3.2 for a further
discussion of spin locks.)
A processor that must access a shared structure must first secure a
corresponding spin lock. The acquisition of a spin lock often involves the
raising of IPL to the IPL associated with the spin lock and the database it
protects. Spin lock acquisition code can elevate IPL automatically if called
from a code thread executing at an IPL lower than the synchronization
IPL of the lock. A processor that has properly obtained a spin lock can
thus proceed to access the associated database at the appropriate IPL. If
necessary, it is free to further raise IPL, but should not lower IPL below
the spin lock's allocation IPL without first releasing the spin lock.
For example, a driver running in a VMS multiprocessing system can
set IPL to IPL$_POWER to block the servicing of a power failure on the
local processor. However, while executing at IPL$_POWER (or at device
IPL), the driver cannot safely access device registers unless it has first
secured the spin lock associated with the device; that is, its device lock.
Similarly, a driver's fork process, although it executes at a fork IPL with
a corresponding fork lock held, may raise a processor's IPL by obtaining
an additional spin lock. Sending a message to the OPCOM (operators
communication process) mailbox (obtaining the MAILBOX spin lock at
IPL 11) and accessing device registers (obtaining the appropriate device
lock at device IPL) are two such activities.
The LOCK, FORKLOCK, and DEVICELOCK macros ensure that the
synchronization needed for either the uniprocessor or multiprocessor
environment is obtained before the requested resource is accessed.
When executed in a uniprocessor environment, these macros only obtain
the proper IPL synchronization. When invoked in a multiprocessing
environment, these macros both raise IPL and obtain an appropriate spin
lock, thus extending IPL synchronization systemwide.

3-11

Synchronization of 1/0 Request Processing
3.1 Interrupt Priority Levels

3.1.4.2

Lowering IPL
Driver code lowers its IPL to synchronize with code threads that access
common data or perform common activities at the lower IPL. In a
multiprocessing environment, lowering IPL is often associated with the
release of a spin lock. In addition, lowering IPL may be necessary in order
to obtain a spin lock synchronized at the lower IPL.

One of the most fundamental coding rules in VMS is that a code thread
cannot explicitly lower IPL below the level at which its execution has been
initiated. In relation to driver processing, this means that a driver fork
process cannot explicitly set IPL to be less than its fork IPL, nor can a
driver's interrupt service routine explicitly set IPL to be less than device
IPL. This is because a processor interrupted a lower IPL code thread
in mid-execution to place the current code thread into execution. It is
important to the integrity of the data structures protected at this lower
IPL that the previous code thread be resumed before other code accesses
the same structures. A violation of the IPL rule would undermine the
VMS interrupt dispatching mechanism by not first returning control to the
interrupted code thread.
Driver code uses the following methods to lower IPL:
•

Issuing a DEVICEUNLOCK, FORKUNLOCK, or UNLOCK macro
(paired with an earlier invocation of a DEVICELOCK, FORKLOCK, or
LOCK macro) or a ENBINT macro (paired with an earlier invocation
of an DSBINT macro) to restore IPL to a previously saved value.

•

Invoking the IOFORK (or FORK) macro to preserve its context in
a fork block, to insert the block in a fork queue, and to request a
software interrupt at the driver's fork IPL. See Section 3.3.3.1 for a
complete discussion of forking.

•

Issuing an REI instruction at the end of its interrupt service routine
that dismisses the interrupt.

Lowering IPL can cause many pending interrupts on the local processor
between the old and new IPLs to become deliverable.

3.2

Spin Locks
In a multiprocessing environment, as in a uniprocessing environment, you
can block activities on the local processor by raising IPL. Similarly, certain
shared databases must be accessed only at a given IPL. However, in a
multiprocessing environment, simply raising IPL on the local processor
does not prevent other processors in the system from reading or modifying
a shared database. Unless other steps are taken to notify the other
processors that the database is "owned," such contention could potentially
result in corrupted data and system failures.
A spin lock is a semaphore associated with a set of system structures,
fields, or registers whose integrity is critical to the performance of
a specific operating system task. The scheduler and the memory
management subsystem thus have their own spin locks, as does each
fork processing level and each device controller. Because a spin lock can
be owned by only one processor in the system at a time, other processors
3-12

Synchronization of 1/0 Request Processing
3.2 Spin Locks

attempting to acquire the same spin lock are prevented from reading
from or writing into the database it protects. Refer to the data structures
contained in VMS Device Support Reference Manual for an illustration of
the spin lock (SPL) structure and a description of its contents.
There are two categories of spin lock:
•

The structure of a static spin lock is permanently assembled into
the system. As a result, its existence and definition are fixed from one
system to another. Static spin locks are accessed as indexes into a
vector of longword addresses called the spin lock vector and pointed
to by SMP$AR_SPNLKVEC. The system spin locks and fork locks
listed in Table 3-3 are static spin locks.

•

A dynamic spin lock is a spin lock that is created based on the 1/0
configuration of a particular system. One such dynamic spin lock is
the device lock SYSGEN creates when configuring a particular device.
This device lock synchronizes access to the device's registers and
certain unit control block (UCB) fields. VMS creates a dynamic spin
lock by allocating space from nonpaged pool, rather than by assembling
the lock into the system as it does in the creation of a static spin lock.
Section 3.2.2 describes device locks.

Table 3-3 lists, in order of increasing logical rank, the static spin locks.
For each system spin lock or fork lock, the table records its index into
the spin lock vector, its synchronization IPL, and a brief description of its
function.
Table 3-3 Static Spin Locks
Lock Name

Lock Index

Synchronization IPL

Description

QUEUEAST

SPL$C_QUEUEAST

6 (IPL$_QUEUEAST)

Fork lock for executing a fork process at
IPL 6

FILS VS

SPL$C_FILSYS

8 (IPL$_FILSYS) 1

Lock on file system structures

scs2

IOLOCK8

SPL$C_IOLOCK8
SPL$C_SCS

8 (IPL$_10LOCK8
IPL$_SCS) 1

Fork lock for executing a fork process at
IPL 8

PR_LK8

SPL$C_PR_LK8

8 (IPL$_10LOCK8) 1

Primary CPU's private lock for IPL 8

TIMER

SPL$C_TIMER

8 (IPL$_TIMER)

JIB

SPL$C_JIB

8 (IPL$_JIB) 1

Lock for adding and deleting timer queue
entries and searching the timer queue3
Lock for manipulating job nonpaged pool
quotas as reflected by the fields JIB$L_
BYTCNT and JIB$L_BYTLM in the job
information block

1
IPL$_TIMER, IPL$_SCHED, IPL$_SCS, IPL$_JIB, IPL$_MMG, IPL$_FILSYS, and IPL$_10LOCK8 are all synonyms for
IPL$_SYNCH.

2 These names refer to the same spin lock.
3

The HWCLK spin lock implicitly locks the timer queue element at the head of the timer queue by locking the quadword
representing its due time (EXE$GQ_1ST_TIME).
(continued on next page)

3-13

Synchronization of 1/0 Request Processing
3.2 Spin Locks

Table 3-3 (Cont.)

Static Spin Locks

Lock Name

Lock Index

Synchronization IPL

Description

MMG

SPL$C_MMG

8 (IPL$_MMG) 1

Lock on VMS memory management,
PFN database, swapper, modified page
writer, and creation of per-CPU database
structures

SCH ED

SPL$C_SCHED

8 (IPL$_SCH ED) 1

Lock on process control blocks, scheduler
database, and mutex acquisition and
release structures

IOLOCK9

SPL$C_IOLOCK9

9 (IPL$_10LOCK9)

Fork lock for executing a fork process at
IPL 9

PR_LK9

SPL$C_PR_LK9

9 (IPL$_10LOCK9)

Primary CPU's private lock for IPL 9

IOLOCK10

SPL$C_IOLOCK10

10 (IPL$_10LOCK10)

Fork lock for executing a fork process at
IPL 10

PR_LK10

SPL$C_PR_LK10

10 (IPL$_10LOCK10)

Primary CPU's private lock for IPL 10

IOLOCK11

SPL$C_IOLOCK11

11 (IPL$_10LOCK11)

Fork lock for executing a fork process at
IPL 11

PR_LK11

SPL$C_PR_LK11

11 (IPL$_10LOCK11)

Primary CPU's private lock for IPL 11

MAILBOX

SPL$C_MAILBOX

11 (IPL$_MAILBOX)

Lock for sending messages to mailboxes

POOL

SPL$C_POOL

11 (IPL$_POOL)

Lock on nonpaged pool database

PERFMON

SPL$C_PERFMON

15 (IPL$_PERFMON)
4

Lock for 1/0 performance monitoring

INVALIDATE

SPL$C_INVALIDATE

IPL$_1NVALIDATE

Lock system space translation buffer (TB)
invalidation

VIRTCONS

SPL$C_VIRTCONS

IPL$_VIRTCONS 5

Lock for ownership of the virtual console

HWCLK

SPL$C_HWCLK

22 or 24

Lock on interval clock database, including
the quadword containing the due time
of the first timer queue element and the
quadword containing the system time

MEGA

SPL$C_MEGA

31 (IPL$_MEGA)

Lock for serializing access to fork and wait
queue

MCHECK2
EMB 2

SPL$C_MCHECK
SPL$_EMB

31 (IPL$_MCHECK
IPL$_EMB)

Lock for synchronizing certain machine
error handling and for allocating and
releasing error logging buffers

1
IPL$_TIMER, IPL$_SCHED, IPL$_SCS, IPL$_JIB, IPL$_MMG, IPL$_FILSYS, and IPL$_10LOCK8 are all synonyms for
IPL$_SYNCH.
2 These names refer to the same spin lock.

The IPL associated with this spin lock is determined at system initialization and is one less than that of the system's
interprocessor interrupt. On VAX 88x0 and VAX 83x0 systems, the value is 19. On VAX 6000-series and VAX 9000-series
systems, the value is 21.

5 The IPL associated with this spin lock is determined at system initialization and is the level of the system's interprocessor

interrupt. On VAX 6000-series and VAX 9000-series systems, the value is 22; on other VAX multiprocessing systems, the value
is 20.

Drivers rarely need to obtain system spin locks or fork locks explicitly;
the VMS routines that initiate driver processing and access resources
protected by a spin lock generally obtain and release these locks as
required. However, a driver must obtain the appropriate device locks

3-14

Synchronization of 1/0 Request Processing
3.2 Spin Locks

whenever it must access data synchronized at device IPL; for instance, in
its interrupt service routine.
VMS provides a set of macros, listed in Table 3-2 and described in full in
the macro chapter of the VMS Device Support Reference Manual, that call
the system's spin lock acquisition and releasing routines.
Three factors control the successful acquisition of a spin lock: IPL, rank,
and ownership.
IPL

The processor must be executing at an IPL equal to or below the spin lock's
synchronization IPL (SPL$B_IPL). In keeping with the rules discussed in
Section 3.1.4.2, a processor should not lower the IPL of its thread of
execution in the process of acquiring a spin lock. Thus, in acquiring a spin
lock, a processor may or may not raise its IPL, depending upon whether
it is executing already at the spin lock synchronization IPL. VMS supplies
spin lock acquisition macros (DEVICELOCK, FORKLOCK, and LOCK)
that, in calling appropriate VMS routines, raise IPL automatically in the
course of obtaining the requested spin lock. Once it owns the spin lock,
the processor can raise its IPL above the IPL at which the spin lock was
acquired, but it should not lower it below that level.

Rank
A processor can own multiple spin locks simultaneously, but must obtain
these spin locks in increasing order of rank. (Table 3-3 lists the spin locks
in order of rank.) In other words, a processor that owns one or more spin
locks should not attempt to acquire a spin lock whose logical rank 4 is less
than a spin lock it already holds. It does not need to acquire all spin locks
of intervening rank. This rule is meant to avoid potential deadlocks in
the acquisition of system spin locks and fork locks, and does not pertain
to device locks. The processor may release spin locks in any order, as long
as any attempt to reacquire those spin locks acquires them in ascending
order.
Note that the concept of rank is independent of IPL. At any given
synchronization IPL, there may be many spin locks, each of which is
ranked according to its position in Table 3-3.
Ownership
The spin lock must not be owned by any other processor. If the spin lock is
currently owned by another processor, a requesting processor spin waits
for the lock to become available. That is, it executes in a loop, waiting for
the processor that owns the spin lock to release it. If a spin lock is owned,
its owner field (SPL$L_OWN_CPU) contains an identifier that indicates
which processor in the multiprocessor system owns the spin lock.
It is legal for a processor to nest acquisitions of a given spin lock. In other
words, if a processor attempts to acquire a spin lock that it currently owns,
the acquisition will succeed. VMS provides a mechanism whereby such a
processor can release a single acquisition or all acquisitions of a spin lock.
4

The physical rank of a spin lock is the inverse of its logical rank. See the description of the SPL$B_RANK
field in the VMS Device Support Reference Manual for additional information.

3-15

Synchronization of 1/0 Request Processing
3.2 Spin Locks

3.2.1

Fork Locks
In its simplest form, a fork lock is a static spin lock that synchronizes
the right of a fork process to execute at a specified IPL in a VMS
multiprocessing system. Fork locks exist for each of the fork IPLs from
IPL 8 to 11. A driver indicates the fork lock under which it processes, and
by implication its fork IPL, by specifying a fork lock index in its driver
prologue table (using the DPT_STORE macro as described in Section 6.1).
Those code threads that must synchronize with another fork thread use
the same fork lock. For instance, the fork processes of drivers whose
devices share the resources of a common adapter must synchronize
themselves by means of a common fork lock. These code threads fork
not necessarily to lower IPL, but rather to wait for the availability of a
common resource such as a controller data channel or map registers (see
Section 3.4). The VMS routines that acquire and release these resources
ensure that the fork lock is acquired and released as necessary.
Drivers rarely need to obtain a fork lock explicitly. VMS places the
driver fork process into execution (originally by EXE$INSIOQ and, by
implication, by IOC$REQCOM) at fork IPL holding the appropriate fork
lock. In addition, the fork dispatcher obtains the fork lock associated
with the driver fork process before it restores its context and resumes its
execution. (Section 3.3.3 describes these concepts in greater detail.)
Note that, if a driver fork process is not placed into execution by one of
these means, it must itself expressly obtain the fork lock.
As an example, consider a driver fork process activated by a timer wakeup
associated with a timer queue element (TQE) previously queued by the
driver. The software timer interrupt service routine does raise IPL to IPL
8 (IPL$_SYNCH) and obtain certain spin locks prior to dequeuing the TQE
and placing it into execution, but it does not obtain the driver's fork lock.
Thus, even though the driver's fork IPL may be IPL$_SYNCH, the driver
will not be properly synchronized at fork level unless it first obtains the
appropriate fork lock.

3.2.2

Device Locks
A device lock represents a lock on an individual adapter or controller.
A processor executing a code thread that accesses a device's registers or
certain fields in its unit control block (UCB) that reflect its status does so
while holding the corresponding device lock.
UCBs are protected by a device lock common to all units on the same
adapter or common to the entire system, depending upon the type of
device. A device lock is dynamically created by the System Generation
Utility (SYSGEN) when it creates a channel request block (CRB). SYSGEN
stores the address of the device lock in the CRB (CRB$L_DLCK) and later
copies it to the unit control block (UCB$L_DLCK) as a UCB is created for
each unit on the controller.

3-16

Synchronization of 1/0 Request Processing
3.2 Spin Locks

The acquisition of device locks is exempt from the spin lock rank rule.
As long as the processor does not violate IPL synchronization, it may
successfully obtain an unowned device lock while holding any system spin
lock and, likewise, may successfully obtain unowned system spin locks
while holding a device lock. However, a processor can acquire only one
device lock at a given IPL.

3.3

Device Driver Synchronization
This section describes how VMS and driver processing maintain
synchronization during the processing of a general 1/0 request. It later
focuses on the specific strategies drivers employ to synchronize at the
device and fork levels.

3.3.1

Overview of the Synchronization of an 1/0 Operation
Figure 3-1 diagrams the general flow of the processing of a single 1/0
request, as synchronization is achieved by raising and lowering IPL, and,
in a multiprocessing environment, by also obtaining and releasing the
necessary spin locks.

3-17

Synchronization of 1/0 Request Processing
3.3 Device Driver Synchronization

Figure 3-1

Synchronizing 1/0 Request Processing

8
Check for
power failure;
start device.

......

•

IPL$ POWER

Save driver
context;
release
device lock;
wait for
interrupt.

e
Obtain
device lock.

Device IPL

e
Obtain fork lock;
modify and
read UCB:;
release fork lock.

Fork IPL

Start-1/0
routine.

I+-FDT
Routine

Obtain fork lock;
call driver's
start-1/0
routine.

Release
fork lock.

l
l

_I_

$010
System
Service

f-+

FDT
Routine

IPL$_ASTDEL

0
User
issues
QIO.

User
process
resumes.

IPLO
ZK-6534-GE

Figure 3-1 illustrates the following events:

0 The user program, executing at IPL 0, issues a $QIO system service
call.

8 The $QIO system service raises IPL to IPL$_ASTDEL to prepare the
I/O request according to the arguments included in the call.
3-18

Synchronization of 1/0 Request Processing
3.3 Device Driver Synchronization

0 The driver's FDT routines execute, mainly at IPL$_ASTDEL.
Note that during IPL 0 processing and FDT routine activity at IPL$_
ASTDEL, the process requesting the 1/0 is susceptible to being
rescheduled. In a multiprocessing environment, such an event could
cause 1/0 processing to resume on a different processor from that on
which it was started.

In certain rare circumstances, an FDT routine must read or modify
the device's UCB. Because most fields in the UCB may be shared by
fork processes running systemwide it is important that, if the FDT
routine must use them, it issue the FORKLOCK macro to obtain
the appropriate fork lock and raise to fork IPL. (When finished, it
relinquishes this synchronization by issuing the FORKUNLOCK
macro.)

0 The continuation of VMS preprocessing of the 1/0 request-or the
completion of a previous 1/0 request on the device unit--ensures that
the driver's start-1/0 routine is placed into execution at fork IPL and,
in a multiprocessing system, holding the corresponding fork lock. The
start-1/0 routine accesses various UCB fields and contends for adapter
resources synchronized systemwide by the fork lock.

0 Once it has further prepared the 1/0 request and obtained the required
resources, it generally must access device registers. Device registers
and those UCB fields that record their status are synchronized at
device IPL. A processor in a VMS multiprocessing system must hold
the appropriate device lock to access the device database.

While executing a critical code sequence, such as those instructions
that start a device, the start-1/0 routine raises the IPL of the local
processor to IPL$_POWER to check for a processor power failure. In a
VMS multiprocessing environment, the executing processor retains the
device lock during this sequence.

0 After it activates the device, the start-110 routine calls a VMS routine
that saves the driver's context in the UCB fork block, suspends driver
processing, releases the device lock, if held, and restores IPL to a
previous level.

tD VMS at this point returns control to the code that initiated the fork
thread where, in a VMS multiprocessing system, the fork lock is
released.

G After VMS services interrupts at intervening IPLs, the user process
resumes.
Figure 3-2 illustrates the synchronization involved in the completion of an
1/0 request from the point of the device interrupt to the delivery of ASTs to
the user program. There is little linear flow involved in the completion of
an 1/0 request. The servicing of interrupts, represented by jagged lines in
the figure, the requesting of software interrupts, and the REI instruction
contribute to the flow that completes an 1/0 request.

3-19

Synchronization of 1/0 Request Processing
3.3 Device Driver Synchronization

Figure 3-2

Synchronizing 1/0 Request Completion

8,9

Interrupt service
routine obtains
device lock; services
device, releases
device lock; REI.

Driver resumes,
places context
in fork block;
ID fork;
REI.

Device IPL

G
Fork dispatcher
obtains fork lock.
Resumes driver
fork process.

Driver writes status
into UCB; invokes
REQCOM macro;
requests interrupt
at IPL$_10POST.

8 IOPOST obtains
SCHED SPINLOCK;
queues special kernel
mode AST to process;
releases SCHED
SPINLOCK.
~

Fork IPL

80
'
L

Postprocess
1/0 request;
REI.

I.a.

i-.

ILP$_10POST

9
Deliver AST
to process;
REI.

z
IPL$_ASTDEL

e
L

Deliver user
AST to
process;
execution
resumes.

IPLO
ZK-6535-GE

Figure 3-2 illustrates the following events:

0 A device interrupt in the range of IPL 20 to IPL 23 triggers the
execution of the driver's interrupt service routine. The interrupt
service routine locates the device unit's UCB and, in a VMS
multiprocessing system, immediately obtains the appropriate device
lock. After it analyzes the interrupt and determines that it is expected,
3-20

Synchronization of 1/0 Request Processing
3.3 Device Driver Synchronization

it reactivates the driver, still at device IPL and holding any acquired
device lock.

8 The driver briefly examines and/or saves the contents of the device's
registers, but, in order to permit other device interrupts to be serviced
and to allow other high priority system tasks to proceed, it lowers
its own priority. The driver accomplishes this by requesting VMS to
save some driver context in the UCB fork block and place it into one
of the processor-specific fork queues at IPLs 8 to 11 serviced by the
fork dispatcher. When it does so, VMS returns control to the driver's
interrupt service routine.

0 The interrupt service routine releases any acquired device lock and
issues an REI instruction to dismiss the device interrupt.

8 When IPL drops below the driver's fork IPL, the fork dispatcher
restores the context of the driver and resumes its execution. In a VMS
multiprocessing system, the fork dispatcher obtains the necessary fork
lock prior to placing the driver into execution.

0 Still synchronized at fork level, the driver fork process analyzes the
success of the 1/0 operation and writes status into RO and Rl. VMS
then inserts the IRP in the systemwide 1/0 postprocessing queue,
requests a software interrupt at IPL$_IOPOST, and starts any 1/0
request that may be waiting for the device. Eventually, VMS returns
to the fork dispatcher and, if no other fork processes are queued for
that IPL, issues an REI instruction to dismiss the software interrupt.

8 When the processor's IPL falls below IPL$_IOPOST, the 1/0
postprocessing routine removes the IRP from the 1/0 postprocessing
queue, adjusts process quota usage, and deallocates system buffers for
write functions.

8 When the routine finishes processing the IRP, it queues a special
kernel-mode AST to the process that issued the original $QIO request.
To accomplish this, it obtains the SCHED spin lock (raising to IPL$_
SYNCH in the process) and calls another VMS routine that queues the
AST to the process's PCB. It then releases the SCHED spin lock.

8 The 1/0 postprocessing routine continues execution at IPL$_IOPOST
until it has serviced all entries in the postprocessing queue. It then
issues an REI instruction to dismiss this software interrupt.

0 The special kernel-mode AST routine executes at IPL$_ASTDEL. It
completes the transfer of the results and status of the 1/0 request to
the user process.

I> The special kernel-mode AST routine can queue a user-mode AST
routine to the user process. When the user process has been
rescheduled and its context reloaded, the user-mode AST routine
executes at IPL 0.

3-21

Synchronization of 1/0 Request Processing
3.3 Device Driver Synchronization

3.3.2

Synchronizing the Device Database
A device database ordinarily consists of the device or adapter registers,
plus some storage in the UCB (or in another data structure) that
reflects the status of the device. Routines that access data in the device
database must do so at device IPL (UCB$B_DIPL) in order to maintain
synchronization. Generally, only three driver routines contend for access
to the device database.
•

Interrupt service routine

•

Start-110 routine when loading or reading device registers

•

Timeout handling routine

In a VMS uniprocessing environment, the start-1/0 routine raises its IPL
to device IPL using the DSBINT macro. VMS calls the driver's timeout
handling routine at device IPL. Because the interrupt dispatcher invokes
it at device IPL, the driver's interrupt service routine does not need to
acquire additional synchronization.
In a VMS multiprocessing environment, these routines must also hold
the appropriate device lock (UCB$L_DLCK). The device lock protecting
the device database is a dynamic spin lock, created by SYSGEN when the
device is configured and its channel request block (CRB) is created. The
address of the device lock is first stored in CRB$L_DLCK and is moved
to UCB$L_DLCK as corresponding UCBs are allocated for each unit on
the controller. VMS calls the driver's timeout handling routine at device
IPL with the device lock held. The start-1/0 routine and the interrupt
service routine must explicitly obtain such synchronization by invoking the
DEVICELOCK macro.
The start-1/0 routine and timeout handling routine are additionally
synchronized at driver fork level. VMS raises IPL to fork level and obtains
the corresponding fork lock before transferring control to them. This is
not the case, however, with a driver's interrupt service routine. A device's
interrupt service routine usually does not hold the fork lock. However,
it may have preempted a thread holding the fork lock, or a fork thread
may be running in parallel on another processor. Therefore, an interrupt
service routine must not change any fields in the UCB that are protected
by the fork lock. To access these fields, an interrupt service routine must
fork, as described in Section 3.3.3.1.

3.3.3

Synchronizing at Driver Fork Level
A large part of driver code executes in the context of a fork process.
As a fork process, driver code that must access data in its fork database
does so at a single, specific fork IPL (from IPL 8 to IPL 11) and-in a
VMS multiprocessing environment-holding a single, specific fork lock
(see Section 3.2.1 ). The fork database consists of those fields in the unit
control block (UCB) not explicitly synchronized at device level and such
adapter or controller resources as map registers or data paths.

3-22

Synchronization of 1/0 Request Processing
3.3 Device Driver Synchronization

The system routine EXE$INSIOQ initially creates a driver fork process
as it attempts to deliver a preprocessed 110 request to the driver's startI/O routine. If the device unit is busy (that is, a fork process is already
active servicing a prior request for that device), EXE$INSIOQ inserts
the IRP into the UCB's pending-110 queue. If the device unit is not busy,
EXE$INSIOQ calls IOC$INITIATE to transfer control to the driver's start110 routine. The start-110 routine begins to execute at fork IPL holding
the associated fork lock, if necessary.
When the driver fork process later calls IOC$REQCOM to complete
processing of a prior 110 request, IOC$REQCOM executes within the
driver fork process, dequeues the next IRP on the pending-110 queue, and
begins processing it.
Like other processes, fork processes can be interrupted or suspended.
The local processor interrupts a fork process when the processor receives
a request for an interrupt at a higher priority level. To minimize the
number of interruptions, fork processes sometimes execute at raised IPLs,
and even raise their IPL to block all other interrupts, if necessary.
VMS stalls a driver's fork process when the process requests an
unavailable resource such as a controller's data path (see Section 3.4).
When suspended, a driver fork process, like other processes, preserves
some context information. As VMS preserves some of the context of a
normal process in its hardware PCB, so it preserves a driver fork process's
context-however abbreviated-in a fork block. Fork context consists of
the following:
•

Two general purpose registers (R3 and R4)

•

The program counter (PC)

•

A fork block (usually the UCB), the address of which is in R5 at the
time of the suspension

Minimal context helps ensure that, when a driver fork process is ready to
be resumed, the resulting context-switching occurs swiftly.
3.3.3.1

Forking and the VMS Fork Dispatcher
Forking allows high IPL code to do the following:

•

Continue executing a particular code thread at a lower IPL than the
IPL at which the code thread was initiated

•

Synchronize with other code executing at the lower IPL

Usually, a driver forks after servicing a device interrupt at an IPL from
20 to 23. By forking, the driver lowers the IPL at which it continues to
process the device interrupt from device IPL to fork IPL (8 to 11). Forking
not only allows the driver to process efficiently that part of interrupt
request processing that is not time critical, but it allows the driver to
synchronize its execution with other fork process code threads initiating
110. For example, forking helps the driver synchronize its use of a device
unit's UCB with other code threads interested in the structure. Moreover,
the driver, by forking after completing the initial servicing of a device
interrupt, allows other device interrupts to occur at that device IPL.
3-23

Synchronization of 1/0 Request Processing
3.3 Device Driver Synchronization

To fork, either the driver's interrupt service routine or the start-110
routine, when resumed by the interrupt service routine, invokes the VMS
macro IOFORK. The IOFORK macro saves fork process context in the
UCB fork block, places the fork block in the local processor's fork queue for
the specific fork IPL, and requests a software interrupt for that IPL. When
that interrupt is ultimately serviced, driver fork processing resumes at the
lower level.
There are other specialized instances in which a device driver may fork.
As discussed in Section 11.1.5, the driver's unit initialization routine
or controller initialization routine, while executing at IPL 31, may fork
in order to permanently allocate controller resources, system nonpaged
dynamic memory, or system page-table entries. To fork, these routines use
the VMS macro FORK. The FORK macro allows a driver to fork, utilizing
the fork block, the address of which is placed in R5. Because the channel
request block (CRB) is available to these routines and contains a fork
block, they invoke the VMS macro FORK with the address of the CRB in
R5.
One interrupt service routine (EXE$FORKDSPTH) handles all forkprocess dispatching on each processor in a VAX system. When the
processor grants an interrupt at fork IPL, the fork dispatcher saves RO
to R5 on the stack and processes the local fork queue that corresponds to
the IPL of the interrupt. To do so, it removes an entry from the fork queue,
restores the fork process context from the fork block, obtains ownership of
the fork lock specified in the fork block (in a VMS multiprocessing system),
and reactivates the suspended fork process.
When that fork process is completed, the dispatcher releases the fork lock
and examines the fork queue. If an entry exists on the queue, the fork
dispatcher removes it, restores the context of the fork process, secures the
fork lock specified in the fork block, and reactivates the fork process. This
sequence is repeated until the fork queue is empty. When the queue is
empty, the fork dispatcher restores RO to R5 from the stack and dismisses
the interrupt with an REI instruction.
Figure 3-3 illustrates the fork queue structure.
3.3.3.2

3-24

Restrictions on Fork Processes
A driver fork process executes under the following constraints:

•

It should not attempt to refer to the address space of the process
initiating the I/O request.

•

It can use only RO to R5 freely; it must save other registers before use
and restore them after use. Use of registers other than RO to R5 is
strongly discouraged.

•

It must clean up the stack after use; the stack must be in its original
state when the fork process relinquishes control to any VMS routine.

•

It must execute at IPLs between the driver's fork IPL and IPL$_
POWER. It must not lower IPL below the driver's fork IPL except by
creating a fork process to execute at a lower IPL.

Synchronization of 1/0 Request Processing
3.3 Device Driver Synchronization

Figure 3-3

Processor-Specific Fork Queue Structure

IPL 11
Fork Queue
List Head

Fork
Block

IPL 10
Fork Queue
List Head

IPL 11

CPU$Q_SWIQFL [40]

IPL 10

CPU$Q_SWIQFL [32]

IPL9

CPU$Q_SWIQFL [24]

IPL8

CPU$Q_SWIQFL [16]

IPL9
Fork Queue
List Head

CPU$Q_SWIQFL [O]

IPL8
Fork Queue
List Head

Fork
Block

IPL6
Fork Queue
List Head

Fork
Block

IPL 7
IPL6

ZK-0584-GE

•

If executing in a VMS multiprocessing environment, it cannot attempt

to obtain system spin locks with lower ranks than that ·of its fork lock.
•

3.4

When it returns control to the fork dispatcher, the fork process must
be at the same fork IPL and, if executing on a VMS multiprocessing
system, own the appropriate fork lock.

Resource Wait Queues
The processing of an 1/0 request often requires shared system resources
such as memory and 1/0 adapter map registers. Drivers that depend
on such resources synchronize access to these resources and their
respective resource wait queues by executing at fork IPL and, in a VMS
multiprocessing environment,· obtaining ownership of the associated fork
lock.
The $QIO system service and fork processes call VMS routines to allocate
and deallocate shared system resources. Because the resources are limited,
1/0 processing might be delayed until any such needed. resources are
released. Thus, synchronization of access to these resources can have a
substantial impact on the processing of 1/0 requests.
For example, the $QIO system service calls a VMS routine to allocate
non paged system space for an IRP. If there is insufficient nonpaged pool,
the routine calls another VMS routine to save the process context and
change the process state to resource-wait mode (also called miscellaneous
wait~ or MWAIT). As a result of waiting, the process is a candidate to
3-25

Synchronization of 1/0 Request Processing
3.4 Resource Wait Queues

be swapped out of memory. When nonpaged pool becomes available, the
scheduler reschedules the process.
During fork process execution at elevated IPLs, driver context is very
small. At any point, the driver can obtain all details about an 110 request
by referring to the 1/0 database (see the data structures in VMS Device
Support Reference Manual). The driver needs only the address of the
device's UCB, which is the key to the rest of the database. Therefore,
VMS routines that control driver resources, such as map registers, use
fork blocks and resource-wait queues to save minimal driver context. Each
entry in a queue is a fork block (or UCB) that contains R3, R4, and the
continuation PC of the waiting fork process.
When the awaited resource becomes available, the routine controlling the
resource performs the following steps:
•

Restores the UCB address to R5

•

Restores the saved registers R3 and R4

•

Grants the resource

•

Transfers control to the saved driver return PC address

Because the VMS routine that controls a particular resource stalls any
driver that requests an unavailable resource, drivers are unaware of
execution being suspended and subsequently reactivated. Drivers must
not leave anything on the stack, or in general purpose registers, other than
R3, R4, and R5, when calling a routine that might suspend the driver's
execution.

3.4.1

Competing for a Controller's Data Channel
A controller's data channel is a VMS synchronization mechanism that
guarantees that only one unit of a multiunit controller uses the controller
at one time.
Devices that share a controller, such as disk units, own the controller's
data channel only when a VMS routine assigns the channel to the unit's
fork process. The device driver's start-I/O routine issues the REQPCHAN
macro to obtain the channel.
In contrast, a device unit on a single-unit controller always owns
the controller's data channel. The device driver's controller (or unit)
initialization routine affirms this fact by moving the address of the device's
UCB into IDB$L_OWNER. Generally, the driver's start-110 routine does
not request a single-unit controller.

In each case, the driver's start-110 routine must take steps to synchronize
its access to device registers with any access of these registers by the
driver's interrupt service routine. The routine does so by issuing the
DEVICELOCK macro (as described in Section 3.1.4). The DEVICELOCK
macro raises IPL to device IPL and, in a VMS multiprocessing system,
obtains the device lock associated with the controller.

3-26

Synchronization of 1/0 Request Processing
3.4 Resource Wait Queues

An RK611 controller, for example, controls as many as eight RK06/RK07
devices. The disk driver's fork process must gain control of the controller's
data channel before starting an 110 operation on the unit associated with
the fork process. The disk driver's start-110 routine uses the following
sequence to start a seek operation on an RK07 device:
1

The start-110 routine requests the controller's data channel by
invoking a VMS channel arbitration macro (REQPCHAN).

The VMS routine tests the CRB mask field to determine whether the
controller's data channel is available.

If the channel is available, the VMS routine allocates the channel to

the fork process and returns the address of the device's CSR to the
fork process.
If the channel is busy, the VMS routine saves the driver fork context
in the UCB fork block and inserts the fork block address in the
controller's channel wait queue.
4

When the fork process resumes execution, the process owns the
controller channel. The fork process can then obtain the device lock
(raising IPL to device IPL) and modify the device's registers to activate
the device.

The driver's start-110 routine then requests the VMS operating system
to suspend driver processing in anticipation of an interrupt or timeout
and to release the channel.

The VMS channel-releasing routine assigns channel ownership to the
next fork process in the channel wait queue, loads the CSR address
into a general register, and reactivates the suspended fork process.

The reactivated fork process continues execution as though the channel
had been available in the first place.

The VMS channel-arbitration routines keep track of controller availability
using a flag field in the CRB. The fork process must always request and
release the controller's data channel by invoking these routines.

3-27

Overview of 1/0 Processing

Under the VMS operating system, l/O processing occurs in three major
phases:
•

1/0 request preprocessing

•

Device activation and subsequent handling of the device interrupt

•

I/O postprocessing

When a user process issues an 1/0 request, the Queue 1/0 Request ($QIO)
system service gains control and coordinates preprocessing of the request.
The last driver FDT routine called by the $QIO system service calls a VMS
routine that creates a driver fork process to execute the driver's start-110
routine. This routine activates the device.
When the transfer is completed, the device requests an interrupt that
results in execution of the driver's interrupt service routine. This routine
handles the interrupt and requests resumption of the driver fork process
to perform device-dependent I/O postprocessing. The driver fork process
finally transfers control to the system to perform device-independent I/O
postprocessing. Figure 4-1 illustrates the sequence of events.
The $QIO system service is dispatched by means of a corresponding
system service vector in process Pl space. This vector contains a CHMK
instruction that causes an exception that alters the process's access mode
to kernel and dispatches to the service-specific procedure, EXE$QIO.
For the purposes of the discussion in this section, as well as the rest of
the book, Figure 4-2 portrays the flow of an l/O request from its system
service entry point to its servicing by VMS executive routines and driver
code. Discussion of other entry points appears in Chapters 8, 9, and 10.

4-1

Overview of 1/0 Processing

Figure 4-1

Sequence of Driver Execution

User Process Context
User Stack
User Process Context
Kernel Stack

User process issues $QIO.

-------------------~------------------Queue 1/0 request system service
performs device-independent 1/0
preprocessing.

I
Queue 1/0 system service calls driver
FDT routine(s) to perform devicedependent preprocessing.

1
Last FDT routine calls VMS routine to
queue 1/0 request and creates a driver
fork process.
Fork Process Context
Kernel Stack

Once activated the driver fork process
executes the Start 1/0 Routine.

I
Start 1/0 Routine obtains necessary
resources (for example, controller
channel, map registers) and activates
the device.

I
Start 1/0 Routine invokes a wait for
interrupt macro that saves the fork
process context and suspends the
Start 1/0 Routine.
ZK-0918.1-GE

(continued on next page)

4-2

Overview of 1/0 Processing

Figure 4-1 (Cont.)

Sequence of Driver Execution

- - - - - - - - - - - - - - - - Hardware Interrupt Occurs When.__ _ _ _ _ _ _ _ _ _ _ __
Requested by Device
Interrupt Context
Interrupt Stack
Interrupt Dispatcher activates
Interrupt Service Routine.

I
Driver's interrupt service routine
handles the interrupt and transfers
control to the driver at the
instruction following the Wait for
Interrupt invocation.

I
The driver invokes IOFORK to be
rescheduled at fork IPL as a fork process.
ForkP recess Context
Interrupt Stack

Once rescheduled as a fork process,
the driver executes the rest of the
driver code that performs devicedependent 1/0 completion.

I
The driver then calls a VMS routine to perform
device-independent 1/0 completion.

Interrupt Context
Interrupt Stack

User Process Context
Kernel Stack

_t
VMS queues a kernel mode AST to the
process that originally issued the 1/0
request.

Once delivered, the kernel mode AST
routine runs in user process context
to read data into the user's buffer
for a buffered 1/0 request,
return final status, and if requested,
queue a user mode AST and/or set an
event flag.

-----------------------------------------------1-------------------------------------------User Process Context
User Stack

User Mode AST
ZK-0918.2-G E

4-3

Overview of 1/0 Processing
4.1 Preprocessing an 1/0 Request

Figure 4-2

Detailed Sequence of VMS 1/0 Processing

User's
Program
Call

System Service
Vector

Change Mode
Dispatcher

SYS$010::

EXE$CMODKRNL::

$010System
Service
FDT

EXE$010::
(Call)

010

CHMK
RET

FDT

JMP
FDT

SERVICE_EXIT:

RET

JMP
EXE$QIODRVPKT

REI

JSB
RSB

JMP
RET

Driver

EXE$QIORETURN

RSB

IOStart:

IPL$_10POST
Software Interrupt

DRIVER
INTSERV:

WFIKPCH

Device
Interrupt

JSB
IOC$10POST::

RSB

IOFORK*

REI

Queue Special
Kernel AST
REQCOM
REI

FORK DISPATCHER
JMP

To
IOC$1NITIATE

EXE$FORKDSPTH::

----It! ---------------

IOC$REQCOM::
Special Kernel
AST:
- Set event flag.
-WritelOSB.
- Copy data.
- Update quotas.

JSB

Fork IPL
Software
Interrupt

REI

,___JM_P_-4 SOFTINT #IPL$_10POST
If More IRPs
Else

UCB
RSB

*Driver content saved in fork block of UCB.

Fork Block
FR3
FR4*
FPC

ZK-4844-GE

4.1

Preprocessing an 1/0 Request
EXE$QIO performs device-independent preprocessing of an I/O request
and calls driver FDT routines to perform device-dependent preprocessing.
To preprocess an I/O request, EXE$QIO takes the following steps:

4-4

•

Verifies that the requesting process has assigned a process I/O channel
to the target device

•

Locates the device driver in the I/O database

•

Validates the I/O function code

•

Checks process I/O request quotas

•

Validates the I/O status block

Overview of 1/0 Processing
4.1 Preprocessing an 1/0 Request

4.1.1

•

Allocates and sets up the I/O request packet (IRP)

•

Calls driver FDT routines to perform device-dependent preprocessing

Process 1/0 Channel Assignment
The first step in preprocessing an 1/0 request is to verify that the 1/0
request specifies a valid process 1/0 channel. The process I/O channel is
an entry in a system-maintained process table that describes a path of
reference from a process to a peripheral device unit. Before a program
requests I/O to a device, the program identifies the target device unit
by issuing an Assign-1/0-Channel ($ASSIGN) system service call. The
$ASSIGN system service performs the following functions:
•

Locates an unused entry in the table of process 1/0 channels

•

Creates a pointer to the device unit in the table entry for the channel

•

Returns a channel-index number to the program

When the program issues an I/O request, EXE$QIO verifies that the
channel number specified is associated with a device and locates the unit
control block associated with the specified channel using the field CCB$L_
UCB.
Refer to the VMS Device Support Reference Manual data structures for
an illustration of the channel control block (CCB) and a description of its
contents.

4.1.2

Locating a Device Driver in the 1/0 Database
A unit control block (UCB) that describes a device unit exists for each
device in the system. The UCB indicates the current state of the device
unit by recording such information as the following:
•

Whether the device is active (UCB$V_BSY in UCB$L_STS)

•

What 1/0 request is being processed (UCB$L_IRP)

•

Where transfer buffers are located (UCB$L_SVAPTE)

Because drivers run as fork processes and cannot use process address
space to store additional context, drivers use the UCB for temporary data
storage during I/O processing. (Section 6.1 describes how you can allocate
additional UCB space for storing data or device-dependent driver context.)
The UCB also holds the context of a driver fork process when VMS I/O
routines suspend the fork process to wait for an asynchronous event such
as a device interrupt.
Using information in the UCB, a driver can find other 1/0 data structures
associated with the device, including the channel request block, interrupt
dispatch block, and the device data block.
Refer to the VMS Device Support Reference Manual data structures for an
illustration of the UCB and description of its contents.

4-5

Overview of 1/0 Processing
4.1 Preprocessing an 110 Request

4.1.2.1

Channel Request Block

The channel request block (CRB) allows the operating system to manage
the controller data channel. Among its contents are the following:
•

Code that transfers control to a driver's interrupt service routine
(CRB$L_INTD)

•

A pointer to the driver's interrupt service routine (CRB$L_
INTD+VEC$L_ISR)

•

Addresses of a driver's unit and controller initialization routines
(CRB$L_INTD+VEC$L_UNITINIT, CRB$L_INTD+VEC$L_INITIAL)

•

A pointer to the interrupt dispatch block (IDB), which further describes
the controller (CRB$L_INTD+VEC$L_IDB)

Controllers can be either multiunit or dedicated.
All UCBs describing device units attached to a single multiunit
controller contain a pointer to a single CRB (UCB$L_CRB). For these
controllers, a VMS routine uses fields in the CRB (CRB$L_WQFL, CRB$B_
MASK) and IDB (IDB$L_OWNER) to arbitrate pending driver requests for
the controller. When the system grants ownership of a multiunit controller
data channel to a driver fork process, the fork process can initiate an I/O
operation on a device attached to that controller. Figure 4-3 illustrates
the data structures required to describe three devices on a multiunit
controller.
Figure 4-3

Data Structures for Three Devices on One Controller

CAB

UCB

IDB

ZK-0920-GE

4-6

Overview of 110 Processing
4.1 Preprocessing an 1/0 Request

The VMS operating system does not use the CRB to synchronize 1/0
operations for a dedicated controller, as the controller manages but a
single device. Nevertheless, the CRB still is present and is used by drivers
and operating system routines.
Refer to the VMS Device Support Reference Manual data structures for an
illustration of the CRB and a description of its contents.
4.1.2.2

Interrupt Dispatch Block

The CRB contains a pointer to an interrupt dispatch block (IDB) (CRB$L_
INTD+VEC$L_IDB). In tum, the IDB (at IDB$L_UCBLST) points to all
UCBs that share the controller (see Figure 4-3).
The IDB contains the addresses of these three critical data structures:
•

The UCB of the device unit, if any, that currently owns the controller
data channel (IDB$L_OWNER)

•

The control and status register (IDB$L_CSR); it is the key to access to
device registers

•

The adapter control block (IDB$L_ADP) that describes the adapter of
the 1/0 bus to which the controller is attached

Refer to the VMS Device Support Reference Manual data structures for an
illustration of the IDB and a desription of its contents.
Figure 4-4 illustrates the relationship between the data structures that
describe a group of equivalent devices on two separate controllers. In this
figure, one controller has a single device unit, and the other controller has
two device units. Devices on both controllers share the same driver code.

4-7

Overview of 1/0 Processing
4.1 Preprocessing an 1/0 Request

Figure 4-4 1/0 Database for Two Controllers

IDB

CAB

Device
Driver
ZK-1765-GE

4.1.2.3

Device Data Block

All UCBs describing device units attached to a single controller contain
a pointer (UCB$L_DDB) to a single device data block (DDB). The DDB
contains two fields that identify the device and its driver:
•

The generic device/controller name (DDB$T_NAME)

•

The name of the device's driver as obtained from the driver prologue
table (DDB$T_DRVNAME)

Refer to the VMS Device Support Reference Manual data structures for an
illustration of the DDB and description of its contents.

4.1.3

Validating the 1/0 Function
Using the I/O database, EXE$QIO locates the address of the driver's
function decision table by following a chain of pointers that begins in the
UCB of the target device:
UCB ~ DDT ~ FDT
EXE$QIO then uses data in the function decision table to analyze the I/O
function. The procedure confirms that the function specified in the I/O
request is a valid function for the device.
4-8

Overview of 1/0 Processing
4.1 Preprocessing an 1/0 Request

4.1.4

Checking Process 1/0 Request Quotas
EXE$QIO determines whether the I/O request being readied will cause the
process to exceed its quota for outstanding direct or buffered I/O requests.
If the process's requests remain under quota, the system service allows
it to continue 1/0 preprocessing. Where quota is exceeded, the procedure
examines the process's resource wait flag (PCB$V_SSRWAIT in PCB$L_
STS).
If the flag is clear, EXE$QIO aborts the I/O request. However, if the flag

is set, it places the process in a wait state until previously issued 1/0
requests complete and the number of requests drops below quota. When
this occurs, process execution resumes, at which time EXE$QIO charges
process quotas as appropriate for the requested operation.

4.1.5

Validating the 1/0 Status Block
If the I/O request specifies a quadword l/O status block to receive final

1/0 status information, EXE$QIO determines whether the process issuing
the request has write access to the status block locations specified. If the
process has write access, EXE$Ql0 fills the quadword with zeros. If the
process does not have write access, the procedure terminates the request
with an error status.

4.1.6

Allocating and Setting Up an 1/0 Request Packet
If validation of the I/O request succeeds to this point, EXE$Ql0 allocates

a block of nonpaged pool to contain an I/O request packet (IRP).
Before EXE$QIO allocates an IRP, it raises the IPL of the processor to
lPL$_ASTDEL to block any other asynchronous activity in the process.
The new IPL prevents possible deletion of the process; process deletion
would result in the operating system's losing track of the pool allocated for
the lRP.
EXE$QIO attempts to allocate an IRP from a lookaside list containing
preallocated lRPs. If no preallocated packets exist, the procedure calls
a VMS routine that allocates an IRP from general nonpaged pool. This
allocating routine synchronizes with the rest of the system so that it can
allocate the memory needed.
EXE$QIO resumes I/O preprocessing by writing a description of the 1/0
request into the fields of the IRP, as shown in Table 4-1. Note that this
data encompasses the device-independent information associated with the
request. It is up to the device driver's FDT routines or VMS common FDT
routines to fill in the device-dependent portions of the lRP, as described in
Section 4.1.7 and Chapter 7.
Refer to the VMS Device Support Reference Manual data structures for an
illustration of the IRP and description of its contents.

4-9

Overview of 1/0 Processing
4.1 Preprocessing an 1/0 Request

Table 4-1

IRP Data Fields

Data

Fields

Size in bytes of the IRP

IRP$W_SIZE

Identification of the block as an IRP

IRP$B_TYPE

Access mode of the process at the time of the
request

IRP$B_RMOD

Process ID of the requesting process

IRP$L_PID

Address of an AST routine (if specified in the
request) and its parameter1

IRP$L_AST, IRP$L_ASTPRM

For file-structured devices, address of a window
control block (WCB) that describes the physical
location of part of the file

IRP$L_WIND

Address of the target device's UCB

IRP$L_UCB

1/0 function code

IRP$W_FUNC

Number of event flag to set when processing of
the 1/0 request is complete

IRP$B_EFN

Base software priority of the requesting process

IRP$B_PRI

Address of an 1/0 status block (if specified in the
request)

IRP$L_IOSB

Process 1/0 channel index number

IRP$W_CHAN

A flag indicating whether the 1/0 function is for
buffered or direct 1/0

IRP$V_BUFIO in IRP$W_STS

A flag indicating whether the 1/0 request is an
input request

IRP$V_FUNC in IRP$W_STS

A flag indicating whether the 1/0 function is a
physical-1/0 function

IRP$V_PHYSIO in IRP$W_STS

Address of a diagnostic buffer (if specified in the
request) 3 and a flag indicating that the buffer is
present

IRP$L_DIAGBUF, IRP$V_
DIAGBUF in IRP$W_STS

Address of process's access rights block

IRP$L_ARB

1/0 transaction sequence number

IRP$L_SEQNUM

1
If the request specifies an AST, EXE$010 also verifies that the request would not cause the
process to exceed its AST quota. If it would, EXE$QIO aborts the request.

2
For nonfile devices (DEV$V_FOD clear in UCB$L_DEVCHAR}, EXE$QIO reduces read- and
write-virtual-block functions to their equivalent read- and write-logical-block functions before
storing a code.
3
The size of the diagnostic buffer is specified in the driver dispatch table of the driver servicing
the device unit to which the request is made. See Section 6.2 for more information.

4.1.7

FDT Processing
The driver's function decision table controls the device-dependent
preprocessing of an 1/0 request. Figure 4-5 illustrates the layout of a
function decision table.

4-10

Overview of 1/0 Processing
4.1 Preprocessing an 1/0 Request

Figure 4-5 Layout of a Function Decision Table

Validl/O

2 Longwords
{

~------------------------------

Functions
Buffered 1/0

2 Longwords
{

~------------------------------

Functions
64-Bit
~------------------------------

3 Longwords

Mask
~------------------------------

Routine Address
64-Bit
~------------------------------

3 Longwords

Mask
~------------------------------

Routine Address

•
•
•

ZK-0921-GE

The I/O function code specified in an I/O request is a 16-bit value
consisting of two fields:
•

A 6-bit I/O function code (bits 0 through 5) that permits you to define
64 unique I/O function codes for every device type. Table 6-1 lists the
function codes defined by VMS. Section 6.3.2 describes how you can
define device-specific function codes.

•

A 10-bit I/O function modifier (bits 6 through 15). In subsequent
processing of the I/O request, the driver's start-I/O routine uses both
I/O function code and I/O function modifier, as stored in IRP$W_
FUNC, to create a device-specific function code to use in device
activation.

The first two entries of a function decision table are two longwords (64
bits) each. The first quadword entry is the legal function bit mask of
all I/O function codes that are valid for the device. The second quadword
entry is the buffered function bit mask of those valid I/O functions that
are also buffered-I/O functions.
4-11

Overview of 1/0 Processing
4.1 Preprocessing an 1/0 Request

EXE$QIO uses the value of the low-order six bits of the I/O function code
to determine which bit to check in each of these bit masks. For example, if
the function code has a value of 22, the procedure checks the twenty-third
bit (bit 22) of each bit mask. Thus, EXE$QIO determines whether the
I/O function code is valid for the device and is able to charge against the
appropriate quota of the requesting process for a direct- or buffered-I/O
operation. 1
Subsequent entries in the function decision table are three longwords long,
and it is these entries that EXE$QIO uses to dispatch to the appropriate
1/0 preprocessing routine (FDT routine) for the requested function. Again,
the first quadword is a 64-bit bit mask, and is checked by EXE$QIO in
exactly the same way as the legal function bit mask and the buffered
function bit mask. These action routine bit masks, however, contain
the address of an FDT routine in the subsequent longword, and it is to
this FDT routine that EXE$QIO transfers control when it discovers the bit
corresponding to the 1/0 function set in the quadword.
Some FDT routines are present in the operating system because they
provide common services for many devices. Section 7 .5 describes these
routines. Other routines are included in the device driver because they
perform device-dependent services.
EXE$QIO uses the action routine bit mask entries in the function decision
table to call FDT routines in the driver or system, according to the
following strategy:
1

If the bit corresponding to the function code is set in the action routine
bit mask, EXE$QIO calls the FDT routine whose address appears in
the following longword.
•

If this I/O function requires additional preprocessing after this
particular FDT routine completes its activity, the FDT routine
returns control to EXE$QIO with an RSB instruction. When
EXE$QIO regains control, it advances to the next action routine
bit mask and repeats step 1.

•

If this FDT routine completes all necessary preprocessing for this
particular I/O function, then it transfers control to a VMS routine
that queues the IRP or completes the request.

If the bit corresponding to the function code is not set, EXE$QIO
advances to the next action routine bit mask in the table and repeats
step 1.

Note: A single function decision table can specify that EXE$QIO call
more than one FDT routine to perform the many and varied
steps in the preprocessing of a single 1/0 function. However, it
is the responsibility of the FDT routine that ultimately completes
the preprocessing to end the scan (by EXE$QIO) of the function
decision table. An FDT routine accomplishes this by transferring
control to either a VMS routine that queues the 1/0 request for
the driver's start-1/0 routine or one that completes or aborts
1

For physical- and logical-1/0 operations, EXE$QIO also verifies that the process making the 1/0 request has
suitable privileges.

4-12

Overview of 1/0 Processing
4.1 Preprocessing an 1/0 Request

the request (see Figure 4-6). In other words, for each valid 1/0
function code for a device, an FDT entry must contain the address
of a routine that ends 1/0 preprocessing.
The execution flow of FDT routines is illustrated in Figure 4-6. FDT
routines execute in the context of the process that requested the 110
operation. Thus, FDT routines can access process virtual address space.
Once all FDT preprocessing is complete, however, the rest of the processing
for the 110 request continues in the limited context of a driver fork process
or an interrupt service routine.

4.2

Handling Device Activity
When 1/0 preprocessing is complete, the last-called FDT routine generally
jumps (with a JMP instruction) to a routine called EXE$QIODRVPKT. 2
EXE$QIODRVPKT, in turn, transfers control (using a JSB instruction) to
EXE$INSIOQ, the VMS routine that queues IRPs and arbitrates device
activity. (See Figure 4-2 for a representation of the flow of 110 request
processing at this juncture.)

4.2.1

Creating a Driver Fork Process to Start 1/0
EXE$INSIOQ creates only one driver fork process at a time for each
device unit on the system. As a result, only one IRP for each device unit
is serviced at one time. EXE$INSIOQ determines whether a driver fork
process exists for the target device, as follows:
•

If the device is idle, no driver fork process exists for the device; in this

case, EXE$INSIOQ immediately calls IOC$INITIATE to create and
transfer control to a driver fork process to execute the driver's start-110
routine.
•

If the device is busy, a driver fork process already exists for the device,
servicing some other I/O request. In this case, EXE$INSIOQ calls
EXE$INSERTIRP to insert the IRP into a queue of IRPs waiting for
the device unit. The routine queues the IRP according to the base
priority of the caller. Within each priority, IRPs are in first-in/first-out
order. The completion of the current 110 request triggers the servicing
of the I/O request that is first in the queue, according to the procedure
described in Section 10.1.2.3.

In the latter case, by the time the driver's start-110 routine gains control
to dequeue the IRP, the originating user's process context is no longer
available. Because the context of the process initiating the 110 request is
not guaranteed to a driver's start-110 routine, the driver must execute in
the reduced context available to a fork process.

The rules for exiting from FDT preprocessing, including descriptions of EXE$QIODRVPKT and other FDT
exit routines, appear in Section 7.2.

4-13

Overview of 1/0 Processing
4.2 Handling Device Activity

Figure 4-6

FDT Routines and 1/0 Preprocessing

010 determines
function
code value.

Terminate
request and
return to
user.

Check for
buffered
1/0.

Advance
to
next
entry.

Call
subroutine.

Subroutine performs
1/0 preprocessing
and returns or
calls to queue
packet or terminates.
Return to 010.

Call VMS
routine to
queue packet
for driver.

Call VMS
routine to
complete or
abort 1/0.
ZK-0922-GE

4-14

Overview of 1/0 Processing
4.2 Handling Device Activity

IOC$INITIATE always initiates the driver's start-I/0 routine with a
context that is appropriate for a fork process. VMS establishes this
context by performing the following steps:
1

Raising IPL to driver fork IPL (and obtaining the associated fork lock
in a VMS multiprocessing environment)

Loading the address of the IRP into R3

Loading the address of the device's UCB into R5

Transferring control (with a JMP instruction) to the entry point of the
device driver's start-I/0 routine

The newly activated driver fork process executes under the constraints
listed in Section 3.3.3.2. It executes until one of the following events
occurs:

4.2.2

•

Device-dependent processing of the I/O request is complete.

•

A shared resource needed by the driver is unavailable, as described in
Section 3.4.

•

Device activity requires the fork process to wait for a device interrupt.

Activating a Device and Waiting for an Interrupt
Depending on the device type supported by the driver, the start-I/0 routine
performs some or all of the following steps:
1

Analyzes the I/O function and branches to driver code that prepares
the UCB and the device for that I/O operation

Copies the contents of fields in the IRP into the UCB

Tests fields in the UCB to determine whether the device and/or volume
mounted on the device are valid

If the device is attached to a multiunit controller, obtains the controller

data channel
5

If the I/O operation is a DMA transfer, obtains I/O adapter resources

such as map registers and a UNIBUS adapter buffered data path
6

Raises IPL to device IPL, obtaining the associated device lock in a
VMS multiprocessing environment, to synchronize its access to device
registers

Loads all necessary device registers except for the device's control and
status register (CSR)

Raises IPL to IPL$_POWER and confirms that a power failure that
would invalidate the device operation has not occurred on the local
processor

Loads the device's CSR to activate the device

4-15

Overview of 1/0 Processing
4.2 Handling Device Activity

10 Invokes a VMS routine (using either the WFIKPCH or WFIRLCH

macro) to suspend the driver fork process until a device interrupt or
timeout occurs
This routine (IOC$WFIKPCH or IOC$WFIRLCH) expects to find, among
the items it inherits on the stack, the driver's fork IPL, as placed there by
the start-I/0 routine in step 7. As it suspends the driver, IOC$WFIKPCH
or IOC$WFIRLCH saves the driver's context in the UCB's fork block. This
context consists of the following information:
•

The contents of R3 and R4 (UCB$L_FR3, UCB$L_FR4)

•

The implicit contents of R5 as the address of the UCB

•

A driver return address (UCB$L_FPC)

•

The relative offset to a device timeout handler (calculated from
UCB$L_FPC and the value specified in the invocation of the
WFIKPCH or WFIRLCH macro)

•

The time at which the device will time out (UCB$L_DUETIM)

By convention, R4 often contains the address of the CSR; it permits the
driver to examine device registers. When the driver fork process regains
control after interrupt processing, R5 contains the UCB address; it is the
key to the rest of the I/O database that is relevant to the current I/O
operation.
Having removed the driver's start-I/0 routine's return address from the
stack and stored it in UCB$L_FPC, IOC$WFIKPCH (or IOC$WFIRLCH)
issues a DEVICEUNLOCK macro that restores IPL to fork IPL from the
stack. It then exits with an RSB instruction. Thus, IOC$WFIKPCH (or
I OC$WFIRLCH) effectively passes control to the caller of its caller. In this
case, the caller of the driver start-I/0 routine is EXE$INSIOQ. The flow
back from EXE$INSIOQ to a user process that asynchronously requested
the I/O operation is shown in Figure 4-2.
You can find additional information on the context of a start-I/0 routine in
Chapter 8.

4.2.3

Handling a Device Interrupt
When the device requests an interrupt, the interrupt dispatcher transfers
control to the driver interrupt service routine. The driver's interrupt
service routine runs at a high IPL so that the routine can service
interrupts quickly. A driver interrupt service routine usually performs
the following processing:

4-16

Retrieves the address of the UCB that owns the controller from
IDB$L_OWNER

Issues the DEVICELOCK macro to obtain the device lock associated
with operations at device IPL in a VMS multiprocessing environment

For multiunit device controllers, determines which device unit
generated the interrupt

Overview of 1/0 Processing
4.2 Handling Device Activity

Examines the UCB for the device to confirm that the driver fork
process expects the interrupt

Saves device registers

Reactivates the suspended driver fork process

If necessary, the reactivated driver fork process executes at the high IPL

of the interrupt service routine for a few instructions. Very soon, however,
the driver lowers its execution priority so that it does not block subsequent
interrupts for other devices in the system.

4.2.4

Switching from Interrupt to Fork Process Context
To lower its priority, the driver calls a VMS fork process queuing routine
(by means of the IO FORK macro) that performs the following actions:
1

Disables the timeout that was specified in the wait-for-interrupt
routine

Saves R3 and R4 (UCB$L_FR3, UCB$L_FR4)

Saves the address of the instruction following the IO FORK request in
the UCB fork block (UCB$L_FPC)

Places the address of the UCB fork block from R5 in a processorspecific fork queue for the driver's fork level

Returns to the driver's interrupt service routine

The interrupt service routine then cleans up the stack, issues the
DEVICEUNLOCK macro to release the device lock, restores registers,
and dismisses the interrupt. Figure 4-7 illustrates the flow of control in a
driver that creates a fork process after a device interrupt.

4-17

Overview of 1/0 Processing
4.2 Handling Device Activity

Figure 4-7

Creating a Fork Process After an Interrupt

Device
Generates
Interrupt

.....

........
REI

Driver
Interrupt
Service
Routine

JSB

......

Driver

•

JSB
~,

RSB

IOFORK

ZK-0923-GE

4.2.5

Activating a Fork Process from a Fork Queue
When no higher priority interrupts are pending, the local processor
transfers control to the fork dispatcher. When the processor grants an
interrupt at a fork IPL, the fork dispatcher processes the local fork queue
that corresponds to the IPL of the interrupt. To do so, the dispatcher
performs these actions:
1

Removes a fork block from the fork queue

Restores fork context

Obtains the fork lock specified in the fork block

Transfers control back to the fork process

Thus, the driver code calls VMS code that coordinates suspension and
restoration of a driver fork process. This convention allows VMS to service
hardware device interrupts in a timely manner and reactivate driver fork
processes as soon as no device requires attention.
When a given fork process completes execution, the fork dispatcher
releases the fork lock and removes the next entry, if any, from the local
fork queue. This fork dispatcher repeats the sequence described previously
until the fork queue is empty. After servicing the last entry in the queue,
the fork dispatcher releases the fork lock, restores RO through R5 from the
stack, and dismisses the interrupt with an REI instruction.
Figure 4-8 illustrates the reactivation of a driver fork process.

4-18

Overview of 1/0 Processing
4.3 Completing an 1/0 Request

Figure 4-8

Reactivation of a Driver Fork Process

Device
generates
interrupt.

•
Driver
services
interrupt.

Software
interrupt
occurs.

Driver
forks.

I-

Lower IPL to fork level.

Fork
dispatcher
calls driver.

Driver
dismisses
interrupt.

Driver
completes
request.

•

Fork
dispatcher
dismisses
interrupt.
ZK-0924-GE

4.3

Completing an 1/0 Request
Once reactivated, a driver fork process completes the I/O request as
follows:
1

Releases shared driver resources, such as map registers, UNIBUS
adapter buffered data path, and controller ownership

Returns status to the VMS I/O completion routine

4-19

Overview of 1/0 Processing
4.3 Completing an 1/0 Request

The I/0-completion routine performs the following steps to start
postprocessing of the I/O request and to start processing the next I/O
request in the device's queue:

4.3.1

Writes return status from the driver into the IRP

Inserts the finished IRP in the systemwide I/O postprocessing queue
and requests an interrupt from the processor at IPL$_IOPOST

Creates a new fork process for the next IRP in the device's pending-I/O
queue

Activates the new driver fork process

1/0 Postprocessing
When the local processor's IPL drops below the I/O postprocessing IPL, the
processor dispatches to the I/O postprocessing interrupt service routine.
This VMS routine completes device-independent processing of the I/O
request.
Using the IRP as a source of information, the IPL$_IOPOST dispatcher
executes the following sequence for each IRP in the postprocessing queue:

Removes the IRP from the queue

If the I/O function was a direct I/O function, adjusts the issuing

process's direct I/O quota and unlocks the pages involved in the I/O
transfer
3

If the I/O function was a buffered I/O function, adjusts the issuing

process's buffered I/O quota and, if the I/O was a write function,
deallocates the system buffers used in the transfer
4

Posts the local event flag associated with the I/O request

Queues a special kernel-mode AST routine to the process that issued
the $QI 0 system service call

The queuing of a special kernel-mode AST routine allows I/O
postprocessing to execute in the context of the user process but in a
privileged access mode. Process context is needed to return the results of
the I/O operation to the process's address space. The special kernel-mode
AST routine sets any common event flag associated with the I/O request
and writes the following data into the process's address space:
•

Data read in a buffered I/O operation

•

If specified in the I/O request, the contents of the diagnostic buffer

•

If specified in the I/O request, the two longwords of I/O status

If the I/O reque~t specifies an I/O completion AST routine, the special

kernel-mode AST routine queues the I/O completion AST for the process.
When VMS delivers the I/O completion AST, the system AST delivery
routine deallocates the IRP. The first part of an IRP is the AST control
block for user requested ASTs.

4-20

Device Driver Coding Format

This chapter describes the coding format of a basic driver program. It
describes basic program flow and code conventions to follow in the initial
phase of device driver programming.
A VMS template driver is provided in Appendix A and a VMS SCSI class
driver template is provided in Appendix B. The code in the VMS template
can serve as a starting point for coding a new UNIBUS or Q22 bus device
driver. The code in the SCSI template can serve as the starting point
for coding a new SCSI class driver. You can obtain machine-readable
copy of these templates from SYS$EXAMPLES:TDRIVER.MAR and
SYS$EXAMPLES:SKDRIVER.MAR, respectively.
Drivers do not necessarily need all of the routines indicated by the
templates, nor do driver routines and tables need to follow the exact
order of the templates. However, the VMS operating system does place a
few re.strictions on the order and content of driver routines and tables.
Figure 5-1 illustrates the organization of a device driver. The first item
in a device driver is the driver prologue table and the second is usually
the driver dispatch table. The order of the remaining driver components
varies from driver to driver.
The last statement in every driver, except for the .END assembly directive,
must be a label marking the end of the driver. The address of this label
is stored in the driver prologue table. The driver-loading procedure uses
this address to calculate the size of the driver. Chapter 12 describes the
driver-loading procedure.
Some drivers contain no device-dependent, FDT routines. Other drivers
need only minimal initialization procedures. However, every driver
normally contains static driver tables and a start-110 routine or an
interrupt service routine.

5.1

Coding Conventions
The driver-loading procedure loads a device driver into a block of
nonpaged system memory whose location is chosen by the operating
system memory allocation routines. Therefore, the driver must consist of
position-independent code only.
In addition, the system might call a device driver repeatedly to process
1/0 requests and interrupts. The driver often does not complete one 110
operation before the system transfers control to the driver to begin another
on a different unit. For this reason, the code must be reentrant.

5-1

Device Driver Coding Format
5.1 Coding Conventions

Figure 5-1

Driver Organization

Driver
Prologue
Table

Driver
Dispatch
Table

Function
Decision
Table

FDT
Routines

Device Handling
Routines

End Mark
ZK-0925-GE

The rules of position-independent and reentrant code are as follows:

5-2

•

Instructions can branch only to relative addresses within the
driver and to global addresses listed in the VMS symbol table
(SYS$SYSTEM:SYS.STB).

•

Static tables can list only global addresses and relative addresses
within the driver.

•

The driver cannot store temporary data in local driver tables for
dynamic driver context. All dynamic temporary storage must be
contained within the unit control block corresponding to an I/O request
or the current 1/0 request block.

Device Driver Coding Format
5.1 Coding Conventions

•

The driver must refer to the I/O database by loading the address
of a data structure into a general register and using displacement
addressing to the fields of the data structure.

Device drivers must also restrict their use of general registers and the
stack:
•

FDT routines can use RO through R2 and R9 through Rll as available
registers. The routlnes can use other registers by saving the registers
before use and restoring them before exiting from the FDT routine.

•

All other driver routines can use RO through R5 as available registers.
The routines can use other registers, if necessary, by saving and
restoring them; but using other registers in this way is discouraged.

•

All driver routines can use the stack for temporary storage only if the
routines restore the stack to its previous state before calling any VMS
routines, forking, or executing RSB instructions.

Because certain VAX processors and VMS cooperate to support the
emulation of specific sets of VAX instructions, a device driver writer should
exercise some caution. Because the software emulation for floating-point
instructions may at some time be placed in pageable code, drivers should
never use floating-point instructions. VMS only guarantees the emulation
for character string instructions to be nonpaged.
Finally, the use of VAX vector instructions is prohibited above IPL$_
ASTDEL.

5.2

Restrictions on the Use of Device-Register 1/0 Space
The programmer of a device driver must observe the following restrictions
on the use of device registers:
•

Drivers should always store the address of a device control register in
a general register and then gain access to the device register indirectly
through the general register. The following example defines symbolic
word offsets for each device register and gains access to them using
displacement-mode addressing from R4.
; Device register offsets
LP CSR
LP DBR

0
2

;CSR offset
;Buffer address offset

MOVL
MOVL

UCB$L_CRB(R5),R4
;Get address of CRB
@CRB$L_INTD+VEC$L_IDB(R4),R4 ;Get the address of
; the device's CSR

TSTW

LP_CSR(R4)

;Is printer on line?

5-3

Device Driver Coding Format
5.2 Restrictions on the Use of Device-Register 1/0 Space

•

Floating-point, field, queue, quadword, octaword, and vector operands
are not allowed in 1/0 address space, nor can an instruction obtain
the position, size, length, or base of an operand from 1/0 space. For
example, a driver cannot use a bit field instruction to test a bit in a
device register.

•

Drivers cannot use string-handling instructions when referring to 1/0
space.

•

Drivers can use only those instructions that modify or write to a
maximum of one destination. The destination must be the last
operand.

•

Registers of devices connected to the backplane interconnect (for
example, UNIBUS adapter d~vice registers and MASSBUS device
registers) are longwords. Registers of devices connected to the
UNIBUS or Q22 bus are words. Instructions that refer to UNIBUS
adapter registers must use longword context. All driver instructions
that affect UNIBUS or Q22 bus device registers must use word context
(for example, BISW, MOVW, and ADDW3) unless the register is byte
addressable.

•

An instruction that refers to 1/0 space must not generate an exception
or be interruptable. If the instruction is allowed to restart, it will
reread the device register, which can cause undesirable device side
effects or data loss.

•

On any given VAX processor, a device driver cannot anticipate the
completion of an instruction that writes to 1/0 space before subsequent
instructions execute. The processor can continue to execute without
waiting for the data to reach its intended destination.
Among the consequences of this behavior are the following:
If a driver initiates device actions that result in an interrupt from

the device, the amount of time before that interrupt actually occurs
is unpredictable.
If a driver disables interrupts from a device, the time before that

device can no longer generate an interrupt is unpredictable.
An 1/0 bus error will not be reported synchronously with the
instruction causing the error.

As a result, a driver's interrupt service routine always should be
prepared to service unexpected or spurious interrupts. See Section 9.3
for additional discussion of the servicing of unexpected interrupts.

5-4

Device Driver Coding Format
5.2 Restrictions on the Use of Device-Register 1/0 Space

•

5.3

To access I/O space, use only the following instructions. These
instructions cannot be interrupted unless they use autoincrementdeferred addressing mode or any of the displacement-deferred modes
when specifying an operand.
ADAWI

ADD(B,W,L)2

ADD(B,W,L)3

ADWC

BIC(B,W,L)2

BIC(B,W,L)3

BICPSW

BIS(B,W,L)2

BIS(B,W,L)3

BISPSL

BISPSW

BIT(B,W,L)

CASE(B,W,L)

CHM(K,E,S,U)

CLR(B,W,L)

CMP(B,W,L)

CVT(BW,BL,WB,
WL,LB,LW)

DEC(B,W,L)

INC(B,W,L)

MCOM(B,W,L)

MFPR

MNEG(B,W,L)

MOV(B,W,L)

MOVA(B,W,L)

MOVAQ

MOVPSL

MOVZ(BW, BL, WL)

MTPR

PROBE(R,W)

PUSHA(B,W,L)

PUS HAQ

PUSHL

SBWC

SUB(B,W,L)2

SUB(B,W,L)3

TST(B,W,L)

XOR(B,W,L)2

XOR(B,W,L)3

Implementing Conditional Code in a Driver
When writing a DMA driver to function for equivalent devices on different
I/O bus implementations, you should use the ADPDISP macro in code
paths that need to differentiate between the systems.
The ADPDISP macro (defined in SYS$LIBRARY:LIB.MLB) provides a
means by which a device driver can be designed to drive a similar device
in a variety of VAX configurations. The ADPDISP macro allows the driver
to determine at run time the existence of a certain I/O bus or adapter
characteristic, and transfer control to code designed to execute given this
hardware trait.
A driver can use ADPDISP to transfer control to specific code given any of
the following characteristics:
•

Adapter type

•

Number of adapter address bits (18 or 22)

•

Map registers supported

•

Autopurging data paths supported

•

Buffered data paths supported

•

Direct-vector interrupt dispatching supported

•

Odd-aligned transfers on buffered data path supported

•

Odd-aligned transfers on direct data path supported

•

Alternate set of map registers (496 to 8191) available

•

Q22 bus device

5-5

Device Driver Coding Format
5.3 Implementing Conditional Code in a Driver

Use ADPDISP when it is necessary to conditionally execute pieces of
code, for instance, the allocation and loading of map registers for devices
for which map registers are available or the allocation of a physically
contiguous buffer for a DMA transfer on a generic VAXBI device which
requires such a buffer). VMS supplies a similar macro, CPUDISP, which
causes a run-time transfer of control to a specified destination depending
on the CPU type of the executing processor. For those processors not
uniquely identified by CPU type, CPUDISP also provides the means to
dispatch on a particular CPU subtype.
Because a device driver cannot make assumptions about the I/O
architecture of any given VAX system, Digital recommends that most
instances of the CPUDISP macro be replaced by an appropriate usage of
the ADPDISP macro.
Appendix C and Appendix D contain examples of drivers that use the
ADPDISP macro to provide conditional code in a driver. See also the
description of the ADPDISP macro in the macro chapter of the VMS
Device Support Reference Manual.

5-6

Writing Device-Driver Tables

Every device driver declares three static tables that describe the device
and driver:
•

Driver prologue table-Describes the device type, driver name, and
fields in the I/O database to be initialized during driver loading and
reloading.

•

Driver dispatch table-Lists some of the driver's entry points to
which VMS transfers control. The channel request block and function
decision table list other entry points.

•

Function decision table-Lists valid functions of the driver and
entry points to routines that perform I/O preprocessing for each
function.

The VMS operating system provides macros that drivers can invoke to
create these tables.

6.1

Driver Prologue Table
The driver prologue table (DPT) is the first part of every device driver.
This table, along with parameters to the SYSGEN command that request
driver loading, describes the driver to the driver-loading procedure. In
turn, the driver-loading procedure computes the size of the driver, loads
it into nonpaged system memory, and creates data structures for the new
devices in the I/O database. The loading procedure also links the new DPT
into a list of all DPTs known to the system. Chapter 12 describes how the
driver-loading procedure decides which data structures to build for a given
device.
Device drivers can pass data-structure initialization information to the
driver-loading procedure through values stored in the DPT. In addition,
the driver-loading procedure initializes some fields within the device data
structures using information from its own tables.
The contents of the DPT data structure are shown and described in the
VMS Device Support Reference Manual data structures section. Drivers
must treat many of the fields initialized by the driver-loading procedure
as read-only fields. These fields are marked with an asterisk in the VMS
Device Support Reference Manual DPT illustration.
To create a DPT, the driver invokes the DPTAB macro, as described in the
macro chapter of the VMS Device Support Reference Manual. The DPTAB
macro generates a driver prologue table (DPT) in a program section called
$$$105_PROLOGUE.
The DPTAB macro requires the following information:
•

Address of the end of the driver in its end argument.

6-1

Writing Device-Driver Tables
6.1 Driver Prologue Table

•

Code identifying the device by its adapter type in the adapter
argument. Accepted adapter types include UBA (for devices attached
to either a UNIBUS or Q22 bus), MBA, and GENBI.

•

Name of the driver in the name argument. (Digital reserves to
customers driver names beginning with the letters J and Q.)

•

Size of the unit control block (UCB) in the ucbsize argument. (The
template in Appendix A and the macro descriptions in VMS Device
Support Reference Manual demonstrate how you can specify an
extended UCB defined by VMS or create an extended UCB within
a driver.)

The DPTAB also allows you to specify the following information, if
applicable to the device driver:
•

Whether the driver needs a permanently allocated system page

•

Whether the driver has been written to run in a VMS symmetric
multiprocessing system

•

Name of a driver unloading routine, if any, to be called subject to a
SYSGEN RELOAD command

•

Maximum number of units supported by the driver (default is 8)

•

Number of UCBs to be created when the driver is loaded by means
of the SYSGEN autoconfiguration facility and the address of a unit
delivery routine to be called by that facility

A driver follows the DPTAB macro invocation with several instances of
the DPT_STORE macro. The DPT_STORE macro provides the driver with
a means of communicating its initialization needs to the driver-loading
procedure. When invoked, the DPT_STORE macro places information in
the DPT that the driver-loading procedure uses to load specified values
into specified fields. The DPT_STORE macro accepts two lists of fields:
•

Fields to be initialized only when the driver is first loaded

•

Fields to be initialized when a driver is first loaded and reinitialized if
the driver is reloaded

The DPTAB macro stores the relative addresses of these two lists, called
initialization and reinitialization tables, in the DPT.
Drivers use the DPT_STORE macro with the INIT table marker label to
begin a list of DPT_STORE invocations that supply initialization data for
the following fields:

6-2

UCB$B_FLCK

Index of the fork lock under which the driver performs
fork processing. The DPTAB macro, in invoking the
$SPLCODDEF macro, defines the symbols for these
indexes.

UCB$B_DIPL

Device interrupt priority level.

Writing Device-Driver Tables
6.1 Driver Prologue Table

Other commonly initialized fields are
UCB$L_DEVCHAR

Device characteristics

UCB$B_DEVCLASS

Device class

UCB$B_DEVTYPE

Device type

UCB$W_DEVBUFSIZ

Default buffer size

UCB$Q_DEVDEPEND

Device-dependent parameters

Drivers use the DPT_STORE macro with the REINIT table marker label
to begin a list of DPT_STORE invocations that supply initialization and
reinitialization data for certain fields. Every driver must specify the
following field in such an invocation:
DDB$L_DDT

Driver dispatch table

Other commonly initialized fields are
CRB$L_INTD+ VEC$L_ISR

Interrupt service routine.

CRB$L_INTD2+VEC$L_ISR

Interrupt service routine for second interrupt
vector.

CRB$L_INTD+ VEC$L_INITIAL

Controller initialization routine.

CRB$L_INTD+VEC$L_UNITINIT

Unit initialization routine (for UNIBUS, Q22
bus, and generic VAXBI device drivers). Note
that MASSBUS drivers must specify the
address of the unit initialization routine in an
invocation of the DDTAB macro.

For an example of the use of the DPT and DPT_STORE macros, see the
description of the DPTAB macro in VMS Device Support Reference Manual.

6.2

Driver Dispatch Table
The driver dispatch table (DDT) lists some of the entry points for driver
routines to be called by VMS for 1/0 processing. Every driver must create
a DDT.
The routines listed in the DDT can reside in the driver module or in a
VMS module. The routines chapter in the VMS Device Support Reference
Manual describes the VMS device-independent routines that can be
specified.
Device-dependent routines are normally located in the driver module. The
DDT contains relative addresses for routines located in the driver module
and absolute addresses for routines located in the operating system. At
loading time, the driver-loading procedure changes the relative addresses
of driver routines to absolute addresses.
The driver creates a DDT by invoking the macro DDTAB. The DDTAB
macro labels the DDT devnam$DDT, according to the value you supply in
its devnam argument. The driver-loading procedure writes the address of
the DDT table, as specified in a DPT_STORE macro, into the DDB. Refer
to the VMS Device Support Reference Manual for an illustration of the
DDT and a description of its contents.

6-3

Writing Device-Driver Tables
6.2 Driver Dispatch Table

The DDTAB macro also generates the program section ($$$115_DRIVER)
in which the DDT itself and all driver code reside.
The DDTAB macro has a single required argument, functb, for which
the driver must specify the address of its function decision table. Several
optional arguments allow the driver to specify the names of the following
routines, if applicable:
•

Start-1/0 routine

•

Unsolicited interrupt service routine (for MASSBUS device drivers)

•

Cancel-1/0 routine

•

Unit initialization routine

•

Alternate start-110 routine

•

Cloned UCB routine

In addition, you specify the length of any diagnostic buffer or error
message buffer using the DDTAB macro.
See the description of the DDTAB macro in the VMS Device Support
Reference Manual for additional information.

6.3

Function Decision Table
The function decision table (FDT) lists codes for I/O functions that are
valid for the device; indicates whether the functions are buffered-I/O
functions; and specifies routines to perform preprocessing for particular
functions. Every device driver must create an FDT containing three or
more entries:
•

The list of valid 1/0 function codes

•

The list of buffered I/O function codes

•

One or more entries each of which specifies all or a subset of I/O
function codes and the address of a routine that performs I/O
preprocessing for those function codes

If no buffered I/O functions are defined for the device, the second entry

contains an empty list.
Taken together, the third through last entries in the FDT specify one
or more FDT routines for each valid I/O function code for the device.
The FDT routines must terminate the 1/0 preprocessing for each type of
function by transferring control out of the $QIO system service and into a
routine that queues the I/O request to a driver, inserts the I/O request in
the postprocessing queue, or aborts the I/O request.
Refer to Chapter 7 for information on writing FDT routines.

6-4

Writing Device-Driver Tables
6.3 Function Decision Table

Table 6-1 lists the physical, logical, and virtual I/O function codes defined
by VMS. A complete list of function codes and values is contained in the
macro $IODEF in SYS$LIBRARY:STARLET.MLB.
Table 6-1

1/0 Function Codes

Function

Description

Equivalent Symbols

Physical 1/0
10$_NOP1

No operation

10$_UNLOAD

Unload drive (required by all
disk drivers)

10$_LOADMCODE

10$_SEEK

Seek cylinder

10$_SPACEFILE1 (space files), 10$_STARTMPROC1
(start microprocessor)

10$_RECAL1

Recalibrate drive

10$_DUPLEX1 (enter duplex mode), 10$_STOP1 (stop)

10$_DRVCLR1

Drive clear

10$_1NITIALIZE (initialize), 10$_MIMIC1 (enter mimic
mode)

10$_RELEASE 1

Release port

10$_SETCLOCKP1 (set clock-physical)

10$_0FFSET

Offset read heads

10$_ERASETAPE 1 (erase tape), 10$_STARTDATAP1
(start data transfer-physical)

10$_RETCENTER 1

Return to center line

10$_QSTOP1 (queue stop request)

10$_PACKACK

Pack acknowledgment
(required by all disk drivers)

10$_SEARCH

Search for sector

10$_WRITECHECK

Write check data

10$_WRITEPBLK

Write physical block

10$_READPBLK

10$_SPACERECORD1 (space records), 10$_READRCT1
(read replacement and caching table)

Read physical block
Write header and data

10$_RDSTATS 1 (read statistics), 10$_CRESHAD1
(create a shadow set)

10$_READHEAD 1

Read header and data

10$_ADDSHAD1 (add member to shadow set)

10$_WRITETRACKD 1

Write track data

10$_COPYSHAD1 (perform shadow set copy op~rations)

10$_READTRACKD 1

Read track data

10$_REMSHAD1 (remove member from shadow set)

10$_AVAILABLE

Set device available (required
by all disk drivers)

10$_SETPRFPATH 1

Set preferred path

10$_DISPLAY1

Display MSCP/TMSCP
volume label

10$_DSE

Data security erase (and
rewind)

10$_WRITEHEAD

10$_REREADN 1
10$_REREADP

Reread next
Reread previous

10$_WRITERET

Write retry

10$_WRITECHECKH 1 (write check header and data)

1 Unsupported; subject to change without notice

(continued on next page)

6-5

Writing Device-Driver Tables
6.3 Function Decision Table

Table 6-1 (Cont.)

1/0 Function Codes
Description

Equivalent Symbols

10$_READPRESET1

Read in preset

10$_STARTSPNDL1 (start spindle)

10$_SETCHAR

Set device characteristics

Function
Physical 1/0

10$_SENSECHAR

Sense device characteristics

10$_WRITEMARK

Write tape mark

10$_COPYMEM 1 (copy memory)

10$_WRTTMKR1

Write tape mark retry

10$_DIAGNOSE1 (diagnose), 10$_SHADMV1 (perform
mount verification on shadow set)

10$_FORMAT

Format

10$_CLEAN 1 (clean tape)

Logical 1/0
10$_WRITELBLK

Write logical block

10$_READLBLK

Read logical block

10$_REWINDOFF

Rewind and set offline

10$_SETMODE

Set mode

10$_REWIND

Rewind tape

10$_SKIPFILE

Skip files

10$_SKIPRECORD

Skip records

10$_SENSEMODE

Sense mode

10$_WRITEOF

Write end of file

10$_TTY_PORT 1

Terminal port FDT routine

10$_FLUSH

10$_READRCTL1 (read RCT sector 0)

10$_FREECAP 1 (return free capacity)

Flush controller cache
1

10$_READLCHUNK

Read large logical block
1

10$_WRITELCHUNK

Write large logical block

Virtual 1/0
10$_WRITEVBLK

Write virtual block

10$_READVBLK

Read virtual block

10$_ACCESS

Access file

10$_CREATE

Create file

10$_DEACCESS

Deaccess file

10$_DELETE

Delete file

10$_MODIFY

Modify file
1

10$_NETCONTROL

X25 network control function

10$_READPROMPT

Read terminal with prompt

10$_SETCLOCK (set clock)

10$_ACPCONTROL

Miscellaneous ACP control

10$_STARTDATA (start data)

Unsupported; subject to change without notice
(continued on next page)

6-6

Writing Device-Driver Tables
6.3 Function Decision Table

Table 6-1 (Cont.)
Function

1/0 Function Codes
Description

Equivalent Symbols

Virtual 1/0
10$_MOUNT1
10$_TTYREADALL

Mount volume
1

Terminal read passall

10$_TTYREADPALL1

Terminal read with prompt
passall

10$_CONINTREAD

Connect to interrupt read-only

10$_CONINTWRITE

Connect to interrupt with
write

1 Unsupported; subject to change without notice

The device driver creates an FDT by invoking the FUNCTAB macro. Each
invocation of the FUNCTAB macro creates a 2- or 3-longword entry in
the FDT. The first two invocations create 2-longword entries because they
specify only function codes; they do not specify an accompanying action
routine.
All subsequent invocations of the FUNCTAB macro must specify
both function codes and the address of a routine that is to perform
preprocessing for those functions. These invocations create 3-longword
entries.
The $QIO system service processes entries in the order in which they
appear in the FDT. When a function code is present in more than one
3-longword entry, the system service sequentially calls every routine
specified for the function code until a routine stops the scan by aborting,
completing, or queuing an I/O request.
See the description of the FUNCTAB macro, and the example of its use, in
the VMS Device Support Reference Manual for additional information on
creating an FDT.

6.3.1

Defining Buffered-1/0 Functions
The second entry in an FDT is a buffered function bit mask that
indicates which legal functions the driver handles as buffered-I/O
operations. In selecting the functions that are to be buffered, you should
take the following information into consideration:
•

Direct 1/0 is intended only for devices whose 1/0 operations always
complete quickly. For example, although terminal I/O appears fast,
users can prevent the I/O operation from completing by using Ctrl/S to
halt the operation indefinitely; therefore, terminal I/O operations are
buffered I/O.

•

Use of direct I/O requires that the process pages containing the buffer
be locked in memory. Locking pages in memory increases the overhead
of swapping the process that contains the pages.

6-7

Writing Device-Driver Tables
6.3 Function Decision Table

6.3.2

•

Use of buffered 1/0 requires that the data be moved from the system
buffer to the user buffer. Moving data requires additional time.

•

Routines that manipulate data before delivering it to the user (for
example, an interrupt service routine for a terminal) cannot gain
access to the data if direct 1/0 is used. Therefore, transfers that
require data manipulation must be buffered 1/0.

•

VMS handles the quotas differently for direct 1/0 and buffered 1/0, as
described in the Guide to Maintaining a VMS System.

•

Generally, direct-memory-access (DMA) devices use direct 1/0, while
programmed 1/0 devices use buffered 1/0.

Defining Device-Specific Function Codes
You can also define device-specific function codes by equating the name
of a device-specific function with the name of an existing function that
is irrelevant to the device. The selected codes should, however, have a
type (logical, physical, or virtual) that is appropriate for the function
they represent. Also, user programs that issue $QIO requests specifying
a device-specific code must similarly redefine the existing function. For
example, the assembly code that follows defines three device-specific
physical 1/0 function codes.
IO$ STARTCLOCK=IO$ ERASETAPE
IO$-STOPCLOCK=IO$ OFFSET
IO$=STARTDATA=IO$=SPACEFILE

6-8

Start interval clock
Stop interval clock
Start data acquisition

Writing FDT Routines

The $QIO system service uses the driver's function decision table (FDT) to
determine which FDT routines to call to preprocess an I/O request. These
FDT routines validate process-specified arguments to the $QIO request.
VMS supplies many device-independent FDT routines. Device drivers
contain device-dependent FDT routines.
A driver should call the VMS device-independent FDT routines, described
in Section 7.5, whenever possible. This practice encourages the use of well
debugged routines and minimizes driver size.

7.1

Context of FDT Routine Execution
The $QIO system service executes in the context of the process that issues
the I/O request, but in kernel mode and at IPL$_ASTDEL. The process
is executing in kernel mode because the dispatching of the $QIO system
service executes a CHMK instruction. Process context allows the $QIO
system service and driver FDT routines to access process address space.
Because the $QIO system service expects FDT routines to preserve this
context, an FDT routine observes the following conventions:
•

It cannot call VMS system services or VMS RMS services.

•

It does not lower IPL below IPL$_ASTDEL. If a routine raises IPL,

it must obtain any appropriate spin lock, and it must lower IPL to
IPL$_ASTDEL before exiting, releasing any acquired spin lock.
•

It does not alter the stack without restoring its original state before

exiting.
•

If it issues a subroutine call, it must preserve the contents of R3
through RB across the call. It can, however, use RO through R2 and
R9 through Rll without saving their previous contents. If an FDT
routine needs to use R3 through RB, it can use the PUSHR and POPR

instructions to save registers on the stack and later restore them.
•

It exits either by an RSB instruction to return control to the system

service, or it issues a JMP instruction to one of the VMS routines
described in Section 7.2.1.
Before calling an FDT routine, the $QIO system service sets up the
contents of certain registers, as described in Table 7-1.

7-1

Writing FDT Routines
7.1 Context of FDT Routine Execution

Table 7-1

Registers Loaded by the $010 System Service

Content

Address of FDT routine being called

Address of IRP for current 1/0 request

Address of process control block (PCB) of current process

Address of UCB of device assigned to user-specified process-1/0
channel

Address of CCB that describes user-specified process-1/0 channel

Bit number of user-specified 1/0 function code

Address of current entry in FDT

Address of first function-dependent argument (p1) specified in 1/0
request

While FDT routines can perform extensive preprocessing, such as
determining whether user buffers are accessible and reformatting data
into buffers in the system address space, they should not access device
registers because the device might be active. Furthermore, FDT routines
should exercise restraint when modifying the UCB. Routines usually
access the UCB while holding the associated fork lock at driver fork IPL
to synchronize modifications, and FDT routines do not execute with such
synchronization. Drivers containing FDT routines that access device
registers or carelessly modify the UCB risk unpredictable operation or a
system failure.

7.2

FDT Routines and Their Exit Paths
To transfer control to an FDT routine, the $QIO system service loads the
address of the FDT routine into a register and executes a JSB instruction,
as follows:
JSB

(RO)

Each FDT routine chooses an exit path based on the following factors:
•

Whether another FDT routine needs to be called to perform additional
function-specific processing

•

Whether an error is found in the I/O request

•

Whether the operation is complete

•

Whether the I/O operation requires and is ready for device activity

The FDT routines, as illustrated in Figure 7-1, must transfer control out
of the FDT processing loop and into a VMS routine that queues an IRP,
completes an I/O request, or aborts an I/O request. The $QIO system
service does not stop scanning the FDT. Therefore, you must ensure that
for each valid function code in a driver's FDT, there is an FDT routine that
does not return control to the $QIO system service.

7-2

Writing FDT Routines
7.2 FDT Routines and Their Exit Paths

Figure 7-1

$QIO Scan of a Function Decision Table

Read
next
FDTentry.

Call
FDT
routine.

FDT routine
returns.

FDT routine exits.
QueuelRP,
finish 1/0,
or abort 1/0.
ZK-0926-GE

7.2.1

FDT Exit Paths
An FDT routine can exit using any of the following methods:

•

RSB

•

JMP G"EXE$QIODRVPKT

•

JSB G"EXE$ALTQUEPKT

•

JMP G"EXE$FINISHIO or JMP G"EXE$FINISHIOC

•

JMP G"EXE$ABORTIO

These methods are described in the following sections, and you can find
additional details on the routines they involve in the routines chapter of
the VMS Device Support Reference Manual.

7-3

Writing FDT Routines
7.2 FDT Routines and Their Exit Paths

7.2.1.1

RSB

An FDT routine issees an RSB instruction to return to the $QIO system
service. The FDT routine returns to the system service because the routine
knows that the FDT contains a subsequent entry with the same function
code bit set. As a result, the system service searches for another FDT
routine.
7.2.1.2

JMP G/\EXE$QIODRVPKT

EXE$QIODRVPKT transfers control to a VMS routine (EXE$INSIOQ)
that either delivers an lRP immediately to a driver's start-1/0 routine or
places the IRP in a pending-1/0 queue waiting for driver servicing. The
FDT routine uses this exit method if all preprocessing is complete, if no
fatal errors are found in the specification of an 1/0 request, and if device
activity, synchronized access to the device's UCB, or synchronized access to
device registers is required to complete the I/O request. Common examples
of such a request are read and write functions.
EXE$INSIOQ transfers control to the device driver's start-1/0 routine only
if the device unit is currently idle. If the device unit is busy, EXE$INSIOQ
inserts the IRP in a priority-ordered queue of IRPs waiting for the unit.
Once an FDT routine transfers control to EXE$QIODRVPKT, no driver
code that further processes the I/O request can refer to process virtual
address space. When a device driver's start-1/0 routine gains control,
the process that queued the I/O request might no longer be the mapped
process. Therefore, the driver must assume that all information regarding
the 1/0 request is in the UCB or the IRP and that all buffer addresses in
the UCB are either system addresses or page-frame numbers that can be
interpreted in any process context.
For direct 1/0 operations, FDT routines also must have locked all user
buffer pages in physical memory because paging cannot occur at driver
fork level or higher interrupt priority levels. The process virtual address
space is not guaranteed to be mapped again until VMS delivers a special
kernel-mode AST to the requesting process as part of I/O postprocessing.
7.2.1.3

JMP G/\EXE$FINISHIO or JMP G/\EXE$FINISHIOC

EXE$FINISHIO and EXE$FINISHIOC transfer control to a VMS routine
that writes a quadword of final I/O status from RO and Rl into the 1/0
status field of the IRP (IRP$L_MEDIA and IRP$L_MEDIA+4). (Note
that EXE$FINISHIOC clears the second longword of the final 1/0 status.)
The routine then inserts the IRP in the 1/0 postprocessing queue. These
routines return to the $QIO system service the two longwords of status
contained in the 1/0 status block (if any) specified in the 1/0 request.
An FDT routine that discovers a device-dependent error should always
return status using EXE$FINISHIO or EXE$FINISHIOC. These routines
gain control without any change in process context. Interrupt priority
level is at IPL$_ASTDEL; the process page-tables are mapped; and the
process is executing in kernel mode.

7-4

Writing FDT Routines
7.2 FDT Routines and Their Exit Paths

7.2.1.4

JMP GAEXE$ABORTIO

EXE$ABORTIO transfers control to a VMS routine that aborts an I/O
request. An FDT routine that discovers a device-independent error should
always use this method of exiting. Inability to gain access to a data
buffer or an error in the specification of the I/O request are examples of
device-independent errors.
EXE$ABORTIO gains control without any change in the process context.
Interrupt priority level is at IPL$_ASTDEL; the process virtual space is
mapped; and the process is executing in kernel mode. EXE$ABORTIO
stores a longword of status in RO and returns this to the system service.
7.2.1.5

JSB GAEXE$ALTQUEPKT

EXE$ALTQUEPKT transfers control to a VMS routine that calls an
alternate start-110 routine in the driver (specified in the driver dispatch
table at offset DDT$L_ALTSTART) that synchronizes requests for activity
on a device unit and initiates the processing of 110 requests.
The FDT routine uses this exit method when it has successfully completed
all driver preprocessing and the request requires device activity. However,
in contrast to EXE$QIODRVPKT, EXE$ALTQUEPKT bypasses the device
unit's pending-110 queue and the device busy flag; thus, the driver is
activated regardless of whether the device unit is busy. A driver that can
handle two or more 110 requests simultaneously uses this exit method.
Be aware that programming a device driver to process simultaneous 110
requests requires detailed knowledge of VMS internal design. A driver
that uses EXE$ALTQUEPKT must not only maintain its internal queues
but must also synchronize those queues with the unit's pending-110 queue,
which the operating system maintains. In addition, if a driver processes
more than one IRP at the same time, it must use separate fork blocks.
Such a driver completes the processing of 110 requests by calling the
routine COM$POST. This routine places each IRP in the systemwide I/O
postprocessing queue and returns control to the driver. The driver can
then fetch another IRP from an internal queue. For more information
about COM$POST, see the routines chapter of the VMS Device Support
Reference Manual.
Unlike the other FDT exit routines, EXE$ALTQUEPKT is called with
a JSB instruction rather than a JMP instruction. When the alternate
start-110 routine finishes, it returns control to EXE$ALTQUEPKT
by executing an RSB instruction. The FDT routine performs any
postprocessing and transfers control to the routine EXE$QIORETURN.
When EXE$QIORETURN gains control, it performs the following steps:
1

Sets the success status code SS$_NORMAL in RO

Lowers the interrupt priority level to zero

Returns (with the RET instruction) to the system service dispatcher

7-5

Writing FDT Routines
7 .3 FDT Routines for VMS Direct 1/0

7.3

FDT Routines for VMS Direct 1/0
The VMS operating system provides two standard FDT routines that are
applicable for direct 110 operations: EXE$READ and EXE$WRITE. When
called by the driver, these routines completely prepare a direct 1/0 read or
write request. Thus, a driver that uses these routines eliminates the need
for its own device-specific FDT routines.
EXE$READ and EXE$WRITE are described in Section 7.5.

7.4

FDT Routines for VMS Buffered 1/0
Device drivers for buffered 1/0 operations generally contain their own
device-specific FDT routines.
An FDT routine for a buffered 1/0 data transfer operation should confirm
either read or write access to the user's buffer and allocate a buffer in
system space. Sections 7.4.1 and 7.4.2 describe these tasks.
An FDT routine for a buffered I/O operation that does not involve data
transfer should copy the function-dependent parameters of the $QIO
request (pl to p6) to the IRP, perform any necessary preprocessing, and
use one of the exit methods listed in Section 7.2.1.

7.4.1

Checking Accessibility of the User's Buffer
First the FDT routine calls EXE$READCHK or EXE$WRITECHK to
confirm write or read access, respectively, to the user's buffer. Both
of these routines write the transfer byte count into IRP$L_BCNT.
EXE$READCHK also sets IRP$V_FUNC in IRP$W_STS to indicate that
the function is a read.

7.4.2

Allocating the System Buffer
Next, the FDT routine allocates a system buffer in the following manner:
1

It adds 12 bytes to the byte count passed in the p2 argument of the
user's 110 request, thus accommodating the standard size of a VMS
buffer header. This is the total system buffer size.

It calls EXE$DEBIT_BYTCNT_ALO to ensure that the process's
job has sufficient remaining byte count quota to allow its use of
the requested buffer. If the job has sufficient quota, EXE$DEBIT_
BYTCNT_ALO allocates the requested buffer from nonpaged pool,
writes the buffer's size and type into its third longword, and subtracts
the system buffer size from JIB$L_BYTCNT.

VMS also supplies the routines EXE$DEBIT_BYTCNT_BYTLM_ALO,
EXE$DEBIT_BYTCNT(_NW), EXE$DEBIT_BYTCNT_BYTLM(_NW), and
EXE$ALLOCBUF, which perform the same type of work as EXE$DEBIT_
BYTCNT_ALO. These routines are fully described in the VMS Device
Support Reference Manual.

7-6

Writing FDT Routines
7.4 FDT Routines for VMS Buffered 1/0

Once the buffer is allocated, the FDT routine takes the following steps:
1

Loads the address of the system buffer into IRP$L_SVAPTE.

Loads the total size of the system buffer into IRP$W_BOFF.

Stores the starting address of the system buffer data area in the first
longword of the buffer header.

Stores the user's buffer address in the second longword of the header.

Copies data from the user buffer to the system buffer if the 1/0 request
is a write operation.

At this point, the buffers are ready for the transfer. Figure 7-2 illustrates
the format of the system buffer.
Figure 7-2 Format of System Buffer for a Buffered-110 Read Function
System Space
System Buffer

Address of Data Area
User Buffer Address

Header

Size

Type

Buffer
Data
Area

Process Space

User
Buffer

ZK-0927-GE

7-7

Writing FDT Routines
7 .4 FDT Routines for VMS Buffered 1/0

7.4.3

Buffered-110 Postprocessing
When the transfer finishes, the driver returns control to VMS for
completion of the I/O request. The driver writes the final request status
in the low-order word of RO. Use of the high-order word of RO and the
longword of Rl is driver specific. Certain drivers use these fields to report
a transfer byte count, for example.
The driver must leave the buffer header intact; I/O postprocessing relies
on the header's accuracy. When VMS I/O postprocessing gains control, it
performs three steps:
1

Calls EXE$CREDIT_BYTCNT to add the value in IRP$W_BOFF to
JIB$L_BYTCNT, thus updating the user's byte count quota

If IRP$L_SVAPTE is nonzero, assumes a system buffer was allocated

and checks to see whether IRP$V_FUNC is set in IRP$W_STS
3

If IRP$V_FUNC is clear, deallocates the system buffer used for the
write operation; if IRP$V_FUNC is set, the special kernel-mode AST

copies the data to the user's buffer and then deallocates the buffer in
addition to performing other kernel-mode AST functions
The special kernel-mode AST performs the following steps to complete a
buffered read operation:

7.5

Obtains the address of the system buffer from IRP$L_SVAPTE.

Obtains the number of bytes to write to the user's buffer from IRP$L_
BCNT.

Obtains the address of the user's buffer from the second longword of
the system buffer header.

Checks for write accessibility on all pages of the user's buffer.

Copies the data from the system buffer to the process' buffer.

Deallocates the system buffer. Note that the system uses the size
listed in the buffer's header to deallocate the buffer.

FDT Routines Provided by VMS
The VMS FDT routines perform I/O request validation that is common to
many devices. Whenever possible, drivers should take advantage of these
routines. Normally, if a VMS FDT routine is called, no additional FDT
processing is required. All of the VMS FDT routines listed in Table 7-2
exit by transferring control to EXE$QIODRVPKT, EXE$FINISHIO,
EXE$FINISHIOC, or EXE$ABORTIO. Once a VMS FDT routine is called,
no subsequent FDT processing occurs.
For additional information about VMS FDT routines, see the pertinent
routine descriptions in VMS Device Support Reference Manual.

7-8

Writing FDT Routines
7.5 FDT Routines Provided by VMS

Table 7-2

FDT Routines Provided by VMS

FDT Routine

Function

Exit Method

EXE$MODIFY

Processes a logical-read/write or
physical-read/write function for a read
and write direct 1/0 operation to a
user-specified buffer

Aborts the 1/0 request if an error occurs,
or dismisses the 1/0 request if the
user 1/0 buffers cannot be locked in
memory; otherwise, transfers control to
EXE$QIODRVPKT

EXE$0NEPARM

Processes a nontransfer 1/0 function
code that has one parameter
associated with it

Transfers control to EXE$QIODRVPKT

EXE$READ

Processes a logical-read or physicalread function for a direct 1/0 operation

Aborts the 1/0 request if an error occurs,
or dismisses and resubmits the 1/0 request
if the user 1/0 buffers cannot be locked
in memory; otherwise, transfers control to
EXE$QIODRVPKT

EXE$SENSEMODE

Processes the sense-device-mode
and sense-device-characteristics
functions by reading fields of the UCB

Transfers control to EXE$FINISHIO

EXE$SETCHAR 1

Processes the set-device-mode and
set-device-characteristics functions

Transfers control to EXE$FINISHIO

EXE$SETMODE 1

Processes the set-device-mode and
set-device-characteristics functions by
creating a driver fork process

Aborts the 1/0 request if an error
occurs; otherwise, transfers control to
EXE$QIODRVPKT

EXE$WRITE

Processes a logical-write or physicalwrite function for a direct 1/0 operation

Aborts the 1/0 request if an error occurs,
or dismisses the 1/0 request if the
user 1/0 buffers cannot be locked in
memory; otherwise, transfers control to
EXE$QIODRVPKT

EXE$ZEROPARM

Processes a nontransfer 1/0 function
code that has no associated
parameters

Transfers control to EXE$QIODRVPKT

1
If setting device characteristics requires no device activity or requires no synchronization with fork processing, the driver's FDT
entry can specify EXE$SETCHAR; otherwise, it must specify EXE$SETMODE.

7-9

Writing a Start-1/0 Routine

A driver start-I/0 routine activates a device and then waits for a device
interrupt or timeout. This chapter describes the start-I/O routine.
Chapter 10 describes the reactivation of the driver routine that performs
device-dependent I/O postprocessing. With a few exceptions, the start-I/0
routine discussed in the following sections describes a DMA transfer using
a single-unit controller.

8.1

Transferring Control to the Start-1/0 Routine
The start-I/O routine of a device driver gains control from either of two
VMS routines: EXE$QIODRVPKT or IOC$REQCOM.
When FDT processing is complete for an I/O request, the FDT routine
transfers control to EXE$QIODRVPKT which, in turn, calls EXE$INSIOQ.
If the designated device is idle, EXE$INSIOQ calls IOC$INITIATE to
create a driver fork process. (This procedure is detailed in Section 7.2.1.2.)
The driver fork process then gains control in the start-I/0 routine of the
appropriate driver. If the device is busy, EXE$INSIOQ queues the packet
to the device unit's pending-I/0 queue.
After a device completes an I/O operation, the driver fork process exits
by transferring control to IOC$REQCOM. IOC$REQCOM inserts the
IRP for the finished transfer into the postprocessing queue. It then
dequeues the next IRP from the device unit's pending-I/0 queue and calls
IOC$INITIATE to initiate the processing of this I/O request in the driver's
fork process at the entry point of the driver's start-I/O routine.

8.2

Context of a Driver Fork Process
A start-I/O routine does not run in the context of a user process. Rather, it
has the following context:
System context

Driver code can only refer to system virtual addresses.

Kernel mode

Execution occurs in the most privileged access mode and
can, therefore, change IPL and obtain spin locks.

High IPL

The VMS routine that creates a driver fork process obtains
the driver's fork lock, raising IPL to driver fork level before
activating the driver.

Kernel or
interrupt stack

Execution occurs on the kernel or interrupt stack. The driver
must not alter the state of the stack without restoring the
stack to its previous state before relinquishing control. The
stack used depends on whether the 1/0 startup is the result
of a new 1/0 request or because a previously requested 1/0
operation has been completed. The choice of stacks must
not affect the operation of the start-1/0 routine.

8-1

Writing a Start-1/0 Routine
8.2 Context of a Driver Fork Process

In addition to the context described, the VMS packet-queuing routines set
up R3 and R5 for a driver start-1/0 routine, as follows:
•

R3 contains the address of the IRP.

•

R5 contains the address of the UCB for the device.

The start-110 routine must preserve all general registers except RO, Rl,
R2, and R4.
Before the packet-queuing routines call the start-110 routine, they copy the
following IRP fields into their corresponding slots in the device's UCB:

8.3

•

IRP$L_BCNT (low-order word) --.. UCB$W_BCNT

•

IRP$W_BOFF --.. UCB$W_BOFF

•

IRP$L_SVAPTE--.. UCB$L_SVAPTE

Functions of a Start-1/0 Routine
The processing performed by a start-110 routine is device specific. A
start-110 routine normally contains elements that perform the following
functions to activate:
•

Analyzing the 1/0 function

•

Transferring the details of a request from the IRP into the UCB

•

Obtaining and initializing the controller

•

Modifying device registers to activate the device

A start-1/0 routine of a DMA device driver performs additional tasks to
prepare the device for a DMA transfer prior to activating the device. These
tasks include the following:
•

Obtaining 1/0 adapter resources such as map registers and a buffered
data path

•

Computing the starting address of a data transfer

The following sections describe the general activities of a start-110 routine
for a typical device. The details of DMA processing are specific to the
particular device. Section 14.2 describes the UNIBUS- and Q22 busrelated details of DMA transfers. Section 15.5.3 relates those tasks that
MASSBUS DMA device drivers must perform. Section 16.6 discusses
similar functions that drivers for generic VAXBI devices may need to
perform.

8.3.1

Obtaining Controller Access
If the device is one of several attached to a controller, the start-110 routine
invokes the VMS macro REQPCHAN to assign the controller's data
channel to the device unit. Controllers that control only one device do not
require arbitration for the controller's data channel. REQPCHAN calls the
VMS routine IOC$REQPCHANL that acquires ownership of the controller
data channel.

8-2

Writing a Start-1/0 Routine
8.3 Functions of a Start-1/0 Routine

The transfer being controlled by the start-110 routine discussed here
requires no seek preceding the transfer. Disk 1/0 is an example of a
transfer that requires a seek first. To permit seeks to be overlapped with
transfers, invoke REQPCHAN with the argument pri=HIGH. Specifying
pri=HIGH inserts a request for a channel at the head of the channel wait
queue.
If the channel is not available, IOC$REQPCHANL suspends driver
processing by saving the driver's context in the UCB fork block and
inserting the fork block in the channel wait queue. IOC$REQPCHANL
then returns control to the caller of the driver, that is, to EXE$INSIOQ,
as illustrated in Figure 8-1. This procedure is further discussed in
Section 3.4.1.
Figure 8-1

Inserting a UCB into the Channel Wait Queue

010

FDT

JMP

QIODRVPKT
User
Program

INmATE

INSIOQ

JMP

RET

JMP

Channel
Wait
QJeue

QIORETURN

Driver

JSB
RSB

I REOCHAN ~-- -----

UCB
Address

ZK-0928-GE

The UCB fork block now represents the entire context of the suspended
driver:
•

Saved R3 containing the IRP address

•

Implicitly saved R5 containing the UCB address

•

A return address in the driver

Note that, because IOC$RELCHAN moves the address of the device's CSR
into R4 before resuming a suspended driver, IOC$REQPCHANL does not
save R4 in the UCB fork block.

8-3

Writing a Start-1/0 Routine
8.3 Functions of a Start-1/0 Routine

If the channel is available, IOC$REQPCHANL locates the interrupt
dispatch block (IDB) for the channel with a pointer in the UCB:

UCB ~ CRB ~ IDB
The IDB contains the address of the control and status register (CSR) for
the channel (IDB$L_CSR). IOC$REQPCHANL returns the CSR address in
R4. The driver for a unit attached to a dedicated controller must contain
the code needed to load the CSR address into R4.
IOC$REQPCHANL also writes the address of the new channel-owner's
UCB in the owner field of the IDB (IDB$L_OWNER). The driver's
interrupt service routine later reads this IDB field to determine which
device unit owns the controller's data channel. A driver for a single-unit
controller must fill the IDB$L_OWNER field in its controller or unit
initialization routines.
The driver must maintain the stack in a known and consistent state for
the resource-wait-queue mechanism to work. When IOC$REQPCHANL
gains control, the top two items on the stack must be two return addresses:

8.3.2

•

OO(SP)-Address of the next instruction to be executed in the driver
fork process. The transfer of control to IOC$REQPCHANL places this
address on the stack.

•

04(SP)-Address of the next instruction to be executed in the routine
that called the driver start-I/O routine.

Obtaining and Converting the 1/0 Function Code and Its Modifiers
The start-I/O routine extracts the I/O function code and function modifiers
from the field IRP$W_FUNC and translates them into device-specific
function codes, which it loads into the device's CSR or other control
registers. The start-I/O routine creates and modifies a bit mask that is to
be loaded into the CSR when the driver starts the device. To accomplish
this, the start-I/O routine converts the function modifiers contained in
IRP$W_FUNC into device-specific bit settings in the general register.
At this point, a UNIBUS/Q22 bus DMA driver follows procedures to obtain
I/O bus resources and compute the size and starting address of a transfer.
These procedures are discussed in Section 14.2. MASSBUS DMA device
drivers perform the steps indicated in Section 15.5.3.

8.3.3

Preparing the Device Activation Bit Mask
For a typical device, the start-I/O routine prepares the device-activation
bit mask by setting the interrupt-enable bit and the go bit in the general
purpose register that also contains the high-order bits of the bus address
and the device-function bits. At this point, the general register contains
a complete command for starting the transfer, also known as the control
mask.

8-4

Writing a Start-1/0 Routine
8.3 Functions of a Start-1/0 Routine
When the start-I/O routine copies the contents of the register into the
device's CSR, the device starts the transfer. Before activating the device,
however, the start-I/0 routine should perform the steps described in
Sections 8.3.4 and 8.3.5.

8.3.4

Synchronizing Access to the Device Database
The start-I/0 routine invokes the VMS macro DEVICELOCK to
synchronize its access to device registers with the interrupt service
routine. This macro invocation is doubly important, for it establishes
the context wherein the driver can later issue the wait-for-interrupt
macro (WFIKPCH or WFIRLCH). The wait-for-interrupt macros
expect the driver's fork IPL to be on the stack, as placed there by the
DEVICELOCK macro. In addition, the wait-for-interrupt macros issue
the DEVICEUNLOCK macro to release ownership of the device lock and
restore the previous IPL.

8.3.5

Checking for a Local Processor Power Failure
After synchronizing access to device registers, the start-I/O routine
invokes the VMS macro SETIPL to raise IPL to IPL$_POWER to block all
interrupts on the local processor.
The start-I/O routine then examines the powerfail bit in the UCB's status
longword (UCB$V_POWER in UCB$L_STS) to determine whether a local
power failure has occurred since the start-I/0 routine gained control. If
the bit is not set, the transfer can proceed.
If the bit is set, a power failure might have occurred between the time

that the start-I/O routine wrote the first device register and the time that
the start-I/0 routine is ready to activate the device. Such a power failure
could modify the already-written device registers and cause unpredictable
device behavior if the device were to be started.
If the bit UCB$V_POWER is set, the start-I/0 routine branches to an error

handler in the driver. The driver error handler must perform the following
actions:
•

Clear UCB$V_POWER

•

Issue the DEVICEUNLOCK macro to release the device lock and
restore IPL to fork IPL

After performing these tasks, many drivers transfer control to the
beginning of the start-I/0 routine, which restarts the processing of the
I/O request.

8.3.6

Activating the Device
If no power failure has occurred, the start-I/0 routine copies the contents

of the control mask into the device's CSR. When the device notices the new
contents of the device register, it begins to transfer the requested data.

8-5

Writing a Start-1/0 Routine
8.4 Waiting for an Interrupt or Timeout

8.4

Waiting for an Interrupt or Timeout
Once the start-I/0 routine activates the device, the driver fork process
cannot proceed until one of these events occurs:
•

The device generates a hardware interrupt.

•

The device does not generate a hardware interrupt within an expected
time limit, which is to say that a device timeout occurs.

Still executing at IPL$_POWER, the driver's start-I/O routine asks VMS
to suspend the driver fork process by invoking one of the following macros:
WFIKPCH

Wait for an interrupt or timeout and keep the controller data channel

WFIRLCH

Wait for an interrupt or timeout and release the controller data
channel

The WFIKPCH and WFIRLCH macros require the address of a timeout
handling routine in the excpt argument. Optionally, but almost always,
the driver can also indicate the number of seconds the system must wait
before signaling a timeout in the time argument. A full description of
these macros appears in the macro chapter of the VMS Device Support
Reference Manual.
Both macros invoke routines that release ownership of the device lock,
relinquish synchronization, and return IPL to the previous level when
exiting. These routines expect to find the return IPL on the stack. This
IPL is saved on the stack by the DEVICELOCK macro as described in
Section 8.3.4.
Drivers generally keep the controller data channel while waiting for the
interrupt or timeout. Drivers of devices with dedicated controllers always
keep the channel because only one unit ever needs it. For devices that
share a controller, some operations, such as disk seeks, do not require
the controller once the operation has begun. In such cases, the driver
can release the controller's data channel while waiting for an interrupt or
timeout so that other units on the controller can start their operations.

8.4.1

Expansion of WFIKPCH Macro
Because the WFIKPCH and WFIRLCH macros are similar, the description
that follows analyzes the expansion of WFIKPCH only.
If the driver specifies the time argument in the macro call, the macro
pushes the value of the argument into the stack. If the time argument

is not specified, the macro pushes the value 65,536 onto the stack.
IOC$WFIKPCH uses the time value to calculate the length of time VMS
waits before transferring control to a device timeout handler.

8-6

Writing a Start-1/0 Routine
8.4 Waiting for an Interrupt or Timeout

WFIKPCH completes its expansion with two lines of code:
JSB
.WORD

GAIOC$WFIKPCH
EXCPT-.

The execution of the JSB instruction pushes the address following the JSB
onto the stack as the address to which the called routine would normally
return with an RSB instruction.

8.4.2

IOC$WFIKPCH Routine
The VMS routine IOC$WFIKPCH, invoked by the macro WFIKPCH,
performs the functions necessary for the driver fork process to wait for a
device interrupt or timeout. IOC$WFIKPCH first adds 2 to the address
on the top of the stack so that the top of the stack contains the address of
the next instruction in the driver after the macro invocation. This address
is where the driver resumes execution as a result of an interrupt service
routine's JSB instruction.
IOC$WFIKPCH then saves the contents of R3, R4, and the address to
which control must be returned to the driver, which it takes from the top
of the stack. It saves this information in the first part of the UCB in the
UCB fork block.
Note that, after an interrupt, the interrupt service routine must restore R5
so that it contains the address of the UCB. The interrupt service routine
normally obtains the address of the UCB from the field IDB$L_OWNER of
the IDB.
The VMS routine that detects a device timeout calculates the address of
the driver's timeout routine by subtracting 2 from the saved PC in the
UCB's fork block and calling indirectly through the result. For example:
MOVL
CVTWL

UCB$L_FPC(R5),R2
-(R2),-(SP)

ADDL

(SP)+,R2

JSB

(R2)

Get saved PC
Get off set to timeout
handler
Add to relative driver
address to obtain relative
handler address
Call timeout handler

IOC$WFIKPCH sets bits in the UCB (UCB$V_INT and UCB$V_TIM in
UCB$L_STS) to indicate that interrupts and timeouts are expected from
the device. IOC$WFIKPCH also writes the device timeout absolute time
in the field UCB$L_DUETIM. The absolute time is the number of seconds
since the operating system was bootstrapped plus the number of seconds
specified in the time argument to the macro.
Finally, IOC$WFIKPCH reenables interrupts by releasing the device lock
and lowering IPL to fork level, the IPL at which the driver was executing
previously. It then returns control to the caller of the driver.

8-7

Writing an Interrupt Service Routine

When a device generates a hardware interrupt, it requests an interrupt
at the appropriate device IPL. Either the device or its adapter requests a
processor interrupt at that IPL. When the processor executes at an IPL
below that device IPL, interrupt dispatching begins.
The mechanism of interrupt dispatching has no direct bearing on the
contents of a driver's interrupt service routine. Its implementation varies
slightly according to the VAX processing system and I/O subsystem in use.
To obtain background information on the dispatcher, refer to the overview
provided in Section 14.3, which also details the method of dispatching
UNIBUS/Q22 bus device interrupts. MASSBUS device driver writers
should refer also to Section 15.4; generic VAX.BI device driver writers
should read the discussion in Section 16.4.1.
For most device drivers, the driver prologue table contains, in the
reinitialization section established by the DPT_STORE macro, the address
of one or more interrupt service routines. Each interrupt service routine
corresponds to an interrupt vector on the I/O bus. You specify the address
of an I/O bus vector using the SYSGEN command CONNECT, as described
in Section 12.2.2.
Most device interrupt service routines perform the following functions:
•

Locate the device's UCB

•

Determine whether the interrupt was solicited

•

Reject or process unsolicited interrupts

•

Activate the suspended driver to process solicited interrupts

Figure 9-1 illustrates the general flow of interrupt handling. The
remaining sections of this chapter describe the handling of solicited and
unsolicited interrupts in further detail.

9-1

Writing an Interrupt Service Routine

Figure 9-1

Flow of Interrupt Servicing
Interrupt
Interrupt
dispatcher
activates the
device unit's
Interrupt
service routine.
Interrupt service •
routine locates
device's UCB
using IDB pointer
on interrupt
stack.

Interrupt service
routine Issues
DEVICELOCK macro.

Yes

Reactivate
suspended
driver.

Interrupt
service routine
detennlnes
cause of
Interrupt.

Takes
appropriate
action.

Interrupt
service routine
rejects Interrupt
as spurious

Driver
Invokes
IOFORK
macro.

IOFORK

cans

EXE$10FORK.

EXE$10FORK
queues driver
fork block
and returns
to Interrupt
service routine.
Interrupt
service routine
removes IDB pointer
from stack, releases
device lock. and
restores RO - RS.

Interrupt
service routine
dismisses
interrupt
with REI.
ZK-0929-GE

9-2

Writing an Interrupt Service Routine
9.1 Interrupt Context

9.1

Interrupt Context
When the interrupt dispatcher calls a driver's interrupt service routine,
execution context is as follows:
•

RO through R5 are saved on the stack.

•

Only system address space may be accessed.

•

IPL is at hardware device interrupt level.

•

The processor is running in kernel mode.

•

The processor is running on the interrupt stack.

The stack contains the following information:
Stack Location

Content

OO(SP)

Pointer to the address of the IDB

04(SP) through 24(SP)

Saved RO through RS

28(SP)

PC at the time of the interrupt

32(SP)

PSL at the time of the interrupt

In the course of its processing, an interrupt service routine must remove
the IDB pointer and the saved registers from the stack before dismissing
the interrupt with an REI instruction.

9.2

Servicing a Solicited Interrupt
When a driver's fork process activates a device and expects to service a
device interrupt as a result, the fork process suspends its execution and
waits for an interrupt to occur. The suspended driver is represented only
by the contents of the fork block in the device's UCB and the stack, which
contain the following information:
•

A description of the I/O. request and the state of the device

•

The contents of R3 and R4

•

The implicit contents of R5 (the address of the UCB fork block)

•

The address at which to return control to the driver

•

The implicit address of a timeout handling routine

When the interrupt service routine returns control to the main line of
driver processing, it has only restored the contents of R3, R4, R5, and the
PC.
A driver's interrupt service routine performs the following tasks to process
the interrupt and transfer control to the waiting driver:
1

Obtains the address of the device's UCB from the IDB, as follows:
OO(SP) ~ CRB ~ IDB ~ IDB$L_OWNER ~ UCB
The interrupt service routine restores the UCB address to R5.

9-3

Writing an Interrupt Service Routine
9.2 Servicing a Solicited Interrupt

Issues the DEVICELOCK macro to obtain synchronized access to
device registers.

Tests the interrupt-expected bit in the UCB status longword (UCB$V_
INT in UCB$L_STS). If the bit is set, the driver is waiting for an
interrupt from this device. After performing this test, the interrupt
service routine must clear UCB$V_INT to indicate that it has received
the expected interrupt.

Note: Because device timeout processing mostly occurs at fork
IPL (see Section 10.2), a driver's interrupt service routine,
executing at device IPL, could interrupt the processing of a
timeout on the same device unit. For this reason, the driver's
interrupt service routine should check the interrupt-expected
bit (UCB$V_INT) before handling the interrupt. VMS clears
this bit before it calls the driver's timeout handler.
4

Obtains device-status or controller-status information from the device
registers, if necessary, and stores the status information in the UCB.

Places the contents of UCB$L_FR3 and UCB$L_FR4 in R3 and R4,
respectively.

Issues a JSB instruction to the waiting driver's PC address, which is
saved in the UCB fork block at UCB$L_FPC.

The restored driver should execute as briefly as possible in interrupt
context. As soon as possible, the driver should invoke the IOFORK macro
to request the creation of a fork process at the driver's fork IPL. It must
do this in order to complete the I/O operation. Forking lowers the IPL
of driver execution below device IPL, allowing the processor to service
additional device interrupts. IOFORK calls the routine EXE$IOFORK.
EXE$IOFORK inserts into the appropriate fork queue the UCB fork block
that describes the driver process. It then returns control to the driver's
interrupt service routine. (See Section 10.1.1 for additional information on
driver forking.)
The interrupt service routine then performs the following steps:

9.3

Removes the IDB pointer from the stack

Issues the DEVICEUNLOCK macro to release ownership of the device
lock

Restores RO through R5

Dismisses the interrupt with an REI instruction

Servicing an Unsolicited Interrupt
A device requests an interrupt to indicate to a driver that the device has
changed status. If a driver's fork process starts an I/O operation on a
device, the driver expects to receive an interrupt from the device when the
I/O operation completes or an error occurs.

9-4

Writing an Interrupt Service Routine
9.3 Servicing an Unsolicited Interrupt

Other changes in the device's status occur when the device has not
been activated by a device driver. The device reports such a change by
requesting an unsolicited interrupt. For example, when a user types
on a terminal, the terminal requests an interrupt that is handled by
the terminal driver. If the terminal is not attached to a process, the
terminal driver causes the login procedure to be invoked for the user at
the terminal.
As another example, an unsolicited interrupt occurs whenever a disk drive
goes off line, as could happen when an operator spins it down or pushes
the offline button. The disk driver services the interrupt by altering
volume and unit status bits in the disk device's UCB.
Devices request unsolicited interrupts because some external event
has changed the status of the device. A device driver can handle these
interrupts in two ways:
•

Ignore the interrupt as spurious

•

Examine the device registers and take action according to their
indications of changed status, and then poll for any other changes
in device status

As mentioned in Section 9.2, an interrupt service routine first obtains
the address of the device's UCB from the IDB. It then issues the
DEVICELOCK macro to obtain synchronized access to device registers.
The routine determines whether an interrupt is solicited or not by
examining the interrupt-expected bit in the UCB status longword
(UCB$V_INT in UCB$L_STS). All UNIBUS, Q22 bus, and generic VAXBI
device drivers must use this method to determine whether or not an
interrupt is solicited; the address of the unsolicited interrupt service
routine, specified in the driver dispatch table, is used only by MASSBUS
drivers (see Sections 15.4 and 15.6).
If the interrupt is unsolicited, the driver can reject the interrupt with the

following code sequence:
1

Remove the IDB pointer from the stack

Restore RO through R5

Dismiss the interrupt with an REI instruction

If the driver decides to handle the unsolicited interrupt, it must observe

certain precautions. Certain methods of servicing unsolicited interruptsfor instance sending a message to the operator or the job controller's
mailbox-must be accomplished at an IPL lower than device IPL. Although
the interrupt service routine can legitimately fork to accommodate
unsolicited interrupts, it should exercise extreme caution in doing so.
If UCB$V_BSY is set in UCB$L_STS, the UCB fork block is currently in

use by the driver's start-I/O routine. An attempt by the interrupt service
routine to concurrently use the fork block can destroy the fork context
already stored in that UCB. Moreover, if UCB$V_BSY is not set, the
interrupt service routine cannot safely assume that the fork block is not
in use, for it may be currently employed to service a previous unsolicited
interrupt.

9-5

Writing an Interrupt Service Routine
9.3 Servicing an Unsolicited Interrupt

To avoid confusion, code servicing an unsolicited interrupt must ensure
that the fork block it requires is not being used. Perhaps the safest
method to guarantee this is for the driver to define a separate fork
block in a device-specific UCB extension. The driver should also define
a semaphore bit to control access to this fork block and protect against
multiple forking. Note that the driver should access the semaphore bit
using interlocked instructions (for example, BBSSI or BBCCI).
If, upon servicing an unsolicited interrupt, the driver's interrupt service
routine examines the semaphore and discovers that a fork is already in
progress (that is, the bit is set), it should not attempt to fork.
The VMS routine that creates the fork process (once these conditions are
satisfied) returns control to the interrupt service routine. The interrupt
service routine then releases the device lock, restores the saved registers,
and issues an REI instruction to dismiss the interrupt.

9.3.1

Examples of Unsolicited Interrupts
A card reader requests an unsolicited interrupt when a user puts the
reader on line. Once the card-reader driver's interrupt service routine
determines that the interrupt is unsolicited, the routine analyzes the
interrupt, as in the following code example.
Because only one sequence of instructions can use the UCB as a fork block,
the interrupt service routine performs the following steps before it creates
the fork process:
•

Ensures that no one is using the device, and that no one wants to use
it, by determining that the reference count (UCB$W_REFC) is zero.

•

Ensures that it is not already using the UCB, to create a fork process
in order to lower IPL and to send a message to the job controller, by
testing the job-attached bit (UCB$V_JOB in UCB$W_DEVSTS).

CR$INT::
MOVL
MOVQ

@(SP)+,R3
IDB$L_CSR(R3),R4

;Get address of IDBt»
;Get controller CSR and owner UCB
; address8

DEVICELOCK LOCKADDR=UCB$L_DLCK(R5),PRESERVE=NO,CONDITION=NOSETIPL
;Obtain device locktl
BBCC
#UCB$V_INT,UCB$L_STS(R5),10$ ;If clear, interrupt not expected~

UNSOLICITED INTERRUPT
10$:

MOVZWL
MOVZBW
BITW
BEQL
TSTW
BNEQ
BBSS
BSBB

9-6

CR_CSR(R4),RO
;Get reader status
#CR_CSR_M_IE,CR_CSR(R4)
;Clear status, enable interrupts~
#CR CSR M ONLINE,RO
;Reader transition to online?(t
20$- ;If equal no
UCB$W_REFC(R5)
;Device assigned or allocated?fl
20$
;If not equal yes
#UCB$V_JOB,UCB$W_DEVSTS(R5),20$
;If set, message already sentfD
30$
;Send message to job controller

Writing an Interrupt Service Routine
9.3 Servicing an Unsolicited Interrupt

20$:

30$:

40$:

DEVICEUNLOCK LOCKADDR=UCB$L_DLCK(R5),PRESERVE=NO
;Release device lock
(SP)+, RO
;Restore registers
MOVQ
MOVQ
(SP)+, R2
MOVQ
(SP)+, R4
REI
;Create fork processCD
FORK
;Set message typel)
MOVZBL #MSG$ CRUNSOLIC,R4
GASYS$AR JOBCTLMB,R3
;Set address of job controller mailbox
MOVL
GAEXE$SNDEVMSG
;Sent message to job controller
JSB
;If LBS successful notification41
R0,40$
BLBS
;Clear message sent bit'9
BICW
#UCB$M_JOB,UCB$W_DEVSTS(R5)
RSB

8 The interrupt service routine obtains the address of the IDB from the
top of the stack.

8 By means of this action, it obtains the address of the control and
status register (CSR) in R4 and restores the address of the UCB in
R5. 1

e It issues a DEVICELOCK macro to secure synchronized access to
device registers and UCB fields.

8 It checks for an unsolicited interrupt by testing the interrupt expected
bit in the UCB status longword.

0 Because the interrupt is unsolicited, the routine clears all CSR bits
except for the interrupt-expected bit.
C) It confirms that the reader was just placed on line by examining a

saved copy of the CSR.

8 It examines the reference count field of the device's UCB (UCB$W_
REFC) to determine whether a process has allocated the device or
assigned a channel to it.
@) If the reference count is zero, the interrupt service routine tests the

job-attached bit in the device-dependent status field (UCB$V_JOB
in UCB$W_DEVSTS) to make sure it has not already sent the job
controller a message about the card reader being placed on line.

CD If the job-attached bit is not set, the routine sets the bit and creates a
fork process to send the message to the job controller, using the system
routine EXE$SNDEVMSG (described in the VMS Device Support
Reference Manual). It is necessary to lower IPL from device IPL by
forking at this point because EXE$SNDEVMSG expects its caller's IPL
to be no greater than IPL$_MAILBOX.
When the interrupt service routine regains control, it releases the device
lock, restores RO through R5 and dismisses the interrupt with an REI
instruction. (The interrupt service routine removed the IDB pointer
from the stack earlier in its execution in order to obtain CSR and UCB
addresses.)

Because the card reader has a dedicated controller, the IDB$L_OWNER field always points to the UCB for
the si~gle unit:
OO(SP) ~ CRB ~ IDB ~ IDB$L_OWNER ~ UCB

9-7

Writing an Interrupt Service Routine
9.3 Servicing an Unsolicited Interrupt

8 When the fork process created at step 8 eventually executes, it writes a
message to the job controller's mailbox, indicating that the card reader
is on line.

e If the fork process successfully sends the message, it leaves the jobattached bit set to prevent the job controller from receiving any further
messages about the card reader's state. (The driver's cancel-I/O
routine later clears the bit.)

If the send-message request fails, the fork process clears the job-

attached bit so that if the card reader makes a subsequent state
change to on line, the interrupt service routine can attempt again to
send a message to the job controller.
Another example of unsolicited interrupt processing occurs in a device
driver for a multiunit controller. When a disk is placed off line, the disk
drive hardware requests an interrupt. The driver interrupt service routine
must determine what device unit requested the interrupt, obtain status
information from the disk device's CSR, and then decide whether the
interrupt was solicited.
Because it must access device UCB fields and device registers, the
interrupt service routine first obtains the appropriate device lock. If
the interrupt is unexpected, it calls code that services the unsolicited
interrupt. This code checks the status of the volume, as described in the
following steps:
1

It sets a bit in the UCB to indicate that the unit is on line (UCB$V_
ONLINE in UCB$L_STS).

If the UCB's volume-valid bit is set (UCB$V_VALID in UCB$L_STS),

the routine tests the volume valid status bit in a device register to
determine whether the volume status has changed. If the volume is no
longer valid, the routine clears the UCB volume valid bit.
3

The routine returns control to the driver's interrupt service routine.

The driver's interrupt service routine then polls the other device units on
the controller to determine whether any other units requested interrupts
while the first interrupt was being processed. When no unit requires
interrupt servicing, the routine removes the IDB pointer from the stack,
releases the device lock, restores registers RO through R5, and dismisses
the interrupt with an REI instruction.

9-8

10 Completing an 1/0 Request and Handling 'Timeouts
Once a driver has activated the device and invoked the wait-for-interrupt
macro, the driver remains suspended until the device requests an interrupt
or times out.
If the device requests an interrupt, the driver's interrupt service routine

handles the interrupt and then reactivates the driver at the instruction
following the wait-for-interrupt macro. The reactivated driver performs
device-dependent I/O postprocessing.
If the device does not request an interrupt within the designated time
interval, the system transfers control to the driver's timeout handling
routine. The address of the timeout handling routine is specified as the
excpt argument to the wait-for-interrupt macro.

10.1

1/0 Postprocessing
Once the driver interrupt service routine has processed an interrupt, it
transfers control to the driver by issuing a JSB instruction. At this point,
the driver is executing in interrupt context. If the driver were to continue
executing in interrupt context, it would lock out most other processing on
the processor including the handling of hardware interrupts.
To restore the driver to the context of a driver fork process, the driver
invokes the VMS macro IOFORK. Once the fork process has been created
and dispatched for execution, it executes the driver code that completes
the processing of the I/O request.

10.1.1

EXE$10FORK
IOFORK generates a call to the routine EXE$IOFORK. EXE$IOFORK
converts the driver context from that of an interrupt service routine to
that of a fork process by performing the following steps:
1

It disables software timeouts by clearing the timeout enable bit in the
UCB status longword (UCB$V_TIM in UCB$L_STS).

It saves R3 and R4 of the current driver context in the UCB fork block

(UCB$L_FR3 and UCB$L_FR4).
3

It saves the current driver PC in the UCB fork block (UCB$L_FPC).

(The driver PC is the top longword on the stack, as a result of the JSB
to EXE$IOFORK.)
4

It obtains the fork lock index of the driver from the UCB (UCB$B_

FLCK) and uses it to determine in which fork queue it should place
the fork block.
5

It inserts the address of the UCB fork block (R5) into the processorspeci:fi.c fork queue corresponding to the driver's fork IPL.
10-1

Completing an 1/0 Request and Handling Timeouts
10.1 110 Postprocessing

Finally, if the fork block is the first entry in the fork queue,
EXE$IOFORK requests a software interrupt from the local processor
at the driver's fork IPL.

The steps listed previously move the fork process's context into the UCB's
fork block. They save R3 through R5 and the driver's PC address. The
driver's fork process resumes processing when the VMS fork dispatcher
dequeues the UCB fork block from the fork queue, and reactivates the
driver at the driver's fork IPL.

10.1.2

Completing an 1/0 Request
When VMS reactivates a driver's fork process by dequeuing the fork block,
the driver resumes processing of the 1/0 operation holding the appropriate
fork lock at fork IPL. Generic VAXBI devices perform whatever devicedependent operations are needed to prepare an 1/0 request for completion.
If the device has completed the 1/0 operation without errors, a UNIBUS or
Q22 bus driver for a DMA device proceeds as follows:
1

Purges the data path

Releases the buffered data path (applies only to UNIBUS DMA device
drivers)

Releases map registers

Releases the controller (applies only to drivers of devices on multiunit
controllers)

Checks device register images saved in the UCB to determine the
status of the 1/0 operation

Saves in the IRP the status code, transfer count, and device-dependent
status that is to be returned to the user process in an 1/0 status block

Returns control to the operating system

The first three steps apply to UNIBUS or Q22 bus DMA transfers only
and are discussed in Section 14.2. The following sections describe the last
steps.
10.1.2.1

Releasing the Controller

To release the controller channel, the driver code invokes the VMS macro
RELCHAN. RELCHAN calls the VMS routine IOC$RELCHAN. If another
driver is waiting for the controller channel, IOC$RELCHAN grants that
driver's fork process the channel, restores its context from the UCB fork
block, and transfers control to the saved PC. When no more drivers are
awaiting the channel, IOC$RELCHAN returns control to the fork process
that released the channel.
Drivers for devices with dedicated controllers need not release the
controller's data channel (as discussed in Sections 8.3.1 and 11.1). By
means of code in the unit initialization routine, these drivers set up the
device's UCB so that the device owns the controller permanently.
Drivers must be executing at driver's fork IPL when they invoke
RELCHAN or call IOC$RELCHAN.
10-2

Completing an 1/0 Request and Handling Timeouts
10.1 110 Postprocessing

10.1.2.2

Saving Status, Count, and Device-Dependent Status

To save the status code, transfer count, and device-dependent status, the
driver performs the following steps:

10.1.2.3

Loads a success status code (SS$_NORMAL), or whatever is
appropriate, into bits 0 through 15 of RO.

Loads the number of bytes transferred into the high-order 16 bits of
RO (bits 16 through 31), if the 1/0 operation performed by the device is
a transfer function.

Loads device-dependent status information, if any, into Rl .1

Returning Control to the Operating System

Finally, the driver fork process returns control to the system by invoking
the REQCOM macro to complete the 1/0 request. REQCOM issues a JMP
instruction to the VMS routine IOC$REQCOM. IOC$REQCOM locates the
address of the I/O request packet (IRP) corresponding to the 1/0 operation
in the device's UCB (UCB$L_IRP). It then writes the two longwords of
completion status contained in RO and Rl into the media field of the IRP
(IRP$L_MEDIA and IRP$L_MEDIA+4).
IOC$REQCOM then inserts the IRP in the local processor's 1/0postprocessing queue and requests a software interrupt at IPL$_IOPOST
from the local processor so the postprocessing begins when IPL drops
below IPL$_IOPOST.
If the error-logging bit is set in the device's UCB (UCB$V_ERLOGIP in

UCB$L_STS), IOC$REQCOM obtains the address of the error message
buffer from the UCB (UCB$L_EMB). It then writes the following
information into the error buffer:
•

Final device status (UCB$W_DEVSTS)

•

Final error count (UCB$B_ERTCNT)

•

Maximum error retry count for the driver

•

Two longwords of completion status (RO and Rl)

To release the error message buffer, IOC$REQCOM calls
ERL$RELEASEMB. Section 11.3 describes error logging in more detail.
If any IRPs are waiting for driver processing, IOC$REQCOM dequeues

an IRP from the head of the queue of packets waiting for the device unit
(UCB$L_IOQFL), and transfers control to IOC$INITIATE. IOC$INITIATE
initiates execution of this 1/0 request in the driver's fork process, by
activating the driver's start-1/0 routine, as described in Section 4.2.1.
Otherwise, IOC$REQCOM clears the unit-busy bit in the device's UCB
status longword (UCB$V_BSY in UCB$L_STS) and tnnsfers control to
IOC$RELCHAN to release the controller channel in case the driver failed
to do so. I OC$RELCHAN, in turn, returns control to the caller of the
driver fork process (if the fork process issued the REQCOM macro). This
is generally the VMS fork dispatcher. The fork dispatcher releases the
1

RO and Rl are the status values that VMS returns to the user process in the I/O status block specified in
the original $QIO system service.

10-3

Completing an 1/0 Request and Handling Timeouts
10.1 1/0 Postprocessing

fork lock, restores saved registers, and dismisses the fork IPL software
interrupt with an REI instruction.
The remaining steps in processing the 1/0 request are performed by VMS
1/0 postprocessing. (See Section 4.3.1 for additional information.)

10.2

Timeout Handling Routines
VMS transfers control to the driver's timeout handling routine if a device
unit does not request an interrupt within the time limit specified in the
invocation of the wait-for-interrupt macro. Among its other activities, the
VMS software timer interrupt service routine, having raised IPL from
IPL$_TIMERFORK to IPL$_SYNCH, scans UCBs once every second to
determine whether a device has timed out.
When the software timer interrupt service routine locates a device that
has timed out, the routine calls the driver's timeout handling routine by
performing the following steps:
1

It obtains both the fork lock and the device lock associated with the

device unit to synchronize access to its fork database and device
database. It raises IPL to device IPL as a result of obtaining the
device lock.

It raises IPL on the local processor to IPL$_POWER to block local
power failure servicing.

It disables expected interrupts and timeouts on the device by clearing

bits in the status field of the device's UCB (UCB$V_INT and UCB$V_
TIM in UCB$L_STS).
4

It sets the device-timeout bit in the UCB status field (UCB$V_
TIMOUT in UCB$L_STS).

It lowers IPL to hardware device interrupt IPL (UCB$B_DIPL).

It restores the saved R3 and R4 of the driver's fork process from the
UCB fork block (UCB$L_FR3 and UCB$L_FR4).

It restores R5 (address of the UCB fork block).

It computes the address of the driver's timeout handling routine from
the saved PC in the UCB fork block (UCB$L_FPC).

It transfers control to the driver's timeout handling routine.

The driver's timeout handling routine executes in the following context:

10-4

•

RO through R5 are saved on the stack.

•

R5 contains the address of the UCB for the device that timed out.

•

Only system address space may be accessed.

•

The processor is running in kernel mode.

•

The processor is running on the interrupt stack.

Completing an 1/0 Request and Handling Timeouts
10.2 Timeout Handling Routines

•

The processor holds both fork lock and device lock.

•

IPL is at hardware device interrupt level.

A timeout handling routine returns control to the software timer interrupt
service routine by issuing an RSB instruction. The driver's fork process
eventually regains control, with R3 and R4 restored from UCB$L_FR3 and
UCB$L_FR4.
Certain timeout handling routines may find it useful to fork to execute low
priority code or to accomplish certain tasks, such as the restarting of an
1/0 request (see Section 10.2.1). If a driver uses this method, its interrupt
service routine should check the interrupt-expected bit (UCB$V_INT)
before handling the interrupt. The operating system clears this bit before
it calls the driver's timeout handling routine. This allows the routine to
determine whether device-timeout processing is in progress at fork IPL.
During recovery from a power failure, VMS forces a device timeout by
altering the timeout field (UCB$L_DUETIM) of a UCB if that device's
UCB records that the unit is waiting for an interrupt or timeout (UCB$V_
INT and UCB$V_TIM set in UCB$L_STS). The timeout handling routine
can perceive that recovery from a power failure is occurring by examining
the power bit (UCB$V_POWER in UCB$L_STS) in the UCB.
A timeout handling routine usually performs one of three functions:

10.2.1

•

It retries the 1/0 operation unless a retry count is exhausted.

•

It aborts the 1/0 request, returning status (for instance, SS$_
TIMEOUT) in RO.

•

It sends a message to an operator mailbox and waits for a subsequent
interrupt or timeout.

Retrying an 1/0 Operation
Some devices might retry an 1/0 operation after a timeout. For example, a
disk driver's timeout handling routine might take the following steps after
a transfer timeout:
1

Invokes the FORK macro to lower IPL to fork level.

Releases any owned map registers, data path, and controller data
channel.

Determines whether it is possible to retry the 1/0 operation.

Examines the error retry count (UCB$B_ERTCNT) to determine
whether it is possible to retry the 1/0 operation.
If the retry count is exhausted, the timeout handling routine sets the
error code, performs a normal abort 1/0 cleanup operation, and issues
the REQCOM macro to complete the 1/0 request.
If the retry count is not exhausted, the routine proceeds to the next
step.

10-5

Completing an 1/0 Request and Handling Timeouts
10.2 Timeout Handling Routines

Examines the power bit (UCB$V_POWER in UCB$L_STS) to
determine if it must take special steps before retrying the operation.
For instance, the timeout handling routine should load the address
of the IRP into R3 and reload the following fields of the IRP into
the corresponding UCB fields, if they have been altered by partial
processing of the 110 request:
IRP$L_BCNT
IRP$W_BOFF
IRP$L_SVAPTE
These actions set up an environment in which the transfer can be
retried from the beginning.

10.2.2

Calls ERL$DEVICTMO to log the device timeout if the driver supports
error logging (see Section 6.2).

Decreases the error retry count (UCB$B_ERTCNT).

Clears the UCB timeout bit (UCB$V_TIMOUT) in UCB$L_STS.

Branches to the start-110 routine to retry the operation.

Aborting an 1/0 Request
A driver's timeout handling routine aborts the 110 request when it
exhausts its retry count or when, having read device registers, the driver
determines that some fatal error condition has occurred such that there
is no point in retrying the request. Similarly, the routine aborts a request
if the device's cancel-110 bit (UCB$V_CANCEL in UCB$L_STS) is set,
signifying that a cancel-110 request was made.
To abort an 110 request, a timeout handling routine performs the following
sequence of steps:
1

Clears the device control and status register (CSR), if appropriate to
the device and controller

Invokes the FORK macro to lower IPL to fork level

Releases any owned map registers, data path, and controller data
channel

Loads the abort status code (SS$_ABORT) into the low word of RO

Clears bits 16 through 31 in RO to indicate that no data was
transferred

Issues the REQCOM macro to complete the request

10.2.3 Sending a Message to the Operator
The following sequence describes a timeout handling routine that sends
a message to the operator's mailbox and then goes back into a wait-forinterrupt or timeout state on the presumption that subsequent human
intervention will make the device operational:

10--6

Completing an 1/0 Request and Handling Timeouts
10.2 Timeout Handling Routines

The timeout handling routine invokes the FORK macro to lower IPL to
driver fork level.

It checks the cancel-I/Obit in the UCB status longword (UCB$V_

CANCEL in UCB$L_STS).
IfUCB$V_CANCEL is set, the timeout handling routine can abort the
request. However, if UCB$V_CANCEL is clear, the timeout handling
routine performs the following actions:

a. Saves R3 and R4 on the stack.

b. Loads an OPCOM message code, such as MSG$_DEVOFFLIN, into
R4. Note that the driver must invoke the message definition macro
$MSGDEF (located in SYS$LIBRARY:STARLET.MLB) to use these
message codes.

c. Loads the address of the operator's mailbox (a pointer to which is
located at SYS$AR_OPRMBX) into R3.
d. Calls a VMS routine to place the message in the operator's
mailbox, as follows:
JSB

GAEXE$SNDEVMSG

e. Restores R3 and R4.
f.

Invokes the DEVICELOCK macro to raise IPL to device IPL and
obtain the associated device lock.

g. Issues a SETIPL macro to raise IPL$_POWER and prevent power
failure interrupts on the local processor.
h. Invokes the WFIKPCH macro to wait for another interrupt or
timeout.

When the OPCOM process reads the message in its mailbox, it sends the
requested message, in this case "device-offline," to all operator terminals
enabled for that device class.

10-7

Other Driver Routines

Drivers normally contain initialization, cancel-I/O, error logging, and
register dumping routines. The driver prologue table specifies the
addresses of the unit and controller initialization routines. 1 The driver
dispatch table (DDT) contains the addresses of the cancel-I/O, error
logging, and register dumping routines. The type of device determines
which of these routines are required in a driver.
Drivers more rarely require a driver unloading routine, cloned UCB
routine, or unit delivery routine. VMS, however, provides a method for
specifying these routines in the DPT or DDT. A brief discussion of the
driver unloading routine appears in Section 12.2.3. Section 11.4 describes
the functions of a cloned UCB routine. A description of the unit delivery
routine appears in Section 12.4.2.

11.1

Initialization Routines
Most device controllers and device units require initialization both when
the corresponding device driver is loaded and when the operating system is
recovering from a power failure. At these times, the duty of initialization
routines is to prepare controllers and device units for operation, according
to their characteristics.
The VMS operating system always calls controller and unit initialization
routines with IPL raised to IPL$_POWER. The high IPL prevents any
interrupts from reaching the local processor while initialization is
occurring; for this reason, initialization routines should only contain
code that is absolutely needed at initialization time. Initialization
routines should not explicitly lower IPL. The system calls initialization
routines with a JSB instruction; the routines return by executing an RSB
instruction.

11.1.1

Controller Initialization Routine
The duties of a controller initialization routines depend on the
characteristics of the device. For example, a controller initialization
routine for a card reader might enable interrupts from the device by
setting the interrupt-enable bit in the device's control and status register
(CSR). A disk's controller initialization routine, on the other hand, might
enable interrupts and initialize all unit-status registers. A controller
initialization routine can typically perform any of the following tasks:
•

Determine if it is being called during power failure recovery by
examining the power bit (UCB$V_POWER in UCB$L_STS) in the

A MASSBUS device driver must specify the address of its unit initialization routine in the driver dispatch
table (using the unitinit argument to the DDTAB macro as discussed in Section 6.2). UNIBUS, Q22 bus,
and generic VAXBI device drivers can specify the address in either the DPT or DDT.

11-1

Other Driver Routines
11.1 Initialization Routines

UCB. A controller initialization routine may want to perform or avoid
specific tasks during power failure recovery (see Section 11.1.4).
•

Clear error-status bits in device registers.

•

Initiate a device operation, such as clearing a drive or acknowledging
a disk pack.

•

Enable controller interrupts.

•

If the controller is dedicated to a single-unit device, such as a printer,
fill in IDB$L_OWNER and set the online bit (UCB$V_ONLINE in
UCB$L_STS).

•

Permanently allocate driver resources, such as
UNIBUS/Q22 bus map registers (see Section 14.2.2.2)
UNIBUS buffered data path (see Section 14.2.1.2)

•

Allocate a buffer from nonpaged system dynamic memory.

Note that the permanent allocation of driver resources and the allocation
of nonpaged pool require that the controller initialization routine fork
to the driver's fork IPL. This action warrants careful coordination of
the activities of the controller and unit initialization routines, both
with each other and with the System Generation Utility (SYSGEN).
See Section 11.1.5 for a discussion of forking in an initialization routine.
The controller initialization routine for a generic VAXBI device driver
must initialize the device-specific aspects of the VAXBI device. Hardware
initialization might include such activities as writing values to BIIC
and device-specific registers, examining the results of the BIIC self-test,
mapping a node's window space, building data structures to control the
device, and linking these structures into chains of similar data structures.
(Section 16.5 extensively discusses the means by which a driver's controller
initialization routine performs these tasks.)
At the time of a call to a controller initialization routine, the following
registers contain the listed values:
Register

Value

Address of CSR

Address of IDB that describes the controller

Address of DDB associated with the controller

Address of CRB for the controller

A controller initialization routine must preserve the contents of all
registers except RO, Rl, and R2.

11-2

Other Driver Routines
11.1 Initialization Routines

11.1.2

Unit Initialization Routine
A unit initialization routine is useful for initializing device-dependent
fields in the UCB. For example, a unit initialization routine for a disk can
also specify disk-drive geometry (such as number of cylinders) in the UCB
and wait for online units to spin up to speed. Unit initialization routines
must set the online bit in the UCB (UCB$V_ONLINE) to declare the unit
to be on line.
A unit initialization routine can perform the same types of tasks as a
controller initialization routine (see Section 11.1.1 ). Generally, the driver
for a single-unit controller does not need a unit initialization routine.
At the time of a call to a unit initialization routine, the registers contain
the following values:
Register

Value

Address of primary CSR

Address of secondary CSR; R4 is equal to R3 if there is no secondary
CSR

Address of the device's UCB

A unit initialization routine must preserve the contents of all registers
except RO, Rl, and R2.

11.1.3

Initialization Duri.ng Driver Loading
Prior to calling the initialization routines within a driver, VMS takes steps
to initialize the .appropriate I/O database structures and establish the
appropriate links between these data structures and the driver. First,
during system initialization, VMS creates an ADP for the device adapter.
For generic VAXBI devices and MASSBUS devices, VMS creates an
ADP, CRB, and IDB for the device at this time. Secondly, during driver
loading, VMS performs some additional initialization. Finally, the driver's
initialization routines are given an opportunity to initialize the device in a
device-specific manner.
The extent of the initialization VMS performs during driver loading
depends upon whether the 1/0 database is being created, and whether the
driver is being loaded for the first time or is replacing a driver that was
previously loaded.
The SYSGEN commands LOAD, AUTOCONFIGURE, and CONNECT add
new drivers to the system configuration. The RELOAD command unloads
an existing version of a driver and replaces it with a new one.
The LOAD command loads the driver into nonpaged system memory but
does not call any driver-specific routines nor execute any initialization
requests specified in DPT_STORE macro invocations nor create all of the
I/O data structures associated with the device.

11-3

Other Driver Routines
11.1 Initialization Routines

The AUTOCONFIGURE and CONNECT commands create and initialize
I/O database structures associated with the device driver, call driverspecific initialization routines, and perform requests specified in DPT_
STORE macro invocations. For each new device they add to the system,
AUTOCONFIGURE and CONNECT perform the following steps:
•

Create a UCB for the device. If this is the first occurrence of device
and controller name, the commands create a DDB, CRB, and an
IDB. (Because the CRB and IDB for a generic VAXBI device driver
or MASSBUS device driver have already been created by the VMS
adapter initialization routine, a CONNECT or AUTOCONFIGURE
command for such a device never creates these structures.)

•

Perform the initialization operations specified by the DPT_STORE
macros within the initialization and reinitialization portions of the
DPT.

•

Relocate all addresses in the DDT and FDT to system virtual
addresses.

•

Call the controller initialization routine specified in the CRB, if it has
created a CRB (or if CRB$V_UNINIT is set in CRB$B_MASK for a
generic VAXBI device).

•

Call the unit initialization routine (if any) specified in the DDT. If no
routine exists in the DDT, call the unit initialization routine (if any)
specified in the CRB.

The AUTOCONFIGURE and CONNECT command operations raise IPL to
IPL$_POWER before calling the driver's initialization routines.
The RELOAD command replaces an existing driver with a new driver. The
command loads the new driver's code into nonpaged system memory.
Unlike the other SYSGEN commands for driver loading, RELOAD
assumes that the data structures associated with the driver already
exist, and thus updates the I/O database to reflect the modified code and
its different location in system virtual address space. It performs the
following functions:
•

Calls the driver unloading routine in the old version of the driver, if
one exists (as indicated in the unload argument of the DPTAB macro)
and if bit DPT$V_NOUNLOAD in DPT$B_FLAGS is clear.
The driver unloading routine must return success status in RO for
SYSGEN to proceed with the following steps.

11-4

•

Deallocates the memory occupied by the old version of the driver.

•

Loads the new version of the driver.

•

Executes requests specified by DPT_STORE macro invocations in only
the reinitialization section of the DPT in the new driver.

•

Relocates all addresses in the FDT and DDT to system virtual
addresses.

•

Calls the controller initialization routine.

Other Driver Routines
11.1 Initialization Routines

Chapter 12 contains detailed descriptions of all SYSGEN commands
related to device drivers.

11.1.4

Initialization During Recovery from a Power Failure
During recovery from a power failure, the operating system locates every
UCB in the 1/0 database, by following the chain of pointers to all DDBs in
the system (starting at IOC$GL_DEVLIST and chained by DDB$L_LINK)
and the chain of pointers to all UCBs of the same device and controller
type (starting at DDB$L_UCB and chained by UCB$L_LINK). For each
UCB it finds, VMS performs the following procedure:
1

It locates the CRB associated with the UCB (UCB$L_CRB) and
determines whether a controller initialization routine exists for the
device's controller by examining CRB$L_INTD+VEC$L_INITIAL. If an
invocation of the DPT_STORE macro loaded the address of a controller
initialization routine into this field, VMS calls that routine.

It determines whether a unit initialization routine exists for the
particular device unit by examining the unit initialization field of the
DDT (DDT$L_UNITINIT). Ifthe field does not contain an address, the
system checks the CRB (CRB$L_INTD+VEC$L_UNITINIT). 2
If either the CRB or the DDT contains a nonzero address for such a

routine, the system calls the routine to initialize the device unit. The
system calls only one routine; if the DDT contains an address, the
address in the CRB is ignored.
When called during power failure recovery, driver initialization routines
must adhere to the following rules:
•

These routines cannot acquire any spin locks. Controller and unit
initialization routines are called at IPL 31 during power failure
recovery to reinitialize 1/0 devices before the processors are allowed to
proceed with execution at lower IPLs. Because processors may have
been holding spin locks at the time of the power failure, they will
not be able to release them until after they resume execution. As a
result, spin locks are not available to controller and unit initialization
routines.

•

They cannot perform any operation that requires the intervention of
other processors in a VMS multiprocessing system.

A driver initialization routine can determine if it is being called during
power failure recovery by examining the power bit (UCB$V_POWER in
UCB$L_STS) in the UCB.

MASSBUS drivers store unit initialization routines addresses only in the DDT.

11-5

Other Driver Routines
11.1 Initialization Routines

11.1.5

Forking from a Driver Initialization Routine
If a driver initialization routine must fork to perform a thread of code that

must synchronize with code or a structure synchronized at a lower IPL, it
must take special care to avoid breaking that synchronization.
First of all, because SYSGEN, under normal circumstances, immediately
calls a driver's unit initialization routine at IPL$_POWER after its
.
controller initialization completes, the unit initialization routine must
be prepared for the instance of a controller initialization routine that
forks. Such a unit initialization routine would complete before the fork
thread of the controller initialization routine resumed.
A fork thread in a unit initialization routine (or a controller initialization
routine in a driver without a unit initialization routine) must otherwise
take the following precautions to avoid breaking synchronization:

11.2

•

Use either the CRB fork block, or a fork block defined in a devicespecific extension to the UCB. The separate fork block prevents a
conflict with the use of the normal UCB fork block by the IOFORK
routine. If you are using a separate UCB fork block, you must not
attempt to allocate the fork block from paged pool.

•

You should use a semaphore bit to protect against multiple forking.
Remember that the unit initialization routine may be called repeatedly
if multiple power failures require servicing. If the semaphore shows
that a fork is in progress, then exit without attempting to fork. Access
the semaphore bit using interlocked instructions (for example, BBSSI
or BBCCI).

•

Invoke EXE$FORK with R5 pointing to the alternate fork block.
Restore the original value of R5 once the fork process is active.

•

Restore all registers on exit. Because EXE$FORK removes the caller's
address from the stack and returns to the caller's caller, the unit
initialization routine must set up a dummy caller's caller routine to
restore registers destroyed by EXE$FORK.

Cancel-1/0 Routine
VMS routines call a device driver's cancel-110 routine under the following
circumstances:

11-6

•

When a process issues a Cancel-1/0-on-Channel system service
($CANCEL)

•

When a process deallocates a device, causing the device reference
count (UCB$W_REFC) to become zero (that is, no process 1/0 channels
are assigned to the device)

Other Driver Routines
11.2 Cancel-1/0 Routine

•

When a process deassigns a channel from a device, using the
$DASSGN system service3

•

When VMS performs cleanup operations as part of image termination
by canceling all pending I/O requests for the image and closing all
image-related files open on process I/O channels

The VMS routine EXE$CANCEL locates the UCB for the device associated
with a process I/O channel from a pointer in the CCB, as follows:
channel index number -+ CCB -+ UCB
EXE$CANCEL performs the following steps:
1

Obtains the fork lock associated with the driver, thus raising IPL to
fork IPL.

Removes from the device's pending-I/0 queue all IRPs associated with
the process and that channel.

For a buffered-I/O read operation, clears the buffered-read function bit
(IRP$V_FUNC) in IRP$W_STS.

Sets the status code SS$_CANCEL in IRP$L_MEDIA.

Inserts the IRPs removed from the pending-I/0 queue into the
systemwide I/O postprocessing queue.

Requests a software interrupt from the local processor at IPL$_
IO POST.

Calls the cancel-I/O routine specified in the DDT of the associated
device driver (argument cancel to the DDTAB macro). EXE$CANCEL
locates the routine using the following chain of pointers:
UCB -+ DDT -+ cancel-I/O routine

The cancel-I/O routine gives the driver an opportunity to prevent further
device-specific processing of the I/O request currently being processed on
the device.

11.2.1

Context of a Cancel-1/0 Routine
When EXE$CANCEL calls the cancel-I/O routine, the local processor is at
driver fork IPL holding the associated fork lock. As a result, the cancel-I/O
routine can read and modify the device's UCB. Registers at the time of the
call contain the following values:

Note that if the call to $DASSGN deassigns the last channel to the device, the device driver's cancel-I/O
routine is called a second time. Channel deassignment and last channel deassignment are both potentially
significant events for certain devices. The former means, in effert.'. that a user has finished with a
device and the latter means that all users are finished with a devir.e~ The reason code for both events
is CAN$C_DASSGN. However, a driver's cancel-110 routine can distinguish between the two cases by
examining UCB$W_REFC.

11-7

Other Driver Routines
11.2 Cancel-110 Routine

Value

Channel index number.

Contents of UCB$L_IRP (address of current IRP, if any, for device).

Address of process control block (PCB) of process for which the
$CANCEL system service is being performed.

Address of device's UCB.

Reason for call to cancel the 1/0 request. Codes that signify the
reasons for cancellation are defined by the $CANDEF macro. Possible
values for RS include
CAN$C_CANCEL
Called by $CANCEL system service
CAN$C_DASSGN

Called by $DASSGN or $DALLOC system
service

If a cancel-I/O routine uses registers other than RO through R3, it must
save the registers and restore them before exiting.

Device drivers might want to base their cancel-I/O operation on whether
the cancel-I/O request is the result of a channel deassignment (CAN$C_
DASSGN). ·For example, the terminal driver cancels out-of-band AST
requests only if the call to its cancel-I/O routine results from a DeassignI/0-Channel ($DASSGN) system service call.

11.2.2

Drivers That Need No Cancel-1/0 Routine
Some devices do not need any device-dependent processing performed
for an I/O request; you can omit the cancel argument from the DDTAB
macro. In this case, the DDTAB macro expansion loads the address of the
VMS routine IOC$RETURN into the appropriate position in the DDT. The
routine IOC$RETURN executes a single RSB instruction.

11.2.3

Device-Independent Cancel-1/0 Routine
Drivers can specify the VMS routine IOC$CANCELIO as the value of
the cancel argument in the DDTAB macro invocation. IOC$CANCELIO
cancels I/Oto a device in the following device-independent manner:
1

It confirms that the device is busy by examining the device-busy bit in
the UCB status longword (UCB$V_BSY in UCB$L_STS).

It locates the process-identification field in the IRP currently being
processed on the device by using the following chain of pointers:
UCB ~ IRP ~ process identification field
IOC$CANCELIO confirms that the field (IRP$L_PID) contains the
same value as the corresponding field in the PCB (PCB$L_PID).

11-8

It confirms that the specified channel-index number is the same as the
value stored in the IRP's channel-index field (IRP$W_CHAN).

Other Driver Routines
11.2 Cancel-1/0 Routine

11.2.4

It sets the cancel-1/0 bit in the UCB status longword (UCB$V_
CANCEL in UCB$L_STS). Other driver routines, such as the timeout
handling routine, check the cancel-1/0 bit to determine whether to
retry the 1/0 operation or abort it. (See Section 10.2.2 for additional
information.)

Device-Dependent Cancel-110 Routine
Drivers that include their own cancel-1/0 routines must perform the
first three steps of IOC$CANCELIO listed in Section 11.2.3 to determine
whether the 1/0 request being processed originates from the process
canceling 1/0 on a channel. If the three checks succeed, the cancel-1/0
routine can proceed in a device-specific manner. For instance, a cancel-1/0
routine may perform the following tasks:

11.3

•

Clear UCB$V_INT and UCB$V_TIM in the UCB status longword
(UCB$L_STS)

•

Release any owned map registers, data path, and controller data
channel

•

Load a status code (SS$_CANCEL, for instance) into the low word of
RO

•

Load other status information into the high word of RO and the
longword of Rl

•

Issue the REQCOM macro to complete the request

Error Logging Routines
A driver that supports error logging must satisfy the following
prerequisites:
•

It must invoke the data structure definition macro $EMBDEF (located
in SYS$LIBRARY:LIB.MLB).

•

It must use the local disk extension or local tape extension of the
UCB. These extensions include error-log extension. (See the data
structures in the VMS Device Support Reference Manual for additional
information.)

•

It must provide a means whereby error logging can be enabled for
the device. For instance, it can use the DPT_STORE macro to set the
device characteristic DEV$V_ELG in UCB$L_DEVCHAR or it can
support an IO$_SETCHAR function that sets this bit.

•

It must ensure that the size of the error log buffer, as specified in
DDT$W_ERRORBUF, is large enough to accommodate EMB$L_DV_
REGSAV+4, plus one longword for each register to be dumped. It must
specify this value in the erlgbf argument to the DDTAB macro.

•

It should include a register dumping routine, specifying its address in
the regdmp argument of the DDTAB macro.

11-9

Other Driver Routines
11.3 Error Logging Routines

•

11.3.1

It must complete the servicing of the I/O request by invoking the
REQCOM macro. (Routines, like ERL$DEVICEATTN, that log errors
that are not associated with the current 1/0 request skip this step.)
IOC$REQCOM takes steps to complete the error logging initiated by a
call to an error logging routine.

Error Logging Routines Supplied by VMS
The VMS operating system provides the following routines that drivers
can call to allocate and fill an error message buffer after a device error or
timeout occurs:
Routine

Function

ERL$DEVICERR

Logs an error associated with the 1/0 request in progress

ERL$DEVICTMO

Logs a timeout associated with the 1/0 request in progress

ERL$DEVICEATIN

Logs an error not associated with an 1/0 request

These routines are described in full in the VMS Device Support Reference
Manual, but they all perform similar functions, as follows:

11-10

•

Increment UCB$W_ERRCNT to record a device error. If the error-login-progress bit (UCB$V_ERLOGIP in UCB$L_STS) is set, the routine
returns control to its caller (ERL$DEVICERR and ERL$DEVICTMO
only).

•

Allocate from the current error log allocation buffer an error message
buffer of the length specified in the device's DDT (in argument erlgbf
to the DDTAB macro).

•

Initialize the buffer with the current system time, error log sequence
number, and error type code. These routines use the following error
type codes:
Routine

Error Code

ERL$DEVICERR

Device error {EMB$C_DE)

ERL$DEVICTMO

Device timeout {EMB$C_DT)

ERL$DEVICEATIN

Device attention {EMB$C_DA)

•

Place the address of the error message buffer in UCB$L_EMB.

•

Set UCB$V_ERLOGIP in UCB$L_STS.

•

Load into RO the address of the location in the buffer in which the
contents of the device registers are to be stor~d.

•

Call the driver's register dumping routine.

Other Driver Routines
11.3 Error Logging Routines

11.3.2

Register Dumping Routine
A driver that supports error logging or diagnostics specifies the address
of a register dumping routine in the regdmp argument to the DDTAB
macro.
When an error logging routine passes control to the driver's register
dumping routine, the following registers contain the listed values:
Register

Value

Address of buffer into which a register dumping routine copies the
contents of device registers

Address of device's CSR (if the driver invoked the WFIKPCH macro to
wait for an interrupt or timeout)

Address of UCB

The register dumping routine preserves the contents of all registers except
RO through R2. If it uses the stack, the register dumping routine must
restore the stack before passing control to another routine, waiting for an
interrupt, or returning control to its caller.
A register dumping routine uses the following procedure to fill the
indicated buffer:
1

Writes a longword value representing the number of device registers to
be written into the buffer.

Moves device register longword values into the buffer following the
register count longword.
The source of these register values depends upon the nature of the
driver. If the driver has established a UCB extension, its interrupt
service routine can copy to it the values of critical device registers.
In this case, the register dumping routine may contain instructions
similar to the following:
MOVL

UCB$L_TD_STATUS(R5), (RO)+

Alternatively, the register dumping routine can obtain device register
values directly from 1/0 address space, offsetting from the address of
the CSR as follows:
MOVZWL TD_STATUS(R4), (RO)+

Note that this latter method is not truly accurate in that, at the time
a register dumping routine runs, all or some device registers may have
been modified during the servicing of device interrupts unrelated to
the error.
When a driver fork process invokes the system routine IOC$DIAGBUFILL,
as described in the VMS Device Support Reference Manual, the routine
transfers control to the register dumping routine with the address of the
diagnostic buffer in RO, the address of the device's CSR in R4, and the
address of the UCB in R5.

11-11

Other Driver Routines
11.3 Error Logging Routines

11.3.3

Interpreting Error Log Entries
See the Guide to Maintaining a VMS System and the VMS Error Log
Utility Manual for help with producing and reading error log files.

11.4

Cloned UCB Routine
EXE$ASSIGN calls the driver's cloned UCB routine when an Assign I/O
Channel system service request ($ASSIGN) specifies a template device
(that is, bit UCB$V_TEMPLATE in UCB$L_STS is set). EXE$ASSIGN
does not assign the channel to the template device itself. Rather, it creates
a copy of the template device's UCB and ORB, initializing and clearing
certain fields as appropriate.
A cloned UCB routine receives control at IPL$_ASTDEL in kernel mode
with process context available, holding the I/O database mutex (IOC$GL_
MUTEX).
Only drivers for network devices or template devices, such as mailboxes,
include a cloned UCB routine. A driver specifies the address of a cloned
UCB routine in the cloneducb argument of the DDTAB macro.
The driver's cloned UCB routine verifies the contents of fields in the UCB
and ORB and completes their initialization. When a cloned UCB routine
is called, the following locations contain the listed values:
Location

11-12

Contents

SS$_NORMAL

Address of cloned UCB

Address of DDT

Address of current PCB

Address of template UCB

UCB$L_FQFL(R2)

Address of UCB$L_FQFL(R2)

UCB$L_FQBL(R2)

Address of UCB$L_FQBL(R2)

UCB$L_FPC(R2)

UCB$L_FR3(R2)

UCB$L_FR4(R2)

UCB$W_BUFQUO(R2)

UCB$L_ORB(R2)

Address of cloned ORB

UCB$L_LINK(R2)

Address of next UCB in DOB chain

UCB$L_IOQFL(R2)

Address of UCB$L_IOQFL(R2)

UCB$L_IOQBL(R2)

Address of UCB$L_IOQBL(R2)

UCB$W_UNIT(R2)

Device unit number (minimum UCB$W_UNIT_
SEED(R5)+ 1)

UCB$W_CHARGE(R2)

Mailbox byte quota charge (UCB$W_SIZE)

UCB$W_REFC(R2)

UCB$L_STS(R2)

UCB$V_DELETEUCB set, UCB$V_ONLINE set

Other Driver Routines
11.4 Cloned UCB Routine

Location

Contents

UCB$W_DEVSTS(R2)

UCB$V_DELMBX set if DEV$V_MBX is set in
UCB$L_DEVCHAR(R2)

UCB$L_OPCNT(R2)

UCB$L_SVAPTE(R2)

UCB$W_BOFF(R2)

UCB$W_BCNT(R2)

UCB$L_ORB(R2)

Address of cloned ORB

ORB$L_OWNER
of template ORB

UIC of current process

ORB$L_ACL_MUTEX
of template ORB
ORB$B_FLAGS
of template ORB

ORB$V_PROT_ 16 set

ORB$W_PROT
of template ORB

ORB$L_ACL_COUNT
of template ORB

ORB$L_ACL_DESC
of template ORB

ORB$R_MIN_CLASS
of template ORB

O in first longword

A cloned UCB routine must preserve the contents of R2 and R4. It issues
an RSB instruction to return control to EXE$ASSIGN. If the routine
returns error status in RO, EXE$ASSIGN undoes the process of UCB
cloning and completes with the failure status in RO.

11-13

Loading a Device Driver

You can load a non-Digital-supplied device driver any time after the
system is bootstrapped. If the driver contains an error and the error does
not crash or corrupt the operating system, you can correct the error and
reload a new version of the driver.

12.1

Preparing a Driver for Loading into the Operating System
To prepare a device driver for loading, perform the following steps:
1

Write the device driver in one or more source files. If the driver
comprises several source files, you must insert a .PSECT directive
before any generated code in all files except the file that contains the
DPTAB and DDTAB macro invocations. The following .PSECT must
be used:
.PSECT

$$$115_DRIVER

If a single source file contains the driver, you must not specify any

.PSECT directives. The declaration of the DPTAB and DDTAB macros
correctly establishes driver program sections ($$$105_PROLOGUE
and $$$115_DRIVER, respectively).

Assemble the source files with the system's macro library
(SYS$LIBRARY:LIB.MLB). For example:
MACRO MYDRIVER.MAR+SYS$LIBRARY:LIB.MLB/LIBRARY

Link the object file with the VMS global symbol table, which is located
in SYS$SYSTEM and called SYS.STB. If the driver consists of several
source files, you must specify the file that contains the driver prologue
table as the first file in the list. The linker-options file must contain a
BASE statement specifying a zero base for the executable image. The
following is an example of the creation of the options file and the LINK
command used to link a driver:
$ CREATE MYDRIVER.OPT
BASE=O

I Ctrl/Z I
$
$

LINK /NOTRACE MYDRIVER1[,MYDRIVER2, ... ],MYDRIVER.OPT/OPTIONS,SYS$SYSTEM:SYS.STB/SELECTIVE_SEARCH

The resulting image must consist of a single image section. The linker
will report that the image has no transfer address.
Once you have linked or relinked a driver, you should copy its image
to the SYS$LOADABLE_IMAGES or SYS$SYSTEM directory. The
SYSGEN LOAD and CONNECT commands first search for a driver in
the SYS$LOADABLE_IMAGES directory. If they do not find the driver,
they then search the SYS$SYSTEM directory.

12-1

Loading a Device Driver
12.2 Loading a Driver

12.2

Loading a Driver
Once the driver has been linked correctly, it is ready to be loaded. To load
the driver into system virtual memory, run the System Generation Utility
(SYSGEN) from the system manager's account or from an account having
CMKRNL privilege, using the following command:
$

RUN SYS$SYSTEM:SYSGEN

SYSGEN responds with a prompt and waits for further input:
SYS GEN>

The VMS System Generation Utility Manual describes the full set of
SYSGEN commands. The sections that follow describe those commands
SYSGEN uses to load drivers:
SVSGEN Command

Privilege Required

LOAD

CMKRNL

CONNECT

CMKRNL

RELOAD

CMKRNL

SHOW/ADAPTER

CM EXEC

SHOW/Bl

CM EXEC

SHOW/BUS

CM EXEC

SHOW/CONFIGURATION

CM EXEC

SHOW/DEVICE

CM EXEC

SHOW/XMI

CM EXEC

SYSGEN takes special steps to ensure that drivers that do not adhere to
multiprocessing synchronization standards do not coexist in a system with
drivers that are properly synchronized. The procedure that SYSGEN
follows to accomplish this is discussed in Section 12.3. In addition,
SYSGEN provides an automatic configuration service for most all devices
of the various bus-types, as described in Section 12.4.

12.2.1

LOAD Command
To load a device driver, issue the LOAD command.

Note: If the controller has only a single unit attached to it, you can
issue the CONNECT command to perform the driver-loading tasks
normally performed by the LOAD command, as well as its task of
creating the device's 1/0 database (see Section 12.2.2).
Format
LOAD filespec

12-2

Loading a Device Driver
12.2 Loading a Driver

Parameter
files pee

Name of a file containing an executable driver image. The driver-loading
procedure compares the file specification from the command line with
the names of the drivers in the current system configuration. If the
procedure discovers that a driver with the same name already exists
in the configuration, it will not load the new driver. If it does not find
a configured driver with the same name, it loads the new driver into
contiguous locations in nonpaged pool, and links the DPT into the system's
linked list of DPTs (headed by IOC$GL_DPTLIST).
The LOAD command uses SYS$LOADABLE_IMAGES as the default
device/directory name, and EXE as the default file type. If it cannot find
the driver in the SYS$LOADABLE_IMAGES directory, it searches for it in
SYS$SYSTEM.
Example
SYSGEN>

LOAD CRDRIVER

This command loads the driver found in SYS$LOADABLE_
IMAGES:CRDRIVER.EXE (the card-reader driver).

12.2.2

CONNECT Command
The CONNECT command creates data structures in the l/O database for
a specified device. The device-connecting procedure performs the following
general functions:
•

If the CONNECT command specifies a new device unit on an existing
controller, it creates a unit control block for the new unit and calls the
driver's unit initialization routine.

•

If the CONNECT command specifies a device unit on a new controller,
it creates a device data block, channel request block, interrupt dispatch
block, and unit control block and then calls both the controller
initialization and unit initialization routine in the driver. (Note that,
because system initialization creates the CRB and IDB for a generic
VAXBI device, the CONNECT command for such a device omits the
creation and initialization of these structures.)

The CONNECT command can also load into system memory a driver
that has not been previously loaded. (See the following discussion of the
/DRIVERNAME qualifier and the description of the LOAD command in
Section 12.2.1 for information on driver loading.)

Caution: The database-loading procedure does little error checking. If you
specify a vector that has already been defined, the procedure
rejects the CONNECT command. However, if the CONNECT
command specifies an incorrect CSR address, the 1/0 database
is apt to become corrupted and will likely cause a system failure.
Format
CONNECT device

12-3

Loading a Device Driver
12.2 Loading a Driver

Parameter
device
Name of the device to be connected. Specify the device name in the form.at
ddcu where
dd =
c

device code (up to 9 alphabetic characters)
controller designation (alphabetic)
unit number

For example, LPAO specifies the line printer (LP) on controller A at unit
number 0. When specifying the device name, do not follow it with a colon
(: ).

The device code and controller specification must be a unique and
accurate device name and controller combination. If data structures
for the specified device/controller already exist, the device-connecting
procedure does not create any data structures or perform any initialization
operations. If the device/controller name does not accurately name a
device, the procedure creates spurious data structures.
The device-connecting procedure examines the 1/0 database for data
structures that support the specified device. The procedure creates the
following data structures if they do not exist:
•

DDB for the specified device/controller combination (ddcu).

•

CRB and IDB for the specified controller. The device-connecting
procedure creates these data structures whenever it creates a DDB for
a UNIBUS, MASSBUS, or Q22 bus device.

•

UCB for the device unit. The device-connecting procedure creates a
UCB whenever it creates a DDB, or when a UCB for the specified
device does not exist. If a UCB already exists, the procedure ceases its
modifications to the I/O database and continues its other tasks.

After it creates these data structures, the procedure initializes them as
follows:
•

Performs the initialization operations specified by the DPT_STORE
macros in the initialization and reinitialization portions of the DPT.

•

Relocates all addresses in the DDT and FDT to absolute system virtual
addresses.

•

Raises IPL to IPL$_POWER on the local processor so that
initialization is not interrupted.

•

If it created a new CRB (or is connecting a generic VAXBI device),
calls the controller initialization routine, if one is specified by CRB$L_

INTD+VEC$L_INITIAL.
•

12-4

Calls the unit initialization routine if one is sgecified by DDT$L_
UNITINIT. If the DDT$L_UNITINIT does not specify a unit
initialization routine, the device-connecting procedure calls the unit
initialization routine (if any) specified by CRB$L_INTD+VEC$L_
UNITINIT.

Loading a Device Driver
12.2 Loading a Driver

Required Qualifiers
/[NO]ADAPTER:nexus
Nexus value of the UNIBUS adapter, MASSBUS adapter, or other
controller to which the device unit is attached. The nexus can be a
number or a generic name as listed by the /ADAPTER qualifier to the
SYSGEN command SHOW. (See Section 12.2.4 for a discussion of the
SHOW/ADAPTER command.) For generic VAXBI devices, this value is the
VAXBI node number (see Section 12.2.5 for discussion of the SHOW/BI
command).

Table 12-1 lists typical nexus assignments for UNIBUS and MASSBUS
adapters. For XMI bus and nexus assignments, refer to Sections
12.2.6 and 12.2.7 for a discussion of the SHOW/BUS and SHOW/XMI
commands.
Table 12-1

Adapter

Conventional Nexus Assignments
VAX 82~/83~
VAX 6000 series
VAX 85~/8700/88~

VAX-11/730

VAX-11/750

VAX-111780
VAX-11/785
VAX 8600/8650

UNIBUS
0

MASSBUS
0

8
9

5
6

10
11

All numeric values are interpreted as decimal unless they are preceded
by a radix descriptor (%0 or %X). Issue the CONNECT command with
the /NOADAPTER qualifier to connect drivers associated with software
devices. The mailbox driver is an example of this type of driver.
/CSR:csr-addr
UNIBUS or Q22 bus address of the device's control and status register
(CSR). All numeric values are interpreted as decimal unless they are
preceded by a radix descriptor (%0 or %X). Table 12-2 provides additional
information on vector and CSR assignments for UNIBUS and Q22 bus
devices.
/CSR_OFFSET:value
Offset from the CSR address of a multiple-device controller board to the
CSR address of the device. The /CSR_OFFSET qualifier is only required
for a multidevice board, such as the DMF32. All numeric values are
interpreted as decimal unless they are preceded by a radix descriptor

12-5

Loading a Device Driver
12.2 Loading a Driver

(%0 or %X). Table 12-2 provides additional information on vector and CSR
assignments for UNIBUS and Q22 bus devices.
/VECTOR:vector-addr

Q22 bus or UNIBUS address of the interrupt vector for the device. All
numeric values are interpreted as decimal unless they are preceded by a
radix descriptor (%0 or %X). Table 12-2 provides additional information
on vector and CSR assignments for UNIBUS and Q22 bus devices.
/VECTOR_OFFSET:value

Offset from the interrupt vector of a multiple-device board to the interrupt
vector of the device being connected. The NECTOR_OFFSET qualifier is
only required for a multi-device board, such as the DMF32. All numeric
values are interpreted as decimal unless they are preceded by a radix
descriptor (%0 or %X). Table 12-2 provides additional information on
vector and CSR assignments for UNIBUS and Q22 bus devices.
Optional Qualifiers
/NUMVEC:vector-cnt

Number of interrupt vectors for the device. If this qualifier is omitted, the
default number of vectors is 1. The number specified by the NECTOR
qualifier is the address of the lowest vector. Vectors must be contiguous.
/DRIVERNAME:driver

Name of the driver for the device to be connected. If the driver for
the specified device has not yet been loaded, the CONNECT command
will load its driver. First, it will attempt to load the driver whose
name is specified in this qualifier, defaulting to a file type of EXE
in device/directory SYS$LOADABLE_IMAGES. (If it cannot find the
driver in SYS$LOADABLE_IMAGES, the CONNECT command checks
SYS$SYSTEM.)
If the /DRIVERNAME qualifier is omitted, CONNECT follows one of
two procedures to supply a default name. If the device to be connected

is the first unit on the controller, CONNECT concatenates the first two
characters of the device code with "DRIVER" (for example, LPDRIVER).
Otherwise, CONNECT obtains the driver name from the field DDB$T_
DRVNAME.
Consult the SYSGEN device table in Table 12-2 for the driver names of
the devices supported by VMS.
I ADPUNIT:unit-number

Unit number of a device on the MASSBUS adapter. The unit number for
a disk drive is the number of the plug on the drive. For magnetic tape
drives, the unit number corresponds to the tape controller's number.
/MAXUNITS:max-unit-cnt

Maximum number of units attached to the controller. This number
determines the size of the UCB list appended to the IDB. If specified,
this value overrides the maximum number of units designated in the DPT.
The maximum number of units is stored in the field IDB$W_UNITS.

12-6

Loading a Device Driver
12.2 Loading a Driver

Example
SYSGEN>

CONNECT LPAO /ADAPTER=UBO/CSR=%0777514/VECTOR=%0200

This command loads the driver LPDRIVER, if it is not already loaded, and
creates the data structures (DDB, CRB, IDB, and UCB) needed to describe
LPAO. It also causes the driver's controller and unit initialization routines
to be executed.

12.2.3

RELOAD Command
The RELOAD command loads a driver and removes a previously loaded
version of that driver.
The RELOAD command provides all of the functions of LOAD, except that
it loads the driver regardless of whether it is already loaded. If any of the
units associated with the driver is busy, the driver cannot be reloaded;
SYSGEN issues an error message.

Caution: Use the RELOAD command only when all devices supported by the
driver are inactive. The checks for activity made by the RELOAD
command might not detect all device activity, and changing a
driver while an 1/0 request is being processed will cause a system
failure.
Format
RELOAD filespec

Parameter
filespec

Name of a file containing an executable driver image. The driver-reloading
procedure compares the name DPT$T_NAME of the driver being loaded
with the names of the drivers in the current system configuration. If no
such driver is configured, the driver-reloading procedure loads the driver
as described in the discussion of the LOAD command in Section 12.2.1.
If the SYSGEN reloading procedure finds a driver with the specified name

in the configuration, it first determines that the current driver can be
replaced in the following steps:
•

Confirms that the DPT$V_NOUNLOAD flag of the current driver is
not set.

•

Ensures that no devices that use the current driver are busy, as
indicated by the UCB$V_BSY bit set in UCB$L_STS.

•

If these checks succeed, calls the current driver's driver unloading

routine, if one has been specified in the unload argument of the
DPTAB macro.
The driver unloading routine executes in process context at IPL$_
POWER. It cannot lower IPL or obtain spin locks.
At the time of the call, register Rl 0 contains the address of the DPT.

12-7

Loading a Device Driver
12.2 Loading a Driver

A driver unloading routine can take steps to ensure that no thread
of code or structure exists in the system that may reference the
space occupied by the version of the driver about to be unloaded, a
timer-queue element (TQE), for instance.
A driver unloading routine can use COM$DRVDEALMEM to return
system buffers allocated by the driver to nonpaged pool. The driver
unloading routine returns status in RO to the driver-reloading
procedure.
Upon receiving success status, the driver-reloading procedure replaces the
current driver with the new driver in the following manner:

Loads the new driver into contiguous locations in nonpaged pool.

Searches the 1/0 database for references to the driver. If any DDB
refers to the driver being reloaded, the driver-reloading procedure
must reinitialize data structure fields according to the reinitialization
instructions in the new DPT (see Section 6.1 ).
Fields that must be reinitialized when a driver is reloaded include
those that contain relative addresses within the driver:

12.2.4

•

Addresses of the interrupt service routines

•

Addresses of the unit and controller initialization routines

•

Address of the driver dispatch table

Calls the driver's controller initialization routine. (It does not call the
unit initialization routine.)

Removes the newly replaced driver from the system's linked list of
DPTs (headed by IOC$GL_DPTLIST) and deallocates the nonpaged
system space the old driver occupied.

Links the address of the new DPT to the system's DPT list.

SHOW/ADAPTER Command
The SHOW/ADAPTER command displays nexus numbers and generic
names of UNIBUS adapters, VAXBI adapters, memory controllers, and
interconnection devices such as the DEBNI and CI. Use of the SHOW
/ADAPTER command requires CMEXEC privilege.
Format
SHOW/ADAPTER

Example
SYSGEN>

SHOW/ADAPTER

CPU Type:

12-8

VAX 6000-360

Loading a Device Driver
12.2 Loading a Driver

Nexus (decimal)
0001
1
0002
2
0003
3
0004
4
0005
5
0006
6
0007
7
0008
8
0009
9
OOOA
10
OOOB
11
oooc 12
OODl
OOD3
OOD6
OOEl
OOE4
OOE6

12.2.5

209
211
214
225
228
230

Generic Name or Description
XMI - 6000-200/300 processor
XMI - 6000-200/300 processor
XMI - 6000-200/300 processor
XMI - 6000-200/300 processor
XMI - 6000-200/300 processor
XMI - 6000-200/300 processor
XMI - memory module
XMI - memory module
XMI - memory module
XMI - memory module
XMI - memory module
XMI - memory module
XMI - BI Adapter (DWMBA/A)
XMI - BI Adapter (DWMBA/A)
BI - XMI Adapter (DWMBA/B)
CIO

BI
BI
BI
BI

NI Adapter (DEBNI)
XMI Adapter (DWMBA/B)
Disk Adapter (KDB50)
TK50 Adapter (TBK50)

SHOW/Bl Command
The SHOW/Bl command displays device addresses that are currently
mapped in the 1/0 space for the VAXBI bus. It also displays node and
nexus numbers and generic names of UNIBUS adapters, VAXBI adapters,
memory controllers, and interconnection devices such as the DMB32 and
Cl. Use of the SHOW/BI command requires CMEXEC privilege.

Format
SHOW/Bl

Example 1
SYSGEN> SHOW/BI
CPU Type:

VAX 8800

Cpu Connection: NMI

** Bus map for BI
Address 20000000 (node
Address 20004000 (node
Address 2000EOOO (node
** Bus map for BI
Address 22000000 (node
Address 22004000 (node
Address 2200EOOO (node

00 on 28-AUG-1990 14:13:02.95 **
00) responds with value 0108 CI
02) responds with value 0106 BI - NMI Adapter (NBIB)
07) responds with value 0109 BI Combo Board (DMB32)
01 on 28-AUG-1990 14:13:03.00 **
00) responds with value 0102 UB
02) responds with value 0106 BI - NMI Adapter (NBIB)
07) responds with value 410F BI - NI Adapter (DEBNA)

Example 2
SYS GEN> SHOW /BI
CPU.Type:

VAX 6000-450

Cpu Connection: XMI

** Bus map for BI 00 on 28-AUG-1990 14:14:54.03 **
Address 3A002000 (node 01) responds with value 2107 BI - XMI Adapter (DWMBA/B)

12-9

Loading a Device Driver
12.2 Loading a Driver

12.2.6

SHOW/BUS Command
The SHOW/BUS command displays the hierarchical bus structure of a
system and all attached devices. The display list includes node numbers,
generic names of processors, memory modules, adapters such as VAXBI
adapters, memory controllers, and interconnection devices such as the NI.
Use of the SHOW/BUS command requires CMEXEC privilege.
Format
SHOW/BUS

Example 1
SYS GEN>

SHOW /BUS

Cpu Type: VAX 8800
Bus
Node
Generic Name

Cpu Connection: NMI
Nexus(hex)
Connection Address

BI 00
BI 00
BI 00

00
02
07

CI
BI - NMI Adapter (NBIB)
BI Combo Board (DMB32)

0000
0002
0007

BI 01
BI 01
BI 01

00
02
07

UB
BI - NMI Adapter (NBIB)
BI - NI Adapter (DEBNA)

0010
0012
0017

Example 2
SYSGEN> SHOW/BUS
Cpu Type: VAX 6000-450
Bus
Node
Generic Name
XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI

00
00
00
00
00
00
00
00
00
00
00
00
00

01
02
03
04
05
06
07
08
09
OA
OB

oc
OD

BI 00
XMI 00
BI
BI
BI
BI

12-10

01
01
01
01

XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI
01

6000-400 processor
6000-400 processor
6000-400 processor
6000-400 processor
6000-400 processor
memory module
memory module
memory module
memory module
memory module
memory module
NI adapter (DEMNA)
BI Adapter (DWMBA/A)

BI - XMI Adapter (DWMBA/B)
XMI - BI Adapter (DWMBA/A)

01
02
04
06

BI - XMI Adapter (DWMBA/B)
BI - Disk Adapter (KDB50)
CI
BI - TK50 Adapter (TBK50)

Cpu Connection: XMI
Nexus(hex)
Connection Address
0001
0002
0003
0004
0005
0006
0007
0008
0009
OOOA
OOOB

oooc

OOOD Connects to BI 00 node 01
OODl Connects to XMI 00 node OD
OOOE Connects to BI 01 node 01
OOEl Connects to XMI 00 node OE
OOE2
OOE4
OOE6

Loading a Device Driver
12.2 Loading a Driver

12.2.7

SHOW/XMI Command
The SHOWIXMI command displays device addresses that are currently
mapped in the 1/0 space for the XMI bus. It also displays node and nexus
numbers and generic names of processors, adapters, VAXBI adapters,
memory controllers, and interconnection devices such as the NI. Use of the
SHOWIXMI command requires CMEXEC privilege.
Format
SHOW/XMI

Example
SYS GEN>

SHOW/XMI

** Bus map for XMI 00 on 28-AUG-1990 14:14:50.48 **

Address
Address
Address
Address
Address
Address
Address
Address
Address
Address
Address
Address
Address
Address

12.2.8

21880000
21900000
21980000
21A00000
21A80000
21BOOOOO
21B80000
21COOOOO
21C80000
21000000
21080000
21EOOOOO
21E80000
21FOOOOO

(node
(node
(node
(node
(node
(node
(node
(node
(node
(node
(node
(node
(node
(node

01)
02)
03)
04)
05)
06)
07)
08)
09)
OA)
OB)
OC)
OD)
OE)

responds with value 8082 XMI
responds with value 8082 XMI
responds with value 8082 XMI
responds with value 8082 XMI
responds with value 8082 XMI
responds with value 4001 XMI
responds with value 4001 XMI
responds with value 4001 XMI
responds with value 4001 XMI
responds with value 4001 XMI
responds with value 4001 XMI
responds with value OC03 XMI
responds with value 2001 XMI
responds with value 2001 XMI

SHOW/CONFIGURATION Command
The SHOW/CONFIGURATION command displays the device name,
number of units, nexus number and type, and shows the CSR and vector
addresses of devices connected to or autoconfigured in the system.
Format
SHOW/CONFIGURATION

Optional Qualifiers
I ADAPTER:nexus

Nexus value of the UNIBUS adapter, MASSBUS adapter, or other
interconnect to be displayed. The nexus value can be expressed as an
integer or as one of the generic names listed by the SHOW/ADAPTER
command.
/COMMAND_FILE
Option by which you instruct SYSGEN to format all device data
produced by the SHOW/CONFIGURATION command into CONNECT
IADAPTER=nexus commands and write them to a specified output file.
By executing the commands in this file, you can remove a device from
floating address space without completely reconnecting the CSR and vector
addresses of the remaining devices. See the VMS System Generation
Utility Manual for more details.
12-11

Loading a Device Driver
12.2 Loading a Driver

/OUTPUT:filespec

Name of a file into which SHOW/CONFIGURATION is to write device
configuration information.
Example
SHOW/CONFIGURATION/ADAPTER=UBl

SYS GEN>

System CSR and Vectors on
Name:
Name:
Name:
Name:
Name:
Name:
Name:
Name:
Name:
Name:

12.2.9

LPA
DYA
XMA
XMB
XMC
TTA
TTB
TTC
TTD
TTE

Units:
Units:
Units:
Units:
Units:
Units:
Units:
Units:
Units:
Units:

1 Nexus:4
2 Nexus:4
1 Nexus:4
1 Nexus:4
1 Nexus:4
8 Nexus:4
8 Nexus:4
8 Nexus:4
8 Nexus:4
8 Nexus:4

24-JUL-1991 14:58:26.08

(UBA)
(UBA)
(UBA)
(UBA)
(UBA)
(UBA)
(UBA)
(UBA)
(UBA)
(UBA)

CSR:
CSR:
CSR:
CSR:
CSR:
CSR:
CSR:
CSR:
CSR:
CSR:

777514 Vectorl:
777170 Vectorl:
760070 Vectorl:
760100 Vectorl:
760110 Vectorl:
760130 Vectorl:
760140 Vectorl:
760150 Vectorl:
760160 Vectorl:
760170 Vectorl:

200 Vector2:
264 Vector2:
300 Vector2:
310 Vector2:
320 Vector2:
330 Vector2:
340 Vector2:
350 Vector2:
360 Vector2:
370 Vector2:

000
000
304
314
324
334
344
354
364
374

SHOW/DEVICE Command
The SHOW/DEVICE command displays the following information:
•

Name of the driver

•

Starting virtual address of the driver (that is, the address of its DPT)

•

Ending virtual address of the driver

•

Generic device/controller name associated with the driver

•

Addresses of the DDB, CRB, and IDB for the generic device/controller
supported by the driver

•

Unit number and UCB address of each device unit associated with the
driver

The SHOW/DEVICE command requires CMEXEC privilege.
Format
SHOW/DEVICE [=driver-name]

Parameter
driver-name

Name of the driver for which the information is to be displayed. If a driver
name is not specified, the command displays information about all drivers
and devices known to the system.
Example
SYSGEN>

SHOW/DEVICE=TMDRIVER

DRIVER

START

- -END- -DEV- -DDB- - -CRB- - -IDB- - - -UNIT

UCB

TMDRIVER 8009DF00 8009F020
MTA 800BA660 800BA6CO 800BA360
0 8009F020
1 8009FOCO

12-12

Loading a Device Driver
12.3 Loading Uniprocessing and Multiprocessing Drivers

12.3

Loading Uniprocessing and Multiprocessing Drivers
In a VMS multiprocessing environment, the presence of a device driver
that does not adhere to multiprocessing synchronization conventions
might impair proper system functions. VMS takes steps to either prohibit
the enabling of multiprocessing in a VAX system that has such a driver
present or prevent the loading of such a driver if multiprocessing has
already been enabled.
To accomplish this, the VMS driver-loading routine assumes that any
driver that can run in a VMS multiprocessing environment uses the spin
lock synchronization macros and loads the appropriate 1/0 database fields.
(See Section E.3 for information on how to produce a driver that can
execute in a VMS multiprocessing environment.) Use of the spin lock
synchronization macros causes VMS to set the SMP-modified bit in the
DPT (DPT$V_SMPMOD in DPT$L_FLAGS).
If multiprocessing has not been enabled on the system, the driver-loading
routine checks the SMP-modified bit in the DPT and takes either of the
following actions:
•

If the SMP-modified bit is set, the driver-loading routine loads the
driver and calls its controller and unit initialization routines, as
discussed in Section 12.2.

•

If the SMP-modified bit is not set, the driver-loading mechanism sets
the unmodified-driver bit (SMP$V_UNMOD_DRIVER) in SMP$GL_
FLAGS, thus prohibiting the subsequent enabling of multiprocessing
on the system. It then loads the driver and calls its controller and unit
initialization routines. If such a driver has been successfully loaded
into a VMS system, you cannot subsequently enable multiprocessing.

If multiprocessing is currently enabled on the system, the driver-loading
mechanism checks the SMP-modified bit in the DPT and takes either of
the following actions:

12.4

•

If the SMP-modified bit is set, the driver-loading mechanism loads the
driver and calls its controller and unit initialization routines.

•

If the SMP-modified bit is not set, the driver-loading mechanism does
not load the driver, returning the error status SS$_NONSMPDRV to
its caller.

The SYSGEN Autoconfiguration Facility
Traditionally, SYSGEN is invoked near the end of system initialization
processing during the execution of the system startup command procedure.
This procedure generally issues a SYSGEN AUTOCONFIGURE ALL
command, the result of which is that SYSGEN scans various device tables
to determine devices VMS expects to be connected to each UNIBUS, Q22
bus, MASSBUS, and VAX.BI bus configured in the system. Ultimately, as
the autoconfigure facility discovers the data structures associated with
the devices recognized by VMS, it loads the associated device drivers and
invokes their initialization routines.

12-13

Loading a Device Driver
12.4 The SVSGEN Autoconfiguration Facility

To configure devices attached to the UNIBUS or Q22 bus, SYSGEN
goes through the steps described in subsequent sections of this chapter.
Because the autoconfigure facility cannot recognize non-Digital-supplied
VAXBI devices, the system startup procedure (or a later invocation of
SYSGEN) must explicitly request that SYSGEN connect the device. 1
SYSGEN responds to such explicit requests by utilizing the data structures
created by the VMS adapter initialization module for the unknown VAXBI
device to load the associated device driver and invoke its initialization
routines.
SYSGEN automatically configures a UNIBUS or Q22 bus as follows:

12.4.1

•

It initializes the base of floating space to 3008 and 760010s for vectors
and CSRs, respectively.

•

It tests fixed and floating CSR address space for all known Digital
devices.

•

When a device is found at a CSR, SYSGEN reserves floating CSR and
vector space for that device, if necessary.

•

It searches for the name of the driver associated with the device
~y c~ecking t~~-~~!39"~~-<!_e_y~e-~~~l~~~h~wn_~~-~~~!~_!~~) ~~d
tne mrectory ;:; H:itj)LV.8..LJ.fUjL.r.i_HV.lAu.l!ii':> ~or i':> .1 i':>fl>O .1 o l .i!ilVlJ. n
the driver has already been loaded or exists as an image file in
SYS$LOADABLE_IMAGES (or.SYS$SYSTEM), SYSGEN creates
and initializes the I/O database for that device and loads the driver's
image if necessary. If the device at the CSR is supported by VMS and
SYSGEN cannot locate its associated driver's image, it generates an
error message. If the device is unsupported and has no corresponding
driver's image, SYSGEN ignores the condition.

SYSGEN Device Table
Digital-supplied devices are attached to the UNIBUS or Q22 bus according
to the following basic rules:

•

A device of type A is always at a fixed and predefined CSR address;
the device always interrupts at a fixed and predefined vector address;
only one example of device A can be configured in each system.

•

A device of type B is identical to type A except that 1 through n
examples can be configured in a single system. Examples 2 through n
are also located at fixed and predefined CSRs and vector addresses.

•

Devices of type C (1 through n of them) are always at fixed and
predefined CSR addresses; however, the interrupt vector addresses
vary according to what other devices are present on the system.

•

Devices of type D (1 through n of them) are at CSR addresses and
vector addresses that vary according to what other devices are present
on the system.

Because the autoconfigure facility will never be called for a non-Digital-supplied device, any unit delivery
routine that a VAXBI device driver may include will never be called.

12-14

Loading a Device Driver
12.4 The SYSGEN Autoconfiguration Facility

CSR and vector addresses that vary are called floating addresses. The
devices must be located in floating CSR and vector space according to the
order in which the devices appear in the SYSGEN device table. This table,
shown in Table 12-2, lists all the type A and type B devices supported by
VMS. It also lists the type C and type D devices that are recognized by
SYSGEN's autoconfiguration procedure.
For UNIBUS and Q22 bus systems, the base of floating CSR space is
7600108 . CSR range 7641008 to 767776s is reserved for Digital's Customer
Special Systems (CSS) and for non-Digital-supplied devices. Reserved
addresses 7660008 to 7677768 are recommended for customer third-party
devices. For UNIBUS and Q22 bus systems, the base of floating vector
space is 300g. For third-party devices, it is recommended that the vector
assignment begin from the top of floating vector space and work down
toward its base.
Table 12-2 lists the characteristics of all devices recognized by SYSGEN.
This table indicates the following information for each device type:
•

Device name

•

Device controller name

•

Interrupt vector

•

Number of interrupt vectors per controller

•

Vector alignment factor

•

Address of the first device register for each controller recognized by
SYSGEN. (The first register is usually, but not always, the CSR.)

•

Number of registers per controller

•

Device driver name

•

Indication of whether the driver is supported

Devices not listed in the SYSGEN device table include the following:
•

Non-Digital-supplied devices with fixed CSR and vector addresses.
These devices have no effect on autoconfiguration. Customer-built
devices should be assigned CSR and vector addresses beyond the
floating address space reserved for Digital-supplied devices.

•

Those Digital-supplied floating-vector devices that the
AUTOCONFIGURE command does not recognize. Use the CONNECT
command to attach these devices to the system.

12-15

Loading a Device Driver
12.4 The SYSGEN Autoconfiguration Facility

Table 12-2 SVSGEN Device Table
Device
Name

Controller
Name

CR
OM
LP

CR11
RK611
LP11

DL
MS
DY
DQ
PU
PT
XE
XQ
OM

RL 11
TS11
RX211
RB730
UDA
TU81
UNA
QNA
DC11

TU58

DN11

Vector

230
210
200
170
174
270
274
160
224
264
250
154
260
120
120
Float

Float

Number
of
Vectors

Driver
Name

Support

CR DRIVER
DMD RIVER
LP DRIVER

Yes
Yes
Yes

OLD RIVER
TS DRIVER
DYDRIVER
DQDRIVER
PU DRIVER
PU DRIVER
XEDRIVER
XQDRIVER
OMDRIVER

Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No

32 units
maximum
776500
776510
776520
776530

DD RIVER

Yes

16 units
maximum
775200
775210
775220
775230

OBDRIVER

Vector
Alignment

CSR/Rank

777160
777440
777514
764004
764014
764024
764034
774400
772520
777170
775606
772150
774500
774510
774440
774000
774010
774020
774030

16 units
maximum
(continued on next page)

12-16

Loading a Device Driver
12.4 The SVSGEN Autoconfiguration Facility

Table 12-2 (Cont.)

SYSGEN Device Table

Device
Name

Controller
Name

Vector

DM11B

Float

Number
of
Vectors

Vector
Alignment

CSR/Rank
770500
770510
770520
770530

Driver
Name

Support

YMDRIVER

OADRIVER

PRO RIVER

PPDRIVER

OCDRIVER

16 units
maximum
OA

DR11C

Float

767600
767570
767560
767550

16 units
maximum
PR

PR611

Float

772600
772604
772610
772614

8 units
maximum

PP611

Float

772700
772704
772710
772714

8 units
maximum
OC

DT11

Float

777420
777422
777424
777426

8 units
maximum
(continued on next page)

12-17

Loading a Device Driver
12.4 The SVSGEN Autoconfiguration Facility

Table 12-2 (Cont.)

SVSGEN Device Table

Vector

Number
of
Vectors

Vector
Alignment

DX11

Float

DL11C

Float

Device
Name

Controller
Name

OD
YL

Driver
Name

Support

776200
776240

ODD RIVER

775610
775620
775630
775640

YLDRIVER

CSR/Rank

31 units
maximum
VJ

DJ11

Float

YJDRIVER

DH11

Float

YHDRIVER

GT40

Float

772000
772010

OED RIVER

LPS11

Float

770400

DQ11

Float

KW11W

Float

772400

LSD RIVER

ORD RIVER

OFDRIVER

XUDRIVER

XVDRIVER

DU11

Float

DV11

Float

775000
775040
775100
775140

LK11

Float

OGDRIVER

DMC11

Float

XMDRIVER

Yes

TIA

DZ11

Float

DZDRIVER

Yes

Float

XKDRIVER

KMC11

LPP11

Float

OH DRIVER

VMV21

Float

OIDRIVER

VMV31

Float

OJ DRIVER

Float

OKDRIVER

DWR70

Float

RL11

Float

TS11

Float

772524
772530
772534

LPA11

Float

770460

LPA11

Float

KW11C

Float

8
8

Float

RX211

Float

DLDRIVER

Yes

TSDRIVER

Yes

LAD RIVER

Yes

LAD RIVER

Yes

OLDRIVER

DYDRIVER

Yes

(continued on next page)

12-18

Loading a Device Driver
12.4 The SVSGEN Autoconfiguration Facility

Table 12-2 (Cont.)

SYSGEN Device Table
Number
of
Vectors

Vector
Alignment

CSR/Rank

Driver
Name

Support

Float

XADRIVER

Yes

XBDRIVER

XDDRIVER

Yes

ON DRIVER

Float

ISDRIVER

Float

XO DRIVER

Float

XEDRIVER

774460

XQDRIVER

Yes

Float

PU DRIVER

Yes

Float

XSDRIVER

764200
764240
764300
764340

XPDRIVER

Float

VBDRIVER

Float

PU DRIVER

Yes

Float

OQDRIVER

Float

764400
764440
764500
764540

UKDRIVER

Float

764100

IXDRIVER

Device
Name

Controller
Name

Vector

DR11W

Float

DR11B

124

DR11B

Float

772430

DR11B

Float

DMP11

Float

DPV11

Float

ISB11

Float

DMV11

Float

UNA

Float

ONA

Float

LIDA

Float

KMS11

Float

PCL11

Float

VS100

TU81

KMV11

Float

KCT32

IEQ11

772410

DHV11

Float

TC11

214

vc
vc

VCB01

Float

VCB01

Float

LNV11

Float

776200

LNV21

Float

QTA

Float

772570

Float

YFDRIVER

Yes

777340

DTDRIVER

777200

VCDRIVER

Yes

Float

VCDRIVER

Yes

OTO RIVER

LO DRIVER

ZQDRIVER

Float

QTA

Float

DSV11

Float

ADV11C

Float

ov
ov

AAV11

Float

770440

AAV11C

Float

64
16
8

ZQDRIVER

Float

SJ DRIVER

Float

OU DRIVER

OVDRIVER

(continued on next page)

12-19

Loading a Device Driver
12.4 The SVSGEN Autoconfiguration Facility

Table 12-2 (Cont.)

SYSGEN Device Table

Device
Name

Controller
Name

Vector

Number
of
Vectors

AXV11C

140

AXV11C

Float

KWV11C

Float

770420

KWV11C

Float

ADV11D

Float

776410

Vector
Alignment

CSR/Rank

776400

ADV110

Float

AAV11D

Float

776420

AAV11D

Float

VCB02

Float

777400
777402
777404
777406

8
4
4
4

Driver
Name

Support

AXDRIVER

KZDRIVER

AZDRIVER

AYDRIVER

VADRIVER

Yes

ON DRIVER

8 units
maximum
ON

DRV11J

Float

764160
764140
764120

DRQ38

Float

HXDRIVER

VSV24

Float

VODRIVER

VSV21

Float

VVDRIVER

BOD RIVER

UTDRIVER

18001

Float

MIRA

Float

8
8
8

IEQ11

Float

IXDRIVER

ADQ32

Float

AWDRIVER

DTC04

Float

VXDRIVER

DES NA

Float

COD RIVER

IGQ11

Float

~QDRIVER

Float

RSDRIVER

KMV1F

Float

DIV32

Float

SDDRIVER

DTCN5

Float

VNDRIVER

DTC05

Float

VMDRIVER

KWV32

Float

UJDRIVER

OZA

Float

PKIDRIVER

Yes

12-20

Loading a Device Driver
12.4 The SVSGEN Autoconfiguration Facility

12.4.2

Device Driver Control of Autoconfiguration
The SYSGEN autoconfiguration facility provides two features that drivers
can use to control the automatic configuration of the devices they operate.
These features are invoked through the defunits and deliver arguments
to the DPTAB macro.
The defunits argument to the DPTAB macro specifies a default number
of units to be configured on each controller. The DPTAB macro copies
this value to the DPT$W_DEFUNITS field in the DPT. The SYSGEN
autoconfiguration facility reads this field and creates UCBs numbered
zero through the default unit number minus one. The default value of
defunits is 1.
The deliver argument to the DPTAB macro specifies the address of a
driver-specific unit delivery routine. An offset to this routine is stored in
the DPT$W_DELIVER field in the DPT. When the deliver argument is
present, the SYSGEN autoconfiguration facility calls the unit delivery
routine once for each unit, the number of which is specified in the
defunits argument.
The unit delivery routine prevents the creation of UCBs for devices that
do not respond to a test for their presence.
If the unit delivery routine returns a true status in RO, the unit is

configured. If the status in RO is false, the autoconfiguration facility
does not configure the device. If the deliver argument is not used, the
unit delivery feature is disabled.
SYSGEN calls the unit delivery routine with a JSB instruction in the
following context:
•

Interrupt priority level is at IPL$_POWER.

•

RO through R2 are available for use.

•

R3 contains the address of the IDB, if one exists. If none exists, the
value contained in R3 is zero.

•

R4 contains the address of the CSR for the controller.

•

R5 contains the number of the unit that the routine must decide
whether or not to configure.

•

R6 contains the base address of UNIBUS adapter 1/0 space.

•

R7 contains the address of the configuration control block (ACF).

•

RB contains the address of the ADP.

The configuration control block (ACF) is described in the VMS Device
Support Reference Manual.
A driver may or may not specify a unit delivery routine. For instance, the
DZll's device driver specifies 8 as the default unit number, but provides
no routine to configure eight terminal units automatically for each DZll 's
CSR. The RK611 device driver specifies 8 as the default number of units
and also specifies the address of a unit delivery routine that is called once
for each of the eight possible devices on the controller.

12-21

Loading a Device Driver
12.4 The SVSGEN Autoconfiguration Facility

12.4.3

Floating-Vector Address Calculation
To calculate the floating-vector address of a device, SYSGEN rounds the
current floating-vector base (CFVB) up to the next valid vector address
boundary for the next device in the table.
If a device is present, SYSGEN reserves floating-vector space for the device

by computing a new CFVB:
CFVB + (4 * number-of-vectors) -+ CFVB

12.4.4

Floating-CSR Address Calculation
To calculate the floating CSR address of a device, SYSGEN rounds the
current floating CSR base (CFCB) up to the next valid floating CSR
address. Floating CSR addresses must be on a word boundary.
SYSGEN tests the CSR address (CFCB) for the next device in the device
table by executing a TSTW instruction on the address and noting whether
there is a response at that address.
1f the device is present, SYSG.l!:N reserves tloating CSH. address space tor
the device by computing a new CFCB:

CFCB +bytes-in-register-set-+ CFCB
When all devices of a particular type have been located and their floating
CSR space reserved, SYSGEN reserves an extra block of CSR space to
indicate a change to a new device type:
CFCB + 2 -+ CFCB
If the device is not present, SYSGEN reserves an extra block of CSR space

to indicate a change to a new device type by adding two to the rounded
CFCB:
CFCB + 2 -+ CFCB

12.4.5

Rules for Configuration
The formulas described in Sections 12.4.3 and 12.4.4 reduce to the
following rules:
•

Devices with fixed CSR addresses and fixed vector addresses must be
attached according to the SYSGEN device table settings.

•

Devices with floating CSR or vector addresses must be attached in the
order in which they are listed in the SYSGEN device table.

•

A 2-byte gap must be reserved between each device type located in
floating CSR address space.

•

A 2-byte gap must be reserved in floating CSR address space for each
device type that has no controller in its configuration.

•

An extra 2-byte gap must be reserved between the K.WllC and the

RXll in floating CSR address space.

12-22

Loading a Device Driver
12.4 The SYSGEN Autoconfiguration Facility

When assigning floating vector addresses and registers to devices
not supplied by Digital, be sure to leave a generous gap between
these addresses and those of devices in the table because future VMS
maintenance updates might add new devices to the SYSGEN device
table. 2

UNIBUS addresses 766000s through 7677768 are available for non-Digital-supplied devices.

12-23

Debugging a Device Driver

DELTA and XDELTA are debugging tools that can be used to monitor the
execution of user programs and the VMS operating system. When you link
DELTA with a user image that runs in a nonprivileged process, DELTA is
a user-mode debugging tool. When run in a privileged process, however,
DELTA acts as a multimode debugger; it allows you to debug in user mode
or to change to kernel mode for debugging. However, DELTA does not
support debugging at elevated IPLs.
XDELTA is syntactically identical to DELTA but also allows you to debug
code that executes at an elevated IPL. XDELTA is used for standalone
debugging of driver code and the executive.
This chapter primarily describes the use of XDELTA as a tool for
debugging an executing driver image.
The chapter includes discussions of two additional topics:
•

Detection and analysis of driver errors in a VMS multiprocessing
system

•

Detection of corruption in nonpaged pool and the ways in which the
corrupting code can be discovered

These topics supplement information presented in the VMS System Dump
Analyzer Utility Manual.

13.1

Bootstrapping the System with XDELTA
Under VMS, drivers are part of the operating system. You normally
bootstrap the system with two boot flags set to allow you to debug with
XDELTA. One flag causes the bootstrapping procedure to include XDELTA
in the system. The other boot flag indicates a stop at the breakpoint at the
beginning of VMS initialization. (The BREAKPOINTS system parameter,
by default, enables a breakpoint at the end of system initialization. See
Section 13.2 for additional information.) Table 13--1 describes the possible
values of these flags. Following a boot that includes XDELTA, executing
a BPT instruction causes control to transfer to a fault handler located in
XDELTA.

13-1

Debugging a Device Driver
13.1 Bootstrapping the System with XDELTA

Table 13-1

Boot Flags That Control the Loading of XDELTA

Flag
Value (f)

Meaning

Normal nonstop bootstrap (default)

Stop in SYSBOOT (equivalent to @DxyGEN on the VAX-11/780)

Include XDELTA with the system but do not take the initial breakpoint

Include XDELTA with the system and take the initial breakpoint

Include XDELTA with the system, stop in SYSBOOT and take the
initial breakpoint at system initialization (equivalent to @DxyXDT on
the VAX-11/780)

The procedures for bootstrapping the system with XDELTA differ
depending upon the system on which the operating system is running.
Some VAX systems that use a console block storage device supply a special
boot command file that automatically includes XDELTA in the system and
causes the processor to stop in SYSBOOT and take the initial breakpoint
Rt i;:vi;:fa~m init.iRli'7.Rtinn WhPn hnntinP' nt.hP.r i;:vd.P.m!': vnn mni;:t. i;:niPrifv
-

...

....

the appropriate flag value in the BOOT command. Table 13-2 lists some
recommended methods for booting with XDELTA. See your system's
installation and operations guides for additional information.
Table 13-2 Recommended Methods for Bootstrapping with XDELTA
Boot Commands

Explanation

MicroVAX/VAXstation Systems and VAX-11/7501 Systems

B[ If] devname

B is the console BOOT command. The flags ( f) parameter is a 32-bit hexadecimal
integer loaded into R5 as input to VMS.EXE, the primary bootstrap program. See
Table 13-1 for a list of its possible values.
Using the format ddcu, specify the name of the device that contains the volume to be
bootstrapped. You must supply both controller ( c) and unit ( u) identifiers; there are no
defaults. ·If you omit devname, the f parameter is ignored.
The following example bootstraps a MicroVAX II system from DUA0. 2

»>

B/7 DUAO

SYS BOOT>
SYSBOOT>

CONTINUE

The console TU58 of the VAX-11/750 system contains command files (DMAXDT.CMD and DBAXDT.CMD) analogous to those
supplied for the VAX-111780. See your system's installation and operations guides for additional information.
2 At the SYSBOOT prompt enter other required SYSBOOT commands and conclude the boot operation with a CONTINUE
command. If you do not set or load system parameters with a USE command, the system uses parameters stored in the
system image. To prevent the system from automatically rebooting after a bugcheck, clear the BUGREBOOT system parameter.

(continued on next page)

13-2

Debugging a Device Driver
13.1 Bootstrapping the System with XDELTA

Table 13-2 (Cont.)
Boot Commands

Recommended Methods for Bootstrapping with XDELTA
Explanation

VAX-11 /730 Systems
@DQAXDT
@DQOXDT

Use either DQAXDT.CMD or DQOXDT.CMD, depending upon the boot device. The
following example boots from DOA 1, first depositing the value 1 in R3. When the boot
device is DQAO, you can omit this step and execute DQOXDT.COM. 2
>>> D/G/L 3 1
>>> @DQAXDT
SYSBOOT>
SYSBOOT> CONTINUE

VAX 6000-Series Systems
B /RS:f [bootspec]

B is the console BOOT command. The flags ( f) parameter is a 32-bit hexadecimal
integer loaded into RS as input to VMS.EXE, the primary bootstrap program. See the
XDELTA boot flags in Table 13-1 for a list of its possible values.
The bootspec may indicate a specific boot path using explicit /XMI and /Bl qualifiers,
or it may be a symbolic name for qualifiers which you previously specified for your
VAX 6000-series configuration. Refer to your system-specific operations guide for more
information on booting and the boot specifications.
If you do not currently use RS in any boot specification, use the values in the XDELTA
boot flag table for RS. For example, to boot from the boot disk at VAXBI [lode 4 through
the DWMBA adapter at XMI node E, load XDELTA, stop in SYSBOOT, and take the
initial breakpoint (RS= 7) as follows:
>>> B/R5: 7 /XMI: E /BI: 4 DUl
SYSBOOT>

If you have previously specified a /RS qualifier value for your VAX 6000-series
configuration, you must logically OR this value with one from the XDELTA boot table.
For example, if you have a boot alias SYS1 defined to boot from system root SYS1,
your boot specification might result as follows:
>>> SHOW BOOT
SYSl
/XMI:E/BI:4/R5:10000000

For the XDELTA boot, you must then OR the values from the XDELTA boot flag table
with your existing RS specification. If you take the initial break point, in this example,
specify the following:
>>>

B SYSl /RS: 10000006

2 At the SYSBOOT prompt enter other required SYSBOOT commands and conclude the boot operation with a CONTINUE
command. If you do not set or load system parameters with a USE command, the system uses parameters stored in the
system image. To prevent the system from automatically rebooting after a bugcheck, clear the BUGREBOOT system parameter.

(continued on next page)

13-3

Debugging a Devicf;} Driver
13.1 Bootstrapping the System with XDELTA

Table 13-2 (Cont.)

Recommended Methods for Bootstrapping with XDELTA

Boot Commands

Explanation

VAX 8600/8650 Systems
@DUOXDT

Use DUOXDT.COM, if available on the console media, according to the method
described for the VAX-11/780. Otherwise, perform a normal bootstrap using the
available dduGEN.COM or dduBOO.COM according to the following method:
Use the /NOSTART qualifier in the BOOT command to cause the processor to pause
and await console commands after it boots. After a variety of progress messages are
displayed, the console prompt reappears. First, determine a value for the flag that
controls XDELTA loading (see Table 13-1). Then, examine the current value of R5;
if it is nonzero (for instance, it is the system root number), perform an inclusive-OR
operation upon it and your selected XDELTA flag value. 2
>>> BOOT /NOST ART
>>> EXAMINE RS
>>> DEPOSIT RS 7
>>> CONTINUE
SYSBOOT>
SYSBOOT> CONTINUE

VAX 9000-Series Systems
B[/R5:~

[/XM I:xmi_info]
[/Bl: vaxbLnode_idj

devname

B is the console BOOT command. The flags ( f) parameter is a 32-bit hexadecimal
integer loaded into R5 as input to VMB9AQ.EXE, the primary bootstrap program. See
the XDELTA boot flags in Table 13-1 for a list of its possible values.
Specify xmi_info using the XMI number and XMI node number (both in hexadecimal)
of the node being accessed. The XMI bus number defaults to zero. The hexadecimal
number that you specify with this qualifier must be in the format xy, where xis the XMI
bus number and y is the XMI node number.
Specify devname in the format ddduuu and the VAXBI node ID of the device in the /Bl
qualifier. (You can substitute a symbolic name for these qualifiers as discussed in your
system-specific operations guide.)
The console passes the specified unit number (uuu) to the procedure ddaBOO.CMD. If
you do not specify devname, the console executes DEFBOO.CMD.
The following example bootstraps a VAX 9000 system from the boot disk (unit 0) at
node 3 of the VAXBI bus at node 11 (C1 6 ) of the XMIO bus. 2
>>> B/RS: 7 /X:MI: C/BI: 3 KDMO
SYSBOOT>
SYSBOOT> CONTINUE

2 At the SYSBOOT prompt enter other required SYSBOOT commands and conclude the boot operation with a CONTINUE

command. If you do not set or load system parameters with a USE command, the system uses parameters stored in the
system image. To prevent the system from automatically rebooting after a bugcheck, clear the BUGREBOOT system parameter.

13-4

Debugging a Device Driver
13.2 Proceeding from the Initial Breakpoints

13.2

Proceeding from the Initial Breakpoints
Before stopping at any breakpoints that may be defined in driver code,
the VAX processor can stop at either or both of two breakpoints in system
initialization.
The breakpoint at the end of system initialization is enabled by the default
setting of the BREAKPOINTS system parameter. The breakpoint at the
beginning is enabled by the appropriate value of the boot flag as described
in Table 13-1.
After being bootstrapped, the system displays its welcoming message and
halts in XDELTA, as follows:
1 BRK AT nnnnnnnn
address/NOP

XDELTA is waiting for input. (XDELTA never issues explicit prompts.)
Usually, you proceed from this point with the following command:
;P

!Return!

All of the XDELTA commands are described in Section 13.10 and in the
VMS Delta I XDelta Utility Manual.
If the operating system halts with a fatal bugcheck, the system prints
the bugcheck information on the console terminal. Then, because the
BUGREBOOT system parameter is clear, XDELTA prompts. Bugcheck
information consists of the following:

•

Type of bugcheck

•

Dump of one or more stacks

PC and stack content indicate how an experimental driver crashed
the system. You can then examine the system state further by issuing
XDELTA commands.

13.3

Loading the Driver
Once the system is running, you can log in to the system as the system
manager and load the experimental driver.
To load the driver, run SYSGEN and issue the appropriate LOAD and
CONNECT commands. Example 13-1 provides a sample dialogue.
The first SHOW command in Example 13-1 causes SYSGEN to display the
location of the device driver in system memory. You then define the device
to the operating system. The second SHOW command causes SYSGEN to
display the driver's location and the addresses of the device's DDB, CRB,
IDB, and UCB.

13-5

Debugging a Device Driver
13.4 Inserting Breakpoints in Driver Source Code

Example 13-1

Loading a Driver

$ RUN SYS$SYSTEM:SYSGEN
SYSGEN> LOAD DMAO: [YOUR.DIRECTORY]YRDRIVER.EXE
SYSGEN> SHOW /DEVICE=YRDRIVER
Driver
Start
End
Dev
DDB
CRB
IDB
Unit UCB
YRDRIVER--S0060E50 80061070
------SYSGEN> CONNECT YR /ADAP=3/VEC=%0274/CSR=%0776240
SYSGEN> SHOW /DEVICE=YRDRIVER
Driver
Start
End
Dev
DDB
CRB
IDB
Unit UCB
YRDRIVER---S0060E50 80061070
------YRA 8005FDCO 80060B70 8005FEOO
0 80060BBO
SYSGEN> EXIT

13.4

Inserting Breakpoints in Driver Source Code
The SYSGEN command CONNECT calls controller initialization and unit
initialization routines. To begin debugging the driver, you should ensure
tflat tfle Kernei-mocie ciei>ugging Utiiity ALJ~~'i"A gain;:; \;Vll~l"U~ ul' ~~.l" ~~V".l
before these routines execute. This is accomplished by placing one or more
calls to the special system routine INI$BRK within the source code of
either the controller or unit initialization routine. To call INI$BRK, use
the following instruction:
JSB

GAINI$BRK

The INI$BRK routine contains two instructions:
BPT
RSB

When the processor executes the BPT instruction, XDELTA gains control
and reports the address of the breakpoint:
1 BRK AT nnnnnnnn

You can use INI$BRK as a debugging tool and place calls to it within any
part of the driver source code.
To determine the last driver PC before the breakpoint, examine the kernel
stack. The stack register is register RE (hexadecimal format):
RE/ address

I address

Display RE to find the address of the top of the stack. Another display
command (I) reveals the contents of the top of the stack, which should be
the return address to the driver that called INI$BRK.

13-6

Debugging a Device Driver
13.5 Calculating the Base of Driver Code

13.5

Calculating the Base of Driver Code
Before you debug the driver, it is a good idea to calculate the base address
of driver code, as follows:
1

Run SYSGEN and issue the SHOW/DEVICE command. The resulting
display lists the location in nonpaged pool at which SYSGEN loaded
the driver.

Consult the loadmap for the driver (obtained at driver link time).
Driver code resides in two program sections (PSECTs):
$$$105_PROLOGUE

driver prologue table

$$$11 S_DRIVER

driver code

The locations given in the driver code listing are offsets from $$$115_
DRIVER. Thus, you can calculate the base address of the driver
by adding the address at which the driver was loaded to the offset
associated with the PSECT $$$115_DRIVER shown in the map.
If you do not have the loadmap, consult the driver prologue table in the
driver listing. Look for the address of DPT_STORE_END, which generates
a 2-byte entry that terminates the DPT. To get the base address of driver
code, add the address of DPT_STORE_END + 2 to the address at which
the driver was loaded. You can set an XDELTA base register to the base of
driver code; Section 13.8 describes this procedure.

13.6

Requesting an XDELTA Software Interrupt
Once the controller and unit initialization routines complete execution,
you will need to set breakpoints in order to debug the driver. You can set
a breakpoint in the driver source code by inserting calls to INl$BRK, as
described in Section 13.4.
Note that, in a VMS multiprocessing system, only one processor can be in
XDELTA at a time. If a processor encounters a breakpoint while another
processor is in XDELTA, it too must wait until the current processor
exits from XDELTA. When it does, this processor again executes the
instruction that caused it to attempt to enter XDELTA. If the processor
previously in XDELTA did not delete the breakpoint, this processor now
enters XDELTA. If the processor previously in XDELTA did remove the
breakpoint, this processor does not enter XDELTA.
You can also invoke XDELTA to set breakpoints interactively by requesting
an XDELTA software interrupt.
The procedures described in Table 13-3 issue a software interrupt to a
single processor at IPL 14.
On the processor requesting the XDELTA interrupt, the interrupt service
routine at IPL 14 handles the interrupt by calling the routine INI$BRK,
which in turn executes the first XDELTA breakpoint. XDELTA then issues
this message:
1 BRK AT nnnnnnnn
address/NOP

13-7

Debugging a Device Driver
13.6 Requesting an XDELTA Software Interrupt

In a VMS multiprocessing system, if another processor attempts to
enter XDELTA at this time, it must wait until the processor currently
in XDELTA exits.
Table 13-3 Requesting an XDELTA Software Interrupt
System
VAX 9000

Boot Commands

I Ctrl/P I

>>> HALT
>>> D/I 14 E
>>> c
VAX 85x0/8700/88x0 1
VAX 6000 Series2
VAXstation 3520/35403

\/Av A~nn1A~i:;n2
- - -- - - - - - - - -

VAX 82x0/83x0
VAX-11/750
VAX-11n30 2

VAX-11/780
VAX-11n85

MicroVAX Systems2

>>> HALT
>>> D/I 14 E
>>> c

$ I Ctrl/P I
>>> HALT
>>> D/I 14 E
>>> c

$ ITiillII
>>> D/I 14 E
>>> c

$ ITiillII
>>> HALT
>>> DEPOSIT/I 14 E
>>> CONTINUE

Press and release the HALT
button on the CPU control panel,
or press the BREAK key (if
enabled) on the console terminal.
Then issue these commands:
>>> D/I 14 E
>>> c

Note that the console prompt for the VAX 8810/8820/8830 systems is PS-C/0-0> and not >».

2 These VAX systems accept only 1-character console commands.

3 Note that command C for VAXstation 3520/3540 systems will only continue the primary

processor. To continue all processors, use command CIALL.

13-8

Debugging a Device Driver
13.7 Examining the Vector-Jump Table

13.7

Examining the Vector-Jump Table
To gain familiarity with the I/O database, you might wish to look for the
address of the location in the channel request block that contains a JSB
instruction to the driver's interrupt service routine. You can do this at a
controller initialization breakpoint because one of the inputs is the IDB
address. The procedures for locating the driver interrupt service routine
on non-direct-vector and direct-vector adapters follow.
Non-Direct-Vector Procedure
R5/ IDB-address Q+lO/ADP-address
Q+lO/vector-table-address
Q+vector-address-in-hex/ address-of-JSB-instruction-in-CRB
Q! JSB-instruction

Direct-Vector Procedure
R5/ IDB-address
Q+lO/ADP-address
Q+lO/vector-table-address
Q+vector-address-in-hex+2/ address-of-JSB-instruction-in-CRB
Q! JSB-instruction

Finding the address of the driver's interrupt service routine at the
expected vector does not guarantee that an interrupt from the device
will dispatch to the driver's interrupt service routine. If the device's
physical vector is set to some other address, an interrupt from the device
can dispatch to some other interrupt service routine, or dispatch to an
unassigned vector.
See the SYSGEN device table shown in Table 12-2 for a list of vectors.
Consult Digital customer service for help with any problem similar to the
one described above.

13.8

Setting an XDELTA Base Register
During a driver debugging session, you can use an XDELTA relocation
register as a base from which to examine driver code and set breakpoints
within the driver. Use one of the methods outlined in Section 13.5 to
determine the base address of driver code, then set a relocation register by
issuing the following command:
driver-base-address,O;X

IReturnl

This command sets relocation register XO to the base of driver code. Now
you can examine offsets into the code using XO as a base:
XO + offset/ nnnnnnnn

or
XO +offset! instruction

XDELTA also uses the base register to display address values in the base
register plus offset format. Suppose, for example, that your driver contains
the following code:

13-9

Debugging a Device Driver
13.8 Setting an XDELTA Base Register

50
20
7A

SF
82

81
10
50
F6
50
FO
50
EB

90
13
91
19
91
14
90
11

OOD3
OOD6
OOD8
OODB
OODD
OOEl
OOE3
OOE6

132 10$:
133
134
135
136
137
138
139

MOVB
BEQL
CMPB
BLSS
CMPB
BGTR
MOVB
BRB

(Rl)+,RO
20$
RO,#"A/ I
10$
RO,#"A/Z/
10$
RO, (R2) +
10$

If base register 0 contains the base address of your driver, the following
XDELTA dialogue is possible:
XO+D3,XO+E6! XO+D3/MOVB (Rl)+,RO
XO+D6/BEQL
XO+E8
XO+D8/CMPB
R0,#20
XO+DB/BLSS
XO+D3
R0,#7A
XO+DD/CMPB
XO+El/BGTR
XO+D3
XO+E3/MOVB
RO, (R2) +
XO+E6/BRB
XO+D3

To set breakpoints in driver code, use the following command:
XO + offset;B

IReturnl

To display a driver instruction and set a breakpoint, add the instruction's
offset to the base register. For example:
XO+lC! instruction

•; B

I Return I

The last XDELTA command sets a breakpoint at the displayed location.
See Section 13.10 or the VMS Delta/XDelta Utility Manual for a detailed
discussion of XDELTA commands.

13.9

Examining the UCB, IRP, or PSL
In addition to using XDELTA to debug drivers, you can also examine the
contents of the UCB and the associated IRP.
It is also useful to examine the contents of the PSL at the time of a system
failure. The PSL, for example, indicates the IPL at the time. When the
system fails, it prints the PSL and other register contents on the console
terminal.

While the system is running, the following command can be used to
examine the PSL in XDELTA:
RF+4/

The PSL location is stored in the longword following the PC.

13.10

XDELTA Commands
Table 13-4 summarizes XDELTA commands. The sections that follow this
table describe the commands.

13-10

Debugging a Device Driver
13.10 XDELTA Commands

Table 13-4 XDELTA Command Summary
Command

Function

Set Display Mode

Set byte mode

Set word mode

Set longword mode
Set instruction mode

Set ASCII mode
Set and Proceed from Breakpoint
;P

Proceed from breakpoint

Set/clear/display breakpoint

Open, Examine, and Close Location
I

Open location (display contents in current mode)
Open location (display contents as instructions)

IReturn I
ICrtl/JI
ITabI
ICrtl/31

Close current location
Close current location; open next
Open location specified by current value
Display previous location

Deposit in Location

'string'

Deposit string at current location, autoincrementing the current location
symbol (. ). Every carriage-return and line-feed character typed will be
stored. An apostrophe terminates the string.

Step, Set Location, and Execute Code

Execute one instruction, step into subroutine call

Execute one instruction, step over subroutine call (on CALLx, JSB, or
BSBx instruction)

Go to location and proceed

Execute command string at location

Special Symbols

Field separator

Last quantity displayed
Display value of expression; set Q
(continued on next page)

13-11

Debugging a Device Driver
13.10 XDELTA Commands

Table 13-4 (Cont.)
Command

XDELTA Command Summary

Function

Special Symbols

Base register n

Set base register

Processor register n

Add "X80000000 to subsequent or preceding value

Add "X7FFEOOOO to subsequent or preceding value
Current location

Operators

Add
Subtract

space

Add

Multiply

Shift

Divide

Miscellaneous

List names and locations of loaded executive images

13.10.1 Values and Expressions
All numeric values are interpreted in hexadecimal radix. Expressions are
strings of alternating values and binary operators, where the first and last
items in the string are always values, as in the following example:
G4A32 + 24 -

XDELTA evaluates expressions from left to right with no precedence, and
ignores trailing operators. To display the value of an expression, use the
XDELTA Show Value ( =) command, as follows:
Syntax
expression= value-of-expression

Type an expression followed by an equal sign ( =). The expression can be
composed of a series of values and operators from the set of operators
listed in the command summary. XDELTA shows the value of the
expression according to the current display data type. The last quantity
( Q) is set to the value of the computed expression.

13-12

Debugging a Device Driver
13.10 XDELTA Commands

13.10.2 Special Symbols
XDELTA defines the following special symbols:
Current location; set by slash (/ ), exclamation point (I), and Tab
operations.
Q

Last quantity displayed; you can also change this value by using the
Show Value ( =) command described in Section 13.10.1.

XO-XF

Base registers; used for remembering values. Set base registers by
means of the Set Base Register command ( ;X ) described in Sections
13.8 and 13.10.2.3. XDELTA, by default, stores special values in base
registers X4 and X5 that help reference the process control block of
the current process (see Section 13.10.2.1 ). Also, XDELTA initializes
XE and XF with special commands that help reference page-frame
numbers, as described in Section 13.10.2.2.

RO-RF

General register names.

PO-Pnn

Internal processor registers.

RF+4

PSL.

"X80000000; prefix for system space addresses; for example, G2E is
equivalent to "X8000002E.

"X7FFEOOOO; prefix for control region prefix; for example, H2E is
equivalent to "X7FFE002E.

13.10.2.1

Stored Base Registers
XDELTA defines two base registers useful in system debugging: X4 and
X5. Base register X4 contains the address of the location that contains the
address of the PCB of the current process on the current processor. Base
register X5 corresponds to the global symbol SCH$GL_PCBVEC, which
contains the starting address of the list of PCB slots.

13.10.2.2

Stored Command Strings
XDELTA contains two predefined command strings whose addresses are
contained in base registers XE and XF. You can use these commands
during general system debugging as well as driver debugging; they
perform the following functions:
XE

Use the value of base register XO as a page-frame number and display the
PFN database for that page

Set base register XO to the value (PFN) in RO and perform the same function
as XE

You must initialize the stored commands to set the relocation registers
they use (X6 to XD ). Issue the following commands:
XE;E
XF;E

!Return!
IReturnl

After executing these commands, you can use the commands stored in XE
and XF to obtain the following information about a page-frame number:
•

Specified physical page number (PFN)

•

PFN state

•

PFN type
13-13

Debugging a Device Driver
13.10 XDELTA Commands

13.10.2.3

•

PFN reference count

•

PFN backward link/working set list index

•

PFN forward link/share count

•

Page-table entry (PTE) pointer to PFN

•

PFN backing store address

•

Virtual block number in process swap image

Setting Base Registers
Syntax
address-expression,n;X

!Return)

Type an expression followed by a comma ( , ), a single digit between 0 and
D (hexadecimal), a semicolon ( ; ), and the letter X. XDELTA assigns the
specified expression to the base register selected by n. XDELTA confirms
that the base register is set by displaying the value deposited in the base
register.
Whenever XDELTA displays an address located close to an address stored
in a base register, XDELTA displays the base register identifier (Xn),
followed by an offset that gives the address's location in relation to
the address stored in the base register. For example, if base register
2 (X2) contains 800D046A and the address XDELTA needs to display
is 800D052E, XDELTA displays X2+C4. XDELTA computes relative
addresses for opened or displayed locations and addresses that are
instruction operands.
XDELTA displays an address in base register plus offset format to a
distance of 8001 s from the base register. If the address falls outside this
range, XDELTA displays it as a hexadecimal value.

13.10.3 Display Names and Locations of Loaded Executive Images
Syntax
;L

Use the ;L command to list the names and locations of the loaded modules
of the VMS executive. If you issue the ;L command before all the executive
images are loaded (for example, at an XDELTA initial breakpoint), only
those images that have been loaded will be displayed.

13.10.4 Set Display Mode
Syntax

13-14

Byte width

Word width

Longword width

Debugging a Device Driver
13.10 XDELTA Commands

Instruction display (using longword width)

ASCII display (using current width)

Type a left bracket ( [) followed by one of the letters B, W, or L to change
the current display width to byte, word, or longword, respectively. The
default value is longword. The setting remains in effect until another
display mode control command is given. For example, the following
command displays the least significant byte contained at the specified
address and deposits the new value to that byte only.
address-expression [B/

old-value

new-value

Type a left bracket ( [ ) followed by the letter I to change the current
display mode to instruction format. This command is equivalent to the
exclamation point ( ! ) command and, similarly, is canceled by typing
a slash (I) or a quotation mark ( " ). Instruction mode sets display mode
storage units to longword values. For an example of an instruction display,
see Section 13.8.
You can display contents of memory locations in ASCII characters by
typing an address expression followed by a quotation mark ( " ).
address-expression"

old-value-in-ASCII

Pressing Ctrl/J displays the next location in ASCII.
The display mode remains set to ASCII until the next slash (I) or
exclamation point ( ! ) command. At this point, the display mode reverts to
hexadecimal. The width remains unchanged.

13.10.5 Open, Examine, and Close Location
XDELTA provides the commands described in the following sections to
open, examine, and close the specified memory locations.
13.10.5.1

Open and Display Value Command
Syntax
address-expression/old-value

[new-value-expression]

Type an address expression followed by a slash (I) character. XDELTA
displays the contents of the location (old-value above), followed by a
space. You can change the value at the location by typing a new value and
then pressing Return. If you press the Return key without preceding it
with a value, the old contents remain unchanged.
The display and the value deposited default to longword hexadecimal
values. The length can be changed to byte or word with the set mode
commands.
A slash preceded by a null address expression uses the displayed value
( Q) as the address value. This feature is convenient for following address
linked chains, as follows:
address-expression/old-value

/old-value

13-15

Debugging a Device Driver
13.10 XDELTA Commands

13.10.5.2

Display Instruction Command
Syntax
address-expression! decoded-instruction

Type an address expression followed by an exclamation point ( ! ). XDELTA
displays the contents of memory as a VAX MACRO instruction starting
with the address you specify.
XDELTA does not make any distinction between reasonable and
unreasonable instructions or instruction streams; the decoding always
begins at the specified address. The display instruction command does not
allow you to modify the displayed location. The command sets a flag that
causes subsequent close and display next or indirect location commands
to perform instruction decoding. You can reset the flag with the open and
display value command.
Whenever an address appears as an instruction operand, XDELTA sets
the last quantity displayed ( Q) to that address. XDELTA changes Q only
for operands that use program counter or branch displacement addressing
modes; Q is not altered for literal and register addressing modes. This
feature is useful for following branches, as follows:
address-expression! BRW address-2

13.10.5.3

! instruction-at-address-2

Close and Display Next Location Command
Syntax
I Ctrl/J I
address/old-value

Press Ctrl/J. XDELTA closes the current open location, then opens and
displays the value in the next location, according to the current display
mode.
If instruction display is the current mode, XDELTA does not deposit a
value in the open location. The next location is the first location after the
instruction currently displayed. If value display is the current mode, you
can deposit a value into the open location. In this case, the next location
is the current location, incremented by the current data width (byte, word,
or longword).
13.10.5.4

Display Range Command
Syntax
start-addr-expression,end-addr-expression/ contents-of-start

or
start-addr-expression,end-addr-expression! contents-of-start

Type two address expressions separated by a comma and followed by
a slash (I) or exclamation point ( ! ). XDELTA displays the range of
addresses, using the specified display mode (value or instruction). If you
specify instruction display, XDELTA decodes one or more instructions.
Otherwise, XDELTA displays the contents of each location in the current
data type (byte, word, or longword).

13-16

Debugging a Device Driver
13.10 XDELTA Commands

13.10.5.5

Indirect Command
Syntax
~
address/old-value

Press Tab. XDELTA uses the last quantity displayed ( Q ) as an address
and displays that address and its contents using the current display
mode. This command opens locations in the same way as the slash (I) and
exclamation point ( ! ) commands, but prints the information on a new line
and displays the address value before showing the address's contents.
13.10.5.6

Display Previous Location Command
Syntax
~
address/old-value

Press Crtl/3. Unless the current display mode is instruction, XDELTA
decreases the location counter by the current data width, and displays the
contents of the resulting location using the current data width and type.
This command is ignored in instruction display mode.

13.10.6 Breakpoints
XDELTA uses the following commands to set and clear breakpoints,
display a list of set breakpoints, continue from a breakpoint, and set a
complex breakpoint.
13.10.6.1

Setting Breakpoints
Syntax
address-expression;B

IReturnl

Type an address followed by a semicolon ( ; ) and the letter B, then press
Return. XDELTA sets a breakpoint at the specified location and assigns it
the first available breakpoint number.
Alternate Syntax
address-expression,n;B

Type an address followed by a comma, a single digit between 2 and 8,
a semicolon (; ), the letter B, and then press Return. XDELTA sets a
breakpoint at the specified location and assigns it the specified breakpoint
number. Breakpoint 1 is reserved for INI$BRK.
Before XDELTA executes the instruction as a breakpoint, it suspends
normal instruction processing, sets a flag that causes subsequent close
and display next or indirect location commands to perform instruction
decoding, and displays the following message:
n BRK at address
address/decoded-instruction

You can now enter XDELTA commands. You can reset the flag that
controls instruction display mode by issuing the open and display value
command.
13-17

Debugging a Device Driver
13.10 XDELTA Commands

13.10.6.2

Clearing Breakpoints
Syntax
O,n;B

IReturnl

Type zero ( 0) followed by a comma, a single digit between 2 and 8, a
semicolon ( ; ), the letter B, and then press Return. XDELTA clears the
specified breakpoint. Never clear breakpoint 1.
13.10.6.3

Displaying Breakpoint List
Syntax
;B

jReturnl

Type a semicolon ( ; ) followed by the letter B. XDELTA shows the current
settings of all breakpoints. For each breakpoint, XDELTA displays the
following information:

13.10.6.4

•

Breakpoint number

•

Address at which the breakpoint is set

•

Display address (for complex breakpoints; see Section 13.10.6.5)

•

Command string address (for complex breakpoints)

Proceeding from Breakpoints
Syntax
;P

I Return l

Type a semicolon ( ; ) followed by the letter P, and then press Return.
XDELTA continues executing at the current PC.
13.10.6.5

Setting Complex Breakpoints
Syntax

address-expression,n,display-addr-expression,cornmand-string-address;B lReturnl

Type an address expression followed by a comma, a single digit between
2 and 8, another address expression, and the address of a command
string. The first address is the breakpoint address; the digit equals the
breakpoint number. XDELTA shows the contents of the display address in
the current display mode when the breakpoint is reached. The command
string address specified i:D: the last command parameter executes after
automatic display.

13.10.7 Step, Set Location, and Execute Instruction Commands
The following XDELTA commands enable you to step through and execute
driver code.
13.10.7.1

Loading PC and Continuing
Syntax
address-expression;G

Type an address, a semicolon, and G, then press Return. XDELTA loads
the address into PC and continues executing at the new PC.
13-18

Debugging a Device Driver
13.10 XDELTA Commands

13.10.7.2

Execute Instruction and Step Command
Syntax

s
Type an S. XDELTA causes one instruction to be executed, then displays
the address of the next instruction and decodes that instruction.
This command also sets a flag that causes subsequent close and display
next or indirect location commands to perform instruction decoding. The
open and display value command resets the flag.
If the next instruction is BSBB, BSBW, JSB, CALLG, or CALLS, this
command steps into the subroutine and displays the first instruction
within the routine.
13.1O.7.3

Step Instruction over Subroutine Command
Syntax
0

Type an 0 (capital letter 0). XDELTA causes one instruction to be
executed, then displays the address of the next instruction and decodes
that instruction.
This command also sets a flag that causes subsequent close and display
next or indirect location commands to perform instruction decoding. The
open and display value command resets the flag.
If the next instruction is BSBB, BSBW, JSB, CALLG, or CALLS,
XDELTA executes the entire subroutine and displays the instruction
that immediately follows the subroutine call; this command steps over
subroutines.

13.10.8 Execute String Command
Syntax
address-expression;E

!Return!

Type an address expression followed by a semicolon, the letter E, then
press Return. This command executes the ASCII commands found at the
specified address expression. If you terminate the ASCII commands with
a semicolon followed by the letter P, XDELTA will proceed with program
execution. If you terminate the string with null (1 byte of 0), XDELTA
waits for a new command.
To create command strings, open the address of the start of the string and
deposit ASCII text as follows:
address/ old-contents

'XDELTA-corrnnand'

You can use any XDELTA command, including Return, CtrVJ, and Tab.
To terminate the string with a null, follow the above command with
. I old-contents 0 I Return I

13-19

Debugging a Device Driver
13.10 XDELTA Commands

You can preassemble command strings within your experimental driver.
Locate the addresses of these strings as you would any other address
within your driver.
13.10.8.1

Locating Nonpaged System Patch Space

When debugging a non-Digital-supplied device driver with XDELTA, you
may need to construct a complex breakpoint or store an XDELTA command
string in nonpaged system patch space.
Each of the loadable images of the executive contains an area reserved as
nonpaged system patch space. In each loadable image, the symbol PAT$A_
NONPAGED contains a descriptor that identifies the location and size of
the unused nonpaged system patch space in that image. This descriptor
has the following form:
PAT$A_NONPAGED::
.LONG
.LONG

size-in-bytes
off set to patch-space-start-address

A suitably privileged process can access unused system patch space in
any of the loadable images of the VMS executive. To determine the size
of patch space and its starting address in any given loadable executive
image, perform the following steps:
1

Issue the following commands to display a list of all images of the
VMS executive that have been loaded into memory:
$ ANALYZE/SYSTEM
SDA> SHOW EXECUTIVE
SDA> EXIT

The XDELTA command ;L also displays a list of the loaded images.
2

Note the base address of the image whose patch space you want to use.
For example, you may have selected PROCESS_MANAGEMENT and
determined its base address to be 80127C0016 ;

Determine the image value of the nonpaged system patch space
descriptor (PAT$A_NONPAGED) in the selected image.
For example, to determine the image value of PAT$A_NONPAGED in
PROCESS_MANAGEMENT, issue the following commands from the
DCL prompt:

$
$

ANALYZE/IMAGE/OUT=TEMP.DAT SYS$LOADABLE IMAGES:PROCESS MANAGEMENT.EXE
SEARCH/WIND TEMP.DAT PAT$A_NONPAGED
-

Suppose these commands determine the image value of
PAT$A_NONPAGED in SYS$LOADABLE_IMAGES:PROCESS_
MANAGEMENT.EXE to be 654416.
4

Use the Patch Utility to locate PAT$A_NONPAGED in the image and
examine its contents.
The following commands locate and examine PAT$A_NONPAGED in
SYS$LOADABLE_IMAGES:PROCESS_MANAGEMENT.EXE:

13-20

Debugging a Device Driver
13.10 XDELTA Commands

$ PATCH/NOJOURNAL SYS$LOADABLE_IMAGES:PROCESS_MANAGEMENT.EXE
PATCH> EXAMINE 6544
00006544:
00000077
PATCH> EXAMINE
00006548:
OOOOOF85
PATCH> EXIT

In this example, the Patch Utility output shows that there are 771a
bytes remaining in the nonpaged system patch space of PROCESS_
MANAGEMENT and that the available patch space starts at offset
F851a into the image.
5

Calculate the starting address of nonpaged system patch space in
the selected loadable executive image by adding the offset from the
descriptor to the base address of the image you determined in step 2.
For instance, the base address of nonpaged system patch space
in SYS$LOADABLE.~IMAGES:PROCESS_MANAGEMENT.EXE is
80127C0016 +F8516 , or 80128B851a-

13.11

Guidelines for Debugging Device Drivers
The following sections discuss errors commonly made during debugging
sessions and describe additional debugging techniques.

13.11.1 Opening Device Registers in XDELTA
References to 16-bit device registers must be word instructions; references
to 8-bit device registers must be byte instructions. These restrictions
apply to the XDELTA EXAMINE command; therefore, be sure to set the
correct mode control before examining device registers. For example, if the
address of the device CSR is in R4, give the following command:
R4/ csr_address

[W/ csr_contents

13.11.2 Adjusting the Device Timeout Value
When single-stepping through driver code using XDELTA, it may be
necessary to adjust the device's timeout value (as specified in the
WFIKPCH or WFIRLCH macro) so that it is large enough to keep the
device from timing out. When the driver debugging is complete, this value
should be reset to a reasonable length of time.

13.11.3 XDELTA and System Failures
Driver errors can cause the operating system to suspend activity in such
a way that you cannot invoke XDELTA. In this case, the only recourse is
to induce a system failure. Follow the procedure described in the VMS
System Dump Analyzer Utility Manual; the system will signal a fatal
bugcheck.

13-21

Debugging a Device Driver
13.11 Guidelines for Debugging Device D,rivers

To gain control in XDELTA following a fatal bugcheck, stop in SYSBOOT
while initializing the system and clear the BUGREBOOT system
parameter. The system will stop in XDELTA, thereby allowing you to
examine the device UCB and other driver data to determine the driver
error.
Another, more thorough, way to determine the cause of a system failure
is to leave the BUGREBOOT system parameter set, allow the system
to reboot, and then invoke the System Dump Analyzer (SDA) Utility to
examine the condition of the 1/0 data structures at the time of the fatal
bugcheck. The VMS System Dump Analyzer Utility Manual provides
detailed information on fatal bugcheck stack format and how SDA can
help debug a device driver.

13.12

Common Driver Errors
This section describes errors commonly made in drivers.

13.12.1 References to System Addresses
References by drivers to system addresses within the executive must use
general addressing (GA ) mode. For example, use
JSB

GAINI$BRK

13.12.2 Incorrect References to Device Registers
A common driver error is to access a nonexistent device register or to
access the correct register with an instruction using incorrect length. On
VAX systems that use direct-vector interrupts, these references cause a
fatal machine check exception. On VAX systems using non-direct-vector
interrupts, these references cause a UNIBUS adapter error interrupt. The
system logs the adapter error and continues.
In many cases, the saved PC on the stack is the address of the instruction
that caused the error. In other cases (for example, when the offending
instruction is executed at IPL 31 ), the saved PC is not the address of this
instruction but an address some number of instructions later, when the
system actually services the interrupt.

13.12.3 Destroying Register Contents
Because the driver frequently calls VMS 1/0 routines, you must be careful
to anticipate the register usage of these routines. Most VMS common 1/0
support routines use RO to R3 freely. A frequent driver bug is to load a
value into R3 and expect to find it intact after a call to allocate or load
adapter resources.
Other VMS 1/0 routines write into R4. In some cases, the use of R4 is
obvious; for example, IOC$REQSCHANL writes the device's CRB address
into R4. In other cases, you might not anticipate the use of R4.

13-22

Debugging a Device Driver
13.12 Common Driver Errors

For example, EXE$10FORK saves the calling code's R4 in a fork block, and
then writes the device's IPL into R4. Because the normal flow of events is
that an interrupt service routine restores a driver with a JSB instruction
and the driver then calls EXE$IOFORK which returns to the interrupt
service routine, the instructions following the JSB in the interrupt service
routine can only assume R5 is still untouched. The coding sequence is as
follows:
MOVQ
JSB

UCB$L FR3(R5),R3
@UCB$L_FPC(R5)

;Restore R3-R4.
;Restore the driver process

;Between these instructions, the interrupt service routine
;can make no assumptions about the contents of RO to R4.

POPR
REI

13.13

#AM<RO,Rl,R2,R3,R4,R5> ;Restore interrupt registers
;Return from the interrupt

Pool Checking Mechanism
Certain system failures cannot easily be traced to a single instruction or to
a single piece of kernel-mode code. If a device driver, for example, accesses
memory that it has not properly allocated or continues to use memory
that it has deallocated, a system failure can occur long after the driver
has completed its activity. The system may crash when another operating
system thread executes and attempts to use the corrupted data.
Special pool checking code in the VMS memory allocation and deallocation
modules can help isolate problems of this sort reliably and quickly. In
a normal VMS system, this code is disabled. For a system experiencing
frequent and inexplicable failures, you can enable pool checking by setting
the POOLCHECK system parameter.
When enabled, pool checking routines execute whenever pool is deallocated
or allocated. 1
·
On any deallocation of pool using the pool allocation routines2 , the
routine fills the deallocated packet with a "free" pattern specified in the
POOLCHECK system parameter. The first five longwords of the packet
are not filled, but instead contain the following information:
•

Forward and backward links into the free list

•

Size, type, and subtype fields

•

Address of the code that deallocated the packet

•

Checksum

The pool allocation routines (EXE$ALLOCBUF, EXE$ALLOCIRP, EXE$ALONONPAGED,
COM$DEANONPAGED, EXE$DEANONPAGED, and so on) are discussed in VMS Deuice Support
Reference Manual. These routines are the only means recommended by Digital for allocating pool.
2
A small number of VMS facilities use other methods of obtaining pool. The pool allocated by these facilities
is, by consequence, exempt from the pool checking mechanism.

13-23

Debugging a Device Driver
13.13 Pool Checking Mechanism

On any allocation from pool, the routine verifies the checksum and ensures
that the packet still contains the "free" pattern. If the pattern is still
intact, the routine replaces the "free" pattern with an "allo" pattern, also
specified in the POOLCHECK system parameter. The two patterns allow
allocated, uninitialized pool to be distinguished from nonallocated pool.
If the "free" pattern is not intact, the pool checking routine induces a
POOLCHECK bugcheck, assuming that some code has modified the packet
while it was on the free list.
Figure 13-1 illustrates the format of the POOLCHECK system
parameter.
Figure 13-1

Format of the POOLCHECK System Parameter

allo

free

flags
ZK-6618-GE

The flags byte indicates the actions that the pool checking code should
take whenever pool is allocated or deallocated. It also indicates the type of
pool to be subject to checking. The following bit masks are defined:
Flag Bit

Bit Mask (hex)

Action

At deallocation, fill variable pool packets with free pattern.

At allocation, check packets for free pattern and, if the pattern is intact, fill
with allo pattern. If not, induce POOLCHECK bugcheck.

At deallocation, fill SRPs with free pattern.

At deallocation, fill IRPs with free pattern.

At deallocation, fill LRPs with free pattern.

Validate the lookaside list deallocation when the associated bit (2, 3, or 4)
is set. Validation ensures that the packet address is on a proper boundary
before the packet is deallocated to the free list.

At deallocation, fill P1 /PO-space buffers with free pattern. Note that the DCL
lexical function F$SEARCH and the NETACP process do not function properly
whenever this bit is set.

The free byte indicates the character to be inserted in a packet (except
for its header) when it is deallocated to free pool. Select a value that will
facilitate examining pool with SDA (and also could not be interpreted by
the system as a valid address): for instance, an ideal value would be "d"
(6416), for "deallocated".

13-24

Debugging a Device Driver
13.13 Pool Checking Mechanism

Note: If, during a single bootstrap, you enable pool checking with a
certain free byte value, disable it, and then later reenable it
with the same free byte value, the system may signal spurious
POOLCHECK bugchecks. After pool checking has been reenabled
in this manner, the pool checking mechanism may encounter an
allocation of pool which only partially contains the free pattern,
because of a deallocation that occurred when checking was
disabled.
The allo byte indicates the character to be inserted in a packet (if bit 2 of
the flags byte is set) when it is allocated. Select a value that will facilitate
examining pool with SDA (and also could not be interpreted by the system
as a valid address): for instance, an ideal value would be "a" (6l1a), for
"allocated."

It is possible that, when first enabled on a system, the pool checking
mechanism will discover specific violations of pool allocation and
deaHocation protocol. In investigating subsequent crashes using SDA, you
should first check the value of the global longword EXE$GL_POOLCHECK
to determine whether pool checking has been enabled and, if so, which
packets it has been enabled for and which patterns it is using.
One of the results of the pool checking mechanism is the occurrence
of a fatal system bugcheck such as INVEXCEPTN, SSRVEXCEPT, or
FATALEXCPTN whenever kernel-mode code attempts to use an address in
free pool. When these exceptions signal an access violation and the free
pattern appears as the violating address in the exception's signal array,
the exception PC has been caught in the process of using deallocated pool.
The pool checking mechanism explicitly generates a POOLCHECK
bugcheck for one of several reasons. A reason value is pushed onto the
top of the stack as follows:
Longword
Value

Reason

Corrupt packet
Bad alignment

Bad alignment of lookaside list element

Paged block partially outside paged pool

Nonpaged block partially outside nonpaged pool

IPL too high

Corrupt packet

From the top-of-stack, a reason value of 0 indicates a pool packet being
allocated might have been corrupted while on the free queue. There are
several causes of a corrupt packet bugcheck. You can obtain information
about the crash from the contents of general registers as well as from the
pool packet itself.

13-25

Debugging a Device Driver
13.13 Pool Checking Mechanism

At the time of the crash, the following registers contain relevant
information:
Register

Contents

Allocation (allo) pattern

Deallocation (free) pattern

Address of packet being allocated

Number of longwords remaining in packet to be checked

Address in packet where the pool checking code discovered
corrupted pattern

Checksum, computed as the sum of the address of the packet,
the deallocation pattern, the third and fourth longwords of the
packet, and a longword within the system boot time quadword
(EXE$GQ_BOOTIME)

Because the address of the packet is in R2, you can attempt to format R2
to see what type of structure the pool is being allocated for. The following
SDA commands accomplish this:
SDA>
SDA>

READ SYS$SYSTEM: SYSDEF. STB
FORMAT @R2

If this does not identify the structure, you may obtain some information
from the packet itself, as pictured in Figure 13-2.
Figure 13-2 Poisoned Pool Packet

Subtype

Type

Forward link

Backward link

Size

Address of deallocating routine*

Packet checksum

Poison pattern (20 bytes)

~~ 20

*Note that the deallocation routine is only valid when the packet is from a lookaside list.
To determine what code may have corrupted the packet, it may be helpful
to examine the contents of R4 (the address at which the pool checking
routine found a corrupted pattern). If this address contains an address,
it is a fair assumption that it was placed there by code that uses that
address.

13-26

Debugging a Device Driver
13.13 Pool Checking Mechanism

In addition, the routine that deallocated the packet may be a likely
suspect. Bugchecks can occur if you deallocate in pieces nonpaged pool
that you originally allocated as a unit. Frequently, pool is corrupted by a
device driver that deallocates pool and later attempts to use the pool that
it has deallocated.
Bad alignment

A top-of-stack longword value of 1 indicates that the lookaside list element
being deallocated is not aligned on the boundary defined by constant
EXE$C_ALCGRNMSK. The memory address to be deallocated is stored in
RO.
Bad alignment lookaside list element

A top-of-stack longword value of 2 indicates that the lookaside list element
being deallocated is misaligned. Specifically, a valid lookaside packet
address was not supplied to the routine. At the time of the crash, the
following registers contain relevant information:
Register

Contents

Starting address of memory to be deallocated

Size of list elements

Starting address of lookaside list

Paged block partially outside paged pool

A top-of-stack longword value of 3 indicates the paged block being
allocated is partially outside of paged pool. This bugcheck indicates
that the memory starts in paged pool, but ends outside of paged pool. At
the time of the crash, the following registers contain relevant information:
Register

Contents

Starting address of block

Size of block

Ending address of block

Nonpaged block partially outside nonpaged pool

A top-of-stack longword value of 4 indicates the nonpaged block being
allocated is partially outside nonpaged pool. This bugcheck indicates
that memory being allocated starts in nonpaged pool, but ends outside of
nonpaged pool. At the time of the crash, the registers shown in the table
above contain the same relevant information.
IPL too high

A top-of-stack longword value of 5 indicates the IPL was above IPL$_
ASTDEL when an attempt was made to allocate or deallocate Pl space.

13-27

Debugging a Device Driver
13.14 Detecting Driver Problems in a Multiprocessing System

13.14

Detecting Driver Problems in a Multiprocessing System
When testing a new driver that has been designed to run in a VMS
multiprocessing environment, it is a good idea to ensure that the
system in which the driver is being tested is running the full-checking
synchronization image. You can cause the full-checking synchronization
image to be loaded at boot time on either a VAX uniprocessing
system or multiprocessing system by the appropriate setting of the·
MULTIPROCESSING system parameter, as listed in Table 13-5.
Table 13-5 Settings of MULTIPROCESSING System Parameter
Value

Result

Loads uniprocessing synchronization image for any hardware configuration.
Loads full-checking synchronization image and sets multiprocessingenabled bit (SMP$V_ENABLED in SMP$GL_FLAGS) if the hardware
configuration is capable of multiprocessing and two or more processors are
available; otherwise, loads uniprocessing synchronization image.

Loads full-checking synchronization image and sets multiprocessingenabled bit regardless of the hardware configuration.

Loads streamlined synchronization image and sets multiprocessingenabled bit if the hardware configuration is capable of multiprocessing
and two or more processors are available; otherwise, loads uniprocessing
synchronization image. This is the default value.

In a processing environment with the full-checking synchronization image
loaded, violation of spin lock synchronization by a device driver will
produce the bugchecks described in Table 13-6.
Table 13-6
SPLIPLHIGH

Bugchecks Produced by Full-Checking Multiprocessing
A processor has attempted to acquire a spin lock at an IPL higher
than the IPL associated with spin lock synchronization (SPL$B_IPL).
SMP$ACQUIRE (called by the LOCK and FORKLOCK macros with
condition=NOSETIPL not specified) signals this bugcheck.
A processor has attempted to acquire a device lock-not already
owned by the acquiring processor-at an IPL higher than the
IPL associated with device lock synchronization (SPL$B_IPL).
SMP$ACQUIREL (called by the DEVICELOCK macro with
condition=NOSETIPL not set) signals this bugcheck.

SPLIPLLOW

A processor has attempted to conditionally or unconditionally release
a spin lock or device lock at an IPL lower than the IPL at which it
originally acquired it. SMP$RELEASE and SMP$RESTORE (called
by the UNLOCK and FORKUNLOCK macros) and SMP$RELEASEL
or SMP$RESTOREL (called by the DEVICEUNLOCK macro) signal
this bugcheck.
(continued on next page)

13-28

Debugging a Device Driver
13.14 Detecting Driver Problems in a Multiprocessing System

Table 13-6 {Cont.)

Bugchecks Produced by Full-Checking
Multiprocessing

SPLACQERR

A processor has attempted to acquire a spin lock while holding
a higher ranked spin lock. SMP$ACQUIRE, SMP$ACQUIREL,
and SMP$ACQNOIPL (called by the LOCK, FORKLOCK, and
DEVICELOCK macros) signal this bugcheck.

SPLRELERR

An attempt has been made to completely release a spin lock
not owned by the releasing processor. SMP$RELEASE and
SMP$RELEASEL (called by the UNLOCK, FORKUNLOCK, and
DEVICEUNLOCK macros) signal this bugcheck.

SPLRSTERR

An attempt has been made to conditionally release a spin lock
not owned by the releasing processor. SMP$RESTORE and
SMP$RESTOREL (called by the UNLOCK, FORKUNLOCK, and
DEVICEUNLOCK macros when condition=RESTORE is specified)
signal this bugcheck.

An examination of the crash dump resulting from any of these bugchecks
can help locate the cause of the crash. Enter the System Dump Analyzer
(SDA) and perform the following steps:
1

Issue the following command:
SDA>

READ/EXECUTIVE SYS$LOADABLE IMAGES

This command generates the symbols that correspond to locations
in the loadable images that are part of the VMS executive. These
symbols facilitate the interpretation of addresses that appear in the
stacks and other SDA displays.
2

Issue the following command:
SDA>

SHOW STACK

Trace through the current stack to determine what activities on the
processor led to the acquisition or release of the spin lock. Start at
high stack addresses and work towards low addresses, identifying
everything on the stack, or as much of it as required to decipher what
is going on.
3

Issue the following command:
SDA>

SHOW SPINLOCK/FULL/ADDR=@RO

This command produces a display of information about the spin lock
the executing code was trying to acquire or release, a list of PCs
indicating the addresses of the latest eight acquirers or releasers of the
lock, plus the PC of the last unconditional release of a set of multiply
nested spin lock acquisitions. Note the acquisition IPL and the rank of
the spin lock.
4

To decipher SPLIPLLO and SPLIPLHI bugchecks, compare the IPL at
which the system was running at the time of the crash to that shown
in the SHOW SPINLOCK display as required for acquisition of the
spin lock.

13-29

Debugging a Device Driver
13.14 Detecting Driver Problems in a Multiprocessing System

To decipher SPLACQERR, SPLRSTERR, and SPLRELERR bugchecks,
issue the following command:
SDA>

SHOW SPINLOCK/OWNED

In the case of SPLACQERR bugchecks, compare the rank of the spin
lock being sought with that of the currently owned spin locks.
In the case of SPLRSTERR and SPLRELERR bugchecks, determine
whether the releasing processing did not in fact own the spin lock it is
attempting to release.
Standard drivers seldom release spin locks and fork locks. When they do,
they should be careful to use the condition=RESTORE argument to the
UNLOCK and FORKUNLOCK macros when it is likely that the driver
code is executing at the behest of other code interested in retaining the
lock.
One error of which driver writers should be wary concerns the
unconditional release of a spin lock or fork lock for which there exist
multiple, nested acquisitions. When multiple acquisitions of a spin lock
accumulate for a processor, and one of the intermediate acquirers performs
an explicit release of that lock, all ownership of the lock by that processor
is entirely and immediately relinquished. If at least one of the original
acquisition threads still expects the lock to be held when that thread
regains control, system synchronization is broken. Moreover, when the
original thread that acquired the lock itself attempts to release the lock,
the system crashes with an SPLRELERR because the processor no longer
owns the lock being released.
If few attempts have subsequently been made by the processor to obtain or

release spin locks, you should be able to find the PC of the code that last
unconditionally released the spin lock in question in SHOW SPINLOCKS
/FULUADDRESS=@RO display. Issue the SDA command EXAMINE/INST
for each of the PCs in the display, from the top to the bottom, to determine
the recent history of the lock.

13-30

UNIBUS and Q22 Bus Device Support

This chapter provides information specific to the creation of drivers for
devices attached to the UNIBUS or Q22 bus. VMS provides extensive
support for UNIBUS/Q22 bus drivers, including many system routines
and macros that drivers can use to accomplish a multiblock transfer to a
DMA device by means of UNIBUS adapter/Q22 bus interface resources.
Section 14.1 explains the functions of the UNIBUS adapter and Q22 bus
interface, describing these resources in detail. Section 14.2 provides a
step-by-step account of how UNIBUS/Q22 bus device drivers can use the
facilities of VMS to accomplish DMA transfers.
Although the general mechanism of .ievice interrupt dispatching, as
defined by the VAX architecture and briefly described on Chapter 9, is
the same for all VAX processing systems and I/O subsystems, certain
implementation details differ. In that regard, Section 14.3 describes the
means by which VAX hardware and the VMS operating system deliver
a UNIBUS or Q22 bus device's interrupt to its driver's interrupt service
routine.

14.1

Functions of the UNIBUS Adapter and Q22 Bus Interface
The UNIBUS adapter connects the UNIBUS, an asynchronous,
bidirectional bus, to the backplane interconnect. The adapter performs
the following functions:
•

Arbitrates interrupts from UNIBUS devices according to their priority

•

Delivers interrupts from UNIBUS devices to the processor

•

Allows drivers to gain access to UNIBUS device registers using system
virtual addresses

•

Translates 18-bit UNIBUS addresses to physical addresses in main
memory

•

Provides a data-transfer path to randomly ordered physical addresses
in main memory

•

Provides buffered data transfer paths to consecutively increasing
UNIBUS addresses, thus optimizing CPU-to-UNIBUS data transfers

•

Permits byte-aligned buffers for UNIBUS devices requiring wordaligned buffer addresses

The Q22 bus closely resembles the UNIBUS. For MicroVAX systems
with an attached Q22 bus, special processor logic implements a Q22
bus interface that similarly allows drivers access to device registers and
manages device interrupts. Additional logic in the MicroVAX processor
establishes a scatter-gather map that translates 22-bit Q22 bus addresses
to physical addresses. However, Q22 bus systems do not implement

14-1

UNIBUS and Q22 Bus Device Support
14.1 Functions of the UNIBUS Adapter and Q22 Bus Interface

buffered data paths. Table 14-1 compares the UNIBUS and Q22 bus 1/0
subsystems of the various VAX and MicroVAX processing systems.
The protocol a VAX system uses to enable communications between its 1/0
bus and backplane permits its devices and device drivers to exchange data
without much awareness of the intervening hardware. First of all, both
the UNIBUS adapter and the Q22 bus interface provide access to device
registers using an address mapping scheme that is invisible to the driver.
In addition, when the configuration of the 1/0 interface has an impact on
the control of a data transfer, the driver can generally call one of the many
VMS routines that handle the details of the interface.
The functional differences between 1/0 adapters are irrelevant to devices
that do not perform DMA transfers. A driver that performs non-DMA
(programmed 1/0) transfers for a device on the UNIBUS can, with no
alteration, perform the same services for an equivalent device on a Q22
bus.
On the other hand, the differences between the functions of the UNIBUS
adapter and the Q22 bus interface are significant to those drivers that
manage DMA device operations.
Section 14.2 describes the means by which device drivers set up DMA
transfers, according to any of these interfaces. If a DMA driver that drives
similar devices on various VAX systems must secure some measure of
machine independence, it can include some run-time conditional code
that branches to appropriate routines in the driver that accomplish the
machine-dependent work. See the description of the ADPDISP macro in
the VMS Device Support Reference Manual and the sample drivers that
appear in Appendix C and Appendix D for guidance.
This section discusses the functions of the UNIBUS adapter and the Q22
bus, as follows:

14-2

•

The discussion of reading and writing device registers in Section 14.1.1
applies to UNIBUS and Q22 bus drivers.

•

The description of mapping 1/0 bus addresses in Section 14.1.2
pertains only to UNIBUS and Q22 bus DMA device drivers.

•

The description of buffering data transfers in Section 14.1.3 relates
mainly to UNIBUS drivers, although Section 14.1.3.1 contains
information relevant to Q22 bus drivers as well.

UNIBUS and Q22 Bus Device Support
14.1 Functions of the UNIBUS Adapter and Q22 Bus Interface

Table 14-1

Features of the UNIBUS Adapters/022 Bus Interfaces of VAX Systems
Memory
References
(Physical
Address)

Direct
Data Path

Buffered Data
Paths

Map
Registers

Interrupt
Dispatcher

30-bit (via
SBI)

1,
no bytealigned
transfers

15,
8-byte buffer,
byte-aligned
transfers,
LWAE, 3
prefetch

496

Nondirect-vector

UBI

24-bit (via
CMI)

1,
bytealigned
transfers

3,
4-byte buffer, 2
byte-aligned
transfers,
LWAE, 3
no prefetch

5124

Direct-vector

VAX-11/730

UBA

24-bit

1,
bytealigned
transfers

None

5124

Direct-vector

VAX 82x0/83x0
VAX 85x0/8700
/88x0

DWBUA

30-bit (via
VAXBI)

1,
bytealigned
transfers

5,
8-byte buffer,
byte-aligned
transfers,
LWAE, 3
no prefetch

512 4

Direct-vector

VAX 6000
series

DWMUA

30-bit (via
VAXBI)

1,
bytealigned
transfers

5,
8-byte buffer,
byte-aligned
transfers,
LWAE, 3
no prefetch

5124

Direct-vector

MicroVAX 3400
/3600/3900
series
VAX 4000
series

29-bit

1,
no
restrictions
on data
alignment1

None

8192

Direct-vector

MicroVAX II

24-bit

1,
no
restrictions
on data
alignment 1

None

8192

Direct-vector

System

Adapter

VAX-11/780
VAX-11/785
VAX 8600
VAX 8650

UBA

VAX-11/750

1 The MicroVAX 022 bus implementation provides no byte-offset register; so, on 022 bus devices that are only capable of
word-aligned transfers, only word-aligned transfers are possible.
2 Buffered data paths on the VAX-111750 only buffer four bytes of data.

Because the data paths do not perform a prefetch, they

can always reference longwords at random.
3 LWAE (longword access enable) refers to the capability to reference random longword-aligned data in a bus transfer.
4

The VMS operating system makes available only 496 of these map registers.

14-3

UNIBUS and Q22 Bus Device Support
14.1 Functions of the UNIBUS Adapter and Q22 Bus Interface

14.1.1

Reading and Writing Device Registers
Each 1/0 controller or device directly attached to a UNIBUS or Q22 bus
has a control and status register (CSR) and set of data registers. These
registers are assigned physical addresses in the 8Kb allocated for this
purpose from the 256Kb UNIBUS address space or in the Q22 bus 1/0
space. Device drivers obtain the device's status and activate the device by
reading and writing to these registers.
Because the VMS operating system maps this 1/0 space into virtual
address space, a device driver can treat the addresses of device registers
as identical to all other virtual addresses. The driver can read and write
data to the device's register as though the device's register were a location
in memory. The driver must use instructions within the restrictions
described in Section 5.2.
Before a driver for a device that shares a controller can gain access to a
device's registers, it must first obtain a controller channel, as described in
Sections 3.4.1 and 8.3.1.

14.1.2

Map Registers
DMA devices read and write data from and to memory locations using
18-bit UNIBUS addresses or 22-bit Q22 bus addresses.
A driver that performs multiblock DMA transfers for a UNIBUS device
or Q22 bus device must set up any mapping or buffering mechanisms
required by the system's 1/0 interface. For UNIBUS DMA drivers, this
involves setting up sufficient map registers and, perhaps, a buffered data
path prior to the transfer. Q22 bus DMA device drivers, likewise, must
allocate and fill a set of map registers.
For UNIBUS and Q22 bus devices, the UNIBUS adapter and the Q22
bus interface translate the bus addresses into main memory addresses,
thus allowing the operating system, 1/0 drivers, and UNIBUS devices
to access the same physical address space. DMA devices connected to
either a UNIBUS or a Q22 bus can access a block of memory indirectly
by means of the scatter-gather map supplied by the UNIBUS adapter
or MicroVAX processor, respectively. The map registers provided allow
the device to access scattered, physical memory addresses as contiguous,
physical addresses in 1/0 space.
When a device driver performs a DMA transfer, it allocates map registers
and a buffered data path (an option available to devices on the UNIBUS
of some VAX systems), and sets up the transfer by means of the device's
registers. The device then accesses memory directly by means of the 1/0
bus, transferring all the data requested. When the transfer is complete,
the device notifies the driver by requesting an interrupt.
Consider a buffer, for example, that consists of virtual pages 400, 401, 402,
and 403, which are physical pages 1003, 204, 1190, and 240, respectively.
For a UNIBUS or Q22 bus device to access this buffer, the driver requests
four map registers, then places the physical addresses of these pages in
the map registers. A field in each map register identifies the page-frame

14-4

UNIBUS and Q22 Bus Device Support
14.1 Functions of the UNIBUS Adapter and Q22 Bus Interface

number corresponding to the UNIBUS space or Q22 bus space address
that the map register represents (see Figure 14-1).
Figure 14-1

UNIBUS and Q22 Bus Map Registers

VAX -11/780, VAX-11/785, and VAX 8600/8650
31

26 25 24

21 20

Data
Path
Number

Reserved

.l C-

•

Page Frame Number

Byte offset
Longword Access Enable (LWAE)
VahdB1t

VAX-11/750, and VAX-11/730
31

26 25 24

22 21 20

MBZ

15 14

Reserved

•

l L

Page Frame Number

Data Path Number (for VAX-111750)
Byte Offset
Longword Access Enable (LWAE) for compatibility with
VAX-111780; unused on VAX-111750 and VAX-111730
Valid Bit

VAX 82x0/83xO, VAX 85x0/8700/88x0, and VAX 6000 Series
VAX 8200/8250/8300/8350, VAX 8530/8550/8700/8800/8810/8820/8830, and VAX 6000 Series
31

30 29

27 26 25 24 23

Reserved

21 20

Data
Path
Number

Page Frame Number

~1
Byte Offset
Longword Access Enable (LWAE)
VahdB1t

MicroVAX II
31

15 14
Reserved

Page Frame Number

T....._______ Valid Bit
MicroVAX 3400/360013900 Series
VAX 4000 Series
31

20 19
Reserved

Page Frame Number

.....__ _ _ _ _ _ Valid Bit
ZK-4842-GE

14-5

UNIBUS and Q22 Bus Device Support
14.1 Functions of the UNIBUS Adapter and Q22 Bus Interface

Assume the driver has allocated four map registers, 127 through 130. The
driver loads them as follows:
Map Register

Contents

127
128
129

1190

130

240

1003
204

Note that the VMS routine the driver calls to allocate map registers
automatically allocates an additional map register (register 131 in this
case). The map register loading routine clears this register in order to
prevent a runaway DMA transfer.
The device and the UNIBUS can transfer data into or out of these physical
pages without intervention by the driver. The device requests an interrupt
only when all the data in these four pages has been transferred.
Generally, a map register exists for each page of 1/0 space. Because
the UNIBUS address space consists of 256K of memory, minus the 8Kb
reserved for device control registers, 496 map registers are available for
UNIBUS DMA transfers. Q22 bus DMA devices can use up to 8192 of the
map registers that correspond to the 4MB of Q22 bus 1/0 space.
Drivers call VMS routines to fill as many map registers with valid pageframe numbers as needed for a DMA transfer. The DMA device puts
an address on the I/O bus. The UNIBUS adapter or Q22 bus interface
receives the address and translates it using the following information (see
Figures 14--2 and 14--3):
•

In UNIBUS addresses, the 9-bit UNIBUS page address field (bits 9
through 1 7 of the UNIBUS address) identifies the UNIBUS adapter
map register.
In Q22 bus addresses, the 13-bit Q22 bus page address field (bits 9
through 22 of the Q22 bus address) identifies the map register.

•

The page-frame-number (PFN) field in the map register specifies the
high-order bits of the physical address. (The PFN field is 15 bits long
for the MicroVAX II, VAX-11/750, and VAX-11/730; 20 bits long for the
MicroVAX 3400/3600/3900 and VAX 4000 series systems, and 21 bits
long for other VAX systems.)

•

From UNIBUS addresses, bits 2 through 8 map to bits 0 through 6
of the physical address. 1 The resulting physical address locates the
longword that is the target of the transfer.

The disposition of the lowest two bits of the UNIBUS address depends on the VAX system. For instance, the
VAX-111780 uses them to construct a byte-selection mask and function to be transmitted across UNIBUS
lines that modify the 1/0 transaction.

14-6

UNIBUS and Q22 Bus Device Support
14.1 Functions of the UNIBUS Adapter and Q22 Bus Interface

Figure 14-2 Mapping a UNIBUS Address to a Physical Address
18-Bit UNIBUS Address
.------------------1 Map Register Number Longword
Offset

UNIBUS
Adapter
Scatter-Gather
Map
32-Bit Map Register
Page Frame Number

Longword
Offset
Physical Address

Page Frame Number

ZK-0915-GE

From Q22 bus addresses (Figure 14-3), bits 0 through 8 map to bits
0 through 8 of the physical address. The resulting physical address
locates the byte that is the target of the transfer.
Each UNIBUS adapter or Q22 bus map register also contains a bit called
the map-register valid bit. The UNIBUS adapter or Q22 bus interface
tests this bit every time the map register is used. If the bit is not set, the
UNIBUS adapter or Q22 bus interface aborts the transfer. This bit is clear
whenever the register is not mapped to a physical address.

14.1.3

UNIBUS Adapter Data Transfer Paths
The UNIBUS adapter sends data through one of several data paths
for UNIBUS devices performing DMA transfers. One data path, the
direct data path (DDP), allows UNIBUS transfers to randomly ordered
physical addresses. The direct data path maps each UNIBUS transfer to
a backplane interconnect transfer. Thus, a single word or byte of data is
transferred for each backplane interconnect operation.

14-7

UNIBUS and Q22 Bus Device Support
14.1 Functions of the UNIBUS Adapter and Q22 Bus Interface

Figure 14-3

Mapping a Q22 Bus Address to a Physical Address
22-Bit 022 Bus Address

-----------------1 Map Register Number

Byte Offset

Scatter-Gather
Map

32-Bit Map Register
Page Frame Number

Page Frame Number

Byte Offset

24-Bit Physical Address (MicroVAX II)
29-Bit Physical Address
(MicroVAX 3400/3600/3900 Series;
VAX 4000 Series)
ZK-4841-GE

The remaining data paths, the buffered data paths (BDPs), allow devices
on the UNIBUS to transfer more efficiently than through the direct data
path. The buffered data paths store UNIBUS data so that multiple
UNIBUS transfers result in a single backplane interconnect transfer.
When a UNIBUS device begins a DMA transfer by placing an address on
the UNIBUS, the UNIBUS adapter not only performs address mapping
but also provides the number of the data path to be used for the transfer
(see Figure 14-1). Each UNIBUS adapter map register contains a field
that describes the data path. Data path 0 is the direct data path; the other
data paths are the buffered data paths. The UNIBUS data path registers
of the various VAX systems are pictured in Figure 14-4.
The following sequence describes a UNIBUS-device DMA transfer.

14-8

The UNIBUS device puts an address on the UNIBUS.

The UNIBUS adapter locates the UNIBUS adapter map register that
corresponds to the UNIBUS address.

UNIBUS and Q22 Bus Device Support
14.1 Functions of the UNIBUS Adapter and Q22 Bus Interface

Figure 14-4

UNIBUS Data Path Registers

VAX-111780, VAX 8600, and VAX 8650
31

30 29 28

23
Unused

1·L_

UNIBUS Address
< 17:2>

Spare

Data Path Function
Buffer Transfer Error
Buffernot em ptyI pug
re

VAX-111750
31 30 29 28

MBZ

Uncorrectable Error

Purge

- - - Nonexistent Memory Error
.....__ _ _ Error Summary

VAX 8200/8250/8300/8350, VAX 8530/8550/8700/8800/8810/8820/8830, and VAX 6000 Series
Data Path ControVStatus Register
31

21 20

24 23

Data
Path
Select

Address/Status Register
31

16 15

Buffa< Mlress

Flags

ZK-4843-GE

The UNIBUS adapter verifies that the map register has the mapregister valid bit set.

The UNIBUS adapter maps the UNIBUS address to a physical
address.

The UNIBUS adapter extracts the number of the data path to be used
for the transfer from the map register.

The UNIBUS adapter translates the UNIBUS function to a backplane
interconnect function by reading the UNIBUS control lines.

Based on the UNIBUS function indicated by the UNIBUS control
lines (DATI, DATIP, DATO, or DATOB), the UNIBUS adapter starts
appropriate UNIBUS and backplane interconnect operations to
transfer data between the UNIBUS device and memory.

14-9

UNIBUS and Q22 Bus Device Support
14.1 Functions of the UNIBUS Adapter and Q22 Bus Interface

14.1.3.1

Direct Data Path

Since the direct data path performs a backplane interconnect transfer for
every 1/0 bus transfer, it can be used by more than one UNIBUS or Q22
bus device at a time. The UNIBUS adapter or Q22 bus interface arbitrates
among devices that wish to use the direct data path simultaneously. The
device driver is unaffected by this arbitration.
The direct data path is less efficient than a buffered data path because
each 1/0 bus transfer cycle corresponds to a backplane intereonnect cycle.
One word or byte is transferred for each backplane interconnect cycle. On
some hardware configurations, the direct data path is unable to transfer
a word of data to an odd-numbered physical address. Therefore, an FDT
routine for a DMA device that uses the direct data path should check that
the specified buffer is on a word boundary. 2
The Q22 bus systems only employ a direct data path. A UNIBUS device
driver may choose to use a direct data path rather than a buffered data
path to perform the following functions:
•

Execute an interlock sequence to the backplane interconnect (DATIPDATO/DATOB)

•

Transfer to randomly ordered addresses instead of consecutively
increasing addresses

•

Mix read and write functions

The direct data path is the simplest data path to program. Since the direct
data path can be shared simultaneously by any number of 1/0 transfers,
the device driver does not need to call a VMS routine to allocate the data
path. Instead, the driver performs the following actions:

Uses the REQMPR macro to allocate a set of map registers (or the
REQALT macro to allocate a set of Q22 bus alternate map registers
(registers 496 to 8191) ).

Uses the LOADUBA macro (or LOADALT macro) to load the
map registers with physical address map data and, for UNIBUS
devices, the number of the direct data path ( 0 ). The VMS routines
called in the expansion of these macros (IOC$LOADUBAMAP and
IOC$LOADALTMAP respectively) also set the valid bit in every map
register except the last, which remains invalid to prevent a runaway
transfer.

Loads the starting address of the transfer in a device register.

Loads the transfer byte or word count in a device register.

Sets bits in the device CSR to initiate the transfer.

The MicroVAX implementation of the Q22 bus provides no byte-offset register. As a result, for Q22 bus
devices that are only capable of word-aligned transfers, only word-aligned transfers are possible.

14-10

UNIBUS and Q22 Bus Device Support
14.1 Functions of the UNIBUS Adapter and Q22 Bus Interface

14.1.3.2

Buffered Data Paths

When a buffered data path is used, the UNIBUS adapter transfers
data much more efficiently between the UNIBUS and the backplane
interconnect than when a direct data path is used. It accomplishes this
by decoupling the UNIBUS transfer from the backplane interconnect
transfer. The buffered data path allows the UNIBUS adapter to read or
write multiple words of data in a transfer, and buffer the unrequested
portions of the data in a UNIBUS adapter buffer. Thus, several UNIBUS
read functions can be accommodated with a single backplane interconnect
transfer.
Q22 bus systems do not employ buffered data paths. The writer of a
UNIBUS device driver may choose to use a buffered data path rather than
a direct data path to perform the following functions:
•

Faster DMA block transfers to or from consecutively increasing
UNIBUS addresses

•

Word-oriented block transfers that begin and end on an odd-numbered
byte of memory; note, however, that these transfers can be quite slow
because the UNIBUS adapter might need to perform multiple transfers
to complete a one-word transfer

•

32-bit data transfers from random longword-aligned physical addresses

A single buffered data path cannot be assigned to more than one active
transfer at a time. When a driver fork process is preparing to transfer
data to or from a UNIBUS device on a buffered data path, it performs
a sequence of steps similar to those performed by a driver that uses the
direct data path, with the exception that it uses a macro that calls a VMS
routine that allocates a free buffered data path. The following are among
the actions of the driver fork process:
1

Uses the REQMPR macro to allocate a set of map registers.

Uses the REQDPR macro to allocate a free buffered data path.

Uses the LOADUBA macro to load the map registers with physical
address mapping data and the number of the allocated buffered data
path. The VMS routine called in the expansion of the LOADUBA
macro (10C$LOADUBAMAP) also sets the valid bit in every map
register except the last, which remains invalid to prevent a runaway
transfer.

Loads the starting address of the transfer in a device register.

Loads the transfer byte or word count in a device register.

Sets bits in the device CSR to initiate the transfer.

The UNIBUS adapter hardware of certain VAX systems normally
restricts buffered data paths to referring only to consecutively increasing
UNIBUS addresses. Through a special mode of operation, these UNIBUS
adapters can also refer to 32-bit data at randomly-ordered, longwordaligned locations in physical memory. Other systems do not impose this
restriction. In order for a device driver to run on both types of systems, it
must observe three rules:
14-1'

UNIBUS and Q22 Bus Device Support
14.1 Functions of the UNIBUS Adapter and Q22 Bus Interface

•

All transfers within a block must be of the same function type (DATI
or DATO/DATOB).

•

Buffered data paths must always transfer data to consecutively
increasing addresses.

•

To reference 32-bit data at random, longword-aligned locations in
physical memory, the longword-access-enable bit (LWAE) must be set.

A buffered data path stores data from the UNIBUS in a buffer until
multiple words of data have been transferred (except in longwordaligned, 32-bit, random-access mode as discussed in Section 14.1.3.5).
Then, the UNIBUS adapter transfers the contents of the buffer to the
appropriate physical address in a single backplane interconnect operation.
The procedure for a UNIBUS write operation that transfers data from a
device to memory is broken into individual steps.
1

The UNIBUS device transfers one word· of data to the buffered data
path.

The UNIBUS adapter stores the word of data and completes the
UNIBUS cycle.

The UNIBUS adapter sets the buffer-not-empty flag in the buffered
data path to indicate that the buffer contains valid data.

The UNIBUS device repeats the first three steps until the buffer is
full.

When the UNIBUS device addresses the last byte or word in the
buffer, the UNIBUS adapter recognizes a complete data-gathering
cycle.

The UNIBUS adapter requests a write function on the backplane
interconnect to write the data from the buffered data path to memory.

When the backplane interconnect transfer is complete, the buffered
data path clears its flag to indicate that the buffer no longer contains
valid data.

The procedure for a UNIBUS read operation that transfers data from
main memory to a device varies according to the type of UNIBUS adapter.
Those adapters that can perform a prefetch function complete UNIBUS
reads from memory more quickly than those that cannot. The prefetch
feature accomplishes this improved performance by automatically filling
the data path buffer after the buffer's contents are transferred to the
UNIBUS.
The following paragraphs discuss the UNIBUS read operation with
and without the prefetch function. Device drivers that adhere to the
conventions outlined in this manual will execute properly whether or
not the device is associated with a UNIBUS adapter that is capable of
prefetches.

14-12

The UNIBUS device initiates a read operation from a buffered data
path.

The UNIBUS adapter checks to see if its buffers contain valid data.

UNIBUS and Q22 Bus Device Support
14.1 Functions of the UNIBUS Adapter and Q22 Bus Interface

If the buffers do not contain valid data, the buffered data path initiates

a read function to fill the buffers with data from main memory. The
transfer completes before the UNIBUS adapter begins a UNIBUS
transfer.
4

The UNIBUS adapter transfers the requested bytes to the UNIBUS.
Bytes of data that were not transferred to the UNIBUS remain in the
buffer.

The UNIBUS adapter sets the buffer-not-empty flag in the buffered
data path to indicate that the buffer contains valid data.

When the UNIBUS device empties the buffers of the buffered data
path with a UNIBUS read function that accesses the last word of data,
the buffered data path clears the buffer-not-empty flag to indicate that
the buffer no longer contains valid data.

The buffered data path then initiates a read function to prefetch data
from memory.

When the prefetch is complete, the buffered data path sets the buffernot-empty flag to indicate that the buffers now contain valid data.

The prefetch might attempt to read data beyond the address mapped by
the final map register. To avoid referring to memory that does not exist,
the VMS routines that allocate and load map registers always allocate one
extra map register and clear the map-register-valid bit before initiating
the transfer. When the UNIBUS adapter notices that the map register for
the prefetch is invalid, the UNIBUS adapter aborts the prefetch without
reporting an error.
A UNIBUS read function without prefetch includes the following steps:
1

The UNIBUS device initiates a read operation from a buffered data
path.

The buffered data path checks to see if its buffers contain valid data.

If the buffers do not contain valid data, the buffered data path initiates

a read function to fill the buffers with data. The transfer completes
before the UNIBUS adapter begins a UNIBUS transfer.
4

14.1.3.3

The buffered data path transfers the requested bytes to the UNIBUS.
Bytes of data that were not transferred to the UNIBUS remain in the
buffer.

Byte-Offset Data Transfers

The UNIBUS adapter has a byte-offset register; thus, words that are not
word-aligned can be transferred to and from any device on the UNIBUS
regardless of whether the device supports non-word-aligned transfers.
Some UNIBUS devices are restricted to transferring integral words of data
in word-aligned UNIBUS addresses. The buffered data paths allow these
devices to perform transfers to memory that begins and ends on an oddbyte address. A byte-offset bit in the map registers indicates byte-aligned
data to the hardware. If the bit is set, the hardware increments physical
addresses. A VMS subroutine that loads map registers determines

14-13

UNIBUS and Q22 Bus Device Support
14.1 Functions of the UNIBUS Adapter and Q22 Bus Interface

whether the data is word- or byte-aligned and sets the byte-offset bit
accordingly.
14.1.3.4

Purging a Buffered Data Path

Because prefetches can read more data from memory than the UNIBUS
device wishes to read, driver fork processes must ask the UNIBUS adapter
to purge the buffered data path when a transfer is complete. In addition,
a transfer from a device to the backplane interconnect can complete with
some data left in the buffer. The driver must purge the data path to
complete the transfer.
The purge guarantees that the data is not transferred to the next user
of the buffered data path. The driver fork process performs the purge by
calling a standard VMS routine that performs two functions:
•

Tells the hardware to purge the buffered data path register owned by
the fork process. For a UNIBUS read function, the adapter simply
clears the buffer-not-empty flag. For a UNIBUS write function, the
adapter transfers any data left in the data path buffer to VAX memory,
then clears the flag.

•

Notifies the driver fork process of any error that occurs during the
purge.

The data path must be purged before the driver releases map registers or
the buffered data path register.
14.1.3.5

Longword-Aligned, 32-Bit, Random-Access Mode

Another method of transferring data over a buffered data path is the use
of longword-aligned, 32-bit, random-access mode. This mode essentially
prevents the UNIBUS prefetch operation, thereby allowing a device that
reads data from or writes data to memory to reference longword-aligned
locations in memory at random, in longword multiples.
To transfer data in the longword-aligned, 32-bit, random-access mode, the
driver fork process sets the longword-access-enable bit (VEC$V_LWAE) in
the channel request block (CRB) prior to loading the map registers. The
UNIBUS device can then perform a read (DATI) or write (DATO) function.
For a UNIBUS read operation that transfers data from main memory to a
device, the function occurs as follows:

14-14

The driver fork process initiates a read function on the UNIBUS
device.

The UNIBUS adapter clears the buffer-not-empty flag in the assigned
buffered data path.

The UNIBUS adapter requests a read-from-memory operation on the
backplane interconnect.

The UNIBUS adapter stores the longword of data in the buffered data
path and sets the 'buffer-not-empty flag.

The UNIBUS adapter completes two UNIBUS read operations to
transfer two words of data.

UNIBUS and Q22 Bus Device Support
14.1 Functions of the UNIBUS Adapter and Q22 Bus Interface

For a UNIBUS write operation that transfers data from a device to main
memory, the function occurs as follows:
1

The driver fork process initiates a write function on the UNIBUS
device.

The UNIBUS adapter clears the buffer-not-empty flag in the assigned
buffered data path.

The UNIBUS adapter completes two write operations to transfer two
words of data from the UNIBUS device.

The UNIBUS adapter stores the longword of data in the data path's
buffer and sets the buffer-not-empty flag.

The UNIBUS adapter initiates a backplane interconnect write
operation.

When the backplane interconnect write operation is complete, the
UNIBUS adapter clears the buffer-not-empty flag.

To ensure that random-access mode works correctly regardless of the
VAX system involved, the writer of a device driver should ensure that a
device assigned to a buffered data path does not repeatedly address the
same longword. On certain systems, a UNIBUS device that polls a single
longword, waiting for data, will constantly be returned the same data.

14.2

Writing Driver Code for UNIBUS/Q22 Bus OMA Transfers
A driver performing DMA transfers over the UNIBUS or Q22 bus must
take I/O bus operation into consideration. The VMS operating system and
the I/O database manage the map registers and data path resources of the
1/0 adapter for device drivers.
The I/O database contains an adapter control block (ADP) that describes
the I/O adapter. This block contains allocation information for the map
registers; for UNIBUS adapters, the ADP also contains similar information
for data paths.
The ADP also contains the virtual address of the adapter's configuration
register. All the adapter's other registers are located at fixed offsets from
the configuration register. The VMS adapter-handling routines modify the
adapter's map registers and data-path register according to requests from
the driver fork process.
In general, a driver fork process does not directly access the ADP. Instead,
a driver calls VMS routines that perform adapter-related services, such as
the following:
•

Allocating a buffered data path

•

Allocating map registers or alternate map registers

•

Loading map registers or alternate map registers

•

Deallocating map registers or alternate map registers

14-15

UNIBUS and Q22 Bus Device Support
14.2 Writing Driver Code for UNIBUS/Q22 Bus OMA Transfers

•

Purging a buffered data path

•

Deallocating a buffered data path

The critical responsibility of device drivers that actively compete for such
shared I/O adapter resources as map registers and data paths is to ensure
the synchronized access of adapter resources. Drivers that share these
resources must execute at the same fork IPL. In a VMS multiprocessing
system, they must additionally contend for the same fork lock. A given
driver code thread that must attempt to access its fork database can only
do so if suitably synchronized.
The system creates a driver fork process by calling the start-I/O routine in
a device driver. The fork process takes some or all of the following steps to
initiate an I/O transfer to or from a device on a UNIBUS or Q22 bus.
Operation

Applicable to

Requests buffered data path

UNIBUS

Requests map registers

UNIBUS or 022 bus

Requests alternate map registers

022 bus

Loads map registers

UNIBUS or 022 bus

Loads alternate map registers

022 bus

Calculates starting bus address

UNIBUS or 022 bus

Activates device

UNIBUS or 022 bus

Waits for interrupt

UNIBUS or 022 bus

When a hardware interrupt indicates that the I/O transfer is complete, the
driver fork process checks the success or failure of the transfer. The driver
then concludes with the following steps:
Operation

Applicable to

Purges data path

UNIBUS or 022 bus

Releases buffered data path

UNIBUS

Releases map registers

UNIBUS or 022 bus

Releases alternate map registers

022 bus

Because of the different requirements of DMA transfers on different VAX
and MicroVAX systems, a driver must contain some run-time conditional
code in order to function for equivalent UNIBUS and Q22 bus devices.
The DLDRIVER code example in Appendix C is one driver that supports
the RLll on the UNIBUS and the RLVll on the Q22 bus.
Regarding the material presented in this section, UNIBUS driver writers
should read Sections 14.2.1 through 14.2.7.3. Q22 bus driver writers
should read Section 14.2.1.3 and Sections 14.2.2 through 14.2.7.3.

14-16

UNIBUS and Q22 Bus Device Support
14.2 Writing Driver Code for UNIBUS/Q22 Bus OMA Transfers

14.2.1

Selecting and Requesting a Data Path
DMA device drivers for certain VAX systems can elect to request the use
of a UNIBUS adapter buffered data path to accelerate data transfers
(as described in Section 14.1.3). Other VAX processing systems, such as
MicroVAX systems and the VAX-111730, provide no buffered data paths for
data transfers. The descriptions of the direct data path in the following
sections apply to drivers written for devices in those systems.
14.2.1.1

Requesting a Buffered Data Path

Some VAX systems allow UNIBUS drivers to request temporary or
permanent allocation of a buffered data path (see Table 14-1). After
the driver fork process gains access to the controller (see Section 8.3.1 ),
it requests a buffered data path by invoking the VMS macro REQDPR.
REQDPR calls a VMS routine named IOC$REQDATAP that locates the
ADP. To do this, IOC$REQDATAP uses a series of pointers that begins in
the current unit control block (UCB), as follows:
UCB -+ CRB -+ ADP
IOC$REQDATAP performs the following services:
1

Tests the path-lock bit (VEC$V_PATHLOCK) in the data-path
number field of the channel request block (CRB$L_INTD+VEC$B_
DATAPATH). If the device has a permanent data path allocated to it,
IOC$REQDATAP simply returns.

Determines which data paths are available by examining the data
path allocation information in the ADP (ADP$W_DPBITMAP).

Allocates the first free data path to the driver by inserting its number
in the data path field of the CRB (CRB$L_INTD+VEC$B_DATAPATH)
and indicating in the ADP that the data path is in use (by clearing the
appropriate bit in ADP$W_DPBITMAP).

Returns control to the driver fork process.

If no data path is available, IOC$REQDATAP saves driver context (R3, R4,

and PC) in the UCB fork block and inserts the address of the fork block,
which is also the address of the UCB and the contents of R5, in the AD P's
data-path wait queue. The driver fork block remains in the queue until
both of the following conditions are met:
•

A data path is available.

•

The driver fork block is the next entry in the data-path wait queue.

When these conditions are met, the VMS routine IOC$RELDATAP
allocates the data path to the suspended driver and reactivates the driver
fork process.

14-17

UNIBUS and Q22 Bus Device Support
14.2 Writing Driver Code for UNIBUS/Q22 Bus OMA Transfers

14.2.1.2

Requesting a Permanent Buffered Data Path

A device driver can permanently allocate a buffered data path in its unit
initialization routine. Instead of using the REQDPR macro, however, the
unit initialization routine should perform the following steps:
1

Issue the FORK m~cro to drop IPL to fork IPL. The VMS fork
dispatcher causes the following steps to be performed at fork
IPL under the ownership of the required fork lock in a VMS
multiprocessing system. (The consequences of forking in a unit
initialization routine are discussed at length in Section 11.1.5.)

Test the path-lock bit (VEC$V_PATHLOCK) in the data-path-number
field of the CRB (CRB$L_INTD+VEC$B_DATAPATH) to ensure that a
data path is not already allocated for this device.

Call the subroutine IOC$REQDATAPNW to allocate the data path as
follows:
JSB

GAIOC$REQDATAPNW

If IOC$REQDATAPNW successfully allocates the data path, it

stores the number of the data path it obtained in the CRB at
CRB$L_INTD+VEC$B_DATAPATH and returns with the low-order
bit set in RO (SS$_NORMAL). If it cannot allocate a data path,
IOC$REQDATAPNW does not create a fork process to wait for one
to become available. Instead, it returns to the unit initialization
routine with the low-order bit clear in RO.
4

If the data path has been successfully obtained, set the path-lock

bit (VEC$V_PATHLOCK) in the CRB at CRB$L_INTD+VEC$B_
DATAPATH.
The driver-loading procedure calls the unit initialization routine for each
unit that the driver serves. A unit initialization routine that contains
the code described previously will permanently allocate one buffered data
path for each CRB associ~ted with the driver, which is one path for each
controller that the driver s'erves.
Because some VAX systems have few buffered data paths (refer to
Table 14-1), device drivers running in these systems must limit their
allocation of permanent buffered data paths. For example, if the drivers
loaded on a V.AX-111750 permanently allocated all three of the system's
buffered data paths, none would remain for normal system operations. As
a result, I/O transfers requiring a buffered data path would wait forever.
14.2.1.3

Requesting the Direct Data Path

Because the UNIBUS adapter or Q22 bus interface arbitrates among
devices that wish to use the direct data path and initializes the data path
field in the CRB (CRB$L_INTD+VEC$B_DATAPATH) to 0 (0 =direct data
path), drivers are not required to invoke the REQDPR macro to request
the direct data path.
Some VAX systems, such as the VAX-111780 or VAX 8600, do not permit
byte-offset transfers on the direct data path (see Table 14-1). Because the
UNIBUS itself is word-oriented, such a system must ensure that the data
buffer is aligned on a word boundary for word-aligned devices.
14-18

UNIBUS and Q22 Bus Device Support
14.2 Writing Driver Code for UNIBUS/Q22 Bus OMA Transfers

14.2.1.4

Mixed Use of Direct and Buffered Data Paths

A UNIBUS device driver can use the buffered data path for certain
operations, then use the direct data path for other operations. To
accomplish this task, the driver should allocate a buffered data path
for buffered 1/0. When the operation is completed, the driver should then
purge and release the buffered data path. The release automatically resets
the data path number to zero, which signifies a direct data path. When
the driver has finished using the direct data path, it should purge it (but
not release it). (A purge of the direct data path is a NOP and always
yields success.)

14.2.2

Requesting Map Registers
The UNIBUS adapter and Q22 bus interface allow UNIBUS and Q22 bus
drivers, respectively, to allocate map registers as needed or to allocate
them permanently.
14.2.2.1

Allocating Map Registers

After the driver fork process gains access to the controller (see
Section 8.3.1), it can request a set of adapter map registers (registers 0
through 495) by invoking the VMS macro REQMPR. This macro calls the
routine IOC$REQMAPREG. IOC$REQMAPREG calculates the number of
map registers needed for a transfer, allocating one map register for each
full or partial page of the buffer (based on the values of UCB$W_BCNT
and UCB$W_BOFF). In addition, it reserves an additional map register
to be marked invalid to stop a potential runaway transfer and inhibit
prefetches from the page past that in which the end of the buffer resides.
Finally, IOC$REQMAPREG may allocate one more extra map register to
ensure that an even number of map registers is allocated.
The procedure for &llocating map registers is similar to that used to
allocate a buffered data path. First, IOC$REQMAPREG locates the ADP
from a series of pointers that begins with the current UCB, as follows:
UCB ~ CRB ~ ADP
Then, t11.~ routine examines the map-register-allocation information to
locate the required number of contiguous map registers. If the registers
are not currently available, IOC$REQMAPREG saves the driver context
(R3, R4, and PC) in the UCB fork block and inserts the fork block's
address (same as UCB address and the contents of R5) in the standardmap-register wait queue.
When the map registers are available, IOC$REQMAPREG allocates them
and adjusts the appropriate information about the allocation of map
registers in the ADP. IOC$REQMAPREG then writes the number of the
first map register and the number of map registers allocated into the CRB
and returns control to the driver fork process.
VMS supplies a similar macro (REQALT) and routine (IOC$REQALTMAP)
that Q22 bus drivers use to allocate a set of alternate map registers
(registers 496 through 8191). REQALT and IOC$REQALTMAP perform
the allocation in the same manner as REQMPR and IOC$REQMAPREG.
Note that, although VMS records the allocation of standard and alternate
14-19

UNIBUS and Q22 Bus Device Support
14.2 Writing Driver Code for UNIBUS/Q22 Bus OMA Transfers

map registers in separate areas of the ADP and CRB, IOC$REQMAPREG
and IOC$REQALTMAP use the same UCB fields to calculate the number
of map registers required for a transfer.
14.2.2.2

Permanently Allocating Map Registers

A device driver can allocate a permanent set of map registers with code in
its unit initialization routine. The number of map registers permanently
allocated must be sufficient for the largest possible transfer and must
include an extra map register to be marked invalid to prevent a runaway
transfer.
A unit initialization routine performs the following steps to permanently
allocate a set of map registers:
1

Issue the FORK macro to drop IPL to fork IPL. The VMS fork
dispatcher causes the following steps to be performed at fork
IPL under the ownership of the required fork lock in a VMS
multiprocessing system. (The consequences of forking in a unit
initialization routine are discussed at length in Section 11.1.5.)

Test the map-lock bit (VEC$V_MAPLOCK) in the CRB (CRB$L_
INTD+VEC$W_MAPREG) to ensure that map registers are not
already allocated for this device.

Load the number of map registers required into R3.

Call the VMS routine IOC$ALOUBAMAPN with a JSB instruction:
JSB

GAIOC$ALOUBAMAPN

If IOC$ALOUBAMAPN successfully allocates the map registers, it

stores the number of map registers allocated and the number of
the first of the allocated map registers at CRB$L_INTD+VEC$B_
NUMREG and CRB$L_INTD+VEC$W_MAPREG, respectively. It then
returns with the low-order bit set in RO. Otherwise, it returns with
the low-order bit of RO clear.
5

If map registers have been successfully allocated, set the map-lock bit

in the CRB (VEC$V_MAPLOCK in CRB$L_INTD+VEC$W_MAPREG).
Q22 bus drivers perform the following steps to allocate a permanent set of
alternate map registers (registers 496 through 8191):
1

Test the alternate-map-lock bit (VEC$V_ALTLOCK) in the CRB
(CRB$L_INTD+VEC$W_MAPALT) to ensure that alternate map
registers are not already allocated for this device.

Load the number of alternate map registers required into R3.

Call the VMS routine IOC$ALOALTMAPN with a JSB instruction:
JSB

14-20

GAIOC$ALOALTMAPN

UNIBUS and Q22 Bus Device Support
14.2 Writing Driver Code for UNIBUS/Q22 Bus OMA Transfers

If IOC$ALOALTMAPN successfully allocates the alternate map

registers, it stores the number of map registers allocated and
the number of the first of the allocated map registers in CRB$L_
INTD+VEC$W_NUMALT and CRB$L_INTD+VEC$W_MAPALT,
respectively. It then returns with the low-order bit set in RO.
Otherwise, it returns with the low-order bit of RO clear.
5

If alternate map registers have been successfully allocated, set the

alternate-map-lock bit in the CRB (VEC$V_ALTLOCK in CRB$L_
INTD+VEC$W_MAPALT).
The driver-loading procedure calls the unit initialization routine once for
each unit associated with the driver. If the unit initialization routine
contains the code described previously, it permanently allocates a set of
map registers for each CRB associated with the driver, which is a set of
registers for each device controller that the driver serves. Because VMS
records the allocation of standard and alternate map registers in separate
areas of the ADP and CRB, a Q22 bus driver could permanently allocate a
set of registers from both areas.

14.2.3

Loading Map Registers
Once a driver fork process has assigned a data path and allocated a set of
map registers, it can request VMS to load the map registers with physical
page-frame numbers (PFNs) by invoking the VMS macro LOADUBA. 3
LOADUBA calls the VMS routine IOC$LOADUBAMAP to load each
allocated map register with the following data items:
•

A bit setting to indicate whether the map register is valid.

•

A bit setting to indicate whether the transfer is to start on the odd or
even byte within a word; this bit is set if the low-order bit of UCB$W_
BOFF is 1.

•

The number of the data path to use for the transfer (UNIBUS drivers
only).

•

The page-frame number of a page in memory.

•

A bit setting to indicate that the transfer operates in longword-aligned,
random-access mode on the buffered data path; this bit is set when
VEC$V_LWAE is set in VEC$B_DATAPATH (UNIBUS drivers only).

IOC$LOADUBAMAP loads the PFN of the first page of the transfer into
the first allocated map register, the PFN number of the second page of the
transfer into the second map register, and so forth. IOC$LOADUBAMAP
sets the valid bit in every allocated map register except the last. It clears
the valid bit in the final map register to prevent a prefetch from an invalid
page.

Q22 bus DMA device driver writers also use the LOADUBA macro to load a set of standard map registers
(registers 0 through 495).

14-21

UNIBUS and Q22 Bus Device Support
14.2 Writing Driver Code for UNIBUS/Q22 Bus OMA Transfers

To calculate the PFN used in the 1/0 transfer, IOC$LOADUBAMAP uses
three fields that VMS has written into the UCB:
•

UCB$W_BOFF-Byte offset in the first page of the transfer

•

UCB$W_BCNT-Number of bytes to transfer

•

UCB$L_SVAPTE-Virtual address of the page-table entry that
contains the PFN of the first page of the transfer

IOC$LOADUBAMAP determines the data path's number (for UNIBUS
devices), the number of the first map register, the address of the first map
register, and the number of allocated map registers from the CRB and the
ADP, as follows:
UCB -+ CRB -+ number of the data path
UCB -+ CRB -+ number of first map register
UCB-+ CRB-+ ADP-+ virtual address of first map register
UCB -+ CRB -+ number of map registers
When IOC$LOADUBAMAP has loaded all the map registers and marked
the last map register invalid, it returns control to the driver fork process.
VMS supplies a similar macro (LOADALT) and routine
(IOC$LOADALTMAP) that Q22 bus drivers use to load a set of previously
allocated alternate map registers (registers 496 through 8191). LOADALT
and IOC$LOADALTMAP load the alternate map registers in the same
manner as LOADUBA and IOC$LOADUBAMAP load standard map
registers.
Drivers that handle UNIBUS byte-addressable devices call the routine
IOC$LOADUBAMAPA. This routine performs the same function as
IOC$LOADUBAMAP, with one exception. When IOC$LOADUBAMAPA
loads map registers, it clears the byte-offset bit even if the transfer begins
on an odd-byte address.

14.2.4

Computing the Starting Address of a Transfer
The driver fork process must calculate the starting address of a DMA
transfer and load this address into the appropriate device register.
UNIBUS drivers and other Q22 bus drivers that use a set of standard
map registers take the following steps to make the calculation:

14-22

Write the byte-offset-in-page field of the UCB (UCB$W_BOFF) into
bits 0 through 8 of a general register.

Get the number of the starting map register for the transfer from
CRB$L_INTD+VEC$W_MAPREG. Write bits 0 through 6 of this 9-bit
value into bits 9 through 15 of the general register.

Write bits 0 through 15 of the general register into the device's buffer
address register.

UNIBUS and Q22 Bus Device Support
14.2 Writing Driver Code for UNIBUS/Q22 Bus OMA Transfers

Write bits 7 and 8 of the map register number, acquired in step 2, into
the extended memory bits of the appropriate device register (usually
the control and status register (CSR)). 4

Q22 bus drivers that use a set of alternate map registers perform a similar
procedure, as follows:

14.2.5

Write the byte-offset-in-page field of the UCB (UCB$W_BOFF) into
bits 0 through 8 of a general register.

Get the number of the starting alternate map register for the transfer
from CRB$L_INTD+VEC$W_MAPALT. Write bits 0 through 6 of this
13-bit value into bits 9 through 15 of the general register.

Write bits 0 through 15 of the general register into the device's buffer
address register.

Write bits 7 through 12 of the map register number, acquired in step
2, into the extended memory bits of the appropriate device register
(usually the control and status register (CSR)).

Computing the Transfer Length
Generally, a device driver must indicate to the device the size of a DMA
transfer by writing to a device register. If a device expects the transfer
size as a word count, for instance, the start-1/0 routine computes the
length of the transfer in words by dividing the byte count field of the UCB
(UCB$W_BCNT) by 2. The routine loads the computed value into the
device's word-count register. One of the FDT routines that processes the
1/0 request must ensure that the byte count for the transfer is even. An
odd byte count results in the user's not receiving the last byte of data.

14.2.6

Activating the Device
Because a driver fork process can address device registers as though they
were any other virtual address, the loading of the device buffer address
register and CSR are simple procedures. The driver locates the CSR
address of the device in the interrupt dispatch block (IDB), as follows:
UCB-+ CRB-+ IDB-+ CSR address
The CSR address is the virtual address of a device register. All other
device registers are located at constant offsets from the CSR address. If,
for example, the CSR is the first device register and the device's wordcount register is the third device register, the device driver can describe
the device register offsets and load the word-count register with the
following series of instructions:

One example of a device that does not treat the extended memory bits in this fashion is the DRVll-WA,
the the driver code <XADRIVER) for which is listed in Appendix D. For the DRV11-WA, code in XADRIVER
stores bits 7 and 8 of the map register number in a discrete device bus address extension register, then
clears the extended address bits of the device's CSR. In contrast, XADRIVER handles the DRll-W according
to the method described previously.

14-23

UNIBUS and Q22 Bus Device Support
14.2 Writing Driver Code for UNIBUS/Q22 Bus OMA Transfers

DEV CSR =
0
DEV XREG = 2
DEV WDCNT = 4

Compute word count of transfer and store it in user-defined UCB field,
UCB$W_WDCNT.

MOVL
MOVL
MOVW

14.2.7

UCB$L CRB(R5),R4
@CRB$L INTD+VEC$L IDB(R4),R4
UCB$W_WDCNT,DEV_WDCNT(R4)

;Address of CRB
;Address of CSR
;Move word count to device
;word count register

Completing a DMA Transfer
After a UNIBUS or Q22 bus driver fork process activates a DMA device,
the driver waits for a device interrupt by invoking a VMS macro that
suspends execution of the driver. When the device requests a hardware
interrupt, the interrupt dispatcher gains control.
The dispatcher saves RO through R5 and transfers control to the driver's
interrupt service routine. If the interrupt service routine can match the
interrupt with a suspended driver fork process, it reactivates the driver
fork process at the point where execution was suspended. Most driver fork
processes almost immediately invoke the VMS macro IOFORK.
IOFORK calls the VMS routine EXE$10FORK. EXE$IOFORK saves
the driver context (R3, R4, and PC) in the UCB fork block and inserts
the address of the fork block (R5) in the processor-specific fork queue
corresponding to the device's fork IPL. EXE$10FORK then returns control
to the driver's interrupt service routine, which dismisses the interrupt.
When the fork dispatcher reactivates the driver fork process, the driver
performs any necessary cleanup operations, such as purging the data path
and deallocating adapter resources used in the DMA transfer.
14.2.7.1

Purging the Data Path

Driver fork processes must purge the data path after the DMA transfer
is complete. This is true for devices with buffered data paths, direct data
paths, or no data path.
To purge the data path, the driver invokes the macro PURDPR, which
in tum calls the VMS routine IOC$PURGDATAP. This routine takes the
following steps to purge the data path:
1

Saves the contents of R4 on the stack.

Locates the CRB as follows:
R5 -+ UCB -+ CRB

14-24

Obtains the starting address of the UNIBUS adapter's register space
and stores it in R2.

Extracts the number of the data path to be purged from the CRB and
loads it into Rl.

UNIBUS and Q22 Bus Device Support
14.2 Writing Driver Code for UNIBUS/Q22 Bus OMA Transfers

Stores the address of the data path register in R4.

Instructs the UNIBUS adapter or Q22 bus interface to purge the
data path. The routine then modifies RO through R2 to contain the
following information:
RO

Success/failure status. If the purge completes without error, the routine sets
SS$_NORMAL in this register. If a data-path error does occur, RO is clear
and the hardware is reset.

Contents of the data-path register.

Address of the first adapter map register.

The address of the CRB remains in R3. This address, along with the
information in Rl and R2, is used as input to the error logging routine
in the event of a data-path error.
7

Restores the information stored on the stack to R4 and returns to the
address in the driver immediately after the invocation of the PURDPR
macro.

Some machine implementations also check for memory errors that
might have occurred during the DMA operation, and, if an error is
detected, log it.

If a data-path error occurs during a data-path purge, the driver should

retry the entire DMA transfer.
14.2.7.2

Releasing a Buffered Data Path

A driver fork process releases a buffered data path by invoking the VMS
macro RELDPR. RELDPR calls a VMS routine, IOC$RELDATAP, that
determines which data path was assigned to the driver fork process and
releases the data path to a waiting driver. The driver must be executing
at fork IPL.
The data-path number is stored in the CRB. IOC$RELDATAP locates it as
follows:
UCB -+ CRB -+ number of the data path
If the data path is permanently assigned to a device, IOC$RELDATAP

does not release the data path. Otherwise, the data path number in the
CRB (CRB$L_INTD+VEC$B_DATAPATH) is zeroed. The IOC$RELDATAP
routine attempts to dequeue a waiting driver fork process from the datapath wait queue. It finds the queue as follows:
UCB -+ CRB -+ ADP -+ data-path wait queue
If another driver is waiting for a buffered data path, IOC$RELDATAP

grants that driver fork process the data path, restores its context from
its UCB fork block, and transfers control to the saved driver PC. When
IOC$RELDATAP can allocate no more data paths, the routine returns to
the driver that released the data path. This diversion of driver processing
is transparent to the driver fork process.
If the data-path wait queue is empty, IOC$RELDATAP marks the data

path as available in the ADP and returns control to the driver.

14-25

UNIBUS and Q22 Bus Device Support
14.2 Writing Driver Code for UNIBUS/Q22 Bus OMA Transfers

14.2.7.3

Releasing Map Registers
A driver fork process releases a set of map registers by invoking the
VMS macro RELMPR at fork IPL. RELMPR calls the VMS routine
IOC$RELMAPREG, which releases map registers in a manner similar
to the way in which the RELDPR macro releases data paths. The CRB
records the number of map registers assigned to the device. The number
of the first map register and the number of map registers are located as
follows:

UCB -+ CRB -+ number of the first map register
UCB -+ CRB -+ number of allocated map registers
IOC$RELMAPREG releases the map registers by adjusting the mapregister-allocation information in the ADP.
Then, IOC$RELMAPREG attempts to dequeue a driver fork process from
the standard-map-register wait queue. If a suspended driver is found,
IOC$RELMAPREG takes the following steps:
1

Dequeues the fork block and restores driver context

Satisfies the map-register request, if possible

Reactivates the driver fork process at the instruction following the
driver's request for map registers

Repeats steps 1 through 3

If the standard-map-register wait queue is empty or if IOC$RELMAPREG

still does not have enough contiguous map registers for any of the waiting
fork processes, it returns control to the fork process that released the map
registers.
VMS supplies a similar macro (RELALT) and routine (IOC$RELALTMAP)
that Q22 bus drivers use to release a set of alternate map registers
(registers 496 through 8191). RELALT and IOC$RELALTMAP perform
the release in the same manner as RELMPR and IOC$RELMAPREG.
Note that VMS records the allocation of standard and alternate map
registers in separate areas of the ADP and CRB.

14.3

Interrupt Dispatching in a UNIBUS/Q22 Bus System
The interrupt dispatcher is a combination of hardware and software
that routes interrupts from a device on the UNIBUS or Q22 bus to the
appropriate device driver's interrupt service routine. Although there
are slight differences in the implementation of the interrupt dispatcher
in different VAX systems, it performs the same tasks in any given VAX
environment.
When a processor grants a device interrupt, the processor microcode first
saves the PC and PSL of the currently executing code on the interrupt
stack. The device responds to the grant by supplying a device interrupt
vector in the range of 0 to 777 8 to the processor. VAX VMS uses the
device interrupt vector to locate the correct interrupt transfer vector for
the device. The interrupt transfer vector structure (VEC) contains a short
14-26

UNIBUS and Q22 Bus Device Support
14.3 Interrupt Dispatching in a UNIBUS/Q22 Bus System

routine which issues a JSB instruction to the device driver's interrupt
service routine. Execution continues at the location of the transfer vector.
This is a somewhat simplified view of the interrupt dispatcher's activities.
Figure 14-5 and Figure 14-6 depict the flow of interrupt dispatching
from the time that a processor grants the interrupt to the processing
of the interrupt within a device driver's interrupt service routine. The
following subsections provide a more complete description of the role of
each component in the servicing of device interrupts.
Figure 14-5 Direct-Vector Interrupt Dispatching

......

Device IDB
Device CSR

r-+ Device

Registers

---~~-~=~! ___

QBUS_MULT_INTR
system parameter
set

r-------------..
•

Interrupt gianted.

•

PC and PSL saved
on stack.

• Device supplies
device interrupt
vector.

UCB Address

VEC (inCRB)

I
I
I
I
I
I
I

t--

022 Bus Multilevel
Interrupt Code

r--;_

PUSHR RO-R5
JSB driver isr
IDB Pointer

.....--._ _____________

Device UCB

Device Driver
'"I

Interrupt Service Routine

Fork Block

•

Obtains device lock.

•

Uses IDB address
on stack to locate
device registers and UCB.

• R3
• R4

•

Restores R3 and R4
from UCB fork block.

•

Transfers control to PC
in fork block (via JSB).

•

When driver issues RSB:

• PC

- Releases device lock.
- Restores RO-R5.
- Issues REI to
dismiss interrupt.

The interrupted
recess continues
execution.

-p

ZK-6537-GE

14-27

UNIBUS and Q22 Bus Device Support
14.3 Interrupt Dispatching in a UNIBUS/Q22 Bus System

Figure 14-6

Non-Direct-Vector Interrupt Dispatching
see (First Page)

UBAADP

r---+-------------------------UBA Interrupt Service Routine

•
•

• Interrupt granted.
• PC and PSLsaved
on stack.

• UBAsupplies
adapter interrupt
vector.

•
--------------

•

PUSHR RO-RS
Reads BRRVR in UBA
to obtain device
interrupt vector.
Uses vector as index
into VECTAB to obtain
vector address.

1---

Device IDB
-..

Device CSR

i---. Device
Registers

JMP to vector
address+2.

~------------------------~
VECTAB

UCB Address

VEC (inCRB)

t--

022 Bus Multilevel
lnter~pt Code

PUSHRRO-RS
JSB driver_isr
IDB Pointer

r--

....-

Device UCB

Device Driver

....-

Interrupt Service Routine

Fork Block

•
•

• R3
• R4

•

•
•

Obtains device lock.
Uses IDB address
on stack to locate
device registers and UCB.

• PC

Restores R3 and R4
from UCB fork block.
Transfers control to PC
in fork block (via JSB).
When driver issues RSB:
- Releases device lock.
- Restores RO-RS.
- Issues REI to
dismiss interrupt.

The interrupted
process continues
execution.
ZK-6536-GE

14.3.1

Direct-Vector and Non-Direct-Vector Interrupt Dispatching
The system control block (SCB) contains the vectors that the VAX
architecture uses to dispatch all interrupts and exceptions. The size of
the SCB is system dependent. Page 1, the only SCB page defined by
the VAX architecture, contains the addresses of software and hardware
interrupt service routines and exception service routines.
The SCB therefore has an initial, albeit system-dependent, role in
servicing device interrupts. A UNIBUS/Q22 bus system employs either of
two methods to dispatch a device interrupt (see Table 14-2).

14-28

UNIBUS and Q22 Bus Device Support
14.3 Interrupt Dispatching in a UNIBUS/Q22 Bus System

Table 14-2 VAX System UNIBUS/Q22 Bus Interrupt Dispatching

VAX System

Method of
Interrupt
Dispatching

Location of
Adapter Dispatch Table

VAX-11/750, VAX-11/730, MicroVAX systems

Direct

SCB pages 2 and 3

VAX-11/780, VAX-11/785, VAX 8600, VAX 8650

Non-Direct

ADP vector-jump table

VAX 82x0/83x0

Direct

SCB page 2 1

VAX 85x0/8700/88x0

Direct

SCB page 2 1

VAX 6000 series

Direct

SCB page 2 1

1 Subsequent pages may be used if there is more than one DWBUA in the system.

•

Direct-vector interrupt dispatching: If the system in question is a
MicroVAX system, or uses a direct-vector UNIBUS adapter (UBA), it
dispatches a device interrupt directly through page 2 (or subsequent
pages, for VAX systems with more than one such UNIBUS) of the SCB.
It takes the device interrupt vector and uses it as an index into the
appropriate SCB page, thus obtaining the address of the appropriate
interrupt transfer vector structure (VEC) for the device.

•

Non-direct-vector interrupt dispatching: In a VAX system that
employs a non-direct-vector UNIBUS adapter, the adapter posts an
interrupt that is dispatched through a vector in page 1 of the SCB that
points to a UBA interrupt service routine. For each non-direct-vector
UBA adapter, the VMS adapter initialization procedure creates four
such interrupt service routines, each corresponding to a device BR (bus
request) level, and places them in an area of nonpaged pool specially
allocated at the end of the adapter control block.
The UNIBUS adapter's interrupt service routine performs the
following actions:
1

Saves RO through R5 on the interrupt stack.

Reads the UNIBUS adapter's Bus Request Receive Vector register
(BRRVR) to determine the vector address of the device requesting
the interrupt.

Uses the vector address as an index into the adapter dispatch table
to locate the interrupt transfer vector for the device in the CRB.
For each non-direct-vector UBA, an adapter dispatch table (also
known as the vector-jump table) is located after the UBA interrupt
service routines in nonpaged pool.

Transfers control by means of a JMP instruction to a location
within the interrupt transfer routine contained in the VEC
structure.

14-29

UNIBUS and Q22 Bus Device Support
14.3 Interrupt Dispatching in a UNIBUS/Q22 Bus System

From another point of view, direct-vector interrupt dispatching and nondirect-vector interrupt dispatching are characterized by the following two
factors:
•

Location of the adapter dispatch table

•

Contents of the interrupt transfer routine

The following sections further examine the differences in the dispatching
methods. Figures 14-5 and 14-6 present the flow of tasks performed
within the context of both direct-vector and non-direct-vector interrupt
dispatching.

14.3.2

Adapter Dispatch Table
The adapter dispatch table contains 128 longword vectors, each of which
corresponds to a device interrupt vector. Each longword vector within
the adapter dispatch table contains either the address of an interrupt
transfer vector structure (VEC), located within the channel request
block (CRB) of the device's controller or, if no device is using the vector, the
address of the adapter's unexpected interrupt service routine. In either
case, the address contained in the adapter dispatch table is longword
aligned.
The location of the adapter dispatch table, as signified by the contents of
ADP$L_VECTOR, is system dependent:

14.3.3

•

MicroVAX systems and those VAX systems that employ direct vector
UNIBUS adapters situate the adapter dispatch table in the second
and subsequent pages of the system control block (SCB), as described
previously.

•

Those VAX systems that employ non-direct-vector interrupt
dispatching situate the adapter dispatch table in a region of nonpaged
pool (known also as the vector-jump table and commonly referred to as
VECTAB).

Interrupt Transfer Vector and Interrupt Transfer Routine
The interrupt transfer vector data structure (VEC) is located within
the channel request block (CRB) corresponding to the interrupting device's
controller, as shown in Figure 14-7.
The interrupt transfer vector structure (see Figure 14-8 and the CRB
structure in the VMS Device Support Reference Manual) starts with
several lines of executable code known as the interrupt transfer routine.
It also stores several pieces of data, including pointers to the unit and
controller initialization routines in the device driver, the address of the
interrupt dispatch block (IDB), and the address of the adapter control
block (ADP). The interrupt transfer vector may also include information
reflecting the disposition of the adapter's map registers.

14-30

UNIBUS and Q22 Bus Device Support
14.3 Interrupt Dispatching in a UNIBUS/Q22 Bus System

Figure 14-7 VEC Structures Within

a CRB

Preceding Portion of CAB

Interrupt Transfer Vector Block
(VEC$K_LENGTH BYTES)

:CRB$L_INTD

Interrupt Transfer Vector Block
(VEC$K_LENGtH BYTES)

:CRB$L_INTD2

••
•

Additional
transfer vectors
may follow

•

••
ZK-6538-GE

There may be one or more interrupt transfer vectors within a single
CRB, a~ shown in Figure 14-7. VMS creates the appropriate number of
interrupt transfer vector structures within a CRB according the the value
specified in the /NUMVEC qualifier to the SYSGEN command CONNECT.
The default value is 1.
VMS automatically initializes the interrupt dispatching instructions and
the data structure locations in each of the specified vectors.
The interrupt transfer routine is a piece of executable code at the
beginning of each interrupt transfer vector. It is the interrupt transfer
routine that ultimately transfers control to the device driver's interrupt
service routine and, to a certain extent, establishes the context for its
execution.
For those VAX systems employing non-direct-vector interrupt dispatching,
the interrupt transfer routine consists of only one instruction:
JSB

@#Adriver-isr-address

For those VAX systems employing direct-vector interrupt dispatching, the
interrupt transfer routine consists of the following two instructions:
PUS HR
JSB

#AM<R0,Rl,R2,R3,R4,R5>
@#Adriver-isr-address

Note: If the. MicroYAX system has multilevel device interrupt
dispatching enabled, these two instructions are preceded by some
instructions that check the legality of the Q22 bus configuration
and conditionally lower IPL. See Section 14.3.4 for a description of
this optional function of the interrupt transfer routine.
14-31

UNIBUS and Q22 Bus Device Support
14.3 Interrupt Dispatching in a UNIBUS/Q22 Bus System

Figure 14-8 Interrupt Transfer Vector Block (VEC)

Bugcheck Data

:VEC$L_BUGCHECK

BUG_CHECK

:VEC$L_RTINTD
CMPZV #PSL$V_IPL,#PSL$S_IPL,4(SP),s"#DIPL
BGEQ VEC$L_BUGCHECK
SETIPL s"#DIPL
(Total of 12 bytes of code)

JSB@#

:VEC$L_INTD
(CRB$L_INTD)

PUSHR RO-RS

:VEC$L_ISR

Address of ISR
Address of IDB

-'-

Remaining bytes m VEC block

T
ZK-6539-GE

The driver-loading procedure obtains the address of the interrupt
service routine for each interrupt transfer vector structure from the
reinitialization portion of the driver prologue table (see Section 6.1). This
section of the DPT contains one or more DPT_STORE macros that identify
the addresses of the interrupt service routines. For example:
DPT STORE,CRB,CRB$L INTD+VEC$L ISR,D,isr for 1st vector
DPT-STORE,CRB,CRB$L-INTD2+VEC$L ISR,D,isr for 2nd vector
DPT=STORE,CRB,CRB$L=INTD+<2*VEC$K_LENGTH>+VEC$L_ISR,D,isr_for_3rd_vector

The number of DPT_STORE macros that identify interrupt service
routines must equal the number of vectors given in the /NUMVEC
qualifier to the SYSGEN command CONNECT to avoid errors in device
initialization or interrupt handling.
Immediately following the interrupt transfer routine in the CRB is the
address of the interrupt dispatch block (IDB) associated with the CRB.
When the JSB instruction executes, a pointer to the address of the IDB
is pushed onto the top of the stack as though it were a return address.
The driver interrupt service routine can use this IDB address as a pointer

14-32

UNIBUS and Q22 Bus Device Support
14.3 Interrupt Dispatching in a UNIBUS/Q22 Bus System

into the I/O database. See Figures 14-5 and 14-6 for an illustration of the
context available to a driver's interrupt service routine when it is called by
the interrupt transfer routine.

14.3.4

Multilevel Device Interrupt Dispatching for Q22 Bus Devices
VAX peripheral devices request interrupts at IPLs 20 through 23. IPLs
20 through 23 generally correspond with the four bus request levels of the
UNIBUS (BR4 through BR7) and Q22 bus (BIRQ4 through BIRQ7).
The UNIBUS also has four bus grant lines (BG4 through BG7). Because of
this, interrupt dispatching for UNIBUS devices inherently occurs at four
levels. When a UNIBUS device requests an interrupt at BR4, for example,
from a processor executing at an IPL lower than IPL 20, the processor
grants the interrupt to the device at IPL 20 (BG4). If the processor
is already executing at IPL 20 or above, the device interrupt remains
pending.
The MicroVAX Q22 bus implementation has but one bus grant line (BIA.K).
As a result, the central processor must, by default, grant all Q22 bus
device interrupts at a single IPL (IPL 23 ), even though it arbitrates
interrupt requests according to the bus request line used. When a Q22
bus device requests an interrupt at BIRQ4, for example, from a processor
executing at an IPL lower than IPL 20, the processor grants the interrupt,
unconditionally raising IPL to IPL 23. If the processor is already executing
at IPL 20 or above, the interrupt remains pending.
There are certain consequences of this implementation of interrupt
dispatching on the configuration and behavior of Q22 bus devices:
1

Because MicroVAX systems dispatch Q22 bus interrupts at a single
IPL, it is essential that Q22 bus devices that request interrupts at a
high BIRQ be positioned on the bus closer to the CPU than devices
that interrupt at a low BIRQ. (To determine the BIRQ level of any
given Q22 bus device, refer to its hardware user's guide.)

It is possible for a Q22 bus peripheral that requests interrupts at a
low BIRQ to block the granting of an interrupt to a peripheral that
requests interrupts at a higher BIRQ. For instance, the processor could
grant an interrupt to a BIRQ4 device, elevating its IPL to IPL 23 in
the process. While executing at IPL 23, the processor would not grant
the interrupt request of a BIRQ7 device. In a real-time environment,
where I/O operations to one peripheral must always have priority over
lesser forms of I/O, this behavior can cause problems.

VMS incorporates a means by which system programmers, concerned
about real-time performance issues, can avoid these problems and
implement multilevel interrupt dispatching for devices on a MicroVAX
Q22 bus.
Because single-level interrupt dispatching is sufficient for most
applications, only system managers and system programmers involved
in real-time system environments should attempt to use the multilevel
device interrupt dispatching capability of VMS Version 5.4. Such
users should possess a thorough understanding of the VMS interrupt

14-33

UNIBUS and Q22 Bus Device Support
14.3 Interrupt Dispatching in a UNIBUS/Q22 Bus System

dispatching mechanism and the means by which VMS synchronizes access
to structures in the 110 database.
If you must enforce real-time device priorities in your Q22 bus system,
you can do so by setting the QBUS_MULT_INTR system parameter. This
static parameter causes VMS to set up the proper code and data structures
to enable multilevel device interrupt dispatching at system initialization. 5

When you bootstrap a MicroVAX system with the QBUS_MULT_INTR
system parameter set, VMS initializes data structures for each device and
implements multilevel device interrupts as follows:
•

Locates the address of the device driver's interrupt service routine in
the driver's DPT and stores it in the appropriate VEC data structure.

•

Adjusts the corresponding vectors in the second page of the SCB so
that they point to the multilevel device interrupt dispatching code in
the interrupt transfer vector (that is, replacing the address of CRB$L_
INTD with CRB$L_INTD+VEC$L_RTINTD).

•

Sets up data and code at VEC$L_RTINTD in the first interrupt
transfer vector for the device. This code performs special checks for
the legality of the Q22 bus configuration and conditionally lowers IPL,
when necessary, to service the interrupts of low priority devices.

When multilevei device interrupt dispatching is enabled, interrupt
dispatching proceeds as in the default case. However, after the processor
raises IPL to IPL 23 to grant the interrupt, the dispatching of the
interrupt results in the lowering of IPL to device IPL, if necessary, to
service the interrupt. As a result, the processor, executing at the lower
IPL, will be free to grant interrupts from higher priority devices.
Prior to activating this feature in a MicroVAX system, a user should
perform the following tasks:

1·4.3.4.1

Ensure that the Q22 bus is properly configured.

Adapt any existing non-Digital-supplied device driver so that it
correctly initializes any secondary vector (VEC) structures it uses
and also refers to fields in the channel request block (CRB) and VEC
by the proper symbolic offsets.

Ensuring That the Q22 Bus Is Properly Configured

The MicroVAX Q22 bus architecture mandates that devices with the ability
to interrupt at a high BIRQ level (for instance, BIRQ7) must be positioned
on the bus closer to the CPU than devices that interrupt at lower BIRQ
levels. In a Q22 bus system, when the processor grants an interrupt to a
device, the processor passes the interrupt down the BIAK line to the first
device on the bus. If the device is not the one requesting an interrupt, it is
responsible for propagating the acknowledgment grant to the next device
on the bus, and so on. However, if a device coincidentally initiates an
interrupt just before it would be required to pass the grant further down
the bus, it may instead "steal" the grant for itself.

Other VAX systems ignore the QBUS_MULT_INTR system parameter.

14-34

UNIBUS and Q22 Bus Device Support
14.3 Interrupt D~spatching in a UNIBUS/Q22 Bus System

The problems of an illegally configured Q22 bus can be illustrated in the
following two examples.
Consider the case of a device that interrupts at BIRQ6 (IPL 22). Assume
the CPU is at IPL 21. The bus arbitrator will grant the device its interrupt
and send the grant down the Q22 bus. However, if at this precise moment
a device that is closer to the CPU on the grant path, and that interrupts
at BIRQ5 (IPL 21), initiates an interrupt, it may not propagate the grant
as it should. Instead, it may steal the grant and assume ownership
of the interrupt. Thus, there exists the possibility of an IPL 21 device
successfully interrupting a processor executing at IPL 21. The end result
is an unpredictable break in synchronization that could have a multitude
of consequences.
Consider also an instance where the second device interrupts at a lower
IPL, such as BIRQ4 (IPL 20). Although it essentially is executing below
the IPL of the CPU (IPL 21 ), this device, too, may steal the interrupt
grant. The break in synchronization in this instance will result in a
reserved operand fault when the driver's interrupt service routine issues
the REI instruction, as the VAX architecture does not permit an REI from
a lower IPL to a higher IPL.
If the MicroVAX system employs the multilevel device interrupt

dispatching option, VMS introduces special code in the interrupt
transfer vector data structure that helps prevent violations of system
synchronization resulting from an illegally configured Q22 bus (see
Figure 14-8). This code, located at offset VEC$L_RTINTD, checks the
device IPL of the interrupting peripheral against the IPL in the processor
status longword (PSL) of the interrupted thread of code. If the device
IPL is not greater than the IPL in the saved PSL, VMS generates
an ILLQBUSCFG bugcheck, signifying that the Q22 bus is illegally
configured.
14.3.4.2

Effects of Enabling Multilevel Device Interrupt Dispatching

Before enabling multilevel device interrupts in a MicroVAX system, you
should first ensure that all existing device drivers have been adapted
according to the following guidelipes:
•

If the driver creates or accesses any secondary VEC data structures,

it must take steps to initialize properly the multilevel device
interrupt dispatching code (at offset VEC$L_RTINTD in the primary
VEC structure) in these secondary structures. Failure to properly
initialize these structures in the system can negate any performance
increases expected as a result of enabling multilevel device interrupt
dispatching.
•

The device IPLs of certain Q22 bus devices may differ from those of
corresponding UNIBUS devices. To ensure that the DPT specifies the
correct device IPL, refer to the device's hardware user's guide.

•

Wherever the driver implicitly refers to the longword in the VEC
structure that contains the address of the interrupt service routine, it
should explicitly use the symbol VEC$L_ISR. For example, you should
replace any instance of CRB$L_INTD+4 with CRB$L_INTD+VEC$L_
ISR.
14-35

UNIBUS and Q22 Bus Device Support
14.3 Interrupt Dispatching in a UNIBUS/Q22 Bus System

•

If the driver assumes that the contents of the device's SCB vector (that
is, the vector in the adapter dispatch table) always points to CRB$L_
INTD, it must be appropriately modified to reflect the implementation
of multilevel device interrupt dispatching. The transfer vector can
legally point to any longword-aligned address between CRB$L_
INTD+VEC$L_RTINTD and CRB$L_INTD+VEC$L_INTD. Because
MicroVAX systems utilize direct-vector interrupt dispatching, the
transfer vector will never point to VEC$L_INTD+2.

Although certain of the symbolic offsets defined in the data structure
definition macro $VECDEF have negative values, driver code can
uniformly refer to the contents of the VEC structure in the form CRB$L_
INTD+VEC$x_symbol.

14-36

MASSBUS Device Support

The MASSBUS adapter (MBA) is the hardware interface between the
backplane interconnect and MASSBUS storage devices. The MASSBUS
is the communication path linking the MASSBUS adapter to the mass
storage devices.
The MASSBUS adapter performs the following functions that allow
communication between devices and memory:
•

Mapping of virtual addresses to physical addresses

•

Buffering of data for transfers between main memory and the
MASSBUS

•

Transfer of interrupts from MASSBUS devices to the backplane
interconnect

A MASSBUS adapter supports any combination of up to eight device
controllers. Typical MASSBUS controllers include the TM03 tape
controller and the RP06, RM03, and RMSO disk controllers. Only one
controller can transfer data over the MASSBUS at a time.
The TM03 tape controller supports up to eight tape drives. In contrast
to tape controllers, there is a one-to-one relationship between a disk
controller and its device; each controller supports only one disk drive.
The VMS system interprets and maintains the I/O database differently,
depending upon whether the controller is single unit or multiunit.
Each MASSBUS controller connected to a MASSBUS adapter is assigned
a unit number in the range 0 to 7. The method of unit number assignment
is controller specific, but you can obtain the number from either unit plugs
or switch packs. In the case of a controller for several devices, the unit
number is distinct from the subunit numbers assigned to the individual
drives connected to the controller.
Figure 15-1 illustrates a possible MASSBUS configuration.

15.1

MASSBUS Adapter Registers
The MASSBUS adapter has three sets of registers:
•

The MASSBUS adapter's registers

•

External registers for each device (controller) on the MASSBUS

•

256 map registers

15-1

MASSBUS Device Support
15.1 MASSBUS Adapter Registers

Figure 15-1

MASSBUS Configuration

Unit 1

Subunit
0

Subunit
1

Subunit
2

Unit 2

Non-Digital
Device

Subunit

3
ZK-0939-GE

To allow competing devices to share these resources, access to and
modification of all MASSBUS adapter registers (internal, external,
and map registers) are governed by certain rules and conventions. In
particular, access to registers might, at times, require ownership of either
the device controller or the MASSBUS adapter itself, or both. Subsequent
sections in this chapter discuss the methods of obtaining such ownership
of these shared resources.
MASSBUS adapter external registers are device dependent and accessible
whether or not the driver owns the MASSBUS adapter. However, in the
case of multiunit MASSBUS adapter controllers, the driver might need to
own the controller before it can gain access to a register.
MASSBUS adapter external registers are each 16 bits wide, but they
must be accessed as longwords. When a driver reads an external register,
the MASSBUS adapter concatenates the high-order 16 bits of the MBA's
status register (one of the MBA's internal registers) with the contents
of the specified external register. Figure 15-2 illustrates the resulting
longword.
On a write to an external register, the MASSBUS adapter uses the loworder 16 bits of the longword source operand to update the external
register.

15-2

MASSBUS Device Support
15.1 MASSBUS Adapter Registers

Figure 15-2 MASSBUS External-Register Longword
16 15

MBA's Status Register Bits

External Register Contents
ZK-1796-GE

MASSBUS adapter internal and map registers are 32 bits in length. They
must be accessed as longwords or the processor will signal a machine
check exception. The driver for a MASSBUS device must obtain exclusive
ownership of the MASSBUS adapter before modifying any of the MBA's
internal or map registers.
Bits 21 through 30 of each of the MBA's map registers are reserved; they
cannot be written. Use of the MBA's map registers is analogous to use of
the UNIBUS adapter's map registers with the following exceptions:

15.1.1

•

Because the MASSBUS can handle only one transfer at a time,
ownership of the MASSBUS adapter implies ownership of all its
map registers. Thus, the driver need not independently request map
registers.

•

The MBA's map registers do not contain a byte-offset field. The
driver loads the full MASSBUS adapter virtual address, including
the byte alignment, into the MASSBUS adapter virtual address
register (MBA$L_VAR, one of the MBA's internal registers) at the start
of a data transfer. Use of the MBA$L_VAR register is described in
Section 15.1.1.

•

The MBA's map registers do not contain a data path field; the
MASSBUS adapter has a single data path, and ownership of the
adapter implies ownership of the path. Thus, the driver need not
allocate the data path independently.

Loading MASSBUS Adapter Registers
To pre.pare for a data transfer over the MASSBUS, the driver that owns
the MASSBUS adapter uses the LOADMBA macro to load the MBA's map
registers and associated internal registers. The LOADMBA macro invokes
the subroutine IOC$LOADMBAMAP, which performs the following steps:
•

Determines the number of map registers needed to map the data area
by adding the contents of UCB$W_BCNT to UCB$W_BOFF, adjusting
the sum to the next even multiple of 512, and dividing the result by
512.

•

Loads the specified number of map registers, beginning with map
register 0, with the contents of the page-table entries to which
UCB$L_SVAPTE points. This step maps the data area for the transfer
into the low portion of the MBA's virtual address space. The routine
also load~ the next map register beyond the number used to map the
15-3

MASSBUS Device Support
15.1 MASSBUS Adapter Registers

data area with zeros (an invalid map entry). This procedure stops the
transfer should a hardware failure occur.
•

Loads the MBA$L_VAR register with the zero-extended contents of
UCB$W_BOFF. Because the first byte of the data area is located at
offset UCB$W_BOFF within the page of memory mapped by map
register 0, the UCB$W_BOFF contains the virtual address of the start
of the data area in MASSBUS adapter virtual address space.

•

Loads the complement (negative) of UCB$W_BCNT into the MBA's
byte-count register (MBA$L_BCR).

Note that if a driver is to perform a data transfer in the reverse direction
(for example, read reverse on a tape), it must modify the contents of the
MBA$L_VAR, as established by IOC$LOADMBAMAP, so that it points to
the last byte of the data area. This is done by adding one less than the
contents of UCB$W_BCNT to the contents of the MBA$L_VAR register.
During the progress of a data transfer over the MASSBUS, the MBA$L_
VAR register is continuously updated so that it points to the current
position in the data area. The VAX Hardware Handbook illustrates the
mapping of the contents of the MBA$L_VAR register into physical memory.

15.1.2

MASSBUS Adapter Registers and Offsets
During system initialization, VMS builds an adapter control block (ADP),
a channel request block (CRB), and an interrupt dispatch block (IDB) for
each MASSBUS adapter. The system also allocates 4KB of system virtual
address space for the adapter's register I/O space. The base of this I/O
register virtual address space is placed in IDB$L_CSR. Thus, you can
access MASSBUS adapter registers using the base register virtual address
plus some offset. The $MBADEF macro defines the offsets for MASSBUS
adapter registers. The major symbols defined by this macro are shown in
Table 15-1.
Table 15-1

Major Offsets Defined by $MBADEF

Symbol

MBA Register Name

MBA$L_CSR

Configuration register

MBA$L_CR

Control register

MBA$L_SR

Status register

MBA$L_VAR

Virtual-address register

MBA$L_BCR

Byte-count register

MBA$L_DR

Diagnostic register

MBA$L_SMR

Selected map register

Hex Offset

(continued on next page)

15-4

MASSBUS Device Support
15.1 MASSBUS Adapter Registers

Table 15-1 (Cont.)

Major Offsets Defined by $MBADEF

Symbol

MBA Register Name

Hex Offset

MBA$L_CAR

Command-address register

MBA$L_ERB

External register base

400

MBA$L_AS

Attention-summary register

414

MBA$L_MAP

Base of map registers

800

The MASSBUS adapter's internal registers occupy the low-order 1024
bytes of address space even though there are only eight internal MBA
registers. Beyond the internal registers, there are eight blocks of 32
longwords (128 bytes) each, one block for each of the eight device
controllers that can be connected to a single MASSBUS adapter. Each
of these blocks provides space for the device registers of each controller.
Beyond the device-register space is the area reserved for the MASSBUS
adapter's 256 map registers.
Figure 15-3 illustrates the relative positions of the MASSBUS adapter's
registers and the values device drivers use to gain access to them. The
base address of the MASSBUS adapter's address space, stored in IDB$L_
CSR, is the address of the first of the MASSBUS adapter's internal
registers.
IDB$L_CSR represents the internal register's virtual location, while the
MBA$L_ symbols represent register values as defined by $MBADEF. Note
that the MASSBUS adapter's register space occupies only the first 3Kb out
of the 8Kb allotted to physical 1/0 address space. However, by convention,
VMS allocates 4Kb of virtual addresses to each MASSBUS adapter.
To address a map register in the MASSBUS adapter, the driver constructs
the following address:
IDB$L_CSR + MBA$L_MAP +map-register-index
To address a device register, the driver constructs the following address:
IDB$L_CSR + MBA$L_ERB + (unit-number * 8015) + registerdisplacement
An individual driver should define offsets for the registers of its device.
During execution, the driver computes a register address by summing the
MBA's starting virtual address (the contents of IDB$L_CSR), MBA$L_
ERB, the unit number of the device controller multiplied by 8016, and the
offset of the specified register.

The attention-summary register (MBA$L_AS), as shown in Table 15-1,
appears to reside within the external-register space reserved for
MASSBUS adapter controller 0. Actually, the attention-summary register
is a composite register. Each of the MASSBUS adapter's controllers
contributes one bit of information to the register. This composite register
appears in each of the eight device register spaces at offset 1016 from
the base of the device registers for that device. Thus, MBA$L_AS can be

15-5

MASSBUS Device Support
15.1 MASSBUS Adapter Registers

Figure 15-3 Location of MASSBUS Registers in Physical Address
Space

MASSBUS Internal Registers
IDB$L_CSR
Unit ODevice Registers
IDB$L_CSR+MBA$L_ERB=(X"80 *Q)
Unit 1 Device Registers
IDB$L_CSR+MBA$L_ERB=(X"80 *1)
Unit 2 Device Registers
IDB$L_CSR+MBA$L_ERB=(X"80 *2)
......
..,..

•
•
•

4Kb

......
..,..

Unit 7 Device Registers
IDB$L_CSR+MBA$L_ERB=(X"80 *7)
Map Registers
IDB$L_CSR+MBA$L_MAP
1024 Unused Bytes
ZK-0940-GE

defined as any of the values 41015, 49016, 51015, 59015, and so on. For
convenience, it has been defined as 41015.

15.1.3

Modifying MASSBUS Adapter Registers
The driver for a MASSBUS device must obtain ownership of the MBA
before modifying any of the MBA's internal registers or map registers. A
driver obtains ownership of the MBA by invoking either the REQPCHAN
macro or the REQSCHAN macro, depending on whether the device is
connected to a single-unit MASSBUS controller or a multiunit MASSBUS
controller.
For dedicated controllers, invoke the REQPCHAN macro. Because the
controller is dedicated to its single device, there is never any contention
for the controller.
For multiunit devices, however, invoke the REQSCHAN macro to obtain
MBA ownership because several devices can share the controller, and
so must contend for its use. The controller for several devices relegates
the MASSBUS adapter to a secondary position. Thus, for multiunit
controllers, invoke REQPCHAN to gain ownership of the controller, and
invoke REQSCHAN to obtain the MASSBUS adapter.

15-6

MASSBUS Device Support
15.2 1/0 Database for MASSBUS Devices

15.2

110 Database for MASSBUS Devices
During initialization, the system creates an ADP, a CRB, and an IDB for
each MASSBUS adapter included in the configuration. The driver-loading
procedure subsequently builds additional data structures for each device
controller connected to a MASSBUS adapter. The type of structure created
depends upon whether the device controller is a dedicated controller or the
controller of several devices.
The system builds a unit control block (UCB) for each single-unit
controller. Figure 15-4 illustrates the I/O database for a MASSBUS
adapter with one dedicated controller attached to it. Note that the ADP,
CRB, and IDB all correspond to the MASSBUS adapter and can logically
be considered a single, extended data block. The UCB corresponds to the
device/controller pair. Because of the one-to-one correspondence between a
dedicated controller and its device, the system does not need to distinguish
between the two and thus does not maintain separate data blocks for each
piece of hardware.
Figure 15-4 1/0 Database for MASSBUS Disk Unit

Hardware
Configuration

MBA .........

Associated
Database

I ......
I
......
I
I
I
I
I

RP06

ADP

...... ......

I
I

...... ......

1-----"---- ~ UCB

...... ......

...... .......

...... CRB

,,
IDB

ZK-0941-GE

A controller of several devices, however, requires separate data structures
for the controller and each of its subunits (devices). The driver-loading
procedure builds a CRB/IDB pair for the controller, as well as a UCB for
each subunit. Figure 15-5 shows the I/O database created for a MASSBUS
adapter with one disk unit and two tape units.

15-7

MASSBUS Device Support
15.2 1/0 Database for MASSBUS Devices

Figure 15-5 110 Database for MASSBUS Disk and Tape Units
Hardware
Configuration

Associated
Database
ADP

~---------------------------~----------I

IDB

RP06 -------------~---- UCB

MBA
Unit
0

I
I
I
I
I
I
I
I
I

---T--- UCB
1

I
I
I
I
I
I
I
I

Unit

___ l_ __

IDB

UCB

I
I
I
I

ZK-0942-GE

Figure 15-5 does not include several pointers used in interrupt
dispatching. In particular, the IDB associated with the MASSBUS
adapter maintains an array of up to eight longwords that point to the
data structures associated with the eight possible MASSBUS controllers
attached to the MASSBUS.
For dedicated controllers, the IDB longword points to the device's UCB;
whereas, for a controller for several devices, the longword (or longwords)
points to a field within the CRB associated with the controller. The low
bit of this longword, when set, indicates a multiunit vector. The software
checks this bit to determine whether the longword points to a single UCB
or a multiunit CRB.
Also not pictured in Figure 15-5 is how multiunit IDBs also maintain an
array of longwords. Each longword points to the individual UCBs for the
units attached to the controller. Figure 15-6 illustrates in more detail the
set of I/O data structures for the MASSBUS adapter and its devices.

15-8

MASSBUS Device Support
15.2 1/0 Database for MASSBUS Devices

Figure 15-6 1/0 Data Structures Used in Dispatching a MASSBUS Device Interrupt
ADP

Disk
UCBO

IDB for MBA

CRBfor MBA

.--+

MBA CONFIG. REG

MBA Unit 0 _iDis~
CRB

t--J

IDB

I-'

r--1

...._,

i...

...

ADP CSR
Link
INTD+1
ADP

Tape
UCBO

IDBforTM03

CRBforTM03

......,

ADP

14--

IDB

'4-

1---

CRB

MBA Unit 1J.T~el

.......,

CRB
UCBO
UCB 1

1--'

t---i

Tape
UCB 1
~

i--

CRB

ZK-0943-GE

15.3

MASSBUS Adapter Operations
The MASSBUS accepts two kinds of operations: data transfer operations
and nondata transfer operations. Data transfer operations require the use
of MASSBUS adapter shared resources, while nondata transfers do not.
Before a driver can activate a data transfer operation on the MASSBUS,
the driver must request and receive ownership of the MASSBUS adapter
on behalf of the device unit. However, drivers must not initiate nondata
transfer operations while they have control of the MASSBUS adapter.
Section 15.4.1 explains this statement further.
The MASSBUS adapter generates interrupts when data transfers
terminate and when attention conditions arise on devices. When an
interrupt occurs on the MASSBUS adapter, the MASSBUS adapter's
interrupt dispatcher determines whether the interrupt is for a data
transfer or an attention condition.
15-9

MASSBUS Device Support
15.3 MASSBUS Adapter Operations

Data transfer interrupts occur when a data transfer either completes or is
aborted. When the interrupt occurs, the MBA's status register (MBA$L_
SR) contains information about the condition that caused the interrupt.
Attention interrupts occur when nondata transfers on MASSBUS devices
terminate, or when the device undergoes an exceptional condition, such as
coming on line.
The MASSBUS adapter's attention-summary register controls attentioninterrupt handling. This register contains eight bits of data, one for each
of the eight possible controllers that can be connected to the MASSBUS
adapter. When a device incurs an attention condition, the hardware sets
the corresponding bit in the attention-summary register and generates a
MASSBUS adapter interrupt.
If the attention condition occurs while a data transfer operation for

another device is in progress, the hardware sets the bit in the attentionsummary register but suppresses the attention interrupt. The interrupt
generated when the data transfer is completed allows the MASSBUS
adapter's interrupt dispatcher to gain control, handle the data transfer
interrupt, check the attention-summary register and then invoke the
proper driver to handle the attention condition.

15.4

MASSBUS Adapter's Interrupt Dispatching
When interrupts occur on the MASSBUS adapter, the MASSBUS adapter's
interrupt dispatcher gains control. This routine first determines whether
the interrupt is the result of a data transfer or an attention condition.
The routine checks to see if the MASSBUS adapter is owned and, if so, by
whom.

15.4.1

Checking for MASSBUS Adapter Ownership
There are two conditions by which the interrupt dispatcher can determine
that the interrupt is an attention interrupt:
•

If the MASSBUS adapter is not owned

•

If the MASSBUS adapter is owned, but the owner is not expecting an

interrupt (UCB$V_INT in UCB$L_STS is clear)
When the MASSBUS adapter is owned and the owner expects an
interrupt, the interrupt is assumed to be the result of a data transfer
operation.
As mentioned earlier, a driver must not initiate nondata transfers on
the MASSBUS adapter while it owns the adapter. For example, consider
a MASSBUS adapter attached to two disk units, A and B. Disk A is
performing an 10$_SEEK (a nondata transfer operation that completes
fairly quickly), while at the same time, disk Bis performing an 10$_
RECAL operation (a nondata transfer operation that takes about 0.5
seconds to complete).

15-10

MASSBUS Device Support
15.4 MASSBUS Adapter's Interrupt Dispatching

The driver for disk A correctly initiates its operation without obtaining
possession of the MASSBUS adapter channel, but the disk B driver
initiates its operation while it owns the MASSBUS adapter. Both of these
operations, upon completion, set the bit in the attention-summary register
that corresponds to their respective drive units, and initiate an interrupt.
We will assume that disk Ns 10$_SEEK is completed first. The operation
sets disk Ns bit in the attention-summary register and generates the
MASSBUS adapter's interrupt.
The MASSBUS adapter's interrupt dispatcher finds that the adapter
is owned, and that the owner is expecting an interrupt. Therefore, the
interrupt dispatcher incorrectly assumes that it is handling a data transfer
interrupt, and, moreover, that this interrupt is the one for which the owner
of the MBA is waiting.
As a result, the MASSBUS adapter's interrupt dispatcher returns control,
through the fork block in the MASSBUS adapter owner's UCB, to the
driver for disk B, even though disk B's operation has not completed. The
disk B driver will now incorrectly assume that the device has completed
its operation, which can cause serious problems.

15.4.2

Dispatching a Device Interrupt
Once the MASSBUS adapter's interrupt dispatcher determines the type
of interrupt, it dispatches the interrupt to the driver. The interrupt
dispatcher handles attention interrupts and data transfer interrupts in
the same way, with one exception: on an attention interrupt, the interrupt
dispatcher clears the MASSBUS adapter's status register (MBA$L_SR)
before dispatching the interrupt to the driver. The status register contains
information used only in data transfer interrupt dispatching.
How the interrupt dispatcher dispatches the interrupt to the driver differs
depending on the type of controller.
The MASSBUS adapter's interrupt dispatcher handles a solicited interrupt
on a dedicated controller by transferring control to the driver through the
fork block in the UCB. On unsolicited interrupts on dedicated controllers,
the interrupt dispatcher calls the driver's unsolicited interrupt service
routine.
On dedicated controllers, the MASSBUS adapter's interrupt dispatcher
always clears the attention bit in the attention-summary register before it
calls back the driver after an interrupt.
Dispatching interrupts to the driver of a device that shares its controller
with several other devices differs in two ways from dispatching interrupts
to the driver of a device with a dedicated controller.
First, the interrupt dispatcher never clears the attention bit. This task
is left to the driver because some controllers that control more than one
device use this bit to synchronize their activities, and guarantee the
integrity of device registers only while the bit is set. If the interrupt
dispatcher clears the bit before returning control to the driver, the driver
can no longer rely on the contents of the device's registers.

15-11

MASSBUS Device Support
15.4 MASSBUS Adapter's Interrupt Dispatching

Second, a controller that controls several devices needs another interrupt
dispatcher to handle simultaneous requests from its several subunits.
This second-level interrupt dispatcher resides in the driver. After an
interrupt, the MASSBUS adapter's interrupt dispatcher indirectly calls
this second driver's interrupt dispatcher using code in the controller's
CRB. The driver-loading procedure installs this code when it establishes
the 1/0 database.

15.5

Special Considerations for MASSBUS Device Drivers
MASSBUS adapter considerations affect a driver's device unit
initialization routine, start-110 routines and, for multiunit controllers
only, the driver's use of the DPTAB macro. MBA considerations also affect
interrupt handling, as described in Section 15.4.2. The next sections in
this chapter discuss programming details for writing a MASSBUS device
driver.

15.5.1

Unit Initialization Routine
All drivers for MASSBUS adapter devices initialize two fields in the UCB
(as well as initializing device-specific fields): UCB$B_SLAVE and
UCB$B_SLAVE+l. The first of these fields should contain the controller's
MASSBUS adapter unit number, which marks the controller's position
on the MASSBUS adapter. The second of these contains the offset, in
longwords, from the start of the MASSBUS adapter's external registers
to this controller's device registers. The value of this longword offset is
always 32 times the unit number of the controller.
Initialization of a device attached to a dedicated controller is simple
because the device unit number and the controller position number on
the MASSBUS adapter are always equal. To initialize the field UCB$B_
SLAVE, copy to it the contents of UCB$W_UNIT. To initialize UCB$B_
SLAVE+l, multiply the contents of UCB$W_UNIT by 32. The driver's
fork process or interrupt service routine later uses this information to
compute a pointer to this device's registers. By convention, R4 points to
the MASSBUS adapter configuration register, and R5 points to the UCB of
this device.
Thus, the following two instructions cause R3 to point to the device
registers during normal system operation:
MOVZBL
MO VAL

UCB$B_SLAVE+l(R5),R3
MBA$L_ERB(R4) [R3],R3

For devices connected to a controller that controls several devices,
determination of the controller's MBA position is more complex. When
the unit initialization routine is invoked, the following values are in the
following registers:

15-12

Address of controller's device registers

Address of the MBA's configuration register

Address of device's UCB

MASSBUS Device Support
15.5 Special Considerations for MASSBUS Device Drivers

The driver computes the MBA position of the controller by using R3 and
R4 to determine the number of bytes from the start of the MBA's external
registers to the start of the device's device registers. The difference, when
divided by 128, is the controller's MBA position number.

15.5.2

The MASSBUS Adapter and the 1/0 Database
The UCB of a device connected to a single-unit controller, at offset
UCB$L_CRB, contains the address of the MASSBUS adapter's CRB. This
CRB in turn contains, at offset CRB$L_INTD+VEC$L_IDB, the address of
the MASSBUS IDB. This IDB points to the base address of the MASSBUS
adapter registers at offset IDB$L_CSR.
A controller that controls several devices maintains a more complicated
1/0 database. The device UCB, at offset UCB$L_CRB, points to the
controller's CRB, and this structure points to the CRB for the MASSBUS
adapter at offset CRB$L_LINK. Also, the controller's CRB points to its
own IDB at offset CRB$L_INTD+VEC$L_IDB. This IDB points to the
controller's device registers at offset IDB$L_CSR.
Thus, the UCB for a device always points to that device's primary CRB,
whether it is the MASSBUS adapter's CRB or the controller's CRB. The
primary CRB points to the secondary CRB, if one exists for the device.
Figure 15-6 shows these relationships among 1/0 data structures.

15.5.3

Start-1/0 Routine
Depending on the function being executed, the start-110 routine for a
MASSBUS device performs all or some of the following tasks:
•

Requests, if necessary, controller data channel(s) as described in
Section 15.5.3.1

•

Clears errors on the MASSBUS adapter by placing the value -1
into the MBA's status register; this is a write-ones-to-clear register
(MASSBUS device registers and the MBA's registers are all longwords)

•

Invokes the LOADMBA macro to load the MBA's map registers as
described in Section 15.5.3.2

•

Loads device registers to start the function

•

Waits for a device interrupt or timeout

•

Releases, if necessary, controller data channel(s) as described in
Section 15.5.3.3

•

Finishes the request like other drivers

15-13

MASSBUS Device Support
15.5 Special Considerations for MASSBUS Device Drivers

15.5.3.1

Requesting Controller Data Channels

Device drivers for MASSBUS devices must request and receive ownership
of the MASSBUS adapter channel before loading the MBA's internal
registers or map registers. In addition, drivers for devices connected to
multiunit controllers must obtain ownership of the controller channel
before modifying the contents of controller registers that can be shared
among the units connected to the controller.
Drivers for dedicated controllers must request ownership of the MASSBUS
adapter channel by invoking the macrd REQPCHAN.
Device drivers for controllers that control several devices invoke the
REQPCHAN macro when the operation requires ownership of only the
primary channel (the controller's channel). However, if the operation
requires ownership of both primary and secondary channels (a data
transfer operation), the driver must first obtain the controller channel and
then request the MASSBUS adapter channel by invoking the REQSCHAN
macro.
Again, the driver needs ownership of both channels only when performing
a data transfer, and must release the channels before initiating a nondata
transfer. Thus, a driver must obtain ownership of the MASSBUS adapter
channel some time before initiating a data transfer and must either
not own the channel or release such ownership before it invokes the
WFIKPCH macro, or issue the WFIRLCH macro, following the start of a
nondata transfer operation.
15.5.3.2

Loading Map Registers

MASSBUS device drivers invoke the LOADMBA macro before they initiate
a data transfer, to load the MBA's map registers, the MBA's virtual-address
register (MBA$L_VAR), and the MBA's byte-count register (MBA$L_BCR).
Drivers cannot modify these registers during a transfer. The LOADMBA
macro expects the following register contents:
•

The address of the MBA's configuration register (MBA$L_CSR) in R4

•

The address of the device UCB in R5

LOADMBA preserves the contents of R3 but modifies RO through R2. The
macro performs the following steps:

15-14

Uses the contents of UCB$W_BCNT and UCB$W_BOFF to determine
the number of pages that contain pieces of the 1/0 buffer.

Beginning with the page-table entry to which UCB$L_SV.APTE points
and continuing for the number of page-table entries determined in step
1, copies the page-frame numbers from the page-table entries to the
corresponding map registers, starting at map register 0.

Ensures that the valid bit is clear in the map register that immediately
follows the last map register loaded with a PFN. This prevents a
hardware fault or prefetch from modifying memory.

Moves the negative value of the transfer byte count (UCB$W_BCNT)
into the MBA's byte-count register (MBA$L_BCR).

MASSBUS Device Support
15.5 Special Considerations for MASSBUS Device Drivers

Moves the byte offset in the first page of the transfer (UCB$W_BOFF)
into the MBA's virtual-address register (MBA$L_VAR).

Returns to the start-I/0 routine that invoked it.

If the I/O operation about to be initiated by the driver is a reverse
operation (a read-reverse on tape), the driver must modify the contents
of the MBA's virtual-address register set up by LOADMBA. Because
reverse operations access the I/O buffer from its highest address through
its lowest address, the value to be loaded into the MBA's virtual-address
register must be the virtual address, in MBA's virtual memory, of the last
byte of the buffer. This number is equal to one less than the sum of the
contents of UCB$W_BOFF and UCB$W_BCNT.
15.5.3.3

Releasing Controller Data Channels

The driver releases the controller data channels by invoking the
RELCHAN macro. RELCHAN releases all controller channels (both
primary and secondary) currently owned by the device. To release only the
secondary channel and retain ownership of the primary channel, a driver
can invoke the RELSCHAN macro.

15.5.4

DPTAB Macro
The device driver for a MASSBUS device that shares its controller with
other devices must set the DPT$V_SUBCNTRL bit in the flags argument
of the DPTAB macro. Setting this bit causes the driver-loading procedure
to create a second CRB and an IDB for the controller.

15.6

Interrupt Service Routines for MASSBUS Devices
The MASSBUS interrupt dispatcher (MBA$INT) gains control when it
receives an interrupt from the MASSBUS adapter. Because data transfers
in progress suppress attention interrupts on the MASSBUS adapter, and
because several devices can request attention simultaneously, several
device drivers might need to be informed of the interrupt.
MBA$INT determines which drivers should be invoked as a result of
the interrupt and then passes control to these drivers. For data transfer
interrupts, MBA$INT preserves the value contained in the MBA's status
register at the time of the interrupt so that the driver can have access to
this value.
For 1/0 operations that involve no data transfer, MBA$INT clears this
register before invoking the driver. MBA$INT only preserves the contents
of registers R2 through R5. Drivers that use other registers must save the
contents of those registers, and must restore them before exiting from the
interrupt service routine.

15-15

MASSBUS Device Support
15.6 Interrupt Service Routines for MASSBUS Devices

15.6.1

Transferring Control to the Interrupt Service Routine
The method by which MBA$INT invokes a driver depends upon whether
the driver serves a device connected to a dedicated controller or a device
that shares its controller with several other devices. Furthermore, if the
device is connected to a dedicated controller, the method of transfer from
MBA$INT to the driver depends upon whether or not the interrupt is
expected.
For a device on a dedicated controller whose driver is expecting an
interrupt, MBA$INT restores the driver context saved in the UCB fork
block and transfers control (using a JSB instruction) to the instruction
that follows the wait-for-interrupt instruction.
For a device on a dedicated controller whose driver is not expecting
interrupts, MBA$INT obtains the address of the driver's unsolicited
interrupt service routine from the driver dispatch table and calls the
routine.
For a device that shares its controller with several other devices,
MBA$INT transfers control to the driver's interrupt service routine by
simulating a direct transfer, through an interrupt vector, to the controller's
CRB. The CRB contains code that transfers control to the interrupt service
routine.
MBA$INT first pushes the processor status longword (PSL) onto the
stack. The routine then calls (with a JSB instruction that leaves an
address within MBA$INT on the stack) the code within the CRB. This
code contains the following sequence of instructions, where :XX$INT is the
address of the interrupt service routine and :XX$IDB is the address of the
controller's IDB:
PUS HR
JSB
.LONG

#AM<R2,R3,R4,R5>
XX$INT
XX$IDB

The execution of the previous instruction sequence, plus the instructions
executed by MBA$INT (the pushing of the PSL onto the stack and the
JSB), places a simulated interrupt frame onto the stack, including a saved
PSL, a saved PC, saved registers, and a pointer to an address in the IDB.

15.6.2

Returning Control to MBA$1NT
The way in which a driver returns control to MBA$INT depends on the
way in which MBA$INT invoked it. Drivers for dedicated controller
devices return to MBA$INT through an RSB instruction, although the
RSB can execute as a result of the driver's invoking the IO FORK macro.
Drivers of devices that share a controller return control to MBA$INT
by removing the indirect pointer to the IDB from the top of the stack,
restoring registers R2 through R5, and executing an REI instruction.
This sequence, executed within the driver's interrupt service routine,
eliminates the simulated interrupt frame from the stack before returning
to MBA$INT.

15-16

MASSBUS Device Support
15.6 Interrupt Service Routines for MASSBUS Devices

15.6.3

Considerations for Interrupt Service Routines
Drivers for dedicated controller devices attached to the MASSBUS do
not have interrupt service routines. Instead, MBA$INT handles all the
functions that a driver interrupt service routine normally provides.
Drivers of devices that share a controller on the MASSBUS must have
their own interrupt service routines. In general, these routines perform
the same functions as the interrupt service routines for UNIBUS and Q22
bus devices (discussed in Chapter 9). However, the two types of drivers
diverge in two areas.
One difference between UNIBUS/Q22 bus and MASSBUS drivers concerns
the number of registers saved by the interrupt service routine. When the
interrupt dispatcher transfers control to a MASSBUS driver interrupt
service routine, registers R2 through R5 are pushed onto the stack.
UNIBUS/Q22 bus drivers save RO through R5.
After handling an interrupt, both MASSBUS and UNIBUS/Q22 bus driver
interrupt service routines execute an REI instruction. For UNIBUS/Q22
bus devices, the REI dismisses a real interrupt, whereas the MASSBUS
driver's REI returns control to MBA$INT.

15-17

Generic VAXBI Device Support

This chapter provides information needed to write and load a device
driver for a non-Digital-supplied device attached to the VAXBI bus. VMS
provides special support for such devices in the system initialization
routines for the VAX 82x0/83x0, VAX 85x0/8700/88x0, VAX 6000series, and VAX 9000-series systems. Because of the many and varied
implementations of VAX.BI devices, however, VMS support must of
necessity be very general. Some devices may more fully utilize the VAXBI
interface than others; a device may incorporate its interface initialization
logic in microcode, whereas another may defer initialization to code in its
driver.
The VAXBI Options Handbook includes a description and guidelines for
possible VAXBI device implementations. Refer to that manual for further
discussion of all VAXBI topics discussed in brief in Section 16.2 and
elsewhere in this chapter.

16.1

Overview
A VAX.BI device driver refers to the same data structures and contains the
same routines as a traditional VMS driver. A VAX.BI device driver deviates
from the traditional VMS driver almost exclusively in code that initializes
the VAX.BI interface or supports direct-memory-access CDMA) transfers
for devices that address memory across the VAXBI bus. Section 16.5
discusses tasks that drivers of various VAXBI devices may perform in
their initialization routines to supplement VMS initialization and that
initialization performed by device microcode. Section 16.6 contains a
general discussion of how some VAX.BI devices and their drivers manage
DMA transactions.
Section 16.4 describes those data structures the VMS adapter initialization
routine creates and prepares for a generic VAX.BI device, while
Section 16.9 discusses the method by which its driver can be loaded into
the operating system. The final section of this chapter provides reference
material and includes a description of the backplane interconnect interface
chip (BIIC) registers.

16.2

VAXBI Concepts
The VAX.BI serves as an I/O bus for the VAX 82x0/83x0, VAX 85x0/8700
/88x0, VAX 6000-series, and VAX 9000-series systems (see Figure 1-3).
The VAXBI is also the system bus for the VAX 82x0/83x0 systems. The
VAX 82x0/83x0 systems have a single VAXBI; the VAX 85x0/8700/88x0,
VAX 6000-series, and VAX 9000-series systems can have multiple VAX.BI
buses.

16-1

Generic VAXBI Device Support
16.2 VAXBI Concepts

Each location on a VAX.BI bus is called a node. A single VAX.BI bus
can service 16 nodes. In the case of the VAX 82x0/83x0 systems, these
nodes can be processors, memory, and adapters; the VAX 85x0/8700/88x0
and VAX 6000-series systems permit only adapters to be attached to the
VAX.BI bus. 1 A node receives its node ID, a number from 0 to 15, from a
plug on the VAX.BI backplane slot into which the node module is inserted.
An adapter is a node that connects other buses, communication lines, and
peripheral devices to the VAX.BI bus. This chapter uses the term device
to refer to a device or combination of devices serviced by a single adapter
or controller.

16.2.1

VAXBI Address Space
Each VAX.BI bus supports 30-bit addressing capability. This gigabyte of
physical address space is split equally between memory and I/O address
space, as shown in Figure 16-1.
All memory locations on a VAX.BI bus are addressed using physical
addresses in VAX.BI memory space (from 0000000016 through
1FFFFFFF1a). A VAX.BI device that accesses memory directly (or
indirectly through a memory-interconnect-to-VAXBI adapter), or its driver,
must perform virtual-to-physical translation before transmitting a memory
address on the bus. (See Section 16.6 for additional information.)
Figure 16-1

VAXBI Address Space

Hex Address
0000 0000

Memory Space
512Mb

2000 0000

l/OSpace
512Mb

3FFFFFFF
ZK-5541-GE

For VAX 85x0/8700/88x0, VAX 6000-series, and VAX 9000-series systems, the memory-interconnect-to-VAXBI
adapter (NBI, PBI, or DWMBA) or, more specifically, the NBIB, PBIB, or DWMBA/B resides at a node on
a VAXBI bus, monitoring and controlling transactions to the memory interconnect (NMI, NMis, or XMD
where the processors and memory reside.

16-2

Generic VAXBI Device Support
16.2 VAXBI Concepts

VAXBI 1/0 address space (physical addresses 2000000016 through
3FFFFFFF16 ) is partitioned as illustrated in Figure 16-2. Figure 16-3
shows the structure of a VAXBI 1/0-space address.
Figure 16-2

Description of VAXBI 1/0 Address Space
Hex Address

Node ONode Space
(8Kb)

...

2000 0000
20001FFF

2001 EOOO
Node 15 Node Space
(8Kb)

2001 FFFF
2002 0000

Multicast Space
(128Kb)
2003 FFFF
2004 0000

Node Private Space
(3.75Mb)

NodeO
Window Space
(256Kb)

203F FFFF
2040 0000

...

2043 FFFF

Node 15
Window Space
(256Kb)

207C 0000
207FFFFF

Reserved

Reserved
(For multiple VAXBI systems)
(480Mb)
3FFFFFFF
ZK-5542-GE

16-3

Generic VAXBI Device Support
16.2 VAXBI Concepts

Figure 16-3

Physical Addresses in VAXBI 1/0 Address Space

l/OSpace

CJ
B

Specifies which VAXBI bus

24 23
If not zero bits <24: 23>, indicate reserved space
22

Window Space
21

~ Specifies which node's window space
17

I....________________.I Window Space Address
22

Non-Window Space

212019 18

~ If not zero bits <21 :18>, indicate node private space
17

D
CJ

NodeSpace

NodelD
12

I. . ______________I

Node Space Address

Multicast Space

I....__________________.I Multicast Space Address
ZK-5543-GE

16-4

Generic VAXBI Device Support
16.2 VAXBI Concepts

As shown in Figures 16-2 and 16-3, VAXBI architecture grants each of
the 16 nodes on a VAXBI bus two discrete sections in I/O address space.
Node space

An 8KB block of addresses consisting of 256 bytes of BllC
CSR space, followed by user interface CSR space. A
device can access the control and status registers (CSRs)
of its backplane interconnect interface chip by using BllC
CSR space addresses. Device-specific registers reside in
user interface CSR space.
Because the VMS adapter initialization routine virtually
maps node space for each VAXBI node on each VAXBI bus,
a device driver can access both BllC registers and device
registers using virtual addresses. (See Sections 16.5 and
16.6 for a discussion of driver access to registers.)

Window space

A 256KB block used by a VAXBI adapter to map an
1/0 transfer to a target bus. Because VMS does not
automatically map window space to virtual addresses,
a driver that manipulates addresses in window space
must itself allocate and fill sufficient system page-table
entries for the range of its window space addresses. (See
Section 16.5.)

Note that node private space contains locations used for the storage of
bootstrap firmware and software. VAXBI nodes are not permitted to issue
or respond to VAXBI transactions targeting locations in node private space.

16.2o2

Backplane Interconnect Interface Chip (BllC)
The backplane interconnect interface chip (BIIC) serves as the
primary interface between the VAXBI bus and the user interface logic of
a node. The BIIC supplies the logic necessary for a node to initiate and
respond to transactions on the VAXBI bus, arbitrate bus ownership, send
and receive interrupt requests, and monitor bus errors.
A node can enable, control, and monitor such activities by accessing
the set of BIIC registers located in the first 256 bytes of its node space.
Because the VMS adapter initialization routine virtually maps node space
addresses, drivers for VAXBI devices can use virtual addresses to access
BIIC registers. In addition, given the virtual address of the base of a
device's node space, a driver can use the symbolic offsets, masks, and bit
fields defined by the VMS macro $BIICDEF (in SYS$LIBRARY:LIB.MLB).
Table 16-1 in Section 16.10 describes these symbols.

16.3

SCU/XMI Concepts
As shown in Figure 1-4, the XMI bus of an SCU/XMI system, such as a
VAX 9000, serves as the primary I/O bus. Each XMI bus supports 30-bit
addressing and provides 1 gigabyte of physical address space. Like the
VAXBI address space, the total VAX 9000 address space is divided into
equal areas of memory and I/O address space, as shown in Figure 16-1.
All memory locations on a VAX 9000 XMI bus are addressed using
physical addresses in XMI memory space (from 0000 000016 through
lFFF FFFF16)·

16-5

Generic VAXBI Device Support
16.3 SCU/XMI Concepts

VAX 9000 XMI 1/0 address space (physical addresses 2000 000015 through
3FFF FFFF16) is partitioned as illustrated in Figure 16-4.
Figure 16-4 SCU/XMI Systems 1/0 Address Space

XMIO Node Space
XMI 1 Node Space
XMl2 Node Space
XMl3 Node Space
XBIO Window Space
XBl1 Window Space
XBl2 Window Space
XBl3 Window Space
XBl4 Window Space
XBIS Window Space
XBl6 Window Space
XBl7 Window Space
XBl8 Window Space
XBl9 Window Space
XBIA Window Space
XBIB Window Space
XBIC Window Space
XBID Window Space
XJAO Private Space
XJA 1 Private Space
XJA2 Private Space
XJA3 Private Space
SCU Register Space

Hex Address
2000 0000
2080 0000
2100 0000
2180 0000
2200 0000
2400 0000
2600 0000
2800 0000
2AOO 0000
2COO 0000
2EOO 0000
3000 0000
3200 0000
3400 0000
3600 0000
3800 0000
3AOO 0000
3COO 0000
3EOO 0000
3E08 0000
3E10 0000
3E18 0000
3E20 0000
3FFFFFFF
ZK-1938A-GE

The assignment of 110 addresses, shown in Figure 16-4, for any VAX 9000
system supports two levels of bus structure: the XMI and the VAXBI. A
VAX 9000 system uses the XMI as an 1/0 bus and may have up to 4 XMls,
depending on the model. Each XMI can have up to 12 nodes or devices
numbered 1 through D hexadecimal. (The XJA adapter occupies node 0 on
an XML)

16-6

Generic VAXBI Device Support
16.3 SCU/XMI Concepts

The four XMI-bus node spaces (XMIO to XMI3) are assigned the first
region of XMI 1/0 address space. By means of address translation
performed by the system control unit (SCU) and the 1/0 control unit,
CPUs address individual XMI device CSRs using XMI nodes pace.
Fourteen XBI window space regions follow XMI nodespace, one for each
DWMBA adapter that might be present on any of the XMI buses. A
DWMBA is an 1/0 adapter that connects a VAXBI bus to an XMI bus.
Each DWMBA (14 maximum) is physically mapped into its own XBI
window space (XBix) in the 1/0 block. The VAXBI window spaces are
named XBIO to XBID16 , and span the XBI window space region. XBI
window space allows CPUs to address the individual VAXBI device CSRs.
In XM:I I/O space, a given XBI's window space is determined by the XBI's
XMI node number. There is a limit of 8 XBis on a given XMI bus and a
limit of 14 XBis across all XMI buses. In the assignment of XBI window
spaces, the XBI with the lowest node number on XMIO is assigned to XBIO
window space. The XBI with the second lowest node number in XMIO is
assigned to XBil window space, and so on through all XBis on XMIO; then
to XMll, XMI2, and until XMI3 is exhausted or the 14th XBI is found.
An XJA of the SCU/XMI bus architecture is an adapter that connects the
SCU ports to the XMI bus. The XJAs have a private space region in the
1/0 block that allows CPUs to address the XJA CSRs. Since there are up
to four XMis, there can be four XJAs. In the XJA private space region,
XJAs are mapped XJAO through XJA3.

16.4

Initialization Performed by VMS
During the phase of system initialization known as adapter initialization
VMS performs a set of system-specific tasks to identify and configure
each device it discovers at each of the 16 nodes on each VAXBI bus in the
system configuration.
The adapter initialization module configures Digital-supplied and nonDigital-supplied devices alike, performing the following activities as part
of its initialization cycle:

Tests for the presence of a device at the node by issuing a MOVL
instruction, the target of which is a system virtual address temporarily
mapped to the first longword of its node space. If this instruction is
successful, it returns the contents of the BIIC Device Type Register of
the addressed node to the processor. 2

Records the contents of the low 16 bits of the BIIC Device Type
Register, plus an 1/0 bus identifier in the slot in the CONFREGL
array that corresponds to the VAXBI bus and node at which it found

If no device exists at a given VAXBI node address, the CPU becomes aware of this in a system-specific way.

For example, the VAX 82x0/83x0 systems experience a machine check, whereas the VAX 85x0/8700/88x0,
VAX 6000-series, and VAX 9000-series systems determine that the node is vacant by reading an NXM
(nonexistent memory) error from the BIIC Bus Error Register of the NBIB, PBIB, or DWMBA on the VAXBI
being examined.

16-7

Generic VAXBI Device Support
16.4 Initialization Performed by VMS

the device, 3 and compares this value against a table of recognized
device types.
3

If it recognizes the device, maps the number of pages specified in the

table for the device type, and places the system virtual address of the
base of the mapped node space in the slot in the SBICONF array that
corresponds to the VAXBI bus and node at which it found the device. 4
If it does not recognize the device, maps the entire SKB of the node's

node space into VMS virtual address space by allocating 16 system
page-table entries (SPTEs) and associating them with the 16 pageframe numbers (PFNs) of the physical addresses assigned to this
node's node space on this VAXBI bus. The adapter initialization
module then saves the base system virtual address of the resulting
BKB range in the longword slot corresponding to this node in the
SBICONF array.
4

Performs such additional tasks as allocating and filling in data
structures in a device-specific manner. For a non-Digital-supplied
device attached to a VAXBI bus, VMS creates generic versions of
the channel request block, interrupt dispatch block, and adapter
control block-and fills in the appropriate vectors in the system control
block-as discussed in Section 16.4.1.
For devices it does recognize, VMS additionally calls a VMS-supplied
subroutine, the address of which it obtains from the device-type table,
that performs further device-specific initialization.
For devices it does not recognize, VMS must defer device-specific
initialization to the device driver's initialization routine.

16.4.1

Data Structures
The adapter initialization module creates and prepares a channel request
block, interrupt dispatch block, and an adapter control block in the manner
described in this section. For each data structure it creates, VMS fills in
the first three longwords with the standard VMS header information (that
is, the structure type, size, and links).
Channel Request Block

For the newly created channel request block (CRB), VMS performs the
following tasks:
•

Sets up the resource wait queue header (CRB$L_WQFL and CRB$L_
WQBL)

The CONFREGL array is a set of longwords in system pool pointed to by EXE$GL_CONFREGL. The
CONFREGL array contains an entry for each possible VAXBI node. For VAX 82x0/83x0 systems, with one
VAXBI, this array has 16 entries. For VAX 85x0/8700/88x0, VAX 6000-series, and VAX 9000-series systems,
this array has 16 entries for each VAXBI bus on the system.
4
The SBICONF array is a set of longwords, similar in structure to the CONFREGL array and pointed to by
MMG$GL_SBICONF, that lists the system virtual addresses of the base of the node space for each node on
a VAXBI bus.

16-8

Generic VAXBI Device Support
16.4 Initialization Performed by VMS
•

Sets the bit CRB$V_UNINIT in CRB$B_MASK to indicate to the
System Generation Utility that, although the CRB exists, its controller
initialization routine has not yet been called

•

Initializes four interrupt dispatchers (CRB$L_INTD, CRB$L_INTD2,
and so on) so that they have the effect of pushing general registers RO
through R5 onto the stack, and issuing a JSB instruction

The adapter initialization module always creates the four vectors, in
contrast to the methods by which UNIBUS/Q22 bus drivers control the
number of vectors created (see Section 14.3.3). The destination of the JSB
instruction at initialization is a standard null interrupt handler which
merely dismisses the interrupt. Later, when the specific device driver
is loaded for the device (see Section 16.9), the driver's interrupt service
routine address replaces this null interrupt handler in the dispatchers.
As necessary, the driver specifies the addresses of its interrupt service
routines as follows:
DPT STORE,CRB,CRB$L INTD,D,isr for 1st vector
DPT-STORE,CRB,CRB$L-INTD2+VEC$L ISR,D,isr for 2nd vector
DPT-STORE,CRB,CRB$L-INTD+(2*VEC$K LENGTH)+VEC$L ISR,D,isr for 3rd vector
DPT=STORE,CRB,CRB$L=INTD+(3*VEC$K=LENGTH)+VEC$L=ISR,D,isr=for=4th=vector

Interrupt Dispatch Block

VMS initializes the interrupt dispatch block (IDB) in the following
manner:
•

Sets the number of device units controlled by this interrupt dispatch
block (IDB$W_UNITS) to 1. The list of unit control block (UCB)
addresses in this IDB, as a result, is one longword in size. The driverloading procedure writes a UCB address into this longword whenever
it creates a new UCB associated with the controller. Because there is
only one slot in this array, drivers for non-Digital-supplied multiunit
controllers must use a different mechanism to locate the UCB of
interest at the time of an interrupt.

•

Copies the virtual address of the base of this device's node space to
IDB$L_CSR from the corresponding slot in the SBICONF array.

Adapter Control Block

VMS creates a truncated adapter control block (ADP) for a non-Digitalsupplied VAXBI device (48 bytes as opposed to the traditional 600 bytes).
The ADP it creates contains no fields reserved for the allocation and
accounting of data paths or map registers. VMS prepares this generic
ADP in the following manner:
•

Copies the virtual address of the base of this device's node space to
ADP$L_CSR from IDB$L_CSR.

•

Places the VAXBI node ID of this device in ADP$W_TR.

•

Stores the value AT$_GENBI (signifying the generic VAXBI ADP type)
in ADP$W_ADPTYPE.

16-9

Generic VAXBI Device Support
16.4 Initialization Performed by VMS

16.4.2

•

Calculates the address of the first of the four interrupt vectors for
this node in the system control block (SCB), and places it in ADP$L_
AVECTOR. A driver can determine the addresses of the other three
SCB vectors by adding 64, 128, or 192, respectively, to the address of
this first SCB vector.

•

Saves the offset of this first SCB vector from the start of its SCB page
in ADP$W_BI_VECTOR. (Refer to Section 16.4.2 for a description of
the SCB.)

•

Places in ADP$L_BI_IDR a longword mask with a single bit set, as
appropriate to the VAX system, that specifies which VAXBI node
should become the destination of interrupts from this node. In VAX
82x0/83x0 systems, the VAXBI node of the primary processor becomes
the destination for interrupts. In VAX 85x0/8700/88x0, VAX 6000series, and VAX 9000-series systems, it is the VAXBI node of the
NBIB, PBIB, or DWMBA/B on the particular VAXBI bus on which this
device resides that becomes the destination for such interrupts.

•

Stores in ADP$L..:..MBASCB-and in each of the device's four SCB
vectors-the address of the interrupt dispatcher. The actual stored
value is CRB$L_INTD+l, CRB$L_INTD2, and so on, the set low bit of
the address indicating that the interrupt stack be used to service the
interrupt. Certain powerfail recovery operations use the contents of
ADP$L_MBASCB to refresh the SCB vectors.

•

Saves in ADP$L_MBASPTE the contents of the first of the 16 SPTEs
that map the device's node space. Certain recovery operations use
the contents of ADP$L_MBASPTE to restore correct SPTE values and
remap node space following a power failure.

•

Places in ADP$L_BIMASTER the address of the ADP of the memoryinterconnect-to-VAXBI-adapter (NBI, PBI, or DWMBA). Note that
there is no memory-interconnect-to-VAXBI adapter for VAX 82x0/83x0
configurations.

System Control Block
The system control block (SCB) consists of one or more pages of vectors.
For all VAX processing systems, the first half page contains vectors used
in exception dispatching. VMS uses the remainder of the first page, as
well as subsequent pages, in a system-specific way.
For VAX 82x0/83x0 systems, VMS assigns the vectors from 10016 to lFC16
to VAXBI devices in the order of their node IDs.
The VAX 85x0/8700/88x0 system architectures relegate vectors 10016 to
lFC16 to NMI nexus vectors in page 0. Page 1 is reserved for the first
"offsettable" device that exists in the system. (An "offsettable" device is
an adapter such as the VAXBI-to-UNIBUS adapter (DWBUA or DWMUA)
that passes interrupts from devices on another bus to the VAXBI and,
from there, to the memory interconnect (NMI or XMI) and the processor.)
If there is more than one "offsettable" device, an additional SCB page is
needed for each.

16-10

Generic VAXBI Device Support
16.4 Initialization Performed by VMS

illtimately, the vectors for other devices attached to each of the six possible
VAXBI buses of the system are contained in the six corresponding SCB
pages from page 26 to page 31. In a 4-VAXBI system, for instance, vectors
for devices connected to VAXBI 0 and VAXBI 1 on NBI/PBI/DWMBA 0
are assigned to pages 28 and 29 of the SCB, respectively; vectors for
devices connected to VAXBI 0 and VAXBI 1 on NBI/PBI/DWMBA 1 are
likewise assigned to pages 30 and 31. In a 6-VAXBI system, the vectors
are assigned in a similar fashion, starting at page 26.
For VAX 6000-series systems, the vectors for XM:I devices are assigned
from 10016 to 1FC16 in the first SCB page (page 0). Then vectors for
devices connected to VAXBI 0 start on page 1 and run from 30016 to
3FC1a, then devices for VAXBI 1 are assigned vectors (50016 to 5FC1a) in
page 2, and so on for the remaining VAXBis and respective pages.
For VAX 9000-series systems, the vectors for devices connected to XM:IO
bus are assigned from 10016 to 1FC16 in SCB page 0. Then vectors for
devices connected to XMil bus start on page 1 and run from 3001 a to
3FC1a, and so on for devices on buses up through XMI3 bus. Then, vectors
for devices connected to VAXBI 0 start on page 4 with vectors B001a to
BFC1a, and so on for the remaining VAXBI buses and respective pages.
Generally, a VAX processor obtains a device vector from the BIIC
registers of the node that has requested the interrupt (see Figure 16--5).
Information supplied in the device vector allows the processor to index
to the corresponding interrupt-dispatching vector in the appropriate page
of the SCB. For VAX 82x0/83x0 systems, such information includes the
interrupt level of the device and its VAXBI node ID. A similar vector for
VAX 85x0/8700/88x0, VAX 6000 series and VAX 9000-series devices further
specifies the appropriate NBI/PBI/DWMBA vector offset and the number
of the VAX.BI bus.
The specific SCB interrupt-dispatching vector, thus found, transfers control
to the interrupt-dispatching code in the device's CRB. Upon an interrupt
from this device, the SCB vector directs flow into the interrupt dispatcher
in the CRB, which saves the register contents and dispatches to the
interrupt service routine established by the device driver.

16.5

Initialization Performed by the VAXBI Device Driver
All generic VAXBI device drivers must specify GENBI as the adapter type
in the adapter argument to the DPTAB macro.
The device driver's initialization routines are expected to initialize the
device-specific aspects of the VAX.BI device. For non-Digital-supplied
devices, the initialization routines perform the sort of tasks that the
adapter initialization module performs for the Digital-supplied devices
it discovers on a VAXBI bus. For single-unit devices, a separate unit
initialization routine may not be necessary.

16-11

Generic VAXBI Device Support
16.5 Initialization Performed by the VAXBI Device Driver

Figure 16-5 VAXBI Device Vectors
For VAX 8200/8250/8300/8350
13

l&l~IVAXBINOOelDI

For VAX 8530/8550/8700/8800/8810/8820/8830,
VAX 6000 Series, and VAX 9000 Series Devices

9 8 7 6 5 4 3 2 1 0
NBl/PBl/XBI
Vector
Offset
Register

Select VAXBI Node ID

"&lecl" indicates one
of four interrupt vectors.
ZK-5545-GE

The VMS System Generation Utility (SYSGEN) calls the controller
initialization routine at IPL 31 (see Section 11.1), passing it the following
values in the listed general registers:
•

R4 pointing to the system virtual address of the device's node space

•

R5 pointing to the IDB

•

R6 pointing to the DDB

•

RS pointing to the CRB

After the controller initialization routine has completed, SYSGEN calls the
driver's unit initialization routine at IPL 31, and passes it the following
values in the listed general registers:
•

R3 pointing to the system virtual address of the device's node space

•

R5 pointing to the UCB

Hardware initialization might include such activities as writing values
to BIIC and device-specific registers, examining the results of the BIIC
self-test, mapping a node's window space, building data structures to
control the device, and linking these structures into chains of similar data
structures.

16-12

Generic VAXBI Device Support
16.5 Initialization Performed by the VAXBI Device Driver

This section provides some ideas and guidelines for code that may be
necessary in an initialization routine. There is no requirement that driver
code perform all of the functions discussed here. The needs of various
devices differ, and some devices make more demands on driver software
than others.
Code examples in the section assume that R4 initially contains the virtual
address of the base of the device's node space and RS contains the virtual
address of the device's CRB.

16.5.1

Examining BllC Self-Test Status
According to the hardware specification for all devices attached to a VAXBI
bus, a VAXBI node undergoes a self-test on power failure recovery and
at system boot time. The BIIC indicates the successful completion of
the self-test by setting BIIC$V_STS and by clearing BIIC$V_BROKE in
BIIC$L_BICSR.
A driver unit initialization routine should test these bits before performing
any transaction on the VAXBI bus. If BIIC$V_STS is clear, then self-test
is still under way. If BIIC$V_BROKE is set, then the driver action is
implementation-specific. In any event, a driver should not set UCB$V_
ONLINE in UCB$L_STS if the node is not usable.
The maximum duration of the BIIC self-test is 10 seconds. If a VAXBI
node implements the maximum self-test time, then the driver unit
initialization routine may have to spin wait for the setting of BIIC$V_
STS (for instance, by embedding the testing instructions in an invocation
of the TIMEDWAIT macro). Driver unit initialization routines should
perform this spin wait only when UCB$V_POWER in UCB$L_STS is set.
Otherwise, the driver is being loaded by SYSGEN, and a long spin wait at
high IPL will have adverse effects on the rest of the VMS system.
Normally, only diagnostics initiate a self-test by setting the SST bit in
the BIIC. A VAXBI driver that sets this bit must take special precautions
to avoid a machine check and to avoid undetected corruption of VAXBI
memory. These precautions include the following steps:
1

Use the $PRTCTINI macro to begin a machine check protection block,
supplying the location of the end of the block in the label argument
and the mask value #<MCHK$M_NEXM!MCHK$M_LOG> in the
mask argument. (Note that you must include an invocation of the
$MCHKDEF macro in the driver to use these symbols.) Code within
the block executes at IPL 31.

Invoke the BI_NODE_RESET macro as follows:
BI - NODE- RESET

CSR=R4

The Bl_NODE_RESET macro uses the recommended instruction
sequence to disable arbitration on the VAXBI node to be reset, and
sets the node reset and self-test status bits in BIIC$L_BICSR. The use
of any instruction sequence other than that defined by the BI_NODE_
RESET macro to perform these actions may cause an undefined
condition on the VAXBI bus.
16-13

Generic VAXBI Device Support
16.5 Initialization Performed by the VAXBI Device Driver

Use the $PRTCTEND macro to end the machine check protection
block. You must specify in the label argument the same value you
specified in the label argument to the $PRTCTINI macro.

Do not access the BIIC registers for at least 1 millisecond. You may
not even check the state of the STS bit during this interval.

Do not access any other address on the VAXBI node until the self-test
has completed.

Normally, only diagnostics initiate a self-test by setting the SST bit in
the BIIC. A VAXBI driver that sets this bit must take special precautions
to avoid a machine check and to avoid undetected corruption of VAXBI
memory. These precautions include the following steps:

16.5.2

Disable arbitration on the VAXBI node being reset by setting BIIC$V_
ARBCNTRL in BIIC$L_BICSR.

Set BIIC$V_SST and BIIC$V_STS simultaneously to initiate the selftest. Do not set BIIC$V_SST in the same instruction that disables
arbitration.

Use the $PRTCTEND macro to end the machine check protection
block. You must specify in the label argument the same value you
specified in the label argument to the $PRTCTINI macro.

Do not access the BIIC registers for at least 1 millisecond. You cannot
even check the state of the STS bit during this interval.

Do not access any other address on the VAXBI node until the self-test
has completed.

Clearing BllC Errors, Setting Interrupts, and Enabling Interrupts
There is a set of tasks that a VAXBI driver should perform during
initialization that ensures that interrupts are properly enabled and
delivered to an appropriate VAXBI target node. These tasks include
the following:

16-14

•

Clearing any outstanding set bits in the Bus Error Register.

•

Setting the target node for interrupts in the Interrupt Destination
Register.

•

Setting the device interrupt vector in the Error Interrupt Control
Register.

•

Setting the device interrupt vector in the User Interface Interrupt
Control Register.

•

Enabling hard and soft error interrupts as required by the device.
Typically hard errors are enabled and soft errors are disabled.

Generic VAXBI Device Support
16.5 Initialization Performed by the VAXBI Device Driver

•

Enabling interrupts upon certain types of transactions to user interface
CSR space.

It is important that the interrupt vectors and destination be set up before
BIIC hard error and soft error interrupts are enabled. An error occurring
while error interrupts are enabled but the vector is not initialized could
lead to an invalid condition.
16.5.2.1

Clearing the Bus Error Register

The following example clears all set bits in the Bus Error Register
(BIIC$L_BER) to prevent spurious or pending error interrupts at
initialization.
MOVL

16.5.2.2

BIIC$L BER(R4),BIIC$L=BER (R4)

;Clear all set write-1-to-clear
;bits in BIIC$L_BER

Loading the Interrupt Destination Register

The Interrupt Destination Register (BIIC$L_IDR) specifies which VAXBI
node should become the destination of interrupts from this node. In VAX
82x0/83x0 systems, the VAX.BI node of the primary CPU becomes the
destination for interrupts. In VAX 85x0/8700/88x0, VAX 6000-series, and
VAX 9000-series systems, the VAXBI node of the NBIB, PBIB, or DWMBA
/Bon the particular VAXBI on which this device resides becomes the
destination for such interrupts.
The VMS system initialization procedure described in Section 16.4 creates
a 32-bit mask with the appropriate bit set and stores it in ADP$L_Bl_IDR.
If a driver must set the Interrupt Destination Register, it can simply move
this value to the BIIC register:
MOVL
MOVL

16.5.2.3

CRB$L INTD+VEC$L ADP(R8),R0
ADP$L-BI IDR(RO)~BIIC$L_IDR (R4)

;Get ADP address
;Write to IDR

Setting Interrupt Vectors

A VAXBI node uses the Error Interrupt Control Register (BIIC$L_EICR) to
determine the SCB vector through which to interrupt when a BIIC at this
node detects a bus error. The User Interface Interrupt Control Register
(BIIC$L_UICR) similarly controls the operation of interrupts initiated by
the device at this node. A driver can also use the Error Interrupt Control
Register to support a device that generates secondary interrupt vectors.
Because the VMS system initialization procedure described in Section 16.4
saves the offset of the node's first SCB vector from the start of its SCB
page in ADP$W_BI_VECTOR, a driver can initialize both of these registers
by using code similar to that in the following example:
MOVL
CRB$L INTD+VEC$L ADP(R8),RO
;Get ADP address
MOVZWL ADP$W-BI VECTOR(R0),R2
;Get device vector
MOVL
BIIC$L UICR(R4),BIIC$L UICR(R4)
;Clear user vector
MOVL
R2,BIIC$L UICR(R4)
;Set user vector
BISL
#l@<BIIC$V_LEVEL+BIIC$S_LEVEL-1>,R2
;OR in interrupt level
;BR7 in this case
MOVL
BIIC$L EICR(R4),BIIC$L EICR(R4) ;Clear error vector
MOVL
R2,BIIC$L_EICR(R4)
;Set error vector

16-15

Generic VAXBI Device Support
16.5 Initialization Performed by the VAXBI Device Driver

Note that the driver clears both vectors before it actually sets them.
Clearing BIIC$L_UICR and BIIC$L_EICR causes any pending interrupt
to be cleared. Also note that the interrupt level must be set in BIIC$L_
EICR, in this case BR7. If the level is not set, an interrupt will n.ever be
generated.
16.5.2.4

Enabling Error Interrupts
Finally, to enable interrupts that report errors detected by the node's BIIC,
the controller initialization routine can set the soft error interrupt-enable
or hard error interrupt-enable bits in the VAXBI Control and Status
Register. The BIIC sets bits in the Bus Error Register (BIIC$L_BER) to
reflect the type of bus error reported by the interrupt.
BISL

16.5.2.5

#<BIIC$M SEIE!BIIC$M HEIE>,- ;Soft error interrupt enable
BIIC$L_BICSR(R4);Hard error interrupt enable

Enabling BllC Options
Device registers are in the area of node space called user interface CSR
space, and are located following the 256 bytes reserved for the BIICrequired registers. Use of user interface CSR space is implementationdependent.

For the processor to be alerted to various transactions directed at user
interface CSR space, the controller initialization routine of devices that
support such transactions should set appropriate bits in the BCI Control
and Status Register (BIIC$L_BCICR). See Table 16-1 for definitions of
these bits.
The following example enables a node to alert the node specified as the
interrupt destination (in BIIC$L_IDR) when a retry timeout, STOP
command, or read or write transaction is directed at its user interface
CSR space.
BISL

16.5.3

#<BIIC$M STOPEN!BIIC$M-RTOEVEN!BIIC$M-UCSREN>,BIIC$L=BCICR(R4)

;Stop enable
;Retry timeout enable
;User CSR enable

Mapping Window Space
Each VAXBI, starting at address 2040000016 in its I/O address space,
provides 16 address blocks of 256K bytes apiece, called window space.
VAXBI nodes can use window space if it is necessary to map VAXBI
transactions to memory space on a target bus, although only such nodes as
the DWBUA or DWMUA adapter currently use this feature.
Whereas the VMS initialization routine maps each VAXBI node's node
space to virtual addresses, it does not automatically map each node's
window space. If a device needs to use its window space, it is up to the
driver's unit initialization routine to map this space.
First of all, the driver must determine the starting physical address of
the node's window space. Figure 16-3 illustrates how VAXBI addresses
are constructed. Drivers can use the following VMS-supplied macros (in
SYS$LIBRARY:LIB.MLB) to access pertinent VAXBI addresses and values:
16-16

Generic VAXBI Device Support
16.5 Initialization Performed by the VAXBI Device Driver
$108SSDEF (for VAX 82x0/83x0 systems)
$108NNDEF (for VAX 8530/8550/8700/8800 systems)
$108NNDEF and $I08PSDEF (for VAX 8810/8820/8830 systems)
$109CCDEF (for VAX 6000-2xx/6000-3xx series systems)
$109RRDEF (for VAX 6000-4xx series system)
$109AQDEF (for VAX 9000-series system)
A driver calculates the starting address of a node's window space by first
determining the offset to the start of the VAXBI node's window space from
the beginning of its VAXBI 1/0 space. To do so, it performs the following
tasks:
1

Extracts the VAXBI node ID from bits <3:0> of ADP$W_TR.

Multiplies the VAXBI node ID with the size of window space. The
driver obtains this value from the following symbols:

Symbol

System

108$S$AL_NDSPER

VAX 82x0/83x0

108NN$AL_NDSPER

VAX 85x0/8700/88x0

109CC$C_BIWSIZ

VAX 6000-2xx/6000-3xx series

109RR$C_BIWSIZ

VAX 6000-4xx series

109AQ$C_BIWSIZ

VAX 9000-series

Adds the address of the window space ofVAXBI node 0 to this value.
The driver obtains this value from the following symbols:
Symbol

System

108SS$AL_NODESP

VAX 82x0/83x0

108NN$AL_NODESP

VAX 85x0/8700/88x0

109CC$C_BIWINDOW

VAX 6000-2xx/6000-3xx series

109RR$C_BIWINDOW

VAX 6000-4xx series

109AQ$C_BIWINDOW

VAX 9000 series

The driver for a device on a VAX system configured with more than one
VAXBI bus (for instance, the VAX 85x0/8700/88x0, VAX 6000 series, or
VAX 9000 series systems) must proceed to calculate the start of the 1/0
address space of the VAXBI bus to which the device is attached. It adds
the result of the following steps to the value it has obtained in the prior
steps:
1

Determine the offset to the 1/0 address space of the VAXBI bus to
which the node is attached.
For VAX 6000-series systems, a driver first must obtain the XMI node
ID of the DWMBA to which the VAXBI is connected. It determines
the address of the DWMBA's ADP at offset ADP$L_BIMASTER of
the node's ADP. It then finds the XMI node of the DWMBA at offset
ADP$W_XBIA_TR of the ADP.

16-17

Generic VAXBI Device Support
16.5 Initialization Performed by the VAXBI Device Driver

For VAX 85x0/8700/88x0 configurations, a driver obtains the VAXBI
bus number from bits <7:4> from offset ADP$W_TR of the node's ADP.
For VAX 9000 systems, a driver obtains the relative VAXBI number
from ADP$B_REL_BI.
2

Multiply this value by 200000016, the amount of physical address
space allocated for each VAXBI bus.

Add to this value the base of 1/0 address space. The driver obtains
this value from the following symbols:
Symbol

System

108SS$AL_IOBASE

VAX 82x0/83x0

108NN$AL_IOBASE

VAX 85x0/8700/88x0

109CC$AL_IOBASE

VAX 6000-2xx/6000-3xx series

109RR$AL_IOBASE

VAX 6000-4xx series

109AQ$AL_XBIO_WINDSP_30

VAX 9000 series

After performing these calculations, the driver must associate each page
of window space to be used with a system page-table entry (SPTE) that
maps the page-frame number (PFN) of the physical page in window space
to a system virtual address. VMS includes the routine LDR$ALLOC_PT,
described in the VMS Device Support Reference Manual, that allocates
system page-table entries (SPTEs) for a specified number of pages.
Because LDR$ALLOC_PT executes at IPL$_SYNCH (holding the MMG
spin lock in a VMS multiprocessing system), the controller initialization
routine must fork from IPL$_POWER to fork IPL (using the CRB fork
block) prior to calling it. See Section 11.1.5 for a discussion of forking in a
driver initialization routine.
Finally, once the SPTEs have been allocated, the driver moves the PFN s
of the window space pages into the SPTEs, sets their valid bits, and
initializes them in a device-specific manner.

16.6

OMA Transfers
The method by which a device accomplishes direct-memory-access (DMA)
transfers depends upon the characteristics of the device. As part of a
VAXBI read or write transaction, such a device must place on the VAXBI
bus a physical address, the target of which is a memory node or a node
(such as an NBIB adapter) that transmits the request to memory across
another bus.
For the DMA device to successfully access the memory pages of a buffer
involved in an 1/0 transfer, it must be given sufficient information as to
the size and location of these buffer pages, the type of transaction that
is requested, an offset into the first page of the buffer, and the length
of the transaction. In addition, if the size of the transaction causes it
to exceed the boundaries of a page, the device must have some means
of accessing the remaining pages-even if they are, as is most likely,
scattered throughout physical memory.
16-18

Generic VAXBI Device Support
16.6 OMA Transfers

As a result, devices make use of several types of structures, the purpose of
which is to help generate a succession of contiguous physical addresses on
the VAXBI bus, that map to the various pages of the buffer involved in the
transfer. Some possible strategies of this sort include the following:
•

A physically contiguous buffer in memory

•

System page tables in system memory

•

Process page tables locked in system memory

•

Map registers in the device's VAXBI 110 address space

A separate but related issue results from the fact that the original buffer,
as specified in the user $QIO request, is in process space and is mapped
by process page-table entries. Because the driver cannot rely on process
context existing at the time the device is ready to service the 110 request,
it must have some means of guaranteeing that it can access both the data
involved in the transfer and the page-table entries that map the buffer.
VMS supplies two separate techniques, applied by traditional VMS drivers
and described in Section 6.3.1.

•

Direct 110, the technique used most commonly by DMA drivers, locks
the user buffer in memory as well as the page-table entries that map
it. Such a driver calls a VMS-supplied FDT routine that prepares the
user buffer for direct 110.

•

Buffered 1/0 is the strategy whereby the driver FDT routine allocates
a buffer from nonpaged pool. It is this intermediate buffer that is
involved in the DMA transfer. The FDT routine copies the data
from the user buffer to the system buffer for a write request; I/O
postprocessing routines deliver data from the system buffer to the user
buffer for a read request.

That DMA drivers may make use of either VMS direct 110 or buffered 110
is one way by which these drivers can supply specific information needed
by the device to accomplish a DMA transfer. Those driver FDT routines
that call a VMS direct-I/0 FDT routine provide the following information
in the device's unit control block (UCB):
UCB$L_SVAPTE

Virtual address of the system page-table entry (SPTE) for
the first page used in the transfer

UCB$W_BOFF

Byte offset in the first page of the transfer buffer

UCB$W_BCNT

Size in bytes of the transfer

FDT routines for buffered 1/0 call EXE$ALLOCBUF, EXE$DEBIT_
BYTCNT_ALO, or EXE$DEBIT_BYTCNT_BYTLM_ALO to obtain a
nonpaged pool buffer (debiting a job's byte count quota in the last
two routines) and initialize the same UCB fields with the following
information:
UCB$L_SVAPTE

Virtual address of system buffer used in the 1/0 transfer

UCB$W_BOFF

Number of bytes to be charged to process for transfer

UCB$W_BCNT

Size in bytes of the transfer

16-19

Generic VAXBI Device Support
16.6 OMA Transfers

If a driver's fork process must manipulate the data in any way at fork
level (that is, outside of the driver's FDT routines), then it needs a virtual
address it can use to access the data. Such a requirement could cause the
driver writer to consider structuring the driver so that it uses buffered I/O.
For short transfers, this need also could be accommodated by the driver's
loading an SPTE with the correct PFN and computing the associated
system virtual address. The drivers for the disks that have ECC correction
applied by the host do this when there is ~n ECC error detected. The
controller can tell the driver that the error in the data in memory can
be corrected by applying some pattern to a part of the data, but the fork
process has to perform the correction, not the controller.
MOVL
SUBW3
BICW3
EXTZV
MOVL
MOVAL

16.6.1

IRP$L SVAPTE(R3),R2
#12,8(R2),UCB$W_BCNT(R5)

;Get address of system buffer
;Calculate system buffer
; length
#CA<VA$M BYTE>, (R2),UCB$W BOFF ;Put offset in buffer
#VA$V_VPN,#VA$S_VPN(R2),R2
;Get system virtual page
; number
GAMMG$GL_SPTBASE,Rl
;Get address of system page
; table
(Rl) [R2],UCB$L_SVAPTE(R5)
;Get system virtual address
; of page

Example: DMB32 Asynchronous/Synchronous Multiplexer
The DMB32 asynchronous/synchronous multiplexer can use any of four
different modes of address translation for DMA accesses. Under each of
these modes, the DMB32 requires that its driver supply an address by
which it can either directly or indirectly obtain the pages of the buffer that
is involved in the transfer. The four different translation modes require
such addresses in one of the following forms:
1

System virtual address of a buffer

System virtual address of a page-table entry

Physical address of a page table

Address of a physically-contiguous buffer

System Virtual Address of a Buffer and a Page-Table Entry

The DMB32 can itself perform the first two types of address translation
because it can read entries in the VMS system page table (see the
VAX/VMS Internals and Data Structures manual for a description of
page-table entries). The controller initialization routine of a DMB32
device driver supplies the physical address and length of the VMS system
page table, plus the virtual address and length of the VMS global page
table. It also sets a page-table-valid bit in a device maintenance register.
As a result, a driver for a DMB32 device could use either direct I/O or
buffered I/O, and accordingly load a device register with the system virtual
address of the page-table entry that maps the buffer or the system virtual
address of the buffer itself. After the driver has loaded other device
registers with a buffer offset value and a transfer size-and set the "start"
bit in a DMB32 line-control register-the DMB32 performs the transfer
without any additional mapping or other driver intervention.

16-20

Generic VAXBI Device Support
16.6 OMA Transfers

Physical Address of a Page Table

In this mode, the DMB32 can be given the physical address of a page table
that maps the I/O transfer. The DMB32 architecture mandates that each
page-table entry be four bytes long and that the page table be aligned
on a longword boundary. Also, each page is 512 bytes long. However,
the page tabl~ can be anywhere in memory, possibly at a range of VAXBI
I/0-space addresses belonging to the node to which the DMB32 adapter
is attached. To perform a DMA transfer under this addressing mode, the
DMB32 adapter requires the offset of the first byte of the buffer that is in
the page described by the page-table entry. Each page-table entry contains
bits <29:9> of the physical address of the page that is to be accessed.
In this case, the driver must extract the PFNs of the pages involved in the
transfer and insert them into the page table of the device. The following
is an example of a routine that translates a system virtual address to a
physical address. It returns the physical address at the top of the stack.
VIRT TO PHYAD:
PUSHL (SP)
PUSHR
BICL3
EXTZV
MOVL
MOVL
EXTZV
ASHL
BISL3
POPR
RSB

#AM<R0,Rl,R2,R3>
#-512,Rl,RO
#VA$V VPN,#VA$S VPN,Rl,R2
GAMMG$GL SPTBASE,R3
(R3) [R2],R3
#PTE$V_PFN,#PTE$S PFN,R3,R3
#VA$V_VPN,R3,R3
RO,R3,20(SP)
#AM<R0,Rl,R2,R3>

;Create slot at top of stack
;for return value
;Save registers
;RO = byte offset of address
;Extract VPN
; and put it in R2
;R3 => system page table
;R3 => PTE
;Get page frame number of
; buff er page into R3
;Shift into place for
; physical address
;Put result into stack slot
;Restore registers
;Return to caller

Physical Address of a Buffe·r
If the device can neither read system page tables nor has its own scatter-

gather map-and must perform a DMA transfer that spans physical
pages-it must rely upon the actual contiguity of the physical pages
involved in the transfer. Because there is no guarantee that this is
the state of the user's buffer, the driver must allocate an intermediate
buffer consisting of contiguous physical pages. The driver never
deallocates this buffer unless the driver is being unloaded by means of
SYSGEN's RELOAD command. (The driver unloading routine can call
COM$DRVDEALMEM to do so.) The best time to allocate such a buffer
is during the device's initialization, when memory is most likely to be
contiguous.
The VMS routine EXE$ALOPHYCNTG, described in the VMS Device
Support Reference Manual, allocates such a buffer. The size of the buffer
that should be allocated depends on the device's characteristics and the
size of the transfers requested on the device. A buffer of four pages is
likely to be large enough for most disk transfers, for example; but if you
have enough memory on your system, you might want to make your buffer
the size of a disk track in order to reduce disk latency. In any event, large
transfers to the device can be segmented into transfers the size of your
intermediate buffer.
16-21

Generic VAXBI Device Support
16.6 OMA Transfers

The start-I/0 routine of such a driver copies the data from the user's buffer
into the intermediate, physically contiguous buffer by means of the routine
IOC$MOVFRUSER.
The driver then sets up the device for the DMA transfer:
1

Determines the physical address of the buffer from the system virtual
address returned by EXE$ALOPHYCNTG

Moves the address to the device address register

Activates the device

If the transfer size exceeds the size of the buffer, returns to step 1

When a user requests a transfer from such a device, the driver moves the
data from the device to the intermediate, physically contiguous buffer by
means of a DMA transfer, then calls IOC$MOVTOUSER to copy the data
into the user's buffer.

16.7

Unit Initialization Routine
A generic VAXBI device driver may include a unit initialization routine,
in addition to its controller initialization routine, if it services a multiunit
device.
SYSGEN attempts to create a UCB and call the unit initialization routine
for the number of units specified in the maxunits argument to the DPTAB
macro.
When called in the process of driver loading, the unit initialization routine
of a generic VAXBI device driver must therefore determine if the unit it is
currently servicing actually exists. Prior to returning control to SYSGEN,
the routine must place in RO a success status (low bit set) if the unit exists
or a failure status (low bit clear) if it does not. If SYSGEN receives failure
status, it deallocates the UCB for the unit and proceeds to configure the
next unit in a similar manner.

16.8

Register Dumping Routine
In the event of a device error or a VAXBI bus error, a driver's register
dumping routine should contain code that makes certain interesting
registers available for error logging. Apart from any device registers that
should be saved, the following BIIC registers may contain information
important in determining the cause of the error: the Device Register
(BIIC$L_DTREG), the VAXBI Control and Status Register (BIIC$L_
BICSR), the Bus Error Register (BIIC$L_BER), the Error Interrupt
Control Register (BIIC$L_EICR), and the Interrupt Destination Register
(BIIC$L_IDR).

16-22

Generic VAXBI Device Support
16.8 Register Dumping Routine

The following is an example of part of a register dumping routine that
saves the contents of these BIIC registers in an error buffer.
MOVL
MOVL
MOVL
MOVL
MOVL

16.9

BIIC$L_DTREG(R4), (RO)+
BIIC$L_BICSR(R4), (RO)+
BIIC$L_BER(R4), (RO)+
BIIC$L_EICR(R4), (RO)+
BIIC$L_IDR(R4), (RO)+

;Device Type Register
. ;BIIC CSR Register
;Bus Error Register
;Error Interrupt Control Register
;Interrupt Destination Register

Loading a VAXBI Device Driver
The System Generation Utility (SYSGEN) loads the device driver into
system virtual memory, creates additional data structures for the device
unit, connects the device's interrupt vectors, and calls the device driver's
controller initialization routine and unit initialization routine.
Chapter 12 discusses the loading of a device driver and the SYSGEN
commands commonly used during driver loading.

16.10

BllC Register Definitions
Each VAXBI node is required to implement a minimum set of registers
contained in specific locations within the node's node space. VMS
automatically maps each node's node space at boot time and provides
the macro $BIICDEF (in SYS$LIBRARY:LIB.MLB) to define offsets to the
BIIC registers and their significant bit fields.
The contents of the BIIC registers are illustrated in Figure 16-6 and
described in Table 16-1. See the VAXBI Options Handbook for a discussion
of the BIIC and the rules for configuring its registers.
Note: Fields marked "Reserved to Digital" are reserved for Digital's
future use and should contain zeros.
Figure 16-6 Backplane Interconnect Interface Chip (BllC) Registers

BllC$L_DTREG

BllC$L_BICSR

BllC$L_BER

BllC$L_EICR

BllC$L_IDR

BllC$L_IPIMR

BllC$L_IPIDR

BllC$L_IPISR

28
(continued on next page)

16-23

Generic VAXBI Device Support
16.10 BllC Register Definitions

Figure 16-6 (Cont.)

Backplane Interconnect Interface Chip (BllC) Registers

::~

Table 16-1

BllC$L_SAR

BllC$L_EAR

BllC$L_BCICR

BllC$L_WSR

BllC$L_IPISTPF

Unused

BllC$L_UICR

Unused (172 bytes)

::~ 68

BllC$L_GPRO

240

BllC$L_GPR1

244

BllC$L_GPR2

248

BllC$L_GPR3

252

Contents of the BllC Registers

Field Name

Contents

BllC$L_DTREG

Device Register that contains the following two words:
BllC$W_DEVTYPE
Device type. This field is written by device hardware and
self-test microcode. It contains two bit fields:
BllC$V_MEMNODE (bits <14:8>), when clear, indicates a
memory node.
BllC$V_NONDEC (bit 15), when clear, indicates a Digitalsupplied device; it should be 1 otherwise.
BllC$W_REVCODE

Revision code.
(continued on next page)

16-24

Generic VAXBI Device Support
16.10 BllC Register Definitions

Table 16-1 (Cont.)

Contents of the BllC Registers

Field Name

Contents

BllC$L_BICSR

VAXBI Control and Status Register.
The following fields are defined within BllC$L_BICSR.
BllC$V_NODE_ID 1
Node ID. This field is automatically loaded during the
powerup sequence. Reserved to Digital.
Bl IC$V_ARBCNTL

Arbitration mode used by the node. Currently, all arbitration
modes except dual round-robin arbitration are reserved to
Digital. Correspondingly, these two bits should be clear.
When these two bits are set, arbitration is disabled, thus
preventing a node from starting a VAXBI transaction.

BllC$V_SEIE

Soft error interrupt enable. When set, this bit allows the node
to generate an interrupt when the soft error summary bit
(BllC$V_SES) in this register is set.

BllC$V_HEIE

Hard error interrupt enable. When set, this bit allows the
node to generate an interrupt when the hard error summary
bit (BllC$V_HES) in this register is set.

BllC$V_UWP

Unlock write pending. When set, this bit signals that the
master port interface at this node has successfully completed
an IRCI (Interlock Read with Cache Intent) transaction.
The node clears this bit when it successfully completes a
corresponding UWMCI (Unlock Write Mask with Cache Intent)
instruction.

<9>

Reserved to Digital. Must be zero.

BllC$V_SST

Node reset. This bit is normally used by diagnostics to initiate
the BllC internal self-test. Prior to initiating a BllC self-test, a
node should disable arbitration by setting both bits in BllC$V_
ARBCNTL. When BllC$V_SST is set, the self-test status bit
(BllC$V_STS) ih this register must also be set.
Reads to BllC$V_SST return a zero.

BllC$V_STS

Self-test status. When set, this bit indicates that the BllC has
passed its self-test. The controller initialization routine of a
VAXBI device driver should inspect this bit and the BllC$V_
BROKE bit before proceeding with any VAXBI transactions.
During the self-test sequence, BllC$V_STS will automatically
be reset by the BllC to allow the proper recording of the new
self-test results at the end of self-test.

BllC$V_BROKE 2

Broke bit. When cleared by the device's self-test, this
bit indicates that the device has passed its self-test. The
controller initialization routine of a VAXBI device driver should
inspect this bit and the BllC$V_STS bit before proceeding
with any VAXBI transactions.

BllC$V_INIT2

Initialization bit.

1 Read-only field.
2

Write-one-to-clear bit. Write-type transactions cannot set this bit.
(continued on next page)

16-25

Generic VAXBI Device Support
16.10 BllC Register Definitions

Table 16-1 (Cont.) Contents of the BllC Registers
Field Name

BllC$L_BER

Contents
BllC$V_SES 1

Soft error summary. When set, this bit indicates that one or
more of the soft error bits in the Bus Error Register (BllC$L_
BER) is set.

BllC$V_HES 1

Hard error summary. When set, indicates that one or more of
the hard error bits in the Bus Error Register (BllC$L_BER) is
set.

BllC$V_BllCTYPE 1

BllC type. These bits <23:16> always contain 00000001.

BllC$V_BllCREVN 1

BllC revision number.

Bus Error Register.
The following bits are defined within BllC$L_BER. Bits <30:16> are hard error bits and
bits <2:0> are soft error bits.
BllC$V_NPE 2
Null bus parity error.
BllC$V_CRD 2

Corrected read data.

BllC$V_IPE2

ID parity error.

BllC$V_UPEN
<14:4>

User parity enabled.
Reserved to Digital. Must be zero.

BllC$V_ICE2

Illegal confirmation error.
2

Nonexistent address.

Bus timeout.

Stall timeout.

BllC$V_RT02

Retry timeout.

BllC$V_NEX
BllC$V_BT0

BllC$V_ST0

Read data substitute.

Slave parity error.

Command parity error.

BllC$V_RDS
BllC$V_SPE

BllC$V_CPE
BllC$V_IVE2

IDENT vector error.

BllC$V_TDF

Transmitter during fault.

Interlock sequence error.

BllC$V_ISE

BllC$V_MPE2

Master parity error.

BllC$V_CTE2
BllC$V_MTCE
BllC$V_NMR
<31>

Control transmit error.
2

Master transmit check error.
NO ACK to multiresponder command received.
Reserved to Digital. Must be zero.

1 Read-only field.

2 Write-one-to-clear bit.

Write-type transactions cannot set this bit.
(continued on next page)

16-26

Generic VAXBI Device Support
16.10 BllC Register Definitions

Table 16-1 (Cont.)

Contents of the BllC Registers

Field Name

Contents

BllC$L_EICR

Error Interrupt Control Register. This register supplies information the node uses to
request and monitor the status of both BllC-detected and forced-error interrupts: that is,
those interrupts signaled by either the setting of a bit in the Bus Error Register (BllC$L_
BER) or the setting of the force bit (BllC$V_EIFORCE) in this register, respectively.
The node can initiate BllC-detected error-interrupt requests only if the appropriate errorinterrupt enables (BllC$V_SEIE and/or BllC$V_HEIE) are set in the VAXBI Control and
Status Register (BllC$L_BICSR).
The following fields are defined within BllC$L_EICR.
<1 :0>1
Reserved to Digital. Must be zero.
BllC$V_EIVECTOR
<15:14>

12-bit vector used in error interrupt sequences.
Reserved to Digital. Must be zero.

BllC$V_LEVEL

These four bits (<19:16>) correspond to the four interrupt
levels (INT<7:4>) of the VAXBI bus. A set bit causes the
corresponding level to be used when INTR commands under
control of this register are transmitted.

BllC$V_EIFORCE

Force bit. When set, this bit posts an error interrupt request
in the same way as a bit set in the Bus Error Register
(BllC$L_BER), except that the request is not qualified by the
bits BllC$V_HEIE and BllC$V_SEIE in BllC$L_BICSR.

BllC$V_EISENT2

INTR sent.

<22>

Reserved to Digital. Must be zero.

BllC$V_EllNTC2

INTR complete. When set, this bit indicates that the vector
for an error interrupt has been successfully transmitted or an
INTR command sent under the control of this register has
been successfully aborted.

BllC$V_EllNTAB 2

INTR abort. When set, this bit indicates that an INTR
command under the control of this register has been aborted
(that is, a NO ACK or illegal confirmation code has been
received). This bit is a status bit set by the BllC and can be
reset only by the user interface.
Reserved to Digital. Must be zero.

BllC$L_IDR

Interrupt Destination Register. The low-order word of this register indicates which nodes
are to be selected by INTR commands.

BllC$L_IPIMR

Interprocessor Interrupt Mask Register. The high-order word of this register indicates
which nodes are permitted to send interprocessor interrupts to this node.

BllC$L_IPIDR

Force-bit IPINTR/STOP Destination Register. The low-order word of this register indicates
which nodes are to be targeted by force-bit IPINTR or STOP commands sent by this
node.

BllC$L_IPISR 2

IPINTR Source Register. The BllC stores in the high-order word of this register the
decoded ID of a node that sends an IPINTR command to this node.

1 Read-only field.

Write-one-to-clear bit. Write-type transactions cannot set this bit.
(continued on next page)

16-27

Generic VAXBI Device Support
16.10 BllC Register Definitions

Table 16-1 (Cont.)

Contents of the BllC Registers

Field Name

Contents

BllC$L_SAR

Starting Address Register. The Starting Address Register and Ending Address Register
define storage blocks in either memory or 1/0 space. They must not be configured to
include node space or multicast space.
The low-order 18 bits of this register must be zero. This means that memories are
multiples of 256K bytes. Software should set up the Starting Address Register before the
Ending Address Register.

BllC$L_EAR

Ending Address Register.
The low-order 18 bits of this register must be zero. This means that memories are
multiples of 256K bytes. Software should set up the Starting Address Register before the
Ending Address Register. See the description of the Starting Address Register {BllC$L_
SAR) for further details ..

BllC$L_BCICR

BCI Control Register.
The following fields are defined within BllC$L_BCICR.
<2:0> 1

Reserved to Digital. Must be zero.

BllC$V_RTOEVEN

RTO EV enable.

BllC$V_PNXTEN

Pipeline NXT enable.

BllC$V_IPINTREN

IPINTR enable.

BllC$V_INTREN

INTR enable.

BllC$V_BICSREN

BllC CSR Space enable.

BllC$V_UCSREN

User Interface CSR Space enable.

BllC$V_WINVALEN

WRITE Invalidate enable.

BllC$V_INVALEN

INVAL enable.

BllC$V_IDENT

IDENT enable.

BllC$V_RESEN

RESERVED enable.

BllC$V_STOPEN

STOP enable.

BllC$V_BDCSTEN

BDCST enable.

BllC$V_MSEN

Multicast Space enable.

BllC$V_IPINTRF

IPINTR/STOP force.

BllC$V_BURSTEN

Burst enable.

<31:18>
BllC$L_WSR

Re~erved to Digital. Must be zero.

Write Status Register.
The following fields are defined within BllC$L_WSR.
<27:0>

BllC$V_GPR0

Reserved to Digital. Must be zero.
2

Indicates that a VAXBI transaction has written to General
Purpose Register 0 {BllC$L_GPRO).

1 Read-only field.
2

Write-one-to-clear bit. Write-type transactions cannot set this bit.
(continued on next page}

16-28

Generic VAXBI Device Support
16.10 BllC Register Definitions

Table 16-1 (Cont.)

Contents of the BllC Registers

Field Name

Contents

BllC$L_IPISTPF

BllC$V_GPR1 2

Indicates that a VAXBI transaction has written to General
Purpose Register 1 (BllC$L_GPR1 ).

BllC$V_GPR2 2

Indicates that a VAXBI transaction has written to General
Purpose Register 2 (BllC$L_GPR2).

BllC$V_GPR32

Indicates that a VAXBI transaction has written to General
Purpose Register 3 (BllC$L_GPR3).

Force-Bit IPINTR/STOP Command Register.
The following fields are defined within BllC$L_IPISTPF.
<10:0> 1
Reserved to Digital. Must be zero.
BllC$V_MIDEN

Master ID Enable.

BllC$V_CMD

These four bits indicate the command code for either an
IPINTR or STOP transaction that is initiated by setting the
IPINTR/STOP force bit (BllC$V_INTRF in BllC$L_BCICR).
Reserved to Digital. Must be zero.

BllC$L_UICR

User Interface Interrupt Control Register. This register controls the operation of interrupts
initiated by the device.
The following fields are defined within BllC$L_UICR.
<1 :0> 1
Reserved to Digital. Must be zero.
BllC$V_UIVECTOR

These 12 bits contain the vector used during user interface
interrupt sequences (unless the external vector bit (BllC$V_
EXVECTOR in BllC$L_UICR) is set). The vector is
transmitted when this node wins an IDENT arbitration that
matches the conditions given in BllC$L_UICR.

<14>

Reserved to Digital. Must be zero.

BllC$V_EXVECTOR

When set, the BllC solicits the interrupt vector from the node
rather than transmitting the vector contained in BllC$L_UICR.

BllC$V_UIFORCE

These four bits correspond to the four interrupt levels
(INT<7:4>). When a bit is set, the BllC generates an interrupt
at the indicated level.

BllC$V_U ISENT2

These four bits correspond to the four interrupt levels
(INT<7:4>). A set bit indicates that an INTR command
for the corresponding level has been successfully transmitted.

BllC$V_UllNTC 2

These four bits correspond to the four interrupt levels
(INT<7:4>). A set bit indicates that the vector for an interrupt
at the corresponding level has been successfully transmitted
or that an INTR command sent under the control of this
register has been successfully aborted.

1 Read-only field.

2 Write-one-to-clear bit.

Write-type transactions cannot set this bit.
(continued on next page)

16-29

Generic VAXBI Device Support
16.10 BllC Register Definitions

Table 16-1 (Cont.)

Contents of the BllC Registers

Field Name

Contents
BllC$V_UllNTAB 2

BllC$L_GPRO

These four bits correspond to the four interrupt levels
(INT<7:4>). A set bit indicates that an INTR command at the
corresponding level, sent under the control of this register,
has been aborted (that is, a NO ACK or illegal confirmation
code has been received).

General Purpose Register 0.

BllC$L_GPR1

General Purpose Register 1.

BllC$L_GPR2

General Purpose Register 2.

BllC$L_GPR3

General Purpose Register 3.

2 Write-one-to-clear bit.

16-30

Write-type transactions cannot set this bit.

17 SCSI Class Driver Support
The Small Computer System Interface (SCSI) provides a standard
bus by which small computers and intelligent peripheral devices may
be interconnected. The VMS operating system offers a native mode
implementation of the ANSI SCSI bus on its MicroVAXNAXstation
3100 and VAXstation 3520/3540 system configurations. Any non-Digitalsupplied device to be attached to the SCSI bus of a MicroVAXNAXstation
system must implement all mandatory features of the SCSI-2 standard as
described in the specification.
The VMS operating system defines a mechanism by which a system
programmer can write a class driver that, in conjunction with a standard
VMS SCSI port driver, exchanges data, commands, and status with a
third-party device on the SCSI bus. Given the particular requirements
of the device, or the expectations of application programs accessing the
device, the programmer may choose to create a SCSI class driver rather
than employ a VMS generic SCSI class driver dicussed in the VMS I I 0
User's Reference Manual: Part I.
By writing a device-specific SCSI class driver, a programmer can define
a unique, simple, robust $QIO interface to a SCSI device. The generic
SCSI class driver, by contrast, provides a more complex $QIO interface,
requiring the application program to have some knowledge of the data
transfer mode and capabilities of the target device and to construct in
memory the SCSI commands to be passed to the SCSI port. A third-party
SCSI class driver conceals these details from the application program.
Additionally, it can provide device-specific error recovery, full error logging,
and notification of asynchronous events from the device.

Note: A non-Digital-supplied SCSI disk device residing on the local node
and controlled by a SCSI third-party class driver cannot be served
to other nodes of the local area VAXcluster.
This chapter introduces the VMS SCSI class/port interface and discusses
the mechanisms VMS provides to facilitate the creation of a SCSI class
driver. It describes the capabilities and components of such a driver
and suggests some coding strategies. It also includes sections on driver
naming conventions, driver loading, and driver debugging techniques. It
concludes with descriptions of class driver error logging protocol and the
asynchronous event notification facility.

17.1

VAX Systems with SCSI Bus Concepts
Implementation of the SCSI bus architecture for the MicroVAX/VAXstation
3100 is shown in Figure 1-6 and for the VAXstation 3520/3540 in
Figure 1-7. Each SCSI bus in the system is identified by a SCSI port
ID (A or B). The SCSI port ID uniquely identifies a SCSI port: that is,
the SCSI controller channel that controls communications to and from a
specific SCSI bus on the system.
17-1

SCSI Class Driver Support
17.1 VAX Systems with SCSI Bus Concepts

Each SCSI bus supports seven devices and a processor, at SCSI IDs 0 to
7. As defined by the ANSI SCSI specification, a SCSI ID refers to a line
on the SCSI data bus (DB) on which the device uniquely asserts itself.
The VMS operating system uses the term SCSI device ID to represent
this value. Typically, a MicroVAX/VAXstation 3100 system processor is
assigned device ID 6 and asserts itself at DB(6); a VAXstation 3520/3540
system processor is assigned device ID 7 and asserts itself at DB(7).
According to the ANSI SCSI specification, a logical unit is a physical
or virtual device accessible by means of a SCSI device. For instance, if a
peripheral controller resides on the SCSI bus, it, in turn, can control up
to eight devices. A logical unit number (LUN), an integer from 0 to 7,
uniquely identifies the device with respect to the controller's SCSI device
ID.
Transactions on the SCSI bus are between an initiator and a target.
The initiator, usually the host processor, requests that another SCSI
device, the target, perform a certain operation. In situations in which
the host processor requires notification of some unexpected event on
the SCSI bus, the ANSI specification defines the asynchronous event
notification (AEN) protocol. AEN allows a SCSI device that is usually a
target to inform the processor that an event has occurred asynchronously
with respect to the processor's current stream of execution. (Certain
MicroVAX/VAXstation implementations make the AEN protocol available
to non-Digital-supplied SCSI class drivers, as described in Section 17.9.)
As Figures 1--6 and 1-7 illustrate, the MicroVAX/VAXstation 3100 and
VAXstation 3520/3540 port hardware cannot directly access data in main
memory. In order to access command, status, and data buffers involved in
an operation on the SCSI bus, the MicroVAX/VAXstation port hardware
must refer to its own direct-memory-access (DMA) buffer. Whenever the
port hardware requires access to buffered information, the standard VMS
port driver dynamically allocates a segment of the port DMA buffer and
maps to it the pages of the buffer in main memory in a system-dependent
manner.

17.2

SCSI Class/Port Architecture
VMS uses a class/port driver architecture to communicate with devices
on the SCSI bus. The class/port design allows the responsibilities for
communication between the operating system and the device to be cleanly
divided between two separate driver images (see Figure 17-1).

17-2

SCSI Class Driver Support
17.2 SCSI Class/Port Architecture

Figure 17-1

VMS SCSI Class/Port Interface

$010

,,
Class
Driver

Device-Level Operations
• Handles SCSI commands
• Handles SCSI status

---------------- ---------------Bus-Level Operations
• Handles SCSI phases and timing
• Handles SCSI messages
• Handles data movement

[

t
SCSI Port Interface

Port
Driver

Port Hardware
ZK-1366A-GE

The SCSI port driver transmits and receives SCSI commands and data.
It knows the details of transmitting data from the local processor's SCSI
port hardware across the SCSI bus. Although it understands SCSI bus
phases, protocol, and timing, the SCSI port driver has no knowledge of the
SCSI commands the device supports, the status messages it returns,
or the format of the packets in which this information is delivered.
Strictly speaking, the port driver is a communications path. When
directed by a SCSI class driver, the port driver forwards commands and
data from the class driver onto the SCSI bus to the device. On a single
MicroVAX/VAXstation system, a single SCSI port driver handles bus-level
communications for all SCSI class drivers that may. exist on the system
(see Figure 1 7-2).

17-3

SCSI Class Driver Support
17.2 SCSI Class/Port Architecture

Figure 17-2 VMS SCSI Port Driver Configuration
$010

$010

DKDRIVER

MKDRIVER

LKDRIVER

GKDRIVER

PKN DRIVER

SCSI
Disk
(Target)

SCSI

Tape
(Target)

Other
SCSI
(Target)

PKSDRIVER

Other
SCSI
(Target)

SCSI
T~

(Target)

SCSI
Disk
(Target)
ZK-1379A-GE

The SCSI class driver acts as an interface between the user and the
SCSI port, translating I/O functions as specified in a user's $QIO request
to a SCSI command directed to a device on the SCSI bus. Although
the class driver knows about SCSI command descriptor buffers, status
codes, and data, it has no knowledge of underlying bus protocols or
hardware, command transmission, bus phases, timing, or messages (except
in asynchronous event notification mode, as described in Section 17.9).
A single SCSI class driver can run with the SCSI port driver of any
MicroVAX/VAXstation system, controlling the same set of devices on each
system (see Figure 17-3).

17-4

SCSI Class Driver Support
17.2 SCSI Class/Port Architecture

Figure 17-3 VMS SCSI Class Driver Configuration

Tape Class Driver

Disk Class Driver

SCSI Port

Driver

Disk Class Driver

VAX3100
SCSI Port

VAX 3520
SCSI Port

Driver

Driver
ZK-1378A-GE

The design of the SCSI driver class/port interface allows a programmer
to write a class driver that is independent of any concern about the
underlying hardware. VMS supplies software tools that facilitate the
development of SCSI class drivers, including the following:

17.2.1

•

A standard interface that all SCSI class drivers use to request work
from and transfer control to the port driver. This interface is known as
the SCSI port interface (SPI).

•

SCSI-specific data structures that class and port drivers use to
exchange information and monitor the state of the device connection or
SCSI port.

•

A template SCSI class driver that can serve as the basis for a thirdparty SCSI class driver.

SCSI Port Interface
The SCSI port interface (SPI) consists of a group of routines within
the SCSI port driver that create and manage the connection between a
SCSI class driver and a device unit. Across this connection, SPI routines
exchange control information and data between the class driver and the
port.

17-5

SCSI Class Driver Support
17.2 SCSI Class/Port Architecture

When a connection must be established, a SCSI command transmitted,
or data transferred, a SCSI class driver calls the appropriate routine
within the port driver by invoking one of a series of macros, defined in
SYS$LIBRARY:LIB.MLB. Each macro corresponds to a vector in the SCSI
port descriptor table (SPDT) that supplies the address of the port routine
that performs the applicable function. Table 17-1 lists the standard SPI
macros and their functions.
Table 17-1

SCSI Port Interface (SPI) Macros

Macro

Description

SP1$ABORT_COMMAND

Aborts the execution of an outstanding SCSI command over a
specified connection

SPl$ALLOCATE_COMMAND_BUFFER

Allocates a buffer in which a class driver passes a SCSI
command descriptor to the port driver

SPl$CONNECT

Creates a connection from a class driver to a SCSI device unit

SP1$DEALLOCATE_COMMAND_BUFFER

Deallocates a SCSI command buffer

SPl$DISCONNECT

Breaks the connection between a class driver and a SCSI device
unit

SP1$GET_CONNECTION_CHAR

Obtains the characteristics of a specified connection and places
them in the buffer specified by the class driver

SPl$MAP_BUFFER

Makes the process buffer involved in a data transfer available to
the port driver

SP1$RESET

Resets the port hardware and SCSI bus

SP1$SEND_COMMAND

Delivers a SCSI command descriptor buffer to a SCSI device,
returning status and data, if applicable

SP1$SET_CONNECTION_CHAR

Sets up the characteristics of a specified connection

SP1$UNMAP_BUFFER

Releases the SCSI port's OMA buffer space and the system
page-table entries that double-mapped a user buffer involved in
a transfer

A SCSI class driver invokes SPI macros at fork IPL, holding the fork lock.
Because the port driver routines called by SPI macros may fork or stall, a
class driver must preserve local context and local return addresses across
an SPI macro invocation. It must also ensure that the address of its caller
is at the top of the stack at the time the macro is invoked. (These issues
are more fully discussed in Section 17.6.1.)
Detailed descriptions of the functions provided by the SPI macros appear
where pertinent in the discussions of SCSI class driver operations that
follow in this chapter. The macro chapter of the VMS Device Support
Reference Manual provides a condensed description of the calling interface,
functions, inputs, and returned values of each macro.
An extension to the SPI interface includes several additional macros
that enable the host to receive an asynchronous event notification from
a target on the SCSI bus. Section 1 7.9 describes the asynchronous event
notification (AEN) feature in greater detail, and introduces each of the
macros in the SPI interface extension.

17-6

SCSI Class Driver Support
17.2 SCSI Class/Port Architecture

17.2.2

SCSI-Specific Data Structures
The SCSI class/port interface must maintain status and control
information relevant to each participating connection and port. Moreover,
SCSI class drivers and port drivers require a means of sharing information
about each I/O request that involves the port. The following data
structures accommodate these needs:
•

SCSI connection descriptor table (SCDT)

•

SCSI port descriptor table (SPDT)

•

SCSI class driver request packet (SCDRP)

•

Device and port unit control blocks (UCBs)

The SCSI connection descriptor table (SCDT) contains information
specific to a connection established between a SCSI class driver and the
port, such as phase records, timeout values, and error counters. The SCSI
port driver creates an SCDT each time a SCSI class driver, by invoking the
SPI$CONNECT macro, connects to a device on the SCSI bus. The class
driver stores the address of the SCDT in the SCSI device's UCB.
The port driver has exclusive access to the SCDT; it is not accessed by
the class driver. (The SCDT structure is shown and described in the data
structure chapter of the VMS Device Support Reference Manual.)
The SCSI port descriptor table (SPDT) contains information specific
to a SCSI port, such as the port driver connection database. The SPDT
also includes a set of vectors, corresponding to the SPI macros invoked by
SCSI class drivers, that point to service routines within the port driver.
The SCSI port driver's unit initialization routine creates an SPDT for
each SCSI port defined for a specific MicroVAX/VAXstation system and
initializes each SPI vector.
The port driver reads and writes fields in the SPDT. The class driver does
not write SPDT fields, but reads the SPDT indirectly when it invokes
an SPI macro. (The SPDT structure is shown and described in the VMS
Device Support Reference Manual.)
A SCSI class driver creates a SCSI class driver request packet
(SCDRP) to deliver to the port driver information specific to an I/O
request, such as the address of the SCSI command descriptor buffer.
The class driver also places in the SCDRP some of the data it originally
received in the I/0-request packet (IRP), such as the $QIO system service
parameters, the I/O function, and the length and location of any userspecified buffer involved in a transfer. The port driver returns the actual
data transfer byte count and status information to the class driver in the
SCDRP.
Both class and port drivers read and write fields in the SCDRP; the
port driver may modify fields written by the class driver. (The SCDRP
structure is shown and described in the VMS Device Support Reference
Manual.)

17-7

SCSI Class Driver Support
17.2 SCSI Class/Port Architecture

Two unit control blocks (UCBs) are involved in any interaction between the
class driver and the port. The SCSI class driver maintains information in
the SCSI device UCB, such as the device type, class, and characteristics;
maximum transfer size; the address of the current SCDRP; and the
addresses of the associated SPDT and SCDT. The SCSI port driver
maintains similar information in the SCSI port UCB.
Table 17-2 summarizes the class/port ownership of and access to these
structures; their interrelationships are pictured in Figure 17-4.
Table 17-2 Data Structures
Structure

Allocation

Owner

Port Access

Class Access

SCORP

One per 1/0
transfer request

Class driver

Read/write

SCOT

One per SCSI
connection

Port driver

Read/write

None

SPOT

One per SCSI
port

Port driver

Read/write

Read

SCSI device UCB

One per SCSI
device unit

Class driver

None

Read/write

SCSI port UCB

One per SCSI
controller port

Port driver

Read/write

None

Figure 17-4 SCSI Class/Port Data Structures

Vectors to
SPI Routines

Device
UCB

~~---js"CDRPj--- -~~~~-

1::-1
~

ZK-1375A-GE

17-8

SCSI Class Driver Support
17.2 SCSI Class/Port Architecture

17.2.3

SCSI Class Driver Template
The VMS operating system supplies a model for a third-party
class driver in the SCSI class driver template, located in
SYS$EXAMPLES:SKDRIVER.MAR and listed in Appendix B.
SKDRIVER is a simplified, self-documenting driver that supports the
1/0 functions IO$_AVAILABLE, IO$_DIAGNOSE, and IO$_READLBLK
on a generalized device. SKDRIVER performs most operations required
of a typical SCSI class driver to process a typical 1/0 request, including
the appropriate SPI interface macro calls to establish a connection to
the port, allocate port resources, and accomplish a transfer to the SCSI
device. SKDRIVER also allocates pool for two SCDRPs. It uses one to
send a SCSI command to the device, and it uses the other to issue a SCSI
REQUEST SENSE command in the event the SCSI device returns failure
status on the original command (see Section 17.5.6.2 for information on
the interpretation of port and SCSI status return values).
In addition, SKDRIVER defines local macros that simplify common
operations, including the following:
•

Preserving register contents and return addresses within the class
driver across calls to executive and port routines that may destroy this
context (INIT_UCB_STACK, SUBPOP, SUBPUSH, SUBRETURN).

•

Assembling the information relevant to a supported SCSI command
such that a driver routine can easily construct the SCSI command
descriptor buffer and initialize the SCDRP fields describing transfer
buffer characteristics and timeout values (SCSI_CMD). SKDRIVER
uses this macro to define the SCSI commands TEST UNIT READY,
INQUIRY, REQUEST SENSE, and MODE SELECT. (It "invents" a
fifth command, QIO INQUIRY, to provide a device-independent read
operation servicing an IO$_READLBLK 1/0 function.)

SKDRIVER extends the device UCB to accommodate its context-saving
macros, the allocation of SCDRPs, and per-request timeout values (see
Section 17.4.2), SCSI-specific device characteristics, and the addresses of
the SCDT and the current SCDRP.
Code in the SCSI class driver template can serve as a good starting
point for the development of a third-party SCSI class driver. Subsequent
sections of this chapter refer to the SCSI class driver template,
as appropriate, to explain certain class driver concepts or possible
implementation strategies.

17.3

Connecting to a SCSI Device
As defined by the VMS SCSI class/port interface, a connection is a
logical link between a SCSI class driver and a SCSI device unit. In
MicroVAX/VAXstation systems, a SCSI device is identified by its device
mnemonic (for instance, SK), its SCSI port ID (A or B), its SCSI device ID
(an integer from 0 to 7), and its logical unit number (an integer from 0
to 7).

17-9

SCSI Class Driver Support
17.3 Connecting to a SCSI Device

Before a SCSI class driver can issue commands to a target device on the
SCSI bus and transfer data across the bus, it must establish a logical
connection to that device. The SPI$CONNECT macro connects a SCSI
class driver with a target device, thereby establishing a linkage between
the SCSI class driver and the SCSI port driver. Once the SCSI connection
exists, the class and port drivers can intercommunicate.
A SCSI class driver's unit initialization routine invokes the
SPI$CONNECT macro at fork level, specifying the SCSI port ID (in
numeric form), the SCSI device ID, and the SCSI logical unit number
of the device to which it needs to connect. (More detailed information
about the use and functions of the SPI$CONNECT macro appears in
Section 17.8.6 and the VMS Device Support Reference Manual.)
Normally a connection lasts throughout the runtime life of a system; a
SCSI class driver should never need to break a connection.

17.4

Setting Up a SCSI Command
This section describes the procedures a SCSI class driver follows to set
up a SCSI command for transmission to the SCSI port driver. Although
it discusses the aspects of the setup of a data transfer over the SCSI bus
that relate to the preparation of a SCSI command, you should refer to
Section 17.5 for a more complete discussion of SCSI data transfers.

17.4.1

Preparing a SCSI Command Descriptor Block
In preparation for sending a SCSI command to a device on the SCSI bus, a
SCSI class driver must first determine which SCSI commands it supports.
For each supported SCSI command, the driver programmer must perform
the following tasks:
•

Determine the correct size and format for the command

•

Define the appropriate contents for all command bytes

•

Allocate a SCSI port command buffer to make the command descriptor
block and status buffer available to the port

•

Create a SCSI command descriptor block in the SCSI port command
buffer

•

Create a 1-byte SCSI status buffer in the SCSI port command buffer

•

Establish pointers in the SCDRP to the command descriptor block and
the status buffer

•

If the command involves a data transfer, store the parameters of the
transfer in the SCDRP

The SCSI class driver template (SKDRIVER) performs these operations
by means of the locally-defined SCSI_CMD macro and the SETUP_
CMD subroutine. Each invocation of the SCSI_CMD macro establishes
a data area within the driver to contain information about a specific SCSI
command, including its length and the contents of its command bytes, plus
the size, direction, and timeout values for any associated data transfer.
The SCSI class driver template uses the SCSI_CMD macro to define
17-10

SCSI Class Driver Support
17.4 Setting Up a SCSI Command

the parameters of five 6-byte SCSI commands, although the macro can
describe commands of any length.
The SETUP_CMD subroutine of the class driver template SK_STARTIO
routine repackages command data into a SCSI command descriptor block.
Because both the command descriptor block and the SCSI status buffer
must be accessed by both the class and port drivers, it is useful to account
for the status buffer in the request to allocate the SCSI port command
buffer. Thus, the SETUP_CMD subroutine adds 2 longwords of overheadone for the SCSI status byte and one for the SCSI command size-to the
SCSI command size. It then invokes SPI$ALLOCATE_COMMAND_
BUFFER, causing the port driver to allocate a port command buffer and
return its address and size.
The class driver initializes the status longword to -1 and stores its address
in SCDRP$L_STS_PTR. It places the size (in bytes) of the SCSI command
in the next longword, and then constructs a SCSI command descriptor
block in the buffer, copying the command to the buffer byte by byte. It
places the address of the size longword in SCDRP$L_CMD_PTR.
Prior to invoking SPI$SEND_COMMAND to transmit the command
descriptor block to the port driver, the class driver may perform several
optional tasks to set up a data transfer operation, such as the following:
•

Initializing the phase change (DMA) timeout and/or disconnect timeout
fields in the SCDRP (SCDRP$L_DMA_TIMEOUT and SCDRP$L_
DISCON_TIMEOUT), thus providing command-specific timeout values
(see Section 17.4.2 for information on how to set up timeout values)

•

For a data transfer involving a user buffer, initializing fields in the
SCDRP to reflect the parameters of the buffer, and acquiring a port
mapping of that buffer

•

For a data transfer requiring a system buffer, allocating the buffer
from nonpaged pool, initializing fields in the SCDRP to reflect the
parameters of the buffer, and acquiring a port mapping of that buffer

When the command has completed and the SCSI port command buffer
is no longer required, the class driver checks the command status,
as described in Section 17 .5.6, and invokes the SPI$DEALLOCATE_
COMMAND_BUFFER macro to deallocate the buffer.

17-11

SCSI Class Driver Support
17.4 Setting Up a SCSI Command

17.4.2

Setting Command Timeouts
The SCSI port driver implements several timeout mechanisms, some
governed by the ANSI SCSI specification and others required by VMS. The
timeouts required by VMS include the following:
Timeout

Description

Phase change timeout

Maximum number of seconds for a target to change the
SCSI bus phase or complete a data transfer. (This value is
also known as the OMA timeout.)
Upon sending the last command byte, the port driver waits
this many seconds for the target to change the bus phase
lines and assert REQ (indicating a new phase). Or, if the
target enters the DATA IN or DATA OUT phase, the transfer
must be completed within this interval.

Disconnect timeout

Maximum number of seconds, from the time the initiator
receives the DISCONNECT message, for a target to
reselect the initiator so that it can proceed with the
disconnected 1/0 transfer.

The SCSI class driver is responsible for maintaining both of these timeout
values. It has the following three options:

17.4.3

•

Accepting a connection's default value. The default value for both
timeouts is 4 seconds.

•

Altering the connection's default value. To modify the default values,
the class driver specifies nonzero values in the phase change
timeout and disconnect timeout longwords of the connection
characteristics buffer and invokes the SPI$SET_CONNECTION_
CHAR macro.

•

Establishing timeouts for individual commands that override the
connection's default value. If, prior to invoking the SPI$SEND_
COMMAND macro, the class driver supplies a nonzero value in either
SCDRP$L_DMA_TIMEOUT or SCDRP$L_DISCON_TIMEOUT, the
port driver uses that value, instead of the default, for the course of
that data transfer.

Disabling Command Retry
The SCSI port driver implements a command retry mechanism, which is
enabled on a given connection by default.
When the command retry mechanism is enabled, the port driver retries
up to three times any 1/0 operation that fails during the COMMAND,
Message, Data, or STATUS phases. For instance, if the port driver detects
a parity error during the Data phase, it aborts the 1/0 operation, logs
an error, and retries the 1/0 operation. It repeats this sequence twice
more, if necessary. If the 1/0 operation completes successfully during a
retry attempt, the port driver returns success status to the class driver.
However, if all retry attempts fail, the port driver returns failure status to
the class driver.

17-12

SCSI Class Driver Support
17.4 Setting Up a SCSI Command

When command retry is enabled on a connection, a SCSI class driver
can control the number of retries the port attempts by supplying nonzero
values in the command retry count, busy retry count, arbitration
retry count, and select retry count longwords of the connection
characteristics buffer, and invoking the SPI$SET_CONNECTION_CHAR
macro.
A SCSI class driver may need to disable the command retry mechanism
under certain circumstances. For instance, repeated execution of a
command on a sequential device may produce different results than
are intended by a single command request. A tape drive could perform a
partial write and then repeat the write without resetting the tape position.
A SCSI class driver can disable this mechanism by setting bit 1 of the
connection flags longword of the connection characteristics buffer, and
invoking the SPI$SET_CONNECTION_CHAR macro.

17.5

Performing a SCSI Data Transfer
This section describes the procedures a SCSI class driver follows to set up
and accomplish a data transfer over the SCSI bus.

17.5.1

Setting the Data Transfer Mode
The SCSI bus defines two data transfer modes, asynchronous and
synchronous. In asynchronous mode, for each REQ from a target there is
an ACK from the host prior to the next REQ from the target. Synchronous
mode allows higher data transfer rates by allowing a pipelined data
transfer mechanism where, for short bursts (defined by the REQ-ACK
offset), the target can pipeline data to an initiator without waiting for the
initiator to respond.
A class driver can determine the transfer modes supported by a device
from the port capabilities longword returned from its invocation of the
SPI$CONNECT macro. Whether or not a port or a target device supports
synchronous data transfers, it is harmless for a class driver to set up the
connection to use such transfers. If synchronous mode is not supported,
the port driver automatically uses asynchronous mode.
To use synchronous mode in a transfer, the programmer of a SCSI
class driver must ensure that both the SCSI port and the SCSI device
involved in the transfer support synchronous mode. The SCSI port
of the MicroVAX 3520/3540 systems supports both synchronous and
asynchronous transfers, whereas that of the MicroVAXNAXstation 3100
supports only asynchronous transfers.
To set up a connection to use synchronous data transfer mode, the SCSI
class driver specifies a nonzero value in the synchronous longword
of the connection characteristics buffer, and invokes the SPI$SET_
CONNECTION_CHAR macro. The driver can also control the protocol of
synchronous data transfers by supplying nonzero values for the transfer
period and REQ-ACK offset longwords of the connection characteristics
buffer and invoking the macro.
17-13

SCSI Class Driver Support
17.5 Performing a SCSI Data Transfer

17.5.2

Enabling Disconnection and Reselection
The ANSI SCSI specification defines a disconnection facility that allows
a target device to yield ownership of the SCSI bus while seeking or
performing other time-consuming operations. When a target disconnects
from the SCSI bus, it sends a sequence of messages to the initiator that
cause it to save the state of the 1/0 transfer in progress. Once this is done,
the target releases the SCSI bus. When the target is ready to complete
the operation, it reselects the initiator and sends to it another sequence
of messages. This sequence uniquely identifies the target and allows the
initiator to restore the context of the suspended 1/0 operation.
Whether disconnection should be enabled or disabled on a given connection
depends on the nature and capabilities of the device involved in the
transfer, as well as on the configuration of the system. In configurations
where there is a slow device present on the SCSI bus, enabling
disconnection on connections that transfer data to the device can increase
bus throughput. By contrast, systems where most of the 1/0 is directed
toward a single device for long intervals can benefit from disabling
disconnection. By disabling disconnection when there is no contention
on the SCSI bus, port drivers can increase throughput and decrease the
processor overhead for each 1/0 transfer.
By default, the VMS class/port interface disables the disconnect facility on
a connection. To enable disconnection, the SCSI class driver sets bit 0 of
the connection flags longword of the connection characteristics buffer,
and invokes the SPI$SET_CONNECTION_CHAR macro.

17.5.3

Determining the Maximum Data Transfer Size
There are two factors governing the maximum data transfer size that any
given SCSI device can accommodate.
First, there is the maximum size supported by the device; this can be
determined from an inspection of the device's functional specification. The
SCSI class driver writes the maximum device byte count to the device's
UCB (UCB$L_MAXBCNT), usually by invoking the DPT_STORE macro
when initializing the driver prologue table (DPT).
Secondly, there is the maximum value supported by the SCSI port. The
port driver returns this value to the class driver in response to the class
driver's invocation of the SPI$CONNECT macro.
The class driver may need to adjust the value in UCB$L_MAXBCNT to
reflect the smaller of the device-specific and port-specific values.
The class driver compares the value supplied in IRP$L_BCNT with
UCB$L_MAXBCNT to determine whether to accept, reject, or segment
an 1/0 data transfer request.

17-14

SCSI Class Driver Support
17.5 Performing a SCSI Data Transfer

17.5.4

Initializing the SCDRP to Reflect Class Driver Data Buffering
Mechanisms
A standard data transfer, using direct I/O, involves the buffer specified
in the $QIO system service call as the source or destination of the data
involved in the transfer. Typically this buffer is in process space (PO
space) and mapped by the process's PO page table. To access this buffer
at elevated IPL, a driver calls a VMS-supplied FDT routine (such as
EXE$READ or EXE$MODIFY) that locks the buffer into memory and
returns the system virtual address of the first PO page-table entry that
maps the buffer. The servicing of the QIO_INQUIRY SCSI command by
the SCSI class driver template follows this approach. (Note that the QIO_
INQUIRY command is the means by which the template driver illustrates
the transfer of data from a SCSI device to a process buffer. Ordinarily, for
a specific SCSI device, a class driver would use a SCSI READ command.)
Other transfer operations may require that the class driver itself operate
upon the contents of the data buffer, or maintain its own data buffer.
For these operations, the class driver must allocate a system buffer from
nonpaged pool. The servicing of the INQUIRY SCSI command by the SCSI
class driver template follows this approach.
Depending upon the local buffering mechanism it uses to service an
I/O request, a SCSI class driver must initialize the SCDRP with the
parameters of the transfer. When a process buffer is involved in the
transfer, the class driver initializes the following fields:
Field

Contents

SCDRP$L_ABCNT

SCDRP$W_FUNC

IRP$W_FUNC

SCDRP$W_STS

IRP$W_STS

SCDRP$L_MEDIA

IRP$L_MEDIA

SCDRP$L_SVAPTE

IRP$L_SVAPTE

SCDRP$W_BOFF

IRP$W_BOFF

SCDRP$L_BCNT

IRP$L_BCNT

SCDRP$L_PAD_COUNT

SCDRP$L_SCSl_FLAGS

SCDRP$V_SOBUF bit cleared

When a system buffer is involved in the transfer, the class driver initializes
the following fields:
Field

Contents

SCDRP$L_SVA_USER

System virtual address of system buffer

SCDRP$L_SVAPTE

System virtual address of the system page table entry
mapping the first page of the system buffer

SCDRP$L_BCNT

Length of the transfer

SCDRP$L_PAD_COUNT

17-15

SCSI Class Driver Support
17.5 Performing a SCSI Data Transfer

17.5.5

Field

Contents

SCDRP$W_BOFF

Byte offset within page

SCDRP$W_STS

IRP$V_FUNC set for a read operation; clear for a write
operation

SCDRP$L_SCSl_FLAGS

SCDRP$V_SOBUF bit set

Making a Class Driver Data Buffer Accessible to the Port
Regardless of the local buffering mechanism it requires to fulfill the 1/0
transfer, a SCSI class driver must make the buffer available to the SCSI
port hardware. A SCSI class driver accomplishes this by invoking the
SPI$MAP_BUFFER macro.
The SPI$MAP_BUFFER macro causes the SCSI port driver to reserve
sufficient pages of the port's DMA buffer to accomplish the transfer, plus
sufficient mapping resources, if required, to map the class driver's data
buffer to system virtual addresses. Certain ports require this mapping so
that the port driver can access a process space buffer when setting up or
completing a transfer for the SCSI port. When the class driver initiates
a write operation, the SCSI port driver uses its mapping resources to
copy the data from the class driver's user or system data buffer to this
intermediate DMA buffer, from which the SCSI port can access it. When
the class driver initiates a read operation, the SCSI device transfers the
data to the DMA buffer, from which the port driver copies it to the class
driver's data buffer.
Other ports do not require this mapping and can access the class driver's
data buffer using system page-table entries.
By convention, a SCSI class driver sets the SCDRP$V_BUFFER_MAPPED
bit in SCDRP$L_SCSI_FLAGS when it invokes SPI$MAP_BUFFER to
map a buffer; if the buffer involved in the transfer is a system buffer, it
also sets the SCDRP$V_SOBUF bit. The SCDRP$V_SOBUF flag prevents
the SPI$MAP_BUFFER port routine from double-mapping a system buffer.
The SPI$MAP_BUFFER port routine initializes the following fields in the
SCDRP:

17-16

Field

Contents

SCDRP$L_SVA_USER

System virtual address of the system buffer. When
the class driver's local buffer is a system buffer, the
contents of this field are unchanged by SPl$MAP_
BUFFER.

SCDRP$L_SPTE_SVAPTE

System virtual address of the system page-table entry
mapping the first page of the system buffer. When
the class driver's local buffer is a system buffer, the
contents of this field and SCDRP$L_SVAPTE are
identical.

SCSI Class Driver Support
17.5 Performing a SCSI Data Transfer

Field

Contents

SCDRP$W_NUMREG

Number of pages of the port's DMA buffer allocated
for this transfer.

SCDRP$W_MAPREG

Starting page number of the first DMA buffer page
allocated for this transfer.

Once the SCSI command has been prepared, the SCSI class driver issues
the command to the SCSI device by invoking the SPI$SEND_COMMAND
macro.
When the data transfer has completed (or its failure has been serviced)
and the port DMA buffer and mapping resources are no longer required,
the class driver invokes the SPI$UNMAP_BUFFER macro to deallocate
these resources.

17.5.6

Examining Port and SCSI Status
Whether a SCSI command completes or fails, the port driver returns to
the class driver the following status values:
•

Port status in RO

•

SCSI command status in the low byte of the status buffer pointed to
by SCDRP$L_STS_PTR

•

Actual number of bytes transferred in SCDRP$L_TRANS_CNT

The class driver should examine these returned values to determine the
success or failure of a SCSI command. If a SCSI command fails, the class
driver can pursue its recovery or retry the command, depending upon the
type and severity of the error and the nature of the device.
17.5.6.1

Examining Port Status
The port status is the primary indicator of the failure of a SCSI command;
that is, if the port failed during command preparation or transmission,
it is unlikely that the SCSI command status byte contains meaningful
information.

The port driver returns one of the following status values in RO:
Status

Meaning

SS$_NORMAL

Normal successful completion

SS$_TIMEOUT

Failed during selection or arbitration

SS$_CTRLERR

Controller error or port hardware failure

SS$_BADPARAM

Bad parameter specified by the class driver

SS$_LINKABORT

Connection no longer exists

SS$_DEVACTIVE

Command outstanding on this connection

If RO contains anything but success status, the class driver may want to

examine it for specific status values and attempt error recovery, retry the
operation, or return a special error status to the original $QIO call. At
17-17

SCSI Class Driver Support
17.5 Performing a SCSI Data Transfer

the very least, the class driver should log a device error, according to the
method described in Section 17.6.2.
17.5.6.2

Examining the SCSI Status Byte
If the port driver returns SS$_NORMAL status in RO, the class driver

should proceed to check the SCSI command status in the low byte of the
longword buffer pointed to by SCDRP$L_STS_PTR.
The format of a SCSI status byte is illustrated in Table 17-3.
Interpretation of the bits in this status byte is device-specific. The VMS
SCSI template driver (SKDRIVER) first clears reserved bits 0, 6, and 7. It
compares the resulting value with the CHECK CONDITION status value,
to determine if CHECK CONDITION status has been returned.
Table 17-3 SCSI Status Byte Format
Bits of Status Byte1

Status Represented

R 0

GOOD

R 0

CHECK CONDITION

R 0

CONDITION MET/GOOD

R 0

BUSY

R 0

INTERMEDIATE/GOOD

R 0

INTERMEDIATE/CONDITION MET/GOOD

R 0

RESERVATION CONFLICT

QUEUE FULL (not implemented)

All other codes reserved.

When CHECK CONDITION status is returned, SKDRIVER initiates a
REQUEST SENSE SCSI command to determine the specific nature of the
SCSI error. To do so, it must save the address of the SCDRP associated
with the original command (in an extension to the device UCB), and
allocate a new one for use with the REQUEST SENSE command. It
prepares and issues the command according to the procedures described
in Section 17.4. When the port driver returns status from the REQUEST
SENSE command, SKDRIVER examines its status. If the port returns
failure status or if the SCSI status byte has any error bit set, SKDRIVER
completes the 1/0 request, deallocating both SCDRPs and its command
and data buffers; and returns error status to the $QIO system service.
If the port returns success status from the REQUEST SENSE command,
SKDRIVER examines the request sense key in its local system buffer
(at SCDRP$L_SVA_USER). The actions of any class driver in response
to any specific request sense key are device specific. SKDRIVER merely
translates the value into a VMS success or failure status code and returns
this code in RO. For sense keys indicating fatal errors, SKDRIVER logs a
device error.

17-18

SCSI Class Driver Support
17.5 Performing a SCSI Data Transfer

17.5.6.3

Testing for Incomplete Transfers
If both the port status value and the SCSI command status byte indicate
successful completion, the class driver performs one last test to determine
the success of any data transfer associated with the SCSI command.

The port driver returns the actual number of bytes transferred during
command processing in SCDRP$L_TRANS_CNT. The class driver should
compare the value in this field with the requested transfer size in
SCDRP$L_BCNT. If they are not equal, the class driver may return
successfully or investigate a possible error.

17.6

Other SCSI Class Driver Issues
The writer of a third-party SCSI class driver must deal with several
issues that are not specifically related to the tasks of setting up a SCSI
command or data transfer, but rather relate to the definition of the
class/port interface. Among these issues are the following:
•

Preserving the local context of the driver across calls to the port driver

•

Logging errors detected by the class driver

Subsequent sections discuss each of these issues in detail.

17.6.1

Preserving Local Context
VMS SCSI port drivers contain routines that execute in response to a
class driver's invocation of an SPI macro. A class driver should take into
account the fact that any SPI macro invocation may cause the port driver
routine to fork or stall while waiting for a port resource, and return to its
caller's caller. These actions eradicate the local context of the class driver
at the time it invoked the macro.
Therefore, a SCSI class driver routine must take special steps to ensure
the following:
•

The address of its caller is on the top of the stack.

•

All significant local context currently in registers is preserved.

•

Any local return address currently on the stack is preserved.

The SCSI class driver template (SKDRIVER) resolves these needs by
allocating a 10-longword stack within its extension to the SCSI device
UCB. The symbol UCB$L_STACK_PTR functions as a stack pointer.
The class driver template defines macros that initialize the UCB stack
(INIT_UCB_STACK), push and pop registers (or data) from the UCB
stack (SUBPUSH and SUBPOP), push the return address from the top
of the interrupt stack onto the UCB stack (SUBSAVE), and pop the
return address from the UCB stack onto the interrupt stack and RSB
(SUBRETURN).

Caution: The class driver must be careful not to overflow its local stack.
Unless it takes precautions, it could overwrite data integral to a
transfer in progress and cause unpredictable results.
17-19

SCSI Class Driver Support
17.6 Other SCSI Class Driver Issues

Prior to calling any routine that may destroy its context, the class driver
template issues a SUBSAVE to preserve its return address (before any
additional data is pushed on the interrupt stack), and invokes the
SUBPUSH macro for each register that must be preserved across the
call. When execution in the class driver resumes, the driver issues the
SUBPOP macro to restore the saved registers and the SUBRETURN
macro to return to its caller.

17.6.2

Error Logging
A SCSI class driver establishes error logging and uses the system
error logging routines (ERL$DEVICERR, ERL$DEVICTMO, and
ERL$DEVICEATTN) as described in the VMS Device Support Reference
Manual.
The VMS SCSI class/port interface defines SCSI port-driver and SCSI
class-driver extensions to the error message buffer, which are interpreted
and formatted by the VMS Error Log Utility (see Section 17.11.2). A SCSI
class driver and the associated port driver log errors independently, each
supplying SCSI-specific information as defined in its extension to the error
message buffer.
The class driver extension to the error message buffer includes the
information listed in Table 17-4.
Table 17-4 Error Message Buffer Extension for SCSI Class Drivers
Field

Length
(in bytes)

Longword count

Revision
Hardware revision
Error type

Contents
Number of longwords that follow in the error message buffer {not
including this one).
Revision level of the error message buffer. The class driver must set this
field to 1.

Hardware revision information, returned by the SCSI INQUIRY command
in ASCII format.
Type of error detected by the class driver. A SCSI class driver defines
device-specific error types according to the nature of the device it
services. The following error types are used by the VMS disk and tape
class drivers and, as such, have defined values that are interpreted by
the VMS Error Log Utility:

Error

Name

Description

CON_ERR

Attempt to connect to the port driver
failed.

MAP_ERR

Attempt to map a user buffer failed.

SND_ERR

Attempt to send a SCSI command
failed.

INV_INQ

Invalid inquiry data was received.
(continued on next page)

17-20

SCSI Class Driver Support
17.6 Other SCSI Class Driver Issues

Table 17-4 {Cont.)

Error Message Buffer Extension for SCSI Class Drivers
Length

Field

(in bytes)

Contents
Error

Name

Description

EXT_SNS_DAT

Extended sense data was returned
from the SCSI device.

INV_MOD_SNS

Invalid mode sense data returned
from the SCSI device.

07
08

REASSIGN_BLK

Reassign block.

DIAG_DATA

Invalid diagnostic data returned to the
VMS SCSI tape class driver.

SCSI ID

SCSI ID of the device to which the current command was sent. The
SCSI ID is an integer between O and 7.

SCSI LUN

SCSI LUN of the device to which the current command was sent. The
SCSI LUN is an integer between O and 7.

SCSISUBLUN

Not used. This field always contains 0.

Port status

Longword status returned in RO from the port driver. A value of -1 in this
field indicates that there is no valid data in this field.

SCSI CMD

Current SCSI command bytes. The SCSI command bytes are preceded
by a byte containing the length of the command.

SCSISTS
Additional data

Current SCSI status byte. A status byte of -1 in this field indicates that
the status byte does not yet contain valid information.

Prior to calling ERL$DEVICERR to log an error associated with device
activity, or ERL$DEVICEATTN (or ERL$DEVICTMO) to log an error on
an inactive device, the class driver should perform the following tasks:
•

Ensure that the DDT$W_ERRORBUF field contains a sufficient byte
count to accommodate both the standard error message buffer and
the SCSI class driver extension. The class driver can either supply
this value in the erlgbf argument to the DDTAB macro or specifically
initialize DDT$W_ERRORBUF.

•

Initialize the device type (UCB$B_DEVTYPE) and device class
(UCB$B_DEVCLASS) fields to DT$_GENERIC_SCSI and DC$_MISC.
A driver normally initializes these fields by invoking the DPT_STORE
macro. If the driver must use other device type or class values, or
allows them to be changed by a user program, it may need to save and
restore the real values of these fields temporarily across calls to the
error logging routines.

ERL$DEVICERR, ERL$DEVICTMO, and ERL$DEVICEATTN all result
ultimately in a call to the class driver's register dumping routine. The
register dumping routine must supply all available information about the
SCSI device error in the class driver's SCSI-specific extension to the error
message buffer.
17-21

SCSI Class Driver Support
17.6 Other SCSI Class Driver Issues

The VMS SCSI class driver template (SKDRIVER) defines the fields of this
extension and contains a macro (LOG_ERROR) and a routine (ERROR_
LOG) that are a useful basis for the implementation of error logging in a
third-party SCSI class driver.

17.7

Flow of a Read 1/0 Request Through the SCSI Class and Port Drivers
This section describes a hypothetical read-I/O request to a SCSI device as
it is serviced by a SCSI class driver and the port driver. The discussion
assumes that the read operation is successful.
When it is loaded, the class driver performs a one-time initialization
sequence as follows:
1

Its unit initialization routine invokes the SPI$CONNECT macro. In
response, the port driver forms a logical connection between the SCSI
device's UCB and the target on the SCSI bus. The port driver creates
an SCDT in which it inserts information describing the connection.

Its unit initialization routine optionally invokes the SPI$SET_
CONNECTION_CHAR macro to set the appropriate data transfer
mode or timeout values, or to enable disconnection of the connection.
In response, the port driver modifies the connection-specific
characteristics it maintains in the SCDT.

When the class driver receives a read-I/O request, it performs the following
operations:

17-22

Its read FDT routine verifies and interprets the parameters of the
$QIO system service call.

It calls a system FDT routine that locks the specified process buffer in
memory.

When the request becomes current, the start-I/0 routine dispatches to
code that services the specified function.

Its start-I/0 routine allocates and initializes an SCDRP and copies to
it the fields from the IRP required by the port driver to complete the
read operation.

Its start-I/O routine invokes the SPI$ALLOCATE_COMMAND_
BUFFER macro. In response, the port driver allocates a buffer
suitable for a SCSI command descriptor buffer and a SCSI status
byte.

Its start-I/0 routine invokes the SPI$MAP_BUFFER macro. In
response, the port driver allocates the resources required to make
the process buffer available to the port driver.

Its start-I/O routine builds a SCSI command in the command
descriptor buffer, initializes the status byte, and invokes the
SPI$SEND_COMMAND macro to send the command to the port
driver.

SCSI Class Driver Support
17.7 Flow of a Read 1/0 Request Through the SCSI Class and Port Drivers

When the port driver receives the command, it sets up the connection
characteristics (data transfer mode, timeout value, and disconnect mode)
recorded in the SCDT, sends the command buffer to the device, and
responds to changes in SCSI bus phases. The port driver performs the
following specific actions:
1

It requests and obtains ownership of the port, stalling if necessary

until the port is available.
2

It arbitrates for ownership of the SCSI bus.

It selects a target device on the SCSI bus and sends it an IDENTIFY

message.
4

It waits for the bus COMMAND phase.

It sends the SCSI command descriptor buffer, byte by byte, to the
target device.

It waits for a SCSI bus phase change. If the next phase is not DATA

IN, the port driver proceeds with the next step. Otherwise, it accepts
data from the target device as follows:

a. It sets up and starts a DMA transfer to the port's DMA buffer.
b. It saves its context in the port UCB and waits for the target device
to interrupt, signifying the completion of the read request. If the
target device does not interrupt, the port driver sets up error
status and returns to the class driver.
7

It checks the SCSI bus phase. If the phase is unchanged, the port
driver sets up the next transfer. If the phase is STATUS, the port

driver reads the status and copies the status to the return status
buffer.
8

It waits for the MESSAGE IN phase. When the phase changes to
MESSAGE IN, the port driver reads the message. If the message
is COMMAND COMPLETE, the port driver returns SS$_NORMAL
in RO. Otherwise, it returns the appropriate port status to the class
driver.

It releases the port.

10 It transfers the data from the port's DMA buffer to the process buffer.
11 It returns to the class driver.

When it regains control from the port driver, the class driver performs the
following tasks to complete the read operation:
1

It checks the port status in RO.

It checks the SCSI status in the SCSI status byte.

It checks that the actual transfer length agrees with the requested
transfer length.

It invokes the SPI$DEALLOCATE_COMMAND_BUFFER macro to
deallocate the command buffer.

17-23

SCSI Class Driver Support
17.7 Flow of a Read 1/0 Request Through the SCSI Class and Port Drivers

17.8

It invokes the SPI$UNMAP_BUFFER macro to release the port
resources mapping the user buffer.

It initiates device-independent postprocessing of the request by
invoking the REQCOM macro.

Components of a SCSI Class Driver
A SCSI class driver contains nearly all of the components of a traditional
VMS driver. These include the following:
•

Data, macro, and constant definitions

•

Driver prologue table

•

Driver dispatch table

•

Function decision table and FDT routines

•

Controller initialization routine

•

Unit initialization routine

•

Start-I/0 routine

•

Cancel-I/O routine

•

Error logging routine

•

A SCSI class driver contains no interrupt service routine. Moreover, it
has no access to device control and status registers (CSRs). It relies on
the port driver to initiate operations on the device and to service device
interrupts.
This section describes the special operations that must be performed by the
components of a SCSI class driver. The standard and typical operations ·
performed by driver routines and tables are discussed in Part II.

17.8.1

Data Definitions
A SCSI class driver must invoke the $SCDRPDEF data structure
definition macros, located in SYS$LIBRARY:LIB.MLB. $SCDRPDEF
defines the fields of the SCSI class driver request packet.
A SCSI class driver typically does not reference fields in the SCSI
connection descriptor table and, thus, does not need to invoke the
$SCDTDEF macro. Although fields in the SCSI port descriptor table
are used by the SPI macros as vectors to routines in the port driver, a
SCSI class driver need not explicitly define SPDT fields. It indirectly
obtains the SPDT definitions through its invocation of the SPI$CONNECT
macro; it is the macro that invokes $SPDTDEF.
A SCSI class driver may define an extension to the device UCB for an
internal stack or for managing the allocation of SCDRPs, depending
upon the needs of the implementation. The VMS SCSI template driver
(SKDRIVER), listed in Appendix B, illustrates uses of these additional

17-24

SCSI Class Driver Support
17.8 Components of a SCSI Class Driver

UCB fields. SKDRIVER also defines symbols representing SCSI-specific
data buffer offsets and status values.

17.8.2

Driver Prologue Table
A SCSI class driver must supply the NULL keyword as the adapter
argument to the DPTAB macro. It also must specify that the DPT$V_NO_
IDB_DISPATCH flag is set in the flags argument. The DPT$V_NO_IDB_
DISPATCH flag indicates that the IDB$L_UCBLIST field is not used to
store the addresses of UCBs for this device.
If the class driver implements error logging, it should use the DPT_

STORE macro to initialize UCB$B_DEVTYPE to DT$_GENERIC_SCSI
and UCB$B_DEVCLASS to DC$_MISC. If the class driver must use
other device type or class values, or allows them to be changed by a user
program, it may need to save and restore the real values of these fields
temporarily across calls to the error logging routines.
A SCSI class driver should not initialize CRB$L_INTD+VEC$L_ISR or the
other interrupt vectors in the CRB. A SCSI device interrupts through a
vector serviced by the port driver; any interrupt service routine specified
by the SCSI class driver is not used.

17.8.3

Driver Dispatch Table
There are no special requirements for a SCSI class driver's driver dispatch
table.

17.8.4

Function Decision Table and FDT Routines
There are no special requirements for a SCSI class driver's function
decision table.
A class driver invokes FDT routines to preprocess 1/0 functions in
a device-specific manner. Most SCSI class drivers use the standard
VMS-supplied FDT routines (such as EXE$READ, EXE$WRITE, and
EXE$SETMODE). However, some class drivers may need to include a
special FDT routine. The VMS SCSI class driver template illustrates this
approach.

17.8.5

Controller Initialization Routine
There are no special requirements for a SCSI class driver's controller
initialization routine.

17-25

SCSI Class Driver Support
17.8 Components of a SCSI Class Driver

17.8.6

Unit Initialization Routine
A SCSI class driver's unit initialization routine must perform several
special actions, as follows:
•

It checks the power failure bit (UCB$V_POWER) in UCB$W_STS to
determine whether it is being called in the course of power failure
recovery. If this bit is set, the unit initialization routine returns
immediately.

•

It forks twice, issuing the FORK macro twice in succession. The first
fork ensures, during system initialization or autoconfiguration, that
the SCSI port driver's initialization routines begin execution before
the class driver performs its initialization. The second fork guarantees
that a port driver initialization fork thread has created its SPDTs and
initialized the SCSI ports.
Note that the unit initialization routine must be executing at fork IPL
when it invokes the SPI$CONNECT macro.

•

It prepares for an SPI$CONNECT request by obtaining the SCSI port
ID, the SCSI device ID, and the SCSI logical unit number (LUN).
SCSI device unit numbers have the form dOu, where dis the device
ID and u is the LUN. The unit initialization routine obtains the SCSI
device unit number from UCB$W_UNIT and divides it by 100 (using
the EDIV instruction). The quotient (in Rl) is the device ID and the
remainder (in R2) is the LUN. Both should be values between 0 and 7.
SCSI port IDs are represented by the alphabetic characters A and B.
The unit initialization routine obtains this letter from the third byte in
DDB$T_NAME (for instance, A, from SKA500) and converts it to the
numeral 0 or 1.
Once it has obtained the SCSI port ID, the SCSI device ID, and the
SCSI LUN, the unit initialization routine sets up the registers for the
call to SPI$CONNECT as follows:

•

Destination

SCSI port ID

Low-order word of R1

SCSI device ID

High-order word of R1

SCSI LUN

High-order word of R2

It invokes the SPI$CONNECT macro. The port driver, as a result,
attempts to create a connection between the class driver and the port.
If the class driver expects notification of asynchronous events from

the target device, it supplies the address of a local selection callback
routine in the callback argument of the SPI$CONNECT macro.
(For a discussion of asynchronous event notification (AEN) mode, see
Section 17 .9.)
If the port driver returns failure status, the unit initialization

routine sets the device off line.

17-26

SCSI Class Driver Support
17.8 Components of a SCSI Class Driver

If the port driver successfully creates the connection, the unit
initialization routine initializes UCB$L_MAXBCNT, UCB$L_
SCDT, and UCB$L_PDT with the values returned by the port
driver, sets the device unit on line (by setting UCB$V_ONLINE in
UCB$W_STS), and returns success status to its caller.

The VMS template SCSI class driver (SKDRIVER) unit initialization
routine performs such optional actions as setting up an internal stack in
the UCB for context-saving purposes, and allocating nonpaged pool for a
set of SCDRPs to be queued to the UCB for use by the driver's start-110
routine. See the Appendix B for a listing of the SCSI class driver template.
The unit initialization routine may also invoke the SPI$GET_
CONNECTION_CHAR and SPI$SET_CONNECTION_CHAR macros
to examine (and possibly alter) the current data transfer mode, timeout,
command retry, and disconnect characteristics of the SCSI connection.
(See Section 17.5 for additional information.)

17.8.7

Start-1/0 Routine
A SCSI class driver's start-1/0 routine must perform the following steps to
prepare a SCSI command for delivery to the port driver:
•

Allocate an SCDRP from nonpaged pool. (The VMS template SCSI
class driver allocates SCDRPs in its unit initialization routine; its
start-1/0 routine simply removes a preallocated SCDRP from a queue
in the device UCB.)

•

Insert the address of the IRP in SCDRP$L_IRP.

•

Dispatch to a function-specific command preparation routine.

The command preparation routine performs the procedures described in
Section 17.4 and Section 17 .5. Its actions typically involve the following:
•

Invoking SPI$ALLOCATE_COMMAND_BUFFER to allocate a port
command buffer in which it assembles the SCSI command and
reserves a longword for the SCSI status byte to be returned from
command execution.

•

Initializing fields in the SCDRP from the corresponding fields in the
IRP. For read-1/0 functions, the class driver must ensure that IRP$V_
FUNC is set in SCDRP$W_STS.

•

Invoking SPI$MAP_BUFFER to make data in the process buffer
available to the port, and setting the SCDRP$V_BUFFER_MAPPED
bit in SCDRP$L_SCSI_FLAGS to indicate that the buffer has been
mapped to the port. (If it maps a system buffer, it must set both the
SCDRP$V_SOBUF and the SCDRP$V_BUFFER_MAPPED bits.)

•

Invoking SPI$SEND_COMMAND to deliver the SCSI command to the
port driver.

•

When the command completes, examining the port status, SCSI status,
and transfer count to determine the success or failure of the I/O
operation. (See Section 17.5.6 for a detailed description of the means
by which a SCSI class driver typically responds to status information.)

17-27

SCSI Class Driver Support
17.8 Components of a SCSI Class Driver

If the operation fails, the class driver may take steps to obtain

additional status information from the target device, pursue error
recovery and retry the operation, enter a device-specific message in
the error log buffer, return error status to the $QIO system service, or
perform some combination of these actions.

17.8.8

•

Invoking SPI$UNMAP_BUFFER to release port mapping resources.

•

Invoking SPI$DEALLOCATE_COMMAND_BUFFER to deallocate the
port command buffer.

•

Deallocating the SCDRP.

•

Initiating device-independent postprocessing by invoking the REQCOM
macro.

Cancel-1/0 Routine
If a SCSI class driver receives a cancel request for an 1/0 operation
in progress on a SCSI device, its cancel-1/0 routine may invoke the
SPI$ABORT_COMMAND macro to terminate the 1/0 operation.

Note: VAXstation 3520/3540 systems do not implement the abort-SCSIcommand function.

17.8.9

Register Dumping Routine
A SCSI class driver's register dumping routine executes in the course of
a driver error logging operation. The class driver calls ERL$DEVICERR,
ERL$DEVICTMO, or ERL$DEVICEATTN, and the system error logging
routine calls the driver's register dumping routine.
The register dumping routine loads the error message buffer with all
available information about a SCSI device error in the buffer extension
reserved for SCSI class driver information (see Table 17-4). Detailed
information on SCSI class driver error logging appears in Section 17.6.2.

17.9

Servicing Asynchronous Events from a SCSI Device
Devices can perform one of two roles on the SCSI bus; either the target
role or the initiator role. Typically, the host processor serves as the
initiator and peripheral devices serve as targets. However, some devices
require that the host processor respond to an unsolicited event, such as
when the device is selected or deselected. When such an event occurs,
the target device must be capable of selecting the host and acting in the
initiator mode.
Certain MicroVAXNAXstation systems implement the SCSI asynchronous
event notification (AEN) feature, allowing SCSI devices to act as initiators
on given connections. When AEN is enabled and the host is selected by a
target, the host

17-28

•

Res ponds to selection

•

Parses SCSI command packets

SCSI Class Driver Support
17.9 Servicing Asynchronous Events from a SCSI Device

•

Drives the SCSI bus phase as required by targets

The VMS SCSI class/port interface supports asynchronous event
notification by the SPI$CONNECT macro and an extension to the SCSI
port interface (SPI). Table 17-5 lists the SPI macros provided in the SPI
extension.
Table 17-5 SPI Extension Macros Supporting Asynchronous Event
Notification
SPl$FINISH_COMMAND 1

Completes an 1/0 operation executing under
the AEN feature

SPl$RECEIVE_BYTES

Receives command, message, and data
bytes from a device acting as an initiator

SP1$RELEASE_BUS 1

Releases the SCSI bus

SPl$SEND_BYTES

Sends command, message, and data bytes
to a device acting as an initiator

SPl$SENSE_PHASE

Reads the current SCSI bus phase

SPl$SET_PHASE

Sets the SCSI bus phase

1 A SCSI class driver must invoke either the SP1$FINISH_COMMAND macro or the
SP1$RELEASE_BUS macro (but not both) to complete an AEN operation.

To utilize asynchronous event notification, a SCSI class driver's unit
initialization routine must provide the address of a selection callback
routine in the call to the SPI$CONNECT macro. The port driver invokes
the callback routine at this address in response to selection by another
device. The port driver passes the selection callback routine the address of
the SPDT in R4 and any optional selection context in R5. When invoked,
the callback routine is executing at IPL 8, holding the fork lock.
If the SCSI class driver does not provide a callback address, no selections
are allowed on the connection that is established. If a selection does occur

on a connection that is not set up to accommodate selections, the port
driver releases the SCSI bus.
The flow of an AEN operation is as follows:
1

The class driver connects to the port driver and provides the callback
address.

The port driver receives a selection on an existing connection. If
selections are allowed, the port driver calls the class driver at its
callback address, holding the fork lock at IPL 8. R4 contains the
address of the SCDT and R5 contains the address of the SCDRP.

The class driver invokes SPI$SET_PHASE to set the SCSI bus to
COMMAND phase.
Because the target has selected the host, the host now becomes
the target. In SCSI, the target drives the phase of the SCSI bus
after selection. Thus, the class driver drives the SCSI bus to the
COMMAND phase to receive the command bytes from the initiator.

17-29

SCSI Class Driver Support
17.9 Servicing Asynchronous Events from a SCSI Device

The class driver invokes SPI$RECEIVE_BYTES.
Because command packets are variable in size, the class driver
requests the first byte of the command to determine how many
additional command bytes are to be expected.

The class driver again invokes SPI$RECEIVE_BYTES.
Once the class driver has determined exactly how many command
bytes are expected, it requests all remaining command bytes with this
one call.

The class driver invokes SPI$SET_PHASE to set the SCSI bus phase
to DATA IN.
After the class driver has received all the command bytes and parsed
the command to identify it, the class driver sets the bus to the
appropriate phase. For instance, if the command is READ BUFFER,
the class driver must set the bus phase to DATA IN.

The class driver invokes SPI$SEND_BYTES to return exactly the
number of data bytes requested by the initiator.

The class driver invokes SPI$FINISH_COMMAND.

The class driver returns from its callback routine.
Once the data transfer has completed, the 1/0 operation is done
from the class driver's perspective. The class driver completes the
1/0 operation by returning status and the COMMAND COMPLETE
message to the device.

17.10

Configuring a SCSI Third-Party Device
The System Generation Utility (SYSGEN) loads a third-party SCSI class
driver into system virtual memory, creates additional data structures for
the device unit, and calls the driver's controller initialization routine
and unit initialization routine. SYSGEN automatically loads and
autoconfigures the SCSI port driver at system initialization. As part
of autoconfiguration, SYSGEN polls each device on each SCSI bus.
If the device identifies itself as a direct-access device, a direct-access
CDROM device, or a flexible disk device, SYSGEN automatically loads
the VMS disk class driver (DKDRIVER); if the device identifies itself as a
sequential-access device, SYSGEN automatically loads the VMS tape class
driver (MKDRIVER). If the autoconfiguration facility does not recognize
the type of the SCSI device, it loads no driver.
Consequently, third-party SCSI devices must be configured and their
drivers loaded by an explicit SYSGEN CONNECT command, as follows:
$ RUN SYS$SYSTEM:SYSGEN
SYSGEN> CONNECT mrnpdOu /NOADAPTER

In this command, mm represents the device mnemonic (for instance, SK;
p represents the SCSI port ID (for instance, the controller ID A or B); d

represents the SCSI device ID (a digit from 0 to 7); 0 signifies the digit
zero; and u represents the SCSI logical unit number (a digit from 0 to 7).

17-30

SCSI Class Driver Support
17.1 O Configuring a SCSI Third-Party Device

17.10.1 Disabling the Autoconfiguration of a SCSI Device
Note that, in special cases, you may need to prevent SYSGEN's
autoconfiguration facility from loading the VMS disk or tape class driver
for a device with a specific port ID and device ID. This would be the case
if a 'third-party device should identify itself as either a random-access or
sequential-access device and were to be supported by the VMS generic
SCSI class driver.
To disable the loading of a VMS disk or tape driver for any given device
ID, VMS temporarily defines the special SYSGEN parameter SCSI_
NOAUTO.
The SCSI_NOAUTO system parameter, as shown in Figure 17-5, stores
a bit mask of 32 bits in which the low-order byte corresponds to the first
SCSI bus (PKAO), the second byte corresponds to the second SCSI bus
(PKBO), and so on. For each SCSI bus, setting the low-order bit inhibits
automatic configuration of the device with SCSI device ID O; setting the
second low-order bit inhibits automatic configuration of the device with
SCSI device ID 1, and so forth. For instance, the value 0000200016 would
prevent the device with SCSI ID 5 on the bus identified by SCSI port ID B
from being configured. By default, all of the bits in the mask are cleared,
allowing all devices to be configured.
Figure 17-5 SCSl_NOAUTO System Parameter

+- SCSI Port ID
ZK-1371A-GE

Note: The VMSD2 system parameter is now a special parameter reserved
to Digital.

17.11

Debugging a SCSI Class Driver
VMS device drivers execute in kernel mode at elevated interrupt priority
levels. Problems in device driver code often manifest themselves in system
failures and system hangs. Chapter 13 describes some general methods for
debugging device drivers that can also be used to debug a third-party SCSI
class driver. While using the XDELTA debugger to investigate problems
in a class driver, however, you should set breakpoints such that you can
easily step over VMS SCSI port driver code.

17-31

SCSI Class Driver Support
17.11 Debugging a SCSI Class Driver

As discussed in Section 17.6.2, Digital strongly recommends that a thirdparty SCSI class driver respond to port and SCSI status return values, and
that it incorporate an error logging routine that records events significant
to the device. Class driver error log entries, as well as VMS port driver
error log entries, can provide clues that are helpful in resolving problems
(see Section 17 .11.2) that may occur during the development of a thirdparty SCSI class driver.
Among the problems that commonly occur in early versions of SCSI class
drivers are the following:
•

The class driver has failed to deallocate a port resource, such as a
command buffer or port map registers. You should ensure that the
class driver invokes the SPI$DEALLOCATE_COMMAND_BUFFER
and the SPI$UNMAP_BUFFER macros before completing a data
transfer (that is, before invoking the REQCOM macro).

•

The class driver has sent a SCSI command to a device, but the device
does not support the command. Typically, the device times out or the
port driver logs an entry for a bad phase transition event.

•

The class driver has sent a misformatted SCSI command packet to a
device. This problem also results in a device timeout or phase error.

Hardware problems on a SCSI bus can cause a SCSI command to fail,
regardless of whether the device to which the command was directed is
at fault. When testing and debugging a class driver for a new device on a
SCSI bus, you should ensure that bus traffic from busy or faulty devices
elsewhere on a SCSI bus does not interfere with the device's operation.
Isolate the device by placing it on a SCSI bus reserved for it and the
processor alone or, if that is not possible, by placing it on the SCSI bus on
which the system disk does not reside.

17.11.1 Selecting a SCSI Bus Analyzer
Finally, in debugging a SCSI class driver, you may find a SCSI bus
analyzer to be a valuable aid.
A SCSI bus analyzer is a passive device that monitors all traffic on the
SCSI bus to which it is connected, and displays in a useful format the data
it has collected. Some analyzers can be used in an active mode to generate
packets on the bus; however, this is generally more useful to developers of
SCSI target devices than to writers of class drivers.
A SCSI bus analyzer is commonly used to verify that the commands the
class driver generates (or should generate) are actually being transmitted
across the SCSI bus. The most useful analyzers can interpret the SCSI
phase lines and display the phase along with the data sent during that
phase. This helps the writer of a class driver pinpoint the location of a
possible coding problem. Another common use of an analyzer is to capture
infrequent errors such as bus hangs or a target dropping off the bus.

17-32

SCSI Class Driver Support
17.11 Debugging a SCSI Class Driver

Some features to look for in an analyzer are as follows:
•

Ability to interpret the bus phase lines and display the data according
to the phase

•

A "timing mode" that displays bus signals in the form of a timing
diagram

•

Ability to trigger the analyzer on a specific event, such as a specific
data pattern in a specific phase or a bus reset

•

Ability to dump the contents of the display to a printer

17.11.2 Interpreting SCSI Error Log Entries
As dictated by the VMS SCSI class/port driver architecture, a VMS SCSI
port driver logs port-specific events in a defined form. Port driver error log
entries can provide clues that are helpful in resolving problems that may
occur during the development of a third-party SCSI class driver.
The VMS SCSI class/port driver architecture also specifies a form for class
driver error log entries. Because of the value of the error log in debugging,
Digital highly recommends that a third-party SCSI class driver incorporate
an error logging routine that records events significant to the device. (See
Section 17 .6.2 for a discussion of the procedures by which class drivers
interpret status, format events, and register error log entries.)
You can use the VMS Error Log Utility, as described in the VMS Error
Log Utility Manual, to list and format SCSI port and class driver error log
entries.
17.11.2.1

SCSI Port Driver Error Log Entries
The SCSI port driver is responsible for all low-level activity associated
with sending commands to a target SCSI device. The standard format
of an error log entry generated by a port driver has two parts: a portcommon section and a port-specific section. All VMS port drivers provide
the same type of information in the port-common section of the entry. The
information a port driver supplies in the port-specific section depends upon
the SCSI port hardware that is in use.

Table 17-6 describes the contents of a formatted port driver error log
entry. A reference number in the table column "Field" associates each
table item with an entry in the representative error logs presented in
Examples 17-1 and 17-2.
When inspecting a SCSI port driver error log entry, first examine the
error type and error subtype. These fields indicate the nature of the
event that occurred. Also check the SCSI ID field to determine the device
for which the event has been reported. Although the SCSI ID may not
always identify the device responsible for the event, it may help you
interpret the significance of the information in this and other error log
entries.

17-33

SCSI Class Driver Support
17.11 Debugging a SCSI Class Driver

Next, examine the SCSI CMD field to determine which SCSI command
was current at the time of the logged event. The phase queue entry
lists those SCSI bus phases that have been successfully completed during
execution of this command. You can derive the current phase of the
SCSI bus by referring to the description of the phase signals defined for
the command in the ANSI SCSI specification. In addition, the port-specific
section of the error log entry of certain VMS port drivers lists the currently
asserted bus lines.
Finally, the sets of counters that appear in a port driver error log entry
can help you discern patterns of activity on the SCSI bus. For instance, a
large number of parity errors are a symptom of a bus termination problem
or other hardware problem.

17-34

SCSI Class Driver Support
17.11 Debugging a SCSI Class Driver

Table 17-6 Key to Port Driver Error Log Entries
Field 1

Description

General Event Information
Error type 0
Error subtype 8

Error type and subtype. The following types and subtypes are defined.

Error2

Definition

Description

BUS_HUNG

SCSI bus was continuously busy during an
arbitration attempt.

ARB_FAIL

Arbitration of SCSI bus failed due to activity of
higher priority devices.

03
04
05
06

SEL_FAIL

Selection failed.

TIMEOUT

Timeout occurred.

PARITY_ERROR

Parity error detected.

PHASE_ERROR

SCSI bus phase error. A phase error results
from a missing SCSI bus phase, a phase that
is entered more than once, or a bad phase
sequence.

Subtype2 Description

BUS_RESET

Missing phase error

02
03
04

Timeout waiting for phase interrupt

Bad phase transition
Unexpected phase change during
DATA IN; error during REQ-ACK

Unexpected phase change during
DATA OUT; error during REQ-ACK

Phase change timeout during DATA
IN

Phase change timeout during DATA
OUT

08
09

Timeout waiting for phase change

Bus freed during command phase

Phase change timeout during
COMMAND OUT

Bus reset detected.

Subtype2 Description
01

Reset occurred while no 1/0 operation
was active

UNEXPECTED_
INTERRUPT

Unexpected interrupt received.

BUS_RESET_
ISSUED

Bus reset initiated.

Reference numbers refer to Examples 17-1 and 17-2.

Error type and subtype values are rendered in hexadecimal format.
(continued on next page)

17-35

SCSI Class Driver Support
17.11 Debugging a SCSI Class Driver

Table 17-6 (Cont.) Key to Port Driver Error Log Entries
Field1

Description

General Event Information
10

RESEL_ERR

Error following a device disconnect.

Subtype2 Description
01

Bad parity during reselect

No target ID during reselect

Multiple target IDs during reconnect

No connection to this target

Failed while no reselect was pending

SEL failed to clear during reselect

REQ failed to set during reselect

Bad RESEL message

CTL_ERR

Error detected by controller.

BUS_ERR

Controller detected a SCSI bus protocol error.

ILLEGAL_MSG

Illegal message received.

14-19

Reserved.

SCSI ID@)

SCSI ID of the device to which the current command is being sent. Valid SCSI
IDs range from Oto 7. A value of FF1 6 in this entry indicates that the SCSI ID is
unknown or not relevant (as in the case of a spurious bus reset).

SCSI CMD8

Current SCSI command.

SCSI MSG0

Current SCSI message.

SCSI STATUS 8

Current SCSI status. A status value of FF1 6 indicates that the SCSI bus has not
yet returned status.

Port Error Counters3
Bus busy count 8

Number of times the port driver has attempted to arbitrate for the SCSI bus and
has found the bus hung for an extended period of time. A value in this field
indicates either that the bus is extremely busy or a device on the bus is hung.

Unsolicited reset count 6)

Number of times the port driver has received a reset interrupt that is not due to its
own pulling of the bus reset line. This could be due to noise on the reset line or to
a device (or another initiator) pulling the bus reset line.

Unsolicited interrupt count 0

Number of times the port driver has received an unsolicited interrupt.

1 Reference numbers refer to Examples 17-1 and 17-2.

2 Error type and subtype values are rendered in hexadecimal format.

3 The port error counters record errors that cannot be attributed to a specific device on the SCSI bus.

(continued on next page)

17-36

SCSI Class Driver Support
17.11 Debugging a SCSI Class Driver

Table 17-6 (Cont.)
Field1

Key to Port Driver Error Log Entries
Description

Connection Error Counters4
Arbitration fail count 8

Selection fail count

Number of times the port driver has attempted to arbitrate for the SCSI bus
and has failed. Arbitration is attempted only when a bus free condition is
detected. Thus, this counter reflects the number of times a low priority device
loses arbitration to a higher priority device.
Number of times the port driver has attempted to select a target device and has
failed. This could happen just after a target device has been reset, if it has been
powered off or disconnected from the bus, or if it is hung in such a way that it is
not also hanging the bus.

Parity error count 8

Number of times the port driver has detected a parity error while sending a
command to a target SCSI device.

Phase error count 8

Number of times the port driver has detected a phase error while sending a
command to a target SCSI device.

Bus reset count

Number of times the port driver has reset the bus because it was unable to send
a command to a target SCSI device. The port driver resets the bus for a number
of reasons: for instance when it detects a bus hang or a phase error.

Bus error count 8
Controller error count

Number of times the SCSI controller has detected an error on the SCSI bus. This
field is not used by SCSI controllers on MicroVAXNAXstation 3100 systems.

Number of times the SCSI controller has reported an internal error. This field is
not used by SCSI controllers on MicroVAXNAXstation 3100 systems.

Retry Counters
Arbitration retry count •

Number of arbitration retries attempted. A value of -1 indicates that the counter
contains no valid data.

Selection retry counter 8

Number of selection retries attempted. A value of -1 indicates that the counter
contains no valid data.

Bus busy retry counter 8

Number of bus busy retries attempted. A value of -1 indicates that the counter
contains no valid data.

Phase Queue
Element phase queue 9

Lists the SCSI phases that have been entered and completed during the execution
of the current command. The digit preceding the list indicates the number of
phases that have been completed.

Port dependent data •

Contents of port controller registers. This section of the error log entry contains
information specific to the SCSI port controller employed by the system.

Reference numbers refer to Examples 17-1 and 17-2.

4 The connection error counters record errors that can be attributed to a specific device on the SCSI bus. The SCSI ID field

specifies the devices to which the command was being sent when the error occurred.

17-37

SCSI Class Driver Support
17.11 Debugging a SCSI Class Driver

17.11.2.2

SCSI Class Driver Error Log Entries

A SCSI class driver logs device-specific events in the manner described in
Section 17 .6.2. Although all class drivers use a common extension to the
standard error message buffer when logging errors, the types of events
detected and reported by class drivers are specific to the devices they
control.
Table .17-7 describes the contents of a formatted class driver error log
entry. Each item in the "Field" column of this table is associated with a
field in the error log contained in Example 17-3.
Table 17-7 Key to Class Driver Error Log Entries
Field1

Description

Hardware revision 9

Hardware revision information, returned by the SCSI INQUIRY command.

Error type 9

Type of error detected by the class driver. A SCSI class driver defines devicespecific error types according to the nature of the device it services. The following
error values are interpreted by the VMS Error Log Utility:

SCSI

toe

Error2

Name

Description

01
02
03
04
05

CON_ERR

Attempt to connect to the port driver failed

MAP_ERR

Attempt to map a user buffer failed

SND_ERR

Attempt to send a SCSI command failed

INV_INQ

Invalid inquiry data was received

EXT_SNS_DAT

Extended sense data was returned from the
SCSI device

INV_MOD_SNS

Invalid mode sense data returned from the
SCSI device

07
08

REASSIGN_BLK

Reassign block

DIAG_DATA

Invalid diagnostic data returned to the VMS
SCSI tape class driver

SCSI ID of the device to which the current command was sent. The SCSI ID is an
integer between O and 7.

SCSI LUN 9

SCSI logical unit number of the device to which the current command was sent.
The SCSI LUN is an integer between O and 7.

SCSI SUBLUN 9

Not used. This field always contains 0.

Port status 9

Current port status. A value of -1 indicates that there is no valid data in this field.

SCSI CMD8

Current SCSI command.

SCSI STSfJ>

Current SCSI status. A value of -1 indicates that there is no valid data in this
field.

Reference numbers refer to Example 17-3.

2 Error type values are rendered in hexadecimal format.

(continued on next page)

17-38

SCSI Class Driver Support
17.11 Debugging a SCSI Class Driver

Table 17-7 (Cont.)

Key to Class Driver Error Log Entries

Field1

Description

Additional data 9

Additional data, preceded by a byte count of the data. A class driver defines what
additional data would be meaningful in an error log entry based on the type of
device it services. Additional data is displayed by the VMS Error Log Utility as
untranslated longwords.
Note that the VMS Error Log Utility can interpret extended sense data values
when the extended sense data received error type is reported in the log and
the driver's error logging routine places the sense data in this field of its error
message buffer. Thus, the error log entry that appears in Example 17-3 interprets
the logged sense data as a unit attention message signifying a power on or reset
condition.

1 Reference numbers refer to Example 17-3.

17.12

Resolving SCSI Class Driver Problems Using Error Logs
Taken as a unit, Examples 17-1 through 17-3 illustrate a standard event
sequence that may occur during a SCSI bus transaction. This sequence
involves the following actions:
1

The port detects an abnormal event, such as a timeout.
(Example 17-1)

The port driver resets the SCSI bus. (Example 17-2)

A class driver receives extended sense data from the device informing
it of the reset event. (Example 17-3)

These events typically occur for one of the following reasons:
•

The class driver has sent a SCSI command to a device that the device
does not understand or does not support.

•

The class driver has sent a misformatted SCSI command packet to a
device.

•

The class driver has failed to deallocate a port resource, such as a
command buffer or port map registers.

•

A hardware failure has occurred on the SCSI bus.

17-39

SCSI Class Driver Support
17.12 Resolving SCSI Class Driver Problems Using Error Logs

Example 17-1

SCSI Bus Phase Error Port Driver Error Log Entry

V A X I V M S

SYSTEM ERROR REPORT

******************************* ENTRY
ERROR SEQUENCE 43028.
DATE/TIME 13-SEP-1990 15:03:35.08
SCS NODE:
DEVICE ATTENTION

KA420

COMPILED 13-SEP-1990 15:05
PAGE
1.

208. *******************************
SID OA000005
LOGGED ON:
SYS TYPE 04010102
VAX/VMS X5.2-1C

CPU REV# 6.

SCSI PORT SUB-SYSTEM, UNIT _PKAO:
ERROR TYPE

06
SCSI BUS PHASE ERROR. .
SUB-ERROR TYPE = 02(X).

SCSI ID

SCSI CMD

CA810208
0019

SCSI MSG

SCSI STATUS

SCSI ID = 2.9

READO
COMMAND COMPLETE.
NO STATUS RECEIVED(!)
PORT ERROR CNT

00000000
00000000
00000000
BUS BUSY CNT = 0.fj
UNSOL RESET CNT = 0 . . ,
UNSOL INTRPT CNT = o.@>

CONN ERROR CNT

00000000
00000000
00000000
00000001
00000000
00000000
00000000
ARB FAIL CNT =
SEL FAIL CNT =

o.C!>

0.~

PARITY ERR CNT = 0.~
PHASE ERR CNT
l.~

BUS RESET CNT = 0.~
BUS ERROR CNT = 0 . . .
CONTROLLER ERROR CNT =
SCSI RETRY CNT

00000000
0000
ARB RETRY CNT
SEL RETRY CNT
BUSY RETRY CNT

PHASE QUEUE

0.~

= 0.~
= o.48)

= o.41>

0908

2. ELEMENT PHASE QUEUEC&
_ARBITRATION
_SELECTION
PORT DEPENDENT DATA~
CNTLR INI CMD

CNTLR MODE

ATN ASSERTED
PARITY CHECK ENABLED

(continued on next page)

17-40

SCSI Class Driver Support
17.12 Resolving SCSI Class Driver Problems Using Error Logs

Example 17-1 (Cont.)
CNTLR TAR CMD
CNTLR CURR STS

SCSI Bus Phase Error Port Driver Error Log Entry
00
78

CID ASSERTED
MSG ASSERTED
REQ ASSERTED
BUSY ASSERTED
CNTLR STATUS

OMA CNT
OMA ADDRESS
OMA DIR

00000000
00004200
01

ATN ASSERTED

Example 17-2 SCSI Bus Reset Port Driver Error Log Entry

******************************* ENTRY
ERROR SEQUENCE 43029.
DATE/TIME 13-SEP-1990 15:03:35.08
SCS NODE:
DEVICE ATTENTION

KA420

READ OPERATION
209. *******************************
LOGGED ON:
SID 0A000005
SYS TYPE 04010102
VAX/VMS X5.2-1C

CPU REV# 6.

SCSI PORT SUB-SYSTEM, UNIT _PKAO:
ERROR TYPE

09
BUS RESET INITIATEDtt
SUB-ERROR TYPE = OO(X)f}

SCSI ID

SCSI CMD

CA810208
0019

SCSI MSG

SCSI STATUS

SCSI ID = 2 • •

READ.
COMMAND COMPLETE.
NO STATUS RECEIVED(t
PORT ERROR CNT

00000000
00000000
00000001
BUS BUSY CNT = O.fj
UNSOL RESET CNT =
UNSOL INTRPT CNT = l.f>

o.fD

CONN ERROR CNT

00000000
00000000
00000000
00000001
00000001
00000000
00000000

o.C!>

ARB FAIL CNT =
SEL FAIL CNT =
PARITY ERR CNT = 0.~
PHASE ERR CNT = 1.41)
BUS RESET CNT =
BUS ERROR CNT = 0.49
CONTROLLER ERROR CNT =

o.41

1.49

SCSI RETRY CNT

o.e

00000000
0000

o.4fi

ARB RETRY CNT =
SEL RETRY CNT =
BUSY RETRY CNT =

o.41&

o.41>
{continued on next page)

17-41

SCSI Class Driver Support
17.12 Resolving SCSI Class Driver Problems Using Error Logs

Example 17-2 (Cont.)
PHASE QUEUE

SCSI Bus Reset Port Driver Error Log Entry
0908
2. ELEMENT PHASE QUEUEei
ARBITRATION
SELECTION

PORT DEPENDENT DATA~
CNTLR INI CMD
CNTLR MODE
CNTLR TAR CMD
CNTLR CURR STS
CNTLR STATUS

00
00
00
00
08
PHASE MATCH

DMA CNT
DMA ADDRESS
DMA DIR

00000000
00004200
01
READ OPERATION

Example 17-3 SCSI Bus Reset Class Driver Error Log Entry
******************************* ENTRY
ERROR SEQUENCE 43030.
DATE/TIME 13-SEP-1990 15:03:35.49
SCS NODE:
DEVICE ERROR

KA420

210. *******************************
LOGGED ON:
SID OA000005
SYS TYPE 04010102
VAX/VMS X5.2-1C

CPU REV# 6.

RZ23 SUB-SYSTEM, UNIT _DKA200:
HW REVISION

38313630

ERROR TYPE

SCSI ID

SCSI LON

SCSI SUBLUN

PORT STATUS

00000001

HW REVISION =

0618~

EXTENDED SENSE DATA RECEIVED~
SCSI ID= 2 . •
SCSI LUN = 0.1)
SCSI SUBLUN =

o.9

%SYSTEM-S-NORMAL, NORMAL SUCCESSFUL
COMPLETION.
SCSI CMD

CA810208
0019
READ9

SCSI STATUS

CHECK CONDITION~

EXTENDED SENSE DAT AG
EXTENDED SENSE

00060070

ocoooooo

00000000
00000029
0000
UNIT ATTENTION
POWER ON OR RESET OCCURRED

(continued on next page)

17-42

SCSI Class Driver Support
17.12 Resolving SCSI Class Driver Problems Using Error Logs

Example 17-3 (Cont.)

SCSI Bus Reset Class Driver Error Log Entry

UCB$B_ERTCNT

UCB$B_ERTMAX

ORB$L_OWNER

00010001

UCB$L_CHAR

1C4D4008

0. RETRIES REMAINING
0. RETRIES ALLOWABLE
OWNER UIC (001,001]
DIRECTORY STRUCTURED
FILE ORIENTED
SHARABLE
AVAILABLE
MOUNTED
ERROR LOGGING
CAPABLE OF INPUT
CAPABLE OF OUTPUT
RANDOM ACCESS
UCB$W_STS

0010
ONLINE

UCB$L_OPCNT

0000104E
4174. QIO'S THIS UNIT

UCB$W_ERRCNT

0001

IRP$W_BCNT

3200

IRP$W_BOFF

0000

IRP$L_PID

00010000

IRP$Q_IOSB

00000000
00000000

1. ERRORS THIS UNIT
TRANSFER SIZE 12800. BYTE(S)
TRANSFER PAGE ALIGNED
REQUESTOR "PIO"

******************************* ENTRY
ERROR SEQUENCE 43031.
DATE/TIME 13-SEP-1990 15:04:51.53
SCS NODE:
TIME STAMP

KA420

IOSB, 0. BYTE(S) TRANSFERRED
211. *******************************
LOGGED ON:
SID OA000005
SYS TYPE 04010102
VAX/VMS X5.2-1C

CPU REV# 6.

17-43

18 Terminal Class and Port Drivers
This chapter describes details of the implementation of the VMS terminal
driver. The VMS terminal driver consists of two pieces: the terminal
port driver and the terminal class driver. These two pieces of code, when
bound together within the unit control block (UCB), form a single devicedependent driver that implements the VMS terminal services.
TTDRIVER.EXE, the VMS terminal class driver, handles the deviceindependent functions and tasks. For example, it contains code that
enables command line editing on many different types of terminals. The
port drivers manage those functions and tasks that depend on the device's
hardware configuration. For example, the port driver for a particular type
of terminal controller performs the actual transmission and reception of
characters to and from that terminal controller. The port driver reserves
all manipulation and interpretation of those characters to the class driver.
Because class driver code supports the functions common to terminal
devices, a terminal port driver can contain only that code needed to control
a specific interface.
There are several reasons why a new port driver may be required:
•

To support a new terminal controller

•

To implement a terminal server such as LATll

•

To provide a pseudoterminal

Both class drivers and port drivers adhere to the same rules as other VMS
device drivers. They consist of the same routines and tables as standard
drivers, and reference the same data structures. However, because a class
driver and its port drivers must intercommunicate, they must employ a
few additional structures and routines not required for standard VMS
device drivers.
The structure of the VMS terminal driver illustrates one specific approach
to the class/port concept. The interface described in this chapter relates
only to TTDRIVER.EXE and its ports. Programmers of terminal port
drivers must adhere to the programming rules presented in this chapter.
Note that there are no supported methods for implementing the class/port
design in a non-Digital-supplied device driver. Moreover, the System
Generation Utility (SYSGEN) provides no support for alternate class
drivers and can only connect port drivers to TTDRIVER.EXE.
The remainder of this chapter describes how the VMS terminal class and
port drivers are structured and how they interact. A full description of
the functions of the VMS terminal driver appears in the VMS I I 0 User's
Reference Manual: Part I.

18-1

Terminal Class and Port Drivers
18.1 Overview

18.1

Overview
The terminal class driver is the device-independent part of the VMS
terminal driver. It contains the driver's function decision table (FDT)
routines, start I/O routine, fork process routines, code that implements
the features of the VMS terminal services, and the class driver service
routines.
The terminal port driver is the device-dependent piece of the VMS
terminal driver. It contains the driver prologue table (DPT); data structure
initialization; device, unit, and controller initialization routines; port
service routines; interrupt service routine; and any additional devicedependent code. Among the port drivers included in VMS are DZDRIVER
for the DZ-32 and DZ-11, YCDRIVER for the DMF-32 and DMZ-32,
YFDRIVER for the DHU-11 and DHV-11, YIDRIVER for the DMB32, and
YEDRIVER for the MicroVAX 2000/3100 and VAXstation 3100 built-in
serial lines. (See the VMS I I 0 User's Reference Manual: Part I for a
complete list of supported terminal controllers.)

18.2

Data Structures
There are three major data structures that define the communication
between the port and the class drivers. These data structures are the
UCB, the port driver vector table and the class driver vector table. To
reference these structures, a driver must include an invocation of the
$TTYDEFS macro (from SYS$LIBRARY:LIB.MLB). The $TTYDEFS macro
defines symbolic offsets for the following structures:

18.2.1

•

Unit control block (UCB)

•
•
•
•
•
•
•
•

Terminal UCB extension
Channel request·block (CRB)
Interrupt dispatch block (IDB)
Port and class driver vector tables
Read buffer
Input stack
I tern list descriptor
Type-ahead buffer

Terminal UCB
A terminal UCB, as depicted in Figure 18-1, contains four sections: the
system section (base UCB), the class driver required section, the port
driver required section, and the port extension region.
The system section of the terminal driver UCB contains the pieces of the
UCB that are present in all of the UCBs on the system.

18-2

Terminal Class and Port Drivers
18.2 Data Structures

Figure 18-1

UCB Structure for Terminal Class/Port Drivers

System
Region

Terminal Class
Driver Required
Region

Terminal Port
Driver Required
Region

Port Driver
Extension Region

ZK-6540-GE

The class driver required section of the UCB contains fields that are
needed by the class driver. These fields have names of the form UCB$x_
TT_fieldname, where x denotes the field size and fieldname is the name of
the field.
The port driver required section of the UCB contains fields that both the
class and port driver must access. These fields have names of the form
UCB$x_TP_fieldname, where x denotes the field size and fieldname is the
name of the field. Although a port driver may not actually use all these
fields, their presence is required.
The terminal port extension region is defined by the terminal port driver.
It can be any length and contain any context that the port driver needs to
perform its duties.
The structures and contents of the UCB and terminal extensions are
described in the VMS Device Support Reference Manual.

18-3

Terminal Class and Port Drivers
18.2 Data Structures

18.2.2

Port Driver Vector Table
The port driver vector table, as depicted in Figure 18-2, is the data
structure that allows the terminal class driver to find the port service
routines. The vector table contains the address, relative to the beginning
of the port driver, of each port service routine. The port driver's controller
initialization routine invokes the CLASS_CTRL_INIT macro, as described
in Section 18.4.1.1, to relocate this vector table.
The port driver vector table is contained within the port driver itself,
usually after the port driver's DPT. The port driver must build its vector
table using the $VECINI, $VEC, and $VECEND macros, as described
in Section 18.2.4. A field in the UCB, UCB$L_TT_PORT, contains the
address of the port driver vector table.
Port and class drivers refer to fields within the port driver vector
table using the symbolic offsets represented in Figure 18-2. To use
these offsets, they include an invocation of the macro $TTYDEFS (in
SYS$LIBRARY:LIB.MLB).
Figure 18-2 Port Driver Vector Table

PORT_STARTIO

PORT_DISCONNECT

PORT_SET_LINE

PORT_DS_SET

PORT_XON

PORT_XOFF

PORT_STOP

Reserved

PORT_ABORT

PORT_RESUME

PORT_SET_MODEM

Reserved

PORT_MAINT

PORT_FOR KR ET

PORT_FDT

56
(continued on next page)

18-4

Terminal Class and Port Drivers
18.2 Data Structures

Figure 18-2 (Cont.)

18.2.3

Port Driver Vector Table

Reserved

PORT_CANCEL

Class Driver Vector Table
The class driver vector table, as depicted in Figure 18-3, contains the
address, relative to the beginning of the class driver, of each class service
routine. The list is terminated by a longword containing zeros that
indicates to the relocation routine where the list ends.
At driver load time, the relative offsets are relocated to actual virtual
addresses. The port driver's controller initialization routine invokes the
CLASS_CTRL_INIT macro, as described in Section 18.4.1.1, to relocate
this vector table. The VMS terminal class driver is loaded by SYSINIT at
boot time to allow the console terminal port driver to run.
Figure 18-3 Class Driver Vector Table

CLASS_GETNXT

CLASS_PUTNXT

CLASS_SETUP_UCB

CLASS_DS_TRAN

CLASS_DDT

CLASS_READERROR

CLASS_DISCONNECT

CLASS_FORK

CLASS_POWERFAIL

CLASS_TABLES

18-5

Terminal Class and Port Drivers
18.2 Data Structures

The class driver vector table is contained within the class driver itself,
usually after the class driver's DPT. The class driver builds its vector
table using the $VECINI, $VEC, and $VECEND macros, as described
in Section 18.2.4. A field in the UCB, UCB$L_TT_CLASS, contains the
address of the class driver vector table.

18.2.4

Vector Table Generation Macros
Port drivers use three VMS-supplied macros to build the port driver vector
table: $VECINI, $VEC, and $VECEND. Class drivers build the class
driver vector table using the same macros. To obtain the definitions
for these macros, a driver must invoke the $TTYMACS macro (in
SYS$LIBRARY:LIB.MLB). This section briefly discusses the functions
of each of these macros. An example of their use appears in Figure 18-4,
and a full discussion of their syntax appears in the macro chapter of the
VMS Device Support Reference Manual.
18.2.4.1

$VECINI Macro
The $VECINI macro creates a vector table and initializes each entry with
the address of the driver's null entry point. Subsequent calls to the $VEC
macro fill in selected table entries with the addresses of real entry points.

The driver must specify the drivername and null_routine arguments
to the $VECINI macro. The drivername argument generally contains a
2-letter prefix to the driver name, such as DZ or YE. The null_routine
argument contains the address of a routine within the driver (for example
DZ$NULL) that contains an RSB. When the class driver attempts to
call the port driver at an entry point corresponding to an unsupported
function, the port driver's null routine simply returns control to the class
driver. The class driver can then proceed to service the error.
18.2.4.2

$VEC Macro
The $VEC macro validates and generates a vector table entry.

Each invocation of the $VEC macro specifies the entry argument and
the routine argument. However, a driver need not supply the address of
a routine for each entry in the table. The $VEC macro will construct a
valid table regardless of how many entries are supplied. The $VEC macro
accepts the entry names (minus the PORT_ or CLASS_ prefix) shown in
Table 18-1, for port drivers, and Table 18-2, for class drivers. Note that
a driver accesses the table using the symbolic offsets indicated in Figures
18-2 and 18-3. The $VECINI macro defines the prefix applied to the
entries, which is PORT_ for the port vector table and CLASS_ for the class
vector table.
18.2.4.3

18-6

$VECEND Macro
The $VECEND macro generates the longword of zeros that
terminates the vector table and positions the location counter at label
drivername$VECEND. It has no required arguments.

Terminal Class and Port Drivers
18.3 Structure of Port and Class Drivers

18.3

Structure of Port and Class Drivers
Class and port drivers share a similar organization, as seen in Figures
18-4 and 18-5.
The vector table of each follows the driver prologue table (DPT). The
driver specifies the address of the vector table in the vector argument to
the DPTAB macro, which places its offset from the beginning of the DPT
in DPT$W_VECTOR.
Following the vector table, and linked to the vectors by invocations of
the $VEC macro, is a set of service routines. The balance of the driver
includes standard driver routines and tables and driver-specific routines.
Figure 18-4 Port Driver Structure

DPT

Port Vector Table
$VECINI ZZ,ZZ$NUL
$VEC STARTIO,ZZ$STARTIO
$VEC RESUME,ZZ$RESUME
$VEC ABORT,ZZ$ABORT
$VECEND

Port Service Routines
.,
ZZ$ABORT:
ZZ$RESUME: ....
ZZ$STARTIO: . ,

---

Port-Specific Routines

ZK-6541-GE

18-7

Terminal Class and Port Drivers
18.3 Structure of Port and Class Drivers

Figure 18-5 Class Driver Structure

TIY$GL_DPT::
DPT
DPT$W_VECTOR:

--------+-----a
DDT

CLASS_VECTOR: .... _ - - - - - - - - - - - Class Vector Table
.LONG TIY$GETNEXTCHAR_TT$DPT
.LONG TIY$PUTNEXTCHAR_TT$DPT

.LONG 0

Class Service Routines
TIY$PUTNEXTCHAR:•
TIY$GETNEXTCHAR:~

Class-Specific Routines
ZK-6542-GE

18-8

Terminal Class and Port Drivers
18.3 Structure of Port and Class Drivers

18.3.1

Binding Class and Port Drivers
The terminal class and port drivers are bound together to form a single,
complete driver in the manner represented in Figure 18-6.
The port driver's unit initialization routine performs the binding process
by calling the CLASS_UNIT_INIT macro. The CLASS_UNIT_INIT macro
fills in the following UCB fields as indicated:
Field

Contents

UCB$L_TI_CLASS

Terminal class driver's vector table address

UCB$L_TI_PORT

Terminal port driver vector table address

UC8$~TI_GETNXT

Address of the class driver's get-next-character routine
(CLASS_GETNXT)

UCB$L_TI_PUTNXT

Address of the class driver's put-next-character routine
(CLASS_PUTNXT)

UCB$L_DDT

Address of the terminal class driver's driver dispatch
table

Note that, because the get-next-character and put-next-character routines
are the most heavily used class driver routines, their addresses are stored
in the UCB. It is therefore possible for code to issue the instruction JSB
@address(R5) to call either routine (presuming that R5 contains the
address of the UCB). To call other routines, the driver must first move the
address of the vector table to a general register and issue an instruction
of the form JSB @offset(Rn). Although a saving of one instruction does not
seem significant, it can save one instruction per character when a driver is
receiving data.
When the port driver's unit initialization routine completes the binding,
the terminal class and port drivers have become one complete driver, and
the device units are ready for I/0.

18-9

Terminal Class and Port Drivers
18.3 Structure of Port and Class Drivers

Figure 18-6 Terminal Class/Port Driver Binding
Port Driver
PORT_VECTOR: 4
Port Vector Table
$VECINI ZZ,ZZ$NUL
$VEC STARTIO,ZZ$STARTIO
$VEC RESUME,ZZ$RESUME
$VEC ABORT,ZZ$ABORT
$VECEND

UCB

Port Service Routines
ZZ$ABORT: ....
ZZ$RESUME: "'
ZZ$STARTIO: •
~

System Section

1
-

Terminal Class
Driver Required
Class Driver

...

UCB$L_TT_PORT

TTY$GL_DPT::
DPT
DPT$W_VECTOR

Terminal Port
Driver Required
DDT

I
CLASS_VECTOR:•

UCB$L_TT_CLASS
UCB$L_TT_PUTNXT
UCB$1_TT_GETNXT

Class Vector Table
.LONG TTY$GETNEXTCHAR_TT$DPT
.LONG TTY$PUTNEXTCHAR_TT$DPT

...

Port Driver
Extension Region

::::

.LONGO

Class Service Routine
TTY$PUTNEXTCHAR:...TTY$GETNEXTCHAR:,

•
ZK-6543-GE

18-10

Terminal Class and Port Drivers
18.4 Port Driver Routines

18.4

Port Driver Routines
When the terminal class driver has completed a segment of deviceindependent processing of an 1/0 request, it calls a port routine to complete
the device-dependent processing. The port driver contains three types of
routines: port startup routines, port initiate routines, and port service
routines.
Table 18-1 lists the port driver routines that are part of the class/port
interface. This section describes the functions and context of each listed
routine.
Table 18-1

Port Driver Routines

Routine

Function

Port Startup Routines
Controller initialization routine

Resets the controller and relocates the port and class
driver vector tables

Unit initialization routine

Sets up each device unit controlled by the driver

Port Initiate Routines
PORT_DISCONNECT

Notifies the port driver of the last deassign for the
UCB

PORT_DS_SET

Outputs modem signals to a specified unit

PORT_FDT

Performs FDT processing for device-specific function
modifiers

PORT_FORKRET

Return address in the port driver to which CLASS_
FORK transfers control when servicing the port
driver's request for a fork process

PORT_MAINT

Services $010 requests for 10$_SETMODE function
with the 10$M_MAINT modifier

PORT_SET_LINE

Changes terminal line parameters

PORT_SET_MODEM

Informs the port that a line has been enabled for
modem signal input transitions

PORT_STARTIO

Starts output on an inactive line
(continued on next page)

18-11

Terminal Class and Port Drivers
18.4 Port Driver Routines

Table 18-1 (Cont.)
Routine

Port Driver Routines
Function

Port Service Routines

18.4.1

PORT_ABORT

Aborts any currently active output

PORT_CANCEL

Cancels internally queued operations in response to a
$CANCEL request

PORT_RESUME

Resumes any previously stopped output

PORT_STOP

Halts the output data stream

PORT_XOFF

Takes steps to halt an input data stream that is
approaching its limit

PORT_XON

Resumes the acceptance of input data

Port Startup Routines
Port startup routines include the port driver's controller and unit
initialization routines. Note that, although these routines are not included
in the port vector table, they must make calls to several class routines.
They additionally fill the role of the equivalent initialization routines in a
standard device driver, as discussed in Section 11.1.
18.4.1.1

Controller Initialization Routine
The controller initialization routine is responsible for resetting the
controller and relocating the port and class driver's vector tables. To
perform the last-mentioned task, the routine should invoke the CLASS_
CTRL_INIT macro, supplying the symbolic name of the driver prologue
table (for instance, DZ$DPT) in the dpt argument and the address
of the port driver's vector table in the vector argument. To use the
CLASS_CTRL_INIT macro, the driver must include an invocation of the
$TTYMACS definition macro (from SYS$LIBRARY:LIB.MLB).

18.4.1.2

Unit Initialization Routine
The unit initialization routine is responsible for setting up each individual
device unit. The activities of a standard unit initialization routine
include loading certain locations in the UCB with controller-specific
data, preparing the hardware for input and output, and taking any action
necessary to service a power failure.

The unit initialization routine of a terminal port driver must additionally
perform the following tasks:
1

Invoke the CLASS_UNIT_INIT macro to generate the common code
that must be executed by all terminal port driver unit initialization
routines. This code includes the logic that binds the class and port
drivers in the manner discussed in Section 18.3.1. Before it invokes
the CLASS_UNIT_INIT macro, the unit initialization routine must
place the address of the port driver vector table in RO.
To use the CLASS_UNIT_INIT macro, the driver must include
an invocation of the $TTYMACS definition macro (from
SYS$LIBRARY:LIB.MLB).

18-12

Terminal Class and Port Drivers
18.4 Port Driver Routines

18.4.2

Call the class service routine, CLASS_SETUP_UCB, to allow the class
driver to reset fields in the UCB.

Call the class service routine, CLASS_SET_LINE, to allow the class
driver to reset the speed, parity, and the device-dependent bits, if
necessary.

If the line can run modem protocol, call the class service routine,
CLASS_DS_TRANS, with the transition type MODEM$C_INIT in Rl.
Note that, to use modem symbols, the port driver must invoke the
$TTYMDMDEF macro (from SYS$LIBRARY:LIB.MLB).

When a power failure occurs (UCB$V_POWER set in UCB$W_STS),
call the class service routine, CLASS_POWERFAIL.

Perform other hardware-specific functions.

Port Initiate Routines
The terminal class driver calls port initiate routines when it must initiate
device activity and the port driver is not active. Port initiate routines can
issue callbacks to the class driver.
A call to a port initiate routine uses the following instruction format:
MOVL
JSB

UCB$L_TT_PORT(R5),RO
@PORT_DISCONNECT(RO)

;get pointer to port vector table
;call port disconnect routine

Note that a port initiate routine must preserve the contents of all registers.
18.4.2.1

PORT_DISCONNECT
A call to the PORT_DISCONNECT routine indicates that there are no
longer channels associated with the device, thus notifying the port driver
of the last deassignment for the device's UCB. If the delete bit (UCB$V_
DELMBX) is set in UCB$W_DEVSTS, VMS will delete the UCB.

Note: As long as the device name is known to the system, broadcasts and
assign channel requests may occur on this device. (Broadcasts,
however, will not occur if the DEV$V_NET bit is set in UCB$L_
DEVCHAR.)
Input to the PORT_DISCONNECT routine is as follows:
RO

Flags. If bit O is set, the user requested that the UCB not be deleted

(NOHANGUP).
R5

18.4.2.2

Address of UCB.

PORT_DS_SET
The PORT_DS_SET routine sends modem signals to the specified
unit. Masks representing modem signals are defined in $TTDEF (in
SYS$LIBRARY:STARLET.MLB). They include the following:
TT$M_DS_CARRIER

Data channel received line signal detector

TT$M_DS_CTS

Clear to send

TT$M_DS_DSR

Data set ready

18-13

Terminal Class and Port Drivers
18.4 Port Driver Routines

TT$M_DS_DTR

Data terminal ready

TT$M_DS_RING

Calling indicator

TT$M_DS_RTS

Request to send

TT$M_DS_SECREC

Secondary receive

TT$M_DS_SECTX

Secondary transmit

See the VMS I I 0 User's Reference Manual: Part I for an explanation of
modem protocol.
Input to the PORT_DS_SET routine is as follows:

18.4.2.3

Low byte indicates signals to be activated; high byte indicates signals to be
deactivated.

Address of UCB.

PORT_FDT

The terminal class driver calls the PORT_FDT routine when servicing a
$QIO request for an IO$_TTY_PORT function. The PORT_FDT routine
performs whatever tasks the class driver's FDT routine would normally
do to service the request. These tasks include checking the functiondependent parameters (pl through p6), verifying access to buffers,
and terminating with a call to EXE$QIORETURN, EXE$ABORTIO, or
EXE$FINISHIO.
The PORT_FDT routine thus allows a port driver to implement support
for device-specific function modifiers without requiring an extension to the
class/port interface.
If there is no PORT_FDT routine, control will pass to the port driver's null
routine, which returns control to the class driver. The VMS terminal class
driver, TTDRIVER.EXE, thereupon issues an illegal I/O function error.

Input to the PORT_FDT routine is as follows:
R3

Address of IRP

Address of current PCB

Address of UCB

Address of CCB

Bit number of the 110 function code

OO(AP)

Address of the first function-dependent 010 parameter (p1)

The routine destroys the contents of ;R2.
Note that a port driver must set TTY$V_PC_PORTFDT in UCB$W_TT_
PRTCTL ifit contains a PORT_FDT routine.
18.4.2.4

PORT_FORKRET

The terminal class driver's service routine, CLASS_FORK, returns control
to the port driver's PORT_FORKRET entry point after servicing the port
driver's request to create a fork process. (See the description of CLASS_
FORK in Section 18..5.4.) The only context returned from the servicing of
the fork request is the address of the UCB in R5.
The terminal class driver issues a a JMP instruction (rather than a JSB
instruction) to the PORT_FORKRET routine.
18-14

Terminal Class and Port Drivers
18.4 Port Driver Routines

18.4.2.5

PORT_MAINT
The class driver calls the PORT_MAINT routine whenever a $QIO
request is issued for an 10$_SETMODE function with the 10$M_MAINT
modifier. The VMS I I 0 User's Reference Manual: Part I lists all possible
maintenance functions; each port driver must decide which of these
functions it must support.

Input to the PORT_MAINT routine is as follows:

18.4.2.6

Address of UCB

UCB$B_TT_MAINT

Parameters to the 10$M_MAINT function

PORT_SET_LINE
The PORT_SET_LINE routine changes terminal line parameters. The
terminal class driver calls the PORT_SET_LINE routine whenever any
terminal characteristic in UCB$L_DEVDEPEND or UCB$L_DEVDEPND2
is changed. It also calls this routine when speed, parity, and the enabling
or disabling of DMA and automatic flow control are affected.

The PORT_SET_LINE routine is the only port routine that is allowed to
write the fields UCB$L_DEVDEPEND and UCB$L_DEVDEPND2.
Input to the PORT_SET_LINE routine is as follows:
RS

Address of UCB.

UCB$B_TT_MAINT

Parameters to the 10$M_MAINT function.

UCB$B_TT_PARITY

Parity, stop bits, and frame size.

UCB$W_TT_SPEED

Low byte indicates transmit speed; high byte indicates
receive speed or is zero.

UCB$W_TT_PRTCTL

DMA enable flag (TTY$V_PC_DMAENA) and auto XOFF
enable flag (TTY$V_PC_XOFENA).

UCB$L_DEVDEPEND

First longword for device-dependent status.

UCB$L...:..DEVDEPND2

Second longword for device-dependent status.

The PORT_SET_LINE routine can safely destroy the contents of R4.
18.4.2.7

PORT_SET_MODEM
A call to the PORT_SET_MODEM routine informs the port that the line
has been enabled for modem signal input transitions. A port implementing
modem functions must ensure that the hardware is ready to detect
changes in input modem signals. When hardware does not provide this
capability (as, for instance, the DZll terminal controller does not), the
VMS terminal class/port interface implements the equivalent capability by
using timer-based polling.

At the time of the call, R5 contains the address of the UCB.

18-15

Terminal Class and Port Drivers
18.4 Port Driver Routines

18.4.2.8

PORT_STARTIO

The terminal class driver calls the PORT_STARTIO routine to start output
on a line that is currently inactive. The PORT_STARTIO routine is always
called with either a character or a burst of data and it is never called
unless the line is idle (UCB$V_INT is clear in UCB$W_STS).
The UCB$V_INT bit functions as an interlock, signifying that the port
output logic is busy. The class driver always sets UCB$V_INT when
it calls PORT_STARTIO. If the port requests that timers be set up
(TTY$V_PC_NOTIME clear in UCB$W_TT_PRTCTL), then the class
driver calculates and creates an output timer for the burst or character
and sets UCB$V_TIM in UCB$L_STS.
Input to the PORT_STARTIO routine is as follows:

18.4.3

Address of the port driver's vector table
(UC8$L_TT_PORT)

Address of the terminal state quadword
(UCB$L_TT_STATE1)

Character to be output (if UCB$B_TT_OUTYPE is 1)

Address of UCB

UCB$8_TT_OUTYPE

Zero if there is no character to be output; 1 if there is
one character to be output; and a negative value if there
is a burst to be output

UCB$L_TT_OUTADR

Address of burst to output (if UCB$B_TT_OUTYPE is
negative)

UC8$W_TT_OUTLEN

Length of burst (if UCB$8_TT_OUTYPE is negative)

Port Service Routines
The terminal class driver can call port service routines at any time.
Note: Because they must consist of reentrant code, port service routines
cannot issue callbacks to the class driver.

A call to a port service routine uses the following instruction format:
MOVL
JSB

UCB$L_TT_PORT(R5),RO
@PORT_ABORT(RO)

;get pointer to port vector table
;call port abort routine

Note that a port service routine must preserve the contents of all registers.
18.4.3.1

PORT_ABORT

The terminal class driver calls the PORT_ABORT routine to abort any
currently active output activity: for instance, the last burst of output sent
to the port. The PORT_ABORT routine invalidates the contents of the
address stored in UCB$L_TT_OUTADR.
At the time of the call, R5 contains the address of the UCB.

18-16

Terminal Class and Port Drivers
18.4 Port Driver Routines

18.4.3.2

PORT_CANCEL
The terminal class driver calls the PORT_CANCEL routine in servicing
a $CANCEL, $DASSGN, or $DALLOC request. The PORT_CANCEL
routine cancels any internally queued operations for the port. Most
commonly, a call is issued to this routine when a request to establish an
outgoing connection has been stalled because the port is busy.

Input to the PORT_CANCEL routine is as follows:
R2

Address of the terminal state quadword (UCB$L_STATE1)

Address of IRP

Address of current PCB

Address of UCB

Channel index number

Reason for cancellation, one of the following:
CAN$C_CANCEL
Called by $CANCEL system service
CAN$C_DASSGN

18.4.3.3

Called by $DASSGN or $DALLOC system service

Address of logical UCB (UCB$L_TT_LOGUCB)

PORT_RESUME
The terminal class driver calls the PORT_RESUME routine to resume any
previously stopped output. The port must be prepared for this routine to
be called at any time (whether output is currently active or has previously
been stopped). The PORT_RESUME routine should always ensure that
the port hardware is enabled for output.

At the time of the call, R5 contains the address of the UCB.
18.4.3.4

PORT_STOP
The PORT_STOP routine halts the output data stream. The terminal class
driver normally calls this routine in response to input flow control. When
called, the PORT_STOP routine should stop the data stream as soon as
possible.

At the time of the call, R5 contains the address of the UCB.
18.4.3.5

PORT_XOFF
The terminal class driver calls the PORT_XOFF routine when it is
approaching or has reached its input limit. The PORT_XOFF routine
takes steps to stop the input data stream. For character-oriented
controllers, it commands the port to insert the flow control character
in the output data stream as soon as possible.

Input to the PORT_XOFF routine is as follows:
R3

Flow control character to be inserted in the input data
stream

Address of UCB

UCB$L_STS

UCB$V_INT may or may not be set

If the port hardware requires it, the PORT_XOFF routine sets UCB$V_
INT in UCB$L_STS.

18-17

Terminal Class and Port Drivers
18.4 Port Driver Routines

18.4.3.6

PORT_XON

The terminal class driver calls the PORT_XON routine when it has
cleared its input path and is ready to accept data. For character-oriented
controllers, the PORT_XON routine commands the port to insert the flow
control character in the input data stream.
Input to the PORT_XON routine is as follows:
R3

Flow control character to be inserted in the input data
stream

Address of UCB

UCB$L_STS

UCB$V_INT may or may not be set

If the port hardware requires it, the PORT_XON routine sets UCB$V_INT

in UCB$L_STS.
18.4.3.7

Port Interrupt Service Routines

A terminal port driver must contain code to service receiver interrupts and
transmitter interrupts. The exact form of a device interrupt associated
with the port driver is device dependent. For multiple-line interfaces, the
port driver must also determine which line is requesting the interrupt and
move its UCB address into R5.
To service receiver interrupts, the port driver obtains a character from the
port, together with hardware error flags that signal a parity, overrun, or
frame error in the transaction. It proceeds as follows:
•

If an error has been detected, the port driver passes the character and

error flags to the CLASS_READERROR service routine for processing
(for instance, autobaud detection).
•

If no error has been detected, the port driver passes the character to

the CLASS_PUTNXT service routine.
If either of these service routines returns characters that must be echoed

and the line is currently inactive, the port driver must start output. Before
dismissing the interrupt, the port driver for a controller with multiple lines
should check all lines for pending transactions and empty the silo.
To service transmitter interrupts, the port driver first records any reported
errors. It then proceeds as follows:
•

If TTY$V_TP_ABORT is set in UCB$B_TP_STAT, the port driver calls

the PORT_ABORT service routine to terminate the transaction.
•

If TTY$V_TP_ABORT is not set, the port driver sets up the next

output sequence according to the following priority:
Transaction

Use

Preempt

Normally used to send an XON or XOFF character

Hold

Normally used for single-character output

Burst

Used for multiple-character (OMA) output

Note that this action can result in an XON or XOFF character
appearing in the middle of an escape sequence.
18-18

Terminal Class and Port Drivers
18.4 Port Driver Routines

18.5

Class Driver Routines
Table 18-2 lists the class driver routines that are part of the class/port
interface. This section describes the functions and context of each listed
routine.
A call to a class service routine uses the following instruction format:
MOVL
JSB

UCB$L_TT_CLASS(R5),R0
@CLASS_DISCONNECT(RO)

;get pointer to class vector table
;call class disconnect routine

Table 18-2 Class Driver Routines

18.5.1

Routine

Function

CLASS_DDT

Pointer to the driver dispatch table

CLASS_DISCONNECT

Disconnects a process from a terminal on a
nonmodem line

CLASS_DS_TRANS

Manages data set transitions

CLASS_FORK

Services a port driver's request to create a fork
process

CLASS_GETNXT

Delivers to the port driver the next character or burst
to be output

CLASS_PUTNXT

Obtains input characters from the port driver

CLASS_SETUP_UCB

Initializes the UCB

CLASS_POWERFAIL

Services a power failure

CLASS_READERROR

Services a parity, data overrun, or framing error on a
terminal line

CLASS_DDT
This entry in the class driver vector table points to the driver dispatch
table (DDT). The CLASS_UNIT_INIT macro uses the CLASS_DDT entry
point when moving the address of the DDT into the UCB.

18.5.2

CLASS_DISCONNECT
A port driver calls the CLASS_DISCONNECT routine to indicate to the
terminal class driver that the terminal is no longer connected to the
system. This is the preferred way of disconnecting a process from a
terminal on a nonmodem line.
At the time of the call, R5 must contain the address of the UCB. The
CLASS_DISCONNECT routine destroys the contents of R4.

18-19

Terminal Class and Port Drivers
18.5 Class Driver Routines

18.5.3

CLASS_DS_TRANS
This CLASS_DS_TRANS routine manages data set state transitions. The
port driver's unit initialization routine must call this routine with the
transition type MODEM$C_INIT in Rl if the unit is capable of having
data set transitions. (Note that, to use modem symbols, the port driver
must invoke the $TTYMDMDEF data structure definition macro (from
SYS$LIBRARY:LIB.MLB).
Input to the CLASS_DS_TRANS routine is as follows:
R1

Transition type, one of the following:
MODEM$C_INIT

Initialize modem control

MODEM$C_INIT_NORESET

Start modem protocol, but do not
initialize signals

MODEM$C_SHUTDWN

Shut down the line and disconnect
the process

MODEM$C_SHUTDWN_NOHANGUP

Stop modem protocol but do not
stop the signals

MODEM$C_DATASET

Data set signal changes

New receive modem mask (if MODEM$C_DATASET is specified in R1)

Address of UCB

The CLASS_DS_TRANS routine destroys the contents of RO through R4.

18.5.4

CLASS_FORK
A port driver calls the CLASS_FORK routine to create a driver fork
process that uses the UCB fork block. The port driver must never initiate
a fork directly-it must always call this routine.
The CLASS_FORK routine sets up the fork block in the UCB and performs
the other tasks necessary to store context in the fork block, insert it in a
processor-specific fork queue, and suspend driver processing. When the
fork has taken place, the class driver calls the port driver at its PORT_
FORKRET entry point.
At the time of the call, R5 must contain the address of the UCB. The
CLASS_FORK routine destroys the contents of R4.

18.5.5

CLASS_GETNXT
The port driver calls the CLASS_GETNXT routine whenever it has
completed the current character or burst to obtain the next characters
to be output on the unit. If CLASS_GETNXT returns data to the port
driver, a timer is set up (unless explicitly disabled) and the interrupt
expected bit is set.

18-20

Terminal Class and Port Drivers
18.5 Class Driver Routines

At the time of the call, R5 must contain the address of the UCB. Output
from the CLASS_GETNXT routine includes the following:

18.5.6

Destroyed

Number of characters (if R3 contains an address)

Character to be output (if UCB$B_TT_OUTYPE is
positive); address of characters to be output (if UCB$B_
TT_OUTYPE is negative); or no character (if UCB$B_
TT_OUTYPE is zero)

Destroyed

Address of UCB

R6 through R11

Destroyed

UCB$B_TT_OUTYPE

Zero if there is no character to be output; 1 if there is
one character to be output; and a negative value if there
is a burst to be output

UCB$L_TT_OUTADR

Address of burst to output (if UCB$B_TT_OUTYPE is
negative)

UCB$W_TT_OUTLEN

Length of burst (if UCB$B_TT_OUTYPE is negative)

CLASS_PUTNXT
The port driver calls the CLASS_PUTNXT routine to pass input characters
to the terminal class driver. The CLASS_PUTNXT routine filters
characters received from nonpassall units for immediate control sequences.
If a slave mode unit (that is, generating no unsolicited input) does not
have a read outstanding, the CLASS_PUTNXT routine ignores the input
characters, after performing the control-character :filtering.
If the input characters are to be echoed to the terminal, CLASS_PUTNXT
calls CLASS_GETNXT to notify the port driver.

The CLASS_PUTNXT routine may or may not return output data to
the port driver, depending upon the setting of the interrupt-expected bit
(UCB$V_INT) in UCB$L_STS. If this bit is set, CLASS_PUTNXT does not
return data. If it does return data, the terminal port driver should assume
that more data may follow, and call CLASS_GETNXT after outputting the
returned data.
Input to the CLASS_PUTNXT routine is as follows:
R3

Input character

Address of UCB

Output from the CLASS_PUTNXT routine is as follows:
R1

Destroyed

Number of characters (if R3 contains an address)

Character to be output (if UCB$B_TT_OUTYPE is
positive); address of characters to be output (if UCB$B_
TT_OUTYPE is negative); or no character (if UCB$B_
TT_OUTYPE is zero)

18-21

Terminal Class and Port Drivers
18.5 Class Driver Routines

18.5.7

Destroyed

Address of UCB

R6 through R11

Destroyed

UCB$B_TT_OUTYPE

Zero if there is no character to be output; one if there is
one character to be output; and a negative value if there
is a burst to be output

UCB$L_TT_OUTADR

Address of burst to output {if UCB$B_TT_OUTYPE is
negative)

UCB$W_TT_OUTLEN

Length of burst {if UCB$B_TT_OUTYPE is negative)

CLASS_SETUP_UCB
A port driver's unit initialization routine calls CLASS_SETUP_UCB when
it is invoked at system startup and power failure.
The CLASS_SETUP_UCB routine initializes the unit's fork block;
write queue (UCB$L_TT_WFLINK); break, passall, and DMA device
characteristics; and read timed out dispatch field (UCB$L_TT_RTIMOU).
In addition, it initializes several UCB fields as follows:
UCB$L_TT_LOGUCB

Address of UCB

UCB$L_DEVCHAR

DEV$V_AVL set

UCB$L_DEVCHAR2

DEV$V_RED cleared

UCB$W_TT_CURSOR

UCB$W_TT_HOLD

Cleared

UCB$W_TT_SPEED

UCB$W_TT_DESPEE

UCB$B_TT_PARITY

UCB$B_TT_DEPARI

UCB$B_DEVTYPE

UCB$B_TT_DETYPE

At the time of the call, R5 must contain the address of the UCB.

18.5.8

CLASS_POWERFAIL
A port driver's unit initialization routine calls the CLASS_POWERFAIL
routine when it detects a power failure.
At the time of the call, R5 must contain the address of the UCB.
Output from the CLASS_POWERFAIL routine includes the following:

18.5.9

UCB$W_STS

UCB$V_INT cleared; UCB$V_TIM set

UCB$L_DUETIM

Cleared

CLASS_READERROR
A port driver calls CLASS_READERROR when it detects a parity, data
overrun, or framing error on the terminal line. CLASS_READERROR
completes the read operation with error status if a read is active, or simply
returns if no read is active.
18-22

Terminal Class and Port Drivers
18.5 Class Driver Routines

Input to the CLASS_READERROR routine is as follows:
R3

Character and flags. The following flags are defined:
Bit 12
Parity error on the given character
Bit 13

Framing error on the given character

Bit 14

Data overrun

Address of UCB.

Output from the CLASS_READERROR routine is as follows:
RO through R3

Destroyed

UCB$B_TT_OUTYPE

Zero if there is no character to be output; 1 if there is
one character to be output; and a negative value if there
is a burst to be output

18-23

Mapping to 110 Space and the Connect-to-Interrupt
Facility
Programs written in VAX MACRO can interface with the 1/0 subsystem by
using VMS RMS, by using the Queue 1/0 Request ($QIO) system service,
or by mapping to 1/0 address space and connecting to a device interrupt
vector. Programs written in a high-level language can interface with the
1/0 subsystem using the same methods as a VAX MACRO program, or
they can issue the 1/0 statements specific to that language. In the latter
case, the program interfaces with the 1/0 subsystem by means of the VAX
Common Run-Time Procedure Library.
A user program can interface with the 1/0 subsystem at one of several
levels, depending on its requirements. At each level, the user program
makes trade-offs between ease of use and execution speed. As a general
rule, the closer to the VMS executive that a user program interfaces, the
less overhead is involved in the 1/0 operation. The connect-to-interrupt
capability offers the least overhead.
A process with suitable privileges can connect to a device interrupt vector
or map the system's 1/0 address space into process virtual address space
or both. Connecting to a device interrupt vector allows your process to
respond to interrupts from the device with minimal overhead. Mapping
system 1/0 address space allows your process to access device registers
from the main program or from an AST procedure.
A process normally uses these features for devices that do not have VMS
drivers. These devices must not be direct memory access CDMA) devices,
and they must be attached to the UNIBUS or Q22 bus. Examples of such
devices are the AXVll-C and the K.Wll-P.

19.1

1/0 Address Space
In a VAX system, 1/0 address space is assigned physical address locations
of 20000000 16 and higher (F20000 16 and higher for VAX-11/730 and
VAX-111780 systems). 1/0 address space contains device registers that
a driver or user process can read and write to control a device. Each
device controller has an associated control and status register (CSR) in
1/0 address space. Device registers for each device are located at an offset
from the device's CSR.
Macros of the format $IOxxxDEF (where xxx represents a specific VAX
system), contained in SYS$LIBRARY:LIB.MLB, define symbols describing
the layout of 1/0 address space. Table 19-1 describes these macros and
the symbols they define for each VAX system.

19-1

Mapping to 110 Space and the Connect-to-Interrupt Facility
19.1 110 Address Space

Table 19-1

Symbols Defined by the $10xxxDEF Macros

Symbols

Meaning

Value (Hex)

For VAX 6000-2xx/6000-3xx Series defined by macro $109CCDEF
109CC$AL_IOBASE
109CC$C_BIWINDOW
109CC$C_BIWSIZ
109CC$C_PERXBI

Start of 1/0 address space
Offset to node O window space
Size of window space
Size of adapter address space

20000000
400000
40000
2000000

For VAX 6000-4xx Series defined by macro $109RRDEF
109RR$AL_IOBASE
109RR$C_BIWINDOW
109RR$C_BIWSIZ
109RR$C_PERXBI

Start of 1/0 address space
Offset to node O window space
Size of window space
Size of adapter address space

20000000
400000
40000
2000000

For VAX 85x0/8700/88x0 defined by macro $108NNDEF
108NN$AL_NBIB_O
108NN$AL_NBIB_1
108NN$AL_NBIB_2
108NN$AL_NBIB_3
108NN$AL_NBIB_4
108NN$AL_NBIB_5
108NN$AL_NODESP
108NN$AL_NDSPER

Start of 1/0 address space for VAXBI 0
Start of 1/0 address space for VAXBI 1
Start of 1/0 address space for VAXBI 2
Start of 1/0 address space for VAXBI 3
Start of 1/0 address space for VAXBI 4
Start of 1/0 address space for VAXBI 5
Offset to node O window space
Size of window space

20000000
22000000
24000000
26000000
28000000
2AOOOOOO
400000
40000

For VAX 82x0/83x0 defined by macro $108SSDEF
108SS$AL_NODESP
108SS$AL_NDSPER

Address of node O window space
Size of window space

20400000
40000

For VAX 8600/8650 defined by macro $10790DEF
10790$AL_IOAO
10790$AL_IOA1
10790$AL_UBOSP

Start of 1/0 address space for SBIO
Start of 1/0 address space for SBl1
Offset to start of adapter address space
for first UNIBUS

20000000
22000000
24000000

For VAX-11n80 and VAX-11n85 defined by macro $10780DEF
10780$AL_IOBASE
10780$AL_UBOSP

Start of 1/0 address space
Start of adapter address space for first UNIBUS

20000000
20100000

(continued on next page)

19-2

Mapping to 110 Space and the Connect-to-Interrupt Facility
19.1 110 Address Space

Table 19-1 (Cont.)
Symbols

Symbols Defined by the $10xxxDEF Macros
Meaning

Value (Hex)

For VAX-111750 defined by macro $10750DEF1
10750$AL_IOBASE
10750$AL_UBBASE
10750$AL_MBBASE
10750$AL_UBOSP

Start of 1/0 address space
Start of UBAO adapter register space
Start of MBAO adapter register space
Start of adapter address space for first UNIBUS

F20000
F30000
F28000
FCOOOO

For VAX-111730 defined by macro $10730DEF
10730$AL_IOBASE
10730$AL_UBOSP

Start of 1/0 address space
Start of adapter address space for UNIBUS

F20000
FCOOOO

MicroVAX 3400 Series defined by $10640DEF macro
10640$AL_OBOSP

Start of adapter address space for 022bus

20000000

MicroVAX 3600/3900 Series defined by $10650DEF macro
10650$AL_OBOSP

Start of adapter address space for 022 bus

20000000

VAX 4000 Series defined by $10670DEF macro
10670$AL_OBOSP

Start of adapter address space for 022 bus

20000000

MicroVAX II defined by $10UV2DEF macro
IOUV2$AL_OBOSP

Start of adapter address space for 022 bus

20000000

1The VAX-11/750 system has fixed MASSBUS adapters (UBBASE, MBBASE) in contrast to the VAX-11/780 system, which has
floating MASSBUS adapters, and the VAX-11/730, which does not have MASSBUS adapters.

The number of registers and their locations varies from device to device.
The PDP-11 Peripherals Handbook provides the necessary information
for Digital-supplied devices. The VAX Hardware Handbook contains
information about the layout of I/O address space.
From the symbols defined by the macros described in Table 19-1, you can
derive the starting physical addresses of UNIBUS or Q22 bus adapter
address space for the various VAX systems. Table 19-2 lists the starting
physical addresses for UNIBUS adapters on the VAX 8600/8650, VAX-11
1780, VAX-11/785, VAX-111750, and VAX-11/730 systems, as well as the
starting physical addresses for MicroVAX/Q22 bus interface address space.

19-3

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.1 1/0 Address Space

Note: To access UNIBUS device CSRs you must add 3E00016 to the
addresses listed in Table 19-2. This operation is not necessary
when you use the values supplied for MicroVAX/Q22 bus systems.

For VAX 85x0/8700/88x0, VAX 82x0/83x0, and VAX 6000-series systems,
Example 19-1 illustrates the calculations that are necessary to determine
the location of the adapter address space for a given UNIBUS adapter
(DWBUA or DWMBA) on a VAXBI bus. For additional information on the
layout of VAXBI 1/0 address space, see the discussion and illustrations in
Section 16.2.
Table 19-2 UNIBUS and Q22 Bus Adapter Address Space
UNIBUS
Adapter
Number

VAX-111730

VAX-111750

VAX-11/780
VAX-11/785

MicroVAX
Systems

VAX 8600 SBIO/SBl1
VAX 8650 SBIO/SBl1

OOFCOOOO

20100000

20000000

20100000/22100000

OOF80000

20140000

20140000/22140000

20180000

20180000/22180000

201COOOO

201 C0000/221 COOOO

Example 19-1

Locating the Adapter Address Space of a UNIBUS Adapter on a VAXBI Bus

For VAX 85x0/8700/88x0:
I08NN$AL_NBIB_n

;Start of I/O address space for given
;VAXBI bus
+ I08NN$AL NODESP
;Offset to window space
+ I08NN$AL=NDSPER * VAXBI-node-ID-of-DWBUA ;Offset to given VAXBI node window space
+ UNIBUS-address-of-device-CSR
;Offset to device CSR
For VAX 82x0/83x0:
I08SS$AL NODESP
;Start of window space
+ I08SS$AL=NDSPER * VAXBI-node-ID-of-DWBUA ;Offset to given VAXBI node window space
+ UNIBUS-address-of-device-CSR
;Offset to device CSR
For VAX 6000 series:
I09CC$AL IOBASE

+ I09CC$_BIWINDOW
+ XMI-node-ID-of-XBI * I09CC$C PERXBI
+ I09CC$C_BIWSIZ * VAXBI-node-ID-of-DWMBA
+ UNIBUS-address-of-device-CSR

;Start of I/O address space
;Offset to node 0 window space
;Offset to given VAXBI bus
;Offset to given VAXBI node window space
;Offset to device CSR

For most VAX processors, the page frame number (PFN) of a physical
page in memory is contained in bits 9 through 29 of its physical address
(see Figure 19-1). Bit 29 of the address is clear to indicate a physical
memory address and set to indicate an address in 1/0 address space. Bits
0 through 8 specify the byte address within the page.

19-4

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.2 PFN Mapping

Figure 19-1

Format of a Physical Address

9 8

III

Page Frame Number

0
Byte

ZK-4845-GE

19.2

PFN Mapping
For a process to gain access from an outer access mode to I/O address
space or to any page of physical memory, it must map that page into its
virtual address space. When a VMS process maps a page by specifying its
page frame number, it completely bypasses VMS memory management and
creates its own window to the page. As a result, the protection functions
that VMS normally performs are not performed for PFN mapping:
•

No checks are performed to ensure that no other VMS processes are
mapped to the page and modifying it.

•

No reference count is maintained. A process can delete a global section
mapped by page frame numbers when other processes are still using
it; this is not the case for other types of global sections.

Modifying pages mapped by page frame numbers can have unpredictable
results and can adversely affect system operation, especially if the
operating system is also using these pages or accessing devices whose
registers are in the same pages. Because PFN-mapped pages are not
inherently protected from such modification, a process must have the
PFNMAP privilege to use this capability.
When used for PFN mapping, the Create and Map Section ($CRMPSC)
system service designates the specified page(s) as a global or private
section and maps the section into the requesting process's virtual address
space. The pages can be located anywhere in the VAX system's local
memory, in MA780 memory (if a multiport memory unit is connected to
the system), or in I/O address space.
The format and conventions for PFN mapping (that is, mapping a physical
page frame section) are similar to those for mapping a disk file section.
The $CRMPSC system service has the following general formats:
VAX MACRO Format
$CRMPSC

[inadr] [,retadr] [,acmode] [,flags] [,gsdnam] [,ident] [,relpag] [,chan] [,pagcnt] [,vbn] [,prot] [,pfc]

19-5

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.2 PFN Mapping

High-Level Language Format
SYS$CRMPSC ([inadr] [,retadr] [,acmode] [,flags] [,gsdnam] [,ident]
[,relpag] [,chan] [,pagcnt] [,vbn] [,prot] [,pfc])

The relpag, chan, and pfc arguments are not applicable to mapping by
page frame number. The inadr, retadr, acmode, gsdnam, ident, and
prot arguments have the same functions regardless of whether you specify
page frame number mapping. The VMS System Services Reference Manual
further describes these arguments.
The following arguments can have values specific to PFN mapping.
Arguments
[flags]
Mask defining the section type and characteristics. This mask is the
logical OR of the flag bits you want to set. The $SECDEF macro defines
symbolic names for the flag bits in the mask. The SEC$M_PFNMAP flag
bit must be set to indicate mapping by page frame number. The SEC$M_
PFNMAP flag setting identifies the memory for the section as starting at
the page frame number specified in the vbn argument and extending for
the number of pages specified in the pagcnt argument.
If appropriate, the following flags can also be set:
Flag

Description

SEC$M_GBL

Pages form a global section. The default is private section.

SEC$M_EXPREG

Pages are mapped into the first available space. By default,
pages are mapped into the range specified by the inadr
argument.

SEC$M_WRT

Pages form a read/write section. By default, pages form a
read-only section.

SEC$M_PERM

Pages are permanent. By default, pages are temporary.

SEC$M_SYSGBL

Pages form a system global section. By default, pages form a
group global section.

You must not set either the SEC$M_CRF (copy-on-reference) or the
SEC$M_DZRO (demand-zero) bit when mapping by page frame number.
[pagcnt]
Number of pages in the section; the value of this argument must not be
zero.
[vbn]
Page frame number of the first page to be mapped (as opposed to this
argument's normal usage identifying the starting virtual block number
(vbn) within a disk file). When you are mapping more than one page
with a single $CRMPSC system service request, the pages are physically
contiguous starting with the specified page.

19-6

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.2 PFN Mapping

19.2.1

Notes on PFN Mapping
The following considerations apply to PFN mapping.
1

An error in mapping UNIBUS or Q22 bus adapter address space or

a reference to a nonexistent bus address causes a UNIBUS adapter
error. However, this error does not cause a system failure (except on
a VAX 85x0/8700/88x0, VAX-11/750, or VAX-11/730 system, where a
machine check will occur). Rather, an entry is made in the system
error log file and the user program continues executing (probably with
erroneous results). The process is not notified of the UNIBUS adapter
error.
2

On systems where a UNIBUS power failure can occur without causing
a system failure, a user process receives a machine check exception,
if it is using process space mapping when accessing UNIBUS or Q22
bus 1/0 address space during the failure. To survive this exception,
the process must have a condition handler to deal with machine check
exceptions. The VMS System Services Reference Manual discusses
condition handlers in detail.

During recovery from a power failure, the processor spends a
considerable amount of time (perhaps 10 to 60 milliseconds) at IPL 31.
This action blocks user processes from executing during the recovery.

When a process requests deletion of a PFN-mapped page, VMS will
wait until there is no direct 1/0 outstanding for the process before
deleting the page. This is because no reference count is maintained
for PFN-mapped pages. (For example, VMS cannot determine
whether outstanding direct 1/0 is for the PFN-mapped page or
not.) Applications using devices that have direct 1/0 perpetually
outstanding, such as the DR32, must not delete PFN-mapped pages
because this will cause the process to hang in the MWAIT state.

Once you have mapped to 1/0 address space, you can read data from
a device data buffer register, because the device registers are now
addressable as part of your process's virtual memory. The UNIBUS
adapter performs the actual mapping of VAX virtual addresses to the 18bit UNIBUS addresses that correspond to device registers. Likewise, the
MicroVAX systems perform the mapping of virtual addresses to 22-bit Q22
bus addresses that correspond to device registers.
See Section 5.2 for a list of restrictions that apply to instruction references
to device register address space.

19.3

Connecting to an Interrupt Vector
You can use the $QIO system service with an appropriate function code
to connect to a device interrupt vector and to specify a user-supplied
interrupt service routine that VMS executes when the designated device
interrupts. Connecting to a device interrupt vector allows you to do the
following:
•

Respond to an interrupt within a short time

19-7

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.3 Connecting to an Interrupt Vector

•

Preempt other system processing to handle a real-time event, for
example, a clock interrupt

•

Buffer data from a device in real time and return· the data to the
process at a later time

•

Set an event flag or queue an AST to your process after receiving the
interrupt

An interrupt service routine specified in your process allows it to perform
some of the functions normally performed by a device driver. The connectto-interrupt facility, with its VMS-supplied driver (CONINTERR), thus
allows you to avoid writing a full device driver and loading it into the
operating system.
If you must access device registers from user mode (that is, from the

main program or a user-mode AST procedure), you must use the Create
and Map Section ($CRMPSC) system service to map 1/0 address space,
specifying page frame number (PFN) mapping. The service creates a
global or private section that maps the specified 1/0 pages into your
process's virtual address space with suitable protection. The process can
then gain access to 1/0 address space using perprocess virtual addresses
(see Section 19.1 for additional discussion).
You do not need to map 1/0 address space to access device registers from
any of the following routines specified in the $QIO call connecting to an
interrupt vector:

•
•
•
•

Unit initialization routine
Start-1/0 routine
Interrupt service routine
Cancel-1/0 routine

These routines execute in system context and thus can access UNIBUS
or Q22 bus 1/0 address space, which is mapped as part of system address
space.

19.3.1

Performing the Connect-to-Interrupt
Connecting to a device interrupt vector allows your program to receive
notification of an interrupt from a designated device by any combination of
the following means:
•

By execution of a user-supplied interrupt service routine

•

By the setting of an event flag

•

By execution of an AST procedure that gains control in process context

In addition, you can specify a cancel-I/O routine that is executed when the
process disconnects from the interrupt vector or is deleted.

19-8

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.3 Connecting to an Interrupt Vector

Before your program can run, the system manager must have performed
the following actions at system generation time:
•

Specify the REALTIME_SPTS system parameter, reserving system
page table entries for use by real-time processes. These system pagetable entries are used to map process-specified buffers in system
address space (see the pl argument description in Section 19.3.2). The
REALTIME_SPTS parameter value must be greater than or equal
to the number of pages in buffers specified by processes connected to
interrupt vectors.

•

Configure the real-time device by issuing a CONNECT command to the
System Generation Utility. This command names the device; its vector,
register, and adapter addresses; and a skeletal driver (CONINTERR)
for the device. (See the description of the CONNECT command in
Section 12.2.2 and in the VMS System Generation Utility Manual.)

At run time the process calls the $ASSIGN system service to associate
a channel with the device. To connect to the device interrupt vector, the
process issues a $QIO call specifying the 10$_CONINTREAD or 10$_
CONINTWRITE function code and as many of the following items as are
appropriate:
•

An interrupt service routine to be executed when the device generates
an interrupt.

•

A unit initialization routine.

•

A start-1/0 routine.

•

A cancel-1/0 routine.

•

A buffer containing the code to be executed in system context, data
(that is, the previously-listed routines), or both.

•

An AST procedure to execute, an event flag to be set after the interrupt
service routine (if any) completes, or both. (If an AST procedure is
specified, an AST parameter may also be specified.)

A nonprivileged process (that is, lacking the CMKRNL privilege) can also
connect to an interrupt vector, but it can only specify an AST procedure
to be executed or an event flag to be set (or both) when an interrupt is
generated. The process can also map the page in UNIBUS or Q22bus1/0
address space containing the device registers (see Section 19.2).

19.3.2 $QIO Connect-to-Interrupt Request to Driver
The format of the $QIO system service to connect to an interrupt vector
follows. This explanation is limited to connecting to an interrupt vector.
For a detailed description of the $QIO system service, see the VMS System
Services Reference Manual.
VAX MACRO Format
$010

[efn] ,[chan] ,func [,iosb] [,astadr] [,astprm] [,p1] [,p2] [,p3] [,p4] [,p5] [,p6]

19-9

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.3 Connecting to an Interrupt Vector

High-Level Language Format
SYS$QIO ([efn] ,[chan] ,func [,iosb] [,astadr] [,astprm]
[,p1] [,p2] [,p3] [,p4] [,p5] [,p6])

Arguments
[efn]
[chan]
[iosb]
[astadr]
[astprm]

These arguments apply to the $QIO system service completion, not to
device interrupt actions. For an explanation of these arguments, see
the description of the $QIO system service in the VMS System Services
Reference Manual.
func

Function code of 10$_CONINTREAD or 10$_CONINTWRITE. The 10$_
CONINTWRITE function code allows locations in the buffer pointed to by
the pl argument to be modified; the 10$_CONINTREAD function code
makes the buffer contents read-only.
[p1]

Address of a descriptor for the buffer containing code and/or data. The first
longword records the number of bytes in the buffer; the second longword
records the address of the buffer. The buffer size must not exceed 65,535
bytes.
[p2]

Address of an entry point list. The list consists of four longwords that
contain offsets into the buffer (specified in the pl argument) of the entry
points of process-specified routines. These longwords and their contents 1
are as follows:
Symbol

Meaning

CIN$L_INIDEV

Offset to unit initialization routine

CIN$L_START

Offset to start-1/0 routine

CIN$L_ISR

Offset to interrupt service routine

CIN$L_CANCEL

Offset to cancel-1/0 routine

[p3]

Longword containing flags and an optional event flag number specification.
The low-order word contains the inclusive-OR of flags describing options
to the connect-to-interrupt facility. The flags and their meanings are as
follows:

The listed symbols are defined by the $CINDEF macro located in the library SYS$LIBRARY:LIB.MLB.

19-10

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.3 Connecting to an Interrupt Vector

Flag

Meaning

CIN$M_EFN

Set event flag on interrupt.

CIN$M_USECAL

Use CALL interface to process-specified routines (default is
JSB interface).

CIN$M_REPEAT

Leave process connected to the interrupt vector until the
connection is canceled.

CIN$M_INIDEV

Process-specified unit initialization routine is in the buffer
specified in the p1 argument.

CIN$M_START

Process-specified start-1/0 routine is in buffer.

CIN$M_ISR

Process-specified interrupt service routine is in buffer.

CIN$M_CANCEL

Process-specified cancel-1/0 routine is in buffer.

The high-order word specifies the number of the event flag to be set when
an interrupt occurs. This number is expressed as an offset to CIN$V_
EFNUM.
For example, to specify that your interrupt service routine is in the buffer
and to set event flag 4, code p3 as follows:
P3 = <CIN$M_ISR!CIN$M_EFN!4@CIN$V_EFNUM>

See note 3 in the following description for additional information on these
flags.
[p4]

Address of the entry mask of an AST procedure to be called as the result
of an interrupt (see Section 19.3.5).
[p5]

AST parameter to be passed to the AST procedure (used as the AST
parameter only if the process-supplied interrupt service routine does not
overwrite the value).
[p6]

Number of AST control blocks to preallocate in anticipation of fast,
recurrent interrupts from the device.
Condition Values Returned
SS$_NORMAL

System service successfully completed.

SS$_ACCVIO

The caller does not have the appropriate access to the buffer
specified in the p1 argument or to the entry point list specified
in the p2 argument.

SS$_8ADPARAM

The size of the buffer specified in the p1 argument exceeds
65,535 bytes, or the number of preallocated AST control
blocks specified in the P6 argument exceeds 65,535.

SS$_DISCONNECT

A connection is already outstanding for the device, or a
condition described as follows in note 2b has occurred.

SS$_EXQUOTA

The process has exceeded its direct 1/0 limit quota or its AST
limit quota.

19-11

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.3 Connecting to an Interrupt Vector

SS$_1LLEFC

An illegal event flag number was specified.

SS$_1NSFMEM

Insufficient system dynamic memory is available to complete
the system service.

SS$_1NSFSPTS

Insufficient system page-table entries are available to double
map the process buffer. (The value of the REALTIME_SPTS
SYSGEN parameter must be increased.)

SS$_NOPRIV

The process does not have the CMKRNL privilege. This
privilege is only required if the user specifies a buffer to be
used by the process and the process-specified kernel-mode
routines.

SS$_UNASEFC

The process is not associated with the cluster containing the
specified event flag.

Privilege Restrictions

The connect-to-interrupt $QIO call does not require privileges if no shared
buffer is specified. If the request specifies a buffer descriptor argument
(that is, pl), the process must have the CMKRNL privilege.
Resources Required/Returned

A connect-to-interrupt request updates the process quota values as follows:
•

Subtracts the number of preallocated AST control blocks in the p6
argument from the number of outstanding ASTs remaining for the
process (ASTCNT)

•

Subtracts 1 (for the $QIO) from the direct 1/0 count (DIOCNT)

Notes
1

After the $QI0 call is issued, the operation is not completed until the
process or the connect-to-interrupt driver cancels 1/0 on the channel.

The connect-to-interrupt driver can cancel 1/0 on the channel for a
number of reasons, including the following:

a. The driver cannot set the specified event flag, perhaps because
the process disassociated from the common event flag cluster after
requesting that a flag in that cluster be set.
b. The driver cannot reallocate AST control blocks quickly enough.

This condition can occur because not enough AST control blocks
(p6 argument) were specified, not enough pool space is available
for the requested i\ST control blocks, or the process ASTCNT quota
is exhausted.

c. The driver cannot queue the AST to the process.
3

If no event flag setting was requested in the p3 argument and if no
AST procedure was specified in the p4 argument, p6 is ignored and

no AST control blocks are preallocated. If you requested that an event
flag be set or specified an AST procedure, but did not preallocate
any AST control blocks (that is, p6 is zero), one AST control block is
preallocated automatically, because the system needs one control block
to set any event flag or to deliver any ASTs.

19-12

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.3 Connecting to an Interrupt Vector

If you request an event flag and/or an AST procedure and if you

preallocate any AST control blocks, the CIN$M_REPEAT bit is set
automatically in the longword specified in the p3 argument. Thus,
as long as you preallocate any AST control blocks, your process will
automatically remain connected to the interrupt vector to receive
repeated interrupts until the process is disconnected from the interrupt
vector.
If the CIN$M_REPEAT flag is not set, the process is disconnected from

the interrupt vector after the first successful interrupt, and a status
code of SS$_NORMAL is returned.

19.3.3 The Connect-to-Interrupt Driver (CONINTERR.EXE)
The VMS connect-to-interrupt driver (CONINTERR) provides a driver
interface to the system on behalf of the process. CONINTERR connects
the process to the device by executing the following steps:
1

Validates the arguments to the $QIO system service call, such as the
accessibility of the buffer specified in argument pl to the process, and
the number of the event flag optionally specified in the efn argument.

Locks the physical pages of the buffer into physical memory, and
maps the pages using system page-table entries allocated by the
REALTIME_SPTS SYSGEN parameter.

Constructs argument lists and calling interfaces to the processspecified routines by storing values in the device's unit control block
(UCB).

Allocates the specified number of AST control blocks to the process,
and inserts each block in a queue in the device's UCB.

Transfers control to VMS to queue the connect-to-interrupt I/O packet
to the CONINTERR start-I/0 routine.

When the CONINTERR start-I/0 routine gains control, it passes control,
by means of a user-specified JSB or CALLS instruction interface, to the
process-specified start-I/0 routine. This routine usually initializes the
device and may also start device activity.
When the device generates an interrupt, the CONINTERR interrupt
service routine gains control. This routine transfers control to the processsupplied interrupt service routine.

19.3.4

Process-Specified Routines
Any routines that the process specifies in the connect-to-interrupt call,
with the exception of the AST procedure, are double-mapped, once in
process address space and once in system address space. Each routine
executes in kernel mode at an appropriate IPL, as listed in the following
table.

19-13

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.3 Connecting to an Interrupt Vector

Routine

IPL

Unit initialization routine (after power
recovery)

IPL$_POWER (IPL 31)

Start-110 routine

IPL$_QUEUEAST (IPL 6)

Interrupt service routine

Device IPL

Cancel-1/0 routine

IPL$_QUEUEAST (IPL 6)

The process must have CMKRNL privilege. Each routine must
•

Be position independent

•

Follow the rules for accessing I/O address space as described in
Section 5.2

•

Access only data within the buffer or nonpageable locations in system
address space

•

Perform any necessary synchronization of access to data in the shared
buffer

•

Save any registers it uses (unless otherwise noted in the remaining
sections of this chapter)

•

Exit properly

•

Not incur exceptions

•

Not perform lengthy processing

•

Not dispatch to code outside the buffer specified in the pl argument to
the $QIO system service call

Only VAX MACRO or VAX BLISS-32 should be used to code processspecified routines in system address space or any references to 1/0 address
space. There is no assurance that the code generated by compilers for
other languages will satisfy all the constraints described in this section.
The following constraints apply to process-specified routines in system
address space (that is, in the buffer specified in the pl argument to the
$QIO call that establishes the connection to the interrupt vector):
•

The compiler must generate position-independent code for the routines.

•

The generated code and data must be contiguous in virtual address
space.

•

No calls can be made to any procedure outside the buffer. (This
restriction includes calls to routines in the VAX Run-Time Library.)

•

For any references to I/O address space, the generated code must
follow the rules for accessing I/O address space discussed in
Section 5.2.

You can find additional help for writing a start-I/0 routine, interrupt
service routine, unit initialization routine, or cancel-I/O routine in Sections
8, 9, 11.1, and 11.2, respectively. Additionally, you may find useful the
several program examples of connecting to an interrupt vector with which
this chapter concludes.
19-14

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.3 Connecting to an Interrupt Vector

19.3.4.1

Unit Initialization Routine

During recovery from a power failure, VMS calls the CONINTERR unit
initialization routine. This routine marks the device as on line in the
UCB$L_STS field, stores the UCB address in the IDB$L_OWNER field,
and then transfers control to the process-specified unit initialization
routine. The process-specified routine executes in system context at IPL$_
POWER (IPL 31). If the process specified a JSB interface, the process unit
initialization routine gains control with the following register settings:
RO

Address of UCB

Address of CSR

Address of IDB

Address of DOB

Address of CRB

If the process specified a CALL interface, the process unit initialization

routine gains control with an argument list pointed to by AP:
OO(AP)

Argument count of 5

04(AP)

Address of CSR

08(AP)

Address of IDB

12(AP)

Address of DOB

16(AP)

Address of CRB

20(AP)

Address of UCB

The process-specified unit initialization routine may initialize device
registers. It must follow these conventions:
•

Not lower IPL nor obtain any spin locks

•

Save and restore all registers it uses, other than RO through R3

•

Restore the stack to its original state before exiting

•

Exit with an RSB instruction (for a JSB interface) or a RET instruction
(for a CALL interface)

For more on writing a unit initialization routine, see Section 11.1.
19.3.4.2

Start-1/0 Routine

The process-specified start-I/0 routine executes in process context in
system space at IPL$_QUEUEAST (IPL 6), holding the QUEUEAST
fork lock in a VMS multiprocessing environment. It is entered from the
CONINTERR start-I/0 routine.
If the process specified a JSB interface, the process start-I/O routine gains
control with the following register settings:
R2

Address of counted argument list

Address of IRP

Address of UCB

19-15

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.3 Connecting to an Interrupt Vector

If the process specified a CALL interface, the process start-1/0 routine
gains control with an argument list pointed to by AP:
OO(AP)

Argument count of 4

04(AP)

System-mapped address of process buffer

08(AP)

Address of IRP

12(AP)

System-mapped address of the device's CSR

16(AP)

Address of UCB

The process-specified start-I/0 routine may set up device registers. It must
follow these conventions:
•

Maintain an IPL equal to or higher than IPL$_QUEUEAST (IPL
6), and exit at IPL 6. (If it raises IPL, the routine should first save
the current IPL on the stack for later use in restoring IPL.) In a
VMS multiprocessing system, the process-specified start-1/0 routine
must suitably synchronize any access of device registers with the
process-specified interrupt service routine. To do so, each routine must
obtain the appropriate device lock, using the VMS-supplied macro
DEVICELOCK. Before exiting, each routine releases ownership of the
device lock using the DEVICEUNLOCK macro. (See the discussion of
these macros in the VMS Device Support Reference Manual.)

•

Save and restore all registers it uses, other than RO through R4.

•

Restore the stack to its original state before exiting.

•

Exit with an RSB instruction (for a JSB interface) or a RET instruction
(for a CALL interface).

For additional information on writing a start-I/O routine, see Chapter 8.
19.3.4.3

Interrupt Service Routine

A process-specified interrupt service routine is entered when an interrupt
from the device occurs. This routine executes in system context at device
IPL.
If the process specified a JSB interface, the process interrupt service
routine gains control with the following register settings:
R2

Address of counted argument list

Address of IDB

Address of UCB

If the process specified a CALL interface, the process interrupt service
routine gains control with an argument list pointed to by AP:

19-16

OO(AP)

Argument count of 5

04(AP)

System-mapped address of process buffer

08(AP)

Address of AST parameter

12(AP)

System-mapped address of the device's CSR

16(AP)

Address of IDB

20(AP)

Address of UCB

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.3 Connecting to an Interrupt Vector

The process-specified interrupt service routine usually performs one or
more of the following steps:
1

Copies the contents of device registers into the shared buffer or the
AST parameter

Writes to a device register to clear the interrupt condition, if such an
operation is required for the device

Restarts the device, or returns an offset, a byte count, or actual data
as an AST parameter

Returns an interrupt status to the VMS connect-to-interrupt driver
(CONINTERR)

The process-specified interrupt service routine, like those supplied by
VMS, has the following characteristics:
•

It is mapped in system address space.

•

It executes on the interrupt stack.

•

It executes at the IPL of the device that requested the interrupt.

The routine must follow these conventions:
•

Maintain an IPL equal to or higher than device IPL. (If it raises
IPL, the routine should first save the current IPL on the stack for
later use in restoring IPL.) In a VMS multiprocessing system, if the
process-specified start-110 routine or cancel-1/0 routine accesses device
registers or UCB fields also accessed by the process-specified interrupt
service routine, the routines must suitably synchronize. To do so,
each routine must obtain the appropriate device lock, using the VMSsupplied macro DEVICELOCK. Before exiting, each routine releases
ownership of the device lock using the DEVICEUNLOCK macro. (See
the discussion of these macros in the VMS Device Support Reference
Manual.)

•

Save and restore all registers it uses, other than RO through R4.

•

Restore the stack to its original state before exiting.

•

Set or clear the low bit of RO, as a status value, before exiting. The
status values are as follows:

•

Bit 0 of RO

Meaning

Clear

Dismiss the interrupt. The process is not notified of the
interrupt.

Set

Set the event flag if CIN$M_EFN bit is set in the p3 argument
to the $010 system service call, and queue the AST if p4
specifies an AST procedure.

Return to the CONINTERR interrupt service routine with a RET
instruction (for a CALL interface) or RSB instruction (for a JSB
interface).

19-17

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.3 Connecting to an Interrupt Vector

Depending on the interrupt status returned in RO, the CONINTERR
interrupt service routine queues a fork process to run at a lower IPL
(IPL$_QUEUEAST). Then the interrupt service routine exits from the
interrupt with an REI instruction. When the CONINTERR fork process
gains control, it queues an AST or posts an event flag to the process (or
both).
For additional information on writing an interrupt service routine, see
Chapter 9.
19.3.4.4

Cancel-1/0 Routine

When the user process issues a cancel-I/O request for a device connected to
the process, the CONINTERR cancel-I/O routine first checks to determine
whether the process can indeed cancel I/O for this device. If it can, the
CONINTERR cancel-I/O routine transfers control to the process-specified
cancel-I/O routine. This routine executes in system context at IPL 8 (fork
IPL).
If the process specified a JSB interface, the process cancel-I/O routine

gains control with the following register settings:
R2

Negated value of channel index number

Address of current IRP

Address of PCB for process canceling the 1/0

Address of UCB

If the process specified a CALL interface, the process cancel-I/O routine
gains control with an argument list pointed to by AP:
OO(AP)

Argument list count of 4

04(AP)

Negated value of channel index number

OS(AP)

Address of current IRP

12(AP)

Address of PCB for process canceling the 1/0

16(AP)

Address of UCB

The process-specified cancel-I/O routine may clear device registers and
set the UCB$V_CANCEL bit in UCB$L_STS. It must follow these
conventions:

19-18

•

Maintain an IPL equal to or higher than IPL$_QUEUEAST (IPL
6), and exit at IPL 6. (If it raises IPL, the routine should first save
the current IPL on the stack for later use in restoring IPL.) In a
VMS multiprocessing system, if the process-specified cancel-I/O
routine accesses device registers or UCB fields also accessed by the
process-specified interrupt service routine, the routines must suitably
synchronize. To do so, each routine must obtain the appropriate
device lock, using the VMS-supplied macro DEVICELOCK. Before
exiting, each routine releases ownership of the device lock using the
DEVICEUNLOCK macro. (See the discussion of these macros in the
VMS Device Support Reference Manual.)

•

Save and restore all registers it uses, other than RO through R3.

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.3 Connecting to an Interrupt Vector

•

Place a completion status in RO and Rl. VMS places the values in
these registers in the I/O status block associated with the connect-tointerrupt $QIO call.

•

Restore the stack to its original state before exiting.

•

Exit with an RSB instruction (for a JSB interface) or a RET instruction
(for a CALL interface).

For additional information on writing a cancel-I/O routine, see
Section 11.2.

19.3.5

AST Procedure
The AST procedure that you specify in the call to the $QIO system service
for the connect-to-interrupt operation gains control in process context.
This routine usually performs one or more of the following steps:

19.4

Reads or writes device registers if the process mapped I/O address
space.

Interprets data. Use caution, however, because any processing done
by the AST procedure can be interrupted by a device interrupt, which
might store more data or modify the buffer's contents.

Calls the Cancel I/O on Channel ($CANCEL) system service to
disconnect the process from the interrupt. Once the process is
completely disconnected, the CONINTERR driver clears all interrupts
for the driver.

Real-Time Applications Examples
To understand how the connect-to-interrupt facility is useful for
programming real-time devices, consider devices used in three types of
real-time applications:
1

Asynchronous event reporting without data-devices that generate
an interrupt as the result of an external event not initiated by a
programmed request.

Program-driven data collection-devices that generate an interrupt as
the result of a programmed request, and make the result of the request
available as data in a device register at the time of the interrupt.

Asynchronous event reporting with data-one device triggers another
device by generating an interrupt that causes a programmed request
to be sent to the other device, which in turn generates an interrupt.

Examples of these three types of real-time applications and models of
programs to handle the devices follow.

Note: The configurations described in the examples in this section are
not officially supported; Digital does not provide device driver,
UETP, or diagnostic support for certain devices mentioned. (In
fact, Digital has officially retired the -K series models
(ADll-K and AMll-K AID Converter). The examples are provided
19-19

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.4 Real-Time Applications Examples

merely as possible models for users who wish to design real-time
applications using unsupported devices or configurations.
The files in the SYS$EXAMPLES directory whose names begin with
"LABIO" illustrate an application using the connect-to-interrupt technique.
Included is a program example illustrating data definitions and coding
used to connect to a device interrupt vector.

19.4.1

Example 1: KW11-W Watchdog Timer
This type of device reports asynchronous external events: it generates an
interrupt as a result of an external event not initiated by a programmed
request. The only data of interest to be passed to the user process is the
occurrence of the external event. Such devices include contact and/or
solid state interrupts, and clocks or counters. The program may need to
activate clock and counter devices by means of a programmed request, but
any subsequent interrupts are the result of external events only.
In this example, a dual-processor system uses two KWll-W watchdog
timers connected back-to-back to monitor CPU failures. Each processor
must arm its timer at regular intervals to prevent the timer from
operating a relay that outputs an alarm signal. The alarm output of
each timer is connected to the receive input of the other watchdog. If
processor A fails and its watchdog times out, the alarm output generates
an interrupt on processor B by way of the second watchdog timer.
The watchdog control program on each processor simply addresses the
timer at regular intervals. If the interval passes without the timer
being addressed, the timer operates an output relay that generates an
interrupt to the second CPU. For this example, assume that the interval is
5 seconds. (Section 19.4.3 contains an example that addresses the problem
of a much smaller time interval.)
The watchdog control program on processor A executes as follows:

19-20

Assigns a channel to the device

Calls the $CRMPSC system service to map to the 1/0 page in order to
address the device registers

Issues a connect-to-interrupt $QIO request to connect the program
to the watchdog timer for processor B; specifies the addresses of an
interrupt service routine and an AST procedure

Writes a value to a device register to start the timer

Calls the $SETIMR system service to request that an event flag be set
after a specified interval (for example, 4 seconds)

Calls the $WAITFR system service to wait for the event flag

When the event flag is set, writes a value to a device register to reset
the timer

Loops to step 5

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.4 Real-Time Applications Examples

The same control program runs on processor B except that it connects to
the watchdog timer for processor A. If either processor fails, the watchdog
timer generates an interrupt on the other processor.
The standby processor that receives the interrupt gains control in the VMS
connect-to-interrupt driver (CONINTERR), which calls a process-supplied
interrupt service routine (defined in step 3) that handles the interrupt as
follows:
1

Sets the KWll-W switch relay register to clear the timer interrupt
condition

Sets a status flag that will cause an AST to be delivered to the control
program that connected to the interrupt

Returns to CONINTERR

CONINTERR completes the interrupt handling as follows:
1

Schedules a fork process at a lower IPL (IPL$_QUEUEAST). This fork
process, when it gains control, will queue an AST to the user program.

Executes an REI instruction to return from the interrupt.

The timer control program on the standby processor regains control in an
AST procedure which responds to the other processor's failure by switching
over and assuming control of the other processor's tasks (or whatever is
appropriate).

19.4.2

Example 2: AD11-K, AM11-K A/D Converter with Multiplexer
Connected to the UNIBUS
This type of device provides program-driven data collection: it generates
an interrupt as the result of a programmed request to the device, and
makes the result of the request available as data in a device register.
Typical devices include AID converters and Digital I/O registers.
The data collection operation is usually repetitive for such applications.
Therefore, the interrupt service routine must be capable of buffering data
from the device in order to ensure that no data is lost because of the highspeed data transfer rate. A typical buffer size for this sampling technique
might be 32 16-bit words.
In this example, a user program controls an ADll-K/AMll-K combination
that accepts analog data from thermocouples. The ADll-K converts
analog data to Digital data and returns the data in a device register.
Every 10 seconds, the program samples 16 to 32 out of 64 channels at
gain settings that may vary based on the thermocouple type and previous
samplings.
To collect data efficiently, the program buffers- data in a process-specified
interrupt service routine, and requests delivery of an AST to the user
process when all the requested channels have been sampled. To perform
variable sampling, the program passes parameters to the interrupt service
routine.

19-21

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.4 Real-Time Applications Examples

The program establishes a protocol to communicate between the program
and the interrupt service routine. The protocol defines a data area
shared by the main program, the interrupt service routine, and the AST
procedure. The data area contains parameters from the program and data
from the ADll-K. The data area is a 98-word array used as follows:
1

Elements 1 and 2 of the data area contain an index to the next buffer
location to be filled, and a count indicating the number of samplings
still to be taken. The main program initializes these values before
starting the device. The interrupt service routine reads and modifies
these values in the process of copying data and determining when to
stop sampling.

Elements 3 to 66 of the data area are reserved for interrupt service
routine parameters. Each pair of elements contains the number of a
channel and a gain value. The main program loads these parameters
before starting the device.

Elements 67 to 98 of the data area receive the data that the interrupt
service routine reads from the ADll-K data buffer register. The AST
routine later reads data from this part of the buffer.

The program sets up for the sampling as follows:
1

Assigns a channel to the device

Calls the $CRMPSC system service to map to the I/O page in order to
address the device registers

Initializes the data area by writing a 67 (the index to the next buffer
location to be filled) into element 1, and the number of samples to take
into element 2 of the data area; clears elements 3 through 98 of the
data area

Writes channel numbers and gain values into the parameter section of
the data area

Issues a connect-to-interrupt $QIO call to connect the process to the
AID converter; specifies the addresses of the area to be double-mapped,

an offset to the interrupt service routine, and an AST procedure
6

Sets the start and interrupt-enable bits in the ADll-K status register
to start the AID converter

Calls the $HIBER system service to place the process in a wait state

As soon as the ADll-K has converted the first sample, the device
generates an interrupt. CONINTERR.EXE calls the process-specified
interrupt service routine. This process-specified routine executes as
follows:

19-22

Computes the next location to be written in the buffer by reading the
first element in the data area

Reads 12 bits of data from the AID buffer register into the next location
in the buffer

Updates the buffer offset and count elements at the beginning of the
data area

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.4 Real-Time Applications Examples

If all requested samples have been collected, writes the address of the
data area into the AST parameter, sets a status flag that will cause
an AST to be delivered to the control program, and returns to the
CONINTERR routine

Otherwise, sets the start bit in a device register to restart the device
and returns to the CONINTERR routine with a status flag requesting
no AST delivery or event flag setting

Based on the interrupt status from the process-specified interrupt service
routine, the CONINTERR routine completes the interrupt processing by
queuing a fork process that will queue an AST to the user process. When
the process gains control in the AST procedure, it processes the samples in
the following steps:
1

Clears the interrupt-enable bit in the device status register

Examines the data collected in order to adjust channel selection and/or
gain values for the next sampling

Copies the data to a file

Reinitializes the data area

Calls the $SCHDWK system service to wake the process after a short
interval (for example, 10 seconds)

Returns

When the time interval elapses, the process regains control. The program
can then restart the sampling process by again setting the start and
interrupt-enable bits in the ADll-K status register.

19.4.3

Example 3: KW11-P Real-Time Clock and AD11-K Converter
Connected to the UNIBUS
This type of device reports asynchronous external events by collecting
data: one device triggers another device by generating an interrupt that
causes a programmed request to be sent to the other device, which in turn
generates an interrupt. A typical example is a clock-driven AID operation
for precise time sampling as required in signal processing. This processing
technique is often used in laboratories. The amount of data collected in
such a timed sampling might typically be 200 to 1000 16-bit words.
In this example, the main program sets up the real-time clock to generate
interrupts periodically. At regular intervals, the clock interrupt triggers
a programmed request for an AID conversion operation. The ADll-K
collects a sample, and interrupts the CPU with a "done" interrupt and 12
bits of data. The ADll-K interrupt service routine buffers the data and,
if the buffer is full, causes an AST to be delivered to the process. The
process, gaining control in an AST procedure, copies the buffered data to
another buffer or to disk.

19-23

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.4 Real-Time Applications Examples

Programming these device functions is slightly more complicated than
the previous example. The main program must specify a large buffer to
be used in ring fashion to guarantee that data is not lost between clockdriven samplings. In addition, the program must connect to two device
interrupts-one for the clock and one for the AID converter.
The protocol used by the main program, the interrupt service routine,
and the AST procedure is similar to the previous example. The data
area is larger: 4K words of buffer area follow the parameter area. The
AID converter interrupt service routine and the AST procedure treat the
4K-word buffer as four buffer sections of lK words per section. The first
element in each lK buffer section is a flag indicating whether the section
is in use. The AST resets the flag value after copying the contents of
the buffer. The interrupt service routine uses a buffer section only if the
section's flag value indicates that the buffer has been emptied.
The main program starts the sampling with the following steps:
1

Assigns channels to the clock and to the AID converter.

Calls the $CRMPSC system service to map to the I/O page in order to
address the device registers.

Initializes the data buffer by writing a 67 (the index to the next buffer
location to be filled) into element 1, and the number of samples to take
into element 2 of the data area; clears elements 3 through 4096 of the
data area; flags each page of the buffer as available.

Writes channel numbers and gain values into the parameter segments
of the data area.

Issues a connect-to-interrupt $QIO call to connect the process to the
clock, and specifies the address of an interrupt service routine.

Issues a connect-to-interrupt $QIO call to connect the process to
the AID converter; and specifies the addresses of the area to be
double mapped, an offset to the interrupt service routine and an
AST procedure.

Sets the sampling interval by writing a 16-bit value into the KWll-P
count set buffer register.

Starts the clock by setting the run, mode, rate selection, and interruptenable bits in the KWll-P control and status register. Setting the
mode bit causes repeated interrupts generated at a rate specified in
the time interval.

Calls the $HIBER system service to place the process in a wait state.

The clock interrupts when zero (underflow) occurs during a countdown
from the preset interval count. The VMS CONINTERR routine calls the
process-specified clock interrupt service routine. This process-specified
routine starts the AID conversion as follows:

19-24

Starts the AID converter by setting the start and interrupt-enable bits
in the ADll-K status register

Sets interrupt status that prevents AST delivery or event flag setting
as a result of this interrupt

Mapping to 1/0 Space and the Connect-to-Interrupt Facility
19.4 Real-Time Applications Examples

Returns to CONINTERR

Starting the AID converter results in an interrupt from the ADll-K, and
control passes, by way of CONINTERR, to the ADll-K interrupt service
routine. This routine executes as follows:
1

If this sample is the first sample for a new buffer (indicated by a flag in

the data area), the routine moves to the next buffer section (branching
to error handling if the buffer is still full), and sets up the first two
elements of the data area to indicate the buffer section to be written
next. Then it sets the flag at the start of the new buffer section and
sets a flag in the data area to indicate that sampling is occurring.
2

The routine computes the next location to be written in the buffer by
reading the first location in the data area.

The routine reads 12 bits of data from the AID buffer register into the
next location in the buffer.

The routine updates the buffer offset and count values in the data
area.

If this sample fills the data sector, the routine writes the offset of
the filled sector from the start of the 4K-word buffer into the AST
parameter, sets a status flag that will cause an AST to be delivered to
the control program, and sets a flag indicating that a new data section
is to be started.

The routine returns to CONINTERR.

The AST procedure copies and fills the next buffer section with zeros to
indicate that the section is again available to the interrupt service routine.
When the next clock interrupt occurs, the data can be written to the next
buffer section, even if the AST routine has not yet emptied the previous
buffer section.

19-25

VMS Driver Template

This appendix lists the contents of the VMS driver template. The code in
this template can serve as the starting point for a new UNIBUS or Q22
bus device driver. You can obtain a machine-readable copy of this driver
from SYS$EXAMPLES:TDRIVER.MAR.
. TITLE
. IDENT

TDRIVER - VAX/VMS TEMPLATE DRIVER
'X-3'

;****************************************************************************
;*
*
;* COPYRIGHT (c) 1978, 1980, 1982, 1984 BY
*
;* DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASSACHUSETTS.
*
;* ALL RIGHTS RESERVED.
*
;*
*
;*
;*
;*

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY
TRANSFERRED.

;*
;*
;*

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT
CORPORATION.

;*
;*
;*

;*
;*

DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.

;*
;*
;*

*
*

*
*
*

*
*
*
*
*

*
*
*

;****************************************************************************
;++

FACILITY:
VAX/VMS Template Driver
ABSTRACT:
This module contains the outline of a driver:
Models of driver tables
Controller and unit initialization routines
An FDT routine
The start I/O routine
The interrupt service routine
The cancel I/O routine
The device register dump routine
AUTHOR:
S. Programmer

ll-Nov-1979

A-1

VMS Driver Template

REVISION HISTORY:
X-3

JHP003 J. Progranuner
5-0ct-1988
Changed all user symbols to use underscores instead of
dollar signs to avoid conflict with any symbols defined
by Digital. Added return status to unit initialization
routine.

X-2

JHP002 J. Progranuner
Add SMP support.

V02

JHPOOl J. Progranuner
2-Aug-1979
11:27
Remove BLBC instruction from CANCEL routine.

21-Aug-1987

V02-001 ROW0067 R. Progranuner
ll-Feb-1981
13:10
Add description of reason argument to CANCEL routine.
Correct references to channel index number .

. SBTTL

External and local symbol definitions

External symbols
$CANDEF
$CRBDEF
$DCDEF
$DDBDEF
$DEVDEF
$DYNDEF
$IDBDEF
$IODEF
$IPLDEF
$IRPDEF
$SSDEF
$UCBDEF
$VECDEF

Cancel reason codes
Channel request block
Device classes and types
Device data block
Device characteristics
Dynamic data structure definitions
Interrupt data block
I/O function codes
Hardware IPL definitions
I/0 request packet
System status codes
Unit control block
Interrupt vector block

Local symbols

Argument list (AP) offsets for device-dependent QIO parameters
Pl
P2
P3
P4
PS
P6

0
4
8

First QIO parameter
Second QIO parameter
Third QIO parameter
Fourth QIO parameter
Fifth QIO parameter
Sixth QIO parameter

12
16
20
Other constants

TD DEF BUFSIZ
TD_TIMEOUT_SEC
TD NUM REGS

1024
10
4

Default buffer size
10-second device timeout
Device has 4 registers

Definitions that follow the standard UCB fields

A-2

VMS Driver Template

$DEF
$DEF
$DEF
$DEF

$DEFINI UCB

Start of UCB definitions

.=UCB$K_LENGTH

Position at end of UCB
A sample word

UCB W TD WORD

- -

.BLKW

Device's CSR

UCB W TD STATUS

Device's word count register

UCB W TD WRDCNT

- -

UCB W TD BUFADR

- -

$DEF

UCB- W- TD - DATBUF

$DEF

UCB K TD UCBLEN

Device's buff er address
register
Device's data buffer register
Length of extended UCB

Bit positions for device-dependent status field in UCB
VIELD

Device status
First bit
Second bit

UCB,O,<<BIT_ZERO,,M>,<BIT_ONE,,M>,-

>
; End of UCB definitions

$DEFEND UCB

Device register off sets from CSR address
$DEFINI TD
$DEF

Start of status definitions

TD STATUS

Control/status
.BLKW

Bit positions for device control/status register
VIELD

TD STS,O,<<GO,,M>,<BITl, ,M>, <BIT2,,M>,<BIT3, ,M>, <XBA,2,M>,<INTEN,,M>,<READY,,M>,<BIT8,, M>, <BIT9,,M>,<BITlO,,M>,<BITll,,M>,<,1>,<ATTN,,M>,<NEX,,M>,<ERROR,,M>,-

Control/status register
Start device
Bit 1
Bit 2
Bit 3
Extended address bits
Enable interrupts
Device ready for command
Bit 8
Bit 9
Bit 10
Bit 11
Disregarded bit
Attention bit
Nonexistent memory flag
Error or external interrupt

>
$DEF
$DEF
$DEF

TD WRDCNT

Word count
.BLKW

.BLKW

TD BUFADR

Buff er address

TD DATBUF
$DEFEND TD

Data buff er
End of device register
definitions.

A-3

VMS Driver Template

.SBTTL

Standard tables

Driver prologue table
DP TAB
END=TD_END,ADAPTER=UBA,UCBSIZE=<UCB_K_TD UCBLEN>,NAME=TDDRIVER
DPT STORE INIT
DPT STORE UCB,UCB$B FLCK,B,SPL$C IOLOCK8
DPT STORE UCB,UCB$B-DIPL,B,22
DPT STORE UCB,UCB$L-DEVCHAR,L,<DEV$M IDV ! - DEV$M-ODV>
DPT STORE UCB~UCB$B DEVCLASS,B,DC$ SCOM
DPT=STORE UCB,UCB$W=DEVBUFSIZ,W,TD DEF BUFSIZ
DPT STORE REINIT
DPT STORE DDB,DDB$L DDT,D,TD$DDT
DPT STORE CRB,CRB$L=INTD+VEC$L_ISR,D,TD INTERRUPT
DPT_STORE CRB,CRB$L_INTD+VEC$L_INITIAL,D,TD_CONTROL_INIT
DPT_STORE CRB,CRB$L_INTD+VEC$L_UNITINIT,D,TD_UNIT_INIT
DPT STORE END

DPT-creation macro
End of driver label
Adapter type
Length of UCB
Driver name
Start of load
initialization table
Device FORK LOCK
Device interrupt IPL
Device characteristics
input device
output device
Sample device class
Default buffer size
Start of reload
initialization table
Address of DDT
Address of interrupt
service routine
Address of controller
initialization routine
Address of device
unit initialization
routine
End of initialization
tables

Driver dispatch table
DD TAB
DEVNAM=TD,START=TD_START,FUNCTB=TD_FUNCTABLE,CANCEL=TD_CANCEL,REGDMP=TD REG DUMP
Function decision table

A-4

DDT-creation macro
Name of device
Start I/O routine
FDT address
Cancel I/0 routine
Register dump routine

VMS Driver Template

TD FUNCTABLE:
FUNCTAB
<READVBLK,READLBLK,READPBLK,WRITEVBLK,WRITELBLK,WRITEPBLK,SETMODE,SETCHAR>
FUNCTAB
FUNCTAB +EXE$READ,<READVBLK,READLBLK,READPBLK>
FUNCTAB +EXE$WRITE,<WRITEVBLK,WRITELBLK,WRITEPBLK>
FUNCTAB +EXE$SETMODE,<SETCHAR,SETMODE>
.SBTTL

FDT for driver
Valid I/O functions
Read virtual
Read logical
Read physical
Write virtual
Write logical
Write physical
Set device mode
; Set device characteristics
No buffered functions
FDT read routine for
read virtual,
read logical,
and read physical block
FDT write routine for
write virtual,
write logical,
and write physical block
FDT set mode routine
set characteristics, and
set mode

TD_CONTROL_INIT, Controller initialization routine

;++
TD_CONTROL_INIT, Readies controller for I/O operations
Functional description:
The operating system calls this routine in 3 places:
at system startup
during driver loading and reloading
during recovery from a power failure
Inputs:
R4
RS
R6
RS

address
address
address
address

of the CSR
of the IDB
of the DDB
of the CRB

(controller status register)
(interrupt data block)
(device data block)
(channel request block)

Outputs:
The routine must preserve all registers except RO-R3.

TD CONTROL INIT:
RSB
.SBTTL

; Initialize controller
; Return
TD_UNIT_INIT, Unit initialization routine

A-5

VMS Driver Template

;++
TD_UNIT INIT, Readies unit for I/O operations
Functional description:
The operating system calls this routine after calling the
controller initialization routine:
at system startup
during driver loading
during recovery from a power failure
Inputs:
R4
RS

- address of the CSR (controller status register)
- address of the UCB (unit control block)

Outputs:
The routine must preserve all registers except RO-R3.

TD UNIT INIT:
BISW
MOVL

Initialize unit
#UCB$M_ONLINE, UCB$W STS(RS)
# SS$=NORMAL, RO

RSB
.SBTTL

Set unit online
VAXBI devices need to return success
if unit is properly configured.
Return

TD_FDT_ROUTINE, Sample FDT routine

;++
TD_FDT_ROUTINE, Sample FDT routine
Functional description:
T.B.S.
Inputs:
RO-R2
R3
R4
RS
R6
R7

R8
R9-Rll
AP

scratch registers
address of the IRP (I/O request packet)
address of the PCB (process control block)
address of the UCB (unit control block)
address of the CCB (channel control block)
bit number of the I/0 function code
address of the FDT table entry for this routine
scratch registers
address of the 1st function dependent QIO parameter

Outputs:
The routine must preserve all registers except RO-R2, and
R9-Rll.

TD FDT ROUTINE:
RSB
.SBTTL

A-6

Sample FDT routine
Return
TD_START, Start I/O routine

VMS Driver Template

;++
TD START - Start a transmit, receive, or set mode operation

Functional description:
T.B.S.
Inputs:
R3
RS

- address of the IRP (I/O request packet)
- address of the UCB (unit control block)

Outputs:
RO
Rl

- 1st longword of I/O status: contains status code and
number of bytes transferred
- 2nd longword of I/O status: device-dependent

The routine must preserve all registers except RO-R2 and R4.

TD START:
DEVICELOCK LOCKADDR=UCB$L DLCK(R5),SAVIPL=-(SP)

Process an I/O packet
Lock device access.
Save current IPL

WFIKPCH TD_TIMEOUT,#TD_TIMEOUT SEC
After a transfer completes successfully, return the number of bytes
transferred and a success status code.
IOFORK
INSV
MOVW

UCB$W_BCNT(R5),#16,U6,RO
#SS$_NORMAL,RO

Load number of bytes transferred into high word of RO.
Load a success code into RO.

Call I/O postprocessing.
COMPLETE IO:
REQCOM

Driver processing is finished.
Complete I/O.

Device timeout handling. Return an error status code.
TD TIMEOUT:
Timeout handling
Unlock device access
DEVICEUNLOCK LOCKADDR=UCB$L DLCK(R5),NEWIPL=#8,Lower IPL
Don't preserve RO
PRESERVE= NO
Return error status.
MOVZWL #SS$_TIMEOUT,RO
BSBB
COMPLETE IO
Call I/O postprocessing.
DEVICELOCK LOCKADDR=UCB$L_DLCK(R5),- ; Acquire device lock for exit
PRESERVE=NO
RSB
.SBTTL

TD_INTERRUPT, Interrupt service routine

A-7

VMS Driver Template

;++
TD_INTERRUPT, Analyzes interrupts, processes solicited interrupts
Functional description:
The sample code assumes either
that the driver is for a single-unit controller, and
that the unit initialization code has stored the
address of the UCB in the IDB; or
that the driver's start I/O routine acquired the
controller's channel with a REQPCHANL macro call, and
then invoked the WFIKPCH macro to keep the channel
while waiting for an interrupt.
Inputs:
O(SP)
4(SP)
8(SP)
12(SP)
16(SP)
20(SP)
24(SP)
28(SP)
32(SP)

- pointer to the address of the IDB (interrupt data
block)
- saved RO
- saved Rl
- saved R2
- saved R3
- saved R4
- saved RS
- saved PC
- saved PSL (processor status longword)

The IDB contains the CSR address and the UCB address.
Outputs:
The routine must preserve all registers except RO-RS.

TD INTERRUPT:
MOVL
ASSUME
ASSUME
MOVQ

@(SP)+,R4
IDB$L_CSR EQ 0
IDB$L OWNER EQ 4
IDB$L=CSR(R4),R4

DEVICELOCK LOCKADDR=UCB$L_DLCK(RS),
PRESERVE=NO,CONDITION=NOSETIPL
BBCC
#UCB$V_INT,UCB$W_STS (RS),UNSOL INTERRUPT

Service device interrupt
Get address of IDB and
remove pointer from stack.

Get address of device's CSR
Get address of device
owner's UCB.
Lock device access
Don't preserve RO
Don't bother setting IPL
If device does not expect
interrupt, dismiss it.

This is a solicited interrupt. Save
the contents of the device registers in the UCB.

A-8

VMS Driver Template

MOVW
MOVW
MOVW
MOVW

TD_STATUS(R4),UCB_W_TD_STATUS(R5)
TD_WRDCNT(R4),UCB_W_TD_WRDCNT(R5)
TD_BUFADR(R4),UCB_W_TD_BUFADR(R5)
TD_DATBUF(R4),UCB_W_TD_DATBUF(R5)

Otherwise, save all device
registers. First the CSR.
Save the word count register.
Save the buffer address
register.
Save the data buffer register.

Restore control to the main driver.
RESTORE DRIVER:
MOVL
UCB$L_FR3(R5),R3
JSB

@UCB$L_FPC(R5)

Jump to main driver code.
Restore driver's R3 (use a
MOVQ to restore R3-R4).
Call driver at interrupt
wait address.

Dismiss the interrupt.
UNSOL INTERRUPT:
; Dismiss unsolicited interrupt.
DEVICEUNLOCK LOCKADDR=UCB$L DLCK(RS),-; Unlock device access.
PRESERVE=NO
Don't bother preserving RO.
POPR
#AM<RO,Rl,R2,R3,R4,R5>
Restore RO-RS
REI
Return from interrupt.
.SBTTL

TD_CANCEL, Cancel I/O routine

;++

TD_CANCEL, Cancels an I/O operation in progress
Functional description:
This routine calls IOC$CANCELIO to set the cancel bit in the
UCB status longword if:
the device is busy,
the IRP's process ID matches the cancel process ID,
the IRP channel matches the cancel channel.
If IOC$CANCELIO sets the cancel bit, then this driver routine
does device-dependent cancel I/O fixups.
Inputs:
R2
R3
R4
R5
R8

- channel index number
- address of the current IRP (I/O request packet)
- address of the PCB (process control block) for the
process canceling I/O
- address of the UCB (unit control block)
- cancel reason code, one of:
CAN$C CANCEL
if called through $CANCEL system service
CAN$C=DASSGN
if called through $DASSGN or
$DALLOC system services
These reason codes are defined by the $CANDEF macro.

Outputs:
The routine must preserve all registers except RO-R3.
The routine may set the UCB$M_CANCEL bit in UCB$W_STS.

A-9

VMS Driver Template

TD CANCEL:
JSB
BBC

Cancel an I/O operation
Set cancel bit if appropriate.
If the cancel bit is not set,
just return.

G"IOC$CANCELIO
#UCB$V_CANCEL,UCB$W_STS(R5), 10$

Device-dependent cancel operations go next.

Finally, the return.
10$:
RSB
.SBTTL

; Return
TD_REG_DUMP, Device register dump routine

;++
TD_REG DUMP, Dumps the contents of device registers to a buffer
Functional description:
Writes the number of device registers, and their current
contents into a diagnostic or error buffer.
Inputs:
RO
R4
RS

- address of the output buffer
- address of the CSR (controller status register)
- address of the UCB (unit control block)

Outputs:
The routine must preserve all registers except Rl-R3.
The output buffer contains the current contents of the device
registers. RO contains the address of the next empty longword in
the output buffer.
;--

TD REG DUMP:
MOVZBL
MOVZWL
MOVZWL
MOVZWL
MOVZWL

#TD_NUM_REGS, (RO)+
UCB_W_TD_STATUS(R5),(RO)+
UCB_W_TD_WRDCNT(R5),(R0)+
UCB_W_TD_BUFADR(R5),(RO)+
UCB_W_TD_DATBUF(R5),(R0)+

RSB
.SBTTL

Dump device registers
Store device register count.
Store device status register.
Store word count register.
Store buffer address register.
Store data buffer register.
Return

TD_END, End of driver

;++
; Label that marks the end of the driver
TD END:

Last location in driver
.END

A-10

VMS SCSI Class Driver Template

This appendix lists the contents of the VMS SCSI class driver template.
The code in this template can serve as the starting point for a new thirdparty SCSI class driver. You can obtain a machine-readable copy of this
driver from SYS$EXAMPLES:SKDRIVER.MAR.
.TITLE
. !DENT
.LIST

SKDRIVER - VAX/VMS Sample SCSI Class Driver
'X-3'
MEB

;****************************************************************************

;*
;*
;*
;*
;*

;*
;*
;*

;*
;*

;*
;*
;*

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT
CORPORATION.

;*
;*

DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.

;*
;*

*
*

*
*
*

*
*

*
*
*

*
*

;****************************************************************************
;++
FACILITY:
VAX/VMS Sample SCSI Class Driver
ABSTRACT:
This module contains a sample SCSI class driver. This template
supports two modes of operation: either the SCSI command
packets are formatted in the application program (passthru mode) or
the SCSI command packets are formatted within the driver. In the
latter case, command processing and error recovery are implemented
within a third-party SCSI class driver derived from this driver.
Passthru mode is the method of access used by the generic SCSI
class driver (GKDRIVER) . GKDRIVER provides access to a SCSI device
from an application program. The QIO interface of the GKDRIVER
is fixed. However, third-party SCSI class drivers can define a
unique QIO interface. Third-party class drivers can have device
specific error recovery, log device errors and implement asynchronous event notification (AEN) . Third-party class drivers have
direct access to the SCSI Port Interface (SP!) routines, while

B-1

VMS SCSI Class Driver Template

using the passthru function provides access to SCSI without writing
a driver.
The code to perform the IO$ DIAGNOSE function is included in this
driver for informational purposes only. Typical third-party SCSI
class drivers do not require this function. If the IO$ DIAGNOSE
function is required, you should use the VMS-supported- SCSI
generic class driver (GKDRIVER) .
SKDRIVER supports three I/O functions:
IO$ AVAILABLE
IO$=DIAGNOSE
IO$_READLBLK

.SBTTL
.SBTTL
.SBTTL
.SBTTL

- Inquiry and Test Unit Ready sequence,
- Passthru function
- Return Inquiry data to user

+
+ SYMBOL DEFINITIONS

+
External symbol definitions

;+
; External symbols
;$CRBDEF
$DDBDEF
$DEVDEF
$EMBDEF
$DYNDEF
$FKBDEF
$IODEF
$IPLDEF
$IRPDEF
$PCBDEF
$PRVDEF
$SCDRPDEF
$SSDEF
$UCBDEF
$VECDEF

Channel request block
Device data block
Device characteristics
Error log message buffer
Data structure types
Define fork block symbols
I/O function codes
Hardware IPL definitions
I/O request packet
Process control block
Privilege mask
SCSI SCDRP symbols
System status codes
Unit control block
Interrupt vector block

.SBTTL Miscellaneous local symbols
;+
; Local symbols

;+
; Argument list (AP) offsets for device-dependent QIO parameters
Pl

P2
P3
P4
PS

B-2

0
4

8
12
16
20

First QIO parameter
Second QIO parameter
Third QIO parameter
Fourth QIO parameter
Fifth QIO parameter
Sixth QIO parameter

VMS SCSI Class Driver Template

Number of SCDRPs to allocate per
unit
UCB STACK SIZE
10
Size of internal stack in UCB
MAX BCNT
"XFFFF
Maximum byte count
.IIF NDF DT$_GENERIC_SCSI, DT$~GENERIC_SCSI
5 ; GENERIC SCSI DEVICE
ASSEMBLE PASSTHRU
0
If 0 don't assemble DIAG code, if
1 do.
SCSI$M_STS
"XCl
Used to extract vendor unique STS
bits.
Length in bytes of DIAGNOSE input
DIAG BUF LEN
60
buffer.
Maximum size in bytes of a SCSI
MAX CMD LEN
248
CMD.
INQ_DATA_LEN
Exact number of INQUIRY bytes
36
required.
Number of SET/GET CONNECTION CHAR
NUM ARGS
10
arguments .
SCDRPS PER UNIT

. SBTTL

SCSI Peripheral Device Types

;+
; Define SCSI Peripheral Device Types
SCSI
SCSI
SCSI
SCSI
SCSI
SCSI

C DA
C SA
C PT
C PR
C WR
C RO

.SBTTL

0
1
2

3
4
5

Direct Access
Sequential Access
Printer
Processor
Write-once Read-multiple
Read-only direct access

Sense key codes

;+
;

Define SCSI sense key codes.

,
SCSI C NO SENSE
- - SCSI C RECOVERED ERROR

0
1

SCSI - C- NOT- READY
SCSI C MEDIUM ERROR
- SCSI- C- HARDWARE- ERROR
SCSI_C_ILLEGAL_REQUEST
SCSI C UNIT ATTENTION

2
3
4
5
6

SCSI C DATA PROTECT
- SCSI C BLANK CHECK

SCSI_C_VENDOR_UNIQUE
SCSI C COPY ABORTED
- SCSI - C- ABORTED- COMMAND
SCSI_C_EQUAL
SCSI - C- VOLUME- OVERFLOW
SCSI C MISCOMPARE

10
11
12
13
14

- -

No sense data
Recovered error (treated as
success)
Device not ready
Medium (parity) error
Hardware error
Illegal request
Unit attention (media change,
reset)
Data protection (write lock error)
Blank check (advance past end of
data)
Vendor unique key
Copy operation aborted
Corrunand aborted
Compare operation, data match
Write beyond physical end of tape
Compare operation, data mismatch

;++
; Define offsets in various SCSI command packets.

B-3

VMS SCSI Class Driver Template

;+
; REQUEST SENSE data offsets.
SCSI XS B ERR CODE
- - SCSI XS B KEY
SCSI- XS- V- KEY
SCSI XS S KEY
- - SCSI XS B ADDNL INFO
- - SCSI XS B ADDNL CODE
- - SCSI XS B ADDNL CODE30
- - SCSI - XS- B- ADDNL- CODESO
SCSI- XS- M- EOF
SCSI XS M EOM
- - SCSI XS M ILI

0
2
0
4
3
12
8
8
"X80
"X40
"X20

SCSI XS V ADDNL VALID

- -

Extended sense error code
Extended sense KEY field
Extended sense KEY bit number
Extended sense KEY length
Extended sense additional code
Extended sense additional code
" (TZ30)
" (TZK50)
"
Extended sense end of file
Extended sense end of medium
Extended sense illegal length
indicator
Extended sense additional data
valid

;+
; INQUIRY data offsets.
SCSI_INQ_B_DEVTYPE
SCSI_INQ_B_DEVQUAL
SCSI_INQ_V_DEVQUAL

0
1
0

SCSI_INQ_S_DEVQUAL
SCSI_INQ_V_REMOVABLE

7
7

Inquiry device type
Inquiry device qualifier field
Inquiry device qualifier starting
bit
Inquiry device qualifier length
Inquiry removable bit

SCSI SKIP B CNT

Skip record count

SCSI MSNS B WP
- SCSI_MSNS_V_WP

Mode sense write protect field
Mode sense write protect bit

SCSI MSEL W RSVDO
- SCSI MSEL B SPEED
- SCSI MSEL B MODE
- SCSI MSEL B DSCLEN

0
2
2
3

SCSI MSEL C DSCLEN

SCSI MSEL B DENS
SCSI- MSEL- B- BLOCKS
SCSI MSEL B RSVDl
SCSI MSEL B BLKLEN
- SCSI MSEL B VULEN
SCSI MSEL B VU
- SCSI MSEL M BUF
SCSI MSEL M NOF

4
5
8

;+
;

MODE SELECT/SENSE data offsets.

- - -

SCSI MSEL M NOFSO
- SCSI - MSEL- M- NOF30
SCSI MSEL M RESEL

- -

12
13
"XlO
7
7

"XOF
"X40

Mode select reserved
Mode select speed field
Mode select buffered mode
Mode select record descriptor
length
Mode select record descriptor
length
Mode select density
Mode select number of blocks
Mode select reserved
Mode select block length
Mode select vendor unique length
Mode select vendor unique field
Mode select buffered mode
Number of fillers for generic
device
Number of fillers for TZKSO
Number of fillers for TZ30
Reselection timeout flag

;+
; SPI interface, Get/set connect characteristics symbols.
SET- CON- L- LEN
SET- CON- L- CON- FLAGS
SET - CON- M- DISC
SET- CON- M- NORETRY
SET- CON- L- SYN- FLAG
SET- CON- M- SYN

B-4

0
4
1
2
8
1

Length field
Flags field
Enable disconnect flag
Disable command retry flag
Synchronous flag field
Synchronous flag

VMS SCSI Class Driver Template

.SBTTL Template class driver extensions to the UCB
;+
; Template class driver extensions to the UCB.

$DEF
$DEF
$DEF
$DEF
$DEF

$DEFINI UCB

Start of UCB definitions

.=UCB$K_LCL_DISK LENGTH

Position at end of UCB

$DEF
$DEF
$DEF
$DEF

UCB L STACK PTR .BLKL
1
Internal stack pointer
UCB L STACK
.BLKL
UCB_ST~CK SIZE
; Internal stack
1
-Address of active SCDRP
UCB L SCDRP
.BLKL
UCB L SCDT
.BLKL
1
SCDT address
UCB L SK FLAGS .BLKL
1
Class driver flags
VIELD UCB,O,<<DISCONNECT, ,M>,Device supports disconnect
<DISABL_ERRLOG,,M>,Disable error logging
<SYNCHRONOUS,,M>>
Device supports synchro; nous operation
UCB W PHASE TMO .BLKW
Phase change timeout
1
- UCB- W- DISC- TMO .BLKW
1
Disconnect timeout
UCB_L_SCDRPQ_FL .BLKL
Queue of free SCDRPs used to
1
UCB_L_SCDRPQ_BL .BLKL
1
send SCSI commands

$DEF
$DEF
$DEF
$DEF

UCB L SAVER6
.BLKL
UCB L SAVER7
.BLKL
UCB L SCDRP SAVl .BLKL
- UCB B LUN
.BLKB

$DEF

UCB K SK UCBLEN

Length of extended UCB

$DEFEND UCB

End of UCB definitions

.SBTTL

1
1
1
1

Safe place for R6.
Safe place for R7.
Safe place for SCDRP address.
Save device LUN

Error log packet formats

;+
The following are the definitions for class driver error log packets.
The VMS error log formatter formats third-party SCSI class driver
error log packets. The ERF utility formats a standard error
log packet for third-party class drivers. The standard packet is defined
below. If a user would like to dump additional data to the error log,
simply increase the size of the error log packet defined. The additional
data will be dumped as untranslated longwords in the error log.
$DEFINI ERROR_PACKETS
= EMB$L_DV_REGSAV

Start of area to dump error info

$DEF

ERR LW CNT

.BLKL

$DEF
$DEF
$DEF
$DEF
$DEF
$DEF
$DEF
$DEF
$DEF
$DEF
$DEF
$DEF

ERR REVISION
ERR HW REV
ERR TYPE
ERR SCSI ID
ERR SCSI LUN
ERR SCSI SUBLUN
ERR- PORT- STATUS
ERR CMD LEN
ERR CMD BYTES
ERR_SCSI_STS
ERR TXT LEN
ERR TXT BYTES
.=.+4

.BLKB
.BLKL
.BLKB
.BLKB
.BLKB
.BLKB
.BLKL
.BLKB
.BLKB
.BLKB
.BLKB
.BLKB

1
1
1
1
1
1
1
1

$DEF

ERR_K_COMMAND_LENGTH

12
1

1
60

Count of number of longwords that
follow
Revision level
Hardware revision
Error type
SCSI ID
SCSI logical unit
SCSI sublogical unit
Port status code
SCSI command length field
Maximum possible command bytes
SCSI status byte
Error message text size
Maximum possible text bytes
Reserve one longword after end of
defined packet.
Length of packet containing SCSI
command

$DEFEND ERROR PACKETS

B-5

VMS SCSI Class Driver Template

.SBTTL

SCSI Class driver error log types.

; SCSI class driver error log types. Each error that is logged by the
; class driver should have a unique error type.
CLS DRV ERROR 01
CLS DRV ERROR 02
CLS DRV ERROR 03
CLS DRV ERROR 04
CLS DRV ERROR 05
- CLS_DRV_ERROR_06
.SBTTL
.SBTTL
.SBTTL
.SBTTL

Class driver
Class driver
Class driver
Class driver
Class driver
Class driver

1
2

3
4

5
6

specific error type.
specific error type.
specific error type.
specific error type.
specific error type.
specific error type.

+
+ MACRO DEFINITIONS
+
SCSI CMD

- Define a SCSI command packet

SCSI CMD
This macro defines the contents of a SCSI command packet. Each SCSI command can have associated with it a DMA buffer used during the
DATAIN/DATAOUT bus phases. A DMA length of zero indicates there is no
DATA(IN/OUT) phase associated with this command (except in the case of a
read/write SCSI command, which is handled specially.)
Class drivers can specify on a command by command basis the DMA Timeout
and Disconnect Timeout values. The disconnect timeout is the maximum
number of seconds that an I/O can be disconnected from the bus. A timeout
of -1 allows an infinite timeout. The DMA timeout is the maximum timeout
for a DMA transfer to complete or a phase change on the SCSI bus to occur;
this timeout is also in units of seconds.
The SETUP_CMD routine uses this information in preparing to send a SCSI
command. The macro generates a label and the SCSI command information as
follows:

+-----------------------+
I
SCSI cmd length
I 1 byte
+-----------------------+
SCSI cmd bytes
n bytes
+-----------------------+
I
DMA buff er length
I 2 bytes
+-----------------------+
DMA direction
1 byte
+-----------------------+
I
DMA Timeout
I 1 longword
+-----------------------+
I Disconnect Timeout
I 1 longword
+-----------------------+
DMA direction is defined as: O=write, l=read .
. MACRO

SCSI_CMD, NAME, CMD_BYTES, DMA_LEN=O, DMA_DIR=READ,DMA_TMO=O, DISCON_TMO=O

'NAME' CMD:
- $$$BYTE_COUNT=O
.IRP CMD BYTE, <CMD BYTES>
$$$BYTE COUNT = $$$BYTE COUNT + 1
.IIF EQ-$$$BYTE_COUNT-l; SCSI_C_'NAME'
.ENDR
.BYTE
$$$BYTE_COUNT
.IRP CMD_BYTE, <CMD_BYTES>
.BYTE
CMD BYTE
.ENDR

B-6

CMD BYTE

Define opcode

VMS SCSI Class Driver Template

.WORD
DMA LEN
$$$DIRECTION = 0
.IIF IDN DMA DIR, READ, $$$DIRECTION
.BYTE
$$$DIRECTION
.LONG
DMA TMO
.LONG
DISCON TMO
.ENDM
SCSI CMD
.SBTTL

LOG ERROR

- Log a SCSI class driver error

;+
LOG ERROR
This macro logs a SCSI class driver error. The error type and VMS status
code are placed in R7 and R8 respectively, and the LOG ERROR routine is
called .
. MACRO

LOG_ERROR,TYPE,VMS_STATUS,UCB=R3,MESSAGE='' ,?LABEL_l

.SHOW EXPANSIONS
PUSHR
#AM<R5,R7,R8,Rll>
Save registers
.IF DIF UCB,RS
MOVL
UCB, RS
Get UCB address
.ENDC
MOVL
#'TYPE' ,R7
Get error code
MOVL
VMS_STATUS,R8
And VMS status code
.IF LESS_THAN
60-%LENGTH(MESSAGE) ; Maximum size message is 60
.ERROR ; Message text is greater than 60 characters
.ENDC
.SAVE PSECT LOCAL BLOCK
.PSECT $$$111_TEXT
LABEL 1:
.ASCIC /'MESSAGE'/
.RESTORE PSECT
MOVAL
LABEL_l,Rll
Write an error log entry
BSBW
LOG ERROR
POPR
#AM<RS,R7,R8,Rll>
Restore registers
.NOSHOW EXPANSIONS
.ENDM

LOG ERROR

.SBTTL

WORD BRANCHES

- Define word displacement branches

;+
WORD BRANCHES
This macro defines for each Bxxx (conditional branch) instruction an
equivalent macro named BxxxW with a word displacement. The macro takes
as an argument a list of tuples, each tuple containing 3 items: 1) a
conditional branch opcode; 2) the opcode with the opposite polarity;
and 3) the number of arguments required by the opcode.

.MACRO

WORD BRANCHES LIST

.MACRO

WORD_BRANCHES2, OPCODEl, OPCODE2, ARGCNT

.IF EQ ARGCNT-0
.MACRO OPCODEl, DST, ?L
OPCODE2 L
BRW
DST
.ENDM
OP COD El
.ENDC

B-7

VMS SCSI Class Driver Template

.IF EQ ARGCNT-1
.MACRO OPCODEl, FIELD, DST, ?L
OPCODE2 FIELD, L
BRW
DST
.ENDM
OPCODEl
.ENDC

.IF EQ ARGCNT-2
.MACRO OPCODEl, BIT, FIELD, DST, ?L
OPCODE2 BIT,FIELD,L
BRW
DST
.ENDM
OPCODEl
.ENDC

.ENDM

WORD BRANCHES2

.MACRO

WORD_BRANCHESl, OPCODEl, OPCODE2, ARGCNT

WORD_BRANCHES2 'OPCODEl'W, OPCODE2, ARGCNT
WORD_BRANCHES2 '0PCODE2'W, OPCODEl, ARGCNT
.ENDM

WORD BRANCHESl

.IRP
ENTRY, <LIST>
WORD BRANCHESl ENTRY
.ENDR
.ENDM

WORD BRANCHES

WORD BRANCHES <<BBC,
BBS,
<BBCC, BBSC,
<BBCS, BBSS,
<BCC,
BCS,
<BEQL, BNEQ,
<BEQLU, BNEQU,
<BGEQ, BLSS,
<BGEQU, BLSSU,
<BGTR, BLEQ,
<BGTRU, BLEQU,
<BLBC, BLBS,
<BVC,
BVS,

2>,2>,2>,0>,0>,0>,0>,0>,0>,0>,1>,0>>

.SBTTL
.SBTTL
.SBTTL
.SBTTL
.SBTTL

INIT UCB STACK
SUBPUSH
SUBPOP
SUBSAVE
SUBRETURN

Initialize the internal UCB stack
Push an item on the UCB stack
Pop an item from the UCB stack
Save a return address on the·ucB stack
Return to the address saved on UCB stack

;+
INIT UCB STACK
SUBPUSH
SUBPOP
SUBSAVE
SUBRETURN
These macros manipulate the UCB internal stack, which is used to save
routine return address and temporary variables .

B-8

. MACRO

INIT_UCB_STACK,UCB=R5,?Ll

MOVAL

UCB_L_STACK-4(UCB),UCB_L_STACK_PTR(UCB)

.ENDM

INIT UCB STACK

.MACRO

SUBPUSH,ARG,UCB=R3,?Ll,?L2

VMS SCSI Class Driver Template

ADDL
MOVL

#4,UCB_L_STACK_PTR(UCB)
ARG,@UCB_L_STACK_PTR(UCB)

.ENDM

SUBPUSH

.MACRO

SUBPOP,ARG,UCB=R3,?Ll,?L2

MOVL
SUBL

@UCB L STACK PTR(UCB),ARG
#4,UCB=L_STACK_PTR(UCB)

.ENDM

SUBPOP

.MACRO

SUBSAVE,UCB=R3,?Ll,?L2

SUBPUSH (SP)+,UCB
.ENDM

SUB SAVE

.MACRO

SUBRETURN,UCB=R3,?Ll,?L2

SUBPOP
RSB

-(SP),UCB

.ENDM

SUBRETURN

.SBTTL

SK WAIT

- Stall a thread for a specific number of seconds

;+
SK WAIT
This macro uses the device timeout mechanism to stall a thread for a
specified number of seconds. The UCB address and stall time are required
as inputs.
.MACRO

SK_WAIT,SECONDS,UCB=R5,SCRATCH=RO,?L

.IF DIF UCB,R5
MOVL
RS, SCRATCH
MOVL
UCB,R5
MOVL
SCRATCH, UCB
.ENDC
DSBINT ENVIRON=UNIPROCESSOR
PUSHL
SECONDS
BSBW
SK WAIT
.WORD
L-.
IO FORK
BICW
#UCB$M_TIMOUT,UCB$W_STS(R5)
.IF DIF UCB,R5
MOVL
UCB, SCRATCH
MOVL
R5,UCB
MOVL
SCRATCH, RS
.ENDC
.ENDM

SK WAIT

.SBTTL
.SBTTL
.SBTTL
.SBTTL

+
+ DRIVER TABLES
+
Driver prologue table

;+
Driver prologue table
This table provides various information about the driver, such as its name
and length, and causes initialization of various fields in the I/O
database when the driver is loaded .
. IIF NDF DPT$M_NO_IDB_DISPATCH, DPT$M_NO_IDB_DISPATCH

"XlOOO

B-9

VMS SCSI Class Driver Template

DPT-creation macro
End of driver label
END=SK_END,Adapter type
ADAPTER=NULL,UCBSIZE=<UCB_K_SK_UCBLEN>,Length of UCB
; Driver name
NAME=SKDRIVER,FLAGS=<DPT$M_SMPMOD!- ; Driver runs in SMP
; environment
DPT$M_NO_IDB_DISPATCH>
Don't fill in IDB$L_UCBLST
DPT_STORE INIT
Start of load
initialization table
DPT_STORE UCB,UCB$L MAXBCNT,L,MAX BCNT ; Maximum byte count
DPT_STORE UCB,UCB$B-FLCK,B,SPL$C IOLOCKS ; Device FORK LOCK
DPT_STORE UCB,UCB$B-DIPL,B,22
; Device interrupt IPL
DPT STORE UCB,UCB$L-DEVCHAR,L,<Device characterstics
DEV$M AVL!-Available
DEV$M-IDV!Input device
DEV$M-ODV!Output device
DEV$M-SHR!Shareable Device
DEV$M-ELG!Error logging enabled
DEV$M-RND>
Random Access Device
DPT STORE UCB;UCB$L DEVCHAR2,L,<- ; Device characterstics
DEV$M NNM> ; Prefix name with "node$"
DPT STORE UCB;UCB$B DEVTYPE,B,DT$ GENERIC SCSI ; Generic SCSI device
DPT-STORE UCB,UCB$B-DEVCLASS,B,Dc$ MISC -Sample device class
DPT-STORE UCB,UCB$W-DEVSTS,W,Set no logical to physical
UCB$M NOCNVRT
block number conversion
DPT_STORE REINIT
Start of reload
initialization table
DPT_STORE DDB,DDB$L_DDT,D,SK$DDT
Address of DDT
DPT STORE CRB,Address of controller
CRB$L_INTD+VEC$L_INITIAL,initialization routine
D,SK_CTRL_INIT
DPT_STORE CRB,Address of device
CRB$L_INTD+VEC$L_UNITINIT,unit initialization
D,SK UNIT INIT
routine
DPT_STORE CRB,CRB$B_FLCK,B,IPL$_IOLOCK8
Initialize fork lock field

DPT AB

DPT_STORE END
.SBTTL

End of initialization
tables

Driver dispatch table

Driver dispatch table
This table defines the entry points into the driver.
;DD TAB
DEVNAM=SK,START=SK_STARTIO,FUNCTB=SK_FUNCTABLE,REGDMP=SK_REG_DUMP
.SBTTL

DDT-creation macro
Name of device
Start I/0 routine
FDT address
Register dump routine

Function decision table

;+
Function decision table
This table lists the $QIO function codes implemented by the driver and
the preprocessing routines used by each function.
;-

B-10

VMS SCSI Class Driver Template

SK FUNCTABLE:
FUNCTAB,<AVAILABLE,READLBLK,READVBLK,DIAGNOSE>
FUNCTAB,<>

; FDT for driver
; Valid I/O functions
Inquiry and Test Unit Ready
Perform a "read" function
Perform a "read" function
Special pass-through function
; Buffered I/O functions

FUNCTAB SK_READ,<READLBLK,READVBLK>
FUNCTAB +EXE$ZEROPARM,<AVAILABLE>
FUNCTAB SK_DIAGNOSE,<DIAGNOSE>

.SBTTL

Issue SCSI
INQUIRY command
Issue SCSI INQUIRY
command
Special pass; through function

SCSI Command Packet Definition Table

SK CMD DEFS::
SCSI_CMD NAME = TEST_UNIT_READY,CMD_BYTES = <0, 0, O, O, O, 0>
SCSI CMD NAME = INQUIRY,CMD_BYTES = <18 I 0, O, O, 36, 0>,DMA LEN
36,DMA DIR= READ,DMA_TMO = 0,Use default
DISCON TMO = 0
Use default
SCSI CMD NAME = REQUEST_SENSE,CMD BYTES = <3, O, 0, 0, 18, O>,DMA LEN
18,DMA DIR = READ,DMA_TMO = 0,Use default
DISCON TMO = 0
Use default
SCSI_CMD NAME = MODE_SELECT,CMD_BYTES = <21, O, O, O, 4, O>,DMA LEN
4,DMA DIR= WRITE,DMA_TMO = 0,Use default
DISCON TMO = 0
Use default
SCSI_CMD NAME = QIO_INQUIRY,Normally this would be
CMD BYTES = <18 , 0, 0, O, 0, O>,- ; a read/write
; command
DMA LEN
-1,If data goes to user
DMA DIR
READ,buffer, then use -1 here.
DMA_TMO
0,Use default
DISCON TMO = 0
Use default
SK CMD DEFS END

B-11

VMS SCSI Class Driver Template

.SBTTL
.SBTTL
.SBTTL
.SBTTL

+
+ DRIVER ENTRY POINTS

+
SK CTRL INIT

;++
SK CTRL INIT

- Controller initialization routine

This routine is called to perform controller-specific initialization
and is called by the operating system in three places:
- at system startup
- during driver loading and reloading
- during recovery from a power failure
Currently this routine is a NOP.
INPUTS:
R4
R5
R6
R8

address
address
address
address

of the CSR
of the IDB
of the DDB
of the CRB

(controller status register)
(interrupt data block)
(device data block)
(channel request block)

OUTPUTS:
All registers preserved
SK CTRL INIT:

MOVZWL
RSB
.SBTTL
;++
SK UNIT INIT

#SS$_NORMAL,RO

SK UNIT INIT
-

Set success status
Return to caller
- Unit initialization routine

This routine allocates a set of SCDRPs and places them on a queue in the
UCB, forms a connection to the port driver by calling SPI$CONNECT, and
sets the unit online.
INPUTS:
RS

- UCB address

OUTPUTS:
RO-R3
- Destroyed
All other registers preserved
;--

SK UNIT INIT:
BBC

Initialize unit
#UCB$V POWER,UCB$W_STS(R5) ,2$

RSB

Branch if we're not here due to a
powerf ail
Otherwise, exit immediately

;+
; Fork twice for now to allow the port driver's unit init routine to execute
; before ours.
2$:

8-12

FORK
FORK
INIT UCB STACK

Fork to drop IPL to SYNCH
2nd Fork synchronizes with port driver.
Initialize the internal stack in the UCB

VMS SCSI Class Driver Template

10$:

MOVAL
MOVL
MOVL
MOVL
MOVL
MOVL
BSBW
MOVW
INS QUE
SOBGTR

UCB_L_SCDRPQ_FL(R5),R0
RO, (RO)
R0,4(RO)
#SCDRPS PER UNIT,R4
#<SCDRP$C_LENGTH>,Rl
R5,R3
ALLOC POOL
Rl,SCDRP$W SCDRPSIZE(R2);
SCDRP$L_FQFL(R2),UCB L SCDRPQ FL(R5)
R4,lO$
-

Initialize the SCDRP queue header
in the UCB
Number of SCDRPs allocated per unit
Length of SCDRP
Copy UCB address
Go allocate an SCDRP
Save length of SCDRP
Place SCDRP in UCB queue
Repeat for all SCDRPs

;+
All SCSI device unit numbers should be of the form "nOm" where n is the
SCSI ID between 0 and 7 and mis the LUN between 0 and 7. Extract the ID
from the LUN by dividing the unit number by 100. The quotient is then
used as the ID while the remainder is the LUN. Note that the unit number
contains three digits because early versions of SCSI provided for sublogical unit numbers. This feature has since been removed and the second
digit in the unit number is not used.
;-

MOVZWL
MOVZWL
CLRL
EDIV
CMPL

#SS$_BADPARAM,RO
UCB$W_UNIT(R5),Rl
R2
#100,Rl,Rl,R2
Rl,#7

BGTRUW
CMPL

20$
R2, #7

BGTRUW
MULB3

20$
#<1@5>,R2,UCB_B_LUN(R5)

ASHL

#16,Rl,Rl

ASHL
MOVL
SUBB3

15$:

#16,R2,R2
UCB$L DDB(R5),R0
#"A'A',DDB$T NAME+3(R0),Rl
SPI$CONNECT BLBC
R0,20$
CMPL
Rl,UCB$L MAXBCNT(R5)
BGEQ
15$
MOVL
Rl,UCB$L_MAXBCNT(R5)
MOVL
R2,UCB L SCDT(R5)
MOVL
R4,UCB$L=PDT(R5)
BISW

20$:

RSB
.SBTTL
.SBTTL
.SBTTL

#UCB$M ONLINE,UCB$W_STS (RS)

Assume bad LUN or SUBLUN specified
Get device unit number
Prepare for extended divide
Extract SCSI bus ID from LUN
Valid SCSI ID (0 <= n
<= 7)?
Branch if not
Valid LUN (0 <= n
<= 7)?
Branch if not
; Save LUN (shifted left
5 bits for use later in SETUP_CMD)
Place SCSI ID in high-order word
of Rl
Place LUN in high-order word of R2
Get DDB address
Translate controller letter to
SCSI bus ID
Connect to the port driver
Branch if connect attempt failed
For MAXBCNT, use minimum supported
value of port and class drivers
Save maximum byte count in UCB
Save SCDT address
Save PDT address
Set unit online
Return to caller

+
+ QIO FDT INTERFACE ROUTINES
+

B-13

VMS SCSI Class Driver Template

.SBTTL
;++
SK READ

SK READ

- FDT preprocessing for sending SCSI Inquiry command

This routine performs FDT preprocessing including:
- Validating access to, and locking, the read/write buffer
INPUTS:
RO
R3
R4
RS
R6
R7
R8
AP

Address of FDT routine
IRP address
PCB address
UCB address
CCB address
Bit number of user-specified I/O function code
Address of current entry in FDT
Address of first function-dependent argument (Pl)

OUTPUTS:

SK READ:

;+
; Use system routines to execute I/O preprocessing.
TSTL
BEQL
JMP
BADPARAM:
MOVZWL
JMP
.SBTTL

P2 (AP)
BADPARAM
G"EXE$MODIFY

There must be bytes to receive.
Bad input parameters.
Lock down pages, set up IRP,
JUMP to EXE$QIODRVPKT, etc ...

#SS$ BADPARAM,RO
G"EXE$ABORTIO
SK DIAGNOSE

; Set bad parameter status
; Abort the I/O with status in RO

- FDT preprocessing for special pass-through
function

;++
SK DIAGNOSE
This routine performs FDT preprocessing including:
- Validating access to the descriptor buff er
- Validating access to, and locking, the read/write buffer
- Copying the SCSI command to a buff er in nonpaged pool
INPUTS:
RO
R3
R4
RS
R6
R7
R8
AP
OUTPUTS:

B-14

Address of FDT routine
IRP address
PCB address
UCB address
CCB address
Bit number of user-specified I/O function code
Address of current entry in FDT
Address of first function-dependent argument (Pl)

VMS SCSI Class Driver Template

DSC OPCODE = 0
DSC FLAGS = 4
DSC CMDADR
8
DSC CMDLEN
12
DSC DATADR
16
DSC DATLEN
20
DSC PADCNT
24
DSC PHSTMO
28
DSC DSCTMO
32
SK DIAGNOSE:
.IF NOT_EQUAL ASSEMBLE_PASSTHRU
IFPRIV
MOVZWL
BRW

DIAGNOSE,10$
#SS$ NOPRIV,RO
50$ -

Flag to control assembly of
IO$ DIAGNOSE
Branch if process has DIAGNOSE priv
Set no privilege status
Branch to abort the I/O

;+
; First, check that we have read access to the user's descriptor.
;-

10$:

MOVQ
MOVL
CMPL
BLSSW
JSB

(AP) ,RO
RO,R9
Rl,#DlAG BUF LEN
40$
G"EXE$WRITECHK

Get user descriptor address, length
Save a copy of descriptor address
Valid descriptor length
Branch if not
Check for read access to the
descriptor buffer (don't return if
no access)

CMPL
BNEQW

DSC_OPCODE(R9),#l
40$

Valid opcode?
Branch if not

CMPL
BGTRUW
CMPL
BGTRU

DSC_DATLEN(R9),UCB$L_MAXBCNT(R5)
40$
DSC PADCNT(R9),#511
40$-

Reasonable read/write data buffer
length?
Branch if not
Reasonable pad count?
Branch if not

MOVQ

DSC_CMDADR(R9),R0

CMPL
BGTRU
JSB
ADDL
JSB
BLBC
MOVL
MOVL
MOVL
MOVL
PUS HR
MOVC3

20$:

POPR
CLRL
MOVL
BEQL
MOVL
BEQL
MO VAL
BLBS
MO VAL
JSB
BLBC

Get SCSI command buffer address,
length
Rl,#MAX CMD LEN
Valid command length?
40$
Branch if not
G"EXE$WRITECHK
Check for read access to the command
buffer (don't return if no access)
#8,Rl
Reserve space for command buff er
overhead
G"EXE$ALONONPAGED
Allocate a buffer in which to copy
the SCSI command
R0,50$
Branch on error
Save length of buff er
Rl, (R2) +
R2,IRP$L_MEDIA(R3)
Save the command buffer address
DSC_CMDLEN(R9),R0
Get length of the SCSI command
Save it in the command buffer
RO, (R2) +
#"M<R2,R3,R4,R5>
Save registers
Copy the SCSI command from user's
R0,@DSC_CMDADR(R9), (R2)
buff er to the buff er in pool
#"M<R2,R3,R4,R5>
Restore registers
IRP$L_BCNT(R3)
Assume no user read/write data
DSC_DATADR(R9),RO
Get address of user data buffer
30$
Branch if no user read/write data
DSC_DATLEN(R9),Rl
Get length of user data buffer
30$
Branch if no user read/write data
Assume user is performing a read
G"EXE$READLOCKR,R2
DSC FLAGS(R9),20$
Branch if this is a read operation
Other check for read access
G"EXE$WRITE LOCKR,R2
(R2)
Check access to and lock down buff er
R0,60$
; Branch on error

B-15

VMS SCSI Class Driver Template

30$:

40$:
50$:

MO VAL
MOVL
MO VAL
.REPT
MOVL
.ENDR
JMP

IRP$C_CDRP(R3),RO
DSC_FLAGS(R9), (RO)+
DSC_PADCNT(R9),Rl

MOVZWL
JMP

Get address of SCDRP within IRP
Save flags field in IRP/SCDRP
Get address of pad count field

(Rl) +, (RO)+

Save pad count, timeout values

G"EXE$QIODRVPKT

Queue the packet to the driver

#SS$ BADPARAM,RO
G"EXE$ABORTIO

Set bad parameter status
Abort the I/O with status in RO

;+
We arrive here if the last FDT operation - checking access to and locking
down the user's read/write buffer - fails. EXE$READLOCKR or EXE$WRITE LOCKR
returns to us through a coroutine call to allow us to give up any resources
which we have allocated during FDT processing. Deallocate the buffer
containing a copy of the SCSI command, then return from the coroutine call.
RO and Rl must be preserved.
60$:

PUSHQ
MOVL

RO
IRP$L_MEDIA(R3),R0

MOVL
JSB
POPQ
RSB
.ENDC

-(RO),Rl
G"EXE$DEANONPGDSIZ
RO

.IF EQUAL ASSEMBLE PASSTHRU
MOVZBL
JMP
.ENDC
.SBTTL
.SBTTL
.SBTTL
.SBTTL
;++
SK STARTIO

#SS$ ILLIOFUNC,RO
G"EXE$ABORTIO

Save registers
Get address of nonpaged pool buffer
containing SCSI command
Get length of buff er
Deallocate the packet
Restore registers
Return from coroutine call
IF ASSEMBLE PASTHRU
IF IO$ DIAGNOSE not assembled, do
this .. Specify the error type
Abort the I/O with status in RO

+ STARTIO SCSI COMMAND EXECUTION ROUTINES
+
SK STARTIO

- Driver STARTIO entry point

This routine is the STARTIO entry point into the driver. Its main function
is to dispatch to the function-code-specific routine that starts a specific
I/O function.
INPUTS:
R3
R5

- IRP address
- UCB address

OUTPUTS:
RO

- 1st longword of I/0 status: contains status code and
number of bytes transferred
Rl
- 2nd longword of I/O status: low-order word contains
high-order word of number of bytes transferred
R4
- Destroyed
All other registers preserved
SK STARTIO:
.ENABLE LSB
INIT UCB STACK

B-16

SK STARTIO
Initialize the internal stack in the UCB

VMS SCSI Class Driver Template

MOVL
MOVL
MOVL
BSBW
MOVL

UCB$L_PDT(R5),R4
R3,R2
R5,R3
ALLOC SCDRP
R2,SCDRP$L_IRP(R5)

Get PDT address
Copy IRP address
Copy UCB address
Allocate an SCDRP
Save IRP address in SCDRP

EXTZV

#IRP $V FCODE, Extract I/O function code
#IRP$(~FCODE, IRP$W FUNC(R2),Rl
ASSUME IRP$S=FCODE LE 7
Allow byte mode dispatch
DISPATCH Rl,TYPE=B,<Dispatch according to function
<IO$_DIAGNOSE,
IO_DIAGNOSE>,IO_READ>,<IO$_READPBLK,
<IO$_AVAILABLE, IO_INQUIRY>>
;+
; Bogus I/O function code will fall through. Set illegal function code
; status and complete the I/O.
IO_BOGUS:
MOVZBL
BRB

#SS$_ILLIOFUNC,RO
COMPLETE IO

COMPLETE IO:
BSBW
DEALLOC SCDRP
MOVL
R3,R5
REQCOM
.DISABLE LSB
. SBTTL
;++
IO_INQUIRY

IO_INQUIRY

Specify the error type
Fall through to exit path for
if other error then uncomment.
Deallocate the SCDRP
Copy UCB address
Complete the I/O
SK STARTIO

- Send SCSI INQUIRY command .

This routine is intended as an example of how to write a STARTIO
routine for a SCSI class driver.
This routine sends an inquiry command to the target. If
errors occur during the execution of this operation no retries
occur. However, this class driver issues a REQUEST SENSE to
determine the nature of the event. If the event is fatal, the
error is logged and the I/O fails. If the event is
benign, then the I/O completes with a REQCOM.
IO_INQUIRY calls the port driver to allocate command buffer areas,
maps the system or user buffer such that the port driver has access
to these areas, and then calls the port driver's SEND_CMD entry point
to send the SCSI command to a target.
When the port driver returns from this call, the INQUIRY data has been
moved, the command status is in the status-in buff er and the SCSI
bus is free. The class driver checks the transfer count, releases
its resources and completes the I/O with a call to REQCOM.
INPUTS:
R3
R4
R5

- UCB address
- PDT address
- SCDRP address

OUPUTS:
RO

- Status
SS$_NORMAL
- I/O completed successfully.
SS$_ILLSEQOP - I/O failed, bad sense key.

B-17

VMS SCSI Class Driver Template

SS$_IVSTSFLG - Invalid SCSI status returned.
SS$_0PINCMPL - I/O failed, insufficient data returned.

IO_INQUIRY:
IO_INQUIRY
.ENABLE LSB
Address of INQUIRY command
MO VAL
INQUIRY_CMD,R2
Perform setup for SCSI command
BSBW
SETUP CMD
BLBC
R0,35$
Send the SCSI command
BSBW
SEND COMMAND
;+
Determine by sending the INQUIRY command, what target is at this ID.
After a call to the port driver, when the port status (RO) and SCSI
command status have been checked, the class driver must verify that
the number of bytes that were to be received or sent have been delivered
by the port driver. SCDRP$L TRANS CNT contains the actual number of bytes
of data transferred by the port d~iver.
BLBC
CMPL
BLSSUW
MOVL
CMPB

R0,35$
SCDRP$L_TRANS_CNT(R5),#INQ DATA LEN
34$ SCDRP$L SVA USER(R5),Rl
#SCSI_C=DA,=
SCSI_INQ_B_DEVTYPE(Rl)
SOMEWHERE
CLEANUP CMD

Branch on error
Sufficient inquiry data returned?

TEST_UNIT_READY_CMD,R2
SETUP CMD
R0,35$
SEND COMMAND
R0,3S$
CLEANUP CMD
Rl
COMPLETE IO

Test Unit Ready command
Perform setup for SCSI command
Branch on error
Send the SCSI command
Branch on error
Clean up from the SCSI command
Clean up Rl
Complete the user's I/O.

Branch if not
Get address of inquiry data
Is this a SCSI disk device?
Check INQUIRY data
If it's not the target you want.
Clean up from the SCSI command

BNEQ
;***
30$:
BSBW
;+
; Now that the class driver knows what target is out there, determine if
; the target is ready by sending a TEST UNIT READY command.
;-

MO VAL
BSBW
BLBC
BSBW
BLBC
BSBW
CLRL
BRW

;+
; Any error the class driver encounters is logged.
; RO contains the VMS status.
34$:
35$:

B-18

MOVZWL #SS$_0PINCOMPL,RO
LOG ERROR Log an invalid inquiry data error
TYPE=CLS DRV ERROR_Ol,VMS_STATUS=RO,I/O operation failed
UCB=R3,MESSAGE=<ERROR DURING INQUIRY_TEST UNIT RDY
SEQUENCE>
BSBW
CLEANUP CMD
Clean up from the SCSI command
CLRL
Rl
Clean up Rl
BRW
COMPLETE IO
Complete the user's I/O.
.DISABLE LSB
IO_INQUIRY

VMS SCSI Class Driver Template

.SBTTL
;++
IO READ

IO READ - Send SCSI INQUIRY command and return data.

This routine is intended as an example of how to write a STARTIO
routine that reads data from a target device and returns the data
to a user buffer. Normally, some form of read command would be used
to retrieve data from a target; however the format of read commands
varies depending on the SCSI device class. Therefore, this
example uses the INQUIRY command to get data from the target; the
INQUIRY command is one of the few commands that is common among
all device types.
Third-party class drivers traditionally do NOT return the INQUIRY
data to the application. Rather, the class driver uses this
information to establish the characteristics of the SCSI target
and the class driver's connection to this target.
IO_READ calls the port driver to allocate command buffer areas,
maps user read buffer such that the port driver has access to these
areas and then calls the port driver's SEND CMD entry point
to send the SCSI command to a target. When the port driver returns from
this call, the INQUIRY data has been moved to the user's buffer,
the command status is in the status-in buffer and the SCSI bus is free.
The class driver checks the transfer count, releases its resources and
complete the I/O with a call to REQCOM.
INPUTS:
R3
R4
RS

- UCB address
- PDT address
- SCDRP address

OUPUTS:
RO

- Status
SS$ NORMAL
SS$=ILLSEQOP SS$_IVSTSFLG SS$_0PINCMPL -

I/O completed successfully.
I/0 failed, bad sense key.
Invalid SCSI status returned.
I/O failed, insufficient data returned

IO READ:
.ENABLE LSB

IO READ

B-19

VMS SCSI Class Driver Template

;+
WARNING: If the user provides the wrong byte count the SCSI bus may hang.
; SCSI port drivers can recover from this error; however, the recovery
; mechanism may be severe and this I/O request will fail.
MOVL

#SCDRP$M BUFFER MAPPED,- ; Set buffer mapped flag to prevent
SCDRP$L_SCSI_FLAGS(R5)
allocation of SO buffer for data
MOVAL
QIO_INQUIRY_CMD,R2
Address of INQUIRY command for
user data
BSBW
SETUP CMD
Perform setup for SCSI command
BLBC
R0,300$
Setup failed
SPI$MAP_BUFFER
Map the user buff er
BSBW
SEND COMMAND
Send the SCSI command

;+
The port driver has been called to send the command and now returns
with the data moved to the user's buffer, the port status in RO, and SCSI
status in the STATUSIN buffer. The class driver checks the port driver
and SCSI command status and then verifies that the number of bytes that
were received equals the BCNT. SCDRP$L TRANS CNT contains the actual
number of bytes of data transferred by the port driver.
;-

BLBC
CMPL

30$:

BNEQUW
MOVL
BSBW
BRW

R0,35$
SCDRP$L TRANS CNT(RS),SCDRP$L::)CNT (RS)
34$
SCDRP$L_TRANS_CNT(R5),Rl;
CLEANUP CMD
COMPLETE IO

Branch on error
Sufficient inquiry data returned?
Branch if not
Return transaction count in IOSB
Clean up from the SCSI command
Complete the user's I/O

;+
; Errors the class driver encounters are logged.
; RO contains the VMS status.
34$:
35$:

MOVZWL #SS$_0PINCOMPL,RO
LOG ERROR Log an invalid inquiry data error
TYPE=CLS_DRV_ERROR_04,VMS_STATUS=RO,I/O operation failed
UCB=R3,MESSAGE=<ERROR DURING READ QIO FUNCTION>
BSBW
CLEANUP_CMD
Clean up from the SCSI command
CLRL
Rl
Clean up Rl
BRW
COMPLETE IO
Complete the user's I/0

;+
; The template driver does not support segmented I/O. This exercise
; is left to the user.
300$:

B-20

BICL

#SCDRP$M BUFFER MAPPED,-; No buffer mapped, so don't unmap.
SCDRP$L_SCSI_FLAGS(R5)
LOG ERROR Log an invalid inquiry data error
TYPE=CLS_DRV_ERROR_OS,VMS_STATUS=RO,I/O operation failed.
UCB=R3,MESSAGE=<ERROR I 0 OPERATION NOT PROPERLY SEGMENTED>
CLRL
Rl
Clean up Rl
BRW
COMPLETE IO
Complete the user's I/O
.DISABLE LSB
IO READ

VMS SCSI Class Driver Template

.SBTTL
;++
IO DIAGNOSE

IO DIAGNOSE

- Special pass-through function

STARTIO routine for the passthru function of the template SCSI
class driver. This routine assumes that the user has provided
a buffer that contains the SCSI command packet and that the
FDT routines in the driver have made the appropriate checks
during I/O preprocessing to allow access to the user data areas
during STARTIO.
IO DIAGNOSE makes calls into the port driver to allocate command
buffer areas, maps the user buffer such that the port driver
can access user areas, and then calls the port driver's SEND_CMD
entry point to send the SCSI command to a target. When the port
driver returns from this call, the user's data has been moved,
the command status is in the status-in buffer and the SCSI bus
is free. The class driver releases its resources and
completes the I/O with a call to REQCOM.
INPUTS:
R2
R3
R4
RS

IRP address
UCB address
PDT address
SCDRP address

OUTPUTS:
RO
- Status
Rl,R2
- Destroyed
All other registers preserved
;--

IO DIAGNOSE:
.ENABLE LSB
.IF NOT_EQUAL ASSEMBLE_PASSTHRU
MOVL
MOVL
MOVL
MOVW
MOVW
MOVAL
EXTZV
INSV
EXTZV
INSV
ADDL
MOVL
MOVL

MOVL
BSBW

IRP$L MEDIA(R2),SCDRP$L MEDIA(R5)
IRP$L SVAPTE(R2),SCDRP$L SVAPTE(RS)
IRP$L BCNT(R2),SCDRP$L BCNT (RS)
IRP$W BOFF(R2),SCDRP$W BOFF (RS)
IRP$W STS(R2),SCDRP$W STS (RS)
IRP$C CDRP(R2),RO
#1, #1:-(RO) ,Rl
Rl,#UCB V DISCONNECT,#1,UCB
SK FLAGS(R3)
#2,U,(RO) ,Rl
Rl,#UCB V SYNCHRONOUS,#l,UCB_L_SK_FLAGS(R3)
#4,RO
(RO)+,SCDRP$L_PAD_BCNT(RS)
(RO)+,-

IO DIAGNOSE
IF assemble IO$_DIAGNOSE if
ASSM PASS
Copy command buffer from IRP to
SCDRP
and SVAPTE,
BCNT,
and BOFF
and STS
Get address of SCDRP portion of IRP
Get disconnect flag
Fill in disconnect flag in UCB
Get synchronous flag
Fill in synchronous flag in UCB
Advance to pad count field
Fill in the pad count in the SCDRP

Fill in the phase change (DMA)
timeout
SCDRP$L DMA TIMEOUT(RS)
in the SCDRP
(RO)+,-Fill in the disconnect timeout in
SCDRP$L DISCON TIMEOUT(RS) ; the SCDRP
SET_CONN CHAR ; Set up the connect characteristics

B-21

VMS SCSI Class Driver Template

MOVL
SCDRP$L_MEDIA(R5),Rl
MOVL
(Rl) +,Rl
ADDL
#8,Rl
SPI$ALLOCATE COMMAND BUFFER
MOVL
R2,SCDRP$L_CMD_BUF(R5)
CLRL
(R2)+
MOVB
#AXFF,-l(R2)
MOVAL
-l(R2),SCDRP$L STS PTR(RS)
MOVL
R2,SCDRP$L_CMD_PTR(R5)

10$:

20$:

Get address of SCSI conunand in pool
Get length of SCSI conunand
Account for overhead
Allocate a conunand buff er
Save address of conunand buff er
Reserve a longword for status
Initialize status field
Address to save status byte

Address of SCSI conunand in cmd
buff er
Get SCSI conunand in pool again
MOVL
SCDRP$L_MEDIA(R5),R0
MOVL
(RO), (R2)+
Copy SCSI conunand length
PUSHR
#AM<RO,R2,R3,R4,R5>
Save registers
; Copy SCSI conunand to conunand buff er
MOVC3
(RO) I 4 (RO) I (R2)
POPR
#AM<R0,R2,R3,R4,R5>
; Restore registers
Get length of command buffer in pool
MOVL
-(RO),Rl
JSB
GAEXE$DEANONPGDSIZ
Deallocate the buff er
TSTL
SCDRP$L BCNT(RS)
Any user data buff er?
BEQL
10$
Branch if not
SPI$MAP BUFFER
Map the user's data buffer
SPI$SEND_COMMAND
Send the SCSI command
Save returned port status
PUSHL
RO
User buffer mapped?
TSTL
SCDRP$L BCNT(RS)
BEQL
20$
Branch if not
SPI$UNMAP BUFFER
Unmap the user's data buffer
MOVL
SCDRP$L_CMD_BUF(R5),RO
Get the command buff er address
PUSHL
(RO)
Save the SCSI status byte
Deallocate the conunand buffer
SPI$DEALLOCATE_COMMAND_BUFFER
POPL
Rl
Restore the SCSI status byte
POPL
RO
Restore the port status
INSV
SCDRP$L TRANS_CNT(RS),Copy the transfer count to the
high-order word of RO
#16 I #16:-RO
.ENDC
If ASS DIAG FALSE don't assemble
BRW
COMPLETE IO
Complete the QIO
.DISABLE LSB
IO DIAGNOSE
.SBTTL
.SBTTL
.SBTTL

.SBTTL
;++
SEND COMMAND

+
+ UTILITY ROUTINES
+
SEND COMMAND

- Send a SCSI conunand

This routines sends a command to the SCSI device. It returns any failing
port status to the caller. If the port status is success, it checks the
SCSI status byte. If a check condition status is returned, a request
sense command is sent to the target and the sense key is translated into
a VMS status code, which is returned as status.
INPUTS:
R3
R4
RS

- UCB address
- PDT address
- SCDRP address

OUTPUTS:

B-22

- Status

Rl,R2

SS$_IVSTSFLG - Invalid SCSI status returned.
SS$_ILLSEQOP - I/O operation failed.
- Destroyed

VMS SCSI Class Driver Template

All other registers preserved
;-SEND COMMAND:

10$:

.ENABLE LSB
SUBSAVE
SPI$SEND COMMAND
BLBC
R0,10$
MOVZBL @SCDRP$L STS PTR(R5),Rl
BICB
#SCSI$M STS,Rl
BNEQ
20$
SUBRETURN

SEND COMMAND
Save return address
Send the SCSI conunand
If port failed, return
Get SCSI status byte
Clear reserved, vendor-unique bits
Branch if bad status
Return to caller

;+
A bad SCSI status code was returned. If the code is a check condition,
; then send a request sense conunand to the device. Otherwise, the status
; code is something unexpected. Log an error and return SS$_MEDOFL status.
;-

20$:

CMPB
BNEQ

Rl,#2
90$

Check condition status?
Branch if not

;+
A check condition status code was returned. Save the original SCDRP
address, allocate a second one and send a request sense conunand. If the
request sense succeeds, translate the sense key to a VMS status code and
return that as the status code for the original conunand.
;-

45$:

MOVL
BSBW
BSBW
BLBC

R5,UCB_L_SCDRP_SAV1(R3)
ALLOC_SCDRP
REQUEST SENSE
R0,50$ -

Save original SCDRP address
Allocate an additional SCDRP
Send a request sense conunand
Branch on error
a VMS status code in RO

;+
; Look at the results of the request sense to determine the exact nature
; of the event.
;-

MOVL
BICB3
BNEQ
BICB3

SCDRP$L SVA USER(R5),Rl; Get address of REQUEST SENSE DATA.
#AXFO,SCSI XS B ERR CODE(Rl),-; First check ERROR CODE.
RO
- - In this case zero is good, but this
50$
is really device specific.
#AXFO,SCSI XS B KEY(Rl),-; Mask of~ SENSE KEY.
RO
- - -

; Depending on the value of the sense key, dispatch to the appropriate
; error recovery.
;-

DISPATCH RO,TYPE=B,<-

Dispatch accord; ing to SENSE KEY.
<SCSI_C_NO_SENSE,SK_OK>,No sense data
<SCSI C RECOVERED ERROR,SK OK>,- ; Recovered error
<SCSI=C=NOT_READY;sK_BAD>,=
Device not ready
<SCSI_C_MEDIUM_ERROR,SK_BAD>,Medium (parity)
; error
<SCSI C HARDWARE ERROR, SK BAD>,Hardware error
<SCSI-C-ILLEGAL REQUEST,SK BAD>,Illegal request
Unit attention
<SCSI=C=UNIT_ATTENTION,SK_BAD>,; ( reset ...
<SCSI_C_DATA_PROTECT,SK_BAD>,Data protection
; (write lock)
<SCSI_C_BLANK_CHECK,SK_BAD>,Blank check
<SCSI_C_VENDOR_UNIQUE,SK_BAD>,Vendor unique key
<SCSI_C_COPY_ABORTED,SK_BAD>,Copy operation
; aborted
<SCSI_C_ABORTED_COMMAND,SK_BAD>,- ; Conunand aborted

B-23

VMS SCSI Class Driver Template

<SCSI_C_EQUAL,SK_BAD>,Data match
<SCSI_C_VOLUME_OVERFLOW,SK_BAD>,- ; Write past
; physical end
<SCSI_C_MISCOMPARE,SK_BAD>>
Data mismatch

;+
Either the sense key was bad or the key was invalid. In either case
indicate that the command failed. Some class drivers will want
to translate each bad sense key to a unique class driver SS$_XXXXX
status code. Here we will always return SS$_ILLSEQOP.
SK BAD:
MOVL
BRB

#SS$ ILLSEQOP,RO
50$ -

I/O operation failed
cleanup and return error

;+
; If the sense key indicated that the operation completed successfully,
; then return success.
SK OK:

50$:

MOVL
BRB

#SS$ NORMAL,RO
50$ -

I/O operation succeeded
Clean up and return error

BSBW
BSBW
MOVL
MOVL
BRW

CLEANUP CMD
DEALLOC SCDRP
UCB_L_SCDRP_SAV1(R3),R5
RS,UCB L SCDRP(R3)
10$
- -

Clean up the request sense command
Deallocate the request sense SCDRP
Restore original SCDRP address
Copy it to the UCB
Return to caller

;+
If the status returned for the last command was anything other than
; check condition, log an error and return a status of SS$ IVSTSFLG to
; indicate that command failed and that there is no request sense data.
90$:

MOVL
#SS$_IVSTSFLG,RO
Return a generic status code
LOG ERROR Log a send command error
TYPE=CLS DRV ERROR_02,Generic user class driver error
VMS_STATUS=RO,UCB=R3,MESSAGE=<ERROR BAD SCSI COMMAND STATUS>
BRW
10$
.DISABLE LSB
; SEND_COMMAND

.SBTTL REQUEST_SENSE
;++
REQUEST_SENSE

- Send a request sense command

This routine is called by SEND_COMMAND when a command fails with check
condition status. A request sense command is sent to the target.
INPUTS:
R3
R4
RS

- UCB address
- PDT address
- SCDRP address

OUTPUTS:
RO

- Status

SS$_IVSTSFLG - Bad SCSI status returned during
REQUEST SENSE.
Rl,R2
- Destroyed
All other registers preserved

B-24

VMS SCSI Class Driver Template

REQUEST_SENSE:
.ENABLE LSB
SUBSAVE
MOVAL
REQUEST_SENSE_CMD,R2
BSBW
SETUP CMD
BLBC
R0,10$
SPI$SEND COMMAND
BLBC
R0,10$
MOVZBL @SCDRP$L STS PTR(R5),Rl
BICB
#SCSI$M STS,Rl
BNEQ
20$
10$:
SUBRETURN
20$:

REQUEST_SENSE
Save return address
Address of REQUEST_SENSE command
Perform setup for SCSI command
Branch on error
Send the SCSI command
Return on error
Get SCSI status byte
Clear reserved, vendor unique bits
Branch if bad status
Return to caller

MOVZWL #SS$ IVSTSFLG,RO
Return bad SCSI status to caller.
BRB
10$ .DISABLE LSB
REQUEST SENSE
.SBTTL SET CONN CHAR
- Modify connection characteristics

;++
SET CONN CHAR
This routine is called to initialize the connection characteristics,
which specify such things as whether. the device supports disconnect
and synchronous operation, and the bus busy, arbitration, selection,
and command retry counters.
This routine first does a SPI$GET CONNECTION CHAR to get the current
values of the connection characteristics, modifies the values of interest,
then does a SPI$SET CONNECTION CHAR to set up the new values. This allows
the class driver to-change a s~bset of the characteristics and leave the
rest unmodified.
INPUTS:
R3
R4
RS

- UCB address
- SPDT address
- SCDRP address

OUTPUTS:
RO-R2
- Destroyed
All other registers preserved
SET CONN CHAR:
.ENABLE LSB

SET_CONN_CHAR

B-25

VMS SCSI Class Driver Template

SUBSAVE
MOVL
#<<NUM_ARGS+1>*4>,Rl
BSBW
ALLOC POOL
SUBPUSH R2
MOVL
#NUM ARGS, (R2)
SPI$GET_CONNECTION_CHAR
BLBC

R0,10$

Save return address
Size of
get/set connection char buffer
Allocate the buffer
Save address of buffer
Set argument count in buffer
Get current connection
characteristics
Branch on error

;+
Some devices won't select if selected with attention.
NOTE: It is strongly suggested that targets and devices
support the disconnect/reselection sequence. All
Digital-supplied devices support this feature to
ensure consistent bus performance.
EXTZV

#UCB_V_DISCONNECT,#1,Fill in disconnect flag
UCB_L_SK_FLAGS(R3),4(R2);

EXTZV
10$:

20$:

#UCB_V_SYNCHRONOUS,#1,; Fill in synchronous flag
UCB L SK FLAGS(R3),8(R2)
SPI$SET_CONNECTION_CHAR
Set the connection characteristics
PUSHL
RO
Save return status
SUBPOP RO
Get address of characteristics
buff er
BSBW
DEALLOC POOL
Deallocate the buff er
POPL
RO
Restore return status
BLBS
R0,20$
Branch if success status
MOVL
#SS$_CTRLERR,RO
Otherwise, return a reasonable
status
SUBRETURN
Return to caller
.DISABLE LSB
SET CONN CHAR

.SBTTL
;++
SK WAIT

SK WAIT

- Stall for the specified number of seconds

This routine is used by the SK_WAIT macro to stall a thread for a
specified number of seconds. It sets the timeout bit in the UCB and
relies on the device timeout mechanism to resume the stalled thread.
INPUTS:
IPL
RS
(SP)
4(SP)
8(SP)
12(SP)

31
UCB address
Return address
Wait time in seconds
Saved IPL
Address of caller's caller

OUPUTS:
Stack
- Return address, wait time, IPL removed
Control returns to caller's caller
All registers preserved
NOTE: The use of the SK WAIT macro destroys RO-R3
SK WAIT:

B-26

VMS SCSI Class Driver Template

MOVQ
ADDL3
BISW
ADDL3
BICW

R3,UCB$L FR3(RS)
#2, (SP)+~UCB$L FPC(RS)
#UCB$M TIM,UCB$W STS(RS);
(SP)+,GAEXE$GL ABSTIM,UCB$L DUETIM(RS)
#UCB$M TIMOUT,UCB$W_STS (RS)

ENBINT
RSB
.SBTTL
;++
ALLOC SCDRP

Save R3 and R4 in fork block
Save return address in fork block
Set timer expected bit
Set up timeout time in UCB
Clear timer expired bit
Reenable interrupts
Return to caller's caller

ALLOC SCDRP

- Allocate an SCDRP

This routine allocates an SCDRP by attempting to remove one from the
queue in the UCB. If the queue is empty (which should never happen),
then bugcheck. The entire SCDRP is zeroed and various fields are
initialized.
INPUTS:
R3

- UCB address

UCB_L_SCDRPQ_FL - Queue of SCDRPs
OUTPUTS:
RS
- SCDRP address
All other registers preserved
SCDRP$L UCB
- UCB address
SCDRP$L-IRP
- IRP address
SCDRP$L-CDT
- SCDT address
SCDRP$L-SCSI FLAGS - Initialized
SCDRP$L=CL_SSK_PTR - Initialized
ALLOC SCDRP:
.ENABLE
REMQUE
PUS HR
MOVCS

POPR
MOVL
MOVL
MOVB
MOVL
MO VAL

LSB
@UCB L SCDRPQ FL(R3),R5
#AM<RO~Rl,R2,R3,R4,RS>
#0,.,#0,#SCDRP$C_LENGTH-12,12(R5)
#AM<R0,Rl,R2,R3,R4,R5>
RS,UCB L SCDRP(R3)
R3,SCDRP$L_UCB(R5)
UCB$B FLCK(R3),SCDRP$B_FLCK(RS)
UCB L SCDT(R3),SCDRP$L_CDT (RS)
SCDRP$L SCSI STK-4(RS),-;
SCDRP$L=SCSI=STK_PTR(RS);

ALLOC SCDRP
Remove an SCDRP from the queue
Save registers
Initialize the SCDRP

Restore registers
Save SCDRP address in UCB
Save UCB address in SCDRP
Copy the fork lock field from the
UCB to the SCDRP
Save SCDT address in SCDRP
Initialize the SCDRP stack pointer

RSB
.DISABLE LSB

ALLOC SCDRP

B-27

VMS SCSI Class Driver Template

.SBTTL DEALLOC SCDRP
;++
DEALLOC SCDRP

- Deallocate an SCDRP

This routine deallocates an SCDRP by returning it to the queue in the
UCB. A sanity check is made to ensure that any map registers for this
command have been deallocated.
INPUTS:
R3
RS

- UCB address
- SCDRP address

OUTPUTS:
R3
- UCB address
RS
- UCB address (for RS entry point)
All other registers preserved
UCB L SCDRP

- Cleared to indicate no active SCDRP

DEALLOC SCDRP:
.ENABLE LSB
INSQUE SCDRP$L_FQFL(RS),UCB_L_SCDRPQ_FL(R3)
CLRL
UCB_L_SCDRP(R3)
RSB
.DISABLE LSB
.SBTTL
;++
ALLOC POOL

ALLOC POOL

DEALLOC SCDRP
Insert SCDRP in UCB queue
No active SCDRP for this UCB
; DEALLOC_SCDRP

- Allocate a block of nonpaged pool

This routine allocates a block of nonpaged pool no smaller than the
size of a fork block (allowing COM$DRVDEALMEM to fork on this block
during deallocation.) An extra quadword at the top of the block is
reserved to save the size field, relieving the caller of this responsibility. The caller is presented with the address just beyond the
reserved quadword. Although a word would be sufficient for this field,
a quadword is used for alignment purposes (some blocks are used as IRPs,
which are placed on self-relative queues and require quadword alignment.)
If an allocation failure occurs, the thread is stalled and wakes up once
a second to retry the allocation.
INPUTS:
Rl
R3

- Size of block to allocate
- UCB address

OUTPUTS:
RO
- Destroyed
Rl
- Size of block allocated
R2
- Address of allocated block
-8(R2)
- Length of allocated block (used by DEALLOC_POOL)
All other registers preserved
ALLOC POOL:

8-28

VMS SCSI Class Driver Template

.ENABLE LSB
ADDL
#8,Rl
CMPL
Rl,#FKB$C_LENGTH

10$:

BGEQ
MOVL
PUSHL
PUSHL
JSB
POPL
BLBC
ADDL
PUS HR
MOVCS
POPR
MOVL
ADDL
RSB

10$
#FKB$C_LENGTH,Rl
Rl
R3
GAEXE$ALONONPAGED
R3
R0,20$
#4,SP
#AM<RO,Rl,R2,R3,R4,R5>
#0,., #0, Rl, (R2)
#AM<R0,Rl,R2,R3,R4,R5>
Rl, (R2) +
#4,R2

ALLOC POOL
Reserve a quadword to save size
Requested size smaller than fork
block?
Branch if not
Use fork block size as minimum
Save allocation length
Save UCB address
Allocate a block
Restore register
Branch if error
Remove allocation length from stack
Save registers
Initialize the packet
Restore registers
Save size of block
Skip a longword
Return to caller

;+
; A pool allocation failure occurred. Come back once a second and retry the
; operation until successful.
20$:

SUBPUSH (SP)+
SUBSAVE
SK WAIT #1,UCB=R3
SUBPOP -(SP)
SUBPOP Rl
BRW
10$
.DISABLE LSB

.SBTTL
;++
DEALLOC POOL

DEALLOC POOL

Save allocation length (PUSHL Rl above)
Save return address
Wait a second
Restore return address
Restore allocation length
Try again
ALLOC POOL
- Deallocate a.blocK of nonpaged pool

This routine deallocates a block of nonpaged pool. The size of the block
is stored in the reserved quadword at a negative offset from the
beginning of the block.
INPUTS:
RO
-8(R0)

- Address of block to deallocate
- Length of block to deallocate

OUTPUTS:
RO
- Destroyed
All other registers preserved
;--

DEALLOC POOL:
.ENABLE LSB
PUSHQ
Rl
SUBL
#4,RO
MOVL
-(RO),IRP$W_SIZE(R0)
CLRB
IRP$B_TYPE (RO)
JSB
GAEXE$DEANONPAGED
POPQ
Rl
RSB
.DISABLE LSB

DEALLOC POOL
Save Rl,R2
Skip a longword
Copy size field
Clear type field (prevents block
from being interpreted as shared
memory during deallocation)
Deallocate the block
Restore Rl,R2
DEALLOC POOL

B-29

VMS SCSI Class Driver Template

.SBTTL
;++
SETUP CMD

SETUP CMD

- Common setup for all SCSI commands

This routine performs common setup prior to the sending of a SCSI command.
Setup includes allocating a command buffer, filling in the pointers in the
SCDRP to the command and status fields, copying the SCSI command to the
command buffer, allocating an SO "user" buffer if the command requires
transferring data to or from the class driver, filling in the SCDRP fields
used to map this buffer, and mapping the buffer.
Since this routine calls SPI$ALLOCATE COMMAND BUFFER, which can suspend
the thread, the return PC must be saved in the SCDRP.
INPUTS:
R2
R4
RS

Pointer to entry in SCSI CMD table
- PDT address
- SCDRP address

OUTPUTS:
RO
Rl,R2

- Status
- Destroyed

SCDRP$L_CMD BUF - Address of SCSI command buffer
SCDRP$L CMD PTR - Address of SCSI command
SCDRP$L-STS-PTR - Address to save SCSI status byte
SCDRP$L-SVA-USER- Address of SO "user" buffer
SCDRP$()CNT
- Length of SO "user" buffer
SCDRP$W BOFF
- Byte off set of SO "user" buffer
SCDRP$L-SVAPTE - SVAPTE of SO "user" buffer
IRP$V FUNC
- SET/CLEAR to indicate READ/WRITE from SO "user" buffer
SCDRP$L DMA TIMEOUT - Time in seconds for a DMA timeout.
SCDRP$L=DISCON_TIMEOUT - Time in seconds for a disconnect to time out
;--

.ENABLE LSB
SETUP CMD:
SCSI_CMD_BUF_OVHD

10$:

B-30

SETUP CMD

4 + 4

SUBSAVE
MOVZBL
(R2),Rl
ADDL
#SCSI_CMD_BUF OVHD,Rl
SUBPUSH R2
SPI$ALLOCATE_COMMAND_BUFFER
MOVL
R2,Rl
SUBPOP R2
MOVB
#AXFF, (Rl)
MOVAL
(Rl) +, SCDRP$L STS PTR(RS)
MOVL
Rl,SCDRP$L CMD PTR(RS)
MOVZBL
(R2)+,RO MOVL
RO, (Rl)+
ASHL
#-1,RO,RO
MOVW
(R2)+, (Rl)+
SOBGTR R0,10$

4 bytes to save status byte +
4 bytes for SCSI command length
Save return address
Get size SCSI command
Add in command buff er overhead
Save R2
Allocate a command buff er
Copy command buffer address
Restore R2
Initialize status field
Address to put SCSI status byte
Save address of SCSI command
Get SCSI command length
Save length in command buffer
Change byte count to word count
Copy a byte of SCSI command
Repeat for entire SCSI command

VMS SCSI Class Driver Template

;+
There is a dependency here that the format of the SCSI COMMAND record
does not change.
Copy the per command timeout values from the SCSI CMD block to the
SCSI Class Driver Request Packet.
R2 points at the direction field in the SCSI CMD block.
;-

MOVL
MOVL

3(R2),Time in seconds for a DMA timeout.
SCDRP$L DMA_TIMEOUT(R5)
7(R2),- Disconnect timeout in seconds.
SCDRP$L_DISCON_TIMEOUT(R5)

;+
Determine if a buffer has already been mapped. If no buffer has been
; mapped, then allocate a system buffer and map it to receive the data
; from the target device.
BBC

#SCDRP$V BUFFER MAPPED,-; If buffer is mapped then do
SCDRP$L SCSI FLAGS(R5),-; special setup for this command
20$
-

;+
During the STARTIO operation in the class driver, the user's QIO
parameters must be copied from the !RP to SCDRP (SCSI Class Driver
Request Packet) . The user data is then mapped, the SCSI CMD packet is
allocated, and the command is sent to a target, over the connection
established during UNIT !NIT.

,
MOVL
CLRL
MOVW
MOVW
MOVL
MOVL
MOVW
MOVL
CMPL
BGTR
CLRL
ADDL3
MOVB
BRW

UCB$L IRP(R3),R2
Get current I/O's !RP address
SCDRP$L ABCNT(R5)
Initialize accumulated byte count
IRP$W FUNC(R2),Copy function code and modifiers,
SCDRP$W FUNC(RS)
MEDIA, SVAPTE, and BOFF fields,
IRP$W STS(R2),and STS
SCDRP$W STS (RS)
IRP$L MEDIA(R2),from the !RP to the SCDRP
SCDRP$L MEDIA(RS)
IRP$L SVAPTE(R2),SCDRP$L SVAPTE(RS)
IRP$W BOFF(R2),SCDRP$W BOFF(R5)
IRP$L BCNT(R2),Copy user's BCNT from IRP to SCDRP
SCDRP$L BCNT(RS)
SCDRP$L-BCNT(R5),Transfer length greater than maximum
UCB$L_MAXBCNT(R3)
supported?
300$
GTR, therefore I/O must be segmented
SCDRP$L PAD BCNT(RS)
No padding of last page required
#<4+4>,=
- ; Address of transfer length field in
SCDRP$L CMD PTR(R5),Rl ; SCSI command
SCDRP$L=BCNT(R5), (Rl)
Copy user-supplied byte count to
command.
50$
Setup finished.

B-31

VMS SCSI Class Driver Template

20$:

Get length of send data buff er
Branch if negative, no system buffer
involved, leave SCDRP$L BCNT unchanged
Branch if zero length, zero SCDRP$L_BCNT
BEQL
30$
SUBPUSH R2
Save R2
Allocate a buffer to receive response
BSBW
ALLOC POOL
Copy buffer address
MOVL
R2,Rl
SUBPOP R2
Restore R2
Rl,SCDRP$L SVA USER(RS)
Save address of allocated buffer
MOVL
MOVZWL
(R2)+,SCDRP$L BCNT(RS)
; Save length of transfer
CLRL
SCDRP$L PAD BCNT(RS)
; No padding required
BICW3
#AC<AXlFF>,Rl,; And byte offset within page
SCDRP$W BOFF(RS)
(R2),#IRP$V FUNC,#1,Set/clear FUNC bit to indicate READ/
INSV
SCDRP$W STS(RS)
; WRITE function
R3
; Save R3
PUSHL
MOVL
SCDRP$L SVA USER(R5),R2; Get user buffer address
GAMMG$SVAPTECHK
Get SVAPTE of allocated system buffer
JSB
R3,SCDRP$L SVAPTE(RS)
Save SVAPTE in SCDRP
MOVL
R3
Restore R3
POPL
BISB
#SCDRP$M SOBUF!This buffer is an SO "user" buffer
SCDRP$M-BUFFER MAPPED,- ; and it has been mapped
SCDRP$L SCSI FLAGS(RS)
SPI$MAP_BUFFER Map the "user" buff er for read access

50$:
52$:

MOVZWL #SS$_NORMAL,RO
SUBRETURN

30$:

CLRL
BRB

300$:

MOVZWL #SS$ IVBUFLEN,RO
52$ BRB
.DISABLE
LSB
.SBTTL CLEANUP CMD

CVTWL
BLSS

(R2) ,Rl
50$

SCDRP$L BCNT (R5)
50$
-

Set success status

No data being transferred
Use common exit
Bad byte count
SETUP CMD
- Common cleanup for all SCSI commands

;++
CLEANUP CMD
This routine performs common cleanup after the sending of a SCSI command,
including unmapping the user buffer and deallocating the command buffer.
INPUTS:
R4
RS

- PDT address
- SCDRP address

OUTPUTS:
R2
- Destroyed
All other registers preserved
CLEANUP_CMD:

B-32

VMS SCSI Class Driver Template

10$:

20$:
30$:

.ENABLE LSB
PUSHR
#AM<RO,Rl,R3>
BBCC
#SCDRP$V BUFFER MAPPED,-;
SCDRP$L SCSI FLAGS(RS),-;
10$
SPI$UNMAP BUFFER
BBCC
#SCDRP$V SOBUF,SCDRP$L SCSI FLAGS(RS),-;
20$
MOVL
SCDRP$L SVA USER(RS),RO
CLRL
SCDRP$L=SVA=USER(R5)
BSBW
DEALLOC POOL
MOVL
SCDRP$L_CMD_BUF(R5),RO
SPI$DEALLOCATE COMMAND BUFFER
POPR
#AM<RO~Rl,R3> RSB
.DISABLE LSB

.SBTTL
;++
LOG ERROR

LOG ERROR

CLEANUP CMD
Save registers
Branch if no buffer has been mapped

Unmap the mapped buff er
Branch if this is not an SO "user"
buff er
Get address of SO user buffer
Buff er no longer owned
Deallocate the buff er
Get address of command buff er
Deallocate the command buff er
Restore registers
CLEANUP CMD

- Write an entry to the error log file

This routine writes an entry to the error log file. If the device is
offline, no error is logged. This prevents the error log file from being
filled up while the class driver does its periodic polling of devices
that have been set offline. The assumption is that the initial error that
caused the device to be placed off line has been logged and that
subsequent error log entries would be redundant.
INPUTS:
RS
R7
RS

- UCB address
- Error type
- VMS status code

OUTPUTS:
All registers preserved

,
LOG ERROR:
.ENABLE LSB
#AM<RO,R2,R9,Rl0>
PUS HR
MOVB
UCB$B DEVTYPE(R5),R9
MOVB
UCB$B-DEVCLASS(R5),Rl0
10$:
UCB$L-DDT(R5),RO
MOVL
MOVW
#ERR_K_COMMAND_LENGTH,-

JSB
BBCC

30$:
40$:

DDT$W ERRORBUF(RO)
GAERL$DEVICERR
#UCB$V ERLOGIP,UCB$W STS(RS),30$
UCB$L=EMB(R5),R2
30$
GAERL$RELEASEMB
#AM<RO,R2,R9,Rl0>

MOVL
BEQL
JSB
POPR
RSB
.DISABLE LSB
.SBTTL

SK REG DUMP

LOG ERROR
Save registers
Save SCSI device type
Save DEVCLASS field
Get DDT address
Length of packet containing SCSI
command
in the DDT
Log a device error
Clear error log in progress
Get address of error message buff er
Branch if none available
Release the error log buffer
Restore registers
Return to caller
LOG ERROR

- Device register dump routine

B-33

VMS SCSI Class Driver Template

;++
SK REG DUMP
This routine dumps device-specific information into an error log packet.
The format of this information is as follows:

+-----------------------+
Longword count
I
I 4 bytes
+-----------------------+
Revision
1 byte
I
+-----------------------+
HW revision
I
I 4 bytes
+-----------------------+
Error Type
1 byte
I
+-----------------------+
SCSI ID
1 byte
I
+-----------------------+
SCSI LUN
1 byte
+-----------------------+
I
SCSI SUBLUN
I 1 byte
+-----------------------+
I
Port status
I 4 bytes
+-----------------------+
I
SCSI CMD LENGTH
I 1 byte
+-----------------------+
I
SCSI CMD BYTES
I Up to 12 bytes
+-----------------------+
I
SCSI STS
I 1 byte
+-----------------------+
I
Error Text Count
I 1 byte
+-----------------------+
I
Error Text
I Up to 60 bytes
+-----------------------+
Inputs:
RO
RS

- Output buff er address
- UCB address

Outputs:
Rl-R3
- Destroyed
All other registers preserved

B-34

VMS SCSI Class Driver Template

SK REG DUMP:
.ENABLE LSB
; SK REG DUMP
MOVL
#<<ERR K COMMAND LENGTH/4>+1>,(RO)+ - Length of error log packet in words
MOVB
#0, (RO)+
Save revision level
CLRL
(RO)+
Save hardware revision level
MOVB
R7, (RO)+
Save error type
MOVZWL UCB$W_UNIT(R5),Rl
Get unit number
CLRL
R2
Prepare for extended divide
EDIV
#100,Rl,Rl,R2
Extract SCSI bus ID from unit number
MOVB
Rl, (RO)+
Save SCSI bus ID
MOVL
R2,Rl
Copy LUN, SUBLUN
CLRL
R2
Prepare for extended divide
EDIV
#10,Rl,Rl,R2
Extract LUN and SUBLUN
MOVB
Rl, (RO)+
Save LUN field
MOVB
R2, (RO)+
Save SUBLUN field
MOVL
R8, (RO)+
Save port status code
MOVL
UCB L SCDRP(R5),Rl
Get active SCDRP address
50$- Branch if none active
BEQL
MOVL
SCDRP$L_CMD_PTR(Rl),R2
Get address of SCSI command
BEQL
50$
Branch if none active
MOVL
(R2)+,R3
Get number of SCSI command bytes
MOVB
R3, (RO)+
Save command length
10$:
MOVB
(R2)+, (RO)+
Save a command byte
SOBGTR R3,10$
Continue for entire SCSI command
MOVL
SCDRP$L_STS_PTR(Rl),R2
Get address of status byte
MOVB
(R2), (RO)+
Save SCSI status byte
MOVB
(Rll)+,R3
Get count of number of text bytes.
BEQL
50$
If no text finished
MOVB
R3, (RO)+
Save text length
20$:
MOVB
(Rll)+, (RO)+
Save a text byte in error packet
SOBGTR R3,20$
Continue for entire text string
command
50$:
RSB
Return
.DISABLE
LSB
SK REG DUMP
SK PATCH:
.BLKB
200
Patch space
SK END:

Last location in driver
.END

B-35

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

This example driver, DLDRIVER, drives a disk device on both the
UNIBUS and the Q22 bus .
. TITLE
.IDENT

DLDRIVER - VAX/VMS RL11/RL01,RL02 DISK DRIVER
'X-7'

;****************************************************************************
•*
*
'
;*
COPYRIGHT (c) 1978, 1980, 1982, 1984 BY
*
;* DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASSACHUSETTS.
*
;*

•*

'
;*

;*
;*
;*
;*
;*
•*

';*

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT
CORPORATION.

;*
;*

DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.

;*
;*

*
*

*
*
*
*
*

*
*

*
;****************************************************************************
FACILITY:
VAX/VMS RL11/RL01,RL02 DISK DRIVER

•**

.PAGE
ABSTRACT:
THIS MODULE CONTAINS THE TABLES AND ROUTINES NECESSARY TO
PERFORM ALL DEVICE-DEPENDENT PROCESSING OF AN I/O REQUEST
FOR RL11/RL01,RL02 DISK TYPES ON A VAX/VMS SYSTEM.
THE DISKS HAVE THE FOLLOWING PHYSICAL GEOMETRY:

RLOl
RL02

# CYL

TRACKS/
CYLINDER

SECTORS/
TRACK

BYTES/
SECTOR

MAXIMUM
BLOCKS

256
512

2
2

40
40

256
256

10240
20480

SINCE THE SECTOR SIZE IS ONLY 1/2 BLOCK, LOGICAL TO PHYSICAL
CONVERSION OF THE DISK ADDRESS IS DONE IN THE DRIVER STARTIO
ROUTINE RATHER THAN IN THE IOC$CVTLOGPHY FDT ROUTINE.
OVERLAPPED SEEKS ARE NOT ATTEMPTED BECAUSE THE DEVICE DOES

C-1

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

NOT INTERRUPT AT THE COMPLETION OF A SEEK.
ALSO, THE DEVICE DOES NOT PERFORM AN IMPLICIT SEEK WHEN PERFORMING
A READ OR WRITE FUNCTION,SO SEEK FUNCTIONS ARE ISSUED BY THIS
DRIVER WHERE NECESSARY PRIOR TO ISSUING A READ OR WRITE FUNCTION.
THE READ OR WRITE FUNCTION IS THEN ISSUED AS SOON AS TijE RLll
CONTROLLER BECOMES READY (WHILE THE SEEK rs IN PROGRESS), AND A
WAIT FOR INTERRUPT (UPON COMPLETION OF THE READ OR WRITE) IS
ISSUED. IF A SEEK FUNCTION IS REQUESTED SEPARATELY FROM A READ OR
WRITE, A DUMMY READ HEADER FUNCTION IS ISSUED FOLLOWING THE SEEK
FUNCTION AND A WAIT FOR INTERRUPT (UPON COMPLETION OF THE READ
HEADER) IS ISSUED.
THE IO$X_INHSEEK FUNCTION MODIFIER IS TREATED AS A NO-OP BY
THIS DRIVER, SINCE AN EXPLICIT SEEK IS NECESSARY FOR THE RL02
TO TRANSFER DATA PROPERLY.
THE RL'S DO NOT READ OR WRITE BEYOND THE END OF TRACK (THEY DO NOT
AUTOMATICALLY SEEK THE NEXT TRACK), SO ALL READ AND WRITE FUNCTIONS
ARE BROKEN UP BY THIS DRIVER INTO PARTIAL TRANSFERS TO THE END OF
TRACK, FOLLOWED BY A SEEK TO THE NEXT TRACK, THEN ANOTHER READ OR
WRITE FUNCTION UNTIL THE TOTAL DATA TRANSFER IS COMPLETE .
. PAGE
.SBTTL

EXTERNAL AND LOCAL DEFINITIONS

EXTERNAL SYMBOLS
$ADPDEF
$CRBDEF
$DCDEF
$DDBDEF
$DEVDEF
$DPTDEF
$DYNDEF
$EMBDEF
$IDBDEF
$IODEF
$IRPDEF
$PRDEF
$PTEDEF
$SSDEF
$UCBDEF
$VADEF
$VECDEF

;DEFINE ADAPTER CONTROL BLOCK
;DEFINE CHANNEL REQUEST BLOCK
;DEFINE DEVICE CLASS
;DEFINE DEVICE DATA BLOCK
;DEFINE DEVICE CHARACTERISTICS
;DEFINE DRIVER PROLOGUE TABLE
;DEFINE DYNAMIC DATA STRUCTURE TYPES
;DEFINE ERROR MESSAGE BUFFER
;DEFINE INTERRUPT DATA BLOCK
;DEFINE I/O FUNCTION CODES
;DEFINE I/O REQUEST PACKET
;DEFINE PROCESSOR REGISTERS
;DEFINE SYSTEM PTES
;DEFINE SYSTEM STATUS CODES
;DEFINE UNIT CONTROL BLOCK
;DEFINE VIRTUAL ADDRESS BITS
;DEFINE INTERRUPT VECTOR BLOCK

LOCAL MACROS
EXFUNCL
BRANCH TO SUBROUTINE WHICH REQUESTS CHANNEL (IF NOT ALREADY OWNED),
EXECUTES FCODE (OR R3) FUNCTION, AND BRANCHES TO BDST ON ERROR
.MACRO

.ENDM

C-2

EXFUNCL BDST,FCODE
.IF NB FCODE
MOVZBL #CD'FCODE,R3
.ENDC
BSBW
FEXL
.BYTE
BDST-.-1

;IS FCODE NONBLANK?
;IF NB - SPECIFY FCODE FUNCTION
;IF B - SPECIFY FNTN IN EXISTING R3
;EXECUTE FUNCTION
;WHERE TO GO IF ERROR

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

GENF
GENERATE FUNCTION TABLE ENTRY AND CASE TABLE INDEX SYMBOL
.MACRO

GENF FCODE
CD'FCODE=.-FTAB/2
.WORD
FCODE!RL_CS_M_IE

;FCODE WITH INT ENABLE BIT

.ENDM
CKPWR
DISABLE INTERRUPTS, CHECK IF POWER HAS FAILED,
AND PUT DEVICE UNIT NUMBER IN R2<9:8>
.MACRO

Ll:

CKPWR SAVE_RO=YES,?Ll
CLRL
R2
;CLEAR R2 FOR UNIT NUMBER
INSV
UCB$W UNIT(R5),- ;PUT UNIT# IN R2<9:8>
# 8 , # 2-;R2
, ...
DEVICELOCK LOCKADDR=UCB$L DLCK(R5),-; LOCK DEVICE ACCESS
LOCKIPL=UCB$B_DIPL(R5),-; RAISE IPL
SAVIPL=-(SP),- ;SAVE CURRENT IPL
PRESERVE='SAVE RO
SETIPL #31,- ;DISABLE ALL INTERRUPTS
ENVIRON=UNIPROCESSOR
BBC
#UCB$V POWER,- ;IF CLR - NO POWER FAILURE
UCB$W_STS(R5),Ll , ...
; POWERFAILURE!
DEVICEUNLOCK LOCKADDR=UCB$L_DLCK(R5),-; UNLOCK DEVICE ACCESS
NEWIPL=(SP)+,- ;RESTORE IPL
PRESERVE=' SAVE RO
BRW
RETREG
; EXIT
;RETURN FOR NO POWER FAILURE

.ENDM

LOCAL SYMBOLS
RL NUM REGS
RL SLM
UCB$B_DL_DCHEK

=4
=5
=UCB$W_OFFSET+l

;NUMBER OF DEVICE REGISTERS
;STATE=SEEK LINEAR MODE (READY TO GO)
;REDEFINE FOR DATA CHECK USE

UCB OFFSETS WHICH FOLLOW THE STANDARD UCB FIELDS
$DEFINI UCB

;START OF UCB DEFINITIONS

C-3

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

.=UCB$K LCL DISK LENGTH
$DEF
-UCB$W DL-PBCR
.BLKW
1
$DEF
UCB$W-DL-CS
1
.BLKW
$DEF
UCB$W-DL-BA
1
.BLKW
$DEF
UCB$W-DL-DA
.BLKW
1
$DEF
UCB$W-DL-MP
.BLKW
1
$DEF
UCB$W-DL-DPN
.BLKW
1
$DEF
UCB$L-DL-SVAPTE
$DEF
UCB$L-DL-DPR
.BLKL
1
$DEF
UCB$L-DL-BUFADR
$DEF
UCB$L-DL-FMPR
1
.BLKL
$DEF
UCB$A-DL-MOVRTN
$DEF
UCB$L-DL-PMPR
.BLKL
1
$DEF
UCB$B-DL-DPPE
.BLKB
1
$DEF
UCB$W-DL-DB
.BLKW
3
$DEF
UCB$B-DL-XBA
.BLKB
1
$DEF
UCB$W-DL-SBA
.BLKW
1
$DEF
UCB$A-DL-BUF VA .BLKL
1
$DEF
UCB$A-DL-BUF-PA .BLKL
1
$DEF
UCB$W-DL-FLAGS .BLKW
1
$VIELD UCB,0,<<DL_22BIT, ,M>,<DL_MAPPING,,M>,-

>
$DEF
$EQU

UCB$K DL LEN
.BLKW
UCB$K=DL=BUFSZ 20

$DEFEND UCB

;BEGIN DEFINITIONS AT END OF UCB
;PARTIAL BYTE COUNT
;CONTROL STATUS REGISTER
;BUS ADDRESS REGISTER
;DISK ADDRESS REGISTER
;MULTIPURPOSE REGISTER
;DATA PATH NUMBER
;SAVED SVAPTE OF THE USER'S BUFFER
;DATAPATH REGISTER
;USER BUFFER ADDRESS
;FINAL MAP REGISTER
;BUFFER MOVE ROUTINE ADDRESS
;PREVIOUS MAP REGISTER
;DATAPATH PURGE ERROR
;DATA BUFFER REGISTER
;BUS ADDRESS EXTENSION BITS
;SAVED BUFFER ADDRESS
;PHYSICAL BUFFER VIRTUAL ADDRESS
;PHYSICAL BUFFER PHYSICAL ADDRESS
;FLAGS
;START THE FLAG DEFINITIONS
;22 BIT ADDRESSING
;ADAPTER MAPPING
;END OF FLAG DEFINITIONS
;LENGTH OF UCB
;BUFFER SIZE = 40 SECTORS *
;256 BYTES/SECTOR / 512 BYTES/PAGE
;END OF UCB DEFINITIONS

RLll/RLOl REGISTER OFFSETS FROM CSR ADDRESS
; START OF REGISTER DEFINITIONS

$DEFINI RL
$DEF

RL CS
VIELD

.BLKW
RL_CS,O,<<DRDY, ,M>,<FCODE,3>,<XBA,2>,<IE,,M>,<CRDY,,M>,<DS,2>,<0PI, ,M>, <CRC,,M>,<DLT,,M>,<NXM,,M>,<DE, ,M>,<CE, ,M>-

;CONTROL STATUS REGISTER (CSR)
;START OF CSR BIT DEFINITIONS
DRIVE READY
FUNCTION CODE
BUS ADDRESS EXTENSION BITS
INTERRUPT ENABLE
CONTROLLER READY
DRIVE SELECT
OPERATION INCOMPLETE
DATA CRC OR HEADER CRC
DATA LATE OR HEADER NOT FOUND
NONEXISTENT MEMORY
DRIVE ERROR
COMPOSITE ERROR
;END CSR BIT DEFINITIONS

$DEF

RL BA

.BLKW

;BUS ADDRESS REGISTER (BAR)

$DEF

RL DA
VIELD

.BLKW
RL_DA,0,<<MRK,,M>,<STS,,M>,<,1>,<RST,,M>,<,12>,-

;DISK ADDRESS REGISTER (DAR)
;START OF DAR BIT DEFINITIONS
MARK (ALWAYS 1)
GET STATUS
RESERVED BIT
RESET
RESERVED BITS
;END OF DAR BIT DEFINITIONS

C-4

Sample Driver for the RL11, RL01, and RL02 Disk Drives

$DEF

RL MP
VI ELD

.BLKW
RL MP,0,<<STA,3>,<BH,,M>,<HO,,M>,<CO,,M>,<HS,,M>,<TYP,,M>,<DSE,,M>,<VC,,M>,<WGE, ,M>, <SPE,,M>,<SKTO,,M>,<WL,,M>,<CHE,,M>,<WDE, ,M>-

;MULTIPURPOSE REGISTER (MPR)
;START OF MPR BIT DEFINITIONS
DRIVE STATE
BRUSH HOME
HEADS OUT
COVER OPEN
HEAD SELECT
DRIVE TYPE
DRIVE SELECT ERROR
VOLUME CHECK
WRITE GATE ERROR
SPIN ERROR
SEEK TIME OUT
WRITE LOCK
CURRENT HEAD ERROR
WRITE DATA ERROR
;END MPR BIT DEFINITIONS

.BLKW

; BUS ADDRESS EXTENSION REGISTER(BAE)

>
$DEF

RL BAE
$DEFEND RL

;END RLll/RLOl REGISTER DEFINITIONS

HARDWARE FUNCTION CODES
F NOP=0*2
F UNLOAD=F NOP
F SEEK=3*2
F RECAL=F NOP
F DRVCLR=2*2
F RELEASE=F NOP
F OFFSET=F NOP
F RETCENTER=F NOP
F PACKACK=2*2
F- SEARCH=F- NOP
F WRITECHECK=1*2
F WRITEDATA=5*2
F WRITEHEAD=F NOP
F READDATA=6*2
F READHEAD=4*2
F AVAILABLE=F NOP
F GETSTATUS=2*2
.PAGE
.SBTTL

;NO OPERATION
;NO OPERATION
;SEEK CYLINDER
;NO OPERATION
;DRIVE CLEAR (GET STATUS)
;NO OPERATION
;NO OPERATION
;NO OPERATION
;PACK ACKNOWLEDGE (SET VOLUME VALID)
;NO OPERATION
;WRITE CHECK
;WRITE DATA
;NO OPERATION
;READ DATA
;READ HEADER
;NO OPERATION
;GET STATUS (DRIVER INTERNAL USE)

STANDARD TABLES

DRIVER PROLOGUE TABLE
THE DPT DESCRIBES DRIVER PARAMETERS AND I/O DATABASE FIELDS
THAT ARE TO BE INITIALIZED DURING DRIVER LOADING AND RELOADING
DP TAB
END=DL_END,ADAPTER=UBA,FLAGS=DPT$M SVP,UCBSIZE=UCB$K_DL_LEN,NAME=DLDRIVER

;DPT CREATION MACRO
;END OF DRIVER LABEL
;ADAPTER TYPE = UNIBUS
;SYSTEM PAGE-TABLE ENTRY REQUIRED
;LENGTH OF UCB
;DRIVER NAME

C-5

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

DPT STORE !NIT
;START CONTROL BLOCK !NIT VALUES
DPT STORE DDB,DDB$L ACPD,L,<AA\Fll\> ;DEFAULT ACP NAME
DPT STORE DDB,DDB$L-ACPD+3,B,DDB$K CART ;ACP CLASS
DPT STORE UCB,UCB$B-FLCK,B,SPL$C IOLOCK8 ;FORK LOCK INDEX
DPT STORE UCB,UCB$L-DEVCHAR,L,- ;DEVICE CHARACTERISTICS
<DEV$M FOD-FILES ORIENTED
!DEV$M-DIRDIRECTORY STRUCTURED
!DEV$M-AVLAVAILABLE
!DEV$M-ELGERROR LOGGING
!DEV$M-SHRSHAREABLE
!DEV$M-IDVINPUT DEVICE
!DEV$M-ODVOUTPUT DEVICE
!DEV$M-RND>
RANDOM ACCESS
DPT STORE UCB,UCB$L DEVCHAR2,L,-; DEVICE CHARACTERISTICS
<DEV$M NNM>PREFIX NAME WITH "node$"
DPT_STORE UCB,UCB$B_DEVCLASS,B,DC$_DISK ;DEVICE CLASS
DPT STORE UCB,UCB$W DEVBUFSIZ,W,512 ;DEFAULT BUFFER SIZE
DPT STORE UCB,UCB$B-SECTORS,B,40 ;NUMBER OF SECTORS PER TRACK
DPT STORE UCB,UCB$B-TRACKS,B,2 ;NUMBER OF TRACKS PER CYLINDER
DPT STORE UCB,UCB$B-DIPL,B,21
;DEVICE IPL
DPT STORE UCB,UCB$B-ERTMAX,B,8 ;MAX ERROR RETRY COUNT
DPT STORE UCB,UCB$W-DEVSTS,W,- ;INHIBIT LOG TO PHYS CONVERSION IN FDT
<UCB$M_NOCNVRT>
I

•••

DPT STORE REINIT
;START CONTROL BLOCK RE-INIT VALUES
DPT STORE CRB,CRB$L INTD+4,D,DL INT ;INTERRUPT SERVICE ROUTINE ADDRESS
DPT STORE CRB,CRB$L=INTD+VEC$L_INITIAL,- ;CONTROLLER INIT ADDRESS
D,DL_RLll_INIT
, ...
DPT STORE CRB,CRB$L_INTD+VEC$L_UNITINIT,- ;UNIT INIT ADDRESS
D,DL RLOX INIT
, ...
DPT STORE DDB,DDB$L_DDT~D,DL$DDT
;DDT ADDRESS
DPT STORE END

;END OF INITIALIZATION TABLE

DRIVER DISPATCH TABLE
THE DDT LISTS ENTRY POINTS FOR DRIVER SUBROUTINES WHICH ARE
CALLED BY THE OPERATING SYSTEM.
DDTAB

;DDT CREATION MACRO
DEVNAM=DL,;NAME OF DEVICE
START=DL_STARTIO,;START I/0 ROUTINE
UNSOLIC=DL_UNSOLNT,;UNSOLICITED INTERRUPT
FUNCTB=DL_FUNCTABLE,;FUNCTION DECISION TABLE
CANCEL=O,;CANCEL=NO-OP FOR FILES DEVICE
REGDMP=DL_REGDUMP,;REGISTER DUMP ROUTINE
DIAGBF=<<RL NUM REGS+5+5+3+1>*4>,- ;BYTES IN DIAG BUFFER
ERLGBF=<<<RL_NUM_REGS+5+1>*4>+EMB$L_DV_REGSAV> ;BYTES IN
;ERROR LOG BUFFER

DIAGNOSTIC BUFFER SIZE = <<4 RL02 REGISTER LONGWORDS + 5 UCB FIELD LONGWORDS
+ 5 IOC$DIAGBUFILL LONGWORDS + 3 BUFFER ALLOCATION
LONGWORDS + 1 LONGWORD FOR # REGISTERS IN DL REGDUMP>
* 4 BYTES/LONGWORD>
ERROR LOG BUFFER SIZE

C-6

<<<4 RL02 REGISTER LONGWORDS + 5 UCB FIELD LONGWORDS
+ 1 LONGWORD FOR # REGISTERS IN DL REGDUMP>
* 4 BYTES/LONGWORD> + BYTES NEEDED-FOR ERROR LOGGER
TO SAVE SOFTWARE REGISTERS>

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

HARDWARE FUNCTION CODE TABLE
THIS TABLE MERGES THE FUNCTION CODE BITS WITH THE
INTERRUPT ENABLE BIT AND GENERA-TES THE CASE TABLE
INDEX SYMBOL.
FTAB:

GENF
GENF
GENF
GENF
GENF
GENF
GENF
GENF
GENF
GENF
GENF
GENF
GENF
GENF
GENF
GENF
GENF
GENF

F NOP
F UNLOAD
F SEEK
F RECAL
F DRVCLR
F RELEASE
F OFFSET
F RETCENTER
F PACKACK
F SEARCH
F WRITECHECK
F WRITEDATA
F READDATA
F WRITEHEAD
F READHEAD
F NOP
F NOP
F AVAILABLE

;NO-OP
;UNLOAD VOLUME (NOP)
;SEEK
;RECALIBRATE (NOP)
;DRIVE CLEAR (RESET & GET STATUS)
;RELEASE PORT (NOP)
;OFFSET HEADS (NOP)
;RETURN HEADS TO CENTERLINE (NOP)
;PACK ACKNOWLEDGE (RESET & GET STATUS)
;SEARCH (NOP)
;WRITE CHECK
;WRITE DATA
;READ DATA
;WRITE HEADERS (NOP)
;READ HEADERS
;place holder
;place holder
;AVAILABLE

.PAGE
FUNCTION DECISION TABLE
THE FDT LISTS VALID FUNCTION CODES, SPECIFIES WHICH
CODES ARE BUFFERED, AND DESIGNATES SUBROUTINES TO
PERFORM PREPROCESSING FOR PARTICULAR FUNCTIONS.
DL FUNCTABLE:
FUNCTAB
<NOP,UNLOAD,SEEK,DRVCLR,PACKACK,SENSECHAR,SETCHAR,SENSEMODE,SETMODE,WRITECHECK,READHEAD,READLBLK,WRITELBLK,READPBLK,WRITEPBLK,READVBLK,WRITEVBLK,AVAILABLE,ACCESS,ACPCONTROL,CREATE,DEACCESS,DELETE,MODIFY,MOUNT-

;LIST LEGAL FUNCTIONS
NO-OP
UNLOAD
SEEK
DRIVE CLEAR
PACK ACKNOWLEDGE
SENSE CHARACTERISTICS
SET CHARACTERISTICS
SENSE MODE
SET MODE
WRITE CHECK
READ HEADER
READ LOGICAL BLOCK
WRITE LOGICAL BLOCK
READ PHYSICAL BLOCK
WRITE PHYSICAL BLOCK
READ VIRTUAL BLOCK
WRITE VIRTUAL BLOCK
AVAILABLE
ACCESS FILE / FIND DIRECTORY ENTRY
ACP CONTROL FUNCTION
CREATE FILE AND/OR DIRECTORY ENTRY
DEACCESS FILE
DELETE FILE AND/OR DIRECTORY ENTRY
MODIFY FILE ATTRIBUTES
MOUNT VOLUME

>
FUNCTAB
<NOP,-

;BUFFERED FUNCTIONS
; NO-OP

C-7

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

UNLOAD,SEEK,DRVCLR,PACKACK,SENSECHAR,SETCHAR,SENSEMODE,SETMODE,AVAILABLE,ACCESS,ACPCONTROL,CREATE,DEACCESS,DELETE,MODIFY,MOUNT>
FUNCTAB DL_ALIGN,<READHEAD,READLBLK,READPBLK,READVBLK,WRITECHECK,WRITELBLK,WRITEPBLK,WRITEVBLK-

UNLOAD
SEEK
DRIVE CLEAR
PACK ACKNOWLEDGE
SENSE CHARACTERISTICS
SET CHARACTERISTICS
SENSE MODE
SET MODE
AVAILABLE
ACCESS FILE / FIND DIRECTORY ENTRY
ACP CONTROL FUNCTION
CREATE FILE AND/OR DIRECTORY ENTRY
DEACCESS FILE
DELETE FILE AND/OR DIRECTORY ENTRY
MODIFY FILE ATTRIBUTES
MOUNT VOLUME
;TEST ALIGNMENT FUNCTIONS
READ HEADER
READ LOGICAL BLOCK
READ PHYSICAL BLOCK
READ VIRTUAL BLOCK
WRITE CHECK
WRITE LOGICAL BLOCK
WRITE PHYSICAL BLOCK
WRITE VIRTUAL BLOCK

FUNCTAB +ACP$READBLK,<READHEAD,READLBLK,READPBLK,READVBLK>
FUNCTAB +ACP$WRITEBLK,<WRITECHECK,WRITELBLK,WRITEPBLK,WRITEVBLK>
FUNCTAB +ACP$ACCESS,<ACCESS,CREATE>
FUNCTAB +ACP$DEACCESS,<DEACCESS-

;READ FUNCTIONS
READ HEADER
READ LOGICAL BLOCK
READ PHYSICAL BLOCK
READ VIRTUAL BLOCK
;WRITE FUNCTIONS
WRITE CHECK
WRITE LOGICAL BLOCK
WRITE PHYSICAL BLOCK
WRITE VIRTUAL BLOCK
;ACCESS FUNCTIONS
ACCESS FILE / FIND DIRECTORY ENTRY
; CREATE FILE AND/OR DIRECTORY ENTRY
;DEACCESS FUNCTION
; DEACCESS FILE

>
FUNCTAB +ACP$MODIFY,<ACPCONTROL,DELETE,MODIFY>
FUNCTAB +ACP$MOUNT,<MOUNT>
FUNCTAB +EXE$LCLDSKVALID,<UNLOAD,AVAILABLE,PACKACK>
FUNCTAB +EXE$ZEROPARM,<NOP,UNLOAD,DRVCLR,-

C-8

;MODIFY FUNCTIONS
ACP CONTROL FUNCTION
DELETE FILE AND/OR DIRECTORY ENTRY
MODIFY FILE ATTRIBUTES
;MOUNT FUNCTION
; MOUNT VOLUME
;LOCAL DISK VALID FUNCTIONS
;UNLOAD VOLUME
;UNIT AVAILABLE
;PACK ACKNOWLEDGE
;ZERO PARAMETER FUNCTIONS
NO-OP
UNLOAD
DRIVE CLEAR

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

PACKACK,AVAILABLE,>
FUNCTAB +EXE$0NEPARM,<SEEK>
FUNCTAB +EXE$SENSEMODE,<SENSECHAR,SENSEMODE-

PACK ACKNOWLEDGE
AVAILABLE
;ONE PARAMETER FUNCTION
; SEEK
;SENSE FUNCTIONS
SENSE CHARACTERISTICS
; SENSE MODE

>
FUNCTAB +EXE$SETCHAR,<SETCHAR,SETMODE-

;SET FUNCTIONS
SET CHARACTERISTICS
; SET MODE

>
.PAGE
.SBTTL

CONTROLLER INITIALIZATION ROUTINE

;++
FUNCTIONAL DESCRIPTION:
THIS ROUTINE IS A NO-OP FOR THE RLll BUT MUST BE INCLUDED
SINCE IT IS CALLED WHEN THE RL02 IS BOOTED AS A SYSTEM DEVICE.
THE OPERATING SYSTEM CALLS THIS ROUTINE:
- AT SYSTEM STARTUP
- DURING DRIVER LOADING
- DURING RECOVERY FROM POWER FAILURE
INPUTS:
R4
- CSR ADDRESS (DEVICE CONTROL STATUS REGISTER)
RS
- IDB ADDRESS (INTERRUPT DATA BLOCK)
R6
- DDB ADDRESS (DEVICE DATA BLOCK)
RS
- CRB ADDRESS (CHANNEL REQUEST BLOCK)
ALL INTERRUPTS ARE LOCKED OUT
OUTPUTS:
ALL REGISTERS EXCEPT RO-R3 ARE PRESERVED.
CONTROL IS RETURNED TO THE CALLER.
;--

DL RLll INIT:

;CONTROLLER INITIALIZATION

FOR MICROVAX I, ALLOCATE A PHYSICALLY CONTIGUOUS BUFFER
AREA FOR PERFORMING I/O.
ADPDISP SELECT=ADAP MAPPING,ADDRLIST=<<YES,20$>>,CRBADDR=R8,SCRATCH=RO

Allocate a physically contiguous
buffer for those adapters that
don't support mapping.

10$:

MOVZWL
JSB
BLBC
MOVL
RSB

#UCB$K DL BUFSZ,Rl
GAEXE$ALOPHYCNTG
R0,20$
R2,CRB$L_AUXSTRUC(R8)

;LOAD SIZE OF BUFFER
;ALLOCATE PHYSICALLY CONTIGUOUS MEMORY
;EXIT ON ERROR
;GET BUFFER VIRTUAL ADDRESS
;RETURN TO CALLER

20$:

CLRL
RSB
.PAGE
.SBTTL

CRB$L_AUXSTRUC(R8)

;INDICATE MEMORY ALLOCATION FAILURE
;RETURN TO CALLER

UNIT INITIALIZATION ROUTINE

C-9

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

;++

DL_RLOX_INIT - UNIT INITIALIZATION ROUTINE
FUNCTIONAL DESCRIPTION:
THIS ROUTINE READIES THE RL01/RL02 UNITS FOR I/0 OPERATIONS.
THE OPERATING SYSTEM CALLS THIS ROUTINE:
- AT SYSTEM STARTUP
- DURING DRIVER LOADING
- DURING RECOVERY FROM POWER FAILURE
INPUTS:
R4
RS

- CSR ADDRESS (CONTROLLER STATUS REGISTER)
- UCB ADDRESS (UNIT CONTROL BLOCK)

OUTPUTS:
THE DRIVE UNIT IS RESET, UCB FIELDS ARE INITIALIZED, AND THE
ROUTINE WAITS FOR ONLINE UNITS TO SPIN UP. ALL REGISTERS
EXCEPT R0-R3 ARE PRESERVED.

DL- RLOX- INIT:
MOVW

2$:

3$:
10$:

#l@UCB$V DL MAPPING,UCB$W_DL=FLAGS (RS)
ADPDISP SELECT=ADAP_MAPPING,ADDRLIST=<<YES,2$>>,UCBADDR=RS,SCRATCH=RO
CLRW
UCB$W_DL_FLAGS(RS)
ADPDISP SELECT=ADDR BITS,ADDRLIST=<<l8,3$>>,ADPADDR=RO
BISW
#l@UCB$V DL 22BIT,UCB$W_DL=FLAGS (RS)
MOVZWL
BICW

;RL01/RL02 UNIT INITIALIZATION
DEFAULT TO ADAPTER MAPPING
; AND 18 BIT ADDRESSING

Clear adapter mapping bit

FOR MICROVAX II 22-BIT
ADDRESSING AS WELL AS ADAPTER MAPPING

UCB$W STS(RS),R3
;SAVE CURRENT UNIT STATUS
#UCB$M ONLINE!UCB$M VALID,- ;ASSUME OFFLINE/INVALID
UCB$W_STS (RS)
, ...

WAIT FOR CONTROLLER (6 SECONDS MAX) IF CHANNEL IS BUSY WITH ANOTHER UNIT
MOVL
UCB$L CRB(RS),RO
;GET CRB ADDRESS
BBC
#CRB$V BSY,CRB$B MASK(R0),20$ ;IF CLEAR - CHANNEL NOT BUSY
TIMEDWAIT TIME~#600*1000;;6 SECOND WAIT LOOP
INSl=<TSTB
RL_CS(R4)>,- ;IS CONTROLLER READY
INS2=<BLSS
1S$>,- ;IF LSS - YES
DONELBL=1S$
;LABEL TO EXIT WAIT LOOP
BLBC
R0,2S$
;TIME EXPIRED - EXIT
GET CURRENT DRIVE STATUS AND RESET DRIVE

C-10

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

20$:

MOVW
CLRL
INSV
BISW3
BSBW
TSTB
BGEQ

#RL_DA_M_RST!;PUT RESET AND GET STATUS IN DAR
RL_DA_M_STS!RL_DA__M_MRK,RL DA(R4)
, ...
Rl
;CLEAR Rl FOR UNIT NUMBER
UCB$W UNIT(RS),#8,#8,Rl ;GET UNIT NUMBER
Rl,#F=GETSTATUS,RL_CS(R4)
;EXECUTE GET STATUS FUNCTION
DL_WAIT
;WAIT FOR CONTROLLER
RL_CS(R4)
;WAS CONTROLLER READY?
25$
;IF GEQ - NO

CLASSIFY DRIVE TYPE

MOVW
MOVZWL
BRB

#AX2324C001,UCB$L MEDIA ID(RS)
;SET MEDIA IDENT "DL RLOl"
#RL MP-M TYP~RL MP(R4)
;IS DRIVE TYPE
RL02?
30$- - ;IF NEQ - YES
SA#DT$ RL01,UCB$B-DEVTYPE (R5)
;SET RLOl DEVICE TYPE
#256,UCB$W CYLINDERS(RS);SET NUMBER OF RLOl CYLINDERS
#10240,UCB$L MAXBLOCK(RS) ;SET MAX RLOl BLOCK NUMBER
40$
-

BRB

70$

30$:

MOVB

40$:

MOVW
MOVZWL
INCL
BBC

SA#DT$ RL02,UCB$B-DEVTYPE (R5)
;SET RL02 DEVICE TYPE
#512,UCB$W CYLINDERS(RS);SET NUMBER OF RL02 CYLINDERS
#20480,UCB$L MAXBLOCK(R5) ;SET MAX RL02 BLOCK NUMBER
UCB$L MEDIA ID (RS)
; SET MEDIA IDENT "DL RL02"
#UCB$V VALID,R3,60$
Branch around wait for drive to spin up
if the drive did NOT have a VALID
volume on it before POWER failure.

MOVL
BITW
BNEQ
MOVB

25$:

;BRANCH TO COMMON EXIT

INITIALIZE UCB FIELDS AND WAIT FOR ONLINE UNITS TO SPIN UP
45$:

BITW
BNEQ
JSB
BLBS
BRB

#RL CS M DRDY,RL CS(R4)
50$- - GAEXE$PWRTIMCHK
R0,45$
60$

; Is drive ready?
;IF NEQ - YES
;IS MAX TIME EXCEEDED?
;IF LBS - NO, STILL MORE TIME NEEDED
;POWER UP TIME EXCEEDED

BISW

#UCB$M_VALID,UCB$W_STS(R5) ;SET UCB STATUS VOLUME VALID

50$:

C-11

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

60$:

65$:
70$:

BBS
MOVL
MOVL
BEQL
MOVL
EXTZV
MOVL
MOVL
BICL3
ASSUME
INSV
MOVL
BISW
RSB
.PAGE
.SBTTL

#UCB$V DL MAPPING,;ADAPTER MAPPING?
UCB$W DL FLAGS(RS),65$ ;IF BS YES
UCB$L=CRB(R5),Rl
;GET CRB ADDRESS
CRB$L_AUXSTRUC(Rl),R2
;MEMORY ALLOC FAILURE DURING CTL INIT?
70$
;IF EQL YES, LEAVE OFFLINE
R2,UCB$A DL BUF VA(R5)
;SAVE BUFFER'S VIRTUAL ADDRESS
#VA$V VPN,#VA$S-VPN,R2,Rl;GET VIRTUAL PAGE NUMBER OF BUFFER
GAMMG$GL_SPTBASE,RO
;GET BASE ADDRESS OF SPTS
(RO) [Rl],RO
;GET THE PTE CONTENTS
#AC<VA$M_BYTE>,R2,Rl
;GET BUFFER OFFSET (BA00-BA08)
PTE$S PFN GE 13
R0,#9~#13,Rl
;COPY BA09-BA21
Rl,UCB$A DL BUF PA(R5)
;SAVE PHYSICAL ADDRESS OF BUFFER
#UCB$M_ONLINE,UCB$W_STS(R5)
;SET UCB STATUS VOLUME VALID

DRIVER SPECIFIC SUBROUTINES

DL WAIT - WAIT FOR CONTROLLER READY
INPUTS:
R4

- DEVICE CSR ADDRESS

FUNCTIONAL DESCRIPTION:
THIS ROUTINE IS CALLED FROM THE DRIVER UNIT INITIALIZATION ROUTINE
TO WAIT UNTIL THE RLll CONTROLLER IS READY. TO PREVENT HANGING UP
AT HIGH IPL, A MAXIMUM OF 30 USEC ELAPSES BEFORE CONTROL IS
RETURNED TO THE CALLER.
DL WAIT:

;WAIT FOR CONTROLLER READY
MOVQ
RO,-(SP)
;SAVE RO, Rl
TIMEWAIT
#3,#RL_CS_M_CRDY,RL_CS(R4),W
MOVQ
(SP)+,RO
;RESTORE RO, Rl
RSB
;RETURN TO UNIT INIT OR STARTIO
.PAGE
.SBTTL FDT ROUTINE - TEST TRANSFER BYTE COUNT ALIGNMENT

;++
DL ALIGN - FDT ROUTINE TO TEST XFER BYTE COUNT
FUNCTIONAL DESCRIPTION:
THIS ROUTINE IS CALLED FROM THE FUNCTION DECISION TABLE DISPATCHER
TO CHECK THE BYTE COUNT PARAMETER SPECIFIED BY THE USER PROCESS
FOR AN EVEN NUMBER OF BYTES (WORD BOUNDARY) .
INPUTS:
R3
R4
RS
R6
R7
R8
4 (AP)

IRP ADDRESS (I/O REQUEST PACKET)
PCB ADDRESS (PROCESS CONTROL BLOCK)
UCB ADDRESS (UNIT CONTROL BLOCK)
CCB ADDRESS (CHANNEL CONTROL BLOCK)
BIT NUMBER OF THE I/O FUNCTION CODE
ADDRESS OF FDT TABLE ENTRY FOR THIS ROUTINE
ADDRESS OF FIRST FUNCTION DEPENDENT QIO PARAMETER

OUTPUTS:
IF THE QIO BYTE COUNT PARAMETER IS ODD, THE I/0 OPERATION IS
TERMINATED WITH AN ERROR. IF IT IS EVEN, CONTROL IS RETURNED
TO THE FDT DISPATCHER.

C-12

Sample Driver for the RL11, RL01, and RL02 Disk Drives

DL ALIGN:
BLBS
RSB
10$:
MOVZWL
JMP
.PAGE
.SBTTL

4{AP),10$
#SS$ IVBUFLEN,RO
G"EXE$ABORTIO

;CHECK BYTE COUNT AT Pl{AP)
;IF LBS - ODD BYTE COUNT
;EVEN - RETURN TO CALLER
;SET BUFFER ALIGNMENT STATUS
;ABORT I/O

START I/O ROUTINE

;++
DL STARTIO - START I/0 ROUTINE
FUNCTIONAL DESCRIPTION:
THIS FORK PROCESS IS ENTERED FROM THE EXECUTIVE AFTER AN I/0 REQUEST
PACKET HAS BEEN DEQUEUED, AND PERFORMS THE FOLLOWING:
- ACTIVATES THE DISK AFTER SETTING UCB FIELDS, OBTAINING
UBA AND CONTROLLER RESOURCES, AND SETTING RLll REGISTERS
- WAITS FOR AN INTERRUPT
- REGAINS CONTROL AFTER THE ISR SERVICES THE INTERRUPT, AND
REACTIVATES THE DISK IF THE ORIGINAL FUNCTION
IS NOT YET COMPLETE, OR
COMPLETES THE I/O REQUEST BY RELEASING RESOURCES,
SETTING STATUS CODES, AND RETURNING TO THE EXECUTIVE.
INPUTS:

R3
RS
IRP$L_MEDIA

- IRP ADDRESS {I/O REQUEST PACKET)
- UCB ADDRESS {UNIT CONTROL BLOCK)
- PARAMETER LONGWORD {LOGICAL BLOCK NUMBER)

OUTPUTS:
RO
Rl

- FIRST I/O STATUS LONGWORD: STATUS CODE & BYTES XFERED
- SECOND I/O STATUS LONGWORD: 0 FOR DISKS

THE I/0 FUNCTION IS EXECUTED.
ALL REGISTERS EXCEPT RO-R4 ARE PRESERVED.

;START I/0 OPERATION

DL STARTIO:
COMPUTE PHYSICAL MEDIA ADDRESS

LBN = LBN * {SECTORS/BLOCK)
LBN/{SECTORS/TRACK)
D +SECTOR
D/{TRACKS/CYLINDER) =CYLINDER+ TRACK

PREPROCESS UCB FIELDS

C-13

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

PREPROCESS:
MOVL
BBS
MULL3
MOVZBL
CLRL
EDIV
MOVZBL
EDIV
MOVB
MOVW

IRP$L_MEDIA(R3),Copy given MEDIA address (logical)
UCB$L MEDIA(R5)
to the UCB.
#IRP$V_PHYSIO, ;IF SET - PHYSICAL I/O
IRP$W STS(R3),10$
#2,UCB$L_MEDIA(R5),RO
;SCALE LBN IN RO
UCB$B_SECTORS(R5),R2
;GET NUMBER OF SECTORS PER TRACK
Rl
;CLEAR HIGH PART OF DIVIDEND
R2,RO,RO,UCB$L MEDIA(R5);CALCULATE SECTOR NUMBER AND STORE
UCB$B_TRACKS(RS),R2
;GET NUMBER OF TRACKS PER CYLINDER
R2,RO,RO,Rl
;CALCULATE TRACK AND CYLINDER
Rl,UCB$L MEDIA+l(R5)
;STORE TRACK NUMBER
RO,UCB$L=MEDIA+2(R5)
;STORE CYLINDER NUMBER

10$:
MOVB
MNEGW
CLRW
CLRB
MOVW
EXTZV
MOVB
CMPB
BNEQ
MOVW

UCB$B_ERTMAX(R5),;INITIALIZE ERROR RETRY COUNT
UCB$B ERTCNT(R5)
, ...
UCB$W-BCNT(R5),UCB$W BCR(R5)
;INIT NEG BYTES LEFT TO XFER
UCB$W=DL_DPN(R5)
;CLEAR DATA PATH NO. FOR USE AS;UBA RESOURCE ALLOCATION FLAG
UCB$B_DL_DPPE(R5)
;CLEAR DATAPATH PURGE ERROR REGISTER
IRP$W FUNC(R3),UCB$W FUNC(R5)
;SAVE FUNCTION CODE
#IRP$V FCODE,;EXTRACT I/O FUNCTION CODE
#IRP$S-FCODE,IRP$W FUNC(R3),Rl , ...
Rl,UCB$B_FEX(R5) ;STORE FUNCTION DISPATCH INDEX
#IO$ SEEK,Rl
;SEEK FUNCTION?
20$ ;IF NEQ - NO
IRP$L MEDIA(R3),;STORE CYLINDER ADDRESS
UCB$W=DC(R5)
, ...

20$:
BICW
BBC
BISW

#UCB$M_DIAGBUF,UCB$W DEVSTS(R5)
;CLR DIAGNOSTIC BUFFER PRESENT
#IRP$V_DIAGBUF,;IF CLR - NO DIAG BUFFER
IRP$W STS(R3),FDISPATCH, ...
#UCB$M_DIAGBUF,UCB$W_DEVSTS(R5)
;SET DIAG BUFFER PRESENT

CENTRAL FUNCTION DISPATCH
FDISPATCH:
MOVL
BBS
BBS

10$:

C-14

MOVZWL
BRW
CLRB
MOVZBL
CASE

UCB$L IRP(R5),R3
#IRP$V PHYSIO,IRP$W STS(R3),10$
#UCB$V VALID,UCB$W STS(RS),10$
#SS$_VOLINV,RO
RESETXFR
UCB$B_DL_DCHEK(R5)
UCB$B_FEX(R5),R3
R3,<UNLOAD,SEEK,NOP,DRVCLR,NOP,NOP,NOP,PACKACK,NOP,WRITECHECK,WRITEDATA,READDATA,NOP,READHEAD,-

;FUNCTION DISPATCH
;GET IRP ADDRESS
;IF SET - PHYSICAL I/O FUNCTION
;IF SET - VOLUME SOFTWARE VALID
;SET VOLUME INVALID STATUS
;RESET BYTE COUNT AND EXIT
;CLEAR DATA CHECK IN PROGRESS
;GET FUNCTION DISPATCH INDEX
;DISPATCH TO FUNCTION HANDLING ROUTINE
UNLOAD
SEEK
RECALIBRATE (unsupported)
DRVCLR
RELEASE PORT (unsupported)
OFFSET HEADS (unsupported)
RETURN TO CENTER (unsupported)
PACK ACKNOWLEDGE
SEARCH (unsupported)
WRITE CHECK
WRITE DATA
READ DATA
WRITE HEADER (unsupported)
READ HEADER

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

NOP,NOP,AVAILABLE>, LIMIT=#CDF_UNLOAD

place holder
place holder
AVAILABLE

NOP:
SEEK:
DRVCLR:
DO_FUNCTION:
EXFUNCL RETRYERR
BRB
NORMAL

;NO-OP
;SEEK
;DRIVE CLEAR (GET STATUS & RESET)

PACKACK:

;PACK ACKNOWLEDGE (GET STATUS & RESET)
;Set software volume valid bit.

BISW
BRB
UNLOAD:
AVAILABLE:
BICW
BRB
WRITECHECK:
READHEAD:
BICW

#UCB$M VALID, UCB$W_jTS(R5)
DO FUNCTION

;EXECUTE FUNCTION - RETRY IF FAILURE
;SUCCESSFUL - EXIT WITH NORMAL STATUS

;Then go do hardware function.

#UCB$M VALID, UCB$W_STS(R5)
NORMAL

;UNLOAD
;AVAILABLE
;Clear software volume valid bit.
;and go complete operation without
;any hardware interaction.

#I0$M DATACHECK,UCB$W=FUNC(R5)

;WRITE CHECK
;READ HEADER
;CLEAR DATA CHECK REQUEST;TO PREVENT EXTRA WRITE CHECK

WRITEDATA:
READDATA:
EXFUNCL RETRYERR,F_SEEK
MOVZBL UCB$B_FEX(R5),R3
EXFUNCL RETRYERR

;WRITE DATA
;READ DATA
;EXECUTE EXPLICIT SEEK - RETRY IF FAIL
;GET FUNCTION DISPATCH INDEX
;EXECUTE TRANSFER FUNCTION

OPERATON COMPLETION

NORMAL:
MOVZWL
BRW
RETRYERR:
DECB
BEQL
BRW
FATALERR:
MOVZWL
BBS
MOVZWL
BBC
BBS
5$:

MOVZWL
TSTB
BEQL
BBS
BBS

#SS$_NORMAL,RO
FUNCXT

;SUCCESSFUL OPERATION COMPLETE
;SET NORMAL COMPLETION STATUS
;FUNCTION EXIT

UCB$B_ERTCNT(R5)
FATALERR
FDISPATCH

;RETRIABLE ERROR
;ANY RETRIES LEFT?
;IF EQL - NO
; RETRY FUNCTION

#SS$ VOLINV,RO
#RL MP v vc,UCB$W_DL=MP (R5) ,FUNCXT

;UNRECOVERABLE ERROR
;ASSUME VOLUME INVALID STATUS
;IF SET - VOLUME INVALID

#SS$ WRITLCK,RO
#RL MP v WL,UCB$w_DL=MP (R5) ,5$
#RL MPV WGE,UCB$W_DL=MP (R5) ,FUNCXT

;ASSUME WRITE LOCK ERROR STATUS
;IF CLR - VOLUME NOT WRITE LOCKED

#SS$ DATACHECK,RO
UCB$B DL DCHEK(R5)
10$ #RL_CS_V_OPI,UCB$W DL CS(RS),10$
#RL_CS_V=CRC,UCB$W_DL_CS (R5) ,FUNCXT

;ASSUME DATA CHECK ERROR STATUS
;WRITE CHECK IN PROGRESS?
;IF EQL - NO
;IF SET - NOT WRITE CHECK ERROR

;IF SET - WRITE GATE ERROR
;IF WL & WGE SET - WRITE LOCK ERROR

;IF SET - WRITE CHECK ERROR

C-15

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

10$:

MOVZWL
BBS

#SS$_PARITY,RO
#RL CS V CRC,UCB$W_DL=CS (R5) ,FUNCXT

;ASSUME PARITY ERROR STATUS
;IF SET - CRC ERROR
;OR DATAPATH PURGE ERROR

20$:

MOVZWL
BBS

#SS$_DRVERR,RO
#RL_CS_V_DE,UCB$W_DL_CS(R5) ,FUNCXT

;ASSUME DRIVE ERROR STATUS
;IF SET - DRIVE ERROR

MOVZWL

#SS$_CTRLERR,RO

;ASSUME CONTROLLER ERROR STATUS

FUNCXT:

;FUNCTION EXIT
RO
;SAVE FINAL REQUEST STATUS
GAIOC$DIAGBUFILL
;FILL DIAGNOSTIC BUFFER IF PRESENT
#CDF WRITECHECK,UCB$B_FEX(R5)
;DRIVE RELATED FUNCTION?
10$
;IF GTRU - YES
#CDF_AVAILABLE,UCB$B_FEX(R5)
;DRIVE RELATED FUNCTION?
10$
;IF EQL - YES
UCB$L_IRP(R5),R3
;RETRIEVE ADDRESS OF IRP
UCB$W_BCR(R5),;CALCULATE BYTES TRANSFERRED
IRP$W_BCNT(R3),2(SP)
TSTW
UCB$W_DL_DPN(R5)
;ARE UBA RESOURCES ALLOCATED?
BEQL
20$
;IF EQL - NO
BBC
#UCB$V DL MAPPING,;ADAPTER MAPPING?
UCB$W_DL_FLAGS(R5),10$ ;IF BC NO
RELDPR
;RELEASE DATA PATH
RELMPR
;RELEASE MAP REGISTERS
BRB
20$
;JOIN COMMON CODE
MOVL
UCB$L_DL_SVAPTE(R5),;RESTORE ORIGINAL SVAPTE
UCB$L_SVAPTE(R5)
REL CHAN
;RELEASE CHANNEL IF OWNED
PUSHL
JSB
CMPB
BGTRU
CMPB
BEQL
MOVL
ADDW3

10$:
20$:

CLRL
POPL
RE QC OM
.PAGE

Rl
RO

•••

;CLEAR SECOND STATUS LONGWORD
;RETRIEVE FINAL REQUEST STATUS
;COMPLETE REQUEST

FEXL - RLll HARDWARE FUNCTION EXECUTION
THIS ROUTINE IS CALLED VIA A BSB WITH A BYTE IMMEDIATELY FOLLOWING THAT
SPECIFIES THE ADDRESS OF AN ERROR ROUTINE. ALL DATA IS ASSUMED TO HAVE BEEN
SET UP IN THE UCB BEFORE THE CALL. THE APPROPRIATE PARAMETERS ARE LOADED
INTO DEVICE REGISTERS AND THE FUNCTION IS INITIATED. THE RETURN ADDRESS
IS STORED IN THE UCB AND A WAIT FOR INTERRUPT IS EXECUTED. WHEN THE
INTERRUPT OCCURS, CONTROL IS RETURNED TO THE CALLER.
INPUTS:
R3
RS

FUNCTION TABLE DISPATCH INDEX
DEVICE UNIT UCB ADDRESS

OO(SP)
04(SP)

RETURN ADDRESS OF CALLER
RETURN ADDRESS OF CALLER'S CALLER

IMMEDIATELY FOLLOWING INLINE AT THE CALL SITE IS A BYTE WHICH CONTAINS
A BRANCH DESTINATION TO AN ERROR RETRY ROUTINE.
OUTPUTS:
THERE ARE FOUR EXITS FROM THIS ROUTINE:
1. SPECIAL CONDITION - THIS EXIT IS TAKEN IF A POWER FAILURE OCCURS
OR THE OPERATION TIMES OUT. IT IS A JUMP TO THE APPROPRIATE
ERROR ROUTINE.
2. FATAL ERROR - THIS EXIT IS TAKEN IF A FATAL CONTROLLER OR DRIVE

C-16

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

ERROR OCCURS OR IF ANY ERROR OCCURS AND ERROR RETRY IS EITHER
INHIBITED OR EXHAUSTED. IT IS A JUMP TO THE FATAL ERROR EXIT
ROUTINE.
3. RETRIABLE ERROR - THIS EXIT IS TAKEN IF A RETRIABLE CONTROLLER
OR DRIVE ERROR OCCURS AND ERROR RETRY IS NEITHER INHIBITED
NOR EXHAUSTED. IT CONSISTS OF TAKING THE ERROR BRANCH EXIT
SPECIFIED AT THE CALL SITE.
4. SUCCESSFUL OPERATION - THIS EXIT IS TAKEN IF NO ERRORS OCCUR
DURING THE OPERATION. IT CONSISTS OF A RETURN INLINE.
IN ALL CASES IF AN ERROR OCCURS, AN ATTEMPT IS MADE TO LOG THE ERROR.
IN ALL CASES FINAL DEVICE REGISTERS ARE RETURNED VIA THE UCB.
UCB$W_BCR(R5)

NEGATIVE BYTES REMAINING TO TRANSFER

.PAGE
FEXL:

10$:

;FUNCTION EXECUTOR
POPL
UCB$L DPC(R5)
;SAVE DRIVER PC VALUE
MOVB
R3,UCB$B_CEX(R5)
;SAVE CASE INDEX
MOVL
UCB$L_CRB(R5),RO
;GET ADDRESS OF PRIMARY CRB
MOVL
CRB$L INTD+VEC$L IDB(RO),Rl ;GET ADDRESS OF IDB
CMPL
R5,IDB$L OWNER(Rl)
;DOES THIS PROCESS OWN CHANNEL?
10$
;IF NEQ - NO
BNEQ
MOVL
IDB$L CSR(Rl),R4
;SET ASSIGNED CHANNEL CSR ADDRESS
20$ BRB
REQPCHAN
;REQUEST CHANNEL (RETURNS R4 = CSR ADR)

20$:

CASE

BRW
.PAGE

R3,<IMMED,IMMED,POSIT,IMMED,DRCLR,IMMED,IMMED,IMMED,DRCLR,IMMED,>
XFER

;DISPATCH TO PROPER FUNCTION ROUTINE
;NO OPERATION
;UNLOAD VOLUME (NOP)
;SEEK CYLINDER
;RECALIBRATE (NOP)
;DRIVE CLEAR (GET STATUS & RESET)
;RELEASE DRIVE (NOP)
;OFFSET HEADS (NOP)
;RETURN TO CENTERLINE (NOP)
;PACK ACKNOWLEDGE
;SEARCH (NOP)
;TRANSFER FUNCTION

IMMEDIATE FUNCTION EXECUTION
FUNCTIONS INCLUDE:
NO OPERATION,
DRIVE CLEAR, AND
PACK ACKNOWLEDGE
INPUTS:
R3
R4
R5

- CASE INDEX
- CSR ADDRESS
- UCB ADDRESS

FUNCTIONAL DESRIPTION:
INTERRUPTS ARE LOCKED OUT, THE APPROPRIATE FUNCTION IS INITIATED WITH
INTERRUPT ENABLE, AND A WAIT FOR INTERRUPT AND KEEP CHANNEL IS EXECUTED.

C-17

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

DRCLR:
BISW

;DRIVE CLEAR
#RL_DA_M_STS!;SET GETSTATUS,RESET,AND MARK IN DAR
RL DAM RST!RL_DA_M_MRK,RL_DA(R4)
I

IMMED:
CKPWR

SAVE RO=NO

BISW3
R2,FTAB[R3],RL CS(R4)
WFIKPCH RETREG,#2
IOFORK
BRW
.PAGE

•••

;IMMEDIATE FUNCTION EXECUTION
;DISABLE INTERRUPTS, CHECK POWER,;AND PUT UNIT NUMBER IN R2<9:8>
;MERGE UNIT WITH FNTN AND EXECUTE
;WAIT FOR INTERRUPT
;RETURN FROM ISR;CREATE FORK PROCESS (&JSB BACK TO ISR)

RETREG

POSITIONING FUNCTION EXECUTION
FUNCTIONS INCLUDE:
SEEK CYLINDER
INPUTS:
R3
R4
R5

- CASE INDEX
- DEVICE CSR ADDRESS
- UCB ADDRESS

FUNCTIONAL DESRIPTION:
THE CYLINDER DIFFERENCE WORD IS CALCULATED AND LOADED INTO THE DISK
ADDRESS REGISTER, INTERRUPTS ARE LOCKED OUT, AND THE SEEK FUNCTION
rs INITIATED WITHOUT INTERRUPT ENABLE. THE CONTROLLER IS THEN POLLED
FOR READY, AND DEVICE INTERRUPTS ARE ENABLED.
SINCE THE RL01/RL02 DO NOT ISSUE AN INTERRUPT UPON COMPLETION OF A
SEEK, OVERLAPPED SEEKS ARE NOT ATTEMPTED, AND ONE OF THE FOLLOWING IS
PERFORMED.
IF ONLY A SEEK FUNCTION IS BEING REQUESTED, A DUMMY READ HEADER
FUNCTION IS ISSUED AND A WAITFOR INTERRUPT IS INITIATED.
THE READ HEADER IS USED TO SIGNAL THE END OF THE SEEK, SINCE IT
WILL ISSUE AN INTERRUPT SHORTLY (315 USEC AVG) AFTER THE SEEK IS
COMPLETE. IT WILL ALSO SENSE FOR A TIMEOUT DURING THE SEEK.
IF THE SEEK IS ASSOCIATED WITH A DATA TRANSFER REQUEST (RL01/RL02
TRANSFER FUNCTIONS REQUIRE EXPLICIT SEEKS), THE PROGRAM KEEPS THE
CHANNEL AND RETURNS TO FDISPATCH TO ISSUE THE TRANSFER REQUEST
WHILE THE SEEK IS STILL IN PROGRESS. WHEN THE SEEK COMPLETES, THE
RLll CONTROLLER WILL BEGIN THE TRANSFER.

C-18

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

;POSITIONING FUNCTION

POSIT:
OBTAIN CURRENT DISK ADDRESS

IF THERE HAS NOT BEEN A PREVIOUS TRANSFER DURING THIS REQUEST,
A READ HEADER IS EXECUTED TO DETERMINE THE CURRENT DISK ADDRESS.

5$:
10$:
20$:

40$:
50$:

TSTW
BEQL
BICW3
BRW
BRW
MOVZBL
CKPWR

UCB$W_DL_DPN(R5)
;WAS THERE A PREVIOUS TRANSFER?
10$
;IF EQL - NO, READ HEADER
#A077,UCB$W DL DA(R5),Rl ;PUT CURRENT CYL & SURFACE IN Rl
60$
- ;CALCULATE DIFFERENCE WORD
50$
;CONTINUE
#8,R3
;SET READ HEADER RETRY COUNT IN R3
SAVE RO=NO
;DISABLE INTERRUPTS, CHECK POWER,;AND PUT UNIT NUMBER IN R2<9:8>
R2,#F_READHEAD!RL_CS_M_IE,- ;EXECUTE READ HEADER
BISW3
RL_CS(R4)
, ...
;WAIT FOR INTERRUPT OR TIMEOUT
WFIKPCH 40$,#2
IO FORK
;CREATE FORK PROCESS
BBC
#RL_CS_V_CE,UCB$W_DL_CS(R5),5$ ;BR ON NO ERRORS
DECB
R3
;DECREMENT READ HEADER RETRY COUNT
BNEQ
20$
;IF NEQ - RETRY READ HEADER
;IF EQL - READ HEADER RETRY EXHAUSTED ;TRY PREVIOUS TRACK
MOVZBW #AX80!RL_DA_M_MRK,;LOAD REVERSE SEEK DIFFERENCE WORD
RL_DA(R4)
CKPWR
;DISABLE INTERRUPTS, CHECK POWER,SAVE RO=NO
;AND PUT UNIT NUMBER IN R2<9:8>
BISW3
R2,#F_SEEK!RL_CS_M_IE,- ;EXECUTE REVERSE SEEK
RL_CS(R4)
, ...
WFIKPCH 40$,#2
;WAIT FOR SEEK TO BEGIN (INTERRUPT)
IO FORK
;CREATE FORK PROCESS
CKPWR
SAVE RO=NO
;DISABLE INTERRUPTS, CHECK POWER,;AND PUT UNIT NUMBER IN R2<9:8>
BISW3
R2,#F_READHEAD!RL_CS_M_IE,- ;TRY READ HEADER ON NEW TRACK
RL CS (R4)
, ...
WFIKPCH 40$,#2
;WAITFOR INTERRUPT OR TIMEOUT
IOFORK
;CREATE FORK PROCESS
BBC
#RL_CS_V_CE,UCB$W_DL_CS(R5),50$ ;BR IF NO HEADER ERROR
;CANNOT READ CURRENT DISK ADDRESS
CLRB
UCB$B_ERTCNT(R5)
;CLEAR RETRY COUNT
BRW
RETREG
;FOUND CURRENT DISK ADDRESS
BICW3
#A077,UCB$W_DL_MP(R5),Rl ;PUT CURRENT CYL & SURFACE IN Rl

CALCULATE CYLINDER DIFFERENCE WORD
60$:

70$:

CLRL
INSV
INSV
CMPW
BEQL
BICB
BICB
SUBW
BEQL
BCC
MNEGW
BISW
INSV
BISW3

RO
;CLEAR RO FOR DESIRED ADDRESS
UCB$W DA+l(RS),#6,#1,RO ;INSERT DESIRED SURFACE IN R0<6>
UCB$W=DC(R5),#7,#9,RO
;INSERT DESIRED CYLINDER IN R0<15:7>
RO,Rl
;IS A SEEK NEEDED?
80$
;IF EQL - NO
#A0177,Rl
;REMOVE SURFACE BIT
#A0177,RO
;REMOVE SURFACE BIT
RO,Rl
;SUBTRACT DESIRED FROM ACTUAL
70$
;IF EQL - ONLY CHANGE SURFACE
70$
;IF CC - ACTUAL>=DESIRED
Rl,Rl
;ACTUAL<DESIRED, MAKE POSITIVE DIFF
#4,Rl
;SET SIGN FOR MOVE TO CENTER OF DISK
UCB$W DA+l(RS),#4,#1,Rl ;INSERT SURFACE BIT
#RL_DA_M_MRK,Rl,RL_DA(R4)
;SET MARKER AND LOAD DIFFERENCE WORD

C-19

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

EXECUTE SEEK
CKPWR

SAVE RO=NO

;DISABLE INTERRUPTS, CHECK POWER,;AND PUT UNIT NUMBER IN R2<9:8>
BISW3
R2,#F_SEEK!RL_CS_M_IE,- ;EXECUTE SEEK FUNCTION
RL CS(R4)
WFIKPCH 40$,#2
;WAIT FOR SEEK TO BEGIN (INTERRUPT)
IOFORK
;CREATE FORK PROCESS
CMPB
#IO$ SEEK,UCB$B FEX(RS) ;IS SEEK ASSOCIATED WITH A TRANSFER?
BEQL
90$ ; IF EQL - NO, SEEK ONLY
I

80$:

•••

RETURN FOR SEEK ASSOCIATED WITH A TRANSFER REQUEST
INCL
JMP

UCB$L DPC(RS)
@UCB$L_DPC(R5)

;ADJUST TO CORRECT RETURN ADDRESS
;RETURN TO DRIVER FOR TRANSFER

RETURN FOR SEEK ONLY REQUEST
90$:

CKPWR

SAVE RO=NO

;DISABLE INTERRUPTS, CHECK POWER,;AND PUT UNIT NUMBER IN R2<9:8>
BISW3
R2,#F_READHEAD!RL_CS_M_IE,- ;EXECUTE DUMMY READ HEADER
RL CS (R4)
, ...
WE'IKPCH RETREG, #2
;WAIT FOR SEEK TO COMPLETE (INTERRUPT)
IOFORK
;CREATE FORK PROCESS
BRW
RETREG
.PAGE

TRANSFER FUNCTION EXECUTION
FUNCTIONS INCLUDE:
WRITE CHECK
WRITE DATA
READ DATA, AND
READ HEADER
INPUTS:
R3
R4
RS

- CASE INDEX
- DEVICE CSR ADDRESS
- UCB ADDRESS

FUNCTIONAL DESCRIPTION:
A UNIBUS DATAPATH IS REQUESTED FOLLOWED BY THE APPROPRIATE NUMBER OF MAP
REGISTERS REQUIRED FOR THE TRANSFER. THE TRANSFER PARAMETERS ARE LOADED
INTO THE DEVICE REGISTERS, INTERRUPTS ARE LOCKED OUT, THE FUNCTION IS
INITIATED, AND A WAITFOR INTERRUPT AND KEEP CHANNEL IS EXECUTED.
UPON RETURN FROM THE INTERRUPT SERVICE ROUTINE, IF THE TRANSFER IS
COMPLETE, THE APPROPRIATE EXIT IS TAKEN. IF THE FUNCTION IS NOT COMPLETE
TRANSFER PARAMETERS ARE UPDATED AND A RETURN TO FDISPATCH IS EXECUTED TO
REISSUE SEEK AND TRANSFER FUNCTIONS WHILE KEEPING CHANNEL AND UBA
RESOURCES. IF A DATA CHECK HAS BEEN REQUESTED, IT IS PERFORMED
BEFORE RETURNING TO FDISPATCH.

C-20

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

XFER:
BBS
MOVW
MOVZWL
MOVW
ASHL
MOVB

;TRANSFER FUNCTION EXECUTION
#UCB$V_DL_MAPPING,;ADAPTER MAPPING?
UCB$W DL FLAGS(R5),2$
;BRANCH IF ADAPTER MAPPING.
UCB$A-DL-BUF PA(R5),UCB$W DL SBA(R5);GET lST WORD OF BUFFER ADDR
UCB$A=DL=BUF=PA+2(R5),RO;GET-BITS 16:21 OF BUFFER ADDRESS
R0,RL_BAE(R4)
;SET MEMORY EXTENSION BITS IN BAE
#4,RO,RO
;PUT MEMORY EXTENSION BITS IN <5:4>
RO,UCB$B_DL_XBA(R5)
;OF CSR

FIRST TRANSFER OF THIS I/O REQUEST - ALLOCATE RESOURCES
TSTW
BNEQ
CLRL
CMPB
BNEQ
MOVAB
1$:

MOVL
MNEGW
BRB

;RESOURCES ALREADY ALLOCATED?
UCB$W_DL_DPN(R5)
;IF NEQ - YES
5$
UCB$A DL MOVRTN(R5)
;ASSUME READ
;WRITE DATA?
#CDF_WRITEDATA,R3
;IF NEQ NO
1$
GAIOC$MOVFRUSER,;SET MOVE ROUTINE ADDRESS FOR
;lST PARTIAL WRITE
UCB$A DL MOVRTN(R5)
UCB$L=SVAPTE(R5),UCB$L_DL SVAPTE(R5);SAVE SVAPTE FOR BUFFER COPY
;SET FIRST XFER FLAG
#1,UCB$W_DL_DPN(R5)
;JOIN COMMON CODE
5$

FIRST TRANSFER OF THIS I/O REQUEST - ALLOCATE RESOURCES
2$:

TSTW
UCB$W DL DPN(R5)
;UBA RESOURCES ALREADY ALLOCATED?
BNEQ
5$
- ;IF NEQ - YES
REQDPR
;REQUEST DATAPATH
REQMPR
; REQUEST MAP REGISTERS
LOADUBA
;LOAD UNIBUS MAP REGISTERS
MOVL
UCB$L_CRB(R5),Rl
;GET CRB ADDRESS
EXTZV
#VEC$V DATAPATH,#VEC$S DATAPATH,- ;EXTRACT DATAPATH NUMBER CRB$L INTD+VEC$B DATAPATH(Rl),RO
;FOR UBA RESOURCE FLAG
MOVW
RO,UCB$W_DL_DPN(R5)
;INDICATE UBA RESOURCES ALLOCATED
MOVZWL
INSV
MOVW
EXTZV
MULB3

UCB$W BOFF(R5),R0
;GET BYTE OFFSET IN PAGE
CRB$L-INTD+VEC$W MAPREG(Rl),- ;INSERT HIGH 7 BITS OF ADDRESS
#9,#7~RO
, ...
RO,UCB$W DL SBA(R5)
;SET BUFFER ADDRESS
#7,#2,CRB$L-INTD+VEC$W MAPREG(Rl),RO ;GET MEMORY EXTENSION BITS
#16,RO,UCB$B_DL_XBA(R5) ;POSITION MEMORY EXTENSION BITS TO <5:4>

COMMON TRANSFER POINT

FOR A READ OPERATION WHEN NO ADAPTER MAPPING IS PRESENT EMPTY THE
INTERNAL PHYSICALLY CONTIGUOUS BUFFER FROM THE PREVIOUS READ TO THE
USER'S BUFFER.
5$:

BSBW

DL- MOVE- TO- BUFFER

;COPY TO USER BUFFER

PUT BUFFER ADDRESS, WORD COUNT, AND DISK ADDRESS IN DEVICE REGISTERS

C-21

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

MOVW
MNEGW
MOVZBL
MOVZBL
SUBW
MULW
CMPW
BLEQU
MOVW

UCB$W DL SBA(R5),RL BA(R4)
;SET BUFFER ADDRESS
UCB$W-BCR(R5),;GET BYTES LEFT TO TRANSFER AND UCB$W-DL PBCR(RS)
;ASSUME ONLY ONE TRANSFER NEEDED
UCB$B-SECTORS(R5),R2
;GET SECTORS/SURFACE
UCB$W=DA(R5),Rl
;GET DESIRED SECTOR
Rl,R2
;CALCULATE SECTORS LEFT ON SURFACE
#256,R2
;CONVERT TO BYTES LEFT ON SURFACE
UCB$W_DL_PBCR(R5),R2
;ARE ADDITIONAL TRANSFERS REQUIRED?
10$
;IF LEQU - NO
R2,UCB$W_DL_PBCR(R5)
;SET BYTE COUNT FOR THIS TRANSFER

FOR A WRITE OPERATION WHEN NO ADAPTER MAPPING IS PRESENT
FILL INTERNAL PHYSICALLY CONTIGUOUS BUFFER FROM THE USER'S BUFFER.
10$:

BSBW

DL- MOVE - FROM- BUFFER

;COPY FROM USER BUFFER

MOVZBL
BISW
DIVW3
MNEGW

UCB$B_DL_XBA(R5),RO
FTAB[R3],R0
#2,UCB$W_DL_PBCR(R5),R2
R2,RL_MP(R4)

;SET MEMORY EXTENSION BITS
;MERGE XBA BITS WITH FUNCTION
;CALCULATE TRANSFER WORD COUNT
;SET TRANSFER WORD COUNT

MOVZBL
INSV
INSV
MOVW

UCB$W DA(RS),Rl
UCB$W-DA+l(R5),#6,#l,Rl
UCB$W=DC(R5),#7,#9,Rl
Rl,RL_DA(R4)

;PUT DESIRED SECTOR IN Rl<5:0>
;INSERT DESIRED SURFACE IN Rl<6>
;INSERT DESIRED CYLINDER IN Rl<l5:7>
;SET DESIRED DISK ADDRESS

EXECUTE THE TRANSFER FUNCTION
CKPWR
BISW3
R2,R0,RL CS(R4)
WFIKPCH RETREG,#6
IOFORK

;DISABLE INTERRUPTS, CHECK POWER,;AND PUT UNIT NUMBER IN R2<9:8>
;EXECUTE FUNCTION
;WAITFOR INTERRUPT AND KEEP CHANNEL
;RETURN HERE FROM ISR SAVING REGISTERS
;CREATE FORK PROCESS (RETURN TO ISR)
;RETURN HERE FROM ISR REI ROUTINE

PURGE DATAPATH
CLRB
JSB
BLBS
INCB

UCB$B DL DPPE(R5)
G"IOC$PURGDATAP
R0,20$
UCB$B_DL_DPPE(R5)

;CLEAR DATAPATH PURGE ERROR
;PURGE DATAPATH
;IF SET - NO PURGE ERRORS
;SET DATAPATH PURGE ERROR

SAVE UBA REGISTERS FOR UPDATE AND REGDUMP ROUTINES

C-22

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

20$:

25$:

30$:
40$:

BBC
MOVL
EXTZV
EXTZV
INSV
CMPW
BGEQ
MOVZWL
MOVL
CLRL
DECL
CMPV
BGTR
MOVL
BBC
BRW
BLBC
BRW

#UCB$V DL MAPPING,;ADAPTER MAPPING?
UCB$W DL FLAGS(R5),30$ ;IF BC NO
Rl,UCB$L-DL DPR(R5)
;SAVE DATAPATH REGISTER
#9,#7,UCB$W-DL BA(R5),RO ;EXTRACT LOW BITS OF FINAL MAP REG NO.
#4,#2,UCB$W-DL-CS(R5),Rl ;EXTRACT HI BITS OF FINAL MAP REG NO.
Rl,#7,#2,RO- ;INSERT HIGH BITS OF FINAL MAP REGISTER
#495,RO
;LEGAL MAP REGISTER NUMBER?
25$
;IF GEQ - YES
#495,RO
;RESTRICT MAP REGISTER NUMBER
(R2) [R0],UCB$L_DL_FMPR(R5)
;SAVE FINAL MAP REGISTER NUMBER
UCB$L_DL_PMPR(R5)
;CLEAR PREVIOUS MAP REGISTER CONTENTS
RO
;CALCULATE PREVIOUS MAP REGISTER NUMBER
#VEC$V MAPREG,#VEC$S MAPREG,- ;ANY PREVIOUS MAP REGISTER?
CRB$L INTD+VEC$W MAPREG(R3),R0; ...
30$ ; IF GTR - NO
(R2) [R0],UCB$L DL PMPR(R5)
;SAVE PREVIOUS MAP REGISTER
#RL_CS_V_CE,UCB$W=DL_CS(R5),40$ ;IF CLR - NO RL ERRORS
RETREG
;DEVICE ERROR
UCB$B_DL_DPPE(R5),45$
;IF CLR - NO PURGE ERROR
RETREG
;PURGE ERROR

RETURN HEADER INFORMATION FOR READ HEADER FUNCTION
45$:

50$:

CMPB
BNEQ
PUSHL
PUSHL
MOVAB
MOVL
CMPW
BLSSU
MOVZWL
SUBW3
JSB
POPL
POPL

#CDF_READHEAD,UCB$B_CEX(R5)
;READ HEADER FUNCTION?
DATACHECK
;IF NEQ - NO
UCB$W BCR(R5)
;SAVE NEG BYTES REMAINING
UCB$L=SVAPTE(R5)
;SAVE ADDRESS OF PTE
UCB$W_DL_DB(R5),Rl
;SET ADDRESS OF INTERNAL BUFFER
#6,R2
;SET NUMBER OF BYTES TO MOVE
R2,UCB$W BCNT(R5)
;ROOM FOR FULL HEADER?
50$
;IF LSSU - YES
UCB$W BCNT(R5),R2
;SET LENGTH OF PARTIAL HEADER
UCB$W=BCNT(R5),R2,UCB$W_BCR(R5)
;CALCULATE TRANSFER BYTE COUNT
GAIOC$MOVTOUSER
;MOVE HEADER TO USER BUFFER
UCB$L SVAPTE(R5)
;RESTORE ADDRESS OF PTE
UCB$W=BCR(R5)
;RESTORE NEG BYTES REMAINING

PERFORM DATA CHECK, IF REQUESTED
DATACHECK:
BBC
BBSC
INCB
MOVZBL
BRW

#IO$V DATACHECK,UCB$W=FUNC(R5) ,UPDATE
#0,UCB$B_DL_DCHEK(R5),UPDATE
UCB$B DL DCHEK(R5)
#IO$_WRITECHECK,R3
XFER

;DATACHECK AFTER PARTIAL TRANSFER
;IF CLR - DATA CHECK NOT REQUESTED
;IF SET - DATA CHECK ALREADY PERFORMED
;SET DATA CHECK IN PROGRESS
;SET CASE INDEX TO WRITE CHECK
;BRANCH TO PERFORM WRITE CHECK

UPDATE BUFFER ADDRESS, CURRENT DISK ADDRESS, AND BYTES REMAINING
FOR NEXT TRANSFER
UPDATE:
BBC
BICB3
MOVW

;UPDATE TRANSFER PARAMETERS
;ADAPTER MAPPING?
#UCB$V DL MAPPING,UCB$W_DL_FLAGS (R5), 10$ ;IF BC NO
#AXCF,UCB$W_DL_CS(R5),- ;SAVE MEMORY EXTENSION BITS
UCB$B_DL_XBA(R5)
UCB$W DL BA(R5) ,;UPDATE SAVED BUFFER ADDRESS
UCB$W=DL=SBA (R5)

C-23

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

10$:

CLRB
ADDL3
EXTZV
MOVB
EXTZV
MOVW
ADDW
BEQL
BRW

UCB$W_DA(R5)
;UPDATE DESIRED SECTOR TO ZERO
#A0100,UCB$W_DL_DA(R5),Rl ;INCREMENT CYLINDER & SURFACE
# 6, #1, Rl , R2
;EXTRACT DESIRED DISK SURFACE
R2,UCB$W DA+l(RS)
;UPDATE DESIRED DISK SURFACE
;EXTRACT DESIRED DISK CYLINDER
#7, #9, Rl :-R2
;UPDATE DESIRED DISK CYLINDER
R2,UCB$W DC(RS)
UCB$W DL-PBCR(RS) ,;UPDATE NEG BYTES REMAINING TO XFER
UCB$W~)CR (RS)
I•••
;IF EQL - TRANSFER COMPLETE
RETREG
;MORE BYTES REMAINING - CONTINUE
FDISPATCH

GET STATUS AND RESET ERRORS
RETREG:

;GET STATUS AND RESET ERRORS

FOR A READ OPERATION WHEN NO ADAPTER MAPPING IS PRESENT
EMPTY INTERNAL BUFFER INTO USER'S BUFFER FOR LAST READ
BSBW

DL- MOVE - TO- BUFFER

;MOVE LAST READ INTO USER'S BUFFER

BITW

0$:

#UCB$M TIMOUT!UCB$M POWER,TIMEOUT OR POWERFAIL?
UCB$L STS(RS)
BEQL
0$
;BR IF NO
IOFORK
;ELSE, FORK
MOVW
#RL_DA_M_STS!;PUT GET STATUS IN DAR
RL_DA_M_MRK,RL_DA(R4)
CLRL
R2
;CLEAR R2 FOR UNIT NUMBER
INSV
UCB$W UNIT(R5),#8,#8,R2 ;GET UNIT NUMBER
BISW3
R2,#F=GETSTATUS,RL_CS(R4)
;EXECUTE GET STATUS
DEVICELOCK LOCKADDR=UCB$L DLCK(RS),- ;LOCK DEVICE ACCESS
LOCKIPL=UCB$B_DIPL(R5) ,- ;RAISE IPL
SAVIPL=-(SP),;SAVE CURRENT IPL
PRESERVE=NO
;DON'T PRESERVE RO
BSBW
DL WAIT
;WAIT FOR CONTROLLER
MOVW
RL MP(R4),UCB$W DL MP(RS)
;RETRIEVE ERROR REGISTER
MOVW
#RL_DA_M_RST!- - ;PUT GET STATUS & RESET IN DAR
RL DAM STS!RL DAM MRK,RL DA(R4)
, ...
BISW3
R2:-#F=GETSTATUS,RL_CS(R4) -;EXECUTE RESET
BSBW
DL_WAIT
;WAIT FOR CONTROLLER
DEVICEUNLOCK LOCKADDR=UCB$L_DLCK(R5),- ;UNLOCK DEVICE ACCESS
NEWIPL=(SP)+,;RESTORE IPL
PRESERVE=NO
;DON'T PRESERVE RO
I

•••

DETERMINE EXIT - SPECIAL CONDITION, FATAL ERROR, RETRIABLE ERROR, OR SUCCESS
CMPZV

#0,#5,UCB$W DL MP(RS),- ;HEADS, BRUSHES, STATE OK?
#RL MP M BHlRL-MP M HO!RL SLM
1$ - - - - ; IF EQL - YES, ONLINE
#UCB$M TIMOUT,UCB$W STS(RS)
;CLEAR DEVICE TIME OUT
#SS$_MEDOFL,RO
;SET MEDIUM OFFLINE STATUS
FUNCXT
;RETURN
#UCB$M POWER!;POWER FAIL OR DEVICE TIMEOUT?
UCB$M_TIMOUT,UCB$W_STS(R5)
SPECOND
;IF NEQ - YES, SPECIAL CONDITION
I

1$:

BEQL
BICW
MOVZWL
BRW
BITW

BNEQ

C-24

•••

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

2$:

4$:

BBS
BBS
BLBC
JSB
BBS
BBS
BBC
BBC
BBS
BITW

BNEQ

#RL MPV VC,UCB$W DL MP(R5),20$ ;IF SET - VOLUME INVALID
#RL-CS-V-CE,UCB$W-DL-CS(R5),2$ ;IF SET - RL ERROR
UCB$B DL-DPPE(R5)~10$
;IF CLR - NO PURGE ERROR
GAERL$DEVICERR
;ALLOCATE AND FILL ERROR MESSAGE BUFFER
#IO$V INHRETRY,UCB$W FUNC(R5),20$ ;IF SET - RETRY INHIBITED
#RL CS V NXM,UCB$W DL CS(RS),20$ ;IF SET - NONEXISTENT MEMORY
#RL-CS-V-DE,UCB$W DL CS(R5),5$ ;IF CLR - NO DRIVE ERRORS
#RL_MP_V-WL,UCB$W-DL-MP(R5),4$ ;IF CLR - NOT WRITE LOCKED
#RL_MP_V-WGE,UCB$W DL MP(RS),20$ ;IF WL & WGE SET - WL ERROR
#RL=MP=M=WDE!- ;WRITE DATA ERROR, OR
RL_MP_M_CHE!;CURRENT HEAD ERROR, OR
RL MP M WGE!;WRITE GATE ERROR, OR
RL-MP-M-DSE,UCB$W DL MP(R5)
;DRIVE SELECT ERROR?
20$ - - ; IF NEQ - YES

RETRIABLE ERROR EXIT
5$:

CVTBL
ADDL

@UCB$L DPC(RS),-(SP)
(SP)+,UCB$L_DPC(RS)

;GET BRANCH DISPLACEMENT
;CALCULATE RETURN ADDRESS - 1

SUCCESSFUL OPERATION EXIT
10$:

INCL
JMP

UCB$L DPC (RS)
@UCB$L_DPC (RS)

;ADJUST TO CORRECT RETURN ADDRESS
;RETURN TO DRIVER

FATAL ERROR EXIT
20$:

BRW

FATALERR

;FATAL ERROR EXIT

; SPECIAL CONDITION EXIT (POWER FAILURE OR DEVICE TIMEOUT)
SPECOND:
BBS
JSB
BICW
MOVZWL
DECB
BEQL
BRW
RESETXFR:
MOVL
MNEGW
BRW

#UCB$V_POWER,UCB$W_STS(R5),PWRFAIL ;IF SET - POWER FAILURE
;IF CLR - DEVICE TIMEOUT
GAERL$DEVICTMO
;LOG DEVICE TIMEOUT
#UCB$M TIMOUT,UCB$W_STS(R5)
;CLEAR TIMEOUT STATUS
#SS$_TIMEOUT,RO
;SET DEVICE TIMEOUT STATUS
UCB$B_ERTCNT(RS)
;ANY ERROR RETRIES REMAINING?
RESETXFR
;IF EQL - NO
FDISPATCH
;RETURN
;RESET TRANSFER BYTE COUNT
UCB$L_IRP(R5),R3
;GET ADDRESS OF I/O PACKET
IRP$W_BCNT(R3),UCB$W_BCR(R5)
;RESET BYTE COUNT
FUNCXT
;EXIT

C-25

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

PWRFAIL:

;POWER FAILURE
#UCB$M POWER,UCB$W_STS(RS)
;CLEAR POWER FAILURE BIT
UCB$W DL DPN(RS)
;ARE UCB RESOURCES ALLOCATED?
SO$ ;IF EQL - NO
#UCB$V_DL_MAPPING,;ADAPTER MAPPING?
UCB$W_DL_FLAGS(RS),S0$ ;IF BC NO
RELDPR
;RELEASE DATA PATH
RELMPR
;RELEASE MAP REGISTERS
RELCHAN
;RELEASE CHANNEL IF OWNED
MOVL
UCB$L IRP(RS),R3
;GET ADDRESS OF I/0 PACKET
IRP$L-SVAPTE(R3),MOVQ
;RESTORE TRANSFER PARAMETERS
UCB$(::SVAPTE (RS)
BRW
PREPROCESS
;RETURN TO PREPROCESS UCB FIELDS
.PAGE
.SBTTL INTERRUPT SERVICE ROUTINE
BICW
TSTW
BEQL
BBC

SO$:

;++
DL$INT - RLll INTERRUPT SERVICE ROUTINE
FUNCTIONAL DESCRIPTION:
THIS ROUTINE IS ENTERED VIA A JSB INSTRUCTION WHEN AN INTERRUPT
OCCURS ON AN RLll DISK CONTROLLER. IF THE INTERRUPT IS NOT EXPECTED,
THE UNSOLICITED INTERRUPT ROUTINE DISMISSES THE INTERRUPT. IF
THE INTERRUPT rs EXPECTED, DEVICE REGISTERS ARE SAVED AND THE
DRIVER IS CALLED AT ITS INTERRUPT RETURN ADDRESS. THE DRIVER FORKS,
CAUSING A RETURN TO THIS ROUTINE, WHICH RESTORES GENERAL REGISTERS
AND DISMISSES THE INTERRUPT.
INPUTS:
OO(SP)
04(SP)
08(SP)
12(SP)
16(SP)
20(SP)
24(SP)
28(SP)
32(SP)

POINTER TO ADDRESS OF THE IDB
SAVED RO
SAVED Rl
SAVED R2
SAVED R3
SAVED R4
SAVED RS
PC AT THE TIME OF THE INTERRUPT
PSL AT THE TIME OF THE INTERRUPT

OUTPUTS:
DEVICE REGISTERS ARE SAVED, IPL rs LOWERED TO FORK LEVEL, THE
INTERRUPT rs DISMISSED, ALL REGISTERS EXCEPT RO-RS ARE PRESERVED.

DL INT::

C-26

;INTERRUPT SERVICE ROUTINE
MOVL
@(SP)+,R3
;REMOVE ADDRESS OF IDB FROM STACK
ASSUME IDB$L_CSR EQ 0
ASSUME IDB$L_OWNER EQ 4
MOVQ
(R3),R4
;GET ADDRESS OF CSR AND UCB
TSTL
RS
;IS RS A ZERO
BEQL
DL_UNSOLNT
;IF EQL NO OWNER
DEVICELOCK LOCKADDR=UCB$L_DLCK(RS),- ;LOCK DEVICE ACCESS
CONDITION=NOSETIPL,;DON'T CHANGE IPL
PRESERVE=NO
;DON'T PRESERVE RO
BBCC
#UCB$V_INT,;IF CLR - INTERRUPT NOT EXPECTED
UCB$W_STS(RS),40$
, ...

Sample Driver for the RL11, RL01, and RL02 Disk Drives

CMPB
BNEQ
MOVW
MOVW
MOVW

#CDF READHEAD,UCB$B CEX(RS)
;READ HEADER FUNCTION?
10$ ;IF NEQ - NO
RL MP(R4),UCB$W DL DB(RS)
;SAVE SECTOR HEADER INFORMATION
RL-MP(R4),UCB$W-DL-DB+2(RS)
RL=MP(R4),UCB$W=DL=DB+4(RS)

10$:

MOVAB
MOVAB
MOVW
MOVW
MOVW
MOVW

RL CS(R4) ,R2
UCB$W_DL_CS(RS),R3
(R2) +, (R3) +
(R2) +, (R3) +
(R2) +, (R3) +
(R2) +, (R3) +

;GET ADDRESS OF CONTROL STATUS REGISTER
;GET ADDRESS OF REGISTER SAVE AREA
;SAVE CONTROL STATUS REGISTER
;SAVE BUFFER ADDRESS REGISTER
;SAVE DISK ADDRESS REGISTER
;SAVE MULTIPURPOSE REGISTER

20$:

MOVQ
JSB

UCB$L FR3(RS),R3
@UCB$L_FPC(RS)

;RESTORE DRIVER CONTEXT
;CALL DRIVER AT INTERRUPT RETURN ADDRESS

40$:

DEVICEUNLOCK LOCKADDR=UCB$L_DLCK(RS),- ;UNLOCK DEVICE ACCESS
PRESERVE=NO
;DON'T PRESERVE RO

DL UNSOLNT:
POPR
REI
.PAGE
.SBTTL

#AM<RO,Rl,R2,R3,R4,RS>

;UNSOLICITED INTERRUPT
;RESTORE RO-RS
;RETURN FROM INTERRUPT

;++
DL REGDUMP - REGISTER DUMP ROUTINE
FUNCTIONAL DESCRIPTION:
THIS ROUTINE IS CALLED TO SAVE THE DEVICE REGISTERS AND OBA RESOURCE
REGISTERS IN A SPECIFIED BUFFER. IT IS CALLED FROM THE DEVICE ERROR
LOGGING ROUTINE AND FROM THE DIAGNOSTIC BUFFER FILL ROUTINE.
INPUTS:
RO
R4
RS

- ADDRESS OF REGISTER SAVE BUFFER
- ADDRESS OF DEVICE CONTROL STATUS REGISTER (CSR)
- ADDRESS OF UNIT CONTROL BLOCK (UCB)

OUTPUTS:
THE DEVICE AND OBA REGISTERS ARE SAVED IN THE SPECIFIED BUFFER.
RO CONTAINS THE ADDRESS OF THE NEXT EMPTY LONGWORD IN THE BUFFER.
ALL REGISTERS EXCEPT Rl AND R2 ARE PRESERVED.
;--

DL REGDUMP:
MOVL
MOVAL
MOVZBL
10$:
MOVZWL
SOBGTR
MOVZWL
MOVL
MOVL
MOVL
MOVZBL
RSB

#<RL NUM REGS+S>, (RO)+
UCB$W DL-CS(RS),Rl
#RL_NUM_REGS,R2
(Rl) +, (RO)+
R2,10$
(Rl) +, (RO)+
(Rl) +, (RO)+
(Rl) +, (RO)+
(Rl) +, (RO)+
(Rl) +, (RO)+

;REGISTER DUMP ROUTINE
;INSERT NUMBER OF REGISTERS
;GET ADDRESS OF SAVED DEVICE REGISTERS
;GET NUMBER OF DEVICE REGISTERS TO MOVE
;DUMP REGISTER IN BUFFER
;IF GTR - STILL MORE TO MOVE
;DUMP DATAPATH NUMBER
;DUMP DATAPATH REGISTER
;DUMP FINAL MAP REGISTER
;DUMP PREVIOUS MAP REGISTER
;DUMP DATAPATH PURGE ERROR REGISTER
;RETURN

C-27

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

.PAGE
.SBTTL

MOVE TO USER BUFFER ROUTINE

;++
DL MOVE TO BUFFER - MOVE TO USER BUFFER

FUNCTIONAL DESCRIPTION:
THIS ROUTINE MOVES DATA BETWEEN THE PHYSICALLY CONTIGUOUS BUFFER AND
THE USER'S BUFFER.
INPUTS:
RS - UCB ADDRESS
OUTPUTS:
DATA MOVE BETWEEN THE PHYSICALLY CONTIGUOUS BUFFER AND.THE USER'S BUFFER.
REGISTER'S RO,Rl, AND R2 ARE DESTROYED

DL_MOVE_TO_BUFFER:
;BUFFER MOVE ROUTINE
BBS
#UCB$V_DL_MAPPING,;ADAPTER MAPPING?
UCB$W DL FLAGS(RS),10$ ;IF BS YES NOTHING TO MOVE
#CDF READDATA,UCB$B CEX(RS);READ DATA OPERATION?
CMPB
10$ ; IF NEQ NOT A READ
BNEQ
#0,UCB$B DL DCHEK(RS),- ;DATA CHECK IN PROGRESS?
BBS
10$
;IF BS YES NOTHING TO MOVE
UCB$A DL MOVRTN(RS)
;ANYTHING TO MOVE?
TSTL
20$ ;IF EQL NO
BEQL
UCB$L DL BUFADR(RS),RO ;GET USER BUFFER POINTER
MOVL
UCB$A-DL-BUF VA(RS),Rl ;GET PHYSICALLY CONTIGUOUS BUFFER ADDRESS
MOVL
;GET NUMBER OF BYTES TO TRANSFER
MOVZWL UCB$W-DL-PBCR(R5),R2
@UCB$A_DL_MOVRTN(R5)
;CALL MOVE ROUTINE
JSB
MOVL
RO,UCB$L DL BUFADR(RS)
;SAVE INTERNAL BUFFER POINTER
GAIOC$MOVTOUSER2,;SET NEXT MOVE ROUTINE TO BE USED
MOVAB
UCB$A_DL_MOVRTN(R5)
10$:
RSB
;RETURN
20$:

MOVAB
RSB

C-28

GAIOC$MOVTOUSER,UCB$A_DL_MOVRTN(R5)

;SET NEXT MOVE ROUTINE TO BE USED
;RETURN

Sample Driver for the RL 11, RL01, and RL02 Disk Drives

.PAGE
.SBTTL

MOVE FROM USER BUFFER ROUTINE

;++

DL- MOVE- FROM- BUFFER - MOVE FROM USER BUFFER
FUNCTIONAL DESCRIPTION:
THIS ROUTINE MOVES DATA BETWEEN THE PHYSICALLY CONTIGUOUS BUFFER AND
THE USER'S BUFFER.
INPUTS:
R5 - UCB ADDRESS
OUTPUTS:
DATA MOVE BETWEEN THE PHYSICALLY CONTIGUOUS BUFFER AND THE USER'S BUFFER.
REGISTER'S RO,Rl, AND R2 ARE DESTROYED
;--

DL MOVE FROM BUFFER:
;BUFFER MOVE ROUTINE
-BBS #UCB$V_DL_MAPPING,;ADAPTER MAPPING?
UCB$W DL FLAGS(R5),10$ ;IF BS YES NOTHING TO MOVE
CMPB
#CDF WRITEDATA,UCB$B CEX(R5);WRITE DATA OPERATION?
10$ ; IF NEQ NOT A WRITE
BNEQ
BBS
#0,UCB$B DL DCHEK(R5),- ;DATA CHECK IN PROGRESS?
10$
- ;IF BS YES NOTHING TO MOVE
MOVL
UCB$L DL BUFADR(R5),R0 ;GET USER BUFFER POINTER
UCB$A-DL-BUF VA(R5),Rl ;GET PHYSICALLY CONTIGUOUS BUFFER ADDRESS
MOVL
MOVZWL UCB$W-DL-PBCR(R5),R2
;GET NUMBER OF BYTES TO TRANSFER
JSB
@UCB$A DL MOVRTN(R5)
;CALL MOVE ROUTINE
R0,UCB$L DL BUFADR(RS)
;SAVE INTERNAL BUFFER POINTER
MOVL
GAIOC$MOVFRUSER2,;SET NEXT MOVE ROUTINE TO BE USED
MOVAB
UCB$A_DL_MOVRTN(R5)
10$:
RSB
;RETURN
DL END:

;ADDRESS OF LAST LOCATION IN DRIVER
.END

C-29

Sample Driver for the DR11-W and DRV11-WA
Interfaces
The following driver, XADRIVER, controls the DRll-W, a 16-bit parallel
DMA interface on UNIBUS systems. The driver also controls the
DRVll-WA, a 16-bit parallel DMA interface on the Q22 bus. Operational
details of these devices, as well as the capabilities controlled by the driver,
can be found in the VMS 1/0 User's Reference Manual: Part II.
You can find an online copy of the driver code (XADRIVER.MAR) in
SYS$EXAMPLES .
. TITLE
.IDENT

XADRIVER - VAX/VMS DRll-W AND DRVll-WA DRIVER
'X-18'

;****************************************************************************
*
;* COPYRIGHT (c) 1978, 1980, 1982, 1984, 1985, 1986 BY
*
;*

;*
;*
;*

;*
;*
;*
;*

;*
;*

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT
CORPORATION.

;*
;*
;*

DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.

*
*
*

*
*
*
*

*
*
*

*
*

;****************************************************************************
;++
FACILITY:
VAX/VMS Executive, I/0 Drivers
ABSTRACT:
This module contains the driver for the DRll-W (Unibus) and
DRVll-WA (Q-bus) . Since the driver was originally written for
the DRll-W, many inline comments refer to the "DRll-W" and "Unibus"
but apply equally well to the DRVll-WA and the Q-bus.
For DRll-W users:
This driver works for all hardware revision levels of
the DRll-W.
For DRVll-WA users:
This driver works for all hardware revision levels of

D-1

Sample Driver for the DR11-W and DRV11-WA Interfaces

the DRVll-WA, up through and including CS Rev C.
BECAUSE ETCH REVISION E OF THE DRVll-WA
PROVIDES SEVERAL CUSTOMER MODIFIABLE SETTINGS,
IT IS VERY IMPORTANT THAT THE USERS OF THIS
BOARD PROPERLY CONFIGURE IT TO BE BACKWARDS
COMPATIBLE WITH EARLIER REVISIONS OF THE
DRVll-WA. SPECIFICALLY, ON ETCH REVISION E
BOARDS, JUMPERS W2, W3, AND W6 MUST BE INSTALLED.

ENVIRONMENT:
Kernel Mode, Non-paged

.SBTTL

External and local symbol definitions

External symbols
AST control block
Adapter control block
Channel request block
Device types
Device data block
Device characteristics
Driver prologue table
Dynamic data structure types
EMB off sets
Interrupt data block
I/O function codes
Hardware IPL definitions
I/O request packet
Internal processor registers
Scheduler priority increments
System status codes
Unit control block
Interrupt vector block
Define device specific
characteristics

$ACBDEF
$ADPDEF
$CRBDEF
$DCDEF
$DDBDEF
$DEVDEF
$DPTDEF
$DYNDEF
$EMBDEF
$IDBDEF
$IODEF
$IPLDEF
$IRPDEF
$PRDEF
$PRIDEF
$SSDEF
$UCBDEF
$VECDEF
$XADEF

Local symbols
Argument list (AP) offsets for device-dependent QIO parameters
Pl
P2
P3

0
4
8
12
16
20

PS
P6

First QIO parameter
Second QIO parameter
Third QIO parameter
Fourth QIO parameter
Fifth QIO parameter
Sixth QIO parameter

; Other constants
XA_DEF_TIMEOUT
XA DEF BUFSIZ
XA- RESET- DELAY

10
65535
<<2+9>/10>

10 second default device timeout
Default buffer size
Delay N microseconds after RESET
; (rounded up to 10 microsec intervals)

DRll-W definitions that follow the standard UCB fields
*** N 0 T E *** ORDER OF THESE UCB FIELDS IS ASSUMED

D-2

Sample Driver for the DR11-W and DRV11-WA Interfaces

$DEF
$DEF
$DEF
$DEF
$DEF
$DEF
$DEF
$DEF
$DEF
$DEF
$DEF
$DEF
$DEF
$DEF
$DEF

$DEFINI UCB
.=UCB$L DPC+4
UCB$L_XA_ATTN
.BLKL
UCB$W_XA_CSRTMP
.BLKW
UCB$W_XA_BARTMP
.BLKW
UCB$W_XA_CSR
.BLKW
UCB$W_XA_EIR
.BLKW
UCB$W_XA_IDR
.BLKW
UCB$W_XA_BAR
.BLKW
UCB$W_XA_WCR
.BLKW
UCB$W_XA_ERROR
.BLKW
UCB$L_XA_DPR
.BLKL
UCB$L_XA_FMPR
.BLKL
UCB$L_XA_PMPR
.BLKL
UCB$W_XA_DPRN
.BLKW
UCB$W_XA_BAETMP
.BLKW
UCB$W_XA_BAE
.BLKW

Attention AST listhead
1
Temporary storage of CSR image
1
Temporary storage of BAR image
1
Saved CSR on interrupt
1
Saved EIR on interrupt
1
Saved IDR on interrupt
1
Saved BAR register on interrupt
1
Saved WCR register on interrupt
1
Saved device status flag
1
Data Path Register contents
1
Final Map Register contents
1
Previous Map Register contents
1
Saved Datapath Register Number
And Datapath Parity error flag
Temporary storage of BAE (DRVll-WA
only)
Saved BAE register (DRVll-WA only)

1
1
1

Bit positions for device-dependent status field in UCB
$VIELD

UCB,0,<<ATTNAST, ,M>,<UNEXPT,,M>,<IGNORE_UNEXPT,,M>,>

UCB device specific bit definitions
ATTN AST requested
Unexpected interrupt received
Ignore initial interrupt on DRVll-WA

UCB$K SIZE=.
$DEFEND UCB
; Device register off sets from CSR address
$DEF

$DEFINI XA
XA WCR

$DEF
$DEF

XA BAR
XA_BAE

$DEF

XA CSR

Start of DRll-W definitions
Word count
.BLKW

1
Buff er address
Buff er address extension (DRVll-WA)

.BLKW

1
Control/status

; Bit positions for device control/status register
$EQULST XA$K_,,0,1,<<FNCT1,2><FNCT2,4><FNCT3,8><STATUSA,2048><STATUSB, 1024><STATUSC,512>>

Define CSR FNCT bit values

Define CSR STATUS bit values

D-3

Sample Driver for the DR11-W and DRV11-WA Interfaces

$VIELD

XA_CSR,0,<<GO,,M>,<FNCT,3,M>,<XBA,2,M>,<IE, ,M>, <RDY,,M>,<CYCLE,,M>,<STATUS,3,M>,<MAINT,,M>,<ATTN,,M>,<NEX, ,M>, <ERROR,,M>,-

Control/status register
Start device
CSR FNCT bits
Extended address bits
Enable interrupts
Device ready for command
Starts slave transmit
CSR STATUS bits
Maintenance bit
Status from other processor
Nonexistent memory flag
Error or external interrupt

XA_BAE,0,<<MSB_ADDR,6,M>,<,9,>,<CS_REV_C,,M>,-

Extended bus address register
Qbus physical address <22:16>

>
$VIELD

true i f DRVll-WA CS Rev C

>
$DEF
;

XA EIR

;

Error information register

Bit positions for error information register
$VIELD

XA_EIR,0,<<REGFLG,,M>,<SPARE,7,M>,<BURST,,M>,<DLT,,M>,<PAR,,M>,<ACLO,,M>,<MULTI,,M>,<ATTN,,M>,<NEX,,M>,<ERROR,,M>,-

; Error information register
;Flags whether EIR or CSR is accessed
Unused - spare
Burst mode transfer occurred
Timeout for successive burst xfer
Parity error during DATI/P
Power fail on this processor
Multi-cycle request error
ATTN - same as in CSR
NEX - same as in CSR
ERROR - same as in CSR

>
.BLKW
$DEF
$DEF

XA IDR
XA ODR

Input Data Buff er register
Output Data Buff er register
.BLKW

$DEFEND XA
.SBTTL

Device Driver Tables

Driver prologue table

D-4

End of DRll-W definitions

Sample Driver for the DR11-W and DRV11-WA Interfaces

DPT-creation macro
End of driver label
Adapter type
Allocate system page table
UCB size
Driver name
Start of load
initialization table
DPT STORE UCB,UCB$B FLCK,B,SPL$C IOLOCK8 ; Device fork IPL
DPT STORE UCB,UCB$B=DIPL,B,22
Device interrupt IPL
DPT STORE UCB,UCB$L DEVCHAR,L,<Device characteristics
DEV$M AVL!-Available
DEV$M-RTM!Real Time device
DEV$M-ELG!Error Logging enabled
DEV$M-IDV!input device
DEV$M=ODV>
output device
DPT STORE UCB,UCB$B DEVCLASS,B,DC$ REALTIME
; Device class
DPT-STORE UCB,UCB$B-DEVTYPE,B,DT$ DRllW
Device Type
DPT=STORE UCB,UCB$W=DEVBUFSIZ,W,-Default buffer size
XA DEF BUFSIZ
DPT STORE REINIT
Start of reload
initialization table
DPT STORE DDB,DDB$L DDT,D,XA$DDT
Address of DDT
DPT STORE CRB,CRB$L=INTD+4,D,Address of interrupt
XA INTERRUPT
service routine
DPT_STORE CRB,CRB$L_INTD+VEC$L_INITIAL,-; Address of controller
D,XA_CONTROL_INIT
initialization routine
DPT STORE END
End of initialization
tables

DP TAB

END=XA_END,ADAPTER=UBA,FLAGS=DPT$M_SVP,UCBSIZE=UCB$K_SIZE,NAME=XADRIVER
DPT STORE INIT

Driver dispatch table
DD TAB

DDT-creation macro
DEVNAM=XA,Name of device
START=XA_START,Start I/O routine
FUNCTB=XA_FUNCTABLE,FDT address
CANCEL=XA_CANCEL,Cancel I/O routine
REGDMP=XA_REGDUMP,Register dump routine
DIAGBF=<<15*4>+<<3+5+1>*4>>,Diagnostic buffer size
ERLGBF=<<l5*4>+<1*4>+<EMB$L_DV_REGSAV>> ;Error log buffer size

Function dispatch table
XA FUNCTABLE:
FUNCTAB

; FDT for driver
; Valid I/O functions
<READPBLK,READLBLK,READVBLK,WRITEPBLK,WRITELBLK,WRITEVBLK,SETMODE, SETCHAR, SENSEMODE, SENSECHAR>
FUNCTAB ,
; No buffered functions
FUNCTAB XA_READ_WRITE,; Device-specific FDT
<READPBLK,READLBLK,READVBLK,WRITEPBLK,WRITELBLK,WRITEVBLK>
FUNCTAB +EXE$READ,<READPBLK,READLBLK,READVBLK>
FUNCTAB +EXE$WRITE,<WRITEPBLK,WRITELBLK,WRITEVBLK>
FUNCTAB XA_SETMODE,<SETMODE,SETCHAR>
FUNCTAB +EXE$SENSEMODE,<SENSEMODE,SENSECHAR>
.SBTTL

XA_CONTROL_INIT, Controller initialization

D-5

Sample Driver for the DR11-W and DRV11-WA Interfaces

;++
XA CONTROL INIT, Called when driver is loaded, system is booted, or
po;er failure recovery.
Functional Description:
1)
2)
3)
4)

A1locates the direct data path permanently
Assigns the controller data channel permanently
Clears the Control and Status Register
If power recovery, requests device timeout

Inputs:
R4
RS
R6
R8

address
address
address
address

of CSR
of IDB
of DDB
of CRB

Outputs:
VEC$V_PATHLOCK bit set in CRB$L INTD+VEC$B DATAPATH
UCB address placed into IDB$L_OWNER
-

XA CONTROL INIT:

IDB$L_UCBLST(R5),RO
; Address of UCB
RO,IDB$L OWNER(RS)
; Make permanent controller owner
#UCB$M_ONLINE,UCB$W_STS(R0)
Set device status "on-line"
; Check for adapter mapping
ADPDISP SELECT=ADAP_MAPPING,ADDRLIST=<<YES,1$>>,CRBADDR=R8,SCRATCH=Rl
BUG_CHECK UNSUPRTCPU,FATAL
DRVll-WA not supported on nonmapping adapter
ADPDISP SELECT=QBUS,Check for QBUS machine
ADDRLIST=<<N0,9$>>,ADPADDR=Rl
BLBC
gASGN$GB QBUS MULT INTR,2$ ; protect against ILLQBUSCFG
MOVB
#Ax14,UCB$B DIPL(RS)
This is correct DIPL for DRVll-WA
MOVB
#DT$ XA DRVllWA,This is a Q-bus, therefore it is
UCB$B=DEVTYPE(R0)
a DRVll-WA rather than a DRll-W.

MOVL
MOVL
BISW

1$:

2$:

;+
DRVll-WAs at CS revision B and earlier incorrectly generated an interrupt
whenever the Interrupt Enable control bit (IE) underwent a low to high
transition. This phenomenon does not occur in boards at CS revision C.
To account for this unsoliciated interrupt, IGNORE UNEXPT is set at
initialization for all DRVll-WAs at cs revisions prior to c. When this
bit is set, the next unexpected interrupt (as determined by the INT bit
in UCB status word, which is set whenever an I/O request is outstanding)
is discarded. The IGNORE UNEXPT flag is necessary because driver
initialization occurs at
different IPL than the interrupt handling
routine.

BICW

D-6

#UCB$M IGNORE UNEXPT,UCB$W_DEVSTS (RO)

start out assuming this is a
CS Rev C DRVll-WA

Sample Driver for the DR11-W and DRV11-WA Interfaces

TSTW
MOVW

XA_BAR(R4)
XA_BAE(R4),Rl

BBS

#XA_BAE$V_CS_REV_C,Rl,9$

BAR and BAE share the same physical
address- they must be read in order
; branch around if CS Rev C

BAE<lS> is always set if the DRVll-WA is at CS Rev C or later.
BISW

#UCB$M IGNORE UNEXPT,UCB$W_DEVSTS (RO)

; set flag so all interrupts are
; discarded until further notice

If powerfail has occurred and device was active, force device timeout.
The user can set his own timeout interval for each request. Timeout is forced so a very long timeout period will be short circuited.
9$:

BBS

PUSHL
MOVL
BSBW
POPL
RSB

#UCB$V_POWER,UCB$W_STS(R0),10$
; Branch if powerf ail
#VEC$M PATHLOCK,CRB$L INTD+VEC$B_DATAPATH(R8)
Permanently allocate direct datapath
RS
Save RS
RO,RS
Copy UCB address to RS
XA DEV HWRESET
RS
Restore RS
Done

.SBTTL

XA_READ_WRITE, FDT for device data transfers

BISB
10$:

;++
XA_READ_WRITE, FDT for READLBLK,READVBLK,READPBLK,WRITELBLK,WRITEVBLK,
WRITEPBLK
Functional description:
1) Rejects QUEUE I/O's with odd transfer count
2) Rejects QUEUE I/O's for BLOCK MODE request to UBA Direct Data
PATH on odd byte boundary
3) Stores request timeout count specified in P3 into IRP
4) Stores FNCT bits specified in P4 into IRP
S) Stores word to write into ODR from PS into IRP
6) Checks block mode transfers for memory modify access
Inputs:
R3
R4
RS
R6
R8
AP

Address of IRP
Address of PCB
Address of UCB
Address of CCB
Address of FDT routine
Address of Pl
Pl
Buff er Address
P2
Buff er size in bytes
P3
Request timeout period (conditional on IO$M_TIMED)
P4
Value for CSR FNCT bits (conditional on IO$M SETFNCT)
PS
Value for ODR (conditional on IO$M SETFNCT) P6
Address of Diagnostic Buffer
-

Outputs:
RO = Error status if odd transfer count
IRP$L_MEDIA = Timeout count for this request
IRP$L_SEGVBN = FNCT bits for DRll-W CSR and ODR image

XA READ WRITE:

D-7

Sample Driver for the DR11-W and DRV11-WA Interfaces

The IO$M INHERLOG ("inhibit error logging") function modifier was not
intended-to be used by this driver. However, since the definition for
the IO$M RESET modifier used to be the same as that for IO$M INHERLOG,
the erro~ logging routine incorrectly used the IO$M_RESET bit to
determine whether it should log errors. To solve this problem, the
definition for IO$M RESET was changed. For the sake of old programs, we
manually move the RESET bit to its new location.
BBCC
BISW
1$:
2$:
5$:
10$:

BLBC
MOVZWL
JMP
MOVZWL
MOVL
BBS
MOVL

15$:

BBC
EXTZV
CMPB

20$:

BEQL
CMPB
BEQL
MOVZWL
BRB
EXTZV
ASHL
MOVW

#IO$V_INHERLOG,IRP$W_FUNC(R3),1$
; Branch if old reset bit not set
#IO$M_RESET,IRP$W_FUNC(R3)
Set new reset bit
P2(AP),10$
Branch if transfer count even
#SS$ BADPARAM,RO
Set error status code
GAEXE$ABORTIO
Abort request
IRP$W FUNC(R3),Rl
Fetch I/0 Function code
P3(AP),IRP$L MEDIA(R3)
Set request specific timeout count
#IO$V TIMED,Rl,15$
Branch if timeout specified
#XA_DEF_TIMEOUT,IRP$L_MEDIA(R3)
; Else set default timeout value
#IO$V DIAGNOSTIC,Rl,20$ ; Branch if not maintenance reqeust
#IO$V-FCODE,#IO$S FCODE,Rl,Rl ; AND out all function modifiers
#IO$_READPBLK,Rl If maintenance function, must be
; physical I/O read or write
20$
#IO$_WRITEPBLK,Rl
20$
#SS$ NOPRIV,RO
No privilege for operation
5$ Abort request
#0,#3,P4(AP),RO
Get value for FNCT bits
#XA_CSR$V_FNCT,RO,IRP$L_SEGVBN(R3) ; Shift into position
; for CSR
P5(AP),IRP$L_SEGVBN+2(R3) ; Store ODR value for later

If this is a block mode transfer, check buffer for modify access
whether or not the function is read or write. The DRll-W does
not decide whether to read or write, the user's device does.
For word mode requests, return to read check or write check.
If this is a BLOCK MODE request and the UBA Direct Data Path is
in use, check the data buffer address for word alignment.
If buffer
is not word aligned, reject the request.
BBS

BLBS
JMP
RSB

#IO$V_WORD,IRP$W_FUNC(R3),30$
; Branch if word mode transfer
#XA$V_DATAPATH,UCB$L_DEVDEPEND(R5),25$
Branch if Buffered Data Path in use
Pl(AP),2$
DDP, branch on bad alignment
GAEXE$MODIFY
Check buff er for modify access
Return

.SBTTL

XA_SETMODE, Set Mode, Set characteristics FDT

BBS
25$:
30$:

D-8

Sample Driver for the DR11-W and DRV11-WA Interfaces

;++
XA_SETMODE, FDT routine to process SET MODE and SET CHARACTERISTICS
Functional description:
If IO$M ATTNAST modifier is set, queue attention AST for device
If IO$M-DATAPATH modifier is set, queue packet.
Else, finish I/O.
Inputs:
R3
R4
RS
R6
R7
AP

I/O packet address
PCB address
UCB address
CCB address
Function code
QIO Parameter list address

Outputs:
If IO$M ATTNAST is specified, queue AST on UCB attention AST list.
If IO$M-DATAPATH is specified, queue packet to driver.
Else, use exec routine to update device characteristics

XA SETMODE:
MOVZWL
BBC

IRP$W FUNC(R3),R0
#IO$V=ATTNAST,R0,20$

Get entire function code
Branch if not an attention AST

Attention AST request
PUS HR
MOVAB

#AM<R4,R7>
UCB$L_XA_ATTN(R5),R7

JSB
POPR
BLBC
BISW

GACOM$SETATTNAST
#AM<R4,R7>
R0,50$
Branch if error
#UCB$M_ATTNAST,UCB$W_DEVSTS(R5)
; Flag ATTN AST expected.
#UCB$V UNEXPT,UCB$W DEVSTS(R5),10$
Deliver AST if unsolicited interrupt
DEL ATTNAST
#SS$_NORMAL,RO
Set status
GAEXE$FINISHIOC
That's all for now (clears Rl)

BBC

10$:

BSBW
MOVZBL
JMP

Address of attention AST control
block list
Set up attention AST

If modifier IO$M_DATAPATH is set,
queue packet. The data path is changed at driver level to preserve
order with other requests.
20$:

BBS

SA#I0$V_DATAPATH,R0,30$

If BDP modifier set, queue packet

JMP

GAEXE$SETCHAR

Set device characteristics

; This is a request to change data path useage, queue packet
30$:

CMPL
BNEQ
JMP

#IO$_SETCHAR,R7
45$
GAEXE$SETMODE

Set characteristics?
No, must have the privilege
Queue packet to start I/O

Error, abort IO
45$:
50$:

MOVZWL
CLRL
JMP

#SS$_NOPRIV,RO
Rl
GAEXE$ABORTIO

No priv for operation
Abort IO on error

D-9

Sample Driver for the DR11-W and DRV11-WA Interfaces

.SBTTL XA_START, Start I/O routines
;++
XA START - Start a data transfer, set characteristics, enable ATTN AST.
Functional Description:
This routine has two major functions:
1) Start an I/O transfer. This transfer can be in either word
or block mode. The FNCTN bits in the DRll-W CSR are set.
If
the transfer count is zero, the STATUS bits in the DRll-W CSR
are read and the request completed.
2) Set Characteristics. If the function is change data path, the
new data path flag is set in the UCB.
Inputs:
R3
RS

Address of the I/O request packet
Address of the UCB

Outputs:
RO = final status and number of bytes transferred
Rl = value of CSR STATUS bits and value of input data buffer register
Device errors are logged
Diagnostic buff er is filled

.ENABL

LSB

XA START:
Retrieve the address of the device CSR
ASSUME
MOVL
MOVL

IDB$L_CSR EQ 0
UCB$L CRB(R5),R4
; Address of CRB
@CRB$L_INTD+VEC$L_IDB(R4),R4
; Address of CSR

Fetch the I/O function code
MOVZWL
MOVW
EXTZV

IRP$W_FUNC(R3),Rl
; Get entire function code
Rl,UCB$W_FUNC(R5)
; Save FUNC in UCB for Error Logging
#IO$V FCODE,#IO$S_FCODE,Rl,R2 ; Extract function field

Dispatch on function code. If this is SET CHARACTERISTICS, we will
select a data path for future use.
If this is a transfer function, it will either be processed in word
or block mode.
CMPB
BNEQ

D-10

#IO$ SETCHAR,R2
3$ -

Set characteristics?

Sample Driver for the DR11-W and DRV11-WA Interfaces

; ++
SET CHARACTERISTICS - Process Set Characteristics QIO function
INPUTS:
XA DATAPATH bit in Device Characteristics specifies which data path
to use. If bit is a one, use buffered data path.
If zero, use
direct datapath.
OUTPUTS:
CRB is flagged as to which datapath to use.
DEVDEPEND bits in device characteristics is updated
XA_DATAPATH
1 -> buffered data path in use
XA_DATAPATH = 0 -> direct data path in use
MOVL
MOVQ
BISB
BBC
BICB

UCB$L CRB(R5),R0
; Get CRB address
IRP$L-MEDIA(R3),UCB$B DEVCLASS(R5) ;Set device characteristics
#VEC$M PATHLOCK,CRB$L-INTD+VEC$B DATAPATH(RO)
; Assume direct datapath
#XA$V DATAPATH,UCB$L DEVDEPEND(R5),2$; Were we right?
#VEC$M_PATHLOCK,CRB$L_INTD+VEC$B_DATAPATH(RO) ;Set buffered
;datapath

2$:
CLRL
MOVZWL
REQCOM

Rl
#SS$_NORMAL,RO

Return Success

; If subfunction modifier for device reset is set, do one here
3$:

BBC
BSBW

SA#IO$V_RESET,Rl,4$
XA DEV RESET

Branch if not device reset
; Reset DRll-W

This must be a data transfer function - i.e. READ OR WRITE
Check to see if this is a zero length transfer.
If so, only set CSR FNCT bits and return STATUS from CSR
4$:

TSTW
UCB$W BCNT(R5) •
Is transfer count zero?
BNEQ
10$ No, continue with data transfer
BBC
SA#IO$V_SETFNCT,Rl,6$
Set CSR FNCT specified?
DEVICELOCK LOCKADDR=UCB$L_DLCK(R5),-; Lock device access
SAVIPL=-(SP),Save current IPL
PRESERVE=NO
Don't preserve RO
MOVW
IRP$L_SEGVBN+2(R3),XA_ODR(R4)
; Store word in ODR
MOVZWL XA CSR(R4),RO
BICW
#<XA CSR$M FNCT!XA CSR$M ERROR>,RO
BISW
IRP$L SEGVBN(R3),RO
BISW
#XA_CSR$M_ATTN,RO
Force ATTN on to prevent lost
interrupt
MOVW
RO,XA CSR(R4)
#XA$V-LINK,UCB$L DEVDEPEND(R5),5$
BBC
Link mode?
BICW3
Make FNCT bit 2 a pulse
#XA$K=FNCT2,RO,XA_CSR(R4)

5$:
DEVICEUNLOCK LOCKADDR=UCB$L_DLCK(R5),-; Unlock device access
NEWIPL=(SP)+,Enable interrupts
PRESERVE=NO
6$:

7$:

BSBW
BLBS
JSB
JSB

XA REGISTER
R0,7$
G"ERL$DEVICERR
GAIOC$DIAGBUFILL

Fetch DRll-W registers
If error, then log it
Log a device error
Fill diagnostic buffer if specified

D-11

Sample Driver for the DR11-W and DRV11-WA Interfaces

MOVL
MOVZWL
BISB
RE QC OM

UCB$W XA CSR(R5),Rl
UCB$W-XA-ERROR(R5) ,RO
#XA_CSR$M_IE,XA_CSR(R4)

Return CSR and EIR in Rl
Return status in RO
Enable device interrupts
Request done

; Build CSR image in RO for later use in starting transfers
10$:
MOVZWL
DIVL3

UCB$W BCNT(R5) ,RO

#2,RO~UCB$L_XA_DPR(R5)

Fetch byte count
Make byte count into word count

; Set up UCB$W_CSRTMP used for loading CSR later

20$:

MOVZWL
BICW
BISW
BBC
BICW
BISB
BBC
BISW

XA_CSR(R4),RO
#AC<XA_CSR$M_FNCT>,RO
; Set Interrupt Enable and ATTN
#XA CSR$M IE!XA CSR$M ATTN,RO
SA#IO$V SETFNCT~Rl,20$
Set FNCT bits in CSR?
#<XA_CSR$M_FNCT>,RO
Yes, Clear previous FNCT bits
IRP$L SEGVBN(R3),RO
OR in new value
sA#Io$v DIAGNOSTIC,Rl,23$ ; Check for maintenance function
#XA_CSR$M_MAINT,RO
Set maintenance bit in CSR image

; Is this a word mode or block mode request?
23$:

MOVW
BBC
BRW

R0,UCB$W_XA_CSRTMP(R5)
; Save CSR image in UCB
SA#IO$V_WORD,Rl,BLOCK_MODE ; Check if word or block mode
WORD_MODE
; Branch to handle word mode

;++
BLOCK MODE -- Process a Block Mode (DMA) transfer request
FUNCTIONAL DESCRIPTION:
This routine takes the buffer address, buffer size, function code,
and function modifier fields from the IRP.
It calculates the UNIBUS
address, allocates the UBA map registers, loads the DRll-W device
registers and starts the request.
; Set up UBA
; Start transfer
BLOCK MODE:
; If IO$M_CYCLE subfunction is specified, set CYCLE bit in CSR image
BBC
BISW

#IO$V CYCLE,Rl,25$
; Set CYCLE bit in CSR?
#XA_CSR$M_CYCLE,UCB$W_XA_CSRTMP(R5) ; If yes, OR into CSR image

Allocate UBA data path and map registers
25$:
REQDPR
REQMPR
LOADUBA

Request UBA data path
Request UBA map registers
Load UBA map reqisters

Calculate the UNIBUS transfer address for the DRll-W from the UBA
map register address and byte offset.

D-12

Sample Driver for the DR11-W and DRV11-WA Interfaces

MOVZWL
MOVL
INSV
EXTZV
CMPB

100$:

BEQL
MOVW
CLRL
ASHL
BISW
BISW
BICW3
BICW3
MOVW

UCB$W_BOFF(R5),Rl
; Byte offset in first page of xfer
UCB$L CRB(R5),R2
; Address of CRB
CRB$L=INTD+VEC$W_MAPREG(R2),#9,#9,Rl
Insert page number
#16, #2, Rl, R2
Extract bits 17:16 of bus address
#DT$_DR11W, If this is a DRll-W,
UCB$B_DEVTYPE(R5)
then branch.
100$
R2,UCB$W_XA_BAETMP(R5)
Save value of BAE prior to transfer
Clear XBA bits
R2
#XA CSR$V XBA,R2,R2
Shift extended memory bits for CSR
#XA-CSR$M-GO,R2
Set "GO" bit into CSR image
R2,UCB$W XA CSRTMP(RS)
Set into CSR image we are building
#<XA_CSR$M_GO!XA_CSR$M_CYCLE>,UCB$W XA CSRTMP(R5),RO
; CSR image less "GO" and "CYCLE"
#XA$K FNCT2,UCB$W XA CSRTMP(R5),R2 ; CSR image less FNCT bit 2
Rl,UCB$W_XA_BARTMP(RS)
; Save BAR for error logging

At this juncture:
RO
CSR image less "GO" and "CYCLE"
Rl = low 16 bits of transfer bus address
R2 = CSR image less FNCT bit 2
UCB$L_XA_DPR(R5) = transfer count in words
UCB$W_XA_CSRTMP(R5) =CSR image to start transfer with
Set DRll-W registers and start transfer
Note that read-modify-write cycles are NOT performed to the DRll-W CSR.
The CSR is always written directly into. This prevents inadvertently
setting the EIR select flag (writing bit 15) if error happens to become
true.

200$:

DEVICELOCK LOCKADDR=UCB$L_DLCK(R5),- ; Lock device access
SAVIPL=-(SP),Save current IPL
PRESERVE=YES
Preserve RO
SETIPL #31,Raise to IPL$_POWER
ENVIRON=UNIPROCESSOR
MNEGW
UCB$L_XA_DPR(R5),XA_WCR(R4)
Load negative of transfer count
MOVW
Rl, XA BAR (R4)
Load low 16 bits of bus address
CMPB
#DT$_DR11W, If this is a DRll-W,
UCB$B_DEVTYPE(R5)
BEQL
200$
then branch.
MOVW
UCB$W_XA_BAETMP(R5),Load high bits of bus address
XA_BAE (R4)
MOVW
RO,XA CSR(R4)
;Load CSR image less "GO" and "CYCLE"
BBC
#XA$V=LINK,UCB$L_DEVDEPEND(R5),26$ ;Link mode?
MOVW
R2,XA CSR(R4)
;Yes, load CSR image less "FNCT" bit 2
BRB
126$ ;Only if link mode in dev characteristics

26$:
MOVW

UCB$W_XA_CSRTMP(R5),XA CSR(R4)

; Move all bits to CSR

; Wait for transfer complete interrupt, powerfail, or device timeout
126$:
WFIKPCH XA_TIME_OUT,IRP$L_MEDIA(R3)

; Wait for interrupt

Device has interrupted, FORK
IO FORK

; FORK to lower IPL

Handle request completion, release UBA resources, check for errors

D-13

Sample Driver for the DR11-W and DRV11-WA Interfaces

27$:

MOVZWL
CLRW
PURDPR
BLBS
MOVZWL
INCB
MOVL
EXTZV
MOVB
EXTZV
CMPB

300$:
310$:

BEQL
MOVZWL
BRB
EXTZV
INSV
CMPW
BGTR
MOVL
CLRL
DECL
CMPV
BGTR
MOVL

28$:

RELMPR
RELDPR

#SS$ NORMAL,-(SP)
UCB$W_XA_DPRN(R5)

Assume success, store code on stack
Clear DPR number and DPR error flag
Purge UBA buffered data path
R0,27$
Branch if no datapath error
#SS$ PARITY, (SP)
Flag parity error on device
UCB$W_XA_DPRN+l(R5)
Flag PDR error for log
Rl,UCB$L XA DPR(R5)
Save data path register in UCB
#VEC$V_DATAPATH,Get Datapath register no.
#VEC$S_DATAPATH,For Error Log
CRB$L_INTD+VEC$B_DATAPATH(R3),RO
R0,UCB$W XA DPRN(R5)
Save for later in UCB
#9,#7,UCB$W-XA BAR(R5),R0; Low bits, final map register no.
#DT$ DRllw,= If this is a DRll-W,
UCB$B_DEVTYPE(R5)
300$
then branch.
UCB$W XA BAE(R5),Rl
Fetch high bits of map register no.
310$ - #4,#2,UCB$W XA CSR(R5),Rl; Hi bits of map register no.
Rl,#7,#2,RO- Entire map register number
R0,#496
Is map register number in range?
28$
No, forget it - compound error
(R2) [R0],UCB$L XA FMPR(R5) ; Save map register contents
UCB$L_XA_PMPR(R5); Assume no previous map register
RO
; Was there a previous map register?
#VEC$V MAPREG,#VEC$S MAPREG,CRB$L INTD+VEC$W MAPREG(R3),RO
28$ ; No if gtr
(R2) [R0],UCB$L_XA_PMPR(R5) ; Save previous map register
; contents
; Release UBA resources

; Check for errors and return status

30$:

35$:

TSTW
BEQL
MOVZWL
BBC
MOVZWL
BSBW
BLBS
CMPW
BNEQ
CMPB
BEQL
BBS

37$:

JSB

40$:

BSBW
JSB
MOVL
MULW3
ADDW
INSV
MOVL
BISB
RE QC OM

D-14

UCB$W XA WCR(R5)
All words transferred?
30$ - Yes
#SS$ OPINCOMPL, (SP)
No, flag operation not complete
#XA CSR$V ERROR,UCB$W XA CSR(R5),35$; Branch on CSR error bit
UCB$W_XA_ERROR(R5), (SP)
Flag for controller/drive error
status
XA DEV RESET
Reset DRll-W
(SP),40$
Any errors after all this?
(SP),#SS$ OPINCOMPL
Log the error, unless this is
37$
a DRVll-WA running in link mode
#DT$_DR11W, and the operation is incomplete,
UCB$B DEVTYPE(R5)
in which case it is an expected
37$
error and not worth logging.
#XA$V LINK,UCB$L DEVDEPEND(RS),40$
G"ERL$DEVICERR
Log the error.
DEL ATTNAST
G"IOC$DIAGBUFILL
(SP)+,RO
#2,UCB$W_XA_WCR(R5),Rl
UCB$W_BCNT(R5),Rl
Rl ' n 6, n 6' RO
UCB$W XA CSR(RS),Rl
#XA_CSR$M_IE,XA_CSR(R4)

Deliver outstanding ATTN ASTs
Fill diagnostic buffer
Get final device status
Calculate final transfer count
Insert into high byte of IOSB
Return CSR and EIR in IOSB
Enable interrupts
Finish request in exec

Sample Driver for the DR11-W and DRV11-WA Interfaces

.DSABL LSB
;++
WORD MODE -- Process word mode (interrupt per word) transfer
FUNCTIONAL DESCRIPTION:
Data is transferred one word at a time with an interrupt for each word.
The request is handled separately for a write (from memory to DRll-W
and a read (from DRll-W to memory) .
For a write, data is fetched from memory, loaded into the ODR of the
DRll-W and the system waits for an interrupt. For a read, the system
waits for a DRll-W interrupt and the !DR is transferred into memory.
If the unsolicited interrupt flag is set, the first word is transferred
directly into memory withou waiting for an interrupt .
. ENABL
WORD MODE:

LSB

Dispatch to separate loops on READ or WRITE
CMPB
BNEQ
BRW

#IO$ READPBLK,R2
10$ 30$

Check for read function
Br if not, must be write function
Else, read

;++
WORD MODE WRITE -- Write (output) in word mode
FUNCTIONAL DESCRIPTION:
Transfer the requested number of words from user memory to
the DRll-W ODR one word at a time, wait for interrupt for each
word.
10$:
BSBW
Get two bytes from user buff er
MOVFRUSER
DEVICELOCK LOCKADDR=UCB$L_DLCK(R5),-; Lock device access
SAVIPL=-(SP),Save current IPL
PRESERVE=NO
Don't preserve RO
Flag interrupt expected
SETIPL #31,Raise IPL to power
ENVIRON=UNIPROCESSOR
MOVW
Rl,XA ODR(R4)
Move data to DRll-W
MOVW
UCB$W-XA CSRTMP(R5),XA CSR(R4) ; Set DRll-W CSR
BBC
#XA$V-LINK,UCB$L DEVDEPEND(R5),15$; Link mode?
BICW3
#XA$K-FNCT2,UCB$W XA CSRTMP(R5),XA CSR(R4) ;Clear interrupt
FNCT bit-2
; Only if link mode specified
15$:
; Wait for interrupt, powerfail, or device timeout
WFIKPCH XA_TIME_OUTW,IRP$L_MEDIA(R3)
Check for errors, decrement transfer count, and loop until complete

D-15

Sample Driver for the DR11-W and DRV11-WA Interfaces

IOFORK
CMPB
BEQL
BBC

17$:

20$:

BRW
BITW

BEQL
BRW
DECW
BNEQ

Fork to lower IPL
#DT$_DR11W,Branch if this is a DRll-W
UCB$B DEVTYPE(R5)
17$
#XA CSR$V ERROR,DRVll-WA - check ERROR bit in CSR.
UCB$W XA CSR(R5),20$
Branch on success.
40$
Branch on error.
#XA EIR$M NEX!XA EIR$M MULTI!XA-EIR$M-ACLO!XA-EIR$M-PAR!XA-EIR$M-DLT, UCB$W XA EIR(R5) ; Any errors?
20$
No, continue
40$
Yes, abort transfer.
UCB$L XA DPR(R5)
; All words transferred?
10$ No, loop until finished.

; Transfer is done, clear iterrupt expected flag and FORK
; All words read or written in WORD MODE. Finish I/O.
RETURN STATUS:

22$:

JSB
BSBW
MOVZWL
MULW3
SUBW3
INSV
MOVL
BISB
REQCOM

GAIOC$DIAGBUFILL
DEL ATTNAST
#SS$ NORMAL,RO
#2,UCB$L XA DPR(R5),Rl
Rl,UCB$W-BCNT(R5),Rl
Rl, #16, #l6, RO
UCB$W XA CSR(R5),Rl
#XA_CSR$M_IE,XA_CSR(R4)

Fill diagnostic buffer if present
Deliver outstanding ATTN ASTs
Complete success status
Calculate actual bytes transferred
From requested number of bytes
And place in high word of RO
Return CSR and EIR status
Enable device interrupts
Finish request in exec

;++
WORD MODE READ -- Read (input) in word mode
FUNCTIONAL DESCRIPTION:
Transfer the requested number of words from the DRll-W IDR into
user memory one word at a time, wait for interrupt for each word.
If the unexpected (unsolicited) interrupt bit is set, transfer the
first (last received) word to memory without waiting for an
interrupt.
30$:
DEVICELOCK LOCKADDR=UCB$L_DLCK(R5),-; Lock device access
SAVIPL=-{SP),Save current IPL
PRESERVE=NO
Don't preserve RO
If an unexpected (unsolicited) interrupt has occurred, assume it
is for this READ request and return value to user buffer without
waiting for an interrupt.
BBCC

#UCB$V UNEXPT,UCB$W_DEVSTS (R5) ,32$

Branch if no unexpected interrupt

DEVICEUNLOCK LOCKADDR=UCB$L_DLCK(R5),- ; Unlock device access
NEWIPL=(SP)+,Enable interrupts
PRESERVE=NO
BRB
37$
continue
32$:
SETIPL

D-16

#IPL$_POWER,ENVIRON=UNIPROCESSOR

Sample Driver for the DR11-W and DRV11-WA Interfaces

35$:
; Wait for interrupt, powerfail, or device timeout
WFIKPCH XA_TIME_OUTW,IRP$L_MEDIA(R3)
; Check for errors, decrement transfer count and loop until done
I OF ORK

Fork to lower IPL

37$:
CMPB
BEQL
BBC
1037$:

BRW
BITW

1038$:

BNEQ
BSBW

#DT$_DR11W,Branch if this is a DRll-W
UCB$B_DEVTYPE(R5)
1037$
#XA_CSR$V_ERROR,; DRVll-WA - check ERROR bit in CSR.
UCB$W_XA_CSR(R5),1038$; Branch on success.
40$
; Branch on error.
#XA_EIR$M_NEX!XA EIR$M MULTI!XA-EIR$M-ACLO!XA-EIR$M-PAR!XA-EIR$M-DLT, UCB$W XA EIR(R5) ; Any errors?
40$
- ; Yes, abort transfer.
MOVTOUSER
; Store two bytes into user buff er

; Send interrupt back to sender.

Acknowledge we got last word.

DEVICELOCK LOCKADDR=UCB$L_DLCK(R5),-; Lock device access
SAVIPL=-(SP),Save current IPL
PRESERVE=NO
Don't preserve RO
MOVW
UCB$W XA CSRTMP(R5),XA CSR(R4)
BBC
#XA$V-LINK,UCB$L DEVDEPEND(R5),38$; Link mode?
BICW3
#XA$K=FNCT2,UCB$W_XA_CSRTMP(R5),XA_CSR(R4) ;Yes, clear
; FNCT 2
38$:
DECW
UCB$L XA DPR(R5)
Decrement transfer count
BNEQ
35$ - Loop until all words transferred
DEVICEUNLOCK LOCKADDR=UCB$L_DLCK(R5),- ; Unlock device access
NEWIPL=(SP)+,Enable interrupts
PRESERVE=NO
BRW
RETURN STATUS
Finish request in common code
; Error detected in word mode transfer
40$:
BSBW
BSBW
JSB
JSB
MOVZWL
BRW

DEL ATTNAST
XA DEV RESET
GAIOC$DIAGBUFILL
GAERL$DEVICERR
UCB$W XA ERROR(R5),RO
22$ - -

Deliver ATTN ASTs
Error, reset DRll-W
Fill diagnostic buffer if present
Log device error
Set controller/drive status in RO

D-17

Sample Driver for the DR11-W and DRV11-WA Interfaces

.DSABL

LSB

MOVFRUSER - Routine to fetch two bytes from user buffer.
INPUTS:
RS

UCB address

OUTPUTS:
Rl =Two bytes of data from user's buffer
Buffer descriptor in UCB is updated .
. ENABL
MOVFRUSER:
MOVAL
MOVZBL
JSB
MOVL
BRB

LSB
-(SP),Rl
#2,R2
GAIOC$MOVFRUSER
(SP)+,Rl
20$

Address of temporary stack loc
Fetch two bytes
Call exec routine to do the deed
Retrieve the bytes
Update UCB buffer pointers

MOVTOUSER - Routine to store two bytes into user's buffer.
INPUTS:
RS = UCB address
UCB$W_XA_IDR (RS)

Location where two bytes are saved

OUTPUTS:
Two bytes are stored in user buffer and buffer descriptor in
UCB is updated.
MOVTOUSER:
MOVAB
MOVZBL
JSB
20$:
ADDW
BICW
BNEQ
ADDL
30$:
RSB
.DSABL

UCB$W XA IDR(RS),Rl
#2,R2- GAIOC$MOVTOUSER

Address of internal buff er

Call exec
Update buff er pointers in UCB
#2,UCB$W_BOFF(RS)
Add two to buffer descriptor
#AC<AX01FF>,UCB$W_BOFF(RS) ; Modulo the page size
30$
If NEQ, no page boundary crossed
#4,UCB$L_SVAPTE(RS)
; Point to next page

LSB

.PAGE
.SBTTL

DRll-W DEVICE TIMEOUT
;++
DRll-W device TIMEOUT
If a DMA transfer was in progress, release UBA resources.
For DMA or WORD mode, deliver attention ASTs, log a device timeout error,
and do a hard reset on the controller.
Clear DRll-W CSR
Return error status
Power failure will appear as a device timeout
.ENABL
XA TIME OUT:

D-18

LSB
Timeout for DMA transfer

Sample Driver for the DR11-W and DRV11-WA Interfaces

BSBW
IOFORK
PURDPR
RELMPR
RELDPR
BRB

XA DEV HWRESET

10$

XA TIME OUTW:

20$:

IOFORK
MOVL
MOVL
BSBW
JSB
JSB
BSBW
BSBW
MOVZWL
BBC
MOVZWL
CLRL
BICW
BICW
REQCOM
.DSABL
.PAGE

Fork to complete request
Purge buffered data path in UBA
Release UBA map registers
Release UBA data path
continue
Timeout for WORD mode transfer

10$:

reset h/w &
blow away any outstanding DMA

Fork to complete operations
UCB$L_CRB(R5),R4
Fetch address of CSR
@CRB$L INTD+VEC$L IDB(R4),R4
XA REGISTER
Read DRll-W registers
GAIOC$DIAGBUFILL
Fill diagnostic buffer
GAERL$DEVICTMO
Log device time out
DEL ATTNAST
And deliver the ASTs
XA DEV RESET
Reset controller
#SS$ TIMEOUT,RO
Assume error status
#UCB$V CANCEL,UCB$W STS(RS),20$
Branch if not cancel
#SS$_CANCEL,RO
Set status
Rl
#UCB$M_ATTNAST!UCB$M_UNEXPT,UCB$W_DEVSTS(R5)
; Clear unwanted flags.
#<UCB$M TIM!UCB$M INT!UCB$M TIMOUT!UCB$M CANCEL!UCB$M POWER>,UCB$W STS(R5)
Clear unit status flags
; Complete I/O in exec
LSB

.SBTTL XA_INTERRUPT, Interrupt service routine for DRll-W
;++
XA_INTERRUPT, Handles interrupts generated by DRll-W
Functional description:
This routine is entered whenever an interrupt is generated
by the DRll-W. It checks that an interrupt was expected.
If not, it sets the unexpected (unsolicited) interrupt flag.
All device registers are read and stored into the UCB.
If an interrupt was expected, it calls the driver back at its Wait
For Interrupt point.
Deliver attention ASTs if unexpected interrupt.
Inputs:
OO(SP)
04(SP)
08(SP)
12(SP)
16(SP)
20(SP)
24(SP)
28(SP)
32(SP)

Pointer to address of the device IDB
saved RO
saved Rl
saved R2
saved R3
saved R4
saved RS
saved PSL
saved PC

Outputs:
The driver is called at its Wait For Interrupt point if an
interrupt was expected.
The current value of the DRll-W CSRs are stored in the UCB.

D-19

Sample Driver for the DR11-W and DRV11-WA Interfaces

;--

XA INTERRUPT:
MOVL
MOVQ

@(SP)+,R4
(R4),R4

Interrupt service for DRll-W
Address of IDB and pop SP
CSR and UCB address from IDB

DEVICELOCK LOCKADDR=UCB$L_DLCK(R5),-; Lock device access
CONDITION=NOSETIPL,already at DIPL
PRESERVE=NO
Don't preserve RO
Read the DRll-W device registers (WCR, BAR, CSR, EIR, IDR) and store
into UCB.
BSBW

XA REGISTER

; Read device registers

Check to see if device transfer request active or not
If so, call driver back at Wait for Interrupt point and
Clear unexpected interrupt flag.
20$:

BBCC

#UCB$V_INT,UCB$W_STS(R5),25$
; If clear, no interrupt expected

Interrupt expected, clear unexpected interrupt flag and call driver
back.
BICW
MOVL
JSB
BRB

#UCB$M_UNEXPT,UCB$W_DEVSTS(R5)
Clear unexpected interrupt flag
UCB$L_FR3(R5),R3
Restore driver's R3
@UCB$L_FPC(R5)
Call driver back
30$

Deliver attention ASTs if no interrupt expected and set unexpected
interrupt flag.
25$:

BBSC
BISW
BSBW
BISB
BRB

#UCB$V IGNORE UNEXPT,- ; Ignore spurious interrupt UCB$W DEVSTS(R5),24$
(DRVll-WA only.)
#UCB$M_UNEXPT,UCB$W_DEVSTS(R5) ;Set unexpected interrupt flag
DEL ATTNAST
Deliver attention ASTs
#XA-CSR$M IE,XA CSR(R4) ; Enable device interrupts
30$-

Restore registers and return from interrupt
24$:

NOP

30$:

DEVICEUNLOCK LOCKADDR=UCB$L_DLCK(R5),-; Unlock device access
PRESERVE=NO
POPR
#AM<R0,Rl,R2,R3,R4,R5>
Restore registers
REI
Return from interrupt
.PAGE

D-20

; allow a breakpoint here (spurious interrupt)

Sample Driver for the DR11-W and DRV11-WA Interfaces

.SBTTL XA REGISTER - Handle DRll-W CSR transfers
;++
XA REGISTER - Routine to handle DRll-W register transfers
INPUTS:
R4 - DRll-W CSR address
RS - UCB address of unit
OUTPUTS:
CSR, EIR, WCR, BAR, BAE, IDR, and status are read and stored into UCB.
The DRll-W is placed in its initial state with interrupts enabled.
RO - .true. if no hard error
.false. if hard error (cannot clear ATTN)
If the CSR ERROR bit is set and the associated condition can be cleared,
then the error is transient and recoverable. The status returned is
SS$_DRVERR. If the CSR ERROR bit is set and cannot be cleared by
clearing the CSR, then this is a hard error and cannot be recovered.
The returned status is SS$_CTRLERR.
RO,Rl - destroyed, all other registers preserved.
;--

XA REGISTER:

55$:

MOVZWL
MOVZWL
MOVW
BBC
MOVZWL
BICW

#SS$_NORMAL,RO
XA CSR(R4),Rl
Rl~UCB$W XA CSR(R5)
#XA_CSR$V_ERROR,Rl,55$
#SS$_DRVERR,RO
#AC<XA_CSR$M_FNCT>,Rl

CMPB

#DT$_XA_DRV11WA,UCB$B_DEVTYPE(R5)
57$

BEQL

Assume success
Read CSR
Save CSR in UCB
Branch if no error
Assume "drive" error
Clear all uninteresting bits
for later
If this is a DRVll-WA,
then branch.

The guide to programming DRxll's stresses over and over again that clearing
the ATTN bit (by writing a 0 to it) can lead to a lost interrupt (i.e., a
pending interrupt request can be flushed) . We will handle this case by
always setting the ATTN bit in the CSR/EIR- which is benign.

57$:

BISB
MOVW
BRB
BISW

#<XA CSR$M ERROR!XA CSR$M ATTN/256>,XA CSR+l(R4) ;Set EIR flag
XA_EIR(R4)~UCB$W_XA=EIR(RS) ; Save EIR-in UCB
59$
#XA_CSR$M_IE,Rl
On the DRVll-WA, if the IE bit
makes a 0->1 transition while
READY=l, a spurious interrupt
in generated.
Therefore, we
leave IE high at all times.

The guide to programming DRxll's stresses over and over again that
clearing the ATTN bit (by writing a 0 to it) can lead to a lost
interrupt (i.e., a pending interrupt request can be flushed). We will
handle this case by always setting the ATTN bit in the CSR/EIR- which
is benign.
59$:
60$:

BISW3
MOVW
MOVW
MOVW
CMPB

#XA_CSR$M_ATTN,Rl,XA_CSR(R4) ; Clear EIR flag and errors
XA CSR(R4),Rl
; Read CSR back
XA=IDR(R4),UCB$W_XA_IDR(R5) ; Save IDR in UCB
XA BAR(R4),UCB$W XA BAR(RS)
#DT$_DR11W,; If this is a DRll-W,

D-21

Sample Driver for the DR11-W and DRV11-WA Interfaces

70$:

BEQL
MOVW
MOVW
MOVW
RSB

UCB$B_DEVTYPE(R5)
70$
then branch.
XA BAE(R4),UCB$W XA BAE(R5) ; Save BAE in UCB
XA-WCR(R4),UCB$W-XA-WCR(R5)
RO~UCB$W_XA_ERROR(RS)
; Save status in UCB

.SBTTL XA_CANCEL, Cancel I/O routine
;++
XA_CANCEL, Cancels an I/O operation in progress
Functional description:
Flushes Attention AST queue for the user.
If transfer in progress, do a device reset to DRll-W and finish the
request.
Clear interrupt expected flag.
Inputs:
R2
R3
R4
R5

negated value of channel index
address of current IRP
address of the PCB requesting the cancel
address of the device's UCB

Outputs:

XA CANCEL:

; Cancel I/O

DEVICELOCK LOCKADDR=UCB$L_DLCK(R5),Lock device access
SAVIPL=-(SP),Save current IPL
PRESERVE=NO
Don't preserve RO
BBCC
#UCB$V ATTNAST,UCB$W_DEVSTS (R5) ,20$
attention AST enabled?
Finish all attention ASTs for this process.
PUS HR
MOVL
MOVAB
JSB
POPR

#"M<R2,R6,R7>
R2,R6
UCB$L XA ATTN(R5),R7
G"COM$FLUSHATTNS
#"M<R2,R6,R7>

Set up channel number
Address of listhead
Flush attention ASTs for process

Check to see if a data transfer request is in progress
for this process on this channel

D-22

Sample Driver for the DR11-W and DRV11-WA Interfaces

20$:

BBC

#UCB$V INT,UCB$W STS(RS),30$
G"'IOC$CANCELIO
#UCB$V_CANCEL,UCB$W_STS (RS) ,30$

JSB
BBC

Branch if I/O not in progress
Check if transfer going
Branch if not for this guy

Force timeout
UCB$L DUETIM(RS)
; Clear timer
#UCB$M TIM,UCB$W STS(RS) ; set timed
#UCB$M-TIMOUT,- UCB$W_STS(R5)
; Clear timed out

CLRL
BISW
BICW
30$:

DEVICEUNLOCK LOCKADDR=UCB$L_DLCK(RS),-; Unlock device access
NEWIPL=(SP)+,Enable interrupts
PRESERVE= NO
RSB
Return
.PAGE
.SBTTL

DEL_ATTNAST, Deliver attention ASTs
;++
DEL_ATTNAST, Deliver all outstanding attention ASTs
Functional description:
This routine is used by the DRll-W driver to deliver all of the
outstanding attention ASTs.
It is copied from COM$DELATTNAST in
the exec. In addition, it places the saved value of the DRll-W CSR
and Input Data Buffer Register in the AST parameter.
Inputs:
RS

UCB of DRll-W unit

Outputs:
RO,Rl,R2 Destroyed
R3,R4,RS Preserved
DEL ATTNAST:
DEVICELOCK LOCKADDR=UCB$L_DLCK(R5),-; Lock device access
SAVIPL=-(SP),Save current IPL
PRESERVE=NO
Don't preserve RO
BBCC
#UCB$V_ATTNAST,UCB$W_DEVSTS(R5),30$
Any attention ASTs expected?
PUSHR
#"'M<R3,R4,RS>
Save R3,R4,RS
10$:
MOVL
8(SP),Rl
Get address of UCB
MOVAB
UCB$L_XA_ATTN(Rl),R2
Address of attention AST listhead
MOVL
(R2),RS
Address of next entry on list
BEQL
20$
No next entry, end of loop
#UCB$M_UNEXPT,UCB$W_DEVSTS(Rl) ;Clear unexpected interrupt
BICW
; flag
MOVL
(RS), (R2)
; Close list
MOVW
UCB$W XA IDR(Rl),ACB$L_KAST+6(RS}
; Store IDR in AST parameter
MOVW
UCB$W_XA_CSR(Rl),ACB$L_KAST+4(RS)
Store CSR in AST parameter
PUSHAB B"'l0$
Set return address for FORK
FORK
FORK for this AST
AST fork procedure

D-23

Sample Driver for the DR11-W and DRV11-WA Interfaces

MOVQ
MOVB
MOVL
CLRL
MOVZBL
JMP
20$:
30$:

ACB$L_KAST(R5),ACB$L_AST(R5)
; Rearrange entries
ACB$L_KAST+8(R5),ACB$B_RMOD(R5)
ACB$L_KAST+l2(R5),ACB$L_PID(R5)
ACB$L_KAST(R5)
#PRI$_IOCOM,R2
Set up priority increment
GASCH$QAST
Queue the AST

POPR
#AM<R3,R4,R5>
Restore registers
DEVICEUNLOCK LOCKADDR=UCB$L_DLCK(R5),- ; Unlock device access
NEWIPL=(SP)+,Enable interrupts
PRESERVE=NO,CONDITION=RESTORE
RSB
Return
.PAGE
.SBTTL

XA REGDUMP - DRll-W register dump routine
;++
XA REGDUMP - DRll-W Register dump routine.
This routine is called to save the controller registers in a specified
buffer.
It is called from the device error logging routine and from the
diagnostic buffer fill routine.
Inputs:
RO - Address of register save buffer
R4 - Address of Control and Status Register
R5 - Address of UCB
Outputs:
The controller registers are saved in the specified buffer.
CSRTMP - The last command written to the DRll-W CSR by
by the driver.
BARTMP - The last value written into the DRll-W BAR by
the driver during a block mode transfer.
CSR - The CSR image at the last interrupt
EIR - The EIR image at the last interrupt
IDR - The IDR image at the last interrupt
BAR - The BAR image at the last interrupt
WCR - Word count register
ERROR - The system status at request completion
PDRN - UBA Datapath Register number
DPR - The contents of the UBA Data Path register
FMPR - The contents of the last UBA Map register
PMRP - The contents of the previous UBA Map register
DPRF - Flag for purge datapath error
0 = no purger datapath error
1 = parity error when datapath was purged
BAETMP - The last value written to the BAE by the
driver during a block mode transfer (DRVll-WA only)
BAE - The BAE image at the last interrupt (DRVll-WA only)
Note that the values stored are from the last completed transfer
operation. If a zero transfer count is specified, then the
values are from the last operation with a non-zero transfer count.
XA REGDUMP:

D-24

Sample Driver for the DR11-W and DRV11-WA Interfaces

10$:

20$:

MOVZBL
MOVAB
MOVZBL
MOVZWL
SO BG TR
MOVZBL
MOVZBL
MOVL
SO BG TR
MOVZBL
MOVZWL
MOVZWL
RSB

#15, (RO)+
; 15 registers are stored.
UCB$W_XA_CSRTMP(R5),Rl ;Get address of saved register images
#8,R2
Return 8 registers here
(Rl) +, (RO)+
R2,10$
Move them all
UCB$W_XA_DPRN(R5), (RO)+
Save Datapath Register number
#3,R2
And 3 more here
(Rl) +, (RO)+
Move UBA register contents
R2,20$
UCB$W XA DPRN+l(R5), (RO)+; Save Datapath Parity Error Flag
UCB$W-XA-BAETMP(R5), (RO)+; Save BAE stored prior to xfer
UCB$W=XA=BAE(R5), (RO)+
Save BAE store following xfer

.PAGE
.SBTTL

XA DEV RESET - Device reset DRll-W
;++
XA DEV RESET - DRll-W Device reset routine
This routine raises IPL to device IPL, performs a device reset to
the required controller, and reenables device interrupts.
Must be called at or below device IPL to prevent a confict in
acquiring the device spinlock.
Inputs:
R4 - Address of Control and Status Register
RS - Address of UCB
Outputs:
Controller is reset, controller interrupts are enabled

XA DEV RESET:
PUSHR
#AM<R0,Rl,R2>
Save some registers
DEVICELOCK LOCKADDR=UCB$L_DLCK(R5),- ; Lock device access
SAVIPL=-(SP),Save current IPL
PRESERVE=NO
Don't preserve RO
BSBB

XA DEV HWRESET

DEVICEUNLOCK LOCKADDR=UCB$L_DLCK(R5),- ; Unlock device access
NEWIPL=(SP)+,Enable interrupts
PRESERVE=NO
POPR
#AM<R0,Rl,R2>
Restore registers
RSB
XA DEV HWRESET:
CMPB
BEQL
MOVW
BITB
BNEQ

#DT$ DRllW, If this is a DRll-W,
UCB$B_DEVTYPE(R5)
20$
then branch.
#XA CSR$M IE,XA CSR(R4)
Clear all writable bits but IE.
#XA=CSR$M=RDY,XA_CSR(R4); If not ready then no transfer
in progress,
40$
so no need to reset device

D-25

Sample Driver for the DR11-W and DRV11-WA Interfaces

MNEGW
BISB

20$:

CLRW
BRB
MOVB
CLRB

#1,XA WCR(R4)
;Tell it only 1 byte left to transfer
#<XA_CSR$M_CYCLE!XA_CSR$M ATTN>/256,XA_CSR+l (R4)
and complete the transfer.
XA_CSR(R4)
; Clear any errors
30$
#<XA_CSR$M_MAINT/256>,XA_CSR+l(R4)
XA_CSR+l(R4)

; ***

Must delay here depending on reset interval

30$:

TIMEDWAIT TIME=#XA_RESET_DELAY

40$:

MOVB
RSB

XA END:

End of driver label
.END

D-26

#XA_CSR$M_IE,XA_CSR(R4)

No. of 10 micro-sec intervals
to wait
Reenable device interrupts

Multiprocessing Requirements on Kernel-Mode Code

Several features introduced in recent VMS releases have some impact
on the execution of non-Digital-supplied kernel-mode code, most notably
device drivers written prior to VMS Version 5.0. This chapter describes
those changes Digital requires or recommends in an existing non-Digitalsupplied device driver. It also provides a brief explanation of key VMS
concepts that are integral to an understanding of the operation of
privileged code in recent VMS versions.

E.1

Uniprocessor and Multiprocessor Device Drivers
One of the most significant components of VMS introduced at Version
5.0 is its support of a symmetric multiprocessing environment for
certain VAX systems, including the VAX 8300/8350, VAX 8800/8820
/8830, VAX 6000, and VAX 9000 series. The multiprocessing environment
provided by earlier versions of VMS was asymmetric in nature. Because
only the primary processor could execute kernel-mode code, kernelmode code, including device drivers, effectively ran in a uniprocessing
environment and did not need to undertake any special actions due to the
multiprocessing nature of the system.
However, in the new symmetric multiprocessing environment supported
by VMS beginning at Version 5.0, all processors in the system can execute
kernel-mode code. Consequently, privileged code must take steps to ensure
that its execution and use of memory are synchronized with kernel-mode
code that may be executing concurrently on another processor. Such
code must maintain two dimensions of synchronization: raising to the
appropriate IPL for a certain transaction, while securing the proper spin
lock for the object of that transaction.
For privileged code executing within a VMS uniprocessing environment,
VMS now transparently forgoes the second of these requirements. That
is, on a VAX uniprocessor, or in a VMS multiprocessor system wherein
multiprocessing is not enabled, privileged code may securely execute by
adhering to the IPL synchronization method alone.
To support both uniprocessor and multiprocessor environments in the
most efficient and secure way possible, VMS now incorporates special logic
in the System Generation Utility (SYSGEN), the device driver loading
mechanism, and several synchronization macros. This code enables VMS
to discern the environment in which it is executing and, most importantly,
to take steps to prohibit a privileged code thread from executing without
prope;r synchronization in a multiprocessing environment.
As discussed in Section E.3, non-Digital-supplied device drivers written
prior to VMS Version 5.0 must be altered to execute correctly in a VMS
symmetric multiprocessing environment. The modifications discussed in
Section E.3 are not required for a device driver that will be loaded and
executed only on a VMS uniprocessor system. However, the same macros,
E-1

Multiprocessing Requirements on Kernel-Mode Code
E.1 Uniprocessor and Multiprocessor Device Drivers

routines, and field names used in a multiprocessing environment are
accepted by VMS in a uniprocessing environment. Furthermore, the spin
lock synchronization macros and routines are specially designed to execute
a streamlined code that obtains IPL synchronization alone in such an
environment. Digital recommends that any driver that may execute in a
multiprocessing environment be updated accordingly.
The remainder of this section identifies the activities of the
MULTIPROCESSING system parameter, VMS driver loading mechanisms,
and the VMS synchronization macros in creating a multiprocessing or
uniprocessing environment and enforcing the appropriate synchronization.

E.1.1

MULTIPROCESSING System Parameter
Every VMS system is initially booted as a single processor, regardless
of its hardware configuration. The setting of the MULTIPROCESSING
system parameter for the first processor in the system to boot (called the
primary processor in a multiprocessing environment) determines which
synchronization image the secondary bootstrap program (SYSBOOT) loads
into memory as part of the operating system. Table E-1 describes the
contents of the three possible synchronization images.
Table E-1

E-2

VMS Synchronization Images

Image

Results

Uniprocessing

Synchronization is accomplished by elevating IPL. Spin lock
acquisition routines only achieve IPL synchronization.

Full-checking

Synchronization is accomplished by both elevating IPL and
obtaining an appropriate spin lock. Spin lock acquisition
routines perform both of these tasks. Spin lock acquisition
routines also perform spin lock rank checking and verify the
spin lock synchronization IPL, issuing appropriate bugchecks
if they discover violations of synchronization rules. Spin
lock acquisition routines maintain various debugging aids
and performance analysis aids (such as the longwords in
the spin lock data structure containing the PCs of the most
recent acquisitions and releases of the spin lock and the
set of counters in the per-CPU database structure (CPU)).
(See Section E.3.7 for additional description of full-checking
synchronization.)

Streamlined

Synchronization is accomplished by both elevating IPL and
obtaining an appropriate spin lock. Spin lock acquisition
routines do not perform checking and do not record the PCs
of the spin lock acquisitions and releases.

Multiprocessing Requirements on Kernel-Mode Code
E.1 Uniprocessor and Multiprocessor Device Drivers

Table E-2 lists the possible settings of the MULTIPROCESSING system
parameter.
Table E-2

Settings of MULTIPROCESSING System Parameter

Value

Result

Loads uniprocessing synchronization image for any hardware configuration
Loads full-checking synchronization image and sets multiprocessing-enabled
bit (SMP$V_ENABLED in SMP$GL_FLAGS) if the hardware configuration
is capable of multiprocessing and two or more processors are available;
otherwise, loads uniprocessing synchronization image.

E.1.2

Loads full-checking synchronization image and sets multiprocessing-enabled
bit regardless of the hardware configuration.

Device Driver Loading
In a VMS multiprocessing environment, the presence of a device driver
that does not adhere to multiprocessing synchronization conventions
introduced at VMS Version 5.0 can be fatal to proper system functions.
Now, VMS takes steps to either prohibit the enabling of multiprocessing
in a VAX system that has such a driver present or prevent the loading of
such a driver if multiprocessing has already been enabled.
To accomplish this, the VMS driver-loading routine assumes that any
driver that can run in a VMS multiprocessing environment uses the spin
lock synchronization macros and loads the appropriate I/O database fields.
(See Section E.3 for information on how to produce a driver that can
execute in a VMS multiprocessing environment.) Use of the spin lock
synchronization macros causes VMS to set the SMP-modified bit in the
DPT (DPT$V_SMPMOD in DPT$L_FLAGS).
If multiprocessing has not been enabled on the system, the driver loading
mechanism checks the SMP-modified bit in the DPT and takes either of
the following actions:
•

If the SMP-modified bit is set, the driver loading mechanism loads
the driver and calls its controller and unit initialization routines, as
discussed in Chapter 12.

•

If the SMP-modified bit is not set, the driver loading mechanism sets
the unmodified-driver bit (SMP$V_UNMOD_DRIVER) in SMP$GL_
FLAGS, thus prohibiting the subsequent enabling of multiprocessing
on the system. It then loads the driver and calls its controller and unit
initialization routines, as described in Chapter 12. If such a driver has
been successfully loaded into a VMS system, you cannot subsequently
enable multiprocessing.

E-3

Multiprocessing Requirements on Kernel-Mode Code
E.1 Uniprocessor and Multiprocessor Device Drivers

If multiprocessing is currently enabled on the system, the driver loading
mechanism checks the SMP-modified bit in the DPT and takes either of
the following actions:

E.1.3

•

If the SMP-modified bit is set, the driver loading mechanism loads
the driver and calls its controller and unit initialization routines, as
discussed in Chapter 12.

•

If the SMP-modified bit is not set, the driver loading mechanism does
not load the driver, returning the error status SS$_NONSMPDRV to
its caller.

VMS Synchronization Macros
To support the spin lock synchronization required in VMS multiprocessor
systems, VMS Version 5.0 added the DEVICELOCK/DEVICEUNLOCK,
FORKLOCK/FORKUNLOCK, and LOCK/UNLOCK macros to the existing
SETIPL and DSBINT/ENBINT macros. As discussed in Section E.3, the
SETIPL and DSBINT/ENBINT macros must not be used to synchronize
systemwide activities in a VMS multiprocessing environment. However,
the DEVICELOCK/DEVICEUNLOCK, FORKLOCK/FORKUNLOCK, and
LOCK/UNLOCK macros are designed to operate appropriately in either a
multiprocessing or uniprocessing environment. According to the value of
the multiprocessing-enabled bit (SMP$V_ENABLED) in SMP$GL_FLAGS,
the run-time code produced by these macros behaves as follows:
•

If multiprocessing has not been enabled in the system, these macros
only raise or lower IPL to the IPL required to synchronize access to
the specified system resource.

•

If multiprocessing has been enabled in the system, these macros call
the appropriate spin lock synchronization routine, which acquires or
releases the spin lock corresponding to the system resource, raising or
lowering IPL as required.

The setting of the MULTIPROCESSING system parameter controls
the disposition of the multiprocessing-enabled bit, as discussed in
Section E.1.1. The macro chapter in the VMS Device Support Reference
Manual describes the VMS synchronization macros in full.

E.2

Changes Required to Drivers Written Before VMS Version 5.0
Most changes introduced at VMS Version 5.0 are transparent to
non-Digital-supplied drivers written prior to that release and can
be accommodated in the driver image by simply reassembling and
relinking the driver. However, there are several required-and some
recommended-changes that the writers and maintainers of these drivers
should make before attempting these tasks. This section describes these
modifications.
In addition, if a non-Digital-supplied driver is to be loaded and run in a
VMS symmetric multiprocessing system, it is critical that it be adapted
according to the guidelines discussed in Section E.3. Failure to adapt such
drivers to use multiprocessing synchronization mechanisms may result in

E-4

Multiprocessing Requirements on Kernel-Mode Code
E.2 Changes Required to Drivers Written Before VMS Version 5.0

either a failure to load the driver or the inability to enable multiprocessing
on the system.

E.2.1

Address of the Driver's Interrupt Service Routine in the DPT
In order to provide an optional method of servicing MicroVAX Q22 bus
device interrupts at the IPLs at which they are requested, VMS now
defines several new symbolic offsets in the interrupt dispatch vector (VEC)
portion of the channel request block (CRB).
One of these symbolic offsets is significant to all device drivers. Prior
to VMS Version 5.0, device drivers initialized the location in the vector
containing the address of the driver's interrupt service routine by referring
explicitly to its location (CRB$L_INTD+4). Digital now recommends that
all device drivers refer to this location using the symbolic offset CRB$L_
INTD+VEC$L_ISR, as follows:
Old:

DPT_STORE CRB,CRB$L_INTD+4,D,LP$1NT_SERV_RTN

New:

DPT_STORE CRB,CRB$L_INTD+VEC$L_ISR,D,LP$1NT_SERV_RTN

To use the new symbols, you must include the $CRBDEF and $VECDEF
structure definition macros in the driver. All structure definition macros
can be found in SYS$LIBRARY:LIB.MLB.

E.2.2

Checking, Debiting, and Crediting a Process's Byte Count Quota
Now the routines EXE$BUFFRQUOTA and EXE$BUFQUOPRC are
replaced with a set of eight new routines that manipulate a job's byte
count quota and byte limit, optionally allocating a nonpaged pool buffer
of the requested size. To ensure proper synchronization, programs should
use these routines and avoid any direct manipulation of the nonpaged pool
quota fields JIB$L_BYTCNT and JIB$L_BYTLM).
Among the new routines are the following:
Routine

Function

EXE$CREDIT_BYTCNT

Returns credit to a job's byte count quota

EXE$CREDIT_BYTCNT_BYTLM

Returns credit to a job's byte count quota
and by~e count limit

EXE$DEBIT_BYTCNT

Determines whether a job's buffered byte
count quota usage permits the process to
be granted additional buffered 1/0 and, if
so, adjusts the job's byte count quota

EXE$DEBIT_BYTCNT_NW

Same function as EXE$DEBIT_BYTCNT,
but never places a process in a resource
wait state pending the return of sufficient
quota

E-5

Multiprocessing Requirements on Kernel-Mode Code
E.2 Changes Required to Drivers Written Before VMS Version 5.0

Routine

Function

EXE$DEBIT_BYTCNT_BYTLM

Determines whether a job's buffered byte
count quota usage permits the process to
be granted additional buffered 1/0 and, if
so, adjusts the job's byte count quota and
byte count limit

EXE$DEBIT_BYTCNT_BYTLM_NW

Same function as EXE$DEBIT_BYTCNT_
BYTLM, but never places a process in a
resource wait state pending sufficient quota

EXE$DEBIT_BYTCNT_ALO

Same functi9n as EXE$DEBIT_BYTCNT,
but, if quota checks succeed, allocates the
requested amount of pool

EXE$DEBIT_BYTCNT_BYTLM_ALO

Same function as EXE$DEBIT_BYTCNT_
BYTLM, but, if quota checks succeed,
allocates the requested amount of pool

Many drivers written prior to VMS Version 5.0 contain code sequences
similar to the following:
JSB

GAEXE$BUFFRQUOTA

BLBC
JSB
BLBC
MOVL

RO,ERROR
GAEXE$ALLOCBUF
RO,ERROR
PCB$L_JIB(R4),R5

SUBL2

Rl,JIB$L_BYTCNT(R5)

;Would buffer allocation
;exceed byte count quota?
;Branch if yes
;If not, allocate buffer
;Branch if error
;Obtain job information
;block
;Decrement job's byte count
;quota

The new routines allow you to simplify such code sequences. For instance,
a single routine, EXE$DEBIT_BYTCNT_ALO, checks and debits quotas
and allocates pool. When there is not enough quota available to service
the request, the routine restores the deducted amount and returns the
error SS$_EXQUOTA IN RO.
The preceding code example can be rewritten as follows:

E.2.3

JSB

GAEXE$DEBIT_BYTCNT_ALO

BLBC

RO,ERROR

;Check for quota violation,
;allocate buffer, decrement
;JIB byte count quota
;Branch if error

Referring to the Current PCB
The symbol SCH$GL_CURPCB is obsolete and should be replaced as
follows:
•

If the process's Pl space is available, use the Pl space location

CTL$GL_PCB.

E-6

Multiprocessing Requirements on Kernel-Mode Code
E.2 Changes Required to Drivers Written Before VMS Version 5.0

•

If the process's Pl space is not available, use the FIND_CPU_DATA
macro, as follows:
FIND CPU DATA RO
MOVLCPU$L_CURPCB(RO),Rl

The FIND_CPU_DATA macro obtains the virtual address of the perCPU database for the processor on which it executes. Code that issues
the FIND_CPU_DATA macro must adhere to the following rules:
It must be executing in kernel mode above IPL 2 when it invokes

the FIND_CPU_DATA macro.
It must take care to prevent rescheduling after issuing the macro

as long as the information returned by FIND_CPU_DATA is in use.
It typically does this by remaining at an IPL greater than 2.

E.2.4

Allocating System Page-Table Entries
The system routine LDR$ALLOC_PT replaces IOC$ALLOSPT (since
Version 5.0) as the appropriate method for non-Digital-supplied VAXBI
device drivers to map a portion of a device's node space to system virtual
address space. See the routines chapter in the VMS Device Support
Reference Manual for a full description of LDR$ALLOC_PT.

E.2.5

Referring to a System Process Mailbox
An existing driver that refers to either the job controller's mailbox or
OPCOM's mailbox must be altered to use the new symbolic names that
point to these mailboxes. Usually, it is the driver's interrupt service
routine or timeout handling routine that loads the address of the mailbox
UCB into R3 and calls the system routine EXE$SNDEVMSG, as follows.
MOVL

GASYS$AR_JOBCTLMB,R3

JSB

GAEXE$SNDEVMSG

;Set address of job controller
;mailbox
;Sent message to job con;troller

The new symbolic names actually refer to global pointers to the mailbox
UCB structures. They include the following:

E.2.6

Since VMS V5.0

Prior to V5.0

Name

SYS$AR_JOBCTLMB

SYS$GL_JOBCTLMB

Job controller's mailbox

SYS$AR_OPRMBX

SYS$GL_OPRMBX

OPCOM's mailbox

Reassembling and Relinking the Driver
Because of changes in the definitions of data structures, the behavior of
system macros, the location of global symbols, and the contents of system
images, it is necessary to reassemble and relink non-Digital-supplied
drivers regardless of whether their contents have been modified.

E-7

Multiprocessing Requirements on Kernel-Mode Code
E.2 Changes Required to Drivers Written Before VMS Version 5.0

To do so, reassemble your driver against SYS$LIBRARY:LIB.MLB. For
example:
$ MACRO MYDRIVER.MAR+SYS$LIBRARY:LIB.MLB/LIBRARY

Relink your driver against the VMS global symbol table. If the driver
consists of several source files, you must specify the file that contains the
driver prologue table as the first file in the list. The linker options file
must contain the statement BASE=O. For example:
$ CREATE MYDRIVER.OPT
BASE=O
jctrl/zl
$ LINK/NOTRACE MYDRIVER1[,MYDRIVER2, ... ],MYDRIVER.OPT/OPTIONS,SYS$SYSTEM:SYS.STB/SELECTIVE_SEARCH

The linker will report that the image has no transfer address. You may
ignore this message.
Once you have linked or relinked a driver, you should copy its image
to the SYS$LOADABLE_IMAGES or SYS$SYSTEM directory. The
SYSGEN LOAD and CONNECT commands first search for a driver in
the SYS$LOADABLE_IMAGES directory. If they do not find the driver,
they then search the SYS$SYSTEM directory.

E.3

Adapting Device Drivers to Run on a VMS Multiprocessing System
VMS now contains several new routines that enforce synchronization in a
symmetric multiprocessing (SMP) environment. Drivers do not generally
call these routines explicitly, but rather invoke VMS-supplied macros that
synchronize as appropriate to the processing environment. There are
only a few instances in which existing non-Digital-supplied drivers must
change to conform to the new synchronization mechanisms. This section
outlines those instances; Chapter 3 describes synchronization rules in
greater detail.

E.3.1

Specifying the Fork Lock Index
To adapt a driver to execute properly in a VMS multiprocessor
environment, you must replace all instances of UCB$B_FIPL (or FKB$B_
FIPL) with UCB$B_FLCK (or FKB$B_FLCK). In addition, you must
replace thP. invocation of the DPT_STORE macro that defined the driver's
fork IPL with one that defines the driver's fork lock index, as follows:
Old:

DPT_STORE UCB,UCB$8_FIPL,8,8

New:

DPT_STORE UCB,UCB$B_FLCK,8,SPL$C_IOLOCK8

To use the new symbol, include the $UCBDEF structure definition macro
in the driver. Fork lock (and other spin lock) indexes, such as SPL$C_
IOLOCK8, are defined by the $SPLCODDEF definition macro as invoked
by DPTAB. Replace fork IPLs with the corresponding fork lock index
according to the following list:

E-8

Multiprocessing Requirements on Kernel-Mode Code
E.3 Adapting Device Drivers to Run on a VMS Multiprocessing System

IPL

Fork Lock Index

SPL$C_IOLOCK8

SPL$C_IOLOCK9

SPL$C_IOLOCK10

SPL$C_IOLOCK11

All structure definition macros can be found in SYS$LIBRARY:LIB.MLB.
Drivers rarely need to obtain a fork lock explicitly. VMS places the
driver fork process into execution (originally by EXE$INSIOQ and, by
implication, by IOC$REQCOM) at fork IPL holding the appropriate fork
lock. In addition, the fork dispatcher obtains the fork lock associated
with the driver fork process before it restores its context and resumes its
execution.
Note that, if a driver fork process is not placed into execution according to
one of these means, it must obtain the fork lock itself. (See the discussion
in Section E.3.6.2.)

E.3.2

Synchronizing Access to the Device Database with the Interrupt
Service Routine
The device database consists of device and adapter registers, plus driverspecific UCB fields that record the status of a device. As these locations
are primarily accessed by the driver's interrupt service routine, the driver
fork process must take special care to synchronize with the interrupt
service routine whenever it accesses them.
E.3.2.1

Synchronizing at Device IPL
VMS prior to Version 5.0 used the DSBINT macro to synchronize with the
interrupt service routine at device IPL (UCB$B_DIPL), as follows:
DSBINT UCB$B_DIPL(R5)

;Raise IPL to device IPL
;Save current IPL on stack

;Access device data

ENBINT

;Restore saved IPL

To run correctly, this code should be modified so that it obtains the
appropriate device lock, as follows:
DEVICELOCK LOCKADDR=UCB$L_DLCK(R5),SAVIPL=-(SP)
;Access device data

DEVICEUNLOCK LOCKADDR=UCB$L_DLCK(R5),NEWIPL=(SP)+

;Secure device lock
; (also raises IPL to device
; IPL)
;Save current IPL on stack

;Release device lock
;Restore old IPL from stack

E-9

Multiprocessing Requirements on Kernel-Mode Code
E.3 Adapting Device Drivers to Run on a VMS Multiprocessing System

E.3.2.2

Raising IPL to IPL$_POWER
If the device driver start-110 routine (or fork process) raises IPL to IPL 31

(IPL$_POWER) to check for the occurrence of a power failure and to access
device registers, it must ensure that it has explicitly synchronized with
the device's database at device IPL. This means that the routine must first
obtain the appropriate device lock, using the DEVICELOCK macro.
Because versions of VMS prior to Version 5.0 allowed only one processor,
even in a VAX multiprocessor system, to execute kernel-mode code,
the following code in a driver's start-110 routine provided adequate
synchronization:
DSBINT
#UCB$V POWER,UCB$W STS(R5),30$
;Service power-failure

;Raise IPL to 31
;Save current IPL on stack

BBC

;If clear, no power failure

;Branch
30$: ;Start device

WFIKPCH

To run correctly, the preceding code should be replaced with the following:
DEVICELOCK LOCKADDR=UCB$L_DLCK(R5),SAVIPL=-(SP)
SETIPL #IPL$_POWER,ENVIRON=UNIPROCESSOR
BBC
#UCB$V POWER, UCB$W_STS(R5),30$
;Service power failure

DEVICEUNLOCK LOCKADDR=UCB$L_DLCK(R5),NEWIPL=(SP)+

;Secure device lock
; (also raises IPL to
; device IPL)
;Save current IPL on stack
;Raise IPL to 31
;Avoid assembly-time warning
;If clear, no power failure

;Release device lock
;Restore old IPL from stack

;Branch
30$: ;Start device

WFIKPCH

;Wait for interrupt

Here, the DEVICELOCK macro achieves synchronized systemwide access
to the device registers. The SETIPL macro then synchronizes the local
processor against its own powerfail interrupt event. The code does not
need to synchronize systemwide against powerfail events, because its
interest is truly limited to the local processor.

E-10

Multiprocessing Requirements on Kernel-Mode Code
E.3 Adapting Device Drivers to Run on a VMS Multiprocessing System

Note that the WFIKPCH macro releases the last acquisition of the device
lock by the executing processor, restoring the old IPL prior to returning
control to the caller's caller.
Refer to Chapters 3 and 8 for additional information on the
synchronization rules imposed on a driver's start-1/0 routine.
E.3.2.3

Synchronization Within the Interrupt Service Routine

As soon as it obtains the device unit's UCB in R5, the driver's interrupt
service routine must issue the DEVICELOCK macro to synchronize with
other code threads (such as the start-1/0 routine and the timeout handling
routine) that may access the device database at device IPL holding
the device lock. Because the interrupt service routine is automatically
called at device IPL, the DEVICELOCK macro invocation should specify
condition=NOSETIPL. To save time, the macro should also specify
preserve=NO so that code to preserve RO is not executed.
For example:
DEVICELOCK LOCKADDR=UCB$L_DLCK(R5),CONDITION=NOSETIPL,PRESERVE=NO

;Obtain device lock
;Do not bother to set IPL
;Do not save RO

Similarly, the interrupt service routine should release the device lock
when it no longer needs to access the device database. Generally, this is
immediately after the routine regains control from the driver fork process
and before it restores the saved registers and issues an REI instruction, as
follows:
DEVICEUNLOCK LOCKADDR=UCB$L_DLCK(R5),PRESERVE=NO
POPR
#AM<RO,Rl,R2,R3,R4,R5>
REI

;Release device lock
;Do not save RO
;Restore registers
;Exit from interrupt

Refer to Chapters 3 and 9 for additional information on the
synchronization rules imposed on a driver's interrupt service routine.

E.3.3

Controller and Unit Initialization Routines
As discussed in Section 11.1, a device driver's controller and unit
initialization routines are called during driver loading and reloading
and during system recovery from a power failure.

In a VMS symmetrical multiprocessing environment, any logic in a driver's
controller initialization routine or unit initialization routine that takes
special action to service a power failure must adhere to the following rules:
•

It cannot acquire any spin locks. Controller and unit initialization
routines are called at IPL 31 during power failure recovery to
reinitialize 1/0 devices before the processors are allowed to proceed
with execution at lower IPLs. Because processors may have been
holding spin locks at the time of the power failure, they will not be able
to release them until after they resume execution. As a result, spin
locks are not available to controller and unit initialization routines.
E-11

Multiprocessing Requirements on Kernel-Mode Code
E.3 Adapting Device Drivers to Run on a VMS Multiprocessing System

•
E.3.3.1

It cannot perform any operation that requires the intervention of other
processors in the system.

Permanently Allocating Map Registers and Buffered Data Paths

Because the map registers and buffered data paths of a UNIBUS adapter
are shared by the devices residing on the bus, they are synchronized at
a single fork IPL and, in a VMS multiprocessing system, by a single fork
lock.
Prior to VMS Version 5.0, a unit initialization routine that permanently
allocated map registers or a buffered data path could do so at IPL$_
POWER (its calling IPL). Now, however, the map register and data
path allocation routines require that the appropriate fork lock be held
at the time of their calling. As a result, a unit initialization routine
that permanently allocates these resources must fork before calling the
allocation routine. The VMS fork dispatcher ensures that, when execution
of the routine resumes, it is executing at fork IPL holding the fork lock.
The consequences of forking in a unit initialization routine are discussed
at length in Section 11.1.5. Refer to Sections 14.2.2.2 and 14.2.1.2 for
additional information on permanently allocating map registers and
buffered data paths, respectively.

E.3.4

Timeout Handling Routine
In a VMS multiprocessing environment, the software timeout interrupt
service routine calls a driver's timeout handling routine at device IPL,
holding both the appropriate fork lock and device lock.
Previous editions of this manual have suggested that a timeout handling
routine can explicitly lower its IPL from device IPL to fork IPL using a
SETIPL instruction. This action assumed that the thread of code that
resulted in the call to the routine originated in a software interrupt
granted at IPL 7 (IPL$_TIMERFORK).
In a VMS multiprocessing system, such a forced lowering of IPL would
break synchronization. In addition, similar assumptions about the origin
of the calling code thread cannot be guaranteed. Instead, those timeout
handling routines that must lower IPL should issue the IOFORK macro to
fork.
See Section 10.2 for additional information on the timeout handling
routine.

E.3.5

General Methods for Synchronizing Kernel-Mode Code
In addition to the changes in the driver routines explicitly discussed
in Sections E.3.2 and E.3.3, there may be other alterations required
in device drivers and other kernel-mode code before they can execute
successfully in a VMS symmetric multiprocessing environment. This
section provides some general discussion of these changes. You can find
additional information on multiprocessing synchronization in Chapter 3.

E-12

Multiprocessing Requirements on Kernel-Mode Code
E.3 Adapting Device Drivers to Run on a VMS Multiprocessing System

E.3.5.1

Using the Spin Lock Synchronization Macros

You must adapt most kernel-mode code that raises or lowers IPL so
that it obtains appropriate synchronization in a VMS multiprocessing
environment. Determine these locations by searching for instances of
the system macros SETIPL, ENBINT, and DSBINT or for an instruction
such as MTPR x, PR$_IPL (where xis an IPL value). Do not change
those instances of the SETIPL and DSBINT macros intended to achieve
synchronization only on the local processor. After careful inspection
proves that the macro in question is intended to achieve local processor
synchronization only, add the argument environ=UNIPROCESSOR to
their invocations.
You should replace most instances of these macros with a LOCK,
UNLOCK, FORKLOCK, FORKUNLOCK, DEVICELOCK, or
DEVICEUNLOCK macro, as shown in Table E-3. You can substitute
the appropriate usage of any of these macros wherever Table E-3 lists the
LOCK and UNLOCK macros. The formats of the spin Iock synchronization
macros are fully described in VMS Device Support Reference Manual.
Table 3-3 lists the system spin locks.
Table E-3

Converting IPL Synchronization to Spin Lock Synchronization

Existing Macro

Function

New Macro

Function

SETIPL ipl (where ipl is
greater than 2)

Raise IPL

LOCK lockname,
lockipl

Raise IPL, acquire spin lock

SETIPL ipl (where ipl is
greater than 2)

Lower IPL from an IPL
greater than 2

UNLOCK

Release spin lock, lower IPL

SETIPL ipl (where ipl is
less than 3)

Lower IPL from an IPL
less than 3

SETIPL ipl

Lower IPL

DSBINT ipl

Save current IPL and
raise to specified IPL

LOCK lockname,
lockipl, savipl

Save current IPL, raise IPL,
acquire spin lock

ENBINT

Lower IPL and restore
saved IPL

UNLOCK

Release spin lock, lower IPL

lockname, lockipl

E.3.5.2

lockname, lockipl

Interlocking Access to Data Cells and Queues

VMS now assigns spin lock protection to system resources as described
in Table 3-3. The system time and timer queue are managed under the
TIMER and HWCLK spin locks, as detailed in Section 3.1.3.
In a VMS multiprocessing environment, any thread of code that
manipulates bit fields at different IPLs without spin lock protection must
do so with interlocked instructions (for example, BBCCI and BBSSl). 1
Instances of the INSQUE and REMQUE instructions may need to be
changed to use the INSQTI and REMQHI instructions, respectively, if
they are issued to manipulate a queue at multiple IPLs. Certain cells,
such as PCB$W_ASTCNT, must be incremented and decremented using
an ADAWI instruction. INCx and DECx instructions are not interlocked in
a VMS multiprocessing system.
1

It is illegal to intermix interlocked and noninterlocked instructions that refer to the same bit: for instance
BBCC and BBCCI. Should any noninterlocked instruction refer to the same bit, the bit is not interlocked.
E-13

Multiprocessing Requirements on Kernel-Mode Code
E.3 Adapting Device Drivers to Run on a VMS Multiprocessing System

Spin locks explicitly protect various system queues and lists. For
example, the AST queue in the process control block (PCB$L_ASTQFL) is
synchronized by the SCHED spin lock and the variable region of nonpaged
pool is protected by the POOL spin lock.
A fork lock implicitly protects the following adapter resource wait queues
(at the specified listheads) at fork IPL, as long as the drivers for all devices
on the adapter that require the resources use the same fork lock.
Listhead
Since VMS V5.0

Prior to V5.0

Name

UCB$L_IOOFL

Same

Pending-1/0 queue

ADP$L_DPOFL

Same

UNIBUS buffered data path wait queue

ADP$L_MROFL

Same

UNIBUS/022 bus map register wait queue

ADP$L_MR20FL

Same

022 bus alternate map register wait queue

Because a single spin lock cannot control access to list items that must be
accessed by code threads executing at different IPLs, VMS now provides
either a processor-specific queue or a self-relative queue for such items.
The following queues (at the specified listheads) are now, processor-specific
queues whose forward and backward links are contained in the per-CPU
database (described in the VMS Device Support Reference Manual data
structures).
Listhead
Since VMS V5.0

Prior to V5.0

Name

CPU$0_SWIOFL

SW1$GL_FOFL

Software interrupt queue listhead

IOC$GO_POSTIO

IOC$GL_PSFL

1/0 postprocessing queue

The following queues are now self-relative queues whose forward and
backward links are contained in the data area of the system loadable
image SYSTEM_PRIMITIVES.EXE. 2 All system macros and routines that
access these queues have been converted to access them with the INSQTI
and REMQHI interlocked instructions.
Listhead

Since VMS V5.0

Prior to V5.0

Name

IOC$GO_SRPIO

IOC$GL_SRPFL

Nonpaged pool SRP lookaside list

IOC$GO_LRPIO

IOC$GL_LRPFL

Nonpaged pool LRP lookaside list

IOC$GO_IRPIO

IOC$GL_IRPFL

Nonpaged pool IRP lookaside list

System cell EXE$AR_SYSTEM_PRIMITIVES contains the address of this image; the macro $$SYSTEM_
PRIM_DATADEF in SYS$SYSTEM:LIB.MLB defines offsets into its data area.

E-14

Multiprocessing Requirements on Kernel-Mode Code
E.3 Adapting Device Drivers to Run on a VMS Multiprocessing System

E.3.6

Miscellaneous Conversion Tasks
This section describes those activities performed by some kernel-mode code
threads that should be examined in the course of converting them to run
in a VMS multiprocessing environment.
E.3.6.1

Reading the System Time

As discussed in Section 3.1.3, because EXE$GQ_SYSTIME can only
be changed or compared with multiple instructions, any code thread
in a multiprocessing system that must obtain a consistent copy of the
quadword must first acquire proper synchronization.
VMS now supplies the READ_SYSTIME macro to simplify this procedure.
It has the following format, where dst is the quadword destination where
the macro returns the system time:
READ_SYSTIME dst

Use of the READ_SYSTIME macro is subject to the following restrictions:

E.3.6.2

•

IPL must be less than 23.

•

The processor must be executing in kernel mode.

•

When using the macro within pageable program sections executing at
IPL 2 and below, you must ensure that the pages involved are locked
in memory.

Calling the Driver Fork Process from a TQE

Whenever VMS places a driver fork process into execution, it ensures that
it is synchronized with other processes at that fork level. In other words,
if it is generated by the conclusion of I/O preprocessing (EXE$INSIOQ),
the completion of a previous I/O request on a device unit (IOC$REQCOM),
or the operation of the fork dispatcher, the driver fork process is placed
into execution at the correct fork IPL, holding the corresponding fork lock.
As an example, consider a driver fork process activated by a timer wakeup
associated with a timer queue element (TQE) previously queued by the
driver. The software timer interrupt service routine does raise IPL to IPL
8 (IPL$_SYNCH) and obtain certain spin locks prior to dequeuing the TQE
and placing it into execution, but it does not obtain the driver's fork lock.
Thus, even though the driver's fork IPL may be IPL$_SYNCH, the driver
will not be properly synchronized at fork level unless it first obtains the
appropriate fork lock.
E.3.6.3

Invalidating Translation Buffer Entries

Prior to VMS Version 5.0, privileged code that changed a valid page-table
entry (PTE) could flush the stale PTE from the processor's translation
buffer by using the INVALID macro or writing directly to the Translation
Buffer Invalidate Single (TBIS) processor register. Similarly, it could
invalidate the entire translation buffer by using the INVALID macro or
writing to the Translation Buffer Invalidate All (TBIA) processor register.

E-15

Multiprocessing Requirements on Kernel-Mode Code
E.3 Adapting Device Drivers to Run on a VMS Multiprocessing System

In a VMS symmetric multiprocessing environment, processors must not
use previously buffered PTE contents while another processor is changing
that PTE. Once the PTE has been changed, other processors must flush
the stale translation buffer entry for the PTE. To accomplish this, VMS
has replaced the INVALID macro with the INVALIDATE_TB macro.
The INVALIDATE_TB macro flushes a single PTE or all PTEs from
the processor translation buffers in either a VAX uniprocessor or
multiprocessor system. In updating privileged code written prior to VMS
Version 5.0, you must replace any instances of an INVALID macro or of an
MTPR instruction to PR$_TBIS or PR$_TBIA with a suitable invocation of
the INVALIDATE_TB macro.
The VMS Device Support Reference Manual contains a description of the
INVALIDATE_TB macro.
E.3.6.4

Unsupported Use of the IRP

The VMS multiprocessing code employs a portion of the IRP (the 24 bytes
following IRP$L_KEYDESC), previously used only as a fork block by the
VMS disk and tape class drivers, to effect the transfer of an I/O request
from a processqr with no access to the device to another processor that
does have access.
A driver that uses this portion of the IRP to store data can lose this data
when the VMS I/O initiation routine (IOC$INITIATE) attempts to transfer
the request to the driver's start-I/0 routine. VMS I/O initiation occurs
when an FDT routine calls EXE$QIODRVPKT or when the driver issues
the REQCOM macro to complete the current I/O request.
E.3.6.5

Poor Man's Lockdown

Certain privileged code, written prior to VMS Version 5.0, utilizes a
technique, commonly known as "poor man's lockdown," whereby one or two
pages of code are locked into a process or system working set as a side
effect of elevating IPL. Such code has one of the following forms:
ASSUME
SET IPL

10$-. LE 511
10$

; Check for contiguity of pages

;Code to be locked into memory

RSB

10$:

. LONG

IPL$xxxx

The effect of this coding technique is that, because the system must
determine the value of the argument to the SETIPL macro from location
10$, it must fault into memory the page in which 10$ resides. As a result,
before the code actually elevates IPL, the pages in which the SETIPL
macro and 10$ reside will become memory-resident. In this way, the code
can avoid a page fault while executing the code between the SETIPL and
10$ at elevated IPL. The ASSUME macro guarantees that the pages to be
faulted are contiguous.

E-16

Multiprocessing Requirements on Kernel-Mode Code
E.3 Adapting Device Drivers to Run on a VMS Multiprocessing System

This technique has several limitations:·
•

It cannot lock more than two virtually contiguous pages.

•

Beginning with VMS Version 5.0, it is only useful in locking process
pages, not system pages. In a VMS multiprocessing system, a page in
the system working set could be faulted in by one processor, only to be
removed from the system working set by another processor.
To lock system pages, you must use the LOCK_SYSTEM_PAGES and
UNLOCK_SYSTEM_PAGES macros as described in the VMS Device
Support Reference Manual. (Note that you cannot use these macros to
lock per-process pages in memory.)

•

Prior to VMS Version 5.0, IPLs were the means by which system tasks
were prioritized and access to system data was synchronized. Code
executing at an elevated IPL would effectively block other code in
the system from executing at or below that IPL. Now with symmetric
multiprocessing, merely raising IPL does not synchronize systemwide
activity nor enforce orderly access to data.
Sometimes it may only be necessary to block tasks or synchronize
activity on the local processor. In these instances, raising IPL provides
sufficient synchronization and "poor man's lockdown" behaves as
it did before VMS Version 5.0. For instance, use of "poor man's
lockdown" to lock a code segment executing at IPL$_RESCHED
effectively prevents process deletion and rescheduling while the code
executes at a nonpageable IPL. However, if a locked code segment
must access system data structures at an elevated IPL-for instance,
at IPL$_SYNCH-it must obtain the spin lock associated with the
database by using one of the spin lock synchronization macros (LOCK,
FORKLOCK, or DEVICELOCK). After accessing the data, it must
release the acquired spin lock by invoking UNLOCK, FORK.UNLOCK,
or DEVICEUNLOCK.

E.3.7

Troubleshooting a Device Driver in a Multiprocessing System
If the full-checking synchronization image has been loaded into memory,
the spin lock acquisition and releasing routines perform certain activities
that aid in the debugging and tuning of a VMS multiprocessing system.
These activities include the following:

•

Enforcement of the spin lock ranking and IPL requirements. The
means by. which the multiprocessing synchronization routines
accomplish this are discussed in Section E.3.7.1.

•

Recording, for each spin lock, the last eight PCs that acquired or
released the spin lock. These PCs are located at offset SPL$L_OWN_
PC_VEC in the spin lock data structure (SPL). You can use the SDA
command SHOW SPINLOCKS/FULL to display the contents of the PC
list.

•

Tallying, for each spin lock, the number of successful acquisitions and
the number of failed acquisitions in SPL$Q_ACQ_COUNT and SPL$L_
BUSY_WAITS, respectively.

E-17

Multiprocessing Requirements on Kernel-Mode Code
E.3 Adapting Device Drivers to Run on a VMS Multiprocessing System

Section E.1.1 explains the settings of the MULTIPROCESSING system
parameter that produce the full-checking synchronization environment.
The full-checking synchronization environment contains a mechanism
for producing bugcheck messages that describe the detection of serious
synchronization problems in the system. In most instances, these problems
are caused by a non-Digital-supplied device driver that does not adhere to
multiprocessing synchronization rules.
This section describes the bugchecks that are possible in a VMS fullchecking synchronization environment and the SDA commands that aid in
the investigation of a multiprocessing system failure. It concludes with a
brief description of changes to the XDELTA debugger since VMS Version

5.0.
E.3.7.1

Multiprocessing Bugchecks

In order to obtain a spin lock or fork lock, a processor must be executing
at an IPL no higher than the lock's synchronization IPL (SPL$B_IPL).
Additionally, the processor cannot obtain a spin lock or fork lock if the
lock's rank (SPL$B_RANK) is lower than that of any locks the processor
currently holds. To release a spin lock, a processor must be executing
at or above the IPL at which it originally acquired the lock. However, a
processor can release spin locks in any order of rank. (See Table 3-3 for
additional information on spin lock IPL and rank requirements.)
In a full-checking synchronization environment, violation of spin lock
synchronization will produce the bugchecks described in. Table E-4.
Table E-4
SPLIPLHIGH

Bugchecks Produced Within Full-Checking Synchronization
A processor has attempted to acquire a spin lock at an IPL higher than the IPL associated with
spin lock synchronization (SPL$B_IPL). SMP$ACQUIRE (called by the LOCK and FORKLOCK
macros with condition=NOSETIPL not specified) signals this bugcheck.
A processor has attempted to acquire a device lock-not already owned by the acquiring
processor-at an IPL higher than the IPL associated with device lock synchronization (SPL$B_
IPL). SMP$ACQUIREL (called by the DEVICELOCK macro with condition=NOSETIPL not set)
signals this bugcheck.

SPLIPLLOW

A processor has attempted to unconditionally or conditionally release a spin lock or device lock at
an IPL lower than the IPL at which it originally acquired it. SMP$RELEASE and SMP$RESTORE
(called by the UNLOCK and FORKUNLOCK macros) and SMP$RELEASEL or SMP$RESTOREL
(called by the DEVICEUNLOCK macro) signal this bugcheck.

SPLACQERR

A processor has attempted to acquire a spin lock while holding a higher ranked spin lock.
SMP$ACQUIRE, SMP$ACQUIREL, and SMP$ACQNOIPL (called by the LOCK, FORKLOCK,
and DEVICELOCK macros) signal this bugcheck.

SPLRELERR

An attempt has been made to completely release a spin lock not owned by the releasing
processor. SMP$RELEASE and SMP$RELEASEL (called by the UNLOCK, FORKUNLOCK, and
DEVICEUNLOCK macros) signal this bugcheck.

SPLRSTERR

An attempt has been made to conditionally release a spin lock not owned by the releasing
processor. SMP$RESTORE and SMP$RESTOREL (called by the UNLOCK, FORKUNLOCK,
and DEVICEUNLOCK macros when condition=RESTORE is specified) signal this bugcheck.

E-18

Multiprocessing Requirements on Kernel-Mode Code
E.3 Adapting Device Drivers to Run on a VMS Multiprocessing System

E.3.7.2

Analyzing a Multiprocessing System Failure

When invoked to analyze either a crash dump or a running system, the
VMS System Dump Analyzer (SDA) establishes a default context for itself
from which it interprets certain commands.
When the subject of analysis is a VMS uniprocessing system, SD.Ns
context is solely process context. That is, SDA can interpret its processspecific commands in the context of either the process current on the
uniprocessor or some other process in some other scheduling state. When
initially invoked to analyze a crash dump, SD.Ns process context defaults
to the process that was current at the time of the crash. When invoked to
analyze a running system, process context is initially that of the current
process: that is, the one executing SDA. Change SD.Ns process context by
entering commands in any of the following forms:
SET PROCESS/INDEX=nn
SET PROCESS name
SHOW PROCESS/INDEX=nn
When invoked to analyze a crash dump from a VMS multiprocessing
system with more than one active CPU, SDA maintains a second
dimension of context-its CPU context-that allows it to display
certain processor-specific information, such as the reason for the bugcheck
exception, the currently executing process, the current IPL, the contents of
processor-specific registers, the interrupt stack pointer (ISP), and the spin
locks owned by the processor. When invoked to analyze a multiprocessor's
crash dump, the SDA CPU context defaults to that of the processor that
induced the system failure.
Note: When you use SDA to analyze a running system, CPU context is
not accessible to SDA. As a result, the SET CPU and SHOW CPU
commands are not permitted.
Change the SDA CPU context by using any of the following commands:
SET CPU cpu-id
SHOW CPU cpu.;id
SHOW CRASH
Changing CPU context involves an implicit change in process context in
one of the following ways:
•

If there is a current process on the CPU made current, SDA process

context is changed to that of the CPU's current process.
•

If there is no current process on the CPU made current, SDA process

context is undefined and no process-specific information is available
until SDA process context is set to that of a specific process.
Changing process context can involve a switch of CPU context as well.
For instance, if you enter a SET PROCESS command for a process that is
current on another CPU, SDA will automatically change its CPU context to
that of the CPU on which the process is current. The following commands
can have this effect if the name or index number (nn) refers to a current
process:
SET PROCESS name

E-19

Multiprocessing Requirements on Kernel-Mode Code
E.3 Adapting Device Drivers to Run on a VMS Multiprocessing System

SET PROCESS/INDEX=nn
SHOW PROCESS name
SHOW PROCESS/INDEX=nn
E.3.7.2.1

Investigating the Status of Spin Locks

SDA now includes the command SHOW SPINLOCKS. The SHOW
SPINLOCKS command displays various levels of information about system
spin locks, fork locks, and device locks that help investigations of system
failures caused by synchronization violations.
For each spin lock, fork lock, or device lock in the system, SHOW
SPINLOCKS provides the following information:
•

Name of the spin lock (or device name for the device lock)

•

Address of the spin lock (SPL) structure

•

The owner CPU's CPU ID

•

IPL at which allocation of the lock is synchronized on a local processor

•

Number of nested acquisitions of the spin lock by the processor (depth
of ownership)

•

Rank of the spin lock

•

Number of processors waiting to obtain the spin lock

•

Spin lock index

SHOW SPINLOCKS/BRIEF produces a condensed display of this same
information.
If the VAX system under analysis had been executing with full-checking

synchronization enabled (that is, with the MULTIPROCESSING system
parameter set to 1or2), SHOW SPINLOCKS/FULL adds to the spin lock
display the last eight PCs at which the lock was acquired or released.
E.3.7.3

Using XDELTA on SMP Systems

Only one processor in a VMS multiprocessing environment can be in
XDELTA at a time. If one processor attempts to enter XDELTA while
another processor is using XDELTA, it waits until the other processor
has exited XDELTA. If the processor using XDELTA sets a breakpoint,
other SMP processors are aware of the breakpoint. Therefore, when the
code with the XDELTA breakpoint is executed on another processor, that
processor will stop at the specified breakpoint and wait to enter XDELTA.
XDELTA uses its own system control block (SCB) to direct all interrupt
handling to an error handling routine in XDELTA. Therefore, an error
encountered by XDELTA will not affect any of the other processors which
share the standard system SCB.

E-20

Glossary

ACF: See configuration control block.
ACP: See ancillary control process.
active set: In a VMS symmetric multiprocessing system, those processors that
have been bootstrapped into the system, have undergone initialization, and are
capable of scheduling and executing processes. Together, the primary processor
and all secondary processors make up a system's active set. Compare with
available set.
adapter control block {ADP): A structure in the 1/0 database that describes an 1/0
adapter (or VAXBI device) and its resources.
ADP: See adapter control block.

AEN: See asynchronous event notification.
affinity: In a VMS symmetric multiprocessing system, a close association of a device
or a process with a specific processor or set of processors in the system. See
device affinity and process affinity.
allocate a device: To reserve a particular device unit for exclusive use. A user
process can allocate a device only when that device is not allocated by any other
process.
ancillary control process {ACP): A process that acts as an interface between user
software and an 1/0 driver. An ACP provides functions supplemental to those
performed by the driver, such as file and directory management.

Examples of ACPs are the magnetic tape ACP (MTAACP) and the network ACP
(NETACP).
ASMP: See asymmetric multiprocessing.
assign a channel: To establish the necessary software linkage between a user
process and a device unit before a user process can communicate with that
device. A user process requests the system to assign a channel and the system
returns a channel number.
AST: See asynchronous system trap.
ASTLVL: See asynchronous system trap level.

Glossary-1

Glossary

asymmetric multiprocessing (ASMP): A multiprocessing configuration in which the
processors are not equal in their ability to execute operating system code. In
general, a single processor is designated as the primary, or master, processor;
other processors are the slaves. The slave processors are limited to performing
certain tasks, whereas the master processor can perform all system tasks.
Contrast with symmetric multiprocessing.
asynchronous event notification (AEN): SCSI protocol allowing a SCSI device that
is usually a target to inform the processor (usually the initiator) that an event
has occurred asynchronously with respect to the processor's current stream of
execution.
asynchronous system trap (AST): A software-simulated interrupt that passes
control to a user-defined routine. ASTs enable a user process to be notified of the
occurrence of a specific event asynchronously with respect to the execution of the
user process.
If a user process has defined an AST routine for an event, the system interrupts
the process and executes the AST routine when that event occurs. When the AST
routine exits, the system resumes execution of the process at the point where it
was interrupted.

asynchronous system trap level (ASTLVL): A value kept in an internal processor
register that is the highest access mode for which an AST is pending. The AST
does not occur until the current access mode drops in privilege (rises in numeric
value) to a value greater than or equal to ASTLVL. Thus, an AST for an access
mode will not be delivered while the processor is executing in a more privileged
access mode.
attached processor: See secondary processor.
available set: In a VMS symmetric multiprocessing system, those processors that
have passed the system's power-on hardware diagnostics and may or may not
be actively involved in the system. The available set includes the active set.
Compare with active set.
backplane interconnect: An internal processor bus that allows 1/0 device controllers
to communicate with main memory and the central processor. These 1/0
controllers may reside on the same bus as memory and the central processor
(for instance, in a VAX 82x0/83x0 system), or they may be on a separate bus
entirely (for instance, in a VAX 8600/8650 system). In the latter case, an 1/0
adapter enables and controls the communications between the 1/0 bus and the
processor and memory.

The backplane interconnect is called the synchronous backplane interconnect
(SBI) in the VAX-111780 and VAX 8600/8650 systems, the CPU-to-memory
interconnect (CMI) in the VAX-111750 system, the VAXBI in the VAX 82x0/83x0
systems, and the memory interconnect (NMI or XMI) in VAX 85x0/8700/88x0
and VAX 6000-series systems. The MicroVAX processors use the Q22 bus as a
backplane.
base register: A general register that contains the base address (the address of the
first entry) of a list, table, array, or other data structure.

Glossary-2

Glossary

buffered data path: A UNIBUS adapter data path that transfers several bytes of

data in a single backplane-interconnect transfer.
buffered 1/0: An I/O operation, such as terminal or mailbox I/O, in which an

intermediate buffer from the system's buffer pool is used instead of a buffer
in process space. See also direct I I 0.
bugcheck: The operating system's diagnostic that detects and reports internal

inconsistencies. If the system can continue running, it declares a nonfatal
bugcheck and reports it in an error log entry. A serious error results in a fatal
bugcheck. As a result of a fatal bugcheck, the system shuts itself down in an
orderly fashion.
busy wait: See spin wait.
CALL instructions: The processor instructions CALLG (Call Procedure with General

Argument List) and CALLS (Call Procedure with Stack Argument List).
capability: In a VMS symmetric multiprocessing environment, an attribute of a

single processor or set of processors. The capabilities required by a given process
determine the set of processors on which it can be scheduled. For instance, the
VMS routine that maintains the system time can execute only on the processor
that has the timekeeper capability.
CCB: See channel control block.
channel: A logical path connecting a user process to a physical device unit. A user

process requests the operating system to assign a channel to a device so the
process can communicate with that device. See also controller data channel.
channel control block (CCB): A structure in the I/O database maintained by the

Assign-I/0-Channel system service to describe the device unit to which a channel
is assigned.
channel request block (CRB): A structure in the I/O database that describes the

activity on a particular controller. The CRB for a controller contains pointers to
the queue of drivers waiting to access a device through the controller.
class driver: See SCSI class driver.

Structure created by a SCSI class driver (or an
application using the VMS generic SCSI class driver) in order to initiate a
request of a device on the SCSI bus.

command descriptor block:

configuration control block (ACF): A structure in the I/O database used by the

autoconfiguration facility of the System Generation Utility to describe the device
it is adding to the system. The information stored in the ACF might be useful to
a device driver's unit delivery routine.
configuration register: A control and status register for an I/O adapter (for example,

a UNIBUS adapter). It resides in the adapter's I/O space.

Glossary-3

Glossary

connection: Logical link between a SCSI class driver and a device on the SCSI

bus, involving the binding of the class driver to the VMS SCSI port driver. The
connection allows the driver to issue commands to the SCSI device.
The class driver invokes the SPI$CONNECT macro to perform this linkage. A
connection lasts throughout the run-time life of a system; a SCSI class driver
should never need to break a connection.
connect-to-interrupt: A function by which a process connects to a device interrupt

vector. To perform a connect-to-interrupt, the process must map to the physical
pages in the 1/0 space that contain the vector.
console: The manual control unit integrated into the central processor. The console

includes a serial-line interface connected to a hardcopy terminal. This enables
the operator to start and stop the system, monitor system operation, and run
diagnostic programs.
console terminal: The terminal connected to the central processor's console.
context: The environment of an activity. See also process context, hardware context,

and software context.
control and status register (CSR): A control and status register for a device or

controller. It resides in the processor's 1/0 space.
controller data channel: A logical path to which the driver of a device that shares a

controller must gain access before it can use the controller to activate a device.

CAB: See channel request block.
CSR: See control and status register.
database: A collection of related data structures; all the occurrences of data

described by a database management system.
data structure: Any table, list, array, queue, or tree whose format and access

conventions are well defined for reference by one or more images.
DDB: See device data block.
DDT: See driver dispatch table.
device affinity: In a VMS symmetric multiprocessing system, a close association of

a device with a specific processor or set of processors in the system. There are
three dimensions to device affinity in a VMS system. First, physical connectivity
describes those devices that are directly accessible only to the primary processor
or to all processors. Secondly, affinity is a software mechanism that defines
those processors that can initiate an 1/0 operation on the device. Finally,
interruptibility describes the set of processors that can receive interrupts from a
device.
device data block (DOB): A structure in the I/O database that identifies the generic

device/controller name and driver name for a set of devices that share the same
controller.

Glossary-4

Glossary

device driver: The set of instructions and tables that handles physical I/O

operations to a device.
device ID: See SCSI device ID.
device interrupt: An interrupt received on interrupt priority levels 20 through 23.

Device interrupts can be requested only by devices, controllers, and memories.
device lock: In a VMS symmetric multiprocessing system, a dynamic spin lock the

ownership of which synchronizes device-specific code that executes at device IPL.
A device lock is associated with each adapter or controller in the system. See
spin lock.
device register: A location in controller logic used to request device functions (such

as I/O transfers) and/or report status.
device unit: One device and its controlling logic (for example, a disk drive or

terminal). Some controllers can have several device units connected to a single
controller (for example, mass-storage controllers).
diagnostic program: A program that tests hardware, firmware, peripherals logic, or

memory, and that reports any faults it detects.
direct data path: A UNIBUS adapter data path that transfers several bytes of data

in a single backplane-interconnect transfer.
direct 1/0: An I/O operation in which VMS locks the pages containing the associated

buffer in physical memory for the duration of the I/O operation. The I/O transfer
takes place directly from the process's buffer. Contrast with system buffered I I 0.
direct-memory-access (OMA) transfer: The type of I/O transfer by which a device

controller accesses memory directly and, as a result, can transfer a large amount
of data without requesting a processor interrupt after each of the smaller
amounts. Contrast with programmed-I I 0 (PIO) transfer.
DPT: See driver prologue table.
drive: The electromechanical unit of a mass storage device on which a recording

medium (disk cartridge, disk pack, or magnetic tape reel) is mounted.
driver dispatch table (DDT): A table in a driver that lists the addresses of the entry

points of standard driver routines and the sizes of diagnostic and error message
buffers for the device.
driver prologue table (DPT): A table in a driver that describes the driver and the

type of device it controls to the VMS procedure that loads drivers into the system.
dynamic load balancing: A method of work distribution in which the operating

system ensures that the system work load is evenly distributed among the
processors. Dynamic load balancing in a VMS symmetric multiprocessing
system is a direct effect of the implementation of the scheduler. In a VMS
multiprocessing system, processors independently and continually look for
processes to execute from a common pool of such processes.

ECC: Error-Correction Code.
Glossary-5

Glossary

error logger: A system process that empties the error logging buffers and writes the

error messages into the error file. Errors logged by the system include memory
errors, device errors and timeouts, and interrupts with invalid vector addresses.
exception: An event detected by the hardware or software (other than an interrupt

or jump, branch, case, or call instruction) that changes the normal flow of
instruction execution.
An exception is always caused by the execution of an instruction or set of
instructions (whereas an interrupt is caused by an activity in the system that is
independent of the current instruction).

There are three types of hardware exceptions: traps, faults, and aborts.
Examples are attempts to execute a privileged or reserved instruction,
trace traps, page faults, compatibility-mode faults, execution of breakpoint
instructions, and arithmetic traps.
executive: The software that provides the basic control and monitoring functions of

the operating system.
extended QIO processor: The facility that supplements the QIO driver's functions

when the driver performs virtual I/O operations on file-structured devices
(Files-11 On-Disk Structure Level 2). The XQP executes as a kernel-mode
thread in the process of its caller.
FDT: See function decision table.
FDT routines: Driver routines called by the $QIO system service to perform device-

dependent preprocessing of an I/O request.
fork block: That portion of a data structure, such as the unit control block, which

contains a driver's context while the driver is waiting for an event or a resource.
A driver awaiting the processor resource has its UCB fork block linked into a
processor-specific fork queue.
fork dispatcher: A VMS interrupt service routine that is activated by a software

interrupt on the local processor at a fork IPL. Once activated, it obtains the fork
lock associated with the fork IPL and dispatches driver fork processes from a
fork queue until no processes remain in the queue for that IPL.
fork lock: In a VMS symmetric multiprocessing system, a static spin lock the

ownership of which synchronizes the right of a driver's fork process to execute at
its associated fork IPL. See spin lock.
fork process: A process with a minimal context that executes instructions under

a set of constraints: it executes at raised interrupt priority levels; it uses RO
through R5 only (other registers must be saved and restored); it executes in the
system's virtual address space; it can refer to and modify static storage that is
never modified by procedures that execute at a higher IPL. VMS uses software
interrupts, spin locks, fork processes, and resource wait queues to synchronize
executive operations.
fork queue: A processor-specific queue of fork blocks that are awaiting activation at

a particular IPL by the VMS fork dispatcher.

Glossary-6

Glossary

function code: See I I 0 function code.
function decision table (FDn: A table in the driver that lists all valid function codes
for the device and lists the addresses of preprocessing routines associated with
each valid function of the device.
function modifier: See I I 0 function modifier.
generic device name: A device name that identifies the type of device but not
a particular unit; a device name in which the specific controller and/or unit
number is omitted (for example, MB).
hardware context: The values contained in the following registers while a process is
executing:

•

The PC

•

The PSL

•

The 14 general registers (RO through R13)

•

The four processor registers (POBR, POLR, PlBR, and PlLR) that describe
the process's virtual address space

•

The SP for the access mode in which the processor is executing

•

The contents to be loaded in the SP for every access mode other than the
current access mode

When a process is executing, its hardware context is continually being updated
by the processor. When a process is not executing, its hardware context is stored
in its hardware PCB.
hardware process control block (hardware PCB): A data structure known to the
processor that contains the hardware context when a process is not executing. A
process's hardware PCB resides in its process header (PHD).
IDB: See interrupt dispatch block.
Initiator: A SCSI device (usually the host processor) that requests another SCSI
device (the target) to perform an operation.
interrupt: An event other than an exception or a branch, jump, case, or call
instruction that changes the normal flow of instruction execution. Interrupts
are generally external to the process executing when the interrupt occurs. See
also device interrupt, software interrupt, and urgent interrupt.
interrupt dispatch block (IDB): A structure in the I/O database that describes the
characteristics of a particular controller and points to devices attached to that
controller.
interrupt priority level (IPL): The level at which a software or hardware interrupt is
generated. There are 32 interrupt priority levels: IPL 0 is lowest, 31 is highest.
The levels arbitrate contention for processor service. For example, a device
cannot interrupt a processor if the processor is currently executing at an IPL
greater than the IPL of the device's interrupt request.
interrupt service routine (ISR): A routine executed when a device interrupt occurs.
Glossary-7

Glossary

interrupt stack (IS): The processor-specific stack used when the processor is

executing instructions in interrupt context. In the VMS operating system, all
hardware interrupts (and all software interrupts above IPL 3) are serviced on a
processor-specific interrupt stack and not one of the process stacks.
interrupt stack pointer (ISP): The pointer to the top of the interrupt stack.
interrupt vector: See vector.
1/0 database: A collection of data structures that describe I/O requests, controllers,

device units, volumes, and device drivers in a VMS system. Examples are the
driver dispatch table, driver prologue table, device data table, unit control block,
channel request block, I/O request packet, and interrupt dispatch block.
1/0 driver: See driver.
1/0 function: An I/O operation interpreted by the operating system and typically

resulting in one or more physical I/O operations.
1/0 function code: A 6-bit value specified in a $QIO system service call that

describes the particular I/O operation to be performed (such as, read, write,
rewind).
1/0 function modifier: A 10-bit value specified in a $QIO system service call that

modifies an I/O function code (for example: read terminal input, no echo).
1/0 lockdown: The state of a page such that it cannot be paged or swapped out of

memory.
1/0 request packet (IRP): A structure in the I/O database that describes an

individual I/O request. The $QIO system service creates an IRP for each I/O
request. VMS and the driver of the target device use information in the IRP to
process the request.
1/0 rundown: An operating system function in which the system cleans up any I/O

in progress when an image exits.
1/0 space: The regions of physical address space that contain the configuration

registers and device control and status register and data registers. These regions
are physically noncontiguous.
1/0 status block (IOSB): A data structure associated with the $QIO system service.

This service optionally returns a status code, number of bytes transferred, and
device/function-dependent information in an I/O status block. The information
is not returned from the system service call, but filled in by VMS when the I/O
request completes.
IPL: See interrupt priority level.
IRP: See I I 0 request packet.
ISP: See interrupt stack pointer.
ISR: See interrupt service routine.

Glossary-8

Glossary

limit: The size or number of items requiring system resources (such as mailboxes,
locked pages, I/O requests, or open files) that a job is allowed to have at any
one time during execution, as specified by the system manager in the user
authorization file. See quota.
load balancing: A function of the operating system by which work is distributed
equally among all processors in a system. For more information, see static load
balancing and dynamic load balancing.
locking a page in memory: Making a page ineligible for either paging or swapping.
A page stays locked in physical memory until VMS specifically unlocks it.
logical-1/0 function: A set of I/O operations (for example, read-logical-block
and write-logical-block) that allow restricted direct access to device-level I/O
operations using logical block numbers.
logical unit number (LUN): Unique value, from 0 to 7, that identifies a physical or
virtual device accessible by means of a SCSI device with respect to that device's
SCSI device ID.
loosely coupled system: A multiprocessing system configuration consisting of
separate operating systems that communicate through some message transfer
mechanism. Contrast with tightly coupled system.
LUN: See Logical unit number.
machine check: An exception that is reported when the processor or an external
adapter detects an internal error. If the machine check is recoverable,
the machine check handler logs the condition in an error log entry. If an
unrecoverable machine check occurs while the processor is in supervisor or user
mode, the machine check handler reports the exception to that mode. However,
if an unrecoverable machine check occurs in kernel or executive mode, a fatal
bugcheck results. See also exception and bugcheck.
mailbox: A software data structure that is treated as a record-oriented device for
interprocess communication (for example, the error logger and OPCOM read
from systemwide mailboxes). Communication using a mailbox is similar to other
forms of device-independent I/O. Senders write to a mailbox; the receiver reads
from that mailbox.
map register: See scatter-gather map.
MASSBUS adapter (MBA): An interface device between the backplane interconnect
and the MASSBUS.
memory interconnect: The name of the internal processor bus for the VAX-11/750
(CMI), VAX 85x0/8700/88x0 (NMI), VAX 6000 series (XMI), and VAX 9000 series
(SCU).
multiprocessing system: A system containing two or more general purpose
processors. These processors are connected through hardware so that they
can work on the same application concurrently. See asymmetric multiprocessing
and symmetric multiprocessing.

Glossary-9

Glossary

multiprogramming: A mode of operation in which hardware resources are shared

among multiple, independent software processes.
nexus: A physical connection to the synchronous backplane interconnect (SBI). For

example, when connected to the SBI, the central processor, memory subsystem,
and I/O controllers are known as nexuses. See also synchronous backplane
interconnect.
node: A VAXBI interface-such as a central processor, controller, or memory

subsystem-that occupies one of 16 logical locations on a VAXBI bus. See also
VAXBI.
offset: A displacement from the beginning of a data structure to the beginning of a

field within that data structure. Offsets for items within a data structure usually
have an associated symbol. The name of the symbol is used to refer to the field;
its value is the offset.
page-frame number (PFN): The high-order 21 bits of the physical address of a page

in physical memory.
page-table entry (PTE): The data structure that identifies the physical location and

status of a page of virtual address space. When a virtual page is in memory,
the PTE contains the page-frame number needed to map the virtual page to
a physical page. When it is not in memory, the page-table entry contains the
information needed to locate the page on secondary storage (disk).
parallel processing: A method of computing that occurs when a section of an

application is divided into multiple tasks, and those multiple tasks are executed
simultaneously on multiple processors.

PCB: See process control block.
PFN: See page-frame number.
physical address: The address used by hardware to identify a location in physical

memory or on directly-addressable secondary storage devices such as disks. A
physical-memory address consists of a page-frame number and the number of
a byte within the page. A physical-disk-block address consists of a cylinder or
track and a sector number.
physical address space: The set of all possible physical addresses that can be used

to refer to locations in memory (memory space) or device registers (I/0 space).
physical-1/0 functions: A set of I/O functions that allows access to all device-level

I/O operations except maintenance-mode operations.
PIO: See process identification.
port: See SCSI port.
port driver: See SCSI port driver.
port ID: See SCSI port ID.

Glossary-10

Glossary

primary processor: The processor in a VMS symmetric multiprocessing system that
is either logically or physically attached to the console device. Only the primary
processor performs the initialization activities that define the VMS environment
and prepare memory for the entire system. In addition, the primary processor
serves as the system timekeeper.
process: The basic entity, scheduled by the system software, that provides the
context in which an image executes. A process consists of an address space,
hardware context, and software context.
process affinity: In a VMS symmetric multiprocessing system, a close association
of a process with a specific processor or set of processors in the system. Process
affinity can be indicated as either a requirement that a process run only on the
processor with a specific CPU ID or on a processor or set of processors that have
a needed capability. See capability.
process context: The hardware and software contexts of a process.
process control block (PCB): A data structure used to contain process context. The
hardware PCB contains the hardware context. The software PCB contains the
software context, which includes a pointer to the hardware PCB.
process identification (PID): A 32-bit value that uniquely identifies a process. Each
process has a PID and a name.
process 1/0 channel: See channel.
process page tables: The page tables used to describe process virtual memory.
process priority: The priority assigned to a process for scheduling purposes. The
operating system recognizes 32 levels of process priority, where 0 is lowest and
31 is highest. Levels 16 through 31 are used for real-time processes. The system
does not modify the priority of a real-time process (although the system manager
or the process itself might). Levels 0 through 15 are used for normal processes.
The system can temporarily increase the priority of a normal process based on
the activity of the process.

Contrast with interrupt priority level.
program section (psect): A portion of a program with a given protection and set of
storage-management attributes. Program sections that have the same attributes
are gathered together by the linker to form an image section.
programmed-1/0 (PIO) transfer: The type of I/O transfer, largely conducted by the
driver program, that requires processor intervention after each byte or word is
transferred. Drivers for relatively slow devices, such as printers, card readers,
terminals, and some disk and tape drives use PIO data transfers. Contrast with
direct-memory-access (DMA) transfer.
PTE: See page-table entry.
Q22 bus: The hardware interconnect by which MicroVAX peripheral devices

communicate with main memory and the processor.

Glossary-11

Glossary

QIO: Queue I/O Request system service. The VMS system service that services

$QIO and $QIOW requests. The Queue 1/0 Request system service prepares
an I/O request for processing by the driver and performs device-independent
preprocessing of the request. This system service also calls driver FDT routines.
See also FDT routines.
quota: The total amount of a system resource, such as CPU time, that a job is
allowed to use in an accounting period, as specified by the system manager in
the user-authorization file. See limit.
return status code: See status code.
SBI: See synchronous backplane interconnect.
scatter-gather map: A technique by which a set of physically discontiguous pages
are made to seem contiguous to an 1/0 controller performing a direct-memoryaccess transfer. It is 1/0 adapter hardware that generally provides this means of
mapping physical pages to 1/0 adapter address space.
SCORP: See SCSI class driver request packet.
SCOT: See SCSI connection descriptor table.
SCSI: Refers to the American National Standard for Information Systems Small
Computer System Interface-1 (X3.131-1986) or the ANSI Small Computer
System Interface-2 (X3.131-1989). This standard defines mechanical, electrical,
and functional requirements for attaching small computers to each other and to
intelligent peripheral devices.
SCSI class driver: Component of the VMS SCSI class/port architecture that acts
as an interface between the user and the SCSI port, translating I/O functions as
specified in a user's $QIO request to a SCSI command targeted to a device on
the SCSI bus. Although the class driver knows about SCSI command descriptor
buffers, status codes, and data, it has no knowledge of underlying bus protocols
or hardware, command transmission, bus phases, timing, or messages. A single
class driver can run on any given MicroVAXNA.Xstation system, in conjunction
with the SCSI port driver that supports that system.
SCSI class driver request packet (SCORP): A VMS data structure that contains
information specific to an I/O request that a SCSI class driver must deliver to
the port driver, such as the address of the SCSI command descriptor buffer. The
class driver allocates the SCDRP, and places in it data it originally received in
the I/O request packet (IRP), such as the $QIO system service parameters, 1/0
function, and the length and location of any user-specified buffer involved in a
transfer.
SCSI connection descriptor table (SCOT): A VMS data structure that contains
information describing a connection established between a SCSI class driver
and the port, such as phase records, timeout values, and error counters. The
SCSI port driver creates an SCDT each time a SCSI class driver, by invoking the
SPI$CONNECT macro, connects to a device on the SCSI bus. The class driver
stores the address of the SCDT in the SCSI device's UCB.

Glossary-12

Glossary

SCSI device ID: Unique value, from 0 to 7, representing a device on a specific SCSI
bus. A VMS SCSI device ID corresponds to the line on the SCSI data bus on
which a given device asserts itself and thus is an analog for the term SCSI ID.

Typically, a MicroVAX/VAXstation 3100 system processor is assigned device ID 6
and asserts itself at DB(6); a VAXstation 3520/3540 system processor is assigned
device ID 7, and asserts itseff at DB(7).
SCSI ID: See SCSI device ID.
SCSI port: The SCSI controller channel that controls communications to and from a
specific SCSI bus in the system.
SCSI port descriptor table (SPOT): A VMS data structure that contains information
specific to a SCSI port, such as the port driver connection database. The SPDT
also includes a set of vectors, corresponding to the SPI macros invoked by SCSI
class drivers, that point to service routines within the port driver. The SCSI port
driver's unit initialization routine creates an SPDT for each SCSI port defined
for a specific MicroVAX/VAXstation system and initializes each SPI vector.
SCSI port driver: Component of the VMS SCSI class/port architecture that
transmits and receives SCSI commands and data. It knows the details of
transmitting data from the local processor's SCSI port hardware across the
SCSI bus. Although it understands SCSI bus phases, protocol, and timing, the
SCSI port driver has no knowledge of which SCSI commands a given device
supports, what status messages it returns, or the format of the packets in
which this information is delivered. Strictly speaking, the port driver is a
communications path. When directed by a SCSI class driver, the port driver
forwards commands and data from the class driver onto the SCSI bus to the
device. On any given MicroVAX/VAXstation system, a single SCSI port driver
handles bus-level communications for all SCSI class drivers that may exist on
the system.
SCSI port ID: A unique representation of a SCSI port (see SCSI port) identifying
the SCSI bus it controls. Current legal port IDs are A and B, corresponding to a
VMS controller ID.
secondary processor: The processor or processors in a VMS symmetric
multiprocessing system that do not have the initialization and timekeeper
responsibilities of the primary processor.
Small Computer System Interface: See SCSI.
small process: A system process that has no control region in its virtual address
space and has an abbreviated context. Examples are the swapper and the null
process. A small process is scheduled in the same manner as user processes, but
must remain resident until it completes execution; it cannot be swapped.
shared memory: A generic term referring to any memory that can be accessed by
two or more concurrent processes. In a VMS symmetric multiprocessing system,
a single copy of the VMS operating system resides in memory. Each processor
in the system can access this memory, as can any process executing on any
processor.
SMP: See symmetric multiprocessing.
Glossary-13

Glossary

software context: The context maintained by VMS to describe a process. See also
software process control block (PCB).
software process control block (software PCB): The data structure used to contain
a process's software context. The operating system defines a software PCB for
every process when the process is created.

The software PCB includes the following kinds of information about the process:
current state; storage address, if the process is swapped out of memory; unique
identification of the process; and address of the process header (which contains
the hardware PCB). The software PCB resides in the system region of virtual
address space. It is not swapped with a process.
start-110 routine: The routine in a device driver that is responsible for obtaining
needed resources and for activating the device unit. An example of a needed
resource is the controller's data channel.
spin lock: In a VMS symmetric multiprocessing system, a semaphore associated
with a set of system structures, fields, or registers whose integrity is critical to
the performance of a specific operating system task. There are two types of spin
lock. Static spin locks are assembled permanently into the system; the same
static spin locks exist in the same memory locations in all VMS multiprocessing
systems. A fork lock is a form of static spin lock. Dynamic spin locks are created
as required by the I/O configuration of a system; as a result, the set of dynamic
spin locks differs from processor to processor. A device lock is a form of dynamic
spin lock. See fork lock and device lock.
spin wait: In a VMS symmetric multiprocessing system, an execution loop
performed by a processor attempting to acquire a spin lock already owned by
another processor in the system. This activity is also known as a busy wait.
SPOT: See SCSI port descriptor table.
static load balancing: A method of work distribution in which every process in an
application is preassigned to a processor during process creation.
status code: A longword value that indicates the success or failure of a specific
function. For example, system services always return a status code in RO upon
completion.
SVA: See system virtual address.

symmetric multiprocessing (SMP): A multiprocessing system configuration in which
all processors have equal access to operating system code residing in shared
memory and can perform all, or almost all, system tasks.
synchronous backplane interconnect (SBI): The part of the VAX-11/780, VAX-11
1785, and VAX 8600/8650 hardware that interconnects the processor, memory
controllers, MASSBUS adapters, and the UNIBUS adapter.
system control unit (SCU): Functions as a memory interconnect and internal
processor bus for the VAX 9000-series systems. Also connects to the I/O control
unit and XJA adapters translating I/O addresses between the primary I/O buses
CXMis) and memory or processors in the system.
Glossary-14

Glossary

system page table (SPT): The data structure that maps the system virtual

addresses, including the addresses used to refer to the process page tables.
The SPr contains one PTE for each page of system virtual memory. The physical
base address of the SPr is contained in a processor register called the System
Base Register (SBR).
system virtual address (SVA): A virtual address identifying a location mapped to an

address in system space.
target: A SCSI device that performs an operation requested by an initiator.
tightly coupled system: A multiprocessing system configuration consisting of

multiple processors sharing a single copy of the operating system. These
processors are connected so that they can communicate and share data. Contrast
with loosely coupled system.
timeout: The expiration of the time limit in which a device is to complete an I/O

transfer. The driver's wait-for-interrupt request specifies the timeout limit.
timer: A system process that maintains the time of day and the date. It is also alert

for device timeouts and performs time-dependent scheduling upon request. The
timer's interrupt service routine creates the timer process.
UCB: See unit control block.
UNIBUS adapter: An interface device between the backplane interconnect and the

UNIBUS. In a VAX-11/780, VAX-111785, or VAX 8600/8650 system this device
is called the UBA. In a VAX-111750 system, it is called the UBI. In a VAX 82x0
/83x0 or VAX 85x0/8700/88x0 system, it is called a DWBUA. In a VAX 6000-series
system, it is called a DWMUA.
unit control block (UCB): A structure in the I/O database that describes the

characteristics of a device unit and current activity on it. The unit control
block also holds the fork block for its unit's device driver; the fork block is part of
the UCB and is a critical part of a driver fork process. The UCB also provides a
static storage area for the driver.
unit initialization routine: The routine that readies controllers and device units

for operation. Controllers and device units require initialization after a power
failure and during execution of the driver-loading procedure.
urgent interrupt: An interrupt received on interrupt priority levels 24 through

31. These can be generated only by the processor for the interval clock, serious
errors, and power failures.
VAXBI: The part of the VAX 82x0/83x0 hardware that connects 1/0 adapters with

memory controllers and the processor. In a VAX 85x0/8700/88x0 system, the part
of the hardware that connects 1/0 adapters with the bus that interfaces with the
processor and memory.

Glossary-15

Glossary

vector: A one-dimensional array.

An interrupt or exception vector is a storage location known to the system that
contains the starting address of a routine to be executed when a given interrupt
or exception occurs. The system defines separate vectors for each interrupting
adapter and for classes of exceptions. Each system vector is a longword.
For the purpose of handling exceptions, users can declare up to two softwareexception vectors (primary and secondary) for each of the four processor-access
modes. Each vector contains the address of a condition handler, and is a
longword.
virtual-1/0 functions: A set of I/O functions that must be interpreted by an ancillary
control process.
wait-for-interrupt request: A request made by a driver's start-I/0 routine after it
activates a device. The request causes the driver's fork process to be suspended
until the device requests an interrupt or the device times out.
XDELTA: A software tool for debugging the VMS operating system and device
drivers.
XQP: See extended QIO processor.

Glossary-16

Index

A
Aborting an 1/0 request
See 1/0 request
ACB (AST control block) • 4-20
Access rights block
See ARB
Action routine
See FDT routine
Action routine bit mask • 4-12
Adapter
See 1/0 adapter
Adapter control block
See ADP
Adapter dispatch table • 14-27, 14-30
examining • 13-9
Address
on VAXBI • 12-9
on XMI • 12-11
ADP$L_AVECTOR • 16-9
ADP$L_BIMASTER • 16-10, 16-17
ADP$L_Bl_IDR • 16-10, 16-15
ADP$L_CSR • 16-9
ADP$L_DPQFL • E-14
ADP$L_MBASCB • 16-10
ADP$L_MBASPTE • 16-10
ADP$L_MR2QFL • E-14
ADP$L_MRQFL • E-14
ADP$L_VECTOR • 14-30
ADP$W_ADPTYPE • 16-9
ADP$W_Bl_VECTOR • 16-10, 16-15
ADP$W_DPBITMAP • 14-17
ADP$W_TR • 16-9, 16-18
ADP$W_XBIA_TR • 16-17
ADP (adapter control block)• 1-6, 14-15 to 14-16
address• 4-7, 14-17, 14-19, 14-30
data path allocation information • 14-17
data path wait queue • 14-17
for generic VAXBI device• 16-9 to 16-10
for MBA• 15-4, 15-7 to 15-8
for VAXBI adapter• 16-10
ADPDISP macro• 5-5 to 5-6
AEN
See Asynchronous event notification
Alignment of data transfer • 14-3

Alternate map registers • 14-3, 14-6, 14-23
See also Map registers
allocating• 14-19
allocating permanent • 11-2, 14-20
loading • 14-22
releasing • 14-26
Alternate map register wait queue • E-14
Alternate start 1/0 routine• 7-5
address • 6-4
ARB (access rights block)• 4-1 O
AST (asynchronous system trap)
delivering • 3-4
out of band• 11-8
process-requested • 4-20
queuing • 3-4
special kernel-mode• 3-4, 3-5, 4-20, 7-8, 7-8
AST control block
See ACB
ASTLVL (AST level) processor register• 3-4
AST procedure (for connect to interrupt facility) •
19-19
AST service routine (for connect to interrupt facility) •
19-9, 19-11, 19-12
Asynchronous event notification• 17-2, 17-28 to
17-30
example• 17-29 to 17-30
Asynchronous SCSI data transfer mode
enabling• 17-13
Attention condition • 15-9 to 15-1 O
See also MBA, MBA$L_AS, MASSBUS
Attention summary register
See MBA$L_AS
Autoconfig uration
driver control of• 12-21
of SCSI device• 17-30

B
Backplane interconnect • 1-11, 1-16, 14-2
See also VAXBI, CMI, SBI, 022 bus
Backplane interconnect interface chip
See BllC
Bl
See VAXBI bus
BllC$L_BCICR • 16-16, 16-28

lndex-1

Index

BllC$L_BER • 16-7, 16-15, 16-16, 16-26
BllC$L_BICSR • 16-13, 16-24 to 16-26
BllC$L_DTREG • 16-7, 16-24
BllC$L_EAR • 16-28
BllC$L_EICR • 16--11, 16-15, 16-26 to 16-27
BllC$L_GPRO • 16-30
BllC$L_GPR1 • 16-30
BllC$L_GPR2•16-30
BllC$L_GPR3 • 16-30
BllC$L_IDR • 16-15, 16-27
BllC$L_IPIDR • 16-27
BllC$L_IPIMR • 16-27
BllC$L_IPISR • 16-27
BllC$L_IPISTPF • 16-29
BllC$L_SAR • 16-27
BllC$L_UICR • 16-11, 16-15, 16-29 to 16-30
BllC$L_WSR • 16-28 to 16-29
Bl IC$V_ARBCNTRL • 16-14
BllC$V_BROKE • 16-13
BllC$V_SST • 16-13, 16-14
BllC$V_STS • 16-13, 16-14
BllC (backplane interconnect interface chip) • 16-5
clearing error register • 16-14, 16-15
CSR space • 16-5
enabling error interrupts • 16-16, 16-26
enabling options• 16-16
initializing• 11-2
self-test• 16-13 to 16-14
setting interrupt vectors• 16-15
$BllCDEF macro • 16-5, 16-23
BllC registers
accessing • 16-5
symbolic names • 16-23 to 16-30
BIOCNT (buffered 1/0 count) • 2-3
BIOLM (buffered 1/0 limit) quota
adjusting • 4-20
charging• 4-9, 4-12
checking • 4-9
BIRQ level• 14-33, 14-34
Bl_NODE_RESET macro• 16-13
Booting with XDELTA • 13-1 to 13-5
BPT (Breakpoint) instruction • 13-6
Breakpoint
clearing• 13-18
complex • 13-18
displaying XDELTA breakpoint list• 13-18
proceeding from• 13-5, 13-18
setting in driver code• 13-6, 13-10, 13-17
BREAKPOINTS parameter• 13-1, 13-5
BR level • 14-33

lndex=2

Buffer
allocating• 1-23, 2-3, 7-6 to 7-7, E-5
data area• 7-7
deallocating• 2-7, 4-20, 7-8
format• 7-7
header area· 7-7, 7-8
locking • 1-23, 6-7
size• 7-6
storing address of• 7-7
testing accessibility of• 7-6
Buffer address register • 14-23
Buffered data path • 14-8
See also Data path
allocating permanent• 11-2, 14-18, E-12
flow of read operation using • 14-12 to 14-13
flow of write operation using • 14-12
functions• 14-11
purging• 14-14, 14-19, 14-24 to 14-25
releasing • 10-2, 14-19, 14-25
requesting• 14-11, 14-17 to 14-18
rules for using• 14-11, 14-15
speed• 14-15
Buffered data path wait queue
See Data path wait queue
Buffered function bit mask• 4-11, 6-7
Buffered l/0• 1-22, 1-23, 2-3, 4-11, 11-7, 16-19
FDT routines for• 7-6 to 7-8
functions • 6-4
postprocessing • 7-8
reasons for using• 1-22 to 1-23, 6-7, 6-8
Buffered read function bit
See IRP$V_FUNC
Bugcheck • 13-21
examining information regarding • 13-5
SPLACQERR • 13-28, 13-30, E-18
SPLIPLHIGH • 13-28, E-18
SPLIPLLOW • 13-28, E-18
SPLRELERR • 13-29, 13-30, E-18
SPLRSTERR • 13-29, 13-30, E-18
BUG REBOOT parameter• 13-2, 13-5, 13-22
Bus
device assignments • 12-10
Bus grant • 14-33, 14-34
Bus request
See BR level, BIRQ level
Busy bit
See UCB$V_BSY
BYTCNT (byte count) quota• 3-13
checking• E-5
crediting • E-5

Index

BYTCNT (byte count) quota (Cont.)
debiting • E-5
Byte count register
See MBA$L_BCR
Byte offset register • 14-13
BYTLM (byte limit) quota • 3-13
checking • E-5
crediting• E-5
debiting • E-5

c
CAN$C_CANCEL• 11-8
CAN$C_DASSGN • 11-8
Cancel 1/0 bit
See UCB$V_CANCEL
Cancel 1/0 routine• 1-4, 9-8, 11-6 to 11-9
address • 6-4, 11-1
context• 11-7 to 11-8
device dependent • 11-9
device independent • 11-8 to 11-9
for connect to interrupt facility• 19-8, 19-10,
19-18 to 19-19
of CONINTERR.EXE • 19-12, 19-18
of SCSI third-party class driver• 17-28
when unneeded • 11-8
$CANDEF macro• 11-8
Card reader
device driver • 9-6 to 9-8
CCB$L_UCB • 4-5
CCB (channel control block)• 1-6, 4-5
Channel • 1-6
See also Process 1/0 channel
Channel control block
See CCB
Channel index number• 4-5, 11-8
Channel request block
See CRB
Channel wait queue
See Device controller data channel wait queue
CHMK (Change Mode to Kernel) instruction• 4-1
$CINDEF macro• 19-10
Class driver• 17-4
See Terminal class driver
SCSI template• 17-9
Class driver vector table • 18-5 to 18-6
address • 18-9
CLASS_CTRL_INIT macro• 18-12
CLASS_DDT vector table entry• 18-19

CLASS_DISCONNECT service routine• 18-19
CLASS_DS_TRANS service routine• 18-13, 18-20
CLASS_FORK service routine• 18-14, 18-20
CLASS_GETNXT service routine• 18-20, 18-21
address • 18-9
CLASS_POWERFAIL service routine• 18-13, 18-22
CLASS_PUTNXT service routine• 18-18, 18-21
address • 18-9
CLASS_READERROR service routine• 18-18, 18-22
CLASS_SETUP_UCB service routine• 18-12, 18-22
CLASS_SET_LINE service routine• 18-13
CLASS_UNIT_INIT macro• 18-9, 18-12, 18-19
Clock
See Interval clock
Cloned UCB routine• 11-12 to 11-13
address • 6-4
exit method• 11-13
input• 11-12
register usage • 11-12
CMI (CPU-to-memory interconnect)• 1-11
Coding conventions
See Device driver
COM$DRVDEALMEM • 16-21
COM$POST • 7-5
Command
See SCSI command
Command address register
See MBA$L_CAR
Configuration register
See CSR, MBA$L_CSR
CONFREGL array• 16-7
CONINTERR.EXE • 19-8, 19-13
cancel 1/0 routine of • 19-12
connecting to • 19-9
CONNECT command
See System Generation Utility
Connection • 17-5, 17-9
requesting• 17-26
Connect to interrupt driver
See CONINTERR.EXE
Connect to interrupt facility
cancel 1/0 routine • 19-18 to 19-19
condition values returned • 19-11
CONNECT command• 19-9
example of AID converter using• 19-19, 19-21 to
19-23
example of time sampling using• 19-19, 19-23 to
19-25
example of watchdog timer using• 19-19, 19-20
to 19-21
interrupt service routine• 19-16 to 19-18

lndex-3

Index

Connect to interrupt facility (Cont.)

CRB (channel request block) (Cont.)

mapping 1/0 address space • 19-8
privileges required • 19-12
programming language requirements• 19-14
start 1/0 routine• 19-15 to 19-16
SYSGEN requirements• 19-9
unit initialization routine• 19-15
user-specified routines• 19-9, 19-13 to 19-19
Control and status register

for generic VAXBI device• 16-8
fork block• 3-24, 12-7
for MBA• 15-4, 15-7 to 15-8, 15-13, 15-15
initializing• 6-3
map register allocation information • 14-20
primary• 15-13
reinitializing • 6-3
secondary • 15-13
synchronizing access to• 3-16
CSR (control and status register) • 14-4, 14-23

See CSR
Control block
See Data structure
Controller
See Device controller
Controller initialization routine• 1-3, 11-1 to 11-6,
12-4, 12-8
address • 4-6, 6-3, 11-1, 14-30
allocating controller data channel in • 8-4
context • 11-1
for generic VAXBI device• 16-12 to 16-18
forking in • 3-24, 11-6
for terminal port driver• 18-12
functions • 11-1
input• 11-2
synchronization requirements • E-11 to E-12
Control mask
See Device activation bit mask
Control register
See CSR, MBA$L_CR
Corruption
detecting• 13-23 to 13-27
CPU$Q_SWIQFL • E-14
CPU (per-CPU database)
locating • E-7
CPUDISP macro• 5-6
CPUs
list of• 1-10
CRB$B_MASK • 4-6, 16-8
CRB$L_DLCK • 3-22
CRB$L_INTD • 4-6
CRB$L_INTD+VEC$L_INITIAL • 11-5
CRB$L_INTD+VEC$L_UNITINIT • 11-5
CRB$L_LINK • 15-13
CRB$L_WQBL • 16-8
CRB$L_WQFL • 4-6, 16-8
CRB$V_UNINIT• 16-8
CRB (channel request block}• 1-6, 4-6 to 4-7
alternate map register allocation information •
14-20
creation • 12-4
data path allocation information • 14-17 to 14-18

lndex-4

See also Device registers
address• 4-7, 8-4, 14-23
displaying address • 12-11
fixed space • 12-14
floating space • 12-14
loading • 8-5
locating device registers from • 14-23
of LP11 printer• 2-5
specifying address • 12-5
specifying offset for multiunit controller• 12-6
CTL$GL_PCB • E-6

D
Data path• 1-22, 14-7 to 14-15, 14-17 to 14-19
See also Buffered data path, Direct data path
buffered • 14-3
mixed use of direct and buffered• 14-19
purging• 10-2, 14-14, 14-19, 14-24 to 14-25
speed• 14-10, 14-11, 14-15
Data path register • 14-8, 14-15
Data path wait queue • 14-25, E-14
Data storage • 5-1
device specific• 4-5, 11-3
Data structure
See also 1/0 database
initializing• 6-1
Data transfer
See also DMA transfer, PIO transfer
alignment • 14-3
buffering mechanisms• 17-15
byte aligned • 14-3, 14-22
byte offset• 14-13, 14-18
incomplete• 17-19
in reverse direction• 15-4, 15-15
longword-aligned 32-bit random-access • 14-11
mapping local buffer for• 17-27

Index

Data transfer (Cont.)
mapping local buffer for SCSI port• 17-16 to
17-17
maximum size of• 17-14, 17-19
mixing read and write functions in• 14-10
overlapping with seek operation • 8-2
performing• 17-13 to 17-19
size• 14-23
speed• 14-10, 14-11, 14-15
starting address • 14-22 to 14-23
to randomly ordered addresses • 14-1 O
unmapping local buffer• 17-17, 17-28
word aligned • 14-3
Data transfer mode
as controlled by a third-party SCSI class driver•
17-13
asynchronous• 17-13
synchronous• 17-13
DDB$L_LINK • 11-5
DDB$L_UCB • 11-5
DDB$T_DRVNAME • 4-8
DDB$T_NAME • 4-8
DOB (device data block)• 1-5, 4-8, 11-5
creation • 12-4
initializing • 6-3
reinitializing • 6-3
DDT$L_ALTSTART • 7-5
DDT$L_UNITINIT • 11-5
DDT$W_ERRORBUF • 11-9, 17-21
DDT (driver dispatch table)• 1-2, 11-1, 11-10
address • 6-3
creating• 6-3 to 6-4, 11-4
of terminal class driver • 18-19
relocating addresses specified in• 11-4
DDTAB macro• 11-9, 12-1
Debugging
device driver • 13-1 to 13-30
DELTA
See Delta/XDelta Utility
Delta/XDelta Utility (DELTA/XDELTA) • 13-1 to 13-22
base register• 13-13
predefined • 13-13
X4•13-13
XS• 13-13
XE• 13-13
XF • 13-13
changing contents of location using• 13-15,
13-16
closing location using• 13-16
commands
executing string • 13-19, 13-20
indirect • 13-17

Delta/XDelta Utility (DELTA/XDELTA)
commands (Cont.)
predefined in XE and XF • 13-13
summary• 13-10 to 13-12
depositing command string in system patch space
for use by • 13-20
displaying contents of address range using •
13-16
displaying contents of location using• 13-16
expressions • 13-12
formats
address display • 13-15
instruction display• 13-16
guidelines • 13-21 to 13-22
prefixes
G • 13-13
H•13-13
setting PC with • 13-18
stepping through code with • 13-19
symbols
period (.) • 13-13
Q • 13-13, 13-16, 13-17
using in multiprocessing environment• 13-7, E-20
values• 13-12
DEV$V_AVL• 18-22
DEV$V_ELG • 11-9
DEV$V_NET • 18-13
DEV$V_RED • 18-22
Device
See also Device unit
byte-addressable • 14-22
Digital-supplied • 12-15
file structured • 2-3, 4-10
offsettable • 16-1 O
on VAXBI bus• 16-2
SCSI• 16-30
word-aligned• 14-18
Device activation bit mask • 8-4
Device characteristics• 7-9
specifying • 6-3
Device class
specifying • 6-3
Device controller• 1-5, 1-6
See also MBA, Controller initialization routine
initializing• 11-1
intelligent• 1-22
multiunit • 3-26, 4-6, 4-16, 8-2, 8-6, 9-8
number of units created for• 12-6
single-unit•3-26, 4-7, 10-2, 11-2, 11-3, 12-2
synchronizing access to• 3-16
Device controller channel wait queue • 3-27

lndex-5

Index

Device controller data channel• 4-6 to 4-7, 15-14,
15-15
obtaining ownership of • 3~26, 4-6, 8-2 to 8-4
owner•4-7
releasing • 3-27, 8-6, 10-2
requesting • 8-2
unavailability• 8-3
Device controller data channel wait queue • 8-3
Device database • 3-6, 3-16, E-9
synchronizing access to• 3-22
Device data block
See DOB
Device driver • 1-1
assembling with SYS$LIBRARY:LIB.MLB • 12-1,
E-7
asynchronous nature• 1-1, 1-9, 5-1
calculating base address • 13-7
coding conventions • 5-1 to 5-3, 12-1, 13-22,
13-22 to 13-23
components • 1-2 to 1-4, 5-1
context• 1-7 to 1-9
converting uniprocessing to multiprocessing • E-8
to E-20
debugging • 13-1 to 13-22
displaying address of• 12-12
entry points • 1-2, 6-3 to 6-4
example • C-1 to C-29, D-1 to D-26
flow• 1-9, 1-23 to 1-25
for generic VAXBI device• 16-1 to 16-30
for MASSBUS device • 15-1 to 15-17
for 022 bus device • 14-1 to 14-36
tor UNIBUS device• 14-1 to 14-36
functions • 1-2
hardware considerations • 1-10 to 1-20
linking with SYS$SYSTEM:SYS.STB • 12-1, 13-7,
E-8
loading•6-1, 11-3 to 11-5, 12-1 to 12-23,
13-5, 15-7 to 15-8
machine independence• 1-10, 5-5 to 5-6, 14-16
maximum number of supported units • 6-2
multiprocessor• 12-13, E-1, E-3
name•4-8, 6-2, 12-3, 12-6, 12-7, 12-12
program sections• 6-4, 12-1, 13-7
reloading• 12-7 to 12-8
size• 5-1
storing data from • 5-1
suspending• 2-6, 8-6 to 8-7, 14-24
synchronization flow • 3-17 to 3-21
synchronization methods used by• 1-7, 3-1 to
3-27
template for• A-1 to A-10
uniprocessor• 12-13, E-1, E-3

lndex-6

Device driver (Cont.)
updating old code • E-1
Device interrupt• 1-6, 3-6, 4-16, 9-1 to 9-8, 14-26
to 14-34
See also Interrupt service routine
destination for VAXBI node• 16-10
direct-vector• 14-3, 14-27, 14-29, 14-31
disabling • 5-4, 10-4
enabling • 2-5, 11-2
expected • 8-7, 9-3 to 9-4
multilevel 022bus•14-31, 14-33 to 14-36
non-direct-vector• 14-3, 14-28, 14-29, 14-31
on MASSBUS • 15-9
servicing • 2-6 to 2-7
unsolicited • 9-4 to 9-8
waiting for• 2-5 to 2-6, 4-16, 8-6 to 8-7, 14-24
Device interrupt vector • 14-26, 16-9, 16-1 O to
16-11
connecting to • 19-7 to 19-25
tor generic VAXBI device• 16-15
multiple• 14-31, 16-9
specifying address • 12-6
specifying multiple • 12-6
Device IPL• 3-6, 9-1
specifying • 6-2
Device lock • 3-6, 3-13, 3-16 to 3-17, 8-5
See also Spin lock
address • 3-22
obtaining• 3-1 O
ownership• 3-17
rank• 3-17
releasing• 3-10
DEVICELOCK macro• 3-9, 3-10, E-4, E-9, E-10,
E-11
used by interrupt service routine • 9-3
Device mode • 7-9
Device name • 1-5
Device registers• 1-6, 1-21 to 1-22, 14-23
accessing• 2-5, 4-7, 13-21 to 13-22, 14-4,
14-23, 16-5, 19-1
clearing error status • 11-2
modification by power failure• 8-5
modifying • 5-4
of LP11 printer• 2-5
rules for referencing• 5-3 to 5-5, 14-4
saving the value of• 11-11
synchronizing access to• 3-6, 3-16, 8-5
Device timeout
See Timeout
Device timeout bit
See UCB$V_TIMOUT

Index

Device type
specifying • 6-3
Device unit• 1-5
See also UCB, Unit initialization routine
activating • 2-5, 8-4 to 8-5, 14-23
autoconfiguring • 12-22 to 12-23
CSR address• 12-11
description • 4-5
initializing• 11-1
marking on line • 11-2
name•4-8
reference count• 11-7
status• 4-5
vector address • 12-11
DEVICEUNLOCK macro• 3-10, E-4, E-10, E-11
Diagnostic buffer • 4-20
specifying • 4-10, 6-4
Diagnostic register
See MBA$L_DR
DIOLM (direct 1/0 limit) quota
adjusting • 4-20
charging• 4-9, 4-12
checking • 4-9
Direct data path• 14-7, 14-10
See also Data path
functions • 14-10
purging • 14-19, 14-24 to 14-25
requesting• 14-18
speed• 14-1 O
Direct 1/0•1-22, 1-23, 7-4, 16-19
FDT routines for• 7-6, 7-9
reasons for using• 1-22 to 1-23, 6-7, 6-8
Direct memory access transfer
See OMA transfer
Direct-vector interrupt• 13-9, 14-3, 14-27, 14-29,
14-31
Disconnect feature
enabling• 17-14
Disk class driver
disabling the loading of• 17-31
Disk driver• 7-9, 8-2, 8-6, 9-5
pack acknowledgment in • 11-2
recording disk geometry in • 11-3
removing a disk volume in • 9-8
waiting for disk unit spinup in • 11-3
DLDRIVER.MAR • C-1 to C-29
OMA transfer • 1-22, 5-5
See also Map registers, Data path
byte-aligned • 14-11
detecting memory error during • 14-25
flow • 1-23 to 1-25, 14-8

OMA transfer (Cont.)
longword-aligned 32-bit random-access • 14-12,
14-14 to 14-15
on 022bus•14-15 to 14-16, 14-19 to 14-26
on UNIBUS• 14-15 to 14-26
on VAXBI bus• 16-18 to 16-22
postprocessing • 14-16, 14-24 to 14-26
start 1/0 routine• 8-1 to 8-7
using direct data path in• 14-10
using direct 1/0 in • 6-8
using 1/0 adapter resources in• 14-2 to 14-15
DMB32 asynchronous/synchronous multiplexer •
16-20
DPT$V_NOUNLOAD • 12-7
DPT$V_NO_IDB_DISPATCH • 17-25
DPT$V_SMPMOD • 12-13, E-3
DPT$V_SUBCNTRL•15-15
DPT$W_DEFUNITS • 12-21
DPT (driver prologue table)• 1-2, 3-6, 11-1, 13-7
creating • 6-1 to 6-3
initialization table • 6-2, 12-4
linked into system DPT list• 12-3, 12-7, 12-8
of third-party SCSI class driver• 17-25
reinitialization table • 6-3, 12-4, 12-8
DPTAB macro•6-1, 11-1, 12-1, 16-11
controlling autoconfiguration with • 12-21
used by MASSBUS drivers • 15-15
DPT_STORE macro• 3-6, 6-2 to 6-3, 11-9
DR11-W driver• D-1 to D-26
Driver
See Device driver
Driver dispatch table
See DDT
Driver prologue table
See DPT
Driver unloading routine • 6-3, 11-4, 12-7 to 12-8,
16-21
address • 6-2
DRV11-WA driver• D-1 to D-26
DSBINT macro• 3-9, 3-10, 8-5, 8-6, E-4, E-9,

E-10
replacing with spin lock synchronization macro •
E-13
DWBUA (VAXBl-to-UNIBUS adapter)• 1-13, 16-10,
19-4
See also UNIBUS adapter
DWMBA (XMl-to-VAXBI adapter)
See Memory interconnect to VAXBI adapter
DWMUA (VAXBl-to-UNIBUS adapter)• 1-13, 16-10
See also UNIBUS adapter
Dynamic spin lock • 3-13

lndex-7

Index

E
EMB$C_DA • 11-10
EMB$C_DE • 11-10
EMB$C_DT • 11-10
EMB$L_DV_REGSAV • 11-9
$EMBDEF macro• 11-9
EMB spin lock • 3-14
Emulated instructions
in device driver • 5-3
ENBINT macro• 3-9, 3-10, E-4
replacing with spin lock synchronization macro•
E-13
ERL$DEVICEATTN • 11-10
ERL$DEVICERR • 11-10
ERL$DEVICTMO • 10-6, 11-10
ERL$RELEASEMB • 10-3
Error
See also Error logging
associated with 1/0 request • 11-10
not associated with 1/0request•11-10
servicing within driver• 1-4, 8-5
Error log allocation buffer • 11-10
Error log entry
examining the contents of• 17-33 to 17-43
Error logging
driver prerequisites • 11-9
final error count • 10-3
Error logging enable bit
See UCB$V_ERLOGIP
Error logging routine • 1-4, 11-9 to 11-10
See also Register dumping routine
address• 11-1
in SCSI third-party class driver• 17-20 to 17-22
Error message buffer • 3-14, 10-3
allocating • 11-1 O
initializing • 11-1 O
of third-party SCSI device driver• 17-20 to 17-21
releasing • 10-3
specifying size• 6-4, 11-9, 11-10
Error status
clearing• 11-2
Event flag
posting• 4-20
setting • 2-7
Exception
generating • 5-4
EXE$ABORTIO • 7-5, 18-14
EXE$ALLOCBU F • 7-6, 16-19

lndex-8

EXE$ALOPHYCNTG • 16-21
EXE$ALTQUEPKT • 7-5
EXE$ASSIGN • 11-12
EXE$BUFFRQUOTA
replaced in VMS Version 5.0 • E-5
EXE$BUFQUOPRC
replaced in VMS Version 5.0 • E-5
EXE$CANCEL• 11-7 to 11-8
EXE$CREDIT_BYTCNT • 7-8, E-5
EXE$CREDIT_BYTCNT_BYTLM • E-5
EXE$DEBIT_BYTCNT • E-5
EXE$DEBIT_BYTCNT_ALO • 7-6, 16-19, E-6
EXE$DEBIT_BYTCNT_BYTLM •7-6, E-5
EXE$DEBIT_BYTCNT_BYTLM_ALO • 7-6, 16-19,
E-6
EXE$DEBIT_BYTCNT_BYTLM_NW • E-6
EXE$DEBIT_BYTCNT_NW• E-5
EXE$FINISHIO • 7-4, 7-9, 18-14
EXE$FINISHIOC • 7-4
EXE$FORK • 11-6
EXE$FORKDSPTH • 3-5, 3-24
EXE$GL CONFREGL • 16-7
EXE$GQ~1ST_TIME • 3-8, 3-9, 3-13, 3-14
EXE$GQ_SYSTIME • 3-8, 3-9, 3-14
reading • E-15
EXE$HWCLKINT • 3-8
EXE$1NSERTIRP •4-13
EXE$1NSIOQ • 3-23, 4-13, 7-4, 8-1
returning control to• 4-16
EXE$10FORK • 9-4, 10-1 to 10-2, 14-24
EXE$MODIFY • 7-9
EXE$0NEPARM • 7-9
EXE$QIO • 4-1 to 4-13
EXE$QIODRVPKT • 4-13, 7-4, 7-9, 8-1
EXE$QIORETURN • 18-14
EXE$READ • 7-9
EXE$READCHK • 7-6
EXE$SENSEMODE • 7-9
EXE$SETCHAR • 7-9
EXE$SETMODE • 7-9
EXE$SNDEVMSG • 9-7 to 9-8, 10-7, E-7
EXE$SWTIMINT • 3-8
EXE$WRITE • 7-9
EXE$WRITECHK • 7-6
EXE$ZEROPARM • 7-9
Expected interrupt
See Device interrupt
External register base
See MBA$L_ERB

Index

Forking (Cont.)

F
F$SEARCH lexical function • 13-24
FDT (function decision table) • 1-2, 4-10
address • 4-8, 6-4
as used by EXE$QIO • 4-8
creating• 6-4 to 6-8, 11-4
dispatching to FDT routines from •4-13
relocating addresses specified in • 11-4
specifying buffered functions in • 4-11
specifying legal functions in• 4-11
FDT routine • 1-3, 1-22 to 1-23, 2-3 to 2-4
allocating system buffer in• 7-6 to 7-7
calling sequence• 7-2
context•4-13, 7-1
creating• 7-1 to 7-5
dispatched to from EXE$QIO • 4-12
ensuring an even byte count in • 14-23
exit method• 7-2 to 7-5
for buffered 1/0 • 7-6 to 7-8
for direct 1/0 • 7-6, 7-9
provided by VMS • 7-8 to 7-9
register usage• 5-3, 7-1
File system
synchronizing access to• 3-13
FILSYS spin lock• 3-13
FIND_CPU_DATA macro• E-6
Floating address • 12-14
Floating CSR space
assigning to device • 12-22
current base • 12-22
Floating-point instructions
in device driver • 5-3
Floating vector space
assigning to device• 12-22
current base• 12-22
Fork block• 1-5, 1-8, 3-24, 3-27, 4-16, 8-7, 10-1
dequeuing • 3-5
in CRB • 12-7
in extended UCB• 11-6
Fork context• 1-8, 3-22 to 3-23, 4-16
Fork database • 3-5
synchronizing access to • 3-22 to 3-25
Fork dispatcher • 2-6, 3-3, 3-5, 3-8, 3-24
functions • 4-18
Forking • 3-16, 3-23, E-9
avoiding multiple • 11-6
from controller initialization routine• 11-6
from interrupt service routine • 9-5
from unit initialization routine• 11-6

in terminal port driver• 18-14, 18-20
Fork IPL•2-4, 3-2,3-5, 3-16, 3-22,4-18
Fork lock•2-4, 3-6, 3-8, 3-13, 3-16, 3-22, 11-7,
14-16
See also Spin lock
obtained by fork dispatcher• 3-5
obtaining• 3-10
ownership • 13-30
rank• 3-13 to 3-14
releasing • 3-1 O
Fork lock index• 3-13 to 3-14
list• E-8
placing in UCB$B_FLCK • 6-2, E-8
FORKLOCK macro• 3-9, 3-10, E-4
FORK macro • 3-12, 3-24, 14-18, 14-20
See also IOFORK macro
Fork process• 1-8, 3-22 to 3-25, 8-1
context• 4-15, 4-16, 4-17, 8-1 to 8-2
creation by driver • 2-6, 4-17, 10-1 to 10-2
creation by IOC$1NITIATE•4-13 to 4-15, 8-1,
10-3
reactivating • 4-18
rules• 3-24
suspending • 4-16, 8-6 to 8-7
Fork queue• 3-24, 4-17, 4-18, E-14
FORKUNLOCK macro• 3-10, E-4
Full-checking synchronization image• 13-28, E-17
to E-18
loading • E-2
Full duplex device driver• 7-5
FUNCTAB macro• 6-7
Function decision table
See FDT

G
General purpose registers
rules for using in driver code • 5-3
Generic VAXBI device• 11-2, 16-1 to 16-30
See also VAXBI node
initialized by driver• 16-11 to 16-18
initialized by VMS• 16-7 to 16-11
interrupt destination • 16-10

H
Hardware clock

lndex-9

Index

Hardware clock (Cont.)

1/0 postprocessing (Cont.)

See Interval clock
HWCLK spin lock• 3-8, 3-9, 3-14, E-13, E-15

device-independent• 2-7, 4-20, 7-8
for buffered 1/0 • 7-8, 14-25
for OMA transfer• 14-16, 14-24 to 14-26
synchronization flow • 3-4
1/0 postprocessing queue• 10-3, 11-7, E-14
1/0 preprocessing

I
1/0 adapter• 1-6, 1-1 O to 1-16, 1-22

See also UNIBUS adapter, MBA, and Q22 bus
displaying nexus value • 12-8, 12-11
on VAXBI bus• 16-2
type• 16-9
110 adapter registers
See Map registers, Data path register, Vector
register, Byte count register, MBA
110 address space• 19-1 to 19-7
access to during bus power failure• 19-7
error in mapping• 19-7
mapping to process address space • 19-4, 19-5
to 19-7, 19-8
of SCU/XMI bus• 16-5
of VAXBI bus• 16-2
rules for referencing• 19-7
1/0 channel
See Process 1/0 channel
1/0 completion
See 1/0 postprocessing
1/0 database • 1-4 to 1-7
creation •6-1, 6-3, 11-4, 12-3 to 12-7, 12-14,
15-7
examining with XDELTA • 13-1 O
for MASSBUS configuration• 15-7 to 15-8,
15-13
for two-controller configuration• 4-7
initializing • 11-4, 12-14
locating • 12-12
referencing fields in• 5-2
reinitializing• 11-4
1/0 function
analyzing• 8-2
indicating a buffered• 4-11, 6-4
indicating as legal to a device • 4-11 , 6-4
preprocessing • 4-12
110 function code • 4-11
converting to device-specific function code • 8-4
defined by VMS• 6-5 to 6-7
defining device-specific • 6-8
110 function modifier • 4-11
1/0 postprocessing • 3-5, 10-1 to 10-4
device-dependent • 2-7, 4-19 to 4-20, 7-8, 10-2
to 10-4

lndex-10

See also SYS$QIO and FDT routine
completing • 4-13, 6-4
device-dependent • 2-3 to 2-4, 4-1 O to 4-13,
7-1 to 7-9
device-independent • 2-3, 4-4 to 4-10
IPL requirements • 3-4
1/0 request
aborting • 7-5, 10-6
as serviced by SCSI class and port drivers• 17-22
to 17-24
canceling• 11-6 to 11-9
example• 2-1 to 2-7
restarting after power failure• 8-5
retrying • 10-5 to 10-6
returning completion status of to process• 2-7,
4-20, 7-4, 10-2, 10-3
synchronizing simultaneous processing of multiple
•7-5
validating device-dependent arguments • 2-3
validating device-independent arguments • 2-2 to
2-3, 4-8 to 4-9
with no parameters• 7-9
with one parameter• 7-9
1/0 request packet
See IRP
1/0 space

of MASSBUS • 15-4
of Q22 bus • 14-4
of UNIBUS• 14-4
rules for referencing• 5-3, 5-5
writing to • 5-4
IDB$L_ADP • 4-7
IDB$L_CSR •4-7, 15-4, 15-5, 15-13, 16-9
IDB$L_OWNER • 3-26, 4-6, 4-7, 8-4, 8-7, 9-3,
11-2
IDB$W_UNITS • 12-6, 16-9
IDB (interrupt dispatch block)• 1-6, 4-7 to 4-8,
14-23
address•4-6, 8-4, 14-30, 14-32
creation • 12-4
for generic VAXBI device• 16-9
for MBA• 15-4, 15-7 to 15-8, 15-13, 15-15
Image termination• 11-7
INl$BRK • 13-6

Index

Initialization routine
See Unit initialization routine, Controller
initialization routine
Initialization table • 6-2
Initiator• 17-2
enabling selection of• 17-28 to 17-30
Interlocked instructions
using in multiprocessing environment• E-13 to
E-14
Interprocessor interrupt • 3-4, 3-14
Interrupt• 3-3
See also Device interrupt
dismissing • 10-1
interprocessor • 3-4, 3-14
requesting an XDELTA • 13-7 to 13-8
requesting a software• 3-1 O
Interrupt context • 1-8, 9-3
Interrupt dispatch block
See IDB
Interrupt dispatcher• 3-6, 14-24, 16-9, 16-11
for MASSBUS • 15-8 to 15-12, 15-15 to 15-16
for 022 bus • 14-26 to 14-34
for UNIBUS• 14-26 to 14-34
Interrupt enable bit • 8-4
Interrupt expected bit
See UCB$V_INT
Interrupt priority level
See IPL
Interrupt service routine • 1-3, 3-3, 3-15, 9-1 to
9-8, 14-24
address • 6-3, 14-32, E-5
context • 9-3
entry point • 4-16
example • 9-6 to 9-8
for connect to interrupt facility • 19-10, 19-16 to
19-18
for LP11 printer• 2-6 to 2-7
for MASSBUS device• 15-12, 15-17
for solicited interrupt• 9-3 to 9-4
for terminal port driver• 18-18
for unsolicited interrupt • 9-4 to 9-8
functions• 4-16, 9-1
of CONINTERR.EXE • 19-13
of UNIBUS adapter• 14-29
preemption of device timeout handling • 10-5
register usage• 8-7
synchronization requirements • 3-6, 3-22, 9-3,
E-11
Interrupt stack• 8-1
Interrupt transfer routine• 14-31

Interrupt transfer vector
See VEC
Interrupt vector• 12-11
See Device interrupt vector
number• 12-6
Interval clock• 3-6, 3-8, 3-14
interrupt service routine • 3-8, 3-9
role in device timeouts • 1-4
INVALIDATE spin lock• 3-14
INVALIDATE_TB macro• E-15
INVALID macro
replaced by INVALIDATE_TB macro• E-15
10$_AVAILABLE function • 7-9
10$_CONINTREAD function• 19-9, 19-10
10$_CONINTWRITE function• 19-9, 19-10
10$_PACKACK function • 7-9
10$_SETCHAR function• 11-9
10$_SETMODE function• 18-15
10$_TTY_PORT function• 18-14
10$_UNLOAD function • 7-9
$10650DEF macro• 19-1
$10730DEF macro• 19-1
$10750DEF macro • 19-1
$10780DEF macro• 19-1
$10790DEF macro• 19-1
$108NNDEF macro• 16-17, 19-1
$108PSDEF macro• 16-17
$108SSDEF macro• 16-16, 19-1
$109AQDEF macro• 16-17
$109CCDEF macro• 16-17, 19-1
IOC$ALLOSPT
replaced by LDR$ALLOC_PT • E-'7
IOC$ALOALTMAPN • 14-20
IOC$ALOUBAMAPN • 14-20
IOC$CANCELIO • 11-8 .to 11-9
IOC$GL_DEVLIST • 11-5
IOC$GL_DPTLIST • 12-3, 12-8
IOC$GL_IRPFL
replaced in VMS Version 5.0 • E-14
IOC$GL_LRPFL
replaced in VMS Version 5.0 • E-14
IOC$GL_MUTEX • 11-12
IOC$GL_PSFL
replaced by IOC$GQ_POSTIQ • E-14
IOC$GL_SRPFL
replaced in VMS Version 5.0 • E-14
IOC$GQ_IRPIQ • E-14
IOC$GQ_LRPIQ• E-14
IOC$GQ_SRPIQ • E-14
IOC$1NITIATE • 3-23, 4-13 to 4-15, 8-1, 10-3
IOC$10POST • 3-5

lndex-11

Index

IOC$LOADALTMAP • 14-22
IOC$LOADMBAMAP • 15-3 to 15-4
IOC$LOADUBAMAP • 14-21 to 14-22
IOC$LOADUBAMAPA • 14-22
IOC$MOVFRUSER • 16-22
IOC$MOVTOUSER • 16-22
IOC$PURGDATAP • 14-24 to 14-25
IOC$RELALTMAP • 14-26
IOC$RELCHAN • 10-2
IOC$RELDATAP • 14-25
IOC$RELMAPREG • 14-26
IOC$REQALTMAP • 14-19
IOC$REQCOM • 3-5, 3-23, 8-1, 10-3 to 10-4
error logging activities • 11-1 O
IOC$REQDATAP • 14-17
IOC$REQDATAPNW • 14-18
IOC$REQMAPREG • 14-19 to 14-20
IOC$REQPCHANL • 8-2 to 8-4
IOC$RETURN • 11-8
IOC$WFIKPCH • 4-16, 8-7
IOC$WFIRLCH • 4-16
$10DEF macro • 6-5
IOFORK macro • 3-12, 3-24, 4-17, 9-4, 10-1,
14-24
IOLOCK 10 fork lock • 3-14
IOLOCK11 fork lock • 3-14
IOLOCK8 fork lock • 3-8, 3-13
IOLOCK9 fork lock • 3-14
IOSB (1/0 status block) • 7-4, 10-2, 10-3
validating access to• 4-9
$10UV1 DEF macro• 19-1
$10UV2DEF macro • 19-1
IPL$_ASTDEL•3-2, 3-4, 3-19, 4-9
IPL$_FILSYS • 3-13
IPL$_10LOCK8 • 3-13
IPL$_10POST • 2-7, 3-2, 3-5, 4-20, 10-3, 11-7
IPL$_JIB • 3-13
IPL$_MAILBOX • 3-2, 3-8, 3-14, 9-7, 10-7
IPL$_MMG • 3-13
IPL$_POOL • 3-2
IPL$_POWER • 3-7, 8-5 to 8-6, 11-4, 12-4
IPL$_QUEUEAST • 3-2, 3-7, 3-13, 19-15, 19-18
IPL$_RESCHED • 3-2, 3-5, 3-7
IPL$_SCHED • 3-13
IPL$_SYNCH • 3-2, 3-7, 3-8
IPL$_TIMER• 3-13
IPL$_TIMERFORK • 3-2, 3-8, 10-4, 10-5
IPL (interrupt priority level)• 1-7, 3-1 to 3-12
hardware • 3-1
lowering• 3-9 to 3-12, 3-23, 8-7
raising• 3-9 to 3-12, 3-15

lndex-12

IPL (interrupt priority level) (Cont.)
relation to spin lock • 3-15
saving • 3-1 O
software • 3-2
IRP$L_BCNT • 8-2
writing• 7-6
IRP$L_MEDIA • 7-4, 10-3, 11-7
IRP$L_PID • 11-8
IRP$L_SVAPTE • 8-2
for buffered 1/0 • 7-7, 7-8
IRP$V_FUNC • 7-6, 7-8, 11-7
IRP$W_BOFF • 7-7, 7-8, 8-2
IRP$W_CHAN • 11-8
IRP$W_FUNC • 8-4
IRP$W_STS
for read function• 7-6, 7-8
for write function• 7-8
IRP (1/0 request packet)• 1-6 to 1-7
allocating• 4-9
copying to UCB • 8-2
creation • 2-3, 4-9
deallocation • 2-7
device-independent portion of• 4-9 to 4-1 O
insertion in pending-1/0 queue• 2-4, 4-13, 7-4,
8-1
insertion in postprocessing queue• 2-7
removal from pending-1/0 queue• 2-7, 4-13, 10-3
storing data in• 5-2, E-16

J
JIB$L_BYTCNT • 3-13, 7-6, 7-8, E-5
JIB$L_BYTLM •3-13, E-5
JIB Gob information block)• 3-13
JIB spin lock• 3-13
Job attached bit
See UCB$V_JOB
Job controller
sending a message to• 9-7 to 9-8
Job information block
See JIB
Job quota • E-5
byte count• 2-3, 3-13
byte limit• 3-13

K
Kernel-mode requirements • E-1

Index

Kernel stack • 8-1

L
LDR$ALLOC_PT • 16-18, E-7
Legal function bit mask• 4-11
Lexical function
F$SEARCH • 13-24
LOADALT macro• 14-10, 14-22
LOADMBA macro• 15-3, 15-13, 15-14 to 15-15
LOADUBA macro• 14-10, 14-11, 14-21
Local disk UCB extension
required for error logging• 11-9
Local processor • 1-7
Local tape UCB extension
required for error logging• 11-9
LOCK macro• 3-9, 3-1 O, E-4
Logical 1/0 function
translation from virtual function to • 2-3
Longword-aligned random-access mode • 14-3,
14-11, 14-14 to 14-15
LUN (logical unit number) • 17-2

M
Machine check• 3-14, 13-22, 19-7
condition handler• 19-7
Machine check protection block • 16-13, 16-14
Mailbox
·
of job controller• 9-7, E-7
of OPCOM process• 10-7, E-7
synchronizing access to • 3-8, 3-14
Mailbox driver• 12-5
MAILBOX spin lock• 3-14
Maintenance function• 18-15
Map register base register
See MBA$L_MAP
Map registers• 1-22, 14-3, 14-4 to 14-7, 14-15,
14-19 to 14-22
allocating permanent• 11-2, 14-20 to 14-21,
E-12
calculating the number needed• 14-19
format• 14-6 to 14-7, 14-21
invalidating• 14-7, 14-13, 14-22
loading• 14-21 to 14-22
of MBA• 15-3
of 022 bus • 14-6
of UBA • 14-6

Map registers (Cont.)
operation• 14-6 to 14-7
releasing • 10-2, 14-26
requesting• 14-19 to 14-21
Map register valid bit• 14-21
Map register wait queue• 14-19, 14-26, E-14
MASS BUS
configuration • 15-1, 15-5
1/0 address space • 19-1
1/0 database• 15-4, 15-7 to 15-8
servicing multiunit controller on • 15-2, 15-6,
15-8, 15-12, 15-14, 15-16
servicing single-unit controller on • 15-6 to 15-8,
15-11, 15-12, 15-13, 15-16
MASSBUS adapter
See MBA
MASSBUS driver
DPT for• 15-15
interrupt service routine• 15-17
start 1/0 routine • 15-13
unit initialization routine• 15-12
unsolicited interrupt service routine• 15-16
MBA$1NT • 15-15 to 15-16
MBA$L_AS • 15-5, 15-9 to 15-10, 15-11
MBA$L_BCR • 15-4, 15-5, 15-14
MBA$L_CAR • 15-5
MBA$L_CR • 15-5
MBA$L_CSR • 15-5, 15-14
MBA$L_DR • 15-5
MBA$L_ERB • 15-5, 15-12
MBA$L_MAP • 15-5
MBA$L_SMR • 15-5
MBA$L_SR • 15-5, 15-11, 15-13
MBA$L_VAR • 15-4, 15-5, 15-14, 15-15
MBA (MASSBUS adapter)• 1-11
address space • 15-4 to 15-6
data path • 15-3
functions• 15-1, 15-9 to 15-10
nexus value of • 12-5
obtaining ownership• 15-2, 15-3, 15-6 to 15-11,
15-14
registers • 15-1 to 15-6
device• 15-5, 15-12 to 15-13, 15-13
external • 15-2
internal • 15-3
map• 15-3 to 15-6
subunit number• 15-1
unit number• 12-6, 15-1, 15-12 to 15-13
$MBADEF macro • 15-4 to 15-6
MCHECK spin lock• 3-14
$MCHKDEF macro• 16-13, 16-14

lndex-13

Index

MEGA spin lock• 3-14
Memory
detecting corruption in • 13-23 to 13-27
detecting parity errors in • 14-25
Memory interconnect to VAXBI adapter• 16-1, 16-7,
16-10
ADP address• 16-1 O
Memory management resources
synchronizing access to • 3-13
MicroVAX/VAXstation 3100 systems
support for SCSI devices • 1-18
MicroVAX II
adapter logic • 14-1
MMG$GL_SBICONF • 16-8
MMG spin lock • 3-13
Modem signals
input transitions of • 18-15
sending to device• 18-13
Modify function
FDT routine for• 7-9
MSG$_CRUNSOLIC • 9-7
MSG$_DEVOFFLIN • 10-7
Multilevel device interrupt dispatching• 14-31, 14-33
to 14-36
Multiprocessing device driver
analyzing crash dumps • E-19 to E-20
incompatibility with uniprocessing driver• 12-13,
E-3
using XDELTA • 13-7, E-20
writing • E-8 to E-20
Multiprocessing environment
contrasted with uniprocessing environment• 3-11,
E-1
debugging a driver designed for• 13-28 to 13-30
MULTIPROCESSING parameter• 13-28, E-2 to
E-3, E-4
Mutex
1/0 database • 11-12

N
NBI
See Memory interconnect to VAXBI adapter
NCR 5380controller•1-18
Nexus•12-5, 12-8, 12-9, 12-10, 12-11
Node•12-5, 12-8, 12-9, 12-10, 12-11
See VAXBI node
Node ID• 16-9
Node private space • 16-5
Node space • 16-5

lndex-14

Node space (Cont.)
accessing BllC registers within • 16-5
address • 16-9
mapped by VMS • 16-8
Non-Digital-supplied SCSI class driver
See Third-party SCSI class driver
Non-direct-vector interrupt• 13-9, 14-3, 14-28,
14-29, 14-31
Nonpaged pool
allocating in initialization routine• 11-2
lookaside list • E-14
synchronizing access to• 3-14
variable region • E-14
NPR (Nonprocessor request)
See OMA transfer

0
Online bit
See UCB$V_ONLINE
Online condition
on MASSBUS • 15-10
OPCOM process
sending a message to • 10-7
ORB (object rights block)
cloned• 11-13

p
Page fault
taken within driver code • 3-5
Page table
physical address of• 16-21
Page-table entry
format • 16-20
modifying • E-15
PAT$A_NONPAGED • 13-20
PAT$A_NONPGD
replaced by PAT$A_NONPAGED • 13-20
Patch space • 13-20
PBI
See Memory interconnect to VAXBI adapter
PCB$L_ASTQFL • E-14
PCB$L_JIB • 7-6
PCB$L_PID • 11-8
PCB$V_SSRWAIT • 4-9

Index

PCB$W_ASTCNT
modifying with ADAWI instruction• E-13
PCB$W_BIOCNT • 2-7
PCB (process control block) • 3-4, 3-5, 13-13
referring to current • E-6
synchronizing access to • 3-14
Pending-1/0 queue•3-23, 4-13, 8-1, 11-7, E-14
bypassing• 7-5
synchronizing with driver internal queue• 7-5
PERFMON spin lock• 3-14
Per-Process page
locking in memory• E-16
PFN database
examining with XDELTA • 13-13 to 13-14
PFN mapping• 19-5 to 19-7
deleting a page designated for• 19-7
modifying a page designated for • 19-5
PHD$L_BIOCNT • 2-7
Physical address
format • 19-4
PIO transfer• 1-21
example • f-1 to 2-7
using buffated 1/0 in• 6-8
using 1/0 adapter resources in • 14-2
Pool checking mechanism • 13-23 to 13-27
POOLCHECK parameter• 13-23
POOL spin lock • 3-14
Poor man's lockdown • E-16 to E-17
Port• 17-1
DMA buffer• 17-2, 17-16, 17-27
examining status of• 17-17 to 17-18
Port capabilities longword• 17-13
Port command buffer
allocating• 17-11, 17-27
deallocating• 17-11, 17-28
Port driver• 17-3
See Terminal port driver
Port driver vector table • 18-4 to 18-5
address • 18-9
creating• 18-6
PORT_ABORT service routine • 18-16
PORT_CANCEL service routine• 18-17
PORT_DISCONNECT initiate routine • 18-13
PORT_DS_SET initiate routine• 18-13
PORT_FDT initiate routine• 18....:14
PORT_FORKRET initiate routine • 18-14, 18-20
PORT_MAINT initiate routine• 18-15
PORT_RESUME service routine• 18-17
PORT_SET_LINE initiate routine• 18-15
PORT_SET_MODEM initiate routine• 18-15
PORT_STARTIO initiate routine• 18-16

PORT_STOP service routine• 18-17
PORT_XOFF service routine • 18-17
PORT_XON service routine • 18-18
Position independent code • 5-1
Postprocessing
See 1/0 postprocessing
Power bit
See UCB$V_POWER
Power failure
blocking • 3-7
determining the occurrence of• 8-5
on 1/0 bus• 19-7
servicing in an initialization routine • 11-1, 11-5
servicing in port driver unit initialization routine •
18-13, 18-22
Power failure recovery procedure
device timeout forced by • 10-5
initialization performed by • 11-5
PR$_ASTLVL processor register• 3-4
PR$_SIRR processor register• 3-9
PR$_TBIA processor register• E-15
PR$_TBIS processor register• E-15
Prefetch function of UNIBUS adapter• 14-3, 14-12,
14-13
Preprocessing
See 1/0 preprocessing
Preprocessing routine
See FDT routine
Primary processor • E-2
Printer driver
description • 2-1 to 2-7
Process
quantum end event• 3-8
returning control from driver to • 4-16
Process context• 1-8, 2-4, 4-13, 7-1
returning to• 4-20
Process 1/0 channel • 11-6
assigning • 4-5
assigning to template device • 11-12
deassigning• 11-7, 11-8, 18-13
validating • 2-3, 4-5
Process quota
adjusting • 4-20
buffered 1/0 • 2-3, 2-7, 4-9
byte count• 7-8
charging • 4-9, 4-12
direct 1/0 • 4-9
Programmed 1/0
See PIO transfer
$PRTCTEND macro• 16-13, 16-14
$PRTCTINI macro• 16-13, 16-14

lndex-15

Index

PSL (processor status longword)
examining with XDELTA• 13-10
PURDPR macro• 14-24
detecting memory errors using • 14-25

Q
Q22bus•1-16
accomplishing a OMA transfer on • 14-15 to
14-16, 14-19 to 14-26
address size • 14-6
device interrupt dispatching • 14-33 to 14-36
example of driver designed for • C-1 to C-29,
D-1 to D-26
1/0 address space • 19-1, 19-4, 19-7
1/0 space • 14-4
power failure• 19-7
rules for configuring • 1-16, 14-34 to 14-35
scatter-gather map • 14-4 to 14-7
Q22 bus interface
functions • 14-1 to 14-15
obtaining resources of• 14-16
QBUS_MULT_INTR parameter• 14-34
Quantum end event • 3-8
QUEUEAST spin lock• 3-13
Queue operations
in multiprocessing environment• E-13 to E-14

R
Rank
of spin lock • 3-15
Read function
FDT routine for• 7-9
READ_SYSTIME macro• E-15
REALTIME_SPTS parameter• 19-9
Reentrant code • 5-1
Register dumping routine• 1-4, 11-10, 11-11
address • 6-4
for generic VAXBI device• 16-22
of SCSI third-party class driver• 17-21, 17-28
Registers
See BllC registers, Device registers, General
purpose registers, Map registers
REI instruction
role in AST delivery • 3-4
Reinitialization table • 6-2, 12-8
RELALT macro• 14-26

lndex-16

RELCHAN macro• 10-2, 15-15
RELDPR macro • 14-25
RELMPR macro • 14-26
REQALT macro• 14-10, 14-19
REQCOM macro• 10-3, 17-28
required for error logging• 11-10
REQDPR macro• 14-11, 14-17
REQMPR macro• 14-10, 14-11, 14-19
REQPCHAN macro• 3-27, 8-2 to 8-4, 15-6, 15-14
REQSCHAN macro • 15-6, 15-14
Request sense key• 17-18
Resource wait flag
See PCB$V_SSRWAIT
Resource wait mode • 4-9
Resource wait queue • 3-25 to 3-27, E-14
Retry count • 10-6
RL01 driver• C-1 to C-29
RL02 driver • C-1 to C-29
RL 11 driver • C-1 to C-29
RSB instruction• 7-4

s
SAVIPL macro• 3-10
SBI (synchronous backplane interconnect) • 1-11
UNIBUS interlock sequence to• 14-10
SBICONF array• 16-8
Scatter-gather map • 14-4
See also Map registers
SCB (system control block)• 16-1 O
SCDRP$L_ABCNT • 17-15
SCDRP$L_BCNT • 17-15, 17-19
SCDRP$L_CMD_PTR • 17-11
SCDRP$L_DISCON_TIMEOUT• 17-11, 17-12
SCDRP$L_DMA_TIMEOUT • 17-11, 17-12
SCDRP$L_IRP • 17-27
SCDRP$L_MEDIA • 17-15
SCDRP$L_PAD_COUNT • 17-15
SCDRP$L_SCSl_FLAGS • 17-15, 17-16, 17-27
SCDRP$L_SPTE_SVAPTE • 17-16
SCDRP$L_STS_PTR • 17-11, 17-18
SCDRP$L_SVAPTE • 17-15
SCDRP$L_SVA_USER • 17-15, 17-16
SCDRP$L_TRANS_CNT • 17-19
SCDRP$V_BUFFER_MAPPED • 17-16, 17-27
SCDRP$V_SOBUF • 17-16, 17-27
SCDRP$W_BOFF • 17-15
SCDRP$W_FUNC • 17-15
SCDRP$W_MAPREG • 17-17

Index

SCDRP$W_NUMREG • 17-16
SCDRP$W_STS • 17-15, 17-16
SCDRP (SCSI class driver request packet) • 17-7
allocating• 17-27
deallocating • 17-28
defining fields of• 17-24
initializing• 17-15 to 17-16, 17-27
$SCDRPDEF macro• 17-24
SCOT (SCSI connection descriptor table)• 17-7
SCH$GL_CURPCB
replaced in VMS Version 5.0 • E-6
SCH$GL_PCBVEC • 13-13
SCH$QAST • 3-4
SCH$RESCHED • 3-7
SCHED spin lock• 3-4, 3-8, 3-14
Scheduler
blocking activity of • 3-5
synchronization of• 3-7
SCSI
hardware considerations • 1-18
SCSI (Small Computer System Interface)
definition • 17-1
SCSI bus
VAX systems concepts• 17-1
SCSI bus analyzer• 17-32
SCSI class driver
See Class driver, Disk class driver, Generic SCSI
class driver, Tape class driver, Template class
driver, Third-party SCSI class driver
SCSI class/port architecture• 17-2 to 17-5
summary of 1/0 request servicing• 17-22 to
17-24
SCSI command
controlling the number of retries• 17-13
disabling retry• 17-12
examining status of• 17-17 to 17-19, 17-27
preparing to issue• 17-10 to 17-13
sending to SCSI device• 17-11
setting disconnect timeout for• 17-11, 17-12
setting OMA timeout for• 17-11, 17-12
setting phase change timeout for • 17-11 , 17-12
size of• 17-11
terminating• 17-28
SCSI command byte
buffering• 17-11, 17-27
SCSI command descriptor block
creating• 17-11
initializing pointer to• 17-11
SCSI controller
NCR 5380•1-18
Sii • 1-19

SCSI device
connecting to• 17-9
SCSI device ID• 17-2
SCSI device UCB• 17-8
extending • 17-24
SCSI ID• 17-2
SCSI port driver
See Port driver
SCSI port ID• 17-1
SCSI port interface
See SPI
SCSI port UCB• 17-8
SCSI status byte
examining• 17-18
initializing• 17-11
servicing CHECK CONDITION status• 17-18
SCSl_NOAUTO system parameter• 17-31
SCU/XMI bus
1/0 address space • 16-5
SCU/XMI bus architecture• 1-16
SDA
See System Dump Analyzer
SDA current process• E-19
$SECDEF macro • 19-6
Secondary bootstrap program (SYSBOOT) • 13-21
Secondary controller data channel • 15-14, 15-15
Seek operation • 8-6
overlapping with data transfer• 8-2
Selected map register
See MBA$L_SMR
Self-test status• 16-25
Sense device characteristics function• 7-9
Sense device mode function• 7-9
Set device characteristics function• 7-9
Set device mode function• 7-9
SETI PL macro• 3-9, 3-10, E-4
replacing with spin lock synchronization macro •
E-13
SET PROCESS command • E-19
SHOW SPINLOCKS command• E-17
Sii controller• 1-19
SIAR (software interrupt request register) • 3-9
Small Computer System Interface
See SCSI
SMP$ACQNOIPL • 13-29, E-18
SMP$ACQUIRE • 13-28, 13-29, E-18
SMP$ACQUIREL • 13-28, 13-29, E-18
SMP$AR_SPNLKVEC • 3-13
SMP$GL_FLAGS • 12-13, E-3
SMP$RELEASE • 13-28, 13-29, E-18
SMP$RELEASEL • 13-28, 13-29, E-18

lndex-17

Index

SMP$RESTORE • 13-28, 13-29, E-18
SMP$RESTOREL • 13-28, 13-29, E-18
SMP$V_UNMOD_DRIVER • 12-13, E-3
SOFTINT macro • 3-10
Software timer interrupt service routine • 3-8, 1Q-4
Solicited interrupt
See Device interrupt
SPOT (SCSI port descriptor table) • 17-7
creation of • 17-26
SP1$ABORT_COMMAND macro• 17-6, 17-28
SPl$ALLOCATE_COMMAND_BUFFER macro•
17-6, 17-11, 17-27
SPl$CONNECT macro• 17-6, 17-10, 17-26, 17-29
SPl$DEALLOCATE_COMMAND_BUFFER macro•
17-6, 17-11, 17-28
SPl$DISCONNECT macro• 17-6
SP1$FINISH_COMMAND macro• 17-29
SPl$GET_CONNECTION_CHAR macro• 17-6
SPl$MAP_BUFFER macro• 17-6, 17-16 to 17-17,
17-27
SP1$RECEIVE_BYTES macro• 17-29
SPl$RELEASE_BUS macro • 17-29
SP1$RESET macro • 17-6
SPl$SEND_BYTES macro• 17-29
SPl$SEND_COMMAND macro• 17-6, 17-11, 17-17,
17-27
SPl$SENSE_PHASE macro• 17-29
SP1$SET_CONNECTION_CHAR macro• 17-6,
17-12, 17-13, 17-14, 17-27
SP1$SET_PHASE macro• 17-29
SPl$UNMAP_BUFFER macro• 17-6, 17-17
SPI (SCSI port interface)• 17-5 to 17-6
calling protocol for• 17-6
extensions to• 17-29 to 17-30
Spin lock• 1-7, 3-3, 3-12 to 3-17
See also Device lock, Fork lock, SPL, Spin lock
index, Spin wait
acquisition IPL•3-11, 3-15, E-17, E-20
acquisition PC list• E-17
address • E-20
dynamic • 3-13
multiple acquisition of • 3-15, E-20
name• E-20
obtaining• 3-1 O
ownership• 3-15, 13-30, E-20
rank• 3-13 to 3-14, 3-15, 3-17, E-17, E-20
releasing • 3-1 0
static • 3-13
status • E-20
system • 3-13
Spin lock index• 3-13, 3-13 to 3-14, E-20

lndex-18

Spin lock IPL vector
See SMP$AR_SPNLKVEC
Spin lock synchronization macros• E-4, E-13
See also DEVICELOCK, DEVICEUNLOCK,
FORKLOCK, FORKUNLOCK, LOCK, and
UNLOCK
Spin wait• 3-15
SPL$B_IPL • 3-9, E-18
SPL$B_RANK • E-18
SPL$L_BUSY_WAITS • E-17
SPL$L_OWN_PC_VEC • E-17
SPL$Q_ACQ_COUNT• E-17
SPLACQERR bugcheck • 13-28, 13-30, E-18
$SPLCODDEF macro • E-8
SPLIPLHIGH bugcheck • 13-28, E-18
SPLIPLLOW bugcheck • 13-28, E-18
SPLRELERR bugcheck • 13-29, 13-30, E-18
SPLRSTERR bugcheck • 13-29, 13-30, E-18
SS$_ABORT • 10-6
SS$_CANCEL • 11-7
SS$_EXQUOTA • E-6
SS$_NONSMPDRV • E-4
Stack
device driver use of • 8-1
using for temporary storage • 5-3
Start 1/0 routine • 1-3
address • 2-4, 6-4
context • 4-15, 8-1 to 8-2
for connect to interrupt facility• 19-10, 19-15 to
19-16
for MASSBUS device • 15-13
functions • 4-15 to 4-16
of CONINTERR.EXE • 19-13
of third-party SCSI class driver• 17-27 to 17-28
reactivating • 4-18
register usage • 8-1
suspending • 4-16
synchronization requirements • 3-6, 3-22, 8-5,
E-9 to E-11
transferring control to • 4-13 to 4-15, 8-1 , 10-3
writing• 8-1 to 8-7
Static spin lock· 3-13
Status
See SCSI command, Port, SCSI status byte
Status register
See CSR, MBA$L_SR
Streamlined synchronization image • 13-28
loading• E-2
SWl$GL_FQFL
replaced by CPU$Q_SWIQFL • E-14

Index

Synchronization image
full-checking• 13-28, E-2, E-17 to E-18
streamlined• 13-28, E-2
uniprocessing • 13-28, E-2
Synchronization techniques• 1-7, 3-1 to 3-27
See also IPL, Spin lock, Fork queue, and
Resource wait queue
Synchronous backplane interconnect
See SBI
Synchronous SCSI data transfer mode
enabling• 17-13
setting REQ-ACK offset• 17-13
setting transfer period • 17-13
SYS$AR_JOBCTLMB • 9-7, E-7
SYS$AR_OPRMBX • 10-7, E-7
SYS$ASSIGN • 1-6, 2-3, 4-5, 19-9
SYS$CANCEL • 1-4, 11-6, 11-8, 18-17, 19-19
SYS$CRMPSC • 19-5 to 19-6, 19-8
SYS$DALLOC • 11-8, 18-17
SYS$DASSGN • 11-7, 11-8, 18-17
SYS$GL_JOBCTLMB
replaced by SYS$AR_JOBCTLMB • E-7
SYS$GL_OPRMBX
replaced by SYS$AR_OPRMBX • E-7
SYS$LOADABLE_IMAGES directory• E-8
SYS$QIO • 1-1, 2-2 to 2-4, 4-1 to 4-15
for connect to interrupt facility• 19-9, 19-9 to
19-13
SYS$QIOW • 2-7
SYS$SYNCH • 2-7
SYSGEN
See System Generation Utility
System configuration • 12-11
System context • 1-8
System control block
See SCB
System control unit (SCU) • 1-16
System Dump Analyzer (SDA) • 13-22
current process • E-19
SET CPU command • E-19
SHOW CPU command• E-19
SHOW CRASH command• E-19
SHOW SPINLOCKS command • E-20
using to debug device driver• 13-29
System failure
inducing with XDELTA • 13-21
System Generation Utility (SYSGEN) • 12-2 to
12-23
AUTOCONFIGURE command• 11-4, 12-13 to
12-23
configuring SCSI devices• 17-30

System Generation Utility (SYSGEN) (Cont.)
CONNECT command• 11-4, 12-2, 12-3 to 12-7,
E-3
/ADAPTER qualifier• 12-5
/ADPUNIT qualifier• 12-6
/CSR qualifier• 12-5
/CSR_OFFSET qualifier• 12-6
/DRIVERNAME qualifier• 12-6
/MAXUNITS qualifier• 12-6
/NOADAPTER qualifier • 12-5
/NUMVEC qualifier• 12-6, 14-31, 14-32
NECTOR qualifier • 12-6
NECTOR_OFFSET qualifier• 12-6
device table • 12-15, 12-23
LOAD command • 11-4, 12-2 to 12-3, E-3
loading a VAXBI device driver using• 16-23
RELOAD command• 11-4, 12-7 to 12-8
SHOW/ADAPTER command• 12-8
SHOW/Bl command • 12-9
SHOW/BUS command • 12-10
SHOW/CONFIGURATION command• 12-11 to
12-12
SHOW/DEVICE command • 12-12
SHOW/XMI command• 12-11
System page
locking in memory • E-16
System page-table entry
allocating• 16-18, E-7
allocating permanent • 6-2
System service dispatcher
role in servicing 1/0 request• 4-1
System spin lock • 3-13
System time • 3-8, 3-14, E-13
reading • E-15

T
Tape class driver
disabling the loading of• 17-31
Target• 17-2
enabling selection from • 17-28 to 17-30
Target mode
See Asynchronous event notification
Template class driver• 17-9
listing of • B-1 to B-35
Template device • 11-12
Template for a device driver• A-1 to A-10
Terminal class driver • 18-1 to 18-23
binding to port driver• 18-9 to 18-10
service routines • 18-19 to 18-23

lndex-19

Index

Terminal class driver (Cont.)

Timeout handling routine (Cont.)

structure• 18-7
Terminal port driver• 18-1 to 18-23
aborting output activity. in • 18-16
binding to class driver• 18-9 to 18-1 O
canceling 1/0 request in• 18-17
detecting an error on terminal line in • 18-22
disconnecting a process from a terminal in• 18-19
forking in • 18-14, 18-20
implementing modem functions in • 18-15
initiate routines • 18-13 to 18-16
managing data set state transitions in • 18-20
obtaining characters for output in • 18-20
passing input characters to class driver from •
18-21
resuming stopped output in • 18-17
service routines • 18-16 to 18-18
starting output on an inactive line in • 18-16
startup routines• 18-12 to 18-13
stopping output in• 18-17
structure• 18-7
using input flow control character in• 18-17,
18-18
Terminal UCB extension • 18-2 to 18-3
initializing • 18-22
Third-party SCSI class driver
cancel-1/0 routine of • 17-28
components• 17-24 to 17-28
data definitions• 17-24
debugging• 17-31 to 17-43
driver prologue table • 17-25
error logging • 17-20 to 17-22
loading• 17-30
maintaining local context of• 17-19 to 17-20
receiving notification of asynchronous events on
target • 17-28 to 17-30
register dumping routine of• 17-21, 17-28
start-1/0 routine of• 17-27 to 17-28
unit initialization routine of• 17-26 to 17-27
writing• 17-1 to 17-43
Timeout
caused by power failure recovery procedure • 10-5
disabling• 4-17, 10-1
for SCSI device• 17-11, 17-12
logging• 10-6, 11-10
Timeout enable bit
See UCB$V_TIM
Timeout handling routine • 1-4, 3-8, 9-4, 10-4 to
10-7, 11-8
aborting an 1/0 request in • 10-6
address • 8-7, 10-1
context • 10-4

functions • 10-5
retrying an 1/0 operation in • 10-5 to 10-6
synchronization requirements • 3-22, E-12
Timeout interval
specifying • 10-4
Timer
See Software timer, Interval clock
Timer queue • 3-14, E-13
TIMER spin lock• 3-8, 3-13, E-13
TQE (timer queue element)
calling a driver from • E-15
expiration time • 3-8
Translation buffer
invalidating • E-15
TTDRIVER.EXE • 18-1
TTY$V_PC_NOTIME • 18-16
TTY$V_PC_PORTFDT • 18-14
TTY$V_ TP_ABORT• 18-18
$TTYDEFS macro • 18-2
$TTYMACS macro • 18-12
$TTYMDMDEF macro• 18-20
$TTYMODEMDEF macro• 18-13

lndex-20

u
UBA (UNIBUS adapter)• 1-11
See also UNIBUS adapter
UBI (UNIBUS interface)• 1-11
See also UNIBUS adapter
UCB$B_DEVCLASS • 6-3, 17-21, 17-25
UCB$B_DEVTYPE • 6-3, 17-21, 17-25
UCB$B_DIPL • 3-6, 6-2, 10-4
UCB$B_ERTCNT • 10-3
UCB$B_FLCK • 3-6, 6-2, 10-1
initializing • E-8
UCB$B_SLAVE • 15-12 to 15-13
UCB$B_SLAVE+1•15-12 to 15-13
UCB$B_TP_STAT•18-18
UCB$8_TT_DEPARI • 18-22
UCB$8_TT_DETYPE • 18-22
UCB$8_TT_MAINT • 18-15
UC8$B_TT_OUTYPE • 18-16, 18-21, 18-22, 18-23
UC8$8_TT_PARITY • 18-15, 18-22
UCB$L_CRB • 11-5, 15-13
UCB$L_DDB • 4-8
UCB$L_DDT • 18-9
UC8$L_DEVCHAR • 6-3, 11-9
UC8$L_DLCK • 3-22

Index

UCB$L_DUETIM •4-16, 8-7, 10-5
UCB$L_EMB • 10-3
UCB$L_FPC • 4-16, 4-17, 9-4, 10-1 , 10-4
UCB$L_FR3 • 4-16, 4-17 9-4, 10-1, 10-4
UCB$L_FR4 • 4-16, 4-17, 9-4, 10-1, 10-4
UCB$L_IOQFL• 10-3, E-14
UCB$L_IRP • 4-5, 10-3
UCB$L_LINK • 11-5
UCB$L_MAXBCNT • 17-14, 17-26
UCB$L_PDT • 17-26
UCB$L_SCDT • 17-26
UCB$L_STS • 2-4, 8-5, 8-7
UCB$L_SVAPTE •4-5, 8-2, 14-22, 15-3, 15-14,
16-19
UCB$L_TT_CLASS• 18-9
UCB$L_TT_GETNXT • 18-9
UCB$L_TT_LOGUCB • 18-22
UCB$L_TT_OUTADR • 18-16, 18-21, 18-22
UCB$L_TT_PORT• 18-9
UCB$L_TT_PUTNXT • 18-9
UCB$L_TT_RTIMOU • 18-22
UCB$L_TT_WFLINK • 18-22
UCB$Q_DEVDEPEND•6-3
UCB$V_BSY • 2-4, 4-5, 7-5, 10-4, 11-8
UCB$V_CANCEL• 10-6, 10-7, 11-8
UCB$V_DELMBX • 18-13
UCB$V_ERLOGIP • 10-3, 11-10
UCB$V_INT • 8-7, 9-3, 9-7, 10-4, 15-10, 18-16
UCB$V_JOB• 9-6, 9-7, 9-8
UCB$V_ONLINE • 9-8, 11-2, 11-3, 16-13
UCB$V_POWER • 8-5, 10-5, 11-1, 17-26, 18-13
UCB$V_TIM •8-7, 10-1, 10-4
UCB$V_ TIMOUT • 10-4
UCB$V_VALID • 9-8
UCB$W_BCNT • 8-2, 14-19, 14-22, 15-3, 15-4,
15-14, 16-19
UCB$W_BOFF • 8-2, 14-19, 14-21, 14-22, 14-23,
15-3, 15-4, 15-14, 16-19
UCB$W_DEVBUFSIZ • 6-3
UCB$W_DEVSTS • 10-3
UCB$W_ERRCNT • 11-10
UCB$W_REFC • 9-6, 9-7, 11-6, 11-7
UCB$W_STS • 17-26
UCB$W_TT_CURSOR • 18-22
UCB$W_TT_DESPEE • 18-22
UCB$W_TT_HOLD • 18-22
UCB$W_TT_OUTLEN • 18-16, 18-21, 18-22
UCB$W_TT_PRTCTL• 18-14, 18-16
UCB$W_TT_SPEED • 18-15, 18-22
UCB$W_UNIT• 15-12
UCB (unit control block)• 1-5, 3-5, 4-5
I

UCB (unit control block) (Cont.)
See also SCSI device UCB, SCSI port UCB
address• 8-7, 11-5
as fork block• 8-7
creation• 11-4, 12-4, 12-21, 15-7
error log extension • 11-9
initializing• 11-3
local disk extension • 11-9
local tape extension • 11-9
number to be created • 6-2
storing data in• 4-5, 5-2
synchronizing access to • 2-4, 3-5, 3-6, 3-16
terminal extension • 18-2 to 18-3
UNIBUS
accomplishing a DMA transfer on• 14-15 to
14-26
address size • 14-6
example of driver designed for• C-1 to C-29,
D-1 to D-26
example of read operation • 14-12 to 14-13,
14-14
example of write operation • 14-12, 14-15
1/0 address space • 19-1, 19-4, 19-7
1/0 space • 14-4
power failure• 19-7
UNIBUS adapter• 1-11,.1-13
error interrupt from• 13-22, 19-7
functions• 14-1 to 14-15
interrupt service routine • 14-29
nexus value of • 12-5
obtaining resources of • 14-16
prefetch function• 14-12, 14-13
registers • 14-15
scatter-gather map • 14-4 to 14-7
synchronizing access to • 14-2
Uniprocessing device driver
converting to multiprocessing device driver• E-8
to E-20
incompatibility with multiprocessing device driver •
12-13, E-3
Uniprocessing environment
contrasted with multiprocessing environment•
3-11, E-1
Uniprocessing synchronization image • 13-28
loading• E-2
Unit control block
See UCB
Unit control block (UCB)
See SCSI device UCB, SCSI port UCB
Unit delivery routine
address • 6-2, 12-21
context • 12-21

lndex-21

Index

Unit delivery routine (Cont.)

VAXBI node (Cont.)

functions• 12-21
output • 12-21
Unit initialization routine• 1-3, 11-1 to 11-6, 12-4
address • 4-6, 6-3, 6-4, 11-1, 14-30
allocating controller data channel in • 8-4, 10-2
allocating permanent buffered data path in• 14-18
allocating permanent map registers in • 14-20 to
14-21
context • 11-1 , 11-3
for connect to interrupt facility• 19-10, 19-15
for generic VAXBI device• 16-12, 16-22
forking in • 3-24, 11-6
for MASSBUS device • 11-5, 15-12 to 15-13
for terminal port driver• 18-9, 18-12
functions • 11-3
input• 11-3
of CONINTERR.EXE • 19-15
of third-party SCSI class driver• 17-26 to 17-27
synchronization requirements • E-11 to E-12
UNLOCK macro• 3-10, E-4
Unsolicited interrupt

enabling error interrupts from• 16-16
mapping window space of• 16-16 to 16-18
setting interrupt destination of • 16-15
setting interrupt vector for• 16-15
VAXBl-to-UNIBUS adapter

See Device interrupt
Unsolicited interrupt service routine• 9-5, 15-16
address• 6-4
User interface CSR space
enabling interrupts from • 16-16

v
VAX 9000
bus architecture• 1-16
hardware • 1-16
1/0 address space • 16-5
VAXBI
displaying bus assignments • 12-1 O
displaying mapped addresses • 12-9
VAXBI bus• 1-13
address • 16-2 to 16-5
arbitration mode of • 16-25
errors • 16-26
1/0 address space• 16-2, 16-17, 19-1
master of• 16-10
memory space • 16-2
VAXBI node
See also Generic VAXBI device, Node ID
definition • 16-1
determining self-test status of• 16-13
enabling BllC options on• 16-16

lndex-22

See DWBUA or DWMUA
VAX MACRO instructions
as used in device driver • 5-1 to 5-5
VAXstation 3520/3540 system
support for SCSI devices• 1-18, 1-19
VEC$B_DATAPATH • 14-17, 14-18, 14-21, 14-25
VEC$B_NUMREG • 14-20
VEC$L_IDB • 4-6, 15-13
VEC$L_INITIAL • 4-6, 12-4
VEC$L_ISR • 4-6, E-5
VEC$L_RTINTD • 14-34, 14-35
VEC$L_UNITINIT • 4-6, 12-4
VEC$V_LWAE • 14-15, 14-21
VEC$V_MAPLOCK • 14-20
VEC$V_PATHLOCK • 14-17, 14-18
VEC$W_MAPALT • 14-21, 14-23
VEC$W_MAPREG • 14-20, 14-22
VEC$W_NUMALT • 14-21
VEC (interrupt transfer vector) • 14-29, 14-30, 14-30
to 14-33
initializing• 14-31
$VECEND macro • 18-6
$VECINI macro• 18-6
$VEC macro • 18-6
VECTAB
See Adapter dispatch table
Vector
fixed space • 12-14
floating space • 12-14
Vector jump table
See Adapter dispatch table
VIRTCONS spin lock• 3-14
Virtual address register
See MBA$L_VAR
Virtual 1/0 function
translation to logical function from • 2-3
Volume valid bit
See UCB$V_VALID

w
Wait for interrupt macro
See WFIKPCH macro, WFIRLCH macro

Index

WCB (window control block)• 4-1 O
WFIKPCH macro•4-16, 8-5, 8-6, 10-7, 15-14,
E-10
WFIRLCH macro• 4-16, 8-5, 8-6
Window control block
See WCB
Window space • 16-5
mapping• 16-16 to 16-18
starting address• 16-17
Word count register • 14-23
Write function
FDT routine for• 7-9

x
XADRIVER.MAR • D-1 to D-26
XDELTA
See Delta/XDelta Utility
XDELTA entry IPL• 3-9
XMI
displaying mapped addresses • 12-11
XMI bus
memory space • 16-5

lndex-23

How to Order Additional Documentation

Technical Support
If you need help deciding which documentation best meets your needs, call 800-343-4040 before placing
your electronic, telephone, or direct mail order.

Electronic Orders
To place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using a 1200- or 2400-baud

modem. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825).

Telephone and Direct Mail Orders
Your Location

Call

Contact

Continental USA,
Alaska, or Hawaii

800-DIGITAL

Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire 03061

Puerto Rico

809-754-7575

Local Digital subsidiary

Canada

800-267-6215

Digital Equipment of Canada
Attn: DECdirect Operations KA02/2
P.O. Box 13000
100 Herzberg Road
Kanata, Ontario, Canada K2K 2A6

International

Local Digital subsidiary or
approved distributor

Internal 1

USASSB Order Processing - WMO/E15
or
U.S. Area Software Supply Business
Digital Equipment Corporation
Westminster, Massachusetts 01473

1For internal orders, you must submit an Internal Software Order Form (EN-01740-07).

Reader's Comments

VMS Device Support
Manual
AA-PBPWA-TE

Please use this postage-paid form to comment on this manual. If you require a written reply to a software
problem and are eligible to receive one under Software Performance Report (SPR) service, submit your
comments on an SPR form.
Thank you for your assistance.

I rate this manual's:
Accuracy (software works as manual says)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Index (ability to find topic)
Page layout (easy to find information)

Excellent

Good

Fair

Poor

D
D
D
D
D
D
D
D

I would like to see more/less

What I like best about this manual is

What I like least about this manual is

I found the following errors in this manual:
Page

Description

Additional comments or suggestions to improve this manual:

I am using Version ___ of the software this manual describes.

Name/Title

Dept.

Company

Date

Mailing Address
Phone

- Do Not Tear - Fold Here and Tape

-------------------[lllr--------------No Postage

~nmnoma™

~:~=i~=~y
in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

DIGIT AL EQUIPMENT CORPORATION
Corporate User Publications-Spit Brook
ZK01-3/J35 110 SPIT BROOK ROAD
NASHUA, NH 03062-9987

111 ..... 11.11 .... 11 .... 1.11.1 .. 1.1 .. 1.. 1.1 ... 1.11 .. 1
- Do Not Tear - Fold Here - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

I
I
I
I
I