Digital PDFs

DEC-11-OMWDA-B-D

May 1975

117 pages

Original

4.1MB

Document:	RSX-11M Guide to Writing an I/O Driver Version 2
Order Number:	DEC-11-OMWDA-B-D
Revision:	0
Pages:	117
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V2/DEC-11-OMWDA-B-D_DrvWrt_1975.pdf

OCR Text

RSX-11M
Guide to Writing
an 1/0 Driver
Order No. DEC-11-0MWDA-B-D

RSX-llM Version 2

digital equipment corporation · maynard. massachusetts

First Printinq, April 1975
Revised, September 1975

The information in this document is subject to change without notice
and should not be construed as a commitment by Digital Equipment
Corporation. Digital Equipment Corporation assumes no responsibility
for any errors that may appear in this document.
The software described in this document is furnished under a license
and may only be used or copied in accordance to the terms of such
license.
Digit~l Equipment Corporation assumes no responsibility for the use

or reliability of its software on equipment that is not supplied by
Digital.

@ 1975 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
DECOS
UNIBUS
COMPUTER LABS
COM TEX
DDT
DECCOMM

DECsystem-10
DECtape
DIBOL
EDU SYSTEM
FLIP CHIP
FOCAL
INDAC
LAB-8

MASS BUS
OMNIBUS
OS/8
PHA
RSTS
RSX
TYPESET-8
TYPESET-11

LIMITED RIGHTS LEGEND
Contract No.
Contractor or Subcontractor:

Digital Equipment Corporation

All the material contained herein is considered limited rights data
under such contract.

1 /76-15

CONTENTS
Page
PREFACE

CHAPTER

vii
0.1
0.2

MANUAL OBJECTIVES AND READER ASSUMPTIONS
STRUCTURE OF THE DOCUMENT
ASSOCIATED DOCUMENTS

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

1.1
1. 2
1. 2 .1
1.2.1.1
1.2.1.2
1.2.1.3
1. 2. 2
1.2.2.1
1.2.2.2
1.2.2.3
1.2.2.4
1.2.2.5
1.2.2.6
1. 3
1. 3 .1
1. 3. 2
1. 3. 3
1.3.3.1
1. 3. 4
l. 3. 5
1. 3. 6
1. 3. 7
1. 4
1. 4 .1
1. 4. 2
1.4.2.1
1.4.2.2
1.4.2.3
1.4.2.4
1. 5
1. 5 .1
1. 5. 2
1. 5. 3
1.5.3.1
1.5.3.2
1.5.3.3
1.5.3.4
1. 6
1. 7
1. 7 .1

I/O PHILOSOPHY
STRUCTURE
I/O Hierarchy
FCS
QIO

Executive I/O Processing
Role of I/O Driver in RSX-llM
Device Interrupt
I/O Initiator
Device Timeout
Cancel I/O
Power Failure
Summary
DATA STRUCTURES
The Device Control Block (DCB)
The Unit Control Block (UCB)
The Status Control Block (SCB)
Interrelation of the I/O Control Blocks
The I/O Packet
The I/O Queue
The Fork List
The Device Interrupt Vector
EXECUTIVE SERVICES
Pre-Driver Initiation Processing
Post-Driver Initiation Services
Interrupt Save ($INTSV)
Get Packet ($GTPKT)
Create Fork Process ($FORK)
I/O Done ($IODON)
PROGRAMMING STANDARDS
Process-Like Characteristics of a Driver
Programming Conventions
Programming Protocol
Processing at Priority 7 with Interrupts
Locked Out
Processing at the Priority of the Interrupting
Source
Processing at Fork Level
Programming Protocol Summary
FLOW OF AN I/O REQUEST
DATA STRUCTURES AND THEIR INTERRELATIONSHIPS
Data Structures Summary

iii

vii
viii

1-1
1-1
1-1
1-1
1-2
1-3
1-3
1-4
1-4
1-4
1-4
1-4
1-4
1-5
1-5
1-6
1-6
1-6
1-7
1-8
1=8
1-9
1-9
1-9
1-10
1-10
1-11
1-11
1-11
1-11
1-12
1-12
1-12
1-12
1-13
1-13
1-14
1-14
1-14
1-17
1-19

CONTENTS (Cont. )
Page
CHAPTER

2
2.1
2.2
2.3
2.3.1
2.3.1.1
2.3.1.2
2.3.1.3
2.3.1.4
2.3.2
2.3.3
2.4
2.4.1

CHAPTER

2-1
2-1
2-1
2-2
2-2
2-2
2-3
2-4
2-4
2-4
2-5
2-7

2.5.1
2.5.2

INTRODUCTION
OVERVIEW
INCORPORATING A DRIVER - DETAILS
Creating the Data Structure
Required Device Control Block (DCB) Fields
Required Unit Control Block- (UCB) Fields
Required Status Control Block (SCB) Fields
Source Format of the Data Structure
Creating the Driver Source Code
Incorporating the User-Written Driver
DRIVER DEBUGGING
Rebuilding and Re-incorporating the User
Driver
Re-Assembly
Updating the Executive Object Module Library
Rebuilding the Executive
Incorporating Tasks into the System
Bootstrapping the New System
RSX-llM Executive Debugging Tool
Fault Isolation - Some General Hints
Introduction
Fault Classifications
Immediate Servicing
Other Pertinent Fault Isolation Data
Fault Tracing
SAMPLE OUTPUT FROM CRASH AND PANIC DUMP
ROUTINES
Crash Output
Panic Dump Output

WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS

3-1

3.1
3.1.1
3.1.1.1
3.1. 2
3.1.2.1
3.1.2.2
3.1. 3
3.1.3.1
3 .1. 4
3.1.4.1

DATA STRUCTURES
The I/O Packet
I/O Packet Details
The Device Control Block (DCB)
DCB Details
I/O Function Codes
The Status Control Block (SCB)
SCB Details
The Unit Control Block (UCB)
UCB Details

3-1
3-2
3-4
3-9
3-10
3-15
3-16
3-17
3-19
3-21

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS

4-1

4.1
4.2

SYSTEM-STATE REGISTER CONVENTIONS
SERVICE CALLS

4-1
4-1

INCLUDING A USER-WRITTEN DRIVER - AN EXAMPLE

5-1

5.1
5.2
5.2.1
5.2.2

DEVICE DESCRIPTION
DATA STRUCTURE AND DRIVER SOURCE
The Data Structure
Driver Code

5-1
5-2
5-2
5-5

2.4.1.1
2.4.1.2
2.4.1.3
2.4.1.4
2.4.1.5
2.4.2
2.4.3
2.4.3.1
2.4.3.2
2.4.3.3
2.4.3.4
2.4.3.5
2.5

CHAPTER

INCORPORATING USER-WRITTEN DRIVERS INTO
RSX-llM

2-7
2-7
2-7
2-8
2-8
2-8
2-9
2-10
2-10
2-10
2-ll
2-12
2-13

2-19
2-19
2-19

CONTENTS (Cont. )
Page
APPENDIX A
A. l
A. 2

APPENDIX B

DEVELOPMENT OF THE ADDRESS DOUBLEWORD

A-1

INTRODUCTION
CREATING THE ADDRESS DOUBLEWORD

A-1
A-1

SYSTEM DATA STRUCTURES AND SYMBOLIC
DEFINITIONS

B-1
INDEX-1

INDEX

Page
Figure

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

I/O Control Flow
DLll Disk I/O Data Structure
RKll Disk I/O Data Structure
I/O Data Structure
Unmapped System Header
Mapped System Header
Stack Structure - Internal SST Fault
Stack Structure - Non-Normal SST Fault
Stack Structure - Data Items on Stack
I/O Packet Format
QIO Directive Parameter Block (DPB)
Device Control Block
Status Control Block
Unit Control Block

1-2
1-7
1-8
1-18
2-14
2-15
2-16
2-17
2-18
3-3
3-7
3-9
3-16
3-20

TABLES
Page
Table

3-1

Standard I/O Function Codes

3-15

PREFACE

0.1

MANUAL OBJECTIVES AND READER ASSUMPTIONS

The goal of this manual is to provide all the information necessary to
successfully 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 non-conventional. Complexity of device servicing
requirements sets the dividing line, a line not easily established in
go, no-go terms.
The manual assumes the reader fully understands the device for which
he is writing a driver, and has complete familiarity with the PDP-11
computer, its peripheral devices, and the software supplied with an
RSX-llM system. Complete familiarity implies an in-depth exposure to
the following RSX-llM manuals (see section 0.3 below):
i.

System Generation Manual

I/O Drivers Reference Manual

Executive Reference Manual

Utilities Procedures Manual

I/O Operations Reference Manual

Although this manual is organized tutorially, our reader class
assumptions require a system programmer level of expertise; thus, the
manual will not contain definitions of data processing terms and
concepts familiar to senior level professionals.
As adjuncts to this manual, the reader is 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 the source code contained in the files
IOSUB, SYSXT, DRQIO, BFCTL, and DRDSP {stored under ore [11,10] on the
source disk) should prove beneficial.

vii

0.2

STRUCTURE OF THE DOCUMENT

This document cascades from chapter
levels of implementation detail.

chapter

toward

increasing

Chapter 1 is a functional description of the RSX-llM device level
system, covering both data structure and code requirements.

I/O

Chapter 2 details how a user-written driver is incorporated
system.

the

into

Together, Chapters 1 and 2 provide a complete understanding of the
requirements that must be met in creating a system which contains a
user-written driver.
Chapter 3 provides programming level details on I/O data structures.
Chapter 4 covers all the I/0-related Executive services.
Chapter 5 is an example of a user-written driver.
Appendix A describes the Address Doubleword.
Appendix B lists system
system data structures.

0.3

macros

which

supply

symbolic

offsets

for

ASSOCIATED DOCUMENTS

Other manuals closely allied to the purposes of this document are
described briefly in the RSX-llM/RSX-llS Documentation Directory,
Order No. DEC-11-0MUGA-B-D. The 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.

viii

CHAPTER 1
THE RSX-llM I/0 SYSTEM - PHILOSOPHY AND STRUCTURE

1.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, a substantial effort has been expended in the design of
RSX-llM's data structures. These structures are used to drive the
centralized routines; the effect is to substantially reduce the size
of individual I/0 drivers. The table structures, of course, 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, has enabled RSX-llM to
meet its original memory and performance goals.
In a DEC-released system, DEC-supported drivers are included into the
user-tailored system via system generation queries. User-written
drivers require the user to create object files for I/O data
structures and driver code.
These object files are built and
incorporated during the generation of the user-tailored system.

1.2

STRUCTURE

This section:

1.2.1

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

1-1

THE RSX-llM I/0 SYSTEM - PHILOSOPHY AND STRUCTURE
NON-PRIVILEGED
~USER

I/O
REQUEST

FCS

DEVICE
INDEPENDENT

QIO DIREC

DEVICE
DEPENDENT
~*-----~~~~

USER STATE

SYSTEM STATE
QIO DIREC
SERVICE

EXEC COMM
I/O PROC Is

1
DEVICE INTERRUPT_.

I/O
DRIVER

Figure 1-1
I/O Control Flow

1.2.1.1 FCS - At the top of the hierarchy is File Control Services
(FCS} which provides device-independent access to devices included in
a given system configuration. The user task has two levels with which
to interface with FCS; Get/Put and Read/Write. Get/Put facilitates
the 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.
The discussion of FCS has been purposely terse because its existence
is completely transparent to the driver and rarely concerns the writer
of a conventional driver. FCS will accept a user request, interpret
it, and perform all operations necessary to carry out the user
request.

1-2

THE RSX-llM I/O SYSTEM - PHILOSOPHY AND STRUCTURE
1.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 more direct
control over devices which are connected to a system and for which an
I/O driver exists.
The QIO directive forces all I/O requests from
user task's to go through the Executive. The Executive prevents tasks
from destructively interfering with each other and with the Executive.

1.2.1.3 Executive I/O Processing - The processing of I/O requests
the Executive I/O system is accomplished via:
1.

File Control Primitives (FCP), and

A collection of Executive components consisting of:
a.

QIO directive

I/0-related subroutines, and

The I/O drivers.

processing~

FCP is a privileged task;
it is responsible for maintaining the
structure and integrity of data stored on file-structured volumes. It
maps virtual block numbers to logical block numbers, extends files,
and makes volume protection checks.
No direct connection exists
between FCP and a driver.
Logical blocks are 256 words in length; it is the responsibility of
the driver to convert a logical block number into a physical address
on a file-structured device.
Within the system, FCP exists as a privileged task, possessing all the
attributes of privileged tasks. FCP requires a partition in which to
execute.
Drivers,
on
the
other
hand,
are
specialized,
permanently-resident system processes, not tasks.
The I/O services provided by the Executive consist of OIO 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 will be examined in
considerable detail later.
Executive subroutine services and QIO
directive processing are shown as distinct components but are, in
fact, both parts of the Executive.
These are the routines which
centralize common driver functions, thus eliminating duplicate code
sequences among drivers.
The description of the I/O hierarchy and interrelationships is now
sufficiently complete to allow a more direct consideration of the role
fulfilled by an I/C driver in an RSX-llM system.

1-3

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

Role of I/O Driver in RSX-llM

Every driver has five entry points:
1.

Device interrupt*;

I/O initiator;

Device timeout;

Cancel I/O, and

Power failure.

The first entry point is entered via a hardware interrupt;
the last
four are entered by calls from the Executive. These entry points are
descriptive enough in and of themselves to provide direct insight into
the responsibilities of a driver; the functional details follow.

1.2.2.1 Device Interrupt - Control is passed to this entry point when
a device previously initiated by the driver has completed an I/O
The
operation and has caused an interrupt in the central processor.
connection to the driver in this instance is direct; the Executive is
not involved.

1.2.2.2 I/O Initiator - This entry point is called by the Executive
to inform the driver that work for it is waiting to be done. In
effect, this is a wakeup signal for the driver.

1.2.2.3 Device Timeout - When a driver initiates an I/O operation, it
establishes a timeout count. If the function does not complete within
the specified time interval, the Executive will note the time lapse
and call the driver at this entry point.

