Digital PDFs

AA-2600D-TC

May 1979

164 pages

Original

6.4MB

Document:	RSX-11M Guide to Writing an I/O Driver Version 3.2
Order Number:	AA-2600D-TC
Revision:	0
Pages:	164
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V3.2_Jun79/3B_ProgramDevelopment/AA-2600D-TC_RSX-11M_V3.2_Guide_To_Writing_An_IO_Driver_197905.pdf

OCR Text

'-"i

RSX-11M
Guide to Writing an 1/0 Driver
Order No. AA-26000-TC ·
and
Update Notice No. 1 (AD-2600D-T1)

RSX-11 M Version 3.2

[

To order additional copies of this document, contact the Software Distribution
Center, Digital Equipment Corporation, Maynard, Massachusetts 01754

dig1ital equipment corporation · maynard, massachusetts

First Printing, April 1975
Revised:
September 1975
November 1976
December 1977
Updated:
May 1979
The information in this document is subject to change without notice
and should not be construed as a conuuitment by Digital Equipment
Corporation. Digital Equipment Corporation assumes no responsibility
for any errors that may appear in this document.
The software described in this documE~nt is furnished under a license
and may only be used or copied 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 or its affiliated companies.

1975, 1976, 1977, 1979 by Digital Equipment Corporation

The postage-prepaid READER'S COMMENTS form on the last page of this
document requests the user's critical evaluation to assist us in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:

DIGITAL
DEC
PDP
DEC US
UNIBUS
COMPUTER LABS
COMTEX
DDT
DECCOMM
ASSIST-11
VAX
DECnet
DATAT RIEVE

DECsysteim-10
DECtape
DIBOL
EDUSYSTEM
FLIP CHIP
FOCAL
INDAC
LAB-8
DECSYSTEM-20
RTS-8
VMS

IAS
TRAX

4/80-14

MASS BUS
OMNIBUS
OS/8
PHA
RSTS
RSX
TYPESET-8
TYPESET-11
TMS-11
ITPS-10
SBI
PDT

CONTENTS
Page

vii

PREFACE
CHAPTER

CHAPTER

INTRODUCTION TO I/O DRIVERS

1-1

1.1
1. 2

RESIDENT AND LOADABLE DRIVERS
FUNCTION OF AN I/O DRIVER

1-1
1-1

THE RSX-llM I/O SYSTEM--PHILOSOPHY AND
STRUCTURE
I/O PHILOSOPHY
2.1
2. 2
STRUCTURE
2.2.1
I/O Hierarchy
2.2.1.1
FCS/RMS
2.2.1.2
QIO
Executive I/O Processing
2.2.1.3
2.2.2
Role of I/O Driver in RSX-llM
2.:2.2.1
Device Interrupt
I/O Initiator
2.2.2.2
2.2.2.3
Device Timeout
2.2.2.4
Cancel I/O
2.2.2.5
Power Failure
2.2.2.6
Summary--Role of an I/O Driver
2.3
DATA STRUCTURES
The Device Control Block (DCB)
2.3.1
2.3.2
The Unit Control Block (UCB)
The Status Control Block (SCB)
2.3.3
2.3.3.l
Interrelation of the I/O Control Blocks
2.3.4
The I/O Packet
2.3.5
The I/O Queue
2 • .3. 6
The Fork List
2.3.7
The Device Interrupt Vector
2.4
EXECUTIVE SERVICES
2.4.l
Pre-Driver Initiation Processing
2.4.2
Post-Driver Initiation Services
Interrupt Save ($INTSV)
2.4.2.1
Get Packet ($GTPKT)
2.4.2.2
Create Fork Process ($FORK)
2.4.2.3
2.4.2.4
I/O Done ($!ODON or $IOALT)
2 •.5
PROGRAMMING STANDARDS
Process-Like Characteristics of a Driver
2.5.l
2.5.2
Programming Conventions
2.5.3
Programming Protocol
Processing at Priority 7 with Interrupts
2.5.3.1
Locked Out
Processing at the Priority of the
2.5.3.2
Interrupting Source
Processing at Fork Level
2.5.3.3
Programming Protocol Summary
2.5.3.4
FLOW OF AN I/O REQUEST
2.6
DATA STRUCTURES AND THEIR INTERRELATIONSHIPS
2.7
Data Structures Summary
2.7.l
3

INCORPORATING USER-·WRITTEN DRIVERS INTO
RSX-llM

iii

2-1
2-1
2-1
2-1
2-1
2-2
2-3
2-3
2-3
2-4
2-4
2-4
2-4
2-4
2-5
2-5
2-6
2-6
2-6
2-8
2-8
2-9
2-9
2-10
2-10
2-11
2-11
2-11
2-12
2-12
2-12
2-13
2-13
2-13
2-14
2-14
2-15
2-15
2-15
2~11

2-20
3-1

May 1979

CONTENTS

Page
OVERVIEW OF USER-WRITTEN DRIVERS
Overview of User-Written Code
Overview of User-Written Driver Data Bases
USER-WRITTEN RESIDENT DRIVERS
Creating the Data Base for a Resident Driver
Incorporating a Resident Driver
3;. 3
USER-WRITTEN LOADABl~E DRIVERS
Creating the Data Base for a Loadable Driver
3.3.1
Assembling a Loadable Driver and Its Data
3.3.2
Base
Adding the Driver and Its Data Base to the
3.3.3
System Library
Task-Building a Loadable Driver
3.3.4
Task-Building a Loadable Driver on a
3.3.4.1
Mapped System
Task-Building a Loadable Driver on a
3.3.4.2
Unmapped System
Loading a User-Written Loadable Driver
3.3.5
DRIVER DEBUGGING
3.4
Debugging Aids
3.4.1
3.4.1.1
Executive Stack and Register Dump Routine
3.4.1.2
XDT - The Executbre Debugging Tool
3.4.1.3
Panic Dump
3.4.1.3.1 Using PANIC on Processors with Console Switch
3.4.1.3.2 Using PANIC on Processors Without Console
Switch
3.1
3 .1.1
3 .1. 2
3.2
3.2.l
3.2.2

3.4.1.3.3
3.4.1.4
3.4.2.
3.4.2.1
3.4.2.2
3.4.3
3.4.3.1
3.4.3.2
3.4.3.3
3.4.3.4
3.4.4
3.4.4.1
3.4.4.2
CHAPTER

Sample Output from Panic Dump
Crash Dump Analysis Support Routine
Fault Isolation
Immediate Servicing
Pertinent Fault Isolation Data
Fault Tracing
Tracing Faults Using the Executive Stack
and Register Dump
Tracing Faults When the Processor Halts
Without Display
Tracing Faults After an Unintended Loop
Additional Hints for Tracing Faults
Rebuilding and Reincorporating a Driver
Rebuilding and Reincorporating a Resident
Driver
Rebuilding and Reincorporating a Loadable
Driver

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS

DATA STRUCTURES
4.1
The I/O Packet
4 .1.1
I/O Packet Details
4.1.1.1
The QIO Directive Parameter Block (DPB)
4.1.1.2
4 .1. 2
The Device Control Block (DCB)
4.1.2.1
DCB Details
4.1.2.2
Establishing I/O Function Masks
4 .1. 3
The Status Control Block (SCB)
4.1.3.1
SCB Details
The Unit Control Block (UCB)
4 .1.4
4.1.4.1
UCB Details
4 .1. 5
The Device Interrupt Vector

3-1
3-2
3-3
3-6
3-6
3-6
3-8
3-9
3-10
3-10
3-10
3-10
3-12
3-12
3-12
3-13
3-13
3-14
3-16
3-16
3-16
3-17
3-17
3-18
3-18
3-19
3-20
3-22
3-23
3-24
3-24
3-25
3-25
3-27
4-1
4-1
4-2
4-2
4-6
4-7
4-8
4-14
4-15
4-16
4-19
4-19
4-26

May 1979

CONTENTS
Page

CHA.PTER

CH.A.PTER

4.2
4.3
4.3.1

MULTICONTROLLER DRIVERS
THE INTSV$ MACRO
Format

4-27
4-28
4-29

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS

5-1

5.1
5.2
5.3

SYSTEM-STATE REGISTER CONVENTIONS
CONDITIONAL ROUTINES
SERVICE CALLS

5-1
5-1
5-1

INCLUDING A USER-WRITTEN DRIVER--TWO EXAMPLES

6-1

6.1
6.2
6.2.1
6.2.2
6.3

DEVICE DESCRIPTION
DATA BASE AND DRIVER SOURCE
The Data Base
Driver Code
HANDLING SPECIAL USER BUFFERS

6-1
6-2
6-2
6-4
6-8

DEVELOPMENT OF THE ADDRESS DOUBLEWORD

A-1

INTRODUCTION
CREATING THE ADDRESS DOUBLEWORD

A-1
A-1

PDP-11/70 DRIVERS FOR NPR DEVICES

B-1

CALLING $STMAP AND $MPUBM OR $STMP1 AND $MPUB1
Allocating a Mapping Register Assignment
Block
Calling $STMAP or $STMP1
Calling $MPUBM or $MPUB1
CALLING $ASUMR AND $DEUMR
STATICALLY ALLOCATING UMRs DURING SYSTEM
GENERATION

B-1

APPENDIX A
A. l
A.2

APPENDIX B
B.l
B.1.1
B. l. 2
B. l. 3
B.2
B.3

APPENDIX C

SYSTEM DATA STRUCTURES AND SYMBOLIC
DEFINITIONS

INDEX

B-2
B-2
B-2
B-3
B-3
C-1

Index-1
FIGURES

Figure

2-1
2-2
2-3
2-4
2-5
3-1
3-2
3-3
3-4
3-5
4-1
4-2
4-3
4-4
4-5
4-6

I/O Control Flow
DHll Terminal I/O Data Structure
RKll Disk I/O Data Structure
I/O Data Structure for Two RKll Disk
Controllers
I/O Data Structure
Task Header on an Unmapped System
Task Header on a Mapped System
Stack Structure: Internal SST Fault
Stack Structure: Abnormal SST Fault
Stack Structure: Data Items on Stack
I/O Packet Format
QIO Directive Parameter Block (DPB)
Device Control Block
Status Control Block
Uni~ Control Block
Conditional Code for a Multicontroller Driver

2-2
2-7
2-7
2-8
2-18
3-21
3-21
3-22
3-23
3-24
4-3
4-6
4-8
4-16
4-20
4-28

May 1979

CONTENTS
Page

FIGURES (Cont.)
FIGURE

B-1

Mapping Register Assignment Block

B-3

TABLES
TABLE

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

Required DCB Fields
Required UCB Fields
Required SCB Fields
Mask Values for Standard I/O Functions

3-4
3-4
3-5
4-14

May 1979

PREFACE

MANUIAL OBJE:CTIVES

The goal of this manual is to provide information necessary to prepare
a conventional I/O driver for RSX-llM and subsequently incorporate it
into an operational user-tailored system. A "conventional" driver is
best explained by example.
Disks and unit record devices are
considered conventional; the LPS-11, UDC-11, and TMll are considered
unconventional.
Complexity of device servicing requirements sets the
dividing line, a line not easily established in black-and-white terms.

INTENDED AUDIENCE
The manual assumes that you understand the device for which you are
writing a driver, and that you are familiar with the PDP-11 computer,
its periphE~ral devices, and the software supplied with an RSX-llM
system.
Although this manual is organized tutorially, the intended
audience is assumed to be at a system programmer level of expertise;
thus, the manual does not contain definitions of data processing terms
and concepts familiar to senior level professionals.

ASSOCIATED DOCUMENTS
Familiarity with the system
following RSX-llM manuals:

implies

System Generation Manual

I/O Drivers Reference Manual

Executive Reference Manual

Utilities Procedures Manual

I/O Operations Reference Manual

in-depth

exposure

the

As adjuncts to this manual, you are advised to study existing I/O
drivers. The RF-11 disk driver is a good example of an NPR device and
the TA-11 (cassette) is illustrative of a programmed I/O device.
In
addition, a perusal of Executive source code contained in the files
IOSUB, SYSXT, DRQIO, BFCTL, and DRDSP (stored under UIC [11,10] on the
Executive source disk) is recommended.
Other manuals closely allied to the purposes of this document
described briefly in the RSX-llM/RSX-llS Documentation Directory.

vii

are
The

May 1979

Documentation Directory defines the intended readership of each manual
in the RSX-llM/RSX-llS set and provides a brief synopsis of each
manual's contents.

STRUCTURE OF THIS DOCUMENT

This document proceeds from chapter
levels of implementation detail.

Chapter 1 is a general introduction to
system.

I/O

chapter

toward

drivers

increasing
the

RSX-llM

Chapter 2 is a functional description of the RSX-llM device-level
system. It discusses both data structure and code requirements.

I/O

Chapter 3 details how to incorporate a user-written
system.

the

driver

into

Together, Chapters 1, 2, and 3 provide a complete understanding of the
requirements that must be met in creating a system that contains a
user-written driver.
Chapter 4 provides programming-level details on I/O
and on drivers that service several controllers.

data

structures

Chapter 5 discusses all the I/0-related Executive services.
Chapter 6 gives two examples of user-written drivers.
Appendix A describes the Address Doubleword.
Appendix B outlines special considerations for
drivers.

PDP-11/70

NPR

device

Appendix C lists system macros that supply symbolic offsets for system
data structures.

viii

May 1979

CHAPTER 1
INTRODUCTION TO I/O DRIVERS

The software supplied by DIGITAL for an RSX-llM system includes I/O
drivers for a number of standard I/O devices. An I/O driver is a part
of the RSX-llM Executive that services one type of I/O device.
A
driver may handle one or several controllers, each with one or several
device-units attached.

1.1

RESIDEN~~

AND LOADABLE DRIVERS

A driver can be resident or loadable.
A resident driver is a
permanent part of the Executive, built in at SYSGEN. A loadable
driver, while also part of the Executive, can be added to or unloaded
from a system almost at will by means of MCR or VMR commands. During
the SYSGEN dialog, you can specify that you want this facility.
Making drivers loadable can result in a smaller Executive, and thus
space for user tasks. Any driver that is not needed for a period
of time can be unloaded from the system.
For example, suppose your
system has both a paper-tape reader and a card reader.
Suppose that
only one of them is connected to the system at any one time.
You
could load the driver for
the online device and unload the other
driver, thus reducing the size of the Executive.
morE~

A loadable user-written driver is easier to incorporate into a system
and easier to debug than a resident one. A resident driver can only
be incorporated into a system at SYSGEN;
the Executive must be
rebuilt and the system bootstrapped each time it is reincorporated
during debugging. A loadable driver can be incorporated into a system
with a single MCR command.
Incorporating and debugging user-written
drivers are discussed in Chapter 3.

1.2

•

FUNCTION OF AN I/O DRIVER

An I/O driver is an asynchronous process (not a task) that calls and
is called by the Executive to service an external I/O device or
devices. The role of an I/O driver in the RSX-llM I/O structure is
specific and limited. A driver performs the following functions:
•

Receives and services interrupts from its I/O device(s).

•

Initiates I/O operations when
Executive.

•

Cancels in-progress I/O operations.

•

Performs other (device-specific) functions upon power failure
and device timeout.
1-1.

requested

the

INTRODUCTION TO I/O DRIVERS
As an integral part of the Executive, a driver possesses its own
context, allows or disallows interrupts, and synchronizes its access
to shared data bases with that of other Executive processes.
(It may
also synchronize with itself:
a driver can handle several device
controllers, each with several device-units, all
operating
in
parallel.) A user-written driver must adhere to RSX-llM programming
conventions in order to ensure the integrity of the Executive.
Section 2.5 and Chapter 4 discuss these conventions.

1-2

CHAPTER 2
THE RSX-llM I/O SYSTEM--PHILOSOPHY AND STRUCTURE

2.1

I/0 PHILOSOPHY

Memory constraints and RSX-llD compatibility requirements dominated
the design philosophy and strategy used in creating RSX-llM. To meet
its performance and space goals, the RSX-llM I/O system attempts to
centralize
common functions,
thus eliminating the inclusion of
repetitive code in each and every driver in the system.
To achieve
this centralization, a substantial effort has been expended in
designing RSX-llM's data structures. These structures are used to
drive the centralized routines;
the effect is to reduce substantially
the size of individual I/O drivers.
The table structures require
space and must be considered with the total size of the I/O system.
Nevertheless, the size reduction effected by the centralization of
functions, combined with table-driven design, enables RSX-llM to meet
its intended memory and performance goals.

2.2

STRUCTURE

This section:

2.2.l

Places an I/O driver in the context of
I/O system;

the

overall

RSX-llM

Establishes the responsibilities of an I/O driver, and

Functionally describes the driver's
interface
Executive subroutines and the I/O data structures.

the

I/O Hierarchy

The RSX-llM I/0 system is structured as a loose hierarchy.
The term
"loose" indicates that the hierarchy can be entered at any of its
levels; this characteristic is contrasted to "tight" hierarchies that
permit entry only from the top level.
Tight hierarchies exist
principally for security and protection, but are costly in their
consumption of equipment resources.
Figure 2-1 shows the loose I/O
system hierarchy.

2.2.1.1 FCS/RMS - At the top of the hierarchy are File Control
Services
(FCS)
and Record Management Services (RMS) , which provide
device-independent access to devices included in a given system
configuration.
The user task has two levels with which to interface
with FCS or RMS; Get/Put and Read/Write.
Get/Put facilitates the

2-1

THE RSX-llM I/O SYSTEM--PHILOSOPHY AND STRUCTURE
movement of data records, whereas Read/Write provides a more basic
level of access affording more direct control over data movement
between a task and peripheral devices.

Non-privileged

Privileged

I
FCP

•

.....

•

010
directive

•

I
- I-

- -- -

User 1/0
request

Deviceindependent

010
directive

[CS/RMS

Devicedependen

User state

- - - - - - -

System state

010
directive
service

•

-Device interrupt

Executive
1/0 subroutines

1
1/0
driver

Figure 2-1

I/O Control Flow

The discussion of FCS and RMS is briE~f because their existence is
completely transparent to the driver and rarely concerns the writer of
a conventional driver. FCS or RMS accepts a user request, interprets
it, and translates it into a series of low-level system directives
known as QIOs.

2.2.1.2 QIO - The QIO directive is the lowest level of task I/O. Any
task may issue a QIO directive.
The QIO directive allows direct
control over devices that are connected to a system and that have an
I/O driver. The QIO directive forces all I/O requests from user tasks
to go through the Executive. The Executive works to prevent tasks
from destructively interfering with each other and with the Executive
itself.

2-2

THE RSX-llM I/O SYSTEM--PHILOSOPHY AND STRUCTURE
2.2.1.3 Executive I/O Processing - The processing of I/O requests
the Executive I/O system is accomplished by means of:
1.

File Control Primitives {FCP), and

A collection of Executive components consisting of:
a.

QIO directive processing;

I/0-related subroutines, and

The I/O drivers.

1'-..CP is responsible for maintaining the structure and integrity of data
storE:!d on file-structured volumes.
It maps virtual block numbers to
logical block numbers, extends files,
and makes volume-protection
checks.
The driver converts a logical block number into a physical
No direct connection exists
addrE=ss on a file-structured device.
betwE:!en FCP and a driver.
and requires a
FCP is a privileged task,
execute.
Drivers,
on the other hand,
processes, not tasks.

partition in which to
are specialized system

The I/O services provided by the Executive consist of QIO directive
processing, and a collection of subroutines used by drivers to obtain
I/O requests, facilitate interrupt handling, and return status upon
completion of an I/O request
{actual control of the device is
performed by the driver). These subroutines are examined in detail in
Chapter 5. Executive subroutine services and QIO directive processing
are shown as distinct components but are, in fact, both part of the
Executive. These subroutines centralize common driver functions, thus
eliminating duplicate code sequences among drivers.

Role o:f I/O Driver in RSX-llM

2. 2 •.2

Every I/O driver in the RSX-llM system has five entry points:
1.

Device interrupt*

I/O initiator

Device timeout

Cancel I/O

Power failure

The first entry point is entered by a hardware interrupt;
the other
four are entered by calls from the Executive. Functional details
regarding these entry points follow.

2.2.2.1 Device Interrupt - Control passes to this entry point when a
device previously initiated by the driver completes an I/O operation
and causes an interrupt in the central processor.
The connection
between the device and the driver in this instance is direct;
the
Executive is not involved.
* A device may trigger more than one distinct interrupt
example, a full-duplex device would have two.
2-3

entry.

For

THE RSX-llM I/O SYSTEM--PHILOSOPHY AND STRUCTURE
2.2.2.2 I/O Initiator - The Executive calls this entry point to
inform the driver that work for it is waiting to be done.
In effect,
this is a wakeup signal for the driver.

2.2.2.3 Device Timeout - When a driver initiates an I/O operation, it
can establish a timeout count.
If the! function then fails to complete
within the specified time interval, the Executive notes the time lapse
and calls the driver at this entry point.

2.2.2.4 Cancel I/O - A number of circumstances arise within the
system
that require a driver to terminate an in-progress I/O
operation. When such a termination becomes necessary, a task so
informs the Executive, which then relays the request to the driver by
calling it at the cancel I/O entry point.

2.2.2.5 Power Failure - The Executive calls the driver's
failure entry point in three different circumstances:

power-

When power is restored after a failure

When the system is bootstrapped

When the driver is loaded (if it is a loadable, as opposed to
a resident, driver)

Power Restore - Two conditions can initiate a call to the driver when
power is restored following a power failure.
First, the Executive
automatically calls the power-failure entry point when power is
restored any time the controller is busy (that is, when I/O is in
progress). Second, a driver has the option to be called regardless of
the existence of an outstanding I/O operation at the time the power is
restored (refer to the description of the UC.PWF bit symbol in Section
4.1.4.1). Frequently, a driver's response to a power failure or to an
I/O failure is identical to that when its device times out;
in such a
case, the power-failure entry point may simply be a return, because
recovery will eventually be effected by means of the timeout entry
point.
Bootstrap - When the system is bootstrapped, a power-failure interrupt
is simulated. This simulation gives drivers the opportunity to carry
out any appropriate pre-operational initialization.
Load - The MCR command LOA[D]
calls a loadable driver at
its
power-failure entry point if the device is online and UC.PWF (refer to
Section 4.1.4.1) is set.

2.2.2.6 Summary---Role of an I/O DriVE!r - Functionally, the driver
RSX-llM is responsible for:
1.

Servicing device interrupts

Initiating I/O operations

Cancelling in-progress I/O operations

Performing device-related functions upon
timeout or power failure
2-4

the

occurrence

THE RSX·-llM I/0 SYSTEM--PHILOSOPHY AND STRUCTURE
A driver exists as an integral part of the Executive~
it can call,
and be called by, the Executive. The driver initiates device I/O
operations directly and receives device interrupts directly.
All
other entry points are entered by means of Executive calls. A driver
never receives a QIO request directly, and has no direct interaction
with FCP.

2.3

DATA STUUCTURES

An I/O driver interacts with seven data structures:
1.

Device Control Blocks (DCBs)

Unit Control Blocks (UCBs)

Status Control Blocks (SCBs)

The I/O Packet

The I/O Queue

The Fork List

Device Interrupt Vector

The first four of these data structures are especially important to
the driver, because it is by means of these data structures that all
I/O operations are effected. They also serve as communication and
coordination vehicles between the Executive and individual drivers.
The I/O Queue and the Fork List are actually Executive
data
structures,
but to convey the complete interaction of an I/O driver
with the Executive, we will also describe their role in the system.
The I/O Queue is a list of I/O packets built by the QIO directive,
principally from information in the caller's Directive Parameter Block
(DPB) •
The Fork List synchronizes access to shared Executive data
structures.
Entry to a driver following a device interrupt is accomplished through
the appropriate hardware device interrupt vector. As will be seen,
writers of resident drivers are responsible for properly initializing
this vector.
It is discussed in conjunction with the data structures
associated with a driver.

2.3.1

•

The Device Control Block (DCB}

At least one DCB exists for each type of device appearing in a system
(device type should not be equated with device-unit) • The function of
the DCB is to describe the static characteristics
(rather than
execution-time information)
of both the device controller and the
units attached to the controller. All the DCBs in a system form a
forward-linked list, with the last DCB having a link of zero.
Most of
the data in the DCB is established in the assembly source for
the
driver data structure.
The DCB is used by the QIO directive
processing code in the Executive and not by the driver.

2-5

THE RSX-llM I/O SYSTEM--PHILOSOPHY AND STRUCTURE
2.3.2

The Unit Control Block (UCB)

One UCB exists for each device-unit attached to a system. Much of the
information in the UCB is static, though a few dynamic parameters
exist.* For example, the redirect pointer, which reflects the results
of an MCR Redirect command, is updated dynamically. As with the DCB,
most of the UCB is established in the assembly source;
however,
its
contents are used and modified by both the Executive and the driver,
though modification of a given datum is usually done by either the
Executive or the driver, but not both.

2.3.3

The Status Control Block (SCB)

One SCB exists for each device controller in the system. This is true
even if the controller handles more than one device-unit (like the
RKll Controller). Line multiplexers such as the DHll and DJll are
considered to have one controller for each line because all lines may
transfer in parallel. Most of the information in the SCB is dynamic.
Both the Executive and the driver use the SCB.

2.3.3.1 Interrelation of the I/O Control Blocks - This
section
represents the interrelationship among the DCB, UCB, and SCB without
entering into the detailed contents of the control blocks, leaving
such a discussion to be pursued in Chapter 4.
Figure 2-2 shows the data structure that would result for three I.A36
DECwriters interfaced by means of a DHll multiplexer. The structure
requires one DCB, three UCBs, and threE~ SCBs, because the activity on
all three units can proceed in parallel.
Figure 2-3 depicts the internal data structure for an RKll disk
controller with three units attached.. Note that only one SCB exists
because only one of the three units can be active at any given time.
Figure 2-4 shows the data structure for
two RKll disk controllers,
each of which has two drives attached. Here, there are two SCBs,
because both of the disk controllers can operate in parallel.
Taken together, Figures 2-2, 2-3, and 2-4 illustrate the strategy
underlying the existence of three basic I/O control blocks. There
need be only one DCB for each device type. There may be one or more
SCBs, depending on the degree of parallelism that is desired or
possible: one for each device-unit, or one for each controller
servicing several device-units.
The number of UCBs and SCBs, and
their interrelationships, are uniquely determined by the hardware
these data structures describe.
This data structure provides considerabl€ flexibility in configuring
I/O devices, and, because of the information density in the structures
themselves, substantially reduces the code requirements of
the
associated drivers.

* From the UCB, however, it is possible to access most of the
other structures in the I/O data base
(see Figure 2-5).
In this
sense the UCB gives access to a large amount of dynamic data.

2-6

•

THE RSX-llM I/O SYSTEM--PHILOSOPHY AND STRUCTURE

•

UCB

SCB

Figure 2-2

DHll Terminal I/O Data Structure

UCB

SCB

Figure 2-3

RKll Disk I/O Data Structure

2-7

THE RSX-llM I/O SYSTEM--PHilC.OSOPHY AND STRUCTURE

DCB

UCB

[

l
SCB

Figure 2-4

2.3.4

UCB

I
--

SCB

I/O Data Structure for Two RKll Disk Controllers

The I/O Packet

An I/O Packet contains information extracted from the QIO DPB, as well
as other information needed to initiate and terminate I/O requests.

2.3.5

The I/O Queue

Each time a task makes an I/O request, the Executive performs a series
of validity checks on the DPB parameters. If these checks prove
successful, the Executive generates a data structure called an I/O
Packet. The Executive then inserts thE~ packet into a device-specific,
priority-ordered list of packets called the I/O Queue.
Each I/O
Queue's listhead is located in the SCB to which the I/0 requests
apply.
When a device driver needs work, it requests the Executive to dequeue
the next I/O Packet and deliver it to the requesting driver.
Normally, the driver does not directly manipulate the I/O Queue.*

* An exception is the case in which a driver needs to examine an I/O
packet before it is queued, or in place of having it queued. For the
driver to accomplish this examination, you must set the bit UC.QUE in
the control byte (U.CTL) of the UCB (dE~scribed in Section 4.1.4).
The most common reason for a driver to examine a packet before queuing
is that the driver employs a special user buffer, other than the
normal buffer used in a transfer request. Within the context of the
requesting task,
the driver must address-check and relocate such a
special buffer. See Section 6.3 for an example of a driver that does
this.

2-8

i 1HE RSX-llM I/O SYSTEM--PHILOSOPHY AND STRUCTURE

2.3.6

The Fork List

The Fork List is a mechanism by which RSX-llM splits off processes
that require access to shared data bases, or that require more CPU
time to process an interrupt than is compatible with fast,
real-time
response of the overall system.

•

A process that calls $FORK requests the Executive to transform it into
a "fork process" and place it on the Fork List. What this means is
that a call to $FORK saves a "snapshot" of the process (registers R4,
RS,
and the PC)
in a Fork block. This Fork block is queued on the
Fork List in FIFO order .
Whe?n a for.k process has worked its way to the front of the Fork List,
R4 and RS are restored and execution restarts at the statement after
CALL $FORK. The process is unaware that a pause of indeterminate
length has elapsed.
A fork process exists in a status intermediate between an interrupting
routine and an ordinary task requesting system resources.
Routines in
the system stack--requests for interrupt processing--are run first.
They can be interrupted only by higher-priority requests.
Routines in
the Fork List are run when the system stack is empty--that is,
they
are completely interruptable.
Finally, other tasks are run only when
both the system stack and the Fork List are empty.
Driver interrupts are processed at priority 7
and
are
thus
noninterruptable.
By. system convention, no process should run in a
noninterruptable mode for more than 100 microseconds.
This convention
ensures prompt attention to interrupting real-time events.
In practice, drivers servicing interrupts drop from priority 7 to a
lower priority (namely, that of the interrupting source) after issuing
a few instructions~ Another system convention states that processing
at
this
partially
interruptable level should not exceed SOO
microseconds. Often, more time than this is required to process an
interrupt.
The Fork List mechanism provides a secondary interrupt
stack whose members are processed first-in-first-out
(FIFO)
whenever
the system stack is empty.
A process can also call $FORK to access a shared data base--a system
table,
for example.
Such access must be strictly controlled to avoid
conflicts. Under RSX-llM, many drivers can run in parallel:
a
multicontroller driver can run in parallel with itself.
In these
circumstances access to common data bases must be controlled.
Of the two available methods of controlling such access--interrupt
lockout and priority queuing--RSX-llM uses priority queuing.
The Fork
List is the queue of requests for such access.
Fork processes are
granted FIFO access to common data bases.
Once granted such access, a
process is guaranteed control of the data base until it exits.

2.3.7

The Device Interrupt Vector

The device interrupt vector consists of two consecutive words giving
the address of the interrupt-service routine and the priority at which
it is to run (always set to PR7). The low 4 bits of the second word
of the interrupt vector must contain the number of the controller that
interrupts through the vector. This requirement enables a driver to
service several controllers with few code changes (see Sections 4.2
and 4.3 for an example and discussion of multicontroller driver
coding). Generally, these bits are O.

2--9

THE RSX-llM I/O SYSTEM--PHII,OSOPHY AND STRUCTURE
2.4

,,..,

EXECUTIVE SERVICES

The Executive provides services related to I/O drivers that can be
categorized as pre- and post-driver initiation. The pre-initiation
services are those performed by the Executive during its processing of
a QIO directive;
these services are not available as Executive calls.
The goal of pre-driver-initiation processing is to extract from the
QIO directive all I/O support functions not directly related to the
actual issuance of a function request to a device.
If the outcome of
pre-driver-initiation processing does not result in the queuing of an
I/O Packet to a driver, the driver is unaware that a QIO directive was
issued. Many QIO directives do not result in the initiation of an I/O
operation.
The post-initiation services are those available to the driver after
it has been given control, either by the Executive or as the result of
an interrupt. They are available as needed by means of Executive
calls.
An important concept used in this section and in Section 2.5 is the
"state" of a process.
In RSX-llM, a process can run in one of two
states, user or system. Drivers operate almost entirely in the system
state;
the programming standards described in Section 2.5 apply to
system-state processes.

Pre-Driver Initiation Processing

2.4.1

In processing a QIO directive, the Executive module DRQIO performs the
following pre-driver initiation services:
1.

Checks to verify whether the supplied logical unit
(LUN) is legal.
If not, the directive is rejected.

If the LUN is valid, checks to verify whether a valid UCB
pointer exists in the Logical Unit Table
(LUT) for the
specified LUN. This test determines if the LUN is assigned.
If the test fails, the directive is rejected.

If steps 1 and 2 are successful, traces down the redirect
chain to locate the correct UCB to which the I/O operation
will actually be directed.

Checks the event flag number (EFN) and the address of the I/0
Status Block (IOSB).
If either is illegal, the directive is
rejected. Immediately following validation, the Executive
resets the subject event flag and clears the IOSB.

Obtains 18 words of dynamic storage
and
device-independent portion of an I/O Packet.
If steps 1 thru 5 succeed, the Executive sets
status to +l.

builds
the

number

the

directive

Note that directive rejections in any of the above steps are
completely transparent to the driver. Such rejections cause
a return of carry bit set.

2-10

•

THE RSX-llM I/O SYSTEM--PBILOSOPBY AND STRUCTURE
6.

Checks the validity of the function being requested and,
if
appropriate, checks the buffer address, byte count, and
alignment requirements for the specified device.
If any of these checks fails, the Executive calls the I/O
Finish routine
($IOFIN}.
$IOFIN sets the I/O status and
clears the QIO request from the system.

If the requested function does not require a call to the
driver, the Executive takes the appropriate actions and calls
$IOFIN.

If all I/O Packet checks are positive, the Executive places
the I/O Packet in the driver queue according to the priority
of the requesting task, or gives the packet to the driver (if
bit UC.QUE is set--described in Section 4.1.4.1).

2.4.2

Post-Driver Initiation Services

Once a driver is given control following an I/O interrupt or by the
Executive itself, a number of Executive services are available to the
driver. These services are discussed in detail in Chapter 5.
However, four Executive services merit special
virtually every driver in the system uses them:

.._..,,.

Interrupt Save ($INTSV}

Get Packet ($GTPKT)

Create Fork Process ($FORK)

I/0 Done ($IODON or $IOALT)

emphasis

because

2.4.2.1 Interrupt Save
($INTSV)* - Interrupts from a device are
fielded by the driver.
Immediately following the interrupt, the
driver operates at hardware priority level 7 and is,
therefore,
noninterruptable.
If the driver needs a lengthy processing cycle
(greater than 100 microseconds) to process the interrupt, or if it
requires the use of any general-purpose registers, it calls $INTSV.
This call queues external interrupts, alters the hardware priority,
and provides the calling routine with two free registers to use in
processing the interrupt.
$INTSV is discussed in more detail in
Se?ction 2.5.

2.4.2.2 Get Packet ($GTPKT) - The Executive, after it has queued an
I/O Packet, calls the appropriate driver at its I/O-initiator entry
point. The driver then immediately calls the Executive routine $GTPKT
to obtain work.** If work is available, $GTPKT delivers to the driver
the highest-priority, executable I/O Packet in the driver's I/O queue,
and sets the SCB status to "busy." If the driver's I/O Queue is empty,
$GTPKT returns a no-work indication.
*
SE~e

A loadable driver on a mapped system may not call $INTSV
Section 4. 3.

directly.

** An exception is a driver that handles special user buffers. Such a
driver must call certain other Executive routines before calling
$GTPKT. See Section 6.3 for an example.
2-11

THE RSX-llM I/O SYSTEM--PHILOSOPBY AND STRUCTURE
If the SCB related to the device is already busy, $GTPKT so
the driver, and the driver immediately returns control
Executive.

informs
to the

Note that, from the driver's point of view, no distinction exists
between no-work and SCB busy, because an I/O operation cannot be
initiated in either case.

2.4.2.3 Create Fork Process ($FORK) - Synchronization of access to
shared data bases is accomplished by creating a fork process. When a
driver needs to access a shared data base, it must do so as a fork
procesa: the driver becomes a fork process by calling $FORK. The SCB
contains preallocated storage for a 4- or 5-word "fork block".
See
Section 4.1.3.l for a description of the fork block. Section 5.3
contains details on $FORK.
An interrupt routine may not call $FORK directly:
the routine must
first switch to system state by using the INTSV$ macro or calling
$INTSV (as described in Section 2.4.2.J.). Further, the interrupting
routine's priority is lowered to that of the requesting source.
After calling $FORK, a routine is fully interruptable
(priority
and its access to shared system data bases is strictly linear.

0),

2.4.2.4 I/O Done ($!ODON or $IOALT) - at the completion of an I/O
request, the subroutines $IODON or $IOALT perform a number of
centralized checks and additional functions:
Store status if an IOSB address was specified
Set an event flag, if one was requested
Determine if a checkpoint request can now be honored
Determine if an AST should be queued
$IODON and $IOALT also declare a significant event, resets the SCB and
device unit status to "idle," and releases the dynamic storage used by
the completed I/O operation.

2.5

PROGRAMMING STANDARDS

RSX-llM I/O drivers function as integral components of the RSX-llM
Executive.
They must follow the same conventions and protocol as the
Executive itself if they are to avoid complete disruption of system
service.
This manual has been written to enable you to incorporate
I/O drivers into your system.
Failure to observe the internal
conventions and protocol can result in poor service and reductions in
system efficiency.

2-12

THE RSX·-llM I/O SYSTEM--PHILOSOPHY AND STRUCTURE

2.5.1

Process-Like Characteristics of a Driver

A driver is an asynchronous Executive process.
As a process, it
possesses its own context, allows or disallows interrupts, and
synchronizes functions within itself (all drivers can be parallel,
multiunit,
multicontroller)
and with other Executive processes
executing in parallel.
Most RSX-llM drivers are small; their small size is made possible by
a comprehensive complement of centralized services available by calls
to the Executive, and by the availability of an information-dense,
highly formalized I/O data structure.

2.5~2

Programming Conventions

Appendix E of the IAS/RSX-11 MACR0-11 Reference· Manual describes
program coding standards.
DIGITAL recommends that users refer to
these standards to assist in preparing standards for their own
installations.

2. 5 .. 3

Progr c:imming Protocol

Because an I/O driver accepts interrupts directly from the devices it
controls, the central Executive relies on the driver to follow strict
programming protocol so that system performance is not degraded.
Furthermore, the protocol ensures that the driver properly distributes
shared resources according to user-specified priorities. The protocol
is summarized in Section 2.5.3.4.
When a device interrupts, an I/O driver is entered.
The driver
usually calls $INTSV or issues the INTSV$ macro* for common save and
state-switching services. At the completion of the services provided
by INTSV$ or $INTSV, the interrupt routine is again given control to
complete the interrupt service. The exit routine $INTXT restores the
state prior to switching to the system state, controls the un-nesting
of interrupts, and makes checks on the state of the system (for
example, it checks to determine whether it is necessary to switch
stacks). The Fork Processor linearizes access to shared system data
bases. The details of all these routines are given in Chapter 5.
The interrupt vectors for each controller type in low memory contain a
Program Counter (PC) unique to each interrupting source and a
Processor Status Word (PS) set with a priority of 7. It is a system
software convention to use the low-order 4 bits of the PS word to
encode the controller number for multicontroller drivers.
When a
device interrupt occurs, the hardware pushes the current PS and PC
onto the current stack and loads the new PC and PS (set at PR7 with
the controller number in the condition-code bits) from the appropriate
interrupt vector. The driver then starts executing with interrupts
locked out.
A driver itself may be executing at one of three levels
of interrupt sensitivity:

* The system macro INTSV$ simplifies the
interrupt-entry processing (see Section 4.3).

2-13

coding

standard

May 1979

THE RSX-llM I/O SYSTEM--PHILOSOPHY AND STRUCTURE
1.

At priority 7 with interrupts locked out;

At the priority of the interrupting source; thus, inter.rupt
levels greater than the priority of the interrupting source
are permitted, or

At fork level, which is at priority 0.

2.5.3.l Processing at Priorit~ 7 with Interrupts Locked Out - By
internal convention, processing at this level is limited to 100
microseconds. If processing can be completed in this time, either
without using general-purpose registers or by saving and restorin9 the
registers used, then the driver simply dismisses the interrupt by
executing
an R~I instruction.
The interrupt is processed and
dismissed with minimal overhead.

2.5.3.2 Processing at the Priority of the Interrupting Source - If
the driver requires additional processing time or requires the use of
general-purpose registers, it calls the Interrupt Save routine.
Loadable drivers on mapped systems must use the INTSV$ macro. All
other drivers can use the INTSV$ macro or call the $INTSV routine
directly.
The priority at which the caller is to run is included in
the call to the Interrupt Save routine. The driver sets this priority
level to that of the interrupting source.
The Interrupt Save routine sets up the interrupt routine so that it
can be interrupted by devices with priorities higher than that of the
interrupting source, and switches to :system state if the processor is
not already in system state.
The Interrupt Save routine also saves registers R4 and RS to free
these registers for the driver.
{A standard practice is for the
driver to set R4 to the address of th•= interrupting device's SCB, and
RS to its UCB address.) An internal programming convention assumes
that the driver will not require more than these two registers during
interrupt processing.
If it does, the driver must save and restore
any additional registers it uses.
Processing time following the
return
from the Interrupt Save routine should not exceed 500
microseconds*.
NOTE
In actual practice, every driver in the
system calls the Interrupt Save routine
on every interrupt.
This practice is
due to two factors:
1.

service
an
It is difficult to
interrupt without using one or two
registers.

* The 500-microsecond period is a guideline. The longer the period
of time a real-time executive spends at an elevated priority level,
the less responsive is the system to devices of equal or lower
priority.
This guideline is especially important if the device being
serviced is at the same or higher priority than a character-interrupt
device such as the DUll, which is vulnerable to data loss due to
interrupt lockout.

2-14

THE RSX-llM I/O SYSTEM--PHILOSOPHY AND STRUCTURE
2.

Most interrupt code can safely be
executed at the priority of the
interrupting source.
Execution at
that priority is more desirable in
terms of
system
response
than
continuing to execute at the highest
priority.

2.5.3.3 Pr.ocessing at Fork Level - A driver calls $FORK to become
fully interruptable
(so that it conforms to the 500-microsecond time
limit), or to access the shared system data base.
The INTSV$ macro
must be issued or the $INTSV routine must be called prior to calling
$FOHK.
By calling $FORK, the routine becomes fully interruptable and its
to system data bases is strictly linear. At fork level, all
registers are available to the process,
and R4 and RS retain the
contents they had on entrance to $FORK.
acce~ss

2.5 .. 3.4 Programming Protocol Summary - Drivers are required to adhere
to
the
following
internal conventions when processing device
intE~rrupts:

2.6

No registers are available for use unless $INTSV has been
called or the driver explicitly performs save and restore
operations.
If $INTSV is called, registers R4 and RS are
available;
any other registers must be saved and restored.

Noninterruptable
processing
must
not
instructions,
and
processing
at the
interrupting source must not exceed 500us.

All modifications to system data bases must be done by a fork
process.

exceed
priority

twenty
of the

FLOW OF AN I/O REQUEST

Following an I/O request through the system at the functional
level
(the level at which this chapter is directed) requires that limiting
assumptions be made about the state of the system when a task issues a
QIO directive.
The following assumptions apply:
•

The system is up and ready to accept an I/O request.
All
required data structures for supporting devices attached to
the system are intact.

•

The only I/O request in the
under discussion.

•

The example progresses without encountering any errors that
would prematurely terminate its data transfer;
thus, no
error paths are discussed.

2-15

system

the

sample

request

THE RSX-llM I/O SYSTEM--PHILOSOPHY AND STRUCTURE
The I/O flow proceeds as described below:
1.

[Task issues QIO directive]
All Executive directives are called by means of EMT 377.
The
EMT causes the processor to push the PS and PC on the stack
and to pass control to the Executive's directive processor.

la.

[First-level validity checks]
The QIO
pointer.

lb.

directive

processor

validates

the

LUN

and

UCB

[Redirect algorithm]
Because the UCB may have been dynamically redirected by an
MCR Redirect command,
QIO directive processing traces the
redirect linkage until the target UCB is found.

le.

[Additional validity checks]
The EFN is validated, as well as the address of the
I/O
Status Block
(IOSB).
The event flag is reset and the I/O
status block is cleared.

[Obtain storage for and create an I/O Packet]
The QIO directive processor now acquires an 18-word block of
dynamic storage for
use as an I/O Packet.
It inserts into
the packet data items that are used subsequently by both the
Executive and the driver in fulfilling the I/O request.
Most
items originate in the requesting task's Directive Parameter
Block (DPB) .

[Validate the function requested]
The function is one of four possible types:
Control
No-op
ACP
Transfer
Control functions, with the exception of Attach/Detach,
are
queued
to
the
driver.
If the bit UC.ATT is set,
Attach/Detach will also be queued to the driver.
No-op functions do not result in data transfers.
The
Executive "performs" them without calling the driver.
No-ops
return a status of rs.sue in the I/O status block.
ACP functions may require processing by the file
system.
More typically,
the request is a
read or write virtual
function that is transformed into a
read or write logical
function without requiring file-system intervention.
When
transformed into a
read or write logical,
the function
becomes a transfer function (by definition).
Transfer functions are address checked and queued
to the
proper driver.
Then the driver is called at its initiator
entry point.

2-16

THE RSX-llM I/0 SYSTEM--PHILOSOPHY AND STRUCTURE
4.

[Driver processing]

4a.

[Request work]
To obtain work, the driver calls Get Packet ($GTPKT).
$GTPKT
either provides work,
if it exists, or informs the driver
that no work is available, or that the SCB is busy;
if no
work exists, the driver returns to its caller.
If work is
available, $GTPKT sets the device controller and unit to
"busy," dequeues an I/O request packet, and returns to the
driver.

4b.

[Issue I/O]
From the available data structures, the driver initiates the
required
I/O operation and returns to its caller.
A
subsequent interrupt may inform the driver that the initiated
function is complete, assuming the device is interruptdriven.

5.
~

[Interrupt processing]
When a previously issued I/O operation interrupts,
the
interrupt causes a direct entry into the driver, which
processes the interrupt according to the programming protocol
described in Section 2.5.
According to the protocol, the
driver may process the interrupt at priority 7, at the
priority of the interrupting device, or at fork level.
If
the processing of the I/O request associated with the
interrupt is still incomplete, the driver initiates further
I/O on the device (step 4b) • When the processing of an I/O
request is complete, the driver calls $!ODON.

[I/O Done processing]
$IODON removes the "busy" status from the device unit and
controller, queues an AST, if required, and determines if a
checkpoint request pending for the issuing task can now be
effected.
The IOSB and event flag,
if specified, are
updated, and $!ODON returns to the driver.
The driver
branches to its initiator entry point and looks for more work
(step 4a). This procedure is followed until the driver finds
the queue empty, whereupon the driver returns to its caller •

.....,,-

Eventually, the processor is granted to another ready-to-run
task that issues a QIO directive, starting the I/O flow anew.

2.7

DATA STRUCTURES AND THEIR INTERRELATIONSHIPS

This section introduces all the individual control blocks, as well as
their linkages and use within the system.
The following data
structures comprise the complete set for I/O processing:
1.

Task Header

Window Block (WB)

File Control Block (FCB)

$DEVHD word, the Device Control Block (DCB), and
Dispatch Table (DDT)

2-17

the

Driver

THE RSX-llM I/O SYSTEM--PBILOSOPHY AND STRUCTURE
5.

Unit Control Block (UCB)

Status Control Block (SCB)

Volume Control Block (VCB)

Figure 2-5, which provides the structure for the following discussion,
shows all the individual data structures and the important link fields
within them. The numbers on the figure are keyed to the text to
simplify the discussion and to guide the reader through the data
structures.
1.

The Task Header is constructed during
the
task-build
process.*
(It is one of two independent entries in the I/O
data structure, the other being $DEVHD.) The Task Header
entry of interest, the Logical Unit Table (LUT), is allocated
by the Task Builder and filled in at task installation.
The
number of LUT entries is established by the UNITS= keyword
option~
this number is an upper limit on the number of
device units a task may have active simultaneously.
Each LUT
entry contains a pointer to an associated UCB, and a pointer
to a Window Block if a file is accessed by that logical unit
number (LUN) •

~ti

SYSCM

$DEVHD:

~.______.CJ~--···

-no7D/. .
1/0 Queue

LUT1n
g:::

r-- i======ISCB

Task

Header

[

©:

LUTE""'

TCB

~
L_::_J
\

Fork
Block

D ~r:::::::=:::=::VCB~

'c""'"

~/o·
Figure 2-5

DFCB(index)1 _

MOUnted
volume

""'WB (volume)

I/O Data Structure

* In mapped systems, a copy of the Task Header (located in the task's
partition)
is made in the ExecutivE~'s dynamic storage region. This
copy is then used by the Executive. To access the current information
in this copy, a task must be privileged and have mapping to the
Executive.
2-18

.~.

THE RSX-llM I/O SYSTEM--PHILOSOPHY AND STRUCTURE
2.

A Window Block (WB) exists for each active access to files on
a mounted volume.
Its function is to speed up the process of
retrieving data items in the file;
entries in a WB consist
mainly of pointers to contiguous areas on the device on which
the file resides.
The driver is not concerned with the WB.

Each uniquely opened file on a mounted volume has an
associated File Control Block (FCB) .
The file system uses
the FCB to control access to the file.

$DEVHD is a word located in system common (SYSCM) and is the
other independent entry in the I/O data structure.
$DEVHD
points to a singly linked,
unidirectional list of Device
Control Blocks
(DCBs) .
Each device type in a system has at
least one associated DCB.
The DCB list is terminated by a
zero in the link word.
Linked to each DCB is a Driver Dispatch Table (DDT), which is
part of the driver.
The DDT contains the addresses of the
driver's four entry points that the Executive can call.

A key data structure is the Unit Control Block
(UCB).
All
the UCBs associated with a DCB appear in consecutive memory
locations.
During internal processing of an I/O request,
most drivers set RS to the address of the related UCB;
it is
by means of pointers in the UCB that other control blocks in
the data structure are accessed.
In particular, the UCB
contains pointers to the DCB, SCB, VCB, and to the UCB to
which it may have been redirected.
If a Redirect command has
not been issued for the device-unit, the UCB redirect pointer
points to the UCB itself. When servicing a request for one
of its UCBs, the driver is unaware of whether I/O was issued
directly to its own UCB or to a UCB that had been redirected
to its UCB.

One Status Control Block (SCB) exists for each controller
in
a
system.
A
unique
SCB
must
exist
for
each
controller/device-unit capable of performing parallel
I/O.
The SCB contains the fork-block storage required when a
driver calls $FORK to transfer itself to the fork processing
level.
The I/O request queue listhead is also contained in
the SCB.
Generally, register R4 contains the address of the
SCB during processing of an I/O request.

One Volume Control Block (VCB) exists for each mounted volume
in a system.
The VCB maintains volume-dependent control
information.
It contains pointers to the File Control Block
(FCB)
and Window Block
(WB),
which control access to the
volume's index file.
(The index file
is a
file of file
headers.)
The WB for the index file serves the same function
as the WB for
a
user
file.
(See the IAS/RSX-11 I/O
~ations Reference Manual for more information on the index
filE~.) All unique FCBs
for
a volume form a linked list
emanating from the index file
FCB.
This linkage aids in
keeping file access time short.
Further,
since the window
that contains the mapping pointers is variable in length, the
user can increase file access speed by adding more access
pointers
(greater speed requires more main memory)
to
whatever extent the application requires.

2-19

THE RSX-llM I/O SYSTEM--PBILOSOPHY AND STRUCTURE
2.7.1

Data Structures Summary

As the writer of a conventional driver, you do not manipulate the
entire I/O data structure.
In fact, you are usually involved only
with the I/O Packet, the UCB, and the SCB. The entire structure has
been presented to add depth to your understanding of the I/O system,
to emphasize the relationships among individual control blocks, and to
clarify further the role a given driver fulfills in the processing of
an I/O request.

~..

2-20

CHAPTER 3
INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM

If you want to support an I/O device for which DIGITAL has not
supplied a driver, you can write your own driver. While we have not
yet presented explicit details for writing such a driver, you now have
enough conceptual
information to consider incorporating one of your
own drivers into your system. As will be seen, many considerations
for
writing
a driver are best presented in a discussion of
incorporating one.
NOTE
An alternative approach to writing your
own device driver may be the CONNECT TO
INTERRUPT VECTOR directive.
Refer to
the description of the CINT$ directive
in the RSX-llM
Executive
Reference
Manual.
For examples of the use of
CINT$, examine the task-level support
routines
for
K-series
laboratory
peripheral modules.

3.1

OVERVIEW OF USER-WRITTEN DRIVERS

Incorporating a user-written driver is accomplished by means of the
standard system generation process.
Phase 1 of system generation
includes queries that condition Phase 2 for
the inclusion
of
user-written drivers.
Specifically, the query
ARE YOU PLANNING TO INCLUDE A USER WRITTEN DRIVER?
if answered affirmatively, results in at least one
This query is:

[Y/N] :

additional

WHAT IS THE ADDRESS OF THE HIGHEST DEVICE INTERRUPT VECTOR?

query.
[O] :

Phase 1 uses the specified address or 400, whichever
is greater,
to
allocate sufficient vector space in the Executive to avoid run-time
destruction of the system stack and to avoid hardware trapping
{which
occurs when the SP goes below 400).
The following two additional queries may also appear
5. 3) :
IS

~rHE:

(refer to Section

EXECUTIVE ROUTINE $GTWRD REQUIRED?

[Y/N] :

IS THE EXECUTIVE ROUTINE $PTWRD REQUIRED?

[Y/N] :

3-1

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
NOTE
These additional queries are suppressed
when certain standard drivers, which
require the $GTWRD and $PTWRD routines,
are included during SYSGEN.
During the same phase of system generation,
there is an additional
decision you must make on behalf of the driver you are planning to
incorporate into the system.
Your driver, similar to most
(but not
all)
DIGITAL supplied drivers, can be resident or loadable. Loadable
drivers require extra Executive features to support them (for example,
the MCR/VMR LOAD and UNLOAD commands) . You can choose support for
loadable drivers by answering in the affirmative the following Phase 1
system generation question:
DO YOU WANT LOADABLE DRIVER SUPPORT?

3.1.1

[Y/N] :

Overview of User-Written Driver Code

When you decide to add a driver to your system,
you
share
responsibility for
the integrity of the Executive. Errors in your
driver code can cause a system failure and bring to a halt all user
service.
To create the source code to drive a device, you
steps:

must

perform

Thoroughly read and understand this manual.

Familiarize yourself in detail with the physical
its operational characteristics.

Determine the level of support required for the device.

Create the data base source code for the device.

Determine actions to
points:

Initiator

Cancel I/O

Timeout

Powerfail

Interrupt

taken

the

five

these
~.

device

driver

and

entry

Create the driver source code. This code will contain the
following global symbols (whe!re xx is the 2-character device
mnemonic):
$xxTBL::

address of the driver
Section 4.1.2.1)

$xxINT::

address of the driver interrupt entry point

$xxINP::
$xxOUT::

addresses of input and output
interrupt
entry points (for full-duplex devices).

3-2

dispatch

table

(see

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
Loadable drivers have one additional requirement.
Either
within the driver source code itself or in file RSXMC.MAC,
the conditional assembly symbol LD$xx must be defined.
The
INTSV$ macro (refer to Section 4.3) uses this symbol (and
others in RSXMC.MAC) to determine if the call to $INTSV
should be omitted from the driver.
The symbols used to name interrupt entries are different for
Error Logging devices. See the RSX-llM/M-PLUS Error Losging
Reference Manual for information on modifying device drivers
for error logging. Note that Error Logging must be modified
to handle user-written drivers.
The DIGITAL-supplied terminal driver (TTDRV) is treated as a
special case by VMR LOA[D], in terms of the naming of its
interrupt entries.
When adding a resident driver to the system, you should assemble the
driver with padding space for possible expansion during the debugging
process. This padding space is necessary because the system may crash
upon exiting VMR if the new Executive is larger than the old one (see
the note in Section 3.4.1.5). For a loadable driver, however, you do
not need to include padding space in the assembly source.

3.1.2

Overview of User-Written Driver Data Bases

Of the structures associated with an I/O driver, four require assembly
source:
1.

The DCB

The UCB(s)

The SCB(s)

The device interrupt vector
resident drivers only)

(assembly

source

required

for

A single DCB can service multiple UCBs and SCBs.
The existence of
multiple UCBs and SCBs is determined by the actual device subsystem
being supported by a given driver in your hardware configuration.
Figures 2-2, 2-3, and 2-4 illustrate possible DCB, UCB, and SCB
structural relationships.
Within the DCB, UCBs, and SCBs, only those fields that are static or
that need initialization must be supplied in your assembly source.
The following three tables list these required fields.

3-3

May 1979

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
Table 3·-1
Required DCB Fields
Description

Off set
D.LNK

Link to next DCB. This field is zero if this is the
last (or only) DCB. If you are incorporating more
than one user-written driver at one time, then this
field should point to another DCB in a DCB chain.

D.UCB

Address of the first word (U.DCB) of
associated with this DCB.

D.NAM

Two-character ASCII generic device name.

D.UNIT

Highest and lowest logical unit numbers controlled by
this DCB.

D.UCBL

Length of the UCB (including prefix words, if any).
If a given DCB has multiple UCBs, all UCBs must be of
the same length.

D.DSP

Address of the driver dispatch table.
The dispatch
table is located within the driver code. This field
contains a global reference to the label associated
with this table.
The field is 0 if the driver is
loadable.

D.MSK

I/O ~unction masks.
You must supply bit-by-bit
mapping for these four I/O function masks. Note that
the format of the mask words is split into two groups
of 4 words. Functions 0-15 are covered by the first
group, and functions 16-31 by the second.

D.PCB

Address of driver Partition Control Block (PCB).
This field is required only if loadable driver
support is included in the system.
It must be
initialized to 0.

the

first

UCB

Table 3-2
Required UCB Fields
Offset
U.LUIC

Description
Log-on UIC. This field is located at a negative
from the start of the UCB. It is present in
terminal UCBs on multiuser systems only.

offs~t

U.OWN

Owning terminal UCB address. This field is located
at a negative offset from the start of the UCB. It
is present on multiuser systems only.

U.DCB

Backpointer to the associated DCB.

U.RED

Redirect pointer--initially contains the
this UCB.

address

(continued on next page)

3-4

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
Table 3-2 (Cont.)
Required UCB Fields
Description

Off set
U.CTL

Control bits that must be established by
writer with the UCB source.

U.STS

Unit status byte.

U.UNIT

Physical unit number serviced by this UCB.

U.ST2

Unit status byte extension.

U.CWl

Characteristics
word
1.
(Section 4.1.4.1) applies.

U.CW2

Driver-dependent.

U.CW3

Driver-dependent.

U.CW4

Default buffer size.

U.SCB

Address of the SCB for this UCB.

U. AT~r

TCB address of attached task (initially 0).

._...,

driver

description

Table 3-3
Required SCB Fields
Off set

Standard

the

Description

S.LHD

I/O Queue listhead.

S.PRI

Priority of interrupting source.

s. vc•r

Interrupt vector address divided by 4.

S. !TM

Initial timeout count.

S.CON

Controller index
multiplied by 2).

S.STS

Controller status.

S.CSR

Address of control and status register.

S.FRK

Fork block.

S.MPR

Mapping register block. Needed only by UNIBUS NPR
devices running on a PDP-11/70 in extended-addressing
(22-bit) mode.

(that

3-·5

is,

controller

number

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
3.2

USER-WRITTEN RESIDENT DRIVERS

The general procedure for incorporatin9 a user-written resident driver
into your system is as follows:
l.

Bootstrap the source disk and run SYSGEN Phase l .

Bootstrap the object disk.

Create the assembly source for the driver.

Create the assembly source for the driver's data base.

Run SYSGEN Phase 2.

The following subsections present details of steps 4 and 5 above.

3.2.l

3.2.2

Creating the Data Base for a Resident Driver
1.

Use UIC [200,200] to create source
data base on the object disk.

code

for

your

Use USRTB.MAC as the filename and file type of the assembly
source file.
USRTB as a filename is not actually required.
It is, however, a useful convention--one that you will see
reflected in the sample dialog in Section 3.2.2.

There is no mandatory ordering of the different control
blocks in the data base for your resident driver.
It is
suggested that you follow the convention of placing the DCB
first,
followed by the UCB(s),
followed by the SCB(s).
However, it is required that all UCB(s)
associated with a
particular DCB must be contiguous. DIGITAL-supplied RSX-llM
drivers use this ordering scheme--for examples see the file
[11,10]
SYSTB.MAC, created by Phase l of SYSGEN.
If you are
incorporating multiple resident drivers into your system, you
will have more than one instance of a DCB with UCB(s) and
SCB(s).

Initialize the device interrupt vector
4.1.5 for description of this process).

Use the global label $USRTB::
as the address of
(or only) DCB. This is absolutely required.

(refer

driver's

Section

your

first

Incorporating a Resident Driver

During the execution of system generation Phase 2, the query
*DO YOU WISH TO ADD USER WRITTEN DRIVER(S) TO THE EXEC? [Y/N]:
is posed.
If the answer is affirmative, then subsequent dialog guides
you through the process of adding the driver to the generated system.
Operations performed include assembly of the driver and its data
structure,
inclusion of the resultant object modules into the
Executive object module library, and editing of the RSX-llM task-build
command file.

3-6

INCORPORATING USER-WRITTE:N DRIVERS INTO RSX-llM
The following sample dialog illustrates the addition of a driver
for
device XX.
All user responses are underlined.
The notation [l,2x]
indicates that the appropriate UIC is to be substituted:
[1,20]
for
an unmapped system and [1,24] for a mapped system.
>* DO YOU WISH TO ADD USER WRITTEN DRIVER(S) TO THE EXEC? [Y/N] :Y
>* WAS LOADABLE DRIVER SUPPORT SELECTED DURING SYSGEN PHASE l? [YJN] :!
>SET /UIC=[200,200]

>;
>; WE WILL PAUSE WHILE YOU ASSEMBLE YOUR DRIVER(S) AND USRTB
>; MODULE. THE EXEC ASSEMBLY PREFIX FILE RSXMC.MAC IS ALREADY
> i LOCATED UNDER UIC [200,200]. ASSUMING YOUR DRIVER(S) NAME IS
>; XXDRV, WHERE XX IS THE DEVICE NAME (E.G., DK) THE FOLLOWING
> i COMMANDS WILL ASSEMBLE THE DRIVER(S) AND THE USRTB MODULE.
>;

>i
>i

>;
>;
>

>RUN $MAC
MAC> XXDRV== [ 1, 1] EXEMC/ML, [ 2 0 0, 2 0 0] RSXMC, XXDRV
MAC>USRTB==[l,l]EXEMC/ML,[200,200]RSXMC,USRTB
MAC>"Z

AT. -- PAUSING. ~ro CONTINUE TYPE II RES •.. AT. II
>RUN $MAC
MAC>XXDRV=[l,l]EXEMC/ML,[200,200]RSXMC,XXDRV
MAC> USRTB=:J..!, l JEX EMC/ML, [ 2 0 0, 2 0 0 J RSXMC, USRTB
MAC>xZ
>RE:S •.. AT.
AT. -- CONTINUING

>; NOW YOU MUST ADD YOUR DRIVER(S) AND USRTB MODULE
>; TO THE EXEC OBJECT MODULE LIBRARY.
THE FOLLOWING IS AN EXAMPLE:

>;
>;
>;

LBR>RSX11M/RP=[200,200]XXDRV,USRTB
LBR>"Z

>SE:T /UIC==[l,2x]
>LBR
LBH>RSXlH~lP= [ 200, 200] XXDRV, USRTB
LBH>xZ

>;
>; YOU MUST NOW ADD COMMANDS TO INCLUDE YOUR DRIVER(S) AND USRTB
>; MODULE INTO THE EXEC BY EDITING THE EXEC TASK BUILD COMMAND FILE.
>; TO ADD DRIVER(S), INSERT COMMANDS OF THE FORM:

>;
>;

RSXllM/LB:XXDRV

>;
>; INTO THE COMMAND FILE IN THE PLACE WHERE THE
>; OTHER DRIVERS ARE REFERENCED.
XXDRV REPRESENTS THE NAME OF
>; YOUR DRIVER(S).

>;
>i
>;
>i
>i

NOTE: FOR THOSE DRIVERS WHICH YOU WANT TO BE LOADABLE,
DO NOT INCLUDE CORRESPONDING COMMANDS TO ADD THEM TO
THE EXECUTIVE.

>; THEN LOCATE THE LINE IN WHICH THE MODULE SYSTB IS
>; REFERENCED AND ADD THE ENTRY FOR YOUR
>; USRTB MODULE IMMEDIATELY AFTER IT.
EG:

>i
>;
>;

[l,2x]RSX11M/LB:LOADR:NULTK:SYSTB:USRTB:SYTAB:INITL

>; FINALLY, LOCATE THE LINE:

3-7

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM

>;
>;

GBLDEF=$USRTB:O

>;
>; AND DELETE IT.

>EDI RSXBLD.CMD
[PAGE
l]
*PL TTDRV
[l,2x]RSXllM/LB:TTDRV
*I
[l,2x]RSX11M/LB:XXDRV

*PL SYSTB
[l,2x]RSXllM/LB:LOADR:NULTK:SYSTB:SYTAB:INITL
*C/SYSTB/SYSTB:USRTB/
[l,2x]RSX11M/LB:LOADR:NULTK:SYSTB:USRTB:SYTAB:INITL
*PL $USRTB
GBLDEF=$USRTB:O
*D

*EX

[EXIT]

>;
>; YOUR NON-LOADABLE DRIVERS WILL AUTOMATICALLY BE LINKED
>; WITH THE EXECUTIVE YOU ARE BUILDING.
This completes the user-written resident driver section
which then continues.

3.3

Phase

USER-WRITTEN LOADABLE DRIVERS

The procedure for incorporation of a user-written loadable driver
depends on the nature of the data base associated with the driver.
The data base for such a driver can be either resident or loadable.
In deciding whether the data base for your loadable driver will be
resident or loadable, you should consider the following limitations on
loadable data bases:
1.

A loadable data base is only lo~ded once;
thereafter it is
resident
until the system is bootstrapped again.
The
UNL[OAD] command does not remove a data base from memory even
if the data base was loaded with the LOA[D] command.

When installing a loadable driver in memory, the LOA[D]
command searches first for a resident data base.
If it finds
one, it uses that and ignores the loadable version of the
data base that may accompany the driver image on disk.

When loading a data base, LOA[D]
relocates certain known
pointers within the control blocks.* If the data base
requires relocation of additional address pointers beyond the
standard ones,
it cannot be loaded with LOA[D].
It must be
incorporated into the system as a resident data base by means
of SYSGEN.

* The pointers are:
(DCB) D.LNK, D.UC:B;
(UCB) U.DCB, U.RED, U.SCB.
(SCB)
S.LHD+2.
Chapter 4 gives details on these and other fields in
the data base.

3-8

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
During debugging of a loadable driver (with loadable data base),
you
can correct errors in the coding of the driver itself by unloading it,
modifying,
assembling,
task-building,
and reloading the
driver.
However,
if the data base must be replaced,
the system must be
bootstrapped to remove it.
You can then modify,
assemble,
and
task-build the data base,
and reload it along with the (corrected)
driver.
The subsections below describe the procedure for
user-written loadable driver as follows:

incorporation

Creating the data base for a loadable driver.

Assembling a loadable driver and its data base.

Adding the driver and its data base to the system library.

Task-building a loadable driver.

Loading a user-written loadable driver.

Creating the Data Base for a Loadable Driver

3.3.1

In creating the data base for your loadable driver,
you must decide
whether the data base will be resident or loadable.
If you decide
upon a resident data base, you follow the procedure for creating the
data base of a resident driver with the exception of initializing the
device interrupt vector (see Section 3.2.1).
If, however, you decide
upon a loadable data base for your driver, you take the following
steps:
1.

While both the loadable driver and its data base can be
contained in the same source module, it is recommended that
you create separate sources for your driver and its data
base.
If,
however,
you place both the data base and the
driver in the same module, you must ensure that, when linked,
the data base follows the driver code. You can do this by
physically placing the data base code after the driver code
or by using .PSECT names to force proper allocation.

A useful convention is to name your data base source xxTAB
and your driver source xxlDRV where xx is the 2-character
device mnemonic.

Place the DCB first
in the assembly source.
This is
absolutely required.
In a multiuser protection system, the
DCB must be followed first by the associated UCB(s) and then
by the SCB(s). All UCB(s) associated with a particular DCB
must be contiguous.
DIGITAL-supplied drivers use
this
ordering scheme--for examples see the file [11,10] SYSTB.MAC
created by Phase 1 of SYSGEN.
Since you are creating a
loadable data base for a single driver, your source code will
contain a single DCB with associated UCB(s) and SCB(s).

The global
data base
end of the
word
of
required.

label $xxDAT:: marks the start of your driver's
(the DCB). The global label $xxEND:: marks the
data base (i.e., immediately following the final
the data base).
These labels are absolutely
xx represents the 2-character device mnemonic.

3-9

May 1979

INCORPORATING USER-WRITTBN DRIVERS INTO RSX-llM
3.3.2

Assembling a Loadable Driver and Its Data Base

During SYSGEN Phase 2, you can assemble your loadable drivers at the
same time that you assemble resident drivers. To do this, you would
use the following command line:
MAC>xxDRV,xxDRV=[l,l]EXEMC/ML, [200,200]RSXMC/PA:l,xxDRV
If you decided upon a resident data base for your loadable driver,
assembly of the data base durin9 SYSGEN Phase 2 is described in
Section 3.2.2.
If, however, you are using a loadable data base for
your driver
(and assuming that you choose to assemble it at the same
point during SYSGEN Phase 2), use the following input to MAC:
MAC>xxTAB,xxTAB=[l,l]EXEMC/ML, [200,200]RSXMC/PA:l,xxTAB

3.3.3

Adding the Driver and Its Data Base to the System Library

If you are using a resident data basE~ for your driver, the data base
is added to the Executive object module library during SYSGEN Phase 2.
For loadable data bases, however, you use the following command to add
both the d~iver and its data base to the same library:
LBR>RSXllM/RP = [200,200]xxDRV,xxTAB

3.3.4

Task-Building a Loadable Driver

In this section, two examples of task-building a loadable driver with
a loadable data base are presented:: one for a mapped system and one
for an unmapped system.
3.3.4.l Task-Building a Loadable Driver on a Mapped
following seven requirements apply to task-building
driver, whether user-written or DIGITAL-supplied.
1.

System - The
any loadable

You must specify a task--image filename and a
symboldefinition filename as TKB output. Both files must be placed
in the UFO corresponding to the system UIC that will be in
effect when the LOA[D] command is issued. The filenames must
both be xxDRV, where xx is the device mnemonic~
The Task
Builder produces output files named xxDRV.TSK and xxDRV.STR.
For example, the beginning of input to TKB to build a
paper-tape reader driver for a mapped system might look like
this (user input underlined):
>TKB
TKB> [l,54]PRDRV/-HD/-MM, ,, [l,54]PRDRV=

Task image. Switches: see
items 2 & 3
below.
2.

t Symbol
definition.

You must not have a task header. Use the switch /-HD, as in
the example above.
A driver is not really a task, but an
extension of the Executive, and as such needs no task header.

3-10

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
3.

You must use the /-MM switch, whether in fact the
destined for a mapped or an unmapped system.

driver

You must link to the system symbol-table file that contains
definitions of Executive global symbols.
Continuing the
paper-tape reader driver example from Item 1 above,
further
TKB input might look like this:
TKB>[l,24]RSX11M/LB:PRDRV:PRTAB
TKB>[l,54]RSX11M.STB/SS
The first line above specifies the library file
(/LB)
in
which the input driver object module and the object file for
the loadable data base can be found.
The object module
specification
for
the driver must always precede the
specification for the data base in the TKB command line.
You omit the data-base file specifier when task-building any
DIGITAL-supplied driver or one of your own drivers if it has
a resident data base. All DIGITAL-supplied drivers that are
declared loadable at SYSGEN use resident data bases.
The second line in item 4, above,
indicates that the
symbol-table file RSXllM.STB is to be searched selectively
(/SS) for definitions of Executive global symbols. Note that
the /SS switch must appear in this context.
It cannot be
omitted.

You must link to the system library file that defines masks
and offsets used in the Executive. Continuing the example:
TKB>[l,l]EXELIB/LB
TKB>/_
The singlE: slash begins the option phase of the Task Builder.

You must direct the Task Builder not to allocate space for
stack within the driver:

TKB>STACK=O
7.

You must specify a partition
for
the
driver.
The
specification
differs for mapped and unmapped systems.
Continuing the mapped-system example:
TKB>PAR=DRVPAR:l20000:4000
TKB>//

On mapped systems the starting address of the partition must
be 120000 octal. That is, the loadable driver must be mapped
to kernel APRS.
On unmapped systems,
the second parameter
physical starting address of the partition.

the

On either mapped or unmapped systems the length of
partition may not exceed 4K words (20000 octal bytes).

the

3-11

must

INCORPORATING USER-WRITTE:N DRIVERS INTO RSX-llM
3.3.4.2 Task-Building a Loadable Driver on an Unmapped System - In
the example below, we build a magtape driver for an unmapped system.
The only differences from the mapped-system example are the partition
starting address and the UIC of some of the files ([1,50] and [l,20]
instead of [1,54] and [1,24]).
>TKB
TKB>[l,50]MTDRV/-HD/-MM,, [l,50]MTDRV=
TKB> [ 1, 2 0] RSXl lM/LB: MTDRV: MTTA.B
TKB>[l,50]RSX11M.STB/SS
TKB>[l,l]EXELIB/LB
TKB>/
ENTER OPTIONS:_.}
TKB>STACK=O
~
TKB>PAR=DRVPAR:34000:4000
TKB>//

3.3.5

Loading a User-Written Loadable Driver

Loading is done by using the privileged MCR command LOA[D].
is:

Its

form

LOA[D] xx: [/PAR=partition]
where xx is the 2-character device mnemonic. Specifying a partition
is optional.
If none is specified, the partition input to the Task
Builder is used.
The LOA[D] command requires that the two files xxDRV.TSK and xxDRV.STB
reside under the system UIC
(i.e., the UIC established by the SET
/SYSUIC command). Typically, this UIC is [1,50] for unmapped systems
and [1,54] for mapped systems.
LOA[D] searches first for a resident data base for the driver being
loaded.
If none is found,
LOA[D]
looks for the following global
symbols in the file xxDRV.STB:

3.4

$xxDAT::

address of the st.art of the data
associated with t.he driver

base

(the

DCB)

$xxEND::

address+2 of the last word
associated with the driver.

the

data

base

DRIVER DEBUGGING

Because the protection checks provided for user programs are not
available to system modules, driv1:r errors are more difficult to
isolate than user-program errors. But conventional drivers,
because
they are modular and short, should be easily debugged. This debugging
process requires that you understand the following topics, each of
which is discussed in a separate subsection:
1.

Debugging aids and tools.

Fault isolation.

Fault tracing

Rebuilding and reincorporating a driver.

3-12

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
3.4.1

Debugging Aids

Adding a user-written driver carries with it the risk of introducing
obscure bugs into an RSX-llM system. Since the driver runs as part of
the Executive, special debugging tools are both desirable
and
necessary.
RSX-llM
provides several such aids, which can be
incorporated into your system during SYSGEN:
1.

Executive stack and register dump

XDT

Panic dump

Crash dump analysis (CDA) support routine.

You need
you do
thre!e of
support
describe

not select any of this software during SYSGEN.
If, however,
require the facilities they offer, you can select from one to
them for incorporation in your system (panic dump and the CDA
routine are mutually exclusive) • The following subsections
the features and use of each debugging aid.

3.4 .. 1.1 Exec:utive Stack and Register Dump Routine - At SYSGEN, you
can indicate~ that you want a dump of the Executive stack and the
registers when a crash occurs. This dump will be provided in the
following manner:
1.

A system error, or the XDT X command (described in the next
section), or operator manipulation of the switch register
following a halt causes processing to resume at location
40(8).

Location 40(8) contains a JMP to location $CRASH.

$CRASH invokes the routine that dumps the Executive stack and
registers as shown below:
SYSTEM CRASH AT LOCATION 047622
REGISTERS
R0=000340 Rl=l77753 R2=000353 R3=000000
R4=000004 R5=046712 SP=000472 PS=000340
SYSTEM STACK DUMP
LOCATION CONTENTS
0004 72
000474
000476
000500
000502
000504
000506
000510
000512
000514
000516
000520
000522

000004
000000
001514
000340
177753
000353
000000
000000
057750
002504
030011
100340
000340

3-13

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
LOCATION CONTENTS

,_!1.,1\
i

000524
000526
000530
000532
000534
000536
000540
000542

056446
000000
102144
000000
101376
101372
102022
170000

Following this display, either the CDA support routine or panic dump
is invoked -- if either is present in the system. Otherwise, the
system halts.

3.4.1.2 XDT - The Executive Debugging Tool - An interactive debugging
tool has been developed for RSX-llM to aid in debugging Executive
modules, I/O drivers, and interrupt service routines. This debugging
aid, called XDT, is a version of RSX-11 ODT. XDT does not contain the
following features and commands available on ODT:
No $M -

(Mask)

No $X -

(Entry Flag) registers

No $V -

(SST vector) registers

No $D -

(I/O LUN)

No $E -

(SST data) registers

No $W -

(Directive status word) !?DSW word

registers

No E

- (Effective Address Search) command

No F

- (Fill Memory) command

- (Not word search) command
No v - (Restore SST vectors) command
No N

No w

- (Memory word search) command

In addition, the X (Exit) ODT command has been changed for XDT.
command causes a jump to the crash reporting routine.

The X

Except for the omitted features and the change in the X command, XDT
is command-compatible with RSX-11 ODT; consequently, the RSX-11 ODT
Manual can be used as a guide to XDT operation.
XDT may be included in a system durin9 Phase 1 of
The query:
DO YOU WANT TO INCLUDE THE

EXECU~~IVE

system

generation.

DEBUGGING TOOL? [Y/N] :

is posed.
If the answer is affirmative, then XDT is automatically
included in the generated system.
When the resultant system is
bootstrapped, XDT gains control and types on the console terminal:
XDT:

followed by the prompting symbol
XDT>
3-14

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
You can set breakpoints at this time,
and then give a G command,
passing
control
to the RSX-llM Executive initialization code.
Whenever control reaches a breakpoint, a printout similar to that of
RSX-11 ODT occurs.
A forced entry to XDT can be executed at any time from a privileged
terminal by means of the MCR Breakpoint (BRK) command. Thus, the
normal procedure is to type G when the system is bootstrapped without
setting any breakpoints.
When it becomes necessary to use XDT, the
MCR Breakpoint command is executed, causing a forced breakpoint.
XDT
then prints on the console terminal:
BE:xxxxxx
followed by the prompting symbol
XDT>
You can then set breakpoints and/or
issue other XDT commands.
Continue system operation by typing the P (Proceed) command to XDT.
Note that XDT runs entirely at priority level 7 and does not interfere
with user-level RSX-11 ODT.
In other words, user-level RSX-11 ODT can
be in use with several tasks, while XDT is being used to debug
Executive modules.
All XDT command I/O goes to and from the console terminal, and the L
(List Memory)
command can list on either the console or the line
printer.
Using XDT to debug a loadable driver on a mapped system
pitfalls. One problem that can arise is a T-bit error:

has

special

TE:xxxxxx
XDT>
This error results when control reaches a breakpoint that you have
set,
using XDT,
in a loaded driver on a mapped system.
The T-bit
error, rather than the expected BE:
error, occurs unless register
APR!5 is mapped to the driver at the time XDT sets the breakpoint.
To avoid this T-bit error, assemble the driver with an embedded BPT
instruction or use either the ZAP utility or the MCR OPEN function to
set the breakpoint by replacing a word of code with the BPT
instruction.
When control reaches a breakpoint set in this manner,
XDT prints:
BE:xxxxxx
XDT>
Recover as follows:
using XDT, replace the BPT instruction with the
desired instruction.
Decrement the PC by subtracting 2 from the
contents of register R7.
Then proceed by using the P or S commands.
NOTE
You should not set breakpoints in more
than one module that maps into the
Executive through APR 5 or APR 6.
In
particular, do not set breakpoints in
more than one loadable driver at a time
or XDT will overwrite words of main
memory when it attempts to restore the
contents of breakpoints.
3-15

INCORPORATING USER-WRITTE:N DRIVERS INTO RSX-llM
3.4.1.3 Panic Dump - The Panic Dump routine (PANIC)
saves registers
RO through R6 and then halts, awaiting dump Limits to be entered.
The procedure for entering dump limits depends on whether or not your
processor has a console switch register. The subsections that follow
describe the procedure in each instance.

with
Console
Switch
3. 4 .1. 3 .1 Using
PANIC
on
Proce·ssors
Registers - For processors with console switch registers, you can
obtain dumps of selected blocks of memory by using the following
procedure:
1.

Enter the low dump limit in the console switch register
press CONT. The processor will immediately halt again.

and

Enter the high dump limit in the console switch register and
press CONT.
The dump will begin on the device whose CSR
address is D$$BUG (usually 177514, which is the
line
printer).
The actual value of D$$BUG is determined during
system generation when answering the panic dump question. At
the end of the dump, the processor will again halt, awaiting
the input of another set of dump limits.
If your system does not have the Executive routine stack and
register dump, enter the dump limits 0-520(8) when the Panic
Dump routine first halts. This causes dump of the system
stack and the general registers. The limit 520(8) changes if
the highest interrupt vector is above 400(8).
The actual
upper limit is always the value of the global symbol $STACK
and can be obtained from the global symbol listing in the
Executive memory allocation map.

3.4.1.3.2 Using PANIC
on
Processors
Without
Console
Switch
Registers - A number of PDP-11 processors are being delivered without
a console switch register;
they are configured with the M9301 Console
Emulator and Bootstrap.
This presents no problem for the normal
operation of RSX-llM, because it does not require a switch register.
However, the panic dump routine usually reads its arguments from the
switch register. In systems that have been generated for processors
that have no switch register, the panic dump module has been altered
to read its arguments from location 0. The following instructions are
designed to allow you to enter the proper information to the panic
dump routine on processors equipped with the M9301 Console Emulator.
1.

When PANIC halts, the RUN light will go out.
press and release the BOOT switch.

this

The Console Emulator should display:
XXXXXX XXXXXX XXXXXX nnnnnn
$

Where nnnnnn is the address+2 of the HALT instruction.
2.

You should enter the following:
$L O<CR>
$D low-address<CR>
$L nnnnnn<CR>
$8 <CR>

3-16

time

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
3.

The processor should again halt.
switch.

Press and release the

BOOT

The Console Emulator should display:
XXXXXX XXXXXX XXXXXX mmmmmm
$
4.

You should then enter:
$L O<CR>
$D high-address<CR>
$L mmmmmm<CR>
$S <CR>

At this time the dump should commence.
When it
processor will halt and wait for additional input.

finished,

the

3.4.1.3.3 Sample Output from Panic Dump - A portion of the output
from Panic Dump is shown below.
Output is in 3-line groupings.
In
the left-hand column, two addresses are shown.
The first address is
the absolute address;
the second address is the dump relative
address.
The first line in a 3-line group gives the octal word value;
the second line gives the two octal byte values of the word;
the
third line contains the ASCII representation of the bytes.
The ASCII
representations in each word are reversed to improve readability.
The
first output grouping from Panic Dump shows, proceeding from right to
left, PS, RO, Rl, R2, R3, R4, RS, and the SP.
000544 000000 046076 000066 000000 000000 000000 000000 045316
000000 000 000 114 076 000 066 000 000 000 000 000 000 000 000 112 316
A@
A@
>
L
6 A@
A@
A@
A@ A@
A@
A@
A@ A@
N
J
000000 022646 000340 045770 000340 045770 000340 045770 000340
000000 045 246 000 340 113 370 000 340 113 370 000 340 113 370 000 340
&
%
A@
K
A@
K
A@
K
A@
000020 045776 000340 011124 000340 045770 000340 050500 000340
000020 113 376 000 340 022 124 000 340 113 370 000 340 121 100 000 340
K
A@
T AR
A@
K
A@
@
Q
A@
000040 000167 000543 000001 000001 000000 000000 000000 000353
000040 000 167 001 143 000 001 000 001 000 000 000 000 000 000 000 353
A@
AA AA A@
AA A@
A@
A@
A@
A@
A@
A@
A@

000060 035444 000340 034034 000340 032776 000340 032402 000340
000060 073 044 000 340 070 034 000 340 065 376 000 340 065 002 000 340
$
A@
A\
8
A@
5
A@
AB
5
A@

3.~1.1.4

Crash Dump Analysis Support Routine - The crash dump analysis
(CDA) support routine, when entered, prints the following message on a
notification device specified at SYSGEN:
CRASH - CONT WITH SCRATCH MEDIA ON device mnemonic

3-17

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
You can then put the secondary crash dump device on-line and depress
the CONT switch on the operator's console. The Executive Crash Dump
routine will dump memory to the crash dump device and halt the
processor upon completion.

~
11-·

The procedure for subsequently invoking the Crash Dump Analyzer, which
reads and formats the memory dump, is fully documented in the RSX-llM
Crash Dump Analyzer Reference Manual.

3.4.2

Fault Isolation

Four causes can be identified when the system faults:
1.

A user-state task has faulted in such a way
the system to fault.

that

The user-written driver has faulted in such
causes the system to fault.

The RSX-llM system software itself has faulted.

The host hardware has faulted.

way

causes
that

When the system faults, you must immediately determine which of these
four
causes is responsible.
In this section we present some
procedures that can help you isolate the source of the fault.
Correcting the fault itself is your r(~sponsibility.

3.4.2.l Immediate Servicing - Faults manifest themselves in roughly
four ways
{they are listed here in order of increasing difficulty of
isolation):
1.

If XDT is included, an unintended trap to XDT occurs.

The system displays text indicating a crash has occurred
halts.

The system halts but displays nothing.

The system is in an unintended loop.

and

The following discussions assume the E!Xistence of a system built with
at least one of the debugging aids dE!Scribed in Section 3.4.l.
{Note
that the minimal system does not have space for these routines.)
The immediate aim, regardless of the fault manifestation, is to get to
the point where you can obtain pertinent fault isolation data.
Case 1--The system has trapped to XDT:
The trap may or may not be intended {for example, a previously set
breakpoint).
If it is not intended, type the X command, causing XDT
to exit to location 40(8), from which the Executive stack and register
dump routine
{if present)
followed by either Panic Dump or the CDA
support routine {if present) will be invoked.
If, however, you have
some idea of the source of the problem {for example, a recent coding
change), then you may use XDT to examine pertinent data structures and
code.

3-18

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
Case 2--The system has displayed text indicating a crash has occurred:
If the text consists of output from the Executive stack and register
dump routine
(refer to Section 3.4.1.1), all the basic information
describing the state of the system has been displayed.
If the text
has been produced by the CDA support routine, follow the procedure for
obtaining and formatting a memory dump as outlined in the RSX-11 Crash
Dump Analyzer Reference Manual.
Case 3--The system has halted but displays no information:
Before taking any action, preserve the current PS and PC and the
pertinent
device
registers
(that is, examine and record the
information these registers contain) . The procedure depends on the
particular PDP-11 processor. Consult the appropriate PDP-11 Processor
Handbook for details.
After preserving the PS and PC, invoke your resident debugging aid:
enter 40(8)
in the switch register, press LOAD ADDR, and then press
STJ~RT.
The contents of 40(8) cause the successive invocation of:
1.

The Executive stack and register dump routine (if present).

Either Panic Dump or CDA support routine (if present).

Case 4--The system is in an unintended loop:
Proceed as follows:
1.

Halt the processor.

Record the PC, the PS, and any pertinent device registers, as
in Case 3 above.

You may then want to step through a number of instructions in an
attempt to locate the loop.
For this attempt to be meaningful you
must first disable the system clock.
Proceed as follows:
Examine the
contents of word 777546 (if your system has a line-frequency clock) or
word 772540 (if a programmable clock).
Clear bit 6 in this word and
redeposit the word.
Note:
the system will not run until you have
reenabled the clock.
After trying to locate the loop and reenabling the clock, transfer
location 40(8) as in Case 3.

This brings us to an equivalent status for the four fault situations.

3.4.2.2 Pertinent Fault Isolation Data - Before you attempt to locate
the fault,
we strongly advise you to dump system common (SYSCM).
SYSCM contains a number of critical pointers and listheads.
Find the
appropriate limits for
the module SYSCM by examining the Executive
memory allocation map.
Enter these limits to the Panic Dump routine
or specify them in the command line used to invoke the Crash Dump
Analyzer.
In addition, we advise you to dump the dynamic storage region and the
device tables. The dynamic storage region is the module INITL and any
additional space gained from the SET /POOL command and the device
tables are in SYSTB.

3-19

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
At this point, you have the following data:
PS
PC
The Stack
RO through R6
Pertinent device registers
The dynamic storage region
The device tables
System common
These data represent a minimal requirement for effectively tracing the
fault.

3.4.3

Fault Tracing

Three pointers in SYSCM are critical in fault tracing.
are described below:

These pointers

$STKDP - Stack Depth Indicator
This data item indicates which stack was being used at the time
of the crash.
$STKDP plays an important role in determining the
origin of a fault.
The following values apply:
+1--User (task-state) stack
0 or less--System stack
If the stack depth is +l, then the user has crashed the system.
In a system with brickwall protection (for example, the mapped
RSX-llM system), the nonprivileged user should not be able to
crash the system.
$TKTCB - Pointer to the Current Task Control Block (TCB)
This is the TCB of the user-level task in control of the CPU.
$HEADR - Pointer to the Current Task Header.
The $HEADR word points to the header of the task currently
running.
The task header provides additional data to help
isolate a fault.
Figures 3-1 and 3-2 show the layout of task
headers for unmapped and mapped systems, respectively.
The first word in the header is the user's stack pointer (SP) the
last time it was saved.
If the user branches wildly into the
Executive, the Executive terminates the user task, but the system
continues to function (possibly erroneously).
Knowing the user's
stack pointer provides one more link in the chain that may lead
to the resolution of the fault.
The header (as pointed to by $HEADR) also contains the last-saved
register set, just before the header guard word (the last word in
the header--pointed to by H.GARD).

3-20

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM

r----i

0
RO
R1
R2

•

..
.
H.NLUN
H.GARD

N
~

PS
PC

H.HDLN

Length in bytes

·---._______.----SP
R4
~·

Figure 3-1

Task Header on an Unmapped System

t------i

..
.
Ra::·
~·
PC

H.NLUN
H.GARD

H.HDLN

I---

Length in bytes

Figure 3-2

Task Header on a Mapped System
3-21

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
3.4.3.l Tracing Faults Using the Executive Stack and
Register
Dump - To trace a fault after a display of the Executive stack and
register contents, first examine the system stack pointer.
Usually an
Executive failure
is the result of an SST-type trap within the
Executive.
If an SST does occur within the Executive, then the origin
of the call on the crash-reporting routine is in the SST service
module.
(The crash call is initiated by issuing an IOT at a stack
depth of zero or less.)
A call to crash also occurs in the Directive Dispatcher when an EMT is
issued at a stack depth of zero or less, or a trap instruction is
executed at a stack depth of less than zero. The stack structure in
the case of an internal SST fault is shown in Figure 3-3.

PS
PC

~\.
R5
R4
R3
R2
R1
RO
Return to system exit
Zero or more SST parameters
SST fault code
-------SP

Number of bytes

Figure 3-3

Stack Structure:

Internal SST Fault

The fault codes are:
0

2
4
6

10
12
14
16
20
22
24
26
30
32
34

;ODD ADDRESS AND TRAPS TO 4
;MEMORY PROTECT VIOLATION
;BREAK POINT OR TRACE TRAP
;IOT INSTRUCTION
;ILLEGAL OR RESERVED INSTRUCTION
;NON RSX EMT INSTRUCTION
;TRAP INSTRUCTION
;11/40 FLOATING POINT EXCEPTION
;SST ABORT-BAD STACK
;AST ABORT-BAD STACK
;ABORT VIA DIRECTIVE
;TASK LOAD READ FAILURE
;TASK CHECKPOINT READ FAILURE
;TASK EXIT WITH OUTSTANDING I/O
;TASK MEMORY PARITY ERROR

3-22

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
The PC points to the instruction following the one that caused the SST
failure.
The number of bytes is the number normally transferred to
the user stack when the particular type of SST occurs.
If the number
is 4, then a non-normal SST fault occurred, and only the PS and PC are
transferred.
There are no SST parameters.
If the failure is detected in $DRDSP, the stack is the same as shown
in Figure 3-3, except that the number of bytes, the SST fault code
(the fault codes are listed above) , and the SST parameters are not
present.
The crash report message, however, will indicate that the
failure occurred in $DRDSP.
One SST-type failure, stack underflow, does not result in the stack
structure of Figure 3-3.
To determine where the crash occurred, first
establish the stack structure;
this can be deduced by the value of
the SP and the contents of the top word on the stack.
If the stack
structure is that of Figure 3-3, then the failure occurred in $DRDSP,
or was a normal SST crash.
If the stack structure is that of Figure
3-4, then an abnormal SST crash has occurred.

Figure 3-4

Stack Structure:

Abnormal SST Fault

Abnormal SST failures occur when it is not possible to
push
information on the stack without forcing another SST fault.
When this
situation occurs, a direct jump to the crash-reporting routine is made
rather than an IOT crash.
The PS and PC on the stack are those of the
actual crash, and the address printed out by the crash-reporting
routine is the address of the fault rather than the address of the IOT
that crashes the system.
Note that the crash-reporting routine
removes the PC and PS of the IOT instruction from the stack, which in
this case is incorrect.
Thus, the SP appears to be 4 bytes greater
than it really is (as in Figure 3-4).
You now have all the information needed to isolate the cause of the
failure.
From this point on,
rely on personal experience and a
knowledge of the interaction between the driver and the services
provided by the Executive.

3.4.3.2 ~rracing Faults When the Processor Halts Without Display - To
trace a fault when the processor halts but displays no information
(case 3 in Section 3.4.2.1 above), first examine $STKDP,
$TKTCB,
and
$HEADR.
The difficulty in tracing failures in this case is that the
system stack is not directly associated with the cause of a failure.
By examinin9 $STKDP, you can determine the system state at the time of
failure.
If it was in user state, the next step is to examine the
user's stack. The examination focuses on scanning the stack for
addresses that may be subroutine links that can ultimately lead to a
thread of events isolating the fault.
This is essentially the aim of
looking at the system stack if $STKDP is zero or less.

3-23

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
Frequently, a fault can occur that causes the SP to point to Top of
Stack
(TOS)+4.
This fault results from issuing an RTI when the top
two items on the stack are data.
The result is a wild branch and
then, most probably, a halt.
Figure 3-5 shows a case in which two
data items are on the stack when the program executes an RTI.
TOS
points to a word containing 40100.
Suppose that location 40100
contains a halt. This indicates that the original SP was four bytes
below the final SP, and fault tracing should begin from the original
SP.

5
40100

Figure 3-5

Stack Structure:

Data Items on Stack

This type of fault also occurs when an RTS instruction is executed
with an inconsistent stack.
However,
in that case, SP points to
TOS+2.
A scan of the contents of the general registers may give some hint as
to the neighborhood in which a fault
(or the sequence of events
leading up to the fault) occurred.
If the fault occurred in a new driver, a frequent source of clues is
the buffer address and count words in the UCB (U.BUF, U.BUF+2, U.CNT),
as are the activity flags (US.BSY and S.STS). Other locations in both
the UCB and SCB may also provide information that may help locate the
source of the fault.

3.4.3.3 Tracing Faults After an Unintended Loop - To trace a
when an unintended loop has occurred, first halt the processor.

fault

After you halt the processor, the same state exists as was discussed
in Section 3.4.3.2.
Follow the same tracing procedure described
there. A specific suggestion is to ch1~ck for a stack overflow loop.
Patterns of data successively duplicated on the stack indicate a stack
looping failure.

3. 4. 3. 4 Additional Hints for Tracing :f!'aul ts - Another i tern to check
is the current (or last) I/O Packet, the address of which is found in
S.PKT of the SCB.
The packet function
(I.FCN}
defines the last
activity performed on the unit.
If trouble occurred in terminating an I/O request, a scan of the
system dynamic memory region may provide some insight. This region
starts at the address contained in $CRAVL, a cell in SYSCM.
Because
all I/O packets are built in system dynamic memory, their memory is
returned to the dynamic memory region when they are successfully
terminated.
Following the link pointers in this region may reveal
whether I/O completion proceeded to that point.
In systems with QIO
optimization, $PKAVL
(SYSCM}
points to a list of I/O packet-sized
blocks of dynamic memory that are not linked into the $CRAVL chain.

3-24

INCORPORATING USER-WRITTEN DRIVERSS INTO RSX-llM
A frequent error for an interrupt-driven device is to terminate an I/O
Packet twice when the device is not properly disabled on I/O
completion and an unexpected interrupt occurs.
This action ultimately
produces a double deallocation of the same packet of dynamic memory.
Double deallocation of a dynamic buffer in RSX-llM causes a loop in
the module $DEACB on the next deallocation (of a block of higher
address) after the second deallocation of the same block.
At that
time, R2 and R3 both contain the address of the I/O Packet memory that
has been doubly deallocated.
If XDT has been included in the system,
the deallocation routine checks for bad deallocation and crashes the
system if it occurs.

3.4.4

Rebuilding and Reincorporating a Driver

The procedure for rebuilding and reincorporating a driver
into your
system depends on whether the driver is resident or loadable.
The two
subsections that follow describe the procedure for
each kind of
driver.

3.4.4.1 Rebuilding and Reincorporating a
Resident
Driver - The
procedure
for
rebuilding and reincorporating a
resident driver
involves five steps:
1.

Correct and
structures.

assemble

the

driver

and/or

device

data

Assuming that the object system has been bootstrapped,
appropriate volumes have been MOUnted, and the source code
for the user driver and/or device data base has been updated,
then the following commands effect the reassembly of both the
driver and the data base:
>SET /UIC=[200,200]
>RUN $MAC
OR RUN $BIGMAC
MAC>XXDRV=[l,l]EXEMC/ML, [200,200]RSXMC/PA:l,XXDRV
MAC>USRTB=[l,l]EXEMC/ML, [200,200]RSXMC/PA:l,USRTB
MAC>xZ

Update the Executive object module library.
After reassembling the user driver and/or data base, you must
update the Executive object module library.
The following
commands will accomplish this:
>SET /UIC=[l,2x]
>RUN $LBR
LBR>RSX11M/RP=[200,200]XXDRV,USRTB
LBR>xZ

Rebuild the Executive.
Because an updated driver
is to be reinserted into the
system, the Executive, of which the driver is a part, must be
relinked.
The following commands are an example of this
relinking:

3-25

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM

>SET /UIC=[l,2x]
>RUN $TKB
TKB>@RSXBLD

OR RUN $BIGTKB

TKB>~

>SET /UIC=[l,Sx]
>RUN $PIP
PIP>RSXllM.SYS/NV=RSXllM.TSK
PIP>" Z
4.

Incorporate tasks into the system using Virtual MCR.
Run Virtual MCR (VMR) to incorporate tasks into
This step in the procedure requires that you:

the

system.

dynamic

storage

•

Establish system partitions

•

Release all
region

•

Install tasks (at least FCP, INS, MOU, and MCR)

•

Exit from Virtual MCR

unused

space

the

The following is an example of this step:
>RUN $VMR/UIC=[l,5x]
! RUN VIRTUAL MCR
ENTER FILENAME:RSXllM.SYS
! VMR PROMPTS FOR FILE NAME
VMR>SET /MAIN=SYSPAR:l300:100:TASK
SET UP SYSTEM PARTITION
VMR>SET /MAIN=PAR14K:400:700:TASK ! SET UP 14K PARTITION
VMR>SET /SUB=PAR14K:GEN:400:400
! SET UP BK SUB PARTITION
VMR>SET /POOL=400
. ADD FREE SPACE TO POOL
VMR>INS BOO
INSTALL BOOT
VMR>INS DMO
INSTALL DISMOUNT
VMR>INS FCPNMH
INSTALL FILE SYSTEM
VMR>INS IND
INS'TALL INDIRECT FILE PROCESSOR
VMR>INS INI
INSTALL INITVOLUME
VMR>INS INS
INSTALL INSTALL
VMR>INS MCR
INSTALL MCR
VMR>INS MOU
INSTALL MOUNT
VMR>INS SAV
INSTALL SAVE
VMR>INS TKN
INSTALL TASK TERMINATION TASK
VMR>INS UFD
INSTALL USER FILE DIRECTORY BUILDER
VMR>"Z
EXIT FROM VIRTUAL MCR
The eleven INStall commands above can be placed in an
indirect VMR file by Phase 2 of SYSGEN.
Instead of entering
each command, you could then enter, for example,
the
following:
@[200,200]INSTALL
5.

Bootstrap the new system.
The new system can now be bootstrapped with the MCR BOOt
command.
If you are using the baseline system, first issue
the following command:
>INS B00;-1
Then issue the following command:
>BOO (l,Sx]RSXllM

3-26

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
NOTE
If the newly created Executive is larger
or smaller than the old one, the system
may not run properly after exiting VMR.
In this case the procedure outlined
above amounts to supporting two systems
on the same volume.
See the RSX-llM
System
Generation
Manual
for
the
procedure to follow to support multiple
systems on one volume.

3.4.4.2 Rebuilding and Reincorporating a Loadable Driver - A loadable
driver is easier to reincorporate during debugging than a resident
driver. After correcting and assembling the driver source, simply
unload the old version, using the MCR command UNL, task-build the new
one, and load it using the LOA command.
The data structure, once loaded, becomes a permanent part of the
Executive.
It is not removed by the UNL command. If the data
structure is in error and cannot be patched, correct its source,
Then bootstrap the system before
reassemble, and task-build it.
loading the corrected driver.

3-27

CHAPTER 4
WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS

In Chapter

overviews were given for:

Data structures:
Executive services, and
Programming protocol.
This chapter gives details for the data structures, and in addition
discusses specifics of multicontroller drivers and the INTSV$ macro.
Executive services are covered in Chapter 5. The protocol coverage in
the discussion of programming protocol in Chapter 2 is detailed enough
to make further elaboration unnecessary.

4.1

DATA STRUCTURES

The following elements in the I/O data structure are of concern to the
programmer writing a driver:
1.

The I/O packet

The DCB

The UCB

The SCB

The device interrupt vector

The I/O data structure, and the first four control blocks listed above
in particular, contain an abundance of data pertaining to input/output
operations. Drivers themselves are involved with only a subset of the
data.
In the detailed descriptions of the I/O packet, the DCB, the UCB, and
the SCB that follow, most data fields (words or bytes) are classified
by one of five descriptions.
Two items in each description indicate:
•

Whether the
source, and

field

initialized

the

data-structure

•

What sort of access
execution.

the

driver

the

field

4-1

has

during

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
The five descriptions are:
<initialized, not referenced>
Field is supplied in the data-structure source code,
not referenced by the driver during execution.

and

<initialized, read-only>
Field is supplied in the data·-structure source code, and
be read by the driver.

may

<not initialized, read-only>
Either an agent other than the driver establishes this field,
or the driver sets it up once, and thereafter references it
read-only.
<not initialized, read-write>
Either the driver or some other agent establishes this field,
and the driver may read it or write over it.
<not initialized, not referenced>
Field does not involve the driver in any way.
These five descriptions cover most of the fields in the four control
blocks described in this section.
Exceptions are noted in the text.
The final discussion in this section deals with the
vector.

4.1.1

device

interrupt

The I/O Packet

Figure 4-1 shows the layout of the .18-word I/O Packet, which is
constructed and placed in the driver
I/O queue by QIO directive
processing, and is subsequently delivered to the driver by a call to
$GTPKT. The DPB from which the I/O Packet is generated is illustrated
in Figure 4-2 (see Section 4.1.1.2).

4.1.l.l I/O Packet Details - The I/O
QIO directive processing. Thus, no
to a driver.
I/O Packets are created
first parameter
(I.LNK)
does not
(described below) are classified as:

Packet is built dynamically by
static fields exist with respect
dynamically, and therefore the
apply.
Fields in the I/O Packet

Not referenced,
read-only, or
read-write.
I.LNK
Driver access:
Not referenced.
Description:
Links I/O Packets queued for a driver.
A
chain. The listhead is in the SCB (S.LHD).

4-2

zero

ends

the

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
I.EFN
Driver access::
Not referenced.
Description:
Contains the event flag number as copied
processing from the requester's DPB.

l.LNK
1.PRI
LEFN

,,_..,.

Link to next 1/0 packet

}

EFN

0
PRI

i.TCB

TCB address of requester

i.LN2

Address of second LUT word

I.UCB

Address of redirect UCB

Modifier

Virtual address of 1/0 status block

Relocation bias of IOSB

Real address of IOSB

Virtual address of AST service routine

1.FCN

Function code

1.IOSB

I.AST

QIO

I.PAM

r--

t--t---

Device
parameters

t---

r--

Figure 4-1

I/O Packet Format

I. PH.I

Driver access:
Not referenced.
Description:
Priority copied from the TCB of the requesting task.

4-3

directive

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
I.TCB
Driver access:
Not referenced.
Description:
TCB address of the requesting task.
I.LN2
Driver access:
Not referenced.
Description:
Contains the address of the second word of the LOT entry in
the task header to which the I/O request is directed. For
open files on file-structured devices, this word contains the
address of the Window Block; otherwise, it is zero.
I.UCB
Driver access:
Not referenced.
Description:
Contains the address of the unit to which I/O is to be
directed.
I.UCB is the address of the Redirect UCB if the
starting UCB has been subject to an MCR Redirect command.

I.FCN
Driver access:
Read-only.
Description:
Contains the function code (see Table 4-1, Section 4.1.2.2)
for the I/O request.
The modifier byte is one or more
subfunction bits that may be set.
I.IOSB
Driver access:
Not referenced.
Description:
I.IOSB contains the virtual address of the I/O Status Block
(IOSB), if one is specified, or zero if one is not specified.
I.IOSB+2 and I.IOSB+4 contain the address doubleword for
the
IOSB
(see Appendix A for a detailed description of the
address doubleword). On an unmapped system, the first word
is zero; the second word is the real address of the IOSB.

4-4

WRITING AN I/0 DRIVER--PROGRAMMING SPECIFICS
In a mapped system, the first word contains the relocation
bias of the IOSB;
the bias is, in effect, the number of the
32-word block in which the IOSB starts. This block number is
derived by viewing available real memory as a collection of
32-word blocks numbered consecutively, starting with 0.
Thus,
if the IOSB starts at physical location 3210(8), its
block number is 32(8).
The second word is formatted as follows:
Displacement in block
Bits 0-5
Bits 6-12 All zeros
Bits 13-15
6

(DIB)

The displacement in block is the offset from the block base.
In the above example, in which the IOSB starts at 3210(8),
the DIB is equal to 10(8).
The value 6 in bits 13-15 is constant.
It is used to cause
an address reference through Kernel Address Page Register 6
(APR6). Again, see Appendix A for details.
We defer discussion of the address doubleword to an appendix
because you seldom have to be concerned with its contents or
format in writing a conventional driver.
Its construction
and subsequent manipulation are normally external to the
driver. Subroutines are provided as Executive services for
programmed I/O to render the manipulations of I/O transfers
transparent to the driver itself.
I. AS~r

Driver access:
Not referenced.
Description:
Contains the virtual address of the AST service routine to be
executed at I/O completion.
If no address is specified, the
field contains zero.
I.PRM
Driver access:
Not initialized, read-only.
Description:
Device-dependent parameters constructed from the last 6 words
of the DPB.
Note that if the I/O function is a transfer
(refer to the description of D.MSK in Section 4.1.2.1), the
buffer address
(first DPB device-dependent parameter) is
translated to an equivalent address doubleword.
Therefore,
device-dependent parameter n is copied to I.PRM +(2*n)+2.

4-5

WRITING AN I/0 DRIVER--PROGRAMMING SPECIFICS
4.1.1.2 The QIO Directive Parameter
constructed as shown in Figure 4-2.

Block

(DPB) - The

QIO

DPB

directive

The parameters in the DPB have the following meanings.
Length (required):
The length of the DPB, which for the
always fixed at 12 words.

RSX-llM

QIO

DIC (required):
Directive Identification Code.
is 1. For QIOW it is 3.

For the QIO directive, this value

Function Code (required):
The code of the requested I/O function

(0 through 31.).

Length

DIC

Function code

Modifier

Reserved

LUN

Priority

EFN

1/0 status block address

AST address

12
14

Devicedependent
parameters

Figure 4-2

QIO Directive Parameter Block (DPB)

Modifier:
Device-dependent modifier bits.
Reserved:
Reserved byte;

must not be used.

LUN (required):
Logical Unit Number.

""·
4-6

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
Priority:
Request priority.
Ignored by RSX-llM,
allocated for RSX-llD compatibility.

but

space

must

EFN (optional):
Event flag number.
I/O Status Block Address

Zero indicates no event flag.
(optional):

This word contains a pointer to the I/O status block, which is a
2-word, device-dependent I/0-completion data packet formatted as:
Byte 0
I/O status byte.
Byte 1
Augmented data supplied by the driver.
Bytes 2 and 3
The contents of these bytes depend on the value of byte 0.
If
byte 0 = 1,
then these bytes usually contain the
processed byte count.
If byte 0 does not equal 0, then the
contents are device-dependent.
AST Address (optional):
Address of an AST service routine.
Device Dependent Parameters:
Up to six parameters specific to the device and I/O function to
be performed.
Typically,
for data transfer functions,
the
following four are used:
Buff er address
Byte count
Carriage control type
Logical block number
The fields for any optional parameters not specified
with zeros.

4.1.2

•

must

filled

The Device Control Block (DCB)

Figure 4-3 is a schematic layout of the DCB.
The DCB describes the
static characteristics of a device controller and the units attached
to the controller. All fields must be specified except D.PCB, which
is required only if the loadable-driver option has been selected.

4·-7

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
4.1.2.1

DCB Details - The fields in the DCB are described below:

D.LNK {link to next DCB)*
Driver access:
Initialized, not referenced.
Description:
Address link to the next DCB. A zero in this field indicates
the last {or only) DCB in the chain.
D.UCB {pointer to first UCB)
Driver access:
Initialized, not referenced.

D.LNK

Link to next DCB (O=last)

D.UCB

Link to first UCB

D.NAM

Generic device name

D.UNIT

Highest unit no.

Lowest unit no.

D.UCBL.

Length of UCl3

D.DSP

Address of driver dispatch table

D.MSK

Legal function mask bits 0 - 15.

Control function mask bits 0 - 15.

No-op'ed function mask bits 0 - 15.

ACP function mask bits 0 - 15.

Legal function mask bits 16. - 31.

Control function mask bits 16. - 31.

No-op'ed function mask bits 16. - 31.

ACP function mask bits 16. - 31.
D.PCB

. .
Address o f part1t1on control block

32
I
I

L-----------------------J

Figure 4-3

Device Control Block

* Parenthesized contents indicate value to be initialized in the data
base source code.
4-8

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
Description:
Address link to the U.DCB field of the first, and possibly
the only, UCB associated with the DCB. For a given DCB, all
UCBs are in contiguous memory locations and must all have the
same length.
D.NAM (ASCII device name)
Driver

access~

Initialized, not referenced.
Description:
Generic device name in ASCII
mnemonically referenced.

which

device

units

are

D.UNIT (unit number range)
Driver access:
Initialized, not referenced.
Description:
Unit number range for the device. This range covers those
logical units available to the user for device assignment.
Typically, the lowest number is zero, and the highest is n-1,
where n is the number of device-units described by the DCB.
D.UCBL (UCB length)
Driver access:
Initialized, not referenced.
Descr :Lption:
The UCB can have any length to meet the needs of the driver
for variable storage.
However, all UCB's for a given DCB
must have the same length. The specified length must include
prefix words (U.LUIC and U.OWN) if present.
D.DSP (dispatch table pointer)
Driver access:
Initialized, not referenced.
Description:
Address of the driver dispatch table.
When the Executive wishes to enter the driver at any of the
four. entry points contained in the driver dispatch table, it
accesses D.DSP, locates the appropriate address in the table,
and calls the driver at that address. A zero table address
indicates that the (loadable) driver is not in memory. For a
loadable driver, then, this field must be initialized to
zero. If the driver does not process a given function, then
it simply supplies the address of a return.

4-9

May 1979

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
You must provide a driver dispatch table in the driver
source.
The label on this table is of the form $xxTBL:
it
must be a global label.
The designation xx
is
the
2-character generic device name for the device.
Thus, $TTTBL
is the global label on the driver dispatch table for
the
generic device name TT.
This table is an ordered, 4-word
table containing the following entry points:
I/O Initiator
Cancel I/O
Device Timeout
Power failure
When a driver is entered at one of these entry points,
conditions are as follows:

entry

At Initiator:
I f UC.QUE=!

RS
R4
Rl

UCB address
SCB address
Address of the I/O Packet

I f UC.QUE=O

RS = UCB address
Interrupts are allowed.
(UC.QUE is a bit
UCB.
See Section 4.1.4.1.)

U.CTL

the

At Cancel I/O:
RS
R4
R3
Rl
RO

UCB address
SCB address
Controller index
Address of TCB of current task
Address of active I/O packet

Device interrupts at or below the priority of the
requesting device are locked out.
At Device Timeout:

~\
!

RS
R4
R3
R2
RO

UCB address
SCB address
Controller index
Address of device CSR
I/O status code IE.DNR (Device Not Ready}

Device interrupts at or below the priority of the
requesting device are locked out.
At Power Failure:
RS
R4
R3

UCB address
SCB address
Controller index

Interrupts are allowed.
The power fai1ure entry point of
a loadable driver
is called by LOAd only for units that
are online and have UC.PWF set.

4-10

WRITUJG AN I/O DRIVER--PROGRAMMING SPECIFICS

D.MSK (function masks)
Driver access:
Initialized, not referenced.
Description:
There are 8 words, beginning at D.MSK, that are critical to
the proper functioning of a device driver. The Executive
uses these words to validate and dispatch the I/O reauest
specified by a QIO directive.
The following description
applies only to non-file-structured devices.* Four masks,
with
2
words
per
mask,
are described by the bit
configurations that you establish for these words:
1.

Legal function mask

Control function mask

No-op'ed function mask

ACP function mask

•

The QIO directive allows for 32 possible I/O functions.
The
masks,
as stated, are filters to determine validity and I/O
requirements for the subject driver.
The Executive filters the function code in the I/O request
through the four masks.
The I/O function code is the
high-order byte of the function parameter issued with the OIO
directive.
The decimal representation of that high-order
byte is equivalent to the decimal bit number of the mask.
If
you want the function to be true in one of the four masks,
you must set the bit in that mask in the position that
numerically corresponds to the function code.
For example,
the code for IO.RVB is 21
(octal)
and
its
decimal
representation is 17.
If you want IO.RVB to be true for a
mask, you must set bit number 17 in the mask.
The masks are laid out in memory in two 4-word groups.
Each
4-word qroup covers 16 function codes. The first 4 words
cover the function codes 0-15;
the second 4 words cover
codes 16-31.
Below is the exact layout used for the driver
example in Section 6.2.2.
• WORD
• WORD
.WORD
• WORD
• WORD
• WORD
.WORD
• WORD

140033
30
140000
0
5
0
1
4

;LEGAL FUNCTION MASK CODES 0-15 .
;CONTROL FUNCTION MASK CODES 0-15 •
;NO-OP'ED FUNCTION MASK CODES 0-15.
;ACP FUNCTION MASK CODES 0-15 •
;LEGAL FUNCTION MASK CODES 16.-31 •
;CONTROL FUNCTION MASK CODES 16.-31 •
;NO-OP'ED FUNCTION MASK CODES 16.-31.
;ACP FUNCTION MASK CODES 16.-31 .

* Although no DIGITAL publication describes writing drivers for
file-structured devices
(drivers that interface with FllACP), many
users have successfully written a disk/drum driver by using a
DIGITAL-supplied driver as a template.
For example, the RFll driver
(DF'DRV) could be modified to be a drum driver.

4-11

May 1979

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
The mask words filter sequentially as follows:

.......

Legal Function Mask:

; !

Legal function values have the corresponding bit position in
this word set to 1. Function codes that are not legal are
rejected by QIO directive processing, which returns IE.IFC in
the I/O status block, provided an IOSB address was specified.
Control Function Mask:
If any device-dependent data exists in the DPB, and this data
does not require further checking by the OIO directive
processor, the function is considered to be a control
function. Such a function allows QIO directive processing to
copy the DPB device-dependent data directly into the I/O
Packet.
No-op'ed Function Mask:
A no-op function is any function that
is
considered
successful as soon as it is issued. Lf the function is a
no-op, QIO directive processing immediately marks the request
successful; no additional filtering occurs.
ACP Function Mask:
If a function code is legal, but specifies neither a control
function nor a no-op, then it specifies either an ACP
function or a transfer function. If a function code reauires
intervention of an Ancillary Control Processor (ACPj, the
corresponding bit in the ACP :Eunction mask must be set.
ACP
function codes must have a value greater than 7.
In the specific case of read-write virtual functions, the
corresponding mask bits may be set at your option. If the
corresponding mask bits for a read-write virtual function are
set, QIO directive processing recognizes that a file-oriented
function is being requested to a non-file-structured device
and converts the request to a read-write logical function.
This conversion is
particularly
useful.
Consider
read-write virtual function to a specific device:

If the device is file-structured and a file is open
on the specified LUN, the block number specified is
converted from a virtual block number in the file to
a logical block number on the medium, and the reauest
is queued to the driver as a read-write lo~ical
function.

If the device is file-structured and no file is open
on the specified LUN, then an error is returned and
no further action is taken.

If the device is not file-structured, then the
request is simply transformed to a read-write logical
function and is queued to the driver.
(Specified
block number is unchanged.)

4-12

May 1979

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
Transfer Function Processing:
Finally, if the function is not an ACP function, then, by
default, it is a transfer function. All transfer functions
cause the QIO directive processor to check the specified
buffer for legality (that is, inclusion within the address
space of the requesting task) and proper alignment (word or
byte). In addition, the processor checks the number of bytes
being transferred for proper modulus (that is, nonzero and a
proper multiple).

4-12.1

May 1979

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
Creating Mask Words:
Creating function mask words involves five steps:
1.

Establish the I/O functions available on the
for which driver support is to be provided.

device

Build the Legal Function mask:
Check the standard
RSX-llM
function mask values in Table 4-1 for
equivalencies.
Only
the
IO.KIL
function
is
mandatory.
IO.ATT and IO.DET functions, if used,
must have the RSX-llM system interpretation. Digital
suggests that functions having an RSX-llM system
counterpart use the RSX-llM code, but this
is
required only when the device is to be used in
conjunction with an ACP.
From the supported function
list in Table 4-1, you can build the two Legal
Function mask words.

Build the Control Function mask by asking:

Does this function carry a standard buffer address
and byte count in the first two device-dependent
parameter words?
If it does not, then either it qualifies as a control
function,
or the driver itself must effect the
checking and conversion of any addresses to the
format required by the driver.
See Section 6.3 for
an example o~ a driver that does this.
(Buffer
addresses
in
standard format are automatically
converted to Address Doubleword format.)
Control functions are essentially those functions
whose DPBs do not contain buffer addresses or counts.
4.

Create the No-op Function mask by deciding which
legal functions are to be no-op'ed. Typically, for
compatibility with File Control Services
(FCS)
or
Record
Management
Services
(RMS)
on
non-file-structured devices, the file access/deaccess
functions are selected as legal functions,
even
though no specific action is required to access or
deaccess a non-file-structured device;
thus, the
access/deaccess functions are no-op'ed.

Finally, include the ACP functions Write Virtual
Block and Read Virtual Block for those drivers that
support both read and write.
(Include only one
related ACP function if the driver supports only read
or write.) Other ACP functions that might be included
fall
into the non-conventional driver classification
and are beyond the scope of this document.

D.PCB (Partition Control Block)
Driver access:
Initialized, not referenced.
Description:
Address of the driver's Partition Control Block (PCB).
This
word is present in the DCB if and only if the loadable-driver

4-13

May 1979

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
SYSGEN option has been selected.
It must be initialized to
zero. The DCB can be extended by adding words after D.PCB.
A PCB exists for every partition in a system. MCR creates a
PCB when the SET /MAIN or SET /SUB commands are given.
If a
driver is loadable, its PCB describes the partition in which
it resides.
The Executive uses D.PCB together with D.DSP (the address of
the driver dispatch table) to determine whether a driver is
loadable or resident, and, if loadable, whether or not it is
in memory.
Zero and nonzero values for these two pointers
have the following meanings:

'10

Loadable
driver,
not in
memory

Resident
driver

(not
possible)

Loadable
driver,
in memory

4.1.2.2 Establishing I/O Function Masks - Table 4-1 is supplied to
assist you in determining the proper values to set in the function
masks. The mask values are given for each I/O function used by
DIGITAL-supplied drivers.
The bit number allows you to determine
which mask group to use:
for bits numbered 0 through 15, use the mask
value for a word in the first 4-word group~
for bits numbered 16
through 31, use the mask value for a word in the second 4-word group.
Table· 4,-1
Mask Values for Standard I/O Functions

Bit
#

Mask
Value

Related
Symbolic

0
1
2
3
4
5
6
7

IO.KIL
IO.WLB
IO.RLB
IO.ATT
IO.DET

1
2
4
10
20
40
100
200
400
1000
2000
4000
10000
20000
40000
100000

10
11
12
13
14
15

10.FNA
IO.ULK
IO.RNA
IO.ENA
IO.ACR
IO.ACW
IO.ACE

I/O
Function
Cancel I/O
Write Logical Block
Read Logical Block
Attach Device
Detach Device
General Device Control
General Device Control
General Device Control
Diagnostics
Find File in Directory
Unlock Block
Remove Pile from Directory
Enter File in Directory
Access Pile for Read
Access Pile for Read/Write
Access Pile for Read/Write/Extend
(continued on next page)

4-14

May 1979

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
Table 4-1
(Cont.)
Mask Values for Standard I/O Functions
B:it

Mas k

v al ue

Related
Symbolic

1 i6
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

1
2
4
10
20
40
100
200
400
1 000
2 000
4 000
10 000
20 000
40 000
1 00 000

IO.DAC
IO.RVS
IO.WVB
IO.EXT
IO.CRE
IO.DEL
IO.RAT
IO.WAT
IO.APC

I/0
Function

Deaccess: File
Read Virt~al Block
Write Virtual Block
Extend F' ile
Create F'ile
Mark File for Delete
Read File Attributes
Write File Attributes
ACP Control
Unused
Unused
Unused
Unused
Unused
Unused
Unused

Of the function mask values listed in Table 4-1, only IO.KIL is
mandatory and has a fixed interpretation. However, if IO.ATT and
IO.DET are used, they must have the standard meaning.
(Refer to the
RSX-·llM/M-PLUS I/0 Drivers Reference Manual for a description of
standard I/O functions.) If QIO directive processing encounters a
function code of 3 or 4 and the code is not no-op'ed, OIO assumes that
these codes represent Attach Device and Detach Device,
respectively.
The other codes are suggested but not mandatory. You are free to
establish all other function-code values on
non-file-structured
devices. The mask words must reflect the proper filtering process.
If a driver is being written for a file-structured device,
standard function mask values of Table 4-1 must be established.

4.1.3

the

The Status Control Block (SCB)

Figure 4-4 is a layout of the SCB. The SCB describes the status of
control unit that can run in parallel with all other control units.

4-15

May 1979

WRITING AN I/O DRIVER--l1ROGRAMMING SPECIFICS

S.LHD

S.PRI
S.VCT
S.CTM
S.ITM
S.CON
S.STS

}

Vector address74

}

Device 1/0 queue
listhead

r---

Device priority

Timeout count:

}

Initial

Current

Controller status

Controller index

S.CSR

Address of control status register

S.PKT

Address of current 1/0 packet

S.FRK

Fork link word

Fork PC:

Fork Rfi

Fork R4

Relocation base of driver's partition

I
I
S.MPR

L-----------------------J
I

I
I- - I

'---

Storage required for
NPR UNIBUS devices
with 22·bit addressing

- -

I
- I

----'

1
1
I, _______________________ J I
I
I

I
I

,-----------------------~

,_- - - - - - - - - - - - - - - - - - - - - --

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

Figure 4-4

4.1.3.1

Status Control Block

SCB Details - The fields in the SCB are described below:

S.LHD (first word equals zero; second word points to first)*
Driver access:
Initialized, not referenced.
Description:
Two words forming the I/O queue listhead.
The first word
points to the first I/O Packet in the queue, and the second
word points to the last I/O Packet in the queue.
If the
queue is empty, the first word is zero, and the second word
points to the first word.

* Parenthesized contents indicate values to
data base source code.

4-16

initialized

the

~·
'I

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
S.PRI (device priority)
Drive:r access:
Initialized, read-only.
Description:
Contains the priority at which the device interrupts.
Use
symbolic values
(for example, PR4) to initialize this field
in your data base source. These symbolic values are defined
by issuing the HWDDF$ macro (refer to the sample data base in
Section 6.2.1 and the listing of the HWDDF$ macro in Appendix
c} •

S.VCT (interrupt vector divided by four)
Driver access:
Itiitialized, not referenced.
Description:
Interrupt vector address divided by four.
For loadable
drivers,
the MCR/VMR LOA[D] function uses this field and the
existen~e of driver symbol(s} $xxINT, $xxINP, and
$xxOUT to
initialize the device interrupt vector.
S.CTM (initialize to zero}
Driver access:
Not initialized, read-write.
Description:
RSX-llM supports device timeout, which enables a driver to
limit the time that elapses between the issuing of an I/O
operation and its termination. The current timeout count (in
seconds}
is initialized by moving S.ITM (initial timeout
count} into S.CTM. The Executive clock service
(in module
TOSCH)
examines active times, decrements them, and, if they
reach 0, calls the driver at its device timeout entry point.
The internal clock count is kept in !-second increments.
Thus, a time count of 1 is not precise because the internal
clocking mechanism is operating asynchronously with driver
execution. The minimum meaningful clock interval is 2 if you
intend to treat timeout as a consistently detectable error
condition.
Note, if the count is 0, that no timeout occurs;
a zero value is, in fact, an indication that timeout is not
operative.
The maximum count is 255. You are responsible
for setting this field.
Resetting occurs at actual timeout
or within $FORK.
S.ITM (set to initial timeout count}
Driver access:
Initialized, read-only.
Description:
Contains the initial timeout value.

4-17

WRITING AN I/O DRIVER--PlROGRAMMING SPECIFICS

S.CON (controller number times 2)
Driver access:
Initialized, read-only.
Description:
Controller number multiplied by 2.
This field
is used by
drivers that are written to support more than one controller.
A driver may use S.CON to index into a controller table
created and maintained internally by the driver itself.
By
indexing the controller tablE~, the driver can service the
correct controller when a device interrupts.
See Section 4.2
for an example.
S.STS (initialize to zero)
Driver access:
Initialized, not referenced.
Description:
Establishes the controller as busy/not busy
(nonzero/zero).
This byte is the interlock mechanism for marking a driver as
busy for a specific controller.
The byte is tested and set
by $GTPKT and reset by $!ODON.
S.CSR (Control Status Register address)
Driver access:
Initialized, read-only.
Description:
Contains the address of the Control Status Register (CSR) for
the device controller.
The driver uses S.CSR to initiate I/O
operations and to access,
by indexing, other registers
related to the device that are located in the I/O page.
This
address need not be a CSR:
it need only be a member of the
device's register set.
It is accessed at system bootstrap
time to determine if the interface exists on the system
hosting the Executive.
The Executive uses S.CSR to set the
offline bit at bootstrap so that system software can be
interchanged between systems without an intervening system
generation.
The MCR LOAD function also references S.CSR when
it processes a loadable data base.
Otherwise, only the
driver itself accesses S.CSR.
S.PKT (reserve 1 word of storage)
Driver access:
Not initialized, read-only.
Description:
Address of the current I/O Packet established by $GTPKT.
The
Executive uses this field to retrieve the I/O Packet address
upon the completion of an I/O request.
S.PKT is not zeroed
after the packet is completed.

4-18

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
S.FRK (reserve 4 or 5 words of storage)
Driver access::
Not initialized, not referenced.
Description:
The 4 words starting at S.FRK are used for fork-block storage
if and when the driver deems it necessary to establish itself
as a Fork process.
Fork-block storage preserves the state of
the driver, which is restored when the driver regains control
at fork level. This area is automatically used if the driver
calls $FORK.
The fork block is 5 words long instead of 4 if two conditions
are met:
1.

Loadable drivers
option; and

The system is mapped.

have

been

selected

SYSGEN

If these conditions are met, and the fork block is 5 words
lonq, you must not use the fork block for any other purpose.
In other words, you may not share the space reserved for
the
fork block;
if you attempt to do so, you will destroy the
loadable driver's relocation base.
In addition,
the 5-word
fork block should always be part of the SCB if the two above
conditions are met.
(reserve 6 words of storage)

S.M~R

Driver access:
Initialized, read-only.
Description:
Drivers use the 6 words starting at S.MPR for non-processor
request
(NPR)
devices attached to a PDP-11/70 with 22-bit
addressing.
See Appendix B for details on initializing
S.MPR.

4.1.4

The Unit Control Block (UCB)

Figure 4-5 is a layout of the UCB (a variable-length control block).
One UCB existB for each physical device-unit generated into a system
configuration.
For user-added drivers, this control block is defined
as part of the source code for the driver data structure.

4.1.4.1

UCB Details - The fields in the UCB are described below:

U.LUIC
Driver access:
Not initialized, not referenced.

4-19

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
Description:
For terminal UCB's only, and only in multiuser systems:
logon UIC of the user at the particular terminal.

the

r------------------------1
I
Log-on UIC
-4

U.LUIC

~----------------------~
U.OWN

Owning terminal UCB address

-2

U.DCB

Back pointer to DCB

U.RED

Redirect UCB pointer

U.CTL
U.STS
U.UNIT
U.ST2

}
}

Unit status

Control flags

Unit status

Physical unit no.

U.CWl

Characteristics word 1

U.CW2

Characteristics word 2

U.CW3

Characteristics word 3

U.CW4

Characteristics word 4

U.SCB

Pointer to SCB

U.ATT

TCB address of attached task

U.BUF

Buffer relocat:1on bias

U.BUF+2

Buffer address

U.CNT

Byte count

I---

Device·
dependent

,____

~i,

storage

Figure 4-5

Unit Control Block

U.OWN (initialize to zero)
Driver access:
Initialized, not referenced.
Description:
Only in multiuser systems:
the UCB
terminal for allocated devices.

4-20

address

the

owning

May 1979

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
U.DCB (pointer to associated DCB)
Driver access:
Initialized, not referenced.
Description:
Backpointer to the corresponding DCB. Because the UCB is a
key control block in the I/O data structure, access to other
control blocks usually occurs by means of links implanted in
the UCB.
U.RED (redirect pointer--initialized to point to U.DCB of the UCB)
Driver access:
Initialized, not referenced.
Description:
Contains a pointer to the UCB to which this device-unit has
been redirected.
This field is updated as the result of an
MCR Redirect command. The redirect chain ends when this word
points to the beginning of the UCB itself (U.DCB of the UCB
to be precise).
U.CTL (set by you)
Driver access:
Initialized, not referenced.
Description:
U.CTL -and the function mask words in the DCB drive OIO
directive processing.
You are responsible for setting up
this bit pattern. Any inaccuracy in the bit setting of U.CTL
produces erroneous I/O processing.
Bit symbols and their
meanings are as follows:
UC.ALG - Alignment bit.
If this bit = O, then byte alignment of data buffers
allowed.
If
UC.ALG
= 1,
then buffers must
word-·al igned.

is
be

UC.ATT - Attach/Detach notification.
If this bit is set, then the driver is called when $GTPKT
processes an Attach/Detach I/O function. Typically, the
driver does not need to obtain control for Attach/Detach
requests,
and the Executive performs the entire function
without any assistance from the driver.
UC.KIL - Unconditional Cancel I/O call bit.
If set, the driver is called on a Cancel I/O request,
even if the unit specified is not busy. Typically, the
driver is called on Cancel I/O only if an I/O operation
is in progress.

4-21

May 1979

WRITING AN I/O DtRIVER--PllOGRAMMING SPECIFICS

UC.QUE - Queue bypass bit.
If set, the QIO directive processor calls the driver
prior to queuing the I/O packet. After the processor
makes this call, the driver is responsible for the
disposition of the I/O packet. Typically, the processor
queues an I/O Packet prior to calling the driver, which
later retrieves it by a call to $GTPKT.
UC.PWF - Unconditional call on power failure bit.
If set and the unit is online, the driver is always to be
called when the system is bootstrapped or power is
restored after a power failure occurs.
Typically, the
driver is called on power restoration only when an I/O
operation is in progress.
Additionally, for loadable
drivers, the driver is called when LOAded if the unit is
online and UC.PWF is set.
UC.NPR - NPR device bit.
If set, the device is an NPR device. This bit determines
the format of the 2-word address in U.BUF (details given
in the discussion of U.BUF below).
UC.LGH - Buffer size mask bits (2 bits).
These two bits are used to check whether the byte count
specified in an I/O request is a legal buffer modulus.
You select one of the values below by ORing into the byte
a O, 1, 2, or 3 .
00 01 10 11 -

Any buffer modulus valid
Must have word alignment modulus
Combination invalid
Must have double word-alignment modulus

UC.ALG and UC.LGH are independent settings.
UC.ATT, UC.KIL, UC.QUE, and UC.PWF are
usually
zero,
especially for conventional drivers. Every driver, however,
must be concerned with its particular values for UC.ALG,
UC.NPR, and UC.LGH.
You are totally responsible for the
values in these bits, and erroneous values are likely to
produce unpredictable results.

~
'1

U.STS (initialize to zero)
Driver access:
Initialized, not referenced.
Description:
This byte contains device-independent
The bit meanings are as follows:

status

information.

US.BSY - If set, device-unit is busy.
US.MNT - If set, volume is not mounted.
US.FOR - If set, volume is foreign.
US.MOM - If set, device is marked for dismount.

4-22

~.
;J

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
The unused bits in U.STS are reserved for system
expansiori.
US.MOM,
US.MNT, and US.FOR apply
mountable devices.

use and
only to

U.UNIT (unit number)
Driver access:
Initialized, read-only.
Description:
This byte contains the physical unit
number
of
the
device-unit.
If the controller for the device supports only
a single unit, the unit number is always zero.
U.ST2 (set by you)
Driver access:
Initialized, not referenced.
Description:
This byte contains additional device-independent
information. The bit meanings are as follows:
US.OFL - If set, the device is offline (that is,
the configuration).

status
not

US.RED - If set, the device cannot be redirected.
US.PUB - If set, the device is a public device.
US.UMD - If set, the device is attached for diagnostics.
The remaining bits are reserved for system use and expansion.
U.CWl (set by you)
Driver access:
Initialized, not referenced.
Description:
The first of a 4-word contiguous
cluster
of
device
characteristics
information.
U.CWl
and
U.CW4
are
device-independent.
U.CW2 and U.CW3 are device-dependent.
The four characteristics words are retrieved from the UCB and
placed in the requester's buffer on issuance of a Get LUN
information
(GLUN$)
Executive
directive.
It is your
responsibility to supply the contents of these four words in
the assembly source code of the driver's data structure.
U.CWl is defined as follows.
(If a bit is set to 1,
corresponding characteristic is true for the device.)

4-23

the

WRITING AN I/O DRIVER--P'ROGRAMMING SPECIFICS

DV.REC
DV.CCL
DV.TTY
DV.DIR
DV.SDI

DV~SQD

DV.UMD
DV.MBC
DV.SWL
DV.PSE
DV.COM
DV .Fll
DV.MNT

Bit
Bit
Bit
Bit
Bit
Bit
Bit
Bit

0--Record-oriented device
!--Carriage-control device
2--Terminal device
3--Directory device
4--Single directory device
5--Sequential device
7--Device supports user-mode diagnostics
8--Device attached to a 22-bit MASSBUS
controller
Bit 9--Unit is software write-locked
Bit 12--Pseudo device
Bit 13--Device mountable as a communications channel
Bit 14--Device mountable as a FILES-11 device
Bit 15--Device mountable

U.CW2 (initialize to zero)
Driver access:
Initialized, read-write.
Description:
Specific to a given device
storage or constants).*

