Digital PDFs

AA-H267B-TC

March 1982

312 pages

Original

12MB

Document:	RSX-11M-PLUS Guide to Writing an I/O Driver
Order Number:	AA-H267B-TC
Revision:	0
Pages:	312
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_plus/RSX11Mplus_V3.0_Jul85/AA-H267B-TC_RSX-11M-PLUS_V2.0_Guide_to_Writing_an_IO_Driver_Mar82.pdf

OCR Text

RSX-11 M-PLUS
Guide to Writing an I/O Driver
Order No. AA-H267B-TC

RSX-11 M-PLUS Version 2.0

digital equipment corporation · maynard, massachusetts

First Printing, October 1979
Revised, March 1982
The inf~rmation in this document is subject to change without notice
and sh~uld not be construed as a commitment by Digital Equipment
Corporation. Digital Equipment Corporation assumes no responsibility
for any errors that may appear in this document.
The software described in this document is furnished under a license
and may be used or copied only in accordance with the terms of such
license.
No rospJnsibility is assumed for the use or reliability of software on
equipment that is not supplied by Digital Equipment Corporation or its
affiliated companies.
C~pyright

1979, 1982 by Digital Equipment Corporation
All Rights Reserved.
Printed in U.S.A.

The postpaid READER'S COMMENTS form on the last page of this document
requests the user's critical evaluation to assist in preparing future
documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DEC/CMS
DECnet
DECsystem-lO
DECSYSTEM-20
DECUS
DECwriter

DIBOL
EduSystem
IAS
MASSBUS
PDP
PDT
RSTS

RSX
UNIBUS
VAX
VMS
VT

~DmDDmD
ZK21S0

HOW TO ORDER ADDITIONAL DOCUMENTATION
n Continental USA and Puerto Rico call

800-258-1710

n New Hampshire. Alaska. and Hawaii call
n Canada call

603-884-6660

613-234-7726 (Ottawa-Hull)
800-267-6146 (all other Canadian)

)IRECT MAIL ORDERS (USA & PUERTO RICO)·
Digital EqUipment Corporation
P a Box CS2008
Nashua New Hampshire 03061

DIRECT MAIL ORDERS (CANADA)
Digital Equipment of Canada Ltd.
940 Belfast Road
Ottawa, Ontario K 1G 4C2
Attn: A&SG Business Manager

DIRECT MAIL ORDERS (INTERNATIONAL)
Digital Equipment Corporation
A&SG Business Manager
c/o Digital'S local subsidiary or
approved distributor

• Any prepaid order from Puerto Rico must be placed
With ihe local Digital subSidiary (809-754-7575)
nternal orders should be placed through the Software Distribution Center (SOC), Digital Equipment
Northboro, Massachusetts 01532

~orporatlon.

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

CONTENTS

Page
PREFACg

SUMMARY OF TECHNICAL CHANGES
CHAPTEH 1
1.1
1.2
1.2.1
1.2.2
1.3
1.3.1
1.3.2
1.3.3
1.3.4
1.4
1.4.1
1.4.2
1.4.3
1.4.4
1.4.5
1.4.6
1.4.7
1.4.8
1.4.9
1.5
1.5.1
1.5.2
1.5.3
1.6
1.7
CHAPTER 2
2.1
2.1.1
2.1.2
2.1.3
2.1.4
2.1.5
2.2
2.2.1
2.2.2
2.2.3
2.2.4
2.2.5
2.2.6
2.3

xiii

RSX-IIM-PLUS I/O DRIVERS
VECTORS AND CONTROL AND STATUS REGISTERS •
• • 1-1
SERVICE ROUTINES • • • • • • • • •
••••
1-2
Executive and Driver Layout
• • • • • 1-2
Driver Contents • • • • • • • • • • • • • • • • 1-4
EXECUTIVE AND DRIVER INTERACTION •
• • 1-4
The Driver Process • • • • • •
• 1-4
Interrupt Dispatching and the Interrupt Control
Block • • • • • • • • • • • • • • •
• • 1-5
Interrupt Servicing and Fork Proce~s •
• • 1-8
Nonsense Interrupt Entry Points
• 1-9
ADVANCED DRIVER FEATURES •
1-10
Overlapped Seek I/O
• • • • •
1-10
Dual-Access Support
• • • •
• • • ••
1-11
Delayed Controller Access
• • •
• • ••
1-11
Controller Reassignment and Load Sharing •
1-11
Common Interrupt Dispatching •
••••••
1-12
Subcontroller Devices
1-13
Full Duplex Input/Output • •
1-13
Buffered Input and Output
• • ••
1-14
I/O Queue Optimization •
• • ••
1-14
DISTRIBUTED I/O
• • • • • • •
1-16
UNIBUS Run Mask
• • • • •
• • •.
1-16
Conditional Fork.
• • • • •
1-17
Processor-Specific Functions.
1-17
OVERVIEW OF INCORPORATING A USER-WRITTEN DRIVER
INTO RSX-IIM-PLUS
• • • •
1-18
SPR SUPPORT
• • • • • • • • • • . • • ••
1-20
DEVICE DRIVER I/O STRUCTURES
I/O STRUCTURES • • • • • • •
••••
Controller Table (CTB) • •
• • • •
•
Controller Request Block (KRB)
.
Device Control Block (DCB) • • • • • • • • • • •
Unit Control Block (UCB) •
• •••••••
Status Control Block (SCB) • • • • • • • •
•
DRIVER DISPATCH TABLE (DDT)
•••••••••••
I/O Initiation. • •
•
Cancel I/O • • • • • • • • • • • • • • • •
•
Device Timeout • • • • • •
• ••••
Device Power Failure • • • • • • • • • •
•
Contro lIe r and Un i t Sta tus Change
• • • • •
Device Interrupt Addresses • • • • • •
• •
TYPICAL CONTROL RELATIONSHIPS
• • • • • • •
iii

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

CONTENTS
Page

2.3. 1
2.3.2
2.3.3
2.3.4
2.4
CHAPTEP 3
3. 1
3. 1. 1
3.1.2
3.2
3.2. 1
3.2. 2
3.2. 3
3.2.4

CHAPTER 4

Multiple Units per Controller, Serial Unit
Operation
•••••••••••••••
Single Controller, Serial Operation
Parallel Unit Operation
••••••••
Multiple-Access (Dual-Access) Operation
OVERVIEW OF DATA STRUCTURE RELATIONSHIPS •

·
• •
·
•

2-7
2-7
2-8
2-9
2-10

EXECUTIVE SERVICES AND DRIVER PROCESSING
FLOW OF AN I/O REQUEST • • • • • • •
••••
Predriver Initiation Processing
••••
Driver Processing
••••
• ••.
EXEC_lIVE SERVICES AVAILABLE TO A DRIV~R .
Get Packet ($GTPKT)
•••••
• • •
Interrupt Save ($INTSV)
•
Create Fork Process ($FORK)
I/O Done ($IODON or $IOALT)
•

•
•
·
·
•
•
•
•

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

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER

4. 1
4. 1. 1
4. 1. 2
4.2

PROGRAMMING STANDARDS
• 4-1
Programming Protocol Summary • . .
• 4-1
Accessing Driver Data Structures • •
· 4-2
OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER DATA
BASES
• • • • • • • • • • • • • . • • • . • • • . 4-2
General Labeling and Ordering of Data Structures 4-2
4.2. 1
4.2.2
Device Control Block Labeling
. • • • . • • • • 4-3
Unit Control Block Ordering
• • • • • • • • • • 4-3
4.2. 3
4.2.4
Status Control and Controller Request Blocks • • 4-3
4.2.5
Controller Table • • • • • • • • • • • • • • • . 4-3
OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER CODE • 4-4
4.3
Generate Driver Dispatch Table Macro Call - DDT$ 4-4
4. 3. 1
4.3. 2
Get Packet Macro Call - GTPKT$ • • • •
. . 4-6
Interrupt Save Macro Call - INTSV$ • . . . • • . 4-8
4.3. 3
Usage of UCBSV Argument in Macro Calls • •
. 4-8
4.3.4
4.3. 5
Specifying a Loadable Driver
. • • • . 4-9
Loadable Driver Entry Points for LOAD and UNLOAD 4-9
4.3.6
4.4
DRIVER DA7A STRUCTURE DETAILS
• • • • •
4-10
4.4.1
The I/O Packet • • • • • • • • • • • • •
4-11
4.4.2
The QIO Directive Parameter Block (DPB)
4-14
4.4. 3
The Device Control Block (DCB) • •
4-16
4.4.3.1
Establishing I/O Function Masks
••• •
4-22
4.4.4
The Unit Control Block (UCB) • • • • . • • • .
4-27
The Status Control Block (SCB) • .
4-37
4.4. 5
4.4.fi
The Controller Request Block (KRB) • • • •
4-45
4.4.7
Continuous Allocation of the SCB and KRB .
4-53
4.4.8
Controller Tabl~ (CTB) • • • •
. • •.
4-53
4.5
DRIVER CODE DETAILS
• • • • •
4-59
4. 5. 1
Driver Dispatch Table Format •
4-60
4.5.2
I/O Initiation Entry Point.
4-63
4.5. 3
Cancel Entry Point • • • • • .
4-64
Device Timeout Entry Point • •
4-fi5
4.5.4
Next Command Entry Point. • •
4-65
4.5.5
4.5.6
Queue Optimization Entry Point
4-65
De~llocation Entry Point • • • •
. • ••
4-66
4.5. 7
Power Failure Entry Point
4-66
4.5.8
Controller Status Change Entry Point •
4-66
4.5.9
Unit Status Change Entry Point.
4-68
4.5.10
Interrupt Entry Point
• • • • • • • • .•
4-69
4.5.11
Volume Valid Processing
4-70
4.5.12

CONTENTS
Page
CHAPTEH 5

INCORPORATING A USER-SUPPLIED DRIVER INTO RSX-1lM-PLUS

5.1
5.1.1
5.1.2

GUIDELINES FOR INCORPORATING A DRIVER • • • • • • 5-1
Incorporating a Driver at System Generation
5-1
Incorporating a Loadable Driver with a Loadab1e
Data Base After System Generation • • • • • • • 5-2
5.2
WHAT THE SYSTEM GENERATION PROCEDURE DOES FOR YOU 5-3
5.2.1
Assembling the Driver and Data Base
• 5-3
Inserting the Driver and Data Base Modules in
5.2.2
the Library • • • • • • • • • • • • •
• • 5-4
5.2.3
Task Building the Driver • • • • • • •
5-4
5.2.4
Loading the Driver • • • • • • • • • • • • • • • 5-5
5.2.5
Making the Devices Accessible
• • ••
5-6
5.2.5.1
Setting Vector and CSR Assignments • •
5-6
5.2.5.2
Placing a Controller and Units(s) On-Line
5-7
CSR and Vector Assigment Errors • • • • • • • 5-8
5.2.5.3
5.3
USER-SUPPLIED DRIVER SYSTEM GENERATION DIALOGUE
SUMMARY • • • • • • • • • • • • • • • • • • • • • 5-9
Choosing Executive Options • • • • • • • • • • • 5-9
5.3.1
Choosing Peripheral Configuration
5-10
5.3.2
LOAD PROC'ESS ING • • • • • • • •
• • • ••
5-11
5.4
LOAD Operations and Diagnostic Checks • • • •
5-11
5.4.1
';.4.2
Use of /CTB in LOAD • • • • • • • • • • • • •
5-14
CHAPTEH 6

DEBUGGING A USER-SUPPLIED DRIVER

CRASH DUMP ANALYSIS SUPPORT ROUTINE
• • • • 6-1
6.1
6.2
THE EXECUTIVE DEBUGGING TOOL •
• • • •
6-1
XDT Commands • •
• • • • • • • • • • 6-2
6.2.1
XDT Start Up • • • • • • • •
• 6-2
6.2.2
XDT Restrictions • • • • •
• 6-3
6.2.3
XDT General Operation
• • 6-4
6.2.4
XDT and Debugging a User-Supplied Driver •
• 6-4
6.2.5
6.3
FAULT ISOLATION • • • • • • • •
• • • • • • 6-5
Immediate Servicing • • • • • • • • • •
• 6-5
6.3.1
The System Traps to XDT
• • • •
• • 6-6
6.3.1.1
The System Reports a Crash • • • • • • • • • • 6-6
6.3.1.2
The System Halts but Displays No Information. 6-6
6.3.1.3
The System Is in an Unintended Loop • • • • • 6-6
6.3.1.4
6.3.2
Pertinent Fault Isolation Data. •
• 6-7
TRACING FAULTS • • • • • • • • • • •
• 6-7
6.4
6.4.1
Tracing Faults Using the Executive Stack and
Register Dump • • • • • • • • • •
6-10
Tracing Faults When the Processor Halts Without
6.4.2
Display
•••••••••••••
6-11
6.4.3
Tracing Faults After an Unintended Loop
6-12
Additional Hints for Tracing Faults
6-12
6.4.4
REBUILDING AND REINCORPORATING A LOADABLE DRIVER 6-13
6.5
CHAPTEH 7

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

SYSTEM-STATE REGISTER CONVENTIONS
• • • • • •
7.1
THE ADDRESS DOUBLE WORD • • • • •
• • • • • •
7.2
DRIVERS FOR NPR DEVICES USING EXTENDED MEMORY • •
7.3
Calling $STMAP and $MPUBM or $STMPI and $MPUB1 •
7.3.1
Allocating a Mapping Register Assignment Block
7.3.1.1
7.3.1.2
Calling $STMAP or $STMPI •
••••
••
Calling $MPUBM or $MPUB1 • • • • • • • • • • •
7.3.1.3
7.3.2
Calling $ASUMR and $DEUMR • • • • • • •
••
Statically Allocating UMRs During System
7.3.3
Generation • • • •
• •
SERVICE CALLS • • • • • • • • •
•
7.4
7.4.1
Address Check • • • •
• • • • •
v

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

CONTENTS
Page
7.4.2
7.4.3
7.4.4
7.4.5
7.4.6
7.4.7
7.4.8
7.4.9
7.4.10
7.4.11
7.4.12
7.4.13
7.4.14
7.4.15
7.4.16
7.4.17
7.4.18
7.4.19
7.4.20
7.4.21
7.4.22
7.4.23
7.4.24
7.4.25
7.4.26
7.4.27
7.4.28
7.4.29
7.4.30
7.4.31
7.4.32
7.4.33
CHAPTEH 8
8.1
8.2
8.3

Allo~ate Core Buffer • • • • • • •
• • • • 7-8
Assign UNIBUS Mapping Registers
• • 7-9
Check Logical Block
••••
7-10
Move Block of Data • • •
• • • • • • • • 7-11
Check I/O Buffer • • • • • • • • • • • • • • • 7-12
Clock Queue Insertion
7-13
Convert Logical Block Number •
• • ••
7-14
Deallocate Core Buffer • • •
• • ••
7-15
7-16
Deassign UNIBUS Mapping Registers
7-17
Device Message Output • • • • • •
7-18
Fork • •
• • • • •
7-19
Forkl
• • • • • • • • • •
7-20
• • • • ••
Get Byte •
• • • •
7-21
Get Packet • • • • •
••••
Get Word •
• •••••
• • • • 7-23
7-24
Initiate I/O Buffering.
7-25
Interrupt Save • •
Interrupt Exit • • • • • • • • • •
7-26
7-27
I/O Done Alternate Entry and I/O Done • • • •
I/O Finish • • • • •
• • • • 7-28
Map UNIBUS to Memory
• • • • 7-29
Map UNIBUS to Memory (Alternate Entry) • • • •
7-30
Put Byte • • • • • • • • • • • • • • • •
7-31
Put Word • • • • • • • • • • • • •
• •••
7-32
7-33
Queue Insertion by Priority
••••••
7-34
Relocate • • • • • • • • • • • • • • • •
Relocate UNIBUS Physical Address •
• • ••
7-35
Queue Kernel AST to Task • • • • • • • • • • •
7-36
7-17
Set Up UNIBUS Mapping Address
Set Up UNIBUS Mapping Address (Alternate Entry) 7-38
Test if Partition Memory Resident for Kernel
AST
• • • • • • • • • • • • • • • • •
7-39
7-40
Test for I/O Buffering •

SAMPLE DRIVER CODE
SAMPLE DRIVER DATA BASE
• • • •
SAMPLE DRIVER CODE
• • ••
••• •
HANDLING SPECIAL USER BUFFERS • • • •

• • 8-1
• 8-3
8-12

APPEND} X A

RSX-llM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC
DEFINITIONS

APPEND1X B

CONVERTING A USER-SUPPLIED RSX-llM DRIVER

B.l
B.2
B.2.l
B.2.2
B.2.3
B.3
B.3.l
B.3.2
B.3.3
B.3.4
B.3.5
B.3.6
B.3.7

ASSUMPTIONS AND GENERAL APPROACH • • • • • • • • • B-1
MODIFYING THE DATA BASE CODE • • • • • • • • • • • B-1
Un i t Con trol Block Chang es • •
• • • • B-2
Status Control Block Changes • •
• • • • • B-2
The Controller Table • • • •
• B-3
MODIFYING THE DRIVER CODE • • • • • • • •
• B-4
Conditional Symbols
• • • ••
• • B-4
Controller-Dependent Code
• • B-4
Driver Dispatch Table • • • •
• • B-4
Reconfiguration Support • • • •
8-5
Volume Valid Processing • • • • • • • • • • • • B-5
Converting Logical Block Numbers •
• B-6
Interrupt Entry Processing • • • •
8-6

INDEX

CONTENTS
Page
FIGURES
FIGURE

1-1
1-2
1-3
1-4
2-1
2-2
2-3
2-4
2-5
4-1
4-2
4-3
4-4
4-5
4-6
4-7
4-8
4-9
4-10
4-11
4-12
4-13
4-14
4-15
4-16
4-17
4-18
4-19
6-1
6-2
6-3
6-4
6-5
7-1
B-1
B-2
B-3
B-4
B-5
B-6

Virtual to Physical Mapping for the Executive • • 1-3
Interrupt Dispatching for a Resident Driver • • • 1-5
Interrupt Dispatchj~g for a Loadable Driver
1-7
Interrupt Dispa~chi 19 for Common Interrupt
Devices
• • • • • • • • • • • • •
1-12
Mul~;ple Units per Control]~r, Serial Unit
Operation • • • • • • • • • • • • • • • •
• 2-8
Single Controller, Serial Operation
• 2-9
Parallel Unit Operation (Overlapped Seek)
• 2-9
Dual-Access Operation • • • •
•••••
2-10
Composite I/O Data Structures
• • • •
2-12
I/O Packet Format • • • • • •
4-11
QIO Directive Parameter Block (DPB)
••••
4-15
Device Control Block. • • •
4-17
D.PCB and D.DSP Bit Meanings.
••••
4-22
Unit Control Bloc~
• • • • •
4-28
Unit Control Byte • • • • • • • •
4-29
Unit Status Byte • • • • •
• • • •
4-31
Unit Status Extension 2
4-32
Status Control Block • • • • • • • • • • •
4-38
Controller Status Extension 3 • • • • • • • • •
4-41
Controller Status Extension 2 • • • • • • • • •
4-43
Controller Request Block • • • • •
• • ••
4-46
Controller Status Word • • • • • • • • •
4-48
Continuous KRB/SCB Allocation
4-54
Controller Table • • • • • • • •
4-55
Common Interrupt Table and Table of DCB Addresses 4-57
Controller Table Status Byte • • • • • • •
4-58
Driver Dispatch Table Format • • • • • • •
4-61
Sample Interrupt Address Block in the DDT
4-63
Interaction of Task Header Pointers
• • 6-8
Task Header • • • • • • • • • • • • • • • • • • • 6-9
Stack Structure: Internal SST Fault
6-10
Stack Stucture: Abnormal SST Fault.
6-11
Stack Structure:Data Items on Stack • • • •
6-12
Mapping Register Assignment Block • • • • • • • • 7-4
Contiguous KRB/SCB for DLDRV • • • • • • •
• • B-3
Controller Table (CTB) for DLDRV •
• B-3
Register Pass Routine
(REGPAS)
• • • • • • • • • B-5
Typical Handling of Volume Valid •
• B-5
RSX-llM Logical Block Number Conversion • • • • • B-6
RSX-llM-PLUS Logical Block Number Conversion • • • B-6

TABLES
TABLE

4-1
4-2
4-3
4-4
4-5
4-6
4-7
4-8
4-9
4-10
7-1
A-I

System Macro Calls for Driver Code •
• 4-5
DDT$ Macro Call Arguments
• • • • •
• 4-5
GTPKT$ Macro Call Arguments • • • • • • • • • • • 4-7
INTSV$ Macro Call Arguments
• • • •
• 4-8
Mask Values for Standard I/O Functions •
4-23
Mask Word Bit Settings for Disk Drives • • •
4-24
Mask Word Bit Settings for Magnetic Tape Drives
4-25
Mask Word Bit Settings for Unit Record Devices.
4-26
Labels Required for the Driver Dispatch Table
4-60
Standard Labels for Driver Entry Points
••••
4-62
Summary of Executive Calls for Drivers.
• • • 7-5
Summary of System Data Structure Macros
• • A-I

vii

PREFACE

MANUAL OBJECTIVES
The primary goal of this manual is to introduce RSX-IIM-PLUS physical
I/O concepts, define Exe~ut~ve and I/O service routine protocol,
describe system I/O data structures, and prescribe I/O service routine
coding procedures.
This information is in sufficient det?il to allow
you to:
•

Prepare software that interfaces
supports a conventional I/O device

with

•

Incorporate the user-written
system

•

Detect typical errors that cause the system to crash

•

Use Executive service routines that
typically employs

software

the

into

I/O

Executive
an

and

RSX-IIM-PLUS

service

routine

A secondary objective is to introduce advanced hardware and software
features and sophisticated Executive facilities, and to describe both
the conventional and advanced features of I/O data structures and
mechanisms.
Knowledge of advanced features should facilitate the
understanding of conventional I/O processing and eliminate some of the
confusion inherent in seeing data structures without knowing their
usage.
The manual does not describe how to write software that incorporates
advanced
driver
features.
The only complete package of such
information is DIGITAL-supplied software,
such as DVINT.MAC and
DBDRV.MAC
(for overlapped seek, dual access, and common interrupt
handling);
IOSUB.MAC and TTDRV.MAC
(for full duplex I/O);
and
MMDRV.~1AC
(for subcontroller device operation).
The manual also does
not describe how to attach hardware to the PDP-II, how to perform
diagnostic
functions
to
uncover hardware faults,
nor how to
incorporate DIGITAL-standard error-reporting functions in user-written
software.

INTENDED AUDIENCE
This manual is written for the senior-level system programmer who
is
familicir with the hardware characteristics of both the PDP-II and the
device that the user-written software supports.
The programmer should
also be! knowledgeable about DIGITAL peripheral devices and experienced
in using the software supplied with an RSX-IIM-PLUS system.
The
manual neither describes general Executive concepts nor defines
general system structures.
The manual does describe I/O concepts, the
Executive role in processing I/O requests, and some pertinent aspects
of I/O processing done by DIGITAL-supplied software.
Therefore, with

PREFACE
a firm understanding of hardware characteristics and real-time system
softwaJ-e,
a
senior-level system programmer should be able to
apprec.ate how user-written software interfacing with the Executive
can af::ect overall system performance.

STRUCTURE OF THIS DOCUMENT
This d(,cument is structured to be self-contained so that you need not
refer to any ~ther manual to build and incorporate a user-written
driver into your system. The manual has three types of information:
conceptual, procedural, and reference. The following are abstracts of
the c he! pte r sin the doc um e n t :
•

Chapter 1, "RSX-llM-PLUS I/O Drivers," introduces terms and
concepts
fundamental
to
understanding physical I/O in
RSX-llM-PLUS, and describes the protocol that a driver must
follow to preserve system integrity. It summarizes advanced
driver features and RSX-llM-PLUS capabilities helpful in
becoming
acquainted
with
overall Executive and driver
interaction.

•

Chapter 2,
"Device Driver I/O Structures," continues the
conceptual discussion begun in Chapter 1. It introduces 0n a
general level the software data structures involved
in
handling I/O operations at the device level; examines typical
arrangements of data structures that are necessary
for
controlling hardware functions;
and presents a macroscopic
software
configuration
that
summarizes
the
logical
relationships of the I/O data structures.

•

Chapter 3, "Executive Services and Driver Processing," ends
the conceptual presentation. It summarizes how an I/O request
originates; how the Executive processes the request; and how
a driver would use Executive services to satisfy an I/O
request.

•

Chapter 4, "Programming Specifics for Writing an I/O Driver,"
provides the detailed reference information necessary to code
a conventional I/O driver.
Included is a
summary
of
programming standards and protocol; an introduction to the
programming facilities and requirements for both the driver
data base itself and the executable code that constitutes th2
driver; and an extensive elaboration of the driver data base
and of the driver code.

•

Chapter 5, "Incorporating A
User-Supplied
Driver
into
RSX-llM-PLUS," supplies the procedural information that you
need to assemble and build a loadable driver image, load it
into memory, and make accessible the devices that the driver
supports.
Also included are a summary of
the
system
generation dialogue concerning including user-supplied drivers
and a description of the loading mechanism and the diagnostic
operations performed during loading.

•

Chapter 6, "Debugging A User-Supplied Driver," summarizes
software features provided to help you uncuver faults in
drivers and gives procedures to follow that might prove
successful in isolating faults in drivers.

•

Chapter 7, "Executive Services Available to An I/O Driver,"
gIves general coding information relating to the PDP-II and
RSX-lIM-PLUS Executive service routines.

PREFACE
•

Chapter 8, "Sample Driver Code," shows the source code for the
data base and driver of a conventional device and an excerpt
of source code from a driver that handles special user
buffers.

•

Appendix A, "System Data Structures and Symbol Definitions,"
lists the source code of system macro calls that define system
device structure3, driver-related structures, and system-wide
symbolic offsets needed to access those structures.

•

Appendix B,
"Converting a
User-Supplied RSX-IIM Driver,"
describes the modifications that you must make to enable an
RSX-IIM user-supplied driver to run on an RSX-IIM-PLUS system.

ASSOCIATED DOCUMENTS
Accompanying your RSX-IIM-PLUS system are documents that describe both
the software and hardware on the system.
The software documents are
listed and described in the RSX-IIM-PLUS Information Directory and
Index.
Consult
the
directory
for
concise
summaries-of
software-related pUblications.
Processor and peripherals handbooks
sum~arize
hardware
information published
in various maintenance,
installation, and operator manuals that are provided with your system.

SUMMARY OF TECHNICAL CHANGES

This reVISIon of the RSX-llM-PLUS Guide to Writin<J an I/O
incorporates the followIng technIcal changes and addItions:---

Driver

Two new arguments (BUF and OPT) have been added to
macro call in Chapter 4.

the

DDT$

The I/O Function Masks for Mass Storage, Magtape,
Record Devices have been added in Chapter 4.

and

Unit

Additions have been made to the UCB in Chapt&r 4 as follows:

oL.

•

A new symbolic name U.MUP has been added (redefinition
U. CLI)

•

The DV.MXD offset to U.CWI has been renamed to DV.MSD
mass storage.

for

•

U.UCBX has
devices.

been

added

for

mass

storage

errorlogging

New status control block extension bit definitions
(S2.0PT,
S2.0Pl,
S2.0P2,
and S3.0PT)
have been added to the SCB in
Chapter 4.

New controller bit definitions (KS.MOF,
KS.EXT
have been added to the KRB in Chapter 4.

The Queue Optimization entry point, Deallocation entry point
and the Next command entry point have been added to Chapter
4.

New tracing faults of $HEADR have been added to Chapter 6.

Some Executive routines listed in Chapter 7 have been moved
to new Executive modules and 12 have been added.
The
following is a list of the affected modules and subroutines,
plus the additions:
Routine

Old Module

New Module

$ACHKB
$ACHCK
$ASUMR
$BLKCK
$BLKCl
$BLKC2
$BLXIO
$CKBFI
$CKBFR
$CKBFW
$CKBFB
$CVLBN
$DEUMR

IOSUB
IOSUB
IOSUB
IOSUB
(new)
(new)
(new)
(new)
(new)
(new)
(new)
IOSUB
IOSUB

EXSUB
EXSUB
MEMAP
MDSUB
MDSUB
MDSUB
BFCTL
EXESB
EXESB
EXESB
EXESB
MDSUB
MEMAP

xiii

and

KS.SLO)

SUMMARY OF TECHNICAL CHANGES
Routine
$INIBF
$MPUBM
$MPUBl
$RELOC
$RELOP
$REQUE
$REQUl
$STMAP
$STMPl
$TSPAR
$TSTBF

Old Module

New Module

(new)

IOSUB
MEMAP
MEMAP
MEMAP
MEMAP
IOSUB
IOSUB
MEMAP
MEMAP
REQSB
IOSUB

IOSUB
IOSUB
IOSUB
IOSUB
(new)
(new)

IOSUB
IOSUB
(new)
(new)

xiv

CHAPTER 1
RSX-llM-PLUS I/O DRIVERS

Device drivers on RSX-llM-PLUS are the primary method of interfacing
Executive software with hardware attached to the computer. Most
DIGITAL-supplied hardware l is supported by drivers accompanying the
remaining software that the user receives with the system. This
chaptE~r introduces the concept of device drivers and
explains driver
operations and features.

1.1

VECTORS AND CONTROL AND STATUS REGISTERS

A device controller hds a unique address on the PDP-II UNIBUS that
identifies itself and distinguishes it from other hardware attached to
the computer. At this unique address is usually a control and status
register (CSR) containing data elements that allow software to operate
and interrogate the related device.
The CSR resides in physical
address space that is reserved for device registers and is referred to
as the I/O, or peripheral, page. Other registers associated with the
device are placed in contiguous addresses lower and/or higher than the
CSR address. Software usually controls a device by accessing the CSR
to enable interrupts, initiate a function, and respond to the
resulting interrupt to continue or finish the function.
Associated with many devices can be one or more 2-word areas called
interrupt vectors. A vector provides a connection between the device
and the software that services the device. A vector allows a device
to trigger certain software actions because of some external condition
related to the device.
When ~ device interrupts, it sends the
processor the address of the interrupt vector. The first word of the
interrupt vector contains the address of the interrupt service routine
for that device. The processor uses the second word of the vector as
a new Processor Status Word. Thus, when the processor services the
interrupt, the first word of the vector is taken as the new Program
Counter (PC) and the second word is the new PS.
Space is reserved on the PDP-II for the interrupt vectors. This space
is in the low part of Kernel I-space. The vectors are considered to
be in Kernel mode virtual address space and are thus mapped by the
Executive.
Because the interrupt vector is in Kernel space, the
Executive receives control of the processor on every interrupt. On a
multiprocessor system, each central processor untt has its own vector
space.

1. The CINT$ directive enables a privileged task to gain control when
a device interrupts and thereby to access device registers. ~e
The
K-series Laboratory modules use this feature to perform I/O.
CINT$
directive
is a secondary but equally viable method of
interfacing software to hardware.

1-1

RSX-lH.-P",US I/O DRIVERS
1.2

SERVICE ROUTINES

The service routine that is entered to process an interrupt is most
frequently in the device driver.
Device drivers vary in complexity
depending on the capabilities of the type of device and the number of
device units they service.
A driver can reside with the Executive
itself or can be separated from it. The former driver is resident and
the latter is loadable.
The distinction between resident and loadable drivers is mainly one of
flexibility.
A resident driver is built in during system generation
as a permanent part of the Executive. l It resides in the Executive
address space and cannot be removed. A resident driver responds to
interrupts slightly faster than a loadable driver.
Although linked
into the Executive structures, a loadable driver resides in memory
outside the virtual address space of the Executive. A user can add or
remove a loadable driver by means of an MCR or VMR command.
In
addition, any driver not required for a period of time need not be
loaded.
The space normally occupied by the unloaded driver can hold
user tasks or another driver.
On a system without Executive data
space support, making a driver loadable frees virtual space in the
Executive which can be used for additional pool.

1.2.1

Executive and Driver Layout

A device driver is a logical extension of the Executive that need not
be contiguous in physical memory with the Executive code. Active Page
Registers (APRs) 0 through 4 map the Executive, whereas APR 7 is
reserved to map the I/O page. 2 Resident drivers are mapped within the
Executive space. Loadable drivers reside in a separate partition of
memory and are mapped by APR 5. Therefore, a loadable driver is by
default restricted to the 4K words of space mapped by APR 5 unless it
controls its own mapping with APR 6 to gain access to an extra 4K
wo rds.
The virtual to physical mapping on a system
support is shown in Figure 1-1.

with

Kernel

data

space

Virtual addresses 0 through 4K words (APR 0) of I and D space overmap
the same physical memory.
The mapped area contains the interrupt
vectors, processor stack, processor-specific memory locations, and
interrupt control block
(ICB)
pool space as well as some Executive
code.
I-space virtual addresses 4K through 20K words
(APRI through
APR 4) map the remaining Executive code, which is therefore limited to
16K worjs.
D-space virtual addresses 4K through 20K words
(APR 1
through APR 4) map the dynamic storage region (or pool) and system
data structures to a maximum of 16K words.

1. On systems with Executive data space support, all drivers
loadable.

must

2. ActiJe Page Register is a term referring to the KTll Memory
Management register pair
(Page Address Register
(PAR)
and Page
Descriptor Register (PDR).) Refer to the relevant processor handbook
for
information on hardware mapping and memory management. Refer to
the RSX-I1M/RSX-llM-PLUS Task Builder Manual for a description of
mappTng and APR asslgnmen~y software.
1-2

RSX-llM-PLUS I/O DRIVERS

Physical Memory
Address Space
I/O Page

32K Words

Virtual
Kernel
D-Space

Virtual
Kernel
I-Space

APR 7

28K Words

32K Words
28K Words

Privi leged Task
or
Driver

APR 5

20K Words

Processor n
Specific 1

APR 1

4K Words

- - APR 0

OK Words

Dynamic Storage
Region

APR 1

- - -

4K Words

APR 0

System Resident
I/O Data Base

OK Words

Executive
Code

Processor 0
Specific

10n multiple processor systems, each additional processor requires its own processor-specific area in the CPU partition.
ZK-245-81

Figure 1-1

Virtual to Physical Mapping for the Executive

Virtual addresses 20K through 28K words (APR 5 and APR 6) of I and D
space overmap the same physical memory, which is reserved to map
loadable drivers and privileged tasks in Kernel mode.
(Although APR5
and APR6 are reserved for drivers, the Executive maps only APR5 when
it calls a driver.) Finally, virtual addresses 28K through 32K words
(APR 7) of I and D space overmap the I/O page.
Thus, a device driver is mapped with the Executive code and the I/O
page.
When a driver has control, it can access the device registers
in the I/O page to perform its operations. It also has available all
the Executive service routines to help it process I/O requests.
Because· of
functions
routines.
coding in
reduced to

the layout of the Executive and device drivers, many common
related to I/O are centralized in the Executive as service
This commonality eliminates the inclusion of repetitive
each and every driver. Coding in each driver is therefore
handling the specific functions of the device supported.

1-3

RSX-llM-PLUS I/O DRIVERS
1.2.2

Driver Contents

A dev.ce driver consists of two parts. One part is the executable
instrllctions of the driver itself. This part has the entry points to
the driver. The entry points are those places where the Executive
calls the driver to perform a specific action, and their addresses are
estabJished in the driver dispatch table (DDT).
The table contains
addref,ses of routines in a fixed ord~~ so that the Executive can enter
the driver at the appropriate place for a given action.
The other part of a device driver is the data structures forming the
data base that describes the controllers and units supported by the
driver. Two structures, the controller table (CTB) and the controller
reque~t
block (KRB) , describe the controller of the device being
supported. Because the CTB supplies generic information about the
contrcl:er type, only one CTB need exist for each controller type on a
systerr. The KRB holds information related to a specific controller
and tterefore each controlJer has its associated KRB.
Three structures in the driver data base--the device control block
(DCB) , the unit control block
(UCB) , and the status control block
(SCB)--describe the device as a logical entity.
The DCB contains
information related to the type of device, whereas the UCB holds
information specific to an individual unit of the device. The SCB is
used mainly to store data (driver context) concerning an operation in
progress on the device unit.
The code of a driver must be in one continuous portion of main memory.
Because the Executive is designed to respond to real-time activities,
the driver code must run as fast as possible. Therefore, it cannot be
0verlaid.
The driver data structures are tailored to the number of controllers
on the system, the number of units attached to each controller, and
the types of features the devices support. The structures increase in
complexity as the number of supported features increases.

1.3

EXECUTIVE AND DRIVER INTERACTION

The Ex~cutive and a driver interact by accessing and manipulating
common data structures. An I/O activity typically begins when a task
generates a request for input or output.
The Executive performs
preliminary processing of that request before it initiates the driver.
This p~eliminary processing, called predriver initiation, is common
for all drivers and eliminates a great deal of code from all drivers.
In per:orming predriver initiation, the Executive accesses the driver
data
;tructures to assess the legality of the I/O request. For
exampl,~, cells in the device control block (DCB) define the
functions
that
:he driver supports.
If the function specified in the I/O
reques~: is not supported by the driver, the Executive
need not call
the dJ-iver.
The driver is not aware of the I/O request. Therefore,
the Executive calls the driver only when the predriver initiation
warrants it.

1.3.1

The Driver Process

When the Executive does call the driver to process an I/O request, the
driver begins I/O initiation.
Once an I/O request is created, a
driver process is initiated. The Executive has queued to the driver
an I/O packet that must be processed to satisfy the request.
Potentjally there exist on the system as many driver processes as
1-4

RSX-llM-PLUS I/O DRIVERS
there are distinct units capable of being active simultaneously.
(Moreover, some drivers supporting advanced features can have multiple
I/O requests simultaneously active for a given unit. In this case,
each active I/O request is part of a separate driver process.
Refer
to Section 1.4.7 for more information.)
Central to a full understanding of a driver and the I/O structure is
the difference between a driver process and the driver code. The
driver code, which is pure instructions, invokes an Executive routine
called $GTPKT to get an I/O packet to process.
This activity
generates data for the request being processed and the unit doing the
processing. The driver process, once initiated, starts the proper I/O
function, waits for a completion interrupt, posts I/O status, and
requests another I/O packet.
This sequence of execution steps
continues until the I/O queue is empty.
The driver process then
terminates.
Because a driver may be capable of servlclng several I/O requests in
parallel, it is possible that, for a single driver, many driver
processes exist at the same time. However, there is only one copy of
driver code.
The driver process is reentrant code and the data that
defines the state of the code is stored in the driver data base when
the process is not executing (for example, when it is waiting for an
interrupt). The driver process executes driver code for a particular
device type on behalf of a specific unit. If independent units of a
particular device type are concurrently active, several
driver
processes are also active at the same time, each with its own set of
data.

1.3.2

Interrupt Dispatching and the Interrupt Control Block

Once a driver starts an I/O function, it must await the I/O completion
interrupt.
When a device interrupt occurs, the processor pushes the
current PS and PC onto the current stack and loads the new PS and PC
from the device controller interrupt vector. By convention, the PS in
the interrupt vector is preset with a priority of 7 and the number of
the controller associated with the vector.
(The controller number is
in the low-order four bits.)
Because an interrupt must be serviced in Kernel address space, how the
interrupt is handled depends on whether the driver is resident or
loadable. A resident driver, being mapped with the Executive in
Kernel address space, handles the interrupt directly (that is, the
entry point address of the driver is the PC word of the interrupt
vector).
For a resident driver, then, the hardware dispatches
directly to the interrupt service routine in the driver.
Figure 1-2
shows this mechanism.

CONTROLLER
NUMBER

RESIDENT
DRIVER

INTERRUPT
VECTOR
ZK-246-81

Figure 1-2

Interrupt Dispatching for a Resident Driver

1-5

RSX-IIM-PLUS I/O DRIVERS
When tie interrupt service routine in the resident driver gains
contro],
it runs at priority 7, which locks out further interrupts.
The driver is therefore uninterruptable and, because the system must
responc
to real-time events, processing at this level cannot take too
10ng. 1
To ensure that a driver does not lock out other interrupts on the
system or destroy the context of any interrupted process, a protocol
has bef!n established. By system convention, no process should run at
an un.nterruptable level for more than 100 microseconds. A common
Execut~ve coroutine, called interrupt save ($INTSV), exists
to lower
the pliority level of the driver process to that of the interrupting
device and to save two registers of the interrupted
process.
Therefc1re, by system convention, all resident drivers call the $INTSV
corout:ne, which saves the PS and extracts the controller number.
Becaus(·
most instructions change the PS bits that encode the
contro~ler number, under most circumstances the
driver can do very
little else witbout saving the controller number.
The $ItJTSV coroutine saves two registers, R4 and R5, which are
thereafter free for the driver to use. These registers are typically
used b~' drivers to hold addresses of the data blocks containing unit
status and control information, the SCB and UCB.
(Most Executive
routin(~s
assume these two registers hold pointers to the
two
structllres.
If the driver needs to use more registers, it saves them
on the stack and restores them when it finishes.) When the interrupt
save c(!routine returns to the driver, the driver runs at the interrupt
level of the device that it is servicing and has two free registers
that
it
can
use.
This protocol makes the driver partially
internlptable (that is, interruptable by devices with a higher
priori1:y) and preserves the context of the interrupted process.
The dr .ver may then run for a short interval at the partially
interruptable level.
By convention, this interval should not exceed
500 microseconds. When the driver finishes processing the
interrupt,
it rna"
execute a RETURN instruction to transfer control back to the
corout ne which gives control of the CPU to the next process. 2
For a ~.oadable driver, the hardware cannot dispatch directly to the
internlpt service routine in the driver because the driver is mapped
out sid (~ the add res ssp ace 0 f the Ex e cut i ve • Th ere for e, so me cod e i n
the Executive must Initially handle the interrupt, load the mapping
context: of the driver, and dispatch to the proper driver.
This code
reside~;
in the Executive in a structure called an interrupt control
block ICB). Figure 1-3 shows this mechanism.
The ICB actually contains a JSR instruction to an Executive interrupt
save l-outine
($INTSI) and some data cells that enable the routine to
do the following:
•

Save R4 and R5

•

Save the Kernel mapping (APR 5)

1. On

d
multiprocessor system, a driver running at priority 7 is
interruptable by a device of the same type on another CPU. To handle
this s tuation, the driver being interrupted does not have to do any
specia:. processing beyond what is described in this manual.

2. An Executive interrupt exit rout~ne, ylNTXT, exists to standardize
the Wily a driver exits from an interrupt. However, on RSX-llM-PLUS
system:; this routine is simply a RETURN instruction.
1-6

RSX-IIM-PLUS I/O DRIVERS
•

Load APR 5 to map the driver

•

Transfer control to the driver

•

Restore the mapping after return from the driver

•

Restore R4 and R5

Thus, the interrupt vector for a controller serviced by a loadable
driver points to an ICB rather than to the driver. Accordingly, the
loadable driver does not (and must not) call the $INTSV routine as the
resident driver does because the $INTSI routine saves the context on
behalf of the loadable driver. When it gains control, the loadable
driver is also partially interruptable as if it had called the $INTSV
routinH. After it gains control, the loadable driver is exactly like
the rHsident driver.
(That is, it must also observe the protocols
established on the system.)

INTERRUPT
CONTROL
BLOCK
(ICB)

CONTROLLER
NUMBER
INTERRUPT
VECTOR

LOADABLE
DRIVER

ZK-247-81

Figure 1-3

Interrupt Dispatching for a Loadable Driver

The ICB allows up to 128 controllers of the same type on a system.
The low-order four bits in the PS of the interrupt vector restricts
the number of controllers to 16. In the ICB, the system maintains a
controller group number and the PS bits describe the controller number
within the group. To obtain the real controller number, the Executive
interrupt service routine adds the controller group number in the ICB
and the controller number in the PS.
(Note that, because a resident
driver does not use the ICB mechanism, there can be at most 16
controllers of one type if the driver is resident. Furthermore, only
the LOAD command in VMR supports more than 16 controllers of one
type. )
The simplest case in handling an interrupt is that in which a
controller can have only one unit active at anyone time. Multiple
controllers may be active concurrently, yet only one unit per
controller may be active. When an interrupt occurs, the driver can
determine the number of the saved controller from information encoded
in the low-order four bits of the PS. The interrupt service routine
in the driver uses the number to index a table in the CTB and to
access the proper unit data and context.
The more complex case in dispatching an interrupt is that in which a
controller can have multiple units operating in parallel. This is an
advanced driver feature called overlapped seek I/O and is described in
Section 1.4.1.

1-7

RSX-IIM-PLUS I/O DRIVERS
1.3.3

Interrupt Servicing and Fork Process

A driver (whether resident or loadable)
handling an interrupt and
operat ng at the partially interruptable level may need to (I) access
structures in its data base or (2) call centralized Executive service
routinps which may access structures in the data base. Because a
driver may have more than one process active simultaneously, the
driver itself may need to access structures in the data base shared
among separate, unrelated processes.
A method must
exist
to
coordirlate access to the data structures shared among the processes
and thp Exe-::utive.
The mechanism that coordinates access to the shared structures is
called the fork process. An Executive routine, called fork ($FORK),
causes the driver to be placed in a queue of processes waiting for
access to the shared data structures, to run at processor priority
level (1, and to be completely interruptable. l A driver must therefore
call the fork routine before it calls any other Executive service
routinf! (except for $INTSV), or before it accesses any device-specific
(nonpr ovate) structures in its data base. If a driver does not follow
this protocol, it will corrupt the system data base and will
eventually cause a system crash.
A driv(~r that calls the fork routine requests the Executive to
transform it into a fork process. The routine saves a snapshot of the
proces:; ina fo rk block. The snapshot is the context 0 f the d river
proces~;--the
PC 0 f the process and the contents 0 f R4 and R5. The
fork b:_ock itself resides in the I/O data structure holding the status
information of the device being serviced (that is, the status control
block, or SCB). The Executive maintains a list of fork blocks in FIFO
order.
A new fork block is added to the list after the last block in
the li~;t.
When the driver calls $FORK, the CPU priority is lowered to 0, which
allows other interrupts to be serviced.
When there are no more
pendinq interrupts (they have either been dismissed or the drivers
have called $FORK), the Executive checks to see whether the first
interrupt preempted a priority 0 Executive process. If a preemption
occurred, the Executive process is continued from where it was
interrupted.
If no priority level
0
Executive
process
was
interrupted, the Executive executes the process at the head of the
fork l:st. The Executive restores the saved context of the process
from the SCB and returns control to the driver at the statement
immedi~tely following the call to the fork routine.
The process is
unawarp that a pause of indeterminate length has elapsed.
Fork processes thereby are granted FIFO access to the common I/O data
structures.
Once granted such access, a fork process has control of
the structures until it exits.
The protocol guarantees that the
driver
process
has unrestricted access to shared system data
structures. As one fork process exits, the next in the list is
eligibJe to run and access the data structures. Thus, the fork
mechanjsm allows both controlled access to the common data structures
and sufficient time to process an interrupt without locking up the
system.

1. By convention, drivers may operate at a partially interruptable
level for no more than 500 microseconds. Some drivers conceivably
could need more time than this convention allows. Thus, an additional
reason for th~ fork mechanism is to preserve the response time of the
system and not lock out interrupts from lower-priority levels.
1-8

RSX-llM-PLUS I/O DRIVERS
The status of a fork process lies between an interrupting routine and
a task requesting system resources.
Interrupt routines are run first
and can be interrupted only by higher-priority interrupts.
Processes
in the fork list run after other system processes either terminate or
call $FORK themselves.
Because system processes save and restore
registers, a
fork process can use all registers.
The fork processes
are completely interruptable.
Tasks run only when the fork list
is
empty.l
The fork mechanism establishes linear, or serial, access to the shared
data structures.
For example, an Executive routine that completes I/O
processing ($IODON) manipulates the I/O queue to deallocate an
I/O
packet that the driver processed.
If multiple processes were allowed
to alter the queue at random times, the queue pointers could become
disarranged.
Without the fork mechanism, any process could be
interrupted by a higher-priority process and not be able to complete
its manipulation.
Because the Executive completes a currently active
fork process before it starts the next fork process in the queue,
the
integrity of the
I/O data structures is maintained if all routines
that call $IODON run at fork level.
Between the time that a driver process calls $FORK and the Executive
starts the process at fork level, the driver cannot call $FORK again
for that same device.
If the $FORK routine is called again before the
first process starts, context stored in the fork block for the first
fork process is overwritten.
However, once a fork process starts, the
data
in the fork block is stale and the process may call $FORK again
while it is at fork level.
If the driver does not ensure against
unexpected interrupts,
it may double fork as described above.
As a
result of the double fork, the driver may either miss an
interrupt
from the device or miss interrupts from several devices.
As a further
consequence, code after the call to $FORK is executed twice for
the
same context with generally catastrophic results.
For example,
calling $IODON twice for the same I/O packet eventually causes the
system to crash.
If all drivers adhere to the interrupt protocol, the integrity of the
I/O data structures is preserved.
Thus, when a device interrupt
occurs while a fork process is executing, the protocol demands that
the service routine handling the
interrupt not destroy any of the
registers.
The registers are part of the context of the fork process.
After the driver dismisses the
interrupt or itself becomes a fork
process, the interrupted fork process can safely resume execution with
its proper context.
If any driver violates the protocol,
the
integrity of the I/O data structures is endangered.
(That is,
the
system crashes in mysterious ways.)

1.3.4

Nonsense Interrupt Entry Points

All vectors for off-line devices and vectors for which there are no
devices contain the addresses of Executive nonsense interrupt entry
points.
Code at these special entry points exists to properly dismiss

1. On a multiprocessor system, the fork list is not necessarily empty
when the Executive returns control to a task.
The Executive processes
only those fork blocks that are to run on the current processor.
To
ensure that fork blocks remaining in the list are readily processed,
the Executive running on one processor interrupts
(using
the
interprocessor interrupt hardware) any other processor that has fork
blocks waiting for processing.

1-9

RSX-IIM-PLUS I/O DRIVERS
unexpe(=ted interrupts from these devices. If error logging is active,
any unexpected interrupts are recorded as undefined interrupt errors.
This ff~ature helps in detecting faulty hardware.

1.4

ADVANCED DRIVER FEATURES

drivers have certain optional and built-in special features.
This :3ection introduces these features so that you can better
unders':and the structures described in the remainder of the manual.

Advancf~d

1.4.1

Overlapped Seek I/O

Some disk devices allow multiple device units attached to the same
controller
to execute operations in parallel.
This is called
overla0ped seek suoport and is a software option designed to take
advantlge of a hardware feature found in most advanced disk drives.
This f'~ature allows any or all drives attached to the same controller
to ex,~cute a seek function simultaneously. Each unit may perform a
seek o~eration ~ndependent of what another unit may be doing.
Only
one d3ta transfer can occur at anyone time. Some types of drives
allow 3eek functions to overlap a data transfer function, whereas
other ~ypes do not.
The in~reased difficulty for overlapped seek devices stems from
determining
whether
the controller or the unit generated the
interrrupt.
Most control functions issued to the
drive
unit
(including the positioning commands SEEK and SEARCH) terminate with a
unit i:lterrupt. The controller reports the physical unit number of
the interrupting unit in its attention summary register. A controller
interrlpt indicates the termination of a function
(usually a data
transfer command)
that changes the controller status from busy to
ready. Only one unit may issue a data transfer complete notification
to a particular controller at anyone time because only one data
transf,~r can be in progress at anyone
time.
Most hardware defers
seek termination interrupts until the current data transfer is
complete.
To hanjle interrupts for a device that supports overlapped seek
operations, a device-specific interrupt service routine built into the
Executive examines the device registers to determine whether the
interrJpt was initiated by the controller or the drive unit. Using
the cOltroller number retrieved from the PS in the interrupt vector,
the r~utine forms an index (called the controller index) to use as an
offset into a table of addresses in a structure (called the controller
table )r eTB) in the I/O data base. The routine accesses the table to
determine the address of the I/O data structure of the controller
(callei the controller request block or KRB)
that generated the
interrJpt. Accessing the KRB yields the address of the eSR of that
controller and having the eSR address allows the routine to examine
the device registers.
If th~ controller itself initiated the interrupt, the
routine
determines the data base structure of the unit that is active. This
determination is possible because such a controller interrupt relates
to a termination of a data transfer, and only one such unit can be
active for a data transfer. A cell in the KRB has the address of the
data structure describing the active unit (the unit control block or
UeB). The routine can then determine the address of the driver
dispat~h table and transfer control to the driver.

1-10

RSX-llM-PLUS I/O DRIVERS

If a device unit initiated the interrupt, the routine retrieves its
unit number from the Attention Summary Register.
Using the physical
unit number, the routine indexes a table at the end of the KRB to
yield the address of the related UCB.
The driver is entered through
the driver dispatch table.

1.4.2

Dual-Access Support

Some devices have mUltiple-access paths for both control and data
transfer
functions.
Such devices are called dual access.
A
dual-access unit is connected to two controllers at one time and may
be accessed ~~om either controller at the option of the system
software.
Since a single device unit may have only one physical unit
number,
a dual-access unit must have the same unit number for both
controllers.
A dual-access unit may be accessed only from one port at
a time,.
The system supports dual-access operation for those devices
~quipped with the necessary hardware capability.
This feature is most
useful on a multiprocessor system where each access path is to a
different central processor unit.
To support dual-access operations,
the
I/O data structures must
reflect the existence of alternate controllers.
Particularly, the
driver process context for I/O on a unit can be associated with either
of two controllers.
To decide which controller will provide access to
the drive unit, the driver must call an Executive routine to request
access to a particular controller. When the Executive grants access,
the driver process context for a unit is associated with the assigned
controller.
A driver must have access to the assigned controller
before actually changing the registers in the I/O page.
When a driver and a unit are given access to a controller,
the
controller status is set to busy.
The unit becomes the device owned
by the controller for the operation. A controller without an owned
unit is considered a free controller.
By this ownership mechanism,
controller interrupts are sent to the correct unit for processing.
After the operation completes, the driver requests the Executive to
release the controller and thus frees it.

1.4.3

Delayed Controller Access

Drivers that support overlapped seeks also must request access to a
controller before executing a function on an independent unit and must
release access after completing the function.
To take maximum
advantage of simultaneous operation of units on one controller, the
system delays controller access when the controller is busy.
The Executive maintains a request queue for the controller.
Whenever
a driver process requests access to a controller and must wait for
access to the controller, the Executive places the associated fork
block in the controller request queue.
When a driver releases a
controller, the Executive automatically grants access to the next
driver process waiting for access.
Precedence is given to positioning
requests over requests for data transfer.
The controller request
queue thereby provides the means for the Executive to synchronize
access.

1.4.4

Controller Reassignment and Load Sharing

Controller assignment for dual-access devices is dynamic.
If one port
(access path)
to a device is busy, the system can request access on
1-11

RSX-llM-PLUS I/O DRIVERS
the ot:her port.
This switching between ports
share the load between the two controllers.

allows

the

system

NOTE
A dual-access device has both ports
attached to
the same system.
DIGITAL
does not support systems loosely coupled
through a peripheral.
The s~stem also maintains an
I/O count for
each controller to
deterrrine how busy it
is.
If one controller is not as busy as the
other, the system can queue the access requests to
the less busy
controller.
Whenever load sharing is done on a dual-access unit, the
Executive makes any reassignment necessary before actually requesting
access to the controller.

1.4.5

Common Interrupt Dispatching

To handle interrupts from a controller that supports more than one
type of device, the Executive uses a mechanism called common interrupt
dispatching.
The RH70 MASSBUS controller can have different types of
devices
(RP04,
RPOS,
and RP06 moving head disks;
RM02, RM03, RMOS,
moving head disks;
RM80 and RP07 fixed
media
disks;
MLll
non-rotating memory;
RS03 and RS04 fixed head disks;
and TE16, TU4~,
and TU77 magnetic tape drives)
connected to the same type of
controller.
Interrupt dispatching for such devices is more difficult
than f')r standard interrupt devices because associated with one set of
interrjpt vectors are multiple drivers.
To dispatch interrupts,
therefr)re, a routine in the Executive must intervene.
Figure 1-4
showsln example of common interrupt dispatching.

Common
Interrupt
Dispatch
Routine
($RHALT)

DB
Driver

DS
Driver

MM
Driver

RH70 Interrupt
Vectors
ZK-248-81

Figure 1-4

Interrupt Dispatching for Common Interrupt Devices

The vectors for
such controllers point to a common
interrupt
dispatching
routine
in the
Executive module DVINT.
This common
routine avoids having to duplicate code in drivers.
This routine,
in
essence acting like an RH70 controller driver or a sophisticated rCB,
determines which driver will
receive control upon an
interrupt.
Operating like the routine that handles interrupts for overlapped seek
devices, this routine determines the type of device that
interrupted
and dispatches to the proper driver.
1-12

RSX-llM-PLUS I/O DRIVERS
1.4.6

Subcontroller Devices

Certain devices have 2-level controllers, such as magtapes, where a
TM03 connects to an RH70 MASSBUS controller and also connects to TE16
magtape drives.
In such an arrangement, the TM03 is a subcontroller,
or master unit, that controls slave units; a register in the master
unit rE~ports the number of the slave unit that generates an interrupt.
A subcontroller is associated with a data structure called
a
subcontroller request block
(KRBl)
that serializes access to the
subcontroller.
Therefore, a driver must request and receive access to
both the subcontroller and the controller for a unit before executing
any operations.
The KRBI is a subset of the KRB and every unit on the
subcontroller points to the KRBI of the subcontroller to which it is
attached.

1.4.7

Full Duplex Input/Output

In certain circumstances it may be necessary for a driver to handle
more than one I/O request on a unit at the same time.
Typically a
driver processes only one I/O packet per unit at anyone time.
In
normal operation the driver calls the Executive routine $GTPKT to get
an I/O packet to process. When $GTPKT returns an I/O packet, it marks
the device busy and does not allow additional I/O until the first I/O
activity completes.
Therefore, only one I/O process can be in
progress at the same time on a device.
Full duplex operation allows
more than one I/O process to be in progress on a device at the same
time.
To allow full duplex operation, the $GTPKT routine has a special entry
point called $GSPKT.
A driver calling $GSPKT specifies an acceptance
routine, to which $GSPKT returns control when an eligible packet is
found.
The acceptance routine determines whether to accept or reject
the packet.
The criteria that the acceptance routine applies could be
that a write request is accepted if a write has just completed or that
a read request is accepted if a
read has just completed.
If the
routine rejects the packet, it indicates so to $GSPKT, which continues
to search for another packet.
If the acceptance routine accepts the
packet,
$GSPKT dequeues the packet and passes it to the driver but
does not modify U.BUF and U.CNT in the unit control block
(UCB)
nor
does it mark the device busy.
As a
result, during full duplex
operation the device appears idle even while it is processing an
I/O
request.
To complete an I/O request under full duplex operation,
the driver
calls the $IOFIN routine rather than the $IOALT or $IODON routine.
$IOFIN does final processing without making the device look idle, as
$IOALT and $IODON attempt to do.
In full duplex operation, a unit
will always appear idle to the system and the driver acceptance
routine will determine whether the device can handle an I/O request.
A driver handling full duplex operations"requires augmented data base
structures.
The conventional data base structures are defined for
only onE~ I/O request in progress per unit.
Because the driver has to
keep more information concerning a unit that allows two I/O requests
in progress, you may have to alter the UCB and other data base
structures to provide additional offsets. The DIGITAL-supplied full
duplex terminal driver not only uses a
lengthened UCB and
a
nonstandard SCB,
but also connects to a dynamically allocated UCB
extension when the device is configured on-line.
A driver that handles full duplex operations provides a specific
example of software that handles concurrent I/O for individual units.
Some
devices,
such
as
the
DIGITAL-supplied
LPAII-K
1-13

RSX-llM-PLUS I/O DRIVERS
miCrOpI"OCeSsor-based laboratory subsystem,
can handle a number of
simultaneously active I/O requests.
The software to handle such
concurrent I/O may require augmented driver data base structures so
that the context of each I/O
process
remains
distinct
and
controllable.
The driver for the LPAIl-K relies on an extended user
control block (UCB) to preserve the context of a maximum of eight
simult2neously active I/O processes.
User-written software for such a
device must properly synchronize
fork
processing
to
prevent
substituting the
I/O context of one process for that of another.
Moreover, the $GSPKT routine also might be used as described above to
make a unit appear idle when it is busy.

1.4.8

Buffered Input and Output

Typically, data for input and output requests are transferred directly
to and
from task memory.
To allow the successful transfer of data,
the task cannot be checkpointed until the transfer is complete.
For
most high-speed devices, the transfer occurs quickly enough so that a
task does not occupy memory for
too long a
time.
For slow-speed
devices, however,
some mechanism must be available to avoid binding
memory to a task for too long a time while the task is performing I/O.
Using t.he routines $TSTBF, $INIBF, and $QUEBF in the Executive module
IOSUB, a driver can execute an I/O request for a slow-speed device and
allow the task to be checkpointed while the request
is in progress.
To perform the
I/O request,
the driver buffers the data in memory
allocated to the driver while the task is checkpointed and
the
I/O
request is in progress.
To test whether a task is in a proper state to initiate I/O buffering,
the dI·iver calls the $TSTBF routine and passes it the address of the
I/O packet.
By extracting the address of the task control block (TCB)
from the I/O packet, $TSTBF can examine various task attributes.
For
example, if the task is checkpointable, buffered I/O can be performed.
$TSTBF returns to the driver and indicates whether buffered I/O can be
performed.
If buffered I/O can be performed, the driver performs two operations.
First,
it establishes the buffering conditions.
For an output
request, it copies the task buffers to dynamically allocated pool
space.
For an
input request, it allocates sufficient pool space to
receivE' the incoming data.
Second,
the driver calls the $INIBF
routinE' to initiate the I/O buffering.
$INIBF decrements the task I/O
count, increments the task's buffered I/O count in T.TIO, and releases
the tEsk for
checkpointing and shuffling.
If the task is currently
blocke~, the task state is transformed into a
"stopfor"
state until
the task is unblocked, buffered I/O completes, or both.
Checkpointing
the ta~;k is subject to the normal
requirements of an active or
"stopfer" state as described in the RSX-lIM/M-PLUS Executive Reference
Manual.
After the driver transfers the data, it calls the $QUEBF routine to
queue the buffered I/O for completion.
$QUEBF sets up a kernel
asynchronous system trap (AST) for the buffered I/O request and
if
necess2.ry, unstops the task. When the task is active again, a routine
in thE
Executive module SYSXT notices the outstanding AST and
processes it.
(If the request is for input, the routine copies the
buffer~d data to task memory.) This mechanism occurs transparently
to
the task, thus the name kernel AST.
The routine then calls the driver
to deallocate the buffer from pool.
$IOFIN completes the processing.

1-14

RSX-IIM-PLUS I/O DRIVERS
1.4.9

I/O Queue Optimization

Without I/O queue optimization, the operating system groups input and
output requests in the queue by highest priority on a first-in,
first-out basis.
The first request at the highest priority appears
first in the queue and is processed first.
Other requests within that
priority are then processed sequentially until the last request at
that priority is serviced.
With I/O queue optimization, however, the next I/O request at the
highest priority is not necessarily the next sequential request to be
processed.
I/O queue optimization allows the queue to be scanned, and
each rE~quest to be examined.
The I/O request, according to the method
of optimization then in effect, is the next one dequeued and passed to
the
I/O driver
for processing.
The highest priority requests are
still serviced first;
however,
throughpu~
is improved by
the
reordering of requests within a priority.
There are three methods of I/O queue optimization available:
•

Nearest Cylinder

•

Elevator

•

Cylinder Scan

The Nearest Cylinder method processes the I/O request that is closest
to the one at which the disk head is currently positioned.
The
Elevator method processes requests as the disk head moves from the
perimeter to the
innermost track of the disk.
Once the disk head
reaches the innermost track, the direction is reversed and requests
are processed along the disk as the head moves back to the perimeter.
The Cylinder Scan method operates similar to the Elevator method,
except requests are only processed as the disk head moves from the
perimeter to the innermost track.
Once at the
innermost track,
the
disk hE~ad returns to the perimeter and begins processing new requests.
The met~od you choose for
your system is dependent upon the I/O
processlng
requirement of your application, the frequency with which
tasks access certain data areas on the disk, and the physical location
of data on the disk.
Refer to the RSX-IIM/M-PLUS System Management
Guide for information on selecting I/O queue optimization methods.
Before an I/O request can be queued to the driver,
all three queue
optimization methods require the starting cylinder number of the I/O
request.
To find the cylinder number, the logical block number
(LBN)
of each I/O request is converted to cylinder, track, and sector form.
The routine $DRQRQ in the Executive module DRSUB begins
this
conversion.
Because the cylinder, track, and sector form is specific
to the device geometry,
this conversion must be completed by a
sepa~ate
routine in the driver.
The routine $DRQRQ locates the
conversion routine in the driver through offset D.VCHK in the driver
dispatch table.
The routine $DRQRQ calls the conversion routine for all I/O requests.
However,
if the functions are not logical transfer functions, such as
ACP functions or Attach and Detach operations, the conversion routine
does not complete the conversion, but rather returns to $DRQRQ.
Drivers without queue optimization call the routine $BLKCK in the
Executive module MDSUB to check the limits of the I/O request.
If
$BLKCK locates an error, the routine SIOALT in the Executive module
IOSUB is called for the I/O reque~t and the driver is returned to the
initiation entry point.
If you chose queue optimization, a return to
the
initiation entry point is not desirable because the necessary
functions of $DRQRQ will not be completed.
Therefore, your completion

1-15

RSX-IIM-PLUS I/O DRIVERS
routine must call the
routine $BLKC2 in the Executive module MDSUB
instedd of $BLKCK to ensure the correct return to $DRQRQ if an error
is de:ected.
The routine $GTPKT in the Executive module IOSUB performs the actual
optim~zation.
The driver calls the Ex~cutive routine $GTPKT for an
I/O request to process.
$GTPKT scans the queue of I/O packets to
selec1: those of the highest priority.
The routine then chooses the
correct packet within that priority based on the optimization method
currently in effect, dequeues that packet, and returns control to the
driver to process that I/O r~quest.

1.5

DISTRIBUTED I/O

On a multiprocessor system, a task may issue an
I/O request to any
on any processor.
The Executive must be responsible for
distrjbuting the I/O request to the correct processor.
To ascertain
to which processor a device is attached and to have the driver execute
on tre correct processor,
the
Executive
must
perform
some
procersor-specific functions.
The following sections introduce the
data ~tructure and the processing routines used by the Executive for
procersor-specific functions.
devic~

1.5.1

UNIBUS Run Mask

To help describe devices attached to a processor, the software relies
on a concept called UNIBUS run.
A UNIBUS run consists of a group of
distinct devices, all of which are electrically connected to the same
UNIBUS and are not separated by any bus reconfiguration devices.
Each
UNIBUS run is attached to the same processor at the same time because
of the way the devices are physically attached to
the UNIBUS.
(Devices attached to a MASSBUS of a
processor are also on the
processor's UNIBUS
run.)
The UNIBUS run,
then,
is the smallest
fragment of a particular UNIBUS capable of being switched
(or not
switched) between processors.
Essential to understanding UNIBUS runs is the concept of a
switched
bus.
A switched bus is a portion of a UNIBUS that can be physically
connected to one of multiple UNIBUSes.
A device on the UNIBUS, called
the Dr07 UNIBUS switch, controls the connection and allows a switched
bus to be connected to anyone of a maximum of four
UNIBUSes.
Any
UNIBUS device or devices except a processor or another bus switch may
be conlected to a switched bus.
Moreover, because of the electrical
delay lssociated with the bus switch, some high-speed devices (such as
the DM'~-ll) cannot be on a switched bus.
In a mlltiprocessor system, the DT07 allows the switched bus to be
physicilly switched from the UNIBUS of one processor to the UNIBUS of
anothe~ processor.
When the switch is connected to a
particular
proces:;or's UNIBUS, all peripherals on the switched bus operate as if
they were permanently connected to that UNIBUS.
By means
of
reconf_guration software, a switched bus can be disconnected from one
UNIBUS and be available for connection to another processor's UNIBUS.
Becaus{~
a
user task can direct an I/O request to any device on the
system the Executive must be able to perform the operation on the
specif:c processor to which the device is connected.
A UNIBUS run is represented in a cell called a
UNIBUS run mask
(or
URM) •
The URM is a l6-bit word containing a bit for every possible
UNIBUS run.
UNIBUS runs are numbered from 0 to 15, and the system is
restricted to a maximum of 16 UNIBUS runs.
There are four UNIBUS runs
reserved for the maximum of four processors.
The numbering allows a
1-16

RSX-llM-PLUS I/O DRIVERS
maximum of 12 switched buses. However, a switched UNIBUS cannot be
connected to another switched UNIBUS.
A primary UNIBUS run would
contain a processor, its UNIBUS, and the peripherals directly attached
to its UNIBUS; and a secondary run would consist of a switched bus
and the devices attached to it.
In thE! I/O data structures for each controller in the multiprocessor
system is an associated UNIBUS run mask. The bit set in the URM
defines the UNIBUS run to which the controller is attached.
In the
Execut.ive, there is a table of connectivity masks, one UNIBUS run mask
for each processor in the system. The' table represents the UNIBUS
runs to which each processor is attached. A bit set in the table mask
word for a processor indicates that the UNIBUS run is currently
associated with that processor.
To ascertain whether a controller is attached to the
current
processor, the Executive compares the controller URM with the mask for
the processor in the connectivity table. If the same bit is set in
both words, the controller is attached to the current processor. If a
bus is switched from one processor to another, the system need alter
only the connectivity masks of the processors affected.

1.5.2

Conditional Fork

The conditional fork routine ($CFORK)
is the method by which the
Executive distributes I/O requests to devices connected to another
processor.
In a multiprocessor system, peripheral devices
are
generally accessible to only one UNIBUS run. Devices that do have
dual-access capability are not necessarily accessible from every
UNIBUS.
The Executive ensures that, when a driver accesses a
controller, the driver process executes under control of the processor
in whose I/O space the controller registers reside. An exception is
the Executive passing control to a driver for special processing of an
I/O packet. In this case, the driver is responsible for ensuring that
the process executes on the correct CPU. See the discussion of the
UC.QUE bit in Section 4.4.4.
The conditional fork routine is necessary because the system allows
processors to remain anonymous as far as task execution is concerned.
The system does not restrict execution of a user task to the processor
associated with a device to which the task directs I/O. Basically it
is the driver processes that need to execute on specific processors.

1.5.3

Processor-Specific Functions

When the Executive calls a driver to initiate I/O, the driver may not
be executing on the processor associated with the device unit to which
I/O is directed. When the driver requests an I/O packet to process,
the Executive must ensure that the driver executes on the correct
processor because the driver may access the I/O page. Therefore, the
Executive routine ($GTPKT) that dequeues an I/O packet for the driver
performs a conditional fork. A cell in the fork block for the device
unit contains a UNIBUS run mask that defines the processor to which
the unit's controller is attached.
The conditional fork routine
accesses this cell to ascertain what action to take.
The UR~1 of the device to which the I/O request is directed therefore
determines whether the driver may execute on the current processor.
If the URM of the device intersects the current processor URM, the
conditional fork routine returns and the I/O packet is immediately
passed to the driver. The driver then normally proceeds to start the
proper I/O function.
If execution must be continued on another
1-17

RSX-llM-PLUS I/O DRIVERS
proces:ior, the conditional fork routine performs a fork
(that is,
call s the $ FOR K r 0 uti n e). Th e d r i ve r has no i n d i cat ion t hat i t has
become a fork process (that is, the action is transparent to the
driver~ •
To ensllre that the driver executes on the correct processor, the fork
routin!! does two operations.
First,
it creates and queues a fork
block !'or the processor on which the driver must execute. Second,
it
return:; to the driver in such a manner as to force the driver to
dismis!; itself. As soon as possible, the fork processor restarts the
driver process executing on the appropriate processor.
For devices that do not have an assigned controller, the system may
defer
determining
whether the driver executes on the current
pro c e s :; 0 r • Th ere for e, for 0 v e rIa p p e d see k and d u a 1- a c c e s s d e vic e s ,
the conditional fork routine is entered after the Executive routine
that a!;signs the controller.

1.6

O"ERVIEW OF INCORPORATING A USER-WRITTEN DRIVER INTO RSX-llM-PLUS

How y011 incorporate a user-written driver into the system depends
mainly on whether you make your driver loadable or resident.
If your
driver is loadable, its data base can be either loadable or resident.
If your driver is resident, both its data base and its code are
res ide II t • Th us, be c a use you b u i 1 d the Ex e cut i v e i mag e d uri n g s y stem
generation, you can include any resident driver elements in the
Execut ve image only during system generation.
If your driver is
loadab e and has a loadable data base, you can incorporate it at any
time a·:ter you build the Executive under which the driver will run.
During system gener~tion, you answer questions concerning the types
and qllantity of peripheral devices on your system. Based on your
answer:;, the system generation software creates the device data base
source files.
The file SYSTB.MAC contains the data base definitions
for al the DIGITAL-supplied devices that were generated with resident
data bases.
The files xxTAB.MAC, where xx is the device mnemonic,
contain the data base definitions for each of the DIGITAL-supplied
de vic e :; t hat we r e g en era ted wit h loa dab l e d a tab as e s • Th e f i 1 e s
xxDRV.r1AC, where xx is the device mnemonic, contain the driver code to
support the devices.
The system generation software assembles and
task bllilds these modules.
The resident driver and data base modules
are 1 nked into and become a permanent part of the Executive. The
loadab-_e driver and data base modules are task built separately for
loadinq into memory after the Executive has been built.
A priv leged system task called LOAD is responsible for loading into
memory a driver that is not resident.
LOAD creates the necessary
interrupt control blocks (ICBs) for accessing a driver and establishes
the 1 nkage between the data base structures in the system device
tables and the driver code being loaded. Another system task called
CON initializes the interrupt vectors to point to the ICSs and
actual~y places the devices on-line.
CON can also change the vector
and CiR address assignments in a device's data base.
Another
privilt~ged system task called UNLOAD can remove a loadable driver from
memory,
(Although UNLOAD removes a loadable driver, it does not
remove a loadable data base.)
To inc()rpor~te a user-written driver into RSX-llM-PLUS, you first
create two modules, one in which you define the data base and the
other n which you include the driver code itself.
You then must
integrdte your driver data base and driver code modules into the
system device tables.
If your data base is resident,
the linkages
that "our data base module must satisfy are:
(1) the link of the
contro ler table (CTB) list; and (2) the link of the device control
1-18

RSX-llM-PLUS I/O DRIVERS
block (DCB)
list.
The linkage for the driver code connects the DCB
for the device that your driver supports to the driver dispatch table
(DDT) •
If your driver and data base are loadable, you must supply in
your code symbols and labels that LOAD needs. Your device interrupt
vectors are initialized and the devices are placed on-line by CON.
Because the data base for a loadable driver can be loadable, the LOAD
task also loads a data base. When you load a driver, LOAD checks to
see whether a data base is resident for the type of device whose
driver is being loaded. If a data base is not resident, LOAD reads
the driver symbol definition file to find the start and end of the
data base in the driver image.
(Thus, if your driver data base is to
be loadable, you must have defined its start and end in the data base
source code.) Knowing the start and end, LOAD reads the data base from
the driver image. LOAD places the data base in the system pool so
that it resides in Executive address space, accordingly relocates
pointers and links within the data base to be valid Executive
addresses, and also connects the CTB and DCB(s) in the data base to
the system device tables. Moreover, so that the system device tables
are not corrupted by an incorrect data base, LOAD performs many
consistency and validity checks on the data base being loaded.
If your driver is loadable and has a loadable data base, you will
build (1) a loadable image containing the driver code module followed
by the driver data base module and (2) a symbol definition file on
which LOAD depends to find critical data base and driver locations.
You will link the driver image to the Executive under which the driver
will run.
However, the driver image will be separate from the
Executive image. LOAD is responsible for loading both your driver
data base and driver code, for connecting the data base to the system
device tables, and for connecting your driver code to the data base.
If your driver is loadable but has a resident data base, you will have
to perform a system generation and build the Executive under which the
driver will run to link your driver data base module(s)
into the
system device tables.
This 'operation makes your driver data base
resident with the system device tables. You will also build (1)
a
loadable image containing the driver code and (2) a symbol definition
file which LOAD will use to locate the driver dispatch table. LOAD is
responsible for loading your driver code and for connecting your
driver code to the data base that is resident with the system device
tables.
If your driver is resident, you will have to perform a system
generation and build the Executive to link the driver data base into
the system device tables and to include the driver code in the
Executive image.
Whatever type your driver is, you will use the CON task to initialize
the device interrupt vectors and place the devices on-line.
Because LOAD provides consistency and validity checks on a data base
being loaded, DIGITAL recommends that you make your driver and its
data base loadable.
(Additional rationale for making your driver
fully loadable is given in Section 1.7.) Furthermore, with a loadable
driver and loadable data base, you can more easily modify your driver
and its data base. You need not rebuild your Executive and privileged
tasks. To change the driver code, you need only build a new driver
image, unload the current version, and reload the new version. To
change the driver data base, you must build a new driver image (which
incorporates the modified data base module), rebootstrap your system,
and load the new driver which causes the modified data base to be
loaded.
(You must bootstrap your system to change the data base
because UNLOAD does not unload a data base, and because LOAD does not
load a data base for a driver if one is currently loaded for that
driver.)
1-19

RSX-llM-PLUS I/O DRIVERS
Using a loadable driver with a loadable data base saves work in the
long term. During debugging, data base inconsistencies are likely to
be caught by LOAD. Thus, you prevent many such errors from later
creating system problems.
A resident driver or a loadable driver with a resident data base is
more difficult to debug and to modify.
LOAD does not perform
consistency and validity checks on a resident data base.
Thus, a
valuable debugging aid is not available. Moreover, to modify such
drivers, you must rebuild the Executive, which generally implies
rebuilding the privileged tasks.

1.7

SPR SUPPORT

The capability to incorporate a user-written driver into your system
is a supported feature of RSX-I1M-PLUS. Because a user-written driver
is considered a system modification, DIGITAL may not ~upport the
system that results after you incorporate your driver. Being a part
of the Executive, your driver can subtly corrupt it.
~herefore,
DIGIT~L
cannot guarantee support which entails debugging user-written
drivers.
Fixinq a problem in a system is largely a matter of being able to
reproduce the problem reliably. If a problem on your system can be
shown to have no relation to your driver and DIGITAL can reproduce the
probl'~m,
SPR support can be provided.
A good reason for using a
loadable driver with a loadable data base is that you can more easily
attai~
an unmodified system by not loading your driver and its data
base. You can then reproduce a suspected problem in an unmodified
system and can submit an SPR that DIGITAL can answer. Therefore, your
attempting to recreate a suspected problem on your system without your
driver and its data base saves both you and DIGITAL time in answering
the SPR.

1-20

CHAPTER 2
DEVICE DRIVER I/O STRUCTURES

This chapter deals mainly with structures at the block
relationship
to
the
hardware
configuration and
supported, and their relationships to each other.
description of each structure is given in Chapter 4.

2.1

level,
their
functionality
The precise

I/O STRUCTURES

The main elements in the driver I/O environment essentially define
logical and physical characteristics of the supported hardware
establish the links and connections by which routines can access
manipulate driver data.
The following subsections describe
control blocks that a driver data base module defines, and explain
general terms the purposes for each block.

2.1.1

the
and
and
the
in

Controller Table (CTB)

A controller table defines a unique controller type on the system.
A
CTB must exist for each physical controller type. All controller
tables are linked together, in a list, with the head of the list
$CTLST in the Executive common area.
The list of the controller
tables is one of the threads through the system data base to provide
access to all device-related data.
The link in the last CTB in the
list has a value of zero.
Associated with each CTB is a 2-character ASCII controller name which
must be unique throughout the system.
This unique name allows the
Executive to find the correct CTB for the controller type.
For
example, the RHll/70 controller has the name RH instead of DB, OS, DR,
or MM.
A CTB is a static structure created during system generation.
user-written driver data base, therefore, must have its own CTB.
user-created controller table must also be linked into the system
list.

Any
The
CTB

A CTB has generic status information, links, and pointers to other
structures on the system.
The table of KRB addresses in the CTB is
the means by which the Executive handles interrupts for the controller
type and dispatches to the correct driver routine.

2.1.2

Controller Request Block (KRB)

The controller request block is the means by which the Executive
maintains contro11er- or hardware-specific information and accesses

2-1

DEVICE DRIVER I/O STRUCTURES
the correct information for a unit which
its associated
controller
owns.
One KRB exists for each device controller in the configuration.
It stores such data as vector and CSR location, status, and UNIBUS run
mask.
In a configuration where a device has only one access path
to
a
controller and the controller allows only one operation at a time, the
KRB is =ombined with another structure called the status control block
(SCB) •
(The
SCB holds context for a unit while an operation is in
progress.) Because only one access path
is possible
in
such a
configuration,
unit context
is always associated with the
same
controller.
Moreover, because only one operation is possible at a
time, the same context storage area can be used for all units attached
to
the controller.
Thus,
in a
conventional
driver
operating
environ~ent,
the context storage
is merely an extension of the
controller request block.
In a configuration where multiple operations in parallel on the
same
controller are possible, the controller context is separate from each
indepenjent unit context.
Therefore, each unit capable of operating
indepenjently on a
controller has the context of the current I/O
operation stored in an SCB separate from the controller KRB.
In
such
an operating
environment,
any unit can access the controller while
other operations are pending, but only one unit can have access at a
time.
The KRB, then, indicates which unit owns the controller for the
current operation, and synchronizes access among driver processes on
the same controller.
Where multiple operations in parallel are
allowed on a
controller,
there must be
some way to delay access to the controller when it is
busy.
Therefore, in the KRB the Executive holds the head of a list of
access
requests called the controller
request queue.
The
list
contains fork blocks for driver processes awaiting controller access.
The queue is the means by which the Executive serializes access to the
controller.
When a controller allows parallel operations, the software must have a
means of determining which of several units generated an interrupt.
The KRB, therefore, contains a table of addresses which associate
the
controller with all the units connected to it.
This table, indexed by
physical unit number,
must appear
if the controller
in question
supports overlapped seek operations.
When a device has multipleaccess paths,
the controller-specific
information
in
the
KRB
is
separate
from each independent unit context.
In a situation where a
device accesses alternate controllers,
a driver must
request
the
Executive to
assign the
unit
to
a specific controller.
The unit
assignment involves temporarily associating unit context with the
KRB
of
the
specific controller.
The SCB,
then,
holds
information
connecting it to the KRB of the currently assigned controller.
The KRE also holds the configuration status of the controller.
If the
KRB
indicates that
the controller is off-line, no activity can take
place on any unit connected to the controller.

2.1.3

Device Control Block (DCB)

The device control block describes the
static characteristics of a
device type and of units associated with a certain device type.
The
DCB is the means of access to the driver dispatch table and
thus
to
the driver.
At least one DCB exists for each logical type of device
on a system.
There may be more than one DCB for a device
type.
For
examplE,
there are two device control blocks for the device TT:
on a
system that supports terminals connected by both DLll and
DZll
interfaces.
2-2

DEVICE DRIVER I/O STRUCTURES
A cell in each device control block forms a link in a
forward-linked
list, with the head of the list starting in a cell ($DEVHD) in the
Executive common area.
This list, as with the CTB list,
is a main
thread through the system data structures to device-related data.
The
link in the last DCB in the list has a value of zero.
The static data in the DCB gives such information as the generic
device name,
unit quantity and
links to individual unit data, the
address of the driver dispatch tabie,
and types of I/O functions
supported by the driver.
Typically,
the
Executive QIO directive
processing code and not the driver code accesses the DCB.

2.1.4

Unit Control Block (UCB)

The unit control block holds much of the static information about an
individual
device unit and contains a
few dynamic parameters.
Although unit control blocks need not be any prescribed length for
different devices,
all
unit control blocks for the same device type
must be of equal length.
(The UCB length is stored
in the device
control block.)
This condition allows the UCB to contain varying
amounts of unit- and device-independent data for different types of
devices.
A UCB, one of which exists for each device unit, enables a driver to
access most of the other structures in the I/O e~vironment.
A UCB
provides access to most of the dynamic data associated with
I/O
operations.
Given the address of a UCB, a driver may readily find
most of the other data structures in which it
is interested because
the proper links exist.
Because of this access information, the UCB
is a key control block in the driver I/O structure.
The static data in the UCB includes pointers to other I/O structures,
definitions of unit control bits which regulate directive processing,
definitions of unit status bits which describe operational conditions,
and definitions of unit- and device-dependent characteristics and
storage cells.
Data in the UCB is accessed and modified by botn the Executive and the
driver.

2.1.5

Status Control Block (SCB)

The status control block holds driver context for operations on a
device unit.
In
the SCB are stored such data as the pointer to the
head of the queue of input/output requests;
the link to
the fork
blocks queued for the unit;
the fork process context;
timeout, unit
status, and error logging
information;
and the address for
the
controller
request block (KRB) representing the device controller (if
the device has a controller).
The Executive accesses the SCB to set up an
I/O request,
to store
context while a
request
is
1n progress,
and to post results and
read
status. When the driver accesses the SCB,
it is usually for
access only.
The number of status control blocks depends on the processing support
in the Executive.
If the controller itself cannot handle parallel
operations, only one SCB is needed for each controller.
In such a
case,
a controller can have only one unit processing a command at one
time, and there is no need to store context for more than one unit at

2-3

DEVICE DRIVER I/O STRUCTURES
a tin'e. There is also no need for a physically separate controller
request block (KRB)
to separate generic data from unit context.
Therefore, the driver data base contains the required KRB cells in the
statl,s control block.
If the controller allows parallel operations and the Executive
supports this feature, there must be one SCB to store context for each
unit capable of operating independently on the controller. In such a
configuration, a cell in each seB points to the KRB of the controller
to which the units are connected.

2.2

DRIVER DISPATCH TABLE (DDT)

The driver dispatch table 1 contains the entry points to and the
interrupt entry addresses for the driver.
An entry point is the
location at which the Executive calls the driver to perform a specific
function.
An interrupt entry address is a location to which the
central processor or the Executive transfers control within the driver
for servicing hardware interrupts. The pointer to the interrupt entry
address resides either in an interrupt control block if the driver is
loadable or in the device interrupt vector in the system common area
of the Executive if the driver is resident.
Every driver has four conventional entry points as follows:
•

I/O initiation

cancel I/O

dev i ce timeout

•

device power fail

Two ml)re entry points are added for controller and
off-ILne status changes:
•

KRB status change

ueB status change

unit

on-line

and

For many devices, these status change entry points are merely a return
to the Executive calling routine.
There are two additional entry points that have been added for advance
driver features:
~

Deallocate buffers and next command (FOX TTDRV)

Address checking
drivers)

and

conversion

(queue

optimization

1. The DDT is not a structure in the strict sense of the word

disk

because
it is defined in the instruction part of the driver code. However,
because it contains addresses for dispatching code, it is included in
the data structure description.
2-4

DEVICE DRIVER I/O STRUCTURES
2.2.1

I/O Initiation

The Executive transfers control to this entry point to inform the
driver that work for it is waiting to be done. To make work for the
driver, the Executive performs
predriver-initiation
processing.
(Predriver initiation is described in Chapter 3). If, at the end of
predriver processing, the Executive has I/O packets queued for the
driver, it calls the driver at this ~ntry point.
When the driver gets control at its I/O initiation entry point, R5
contains the address of the UCB for the unit on which the request is
to be processed. To establish access to the I/O packet, the driver
calls
an Executive routine that either returns information in
registers concerning both the packet to be processed and
the
associated data in order to gain access to the data structures l or
causes the driver to dismiss itself.
(There may be no packet to
process or the driver may already be busy.)
Once control is returned to a driver and there is a request to
process, the driver must extract the information from the registers,
establish data within the control blocks, and process the request.
This means that the driver proceeds with an I/O request until it sets
the GO bit on the device, which physically initiates the I/O
operation.
Typically a driver is called at this entry point when there is a
packet in the I/O queue. However, a driver can be called before a
packet is placed in the I/O queue. Refer to the description of the
U.CTL control flag UC.QUE in Section 4.4.4 for information on queueing
an I/O packet to the driver.

2.2.2

Cancel I/O

To terminate an in-progress I/O operation, the system flushes the I/O
queue and calls the driver at this entry. There are many situations
in which a task must terminate I/O. When such a termination becomes
necessary, a task issues an Executive request and the Executive relays
the request to the driver by calling it at this entry point.
The driver is responsible for checking that the I/O operation
in-progress was issued from the task that is forcing the termination,
and for completing or terminating the operation before returning to
the caller.
Typically, a driver is called at this entry point only when an I/O
operation is in progress.
A driver can be called even if the unit
specified is not busy. Refer to the description of the U.CTL control
flag
UC.KIL in Section 4.4.4 for information on unconditional
cancelling of I/O.

2.2.3

Device Timeout

When a driver initiates an I/O operation, it can establish a timeout
count.
If the operation fails to complete within the specified
interval, the Executive notes the lapse and calls the driver at this

1. The $GTPKT routine, which gets a packet for the driver to
is described in Chapter 7.
2-5

process,

DEVICE DRIVER I/O STRUCTURES
entry p)int. Using this facility, a driver can wait for an interrupt
but need not hang up if the interrupt never occurs. Thus, no driver
should ever stall on a request because a hardware failure prevented an
expected interrupt from happening.

2.2.4

Device Power Failure

The Exe~utive calls the power failure entry point when power is
restored after a failure any time the controller is busy (that is,
when I/J is in progress). Typically, a driver responds to a power
failure in the same manner it responds to a timeout.
In such cases,
the power failure entry point may simply be a return to the caller
because recovery will occur by means of the timeout entry point. The
driver is called for both controller and unit power failure unless the
driver is associated with a common interrupt controller. For common
interrupt controllers, the driver is called at this entry point only
for unit power failure and is called at a special entry defined in the
common interrupt table for controller power failure.
A driver can be called when power is restored regardless of the
existence of an outstanding I/O operation. Refer to the description
of the U.CTL control flag UC.PWF in Section 4.4.4 for information on
unconditional calIon power failure.

2.2.5

Controller and Unit Status Change

Two entry points are required for configuration status changes of the
controller and units. The Executive enters one entry point to put the
controller on-line and take it off-line.
The other entry point,
called once for each unit whose status changes, is for putting units
on-line and taking them off-line. The driver must show successful
completion of the on-line or off-line request or the Executive will
not effect the status change. The driver has 60 seconds to perform
whatever
synchronization
it
requires before returning to the
Executive.
In most cases, however,
the
driver
will
return
immediately.

2.2.6

Device Interrupt Addresses

Control passes to an interrupt address when a device, previously
initiated by the driver, completes an I/O operation and causes an
interrupt in the central processor. A device may have associated with
it more than one interrupt entry. For example, a full duplex device
such as a terminal will have two interrupt addresses.
The interrupt
entry differs from an entry point in that the connections between the
device and the driver is more direct--the Executive is not involved.
The interrupt addresses are arranged in a block in the DDT.
The
arrangement is general enough to support multicontroller drivers such
as the terminal driver. The block defines the address or addresses to
include in the vector for the driver. There is no restriction on the
number of vectors each controller has, and the number of vectors is
implied by the number of addresses in the interrupt address block.

2.3

TYPICAL CONTROL RELATIONSHIPS

This section presents different arrangements of the control structures
that are found in RSX-IIM-PLUS.
The section concentrates on the
2-6

DEVICE DRIVER I/O STRUCTURES
relationships among device control, unit control, status control,
and
controller
request blocks and controller tables based on hardware and
functions supported.
Descriptions of the detailed contents of the
structures is left to Chapter 4, where the coding requirements are
presented.
Some of the arrangements are not conventional but are
shown to convey the flexibility you can find in a system.
Section 2.4
shows how such arrangements fit
into the overall system I/O data
structure.
The arrangements described in this section illustrate the strategy in
offering a
flexible
I/O data structure.
There need be only one
controller table for each controller type.
Multiple-device control
blocks for
a
single device type
reflect the capability to handle
varyinq characteristics.
The existence of one or more status control
blocks depends on the degree of parallelism possible:
one SCB for
each controller servicing several units (no parallelism);
or one
for
each dE~vice unit combination on the same controller (unit operation in
pa raIl E~ I) •
The I/O data structure reflects the hardware configuration that the
data structures describe.
The
flexibility
in the data structure
arrangements provide flexibility
in configuring
I/O devices.
The
information density in the structures themselves reduces the coding
requirements for the associated drivers.

2.3.1

Multiple Units per Controller, Serial Unit Operation

A typical arrangement of structures for a user-written driver is shown
in FiSjure 2-1.
The arrangement could represent an RK05J controller
with two RK05 drives attached.
A single controller table
(CTB)
defines the existence of the controller type on the system.
One
device control block (DCB) establishes the characteristics for
the
type of device running on the controller.
The status control block (SCB) and controller request block (KRB)
are
contiguous in this arrangement because the software does not allow
another I/O operation to begin while the controller
is busy.
A
separate unit control block (UCB) describes each unit attached to the
controller.
The UCBs are associated with the SCB, which contains the
context of the operation currently in progress.

2.3.2

Single Controller, Serial Operation

Another typical conventional arrangement of
structures
for
a
user-written driver is shown in Figure 2-2, which could represent two
LPll controllers, one with an LP04 and the other with an LP05
attached.
It
represents the simplest case of driver processing.
Figure 2-2 shows what is required for a controller that allows only a
single I/O operation for each controller.
A single controller table
defines the existence of the controller type on the system.
One
device control block establishes the characteristics for the type of
device running on the controller.
The status control and controller request blocks are contiguous
in
this arrangement because, while the controller is busy, another I/O
operation cannot begin.
Only one SCB is necessary to store the
context of the
unit operation.
The UCB points to the SCB, which in
turn points to the KRB of the unit's controller.
Because the system
must handle interrupts from multiple controllers, the controller table
points to the KRB of each controller present.

2-7

DEVICE DRIVER I/O STRUCTURES

DCB

CTB

List] I

List

DCB

J 1
CTB

I
KRB

,....

UCB

SCB

UCB

ZK-249-81

Figure 2-1

2.3.3

Multiple Units per Controller, Serial Unit Operation

Parallel Unit Operation

Some devices, such as the RK06, allow multiple units to have seek
operations in progress at the same time. In particular, the RK06
allows such operations to overlap a data operation. Figure 2-3 shows
the arrangement needed in the software structures to support parallel
operations on one controller.
Two additional structural changes are required from the serial
operation arrangement. First, because more than one unit may have an
operation pending at the same time, a structure is needed to store
unit ~ontext. Therefore, for each unit (and each unit control block)
there is a separate status control block. Second, because interrupts
can c')me from more than one unit, some way must exist to access the
proper unit. As a result, the controller request block contains a
table of unit control block addresses that allows the driver to find
the structures for the unit generating an interrupt.

2-8

DEVICE DRIVER I/O STRUCTURES
DCB
List

CTB

t I

List

t I

CTB

DCB

KRB

UCB

SCB

UCB

KRB

SCB ZK-250-81

Figure 2-2

Single Controller, Serial Operation

CTB

DCB

SCB

UCB

f-----

UCB

KRB
SCB
UCB
Table
ZK-251-81

Figure 2-3

2.3.4

Parallel Unit Operation (Overlapped Seek)

Multiple-Access (Dual-Access) Operation

Some devices, such as the RK06, have a dual port option that provides
multiple-access paths to units.
On the RK06, dual ports on the unit
enable a single unit to be electronically switched between two
controllers.
Figure 2-4 shows the several changes in the structures
needed to support dual-access operations.
2-9

DEVICE DRIVER I/O STRUCTURES

Common
Interrupt
Table

.....
r4'-"

DeB

CTB

Current
KRB
Pointer

•
~

SCB

UCB

.....

Port A
KRB
Table

Port B

KRB

Current
KRB
Pointer

UCB

SCB

UCB
Table

Port A
KRB
Table

KRB

-----

Port B
UCB
Table

Figure 2-4

Dual-Access Operation

Separate status control blocks are needed for each unit because,
if
one controller is currentJy busy, the alternate controller can be idle
and allow the operation to proceed. The difference in the dual-access
structure is that the SCB no longer points to the same controller
request block all the time as in the overlapped seek arrangement. The
Executive can change the SCB pointer to a KRB to reflect the
capability to electronically switch a unit between two controllers.
To enable the software to differentiate which controllers may access a
unit, the SCB has a table of KRB addresses. For dual-access disks,
the table contains two entries:
the addresses of the controller
request blocks for each controller between which the unit can be
swi tchf~d •

2.4

OVERVIEW OF DATA STRUCTURE RELATIONSHIPS

This section presents an overview of the relationships among the
user-written driver data structures previously introduced in this
chapter and the Executive I/O structures and DIGITAL-supplied driver
structures.
The goal of the section is to convey the general manner
in which user-written structures and code link into the system liD
scheme and to describe generally the use to which the system puts the
structures.
The specific user-written structures are simplified
somewhat so that the emphasis is placed on the linkages with other
parts of the system rather than on the details of user-written
structural relationships.

2-10

DEVICE DRIVER I/O STRUCTURES
This sE~ction should be used with Section 2.3 to understand the general
structural concepts.
For example, Section 2.3 describes various
arrangE~ments of unit control, status control, and
controller request
blocks based on hardware functions the software structures support.
This sE~ction treats such arrangements as an engineering black box that
is oriented in the general I/O environment. Thus, in the generalized
I/O data structure depicted in this section, the pointers in the KRB
table of the SCB are not shown and the table is simply marked KRB
Table.
Figure 2-5, which provides the basis for the presentation of the I/O
data structure, shows the individual elements and the important link
fields within them. The numbers in the figure correspond to the
numbers in the lead paragraphs of the text to simplify the discussion
and to guide you through the data structures.
1.

The location represented by the Executive symbol $DEVHD is a
cell in system common (SYSCM). It is the head (or start) of
a singly-linked, unidirectional list of all device control
blocks in the system. The first word in each DCB is a link
to the next DCB.
The list of device control blocks is one of the two threads
through
the
system
data
tables
for
device-related
information. For example, the list is the means by which
executive routines scan the data structures to determine what
devices are on the system and what is the status of units.
User-written device control blocks must be linked into the
list of system defined DCBs.

Every loadable driver is associated with a partition control
block (PCB).
The PCB defines the characteristics of the
memory area into which the driver is loaded.
The Executive
and tasks such as LOA and UNL reference the data in the PCB.
A driver is not concerned with the PCB.

If a task is attached to a unit, the UCB has a pointer to the
task control block (TCB) of that task.

The task header is an independent entity in the I/O data
structure and the driver never accesses it. A copy of the
task header is taken from the task partition and stored in
the Executive dynamic storage region whenever the task is
actually in memory. This copy is then used by the Executive.
A logical unit table (LUT) entry in the task header has two
items of interest: a pointer to an associated unit control
block and, if a file is being accessed, a pointer to a window
block.
The Executive accesses the logical unit table of a
task during a QIO request and indexes the table by the
logical unit number specified in the QIO request.

A device control block has a pointer to the unit control
block of the first related unit. Because the length of a UCB
is stored in the DCB and all ueBs are allocated in a
continuous area, access to all the UCBs related to that DeB
is possible. This arrangement allows software to access all
related unit information for a device type.
A DCB also has a pointer to the start of the driver dispatch
table.
This pointer allows the Executive to call the driver
at its entry points to process an I/O-related
or
a
reconfiguration request.

2-11

POINTER TO

DEVICE VECTOR

ICB

-----

DDT

Common
Interrupt
Table

$DEVHD

I
I
I
I

DCB

I/O PACKETS
I/O QUEUE

lOADABlE
DRIVER
PCB

UCB

CTB

FORKBLOCK
SCB

<
H
()

tzl

Current
I/O
Packet

::tI

<
tzl

UCB TABLE

FCB
(INDEX)

"oen
toi

FORKBLOCK -

TASK
HEADER

LUT ENTRY

If- -_ _

KRB TABLE

KRB

NOTE

()

UCB TABLE

I•

::tI

VCB
MOUNTED
VOLUME

@
SCB

lUT

::tI

KRB

UCB

tzl

KRB TABLE
TCB OF
ATTACHED
TASK

TCB OF
ACP

CTB

$FRKHD

•

- --.

I
I
I
I
I

$CTLST

I
(2)
L. ~---------. J

t'-J
I-'
t'-J

LINK TO
FIRSTICB

DRIVER CODE

1'Jt:Jl.1 UCtl

WB
(TASK)

::tI

tzl

en
WB

(VOLUME)

·FCB
(TASK)

This diagram shows only a typical example;
it does not show every possible arrangement.
ZK·253·81

Figure 2-5 Composite I/O Data Structures

DEVICE DRIVER I/O STRUCTURES
6.

Each unit control block contains a pointer back to its
related DCB. This backpointer allows the Executive interrupt
dispatch code to enter the proper driver (through the pointer
to the driver dispatch table).
Associated with each UCB is a status control block. The SCB
is shared by all units for a device type that does not
require units to operate in parallel. When units can operate
in parallel, each UCB has its own associated SCB.

As part of processing a QIO directive (queued I/O request),
the Executive builds a structure called an I/O packet.
Storage for packets is in the system dynamic storage region
(the pool). The Executive connects the packets by a pointer
in each packet to form a singly-linked list called the I/O
queue.
The Executive maintains two pointers in the SCB to
the list of packets. The first pointer is to the start of
the list and the second pointer is to the last packet in the
list.
The driver should not access the list of I/O packets
directly. When the Executive transfers control to the driver
to initiate processing of an I/O request, the
driver
immediately calls an Executive service routine to get a
packet to process. The routine passes, to the driver, data
sufficient to process the request (for example, the address
of the packet). Thus, the Executive, and not the driver,
removes a packet from the queue of packets. However, in
performing the I/O request, the driver can access certain
fields in the packet to be processed because a pointer to the
currently active I/O packet is kept in the SCB.l
The Executive determines the ordering of packets in the
queue. Typically, higher-priority requests are placed at the
head of the queue.

At least one status control block (SCB) exists for each
controller.
Where
a
controller and software support
operations in parallel on multiple units, one SCB exists for
each unit capable of operating independently. A pointer in
the SCB connects to the controller request block (KRB) of the
controller to which the related unit is connected. If
multiple-access paths between a unit and controller are
possible, the KRB pointer is dynamic. The KRB to which the
SCB points at one instant therefore, is considered to be the
currently
assigned
KRB.
To reflect the existence of
alternate controllers, a table of pointers to all the
possible KRBs is contained in the SCB, separate from the
pointer to the currently assigned KRB.
The fork block in the SCB contains some of the driver process
context.
The driver executes an Executive routine so that
processing will occur at fork level. To preserve processing
status, the routine stores some context in the fork block.
When the driver eventually runs again, the fork processor
recovers the proper context from the fork block.

1. Normally, the driver does not directly manipulate the I/O queue.
An excE!ption is when a driver needs to examine an I/O packet before it
is queued or instead of having it queued. This exception involves a
status bit in a control byte of the unit control block. For more
informcltion on queuing of I/O packets to the driver, refer to the
description of the UC.QUE bit in Section 4.4.4.
2-13

DEVICE DRIVER I/O STRUCTURES
On multiprocessor systems, the fork block contains an extra
cell to define the processor on which the driver must execute
the
I/O request.
The
Executive routine that preserves
context in the fork block ensures that certain driver code is
processed on a particular processor.
The fork blocks for pending driver processes are connected in
a
singly-linked list,
the head of which is in a location
($FRKHD)
in the
Executive region.
Generally,
the
fork
processing
routines link a
fQrk block in FIFO order.
At
location $FRKHD+2 the executive maintains a
pointer to
the
last fork block in the list.
9.

Associated with each open file on a mounted volume is a
file
control block
(FCB).
The file system alone uses the FCB to
control access to the file.

10.

For each open file on a mounted volume, a window block exists
for
each task that has the file open to hold pointers to
areas on the volume on which the file resides.
The
function
of the window block is to speed up the process of retrieving
data items from the file.
(The associated ACP need not be
called to convert a virtual block number in a file to a
logical block number on the device.)
The driver
is not
concerned with the window block.

11.

The driver dispatch table (DDT) is part of the driver code
and,
through the vector and the interrupt control block, is
the means by which the device interrupts are passed to
the
driver.

12.

The controller request blocks (KRB) are linked into the
I/O
data structure through the pointers in the controller table
(CTB).
The table of KRB address in the CTB is static.
The KRB table allows the Executive access to
the structures
for
a
controller when it initiates an interrupt.
To report
the termination of a data transfer command,
a controller
initiates an
interrupt.
(While such a controller-initiated
interrupt is in progress, the hardware delays interrupts from
units.)
The Executive determines the correct KRB by indexing
the CTB with the controller number from the PS word
in the
vector.
For a controller
that allows
unit operation
in parallel
(overlapped seek support), the related KRB must have a table
of UCB addresses.
This table allows the driver to access the
structures of the unit that generates an interrupt.
When a
unit interrupts, its controller
records
(in the attention
summary register)
the physical number of the interrupting
unit.
The driver must retrieve the number and
use
it to
index the UCB table
in the KRB to access the proper unit
control block.
To support unit operation in parallel, the KRB also contains
a queue to
regulate controller access.
This queue, the
controller request queue, is a list of fork blocks for driver
processes that have requested and have been denied access to
the controller.
The driver requests access to a
controller.
If the controller is busy, the Executive forces the driver to
wait for access by placing the fork block
in the queue of
processes waiting for access.
The Executive gives precedence
to control access over requests for data transfer by placing
positioning
requests onto the front of the queue and adding

2-14

DEVICE DRIVER I/O STRUCTURES
data transfer requests to the end of the queue. When a
unit
is given access,
the controller status is set to busy and
unit UCB address is set to connect the KRB to the owned UCB.
To indicate what unit to process on a controller
initiated
interrupt, a cell in the KRB points to the unit control block
(UCB) of the unit that currently owns the KRB.
The KRB queue cells have two words.
The first word points to
the fork block in the SCB of the next unit to get access.
The second word points to the fork block in the SCB of the
last unit to get access.
If the first word is 0, then the
second word points to the first and no unit is waiting for
access to the controller.
13.

The location represented by the Executive symbol $CTLST is a
cell
in system common (SYSCM).
It is the head (or start) of
a singly-linked, unidirectional list of all controller tables
(CTBs)
in the system.
A word in each CTB is a link to the
next CTB.
The last CTB in the list contains a link word of

The list of controller tables is one of the two
threads
through the system for device-related information.
(The list
of device control blocks is the other thread.) A user-written
controller
table
must
be
linked
into the list of
system-defined CTBs.
This list is the mechanism by which
system routines,
such as those for reconfiguration, access
I/O data structures for hardware information.
14.

One volume control block (VCB) exists for each mounted volume
in the system.
The VCB maintains volume-dependent control
information.
Pointers within the VCB connect to
the
file control block
(FCB)
and window block (WB).
The FCB and WB control access
to the volume's index file, which is a file of file headers.
All
FCBs
for
a volume form a linked list starting from the
index file FCB.
These linkages aid in keeping file access
time to a minimum.
A conventional driver does not access any
of these structures.

2-15

CHAPTER 3
EXECUTIVE SERVICES AND DRIVER PROCESSING

The Executive provides services related to I/O drivers. Some services
are provided before a driver process is initiated and are therefore
called predriver initiation services.
The predriver
initiation
services are those performed by the Executive during its processing of
a QIO directive; these services are not available as Executive calls.
Predriver initiation processing extracts from the QIO directive all
I/O support functions not directly related to the actual issuance of a
function request to a device. If the outcome of predriver initiation
processing does not result in the queuing of an I/O Packet to a
driver, the driver is unaware that a QIO directive was issued.
Many
QIO directives do not result in the initiation of an I/O operation.
Other services are available to the driver after it has been given
control, either by the Executive or as the result of an interrupt.
They are available as needed by means of Executive calls.
An important concept used in this section and in Chapter 4 is the
state of a process. In RSX-llM-PLUS, a process can run in one of two
states, user or system. Drivers operate entirely in the system state;
the programming standards described in Chapter 4 apply to system-state
processl~s •

3.1

FLOW OF AN I/O REQUEST

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

The system is running 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 is the sample request under
discussion.

•

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

•

The controller in question executes only a single operation at
a time.

3-1

EXECUTIVE SERVICES 'AND DRIVER PROCESSING
3.1.1

Predriver Initiation Processing

The I/O flow proceeds as described below:
1.

Task issues QIO directive
The user program first either statically (by QIOW$C,
QIOW$,
QIO$C, or QIO$) or dynamically (by QIOW$S or QIO$S) creates a
directive parameter block (DPB) containing information about
what I/O is to be performed on what device.
Then, it issues
the directive.
All Executive directives are called by means of EMT 377.
The
EMT causes the processor to push the PS and PC on the stack
and to pass control to the Executive's directive processor.

QIO Dispatching
The Executive directive dispatcher DRDSP ascertains that
the
EMT
is a QIO directive and calls the QIO directive processor
DRQIO.

First-level validity checks
The QIO directive processor validates the logical unit number
(LUN) and the Unit Control Block (UCB) pointer.
DRQIO checks
whether the LUN supplied in the directive parameter block
is
a
legal value.
If it is not a legal value, the directive is
rejected.
If the LUN is legal, DRQIO checks whether a valid
UCB pointer
exists
in the Logical Unit Table (LUT) for the
specified LUN.
This check ascertains whether
the LUN
is
assigned.
If the check fails, the directive is rejected.
If
both these checks are successful,
DRQIO then performs the
redirect algorithm.

Redirect algorithm
Because the UCB may have been dynamically redirected
by a
Redirect
command,
QIO directive processing
traces the
redirect linkage until the target UCB is found.
The
target
UCB provides the links to most of the other structures of the
device to which the I/O operation will be directed.

Additional validity checks
The event flag number (EFN) is validated,
as well
as the
address of the
I/O Status Block
[IOSB).
If either is
illegal, the directive is rejected.
Immediately following
successful validation, DRQIO resets the event flag and clears
the I/O status block.

Obtain storage for and create an I/O Packet
The QIO directive processor now acquires a 20-word
block of
dynamic storage
for
use as an I/O Packet.
It inserts into
the packet the device-independent data items that are
used
subsequently
by both the Executive and
the driver
in
fulfilling the I/O request.
Most
items originate
in the
requesting task's Directive Parameter Block (DPB).
At this point, DRQIO sets the directive status to +1,
which
indicates
directive acceptance.
Note
that a
directive
rejection is a return to the caller with the C bit set.
In
addition, a directive rejection is transparent to the driver.

3-2

EXECUTIVE SERVICES AND DRIVER PROCESSING

Validate the function requested
If the function is legal, DRQIO checks to see whether the
unit is on-line.
If the unit is off-line, the packet is
rejected. The function is one of four possible types:
Control
No-op
ACP
Transfer
With the exception of Attach/Detach, control functions are
queued
to
the
driver.
If the bit UC.ATT is set,
Attach/Detach will also be queued to the driver.
If the
requested function does not require a call to the driver, the
Executive takes the appropriate action and calls the I/O
Finish routine ($IOFIN).
No-op functions do not result in data transfers.
The
Executive performs them without calling the driver. No-ops
return a status of IS.SUC in the I/O status block.
ACP functions may require processing by the file system.
More typically, the request is a read or write virtual
function that is transformed into a read or write logical
function without requiring file-system intervention. When
transformed into a read or write logical function, the
function becomes a transfer function (by definition) •
Transfer functions are address checked and queued to the
proper driver.
This means that DRQIO checks the address of
the I/O buffer, the byte count, and the alignment requirement
for the specified device.
If any of these checks fails,
DRQIO calls the I/O Finish routine ($IOFIN), which returns an
I/O error status and clears the I/O request from the system.
If the checks succeed, DRQIO either places the I/O Packet in
the driver request queue according to the priority of the
requesting task or, if the UC.QUE bit is set, gives the
packet directly to the driver.
(See Section 4.4.4 for a
description of the UC.QUE bit.)

3.1.2

Driver Processing
8.

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

3-3

EXECUTIVE SERVICES AND DRIVER PROCESSING

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.

10.

Interrupt processing
When a previously issued I/O operation interrupts, the
interrupt causes the driver to be entered.
The driver
processes the interrupt according to the programming protocol
described in Chapter 1.
Acc~rding
to the protocol, the
driver may process the interrupt at priority 7, at the
priority of the interrupting device, or at fork level. If
the processing of the I/O request associated with the
interrupt is ,still incomplete, the driver initiates further
I/O on the device (Step 9). When the processing of an I/O
request is complete, the driver calls $IODON.

11.

I/O Done processing
$IODON removes the busy status from the device unit and
controller, queues an AST if required, and determines whether
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 and looks for more work
(Step 8). This procedure is followed until the driver finds
the queue empty, whereupon the driver returns to its caller
and the driver process vanishes.
Eventually, the processor is granted to another ready-to-run
task that issues a QIO directive, starting the I/O flow anew.

3.2

EXECUTIVE SERVICES AVAILABLE TO A DRIVER

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

Get Packet ($GTPKT)

Interrupt Save ($INTSV)

Create Fork Process ($FORK)

I/O Done ($IODON or $IOALT)

3-4

emphasis

because

EXECUTIVE SERVICES AND DRIVER PROCESSING
3.2.1

Get Packet ($GTPKT)

The Executive, after it queues an I/O Packet, calls the appropriate
driver at its I/O initiation entry point. The driver then immediately
calls the Executive routine $GTPKT to obtain work. l
If work is
available,
$GTPKT delivers to the driver the highest-priority,
executable I/O Packet in the driver's I/O queue, and sets the SC8
status to busy. If the driver's I/O queue is empty or if the driver
is busy, $GTPKT returns a no-work indication.
If the SCB related to the device is already busy, $GTPKT so
the driver, and the driver immediately returns control
Executive.

informs
to the

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

3.2.2

Interrupt Save ($INTSV)

A driver should not directly call the $INTSV coroutine but should use
the INTSV$ macro call. Therefore, if the driver is loadable, it need
not call $INTSV and the macro will not generate the call in the
driver.
(The interrupt save processing is done by either the
interrupt control block or the appropriate common interrupt routine in
the Executive.)
If a driver is resident, the INTSV$ macro call
generates the call to the $INTSV coroutine. The coroutine saves code
in the driver because the call is shorter than the code to save and
restore the conventional registers R4 and R5. More importantly, the
$INTSV coroutine gets the driver onto the system stack if it is not
already there. The INTSV$ macro is described in more detail in
Section 4.3 and the interrupt entry point is described in Section 4.5.

3.2.3

Create Fork Process ($FORK)

Synchronization of access to shared data bases is accomplished by
creating a fork process. When a driver needs to access a shared data
base, it must do so as a fork process;
the driver becomes a fork
process by calling $FORK. The SC8 contains preallocated storage for a
4- or 5-word fork block. See Section 4.4.5 for a description of the
fork block.
Section 7.4 contains details on $FORK. After $FORK is
called, a routine is fully interruptable (priority 0), and its access
to shared system data bases is strictly linear.

3.2.4

I/O Done ($IODON or $IOALT)

At the completion of an I/O request, the subroutines $IODON or $IOALT
perform a number of centralized checks and additional functions:
•

Store status if an IOS8 address was specified

•

Set an event flag if one was requested

I.An exception is a driver that handles special user buffers. Such a
driver must call certain other Executive routines before calling
$GTPKT. See Section 4.4.4 for a description of the UC.QUE bit.

3-5

EXECUTIVE SERVICES AND DRIVER PROCESSING
•

Determine whether a checkpoint request can now be honored

•

)etermine whether an AST should be queued

$IODON and $IOALT also declare a significant event, reset the SCB and
device unit status to idle, and release the dynamic storage used by
the completed I/O operation.

3-6

CHAPTER 4
PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER

Chapters 2 and 3 give overviews of data structures and Executive
services,
respectively.
This
chapter
summarizes
programming
standards, presents overviews of
programming
requirements
for
user-written driver code and data, and gives details of the data
structures and driver code.
Executive services are covered in Chapter
7.

4.1

PROGRAMMING STANDARDS

I/O drivers function as integral components of the RSX-11M-PLUS
Executive, and this manual enables you to incorporate I/O drivers into
your system. User-written drivers must follow the same conventions
and protocol as the Executive itself if they are to avoid complete
disruption of system service.
Failure to observe the internal
conventions and protocol that are described fully in Chapter 1 can
result in poor service and reductions in system efficiency.
The programming conventions used by RSX-11M-PLUS system components are
identical to those described in Appendix E of the PDP-11 MACRO-II
Language Reference Manual. DIGITAL urges you to adhere to these
conventions.

4.1.1

Programming Protocol Summary

Drivers are required to adhere to the following
when processing device interrupts:

internal

conventions

No registers are available for use unless $INTSV has been
called, or the driver explicitly performs save and restore
operations.
If $INTSV is called, registers R4 and RS are
available;
any other registers must be saved and restored.
If the driver is to call $INTSV directly,
it must do so
immediately
because
$INTSV
attempts
to retrieve the
controller number from the PS.

Noninterruptable processing must not exceed 20 instructions,
and processing at the priority of the interrupting source
must not exceed SODus.

Only a fork process should modify system data bases.

4-1

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
4.1.2

Accessing Driver Data Structures

All th~ driver data structure elements have symbolic offsets. Because
the p1ysical offset values may vary from one version of the Executive
to another, your user-written driver code should always use the
symbo13 to access the elements.
Accordingly, your driver code should not step from one structural
elemen: to another
(relying on the juxtaposition of data structures
and in·jividual words in a data structure)
but should access each
elemen: by symbolic offset. By following this aspect of good coding
practi;e, you can reduce debugging time when converting an RSX-IIM
driver to run on RSX-IlM-PLUS. Many of the offsets in the RSX-llM SCB
differ physically from those in the RSX-llM-PLUS SCB but have the same
symbolLc values.
On the other hand, it is a common coding practice to assume that zero
(particularly link pointers such as D.LNK) will remain zero.
This a:~sumption allows the saving of one word per instruction by
substi :uting an instruction such as MOV (R3) ,R3 for MOV D.LNK(R3) ,R3.
DIGITA~ recognizes that such practices are followed
and consequently
attemp':s to keep such offsets zero.
offset~

4.2

OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER DATA BASES

You should create the source code for your user-written driver data
base
.n a file separate from that of the driver code. You assemble
this f Ie to create the driver data base module.
If you make your
data base resident, your data base module will be linked separately
from the driver code and will be linked to the system device tables
module SYSTB.OBJ.
(The source code for the SYSTB module is created in
UFD [1 _,10] during system generation.) If your data base is in a
separai:e module and is to be loadable, it will be linked to the end of
the dr ver code module.
If your driver data base is in the same
module as that of your driver code, it must be at the end of the
driver code.
The det.ailed descriptions of the driver data structures are in Section
4.4.
A few fields in the structures are conditional on certain
featUrE's in the Executive.
You therefore must use conditional
assembJy directives and some system-wide symbols that are defined in
the Expcutive assembly prefix file RSXMC.MAC, which is created during
system generation.
To crecite the source code, you need to know,
in addition to the
structures, what ordering and labeling are required. These
requirE'ments, though not extensive, are important in linking and
loadin~
your driver data base. The general coding requirements for
both lcadable and resident driver data bases are described in the
following subsections.
detail~d

4.2.1

General Labeling and Ordering of Data Structures

If you are creating a loadable data base, you must
LOAD rcutines, two global labels as follows:

specify,

for

the

$~xDAT::

marks the start of the user-written driver data base.

$xxEND: :

marks the end of the user-written driver data base,
that is, immediately following the final word of the
data base.

4-2

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
The chclracters xx represent the 2-character mnemonic of the device
that your driver data base supports.
If either or both of these
labels are not defined, LOAD cannot determine the length of your data
base when you attempt to load your driver.
There is no mandatory ordering of 'the different structures in a driver
data base.
DIGITAL suggests, however, that you place the DCB first,
followed by the UCB, the SCB(s), the KRB(s), and the CTB.
If you do
not follow this ordering scheme,
you must specify the starting
location of the first (or only) DCB as described in Section 4.2.2.

4.2.2

Device Control Block Labeling

If the data base for a driver is to be loadable,
the
LOAD routines
require either that the first
(or only) DCB be identified by the
global label $xxDCB::
or that the DCB be at the start of the data
base.
If the data base for a driver is to be resident, you must define the
start of the first (or only) DCB with the global label $USRTB::.
This
label is required to link the last DCB defined
in the SYSTB module
with the DCB in your driver data base.
If you fail to supply this
symbol, the Task Builder will generate an undefined
reference error
when it builds the Executive.

4.2.3

Unit Control Block Ordering

All the UCBs associated with a specific device control block
(DCB)
must be contiguous with each other and must be of equal length~
These
requirements are necessary because the DCB has only one link to the
UCBs,
and that link is to the first UCB.
Two data elements, the UCB
length and the number of units, are stored in the DCB;
they, together
with the link to the first UCB, are used to locate subsequent UCBs.
If you do not follow these requirements, no software can access the
UCBs.

4.2.4

Status Control and Controller Request Blocks

All user-written drivers that do not need separate storage for
independent unit context should use the continuous allocation of the
KRB and SCB.
(For an explanation of when independent unit context
is
required,
refer to the discussion of overlapped seek I/O in Section
1.4.1.) Therefore, the KRB and SCB are contiguous and some fields of
each structure overlap.
This arrangement saves space that would be
required for one SCB for each independent unit.
Because only one unit
can be active at anyone time,
all
units attached to the same
controller can share the SCB.
This arrangement of the KRB and the SCB
is described in Section 4.4.7.

4.2.5

Controller Table

You must define the start of the table of KRB addresses
in the CTB
with the global label $xxCTB::.
Both the INTSV$ macro call and the
Executive LOAD routines require this label.
If your data base is resident, you must use the CTB macro at the CTB
link word L.LNK.
The CTB macro automatically generates a global label
that provides the linkage between the last CTB defined
in the SYSTB
4-3

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
module and the CTB defined in your driver tables module.
(The
definition of the CTB macro is created in the file RSXMC.MAC during
system generation.)

4.3

OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER CODE

To create the source code to drive a
follow:;ng steps:

must

perform

the

Thoroughly read and understand this manual.

Familiarize yourself in detail with the physical
its operational characteristics.

device

and

Determine the level of support required for the device.

Determine actions to be taken at the driver entry points.

Create the driver source code.

You can write driver code
follow:,ng:

for

device,

RSX-llM-PLUS

you

that

does

one

the

Supports standard functions and runs on RSX-llM-PLUS only.

Supports standard functions and is written so that it is
(This
compatible with use on both RSX-llM and RSX-llM-PLUS.
driver needs separate data bases for each system.)

Supports advanced features and runs on RSX-llM-PLUS only.
(Although Chapter 1 discusses advanced features, this manual
Your
does not describe how to program advanced features.
best guide to utilizing advanced features is to use a
DIGITAL-supplied driver as a model.)

To assist you in generating proper code for your user-written driver
and to provide a stable user-level interface from one release of the
system to another, RSX-llM-PLUS provides the macro calls listed in
Table 4-1.
The definitions of the system macro calls for drivers are in the
Execut ve assembly prefix file RSXMC.MAC. The following subsections
describe the format of the macro calls and other features of
user-written driver code.
Driver code details
(such as labeling
requir.~ments and entry point conditions) are presented in Section 4.5.

4.3.1

Generate Driver Dispatch Table Macro Call - DDT$

The DDT$ macro call facilitates generation of the driver
table. The format of the DDT$ macro call is as follows:
DDT$

dispatch

dev,nctrlr,iny,inx,ucbsv,NEW,OPT,BUF

Table 4-2 lists the arguments of the DDT$ macro call.
The macro
constructs the DDT, using as addresses those locations indicated by
the standard labels. The macro has arguments allowing you to tailor
some of the standard entry points. The format of the DDT generated by
the DDT$ macro is described in Section 4.5.1.

4-4

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
Table 4-1
System Macro Calls for Driver Code
Macro Name

General Functions

DDT$

Used conventionally at the start of the driver code
(1)
to allocate storage for
and to generate a
driver dispatch table containing the addresses of
entry points in the order in which the Executive
expects them;
(2)
to generate special global
labels required by the Executive;
(3) to tell the
Executive LOAD routines:
(a) which controllers the
driver supports,
(b)
how many interrupt vectors
each controller supports, and (c)
the association
between
the
interrupt vectors and the driver
interrupt entry points;
and
(4)
to
generate
default controller and unit status change entry
point procedures
(for
on-line
and
off-line
transitions)

GTPKT$

Used at the I/O initiator entry point to generate
the call to the $GTPKT routine and to generate code
to save the address of the currently active unit's
UCB

INTSV$

Used at an interrupt entry point to conditionally
generate a call to the $INTSV routine and to
generate code to load the UCB address of the
interrupting device into R5
Table 4-2
DDT$ Macro Call Arguments
Meaning

Argument
dev

is the 2-character device mnemonic.

nctrlr

is the number of controllers that the driver
(counting from 1).

iny

allows the definition of no interrupt entry point or
multiple
interrupt entry points.
If you leave the
argument null, the macro generates as the
interrupt
entry point address the location defined by the
conventional label $xxINT.
If you specify NONE,
no
interrupt
generated for the controller.

entry

services

point

If you specify an argument list
of
the
form
<aaa,bbb, ••• >,
the macro generates multiple cells
containing addresses defined by unconventional
labels
of the form $xxaaa and $xxbbb.
This latter mechanism
allows you to define multiple interrupt entry points
in
the driver.
For example,
the argument list
<INP,OUT> generates two interrupt address labels of
the
form $xxINP and $xxOUT, the typical names used by
drivers with two interrupt entry points.
(continued on next page)

4-5

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
Table 4-2 (Cont.)
DDT$ Macro Call Arguments
Argunent

Meaning

in<

uses an alternate I/O initiation entry point address
label instead of the conventional xxINI form.
If you
specify inx, the macro uses as the only I/O initiation
entry point address the location defined by the label
xxinx.

UC)sV

is for compatibility with RSX-IIM drivers. If you are
writing a driver for RSX-IIM-PLUS, you should leave
this argument blank. As a result, the macro does not
allocate the space for the table of UCB addresses.
For guidelines on specifying this argument, refer to
Section 4.3.4.

NEH

distinguishes
between
RSX-IIM-PLUS
and
RSX-IIM
drivers.
If you specify this argument (any character
except null), the macro generates two cells to hold
the controller and unit status change entry point
addresses. The referenced driver entry points must be
labelled xxKRB:
and xxUCB:.
If your driver uses
these entry points, it cannot be compatible with
RSX-IIM unless the two routines are conditionalized.
If the argument is null, the macro generates code to
use the xxPWF entry point for controller and unit
on-line and off-line status changes.

opn

indicates that the driver supports seek optimization.
The referenced entry point must be labelled xxCHK:.
The routine corresponding to that label should qualify
the I/O request and convert it to cylinder track and
sector.

Bur

required if the driver performs buffered input
output. The entry point xxDEA: is generated.

and

NOTE
RSX-IIM drivers implicitly handle controller
and unit on-line and off-line status changes
as power failures.
Although this default
operation (enabled by code generated from
leaving this argument null) is not optimal for
operation on RSX-IIM-PLUS, the driver will
probably function properly
without
being
changed to include the xxKRB and xxUCB entry
points.

4.3.2

G~t

Packet Macro Call - GTPKT$

The GTf'KT$ macro call standardizes use of the Executive $GTPKT
routine, which retrieves an I/O packet for the driver to process. The
format of the GTPKT$ macro call is as follows:
G'I PKT$

dev,nctrlr,addr,ucbsv,suc

The deEcription of the arguments appears in Table 4-3.
4-6

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
Table 4-3
GTPKT$ Macro Call Arguments
Meaning

Argument
dev

is the 2-character device mnemonic.

nctrlr

is the number of controllers that the driver
(counting from 1).

addr

is the local label defining the location at which to
continue
execution
if
there is no I/O packet
available.
A driver typically executes a RETURN
instruction when the $GTPKT routine indicates that
there is no I/O packet to process.
If you leave this
argument null, therefore, the macro generates a RETURN
instruction.

ucbsv

is for compatibility with RSX-IIM drivers.
If you are
writing a driver for RSX-IIM-PLUS, you should leave
this argument nUll.
The macro then generates code to
load the pointer S.OWN with the address of the UCB
returned by $GTPKT.
For guidelines on using the
argument, refer to Section 4.3.4.

suc

indicates single unit controller.
If you are writing
a driver for RSX-IIM-PLUS that supports a controller
type such as the LPll, to which only a single unit can
be attached, you should specify this argument (any
character(s)
except null).
If you specify
this
argument,
you
should
ensure
that
the offset
K.OWN/S.OWN in the KRB(s) of your driver data base
points to the UCB(s)
of the unit(s) to which the
controller(s) is attached.
Thus, the macro does not
generate code that stores the UCB address in the KRB
(a gratuitous operation) for a device that has only
one UCB per KRB.

services

If your RSX-IIM-PLUS driver has
multiple
units
attached to the same controller, you should leave this
argument nUll.
The macro therefore generates code to
store in the KRB the UCB address of the unit to
process.
This macro call generates the call to the Executive $GTPKT routine.
You should place it at the I/O initiation (xxINI) entry point because
the $GTPKT routine is the standard manner for a driver to receive work
from the Executive.
When the driver receives control at its xxINI
entry point, the Executive has loaded RS with the address of the UCB
of the unit that the driver must service.
Because of the code the
macro call generates, the driver immediately calls $GTPKT, which can
set the C bit to
indicate that no work is pending.
The call
additionally generates the BCS instruction that returns control to the
calling routine when there is no work.
If you specify an address as
an argument in the macro call, it is used as the destination of the
BCS
instruction.
The address is typically that of a
RETURN
instruction, but does not have to be.
Eventually the driver must
execute a RETURN to the system.
The $GTPKT routine indicates that
process by clearing the C bit.

~he

driver has an I/O packet to
Therefore, when the test of the Bes

4-7

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
instruction is false, execution continues inline and the driver can
process the I/O packet that the Executive queued to it. The $GTPKT
routine leaves information in the driver registers to enable the
driver to process the request. Refer to the description of the $GTPKT
routine in Chapter 7.

4.3.3

Interrupt Save Macro Call - INTSV$

You should specify the INTSV$ macro call at each interrupt entry point
in the driver.
The macro conditionally generates a call to the
Executive $INTSV routine based on whether the driver is loadable. The
format of the INTSV$ macro call is as follows:
INTSV$

dev,pri,nctrlr,pswsv,ucbsv

The arJuments of the call are described in Table 4-4. If the symbol
LD$xx (where xx is the device mnemonic) is not defined, the macro
generates the call to $INTSV and defines the priority at which the
interrupt service routine will run. Not defining LD$xx indicates that
the driver is resident.
(For loadable drivers, the interrupt service
routine in the Executive dispatches the interrupt.) For both loadable
and resident drivers, however, the macro generates the code to load R5
upon a~ interrupt.
Table 4-4
INTSVS Macro Call Arguments
Argument

Meaning
is the 2-character device mnemonic.

pri

is the processor priority (PR4, PR5 or PR6) at which
the device runs and at which the $INTSV coroutine will
run.

nctrlr

is the number of controllers that the driver
(counting from 1).

services

is for compatibility with RSX-I1M drivers. If you are
writing an RSX-1IM-PLUS driver, leave this argument
nUll.
If your driver is an RSX-I1M driver, this
argument has no effect.
ucbsv

4.3.4

is for compatibility with RSX-1IM drivers. If you are
writing a driver for RSX-IIM-PLUS, you should leave
this argument nUll. The macro generates code which
uses the controller index returned in R4 by $INTSV,
calculates the KRB of the interrupting controller, and
loads the UCB address of the interrupting unit into
R5. For guidelines on specifying this argument, refer
to Section 4.3.4.

Usage of UCBSV Argument in Macro Calls

The DD~$, GTPKT$, and INTSV$ macro calls allow you to specify an
argument (ucbsv)
that maintains compatibility with RSX-IIM drivers.
RSX-llH-PLUS does not need to utilize the ucbsv argument.
The
argument ucbsv in the DDT$ macro allocates nctrlr words of storage
(one word for each controller that the driver supports) and labels the

4-8

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
first word ucbsv:.
This storage is the CNTBL area used by RSX-IIM
drivers to contain the address of the unit control block of the
interrupting devices for each controller.
Both the GTPKT$ and
INTSV$
macro calls may use this same area.
For more information concerning
CNTBL, consult the RSX-IIM Guide to Writing an I/O Driver.
If you specify the argument ucbsv in the GTPKT$ macro call, it must be
the same label that you supplied for the ucbsv argument in the DDT$
and INTSV$ macro calls.
The macro generates code to move the UCB
address returned by $GTPKT to the correct location in the table
starting at the label ucbsv.
If you specify the argument ucbsv in the INTSV$ macro call, it should
be thE~ same label you supplied for the ucbsv argument in the DDT$ and
GTPKT$ macro calls.
The macro uses ucbsv to locate the UCB address of
the
interrupting unit,
and then generates code to load the address
into RS.

4.3.5

Specifying a Loadable Driver

To spec=ify that a driver is loadable and to enable generation of
conditional code,
you must define the symbol LD$xx.
The definition
can appear in either the driver source code or the assembly prefix
file RSXMC.MAC.
It is usually more convenient to define the symbol in
the driver source code because you probably will not have cause to
edit RSXMC.MAC. When the symbol is defined, the INTSV$ macro does not
generate the call to $INTSV.

4.3.6

Loadable Driver Entry Points for LOAD and UNLOAD

A loadable driver
that requires additional
initialization
and
completion functions can define two entry points by labels of the form
$xxLOA and $xxUNL (where xx
is the
2-character device mnemonic).
BeCaUSE! these two labels do not appear in the DDT itself, their format
is fixed;
you must use the exact format in your driver code.
When
you load
the driver,
the LOAD routines check for the $xxLOA entry
point.
NOTE
The
LOAD routines can perform
this
function only from MCR.
If you attempt
to load a driver
that has the $xxLOA
entry point from VMR, the load operation
is terminated with the error message
DRIVER
REQUIRES
RUNNING SYSTEM FOR
LOAD/UNLOAD.
The driver is entered, once per UCB, at the $xxLOA entry point at
priority zero.
At this stage, the driver data base has been loaded
and pointers have been relocated.
The driver is mapped through APR 5,
and the following registers are set up:
R3
Controller index (undefined if S.KRB
R4 - Address of the status control block
R5 - Address of the unit control block

The driver may use all the registers. When you unload the driver, the
UNLOAD routine calls it at the $xxUNL entry point with the same
conditions.
4-9

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
These wo entry points in the loadable driver are independent of the
contro ler and unit status change entry points used by Executive
reconf guration software. That is, the two entry points $xxLOA and
$xxUNL are used for initialization and completion at LOAD and UNLOAD
time and not at on-line and off-line status change time.

4.4

DHIVER DATA STRUCTURE DETAILS

The fo~lowing elements in the I/O data structure are of concern to the
prograPlmer writing a driver:
1.

The I/O packet

The DCB

The UCB

The SCB

The KRB

The CTB

The I/O data structure, and the control blocks listed previously in
particular, contain an abundance of data pertaining to input/output
operations. Drivers themselves are involved with only a subset of the
data.
NOTE
Except where explicitly noted otherwise,
all unused bits, fields, and words in
all driver data base structures are
reserved for DIGITAL system use and
expansion.
In the following descriptions, most data fields (words or bytes)
are
classified by one of five descriptions. Two items in each description
indicate:
•

Whether the field is initialized in the data-structure source,
and

•

What sort of
execution

access

the

driver

has

the

field

during

The five descriptions are:
<initialized, not referenced>
This field is supplied in the data-structure source code, and
is not referenced by the driver during execution.
<initialized, read-only>
This field is supplied in the data-structure source code, and
may be read by the driver.
<not initialized, read-only>
Either an agent other than the driver establishes this field,
or the driver sets it up once and thereafter references it
read-only.

4-10

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
<not initialized, read-write>
Either the driver or some other agent establishes this field,
and the driver may read it or write over it.
<not initialized, not referenced>
This field does not involve the driver in any way.
These five descriptions cover most of the fields in the control blocks
described
in this section. No system software or hardware checks or
enforces any of the access described.
Exceptions are noted in the
text.

4.4.1

The I/O Packet

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

Link to next 1/0 packet

LLNK

}

LPRI
LEFN

EFN

PRI

I.TCB

TCB address of requester

I.LN2

Address of second LUT word

I.UCB

Address of redirect UCB

Modifier

Virtual address of 1/0 status block

Relocation bias of 10SB

Real address of 10SB

Virtual address of AST service routine

I.FCN

Function code

1.I0SB

I.AST
I.PRM

Device
parameters

I.AADA

Attachment Descriptor Pointer

I.AADA+2

Attachment Descriptor Pointer
ZK-254-81

Figure 4-1:

I/O Packet Format
4-11

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
QIO directive processing dynamically builds the I/O packet from the
data in the DPB. Fields in the I/O Packet (see the following text)
are c13ssified as:
•

Not referenced,

•

Read-only, or

•

Read-write.

I. LNI{

D-::iver access:
Not referenced.
D,~ sc r i pt ion:

Links I/O Packets queued for a driver.
A
chain. The listhead is in the SCB (S.LHD).

zero

ends

the

QIO

directive

I.EFN
D:::- i ver access:
Not referenced.
D(~sc

r i pt ion:
Contains the event flag number as copied
processing from the requester's DPB.

I.PRI
Driver access:
Not referenced.
Df~scription:

Priority copied from the TCB of the requesting task.
I.TCB
Dl- i ver access:
Not referenced usually.
and power failure.

Sometimes referenced at

I/O

cancel

Df~ S c rip t ion:

TCB address of the requesting task.
I. LN2

Dr- i ver access:
Not referenced.
Description:
Contains the address of the second word of the LUT entry in
the task header to which the I/O request is directed. For
open files on file-structured devices, this word contains the
address of the Window Block; otherwise, it is zero.

4-12

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
I.UCB
Driver access:
Not referenced by conventional driver;
by full duplex drivers.

frequently referenced

Description:
Contains the address of the unit to which I/O is to be
directed.
I.UCB is the address of the Redirect UCB if the
starting UCB has been subject to an MCR Redirect command.
The field is referenced by the $GTPKT routine.
I.FCN
Driver access:
Read-only.
Description:
Contains the function code for the I/O request.
It consists
of two bytes.
The high-order byte contains the function
code; the low-order byte contains modifier bits.
During
predriver initiation the Executive compares the function code
with a function mask value in the DCB. The driver interprets
the modifier bits.
I.IOSB
Driver access:
Not referenced.
Description:
I.IOSB contains the virtual address of the I/O Status Block
(IOSB), if one is specified, or zero if one is not specified.
I.IOSB+2 and I.IOSB+4 contain the address doubleword for
the
IOSB
(see Section 7.2 for a detailed description of the
address doubleword).
The first word contains the relocation
bias of the IOSB;
the bias is, in effect, the number of the
32-word block in which the IOSB starts.
The second word is formatted as follows:
Bits a through 5
Bits 6 through 12
Bits 13 through 15

Displacement in block
All zeros
6

(DIB)

The displacement in block is the offset from the block base.
The value 6 in bits 13 through 15 is constant.
It is used to
cause an address reference through Kernel Address Page
Register 6 (APR6).
Discussion of the address doubleword is deferred to Section
7.3 because you seldom have to be concerned with its contents
or format in writing a conventional driver.
Its construction
and subsequent manipulation are normally external to the
driver.
Subroutines are provided as Executive services for
programmed I/O to render the manipulations of I/O transfers
transparent to the driver itself.

4-13

PROGRAMMING SPECIFICS FOR W~ITING AN I/O DRIVER
l.AST
D::-iver access:
Not referenced.
Dr~ sc r i pt ion:

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
Dl' i ver access:
Read-write.
DE'SC r i pt ion:
Device-dependent parameters constructed from the last six
words of the DPB.
Note that if the I/O function is a
transfer (refer to the description of D.MSK in Section
4.4.3),
the buffer address (first DPB device-dependent
parameter) is translated to an equivalent address doubleword.
Therefore, the virtual buffer address, which occupied one
word in the DPB, occupies two words in I.PRM. As a result,
all other parameters in I.PRM are shifted by one word so that
device-dependent parameter n is copied to I.PRM +(2*n)+2.
Most DIGITAL-supplied drivers treat these words
as
a
read/write storage area after their initial contents have
been used.
When the last word of the device-dependent parameters is
nonzero, the value can have one of several special meanings
to the Executive. For example, if the value is nonzero and
could be an Executive address, the Executive assumes that the
value is a block locking word. Therefore, if the driver uses
the word, it should restore its contents before calling
$IODON.
l.AADA
I. AADA+2

Driver access:
Not referenced;
the driver.

maintained by the Executive transparently to

De sc r i pt ion:
Two pointers, each to an attachment descriptor block of the
region in which the task I/O buffer resides. These pointers
account for I/O by region and enable the Executive to lock a
region to make it noncheckpointable while I/O is in progress,
and to unlock a region after I/O completes.

4.4.2

'rhe QIO Directive Parameter Slock (DPS)

The QIO DPB is constructed as shown in Figure 4-2.
Usually drivers
never ,lccess the DPB; the information is supplied here for general
reference.

4-14

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
The parameters in the DPB have ~he following meanings:
Length (required):
The length of the DPB, which for the RSX-IIM and RSX-IlM-PLUS QIO
directive is always fixed at 12 words.
DIC (required):
Directive Identification Code.
is 1.
Fo r QIOW it is 3.

For the QIO directive, this value

Q.IOFN (required):
The code of the requested I/O function (0 through 3l).

Length

ole

O.IOFN

Function code

Modifier

O.IOLU

Reserved

LUN

Q.IOPR/O.IOEF

Priority

EFN

0.IOS8

lID status block address

O.IOAE

AST address

O.IOPL +0

f---

+2
+4

----f---

+6
+10

+12

Devicedependent
parameters

I----

ZK-255-81

Figure 4-2:

QIO Directive Parameter Block (DPB)

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

must not be used.

Q. IOLU (requi red) :
Logical Unit Number.
Q.IOPR:
Request priority.
Ignored by RSX-llM-PLUS,
allocated for lAS compatibility.

4-15

but

space

must

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
Q.IOEF (optional):
Event flag number.

Zero indicates no event flag.

Q.IOSB (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

a
I/O status byte.

B~'te

1
Augmented data supplied by the driver.

Bytes 2 and 3
The contents of these bytes depend on the value of byte o.
If
byte a = 1,
then these bytes usually contain the
processed byte count.
If byte a does not equal 0, then the
contents are device-dependent.
Q.IOAE (optional):
kldress of the I/O done AST service routine.
Q.IOPL
Up to six parameters specific to the device and to
function
to
be
performed.
Typically,
for data
functions, the following four are used:
•

Buffer address

•

Byte count

•

Carriage control type

•

Logical block number

The fields for any optional parameters not specified
with zeros.

4.4.3

must

the
I/O
transfer

filled

The Device Control Block (DCB)

Figure 4-3 is a schematic layout of the DCB. The DCB describes the
static characteristics of a device controller and the units attached
to the controller. All fields must be specified.
The fiplds 1 in the DCB are described as follows:
D.LNK Ilink to next DCB)
Driver access:
Initialized, not referenced.

1. Parenthesized contents following the symbolic offset
value to be initialized in the database source code.

4-16

indicate

the

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
De sc r i pt i on:
Address link to the next DCB. If this cell is in the last
(or only) DCB, you should set its value to zero. If you are
incorporating more than one user-written driver at one time,
then this field should point to another DCB in a DCB chain,
which is terminated by a value of zero.
D.UCB (pointer to first UCB)
Driver access:
Initialized, not referenced.
D.LNK

Link to next DCB (O=last)

D.UCB

Link to first UCB

D.NAM

Generic device name (ASCII)

D.UNIT

Highest unit no.

Lowest unit no.

D.UCBL

Length of UCB

D.DSP

Address of driver dispatch table

D.MSK

Legal function mask bits 0 - 15.

Control function mask bits 0 - 15.

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

ACP function mask bits 0 - 15.

Legal function mask bits 16. - 31.

Control function mask bits 16. - 31.

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

ACP function mask bits 16. - 31.

Address of partition control block

D.PCB

ZK-256-81

Figure 4-3:

Device Control Block

De sc r i pt ion:
Address link to the U.DCB field of the first, and possibly
the only, unit control block associated with the DCB. For a
given DCB, all UCBs are in contiguous memory locations and
must all have the same length.
D.NAM (ASCII device name)
Driver access:
Initialized, not referenced.
De sc r i pt ion:
Generic device name in ASCII
mnemonically referenced.
4-17

which

device

units

are

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER

D.UNIT (unit number range)
Driver access:
Initialized, not referenced.
D?scription:
Unit number range for the device.
The low-order byte
contains
the lowest, unit number;
the high-order byte
contains the highest unit number. This range covers those
logical units available to the user for device assignment.
Typically, the lowest number is zero, and the highest is n-l,
where n is the number of device-units described by the DCB.
D.UCBL (UCB length)
Driver access:
Initialized, not referenced.
D? sc r i pt ion:
The unit control block can have any length to meet the needs
of the driver for variable storage. However, all UCBs for a
given DCB must have the same length.
The specified length
must include prefix words (such as U.LUIC and U.OWN), if
present.
D.DSP (driver dispatch table pointer)
Driver access:
Initialized, not referenced.
D,~

sc r i pt ion:
Address of the driver dispatch table, which is located within
the driver code.
(When the Executive wishes to enter the
driver at any of the 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.)
For a resident driver, your code references the symbol
$xxTBL, which is generated by the DDT$ macro to mark the
start of the driver dispatch table. For a loadable driver,
then, you should initialize this field to zero, which
indicates that the driver is not in memory.

D.MSK (driver-specific function masks)
Dl~ i ver

access:

Initialized, not referenced.
Dl~ sc r i pt ion:

Eight words, beginning at D.MSK, are critical 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 following description applies only to

4-18

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
nonfile-structured devices. l Four masks, with two words per
mask, are described by the bit configurations that you
establish for these words:
1.

Legal function mask

Control function mask

No-op function mask

ACP function mask

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

177477
70

177200
377

a
a
377

iLEGAL FUNCTION MASK CODES 0-15.
;CONTROL FUNCTION MASK CODES 0-15.
iNO-OP FUNCTION MASK CODES 0-15.
iACP FUNCTION MASK CODES 0-15.
;LEGAL FUNCTION MASK CODES 16.-31.
;CONTROL FUNCTION MASK CODES 16.-31 •
;NO-OP FUNCTION MASK CODES 16.-31 •
iACP FUNCTION MASK CODES 16.-31.

The Executive filters the
function
words sequentially as follows:

code

through

the

mask

Legal Function Mask:
Legal function values have the corresponding bit position in
this word set to 1.
Function codes that are not legal are
rejected by QIO directive processing, which returns IE.IFC in
the I/O status block, provided an IOSB address was specified.

1. Although no DIGITAL publication describes writing drivers for
file-structured devices
(drivers that interface with F11ACP), you
could write a disk driver by using a DIGITAL-supplied driver as a
template.
For example, the RKII driver (DKDRV) is one that does not
use advanced features.
4-19

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
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 to be a control
function.
Such a function allows QIO directive processing to
copy the DPB device-dependent data directly into the
I/O
Packet.
No-op 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 specifies neither a control
function nor a no-op,
then it specifies either an ACP
function or a transfer function.
If a function code requires
intervention of an Ancillary Control Processor (ACP), the
corresponding bit in the ACP function mask must be set.
ACP
function codes must have a value greater than 7.
In the specific case of read-write virtual
functions,
the
corresponding mask bits may be set at your option.
If the
corresponding mask bits for a read-write virtual function are
set, QIO directive processing recognizes that a file-oriented
function is being requested to a nonfile-structured device
and converts the request to a read-write logical function.
This conversion is
particularly
useful.
Consider
read-write virtual function to a specific device:

If the device is file-structured and a file
is open
on the specified LUN, the block number specified is
converted from a virtual block number in the file
to
a logical block number on the medium. Moreover, 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.

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

Transfer Function Processing:
Finally, if the function is not an ACP function, then it is
by default a transfer function.
All transfer functions cause
the QIO directive processor to check the specified buffer for
legality
(that is, inclusion within the address space of the
requesting task) and proper alignment
(word or byte).
In
addition,
the processor checks the number of bytes being
transferred for proper modulus (that is, nonzero and a proper
multiple).
By convention, the first user-supplied parameter
is the buffer address and the second is the byte count.

4-20

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
Creating Mask Words:
Creating function mask
steps:

words

involves

the

following

five

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

device

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

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

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

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

D.PCB (0)
Driver access:
Initialized, not referenced.

4-21

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
D(~sc r i pt ion:

Address of the driver's Partition Control Block
(PCB).
The
driver data base source code must initialize the address to
zero.
The DCB can be extended by adding words after D.PCB.
A PCB exists for every partition in a system.
describes the partition in which it resides.

driver

PCB

The Executive uses D.PCB together with D.DSP (the address of
the driver dispatch table) to determine whether a driver is
loadable or resident and,
if loadable,
whether
it
is
in
memory.
Zero and nonzero values for these two pointers have
the meanings shown in Figure 4-4.

D.DSP:

Loadable
driver,

Resident

not in

driver

D.peB:

memory

(not

ciO

possible)

Loadable
driver,
in memory

ZK·223-81

Figure 4-4:

D.PCB and D.DSP Bit Meanings

4.4.3.1
Establishing I/O Function Masks - Table 4-5
is supplied
to
assist you
in determining
the proper values to set in the function
masks.
The mask values are given
for
each
I/O function
used
by
DIGITAL-supplied drivers.
The bit number allows you to determine
which mask group to use:
for bits numbered a through 15, use the mask
value
for
a
word
in the first 4-word group;
for bits numbered 16
through 31, use the mask value for a word in the second 4-word group.
Of the function mask values listed
in Table 4-5,
only
IO.KIL
is
mandatory and has a
fixed
interpretation.
However, if IO.ATT and
IO.DET 3re used, they must have the standard meaning.
(Refer
to
the
RSX-IIM/M-PLUS
I/O Drivers Reference Manual
for
a description of
standarj I/O functions.) If
QIO directive processing encounters a
functio1 code of
3 or 4 and the code is not no-op, QIO assumes that
these c)des represent Attach Device and Detach Device,
respectively.
The ot~er codes are
suggested but not mandatory.
You are free to
establi3h all
other
function-code values
on
nonfile-structured
devices.
However,
the mask words must still
reflect the proper
filteri1g process.
If you lre writing a driver for a
file-structured
device,
establi3h the standard function mask values of Table 4-5.

you

must

To dete~mine the proper bit masks for disks, tapes,
and
unit
record
devices
(such as
terminals, card readers, line printers, paper tape
punches/readers), use Tables 4-6, 4-7 and 4-8 as guides.

4-22

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
Table 4-5
Mask Values for Standard I/O Functions
Bit

Mask
Value

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
29
30
31

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

Related
Symbolic

I/O
Function

IO.KIL
IO. WLB
I O. RLB
IO.ATT
IO.DET

Cancel I/O
Write Log ical Block
Read Logical Block
Attach Device
Detach Device
General Device Control
General Device Control
General Device Control
Diagnostics
Find File in Directory
Unlock Block
Remove 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
Extend File
Create File
Mark File for Delete
Read File Attributes
Write File Attributes
ACP Control
Unused
Unused
Unused
Unused
Unused
Unused
Unused

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

4-23

PROGRAMMING SPECIFIC] POR WRITING AN I/O DRIVER
Table 4-6
Mask Word Bit Settings for Disk Drives
RSX-llM-PLUS

0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

c
t
t
c
c
c

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

sa
sd
a
a
a
a
a
a
a

IO.CLN
Diagnostic
IO.FNA
IO.ULK
IO.RNA
IO.ENA
IO.ACR
IO.ACW
IO.ACE

a
a
a
a
a
a
a
a
a

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

16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
t
c
n
a
sa
sd

Related Symbolic

Bit

transfer function, bit set only in legal function mask
control function, bit set in legal and control function masks
no-op function, bit set in legal and no-op function masks
ACP function, bit set in legal and ACP function masks
special case, bit set only in ACP function mask, but not legal
special case, bit set only if diagnostic support in system and
driver

4-24

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
Table 4-7
Mask Word Bit Settings for Magnetic Tape Drives

t c n a sa sd -

Bit

RSX-llM-PLUS

Related Symbolic

0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

c
t
t
c
c
c
c
sa
sd
a

IO.CLN
Diagnostic
IO.FNA
IO.ULK
IO.RNA
IO.ENA
IO.ACR
IO.ACW
IO.ACE

IO.DAC

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

a
a
a

IO.RVB
IO.WVB
IO.EXT
IO.CRE
IO.DEL
IO.RAT
IO.WAT
10. APC

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

n
a

4-25

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
Table 4-8
Mask Word Bit Settings for Unit Record Devices
Bit

RSX-llM-PLUS

0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

c
t
t
c
c
c

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

sa
sd
a
a
a
a
a
a
a

IO. CLN
Diagnostic
IO.FNA
IO.ULK
IO.RNA
IO.ENA
IO.ACR
IO.ACW
IO.ACE

a
a
a
a
a
a
a
a
a

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

16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
t
c
n
a
sa
sd

Related Symbolic

4-26

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
4.4.4

The Unit Control Block CUCB)

Figure 4-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.
The fields 1 in the UCB are described below:
U.UAB (0)
Driver access:
Initialized, not referenced.
De sc r i pt ion:
For terminal UCBs only. It is required only if accounting
support is on the system (A$$CNT is defined) but may be
present if accounting support is not on the sy'stem.
This
value is used to access the user accounting block in
secondary pool.
U.MUP
Driver access:
Not initialized, not referenced.
De sc r i pt ion:
For terminal UCBs only. Bits 1 to 4 contain an index to a
table which contains the address of CLI Parser Block (CPB)
for the current CLI; the remaining bits are used for other
terminal specific features and are defined as follows:
UM.OVR
UM. CLI
UM.DSB
UM.NBR
UM.CNT
UM.CMO
UM.SER
UM.KIL

Override CLI indicator
CLI indicator
Terminal diabled because CLI eliminated.
No broadcast
Continuation of command line in progress
Command is in progress from this terminal
Terminal is in serial mode
TTDRV should tell MCR to flush all pieces of
a continued command if the user types CTRL/C.

U.LUIC
Driver access:
Not initialized, not referenced.
Desc r i pt ion:
For terminal UCBs only, and only in multiuser systems:
the
logon UIC of the user at the particular terminal. This
offset must exist for any device on a multiuser system for
which the DV.TTY bit is set. This word is altered by logging
into the system.

1. Parenthesized contents following the symbolic offset
value to be initialized in the data base source code.
4-27

indicate

the

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER

Driver access:
Initialized, not referenced.
De sc r i pt ion:
Only in multiuser systems: the UCB
terminal for allocated devices.

U.UAB 1

U.MUp1

U.LUIC 1

- - - -

User Account Block

- - - - -

Multiuser flags and CLI pointer

- - -

- - - - - -

Log on UIC

address

-,
~
~

10
6
-4

UOWN

Owning terminal UCB address

-2

U.DCB

Back pointer to DCB

U.RED

Redirect UCB pointer

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

}
}

Un it status

Control flags

Unit status

Physical unit no.

U.CW1

Characteristics word 1

U.CW2

Characteristics word 2

U.CW3

Characteristics word 3

U.CW4

Characteristics word 4

All
devices

U.sCB

Pointer to SCB

U.ATT

TCB address of attached task

U.BUF

Buffer relocation bias

U.BUF+2

Buffer address

Byte count

U.CNT

1------- U.UBx2

E r to the UCB

- -

--- --- -

~;~;~~~ in secondary ~ ::

storage
1. This offset appears only for terminal devices (th@t is. devices that have DV.TTY set)
in multiuser systems.
2. This offset appears only for those devices that have OV.MSD set.
ZK-257-81

Figure 4-5:

Unit Control Block

4-28

the

owning

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
U.DCB (pointer to associated DCB)
Driver access:
Initialized, not referenced.
Description:
This word is a pointer to the corresponding device control
block.
Because the UCB is a key control block in the I/O
data structure, access to other control blocks usually occurs
by means of links implanted in the UCB.
U.RED (pointer to start of this UCB (.-2))
Driver access:
Initialized, not referenced.
De sc r i pt ion:
Contains a pointer to the unit control block to which this
device-unit has been redirected.
This field is updated as
the result of an MCR Redirect command.
The redirect chain
ends when this word points to the beginning of the UCB itself
(U.DCB of the UCB, to be precise).
U.CTL (device-dependent values)
Driver access:
Initialized, not referenced.
De sc r i pt ion:
U.CTL and the function mask words in the device control block
control QlO directive processing.
Figure 4-6 shows the
layout of the unit control byte.
U.STS

U.CTL

} UC. LG H . Buffer size mask bits for transfer length
UC.KIL - Unconditional cancel I/O (l=yes)
UC.ATT - Attach/detach notification (1 =Ves)
UC.PWF - Unconditional call at powerfail (l=yes)
UC.QUE - Queue to driver bit (l=yes)
UC.NPR - NPR device bit (l=yes)
UC.ALG - Alignment (byte or word)( l=no)
ZK-258-81

Figure 4-6:

Unit Control Byte

The driver data base code statically establishes this bit
pattern.
Any inaccuracy in the bit setting of U.CTL produces
erroneous I/O processing.
Bit symbols and their meanings are
as follows:
UC.ALG - Alignment bit.

4-29

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
If this bit is 0, then byte alignment of data buffers is
allowed. If UC.ALG is 1, then buffers must be word-aligned.
UC.ATT - Attach/Detach notification.
If this bit is set, then the driver is called when $GTPKT
processes an Attach/Detach I/O function.
Typically, the
driver does not need to obtain control for Attach/Detach
requests, and the Executive performs the entire function
without any assistance from the driver.
UC.KIL - Unconditional Cancel I/O call bit.
If set, the driver is called on a Cancel I/O request, even if
the unit specified is not busy. Typically, the driver is
called on Cancel I/O only if an I/O operation is in progress.
In any case, the Executive flushes the I/O queue.
UC.QUE - Queue to-driver bit.
If set, the QIO directive processor calls the driver at its
I/O initiation entry point without queuing the I/O packet.
After the processor makes this call,
the
driver
is
responsible
for
the
disposition
of the I/O packet.
Typically, the processor queues an I/O Packet before calling
the driver, which later retrieves it by a call to $GTPKT.
The most common reason for a driver to examine a packet
before queuing is that the driver employs a special user
buffer, other than the normal buffer used in a transfer
request.
Within the context of the requesting task, the
driver must address-check and relocate such a special buffer.
See Section 8.3 for an example of a driver that does this.
On multiprocessor systems, certain restrictions apply to this
form of I/O processing.
No driver should process an I/O
packet received directly from the QIO processor without first
performing a conditional fork operation (that is, call
$CFORK) to guarantee execution on the correct processor.
Unless the driver is running on the correct processor, it
must not process a packet that causes access to the device
registers.
The restriction does not apply if the driver
merely uses the current task context to map secondary I/O
buffers and then queues the I/O packet itself. In summary,
packets received directly from $DRQIO may not be processed
directly unless they cause no activity on the I/O page (and
thereby do not need to be executed on a particular processor)
or unless an intervening call to $CFORK has been performed.
UC.PWF - Unconditional calIon power failure bit.
If set and the unit is on-line, 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. See the discussion in
Sections 4.3.6 and 4.5 of the entry points in the DDT for
LOAD and UNLOAD and for controller and unit status change.
UC.NPR - NPR device bit.
If set, the device is an NPR device. This bit determines the
format of the 2-word address in U.BUF (details given in the
discussion of U.BUF below) •

4-30

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
UC.LGH - Buffer size mask bits (two bits).
These two bits are used to check whether the byte count
specified in an I/O request is a legal buffer modulus. You
select one of the values below by ORing into the byte a 0, 1,
2, or 3.
00 01 10 11 -

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

UC.ALG and UC.LGH are independent settings.
NOTE
UC.ATT, UC.KIL, UC.QUE, and UC.PWF are usually zero,
especially for conventional drivers. Every driver,
however, must be concerned with its particulat values
for UC.ALG, UC.NPR, and UC.LGH.
The driver is
totally responsible for the values in these bits, and
erroneous values are likely to produce unpredictable
resul ts.
U.STS (0)
Driver access:
Initialized, not referenced.
De sc r i pt ion:
This byte contains device-independent status information.
Refer to the UCBDF$ macro definition in Appendix A. Figure
4-7 shows the layout of the unit status byte.
U.CTL

U.STS

8 17

l I I I I I I I I
~

I Unused bits are reserved
for system use and expansion .
US.MDM· Marked for dismount (l=yes)
US.FOR - Mounted as foreign volume (O=yes)
US.MNT - Volume is mounted (l=no)
US.BSY - Device-unit busy (l=yes)
ZK-259-81

Figure 4-7:

Unit Status Byte

US.MDM, US.MNT, and US. FOR apply only to mountable devices. l

1. If your user-written driver services a mountable device,
Section 4.5.9 for information on volume valid processing.
4-31

refer

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER

The bit meanings are as follows:
US.BSY
If set, device-unit is busy.
US.fI.1NT
If set, volume is not mounted.
US. FOR
If set, volume is mounted foreign.
US.fI.1DM
If set, device is marked for dismount.
U.UNIT (unit number)
Driver access:
Initialized, read-only.
De sc r i pt ion:
This byte contains the physical unit
number
of
the
device-unit serviced by this UCB.
If the controller for the
device supports only a single unit, the unit number is always
ze ro.
NOTE
This is the physical unit number of the device and
not the logical unit number.
The range of this
number is from zero to n where n is device-dependent.
The logical designation DBO: does not necessarily
imply a zero in this byte.
U.ST2 (US.OFL)
Driver access:
Initialized, not referenced.
De sc r ipt ion:
This byte contains additional device-independent
status
information.
Different parts of the system set and clear
these bits. The layout of the unit status extension byte is
shown in Figure 4-8.
U.ST2

U.UNIT

o
Unused bits are reserved
for system use and expansion.
US.OFL - Unit offline (1=yes)
US.RED - Unit redirectable (1=no)
US.PUB - Unit is public device (1=no)
US.UMD - Unit attached for diagnostic s (1=yes)
US.PDF - Privileged diagnostic
functions only (1=yes)
ZK-260-81

Figure 4-8:

Unit Status Extension 2
4-32

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
The bit meanings are as follows:
US.OFL=l
If set,
the device
is off-line
(that
is, not
in
configuration).
This bit should be initialized to 1.

the

US.RED=2
If set, the device cannot be redirected.
US.PUB=4
If set, the device is a public device.
US.UMD=lO
If set, the device is attached for diagnostics.
US.PDF=20
If set, this unit can be used
function only.
U.CWI

for

privileged

diagnostic

(device-specific characteristics)
Driver access:
Initialized, not referenced.
Description:
The
first of a 4-word continuous
cluster
of
device
characteristics
information.
U.CWI - and
U.CW4
are
device-independent,
whereas
U.CW2
and
U.CW3
are
device-dependent.
The
four
characteristics words are
retrieved from the UCB and placed in the
requester's buffer
on issuance of a Get LUN information
(GLUN$) Executive
directive.
It is your responsibility to supply the contents
of these four words in the assembly source code of the data
structure.
U.CWI is defined as follows.
(If a bit is set to
corresponding characteristic is true for the device.)

the

DV.REC=l
Record-oriented device
DV.CCL=2
Carriage-control device
DV.TTY=4
Terminal device.
If DV.TTY is set,
then the UCB contains
extra cells (for U.LUIC, U.CLI, and optionally U.UAB).
DV.DIR=lO
Directory device
DV.SDI=20
Single directory device

4-33

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
DV.SQD=40
Sequential device
DV.MSD=IOO
Mass Storage device
DV.UMD=200
Device supports user-mode diagnostics
DV.EXT=400
Unit is on an extended 22-bit controller
DV.SWL=lOOO
Unit is software write-locked
DV.ISP=2000
Input spooled device
DV.OSP=4000
Output spooled device
DV.PSE=IOOOO
Pseudo device.
If this bit is set, the UCB does
past the U.CWI offset.

not

extend

DV.COM=20000
Device mountable as a communications channel
DV.FII=40000
Device mountable as a FILES-II device
DV.MNT=IOOOOO
Device mountable l
U.CW2 (device-specific characteristics)
Jriver access:
Initialized, read-write.
)e sc r i pt ion:
Specific to a given device
storage or constants).2

driver

(available

for

1. If your user-written driver services a mountable device,
Sec t i () n 4. 5. 9 for i n for mat ion 0 n vol urn e val i d pro c e s sin g •

working

refer

2. An exception is that, for block-structured devices, U.CW2 and U.CW3
may not be used for working storage. In drivers for block-structured
devices (disks and DECtape), these two words must be initialized to a
doublt~-precision
number giving the total number of blocks on the
device. Place the high-order bits in the low-order byte of U.CW2 and
the low-order bits in U.CW3.
4-34

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
U.CW3 (device-specific characteristics)
Driver access:
Initialized, read-write.
De sc r i pt ion:
Specific to a given device
storage or constants).l

driver

(available

for

working

U.CW4 (device-specific characteristics)
Driver access:
Initialized, read-only.
Description:
Default buffer size in bytes. This word is changed by a
system command (SET with the !BUF keyword). The value in
this word effects FCS, RMS, and many utility programs.
U.SCB (SCB pointer)
Driver access:
Initialized, read-only.
De sc r i pt ion:
This field contains a pointer to the status control block for
this UCB.
In general, R4 contains the value in this word
when the driver is entered by way of the driver dispatch
table, because service routines frequently reference the SCB.
U.ATT (0)
Driver access:
Initialized, not referenced.
De sc r i pt ion:
If a task has attached itself to the device-unit, this
contains its task control block address.

field

U.BUF (reserve two words of storage)
Driver access:
Not initialized, read-write.

1. An exception is that, for block-structured devices, U.CW2 and U.CW3
may not be used for working storage. In drivers for block-structured
devices (disks and DECtape) , these two words must be initialized to a
double-precision number giving the total number of blocks on the
devicE!. Place the high-order bits in the low-order byte of U.CW2 and
the low-order bits in U.CW3.

4-35

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
Dp s c rip t ion:
U.BUF labels two consecutive words that
serve
as
a
communication region between $GTPKT and the driver.
If a
then U.BUF,
nontransfer function is indicated
(in D.MSK),
U.BUF+2,
and U.CNT receive the first 3 parameter words from
the I/O Packet.
For transfer operations, the
initial
format of
words depends on the setting of UC.NPR in U.CTL.
does not format
the words;
all
formatting
is
before the driver receives control.
The format is
by the UC.NPR bit, which is set for an NPR device
for a program-transfer device.

these two
The driver
completed
determined
and
reset

The format for program-transfer devices is identical to that
for
the second two words of I.IOSB in the I/O Packet.
See
Section 4.4.1 for a description of I.IOSB in the I/O packet.
In general, the driver does not manipulate these words when
performing
I/O to
a program-transfer device.
Instead, it
uses the Executive routines Get Byte, Get Word, Put Byte, and
Put Word to effect data transfers between the device and the
user's buffer.
For NPR device drivers, these two words represent what the
driver
uses to
initiate the transfer operation.
For both
UNIBUS and MASSBUS NPR devices, word 2 contains the low-order
16 bits of the physical address.
For a UNIBUS NPR device,
bits 4 and 5 in word 1 are memory extension bits;
for
a
MASSBUS NPR device (the KS.MBC bit is set), bits 0 through 5
are the memory extension bits.
It
is
the
driver's
responsibility to set the function code, interrupt enable,
and go bits.
This action must be accomplished by a
Bit Set
(BIS) operation so that the extension bits are not disturbed.
The driver must move these words into the device control
registers to initiate the I/O operation.
For a typical UNIBUS NPR device driver, the word layout is as
follows:
Word 1
Bit 0
Bits 1,2,3
Bits
4,5
Bits 6
Bits 7 through 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 through 15

Low-order 16 bits of physical address

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 Section 7.2.

4-36

the

Address

Doubleword

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
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 uses this field in constructing the actual device
request.
U.BUF and U.CNT keep track of the current data
item in the
buffer for
the current transfer (except for NPR transfers) •
Because this field is being altered dynamically,
the
I/O
Packet may be needed to
reissue an I/O operation (for
instance, after a powerfail or error retry).
U.UCBX
Driver access:
Not initialized, not referenced
Description:
This field contains
secondary pool
for
(DV.MSD=I) •

a pointer to the UCB extension in
mass storage devices with DV.MSD set,

For information on formatting, see
UCBDF$ macro.

the

description

the

U.PRM (Device-dependent words)
Driver access:
Not initialized, read-write.
Description:
The driver establishes this variable-length block of words to
suit device-specific requirements.
For example, a disk
driver uses the first words to store the disk geometry as
follows:
.BLKB
.BLKB
.BLKW

I
I
I

i# OF SECTORS PER TRACK
i# OF TRACKS PER CYLINDER
i# OF CYLINDERS PER VOLUME

The driver can call the $CVLBN routine (described in Chapter
7)
to convert a logical block number to a disk address based
on the values in U.PRM and U.PRM+2.

4.4.5

The Status Control Block (SCB)

The SCB contains the context for a
Figure 4-9 is a layout of the SCB.
unit operation and describes the status of a unit that can run in
parallel with all other units.

4-37

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER

S.LHD

Input/Output
Queue Listhead

Fork UNIBUS Run Mask

Fork Link Word

Fork PC

Fork R5

Fork R4

S.KS5

Driver/Fork KISAR5

S.PKT

I/O Packet Address

S.FRK

S.CTM/S.ITM

Initial Time·Out Count

Current Time·Out Count

S.STS/S.ST3

Status Extension

Status

S.ST2

Status Extension

S.KRB

KRB Address

S.ROFF 2/S.RCNT 2

~ffset ~ D~ce ~egisterlNumbe~f Byte~o Copyl

Error Message Block Pointer

r
r

KRB Address 0

KRB Address 1

..J

,
J

•

r
r

•
KRB Address n

-i
J

If the symbols below are defined at system generation time,
the related cells marked with a number appear in the structure.
I Multiprocessor support (M$$PRO)

2 Appears only if driver supports error logging

3 'f the system has multiaccess device support (M$$ACD)
and the driver is multiaccess (S2.MAD)

Figure 4-9:

Status Control Block

The fi~ldsl in the SCB are described as follows:

Par~nthesized

value

contents following the symbolic offset
be initialized in the data base source code.

4-38

indicate

the

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
S.LHD (first word equals zero; second word points to first)
Driver access:
Initialized, not referenced.
De sc r i pt ion:
Two words forming the I/O queue listhead.
The first word
points to the first I/O Packet in the queue, and the second
word points to the last I/O Packet in the queue.
If the
queue is empty, the first word is zero, and the second word
points to the first word.
S.URM (controller UNIBUS run mask)
Driver access:
Initialized, not referenced.
DE~sc r i pt ion:

This word appears only in a multiprocessor system (that is,
M$$PRO is defined).
It contains a UNIBUS run mask that
defines the UNIBUS run to which the currently assigned
controller is attached. When controller assignment is made,
this cell is set from K.URM. For the purposes of running a
driver on the correct processor, S.URM is used exclusively
and independently of the value of S.KRB or K.URM.
If S.KRB
is not equal to zero, and if S.URM is not equal to K.URM (an
unusual situation), then the driver must properly handle the
fact that it will run on a different processor from the one
its currently assigned KRB would normally warrant.
It is
possible that the processor on which the driver will run has
the CSRs at a different location from that stored in the
current KRB. ADJACENCY WITH THE FORK BLOCK IS ASSUMED!
S.FRK (reserve four words of storage)
Driver access:
Initialize words to zero, not referenced.
DE~sc r i pt ion:

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. The Fork
processor also depends on the adjacency of S.URM and S.KS5 if
the required support is generated into the system.
S. KS 5 (0)
Driver access:
Initialized, not referenced.

4-39

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
Df ~ S c rip t ion :
This word contains the contents of KISAR5 necessary to
correctly alter the Executive mapping to reach the driver for
this unit.
It has no meaning for a driver that is not
loadable.
It is set by LOAD, and whenever a fork block is
dequeued and executed, this word is unconditiona~ly jammed
into KISAR5. ADJACENCY WITH THE FORK BLOCK IS ASSUMED!
S.PKT :reserve one word of storage)
DJ"iver access:
Not initialized, read-only.
D( ~ S c r i pt ion:
Address of the current I/O Packet established by $GTPKT. The
Executive uses this field to retrieve the I/O Packet address
upon the completion of an I/O request. S.PKT is not modified
after the packet is completed.
S. CTM : 0)
DJ- i ve r access:
Not initialized, read-write.
Dt~ sc r i pt ion:

RSX-IIM-PLUS 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 typically initialized by moving S.ITM (initial
timeout count) into S.CTM. The Executive clock service
(in
module TDSCH) examines active times, decrements them, and, if
they reach zero, calls 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 precise because the internal
clocking mechanism is operating asynchronously with driver
execution. The minimum meaningful clock interval is 2 if you
intend to treat timeout as a consistently detectable error
condition.
If the count is zero, then no timeout occurs; a
zero value is, in fact, an indication that timeout is not
operative.
The maximum count is 250.
The driver is
responsible for setting this field.
Resetting occurs at
actual timeout or within $FORK and $IODON.
S.ITM : ini t ial timeout count)
D;-iver access:
Initialized, read-only.
D(~scription:

Contains the initial timeout value that the driver
into S.CTM to begin device timeout.

4-40

can

load

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
S.STS (0)
Driver access:
Initialized, not referenced.
DE~sc r i pt ion:

Establishes the controller as busy/not busy
(nonzero/zero).
This byte is the interlock mechanism for marking a driver as
busy for a specific controller. The byte is tested and set
by $GTPKT and reset by $IODON.
S.ST3 (driver-specific status byte)
Driver access:
Initialized, referenced by driver for synchronization.
DE~ sc r i pt ion:

This status byte is reserved for driver-specific status bits
concerning driver-executive or driver-driver communication.
Figure 4-10 shows the layout of this byte.

S.ST3

(S.STS)

8 I

l 1I I I I I I 1
4

S3.DR l- Multiaccess drive in released state
S3.NRl- Driver should not release drive
S3.SIP - Seek in progress on drive
S3.ATN - Driver must clear attention bit
S3.SlV - Device uses slave units
S3.SPA - Port' A' spinning up
S3.SPB - Port 'B' spinning up
S3.0PT - Seek optimization enabled (1

yes)

ZK-262-81

Figure 4-10:

Controller Status Extension 3

The following are the descriptions for the currently defined
bits.
All currently defined bits are used by mass storage
devices.
S3. DRL=l
If this bit is set, the drive is in the released state.
Drivers that support dual-access (dual-port) operation set
this bit after completion of the release command by the
drive.
The Executive routines Request Controller for Control
Function ($RQCNC) and Request Controller for Data Transfer
($RQCND)
test this bit to decide whether the drive is in a
released state and whether the Executive should attempt load
balancing by switching ports.

4-41

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
S3.NRL=2
If this bit is set, a driver does not
release
the drive.
This bit exists solely for DIGITAL to maintain the device and
to debug
the driver.
Drivers that support dual-access
(dual-port)
operation examine this bit and, if it is set, do
not issue the release command to the drive and do not set the
S3.DRL bit.
If this bit is set, reconfiguration dual-port
activity (that is, port on-line and off-line operations) will
not function properly.
S3.SIP=4
If this bit is set, the drive has a
seek
in progress.
A
driver that supports overlapped seek operations examines this
bit to keep track of whether the drive
is seeking.
For a
driver
that does not support overlapped operations but does
support error logging (that is, cassette and magtape),
this
bit is set to
indicate that a positioning operation is in
progress.
S3.ATN=lO
This bit is used only by MASSBUS devices.
The
Executive
common interrupt module DVINT checks this bit;
if it is set,
then the driver must clear the attention bit in the Attention
Summary Register.
If this bit is not set, DVINT itself
clears the attention bit in the Attention Summary Register.
S3.SLV=20
If this bit is set,
the device connects to slave units.
Certain devices,
such as magnetic tape controllers attached
to a MASSBUS controller, can in turn have units attached
to
them.
These units are referred to as slave units.
Thus, if
this bit is set, the SCB describes a tape controller to which
slave units can be attached.
S3.SPA=40
If this bit is set, port A on this unit is spinning up.
S3.SPB=lOO
If this bit is set, port B on this unit is spinning up.
S3.0PT=200
If this bit is set, seek optimization is enabled
for
this
device.
$GTPKT
uses
this
bit to determine whether
optimization is to be used.
An MCR SET command can set and
clear this bit.
If you select seek optimization support for
a Digital-supplied device during
system generation,
SYSGEN
sets this bit in that device SCB when it creates the fevice
data base structures.
S.ST2

(~ontroller

status extension)

Driver access:
Initialized.
De3cription:
This status word defines certain status conditions for
the
controll~r-unit combination.
Figure 4-11 shows the layout of
this word.
4-42

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
S.ST2

15
All unused bits are reserved
for system use and expansion.
S2.EIP - Error in progress (1 = yes)
S2.ENB - Error logging enabled (0 = yes)
S2. LOG - Error logging supported (1 = yes)
S2.MAD· Multiaccess device (1 = yes)
S2.LDS - Load sharing enabled (1 yes)
S2.0PT - Device supports seek optimization (1 yes)
S2.CON - Contiguous KRB/SCB allocation (1 yes)
S2.0Pl - Indicates the type of optimization used
S2.0P2 - Indicates the type of optimization used
S2.ACT - Driver has operation (1/0) active (1 yes)
ZK-263-81

Figure 4-11:

Controller Status Extension 2

DIGITAL has attempted to restrict bits in this word to those
defining system-wide status.
Specific bits for driver and
Executive synchronization or driver internal synchronization
are allocated from S.ST3.
The following are the descriptions
for the currently defined bits:
S2.EIP=1
This bit is reserved for DIGITAL error logging routines.
S2.ENB=2
This bit is reserved for DIGITAL error logging routines.
S2.LOG=4
This bit is reserved for DIGITAL error logging routines.
S2.MAD=lO
This bit indicates the presence of the table of KRB addresses
at the end of the Status Control Block.
If this bit is set,
the device is a multiaccess device and the SCB has a KRB
table containing pointers to
the KRBs of the controllers
capable of accessing the device.
S2.LDS=40
This bit enables and disables load sharing
for dual-access
devices.
If this bit is set, the Executive may dynamically
switch ports and therefore alter controller assignment when
establishing an access path for a driver.
If this bit is not
enabled, the Executive does not alter the current controller
assignment.
This
feature
permits
static
controller
assignment, perhaps for diagnostic operations.
Devices (such as terminals) with S2.LDS clear
that explicitly manage controller assignment.

have

drivers

S2.0PT=lOO
If this bit is set, this device supports queue optimization.
This bit,
used by $DRQRQ,
determines whether to call the
block check and convert the LBN routine in the driver.

4-43

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
S2.CON=200
This bit indicates the continuous
allocation
of
the
controller request and status control blocks. Devices that
do not support overlapped operation do not require a separate
seB for each unit. The KRB and SCB for such devices can be
contiguous and some fields in the SCB overlap those in the
KRB.
Therefore, the SCB offsets S.CSR, S.PRI, S.VCT, and
S.CON are valid only for such devices.
For these devices,
S2.CON is set.
For the layout of
Section 4.4.7.

the

contiguous

KRB

and

SCB,

refer

S2.0Pl=400
S2.0P2=1000
These bits indicate the type of optimization selected for
this device.
An MCR command can set and clear these bits.
These two bits give you three options of queue optimization.
They are as follows:
S2.0P2,S2.0Pl
S2.0P2,S2.0Pl
S2.0P2,S2.0Pl
S2.0P2,S2.0Pl =

0,0
0,1
1,0
1,1

Nearest cylinder
Elevator
CSCAN
Reserved

S2.ACT=2000
If this bit is set, the driver has active I/O.
S.KRB (pointer to currently assigned KRB)
Driver access:
Initialized, referenced by driver to access the KRB.
D~scription:

This word points to the currently assigned controller request
block.
For non-multiaccess devices, it is set during system
generation and never altered.
For multiaccess devices with
load-sharing enabled, it may take on the value of one of the
KRB pointers in the KRB table, S.KTB.
If this word has a
value of zero, then the device has no currently assigned KRB.
It may, in fact, not have a KRB or CTB at all. Both the null
driver and virtual terminal driver have no KRR.
Certain restrictions apply to drivers whose data bases do not
include KRBs.
They will
receive powerfail, timeout, and
cancel calls like any other driver, but the priority will
always be zero,
and the CSR address and controller index
(where supplied) will be undefined.
NOTE
All code that checks S.KRB for a KRB pointer must
check for a possible zero value and take appropriate
action. A zero value in S.KRB does not necessarily
mean that a KRB does not exist, but perhaps rather
that one is not currently assigned. A device which
has no KRB will not have S2.CON set.

4-44

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
The first cell in the KRB (K.CSR) contains the control and
status register (CSR) address for the controller.
The offset
K.CSR will always be zero so that the pointer
(S.KRB)
will
always connect directly to
the cell containing the CSR
address.
S.ROFF

This byte is reserved for devices that support DIGITAL error
logging software.
This value is an offset from S.CSR/K.CSR
to indicate the start of the device registers.
It
is
typically zero.

S.RCNT

This byte is reserved for devices that support DIGITAL error
logging software.
It represents the minimum number of words
of I/O page registers that this device has.

S.EMB

This word is reserved for devices that support DIGITAL
logging software.

error

S.KTB (KRB addresses)
Driver access:
Initialized, not referenced.
Description:
This table appears only if the system has multiaccess device
support
(M$$ACD is defined)
and the device is multiaccess
(the S2.MAD bit set).
Every controller to which the unit (unit control block and
status
control
block
combination)
can communicate is
represented in this table by a controller request block
address.
The table contains at least two entries, with the
list terminated by a zero word.
For devices with executive
load sharing supported (S2.LDS set), bit zero of each word is
an on-line and off-line flag which, when set, indicates that
KRB is off-line with respect to this SCB and should not be
considered for controller assignment.
Devices with S2.LDS
clear
have
drivers
that explicitly manage controller
assignment.
Only the driver may change S.KRB, and it mayor
may not use the low-order bit of the KRB addresses in S.KRB
as an on-line and off-line flag.
When drivers explicitly
manage controller assignment, system software (other than the
driver) must not modify S.KRB and must tolerate a
1 in the
low-order bit of the values in S.KTB.

4.4.6

The Controller Request Block (KRB)

Figure 4-12 is a layout of the controller
request block.
One KRB
exists for
each controller.
If a controller allows only a single
operation on a single unit at a time, then the driver can allocate the
controller request block and the status control block in continuous
space. With such continuous allocation, all offsets commonly used by
the dri.ver are referenced by their S.xxx forms.
The system will still
use the offset S.KRB and the K.xxx forms for all references.
Refer to
Section 4.4.7 for the continuous SCB/KRB allocation.

4-45

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER

- - - 1

Driver dependent storage

K.PRM
K.VCT 5 / K.PRI

K.IOC/K.CON 5

Vector/4

Priority

- 6

Controller I/O count

Controller index

K.STS

Controller status

K.CSR 5

Control and status register address

K.OFF

Offset to UCB table

K.HPU

Unused

K.OWN

Owner (UCB address of unit owned)

K.CRQI

Controller request queue listhead

K.URM 1,2

Highest physical unit

Controller UNIBUS run mask

•

•
•
3

22-bit
Working
Storage
Area

KE.RH B

11/70 UMR/RHBAE offset

UCB address physical unit 0

Start of UCB table

•
•
•
4

UCB address physical unit n

-1

Ilf cont guous allocation of KRB and SCB is used (that is, if S2.CON is set), this field overlaps the I/O request queue.
2 Thisfif Id is for multiprocessor support (M$$PRO is defined).
3 This ar'~a is for 11/70 extended memory support (M$$EXT is defined).
The arf a extends in a negative direction from the start of the UCB Table.
4 If KS.l CB is set, then this table appears (allows overlapped function interrupts).
5 The S.).xx forms of these offsets are valid only for devices that perform a single operation on a
control:er at a time. For such devices, S2.CON is set and the SCB and KRB are allocated in a contiguous area.
See Figjre 4-7 for the contiguous SCB/KRB structure.
ZK-264-81

Figure 4-12:
The fields l

Controller Request Block

in the KRB are described as follows:

1. Parenthesized comments following the symbolic offset
value t~ be initialized in the data base source code.
4-46

indicate

the

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
K.PRM (device-dependent storage)
Driver access:
Initialized, read-write.
Description:
LOAD does not relocate any addresses in this area.
K.PRI

(device priority)
Driver access:
Initialized, read-only.
Description:
Contains the priority at which the device
interrupts.
Use
symbolic values
(for example, PR4) to initialize this field
in the driver data source code.
These symbolic values are
defined by issuing the WNDDF$ macro (refer to the sample data
base in Chapter 8 and to the listing of the HWDDF$ macro) •

K.VCT (interrupt vector divided by 4)
Driver access:
Initialized, not referenced.
Description:
Interrupt vector address divided by 4.
Because you can use
the CON task to change the vector value, you need not be
overly concerned with
initializing K.VCT to
the correct
value.
If K.VCT equals zero, then neither LOAD nor UNLOAD
takes any vector action.
In particular, LOAD does not create
any interrupt control block linkage for this KRB.
K.CON (controller number times 2)
Driver access:
Initialized, read-only.
Description:
Controller number multiplied by 2.
Drivers that support more
than one controller use this field.
A driver may use K.CON
to index into a controller table created in the driver data
base source code and maintained
internally by the driver
itself.
By indexing the controller
table,
the driver can
service the correct controller when a device interrupts.
Because this number is an index into the table of addresses
in the CTB,
its maximum value is limited by the value of
L.NUM in that CTB.

4-47

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
K.IOC (0)
D:~ iver

access:

Initialized, not referenced.
DI~sc r i pt ion:

This is an I/O count used by the system to keep track of how
busy the controller is.
The value is related to the number
of outstanding requests queued for this controller.
This is
a weighted number to be used only by the system to judge the
relative activity of one controller with respect to another.
K.STS (controller-specific status)
Dr'iver access:
Initialized, not referenced.
Df~ sc r i pt ion:

This word
is used as a
status word that concerns the
controller.
Figure 4-13 shows the layout of the controller
status word.
K.STS

(1 = yes)
Unused bits are reserved
for system use and expansion.
KS.OFL - Controller offline
KS.MOF - Controller marked for offline
KS.UOP - Supports overlapped operation
KS.MBC· Device is a 22-bit MASSBUS controller
KS.SDX - Seeks allowed during data transfers
KS.POE - Parallel operation enabled
KS.UCB· UCB table present
KS.D IP - Data transfer in progress
KS.PDF . Privileged diagnostic functions only
KS.EXT - Extended 22-bit UNIBUS controller
KS.SLO - Controller is slow coming online
ZK-265-81

Figure 4-13:

Controller Status Word

All
undefined bits are reserved
Currently defined bits are:

for

use

DIGITAL.

KS.OFL=l
The Executive reconfiguration routines set this bit to place
the controller off-line and clear the bit to place the
controller on-line.
The bit is used
in conjunction with
KS.PDF to denote transition states.
If a request is made to
assign a unit to the controller and this KS.OFL is set
(and
no other on-line controller is found), the request terminates
with the IE.OFL error and a return is made to the driver
I/O
initiation entry point to get a new packet.
The driver data code should initialize this bit to 1.

4-48

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
KS.MOF=2
If this bit is set, the unit/controller is in the process
becoming offline.

KS.UOP=4
This bit indicates whether the controller supports unit
operation in parallel and requires synchronization.
If this
bit is set, each unit attached to the controller
is capable
of operating
independently.
Therefore, the KRB contains a
UCB table holding the UCB addresses of each independent unit.
KS.MBC=IO
If this bit is set, the device is a 22-bit MASSBUS controller
and does not use UNIBUS mapping registers (UMRs) but has 2
extra registers to describe a
22-bit address.
If these
registers exist,
the offset to the first of them (RHBAE) is
in the cell KE.RHB.
These registers can be found
by using
the contents of KE.RHB in conjunction with the contents of
S.RCNT.
The Executive on-line reconfiguration code calls the
common interrupt controller status change routine (in the
module DVINT) which dynamically sets or clears this bit
during controller processing.
KS.SDX=20
If this bit is set, the controller allows seek operations to
be
initiated while a data transfer is in progress.
(Some
types of disks, such as the RK06 and RK07, support overlapped
seek operations but do not allow a seek to be initiated if a
data transfer is in progress.) The Executive routines Request
Controller
for
Control
Function
($RQCNC)
and Request
Controller for Data Transfer ($RQCND)
examine this bit to
distinguish between the two types of controllers that support
overlapped seeks.
KS.POE=40
If this bit is set, the driver may initiate an I/O operation
on the controller in parallel with other I/O operations.
A
driver that supports overlapped seek operations checks this
bit to decide whether
it should attempt to perform an I/O
operation as a seek phase and
then a data transfer phase
(that
is,
overlapped)
or as an
implied seek
(that is,
nonoverlapped).
If this bit is set,
the driver can then
attempt the overlapped operation.
An overlapped driver must check this bit once only for each
I/O operation.
Because this bit can be reset by system
commands at any time, the driver must not rely on the bit
value to decide whether, upon being interrupted, the driver
was attempting a seek operation.
The driver must use the
S2.SIP bit to hold its internal state.
KS.UCB=IOO
This bit indicates the presence of the table of unit control
block addresses associated with the KRB.
If this bit is set,
K.OFF gives the offset from the beginning of the KRB to the
start of the UCB table.

4-49

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER

Devices that support unit operation in parallel (for example,
overlapped seeks) require a mechanism for finding the UCB of
the unit generating an interrupt. Therefore,
if KS.UOP is
set, a UCB table must exist.
If KS.UOP is not set, however,
a UCB table may still exist because some devices
(for
example, terminal multiplexers) support full unit operation
in parallel but do not require synchronization.
Therefore,
KS.UCB may be used to determine whether the UCB table exists,
regardless of whether KS.UOP is set.
KS.DIP;::200
If this bit is set, a data transfer is in progress. A driver
that supports overlapped'seek operation sets or clears this
bit to
indicate to
itself and to the Executive common
interrupt module DVINT whether, after an interrupt, a data
transfer is in progress. The driver must set or clear this
bit.
Usage of this bit eliminates the need for the software
to access the device registers to determine what type of
operation was in progress.
KS.PDF=400
This bit and one KS.OFL bit indicate the reconfiguration
status of the controller.
The Executive reconfiguration
software accesses both bits to describe the
off-line,
on-line, and transition status of the controller.
KS.EXT=lOOO
If this bit is set, the device is a 22-bit UNIBUS controller
and does not use UNIBUS mapping registers but has 2 extra
registers to describe a 22-bit address.
If these registers
exist, the offset to the first of them (BAE) is in the cell
KE.RHB.
These registers can be found by using the contents
of KE.RHG in conjunction with the contents of S.RCNT.
KS.SLO=2000
If this bit is
extended time
If this bit
online/offline
K.CSR

(~ontroller

set, the controller requires the use of the
out feature of the reconfiguration subroutine.
is not set, a controller will transition
immediately.

status register address)

Driver access:
Initialized, read-only.
De ~c r i pt ion:
Contains the address of the Control and Status Register (CSR)
for
the device controller.
Because you can use the CON task
to change the CSR value, you need not be overly concerned
with initializing K.CSR to the correct value. The driver
uses K.CSR to initiate I/O operations and to access, by
indexing, other registers that are related to the device and
are located in the I/O page. This address need not be the
CSR;
it need only be a member of the device'S register set.
The Executive reconfiguration software probes K.CSR to bring
a controller on-line.
(If probing K.CSR yields a nonexistent
memory trap, the controller will not be brought on-line.)

4-50

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
NOTE
This word is guaranteed to be offset
zero
for
the
KRB.
This assignment means that an RSX-IIM-PLUS
driver can access the CSR by the reference @S.KRB and
need not use a separate register.
K.OFF (offset in bytes (from K.CSR)

to start of UCB table)

Driver access:
Initialized, referenced by interrupt dispatch code.
Description:
This word contains the offset to the beginning of the
unit
control
block
table.
When added to the starting address of
the KRB, it yields the UCB table address.
The UNIBUS mapping
register work area extends in a negative direction from the
start of the UCB table.
The status bit KS.UCB may be used to determine whether
the
UCB table exists.
A UCB table may exist if KS.UOP is not
set, since some devices (for example, terminal multiplexers)
support
full
unit
operation
in
parallel
with
no
synchronization reguirect.
If KS.UOP is set, a UCB table must
appear (and KS.UCB will also be set).
K.HPU (highest physical unit number)
Driver access:
Initialized.
Description:
This byte contains the value of
number used on this controller.

the

highest

physical

unit

K.OWN (O)
Driver access:
Initialized, referenced for actual unit.
Description:
This word has three slightly different uses, depending on the
particular device.
1.

For controllers which always have only a
single unit
connected
to
them
(for
example,
the
line printer),
K.OWN/S.OWN always points to the UCB of that
unit.
You
can
use
the
suc
argument
in
the GTPKT$ macro
to
statically initialize this cell in the data base.

For controllers that may have multiple units attached but
do
not
support unit operation in parallel (for example,
the RK05), K.OWN/S.OWN is set with the currently active
unit by code generated with the GTPKT$ macro suc argument
set to blank.

4-51

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
3.

For controllers that support unit operation
in parallel
and
require synchronization
(KS.UOP is set), this is a
busy/nonbusy interlock for
the controller.
If
the
controller
is busy for
a data
transfer,
this word
contains the UCB address of the currently active unit.
This is true for RH disks such as the RP06.
This word is
set and cleared by the Request Controller
for
Control
Access
($RQCNC),
Request Controller
for
Data Access
($RQCND), and Release Controller ($RLCN) routines.

K.CRQ (first word equals 0;

second word points to first)

Driver access:
Initialized, not referenced.
DE sc r i pt ion:
Two words that form the controller wait queue.
Fork blocks
are queued here
for driver
processes that have requested
controller access.
Driver processes that request access
for
control
functions are queued on the front of the list, and
those that request access for data transfer are queued on the
end of the list.
K.URM (controller UNIBUS run mask)
Driver access:
Initialized, not referenced.
DE'sc r i pt ion:
This word appears only in a multiprocessor system
M$$PRO is defined) •

(that

is,

It contains a UNIBUS run mask that defines the UNIBUS run
to
which the controller is attached.
When controller assignment
is made, the cell is moved into S.URM for
the
fork block
there.
This word should not be zero.
Table of UCB addresses (offset from K.CSR by K.OFF bytes)
Driver access:
Initialized, referenced by interrupt dispatch code.
DE S c rip t ion:
This table contains the unit control block addresses for
the
units on this controller.
Physical unit zero is in the first
word, unit one is in the second word, and unit n is
in word
n+l.
The table has a length of (K.HPU(R?)+I) words.
A value
of zero in this table indicates a physical
unit number
for
which
no
actual
physical
unit exists.
The table
is
terminated by a -1.
NOTE
This table exists only for those
KS.UCB set.

4-52

devices

that

haVe

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
KE.RHB (reserve appropriate amount of storage)
The UNIBUS mapping register work area extends in a negative
direction from the start of the unit control block table.
This work area always appears if the device is an NPR device.
For devices with either KS.MBC or KS.EXT set, the first word
is used as the BAE offset for the controller.
This word
value is the offset that, when added to the CSR address
contained in K.CSR, yields the address of the BAE register on
the controller.
If both KS.MBC and KS.EXT are clear, the
device controller uses UMRs.

4.4.7

Continuous Allocation of the SCB and KRB

In a configuration where a controller and the Executive supports only
a single operation on a unit at one time, the driver can allocate
space for the KRB and the SCB in a continuous area.
Some fields of
the KRB overlap those in the SCB. Although the KRB and SCB in this
arrangement are contiguous, the system still considers the I/O data
structure to contain a KRB.
The system will still use the S.KRB
offset and the K.xxx forms for all references.
The driver can
reference the fields by the S.xxx form of the symbolic offset
definitions. In such a case, although the physical offsets may differ
between RSX-llM and RSX-llM-PLUS systems, correct referencing of many
locations on both systems is eased. Figure 4-14 shows the physical
layout of the continuous KRB and SCB allocation.

4.4.8

Controller Table (CTB)

Figure 4-15 is a layout of the controller table. You ensure that the
CTB is linked into the system list of controller tables by placing the
CTB macro immediately before the allocation of the L.LNK word.
The
CTB macro generates a global symbol that links the user-written CTB
into the system list.

4-53

PROG~AMMING

SCB
Offsets

SPECIFICS FOR WRITING AN I/O DRIVER

KRB
Offsets

r--

K.PRM

- 1

Driver·dependent storage

S.VCT/S.PRI

K.VCT/K.PRI

Vector/4

Priority

-6

S.CON

K.IOC/K:CON

Controller I/O Count

Controller index

-4

S.CSR

K.STS

Controller status

K.CSR

Pointer to CSR

K.OFF

......

Highest physical unit

K.OWN

Owner UCB

S.LHD

K.CRQ

Input/output queue Iisthead

S.URMI

K.URMI

4
6

S.FRK

-- - - - - - - - - - -

S.KS5

KISAR5

S.PKT

I/O packet address

Fork URM

Fork Link
Fork PC
Fork R5
Fork R4

S.CTM/S.ITM

Initial Time-Out Count

Current Time-Out Count

S.STS/S.ST3

Status Extension

Status

S.ST2

Status extension

S.KRB

KRB address

•
•
•
22-bit
Working
Storage
Area
KE.RHB
Start of UCB table

o
2

Offset to UCB table
Unused

K.HPU

-2

11170 UMR/RHBAE offset

UCB address physical unit 0

•
•
•
UCB address physical unit n
·1

IThis field is for multiprocessor support (M$$PRO is defined).
ZK266·81

Figure 4-14:

Continuous KRB/SCB Allocation

4-54

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER

r----

L.CLK

8-word
Clock
Block

Link to first ICB

-2

L.LNK1

Link to next CTB

L.NAM

Generic controller name

L.DCB 2

DCB address

L.ICB

L.STS/L. NUM

Controller status

L.KRB3

TNumber of KRB addresses

K R B address 0

6
10

K RB address n

1 The head of the list of controller tables is $CTLST in SYSCM.
21f LS.CIN is set, this cell points to the common interrupt
address table rather than to the DCB.
3 See Table 4-10 for label XXCTB.

ZK-267-81

Figure 4-15:

Controller Table

The fields l in the CTB are described below:
L.CLK
Dr· i ver access:
Initialized
De·sc r i pt ion:
This is the clock queue entry for these devices that
single clock block per generic controller type.
appears if LS.CLK is set.

need a
It only

L.rCB (reserve one word of storage)
Driver access:
Not initialized, not referenced.

1. Parenthesized contents following the symbolic offset
value to be initialized in the data base source code.
4-55

indicate

the

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
DE S c rip t ion:
This word points to the first
interrupt control block for
this type of controller.
It is a link and not an address.
In any system the ICBs must be in an executable pool area.
In an
I
and D space multiprocessor system, they must be
distinct for each processor, since each processor has its own
local executable pool mapped by KISARO.
Since the linkage
must enter and leave other than the usual
Executive kernel
mapping, the upper 4 bits encode a processor number which may
be used to enter $K6TAB,
and the lower 12 bits form an
address that has been shifted right once.
On other than an I
and D space multiprocessor system, the upper
four bits are
considered part of the address, which has still been shifted
right once.
L.LNK (0 or link to next CTB in list)
Driver access:
Not initialized, not referenced.
Dp sc r i pt ion:
All of the controller tables in the system are linked
together so they can be found, and they are threaded through
this first word.
A zero link terminates this list.
A CTB must exist for every physical controller
system.
L.NAM

~2-character

type

the

ASCII device name)

Driver access:
Initialized, read-only.
Dpsc r i pt ion:
This 2-character ASCII string is the controller mnemonic used
to
find
this controller table from among all the others in
the system.
For the RHll/70 controller, it is RH instead of
DB, DS, DR, or MM.
L.NAM must be unique throughout the system, unlike
the device control block.
L.DCB

D.NAM

:DCB address or address of common interrupt table)
Driver access:
Initialized, not referenced.
De sc r i pt ion:
The DCB pointer is used to reach the device control block,
and thereby the unit control block and driver dispatch table
for a driver.
If LS.CIN is set, L.DCB is a pointer to a
block that holds the common interrupt address (the address of
the interrupt dispatch routine in the Executive), and the DCB
addresses
(the addresses of the DCBs for the devices that
this controller interfaces).
This block is called the common
interrupt table and is shown in Figure 4-16.

4-56

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
CLCSR

Controller CSR Test Entry

CLKRB

Controller Status Change Entry

CLPWF

Powerfail Entry
Common Interrupt Address

DCB a

DCB n

n+2
n+4

a
- 1

1 If LS.CIN is set, l.DCB in CTB points to this structure
instead of to the DCB.
ZK·268-81

Figure 4-16:

Common Interrupt Table and Table of DCB Addresses

The powerfail entry at offset CI.PWF and the controller
status change entry at offset CI.KRB are addresses of
routines built into the Executive and are used instead of the
entries in a particular driver dispatch table. This allows
devices that have no DCB (for example, the interprocessor
interrupt
and
sanity
timer)
to still participate in
reconfiguration.
At offset CI.KRB is the address of a routine built into the
Executive for multidriver controllers such as the RH type.
This routine should set or clear the KS.MBC bit to indicate
whether the device is connected to an RHll or an RH70. The
driver checks the KS.MBC bit to determine which addressing
format to use. If the value at CI.CSR is zero, the Executive
on-line routines check the existence of a device attached to
this controller by probing the address at K.CSR. If the
value is nonzero, it is the address of a routine built into
the Executive to check device presence. Instead of probing
the address at K.CSR, the Executive on-line code calls this
routine, which returns either with the C bit clear if the
device is present or with the C bit set if the device is not
present.
The common interrupt table may have only the common interrupt
address in those cases in which a DCB does not exist (for
example, the lIST). If LS.MDC is clear, then only one DCB
address exists.
(The zero termination is still necessary.)
If LS.MDC is set, then more than one DCB address is possible;
therefore,
space should be left for all possible DCB
addresses (for LOAD) and the table terminated by a zero,
followed by a -1. Empty entries in this case are indicated
by a zero word. LOAD will then enter the DCB addresses into
the table when it loads data structures for drivers.

4-57

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
L.NUM Inumber of KRB addresses)
Dr iver access:
Initialized, read only.
DE S c rip t ion:
Used by programs that scan the controller tables to compute
the number of KRB addresses. This value is never zero, since
without controller request blocks there should
be
no
controller table.
The maximum value for L.NUM depends on the type of device and
on whether the driver is loadable. For common interrupt
dev ices, the val ue must be 1 ess than I 7 (dec imal) •
Fo r
resident drivers and drivers loaded by MCR LOAD, the value
must be less than 17 (decimal). For drivers loaded by VMR
LOAD, the value must be less than 17 (decimal) if the data
base is loadable and less than 129 (decimal) if the data base
is resident.
L.STS (generic controller status)
Driver access:
Initialized, read only.
De s c rip t ion:
The controller table status bits give information about the
class of controllers. Figure 4-17 shows the layout of this
byte.
l.STS

L.NUM

yes)

Unused bits are reserved
for system use and expansion.
LS.CLK - Clock block allocated
LS.MDC - Multidriver controller
LS.CBL - Clock block linked into clock queue
LS.CIN - Controller uses common interrupt address table
LS.NET - DECnet device
lK-269-81

Figure 4-17:

Controller Table Status Byte

The following are the descriptions of these bits:
LS.CLK=l
If this bit is set, the controller table has an 8-word
block.

clock

LS.MDC=2
If this bit is set, multiple drivers service
to the associated controller.

units

attached

LS.CBL=4
If this bit is set, the clock block is linked into the
queue.
4-58

clock

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
LS.CIN=lO
If this bit is set, the driver is associated with a common
interrupt controller and must have exactly one interrupt
vector. The driver is therefore called at the D.VPWF entry
point only for unit power failure. The Executive uses the
CI.PWF entry point in the common interrupt entry table for
controller power failure recovery.
In addition, the cell
L.DCB does not point to the device control block but rather
to the common interrupt entry table in the Executive.
L.KRB (KRB addresses of controllers)
Driver access:
Initialized once for the controller, not referenced.
DE~ sc r i pt ion:

A list of the controller request block addresses ordered by
their respective system-wide controller numbers. This table
is indexed by the controller index retrieved from the PS word
immediately after an interrupt.
The table is of length
(L.NUM(R?)) words. While the interrupt routines will not
have to scan the list in a linear fashion, the only way to
find all the controller request blocks in the system includes
a linear scan of all the controller tables. The CTB is
static.
The address of the start of the KRB address list in the CTB
is the global symbol $xxCTB in the driver dispatch table,
controller
where xx are the characters comprising the
mnemonic. Because LOAD supplies this address in the DDT when
it loads the driver, a loadable driver should not specify
this address in the DDT.
NOTE
A KRB address of zero indicates a controller that was
specified during system generation with no attached
units.
No controller request block for such a
controller is generated.
Proper action for drivers to access their list of KRB
addresses is to retrieve the address of the start of the KRB
list in the CTB from the cell in the driver dispatch table
set up by LOAD (both VMR and MCR).

4.5

DRIVER CODE DETAILS

This section describes the specific requirements for driver code. The
driver code must contain a driver dispatch table which allows the
Executive to call the driver to perform discrete system functions.
If
the driver needs to access either system structures such as the
partition and task control blocks or structures within its own data
base, it should use the system-wide symbolic offsets rather than the
real offsets. Because the driver is built with the Executive library
EXELIB.OLB, the symbolic offsets are automatically defined for the
driver code. If you want to see the definitions of the symbols in

4-59

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER

your driver listing, place in your driver source code the related
macro name in a
.MCALL directive and invoke the macro.
(For your
convenience, the source code of the macro calls that define the
symbols of structures is in Appendix A.) The detailed descriptions of
the driver data base structures are in Section 4.4.

4.5.1

Driver Dispatch Table Format

The driver dispatch table associates the entry points that the
Executive expects to find in a device driver and the actual locations
of the routines in the driver code. The DDT also provides a link from
the driver code to the driver data base. Figure 4-18 shows the format
of the DDT. Section 4.3.1 describes the DDT$ macro call, which
automatically generates the DDT.
All de\ice drivers require a driver dispatch table somewhere in the
first
4K words of the driver code. Conventionally, the table is
locatec at the beginning of the code.
NOTE
If the length of a driver must exceed 4K
words
(20000 octal bytes), then your
driver must set up the mapping for the
second 4K words whenever it is entered;
and, of course, all entry points must be
in the first 4K words of the driver.
The dr:ver must define some labels that the Executive routines and the
INTSV$ macro call use to access the DDT. Table 4-10 lists these
labels which are automatically generated by the DDT$ macro call.
Becaus(> these labels do not appear in the DDT itself, their format is
fixed ilnd they must be specified in the format shown.
Table 4-9
Labels Required for the Driver Dispatch Table
Rf·qui red Format
$):xTBL: :

Meaning
Defines the start of the DDT.
You specify
this label in the D.DSP word of the DCB of
resident drivers to link the DCB to the
DDT.
For
loadable drivers, the LOAD
routines use this label to fill in D.DSP.
Defines the pointer to the table of KRB
addresses in the CTB of the controller for
device xx. Because a driver can support
different types of controllers, there may
be more than one of this form of label.
(The
DDT$
macro
supports
only
one
controller type.)

$ :<xTB E: :

Defines the end of the DDT for Executive
LOAD and UNLOAD routines that scan the DDT.

4-60

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER

D.VNXC, D.VCHK'

-4

DVDES'

-2
I/O Initiation Entry Point Address

D.VCAN

Cancel Entry Point Address

D.VTIM

Timeout Entry Point Address

D.VPWF

Powerfailure Entry Point Address

D.VKRB

Controller Status Change Entry Point Address

D.VUCB

Unit Status Change Entry Point Address

D.VINT

Generic Controller Name (ASCII) for xy

$xxTBL: : D.VINI

Interrupt Entry Point Address 0
~

··•

For Controller xy
~

Interrupt Entry Point Address n

Pointer to KRB table in CTB (for INTSV$) for xy controller

xy CTB:

Generic Controller Name (ASCII)
~

Interrupt Entry Point Address 0

·
·
·

For Controller wz

Interrupt Entry Point Address n

wzCTB:

Pointer to KRB Table in CTB (for INTSV$) for wz controller

o
o

$xxTBE::
1. These are optional advance driver features

ZK-270-81

Figure 4-18:

Driver Dispatch Table Format

At offsets D.VINI through D.VUCB in the DDT of your driver appear
labels defining the addresses of the entry points in the driver.
As a
standard procedure, you supply the labels described in Table 4-10 at
the entry points in the driver code.
The formats of the standard
labels that appear in the DDT are not fixed.
Because the Executive
expects to
find
the entry point addresses at fixed offsets from the
start of the DDT and the labels themselves appear in the DDT, you can
change their format
if you construct the DDT without using the DDT$
macro call.
(However, other labels that are required
in the driver
code but do not appear in the DDT have a certain, fixed format which
you must not change.
For reference, these fixed format labels are:
$:KxTBL: :
xxCTB:
$xxTBE: :
$:KxLOA: :
$:KxUNL: :

4-61

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
These fixed-format labels are described elsewhere
in this chapter.)
The [DT$ macro
uses the standard labels but allows you to alter the
format of some of them.
At offset D.VINT in the DDT is the name of the controller
type
that
the driver supports.
(The same name is in the CTB.) If the driver has
no controller (such as the virtual terminal driver VTDRV),
this word
is
zero.
The structure allows
the driver
to
support multiple
controller types.
(The terminal driver supports different controller
types.)
Although the
DDT$ macro supports only one controller type,
there is no restriction on the number of controller types that a
driver can support.
After
each controller name
follows
a
block of
interrupt entry
addres3es.
At
location D.VINT+2 begins the first interrupt address
block, each word of which defines an address to be
included
in a
vector for the driver.
A zero terminates the block and indicates that
there lre no more interrupt entry points for the controller.
There is
no res:riction on the number of vectors each controller may have.
For
a sing~e interrupt device, location D.VINT+2 (interrupt entry address
0) is ~he interrupt address.
Table 4-10
Standard Labels for Driver Entry Points
Labell

Entry Po int

xxINI:

I/O initiation

xxCAN:

Cancel I/O

xxCHK:

Block check and conversion

xxOUT:

Dev i ce t imeo ut

xxPWF:

Po we r fa i I u r e

xxKRB:

Controller status change

xxUCB:

Unit status change

$xxINT: :

Interrupt entry point

1. The characters xx are the 2-character mnemonic.
The EXEcutive reconfiguration software uses the following
rules when
it accesses the interrupt address block to calculate the vectors for a
controller.
To calculate the first
vector address,
reconfiguration
routines access the cell K.VCT (or S.VCT) in the controller request
block.
If K.VCT is not equal to zero, it is multiplied by 4.
The
result
is the vector address that will be loaded with the address
found in interrupt entry point O.
The next interrupt entry point
is
examined.
If it is zero, there are no more vectors or interrupt entry
points for the controller.
If it is even, the next vector address
is
the
previous one plus
4 and that vector address is loaded with the
entry PJint address just examined.
If an e'1try point value in the block is odd (bit
zero
is set),
bit
zero
is cleared and
the
resulting number is an offset to the next
vector 3ddress.
To compute the next vector address,
the offset
is

4-62

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
added to the last vector address The next interrupt entry point is
examined.
If
it is even,
then its value is loaded into the last
vector address computed.
If it is odd, the result is an offset that
is added to the vector address just computed and the next entry point
is examined.
The computation of vector addresses terminates when the
next entry point is zero.
The entries shown in Figure 4-19 can be used
interrupt vector addresses when K.VCT equals 300.

calculate

the

The vectors at 300 and 304 are loaded with addresses xxINl and xxIN2.
The odd value 7 yields the offset 6 that is added to the last vector
computed to attain 312.
The address xxIN3 in the next interrupt entry
point examined
is loaded
in the vector at 312.
A zero· word in the
block shows there are no more vectors or interrupt entry points.
Following the interrupt entry address block for a controller type is a
pointer to the KRB table in the CTB.
Its label is in the form xxCTB,
which is used by the INTSV$ macro.
This pointer connects .the driver
code to the driver data base and is the last entry in a block for a
specific controller.
A zero terminates the driver dispatch table.
The global label in
form $}(:xTBE marks the terminating word in the DDT.

D.VINT

the

XXIN1
XXIN2

7
XXIN3

a
0

XXCTB:

ZK-271-81

Figure 4-19:

4.5.2

Sample Interrupt Address Block in the DDT

I/O Initiation Entry Point

The offset D.VINI in the driver dispatch table contains the address of
this entry point.
A driver is called at this entry point at priority
o from the Executive routine $DRQRQ in the module DRQIO.
A driver
should call the Executive $GTPKT routine to get an I/O packet to
process.
This action dequeues an I/O request.
The following are the
register conventions when the Executive enters the driver.
R5

= address of the UCB of the unit for which the

Executive

has

queued an I/O packet
This entry condition pertains unless the driver wants to delay the
queuing operation.
Therefore,
if the queue-to-driver bit UC.QUE in

4-63

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
the unit status block offset U.CTL
register conventions.
R5
R4
Rl

set,

the

following

are

the

UCB address of unit for which a packet has been created
SCB address of the related unit
address of the I/O packet

You may find more information on and coding
requirements for
the
queue-to-driver operation in
the description of the UC.QUE bit in
Section 4.4.4 and an example of its use in Chapter 8.
The GTPKT$ macro call automatically generates the call to
the $GTPKT
routine and
the code to process the return from $GTPKT.
Upon return
from $~TPKT, the C bit indicates whether there is a packet to process.
C = I

If the C bit is set, the Executive found the controller
busy, could not dequeue a request, or had to call $FORK
to have the driver run on the correct processor.

If the C bit
is clear,
the Executive successfully
dequeued a
packet for the driver and placed it in the
device's input/output queue.

If a request was successfully dequeued, the following are the contents
of the registers:
R5
R4
R3
R2
RI

Address of unit control block
Address of status control block
Controller index
Physical unit number of device to process
Address of the I/O packet

If the C bit is set, the driver
returns control
to
the caller
(a
RETURN
instruction should be executed).
If the C bit is clear, the
generated code loads the location at offset K.OWN/S.OWN in the
continuous KRB/SCB with the UCB address of the unit to process.
The
driver may then process the request and activate the device.
All
registers are available to the driver.
The driver executes a RETURN
instruction to transfer control to the system.
On a multiprocessor system, before returning a packet to
the driver,
$GTPKT calls th~ conditional fork routine $CFORK to ensure that the
driver executes on the correct processor.
If the current processor is
the correct processor, $CFORK returns to SGTPKT, and $GTPKT dequeues
an I/O packet, queues it to the driver, and returns to the driver with
the C bit clear.
Should
the current processor not be the correct
processor, $CFORK will call $FORK which returns to the driver with the
C bit set.
This action causes the driver
to dismiss
itself.
Eventually the fork processor restarts the driver
executing on the
correct processor.

4.5.3

Cancel Entry Point

The offset D.VCAN in the driver dispatch table contains the address of
this entry point.
The Executive routine $IOKIL in the IOSUB module
calls the driver at this entry point at device priority.
When
the
Executive enters the driver,
the
following
register conventions
pertain:
R5
R4
R3
RI
RO

UCB address
SCB address
Controller index (undefined if S.KRB equals zero)
Address of TCB of current task
Address of active I/O packet
4-64

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
The usa<ge of this entry point is explained in Section 2.2.2.
All
registers are available to the driver.
The driver returns control to
the Executive by executing a RETURN instruction.

4.5.4

Device Timeout Entry Point

The offset D.VTIM in the driver dispatch table contains the address of
this entry point.
Routines in the Executive module TDSCH call the
driver at this entry point at device priority.
When the Executive
enters the driver, the entry conditions are as follows:
R5
R4
R3
R2
RO

UCB address
SCB address
Controller index (undefined if S.KRB equals zero)
Address of device CSR
I/O status code IE.DNR (Device Not Ready)

The usage of this entry point is explained in Section 2.2.3.
All
registers are available to the driver.
The driver returns control to
the Executive by executing a RETURN instruction.

4.5.5

Next Command Entry Point

Ths offset D.VNXC in the driver dispatch table is only applicable to
the terminal driver.
The offset D.VNXC contains the entry point
address of a routine within the terminal driver which is called from
the routine $SNCMD in the Executive module DRSUB.
This entry point is
entered when a task exits whose TI:
is set to serial mode.
The
driver then passes the next CLI command to the MCR dispatcher. When
the Executive enters the driver, the following
register conventions
pertain:
RO

4.5.6

= UCB address of the TI:

of the exiting task.

Queue Optimization Entry Point

The offset D.VCHK in the driver dispatch table contains the address of
this entry point.
The routine $DRQRQ in the Executive's module DRSUB
calls the driver at this entry point at priority zero.
When the
Executive enters the driver,
the
following
register conventions
pertain:
CO
R -)

UCB address
I/O packet address

If the I/O operation is a data transfer function,
the
I/O packet
contains the starting LBN for the I/O request.
The routine at this
entry point must verify the request is a data transfer function,
and
if it is, the routine must replace the starting LBN with the starting
cylinder, track, and sector number to perform queue optimization.
See
the routine DBCHK in the module DBDRV for an example of a driver that
supports queue optimization.

4-65

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
4.5.7

Deallocation Entry Point

The offset D.VDEB in the driver dispatch table contains the address of
this entry point.
This entry point is called at priority zero from
the rcutine $FINBF in the Executive module SYSXT after a buffered
I/O
request completes.
The driver is expected to deallocate its buffers
at this entry point.
When called,
the
registers are set
up as
follo~s:

RO = address of the first buffer
All re~isters are available to the driver.
The driver returns control
to the Executive by executing a RETURN instruction.

4.5_8

Power Failure Entry Point

The offset D.VPWF in the driver dispatch table contains the address of
this e1try point.
The routines in the Executive module POWER call the
driver at this entry point at priority 0 for both unit and controller
power
failures.
The Executive first calls the driver for controller
power failure with the C bit set.
The driver
is called
in this
fashio1 once for
each controller.
The following are the register
conven:ions:
C bit set (controller power failure)
R3
R)
The

dr~ver

CTB address
KRB address
may use all registers.

After -:he Executive has called the driver for all related controllers,
it ca Is the driver once for each unit power failure at priority 0
with the C bit clear.
The following are the register conventions:
C bit clear (unit power failure)
ueB address
SCB address
Controller index
For both controller and
unit power
failures,
the driver
returns
control to the calling routine by executing a RETURN instruction.
If the driver supports a common interrupt device (that is, the
LS.CIN
bit
ir the CTB is set), the driver is called at this entry point only
for unjt power failures.
For controller power failures, the Executive
calls the entry point at CI.PWF in the common interrupt entry table.
See the description of the offset L.DCB in Section 4.4.8.

4.5.9

Controller Status Change Entry Point

The offset D.VKRB in the driver dispatch table contains the address of
this entry point.
The Executive routine $KRBSC in the OLRSR module
calls the driver at this entry point at priority 0 to put a controller
on-line or to take a controller off-line.

4-66

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
NOTE
If the controller is a common interrupt
controller
(LS.CIN
is
set) ,
the
Executive does not call the driver at
this address
(if any) specified in the
DDT but at the address in the common
interrupt table labelled CI.KRB.
See
Section 4.4.8.
The C bit indicates whether the request is for off-line or on-line.
The following are the register conventions upon entry to the driver.

R3
R2
o (SP)
2 (SP)

CTB address for the controller
KRB address of controller changing status
Return address for completion
Return address for caller of the Executive routine

The C bit is set to indicate the requested status change as follows:
CIOn-line to off-line transition
C
0 Off-line to on-line transition
The status change byte $SCERR is preset as follows:
$SCERR = 1
The driver indicates the return status in the $SCERR byte as follows:
$SCERR

< 0

$SCERR

Operation is not successful and a negative value
in
$SCERR is the I/O error code.
Thus, a negative value
rejects the status change requested by the C bit.
Operation is successful.
The driver
status
change
requested.
Th i s i s
condition.

accepts the
the default

All registers are available to the driver.
The Executive does not
change the status of the controller until and unless the driver shows
successful completion of the on-line or off-line request.
The driver must return immediately by either of the following methods:
1.

The driver can indicate the return status immediately and can
return to
the
first
address on the stack in the normal
fashion.
If the driver accepts the status change, it merely
executes a RETURN instruction.
(The status change byte
$SCERR has been preset with 1.) If the driver
rejects the
status change,
it loads the
relevant I/O error code into
$SCERR and executes a RETURN instruction.
(The
I/O error
code symbolS are listed in an appendix of the IAS/RSX-ll I/O
Operations Reference Manual.)

The driver need not
indicate the status
immediately but
removes the first address from the stack, saves it, and
returns immediately to the second address.
The driver
then
has 60 seconds to perform its processing, to indicnte the
return status, and to
return to the first address.
The
driver can use the offset S.CTM in the status control block
to time out some operation (such as a protocol
rundown)
and
then accept or reject the operation by u~ing $SCERR.

4-67

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
If the driver does not return to the first address on the stack, the
system can be considered to be in an indeterminate state and possibly
corrupted. The driver must return immediately because status changes
should not stall the system. The 60-second delay allows a driver time
to overcome conditions over which it has little control
(such as
networL connections).
System disk and terminal drivers must indicate
return status immediately.
However, the terminal driver
(TTORV)
reject~; a controller on-line request for a 0211 multiplexer if some of
the st,:tus bits indicate that the device is not a 0211 or that it is
broken

4.5.10

Unit Status Change Entry Point

The of'"set D. VUCB in the driver dispatch table contains the address of
this f~ntry point.
The Executive routine $UCBSC in the OLRSR module
calls 1.he driver at this entry point at priority 0 to put a unit
on - 1 i n f ~ 0 r
t o t a k e a un ito f f -1 i n e • Th i sen try i s call e don c e for
each unit whose status changes.
The C bit indicates whether the
reques': is for on-line or off-line. The following are the register
conven:ions:

R;
Rl
Rl

O(SP
2(SP

Address of UCB or unit changing status
Address of SCB of unit
Controller index (undefined if S.KRB equals zero)
Return address for driver completion
Return address for caller of the Executive routine

The C hit is set to indicate the

r~quested

status change as follows:

CIOn-line to off-line transition
C
0 Off-line to on-line transition
The stltUS change byte $SCERR is preset as follows:
$:;CERR = I
The drLver indicates the return status in the $SCERR byte as follows:
$:;CERR

< 0

$;CERR

Ope ra tion is not successful and a negati ve val ue in
$SCERR is the I/O error code. Thus, a negative value
rejects the change requested by the C bit.
Operation is successful.
The driver
status
change
requested.
Th i s i s
condition.

accepts the
the default

All re'Jisters are available to the driver.
The driver must return
within 60 seconds. The Executive does not change the status of a unit
until lnd unless the driver shows successful completion of the on-line
or off-line request.
The drLver must return immediately by either of the following methods:
1.

The driver can indicate the return status immediately and can
return to the first address on the stack in the normal
fashion.
If the driver accepts the status change, it merely
executes a RETURN instruction.
(The status change byte
$SCERR has been preset with 1.) If the driver rejects the
status change,
it loads the relevant I/O error code into
$SCERR and executes a RETURN instruction.
(The I/O error
code symbols are listed in an appendix of the IAS/RSX-il I/O
Q£erations Reference Manual.)

4-68

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
2.

The driver need not
indicate the status immediately but
removes the first address from the stack, saves it, and
returns immediately to the second address.
The driver
then
has 60 seconds to perform its processing, to indicate the
return status, and to
return to the first address.
The
driver can use the offset S.CTM in the status control block
to time out some operation (such as a protocol
rundown)
and
then accept or reject the operation by using $SCERR.

If the driver does not return to the first address on the stack,
the
system can be considered to be in an indeterminate state and possibly
corrupted.
The driver must return immediately because status changes
should not stall the system.
The 60-second delay allows a driver time
to overcome conditions over which it has little control
(such as
network connections).
System disk and terminal drivers must indicate
return status immediately.

4.5.11

Interrupt Entry Point

Upon an interrupt, control
is dispatched to the driver
from an
interrupt vector through an interrupt control block or directly from
an interrupt vector.
A device may have more than one interrupt entry
point.
The entries in the DDT interrupt address block are used to
initialize either the vector(s) or the interrupt control block with
the address(es)
of the related interrupt entry point(s).
(Refer to
Section 4.5.1 for a discussion of the interrupt address block.)
All
drivers should observe the protocol for handling interrupts introduced
in Section 1.3 and summarized in Section 4.1.
from the
interrupt
If the driver is loadable,
it will be called
The following are the
dispatch coroutine $INTSI in the Executive.
register contents when the driver gets control:
R4

= Controller index

Registers R4 and R5 are available to the driver.
The driver
runs at
the priority set
in the
interrupt control block.
To dismiss the
interrupt, a driver executes a RETURN instruction.
If the driver is resident,
it receives control directly from the
interrupt vector.
It runs at priority PR7 and the low-order four bits
of the PS have the controller number of the
interrupting device.
Because the low-order four
bits are status bits and almost any
instruction modifies them,
the first operation that should
be
performed
is to save the PS.
Then, the driver does its processing at
priority PR7 (saving registers if necessary).
After processing,
it
restores the registers (if necessary) and dismisses the interrupt by
executing an RTI instruction.
However, all reasonable drivers should use the INTSV$ macro call at an
interrupt entry point.
The INTSV$ macro resolves entry processing for
both loadable and reside~t drivers.
For loadable drivers, INTSV$ does
not generate a call
to $INTSV because LOAD establishes in the
interrupt control block the call to the $INTSI coroutine.
The $INTSI
coroutine saves R4 and R5;
sets the priority to that in the interrupt
control block;
and forms the controller index from the PS and stores
it
in R4.
(LOAD previously set the priority in the interrupt control
block based on the value at offset K.PRI
in the controller request
block.)
For resident drivers, INTSV$ generates a call to the $INTSV coroutine,
which sets the priority to that specified in the INTSV$ macro call;
saves registers R4 and R5;
and forms the controller index from the PS
and stores it in R4.
4-69

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER
For both load~ble and resident drivers, INTSV$ generates code to load
R5 with the UCB address of the interrupting unit. After the INTSV$
call i~ the driver code, the following conditions pertain for both
loadable and resident drivers:
R5
R4

UCB address of the interrupting unit
Controller index

The driver may then do the following:
1.

Save extra registers if necessary

Do whatever processing is necessary

Become a fork process to access the data
call Executive routines if necessary

Restore the explicitly saved extra registers

Execute a RETURN instruction
dismisses the interrupt

the

structures

coroutine,

which

In summary, then, the INTSV$ macro eliminates your having to consider
the coding differences between a loadable and a resident driver in the
interrilpt service routine.

4.5.12

Volume Valid Processing

System--supplied drivers that service mountable devices
(those that
have ~:he DV.MNT bit in the UCB U.CWI word set) take advantage of
specia:_ processing of volume valid for a device. For such devices the
Execut_ve directive processor DRQIO checks that either of the mounted
status bits US.MNT or US. FOR in the UCB U.STS word is set.
If a
mounterl status bit is not set, DRQIO requires that a device-specific
bit c a :. 1 e d vol urn e val i d
( US. VV)
be set 0 r e I s e i t
r e j e c t s the
direct-vee
If a mounted status bit is set, DRQIO does not check the
volume valid bit.
(DRQIO assumes that the MOUNT command properly set
the vo:ume valid bit.)
To effectively service a mountable device on
the
system,
a
user-written driver should perform in one of two ways. First, it can
take ac'vantage of the volume valid capability in the same way that a
system-supplied driver does.
This processing involves calling the
$VOLVD routine in the Executive module IOSUB, and handling the
s pin n i r, g - ups tat usb i t
( US. S P U) and the vo 1 urn e val i d bit ( US. VV) i n
the UCE, status byte U.STS.
(For details of this mechanism, refer to
driver source code supplied on the system.) Second, a user-written
driver can circumvent the volume valid processing by doing the
following:
1.

Enable the set characteristics function (IO.STC)
valid in the DCB legal function mask word

Enable the same function in the DCB no-op function mask work

Statically set the US.VV bit in the UCB in
base source code

the

for

driver

volume

data

The second method allows the device to be successfully mounted and
associated with an ancillary control processor without your having to
includE code in the driver to handle US.VV.

4-70

CHAPTER 5
INCORPORATING A USER-SUPPLIED DRIVER INTO RSX-IIM-PLUS

This chapter describes how to incorporate a user-supplied driver into
an RSX-IIM-PLUS system. The material in the chapter depends on your
having created source code according to the programming specifics
given in Chapter 4.

5.1

GUIDELINES FOR INCORPORATING A DRIVER

procedures that you follow to incorporate a user-supplied driver
into RSX-llM-PLUS depend on the type of driver you have. Your driver
is one of the following types:

•
•
•

Loadable driver with a loadable data base
Loadable driver with a resident data base
Resident driver with a resident data base

If your driver is loadable with a loadable data base, you may perform
a system generation to include your driver, or you may incorporate it
directly into your currently running system. If you want to use a new
version of a loadable driver with a loadable base, and your driver is
currently loaded, you must create a new system image file, load the
new version of the driver into the file, and then bootstrap the new
system. Refer to Section 5.1.1 if you want to incorporate your driver
at system generation.
Refer to Section 5.1.2 if you want to
incorporate your driver after system generation.
If your driver is loadable with a resident data base, or is resident,
you must perform a system generation because the resident driver
and/or data base reside in the Executive and must be assembled and
task built as part of the Executive.
Refer to Section 5.1.1 to
incorporate your driver at system generation.
Because loadabla drivers and loadable data bases can be changed and
reloaded without performing a system generation, loadable drivers with
loadable data bases are easier to debug and maintain than resident
drivers and/or resident data bases.

5.1.1

Incorporating a Driver at System Generation

If you want to build a loadable driver with a loadable
data base during system generation, proceed as follows:
1.

Assemble and task build
or Task Builder errors.

)~ur

5-1

resident

driver to eliminate any assembly

INCORPORATING A USER-SUPPLIED DRIVER INTO RSX-llM-PLUS
2.

Put the MACRO-II source files containing your driver code and
data base in UFD [11,10]
on the target system disk. The
driver source file should be named xxDRV.MAC and the data
base source file should be named xxTAB.MAC, where xx is the
2-character device mnemonic.
Mnemonics for user-supplied
devices should begin with the letters J or Q to avoid
conflict with DIGITAL-supplied devices.

Perform a system generation and choose the Full-functionality
Executive.
Answer the questions concerning user-supplied
drivers printed during system generation.
This procedure
includes your driver data base in the Executive if it is
resident and builds your driver task image.
A loadable
driver and data base are loaded into the system image file.
Refer to Section 5.3 for a description of the system
generation procedure.

Use CON from MCR to make your devices accessible.
Section 5.2.5 for the CON command description.

Refer

If you want to build a resident driver, proceed as follows:
1.

If your driver can run loadable with a loadable data base,
first build and test it as loadable with a loadable data
base.

Put the MACRO-II source files containing your driver code and
data base in UFD [11,10] on your target system disk. The
driver source file should be named xxDRV.MAC and the data
base source file should be named xxTAB.MAC where xx is the
2-character device mnemonic.
Mnemonics for user-supplied
devices should begin with the letters J or Q to avoid
conflict with DIGITAL-supplied devices.

Perform a system generation.
If you want to include a
resident driver, you must not choose the Full-functionality
Executive or Executive data space support.
Answer the
questions concerning user-supplied drivers printed during
system generation. This procedure includes your driver and
data base modules in the Executive. Refer to Section 5.3 for
a description of the system generation procedure.

Use CON from MCR to make your devices accessible.
Section 5.2.5 for the CON command description.

Refer

Incorporating a Loadable Driver with a Loadable Data Base After
System Generation

5.1.2

The prl)cedures to incorporate a loadable driver with a loadable
base aEter system generation involve the following steps:

data

Assemble and task build your driver to eliminate any assembly
or Task Builder errors.

Put the MACRO-II source files containing your driver code and
data base in UFD [11,10] on your target system disk. The
driver source file should be named xxDRV.MAC and the data
base source file should be named xxTAB.MAC, where xx is the
2-character devic~ mnemonic.
Mnemonics for user-supplied
devices should start with the letters J or Q to avoid
conflict with DIGITAL-supplied devices.

5-2

INCORPORATING A USER-SUPPLIED DRIVER INTO RSX-llM-PLUS
3.

Run the system generation
procedure
and
follow
the
instructions
in
the "Adding a Device"
section.
(For
information on invoking the system generation procedure
(SYSGEN),
refer to the RSX-llM-PLUS System Generation and
Installation Guide) •
The system generation procedure asks you to enter the
2-character device mnemonic for your driver.
Remember, this
should be the same mnemonic used in the driver and data base
source file names.

5.2

Use the MCR LOA command to link your driver data base into
the system device tables and to load your driver data base
and driver code.
Refer to Section 5.2.4 for the LOA command
descriptions.

Use CON from MCR to place the controller(s)
and unit(s)
on
line.
(CON can also alter vector assignments.) Refer to
Section 5.2.5 for the CON command descriptions.

WHAT THE SYSTEM GENERATION PROCEDURE DOES FOR YOU

The system generation procedure assembles your driver and data base,
puts the resulting object modules in the Executive object library and
task builds your driver.
If your driver or its data base is resident,
the driver and/or data base is included in the Executive.
If your
driver or its data base is loadable, the driver and/or data base
is
loaded
into
the system image file.
You must then make the
controller(s) and unit(s) accessible.
The commands that the system generation procedure uses to assemble
your driver and data base, insert your driver and data base modules in
the library, and task build your driver, are the same commands that
you may use to assemble,
insert and task build your driver.
The
following subsections explain each of the procedures for incorporating
your driver.

5.2.1

Assembling the Driver and Data Base

The system generation procedure assembles your
base with the following commands:

driver

and

its

data

MAC> [11, 24] xxDRV, [11, 34] xxDRV/-SP= [1, 1] EXEMC/ML, [11,10 ]RSXMC/PA:l,xxDRV
MAC>[11,24]xxTAB,[11,34]xxTAB/-SP=[1,1]EXEMC/ML,[11,10]RSXMC/PA:I,xxTAB
If your driver is resident, these commands are located
in the file
RSXASM.CMD.
If your driver is loadable, these commands are located in
the file xxDRVASM.CMD, where xx is the device mnemonic'.
The commands to the assembler specify as input the Executive macro
library EXEMC.MLB,
the Executive assembly prefix file RSXMC.MAC, and
either your driver code or driver data base source file (xxDRV.MAC or
xxTAB.~IAC) •
EXEMC.MLB contains the macro definitions of structures
and symbolic offsets that your code may reference.
(The source code
for some of the macro definitions is given in Appendix A.) RSXMC.MAC
contains symbols defined during system generation and definitions of
some macros that your driver may invoke (such as DDT$, GTPKT$, and
INTSV$). The assembler looks for the source file of your driver
in
UFD [11, 10] •

5-3

INCORPORATING A USER-SUPPLIED DRIVER INTO RSX-llM-PLUS
As output, the assembler creates object modules in UFD [11,24] and
listin3 files in UFD [11,34].
The object modules xxDRV.OBJ and
xxTAB.JBJ will later be put in the Executive object library.
You
should
retain
the
listing files xxDRV.LST and xxTAB.LST for
docume~tation and maintenance purposes.

5.2.2

Inserting the Driver and Data Base Modules in the Library

After {our driver and data base modules have been assembled, the
driver and data base modules are added to the Executive object
librart. Commands to the Task Builder (described in Section 5.2.3)
requir~ the modules be in this library.
The sy:;tem generation procedure uses the following commands
both the driver and its data base to the same library:

add

L13R (1,24]RSXllM/RP=[11,24]xxDRV,xxTAB
The cOI:1mand to LBR adds the object modules of both your driver and its
data b.lse to the Executive object library RSX11M.OLB, which resides in
UFD [1.24]. RSXllM.OLB is built from object modules assembled during
system generation.
The /RP switch ensures that any modules of the
same name are replaced by the recently created modules.
If this is
not the first time you have performed this operation, LBR prints
messagl~s telling you that it replaced your modules in the library with
the new versions.

5.2.3

Task Building the Driver

After the modules have been added to the Executive object library, the
system generation procedure task builds your driver and data base.
The cOPlmands for a resident driver are located in the file RSXIIM.CMD.
The commands for a resident data base are located in the file
RSX11M.CMD on systems without Executive data space support and in the
file D~;PllM.CMD on systems with Executive data space support.
The cOl"1ma:1ds for a loadable driver are located in xxDRVBLD.CMD where
xx is the device mnemonic. The following discussion explains each of
the lines that are contained in the command file for a loadable
driver:
1.

When the system generation procedure builds your driver, a
task-image file name and a symbol definition file name are
specified as TKB output.
The task image
and
symbol
definition files are placed in the UFD corresponding to the
system UIC that will be in effect when the LOA command is
issued.
The file names are both xxDRV, where xx is the
device mnemonic. The Task Builder produces the output files
named xxDRV.TSK, xxDRV.MAP, and xxDRV.STB. For example, the
input supplied to TKB to build the xx device would look like
the following:
[1, 54] xxDRV/-HD/-MM, [1, 34] xxDRV/-SP, [1,54]xxDRV=

No task header is included. The switch /-HD is used, as in
the previous example. A driver is not really a task, but an
extension of the Executive, and as such needs no task header.

The switch /-MM must be used in the command line.

5-4

INCORPORATING A USER-SUPPLIED DRIVER INTO RSX-IIM-PLUS
4.

A map file is produced and
is useful
for debugging.
All
driver map files are written to UFD [1,34].
The switch I-SP
suppresses automatic spooling to the line printer.

The system generation procedure links your driver
to the
system symbol definition file that contains definitions of
Executive global symbols.
Continuing the example from item 1
above might give further TKB input that would like this:
[1,24]R8XIIM/LB:xxDRV:xxTAB
[1,54]RSXIIM.STB/SS
The first line above specifies the library file
(/LB)
in
which the input driver object module and the object file for
the loadable data base can be found.
The object module
specification
for
the
driver
always
precedes
the
specification for the data base in the TKB command line.
The second line in item 5, above, indicates that the symbol
definition file RSXIIM.STB is to be searched selectively
(ISS) for definitions of Executive global symbols.
Note that
the ISS switch must appear
in this context.
It is never
omitted.

The system generation procedure links your driver
to the
system library file that defines masks and offsets used in
the Executive.
To continue the example:
[1,I]EXELIB/LB

I
The single slash begins the option phase of the Task Builder.

The Task Builder is directed not
stack within the driver.

allocate

space

for

STACK=O
8.

A partition for the driver is specified:
PAR=DRVPAR:120000:40000
II
The partition name DRVPAR is the typical
name
of
a
conventional partition reserved for drivers.
A driver may be
loaded
into any system-controlled partition.
The
base
virtual address of the partition is always 120000 (8).
That
is, the loadable driver must be mapped through kernel APR5.
The length of the partition, the second parameter should not
exceed 8K words (40000 octal bytes).
The double slash ends the option phase of the Task Builder.

5.2.4

Loading the Driver

After your driver is task built, you are ready to load the driver on
your system.
This procedure is used when you are incorporating your
loadable driver with a loadable data base after system generation.
Loading
is done by using the privileged MCR command LOAD.
Its form
is:
>LOAD xx: [/PAR=GEN] [/HIGH]

5-5

INCORPORATING A USER-SUPPLIED DRIVER INTO RSX-IIM-PLUS
The va~iable xx is the
2-character device mnemonic.
Specifying a
partition is optional.
If a partition is not specified, the partition
input :0 the Task Builder is used.
The keyword /HIGH puts the driver
as hig1 as possible in the partition.
The default condition is to put
the driver as low as possible in the partition.
LOAD p~rforms many diagnostic checks on your driver data base,
reloca:es many addresses within the data base, and loads the data base
and th,~ driver code into memory.
Because the LOAD diagnostic checks
are c')mplicated and LOAD supports another, infrequently used option
(/CTB), a description of LOAD is given in Section 5.4.
LOAD error
messages and meanings are listed in the RSX-IIM/M-PLUS MCR Operations
Manual.
After the driver is loaded, the controller(s) a~ units are
off-line and are not accessible.
To allow access to the device, you
must next place the controller(s) and unit(s) on-line.

5.2.5

Making the Devices Accessible

After lour driver has been successfully loaded,
you must make the
controller(s)
and units accessible.
You use the CON task to place
controller(s) and units on-line, to change vector and CSR assignments
that
IOU established
in the driver data base, and to take units and
controller(s) off-line.
Unless the vector and CSR values in the
driver data base are not correct for the running system, you can place
the c01troller(s) and units on-line.
You may change the vector and
CSR a3signments to match the hardware CSR and vector assignments only
while the controller(s) and units are off-line.

5.2.5.l Setting Vector and CSR Assignments - If the values at the
offset; S.VCT/K.VCT and S.CSR/K.CSR in the KRB(s) of your driver data
base are
incorrect for
the running system,
you must issue the
privil2ged SET command in CON to establish the correct values.
NOTE
Because CON causes the Executive to
access
a driver data base when it
changes a vector or CSR assignment,
you
must load the driver before you issue
the SET commands in CON.
If a driver
data base
is resident, you do not need
to load the driver to establish correct
vector and CSR assignments.
You mU3t do this operation while the controller(s)
and units are
off-li1e.
(LOAD ensures that,
for
a loadable data base,
the
controller(s) and unit(s) are off-line.) Typical commands to set a
vector and CSR for a driver that supparts a single controller are as
follow3:
)I:ON

C)N)SET xxA VEC=300 CSR=160040
CJN)"'Z
)

The command first establishes 300 as the vector for controller A of
type
<x.
The Executive accesses the offset S.VCT/K.VCT in the driver
data b3se and writes the specified value divided by 4.
The command

5-6

INCORPORATING A USER-SUPPLIED DRIVER INTO RSX-IIM-PLUS
secondly establishes the control and status register address as 160040
for controller A of type xx.
The Executive accesses the offset
S.CSR/K.CSR in the driver data base and writes the specified value.
You type the CTRL/Z combination to exit from CON.
After you set the
vector or CSR assignment, you can attempt to place the controller(s)
and units on-line.

5.2.5.2 Placing a Controller and Units(s) On-Line - If the vector and
CSR assignments in your driver data base are correct for the running
system, you can place the controller(s) and units on-line by issuing
the privileged ONLINE command in CON.
NOTE
Because
on-line
driver,
before
CON.

placing a controller or a unit
causes the Executive to call the
you must have loaded the driver
you issue the ONLINE command in

The following commands demonstrate a typical sequence
single controller and two attached units on-line.

place

)CON
CON)ONLINE xxA
CON)ONLINE xxO:
CON)ONLINE xxI:
CON)"'Z
)

The first command places controller A of type xx on-line.
The
Executive accesses the KRB of the controller to read the S.VCT/K.VCT
offset and initializes the vector to point to the related
interrupt
control block.
NOTE
If the driver
is resident within the
Executive, the vector points directly to
the driver.
For a common interrupt
controller,
the vector points to the
interrupt entry address in the Executive
rather than to an ICB.
The Executive then ensures that the address in S.CSR/K.CSR is valid
(that is,
some device responds at that address).
Refer to Section
5.2.5.3 for a discussion of CSR and vector assignment errors.
Next,
the
Executive calls the driver at its controller status change entry
point.
Only after the driver indicates success does the Executive
change the status bit in the SCB/KRB of the controller from off-line
to on-line.
The second and third commands place logical units 0 and lon-line.
The Executive checks that the controller is on-line (that is, an
access path exists to the unit).
If the controller
is not on-line,
the Executive sets the UCB of the unit as marked for on-line.
(The
Executive automatically places on-line a unit that is in the marked
for on-line state only when its controller is placed on-line.) If the

5-7

INCORPORATING A USER-SUPPLIED DRIVER INTO RSX-llM-PLUS
contro~ ler

is on-line, the Executive calls the driver at its unit
status change entry point. Only after the driver indicates success
does tt.e Executive change the status bits in the UCB of the unit from
off-lire to on-line.
(The driver is not required to take any special
action to indicate success. Refer to the discussion of status change
entry F,oints in Section 4.5.)
A.fter J'ou have issued the ONLINE commands, you can issue the DISPLAY
commanc
in CON as follows to verify that the devices are in the state
that yeu want them to be in:
)C ON
C(;N>DISPLAY FULL FOR xx

(The display appears at the terminal.)

The con~mand displays status of all controllers of type xx and
units cttached to the controllers.

all

5.2.5.~
CSR and Vector Assigment Errors - CSR and vector assignment
errors are not always immediately detectable. When you issue the
ONLINE command to CON to place a device on-line, CON verifies that
some eevice responds at the CSR address that you established at the
S.CSR/~.CSR offset in your driver data base.
CON can encounter one of
three rossible cases:

•

Your device is at the established CSR address and it responds
to the CON probe. This is the case you want. CON continues
attempting to place your device on-line.

•

Your device is at some address in the I/O page other than the
established CSR address, but some other device responds at the
established CSR address. CON cannot distinguish your device
from some other device, and continues attempting to place your
device on-line possibly resulting in a system hang or crash.

device is at some address in the I/O page other than
• Your
established CSR address, and no device responds at
established CSR address.
In this case, CON reports
and does not place the device on-line.

the
the
error

Therefore, if CON places your device on-line and
the
device
subsequently
does
not
respond, have a DIGITAL Field Service
representative verify the CSR address jumpers and ensure that the CSR
assignment in your driver data base matches the verified hardware CSR
assignment.
When the vector address developed from the value that yOIl established
at the offset S.VCT/K.VCT in the driver data base differs from the
hardware vector assignment, several outcomes are possible. Should the
established vector already be in use (that is, pointing at other than
the nonsense interrupt entry address in the Executive), CON reports
the condition and does not place the device on-line. If the vector is
not in use, CON establishes it as the device vector and continues
attempting to place the device on-line.
This action does not
guarantee that the software and hardware vector assignments match.

5-8

INCORPORATING A USER-SUPPLIED DRIVER INTO RSX-IIM-PLUS
When CON does place a device on-line and the software and
vector assignments do not match, two results are possible:
•

Your driver will time out waiting for an interrupt.

•

The device will interrupt through an unused vector.

hardware

If error logging is active on your system, a nonsense interrupt will
be logged as an undefined interrupt error and the ERRSEQ count in the
Executive is increased by 1.
The RMDEMO task display, which
includes
the ERRSEQ count, will reflect the occurrence of nonsense interrupts
by an increasing number in ERRSEQ.
Consult an error log
report and
look for undefined interrupt errors.
When (1) error logging
is active,
(2) nonsense interrupts do not
occur,
and
(3) your driver
times out, the interrupt could be going
throuqh some other driver vector.
If the unexpected interrupt goes to
a DIGITAL-supplied driver, one of two outcomes is possible.
•

The interrupt will simply be dismissed.
(Common interrupt
routines dismiss unexpected interrupts and some drivers keep
track of when they expect interrupts and dismiss unexpected
ones.)

•

The driver will react in an unpredictable fashion
attempting to terminate the last I/O packet again)
system crash.

Thus, error logging and the ERRSEQ count in the
indicate improper vector assignments.

5.3

RMDEMO

(such as
causing a

display

help

USgR-SUPPLIED DRIVER SYSTEM GENERATION DIALOGUE SUMMARY

If you are building either a loadable driver with a resident data base
or a
resident driver,
you must perform a
system generation to
incorporate your driver into the system.
This section summarizes the
system generation dialogue only as it relates to user-supplied driver
support and related features.
For more information on the system
generation
procedure
itself,
refer to the RSX-IIM-PLUS System
Generation and Installation Guide.
NOTE
If you are building a
loadable driver
with a loadable data base, you need not
perform
a
system
generation
to
incorporate your driver.
However, you
can still build your driver
during
system
generation.
Section
5.1.2
describes the complete procedures to
build a loadable driver with a loadable
data base any time after you build the
Executive under which the driver will
run.

5.3.1

Choosing Executive Options

The system features are determined during
the "Choosing
Executive
Options"
section.
You have to specify answers related to including a

5-9

INCORPORATING A USER-SUPPLIED DRIVER INTO RSX-llM-PLUS
user-sjpplied driver in your system.
appear;:

A question in the following form

> Do you want the Full-functionality Executive?

[YIN D:Y]:

If you choose the Full-functionality Executive, your driver must be
loadable with either a loadable or resident data base.
If you want to
incorp')rate a user-supplied
resident driver,
you must omit the
Full-fjnctionality Executive and omit Executive data space support.
All DI~ITAL-supplied drivers should be loadable with a
loadable or
reside~t data base.
If you do not choose the Full-functionality Executive,
generation procedure asks the two following questions:

> Do you want Executive data space support?

the

system

[YIN D:N]:

If you have a loadable driver with either a loadable or resident data
base, you should answer Yes to this question.
If you have a resident
driver, you must answer No to this question.

> What is the rCB pool size (in words)?

[D R:16.-1024.

D:128.]:

On systems with Executive data space,
the
rCB pool must be large
enough for
all the drivers loaded into the virgin system image.
One
rCB (8 words) is needed for every 16(10) controllers of the same type.
If
the device controlled by your driver has a
large number of
controllers, you should ensure that there is enough ICB pool space.
Whether you choose the Full-functionality Executive or
questi)n in the following form asks about XDT support:

> Do you want to include XDT?

not,

another

[YIN D:N]:

You sh)uld answer Yes to this question.
XDT (described in Chapter 6)
is helpful
in debugging system problems which incorporating a faulty
driver may engender.
After this question, there are no more questions in this
concer~ing user-supplied driver support or related features.

5.3.2

section

Choosing Peripheral Configuration

In the Peripheral Configuration section of the system generation
you must answer questions about your driver and its data
base c)nfiguration. A question in the
following
form asks you to
supply your device mnemonics:
proced~re,

> Enter device mnemonics for user-supplied drivers [5]:
You mu;t enter the 2-character device mnemonic for your driver.
This
should be the same mnemonic used in the driver and data base source
file n3mes.
If you did not select Executive data space support, a question in
following form appears:

> Do you want the xx:

driver to be loadable?

[YIN D:N]:

Answer Yes to this question if you want a loadable driver.
if you want your driver to be resident.

5-10

the

Answer

INCORPORATING A USER-SUPPLIED DRIVER INTO RSX-llM-PLUS
If your driver is loadable, the next question in the system generation
procedure asks you about your data base:

> Do you want the xx:

driver's data base to be loadable?

Answer Yes to this question if you want a loadable data base.
No if you want your data base to be resident.

[YIN D:N]:
Answer

The system generation procedure always asks you to specify the highest
interrupt vector address:

> What is the highest interrupt vector address?

[0 R:n-774 D:n]:

The system generation procedure calculates and displays the highest
interrupt vector address needed for the DIGITAL-supplied devices.
If
the vector address for your device is higher than this, enter the
highest vector address used by your device.
This ends the system generation
portion
of
incorporating
a
user-supplied driver.
If you are generating a new system, the system
generation procedure includes your driver in the Executive if it is
resident, or loads your driver
into the system image if it is
loadable. After the newly built system is running, you must make the
devices that your driver supports accessible, as directed in Section
5.2.5.
If you are adding your driver after system generation, you must load
your driver and make the devices that it supports accessible, as
described in Sections 5.2.4 and 5.2.5.

5.4

LOAD PROCESSING

The Executive LOAD routines extensively check the driver data base;
LOAD provides the ICTB switch to handle multidriver controllers.
The
following sUbsections describe the two aspects of LOAD.

5.4.1

LOAD Operations and Diagnostic Checks

Two modules (LDVLDB and LDVFIN) in LOAD, load a driver
into memory:
one conditionally checks the validity of and loads the data base;
and
the other finishes the operation by loading the driver.
If there
is
no
resident data base, the data base is loaded into the system pool.
The LOAD routines relocate and validate many of the pointers within
the data base and,
in the process, validate other data in the
structures.
(If the data base is resident, no· validity checks on the
driver data base are performed.) The driver itself is then loaded into
its partition, and the interrupt control blocks are created.
To read the data base from the xxDRV.TSK file into the system pool,
the global labels $xxDAT and $xxEND, defining the start and end of the
data base, are needed.
To check the data base, the LOAD routines must know the starting
address of the DCB.
If the global label $xxDCB is not defined (that
is, not in the symbol table file), the start of the DCB is assumed to
be the first word of the data base. Many unusual error conditions
result when LOAD assumes that the DCB is at the start of the data base
and the DCB is elsewhere in the data base and not labelled properly.
Thus, to avoid this type of problem,
you should always define the
start of the DCB with the global label $xxDCB.

5-11

INCORPORATING A USER-SUPPLIED DRIVER INTO RSX-llM-PLUS
Each CTB is checked and relocated.
checkeJ and relocated:

The

following

offsets

are

both

L. LNK

The link to the next CTB must be even.
If it is
not zero, it must point within the data base, and
the CTB to which it points must lie within the
data base.
(Because it is highly unusual to have
two controller types in one driver data base, this
value is usually zero.)

L.DCB

The address of the related DCB must be even, point
within the data base, and the DCB to which it
points must lie within the data base.
If L.DCB
points to a common interrupt table, the common
interrupt entry point address in the table must be
even and lie within the Executive.
The DCB
address(es) in the table must be even, and the
DCB(s)
to which each address points must lie
within the data base.

L.KRB

Each pointer in the table of KRB addresses must be
even and must point within the data base, and the
KRB to which each cell points must lie within the
data base.

The fo .lowing offsets in the CTB are checked:

L NAM

The controller name cannot duplicate other L.NAM
entries in the resident or loadable data base.

L. NUM

The number of controllers must
(decimal) •

Each KHB is checked and relocated.
are both checked and relocated:

less

than

The following offsets in

the

KRB

K.OWN

The pointer to the owner UCB must be even and
point within the data base, or be zero.
If it is
nonzero, the pointer is relocated.

K.OFF

The start of the table of UCB addresses produced
from K.OFF must be even and must point within the
data base.
The entries themselves must be even,
point within the data base, and the UCB to which
each cell points must lie within the data base.

K.CRQ
K.CRQ+2

The listhead for the controller request queue.
It is initialized to an empty list with the first
word zero, and the second word pointing to the
first, relocated.

The following offset in the KRB is checked:
K.URM

In a multiprocessor system, the UNIBUS run mask
for the controller must have exactly one bit set
and that bit must correspond to an existing UNIBUS
run (either primary or secondary).

LOAD puts each controller in the off-line state by setting the KS.OFL
bit in the K.STS byte. Therefore, all controllers are off-line until
you use CON to place each one on-line.

5-12

INCORPORATING A USER-SUPPLIED DRIVER INTO RSX-llM-PLUS
Each DeB is checked and relocated.
checked and relocated:

The

following

offsets

are

both

D.LNK

The link to the next DCB must be even.
If
it
is
nonzero,
it must point within the data base, and
the DCB to which it points must lie within the
data base.

D.UCB

The link to the first UCB must be even and must
point within the data base, and the UCB to which
it points must lie within the data base.

The following offsets in the DCB are checked:
D.NAM

The device name must be the same as that which you
specified in the LOAD command line.

D.UCBL

The length of the UCB must be even and nonzero.

D.UNIT

The highest unit number (increased by 1) used with
D.UCBL forms the last address of all UCBs.
This
address must lie within the data base.

The pointer to the driver dispatch table (D.DSP)
show that the driver is not loaded.
Each UCB is checked and relocated.
checked and relocated:

The

following

set

offsets

zero

are

both

U.DCB

The pointer to the DCB must point to the DCB
points to this UCB.

that

U.SCB

The pointer to the SCB must be even, must point
within the data base,
and the SCB to which it
points must lie within the data base.

U.RED

The unit redirect pointer must be nonzero and even
if it is an Executive address.
If it is not an
Executive address, it must be nonzero,
even,
and
point within the data base.

LOAD places each unit in the off-line state by setting the US.OFL bit
in the U.ST2 byte.
Therefore, all units are off-line until you use
CON to place each one on-line.
Each SCB is checked and relocated.
checked and relocated:

The

following

offsets

are

both

S.KRB

The pointer to the KRB must be even, must point
within the data base,
and the KRB to which it
points must lie within the data base.
If S.KRB is
nonzero,
there must be a CTB in the loadable data
base.

S.KTB

If the table of KRB addresses is present,
each
entry must point within the data base.
(LOAD
preserves bit zero in each entry.) Each entry in
the
table must also have a matching entry in the
table of KRB addresses of a eTB in the loadable
data base.

5-13

INCORPORATING A USER-SUPPLIED DRIVER INTO RSX-llM-PLUS
The fcllowing offsets in each SCB are initialized as described:
f.LHD

The head of the I/O queue is set to zero and the
pointer to
the end of the queue (S.LHD+2) is set
to point at S.LHD.

f.PKT

The pointer to the current I/O packet is set to 1.

These last checks end the loading and validating of the data base.
After the data base is loaded and validated and no error is found, the
driver
itself is loaded
into memory.
In loading the driver, the
driver dispatch table is validated, each interrupt entry in the driver
dispatch table is inspected,
and the vector(s) are checked.
If a
vector address is higher than the highest vector address allowed on
the system (as specified at system generation) or does not point to a
nonsense interrupt entry point, LOAD prints a warning message.
You
can use CON to set the correct vector address before you place the
controller on-line.
Interrupt control blocks are created and
linked
into the list startin~ at L.ICB in the CTB.
The format of the DDT must be consistent with that described
in
Section 4.5.1.
If the device that the data base describes does not
have any physical controllers
(that is,
the value
at
offset
S.VCT/K.VCT equals zero), the DDT is not checked.
If S.VCT/K.VCT is
nonzero, the device has at least one interrupt vector and therefore at
least one
interrupt entry point.
The DDT is then checked.
The two
global labels $xxTBL and $xxTBE must define the start and end of the
DDT.
The generic controller name(s) must be nonzero and the interrupt
entry values must be valid.
Interrupt entry point 0 must be nonzero,
even, and lie in the range 117777 and 140000.
If the format of DDT is
inconsistent, LOAD prints an error message, restores the system device
tables, and exits.
When the driver is loaded, all links are established.
The DCB of the
loadacle data base is put in the list of DCBs just in front of the DCB
for the first pseudo device.
The CTB(s) are linked to the end of the
CTB list.
The DDT address D.DSP, the driver PCB address D.PCB, and
the driver mapping S.KS5 (the block number of the first word of the
driver)
in the fork block are initialized.
The address of the start
of the KRB table in the CTB, denoted in the driver data base by the
global label $xxCTB, is loaded into the DDT.

5.4.2

Use of /CTB in LOAD

Some controllers such as the RH70 can support more than one device
type.
The CTB for
such a controller differs in two ways from the
standard CTB.
First, the table of KRB addresses at the end of the CTB
contains pointers to KRBs of controllers for different device types.
Second, instead of a pointer to one DCB in the CTB, there is a pointer
to a table of DCB addresses because each different device must have a
separate DeB to describe each separate device type.
Morever, more
than one driver supports the different types of devices capable of
being attached to the controller.
The data base for
such a controller must necessarily be split.
Because only one CTB is needed to describe the type of controller,
only one driver that supports a device on that controller type can
define that CTB.
The remaining drivers cannot define a CTB but must
reference the CTB deflned for the first driver.
Because all drivers
and their data bases can be loadable, the remaining drivers and the
syntax in the LOAD command must indicate to the LOAD routines which

5-14

INCORPORATING A USER-SUPPLIED DRIVER INTO RSX-llM-PLUS
resident CTB to use.
(Of course, the driver data base that defines
the CTB of the multidriver controller must be loaded or already
resident before the other drivers can be loaded.)
The driver data base that defines the CTB for a multidriver controller
allows for structures to define the data base of drivers that are not
resident. In particular, for each device controller there must be a
slot in the CTB table of KRB addresses to hold the pointer to the KRB.
(A KRB must be defined to describe each occurrence of a controller.) A
zero is: in the pointer for a device whose data base (and therefore,
whose KRB) is not resident. Moreover, the table of DCB addresses in
the common interrupt table must have sufficient slots to point to the
DCBs of all device types that the controller supports. A zero in the
DCB table indicates no DCB exists (that is, the data base for a device
type is not res i den t) •
To load the data base of a device attached to the multidriver
controller, the LOAD routines must know the controller name, the
location of the device on the MASSBUS controller and the KRB(s) of the
device(s:) whose driver is to be loaded. The JCTB syntax in the LOAD
command supplies the first two pieces of information. For example:
)LOA DR:jCTB=RHB,C
)

The letters RH are the name in the CTB already resident in the system.
LOAD routines search the system list of CTBs to locate the correct
one. The letters Band C are the slots in the table of KRB addresses
that will be used to link the resident CTB with the KRB in the data
base being loaded.
The name of the device DR reflects the name in the DCB that is being
loaded.
An empty slot in the table of DCB addresses in the resident
data base will be made to point to this DCB.
The LOAD routines need to find the correct KRB in the data base being
loaded.
A global label of the form $cca (where cc is the controller
name and a is the slot, or controller number) must define the start of
the KRB(s) being loaded. Thus, the loadable data base for the example
above must contain the labels $RHB and $RHC, which are the KRB names.
The address(es) of the label(s) is loaded into the appropriate slot in
the CTB table of KRB addresses.
In summary, then, the JCTB syntax on the LOAD command combined with
the global label(s)
allows the LOAD routines to link a driver data
base being loaded with a currently resident driver data base.
The
KRB(s) being loaded are incorporated in the resident data base and the
DCB being loaded is connected to the common interrupt table.

5-15

CHAPTER 6
DEBUGGING A USER-SUPPLIED DRIVER

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

Crash dump analysis support routine (CDA)

Executive debugging tool

(XDT)

You need not select any of this software during system generation.
If, however, you do require the facilities they offer, you can select
them for
incorporation in your system.
The following sections
describe the features and use of each debugging aid.

6.1

CRASH DUMP ANALYSIS SUPPORT ROUTINE

The crash dump analysis (CDA) support routine prints the following
message on a notification device specified at system generation:
CRASH - CONT WITH SCRATCH MEDIA ON device mnemonic
You can then ensure that the secondary crash dump device is ready and
depress the CONT switch on the operator's console. The Executive
Crash Dump routine will dump memory to the crash dump device and halt
the processor upon completion.
The procedure for subsequently invoking CDA, which reads and formats
the memory dump,
is documented in the RSX-llM/M-PLUS Crash Dump
Analyzer Reference Manual.

6.2

THE EXECUTIVE DEBUGGING TOOL

An interactive debugging tool aids in debugging Executive modules, I/O
drivers, and
interrupt service routines.
This debugging aid, called
XDT, is a version of RSX-ll ODT.
Including XDT in a system with
Executive data space support does not reduce the size of pool space
that the system can have.
XDT occupies physical address space but
does not take up any Executive virtual data address space.
XDT also
does not interfere with user-level RSX-ll ODT, which can be used with
any number of tasks while you are debugging your driver with XDT.
You can include XDT in a system during the "Choosing Executive
Options"
section of system generation when the following question is
asked:
Do You Want To Include XDT?

[YIN D:N]
6-1

DEBUGGING A UfER-SUPPLIED DRIVER
If you answer Y, XDT is linked into the Executive image when you build
the Executive.

6.2.1

XDT Commands

XDT commands are generally compatible with RSX-ll ODT commands, which
are described
in the IASjRSX-ll ODT Reference Manual.
That manual,
together with the discussion in Section 6.2 in this manual,
can be
used as a guide to XDT operation on RSX-llM-PLUS.
XDT does not contain the following commands available in ODT:
No $M

- (Mask) register

No $X -

(En try Flag)

registers

No $V -

(SST vector)

registers

No $D -

(I/O LUN)

No $E

registers

- (SST data) registers

No $W -

(Directive status word)

$DSW word

No E

- (Effective Address Search) command

No F

- (Fill Memory) command

No N

- (Not word search) command

No V

- (Resto re SST vectors) command

No W

- (Memory word search) command

In addi':ion, the X (Exit) ODT command has been changed for XDT.
command causes a jump to the crash dump routine.

The X

Except:or the omitted features and the change in the X command,
XDT
is comnand-compatible with RSX-ll ODT;
consequently, the IASjRSX-ll
ODT Reference Manual can be used as a guide to XDT operation.
XDT includes
referencing.
referencing:

both
Instruction space
The
following
commands

and
Data
control
the

sets address references to Instruction space

sets address references to Data space

When XD'J' starts up, the default condition is that
are to [lata space.

6.2.2

space
address
current address

address

references

>DT Start Up

When YOL bootstrap a system that
includes XDT,
the normal
system
startup transfers control
to XDT,
which
identifies itself at the
system console terminal with the following messag~:
XDT:

6-2

DEBUGGING A USER-SUPPLIED DRIVER
If no errors were encountered, the identification message is
by the prompt:

followed

XDT>
The following are the register conditions when XDT starts:
RO
Rl
R2
R3
R4
R5

CSR address of the bootstrap device
LBN of the system image
LBN of the system image
physical unit number of the load device
ASCII name of the load device
total number of blocks read from the system image

XDT runs entirely at priority level 7.
You can set breakpoints at this time,
and
then give a G command,
passing
control
to
the
Executive
initialization module
INITL.
Whenever control reaches a breakpoint, a printout similar to
that of
RSX-ll ODT occurs.
If INITL encounters an error condition, it prints an error message
preceded by a
prefix telling whether the condition is a warning or
fatal.
If the condition is a warning, XDT has control.
You can set
breakpoints to establish control or type the P command to proceed.
If
the condition is fatal, the processor halts.
You must correct the
condition before you can rebootstrap your system.

6.2.3

XDT Restrictions

On some types of systems, the following restrictions exist on the
of XDT when it is first entered:
1.

use

All systems
Some data structures are not yet initialized.
The secondary
pool
is not
set up and
the console terminal
and
the
bootstrapped device are not on-line.

Systems with Kernel data space support
Data space mapping is not yet
set up.
Certain Executive
locations that
the
Task Builder could not resolve are not
initialized.
(The RH common interrupt table address ($RHTBX)
does not contain the
RH common interrupt routine address
($RHALT) .)

To proceed when you encounter such restrictions on your system, at the
initial XDT prompt you should first set a breakpoint near the end of
the INITL module (after the routine that sets up the data structures).
Then, after you proceed and XDT encounters the breakpoint near the end
of INITL, use XDT to examine locations in the
Executive and
to
set
more Executive breakpoints.
On a multiprocessor system, you
conditions:

should

aware

the

following

When you initially place a processor on-line,
prompt
from
that
processor unless you
processor's bit in the $XDTPR word.

XDT does not handle multiprocessor-specific conditions.
You
cannot set processor-specific breakpoints nor can you easily
examine other processors' low memory context.
6-3

XDT does
have set

not
the

DEBUGGING A USER-SUPPLIED DRIVER

G.2.4

Under certain circumstances (such as when Data space is not yet
set up), setting a breakpoint in shared Instruction space may
eventually cause a trap on a processor other than the one on
which you set the breakpoint.
Consequently, because the
processor encountering the breakpoint does not have that
breakpoint in its XDT tables, XDT generates a breakpoint error
message (BE:) rather than a breakpoint message.

All processors are locked out of the Executive
being executed by one of the other processors.

while

XDT

XDT General Operation

A forCEd entry to XDT can be executed at any time from a privileged
termincl by means of the MCR Breakpoint (BRK) command. Thus, if your
system has no XDT restrictions as described in Section 6.2.3, the
normal procedure is to type G when the system is bootstrapped without
settin~ any breakpoints.
When it becomes necessary to use XDT, the
MeR Breakpoint command is executed, causing a forced breakpoint. XDT
then prints on the console terminal:
BE :xxxxxx
This mEssage is followed by the prompt:
XIT>
You car then set breakpoints and issue other XDT commands.
system operation by typing the Proceed (P) command to XDT.

Continue

All XD1 command I/O goes to and from the console terminal, and the
List MEmory (L) command can list on either the console terminal or the
line printer.

6.2.5

XDT and Debugging a User-Supplied Driver

Using IDT to debug a loadable driver has
problen that can arise is a T-bit error:

special

pitfalls.

One

TF:xxxxxx
X[T>
This error results when control reaches a breakpoint that you have
set, Lsing XDT, in a loaded driver. The T-bit error, rather than the
expected BE: error, occurs unless register APR5 is mapped to the
driver at the time XDT sets the breakpoint.
To avoid this T-bit error, assemble the driver with an embedded BPT
instruction, or use either the ZAP utility or the MCR OPEN function to
set the breakpoint by replacing a word of code with the BPT
instruction.
You can use the OPEN command in the following way to
access the driver:
>CPE nnnn/DRV=xx:
where nnnn matches the address in the driver map listing and xx is the
device mnemonic.
(Write down the instruction that you replace with
the BP'I ins t r uc t ion. )

6-4

DEBUGGING A USER-SUPPLIED DRIVER
When control reaches a breakpoint set in the driver, XDT prints:
BE:xxxxxx
XDT>
Recover as follows:
1.

Using XDT, replace
instruction.

the

Decrement the PC
register R7.

Then proceed by using the P or S commands.

BPT

instruction

with

the

contents

subtracting

from

desired
of

NOTE
You should not set breakpoints
in more
than one module that maps
into
the
Executive through APR 5 or APR 6.
In
particular,
do not set breakpoints in
more than one loadable driver at a
time
or
XDT will overwrite words of main
memory when it attempts to restore what
it considers to be the contents of
breakpoints.

6.3

FAULT ISOLATION

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

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

that

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

The system software itself has faulted.

The host hardware has faulted.

way

causes
that

When the system faults, you must first decide which of these
four
causes is responsible.
This section presents some procedures that can
help you isolate the source of the fault.
Correcting the fault itself
is your responsibility.

6.3.1

Immediate Servicing

Faults manifest themselves in four ways (they are listed here in order
of increasing difficulty of isolation):
1.

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

The system displays text indicating a crash has occurred
halts.

The system halts but displays nothing.

The system is in an unintended loop.

6-5

and

DEBUGGING A USER-SUPPLIED DRIVER
The following discussions assume the existence of a system built
at lea~t one debugging aid.

with

The immediate aim, regardless of the fault manifestation, is to get to
the point where you can obtain pertinent fault isolation data.

6.3.1.1 The System Traps to XDT - The trap mayor may not be intended
(for example,
a previously set breakpoint).
If it is not intended,
type the X command, causing XDT to exit to location 40(8), from which
the cr,A support routine will be invoked.
If, however, you have some
idea of the source of the problem
(for example, a
recent coding
change), then you may use XDT to examine pertinent data structures and
code.

6.3.l.~
The System Reports a Crash - If the text displayed on the
consolE
terminal consists of output from the CDA support routine,
follow the procedure for obtaining and formatting a memory dump as
outlinEd in the RSX-llM/M-PLUS Crash Dump Analyzer Reference Manual.

6.3.1.: The System Halts but Displays No Information - Before taking
any action, preserve the current PS and PC and the pertinent device
registers (that is, examine and record the information these registers
contai~) •
The procedure depends on the particular PDP-II processor.
Consult the appropriate PDP-II processor handbook for details.
After·~reserving

the PS and PC, invoke your
resident debugging aid:
enter 40(8)
in the switch register, press LOAD ADDR, and then press
START.
The contents of 40(8) cause the invocation of the CDA support
routine.

6.3.1.4

The System Is in an Unintended Loop - Proceed as follows:

Halt the processor.

Record the PC, the PS, and any pertinent device registers, as
in Section 6.3.1.3.

You may then want to step through a number of instructions in an
attempt
to locate the loop.
For this attempt to be meaningful you
must first disable the system clock.
Proceed as follows:
1.

Examine the contents of word 777546 (if your system has a
line-frequency clock)
or word 772540 (if your system has a
programmable clock).

Clear bit 6 in this word and redeposit the word.
NOTE
Until you reenable the clock,
some
system operations do not work because
they are waiting for time.
You can type
and the system echoes typed characters.
You can input MCR commands.

6-6

DEBUGGING A USER-SUPPLIED DRIVER
After trying to locate the loop and reenabling the clock, transfer
location 40(8) as in Section 6.3.1.3.

6.3.2

Pertinent Fault Isolation Data

Before you attempt to locate the fault, you should dump system common
SYSCM contains a number of critical pointers and listheads.
(SYSCM) •
CDA always dumps the SYSCM area.
In addition, you should dump the
dynamic storage region (system pool and, if it exists, the ICB pool)
and the device tables.
The device tables are in the module SYSTB.
At this point, you have the following data:

• PS
• PC
• The stack
• RO through R6
• Pertinent device registers
• The dynamic storage region
• The device tables
• System common
These data represent a minimal requirement for effectively tracing the
fault.

6. 4

TR1\C ING FAULTS

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

These pointers

$STKDP - Stack Depth Indicator
This data item indicates which stack was being used at the time
of the crash.
$STKDP plays an important role in determining the
origin of a fault.
The following values apply:
+1 -- User (task-state) stack or a privileged task
state

user

o or less -- System stack
If the stack depth is +1, then the user has crashed 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 (Pool-Resident)
The task header and its associated pointers are described below.
The location of the task header and the contents of its associated
pointers vary according to whether the task has an external header.
A

6-7

DEBUGGING A USER-SUPPLIED DRIVER

task with an external header has its header attached in a physically
contiguous and numerically lower location in memory. A task with a
nonexternal header has its header located in Executive pool space.
TherefJre, a header in Executive pool is a pool-resident header, and a
header adjacent to the task is a non-pool-resident header.
Figure 6-1 shows the interaction of header pointers for
both
pool-r!sident and non-pool-resident headers. For a pool-resident task
header, $HEADR, $SAHPT, and $SAVSP all point to the first word of the
task neader.
This word also contains the user task's stack pointer
(SP) f~om the last time it was saved.
Figure 6-2 shows a brief
descri:)tion of the task header. The task header is fully described in
the RS;(-llM/M-PLUS Task Bui Ider Manual.
POOL-RESIDENT TASK HEADER (Non-external)

$HEADR

$SAVSP

I
J

$SAHPT

I
J

Virtua I Hea d er Add r.

I
Current Task
Header

Saved Stack Addr.

Virtual Header Addr.

I--

THDlN

$SAHDB

undefined value

Saved Stack POinter
0

I
NON-POOL-RESIDENT TASK HEADER (External)
Task

$SAHPT

140000
Current Task
Header

$HEADR

Executive
Data Area
1-word block

$SAVSP

T.HDlN 0

Executive
$SAHDB

KISAR6

Figure 6-1:

Address resolution

Interaction of Task Header Pointers

The header (as pointed to by $HEADR)
also contains the last-saved
register set, just before the header guard word (the last word in the
header -- pointed to by H.GARD).
The four pointers associated with the header are:
•

$HEADR

•

$SAVSP

•

$SAHPT

•

$SAHDB

6-8

DEBUGGING A USER-SUPPLIED DRIVER

f4--

..
R5

H.NLUN

N
f--

H.GARD

H.HDLN

Length in bytes

SP
ZK-272-81

Figure 6-2:
The pointers associated with
next:

Task Header

pool-resident

header

are

described

$HEADR - Points to the current task header.
The $HEADR word points to the pool-resident task header of
the task currently running.
The value in $HEADR is a kernel
virtual address in primary pool.
$SAVSP - Points to the first word of the current
contains the saved stack pointer.

task

header,

which

$SAHPT - Points to the current task header in pool.
$SAHPT contains
the virtual address of the header.
$SAHPT and $HEADR contain
the same virtual address for a pool-resident header.
$SAHDB - Contains an unknown value.
The pointers associated with a non-pool-resident header are
next:

described

$HEADR - Points to the pointer for the saved stack pointer, $SAVSP.
$SAVSP - Points to a 4-word block in the Executive data area.
$SAHPT - Contains the octal value of 140000 that is to be used with
$SAHDB to resolve the address of the task's header.
$SAHPT
always contains 140000 in this case.

6-9

DEBUGGING A USER-SUPPLIED DRIVER
$SAHDB - Contains the value in KISAR6, which is a 32-word block-offset
to be used with the value in $SAHPT to resolve the address of
the task's header.

6.4.1

Tracing Faults Using the Executive Stack and Register Dump

To trace a fault after a display of the Executive stack and
register
contents,
first examine the system stack pointer.
Usually an
Executive failure is the result of an SST-type trap within the
Executive.
If an SST does occur within the Executive, then the origin
of the calIon the crash-reporting
routine is in the SST service
module.
(The crash call
is initiated by issuing an lOT at a stack
depth of zero or less.)
A call to crash also occurs in the Directive Dispatcher when an EMT is
issued at a
stack depth of zero or less, or a trap instruction is
executed at a stack depth of less than zero.
The stack structure in
the case of an internal SST fault is shown in Figure 6-3.

PS
PC
R5
R4
R3

R2
Rl
RO
Return to system exit
Zero or more SST parameters
SST fault code

......t - - - - - - - - SP

Number of bytes

ZK-273-81

Figure 6-3:

Stack Structure:

Internal SST Fault

The fault codes are:

o
2
4
6
1('
l~:

It,
1 ~\

20
22

;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

6-10

DEBUGGING A USER-SUPPLIED DRIVER
26
30
32
34

;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 that caused the SST
failure.
The number of bytes is the number normally transferred to
the user stack when the particular type of SST occurs.
If the number
is 4, then a non-normal SST fault occurred, and only the PS and PC are
transferred.
There are no SST parameters.
If the failure is detected in $DRDSP, the stack is the same as that
shown
in Figure 6-3, except that the number of bytes, the SST fault
code (the fault codes are listed above), and the SST parameters are
not present.
One SST-type failure, stack underflow, does not result in the stack
structure of Figure 6-3.
To determine where the crash occurred, first
establish the stack structure;
this can be deduced by the value of
the SP and the contents of the top word on the stack.
If the stack
structure is that of Figure 6-3, then the failure occurred in $DRDSP,
or was a normal SST crash.
If the stack structure is that of Figure
6-4, then an abnormal SST crash has occurred.
~.~-----------SP

PS
PC
ZK-274-81

Figure 6-4:

Stack Structure:

Abnormal SST Fault

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

6.4.2

Tracing Faults When the Processor Halts Without Display

To trace a fault when the processor halts but displays no information,
first examine $STKDP, $TKTCB, $HEADR, $SAVSP, $SAHPT and $SAHDB.
The
difficulty in tracing failures in this case is that the system stack
is not directly associated with the cause of a failure.
By examining $STKDP, you can determine the system state at the time of
failure.
If
it was in user state, the next step is to examine the
user's stack.
The examination focuses on scanning the stack for
addresses that may be subroutine links that can ultimately lead toa
thread of events isolating the fault.
This is essentially the aim of
looking at the system stack if $STKDP is zero or less.

6-11

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

~- - - - - - - 40-~-o-o- - - - - - - ~1 ~:~-----------::
Figure 6-5:

Stack Structure:

Data Items on Stack

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

6.4.3

Tracing Faults After an Unintended Loop

To trace a fault when an unintended loop has occurred, first halt
processJr.

the

After YJu halt the processor, the same state exists as was discussed
in Section 6.4.2.
Follow the same tracing procedure described there.
A specific suggestion is to check for a stack overflow loop.
Patterns
of dat3 successively duplicated on the stack indicate a stack looping
failure.

6.4.4

~dditional

Hints for Tracing Faults

Another item to check is the current (or last) I/O Packet, the address
of whi~h
is
found in S.PKT of the SCB.
The packet function (I.FCN)
defines the last activity performed on the unit.
If trou)le occurred in terminating an
I/O request,
a
scan of the
system dynamic memory region may provide some insight.
This region
starts It the address contained in $CRAVL, a cell in SYSCM.
Because
all
1/:) packets are built in system dynamic memory, their memory is
returne<3 to the dynamic memory region when
they are successfully
termina:ed.
Following
the link pointers in this region may reveal
whether I/O completion proceeded to that point.
In systems with QIO
optimiz.ltion,
$PKAVL
(SYSCM)
points to
a list of I/O packet-sized
blocks I)f dynamic memory that are not linked into the $CRAVL chain.
6-12

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

6.5

REBUILDING AND REINCORPORATING A LOADABLE DRIVER

After correcting and assembling the driver source and updating the
Executive object library, simply unload the old version, using the MeR
command UNLOAD, task build the new one, and load
it using the LOAD
command.
The commands for the assembler, Librarian, and Task Builder
are shown in Section 5.2.
Once loaded, the data base is not removed by the UNLOAD command.
If
the data base is in error and cannot be patched, correct its source,
reassemble it, update the
Executive object library RSXllM.OLB and
build
the new driver task.
Then bootstrap the system before loading
the driver task image containing the corrected data base.

6-13

CHAPTER 7
EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

Because a driver is mapped within the Executive address space, it can
call Executive routines on the same basis as that of any other module
in the Executive.
The driver must observe the
protocol
and
conventions
established on the system.
The following sections
summarize the conventions, describe the address double word, tell what
special processing is required for NPR devices attached to a PDP~ll
processor with extended memory support
(22-bit addressing), and
summarize some of the typical Executive services available.

7.1

SYSTEM-STATE REGISTER CONVENTIONS

In system state, R5 and R4 are, by convention, nonvolatile registers.
This means that an internally called routine is required to save and
restore these two registers if the routine destroys their contents.
R3,
R2, Rl, and RO are volatile registers and may be used by a called
routine without save and restore responsibilities.
When a driver is entered directly from
at interrupt level, not at system
register the driver uses must be saved
code to preserve R5 and R4 for the
follow these conventions.

an interrupt, it is operating
state. At interrupt level, any
and restored.
INTSV$ generates
driver's use. All drivers must

See the description of the driver dispatch table in
the contents of registers when a driver is entered.

7.2

Section

4.5

for

THE ADDRESS DOUBLE WORD

RSX-IIM-PLUS can accommodate configurations whose maximum physical
memory is 2048K words.
Individual tasks, however, are limited to 32K
words.
The addressing is accomplished by using virtual addresses and
memory
mapping hardware.
I/O transfers, however,
use physical
addresses 18 bits in length.
Since the PDP-II word size is 16 bits,
some scheme is necessary to represent an address internally until it
is actually used in an I/O operation.
The choice was made to encode
two words as the internal representation of a physical address and to
transform virtual addresses for
I/O operations into the internal
doubleword format.
On receipt of a QIO directive, the buffer address in the Directive
Parameter Block, which contains a task virtual address, is converted
to address doubleword format.

7-1

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER
The virtual address in the DPB is structured as follows:
Fits 0 through 5

Displacement in terms of 32-word blocks

Eits 6 through 12

Block number

Fits 13 through 15

Page Address Register Number (PARi)

The internal
address into
paragraphs.

virtual
RSX-IIM-PLUS translation restructures this
an address doubleword as described in the following

The relocation base contained in the PAR specified by the PAR number
in the virtual address in the DPB is added to the block number in the
virtual address. The result becomes the first word of the address
doubleword.
It represents the nth 32-word block in a memory viewed as
a collection of 32-word blocks. Note that at the time the address
doubleword is computed, the user's task issuing the QIO directive is
mapped by the processor's memory man~gement registers.
The se:ond word is formed by placing the displacement in block (bits 0
5 of virtual address) into bits 0 through 5. The block number
field was accommodated in the first word and bits 6 through 12 are
cleareJ.
Finally, a 6 is placed in bits 13 through 15 to enable use
of PAR #6, which the Executive uses to service I/O for program
transf~r devices.
throug~

For n01processor request (NPR) devices, the driver requirements for
manipulating the address doubleword are direct and are discussed with
the de3cription of U.BUF in Section 4.4.4.

7.3

DRIVERS FOR NPR DEVICES USING EXTENDED MEMORY

SpeciaL features must be built into drivers for non-MASSBUS NPR
(nonprncessor request)
devices attached to a PDP-II processor with
extend,~d-memory support (22-bit addressing).
Non-Exl:ended memory NPR devices on the PDP-II processor must perform
I/O transfers by using UNIBUS Mapping Registers (UMRs) as described in
the PDP-II Processor Handbook. One UMR is required for each 4K words
invo~ur--in
the transfer -- as specified by the contents of U.CNT in
the UCH. When multiple UMRs are required for a transfer, they must be
contiguous.
A drivf'r can be assigned UMRs through anyone of three procedures:
~.

Dynamically allocating UMRs for
transfer, or

the

duration

Dynamically allocating UMRs for longer periods of time, or

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

7-2

the

data

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER
7.3.1

Calling $STMAP and $MPUBM or $STMPI and $MPUBI

To obtain UMRs through use of the $STMAP and $MPUBM or the $STMPI
$MPUBI routines, a driver must:

and

•

Have available six words for
a mapping
register assignment
block in the
22-bit working storage area of the device's
controller request block (KRB).
The end of this area
is
accessed by adding
the contents of K.OFF to the address at
K.CSR.
If the driver uses $STMPI and $MPUBl,
it must also
have available a lO-word block

•

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

•

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

UNIBUS

These requirements are detailed in the
Note that these routines are only
performing a data transfer.

(Map

UNIBUS
to

Mapping
Memory)

following
three sUbsections.
required when the driver is

7.3.1.1 Allocating a Mapping Register Assignment Block - The
controller request block
(KRB)
of an NPR device requires a 6-word
mapping register assignment block located
in the
22-bit working
storage area.
It does not have to be initialized.
Any initial
contents are simply overwritten.
The following example shows
assignment block.
.BLKW

M.LGTH

the

allocation

mapping

;UMR WORK AREA

If the driver does not support parallel NPR operations requiring
UMR
mapping,
it calls $STMAP and $MPUBM.
If the driver supports parallel
NPR operations requiring UMR mapping, it must call $STMPI and $MPUBI.
In the latter situation,
the six additional words in the 22-bit
working storage area are not used but must still be present.
In
addit.ion, the driver data base must provide a lO-word mapping register
assignment block for each data transfer to be mapped as specified
in
the description of $STMPI later in Section 7.4.31.

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

7.3.1.3 Calling $MPUBM or $MPUBI - Before executing the transfer, the
driver must call $MPUBM or $MPUBI.
These routines get the buffer's

7-3

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER
22-bit physical address and load the UNIBUS mapping registers so that
transfE'rs are mapped directly to the task's space. The call to $MPUBM
or $MPUBI must be conditionalized on M$$EXT.
If the driver calls $STMAP and $MPUBM, the UMRs allocated to
it are
deallocated during the call to $IODON or $IOALT.
If the driver calls
$STMPI and $MPUBl, it must call $DEUMR to deallocate any allocated
UMRs bE~fore calling $IODON or $IOALT.

7.3.2

Calling $ASUMR and $DEUMR

Use of the procedure described in Section 7.3.3 assures that UMRs are
always allocated.
However,
a driver may not require UMRs to be
allocated all of the time, and yet require UMRs for periods of time
longer than the normal
time-frame between $GTPKT and $IODON (or
$IOALT).
In such cases, there is a third procedure for allocating
UMRs.
Through use of the Executive routines $ASUMR and $DEUMR, a driver can
dynamically allocate, retain over a desired time-frame, and deallocate
UMRs.
Refer to Section 7.4 for descriptions of the $ASUMR and $DEUMR
routines.
Similar to the $STMAP/$MPUBM procedure, the use of $ASUMR and $DEUMR
also l-equires the allocation of a 6-word mapping register assignment
block.
In this instance, however, the block must not be located in
the 2:~-bit working storage area.
$IODON or $IOALT, when called, will
attempt to deallocate the UMRs of a block found in the 22-bit working
storage area.
To avoid this deallocation,
the mapping register
assignment block could be dynamically allocated from the pool.
Figure
7-1 details the format of the 6-word block.

M.LNK

Link Word

M.UMRA

Address of first assigned UMR

M.UMRN

Number of assigned UMRs *4

M.UMVL

Low 16 bits mapped by first assigned UM R

M.UMVH
M.BFVH
M.BFVL

High 6 bits of
physical buffer address

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

Low 16 bits of physical buffer address
ZK-276-81

Figure 7-1:

7.3.3

Mapping Register Assignment Block

Statically Allocating UMRs During System Generation

UMRs cC:ln be statically assigned during system generation.
The system
generation procedure defines the symbol N$$UMR equal to a fixed number
of UMRE, multiplied by 4, that are statically assigned to the system.
Before assembling the Executive,
the user can cause the static
allocation of an additional number of UMRs by editing the Executive
assembly prefix file RSXMC.MAC.
The value of the symbol N$$UMR can
then b~ increased to represent the additional number of desired UMRs
multiplied by 4.

7-4

EXECUTIVE 'SERVICES AVAILABLE TO AN I/O DRIVER
The Ex~~cutive assembly prefix file RSXMC.MAC further defines the
following
three symbols, which describe the first UMR statically
allocated during system generation:
U~S$MRN

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

UMR

reg ister

U:S$MLO

The low-order 16 bits
mapped by this UMR

UNIBUS

address

U~S$MHI

The high-order 2 bits of the 18-bit UNIBUS
these 2 bits are in bit positions 4 and 5

address;

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

7.4

the

18-bit

system

itself.

They

are

SERVICE CALLS

This s~~ction contains general commentary on the Executive routines
typically used by I/O drivers.
The descriptions of the routines are
taken from the source code of modules linked to form the Executive.
Table 7-1 summarizes the routines described in this section.
Only the
most widely used routines are described;
however, many
other
Executive services are available.
The source code for the related
routines is in the MACRO-II source files for the Executive modules.
Table 7-1
Summary of Executive Service Calls for Drivers
Ro ut i ne
Name

Location in
UFD [11,10]

Function

$ACHKB
$ACHCK
$ALOCB
$ASUMR
$BLKCK
$BLKCl
$BLKC2
$BLXIO
$CIKBFI
$CKBFR
$CKBFW
$CKBFB
$CLINS
$CVLBN
$DgACB
$DEUMR
$DVMSG
$FORK
$FORKI
$G'rBYT
$G'rPKT
$GSPKT

EXSUB
EXSUB
CORAL
MEMAP
MDSUB
MDSUB
MDSUB
BFCTL
EXESB
EXESB
EXESB
EXESB
QUEUE
MDSUB
CORAL
MEMAP
IOSUB
SYSXT
SYSXT
BFCTL
IOSUB
IOSUB
BFCTL
IOSUB
SYSXT
SYSXT

Adress check for byte-aligned buffers
Address check for word-aligned buffers
Alocate core buffer
Assign UNIBUS mapping registers
Check logical block number
Check logical block number
Check logical block number
Move block of data
Check I/O buffer
Check I/O buffer
Check I/O buffer
Check I/O buffer
Clock queue insertion
Convert logical block number
Deallocate core buffer
Deassign UNIBUS mapping registers
Device message output
Create a fork process
Fork but bypass clearing timeout count
Get byte
Get an I/O packet
Get a special I/O packet
Get wo rd
Initiate I/O buffering
Interrupt save and restore
Interrupt exit

$G'r\~RD

$INIBF
$INTSV
$INTXT

(continued on next page)

7-5

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER
Table 7-1
(Cont.)
Summary of Executive Service Calls for Drivers
ROltine
N~me

Location in
UFD [11,10]

$IJALT
$IJDON
$ I )F IN
$M »UBM
$M ?UBI

IOSUB
IOSUB
IOSUB
MEMAP
MEMAP

$prBYT
$p'rWRD
$Q[NSP
$R ~LOC

$S'rMAP
$S'rMPl

BFCTL
BFCTL
QUEUE
MEMAP
MEMAP
IOSUB
IOSUB
MEMAP
MEMAP

$T::;PAR

REQSB

$T;,)TBF

IOSUB

$R~LOP
$R~QUE
$R ~QU 1

Function
Alternate entry to $IODON
I/O done for completing an I/O request
I/O finish for special I/O completion
Map UNIBUS memory
Alternate $MPUBM entry for parallel
operations
Put byte
Put word
Queue insertion by priority
Relocate address
Relocate UNIBUS physical address
Queue kernel AST to task
Queue kernel AST to task
Set up UNIBUS mapping address
Alternate $STMAP entry for parallel
operations
Test if partition memory resident
for kernel AST
Test for I/O buffering

7-6

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$ACHKB
$ACHCK
7.4.1

Address Check

These routines are in the
file
IOSUB.
A driver can call either
routine to address-check a task buffer while the task is the current
task.
The Address Check routines are normally used only by drivers
setting UC.QUE in U.CTL.
See Section 8.3 for an example.
Call1ng Sequences:
CALL

$ACHKB

CALL

$ACHCK

Description:
i+

**-$ACHKB-ADDRESS CHECK BYTE ALIGNED
**-$ACHCK-ADDRESS CHECK WORD ALIGNED
'rHIS ROUTINE IS CALLED TO ADDRESS CHECK A BLOCK OF MEMORY TO SEE WHETHER
IT LIES WITHIN THE ADDRESS SPACE OF THE CURRENT TASK.
INPUTS:
RO=STARTING ADDRESS OF THE BLOCK TO BE CHECKED.
Rl=LENGTH OF THE BLOCK TO BE CHECKED IN BYTES.
OUTPUTS:
C=l IF ADDRESS CHECK FAILED.
C=O IF ADDRESS CHECK SUCCEEDED.
R2=ADDRESS OF WINDOW BLOCK MAPPING BUFFER
(FOR PRIV TASKS SEE NOTE.)
RO AND R3 ARE PRESERVED ACROSS CALL.
NOTE:

SINCE PRIVILEGED TASK I/O BUFFERS ARE NOT ADDRESS
CHECKED, R2 ALWAYS RETURNS A POINTER TO THE FIRST
WINDOW BLOCK. CHECKPOINTING AND SHUFFLING OF COMMONS
WILL STILL WORK PROPERLY PROVIDED THAT A PRIVILEGED
TASK NEVER SPECIFIES AN I/O INTO A COMMON WHICH IT
ALLOWS TO REMAIN CHECKPOINTABLE AND SHUFFLEABLE.

Notes:
In RSX-IIM-PLUS Version 2.0, almost all drivers will wish to use
the alternate routines $CKBFB/$CKBFW which correctly maintain the
attachment and partition I/O count mechanism
in addition to
address checking the user buffer.
If the driver completes all
references to the buffer in the
initiation routine
(that is,
fills the buffer and calls $IOFIN,
rather than queueing the
packet and/or starting a
transfer which
is completed
via
interrupt service)
then it is permissible to use $ACHKB/$ACHCK.
See Section 7.4.6 for a description of $CKBFB/$CKBFW and Section
8.3 for an example.

7-7

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$ALOCB
7.4.2

Allocate Core Buffer

This routine is in the file CORAL.
CallinJ Sequences:
CA.LL $ALOCB
or
CALL $ALOCI
Description:
:+
J
J

• • -SALOCB-ALLOCATE CORE BuFFER
**-SALOC1-ALLOCATE CORE BUFFE~ (ALTERNATE ENTRV)

THIS ROuTINE IS CALLED TO ALLOCATE AN ExEC CORE BUFFER. TH~ ALLOCATION
ALGORITHM IS FIRST FIT A~D BLOCKS ARE ALLOCATED IN MULTIPLES OF FOUR
BYTES.
INPUTSz
R~=ADDRtSS OF CORE ALLOCATION LISTHEAD-2 IF ENTRY AT SALOC1.
Rl=SIZE OF THE CORE BUFFER TO ALLOCATE IN BVTEa.

OUTPUTS.

,--

C;1 IF INSUFFICIENT CORE IS AVAILABLE TO ALLOCATE THE BLOCK.
C=0 IF THE BLOCK IS ALLOCATED.
R~=ADDRESS OF THE ALLOCATED BLOCK,
Rl=LENGTH OF BLOCK ALLOCATED

7-8

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$ASUMR
7.4.3

Assign UNIBUS Mapping Registers

This routine is in the file MEMAP.
It is used only for PDP-ll/70 NPR
devices
requlrlng
UNIBUS Mapping Registers when 22-bit memory
addressing is enabled. Normally, it is not called directly by an I/O
driver.
Rather,
it is called from within the $STMAP routine. Refer
to Section 7.3 for a discussion.
Calling Sequence:
CALL $ASUMR
Description:
;

.
**.$A5UMR.ASSIG~

UNIBUS

~APPING

R~GISTERS

TMIS ROUTINE IS CALLED TO ASSIGN A CONTIGUOUS SET OF UMR'S, NOTE THAT
FOR TME SAKE OF SPEED, TME LINK ~ORD OF EACM MAPPING ASSIGNMENT BLOCK
POINTS TO TME UMR ADD~ESS (2ND) ~ORD OF TME BLOCK, NOT TME FIRST wORD,
THE CURRENT STATE OF UMR ASSIGNMENT IS REPRESENTED BY A LINKED LIST OF
MAPPI~G ASSIGN~tNT BLOCKS, EACH BLOCK CONTAINING THE ADDRESS OF THE
FIRST u~~ ASSIGNED AND TME NUMB~R OF UM~'S ASSIGNED TIMES~. TME
6LOCKS ARE LINKED IN THE ORDE~ OF INCREASI~G FIRST UMH ADDRESS.
I"oPUTSs
R~=POINTER

TO A ~APPI~G REGISTEk ASSIGNMENT BLOCK.

~.U~R~(R0):~U~RER

UM~'S

~EQuIRED

* ~.

OUTPuTS:
ALL REGISTERS ARE PRf.SERVtD.
IF THE U~~'S wEkE SuCCESS~0LLV ASSIGN~D.
ALL FIELDS OF THE MAPPI~G HEGISTER ASSIGNMENT BLOCK
ARE I~ITIALIZ£D AND TME BLOCK IS LINKED I~TO
TME ASSIGN~ENT LIST.
C:l I~ T~E ~~~'S C00LD ~OT BE ASSIG~ED.
C=~

7-9

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$BLKCK
$BLKC1
$BLKC2
7.4.4

Check Logical Block

This routine is in the file MDSUB. The output from this routine is
used by disk drivers as input to the $CVLBN routine to handle logical
block numbers in data transfers.
Callirg Sequence:
CALL

$BLKCK

CALL

$BLKC2

Descri?tion:

;+
**-$BLKCK-LOGICAL BLOCK CHECK ROUTINE
**-$BLKCI-LOGICAL BLOCK CHECK ROUTINE (ALTERNATE ENTRY)
**-$BLKC2-LOGICAL BLOCK CHECK ROUTINE (ALTERNATE ENTRY FOR QUEUE OPT)
THIS ROUTINE IS CALLED BY I/O DEVICE DRIVERS TO CHECK THE STARTING
AND ENDING LOGICAL BLOCK NUMBERS OF AN I/O TRANSFER TO A FILE
STRUCTURED DEVICE. IF THE RANGE OF BLOCKS IS NOT LEGAL, THEN $IODON
IS ENTERED WITH A FINAL STATUS OF "IE.BLK" AND A RETURN TO THE
DRIVER'S INITIATOR ENTRY POINT IS EXECUTED. ELSE A RETURN TO THE
DRIVER IS EXECUTED.
$BLKC2 RETURNS TO $QOPDN IN $DRQRQ IF THERE IS AN ERROR INSTEAD OF
THE DRIVER'S INITIATOR ENTRY POINT.
THIS ALLOWS THE QUEUE
OPTIMIZATION CODE TO USE BLKCK
INPUTS:
Rl=ADDRESS OF I/O PACKET.
R5=ADDRESS OF THE UCB.
OUTPUTS:
IF THE CHECK FAILS, THEN $IODON IS ENTERED WITH A FINAL STATUS
OF "IE.BLK" AND A RETURN TO THE DRIVER'S INITIATOR ENTRY POINT
IS EXECUTED.
IF THE CHECK SUCCEEDS, THEN THE FOLLOWING REGISTERS ARE RETURNED
RO=LOW PART OF LOGICAL BLOCK NUMBER.
Rl=POINTS TO I.PRM+12 (LOW PART OF USER LBN)
R2=HIGH PART OF LOGICAL BLOCK NUMBER.
R3=ADDRESS OF I/O PACKET.

7-10

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$BLXIO
Move Block of Data

7.4.5

This routine is in file BFCTL.
Calling Sequence:
CALL

$BLXIO

Description:
;+
**-$BLXIO-MOVE BLOCK OF DATA.
'rHIS ROUTINE IS CALLED TO MOVE DATA IN MEMORY IN A MAPPED SYSTEM.
INPUTS:
RO=NUMBER OF BYTES TO MOVE.
Rl=SOURCE APR5 BIAS.
R2=SOURCE DISPLACEMENT.
R3=DESTINATION APR6 BIAS.
R4=DESTINATION DISPLACEMENT.
OUTPUTS:
DESCRIBED MOVE IS ACCOMPLISHED.
RO ALTERED
Rl,R3 PRESERVED
R2,R4 POINT TO LAST BYTE OF SOURCE AND DESTINATION + 1
NOTE:

THE COUNT INPUT IN RO MUST NOT BE ZERO AND IT MUST NOT
BE LARGE ENOUGH TO CROSS APR BOUNDARIES (THIS TYPICALLY
MEANS A MAXIMUM OF 4K-63).

7-11

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$CKBFI
$CKBFR
$CKBFW
$CKBFB
7.4.6

Check I/O Buffer

These

~outines

are in file EXESB.

Callinll Sequences:
C.\LL

$CKBFB (or appropriate entry name)

DescriDtion:
; I-

**-$CKBFI-CHECK
**-$CKBFR-CHECK
**-$CKBFW-CHECK
**-$CKBFB-CHECK

I/O
I/O
I/O
I/O

BUFFER FOR I-SPACE (OVERLAY) ACCESS
BUFFER FOR READ-ONLY (BYTE) ACCESS
BUFFER FOR READ-WRITE (WORD) ACCESS
BUFFER FOR READ-WRITE (BYTE) ACCESS

THESE ROUTINES ARE CALLED TO ADDRESS CHECK AN I/O BUFFER
ASSOCIATED WITH THE CURRENT (UNDER CONSTRUCTION) I/O PACKET.
IF THE ADDRESS CHECK PASSES, THEN AN ATTEMPT IS MADE TO POINT ONE
OF THE ATTACHMENT DESCRIPTOR POINTERS AT THE ASSOCIATED ADB. THIS
WILL HAVE ONE OF THE FOLLOWING OUTCOMES:
1) - THERE IS CURRENTLY NO ATTACHMENT POINTER IN THE PACKET TO THIS
ADB, AND THE POINTERS AREN'T FULL. A POINTER IS FILLED IN AND
THE A.IOC, P.IOC FIELDS FOR THIS I/O ARE INCREMENTED. THIS IS
THE "NORMAL" SUCCESSFUL CASE.
2) - THERE IS ALREADY ONE POINTER TO THIS ADB. THE PACKET IS
UNTOUCHED, AS ARE THE A.IOC AND P.IOC FIELDS, AND THE CHECK
IS CONSIDERED SUCCESSFUL. THE IMPLICATION OF NOT INCREMENTING
A.IOC AND p.roc IS THAT DRIVERS AND ACPS MAY NOT RELEASE
BUFFERS FOR AN I/O REQUEST ONE AT A TIME, I.E. THE DRIVER
SHOULD NOT CALL $DECIO DIRECTLY, BUT SHOULD CALL $IODON OR
$DECAL AFTER ALL BUFFER ACCESS HAS COMPLETED.
3) - THERE ARE ALREADY TWO POINTERS, NONE OF THEM TO THIS ATTACHMENT

DESCRIPTOR. THIS IS CONSIDERED A CHECK FAILURE AND RETURN
IS MADE WITH CARRY SET.
INPUTS:
RO=STARTING ADDRESS OF BLOCK TO BE CHECKED
Rl=LENGTH OF BUFFER TO BE CHECKED
$ATTPT=ADDRESS OF I.AADA IN CURRENT I/O PACKET
HEADER OF THE SUBJECT TASK IS MAPPED THROUGH KISAR6
OUTPUTS:

; ,-

C=O CHECK AND PACKET UPDAT SUCCESSFUL
I.AADA OR I.AADA+2 POINTS TO THE ADB
A.IOC, P.IOC INCREMENTED
C=l CHECK UNSUCCESSFUL OR PACKET COULD NOT BE FILLED IN

7-12

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$CLINS
7.4.7

Clock Queue Insertion

This routine is in the file QUEUE.
Calling Sequence:
CALL

$CLINS

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

; _.

ON MULTIPROCESSOR SYSTEMS, A REQUEST WITH TYPE C.SYSTI100000
WILL BE EXECUTED ON A PRATICULAR UNIBUS RUN, WITH URM
SPECIFIED IN C.URM. TYPE C.CYST REQUESTS ON MP SYSTEMS ARE
DEFAULTED TO RUN ON ANY UNIBUS RUN, WHICH IN PRACTICE WILL
RESULT IN THE REQUEST EXECUTING ON THE CPU WHICH OWNS THE
CLOCK. ($CKURM)

7-13

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$CVLBN
7.4.8

Convert Logical Block Number

This r)utine is in the file MDSUB. The input to this routine is the
same 3S the output from the $BLKCK routine. Typically, a disk driver
calls :his routine to convert a logical block number to a physical
disk 3ddress.
The routine accesses the U.PRM fields in the driver
data b3se unit control block. These fields contain the sector, track,
and c{linder parameters for the type of disk supported. Refer to the
descriJtion of the U.PRM fields in Section 4.4.4.
Callin'l Sequence:
C,\LL

$CVLBN

Descri;>tion:

•• -SCVLBN-CONVERT LOGICAL

BLOC~

NUMBER TO DISK PARAMETERS

THIS SUBROUTINE wILL CONVERT THE SPECIFIED LOGICAL BLOCK NUMBER
TO A SECTOR/TRACK/CYLINDER ADDRESS,
INPUTS.
(SAME AS SBLKCK OUTPUTS)
Re-LOW PART OF LBN
R2-HIG~ PART OF LBN
R3=I/O PACKET ADDRESS
R5=UCB ADDRESS
OUTPUTS.

R0-SECTOR NUto1BER
Rt-TRACK ~UMBER
R2=CYLINDER NU~BER

7-14

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$DEACB
7.4.9

Deallocate Core Buffer

This routine is in the file CORAL.
Calling sequences:
CALL

$DEACB

CALL

$DEACl

Description:

,., .*-SolACB-OEALLOCATE CORE BUFFER
**-SDEAC1-DEALLOCATE CORE BUFFER

(ALTER~ATE

E~TRY)

~OuTI~E IS CALLED TO DEALLOCATE A~ EXEC CORE BUFFER. THE BLOCK IS
INSERTED INTO T~E FREE BLOCK C~AIN BY CORE ADDRESS, IF AN ADJACENT
ALaCK IS CuRRE~TLY FgEE, THEN THE T~U BLOCKS ARE MERGED A~D INSERTED
r IN THE FREE BLOC~ ChAIN.
T~IS

: INPUTS:
R0:ADDRESS OF THE CORE BUFFER TO BE DEALLOCATED.
Rl:SIZE ~F T~E CORE BuFFER "TO DEALLOCATE I~ BYTES.
Q3=ADDRESS OF CORE ALLOCATIO~ LIST~EAD·2 IF ENT~Y AT SDEAC1.
OUTPUTS:

T~E CORE 8LOCK IS ~ERGED INTO
ADDRESS A~n IS AGCQMERATED IF

7-15

TH~ F~EE CO~E CHAIN BY CORE
~ECESSARY ~lT~ ADJACENT BLOCKS.

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$OEUMR
7.4.1(1

Deassign UNIBUS Mapping Registers

This routine is in the file MEMAP.
It is used only for NPR devices
requiring UNIBUS Mapping Registers when 22-bit addressing is enabled.
No r mall y, i t i s not calI ed d ire c t 1 Y by a n I/O d r i ve r • Ra the r ,
i tis
callec from within the $IODON routine. Refer to Section 7.3 for a
discuEsion.
Callirg Sequence:
CALL

$DEUMR

Description:
: .-

* * - \ (') ~ U"1 ~ - I) E ASS 1 G'\0 I)'. 1EI US M 4 P PI'" G ~ £ GIS TE~ S
THIS ~OuTI~E IS CALLED TO nEASSIGN A CO~TIGU00S ~LOCK OF UMR'S. IF
THE MAPPI~G A5SIr.~ME~T BLOCK IS NOT IN THE LIST, NO ACTION IS TAKE~.
NOTE THAT FOR THf SAKE OF ASSIGN~!NT SPEED, THE LINK WORD POINTS TO
THE UM~ ADO~ESS (2~D) ~OQD uF THE ASSIGNMENT BLOCK.
INPUTS:

OUTPUTS,

R0 AND Rl AQE PRESERVED.

7-16

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$DVMSG
7.4.11

Device Message Output

Device Message Output is in file IOSUB.
Calling Sequence:
CALL

$DVMSG

Description:

•• -SDVMSG-DEVICE

~tSSAGE

OUTPUT

THIS POUTINE IS CALLED TO SUB~IT A ~ESSAGE TO THE TASK TERMINATION
NOTIFICATION TASK. ~ESSAGES ARE EITHER DEVICE RELATED OR A CHECKPOINT
~RITE FAILURE F~OM TH~ LOADER.
INPUTS,
R~=MESSAGE NUMBER.
RS8ADDRtSS OF THE UCB OR TCB THAT THE MtSSAGE APPLIES TO.

OUTPUTS,
A FOUR ~OPD PACKET IS ALLOCATED, R0 AND R5 ARE STORED IN THt
SECOND A~D THIRD wORDS RESPECTIvELY, AND THE PACKET IS THREADED
INTO THE TASK TERMINATIO~ NOTIFICATION TASK MESSAGE QUEUE.
NOTEI IF THE TASK TERMINATION NOTIFICATION TASK IS NOT INSTALLED
OR NO STORAGE CAN BE OBTAINED, THEN THE MESSAGE REQUEST
IS IGNORED.

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

#T.NDNR,RQ

MOV
CALL

#T.NDSE,RQ
$DVMSG

7-17

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$FORK
7.4.12

Fork

A driver calls $FORK to switch from a
Fork i; in the file SYSXT.
partially interruptable level (its state following a calIon $INTSV)
to a fIlly interruptable level.
Callinq sequence:
$FORK
De sc r i pt ion:
Jt

**~SFORK.FORK

AND CREATE

THfS ROUTINE IS CA~~ED FROM AN 1/0 DRlv~R TO CREATE A SYSTEM PROCESS THAT
WI~L RETURN TO THE DRIVER AT STACK DEPTH ZERO TO FINISH PROCESSING.

SYSTE~

PROCESS

INPUTS.
R58ADDRESS OF T~E UCB FOR T~E U~IT BEING PROCESSED.
0(SP)=RETURN AODR~SS TO CA~~ER.
2CSP):RETURN ADDRESS TO CA~~ERS CA~LER.
f

OU"PUTS,
REGISTERS R5 AND R~ ARE SAVED IN THE CONTRO~~ER FORK B~OCK AND
A SYSTEM P~OCESS IS CREATED, THE PROCESS IS ~INKEO TO THE FORK
QUEUE AND A JUMP TO SINTXT IS EXECUTED.

Notes:
1.

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

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

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

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

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

7-18

the

stack

when

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$FORK1
7.4.13

Forkl

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

$FORKI

Description:

,., .*·SFORK1-FORK CQEATE
PROCESS
,
TMIS ROUTINE IS AN ALTERNATE ENTRY TO
A~D

5YSTE~

C~E'T~

A SYSTE~

PROC~SS

AND

r SAVE REGISTER R5.
INPUTSI
Q~=AODRESS OF THE LAST ~ORD OF A 3 ~aRD FORK BLOCK PLUS 2.
R5=REGISTEQ TO BE SAV~D I~ THE FOR~ ~LOCK.

OUTPUTSI
REGISTER

~5 IS SAvED I~ THE SPECI~I~D FORK tiLOCK AND A SYSTEM
IS CREATED. T~E P~OCESS IS Lr~KED Tu TH~ FO~~ QUEUE
A~D A Ju~P TO ~I~T~T IS EXECUTED.
~5 IS PRfSf~VfO FOR CALLE~S CALLtP.
P~OCESS

Notes:
1.

A 5-word fork block is required for calls to $FORKI.

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

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

7-19

the

stack

when

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$GTBYT
7.4.14

Get Byte

Get Byte is in the file BFCTL.
U.BUF+2 in the UCB.

Get Byte manipulates words

U.BUF

and

Calling sequence:
CALL

$GTBYT

De sc r i pt ion:

T~IS hOuTI~E IS CALLED TO GET TH~ NtxT ~YTE FROM THE USER aUFFER
AND Pf:. TUIH, IT TC THE. CALLE.I( O"i THE STACK. AFTE.R TH~ BYTE HAS SEEN
FETCHtD, THE NExT ByTE ADO~tSS IS I~C~EME~TED.

INPUTSa

OUTPUTSa
T~E

~EXT ~VT~
T~E CAL~E~

IS FETCHED FRO~ THE USER BUFFER A~D RETURNED
ON THE STACK. T~E NtXT BYTE ADDRESS IS INCRE~ENTED.

ALL REGISTEkS 4RE PRESE~VED ACROSS CALL.

7-20

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$GTPKT
$GSPKT
7.4.15

Get Packet

Get Packet and Get Special Packet are in the file
IOSUB.
The
recommended way to use $GTPKT is to use the GTPKT$ macro call defined
in Section 4.3.
Usage of $GSPKT is described briefly in Section
1.4.7.
Calling Sequences:
CALL

$GTPKT

CALL

$GSPKT

De sc r i pt ion:
;+
,t-*-$GTPKT-GET I/O PACKET FROM REQUEST QUEUE
,t-*-$GSPKT-GET SELECTIVE I/O PACKET FROM REQUEST QUEUE
THIS ROUTINE IS CALLED BY DEVICE DRIVERS TO DEQUEUE THE NEXT I/O REQUEST TO
PROCESS. IF THE DEVICE CONTROLLER IS BUSY, THEN A CARRY SET INDICATION IS
HETURNED TO THE CALLER. ELSE AN ATTEMPT IS MADE TO DEQUEUE THE NEXT REQUEST
I?ROM THE CONTROLLER QUEUE. IF NO REQUEST CAN BE DEQUEUED, THEN A CARRY
SET INDICATION IS RETURNED TO THE CALLER. ELSE THE CONTROLLER IS SET BUSY AND
A CARRY CLEAR INDICATION IS RETURNED TO THE CALLER.
IF QUEUE OPTIMIZATION IS SUPPORTED AND ENABLED FOR THE DEVICE
'rHE APROPRIATE PACKET FOR THE CURRENT OPTIMIZATION ALGORITHM
IS RETURNED.
THREE ALGORITHMS ARE SUPPORTED: NEAREST CYLINDER,
I~LEVATOR, AND C-SCAN.
ALL THREE ALGORITHMS INCORPORATE A
FAIRNESS COUNT.
IF THE FIRST PACKET ON THE LIST IS PASSED OVER
MORE THAN "FCOUNT" TIMES, IT IS DONE IMMEDIATELY.
'rHE ALTERNATE ENTRY POINT $GSPKT IS INTENDED FOR USE BY DRIVERS WHICH
:SUPPORT PARALLEL OPERATIONS ON A SINGLE UNIT, A COMMON EXAMPLE BEING
:~ULL DUPLEX.
SUCH DRIVERS ARE EXPECTED TO LOOK TO THE SYSTEM AS IF
'rHEY ARE ALWAYS FREE, WHILE MAINTAINING THE STATUS OF ALL PARALLEL
OPERATIONS INTERNALLY WITHIN THEIR OWN DEVICE DATA STRUCTURES.
PARALLELISM IS ACCOMPLISHED BY HANDLING DRIVER-DEFINED CLASSES OF I/O
FUNCTION CODES IN PARALLEL WITH EACH OTHER.
FOR EXAMPLE A FULL-DUPLEX
DRIVER WOULD HANDLE INPUT REQUESTS IN PARALLEL WITH OUTPUT REQUESTS •
.~ DRIVER CALLS $GSPKT WHEN IT WANTS TO DEQUEUE A PACKET WHOSE I/O
FUNCTION CODE BELONGS TO A CERTAIN CLASS. WHICH FUNCTIONS QUALIFY IS
DETERMINED BY AN ACCEPTANCE ROUTINE IN THE DRIVER WHOSE ADDRESS IS
PASSED TO $GSPKT IN R2.
THE ACCEPTANCE ROUTINE IS CALLED BY $GSPKT
EACH TIME A PACKET IS FOUND IN THE QUEUE WHICH IS ELIGIBLE TO BE
DEQUEUED.
THE ACCEPTANCE ROUTINE IS THEN EXPECTED TO TAKE ONE OF THE
FOLLOWING THREE ACTIONS:
1.

RETURN WITH CARRY CLEAR IF THE PACKET SHOULD BE
DEQUEUED.
IN THIS CASE $GSPKT PROCEEDS AS $GTPKT
NORMALLY WOULD ON DEQUEUEING THE PACKET.

RETURN WITH CARRY SET IF THE PACKET SHOULD NOT BE
DEQUEUED.
IN THIS CASE $GSPKT WILL CONTINUE THE SCAN
OF THE I/O QUEUE.

7-21

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$GTPKT
$GSPKT (Cont.)
3.

ADD THE CONSTANT G$$SPSA TO THE STACK POINTER TO ABORT
THE SCAN WITH NO FURTHER ACTION.

THE ACCEPTANCE ROUTINE MUST SAVE AND RESTORE ANY REGISTERS WHICH IT
INTENDS TO MODIFY. WHEN A PACKET IS DEQUEUED VIA $GSPKT, THE
FOLLOWING NORMAL $GTPKT ACTIONS DO NOT OCCUR:

NOTE:

FILLING IN OF U.BUF, U.BUF+2 AND U.CNT.
ARE AVAILABLE FOR DRIVER-SPECIFIC USE.

THESE FIELDS

BUSYING OF UCB AND SCB.

EXECUTION OF $CFORK TO GET TO PROPER PROCESSOR (MULTIPROCESSOR SYSTEMS).
$GSPKT MAY NOT BE USED BY A DRIVER WHICH SUPPORTS
QUEUE OPTIMIZATION.

INPUTS:
R2=ADDRESS OF DRIVER'S ACCEPTANCE ROUTINE (IF CALL AT $GSPKT).
R5=ADDRESS OF THE UCB OF THE CONTROLLER TO GET A PACKET FOR.
OUTPUTS:
C=1 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.
R5=ADDRESS OF THE UNIT CONTROL BLOCK.
NOTE: R4 AND R5 ARE DESTROYED BY THIS ROUTINE.
;-

7-22

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$GTWRD
7.4.16

Get Word

Get Word is in the file BFCTL.
in the UCB.

It manipulates words U.BUF and U.BUF+2

Calling Sequence:
CALL

$GTt'lRD

Description:
:+
**·~GT~RD·Gc.T

:~(XT

... o~()

FRO'~

USt~

tlUFFtR

THIS ~OuTIN~ IS CALLtD TO GET THE NExT ~O~D FRO~ THE USER BuFFER
: AND ~ETU~~ IT TO T~E CALLE~ o~ THE STACK, AFTER THE ~ORD HAS SEEN
FE.TCHfD, THE ~JExT .,.('I~D A"D~tSS IS CALCULATED,
It..JPUTSI
R~=ADDP~SS

THE UC8 THAT

CO~TAINS

THE BUFFER POINTERS,

OUTPUTS:

THE ~EXT ~ORD IS FETCHED F~OM T~E USER BU~FER A~D RETURNED
TO THE CALLER ON THE STACK. THE NEXT WOHD ADDRESS IS CALCULATED.
ALL REGISTERS ARE

P~ESERVED

7-23

ACROSS CALL.

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$INIBF
7.4.17

Initiate I/O Buffering

Th i sri) uti n e i sin the f i 1 e lOS UB •
Calling Sequence:
CALL

$INIBF

De sc r i pt ion:
i +

**-$INIBF-INITIATE I/O BUFFERING
THIS ROUTINE INITIATES I/O BUFFERING BY DOING THE FOLLOWING:
1.

DECREMENT THE TASK'S I/O COUNT.

INCREMENT THE TASK'S BUFFERED I/O COUNT

INITIATE CHECKPOINTING IF A REQUEST IS PENDING

INPUTS:
R3=ADDRESS OF I/O PACKET FOR I/O REQUEST.
OUTPUTS:
R3 IS PRESERVED.
i-

7-24

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$INTSV
7.4.18

Interrupt Save

Interrupt Save is in the file SYSXT.
The recommended way to
$INTSV is to use the INTSV$ macro call described in Section 4.3.

use

Calling Sequence:
$INTSV,PRn
n has a range of 0-7.
Description:
:+
**·SI~TSV·INTERPuPT

•• -SI~TSE-INTtR~UPT

SAVE
SA~E

FO~

ERRORLOGGI~G

DEvICES

: THIS ROUTINE IS CALLED FRO~ AN INTERRUPT SERVICE ROUTINE ~HEN AN
J INTERkUPT IS NOT GOING TO BE IM~EDIATELY DISMISSED, A SwITCH TO
THE SYSTEM STACk IS EXECUTEO IF THE CURRENT STACK DEPTH IS +1. wHEN
, THE INTERRUPT SERVICE ROUTINE FINISHES ITS PROCESSING, IT EITHER FORKS
, JUMPS TO SINTXT, OR EXECUTES A RETURN.
INPUTS,
4(SP):PS ~ORD PUSHED 8Y INTERRUPT.
2CSP):PC ~ORO PUSHED AY INTERRUPT.
0CSPl=SAVED RS PUSHED BY 'JSR R5,SINTSV'.
~(R5):NEw PROCESSOR PRIORITy.
: OUTPUTS,
REGISTlR R~ IS PUSHED ONTO T~E CURRENT STACK AND THE CURRENT
STACK DEPTH IS DECREMENTED. IF THE RESULT IS ZERO, THEN
A SwITCH TO THE SYSTE~ STACK IS EXECUTED, THE NEw PROCESSOR
STATUS IS SET AND A CO-ROUTINE CALL TO THE CALLER IS EXECUTED
R4 IS SET ~lTH THE CONTROLLER INOEX*2, WHICH IS OETER~INEO
FHO~ THE PSw AT E~TRY.

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

7-25

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$INTXT
7.4.19

Interrupt Exit

Interrlpt Exit is in the file SYSXT.
Callin~

Sequence:

Jt-' P

$INTXT

Description:
:+

, **-SINTXT-INT£RRUPT EXIT
THIS ROUTINE

~AY

BE CALLED VIA A JMP TO EXIT FROM AN INTERRUPT,

INPUTS,
aCSP)=INTERRUPT SAVE RETURN ADDRESS,
, OUTPUTS:
A R~TURN TO INTERRUPT SAVE IS EXECUTED,

7-26

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$IOAL T/$IODON
7.4.20

I/O Done Alternate Entry and I/O Done

These routines are in the file IOSUS.
Calling Sequences:
CA.LL
CA.LL

$IOALT
$IODON

Description:

,+
J

**-SIOALT-I/O DONE (ALTERNATE ENTRY)
•• -SIODON-I/O DONE

THIS ROUTINE IS CALLED BY DEVICE DRIV~RS AT THE COMPLETION OF AN 1/0 REQUEST
TO DO FINAL PROCESSING. THE UNIT A~D CONTROLLER ARE SET IDLE AND SIOFIN IS
J ENTERED TO FI~IS~ THE PROCESSING.
INPlJTSz
110 STATUS wORD.

R~zFIRST

Rl=SECONO

STATUS ~ORn.
AND FINAL ERROR RETRY COUNTS IF ERROR LOGGING
DEVICE.
R5=ADDRESS OF THE U~IT Ca~TROL BLOCK OF T~E UNIT SEING COMPLETED.
(SP)=RETUR~ AnDRESS TO ORIVER'$ CALLER.
, TM0q5
1/0

R2:STARTl~G

NOTt: IF

E~T~¥ IS AT $IOALT, TH~N Rl IS CLEAR TO SIGNIFY THAT THE
StCONO STATUS ~OQO IS ZERO,

nuH'UTS:
Trlt

U~IT

A~D

CO~T~nLL~~

AkE

SET IDLE.

Note:
R4 is destroyed when either of these routines
routines call $IOFIN, which destroys R4.

called.

The

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

7-27

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$IOFJN
7.4.21

I/O Finish

I/O Filish is in the file IOSUB.
Most drivers do not call I/O Finish,
but y)U should be aware that this routine is executed when a driver
calls SIOALT or $IODON.
A driver that references an I/O packet before
it
is queued
(bit UC.QUE set--see Section 8.3 for an example) calls
I/O Fi~ish if the driver finds an error while preprocessing the
I/O
packet.
CallinJ Sequence:
CALL

$IOFIN

Description:
1+

1 .*-~IOFIN·I/O FINISH
T~IS ROUTINE IS CALLED TO FI~ISH 1/0 PROCESSING IN CASES ~MERE TME UNIT AND
CONTROLLER ARE ~OT TO BE DECLARED IDL~. IF T~E TAS~ wHICH ISSUED THE
110 HAS ~AD A RECENT ~APPING CHANGE wHIC~ ~AY HAVE UN~APPED ITS 1/0
STATUS BLOCK, T~E 110 PACKET IS QUEUED TO T~E F~ONT Of ITS AST QUEUE
TO EE COMPLETED LAT~R IN $FINBF BY CALLING SIOFIN AGAIN.

INPLTS,
R0:FIRST 110 STATUS wORD.
Rl=SECOND 110 STATUS ~ORD.
R3=ADDRESS OF THE 110 R~QUEST

PAC~ET.

OUTFUTSI
THE

FOLLO~ING

ACTIONS ARE PERFORMED

1-THE FINAL 1/0 STATUS VALUES ARE STORED IN THE 1/0 STATUS BLOCK
ONE wAS SPECIFIED.
2-ALL ASSOCIATED 110 COUNTS ARE DECRE~ENTED AND TS.RON IS
CLEARED IN CASE THE TASK WAS BLOCKED FOR 1/0 RUNOO~N.
T3.~PC IS CLEARED IF THE TASK 1/0 COUNT GOES TO ZERO TO
INDICATE TH~T THE 1/0 COUNT ~ENT TO ZERO AFTER A MAPPING
CHANGE.
3-IF

IS SET, THEN IT IS CLEARED AND CHECKPOINTING O~
THE TASK IS INITIATED.

·TS.C~R'

4-IF AN AST SERVICE ROUTINE wAS SPECIFIED, THEN AN AST IS QUEUED
FOR THE TASK. ELSE THE 1/0 PAC~ET IS DEALLOCATED.
S-A

SIG~IFICANT

EVENT OR EQUIVALENT IS DECLARED.

NDTEr R4 IS DESTROVED BY THIS ROUTINE.

7-28

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$MPUBM
7.4.22

Map UNIBUS to Memory

This routine is in the file MEMAP.
It is used only for NPR devices
requiring UNIBUS Mapping Registers when 22-bit memory addressing is
enabled. See Section 7.3 for a discussion.
Calling Sequence:
CALL

$MPUBM

Description:

,, **-SMPUBM-M.P UNIBUS TO MEMORY

, THIS ROUTINE IS CALLED BV UNIBUS NPR DEVICE DRIvERS TO LOAD THE
, NECESSARY UNIBUS MAP REGISTERS TO EFFECT A TRANSFER TO MAIN MEM, ORY ON AN 11/70 PROCESSOR wITH EXTENDED MEMORY.

, INPUTS,
r
r
RQ-'DDRESS OF DEVICE SCB,
r
RS.ADDRESS OF DEVICE UCB,

, OUTPUTS,
,
,
THE UNIBUS MAP REGISTERS NECESSARV TO EFFECT THE TRANSFER
ARE LOADED.
,, NOTE. REGISTER R3 IS PRESERVED ACROSS CALL,
J

7-29

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$MPUB1
7.4.23

Map UNIBUS to Memory (Alternate Entry)

This routine is in file MEMAP.
It is used only for NPR devices that
require UNIBUS Mapping Registers when 22-bit memory addressing is
enabled and for support parallel operations.
Calling Sequences:
CALL

$MPUBI

Description:

,+
, **-SMPUB1-MAP UNI8US TO

~lMORY

(ALT~R~ATE

ENTRY).

THIS ROUTINE IS CALLED BY UNIBUS NPR DEVICE DRIVERS TO LOAD THE
NECESSARY UNIBUS MAP REGISTERS TO EFFECT • TRANSFER TO MAIN
1 MEMORY ON AN 11/7~ PROCESSOR wITH EXTENDED MEMORY. THIS ALTERNATE
ENTRY POINT ALLO~S THE DRIVER TO SPECIFY A NON-STANDARD UMR MAPPING
ASSIG~MENT RLOCK.
INPUTS,
R~=AODRESS

OF A UMR MAPPING ASSIGNMlNT BLOCK.

OUTPUTS,
T"E
NOTE:

U~IBUS

~AP

REGIST~RS

T~ANSFE~

ARE LOADED.

~EGISTER

PRESE~VED

7-30

NECESSARY TO EFFECT THl
ACROSS CALL.

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$PTBYT
7.4.24

Put Byte

Put Byte is in the file BFCTL.
U.BUF+2 in the UCB.

Put Byte manipulates words

U.BUF

and

Calling Sequence:
CALL

$PTBYT

Description:

;+
J

**-SPTBYT-PUT

~EXT

8YTE

USE~

BUFFER

T~IS ROUTINE IS CALLED TO PUT A BYTE I~ THE ~EXT LOCATION IN
USER 8UFFER. AFTER T~E 8YTt HAS 8EE~ STORED, THE NEXT BYTE ADDRESS
IS INCREMENTED.

INPUTS.
RS.ADORESS OF T~E UCB THAT CO~TAINS THE BUFFER POINTERS.
2CSP)=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. T~E NEXT BYTE ADDRESS IS INCREMENTED.
:

ALL REGISTERS ARE PRESERVED ACROSS CALL.

7-31

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$PTWRD
7.4.25

Put Word

Put Word is in the file BFCTL.
in the UCB.

It manipulates words U.BUF and U.BUF+2

Callinq Sequence:
C,\LL

$PTWRD

Description:

, •• -SPTWRD-PUT

~EXT

WORD IN USER BUFFER

THIS ROUTI~E IS CALED TO PUT A wORD I~ THE NExT LOCATION IN
USER BUFFER. AFTER THE WORD HAS BEEN STORED, THE NEXT WORD ADDRESS
IS CALCULATED.
I~PUTSI

RS.ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS.
2(SP).WORD TO BE STORED IN THE ~EXT LOCATION OF THE BUFFER.
OUTPUTS,
THE wORD IS STORED IN THE USER BUFFER AND REMOVED FROM
THE STAC~. THE NEXT WORD ADDRESS IS CALCULATED.

ALL REGISTERS ARE PRESERVED ACROSS CALL.

7-32

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$QINSP
7.4.26

Queue Insertion by Priorit.y

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

$QINSP

Description:

,+
r **-SQINSP-QUEUE INSERTION BY PRIORITY

THIS ROUTINE IS CALLED TO INSERT AN ENTRY IN A PRIORITY ORDERED
LIST, THE LIST IS SEARCHED UNTIL AN ENTRY IS FOUND THAT HAS A
LOWER PRIORITY OR THE END OF THE LIST IS ~EACHED, THE NEW
ENTRY IS THEN LINKED INTO THE LIST AT THE APPROPRIATE POINT,
INPUTS.
R0 •• DDRESS OF THE TwO WORD LISTMEAD,
Rl-ADDRESS OF THE ENTRY TO BE INSERTED,
OUTPUTS.
THf ENTRY IS LINKED INTO THE LIST BY PRIORITY.
R0 AND R1 ARE PRESERVED ACROSS CALL.
J.

7-33

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$RELOC
7.4.27

Relocate

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

$RELOC

Description:

,+
, •• -SRELOC-RELOCATE USER VIRTUAL ADDRESS
T~IS

ROUTINE IS CALLED TO TRANSFOR~ • lb BIT USER VIRTUAL ADDRESS
INTO A RELOCATION BIAS AND DISPLACEMENT IN BLOCK RELATIVE TO APR6.

INPUTSI
R0-USER

VI~TUAL

ADDR~SS

TO RELOCATE.

OUTPUTS,
Rl=RELOCATION BIAS TO AE LOADED INTO PARb.
R2=DISPLACEMENT IN BLOCK PLUS 1~0000 (PARb BIAS).

R0 AND R3 ARE PRESERVED ACROSS CALL.

7-34

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$RELOP
7.4.28

Relocate UNIBUS Physical Address

This routine is in the file MEMAP.
Calling Sequence:
CALL

$RELOP

Description:
;+
.*-SR~~OP-RELOC.TE

UNIBUS PHYSICAL ADDRESS

THIS ROUTINE ~ELOCATES A UNIBUS PHYSICAL ADDRESS TO A KISARb
BIAS AND DISPLACEMENT,
INPUTSI
R0=BVTE OfFSET FRO~ ADDRESS I~ U.BUF+l AND U.BUF+2
R4zSCB ADDRESS
RScUCB ADDRESS
U,BUF+l(RS):HIGH ORDER SITS OF ~HVSICAL ADDRESS
U,BUF+2(R5):LO~ ORDER BITS OF PHYSICAL ADDRESS
, OUTPUTS.

KISAR6-CALCULATED BIAS (MAPPED SYSTEM)
Rl-REAL ADDRESS OR DISPLACEMENT

7-35

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$REQUE
$REQU1
7.4.29

Queue Kernel AST to Task

This routine is in module IOSUB.
Calling Sequence:
CALL

$REQUE

CALL

$REQUI

Desc r i pt ion:
i**-$REQUE-REQUEUE A REGION LOAD AST TO A TASK AST
i**-$REQUI-REQUEUE A REGION LOAD AST TO A TASK AST (ALTERNATE ENTRY)
THESE ROUTINES ARE USED TO QUEUE A TASK KERNEL AST WHICH HAS BEEN
USED AS A REGION LOAD AST BACK AS A TASK AST. THE BUFFERED I/O
COUNT OF THE TASK IS DECREMENTED IF ENTRY AT $REQUE.
INPUTS:
RO=TCB ADDRESS OF ASSOCIATED TASK
R3=ADDRESS OF PACKET TO BE QUEUED

; --

OUTPUTS:
NONE.

7-36

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$STMAP
7.4.30

Set Up UNIBUS Mapping Address

This routine is in the file MEMAP.
It is used only for NPR devices
requiring UNIBUS Mapping Registers when 22-bit memory addressing is
enabled.
See Section 7.3 for a discussion.
Calling Sequence:
CALL

$STMAP

Description:
p+
p **-SSTMAP-SET

UP UNIBUS

MAPPI~G

ADDRESS

THIS ROUTINE IS CALLED BY UNIBUS NPR DEVICE DRIVERS TO SET UP THE
UNIBUS MAPPING ADDRESS, FIRST ASSIGNING THE UMR'S. I~ THE UMR'S
CANNOT BE ALLOCATED, THE DRIVER'S MAPPING ASSIGNMENT BLOCK IS PLACED
IN A wAIT QUEUE AND A RETURN TO THE DRIVER'S CALLER IS EXECUTED. THE
ASSIGNMENT BLOCK ~ILL E~ENTUALLY BE DEQUEUED WHEN THE UMR'S ARE
AVAILABLE AND THE DRIVER ~ILL BE REMAPPED AND RETURNED TO ~ITH Rl-RS
PRESERVED AND THE NORMAL OUTPUTS OF THIS ROUTINE. THE DRIVER'S
CONTEXT IS STORED IN THE ASSIGNMENT BLOCK AND FORK BLOCK WHILE IT IS
~ BLOCKEO AND IN THE ~AIT QUEUE,
ONCE A DRIVER'S MAPPING ASSIQNMENT
1 BLOCK IS PLACED IN THE UMR wAIT QUEUE, IT IS NOT REMOVED FROM THE
QUEUE UNTIL THE UMR'S ARE SUCCESSFULLY ASSIGNED, THIS STRATEGY
ASSURES THAT ~AITING DRIVERS WILL BE SERVICED FIFO AND THAT DRIVER'S
WITH LARGE REQUESTS FOR UMR'S WILL NOT wAIT INDEFINATELY,
~

INPUTS.
R4.ADDRESS OF DEVICE SC8.
RS-ADDRESS OF DEVICE UCB.
(SP).RETURN TO DRIVER'S CALLER,

w OUTPUTS.

UNIBUS MAP ADDRESSES ARE SET UP IN THE DEVICE UCB AND THE
ACTUAL PHYSICAL ADDRESS IS MOVED TO THE SCB.
NOTE. REGISTERS Rl, R2, AND R3 ARE PRESERVED ACROSS CALL.
Note:
This routine pushes the address of routine $DQUMR+2 onto the
stack before returning to the caller.
This precludes the use of
the stack for temporary data storage by drivers when calling this
routine.

7-37

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$STMP1
7.4.31

Set Up UNIBUS Mapping Address (Alternate Entry)

This r)utine is in file MEMAP.
It is used only for NPR devices that
requir~
UNIBUS Mapping Registers when 22-bit memory addressing is
enable,) and for support parallel operations.
Callinq Sequence:
$STMPI

C,\LL

Description:
:+
J

**·SST~Pl·SET

UP UNIBUS MAPPING

'DD~ESS

(ALTERNATE ENTRY).

THIS ENTRY CODE SETS UP AN ALTERNATE DATA STRUCTURE USED AS
A UMR MAPPING ASSIGNMENT BLOCK AND CONTEXl STORAGE BLOCK, IN
THE SAME MANNE~ AS SSTMAP USES THE FO~K BLOCK AND MAPPING
BLOCK IN THE SCB, KRB~ THE FORMAT OF THE STRUCTURE IS AS FOLLOWS •

... --_ ... -.- ............. -

_._----_.---_._---------.-

4 WORDS USED FOR SAVING
DRIVER'S CONTEXT IN CASE
UMRS CAN'T BE MAPPED
IMMEDIATELY,

c wORDS USED AS A UM~

MAPPING ASSIGNMENT BLOCK.

-------------------------!Pl,JPUTS,
R0=AOD~tSS
~4=ADDRESS
~5=ADD~ESS

OF THE DATA STRUCTU~t DEPICTED ABO¥E,
OE¥ICE sca,
O~ DEVICE wC8,
O~

OuTPUTS,
DATA

ST~UCTJRE

POI~TE~S

SET UP FOR ENTRY TO SSTMP2 IN SSTMAP,

,o .

Note:
This routine pushes the address of routine $DQUMR+2 onto the
st3ck before returning to the caller. This precludes the use of
the stack for temporary data storage by drivers when calling this
rO-ltine.

7-38

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$TSPAR
7.4.32

Test if Partition Memory Resident for Kernel AST

This routine is in file REQSB.
Calling Sequence:
CALL

$TSPAR

De sc r i pt ion:
i**-$TSPAR-TEST IF PARTITION IS IN MEMORY FOR KERNEL AST
THIS ROUTINE IS CALLED TO CHECK A REGION FOR MEMEORY RESIDENCE
TO DETERMINE IF IT IS SAFE TO SERVICE A KERNEL AST (E.G. COpy
)\ BUFFER) INTO THE REGION. IF THE REGION IS CHECKPOINTED OR
CURRENTLY BEING CHECKPOINTED, THEN A REGION LOAD AST IS QUEUED
AND THE REGION IS ACCESSED ON THE TASKS BEHALF.
INPUTS:
RO=ADDRESS OF PACKET PEING PROCESSED
Rl=PCB ADDRESS OF REGION
R5=TCB ADDRESS OF ASSOCIATED TASK
OUTPUTS:
C=O IF REGION IS MEMORY RESIDENT
C=l IF REGION IS NON-RESIDENT. IN THIS CASE THE REGION AST
HAS BEEN QUEUED, ETC.
i-

7-39

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

$TSTBF
7.4.33

Test for I/O Buffering

Th i s r» uti n e i sin f i 1 e lOS UB •
Calling Sequence:
C~LL

$TSTBF

Description:
i+

**-$TSTBF-TEST IF I/O BUFFERING CAN BE INITIATED
THIS ROUTINE DETERMINES IF A GIVEN I/O REQUEST IS ELIGIBLE FOR I/O
BUFFERING, AND IF SO IT STORES THE PCB ADDRESS OF THE REGION INTO
WHICH THE TRANSFER IS TO OCCUR IN I.PRM+l6 OF THE I/O PACKET.
INPUTS:
R3=ADDRESS OF I/O PACKET FOR I/O REQUEST
OUTPUTS:
R3 IS PRESERVED.
C=o IF I/O BUFFERING CAN BE INITIATED.
; --

C=l IF I/O BUFFERING CAN NOT BE INITIATED.

7-40

CHAPTER 8
SAMPLE DRIVER CODE

This chapter presents three sections of code.
Sections 8.1 and 8.2
show the driver data base and driver code for a conventional driver.
Section 8.3 gives a coding example from a driver that inhibits the
automatic
packet
queuing
in QIO processing so that it might
address-check and relocate a special user buffer. Both of the sample
drivers are in UFD [200,1] on the distribution kit.
In addition to the examples shown in this chapter, you should review
the source code for one or more standard DIGITAL-supplied drivers.
You should also examine the files SYSTB.MAC and XXTAB.MAC, which
contain data structures created at system generation.

8.1

SAMPLE DRIVER DATA BASE

The following example shows the source code to create the data base
for the driver that supports the DL device.
The data base allows for
one controller and one unit •
• TITLE
.IDENT

DLTAB
/09.0/

SYSTEM TABLES
MACRO LIBRARY CALLS
.MCALL
.MCALL
.MCALL
.MCALL
CLKDF$
HWDDF$
SCBDF$
UCBDF$

CLKDF$
HWDDF$
SCBDF$
UCBDF$

"SYSDEF

jDEFINE
jDEFINE
jDEFINE
jDEFINE

CLOCK BLOCK OFFSETS
HARDWARE REGISTERS
SCB OFFSETS
UCB OFFSETS

$DLDAT:: :
DL CTB
.WORD

L.ICB

.WORD
.ASCII
.WORD
.BYTE

$CTBI
/DL/
• DCO
1

L. LNK
L.NAM
L.DCB
L.NUM

$CTBO:

8-1

SAMPLE DRIVER CODE
.BYTE

.WORD

$DLA

t.STS
L.KRB

$DLCT13 : :

DL DCB
;

iLOADABLE DLDRV

$DLTBL=O
$DLDCB: :
. DCO:
.WORD
.WORD
.ASCII
.BYTE
.WORD
.WORD
.WORD
.WORD

.DCl
D.LNK
.DLO
D.UCB
/DL/
D.NAM
0,0
D.UNIT
DLND-DLST
D.UCBL
$DLTBL
i D.DSP
177477,70,0,177200,377,0,0,377
o
; D.PCB

D.MSK
Dt UCB'S

;

DLST=.
.WORD

.WORD
.WORD
.BYTE
.BYTE
.WORD
.WORD
.WORD
. WORD
.WORD
.WORD
• BYTE
• WORD

• DCO
.-2
UC.ALG!UC.NPR!UC.PWF!l,US.MNT
O,US.OFL
DV.DIR!DV.MSD!DV.UMD!DV.Fll!DV.MNT

• DLO: :

o
50000
512 •
$DLO
0,0,0,0,0,0,0,0
40. ,2 •
512 •

DLND= •
DLA

$DLA: :

.BYTE
.BYTE
.BYTE
.WORD
• WORD
.WORD
.BYTE
.WORD

PR5
160/4
0*2,0
O!KS.OFL
174400
DLA-$DLA
0,0

CONTIGUOUS

S C B

KRB

K.PRI
K.VCT
K.CON, K.IOC
K.STS
K.CSR
K.OFF
K.HPU
K.OWN
HERE FOR

;

$DLO::

.WORD
.WORD
.WORD
.WORD
.BYTE
.BYTE
.BYTE
.BYTE
.WORD
.WORD
• BYTE
.BYTE
.WORD
.BLKW
.WORD

0,.-2
0,0,0,0

o
o
o
4

o
o
S2.LOG!S2.CON
$DLA
7•

o
o

S.LHD AND K.CRQ
S.FRK
S.KS5
S.PKT
S.CTM
S.ITM
S.STS
S.ST3
S.ST2
S.KRB
S.RCNT
S.ROFF
S. EMB
MAPPING ASSIGNMENT BLOCK
KE.RHB

DLA:

8-2

SAMPLE DRIVER CODE

;

SDLEND: :

= 0

END OF DCB LIST FOR DL:

SCTBl = 0

END OF CTB LIST FOR DL:

• DCl

• END

8.2

SAMPLE DRIVER CODE

The following example shows the source code for the DL driver.
Comments beginning with ';;;' indicate that the instruction is being
executed at a priority level greater than or equal to 5 •
• TITLE
.IDENT

DLDRV
/01/

RLll-RL01/02 DISK DRIVER
.MCALL

HWDDF$,PKTDF$
HWDDF$
PKTDF$

jDEFINE HARDWARE REGISTERS
jDEFINE I/O PACKET OFFSETS

EQUATED SYMBOLS
RETRY=
RLBPT=
RLSPU=
i

8.
512.*20.
15.

jCONTROLLER ERROR RETRY COUNT
iBYTES PER SURFACE
iTIME TO SPIN UP

RLll DEVICE REGISTER OFFSETS

RLCS=
RLBA=
RLDA=
RLMP=

iCONTROL STATUS REGISTER

iBUS ADDRESS REGISTER
iDISK ADDRESS REGISTER
iMULTIPURPOSE REGISTER

4
6

RLCS BIT ASSIGNMENTS
ERR=
DE=
NXM=
DLT=
HNF=
DCK=
HCRC=
OPI=
DRDY=
WCHK=
WRITE=
GSTS=
SEEK=
RDH=
READ=

100000
040000
020000
010000
010000
004000
004000
002000
1
2
2
4
6

10
14

iCOMPOSITE ERROR
iDRIVE ERROR
iNONEXISTENT MEMORY
iDATA LATE
iHEADER NOT FOUND
jDATA CHECK ERROR
iHEADER CRC ERROR
jOPERATION INCOMPLETE
jDRIVE READY
iWRITE CHECK FUNCTION
iWRITE OFFSET
iGET DRIVE STATUS FUNCTION
jSEEK FUNCTION
iREAD HEADERS FUNCTION
jREAD DATA FUNCTION

8-3

SAMPLE DRIVER CODE
IE=
CRDY=

iINTERRUPT ENABLE
;CONTROLLER READY

100
200

RLDA STATlJS CODES

MRK=
STS=
SN=
RST=
HS=
REV=

;MARKER BIT
iGET STATUS BIT
iSIGN BIT FOR SEEK
iDRIVE RESET BIT
iHEAD SELECT BIT FOR DIFFERENCE
iREVERSE SEEK DIFFERENCE WORD

1
2

4
10
20
200 MRK

; RLMP GET
WDE=
CHE=
WLS=
SKTO=
SPD=
WGE=
VC=
DSE=
DT=
HSS=
CO=
HH=
BH=
SLM=

~;TATUS

BIT ASSIGNMENTS
;WRITE DATA ERROR
iCURRENT HEAD ERROR
iWRITE LOCK STATUS
;SEEK TIMEOUT ERROR
iSPEED ERROR
iWRITE GATE ERROR
iVOLUME CHECK
iDRIVE SELECT ERROR
iDRIVE TYPE
iHEAD SELECT STATUS
iCOVER OPEN
i HEADS HOME
iBRUSHES HOME
iDRIVE IN SEEK-LINEAR MODE STATE

100000
040000
020000
010000
004000
002000
001000
000400
000200
000100
000040
000020
000010
000005

LOCAL DATA
CONTROLLER IMPURE DATA TABLES
THESE ARE INDEXED BY THE CONTROLLER NUMBER
RTTBL:
PRMSV:

• BLK"w
.BLI<W

R$$Lll
R$$Lll*5

iRETRY COUNT FOR CURRENT OPERATION
iPARAMETER SAVE AREA FOR WRITE CHECK

iDRIVER DISPATCH TABLE
DDT~)

DL,R$$Lll,NEW=Y iGENERATE DISPATCH TABLE

**-DLINI-RLll-RLOl/02 DISK CONTROLLER INITIATOR
THIS ROUT1NE 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 EXECUTION OF THE DRIVER.
IF THE SPECIFIED CONTROLLER
IS NOT BU~:;Y, THEN AN ATTEMPT IS MADE TO DEQUEUE THE NEXT I/O REQUEST.
ELSE A RE~URN TO THE CALLER IS EXECUTED.
IF THE DEQUEUE ATTEMPT
IS SUCCES!'>FUL, 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

~HE

WAI~ING

SPECIFIED CONTROLLER IS NOT BUSY AND AN I/O REQUEST IS
TO BE PROCESSED, THEN THE REQUEST IS DEQUEUED AND THE

8-4

SAMPLE DRIVER CODE
DRIVER INITIATES THE REQUESTED I/O FUNCTION
i-

DLINI:

GTPKT$

DL,R$$L11

iGET NEXT I/O PACKET TO PROCESS

THE FOLLOWING ARGUMENTS ARE RETURNED BY $GTPKT:
R1= ADDRESS OF THE I/O REQUEST PACKET
R2= PHYSICAL UNIT NUMBER OF THE REQUESTED DRIVE
R3= CONTROLLER INDEX
R4= ADDRESS OF THE STATUS CONTROL BLOCK
R5= ADDRESS OF THE UCB OF THE DRIVE TO BE INITIATED
RL11-RL01/02 DISK CONTROLLER I/O REQUEST PACKET FORMAT:
WD.
WD.
WD.
WD.
WD.
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
15
16
17
20
21

I/O QUEUE THREAD WORD
REQUEST PRIORITY, EVENT FLAG NUMBER
ADDRESS OF THE TCB OF THE REQUESTOR TASK
POINTER TO 2ND LUN WORD IN REQUESTOR TASK HEADER
CONTENTS OF FIRST LUN WORD
I/O FUNCTION CODE
VIRTUAL ADDRESS OF I/O STATUS BLOCK
RELOCATION BIAS OF I/O STATUS BLOCK
I/O STATUS BLOCK ADDRESS (DISPLACEMENT + 140000)
VIRTUAL ADDRESS OF AST SERVICE ROUTINE
MEMORY EXTENSION BITS OF I/O TRANSFER
BUFFER ADDRESS OF I/O TRANSFER
NUMBER OF BYTES TO BE TRANSFERRED
NOT USED.
LOW BYTE MUST BE ZERO AND HIGH BYTE IS NOT USED
LOW PART OF LOGICAL BLOCK NUMBER OF I/O REQUEST
RELOCATION BIAS OF REGISTER BUFFER ELSE NOT USED
REGISTER BUFFER ADDRESS (DISPLACEMENT + 140000) ELSE NOT USED

DRIVER USAGE OF WORDS IN I/O PACKET:
I.PRM+6
(WD. 15) - SEEK DIFFERENCE WORD
I.PRM+10 (WD. 16) - STARTING DISK ADDRESS FOR THIS TRANSFER
I.PRM+12 (WD. 17) - BYTE COUNT FOR THIS TRANSFER

5$:
10$:

20$:

MOV
CALL
BCS
TST
BMI
TST
BPL
MOV
CALL
MOV
MOV
MOV
CALL
JMP

tRETRY&377,RTTBL(R3}
iSET INITIAL RETRY COUNT
$VOLVD
iVALIDATE VOLUME VALID
5$
iIF CS WE FAILED
RO
iTRANSFER FUNCTION?
10$
iIF MI YES
I.PRM+2(R1}
iSIZE THE DISK?
5$
iIF PL NO, ERROR
S.CSR(R4),R2
iRETRIEVE CSR ADDRESS
iRESET DRIVE AND GET STATUS
DLRST
S.PKT(R4),R3
iRETRIEVE I/O PACKET ADDRESS
I.PRM+14(R3) ,KISAR6
iSET BUFFER RELOCATION BIAS
I.PRM+16(R3} ,R3 iGET REGISTER BUFFER ADDRESS
REGPAS
iMOVE REGISTERS INTO BUFFER
DLFIN
iFINISH UP

CALL
MOVB
MOV
BIS
CMPB
BEQ
CMPB
BNE
SUB
MOV

$STMAP
iSET UP UNIBUS MAPPING ADDRESS
R2,U.BUF+1(R5}
iSET CURRENT UNIT NUMBER
#IE.IFC&377,RO
iASSUME ILLEGAL FUNCTION
#READ!IE,U.BUF(R5}
iASSUME READ LOGICAL FUNCTION
tIO.RLB/256.,I.FCN+1(R1)
iREALLY?
20$
iIF EQ YES
tIO.WLB/256.,I.FCN+1(Rl)
iWRITE LOGICAL FUNCTION?
5$
iIF NE NO, EXIT WITH ERROR
tWRITE,U.BUF(R5)
iCONVERT TO WRITE LOGICAL FUNCTION
#RETRY,RTTBL(R3)
iSET INITIAL RETRY COUNT

8-5

SAMPLE DRIVER CODE
MOl
CLi.
BI rB
BN ~
CA.~L

CM :>B
BN ~
BI'~B
BN~

MO'!
AD~)

CA~L

MO'l

30$:
35$:

AS,
MO'!

CALL
ROn
ROL
ASH
BI~;

MOv
MOv
M0"
SUfI

SW1.B
CMI'

BLC'S
M0"

40$:

M0''B
MUl

AD[
MO\
MO\

MO\
MO\

MOv

I.PRM+12(RI) ,RO ;RETRIEVE BLOCK NUMBER
R2
iCLEAR HIGH ORDER BLOCK NUMBER
IIO.WPB&377,I.FCN(RI)
iPHYSICAL BLOCK FUNCTION?
35$
;IF NE YES
$BLKCK
;CHECK LOGICAL BLOCK NUMBER
IIO.WLB/256.,I.FCN+I(R3)
;WRITE FUNCTION?
30$
;IF NE NO
IIO.WLT&377,I.FCN(R3)
;OK TO WRITE ON LAST TRACK?
30$
;IF NE YES
RO,I.PRM+6(R3)
;YES, SAVE STARTING BLOCK NUMBER
I D<20),I.PRM+12(R3)
;ADD 1 TRACK'S WORTH OF BLOCKS
$BLKCI
;CHECK IF WRITE ON LAST TRACK OF DISK
I.PRM+6(R3) ,RO
;RESTORE ORIGINAL STARTING BLOCK NUMBER
RO
iCONVERT BLOCKS TO SECTORS
S.PKT(R4) ,R3
;RESET I/O PACKET ADDRESS
$CVLBN
;CONVERT BLOCK NUMBER TO DISK ADDRESS
RI
;PUT SURFACE BIT IN CARRY
R2
;MERGE IT WITH THE CYLIDER NUMBER
16,R2
iPOSITION CYLINDER AND SURFACE
RO,R2
iMERGE SECTOR WITH CYLINDER AND SURFACE
R2,I.PRM+IO(R3) iSAVE STARTING DISK ADDRESS
U.CNT(R5),I.PRM+12(R3)
iASSUME ONLY ONE XFER NEEDED
I D<40),Rl
iSET SECTORS/SURFACE
RO,RI
iCALCULATE SECTORS LEFT ON SURFACE
RI
;GET BYTES LEFT ON SURFACE
U.CNT(R5) ,Rl
iARE ADDITIONAL TRANSFERS REQUIRED?
40$
iIF LOS NO
RI,I.PRM+12(R3) iSET BYTE COUNT FOR FIRST TRANSFER
S.CON(R4) ,RI
;RETRIEVE CONTROLLER INDEX
15,Rl
;FORM INDEX INTO PARAMETER SAVE AREA
#PRMSV,Rl
iPOINT TO THIS ENTRY
U.BUF(R5),(RI)+ iSAVE INITIAL PARAMETERS
U.BUF+2(R5),(RI)+
, •••
U.CNT(R5),(RI)+ i •••
I.PRM+IO(R3), (RI)+ , ••.
I • PRM + 12 (R 3) , (R I) + , •••
A

; THIS SEC1ION WILL INITIATE THE OPERATION
i-

DLINIO: CALL
MOV
MOV

10$:

20$:

CLRB
CLR
MOVB
CALL
MOV
BIC
BIT
BEQ
CMP
BEQ
BIT3
BNE
MOV
JMP
BIC 3
MOV
CAL~

DLGO:

BEQ
MOV
CAL~

30$:

BMI
ADD

$MPUBM
;MAP UNIBUS TO TRANSFER
S.CSR(R4) ,R2
iGET ADDRESS OF CSR
S.PKT(R4),R3
iGET ADDRESS OF I/O PACKET
U.CW2+1 (R5)
iRESET DRIVE SETTLE DOWN FLAG
I. PRM+6 (R3)
iRESET ERROR DIFFERENCE WORD
S.ITM(R4) ,S.CTM(R4)
iSET DEVICE TIMEOUT COUNTER
DLRST
iRESET DRIVE AND GET STATUS
RLMP(R2) ,RI
iGET THE STATUS INFO
#WLS!DT!HSS,RI
iREMOVE IRRELEVANT BITS
#DRDY,(R2)
iIS THE DRIVE READY?
10$
;IF EQ NO
#HH!BH!SLM,Rl
iHEADS, BRUSHES AND STATE OK?
20$
iIF EQ YES
IUS.SPU,U.STS(R5)
;IS DRIVE SPINNING UP?
DLPWFI
iIF NE YES, WAIT FOR IT TO SPIN UP
#IE.DNR&377,RO
;SET RETURN ERROR CODE
DLFIN
iEXIT WITH FATAL ERROR
IUS.SPU,U.STS(R5)
;RESET DRIVE SPINNING UP
I.PRM+IO(R3) ,RO iRETRIEVE STARTING DISK ADDRESS
DLDIFF
iCALCULATE DIFFERENCE WORD
30$
;IF EQ NO SEEK IS NECESSARY
ISEEK,RI
;GET CODE FOR SEEK FUNCTION
DLXCT
;EXECUTE THE SEEK
DLEROR
iIF MI ERROR DURING SEEK FUNCTION
IRLMP,R2
iPOINT TO RLMP

8-6

SAMPLE DRIVER CODE
MOV
ROR
NEG
MOV
MOV
MOV
CALL
MOV

I.PRM+12(R3) ,R1 ;GET BYTE COUNT
R1
;MAKE IT A WORD COUNT
R1
;ALSO NEGATIVE
R1,(R2)
;LOAD WORD COUNT
I.PRM+10(R3) ,-(R2)
;LOAD STARTING DISK ADDRESS
U.BUF+2(RS) ,-(R2)
;LOAD BUS ADDRESS
$BMSET
;SET I/O ACTIVE BIT IN MAP
U.BUF(RS) ,-(R2) ;;;LOAD FUNCTION AND GO

;+
; CANCEL I/O OPERATION IS A NOP FOR FILE STRUCTURED DEVICES.
;-

DLCAN:

RETUHN

;;iNOP FOR RL11

;+
POWERFAIL IS HANDLED VIA THE DEVICE TIMEOUT FACILITY AND
CAUSES NO IMMEDIATE ACTION ON THE UNIT.
THE CURRENT TIMEOUT
COUNT IS EXTENDED, THUS IF A UNIT WAS BUSY IT WILL HAVE
SUFFICIENT TIME TO SPIN BACK UP.
THE NEXT I/O REQUEST TO ANY
UNIT WILL BE SUSPENDED FOR AT LEAST THE EXTENDED TIMEOUT UNLESS
THE UNIT IS CURRENTLY READY.
i-

DLPWF:

TSTB
BEQ
MOVB
DLPWF1: MOVB
DLPWF2: BISB
RETUHN

S.STS(R4)
iIS DRIVE CURRENTLY BUSY?
DLPWF2
;IF EQ NO
#4,S.STS(R4)
;ALLOW FOR A FULL MINUTE TO SPIN UP
#RLSPU,S.CTM(R4)
iEXTEND TIMEOUT INCASE UNIT WAS BUSY
#US.SPU,U.STS(RS)
;SET UNIT SPINNING UP

;+
i

**-$DLINT-RL11-RL01/02 DISK CONTROLLER
INTEHRUPT AND ERROR SERVICE ROUTINES

• ENABL

LSB

$DLINT::INTSV$
CALL
MOV
ASRB
BCS
MOV
MOV
MOV
MOV
MOV
BMI
SUB
BEQ
MOV
CMP
BLOS
MOV
10$:
BIC
MOV
MOV
MOV
MOV
BIS
INC
MOV
CALL
JMP

DL,PRS,R$$Lll
;;;SAVE REGISTERS AND SET PRIORITY
$FORK
ii;CREATE A SYSTEM PROCESS
R4,R3
;COPY CONTROLLER INDEX
RTTBL+l (R3)
;HOME SEEK IN PROGRESS?
DLINIO
;IF CS YES
U.SCB(RS),R4
;GET ADDRESS OF SCB
S.CSR(R4),R2
;GET ADDRESS OF CSR
#IS.SUC&377,RO
;ASSUME SUCCESSFUL OPERATION
S.PKT(R4),R3
iRETRIEVE I/O PACKET ADDRESS
(R2),Rl
iGET CONTENTS OF RLCS
20$
;IF MI AN ERROR OCCURRED
I.PRM+12(R3) ,U.CNT(RS)
;CALCULATE BYTES LEFT TO XFER
70$
;IF EQ NONE LEFT
U.CNT(RS),I.PRM+12(R3)
iASSUME LAST XFER COMING
U.CNT(RS),#RLBPT iIS THIS THE LAST TRANSFER?
10$
;IF LOS YES
#RLBPT,I.PRM+12(R3)
;TRANSFER A WHOLE TRACKS WORTH
#CRDY,Rl
;CLEAR CRDY TO START FUNCTION
Rl,U.BUF(RS)
;SAVE CURRENT FUNCTION AND ADDRESS BITS
RLBA(R2) ,U.BUF+2(RS)
;SAVE CURRENT BUS ADDRESS
I.PRM+IO(R3) ,RO ;GET INITIAL DISK ADDRESS
RO,Rl
;COPY DISK ADDRESS
#77,RO
;UPDATE CYLINDER AND SURFACE
RO
, ••• LEAVING SECTOR BITS ZERO
RO,I.PRM+IO(R3) ;SAVE NEW DISK ADDRESS
DLDIFO
;CALCULATE MID-TRANSFER DIFFERENCE
DLGO
;GO DO THE OPERATION

20$:

#DRDY,Rl

BIT

;IS THE DRIVE READY?

8-7

SAMPLE DRIVER CODE
DLEROR
#3,S.CTM(R4)
U• CW 2 + 1 (R 5 )

iIF NE YES, GO CHECK FOR ERRORS
iWAIT 3 SECONDS FOR THE DRIVE TO SETTLE
iFLAG SETTLE DOWN IN PROGRESS

DLEROR: MOV
MOV
BIT
BNE
BIT
BEQ
CAL':..
BIT
BEQ
BIT
BEQ
MOV
BR
40$:
BIT
BNE
BIT
BNE
BIT
BEQ
MOV
BR

(R2) ,Rl
#IE.VER&377,RO
#NXM, Rl
90$
#DE,Rl
40$
DLGST
#WGE,RLMP(R2)
90$
#WLS, RLMP (R 2)
DLRTRY
#IE.WLK&377,RO
DLFIN
#lO,U.BUF(R5)
DLRTRY
#OPI,Rl
DLRTRY
#DCK,Rl
DLRTRY
tIE.WCK&377,RO
DLRTRY

iRETRIEVE CONTENTS OF RLCS
iASSUME UNRECOVERABLE ERROR
iNON-EXISTENT MEMORY?
iIF NE YES
i DRIVE PROBLEMS?
iIF EQ NO
iEXECUTE GET DRIVE STATUS FUNCTION
iWRITE GATE ERROR?
iIF EQ NO
i1S THE DRIVE WRITE LOCKED?
iIF EQ NO
iSET WRITE LOCK ERROR CODE

70$:

#IO.WLC&377,I.FCN(R3)
iWRITE WITH WRITE CHECK?
80$
iIF NE YES
#US.WCK,U.STS(R5)
iWRITE CHECK ENABLED?
DLFIN
iIF EQ NO
U.BUF(R5),Rl
iGET CURRENT FUNCTION CODE
#WCHK,Rl
iWRITE OR WRITE CHECK FUNCTION?
DLFIN
iIF EQ NO
#lO,Rl
iWAS FUNCTION WRITE CHECK?
DLFIN
iIF EQ YES
S.CON(R4),Rl
iRETRIEVE CONTROLLER INDEX
#RETRY,RTTBL(Rl)iRESET RETRY COUNT
#5,RI
iFORM AN INDEX INTO SAVE AREA
#PRMSV,Rl
, •••
(RI)+,U.BUF(R5) iRESTORE STARTING PARAMETERS
(RI)+,U.BUF+2(R5)
, •••
(RI)+,U.CNT(R5) , •••
(RI)+,I.PRM+IO(R3)
, •••
(RI)+,I.PRM+l2(R3)
, •••
#lO,U.BUF(R5)
iCONVERT TO WRITE CHECK FUNCTION
DLINIO
iSTART THE WRITE CHECK

25$:

80$:

BNE
MOV3
INC3
RETJRN

BIT3
BNE
BIT3
BEQ
MOV
BIT
BEQ
BIT
BEQ
MOV3
MOV
MUL
ADD
MOV
MOV
MOV
MOV
MOV
BIC
JMP

iWRITE CHECK FUNCTION?
iIF NE NO
iOPERATION INCOMPLETE?
iIF NE YES
iWRITE CHECK ERROR?
iIF EQ NO
iYES, SET WRITE CHECK ERROR CODE
iGO RETRY OPERATION IF REQUIRED

i+
i FINISH I/i) OPERATION
i-

90$:
DLFIN:

MOV
MOV
MOV
SUB
MOVlI
MOVB
BIS
CAL.
JMP

#1E.VER&377,RO
iSET UNSUCCESSFUL OPERATION
S.PKT(R4) ,R2
iGET ADDRESS OF I/O PACKET
I.PRM+4(R2) ,RI
iGET TOTAL TRANSFER SIZE
U.CNT(R5) ,Rl
iCALCULATE BYTES TRANSFERRED
S.CON(R4) ,R3
;RETRIEVE CONTROLLER INDEX
RTTBL(R3) ,R2
iGET FINAL RETRY COUNT
#RETRy*A D<256>,R2
iMERGE STARTING RETRY COUNT
$IODON
iFINISH I/O OPERATION
DLINI
iPROCESS NEXT REQUEST

**-DLOUT-HLII-RLOI/02 DISK CONTROLLER
DEV:CE TIMEOUT ROUTINE

8-8

SAMPLE DRIVER CODE
DEVICE TIMgOUT RESULTS IN THE OPERATION BEING REPEATED.
TIMEOUTS AHE USUALLY CAUSED BY A POWER FAILURE BUT MAY ALSO
BE THE RESULT OF A HARDWARE MALFUNCTION.
i-

DLOUT:

MOV
BITB
BEQ
DECB
BNE
INCB
BR
10$:
MTPS
JMP
20$:
TSTB
BEQ
MTPS
JMP
30$:
MTPS
CALL
MOV
DLRTRY: MOV
BITB
BNE
DECB
BLE
JMP

S.PKT(R4),R3
iiiRETRIEVE I/O PACKET ADDRESS
#US.SPU,U.STS(RS)
iiiIS DRIVE SPINNING UP?
20$
iiiIF EQ NO
S.STS(R4)
iiiHAVE WE WAITED A MINUTE YET?
10$
iIF NE NO
S.STS(R4)
iiiLEAVE CONTROLLER BUSY
30$
iiiLOG DEVICE TIMEOUT
#0
iiiALLOW INTERRUPTS
DLINIO
iRETRY ENTIRE OPERATION
U.CW2+1(RS)
iiiIS DRIVE SETTLING DOWN?
30$
;iiIF EQ NO
to
iiiYES, ALLOW INTERRUPTS
DLEROR
iPROCESS THE ERROR
#0
iiiALLOW INTERRUPTS
DLRST
iRESET DRIVE
#IE.DNR&377,RO iSET DEVICE NOT READY
S.PKT(R4) ,Rl
iGET I/O PACKET ADDRESS
tIQ.X,I.FCN(Rl) iINHIBIT RETRIES?
iIF NE YES
DLFIN
RTTBL(R3)
iANY MORE RETRIES LEFT?
DLFIN
iIF LE NO
DLINIO
iYES, RETRY ENTIRE OPERATION

**-DLXCT,DLGST,DLRST-RLII-RLOl/02 DISK CONTROLLER
FUNCTION EXECUTION ROUTINES
THIS ROUTINE WILL EXECUTE A GET DRIVE STATUS OR ANY
NON-INTERRUPTABLE FUNCTION AND WAIT FOR ITS COMPLETION.
INPUTS:
Rl
R2
RS

FUNCTION CODE
CSR ADDRESS
UCB ADDRESS

OUTPUTS:
Rl = CONTENTS OF RLCS (TESTED)
FUNCTION EXECUTED
i-

DLRST:
DLGST:
10$:
DLXCT:
20$:

.ENABL
MOV
CALL
MOV
MOV
MOV
MOVB
MOV
BIT
BEQ
MOV
RETUHN
.DSABL

LSB
tRST!STS!MRK,RLDA(R2)
iSET MESSAGE CODES IN RLDA
10$
iDO THE DRIVE RESET FIRST
#STS!MRK,RLDA(R2)
iSET MESSAGE CODES IN RLDA
tGSTS,Rl
iSET GET STATUS FUNCTION
Rl,-(SP)
iSAVE FUNCTION CODE
U.UNIT(RS) ,1(SP}iMERGE CURRENT DRIVE BITS
(SP)+, (R2)
iLOAD RLCS
tERR!CRDY,(R2)
iREADY OR ERROR?
20$
iIF EQ NEITHER
(R2) ,Rl
iSAVE RLCS AND TEST FOR ERRORS
LSB

**-DLDIFF-RLII-RLOl/02 DISK CONTROLLER
CYLINDER ADDRESS DIFFERENCE CALCULATOR
THIS SUBROUTINE CALCULATES THE DIFFERENCE WORD USED IN THE
SEEK OPERATION.
IF A HEADER CANNOT BE READ AFTER 16. RETRIES,
AN ERROR WILL BE LOGGED AND A ONE CYLINDER REVERSE SEEK WILL BE
ISSUED.
THE SEEK IS FOLLOWED BY A READ HEADERS TO CAUSE AN

8-9

SAMPLE DRIVER CODE
INTERRUP" •
INPUTS:
RO
R3

DESIRED DISK ADDRESS
I/O PACKET ADDRESS

OUTPUTS:
Rl = DIFFERENCE WORD
RLDA = LOADED WITH DIFFERENCE WORD
I.PRM+6 = LOADED WITH DIFFERENCE WORD
IF EQ NO SEEK IS NECESSARY
DLDI FF: MO"
10$:
MO"
CALL
BPI.
DEC
BGT
CM!'
CALL
MO\MO\'
MO\
CAlL
BM]
RIC
BI~

MO\B
MO\B
MO\

20$:

RETURN
TS'I
MO\

DLDIFO: CLF
BIC
BIC
CMF

...

BEC
MO\l

30$:

BIC
ASR
ASR
BIC
BIC
SUB
BCC
NEG
BIS
INC
SIS

...
...

MOV

40$:

tRETRY*2,-(SP)
iSET READ HEADER RETRY COUNT
IRDH,Rl
iSET CODE FOR READ HEADERS FUNCTION
DLXCT
iEXECUTE THE FUNCTION
20$
iIF PL FUNCTION EXECUTED OK
(SP)
iANY RETRIES LEFT?
10$
iIF GT YES
(SP)+,(SP)+
iREMOVE RETRY COUNT AND CALLERS ADDRESS
DLRST
iRESET DRIVE
tREV,RLDA(R2)
iLOAD REVERSE SEEK DIFFERENCE WORD
tSEEK,Rl
iGET CODE FOR SEEK FUNCTION
#IE.VER&377,RO
iASSUME WE WILL FAIL
DLXCT
iEXECUTE THE SEEK
DLFIN
iIF MI WE FAILED
t377,Rl
iCLEAR OUT FUNCTION BITS
#IE!RDH,Rl
iLOAD CODES FOR READ HEADER
#1,RTTBL+l(R3)
iINDICATE REVERSE SEEK IN PROGRESS
S.ITM(R4),S.CTM(R4)
iSET DEVICE TIMEOUT COUNTER
Rl,(R2)
iLOAD FUNCTION AND GO
iWAIT FOR THE INTERRUPT
(SP)+
iREMOVE RETRY COUNT
RLMP(R2) ,Rl
iRETRIEVE HEADER WORD
I. PRM+6 (R3)
iRESET DIFFERENCE WORD
#77,RO
iMASK OUT SECTOR BITS
#77,Rl
,
RO,Rl
iDa WE NEED TO DO A SEEK?
40$
iIF EQ NO
RO,-(SP)
iSAVE DESIRED DISK ADDRESS
I"C<lOO), (SP)
iISOLATE SURFACE BIT
(SP)
iPUT INTO THE PROPER POSITION
(SP)
,
IIOO,RO
iREMOVE SURFACE BIT
IIOO,Rl
,
RO,Rl
~SUBTRACT DESIRED FROM ACTUAL
30$
iIF CC ACTUAL )= DESIRED
iACTUAL < DESIRED, MAKE POSITIVE DIFFERENCE
Rl
iSET SIGN FOR MOVE TO CENTER OF DISK
ISN,Rl
Rl
iSET MARKER BIT
(SP)+,Rl
iMERGE IN SURFACE BIT
Rl,RLDA(R2)
iLOAD DIFFERENCE WORD
iSAVE DIFFERENCE WORD
Rl,I.PRM+6(R3)

MOV
RET'JRN

MOVE THE

~ONTROLLER/DRIVE

INPUTS:
R2
R3

CSR ADDRESS
BUFFER ADDRESS

REG PAS : MOV
MOV

REGISTERS INTO THE SPECIFIED BUFFER.

(R2) , (R3) +
R LB A ( R 2) , (R 3) +

iMOVE RLCS
iMOVE RLBA

8-10

SAMPLE DRIVER CODE
MOV
MOV
CLR
CLR
CALL
MOV
RETlJRN

RLDA(R2) ,(R3)+
RLM P (R 2) , (R 3 ) +
(R3)+
(R3) +
DLGST
RLMP (R2) , (R3)

iMOVE RLDA
iMOVE RLMP
iCLEAR PLACE HOLDERS •••
i ••• SO HRC/CON WILL WORK
iEXECUTE GET DRIVE STATUS FUNCTION
iSAVE DRIVE STATUS

**-DLKRB-CONTROLLER ON-LINE/OFF-LINE ROUTINE
THIS ROUTINE WILL HANDLE RECONFIGURATION CALLS FOR ON-LINE
CONTROLLER AND OFF-LINE CONTROLLER FOR THE RLII.
INPUTS:
R2 = KRB ADDRESS
R3 = CTB ADDRESS
C=l IF OFF-LINE REQUEST
C=O IF ON-LINE REQUEST
OUTPUTS:
NONE
i-

DLKRB:

BCS

DLOFL

iHANDLE OFF-LINE REQUEST

CODE SPECIFIC TO HANDLE THE CONTROLLER COMING ON-LINE.
RETURN

iEXIT

CODE SPECIFIC TO HANDLE THE CONTROLLER GOING OFF-LINE
DLOFL:
RETURN
i+

**-DLUCB-UNIT ON-LINE/OFF-LINE ROUTINES
THIS ROUTINE WILL HANDLE RECONFIGURATION CALLS FOR ON-LINE
UNIT AND OFF-LINE UNIT FOR RLOI AND RL02 DRIVES.
INPUTS:
R3
CONTROLLER INDEX
R4
SCB ADDRESS
R5
UCB ADDRESS
C=l IF OFF-LINE REQUEST
C=O IF ON-LINE REQUEST
OUTPUTS:
NONE:
i .-

DLUCB:

BCS

DLOFLU

iIF CS OFF-LINE REQUEST

CODE SPECIFIC TO BRINGING UNIT ON-LINE.
RETURN
CODE SPECIFIC TO TAKING UNIT OFF-LINE.

8-11

snMPLE DRIVER CODE

DLOFLU:
RETURN
.I:ND

8.3

HANDLING SPECIAL USER BUFFERS

Some drivers need to handle user buffers in addition to
the buffer
that the
Executive address-checks and relocates in a normal transfer
request.
Address-checking and relocation operations must take place
in
the
~ontext
of the
task
issuing the I/O request, because the
mapping registers are set fo;:the
issuing task.
However,
ill
i..rle
normal driver interface, the task context after the call to $GTPKT is
not, in general, that of the issuing task.
Thus, driv~rs that need to handle special buffers must be able to
refer
to the I/O packet before it is queued, while the context of the
issuing task is still intact.
The codinj shown in this section is an excerpt from a driver
that
illustrates the handling of a special user buffer.
The key points
are:
1.

The UC.QUE bit has been set in the control
the UCB for each device/unit.

byte

(U.CTL)

The routine (ZZINI) that is defined as the
I/O initiation
entry point in the driver dispatch table (DDT$) macro call
performs the following actions:
3.

Retrieves the user virtual address and address-checks it

Relocates the virtual address and stores the result
into the packet

back

Inserts the packet
into the
I/O queue and continues
execution
inline to
the entry point BMINI, which calls
$GTPKT
3.

The driver propagates its own execution by branching back
BMINI to call $GTPKT •

• TITLE
.IDENT

BMTAB - DATA BASE FOR BLOCK MOVE DRIVER
/01/

COPYRIGHT (c) 1981, 1982 BY
DIGITAL EQUIPMENT CORPORATION, MAYNARD
~ASSACHUSETTS.
ALL RIGHTS RESERVED.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED
AND COPIED ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE
AND WITH THE INCLUSION OF THE ABOVE COPYRIGHT NOTICE.
THIS
SOFTWARE OR ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR
OTHERWISE MADE AVAILABLE TO ANY OTHER PERSON.
NO TITLE TO AND
OWNERSHIP OF THE SOFTWARE IS HEREBY TRANSFERRED.
THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT
NOTICE ~ND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL
EQUIPMENT CORPORATION.
8-12

SAMPLE DRIVER CODE

DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF
ITS SOF'TWARE ON EQUIPMENT THAT IS NOT SUPPLIED BY DIGITAL.

LOADABLE DATA BASE FOR EXAMPLE BUFFERED I/O DRIVER
MACRO LIBRARY CALLS
.MCALL
.MCALL
.MCALL
.MCALL
CLKDF$
HWDDF$
SCBDF$
UCBDF$

CLKDF$
HWDDF$
SCBDF$
UCBDF$

, , SYSDEF

;DEFINE
;DEFINE
;DEFINE
;DEFINE

CLOCK BLOCK OFFSETS
HARDWARE REGISTERS
SCB OFFSETS
UCB OFFSETS

$BMDAT: :
BM DCB
~;BMTBL=O

;LOADABLE BMDRV

$BMDCB: :
.. WORD
.. WORD
.. ASCII
.. BYTE
.. WORD
.. WORD

0
.BMO
/BM/
0,1-1
BMND-BMST
$BMTBL

.. WORD

.. WORD
.. WORD
,.WORD
,.WORD
,.WORD
.WORD
.WORD
.WORD

31
0
0
4
0
0
0
0

D. LNK
D.UCB
D.NAM
D.UNIT,D.UNIT+l
D.UCBL
D.DSP
D.MSK - FUNCTION MASKS
LEGAL
0-17 IO.KIL,IO.WLB,IO.ATT
IO.DET
CONTROL 0-17 IO.KIL,IO.ATT,IO.DET
NOOP
0-17
ACP
0-17
LEGAL
20-37 IO.WVB
CONTROL 20-37
NOOP
20-37
ACP
20-37
D.PCB
BM UCB'S

l?RO=O
BMST=.
.IF
.WORD
• ENDC

DF M$$MUP
0

.WORD
.WORD
.BYTE
.BYTE
.WORD

$BMDCB
.-2
UC.QUE,O
O,US.OFL
DV.REC

• BMO: :
U.DCB
U.RED
U.CTL,U.STS
U.UNIT,U.ST2
U.CWl
8-13

SAMPLE DRIVER CODE
.WORD
.WORD
. WORD
.WORD
.WORD
.WORD
.WORD

a
a
72 •
$BMO

0,0

U.CW2
U.CW3
U.CW4
U.SCB
U.ATT
U.BUF,U.BUF+2
U.CNT

BMND=.
BM SCB'S
$BMO: :

.WORD
.WORD
.WORD
.WORD
,BYTE
.BYTE
.WORD
.WORD

0, .-2
0,0,0,0

a
a

0,0
0,0

a
a

S.LHD
S.FRK
S.KSS
S.PKT
S.CTM,S.ITM
S.STS,S.ST3
S.ST2
S.KRB - NO KRB SINCE NO CONTROLLER

$BMEND: :
. END
.TITLE
.IDENT

BMDRV - BLOCK MOVE DRIVER
/01/

;+
COPYRI(;HT (c) 1981,1982 BY DIGITAL EQUIPMENT CORPORATION.
ALL RI<;HTS RESERVED.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED
OR COP:ED ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE.

IS A SAMPLE DRIVER WHICH DEMONSTRATES HOW TO USE SOME
OF THE MORE SOPHISTICATED EXECUTIVE SERVICES AVAILABLE TO
]/0 DRIVERS. THIS DRIVER DEMONSTRATES:

~HIS

THE CHECKING OF ADDITIONAL USER BUFFERS PRIOR TO QUEUEING
AN I/O PACKET.

:~ )

USE OF THE CLOCK QUEUE FROM A DRIVER.

:: ) USE OF THE BUFFERED I/O MECHANISM
L )

USE OF THE GENERAL BUFFi;RED I/O KERNEL AST MECHANISM

~ )

USE OF REGION LOAD KERNEL ASTS

USE OF BLXIO

THIS DRIVER UNDERSTANDS PRECISELY ONE QIO, WHICH IS:
IO.WLB, ••••• ,(DEST-BUFFER,LENGTH,TIME,SRC-BUFFER)
OR
IO.WVB
THE DRIVER QUEUES A CLOCK BLOCK FOR TIME TICKS AND AT THE
END OF THAT TIME INTERVAL COPIES THE SOURCE BUFFER TO THE
8-14

SAMPLE. DRIVER CODE
DESTINATION BUFFER. IF POSSIBLE, THE REQUEST IS BUFFERED
INTERNALLY WHILE THE CLOCK REQUEST IS POSTED.

;.MCALL

CLKDF$, PKTDF$

CLKDF$
PKTDF$

;DEFINE CLOCK BLOCK OFFSETS
;DEFINE I/O PACKET OFFSETS

DEFINE MAXIMUM TRANSFER LENGTH WHICH WILL BE BUFFERED

BUFLIM

= 100.

DDT$

BM"NONE",NEW

** - BMINI - I/O INITIATION ENTRY POINT
INPUTS:
DRQIO (BECAUSE THE UC.QUE BIT IS SET IN THE UCB) SETS THE
REGISTERS TO THE FOLLOWING:
Rl
R4
R5

ADDRESS OF I/O PACKET
ADDRESS OF SCB
ADDRESS OF UCB

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.
I/O REQUEST PACKET FORMAT:
I.LNK
I.PRI/I.EFN
I.TCB
I.LN2
I.UCB
I.FCN
I.IOSB
I.IOSB+2
I.IOSB+4
I.IOSB+6
I.PRM
I.PRM+2
I.PRM+4
I.PRM+6
I.PRM+l0
I.PRM+12
I.PRM+14
I.PRM+16

I/O 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.
UCB ADDRESS OF DEVICE
I/O FUNCTION CODE (IO.WLB).
VIRTUAL ADDRESS OF I/O STATUS BLOCK.
RELOCATION BIAS OF I/O STATUS BLOCK.
I/O STATUS BLOCK ADDRESS (DISPLACEMENT + 140000).
VIRTUAL ADDRESS OF AST SERVICE ROUTINE.
RELOCATION BIAS OF SOURCE BUFFER.
BUFFER ADDRESS OF I/O TRANSFER.
NUMBER OF BYTES TO BE TRANSFERED.
TIME DISPLACEMENT IN TICKS
VIRTUAL ADDRES (TO BECOME RELOCATION BIAS) OF
DESTINATION BUFFER
FILLED IN WITH DISPLACEMENT ADDRESS OF DESTINATION
BUFFER
USED TO STORE BUFFER/CLOCK BLOCK ADDRESS
FILLED IN WITH PCB ADDRESS OF OUTPUT BUFFER

;.ENABL

LSB

8-15

SAMPLE DRIVER CODE
*****************************************************************

I NIT I A T ION

E N TRY

POI N T

*************************************~**************** ***********

BMINI:

; PRE-QUEUING INITIALIZE ENTRY POINT
*****************************************************************

'"
'"

ADDRESS CHECK THE SOURCE BUFFER WHILE THE TASKS
CONTEXT IS LOADED, AND FILL IN THE NECESSARY
PARAMETERS IN THE I/O PACKET

*
*

*
*
*

~~**************************************************** ************

r1QV

MOV
MOV

RI, R3
I. PRM+10 (R1) ,RO
I.PRM+4(R3) ,R1

COpy ADDRESS OF I/O PACKET
GET VIRTUAL ADDRESS OF SOURCE BUFFER
AND LENGTH OF SOURCE BUFFER

-~---------------------------------------------------------------+

THE INPUT PARAMETERS FOR $CKBFR ARE:
RO = STARTING ADDRESS OF BLOCK TO BE CHECKED
R1 = LENGTH OF THE BLOCK TO BE CHECKED
$ATTPT = ADDRESS OF I.AADA IN I/O PACKET
(ESTABLISHED IN DRQIO)
CURRENT TASK HEADER MUST BE MAPPED THROUGH APR 6
(ESTABLISHED BY DIRECTIVE DISPATCHER)
THE OUTPUT PARAMETERS ARE:
C = 0 IF CHECK AND PACKET UPDATE SUCCESSFUL
I.AADA OR I.AADA IN PACKET POINTS TO
RELATED ADB, P.IOC, A.IOC INCREMENTED
1 IF CHECK UNSUCCESFUL OR I.AADA, I.AADA
C
ALREADY FILLED IN

I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I

~---------------------------------------------------------------+

$CKBFR
3CC

10$

CHECK BUFFER, INCREMENT A.IOC AND
P.IOC FOR APPROPRIATE REGIONS
IF CC ALL WAS OK

*****************************************************************

*
*
SOURCE BUFFER WAS ILLEGAL, FINISH I/O HERE
*
*
*******************************************************************
iIE.SPC&377,RO
R1

SET COMPLETION STATUS
AND NUMBER OF BYTES TRANSFERRED

8-16

SAMPLE DRIVER CODE

+---------------------------------------------------------------+
THE INPUT PARAMETERS FOR $IOFIN ARE:
FIRST WORD OF I/O STATUS TO RETURN
SECOND WORD OF I/O STATUS TO RETURN
ADDRESS OF I/O PACKET

RO
Rl
R3

THE OUTPUT PARAMETERS ARE:
R4 IS DESTROYED

I
I
I
I
I
I
I
I
I
I
I

~---------------------------------------------------------------+

CALLR

$IOFIN

; COMPLETE I/O AND EXIT DRIVER

,~****************************************************************

*
*

BUFFER WAS LEGAL, CONVERT VIRTUAL ADDRESS TO
ADDRESS DOUBLEWORD AND STORE PARAMETERS

*
*
*
*

*****************************************************************

+---------------------------------------------------------------+I
II

THE INPUT PARAMETERS FOR $RELOC ARE:

I
I
I
I
I

I
I

= USER VIRTUAL ADDRESS TO RELOCATE

THE OUTPUT PARAMETERS ARE:
Rl
R2

APR6 RELOCATION BIAS OF USER BUFFER
DISPLACEMENT IN BLOCK + 140000

I
I

I
I
I
I
I

I
I

+---------------------------------------------------------------+
10$:

CALL
MOV
MOV
CLR

$RELOC
Rl,I.PRM+10(R3)
R2,I.PRM+12(R3)
I.PRM+16(R3)

RELOCATE BUFFER ADDRESS
SAVE APR BIAS OF SOURCE BUFFER
AND DISPLACEMENT ADDRESS
INDICATE NOT BUFFERED I/O

*****************************************************************

*
*
*

NOW QUEUE THE PACKET IN THE DEVICE QUEUE

MOV
MOV

R4,RO
R3,Rl

*
*
*

*****************************************************************
COPY POINTER TO I/O QUEUE LISTHEAD
AND ADDRESS OF I/O PACKET

+---------------------------------------------------------------+

I
I
I
I
I
I
I

THE INPUT PARAMETERS FOR $QINSP ARE:
RO
Rl

ADDRESS OF THE TWO WORD LISTHEAD
ADDRESS OF THE PACKET TO BE INSERTED

NO OUTPUT PARAMETERS

I
I
I
I
I
I
I

+---------------------------------------------------------------+
CALL

$QINSP

; INSERT PACKET IN QUEUE

8-17

SAMPLE DRIVER CODE

*****************************************************************
*
*

*
*

BEGIN SERIAL PROCESSING OF I/O PACKETS

*
*****************************************************************
~---------------------------------------------------------------+

I
I
I
I
I
I
I
I
I
I
I
I
I
I
I

THE INPUT PARAMETERS FOR $GTPKT ARE:
R5

= ADDRESS OF THE UCB OF REQUESTING UNIT

THE OUTPUT PARAMETERS ARE:
C = 0 IF A REQUEST WAS SUCCESSFULLY DEQUEUED
Rl = ADDRESS OF THE I/O PACKET
R2
PHYSICAL UNIT NUMBER
R3
CONTROLLER INDEX
R4
SCB ADDRESS OF CONTROLLER
R5
UCB ADDRESS OF UNIT
C = 1 IF UNIT BUSY OR NO PACKETS QUEUED

+---------------------------------------------------------------+
BMINl::ALL
BCC
RETURN
20$:

$GTPKT
20$

ATTEMPT TO GET A REQUEST
IF CC WE GOT ONE
DEVICE BUSY OR QUEUE EMPTY
; REFERENCE LABEL

*****************************************************************

*
*
*

ATTEMPT TO ALLOCATE CLOCK BLOCK

*
*
*****************************************************************
"'10V
~OV

Rl, R3
#C.LGTH,Rl

COpy I/O PACKET ADDRESS
SET LENGTH OF CLOCK BLOCK

~---------------------------------------------------------------+

THE INPUT PARAMETERS FOR $ALOCB ARE:
Rl = SIZE OF THE BLOCK TO ALLOCATE (IN BYTES)
THE OUTPUT PARAMETERS ARE:
C = 0 IF A BLOCK WAS SUCCESSFULLY ALLOCATED
RO = ADDRESS OF THE ALLOCATED BLOCK
Rl = LENGTH OF THE ALLOCATED BLOCK
C = 1 IF NO BLOCK ISCURRENTLY AVAILABLE

I
I
I
I
I
I
I
I
I
I
I
I

+---------------------------------------------------------------+
:ALL
BCC
"10V

$ALOCB
30$
#IE.NOD&377,RO

ATTEMPT TO ALLOCATE
IF CC SUCCESSFUL
S·ET I/O STATUS

8-18

SAMPLE DRIVER CODE
+---------------------------------------------------------------+
THE INPUT PARAMETERS FOR $IOALT ARE:
RO
Rl
R2
R5

FIRST WORD OF I/O STATUS BLOCK
SECOND WORD OF I/O STATUS BLOCK
STARTING AND FINAL RETRY COUNTS
(IF AN ERROR LOGGING DEVICE)
UCB ADDRESS OF UNIT TO COMPLETE

THE OUTPUT PARAMETERS ARE:
R4 IS DESTROYED

I
I
I
I
I
I
I
I
I
I
I
I
I

+---------------------------------------------------------------+

30$:

CALL
BR
MOV

$IOALT
BMINI
RO,I.PRM+14(R3)

AND COMPLETE THE I/O
GO LOOK FOR MORE WORK
SAVE ADDRESS OF CLOCK BLOCK

*****************************************************************

*
*
*

DETERMINE IF I/O REQUEST IS BUFFERABLE

*
*
*****************************************************************
+---------------------------------------------------------------+

I
I
I
I
I
I
I
I
I
I

THE INPUT PARAMETERS FOR $TSTBF ARE:
R3

= ADDRESS OF I/O PACKET TO TEST

THE OUTPUT PARAMETERS ARE:
C O I F REQUEST MAY BE BUFFERED
C
1 IF REQUEST MAY NOT BE BUFFERED

I
I
I
I
I
I
I
I
I
I

+---------------------------------------------------------------+
CALL
BCS

$TSTBF
40$

TEST FOR BUFFERABLE I/O REQUEST
IF CS CAN'T ALLOCATE A BUFFER

*****************************************************************

ATTEMPT TO ALLOCATE A BUFFER
*
*
*
*
*****************************************************************
MOV
CMP
BHI

I.PRM+4(R3),Rl
Rl,iBUFLIM
40$

GET LENGTH OF BUFFER
BIGGER THAN BUFFER LIMIT ?
IF HI YES, DON'T BUFFER

8-19

SAMPLE DRIVER CODE

+---------------------------------------------------------------+
I
I
I
I
I
I

THE INPUT PARAMETERS FOR $ALOCB ARE:
Rl

= SIZE OF THE BLOCK TO ALLOCATE

(IN BYTES)

THE OUTPUT PARAMETERS ARE:
C = 0 IF A BLOCK WAS SUCCESSFULLY ALLOCATED
RO = ADDRESS OF THE ALLOCATED BLOCK
Rl = LENGTH OF THE ALLOCATED BLOCK
C = 1 IF NO BLOCK ISCURRENTLY AVAILABLE

+---------------------------------------------------------------+
CALL
BCS

$ALOCB
40$

TRY TO ALLOCATE BUFFER
IF CS COULDN'T GET ONE

*****************************************************************
*
COpy USER BUFFER TO INTERNAL BUFFER
*
*
*
*
*****************************************************************
,~

HOV
HOV
~10V

HOV
HOV
HIC
HIS
HOV

RO,R4
R3,RS
I. PRM+4 (RS) ,RO
I. PRM+I0 (RS) ,Rl
I • PRM + 1 2 (R S) , R2
#140000,R2
#120000,R2
R4,I.PRM+I0(RS)

SET ADDRESS OF DESTINATION BUFFER
SAVE ADDRESS OF I/O PACKET
SET LENGTH OF TRANSFER
SET BIAS OF SOURCE BUFFER
AND DISPLACEMENT
STRIP OFF APR6 ADDRESS BITS
AND SUBSTITUTE APRS
SET INTERNAL BUFFER ADDRESS INTO PACKET

~---------------------------------------------------------------+

THE INPUT PARAMETERS FOR $BLXIO ARE:
RO
NUMBER OF BYTES TO MOVE
Rl
SOURCE APR S BIAS
R2
SOURCE DISPLACEMENT
R3
DESTINATION APR6 BIAS
R4 = DESTINATION DISPLACEMENT
THE OUTPUT PARAMETERS ARE
RO ALTERED
Rl,R3 PRESERVED
R2,R4 POINT TO LAST BYTE OF SOURCE/DESTINATION +1
~---------------------------------------------------------------+

CALL

$BLXIO

; COPY TO INTERNAL BUFFER

***********************************.*****************************
*
*

*
*

CONVERT TO BUFFERED I/O REQUEST

t-"OV

RS,R3

*
*

*****************************************************************
; COpy I/O PACKET ADDRESS BACK

8-20

SAMPLE DRIVER CODE

+---------------------------------------------------------------+
I

THE INPUT PARAMETERS FOR $INIBF ARE:

I
I

R3 = ADDRESS OF THE I/O PACKET TO BUFFER

I
I

NO OUTPUT PARAMETERS.

I
I

CALL

$INIBF

~
11

+---------------------------------------------------------------+
; INITIALIZE BUFFERED I/O

*****************************************************************

QUEUE THE CLOCK BLOCK
*
*
*******************************************************************
40$:

MOV
MOV
CLR
~10V

MOV
MOV

I.PRM+14(R3) ,RO ;
iCLKSRV,C.SUB(RO)
Rl
I.PRM+6(R3) ,R2
iC.SYST,R4
R3,R5

GET ADDRESS OF CLOCK BLOCK
; SET ADDRESS OF SUBROUTINE
HIGH ORDER DELTA TIME
LOW ORDER PART
SET REQUEST TYPE
USE PACKET ADDRESS AS IDENTIFIER

+----~----------------------------------------------------------+

I
I

THE INPUT PARAMETERS FOR $CLINS ARE:

I
I
I

RO = ADDRESS OF THE CLOCK BLOCK TO QUEUE
Rl
HIGH ORDER HALF OF DELTA TIME
R2
LOW ORDER HALF OF DELTA TIME
R4
REQUEST TYPE
R5
ADDRESS OF REQUESTING TASK OR IDENTIFIER
NO OUTPUT PARAMETERS.

I
I
I
I
I
I
I
I

+---------------------------------------------------------------+
CALLR

$CLINS

QUEUE CLOCK BLOCK AND TEMPORARILY
EXIT THE DRIVER

'f****************************************************************
C LaC K

E N TRY

POI N T

*
*
*

*****************************************************************
,~****************************************************************

CHECK TO SEE IF THE I/O WAS BUFFERED

*
*
*

*****************************************************************
CLKSRV:

~10V
~rST

BNE

C • TC B (R 4) ,R 5
I • PRM + 1 6 (R 5 )
50$

GET ADDRESS OF I/O PACKET
WAS IT BUFFERED I/O
IF NE YES, GO QUEUE KERNEL AST

'f****************************************************************
COULDN'T BUFFER, PERFORM COpy HERE AND NOW

*
*
*

*****************************************************************

8-21

SAMPLE DRIVER CODE

rv OV
rvov
rvov
EIC
EIS

rvov
f'lOV

I. PRM+4 (RS) , RO
I • PRM + 1 0 (R S) , R 1
I • PRM + 1 2 (R S) , R 2
#140000,R2
#120000,R2
I • PRM (R S) , R 3
I.PRM+2(RS) ,R4

SET LENGTH TO TRANSFER
BIAS OF SOURCE BUFFER
DISPLEACEMENT OF SOURCE
STRIP OFF APR6 ADDRESS BITS
AND CONVERT TO APRS
SET BIAS OF DESTINATION
SET DISPLACEMENT

~---------------------------------------------------------------+

THE INPUT PARAMETERS FOR $BLXIO ARE:
RO
Rl
R2
R3
R4

NUMBER OF BYTES TO MOVE
SOURCE APR S BIAS
SOURCE DISPLACEMENT
DESTINATION APR6 BIAS
DESTINATION DISPLACEMENT

THE OUTPUT PARAMETERS ARE
RO ALTERED
RI,R3 PRESERVED
R2,R4 POINT TO LAST BYTE OF SOURCE/DESTINATION +1

I
I
I
I
I
I
I
I
I
I
I
I
I
I
I

4---------------------------------------------------------------+
CALL
f'I':OV

rvov

$BLXIO
I.PRM+14(RS) ,RO
#C.LGTH,Rl

COPY BUFFER
GET ADDRESS OF CLOCK BLOCK
GET LENGTH OF CLOCK BLOCK

+---------------------------------------------------------------+
I
I
I
I
I
I

THE INPUT PARAMETERS FOR $DEACB ARE:

RO
RI

I
I
I
I

ADDRESS OF BLOCK TO DEALLOCATE
LENGTH OF BLOCK TO DEALLOCATE

NO OUTPUT PARAMETERS.

I
I

~---------------------------------------------------------------+

CALL
BMSUC:

rv'ov
rvov

BMDON:

r.rov

r-OV

$DEACB
RS,R3
#IS.SUC&377,RO
I.PRM+4(R3) ,Rl
I.UCB(R3) ,RS

DEALLOCATE IT
COPY PACKET ADDRESS FOR $IODON
SET FINAL I/O STATUS
AND LENGTH OF TRANSFER = REQUESTED
GET UCB ADDRESS OF DEVICE

~---------------------------------------------------------------+

I
I
I
I

,
,

THE INPUT PARAMETERS FOR $IODON ARE:
RO
RI
R2

I
,

I
I
I
I
,

FIRST WORD OF I/O STATUS BLOCK
SECOND WORD OF I/O STATUS BLOCK
STARTING AND FINAL RETRY COUNTS
(IF AN ERROR LOGGING DEVICE)
UCB ADDRESS OF UNIT TO COMPLETE

THE OUTPUT PARAMETERS ARE:
R4 IS DESTROYED

I
I
I
I
I
I
I
I
I
I
I
I
I

4---------------------------------------------------------------+

8-22

SAMPLE DRIVER CODE
CALL
BR

$IODON
BMINI

; COMPLETE THE I/O
; GO LOOK FOR MORE WORK

It****************************************************************
BUFFERED I/O, CONVERT I/O PACKET TO KERNEL
AST AND EXIT FROM DRIVER

*
*
*
*

*****************************************************************
50$:

~10V
~10V
~rST

~10V

t10V
MOV
~10V

R4,R3
I • TCB (R 5) , RO
(R4)+
#AK.GBI, (R4)+
KISAR5,(R4)+
#KATSRV, (R4)+
R5,(R4)+

COpy CLOCK BLOCK ADDRESS FOR $REQUE
POINT TO TCB OF TASK
SKI P LINK WORD
SET A.CBL=AK.GBI
SET APR BIAS OF SERVICE ROUTINE
SET ADDRESS OF PROCESSING ROUTINE
SAVE I/O PACKET ADDRESS IN CLOCK BLOCK

+---------------------------------------------------------------+

I
I
I
I
I
I
I
I

THE INPUT PARAMETERS FOR $REQUE ARE:
RO
R3

TCB ADDRESS TO QUEUE AST BLOCK TO
ADDRESS OF THE PACKET TO QUEUE

NO OUTPUT PARAMETERS.

I
I
I
I
I
I
I
I

+---------------------------------------------------------------+
CALLR

$REQUE

; QUEUE AST TO TASK

It****************************************************************
K ERN E L

A S T

E N TRY

POI N T

*
*
*

It****************************************************************
1~****************************************************************

GET PCB ADDRESS AND SEE IF PARTITION IS RESIDENT

*
*
*

1~****************************************************************

KATSRV:

~10V
~-10V

BEQ

10(R3),R5
I.PRM+16(R5) ,Rl
70$

GET I/O PACKET ADDRESS
GET PCB ADDRESS OF BUFFER REGION
IF EQ THERE IS NO COpy TO PERFORM

+---------------------------------------------------------------+
THE INPUT PARAMETERS FOR $TSPAR ARE:
RO
Rl
R5

ADDRESS OF THE PACKET (THE KERNEL AST BLOCK)
PCB ADDRESS OF THE PCB CONTAINING THE BUFFER
TCB ADDRESS OF ASSOCIATED TASK

THE OUTPUT PARAMETERS ARE
C
C

o IF REGION IS RESIDENT AND CAN BE ACCESSED
1 IF REGION IS NOT RESIDENT AND AST HAS
BEEN QUEUED

I
I
I
I
I
I
I
I
I
I
I
I
I

r---------------------------------------------------------------+
CALL
BCC

$TSPAR
60$

REGION IN MEMORY ?
IF CC REGION IN MEMORY

8-23

SAMPLE DRIVER CODE
*~***************************************************************

A REGION AST WAS QUEUED. BUMP BUFFERED I/O COUNT
*
*
BACK UP TO FORCE I/O RUNDOWN IN CASE OF ABORT AND
*
*
EXIT AST SERVICE ROUTINE.
*
*
*
*
*t***************************************************************
M)V
I~CB

I.TCB(RS) ,RO
T.TIO(RO)

RETURN

; GET TCB ADDRESS
; BUMP BUFFERED I/O COUNT
; EXIT AST SERVICE ROUTINE

*****************************************************************
*
*

*
*

PERFORM BUFFER COpy OPERATION

MOV
INCB
MOV
MOV
MOV
ADD
MOV

I • TC B (R S) , R0
T.IOC(RO)
I.PRM+4(R5) ,RO
I.PRM+I0(RS) ,R2
P.REL(Rl),R3
I • PRM (R S) , R 3
I. PRM+2 (RS) ,R4

*
*****************************************************************
60$:

GET TCB ADDRESS OF TASK
ADJUST REAL I/O COUNT UPWARDS
GET COUNT OF BYTES
SET SOURCE BUFFER ADDRESS
GET STARTING BIAS OF PARTITION
AND ADD IN OFFSET
SET DISPLACEMENT

+---------------------------------------------------------------+

I
I
I
I
I

I
I

THE INPUT PARAMETERS FOR $BLXIO ARE:
RO
Rl
R2
R3

NUMBER OF BYTES TO MOVE
SOURCE APR S BIAS
SOURCE DISPLACEMENT
DESTINATION APR6 BIAS
DESTINATION DISPLACEMENT

RLl
I
I
THE OUTPUT PARAMETERS ARE
I
I
RO ALTERED
I
Rl,R3 PRESERVED
I
R2,R4 POINT TO LAST BYTE OF SOURCE/DESTINATION +1
I
I
+---------------------------------------------------------------+

CALL
f\\OV
HOV

$BLXIO
I.PRM+I0(RS),RO
I.PRM+4(RS) ,Rl

COpy THE BUFFER
GET BUFFER ADDRESS AGAIN
GET LENGTH OF BUFFER

+---------------------------------------------------------------+
THE INPUT PARAMETERS FOR $DEACB ARE:
RO
Rl

ADDRESS OF BLOCK TO DEALLOCATE
LENGTH OF BLOCK TO DEALLOCATE

NO OUTPUT PARAMETERS.
-~---------------------------------------------------------------+

CALL

$DEACB

; DEALLOCATE IT

*****************************************************************
*
*
IF THIS WASN'T A REGION LOAD AST, FINISH THE I/O

*
*

t****************************************************************

8-24

SAMPLE DRIVER CODE
70$:

MOV
TST
BNE

I.PRM+14(R5) ,RO
(RO)
80$

RETRIEVE AST BLOCK ADDRESS
WAS THIS A REGION LOAD AST ?
IF NE YES

MOV

fJ:C.LGTH,Rl

SET LENGTH OF CLOCK BLOCK

+--------------------------------------~------------------------~

I
I
I
I
I
I
I
I

THE INPUT PARAMETERS FOR $DEACB ARE:
RO
Rl

ADDRESS OF BLOCK TO DEALLOCATE
LENGTH OF BLOCK TO DEALLOCATE

NO OUTPUT PARAMETERS.

I
I
I
I
I
I
I
I

+---------------------------------------------------------------+
C,~LL

MOV
MOV
M'rPD$
MOV
M'rPD$
CLR
MOV
JI~P

$DEACB
I • I OS B ( R 5) , R3
fJ:IS.SUC&377,-(SP)
(R3)
I. PRM+4 (R5) , - (SP)
(R3 )
I.IOSB(R5)
R5,R3
BMSUC

DEALLOCATE CLOCK BLOCK
GET VIRTUAL ADDRESS OF I/O STATUS BLOCK
; SET FIRST I/O STATUS WORD
WRITE FIRST WORD OF STATUS (MAY TRAP)
; SET SECOND WORD OF I/O STATUS
WRITE SECOND WORD (MAY TRAP)
PREVENT $IODON ATTEMPT TO WRITE STATUS
COPY I/O PACKET ADDRESS
FINISH IN COMMON CODE

*****************************************************************
*
*
RECONVERT REGION LOAD AST TO A TASK AST
*
*
*
*
*'****************************************************************
80$:

MOV
CLR
MOV

RO,R3
10(RO)
I.TCB(R5) ,RO

COpy BLOCK ADDRESS
INDICATE NO BUFFER NEXT TIME
GET TCB ADDRESS

+----------------------------------------------------------------+
I
I
I
I
I
I
I
I

THE INPUT PARAMETERS FOR $REQUE ARE:
RO
R3

TCB ADDRESS TO QUEUE AST BLOCK TO
ADDRESS OF THE PACKET TO QUEUE

NO OUTPUT PARAMETERS.

I
I
I
I
I
I
I
I

+._--------------------------------------------------------------+
C}\LLR

$REQUE

; RE-QUEUE TASK AST AND EXIT AST SERVICE

*1~***************************************************************

*
*
*

MISCELLANEOUS ENTRY POINTS

*
*

*,~***************************************************************

*"***************************************************************

*
*
*
*
*
*

CAN C E L

E N TRY

POI N T

WE COULD DEQUEUE PENDING CLOCK REQUEST, ETC HERE,
BUT WE DON'T, WE JUST LET THEM COMPLETE LATER

*
*
*
*
*
*

*~r***************************************************************

8-25

SAMPLE DRIVER CODE
BMCAN:
*****************************************************************

*
*
*
SINCE THERE'S NO PHYSICAL DEVICE TO TIME OUT, NO-OP
*
*
*****************************************************************
*
*
*
*

TIM E 0 U T

E N TRY

POI N T

BMOUT:
*****************************************************************

*
*
*
*

POW E R F A I L

E N TRY

POI N T

POWERFAIL DOESN'T AFFECT NON-EXISTENT DEVICES

*
*

*****************************************************************

BMPWF:
*****************************************************************

*
*
*
*
*
*

S TAT U S

C HAN G E

E N TRY

POI N T S

DON'T NEED TO TOUCH NON-EXISTENT DEVICE, JUST LET
EXEC PUT DEVICE ON/OFF LINE

*
*
*
*
*

*****************************************************************

BMKRB:
BMUCB:
RETURN

ALL THESE ARE NO-OP FOR NOW

• END

8-26

APPENDIX A
HSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

This clppendix describes the RSX-IIM-PLUS system macros that
symbolic offsets for data structures listed in Table A-I.

supply

The data structures are defined by macros in the Executive macro
library.
To reference any of the data structure offsets from your
code, include the macro name in an .MCALL directive and invoke the
macro. For example:
.MCALL DCBDF$
DCBDF$

iDefine DCB offsets
NOTE

All physical offsets and bit definitions
are subject to change in future releases
of the operating system.
Code that
accesses system data structures should
always use the symbolic offsets rather
than the physical offsets.
The first two arguments, <:> and <=>, make all definitions global. If
they are left blank, the definitions will be local. The SYSDEF
argument causes the variable part of a data structure to be defined.
the
All of these macros
are
in
Executive
macro
library,
LB: [1,I]EXEMC.MLB.
All except FIIDF$, ITBDF$, MTADF$, OLRDF$, and
Executive
definition
library,
SHDDF$
are
also
in
the
LB: [1,I]EXELIB.OLB.
Table A-I
Summary of System Data Structure Macros
Macro

Data Structures

Arguments

ABODF$

<:>,<=>

Task abort and termination
notification message codes

ACNDF$

<:>,<=>

Accounting data structures
(user account block, task account
block, system account block)

CLKDF$

<:>,<=>

Clock queue control block
(continued on next page)

A-I

R~)X-IIM-PLUS

SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

Table A-I
(Cont.)
Summary of System Data Structure Macros
Macro

Data Structures

Arguments

CTBDF$

<:>,<=>

Controller table

DCBDr$

<:>,<=>,SYSDEF

Device control block

EPKDF$

<:>,<=>

Error message block

FIlDI'$

<:>,<=>,SYSDEF

Files-II data structures
(volume control block, mount list
entry, file control block, file
window block, locked block list
node)

HDRDF'$

<:>,<=>

Task header and window block

HWDDF'$

<:>,<=>,SYSDEF

Hardware register addresses and
feature mask definitions

ITBDF'$

<:>,<=>,SYSDEF

Interrupt transfer block

KRBDF'$

<:>,<=>

Controller request block

LCBDF'$

<:>,<=>

Logical assignment control block

MTADF$

<:>,<=>

ANSI magtape data structures
(volume set control block)
On-line reconfiguration interface

OLRDF$
PCBDF'$

<:>,<=>,SYSDEF

Partition control block and
attachment descriptor

PKTDF$

<:>,<=>

I/O packet, AST control block,
offspring control block, group
global event flag control block,
and CLI parser block

SCBDF$

<:>,<=>,SYSDEF

Status control block and UMR
assignment block

SHDDF$

<:>,<=>

Shadow recording linkage block

TCBDF$

<:>,<=>,SYSDEF

Task control block

UCBDF$

<:>,<=>,TTDEF,SYSDEF

Unit control block

A-2

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

ABODF$
ABODF$
TASK ABORT CODES
NOTE: S.COAD-S.CFLT ARE ALSO SST VECTOR OFFSETS
;

S.CACT=-4.
S.CEXT=-2.
S.COAD=O.
S.CSGF=2.
S.CBPT=4.
S.CIOT=6.
S.CILI=8.
S.CEMT=10.
S.CTRP=12.
S.CFLT=14.
S.CSST=16.
S.CAST=18.
S. CABO=20.
S.CLRF=22.
S.CCRF=24.
S.IOMG=26.
S.PRTY=28.
S. CPMD=30.
S.CELV=32.
S.CINS=34.
S.CAFF=36.
S.CCSM=38.
S.COTL=40.

;TASK STILL ACTIVE
;TASK EXITED NORMALLY
;ODD ADDRESS AND TRAPS TO 4
;SEGMENT FAULT
;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 REQUEST FAILURE
;TASK CHECKPOINT READ FAILURE
;TASK EXIT WITH OUTSTANDING I/O
;TASK MEMORY PARITY ERROR
;TASK ABORTED WITH PMD REQUEST
iTI: VIRTUAL TERMINAL WAS ELIMINATED
;TASK INSTALLED IN 2 DIFFERENT SYSTEMS
iTASK ABORTED DUE TO BAD AFFINITY (REQUIRED
iBUS RUNS ARE OFFLINE OR NOT PRESENT)
;BAD CSM PARAMETERS OR BAD STACK
iTASK HAS RUN OVER ITS TIME LIMIT

TASK TERMINATION NOTIFICATION MESSAGE CODES
;

T.NDNR=O
T.NDSE=2
T.NCWF=4
T.NCRE=6
T.NDMO=8.
T.NUER=10.
T.NLDN=12.
T.NLUP=14.
T.NCFI=16.
T.NUDE=18.
T.NMPE=20.
T.NKLF=22.
T.NAAF=24.
T.NTAF=26.
T.NDEB=28.
T.NRCT=30.
T.NWBL=32.

;DEVICE NOT READY
;DEVICE SELECT ERROR
iCHECKPOINT WRITE FAILURE
;CARD READER HARDWARE ERROR
;DISMOUNT COMPLETE
;UNRECOVERABLE ERROR
;LINK DOWN (NETWORKS)
;LINK UP (NETWORKS)
;CHECKPOINT FILE INACTIVE
;UNRECOVERABLE DEVICE ERROR
;MEMORY PARITY ERROR
;UCODE LOADER NOT INSTALLED
iACCOUNTING ALLOCATION FAILURE
;ACCOUTING TAB ALLOCATION FAILURE
;TASK HAS NO DEBUGGING AID
iREPLACEMENT CONTROL TASK NOT INSTALLED
;WRITE BACK CACHING DATA LOST
iUNIT WRITE LOCKED

A-3

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

ACNDF$
ACNDF$
ACCOUNTING BLOCK OFFSET AND STATUS DEFINITIONS
FOR EACH TRANSACTION TYPE.
HEADER COMMON TO ALL TRANSACTIONS
.ASECT
.BLKW
.BLKB
.BLKB
.BLKW

1
1
1

00001:~

.=0
B. LNK:
B.TYP:
B.LEN:
B.TIM:
B.HID=.
B. urD:

.BLKW

000011i
00002(1

B.ACN:
B.TID:

.BLKW
.BLKB

1
1

.BLKB

OOOOO()
ooooo:~

00000:;
00000,\
0000l:~

00002_
00002:~

00002::

B.HEND=.
$$$HLN=.

iLINK TO NEXT IN SYSLOG QUEUE
iTRANSACTION TYPE
iTRANSACTION LENGTH
iENDING TIME OF TRANSACTION
iSTART OF HEADER IDENTIFICATION AREA
iUNIQUE SESSION IDENT
iFIRST WORD-RADSO, SECOND-BINARY
iACCOUNT NUMBER
iASCII TERMINAL TYPE (V,T,B OR C)
i (VIRTUAL,REAL,BATCH, OR CONSOLE)
iUNIT NUMBER
iEND OF HEADER ID AREA
iHEADER LENGTH

ACCUMULATION FIELDS FOR TAB, UAB, AND SAB
i

00002;
00002(
00003~

00003f
00004~

OOOOS(
OOOOSf
00006;
00006~
00006~

B.CPU:
.BLKW
B.DIR:
.BLKW
B.QrO:
.BLKW
B.TAS:
.BLKW
B.MEM:
.BLKW
B.BEG:
.BLKW
B.CPUL: .BLKW
B. PNT:
.BLKW
B.STM:
.BLKB
$$$TLN=.

2
2
2
2
3
3
2
1
1

iTOTAL CPU TIME USED
iTOTAL DIRECTIVE COUNT
iTOTAL QIO$ COUNT
iTOTAL TASK COUNT
iRESERVED
iBEGINNING/LOGIN TIME
i CPU LIMIT
iPOINTER TO HIGHER LEVEL TOTALS
iSTATUS MASK
iTOTAL'S LENGTH

USER ACCOUNT BLOCK (UAB)
NOTE:
UAB'S MUST END ON A WORD BOUNDRY
i

00006:
000066
000070
000072
000074
000102
000104
000112
000130
000131
000132
000002

.=$$$TLN
B.USE:
.BLKB
B.ACT:
.BLKW
B.UUIC: .BLKW
B.UCB:
.BLKW
B.LGO:
.BLKW
B.ULNK: .BLKW
B.RNA:
.BLKW
B. NAM:

• BLKB
.BLKB
.BLKB

B.ULEN=.
$$$=<.+77>/100

1
1
1

1
3
1

14.
1
1

iSTART AFTER TOTALS
iUSE COUNT
iNUMBER OF CURRENTLY ACTIVE TASKS
iLOGIN UIC
iPOINTER TO UCB
iLOGOFF TIME
iLINK TO NEXT UAB
iLOC IN SYSTEM ACCNT FILE
i (OFFSET,VBN-HI,VBN-LO)
iLAST NAME OF USER
iFIRST INITIAL OF USER
iUNUSED BYTE
iUAB LENGTH
iUAB LENGTH (ROUNDED UP TO 32 WORD BOUND)

A-4

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

ACNDF$ (Cont.)

TASK ACCOUNT BLOCK (TAB)
NOTE: THE TAB MUST END ON A WORD BOUNDRY
i

000065
000066
000072
000074
000076
000100
000102
000104
000110
000114
000120
000124
000002

.=$$$TLN
.BLKB
B.PRI:
1
B. T'NAM: • BLKW
2
B. T'CB:
1
• BLKW
B.TST3: .BLKW
1
.BLKW
1
B.CUIC: .BLKW
1
B.PUIC: • BLKW
1
B.CTXT: .BLKW
2
B.TCKP: .BLKW
2
B.OVLY: .BLKW
2
B.EXST: .BLKW
2
B.TLEN=.
B.TBLK=<.+77>/100

iSTARTS AFTER TOTALS
iHIGHEST RUNNING PRIORITY
iTASK NAME
iTCB ADDRESS
iT.ST3 FROM TASK'S TCB
iRESERVED FOR FUTURE STATUS BITS
jCURRENT UIC OF TASK
iPROTECTION UIC OF TASK
jNUMBER OF CONTEXT LOADS
jTIMES TASK HAS BEEN CHECKPOINTED
jNUMBER OF DISK OVERLAY LOADS
jEXIT STATUS AND ABORT CODE
jTAB LENGTH
jNUMBER OF SEC POOL BLOCKS IN TAB

SYSTEM ACCOUNT BLOCK (SAB)
j

000065
000066
000070
000072
000076
000102
000106
000112
000120
000122
000124
000126
000134
000136
000140
000144
000146
000154
000160
000162

.=$$$TLN
B. SHDN: .BLKB
.BLKW
B.UHD:
.BLKW
B.ULO:
B.ULT:
.BLKW
.BLKW
B.CKP:
.BLKW
B.SHF:
B.RND:
.BLKW
.BLKW
B.FID:
B.DVNM: .BLKB
B.UNIT: .BLKW
B. EXTS: • BLKW
B.LSCN: .BLKW
B. SCNR : • BLKW
B.DSCN: .BLKW
B.STSP: .BLKW
B.SYSM: .BLKW
B.CKUS: .BLKW
B.CKSP: .BLKW
B • CKA L : • BLKW
B.SLEN=.

1
1
1

2
2
2
2

3
2

1
1
3
1
1
2

1
3
2

jSTART AFTER TOTALS
jACCOUNTING SHUTDOWN REASON CODE
JUAB LISTHEAD
jNUMBER OF USERS CURRENTLY LOGGED ON
jTOTAL NUMBER OF LOGONS
jTOTAL NUMBER OF CHECKPOINTS
jTOTAL NUMBER OF SHUFFLER RUNS
jNUMBER OF CPU INTERVALS ROUNDED UP TO 1
jFILE-ID OF TRANSACTION FILE
jDEVICE OF TRANSACTION FILE
jUNIT
OF TRANSACTION FILE
jEXTEND SIZE FOR TRANSACTION FILE
jTIME OF LAST SCAN
jSCAN RATE IN SECONDS
jSTATISTICAL SCAN RATE (IN SEC)
jRESERVED
jRESERVED
jRESERVED
jRESERVED
jRESERVED
jSAB LENGTH

NEW FIELDS FOR EXTENDED ACCOUNTING
j

000162
000202
000222
000242
000262
000302
000322
000342
000362
000366
000372
000376

B.CPUT:
B.CTXP:
B • I DC T :
B. QI OC:
B • MI OC:
B.AIOC:
B.IPSN:
B • I PR C:
B.CKEX:
B.CFCL:
B.CFRK:
B.TLOD:

.BLKW
.BLKW
• B L KW
• BLKW
• B L KW
.BLKW
.BLKW
• B L KW
.BLKW
.BLKW
.BLKW
.BLKW

8.
8.

8.
8.
8.
8.
8.
2
2
2
2

jCPU TIME USED PER PROCESSOR
jNUMBER OF CONTEXT SWITCHES (PER PROC)
jNUMBER OF IDLE LOOP ENTRIES (PER PROC)
jNUMBER OF I/O INITIATIONS (PER PROC)
jMASS STORE I/O COMPLETIONS (PER PROC)
jALL I/O COMPLETIONS (PER PROC)
jIP INTERRUPTS SENT (PER PROC)
jIP INTERRUPTS RCVD (PER PROC)
jCHECKPOINT DUE TO EXTEND TASKS
jCALLS TO CFORK
jCFORK FORKS
jTASK LOADS
A-5

RSX-11M-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

ACNOF$ (Cont.)
00040~

00040E
00034E

OOOOOE

B.RLOD: .BLKW
2
82.
.BLKB
B.SSBL=.-B.SLEN
$$$=<.+77>/100

iREGION LOADS
iBUMP SIZE TO NEXT 32 WORD BLOCK
iEXTRA LENGTH OF SYSTEM STATISTICS BLOCK
iSAB LENGTH (ROUNDED UP TO 32 WORD BOUND)

SYSLOG STARTUP TRANSACTION
;

00002;

.=$$$HLN
B.SSLN=.

iSTART AFTER HEADER
iTRANSACTION LENGTH

CRASH RECOVERY TRANSACTION
;

00002;
00003C
000032
00012f

.=$$$HLN
B.CTLS: .BLKW
B.CSRT: .BLKW
B.CRSN: .BLKB
B.CLEN=.

3
1
60.

iSTART AFTER STANDARD HEADER
iTIME OF LAST SCAN BEFORE CRASH
iSCAN RATE BEFORE CRASH
iASCII TEXT EXPLAINING CRASH
iTRANSACTION LENGTH

INVALID LOGIN TRANSACTION
;

000022
00004C
000046
000054

.=$$$HLN
B.INAM: .BLKB
B • I UI C: • BLKB
B. I PSW: • BLKB
B.ILEN=.

14.

6.
6.

iNAME FROM LOGIN LINE
iUIC FROM LOGIN LINE
iPASSWORD FROM LOGIN LINE
iTRANSACTION LENGTH

DEVICE TRANSACTIONS (ALLOCATION, DEALLOCATION, MOUNT, AND
DISMOUNT)
;

000022
000024
000025
000025
000026
000042
000044
000046
000050
000054

.=$$$HLN
B. DNAM: • BLKW
B. DUNT: • BLKB
B.DLEN=.
.BLKB
B.DLBL: .BLKW
B • DM S T : • BLKW
B.DUIC: .BLKW
B • DVPR : • BLKW
B.DACP: .BLKW
B.MLEN=.

1
1
1
6
1
1
1
2

iASCII DEVICE NAME
iOCTAL DEVICE UNIT NUMBER
iTRANSACTION LENGTH FOR ALL, DEA, AND DMO
iUNUSED BYTE
i VOLUME LABEL
iMOUNT STATUS BITS
iOWNER UIC
iVOLUME PROTECTION CODE
iNAME OF ACP FOR DEVICE
iLENGTH OF MOUNT TRANSACTION

STATUS BITS FOR MOUNT STATUS MASK (B.DMST)
i

BM.SHR=1
BM.NOS=2
BM.SYS=4
BM.FOR=10

iDEVICE
iDEVICE
iDEVICE
iDEVICE

A-6

IS
IS
IS
IS

MOUNTED SHARED
MOUNTED NOSHARE
MOUNTED FOR THE SYSTEM (PUBLIC)
MOUNTED FOREIGN

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

ACNDF$ (Cont.)

SYSTEM TIME CHANGE TRANSACTION
i

000022
000030
000036

• =$~;$HLN
B.TOLD: .BLKB
B • TN EW : • BLKB
B. Tto1LN=.

6
6

iOLD TIME (YR, MON, DAY, HR, MIN, SEC)
iNEW TIME (YR, MON, DAY, HR, MIN, SEC)
iTRANSACTION LENGTH

PRINT DES POOLER TRANSACTION
;

000022
000030
000032
000034
000035
000036
000040
000041

• =$~i$HLN
B.PNAM: .BLKW
B • P PG S : • BLKW
B • PN F I: • B L KW
B.PFRM: .BLKB
B • P PR I: • BLKB
B. PDEV: • BLKW
B.PPUN: .BLKB
B.PLEN=.

3
1
1
1
1
1
1

iSTART AFTER HEADER
iPRINT JOB NAME
(RAD50)
i PAGE COUNT
iNUMBER OF FILES PRINTED
iFORM NUMBER
iPRINT PRIORITY
iPRINT DEVICE NAME
(ASCII)
iUNIT NUMBER OF PRINT DEVICE
iTRANSACTION LENGTH

CARD READER SPOOLING TRANSACTION
i

000022
000030
000032
000034
000035
000036

.=$$$HLN
B • RNAM : • BL KW
B.RCDS: .BLKW
B. RDEV: • BLKW
B. RUNT: • BLKB
B.RSOP: .BLKB
B.RLEN=.

3
1
1
1
1

iSTART AFTER HEADER
iBATCH OR PRINT JOB NAME
iNUMBER OF CARDS READ
iREADER DEVICE NAME (ASCII)
iUNIT NUMBER OF READER DEVICE
iSUBMIT OR PRINT (O=SUBMIT, 1=PRINT)
iTRANSACTION LENGTH

000022
000024
000042
000043

.=$$$HLN
B.LUIC: .BLKW
B. LN.AM: • BLKB
.BLKB
B.LLEN=.

1
14.
1

iSTART AFTER HEADER
iLOGIN UIC
iUSER'S LAST NAME
iAND FIRST INITIAL
iTRANSACTION LENGTH

RESET TRANSACTION PARAMETERS
i

000022
000030
000032
000034
000042
000044
000046
000050
000052
000054

.=$$$HLN
B.OFID: .BLKW
B.ODNM: .BLKB
B. OUNT: • BLKW
B.NFID: .BLKW
B. NDNM: • BLKB
B • NUN T : • B L KW
B.OEXS: .BLKW
B.NEXS: .BLKW
B.OSCR: .BLKW
B.NSCR: .BLKW

3
2
1
3
2
1
1
1
1
1

iAFTER HEADER
iFILE-ID OF OLD TRN. FILE
iDEVICE OF OLD TRN. FILE
iUNIT OF OLD TRN. FILE
iFILE+ID OF NEW TRN. FILE
iDEVI¢E OF NEW TRN. FILE
iUNITOF NEW TRN. FILE
iEXT. SIZE FOR OLD TRN. FILE
iEXT. SIZE FOR NEW TRN. FILE
iOLD SCAN RATE IN SECONDS
iNEW SCAN RATE IN SECONDS

A-7

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

ACNDF$ (Cont.)
000051)
000060
00006:~

B.ODSC: .BLKW
B.NDSC: .BLKW
B.RTLN=.

1
1

;OLD STATISTICAL SCAN RATE
;NEW STATISTICAL SCAN RATE

TRANSACTION TYPES
000 THRU 127
128 THRU 255

RESERVED FOR DEC USE
RESERVED FOR CUSTOMER USE

BT.SAB=1
BT.UAB=2
BT.TAB=3
BT.SS=11
BT. INV=12
BT.TIM=13
BT.ALL=14
BT.DEA=15
BT.MOU=16
BT.DMO=17
BT.PRT=20
BT.DIR=21
BT.VOL=22
BT.LOG=23
BT.CRH=24
BT.DST=25
BT.RTP=26
BT.INP=27

iSYSTEM ACCOUNT BLOCK (SAB)
iUSER ACCOUNT BLOCK (UAB)
iTASK ACCOUNT BLOCK (TAB)
iSYSLOG STARTUP TRANSACTION
iINVALID LOGIN TRANSACTION
iSYSTEM TIME CHANGE TRANSACTION
iALLOCATE DEVICE TRANSACTION
iDEALLOCATE DEVICE TRANSACTION
iMOUNT DEVICE TRANSACTION
iDISMOUNT DEVICE TRANSACTION
iPRINT DESPOOLER TRANSACTION
iDISK ACCOUNTING BY DIRECTORY (UNSUPPORTED)
iDISK ACCOUNTING BY VOLUME
(UNSUPPORTED)
iLOGIN TRANSACTION
iCRASH RECOVERY TRANSACTION
iDEVICE STATISTICS (UCB EXTENSION)
iRESET TRANSACTION PARAMETERS
iCARD READER SPOOLING TRANSACTION

STATUS MASK BIT DEFINITIONS (B.STM)
i

BS.ACT=200
BS.CRH=100
BS.LGO=40
BS.CO=40
BS.TML=20
BS.ZER=10
BS.SCN=4

;CONTROL BLOCK ACTIVE
iRECORD FROM "TMP" FILE AFTER SYSTEM CRASH
iLOGGED OFF WITH OUTSTANDING ACTIVITY (UAB)
iTASK'S TI: IS CO: (TAB ONLY)
iTAB EXISTS ONLY FOR TIME LIMIT (TAB ONLY)
iLAST CPU INTERVAL WAS OF LENGTH ZERO
iTRANSACTION READY FOR WRITE TO SCAN FILE

ACCOUNTING FEATURE MASK ($ACNFE)
BF.DST=40000
BF.WRT=2000
BF.SCN=1000
BF.SLR=400
BF.ERR=200
BF.STR=100
BF.LSS=40
BF.TRN=10
BF.XTK=4
BF.TSK=2
BF.XAC=1

iSTATISTICAL SCAN RATE
iFORCE SYSLOG TO WRITE ITS BUFFER
iSCAN REQUESTED
iSYSLOG IS RUNNING (NOT STOPPED)
iACCOUNTING STOPPED DUE TO FATAL ERROR
iACCOUNTING IS STARTING UP / SHUTTING DOWN
iACCUMULATE SYSTEM STATISTICS
i(POINT UAB TO SAB)
iOUTPUT TO TRANSACTION FILE
iCHECKPOINT REQUEST IS DUE TO EXTK$
iTASK ACCOUNTING TURNED ON
iEXTENDED ACCOUNTING ASSEMBLED IN

A-8

RSX-IIM-PLUS SYSTEM DATA STRUC'!tURES AND SYMBOLIC DEFINITIONS
I

ACNDF$ (Cont.)

SHUTDOWN CODES (B.SHDN)
MAINTENANCE
REBOOT
SCHEDULED SHUTDOWN
ACCOUNTING SHUTDOWN BY TASK "SHUTUP"
OTHER

1
')
~.

3
4
C"

iMAXIMUM TRANSACTION LENGTH
iMINIMUM TRANSACTION LENGTH

B. ttIAXL=128.
B. ttIINL=$ $ $HLN
• PSECT

ACTDF$
ACTDF$
.ASECT
000000
000003
000006
000014
000032
000046
000054
000056
000062
000064
000070
000074
000076

.=0
A.GRP:

.BLKB
.BLKB
A. PSWD: .BLKB
A.LNM:
.BLKB
A. E'NM:
.BLKB
A.LDAT: .BLKB
A.NLOG: .BLKB
A.SYDV: .BLKB
A. }!~CN:
.BLKW
.BLKW
A.CLI:
.BLKW
A.LPRV: .BLKW
A.SID:
.BLKW
A.LEN=128.
A.~IBR:

3
3
6
14.
12.
6
2
4
1
2
2
1
1

iGROUP CODE (ASCII)
iMEMBER CODE
i PAS-SWORD
iLAST NAME
iFIRST NAME
iDATE OF LAST LOG ON (DD/MM/YY HH:MM:SS
iTOTAL NUMBER OF LOGONS
iDEFAULT SYSTEM DEVICE
iACCOUNT NUMBER (BINARY)
iRAD50 USER CLI
iUNUSED
iLOGIN PRIVILEGE WORD
iSESSION IDENTIFIER
iLENGTH OF CONTROL BLOCK

BIT DEFINITIONS ON A.LPRV - LOGIN PRIVILEGE BITS
i

iSLAVE TERMINAL ON LOGIN

AL.SLV=l
• PSECT

A-9

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

CLKDF$
CLKDF$
CLOCK QUEUE CONTROL BLOCK OFFSET DEFINITIONS
CLOCK QUEUE CONTROL BLOCK
THERE ARE FIVE TYPES OF CLOCK QUEUE CONTROL BLOCKS. EACH CONTROL
BLOCK HAS THE SAME FORMAT IN THE FIRST FIVE WORDS AND DIFFERS IN
THE REMAINING THREE.
THE FOLLOWING CONTROL BLOCK TYPES ARE DEFINED:
;

C.MRKT=O
C.SCHD=2
C.SSHT=4
C.SYST=6

;MARK TIME REQUEST
;TASK REQUEST WITH PERIODIC RESCHEDULING
;SINGLE SHOT TASK REQUEST
;SINGLE SHOT INTERNAL SYSTEM SUBROUTINE
; (IDENT)
;SINGLE SHOT INTERNAL SYSTEM SUBROUTINE
; (TASK)
;CLEAR STOP BIT (CONDITIONALIZED ON
;SHUFFLING)

C.SYTK=8.
C.CSTP=10.

CLOCK QUEUE CONTROL BLOCK TYPE INDEPENDENT OFFSET DEFINTIONS
.ASECT
000000
000002
000003
000004
000006

.=0
C. LNK:
C.RQT:
C.EFN:
C.TCB:
C.TIM:

• BLK\.v
.BLKB
.BLKB
.BLKW
.BLKW

1
1
1
1
2

;CLOCK QUEUE THREAD WORD
;REQUEST TYPE
;EVENT FLAG NUMBER (MARK TIME ONLY)
;TCB ADR OR SYSTEM SUBROUTINE IDENTIFICATION
;ABSOLUTE TIME WHEN REQUEST COMES DUE

CLOCK QUEUE CONTROL BLOCK-MARK TIME DEPENDENT OFFSET DEFINITIONS
;

000012
000014
000016
000020

.=C.TIM+4
C.AST:
.BLKW
C.SRC:
.BLKW
C.DST:
.BLKW
• BLKW

1
1
1
1

;START OF DEPENDENT AREA
;AST ADDRESS
;FLAG MASK WORD FOR 'BIS' SOURCE
;ADDRESS OF 'BIS' DESTINATION
;UNUSED

CLOCK QUEUE CONTROL BLOCK-PERIODIC RESCHEDULING DEPENDENT OFFSET
DEFINITIONS
;

000012
000016
000020

.=C.TIM+4
C.RSI:
.BLKW
C. UI C :
• BLKW
C. UAS :
• BLKW

1
1

;START OF DEPENDENT AREA
;RESCHEDULE INTERVAL IN CLOCK TICKS
;SCHEDULING UIC
;POINTER TO ASSOCIATED UAB

CLOCK QUEUE CONTROL BLOCK-SINGLE SHOT DEPENDENT OFFSET DEFINITIONS
;

000012

.=C.TIM+4
.BLKW

;START OF DEPENDENT AREA
;TWO UNUSED WORDS
A-I0

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

CLKDF$ (Cont.)
.BLKW
.BLKW

000016
000020

1
1

;SCHEDULING UIC
;C.UAB

CLOCK QUEUE CONTROL BLOCK-SINGLE SHOT INTERNAL SUBROUTINE OFFSET
DEFINITIONS
THERE ARE TWO TYPE CODES FOR THIS TYPE OF REQUEST:
TYPE 6

SINGLE SHOT INTERNAL SUBROUTINE WITH A 16 BIT VALUE
AS AN IDENTIFIER.

TYPE 8

SINGLE SHOT INTERNAL SUBROUTINE WITH A TCB ADDRESS
AS AN IDENTIFIER.

;

000012
000014
000016

.=C .. TIM+4
.BLKW
C. SUB:
C.AR5:
.BLKW
C.UHM:
.BLKW

1
1
1

000020
000022

.BLKW

C.LGTH= •

;START OF DEPENDENT AREA
;SUBROUTINE ADDRESS
;RELOCATION BASE (FOR LOADABLE DRIVERS)
;URM TO EXECUTE ROUTINE ON
;(MP SYSTEMS, C.SYST ONLY)
;UNUSED
;LENGTH OF CLOCK QUEUE CONTROL BLOCK

• PSECT

A-II

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

CTBDF$
CTBDF$
CJNTROLLER TABLE (CTB)
THE CONTROLLER TABLE IS A CONTROL BLOCK THAT CONTAINS A VECTOR
O~ KRB ADDRESSES.
THIS VECTOR MAY BE ADDRESSED BY THE CONTROLLER
I~DEX TAKEN FROM THE INTERRUPT PS BY $INTSV/$INTSE •

177756
177776
000000
000002
000004
000006
000007
000010

• ASECT
.=177756
L.CGK:
.BLKW
L.I<~B:
.BLKW
• BLKW
L • L1'J K:
L.N.\M:
.BLKW
L. DCB:
• BLKW
L • NJM :
• BLKB
L.S'rS:
.BLKB
L. Kl~B:
• BLKW

iSTART OF CLOCK BLOCK (IF ANY)

1
1
1

iICB CHAIN FOR THIS CTB

1
1
1

i CTB LINK WORD
iGENERIC CONTROLLER NAME (ASCII)
iDCB ADDRESS OF THIS DEVICE
jNUMBER OF KRB ADDRESSES IN TABLE
iCTB STATUS BYTE
jSTART OF KRB ADDRESSES

NOTE: THE SYMBOL $XYCTB:: IS DEFINED FOR EACH CTB, WHERE THE
C8ARACTERS XY ARE THE SAME AS THOSE STORED IN L.NAM.
THE
SYMBOL IS NOT THE START OF THE CTB, BUT INSTEAD THE START OF
TllE KRB TAB LE AT THE END OF THE CTB (L. KRB) •
• PSECT

CONTROLLER TABLE STATUS BYTE BIT DEFINITIONS
j

LS.CLK=l
LS. ~1DC=2
LS.CBL=4
LS.CIN=lO
LS.tJET=20

jCLOCK BLOCK AT TOP OF CTB (l=YES)
iMULTIDRIVER CTB (l=YES)
iCLOCK BLK LINKED INTO CLK Q (l=YES)
jCONT. USE COMMON INT TABLE (l=YES)
jTHIS IS DECNET DEVICE.
ICBIS IN K.PRM
j (l=YES)

COMMON INTERRUPT TABLE DISPATCH ENTRY POINTS
j

CI.CSR=-6
CI.KRB=-4
CI.PWF=-2
C I. ] NT=O
CI.DCB=2

jCSR TEST ENTRY POINT
jKRB STATUS CHANGE ENTRY POINT
jPOWERFAIL ENTRY POINT
jCOMMON INTERRUPT ADDRESS
jSTART OF DCB TABLE (0 ENDS TABLE)

A-12

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

DCBDF$
DCBDF$

"SYSDEF

DEVICE CONTROL BLOCK
THE DEVICE CONTROL BLOCK (DCB) DEFINES GENERIC INFORMATION ABOUT A
D:EVICE TYPE AND THE LOWEST AND HIGHEST UNIT NUMBERS.
THERE IS AT
LEAST ONE DCB FOR EACH DEVICE TYPE IN A SYSTEM.
FOR EXAMPLE, IF
THERE ARE TELETYPES IN A SYSTEM, THEN THERE IS AT LEAST ONE DCB
WITH THE DEVICE NAME 'TT'.
IF PART OF THE TELETYPES WERE
INTERFACED VIA DL11-A'S AND THE REST VIA A DH11, THEN THERE WOULD
BJE TWO DCB'S.
ONE FOR ALL DL11-A INTERFACED TELETYPES, AND 'ONE
FOR ALL DH11 INTERFACED TELETYPES •
• ASECT
000000
000002
000004
000006
000007
000010
000012
000014
000016
000020
000022
000024
000026
000030
000032
000034

.=0
D.LNK:
D.UCB:
D. N}\M:
D.UNIT:

.BLKW
.BLKW
.BLKW
.BLKB
.BLKB
D.UCBL: .BLKW
D. DSP:
.BLKW
D.MSK:
.BLKW
.BLKW
• BLKW
• BLKW
• BLKW
• BLKW
• BLKW
• BLKW
.BLKW
D.PCB:

1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1

iLINK TO NEXT DCB
iPOINTER TO FIRST UNIT CONTROL BLOCK
iGENERIC DEVICE NAME
iLOWEST UNIT NUMBER COVERED BY THIS DCB
iHIGHEST UNIT NUMBER COVERED BY THIS DCB
iLENGTH OF EACH UNIT CONTROL BLOCK IN BYTES
iPOINTER TO DRIVER DISPATCH TABLE
iLEGAL FUNCTION MASK CODES 0-15.
iCONTROL FUNCTION MASK CODES 0-15.
iNOP'ED FUNCTION MASK CODES 0-15.
iACP FUNCTION MASK CODES 0-15.
iLEGAL FUNCTION MASK CODES 16.-31.
iCONTROL FUNCTION MASK CODES 16.-31.
iNOP'ED FUNCTION MASK CODES 16.-31.
iACP FUNCTION MASK CODES 16.-31.
iLOADABLE DRIVER PCB ADDRESS

.PSECT

DFlIVER DISPATCH TABLE OFFSET DEFINITIONS
i

D.VDEB=-2
D.VCHK=-4
D. VNIXC=-4
D.VINI=O
D.VCAN=2
D.VOUT=4
D.VPWF=6
D.VKRB=10
D.VUCB=12

iDEALLOCATE BUFFER(S)
iADDRESS OF ROUTINE CALLED TO VALIDATE
iAND CONVERT THE LBN.
USED BY DRIVERS
iTHAT SUPPORT SEEK OPTIMIZATION.
iADDRESS OF ROUTINE IN TTDRV CALLED TO
iHAVE IT SEND THE NEXT COMMAND IN THE
iTYPEAHEAD BUFFER TO MCR •••
iDEVICE INITIATOR
iCANCEL CURRENT I/O FUNCTION
iDEVICE TIMEOUT
iPOWERFAIL RECOVERY
iCONTROLLER STATUS CHANGE ENTRY
iUNIT STATUS CHANGE ENTRY

.IF NB SYSDEF
D.VINT=14

iBEGINNING OF INTERRUPT STUFF

• ENDC

A-13

RSX-11M-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

EPKDF$
EPKDF$
ERROR MESSAGE BLOCK DEFINITIONS
.ASECT

HEADER SUBPACKET

+-----------------------------------------------+
I SUBPACKET LENGTH IN BYTES
I
+-----------------------------------------------+
I SUBPACKET FLAGS
I
+-----------------------+-----------------------+
I FORMAT IDENTIFICATION I OPERATING SYSTEM CODE I
+-----------------------+-----------------------+
I OPERATING SYSTEM IDENTIFICATION
I

I
I

+-----------------------+-----------------------+
I FLAGS
I CONTEXT CODE
I
+-----------------------+-----------------------+
I ENTRY SEQUENCE
I
+-----------------------------------------------+
I ERROR SEQUENCE
I
+-----------------------+-----------------------+
I ENTRY TYPE SUBCODE
I ENTRY TYPE CODE
I
+-----------------------+-----------------------+
I TIME STAMP
I

;

000000
000002
000004
000005
000006
000012
000013
000014
000016
000020
000020
000021
000022
000030
000031
000032
000034

.=0
E$HLGH:
E$HSBF:
E$HSYS:
E$HIDN:
E$HSID:
E$HCTX:
E$HFLG:
E$HENS:
E$HERS:
E$HENC:
E$HTYC:
E$HTYS:
E$HTIM:
E$HPTY:

+-----------------------+-----------------------+
I RESERVED
I PROCESSOR TYPE
I
+-----------------------+-----------------------+
I PROCESSOR IDENTIFICATION (URM)
I
+-----------------------------------------------+
.BLKW
.BLKW
.BLKB
.BLKB
.BLKB
.BLKB
.BLKB
.BLKW
.BLKW

1
1
1
1
4
1
1
1
1

.BLKB
.BLKB
.BLKB
.BLKB
• BLKB
E$HURM: .BLKW
.EVEN
E$HLEN:

1
1
6
1
1
1

SUBPACKET LENGTH IN BYTES
SUB PACKET FLAGS
OPERATING SYSTEM CODE
FORMAT IDENTIFICATION
OPERATING SYSTEM IDENTIFICATION
CONTEXT CODE
FLAGS
ENTRY SEQUENCE NUMBER
ERROR SEQUENCE NUMBER
ENTRY CODE
ENTRY TYPE CODE
ENTRY TYPE SUBCODE
TIME STAMP
PROCESSOR TYPE
RESERVED
PROCESSOR IDENTIFICATION (URM)
LENGTH

A-14

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

EPKDF$ (Cont.)

SUBPACKET FLAGS FOR E$HSBF
SM. ERR
SM.HDR
SM.TSK
SM. DID
SM.DOP
SM.DAC
SM.DAT
SM.MBC
SM.CMD
SM. ZER

1
1
2
4

10
20
40
20000
40000
=100000

ERROR PACKET
HEADER SUB PACKET
TASK SUB PACKET
DEVICE IDENTIFICATION SUBPACKET
DEVICE OPERATION SUB PACKET
DEVICE ACTIVITY SUB PACKET
DATA SUB PACKET
22-BIT MASSBUS CONTROLLER PRESENT
ERROR LOG COMMAND PACKET
ZERO I/O COUNTS

CODES FOR FIELD E$HIDN
EH$FOR

1 ; CURRENT PACKET FORMAT

FLAGS FOR THE ERROR LOG FLAGS BYTE ($ERFLA) IN THE EXEC
ES.INI
ES. DAT
ES.LIM
ES.LOG

1
2

4
10

ERROR
ERROR
ERROR
ERROR

LOG INITIALIZED
LOG RECEIVING DATA PACKETS
LIMITING ENABLED
LOGGING ENABLED

TYPE AND SUBTYPE CODES FOR FIELDS E$HTYC AND E$HTYS
SYMBOLS WITH NAMES E$CXXX ARE TYPE CODES FOR FIELD E$HTYC,
SYMBOLS WITH NAMES E$SXXX ARE SUBTYPE CODES FOR FIELD E$HTYS
E$CCMD
E$SSTA
E$SSWI
E$SAPP
E$SBAC
E$SSHO
E$SCHL
E$CERR
E$SDVH
E$SDVS
E$STMO
E$SUNS
E$CDVI
E$SDVI
E$CDCI
E$SMOU
E$SDMO
E$SRES
E$SRCT
E$CCPU
E$SMEM
E$SINT

1
1
2
3
4
5
6

ERROR LOG CONTROL
ERROR LOG STATUS CHANGE
SWITCH LOGGING FILES
APPEND FILE
DECLARE BACKUP FILE
SHOW
CHANGE LIMITS

2
1

DEVICE ERRORS
DEVICE HARD ERROR
DEVICE SOFT ERROR
DEVICE INTERRUPT TIMEOUT
DEVICE UNSOLICITED INTERRUPT

3
1

DEVICE INFORMATION
DEVICE INFORMATION MESSAGE

DEVICE CONTROL INFORMATION
DEVIC E MOUNT
DEVICE DISMOUNT
DEVICE COUNT RESET
BLOCK REPLACEMENT

2
3

2
3
4

5
1
2

CPU DETECTED ERRORS
MEMORY ERROR
UNEXPECTED INTERRUPT

A-15

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

EPKDF$ (Cont.)
E$CSYS
E$SPWR

6
1

SYSTEM CONTROL INFORMATION
POWER RECOVERY

E$CCTL
E$STIM
E$SCRS
E$SLOA
E$SUNL
E$SHRC
E$SMES

1
2
3
4
5
6

CONTROL INFORMATION
TIME CHANGE
SYSTEM CRASH
DEVICE DRIVER LOAD
DEVICE DRIVER UNLOAD
RECONFIGURATION STATUS CHANGE
MESSAGE

E$CSDE
E$SABO

10
1

SOFTWARE DETECTED EVENTS
TASK ABORT

CODES FOR CONTEXT CODE ENTRY E$HCTX
EH$NOR
EH$STA
EH$CRS

1
2
3

NORMAL ENTRY
START ENTRY
CRASH ENTRY

CODES FOR FLAGS ENTRY E$HFLG
EH$VIR
EH$EXT
EH$COU

1
2

ADDRESSES ARE VIRTUAL
ADDRESSES ARE EXTENDED
ERROR COUNTS SUPPLIED

TASK SUBPACKET

+-----------------------------------------------+
I TASK SUBPACKET LENGTH
I
+-----------------------------------------------+
I TASK NAME IN RAD50
I
I

+-----------------------------------------------+
I TASK UIC
I
+-----------------------------------------------+
I TASK TI: DEVICE NAME
I
+-----------------------+-----------------------+
I FLAGS
I TASK TI: UNIT NUMBER I
+-----------------------+-----------------------+

;

000000
000002
000006
000010
000012
000013

.=0
E$TLGH:
E$TTSK:
E$TUIC:
E$TTID:
E$TTIU:
E$TFLG:

000014

E$TLEN:

• BLKW
• BLKW
.BLKW
• BLKB
.BLKB
.BLKB
• EVEN

TASK SUB PACKET LENGTH
TASK NAME IN RAD50
TASK UIC
TASK TI: DEVICE NAME
TASK TI: UNIT
FLAGS

1
2
1
2
1
1

FLAGS FOR ENTRY E$TFLG
ET$PRV
ET$PRI

1
2

TASK IS PRIVILEGED
TERMINAL IS PRIVILEGED

A-16

RSX-11M-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

EPKDF$ (Cont.)

DEVICE IDENTIFICATION SUB PACKET

+-----------------------------------------------+
I DEVICE IDENTIFICATION SUB PACKET LENGTH
I
+-----------------------------------------------+
I DEVICE MNEMONIC NAME
I
+-----------------------+-----------------------+
CONTROLLER NUMBER
DEVICE UNIT NUMBER
+-----------------------+-----------------------+
PHYSICAL SUBUNIT ff
PHYSICAL UNIT #
+-----------------------+-----------------------+
I PHYSICAL DEVICE MNEMONIC (RSX-11M-PLUS ONLY)
I
+-----------------------+-----------------------+
RESERVED
FLAGS
+-----------------------+-----------------------+
I

I VOLUME NAME OF MOUNTED VOLUME
I
I
I
I
I

I
I
I
I
I
I

I DEVICE TYPE
I

I
I

I I/O OPERATION COUNT LONGWORD
I

I
I

+-----------------------------------------------+
I PACK IDENTIFICATION
I
+-----------------------------------------------+
I DEVICE TYPE CLASS
I
+-----------------------------------------------+
+-----------------------------------------------+
+-----------------------+-----------------------+
HARD ERROR COUNT
SOFT ERROR COUNT
+-----------------------+-----------------------+
I BLOCKS TRANSFERRED COUNT (RSX-11M-PLUS ONLY)
I
I

+-----------------------------------------------+
I CYLINDERS CROSSED COUNT (RSX-11M-PLUS ONLY)
I
;

000000
000002
000004
000005
000006
000007
000010
000012
000013
000014
000030
000034
000034
000036
000042
000046
000047

.=0
E$ILGH:
E$ILDV:
E$ILUN:
E$I PCO:
E$IPUN:
E$I PSU:
E$IPDV:
E$IFLG:

+-----------------------------------------------+

.BLKW
.BLKW
.BLKB
.BLKB
.BLKB
.BLKB
.BLKW
.BLKB
.BLKB
E$IVOL: • BLKB
E$I PAK: • BLKB
E$IDEV:
E$IDCL: .BLKW
E$IDTY: .BLKW
E$IOPR: .BLKW
E$IERS: .BLKB
E$IERH: .BLKB

1
1
1
1
1
1
1
1
1
12 •
4
1
2
2
1
1

DEVICE IDENTIFICATION SUB PACKET LENGTH
DEVICE MNEMONIC NAME
DEVICE UNIT NUMBER
CONTROLLER NUMBER
PHYSICAL UNIT NUMBER
PHYSICAL SUBUNIT NUMBER
PHYSICAL DEVICE MNEMONIC
FLAGS
RESERVED
VOLUME NAME
PACK IDENTIFICATION
DEVICE TYPE
DEVICE TYPE CLASS
DEVICE TYPE
I/O OPERATION COUNT LONGWORD
SOFT ERROR COUNT
HARD ERROR COUNT
A-17

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

EPKDF$ (Cont.)
000050
000054

E$IBLK:
E$ICYL:

000060

E$ILEN:

.BLKW
.BLKW
• EVEN

BLOCKS TRANSFERRED COUNT
CYLINDERS CROSSED COUNT

SUB PACKET LENGTH

FLAGS FOR FIELD E$IFLG
EI$SUB
EI$NUX

1
2

SUBCONTROLLER DEVICE
NO UCB EXTENSION, DATA INVALID

DEVICE OPERATION SUB PACKET

+-----------------------------------------------+
I DEVICE OPERATION SUB PACKET LENGTH
I
+-----------------------------------------------+
I TASK NAME IN RAD50
!
I

I TRANSFER OPERATION ADDRESS
I

I
I

+-----------------------------------------------+
I TASK UIC
I
+-----------------------------------------------+
I TASK TI: LOGICAL DEVICE MNEMONIC
I
+-----------------------+-----------------------+
I RBSERVED
I TASK TI: DEVICE UNIT !
+-----------------------+-----------------------+
I I/O FUNCTION CODE
I
+-----------------------+-----------------------+
I RESERVED
I OPERATION FLAGS
I
+-----------------------+-----------------------+
+-----------------------------------------------+
I TRANSFER OPERATION BYTE COUNT
I
+-----------------------------------------------+
I CURRENT OPERATION RETRY COUNT
I
+-----------------------------------------------+

;

000000
000002
000006
000010
000012
000013
000014
000016
000017
000020
000024
000026
000030

.=0
E$OLGN:
E$OTSK:
E$OUIC:
E$OTID:
E$OTIU:

.BLKW
.BLKW
.BLKW
.BLKB
.BLKB
.BLKB
E$OFNC: • BLKW
E$OFLG: .BLKB
.BLKB
E$OADD: .BLKW
E$OSIZ: .BLKW
E$ORTY: .BLKW
.EVEN
E$OLEN:

SUBPACKET LENGTH
TASK NAME IN RAD50
TASK UIC
TASK TI: LOGICAL DEVICE MNEMONIC
TASK TI: LOGICAL DEVICE UNIT
RESERVED
I/O FUNCTION CODE
OPERATION FLAGS
RESERVED
TRANSFER OPERATION ADDRESS
TRANSFER OPERATION BYTE COUNT
CURRENT OPERATION RETRY COUNT

1
2
1
2
1
1
1
1
1
2
1
1

DEVICE OPERATION SUB PACKET LENGTH

FLAGS FOR FIELD E$OFLG
EO$TRA
EO$DMA

1
2

TRANSFER OPERATION
DMA DEVICE

A-18

RSX-llM·-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

EPKDF$ (Cont.)
EO$EXT
EO$PIP

EXTENDED ADDRESSING DEVICE
DEVICE IS POSITIONING

I/O ACTIVITY SUBPACKET

+-----------------------------------------------+
I I/O ACTIVITY SUB PACKET LENGTH
I
+-----------------------------------------------+

;

000000

.=0
E$ALGH: • BLKW

SUBPACKET LENGTH

I/O ACTIVITY SUB PACKET ENTRY

+-----------------------------------------------+
I LOGICAL DEVICE NAME MNEMONIC
I
+-----------------------+-----------------------+
CONTROLLER NUMBER
LOGICAL DEVICE UNIT
+-----------------------+-----------------------+
PHYSICAL SUBUNIT #
PHYSICAL UNIT NUMBER
+-----------------------+-----------------------+
I PHYSICAL DEVICE MNEMONIC (RSX-11M-PLUS ONLY)
I
+-----------------------+-----------------------+
TASK TI: LOGICAL UNIT
DEVICE FLAGS
+-----------------------+-----------------------+
I REQUESTING TASK NAME IN RAD50
I
I

+-----------------------------------------------+
I REQUESTING TASK UIC
I
+-----------------------------------------------+
I TASK TI: LOGICAL DEVICE NAME
I
+-----------------------------------------------+
I I/O FUNCTION CODE
I
+-----------------------+-----------------------+
RESERVED
FLAGS
+-----------------------+-----------------------+
I TRANSFER OPERATION ADDRESS
I
I

;

000000
000002
000003
000004
000005
000006
000010
000011
000012
000016
000020
000022
000024

.=0
E$ALDV:
E$ALUN:
E$APCO:
E$APUN:
E$APSU:
E$APDV:
E$ADFG:
E$AT'IU:
E$AT'SK:
E$AUIC:
E$AT'ID:
E$AFNC:
E$AF'LG:

+-----------------------------------------------+
I TRANSFER OPERATION BYTE COUNT
I
+-----------------------------------------------+
.BLKW
.BLKB
.BLKB
.BLKB
.BLKB
.BLKW
.BLKB
• BLKB
.BLKW
.BLKW
.BLKW
.BLKW
.BLKB

1
1
1
1
1
1
1
1
2
1
1
1
1

LOGICAL DEVICE NAME MNEMONIC
LOGICAL DEVICE UNIT
CONTROLLER NUMBER
PHYSICAL UNIT NUMBER
PHYSICAL SUBUNIT NUMBER
PHYSICAL DEVICE MNEMONIC
DEVICE FLAGS
TASK TI: LOGICAL UNIT
REQUESTING TASK NAME IN RAD50
REQUESTING TASK UIC
TASK TI: LOGICAL DEVICE NAME
I/O FUNCTION CODE
FLAGS

A-19

R3X-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

EPKDF$ (Cont.)
000025
000026
000032
000034

.BLKB
E$AADD: • BLKW
E$A:;IZ: .BLKW
.EVEN
E$A~EN :

RESERVED
TRANSFER OPERATION ADDRESS
TRANSFER OPERATION BYTE COUNT

1
2
1

SUBPACKET ENTRY LENGTH

F:"AGS FOR FIELD E$ADFG
EA$SUB
EA$NUX

1
2

SUBCONTROLLER DEVICE
NO UCB EXTENSION, DATA INVALID

F' .. AGS FOR FIELD E$AFLG
EA$TRA
EA$DMA
EA$EXT
EA$PIP

1
2
4
10

TRANSFER OPERATION
DMA DEVICE
DEVICE HAS EXTENDED ADDRESSING
DEVICE IS POSITIONING

• PSECT

A-20

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

F11DF$
FIIDF$

"SYSDEF

VOLUME CONTROL BLOCK
.ASECT

000004
000020

.=0
V. THCT:
V.TYPE:
VT.SLl=
VT. J\NS=
VT.UNL=
V.VCHA:
VC.SLK=
VC.HLK=
VC.DEA=
VC.PUB=
V.LABL:
V. PKSR:

000024

V.SLEN:

000024
000026
000032
000033
000034
000036
000040

V. IF'WI:
V.FCB:
V. IBLB:
V.IBSZ:

.BLKW
.BLKW
.BLKB
.BLKB
.BLKW
V. F~IAX: .BLKW
V.WISZ: .BLKB

000041
000042
000044
000045
000046
000050
000052
000054
000056
000057
000060
000062

V.SBCL:
V.SBSZ:
V.SBLB:
V • FIE X:

0000 00
000002

000003

V.VOWN:
V.VPRO:
V. FPRO:
V.FHBK:
V.LRUC:

000063
000064

V. ST'S:
VS.IFW=
VS.BMW=
V • FFNU :
V. EXT:

000066

V.LGTH:

• BLKW
.BLKB
1
10
11
.BLKB
1
2
4
10
.BLKB
• BLKW

1
1

14
2

TRANSACTION COUNT
VOLUME TYPE DESCRIPTOR
FILES-II STRUCTURE LEVEL 1
ANSI LABELED TAPE
UNLABELED TAPE
VOLUME CHARACTERISTICS
CLEAR VOLUME VALID ON DISMOUNT
UNLOAD THE VOLUME ON DISMOUNT
DEALLOCATE THE VOLUME ON DISMOUNT
SET {CLEAR} US. PUB ON DISMOUNT
VOLUME LABEL (ASCII)
PACK SERIAL NUMBER FOR ERROR LOGGING
LENGTH OF SHORT VCB

.BLKB
.BLKW
.BLKB
• BLKB
.BLKW
.BLKW
.BLKW
• BLKW
.BLKB
.BLKB
.BLKW
• BLKB
1
2
• BLKB
• BLKW

1
2
1

1
1
1
1
1
1
1
1
1
1
1

1
1
1
1
1

1
1

INDEX FILE WINDOW
FILE CONTROL BLOCK LIST HEAD
INDEX BIT MAP 1ST LBN HIGH BYTE
INDEX BIT MAP SIZE IN BLOCKS
INDEX BITMAP 1ST LBN LOW BITS
MAX NO. OF FILES ON VOLUME
DEFAULT SIZE OF WINDOW IN RTRV PTRS
VALUE IS < 128.
STORAGE BIT MAP CLUSTER FACTOR
STORAGE BIT MAP SIZE IN BLOCKS
STORAGE BIT MAP 1ST LBN HIGH BYTE
DEFAULT FILE EXTEND SIZE
STORAGE BIT MAP 1ST LBN LOW BITS
VOLUME OWNER'S UIC
VOLUME PROTECTION
VOLUME DEFAULT FILE PROTECTION
NUMBER OF FREE BLOCKS ON VOLUME HIGH BYTE
COUNT OF AVAILABLE LRU SLOTS IN FCB LIST
NUMBER OF FREE BLOCKS ON VOLUME LOW BITS
VOL STATUS BYTE, CONTAINING THE FOLLOWING
INDEX FILE IS WRITE ACCESSED
STORAGE BITMAP FILE IS WRITE ACCESSED
FIRST FREE INDEX FILE BITMAP BLOCK
POINTER TO VCB EXTENSION
SIZE IN BYTES OF VCB

MOUNT LIST ENTRY
EACH ENTRY ALLOWS ACCESS TO A SPECIFIED USER FOR A NON-PUB DEVICE
TO ALLOW EXPANSION, ONLY THE ONLY TYPE CODE DEFINED IS "1" FOR
DEVICE ACCESS BLOCKS
.ASECT
000000

.=0
M.LNK:

.BLKW

LINK WORD
A-21

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

F11 DF$ (Cont.)

000003
000004
000006

M.TYPE:
MT.MLS=
M.ACC:
M.DEV:
M.TI:

000010

M.LEN:

000002

.BLKB
1
.BLKB
.BLKW
• BLKW

1
1
1
1

TYPE OF ENTRY
MOUNTED VOLUME USER ACCESS LIST
NUMBER OF ACCESSES
DEVICE UCB
ACCESSOR TI: UCB
LENGTH OF ENTRY

FILE CONTROL BLOCK

000000
000002
000004
000006
000007
000010
000012
000014
000015
000016

.ASECT
.=0
F.LINK: .BLKW
F. FNUM: • BLKW
F.FSEQ: .BLKW
.BLKB
F. FSQN: • BLKB
F. FOWN: • BLKW
F. FPRO: • BLKW
F • UC HA : • BLKB
F.SCHA: .BLKB
F. HDLB: • BLKW

000022

F.LBN:

.BLKW

000026
000032
000033

F.SIZE: .BLKW
F. NACS: • BLKB
F .NLCK: • BLKB

000012

S.STBK=.-F.LBN

000034
000034
000035

000036
000040
000042
000044
000050
000052

F.STAT:
F.NWAC: .BLKB
.BLKB
FC.WAC= 100000
FC.DIR= 40000
FC.CEF= 20000
FC.FCO= 10000
F.DREF: .BLKW
F.DRNM: • BLKW
F.FEXT: .BLKW
F.FVBN: .BLKW
F.LKL:
.BLKW
F.WIN:
.BLKW

000054

F.LGTH:

1
1
1
1
1
1
1
1

1
1

FCB CHAIN POINTER
FILE NUMBER
FILE SEQUENCE NUMBER
NOT USED
FILE SEGMENT NUMBER
FILE OWNER'S UIC
FILE PROTECTION CODE
USER. CONTROLLED CHARACTERISTICS
SYSTEM CONTROLLED CHARACTERISTICS
FILE HEADER LOGICAL BLOCK NUMBER
BEGINNING OF STATISTICS BLOCK
LBN OF VIRTUAL BLOCK 1 IF CONTIGUOUS
o IF NON CONTIGUOUS
SIZE OF FILE IN BLOCKS
NO. OF ACCESSES
NO. OF LOCKS
SIZE OF STATISTICS BLOCK

1
1

1
1
1
2
1
1

FCB STATUS WORD
NUMBER OF WRITE ACCESSORS
STATUS BITS FOR FCB CONSISTING OF
SET IF FILE ACCESSED FOR WRITE
SET IF FCB IS IN DIRECTORY LRU
SET IF DIRECTORY EOF NEEDS UPDATING
SET IF TRYING TO FORCE DIRECTORY CONTIG
DIRECTORY EOF BLOCK NUMBER
1ST WORD OF DIRECTORY NAME
POINTER TO EXTENSION FCB
STARTING VBN OF THIS FILE SEGMENT
POINTER TO LOCKED BLOCK LIST FOR FILE
WINDOW BLOCK LIST FOR THIS FILE
SIZE IN BYTES OF FCB

WINDOW
.ASECT
000000

.=0
W.ACT:

NUMBER OF ACTIVE MAPPING POINTERS
WHEN NO SECONDARY POOL

A-22

RSX-11M-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

F11 DF$ (Cont.)
000000

W.BLKS:

000000

W.C~~L:

.BLKW

WI. HDV=
WI. ylRV=
WI. EXT=
WI.LCK=
WI.DLK=
WI. PND=
WI.EXL=
WI. ylCK=
W. IOC:

400
1000
2000
4000
10000
20000
40000
100000
.BLKB
.BLKB
.BLKW
.BLKW
.BLKW

1
1
1
1
1

000002
000003
000004
000006
000010

W.FCB:
W.LKL:
W.WIN:

BLOCK SIZE OF SECONDARY POOL SEGMENT
WHEN SECONDARY POOL
LOW BYTE = # OF MAP ENTRIES ACTIVE
HIGH BYTE CONSISTS OF CONTROL BITS
READ VIRTUAL BLOCK ALLOWED IF SET
WRITE VIRTUAL BLOCK ALLOWED IF SET
EXTEND ALLOWED IF SET
SET IF LOCKED AGAINST SHARED ACCESS
SET IF DEACCESS LOCK ENABLED
WINDOW TURN PENDING BIT
SET IF MANUAL UNLOCK DESIRED
DATA CHECK ALL WRITES TO FILE
COUNT OF I/O THROUGH THIS WINDOW
RESERVED
FILE CONTROL BLOCK ADDRESS
POINTER TO LIST OF USERS LOCKED BLOCKS
WINDOW BLOCK LIST LINK WORD

.IF NB SYSDEF

IF SYSDEF SPECIFIED IN CALL

.IF NDF P$$WND

IF SECONDARY POOL WINDOWS NOT ALLOWED

NON-SECONDARY POOL WINDOW BLOCK
IF SECONDARY POOL WINDOWS ARE NOT ENABLED, THE WINDOW BLOCK
CONTAINS THE CONTROL INFORMATION AND RETRIEVAL POINTERS.
;

W.VBN:
.BLKB
W. MAP:
W.WISZ: .BLKB
.BLKW
W. R'I'RV:

1
1
1

.IFF

HIGH BYTE OF 1ST VBN MAPPED BY WINDOW
DEF LABEL WITH ODD ADDR TO CATCH BAD REFS
SIZE IN RTRV PTRS OF WINDOW (7 BITS)
LOW ORDER WORD OF 1ST VBN MAPPED
OFFSET TO 1ST RETRIEVAL POINTER IN WINDOW
IF WINDOWS IN SECONDARY POOL

SECONDARY POOL WINDOW CONTROL AND MAPPING BLOCK
IF SECONDARY POOL WINDOW BLOCKS ARE ENABLED, LUTN2 POINTS
TO A CONTROL BLOCK IN SYSTEM POOL WHICH CONTAINS THE
FOLLOWING CONTROL FIELDS AND THE MAPPING INFORMATION
FOR THE SECONDARY POOL WINDOW.
;

W. MP,P :

• BLKW

ADDR TO THE MAPPING PTRS IN SECONDARY POOL

SE:CONDARY POOL WINDOW
IF SECONDARY POOL WINDOW BLOCKS ARE ENABLED, THE RETRIEVAL
POINTERS ARE MAINTAINED IN SECONDARY POOL IN THE FOLLOWING
FORMAT.
;

.=0
W.USE:
W.VBN:

ASSUME
.BLKB
.BLKB
.BLKB

W.CTL,O
1
1
1

NUMBER OF ACTIVE MAPPING POINTERS
STATUS OF BLOCK
HIGH BYTE OF 1ST VBN MAPPED BY WINDOW

A-23

RSX-11M-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

F11 DF$ (Cont.)
W.WISZ: .BLKB
.BLKW
W.RTRV:

1
1

SIZE IN RTRV PTRS OF WINDOW (7 BITS)
LOW ORDER WORD OF 1ST VBN MAPPED
OFFSET TO 1ST RETRIEVAL POINTER IN WINDOW

• ENDC iP$$WND

END SECONDARY POOL WINDOW CONDITIONAL

• ENDC iSYSDEF

END SYSDEF CONDITIONAL

LOCKED BLOCK LIST NODE
.ASECT
000000
000002
000004
000005
000006
000010

.=0
L. LNK:
L. WI 1:
L.VBl:
L.CNT:

.BLKW
.BLKW
.BLKB
.BLKB
.BLKW

1
1

1
1
1

LINK TO NEXT NODE IN LIST
POINTER TO WINDOW FOR FIRST ENTRY
HIGH ORDER VBN BYTE
COUNT FOR ENTRY
LOW ORDER VBN

L.LKSZ:
.PSECT

A-24

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

HDRDF$
HDRDF$
TASK HEADER OFFSET DEFINITIONS

000000
000002
000004
000005
000006
000010
000012
000014
000016
000020
000022
000024
000026
000030
000032
000034
000036
000040
000042
000044
000046
000050
000052
000054
000056
000060
000061
000062
000064
000065
000066
000072
000074
000076

, .ASECT
.=0
H.CSP:
.BLKW
H.HDLN: .BLKW
H.SMAP: .BLKB
H.DMAP: .BLKB
.BLKW
H.CUIC: .BLKW
H.DUIC: .BLKW
.BLKW
H.IPS:
H. IPC:
.BLKW
.BLKW
H.ISP:
H.ODVA: .BLKW
H.ODVL: .BLKW
H.TKVA: .BLKW
H.TKVL: .BLKW
H. PJ"VA: .BLKW
H.FPVA: • BLKW
H.RCVA: • BLKW
H. EJ~SV: .BLKW
H.FPSA: • BLKW
H.WND:
.BLKW
.BLKW
H.DSW:
H.FCS:
.BLKW
H.FORT: .BLKW
H.OVLY: .BLKW
H.VgXT: .BLKW
H.SPRI: .BLKB
H. NML:
.BLKB
H.RHVA: • BLKW
H. X2 5:
.BLKB
.BLKB
.BLKW
H. G}\RD: .BLKW
H.NLUN: .BLKW
.BLKW
H.LUN:

1
1
1
1

1
1
1
1
1
1
1
1
1

1
1

1
1
1
1
1

1
1
1

1
1

1
1
1
1
1

iCURRENT STACK POINTER
iHEADER LENGTH IN BYTES
iSUPERVISOR D SPACE OVERMAP MASK
iUSER D SPACE OVERMAP MASK
iRESERVED
iCURRENT TASK UIC
iDEFAULT TASK UIC
iINITIAL PROCESSOR STATUS WORD (PS)
iINITIAL PROGRAM COUNTER (PC)
iINITIAL STACK POINTER (SP)
iODT SST VECTOR ADDRESS
iODT SST VECTOR LENGTH
iTASK SST VECTOR ADDRESS
iTASK SST VECTOR LENGTH
iPOWER FAIL AST CONTROL BLOCK ADDRESS
iFLOATING POINT AST CONTROL BLOCK ADDRESS
iRECIEVE AST CONTROL BLOCK ADDRESS
iEVENT FLAG ADDRESS SAVE ADDRESS
iPOINTER TO FLOATING POINT/EAE SAVE AREA
iPOINTER TO NUMBER OF WINDOW BLOCKS
iTASK DIRECTIVE STATUS WORD
iFCS IMPURE POINTER
iFORTRAN IMPURE POINTER
iOVERLAY IMPURE POINTER
iWORK AREA EXTENSION VECTOR POINTER
iPRIORITY DIFFERENCE FOR SWAPPING
iNETWORK M."I.ILBOX LUN
iRECEIVE BY REFERENCE AST CONTROL BLOCK ADDR
iFOR USE BY X25 SOFTWARE
i5 RESERVED BYTES

1
1
2

iPOINTER TO HEADER GUARD WORD
iNUMBER OF LUN'S
iSTART OF LOGICAL UNIT TABLE

LgNGTH OF FLOATING POINT SAVE AREA
i

H.FPSL=25.*2

WINDOW BLOCK OFFSETS

000000
000002
000004
000006

.=0
W.BPCB: .BLKW
W.BLVR: .BLKW
W.BHVR: .BLKW
W. B}\TT: • BLKW

1
1

iPARTITION CONTROL BLOCK ADDRESS
iLOW VIRTUAL ADDRESS LIMIT
iHIGH VIRTUAL ADDRESS LIMIT
iADDRESS OF ATTACHMENT DESCRIPTOR

A-25

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

HDRDF$ (Cont.)
000010
000012
000014
000015
000016
000020

W.BSIZ:
W.BOFF:
W.BF'PD:
W.BNPD:
W.BLPD:
W.BLGH:

.BLKW
.BLKW
.BLKB
.BLKB
.BLKW

1
1
1
1
1

jSIZE OF WINDOW IN 32W BLOCKS
jPHYSICAL MEMORY OFFSET IN 32W BLOCKS
jFIRST PDR ADDRESS
jNUMBER OF PDR'S TO MAP
jCONTENTS OF LAST PDR
jLENGTH OF WINDOW DESCRIPTOR

BJT DEFINITION FOR W.BLPD
j

WB.NBP=20
WB. F,PS=40

jCACHE BYPASS IS NOT DESIRED FOR THIS WINDOW
jALWAYS BYPASS THE CACHE FOR THIS WINDOW

.PSECT

A-26

RSX-11M-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

HWDDF$
HWDDF$

"SYSDEF

MACROS FOR DEFINING MAPPING REGISTER DEFINITIONS
.MACRO

CRESET

NAM,ADDR

$$$=:0
.REPT
CRENAM
$$$=:$$$+1
• ENDR
• ENDM

8.
NAM,ADDR+<$$$*2>,\$$$

.MACRO
'NAtJl' 'N'==ADDR
• ENDM

CRENAM

NAM,ADDR,N

Hl\RDWARE REGISTER ADDRESSES AND STATUS CODES
i

iADDRESS OF PDP-ll/70 MEMORY PARITY REGISTER
iADDRESS OF FIRST MEMORY PARITY REGISTER
iPROGRAMMED INTERRUPT REQUEST REGISTER
iPROCESSOR PRIORITY 0
iPROCESSOR PRIORITY 1
iPROCESSOR PRIORITY 4
iPROCESSOR PRIORITY 5
iPROCESSOR PRIORITY 6
iPROCESSOR PRIORITY 7
iPROCESSOR STATUS WORD
iCONSOLE SWITCH AND DISPLAY REGISTER
iCONSOLE TERMINAL PRINTER STATUS REGISTER

MPCSR=177746
MPAH=172100
PIRC~=177772

PRO=:O
PRl=:40
PR4=:200
PR5=:240
PR6=:300
PR7=:340
PS=177776
SWR=:l 77 570
T PS =: 1 77 564

EXTENDED ARITHMETIC ELEMENT REGISTERS
.IF DF

E$$EAE

AC=J.77302
MQ=177304
SC=177310

iACCUMULATOR
iMULTIPLIER-QUOTIENT
iSHIFT COUNT

.ENDC

MEMORY MANAGEMENT HARDWARE REGISTERS AND STATUS CODES
.IF NB

CRESET
CRESET
CRESET
CRESET
CRESET
CRESET
CRESET
CRESET
CRESET

KINAR,172340
KINDR,172300
KDSAR,172360
KDSDR,172320
SISAR,172240
SISDR,172200
SDSAR,172260
SDSDR,172220
UINAR,177640

;KERNEL I PAR'S
iKERNEL I PDR'S
iKERNEL D PAR'S
iKERNEL D PDR'S
iSUPERVISOR I PAR'S
iSUPERVISOR I PDR'S
iSUPERVISOR D PAR'S
iSUPERVISOR D PDR'S
iUSER I PAR'S
A-27

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

HWDDF$ (Cont.)
CRESET
CRESET
CRESET

UINDR,177600
UDSAR,177660
UDSDR,177620

iUSER I PDR'S
iUSER D PAR'S
iUSER D PDR'S

• ENDC
.IF NB

SYSDEF

.IF DF

K$$DAS

CRESET
CRESET

KISAR,172360
KISDR,172320

iKERNEL D PAR'S
iKERNEL D PDR'S

KISAR,172340
KISDR,172300

iKERNEL I PAR'S
iKERNEL I PDR'S

.IFF
CRESET
CRESET
• ENDC
.IF DF

U$$DAS

CRESET
CRESET

UISAR,177660
UISDR,177620

.IFF

CRESE'I'
CRESET

UISAR,177640
UISDR,177600

.ENDC

iUSER D PAR'S
iUSER D PDR'S

DF U$$DAS
; US ER I P,~R' S
iUSER I PDR'S

DF U$$DAS

.ENDC
UBMPR=170200
CMODE=140000
PMODE=30000
CSMODE=40000
PSMODE=IOOOO
SRO=177572
SR3=1725I6
CPUERR=177766
MEMERR=177744
MEMCTL=177746

iUNIBUS MAPPING REGISTER 0
iCURRENT MODE FIELD OF PS WORD
iPREVIOUS MODE FIELD OF PS WORD
iCURRENT MODE = SUPERVISOR PS WORD BITS
iPREVIOUS MODE = SUPERVISOR PS WORD BITS
iSEGMENT STATUS REGISTER 0
iSEGMENT STATUS REGISTER 3
;CPU ERROR REGISTER
iMEMORY SYSTEM ERROR REGISTER
iMEMORY CONTROL REGISTER

FEATURE SYMBOL DEFINITIONS
i

FE.EXT=I
FE.MUP=2
FE. EXV=4
FE.DRV=IO
FE.PLA=20
FE.CAL=40
FE.PKT=100
FE.EXP=200
FE.LSI=400
FE.OFF=IOOO
FE.FDT=2000

;22-BIT EXTENDED MEMORY SUPPORT
;MULTI-USER PROTECTION SUPPORT
iEXECUTIVE IS SUPPORTED TO 20K
iLOADABLE DRIVER SUPPORT
iPLAS SUPPORT
iDYNAMIC CHECKPOINT SPACE ALLOCATION
iPREALLOCATION OF I/O PACKETS
iEXTEND TASK DIRECTIVE SUPPORTED
iPROCESSOR IS AN LSI-II
iPARENT/OFFSPRING TASKING SUPPORTED
iFULL DUPLEX TERMINAL DRIVER SUPPORTED
A-28

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

HWDDF$ (Cont.)
FE.X2S=4000
FE.DYM=lOOOO
FE.CEX=20000
FE. r1XT=4 0000
FE.NLG=lOOOOO

iX.2S CEX IS LOADED
iDYNAMIC MEMORY ALLOCATION SUPPORTED
iCOM EXEC IS LOADED
iMCR EXIT AFTER EACH COMMAND MODE
;LOGINS DISABLED - MULTI-USER SUPPORT

FEATURE MASK DEFINITIONS (SECOND WORD)
;

F2.DAS=l
F2.LIB=2
F2.~1P=4

F2.EVT=10
F2. }~CN=2 0
F2.SDW=40
F2.POL=lOO
F2. ~vND=2 00
F2.DPR=400
F2.IRR=lOOO
F2.GGF=2000
F2.HAS=4000
F2. }~HR=l 0000
F2.HBN=20000
F2.SWP=40000
F2.STP=lOOOOO

iKERNEL DATA SPACE SUPPORTED
iSUPERVISOR MODE LIBRARIES SUPPORTED
iSYSTEM SUPPORTS MULTIPROCESSING
iSYSTEM SUPPORTS EVENT TRACE FEATURE
iSYSTEM SUPPORTS CPU ACCOUNTING
iSYSTEM SUPPORTS SHADOW RECORDING
iSYSTEM SUPPORTS SECONDARY POOLS
iSYSTEM SUPPORTS SECONDARY POOL FILE WINDOWS
iSYSTEM HAS A SEPARATE DIRECTIVE PARTITION
iINSTALL, RUN, AND REMOVE SUPPORT
iGROUP GLOBAL EVENT FLAG SUPPORT
iRECEIVE/SEND DATA PACKET SUPPORT
iALT. HEADER REFRESH AREA SUPPORT
iROUND ROBIN SCHEDULING SUPPORT
iEXECUTIVE LEVEL DISK SWAPPING SUPPORT
iEVENT FLAG MASK IS IN THE TCB(l=YES)

THIRD FEATURE MASK SYMBOL DEFINITIONS
i

F3.eRA=l
F3.XCR=2
F3.EIS=4
F3.STM=lO
F3.UDS=20
F3.PRO=40
F3.XHR=lOO
F3.J~ST=200

F3.11S=400
F3.CLI=lOOO
F 3 • 1~C M=2 0 0 0
F3.PMN=4000
F3. ~IAT=l 00 00
F3.HLK=20000
F3.SHF=40000

iSYSTEM SPONTANEOUSLY CRASHED (l=YES)
iSYSTEM CRASHED FROM XDT (l=YES)
iSYSTEM REQUIRES EXTENDED INSTRUCTION SET
iSYSTEM HAS SET SYSTEM TIME DIRECTIVE
iSYSTEM SUPPORTS USER DATA SPACE
iSYSTEM SUPPORTS SEC. POOL PROTO TCBS
iSYSTEM SUPPORTS EXTERNAL TASK HEADERS
iSYSTEM HAS AST SUPPORT
iRSX-llS SYSTEM
iMULTIPLE CLI SUPPORT
iSYSTEM HAS SEPARATE TERMINAL DRIVER POOL
iSYSTEM SUPPORTS POOL MONITORING
iSYSTEM HAS WATCHDOG TIMER SUPPORT
iSYSTEM SUPPORTS RMS RECORD LOCKING
iSYSTEM SUPPORTS SHUFFLER TASK

FOURTH FEATURE MASK BITS
;

F4.CXD=l

iCOMM EXEC IS DEALLOCATED (NON-I/D ONLY)

H}\RDWARE FEATURE MASK BIT DEFINITIONS
HF.CIS,HF.FPP DEFINED AS SIGN BITS FOR RUN TIME SPEED
i

HF.UBM=l

iPROCESSOR HAS A UNIBUS MAP (l=YES)

A-29

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

HWDDF$ (Cont.)
HF.EIS=2
HF.CIS=200
HF.FPP=lOOOOO

;PROCESSOR HAS EXTENDED INSTRUCION SET
;PROCESSOR SUPPORTS COMMERCIAL INST SET
; (l=PROC. HAS NO FLOATING POINT UNIT)

SYSGEN FEATURE SELECTIONS MASK.
THIS IS INTENDED TO RECORD IN A
BIT MASK THE CHOICES THE USER HAS MADE AT SYSGEN TIME.
FEATURES
WILL BE LISTED HERE WHEN THEY ARE BEING RECORDEJ FOR OUR
INFORMATIONAL PURPOSES ONLY.
THEY CANNOT BE TESTED LIKE BITS IN
THE FEATURE MASK SINCE THIS ONLY EXISTS IN THE RSXIIM.STB FILE8
NO BITS IN MEMORY ARE USED.
THEY ARE ONLY INTENDED TO BE PRINTED
FROM THE STB FILE BY CDA.
;

SF.STD=l
SF.RL2=2

;STANDARD EXEC SELECTED
;SYSTEM IS FROM RL02 KIT

MULTIPROCESSOR STATUS TABLE DEFINITIONS (TEMPORARY)
;

MP.CRH=lOOOOO
MP.PWF=40000
MP.RSM=20000
MP.NOP=lOOOO
MP.STP=4
MP.INT=7777

iCRASH PROCESSOR IMMEDIATELY
;POWERFAIL ON ONE CPU
;RESET INTERRUPT MASKS
;NOP FUNCTION FOR TRANSMISSION CHECK
;STOP PROCESSOR IN ORDERLY FASHION
;BIC MASK FOR INTERRUPT LVL FUNCTIONS

A-30

RSX-IIM-PLUS SYSTEM DATA

STRUCTUR~S

AND SYMBOLIC DEFINITIONS

ITBDF$
ITBDF$

"SYSDEF

INTERRUPT TRANSFER BLOCK (ITB) OFFSET DEFINITIONS
.MCALL
PKTDF$

PKTDF$
DEFINE AST BLOCK OFFSETS

.ASECT
000000
000002
000006
000007
000010
000012
000012
000014
000016
000020
000022
000024
000026

.=0
X. LNK:
X.JSR:
X.PSW:
X.ISR:
X.FORK:

X.REL:
X.DSI:
X.TCB:

000030
000032
000044

X.AST:
X.VEC:

000046
000050

X.VPC:
X. LI~N:

.BLKW
JSR
.BLKB
.BLKB
• BLKW

1
R5,@iO
1
1
1

.BLKW
.BLKW
• BLKW
.BLKW
.BLKW
.BLKW
.BLKW

1
1
1
1
1
1
1

.IF NB

SYSDEF

.BLKW
.BLKB
.BLKW

1
A.PRM
1

.BLKW

LINK WORD FOR ITB LIST STARTING IN TCB
CALL $INTSC
LOW BYTE OF PSW FOR ISR
UNUSED
ISR ENTRY POINT (APR5 MAPPING)
FORK BLOCK
THREAD WORD
FORK PC
SAVED R5
SAVED R4
RELOCATION BASE FOR APR5
ADDRESS OF DIS. INT. ROUTINE
TCB ADDRESS OF OWNING TASK

A.DQSR FOR AST BLOCK
AST BLOCK
VECTOR ADDRESS (IF AST SUPPORT,
THIS IS FIRST AND ONLY AST PARAMETER)
SAVED VECTOR PC
LENGTH IN BYTES OF ITB

• ENDC
• PSECT

A-31

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

KRBDF$
KRBDF$
CONTROLLER REQUEST BLOCK (KRB)
THE CONTROLLER REQUEST BLOCK DEFINES THE ENVIRONMENT OF A DEVICE
EXACTLY ONE KRB EXISTS FOR EVERY DEVICE CONTROLLER
CONTROLLER.
IN AN RSX-11M+ SYSTEM. THE KRB CONTAINS CERTAIN DEVICE STATUS
INCLUDING THE CSR AND VECTOR ADDRESS FOR THE CONTROLLER .

177770
177772
177773
177774
177775
177776
000000

• ASECT
.=177770
K.PRM:
.BLKW
.BLKB
K.PRI:
K.VCT:
.BLKB
K.CON:
.BLKB
K. IOC:
.BLKB
K.STS:
.BLKW
K.CSR:
• BLKW
i

000002
000004
000005
000006
000010
000014
000016

1
1
1
1
1
1
1

jDEVICE DEPENDANT PARAMETER WORD
iCONTROLLER PRIORITY
iINTERRUPT VECTOR ADDRESS
iCONTROLLER INDEX WITHIN THE SYSTEM
jCONTROLLER I/O COUNT
iCONTROLLER STATUS
iADDRESS OF CONTROL STATUS REGISTER

NOTE: K.CSR MUST BE THE ZERO OFFSET!

K.OFF:
K.HPU:
K.OWN:
K. CRQ:
K.URM:
K.FRK:

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

1
1
1
1
2
1
1

iOFFSET TO UCB/UMR/RHBAE TABLE
iHIGHEST PHYSICAL UNIT NUMBER
iUNUSED BYTE
jOWNER OF CONTROLLER
iCONTROLLER REQUEST QUEUE
iCONTROLLER UNIBUS RUN MASK
iPOSSIBLE KRB FORK BLOCK

OFFSETS FOR THE KRB EXTENSION REACHED BY ADDING (K.OFF) TO
THE STARTING ADDRESS OF THE KRB.

DEFINE OFFSETS IN SCB/KRB FOR DISK MSCP CONTROLLERS
i

177754
177760

.=-20.
KE. UMH:
KE. UMC:

• BLKW
• BLKW

2
1

jLIST HEAD FOR UMR WAITING ASSIGNMENT BLK(S)
jCOUNT OF AVAILABLE UMR WAITING ASSIGNMENT
jBLOCK(S)

177776

.=177776
KE.RHB: .BLKW

;OFFSET TO RHBAE REGISTER (IF ANY)

;
i WHEN ONE ADDS

(K.OFF) TO THE KRB ADDRESS, IT YIELDS AN ADDRESS
; WHICH POINTS TO HERE.
;

000000

KE.UCB: .BLKW

jOFFSET TO UCB TABLE (IF KS.UCB SET)

• PSECT

CONTROLLER REQUEST BLOCK (KRB) STATUS BIT DEFINITIONS
j

KS.OFL=1
KS.MOF=2

iCONTROLLER OFFLINE (l=YES)
;CONTROLLER MARKED FOR OFFLINE (1=YES)
A-32

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

KRBDF$ (Cont.)
KS.UOP=4
KS.MBC=10
KS.SDX=20
KS.POE=40
KS.UCB=lOO
KS.DIP=200
KS.PlDF=400
KS.EXT=1000
KS.SLO=2000

iSUPPORTS OVERLAPPED OPERATION (l=YES)
iDEVICE IS MASSBUS CONTROLLER (l=YES)
iSEEKS ALLOWED DURING DATA XFERS (l=YES)
iPARALLEL OPERATION ENABLED (l=YES)
iUCB TABLE PRESENT (l=YES)
iDATA TRANSFER IN PROGRESS (l=YES)
iPRIVILEGED DIAGNOSTIC FUNCTIONS ONLY(l=YES)
iEXTENDED 22-BIT UNIBUS CONTROLLER (l=YES)
iCONTROLLER IS SLOW COMING ONLINE (l=YES)

DEFINE THE CONTIGUOUS SCB OFFSETS

177762
177763
177764
177765
177766
177770
177772
177774
177775
177776

.ASECT
.=177762
S. PRI:
.BLKB
S. vc'r:
.BLKB
S.CON:
.BLKB
.BLKB
.BLKW
S.CSH:
.BLKW
.BLKW
.BLKB
.BLKB
.BLKW
S.OWN:

1
1
1
1
1
1
1
1
1
1

iCONTROLLER PRIORITY
iINTERRUPT VECTOR ADDRESS
iCONTROLLER INDEX
iCONTROL AND STATUS REGISTER

iDISTRIBUTED CNTBL

SUBCONTROLLER REQUEST BLOCK (KRB1)
THE SUBCONTROLLER REQUEST BLOCK DEFINES THE ENVIRONMENT OF A
DEVICE SUBCONTROLLER.
EXACTLY ONE KRB1 EXISTS FOR EVERY DEVICE
SUBCONTROLLER IN AN RSX-11M+ SYSTEM •
• ASECT
177774
177775
177776
000000

.=-4
K1.CON:
K1.s'rs:
K1.MAS:
i
i
;

000002
000004
000010

.BLKB
.BLKB
.BLKW
.BLKW

1
1
1
1

iSUBCONTROLLER INDEX WITHIN THE SYSTEM
iUNUSED BYTE
iSUBCONTROLLER STATUS
iUCB ADDRESS OF THE MASTER UNIT

No'rE: K1.MAS MUST BE THE ZERO OFFSET

K1. m~N: .BLKW
K1.CHQ: .BLKW
K1.ueB:

1
2

iOWNER OF SUBCONTROLLER
iSUBCONTROLLER REQUEST QUEUE
iSTART OF THE UCB TABLE (IF ANY)

• PSECT

A-33

RSX-11M-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

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

000000
000002
000004
000005
000006
000010
000012

• ASECT
.=0
L.LNK:
.BLKW
L.NAM:
.BLKW
L • UN IT: • BLKB
L.TYPE: .BLKB
L. UCB:
• BLKW
L • ASG :
• BLKW
L.LGTH=.-L.LNK

1
1
1
1
1
1

;LINK TO NEXT LCB
iLOGICAL NAME OF DEVICE
iLOGICAL UNIT NUMBER
iTYPE OF ENTRY (O=SYSTEM WIDE)
iTI UCB ADDRESS
iASSIGNMENT UCB ADDRESS
;LENGTH OF LCB

• PSECT

A-34

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

MTADF$
MTADF$
ANSI MAGTAPE SPECIFIC DATA STRUCTURES
VOLUME SET CONTROL BLOCK OFFSET DEFININTIONS (VSCB)
VOLUME SET AND PROCESS CONTROL SECTION
.ASECT
000000
000002
000003
000004
000020
000022
000024
000026
000030
000032
000033
000034
000036
000040
000042
000043
000044
000046
000054
000055

.=0
V.TeNT:
V.TYPE:
V.VCHA:
V. U\BL:
V. NXT:
V.MVL:
V.UVL:
V.A'rL:
V.UCB:
V.RVOL:
V.MOU:
V.TCHR:
V.SEQN:
V.SECN:
V.TPOS:
V.PSTA:
V.TIMO:
V. s'rAT:
V.TRTB:
V. El~TV:

.BLKW
.BLKB
.BLKB
.BLKB
.BLKW
.BLKW
.BLKW
.BLKW
.BLKW
.BLKB
.BLKB
.BLKW
.BLKW
.BLKW
.BLKB
.BLKB
.BLKW
.BLKW
.BLKB
.BLKB

1
1
1
12.
1
1
1
1
1
1
1
1
1
1
1
1
1
3
1
1

iTRANSACTION COUNT
iVOLUME TYPE DESCRIPTOR
iVOLUME CHARACTERISTICS
iFILE SET ID (FIRST SIX BYTES)
iPTR TO NEXT VSCB NODE
iPTR TO MOUNTED VOL LIST
iPTR TO UNMOUNTED VOL LIST
iATL ADDR OF ACCESSING TASK TCB IN RSXIIM
iADDR OF CURRENT UCB OR PUD
iCURRENT RELATIVE VOL #
iMOUNT MODE BYTE
iUINT CHAR. FOR ALL UNITS USED FOR VOL SET
iCURRENT FILE SEQUENCE #
iCURRENT FILE SECTION #
iPOSITION OF TAPE IN TM'S TO NXT HDRI
iPROCESS STATUS BYTE
iBLOCKED PROCESS TIMEOUT COUNTER
iSTATUS WORDS USED BY COMMAND EXECUTION MODS
iTRANSLATION CONTROL BYTE
iFOR MAG TO RETURN IE.EOF, EOT, EOV

LABEL DATA SECTION
i

000056
000060
000062
000070
000072
000074
000100
000104
000110
000111
000112

V.BLKL:
V.RECL:
V.FNAM:
V. F~rYp:
V.FVER:
V.CDAT:
V.EDAT:
V.BLKC:
V. R~rYp:
V.FJ\TT:

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

1
1
3
1
1
2
2
2
1
1
30 •

iBLOCK LENGTH
iRECORD LENGTH
iFILE NAME
iFILE TYPE
iFILE VERSION #
iCREATION DATE
iEXPRIATION DATE
iBLOCK COUNT FOR FILE SECTION
iRECORD TYPE
iFILE ATTRIBUTES FOR CARRIAGE CONTROL
iREMAINDER OF FILE ATTRIBUTES

NULL WINDOW SECTION
000150
000160
000162
000163
000164
000205
000206
000207

V.WIND: • BLKW
V.MST2: .BLKW
V. FJ\BY: .BLKB
.BLKB
V.ANSN: .BLKB
V.BOFF: .BLKB
V.DENS: .BLKB
V.DHAT: .BLKB

4•
1
1
1
17.
1.
1.
1.

iNULL WINDOW
iMAGTAPE STATUS BITS
iFILE ACCESSIBILITY BYTE (HDRI )
i SPARE
i ANSI 17 CHARACTER FILE NAME
iBUFFER OFFSET
iREQUESTED UNIT DENSITY
iDEFAULT RECORD ATTRIBUTES

A-35

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

MTADF$ (Cent.)
000210
000212

V.DBLK: .BLKW
V.DREC: .BLKW

000214

S.VSCB=.

1.
1.

iDEFAULT BLOCK SIZE
iDEFAULT RECORD SIZE
iSIZE OF VSCB

• PSECT
DEFINE OFFSETS INTO NULL WINDOW SECTION

000000

.ASECT
.=0
W.CTL:
.BLKW
1
V.WINC=V.WIND+W.CTL

iCONTROL WORD IN WINDOW
iCNTRL WORD IN NULL WINDOW
iRELATIVE TO THE VSCB

• PS ECT
MOUNTED VOLUME LIST OFFSET DEFININTIONS (MVL)
.ASECT
000000
000002
000004
000006
000010
000011
000012
000014

.=0
M.NXT:
M.UIC:
M.CH:
M.PROT:
M.RVOL:
M.STAT:
M.VIDP:
M.UCB:

000016

S.MVL=.

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

1
1
1
1
1
1
1
1

iPTR TO NXT MVL NODE (11M)
iOWNER UIC FROM RVOL #1
iU.CH/U.VP ( lID)
iPROTECTION U.AR IN lID
iRELATIVE VOL # OF MOUNTED VOLUME
i VOLUME STATUS
iVOLUME ID POINTER
iADDR OF ASSOC UCB OR PUD
iSIZE OF MVL NODE

• PSECT
UNMOUNTED VOLUME AND VOLUME

000000
000002
000003
000004
000012

.ASECT
.=0
L.NXT:
.BLKW
L. VaLl: .BLKB
L. VOL2: .BLKB
L.VID1: .BLKB
L.VID2: .BLKB

000020

S.UVL=.

1
1
1
6
6

LIST OFFSET DEFINITIONS (UVL)

i PTR TO NXT UVL NODE
i REL VOL # OF liST VOL
i REL VOL # OF 21ND VOL
iVOL ID OF liST VOL IN
i VOL ID OF 21ND VOL IN

IN NODE
IN NODE
NODE
NODE

is IZ E OF UVL NODE
• PSECT

SYSTEM DATA STRUCTURE CONTENT VALUES

VSCB VALUES
V.MOU VALUES
i

VM.OLD

200

iOLD .FL300 VOLUME - VM.BYP WILL ALSO BE SET
A-36

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

MTADF$ (Cont.)
VM.BYP
VM .ULB
VM. FSC
VM. EXC

100
40
20
10

iBYPASS LABEL PROCESSING
TAPE
iOVERRIDE FILE SET ID CHECK
iOVERRIDE EXPRIATION DATE CHECK

1
2
4
10
20

iMAG WANTS US TO INITIALIZE NEXT OUTPUT
iTHIS FILE HAS NO HDR2, DON'T WRITE EOF2
iTHIS FILE HAS NO HDR3, DON'T WRITE EOF3
iDON'T WRITE HDR3/EOX3 LABELS
iOVERRIDE FILE/VOLUME ACCESSIBILITY

i UNLABELED

V.MST2 VALUES
i

V2.INI
V2.XH2
V2.XH3
V2. NH3
V2.0AC

V.PSTA VALUES - UNBLOCKED TRANSITION STATE
VP.HM
VP.W'M
VP.UCM
VP.SM
VP.MOU
VP.RWD
VP.VFY
VP.POS

BLOCKED STATE

2
4

n
10
20
40
VP.RWD
100

iREAD DATA MODE
iWRITE DATA MODE
iUNLABELLED CREATE POSITIONING MODE
iSEARCH MODE
i MOUNT MODE
iREWIND OR VOL VERIFICATION WAIT
iPROCESS IN POSITIONING MODE
i (MULTI-SECTION FILE)

= -(UNBLOCKED TRANSITION STATE VALUES)

PROCESS TIMED OUT BIT 0 = 1
i

VP.TO=l

NULL WINDOW CONTROL BIT DEFINITIONS
i

WI. RDV
WI.WRV
WI. EXT
WI.LCK

400
1000
2000
4000

iACCESSED FOR READ
iACCESSED FOR WRITE
iACCESSED FOR EXTEND
iLOCKED

MVL VALUES IN THE M.STAT FIELD
i

MS.VER
MS.RID
MS. NI'v10
MS. TI'v10
MS.EXP

200
1
2

4
10

iVOL ID NOT VERIFIED
iVOL ID TO BE READ NOT CHECKED
iMOUNT MESSAGE NOT GIVEN YET
iONE TIMEOUT ALREADY EXPRIED
iEXPIRATION DATE MESSAGE GIVEN

A-37

RSX-llM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

MTADF$ (Cont.)

MISC BITS USED IN MOUNT (STORED IN V.STS)
i

MO.OVR
MO.JIC
MO.PRO
MO.160

1
2

4
10

iOVER RIDE VOL NAME SWITCH
iEXPLICIT UIC GIVEN
iEXPLICIT PROTECTION GIVEN
i1600 BPI SPECIFIED

A-38

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

OLRDF$
OLRDF$

$$$GBL

THIS MODULE DEFINES THE ONLINE RECONFIGURATION INTERFACE
AS IMPLEMENTED BETWEEN THE RSX-IIM-PLUS TASKS CON, HRC, AND
THE RDDRV.

DEFINE THE I/O FUNCTION CODES FOR ONLINE RECONFIGURATION CONTROL •
• MCALL

.WORD.,DEFIN$

.IF IDN <$$$GBL>,<DEF$G>
••• GBL=l
.IFF
••• GBL=O
• ENDC
THE FOLLOWING MACRO DEFINES THE SUB-FUNCTION CODES FOR EACH OF THE
OPERATIONS PERFORMED BY THE HRC TASK AND A PARAMETER DESCRIBING
THE ARGUMENTS REQUIRED FOR EACH FUNCTION.
IN A MACRO CALL THE
FOLLOWING ARE THE LEGAL COMBINATIONS FOR THE 'MASK'
P}\RAMETER:
SIGNIFYING NO PARAMETERS
<>
SIGNIFYING ONE BUFFER DESCRIPTOR
<D>
<D,D>
SIGNIFYING TWO BUFFER DESCRIPTORS
<D,CT>
SIGNIFYING ONE DESCRIPTOR AND 'CT' BYTES OF
PARAMETERS
SIGNIFYING 'CT' BYTES OF PARAMETERS
<CT>
.MACRO
.WORD.
FUNCA
• ENDM

FUNC NAME,SUBF,FUN,MASK
IO.'NAME,SUBF,FUN
NAME, <MASK>

.MACRO FUNCA NAME,MSK
PARCT=O
DESCT=O
.IRP X,<MSK>
.IIF IDN <X>,<P> PARCT=PARCT+l
.IIF IDN <X>,<D> DESCT=DESCT+l
.IIF GT <PARCT-17> .ERROR INVALID PARAMETER COUNT
.IIF GT <DESCT-17> .ERROR INVALID DESCRIPTOR COUNT
.ENDR
TEMP=<DESCT*4>+<PARCT*2>
.WORD.
IO$'NAME,«DESCT*20+PARCT»,TEMP
• ENDM
DEFINE ONLINE RECONFIGURATION I/O FUNCTIONS
• WORD.
.WORD.
.WORD.

MULTI-FUNCTION MODIFY CONFIGURATN
READ SYSTEM CONFIGURATION
MODIFY DEVICE CONFIGURATION

IO.MFC,OOO,OOl
IO.RSC,OOO,002
IO.WSC,OOO,006

A-39

RSX-llM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

OLRDF$ (Cont.)

DEFINE SUB FUNCTIONS TO MODIFY DEVICE CONFIGURATION
FUNC
FUNC
FUNC
FUNC
FUNC
FUNC
FUNC
FUNC
FUNC
FUNC
FUNC
FUNC
FUNC
FUNC
FUNC
FUNC
FUNC

SET DEVICE ONLINE
SET DEVICE OFFLINE
SET DEVICE IN MAINT MODE
CACHE CONTROL
MIND CONTROL
RECONFIGURATION CONTROL,
SPECIFY TASK NAME
RECONFIGURATION CONTROL,
HRC,007,006,<P,P>
HRC OPERATING MODE
ONE,OlO,006,<P,P>
ON <CONDITION> <COMMAND>
STA,Oll,006,<D>
RETURN DEVICE STATE
IF ,012,006,<P,P>
IF <CONDITION> <COMMAND>
RLI,013,006,<D,D,D,D>
LINK UNIBUS RUN
RUL,014,006,<D,D,D,D>
; UNLINK UNIBUS RUN
MBO,015,006,<P,P,D,D,D,D,D,D,D,D) ; MEM BOX ONLINE
RSW,016,006,<D,D,D,D>
; SWITCH BUS
WAT,017,006,<D>
; WRITE ATTRIBUTES
RAT,020,006,<D,D>
; READ ATTRIBUTES
MBF,02l,006,<P,P,D,D,D,D,D,D,D,D> ; MEM BOX OFFLINE
ONL,OOl,006,<D,D>
OFL,002,006,<D,D>
MAI,003,006,<D,D>
CAC,004,006,<>
MEM,005,006,<>
STN,006,006,<P,P>

IO$MAX=21
DEFINS

; DEFINE MAXIMUM SUBFUNCTION

IS.HRG,6.

STOP PROCESSING COND ENCOUNTERED
SECOND STATUS WORD IS ARGUMENT

DEFINE A MACRO, WHICH WHEN EXPANDED WITH THE APPROPRIATE
DEFINITION FOR .IOER. WILL DEFINE THE PRIVATE ERROR CODES USED BY
HRC AND CON •
• MACRO

OLREM$

$$$VAL=-256.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.

; DEFINE INITIAL ERROR NUMBER VALUE

IE$DAL,<DEVICE already linked>
IE$DNL,<DEVICE not linked>
IE$PRM,<Parameter error>
IE$SYN,<Syntax error>
IE$AFE,<Attribute format error>
IE$TMU,<HRC ••• Internal tables insufficient for this system>
IE$CAB,<Unable to access busrun>
IE$TRP,<HRC .•• internal addressing error>
IE$ALG,<Memory box parameter error>
IE$TQU,<Timeout on unit quieting operation>
IE$EPO,<ONLINE CPU failure>
IE$EUO,<ONLINE UNIT failure>
IE$ECO,<ONLINE CONTROLLER failure>
IE$EPF,<OFFLINE CPU failure>
IE$EUF,<OFFLINE UNIT failure>
IE$ECF,<OFFLINE CONTROLLER failure>
IE$CFU,<Attempt to quiet unit for controller failed>
IE$CSR,<CSR for controller not present in I/O page>

A-40

RSX-llM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

OLRDF$ (Cont.)
.IO:ER.
.IOgR.
• IOIER.
.IOER.
.IOER.
.IOER.
.IOER.
• IOJ~R.
.IOER.
• IOJ~R.
.IOER.
.IOER.
.IOER.
• IOJ~R.
.IOER.
.IOER.
• ENDM

IE$SWF,<Unable to switch unit away from current controller>
IE$ICE,<HRC ••• detected I/O database consistancy error>
IE$SCE,<Executive or Driver status change error>
IE$MDE,<HRC ••• Memory descriptor format error>
IE$NFW,<No path to target device is available>
IE$CXT,<Unable to take unit with context offline.>
IE$IDU,<Invalid device descriptor>
IE$UNK,<Device is unknown in this configuration>
IE$SZE,<HRC ••• Unable to access device to size drive>
IE$POB,<HRC ••• Can't take box offline. Partition overmaps box)
IE$NLB,<HRC ••• Can't take box offline. Not last box in memory)
IE$OMP,<HRC ••• Can't modify partition size. Overmap exists>
IE$POC,<HRC ••• Can't modify partition size. Occupied>
IE$DFE,<HRC ••• Request format error.>
IE$IDS,<HRC ••• Invalid device specification.>
IE$UOE,<HRC ••• Unkown error from online/offline call>

CONDITION CODES FOR CONDITIONS TESTED BY IO.ONE AND IO.IF FUNCTS
CO$ONL
CO$OFL
CO$UNK
CO$ACC
CO$ANY
CO$MAI

2
3
4
5
6

IF DEVICE NOW ONLINE
IF DEVICE NOW OFFLINE
UNKNOWN DEVICE
ACCESSABLE (ACCESS PATH EXISTS)
ANY ERROR CONDITION
MAINTENANCE MODE

CO$MAX

MAXIMUM CODE

CONDITION COMMAND CODES FOR IO.ONE AND IO.IF FUNCTIONS
CD$STO
CD$GOT
CD$CON

'STOP' COMMAND
'GOTO'
'CONTINUE'

CD$MAX

MAXIMUM CONDITION DEFINED

ARGUMENT DEFINITION FOR IO.HRC FUNCTION
M$LOG = I
M$INIT
2
M$DEBG
4
M$EXIT
10

SUPRESS CONFIG TRANSMISSION TO ERR LOG
INITALIZE HRC
SET HRC INTO DEBUG MODE (DEVELOPMENT ONLY)
EXIT REQUEST (FROM ABORT AST REQUEST)

DEFINE TABLE OFFSETS AND STATUS BITS RETURNED IN RESPONSE TO
A 'READ CONFIGURATION' QIO
.ASECT
000000

.=0
C$DTYP:

.BLKB

ENTRY TYPE FIELD

A-41

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

OLRDF$ (Cont.)

ENTRY TYPE CODES ARE AS FOLLOWS
ET$HDR = 1
ET$END
2

CONFIGURATION HEADER ENTRY
END OF CONFIGURATION DATA

ET$DEV

MIN VALUE FOR DEVICE SPECIFICATION ENTRY

000001

C$DECT: .BLKB

000002
000003
000004
000005

1
1
1
1

000006
000012

C$DVER: • BLKB
C$DSTD: .BLKB
C$DMUB: .BLKB
C$DMCT: .BLKB
• EVEN
C$DFAC: .BLKW
C$DIDN: • BLKW

COUNT OF TABLE ENTRIES (CPUS+SWITCHED
BUS RUNS+CONTROLLERS+UNITS)
VERSION OF RECONFIGURATION TASK PROTOCAL
SIZE OF HEADER
MAXIMUM UNIBUS RUNS SUPPORTED
MAX CONTROLLERS OF A GIVEN TYPE SUPPORTED

2
9.

FACILITES SUPPORTED IN HOST SYSTEM
HRC VERSION AND BUILD TIMESTAMP

000034

C$STD:

SIZE OF THE TABLE HEADER

OFFSETS WITHIN THE FIXED PORTION OF A GIVEN ENTRY
i

000000
000000
000002
000003
000004
000005
000006

.=0
C$DTYP:
C$DNAM:
C$DPUN:
C$DLUN:
C$DSCT:
C$DEVT:
C$DSTS:

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

1
1
1
1
1
1

ENTRY TYPE CODE
TWO ASCII CHARACTER UNIT OR CONTR NAME
CONTROLLER NUMBER (0-255.)
LOGICAL UNIT NUM IF THIS DEVICE IS A UNIT
SUB-CONTROLLER NUMBER
DEVICE TYPE CODE
DEVICE STATUS MASK

FLAG VALUES FOR C$DSTS
CS$ATR=l
CS$EXF=76

000010

C$DST2:

CS$SUB=100
iCS$XXX=200
CS$OFL=400
CS$PDF=1000
CS$POR=2000
CS$.MBD=4000
CS$UNK=lOOOO
CS$ACC=20000
CS$MTD=40000
CS$DRV=100000

VARIABLE LENGTH ATTRIBUTE INFO IS APPENDED
FIELD IN C$DSTS CONTAINING COUNT OF
ADDITIONAL BYTES IN THIS DEVICE ENTRY
THIS IS A SUB-CONTROLLER DEVIC~
UNUSED
l=)DEVICE IS OFFLINE, O=)DEVICE IS ONLINE
DEV IS RESTRICTED TO PRIVILEGED DIAG FNS
THIS IS A MULTIPORT DEVICE
DEVICE IS A MASS BUS DEVICE
DEVICE IS UNKNOWN
AN ONLINE ACCESS PATH EXISTS TO THIS DEV
DEV IS MOUNTED(DISK) OR LOGGED IN (TERM)
A DRIVER IS LOADED FOR THIS DEVICE

.BLKW

STATUS EXTENSION

CS$PUN=20
CS$CRD=40

1=) THIS DEVICE SPECIFIED WITH PHYSICAL
UNIT NUMBER
1=) THIS IS A CONTROLLER RELATIVE DEVICE
SPEC

A-42

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

OLRDF$ (Cont.)
CS$PRC=100
CS$CTL=200
CS$DCL=3400

1=> THIS IS A PORT RELATIVE CONTROLLER
SPEC
DEVICE IS A CONTROLLER (MUST BE SIGN BIT)
DEVICE CLASS CODE FIELD. MUST BE LOW ORDER
BITS OF HIGH BYTE.

DEVICE CLASS VALUES
DC$UNI = 0
DC$CTL
1
DC$MKU
2
DC$MKC
3
DC$SBU
4
DC$SBC
5
DC$CPU
6
;DC$XXX = 7
000012

C$DDAT: .BLKW

000016

C$SME:

UNIT
CONTROLLER
MEMORY BOX UNIT
MEMORY BOX CONTROLLER
SWITCHED BUS UNIT
SWITCHED BUS CONTROLLER
CPU
UNUSED
DEVICE DEPENDANT DATA
SIZE IF A MINIMUM ENTRY

VARIABLE PORTION OF A GIVEN ENTRY

FOR CONTROLLERS
;

000016

.=C$SME
C$DKPO: .BLKW

000020

C$SCT:

PORT-STATUS-WORD. THIS DESCRIBES THE BUS
RUN, CPU OR SWITCHED BUS, TO WHICH THIS
CONTROLLER IS CONNECTED.
MIMIMUM SIZE OF A CONTROLLER ENTRY

FOR UNIT ENTRIES
;

000016

.=C$SME
C$DCTN: .BLKW

000020

C$DUPO: .BLKW

000022

C$SUN:

CONTROLLER NAME. TWO CHARACTER ASCII CODE
OF THE CONTROLLER TO WHICH THIS UNIT IS
ATTACHED.
PORT-STATUS-WORD. THIS IS THE
FIRST OF THE PSWS DESCRIBING THE CONTR(S)
TO WHICH THIS UNIT IS CONNECTED.
MIMIMUM SIZE OF A UNIT ENTRY

FOR CPU-S
;

000016

.=C$SME
C$DCPO: .BLKW

000020

C$SCP:

PORT-STATUS-WORD. THIS IS THE BUS
NUMBER FOR THIS CPU.
MINIMUM SIZE OF A CPU ENTRY

A-43

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

OLRDF$ (Cont.)

FJR MEMORY BOXES
;

000016
000020

.=CSSME
C$Dt:TN: .BLKW
.BLKW

0000 3 0

C $ S 11 B :

CONTROLLER NAME.
MAXIMUM OF 4 PORTS FOR MEMORY CONTROLLERS
MAXIMUM SIZE OF A MEMORY BOX ENTRY

STATUS BIT DEFINITIONS FOR THE PORT STATUS WORD
CP$OFL=400
CP$XXX=1000
CP$CUR=2000
CP$XXX=4000
CP$XXX=10000
CP$ACC=20000
CP$MTD=40000
CP$XXX=100000

1=) PORT IS OFFLINE
UNUSED
THIS PORT IS THE CURRENT PORT (S.KRB
REFERENCES THIS PORT
UNUSED
UNUSED
THIS PORT HAS AN ACCESS PATH
PORT HAS CONTEXT OR SERVICES A DEVICE
HAVING CONTEXT
UNUSED

DJ:VICE ATTRIBUTES CODES
.MACRO ATT NAME,SIZ
$$$TMP=$$$TMP+1
DEFIN$ DA$'NAME,$$$TMP!<400*SIZ)
. ENDM
$$$TMP=O
ATT
ATT
ATT
ATT
ATT
ATT
ATT
ATT
ATT
ATT
ATT
ATT

CSR,2
VEC,2
UBR,2
TYP,2
VOL,12.
ERR,10
PRI,2
MBP,6
STE,2
SAL,2
DSN,2
CSN,10

CSR ADDRESS
VECTOR ADDRESS
UNIBUS RUN
DEVICE TYPE, READ ONLY
MOUNTED VOLUME NAME, READ ONLY
DEVICE ERROR COUNTERS, READ/WRITE
DEVICE INTERRUPT PRIORITY
MEMORY BOX PARAMETER
SANITY TIMER ENABLE/DISABLE
ALARM ENABLE/DISABLE
DEVICE SERIAL NUMBER
CPU SERIAL NUMBERS

MEMORY BOX ATTRIBUTE BUFFER
.ASECT
000000
000002
000003
000004
000006

.=0
C$MBAS:
C$MINT:

.BLKW
.BLKB
• BLKB
C$MSIZ: • BLKW
C$MGRN: .BLKW

1
1
1
1
1

BASE ADDRESS OF BOX
INTERLEAVE FACTOR
FREE BYTE
SIZE OF BOX IN 32 WORD BLOCKS
BOX GRANULARITY. "BYTES-PER-UNIT"

A-44

RSX-llM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

OLRDF$ (Cont.)
000010

C$MDSC:

SIZE OF BOX ATTRIBUTE BUFFER
• PSECT

MACRO FOR THE DEFINITION OF DEVICE TYPE CODES
.MACRO DEVCD$ $$$GBL
.MCALL DEFIN$
.IF IDN <$$$GBL),<DEF$G)
••• GB L=l
.IFF
••• GBL=O
.ENDC
.MACRO DEV X
DEFIN$ D$'X,$$$TMP
$$$TMP=$$$TMP+l
.ENDM
$$$TMP = 0
DEV UDET
DEV UKNO

UNDETERMINED DEVICE TYPE
UNKNOWN DEVICE TYPE

DEV RK03
DEV RK05
DEV RK5F

RK03
RK05
RK05-F (DUAL DENSITY FIXED CARTRIDGE)

DEV RXOI
DEV RX02

RXOI
RX02

DEV RLOI
DEV RL02

RLOI
RL02

DEV RP02
DEV RP03
DEV RP04
DEV RP05
DEV RP06
DEV' RP07

RP02
RP03
RP04
RP05
RP06
RP07

DEV RK06
DEV RK07

RK06
RK07

DEV RM02
DEV RM03
DEV RM05
DEV RM80

RM02
RM03
RM05
RM80

DEV RS03
DEV RS04

RS03
RS04 (DUAL DENSITY RS03)

DEV RFll

RFll/RS08

(DUAL DENSITY RXOl)

A-45

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

OLRDF$ (Cont.)
DEV TUlO
DEV TUl6
DEV TU45
DEV TU77
DEV TU78
DEV TSll

TUlO
TUl6
TU45
TU77
TU78
TSll

DEV TM02
DEV TM03
DEV TM78

TM02
TM03
TM78

DEV TU56
DEV TU58
DEV TU60

TU56
TU58
TU60

DEV MSCP
DEV RA60
DEV RA80
DEV RA8l

UDA50
RA60
RA80
RA8l

DEV MLll

MLll

DEV TERM

TERMINAL

$$$TMP=370
DEV USRO
DEV USRl
DEV USR2
DEV USR3
DEV USR4
DEV USR5
DEV USR6
DEV USR7

USER
USER
USER
USER
USER
USER
USER
USER

TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE

A-46

0
1

2
3
4

5
6
7

RSX-11M-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

PCBDF$
PCBDF$

"SYSDEF

MAIN PARTITION PCB
.ASECT
000000
000002
000004
000010
000012
000014
000016
000016
000020
000024
000030
000032
000034
000042
000043

.=0
P. LNK:

.BLKW
• BLKW
P. NJ\M:
.BLKW
P.SUB:
.BLKW
P.MAIN: .BLKW
P.REL:
.BLKW
P.BLKS:
P.S][ZE: .BLKW
P.WAIT: .BLKW
.BLKW
p.S~rAT:
.BLKW
P.ST2:
.BLKW
• BLKW
P.HDLN: .BLKB
.BLKB
P.IOC:
$$$==.
P.RHM:

.BLKW

iLINK TO NEXT MAIN PARTITION PCB

1
1
2
1
1
1

iPARTITION NAME IN RAD50
iPOINTER TO FIRST SUBPARTITION
iPOINTER TO SELF
iSTARTING PHYSICAL ADDRESS IN 32W BLOCKS

1
2
2
1
1
3
1
1

iSIZE OF PARTITION IN 32W BLOCKS
iPARTITION WAIT QUEUE LISTHEAD
i (UNUSED)
iPARTITION STATUS FLAGS
iSTATUS EXTENSION FOR COMMON AND MAIN PCB'S
i (UNUSED)
iSIZE OF EXTERNAL HEADER IN 32W BLOCKS
iPARTITION I/O COUNT

iREQUIRED RUN MASK

i (UNUSED)

.IF NDF M$$PRO
.=$~;$

• ENDC
.IF NB
000044

SYSDEF

P.LGTH=.

iPARTITION CONTROL BLOCK LENGTH
• ENDC

TASK REGION PCB
i

000000
000002
000003
000004
000010
000012
000014
000016
000016
000020
000022
000024
000026
000030
000032
000034
000036

.=0
P.LNK:
P.PRI:
P.RMCT:
P. NA.M:
P.SlJB:
P.MAIN:
P.RE:L:
P.BLKS:
P.SIZE:

.BLKW
.BLKB
.BLKB
.BLKW
.BLKW
.BLKW
.BLKW

1
1
1
2
1
1
1

.BLKW
.BLKW
P.SWSZ: .BLKW
P. DPCB: .BLKW
P.TCB:
.BLKW
P.S'I'AT: .BLKW
P.HDR:
.BLKW
• BLKW
P. A'I'T:
.BLKW

1
1
1
1
1
1
1
1
2

iUTILITY LINK WORD
jPRIORITY OF PARTITION
jRESIDENT MAPPED TASKS COUNT
iPARTITION NAME IN RAD50
jPOINTER TO NEXT SUBPARTITION
iPOINTER TO MAIN PARTITION
iSTARTING PHYSICAL ADDRESS IN 32W BLOCKS
iSIZE OF PARTITION IN 32W BLOCKS
i (UNUSED)

jPARTITION SWAP SIZE
iCHECKPOINT ALLOCATION PCB
iTCB ADDRESS OF OWNER TASK
iPARTITION STATUS FLAGS
iPOINTER TO HEADER CONTROL BLOCK
i (UNUSED)
iATTACHMENT DESCRIPTOR LISTHEAD

A-47

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

PCBDF$ (Cont.)
000042
000043

P.HDLN: .BLKB
P. IOC:
.BLKB

1
1

is IZ E OF EXTERNAL HEADER IN 32W BLOCKS

$$$=.
P.RRM:

iREQUIRED RUN MASK

• BLKW

iPARTITION I/O COUNT

.IF NDF M$$PRO
.=$$$
• ENDC

COMMON REGION PCB
;

000000
000002
000003
000004
000010
000012
000014
000016
000016
000020
000022
000024
000026
000030
000032
000034
000036
000042
000043

.=0
P.LNK:
P • PR I :
P. RMCT:
P. NAM:
P.SUB:
P.MAIN:
P.REL:
P.BLKS:
P.SIZE:
P.CBDL:
P.SWSZ:
P • DPC B:
P. OWN:
P.STAT:
P.ST2:
P. PR 0:
P.ATT:

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

1
1
1
2
1
1
1

iUTILITY LINK WORD
iPRIORITY OF PARTITION
iRESIDENT MAPPED TASKS COUNT
;PARTITION NAME IN RAD50
iPOINTER TO NEXT SUBPARTITION
iPOINTER TO MAIN PARTITION
iSTARTING PHYSICAL ADDRESS IN 32W BLOCKS

• BLKW
• BLKW
.BLKW
• BLKW
• BLKW
.BLKW
.BLKW
• BLKW
.BLKW
P • H D L N: • B L KB
P.IOC:
.BLKB

;SIZE OF PARTITION IN 32W BLOCKS
;COMMON BLOCK DIRECTORY LINK
;PARTITION SWAP SIZE
iPOINTER TO DISK PCB
iOWNING UIC OF REGION
iPARTITION STATUS FLAGS
;STATUS EXTENSION FOR COMMON AND MAIN PCB'S
;PROTECTION WORD [DEWR,DEWR,DEWR,DEWR]
;ATTACHMENT DESCRIPTOR LISTHEAD
iSIZE OF EXTERNAL HEADER IN 32W BLOCKS
iPARTITION I/O COUNT

$$$=.
P. RRM:

;REQUIRED RUN MASK

• BLKW

1
1
1
1

1
1

1
1
2
1

.IF NDF M$$PRO
.=$$$
• ENDC
• PSECT
PARTITION STATUS WORD BIT DEFINITIONS
i

PS.OUT=lOOOOO
PS.CKP=40000
PS.CKR=20000
PS.CHK=10000
PS.FXD=4000
PS.CAF=2000
PS.LIO=lOOO
PS.NSF=400
PS.COM=200
PS.LFR=lOO
PS.PER=40

;PARTITION IS OUT OF MEMORY(l=YES)
;PARTITION CHECKPOINT IN PROGRESS (l=YES)
iPARTITION CHECKPOINT IS REQUESTED (l=YES)
;PARTITION IS NOT CHECKPOINTABLE (l=YES)
iPARTITION IS FIXED (l=YES)
iCHECKPOINT SPACE ALLOCATION FAILURE (l=YES)
iMARKED BY SHUFFLER FOR LONG I/O (l=YES)
iPARTITION IS NOT SHUFFLEABLE (l=YES)
iLIBRARY OR COMMON BLOCK (l=YES)
iLAST LOAD OF REGION FAILED (l=YES)
iPARTIY ERROR OCCURED IN THIS REGION (l=YES)

A-48

RSX-llM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

PCBDF$ (Cont.)
iPARTITION SHOULD BE DELETED WHEN NOT
iATTACHED (l=YES)
iPARTITION HAS REGION LOAD AST PENDING

PS.DEL=lO
PS.AST=4

REQUIRED RUN MASK
;

;UNIBUS RUN T
iUNIBUS RUN S
iUNIBUS RUN R
iUNIBUS RUN P
iUNIBUS RUN N
iUNIBUS RUN M
iUNIBUS RUN L
iUNIBUS RUN K
iUNIBUS RUN J
iUNIBUS RUN H
iUNIBUS RUN F
iUNIBUS RUN E
iPROCESSOR D
i PROCESSOR C
i PROCESSOR B
i PROCESSOR A

PR.UIBT=100000
PR.U13S=40000
PR.U13R=20000
PR.U13P=10000
PR.U13N=4000
PR.U13M=2000
PR.U13L=1000
PR.U13K=400
PR.UIBJ=200
PR.U13H=100
PR.U13F=40
PR.U13E=20
PR.CPD=10
PRe CPC=4
PR. CPB=2
PR.CPA=l

STATUS EXTENSION WORD BIT DEFINITIONS
(THESE BITS CAN ONLY BE EXAMINED IN COMMON OR MAIN PCB'S)
i

iDON'T SHUFFLE,DELETE SPINDLE OR MUTILATE

P2. L1VIA=4 0000

iTHIS PARTITION
iCPCR INITIATED CHECKPOINT PENDING
iTHIS IS RO SECTION OF MU TASK
;WITH TCB IN SEC. POOL
iTHE FIXER TASK HAS HANDLED A PARITY ERROR
iSECONDARY POOL PARTITION
iMULTIPROCESSOR CPU PARTITION
iPOSITION INDEPENDENT LIBRARY OR COMMON
i(l=YES)
iREAD-ONLY COMMON (l=YES)
iDRIVER COMMON PARTITION (l=YES)
;STARTING APR NUMBER MASK FOR NON-PIC COMMON

P2.CPC=20000
P2. SIE:C=4000
P2.PAR=2000
P2.POL=1000
P2.CPU=400
P2.PIC=200
P2.RON=100
P2.DHV=40
P2.AI?R=7

CHECKPOINT FILE PCB
.ASECT
000000
000002
000004
000006
000010
000012
000014
000016
000020

.=0
P. LNI<:
P.UCB:
P.LBN:

.BLKW
.BLKW
.BLKW
.BLKW
P.SUB:
.BLKW
P.MAIN: .BLKW
P.REL:
.BLKW
P.SIZE: .BLKW
P.DLGH=.

1
1
1
1

;LINK WORD OF CHECKPOINT FILE PCB'S
iUCB ADDRESS OF CHECKPOINT FILE DEVICE
;HIGH PART OF STARTING LBN
iLOW PART OF STARTING LBN
iPOINTER TO FIRST CHECKPOINT ALLOCATION PCB
iMUST BE 0 (FOR $RLPRl)
iCONTAINS 0 IF FILE IN USE, 1 IF NOT IN USE
iSIZE OF CHECKPOINT FILE IN 256W BLOCKS
;LENGTH OF ALL DISK PCB'S

A-49

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

PCBDF$ (Cont.)
CHECKPOINT ALLOCATION PCB
i

.=0
000000
000010
000012
000014
000016

• BLKW
P. SUB:
.BLKW
P.MAIN: .BLKW
P.REL:
.BLKW
P.SIZE: .BLKW

4
1
1
1

i (UNUSED)
iLINK TO NEXT CHECKPOINT ALLOCATION PCB
iADDRESS OF CHECKPOINT FILE PCB
iRELATIVE POSITION IN FILE IN 256W BLOCKS
iSIZE ALLOCATED IN 256W BLOCKS

CJMMON TASK IMAGE FILE PCB
i

000000
000002
000004
000006
000010
000012
000014
000016

.=0
P.FIDl:
P.UCB:
P.LBN:

.BLKW
.BLKW
.BLKW
• BLKW
P.FID2: .BLKW
P.MAIN: .BLKW
P.REL:
.BLKW
P.FID3: .BLKW

A~TACHMENT

000000
000002
000003
000004
000006
000010
000011
000012
000014

1
1
1
1
1
1
1
1

iFILE ID WORD FOR SAVE
iUCB ADDR OF DEVICE ON WHICH COMMON RESIDES
iHIGH PART OF STARTING LBN
iLOW PART OF STARTING LBN
iFILE ID WORD FOR SAVE
iPOINTER TO SELF
iALWAYS CONTAINS A 0
iFILE ID WORD FOR SAVE

DESCRIPTOR OFFSETS

.ASECT
.=0
A. peBL: '.BLKW
A. PHI:
.BLKB
A. IOC:
.BLKB
A.TeB:
.BLKW
A.TeBL: .BLKW
A.STAT: .BLKB
A. MPCT: .BLKB
A.PCB:
.BLKW
A.LGTH=.

1
1
1
1
1
1
1
1

iPCB ATTACHMENT QUEUE THREAD WORD
iPRIORITY OF ATTACHED TASK
;1/0 COUNT THROUGH THIS DESCRIPTOR
iTCB ADDRESS OF ATTACHED TASK
iTCB ATTACHMENT QUEUE THREAD WORD
iSTATUS BYTE
iMAPPING COUNT OF TASK THRU THIS DESCRIPTOR
iPCB ADDRESS OF ATTACHED TASK
iLENGTH OF ATTACHMENT DESCRIPTOR

ATTACHMENT DESCRIPTOR STATUS BYTE BIT DEFINITIONS
• PSECT
AS.PRO=100
AS.SBP=20
AS.RBP=40
AS.DEL=10
AS. EXT=4
AS.WRT=2
AS.F:ED=l

iA.TCB IS SEC POOL TCB BIAS (l=YES)
iCACHE BYPASS REQUESTED
iREQUEST TO NOT BYPASS CACHE
iTASK HAS DELETE ACCESS (l=YES)
;TASK HAS EXTEND ACCESS (l=YES)
iTASK HAS WRITE ACCESS (l=YES)
iTASK HAS READ ACCESS (l=YES)

A-50

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

PKTDF$
PKTDF$
ASYNCHRONOUS SYSTEM TRAP CONTROL BLOCK OFFSET DEFINITIONS
SOME POSITIONAL DEPENDENCIES BETWEEN THE OCB AND THE AST CONTROL
BLOCK ARE RELIED UPON IN THE ROUTINE $FINXT IN THE MODULE SYSXT •

177774
177776
000000
000002

000004
000006
000010
000012

• ASECT
.=177774
A.KSR5: .BLKW
A.DQSR: .BLKW
.BLKW
A.CBL:
.BLKW

A.BYT:
A.AST:
A.NPR:
A. Pf;~M:

.BLKW
.BLKW
.BLKW
.BLKW

AS.PPA=l
AS.HCA=2
AS.HRA=3
AS.PEA=4
AS.HEA=5
AS.PFA=6
AS.CAA=7

1
1
1
1

iSUBROUTINE KISAR5 BIAS (A.CBL=O)
iDEQUEUE SUBROUTINE ADDRESS (A.CBL=O)
iAST QUEUE THREAD WORD
iLENGTH OF CONTROL BLOCK IN BYTES
iIF A.CBL = 0, THE AST CONTROL BLOCK IS
iTO BE DEALLOCATED BY THE DEQUEUE SUBROUTINE
iPOINTED TO BY A.DQSR MAPPED VIA APR 5
iVALUE A.KSR5.
THIS IS CURRENTLY USED ONLY
iBY THE FULL DUPLEX TERMINAL DRIVER FOR
iUNSOLICITED CHARACTER ASTS.
iIF THE LOW BYTE OF A.CBL = 0, AND THE
iHIGH BYTE IS NOT = 0, THE AST CONTROL BLOCK
iIS A SPECIFIED AST, WITH LENGTH, C.LGTH.
iIF THE HIGH BYTE OF A.CBL=O
iAND THE LOW BYTE> 0, THEN
iTHE LOW BYTE IS THE LENGTH OF THE
iAST CONTROL BLOCK.
iIF HIGH BYTE = a AND LOW BYTE IS NEGATIVE,
iTHEN THE BLOCK IS A KERNEL AST
iBIT 6 IS SET IF $SGFIN SHOULD
iNOT BE CALLED PRIOR TO DISPATCHING
iTHE AST, AND THE LOW SIX BITS (5-0)
;REPRESENT THE INDEX/2 INTO THE
;KERNEL AST DISPATCH TABLE ($KATBL)
iNUMBER OF BYTES TO ALLOCATE ON TASK STACK
;AST TRAP ADDRESS
iNUMBER OF AST PARAMETERS
;FIRST AST PARAMETER
iCODE
;CODE
i CODE
;CODE
iCODE
i CODE
i CODE

FOR
FOR
FOR
FOR
FOR
FOR
FOR

FLOATING POINT AST
RECEIVE DATA AST
RECEIVE BY REFERENCE AST
PARITY ERROR AST
REQUESTED EXIT AST
POWER FAIL AST
CLI COMMAND ARRIVAL AST

ABORTER SUBCODES FOR ABORT AST (AS. REA) TO BE RETURNED ON USER'S
S1~ACK

;

AB.NPV=l
AB. ~ryp=2
A.PLGH=70
A.DUCB=10
A.DLGH=10.

iABORTER IS NONPRIVILEGED (l=YES)
iABORT FROM DIRECTIVE (O=YES)
;ABORT FROM CLI COMMAND (l=YES)
iSIZE OF PARITY ERROR AST CONTROL BLOCK
iUCB OF TERM ISSUING DEBUG COMMAND
iLENGTH OF DEBUG (AK.TBT) AST BLOCK

A-51

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

PKTDF$ (Cont.)

KERNEL AST CONTROL CODES (A.CBL)
i

AK.BUF=200

iBUFFERED I/O COMPLETION
iTHIS CODE MUST BE 200 UNTIL ALL
iREFERENCES IN TTDRV ARE FIXED
iOFFSPRING TASK EXIT
iSEGMENTED BUFFERED I/O COMPLETION
iTASK FORCE T-BIT TRAP (DEBUG CMD)
iDELAYED I/O COMPLETION
iGRP. GBL. RUNDWN

AK.OCB=201
AK.GBI=202
AK.TBT=203
AK.DIO=204
AK.GGF=205

BIT DEFINITIONS FOR THE GET/SET INFORMATION DIRECTIVE.
i

SF.PRV=100000
SF.IN= 40000

iFUNCTION IS PRIVILEGED
iFUNCTION IS AN INPUT FUNCTION

GROUP GLOBAL EVENT FLAG BLOCK OFFSETS
i

000000
000002
000003
000004
000006

.=0
G. LNK:
G.GRP:
G.STAT:
G.CNT:
G. EFLG:

000012

G.LGTH=.

iLENGTH OF GROUP GLOBAL EVENT FLAG BLOCK

GS.DEL=l

iSTATUS BIT -- MARKED FOR DELETE

.BLKW
.BLKB
.BLKB
.BLKW
.BLKW

1
1
1
1
2

i LINK WORD
iGROUP NUMBER
iSTATUS BYTE
iACCESS COUNT
iEVENT FLAGS

EXECUTIVE POOL MONITOR CONTROL FLAGS

$POLST IS THE SYNCHRONIZATION WORD BETWEEN THE EXEC AND POOL
MONITOR
i

PC.HIH=l
PC. LOW=2
PC.ALF=4
PC.XIT=200
PC.NRM=PC.HIH*400
PC.ALM=PC.LOW*400
i
i

iHIGH POOL LIMIT CROSSED (l=YES)
iLOW POOL LIMIT CROSSED (l=YES)
iPOOL ALLOCATION FAILURE (l=YES)
iFORCE POOL MONITOR TASK TO EXIT (MUST
iBE COUPLED WITH SETTING FE.MXT IN THE
iFEATURE MASK)
iPOOL TASK INHIBIT BIT FOR HIGH POOL
iPOOL TASK INHIBIT BIT FOR LOW POOL

$POLFL IS THE POOL USAGE CONTROL WORD

PF.INS=40
PF.LOG=100
PF.REQ=200
PF.ALL=177777

iREJECT NONPRIVILEGED INS/RUN/REM
iNONPRIVILEGED LOGINS ARE DISABLED
iSTALL REQUEST OF NONPRIV. TASKS
iTAKE ALL POSSIBLE ACTIONS TO SAVE POOL

A-52

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

PKTDF$ (Cont.)

OFFSPRING CONTROL BLOCK DEFINITIONS
SOME POSITIONAL DEPENDENCIES ARE DEPENDED ON BETWEEN THE OCB AND
THE AST BLOCK IN THE ROUTINE $FINXT IN THE MODULE SYSXT.
i

000000
000002
000004
000006
000010
000012
000014

.=0
O. LNK:
.BLKW
O.MCRL: .BLKW
O. p~rCB: .BLKW
O.AST:
.BLKW
O.E]~N:
.BLKW
O.ESB:
.BLKW
o.s~rAT:
.BLKW

000034

O.LGTH=.

1
1
1
1
1
1
8.

i OCB LINK WORD

iADDRESS OF MCR COMMAND LINE

i PARENT TCB ADDRESS

iEXIT AST ADDRESS
iEXIT EVENT FLAG
jEXIT STATUS BLOCK VIRTUAL ADDRESS
jEXIT STATUS BUFFER
jLENGTH OF OCB

I/O PACKET OFFSET DEFINITIONS
.ASECT
.=0
I. LNK:
I.PHI:

000000
000002
000003
000004
000006
000010
000012
000014
000016
000020
000022
000024
000026
000042

.BLKW
.BLKB
I . EIi'N:
.BLKB
I.TCB:
• BLKW
I.LN2:
• BLKW
I.ueB:
.BLKW
I.FCN:
.BLKW
I.IOSB: .BLKW
.BLKW
.BLKW
I.AST:
.BLKW
I. PHM:
• BLKW
• BLKW
• BLKW

000044

I. A'I'TL=.

000044

I. AA.DA:

0.00050

I.LGTH=.
I. AT'RL=6 *8.

• BLKW

6
1

jI/O QUEUE THREAD WORD
jREQUEST PRIORITY
iEVENT FLAG NUMBER
iTCB ADDRESS OF REQUESTOR
jPOINTER TO SECOND LUN WORD
jPOINTER TO UNIT CONTROL BLOCK
iI/O FUNCTION CODE
jVIRTUAL ADDRESS OF I/O STATUS BLOCK
jI/O STATUS BLOCK RELOCATON BIAS
iI/O STATUS BLOCK ADDRESS
jAST SERVICE ROUTINE ADDRESS
jRESERVED FOR MAPPING PARAMETER #1
jPARAMETERS 1 TO 6
iUSER MODE DIAGNOSTIC PARAMETER WORD

iMINIMUM LENGTH OF I/O PACKET (USED BY
jFILE SYSTEM TO CALCULATE MAXIMUM
jNUMBER OF ATTRIBUTES)
iSTORAGE FOR ATT DESCR PTRS WITH I/O

1
1

1
1
1

1
1
1
1
1

iLENGTH OF I/O REQUEST CONTROL BLOCK
jLENGTH OF FILE SYSTEM ATTRIBUTE BLOCK

CLI PARSER BLOCK (CPB) DEFINITIONS
j

000000
000002
000006
000010
000011
000012

.=0
C. PTCB:
C. PNAM:
C. PSTS:
C.PDPL:
C. PCPL:
C.PRMT:

• BLKW
• BLKW
• BLKW
.BLKB
• BLKB

1
2

1
1

jADDRESS OF CLI'S TCB
JCLI NAME
iSTATUS MASK
jLENGTH OF DEFAULT PROMPT
iLENGTH 0 CNTRL/C PROMPT
iSTART OF PROMPT STRINGS. DEFAULT
iIS CON:ATENATED WITH CONTROL C PROMPT

A-53

RSX-11M-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINI'rIONS

PKTDF$ (Cont.)

STATUS BIT DEFINITIONS
i

iPASS EMPTY COMMANDS TO CLI
JCLI DESIRES SYSTEM MESSAGES
iCLI WANTS COMMANDS FROM LOGGED OFF TTYS
iCLI IS DISABLED
iUSER MUST BE PRIV TO SET TTY TO THIS CLI
iDON'T HANDLE CONTINUATIONS (M-PLUS ONLY)
iMCR ••• , HEL, BYE DO NO I/O TO TTY
jHEL, BYE DO NOT SET CLI ETC.
iABILITY TO SET TO THIS CLI IS RESTRICTED
iTO THE CLI ITSELF
iPASS TASK EXIT PROMPT REQUESTS TO CLI
iCLI TCB IS IN SECONDARY POOL

CP.NUL=l
CP.MSG=2
CP.LGO=4
CP.DSB=10
CP.PRV=20
CP.SGL=40
CP.NIO=100
CP.RST=200
CP.EXT=400
CP.POL=1000

SECONDARY POOL COMMAND BUFFER BLOCKS
i

000000
000002
000004
000006
000010
000012
000012
000014
000015
000016

.=0
C.CLK:
C.CTCB:
C.CUCB:
C.CCT:
C.CSTS:
C.CMCD:
C.CSO:
C.CTR:
C.CBLK:
C.CTXT:

.BLKW
.BLKW
.BLKW
.BLKW
.BLKW

.BLKW
.BLKB
.BLKB

1
1

1
1
1
1
1

i LINK WORD
iTCB ADDRESS OF TASK TO RECEIVE COMMAND
iUCB ADDRESS OF RESPONSIBLE TERMINAL
iCHARACTER COUNT, EXCLUDING TRAILING CR
iSTATUS MASK
iSYSTEM MESSAGE CODE
iSTARTING OFFSET OF VALID COMMAND TEXT
iTERMINATOR CHARACTER
iSIZE OF PACKET IN SEC POOL (32 WD.) BLOCKS
iCOMMAND TEXT, FOLLOWED BY CR

STATUS BITS FOR COMMAND BLOCKS
i

CC.MCR=l
CC.PRM=2
CC.EXT=4
CC.KIL=10
CC.CLI=20
CC.MSG=40
CC.TTD=100

;FORCE COMMAND TO MCR
iISSUE DEFAULT PROMPT
jTASK EXIT PROMPT REQUEST
iDELETE ALL CONTINUATION PIECES FROM THIS TT
iCOMMAND TO BE RETREIVED BY GCCI$ ONLY
iPACKET CONTAINS SYSTEM MESSAGE TO CLI
;COMMAND CAME FROM TTDRV

IDENTIFIER CODES FOR SYSTEM TO CLI MESSAGES
CODES 0-127. ARE RESERVED FOR USE BY DIGITAL
CODES 128.-255. ARE RESERVED FOR USE BY CUSTOMERS
i

CM.INE=l
CM.IND=2
CM.CEN=3
CM.CDS=4
CM.ELM=5
CM.EXT=6
CM.LKT=7
CM.RMT=8.
CM.MSG=9.

JCLI INITIALIZED ENABLED
;CLI INITIALIZED DISABLED
JCLI ENABLED
JCLI DISABLED
JCLI BEING ELIMINATED
iCLI MUST EXIT IMMEDIATELY
;NEW TERMINAL LINKED TO CLI
jTERMINAL REMOVED FROM CLI
jGENERAL MESSAGE TO CLI

A-54

RSX-11M-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

PKTDF$ (Cont.)

ANCILLARY CONTROL BLOCK (ACB) DEFINITIONS
i

000000
000002
000004
000006
000007
000010
000012
000013

.=0
A.REL:
A.DIS:
A. MJ~S:
A.NUM:
A.LIN:
A.ACC:
A. S1~A:

000014

A. LE:Nl=.

000010
000012
000014
000016
000020
000022
000024
000030

.=A.LIN
A. I~IAP:
A.IBUF:
A.ILEN:
A. StJIAP:
A.SBUF:
A.SLEN:
A. lOS:
A.RE:S:

000032

A.LE:N2=.

.BLKW
.BLKW
.BLKW
.BLKB
.BLKB
.BLKW
.BLKB
.BLKB

1
1
1
1
1
1
1
1

iACD RELOCATION BIAS
iACD DISPATCH TABLE POINTER
iACD FUNCTION MASK
iACD IDENTIFICATION NUMBER
iRESERVED
iACD LINK WORD
iACD ACCESS COUNT
iACD STATUS BYTE
iLENGTH OF PROTOTYPE ACB
iFULL ACB OVERLAPS PROTOTYPE ACB

• BLKW
.BLKW
• BLKW
• BLKW
.BLKW
.BLKW
• BLKW
.BLKW

1
1

2
1

iACD INTERRUPT BUFFER RELOCATION BIAS
iACD INTERRUPT BUFFER ADDRESS
iACD INTERRUPT BUFFER LENGTH
iACD SYSTEM STATE BUFFER RELOCATION BIAS
iACD SYSTEM STATE BUFFER ADDRESS
iACD SYSTEM STATE BUFFER LENGTH
iACD I/O STATUS
iRESERVED FOR USE BY THE ACD
iLENGTH OF FULL ACB

DE:FINE THE FLAG VALUES IN THE OFFSET U. AFLG
i

UA.A,CC=l
UA. PRO=2
UA. E:CH=4
UA. 'I'YP= 10
UA.SPE=20
UA.PUT=40
UA.CAL=100
UA.COM=200
UA.A.LL=400
UA.'I'RA=1000

iACCEPT THIS CHARACTER
iPROCESS THIS CHARACTER
iECHO THIS CHARACTER
iFORCE THIS CHARACTER INTO TYPEAHEAD
iTHIS CHARACTER HAS A SPECIAL ECHO
iPUT THIS CHARACTER IN THE ~NPUT BUFFER
iCALL THE ACD BACK AFTER THE TRANSFER
iCOMPLETE THE INPUT REQUEST
iALLOW PROCESSING OF THIS I/O REQUEST
iTRANSFER CHARS. WHEN I/O COMPLETES

DEFINE THE ACD ENTRY POINTS (OFFSETS INTO THE DISPATCH TABLE)
i

000000
000002
000004
000006
000010
000012
000014
000016
000020
000022

.=0
A.ACCE:
A.DEQU:
A.POWE:
A.INPU:
A.OUTP:
A.CONN:
A.DISC:
A.RECE:
A.PROC:
A.CALL:

.BLKW
.BLKW
.BLKW
.BLKW
.BLKW
.BLKW
.BLKW
.BLKW
.BLKW
.BLKW

1
1

iI/O REQUEST ACCEPTANCE ENTRY POINT
iI/O REQUEST DEQUEUE ENTRY POINT

1
1

iPOWER FAILURE ENTRY POINT
iINPUT COMPLETION ENTRY POINT
iOUTPUT COMPLETION ENTRY POINT
iCONNECTION ENTRY POINT
iDISCONNECTION ENTRY POINT
iINPUT CHARACTER RECEPTION ENTRY POINT
iINPUT CHARACTER PROCESSING ENTRY POINT
iCALL ACD BACK AFTER TRANSFER ENTRY POINT

1
1
1
1
1
1

A-55

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

PKTDF$ (Cont.)

DEFINE THE STATUS BITS IN A.STA OF THE PROTOTYPE ACB
i

AS. DEL=l
AS.C>IS=2

iACD IS MARKED FOR DELETE
iACD IS DISABLED
• PSECT

A-56

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

SCBDF$
SCBDF$

"SYSDEF

STATUS CONTROL BLOCK
THE STATUS CONTROL BLOCK (SCB) DEFINES THE STATUS OF A DEVICE
CONTROLLER.
THERE IS ONE SCB FOR EACH CONTROLLER IN A SYSTEM.
THE SCB IS POINTED TO BY UNIT CONTROL BLOCKS. TO EXPAND ON THE
TELETYPE EXAMPLE ABOVE, EACH TELETYPE INTERFACED VIA A DLII-A
WOULD HAVE A SCB SINCE EACH DLII-A IS AN INDEPENDENT INTERFACE
UNIT.
THE TELETYPES INTERFACED VIA THE DHII WOULD ALSO EACH HAVE
AN SCB SINCE THE DHII IS A SINGLE CONTROLLER BUT MULTIPLEXES MANY
UNITS IN PARALLEL •
• IF NB

SYSDEF

.ASECT
000000
000004

.=0
S.LHD:
S.URM:

iCONTROLLER I/O QUEUE LISTHEAD
iREFERENCE LABEL

.BLKW

.IF DF

M$$PRO

.BLKW

iUNIBUS RUN MASK FOR THE FORK BLOCK

1
1
1
1
1
1
1
1
1
1
1
1

iFORK BLOCK LINK WORD
iFORK-PC
i FORK-R5
iFORK-R4
iFORK KISAR5
iADDRESS OF CURRENT I/O PACKET
;CURRENT TIMEOUT COUNT
;INITIAL TIMEOUT COUNT
;STATUS (O=FREE, NE O=BUSY)
;STATUS EXTENSION BYTE
;STATUS EXTENSION
;ADDRESS OF KRB
;NUMBER OF REGISTERS TO COpy
;OFFSET TO FIRST DEV REG TO COPY
;ERROR MESSAGE BLOCK POINTER
;START OF MULTI-ACCESS KRBS

• ENDC
000004
000006
000010
000012
000014
000016
000020
000021
000022
000023
000024
000026
000030
000031
000032
000034

S.FRK:

.BLKW
.BLKW
.BLKW
.BLKW
.BLKW
S KS 5:
.BLKW
S.PKT:
S.CTM:
.BLKB
S.ITM:
.BLKB
S.STS:
.BLKB
S.ST3:
.BLKB
S.ST2:
.BLKW
S.KRB:
.BLKW
S.RCNT: .BLKB
S.ROFF: .BLKB
S.EMB:
.BLKW
S.KTB:
.BLKW
u

1
1
1

• PSECT
.IFF
STATUS CONTROL BLOCK
i

S2.EIP=1
S2.ENB=2
S2.LOG=4
S2.MAD=10
S2.LDS=40
S2.0PT=100
S2.CON=200

STATUS EXTENSION BIT DEFINITIONS
iERROR IN PROGRESS (l=YES)
;ERROR LOGGING ENABLED (O=YES)
;ERROR LOGGING SUPPORTED (l=YES)
;MULTIACCESS DEVICE (l=YES)
;LOAD SHARING ENABLED (l=YES)
;SUPPORTS SEEK OPTIMIZATION (l=YES)
;SCB AND KRB ARE CONTIGUOUS (l=YES)

A-57

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

SCBDF$ (Cont.)
iTHESE TWO BITS DEFINE THE OPTIMIZATION
iMETHOD.
iOP2,OP1=0,0 INDICATES NEAREST CYLINDER
iOP2,OP1=0,1 INDICATES ELEVATOR
iOP2,OP1=1,0 INDICATES C-SCAN
iOP2,OP1=1,1 RESERVED
iDRIVER HAS OPERATION OUTSTANDING (1=YES)
iEXTERNAL HEADER AND NEW I.LN2 SUPPORT

S2.0P1=400
S2.0P2=1000

S2.1. CT=2000
S2.XHR=4000

CONTROL BLOCK STATUS EXTENSION (S.ST3) DEFINITIONS

S~'ATUS

S3. DRL=1
S 3. ~!RL=2
S3.SIP=4
S3 .J,TN=l 0
S3.~;LV=20

S3. ~,PA=40
S 3. f: PB = 100
S3.0PT=200
S3.SPU=S3.SPA!S3.SPB

iMULTI-ACCESS DRIVE IN RELEASED STATE(1=YES)
iDRIVER SHOULDN'T RLS MULTI-ACCESS DRIVE
i(1=YES)
;SEEK IN PROGRESS (l=YES)
iDRIVER MUST CLEAR ATTENTION BIT (l=YES)
iDEVICE USES SLAVE UNITS (l=YES)
iPORT 'A' SPINNING UP
iPORT 'B' SPINNING UP
iSEEK OPTIMIZATION ENABLED (1=YES)
i.OR. OF PORT SPINUP BITS

KFB ADDRESS TABLE (S.KTB) PORT OFFLINE FROM THIS SCB FLAG.
i

KP. ('FL=1

iKRB ADDRESS POINTS TO OFFLINE PORT (l=YES)

MPPPING ASSIGNMENT BLOCK (FOR UNIBUS MAPPING REGISTER ASSIGNMENT)
.ASECT
000000
000002
000004
000006
000010
000011
000012
000014

.=0
M.LNK:
M. UM RA :
M. UM RN :
M• U~ VL :
M. UM VH :
M. BFVH:
M • B FVL :

.BLKW
• BLKW
• BLKW
• BLKW
• BLKB
• BLKB
• B L KW

M.LGTH= •

1
1
1
1
1
1
1

i LINK WORD
iADDRESS OF FIRST ASSIGNED UMR
iNUMBER OF UMR'S ASSIGNED * 4
iLOW 16 BITS MAPPED BY 1ST ASSIGNED UMR
iHIGH 2 BITS MAPPED IN BITS 4 AND 5
iHIGH 6 BITS OF PHYSICAL BUFFER ADDRESS
iLOW 16 BITS OF PHYSICAL BUFFER ADDRESS
iLENGTH OF MAPPING ASSIGNMENT BLOCK

• ENDC
• PSECT

A-58

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

SHDDF$
SHDDF$
FIRST, WE MUST DEFINE THE I/O PACKET DEFINITIONS, SINCE WE
USE THEM IN OUR DEFINITIONS.
PKTDF$

iDEFINE I/O PACKET DEFINITIONS

SHADOW RECORDING LINKAGE BLOCK (UMB)
THE UMB LINKS TOGETHER TWO UCB'S AS A SHADOW SET.
ONE IS THE
PRIMARY UCB, THE OTHER THE SECONDARY UCB.
THE EXISTANCE OF A
UM.B SIGNALS THAT SHADOW RECORDING IS ENABLED ON A PARTICULAR
UCB.
.ASECT
000000
000002
000004
000010
000012
000013
000014
000016

.=0
M. LNK:
M.LHD:
M.UCB:
M.ST'S:
M.LBN:

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

1
1
2

1
1
1
1

iLINKAGE OF ALL UMB'S IN THE SYSTEM
iLISTHEAD OF ALL ML NODES FOR THIS SET
iPRIMARY AND SECONDARY UCB ADDRESSES
iSTATUS WORD
iHIGH ORDER BYTE OF FENCE
iUNUSED BYTE (MAYBE STATUS?)
iLOW ORDER WORD OF FENCE

M.LGH=.

UMB STATUS BIT DEFINITIONS
• PSECT
MS.MDA=l
MS.CHP=2

iUMB MARKED FOR DEALLOCATION (l=YES)
iCATCHUP IN PROGRESS (l=YES)

DEFINE THE OFFSETS FOR THE ML NODE, LINKED OFF OF THE UMB
THROUGH CELL M.LHD.
THIS NODE CONTAINS THE SECONDARY I/O
PACKET, AND DOUBLES AS THE ERROR PACKET TO THE ERROR MESSAGE
TASK.
.ASECT
000000
000002
000003
000004
000005
000006
000010
000060

.=0
ML. LNK:
ML.LEN:
ML. T'YP:
ML. DNC:

.BLKW
.BLKB
.BLKB
• BLKB
• BLKB
ML. PRI: .BLKW
ML.PKT: .BLKB

1
1
1
1
1
1
I.LGTH

iLINKAGE OF ALL ML NODES ON UMB
iLENGTH OF ML NODE FOR DEALLOCATION
iTYPE OF ML NODE FOR ERROR TASK
iDONE COUNT OF PACKETS
iUNUSED
iPRIMARY I/O PACKET ADDRESS
iSECONDARY I/O PACKET

ML.LGH=.

A-59

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS .

SHDDF$ (Cont.)

NODE TYPE CODES
.PSECT

MT.PKT=l

;ML NODE IS I/O PACKET TYPE

I/O PACKET OFFSET DEFNS FOR USE BY SHADOW RECORDING
I.RO=I.PRM
I.Rl=I.PRM+2

;STATUS STORAGE FOR RO STATUS
;STATUS STORAGE FOR Rl STATUS

DEFINE THE ERROR MESSAGE POINTERS THAT RESIDE IN THE I/O PACKET •
• PSECT
ML.FID=ML.PKT+I.IOSB
ML.FSEQ=ML.PKT+I.IOSB+2
ML.LBN=ML.PKT+I.PRM+IO
ML.:NT=ML.PKT+I.PRM+4
ML.TCB=ML.PKT+I.TCB
ML.SRO=ML.PKT+I.RO
ML.SRl=~L.PKT+I.Rl

ML.PRO=ML.PKT+I.PRM+14
ML.PRl=ML.PKT+I.PRM+16

iFILE ID WHICH CONTAINS ERROR
;FILE SEQUENCE NUMBER OF FILE IN ERROR
;HIGH ORDER LBN OF BLOCK(S) IN ERROR
iNUMBER OF BLOCKS IN BAD XFER
iTCB OF TASK WITH BAD REQUEST
iRO OF SECONDARY I/O PACKET
iRl OF SECONDARY I/O PACKET
iRO OF PRIMARY I/O PACKET
iRl OF PRIMARY I/O PACKET

A-60

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

TCBDF$
TCBDF$

"SYSDEF

TASK CONTROL BLOCK OFFSET AND STATUS DEFINITIONS
TASK CONTROL BLOCK
.ASECT
000000
000002
000003
000004
000006
000012
000016
000022
000026
000030
000032
000034
000036
000040
000041
000044
000046
000050
000052
000054
000060
000062
000063
OOOOu4
000065
000066
000072

000074
000076
000077
000100

.=0
T.LNK:
T • PFt I :
T. I OC :
T. PCBV:
T. NAM :
T.RCVL:
T.ASTL:
T. EF'LG:
T.ueB:
T • TC B L :

T. S'I'AT:
T.S'I'2:
T.S'I'3:
T.DPRI:
T.LBN:
T.LDV:
T.PCB:
T.MXSZ:
T.ACTL:
T. AT'T:
T.ST4:
T.HDLN:
T.GGF:
T.TIO:
T.EFLM:
T.TKSZ:

.BLKW
• BLKB
• BLKB
• BLKW
• BLKW
.BLKW
.BLKW
• BLKW
.BLKW
• B L KW
• BLKW
.BLKW
.BLKW
.BLKB
.BLKB
.BLKW
.BLKW
.BLKW
• BLKW
.BLKW
.BLKW
• BLKB
.BLKB
.BLKB
.BLKB
.BLKW
.BLKW

$$$=.
T.OFF:

.BLKW
.BLKB
T. SRCT : • BLKB
T.RRFL: .BLKW

1
1
1

1
2
2
2
2

1
1
1
1
1

1
3
1
1
1
1
2
1
1
1
1
1
2
1

1
1
2

iUTILITY LINK WORD
iTASK PRIORITY
iI/O PENDING COUNT
iPOINTER TO COMMON PCB VECTOR
iTASK NAME IN RAD50
iRECEIVE QUEUE LISTHEAD
iAST QUEUE LISTHEAD
iTASK LOCAL EVENT FLAGS 1-32
iUCB ADDRESS FOR PSEUDO DEVICE 'TI'
iTASK LIST THREAD WORD
iFIRST STATUS WORD (BLOCKING BITS)
iSECOND STATUS WORD (STATE BITS)
iTHIRD STATUS WORD (ATTRIBUTE BITS)
iTASK'S DEFAULT PRIORITY
iLBN OF TASK LOAD IMAGE
iUCB ADDRESS OF LOAD DEVICE
iPCB- ADDRESS OF TASK PARTITION
iMAXIMUM SIZE OF TASK IMAGE (MAPPED ONLY)
iADDRESS OF NEXT TASK IN ACTIVE LIST
iATTACHMENT DESCRIPTOR LISTHEAD
iFOURTH TASK STATUS WORD
iLENGTH OF HEADER (0 IF HDR IN POOL)
iUNUSED
iGROUP GLOBAL USE COUNT FOR TASK
iBUFFERED I/O IN PROGRESS COUNT
iTASK WAITFOR MASK/ADDRESS
iTASK LOAD SIZE IN 32 WD BLOCKS
iMARK START OF PLAS AREA
iOFFSET TO TASK IMAGE IN PARTITION
iRESERVED
iSREF WITH EFN COUNT IN ALL RECEIVE QUEUES
iRECEIVE BY REFERENCE LISTHEAD

.IF NDF P$$LAS
.=$$$

iMOVE LC BACK TO START OF PLAS AREA
• ENDC
.IF NB

SYSDEF

$$$=.

aaa1 04

T • OC 13 H :

• B L KW

000110

T.RDCT: .BLKW

;MARK START OF PARENT/OFFSPRING AREA
iOFFSPRING CONTROL BLOCK LISTHEAD
iOUTSTANDING OFFSPRING AND VT: COUNT

.IF NDF P$$OFF
.=$$:S
• ENDC

A-61

RSX-11M-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

TCBDF$ (Cont.)
000112

T.~AST:

$$$=.
T.RRM:
T.IRM:
T.CPU:

• BLKW

;SPECIFY AST LIST HEAD

• BLKW
.BLKW
.BLKB
• BLKB

;REQUIRED RUN MASK
;INITIAL RUN MASK SET UP BY INSTALL
;PROCESSOR NUMBER ON WHICH TASK LAST EXECUTD
; (UNUSED)

1
1

.IF NDF M$$PRO
.=$$$
• ENDC
$$$=.
T.ACN:

• BLKW

;POINTER TO ACCOUNTING BLOCK

.IF NDF A$$CNT
.=$$$
· ENDC
$$$=.
T.ISIZ: .BLKW

;SIZE OF ROOT I SPACE

.IF NDF U$$DAS
.=$$$
• ENDC
T.LGTH=.
T.EXT=O

;LENGTH OF TASK CONTROL BLOCK
;LENGTH OF TCB EXTENSION
.IFF

TASK STATUS DEFINITIONS

FIRST STATUS WORD (BLOCKING BITS)

TS.EXE=100000
TS.RDN=40000
TS.MSG=20000
TS.CIP=10000
TS.RUN=4000
TS.STP=1000
TS.CKR=100
TS.BLC=37

;TASK NOT IN EXECUTION (1=YES)
;1/0 RUN DOWN IN PROGRESS (1=YES)
;ABORT MESSAGE BEING OUTPUT (l=YES)
;TASK BLOCKED FOR CHECKPOINT IN PROGRESS
;(1=YE3)
;TASK IS RUNNING ON ANOTHER PROCESSOR(1=YES)
;TASK BLOCKED BY CLI COMMAND
;TASK HAS CKP REQUEST (MP SYSTEM ONLY)
; (1=YES)
;INCREMENT BLOCKING COUNT MASK

TASK BLOCKING STATUS MASK
;

TS.BLK=177777

A-62

RSX-llM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINIT1UNb

TCBDF$ (Cont.)

SECOND STATUS WORD (STATE BITS)
i

T2.AST=lOOOOO
T2.DST=40000
T2.CHK=20000
T2.REX=10000
T2.SEF=4000
T2.SIO=lOOO
T2.AFF=400
T2.HLT=200
T2. ABO=l 00
T2.STP=40
T2.STP=20
T2.SPN=10
T2.SPN=4
T2.WFR=2
T2.WFR=1

iAST IN PROGRESS (l=YES)
iAST RECOGNITION DISABLED (l=YES)
iTASK NOT CHECKPOINTABLE (l=YES)
iREQUESTED EXIT AST SPECIFIED
iTASK STOPPED FOR EVENT FLAG(S} (l=YES)
iTASK STOPPED FOR BUFFERED I/O
iTASK IS INSTALLED WITH AFFINITY
iTASK IS BEING HALTED (l=YES)
iTASK MARKED FOR ABORT (l=YES)
iSAVED T2.SPN ON AST IN PROGRESS
iTASK STOPPED (l=YES)
iSAVED T2.SPN ON AST IN PROGRESS
iTASK SUSPENDED (l=YES)
iSAVED T2.WFR ON AST IN PROGRESS
iTASK IN WAITFOR STATE (l=YES)

THIRD STATUS WORD (ATTRIBUTE BITS)
i

T3. }\CP=l 00 000
T3.PMD=40000
T3. 'REM=2 0000
T3.PRV=10000
T3. ,MCR=4 000
T3.SLV=2000
T3.CLI=1000
T3.RST=400
T3.NSD=200
T3.CAL=100
T3.ROV=40
T3.NET=20
T3.MPC=10
T3.CMD=4
T3.SWS=2
T3.GFL=1

iANCILLARY CONTROL PROCESSOR (l=YES)
iDUMP TASK ON SYNCHRONOUS ABORT (O=YES)
iREMOVE TASK ON EXIT (l=YES)
iTASK IS PRIVILEGED (l=YES)
iTASK REQUESTED AS EXTERNAL MCR FUNCT(l=YES)
iTASK IS A SLAVE TASK (l=YES)
iTASK IS A COMMAND LINE INTERPRETER (l=YES)
iTASK IS RESTRICTED (l=YES)
iTASK DOES NOT ALLOW SEND DATA
iT~SK HAS CHECKPOINT SPACE IN TASK IMAGE
iTASK HAS RESIDENT OVERLAYS
iNETWORK PROTOCOL LEVEL
iMAPPING CHANGE WITH OUTSTANDING I/O (l=YES)
iTASK IS EXECUTING A CLI COMMAND
iRESERVED FOR SOFTWARE SERVICES USE
iGROUP GLOBAL EVENT FLAG LOCK

STATUS BIT DEFINITIONS FOR FOURTH STATUS WORD (T.ST4)
i

T4.MUT=40
T4.LDD=20
T4 .. PRO=lO
T4 .. PRV=4
T4 .. DSP=2
T4 .. SNC=1

iTASK IS A MULTI-USER TASK
iTASK'S LOAD DEVICE HAS BEEN DISMOUNTED
iTCB IS (OR SHOULD BE) A PROTOTYPE
iTASK WAS PRIV, BUT HAS CLEARED T3.PRV
iWITH GIN (MAY RESET WITH GIN IF T4.PRV SET)
iTASK WAS BUILT FOR USER I/O SPACE
iTASK USES COMMONS FOR SYNCHRONIZATION

REQUIRED RUN MASK
i

TR.UBT=lOOOOO
TR.UBS=40000

iUNIBUS RUN T
iUNIBUS RUN S

A-63

HSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

TCBDF$ (Cont.)
TR.UBR=20000
TR.UBP=lOOOO
TR.UBN=4000
TR.UBM=2000
TR.UBL=lOOO
TR. lJBK=400
TR.uBJ=200
TR.UBH=lOO
TR. 'JBF=4 0
TR. JBE=20
TR .1:PD=l 0
TR. (~PC=4
TR. (:PB=2
TR. (:PA=l

iUNIBUS RUN R
iUNIBUS RUN P
iUNIBUS RUN N
iUNIBUS RUN M
iUNIBUS RUN L
iUNIBUS RUN K
iUNIBUS RUN J
iUNIBUS RUN H
iUNIBUS RUN F
iUNIBUS RUN E
i PROCESSOR D
i PROCESSOR C
i PROCESSOR B
; PROCESSOR A

.ENDC
• PSECT

A-64

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

UCBDF$
UCBDF$

"TTDEF,SYSDEF

UNIT CONTROL BLOCK
THE UNIT CONTROL BLOCK (UCB) DEFINES THE STATUS OF AN INDIVIDUAL
DEVICE UNIT AND IS THE CONTROL BLOCK THAT IS POINTED TO BY THE
FIRST WORD OF AN ASSIGNED LUN.
THERE IS ONE UCB FOR EACH DEVICE
UNIT OF EACH DCB. THE UCB'S ASSOCIATED WITH A PARTICULAR DCB ARE
CONTIGUOUS IN MEMORY AND ARE POINTED TO BY THE DCB.
UCB'S ARE
VARIABLE LENGTH BETWEEN DCB'S BUT ARE OF THE SAME LENGTH FOR A
SPECIFIC DCB.
TO FINISH THE TELETYPE EXAMPLE ABOVE, EACH UNIT ON
BOTH INTERFACES WOULD HAVE A UCB •
• ASECT
.=177772
.IF NB

SYSDEF

.IF DF

A$$CNT

.=177770
U.UAB:
.BLKW

iPOINTER TO USER ACCOUNT BLOCK

iMULTI-USER PROTECTION WORD
iLOGIN UIC - MULTI USER SYSTEMS ONLY
iOWNING TERMINAL - MULTI USER SYSTEMS ONLY
iBACK POINTER TO DCB
iPOINTER TO REDIRECT UNIT UCB
iCONTROL PROCESSING FLAGS
iUNIT STATUS
iPHYSICAL UNIT NUMBER
iUNIT STATUS EXTENSION
iFIRST DEVICE CHARACTERISTICS WORD
iSECOND DEVICE CHARACTERISTICS WORD
iTHIRD DEVICE CHARACTERISTICS WORD
iFOURTH DEVICE CHARACTERISTICS WORD
iPOINTER TO SCB
iTCB ADDRESS OF ATTACHED TASK
iRELOCATION BIAS OF CURRENT I/O REQUEST
iBUFFER ADDRESS OF CURRENT I/O REQUEST
iBYTE COUNT OF CURRENT I/O REQUEST

.IFF
U.UAB:
• ENDC
.ENDC
177772
177774
177776
000000
000002
000004
000005
000006
000007
000010
000012
000014
000016
000020
000022
000024
000026
000030

U. CN~r:

000032
000034
000036
000034
000040
000042
000046
000050
000054

U.UCBX=U.CNT+2
U.ACP=U.CNT+4
U.VCB=U.CNT+6
U.CBP=U.CNT+4
U.UMB=U.CNT+I0
U. PRtJI=U • CNT+ 12
U. UTtJI O=U • CNT+ 16
U.LHD=U.CNT+20
U.BPKT=U.CNT+24

U.MUP:
U.LUIC:
U.OWN:
U.DCB:
U.RED:
U.CTL:
U.STS:
U.UNIT:
U.ST2:
U.CWl:
U. CW2:
U. CW3:
U. CW4:
U.SCI3:
U .AT'r:
U.BU1~:

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

1
1
1
1

1
1
1

1
1
1
1

1
1
1

iPOINTER TO UCB EXTENSION IN SECONDARY POOL
;ADDRESS OF TCB OF MOUNTED ACP
iADDRESS OF VOLUME CONTROL BLOCK
iCONTROL BUFFER RELOCATION AND ADDRESS
iADDRESS OF UMB FOR SHADOW RECORDING
iDISK SIZE PARAMETER WORDS
iUNIT COMMAND TIME OUT
iUNIT OUTSTANDING I/O PACKET LISTHEAD
iUNIT BAD BLOCK PACKET WAITING LIST

A-65

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

UCBDF$ (Cont.)
000060
000062
000064

U.UC2X=U.CNT+30
U. O'IRF=U. CNT+32
U.Clv'ST=U.CNT+34

iPOINTER TO 2ND EXTENSION IN SECONDARY POOL
iOUTSTANDING COMMAND STATUS REQUEST REGISTER
iCOMMAND STATUS PROGRESS REGISTER

Ml,GTAPE DEVICE DEPENDANT UCB OFFSETS
i

000040
000042
000044

U.SNUM=U.CNT+IO
U.FCDE=U.CNT+12
U.KPB1=U.CNT+14

iSLAVE UNIT NUMBER
iFUNCTION CODE
iSUBCONTROLLER KRB1 POINTER

DI;FINE SECONDARY POOL nCB EXTENSION OFFSETS
(ERROR LOGGING DEVICES ONLY)
i

.=0
000000
000022
000026
000032
000033
000034
000035
000036

X.NAME:
X. Ii)C:
X.EHHL:
X.EHSL:
X.E'~SC:

X. E!~HC:
X. W<:NT:

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

9.
2
2
1
1
1
1
2

iFIXED ACCOUNTING TRANSACTION HEADER
iDRIVE NAME IN RAD50
iI/O COUNT
iHARD ERROR LIMIT
i SOFT ERROR LIMIT
iSOFT ERROR COUNT
iHARD ERROR COUNT
iWORDS TRANSFERED COUN'r

DEFINE OFFSETS FOR SEEK OPTIMIZATION DEVICES
i

000042
000046
000050
000051
000051
000052
000054
000055

X.CYLC:
X.CCYL:
X.FCUR:
X.FLIM:
X.DSKD:
X.DNAM:
X.UNIT:

00005(1

X.LGTH=.

iLENGTH OF THE UCB EXTENSION

X.[FFL=10.
X. [IFSL=8.
X. IIFHL=5.

iDEFAULT FAIRNESS COUNT LIMIT
iDEFAULT SOFT ERROR LIMIT
iDEFAULT HARD ERROR LIMIT

• BLKW
• BLKW
.BLKB

2
1
1

.BLKB
.BLKW
.BLKB
.BLKB

1
1
1
1

iCYLINDERS CROSSED COUNT
;CURRENT CYLINDER
iCURRENT FAIRNESS COUNT
iFAIRNESS COUNT LIMIT
iDISK DIRECTION (HIGH BIT 1=OUT)
iDEVICE NAME FOR ACCOUNTING
iUNIT NUMBER FOR ACCOUNTING
iUNUSED FOR NOW

IIEFINE OFFSETS FOR DISK MSCP CONTROLLERS (SECOND UCB EXTENSION)

CHARACTERISTICS OBTAINED FROM "GET UNIT STATUS" END PACKETS
i
.=()

000000
000002
000004
000010
000020
000024

X. r1LUN: • BLKW
X. IJN F L : • BL KW
X. HSTI: • BLKW
X.11NTI: .BLKW
X. I1EDI: • BLKW
X. ';HUN: • BLKW

1
2
4
2

iMULTI-UNIT CODE
iUNIT FLAGS
iHOST IDENTIFIER
iUNIT IDENTIFIER
iMEDIA IDENTIFIER
iSHADOW UNIT
A-66

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

UCBDF$ (Cont.)
000026
000030
000032
000034
000040
000042
000043

X.SHST:
X.TRCK:
X.GRP:
X.CYL:
X.RCTS:
X.RBNS:
X.RCTC:

.BLKW
.BLKW
.BLKW
.BLKW
.BLKW
.BLKB
.BLKB

1
1
1
2
1
1
1

iSHADOW UNIT STATUS
iUNIT TRACK SIZE
iUNIT GROUP SIZE
iUNIT CYLINDER SIZE
iUNIT RCT TABLE SIZE
iUNIT RBN 's / TRACK
iUNIT RCT COPIES

CHARACTERISTICS OBTAINED FROM "ONLINE" OR "SET UNIT
CHARACTERISTICS" END PACKETS
i

000044
000050

X. UNSZ: • BLKW
X. VSER: • BLKW

000054

X.DUSZ=.

2
2

iUN1T SIZE
iVOLUME SERIAL NUMBER
iSIZE OF DISK MSCP CONTROLLER UCB EXTENTION

.IF NB

TTDEF

TERMINAL DRIVER DEFINITIONS
i

000024
000026
000034

.=U .. BUF
U. TUX:
• BLKW
U.TSTA: .BLKW
U. T~rAB: • BLKW

1
3
1

. =. --2
000034

U. TECO: • BLKB

000035
000036
000040
000041
000042
000044
000045
000046
000047
000050
000052
000054

U.TBSZ:
U.UJ:C:
U.TLPP:
U. TIi'RQ:
U.TFLK:
U. TCHP:
U. TCVP:
U. T~~YP:
U. T~\TI:
U.ACB:
U.AFLG:
U.ADMA:

.BLKB
.BLKW
.BLKB
.BLKB
.BLKW
.BLKB
.BLKB
.BLKB
.BLKB
.BLKW
.BLKW
.BLKW

1
1
1
1
1
1

iPOINTER TO UCB EXTENSION (UCBX)
iSTATUS TRIPLE-WORD
iIF 0: U.TTAB+1 IS SINGLE-CHARACTER TYPEi
AHEAD BUFFER, CURRENTLY EMPTY
iIF ODD: U.TTAB+1 IS SINGLE-CHARACTER TYPEAHEAD BUFFER AND HOLDS A CHARACTER
iIF NON-O AND EVEN: POINTER TO MULTIi
CHARACTER TYPE-AHEAD BUFFER
iTHE NEXT TWO OFFSETS OVERLAP U.TTAB WHEN
iTHE TYPEAHEAD BUFFER IS IN SECONDARY POOL
iECHO BUFFER FOR DMA OPERATIONS WHEN UCBX IS
iIN SECONDARY POOL AND THUS NOT MAPPED BY A
iUMR
iTYPEAHEAD BUFFER SIZE
iDEFAULT UIC
iLINES PER PAGE
iFORK REQUEST BYTE
iFORK LIST LINK WORD
iCURRENT HORIZONTAL POSITION
iCURRENT VERTICAL POSITION
iTERMINAL TYPE
iMODEM TIMER
iANCILLARY CONTROL DRIVER BLOCK ADDR
iANCILLARY CONTROL DRIVER FLAGS WORD
iANCILLARY CONTROL DRIVER DMA BUFFER

DEFINE BITS IN STATUS WORD 1 (U.TSTA)
i

S1.RST=1
S1.RUB=2
S1.ESC=4

iREAD WITH SPECIAL TERMINATORS IN PROGRESS
iRUBOUT SEQUENCE IN PROGRESS (NON-SCOPE)
iESCAPE SEQUENCE IN PROGRESS

A-67

RSX-llM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

UCBDF$ (Cont.)
Sl.RAL=lO
Sl.RNE=20
Sl.CTO=40
Sl.0BY=100
Sl.IBY=200
Sl.BEL=400
Sl.DPR=1000
Sl.DEC=2000
Sl.DSI=4000
Sl.CTS=10000
Sl.USI=20000
Sl.0BF=40000
Sl.IBF=100000

iREAD ALL IN PROGRESS
iECHO SUPPRESSED
iOUTPUT STOPPED BY CTRL-O
iOUTPUT BUSY
i INPUT BUSY
iBELL PENDING
iDEFER PROCESSING OF CHAR. IN U.TECB
iDEFER ECHO OF CHAR. IN U.TECB
iINPUT PROCESSING DISABLED
iOUTPUT STOPPED BY CTRL-S
iUNSOLICITED INPUT IN PROGRESS
iBUFFERED OUTPUT IN PROGRESS
iBUFFERED INPUT IN PROGRESS

DEFINE BITS IN STATUS WORD 2 (U.TSTA+2)
i

S2. ACR=l
S2.WRA=6
S2.WRB=2
S2.CR=10
S2.BRQ=20
S2.SRQ=40
S2.0RQ=100
S2.IRQ=200
S2.HFL=3400
S2.VFL=4000
S2.HHT=10000
S2.HFF=20000
S2.FLF=40000
S2.FDX=100000

iWRAP-AROUND (AUTOMATIC CR-LF) REQUIRED
iCONTEXT FOR WRAP-AROUND
iLOW BIT IN S2.WRA BIT PATTERN
iTRAILING CR REQUIRED ON OUTPUT
iBREAK-THROUGH-WRITE REQUEST IN QUEUE
iSPECIAL REQUEST IN QUEUE
i(IO.ATT, IO.DET, SF.SMC)
iOUTPUT REQUEST IN QUEUE (MUST = Sl.0BY)
iINPUT REQUEST IN QUEUE (MUST = Sl.IBY)
iHORIZONTAL FILL REQUIREMENT
iVERTICAL FILL REQUIREMENT
iHARDWARE HORIZONTAL TAB PRESENT
iHARDWARE FORM-FEED PRESENT
iFORCE LINE FEED BEFORE NEXT ECHO
iLINE IS IN FULL DUPLEX MODE

DEFINE BITS IN STATUS WORD 3 (U.TSTA+4)
i

S3. RAL=l 0
S3.RPO=20
S3.WES=40
S3.TAB=100
S3.8BC=200
S3.RCU=400
S3.ABD=1000
S3.ABP=2000
S3.WAL=4000
S3.VER=10000
S3.BCC=20000
S3.DAO=40000

S3.PCU=100000

iTERMINAL IS IN READ-PASS-ALL MODE
i (S3.RAL MUST = Sl.RAL)
iREAD W/PROMPT OUTPUT IN PROGRESS
iTASK WANTS ESCAPE SEQUENCES
iTYPE-AHEAD BUFFER ALLOCATION REQUESTED
iPASS 8 BITS ON INPUT
iRESTORE CURSOR (MUST = TF.RCU*400)
iAUTO-BAUD SPEED DETECTION ENABLED
iAUTO-BAUD SPEED DETECTION IN PROGRESS
iWRITE-PASS-ALL (MUST = TF.WAL*400)
iLAST CHAR. IN TYPE-AHEAD BUFFER
iHAS PARITY ERROR
iLAST CHAR. IN TYPE-AHEAD BUFFER
iHAS FRAMING ERROR
iLAST CHAR. IN TYPE-AHEAD BUFFER
iHAS DATA OVERRUN ERROR
iNOTE - THE 3 BITS ABOVE MUST CORRESPOND
iTO THE RESPECTIVE ERROR FLAGS IN THE
;HARDWARE RECEIVE BUFFER
iPOSITION CURSOR BEFORE WRITE

• ENDC

A-68

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

UCBDF$ (Cont.)
VIRTUAL TERMINAL UCB DEFINITIONS
i

000006

.=U.UNIT
u.oeNT: .BLKB

iOFFSPRING WITH THIS AS TI:

000024
000026
000030
000032
000034

.=U.BUF
U.RPKT:
U.WPKT:
U • I~.ST:
U. O~.ST:
U• Al\ST:

.BLKW
.BLKW
.BLKW
.BLKW
.BLKW

1
1
1
1
1

iCURRENT OFFSPRING READ I/O PACKET
iCURRENT OFFSPRING WRITE I/O PACKET
iINPUT AST ROUTINE ADDRESS
iOUTPUT AST ROUTINE ADDRESS
iATTACH AST ROUTINE ADDRESS

.IF NB

TTDEF

.IIF NE U.AAST+2-U.UIC

• ERROR

;ADJACENCY ASSUMED

• ENDC
000040

.=U.AAST+4
U.P'I'CB: .BLKl.v

;PARENT TCB ADDRESS

CONSOLE DRIVER DEFINITIONS
i

000026
000030
000034

.=U.BUF+2
U. CT'CB: • BLKW
U.COTQ: .BLKW
U.RED2: .BLKW

1
2
1

;ADDRESS OF CONSOLE LOGGER TCB
iI/O PACKET LIST QUEUE
iREDIRECT UCB ADDRESS

.PSECT

DEVICE TABLE STATUS DEFINITIONS
DEVICE CHARACTERISTICS WORD 1 (U.CW1) DEVICE TYPE DEFINITION BITS.
i

DV.REC=l
DV.CCL=2
DV.TTY=4
DV.DIR=10
DV.SDI=20
DV.SQD=40
DV.MSD=lOO
DV~UMD=200

DV.MBC=400
DV.EXT=400
DV.SWL=lOOO
DV.ISP=2000
DV.OSP=4000
DV.PSE=lOOOO
DV.COM=20000
DV.F11=40000
DV.MNT=lOOOOO

iRECORD ORIENTED DEVICE (l=YES)
iCARRIAGE CONTROL DEVICE (l=YES)
iTERMINAL DEVICE (l=YES)
iFILE STRUCTURED DEVICE (l=YES)
iSINGLE DIRECTORY DEVICE (l=YES)
iSEQUENTIAL DEVICE (l=YES)
iMASS STORAGE DEVICE (l=YES)
iUSER MODE DIAGNOSTICS SUPPORTED (l=YES)
iMASSBUS CONTROLLER (11M COMPATIBILITY ONLY)
iUNIT ON EXTENDED 22-BIT UNIBUS CNTROLER
i(l=YES)
iUNIT SOFTWARE WRITE LOCKED (l=YES)
iINPUT SPOOLED DEVICE (l=YES)
iOUTPUT SPOOLED DEVICE (l=YES)
;PSEUDO DEVICE (l=YES)
iDEVICE IS MOUNTABLE AS COM CHANNEL (l=YES)
iDEVICE IS MOUNTABLE AS Fll DEVICE (l=YES)
iDEVICE IS MOUNTABLE (l=YES)

A-69

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

UCBDF$ (Cont.)

TERMINAL DEPENDENT CHARACTERISTICS WORD 2 (U.CW2) BIT DEFINITIONS
i

U2.DH1=100000
U2.DJ1=40000
U2.RMT=20000
U2.HFF=10000
U2.L8S=10000
U2.NEC=4000
U2.CRT=2000
U2.ESC=1000
U2.LOG=400
U2.SLV=200
U2.DZ1=100
U2.HLD=40
U2.AT.=20
U2.PRV=10
U2.L3S=4
U2.VTS=2
U2.LWC=1

iUNIT IS A MULTIPLEXER (l=YES)
iUNIT IS A DJ11 (l=YES)
iUNIT IS REMOTE (l=YES)
iUNIT HANDLES HARDWARE FORM FEEDS (l=YES)
iOLD NAME FOR U2.HFF
iDON'T ECHO SOLICITED INPUT (l=YES)
iUNIT IS A CRT (l=YES)
iUNIT GENERATES ESCAPE SEQUENCES (l=YES)
iUSER LOGGED ON TERMINAL (O=YES)
iUNIT IS A SLAVE TERMINAL (l=YES)
iUNIT IS A DZ11 (l=YES)
iTERMINAL IS IN HOLD SCREEN MODE (l=YES)
iMCR COMMAND AT. BEING PROCESSED (l=YES)
iUNIT IS A PRIVILEGED TERMINAL (l=YES)
iUNIT IS A LA30S TERMINAL (l=YES)
iUNIT IS A VTOSB TERMINAL (l=YES)
iLOWER CASE TO UPPER CASE CONVERSION (O=YES)

BIT DEFINITIONS FOR U.MUP
UM.OVR=l
UM.CLI=36
UM.DSB=200
UM.NBR=400
UM.CNT=lOOO
UM. CMD=2 00 0
UM.SER=4000
UM.KIL=lOOOO

iOVERRIDE CLI INDICATOR
iCLI INDICATOR BITS
iTERMINAL DISABLED SINCE CLI ELIMINATED
iNO BROADCAST
iCONTINUATION LINE IN PROGRESS
iCOMMAND IN PROGRESS
iSERIAL COMMAND RECOGNITION ENABLED
iTTDRV SHOULD SEND KILL PKT ON CNTRL/C

TERMINAL SECONDARY POOL OFFSETS FOR THE UCB EXTENSION AND TYPEAHEAD BUFFER
i

U.TAPR=24
U.TTBF=46

iOFFSET WITHIN UCB WHICH POINTS TO UCB EXT
iOFFSET WITHIN UCB EXTENSION WHICH POINTS TO
;TYPEAHEAD BUFFER

RH11-RS03/RS04 CHARACTERISTICS WORD 2 (U.CW2) BIT DEFINITIONS
i

U2.R04=100000

iUNIT IS A RS04 (l=YES)

RH11-TU16 CHARACTERISTICS WORD 2 (U.CW2) BIT DEFINITIONS
i

U2.7CH=10000

iUNIT IS A 7 CHANNEL DRIVE (l=YES)

TERMINAL DEPENDENT CHARACTERISTICS WORD 3 (U.CW3) BIT DEFINITIONS
i

U3.UPC=20000

iUPCASE OUTPUT FLAG

A-70

RSX-IIM.-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

UCBDF$ (Cont.)

VIRTUAL TERMINAL 3RD CHARACTERISTICS WORD DEFINITIONS
i

U3.FDX=1
U3.DBF=2
U3.RPR=4

iFULL DUPLEX MODE (I=YES)
iINTERMEDIATE BUFFERING DISABLED (I=YES)
iREAD W/PROMPT IN PROGRESS (I=YES)

TERMINAL DEPENDENT CHARACTERISTICS WORD 4 (U.CW4) BIT DEFINITIONS
i

U4.CR=100

iLOOK FOR CARRIAGE RETURN

UNIT CONTROL PROCESSING FLAG DEFINITIONS
i

UC.ALG=200
UC.NPR=100
UC.QUE=40
UC.PWF=20
UC.ATT=10
UC.KIL=4
UC.LGH=3

iBYTE ALIGNMENT ALLOWED (I=NO)
iDEVICE IS AN NPR DEVICE (I=YES)
iCALL DRIVER BEFORE QUEUING (I=YES)
iCALL DRIVER AT POWERFAIL ALWAYS (I=YES)
iCALL DRIVER ON ATTACH/DETACH (I=YES)
iCALL DRIVER AT I/O KILL ALWAYS (I=YES)
iTRANSFER LENGTH MASK BITS

UNIT STATUS BIT DEFINTIONS
i

US.BSY=200
US.MNT=100
US.FOR=40
US.MDM=20

iUNIT
iUNIT
iUNIT
iUNIT

IS
IS
IS
IS

BUSY (I=YES)
MOUNTED (O=YES)
MOUNTED AS FOREIGN VOLUME (I=YES)
MARKED FOR DISMOUNT (I=YES)

CARD READER DEPENDENT UNIT STATUS BIT DEFINITIONS
i

US.ABO=I
US.MDE=2

iUNIT IS MARKED FOR ABORT IF NOT READY
i (I=YES)
iUNIT IS IN 029 TRANSLATION NODE (I=YES)

FILES-II DEPENDENT UNIT STATUS BITS
i

US.WCK=IO
US.SPU=2
US.VV=1

iWRITE CHECK ENABLED (I=YES)
iUNIT IS SPINNING UP (I=YES)
iVOLUME VALID IS SET (I=YES)

TERMINAL DEPENDENT UNIT STATUS BIT DEFINITIONS
i

US. C1RW=4
US.DSB=2
US.OIU=1

iUNIT IS WAITING FOR CARRIER (I=YES)
iUNIT IS DISABLED (I=YES)
iOUTPUT INTERRUPT IS UNEXPECTED ON UNIT
i(I=YES)

A-71

RSX-IIM-PLUS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

UCBDF$ (Cont.)

LPSII DEPENDENT UNIT STATUS BIT DEFINITIONS
;

US.FRK=2
US.SHR=l

iFORK IN PROGRESS (l=YES)
iSHAREABLE FUNCTION IN PROGRESS (O=YES)

ANSI MAGTAPE DEPENDANT UNIT STATUS BITS
;

US.LAB=4

iUNIT HAS LABELED TAPE ON IT (l=YES)

UNIT STATUS EXTENSION (U.ST2) BIT DEFINITIONS
US.OFL=l
US.RED=2
US.PUB=4
US. UMD=l 0
US.PDF=20

iUN1T OFFLINE (l=YES)
iUNIT REDIRECTABLE (O=YES)
iUNIT IS PUBLIC DEVICE (l=YES)
iUNIT ATTACHED FOR DIAGNOSTICS (l=YES)
iPRIVILEGED DIAGNOSTIC FUNCTIONS ONLY(l=YES)

MAGTAPE DENSITY SUPPORT DEFINITION IN U.CW3
i

UD.UNS=O
UD.200=1
UD.556=2
UD.BOO=3
UD.160=4
UD.625=5

iUNSUPPORTED
200BPI, 7 TRACK
; 556BPI, 7 TRACK
; BOOBPI, 7 OR 9 TRACK
i1600BPI, 9 TRACK
i6250BPI, 9 TRACK
i

A-72

APPENDIX B
CONVERTING A USER-SUPPLIED RSX-llM DRIVER

This appendix describes the modifications that you must make to enable
an RSX-IIM user-supplied driver to run on an RSX-llM-PLUS system. The
modifications involve both the driver data base and the driver code.

B.l

ASSUMPTIONS AND GENERAL APPROACH

The discussion in this appendix assumes that the RSX-llM user-supplied
driver runs on a mapped system.
Also, samples of code from the
RLOl/RL02 driver (DLDRV) are used as examples in this appendix.
As a general approach to converting a driver, proceed in the following
manner:
1.

Read the RSX-llM-PLUS Guide to Writing an I/O Driver to gain
a
feeling
for
the
differences ~etween RSX-llM and
RSX-llM-PLUS drivers. Note especially the differences in the
data structures (RSX-llM-PLUS has two additional structures).

Make the changes described in this appendix.

Incorporate the driver according to the guidelines
Chapter 5.

given

For the purposes of this discussion, a standard disk driver is one
that does not attempt to use any of the advanced driver features that
are described in Chapter 1.

B.2

MODIFYING THE DATA BASE CODE

Before creating the driver data base, read the overview of programming
user-written driver data bases (Section 4.2). It gives important
information on ordering and labeling in the code.

B-1

CONVERTING A USER-SUPPLIED RSX-IIM DRIVER
B.2.l

Unit Control Block Changes

Ensure that the Unit Control Block (UCB) has the data needed for disk
geometry calculations.
Refer to the description of U.PRM in Section
4.4.4.
The following is an example of the code needed to store the
disk gE~ometry:
.BYTE
.WORD

40. ,2
512.

iU.PRM
iU.PRM+2

Notes:

8.2.2

40.

indicates the number of sectors per track.

2 indicates the number of tracks per cylinder.

512.

The values in the code are device dependent.

indicates the number of cylinders per volume.

Status Control Block Changes

RSX-llM-PLUS requires a structure called the Controller Request Block
(KRB) •
You can add the KRB data that RSX-llM-PLUS requires to the
Status Control Block (SCB) data to effectively create one continuous
structure.
This arrangement is called the contiguous KRB/SCB and is
described in Sections 4.2.4 and 4.4.7.
Because the ordering of the
SCB data differs from RSX-IIM to RSX-I1M-PLUS, you must rearrange the
RSX-1IM SCB data to accommodate the RSX-I1M-PLUS requirements.
If
your driver refers to the SCB structures by symbolic offset and does
not rely on physical ordering; you do not need to change the driver
code that accesses the SCB. Refer to Sections 4.4.5 and 4.4.6 for a
description of the offsets required.
There must be one KRB/SCB combination for each controller
the system.

present

An example of code that includes the proper offsets appears in
B-1.

B-2

Figure

CONVERTING A USER-SUPPLIED RSX-llM DRIVER
.BYTE
.BYTE
.WORO

PRS,l60/4
0*2,0
KS.OFL

.WORD
.WORD
.BYTE
.WORD

174400
DLA-$DLA
0,0
.DLO

.WORD
.WORD
.WORD
.WORD
• BYTE
.BYTE
.WORD
.WORD
.BYTE
.WORD
.BLKW
.WORD

0,.-2
0,0,0,0

$OLA: :

$OLO: :

a
a

0,4 •
0,0
S2.CON!S2.LOG
$DLA
S. ,0

a
6
a

;K.PRI,K.VCT
;K.CON,K.IOC
;K.STS
;START OF KRB
;K.CSR
;K.OFF
;K.HPU
;K.OWN
;START OF CONTIGUOUS SCB
;S.LHD/K.CRQ
;S.FRK
;S.KSS
;S.PKT
;S.CTM,S.ITM
;S.STS,S.ST3
;S.ST2
;S.KRB
;S.RCNT,S.ROFF
;S.EMB
;MAPPING ASSIGNMENT BLOCK
;KE.RHB

OLA:
Figure B-1

Contiguous KRB/SCB for DLDRV

Notes:
l~

K.VCT and K.CSR can be changed dynamically by reconfiguration
commands when you bring the device on-line. Refer to the
RSX-llM/M-PLUS System Management Guide,
Chapter IS
for
lnformation on the Reconfiguration task and commands.

Label DLA is used solely for calculating K.OFF (DLA-$DLA).

B.2.3

The Controller Table

RSX-llM-PLUS requires a structure called a Controller Table
(CTB).
Add the code to define the CTB according to the rules described in
Sections 4.2.S and 4.4.8.
An example of the code needed to define the
CTB appears in Figure B-2 •
• WORD

.WORD
.ASCII
.WORD
.BYTE

/OL/
$DLDCB
1,0

iL.ICB
;START OF CTB
; L. LNK
;L.NAM
; L. DCB
;L.NUM,L.STS

.WORD

$DLA

;L.KRB

Figure B-2

Controller Table (CTB)

DLCTB:

$DLCTB: :

for DLDRV

Notes:
1.

The symbol $DLDCB is a pointer to the
(DCB) •

L.KRB points to the start of the KRB.

Control

Block

This example assumes that you have a loadable data base.
If the
base is resident, you must include the CTB macro before L.LNK.

data

B-3

Device

CONVERTING A USER-SUPPLIED RSX-llM DRIVER
B.3

MODIFYING THE DRIVER CODE

Several changes must be made to
overview of the RSX-IIM-PLUS
4. 3.

B.3.1

the RSX-IIM driver code.
For an
coding requirements, refer to Section

Conditional Symbols

You can remove most dependence on system conditional definitions from
the c~de.
RSX-IIM-PLUS always defines the symbols D$$IAG, M$$MGE,
MS$EXT, M$$MUP, and E$$DVC.

B.3.2

Controller-Dependent Code

At the I/O initiation entry point in RSX-IIM drivers,
you will
find
code f,)r defining a table of UCB addresses and loading the UCB address
of the currently active unit in the table.
Remove this code and
replac~
it with the GTPKT$ macro call.
For guidelines on doing this,
refer :0 Sections 4.3.2 and 4.5.2.
FollowLng is an example of the

RSX-IlM

driver

code

that

you

must

remove~

1$:

CALL
BCC
RETURN
MOV

$GTPKT
1$
R5, CNTBL (R3)

iGET AN I/O PACKET TO PROCESS
iIF CC PROCESS REQUEST
iRETURN IF BUSY OR NO REQUEST
iSAVE ADDRESS OF REQUEST UCB

Insert the RSX-IIM-PLUS GTPKT$ macro call, a sample of which follows:
GTPKT$

B.3.3

DL,R$$LIl

iGET NEXT I/O PACKET TO PROCESS

Driver Dispatch Table

ReplacE' the code that defines the entry point addresses with the DDT$
macro call.
Refer to Section 4.3.1 for a description of the call and
its parameters.
Refer to Section 4.5.1 for
a description of the
Driver Dispatch Table (DDT) and the format of the labels that it uses
for thE entry points.
Following is an example of the
replace:

RSX-IIM

$DLTBL: : • WORD
.WORD
.WORD
.WORD

iDEVICE INITIATOR ENTRY POINT
iCANCEL I/O OPERATION ENTRY POINT
iDEVICE TIMEOUT ENTRY POINT
iPOWERFAIL ENTRY POINT

DLINI
DLCAN
DLOUT
DLPWF

driver

code

that

you

must

Insert the RSX-IIM-PLUS DDT$ macro call, an example of which follows:
DDT$

DL,R$$Lll

;GENERATE DISPATCH TABLE

You do not have to add code to the driver to handle controller and
unit status changes.
The sample form of the macro call shown
generates code to use the xxPWF entry point for controller and unit
on-line and off-line status changes.

B-4

CONVERTING A USER-SUPPLIED RSX-llM DRIVER
B.3.4

Reconfiguration Support

If you incorporate the device in the Reconfiguration task
(HRC ••• )
tables and the device calls the Executive volume valid routine, you
must incorporate a local register pass routine in your driver,
an
example of which appears in Figure B-3.
i+

MOVE THE CONTROLLER/DRIVE REGISTERS INTO THE
SPECIFIED BUFFER.
INPu~rs :

R2
R3

CSR ADDRESS
BUFFER ADDRESS

OUTPUTS:
R3 - ALTERED
i-

REG PAS:: MOV
MOV
MOV
MOV
CALL
MOV
RETURN

(R2),(R3)+
R LB A (R 2) , (R 3) +

RLDA(R2) ,(R3)+
RLM P (R 2) , (R 3 ) +
DLGST
RLMP (R2) , (R3)

Figure B-3

iMOVE RLCS
iMOVE RLBA
iMOVE RLDA
iMOVE RLMP
iEXECUTE GET DRIVE STATUS FUNCTION
iSAVE DRIVE STATUS

(REGPAS)

Notes:
1.

B.3.5

The index values RLxxx and the subroutine
specific.

DLGST

are

device

Volume Valid Processing

If the device is a disk and has a volume valid function,
the
RSX-llM-PLUS Executive must be able to handle the correct function
codes. Refer to the description of volume valid processing in Section
4.5.9.
For volume valid support, you may also need to include the
code that appears in Figure B-4.
CALL
BCS
TST
BMI
TST
BPL
MOV
CALL
MOV
CALL
BR

$VOLVD
IODON

RO
1$
I. PRM+2 (Rl)
IODON
S.CSR(R4) ,R2
DLRST
S.PKT(R4) ,R3
REG PAS
IODON

1$:

Figure B-4

iVALIDATE VOLUME VALID
iIF CS WE FAILED
iTRANSFER FUNCTION?
iIF MI YES
iSIZE THE DISK
iIF PL NO
iRETRIEVE CSR ADDRESS
iRESET DRIVE AND GET STATUS
;RETRIEVE I/O PACKET ADDRESS
iPASS REGISTERS TO HRC
;FINISH I/O REQUEST
;REFERENCE LABEL

Typical Handling of Volume Valid

Notes:
1.

The subroutine DLRST is device specific.

B-5

CONVERTING A USER-SUPPLIED RSX-IIM DRIVER
B.3.6

Converting Logical Block Numbers

The $CVLBN routine converts a Logical Block Number (LBN) to a physical
disk
3ddress.
You can replace special-purpose code in the RSX-IIM
driver with a call to this Executive routine, a description of which
is in Section 7.4.6.
A sample of the code that you should remove
appear3 in Figure B-5.
MOV
CALL
• REPT
ASL
.ENDR
BIS

#40.,RI
$DIV
6•
RO

iDIVIDE BY SECTORS/SURFACE
iCALCULATE CYLINDER NUMBER

RI,RO

;MERGE SECTOR WITH CYLINDER AND SURFACE

Figure B-5

iPOSITION CYLINDER AND SURFACE

RSX-IIM Logical Block Number Conversion

Figure B-6 includes the call to $CVLBN.
CALL
ROR
ROL
ASH
BIS

$CVLBN
RI
R2
#6,R2
R2,RO

Figure B-6

B.3.7

iCONVERT BLOCK NUMBER TO DISK ADDRESS
iPUT SURFACE BIT IN CARRY
iMERGE IT WITH THE CYLINDER NUMBER
;POSITION CYLINDER AND SURFACE
iMERGE SECTOR WITH CYLINDER AND SURFACE

RSX-IIM-PLUS Logical Block Number Conversion

Interrupt Entry Processing

Ensure that the INTSV$ macro call appears as the first line of code at
each interrupt entry point in the driver. Refer to Section 4.3.3 for
a description of the INTSV$ macro call and to Section 4.5.8 for a
discussion of processing at an interrupt entry point.
Following, is a
sample INTSV$ macro call:
INTSV$

DL,PR5,R$$LII

ii;SAVE REGISTERS AND SET PRIORITY

B-6

INDEX

ABODF$, A-3
Acceptance routine, 1-13
Acce-ss path,
switching between, 1-11
Accounting block offsets, A-4
Accumulation fields,
See ACNDF$
$ACHCK routine, 7-7
$ACHKB routine, 7-7
ACNDF$, A-4 to A-9
ACP function mask, 4-19 to
4-20
ACTDF$, A-I0
Active Page Register,
S€!e APR, 1-2
Address doubleword, 7-1 to 7-2
Advance driver feature, 1-7,
1-10 to 1-16, 2-4
$ALOCB routine, 7-8
APR,- 1-2 to 1-3
AST ,- 1-14
$ASUMR routine, 7-9
calling from driver, 7-4
Asynchronous System Trap,
SE!e AST

$BLKCl routine, 7-10
$BLKC2 routine, 1-16, 7-10
$BLKCK routine, 1-15, 7-10
$BLXIO routine, 7-11
Breakpoint,
setting in a driver, 6-5
Buffer,
special user,
sample of driver handling,
8-12 to 8-25, A-26
Buffered I/O, 1-14
Bus switch, 1-16

Cancel I/O,
entry point, 4-64 to 4-65
overview, 2-5
$CFORK, 1-17
CINT$ directive, 1-1
$CKBFB routine, 7-12
$CKBFI routine, 7-12
$CKBFR routine, 7-12
$CKBFW routine, 7-12
$CLINS routine, 7-13
CLKDF$, A-II
Clock queue control block,
offset definitions, A-II
Index-1

Common interrupt dispatching,
1-12
SON task, 1-18, 5-2, 5-7 to
5-9
overview, 1-18
Concurrent I/O, 1-13
Conditional assembly
directive, 4-2
Conditional fork, 1-17 to 1-18
necessity, 1-17
Co n fig u rat ion,
peripheral,
choosing, 5-10 to 5-11
Connectivity mask, 1-17
Contiguous KRB and SCB, 2-2,
4-53
Control and Status Register,
See CSR
Control function mask, 4-19 to
4-20
Controller, 1-4
2-level controllers, 1-13
access, 1-10 to 1-11
del aye d , 1-11
dual support, 1-11
access list, 2-2
allowing parallel
operations, 2-2
assignment, 1-11
busy/not busy, 1-11 to 1-12
configuration status for,
2-2
defining type, 2-1
group number, 1-7
I/O count, 1-12 to 1-13
interrupt vector, 1-7
interrupts, 1-11
location of a CSR for a, 2-2
maintaining hardwarespecific information
for, 2-2
making accessible, 5-6
name, 2-1
number, 1-5
placing on line, 5-7
reassignment and load
sharing, 1-11
status, 1-11
subcontroller device, 1-13
block, 1-13
supporting more than one
device, 1-12
Controller reassignment, 1-11
Controller Request Block,
See KRB

INDEX

Cortroller request queue,
1-11, 2-2
Co~trol1er status change,
entry point, 4-66 to 4-68
overview, 2-6
Controller status extension 2,
4-42
Controller status extension 3,
4-41
Controller status word, 4-48
Controller table,
See CTB
Controller table status byte,
4-58
Conversion routine, 1-15
Crash dump analysis,
See CDA
CSR, 1-1
a~cessing of, 1-1
ajdress space, 1-1
assignment error, 5-8
assignments,
setting, 5-6
CTB,
cJmposite arrangement, 3-15
d~finition, 1-4
d,=tails, 4-53, 4-55 to 4-59
f,)rmat, 4-55 to 4-59
13yout, 4-55
01 e r vie w, 2-1
r?quirement, B-3
s{stem list, 2-1
U3e in handling interrupts,
2-1
v31idation during LOAD, 5-12
/CTi3,

U!3e in LOAD, 5-14, 6-15
CTBDF$, A-12
$CT~ST symbol, 2-1, 3-15
$CVLBN routine, 7-14
Cy1 Lnder number, 1-15
Cy1 Lnder Scan,
d (: fin i t ion, 1-1 5

D.x):x offsets,
irl DCB, 4-16 to 4-18
Dati'! base, 1-18
a !;sembl i ng ,
during system generation,
5-3
c(,de,
bit symbols, 4-30 to 4-31
ccnverting RSX-I1M to
RSX-IIM-PLUS,
defining CTB, B-3
disk geometry
calculations, B-2

Index-2

Data base (Cont.)
modifying the data base,
B-1
creating source code, 4-2
defining link word for, 4-3
details of structures,
4-31 to 4-37, 4-39,
4-49 to 4-53
driver,
sample code, 8-1 to 8-3
structures,
overview af, 2-1, 2-3
global label, 4-2
$USRTB, 4-3
$xxDCB, 4-3
labeling of data structures,
4-2
loadable, 1-19, 4-3
incorporating, 5-1
modifying RSX-I1M to
RSX-11M-PLUS, B-1
SCB requirements, 8-2
mod ul e,
inserting into library,
5-4
overview of structures,
2-2 to 2-3
owning CTB, 2-1
programming,
requirements, 4-2 to 4-3
resident, 1-19, 4-3
incorporating, 5-1
1 ink to CTB, 4-3
structures,
augmented, 1-13
composite arrangement, 2-11
conventional, 1-13
ordering of, 4-2
typical arrangements,
2-6 to 2-8
validation during LOAD, 5-12
Data structure, 1-13
definitions, A-I to A-71,
B-72
Data transfer, 1-14
DCB,
ASCII device name, 4-17
composite arrangement, 2-11
creating mask words in, 4-21
definition, 1-4
details, 4-16 to 4-18
driver dispatch table
pointer, 4-18
driver-specific function
masks, 4-18 to 4-26
establishing characteristics
for, 2-7
establishing I/O function
masks, 4-22

INDEX (CONT.)

DCB (Cont.)
fields, 4-16 to 4-18
format, 4-16 to 4-18
label ing, 4-3
length of UCB, 4-18
link to next DCB, 4-16
list of, 2-3
means to access Driver
Dispatch Table, 2-2
number of units stored, 4-3
overview, 2-2 to 2-3
pointer to first UCB, 4-17
unit number range, 4-18
validation during LOAD, 5-13
DCBDF$, A-13
DDT$ macro call,
arguments, 4-5 to 4-6
use of, 4-4
$DEACB routine, 7-15
Deallocation entry point,
4-66
Delayed Controller access,
1-11
$DEUMR routine, 7-16
calling from driver, 7-4
$DEVHD routine, 2-3, 2-11
Device,
address, 1-1
assigned controller, 1-18
busy/not busy, 1-13
configured on-line, 1-13
dual-access capability, 1-17
generic name, 2-3
interrupt, 1-5
making accessible, 5-6
registers, 1-1 to 1-2, 4-50
storage of static
characteristics, 2-3
subcontroller, 1-13
Device Control Block,
See DCB
Device driver,
See Driver
Device interrupt address,
overview, 2-6
Device interrupt vector, 2-4
Device timeout,
entry point, 4-65
overview, 2-5
Directive Parameter Block,
See DPB
Disk,
geometry calculations, B-2
Distributed I/O, 1-16
Do ubI ewo rd,
address, 7-1 to 7-2
DPB, 4-11
details, 4-14 to 4-15
format, 4-14 to 4-15

Index-3

DPB (Cont.)
I/O function allowances,
4-19
usage in creating I/O
packet, 3-2
DRDSP,
directive dispatcher, 3-2
Driver,
acceptance routine, 1-13
accessing a controller, 1-17
advanced features, 1-10 to
1-16, 2-4
assembling,
during system generation,
5-3
building,
loadable, 5-2
resident, 5-2
code, 1-19
creating, 4-4
definition, 1-5
function, 4-4
general description, 4-4
requirements, 4-59
usage of symbolic offsets,
4-59
coding, 1-3
conversion routine, 1-15
converting RSX-llM to
RSX-llM-PLUS,
adding GTPKT$, B-4
adding the DDT$ macro
call, B-4
conditional symbols, B-4
handling function codes,
B-6
interrupt entry point, B-6
LBN conversion, B-6
modifying the driver code,
B-4
reconfiguration support,
B-5
using $CVLBN, B-6
using INTSV$, B-6
volume valid processing,
B-5
creating source code, 4-4
data base, 1-4, 1-18
1 inkages, 1-18
data structure, 1-4, 4-27
access i ng, 4-2
details, 4-10
symbolic offsets, 4-2
DDT$ macro call,
arguments, 4-5 to 4-6
placement of, 4-5 to 4-6
debugging, 2-20, 6-1 to 6-6,
6-8, 6-10 to 6-12, 7-13
using CDA, 6-1

INDEX (CONT.)

(Co n t . )
using XDT, 6-1
defining labels, 4-60
details of code, 4-59 to
4-69, 5-70
entry points, 1-4, 2-4
See Driver entry point, 4-62
executable instructions, 1-4
executing on correct
processor, 1-18
Executive,
choosing options, 5-9 to
5-11
Executive services,
typically used, 3-4 to
3-5, 4-6
fer NPR devices on PDP-II,
7-2
fLll-duplex, 4-13
GTPKT$ macro call,
a r g urn e n t s, 4 - 7
placement of, 4-7
handling full-duplex
operations, 1-13
handling multiple I/O
requests, 1-13
I/O packet, 1-4
I/O queue,
placement of I/O packet,
4-11
I/O request,
function codes for, 4-13
processing, 1-15 to 1-16
I/O requirements, 4-19
irlcorporating, 1-18 to 1-19,
5-1
at system generation, 5-1
guidelines for, 5-1
loadable, 5-1
resident, 5-1
ir.itiating I/O, 1-17
irterrupt handling, 1-8
irterrupt level, 1-6, 1-8
i r: t err up t s, 7 -1
INTSV$ macro call,
a r g urn e n t s, 4 - 8
placement of, 4-8
lc,adable,
definition, 1-2
entry points for LOAD and
UNLOAD, 4-9
incorp~rating, 5-1
after system generation,
5-2
at system generation, 5-1
overview, 1-18
rebuildinq and
reincorporating a,
7-13

Dr i v e r

Index-4

Dr i ve r (Co n t. )
with loadable data base,
1-19
with resident data base,
1-19
loadable data base,
incorporating, 5-1
after system generation,
5-2
loading, 5-5
macro call, 4 - 4 to 4 - 5
mapping with Executive,
1-2 to 1-3
modifying data in UCB, 2-3
modul e,
inserting into library,
5-4
partition, 5-5
predriver initiation, 3-2
process, 1-11
definition, 1-5
processing,
I/O request, 1-4, 3-3
interrupts, 1-6
programming,
conventions, 4-1
requirements, 4-4 to
4-9
protocol, 1-8, 4-1
requesting I/O packet, 1-5,
1-17
resident, 1-18
definition, 1-2
incorporating, 5-1
at system generation,
5-2
overview, 1-18
with resident data base,
1-19
sample source code, 8-3 to
8-12
servicing,
I/O request, 1-4
specifying as loadable, 4-9
standards, 4-1
system generation, 5-4 to
5-5
dialogue summary, 5-9
effect, 5-3
system macro call,
arguments, 4-5
general functions, 4-5
task-building, 5-4 to 5-5
types of, 1-2
UMR procedures, 7-2 to
7-5
XDT support, 6-1
Driver Dispatch Table, 4-4
address of routines, 1-4

INDEX (CONT.)

Driver Dispatch Table
(Cont. )
entry points, 2-4
association of, 4-60
fo rmat, 4-60
generation of, 4-4
from DDT$, 4-60
labels required, 4-60
layout, 4-61
link to the driver code and
data base, 4-60
Driver entry point, 2-4
block check and conversion,
4-62
cancel I/O, 4-62, 4-64 to
4-65
controller status change,
4-62, 4-66 to 4-68
deallocation, 4-66
device timeout, 4-62, 4-65
I/O initiation, 4-62 to 4-64
interrupt, 4-62, 4-69, 5-70
next command, 4-65
power failure, 4-62, 4-66
queue optimization, 4-65
standard labels, 4-62
unit status change, 4-62,
4-68 to 4-69
DRQIO,
performing redirect
algorithm, 3-2
$DRQRQ routine, 1-15
locating the conversion
routine, 1-15
DT07 bus switch, 1-16
Dual access, 1-11 to 1-12
operation of, 2-10
Dual-access support, 1-11
$DVMSG routine, 7-17

Elevator,
definition, 1-15
EPKDF$, A-14 to A-20
Executive,
calling the driver, 1-17
coroutine,
$INTSV, 1-6
directive dispatcher,
DRDSP, 3-2
dispatching to correct
driver routine, 2-1
distributing I/O requests,
1-17
handling,
interrupts, 2-1
routines, 1-5 to 1-6
interrupt exit routine, 1-6

Index-5

Executive (Cont.)
interrupt save routine,
1-6 to 1-7
macro library,
EXEMC. MLB, 5- 3
maintaining controller and
hardware specific
information, 2-1
mapping of, 1-3
modifying data in UCB, 2-3
modul e,
DVINT, 1-12
options for driver, 5-9 to
5-11
performing processor
specific functions, 1-16
predriver initiation, 1-4
queuing to the driver, 1-4
request queue for
controller, 1-11
service routine, 1-2 to 1-3
stack and register dump,
6-11
symbol,
$CTLST, 3-15
Executive Debugging Tool,
See XDT
Executive routine, 1-12, 1-15,
4-41
See also Executive services
$G T PKT, 1- 5 , 1-1 3
$IODON, 1-9
Executive services,
summaries of technically
used, 7-5 to 7-39, 8-40
EXELIB.OLB file, A-I
EXEMC.MLB file, A-I
Extended User Control Block,
See UCB
External header, 6-8

FI1DF$, A-21 to A-24
Fa ul t,
tracing, 6-8, 6-12, 7-13
Fault codes, 6-10
Fault isolation, 6-5, 6-7 to
6-8
FCB, 2-14
File Control Block,
See FCB
Fork block, 1-17
storage area, 4-39
Fork list,
head of (SFRKHD), 2-14
Fork process, 1-9, 1-18
definition, 1-8
Fork processing, 1-14

INDEX (CONT.)

Fork routine, 1-8
$FCRK routine, 1-9, 1-18, 7-18
~river use in I/O
processing, 3-5
$FCRKI routine, 7-19
$FFKHD symbol, 2-14
Full-duplex I/O, 1-13
Furction mask,
ACP, 4-19 to 4-20
building for mask word, 4-21
control, 4-19 to 4-20
establishing, 4-22
Jayout, 4-19 to 4-20
1 eg aI,
details, 4-19 to 4-20
no-op, 4-19 to 4-20

SGSPKT routine, 1-13 to 1-14,
7-21 to 7-22
$GT3YT routine, 7-20
$GTPKT routine, 1-5, 1-13,
I-1h, 7-21 to 7-22
u3age in driver code, 3-5
GTP~T$ macro call,
a r g urn e n t s, 4 - 7
$GT1RD routine, 7-23

Har~ware configuration,
r~lationship to structures

at block level, 2-1
HDRJF$, A-25 to A-26
$HE\DR, 6-7, 6-9
p,)inter to first word of
task header, 6-8
Rig l-speed device, 1-16
HWD)F$, A-27 to A-30

I.x(x offsets,
in I/O packet, 4-11 to 4-14
I/O
c,mcel in-progress, 2-5
h gh-speed devices, 1-14
o"erview, 3-4
plocessing requirements,
1-15
s: ow-speed devices, 1-14
I/O count, 1-12
I/O data base structure,
c<'mposite arrangement, 2-11
t\'pical arrangements, 2-7 to
2-8, 2-10
I/O data structure,
dE·tails, 4-10

Index-6

I/O data structure (Cont.)
overview, 2-1 to 2-3
typical arrangements, 2-6
I/O finish,
See $IOFIN routine
I/O function,
definition of types, 3-3
mask values, 4-23
mask word bit settings,
4-24 to 4-26
I/O function mask,
establishing, 4-22
I/O initiation,
entry point, 4-63 to 4-64
sample use of alternative,
8-12 to 8-25, A-26
overview, 2-5
I/O packet, 1-4
building, 4-11
composite arrangement,
2-13 to 2-14
creation of, 3-2
current address, 4-40
fields, 4-11 to 4-14
handling before it is
queued, 8-12 to 8-25,
A-26
layout, 4-11
I/O page, 1-3
I/O queue,
listhead, 4-39
I/O Queue Optimization,
Cylinder Scan, 1-15
Elevator, 1-15
Nearest Cylinder, 1-15
I/O request, 1-4 to 1-5, 1-15
completing process for an,
3-4
flow of, 3-1 to 3-4
issuing I/O for an, 3-4
ICB, 1-2, 1-6, 1-12, 1--18, 2-4
number of controllers
allowed, 1-7
$INIBF routine, 1-14, 7-24
$INISI routine, 1-6
INITL module,
errors from, 6-3
Interrupt, 1-1
addresses,
overview, 2-6
connect-to directive, 1-1
dispatching, 1-7
for common interrupt
devices, 1-12
overview, 2-6
entry address, 2-4
for overlapped seek, 1-12
handling, 1-5, 1-7 to 1-9,
1-12

INDEX (CONT.)

Interrupt (Cont.)
processing by driver, 3-4
protocol, 1-6, 1-9
service routine, 1-5 to 1-6
vector, 1-1, 1-12
Interrupt Control Block,
See ICB
Interrupt entry point, 4-69,
5-70
Interrupt save,
See $INTSV routine
$INTSI routine, 1-7
$INTSV routine, 1-6 to 1-7,
7-25
INTSV$ macro call,
arguments, 4-8
$INTXT routine, 1-6, 7-26
$IOALT routine, 1-13, 1-15,
7-27
driver use in I/O
processing, 3-5, 4-6
$IODON routine, 1-9, 1-13,
7-27
driver use in I/O
processing, 3-5, 4-6
$IOFIN routine, 1-13 to 1-14,
3-3, 7-28
IOS8,
validity checks, 3-2
ITBlDF$, A-31

K. s'rs, 4-48
K. x:<x offsets,
in KRB, 4-47 to 4-48,
4-50 to 4-52
KRB" 1-13
access queue in the, 2-2,
3-15
combined with SCB, 2-2, 4-53
layout, 4-54
composite arrangement, 3-15
configuration status in the,
2-2
contiguous with SCB, 2-7,
4-3
controller status register,
4-50
defining start of addresses,
4-3
dE~fini tion, 1-4
details, 4-45, 4-47 to 4-53
format, 4-47 to 4-53
layout, 4-46
overview, 2-1 to 2-2
subsets, 1-13
use in determining
interrupting unit, 2-2

Index-7

KRB (Cont.)
validation during LOAD,
KRBl, 1-13
KRBDF$, A-32 to A-33

5-12

L.STS, 4-58
L.xxx offsets,
in CTB, 4-55 to 4-56,
4-58 to 4-59
LBN, 1-15
LCBDF$, A-34
LD$xx symbol, 4-9
Legal function mask,
details, 4-19 to 4-20
LOAD command, 1-18 to 1-19,
2-20, 5-2
allowances, 1-7
Executive operation for
driver, 5-11
ope rat i on , 5 -11
overview, 1-18
use of /CTB, 5-14
Load sharing, 1-11
Loadable data base,
See Data base
Loadable driver,
See Driver
Logical block number,
See LBN
Logical unit table,
See LUT
LPAI1-K, 1-13 to 1-14
LUT, 2 -11, 3 - 2

Mask wo rd,
creating, 4-21
I/O function, 4-21
MASSBUS,
controller, 1-13
mixed device, 1-12
Mixed MASSBUS device, 1-12
$MPUBI routine, 7-30
$MPUBM routine, 7-29
MTADF$, A-35 to A-38
Multiple access operation,
data base structures, 2-8,
2-10
Multiple controller, 1-7
Multiprocessor system,
task issuing I/O request,
1-16

INDEX (CONT.)

Nea:est Cylinder,
d ,~ fin i t ion, 1-1 5
Next command entry point, 4-65
No-')p function mask, 4-19 to
4-20
Non-pool-resident, 6-8
h,~ad e r, 6-9
Nonexternal header, 6-8
NPR device,
drivers for (on PDP-II), 7-2

OLRDF$, A-39 to A-46
Overlapped Seek I/O, 1-11
d3ta base structures, 2-8
d3ta transfers, 1-10
difficulty factor, 1-10
e~ecuting parallel
operations, 1-10

Page Address Register,
S,=e PAR
Page Description Register,
See PDR
PAR, 1-2
Parallel un~t operation,
data base structures, 2-8
Partition Control Block,
See PCB
PCB,
composite arrangement, 2-11
PCBDF$, A-47 to A-50
PDR, 1-2
Peripheral configuration,
choosing at system
generation, 5-10 to 5-11
PKTDF$, A-51 to A-56
Pool-resident, 6-8
header, 6-9
Po rts, 1-11
switching between, 1-12
Power failure,
entry point, 4-66
overview, 2-6
Predriver initiation,
processing during, 3-2 to
3-4
Primary UNIBUS run, 1-17
Processor,
halt,
tracing fault, 6-11
loop,
tracing fault, 6-12
Processor-specific functions,
1-17
$PTBYT routine, 7-31

Index-8

$PTWRD routine, 7-32

Q.xxx offsets,
in I/O packet, 4-15 to 4-16
$QINSP routine, 7-33
QIO d i recti ve,
building I/O packet, 4-11
creating DPB, 3-2
directive dispatching, 3-2
QIO Directive Parameter Block,
See QIO DPB
QIO DPB, 4-12, 4-15 to 4-J6
QIO request, 2-11
$QUEBF routine, 1-14
Queue optimization, 1-15
entry point, 4-65

Redirect algorithm, 3-2
Register,
conventions,
at system state, 7-1
$RELOC routine, 7-34
$RELOP routine, 7-35
$REQUI routine, 7-36
$REQUE routine, 7-36
Resident data base,
See Data base
Resident driver,
See Driver
$RQCNC, 4-41
$RQCND, 4-41
RSXASM.CIVID file, 5-3

S.ST2, 4-42
S. ST3, 4-41
S.STS, 4-41
S.xxx offsets,
in SCB, 4-39 to 4-45
SAB, A-5
$SAHDB, 6-9 to 6-10
contains an unknown value,
6-8
$SAHPT, 6-9
pointer to first word of
task header, 6-8
$SAVSP, 6-9
pointer to first word of
task header, 6-8
SCB, 1-13, 2-2
adding KRB, B-2
address for KRB, 2-3
changes for converting a
driver, B-2

INDEX (CaNT.)

SCB (Con t.)
combined with KRB, 4-53
layout, 4-54
composite arrangement,
2-13 to 2-14
contiguous with KRB, 2-7, 4-3
details, 4-37, 4-39 to 4-44
format, 4-39 to 4-44
KRB addresses for, 4-45
layout, 4-38
link to fork blocks, 2-3
overview, 2-3
parallel operations, 2-3
pointer,
to currently assigned KRB,
4-44
to head of queue for I/O
requests, 2-3
validation during LOAD,
5-13 to 5-14
SCBDF$, A-57 to A-58
Secondary UNIBUS run, 1-17
Serial operations,
single controller, 2-7
Serial unit opeiation,
data base structures, 2-7
multiple units per
controller, 2-7
Service routine,
See also Executive services
summaries of Executive, 3-5,
4-6, 7-5 to 7-39, 8-40
SHDDF$, A-59 to A-60
SPR, 2-20
Stack and register dump,
Executive, 6-11
Stack depth indicator, 6-8
Stack structure, 6-12
internal SST fault, 6-10 to
6-11
Static structure, 2-1
Status Control Block,
See SCB
$STKDP, 6-8, 6-11
Stack Depth Indicator, 6-7
$STMAP routine, 7-37
calling from the driver, 7-3
$STMPI routine, 7-38
calling from the driver, 7-3
Subcontroller device, 1-13
block, 1-13
Symbolic offsets, A-I
usage, 4-2
SYSTB.MAC file, 1-18
System,
data structures,
abort codes, A-3
macro definitions, A-I to
A-71, B-72

Index-9

System (Cont.)
stack, 6-11
System Account Block, A-5
System generation,
incorporating a driver, 5-1
System I/O data base,
main thread through, 2-1,
2-3
System macro call, 4-5
System-state,
register convention, 7-1

TAB, A-5
Task,
checkpointing, 1-14
decrementing I/O count, 1-14
frequency of accessing data
areas, 1-15
proper state to initiate
buffered I/O, 1-14
Task Account Block, A-5
Task Control Block,
See TCB
Task header, 6-9
composite arrangement, 2-13
pointers, 6-8
TCB, 1-14
composite arrangement, 2-11
TCBDF$, A-61 to A-64
Timeout count,
initial, 4-40
Timeout entry point,
overview, 2-5
$TKTCB,
pointer to current TCB, 6-7
Tracing fault, 6-8, 6-12, 7-13
Transaction file,
SAB, A-5
TAB, A-5
UAB, A-5
$TSPAR routine, 7-39
$TSTBF routine, 1-14, 8-40

U.ST2, 4-32
U.STS, 4-31
U.xxx offsets,
in UCB, 4-27 to 4-37
UAB, A-5
UCB, 1-13 to 1-14
association with SCB, 2-7
composite arrangement, 2-13
details, 4-27 to 4-37
device-dependent values,
4-29

INDEX (CONT.)

UCB (Cont.)
device-specific
characteristics, 4-32 to
4-35
disk geometry calculations,
B-2
enabling driver to access
data structures, 2-3
fields, 4-27
format, 4-27 to 4-37
layout, 4-28
length, 4-3
stored in DCB, 2-3
order ing, 4-3
overview, 2-3
pointer,
to associated DCB, 4-29
to I/O structures, 2-3
to start of this UCB, 4-29
table,
composite arrangement,
3-15
validation during LOAD, 5-13
UCBDF$, A-65 to A-71, B-72
UCBSV,
usage in macro calls, 4-8
UMR,
programming procedures,
7-2 to 7-5
UNIBUS,
switched bus, 1-16
UNIBUS Mapping Registers,
See UMR
UNIBUS Run Mask,
See URM
Unit,
making accessible, 5-6
placing on line, 5-7
Unit Control Block,
See UCB
Unit status byte, 4-31
Unit status change,
entry point, 4-68 to 4-69
overview, 2-6
Unit status extension 2, 4-32

Index-IO

URM, 1-16, 4-39
User Account Block, A-5
$USRTB global label, 4-3

VCB,
composite arrangement, 3-15
Vector,
addresses,
definition of in Driver
Dispatch Table, 2-6
assignment,
setting, 5-6
assignment error, 5-8
interrupt, 1-1, 1-12
Volume Control Block,
See VCB
Volume valid processing, 5-70

Window block,
composite arrangement, 2-14

XDT, 6-1 to 6-3, 6-5
commands, 6-2
debugg ing,
driver, 6-2, 6-4 to 6-5
general operation, 6-4
restrictions, 6-3
startup, 6-2
xxCTB label, 4-60
$xxDCB,
global label, 4-3
xxDRV.MAC file, 5-2
xxDRVASM.CMD file, 5-3
$xxLOA label, 4-9, 4-61
xxTAB.MAC file, 1-18, 5-2
$xxTBE label, 4-60
$xxTBL label, 4-60
$xxUNL label, 4-9, 4-61

RSX-llM-PLCS
Guide to Writing
an I/O Driver
AA-H26iB- TC
READER'S COMMENTS
NOTE: This form is for document comments only. DIGITAL will use comments submitted on this form at the
company's discretion. If you require a written reply and are eligible to receive one under Software
Performance Report (SPR) service, submit your comments on an SPR form.

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

Did you find errors in this manual? If so, specify the error and the page number.

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

:"lame

.____________________________________________ Date

Organization
Street
City

State ___________ Zi p Code _________
or Country

Do Not Tear - Fold Here and Tape -

~DmDD~D

No Postage
Necessary

11111

if Mailed in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

BSSG PUBLICATIONS ZK1-3/J35
DIGITAL EQUIPMENT CORPORATION
110 SPIT BROOK ROAD
NASHUA, NEW HAMPSHIRE 03061

Do Not Tear - Fold Here