1.2.2.4 Cancel I[O - A number of circumstances arise within the
system which require that a driver terminate an in-progress I/O
operation. When this 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.

1.2.2.5 Power Failure - Two conditions can initiate a call to the
driver when power is restored following a power failure. First, the
power failure entry point is automatically called by the Executive any
time the controller is busy. Secondly, 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. If power fails, and the conditions
* A device may trigger more than one distinct interrupt entry.
exa~ple, a full duplex device would have two.

1-4

For

THE RSX-llM I/O SYSTEM - PHILOSOPHY AND STRUCTURE
exist for power failure code initiation, the ExecutLve will so inform
the driver by calling it at the power failure entry point when power
is restored. Frequently, a driver's response to a power failure or 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, since
recovery will eventually be effected via the timeout entry point.
Also, when the system is bootstrapped, a power failure interrupt is
simulated. This simulation gives drivers the opportunity to carry out
any pre-operational initialization deemed appropriate.

1.2.2.6 Summary - Role of an I/O Driver - Functionally, the driver in
RSX-llM has responsibility for:

Servicing device interrupts;

Initiating I/O operations;

Cancelling in-progress I/O operations, and

Performing device-related functions upon
timeout or power failure.

the

occurrence

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 via Executive calls. A driver never
receives a QIO request directly, and has no direct interaction with
FCP.
At this point, a functional description of the role of an I/O driver
in RSX-llM has been presented. In the next three sections, the
Data structures,
Executive services, and

Programming conventions and protocol
related to I/0 drivers will be discussed. The chapter closes with a
section discussing the flow of an I/O request, from the issuance of a
QIO directive to the delivery of the requested data to the task. Data
structure interrelationships are also covered.

1.3

DATA STRUCTURES

There are seven data structures with which an I/O driver interacts:
1.

Device Control Blocks (DCB' s);

Unit Control Blocks (UCB's);

Status Control Blocks (SCB's);

The I/C Packet;

The I/O Queue;

1-5

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

The Fork List, and

Device Interrupt Vectors.

The first four are most important to the driver, since it is via 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/0 Queue and the Fork List are actually Executive
data
structures, but to properly understand the complete interaction of an
I/0 driver with the Executive, their role in the system will also be
described.
The I/O Queue is a list of I/O Packets which are built by
the QIO directive, principally from information in the caller's
Directive Parameter Block (DPB) .
Entry to a driver following a device interrupt is direct via the
appropriate hardware device interrupt vector. Since the driver writer
is responsible for properly establishing this vector, it is included
in the data structures associated with a driver.

1.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 a 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 DCB's in a system form a
forward-linked list, with the last CCB 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.

1.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 done exclusively by either the
Executive or driver, not both.

1.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 a controller per line since all lines may transfer
in parallel. Most of the information in the SCB is dynamic. The SCB
is used by both the Executive and the driver.

1-6

THE RSX-llM I/O SYSTEM - PHILOSOPHY AND STRUCTURE
1.3.3.1 Interrelation of the I/O Control Blocks - Without explicit
details on the contents of the DCB, UCB, and SCB, their relationships
are difficult to correlate. This section is intended to represent
their interrelationship without entering into the detailed contents of
the control blocks, leaving such a discussion to be pursued in Chapter
3.

Figure 1-2 shows the data structure that would result for three LA30
DECwriters interfaced via DLll controllers. The structure requires
one DCB, three UCB's, and three SCB's, since the activity on all three
units can proceed in parallel.
In Figure 1-3, the internal data structure for an RKll disk controller
with three units attached is depicted. Note that only one SCB exists
because only one of the three units may be active at any given time.

J::l
l
l
I

1
UCB

Figure 1-2
8Lll Disk I/O Data Structure

1-7

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

•
UCB

UCB

SCB

~
~

Figure 1-3
RKll Disk I/O Data Structure

Taken together, Figures 1-2 and 1-3 illustrate the strategy underlying
the existence of three basic I/0 control blocks. There need be only
one DCB per device type.
The SCB, defending on the degree of
parallelism
that
is desired or possible, can exist for each
device-unit, or only once for
controllers
servicing
multiple
device-units.
As will be seen later, this data structure has the effect of providing
considerable flexibility in configuring I/0 devices, and, due to the
information density in the structures themselves,
substantially
reduces the code requirements of the associated drivers.

1.3.4

The I/0 Packet

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

1.3.5

The I/O Queue

Each time an I/0 request is made, the Executive is entered, and, if a
series of validity checks proves successful, the Executive will
generate a data structure called an I/O Packet.
The Executive will
then insert the packet into a device specific, priority-ordered list
of rackets called the I/O Queue. Each I/O Queue's listhead is located
in the SCB to which the I/O requests apply.
When a device driver needs work, it requests the Executive to de-queue
the next I/0 Packet and deliver it to the requesting driver. The
driver never directly manipulates the I/O Queue.

1-8

THE RSX-llM I/0 SYSTEM - PHILOSOPHY AND STRUCTURE
1.3.6

The Fork List

All drivers in RSX-llM can easily be written as multi-controller
drivers;
all drivers may run in parallel with other drivers and with
themselves. When independent processes may execute in parallel, a
method for synchronizing their access to common data bases is
essential.
At the Executive level in RSX-llM, a process
may
synchronize its access to a data base by requesting the Executive to
transform it into a fork process.
Such an operation creates a
specialized context for the process and places it into a list called
the Fork List. Processes in the Fork List are granted FIFO access to
common data bases. Once granted access to the data base, the process
is guaranteed control of the data base until it relinquishes it by
exiting.
Not until the process exits will the next process in the
Fork List be granted data base access.
Thus, it is via the fork
mechanism and the associated Fork List that access to shared system
data bases is synchronized. Essentially, of the two basic techniques
available for data base access synchronization:
1.

Interrupt lockout, and

Access queuing,

~SX-llM

1.3.7

has chosen the latter.

The Device Interrupt Vector

The device interrupt vector is initialized when defining
data
structures,
and
not dynamically.
This makes the driver code
independent of device register address assignments and 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 7.
See lines 81 thru 85 in section 5.2.1
(section 5.2.1 contains the
source code for the data structure of a sample driver).

1.4

EXECUTIVE SERVICES

The I/0-driver-related services provided by the Executive 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 this processing is to extract from the driver all I/O
support functions not directly related to the actual issuance of a
function request to a device.
If the outcome does not.result in the
queueing of an I/O Packet to a driver, the driver is unaware that a
QIO directive was ever issued. As will be shown shortly, many QIO
directives do not result in the initiation of an I/O operation.

1-9

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

Pre-Driver Initiation Processing

QIO directive processing performs the following pre-driver
services:

initiation
is

legal.

Checks if the supplied logical unit number
If not, the directive is rejected.

If the LUN is valid, check if 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 land 2 are successful, the Executive traces down
the redirect chain to locate the correct UCB to which the I/0
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 subject
event flag is reset, and the IOSB is cleared.

Obtains 18-words of dynamic
storage
and
device-inderendent portion of an I/O Packet.

(LUN)

builds

the

If steps l thru 5 succeed, the directive status is set to +l.
Note that directive rejections in any of the above steps
completely transparent to the driver.
6.

are

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 I/0 Finish routine ($IOFIN)
is called.
$IOFIN sets status and clears the QIO request
from the syster.i.

If the requested function does not re~uire a call to the
driver, appropriate actions are handled by the Executive and
$IOFIN is called.

If all I/O Packet checks are positive, the I/O Packet is
placed in the driver queue according to the priority of the
requesting task.

1.4.2

Post-Driver Initiation Services

Gnce a driver is given control following an I/0 interrupt or by the
Executive itself, a number of executive services are available lo I/O
drivers. These services are discussed in detail in Chapter 4.
There are, however, four
Executive services that merit special
emrhasis, since they are used by virtually every driver in the system:
1.

Interrupt Save ($INTSV);

Get Packet ($GTPKT);

1-10

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

Create Fork Process ($FORK), and

I/0 Done ($!ODON).

1.4.2.1 Interrupt Save
($INTSV) - Interrupts from a device
are
fielded directly by the driver.
Immediately following the interrupt,
the driver
is operating at hardware priority level
7 and
is,
therefore,
non-interruptible.
If
the driver
needs a lengthy
processing cycle (greater than lOOus)
to process the
interrupt or
requires registers,
it should call $INTSV;
this has the effect of
stacking external interrupts, altering
the hardware priority, and
providing the calling routine with two free registers to use in
processing the interrupt. More will be said about $INTSV in section
1.5.

1.4.2.2 Get Packet ($GTPKT) - The Executive, after it has queued an
I/O Packet, calls the appropriate driver at its I/0-initiator entry
point.
The driver then immediately calls the Executive routine $GTPKT
to obtain work. When 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.
If the SCB related to the device is already busy,
$GTPKT so
informs
the driver,
in which case the driver immediately returns control to
its caller.
To the driver writer, note that no distinction exists between no-work
and SCB busy,
since,
in either case, an I/O operation cannot be
initiated.

1.4.2.3 Create Fork Process <SFORK) - Synchronization of access to
shared data bases is accomplished via a fork process. When a driver
fork process;
needs to access a shared data base, it must do so as a
the driver creates a fork process by calling $FORK.

1.4.2.4 I/O Done ($!ODON) - At the completion of an I/O request, a
number of centralized checks and additional functions are performed:
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.
$!ODON also declares a significant event, resets the SCB and device
unit status to
idle, and releases the dynamic storage used by the
completed I/O operation.

1-11

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

PROGRAMMING STANDARDS

RSX-llM I/O drivers are integral components of the RSX-llM Executive.
As such, 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 programmers to
incorporate I/O drivers into their systems. Failure to observe the
internal conventions and protocol will result in poor service and
reductions in system efficiency.

1.5.l

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,
multi-unit, multi-controller)
and with other Executive processes
executing in parallel.
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.

1.5.2

Programming Conventions

The programming conventions used by RSX-llM system components are
identical to those described in Appendix E of the RSX-11 MACR0-11
Reference Manual. Users preparing I/O drivers for incorporation into
an RSX-llM system are strongly urged to adhere to these conventions.

1.5.3

Programming Protocol

Since 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.
When a device interrupts, an I/O driver is entered directly, usually
calling $INTSV for common save and state switching services.
(Two
states, user and system, exist in RSX-llM; the conventions discussed
in this manual generally refer to processes running from the system
state, since drivers operate entirely in system state.) At the
completion of the services provided by $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 if it is necessary to
switch tasks). The Fork Processor linearizes access to shared system
data bases.
The details of all these routines will be covered in
Chapter 4.
The interrupt vectors in lower 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

1-12

THE RSX-llM I/O SYSTEM - PHILOSOPHY AND STRUCTURE
the low-order four 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
data base source must set up the 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:
1.

At priority 7 with interrupts locked out;

At the priority of the interrupting source; thus, interrupt
levels greater than the priority of the interrupting source
are permitted, or

At fork level which is at priority 0.

1.5.3.1 Processing at Priority 7 with Interrupts Locked Out - By
internal convention, processing at this level (interrupt processing
routine level 1) is limited to lOOus. If processing can be completed
in this time, then the driver simply dismisses the interrupt by
executing an RTI instruction. The interrupt has been processed and
dismissed with minimal overhead.

1.5.3.2 Processing at the Priority of the Interrupting Source - If
the driver requires additional processing time or the use of general
purpose registers, it calls the routine $INTSV (Interrupt Save).
The
priority at which the caller is to run immediately follows the call to
$INTSV. The driver should set this priority level to that of the
interrupting source.
$INTSV save uses the specified priority to set up the interrupt
routine such that it is interruptible by priorities higher than that
of the interrupting source and conditionally switches to system state
if the processor is not already in system state.
The saving of general registers

registers for the driver.
that assumes the driver will
during interrupt processing.
additional registers it uses.
from $INTSV should not exceed

.rv:1:
o.nu
.re:>
is aunt! c.u free Lrn=be
It is an internal programming convention
not require more than two registers
If it does, it must save and restore any
Processing time following the return
500us*.

In actual practice, every driver in the system calls $INTSV on ·every
interrupt after executing perhaps 0 or 1 instructions (such as saving
the PS if more than one controller is being driven}. This is due to
two factors:
1.

It is difficult to service an interrupt without
registers.

one

two

* The 500us period is a guideline. The shorter the period of time a
realtime executive spends at an elevated priority level, the less
responsive the system will be to devices of lower priority. This 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.

1-13

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

Most interrupt code may safely be executed at the priority of
the interrupting source, which is, of course, desirable.

l.S.3.3 Processing at Fork Level - A driver calls $FORK to meet the
requirement to become fully interruptible (so as to conform to the
SOOus time limit) or to access a shared system data base. $INTSV must
be called prior to calling $FORK.
By virtue of calling $FORK, the routine is now at processing level 3
(interruptible)
and its access to system data bases is strictly
linear. The Fork List is a list of system routines waiting to
complete their processing, in particular, waiting to access a shared
system data base. At fork level, all registers are available to the
process, and R4 and RS retain the contents they had on entrance to
$FORK.

l.S.3.4 Programming Protocol Summary - Drivers are required to adhere
to
the
following
internal conventions when processing device
interrupts~

1.6

Registers are not available for use unless $INTSV is called
or
the
driver
explicitly
performs save and restore
operations. If $INTSV is called, the use of any registers,
except R4 and RS, requires that these registers be saved and
restored.

Non-interruptible
processing
must
not
exceed
instructions,
and
processing
at the priority
interrupting source must not exceed SOOus.

twenty
of the

All modifications to system data bases must
fork process.

via

done

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 the QIO
directive is actually issued. The following assumptions apply:
1.

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 system will be the sample request
under discussion.

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

1-14

THE RSX-llM I/O SYSTEM - PHILOSOPHY AND STRUCTURE
The I/0 flow proceeds as described below:
l;

[Task issues QIO directive]
All Executive directives are called via EMT 377. The effect
of the EMT is to cause the processor to stack the PS and PC
and pass control to the Executive's directive processor.

l~.

[First level validity checks]
The QIO
po inter.

directive processor validates the LUN and
Invalid data results in directive rejection.

UCB

lb. [Redirect algorithm]
Since the UCB may have been dynamically redirected via an MCR
Redirect
command,
~~v
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). If valid, the event flag is reset and the I/O
status block is cleared.
2.

[Obtain storage for and create an I/O Packet]
QIO directive processing now acquires an 18-word block of
dynamic storage for use as an I/O Packet. If the 18-words of
storage are obtained, the directive is accepted. It inserts
data items into the packet which are subsequently used by
both the Executive and 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:
a)

Control;

No-op;

File, or

Transfer.

Control functions, with the exception of Attach/Detach, are
queued to the driver. No-op functions do not result in data
transfers and are performed by the Executive without calling
the driver.
A file function may require processing by the file system.
More typically, the request is a read or write virtual
function which is transformed into a read or write logical
function without requiring file system intervention. When
transformed into a read or write logical, it becomes a
transfer function (read and write logical are, by definition,
transfer functions) .

1-15

THE RSX-llM I/O SYSTEM - PHILOSOPHY AND STRUCTURE
Transfer functions are address checked and queued to the
proper driver.
Then the driver is called at its initiator
entry point.
4.

[Driver processing]

4a. [Request work]
To obtain work, the driver calls Get Packet ($GTPKT). $GTPKT
will either provide work, if it exists, or inform the driver
that no work is available, or the SCB is busy;
if no work
exists, the driver returns to its caller.
If work is
available, $GTPKT will set the device controller and unit
busy, dequeue an I/O request packet, and return 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 interrupt
driven.
5.

[Interrupt processing]
When a previously-issued I/O operation interrupts,
the
interrupt causes a direct entry into the driver, which
processes it according to the programming protocol described
earlier.
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
(4b). When the processing of an I/O request is complete,
$IODON is called.

[ I/O Done processing]
$IODON removes the device unit and controller busy status,
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
$IODON returns to the driver. The driver branches to its
initiator entry point looking 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
process which will issue a QIO directive, starting the I/O
flow anew.

1-16

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

DATA STRUCTURES AND THEIR INTERRELATIONSHIPS

This section presents all the individual contro.J.. blocks, 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);

$DEVTB word, the Device Control Block (DCB), and
Dispatch Table (DDT};

Unit Control Block (UCB);

Status Control Block (SCB), and

Volume Control Block (VCB).

the

Driver

Figure 1-4, which will provide 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 guide the reader through the data
structures.

1-17

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

r7\

SYSCM

$DEVHD:

\._V

~-1
,_________,,

/D
+ DCB

DCB

I
L_ _

TASK

--I

--~

.
I

---- • • •

I
I

"'..

DDT

I/O QUEUE

L_J

1---

HEADER
UCB's

SCB

Figure 1-4
I/O Data Structure

The Task Header, one of two independent entries in the I/O
data structure, is constructed during the task-build process.
The 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 and places 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.

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 where
the file resides.

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.

$DEVTB is a word located in system common (SYSCM) and is the
other independent entry in the I/O data structure. $DEVTB
points to a singly-linked, uni-directional list of Device
Control Blocks (DCB's). Each device type in a system has an
associated DCB. At least one DCB exists per device type.
The DCB list is terminated by a zero in the link word.
Linked to each DCB is a Driver Dispatch Table (DDT). The DDT
contains the addresses of the driver's four callable entry
points.
1-18

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

A key data structure is the Unit Control Block (UCB).
All
the UCB's associated with a DCB appear in consecutive memory
locations. During internal processing of an I/O request, RS
contains the address of the related UCB, and it is via
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. A driver services a fixed set of UCB's.
When servicing a request for one of its UCB's, it is unaware
of whether I/O was issued directly to the UCB or whether it
was issued to a UCB 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.

One Volume Control Block (VCB) exists for each MOUnted volume
in a system.
The VCB is used to maintain volume-dependent
control information.
It contains pointers to the File
Control Block (FCB} and Window Block (WB) used to 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. All unique FCB's 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 which 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
his
application
requires~

1.7.l

Data Structures Summary

The writer of a conventional driver never manipulates the entire I/O
data structure. In fact, he is almost exclusively involved only with
the I/O Packet, the UCB, and the SCB. The entire structure has been
presented to add depth to the driv~r wr~ter's under~ta~d~ng of the I/0
system, to emphasize the relationships _among _individu~l c?ntrol
blocks, and to further clarify the role a given driver fulfills in the
processing of an I/O request.

1-19

CHAPTER 2
INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM

2.1

INTRODUCTION

Though explicit details for writing a driver have not been presented,
enough conceptual information now exists to consider incorporating a
user driver into a system. This follows from the fact that many
considerations for writing a driver are most easily presented within
the context of the process followed for installing it.
The reader is already assumed to be familiar with the
Generation Manual.

RSX-llM

System

Taken together, Chapters land 2 present a comprehensive overview of
the relevant considerations for undertaking the implementation of a
driver.

2.2

OVERVIEW

The user who has decided to add a driver to RSX-llM has concomitantly
shared the responsibilities for the integrity of the Executive.
Errors in this code can easily cause a system failure and bring to a
halt all user service.
The basic steps involved in creating
driver are as follows:

and

installing

Bootstrap the source disk and run Sysgen Phase 1.

Bootstrap the object disk.

Create the assembly source for the driver and its
data structures.

Run Sysgen Phase 2.

2-1

user-written

associated

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
At the completion of Sysgen Phase 2, the user has a system with the
user-written driver integrated into it. Since it is anticipated that
a debugging sequence will be required to shake down the driver, the
following sequence will result in an updated driver being incorporated
into the existing system:
1.

Correct and re-assemble the driver and/or data structures.

Run the Librarian to replace the
RSXllM.OLB with the repaired ones.

Rebuild the Executive using RSXBLD.CMD.

Using Virtual MCR, rebuild the system.

Bootstrap the system.

old

object

modules

When adding a user-written driver to the system, the driver may be
assembled to include padding space for possible expansion during the
debugging process.

2.3

INCORPORATING A DRIVER - DETAILS

2.3.l

Creating the Data Structure

The data structures associated with I/O drivers will be detailed in
Chapter 3.
Of the structures discussed, only three require assembly
source:
1.

The DCB;

UCB' s, and

SCB Is.

Within these control blocks, only those items which are static or
require initialization are supplied in the source description. Listed
below is an overview of the data fields the driver writer will be
required to supply in the assembly source of his driver's data
structure.

2.3.1.1 Required Device Control Block (DCB) Fields - The required DCB
fields are described below:
D. LNK

Link to next DCB.
This field will be zero if this is the last DCB.
If
the user is incorporating more than one user-written
driver at one time, then this field should point to
another DCB in the DCB chain.

D.UCB

Address of the first UCB associated with this DCB.

D.NAM

Two-character ASCII generic
must be unique.

2-2

device

name.

This

name

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
D.UNIT

Highest and lowest unit numbers controlled by this DCB.

C.UCBL

Length of a UCB.
If a given DCB has multiple UCB's, all UCB's 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 will contain a global reference to the label
associated with this table.

D.MSK

I/0 function masks
The user 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
four
words.
Functions 0-15 are covered by the first group, and
functions 16-31 by the second.

2.3.1.2 Reauired Unit Control Block (UCB) Fields - The
fields are described below:

required

U. DCB

Backpointer to the associated DCB.

U.RED

Initially contains
redirect pointer).

U.CTL

Control bits that must be established
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.cvn

Characteristics word l.
3) applies.

U.CW2

Driver dependent.

U.CW3

Driver dependent.

U.CW4

Default buffer size.

u.SCB

Address of the SCB for this UCB.

U.ATT

TCB address of attached task.

the

2-3

address

UCB

this

UCB