driver

(available

for

working

driver

(available

for

working

U.CW3 (initialize to zero)
Driver access:
Initialized, read-write.
Description:
Specific to a given device
storage or constants).*
U.CW4 (set by you)
Driver access:
Initialized, read-only.
Description:
Default buffer size.
SET /BUF=.

This word is changed by the MCR command

U.SCB (SCB pointer)
Driver access:
Initialized, read-only.

* Exception: for block-structured devices, u.cw2 and U.CW3 may not
be used for working storage. In drivers for block-structured devices
(disks and DECtape), these two words must be initialized to a
double-precision number g1v1ng the total number of blocks on the
device. Place the high-order bits in the low-order byte of U.CW2 and
the low-order bits in U.CW3.
4-24:

May 1979

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
Description:
This field contains a pointer to the SCB for this UCB.
In
general,
R4 contains the value in this word when the driver
is entered by way of the driver dispatch table, because
service routines frequently reference the SCB.
U.ATT (initialize to zero)
Driver access:
Initialized, not referenced.
Description:
If a task has attached itself to the device-unit, this
contains its TCB address.

field

U.BUF (reserve 2 words of storage)
Driver access:
Not initialized, read-write.
Description:
that
serve
as
a
U.BUF labels 2 consecutive
words
If a
communication region between $GTPKT and the driver.
then U.BUF,
non-transfer function is indicated (in D.MSK),
U.BUF+2, and U.CNT receive the first 3 parameter words from
the I/O Packet.
For transfer operations, the format of these 2 words depends
on the setting of UC.NPR in U.CTL. The driver does not
format the words;
all formatting
is completed before the
driver receives control.
For unmapped systems, the first
word is zero, and the second word is the physical address of
the buffer.
For mapped systems, the format is determined by
the UC.NPR bit, which is set for an NPR device and reset for
a program-transfer device.
The format for program-transfer devices is identical to that
for
the second 2 words of I.IOSB in the I/O Packet.
See
Section 4 .1.1.1.
In general, the driver does not manipulate these words when
performing I/O to a program-transfer device.
Instead, it
uses the Executive routines Get Byte, Get Word, Put Byte, and
Put Word to effect data transfers between the device and the
user's buffer.
For NPR device drivers, the word layout is as follows:
Wo1:d 1
---Bit 0
Bits 1-3
Bits 4,5
Bits 6
Bits 7-15

Go bit initially set to zero
Function code--set to zeros
Memory extension bits
Interrupt enable--set to zero
Zero

Word 2
-Bits 0-15

Low-order 16-bits of physical address

4-25

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
It is your responsibility to set the function code, interrupt
enable, and go bits. This action must be accomplished by a
Bit Set (BIS) operation so that the extension bits are not
disturbed.
The driver must move these words into the device
control registers to initiate the I/O operation.
Note that when the system is unmapped, bits 4 and 5 are
always zero, but this fact is transparent to the driver.
Thus, NPR device drivers are not cognizant of the mapping
state in the system.
The construction of U.BUF, U.BUF+2, and U.CNT occurs only if
the requested function is a transfer function;
if it is not,
these 3 words contain the first 3 words of the I/O Packet.
The details of the construction
appear in Appendix A.

the

Address

Doubleword

U.CNT (reserve l word of storage)
Driver access:
Not initialized, read-write.
Description:
Contains the byte count of the buffer described by U.BUF.
The driver uses this field in constructing the actual device
request.
U.BUF and U.CNT keep track of the current data item in the
buffer for the current transfer (except for NPR transfers) .
Because this field is being altered dynamically, the I/O
Packet may be needed to reissue an I/O operation, for
instance after a powerfail or error retry.
Device-Dependent Words:
Driver access:
Not initialized, read-write.
Description:
You establish this variable-length block
device-specific requirements.

4.1.5

words

suit

The Device Interrupt Vector

For resident drivers only, the device interrupt vector must be
initialized when defining data structures, and not dynamically. This
practice makes the driver code independent of device register address
assignments and of the actual location of the interrupt vector. The
driver data structure must include a
storage
assignment
and
initialization for the interrupt vector with the priority set to PR7.
See lines 81 thru 85 in Section 6.2.l (Section 6.2.1 contains the
source code for the data structure of a sample resident driver).
Writers of loadable drivers do not initialize the device interrupt
vector.
The vector is dynamically established by LOA[D] when the
driver is loaded. When a driver is unloaded, UNLoad sets the vector
to the system nonsense interrupt entry point.

4-26

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
4.2

MULTICONTROLLER DRIVERS

This section discusses the conditional code needed at the interrupt
enticy point of a driver that may handle one or several device
controllers.
This discussion leads to a description in the next
section of the system macro INTSV$.
INTSV$ contains multicontroller
conditionals and other features to simplify interrupt-entry coding.
Figure 4-6 shows the interrupt-entry coding from the paper-tape-punch
driver.
This is an earlier version of the driver presented in its
entirety in Section 6.2.2.
The coding is conditionalized on P$$Pll-l.
The symbol
represents the number of controllers and is set at SYSGEN.

P$$Pll

In a multicontroller device configuration,
the controllers
are
numbered starting with 0.
The code for a multicontroller driver
contains a table (called CNTBL in the~ example in Figure 4-6)
whose
length in words is equal to the number of controllers. A number
called the controller index--equal to the controller number times
2--is stored in the SCB for each controller, in byte S.CON.
When an I/O request occurs, and the driver is called at its initiator
entry point, the driver first calls $GTPKT to obtain an I/O packet to
process. Among the values returned by $GTPKT are the controller index
(obtained from S.CON in the SCB) and the address of the UCB for the
unit requesting I/O service.
The driver stores the requesting unit's UCB address in the controller
table
(CNTBL)
at an offset equal to the controller index.
Thus, for
the driver at its interrupt entry point to access the requesting UCB,
it needs simply to obtain the controller index.
The controller index is obtained from the controller number, which is
encoded in the lowest 4 bits of the PS word in the device's interrupt
vector. At its interrupt entry point the driver first saves the PS
(line 9 in Figure 4-6), which was set from the device's interrupt
vector upon interrupt.
The PS must be saved with the
first
instruction of interrupt code because its lower 4 bits are the
processor condition code bits, which generally change after each
instruction is issued.
Later, after the call to $INTSV, the driver
constructs the controller index from the saved PS (lines 17-19).
It
then uses this index to obtain the UCB address (line 20).
For single-controller devices, CNTBL is 1 word, TEMP is not needed to
store the PS, and the UCB address is always the first (and only) entry
in CNTBL.

4-27

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
1 ;+
2 ; **-$PPINT-PC11 PAPER TAPE PUNCH CONTROLLER INTERRUPTS
3 ;4
; ; ; REF LABEL
5 $PPINT::
6
.IF GT P$$Pll-l
7
8
PS,TEMP
;;;SAVE CONTROLLER NUMBER
MOV
9
10
.IFTF
11
12
CALL
$INTSV,PR4
;;;SAVE REGISTERS AND SET PRIORITY
13
14
.IFT
15
16
TEMP,R4
;;;RETRIEVE CONTROLLER NUMBER
MOV
17
;;;CLEAR ALL BUT CONTROLLER NUMBER
#177760 ,R4
BIC
18
;;;CONVERT TO CONTROLLER INDEX
ASL
R4
19
;;;RETRIEVE ADDRESS OF UCB
MOV
CNTBL(R4) ,RS
20
21
.IFF
22
23
MOV
CNTBL,RS
;;;RETRIEVE ADDRESS OF UCB
24
25
.ENDC
26
Figure 4-6

4.3

Conditional Code for a Multicontroller Driver

THE INTSV$ MACRO

INTSV$ is a system macro that m1n1m1zes coding differences between
loadable
and
resident
drivers.
INTSV$ contains conditionally
assembled code to handle:
1. Single or multiple controllers
2. Loadable or resident

d~ivers

3. Mapped or unmapped systems
All the code in Figure 4-6 between lines 7 and 26 may be replaced by
the INTSV$ macro
(as is done in the sample driver illustrated in
Section 6.2.2). This is required for loadable drivers on mapped
systems, because interrupts from hardware devices must be proces~ed in
kernel address space.
In particular, the decoding of the PS word and
the call to $INTSV must be done before entering the driver. Thus, a
call to the Executive routine $INTSV within a loadable driver is
illegal, and the MCR LOA[D] function returns an error if loading is
attempted.
When the INTSV$ macro is used for a loadable driver in a mapped
system, the code from lines 9 to 19 inclusive (Figure 4-6) is not
assembled as part of the driver.
Instead, the LOA[D]
function
allocates a block of dynamic memory in kernel address space to contain
the interrupt coding. This block, called the Interrupt Control Block
(ICB), also contains coding to:

4-28

~t'

WRITING AN I/O DRIVER--PROGRAMMING SPECIFICS
1.

Save the kernel mapping (APRS)

Load APRS to map the driver

Transfer to the driver

Restore the mapping after return

The LOA[D] function also sets up the controller's interrupt vector
that hardware interrupts point to the ICB.

Finally, the use of the INTSV$ macro in a loadable driver on a mapped
system requires that the symbol LD$xx (where xx is the 2-character
device mnemonic) be defined either in the driver source or the
assembly prefix file RSXMC.MAC.

4.3.l

Format

The format of the INTSV$ macro is:
INTSV$

xx,pri,nctlr[,pssave,ucbsave]

is the 2-character device mnemonic.

pri

is the priority of the device (the priority that
be used in a call to $INTSV} .

nctlr

is the number of controllers the driver services.

pssave

is an optional argument specifying a variable in which
to save the PS word.
If omitted, a variable named TEMP
is used.

where:

would

ucbsave is an optional argument specifying
a
block
of
contiguous words in which to retrieve the interrupting
device's UCB address.
If omitted,
a
block
of
contiguous words named CNTBL is used.
Outputs: R4

is the controller index, only if nctlr is
1.

is the UCB address.

INTSV$

PP,PR4,P$$Pll

greater

than

8xample:

This usage of INTSV$ would effectively replace lines 7 through 26
Figure
4-6.
(P$$Pll is a symbol equated to the number
controllers.)

4-·29

in
of

CHAPTER S
EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS

This section contains the Executive routines typically used by I/O
They are listed in alphabetical order. The descriptions are
taken directly from the source code for the associated services.

drive~rs.

We de~scribe only the most widely used subroutines.
Many other
Executive service subroutines are available in modules IOSUB.MAC,
SYSX~r. MAC, QUEUE. MAC, CORAL. MAC, and REQSB. MAC under UIC [ 11, 10] .

5.1

SYSTEM-ST~TE

In system state, RS and R4 are, by convention, nonvolatile registers.
This means that an internally called routine is required to save and
restore these two registers if the routine destroys their contents.
R3, R2, Rl, and RO are volatile registers and may be used by a called
routine without save and restore responsibilities.
When a driver is entered directly from an interrupt, it is operating
at interrupt level, not at system state. At interrupt level, any
register the driver uses must be saved and restored.
INTSV$ preserves
RS and R4 for the driver's use.
A routine may violate these conventions as long as an explicit
statement exists in the program preface detailing the departure from
conventions. Such departures should be avoided:
they should be
employed
only when you can demonstrate that a departure from
convention can improve overall system performance.
See JD.DSP in Section 4.1.2.1 for the
driver is entered.

5.2

contents

registers

when

CONDITIONAL ROUTINES

Two of the routines discussed in this chapter (Get Word and Put Word)
normally are assembled conditionally out of the Executive code.
If a
user·-written driver requires either of these routines, the appropriate
question must be answered affirmatively in the SYSGEN dialog. This
requirement is spelled out in the descriptions that follow.

S.3

SERVICE CALLS

In the following descriptions, the filenames mentioned are source
modules found on the Executive source disk as [11,10] filename.MAC.

S-1

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS

ISACHKB/$ACHCKI
ADDRESS CHECK
These routines are in the file
IOSUB.
A driver may call either
routine to address-check a task buffer while the task is the current
task.
The Address Check routines are normally used only by drivers
setting UC.QUE in U.CTL.
See Section 6.3 for an example.
Calling Sequences:
CALL $ACHKB
or
CALL $ACHCK
Description:

;+
**-$ACHKB-ADDRESS CHECK BYTE ALIGNED
**-$ACHCK-ADDRESS CHECK WORD ALIGNED
THIS ROUTINE IS CALLED TO ADDRESS CHECK A BLOCK OF MEMORY TO SEE
WHETHER IT LIES WITHIN THE ADDRESS SPACE OF THE CURRENT TASK.
INPUTS:
RO=STARTING ADDRESS OF THE BLOCK TO BE CHECKED.
Rl=LENGTH OF THE BLOCK TO BE CHECKED IN BYTES.
OUTPUTS:
C=l IF ADDRESS CHECK FAILED.
C=O IF ADDRESS CHECK SUCCEEDED.
RO AND R3 ARE PRESERVED ACROSS CALL.

5-2

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS

ISALOCBI
ALLOCATE CORE BUFFER
This routine is in the file CORAL.
Calling Sequences:
CALL $ALOCB
o.r
CALL $AL0Cl

;+
**-$ALOCB-ALLOCATE CORE BUFFER
**·-$ALOC1-A:LLOCATE CORE BUFFER (ALTERNATE ENTRY)
THIS ROUTINE IS CALLED TO ALLOCATE AN EXEC CORE BUFFER.
THE
ALLOCATION ALGORITHM IS FIRST FIT AND BLOCKS ARE ALLOCATED IN
MULTIPLES OF FOUR BYTES.
INPUTS:
RO=ADDRESS OF CORE ALLOCATION LISTHEAD-2 IF ENTRY AT $ALOC1.
Rl=SIZE OF THE CORE BUFFER TO ALLOCATE IN BYTES.
OUTPUTS:

·'

C=l IF INSUFFICIENT CORE IS AVAILABLE TO ALLOCATE THE BLOCK.
C=O IF THE BLOCK rs ALLOCATED.
RO=ADDRESS OF THE ALLOCATED BLOCK.
Rl=LENGTH OF BLOCK ALLOCATED.

5-3

EXECUTIVE SERVICES AVAIJC..ABLE TO I/O DRIVERS

I $ASUMR I
ASSIGN UNIBUS MAPPING REGISTERS
This routine is in the file IOSUB. It is used only for PDP-11/70 NPR
devices requiring UNIBUS Mapping Hegisters.
Normally, it is not
called directly by an I/O driver. Rather, it is called from within
the $STMAP routine. Refer to Appendix B for a discussion.
Calling Sequence:
CALL $ASUMR
Description:
;+
**-$$ASUMR-ASSIGN UNIBUS MAPPING REGISTERS
THIS ROUTINE IS CALLED TO ASSIGN A CONTIGUOUS SET OF UMR'S. NOTE THAT
FOR THE SAKE OF SPEED, THE LINK WORD OF EACH MAPPING ASSIGNMENT BLOCK
POINTS TO THE UMR ADDRESS (2ND) WORD OF THE BLOCK, NOT THE FIRST WORD.
THE CURRENT STATE OF UMR ASSIGNMENT IS REPRESENTED BY A LINKED LIST OF
MAPPING ASSIGNMENT BLOCKS, EACH BLOCK CONTAINING THE ADDRESS OF THE
FIRST UMR ASSIGNED AND THE NUMBER OE' UMR'S ASSIGNED TIMES 4. THE
BLOCKS ARE LINKED IN THE ORDER OF INCREASING FIRST UMR ADDRESS.
INPUTS:
RO=POINTER TO A MAPPING REGISTER ASSIGNMENT BLOCK.
M. UMRN (RO) =NUMBER OF UMR' S REC!U I RED * 4 .
OUTPUTS:
ALL REGISTERS ARE PRESERVED.
C=O IF THE UMR'S WERE SUCCESSFULLY ASSIGNED.
ALL FIELDS OF THE MAPPING REGISTER ASSIGNMENT BLOCK
ARE INITIALIZED AND THE BLOCK IS LINKED INTO
THE ASSIGNMENT LIST.
C=l IF THE UMR'S COULD NOT BE ASSIGNED.
;-

5-4

"'
I

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS

I$CLINS I
CLOCK QUEUE INSERTION
This routine is in the file QUEUE.
Calling Sequence:
CALL $CLINS
Desc:r iption:

:+
**-$CLINS-CLOCK QUEUE INSERTION
THIS ROUTINE IS CALLED TO MAKE AN ENTRY IN THE CLOCK QUEUE. THE ENTRY
IS INSERTED SUCH THAT THE CLOCK QUEUE IS ORDERED IN ASCENDING TIME.
THUS THE FRONT ENTRIES ARE MOST IMMINENT AND THE BACK LEAST.
INPUTS:
RO=ADDRESS OF THE CLOCK QUEUE ENTRY CORE BLOCK.
Rl=HIGH ORDER HALF OF DELTA TIME.
R2=LOW ORDER HALF OF DELTA TIME.
R4=REQUEST TYPE.
RS=ADDRESS OF REQUESTING TCB OR REQUEST IDENTIFIER.
OUTPUTS:
THE CLOCK QUEUE ENTRY IS INSERTED IN THE CLOCK QUEUE ACCORDING
TO THE TIME THAT IT WILL COME DUE.

5-5

EXECUTIVE SERVICES AVAilC,ABLE TO I/O DRIVERS

ISDEACBI
DEALLOCATE CORE BUFFER
This routine is in the file CORAL.
Calling sequences:
CALL $DEACB
or
CALL $DEAC1

;+
**-$DEACB-DEALLOCATE CORE BUFFER
**-$DEAC1-DEALLOCATE CORE BUFFER (ALTERNATE ENTRY)

~
I '

THIS ROUTINE IS CALLED TO DEALLOCATE AN EXEC CORE BUFFER.
THE BLOCK
IS INSERTED INTO THE FREE BLOCK CHAIN BY CORE ADDRESS.
IF AN
ADJACENT BLOCK IS CURRENTLY FREE, THEN THE TWO BLOCKS ARE MERGED
AND INSERTED IN THE FREE BLOCK CHAIN.
INPUTS:
RO=ADDRESS OF THE CORE BUFFER TO BE DEALLOCATED.
Rl=SIZE OF THE CORE BUFFER TO DEALLOCATE IN BYTES.
R3=ADDRESS OF CORE ALLOCATION LISTHEAD-2 IF ENTRY AT $DEAC1.
OUTPUTS:
THE CORE BLOCK IS MERGED INTO THE FREE CORE CHAIN BY CORE
ADDRESS AND IS MERGED IF NECESSARY WITH ADJACENT BLOCKS.

...

5-6

EXECUTIVE SERVICES AVAIL.ABLE TO I/O DRIVERS

I$DEUMR I
DEASSIGN UNIBUS MAPPING REGISTERS
This routine is in the file IOSUB.
It is used only for PDP-11/70 NPR
devices requiring UNIBUS Mapping Registers.
Normally,
it is not
callE~d directly by an I/O driver.
Rather, it is called from within
the $!ODON routine. Refer to Appendix B for a discussion.
Calling Sequence:
CALL $DEUMR
Descir iption:

;+
**-$DEUMR-DEASSIGN UNIBUS MAPPING REGISTERS
THIS ROUTINE IS CALLED TO DEASSIGN A CONTIGUOUS BLOCK OF UMR'S. IF
THE MAPPING ASSIGNMENT BLOCK IS NOT IN THE LIST, NO ACTION IS TAKEN.
NOTE THAT FOR THE SAKE OF ASSIGNMENT SPEED, THE LINK WORD POINTS TO
THE UMR ADDRESS (2ND) WORD OF THE ASSIGNMENT BLOCK.
INPUTS:
R2=POINTER TO ASSIGNMENT BLOCK.
OU'TPUTS:
RO AND Rl ARE RESERVED.

5-7

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS

lsovMsGI
DEVICE MESSAGE OUTPUT
Device Message Output is in file IOSUB.
Calling Sequence:
CALL

$DVMSG

Description:
;+

**-$DVMSG-DEVICE MESSAGE OUTPUT
THIS ROUTINE IS CALLED TO SUBMIT A MESSAGE TO THE TASK TERMINATION
NOTIFICATION TASK. MESSAGES ARE EITHER DEVICE RELATED OR A
CHECKPOINT WRITE FAILURE FROM THE LOADER.
INPUTS:
RO=MESSAGE NUMBER.
RS=ADDRESS OF THE UCB OR TCB

~rHAT

THE MESSAGE APPLIES TO.

OUTPUTS:
A FOUR WORD PACKET IS ALLOCATED, RO AND RS ARE STORED IN THE
SECOND AND THIRD WORDS, RESPECTIVELY, AND THE PACKET IS
THREADED INTO THE TASK TERMINl\TION NOTIFICATION TASK MESSAGE
QUEUE.
NOTE:

IF THE TASK TERMINATION NOTIFICATION TASK IS NOT
INSTALLED OR NO STORAGE CAN BE OBTAINED, THEN THE
MESSAGE REQUEST IS IGNORED.

;Note:
Drivers use only two codes in calling $DVMSG: T.NDNR (device not
ready), and T.NDSE
(select error).
$DVMSG can be set up and
called as follows:
MOV

#T.NDNR,RO

or
MOV
CALL

#T.NDSE,RO
$DVMSG

5-8

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS

ISFORKI
FORK
Fork is in the file SYSXT. A driver calls $FORK to switch from a
partially interruptable level (its state following a call on $INTSV)
to a fully interruptable level.
Calling sequence:
CALL $FORK
Des:cr iption:

;+
**-$FORK-FORK AND CREATE SYSTEM PROCESS
THIS ROUTINE IS CALLED FROM AN I/O DRIVER TO CREATE A SYSTEM PROCESS THAT
WILL RETURN TO THE DRIVER AT STACK DEPTH ZERO TO FINISH PROCESSING.
INPUTS:
RS=ADDRESS OF THE UCB FOR THE UNIT BEING PROCESSED.
OUTPUTS:
REGISTERS RS AND R4 ARE SAVED IN THE CONTROLLER FORK BLOCK AND
A SYSTEM PROCESS IS CREATED. THE PROCESS IS LINKED TO THE FORK
QUEUE AND A JUMP TO $INTXT IS EXECUTED.

;Notes:
1.

$FORK cannot be called unless $INTSV has been previously
called.
The fork-processing routine assumes that $INTSV has
set up entry conditions.

A driver's current timeout count is cleared in calls to
$FORK.
This
protects the driver from synchronization
problems that can occur when an I/O request and the timeout
for that request happen at the same time. After a return
from a call to $FORK, a driver's timeout code will not be
entered.
If the clearing of the timeout count is not desired, a driver
has two alternatives:

Perform timeout operations by directly inserting elements
in the clock queue
(refer to the description of the
$CLINS routine).

Perform necessary initialization,
including
clearing
S.STS in the SCB to zero (establishing the controller as
not busy), and call the $FORK1 routine rather than $FORK.
Calling $FORK1 bypasses the clearing of the current
timeout count.

The driver must not have any information on
$FORK is called.

5-9

the

stack

when

EXECUTIVE SERVICES AVAIL.f\BLE TO I/O DRIVERS

I$FORK1 I
FORKl
Forkl is in the file SYSXT. A driver calls $FORK1 to bypass the
clearing of its timeout count when it switches from a partially
interruptable level to a fully interruptable level (refer also to the
description of the $FORK routine).
Calling Sequence:
CALL $FORK1
Description:

;+
**-$FORK1-FORK AND CREATE SYSTEM PROCESS
THIS ROUTINE IS AN ALTERNATE ENTRY TO CREATE A SYSTEM PROCESS AND
SAVE REGISTER RS.
INPUTS:
R4=ADDRESS OF THE LAST WORD OF A 3 WORD FORK BLOCK PLUS 2.
RS=REGISTER TO BE SAVED IN THE FORK BLOCK.
OUTPUTS:
REGISTER RS IS SAVED IN THE SPECIFIED FORK BLOCK AND A SYSTEM
PROCESS IS CREATED. THE PROCESS IS LINKED TO THE FORK QUEUE
AND A JUMP TO $INTXT IS EXECUTED.
;-

Notes:
1.

For mapped systems with loadable driver support,
fork block is required for calls to $FORK1.

When a S-word fork block is used, the driver must .initialize
the fifth word with the base address (in 32-word blocks) of
the driver partition. This address can be obtained from the
fifth word of the standard fork block in the SCB.

The driver must not have any information on
$FORK1 is called.

5-10

the

stack

S-word

when

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS

ISGTBYTI
GET' BYTE
Get Byte is in the file BFCTL.
U.BUF+2 in the UCB.

Get byte manipulates words

U.BUF

Calling sequence:
CALL

$GTBYT

Description:
;+
**-$GTBYT-GET NEXT BYTE FROM USER BUFFER
THIS ROUTINE IS CALLED TO GET THE NEXT BYTE FROM THE USER BUFFER

JrnD RETURN IT TO THE CALLER ON THE STACK. AFTER THE BYTE HAS BEEN
FETCHED, THE NEXT BYTE ADDRESS IS INCREMENTED.
INPUTS:
RS=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS.
OUTPUTS:
THE NEXT BYTE IS FETCHED FROM THE USER BUFFER AND RETURNED
TO THE CALLER ON THE STACK. THE NEXT BYTE ADDRESS IS
INCREMENTED.
A.LL REGISTERS ARE PRESERVED ACROSS CALL.

5-11

and

EXECUTIVE SERVICES AVAILABLE TO I/0 DRIVERS

jSGTPKTj
GET PACKET
Get Packet is in the file IOSUB.
Calling sequence:
CALL

$GTPKT

Description:
;+

**-$GTPKT-GET I/O PACKET FROM REQUEST QUEUE
THIS ROUTINE IS CALLED BY DEVICE DRIVERS TO DEQUEUE THE NEXT I/O
REQUEST TO PROCESS. IF THE DEVICE CONTROLLER IS BUSY, THEN A CARRY
SET INDICATION IS RETURNED TO THE CALLER. ELSE AN ATTEMPT IS MADE TO
DEQUEUE THE NEXT REQUEST FROM THE CONTROLLER QUEUE. IF NO REQUEST
CAN BE DEQUEUED, THEN A CARRY SET INDICATION IS RETURNED TO THE
CALLER. ELSE THE CONTROLLER IS SET BUSY AND A CARRY CLEAR
INDICATION IS RETURNED TO THE CALLER.
INPUTS:
RS=ADDRESS OF THE UCB OF THE CONTROLLER TO GET A PACKET FOR.
OUTPUTS:
C=l IF CONTROLLER IS BUSY OR NO REQUEST CAN BE DEQUEUED.
C=O IF A REQUEST WAS SUCCESSFULLY DEQUEUED.
Rl=ADDRESS OF THE I/O PACKET.
R2=PHYSICAL UNIT NUMBER.
R3=CONTROLLER INDEX.
R4=ADDRESS OF THE STATUS CONTROL BLOCK.
RS=ADDRESS OF THE UNIT CONTROL BLOCK.

'·-

NOTE: R4 AND RS ARE DESTROYED BY THIS ROUTINE.

5-12

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS

I$GTWRD I
GET' WORD
Get Word i.s in the file BFCTL.
It manipulates words U.BUF and U.BUF+2
in the UCB. Get Word is conditionally assembled.
If a user-written
driver requires this routine, the following question must be answered
affirmatively in Phase 1 of SYSGEN:
IS THE EXECUTIVE ROUTINE $GTWRD REQUIRED? [Y/N] :
This question is
que!stion:

asked

only

you

have

answered

"yes"

the

ARE YOU PLANNING TO INCLUDE A USER WRITTEN DRIVER? [Y/N] :
Calling sequence:
CALL

$GTWRD

Des;cription:

;+
**-$GTWRD-GET NEXT WORD FROM USER BUFFER
THIS ROUTINE IS CALLED TO GET THE NEXT WORD FROM THE USER BUFFER
AND RETURN IT TO THE CALLER ON THE STACK. AFTER THE WORD HAS BEEN
FETCHED, THE NEXT WORD ADDRESS IS CALCULATED.
INPUTS:
R5=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS.
OUTPUTS:
THE NEXT WORD IS FETCHED FROM THE USER BUFFER AND RETURNED
TO THE CALLER ON THE STACK. THE NEXT WORD ADDRESS IS CALCULATED.
ALL REGISTERS ARE PRESERVED ACROSS CALL.

5-13

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS

I$1NTSV I
INTERRUPT SAVE
Interrupt Save is in the file SYSXT.
Calling sequence:
CALL

$INTSV,PRn

n has a range of 0-7.
Description:

:+
**-$INTSV-INTERRUPT SAVE
THIS ROUTINE IS CALLED FROM AN INTERRUPT SERVICE ROUTINE WHEN AN
INTERRUPT IS NOT GOING TO BE IMMEDIATELY DISMISSED. A SWITCH TO
THE SYSTEM STACK IS EXECUTED IF THE CURRENT STACK DEPTH IS +l. WHEN
THE INTERRUPT SERVICE ROUTINE FINISHES ITS PROCESSING, IT EITHER FORKS,
JUMPS TO $INTXT, OR EXECUTES A RETURN.
INPUTS:
4(SP)=PS WORD PUSHED BY INTERRUPT.
2(SP)=PC WORD PUSHED BY INTERRUPT.
O(SP)=SAVED RS PUSHED BY 'JSR R5,$INTSV'.
O(RS)=NEW PROCESSOR PRIORITY.
OUTPUTS:
REGISTER R4 IS PUSHED ONTO THE CURRENT STACK AND THE CURRENT
STACK DEPTH IS DECREMENTED. IF THE RESULT IS ZERO, THEN
A SWITCH TO THE SYSTEM STACK IS EXECUTED. THE NEW PROCESSOR
STATUS IS SET AND A CO-ROUTINE CALL TO THE CALLER IS EXECUTED.

:Note:
A system macro, INTSV$, is provided to simplify the coding
standard interrupt entry processing. See Section 4.3.

5-14

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS

I$1NTXT I
INTERRUPT EXIT
Interrupt Exit is in the file SYSXT.
Calling sequence:
JMP

$INTXT

Description:
;+
**-$INTXT-INTERRUPT EXIT
THIS ROUTINE IS CALLED VIA A RETURN TO EXIT FROM AN INTERRUPT. IF THE
STACK DEPTH IS NOT EQUAL TO ZERO, THEN REGISTERS R4 AND RS ARE
RESTORED AND AN RTI IS EXECUTED. ELSE A CHECK IS MADE TO SEE
IF THERE ARE ANY ENTRIES IN THE FORK QUEUE. IF NONE, THEN R4 AND
RS ARE RESTORED AND AN RTI IS EXECUTED. ELSE REGISTERS R3 THRU
RO ARE SAVED ON THE CURRENT STACK AND A DIRECTIVE EXIT IS EXECUTED.
INPUTS:

(MAPPED SYSTEM)
06(SP)=PS WORD PUSHED BY INTERRUPT.
04(SP)=PC WORD PUSHED BY INTERRUPT.
02(SP)=SAVED RS.
OO(SP)=SAVED R4.

INPUTS:

(REAL MEMORY SYSTEM)

·~··

NONE.
;-

5-1.5

EXECUTIVE SERVICES AVAII.ABLE TO I/O DRIVERS

I$10ALT /$10DON I

I/O DONE ALTERNATE ENTRY and I/O DONE
These routines are in the file IOSUB.
Calling sequences:
CALL
CALL

$IOALT
$!ODON

Description:

;+
**-$IOALT-I/O DONE (ALTERNATE ENTRY)
**-$IODON-I/O DONE
THIS ROUTINE IS CALLED BY DEVICE DRIVERS AT THE COMPLETION OF AN I/O REQUEST
TO DO FINAL PROCESSING. THE UNIT AND CONTROLLER ARE SET IDLE AND $IOFIN IS
.lflllft •.
ENTERED TO FINISH THE PROCESSING.
INPUTS:
RO=FIRST I/O STATUS WORD.
Rl=SECOND I/O STATUS WORD.
R2=STARTING AND FINAL ERROR RETRY COUNTS IF ERROR LOGGING DEVICE.
RS=ADDRESS OF THE UNIT CONTROI. BLOCK OF THE UNIT BEING COMPLETED.
NOTE: IF ENTRY IS AT $IOALT, THEN Rl IS CLEARED TO SIGNIFY THAT THE
SECOND STATUS WORD IS ZERO.
OUTPUTS:
THE UNIT AND CONTROLLER ARE SET IDLE.
R3=ADDRESS OF THE CURRENT I/O PACKET.
;-

NOTE
R4 is destroyed when either of these routines
routine call $IOFIN, which destroys R4 ..

called.

The

These routines push the address of routine $DQUMR on to the stack
before returning to the driver.
This precludes the use of the
stack for temporary data storaqe by divers when calling these
routines.

.~
'i

5-16

May 1979

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS

I $10FIN I
I/O F'INISH
I/O E'inish is in the file IOSUB. Most drivers do not call I/O Finish,
but you should be aware that this routine is executed when a driver
calls $IOALT or $IODON. A driver that references an I/O packet before
it is queued
(bit UC.QUE set--see Section 6.3 for an example) calls
I/O Finish if the driver finds an error while preprocessing the I/O
packet.
Calling sequence:
CALL

$IOFIN

Description:

;+
**-$IOFIN-I/O FINISH

·~·

THIS ROUTINE IS CALLED TO FINISH I/O PROCESSING IN CASES WHERE THE UNIT AND
CONTROLLER ARE NOT TO BE DECLARED IDLE.
INPUTS:
RO=FIRST I/O STATUS WORD.
Rl=SECOND I/O STATUS WORD.
R3=ADDRESS OF THE I/O REQUEST PACKET.
R5=ADDRESS OF THE UNIT CONTROL BLOCK.
om~PUTS:

THE FOLLOWING ACTIONS ARE PERFORMED:
1-THE FINAL I/O STATUS VALUES ARE STORED IN THE I/0 STATUS BLOCK IF
ONE WAS SPECIFIED.
2-THE I/O REQUEST COUNT IS DECREMENTED. IF THE RESULTANT COUNT IS
ZERO, THEN 'TS.RON' IS CLEARED IN CASE THE TASK WAS
STOPPED FOR I/O RUNDOWN.
3-IF 'TS.CKR' IS SET, THEN IT IS CLEARED AND CHECKPOINTING OF THE
TASK IS INITIATED.
4-IF AN AST SERVICE ROUTINE WAS SPECIFIED, THEN AN AST IS QUEUED
FOR THE TASK. ELSE THE I/O PACKET IS DEALLOCATED.
5-A SIGNIFICANT EVENT OR EQUIVALENT IS DECLARED.

·'

NOTE: R4 IS DESTROYED BY THIS ROUTINE.

5-17

EXECUTIVE SERVICES AV.lULABLE TO I/O DRIVERS

I $MPUBM I
MAP UNIBUS TO MEMORY
This routine is in the file IOSUB.
It is used only for PDP-11/70 NPR
devices requiring UNIBUS Mapping Registers.
See Appendix B for a
discussion.
Calling Sequence:
CALL

$MPUBM

Description:

;+
**-$MPUBM-MAP UNIBUS TO MEMORY
THIS ROUTINE IS CALLED BY UNIBUS NPR DEVICE DRIVERS TO LOAD THE
NECESSARY UNIBUS MAP REGISTERS TO EFFECT A TRANSFER TO MAIN MEMORY ON AN 11/70 PROCESSOR WITH EXTENDED MEMORY.
INPUTS:
R4=ADDRESS OF DEVICE SCB.
RS=ADDRESS OF DEVICE UCB.
OUTPUTS:
THE UNIBUS MAP REGISTERS NECESSARY TO EFFECT THE
ARE LOADED.
NOTE: REGISTER R3 IS PRESERVED ACROSS CALL.
;-

5-lB

TRANSFER

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS

ISMPUB11
MAP UNIBUS TO MEMORY (ALTERNATE ENTRY)
This routine is in file IOSUB.
It is used only for PDP-11/70 NPR
devices that require UNIBUS Mapping Registers and support parallel
operations.
See Appendix B for a discussion of using this routine.
Calling Sequence:
CALL

$MPUB1

Description:
;+
**-$MPUB1-MAP UNIBUS TO MEMORY (ALTERNATE ENTRY)
THIS ROUTINE IS CALLED BY UNIBUS NPR DEVICE DRIVERS TO LOAD THE
NECESSARY UNIBUS MAP REGISTERS TO EFFECT A TRANSFER TO MAIN
MEMORY ON AN 11/70 PROCESSOR WITH gXTENDED MEMORY. THIS ALTERNATE
ENTRY POINT ALLOWS THE DRIVER TO SPECIFY A NON-STANDARD UMR MAPPING
ASSIGNMENT BLOCK.
INPUTS:
RO=ADDRESS OF A UMR MAPPING ASSIGNMENT BLOCK
OUTPUTS:
THE UNIBUS MAP REGISTERS NECESSARY TO EFFECT THE
TRANSFER ARE LOADED
NOTE: REGISTER R3 IS PRESERVED ACROSS CALL.
;-

5-18.l

May 1979

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS

I$PTBYT I
PUT BYTE
Put Byte is in the file BFCTL.
U.BUF+2 in the UCB.

Put Byte manipulates words

U.BUF

and

Calling sequence:
CALL

$PTBYT

Description:
;+
**-$PTBYT-PUT NEXT BYTE IN USER BUFFER
THIS ROUTINE IS CALLED TO PUT A BYTE IN THE NEXT LOCATION IN
USER BUFFER. AFTER THE BYTE HAS BEEN STORED, THE NEXT BYTE ADDRESS
IS INCREMENTED.
INPUTS:
RS=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS.
2(SP)=BYTE TO BE STORED IN THE NEXT LOCATION OF THE USER BUFFER.
OUTPUTS:
THE BYTE IS STORED IN THE USER BUFFER AND REMOVED FROM
THE STACK. THE NEXT BYTE ADDRESS IS INCREMENTED.
ALL

REGIS~rERS

ARE PRESERVED ACROSS CALL.

5-19

EXECUTIVE SERVICES AVAILABLE TO I/0 DRIVERS

I $PTWRD I
PUT WORD
Put Word is in the file BFCTL.
It manipulates words U.BUF and U.BUF+2
in the UCB.
Put Word is conditionally assembled.
If a user-written
driver requires this routine, the following question must be answered
affirmatively in Phase 1 of SYSGEN:
IS THE EXECUTIVE ROUTINE $PTWRD REQUIRED? [Y/N] :
This question is
question:

asked

only

you

have

answered

"yes"

the

ARE YOU PLANNING TO INCLUDE A USER WRITTEN DRIVER? [Y/N] :
Calling sequence:
CALL

$PTWRD

Description:
;+
**-$PTWRD-PUT NEXT WORD IN USER BUFFER
THIS ROUTINE IS CALLED TO PUT A WORD IN THE NEXT LOCATION IN
USER BUFFER. AFTER THE WORD HAS BEEN STORED, THE NEXT WORD ADDRESS
IS CALCULATED.
INPUTS:
RS=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS.
2(SP)=WORD TO BE STORED IN THE NEXT LOCATION OF THE BUFFER.
OUTPUTS:
THE WORD IS STORED IN THE USER BUFFER AND REMOVED FROM
THE STACK. THE NEXT WORD ADDRESS IS CALCULATED.
ALL REGISTERS ARE PRESERVED ACROSS CALL.
;-

5-20

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS

I $QINSP I
QUEUE INSERTION BY PRIORITY
This routine is in the file QUEUE. A driver may call $QINSP to insert
into the I/O queue an I/O packet that the Executive has not already
placed in the queue.
Queue Insertion by Priority is used only by
drivers setting UC.QUE in U.CTL.
See Section 6.3 for an example.
Calling Sequence:
CALL

$QINSP

Description:

:+
**-$QINSP-QUEUE INSERTION BY PRIORITY
THIS ROUTINE IS CALLED TO INSERT AN ENTRY IN A PRIORITY ORDERED
LIST. THE LIST IS SEARCHED UNTIL AN ENTRY IS FOUND THAT HAS A
LOWER PRIORITY OR THE END OF THE LIST IS REACHED. THE NEW
ENTRY IS THEN LINKED INTO THE LIST AT THE APPROPRIATE POINT.
INPUTS:
RO=ADDRESS OF THE TWO WORD LISTHEAD.
Rl=ADDRESS OF THE ENTRY TO BE INSERTED.
OUTPUTS:
THE ENTRY IS LINKED INTO THE LIST BY PRIORITY.
RO AND Rl ARE PRESERVED ACROSS CALL.

5-21

EXECUTIVE SERVICES AVAII,ABLE TO I/O DRIVERS

ISRELocl
RELOCATE
Relocate is in the file IOSUB. A driver may call $RELOC to relocate a
task virtual address while the task is the current task.
Relocate is
normally used only by drivers setting UC.QUE in U.CTL.
See Section
6.3 for an example.
Calling Sequence:
CALL

$RELOC

Description:
;+
**-SRELOC-RELOCATE USER VIRTUAL ADDRESS
THIS ROUTINE IS CALLED TO TRANSFORM A 16 BIT USER VIRTUAL ADDRESS
INTO A RELOCATION BIAS AND DISPLACEMENT IN BLOCK RELATIVE TO APR6.
INPUTS:
RO=USER VIRTUAL ADDRESS TO RELOCATE.
OUTPUTS:
Rl=RELOCATION BIAS TO BE LOADED INTO PAR6.
R2=DISPLACEMENT IN BLOCK PLUS 140000 (PAR6 BIAS) •
RO AND R3 ARE PRESERVED ACROSS CALL.

5-22

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS

ISSTMAPI
SET UP UNIBUS MAPPING ADDRESS
This routine is in the file IOSUB.
It is used only for PDP-11/70 NPR
devices requiring UNIBUS Mapping Registers.
See Appendix B for a
discussion.
Calling Sequence:
CALL

$STMAP

Description:

:+
**-$STMAP-SET UP UNIBUS MAPPING ADDRESS
THIS ROUTINE IS CALLED BY UNIBUS NPR DEVICE DRIVERS TO SET UP THE
UNIBUS MAPPING ADDRESS, FIRST ASSIGNING THE UMR'S. IF THE UMR'S
CANNOT BE ALLOCATED, THE DRIVER'S MAPPING ASSIGNMENT BLOCK IS PLACED
IN A WAIT QUEUE AND A RETURN TO THE DRIVER'S CALLER IS EXECUTED. THE
ASSIGNMENT BLOCK WILL EVENTUALLY BE DEQUEUED WHEN THE UMR'S ARE
AVAILABLE AND THE DRIVER WILL BE REMAPPED AND RETURNED TO WITH Rl-RS
PRESERVED AND THE NORMAL OUTPUTS OF THIS ROUTINE. THE DRIVER'S
CONTEXT IS STORED IN THE ASSIGNMENT BLOCK AND FORK BLOCK WHILE IT IS
BLOCKED AND IN THE WAIT QUEUE. ONCE A DRIVER'S MAPPING ASSIGNMENT
BLOCK IS PLACED IN THE UMR WAIT QUEUE, IT IS NOT REMOVED FROM THE
QUEUE UNTIL THE UMR'S ARE SUCCESSFULLY ASSIGNED. THIS STRATEGY
ASSURES THAT WAITING DRIVERS WILL BE SERVICED FIFO AND THAT DRIVER'S
WITH LARGE REQUESTS FOR UMR'S WILL NOT WAIT INDEFINITELY.
INPUTS:
R4=ADDRESS OF DEVICE SCB.
RS=ADDRESS OF DEVICE UCB.
(SP)=RETURN TO DRIVER'S CALLER.
OUTPUTS:
UNIBUS MAP ADDRESSES ARE SET UP IN THE DEVICE UCB AND THE
ACTUAL PHYSICAL ADDRESS IS MOVED TO THE SCB.

NOTE: REGISTERS Rl, R2, AND R3 ARE PRESERVED ACROSS CALL.

NOTE
This routine pushes the address
of
routine $DQUMR+2 on to the stack before
returning to the caller.
A driver,
therefore,
should not use the stack for
temporary data storage when calling this
routine.

5-23

May 1979

EXECUTIVE SERVICES AVAII,ABLE TO I/O DRIVERS

j$STMP1j

SET UP UNIBUS MAPPING ADDRESS (ALTERNATE ENTRY)
This routine is in file IOSUB.
It is used only for PDP-11/70 NPR
devices that require UNIBUS Mapping Registers and support parallel
operations. See Appendix B for a discussion of using this routine.
Calling Sequence:
CALL

$STMP1

Description:
;+
**-$STMP1-SET UP UNIBUS MAPPING ADDRESS (ALTERNATE ENTRY)
THIS ENTRY CODE SETS UP AN ALTERNATE: DATA STRUCTURE USED AS
A UMR MAPPING ASSIGNMENT BLOCK AND CONTEXT STORAGE BLOCK, IN
THE SAME MANNER AS $STMAP USES THE FORK BLOCK AND MAPPING
BLOCK IN THE SCB. THE FORMAT OF THE STRUCTURE IS AS FOLLOWS:
4 WORDS USED FOR SAVING
DRIVER'S CONTEXT IN CASE
UMR'S CAN'T BE MAPPED
IMMEDIATELY.

6 WORDS USED AS A UMR
MAPPING ASSIGNMENT BLOCK.

INPUTS:
RO=ADDRESS OF THE DATA STRUCTURE DEPICTED ABOVE
R4=ADDRESS OF DEVICE SCB
RS=ADDRESS OF DEVICE UCB
OUTPUTS:
DATA STRUCTURE POINTERS SET UP FOR ENTRY TO $STMP2 IN $STMAP
;-

""·
5-24

May 1979

CHAPTER 6
INCLUDING A USER-WRITTEN DRIVER--TWO EXAMPLES

The= first example that follows
is a complete illustration of the
procedures required to add a resident driver and resident data base to
an RSX-llM system to run on a system without support for loadable
drivers and without multiuser protection. The driver in the example
supports the punch capability of the PCll Paper Tape Reader/Punch.
Section 6.3 gives a coding example from a resident driver that
inhibits
the
automatic
packet
queuing in QIO processing to
address-check and relocate a special user buffer.
In addition to the examples shown in this chapter, you should review
the source code for one or more standard DIGITAL-supplied drivers.
Also, examine file SYSTB.MAC, which contains SYSGEN created data
structures.

6.1

DEVICE DESCRIPTION

The PCll Paper Tape Reader/Punch is capable of reading 8-hole,
unoiled, perforated paper tape at 300 characters-per-second, and
punching tape at 50 characters-per-second. The system consists of a
Paper Tape Reader/Punch and Controller.
A unit containing only a
reader (PRll) is also available.
In reading tape, a set of photodiodes translates the presence or
absence of holes in the tape to logic levels representing l's and O's.
In punching tape, a mechanism translates logic levels representing l's
and O's to the presence or absence of holes in the tape. Any
information read or punched is parallel-transferred through the
Controller.
When an address is placed on the UNIBUS, the Controller
decodes the address and determines if the reader or punch has been
selected.
If one of the four device-register addresses has been
selected, the Controller determines whether an input or an output
operation should be performed. An input operation from the reader is
initiated when the processor transmits a command to the Paper Tape
Reader status register.
An output operation is initiated when the
processor transfers a byte to the Paper Tape Punch buffer register.
The Controller enables the PDP-11 System to control the reading or
punching of paper tape in a flexible manner. The reader can be
operated independently of the punch;
either device can be under
direct program control or can operate without direct supervision,
through the use of interrupts, to maintain continuous operation.

6·-1

INCLUDING A USER-WRITTEN DRIVER--TWO EXAMPLES
6.2

DATA BASE AND DRIVER SOURCE

The simplicity of writing a conventional driver for RSX-llM is
obscured by the volume of explanation required to cover the universal
case. As you will see below,
in a particular case, building a
conventional driver is a straightforward and modest undertaking.

6.2.1

The Data Base

The resident data base source shown below is self-explanatory.
Take
special note of the legal function mask words, starting at line 45.
The standard function codes listed in Table 4-1 were used in creating
the mask. Thus, the Punch driver accepts the following I/O functions:
Cancel I/O
Write Logical Block
Attach Device
Detach Device
Access File For Read/Write
Access File For Read/Write/Extend
Deaccess File
Write Virtual Block
Cancel I/O is mandatory. Write Logical Block
function actually supported.

the

only

transfer

Attach/Detach are control functions.
The three
Access/Deaccess
functions are legal for FCS and RMS compatibility, but are no-op'ed.
Write Virtual Block is legal but is converted to Write Logical Block
by QIO directive processing.
The Bit Mask for each function is as follows:

FUNCTION
CAN
WLB
ATT
DET
ACW
ACE
DAC
WVB

FUNCTION CODE(OCTAL) MASK(OCTAL) BIT RANGE(DECIMAL)
0
1
3
4
16
17
20
22

000001
000002
000010
000020
040000
100000
000001
000004

0-15.
0-15.
0-15.
0-15.
0-15.
0-15.
16. -31.
16.-31.

The legal masks result from adding the 0-15(10)
bit-range words to
form a mask and all the 16-31(10) bit-range words to form the second
mask.
The control, no-op, and ACP masks are created in an analogous fashion,
matching bit positions with legal function-code meanings.
The complete set of mask words appears on lines 45 through 52
data-structure source.

the

The function code selections for record-oriented devices are intended
to match FCS and RMS requirements for file-structured devices. When
FCS or RMS executes an Access For Write, it is simply marked a no-op.
This tends to minimize FCS and RMS device-dependent logic.

6-2

INCLUDING A USER-WRITTEN DRIVER--TWO EXAMPLES
Note also on line 84 that the controller number, which is encoded in
the low byte of the interrupt vector PS word in RSX-llM, is set ~o
zero.
Finally, since the code represents a resident data base, note
that lines 78 through 85 would be omitted for a loadable data base.
• 'rITLE USRTB
• !DENT /01/

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18:
19
20
21
22
23
24.

COPYRIGHT 1976, DIGITAL EQUIPMENT CORP., MAYNARD, MASS.
THIS SOFTWARE IS FURNISHED TO PURCHASER UNDER A LICENSE FOR USE
ON A SINGLE COMPUTER SYSTEM AND CAN BE COPIED (WITH INCLUSION
OF DEC'S COPYRIGHT NOTICE) ONLY FOR USE IN SUCH SYSTEM, EXCEPT
AS MAY OTHERWISE BE PROVIDED IN WRITING BY DEC.
THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL
EQUIPMENT CORPORATION.
DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY
OF ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC.
VERSION 01
T. J. PASCUSNIK

25-NOV-74

CONTROL BLOCKS FOR PAPER TAPE PUNCH DRIVER
MACRO LIBRARY CALLS

2~i

26
27
28
29
30
31
32
33

.MCALL DCBDF$,HWDDF$
DCBDF$
HWDDF$

;DEFINE DEVICE CONTROL BLOCK OFFSETS*
;DEFINE HARDWARE REGISTERS

PAPER TAPE PUNCH DEVICE DATA BASE

3~1

35
36
37
38
39
40
41
42
43
44
45
46
47
40
49
50
51
52
53
54
55
56
57
SB

59
60
61

PAPER TAPE PUNCH DEVICE CONTROL BLOCK
t

$USRTB::
PPDCB:

.WORD
.WORD
.ASCII
.BYTE

0
.PPO
/PP/
0,0

.WORD
.WORD
. WORD
. WORD
• WORD
. WORD
. WORD
• WORD
. WORD
.WORD

PPND-PPST
$PPTBL
140033
30
140000
0
5
0
l

;LINK TO NEXT DCB
;POINTER TO FIRST UCB
;DEVICE NAME
;LOWEST AND HIGHEST UNIT NUMBERS COVERED
;
BY THIS DCB
;LENGTH OF EACH UCB IN BYTES
;POINTER TO DRIVER DISPATCH TABLE
;LEGAL FUNCTION MASK CODES 0-15 .
;CONTROL FUNCTION MASK CODES 0-15 .
;NO-P'ED FUNCTION MASK CODES 0-15 .
;ACP FUNCTION MASK CODES 0-15 •
;LEGAL FUNCTION MASK CODES 16.-31 .
;CONTROL FUNCTION MASK CODES 16.-31 .
;NO-OP'ED FUNCTION MASK CODES 16.-31 .
;ACP FUNCTION MASK CODES 16.-31.

PAPER TAPE PUNCH UNIT CONTROL BLOCK
.PPO::
PPST=.
.WORD
.WORD
.BY'I'E

PP DCB
.-2
UC.ATT,O

* Appendix C lists all macros
control block offsets.

;BACK POINTER TO DCB
; POINTER TO REDIRECT UNIT UCB
;CONTROL PROCESSING FLAG (PASS CONTROL
ON ATTACH/DETACH) , UNIT STATUS

that

6-3

exist

RSX-llM

generate

May 1979

INCLUDING A USER-WRITTEN DRIVER--TWO EXAMPLES
62
63
64
65
66
67
68
69
70

.BYTE
.WORD

0,0
DV.REC

.WORD

64.

71
72
73

.WORD
.WORD
.BLKW

PPSCB
0
1

74
75
76

.BLKW
.BLKW

1
1

;PHYSICAL UNIT NUMBER, UNIT STATUS EXTENSION
;FIRST DEVICE CHARACTERISTICS WORD
;
(RECORD-ORIENTED DEVICE)
;SECOND DEVICE CHARACTERISTICS WORD
;
(FOR INTERNAL USE BY DRIVER)
;THIRD DEVICE CHARACTERISTICS WORD
(FOR INTERNAL USE BY DRIVER)
;
;FOURTH DEVICE CHARACTERISTICS WORD
(DEFAULT BUFFER SIZE IN BYTES)
;
;POINTER TO SCB
;TCB ADDRESS OF ATTACHED TASK
;RELOCATION BIAS OF BUFFER OF CURRENT
;
I/O REQUEST
;ADDRESS OF BUFFER OF CURRENT I/O REQUEST
;BYTE COUNT OF CURRENT I/O REQUEST

77 PPND=.
78 ;

79 ; PAPER TAPE PUNCH INTERRUPT VECTOR
80
.ASECT
81
82 .=74
;ADDRESS OF INTERRUPT ROUTINE
• WORD
$PPINT
83
;INTERRUPT AT PRIORITY 7 (CONTROLLER~O)
.WORD
PR7!0
84
.PSECT
85
86
PAPER TAPE PUNCH STATUS CONTROL BLOCK
87
88 I
;CONTROLLER I/O QUEUE LISTHEAD
.WORD
0
89 PPSCB:
(POINTER TO FIRST ENTRY)
90
;
(POINTER TO LAST ENTRY)
.-2
.WORD
91
;DEVICE PRI, INTERRUPT VECTOR ADDRESS/4
PR4,74/4
.BYTE
92
;CURRENT AND INITIAL TIMEOUT COUNTS
0,4
.BYTE
93
;CONTROLLER INDEX AND STATUS
0,0
.BYTE
94
;
(O=IDLE, !=BUSY)
95
;ADDRESS OF CONTROL STATUS REGISTER
177554
.WORD
96
;ADDRESS OF CURRENT I/O PACKET
.BLKW
1
97
;FORK BLOCK ALLOCATION
.BLKW
4
98
99
.END
100

6.2.2

Driver Code

The code shown below for the punch capability of the PCll is typical
for a conventional driver.
In fact, many of the descriptive comments
can be used as a template and easily tailored to a driver for another
device.
The structure of the driver follows the classic
separated into processing code for:

RSX-llM

form,

being

Initiator
Power Failure
Interrupt
Timeout
Cancel I/O
The driver itself services only Write Logical, Attach, and Detach I/O
functions.
Attach and Detach result in the punching of 170(10} nulls
each for header and trailer.
Power Failure and Cancel I/O are handled by means of
as is the device-not-ready condition.

6-4

device

timeout,

INCLUDING A USER-WRITTEN DRIVER--TWO EXAMPLES
The PP driver uses the following Executive services:
$INTXT
$GTPKT
$GTBYT
$DVMSG
$INTSV is used indirectly;
Section 4.3.

it is called by INTSV$

(line

165).

See

being

Comments beginning with ';;;' indicate that the instruction
executed at a priority level greater than or equal to 4.

The code contained in lines 139-141 is used to inhibit the punching of
a trailer on ATT/DET if the task is being aborted. This is especially
desirable when the device is not ready
(for example, out of paper
tapE=}
and the system has generated the detach for the aborting
process.
l.

2:.
3.

.TITLE
• !DENT

PPDRV
/02/

4,.

5.
6.
7.
8.
9.
10.
11..
12.
13.
14.

1976,

DIGITAL

EQUIPMENT

CORP.,

MAYNARD,

MASS.

THIS SOFTWARE IS FURNISHED TO PURCHASER UNDER A LICENSE FOR USE
ON A SINGLE COMPUTER SYSTEM AND CAN BE COPIED (WITH INCLUSION
OF DEC'S COPYRIGHT NOTICE) ONLY FOR USE IN SUCH SYSTEM, EXCEPT
AS MAY OTHERWISE BE PROVIDED IN WRITING BY DEC.
THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL
EQUIPMENT CORPORATION.

l~i.

16.
17.

DEC ASSUMES NO RESPONSIBILITY FOR
OF ITS SOFTWARE ON EQUIPMENT WHICH

THE USE OR RELIABILITY
IS NOT SUPPLIED BY DEC.

18.

•

19.
20.

VERSION 02

21.

T. J. PASCUSNIK 25-NOV-74

22.
23.
24.
25.
26.
27.
28.
29.
30 .·
31.
32.
33.
34.
3 ~).
36.
37 •
38.
39.
40.
41.

42.
43.
44.
45.
46.
47.
48.
49.
50.

MODIFIED BY:
C. A. ANDERS 15-MAR-76
CAOOl -- ADDITION OF LOADABLE DRIVER SUPPORT.
T. J. PASCUSNIK 4-APR-76
TP031 -- EXECUTIVE DATA STRUCTURE CHANGES.
PCll PAPER TAPE PUNCH DRIVER
MACRO LIBRARY CALLS
.MCALL
ABODF$
HWDDF$
PKTDF$
TCBDF$

ABODF$,HWDDF$,PKTDF$,TCBDF$
;DEFINE TASK ABORT CODES
;DEFINE HARDWARE REGISTER SYMBOLS
;DEFINE I/O PACKET OFFSETS
;DEFINE TASK CONTROL BLOCK OFFSETS

EQUATED SYMBOLS
PAPER TAPE PUNCH STATUS WORD BIT DEFINITIONS (U.CW2)

6-5

INCLUDING A USER-WRITTEN DRIVER--TWO EXAMPLES
WAIT=lOOOOO
51.
;WAITING FOR DEVICE TO COME ON-LINE (l=YES)
ABORT=40000
52.
;ABORT CURRENT I/O REQUEST (l=YES)
53.
TRAIL=200
;CURRENTLY PUNCHING TRAILER (l=YES)
54.
55.
LOCAL DATA
56.
57.
58.
CONTROLLER IMPURE DATA TABLES (INDEXED BY CONTROLLER NUMBER)
59.
60.
CNTBL:
.BLKW
P$$Pll
;ADDRESS OF UNIT CONTROL BLOCK
61.
62.
63.
.IF GT P$$Pll-l
64.
65.
; Tl~MPORARY STOHAGE FOR CONTROLLER NUMBER
TEMP:
.BLKW
l
66.
67.
.ENDC
; CAOOl
68.
; CAOOl
69.
70.
71.
DRIVER DISPATCH TABLE
72.
73.
74.
;DEVICE INITIATOR ENTRY POINT
.WORD
PP I NI
75. $PPTBL::
; ClrnCEL I/O OPERATION ENTRY POINT
.WORD
PP CAN
76.
;DEVICE TIMEOUT ENTRY POINT
PPOUT
.WORD
77.
;POWERFAIL ENTRY POINT
PPPWF
.WORD
78.
79.
80. ;+
**-PPINI-PCll PAPER TAPE PUNCH CONTROLLER INITIATOR
81.
82.
THIS ROUTINE IS ENTERED FROM THE QUEUE I/O DIRECTIVE WHEN AN I/O REQUEST
83.
IS QUEUED AND AT THE END OF A PREVIOUS I/O OPERATION TO PROPAGATE THE EXECU84.
TION OF THE DRIVER. IF THE SPECIFIED CONTROLLER IS NOT BUSY, THEN AN ATTEMPT
85.
IS MADE TO DEQUEUE THE NEXT I/O REQUEST. ELSE A RETURN TO THE CALLER IS
86.
EXECUTED. IF THE DEQUEUE ATTEMPT IS SUCCESSFUL, THEN THE NEXT I/O OPER87.
ATION IS INITIATED. A RETURN TO THE CALLER IS THEN EXECUTED.
88.
89.
INPUTS:
90.
91.
R5=ADDRESS OF THE UCB OF THE CONTROLLER TO BE INITIATED.
92.
93.
94.
OUTPUTS:
95.
96.
IF THE SPECIFIED CONTROLLER IS NOT BUSY AND AN I/O REQUEST IS WAIT97.
ING TO BE PROCESSED, THEN THE REQUEST IS DEQUEUED AND THE I/O OPER98.
ATION IS INITIATED.
99. I
100.
101.
.ENABL LSB
102.
PPINI: CALL
$GTPKT
;GET AN I/O PACKET TO PROCESS
103.
BCS
PPPWF
;IF CS CONTROLLER BUSY OR NO REQUEST
104.
105.
106.
THE FOLLOWING ARGUMENTS ARE RETURNED BY $GTPKT:
107.
108.
Rl=ADDRESS OF THE I/O REQUEST PACKET.
109.
R2=PHYSICAL UNIT NUMBER OF THE REQUEST UCB.
110.
R3=CONTROLLER INDEX.
111.
R4=ADDRESS OF THE STATUS CONTROL BLOCK.
112.
R5=ADDRESS OF THE Uc THE CONTROLLER TO BE INITIATED.
113.
114.
PAPER TAPE PUNCH I/O REQUEST PACKET FORMAT:
115.
116.
WD. 00
I/O QUEUE THREAD WORD.
117.
WD. 01
REQUEST PRIORITY, EVENT FLAG NUMBER.
118.
WD. 02
ADDRESS OF THE TCB OF THE REQUESTER TASK.
119.
WD. 03
POINTER TO SECOND LUN WORD IN REQUESTER TASK HEADER.
120.
WD. 04
CONTENTS OF THE FIRST LUN WORD IN REQUESTER TASK HEADER (UCB)
121.
WD. 05
I/O FUNCTION CODE (IO.WLB, IO.ATT OR IO.DET).
122.
WD. 06
VIRTUAL ADDRESS OF I/O STATUS BLOCK.
123.
WD. 07
RELOCATION BIAS OF I/O STATUS BLOCK.

6-6

~
I

INCLUDING A USER-WRITTEN DRIVER--TWO EXAMPLES
124.
WD. 10
I/O STATUS BLOCK ADDRESS (REAL OR DISPLACEMENT + 140000).
12S.
WD. 11
VIRTUAL ADDRESS OF AST SERVICE ROUTINE.
126.
WD. 12
RELOCATION BIAS OF I/O BUFFER.
127.
WD. 13
BUFFER ADDRESS OF I/O TRANSFER.
128.
WD. 14
NUMBER OF BYTES TO BE TRANSFERED.
129.
WD. lS
NOT USED.
130.
WD. 16
NOT USED.
131.
WD. 17
NOT USED.
132.
WD. 20
NOT USED.
133.
134.
l3S.
MOV
RS,CNTBL(R3)
;SAVE UCB POINTER FOR INTERRUPT ROUTINE
136.
CLR
U.CW2(RS)
;CLEAR ALL SWITCHES
137.
CMPB
I.FCN+l(Rl) ,#IO.WLB/2S6. ;WRITE LOGICAL BLOCK FUNCTION?
138.
BEQ
10$
;IF EQ YES
139.
MOV
I.TCB(Rl) ,RO
;GET REQUESTOR TCB ADDRESS
140.
BIT
#T2.ABO,T.ST2(R0) ;TASK BEING ABORTED?
; TP031
141.
BNE
6S$
;IF NE YES - DON'T PUNCH TRAILER
142.
BIS
#TRAIL,U.CW2(RS) ;OTHERWISE FUNCTION IS ·ATTACH OR DETACH
.143.
;
SET FLAG TO PUNCH TRAILER
144.
MOV
#170.,U.CNT(RS) ;SET COUNT FOR 170 NULLS
14S. 10$:
BIS
#WAIT,U.CW2(RS) ;ASSUME WAIT FOR DEVICE OFF LINE
TST
@S.CSR(R4)
;DEVICE OFF LINE?
146.
80$
;IF MI YES
147.
BMI
BIC
#WAIT,U.CW2(RS) ;DEVICE ON LINE, CLEAR WAIT CONDITION
148. 20$:
S.ITM(R4) ,S.CTM(R4) ;SET TIMEOUT COUNT
MOVB
149.
lSO.
MOV
#100,@S.CSR(R4) ;ENABLE INTERRUPTS
lSl.
lS2.
POWERFAIL IS HANDLED VIA THE DEVICE TIMEOUT FACILITY AND THEREFORE CAUSES
lS3.
1S4.
NO IMMEDIA'l'E ACTION ON THE DEVICE. THIS IS DONE TO AVOID A RACE CONDITION
THAT COULD EXIST IN RESTARTING THE I/O OPERATION
lSS.
1S6.
1S7.
158.
PPPWF:
RETURN
lS9.
160. ;+
161. ; **-$PPINT-PC11 PAPER TAPE PUNCH CONTROLLER INTERUPTS
162. '
163.
164. $PPIN'l1 : :
; ; ; REF LABEL
16S.
INTSV$ PP,PR4,P$$Pll
;;;GENERATE INTERRUPT SAVE CODE ; CAOOl
166.
MOV
U.SCB(RS) ,R4
;;;GET ADDRESS OF STATUS CONTROL BLOCK
167.
MOVB
S.ITM(R4) ,S.CTM(R4) ;;;RESET TIMEOUT COUNT
168.
MOV
S.CSR(R4) ,R4
;;;POINT R4 TO CONTROL STATUS REGISTER
.169.
MOV
(R4)+,U.CW3(RS) ;;;SAVE STATUS
.170.
BMI
60$
;;;IF MI, ERROR
.171.
SUB
#1 , U. CNT (RS)
;;;DECREMENT CHARACTER COUNT
.17 2.
BCS
SO$
;;;IF CS, THEN DONE
.173.
TSTB
U.CW2(RS)
;;;CURRENTLY PUNCHING TRAILER?
.174.
BPL
30$
;;;IF PL NO
CLRB
.l 7S.
(R4)
;;;LOAD NULL INTO OUTPUT REGISTER
.176.
BR
40$
;;;BRANCH TO LOAD IT
.177. 30$:
CALL
$GTBYT
;;;GET NEXT BYTE FROM USER BUFFER
.178.
MOVB
(SP)+, (R4)
;;;LOAD BYTE INTO OUTPUT REGISTER
.179. 40$:
JMP
$INTXT
;;;EXIT FROM INTERRUPT
.180. SO$:
INC
U.CNT(RS)
;;;RESET BYTE COUNT
181. 60$:
CLR
-(R4)
;;;DISABLE PUNCH INTERRUPTS
.182.
CALL
$FORK
;;;CREATE SYSTEM PROCESS
183.
MOV
U. SCB (RS) , R4
;POINT R4 TO SCB
184.
MOV
S. PKT ( R4) , Rl
;POINT Rl TO I/O PACKET
18S.
MOV
I.PRM+4(Rl) ,Rl
;
AND PICK UP CHARACTER COUNT
U. CNT (RS) , Rl
186.
SUB
;CALCULATE CHARACTERS TRANSFERRED
187.
MOV
#IS.SUC&377,RO
;ASSUME SUCCESSFUL TRANSFER
188.
TST
U.CW3(RS)
;DEVICE ERROR?
189.
BPL
70$
;IF PL NO
190. 6S$:
MOV
#IE. VER&377 ,RO
;UNRECOVERABLE HARDWARE ERROR CODE
191. 70$:
CALL
$IODON
;INITIATE I/O COMPLETION
192.
BR
PP IN I
;BRANCH BACK FOR NEXT REQUEST
193.
194.
19S.
DEVICE TIMEOUT RESULTS IN A NOT READY MESSAGE BEING PUT OUT 4 TIMES A
MINUTE. TIMEOUTS ARE CAUSED BY POWERFAILURE AND PUNCH FAULT CONDITIONS.
196.
197.

6-7

INCLUDING A USER-WRITTEN DRIVER--TWO EXAMPLES
198.
199.
200.
201.
202.
203.
204.
205.
206.
207.
208.
209.
210.
211.
212.
213.
214.
215.
216.
217.
218.
219.
220.
221.
222.
223.
224.
225.
226.

6.3

PPOUT:
80$:

CLRB
CLRB
MOV
MOV
BPL
MOV
ASL
BMI
TST
BPL
MOV
MOVB
DECB
BNE
MOVB
CAL LR
.DSABL

@S.CSR(R4)
;;;DISABLE PUNCH INTERRUPT
PS
;;;ALLOW INTERRUPTS
#IE. DNR& 3 77, RO
;ASSUME DEVICE NOT READY ERROR
U .CW2 (RS) ,Rl
;ARE WE WAITING FOR DEVICE READY?
70$
;IF PL NO, TERMINATE I/O REQUEST
#IE.AB0&377 ,RO
;ASSUME REQUEST IS TO BE ABORTED
Rl
;ABORT REQUEST?
70$
;IF MI YES
@S.CSR(R4)
;PUNCH READY?
20$
;IF PL YES
#T.NDNR,RO
;SET FOR NOT READY MESSAGE
#l,S.CTM(R4)
;SET TIMEOUT FOR 1 SECOND
S.STS(R4)
;TIME TO OUTPUT MESSAGE?
PPPWF
;IF NE NO
#15. ,S.STS(R4) ;SET TO OUTPUT NEXT MESSAGE IN 15. SECONDS
$DVMSG
;OUTPUT MESSAGE AND RETURN
LSB

.~
I

CANCEL I/O OPERATION-FORCE I/O TO COMPLETE IF DEVICE IS NOT READY
PPCAN:
10$:

CMP
BNE
BIS
RETURN

Rl,I.TCB(RO)
;;;REQUEST FOR CURRENT TASK?
10$
;;;IF NE NO
#ABORT,U.CW2(R5) ;;;SET FOR ABORT IF DEVICE NOT READY

~'
I

.END

HANDLING SPECIAL USER BUFFERS

Some drivers need to handle user buffers in addition to the buffer
that the Executive address-checks and relocates in a normal transfer
request. Address-checking and relocation operations must take place
in the context of the task issuing the I/O request, because the
mapping registers are set for
the issuing task.
However,
in the
normal driver interface, the task context after the call to $GTPKT is
not, in general, that of the issuing task.
Thus, drivers that need to handle special buffers must be able to
reference the I/O packet before it is queued, while the context of the
issuing task is still intact.
The following coding excerpts from a standard RSX-llM driver
AFCll driver)
illustrate the handling of a special user buffer.
key points are:

(the
The

The UC.QUE bit has been set in the control byte
(U.CTL)
of
the UCB for each device/unit.
(This is not shown in the
coding excerpts below.)

The routine that is referenced as the initiator entry point
in the driver dispatch table performs the following actions:

Picks up the user
address-checks it.

virtual

address

and

conditionally

Relocates the virtual address, storing
into the packet.

the

result

Inserts the packet into the I/O queue and falls
to the entry point AFINI, which calls $GTPKT.

through

The driver propagates its own execution by branching back
AFINI to call $GTPKT.

6-8

back

INCLUDING A USER-WRITTEN DRIVER--TWO EXAMPLES
DRIVER DISPATCH TABLE
$AFTBL: : • WORD
.WORD
.WORD
.WORD

AFC HK
AF CAN
AFOUT
AFPWF

;DEVICE INITIATOR ENTRY POINT
;CANCEL I/O OPERATION ENTRY POINT
;DEVICE TIMEOUT ENTRY POINT
;POWERFAIL ENTRY POINT

;+
**--AFCHK-A.FCll ANALOG TO DIGITAL CONVERTER CONTROLLER PARAMETER CHECKING
THIS ROUTINE IS ENTERED FROM THE QUEUE I/O DIRECTIVE WHEN AN
IS RECEIVED FOR THE AFCll ANALOG TO DIGITAL CONVERTOR. AFCll
CONTAIN DEVICE DEPENDENT INFORMATION THAT MUST BE CHECKED IN
OF THE ISSUING TASK. THEREFORE THE I/O REQUEST IS NOT QUEUED
THE DRIVER.

I/O REQUEST
I/O REQUESTS
THE CONTEXT
BEFORE CALLING

INPUTS:
Rl=ADDRESS OF THE I/O REQUEST PACKET.
R4=ADDRESS OF THE STATUS CONTROL BLOCK.
RS=ADDRESS OF THE UCB OF THE CONTROLER TO BE INITIATED.
OU'l~PUTS:

THE CONTROL BUFFER IS ADDRESS CHECKED TO DETERMINE WHETHER IT LIES
WITHIN THE ISSUING TASK'S ADDRESS SPACE. IF THE ADDRESS CHECK
SUCCEEDS, THEN THE CONTROL BUFFER ADDRESS IS RELOCATED AND STORED
IN THE I/O PACKET, THE I/O PACKET IS INSERTED IN THE CONTROLLER
QUEUE, AND THE DEVICE INITIATOR IS ENTERED TO START THE CONTROLLER.
ELSE AN ILLEGAL BUFFER STATUS IS RETURNED AS THE FINAL I/O STATUS
OF THE REQUEST.
;-

AFCHK: MOV
MOV

Rl,R3
I.PRM+6(R3) ,RO

.IF DF

A$$CHK!M$$MGE

MOV
CALL
BCC
MOV
CAL LR

I. PRM+4 (R3) , Rl

;COPY ADDRESS OF I/O PACKET
;GET VIRTUAL ADDRESS OF CONTROL BUFFER

$ACHCK
10$
#IE.SPC&377 ,RO
$IOFIN

;SET LENGTH OF BUFFER TO CHECK
;ADDRESS CHECK CONTROL BUFFER
;IF CC ADDRESS OKAY
;SET ILLEGAL BUFFER STATUS
;FINISH I/O OPERATION

$RELOC
Rl,I.PRM+6(R3)
R2,I.PRM+l0(R3)
R3,Rl
R4,RO
$QINSP

;RELOCATE CONTROL BUFFER ADDRESS
;SET RELOCATION BIAS OF CONTROL BUFFER
;SET ADDRESS OF CONTROL BUFFER
;SET ADDRESS OF I/O PACKET
;SET ADDRESS OF I/O QUEUE LISTHEAD
;INSERT I/O PACKET IN REQUEST QUEUE

.ENDC
10$:

CALL
MOV
MOV
MOV
MOV
CALL

;+
**-·AFINI-AFCll ANALOG TO DIGITAL CONVERTOR CONTROLLER INITIATOR
THIS ROUTINE IS ENTERED FROM THE QUEUE I/0 DIRECTIVE WHEN AN I/O REQUEST
IS QUEUED AND AT THE END OF A PREVIOUS I/0 OPERATION TO PROPAGATE THE EXECUTION OF THE DRIVER. IF THE SPECIFIED CONTROLLER IS NOT BUSY, THEN AN ATTEMPT
IS MADE TO DEQUE THE NEXT I/O REQUEST. ELSE A RETURN TO THE CALLER IS
EXECUTED. IF THE DEQUEUE ATTEMPT IS SUCCESSFUL, THEN THE NEXT I/O OPERATION IS INITIATED. A RETURN TO THE CALLER IS THEN EXECUTED.
INPUTS:
RS=ADDRESS OF THE UCB OF THE CONTROLLER TO BE INITIATED.
OU'l~PUTS:

IF THE SPECIFIED CONTROLLER IS NOT BUSY AND AN I/O REQUEST IS WAIT
ING TO BE PROCESSED, THEN THE REQUEST IS DEQUEUED AND THE I/O OPERATION IS INITIATED.

6-9

INCLUDING A USER-WRITTEN DRIVER--TWO EXAMPLES
.ENABL
AFINI: CALL
BCS

CALL
BR

LSB
$GTPKT
AF CAN

$!ODON
AF I NI

;GET AN I/O PACKET TO PROCESS
;IF CS CONTROLLER BUSY OR NO REQUEST
;I/O CANCEL (AFCAN) IS A NO-OP FOR AFCll

~,,

;FINISH I/O OPERATION
;GO AGAIN

6-10

APPENDIX A
DEVELOPMENT OF THE ADDRESS DOUBLEWORD

A.l

INTRODUCTION

RSX-·llM can be generated as a mapped or an unmapped system.
Mapped
systems can accommodate configurations whose maximum physical memory
is 4096K bytes.
Individual tasks, however, are limited to 64K bytes.
The addressing in a mapped system is accomplished by using virtual
addresses and memory mapping hardware.
I/O transfers, however, use
phys:ical addresses 18 bits in length. Since the PDP-11 word size is
16 bits, some scheme is necessary to represent an address internally
until it is actually used in an I/O operation. The choice was made to
encode 2 words as the internal representation of a physical address,
and to transform virtual addresses for
I/O operations into the
internal doubleword format.

A.2

CREATING THE ADDRESS DOUBLEWORD

For unmapped systems, the doubleword is simply
followed by a word containing the real address.

word

zeros

On receipt of a QIO directive for mapped systems, the buffer address
in the DPB, which contains a task virtual address, is converted to
address doubleword format.
The virtual address in the DPB is structured as follows:
Bits 0-5

Displacement in terms of 32-word blocks

Bits 6-12

Block number

Bits 13-·15

Page Address Register Number (PAR#)

The internal RSX-llM translation restructures
into an address doubleword as follows:

this

virtual

address

The relocation base contained in the PAR specified by the PAR# in the
virtual address in the DPB is added to the block number in the virtual
address. The result becomes the first word of the address doubleword.
It represents the nth 32-word block in a memory viewed as a collection
of 32-word blocks. Note that at the time the address doubleword is
computed, the user issuing the QIO directive is mapped into the
processor's memory management registers.

A-1

DEVELOPMENT OF THE ADDRESS DOUBLEWORD
The second word is formed by placing the displacement in block
(bits
0-5 of virtual address)
into bits 0-5.
The block number field was
accommodated in the first word and bits 6-12 are cleared.
Finally,
a
6 is placed in bits 13-15 to enable use of PAR #6, which the Executive
uses to service I/O for program transfer devices.
For non-processor request (NPR) devices, the driver requirements for
manipulating the address doubleword are direct and are discussed with
the description of U.BUF in Section 4.1.4.1.

A-2

APPENDIX B
PDP-11/70 DRIVERS FOR NPR DEVICES

Special features must be built into drivers for non-MASSBUS NPR
(non-processor
request)
devices
attached to a PDP-11/70 with
extended-memory support (22-bit addressing).
Non-MASSBUS NPR devices on the 11/70 must perform I/O transfers via
UNIBUS
Mapping Registers (UMRs) as described in the PDP-11/70
Processor Handbook. One UMR is required for each 4K words involved in
the transfer--as specified by the contents of U.CNT in the UCB. When
multiple UMRs are required for a transfer, they must be contiguous.
These

A driver can be assigned UMRs through one of three procedures.
procedures involve:
1.

Dynamically allocating UMRs for
transfer, or

the

duration

the

data

Dynamically allocating UMRs for longer periods of time, or

Statically allocating UMRs during system generation.
NOTE
In large systems, use of the second and
third procedures above to hold UMRs for
longer periods than necessary can result
in the blocking of other drivers and a
reduction in system throughput.

B.l

CALLING $STMAP AND $MPUBM OR $STMP1 AND $MPUB1

To obtain UMRs through use of the $STMAP
$MPUB1 routines, a driver must:

Th,~se

and

$MPUBM

$STMP1

and

If it uses $STMAP and $MPUBM or $STMP1 and $MPUB1, allocate 6
additional words for a mapping register assignment block at
the end of the device's SCB (at S.MPR). If it uses $STMP1
and $MPUB1, also provide a 10-word block.

Call the routine $STMAP or $STMP1 (Set
Address) after getting the I/O packet.

Call the routine $MPUBM or $MPUB1
before initiating a transfer.

UNIBUS

(Map

UNIBUS
to

Mapping
Memory)

requirements are detailed in the following three subsections.

B-1

May 1979

PDP-11/70 DRIVERS FOR NPR DEVICES

Note that these routines are
performing a data transfer.

B.1.1

only

required

when

the

driver

Allocating a Mapping Register Assignment Block

The status control block (SCB) of an NPR device requires an additional
6 words. This 6-word mapping register assignment block is located at
S.MPR, at the end of the SCB.
It does riot have to be initialized.
Any initial contents are simply overwritten.
The following example shows the allocation of a mapping register
assignment block.
The code is conditionalized on the AND of the two
symbols M$$EXT and M$$MGE (representing extended-memory support and
memory-management unit support, respectively).
.IF DF
.BLKW
.ENDC

M$ $EXT&:M$ $MGE
6
;UMR WORK AREA

If the driver does not support parallel NPR operations reauiring UMR
mapping,
it calls $STMAP and $MPUBM.
If the driver supports parallel
NPR operations requiring UMR mapping, it must call $STMP1 and $MPUB1.
In the latter situation, the six additional words starting at S.MPR in
the SCB are not used but must still be present.
In addition,
the
driver must provide a 10-word mapping register assignment block for
each data transfer to be mapped as specified in the description of
$STMP1 in Chapter 5.

B.1.2

Calling $STMAP or STMPl

In the coding at the initiator entry point, after the call to $GTPKT,
the NPR-device driver must call the routine $STMAP or $STMP1. These
routines dynamically allocate required UMRs.
If UMRs are
not
available immediately,
the driver is blocked.
Such blocking, if it
occurs, is completely transparent to the driver.
The driver resumes
processing at fork
level when the UMRs have been allocated.
The
register returns are absolutely identical whether or not blocking has
occurred.
$STMAP or $STMP1 stores into U.BUF and U.BUF+2 (in the UCB)
a UNIBUS
address that causes the appropriate UMR to be selected for mapping the
transfer.
The call to $STMAP or $STMP1 must be conditionalized on
M$$EXT&M$$MGE.
Because $STMAP and $STMP1 push the address of routine $DOUMR+2 on to
the stack before returning to the caller, the driver should not use
the stack for temporary data storage when it calls $STMAP or $STMP1.

B.1.3

Calling $MPUBM or $MPUB1

Before executing the transfer, the driver must call $MPUBM or $MPUB1.
These routines get the buffer's 22-bit physical address, and load the
UNIBUS mapping registers so that transfers are mapped directly to the
task's space. The call to $MPUBM or $MPUB1 must be conditionalized on
M$$EXT&M$$MGE.

B-2

May 1979

PDP-11/70 DRIVERS FOR NPR DEVICES

If the driver calls $STMAP and $MPUBM, the UMRs allocated to it are
deallocated during the call to $!ODON or $IOALT. If the driver calls
$STMP1 and $MPUB1, it must call $DEUMR to deallocate any allocated
UMRs before calling $!ODON or $IOALT.

B.2

I
•

CALLING $ASUMR and $DEUMR

Some drivers may not require UMRs to be allocated all of the time, and
yet irequire UMRs for periods of time longer than the normal time-frame
between $GTPKT and $!ODON (or $IOALT).
In such cases,
there is a
second procedure for allocating UMRs.

Through use of the Executive routines $ASUMR and $DEUMR, a driver can
dynamically allocate, retain over a desired time-frame, and deallocate
UMRs. Refer to Section 5.3 for a description of the $ASUMR and $DEUMR
routines.
Similar to the $STMAP/$MPUBM procedure~, the use of $ASUMR and $DEUMR
also requires the allocation of a 6-·word mapping register assignment
block.
In this instance, however, the block must not be located at
offset S.MPR in the SCB.
$!ODON or $IOALT, when called, will attempt
to deallocate the UMRs of a block found at location S.MPR.
To avoid
this, the mapping register assignment block could, for convenience, be
located at S.MPR+2o Alternatively, it could be dynamically allocated
from the pool.
Figure B-1 details thE~ format of the 6-word block.
M.LNK

Link Word

M.UMRA

Address of first assigned UM R

M.UMRN

Number of assigned UM Rs *4

M.UMVL

Low 16 bits mapped by first assigned UM R

M.UMVH
M.BFVH
M.BFVL

Figure B-1

B. 3

High 6 bits of
physical buffer address

High 2 bits mapped by
UMR (in bits 4 and 5)

Low 16 bits of physical buffer address

Mapping Register Assignment Block

STATICAI,LY ALLOCATING UMRs DURING SYSTEM GENERATION

UMRs can be statically assigned during system generation.
For systems
with extended-memory support and memory-management unit support, the
system generation procedure defines the symbol N$$UMR equal to a fixed
number of UMRs, multiplied by 4, that are statically assigned to the
system. Before assembling the Executive,
the user can cause the
static allocation of an additional number of UMRs by editing file
RSXMC.MAC. The value of the symbol N$$UMR can then be increased to
represent the additional number of desired UMRs multiplied by 4.
RSXMC.MAC further defines the following three symbols, which
the first UMR statically allocated during system generation:
U$$MRN

is the I/O page address of the first
available for allocation to the user.

B-3

UMR

describe
I

May 1979

PDP-11/70 DRIVERS P'OR RPR DEVICES

U$$MLO

represents the low-order 16 bits of the
address mapped by this UMR.

U$$MHI

represents the high-order 2 bits of the 18-bit UNIBUS
address. These 2 bits are in bit positions 4 and 5.

These three symbols are not used by the
available for the user's information.

system

18-bit

itself.

UNIBUS

They

are

"""·

: I

B-4

May 1979

APPENDIX C
SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

.lIY NDF

SSS~DF

, .NLIST

COPYRIGHT CC) 1974.1976,1977
DIGITAL EUUlPMENT CURPORATION, MAYNARD, MASS.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE FUH USE UNLt UN A
SINGLE COMPUTER SYSTEM AND MAY BE COPIEU
ONLY WITH THE
INCLUSION UF THE ABOVE COPYRIGHT ~OTICE. THIS SUfTWARE, OR
ANY OTrlER COPIES 1HEREOF, MAY ~OT BE PROVIDED OR OTHER~lSE
MADE AVAILABLE TU AhY OTHER PERSUN
EXCEPT FOR USE UN SUCH
SYSTEM AND 10 ONl hHO AGREES TO THESE LICENSE IERMS. T1TLE
TU AND OWNEHSHIP OV THE SOFTWARE SHALL AT ALL TIMES REMAIN
IN UEC.
THE INYORMA1ION IN THIS DOCUMENT IS SUBJECT ro CHANGE WITHOUT
NOTICE AND SHOULD ~OT BE CONSTRUED AS A COMMITMENT tiY DIGITAL
EQUIPMENT CURPOFATlON.
DEC ASSUM~S NU RESPONSIBILITY fUR THE USE UR RELIABILltY OF
ITS SOFTWARE ON EOUIPMENT WHlCH IS NUT SUPPLI~D BY DEC •
• MACk8

A80Df$,L,8

;+
; TASK ABORT CODES
;

NOT~:

S.COAD•S.CFLT ARE ALSO SST VECTOR OFFSETS

S.COAD='B'O.
S .CSGf': 'B' 2.
S.CBPT='B'4.
S.CIOT='B'b.
S.CILI='B'8.
S.CEMT:'B'lO.

S.CTRP='B'12.
S.CFLT:'B'14.
S.CSST='B'16.

S.CAST='B'18.
S.CABO:'B'20.
S.CLRF='B'22.
S.CCRF='B'24.
S.IOMG:'B'26.

S.PR1'Y:'B'28.
TASK

T~HMihATIO~

;ODD ADDRESS AND TRAPS TU 4
; SEGM'ENT f'AULT
;BREAK POINT OR TRACE TRAP
; IDT INSTRUCTION
;ILLEGAL OR RESERVEU INSTRUCTlON
;NON RSX EMT INSTRUCTION
;TRAP l~STRUCTIUN
:11/40 FLOATING PdINT EXC~PTION
;SST ABORT•BAD STACK
:AST AdURT"BAu STACK
:ABORT VIA DIRECTIVE
;TASK LUAU REQUEST FAILURE
;TASK CHECKPOI~T READ FAILURE
;TASK ~XlT WITH OUTSTANDlNG 1/0
;TASK MEMUR~ PARITY ERROR
NOTIFICATIUN MESSAGE CODES

C-1

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
T.f'lDtvR='B'O
T.NDSE='B'2
T.NCwF='B'4
T.NCRE='B'6
T.NDMO='i::i'8.
T.NLL>N='B'12.
T.NLUP='B'14.

.MACHO

NUT R~AO~
SELECT ~RROR
:CHECKPUINt ~RITE FAILURE
:CARD READt.R HARDWAR~ ERRUR
:DISMUUNT COMPLETE
;LINK DOwN (N~T~ORKS)
;LINK UP (NETWORKS)
:DEVIC~

:VEVIC~

AbU~FS

X,I

.END~

.t.NDM

.1IF ~VF SSSYDF • .LIST

C-2

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
.Ilf NUf

SS$~0f

, .NLIST

COPYRIGHT CC) 1974,1976,1977
DIGITAL EUUIPMENT CURPUHATIUN, MAYNARD, MASS.
fHIS SOFTWARE lS YU~NISHEU UhDEN A LICENSE FUR USE ONLY UN A
SINGLE COMPUTE~ SYSTE.M AND MAY 8E COPIED
ONLk WlTH THE
INCLUSION UF ThE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR
ANY OTHER COPilS THE.~EOF, MAY NOT BE PROVIDED OR UTHEHWISE
MADE AVAILABLE TO ANY OTHEH PERSON
EXCEPT FOR USE ON SUCH
SYSTEM AND TO ONl wHO AGREES TO THESE LICENSE TERMS. TITLE
TO AND OWN~R&HlP Uf THE SOFTWARE SHALL AT ALL TIMES REMAIN
IN DEC.
THE INFORMATION lh THIS DOCUMENT IS SUBJECT TU CHANGE WITHOUT
NOTICE AND SHOULD NOT BE CONSTMUEU AS A COMMI1MENT BY DIGITAL
EUUIPMENT COHPORATl~N.
DEC ASSUMES NO RESPO~SIBILITY FOR THE USE UR RELIABILITY OF
Its SOFTWARE ON EOUIPMENT WHICH IS NOT SUPPLIED BY DEC •
• MACRU

CLKDFS,L,B

CJUOCK QUEUE CON1'ROL BLOCK Uli'FSET DEli"lN IT IONS
CLOCK QUEUE

CO~TRUL

BLOCK

THERE ARE FIVE TYPES OF CLOCK OUEUE CONTROL BLOCKS. EACH CONTROL BLOCK HAS
THE SAME FORMAT IN THE FIRST FIVE WORDS AND DIFFERS IN THE REMAINING THREE.

THE FOLLO~ING CONTROL BLOCK TYPES ARE OEFlNEU:
;MARK TIME REQUEST
;TASK REQUEST WITH PERIODIC RESCHEDULING
:SINGLE SHUT TASK REOUEST
;SINGL~ SHOT INTERNAL SYSTEM SUBROUTINE ClDENTJ
;SINGLE SHOT INTERNAL SYSTEM SUBROUTINE CTASK)
;CLEAR STOP BlT CCONDITlONALIZED ON SHUFFLING)

C.M.RKT='B'O
C.SCHD='B'2
C.SSHT='B'4
C.SYST='B'6
C.SYTK='B'8.
C.CSTP='B'lO.

; CLOCK QUEUE CONTROL BLOCK TYPE INDEPENDENT OFFSET DEFINTIONS

.._,.,

.ASECT
.=o
C.LNK:'L' .BLKW
C • .RQT: 'L' .BLKB
C. EFN: 'L' .BLKB
c. ·res:' L • .BLKW
C.TIM:'L' .BLKW

1
1
1

1
2

-;CLOCK QUEUE THREAD WURD
;REQUEST TYPE
:EVENT FLAG NUMB~R (MARK TIME ONLY)
;TCB ADDRESS OR SYSTEM SUBROUTINE IDENTIFICATION
;ABSOLUTE TIME WriEN REQUEST COMES DUE

,
; CLOCK QUEUE CONTROL BLOCK•MARK TIME DEPENDENT UFfSET DEFINITIONS
• =C:. TIM+4
C.AST:'L' .BLKW 1
C.SRC:'L' .BLkW 1
C.DST:'L' .BLKW 1

;START OF D~PENDENT AREA
;AST ADDRESS
;FLAG MASK WURD FOR 'BIS' SOUkCE
;ADDRESS OF 'BIS' DESTINATION

,
; CLOCK QUEUE CONTROL BLOCK-PERIODIC RESCHEDULING DEPENDENT OFFSET DEFINITIONS
.=C.TIM+4
C.RSI:'L' .BLKW 2
C.UIC:'L' ~BLKW 1

;START O~ DEPENDENT AREA
;RESCHEDULE IN1ERVAL IN CLOCK.TICKS
;SCHEDULING UlC

CLOCK QUEUE CONTROL BLOCK-SINGLE SHOT DEPENDENT OFFSET DEFlhITIONS

C-·3

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
.=C.'flM+4
.BLKW

.HLKW

;START OF DEPENDENT AREA
;TwU UNUSED WURDS
; SCHrnULING UIC

CLUCK QUEUE CONTROL HLOCK•SINGLE SHOT INTERNAL SUBROUTl~E OFFSET DEFINITIONS
THERE ARE TWO TYPE CODES FUR THIS
TYP~
TYP~

b=SINGLE SHOT
S=SINGLE SHOT

INT~RNAL
lNTER~AL

OF REOUEST:'L'

SUHROUflN~
SUBROUTINI~

WITH A 16 BLT VALUE AS AN IDENTIFIER.
WITH A TCB ADDRESS AS AN IDENTIFIER.

STAHT OF DEPENDE~T AREA
SUBHUUTINE ADDRESS
RELOCATION BASE CFOR LOADABLE DRIVERS)
LINE UNUSED WORL)
LENGTH UF CLUCK UUEUE CONTROL BLOCK

.=C.TIM+4
C.SUB: •L• .BLKl'I
C.AR~: •L• .BLKW
.BLl\w
C.LGTH=•B• •
• PS~CT
.MACHU

TYP~

CLKDl'S

X,Y

.ENDl'-1
.t:NOM

.llf NDF S$SYUF

.LIST

C-4

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
.IIF

NDf 5SSYOF , .NLIST

COPYRIGHT CC) 1974,1976,1977
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOH USE ONLY UN A
SINGLE COMPUTER SYSTEM AND ~AY BE COPIED
ONLY WITH THE
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOYTWAR~, OR
ANY OTHER CO~IES THEREOF, MAY NOT BE PROVIDED OR UTHEkWISE
MADE AVAlLAHLE TO ANY OTHER PERSON
EXCEPT FOR USE ON SUCH
SYSTEM AND TO ONE WHO AGREES TU THESE LICENSE TERMS. TITLE
TO AND OWNERSHIP Of THE SOFTWARE SHALL AT ALL TIMES REMAIN
IN DEC.
THE INFORMATION lN THIS DOCUMENT IS SUHJECT TO CHANGE WITHOUT
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL
EQUIPMENT CORPORATION.
DEC ASSUMES ~O RESPONSIBILITY FOR THE USE OR RELIABILITY OF
ITS SOYT~AME UN EQUIPMENT WHICH IS NOT SUPPLIED Br DEC •
• MACRO

DCBDF$,L,B

:+
DEVICE CONTROL BLOCK
THE DEVICE CONTROL BLOCK CDC8) DEFINES GENERIC INFORMATION ABOUT A DEVICE
TIPE AND THE LOWlST AND HIGHEST UNIT NUMBERS. THERE IS AT LEAST ONE DCB
FOR EACH DEVICE TYPE IN A SYSTEM. FOR EXAMPLE, IF THERE ARE TELETYPES IN A
srsTEM, THEN THERE IS AT LEAST ONE DCB WITH THE DEVICE NAME 'TT'. If PART
OF THE TELETYPES WERE INTERFACED VIA DLll•A'S AND THE REST VIA A DH11, THEN
THERE WOULD BE TWO DCB'S. ONE FOR ALL DLll•A INTERFACED TELETYPES, AND ONE
FOR ALL DHll lNTlRFACED TELETYPES.

:.ASEC1'
.=o
D.LNK:'L' .BLK~ 1
D.UCB:'L' .BLKW 1
D.NAM:'L' .BLKW 1
D.UNIT:'L' .BLKB 1
.BLKB
1
D.UCBL:'L' .BI,KW 1
D.DSP:'L' .BLKW 1
D.MSK:'L' .BLKW 1
• BLKV.
1
• BLK~
1
• BLKW
1
• BLKri
1
• BLKW
1
• BLKW
1
• BLKW
1
D.P'CB: 'L' .BLKW 1

;LINK TO NEXT DCB
;POINTER TO FIRST UNIT CONTROL BLOCK
;GENERIC DEVICE NAME
:LOWEST UNIT NUMBER COVERED BY THIS DCB
;HIGHEST UNIT NUMBER COVERED BY THIS DCB
;LENGTH OF EACH UNIT CONTROL BLOCK IN BYTES
;POINTER TO DRIVER DISPATCH TABLE
;LEGAL FUNCTION MASK CODES 0•15.
;CONTROL FU~CTION MASK CODES o-1s •
;NOP'ED FUNCTION MASK CODES 0•15 •
;ACP FUNCTION MASK CODES 0•15 •
;LEGAL fUNCTION MASK CODES lb.•31 •
;CONTROL FUNCTION MASK CODES 16.•31 •
;NOP'ED FUNCTION MASK CODES lb.•31 •
;ACP FUNCTION MASK CODES 16.-31 •
:LOADABLE DRIVER PCB ADDHESS

.PSECT
;+
; DRIV~R DISPATCH TAHLE OFFSET DEFINITIONS

::DEVICE INITIATOR
;CANCEL CURRENT l/U FUNCTION
;DEVICE TIMEOUT
;POWEHFAIL RECOVERY

D.VINI='B'O
D.VCAN='B'2
D.VOUT='B'4
D.VPWF='B'o
.MACRO
.ENDM
.ENDfw'

DCl:H>f$,X,Y

.UF

NDF S$$YDF

.LIST

C-5

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
• !IF

• TITLE
.!DENT

NDF,SS$YDF,.NLIST
FllTBL FILES 11 TABLE DEFINITIONS
/0022/

1976,

DIGITAL

EQUIPMENT

CORP.,

MAYNARD,

MASS.

THIS SOFTWARE IS FURNISHED TO PURCHASER UND~R A LICENSE FOR USE
ON A SINGLE COMPUTER SYSTEM AND CAN BE COP[ED (WITH INCLUSION
OF DEC'S COPYRIGHT NOTICE) ONLY FOR us~ IN SUCH SYSTEM, EXCEPT
AS MAY OTHERWISE BE PROVIDED IN WRITING SY DEC.
THE INFORMATION I~ THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL
EQUIPMENT CORPORATION.
DEC ASSUM~S NO RESPONSIBILITY FOR
OF ITS SOFTWARE ON EQUIPMENT WHICH

THE USE OR RELIABILITY
IS NOT SUPPLIED BY DEC.

t;LLEN R SIMICH l6•JUN•76 3•MAR•77 11M LOCK CHANGE
ANDREW C. GOLDSTEIN 30 OCT 75 17:55
PETER H. LIPMAN 12/27/73
.MACRO

F11Df$

VOLUME CONTROL BLOCK
.ASECT
.=o
V.TRCT: .BLKW
V.IFWI: .BLK~
.ff

V.STD:

.BLKW
.ENOC
V.FCB: .BLKW
V.IBLB: .BLKB
V.IBSZ: .BLKB
.BLKW
V.FMAX: .BLKW
v.wisz: .BLKB
.BLKB
.BLKW
.BLKB
.BLKB
.BLKW
.IF
V.VOWN: .BLKW
V.VPRO: .BLKW
V.VCHA: .BLKW

V.SBCL:
V.SBSZ:
V.SBLB:
V.1'.IEX:

1
1

;TRANSACTION COUNT
;INDEX FILE WINDOW

OF ,R$$11D
1

;STD OF TASK CHARGED WITH NODE

;FILE CONTROL BLOCK LIST HEAD
;INDEX BIT MAP 1ST LBN HIGH BYTE
;INDEX BIT MAP SIZE IN BLOCKS
;INDEX BITMAP lST LBN LOW BITS
;MAX NO. OF FILES ON VOLUME
;DFLT SIZE OF WINDOW IN NO. OF RTRV PTRS
;VALUE IS < 1~?8.
;STORAGE BIT MAP CLUSTER FACTOR
;STORAGE BIT MAP SIZE IN BLOCKS
;STORAGE BIT MAP lST LBN HIGH BYTE
;DEFAULT FILE EXTEND SIZE
;STORAGE BIT MAP lST LBN LOW BITS

1
l
1
1
1
1
1
1
l

1
DF ,R$$11M

1
1
1

;VOLUME OWVER•s UIC
;VOLUME PROTECTION
;VOLUME CHARACTERISTICS

• IFTF'

V.FPRO: .BLKW
.IfT
V.VFSQ: .BLKw
.Iff
.BLKW
.ENDC
V.FRBK: .BLKB
V.LRUC: .BLKB
.BLKW
• If'

;VOLUME DEFAULT FILE PROTECTION
;VOLUME FILE SEQUENCE NUMBER
;NOT USED
1

1
l
DF,R$$11D

V.LABL: .BLKB
12.
.ENDC
V.STAT: .BLKB
1
VC.IFw= 1
VC.BMw: 2
V.FFNU: .BLKB
1
V.LGTH:
;

;NUMBER OF FREE BLOCKS ON VOLUME HIGH BYTE
;COUNT OF AVAILABLE LRU SLOTS IN FCB LIST
;NUMBER OF FREE BLOCKS ON VOLUME LOW BITS
;VOLUME LABEL CASCII)
;VOLUME STATUS BYTE, CONTAINING THE FOLLOWING
; INDEX FILE IS WRITE ACCESSED
; STORAGE BITMAP FILE IS WRITE ACCESSED
; FIRST FREE INDEX FILE BITMAP BLOCK
;SIZE IN BYTES OF VCB

l'ILE CUN THUL BLUCK

.ASECT
.=o
F.LlNK: .BLKw
.IF
F.FEXT: .BLKW
1'•• STD:
.BLKW
.ENDC

Dl',f?SS110
1
1

;FCb CHAIN

POI~TEH

:POINTER TO EXTENSION FCB
;STD UF TASK CHARGED WITH ~ODE

C-6

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
feFNUM: .BLKW
F.FSEQ: .BLKW
.8LKB
F.F5QN: .BLKB
F.FOWN: .BLKW
f.FPRO: .BLKW
F.UCHA: .BLKB
f.". SC HA: • BLKB
F.HDLB: .BLKW
F.LBN:

.BLKw

1
1
1
1
1

1
1
1

F.SIZE: .BLKW
2
F.NACS: .BLKB
1
F.NLCK: .BLKB.
1
S.STBK=.-F.Lt:lt-i
F. N~'AC:

F.DREF:
F. DRNM:

F.FEXT:
F.FVBN:
F.LKL:
F.LGTH:

• BLKB
.BLKB
1
FC.WAC=lOOOOO
FC. DIR=40000
FC.CEF=20000
F·c. FCO=l 0000
.BLKW
1
• BLKW
1
.lF
Df,RSS11M
.BLKw
1
.ENDC
.BLKW
2
.BLKW
1

:fILE NUMBl::R
:FILE SEQUENCE NUMB~R
;NOT USED
;FILE SEGMENT NUMBER
;FIL~ OwNER'S UIC
:FILE P~OTECTION CODE
;USER CONTROLLED CHARACTERISTICS
;SYSTEM CONTKOLLED CHARACTERISTICS
:FILE HEADER LUGICAL BLOCK NUMBER
:BEGINNING ur STATISTICS BLOCK
;LBN OF VIRTUAL BLUCK 1 IF CONTIGUOUS
;O IF NON CONTIGUOUS
;SIZE OF FILE IN BLOCKS
;NO. Of ACCESSES
;NO. OF LOCKS
;SIZE OF STATICS BLOCK
;FCB STATUS WORD
;NUMBER OF wRITE ACCESSORS
:STATUS BITS FOR FCB CONSISTING OF
;SET IF FILE ACCESSED FOR WRITE
;SET IF FCB IS IN DIRECTORY LRU
;SET IF DIHECTORY EDF NEEDS UPDATING
;SET IF TRYING TO FORCE DIHECTORY CONTIG
;OIR~CTORY EDF BLOCK NUMBER
;1S1 WORD OF DIRECTORY NAME
;POINTER TO EXTENSION FCB
;STARTING VBN OF THIS FILE SEGMENT
;POINTER TO LOCKED BLOCK LIST FOR FILE
;SIZE IN BYTES OF FCB

; w:tNDUW

.=o

w.crL:

.ASECT

.BL.KW
WI.RDV=400
wI.WRV=lOOO
WI .EX1'=2000
WI.LCK=4000
Wl.DLK=lOOOO
WI .EXl,:40000

wI.BPs=tooooo

W.VBN:

w.w1sz:

W.FCB:
W.FCB:
W.STD:
W. VBN:

w.wisz:
W. L1KL:

.IF
.BLKB
.BLKB
.BLKW
.BLKW
.ENDC

DF,RSS11M
1

• IE'

DF,RSS11D

.BLKW
.BLKW
• BLKB
.BLKB
.BLKW
.ENDC
.BLKW

1
1

1
1
1

1
1

JLOW BYTE
# OF MAP ENTRIES ACTIVE
;HIGH BYTE CONSISTS OF THE FOLLOWING BITS
;READ VIRTUAL BLOCK ALLOWED IF SET
;wRITE VIRTUAL BLOCK ALLOWED IF SET
;EXTEND ALLOWED IF SET
;SET IF LOCKED AGAINST SHARED ACCESS
;SET IF DEACCESS LOCK ENABLED
;SET IF MANUAL UNLOCK DESIRED
;BYPASS ACCESS INTERLOCK IF SET
;HIGH BYTE Of lST VBN MAPPED BY WINDOW
;SIZE IN HTRV PTRS OF WINDOW (7 BITS)
;LOW ORDER WORD OF lST VBN MAPPED
;FILE CONTROL BLOCK ADDRESS
;FILE CONTROL BLOCK ADDRESS
;STD OF TASK CHARGED ~ITH WIDOW NODE
;HIGH BYTE OF lST VBN MAPPED BY WINDOW
;SIZE IN RTRV PTRS OF WINDOW (7 BITS)
;LOW ORDER WORD OF lST VBN MAPPED
;POINTER TO LIST OF USERS LOCKED BLOCKS
;OFFS~T TO lST RETRIEVAL POINTER IN WINDOW

W.FtTRV:
: LOCKED BLOCK LIST NUDE
• ASEC'f
.L.1'NK: .Bl1KW
:()

L.~wll:

L.STD
L.'181

L.1182
L·.CN'X'

.BLKW
.H·
• BliKW
.BLKri
• Bl,KW
.BLKB
• Bl, KB
.lFF

DF,RSS11D
1
2

2
1

;LINK TU NEXT NODE IN LIST
;POINTER TO WINDOW FOR FIRST

~NTRY

POINTER TO STD Of TASK NODE CHARGED TO
STARTING VBN OF FIRST ENTRY
STARTING VBN Of SECOND ENTRY
COUNT fOR FIRST ENTRY
COUNT fOR SECOND ENTRY

C-7

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
L. VBl:

.BLKB

L.CNT:

.BLKB
.BL~l'I

1
1
1

;HIGH ORDER VBN BYTE
;COUNT FOR ENTRY

L.LGTH:

.ENDM

F11DFS
F11Df'$
F'l 10t'S

.Ili'"

NDf,SSSYDF,.LIST

.I::NDM

I I ~'

.~NOC

• PSEC1'
.MACRO

C-8

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
.IlF NDF S$$YDf , .NLIST
COPYRIGHT CC) 1974,1976,1977
DIGITAL ~QUIPMENT CORPORATION, MAYNARD, MASS.
THIS SOFTWAHE IS FURNISHED UNDER A LICENS~ FOR USE ONLY ON A
SINGLE COMPUTER SYSTEM AND ~Ar BE COPIED
ONLY WITH THE
I INCLUSION OF THE· ABOVE COPYRIGHT NOTICE.
THIS SOFTWARE, OR
ANr OTHER COPIES THEREOF, MAY NOT BE PNUVIDED OR OTHERWISE
~ MADE AVAILABLE TO ANY OTHER PERSON
EXCEPT FOR USE ON SUCH
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN
IN DEC.
THE INFORMATION IN THIS DOCUMENT lS SUBJECT TO CHANGE WITHOUT
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL
EQUIPMENT CORPORATION.
DEC: ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF
ITS SOFTWARE UN EQUIPMENT WhICH IS NOT SUPPLIED BY DEC •
• MACRO

HDRDFS,L,B

;+
: TASK HEADER OFfSET DEFINITIONS
;-

.=o

.ASECT

H.CSP:'L'.BLKW 1
H.HDLN:'L'.BLKW 1
H.EFLM:'L'.BLKW 2
H.CUIC:'L'.BLKW 1
H.DUIC:'L'.BLKW 1
H.IPS: 'I,' .BLKw 1
H. IPC:: 'L' • BLKW 1
H.ISP: 'L' .BLKw 1
H.ODVA• 'L' .BLKW 1
H.ODVL 'L'.HLKW 1
H.TKVA 'L'.BLKW 1
H.TKVL 'L'.HLKW 1
H.PFVA 'L'.BLKW 1
H.FJ:>VA 'L' .BLKW 1
H.RCVA 'L' .BLKW 1
H.EFSV 'L'.BLKw 1
H.FPSA 'L'.BI,KW 1
H.WND: L'.BLKW 1
H.osw: 'L' .BLKW 1
H.FCS: 'L' .BLKW 1
H.FOHT: 'L' .BJ,KW 1
H.OVJ,Y: 'L' .BLKW 1
H. VEXT: 'L' .BLKW 1
H.SPHI:'L'.BLKB 1
H.NMl.i: 'L' .BLKB 1
H.RRVA: 'L' .BLKW 1
.BLKW
3
H.GAIRD: 'L' .BLKW 1
H.NLllJN: 'L' .BLKW 1
H.LUIN: 'LI .BLKW 2

;CURRENT STACK POINTER
;HEADER LENGTH IN B~TES
:EVENT FLAG MASK ~ORO AND ADDRESS
;CURRENT TASK UIC
;DEFAULT TASK UIC
;INITIAL PROCESSOR STATUS WORD CPS)
;INITIAL PROGRAM COUNTER (PC)
;INITIAL STACK POINTER CSP)
;ODT SST VECTOR ADDRESS
;ODT SST VECTOR LENGTH
;TASK SST VECTOR ADDRESS
;TASK SST VECTOR LENGTH
;POWER FAIL AST CONTROL BLOCK ADDRESS
;FLOATING POINT AST CONTROL BLOCK ADDRESS
;RECIEVE AST CONTROL BLOCK ADDRESS
;EVENT FLAG ADDRESS SAVE ADDRESS
;POINTER TO FLOATING POINT/EAE SAVE AREA
;POINTER TO NUMBER OF WINDOW BLOCKS
;TASK DIRECTIVE STATUS wORD
;FCS IMPURE POINTER
;FORTRAN IMPURE POINTER
;OVERLAY IMPURE POINTER
;WORK AREA EXTENSION VECTOR POINTER
;PRIORITY DIFFERENCE FOR SWAPPING
;NETWORK MAILBOX LUN
;RECEIVE BY REFERENCE AST CONTROL BLOCK ADDRESS
;RESERVED WORDS
;POINTER TO HEADER GUARD WORD
;NUMBER OF LUN'S
;START OF LOGICAL UNIT TABLE

;+
; WINDOW BLOCK OFFSETS
;-

.=o

w.BPCB:'L'.BLKW 1
W.BLVR:'L'.BLKW 1
W.BHVR:'L'.BLKW 1
W.BATT:'L'.BLKW 1
W.BSIZ:'L'.BLKW 1
w.sorF:'L'.BLKW 1
~.BFPD:'L'.BLKB 1
W.BNPD:'L'.BLKB 1

;PARTITION CONTROL BLOCK ADDRESS
;LOW VIRTUAL ADDRESS LIMIT
;HIGH VIRTUAL ADDRESS LIMIT
;ADDRESS OF ATTACHMENT DESCRIPTOR
;SIZE OF WINDOW IN 32W BLOCKS
;PHYSICAL M~MORY OFFSET IN 32W BLOCKS
;FIRST PDR ADDRESS
;NUMBER Of PDR'S TU MAP

C-9

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIOlfS
w.BLPD:"L'.BLKW 1

;CONTENTS Of LAST PDR
;LENGTH OF ~INDOW DESCRIPTOR

w.BLGH: • L'

.PS~CT

.MACRU
.l!:NDM
.Et.OM

HDRDF$

X,~

.Ilf NDF S$SYDF , .LIST

C-10

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
.IIF NDF SSSYDF , .NLIST
COPYRIGHT CC) 1974,1976,1977
; DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A
SINGLE COMPUTER SYSTEM AND MAY BE COPIED
ONLY 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
EXCEPT FOR USE ON SUCH
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE
TO ANO OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN
1 IN DEC.
THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL
EQUIPMENT CORPORATION.
DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF
ITS SOFTWARE ON EOUIPMENT WHICH IS NOT SUPPLIED BY DEC •
• MACRO HWDDf$,L,B
1+

; HARDWARE REGISTER AODRESSES AND STATUS CODES
1-

;ADDRESS OF PDP•ll/70 MEMORY PAkITY REGISTER
;ADDRESS OF FIRST MEMORY PARITY REGISTER
;PROGRAMMED INTERRUPT REQUEST REGISTER
;PROCESSOR PRIORITY 0
;PROCESSOR PRIORITY 1
;PROCESSOR PRIORITY 4
;PROCESSOR PRIORITY 5
;PROCESSOR PRIORITY 6
;PROCESSOR PRIORITY 7
;PROCESSOR STATUS WORD
;CONSOLE SWITCH AND DISPLA~ REGISTER
;CONSOLE TERMINAL PRINTER STATUS REGISTER

MPCS.R=•B' 177746
MPAR=•a'172100
PIRo=·s· 111112
PRo=•s•o
PR1:•5•40
PR4='B'200
PR5:'8'240
PR6='B'300
PR7='B'340
PS='B.177776
SWR=•s•177570
TPs=•s•117564

;+
; EXTENDED ARITHMETIC ELEMENT R~GISTERS
:.IF DF

ESSEAE
:ACCUMULATOR
;MULTIPLIER•QUOTIENT
;SHIFT COUNT

Ac=•s•111302
MQ:'B'177304
sc=•s•111310
.ENDC

;+
; MEMORY MANAGEMENT HARDWARE REGISTERS AND STATUS CODES
;.IF OF
KDSARo=•a•172360
KDSDRo=·B'172320
KISARO=•s•172340
KlSAR5='B•172352
KISAR6:•s•172354
KISAR1=·a•1723s6
KISDRO='B•172300
KISDR6=~a•172314

KISDR7='~'172316

SISDRO:'s•t72200
UDSARo=·s·111660
UDSDRO:•s•111020
UISARO='s•177640
UISA~4=•s•111650

UISARs=•s•117652

MSS,.,GE

;KERNEL D PAR 0
;KERNEL D PDR 0
;KERNEL I PAR 0
;KERNEL l PAR 5
;KERNEL I PAR 6
;KERNEL I PAR 7
;KERNEL I PDR 0
;KERNEL I PDR 6
;KERNEL I PAR 7
;SUPERVISOR I POR 0
;USER D PAR 0
;USER D PDR 0
;USER I PAR 0
;USER I PAR 4
;USER I PAR 5

C-11

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
UISAR6=•B 1 177654
UISAR7=•s•117656
UISDRO=•s•117600
UISOR4:•s•117b10
UISDRS:'B'177b12
UISDR6:'B'177614
UISDR7:'B'177616
UBMPR:'B'170200
CMODE='B'140000
PMODE='B'30000
SRO:'B'177572
SR3=•s•112s16

;USER I PAR 6
:USER I PAR 7
;USER I PDR 0
;USER I PDR 4
;USER I PDR 5
;USER I PDR 6
;USER I PDR 7
JUNIBUS MAPPING REGISTER 0
rCURRENT MODE FIELD OF PS WORD
;PREVIOUS MODE FIELD OF PS WORD
;SEGMENT STATUS REGISTER 0
;SEGMENT STATUS REGISTER 3

.ENDC

;+
; FEATURE SYMBOL DEFINITIONS
;FE.EXT='B'l
FE.MUP='B'2
FE.EXV='B'4
FE.DRV='B'lO
FE.PLA='B'20
FE.CAL='B'40
FE.PKT='B'lOO
FE.EXP=•B 200
FE.LSI:•s 1 400
FE.CEX='B'20000
FE.MXT='B'40000
FE.NLG='B'lOOOOO

;11170 EXTENDED MEMORY SUPPORT
;MULTI-USER PROTECTION SUPPORT
;EXECUTIVE IS SUPPORTED TO 20K
;LOADABLE DRIVER SUPPORT
;PLAS SUPPORT
;DYNAMIC CHECKPOINT SPACE ALLOCATION
;PREALLOCATION OF l/O PACKETS
;EXTEND TASK DIRECTIVE SUPPORTED
;PROCESSOR IS AN LSI-11
;COM EXEC IS LOADED
;MCR EXIT AFTER EACH COMMAND MODE
;LOGINS DISABLED - MULTI-USER SUPPORT

.MACRO
.ENDM
.ENDM

HWDDFS

X,~

.IIF NOF SSSYDF , .LIST

C-12

~·.

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
.llF

NDF S$$YDf , .NLIST

COPYRIGHT CC) 1974,1976,1977
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONL1 ON A
SINGLE COMPUTER SYSTEM AND MAY BE COPIED
ONLY 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
EXCEPT FOR USE ON SUCH
SYSTEM AND TO ONE ~HO AGR~ES TO THESE LICENSE TERMS. TITLE
TO AND OWNERSHIP OF ThE SOFTWARE SHALL AT ALL TIMES REMAIN
IN DEC.
THE: INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL
EQUIPMENT CORPORATION.
DEC: ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF
ITS SOFTWARE ON ~QUlPMENT WHICH IS NOT SUPPLIED BY DEC •
• MACRO

LCBDF$,L,B

;+
LOGICAL ASSIGNMENT CONTROL BLOCK
THE LOGICAL ASSIGNMENT CONTROL BLOCK (LCB) IS USED TO ASSOCIATE A
LOGICAL NAME WITH A PHYSICAL DEVICE UNIT. LCB'S ARE LINKED TOGETHER
TO FORM THE LOGICAL ASSIGNMENTS OF A SYSTEM. ASSIGNMENTS MAY BE ON
A SYSTEM WIDE OR LOCAL (TERMINAL) BASIS.
;-

.=O

.ASECT

L.LNK: 'L' .BLKW
L.NAM:•L' .BLKW 1
L.UNlT:•L' .BLKB 1
L~TYPE:•L• .BLKB 1
L.UCB:'L' .BLKW 1
L.ASG:'L' .BLKW 1
L.LG!H=•B'.•L.LNK
.PSECT

:LINK TO NEXT LCB
;LOGICAL NAME OF DEVICE
;LOGICAL UNIT NUMBER
;TYPE OF ENTRY CO=SYSTEM WIDE)
;TI UCB ADDRESS
;ASSIGNMENT UCB ADDRESS
;LENGTH OF LCB

.MACRO
.ENDM
.ENDM

LCBDf$,X,Y

• llF

NDf' SSSYDF , .LIST

C-13

SYSTEM DATA STRUCTURES AHO SYMBOLIC DEFINITIONS
.IIF NDF S$SYDf , .NLIST
COPYRIGHT CC> 1974,1976,1977
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.
THIS SOFTWARE IS fURNISHED UNDER A LIC~NSE FOR USE ONLY ON A
SINGLE COMPUTER SYSTEM AND MAY BE COPIED
ONLY WITH THE
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE
MADE AVAILABLE TO A~Y OTHER PERSON
EXCEPT FOR USE ON SUCH
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN
IN DEC.
THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL
EQUIPMENT CORPORATION.
DEC ASSUMES NO R~SPONSIBILITY FOR THE USE OR RELIABILITY OF
ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC •
• MACRO

PCBOFS

L,B,SYSDEF

;+
; PARTITION CONTROL BLOCK OFFSET DEFINITIONS
;-

.=o

.ASECT

P.LNK: 'L' .BLKW 1
P.PRI:'L' .BLKB 1
P. IOC: 'L' .BLK~ 1
P.NAM: 'L' .BLK'w 2
P.SUB: 'L' .BLKw 1
P.MAIN: 'L' .BLKw 1

.n· NB

;LINK TO NEXT PARTITION PCB
JPRIORITY or PARTITION
;LIO + 1/0 STATUS BLOCK COUNT
:PARTITION ~AME IN RADSO
;POINTER TO N~XT SUBPARTITION
;POI~TER TO MAI~ PARTITION

SYSDEF

.IF NDF' M$$MGE
;POINTER TO HEADER CONTROL BLOCK

P .HOR: 'L'
.ENDC
.IFTF
P.REL: 'L' .BLKW
P.BLKS:'L'
P.SIZE: 'L' .BLKw 1
P.WAIT:'L'.BLKW 1
P.SWSZ:'L'.BLKw 1
P.BUSY: 'L' .BLKB 2
P.OWN:'L'
P.TCB: 'L' .BLKW
P.STAT: 'L' .BLj(,W

;STARTING PHYSICAL ADDRESS OF PARTITION
;SIZE OF PARTITION IN BYTES
;PARTITION ~AlT OUEUE LISTHEAD C2 WORDS)
;PARTITION SWAP SIZE (SYSTEM ONLY}
;PARTITION BUSY FLAGS
;TCB ADDRESS OF OWNER TASK
;PARTITION STATUS FLAGS

.IFT
.IF Dfi'

MS$MGE

P .. HDR:'L' .BLKW

;POINTER TO HEADER CONTROL BLOCK

.ENDC
P.PRO:'L' .BLKW 1
P.ATT:'L' .BLKW 2

WORD lDEWR,DEWR,DEWR,DEWRl
;ATTACHMENT DESCRIPTOR LlSTHEAD

;PRUT~CTION

.lF NDf' P$$LAS

C-14

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
P. LG'.l'H:' B 'P. PRO

;LENGTH OF PARTITION CONTROL BLOCK

.IFF
P.LG'.rH:'B'.

;LENGTH OF PARTITION CONTROL BLUCK

.ENDC
.IFF
.PSECT
;+
: PARTITION STATUS WORD BIT DEFINITIONS

PS.OUT:'B'lOOOOO
PS.CJ<P='B'40000
PS .Cl<R= 'B' 20000
PS.CliK='B'lOOOO
Ps.nrn='B'4ooo
PS.PJ:;R:'B'2000
PS.LlO='B'lOOO
PS.NSF:'B'400
PS.CDM:'B'200
PS.PlC='B'lOO

;PARTITION IS OUT OF MEMORYCl=YES)
;PARTITION CHECKPOINT IN PROGRESS Cl=YES)
;PARTITION CHECKPOINT IS REQUESTED Cl=YES)
;PARTITION IS NOT CHECKPOINTABLE (l:YES)
;PARTITION IS FIXED Cl=YES)
;PARITY ERROR IN PARTITION Cl=Y~S)
;MARKED BY SHUFFLER FOR LONG l/O Cl=YES)
:PARTITION IS NOT SHUFFLEABLE C1=YES)
:LIBRARY OR COMMON BLOCK C1=YES)
;POSITION INDEPENDENT LIBRARY OR COMMON C1=YES)
:SYSTEM CONTROLLED PARTITION C1=YES)
:DRIVER IS LOADED IN PARTITION C1=YES)
;PARTITION SHOULD BE DELETED WHEN NOT ATTACHED Cl=YES)
;STARTING APR NUMBER MASK

PS.S~iS:i:'B'40

PS.DRV:i:'B'20
PS.DJ:;Lz'B'lO
PS.Al?R='B'7

;+
; ATTACHMENT DESCRIPTOR OFFSETS
;.ASECT
.=o
A.PC.BL: 'L' .BLKW
A.PRI:'L'.BLKB
A. IOC: 'L' .BLKB
A.TCB: 'L' .BLKW
A.'fCBL: 'L' .B:LKw
A.STAT: 'L' .BLKB
A.MPCT: 'L' .BLKB
A.PCB: 'L' .BL.Kw
A.LGTH='B'.

:PCB ATTAC~MENT QUEUE THREAD WORD
;PRIORITY OF ATTACHED TASK
;1/0 COUNT THROUGH THIS DESCRIPTOR
;TCB ADDRESS OF ATTACHED TASK
;TCB ATTACHMENT QUEUE THREAD WORD
;STATUS l:HTE
;MAPPING COUNT OF TASK THRU THIS DESCRIPTOR
:PCB ADDRESS OF ATTACHED TASK
;LENGTH OF ATTACHMENT DESCRIPTOR

;+
; ATTACHMENT DESCRIPTOR STATUS BYTE BIT DEFINITIONS
;-

.PSECT
AS.DEL='B'lO
AS.EXT='B'4
AS.WRT='B'2
AS.RED='B'l

TASK HAS DELETE ACCESS Cl=YES)
TASK HAS EXTEND ACCESS Cl=YES)
TASK HAS WRITE ACCESS Cl=YES)
TASK HAS READ ACCESS C1=YES)

.ENDC
.MACRO
.ENUM
.ENDM

•

PCBDF$

X,Y,Z

.IIF NDF SS$YDF , .LIST

C-15

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
.IIY ~DF S$$YDf , .NL!St
COPYRIGHT CC) 1974, 1977
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.
THIS SOFTwARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A
SINGLE COMPUTER SYSTEM AND MAY BE COPIED
UNLY WITH THE
INCLUSION Of THE ABOVl COPYRIGHT NOTICE. THIS SOFTWARE, OR
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE
MADE AVAILABLE TO ANY OTHER PERSON
EXCEPT FOR USE ON SUCH
SYSTEM AND TO ONE wHO AGREES TO THESE LICl~NSE TERMS. TITLE
TO AND OWNERSHIP Of THE SOFTWARE SHALL AT ALL TIMES REMAIN
IN DEC.
THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL
EQUIPMENT CORPORATION.
DEC ASSUMES NO RESPUNSlBILITY FOR THE USE OR RELIABILITY OF
ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC •
• MACRO

PKTDFS,L,B,SYSDEF

ASYNCHRONOUS SYSTEM TRAP CONTROL BLOCK OFl~SET DEFINITIONS

; SOME POSITIONAL DEPENDENCIES BETWEEN THE OCB AND THE AST CONTROL BLOCK
; ARE RELIED UPON IN THE ROUTINE SFINXT IN ";rHE MODULE SYSXT.
:.ASECT
.=177774
A.KSR5:'L' .BLKW 1
A.DQSR:'L' .tlLKW 1
.BLKh
1
A.CBL:'L' .BLKw 1
A.BYT:'L' .BLKW 1
A.AST:'L' .BLKW 1
A.NPR:'L' .BLKW 1
A.PRM:'L' .BLKW 1

:SUBROUTINE KISARS BIAS CA.CBL=O)
:DEQUEUE SUBROUTINE ADDRESS (A.CBL•O)
:AST QUEUE THREAD WORD
;LENGTH OF CONTROL BLOCK IN BYTES
:NUMBER OF BYTES TO ALLOCATE ON TASK STACK
:AST TRAP ADDRESS
;NUMBER OF AST PARAMETERS
1FIRST AST PARAMETER

;+
; I/O PACKET OFFSET DEfINITIONS

.=o

.ASECT
;I/O QUEUE THREAD WORD
:REQUEST PRIORITY
:EVENT FLAG NUMBER
:TCB ADDRESS OF REQUESTOR
;POINTER TO SECOND LUN WORD
:POINTER TO UNIT CONTROL BLOCK
:110 FUNCTION CODE
;VIHTUAL ADDRESS OF 1/0 STATUS BLOCK
;I/O STATUS BLOCK RELOCATON BIAS
:IIO STATUS BLOCK ADDRESS
:AST SERYICE ROUTINE ADDRESS
:RESERVED FOR MAPPING PARAMETER #1
;PARAMETERS 1 TO 6
;USER MOD~ DIAGNOSTIC PARAMETER WORD
:MINIMUM LENGTH OF 1/0 PACKET (USED BY
;FILE S~STEM TO CALCULATE MAXIMUM
;NUMBER OF ATTRIBUTES)
:LENGTH OF I/O REQUEST CONTROL BLOCK

I.LNK:'L' .BLKW 1
I.PRI:'L' .8LKB 1
I.EFN:'L' .BLKB 1
I.TCB:'L' .BLKW 1
I.LN2:'L' .8LK~ 1
I.UCB:'L' .BLKW 1
I.FCN:'L' .BLKW 1
I.IOSB:'L' .BLKW
.SLKh
1
.BLKW
1
l.AST:'L' .BLK~ 1
l.PRM:'L' .BLKW 1
.BLKW
6
.BLKw
1
I.ATTL='B'.
I.LGTH='B' •
• PSEC'l'
.MACRO

PKTDFS

x,r,z

.ENDM
.ENDM

.IIF NUF SSSYDF , .LIST

C-16

•

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
.IIF

NDF S$$YDF ,

.~LIST

COPYRIGHT CC) 1974,1976,1977
DIGITAL EQUIPMENT CORPORATlON, MAYNARD, MASS.
THIS SOFTWARE lS FURNISHED UNUER A LICE~SE fU" USE ONLY ON A
SINGLE COMPUTER SYSTEM AND MAY BE COPIED
ONLY WITH THE
INCLUSION Of THE ABOVE COPYRIGHT NOTICE. THIS SOFT~ARE, OR
ANY OTHER COPIES THEREOF, MAY NUT BE PROVlDEU UR OTHERWISE
MADE AVAILAbLE TO ANY OTHER PERSON
EXCEPT FOR USE ON SUCH
SYSTEM AND TU ONE ~HO AGREES TO THESE LICENSE TERMS. TITLE
; TO AND OWNERSHIP Of' THE SOFTWARE SHALL AT ALL TIMES REMAIN
IN DEC.
THE INFORMATION IN THIS DOCUMENT IS SUBJECT TU CHANGE ~ITHOUT
NOTICE ANO SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL
EQUIPMENT CORPORATION.
DEC ASSUMES NO RESPONSIBILITY FOR THE uSE OR RELIABILITY OF
ITS SOFTWARE ON EQUIPMENT ~HICH IS NOT SUPPLIED BY DEC •
• MACRO

SCBDF$,L,B,SYSDEF

;+
STATUS CONTROL BLOCK
THE STATUS CONTRUL BLOCK (SCB) DEFINES THE STATUS OF A DEVICE CONTROLLER.
THERE IS ONE SCB FOR EACH CONTROLLER IN A SYSTEM. THE SCB IS POINTED TO
BY UNIT CONTROL BLOCKS. TO EXPAND ON THE TELETYPE EXAMPLE ABOVE, EACH TELETYPE INTERFACED VIA A DLll-A WOULD HAVE A SCB SINCE EACri DLll-A IS AN INDEPENDENT I~TERFACE UNIT. THE TELETYPES INTERFACED VIA THE DHll WOULD ALSO
EACH HAVE AN SCB SINCE THE DH11 IS A SlNGL~ CONTROLLER BUT MULTIPLEXES MANr
UNITS IN PAkALLEL ..
;-

.ASECT
.=ll 77772

S.RCNT:'L' .BLKB 1
S.ROFF:'L' .BLKB 1
S.BMSV:'L' .BLKW 1
S.BMSK:'L' .BLKW 1
S.1... HD: 'L' .. BLKw 2
S.PRl:'L' .BLKb 1
S.VCT:'L' .BLKB 1
S.CTM:'L' .BLKB 1
S.ITM:'L' .BLKB 1
S.CON:'L' .BLKB l
S.STS:'L' .BLKB 1
S.CSR:'L' .BLKW 1
s.PKT: 'L' .Bl1KW 1
S.FRK:'L' .BLKW 1
.BLKw
1
.BLKw
1
.BLKW
1
.IF NB

SYSDEF

.IF DF

L$$DRV & M$$MGE

.BLKW

;NUMBER OF REGISTERS TO COPY UN ERROR
;OFFSET TO FIRST DEVICE REGISTER
;SAVED 1/0 ACTIVE BITMAP AND POINTER TO EMB
;DEVICE I/O ACTIVE BIT MASK
:CONTROLLER I/O QUEUE LlSTHEAD
;DEVICE PRIORITY
;INTERRUPT VECTOR ADDRESS /4
;CURRENT TIMEOUT COUNT
;INITIAL TIMEOUT COUNT
;CONTROLLER INDEX
;CONTROLLER STATUS CO=lDLE,l=BUSY)
;ADDRESS OF CONTROL STATUS REGISTER
;ADDRESS OF CURRENT 1/0 PACKET
;FORK BLOCK LINK WORD
;FORK-PC
;1'-0RK-RS
;FORK-R4

;FORK-DRIVER RELOCATION BASE

.ENDC

s .. cca:'L'

S.,MPR:'L' .BLKW 6

;MIXED MASSBUS CHANNEL CONTROL BLOCK
;11/70 EXTENDED MEMORY UNIBUS DEVICE C-BLOCK

.PSECT

C-17

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
+
STATUS CONTROL BLOCK PRIORITY BYTE CONDITION CODE STATUS BIT DEFINITIONS
SP.ElP='B'l
SP.ENB='B'2
SP.LOG='B'4
SPARE=10

:ERROR IN PROGRESS Cl=YES)
:ERROR LUGGING ENABLED CO=YES)
;ERROR LOGGI~G AVAILABLE Cl•YES)
:SPARE BIT

;+
; MAPPING ASSIGNME~T BLOCK CfOR UNIBUS MAPPING REGISTER ASSIGNMENT)
;-

.ASECT
.=O
M.LNK:'L' .bLKw 1
M.UMRA 'L' .BLKw 1
M.UMRN 'L' .BLKW 1
M.UMVL 'L' .BLKW 1
M.UMVH 'L' .BLKB 1
M.BFVH 'L' .BLKB 1
M.BFVL 'L' .BLKw 1
M.LGTH , B, •

:LINK WORD
;ADDRESS OF FIRST ASSIGNED UMR
;NUMBER or UMR'S ASSIGNED
4
;LOW 16 BITS MAPPED BY lST ASSIGNED UMR
;HIGH 2 BITS MAPPED IN BITS 4 AND 5
;HIGH 6 BITS OF PHYSICAL BUFFER ADDRESS
:LUw 16 BITS OF PHYSICAL BUFFER ADDRESS
;LENGTH UF MAPPING ASSIGNMENT BLUCK

.ENDC
.PSt::CT
.MACRO

SCBDFs,x,~.z

.ENDP-1
.~NDM

.IIF

NDF SSSYDF , .LIST

C-18

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
.IIF ~DF S$$YDf

.NLIST

COPYRIGHT CC) 1974,1976,1977
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A
SINGLE COMPUTER SYSTEM ANO MAY BE CDPl~D
ONLY ~ITH THE
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFT~ARE, OR
ANY OTHER COPIES TH~REOF, MAY NOT BE PROVIDED OR OTHERWISE
MADE AVAILABLE TO ANY OTHER PERSON
EXCEPT FOR USE ON SUCH
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE
TO ANO OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN
lLN DEC.

'.rHE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL
EQUIPMENT CORPORATION.
J)EC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF
ITS SOFTWARE ON EQUIPMENT ~HICH IS NOT SUPPLIED BY DEC •
• MACRO

TCBDFS,L,8,SYSDEF

;+
; TASK CONTROL BLOCK OFFSET AND STATUS DEFINITIONS
;

; TASK CONTROL BLOCK
;-

.=o

.ASECT

T.LNK: 'L' .BliKW 1
T.PRI:'L' .BLKB 1
T.IOC:'L' .BLKB 1
T.CPCB:'L' .BLKW 1
T.NAM: 'L' .BLKW 2
T.RCVL:'L' .BLKW 2
T.ASTL:'L' .BLKW 2
T.EFLG:'L' .liLKW 2
T.UCB: 'L' .BLKW 1
T.TCBL:'L' .BLKW 1
T.STAT:'L' .BLKW 1
T.ST2:'L' .BLKW 1
T.ST3:'L' .BLKW 1
T.OPRI:•L' .bLKB 1
T.LBN:'L' .BLKB 3
T.LDV:'L' .BLKW 1
T.PCB:'L' .BLKW 1
T.MXSZ:'L' .BLKW 1
T.ACTL:'L' .BLKW 1
T •. ATT:'L' .BLKW 2
T.OFF:'L' .BLKW 1
.SLKB 1
ToSRCT:'L' .BLKB 1
ToRRFL:'L~ .BLKW 2

:UTILITY LINK WORD
;TASK PRIORITY
:IID PENDING COUNT
:POINTER TO CHECKPOINT PCB
;TASK NAME IN RAD50
:RECEIVE QUEUE LISTHEAD
;AST QUEUE LlSTHEAD
;TASK LOCAL EVENT FLAGS 1•32
:UCB ADDRESS FOR PSEUDO DEVICE 'Tl'
;TASK LIST THR~AD WORD
;FIRST STATUS WORD (BLOCKING BITS)
;SECOND STATUS WORU (STATE BITS)
:THIRD STATUS WORD CATT~IBUT~ BITS)
:TASK'S DEFAULT PRIORITY
;LBN OF TASK LOAD IMAGE
;UCB ADDRESS OF LOAD DEVICE
:PCB ADDRESS OF TASK PARTITION
;MAXIMUM SIZE OF TASK !MAGE (MAPPED ONLY)
;ADDRESS OF NEXT TASK IN ACTIVE LIST
:ATTACHMENT OESCHIPTOR LISTHEAD
;OFFSET TO TASK IMAGE IN PARTITION
;RESERVED
:SREF wITH EFN COUNT IN ALL RECEIVE QUEUES
7RECE1Vg BY REFERENCE LISTHEAO

.IF NB SYSDEF
.IF NDF P$$LAS
T .. LGTH='B'T.AT'l'
.XFF

T.,LGTH='B'.

:LENGTH OF TASK CONTROL BLOCK

.ENDC
T.EXT='B'O

;LENGTH OF TCB EXTENSION

.IFF

C-·19

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
:+
: TASK STATUS DlFINITIUNS

: FIRST STATUS WOHD (BLOCKING HITS)

;TS.EXE='B'lOOOOO
TS.RDN='B'40000
TS.MSG:'B'20000
TS.NRP='B'lOOOO
TS.RUN='B'4000
TS.OUT='B'400
TS.CKP='B'200
TS.CKR='B'lOO

:TASK NOT IN EXECUTION ClaYES)
:IIO RUN DOWN IN PROGRESS Cl=YES)
:ABORT MESSAGE BEING OUTPUT Cl•YES)
;TASK MAPPED TO NONRESIDENT PARTITION Cl=YES)
;TASK IS RUNNING ON ANOTHER PROCESSOR (1aYES)
;TASK IS OUT OF MEMORY Cl=YES)
;TASK IS BEING CHECKPOINTED Cl=YES)
ITASK CHECKPOINT REQUESTED Cl•YES)

;+
; TASK HLOCKING STATUS MASK
;TS.SLK='B'TS.CKP!TS.CKR!TS.EX~!TS.MSG!TS.NRP!TS.OUT!TS.RDN

;+
; SECOND STATUS WORD CSTATE BITS)

T2.AST:'B'100000
T2.DST='B'40000
T2.CHK='B'20000
T2.CKD:'B'10000
T2.BFX='8'4000
T2.FXD='B'2000
T2.TIO='B'1000
T2.CAF='B'400
T2.HLT='B'200
T2.ABO='B'100
T2.S'l'P='B'40
T2.STP='B'20
T2.SPN='B'10
T2.SPN='B'4
T2.WFR:'8'2
T2.WFR:'B'1

:AST IN PROGRESS Cl=YES)
;AST RECOGNITION DISABLED Cl=YEa)
:TASK NOT CHECKPOINTABLE Cl•YES)
;CHECKPOINTING DISABLED Cl=YES)
:TASK BEING FIXED IN MEMORY Cl=YES)
;TASK FIXED IN MEMORY Cl=YES)
:TASK IS ENGAGED IN TERMINAL I/O
;OYN CHECKPOINT SPACE ALLOCATION FAILURE
:TASK IS BEING HALTED Cl=YES)
;TASK MARKED FOR ABORT C1=YES)
;TASK STOPPED Cl=YES)
ITASK STOPPED Cl=YES)
;SAVED TS.SPN ON AST IN PROGRESS
;TASK SUSPENDED Cl=YES)
;SAVED TS.WFR ON AST IN PROGRESS
;TASK IN WAITFOR STATE Cl•YES)

;+
; THIRD STATUS WORD CAlTRIBUTE BITS)
;T3.ACP:'B'100000
T3.PMD='B'40000
T3.REM='B'20000
T3.PRv=·s·10000
T3.MCR:'B'4000
T3.sLv=•s•iooo
T3.CLI=•a•1000
T3.RST:'B'400
T3.NSD='B'200
T3.CAL='B'100
T3.ROV='B'40
T3.NET='B'20

;ANCILLARY CO~TROL PROCESSOR Cl=YES)
;DUMP TASK ON SYNCHRONOUS ABORT CO=YES)
;REMOVE TASK ON EXIT C1=YES)
:TASK IS PRIVILEGED C1=YES)
;TASK REQUESTED AS EXTERNAL MCR FUNCTION Cl=YES)
;TASK IS A SLAVE TASK Cl=YES)
;TASK IS A COMMAND LINE INTERPRETER Cl•YES)
;TASK IS RESTRICTED C1=YES)
;TASK DOES NOT ALLOW SEND DATA
;TASK HAS CHECKPOINT SPACE IN TASK IMAGE
;TASK HAS RESIDENT OVERLAYS
;NETWORK PROTOCOL LEVEL

.ENDC
.PSECT
.MACRO
.ENDM
.ENDM

TCBDFS

X,Y,Z

.llF NDF S$$YDF , .LIST

C-20

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
.llF

NDF S$SYDF

.NLlST

COPYRIGHT (C) 1974,1976,1977
DIGITAL EOUIPMENT CORPORATION, MAYNARD, MASS.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A
SINGLE COMPUTER SYSTEM AND MAY BE COPIED
ONLY WITH THE
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR
ANY OTHER COPlES THEkEOF, MAY NOT BE PROVIDED OR OTHEHWlSE
MADE AVAILABLE TO ANY OTHER PERSON
EXCEPT FOR USE ON SUCH
SYSTEM AND TO ONE WHO AGREES TU THESE LICENSE TERMS. TITLE
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN
J.N DEC.

~·

THE INFORMATION IN THIS DOCUMENT 15 SUBJECT TO CHANGE WITHOUT
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL
EQUIPMENT CORPORATION.
DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF
ITS SOFTwARE ON EOUlPMENT WHICH IS NOT SUPPLIED BY DEC •
• MACRO

UCBDF$,L,B

;+
UNIT CONTROL BLOCK
THE UNIT CONTROL BLOCK (UCB) DEFINES THE STATUS OF AN INDIVIDUAL DEVICE
UNIT AND IS THE CONTROL BLUCK THAT IS POINTED TO BY THE FIRST WORD OF
i~N ASSIGNEU LUN. THERE IS ONE UCB FOR EACH DEVICE UNIT OF EACH DCB. THE
IUCB'S ASSOCIATED WITH A PARTICULAR DCB ARE CONTIGUOUS IN MEMORY AND ARE
POINTED TO BY THE DCB. UCB'S ARE VARIABLE LENGTH BETWEEN DCB'S BUT ARE
OF THE SAME LENGTH FOR A SPECIFIC DCB. TO FINISH THE TELETYPE EXAMPLE ABOVE,
EACH UNIT ON BOTH INTERFACES WOULD HAVE A UCB.
;~·

.ASECT
.=177774
U.LUIC:'L' .BLKW 1
U.OWN:'L' .BLKW 1
U.DCB:'L' .BLKW 1
U.RED:'L' .BLKW 1
U.CTL:'L' .BLKB 1
U.STS:'L' .BLKB 1
U.UNIT:'L' .BLKB 1
U.ST2 'L' .BLKB 1
u.cw1 'L' .BLKW 1
u.cw2 'L' .BLKW 1
U.CW3 'L' .BLKW 1
U.CW4 'L' .BLKW 1
U.SCB 'L' .BLKW 1
U.ATT 'L' .BLKW 1
U.BUF 'L' .BLKw 1
.BLKW
1
U.CNT:'L' .BLKW 1
U.ACP='B'U.CNT+2
U.VCB='B'U.CNT+4
u •. CBF= I B, u.CINT+2
UtiUIC='B'U.C~T+<9.*2>

;LOGIN UIC • MULTI USER SYSTEMS ONLY
;OWNING TERMINAL • MULTI USER SYSTEMS ONLY
;BACK POINTER TO DCB
;POINTER TO REDIRECT UNIT UCB
;CONTROL PROCESSING FLAGS
;UNIT STATUS
;PHYSICAL UNIT NUMBER
;UNIT STATUS EXTENSION
;FIRST DEVICE CHARACTERISTICS WORD
;SECOND DEVICE CHARACTERISTICS WORD
;THIRD DEVICE CHARACTERISTICS WORD
;FOURTH DEVICE CHARACTERISTICS WORD
;POINTER TO SCB
;TCB ADDRESS OF ATTACHED TASK
;RELOCATION BIAS OF CURRENT I/0 REQUEST
;BUFFER ADDRESS OF CURRENT I/O REQUEST
:BYTE COUNT OF CURRENT I/O REQUEST
;ADDRESS OF TCB Of MOUNTED ACP
;ADDRESS OF VOLUME CONTROL BLOCK
;CONTROL BUFFER RELOCATION AND ADDRESS
;TERMINAL UlC (TERMINALS ONLY)

.PSECT
; ~r

; DEVICE TABLE STATUS DEFINITIONS
I

; DEVICE CHARACTERISTICS WORD 1 CU.CWl) DEVICE TYPE DEFINITION BITS.

;

011.REC='B"l
D11.CCL:'B"2
D1f.TTY='B"4
DV.DIR='B"lO
DV.SDI:'B*20
D'V.SQD:'B'40
D'V.MXD='B'lOO

;RECORD ORIENTED DEVICE Cl=YES)
;CARRIAGE CONTROL DEVICE Cl=YES)
;TERMINAL DEVICE Cl=YES)
;FILE STRUCTURED DEVICE Cl=YES)
:SINGLE DIRECTORY DEVICE Cl=YES)
:SEQUENTIAL DEVICE Cl=YES)
;MASS BUS DEVICE Cl=YES)

C-21

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
DV.UMD='B'200
DV.SWL='B'lOOO
DV.lSP='B'2000
IJV.OSP='H'4000
DV.PSt::'B'lOOOO
DV.COM='B'20000
DV .1'1l='B•40000
DV.MNT='B'lOOOOO

;USER MODE DIAGNOSTICS SUPPORTED Cl=YES)
;UNIT SOFTWARE WRITE LOCKED Cl=YES)
;INPUT SPOOL~D DEVICE Cl=YES)
;OUTPUT SPOOLED DEVICE Cl=YES)
;PSEUDO DEVICE Cl=YES)
:DEVICE IS MOUNTABLE AS COM CHANNEL Cl=YES)
;DEVICE IS MOUNTABLE AS Fll DEVICE Cl=YES)
:DEVICE IS MOUNTABLE Cl:YES)

;+
; TERMINAL DEPENDENT CHARACTERISTICS WORD 2 (U.CW2) BIT DEFINITIONS
;-

U2.DHl:'B'100000
U2.DJ1:'B'4000U
U2.RMT='B'20000
U2.L8S='B'10000
U2.NEC='B'4000
U2.CRT='B'2000
U2.ESC='B'1000
U2.LOG:'B'400
U2.SLV='B'200
U2.DZ1='B'100
U2.HLD='B'40
U2.AT.='B'20
U2.PRV='B'10
U2.L3S='B'4
U2.VT5:'B'2
U2.LWC:'B'l

;UNIT IS A MULTIPLEXEM Cl=YES)
;UNIT IS A DJll Cl=YES)
;UNIT IS REMOTE Cl=YES)
;UNIT 15 LA180S Cl=YES)
;DON'T ECHO SOLICITED INPUT Cl=YES)
;UNIT IS A CRT Cl=YES)
;UNIT GENERATES ESCAPE SEQUENCES Cl=YES)
;USER LOGGED ON TERMINAL CO=YES)
;UNIT IS A SLAVE TERMINAL Cl=YES)
;UNIT IS A DZll Cl=YES)
;tERMINAL IS IN HOLD SCREEN MODE Cl=YES)
:MCR COMMAND AT. B~ING PROCESSED Cl=YES)
;UNIT IS A PRIVILEGED TERMINAL C1=YES)
;UNIT IS A LA30S TERMINAL (l:YES)
:U~IT IS A VT05B TERMINAL Cl=YES)
;LOWER CASE TO UPPER CASE CONVERSION C1=YES)

:+
; RH11•RS03/RS04 CHARACTERISTICS WORD 2 CU.CW2) BIT DEFINITIONS
:-

U2.R04='B'100000

;UNIT lS A RS04 Cl=YES)

; HHl1•TU1b CHARACTERISTICS WORD 2 CU.CW2) BIT DEFINITIONS
:U2.7CH:'B'10000

:UNIT IS A 7 CHANNEL DRIVE Cl=YES)

;+
; UNIT CONTROL PROCESSI~G FLAG DEFINITIONS

UC.ALG='B'200
UC.NPR='B'lOO
UC.QUE='B'40
UC.PWF='B'20
UC.ATT:'B'10
UC.KIL='B'4
UC.LGH='B'3

;BYTE ALIGNME~T ALLOWED C1=NO)
;DEVICE IS AN NPR DEVICE C1=YES)
:CALL DRIVER BEFORE QUEUING Cl=YES)
;CALL DRIVER AT POWERFAIL ALWAYS Cl=YES)
;CALL DRIVER ON ATTACH/DETACH Cl=YES)
:CALL DRIVER AT 1/0 KILL ALWAYS Cl=YES)
:TRANSFER LENGTH MASK BITS

: UNIT STATUS BIT DEFINTIONS

us .• BSY='B'200
US.MNT:'B'100
US.FOR='B'40
US.MDM:'B'20

;UNIT IS BUSY Cl=YES)
;UNIT IS MOUNTED CO:YES)
;UNIT IS MOUNTED AS FOREIGN VOLUME Cl=YES)
;UNIT IS MARKED FOR DISMOUNT Cl=YES)

;+
: CARD READER DEPENDENT UNIT STATUS BIT DEFINITIONS

us.ABO='B'l
US.MDE='B'2

;UNIT IS MARKED FOR ABORT IF NOT READY C1=YES)
;UNIT IS IN 029 TRANSLATION NODE Cl=YES)

;+
; FILES•ll DEPENDENT UNIT STATUS BITS
:us.wcK='B'lO
US.SPU='B'2

;WRITE CHECK ENABLED Cl=YES)
;UNIT IS SPINNING UP (l:YES)

C-22

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
;+
; TERMINAL DEPENDENT UNIT STATUS BIT DEFINITIONS
;-

us.osa=·B·10

;UNIT IS DISABLED (l=YES)
;UNIT IS WAITING FOR CARRIER Cl=YES)
;UNIT HAS ECHO IN PROGRESS Cl=YES)
;UNIT IS EXPECTING OUTPUT INTERRUPT (l:YES)

US.CRwa•a•4
US.ECH='B'2
US.OUT='B'l

;+
; LPSll DEPENDENT UNIT STATUS BIT DEFINITIONS
;;FORK IN PROGRESS (l:YES)
;SHAREABLE FUNCTION IN PROGRESS (O:'B'YES)

US.FRK='B'2
US.SHR='B'l

;+
; ANSI MAGTAPE DEPENDANT UNIT STATUS BITS
;: UNIT HAS LABELED TAPg ON IT Cl=YES)
;+
; UNIT STATUS EXTENSION CU.ST2) BIT DEFINITIONS

US.OFL='B'l
US.KEO='B'2
US.PUB='B'4
US.UMD='B'lO
.MACRO
.ENDM
.ENDM
.IIF

;UNIT OFFLINE Cl=~ES)
;UNIT REDIHECTABLE CO=YES)
;UNIT rs PUBLIC DEVICE Cl=YES)
;UNIT ATTACHED FOR DIAGNOSTICS Cl=YES)
UCBDF$,X,Y

NDf SS$YOF , .NLIST

C-23

INDEX

Accessing shared data bases, 2-9
$ACHCK, 5-2
$ACHKB, 5-2
ACP function, 2-16
ACP function mask, 4-12
Address check,
($ACHKB/$ACHCK) , 5-2
Address-checking and relocation,
6-9
Address doubleword, A-1
Addressing, 22-bit, B-1
Allocate Core Buffer ($ALOCB),
5-3
$ALOCB, 5-3
APR 5, 3-11, 3-15, 4-29
APR 6, 3-15, 4-5
Assign UNIBUS Mapping Registers,
($ASUMR), 5-4, B-3
$ASUMR, 5-4, B-3

Bootstrapping, 2-4, 3-26

Cancel I/O entry point, 2-4,
3-2, 4-10
CDA,, 3-17
Characteristics, device, 4-23,
4-24
CINT$ directive, 3-1
$CLINS, 5-5
Clock Queue Insertion ($CLINS),
5-5
Conditional routines, 5-1
Connect to interrupt vector
directive, 3-1.
Control function, 2-16
Control function mask, 4-12
Control status register (CSR) ,
4-18
Controller number, 2-13, 4-18,
4-27
Conventions, programming, 2-13
Crash dump analysis support
routine (CDA), 3-17
$CRAVL, 3-24
CSR, 4-18

Data bases, accessing shared,
2-9
Data structures, 2-5 to 2-9
interrelation of, 2-17
summary, 2·-2 0
system, C-1
DCB, 2-5, 2-17, 2-19, 3-3, 4-7

DCB fields,
D. DSP, 3-4, 4-9
D.LNK, 3-4, 3-8, 4-8
D.MSK, 3-4, 4-5, 4-11
D. NAM, 3-4, 4-9
D.PCB, 3-4, 4-7, 4-13
D.UCB, 3-4, 3-8, 4-8
D.UCBL, 3-4, 4-9
D.UNIT, 3-4, 4-9
DCB fields, required, 3-4
DDT, 2-17, 2-19, 3-2, 4-9, 4-10
$DEACB, 3-25, 5-6
Deallocate Core Buffer ($DEACB),
3-25, 5-6
Deassign UNIBUS Mapping Registers,
($DEUMR), 5-7, B-3
Debugging, driver, 3-12 to 3-25,
aids, 3-13 to 3-18
fault isolation, 3-18 to 3-20
fault tracing,
after unintended loop, 3-24
critical pointers, 3-20
using stack and register
dump, 3-22
without display, 3-23
Debugging aids, 3-13 to 3-18
Definitions, symbolic, C-1
$DEUMR, 5-7, B-3
$DEVHD word, 2-17, 2-18, 2-19
Device characteristics, 4-23,
4-24
Device Control Block (DCB),
2-5, 2-17, 2-19, 3-3, 4-7
Device interrupt entry point,
2-3, 3-2
Device interrupt vector, 2-9,
2-13, 3-3, 3-6, 4-17, 4-26
Device Message Output ($DVMSG),
5-8
Device timeout, 4-17
Device timeout entry point, 2-4,
3-2, 4-10
Directive Parameter Block (DPB),
2-5, 2-8, 2-16, 4-5
DPB, 2-5, 2-8, 2-16, 4-5
$DRDSP, 3-2 3
Driver,
coding example, 6-1
debugging, 3-12 to 3-25
entry points, 2-3, 2-4, 3-2
function, 1-1
loadable, see loadable drivers
multicontroller, 2-13, 4-27
Non-MASSBUS NPR, B-1
resident, see resident drivers
role in RSX-llM, 2-3, 2~4
Driver code,
loadable, 3-2, 3-3

Index--1

May 1979

INDEX

Driver code (Cont.),
overview, 3-2
resident, 3-2, 3-3
Driver dispatch table (DDT), 2-17,
2-19, 3-2, 4-9, 4-10
DRQIO, 2-10
$DVMSG, 5-8

Error logging, 3-3
Executive debugging tool (XDT) ,
3-14, 3-15, 3-18
Executive services, 2-10 to 2-12
Executive stack and register
dump ~outine, 3-13, 3-14,
3-19
Fault isolation, 3-18 to 3-20
Fault tracing, 3-20
FCB, 2-17 I 2-19
FCP, 2-3
FCS, 2-1, 2-2
File control block {FCB), 2-17,
2-19
File control primitives (FCB),
2-3
File control services (FCS), 2-1,
2-2
Flow of an I/O request, 2-15
$FORK, 2-9, 2-12, 2-15, 4-17,
4-19, 5-9
Fork block, 4-19
Fork level processing, 2-9, 2-15
Fork list, 2-9
$FORK1, 5-10
Function mask values, I/O, 4-14
Get Byte ($GTBYT), 5-11
Get Packet,
($GTPKT), 2-11, 2-17, 4-18,
4-25, 4-27, 5-12
Get Word ($GTWRD) , 5-13
GLUN$ directive, 4-23
$GTBYT, 5-11
$GTPKT, 2-11, 2-17, 4-18, 4-25,
4-27, 5-12
$GTWRD, 5-13
$HEADR pointer, 3-20, 3-23
HWDDF$ macro, 4-17
I/O Done and I/O Done Alternate
Entry,
($IODON/$IOALT) I 2-12, 5-16

I/O Finish,
($IOFIN), 2-11, 5-17
I/O function mask values, 4-14
I/O hierarchy, 2-1
I/O initiator entry point, 2-4,
2-11, 3·-2, 4-10
I/O Packet, 2-8, 2-16, 4-2, 4-18
I/O Packet fields,
I.AST, 4-5
I.EFN, 4-3
I.FCN, 3-24, 4-4
I. IOSB, 4-4
I .LNK, 4-2
I.LN2, 4-4
I. PRI, 4-3
I.PRM, 4-5
I.TCB, 4-4
I.UCB, 4-4
I/O Queue, 2-8, 4-16
I/O request,
flow of, 2-15
I/O Status Block (IOSB), 2-10,
2-16, 2-17, 4-4, 4-7
ICB, 4-28, 4-29
Initiator entry point, I/O, 2-4,
2-11, 3-2' 4-10
INITL module, 3-19
Interrupt control block (ICB),
4-28' 4·-29
Interrupt entry point, device,
2-3, 3-2
Interrupt Exit,
($INTXT), 2-13, 5-15
Interrupt Save,
($INTSV), 2-11, 2-12, 2-13 to
2-15, 4-28, 5-14
Interrupt vector, device, 2-9,
2-13, 3-3, 3-6, 4-17, 4-26
$INTSV, 2-11, 2-12, 2-13 to 2-15,
4-28 I 5-·14
INTSV$ macro, 2-12 to 2-15,
4-27 to 4-29
$INTXT, 2-13, 5-15
$IOALT, 2-12, 5-16
~?IODON, 2-12, 2-17, 4-18, 5-16
$IOFIN, 2-11, 5-17
IOSB, 2-10, 2-16, 2-17, 4-4, 4-7

Legal function mask, 4-11
J:..OAD command, 2-4, 3-8, 3-10 u
3-12, 3-27, 4-17, 4-18,
4-26, 4-28
Loadable drivers,
adding to system library, 3-10
assembling, 3-10
creating the data base foru
3-9

Index·-2

May 1979

INDEX

Loadable drivers (Cont.),
dynamic :initialization of
interrupt vector, 4-26
LD$xx symbol for, 3-3
loading, 3·-12
nature of data base for, 3-8
rebuilding and reincorporating,
3-27
source code, 3-2, 3-3
specifying support for, 3-2
task building, 3-10 to 3-12
Logical unit table (LUT), 2-18,
4-4
LUT 2-18 I 4·-4
jl

Map UNIBUS to memory,
($MPUBM, $MPUB1) I 5-18,
B-2
Mapping register assignment
block, B·-2, B-3
Masks, I/O function, 4-11
establishing, 4-14
$MPUBM, 5-18, B-2
$MPUB1, 5-18.1, B-2
Multicontroller drivers, 2-13,
4-27

Non·-MASSBUS NPR device drivers,
B-1
No-op function, 2-16
No-op function mask, 4-12
NPR device drivers, 4-25, B-1

Panic dump, 3-16, 3-17, 3-19
Paper tape punch driver, 6-3
Partition control block (PCB),
4-13, 4-14
PCB,, 4-13, 4·-14
$PKlWL I 3-2 4
PowE~r failure entry point, 2-4,
3-2, 4·-10
Process,
characteristics, 2-13
states, 2-10
Processing,
at fork level, 2-9, 2-15
at priority 7, 2-9, 2-11, 2-14
at priority of interrupting
source, 2-9, 2-14, 4-17
Proqramming conventions, 2-13
Proqramming protocol, 2-13
Protocol, programming, 2-13
$PTBYT, 5-19
$PTWRD, 5-20

Put Byte ($PTBYT), 5-19
Put Word ($PTWRD), 5-20

$QINSP, 5-21
QIO directive, 2-2, 2-16
Queue Insertion by Priority
($QINSP), 5-21

Record management services
(RMS) I 2-1, 2-2
REDIRECT command, 4-21
Register conventions, systemstate, 5-1
$RELOC, 5-22
Relocate ($RELOC) , 5-22
Relocating and address-checking,
6-9
Resident drivers,
creating the data base for, 3-6
incorporating, 3-6
initializing the device
interrupt vector, 3-6, 4-26
padding space in, 3-3
rebuilding and reincorporating,
3-25
source code, 3-2, 3-3
RMS, 2-1, 2-2

SCB, 2-6, 2-18, 2-19, 3-3~ 4-16,
B-2
SCB fields,
S.CON, 3-5, 4-18, 4-27
S.CSR, 3-5, 4-18
S.CTM, 3-5, 4-17
S.FRK, 3-5, 4-19
S.ITM, 3-5, 4-17
S.LHD, 3-5, 3-8, 4-2, 4-16
S.MPR, 3-5, 4-19, B-2, B-3
S.PKT, 3-5, 3-24, 4-18
S.PRI, 3-5, 4-17
S.STS, 3-5, 4-18
S.VCT, 3-5, 4-17
SCB fields, required, 3-5
Set Up UNIBUS Mapping Address,
($STMAP, $STMP1) I 5-23, B-2
Shared data bases, accessing,
2-9
Special user buffers, 6-9
SST fault, 3-22, 3-23
Stack and register dump routine,
3-13, 3-14, 3-19
Stack structure, 3-22, 3-23
Status Control Block (SCB), 2-6,
2-18, 2-19, 3-3, 4-16, B-2

Index-·3

May 1979

INDEX

Status information, deviceindependent, 4-22, 4-23
$STKOP pointer, 3-20, 3-23
$STMAP, 5-23, B-2
$STMP1, 5-24, B-2
Symbolic definitions, C-1
Symbolic UMR addresses, B-3
Symbols,
LD$xx, 3-3, 4-29
M$$EXT, B-2
M$$MGE, B-2
N$$UMR, B-2
U$$MHI, B-3
U$$MLO, B-3
U$$MRN, B-3
$USRTB, 3-6
$xxINP, 3-2, 4-7
$xxINT, 3-2, 4-7
$xxOUT, 3-2, 4-7
$xxTBL, 3-2
SYSCM pointers,
$CRAVL, 3-24
$HEADR, 3-20, 3-23
$STKDP, 3-20, 3-23
$TKTCB, 3-20, 3-23
SYSTB, 3-19
System data structures, C-1
System-state register conventions,
5-1

Task header, 2-17, 2-18, 3-20,
3-21
Timeout entry point, device,
2-4 I 3-2 I 4-10
$TKTCB pointer, 3-20, 3-23
Transfer function, 2-16

UCB fields (Cont.),
U.CNT, 3-5, 4-26
U.CTL, 2-8, 3-5, 4-21
U.CWl, 3-5, 4-23
U.CW2, 3-5, 4-24
U.CW3, 3-5, 4-24
U.CW4, 3-5, 4-24
U.DCB, 3-4, 3-8, 4-9, 4-21
U.LUIC, 3-4, 4-9, 4-19
U.OWN, 3-4, 4-9, 4-20
U.RED, 3-4, 3-8, 4-21
U.SCB, 3-5, 3-8, 4-24
U.STS, 3-5, 4-22
U.ST2, 3-5, 4-23
U.UNIT, 3-5, 4-23
UCB fields, required, 3-4, 3-5
UMR addresses, symbolic, B-3
UMRs, B-1
UMRs, allocating during system
generation, B-2
UNIBUS Mapping Registers (UMRs),
B-1
Unit control block (UCB), 2-6,
2-18, 2-19, 3-3, 4-19
. UNLOAD command, 3-8, 3-27, 4-·2 6
User buffers, special, 6-9
!?USRTB, 3-6
USRTB, 3-6

VCB, 2-18, 2-19
Virtual MCR (VMR) , 3-26
Volume control block (VCB), 2-18,
2-19

Window block (WB), 2-17, 2-18,
2-19' 4-4
UCB, 2-6, 2-18, 2-19, 3-3, 4-19
UCB fields,
U.ATT, 3-5, 4-25
U.BUF, 3-5, 4-25, B-2

XDT, 3-14, 3-15, 3-18

Index-·4

May 1979

Update No.l
RSX-llM

Guide to Writing an I/O Driver
AA-2600D-TC, AD-2600D-Tl
READER'S COMMENTS

NOTE:

This form is for document comments only.
DIGITAL will
use comments submitted on this form at the company's
discretion.
If you require a written reply and· are
eligible to receive one under Software Performance
Report (SPR) service, submit your comments on an SPR
form.

Did you find this manual understandable, usable, and well-organized?
Please make suggestions for improvement.

·=
.~

..c:
.....

c
~

"5u

Did you find errors in this manual?
page number.

If so, specify the error and the

cQ)

0:::

Please indicate the type of reader that you most nearly represent.
[] Assembly language programmer
[] Higher-level language programmer
[] Occasional programmer (experienced)
[] User with little programming experience
[] Student programmer
[] Other (please specify>~~~~~~~~~~~~~~~~~~-

Organization
Street
City

,_ _ _,_ _ _ _ _ _ _ _ _ S t a t e - - - - - - - Zip Code _ _ _ _ _ __
or
Country

Do Not Tear- Fold Here and Tape -

·- -

No Postage
Necessary
if Maiiled in the
United States

111111

BUSINESS REPLY MAIL
FIRST CLASS PERMIT N0.3:3 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

RT/C SOFTWARE PUBLICATIONS

TW/A14

DIGITAL EQUIPMENT COBPORATION
1925 ANDOVER STREET
TEWKSBURY, MASSACHUSETTS

Do Not Tear - Fold Here

·- -

01876

UPDATE NOTICE NO.l
RSX-llM Guide to Writing an I/O Driver
AD-2600D-Tl
May 1979
Insert this Update Notice page in the manual as a means of maintaining
an up-to-date record of changes to the manual.
NEW AND CHANGED INFORMATION
This update reflects software changes and additions made in RSX-llM
Version 3.2.
Copyright

@ 1979 Digital. Equipment Corporation
INSTRUCTIONS

Place the following pages in the RSX-llM Guide to
Writing an I/O Driver as replacements for, or
additions to, current pages. The changes made on
replacement pages are indicated in the outside
margin by change bars (I) for additions, and
bullets ( • ) for deletions.
Old Page

New Page

Title Page/Copyright Page
iii/iv through vii/viii
2-13/2-14
3-3/3-4
3-9/3-10
4--9/4-10
4--11/4-12

Title Page/Copyright Page
iii/iv through vii/viii
2-13/2-14
3-3/3-4
3-9/3-10
4-9/4-10
4-11/4-12
4-12. 1/ blank
4-13/4-14
4-15/4-16
4-19/4-20 through 4-23/4-24
5-15/5-16
5-18. l/blank
5-23/5-24
6-3/6-4
B-1/B-2
B-3/B-4
Index-1/Index-2
Index-3/Index-4
Reader's Comments

4--13/ 4-14
4--15/ 4-16
4-19/4-20 through 4-23/4-24
5--15/5-16
5·-2 3/5-2 4
6-3/6-4
B-l/B-2
B-3/B-4
Index-1/Index-2
Index-3/Index-4
Reader's Comments

Additional copies of this update to the RSX-11.M Guide to Writing
an I/O Driver may be ordered from the Software Distribution
Center, Digital Equipment Corporation, Maynard, Massachusetts
017 54. Order Code: AD-2 600D-Tl. rhe order code of the base
manual is AA-2600D-TC.
1