(i.e.,

the

driver

Standard description

(Chapter

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
2.3.1.3 Required Status Control Block (SCB) Fields - The required SCB
fields are described below:
S.LHD

I/O Queue listhead.

S. PIH

Priority of interrupting source.

S.VCT

Interrupt vector address divided by 4.

S.ITM

Initial timeout count.

S.CON

Controller index (i.e., controller number multiplied by
2).

S.STS

Controller status.

S.CSR

Address of control and status register.

2.3.1.4 Source Format of the Cata Structure - A single DCB can
service multiple UCB's and SCB's. The existence of multiple UCB's and
SCB's is determined by the actual device subsystem being supported by
a given driver on the user's operational hardware configuration.
Figures 1-2 and 1-3 illustrate possible DCB, UCB, and SCB structural
relationships.
Typically,
in writing a data structure source
(DEC-supplied RSX-llN drivers use this scheme), the DCB is placed
first, followed by the UCB (s), followed by the SCB (s).

2.3.2

Creating the Driver Source Code

Creating the source code to drive a device involves the following:
1.

Thorough reading and understanding of this manual;

Detailed familiarization with the
operational characteristics;

Determining the level of support required for the device;

Creating the data structure source code for the device;

Determining actions to be taken
points:

Initiator;

Cancel I/O;

Timeout;

Power foil, ond

Interrupt.

physical

the

device

~ive

and

driver

its

entry

Creating the driver source code.

Source code for the driver and data structure should be created on the
object disk under UIC [200,200].

2-4

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
2.3.3

Incorporating the User-Written Driver

Incorporating a driver is
generation process.
Phase
which condition Phase
2
Specifically, the query

accomplished via the standard sys~em
l
of system generation includes queries
for
user-written
driver
inclusion.

ARE YOU PLANNING TO INCLUDE A usgR WRITTEN DRIVER? [Y/N]:
if answered affirmatively, results in a second query
WHAT IS THE ADDRESS OF THE HIGHEST DEVICE INTERRUPT VECTOR? [O]:
The answer to which is required so Phase 1 can allocate sufficient
vector space to avoid run-time destruction of the system stack.
At the completion of Phase l,
execution of Phase 2, the query

Phase

the

*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
the driver writer through the process of adding his 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.
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, viz.,
[1,20]
for an unmapped system and [l,24] for a mapped system.
>*DO YOU WISH TO ADD USER WRITTEN DRIVER(S) TO THE EXEC? [Y/N]:X
>SET /UIC=[200,200]

>;
>; WE WILL PAUSE WHILE YOU ASSEMBLE YOUR DRIVER(S) AND USRTB
THE EXEC ASSEMBLY PREFIX FILE RSXMC.MAC IS ALREADY
>; LOCATED UNDER UIC [200,200]. ASSUMING YOUR DRIVER(S) NAME IS
>; XXDRV, WHERE XX IS THE DEVICE NAME (E.G., DK) THE FOLLOWING
>; COMMANDS WILL ASSEMBLE THE DRIVER(S) AND THE USRTB t•lVLJUl..Jw •
>;
>;
>RUN $MAC
>;
MAC>XXDRV=[l,l]EXEMC/ML,[200,200]RSXMC,XXDRV
>;
MAC>USRTB=[l,l]EXEMC/ML, [200,200]RSXMC,USRTB
>;
MAC>"' Z

>; MODULE.

&Jr f""\T"'\TTT

>;
>
AT. -- PAUSING. TO CONTINUE TYPE "RES ... AT."
>RUN $MAC
MAC>XXDRV=[l,l]EXEMC/ML, [200,200]RSXMC,XXDRV
MAC>USRTB=[l,l]EXEMC/ML,[200,200]RSXMC,USRTB
MAC> :.z_

2-5

r.i

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
>RES ... 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

>;
>SET /UIC=[l,2x]
>LBR
LBR>RSX11M/RP=[200,200]XXDRV,USRTB
LBR>"'z

>;
>; 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:

>;
>;

[l,2x]RSX11M/LB:XXDRV

>;
>; INTO THE COMMAND FILE IN THE PLACE WHERE THE
>; OTHER DRIVERS ARE REFERENCED.
XXDRV REPRESENTS THE NAME OF
>; YOUR DRIVER(S). IN ADDITION, LOCATE THE LINE IN WHICH THE
>; MODULE SYSTB IS REFERENCED AND ADD A REFERENCE TO YOUR
>; USRTB MODULE IMMEDIATELY AFTER IT.
E.G.:

>;
>;

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

>;
>; THEN LOCATE THE LINE:

>·,
>;

GBLDEF=$USRTB:O

>;
>; AND DELETE IT.

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

*__)
[""f;2x]RSX11M/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

*EX
[EXIT]

This completes the user-written driver section of Phase 2, which
continues.

2-6

then

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
2.4

DRIVER DEBUGGING

Since the protection checks afforded user programs are not available
to system modules, driver errors will be more difficult to isolate
than user program errors. But conventional drivers, being modular and
short, should be easily debugged.
The following three sections
describe a set of debugging tools and guidelines that should simplify
the driver debugging process.
Section 2.4.l describes how to re-incorporate a driver into a system
after a fault has been discovered.
Section 2.4.2 describes the
Executive Debugging Tool, and Section 2.4.3 provide some general hints
for isolating faults in Executive software (of which drivers are a
subset) •

2.4.1

Rebuilding and Re-incorporating the User Driver

Rebuilding and re-incorporation involves five steps:
1.

Correction and re-assembly of the driver and/or
structures;

Updating the Executive object module library;

Rebuilding the Executive;

Running Virtual MCR to rebuild the system, and

Bootstrapping the new system.

device

data

2.4.1.1 Re-Assembly - 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:
>RUN $MAC/UIC=[200,200]
MAC>XXDRV=[l,l]EXEMC/ML, [200,200]RSXMCiXXDRV
MAC>USRTB=[l,l]EXEMC/ML, [200,200]RSXMC,USRTB
M~>ftZ

will effect the re-assembly of both the driver and data base.

2.4.1.2 Updating the
Executive
Object
Module
Library - After
re-assembly of the user driver and/or data base, the Executive object
module library must be updated.
The following
commands
will
accomplish this:
>RUN $LBR/UIC=[l,2x]*
LBR>RSX11M/RP=[200,200]XXDRV,USRTB
LBR>~

* 'x' is a '0' for an unmapped

syste~

2-7

and '4' for c ma9Ged system.

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
2.4.1.3 Rebuilding the Executive - Since an updated driver is to be
inserted, the Executive, of which the driver is a part, must be
relinked. To do this, enter the following commands:
>RUN $TKB/UIC=[l,2x]*
TKB>@RSXBLD
TKB>.:.Z..
>RUN $PIP/UIC=[l,5x]*
PIP>RSXllM.SYS/NV=RSXllM.TSK
PIP>"z

2.4.1.4 Incorporating Tasks into the System - Run Virtual MCR (VMR)
using the dialog shown as a guide. On completion, the new system is
ready for bootstrapping. The general procedure to follow is:
1.

Establish system partitions;

Release all unused space to the dynamic storage region;

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

Exit from Virtual MCR and boot in the new system.

and

VMR Example:
>RUN $VMR/UIC=[l,5x]*
! RUN VIRTUAL MCR
ENTER FILENAME:RSXllM.SYS
! VMR PROMPTS FOR FILE NAME
VMR>SET /MAIN=SYSFAR: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 8K SUB PARTITION
VMP>SET /POOL=400
ADD FREE SPACE TO POOL
VMR> INS BOO
INSTALL BOOT
VMR>INS OMO
INSTALL DISMOUNT
VMR>INS FCP
INSTALL FILE SYSTEM
VMR>INS IND
INSTALL 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

2.4.1.5 Bootstrapping the New System - The new system
bootstrapped with the MCR Boot command, as shown below:

may

now

>BOO [l,Sx]RSXllM

* 'x' is a

'O' for an unmapped system and '4' for a mapped system.

2-8

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
2.4.2

RSX-llM Executive Debugging Tool

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

(MASK) register

No $X -

(Entry Flag) registers

No $V -

(SST vector) registers

No $D -

(I/O LUN} registers

No $E - (SST data) registers

- (Effective Address Search) command
No F - (Fill Memory) command
No N - (Not word search) command
No v - (Restore SST vectors) command
No w - (Memory word search) command
No E

The X (Exit) and P (Proceed) commands have also been changed.
The X
command causes a jump to the crash reporting routine, and the P
command will permit the user to proceed if an unknown breakpoint is
encountered.
Other than the omitted features and the change in the definition of
the X and P commands, XDT is command-compatible with RSX-11 ODT, and
the RSX-11 ODT Manual may be used as a guide to its operation.
XDT may be included in a system during Phase 1 of
The query:

system

generation.

DO YOU WANT TO INCLUDE THE EXECUTIVE 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:
XDT:

followed by the prompting symbol
XDT>
on the console terminal. Breakpoints may be set at this time, and
then a G command may be given, returning control to the RSX-llM
Executive initialization code. Whenever a breakpoint is reached, a
printout similar to that of RSX-11 ODT will occur.

2-9

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
A forced entry to XDT can be executed at any time from a privileged
terminal via 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:
BE:xxxxxx
followed by the prompting symbol
XDT>
on the console terminal. Breakpoints and/or other XDT commands may
then be executed. System operation may be continued 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 is done via the consolP terminal; and thP r. (List
Memory) command can list on either the console or the line printer.

2.4.3

Fault Isolation - Some General Hints

2.4.3.l Introduction - 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, these bugs are often
difficult to diagnose.
It is extremely important that the driver
writer develop the skills and discipline needed to rapidly isolate the
source of a system failure.

2.4.3.2 Fault Classifications - Four culprits can be identified
the system faults:
1.

A user-state task has faulted such that it causes the
to fault;

The user-written driver has faulted such that it
system to fault;

The RSX-llM system software itself has faulted, or

The host hardware has faulted.

when
system

causes

the

The immediate action on the part of the driver-writer subject to one
of these errors is to determine which of these four cases is the
source of the fault. Of prime concern will be the procedures which
may help the driver writer uncover the fault source. The repair of
the fault itself is assumed to be the driver writer's responsibility.

2-10

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
Faults manifest themselves in roughly three ways (they are listed here
in order of increasing difficulty of isolation):
l.

The system displays the CRASH printout and halts or,
has been included, an unintended trap to XDT occurs.

The system halts but displays nothing.

The system is in an unintended loop.

XDT

2.4.3.3 Immediate Servicing - RSX-llM can be built
to
contain
resident crash reporting and panic dump routines; the following
discussions assume the existence of such a system.
(Note that the
minimal system will not have space for these routines). Section 2.5
contains sample listings from both crash and panic dump routines.
The immediate aim, regardless of the fault manifestation,
initiate the crash reporting and panic dump routines.

CASE 1 - The system has trapped to XDT:·
The trap may or may not be intended
(e.g., a previously set
breakpoint).
If it is not intended, type the X command, causing XDT
to exit to the crash reporting routine; if, however, the source of
the problem is suspected (for example, a recent coding change), then
pertinent data structures and code may be examined using XDT.
CASE 2 - The System Has Displayed the Crash Printout:
In this case, all the basic information describing the state of the
system has been displayed.
The actual Crash printout will be
described after learning how to invoke Panic Dump for cases 3 and 4
(see below).
CASE 3 - The System Has Halted - No Information Displayed:
Before taking any action, preserve the current PS and PC and the
pertinent device registers (i.e., 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 obtaining the PS and PC, invoke the Panic Dump Routine by
entering 40(8) in the switch register, depressing LOAD ADDR, and then
START.
The value 40(8) is the address of a JMP to the Panic Dump
all RSX-llM systems.

Routine

The Panic Dump Routine saves registers RO through R6 and then halts,
awaiting dump limits to be entered via the console switch register.
The PS is cleared when START is depressed, and the original PC is
destroyed;
thus, the importance of recording these vital pieces of
debugging information before initiating the Panic Dump Routine should
be recognized.

2-11

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
Dumps of selected blocks of memory may be obtained using the following
procedure:
1.

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

Enter the high dump limit in the console switch register and
depress 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.
To reach the same status arrived at with crash reporting in
Case 2 above, enter the dump limits 0-520(8) when the panic
dump routine first halts. This will dump 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 may
be obtained from the module LOWCR in the Executve memory
allocation map.

CASE 4 -

Sy~tem

Is in an Unintended Loop:

Proceed as follows:
1.

Halt the processor

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

After recording the PS and PC, the driver-writer may want to step
through a number of instructions in an attempt to locate the loop.
After the attempt to locate the
routine as in Case 3.

loop,

transfer

the

panic

dump

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

2.4.3.4 Other Pertinent Fault Isolation Data - Before proceeding with
the task of locating the fault, the driver-writer is strongly advised
to dump system common (SYSCM). This can be accomplished by looking
for the module SYSCM in the Executive memory allocation map and
entering the appropriate limits to the Panic Dump Routine.
SYSCM
contains a number of critical pointers and listheads.

In addition, the driver-writer should dump the dynamic storage region
and the device tables. The dynamic storage region is the module INITL
and the device tables are in SYSTB.
The driver-writer now has:
PS
PC
The Stack

2-12

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
RO through R6

Pertinent device registers
The dynamic storage region
The device tables, and
System common.
This data is a minimal requirement for effective fault isolation.

2.4.3.5 Fault Tracing - Three pointers in SYSCM are critical in fault
tracing. These pointers are described below:
$STKDP - Stack Depth Indicator
This data item will indicate which stack was being used at the
time of the crash. As will be seen, this plays an important role
in determining the origin of a fault.
The following values
apply:
+l - User (task state) stack
0 or less - System stack
If the stack depth is +l, then the user has managed to crash the
system.
In a system with brickwall protection (for example, the
mapped RSX-llM system), the non-privileged 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 first
Locating the task header provides additional data.
word in the header is the user's stack pointer the last time it
was saved.
If the user branches wildly into the Executive, it
will terminate the user task, but the system will continue to
function
(possibly erroneously).
Knowing the user's
stack
pointer provides one more link in the chain which 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, which is the
last word in the header and is pointed to by H.GARD.

2-13

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM

i....-,

RO
Rl
R2
R3

.
.

H.NLUN
H.GARD

-W

t-------n

.
H.HDLN

LENGTH IN BYTES

Figure 2-1
Unmapped System Header

2-14

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM

-h

i--------0

PC
PS

H.NLUN

H.GARD

H.HDLN

LENGTH IN BYTES

SP
Figure 2-2
Mapped System Header
A.
Tracking Faults Following Automatic Display of System State (Cases
1 and 2) :

First examine the system stack pointer. Usually an Executive
is the result of an SST type trap within the Executive.

failure

If an SST does occur within the Executive, then the origin or ~ne ca~~
on the crash reporting routine will be 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
was issued at a stack depth of zero or less, or a trap instruction was
executed at a depth of less than zero. The stack structure in the
case of an internal SST fault is shown in Figure 2-3.

2-15

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM

RS
R4
R3
R2
Rl
RO
RETURN TO SYSTEM EXIT
ZERO OR MORE SST PARAMETERS
SST FAULT CODE
NUMBER OF BYTES

---SP

Figure 2-3
Stack Structure - Internal SST Fault
The fault codes are:

0.
2.
4.
6.
8.
10.
12.
14.
16.
18.
20.
22.
24.
26.
28.

;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

The PC points to the instruction following the one which caused
the
SST failure.
The
number
of bytes is the number of bytes that are
normally transferred to the user stack when the particular type of SST
occurs.
If
the number is 4, then just the PS and PC are transferred
and there are no SST parameters.
If the failure is detected in $DRDSP, the stack is the same as
Figure
2-3,
except
the number of bytes, SST fault code (the fault codes are
listed above), and SST parameters are not present.
The crash
report
message, however, will indicate that the failure occurred in $DRDSP.

2-16

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
There is one SST-type failure, stack underflow, that will not have the
stack structure of Figure 2-3. To determine where the crash occurred,
first establish the stack structure; this can be deduced by the value
of the stack oointer
<SPi
and the contents of the top word on the
stack. If the stack stru~tu~e is that of Figure 2-3, then the failure
occurred in $DRDSP, or was a normal SST crash.
If the stack structure
is determined to be that of Figure 2-4, then a non-normal SST crash
has occurred.

,...-----:-:-----.I

....,_SP

Figure 2-4
Stack Structure - Non-Normal SST Fault
Non-normal SST failures occur when it is not possible to push
information on the stack without forcing another SST fault. When this
occurs, a direct jump to the crash reporting routine is made rather
than an !OT 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 !OT that
crashes the system. Note that the crash reporting routine rembves the
PC and PS of the !OT instruction from the stack, which in this case is
incorrect. Thus, the stack pointer will appear to be 4 greater than
it really is (i.e., as in Figure 2-4).
The driver writer now has all the information needed to isolate the
cause of the failure. From this point on, one must rely on personal
experience and a knowledge of the interaction between the driver and
the services provided by the Executive.
B. Tracking Faults When the Processor Halts Without
Display:

Providing

Fault

Tracking starts with an examination of $STKDP, $TKTCB, and $HEADR.
The difficulty in tracking failures in this case is that the system
stack is not directly associated with the cause of a failure.
By examining $STKDP, one 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 process focuses on scanning the stack
for addresses which may turn out to be subroutine links which will
ultimately lead to a thread of events isolating the fault.
This is
essentially the same aim in looking at the system stack if $STKDP is
zero or less.
Frequently, a fault will occur such that the SP points to Top of Stack
(TOS)+4.
This results from issuing an RT! when the top two items on
the stack are data; this will result in a wild branch, then, most
probably, a halt. Figure 2-5 shows a case, where two data items are
on the stack when the programmer 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 previous SP.

2-17

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM

~--51-SP
40100 . ..__SP

Figure 2-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 this case SP will point 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.
C.

Tracking Faults When an Un-Intended Loop Has Occurred:

After halting the processor, the same state exists as in the preceding
section.
Some specific suggestions are to check for a stack overflow
loop. Patterns of data successively duplicated on the stack indicate
a stack looping failure.
D.

Additional Hints:

Also of value 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} will
define 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. Since all
I/O packets are built in system dynamic memory, when they are
successfully terminated, their memory is returned to the dynamic
memory region. Following the link pointers in this region may reveal
whether or not I/O completion proceeded to that point.
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 ultimately produces a double
de-allocation of the same packet memory. Double de-allocation of a
dynamic buffer in RSX-llM causes a loop in the module $DEACB on the
next de-allocation (of a block of higher address)
after the second
de-allocation of the same block. At that time, R2 and R3 both contain
the address of the I/O Packet memory which has
been
doubly
de-allocated.

2-18

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
2.5

SAMPLE OUTPUT FROM CRASH AND PANIC DUMP ROUTINES

2.5.1

Crash Output

A sample of Crash output is 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
000472
000474
000476
000500
000502
000504
000506
000510
000512
000514
000516
000520
100522
)00524
000526
000530
000532
000534
000536
000540
000542

2.5.2

000004
000000
001514
000340
177753
000353
000000
000000
057750
002504
030011
100340
000340
056446
000000
102144
000000
101376
101372
102022
170000

Panic Dump Output

A portion of the output from Panic Dump is shown below.
Output is in
three 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 is the
octal word value;
the second line is the two octal byte values of the
word;
the third line contains the ASCII representation of the bytes.
The ASCII representations are reversed to
improve readability.
The
first output grouping from Panic Dump displays, proceeding from right
to left, PS, RO, Rl, R2, R3, R4, RS, and the SP.

2-19

INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM
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@
-@
> L
6 -@ -@ -@ -@ -@ -@ -@ -@ -@
N
J

000000 022646 000340 045770 000340 045770 000340 045770 000340
000000 045 246 000 340 113 3 70 000 340 113 3 70 000 340 113 370 000 340
"@
-@
-@
-@
&
%
K
K
K
000020 045776 000340 011124 000340 04 5 77 0 000340 050500 000340
000020 113 376 000 340 022 124 000 340 113 370 000 340 121 100 000 340
-@
-@
-@
-@
K
T -R
K
@ Q
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 -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
-@ -\
-@
-@
"@ -B
8
$
5
5

2-20

CHAPTER 3
WRITING AN I/0 DRIVER - PROGRAMMING SPECIFICS

In Chapter 1, overviews were given for:
Data structures;
Executive services, and
Programming protocol.
In this chapter, the details for the data structures and Executive
services are given. The protocol coverage in Chapter 1 was, however,
detailed enough to make further elaboration of programming protocol
unnecessary.

3.1

DATA STRUCTURES

Of all the control blocks in the I/O data structure, only four are
direct concern to a driver writer:
1.

The I/O Packet;

The DCB;

The UCB, and

The SCB.

Although the data structures contain an abundance of data pertaining
to input/output operations, drivers per se are involved only with a
subset of this data. Most of the data which requires the driver
writer's attention is supplied in the data structure source code, and
is not referenced during driver execution. Such an item is classified
as:
<initialized, not referenced>*

* The first field states whether the field is initialized in the data
structure source, and the second field gives the typical access at
execution time.

3-1

WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS
Fields supplied statically in the source code at the creation of the
data structure, and subsequently referenced during driver execution,
are classified:
<initialized, read-only>.
Fields set up during driver execution are classified:
<not initialized, read-only>
This form implies that either an agent other than the
driver has established the field or that the driver has
set it up once and references it read-only thereafter.
or:
<not initialized, read-write>.
Fields which do not
classified

involve

the

driver

writer

any

level

are

exceptions

<not initialized, not-referenced>.
These classifications cover most-likely
exist and are appropriately noted.

3.1.1

cases,

since

The I/O Packet

Figure 3-1 is a layout of the 18-word I/O Packet which is constructed
and placed in the driver I/O queue by QIO directive processing and
subsequently delivered to the driver by a call to $GTPKT. Figure 3-2
is the DPB from which the I/O Packet is generated.

* The first field states whether the field is initialized in the
structure source,
execution time.

data
and the second field gives the typical access at

3-2

WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS

I.LNK
I.EFN
I.FRI

LINK TO NEXT I/O PACKET

I.TCB

TCB ADDRESS OF REQUESTER

I.LN2

ADDRESS OF SECOND LUT WORD

I.UCB

ADDRESS OF REDIRECT UCB

I.FCN

FUNCTION CODE !MODIFIER

EFN

VIRTUAL ADDR OF

I. IOSB

PRI

I/O STATUS BLK

RELOCATION BIAS OF IOSB
REAL ADDRESS OF IOSB
I.AST

'VIRTUAL ADDR OF AST SERVICE RTN

LPRTvI

t
I

DEVICE
PARAMETERS

Figure 3-1
I/O Packet Format

3-3

~
_J
I

WRITING AN I/0 DRIVER - PROGRAMMING SPECIFICS
3.1.l.l I/0 Packet Details - The I/O Packet is built dynamically by
QIO directive processing. Thus, no static fields exist with respect
to a driver.
I/O Packets are created dynamically and, therefore, the
first parameter does not apply. Fields in the I/O Packet (described
below) are classified as:
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).

zero

ends

the

I.PRl
Driver access:
Not referenced.
Description:
Priority copied from the TCB of the requesting task.
I.EFN
Driver access:
Not referenced.
Description:
Contains the event flag number as copied
processing from the requester's DPB.
I. TCB
Driver access:
Not referenced.
Description:
TCB address of the reguesting task.
I. LN2

Driver access:
Not referenced.

3-4

QIO

directive

WRITING AN I/0 DRIVER - PROGRAMMING SPECIFICS
Description:
Contains the address of the second word of the LUT entry in
the task header to which the I/O request was 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 Redirect UCB if the starting
has been subject to an MCR Redirect command.

UCB

I.FCN
Driver access:
Read-only.
Description:
Contains the function
request.

code

(see

Table

3-1)

for

the

I/O

I. IOSB

Driver access:
Not referenced.
Description:
I.IOSB contains the virtual address of the I/O
(IOSB), if one is specified, or zero if not.

Status

block

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.

In a mapped system, the first word contains the relocation
bias of the IOSB; the bias is, in effect, the 32-word block
number 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:
Bits 0-5
Displacement in block
Bits 6-12 All zeros
Bits 13-15
6

(DIB)

The displacement in block is the offset from the block base.
In the above ex ample where the IOSB started at 3210 ( 8) , the
DIB is equal to 10(8).

3-5

WRITING AN I/0 DRIVER - PROGRAMMING SPECIFICS
The value 6 in bits 13-15 is constant. It is used to cause
an address reference through Kernel Page Address Register 6.
Again, see Appendix A for details.
The deferral of a discussion of the address doubleword to an
appendix reflects the fact that a writer of a conventional
driver has almost no need to concern himself with the
contents
or
format
of
the address doubleword.
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.AST
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 copied from the DPB.
The QIO Directive Parameter Block (DPB) is constructed as shown in
Figure 3-2.

3-6

WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS

LENGTH

DIC

FUNCT CODE

MODIFIER

RESERVED

LUN

PRIORITY

EFN

I/O STATUS BLOCK ADDRESS
AST ADDRESS
DEVICE

DEPENDENT
PARAMETERS

~
I

Figure 3-2
QIO Directive Parameter Block

3-7

/ 1"'\T"iD \

\ urDJ

WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS
The parameters in the DPB have the following interpretation.
Length (required}:
The length of the DPB, which for the RSX-llM
always fixed at twelve words.

QIO

directive,

DIC (required):
Directive Identification Code.
is a 1.

For the QIO directive, this value

Function Code (required):
The code of the requested I/O function (0 thru 31.).
Modifier:
Device dependent modifier bits.
Reserved:
Reserved byte and must not be used.
LUN (required ) :
Logical Unit Number.
Priority:
Request priority. Ignored by RSX-llM, but space must
be allocated for RSX-llD compatibility.
EFN (optional):
Event flag number.
I/O Status Block Address (optional):
This word contains a pointer to the I/O status block, which is a
2-word, device-dependent I/O 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 zero, then
the contents are device dependent.
AST Address (optional):
Address of an AST service routine.

3-8

WRITING AN I/0 DRIVER - PROGRAMMING SPECIFICS

Device Dependent Parameters:
Up to six parameters specific to the device and I/O function to
be performed. Typically, for data transfer functions, these are:
Buffer address
Byte count
Carriage control type
Logical block number
Any optional parameters that are not specified should be
zeros.

3.1.2

filled

with

The Device Control Block (DCB)

Figure 3-3 is a schematic layout of the DCa. The DCB describes the
static characteristics of a device controller and the units attached
to the controller. All fields must be specified.

D.LNK

LINK TO NEXT DCB (,0'=LAST)

D.UCB

LINK TO FIRST UCB

D.NAM

GENERIC DEVICE NAME

D.UNIT

HIGHEST UNIT #

LOWEST UNIT #

D.UCBL

LENGTH OF UCB

D.DSP

ADDR OF DRIVER DISPATCH TABLE

D.MSK

LEGAL FCN MSK BITS .0'-15.
CONTROL FCN MSK BITS .0'-15.
NO-OP'ED FCN MSK BITS .0-15.
ACP FCN MSK BITS .0'-15.
LEGAL FCN MSK BITS 16.-32.
CONTROL FCN MSK BITS 16.-32.
NO-OP'ED FCN MSK BITS 16.-32.
ACP FCN MSK BITS 16.-32.

Figure 3-3
Device Control Block

3-9

\'JRITING AN I/O DRIVER - PROGRAMMING SPECIFICS
3.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 DCB in the chain. The driver writer links his DCB
into the system DCB's via the global label $USRTB on his
first DCB.
D.UCB (Pointer to First UCB)
Driver access:
Initialized, not referenced.
Description:
Address link to the first and, possibly, the only UCB
associated with the DCB. All UCB's, for a given DCB, are in
contiguous memory locations and must all be 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.

* Parenthesized contents indicate value to be initialized in the
base
source code.

3-10

data

WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS
Description:
The UCB may have any length to meet the needs of the driver
for variable storage.
However! all UCB 1 s for a given DCB
must have the same length.
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. Thus, null addresses
are not permitted. If the driver does not process a given
function, then it simply returns. The driver writer must
provide a driver dispatch table in the driver source.
The
label on this table is of the form $nnTBL and must be a
global label. The designation nn 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, and
Power failure.
When a driver is entered at one of these entry points,
conditions are as follows:
At Initiator :
If UC. QUE=l

RS
UCB address
Rl = Address of the I/O Packet
If UC. QUE=O

RS = UCB address
Interrupts are allowed.
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 are locked out.

3-11

entry

WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS
At Device Timeout:
RS
R4
R3
RO

UCB address
SCB address
Controller index
I/O status code IE.DNR (Device Not Ready)

Device interrupts are locked out.
At Power Failure:
RS
R4
R3

UCB address
SCB address
Controller index

Interrupts are allowed.
D.MSK (Function Masks)
Driver access:
Initialized, not referenced.
Description:
There are eight words, beginning at D.MSK, which are of
critical importance to the proper functioning of a device
driver. The Executive uses these words to validate and
dispatch the I/O request specified by a QIO directive. The
description which follows applies only to non-file-structured
devices,
since
directions
for
writing
drivers
for
file-structured devices (drivers which interface to FCP) are
not included in this manual. Four masks, 2-words per mask,
are described by the bit configurations established by the
driver writer for these words.
1.

Legal function mask;

Control function mask;

No-op'ed function mask, and

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 function value in the I/O request is filtered by the
Executive through the four mask words. I/0 function codes
range from 0-31. If the function corresponds to a true
condition in a mask word, a bit is set in the mask in the
position which numerically corresponds to the function code.
Thus, if the function 5 is legal, then bit 5 in the Legal
Function Mask is set.
The masks are laid out in memory in two 4-word groups.
Each
4-word group covers 16 function codes. The first four words
cover the function codes 0-15; the second four words cover
codes 16-31.
Below is the exact layout used for the driver
example in Chapter 5.

3-12

WRITING AN I/0 DRIVER - PROGRAMMING SPECIFICS
.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.

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 by returning 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 QIO directive
processor, the function is considered in the class <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. If 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 neither control nor no-op,
then it is either an ACP function or a transfer function. If
a function code may require intervention of an Ancillary
Control Processor
(ACP}, the corresponding bit in the ACP
function mask must be set.
In the specific case of read/write virtual functions, the
corresponding mask bits may be set at the driver writer's
option. If the corresponding mask bits for a read/write
virtual function are set, QIO directive processing will
recognize that a file-oriented function is being requested to
a non-file-structured device and convert 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 request
is queued to the driver as a read/write logical
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.

3-13

WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS
3.

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

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 (i.e., being within the address space of
the requesting task) and proper alignment (i.e., word or
byte).
Also, the number of bytes being transferred is
checked for proper modulus (i.e., nonzero and a proper
multiple).

Mask Word Creation
The creation of the function mask words involves three steps:
1.

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

Check the standard RSX-llM function code values in Table 3-1
for equivalencies.
Only function code 0 is mandatory.
Function codes 3 and 4, if used, must have the RSX-llM system
interpretation.
It is suggested that functions having an
RSX-llM system counterpart use the RSX-llM code, but this is
not required, except in the case where the device is to be
used in conjunction with an ACP. From the supported function
list, the two legal function mask words can be built.

Given the legal function mask,

3a. The Control Function mask is built 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 it either 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.
(Buffer
addresses
in
standard
format
are
automatically converted to Address Doubleword format.)
Control functions are, essentially, those whose DPB's do
contain buffer addresses or counts.

not

3b. The No-op Function Mask is created by deciding which legal
functions are to be no-op'ed. Typically, for File Control
Services (FCS) compatibility 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.
3c. Finally, the ACP functions Write Virtual Block and Read
Virtual Block may be included.
Other ACP functions that
might be included fall into the non-conventional driver
classification and are beyond the scope of this document.

3-14

WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS
3.1.2.2 IIO Function Codes - The filtering process which cascades
through the function mask words in the DCB uses the function code byte
supplied in the QIO directive DPB as the match value.
Table 3-1
contains the function code values used for DEC-supplied drivers.

Table 3-1
Standard I/O Function Codes

FUNCTION
VALUE (8)

EQUATED
SYMBOLIC

0
1
2
3
4
5
6
7
10

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

12
13
14
15
16
17
20
21
22
23
24
25
26

27
30
31
32
33
34
35
36
37

II
I

IO.FNA
IO. RNA
IO. ENA
IO.ACR
IO.ACW
IO. ACE
IO.DAC
IO. RVB
IO.WVB
IO. EXT
IO.CRE
IO. DEL
IO. RAT
IO.WAT

I/O
FUNCTION
Cancel I/O
Write Logical Block
Read Logical Block
Attach Device
Detach Device
Unused
Unused
Unused
Unused
Find
File in Directory
I
Unused
Remove File from Directory
Enter File in Directory
Access File for Read
Access File for Read/Write
Access File for Read/Write/Extend
Deaccess File
Read Virtual Block
Write Virtual Block
Ex tend File
Create File
Mark File for Delete
I Read File Attributes
Write File Attributes
Unused
Unused
Unused
Unused
Unused
Unused
Unused
Unused

3-15

II
I

WRITING AN I/0 DRIVER - PROGRAMMING SPECIFICS
Of the function code values listed in Table 3-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.
If QIO
directive processing encounters a function code of 3 or 4 and the code
is not no-op'ed, it will assume that they represent Attach device and
Detach device, respectively.
The other codes are suggested but not
mandatory. The driver writer is free to establish all other function
code values on non-file-structured devices.
The mask words must
obviously reflect the proper filtering process.
If a driver
is being written for a file-structured
standard function codes of Table 3-1 must be used.

3.1.3

device,

the

The Status Control Block (SCB)

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

S.LHD

---

DEVICE I/O QUEUE
LISTHEAD

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

I
I

PRIOR~

VECTOR ADDR/4

DEVICE

INT TM OUT CNT

CURNT TMOUT CNT

CTRLR STATUS

CONTROLLER #*2

S.CSR

ADDRESS OF CONTROL STATUS REG

S.PKT

ADDRESS OF CURRENT I/O PACKET

S.FRK

FORK LINK WORD
FORK PC
FORK RS
FORK R4

Figure 3-4
Status Control Block

3-16

WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS
3.1.3.l

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 which form 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.
S.PRI (device priority)
Driver access:
Initialized, not referenced.
Description:
Contains the priority at which the device interrupts.
S.VCT (interrupt vector divided by four)
Driver access:
Initialized, not referenced.
Description:
Interrupt vector address divided by four.
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 will examine
active times, decrement them and, if they reach 0, call the
driver at its device timeout entry point.
The internal clock count is kept in I-second increments.
Thus, a time count of 1 is not pr~cise, since the internal
clocking mechanism is operating asynchronously with driver
execution.
The only meaningful minimum clock interval is 2
if the programmer intends to treat timeout as a consistently
detectable error condition. Note, if the count is 0, thal no
timeout will occur; it is, in fact, an indication that
timeout is not operative.
The maximum count is 255. The
driver writer is responsible for setting
this
field.
Resetting is at actual timeout or within $FORK.

3-17

WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS
S.ITM (set to initial timeout count)
Driver access:
Initialized, read-only.
Description:
Contains the initial timeout value.
S.CON (controller number times 2)
Driver access:
Initialized, read-only.
Description:
Controller number multiplied by 2. Used by drivers which are
written to support more than one controller. S.CON may be
used by the driver- to index into a controller table created
and maintained internally to the driver itself. Indexing the
controller table enables the driver to service the correct
controller when a
S.STS (initialize to zero)
Driver access:
Initialized, not referenced.
De s c r i pt ion :
Establishes the controller as busy/not busy.
This byte is
the interlock mechanism for marking a driver as busy for a
specific controller. Tested and set by $GTPKT and reset by
$!ODON.
S.CS~

(Control Status Register address)
Driver access:
Initialized, read/only.
Description:
Contains the address of the Control Status Register (CSR) for
the device controller.
S.CSR is used by the driver to
initiate I/O operations and to access, via 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 this to
set the off-line bit at bootstrap so system software can be
interchanged between systems without an intervening system
generation. Otherwise, it is only accessed by the driver
itself.

3-18

WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS
S.PXT (Reserve one word of storage)
Driver access:
Not initialized, read-only.
Description:
Address of the current I/0 Packet established by $GTPKT.
This field is used to retrieve the I/O Packet address upon
the completion of an I/O request.
S.FRK (reserve four words of storage)
Driver access:
Net initialized, not referenced.

Description:
The four 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.

3.1.4

The Unit Control Block {UCB)

riqure 3-5 is a layout of the UCB (a variable-length control block).
One UCB exists 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.

3-19

WRITING AN I/0 DRIVER - PROGRAMMING SPECIFICS

U.DCB

BACK POINTER TO DCB

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

REDIRECT UCB POINTER
UNIT STATUS

CONTROL FLAGS
PHYSICAL UNIT #

STATUS EXT

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

ICB ADDR OF ATTACHED TASK

U.BUF

BUFFER RELOCATION BIAS

U.BUF+2

BUFFER ADDRESS

U.CNT

BYTE COUNT
DEVICE
DEPENDENT

STORAGE

Figure 3-5
Unit Control Block

3-20

WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS
3.1.4.1

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

U.DCB (pointer to associated DCB)
Driver access:
Initialized, not referenced.
Description:
Backpointer to the corresponding DCB. Since the UCB is a key
control block in the I/O data structure, access to other
control blocks usually occurs via links implanted in the UCB.

u RED (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 UCB itself.
"
U.CTL (set by driver writer)
Driver access:
Initialized, not referenced.
Description:
U.CTL and the function mask words in the DCB drive QIO
directive
processing.
The
driver
writer is totally
resoonsible for settino up this bit pattern. Any inaccuracy
in the bit setting of U.CTL will produce erroneous I/O
processing. Bit symbols and their meaning are as follows:
UC.ALG - Alignment bit.
If this bit = 0, then byte alignment of data buffers is
allowed.
If UC.ALG = 1, then buffers must be word
aligned.
UC.ATT - Attach/Detach notification.
If this bit is set, then the driver will be called when
an Attach/Detach I/0 function is processed by $GTPKT.
Typically, the driver has no 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 to be 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.

3-21

WRITING AN I/0 DRIVER - PROGRAMMING SPECIFICS
UC.QUE - Queue bypass bit.
If set, the QIO directive processor is to call the driver
prior
to
queueing
the I/O Packet.
Once gaining
to-be-queued control, the disposition of the I/O Packet
is the driver's responsibility. Typically, an I/O Packet
is queued prior to a call to the driver, which later
retrieves it by a call to $GTPKT.
UC.PWF - Unconditional call on power failure bit.
If set, the driver is always to be called when 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.
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
under the discussion of U.BUF below).
UC.LGH - Buffer size mask bits (2-bits).
These two bits are used to check if the byte count
specified in an I/O request is a legal buffer modulus.
00
01
11
10

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

UC.ALG and UC.LGH are independent settings.
UC.ATT, UC.KIL, UC.QUE, and UC.PWF will
especially for conventional drivers.

usually

zero,

Every driver must, however, be concerned with its
values for UC.ALG, UC.NPR, and UC.LGH.

particular

The driver writer is totally responsible for the
these bits, and erroneous values are likely
unpredictable results.

values in
to produce

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

status

US.BSY - If set, device-unit is busy.
US.MNT - If set, volume is not MOUnted.

3-22

information.

WRITING AN I/0 DRIVER - PROGRAMMING SPECIFICS
US.FOR - If set, volume is foreign.
US.MDM - If set, device is marked for dismount.
The unused bits in U.STS are reserved for system
expansion.
US.MDM,
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 driver writer)
Driver access:
Initialized, not referenced.
D@scription:
This byte contains additional device-independent
information. The bit meanings are as follows:

st1tus

US.OFL - If set, the device is off-line (that is, not
the configuration).

US.RED - If set, the device cannot be redirected.
The remaining bits are reserved for system use and expansion.
U.CWl {set by driver writer)
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 characteristic words are retrieved from the UCB and
placed in the requester's buffer on issuance of a GLUN$
Executive
directive {Get LUN Information).
It is the
responsibility of the driver writer to supply the contents of
these four words in the assembly source code of the driver
data structure.

3-23

WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS
U.CWl is defined as follows:
DV.REC
DV.CCL
DV.TTY
DV.DIR
DV.SDI
DV.SQD
DV.PSE
DV.COM
DV. Fll
DV.MNT

Bit 0--Record-Oriented Device(l=yes)
Bit 1--Carriage-Control Device{l=yes)
Bit 2--Terminal Device(l=yes)
Bit 3--Directory Device(l=yes)
Bit 4--Single Directory Device{l=yes)
Bit 5--Sequential Device{l=yes)
Bit 12--Pseudo Device{l=yes)
Bit 13--Device Mountable as a
Communications Channel(l=yes)
Bit 14--Device mountable as a FILES-11
device ( l=Yes}
Bit 15--Device mountable{l=yes)

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

driver

(available

tor

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 driver writer)
Driver access:
Initialized, read-only.
Description:
Default buffer size.
U.SCB (SCB pointer)
Driver access:
Initialized, read-only.
Description:
This field contains a pointer to the SCB for this UCB.
In
general, R4 on entry to the driver via the driver dispatch
table will contain the value in this word, since the SCB is
frequently referenced by service routines.

3-24

WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS
U.ATT (initialize to zero)
Driver access:
Initiaiized, not referenced.
Description:
If a task has attached itself to a
contains its TCB address.

device-unit,

this

field

U.BUF (reserve two words of storage)
Driver access:
Not initialized, read/write.
Description:
U.BUF labels two consecutive words which serve
as
a
communication region between $GTPKT and the driver. If a
non-transfer function is indicated, then U.BUF, U.BUF+2, and
U.CNT receive the first three parameter words from the I/O
Packet.
For transfer operations, the format of these two words
depends on the setting of UC.NPR in U.CTL. The driver does
not format the words; all formatting is completed prior to
the driver receiving 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.
Format for program transfer devices:
The format is identical to that for the second two
I.IOSB in the I/O Packet. See section 3.1.1.1.

words

In general, the driver will not manipulate these words when
performing I/O to program transfer d~vice. It most likely
will use the Executive routines Get Byte, Get Word, Put Byte,
and Put Word to effect data transfers between the device and
the user's buffer.
Format for an NPR device:
For NPR device drivers, the word layout is as follows:
Word l
Bit
Bit
Bit
Bit
Bits

1-3
4,5
6

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

3-25

WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS
It is the driver's responsibility to set the function code,
interrupt enable, and go bits. This must be accomplished by
a Bit Set (BIS) operation so the extension bits ~re not
disturbed.
The driver is also responsible for moving these
words into the device control registers to initiate the I/O
operation.
Note that when the system is unmapped, bits 4 and 5 will
always be zero, but this is transparent to the driver. Thus,
NPR device drivers will not be 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 three words contain the first three words of the I/O
Packet.
The details of the construction
appear in Appendix A.

the

Address

Doubleword

U.CNT (reserve one word of storage)
Driver access:
Not initialized, read/write.
Description:
Contains the byte count of the buffer described by U.BUF.
The driver will use this field in constructing the actual
device request.
U.BUF and U.CNT are used to keep track of the current data
item in the buffer for the current transfer (except for NPR
transfers). Since this field is bsing altered dynamically,
the I/O Packet may be needed to reissue an I/O operation.
Device-Dependent Words:
Driver access:
Not initialized, read/write.
Description:
The field is variable in length and is established
driver writer to suit driver-specific requirements.

3-26

the

CHAPTER 4
EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS

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

4.1

SYSTEM-STATE REGISTER CONVENTIONS

In system state, RS and R4 are, by convention, established as
non-volatile registers. This means that an internally called routine
is required to save and restore these two registers if it intends to
destroy their contents. Note that drivers are entered directly from
interrupts and have to call $INTSV to preserve RS and R4.
R3, R2, Rl, and RO are volatile registers and may be used by a
routine without save and restore responsibiiities.

called

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 and employed only when
ample justification can be given to demonstrate the value added to
overall system performance by virtue of the proposed departure.

4.2

SERVICE CALLS
$DVMSG

DEVICE MESSAGE OUTPUT
Device Message Output is in the file IOSUB.
Calling sequence:
CALL

$DVMSG

4-1

EXECUTIVE SERVICES AVAILABLE TO I/0 DRIVERS
Description:
i+

**-$DVMSG-DEVICE MESSAGE OUTPUT
THIS ROUTINE rs 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 THAT 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 TERMINATION 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.

Notes:

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

4-2

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS
$FORK

Fork is in the file SYSXT.
$FORK is called by a drivec to switch from
a partially interruptible level (its state following a call on $INTSV)
to a fully interruptible level.
Calling sequence:
CALL $FORK
Description:
;+
**-$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:

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

4-3

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVF.RS
$GTBYT

GET BYTE
Get Byte is in the file BFCTL.
Callinq sequence:
CALL

$GTBYT

Description:
;+
**-$GTBYT-GET NEXT BYTE FROM USER BUFFER
THIS ROUTINE IS CALLED TO GET THE NEXT BYTE FROM THE USER BUFFER
AND 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.
ALL REGISTERS ARE PRESERVED ACROSS CALL.
;-

4-4

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS
GET PACKET

$GTPKT

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/0 REQUEST
PROCESS. IF THE DEVICE CONTROLLER IS BUSY, THEN A CARRY SET INDICATION IE
RETURNED TO THE CALLER. ELSE AN ATTEMPT IS MADE TO DEQUEUE THE NEXT REQUI
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 BUS~
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 AMD RS ARE DESTROYED BY THIS ROUTINE.
;-

4-5

EXECUTIVE SERVICES AVAILABLE TO I/0 DRIVERS
$GTWRD

GET WORD
Get Word is in the file BFCTL.
Calling sequence:
Call

$GTWRD

Description:
;+
**-$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:
RS=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.
;-

4-6

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS
$INTSV

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
OR JUMPS TO $INTXT.
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 LOADED AND A RETURN TO THE CALLER IS EXECUTED.
;-

4-7

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS
$INTXT

INTERRUPT EXIT
Interrcpt Exit is in the file SYSXT.
Calling sequence:
JMP

$INTXT

Description:

;+
**-$INTXT-INTERRUPT EXIT
THIS ROUTINE IS CALLED VIA A JUMP TO EXIT FROM AN INTERRUPT. IF THE
STACK DEPTH IS NOT EQUAL TO ZERO, THEN REGISTERS R4 AND RS ARE
RESTORED AND AN RT! 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 RT! 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.

4-8

EXECUTIVE SERVICES AVAILABLE TO I/0 DRIVERS
$IOALT
$IODON

I/0 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/0 REQUE
TO DO FINAL PROCESSING. THE UNIT AND CONTROLLER ARE SET IDLE AND $IOFIN I~
ENTERED TO FINISH THE PROCESSING.
INPUTS:
RO=FIRST I/O STATUS WORD.
Rl=SECOND I/O STATUS WORD.
RS=ADDRESS OF THE UNIT CONTROL 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/0 PACKET.
;-

4-9

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS
$IOFIN

I/0 FINISH

I/O Finish is in the file IOSUB.
Drivers rarely call I/O Finish, but
they should
be aware of the fact that this routine is executed when
$IOALT or $!ODON is called.
Calling sequence:
CALL

$IOFIN

Description:
;+
**-$IOFIN-I/0 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/0 STATUS WORD.
R3=ADDRESS OF THE I/O REQUEST PACKET.
RS=ADDRESS OF THE UNIT CONTROL BLOCK.
OUTPUTS:
THE FOLLOWING ACTIONS ARE PERFORMED:
1-THE FINAL I/O STATUS VALUES ARE STORED IN THE I/O STATUS BLOCK IF
ONE WAS SPECIFIED.
2-THE I/O REQUEST COUNT IS DECREMENTED. IF THE RESULTANT COUNT IS
ZERO, THEN 'TS.RDN' IS CLEARED IN CASE THE TASK WAS
STOPPED FOR I/0 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.

4-10

EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS
PUT BYTE

$PTBYT

Put Byte is in the file BFCTL.
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 REGISTERS ARE PRESERVED ACROSS CALL.
;-

4-11

EXECUTIVE SERVICES AVAILABLE TO I/0 DRIVERS
$PTWRD

PUT WORD
Put Word is in the file BFCTL.
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.
;-

4-12

CHAPTER 5
INCLUDING A USER-WRITTEN DRIVER - AN EXAMPLE

The example which follows is a complete illustration of the procedures
required to add a driver to an RSX-llM system. The driver in the
example supports the punch capability of the PCll Paper
Tape
Reader/Punch.

5.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 a reader
only (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
infvrmation 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.

5-1

INCLUDING A USER-WRITTEN DRIVER - AN EXAMPLE
5.2

DATA STRUCTURE 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 will be seen below, in a particular case, building a
conventional
driver
is
indeed
a
straightforward and modest
undertaking.

5.2.1

The Data Structure

The data structure source is shown below and is self-explanatory.
Special note should be taken of the legal function mask words,
starting at line 45. The standard function codes listed in Table 3-1
were used in creating the mask. Thus, the Punch driver will accept
the following I/O functions:
Cancel I/O
Write Logical Block
Attach Device
Detach Dev ice
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
two
Access/Deaccess
functions are legal for FCS compatibility, but are no-op'ed. Write
Virtual Block is legal but will be 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
DEA
WVB

FUNCTION CODE(OCTAL) MASK(OCTAL) BIT RANGE(DECIMAL)
0
1
3

000001
000002
000010

0-15.
0-15.
0-15.

000020

0-15.

16
17
20
22

040000
100000
000001
000004

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(10)-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.

5-2

INCLUDING A USER-WRITTEN DRIVER - AN EXAMPLE
The complete mask words appear
structure source.

lines

thru

the

data

The function code selections for record-oriented devices are
intended
to match FCS requirements
for
file-structured
devices.
When FCS
executes an Access-For Write, it will simply be marked a no-op.
This
tends to minimize FCS device-dependent logic.
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 to
zero.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

.TITLE USRTB
.IDENT /01/

COPYRIGHT 1975, DIGITAL EQUIPMENT CORP.: MAYNARDf 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
J.

PASCUSNIK

25-NOV-74

CONTROL BLOCKS FOR PAPER TAPE PUNCH DRIVER
MACRO LIBRARY CALLS
.MCALL DEVDF$,HWDDF$

DEVDF$

;DEFINE DEVICE CONTROL BLOCK OFFSETS*
30
HWDDF$
;DEFINE HARDWARE REGISTERS
31
32
33
PAPER TAPE PUNCH DEVICE DATA BASE
34
35
PAPER TAPE PUNCH DEVICE CONTROL BLOCK
36 ;
37 $USRTB::
38 PPDCB:
.WORD
0
;LINK TO NEXT DCB
39
.WORD
.PPO
;POINTER TO FIRST UCB
40
.ASCII /PP/
;DEVICE NAME
41
.BYTE
0,0
;LOWEST AND HIGHEST UNIT NUMBERS COVE
42
BY THIS DCB
43
.WORD
PPND-PPST
;LENGTH OF EACH UCB IN BYTES
44
.WORD
$PPTBL
;POINTER TO DRIVER DISPATCH TABLE
45
.WORD
140033
;LEGAL FUNCTION MASK CODES 0-15.

* Appendix B lists all macros which exist in RSX-llM and generate control
offsets.

5-3

INCLUDING A USER-WRITTEN DRIVER - AN EXAMPLE
46
47
48
49
50
51
52

.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD

30
140000
0
5
0
1
4

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

53
PAPER TAPE PUNCH UNIT CONTROL BLOCK
54
55 ;
56 .PPO::
57 PPST=.
PP DCB
;BACK POINTER TO DCB
.WORD
58
.WORD
.-2
;POINTER TO REDIRECT UNIT UCB
59
.BYTE
UC.ATT,0
;CONTROL PROCESSING FLAG (PASS CONTROL
50
;
ON ATTACH/DETACH), UNIT STATUS
51
0,0
;PHYSICAL UNIT NUMBER, UNIT STATUS EXTENSION
52
.BYTE
DV.REC
.WORD
;FIRST DEVlCE CHARACTERISTICS WORD
53
;
(RECORD-ORIENTED DEVICE)
54
.WORD
;SECOND DEVICE CHARACTERISTICS WORD
55
0
;
(FOR INTERNAL USE BY DRIVER)
56
;THIRD DEVICE CHARACTERISTICS WORD
.WORD
57
0
;
(FOR INTERNAL USE BY DRIVER)
58
.WORD
64.
;FOURTH DEVICE CHARACTERISTICS WORD
59
;
(DEFAULT BUFFER SIZE IN BYTES)
70
.WORD
PPSCB
; POINTER TO SCB
71
.WORD
;TCB ADDRESS OF ATTACHED TASK
72
0
;RELOCATION BIAS OF BUFFER OF CURRENT
73
.BLKW
1
74
;
I/O REQUEST
75
.BLKW
1
;ADDRESS OF BUFFER OF CURRENT I/0 REQUEST
.BLKW
;BYTE COUNT OF CURRENT I/O REQUEST
76
1
77 PPND=.

78 i
79 ; PAPER TAPE PUNCH INTERRUPT VECTOR
30

.ASECT

32 .=74
33
34

35
36

.WORD
.WORD
.PSECT

$PPINT
PR7!0

;ADDRESS OF INTERRUPT ROUTINE
;INTERRUPT AT PRIORITY 7 (CONTROLLER=O)

PAPER TAPE PUNCH STATUS CONTROL BLOCK
37
38 ;
.WORD
;CONTROLLER I/O QUEUE LISTHEAD
39 PPSCB:
0
(POINTER TO FIRST ENTRY)
90
.WORD
.-2
;
(POINTER TO LAST ENTRY)
n
PR4,74/4
;DEVICE PRI, INTERRUPT VECTOR ADDRESS/4
n
.BYTE
0,4
.BYTE
;CURRENT AND INITIAL TIMEOUT COUNTS
B
.BYTE
0,0
;CONTROLLER INDEX AND STATUS
94
;
(O=IDLE, l=BUSY)
35
.WORD
177554
;ADDRESS OF CONTROL STATUS REGISTER
36
;ADDRESS OF CURRENT I/O PACKET
.BLKW
n
1
;FORK BLOCK ALLOCATION
.BLKW
98
4
99
.END
DO

5-4

INCLUDING A USER-WRITTEN DRIVER - AN EXAMPLE
5.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.
A few preliminary comments will simplify the examination of
the code itself.
Since the PP driver is a DEC product and will eventually be part of a
released system, conditionalized sections in the code exist that will
be included or deleted based on answers provided by the user to the
configuration queries posed during system generation. The system
generation questions determine the value of a symbol defined in the
assembly prefix file RSXMC.MAC. The conditionalized sections of code
are then controlled by the value of the symbol.
The conditionalized
code appears in multi-controller drivers and is recommended for all
driver implementations.
Conditionalized code for PP is implemented as follows:
P$$Pll is set to the number of controllers the driver is to service.
This sets the size of CNTBL and conditionally creates 'TEMP', if
P$$Pll >l. Also, if P$$Pll >l, code is generated to save PS in TEMP
for retrieval on return from $INTSV, and the controller number is
decoded from the low-order four bits of the saved PS and used to index
into CNTBL to obtain the UCB address. For P$$Pll=l, CNTBL is one word
long, TEMP is not necessary, and the UCB address is always the first
entry in CNTBL.
The structure of the driver follows the
separated into processing code for:

classic

RSX-llM

form

being

Initiator;
Power Failure;
Interrupt;
Timeout, and
r"----,

1..-CIIH...:e'.1.

T' ' "
J../
V

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 via device timeout, as is the
device-not-ready condition.
The PP driver uses the following Executive services:
$INTSV
$INTXT
$GT PKT
$GTBYT
$DVMSG
Comments beginning with ';;;'
indicate the instruction
executed at a priority level greater than or equal to 4.

5-5

being

INCLUDING A USER-WRITTEN DRIVER - AN EXAMPLE
The code contained in lines 128-130 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 (i.e., out of paper - tape)
and
the system has generated the detach for the aborting process.
l
2
3
4
5

.TITLE PPDRV
.IDENT /01/
COPYRIGHT 1975, DIGITAL EQUIPMENT CORP., MAYNARD, MASS.

01754

7
8
9
10

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.

12
13
14
15
16
17

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.

19
VERSION 01
20
21
J. PASCUSNIK 25-NOV-74
22
PCll PAPER TAPE PUNCH DRIVER
23
24
25
MACRO LIBRARY CALLS
26
27
.MCALL ABODF$,DEVDF$,HWDDF$,PKTDF$,TCBDF$
28
ABODF$
;DEFINE TASK ABORT CODES
29
DEVDF$
;DEFINE DEVICE CONTROL BLOCK OFFSETS
30
HWDDF$
;DEFINE HARDWARE REGISTER SYMBOLS
31
;DEFINE I/O PACKET OFFSETS
32
PKTDF$
TCBDF$
;DEFINE TASK CONTROL BLOCK OFFSETS
33
34
35
EQUATED SYMBOLS
36
37
PAPER TAPE PUNCH STATUS WORD BIT DEFINITIONS (U.CW2)
38
39
40
;WAITING FOR DEVICE TO COME ON-LINE (l=YES)
41 WAIT=lOOOOO
;ABORT CURRENT I/O REQUEST (l=YES)
42 ABORT=40000
;CURRENTLY PUNCHING TRAILER (l=YES)
4 3 TRAIL= 2 0 0
44
45
LOCAL DATA
46
47
CONTROLLER IMPURE DATA TABLES (INDEXED BY CONTROLLER NUMBER)
48
49
50
;ADDRESS OF UNIT CONTROL BLOCK
.BLKW
P$$Pll
51 CNTBL:
52
53
54
.IF GT P$$Pll-l
55
.BLKW
56 TEMP:
1
;TEMPORARY STORAGE FOR CONTROLLER NUMBER

5-6

INCLUDING A USER-WRITTEN DRIVER - AN EXAMPLE
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

.IFTF
DRIVER DISPATCH TABLE
$PPTBL::

.WORD
. WORD
. WORD
. WORD

PP IN I
PP CAN
PPOUT
PPPWF

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

;+
**-PPINI-PCll PAPER TAPE PUNCH CONTROLLER INITIATOR
THIS ROUTINE IS ENTERED FROM THE QUEUE I/O DIRECTIVE WHEN AN I/O REQUEST
IS QUEUED AND AT THE END OF A PREVIOUS I/O OPERATION TO PROPAGATE THE EXECU
TION OF THE DRIVER. IF THE SPECIFIED CONTROLLER IS NOT BUSY, THEN AN ATTEMP
IS MADE TO DEQUEUE 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:
R5=ADDRESS OF THE UCB OF THE CONTROLLER TO BE INITIATED.

OUTPUTS:
IF THE SPECIFIED CONTROLLER IS NOT BUSY AND AN I/O REQUEST IS WAITING TO BE PROCESSED, THEN THE REQUEST IS DEQUEUED AND THE I/O OPERATION IS INITIATED.
;PPINI:

.ENABL
CALL
BCS

LSB
$GT PKT
PPPWF

;GET AN I/O PACKET TO PROCESS
;IF CS CONTROLLER BUSY OR NO REQUEST

THE FOLLOWING ARGUMENTS ARE RETURNED BY $GTPKT:

97
98
99
100
101
102
103
104
105
106
107
108
109
llO
lll
ll2
ll3
ll4
ll5
ll6
117

Rl=ADDRESS OF THE I/0 REQUEST PACKET.
R2=PHYSICAL UNIT NUMBER OF THE REQUEST UCB.
R3=CONTROLLER INDEX.
R4=ADDRESS OF THE STATUS CONTROL BLOCK.
R5=ADDRESS OF THE UCB OF THE CONTROLLER TO BE INITIATED.
PAPER TAPE PUNCH I/O REQUEST PACKET FORMAT:
WD.
WD.
WD.
WD.
WD.
WD.
WD.
WD.
WD.
WD.
WD.
WD.
WD.

00
01
02
03
04
05
06
07
10
11
12
13
14

I/0 QUEUE THREAD WORD.
REQUEST PRIORITY, EVENT FLAG NUMBER.
ADDRESS OF THE TCB OF THE REQUESTER TASK.
POINTER TO SECOND LUN WORD IN REQUESTER TASK HEADER.
CONTENTS OF THE FIRST LUN WORD IN REQUESTER TASK HEADER (C
I/0 FUNCTION CODE (IO.WLB, IO.ATT OR IO.DET).
VIRTUAL ADDRESS OF I/O STATUS BLOCK.
RELOCATION BIAS OF I/0 STATUS BLOCK.
I/0 STATUS BLOCK ADDRESS (REAL OR DISPLACEMENT + 140000).
VIRTUAL ADDRESS OF AST SERVICE ROUTINE.
RELOCATION BIAS OF I/0 BUFFER.
BUFFER ADDRESS OF I/O TRANSFER.
NUMBER OF BYTES TO BE TRANSFERRED.

5-7

INCLUDING A USER-WRITTEN DRIVER - AN EXAMPLE
118
119

WD. 15
WD. 16
WD. 17
WD. 20

NOT
NOT
NOT
NOT

USED.
USED.
USED.
USED.

120
121
122
123
124
MOV
R5,CNTBL(R3)
;SAVE UCB POINTER FOR INTERRUPT ROUTINE
U.CW2(R5)
;CLEAR ALL SWITCHES
125
CLR
CMPB
I.FCN+l(Rl) ,#IO.WLB/256. ;WRITE LOGICAL BLOCK FUNCTION?
126
127
BEQ
10$
;IF EQ YES
128
MOV
I.TCB(Rl) ,RO
;GET REQUESTER TCB ADDRESS
BITB
#TS.ABO,T.STAT+2(R0) ;TASK BEING ABORTED?
129
BNE
65$
;IF NE YES - DON'T PUNCH TRAILER
130
#TRAIL,U.CW2(R5) ;OTHERWISE FUNCTION IS ATTACH OR DETACH
131
BIS
;
SET FLAG TO PUNCH TRAILER
132
MOV
#170.,U.CNT(R5) ;SET COUNT FOR 170 NULLS
133
134 10$:
BIS
#WAIT,U.CW2(R5) ;ASSUME WAIT FOR DEVICE OFF LINE
TST
@S.CSR(R4)
;DEVICE OFF LINE?
135
BMI
80$
;IF MI YES
136
BIC
#WAIT,U.CW2(R5) ;DEVICE ON LINE, CLEAR WAIT CONDITION
137 20$:
MOVB
S.ITM(R4) ,S.CTM(R4) ;SET TIMEOUT COUNT
138
MOV
#100,@S.CSR(R4) ;ENABLE INTERRUPTS
139
140
141
142
POWERFAIL IS HANDLED VIA THE DEVICE TIMEOUT FACILITY AND THEREFORE CAUSE~
143
NO IMMEDIATE ACTION ON THE DEVICE. THIS IS DONE TO AVOID A RACE CONDITIO~
144
THAT COULD EXIST IN RESTARTING THE I/0 OPERATION
145
146
147 PPPWF:
RETURN
148
149 ; +
150 ; **-$PPINT-PCll PAPER TAPE PUNCH CONTROLLER INTERRUPTS
151 ,
152
153 $PPINT: :
; ; ; REF LABEL
154
155
.IFT
156
157
PS,TEMP
MOV
;;;SAVE CONTROLLER NUMBER
158
.IFTF
159
160
161
CALL
$INTSV, PR4
;;;SAVE REGISTERS AND SET PRIORITY
162
163
.IFT
164
MOV
TEMP,R4
;;;RETRIEVE CONTROLLER NUMBER
165
BIC
166
#1 77760, R4
;;;CLEAR ALL BUT CONTROLLER NUMBER
ASL
R4
167
;;;CONVERT TO CONTROLLER INDEX
MOV
CNTBL(R4) ,RS
168
;;;RETRIEVE ADDRESS OF UCB
169
170
.IFF
171
172
MOV
CNTBL,R5
;;;RETRIEVE ADDRESS OF UCB
173
174
.ENDC
175
176
177
MOV
U.SCB(R5) ,R4
;;;GET ADDRESS OF STATUS CONTROL BLOCK
178
MOVB
S.ITM(R4) ,S.CTM(R4) ;;;RESET TIMEOUT COUNT

5-8

INCLUDING A USER-WRITTEN DRIVER - AN EXAMPLE
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212

MOV
MOV
BM!
SUB

30$:
40$:
50$:
60$:

65$:
70$:

S.PKT(R4) ;Rl
I • PRM+ 4 ( R1 ) , R1
U.CNT(R5) ,Rl
#IS.SUC&377 ,RO
U.CW3(R5)
70$
#IE.VER&377 ,RO
$IODON
PP IN I

;;;POINT R4 TO CONTROL STATUS REGISTER
STATUS
;;;IF MI, ERROR
;;~DECREMENT CHARACTER COUNT
;;;IF CS, THEN DONE
;;;CURRENTLY PUNCHING TRAILER?
;nIF PL NO
;;;PUNCH A NULL
;;;BRANCH TO EXIT FROM INTERRUPT
;;;GET NEXT BYTE FROM USER BUFFER
;;;LOAD BYTE IN OUTPUT REGISTER
;;;EXIT FROM INTERRUPT
;;;RESET BYTE COUNT
;;;DISABLE PUNCH INTERRUPTS
;;;CREATE SYSTEM PROCESS
; POINT R4 TO SCB
;POINT Rl TO I/0 PACKET
;
AND PICK UP CHARACTER COUNT
;CALCULATE CHARACTERS TRANSFERRED
;ASSUME SUCCESSFUL TRANSFER
;DEVICE ERROR?
;IF PL NO
;UNRECOVERABLE HARDWARE ERROR CODE
;INITIATE I/O COMPLETION
;BRANCH BACK FOR NEXT REQUEST
; i; SAVE

DEVICE TIMEOUT RESULTS IN A NOT READY MESSAGE BEING PUT OUT 4 TIMES A
MINUTE. TIMEOUTS ARE CAUSED BY POWERFAILURE AND PUNCH FAULT CONDITION
PPOUT:
80$:

213
214

215
216
217
218
219
220
221
222

223
224

225
226

227
228
229

BCS
TSTB
BPL
CLRB
BR
CALL
MOVB
JMP
INC
CLR
CALL
MOV
MOV
MOV
SUB
MOV
TST
BPL
MOV
CALL
BR

S.CSR(R4) ,R4
(R4)+,U.CW3(R5)
60$
#1, U. CNT (RS)
50$
U.CW2(R5}
30$
(R4)
40$
$GTBYT
(SP)+, (R4)
$INTXT
U.CNT(RS)
-(R4)
$FORK
U.SCB(RS) ,R4

CLRB
CLRB
MOV
MOV
BPL
MOV
ASL
BMI
TST
BPL
MOV
MOVB
DECB
BNE
MOVB
CALLR
. DSABL

@S.CSR(R4)
PS
#IE.DNR&377,RO
U.CW2(R5) ,Rl
70$
#IE.AB0&377,RO
Rl
70$
@S.CSR(R4)
20$
#T.NDNR,RO
#l,S.CTM(R4)
S.STS(R4)
PPPWF
#15. ,S.STS (R4)
$DVMSG
LSB

;;;DISABLE PUNCH INTERRUPT
;;;ALLOW INTERRUPTS
;ASSUME DEVICE NOT READY ERROR
;ARE WE WAITING FOR DEVICE READY?
;IF PL NO, TERMINATE I/O REQUEST
;ASSUME REQUEST IS TO BE ABORTED
;ABORT REQUEST?
;IF MI YES
;PUNCH READY?
,•TH'
.......

....DT.

Vi:;'~
.... .i...a._,

;SET FOR NOT READY MESSAGE
;SET TIMEOUT FOR 1 SECOND
;TIME TO OUTPUT MESSAGE?
; IF NE NO
;SET TO OUTPUT NEXT MESSAGE IN 15. SEC
;OUTPUT MESSAGE

CANCEL I/O OPERATION-FORCE I/0 TO COMPLETE IF DEVICE IS NOT READY

230
231
232 PPCAN:
233
235 10$:

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

236
237

.END

234

5-9

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 248K 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/0 transfers, however, use
physical addresses 18 bits in length. Since the PDP-11 word size is
16 bits, some scheme was necessary for internal representation of an
address until it was actually used in an I/O operation.
One choice may have been to carry about the hardware virtual address.
This, however, was rejected since lengthy conversions are involved,
especially when the user for whom the address was being manipulated
was not presently mapped into the memory management registers.
Additionally, a scheme was needed whereby
the
mapped/unmapped
characteristic of a given system would be relatively transparent to
device drivers.
The choice was made to encode two 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 ACDRESS 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 32-word block

Bits 6-12

Block number

Eits 13-15

Page Address Register Number (PAR#)

A-1

DEVELOPMENT OF THE ADDRESS DOUBLEWORC
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.
This 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.
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
six is placed in bits 13-15 to enable use of PAR #6, which will be
used by the Executive to service I/O for program transfer devices.
For non-program transfer (NPR) devices, the driver requirements for
manipulating the address doubleword are direct and are discussed with
the description of U.BUF in section 3.1.4.1.

A-2

APPENDIX B
SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

J TASK ABORT CODES

,.'; NOTE:

ARE ALSO SST VECTOR OFFSETS

S,CO~DwS.CFLT

rODO ADDRESS AND TRAPS TO 4
rSEGMENT FAULT
rBREAK POINT OR TRACE TRAP
r!OT INSTRUCTION
rILLEGAL OR RESERVED INSTRUCTION
rNO~ RSX EMT INSTRUCTION
rTRAP INSTRUCTION
,11140 FLOATING POINT EXCEPTION
,ssT ABORT•BAD STAC<
tAST ABORT•BAD STACK
JABORT VIA DIRECTIVE
JT4SK LOAD REQUEST FAILURE
rTASK C~ECKPOINT READ FAILURE
JTASK EXIT WITH OUTSTANOI~G I/0
JTASK ~EMORY PARITY ERRO~

S,C04D:"8'0,
S,CSGF="B'2.
s,cBPT:"B"LI,

S,CIOT:'8"6,
S,CILI:"8'8,
S,CEMT:'8"1 ! ,
S,CTR?:'B'12.
1

S,CFL T:'8" 1Lle
S,CSST='8" 16!!
S,CAST:'R'l~.

S,CAB0:"6'2',1,

S,CLi:(F:"..,'22,
S,CCRF:"8"24.
S,IOMG:'8"26,

S,?RTV:'B"2l3.
TAS~

TER~I~ATION

NOTIFICATION

~ESSAGE

CODES

sDEVICE NOT READY
sDEVICE SELECT ERROR
sC~ECKPOI~T WRITE FAILURE
tCARD READER HARDWARE ERROR

T,~D~R•'B'v
•

~ ........ r:-_ "~ " ...
J I I'!
I.I i) i;;. i i , !::'.
t::;

T,NC~Fm'S'4
T,~CRE:"B"e

T.ND~O:"S'~.

sDISMOUNT COMPLETE

T,NLD~~='B"12.
T,~LU"::1'P.'14,

rLI~K

DO~~ CNET~ORKS)
C~ET~ORKS)

tLINK UP
ABODF$

, ;,.14CRO
,Er-.;i)M

, Er~ D~

r+
r CLOCK QUEUE CONTROL BLaCK OFFSET
f

S CLOCK QUEuE

CO~TROL

DEFI~ITIO~s

BLOCK

OF CLOCK QUEUE CONTROL BLOCKS, EACH CONTROL
HAS
'sr THERESAMEARE FIVE TYPES
IN
FIVE
AND DIFFERS
REMAINING THREE

,
,.
J

~LOCK

T~E

FO~~AT

FOLLO~I~G

T~E

FI~ST

~ORDS

CONTROL BLOCK TYPES ARE DEFINED:

B-1

T~E

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

rMARK TIME REQUEST
1TASK REQUEST WITH PERIODIC ~ESCMEDULING
,sI~GLE SHOT TASK ~EQUEST
rSI~GLE SHCT I~ TERNAL SYSTE~ SU8~0UTil\iE (IDE NT)
rSI~GLE S~OT I~TER~AL SYSTE~ SUB~OUTI~E (TASK)

,MRKT:'8'0
,SCHO:'e'2
,SSHT:'e'u
,SYSTs'8'6
,SVTK='8'8,

CLOCK QUEUE CONTROL BLOCK TYPE INDEPENDENT OFFSET

DEFI~TIO~S

,ASECT
=0
,L.NKa'L'

,tlLKY1 ~QT1'L' ,9LKB
,Ef~s'I..' ,eLKB
,TC61'L.' 1 "3LKw
,8Ll(W
1 TIM1'L'
C~OCK

sCLOCK QUEUE THREAD ~ORD
JREQUEST TVPE
sEVE~T FLAG NUMBER (MARK TIME ONLY)
tTCB ADDRrss OP SYSTE~ SUBROUTINE IDENTIFICATID~
rABSOLUTE TIME wMEN REQUEST CO~ES DUE

1
1
1

QUEUE CONTROL BLOCK•MARK TIME

:C,TIH+l.l
,AST1'L'
DST1'L"

,9L!<~"I

CLOCK QUEUE CONTROL BLOCK•?ERIODIC RESC~EDULI~G

.8LK~

CLOCK QUEUE

CO~TROL

BLOCK•SINGLE SHOT

:C,TI1.1+4
I

DE~ENOENT

sSTART OF
AL I(~...

• 8Li~

CLOCK QUEUE
THERE ARE

sT~O

2
1

1
"

CO~TQOL

~EPE~QENi

BLOCK•SINGLE

OFFSET

DEFE~DENT
~ORDS

DEFI~ITIO~S

AREA

U~USEC

rSCHEDULI~G

S~OT

UIC

I~TERNAL

SUBROUTI~E

CFFSET

DEFI~ITIONS

r-o TYPE CODES FOR THIS TYPE OF REOUESTs'L"

TYPE &:SINGLE S~OT
Tyo~

~=SI~GLE

SHOT

INTE~N4L
INTE~~AL

SU~RGUTI~E

SU8ROUTINE

~IT~
~IT~

:C,TI"~+~

7START OF

,SUB1'L' ,ALt<;., 1

,suBROUTI~E

ADn~ESS

,r~o

~aRnS

, Bl'<;"

,LGT~='~'.

nEPE~tE\T

U~USED

rLE~GTH

'"ACRC

• E"·!"I 'A
• E";:; ~·

A 16 BIT VALUE AS A' IDE~TIFIER,
A TCB ADDRESS AS A~ IDENTIFIER,

AREA

OF CLOCK QUEUE

,PSE.CT
1

CFFSET DEFINITIONS

tSTART OF DE?ENDE'T AREA
,RESCHEDULE INTERVAL I~ CLOCK TICKS
tSCHEDULI!l.iG UIC

:c:,TI~+i.1

,RSI1'L' ,BLK;.; 2
,UIC1'L'

DEFINITIO~S

tSTART OF DEPENDENT AREA
tAST ADDRESS
rFLAG ~ASK WORD FOP 'SIS" SOURCE
rADORESS OF 'BIS' DESTI~ATIO~

,8Ll<!"i
,SRC:'L' .BLKLli
1

OFFSET

DEPENDE~T

C:LKDF$

B-2

CO~T~CL

BLOCK

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

,.,

J DEVICE

CC~T~OL

BLOCK

DEVICE
' THE
TYPE
THE

CO~TROL BLOCK (DCB) DEFI~ES GENE~!C INFO~~ATICN ABOUT A DEVICE
LO~EST ANC HIGHEST UNIT NU~BERS, THERE IS AT LEAST ONE DCB
FOR EACH DEVICE TYPE IN A SYSTEM, FOR E~A~PLE, IF THERE ARE TELETV?ES I~ A
SYSTEM, THEN THERE IS AT LEAST ONE DCB ~ITH THE DEVICE NAME 'TT', IF PART
OF THE TELETYPES ~ERE I~TERFACED VIA DL11•A'S A~D THE QEST VIA A 0~11, T~E
THERE ~OULD BE TWO DCB'S, ONE FOR ALL DL11•A INTERFACED TELETYPES, AND ONE
FOR ALL D~11 INTERFACED TELETYPES, A SI~ILAR SITUATION WOULD ARISE IF 4

J
J

SYSTEM CONTAINED TWO RK11 DISK CONTROLLERS, ONE DCB WOULD SE REQUIRED
FOR EACH COMTROLLER,

'
J

r
r

A~D

,ASECT
,:0

0,LNKt'L' 1 8LKW 1
D,UCBa'L' ,eL~W 1
O,NAMs'L' ,3LKW 1
D1 UNIT1'L' ,8LKB 1
,8LKB
1
D,UCBLl'L' ,8LKw 1
0 1 DSP1'L' .BLKw 1
O,MSKI'~' ,aLKW 1
,8LK~
1
,8L~W
1
,BLK~
1
,8LKw
1
,BLK~
,8LK~
,BL~~

rLINK TO ~EXT DCB
sPOINTER TO FIPST UNIT CONTROL BLOCK
sGENERIC DEVICE ~A~E
tLOWEST U~IT NUMBER COVERED BY THIS DCB
rHIGHEST UNIT NUMBER COvEQED av THIS DCB
,LENGTH OF EAC~ U~!T CONTROL BLOCK IN BYTES
r?OINTER TO DRIVER DISPATCH iABLE
,LEGAL FU~CTIO~ MASK CODES 0•15,
JCONTROL FUNCTION ~ASK CODES 2•15,
7NOP'ED FUNCTIO~ ~ASK CODES ~·15~
rACP FUNCTION ~ASK CODES ~-1s.
rLEGAL FUNCTION ~ASK CODES 16 1 •31,
;CONTROL FU~CT!O~ ~ASK coots lbi~11i
r~O?'EO FUNCTION ~ASK CODES 16,•31,
rACP FUNCTION ~ASK CODES lb,•31,

,?SECT

r+
r DRIVER DISPATC~ TABLE OFFSET DEFINITIONS

D,VINI='B'0
D,VCAN:'8'2
O,VOUT:'8'4
D,VPWF:'B'e
,~AC~O

rDEVICE INITIATOR
rCANCEL CURRENT I/0 FUNCTIO~
rDEVICE TI~EOUT
tPOWERFAIL RECCVE~Y
DCBDF$ 1 X1 V

,END~

,E~O~

B-3

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

,MACRO

F11DFS

,A SECT
,:0

V,TRCT: , 1'LK_..
V,IFWII , 8LK\.o'
V,FCB: • ~LK:\'li
V,IBL81 ,RLKB
V1 IBSZ1 • t'L'<~
.~u<:.·;

V,FMAXi • ~LK ,•j
V,WISZ: .~LK8
V,SBCL: • eu<R

v,sesz: , 8LKi<i

8LK8

V,SBL~I

V,FIEX:

.~LK~

1
1

.~L~~

1
1
1
1
1

, 8Lt<: i.:

, RLKi11
I BLK:;.,

V, V0 W~JI
V,VPROt
V,VCHA:
V,FPROt
V,VFSQ:
V,FRB<r
V,LRUCt

1
1
2
1
1
1

, 2L t< i•
• 8LKw
,P.LKR

1
1

AL-<8

1
1

, i?Li<1-

V1 LGTH1

, FILE
BLOC!<
''
,ASECT

•TRANSACTION COUNT
,I~OEX

FILE

~INDO~

rFILE CO~TRDL 8LOCK LIST HEAD
,INDEX SIT MAP 1ST LB~ HIGM BYTE

1INDEX BIT ~AP SIZE IN BLOCKS

,I~OEX BITMAP 1ST LBN LOW BITS
sMAX NO, OF FILES ON VOLUME
sDFLT SIZE OF WINDO~ IN NO, Of ~TRV ~TRS
sVAL.UE IS < 128,
sSTORAGE eIT ~AP CLUSTER FACTOR
sSTORAGE ~IT MAP SIZE IN 8LOCKS
rSTORAGE 8IT ~AP 15T LS~ HIGH BYTE
JDEFAULT FILE EXTE~D SIZE
tSTORAGE 8!T ~AP 1ST LBN LOW BITS
rVOLU~E C~VER'S UIC
tVOLUMf ~ROTECT!O~
tVOLUME CHARACTERISTICS
,voLu~F. DErAULT FILE PROTECTION
rVOLUME FILE SEQUENCE NU~BER
JNU~BER OF F~EE BLOCKS ON VOLUME MIG~ BYTE
JCOUNT OF AVAILABLE LRU SLOTS IN FCB LIST
JNU~BER CF FREE BLOCKS ON VOLUME LOW BITS
,SIZE IN ~VTES OF VCB

CO'-.;Tl.fOL

,:0

F,L.INI<: , F3LK><

~LK:w

1
1

F,FNU~~I

F,FSEQI • ?.>LI< ~'i
F,FOWN:
F,FPROa
F1 UCHA1
F,SCHAa
F,HDLBI

~Ll<.'I

1
1
1

,8LKR

,13LK8
,8LKw

F,L.BNs

, BL.Kt..

F,SIZE: ,6LK~·1
F,NACS: ,FiLl<'.i
F,NLCK: ,BLKR

1 8LKw
, BL Kt.,;
I

S,ST~K=,•F,LB~

1
F,STATI ,BL Kw
F c • I'; _A c=1 0 0 ~ 0 e
FC,DIR:40~H~e

FC,CEF=20v.l~~

FC,Fcr.::10;0n
F,O~EFt

8LKlh

F,DRNM: , 8LKr·
I

'3LK11;

1
1
1

,FCB CHAIN POINTER
1Fil.E NUt-4BER
JFILE SEQUENCE NUMBER
JU1'iUSED
JFIL.E O~~ER'S UIC
1FILE PROTECTION CODE
,usER CO~TROLLED CHARACTERISTICS
rSVSTEM CONTROLLED CHARACTERISTICS
rFILE ~EADER LOGICAL BLOCK NUMBER
1BEGINNI~G OF STATISTICS BLOCK
rLBN OF VIRTUAL BLOCK 1 IF CO~TIGUOUS
J3 IF NON CO~TIGUOUS
1SIZE OF FILE IN BLOCKS
rNO, OF ACCESSES
rNO, OF LOCKS
rSIZE OF STATICS BLOCK
tST4TUS BITS FOR FCB CO~SISTING OF
rSET IF FILE ACCESSED FOR wRITE
rSET IF FC8 IS IN DIRECTORY LRU
,SET IF ~!RECTORY EOF NEEDS UPDATING
sSET IF TRYING TQ FORCE DIRECTO~Y CO~TIG
JDIRECTORY EOF BLOCK NUMBER
11ST WORD OF DIRECTORY NAME
1UNUSED
JSIZE IN BYTES OF FC8

B-4

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
WIN00"1

,ASECT
,:0

wI cTL I

rLO~ BYTE
rHIG~ ~YTE

BI..~ \~

wI I RDV='AM
~I,lliRV:10Z~

~I,EXT•2000
~I,LC1<:40ioe

wI I DLK: 100r.t!
1-i I I 8?5: 1000QHl!

W,VBN1

61..KB

w,WISZs .BLKB

,BLKw

W,FCB1
W,RiRVi

1
1

81..Kw

,PSECT
,MACRO
1 ENDM

,; ... TASK

CONSISTS OF T~E FOLLOWING BITS
,READ VIRTUAL BLOCK ALLO~E~ IF SET
tWRITE VI~TUAL BLOCK 41..LC~ED IF SET
tEXTEND ALLO~ED IF SET
tSET IF LOCKEb AGAINST SHARED ACCESS
rSET IF DEACCESS LOC~ ENABLEn
rBYPASS ACCESS INTERLOCK IF SET
t~IGH BYTE OF 1ST VB~ MA~PED BY WINDOW
tSIZE IN RTRV PTRS OF ~I~oow C7 BITS)
rLOW ORDER WORD CF 1ST veN ~APPED
r'ILE CO~TROL BLOCK ADDRESS
;OFFSET TO 1ST ~ETR!EVAL ~OINTER !~ ~!NDO~

F11DF$

,E~DM

F110F$
F 11 OF!

,~ACRO

HDRDF!,L,B

~EADER

= ~ OF ~AP ENTRIES ACTIVE

OFFSET DEFINITIONS

, ;D

,ASECT
,:0
H,CSPa'L',BLK~
1
H,HDLN:'L',BLKW 1
H,PCBT1'L',8LKW 4
H,PCBC1'L' 1 8LKW 3•4
1
1 BLK~
H,OSWs'L',BLKW 1
H,FCSi'l.',BLK""
HI FORT I , L, I BL K~.,

H1 0l/l..Yi't..' 1 BLl<W

H1 RSVD1#L#16LKW i

H,EFL~i'L'.BL~W 4
H1 CuIC1'L',8LKW 1
H,DUICi'L',BLK~ 1
H1 IPS1'L',BLKw 1
H,IPC1'L',8LK~
H 1 ISP1'L' 1 BLK~
H.ODVAl'L',BL~~

1
1

H,OOVL1'L',BLKw 1
H,TKVAs'L',8LKw 1
H,TKVL1'L' 1 8LK~

H1 PFVA1'L',8LKW 1

H,FPVA1'L' 8LKW 1
1

H,RCVAs'L',8LK~

1
1
H,FPSAs'L',BLK~ 1

, 8LK1~:

,8LK~
1
H,GARDa'L',8LKW 1

H1 NLUN1'L' 1 8LKW 1
H 1 LUN1'L' 1 8LK~

,PSECT
1 "'~ACc:?O

JCURRENT STACK POINTER
JHEAOER LENGTH I~ BYTES
rTASK PARTITION DESCRIPTOR
rCOM~ON PARTITIO~ DESCRIPTORS
,sou~ORY ~ORO FOR PCB ADDRESSES (ALWAVS:0)
JT•SK DIRECTIVE STATUS ~ORD
rFCS IMPURE POI~TER
rFORTRAN I~PURE POikTER
,ovERLAY I~PURE POINTER
rRESERVED ~OINiER LOCAilON
r~VENT FLAG ~ASK wORDS
rCURRENT TASK UIC
rDEFAULT TASK UIC
tINITIAL ~RCCESSOR STATUS WORD (PS)
JINiiIAL PROGRAM COUNTER (PC'
tINITIA~ STACK POI~TER CSP'
tODT SST VECTOR ADDRcSS
rOOT SST VECTOP LE~GT~
rTASK SST VECTOR ADDRESS
rTASK SST VECTOR LENGT~
JPOWER FAIL ~ST CONTROL BLOCK ADDRESS
JFLOATING POINT AST CONTROL 81..0CK ADDRESS
JRECIEVE 4ST CONTROL BLOCK ADDRESS
rRESERvEO WORD
sPOINTER TO FLOATING POINT/EAE SAVE AREA
JRESERVEC lot>Ot<D

r?CINTER TO HEADER GUARD wQRD
OF LUN;S
rSTART OF LOGIC4L UNIT TABLE
tNUM8E~

HDRl)F$

IE ND'~
, E!\Dr-B-5

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS
,~ACRO

HWDDF! 1 L,9

r+
r HARD~ARE QEGISTER ADDRESSES AND STATUS CODES

,ADDRESS CF
rADDRESS OF

MPCSR:'B' 17771.J.o
MP.ARz'B' 112rneo

INTERRUPT REQUEST REGISTER
PRIORITY 0
r?ROCESSOR PRIORITY 1
rPROCESSCR PRIORITY ~
rPROCESSOR PRIORITY 5
rPROCESSOR PRIORITY ~
t?ROCESSOR PRIORITY 7
f PROCESSOR STATUS WORD
rCONSOLE SWITCH A~D DISPLAY REGISTER
JCONSOLE TERMINAL PRI~TER STATUS REGISTE~

PIRQ:'e'177772

rPROGRAM~ED

f PROCESSOR

PR0:'9'<~
PR1:'8'~0
PR4m'9'2~?

PR5:'8'2'-'0
PR&s'B'300
P~ 7 : " B ' 3 tp;,
PS:'B' 177776
Sl-!Rm'B' 177S7rJ

TPS='B'177SbU

,. EXTENOED

,.
J

PD?•tl/7~ MEMORY PARITY REGISTER
FI~ST MEMORY PARITY REGISTE~

ARITH~ETIC

ELEMENT REGISTERS

,IF DF

rACCUMULATOR
rMULTIPLIER•QUOTIENT
JSHIFT COUNT

AC:"B' 1773n
tw1Q:'B' 1773;t4
SC:'B'17731~

, E ~.!DC

J+

,.'

MEMQRV HANAGEMENT HARDv.iARE

,IF ')F"
KOSAR~:'B'1723&0

l<DSDRC!i:'8' 17232~~
KISARt~:'e' 17231.rn

REGISTERS AND STATUS CODES

MU~GE

a KERNEL D PAR 0

s KER~!EL D PDR !?,
JKE~NEL

I PAR

\/;

l<IS~Ro:'B'172354

'KERNEL I PAR 6

KISAP7:'9'172356

rKERNEL I

KISDR?:'R'1723C"~

si<ERNEL I PDR Ill
,KERNEL I PDR 6

KISD~b:'8'172314

KISDR7="E·'17231b

S I S DR -~: " 8 ' 17 2 2 7 0
UDS.AR(1:'E'177660
UDSQR?!:'B"' 177o2e
UISAR0:'f?,'17764~

UISAr.<tJ:'F'177bS?
UISARS:'~"177652
UISA~o='~'177bSU
UISA~7:'8"177656
UISn~~:'6' 1776?:'?

rKERNEL

I=' AR

I PAR 7

,suPEl:(VISOR I ?DR
,us ER D I' AR ~
rUSER I) PDR e
rUSER I PAR ~
rUSER I PAR u
,usE~ I PAR s
,usE~

f:l AR

I PAR 7
1USER I PDR el
sUSE~

UISD~S:'P'177ti12

,us ER I POR 4
sUSER I PDR s

UISDRo:'6"17761t.t
UISDR7:"B" l 77"16

JUSER

UISDr;(u:'B' t 77bH

JUSER .,I P DR b

B-6

PDR 7

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

tUNIBUS ~APPING ~EGISTE~ 0
,CURRENT MOOE FIELD OF PS WORD
tPREVIOUS ~ODE FIELD OF PS WORD
,SEGMENT STATUS REGISTER 0
tSEGMENT STATUS REGISTER 3

UBMPR:"B'170200
CMODE="B" 1401t'.'~0
PMODEz'8'32~~!?J

SR0="B"177572
SP3:"B" 172Slb

,ENDC

,. FEATURE
,.
J

SY~BOL

DEFINITIONS

FE,EXT:'e"l
FE,MU?:"8'2
,MACRO

f 11170

EXTENDEO MEMORY SUPPORT
PROTECTION SUPPO~T

t~ULTI.USER

HillDCF$

, END!'t.
• E t\Jj) I;

,!IF NDF 5!$YDF , ,LIST

S LOGICAL

ASSIGNMENT CONTROL BLOCK

LOGICAL ASSIGNMENT CONTROL BLOCK CLCB) IS USED TO ASSOCIATE A
'r THE
LOGICAL
A PHVSICAL DEVICE UNIT, LCB'S ARE
TOGETMER
NA~E

t
f

~ITH

TO FO~M THE LOGICAL ASSIGN~ENTS OF • SYSTEM,
s A SYSTEM ~IDE OR LOCAL CTERM!NAL) BASIS,

LIN~ED
~AV

ASSIGNMENTS

,ASECT
,:0
L,LN~:"L" ,8LKW 1
L,NAMt'L" ,SLKw 1
L@UNITa"L" ,BLKB 1
L,TYPEa'L" ,BLKB 1
L.UCB1"L' ,8LKW 1
L,ASG1"L' 1 8LK~ 1
L1 LGTM:"8" 1 •L 1 LNK
PSECT

tLINK TO NEXT LC8
rLOGICAL N•ME OF DEVICE
rLOGICAL UNIT NU~BER
rTY~E OF E~TRY C0•SYSTEM WIDE)
'TI UCB ADDRESS
rASSIGN~ENT UCB ADDRESS
'LENGTH OF LCB

,~AC~O

~CBDF!,X,Y

IE t..; D~···
I

END 1-t.

B-7

BE ON

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

,MACRO

PCBDFS

' PARTITION CONTROL BLOCK OFFSET

,•0

,A SECT

P,LNKI ,BLK~
P,NAMI ,BLKw
P,suea 1 8LKW
P 1 MUN I ,Bl.KW
P,REl.1 ,BLKW

P,SIZE1 ,Bl.Kl"
P,BL.t<Si
P 1 ~AIT1

P,SWSZI
P,BUSYI
P,TCB1
P,NAPRI
P,STATI

P,PDR1
P,HORI

DEFI~ITIO~S

2
1

1
1
1

,BL.KW
,BLl<1'1
,SL.KB
,BLKW
,BL.KB
,Bl.KB

1
1
2
1
1
1

,IF DF

~UMGE

rLINK TO NEXT PARTITION PCB
JP•RTITION ~AME 1N RAD50
rPOINTER TO NEXT SUBPARTITIO~
,POINTER TO MAI~ PARTITION
JSTARTING PHYSICAL ADDRESS OF PARTITIO~
,SIZE OF PARTITION IN BYTES
•SIZE OF PARTITION IN 32W BLOC~S (SYSTEM ONLY)
rPARTITION WAIT QUEUE LISTHEAD (2 WORDS)
rPARTITION SWAP SIZE (SYSTEM ONLY)
,PARTITION BUSY FLAGS
rTCB ADDRESS OF OWNER TASK
rNUMBER OF APR;S TO LOAD
rPARTITION STATUS rLAGS

tCONTENT! OF LAST ?DR TO BE LOADED
rPOINTER TO HEADE~ CONT~O~ BLOCK

8Liti~

,SLl<W

,IFF
P,~DR•P,REL

sPOINTE~

TO HEADER CONTROL BLOCK

,E~DC

P,LGTH•,

•LENGTH OF PARTITION CO~TROL BLOCK

,?SECT

J+

' PARTITION STATUS BYTE BIT OEFINITIO~S
sLIBRARY OR COM~O~ BLOCK (t:VES)
rPOSITIO~ !~DEPENDENT LIB~ARV OR COM~o~ C1=VES)
9SYSTE~ CONTROLLED ?A~TITION C1•YES)
rORIVER IS LOADED IN PARTITIC~ (1:VES)
rSTARTING APR ~U~BER MASK

PS.C0~=2~17i

PS 1 PIC:10e

PS,SVS•4'il
PS,DRV:20i
PS,APRa7

'• ~.•CRO

,ENDM
,ENDM

PCBDFS

B-8

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

J+

,.
I

ASE.CT
tAST

, 1'.'L i<"
A,C8Ls'L' .P.U<L..
A,BYT1'L' ,3LK"°!

A,AST1'L'

~UEUE

THREAD

~a~D

t LE ''GP~ 0 F C0 ~1 T R 0 L 3 L 0 CK
r~UMSE; CF BYTES TC
JAST TRA~ ADOR~SS

,3LK~

,~u~sEq

A,t>.iPRl'l.' ,RL"W
A,?RM1"L' ,;;jLK""

tFIRST AST

AST

I ~ 8 VTES
ALLOCATE ON TASK STACK

PAR4MET~RS

P!~A~ETEq

,.
t

~/0

PACKET CFFSET

,ASECT
.=~

sI/C QUEUE TMREAD
JREGUEST PRIORITY

I,LNK1'L' .~L~:•.,
I,PRis"L' ,'3Li<8
I,EfN:'L' ,r~L'<l3
I , TCBI ' I. ' , ~ L;.c; ...:

sEVE~T

I • v~ 2 1 , L, • '3 LKi•!
I,iJCBi'L' ,;Li<"'
I,FCNi'L' ,8L,.K..-J

I,IOSB:'L'

,flLK~

, ~ L '< '"
, ~ L K '•1

I 1 AST1'L'
!;PR~!'~'

,3L~~
;~L<~

, l:L-< IA!

1
1

1
1
6

I,LGTH:::'P',
,PSECT
• ·"'ACRC
• E,, DM
IE.{\;

~ORD

FLAG Nu~eER

1TCB ADDRESS CF ~EQUESTOR
sPOINTER TO SECO~D LUN wo~o
7POI~TER TO U~IT CO~TROL BLOCK
J!/O FUNCTIO~ CODE
sVIRTUAL AOD~ESS OF I/0 STATUS BLOC
JI/0 STATUS 8LOCK RELOCATO~ BIAS
7!/0 STATUS BLOCK ADDRESS
sAST SERVICE ROUTINE ADDRESS
t~ESERVEC FOR ~APPI~G PAR4~ETER *1
t?A~AMETERS 1 TO 6
JLE~GTM OF I/0 REQUEST CO~TROL BLOCK

PKTCF'$

n¥.

B-9

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

rus CO~T~OL ALOCK
STATUS CONTROL BLOCK CSCB)

DEFI~ES "TME STATUS
I~ A SVSTE~.
EX?AND ON T~E TELETYPE

OF A DEVICE CO~T~OLLER,
IS POI~TED TO
BLOCKS, TO
ABCVE, EACH TELE•
~ I~TERFACEO VIA A DL11•A ~auLD HAVE A see SI~CE EACH DL11•A IS A~ tN.
~NOENT I~TERFACE U~IT, THE TELETYPES INTERFACED VIA T~E ~~11 ~O~LD 4LSO
~ ~AVE AN SCA SINCE T~E DH11 IS A SI~GLE CONTROLLER ?GT ~ULTIPLEXES MA~Y

scg FO~ EACM CO~TROLLEP

~E IS C~E
J~IT CO~TROL

T~E SCF
EXA~PLf

rs !1'; PAIULLEL,
,A SECT
r12
la'L' ,9LK6 1
~l'L' ,BLKB 1
ti'L' ,?LK;.« 1
q'L' ,BLKi.. 1
1'L' 1 8Lli<"' 2

CF REGISTE~S TO COPV a~ ERROR
,OFFSET TO FI~ST DEVICE ~E(!STE~
JSAVE~ I/0 ACTIVE e!TµAP A~D POI~TER TO EMB
rDEVICE I/O ACTIVE BIT MASK
rCO~TROLLE~ I/0 QUEUE LIST~EAD
sDEVICE PRIORITY
rINiERRUPf VECTOR 40nRESS /4
rCUR~E~T TIMEOUT COU~T
flNITIAL T!MfOUT COU~T
rCO~TRCLLER INDEX
rCONTROLLEP STATUS c~=IDLE,1:8USY)
JADD~ESS OF CC~TPCL STATlS ~EGISTE~
t4DDRESS OF CuPRE~T I/C PACKET
,FORK/TI~E REQUEST BLOC~ LINK ~ORD
rFOqK-PC/TI~f-QuEuE ~EGUfST TYPE
sFORK•RS/TIME·REQUEST IDE~TIFICATIO~
,~u~SER

1'L' ,BLKE' 1
1·L~

8L.f'\8 i

l'L' ,eLKB 1
8LKB 1
8Ll<8 1
1'L' .~Li'6 1
:'L' ,BLl'I'.~ 1
:'L' 1 8Ll'<W 1
:'L' 1 8LKW 1
1
1 8LK1Aii

1'L'
:'L'

,8L1<1<
1

''L'

9LK 1•·
.~LK .;

,PLK~

''L'

.~LK'"'

·us

CC\T~CL

tFORK•R4/TIME•LO~ 0~DER TI~E
tFCRK•U~~SED/TIME·~IG~ ORCER

TI~f/C~AN~EL CONTROL
sFORK·U~USED/TiwE•S0R~CUTI~E ADD~ESS
r11/7~ EXTE~DED ~e~o~v U~I?uS rEVICE C•SLCCK

1
1

RLOCK

P~IQRITY

BVTE

CC~DITIO~

CODE STATLS

':~~'1

JERRCQ

::-Q'2

sERRCR

LCGGI~G

E~ARLEJ

::'P.'~

JERq~~

~CGGI~G

AVAILA~LE

JSPARE B!'T'
• :-., Ac c; l'
IE~;

c,,

~QOG~fSS

fi c eDF .~ , x , v

IE "·C p

B-10

~IT

~fFI~ITIO~s

(1:VES)
(J:YES)

(1:VES)

bLCC~

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

,.t TASK
BLOCK OFFSET
,.'' TASK CONTROL BLOCK
CG~T~OL

AND

STATUS

DEFI~ITIO~S

,4SECT
• =l"

rUTILITY LINK ~C~D
JTASK PRIO~ITV
tI/0 PENDit-.G COIJ''T
tPOINTER TO T,LNK OF TCB ITSELF
tTASK ~A~E I~ RADS0
s~ECEIVE QUEUE LISTHEAD
sAST QUEUE L!ST~EAO
•TASK LOCAL EVE~T FLAGS 1•32
rUCB ADDRESS FDR PSEUOO DEVICE 'TI'
sTASK LIST T~READ WORD
sTAS~ STATUS ~ORD AND EXTENSION BYTE
rLBN Or TASK LOAD IMAGE
tUCB ADDRESS OF LOAD DEVICE
tPCB ADDRESS OF TASK PARTITION
s~AXIMUM SIZE OF TASK IMAGE CM•PPEO ONLY)
tADDRESS OF NEXT TASK IN ACTIVE LIST
JLENGTH 0~ iASK CONiROL S~OCK
tLENGTH OF TC8 EXTENSION

T,LNKl'L. ,BLKW 1
T,PR!t'L' ,BLKB 1
T,IOC1'L' ,9LK8 1
T1 TC81'L' ,8LK~ 1
T,NAM1'L' ,9LK~ 2
T,RCVLs'L' ,BLKw 2
T,ASTLs'L' ,RLKW 2
T,EFLG1'L' ,BLKW 2
T,UCB1'L' ,3L~~ 1
T,TC9Lt'L' ,8LK~ 1
T,STAT:'L' ,BLKB 3
T,LBN:'L' .~L~8 3

T,LDV1'L'
T PCB1'L'

,BLK~ 1
,BLK~ 1
T,MXSZ:'L' ,BLK~ 1
1

T,ACTLs'L' ,BLKw 1
T,LGTH:"B",
T,EXT:'e',•T,LGTH
,i-'SECT

,. TASK STATUS DEFINITIONS
t

;

,. TASK STATUS wORO
J

JTASK IS IN EXECUTION C~=;B'YES)
J!/0 RUN DOWN I~ PROGRESS C1='B~YES)
tAST RECOGNITION DISABLED C1='B'YES)
JABORT ~ESSAGE BEING OUTPUT C1:;B'YES)
JDUMP TASK ON SYNCHRONOUS ABORT (0:YES)
JTASK STOPPED FOR TER~INAL INPUT C1•YES)
9RE~OVE TASK ON EXIT Cl:'B;VES)
t~NCIL~ARY CONTRO~ eROCE$SqR (1:'B'YES)
rAST IN PROG~ESS C1='8'YES)
rTASK IS C~ECKPOI~TABLE C0•'B'YES)
tTASK BEING FIXED IN MEMORY C1•'B'YES)
rTASK FIXED IN ~EMO~Y C1•'8'YES)
JTASK IS OUT OF ~EMORY C1=;B'YES)
rTASK IS CHECKPOINTED C1m'8'YES)
,CHECKPOINT REQUESTED Cl•'S'YES)
sCHECKPOINT DISABLED C1='B'YES)

TS,EXE='~"li?0000

TS, RD~ z 'B' 4 ,? ~ 0 0

TS, DST:'~'201'?.00
TS,MSG="~"1~000

TS,PMD:'8"4.J00
TS,STP:'6'221V-0
TS,RE'-1:'8' 1~~z,

TS,ACP:'8''100
TS, .AST:'8'200
TS, CHK:'S' H0
rs.en:='B'4~
TS,FXD:"8'2~

TS,OUT:'B'P
TS,Ci<:P:'B'LI
TS,CK~:'~'2

TS,CKJ:'8"'1

,.'+ TASK
f

,.
J

TAS~

BLOCKI~G

STATUS MASK

STATUS BYTE

EXTE~SION

B-11

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

rTASK IS BEING HALTED Cl='R'YES)
sTASK IS PRIVILEGED C1:'8'YES)
'TASK ~A~KED FOR A80~T Cl:'B'VES)
sTASK REQUESTED AS EXTERNAL MCR FUNCTIO~ C1='B'YE5)
rSAVED TS,SPN a~ AST IN PROGRESS
sTASK SUSPENDED Ct='B'YES)
rSAVEO Ts.~FR o~ AST I~ PROG~ESS
sTASK IN WAITFO~ STATE (1:'8'VES)

S,HLT:'B'200
S,PRV:'8'10~
S,ABO:'B'Q~

s.~·cR:'8'2~
S,SPN:'8'U~
S,SPN:i'B'~

s,wF~='B'2

S,WFRa'8'1
,MAC~O

TCBOF$

,ENOM
,END~

+
UNIT

CO~TROL

BLOCK

THE UNIT CO~TROL BLOC~ (UCB) DEFI~ES T~E STATUS OF A~ I~DIVIOUAL DEVICE
UNIT AND IS THE CONT~OL BLOCK T~AT IS POINTED TO 6Y THE FIRST ~ORD OF
AN ASSIGNED LU~, THERE IS ONE UCB FOR EACH DEVICE U~IT OF EACH DCB, THE
UC8'S ASSOCIATED ~ITK ~ PART!CULA~ DCB ARE CONTIGUOUS !~ MEMORV A~O A~E
POINTED TO BY THE DC8 1 UCB'S ARE VARIA8LE LENGT~ 8ET~iEEN DCB'S BUT ARE
OF TME SA~E LENGTH FOR A SPECIFIC DCB. TO FINISM THE TELETYPE EXAMPLE ABOVE,
EACH UNIT ON BOTH INTERFACES ~OULD HAVE A UCB,
•
,ASECT
:0

l,OCB1'L' ,BLKiiJ

rBACK POINTER TO DCB
tPOINTER TO REDI~ECT UNIT
;CO~TRCL PROCESSING FLAGS

l,REDr'L" .RLK1oi
l,CTL1"L' ,BLKB

1.sTS1'L' .eLK~ 1
l.UNITs'L' ,BLKB 1
l 1 ST21'L' ,8LK8 1
l,CW1t'L' 1 8LKw 1
J,CW21'L' ,BLKw 1
l,CW31'L'

1 8LK~

tUNIT ST.ATUS

sPHVSICAL UNIT Nu~8ER
'UNIT STATUS EXTENSION
,FIRST DEVICE CHARACTERISTICS WORD
rSECOND DEVICE C~A~ACTERISTICS wQRD
rTHIRD DEVICE CHARACTERISTICS ~ORO
tFOURT~ DEVICE CHARACTERISTICS ~ORD
rPOINTER TO SCB
sTCB ADDRESS OF ATTACHED TASK
,RELOCATION BIAS OF CURQENT I/O REQUEST
s9UFFER ADDRESS OF CURRE~T I/0 REQUEST
tBYTE COU~T OF CURRENT I/0 REQUEST
JADD~ESS OF TCB OF ~OUNTED AC?
JADORESS OF VOLU~E CONTROL BLOCK
tCO~TPOL 8UFFE~ ~ELOCATIDN A~D ADDRESS
rTER~INAL UIC CTERMINALS ONLY)

1.cwu1'L' ,BLKW 1

J,SC81'L' ,BLK~ 1
J,ATT1'L' ,BLKw 1
J,8UF1'L' 1 BLK~ 1
, BL!<!Ai

J,CNT1"L' 1 6LKW 1
J,ACP:'8'U 1 Cl\iT+2
J,VCB:'e'U,C"1T+4
J , CBF : ' 8 ' U• C~.: T+2
J,UIC='3'U,C~T+<9,•2>

,PSECT

'+ DEVICE TABLf STATUS

J
J
J

UC~

DEFI~!TIO~S

,. DEVICE CHARACTERISTICS

~ORD

1 CU,CW1) DEVICE TYPE CEFINITION BITS,

B-12

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

JRECORO ORIENTED DEVICE C1•YE5)
sCARRIA.GE CONTROL DEVICE C1=YES)
rTERMINAL DEVICE C1•YES)
;FI~E SiRUCTURED DEVICE C1mYES)
rSINGLE DIRECTO~Y DEVICE C1•YES)
rSEQUENTIAL DEVICE (1•YES)
JUNIT SOFTWARE ~qITE LOCKED Cl•YES)
,PSEUDO ~EVICE (1•YES)
tOEVICE IS MOUNTABLE AS COM C~ANNEL C1•YES)
tDEVICE IS MOUNTABLE AS Flt DEVICE C1•YES)
tOEVICE IS MOUNTABLE Ct:YES)

CV,REC='B'1
OV 1 CCL.•'6'2
OV,TTV:'A'tJ
OV,,DIR='B'U
OV,S0h'B'20

OV,SQDr:'8"40
OV,SWL.•'6''+000
DV,PSE•'B~10000

DV,COM='B'20000
OV 1 F11•'B'400e0
OV,MNT•'8'U!tl000

,.' TERMINAL DEPENDENT CMARACTERISTICS WORD 2 CU,CW2l BIT
,.

U2 1 0H1•'B'100000

9UNIT IS A DH11/DJli (1:YES)
JUN!T IS A DJ11 Ct=YES)
tUNIT IS REMOTE C1=YES)
rUSER LOGGED ON TE~~I~AL C~=VES)
tLOWER CASE TO UPPER CASE CO~VERSION C1=YE5

U2,DJ1•'B'4~000
U2,~MTl:'8'20000

U2 1 1.0G:'8"4e0
U2,LWC•'B'200
U2,0FF:'B'100
U2 1 PND:'8"40
U2,AT,='B'2i2!
U2,PRV:'B'10
U2,L.3S:'B•4
U2,VT5•"8#2
U2,Sl.V='B'1

,.
J

RH11•RS~3/RS0~

tOUTPUT IS TURNED OFF C1•YES)
rOUTPUT BYTE PENDING (1•VES)
JMCR CO~MANO AT, BEING ?ROCESSEO C1=YES)
tUNIT IS A PRIVI~EGED TERMI~AL (1:YES)
tUNIT IS A LA30S TERMIN~L C1•YES)
;UNii IS • VT05B TERMINAL C1•VES)
'UNIT IS A SLAVE TER~INAL C1•YES)
CHARACTERISTICS WORD 2 CU,CW2) 8IT OEFI~ITIONS

U2,R04•'8'102000
t+

,.
'

R~11•TU1b

DEFI~1 ITIONS

'UNIT IS A RS04 C1•VES)

CHARACTERISTICS WORD 2 (U,CW2) BIT DEFINITIONS

U2 1 7CH•'B' 12H~0~

rUNIT IS A 7 CHANNEL DRIVE C1=YE5)

r+
, UNIT CONT~OL PROCESSING FLAG DEFINITIONS

UC 1 ALGs"a•200
UC 1 NPR:'8'100
UC,QUE•'8'40
UC,PWF:'8"2~

UC. AT TII, 8, h~

UC,KIL='B'4
UC,LGHz'8"3

rBYTE Al.IGNMENT ALLOWED C1:N0)
'DEVICE IS AN NPR DEVICE C1•VE5)
sCALL DRIVER BEFORE QUEUING C1=YES)
,CALL DRIVER AT PO~ERFAIL ALWAYS (1~YES)
,cA~L. DRIVER o~ ATTACH/DETACH C1=VES)
rCALL DRIVER AT I/0 KILL ALWAYS C1•YES)
rTRANSFER LENGTM MASK SITS

,., UNIT STATUS BIT DEFINTIONS

B-13

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

,UNIT IS 8USV C1sVESl
rUNIT IS ~OUNTED (0m'B'VES)
,u~IT IS ~OUNTED AS FOREIGN VO~U~E C1=VES)
,u~IT IS ~A~KED FOR DIS~OUNT C1mYES)

US,SSY:'8'27:0
US,MNT:z'8' 1;ij0
US 1 FOR:'e't.1J.
us.~01-1='~'2;~

,.
,.' UNIT STATUS EXTENSION BIT

nEFI~ITIONS

1UNIT CFFLINE C1=VES)
rUNIT REDIRECTABLE C~=YES)

IJS,Ofl.:'?'1
US,RE0:'8'2

,. CARD qEADER DEPENDENT UNIT STATUS BIT DEFINITIONS
,.
f

tUNIT IS
rU~IT IS

US,AB0='~'1

US,i"IDE:'1'2
f+

r FILES•11

OEPEN~ENT

U~IT

TE~HI~AL

DEPE~DENT

sUNIT IS DISAB~EO C1:YES)

rUNii IS WAITING FOR CA~RIER C1:YES)
,uNIT HAS ECHO IN ~ROGRESS C1=YE5)
rUNIT IS EXPECTI~G OUTPUT INTERRUPT C1mVES)

us,c~w='~'a

US,ECH:'8'2
US,OUT:'8'1
t

LPS11

CHECK E~A~LE~ C1:YES)

UNIT STATUS BIT DEFI~ITIONS

US,DS8:'8'1CA

IF NOT READY (l•YES)
~ODE (1:YES)

FO~ A60RT
TRA~SLATION

STATUS BITS
r~RITE

~A~KED
I~ 029

DEPE~DENT

U~IT

STATUS BIT DEFINITIONS

, Ill

tFORK IN FROGRESS C1:VES)
p R0GR Es s c 0=, e , v Es )

US,FQK:'~'2

us I s H~ =, s , 1
,MACPO
,E':')tt.·
IE "-'D ~

, s HA RE AeLE Fu ~Jc TI 0\I I !\;

UCBDF$,X 1 V

B-14

INDEX
Address doubleword, A-1

Bootstrapping the new system, 2-8

Cancel I/O, 1-4
Crash output, 2-19
Create Fork process ($FORK), 1-11,
4-3
Creating the address doubleword,
A-1
Creating the data structure, 2-2
Creating the driver source code,
2-4

Data items on the stack, 2-18
Data structure and driver source,
5-2
Data structure, source format
of the, 2-4
Data structures 1 1-5, 3-1, 5-2
Data structures and their inter~
relationships, 1-17
Data structure~, creating, 2-2
Data structures summary, 1-20
Data structures (system),
symbolic definitions, B-1
DCB, 1-6, 3-9
DCB fields, required,
D.DSP, 2-3, 3-11
D.LNK, 2-2, 3-10
D.MSK, 2-3, 3-12
D.NAM, 2-2, 3-10
D.UCB, 2-2, 3-10
D.UCBL, 2-3, 3-10
D.UNIT, 2-3, 3-10
Debugging Tool, Executive, 2-9
Device Control Block (DCB), 1-6,
3-9
Device description, 5-1
Device interrupt, 1-4
Device interrupt vector, 1-9
Device message output, 4-1
Device timeout, 1-4

Development of the address doubleword, A-1
Driver code, 5-5
Driver debugging, 2-7
Dump output, panic, 2-19
$DVMSG, 4-1
Executive Debugging Tool, 2-9
Executive I/O processing, 1-3
Executive services, 1-9
Executive services available to
I/O drivers, 4-1
Fault,
classifications, 2-10
immediate servicing, 2-11
internal SST, 2-16
isolation, 2-10
non-normal SST, 2-17
other pertinent isolation data,
2-12
tracing, 2--13
FCS, 1-2
Flow of an I/O request, 1-14
$FORK, 1-11, 4-3
Fork list, 1-9
Function codes for I/O, 3-15
Function masks,
ACP, 3-13
control, 3-13
legal, 3-13
no-op'ed, 3-13

Get Byte ($GTBYT) , 4-4
Get Packet ($GTPKT), 1-11, 4-5
Get Word ($GTWRD), 4-6
$GTBYT, 4-4
$GTPKT, 1-11, 4-5
$GTWRD, 4-6

Including a user-written driver an example, 5-1
Incorporating tasks into the
system, 2-8

Index-1

INDEX (Cont.)
Incorpor,4ting the user~written
driver, 2-1, 2-7
Interrelation of the I/O control
Blocks, 1-7
Interrupt exit ($INTXT) , 4-8
Interrupt Save ($INTSV), 1-11,
4-7
$INTSV I 1-11, 4 ....7
$INTXT, 4-8
I/O alternate entry, 4 .....9
I/O control blocks, interrelatibnship of the, 1-7
$IOALT, 4-9
$IODON, 1-11, 4-9
$IOFIN, 4-10
I/O Done ($IODON), 1-11, 4-9
I/O Driver, role of an, 1-4
I/O finish, 4-10
I/O function codes, 3-15
I/O hierarchy, 1-1
I/O initiator, 1-4
I/O Packet, 1-8, 3-2
I/O Packet fields,
I .AST, 3-6
I. EFN, 3-4
I.FCN, 3-5
I.IOSB, 3-5
I.LN2, 3-4
I.LNK, 3-4
I.PRI, 3-4
I.PRM, 3-6
I.TCB, 3-4
I.UCB, 3-5
I/O philosophy, 1-1
I/O processing, Executive, 1-3
I/O Queue, 1-8
I/O request, flow of an, 1-14
I/O system - philosophy and
structure, 1-1

Mapped system header, 2~15
Mask word creation, 3-14
Masks, function, 3-12

Panic dump output, 2-19
Post-driver initiation services,
1-10
Power failure, 1-4
Pre-driver initiation processing,
1-10
Processing at priority 7 with
interrupts locked out, 1-13
Process-like characteristics of
a driver, 1-12

Processing at fork level, 1-14
Processing at priority of interrupting source, 1-13
Programming conventions, 1-12
Programming protocol, 1-12
Programming standards, 1-12
$PTBYT, 4-11
$PTWRD, 4-12
Put Byte, 4-11
Put Word, 4-12

QIO, 1-3

Re-assembly, 2-7
Rebuilding and re-incorporating
the user driver, 2-7
Rebuilding the Executive, 2-8
Register conventions, system
state, 4-1
Required Device Control Block
(DCB) fields'
D.DSP, 2-3, 3-11
D.LNK, 2-2, 3-10
D.MSK, 2-3, 3-12
D. NAM, 2-2 I 3-10
D.UCB, 2-2, 3-10
D.UCBL, 2-3, 3-10
D.UNIT, 2-3, 3-10
Required Status Control Block
(SCB) fields,
s . CON , 2- 4 I 3 -18
S.CSR, 2-4, 3-18
S.ITM, 2-4, 3-18
S.LHD, 2-4, 3-17
S.PRI, 2-4, 3-17
S.STS, 2-4, 3-18
s . VCT I 2-4 I 3-1 7
Required Unit Control Block (UCB)
fields,
U.ATT, 2-3, 3-25
U.CTL, 2-3, 3-21
U.CWl, 2-3, 3-23
U.CW2, 2-3, 3-24
U.CW3, 2-3, 3-24
U.CW4, 2-3, 3-24
U.DCB, 2-3, 3-21
U.RED, 2-3, 3-21
U.SCB, 2-3, 3-24
U. ST2, 2-3, 3-23
U.STS, 2-3, 3-22
U.UNIT, 2-3, 3-23
Role of an I/O driver, 1-4

Index-2

INDEX (Cont.)

SCB, 1-6, 3-16
SCB fields other than required,
S .CTM, 3-18
S .FRI<, 3-19
S .PKT, 3-19
SCB fields, required,
S.CON, 2-4, 3-18
S.CSR, 2-4, 3-18
S.ITM, 2-4, 3-18
S.LHD, 2-4, 3-17
S.PRI, 2-4, 3-17
S.STS, 2-4, 3-18
S. VCT, 2-4, 3-17
Service calls, 4-1
Source format of the data structure, 2-4
SST fault,
internal, 2-16
non-normal, 2-17
Stack structure,
data items on stack, 2~18
internal SST fault, 2-16
non-normal SST fault, 2-17
Status Control Block (SCB}, 1-6,
3-16
Structure, 1-1
Symbolic definitions: system
data structures, B-1
System data structures symbolic
definitions, B-1
System header,
mapped, 2-14
unmapped, 2-15
System-state register conventions,
4-1

Tasks, incorporating into the
system, 2-8
UCB, 1-6, 3-19
UCB fields other than required,
U.BUF, 3-25
U.CNT, 3-26
UCB fields, required,
U.ATT, 2-3, 3-25
U.CTL, 2-3, 3-21
U.CWl, 2-3, 3-23
U.CW2, 2-3, 3-24
U.CW3, 2-3, 3-24
U.CW4, 2-3, 3-24
U.DCB, 2-3, 3-21
U.RED, 2-3, 3-21
U.SCB, 2-3, 3-24

Index-3

UCB fields, required (cont.},
U.ST2, 2-3, 3-23
U.STS, 2-3, 3-22
U.UNIT, 2-3, 3-23
Unit Control Block (UCB), 1-6,
3-19
Unmapped system header, 2-14
Updating the executive object
module library, 2-7
User-written drivers, Incorporating, 2-7

Writing an I/O driver - programming specifics, 3-1

XDT, 2-9

RSX-llM Guide to Writing an I/O Driver
DEC-11-0MWDA-B-D

READER'S COMMENTS
NOTE:

This form is for document comments only. Problems
with software should be reported on a Software
Problem Repcrt (SPR) form

Did you find errors in this manual?

If so, specify by page.

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

Is there sufficient documentation on associated system programs
required for use of the software described in this manual? If not,
what material is missing and where should it be placed?

Please indicate the type of user/reader that you most nearly represent.
[] Assembly language programmer
[] Higher-level language programmer
[] Occasional programmer (experienced)
[] User with little programming experience
[]

Student programmer

[] Non-programmer interested in computer concepts and capabilities

CitY~~~~~~~~~~~~~~State~~~~~~-Zip Code~~~~~~~

or
Country
If you require a written reply,

please check here.

[]

·-----------------------------------------------------Fold llere------------------------------------------------------------

·---------------------------------------- Do Not Tear - Fold llere and Staple ----------------------------------------------FIRST CLASS
PERMIT NO. 33
MAYNARD. MASS.
INESS REPLY MAIL
POSTAGE STAMP NECESSARY IF MAILED IN THE UNITED STATES

age will be paid by:

Software Communications

P. O. Box F
Maynard, Massachusetts

01754

digital equipment corporation

Printed in U.S.A.