Digital PDFs

AA-BT73B-TH

June 1987

526 pages

Original

18MB

Document:	POS V3.2 Guide to Writing a POS IO Driver and Advanced Programmers Notes
Order Number:	AA-BT73B-TH
Revision:	0
Pages:	526
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/pro3xx/POS/AA-BT73B-TH_POS_V3.2_Guide_to_Writing_a_POS_IO_Driver_and_Advanced_Programmers_Notes_Jun87.pdf

OCR Text

Guide to Writing a P/OS
I/O Driver and Advanced
Programmer's Notes

Guide to Writing a PIOS
1/0 Driver and Advanced
Programmer's Notes
Order No. AA-BT73B-TH
Order No. AD-BT73BA-T1

June 1987

This reference manual describes the procedures for
writing an I/O driver for P/OS systems. Executive
routine descriptions and sample code are included.
Advanced programmer information is also provided.

REQUIRED SOFTWARE:

Host Tool Kit V3.0,
or PRO/Tool Kit V3.2

OPERATING SYSTEM:

PIOS V3.2

DIGITAL EQUIPMENT CORPORATION
Maynard, Massachusetts 01754-2571

First Printing, April 1982
Revised, December 1985
Updated, June 1987

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

for the use or reliability of
is not supplied by DIGITAL or its

The specifications and drawings, herein, are the property of
Digital Equipment Corporation and shall not be reproduced or
copied or used in whole or in part as the basis for the
manufacture or sale of items without written permission.
Copyright © 1982, 1985, 1987 by Digital Equipment Corporation
All Rights Reserved
The following are trademarks of Digital Equipment Corporation:
CTI BUS
DEC
DECmate
DECsystem-10
DECSYSTEM-20
DECUS
DECwriter
DIBOL

~DmDOmD

MASSBUS
PDP
P/OS
PRO/BASIC
PRO/Communications
Professional
PRO/FMS
PRO/RMS
PROSE
PROSE PLUS

Rainbow
RSTS
RSX
RT
Tool Kit
UNIBUS
VAX
VMS
VT
Work Processor

Update Notice Number 1
Guide to Writing a PIOS 1/0 Driver
and Advanced Programmer's Notes
AD-BT73B-T1
June 1987

Insert this page in the Guide to Writing a P/OS I/O Driver and
Advanced Programmer's Notes to maintain an up-to-date record of
changes to the manual.

NEW AND CHANGED INFORMATION

This update reflects software changes and additions made in P/OS Version 3.2.
Also included are corrections to the original documentation.
Copyright © 1987 Digital Equipment Corporation

INSTRUCTIONS

Add the following pages to the Guide to Writing a P/OS I/O Driver and Advanced
Programmer's Notes as replacements for, or additions to, the current pages. The
technical changes made on replacement pages are indicated in the left margin
by change bars. Changes of an editorial nature are not marked.

OLD PAGE

Title page/copyright page
iii/iv through xi/xii
4-55/4-56
4-63/4-64 through 4-65/4-66
5-3/5-4 through 5-5/5-6
(Continued)

NEW PAGE

Title page/copyright page
iiiliv through xvii/xviii
4-55/4-56
4-63/4-64 through 4-65/4-66
5-3/5-4 through 5-5/5-6

OLD PAGE
7-45/7 -46 through 7-65/7-66
C-1/C-2 through C-33/blank
0-1/0-2
E-1/E-2 through E-43/E-44
Index-1 through Index-6
Reader's comments/mailer

NEW PAGE
7-45/7-46 through 7-65/7-66
C-1/C-2 through C-35/C-36
0-1/0-2
E-1/E-2 through E-45/E-46
Index-1 through Index-8
Reader's comments/mailer

CONTENTS

CHAPTER 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.5

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
2.3.1
2.3.2
2.3.3
2.4

P/OS I/O DRIVERS

VECTORS AND CONTROL AND STATUS REGISTERS .
· 1-1
SERVICE ROUTINES . . .
· . . . . 1- 3
Executive and Driver Layout
· 1-3
Driver Contents . . . . . .
· . . . . . . 1- 5
EXECUTIVE AND DRIVER INTERACTION
· 1-6
The Driver Process . . . . . .
....
· 1-6
Interrupt Dispatching and the Interrupt Control
Block . . • . . . . . . . . . . . .
. 1-7
Interrupt Servicing and Fork Process . . . . . . 1-9
Nonsense Interrupt Entry Points
1-11
ADVANCED DRIVER FEATURES . .
. . . . . . 1-11
Overlapped Seek I/O
. . • . . . . . . . 1-12
Delayed Controller Access
. . . . . . 1-13
Full Duplex Input/Output .
. . . .
1-13
Buffered Input and Output
. . . . . 1-14
OVERVIEW OF INCORPORATING A USER-WRITTEN DRIVER
INTO P/OS . • . . . . . . . . . . . . . . . . . 1-15
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 ·
· · · ·
Controller and Unit Status Change ·
Device Interrupt Addresses
TYPICAL CONTROL RELATIONSHIPS
·
Multiple Units per Controller, Serial Unit
Operation
·
·
·
Multiple Controllers, Single Unit per
Controller
Parallel Unit Operation
·
OVERVIEW OF DATA STRUCTURE RELATIONSHIPS

· ·

·
· · ·

· · · · · ·
· · · · · · ·

iii

· 2-1
2-1

· · · · · 2-2
· · ·
· · · · 2-3
· 2-3
· · · · 2-4
· ·
· 2-5
· 2-6
· · · · · · · 2-7
2-7
· 2-7
·
· 2-8
···
· 2-8
· · · · · · 2-8
· · · · · · · · · · 2-9
2-10
· · · · ·
2-10
· ·
·
2-12

CHAPTER 3
3.1

3.1.1
3.1.2
3.2
3.2.1
3.2.2
3.2.3
CHAPTER 4

EXECUTIVE SERVICES AND DRIVER PROCESSING
FLOW OF AN I/O REQUEST . . . • . . .
. . . . . 3-1
Predriver Initiation Processing
· 3-2
Driver Processing . . . . . . . .
· 3-4
EXECUTIVE SERVICES AVAILABLE TO A DRIVER .
· 3-5
Get Packet ($GTPKT) . . . . .
· 3-5
Create Fork Process ($FORK)
· 3-6
I/O Done ($IODON or $IOALT) . . . .
· 3-6
PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER

PROGRAMMING STANDARDS
. . . . . 4-1
Programming Protocol Summary . . . . . . . . . . 4-1
Accessing Driver Data Structures .
. 4-2
OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER DATA
BASES
• • • • • • • • • • • • • • • • • • • • • • 4-3
General Labeling and Ordering of Data Structures 4-3
4.2.1
Device Control Block Labeling . . . . . . . . . 4-3
4.2.2
Unit Control Block Ordering • . . . . . . . . . 4-3
4.2.3
Status Control and Controller Request Blocks . . 4-4
4.2.4
Controller Table . . . • . . . . . . . . . . . . 4-4
4.2.5
OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER CODE . 4-6
4.3
Generate Driver Dispatch Table Macro Call - DDT$ 4-6
4.3.1
4.3.2
Get Packet Macro Call - GTPKT$ . . . • . . . . . 4-9
Interrupt Save Macro Call - INTSV$ . . . .
4-10
4.3.3
Using the UCBSV Argument in Macro Calls
4-11
4.3.4
Driver Entry Points for PROLOD . . . . . .
4-12
4.3.5
DRIVER DATA STRUCTURE DETAILS . . . • . . .
4-13
4.4
4.4.1
The I/O Packet . . . . . . . . . . • . . .
4-14
The QIO Directive Parameter Block (DPB)
4-20
4.4.2
The Device Control Block (DCB) . . .
4-23
4.4.3
Establishing I/O Function Masks
. . . . 4-29
4.4.3.1
The Unit Control Block (UCB) . . .
. . . . 4-35
4.4.4
The Status Control Block (SCB) . . .
4-47
4.4.5
The Controller Request Block (KRB) .
4-55
4.4.6
Contiguous Allocation of the SCB and KRB .
4-62
4.4.7
Controller Table (CTB) . . .
. . . .
4-62
4.4.8
4.5
DRIVER CODE DETAILS . . . . .
4-67
Driver Dispatch Table Format .
4-68
4.5.1
I/O Initiation Entry Point .
4-72
4.5.2
Cancel Entry Point . . . . .
4-73
4.5.3
Device Timeout Entry Point .
4-73
4.5.4
Deallocation Entry Point .
4-73
4.5.5
4.5.6
Power Failure Entry Point • . . .
4-74
Controller Status Change Entry Point .
4-74
4.5.7
Unit Status Change Entry Point
4-76
4.5.8
Interrupt Entry Point
. . . . . 4-77
4.5.9
Volume Valid Processing . . . .
. . . • 4-78
4.5.10
4.1
4.1.1
4.1.2
4.2

CHAPTER 5
5.1
5.1.1
5.1.2
5.1.3
5.1.4
5.2
5.2.1
5.2.2
5.2.3
5.2.4

CHAPTER 6

INCORPORATING A USER-SUPPLIED DRIVER INTO P/OS

INCORPORATING AN I/O DRIVER INTO A P/OS SYSTEM
5-1
Guidelines for Creating/Adding a Driver Into the
System . . . . . . . . . . . . . . . . . . . . • 5-1
Assembling the I/O Driver
. . . . . . . . . 5-2
Taskbuilding the I/O Driver . . . . • .
. 5-2
Loading an I/O Driver Into the System . . . . . 5-3
PROLOD. . . . . . . . . . . . . . . . . . .
.5-3
PROLOD Operations and Diagnostic Checks
. • 5-5
Using PROLOD Autoconfiguration . . . . .
. 5-8
PROLOD Errors . . . . . . . . .
. 5-9
PROLOD Sample Program . . . . .
5-11
DEBUGGING A USER-SUPPLIED DRIVER

THE EXECUTIVE DEBUGGING TOOL .
• 6-1
6.1
6.1.1
XDT Commands . . . . . . . . . .
. • . . • 6-1
6.1.2
XDT Start Up . . . . . . .
• 6-2
XDT General Operation
. 6-2
6.1.3
XDT and Debugging a User-Supplied Driver •
• 6-3
6.1.4
6.2
MAINTENANCE- OR MICRO-ODT
. 6-3
6.3
FAULT ISOLATION . . . . . . . . • . . . • .
. 6-4
6.3.1
Immediate Servicing
. . . .•
. 6-4
6.3.1.1
The System Traps to XDT
. 6-4
6.3.1.2
The System Halts but Displays No Information . 6-4
6.3.1.3
The System Is in an Unintended Loop . . . . • 6-5
Pertinent Fault Isolation Data . .
. 6-5
6.3.2
6.4
TRACING FAULTS .
. . • . .
. 6-6
Tracing Faults Using the Executive Stack and
6.4.1
Register Dump . . . . . . . . . .
· 6-9
Tracing Faults When the Processor Halts Without
6.4.2
Display
. . . . . . . . . .
6-12
6.4.3
Tracing Faults After an Unintended Loop
6-13
Additional Hints for Tracing Faults
6.4.4
6-13
6.4.5
System Bugcheck without XDT . . . . .
6-13
6.5
REBUILDING AND REINCORPORATING A DRIVER . . . . 6-15
CHAPTER 7
7.1
7.2
7.3
7.3.1
7.3.2
7.4
7.5
7.5.1
7.5.2

EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER

SYSTEM-STATE REGISTER CONVENTIONS . . . .
EXECUTIVE TIMER RELATED FACILITIES .
ADDRESSING A TASK BUFFER . . . . . .
Address Checking a Task Buffer . .
QIO Directive Processing Specifics .
THE ADDRESS DOUBLE WORD
. • . .
SERVI CE CALLS . . . . . . . • . . . . . • .
Address Check . . . .
. • • •
Allocate Core Buffer
...•.
v

·
·
·
·
·

7-1
7-1
7-4
7-6
7-6
7-11
7-12
7-14
7-16

7.5.3
7.5.4
7.5.5
7.5.6
7.5.7
7.5.8
7.5.9
7.5.10
7.5.11
7.5.12
7.5.13
7.5.14
7.5.15
7.5.16
7.5.17
7.5.18
7.5.19
7.5.20
7.5.21
7.5.22
7.5.23
7.5.24
7.6
7.7
7.7.1
7.7.2
7.7.3
7.7.4
CHAPTER 8
8.1
CHAPTER 9
9.1
9.1.1
9.1.2
9.1.3
9.1.4
9.1.5
APPENDIX A
A.l
A.2
A.3

Check Logical Block
. . . .
Move Block of Data . . . . . . .
Check I/O Buffer . . .
....
Clock Queue Insertion . . . . . .
Convert Logical Block Number .
Deallocate Core Buffer . .
Fork . . .
Forkl . . . .
Get Byte .
......... .
Get Packet
. . . .
Get Word . .
. . . .
Initiate I/O Buffering .
Interrupt Exit . • . • . . . . . .
I/O Done Alternate Entry and I/O Done . • . .
I/O Finish . .
. . . . .
Put Byte . . . . .
Put Word . . . . .
Queue Insertion by Priority
Relocate • . . . .
Queue Kernel AST to Task
Test if Partition Memory Resident for Kernel

7-17
7-19
7-20
7-22
7-23
7-24
7-25
7-27
7-28
7-29
7-32
7-33
7-34
7-35
7-36
7-38
7-39
7-40
7-41
7-42

AST

7-43
7-44
7-44
7-48
7-48
7-49
7-50
7-51

•

Test for I/O Buffering . . . . . . . • . . . •
ADDING PHYSICAL MEMORY TO THE P/OS CONFIGURATION
EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS . .
Pointer Location and Format
. . . . • . .
Referencing LOWCR and SYSCM Data Structures
Referencing Executive Routines
. . . .
Executive Routine Vector Table . . . . . . . .
HANDLING SPECIAL USER BUFFERS

. . . . . . . . . . 8-1

DRIVER CODE

ACCESSING VIDEO HARDWARE AND TERMINAL SUBSYSTEM

APPLICATION LEVEL ACCESS TO THE VIDEO HARDWARE
Disabling the Terminal Subsystem
. •
Accessing the Video Device Registers
Accessing Video Memory Through the Bus
The Screen Timer
.........••.
Returning the Video Hardware to the System

•
.
.
.

. 9-1
. 9-2
. 9-3
• 9-4
. 9-4
. . 9-5

PIOS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

ABODF$ .
ACNDF$ .
ACTDF$

• • A-4
• A-6
. A-8

A.4
A.5
A.6
A.7
A.8
A.9
A.l0
A.ll
A.12
A.13
A.14
A.15
A.16
A.17
A.18
A.19
A.20
A.21
A.22
A.23
A.24
APPENDIX B

·
·
·
·
. ·

BCKDF$
CLKDF$
CTBDF$
DCBDF$
DDT$
FllDF
GTPKT$
HDRDF$
HWDDF$
INTSV$
ITBDF$
KRBDF$
LBLDF$
LNMDF$
PCBDF$
PKTDF$
QIOSY$
SCBDF$
TTSYM$
TCBDF$
UCBDF$

· · · · ·
· · · · ·
. · · · · · · · ·

A-l0
A-13
A-1S
A-17
A-19
A-21
A-26
A-27
A-29
A-36
A-37
A-39
A-42
A-4S
A-46
A-52
A-59
A-70
A-73
A-79
A-83

· · · ·
· · ·
· · · ·
.
. . . · · · ·· ·· ·
~.

·
·
· · · ·
·
· · · · ·
·
··
·
· · · ·
· · · · ·
·
·
· · · · ·
·
· · · ·
·
.
.
.
·
·
·····
· .
··
· · · ·
··

TASK BUILDING AND CLUSTER LIBRARIES

AN OVERVIEW OF OVERLAYING
B.l
·
8asic Overlay Concepts and Constraints .
B.l.l
The Overlay structure
. • ..
....
B.l.2
Overlaying Code Segments . • . .
B.l.2.1
Making the Tree More Flexible
. . . .
B.l.2.2
·
B.l.2.3
Co-trees . . . . . . . . . . . .
B.l.2.4
Overlaying Data . . . . . . . . . • . .
CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS
B.2
Simple Task structure and Memory Mapping . . .
B.2.1
Libraries and Virtual Address Windows • . . .
B.2.2
Library Sharing and Multiple Libraries . .
B.2.3
Library with Memory-Resident Overlays . . . .
B.2.4
Clustered Libraries • . . . . . . . . . .
B.2.5
Cluster Libraries - Implementation Detail
B.2.6
Summary and Implications
.•......
B.2.7
Inter-Library References and Miscellaneous
B.2.8
Points . . . • . . . . . . . . . . . . .
WRITE Access to Clustered Libraries
B.2.9
B.2.10
NULL I B . . . . . . • . . . . . . .
OPTIONS IN TASK ORGANIZATION
B.3
FLAT. TSK . . . •
B.3.1
FLATBLD.CMD
B.3.1.1
ROOT • MAC . • .
B.3.1.2
B.3.1.3
MAINLINE.MAC .
ROOTDATA.MAC .
B.3.1.4
CLUST.TSK
6.3.2
vii

.
·
·
·
.
·

8-1
8-2
B-4
B-4
8-8
B-9
8-10
B-ll
8-11
8-14
8-16
8-18
8-20
8-23
8-24
8-25
8-26
B-27
B-28
8-30
8-30
8-30
8-31
8-34
8-37

B.3.2.1
B.3.2.2
B.3.3
B.3.3.1
B.3.3.2
B.3.3.3
B.3.3.4
B.3.3.5
B.3.3.6
B.3.3.7
B.3.4
B.3.4.1
B.3.4.2
B.3.4.3
B.3.4.4
B.3.4.5
APPENDIX C

CLUSTBLD.CMD . . . . . . .
CLUST.ODL . . . . . . . .
VECTOR.TSK and USRRES.TSK
USRRESBLD.CMD
USRRES.ODL .
Discussion . . . . . . . .
Excerpt from RESVEC.MAC . . . .
VECTOR.MAC (Root vector module)
VECTORBLD.CMD
VECTOR.ODL .
OVERLAY.TSK
OVERLAY.ODL
OVERLABLD.CMD
ROOT2.MAC
CLLWTR.MAC .
COMPUTE.MAC

B-37
B-38
B-39
B-39
B-40
B-40
B-42
B-42
B-43
B-44
B-45
B-45
B-46
B-46
B-47
B-47

FILES-11 ON-DISK STRUCTURE SPECIFICATION

C.l
MEDIUM .
·
C.l.l
Volume . . . .
·
Volume sets
C.l.2
C.2
FILES . . . . .
C.2.l
File 10
C.2.2
File Header
Header Area
C.2.2.l
Ident Area . .
C.2.2.2
• •
Map Area . .
C.2.2.3
•
C.2.2.4
End Checksum .
Extension Headers
C.2.3
File Header - Detailed Description
C.2.4
Header Area Description
C.2.4.1
•
Ident Area Description . .
C.2.4.2
• • • •
Map Area Description . . .
C.2.4.3
· .
C.2.4.4
End Checksum Description .
C.2.4.5
File Header Layout . . . .
C.3
DIRECTORIES . . . . . . . . .
Directory Hierarchies
C.3.l
User File Directories . . . . .
C.3.l.l
C.3.2
Directory structure
Di rectory Protection .
....
C.3.3
C.4
KNOWN FILES . . . . . . . . .
C.4.l
Index File . . . . .
. . . .
C.4.l.l
Bootstrap Block . . . . . . . .
Home Block . . . .
C.4.l.2
C.4.l.3
Index File Bitmap . . . . . . .
C.4.l.4
File Headers. . .
· .
C.4.2
storage Bitmap File
C.4.2.l
Storage Control Block
C.4.2.2
Storage Bitmap . .
viii

. . .
. . .
·
·
·
·
·

C-1
C-l
C-2
C-2
C-2
C-3
C-3

• • . C- 4
• • • C- 4

· C-4
· C-4
· C-4
• • • C- 5
•

• C- 9

. .

•

C-lO
C-l3
C-14
C-16
C-16
C-16
C-17
C-18
C-19
C-19
C-19
C-20
C-27
C-28
C-28
C-28
C-29

. .

. · · · ·

Bad Block File
C.4.3
Bad Block Oescriptor
C.4.3.1
C.4.4
Master File Oirectory
C.4.S
Core Image File
FCS FILE STRUCTURE
C.S
C.S.l
FCS File Attributes
F.RTYP: 1 Byte - Record Type
C.S.l.l
F.RATT: 1 Byte - Record Attributes
C.S.l.2
F.RSIZ: 2 Bytes - Record Size
C.S.l.3
F.HIBK: 4 Bytes - Highest VBN Allocated
C.S.l.4
C.S.l.S
F.EFBK: 4 Bytes - End of File Block
F.FFBY: 2 Bytes - First Free Byte
C.S.l.6
S.FATT: 14 Bytes - Size of Attribute Block
C.S.l.7
FCS File Attrfbutes Layout
C.S.l.8
Record Structure
C.S.2
Fixed Length Records
C.S.2.1
C.S.2.2
Variable Length Records
Sequenced Variable Length Records
C.S.2.3
Format of Two Byte Print Control Field in
R.SEQ Records

· · · ·
· · · ·
· · · ·

· · · · ·
· · ·

APPENDIX 0
0.1
0.1.1
0.1.2
0.1.2.1
0.1.2.2
0.1.2.3
0.1.3
0.1.4
0.1.5
0.2
0.3
0.4
0.5
0.5.1
0.5.2
0.5.3
0.5.4
0.5.5
0.6
0.6.1
0.6.2
0.6.3
0.7
0.8
0.9

· · · ·

· · · ·
· · · · ·
·

· · · ·

· · · · · · .

C-29
C-30
C-30
C-30
C-31
C-31
C-31
C-31
C-32
C-32
C-32
C-32
C-33
C-33
C-33
C-33
C-34
C-34

· · · · · ·

C-34

FILES-ll QIO INTERFACE TO THE ACPS
QIO PARAMETER LIST FORMAT
File Identification Block
The Attribute List . . . . . .
The Attribute Type . . . . . . .
Attribute Size . . . . .
Attribute Buffer Address . .
Size and Extend Control
Window Size and Access Control . .
File Name Block Pointer
. . . . .
PLACEMENT CONTROL
. . . . .
BLOCK LOCKING . . . . . . .
SUMMARY OF FllACP FUNCTIONS . . . .
HOW TO USE THE ACP QIOS
. . . . .
Creating a File
Opening a File . . . . .
Closing a File .
Extending a File
Deleting a File
FILE HEADER BLOCK FORMAT
Header Area
. . . .
Identification Area
Map Area . . • . . . .
STATISTICS BLOCK .
ERRORS RETURNED BY THE FILE PROCESSORS .
.... • . . .
FILENAME BLOCK . .

·
·
·
·
·
·
·
·
·

0-1
0-2
0-2
0-3
0-4
0-5
0-6
0-6
0-7
0-8
· 0-8
· 0-9
0-11
0-11
0-11
0-11
0-12
0-12
0-12
0-15
0-16
0-17
0-18
0-19
0-23

APPENDIX E

QUAD SERIAL LINE UNIT (PC3XC-BA)

Appendix . . . .
. . . .
E-1
E.1
INTRODUCTION . .
. . . .
· E-1
E.2
THEORY OF OPERATION . . . . . . . .
E-2
E. 2 . 1
DUART s . . . . . . .
. . . .
· E-2
E.2.2
Interrupt Logic
... .
· E-2
E.2.3
Modem Controls . . . . . .
· • E- 3
E.3
DUART TRANSMITTER OPERATION . . . . • • • • • • • E - 4
E.3.1
Receiver Operation.
. .. .
E-5
E.3.2
Interrupts..
. .. .
· . E-7
E.3.3
Programming
....... .
· . E-7
E.3.4
Multidrop Mode
... .
E-7
E.3.5
Registers
... .
· . E-8
E.3.6
Diagnostic ROM Data Register (RDR) .
· . E-9
E.3.7
Diagnostic ROM Address Register (RAR)
• • • •
E -1 0
E.3.8
Module Status Register (MSR) . . .
E-10
E.3.9
DUART Registers . . . . . . . . .
E-11
E.3.9.1
Channel A Mode Register 1 (MR1A) .
E-13
E.3.9.2
Channel A Mode Register 2 (MR2A)
E-15
E.3.9.3
Channel A Status Register (SRA)
E-18
E.3.9.4
Channel A Clock Select Register (CSRA)
E-21
E.3.9.5
Channel A Command Register (CRA) . . .
E-22
E.3.9.6
Channel A Receive Holding Register (RHRA)
E-24
E.3.9.7
Channel A Transmitter Holding Register (THRA) E-25
E.3.9.8
Input Port Change Register (IPCR)
E-26
E.3.9.9
Auxiliary Control Register (ACR) . . .
E-26
E.3.9.10
INTERRUPT STATUS REGISTER (ISR)
E-30
E.3.9.11
INTERRUPT MASK REGISTER (IMR)
....
E-32
E.3.9.12
Counter/Timer Upper Byte Value (CTU) .
E-32
E.3.9.13
Counter/Timer Upper Register (CTUR)
. . . . E-32
E.3.9.14
Counter/Timer Lower Byte Value (CTL) .
E-33
E.3.9.15
Counter/Timer Lower Register (CTLR)
. . . . E-33
E.3.9.16
Channel B Mode Register 1 (MR1B) . . .
E-33
E.3.9.17
Channel B Mode Register 2 (MR2B)
E-34
E.3.9.18
Status Register B (SRB)
...... .
E-35
E.3.9.19
CHANNEL B CLOCK SELECT REGISTER (CSRB) .
E-35
E.3.9.20
CHANNEL B COMMAND REGISTER (CRB) . . .
E-35
E.3.9.21
CHANNEL B RECEIVE HOLDING REGISTER (RHRB)
E-36
E.3.9.22
CHANNEL B TRANSMITTER HOLDING REGISTER (THRB) E-36
E.3.9.23
INPUT PORT (IP)
. . . . . . . . . . . . . . E-36
E.3.9.24
Output Port Configuration Register (OPCR)
E-36
E.3.9.25
START COUNTER Command
E-37
E.3.9.26
SET OUTPUT PORT BITS Command . .
E-37
E.3.9.27
STOP COUNTER Command . . . . . . . . . .
E-38
E.3.9.28
RESET OUTPUT PORT BITS Command.
E-38
E.4
MODEM CONTROLS FOR 2/2 CONFIGURATION
E-38
E.4.1
Input Port Assignments . . . .
E-38
E-39
E.4.2
Output Port Bit Definitions
E.4.3
Input Port Set-Up . . . . .
E-40
E-40
E • 4 • 3 •1
CT S . . . . . . . . . . .
x

E.4.3.2
DSR
E.4.3.3
CD . .
E.4.3.4
RI . .
E.4.4
Set-Up For Outputs
....
E.4.4.1
RTS . . . . . . . . .
E.4.4.2
LL . .
E.4.4.3
DTR . . . .
E.4.4.4
RL .
E.4.4.5
DSRS .
E.5
MODEM CONTROLS FOR 4/0 CONFIGURATION . .
E.5.1
Input Port Assignments . . .
Output Port Bit Definitons
E.5.2
Input Port Set-Up
E.5.3
E.5.3.1
CTS
. . . .
CD .
E.5.3.2
E.5.3.3
DSR
. . . . .
Set-Up For Outputs .
E.5.4
E.5.4.1
RTS
. . . .
E.5.4.2
DTR
Connector Box
E.5.5

E-40
E-40
E-40
E-40
E-41
E-41
E-41
E-41
E-41
E-41
E-41
E-42
E-43
E-43
E-43
E-43
E-43
E-43
E-43
E-43

INDEX
FIGURES
1-1
1-2
2-1
2-2
2-3
2-4
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

Virtual to Physical Mapping for the Executive . . 1-4
Interrupt Dispatching for a Driver . . . . . . . . 1-8
Multiple Units per Controller, Serial Unit
Operation . . . . . . . . . . . . . . . . . . . . 2-9
Multiple Controllers, Single Unit per Controller 2-11
Parallel Unit Operation (Overlapped Seek)
2-11
Composite I/O Data Structures . . . . .
2-14
I/O Packet Format - Control Function . . .
4-16
I/O Packet Format - Transfer Function
4-17
QIO Directive Parameter Block (DPB)
. . . .
4-21
Device Control Block . . . . .
4-23
D.PCB and D.DSP Bit Meanings .
. . ..
4-30
Unit Control Block .
4-36
Unit Control Byte
4-38
Unit Status Byte . . . . .
. . . .
4-40
unit Status Extension 2
4-42
Status Control Block . . .
4-48
Controller Status Extension 3
4-51
Controller Status Extension 2
4-53
Controller Request Block . . . .
4-56
Controller Status Word . . . . .
. . . .
4-58
Contiguous KRB/SCB Allocation
. . ..
4-63
Controller Table . . . . . . .
. . . . . . 4-64
Controller Table Status Byte. .
. . . .
4-66
xi

4-18
4-19
6-1
6-2
6-3
6-4
6-5
B-1
B-2
B-3
B-4
B-5
D-1
E-1
E-2
E-3
E-4
E-5
E-6
E-7
E-8
E-9
E-10
E-11
E-12

Driver Dispatch Table Format . . . . . . • .
4-69
Sample Interrupt Address Block in the DDT
4-71
Interaction of Task Header Pointers . . • .
• 6-7
Task Header
. . . . . . . . . .
· 6-8
Stack Structure:
Internal SST Fault.
6-10
Stack Structure: Abnormal SST Fault . . . .
6-11
Stack Structure: Data Items on Stack .
6-12
Simple Task Structure and Memory Mapping . .
B-13
Libraries and Virtual Address Windows
B-15
Library Sharing and Multiple Libraries
B-17
Library With Memory-Resident Overlays
B-19
Clustered Libraries . . . . . • . .
B-22
Filename Block Format
. • . .
D-25
PRO 300 Modules Addressing Scheme . . . •
• E-8
Module Status Register . .
E-l0
Channel A Mode Register 1 (MR1A) . . .
E-13
Channel A Mode Register 2 (MR2A) .
E-15
Channel A Status Register (.ref status . • • • . E-19
Channel A Clock Select Register (CSRA)
E-21
Channel A Command Register . . • . . .
E-23
Auxiliary Control Register . . . . . .
E-26
Interrupt Status Register
. • . •
E-30
Interrupt Mask Register
E-32
Channel B Mode Register 2 . . . .
E-34
Output Port Configuration Register .
E-37

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

Option Slot Address Assignments
.
System Macro Calls for Driver Code*
. . . • . .
DDT$ Macro Call Arguments . . . .
GTPKT$ Macro Call Arguments
. . . . .
INTSV$ Macro Call Arguments . . . .
Mask Values for Standard I/O Functions • • .
Mask Word Bit Settings for Disk Drives. • • . .
Mask Word Bit Settings for Magnetic Tape Drives
Mask Word Bit Settings for Unit Record Devices.
Labels Required for the Driver Dispatch Table
Standard Labels for Driver Entry Points . • . .
QIO Processing By Function Type and Device
Characteristics . . . . . •
• . •
I/O Packet Usage by Function Type
. . . .
Summary of Executive Service Calls for Drivers.
Summary of System Data Structure Macros
Maximum Size for Each File Attribute .
File Header Block . . . . .
Statistics Block Format . . . . . .
File Processor Error Codes . . . . .
Filename Block Offset Definitions . • . .
Filename Block Status Word (N.STAT)

TABLES

7-2
7-3
A-1
0-1
D-2
D-3
D-4
D-5
D-6

xii

.
•
.
.

1-2
4-7
4-7
4-9
4-11
4-31
4-32
4-33
4-34
4-68
4-71

. 7-7
. 7-9
7-13
• A-2
• 0-5
0-12
0-18
0-19
0-23
0-25

D-7
E-l
E-2
E-3
E-4
E-5
E-6
E-7
E-8
E-9
E-l0

Filename Block Offset Definitions for ANSI
Magnetic Tape
PRO 300 Module Register Summary
Configuration of Bits 2 and 3 (MSR)
DUART 0 Register Addresses
Channel A Receiver Baud Rate
Baud Rate Generator Characteristics (CLOCK
3.6864 MHZ)
Counter/Timer Mode and Clock
2/2 Input Port Bits
· ·
2/2 Output Port Bits
4/0 Input Port Bits
4/0 Output Port Bits

. . . · · · · · · · ·

· · · ·

E-ll
E-12
E-21

· · · ·
· · ·
· . · · · ·

E-28
E-29
E-38
E-39
E-41
E-42

· · · · · ·
· · · · ·

. . . . ·

· ·
· · · ·
·

xiii

D-26

. E-9

· · · ·

PREFACE

Document Objectives

The primary goal of this manual is to introduce P/OS physical I/O
concepts, define Executive 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
detail to allow you to:
•

Prepare software that interfaces with the Executive
supports a conventional I/O device.

and

•

Incorporate
system.

P/OS

•

Detect typical errors that cause the system to crash.

•

Use Executive service routines
routine typically employs.

•

Develop P/OS video applications that directly access the
video hardware.

the

user-written

software

that

into

I/O

service

CAUTION

Unless
explicitly
noted
otherwise,
all
information in this manual is subject to change
without notice.

Intended Audience

This manual is written for the senior-level system programmer who
is familiar with the hardware characteristics of both the
Professional 300 Series 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 a P/OS system.
The manual neither
describes general Executive concepts nor defines general system
structures. The manual does describe I/O concepts,the Executive
xv

role in processing I/O requests, and some pertinent aspects of
I/O processing done by DIGITAL-supplied software. Therefore,
with a firm understanding of hardware characteristics and P/OS
system software, a senior-level system programmer could attempt
to write an I/O driver.

Structure of This Document

This manual has three types of
information:
conceptual,
procedural, and reference.
The following are abstracts of the
chapters in the document:
•

Chapter 1, P/OS I/O Drivers, introduces terms and concepts
fundamental to understanding physical I/O in P/OS, and
describes the protocol that a driver must follow to preserve
system integrity. It summarizes advanced driver features and
P/OS 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 on 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 the
driver, and an extensive elaboration of the driver data base
and of the driver code.

•

Chapter 5, Incorporating A user-Supplied Driver into P/OS,
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.

xvi

•

Chapter 6, Debugging A User-Supplied Driver, summarizes
software features provided to help you uncover 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-ll and
P/OS Executive service routines.

•

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.

•

Chapter 9, Accessing Video Hardware and Terminal Subsystem,
provides reference information on the driver'S control of
Professional video hardware and software.

•

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

•

Appendix B, Task Building and Cluster Libraries, is a
collection of three documents describing overlaying task
structures, cluster libraries, and task organization.

•

Appendix C, Files-11
On-Disk
Structure
Specification,
describes the general-purpose file structure intended for use
on medium and large-size PDP-ll systems.

•

Appendix 0, 010 Interface to the ACPs, describes
level interface to the file processors (ACPs).

the

QIO

Appendix E, Ouad Serial Line Unit
Driver
(PC3XC-BA),
• describes
the
Quad
Asynchronous Communications Module
(PC3XC-BA) .

Associated Documents

Included in your P/OS Tool Kit documentation are documents that
describe both the software and hardware on the system. The
software documents are listed and described in the Tool Kit
User's Guide.
Consult this document for concise summaries of
For information on
hardware
software-related publications.
technical
specifications,
see the Professional 300 Series
Technical Manual.
xvii

Also, it is recommended that you
listings, which· are published
Executive Listings and Maps.

refer to the PIOS Executive
on microfiche. It is entitled

Associated Files

•• As mentioned in your
•
•
•

installation
guide,
the
directory
[ZZPRIVDEV] on the PRODCL2 diskette contains several library and
symbol table files, which are needed for writing privileged
applications.

xviii

CHAPTER 1
P/OS I/O DRIVERS

Device drivers on P/OS are the primary method of interfacing the
Executive's I/O subsystem with hardware attached to the computer.
Most DIGITAL-supplied hardware is supported by drivers accompanying
the system that the user receives.
This chapter introduces the
concept of device drivers and explains driver operations and features.

1.1

VECTORS AND CONTROL AND STATUS REGISTERS

Associated with a device contoller are device control and status
registers.
The addresses of these registers are determined by the
physical slot in which the controller has been inserted, rather than
the actual option module.
A given controller may have up to 64.
words of device registers as shown in Table 1-1. To provide a unique
identification for controllers, a hardware ID is expected to be
present, and may be accessed at the first address within a given
slot's device register address range. The bootstrap and diagnostic
ROM examines each option slot and places the hardware IDs in a
configuration table located at the top of physical memory. This table
is referenced by PROLOD to resolve the hardware ID specified in the
controller table (CTB) located in the driver's database. The table
may also be accessed by the executive's WIMP$ directive (See the PjOS
System Reference Manual for further details of the directive arguments
and table format.) Certain controllers are physically present on the
motherboard.
These devices have predefined device registers and are
fully described in the Professional 300 Series Technical Manual.

1-1

VECTORS AND CONTROL AND STATUS REGISTERS

Table 1-1:

Option Slot Address Assignments

Physical
Slot
Position

Logical
Slot
Number

Device Register
Address Range

--------

-----0
1
2
3
4
5

17774000-17774177
17774200-17774377
17774400-17774577
17774600-17774777
17775000-17775177
17775200-17775377

1
2
3
4
5
6

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

Vector
Address
Interrupt A
ICSRA=
17773206

Vector
Address
Interrupt B
ICSRB=
ICSRA+4

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

300
310
320
330
340
350

304
314
324
334
344
354

System peripheral Address Assignments

Logical
Slot
Number

Device Register
Address Range

-------

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

0
1
2
3
4
5
6
7

( ICSR;::: 17773202)
Vector
Address Device Type
------- ---------------------Not used
Keyboard receiver
200
Keyboard transmitter
204
210
Comm. Port rec./trans.
214
Comm. Port modem status
Printer Port receiver
220
Printer Port trans.
224
System clock
230

17773500-17773506
17773300-17773314
17773400-17773406
17773000-17773032

Optionally, a controller may utilize one or two of the two-word areas
associated with each slot,
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 a device interrupts, the vector address is sent to the
processor. 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.

1-2

VECTORS AND CONTROL AND STATUS REGISTERS
Space is reserved on the PDP-ll 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.

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.
Although linked into the Executive structures, a driver resides in
memory outside the virtual address space of the Executive. An
application can add or remove a driver by means of PROLOD, a callable
POSSUM system routine.
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.

1.2.1

Executive and Driver Layout

A device driver is a logical extension of the Executive that is not
contiguous in physical memory with the Executive code. Active Page
Registers (APRs)* 0 through 4 map the Executive, APR 7 is reserved to
map the I/O page, and APR 5 maps the driver. Therefore, a 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
words.
The virtual to physical mapping of a P/OS system is

shown

Figure

1-1.

* Active Page Register is a term referring to the Memory Management
register pair (Page Address Register (PAR) and Page Descriptor
Register (PDR).) Refer to the Professional 300 Series Technical Manual
for information on hardware mapping and memory management. Refer to
the RSXIIM-Plus and Micro/RSX Task Builder Manual for a description of
mapping and APR assignments by software.
1-3

SERVICE ROUTINES

Physical Memory
Address Space
1/0 Page

Virtual
Kernel
Space

32K Words

APR 7

Privileged Task
or
Driver

-- - - APR 5

28K Words

20K Words

Dynamic Storage
Region

APR 1
4K Words

APR 0
OK Words

System Resident
1/0 Data Base
Executive
Code

VECTORS

Figure 1-1:

Virtual to Physical Mapping for the Executive

Virtual addresses 20K through 28K words (APR 5 and APR 6) are reserved
to map 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) map the I/O page.

1-4

SERVICE ROUTINES
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. While in system state, a
driver has access to all the Executive service routines to help it
process I/O requests. While in interrupt state, the driver must save
and restore APR 6 (access to APR 6 is unrestricted when the driver is
in system state).
Because of the layout of the Executive and device drivers, many common
functions related to I/O are centralized in the Executive as service
routines. This commonality eliminates the inclusion of repetitive
coding in each and every driver. Coding in each driver is therefore
reduced to handling the specific functions of the device supported.

1.2.2

Driver Contents

A device driver consists of two parts. One part is the executable
instructions 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
established in the driver dispatch table (DDT).
The table contains
addresses of routines in a fixed order 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
request block (KRB), describe the controller of the device being
supported. Because the CTB supplies generic information about the
controller type, only one CTB need exist for each controller type on a
system. The KRB holds information related to a specific controller
and therefore each controller 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 seB is
used mainly to store data (driver context) concerning an operation in
progress on the device unit.
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-5

EXECUTIVE AND DRIVER INTERACTION
1.3

EXECUTIVE AND DRIVER INTERACTION

The Executive 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 preliminary processing, called predriver initiation, is common
for all drivers and eliminates a great deal of code from all drivers.
In performing predriver initiation, the Executive accesses the driver
data structures to assess the legality of the I/O request. For
example, cells in the device control block (DCB) define the functions
that the driver supports.
If the function specified in the I/O
request is not supported by the driver, the Executive need not call
the driver.
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.
Potentially there exist on the system as many driver processes as
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.3 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 instruction), 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
fupction, waits for a completion interrupt and performs any required
data transfers.
It then completes the I/O by specifying I/O status
and requesting another I/O packet. This sequence of execution steps
continues until the I/O queue is empty and the driver process
terminates.
Because a driver may be capable of servicing several I/O requests in
parallel, it is possible that, for a s{ngle 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
1-6

EXECUTIVE AND DRIVER INTERACTION
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,
which identifies a particular controller for a given controller type,
is in the low-order four bits.)
For a driver, the hardware cannot dispatch directly to the interrupt
service routine in the driver because the driver is mapped, outside the
address space of the Executive. Therefore, some code in the Executive
must initially handle the interrupt, load the mapping context of the
driver, and dispatch to the proper driver. This code resides in the
Executive in a structure called an interrupt control block (ICB).
Figure 1-2 shows this mechanism. A common Executive coroutine, called
interrupt save ($INTSI) is called from the ICB. The $INTSI coroutine
saves two registers, R4 and R5, which are thereafter free for the
driver to use. These registers are typically used by drivers to hold
addresses of the data blocks containing unit status and control
information, the SCB and UCB.
(Most Executive routines assume these
two registers hold pointers to the two structures.
If the driver
needs to use more registers, it saves them on the stack and restores
them when it finishes.) Kernel APR 5 is then saved and the driver is
mapped through APR 5 and called at the interrupt entry point. When
the interrupt save coroutine 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.
The driver 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 may execute a RETURN instruction to transfer control back to the
coroutine which gives control of the CPU to the next process.*

* An Executive interrupt exit routine, $INTXT, exists to standardize
the way a driver exits from an interrupt. This routine is executed by
the $INTSI coroutine.
Therefore, interrupt exit processing
is
effected via the "RTS PC" (RETURN) instruction.
1-7

EXECUTIVE AND DRIVER INTERACTION
Thus, the ICB actually contains a JSR instruction to an Executive
interrupt save routine ($INTSI) that performs the following:
o

Save R4 and R5

Save the Kernel mapping (APR 5)

Load APR 5 to map the driver

Transfer control to the driver via a JSR instruction

Restore the mapping after return from the driver

Perform interrupt exit processing

Restore R4 and R5

Return from interrupt

Thus, the interrupt vector for a controller
points to an ICB rather than to the driver.

CONTROLLER
NUMBER

serviced

driver

INTERRUPT
CONTROL
BLOCK
(ICB)

INTERRUPT
VECTOR

DRIVER

ZK-247-81

Figure 1-2:

Interrupt Dispatching for a Driver

The ICB conceptually 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 controller index
(controller number #2), the executive interrupt service routine first
multiplies the controller within group number that was in the low 4
bits of the PS by two. The group number byte in the ICB is then added
to this number.
1-8

EXECUTIVE AND DRIVER INTERACTION
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. The interrupt service routine in the driver
uses the controller index passed in R4 to index a table in the CTB and
to access the proper KRB. From the KRB, the UCB (via K.OWN) may be
determined to access the proper unit data and context.
For those
devices that have a static one-to-one static relationship between a
controller and a perticular UCB, the controller index may be used to
index a table of UCB addresses within the driver.
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.3.3

Interrupt Servicing and Fork Process

A driver handling an interrupt and operating at the partially
interruptable level may need to (1) access structures in its data base
or (2) call centralized Executive service routines 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 coordinate access to the data
structures shared among the processes and the Executive.
The mechanism that coordinates access to the shared structures is
called the fork process. An Executive routine, called fork ($FORK),
causes the driver process to be placed in a queue of processes waiting
for access to the shared data structures, to run at processor priority
level 0, and to be completely interruptable.*
A driver must therefore call the fork routine before it calls any
other Executive service routine (except for $INTSI), or before it
accesses any device-specific (nonprivate) structures in its data base.
If a driver does not follow this protocol, it will corrupt the system
data base and lead to a system crash.
A driver that

calls the fork routine requests the Executive to
transform it into a fork process. The routine saves a snapshot of the

* 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 the fork mechanism is to preserve the response time of the
system and not lock out interrupts from lower-priority levels.
1-9

EXECUTIVE AND DRIVER INTERACTION
process in a fork block. The snapshot is the context of the driver
process--the PC of the process and the contents of R4 and R5. The
fork block itself can (and usually does) reside 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 list.
When the driver calls $FORK, the CPU priority is lowered to 0, which
allows other interrupts to be serviced.
When there are no more
pending 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 list. The Executive restores the saved context of the process
from the SCB and returns control to the driver at the statement
immediately following the call to the fork routine.
The process is
unaware 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
eligible to run and access the data structures. Thus, the fork
mechanism allows both controlled access to the common data structures
and sufficient time to process an interrupt without locking up the
system.
The status of a fork process lies between an interrupting routine and
a task requesting system resources. This is known as "system state."
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 user task registers and
cannot be interrupted by a fork process, a fork process can use all
registers.
The fork processes are completely interruptable. Tasks
run only when the fork list is empty.
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

* The stack must be restored to its state on
calling $FORK.
Therefore, it cannot be
context.
1-10

interrupt entry before
used to pass additional

EXECUTIVE AND DRIVER INTERACTION
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 complete~ 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 system state.
Between the time that a driver process calls $FORK and the Executive
starts the process at system state, 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 system state. If the driver does not ensure against
unexpected interrupts, it may double fork as described above. As a
result of the double fork, the system will bugcheck (crash) with an
lOT trap as a result of a failed sanity check while queuing the
forkblock. A common protocol used by DIGITAL device drivers is to
clear the saved PC in the forkblock immediately following a fork, and
to test this work before forking.
If the word is non-zero, it is not
possible to call $FORK.
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
unexpected interrupts from these devices via an RT1 instruction.

1.4

ADVANCED DRIVER FEATURES

This section introduces optional features so you can better understand
the structures and concepts described in the remainder of the manual.

1-11

ADVANCED DRIVER FEATURES
1.4.1

Overlapped Seek 1/0

Some disk devices allow multiple device units attached to the same
controller
to execute operations in parallel.
This is called
overlapped seek support and is a software option designed to take
advantage of a hardware feature found in most advanced disk drives and
controllers. This feature allows any or all drives to be attached to
the same controller, allowing this functionality to execute a seek
function simultaneously. Each unit may perform a seek operation
independent of what another unit may be doing. Only one data transfer
can occur at anyone time. Some types of drives allow seek functions
to overlap a data transfer function, whereas other types do not.
The increased 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 interrupt. The controller reports the physical unit number of
the
interrupting
unit.
A controller interrupt 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 transfer can be in progress at
anyone time. Most hardware defers seek termination interrupts until
the current data transfer is complete.
To handle interrupts for a device that supports overlapped seek
operations, a device controller-specific interrupt service routine
must be built into the driver to examine the device registers in order
to determine whether the interrupt was initiated by the controller or
the drive unit. Using the controller index on interrupt entry, the
routine uses this as an offset into a table of addresses in a
structure (called the controller table or CTB) in the I/O data base.
The routine accesses the table to determine the address of the I/O
data structure of the interrupt controller (called the controller
request block or KRB) that generated the interrupt. Accessing the KRB
yields the address of the CSR of that controller and having the CSR
address allows the routine to examine the device registers.
If the 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
UCB). The routine can then determine the address of the driver
dispatch table and transfer control to the driver.

1-12

ADVANCED DRIVER FEATURES
If a device unit initiated the interrupt, the
routine retrieves its
unit number from the device registers.
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

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

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

1-13

ADVANCED DRIVER FEATURES
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.
For this
reason,
it may be difficult to make use of the
executiv~'s standard driver timeout facility.
Clock queue entries are
suggested.
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.

1.4.4

Buffered

I~put

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 the 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
al'located 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 driver 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 not checkpointable,
buffered I/O is not
desirable.
$TSTBF returns to the driver and indicates whether
buffered I/O can be performed.

1-14

ADVANCED DRIVER FEATURES
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 task for checkpointing and shuffling.
If the task is currently
blocked, the task state is transformed into a
"stopfor" state until
the task is unblocked, buffered I/O completes, or both.
Checkpointing
the task is subject to the normal
requirements of an active or
"stopfor" state as described in the P/OS System 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
necessary, unstops the task. When the task is active again, a routine
($FINBF) in the Executive module SYSXT notices the outstanding AST and
processes it.
(If the request is for input, the routine copies the
buffered 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 complet~s the processing.

1.5

OVERVIEW OF INCORPORATING A USER-WRITTEN DRIVER INTO PIOS

A callable system service called PROLOD,
located in the POSSUM
library,
is responsible for loading and unloading a driver.
When
loading,
PROLOD establishes the linkage between the data
base
structures in the system device tables and the driver code being
loaded. When unloading, PROLOD removes the driver's code from memory
(although PROLOD removes a driver, it does not remove a data base).
To incorporate a user-written driver into P/OS, you first create two
modules,
one in which you define the data base and the other in which
you include the driver code itself.
You must supply in your code the
global symbols that PROLOD needs.
PROLOD also loads the driver's data base.
It reads the driver symbol
definition file
to find the start and end of the data base in the
driver image.
(Thus, you must have defined its start and end in the
data base source code.) Knowing the start and end, PROLOD reads the
data base from the driver image.
It then 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, PROLOD performs
many consistency and validity checks on the data base being loaded.

1-15

OVERVIEW OF INCORPORATING A USER-WRITTEN DRIVER INTO PIOS
You must build both of the following:
1.

A single image (a .TSK file without a header) containing the
driver code module followed by the driver data base module
(see Section 5.1.3).

A symbol definition (.STB) file that PROLOD requires to
critical data base and driver locations.

find

You will link the driver image to the Executive version under which
the driver will run. However, the driver image will be separate from
the Executive image. PROLOD 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.

1-16

CHAPTER 2
DEVICE DRIVER 1/0 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,
thei r
functionality
The precise

1/0 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 within the system. This unique name allows PROLOD to
find the correct CTB for the controller type.

* Drivers that are not associated with hardware devices (such as in
memory disk or pipe driver) do not need a CTB or KRB. DCBs, SCBs, and
UCBs are a sufficient database.
2-1

I/O STRUCTURES
Any user-written driver data base must have its own CTB.
The
user-created controller table will also be linked into the system CTB
list, if necessary.
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 controller-specific or hardware-specific information and
accesses the correct information for a unit which its associated
controller owns. One KRB exists for each device controller of a given
type in the configuration. It stores such data as the the device CSR
and vector addresses, the slot number, the interrupt controller CSR
address, and controller's status.
In a configuration where a device controller allows only one operation
at a time, the KRB is combined 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
environment, 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
independent unit context. Therefore, each unit capable of operating
independently 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
t~me.
The KRB 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, it
may be necessary 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

* See footnote on page 2-1.
2-2

I/O STRUCTURES
blocks for driver processes awaiting controller access. The queue is
the means by ~hich 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 or multiple simultaneous data
transfers for each physical unit attached to the controller (comm.
multiplexers).
The KRB 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 logical device
type.
(Note that the logical device type is not the same as the
physical device type. )
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 d~ta, the
address of the driver dispatch table, 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 DCB must be of
equal length.
(The UCB length is stored in the device control block
to calculate the offset to a particular UCB in the concatenated set of
UCBs described by the DCB's logical unit numbers.) This condition
2-3

I/O STRUCTURES
allows
the
UCB
to
contain
varying
amounts
of
device-independent data for different types of devices.

unit-

and

A UCB, one of which exists for each device unit, -enables a driver to
access most of the other structures in the I/O environment. 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 both 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, and
unit status; and the address for the controller request block
(KRB)
representing the device controller (if the device has a controller).
The Exe~utive accesses the SCB to set up an I/O request,
to store
context while a
request is in progress, and to post results and
read
status. When the driver accesses the SCB,
it is usually for
access only.
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 a time,
and there is no
need to store context for more than one unit at a time.
There is also
no need for a physically separate controller request block
(KRB)
to
separate controller information from operation state information.
Therefore, the driver data base contains the required KRB cells in the
status control block since the KRB and SCB overlap.
If the controller allows parallel operations, there must be one seB to
store operation state information for each unit capable of operating
independently on the controller.
In such a configuration, a cell in
each SCB points to the KRB of the controller to which the units are
connected.

2-4

I/O STRUCTURES
Certain operations, such as data transfers, could require exclusive
use of a controller. A controller can be requested for this purpose
using the routines located in the MDSUB module of the Executive (the
microfiche distributed with the Tool Kit contains the MDSUB listing).
If the device controller can support unqualified parallel operations
to multiple units, the driver can use $GSPKT and $IOFIN, and can
maintain its own unit busy state internally.
Being capable of unqualified parallel operations
controller can handle any operations in parallel.

2.2

means

that

the

DRIVER DISPATCH TABLE (DDT)

The driver dispatch table* 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 in an interrupt control block.
Every driver has four conventional entry points as follows:
o

I/O initiation

cancel I/O

device timeout

device powerfail

Two more entry points are added for controller and
off-line status changes:
o

KRB status change

UCB 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 addi tional entry points that have

been

added

for

the

* The DDT is not a structure in the strict sense of the word 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-5

DRIVER DISPATCH TABLE (DDT)
advanced
driver
processing:

2.2.1

feature

buffered

Deallocate buffers (buffered I/O)

Send next command (FDX TTDRV)

I/O

and

terminal

driver

1/0 Initiation

The Executiv~ transfers control to this entry point to inform the
driver that work for it is waiting to be done. To reduce 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 entry point.
When the driver receives control at its I/O initiation entry point, RS
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 does either of the following*:
o

It returns information concerning the dequeued packet to be
processed and information needed to gain access to the unit's
data structures

It causes the driver to dismiss the initiation request,
because the $GTPKT routine processed the request on behalf of
the driver.
(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
issues a command to the controller hardware, which
physically
initiates the I/O operation.
Typically a driver is called at this entry point after an I/O packet
has been inserted into 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.

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

process,

DRIVER DISPATCH TABLE (DDT)
2.2.2

Cancel 1/0

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, or the Executive (on behalf of an exiting task), must
terminate I/O.
When such a termination becomes necessary, a task
issues an IO.KIL Executive QIO request and the Executive relays the
request to the driver by calling the driver at its cancel entry point.
Cancel requests are not queued and have no associated I/O packet.
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 also 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.
(For instance, the driver may need to clean up
data structures created during pre-initiation processing (UC.QUE=l)
and has "hidden" the I/O packet listhead in some other structure).

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
entry point. Using this facility, a driver can wait for an interrupt
but need not hang if the interrupt never occurs.
Thus, no driver
should ever stall on a request because a hardware failure prevented an
expected interrupt from happening.
NOTE

Extreme caution must be exercised to avoid completing
an I/O request twice. It can happen once for timeout,
and again when a pending forked process becomes active
and completes I/O again.

2.2.4

Device Power Failure

The Executive calls the power
completion of loading.

failure

2-7

entry

point

upon

successful

DRIVER DISPATCH TABLE (DDT)
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.

2.2.6

Device Interrupt Addresses

Control passes to a driver's interrupt service routine 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.
You specify the interrupt addresses 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.

2.3

TYPICAL CONTROL RELATIONSHIPS

This section presents different arrangements of the control structures
that are found in P/OS. The section concentrates on the 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.
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 ~ontroller type.
Multiple-device control
blocks for a single device type reflect the capability to handle
varying 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 device unit combination on the same controller (unit operation in
parallel).

2-8

TYPICAL CONTROL RELATIONSHIPS
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 Figure 2-1.
The arrangement could represent an RXSO controller
with dual drives.
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.

DCB
List
~

CTB

i I
-

List

i I
CTB

DCB

KRB

UCB

SCB
I

UCB

ZK-249-81

Figure 2-1:

Multiple Units per Controller, Serial Unit Operation

2-9

TYPICAL CONTROL RELATIONSHIPS
The status control block (SCS) and controller request block (KRS)
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 (UCS) describes each unit attached to the
controller. The UCSs are associated with the SCS, which contains the
context of the operation currently in progress.

2.3.2

Multiple Controllers, Single Unit per Controller

Another typical conventional arrangement of
structures
for
a
user-written driver is shown in Figure 2-2, which could represent two
Winchester controllers, one with an RDSO and the other with an RDS1
attached.
It represents the simplest case of driver processing.
Figure 2-1 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 sca is necessary to store the
context of the unit operation. The UCS points to the SCS, which in
turn points to the KRS of the unit's controller. Secause the system
must handle interrupts from multiple controllers, the controller table
points to the KRS of each controller present.

2.3.3

Parallel Unit Operation

Some devices allow multiple units to have operations in progress at
the same time.
For example, a controller could allow seek operations
to overlap data operations.
Figure 2-3 shows the arrangement needed
in the software structures to support parallel operations on one
controller.
T.wo 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 context. Therefore, for each unit (and each unit control block)
there is a separate status control block.
Second, because interrupts
can come 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 fo~ the unit generating an interrupt.

2-10

TYPICAL CONTROL RELATIONSHIPS
DCB

List

----

CTB

t I

List

t I
CTB

DCB

-KRB

----- UCB
-

SCB

UCB

KRB

SCB
ZK-2S0-81

Figure 2-2:

Multiple Controllers, Single Unit per Controller

,......-.
CTB

DCB

...

-UCB

----- seB
--....
~

KRB

:----

UCB

SCB
UCB
Table
ZK-2S1-81

Figure 2-3:

Parallel Unit Operation (Overlapped Seek)

2-11

OVERVIEW OF DATA STRUCTURE RELATIONSHIPS
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 I/O
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.
This section should be used with Section 2.3 to understand the general
structural concepts.
For example, Section 2.3 describes various
arrangements of unit control, status control, and controller request
blocks based on hardware functions the software structures support.
This section 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-4, 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 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
services such as PROLOD reference the data in the PCB. A
driver is not concerned with the PCB.

2-12

OVERVIEW OF DATA STRUCTURE RELATIONSHIPS
3.

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.
(In fact, it may
not be memory resident.) The task header is in physical
memory immediately before the task region when the task's
"task region" is resident in memory.
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
contiguous area, access to all the UCBs related to that DCB
is possible. This arrangement allows software to access all
related unit information for a device type.
A DeB 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 request.

Each unit control block contains a pointer back to its
related DCB.
This backpointer allows the Executive QIO
directive to preprocess an I/O request and possibly call the
driver (through the pointer to the driver dispatch table).
Associated with each ueB is a status control block. The seB
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.

2-13

POINTER TO

DEVICE VECTOR

1\1 I::: J\ 1

LINK TO
FIRST ICB

DRIVER CODE

ut..o

ICB

""'"
(l)
DDT

I\)
I

A
$DEVHD

(')

"'0

-0

(f)

(2)

-.J

- CD
(J)

N
I

P
,j::>,.

r--

I
I
I
I/O PACKETS
I/O QUEUE

0
L

0
0

I
DCB

DCB

( l)

r-----------,

UCB

FORKBLOCK
SCB

""'"

(l)

(f)

!J:oI

t-3

!J:oI

en
e---

rll-

KRB

FCB
UCB TABLE

(INDEXj

t-3

()

t-3

t"l1
VCB
MOUNTED
VOLUME

@
L....-...-.

FORKBLOCKfSCB

KRB

t"l1
t'1
!J:oI

f---

t-3
H

TASK
HEADER
LUT

t"l1

Current
I/O
Packet

UCB

t"l1
H

CTB

TCB OF
ATTACHED
TASK

o
<:
<:

KRB TABLE

TCB OF
ACP

CTB

$FRKHD

--t--l

""'"
c:

I
I
I
I
I

~----------

LOADABLE
DRIVER
PCB

$CTLST

LUT ENTRY
1""- -

t- -

KRB TABLE

UCB TABLE

rr-

I"tJ

WB
(TASK)

(VOLUME)

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

Z
::t:

en
H

@
NOTE

°1

FCB
(TASK)

OVERVIEW OF DATA STRUCTURE RELATIONSHIPS
7.

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 primary pool). The Executive connects the packets by a
pointer in each packet to form a linked rist 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.
Normally, 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.*
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.
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 processing
restores the proper context from the fork block.
The fork blocks for pending driver processes are connected in
a singly-linked list,
the head of which is in a location

* Normally, the driver does not directly manipulate the I/O queue.
An
exception 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
information on queuing of I/O packets to the driver,
refer to the
description of the UC.QUE bit in Section 4.4.4.

2-15

OVERVIEW OF DATA STRUCTURE RELATIONSHIPS
($FRKHD)
in the Executive region.
Generally,
the fork
processing routines link a fork 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 or this VBN to LBN
conversion.

11.

The driver dispatch table (DDT) is part of the driver code
and is the means by which the executive calls 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 KRB table in the CTB 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 driver determines the
correct KRB by indexing the CTB with the controller index.
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 has 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.
(For example,
see DZDRV.MAC
interrupt "B", door open, processing.)
To support multiple parallel unit operations,
the KRB also
contains a queue to regulate controller access.
This queue,
known as the controller request queue,
is a list of fork
blocks for driver processes that have requested and have been
denied immediate access to the controller.
If the driver
requests access to a controller and the controller is busy,
the Executive forces the driver to wait for access by placing
2-16

OVERVIEW OF DATA STRUCTURE RELATIONSHIPS
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 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
(data
transfer).
The KRB controller request queue listhead consists of 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 will be linked into the list of systemdefined CTBs. This list is the mechanism by which system
routines 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 veB connect to the file control block
(FCB) and window block (WB). The FeB 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 FeB. These linkages aid in keeping file access
time to a minimum. A conventional driver never accesses any
of these structures.

2-17

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 P/OS, 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
processes.

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

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.

3-1

FLOW OF AN I/O REQUEST

3.1.1

The only I/O request in the
under discussion.

system

the

sample

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
at a time.

single

request

operation

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.

3-2

FLOW OF AN I/O REQUEST
4.

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.

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 (default if not control, no-op, or ACP)

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

3-3

FLOW OF AN I/O REQUEST
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 addre~s 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.5 for a description of the
UC.QUE bit.)

3.1.2

Driver Processing

Request work
The Executive passes control to the driver by using the
driver's initiation entry point for each new I/O request.
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.

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.

3-4

FLOW OF AN I/O REQUEST
3.

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.
According to the protocol, the
driver may process the interrupt at priority 7,
at the
priority of the interrupting device, or at fork level.
If
the processing of the I/O request associated with the
interrupt is still incomplete, the driver initiates further
I/O on the device (step 9). When the processing of an I/O
request is complete, the driver calls $IODON.

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 IOS8 and event flag,
if specified,
are
updated, and $IODON returns to the driver.
The driver
branches to its initiation entry point and looks for more
work (step 1). This procedure is followed until the driver
cannot obtain work; then the driver returns to its caller.
Eventually, the processor receives a ready-to-run task that
issues a QIO directive, starting the I/O flow allover again.

3.2

EXECUTIVE SERVICES AVAILABLE TO A DRIVER

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

3.2.1

Get Packet ($GTPKT)

Create Fork Process ($FORK)

I/O Done ($IODON or $IOALT)

emphasis

because

Get Packet ($G'TPKT)

The Executive, after it queues an I/O Packet,

3-5

calls

the

appropriate

EXECUTIVE SERVICES AVAILABLE TO A DRIVER
driver at its I/O initiation entry point. The driver then immediately
calls the Executive routine $GTPKT to obtain work.* If work is
available,
$GTPKT delivers to the driver the highest-priority,
executable I/O Packet in the driver's I/O queue,
and sets the SCB
status to busy.
If the driver's I/O queue is empty 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

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 SCB contains preallocated storage for a
5-word fork block. See Section 4.4.5 for a description of the fork
block.
Section 1.3.3 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.3

1/0 Done ($IODON or $IOAl T)

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

Store status if an rOSB address was specified

Set an event flag if one was requested

Determine whether a checkpoint request can now be honored

Determine whether an AST should be queued

$rODON and $rOALT also declare a significant event, reset the SCB and
device unit status to idle, and release the dynamic storage used by

* 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-6

EXECUTIVE SERVICES AVAILABLE TO A DRIVER

the completed I/O operation.

3-7

CHAPTER 4
PROGRAMMING SPECIFICS FOR WRITING AN 110 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

IIO drivers function as integral components of the PIOS Executive, and
this manual enables you to incorporate IIO 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
identical to those described in
Language Reference Manual. DIGITAL
conventions.

4.1.1

by PIOS system components are
Appendix E of the PDP-11 MACRO-11
urges you to adhere to these

Programming Protocol Summary

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

internal

Registers R4 and R5 are available; any other
be saved and restored.

4-1

conventions

registers

must

PROGRAMMING STANDARDS

4.1.2

Processing at the priority of the interrupting source should
be minimized and kept well under 500 usecs. On Professional
Series hardware, all devices interrupt at processor priority
4 and, as a result, processing at device priority is
equivalent to processing at priority 7 with all pending
interrupts (including the clock) locked out. The interrupt
arbitration described in the "Professional
300
Series
Technical Manual" only addresses which of the interrupts is
subsequently serviced at priority 4 when the processor drops
its priority to o.

Kernel APR 6 mapping
~ervice
routine if
data buffers.

Only a fork process, which by definition is in system state,
may modify a system data base or examine dynamic system data
structures such as the installed task directory (the STD).

A fork process has unrestricted access to APR 6, and RO-R5.

Complex drivers and system processes that require extended
periods
of processing at system state should consider
reforking to allow other system processes' execution time.
These other system processes could, for example, perform
clock-related and I/O completion-related processing.
Care
must be exercised that any additional context is preserved if
required, since only R4, R5 and APR 5 mapping are preserved
across the fork. As always, "double forking" must not occur;
it is avoided by either using an interlock protocol on the
forkblock, or through the use of a separate forkblock
allocated from primary pool.

must be preserved by the interrupt
needed to map additional driver code or

Accessing Driver Data Structures

All the driver data structure elements have symbolic offsets. Because
the physical offset values may vary from one version of the Executive
to another, your user-written driver code should always use the
symbols to access the elements.
Accordingly, your driver code should not step from one structural
element to another (relying on the juxtaposition of data structures
and individual words in a data structure) but should access each
element by symbolic offset. On the other hand, it is a common coding
practice to assume that zero offsets (particularly link pointers such
as D.LNK) will remain zero. This assumption allows the saving of one
word per instruction by substituting an instruction such as MOV
(R3),R3 for MOV D.LNK(R3),R3. DIGITAL recognizes that such practices
4-2

PROGRAMMING STANDARDS
are followed and consequently attempts to keep such offsets zero.

4.2

OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER DATA BASES

You should create the source code for your user-written driver data
base in a file separate from that of the driver code. You assemble
this file to create the driver data base module. If your data base is
in a separate module, it will be linked to the end of the driver 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.
To create the source code, you need to know,
in addition to the
detailed structures, what ordering and labeling are required. These
requirements, though not extensive, are important in linking and
loading your driver data base. The general coding requirements for
driver data bases are described in the following subsections.

4.2.1

General Labeling and Ordering of Data Structures

When creating a data base, you must specify, for the PROLOD
two global labels as follows:

routines,

$xxDAT::

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.

If either or both of these labels are not defined, PROLOD 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 DeB first,
followed by the UCB, the SCB(s), the KRB(s), and the eTB. If you do
not follow this ordering scheme, you must specify the starting
location of the first (or only) DeB as described in Section 4.2.2.

4.2.2

Device Control Block Labeling

When writing a driver data base, the PROLOD routines require either
that the first (or only) DeB be identified by the global label
$xxDCB:: or that the DCB be at the start of the data base.

4-3

OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER DATA BASES

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 contiguous 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 PROLOD routines require this label.
You must assemble a
global symbol of the form $xxCTB in the CTB starting at the first word
in the table of KRB addresses. An ~xample follows.

CTB storage cells ...

. WORD $XXDCB
.BYTE
3
.BYTE
0
$XXCTB: :
. WORD
.WORD
.WORD

KRB1
KRB2
KRB3

iOffset L.DCB in CTB
iL.NUM, where 3 is # of KRBs {controllers
iL.STS, controller status
iStart of table of KRB addresses
;Address of 1st KRB

The symbol $xxCTB (defined globally, where xx
4-4

the

two

character

OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER DATA BASES
driver generic name) is used by PROLOD to find the CTB in your driver
data base image. The value of this symbol (that is, the address)
is
placed into the DDT in the word labeled by xxCTB (no $). The INTSV$
macro references the value of the word in the DDT labeled by xxCTB to
obtain the address (in the CTB) of the table of KRB addresses at
runtime.

4-5

OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER CODE

4.3

OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER CODE

To create the source code to drive a
following steps:

device,

you

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.

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, P/OS provides the macro calls listed in Table 4-1.
The definitions of the system macro calls for drivers are in the
Executive 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
requirements 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,buf,opt

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.

* See Appendix A for Macro definitions.
4-6

OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER CODE

Table 4-1:

Macro Name

System Macro Calls for Driver Code*

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 PROLOD 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

Argument

Meaning

dev

Is the 2-character device mnemonic (used
entry point symbol names such as a
dev=xx) .

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
4-7

to generate
$xxINI where
services

OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER CODE
entry point address the
conventional label $xxINT.

location

If you specify NONE, no interrupt
generated for the controller.

defined

the

entry

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

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

ucbsv

This argument is optional on P/OS systems.
Section
4.3.4 provides guidelines on specifying this argument.
If this argument is non-blank, a table of nctrlr words
in length is generated to contain the controller index
to UCB mapping of a per controller I/O operation in
progress.

new

If present, causes the DDT$ macro to generate the DDT
table that refers to the online reconfiguration entry
points. (See the macro definition of DDT$ in Appendix
A. )

buf

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

opt

Required if the mass storage
queue optimization.

4-8

device

driver

and

supports

OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER CODE
4.3.2

Get Packet Macro Call - GTPKT$

The GTPKT$ 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:
GTPKT$

dev,nctrlr,addr,ucbsv,suc

The description of the arguments appears in Table 4-3.
Table 4-3:

GTPKT$ Macro Call Arguments

Argument

Meaning

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

Strictly speaking, this argument is not needed on P/OS
systems and can not be used directly if a given
controller can support parallel operations on multiple
units simultaneously. If this argument is non-blank,
a table of "nctrlr" words in length is generated to
contain the controller index to UCB mapping of a per
controller I/O operation in progress. 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 that supports a controller type such as the
LP11, 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
4-9

services

OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER CODE
address in the KRB for a device that has only one UCB
per KRB.
If your driver has multiple units attached to the same
controller, you should leave this argument null. The
macro will then generate code to store the UCB address
of the unit to process in the SCB or SCB/KRB.
Note that for non-contiguous SCB/KRB configurations,
the UCB is stored in K.OWN when the controller request
is granted, depending on controller characteristics
(see $RQCNC and $RQCND in MDSUB).
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 INI entry
point, the Executive has loaded R5 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 the
"addr" 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 the driver has an I/O packet to
process by clearing the C bit. Therefore, when the test of the BCS
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 and the GTPKT$ macro listing 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 format of the INTSV$ macro call is as follows:
INTSV$

dev,pri,nctrlr,pswsv,ucbsv

The arguments of the call are described in Table 4-4.
The macro
generates the cod~ to load R5 with the UCB address of the current
controller owner, given the controller index is in R4 (R4 is not
modified by macro).
Note that R5may be zero in case of either an
unexpected interrupt (e.g., no current I/O operation), or an interrupt
4-10

OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER CODE
as a result of a parallel operation on the same controller.
(For
example, an overlapped seek completing after a
data
transfer
completion.) In general, for configurations which support overlap seek
it is the driver's responsibility to differentiate between a transfer
function completion interrupt from a control 'function completion
interrupt.
Table 4-4:

INTSV$ Macro Call Arguments

Argument

Meaning

dev

Is the 2-character device mnemonic.

pri

Is not used.

nctrlr

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

pswsw

Leave this argument null; it has no effect. It is an
anachronism, and must be positionally present if ucbsv
is specified.

ucbsv

Strictly speaking, this argument is not needed on PIOS
systems and can not be used directly if a given
controller can support parallel operations on multiple
units simultaneously. If this argument is non-blank,
a table of "nctrlr" words in length is generated to
contain the controller index to UCB mapping of a per
controller I/O operation in progress.
The macro
generates
code
which uses the controller index
returned in R4 by $INTSI to index into a UCB table to
load the UCB address of the interupting device into
R5.

4.3.4

services

Using the UCBSV Argument in Macro Calls

You can optionally specify the ucbsv argument in calls to the macros
DDT$, GTPKT$, and INTSV$.
This argument allows you to use an
alternative technique to map the controller index to a UCB address.
This provides a simple mechanism for retrieving the UCB when an
expected interrupt occurs.
The argument ucbsv in the DDT$ macro allocates nctrlr words of
storage (one word for each controller that the driver supports) and
labels the first word ucbsv:. This table contains the address of
the unit control block of the interrupting devices for each
4-11

OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER CODE
controller.
The GTPKT$ macro updates
initiation and INTSV$ references this
address.

table entries
at
I/O
table to retrieve the UCB

If you specify the argument ucbsv in the GTPKT$ macro call, it must
be the same label 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 matro uses ucbsv to locate the UCB
address of the interrupting unit, and then generates code to load
the address into RS.

4.3.5

Driver Entry Points for PROLOD

A driver that requires additional initialization and completion
functions can define two entry points by labels of the form $xxLOA
and $xxUNL. Because these two labels ~o 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
NOTE

Drivers should not attempt to access controller
registers at the load entry point. Device access is
only possible after the driver has been called at
its controller online entry point.
PROLOD routines check for the $xxLOA entry point.
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
RS - Address of the unit control block

NOTE

The driver cannot access any device CSRs at this
point because ownership has not been established.
To access device CSRs, wait until the controller is
online.

4-12

OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER CODE
The driver may use all the registers. When you unload the driver,
PROLOD calls it at the $xxUNL entry point with the same conditions.
These two entry points in the driver are independent of the
controller
and unit status change entry points used by the
Executive. That is, the two entry points $xxLOA and $xxUNL are used
for initialization and at driver load and unload time and not at
on-line and off-line status change time. Note that $xxUNL is called
only when all controllers and units are offline. The data base is
not removed, but it is reused on subsequent reloads.

4.4

DRIVER DATA STRUCTURE DETAILS

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

The I/O packet

The DCB

The UCB

The seB

The KRB

The CTB

concern

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

Whether the field
source, and

initialized

4-13

the

data-structure

DRIVER DATA STRUCTURE DETAILS
o

What sort of access the driver
execution

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
and may be read by the driver.

source

code,

<not initialized, read-only>
Either an agent other than the driver establishes this
field, or the driver sets it up once and thereafter
references it read-only.
<not initialized, read-write>
Either the driver or some other agent establishes this
field, and the driver may read it or write over it.
<not initialized, not referenced>
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 1/0 Packet

Figure 4-1 shows the layout of a control function I/O Packet, and
Figure 4-2 shows the layout of a transfer function I/O Packet. Both
are constructed and placed in the driver I/O queue by QIO directive
processing, and 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. 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 classified as:
o

Not referenced,

Read-only, or

Read-write.

I.LNK
Driver access:
4-14

DRIVER DATA STRUCTURE DETAILS
Not referenced.
Description:
Links I/O Packets queued for a driver.
A zero
chain. The listhead is in the seB (S.LHD).

ends

the

I.EFN
Driver access:
Not referenced.
Description:
Contains the event flag number as copied by QIO directive
processing from the requester's DPB. Bit 0<200> indicates
a virtual function.
I.PRI
Driver access:
Not referenced.
Description:
Priority copied from the TCB of the requesting task.

4-15

DRIVER DATA STRUCTURE DETAILS

LPRI
LF.FN

Link to next liD packet

LLNK

}

EFN

PRI

LTCB

TCB address of requester

LLN2

Address of second LUT word

LUCB

Address of redirect UCB

Modifier

Virtual address of liD status block

Relocation bias of 10SB

Real address of 10SB

Virtual address of AST service routine

LFCN

Function code

1.I0SB

I.AST
LPRM

I---

Device
parameters
(control functions)

f--~

P5
P6

LAADA

Attachment Descriptor Pointer

I.AADA+2

Attachment Descriptor Pointer

Figure 4-1:

1/0 Packet Format - Control Function

4-16

DRIVER DATA STRUCTURE DETAILS

LPRI
LEFN

Link to next 1/0 packet

LLNK

}

EFN

PRI

LTCB

TeB address of requester

I.LN2

Address of second LUT word

LUCB

Address of redirect UC8

Modifier

Virtual address of 1/0 status block

Relocation bias of IOS8

Real address of 10SB

Virtual address of AST service routine

Relocation B lAS of buffer

I.FCN

Function code

1.I0SB

I.AST
I.PRM

Displacement of buffer (+140000)
~

P2
~

r--P4
r--P5

Device
parameters
(transfer functions)

-----

LAADA

Attachment Descriptor Pointer

I.AADA+2

Attachment Descriptor Pointer

P1 assumed to be buffer virtual address
P2 assumed to be buffer size in bytes

Figure 4-2:

I/O Packet Format - Transfer Function

4-17

DRIVER DATA STRUCTURE DETAILS
I.TCB
Driver access:
Not referenced usually.

Referenced at I/O cancel.

Description:
TCB address of the requesting task.
I.LN2
Driver 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, if
even. Also, for virtual functions, if even, the task
region, and consequently the header, was locked in memory
by incrementing the appropriate I/O counts. For open files
on file-structured devices, this word contains the address
of the Window Block.
If odd, it is the window block
pointer; otherwise zero.
I.UCB
Driver access:
Not
referenced
by
conventional
driver;
frequently
referenced by drivers that use $GSPKT and maintain parallel
active unit context UCBs rather that the SCBs,
and
therefore have a "many to one" UCB to SCB configuration.
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 a Redirect command.
The
field is referenced by the $GTPKT routine.
I.FCN
Driver access:
Read-only~

Description:

4-18

DRIVER DATA STRUCTURE DETAILS
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
(subfunction)
bits.
During predriver initiation the
Executive compares the function code wit~ a function mask
value in the DCB.
The driver interprets the modifier
(subfunction) bits.
I.IOSB
Driver access:
Not referenced.
Do not touch.
Driver specifies status at
I/O completion in registers to $IODON or $IOFIN.
The
region containing the IOSB is not guaranteed to be memory
resident, except at predriver initiation time (see UC.QUE).
Description:
I.IOSB contains the virtual address of the I/O Status Block
(IOSB), if even, or zero if one was not specified.
I.IOSB+2 and I.IOSB+4 contain the address doubleword for
the IOSB if I.IOSB is even and nonzero (see Section 7.4 for
a detailed description of the address doubleword.
I.AST
Driver access:
Not referenced.
Description:
Contains the virtual address of the AST service routine to
be executed at I/O completion.
If no address is specified,
the field contains zero.
I.PRM
Driver access:
Read-write.
Description:
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

4-19

DRIVER DATA STRUCTURE DETAILS
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
the I/O function is marked "virtual," 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.
I.AADA
I.AADA+2
Driver access:
Not referenced; maintained by the
to the driver.

Executive

transparently

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

The 010 Directive Parameter Block (DPB)

The QIO DPB is constructed as shown in Figure 4-3. Usually drivers
never access the DPB; the information is supplied here for general
reference.
The,parameters in the DPB have the following meanings:
Length (required):
The length of the DPB, which for the QIO
fixed at 12 words.

directive

always

DIe (required):
Directive Identification Code.
is 1. For QIOW it is 3.
4-20

For

the

QIO

directive,

this

DRIVER DATA STRUCTURE DETAILS
Q.IOFN (required):
The code of the requested I/O function (0 through 31).

Length

ole

UIOFN

Function code

Modifier

O.IOLU

Reserved

LUN

UIOPR/O.IOEF

Priority

EFN

0.IOS8

1/0 status block address

O.IOAE

AST address

O.lOPL +0

f---

+2
+4

Devicedependent
parameters

I---

r--

+10

+12
ZK-255-81

Figure 4-3:

010 Directive Parameter Block (DPB)

Modifier:
Device-dependent modifier bits.
Reserved:
Reserved byte; must not be used.
Q.IOLU (required):
Logical Unit Number.

4-21

DRIVER DATA STRUCTURE DETAILS
Q.IOPR:
Request priority.
Ignored by PIOS but space must be
for IAS compatibility.

allocated

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 0
I/O status byte.
Byte 1
Augmented data supplied by the driver.
Bytes 2 and 3
The contents of these bytes depend on the value of byte O.
If byte 0
1, then these bytes usually contain the
processed byte count.
If byte 0 does not equal 0,
then
the contents are device-dependent.
Q.IOAE (optional):
Address 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:
o

Buffer address

Byte count

Carriage control type

Logical block number

The fields for any optional parameters not specified must be
with zeros.
4-22

the I/O
transfer

filled

DRIVER DATA STRUCTURE DETAILS
4.4.3

The Device Control Block (DCB)

Figure 4-4 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.

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-2S6-81

Figure 4-4:

Device Control Block

The fields* in the DeB are described as follows:
D.LNK (link to next DeB)

* Parenthesized contents following the symbolic offset indicate
value to be initialized in the data base source code.
4-23

the

DRIVER DATA STRUCTURE DETAILS
Driver access:
Initialized, not referenced.
Description:
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.
Description:
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.
Description:
Generic logical device name in ASCII by which device
are mnemonically referenced.

units

D.UNIT (unit number range)
Driver access:
Initialized, not referenced.
Description:
unit number range for the device.
The low-order byte
contains the lowest logical unit number; the high-order
byte contains the highest logical unit number. This range
covers those logical units available to the user for device
assignment. Typically, the lowest number is zero or one,
and
the highest is n-1, where n is the number of

DRIVER DATA STRUCTURE DETAILS
device-units described by the DCB.
D.UCBL (UCB length)
Driver access:
Initialized, not referenced.
D~scription:

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:
Not referenced.
Description:
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.)
D.MSK (driver-specific function masks)
Driver access:
Initialized, not referenced.
Description:
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
nonfile-structured devices.* Four masks, with two words per

* Although no DIGITAL publication describes writing drivers for
file-structured devices (drivers that interface with Fl1ACP), you
could write a disk driver by using a DIGITAL-supplied driver as a

4-25

DRIVER DATA STRUCTURE DETAILS
mask, are described by the
establish for these words:
1.

Legal function mask

Control function mask

No-op function mask

ACP function mask

bit configurations that you

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 0 through 15i 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

o
o

377

iLEGAL FUNCTION MASK CODES 0-15 .
iCONTROL FUNCTION MASK CODES 0-15 .
iNO-OP FUNCTION MASK CODES 0-15 .
iACP FUNCTION MASK CODES 0-15 .
iLEGAL FUNCTION MASK CODES 16.-31 .
iCONTROL FUNCTION MASK CODES 16.-31 .
iNO-OP FUNCTION MASK CODES 16.-31 .
iACP FUNCTION MASK CODES 16.-31 .

The Executive filters the function code
words sequentially as follows:
Legal Function Mask:

4-26

through

the

mask

DRIVER DATA STRUCTURE DETAILS
Legal function values have the corresponding bit position
in this word set to 1. Function codes that are not legal
are rejected by QIO directive processing, which returns
IE.IFC in the I/O status block, provided an IOSB address
was specified.
Control Function Mask:
If any device-dependent data exists in the DPB, and this
data does not require further checking by the 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:
1.

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.

4-27

DRIVER DATA STRUCTURE DETAILS
2.

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). All transfer functions
except IO.WLB and IO.WVB are assumed to require Read and
Write access to the buffer region, and are access checked
accordingly.
By convention, the
first
user-supplied
parameter is the buffer address and the second is the byte
count.
Creating Mask Words:
Creating function mask words involves
steps:

the

following

five

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

Build the Legal Function mask: Check the standard PIOS
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 P/OS system
interpretation. DIGITAL suggests that functions having
an PIOS system counterpart use the PIOS 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?

4-28

DRIVER DATA STRUCTURE DETAILS
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.1 for an example of a
driver that does this.
(Buffer addresses in standard
format
are
automatically
converted
to
Address
Doubleword format.)
Control functions are essentially those functions whose
DPBs do not contain buffer addresses or counts.
4.

Create the No-op Function mask by deciding which legal
functions
are
to
be
no-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.
Description:
Address of the driver's Partition Control Block (PCB). The
driver data base source 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. A driver PCB
describes the partition in which it resides.
The Executive uses D.PCB together with D.DSP (the address
of the driver dispatch table) to determine a driver is in
memory. Zero and nonzero values for these two pointers
have the meanings shown in Figure 4-5.

4-29

DRIVER DATA STRUCTURE DETAILS
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 0 through 15, use the
mask value for a word in the first 4-word group; for bits numbered
16 through 31, use the mask value for a word in the second 4-word
group.

D.DSP:

D.pes:

"'0

:#0

Figure 4-5:

Loadable
driver,
not in
memory

(not
possible)

Loadable
driver,
in memory

D.peB and D.DSP Bit Meanings

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 are used, they must have the standard meaning.
(Refer to the
P/OS System Reference Manual) for a description of standard I/O
functions.) If QIO directive processing encounters a function code
of 3 or 4 and the code is not no-op, QIO assumes that these codes
represent Attach Device and Detach Device, respectively. The other
codes are suggested but not mandatory. You are free to establish
all other function-code values on nonfile-structured
devices.
However, the mask words must still reflect the proper filtering
process.
If you are writing a driver for a file-structured device,
establish the standard function mask values of Table 4-5.

you

must

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

4-30

DRIVER DATA STRUCTURE DETAILS
Table 4-5:

Mask Values for Standard I/O Functions

Bit

Mask
Value

Related
Symbolic

0
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

1
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

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

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

IO.APV

I/O
Function
I Cancel I/O
Write Logical Block
Read Logical Block
Attach Device
Detach Device
General Device Control
General Device Control
General Device Control
Diagnostics
Find File in Directory
Unlock Block
Remove 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
ACP Privileged
Unused

4-31

DRIVER DATA STRUCTURE DETAILS

Table 4-6:

Mask Word Bit Settings for Disk Drives

Bit

o
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

Related Symbolic

P/OS

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

IO.APV

28
29

31
t
c
n
a
sa
sd

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-32

DRIVER DATA STRUCTURE DETAILS

Table 4-7:

Mask Word Bit Settings for Magnetic Tape Drives

Bit

o
1

2
3
4

5
6

P/OS (currently IS.PND)

c
t
t
c
c
c
c
sa
sd
a

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

a
a
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

a
a
a

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

IO.APV

8
9
10
11
12
13
14
15

25
26
27
28
29

31
t
c
n
a
sa
sd

transfer function, bit set only in legal function mask
control function, bit set in legal and control function masks
rio-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-33

DRIVER DATA STRUCTURE DETAILS
Table 4-8:

Mask Word Bit Settings for Unit Record Devices

Bit
0
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

Related Symbolic

PIOS

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

t - transfer function, bit set only in legal function mask
c - control function, bit set in legal and control function masks
n - no-op function, bit set in legal and no-op function masks
a - ACP function, bit set in legal and ACP function masks
sa - special case, bit set only in ACP function mask, but not legal
sd - special case, bit set only if di~gnostic support in system and
driver

4-34

DRIVER DATA STRUCTURE DETAILS
4.4.4

The Unit Control Block (UCB)

Figure 4-6 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* in the UCB are described below:
U.UAB (0)
Driver access:
Initialized, not referenced.
Description:
For terminal UCBs only.

Reserved.

U.MUP
Driver access:
Not initialized, not referenced.
Description:
For terminal UCBs only.
U.LUIC (0<100200»
Driver access:
Initialized, not referenced.
Description:
For terminal ueBs only, and only in multiuser systems:
the
logon UIe 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.
U.OWN ( 0 )
Driver access:
Initialized, not referenced.

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

indicate

the

DRIVER DATA STRUCTURE DETAILS

Description:
The UCB address of the owning terminal for allocated devices.

U.UAB1

- --

~~-

U.MUp1
U.LUIC 1

reserved

-1

reserved

- reserved
--

10
6

-4

U.OWN

Owning terminal UCB address

-2

U.DCB

Back pointer to DCB

U.RED

Redirect UCB pointer

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

}
}

Unit status

Control flags

Unit status

Physical unit no.

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

~------

U.UCBX 2

- - - - - - -- --

to the UCB

:;;;~~~ in s~onda~ ~ ::

storage

1. This offset appears only for terminal devices (that is. devices that have DV.TTY set)
2. This offset appears only for those devices that have DV.MSO set.

Figure 4-6:

Unit Control Block

4-36

DRIVER DATA STRUCTURE DETAILS
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.
Description:
Contains a pointer to the unit control block to which this
device-unit has been redirected.
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.
Description:
U.CTL and the function mask words in the device control block
control QIO directive processing.
Figure 4-7 shows the
layout of the 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.
If this bit is 0, then byte alignment of data buffers is
allowed (for example, a communications driver).
If UC.ALG is
1, then buffers must be word-aligned (for example,
a disk
driver).

4-37

DRIVER DATA STRUCTURE DETAILS

U.STS

U.CTL

}UC.LGH. Buffer size mask bits for transfer length
UC. K I L . Uncondi tional cancel I/O (1 =yes)
UC.ATT . Attach/detach notification (1 =yes)
UC.PWF· Unconditional call at powerfail (1=yes)
UC.QUE· Queue to driver bit (1=yes)
UC.NPR· NPR device bit (1=yes)
UC.ALG· Alignment (byte or word)(1=no)
ZK·258·81

Figure 4-7:

Unit Control Byte

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.
When the need
exists,
the
most common use of UC.ATT is for event
notification without outstanding I/O.
Attachment coupled
with UC.ATT provides an I/O rundown operation (IO.DET) to
occur so that the driver can remove this context when the
issuing task exits - gracefully or otherwise.
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.

4-38

DRIVER DATA STRUCTURE DETAILS
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.1 for an example of a driver that does this.
Use $CKBFR, $CKBFB, OR $CKBFW rather than $ACHRO, $ACHKB,
$ACHKW, since the later routines do not increment region and
ACB I/O counts.
UC.PWF - Unconditional calIon loading driver bit.
If set and the unit is on-line, the driver is always to be
called when driver is loaded. Driver may then ignore unit
and controller status changes by simply performing a RETURN
instruction.
The driver, however, can never be unloaded
without reboot if these entry points are ignored for the
online to offline transition.
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). It is normally cleared.
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.
U.STS (0)
Driver access:

4-39

DRIVER DATA STRUCTURE DETAILS
Initialized, not referenced.
Description:
This byte contains device-independent status information.
Refer to the UCBDF$ macro definition in Appendix A. Figure
4-8 shows the layout of the unit status byte.

U.ST2
15

I I

U.UNIT

I I ar
I
I
I

o
J Unused bits are reserved

_ _........---il...-.&.-................I...-.A.---L._ _ _ _ _ _ _ _ _ _ _ _ _

• for system use and expansion.

US.OFL - Unit offline (l=yes)
US. RED - Unit redirectable (l=no)
US.PUB - Unit is public device (1=no)
US.UMD - Unit attached for diagnostic s (l=yes)
US.PDF - Privileged diagnostic functions only (l=yes)
US.MUN - clusterdevice (l=yes)
US.TRN - unit transition has accured (l=yes)
L - -_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ ._ _ _ _ _ . US.SIO - stall I/O to unit (l=yes)

Figure 4-8:

Unit Status Byte

US.MDM, US.MNT, Us.vv and US. FOR apply only
devices.* The bit meanings are as follows:

mountable

US.BSY
If set, device-unit is busy.
US.MNT
If set, volume is not mounted.
US.FOR
If set, volume is mounted foreign.
US.MDM

* If your user-written driver services a mountable device,
Section 4.5.7 for information on volume valid processing.
4-40

refer

DRIVER DATA STRUCTURE DETAILS
If set, device is marked for dismount.
US.vv
If set, volume is valid from a software viewpoint.
U.UNIT (unit number)
D~iver

access:

Initialized, read-only.
Description:
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
zero.
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.
Description:
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-9.
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.
US.RED=2

4-41

the

DRIVER DATA STRUCTURE DETAILS
If set, the device cannot be redirected.
US.PUB=4
If set, the device is a public device.
US.UMD=10
If set, the device is attached for diagnostics.
US.PDF=20
If set, this unit can be used
function only.

for

privileged

diagnostic

US.TRN=100
If set, unit volume status change in progress.
US.SIO=200
If set, I/O is stalled typically until volume is reverified.

U.CTL

U.STS

8I7

---- ---

I I I I I I I I I

I Unused hits

•

are reserved
for system use and expansion .

US.MDM - Marked for dismount (1 yes)
US.FOR - Mounted as foreign volume (O=yes)
US.MNT - Volume is mounted (1- no)
US.BSY - Device-unit busy (1 ~oyes)

Figure 4-9:

Unit Status Extension 2

U.CWl (device-specific characteristics)
Driver access:
Initialized, not referenced.
Description:

4-42

DRIVER DATA STRUCTURE DETAILS
The first of a 4-word contiguous
cluster
of
device
characteristics
information.
U.CWl
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.CWl is defined as follows.
(If a bit is set to 1,
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 DV.SQD=40
Sequential device
DV.MSD=100
Mass Storage device
DV.UMD=200
Device supports user-mode diagnostics
DV.EXT=400
unit is on an extended 22-bit controller

4-43

DRIVER DATA STRUCTURE DETAILS
DV.SWL=1000
Unit is software write-locked
DV.ISP=2000
Input spooled device
DV.OSP=4000
output spooled device
DV.PSE=10000
Pseudo device.
If this bit is set, the UCS does
past the U.CWi offset.

not

extend

for

working

DV.COM=20000
Device mountable as a communications channel
DV.Fii=40000
Device mountable as a FILES-i1 device
DV.MNT=100000
Device mountable*
U.CW2 (device-specific characteristics)
Driver access:
Initialized, read-write.
Description:
Specific to a given device
storage or constants}.**

driver

(available

U.CW3 (device-specific characteristics)
Driver access:
Initialized, read-write.

* If your user-written driver services a mountable device,
refer to
Section
4.5.7
for information on volume valid processing and
privileged ACP functions.
4-44

DRIVER DATA STRUCTURE DETAILS
Description:
Specific to a given device
storage or constants).*

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 IBUF keyword). The value in
this word effects FCS, RMS, and many utility programs.
U.SCB (SCB pointer)
Driver access:
Initialized, read-only.
Description:
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.
** 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.

* 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 glvlng the total number of blocks on the
device. Place the high-order bits in the low-order byte ofU.CW2 and
the low-order bits in U.CW3.
4-45

DRIVER DATA STRUCTURE DETAILS
Description:
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.
Description:
U.BUF labels two consecutive words that
serve
as
a
communication region between $GTPKT and the driver. If a
nontransfer function is indicated (in D.MSK), then U.BUF,
U.BUF+2, and U.CNT receive the first 3 parameter words from
the I/O Packet.
For transfer operations, the initial format of these two
words depends on the setting of UC.NPR in U.CTL. The driver
does not format the words; all formatting is completed before
the driver receives control. The format is determined by the
UC.NPR bit, which is set for an NPR device and reset for a
program-transfer device.
The format for program-transfer devices is an
address
doubleword identically formatted to I.IOSB+2 and I.IOSB+4.
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.
The details of the construction
appear in Chapter 7.

the

Address

Doubleword

U.CNT (reserve one word of storage)
Driver access:
Not initialized, read-write.
Description:
Contains the byte count of the buffer described by U.BUF.
The driver uses this field in constructing the actual device
request.

4-46

DRIVER DATA STRUCTURE DETAILS
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=l).

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

1
1
1

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)

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

4-47

DRIVER DATA STRUCTURE DETAILS

S.LHD

Input/Output
Queue Listhead

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

r
I-

•
•
•
KRB Address 0

KRB Address 1

- - - -•

r
tL
Figure 4-10:

•
•
KRB Address n
0

-I
J

Status Control Block

4-48

DRIVER DATA STRUCTURE DETAILS
The fields* in the

sca are described as follows:

S.LHD (first word equals zero; second word points to first)
Driver access:
Initialized, not referenced.
Description:
Two words forming the I/O queue listhead.
The first word
points to the first I/O Packet in the queue, and the second
word points to the last I/O Packet ln the queue.
If the
queue is empty, the first word is zero, and the second word
points to the first word.
S.FRK (reserve four words of storage)
Driver access:
Initialize words to zero, not referenced.
Description:
The four words starting at S.FRK are used for fork-block
storage if and when the driver deems it necessary to
establish itself as a Fork process.
Fork-block storage
preserves the state of the driver, which is restored when the
driver regains control at fork level.
This
area
is
automatically used if the driver calls $FORK.
S.KS5 (0)
Driver access:
Initialized, not referenced.
Description:
This word contains the contents of KISAR5 necessary to
correctly alter the Executive mapping to reach the driver for
this unit. It is set by PROLOD, and whenever a fork block is
de queued and executed, this word is unconditionally jammed
into KISAR5. ADJACENCY WITH THE FORK BLOCK IS ASSUMED!
S.PKT (reserve one word of storage)

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

indicate

the

DRIVER DATA STRUCTURE DETAILS
Driver access:
Not initialized, read-only.
Desqription:
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)
Driver access:
Not initialized, read-write.
Description:
P/OS 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 (initial timeout count)
Driver access:
Initialized, read-only.
Description:
Contains the initial timeout value that the driver
into S.CTM to begin device timeout.

4-50

can

load

DRIVER DATA STRUCTURE DETAILS
S. STS (0)
Driver access:
Initialized, not referenced.
Description:
Establishes the controller as busy/not busy (nonzero/zero).
This byte is the interlock mechanism for marking a driver as
busy for a specific controller. The byte is tested and set
by $GTPKT and reset by $IODON.
S.ST3 (driver-specific status byte)
Driver access:
Initialized, referenced by driver for synchronization.
Description:
This status byte is reserved for driver-specific status bits
concerning driver-executive or driver-driver communication.
Figure 4-11 shows the layout of this byte.

(S.STS)

S.ST3

8 I

I I I I I I I I I
~
j

Figure 4-11:

I
S3 •DRL S3 • NRL S3.SIP 83.ATN S3 • SIN 83. SPA S3. SPB 83.0PT -

Reserved
Reserved
Seek i n progress on drive
Reserved
Reserved
Reserved
Rese:rved
Seek a ptimization enabled (1 yes)

Controller Status Extension 3

The following are the descriptions for the currently defined
bits.
All currently defined bits are used by mass storage
devices.

4-51

DRIVER DATA STRUCTURE DETAILS
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, this bit
is set to indicate that a positioning operation is in
progress.
S3.SPB=100
If this bit is set, port B on this unit is spinning up.
S3.0PT=200
Reserved for future use.

Must be clear.

S.ST2 (controller status extension)
Driver access:
Initialized.
Description:
This status word defines certain status conditions for the
controller-unit combination. Figure 4-12 shows the layout of
this word.

4-52

DRIVER DATA STRUCTURE DETAILS

S.ST2

All unused bits are reserved
for system use and expansion.

52.EIP 52. ENB ' - - - - 52.LOG ~--- 52.MAD '--_ _ _ _ _ 52.IDS ' - - - - - - - - - 52.0PI' ' - - - - - - - - - 52.roN ' " - - - - - - - - - - 52.0P1 ' - - - - - - - - - - - 52.0P2 ' - - - - - - - - - - - - - 52.ACT -

Figure 4-12:

Error in progress (1 = yes)
Reserved
Reserved

Multiaccess device (l = yes)
Reserved (not supported)

Device supports seek optimization (1 yes)
Contiguous KRB/SCB allocation (1 yes)
Irrlicates the type of optimization used
Irxlicates the type of optimization used
Driver has operation (I/O) active (1 yes)

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.MAD=10
This bit indicates the presence of the table of KRB addresses
at the end of the Status Control Block. PROtOD will relocate
these KRB addresses, but it is the drivers' responsibility to
manage controller assignment.
S2.CON=200
This bit indicates the contiguous
allocation
of
the
controller request and status control blocks. Devices that
do not support overlapped operation do not require a separate
SCB 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

S2.ACT=2000

4-53

KRB

and

SCB,

refer

DRIVER DATA STRUCTURE DETAILS
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.
Description:
This word points to the currently assigned controller request
block. 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 KRB.
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.
P/OS systems do not
currently
provice
active
support
of
multi-access devices.
If needed, however,
the driver may dynamically change this KRB
pointer for its own purposes.
The first cell in the KRB (K.CSR) contains the
device register address for the controller.

control

and

S.KTB (KRB addresses)
Driver access:
Initialized.
Description:
This table appears only if and the device is multiaccess (the
S2.MAD bit set).

4-54

DRIVER DATA STRUCTURE DETAILS
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. 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. 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-13 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 contiguous space. with such contiguous allocation, all
offsets commonly used by the driver 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
contiguous SCB/KRB allocation.
The fields* in the KRB are described as follows:
K.PRM (device-dependent storage)
Driver access:
Initialized, read-write.
Description:
PROLOD does not relocate any addresses in this area.

* Parenthesized comments following the symbolic offset indicate
the value to be initialized in the data base source code.
4-55

DRIVER DATA STRUCTURE DETAILS

K:PRM

Driver dependent storage

K.SlT
interrupt controller CSR
K.ICSR

reserved

slot number

K.VCTSI K.PRI S

Vector/4

Priority

-6

K.IOC/K.CON 5

Controller I/O count

Controller index

-4

K.STS

Controller status

- 2

K.CSR S

Control and status register address

K.OFF

Offset to UCB table

Highest physical unit

K.HPU

Unused

K.OWN

Owner (UCB address of unit owned)

K.CRQ 1

Controller request queue listhead

K.URM 1.2

Start of UCB table

Controller UNIBUS run mask

•
•
•
4

UCB address physical unit 0

•
•
•

Figure 4-13:

UCB address physical unit n

-1

Controller Request Block

4-56

DRIVER DATA STRUCTURE DETAILS
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 HWDDF$ macro.
K.VCT (interrupt vector divided by 4)
Driver access:
Initialized, not referenced.
Description:
First interrupt vector address divided by 4.
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.
K.IOC (0)
Driver access:
Initialized, not referenced.
Description:

4-57

DRIVER DATA STRUCTURE DETAILS
Reserved for future use.
K.STS (controller-specific status)
D.river access:
Initialized, not referenced.
Description:
This word is used as a status word that concerns the
controller.
Figure 4-14 shows the layout of the controller
status word.

K.STS

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

Figure 4-14:

Controller Status Word

All undefined bits are reserved
Currently defined bits are:

for

use

DIGITAL.

KS.MOF=2
If this bit is set, the unit/controller is in the process
becoming offline.
KS.UOP=4

4-58

DRIVER DATA STRUCTURE DETAILS
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.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.
The driver must not rely on the bit value to
decide whether,
upon being interrupted,
the driver was
attempting a seek operation.
The driver should use the
S2.SIP bit to hold its internal state.
KS.UCB=100
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.
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 exiats,
regardless of whether KS.UOP is set.

4-59

DRIVER DATA STRUCTURE DETAILS
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 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.
K.CSR (start of controller device register addresses)
Driver access:
Initialized, read-only.
Description:
Contains the first address of the
controller.
The
driver
uses
operations.

device for the device
K.CSR to initiate I/O

NOTE
This word is guaranteed to be offset zero for
the KRB.
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 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 required.
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:

4-60

DRIVER DATA STRUCTURE DETAILS
Initialized.
Description:
This byte contains the value of
number used on this controller.

the

highest

physical

unit

K.OWN (0)
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, K.OWN/S.OWN is
set with the currently active unit by code generated with
the GTPKT$ macro suc argument set to blank.

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 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.
Description:
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
4-61

DRIVER DATA STRUCTURE DETAILS
transfer are queued on the end of the list.
KE.UCB
Driver access:
Initialized, referenced by interrupt dispatch code.
Description:
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+1. The table has a length of (K.HPU+1)
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-i.
NOTE

This table exists only
have KS.UCB set.

4.4.7

for

those

devices

that

Contiguous 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 contiguous 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. Figure 4-15 shows the physical layout of the contiguous
KRB and SCB allocation.

4.4.8

Controller Table (CTB)

Figure 4-16 is a layout of the controller table. You ensure that the
CTB is linked into the system list of controller tables by placing the
global label $xxCTB at the start of the table of the KRB addresses in
the CTB.

4-62

DRIVER DATA STRUCTURE DETAILS
K.PRM

Driver-dependent storage

K.SLT
interrupt controller CSR

S.VCT/S.PRI
S.CON

S.CSR

K.ICSR

reserved

K.VCT/K.PRI

Vector/4

Priority

-6

K.IOC/K.CON

Controller 1/0 Count

Controller index

-4

slot nUll1ber

-2

K.STS

Controller status

K.CSR

Pointer to CSR

K.OFF

Offset to UCB table
Unused

K.HPU

o
2

Highest physical unit

K.OWN

Owner UCB

K.CRQ

Input/output queue listhead

S.LHD

S.FRK

- - - - -Fork-Link- - - - Fork PC
Fork R5
Fork R4

S.KS5

KISAR5

S.PKT

I/O packet address

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

•
•
•

KE.RHB
Start of UCB table

UCB address physical unit 0

•
•
•

UCB address physical unit n

Figure 4-15:

Contiguous KRB/SCB Allocation

4-63

DRIVER DATA STRUCTURE DETAILS

r----

l.CLK

8-word
Clock
Block
(Optional)

l.olD

hardware device 10

-4

L.ICB

Link to first ICB

-2

L.LNK 1

Link to next eTB

L.NAM

Generic controller name

oCB address

l.oCB

Controller status

L.STS/L.NUM
LKRB!

INumber of KRB addresses

KRB address 0

6
10

KRB 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 oCB.

Figure 4-16:

Controller Table

The fields* in the CTB are described below:

L.CLK
Driver access:
Initialized
Description:

* Parenthesized contents following the symbolic offset indicate
the value to be initialized in the data base source code.
4-64

DRIVER DATA STRUCTURE DETAILS
This is the clock queue entry for these devices that
need a single clock block per generic controller type.
It only appears if LS.CLK is set.
L.ICB (reserve one word of storage)
Driver access:
Not initialized, not referenced.
Description:
This word contains the address of the first interrupt
control block for this type of controller, divided by
two (2).
L.LNK (0 or link to next CTB in list)
Driver access:
Not initialized, not referenced.
Description:
All 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
the system.

type

L.DID (controller's hardware ID)
Driver access:
Initialized, read-only.
Description:
This hardware ID is the controller mnemonic used to find
this controller table from among all the others in the
system.
L.NUM (number of KRB addresses)
Driver access:
Initialized, read only.
Description:
4-65

DRIVER DATA STRUCTURE DETAILS

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.
L.STS (generic controller status)
Driver access:
Initialized, read only.
Description:
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 tabh
LS.NET - DECnet device

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
clock block.

8-word

service

units

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

4-66

DRIVER DATA STRUCTURE DETAILS
If this bit is set, the clock block is linked into the
queue.

clock

L.KRB (KRB addresses of controllers)
Driver access:
Initialized once for the controller, not referenced.
Description:
A list of the controller request block addresses ordered by
their respective 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) 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.
PROLOD supplies this address in the DDT when it loads the
driver.
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 PROLOD.

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
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-67

DRIVER CODE DETAILS
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 device drivers require a driver dispatch table somewhere in the
first 4K words of the driver code. Conventionally, the table is
located at the begjnning 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 driver 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.
Because these labels do not appear in the DDT itself, their format is
fixed and they must be specified in the format shown.

Table 4-9:

Labels Required for the Driver Dispatch Table

Meaning

Required Format
$xxTBL::

Defines the start of the DDT.
The PROLOD
routines use this label to fill in D.DSP.

xxCTB:

Defines the pointer to the table of KRB
addresses in the eTB 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.)

$xxTBE: :

Defines the end of the DDT for Executive
PROLOD routines that scan the DDT.

4-68

DRIVER CODE DETAILS

-4

D.VNXC. D.VCHKl
D.VDESl

I/O Initiation Entry Point Address

Cancel Entry Point Address

D.VCAN

-2

$xxTBL: : D.VINI

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

Interrupt Entry Point Address 0

Interrupt Entry Point Address 1
0

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

0
wzCTB:

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

o
o

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

Figure 4-18:

Driver Dispatch Table Format

At offsets D.VINI through D.VUCB in the
4-69

DDT

your

driver

appear

DRIVER CODE DETAILS
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 the
following:
$xxTBL::
$xxTBE::
$xxLOA::
$xxUNL::
These fixed-format labels are described elsewhere in this chapter.
The DDT$ macro uses the standard labels but allows you to alter the
forma~ 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
addresses.
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 are no more interrupt entry points for the controller. There is
no restriction on the number of vectors each controller may have. For
a single interrupt device, location D.VINT+2 (interrupt entry address
0) is the interrupt address.

4-70

DRIVER CODE DETAILS
Table 4-10:

Standard Labels for Driver Entry Points

Label

Entry Point

xxINI:

I/O initiation

xxCAN:

Cancel I/O

xxCHK:

Block check and conversion

xxOUT:

Device timeout

xxPWF:

Power failure

xxKRB:

Controller status change

xxUCB:

Unit status change

$xxINT:

Interrupt entry point

* The characters xx are the 2-character mnemonic.

D.VINT

xx
XXIN1
XXIN2

o
XXCTB:

Figure 4-19:

Sample Interrupt Address Block in the DDT

4-71

DRIVER CODE DETAILS
1/0 Initiation Entry Point

4.5.2

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 DRSUB. 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.
RS = address of the UCB of the unit for which the
queued an I/O packet

Executive

has

This entry condition pertains unless the driver wants to delay the
queuing operation.
Therefore,
if the queue-to-driver bit UC.QUE in
the unit status block offset U.CTL is set,
the following are the
register conventions.
RS
R4
Rl

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

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

C = 1

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
Rl

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
RETURN instruction should be executed).
If the C bit is clear,
generated code loads the location at offset K.OWN/S.OWN in
contiguous KRB/SCB with the UCB address of the unit to process.
driver may then process the request and activate the device.
4-72

(a
the
the
The
All

DRIVER CODE DETAILS
registers are available to the driver. The driver executes a RETURN
instruction to transfer control to the system.

4.5.3

Cancel Entry Point

The offset D.VCAN in the driver dispatch table contains the address of
this ~ntry 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
UCB address
R4
SCB address
R3 = Controller index (undefined if S.KRB equals zero)
Rl
Address of TCB of current task
RO
Address of active I/O packet
The usage 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 TOSCH 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

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 routine $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
4-73

DRIVER CODE DETAILS
follows:
RO = address of the first buffer
All regist~rs are available to the driver. The driver returns control
to the Executive by executing a RETURN instruction.

4.5.6

Power Failure Entry Point

The offset D.VPWF in the driver dispatch table contains the address of
this entry 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
fashion once for each controller.
The following are the register
conventions:
C bjt set (controller power failure)
R3
R2

CTB address
KRB address

The driver may use all registers.
After the Executive has called the driver for all related controllers,
it calls 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)
RS
R4
R3

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

4.5.7

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.
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 = CTB address for the controller
4-74

DRIVER CODE DETAILS
R2
O(SP)
2(SP)

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

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.

$SCERR

The driver
Operation is successful.
This is
status
change
requested.
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 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

4-75

DRIVER CODE DETAILS
network connections). System disk and terminal drivers must indicate
return status immediately.

4.5.8

Unit Status Change Entry Point

The offset D.VUCB in the driver dispatch table contains the address of
this entry point.
The Executive routine $UCBSC in the OLRSR module
calls the driver at this entry point at priority 0 to put a unit
on-line or to take a unit off-line. This entry is called once for
each unit whose status changes.
The C bit indicates whether the
request is for on-line or off-line. The following are the register
conventions:
R5 = Address of UCB or unit changing status
Address of SCB of unit
R4
Controller index (undefined if S.KRB equals zero)
R3
Return address for driver completion
O{SP)
Return address for caller of the Executive routine
2{SP)
The C bit is set to indicate the requested status change as follows:
C = lOn-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

Operation is not successful and a negative value in
$SCERR is the I/O error code. Thus, a negative value
rejects the change requested by the C bit.

$SCERR

The driver
Operation is successful.
status
change
requested.
This is
condition.

accepts the
the default

All registers are available to the driver.
The driver must return
within 60 seconds. The Executive does not change the status of a unit
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.

DRIVER CODE DETAILS
$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.
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.9

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.
The driver will be called from the interrupt dispatch coroutine $INTSI
in the Executive.
The following are the 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.
Drivers should use the INTSV$ macro call at an interrupt entry point,
in order to resolve entry processing. INTSV$ does not generate a call
to $INTSV because PROLOD 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.
4-77

DRIVER CODE DETAILS
INTSV$ generates code to load
interrupting unit.
After the
following conditions apply:
RS
R4

RS with the UCB address of the
INTSV$ call in the driver code, the

= U~B 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
~ismisses

4.5.10

RETURN instruction
the interrupt

the

structures

coroutine,

which

Volume Valid Processing

System-supplied drivers that service mountable devices (those that
have the DV.MNT bit in the UCB U.CW1 word set) take advantage of
special processing of volume valid for a device. For such devices the
Executive 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
mounted status bit is not set, DRQIO requires that a device-specific
bit called volume valid (US.VV) be set or else it rejects the
directive.
If a mounted status bit is set, DRQIO does not check the
volume valid bit.
(DRQIO assumes that the MOUNT command properly set
the volume 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 advantage 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
spinning-up status bit (US.SPU) and the volume valid bit (US.VV) in
the UCB 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:

4-78

DRIVER CODE DETAILS
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-79

CHAPTER 5
INCORPORATING A USER-SUPPLIED DRIVER INTO PIOS

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

5.1

INCORPORATING AN 110 DRIVER INTO A PIOS SYSTEM

With the exception of DIGITAL supplied disk I/O drivers and the
terminal driver, all P/OS I/O drivers are loadable with a loadable
data base and are incorporated directly into a running system via a
call to the PROLOD (POSSUM) system service. The driver may also be
unloaded at runtime, as a result of a specific unload request to
PROLOD.
The driver data base is never removed as there are many
structures in the system which reference the UCB.
Even if it were
possible to track down all references, the required structures might
not be memory resident. Since the system image is not modified as a
result of loading a new driver, the data base can be removed from the
system by rebooting P/OS.

5.1.1

Guidelines for Creating/Adding a Driver Into the System

To incorporate a loadable driver with a loadable data
following procedure:

use

the

Create the driver's macro source code file and the data
source code file in the directory of your choice.

base

Assemble the driver and data base using the prefix file
RSXMC.MAC and the executive data structures macro library
EXEMC.MLB. RSXMC contains the various system configuration
symbols
used by the executive's conditionalization and
commonly used macros, such as DOT$, GTPKT$, and INTSV$.

5-1

base,

INCORPORATING AN I/O DRIVER INTO A P/OS SYSTEM
3.

Taskbuild (using PAB) your driver code and data base.
Ensure
that a symbol table file (.STB) is generated at this time,
since it is required by the PROLOD system service.
The
symbol table file
is expected to be located in the same
directory and have the same file name as the driver image
file
(.TSK).
The only difference will be the file name
extension.

4. ,Create a program that will issue the PROLOD system service
call to load your driver.
As an aid to debugging, the
logical "PROLOD$MSG" (without the quotes)
may be created
using the DCL "ASSIGN" command and set to ASCII "0". This
logical's existence will enable PROLOD ASCII error messages
to be sent to the debugging terminal (TT2:).

5.1.2

Assembling the 1/0 Driver

After you have created the driver source code and data base files,
they must be assembled by the P/OS macro assembler (PMA).
It is
suggested that listing files be created in the event debugging is
needed. The following commands illustrate this:
PMA>DRVCOD,DRVCOD=[1,S]EXEMC/ML,RSXMC/PA:1,[]DRVCOD
; Assemble the driver code.
PMA>DRVTAB,DRVTAB=[1,S]EXEMC/ML,RSXMC/PA:1,[ ]DRVTAB
; Assemble the driver data base.
Note that it is not possible to use ODT in a driver since a driver is
not a task,
and it is not possible to issue a system directive from
system state.
For debugging tips and procedures, see Chapter 6.

5.1.3

Taskbuilding the 1/0 Driver

After completing the assemblies with no detected errors, taskbuild the
driver code and data base with the following commands:
PAB>DRIVER/-HD/-MM,DRIVER,DRIVER=
1) The I-HD switch is specified since a task header is not
needed. The driver is not a task but rather an
extension to the executive.
2) The switch /-MM must be used in the command line.
3) A map file is produced and is useful for debugging.
4) A symbol table file is specified since it will be
required by PROLOD.
PAB>DRVCOD
PAB>DRVTAB

5-2

INCORPORATING AN I/O DRIVER INTO A P/OS SYSTFM
5) PAB reprompts for input files. Both the code and the
data base are specified. The driver data base is built
into the image following the driver code.
PAB>[1,5]POS.STB/SS
PAB>[1,5]EXELIB/LB
PAB>/
6) POS.STB is specified as input so that executive routine and
listhead references may be resolved.
Note that ISS is required because the presence of certain
global symbols, such as $INTSV, cause PROLOD to reject
load attempts.
7) EXELIB is specified so that data structure offsets, mask,
and bit references may be resolved.
; 8) The single slash begins the option phase of the task builder.
Enter options:
TKB>STACK=O
; 9) The taskbuilder is directed not to allocate stack space. A
driver uses the executive's stack sparingly.
PAB>PAR=GEN:120000:40000
PAB>//
10)A partition, base virtual address and maximum size are
specified and the double slash terminates task builder
input.

5.1.4

Loading an I/O Driver Into the System

After completing the taskbuilding of your driver without any
detected errors, you must create a small task to issue the POSSUM
"PROLOD" system service call. If you are in the process of
debugging the driver, it is suggested that you attach a debugging
terminal to the printer port (TT2:), define the logical name
"PROLOD$MSG", eqtiating it to "0", and run XDT prior to invoking
PROLOD.

5.2

PROLOD

The callable PROLOD system routine provides a method to load or
unload an I/O driver into P/OS. PROLon is an entry point in the
POSSUM system resident library; the routine calls the server task
$xxLOAD.
(See the P/OS System Reference Manual for a general
description of POSSUM system services.)
To avoid memory fragmentation, PROLOD loads the driver in the
highest available physical memory, checkpointing any eligible
regions that may be resident in high memory.
5-3

PROLOD
PROLOD requires that both the driver image (.TSK) and the driver
symbol table (.STB) be located in LB:[ZZSYS]. PROLOD provides
the primary values for the device, directory, filename extension,
and last three letters (DRV) of the filename itself. You cannot
specify these in the request, and the name of the device in D.NAM
must be the same as the two characters provided. Also, PROLOD
uses only the highest version of the files.
Unload operations currently have a restriction that requires
access to the image and symbol table files so that PROLOD can
easily determine which units and controllers need to be placed
offline prior to unloading the driver code from memory. The
driver's data base is never removed from primary pool and, if the
driver is reloaded, it is assumed that the old data base can be
reused.
Optionally, a driver can specify the $xxLOA and $xxUNL entry
points so that it can save, restore, or initialize any required
context.
To load or unload a driver,
arguments:

invoke

PROLOD

with

the

following

status, request, fnam, fnamsz
where:
status

The
The address of the 8-word status Block.
chapter on POSSUM in the P/OS System Reference
Manual describes the Status Block.

request

The address of a word containing a request value
indicating the operation to be performed. The
defined decimal values are:
1. = Load a driver and bring
associated controllers and units.
2. = Unload
bringing all
offline.

fnam

a
driver
associated

online

all

after
successfully
controllers and units

If the request is to load or unload, this
argument
contains
the
address of a word
containing two ASCII characters that PROLOD can
use to derive the driver task filename and the
symbol table filename.
(Both files must be
present to successfully load a driver.)

5-4

PROLOD

••

The
derived
names
are
of
the
form
LB:[ZZSYS]xxDRV.TSK
and
LB:[ZZSYS]xxDRV.STB,
respectively, where xx are the two characters
you supply.
For example, you supply the two
characters BM for a driver named BMDRV.

•
•
•
•
•
•
•

fnamsz

5.2.1

If the request is to load or unload a driver,
this argument contains the address of a value
indicating the size in bytes of the filename
argument. This value is currently 2.

PROLOD Operations and Diagnostic Checks

The PROLOD routines relocate and validate many of the pointers
within the data base and, in the process, validate other data in
the structures. The driver itself is then loaded into the
highest available physical address space, and the data base is
loaded into system pool.
To read the data base from the driver image 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 PROLOD routines must know the
starting address of the DCB. If the global label $xxDCB is not
defined (it is not in the symbol table file), PROLOD assumes that
the DCB is the first word of the data base. When this assumption
is incorrect because the DCB is elsewhere in the data base and is
not labeled properly, many unusual error conditions result. To
avoid this type of problem, you should always define the start of
the DCB with the global label $xxDCB.
Each eTB is checked and relocated.
both checked and relocated:

The

following

offsets

are

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
ze ro. )

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.

5-5

PROLOD
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.DID

If non-zero,
PROLOD
scans
the
system
configuration table for the presence of a
device with a matching hardware ID.
If a
match is found, then PROLOD uses information
in the system configuration table to assign
the values K.SLT, K.ICSR, K.CSR and K.VCT of
the KRB.
See Section 5.2.2 for
specifying
L.DID
autoconfiguration.

L.KRB

information
during

about
PROLOD

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 following offsets in the CTB are checked:
L.NAM

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

L.NUM

The number of controllers, must be less
17 (decimal).

than

Each KRB is checked and relocated. The following offsets in
KRB are both checked and relocated:

the

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

The listhead
queue.

K.CRQ+2

It is initialized to an empty list with the
first word zero, and the second word pointing
to the first, relocated.

5-6

for

the

controller

request

PRO tOO
Each DCB is checked and relocated.
checked and relocated:

The

following

offsets

are

both

D.tNK

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.

D.UCBt

The length of the UCB must be even and nonzero.

D.UNIT

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

The pointer to the driver dispatch table (D.DSP) is set
to show. that the driver is not yet loaded.

zero

offsets

are

U.DCB

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

DCB

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.

Each UCB is checked and relocated.
both checked and relocated:

Each SCB is checked and relocated.
both checked and relocated:

The

following

offsets

are

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.
(PROtOD preserves bit zero in each entry.)
Each entry in the table must also have a
matching entry in the table of KRB addresses
5-7

PROLOD
of a CTB in the loadable data base.
The following offsets in each SCB are

initiali~ed

as described:

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

S.PKT

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

These last checks end the loading
base.

and

validating

the

set
data

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 available vector address PROLOD prints a warning message.
Interrupt control blocks are created and linked into the list
starting at L.ICB in the CTB.
The format of the DDT must be consistent with that described in
Section 4.3.1.
If the device that the data base describes does
not have any physical controllers (that is, a CTB does not
exist), the DDT is not checked. Otherwise, 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, PROLOD prints an error message,
restores the system device tables, and exits.
When the driver is loaded, all links are established. The DCB of
the loadable data base is put in the list of DCBs just in front
of the DCBfor the first pseudo device. The CTB(s) are linked to
the end of the eTB 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 local label $xxCTB, is loaded into
the DDT.

5.2.2

Using PROLOD Autoconfiguration

PROLOD autoconfiguration provides option
5-8

slot

independence

for

PROLOD
your
driver.
When
you
use
autoconfiguration,
PROLOD
automatically determines the option slot in which a particular
device resides.
Additionally, PROLOD sets the controller CSR,
the vector, the interrupt controller CSR, and the slot number in
the driver's data base.
We recommend
that
all
drivers
for
P/OS
systems
use
autoconfiguration bec~use of the option slot independence it
provides.
This independence eliminates slot contention and
simplifies end user installation.
To use autoconfiguration, specify a hardware option device ID in
the L.DID field of the driver's CTB. The hardware option device
ID identifies the controller type. Also, you must specify the
value of K.CSR to be equal to zero.
During autoconfiguration, if PROLOD successfully finds the device
and gains access to that device for.the driver (by attempting to
offline a driver which is currently using the device), then
PROLOD sets the values of K.CSR, K.ICSR, K.SLT, and K.VCT.
As an alternative to using autoconfiguration, you can explicitly
access a particular slot by preconfiguring your driver data base.
Note that drivers that access system options such as the kernel
Communications Port must always preconfigure their controller
data base.
To preconfigure your driver
values:

data

base,

specify

the

following

K.CSR--associated controller CSR

K.ICSR--associated interrupt controller's CSR

K.SLT--the slot number in which the option is present

PROLOD does not check the values K.ICSR and K.SLT. Once loaded,
your driver can change K.ICSR or K.SLT for its own purposes;
however, the value of K.CSR must always be within the address
range of those CSRs assigned to the particular option. PROLOD
derives the controller's vector address (K.VCT)
from
the
specified CSR.

5.2.3

PROLOD Errors

PROLOD attempts to return error message text if and only if you
have defined the logical name PROLOD$MSG. with the equivalence
value O. Multiple errors may be detected in the course of
5-9

PRO LaD
loading and checking the driver and its data base.
PROLOD returns the following server-specific error codes in word
2 of the status Control Block when word 1 contains the value -4
(server-specific error):

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.

- 14.
- 15.
- 16.
- 17.

- 27.
- 33.

- 34.
- 35.
-

40.
46.
50.
51.
60.
61.
62.
63.
64.

- 65.
-

66.
68.
69.
70.

- 72.
- 73.

- 74.
- 75.
- 76.
-

77.
78.
79.
80.

O. Illegal request format
File not a valid driver task image
Privileged command
Inconsistent argument length
Illegal request function code
Illegal unit name format specified
Specified unit not found
Illegal controller name specified
Specified controller not found
Failed to offline device
I/O error on input file
Failed to bring device online
Controller already online
Unit already online
File has illegal STB format
Device not found in system
Illegal device name specified
Data base for not found in system or driver
partition/region not in system
Device not mounted
File not contiguous
Open failure on file
Task image I/O error ih file
Partition too small
Illegal driver task APR usage
partition/region is a common
Driver already resident
Driver being loaded or unloaded
Insufficient pool space
Loadable driver support not in system
Driver not loaded
Driver cannot be unloaded, still online
Device is attached, busy, online and/or mounted
Invalid driver data base at offset in file
Driver built with wrong executive STB file
Warning - KRB interrupt vector too high
warning - KRB interrupt vector in use
Symbol is undefined in file
Symbol is doubly defined by file
Illegal value for symbol in file
Driver dispatch table is inconsistent
CTB is not supported by driver -- not loaded
Cannot load/unload a pseudo device
Too many symbols of the form in file
CTB does not exist
5-10

PROLOD
-

5.2.4

DeB table for eTB is full
KRB table of eTB will not accept KRB
KRB not in loadable data base
eTB name is a duplicate
Warning - loadable driver larger than 4K
partition/region is not a common
KRB is not offline
Illegal use of partition or region

81.
82.
83.
84.
85.
86.
87.
88.

PROLOD Sample Program

The following macro program illustrates a PROLOD call .
. TITLE

LOAD - Example PROLOD call

.mcall

qiow$s,exit$s

irequest system macros

This ~ask requests PROLOD to load the driver XXDRV from LB:[ZZSYS]
start:

mov
call
mov
mov
mov
call
qiow$s
exit$s

#loaarg,rS
prolod

iget args for sample call to PROLOD
iload the driver
iprint status block always
#stat,r2
ipoint to status args
#fmt,rl
;output format
#outbf,rO
;output buffer
$edmsg
;format it
;print it
#io.wlb,#S,#S",,<#outbf,rl>
;exit

local data
loaarg: .word
.word
.word
.word
.word
stat:
.blkw
fnmsiz: .word
rqst:
.word
fnm:
.ascii
fnmsz=.-fnm
outbf:
fmt:

.blkb
.asciz

4
stat
rqst
fnm
fnmsiz
8.
fnmsz
1

/XX/

ifour arguments (simple load call)
ipointer to eight word status block
ipointer to PROLOD request
ipointer to filename size
ipointer to size (in bytes) of fnm
ieight word status block
iwOrd containing size of fnm
iload (and online all) request
idriver name
iimplied filename "LB:[ZZSYS]XXDRV.TSK"
i AND "LB:[ZZSYS]XXDRV.STB"
iname extension as this can't be spec'd)

132.
ioutput buffer for status display
/%Nload request status: %N%8P/ ioutput format string
5-11

PROLOD

.even
.end

start

5-12

CHAPTER 6
DEBUGGING A USER-SUPPLIED DRIVER

Adding a user-supplied driver carries with it the risk of introducing
obscure bugs into a P/OS system.
Because the driver runs as part of
the Executive, P/OS provides an Executive debugging tool (XDT).

6.1

THE EXECUTIVE DEBUGGING TOOL

XDT is an interactive debugging tool which can aid in debugging
Executive modules, I/O drivers, and interrupt service routines.
This
debugging aid is similar to ODT,
the task-level debugger.
XDT
occupies physical address space in the GEN partition but does not take
up any Executive virtual address space. XDT also does not interfere
with user-level OOT, which can be used with any number of tasks while
you are debugging your driver with XOT.

6.1.1

XDT Commands

XDT commands are generally compatible with ODT commands.
contain the following commands available in ODT:
o

No $M -

(Mask) register

No $X - (Entry Flag) registers

No $V - (SST vector) registers

No $D - (I/O LUN) registers

No $E -

No $W - (Directive status word) $DSW word

(SST data) registers

6-1

XDT does not

THE EXECUTIVE DEBUGGING TOOL
0

No E

- (Effective Address Search) command

No F

- (Fill Memory) command

No N

- (Not word search) command

No V

- (Restore SST vectors) command

o. No W

- (Memory word search) command

In addition, the X (Exit) command in XDT will simply issue a HALT
instruction. This will drop the printer port terminal into Micro-ODT.
(See Section 6.2.

6.1.2

xor Start Up

You may install XDT from DCL with the command: INSTALL XDT/NOREMOVE.
The "noremove" switch will inform the executive not to abort XDT when
the DCL or PRO/Tool Kit application exits. From DCL, use the SPAWN
RUN XDT command. An initialization message will appear. When active,
XDT runs entirely at priority level 7.

6.1.3

xor General Operation

Prior to embarking on an XDT debugging session, plug a maintenance
cable (BCC-08) into the printer port and attach a VT100 or similar
terminal. A maintenance cable is the same as a printer cable
(BCC-OS), except that pins 8 and 9 are shorted. If the cable was in
place when the system was turned on, the terminal must be set to 9600
baud; otherwise, the terminal must be at 4800 baud. Input and output
are directed to this port.
Assemble the driver with an embedded BPT instruction, or use the ZAP
utility to set the breakpoint by replacing a word of code with the BPT
instruction. (Make sure to write down the instruction that you
replace with the BPT instruction.) When the breakpoint instruction in
the driver is executed, XDT prints:
BE:xxxxxx
XDT>
Then:
1.

Using XDT, replace
instruction.

the

BPT

6-2

instruction

with

the

desired

THE EXECUTIVE DEBUGGING TOOL

6.1.4

Decrement the PC
register R7.

subtracting

from

the

contents

Then proceed by using the P or 5 commands, after optionally
setting breakpoints within the driver or examining memory
locations.

XDT and Debugging a User-Supplied Driver

Using XDT to debug a driver has special pitfalls.
can arise is a T-bit error:

One

problem

that

TE:xxxxxx
XDT>
This error results when control reaches a breakpoint that you have
set, using XDT, in a loaded driver. The T-bit error, rather than the
expected BE: error, occurs unless register APRS is mapped to the
driver at the time XDT sets the breakpoint. Assembling or zapping the
BPT (as opposed to setting it from an XDT prompt) will help avoid this
T-bit error.
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
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.2

MAINTENANCE- OR MICRO-ODT

The processor microcode supports a more limited set of debugging
commands
which
permit debugging of a system in an otherwise
inaccessible state. Be advised, however, that Micro-ODT is able to
access only the low 28K words o~memory and the I/O Page, whereas XDT
can be mapped to any part of" memory.
Micro-ODT is more fully
documented in the Professional 300 Series Technical Manual.
It will
also be discussed further in this chapter.

6-3

FAULT ISOLATION
6.3

FAULT ISOLATION

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

A user-state task has faulted in such a ~ay

that

causes

the system to fault.
2.

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

The system software itself has faulted.

The hardware has faulted.

way

that

When the system faults, you must first decide which of the above four
potential
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 as listed below (in
increasing difficulty to isolate):
1.

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

The system displays a software bugcheck and halts.

The system halts but displays nothing.

The system is in an unintended loop.

order

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 - A trap mayor may not be intended
(for example, a previously set breakpoint). If it is nq,t intended and
you have some idea of the source of the problem (for example, a recent
coding change), you may use XDT to examine pertinent data structures
and code.

6.3.1.2 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
contain). See Section 6.2.
6-4

FAULT ISOLATION
6.3.1.3

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

Halt the processor by pressing
terminal (Micro-DDT).

<BREAK>

from

the

debugging

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

You may then want to step through a number of instructions in an
attempt to locate the loop. Toggle the Micro-DDT Halt register by
entering "H" at the "@" prompt. Following this, each "PH command will
result in a single step. To restore "proceed" functionality to the
"P" command, enter "H" again.
In order to avoid the side-effects of printer port interrupts you may
first wish to disable printer receiver interrupts. Then proceed as
follows:

6.3.2

In micro-DDT open location 173202 (the CSR).

Set the printer receiver IMR (interrupt mask register) bit by
depositing a 75 in this location.

Pertinent Fault Isolation Data

Before you attempt to locate the fault, you should examine the system
common (SYSCM).
SYSCM contains a number of critical pointers and
listheads. In addition, you should examine the dynamic storage region
(system pool and ICB pool) and the device tables. The device tables
are in the module SYSTB. At this point, you have the following data,
which represents a minimal requirement for effectively tracing the
fault:
o

The stack

RO through R6

Pertinent device registers

The dynamic storage region

6-5

FAULT ISOLATION

6.4

The device tables

System common

TRACING 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)
Figure 6-1 shows the interaction of task header pointers.
Note that
all tasks on PIOS systems have a pool-resident (external) header.
The pointers $HEADR, $SAHPT, and $SAVSP all point to the first word of
the task header, which contains the user task's stack pointer (SP)
from the last time it was saved.
Figure 6-2 shows a brief description of the task header.
The task
header is fully described in the RSXIIMIM-PLUS and MicrolRSX Task
Builder Manual, which is distributed with the Tool Kit Documentation.

6-6

TRACING FAULTS

NON.POOL·RESIDENT TASK HEADER (External)
Task
$SAHPT

140000
Current Task
Header

$HEADR

Executive
Data Area

$SAVSP

1·word bloCk

T.HDLN 0

Executive
SSAHDB

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
heaaer -- pointed to by H.GARD).

6-7

TRACING FAULTS

f4--

··
·
R5
PC
PS

··
·

H.NLUN

f---

H.GARD

H.HDLN

Length in bytes

Figure 6-2:

Task Header

The pointers associated with a
described next:

pool-resident

(external)

header

are

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

6-8

task

header,

which

TRACING FAULTS
$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 - Contents undefined .x $SAHDB

6.4.1

Tracing Faults Using the Executive Stack and Register Dump

The following discussion implies that XDT is active.
If the system
crashes
while XDT is not active,
a software bugcheck occurs.
Procedures for analyzing a bugcheck are discussed in Section 6.4.5.
To trace a fault after a software crash, 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.

6-9

TRACING FAULTS

PS
PC
R5
R4
R3
R2
Rl
RO
Return to system exit
Zero or more SST parameters
SST fault code
Number of bytes

Figure 6-3:

Stack Structure:

.....1-------- SP

Internal SST Fault

The fault codes are:

o
2
4
6

10
12
14
16

20
22

24
26
30
32
34

;TRAPS TO 4
;MEMORY PROTECT VIOLA~ION
;BREAK POINT OR TRACE TRAP
;IOT INSTRUCTION
iILLEGAL OR RESERVED INSTRUCTION
;NON RSX EMT INSTRUCTION
iTRAP INSTRUCTION
;11/40 FLOATING POINT EXCEPTION
iSST ABORT-BAD STACK
;AST ABORT-BAD STACK
iABORT VIA DIRECTIVE
;TASK LOAD READ FAILURE
;TASK CHECKPOINT READ FAILURE
iTASK EXIT WITH OUTSTANDING I/O
;TASK MEMORY PARITY ERROR

6-10

TRACING FAULTS
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

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 rOT instruction from the stack, which in
this case is incorrect. Thus, the SP appears to be four bytes greater
th~n 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-11

TRACING FAULTS

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 th~t 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 examtnation focuses on scanning the stack for
addresses that may be subroutine links that can ultimately lead to a
thread of events isolating the fault.
This is essentially the aim of
looking at the system stack if $STKDP is zero or less.
Frequently, a fault can occur that causes the SP to point to Top of
Stack
(TOS)+4.
This fault results from issuing an RTI when the top
two items on the stack are data.
The result is a wild branch and
then,
most probably,
a halt.
Figure 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
contains a halt.
This indicates that the original SP was four bytes
below the final SP, and fault tracing should begin from the original
SP.

....41-------- SP
5
40100

Figure 6-5:

Stack Structure:

. . 1-------.
SP
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-12

TRACING FAULTS
6.4.3

Tracing Faults After an Unintended Loop

To trace a fault when an unintended loop has occurred, first halt
processor by hitting <BREAK> from the debugging terminal.

the

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

6.4.4

Additional Hints for Tracing Faults

Another item to check is the current (or last) I/O Packet, the address
of which is found in S.PKT of the SCB. The packet function (I.FCN)
defines the last activity performed 'on the unit.
If trouble occurred in terminating an I/O request, a scan of the
system dynamic memory region may provide some insight. This region
starts at the address contained in $CRAVL, a cell in SYSCM.
Because
all I/O packets are built in system dynamic memory, their memory is
returned to the dynamic memory region when they are successfully
terminated.
Following the link pointers in this region may reveal
whether I/O completion proceeded to that point. In systems with QIO
optimization, $PKAVL (SYSCM) points to a list of I/O packet-sized
blocks of dynamic memory that are not linked into the $CRAVL chain.
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 deal location of a dynamic buffer causes a loop in the module
$DEACB on the next deallocation (of a block of higher address) after
the second deallocation of the same block. At that time, R2 and R3
both contain the address of the I/O Packet memory that has been doubly
deallocated.

6.4.5

System Bugcheck Without XDT

If a software error causes the system to crash while XDT is not
active, the system will bugcheck.
A bugcheck will request the
diagnostic ROM to display an unhighlighted picture of the Professional
with a two-number code, for facility and type of bugcheck. Errors
with a facility code of 000300 are executive or other system state
errors, in which case, the type is represented in the following list:
000000 rOT in System State
6-13

TRACING FAULTS
000001 Stack Overflow
000002 Trace Trap or Breakpoint
000003 Illegal Instruction Trap
000004 Odd Address or Other Trap 4
NOTE

Since there are no odd address traps or memory parity
errors on the 350, these traps are most likely NXM
(non-existent memory), caused by illegal
address
computation, bus timeou~, or memory management fault.
000005 Segment Fault
000006 A Background Task (one without a parent) aborted or
exited with I/O outstanding
The processing of the diagnostic ROM changes some of the context of
the system at the time of the crash, so that the diagnosis of the
problem is made somewhat more difficult.
In particular, after a
bugcheck, KISAR5, KISAR6, UISARO, and UISARl have been altered, and
the Kernel Stack Pointer has not been preserved. You must therefore
examine the Kernel stack from $STACK toward low memory in order to
locate the trap.
When the processor traps, the PSW and PC are pushed onto the stack.
If the trap is a directive issued by a task in user state (i.e. an
EMT trap), the task's general purpose registers are pushed beginning
with R5 and ending with RO. Then the return call to $DIRXT and an
initial DSW success code of 1 are pushed onto the stack.
The
directive processing may call other system subroutines, some of which
might save R5 and R4 (by convention the "nonvolatile" registers).
When the stack contents are analyzed to determine whether they are
pointing to data structures or subroutine addresses, a picture of the
flow of control can be outlined. Often there will be pointers on the
stack to UCB's or other driver-related structures, TCB's or other
task-related structures, or saved APR mapping biases for temporary
remapping of KISAR5 and KISAR6. Since most of these structures are in
primary pool (and thus in the low 28KW of physical memory), they may
be examined using micro-ODT.
Ultimately, a crash will be preceded by a trap in system state.
Again, the PSW and PC at the time of the crash will be pushed onto the
stack. A PSW of 0300nn or OOOnnn indicates Kernel mode, previous mode
User or Kernel, respectively. The PC will point to the instruction
following the one causing the trap. Remember that after a bugcheck R6
(or SP) will not point to this address on the stack.
6-14

REBUILDING AND REINCORPORATING A DRIVER

6.5

REBUILDING AND REINCORPORATING A DRIVER

After correcting and assembling the driver source, unload the old
version using PROLOD,
task build the new one, and load it using
PROLOD.
Once loaded, the data base is not removed by PROLOD.
If the data base
is incorrect and cannot be patched, correct its source, reassemble it,
and build the new driver task.
Then bootstrap the system before
loading the driver task image containing the corrected data base.

6-15

CHAPTER 7
EXECUTIVE SERVICES AVAILABLE TO AN 1/0 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-11
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, R1, and RO are volatile registers and may be used by a called
routine without save and restore responsibilities.
When a driver is entered directly from an interrupt, it is operating
at interrupt level,
not at system state. At interrupt level, any
register the driver uses must be saved and restored.
INTSV$ .generates
code to preserve R5 and R4 for the driver's use.
All drivers must
follow these conventions.
See the description of the driver dispatch table in
the contents of registers when a driver is entered.

7.2

Section

4.5

for

EXECUTIVE TIMER RELATED FACILITIES

The executive provides a number of timer related facilities which are
available to an I/O driver.
They are typically used to periodically
poll a device for a status change in the absence of an interrupt
capability, to provide general timer services to the driver so that it
can perform it's own timeout processing
(needed by more advanced

7-1

EXECUTIVE TIMER RELATED FACILITIES
drivers such as the full duplex terminal driver), or to call the
driver back after some specified period of time.
A timer request requires a structure called a clock block.
It is
normally located in the device driver's database which has been
allocated from primary pool and is "C.LGTH" bytes in length. A driver
can however simply allocate the clock block from primary pool using
the $ALOCB executive subroutine. The clock block contains the request
type, the absolute time when request is to occur, and the bias and
APR5 displacement of the driver routine to be called when inserted in
the system clock queue.
A timer request is made by calling the
executive's $CLINS routine.
Input parameters to $CLINS are the
virtual address of the primary pool resident clock block, the request
type of "C.SYST", the high and low order time delta (in tics), and a
unique identifier. "C. SUB" is expected to contain the virtual address
of the driver routine to be called by executive's clock processor
(executive module TOSCH) when the specified interval of time has
elapsed. The unique identifier is used to dequeue timer requests
before completion and must be a unique executive (primary pool)
virtual address. This unique identifier could be a UCB address, or
even the address of the clock block itself. Note that since this
identifier is a system wide identifier, and an ad hoc value could
potentially corrupt the system.
Timer requests are one shot in nature and as such, the clock block is
dequeued by the TOSCH processing. The request must be respecified via
the $CLINS routine to achieve a periodic timer facility.
The driver
subroutine specified in the request will be called at system state at
processor priority O.
If it is necessary to cancel a timer request, this may be done by
removing the" clock block from the system's clock queue via the
executive's $CLRMV routine. The following examples further illustrate
the manipulations required:
i+

Example clock queue insertion and removal
Driver database contains clock block in UCB and thus avoids resource
allocation errors associated with dynamic allocation from primary
pool.

+---------------+
I

.BLKB C.LGTH

<--- driver specific clock block at U.MYCB

+---------------+
UCB

7-2

EXECUTIVE TIMER RELATED FACILITIES
i examples assume R5

=> UCB

The first example is a periodic polling of some device status. Though
status changes are traditionally communicated to the driver via an
interrupt, there are instances of when this hardware functionality is
not available.
INITIM:

MOV
ADD
MOV
CLR
MOV

R5,RO
#U.MYCB,RO
#POLL,C.SUB(RO)
Rl
#H$$RTZ/2,R2

UCB address
ipoint to clock block
ispecify address of timer routine
izero high order delta time
iget number of ticks per half
isecond
ifor low order time delta
iCOPY

Note that for a request type (6) "C.SYST" $CLINS will save
current APR5 mapping and restore it when time delta expires
before calling driver. The implication is that the virtual
address specified in C.SUB must be mapped through APR5 and that
the caller of $CLINS is also mapped through APR5 with the same
mapping. If a request type (8) "C.SYTK" is specified, then the
caller must have already specified the APR bias in C.AR5 in
addition to the virtual address in C.SUB. Calling $CLINS after
the clock block has already been inserted in the clock block can
cause unpredictable results including the removal of other system
timer requests as a result of the clock queue corruption. Should
this be a problem, C.RQT could be used as an interlock by
clearing it after clock queue removal and checking this word to
determine if the clock block is in use before attempting to call
$CLINS.
MOV
CALLR

#C.SYST,R4
$CLINS

ispecify request type
iinsert clock block into clock
iqueue
;and return to this subroutine's
icaller.

The driver is called at this entry point every .5 seconds. All
registers may be used by the driver and upon entry, R4 contains
the address of the clock block dequeued.
POLL:
MOV
CLR
MOV
MOV

R4,RO
Rl
#H$$RTZ/2,R2
C.TCB(RO) ,R5

ifirst, respecify clock request
;specify address of clock block
;init high order delta time
iinit low order delta time
iget address of identifier (UCB
;address despite symbolic offset
iname)
7-3

EXECUTIVE TIMER RELATED FACILITIES

CALL

$CLINS

;note that C.SUB is not modified
;and still valid.
irespecify timer request
;note that C.AR5, or C.SUB need
;not be respecified.

On return from $CLINS, (RO,R4, and R5) are unmodified.
;driver does what needs to be
;done
RETURN
The second example builds on the first example and illustrates
how to cancel a timer request.
The CANTIM routine may be called to remove the clock block
inserted above.
CANTIM:

MOV

R5,Rl

;specify identifier of clock
;block
;(in this case, the UCB address)

A clock block may be removed from the system clock queue however,
the listhead $CLKHD is not a double word listhead and therefore,
$QRMVT may not be called. $CLRMV can be called to remove clock
blocks from the system clock queue and if the request type was
not "C.SYST", the clock block will be deallocated from primary
pool. Therefore, if the driver's clock block is located in the
driver's database (such as in the UCB or KRB), only the request
type "C.SYST" should be specified.
MOV

#C.SYST,R4

CALL

$CLRMV

RETURN

7.3

;specify type of request to
;dequeue
;dequeue it (if there)

;return to caller

ADDRESSING A "TASK BUFFER

A typical user task has no knowledge
7-4

the

physical

locations

ADDRESSING A TASK BUFFER
every region mapped into its virtual space, since the physical
addresses ~f a task's regions can change due to checkpointing or
shuffling.* Given that a task can only specify the virtual address of
a buffer to a system directive such as QIO$, this virtual address must
be resolved to some form of an actual physical address being used
while the issuing task's context is loaded. Most I/O operations are
asynchronous to the execution of user tasks. As a result, the issuer
could change its virtual address space mapping, and thus invalidate
the specified virtual address. The executive assists the driver by
keeping a count of all ~ctive I/O requests on a per region basis, and
converting the user buffer virtual address in the first parameter to a
physical address for transfer functions.
If a region contains a
non-zero I/O count, the executive will not checkpoint or shuffle the
region.
This would both invalidate the physical
address
and
compromise the integrity of the system, since the outstanding I/O
could be transferred into the another region resident in memory.
For non-DMA devices, there are three common methods for
reference a task buffer:

driver

The simplest approach is to move the "bias" half of the
physical address double word into KISAR6 and then use the
"displacement-in-block" half, which has been adjusted by the
QIO directive processor to map through APR6 for transfer
functions. Unless the bias and displacement are adjusted by
the driver, the maximum size of the user task buffer is
limited to <4096.-32.> words.

In certain cases, it is not possible for the driver to unmap
KISAR6 because another structure, such as an intermediate
buffer (or possibly the driver code itself), is required to
be mapped.
These cases can use a method in which the
executive $BLXIO routine is used to temporarily unmap the
driver in KISAR5, map the source and destination buffers
through KISAR5 and KISAR6. It then performs the transfer and
restores the mapping.

Another method is useful for drivers that sequentially empty
or fill a task buffer word by word, or byte by byte. with
this method, the executive's $GTBYT, $GTWRD, $PTBYT and
$PTWRD routines unmap KISAR6, perform the transfer, adjust

* Checkpointing is the process of copying a region to a disk so it can
be used by another contending region. Shuffling is the process of
moving a region from one physical location to another location in
order
to
reduce
fragmentation.
Though a fixed region or a
non-checkpointable region cannot be checkpointed, it can be shuffled provided the region has a zero I/O count and is not explicitly marked
as non-shufflable (PS.NSF).
7-5

ADDRESSING A TASK BUFFER
the bias and displacement of the target buffer.
The buffer
could be as large as 32KW and restore the KISAR6 mapping (see
module BFCTL).

7.3.1

Address Checking a Task Buffer

Address checking is the process of validating that a buffer is fully
mapped within the task's virtual address space, that a buffer is
contained within one region, and that the issuing task has write
access to the region. A buffer can be checked for read only access or
read/write access, depending upon the I/O function.
For instance, an
IO.WLB or IO.WVB check the buffer for read-only access, since it is
known that the transfer will not write to the region.
Normally, a
driver does not need to explicitly address check the I/O buffer, as
the executive's QIO$ directive (see DRQIO) assumes this function for
transfer and ACP I/O functions.

7.3.2

010 Directive Processing Specifics

As the Executive processes a QIO directive,
conditions and performs actions as follows:

checks

for

certain

The specified LUN must be valid and assigned. If it is
a directive error IE.ILU or IE.ULN is returned.

The UCB address in LUN is resolved to
following the redirect pointer U.RED.

If I/O is stalled for the unit (US.SIO=l) or if a file
operation is pending (bit 0 in the second LUN word =1), the
issuing task's PC is modified so that the directive is
reissued at a later point in time after a significant event
occurs. The Files-ii reverification task (VER ... ) is allowed
to break through a stalled I/O state.

The driver must be resident.
(IE.HWR) is returned.

If an optional event flag is specified, it is validated and
cleared.
If
an invalid (non-existent) event flag is
specified, a directive error (IE.IEF) is returned.

An I/O packet is allocated from the primary pool.
If there
is insufficient pool to create the I/O packet, a directive
error (IE.UPN) is returned.

7-6

not,

the

target

directive

not,

UCB

error

ADDRESSING A TASK BUFFER
o

If the directive QIOW$ is received, the task is placed
"waitfor" state - if the event flag was specified.

An I/O rundown count (T.IOe) is incremented in
task control block.

The optional I/O status block is validated, and the contents
cleared.
The virtual address and physical address double
word of the I/O status block are stored in the I/O packet.

I/O packet fields are initialized and used
Table 7-2.

IO.KIL functions are always legal
and
are
processed
immediately by the executive. The driver's I/O packet queue
(listhead S.LHD) is flushed, whether the unit is online or
not, of all packets with the same TCB address and UCB address
if the device is not mounted with an associated ACP.
If the
unit is online and cancel notification has been requested by
the driver (UC.KIL=l), the driver is always called at the
D.VCAN entry point - independent of whether the unit was busy
or if any packets were flushed.
If the unit was busy at the
time of the cancel I/O request, the driver will be called.

Depending on device characteristics, unit status, and type of
function, specific processing is performed and the I/O packet
is either queued to the driver or to the ACP.

Table 7-1:
DV.MNT

the

issuer's

indicated

010 Processing By Function Type and Device Characteristics

I TYPE

I US.MNTI US. FORI US.LABI Checks and action performed

-----~--+-------+-------+-------+-------+----------------------------

0
0
0
0
1
1
1
1
1
1
1
1
1
1
1

N
C
T
A
N
C
T

A
C
C
C
T
T

A
A

1
1
1
0
0
0
0
0
0
0

1
0
0
1
0
1
0

1
0

1,2,IS.SUC is returned
1,2, A
1,2,B
1,2,3,B
2,IS.SUC is returned
2,1,A,6
2,4,B,6
2,5
2,1,A,6
2,7,A,6
2,1,A,6
2,8,B,6
2,9,B,6

2,8,C,6
(beyond scope of this table)

7-7

ADDRESSING A TASK BUFFER
where
N
NOP
C
Control
T = Transfer
A
ACP
1.

If the device unit is allocated (U.OWN <> 0 ), and not public
(US.PUB=O), then an I/O error of IE.PRI is return unless the
issuing task is privileged or the issuing task's TI is the
allocator ((T.UCB)=(U.OWN)).

If the function is not legal then an I/O error of IE.IFN is
returned.
Also, if the device unit is marked offline
(US.OFL=l) then an I/O error of IE.OFL is returned.

If function code is IO.RVB ((I.FCN+1)=IO.RVB/ 0400) then
function code is converted to IO.RLB and all subfunction bits
cleared. If function code is an IO.WVB, then subfunction is
converted to an IO.WLB again clearing all subfunction bits.

If device unit's volume status is not valid (US.VV=O) an
error of IE.PRI is returned.

ACP functions to a dismounted
error.

Task load overlay checks.
IO.LOV and IO.LOD
have
a
particular meaning for mountable devices, whether or not
device is mounted or not, and check is performed for both
control and transfer functions.
(These I/O functions are
equivilent to IO.RLB!10 or IO.RLB!110 .)

Control functions to a mounted ANSI tape required the
to be privileged.

issuer

An ACP must be associated with
error of IE.PRI is returned.

I/O

A transfer function to a mounted volume must
overlay function or the task must be privileged.

load

volume

the

result

unit

otherwise
be

I/O

IE.PRI

A control function format I/O packet is built and
to the driver.

A transfer function format I/O packet is built and queued
to the driver. If the I/O function was an IO.WVB or an
IO.WLB, then the buffer is address checked for read only
access, otherwise the buffer is checked to ensure that
the task has write access to the buffer's region.
7-8

queued

ADDRESSING A TASK BUFFER
C.

Table 7-2:
1/0 packet
Field

Same action as B except that packet is queued to ACP.

I/O Packet Usage by Function Type
control
Functions

Transfer
Functions

Notes

utility link word

I.LNK
I.PRI

(T.PRI)

I.EFN

(Q.IOLU)

I.TCB

($TKTCB)

I.LN2

($HEADR)+H.NLUN+2+«Q.IOLU-1>*4>+2

I. UCB

redirected UCB address

I.FCN

(Q.IOFN)

I.IOSB

virtual address of 1/0 status block

I.IOSB+2

bias of 1/0 status block

I.IOSB+4

disp. in blck+140000 of 1/0 status blck 5

I.AST

virtual address of 1/0 completion AST

I.PRM

(Q.IOPL)

bias of buffer

I.PRM+2

(Q.IOPL+2)

OIB+140000 of buf.

I.PRM+4

(Q.IOPL+4)

(Q.IOPL+2)

I.PRM+6

(Q.IOPL+6)

(Q.IOPL+4)

I.PRM+10

(Q.IOPL+I0)

(Q.IOPL+6)

I.PRM+12

(Q. IOPL+12)

(Q.IOPL+I0)

I.PRM+14

(Q.IOPL+12)

I.PRM+16

I.MDA

(Q.IOFN)

address of AOB

7-9

ADDRESSING A TASK BUFFER

I.AADA+2

Notes:
1.

If the high bit in the event flag byte field is set, it
indicates a virtual I/O function. I.PRM+16 is then treated
as a FILES-ll lock block during I/O completion. Mass storage
device drivers should ensure that I.PRM+16 is not used as
temporary storage of I/O context.

If the bit 0 is set in the contents (not the address) of the
second LUN word I.LN2, it indicates that this word contains
the window block pointer. If the function is virtual and
this word is even, the task's header (task region) has been
locked in memory by incrementing the attachment descriptor
I/O count and the task region's PCB I/O count.

UCB addresses in the task header are not fully resolved to
the target UCB, so a level of indirection is possible. For
instance, a task which is pre installed in the system before
boot may need to read a disk overlay from LB:. The UCB
address of the pseudo device LB: is in the LUN, and the
system has redirected the pseudo device to the physical boot
unit during the boot process to DW1:, DZ1:, or Dz2:.

The I.FCN word consists of two bytes. The high byte is
function code and the low byte is the subfunction code.
subfunction consists of eight independent bits which
interpreted within the context of the function code.
exceptions are as follows:

the
The
are
The

The subfunction IQ.UMD (4) stamps any I/O function as a
diagnostic
function,
independent
of
any
device
characteristics.

The subfunction IQ.X (1) means inhibit reties. It is
primary interest to mass storage device drivers.

The subfunction IQ.LCK (A0200) is used by FILES-l1 ACP
functions and will not be seen normally by the mass
storage device driver.

Another subfunction bit of concern to mass storage device
drivers occurs when "write checking" is requested on a
mounted volume. This is indicated by an IO.WLB function
with subfunction bit (20) specified.

7-10

ADDRESSING A TASK BUFFER
5.

I/O counts are not maintained for the I/O status block.
Therefore,
the I/O status block may not be accessed by the
driver except at predriver initialization time
(UC.QUE=l).
I/O completion processing uses the physical address of the
I/O status block, provided no event has occurred while I/O
was outstanding that would have invalidated this address
(such as unmapping a region, an EXTK$, or a checkpoint),
as
indicated by T3.MPC.
If such an event has occurred, the I/O
packet is converted into a kernel AST packet such that when
the task's context is loaded,
the virtual address can be
used. Note that system's integrity is preserved here, rather
than the issuing task's, if the task remapped or unmapped the
I/O status block. "In general, a task may not change the
virtual mapping of it's I/O status block, but can unmap an
I/O buffer if needed.
If I.IOSB+4 is odd, it indicates that the I/O packet is
internal I/O which was issued from another driver or system
process. When I/O is completed, a specified kernel mode
completion routine is called - rather than performing normal
I/O completion processing (see $IOFIN in IOSUB for details).
This is intended to be transparent to the driver.

7.4

THE ADDRESS DOUBLE WORD

P/OS 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-ll 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.
The virtual address in the DPB is structured as follows:
Bits 0 through 5

Displacement in terms of 32-word blocks

Bits 6 through 12

Block number

Bits 13 through 15

Page Address Register Number (PAR_#)

The internal P/OS translation restructures this virtual
7-11

address

into

THE ADDRESS DOUBLE WORD
an address doubleword as described in the following paragraphs.
The relocation base contained in the PAR specified by the PAR number
in the virtual address in the OPB is added to the block number in the
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 management registers.
The second word is formed by placing the displacement in block (bits 0
through 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
cleared.
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
transfer devices.
For nonprocessor request (NPR) devices, the driver requirements for
manipulating the address doubleword are direct and are discussed with
the description of U.BUF in Section 4.4.4.

7.5

SERVICE CALLS

This section 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-3 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-ll source files for the Executive modules.

7-12

SERVICE CALLS

Table 7-3:

Routine

Summary of Executive Service Calls for Drivers

Location in
Module

Name

Function
$ACHKB
$ACHCK
$ALOCB
$BLKCK
$BLKCl
$BLKC2
$BLXIO
$CKBFI
$CKBFR
$CKBFW
$CKBFB
$CLINS
$CVLBN
$DEACB
$FORK
$FORKl
$GTBYT
$GTPKT
$GSPKT
$GTWRD
$INIBF
$INTXT
$IOALT
$IODON
$IOFIN
$PTBYT
$PTWRD
$QINSP
$RELOC
$REQUE
$REQUl
$TSPAR

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

$TSTBF

IOSUB

Address check for byte-aligned buffers
Address check for word-aligned buffers
Alocate core buffer
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
Create a fork process
Fork but bypass clearing timeout count
Get byte
Get an I/O packet
Get a special I/O packet
Get word
Initiate I/O buffering
Interrupt exit
Alternate entry to $IODON
I/O done for completing an I/O request
I/O finish for special I/O completion
Put byte
Put word
Queue insertion by priority
Relocate address
Queue kernel AST to task
Queue kernel AST to task
Test if partition memory resident
for kernel AST
Test for I/O buffering

7-13

SERVICE CALLS

$ACHKB
$ACHCK

7.5.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.1 for an example.
Calling Sequences:
CALL

$ACHKB

CALL

$ACHCK

Description:
+
**-$ACHKB-ADDRESS CHECK BYTE ALIGNED
**-$ACHCK-ADDRESS CHECK WORD ALIGNED

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

SINCE PRIVILEGED TASK I /0 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 /0 INTO A COMMON WHICH IT ALLOWS TO REMAIN
7-14

SERVICE CALLS
CHECKPOINTABLE AND SHUFFLEABLE.
Note:
1.

In P/OS, 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.5.5 for a description of
$CKBFB/$CKBFW and Section 8.1 for an example.

7-15

SERVICE CALLS

$ALOCB

7.5.2

Allocate Core Buffer

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

$ALOCB

CALL

$ALOCl

Description:
i+

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

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

7-16

SERVICE CALLS
$BLKCK
$BLKCl
$BLKC2

7.5.3

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.
Calling Sequence:
CALL

$BLKCK

CALL

$BLKC2

Description:

;+
**-$BLKCK-LOGICAL BLOCK CHECK ROUTINE
**-$BLKC1-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
7-17

SERVICE CALLS
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-18

SERVICE CALLS

$BLXIO

7.5.4

Move Block of Data

This routine is in file BFCTL.
Calling Sequence:
CALL

$BLXIO

Description:
i+

**-$BLXIO-MOVE BLOCK OF DATA.
THIS ROUTINE IS CALLED TO MOVE DATA IN MEMORY IN A MAPPED
SYSTEM.
INPUTS:
RO=NUMBER OF BYTES TO MOVE.
Rl=SOURCE APRS BIAS.
R2=SOURCE DISPLACEMENT.
R3=DESTINATION APR6 BIAS.
R4=DESTINATION DISPLACEMENT.
OUTPUTS:
DESCRIBED MOVE IS ACCOMPLISHED.
RO ALTERED
R1,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 8KB-64.BYTES).

7-19

SERVICE CALLS

$CKBFI
$CKBFR
$CKBFW
$CKBFB

7.5.5

Check 1/0 Buffer

These routines are in file EXESB.
Calling Sequences:
CALL

$CKBFB (or appropriate entry name)

Description:
i+
i ,**-$CKBFI-CHECK I/O BUFFER FOR I-SPACE (OVERLAY) ACCESS

**-$CKBFR-CHECK I/O BUFFER FOR READ-ONLY (BYTE) ACCESS
**-$CKBFW-CHECK I/O BUFFER FOR READ-WRITE (WORD) ACCESS
**-$CKBFB-CHECK I/O 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.IOC 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
R1=LENGTH OF BUFFER TO BE CHECKED
7-20

SERVICE CALLS
$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-21

SERVICE CALLS

$CLINS

7.5.6

Clock Queue Insertion

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

$CLINS

Description:
i+

**-$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.

7-22

SERVICE CALLS

$CVLBN

7.5.7

Convert Logical Block Number

This routine is in the file MDSUB. The input to this routin~ is the
same as the output from the $BLKCK routine. Typically, a disk driver
calls this routine to convert a logical block number to a physical
disk address.
The routine accesses the U.PRM fields in the driver
data base unit control block. These fields contain the sector, track,
and cylinder parameters for the type of disk supported. Refer to the
description of the U.PRM fields in Section 4.4.4.
Calling Sequence:
CALL

$CVLBN

Description:
i+

**-$CVLBN-CONVERT LOGICAL BLOCK NUMBER TO DISK PARAMETERS
THIS SUBROUTINE WILL CONVERT THE SPECIFIED LOGICAL BLOCK
NUMBER TO A SECTOR/TRACK/CYLINDER ADDRESS.
INPUTS:
(SAME AS $BLKCK OUTPUTS)
RO=LOW PART OF LBN
R2=HIGH PART OF LBN
R3=I/O PACKET ADDRESS
R5=UCB ADDRESS
OUTPUTS:
RO=SECTOR NUMBER
Rl=TRACK NUMBER
R2=CYLINDER NUMBER
;-

7-23

SERVICE CALLS

$DEACB

7.5.8

Dea1locate Core Buffer

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

$DEACB

CALL

$DEACl

Description:

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

;

THE CORE BLOCK IS MERGED INTO THE FREE CORE CHAIN BY CORE.
ADDRESS AND IS AGLOMERATED IF NECESSARY WITH ADJACENT
BLOCKS.

7-24

SERVICE CALLS

$FORK

7.5.9

Fork

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

$FORK

Description:
i+

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

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.

7-25

SERVICE CALLS
If the clearing of the timeout count is not desired, a driver
has two alternatives:

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

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

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

7-26

the

stack

when

SERVICE CALLS

$FORK1

7.5.10

Forkl

Fork1 is in the file SYSXT. A driver calls $FORK1 to bypass the
clearins of its timeout count when it switches from a partially
interruptable level to a fully interruptable level (refer also to the
description of the $FORKroutine).
Calling Sequence:
CALL

$FORK1

Description:
i+

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

Notes:
1.

A 5-word fork block is required for calls to $FORK1.

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
$FORKl is called.

7-27

the

stack

when

SERVICE CALLS

$GTBYT

7.5.11

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

Description:
i+

**-GTBYT-GET NEXT BYTE FROM USER BUFFER
THIS ROUTINE IS CALLED TO GET THE NEXT BYTE FROM THE USER BUFFER
AND RETURN IT TO THE CALLER ON THE STACK. AFTER THE BYTE HAS
BEEN FETCHED, THE NEXT BYTE ADDRESS IS INCREMENTED.
INPUTS:
R5=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS.
OUTPUTS:
THE NEXT BYTE IS FETCHED FROMT HE USER BUFFER AND RETURNED
TO THE CALLER ON THE STACK. THE NEXT BYTE ADDRESS IS
INCREMENTED.
i

ALL REGISTERS ARE PRESERVED ACROSS CALL.
i-

7-28

SERVICE CALLS

$GTPKT
$GSPKT

7.5.12

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 Section 4.3. Usage of $GSPKT is described briefly in
Section 1.4.3.
Calling Sequences:
CALL

$GTPKT

CALL

$GSPKT

Description:
i+

**-$GTPKT-GET I/O PACKET FROM REQUEST QUEUE
**-$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 RETURNED TO THE CALLER. ELSE AN ATTEMPT
IS MADE TO DEQUEUE THE NEXT REQUEST FROM THE CONTROLLER QUEUE.
IF NO REQUEST CAN BE DEQUEUED, THEN A CARRY SET INDICATION IS
RETURNED TO THE CALLER. ELSE THE CONTROLLER IS SET BUSY AND A
CARRY CLEAR INDICATION IS RETURNED TO THE CALLER.
IF QUEUE OPTIMIZATION IS SUPPORTED AND ENABLED FOR THE DEVICE
THE APROPRIATE PACKET FOR THE CURRENT OPTIMIZATION ALGORITHM
IS RETURNED. THREE ALGORITHMS ARE SUPPORTED: NEAREST CYLINDER,
ELEVATOR, 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.
THE ALTERNATE ENTRY POINT $GSPKT IS INTENDED FOR USE BY DRIVERS
WHICH SUPPORT PARALLEL OPERATIONS ON A SINGLE UNIT, A COMMON
EXAMPLE BEING FULL DUPLEX.
SUCH DRIVERS ARE EXPECTED TO LOOK TO
THE SYSTEM AS IF THEY 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

7-29

SERVICE CALLS
; REQUESTS IN PARALLEL WITH OUTPUT REQUESTS. A 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 TaE 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.

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.
THESE
FIELDS ARE AVAILABLE FOR DRIVER-SPECIFIC USE.

BUSYING OF UCB AND SCB.

EXECUTION OF $CFORK TO GET TO PROPER PROCESSOR
(MULTI-PROCESSOR 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=l IF CONTROLLER IS BUSY OR NO REQUEST CAN BE DEQUEUED.
C=O IF A REQUEST WAS SUCCESSFULLY DEQUEUED.
Rl=ADDRESS OF THE I/O PACKET.
R2=PHYSICAL UNIT NUMBER.
R3=CONTROLLER INDEX.
R4=ADDRESS OF THE STATUS CONTROL BLOCK.
7-30

SERVICE CALLS
R5=ADDRESS OF THE UNIT CONTROL BLOCK.
NOTE: R4 AND R5 ARE DESTROYED BY THIS ROUTINE.
;-

7-31

SERVICE CALLS

$GTWRD

Get Word

7.5.13

Get Word is in the file BFCTL.
in the UCB.

It manipulates words U.BUF and U.BUF+2

Calling Sequence:
CALL

$GTWRD

Description:
i+

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

ALL REGISTERS ARE PRESERVED ACROSS CALL.

7-32

SERVICE CALLS

$INIBF

7.5.14

Initiate I/O Buffering

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

$INIBF

Description:
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-33

SERVICE CALLS

$INTXT

7.5.15

Interrupt Exit

Interrupt Exit is in the file SYSXT.
Calling Sequence:
JMP

$INTXT

Description:

;+
**-$INTXT-INTERRUPT EXIT
THIS ROUTINE MAY BE CALLED VIA A JMP TO EXIT FROM AN INTERRUPT
INPUTS:
O(SP)=INTERRUPT SAVE RETURN ADDRESS.
OUTPUTS:
A RETURN TO INTERRUPT SAVE IS EXECUTED.
;-

7-34

SERVICE CALLS

$ IOALT/$IODON

7.5.16

I/O Done Alternate Entry and 1/0 Done

These routines are in the file IOSUB.
Calling Sequences:
CALL

$IOALT

CALL

$IODON

Description:
i+

**-$IOALT-I/O DONE (ALTERNATE ENTRY)
**-$IODON-I/O DONE
THIS ROUTINE IS CALLED BY DEVICE DRIVERS AT THE COMPLETION OF AN
I/O REQUEST TO DO FINAL PROCESSING. THE UNIT AND CONTROLLER ARE
SET IDLE AND $IOFIN IS ENTERED TO FINISH THE PROCESSING.
INPUTS:
RO=FIRST I/O STATUS WORD.
R1=SECOND I/O STATUS WORD.
R2=STARTING AND FINAL ERROR RETRY COUNTS IF ERROR LOGGING
DEVICE.
R5=ADDRESS OF THE UNIT CONTROL BLOCK OF THE UNIT BEING
COMPLETED.
(SP)=RETURN ADDRESS TO DRIVER'S CALLER.
NOTE: IF ENTRY IS AT $IOALT, THEN Rl IS CLEAR TO SIGNIFY
THAT THE SECOND STATUS WORD IS ZERO.
OUTPUTS:
THE UNIT AND CONTROLLER ARE SET IDLE.
ALL REGISTERS ARE DESTROYED.
i-

Note:
1.

All registers are destroyed when either of these routines
called.

7-35

SERVICE CALLS

$IOFIN

1/0 Finish

7.5.17

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

$IOFIN

Description:
i+

**-$IOFIN-I/O FINISH
THIS ROUTINE IS CALLED TO FINISH I/O PROCESSING IN CASES WHERE
THE UNIT AND CONTROLLER ARE NOT TO BE DECLARED IDLE. IF THE TASK
WHICH ISSUED THE I/O HAS HAD A RECENT MAPPING CHANGE WHICH MAY
HAVE UNMAPPED ITS I/O STATUS BLOCK, THE I/O PACKET IS QUEUED TO
THE FRONT OF ITS AST QUEUE TO BE COMPLETED LATER IN $FINBF BY
CALLING $IOFIN AGAIN.
INPUTS:
RO=FIRST I/O STATUS WORD.
Rl=SECOND I/O STATUS WORD.
R3=ADDRESS OF THE I/O REQUEST PACKET.
OUTPUTS:
THE FOLLOWING ACTIONS ARE PERFORMED
1-THE FINAL I/O STATUS VALUES ARE STORED IN THE I/O
STATUS BLOCK IF ONE WAS SPECIFIED.
2-ALL ASSOCIATED I/O COUNTS ARE DECREMENTED AND TS.RDN IS
CLEARED IN CASE THE TASK WAS BLOCKED FOR I/O RUNDOWN.
T3.MPC IS CLEARED IF THE TASK I/O COUNT GOES TO ZERO TO
INDICATE THAT THE I/O COUNT WENT TO ZERO AFTER A
MAPPING CHANGE.
3-IF 'TS.CKR' IS SET, THEN IT IS CLEARED AND
CHECKPOINTING OF THE TASK IS INITIATED.
7-36

SERVICE CALLS

4-IF AN AST SERVICE ROUTINE WAS SPECIFIED, THEN AN AST IS
QUEUED FOR THE TASK, ELSE THE I/O PACKET IS DEALLOCATED.
5-A SIGNIFICANT EVENT OR EQUIVALENT IS DECLARED.
;

NOTE: R4 IS DESTROYED BY THIS ROUTINE.
;-

7-37

SERVICE CALLS

$PTBYT

7.5.18

Put Byte

Put Byte is in the file BFCTL.
U.BUF+2 in the UCB.

Put Byte manipulates words

U.BUF

and

Calling Sequence:
$PTBYT

CALL

Description:
i+

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

7-38

SERVICE CALLS

$PTWRD

7.5.19

Put Word

Put Word is in the file BFCTL.
in the UCB.

It manipulates words U.BUF and U.BUF+2

Calling Sequence:
CALL

$PTWRD

Description:

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

7-39

SERVICE CALLS

$QINSP

7.5.20

Queue Insertion by Priority

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

$QINSP

Description:
i+
**~$QINSP-QUEUE

INSERTION BY PRIORITY

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

7-40

SERVICE CALLS

$RELOC

7.5.21

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.1 for an example.
Calling Sequence:
$RELOC

CALL
Description:
i+

**-$RELOC-RELOCATE USER VIRTUAL ADDRESS
THIS ROUTINE IS CALLED TO TRANSFORM A 16-BIT USER VIRTUAL
ADDRESS INTO A RELOCATION BIAS AND DISPLACEMENT IN BLOCK
RELATIVE TO APR6.
INPUTS:
RO=USER VIRTUAL ADDRESS TO RELOCATE.
OUTPUTS:
Rl=RELOCATION BIAS TO BE LOADED INTO PAR6.
R2=DISPLACEMENT IN BLOCK PLUS 140000 (PAR6 BIAS).
;

RO AND R3 ARE PRESERVED ACROSS CALL.

7-41

SERVICE CALLS

$REQUE
$REQUl

7.5.22

Queue Kernel AST to Task

This routine is in module IOSUB.
Calling Sequence:
CALL

$REQUE

CALL

$REQUl

Description:
i+

i**-$REQUE-REQUEUE A REGION LOAD AST TO A TASK AST.
i**-$REQU1-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-42

SERVICE CALLS

$TSPAR

7.5.23

Test if Partition Memory Resident for Kernel AST

This routine is in file REQSB.
Calling Sequence:
CALL

$TSPAR

Description:
;**-$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
A 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.
;-

7-43

SERVICE CALLS

$TSTBF

Test for 1/0 Buffering

7.5.24

This routine is in file IOSUB.
Calling Sequence:
CALL

$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+16 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.
i-

7.6

ADDING PHYSICAL MEMORY TO THE PIOS CONFIGURATION

Option modules that contain additional
(possibly special purpose)
memory,
can allow it to be accessible to the system and applications
by calling the privileged executive subroutine $STPAR
in
the
distributed PRVLIB.OLB object library.
It must be called at system
state.
In order to access the executive vector table, kernel APR6 is
used. Therefore, the routine must be mapped through APR5 when called.
This routine is system version independent. Note that system state
may be entered without the necessity of being bound to the system
version, by using the SWST$ directive.

7-44

ADDING PHYSICAL MEMORY TO THE PjOS CONFIGURATION
If the additional memory is general purpose and there are no
restrictions on its use, it may be added to the "GEN" main
partition. Tasks, commons, and most PLAS regions are allocated
from GEN on demand. If the memory is to be used for a dedicated
purpose, a main partition of the name "$PARsx" can be specified where "s" is the logical slot number corresponding to the slot in
which the board is located and "x" is any legal RAD50 character.
This convention reduces the likelihood of a collision on the
partition name. The partition name must be unique among all of
the (region and partition) names in the system. Dedicated memory
can be accessed, specifying the given main partition name in the
creation of a PLAS region subpartition. Memory is allocated from
the main partition, using a "first fit" algorithm unless the
region is being fixed. If it is, the region is loaded high. If
the region is already in memory, an attempt is made to checkpoint
it so that it can be loaded high. Once additional memory has
been added to the system configuration, it cannot be removed.
If adding memory to the "GEN" partition, do not exit system state
until you have turned on the physical memory and configured the
base address to the value returned by $STPAR.
The calling interface to $STPAR is as follows:
i+

$STPAR -- add additional memory to system configuration
Inputs:
Rl = base address modulus-l (modulus granularity = 64 bytes)
for example, if a base address modulus of 128KB was
required, this parameter would be 3777(8).
R2
size of memory to add (granularity = 32 Kbytes)
R3
address of the name of main partition
(must be unique if not "GEN
")
(if the partition name "GEN
"is specified, the
additional memory will be appended to to this
main partition.)

7-45

ADDING PHYSICAL MEMORY TO THE P/OS CONFIGURATION
Output:
C=O,
R2
base address of the region (granularity = 64 bytes)
C=l,
partition name already exists
R2
insufficient space in available physical
R2 = 2
address space
R2
4
insufficient primary pool space to allocate
required PCBs
R2 = 6
$STPAR uses the vectoring scheme described in
this section in addressing several executive
subroutines. If any of the IDENTS of the
vectored subroutines do not match the IDENTS
that $STPAR expects, $STPAR will fail with
this error code.

This is an example of using the _$STPAR routine .
.b
i+
i This
i -

test program will call $STPAR to extend the GEN partition.

.MCALL DIR$,SWST$,EXIT$S,WIMP$
In order to guarantee that both this code and the code in module
$STPAR are mapped by APR5 during execution in system state,
declare this code to reside in the PSECT $STPAQ, which the task
builder will locate directly preceding PSECT $STPAQ of module
$STPAR .
. PSECT $STPAQ,I,GBL
START:
Verify that this is a V2.0 or later system. To do this,
invoke the WIMP$ directive to retrieve the system version
number. Since this form of the WIMP$ directive was not implementec
before V2.0, if the directive fails, assume that it is not a
V2.0 system.
MOV
DIR$
BCS

#-2,RO
#WIMP
5$

MOV
MOV

#777,Rl
#20,R2

DIR$

#SWITCH

iASSUME VERSION # FAILURE
iGET VERSION
iVERSION NOT AVAILABLE
iMUST BE PRE V2.0
iBIAS MASK (32KB BOUNDARY)
iSIZE OF PARTITION = 2000000 (=512.KB)
<16.>*<32KB>
iDROP THROUGH THE LOOKING GLASS
7-46

ADDING PHYSICAL MEMORY TO THE PjOS CONFIGURATION

TST
BEQ

RO
10$

i(ENTER SYSTEM)
iDID AN ERROR OCCUR?
iIF EQ NO

CALL

ERRMSG

iYES, DO SOMETHING

5$:
10$:
EXIT$S
SWITCH:

iEXAMPLES HAVE NO REAL FUNCTION
SWST$

STPAR:
CLR
MOV
MOV
CALL
MOV
MOV
BCS

START,STPAR

CLR
S.WSRO(SP) iiASSUME SUCCESS
-(SP)
iiSPECIFY SECOND HALF OF PARTITION NAME
#ARGEN,-(SP) iiSPECIFY FIRST HALF OF PARTITION NAME
SP,R3
iiPOINT TO NAME
$STPAR iiEXPAND GEN
(SP)+,(SP)+ iiPOP STACK TWICE WITHOUT AFFECTING
i iC-BIT
R2,S.WSR1(SP) iiQUALIFY ERROR IF FAILURE
10$
iiIF CS ERROR OCCURRED

The memory has been configured in system data structures.
It must
be enabled at this point. Code in module TURNON must also reside in
same APR5 mapping as this routine and $STPAR.
;

5$:

CALL

10$:

BCC
20$
MOV
#-l,S.WSRO(SP) iiINDICATE FAILURE TO PROVIDE MEMORY
RETURN

20$:

TURNON

iiENABLE MEMORY AND SET BASE ADDR.
iiBIAS AT VALUE RETURNED IN R2 BY $STPAR

Turn on memory
Input:

R2 contains base address bias (in units of-64. bytes)
of new memory

TURNON:
i CODE HERE TO ENABLE MEMORY

RETURN
; Error messages
i
i

i
i
;

This subroutine runs entirely in user mode, so it should not occupy
the same PSECT as system state routines.
Input:

= error code

7-47

ADDING PHYSICAL MEMORY TO THE PIOS CONFIGURATION
.PSECT

USRCOD

iuser code psect

ERRMSG:
i

ERROR HANDLING
RETURN
.PSECT

WIMP:

DBPS,D
WIMPS

BUFSIZ = 9.

GI.FMK,BUF,BUFSIZ

iGET SYSTEM IDENT

iTHIS FORM OF WIMPS RETURNS 9.
iWORDS

BUF:

7.1

. BLKW

.END

START

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS

In order to allow greater system version independence for
privileged tasks and device drivers, a simple vectoring scheme
has been implemented in PIOS version 2.0 and later.
Prior to version 2.0, a privileged task was needed to link with
the system's symbol table file to resolve references to various
executive routine and data structure addresses.
Since these
addresses changed with every system version, it was necessary to
rebuild the component for each version of the system.
By
creating a set of absolute addresses which point to various
tables, a privileged component can resolve
the
necessary
addresses at runtime.
While it cannot be guaranteed, DIGITAL will attempt to maintain
upward compatibility of the PIOS executive data structures and
routines. Therefore, the tables provided below are on a "USE AT
YOUR OWN RISK" basis.
In particular, the data structures may
change in future versions of P/OS.
Each vectored executive
routine is stamped with an IDENT which may be used as a validity
check during initialization.
There are three absolute pointers in the PIOS executive.
The
first points to the executive module LOWCR, the second to SYSCM
and the third pointer consists of a bias and a displacement
offset by 140000, which is used to map the executive routine
vector table. In addition, the $BTMSK bit table has been moved
to an absolute location.

7-48

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS

r.1.1

Pointer Location and Format

~he vector table pointers are located in the
Locations:

following

absolute

Symbolic Name

Address

Description

$BTMSK
$VECLC
$VECSC
$VECVT

1002
1042
1044
1046
1050

bitmask table
address of $STACK
address of $CMBEG
bias of vector table
displacement+140000(8)

rhe executive routine vector table's format is:
.WORD
. WORD
. WORD

$VECVT--)

number of vectors in table
$XXX,reserved,IDENT
;entry point 0
$XXX,reserved,IDENT
;entry point 1

where,
$xxx
reserved

is the address of the executive routine
is not currently used though may be used in
the future to contain a bias.
is a value associated with the particular
routine which is incremented when the routine
changes in a non upward compatible manner.

IDENT

7.1.2

Referencing LOWCR and SYSCM Data Structures

The following example illustrates one method
executive data structure reference at runtime .
. MCALL

QIOW$S,EXIT$S

.PSECT

DATA,D

MYTCB:

. WORD

$TKTCB-$STACK

ARGBLK:
BUF:

.BLKW
. BLKB

80.

FORMAT:

.ASCIZ
. EVEN

binding

;system macros

;form offset from base of
;LOWCR to $TKTCB (absolute)
;argument block/taskname buf
;output buffer

/My name is %2R and I got it the hard way/

7-49

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS
.PSECT

CODE,I

This task prints its taskname and exits. Could have been
done simpler using GTSK$ however, the example is one
technique to resolve the symbol $TKTCB in LOWCR.
INIT:

MOV
CALL
ADD
MOV
MOV
MOV
RETURN

TYPIT:

MOV
MOV
MOV
CALL
QIOW$S
EXIT$S
.END

7.1.3

#ARGBLK,R2
ipoint at taskname buffer
$SWSTK,TYPIT
ienter system state
@#$VECLC,MYTCB ;resolve address of $TKTCB
MYTCB,R5
;get current task's TCB addr
T.NAM(R5),(R2)+ iget my task name
T.NAM+2(R5),(R2)
ireturn to user state (which
;restores registers)
#BUF,RO
ipoint at output buffer
#FORMAT,Rl
ipoint to format string
#ARGBLK+2,R2
ipoint to argument block
$EDMSG
iformat output
#IO.WVB,#5,#5",,<#BUF,Rl,#40> ioutput to msg

iexit
INIT

Referencing Executive Routines

The following example subroutine illustrates
referencing a vectored executive routine .
. PSECT
TKTCB:
SETFG:

HIVEC:

one

method

DATA,D
;offset in LOWCR to $TKTCB
;entry point symbols defined
i in PRVLIB
iversion number at time routine
i written
ieach entry point consists of 3
; words .

$TKTCB-$STACK
SETFG$
. WORD

. WORD

SETFG$/<3*2>

. PSECT

CODE,I

This subroutine sets the this task's local event flag the
hard way. (It illustrates the vectoring as opposed to a
SETF$ replacement.)
SETF:

CLR
CALL
ADD
MOV

$ERROR
$SWSTK,20$
@#VECLC,TKTCB
@#KISAR6,-(SP)

;enter system state
iresolve reference to $TKTCB
isave current APR6 mapping

7-50

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS
MOV
MOV
CMP
BHI
ADD
CMP
BNE
MOV
MOV
MOV
CALL
10$:
15$:
20$:

7.1.4
1
2
3
4
5
6
7
8

BR
DEC
MOV
RETURN

@#$VECVT,@#KISAR6 imap vector table
@#VECVT+2,Rl
ipoint to vector table
HIVEC,-2(Rl)
idoes vector table describe
ientry point?
10$
iif hi vectoring error has
ioccurred
SETFG,R1
ipoint to entry point in table
SETFG+2,4(Rl)
isame IDENT?
10$
iif ne no, routine has changed
(R1) , R1
iresolve reference to $SETFG
#l,RO
ispecify event flag to set
@TKTCB,R5
iget this task's TCB address
(R1)
iset a this task's local event
iflag 1
15$
$ERROR
(SP)+,@#KISAR6

Executive Routine Vector Table
.TITLE EXEVEC
.IDENT /01.00/
COPYRIGHT (c) 1984 BY DIGITAL EQUIPMENT CORPORATION.
ALL RIGHTS RESERVED.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED
OR COPIED ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE.

9
10
11
12 i+
EXEVEC -- THIS MODULE DEFINES SELECTED EXECUTIVE ENTRY POINTS
13
14
SO THAT DRIVERS AND PRIVILEGED TASKS MAY BE SYSTEM
15
VERSION INDEPENDENT. THERE IS NO IMPLIED GUARANTEE
16
THAT THE EACH ENTRY POINT'S INTERFACE WILL REMAIN STABLE
THOUGH THERE IS SOME INTEREST IN KEEPING THEM UPWARD
17
COMPATIBLE IF POSSIBLE. AN IDENT HAS BEEN PROVIDED
18
WHICH CAN BE USED TO IDENTIFY THE VERSION OF THE
19
20
REFERENCED ROUTINE.
21 i-

$ALOCB --

ALLOCATE CORE BLOCK

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

7-51

1 MODULE NAME = CORAL
ALOCB$ OFFSET VALUE= 0

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS

$DEACB --

DEALLOC. CORE BLK

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$ALOC1 --

ALLOC. CORE BLK (SPECIFIABLE LSTHD)

ROUTINE VERSION NUMBER
VECTOR TABLE OFFSET NAME

$DEAC1 --

1 MODULE NAME = CORAL
DECLK$ OFFSET VALUE= 36

ALLOC. I/O PACKET

ROUTINE VERSION NUMBER
VECTOR TABLE OFFSET NAME

$DEPKT --

1 MODULE NAME = CORAL
ALCLK$ OFFSET VALUE= 30

DEALLOC. CLOCK QUEUE CORE BLK

ROUTINE VERSION NUMBER
VECTOR TABLE OFFSET NAME

$ALPKT --

1 MODULE NAME = CORAL
DEAC1$ OFFSET VALUE= 22

ALLOC. CLOCK QUEUE CORE BLK

ROUTINE VERSION NUMBER
VECTOR TABLE OFFSET NAME

$DECLK --

1 MODULE NAME = CORAL
ALOC1$ OFFSET VALUE= 14

DEALLOC. CORE BLK (SPECIFIABLE LSTHD)

ROUTINE VERSION NUMBER
VECTOR TABLE OFFSET NAME

$ALCLK --

= 1 MODULE NAME = CORAL
DEACB$ OFFSET VALUE= 6

1 MODULE NAME = CORAL
ALPKT$ OFFSET VALUE= 44

DEALLOC. I/O PACKET

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

7-52

1 MODULE NAME = CO~AL
DEPKT$ OFFSET VALUE= 52

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS
$ALSEC --

ALLOC. SECONDARY POOL CORE BLK

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$DESEC --

= 1 MODULE NAME = CORAL
ALSEC$ OFFSET VALUE= 60

DEALLOC. SECONDARY POOL CORE BLK

ROUTINE
VERSION NUMBER
1 MODULE NAME = CORAL
VECTOR TABLE OFFSET NAME = DESEC$ OFFSET VALUE= 66

$GTBYT --

GET NEXT BYTE FROM USER BUFFER

ROUTINE
VERSION NUMBER = 1 MODULE NAME = BFCTL
VECTOR TABLE OFFSET NAME = GTBYT$ OFFSET VALUE= 74

$PTBYT --

PUT NEXT BYTE IN USER BUFFER

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$GTWRD --

= 1 MODULE NAME = BFCTL
PTBYT$ OFFSET VALUE= 102

GET NEXT WORD FROM USER BUFFER

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

= 1 MODULE NAME = BFCTL
GTWRD$ OFFSET VALUE= 110

;

$PTWRD --' PUT NEXT WORD IN USER BUFFER
ROUTINE
VERSION NUMBER = 1 MODULE NAME = BFCTL
VECTOR TABLE OFFSET NAME = PTWRD$ OFFSET VALUE= 116

$BLXIO --

MOVE BLOCK OF DATA

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$CLINS --

1 MODULE NAME = BFCTL
BLXIO$ OFFSET VALUE= 124

CLOCK QUEUE INSERTION

7-53

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS
ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$CLRMV --

CLOCK QUEUE REMOVAL

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$QINSF --

= 1 MODULE NAME = QUEUE
QINSP$ OFFSET VALUE= 154

QUEUE INSERTION AT BEGINNING

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$QRMVA --

= 1 MODULE NAME = QUEUE
QINSF$ OFFSET VALUE= 146

QUEUE INSERTION BY PRIORITY

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$QINSB --

= 1 MODULE NAME = QUEUE
CLRMV$ OFFSET VALUE= 140

QUEUE INSERTION AT END OF LIST

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$QINSP --

= 1 MODULE NAME = QUEUE
CLINS$ OFFSET VALUE= 132

= 1 MODULE NAME = QUEUE
QINSB$ OFFSET VALUE= 162

QUEUE REMOVAL BY BLOCK ADDRESS

VERSION NUMBER
= 1 MODULE NAME = QUEUE
ROUTINE
VECTOR TABLE OFFSET NAME = QRMVA$ OFFSET VALUE= 170

$QRMVT --

QUEUE REMOVAL BY TCB ADDRESS

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$QSPIB --

= 1 MODULE NAME = QUEUE
QRMVT$ OFFSET VALUE= 176

QUEUE INSERTION (SEC. POOL) AT BEG.

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

7-54

= 1 MODULE NAME = QUEUE
QSPIB$ OFFSET VALUE= 204

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS

$QSPIF --

QUEUE INSERTION (SEC. POOL) AT END.

VERSION NUMBER
ROUTINE
VECTOR TABLE OFFSET NAME

$QSPRF --

QUEUE REMOVAL (SEC. POOL) FROM FRONT

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$QSPIP --

= 1 MODULE NAME = EXESB
ACHCK$ OFFSET VALUE= 242

ADDRESS CHECK BYTE ALIGNED (NO I/O CNTS)

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$ACHRO --

1 MODULE NAME = QUEUE
GTSPK$ OFFSET VALUE= 234

ADDRESS CHECK WORD ALIGNED (NO I/O CNTS)

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$ACHKB --

= 1 MODULE NAME = QUEUE
QSPIP$ OFFSET VALUE= 226

QUEUE REMOVAL (SEC. POOL) BY BLK ADR

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$ACHCK --

1 MODULE NAME = QUEUE
QSPRF$ OFFSET VALUE= 220

QUEUE INSERTION (SEC. POOL) BY PRI.

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$GTSPK --

= 1 MODULE NAME = QUEUE
QSPIF$ OFFSET VALUE= 212

= 1 MODULE NAME = EXESB
ACHKB$ OFFSET VALUE= 250

ADDRESS CHECK FOR READONLY ACCESS NO IOC

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

7-55

= 1 MODULE NAME = EXESB
ACHRO$ OFFSET VALUE= 256

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS

$CKBFW --

CHECK I/O BUFFER FOR READONLY (BYTE)

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$CKBFB --

CHECK I/O BUFFER FOR READWRITE (BYTE)

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$CKBFR --

= 1 MODULE NAME = EXESB
CKBFW$ OFFSET VALUE= 264

= 1 MODULE NAME = EXESB
CKBFB$ OFFSET VALUE= 272

CHECK I/O BUFFER FOR READWRITE (WORD)

ROUTINE
VERSION NUMBER
= 1 MODULE NAME = EXESB
VECTOR TABLE OFFSET NAME = CKBFR$ OFFSET VALUE= 300

$CEFIG --

CONVERT EVENT FLAG AND LOCK FOR I/O

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$CEFI --

CONVERT EVENT FLAG FOR I/O

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$CVDVN --

1 MODULE NAME = EXESB
CVDVN$OFFSET VALUE= 322

MAP LOGICAL UNIT NUMBER

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$MPLND --

= 1 MODULE NAME = EXESB
CEFI$ OFFSET VALUE= 314

CONVERT DEV NAM AND LOGICAL UNIT TO UCB

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$MPLNE --

= 1 MODULE NAME = EXESB
CEFIG$ OFFSET VALUE= 306

= 1 MODULE NAME = EXESB
MPLNE$ OFFSET VALUE= 330

MAP LOGICAL UNIT NUMBER (ALTRN. ENTRYPT)

7-56

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS

ROUTINE
VERSION NUMBER
= 1 MODULE NAME = EXESB
VECTOR TABLE OFFSET NAME = MPLND$ OFFSET VALUE= 336

$TKWSE --

WAIT FOR SIGNIFICANT EVENT

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$RELOC -;

RELOCATE USER VIRTUAL ADDRESS

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$RELOM --

= 1 MODULE NAME = MEMAP
RELOM$ OFFSET VALUE= 360

CONVERT LOGICAL BLOCK NUMBER TO DISK PARAMS

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$BLKCK --

= 1 MODULE NAME = MEMAP
RELOC$ OFFSET VALUE= 352

RELOCATE AND MAP USER VIRTUAL ADDRESS

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$CVLBN --

= 1 MODULE NAME = EXESB
TKWSE$ OFFSET VALUE= 344

= 1 MODULE NAME = MDSUB
CVLBN$ OFFSET VALUE= 366

LOGICAL BLOCK CHECK ROUTINE

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

1 MODULE NAME = MDSUB
BLKCK$ OFFSET VALUE= 374

$BLKCl --

LOGICAL BLOCK CHECK ROUTINE ALTRN. ENTRYPT

ROUTINE
VERSION NUMBER
1 MODULE NAME = MDSUB
VECTOR TABLE OFFSET NAME = BLKC1$ OFFSET VALUE= 402

$BLKC2 --

LOGICAL BLOCK CHECK ROUTINE FOR QUEUE OPT

;

ROUTINE

VERSION NUMBER

7-57

1 MODULE NAME = MDSUB

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS
VECTOR TABLE OFFSET NAME

$RQCNC --

BLKC2$ OFFSET VALUE= 410

REQUEST CONTROLLER FOR CONTROL OPERATION

;

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$RQCND --

REQUEST CONTROLLER FOR DATA TRANSFER

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$RLCN --

= 1 MODULE NAME = MDSUB
VOLVD$ OFFSET VALUE= 440

VOLUME STATUS CHANGE

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$DECIO --

= 1 MODULE NAME = MDSUB
RLCN$ OFFSET VALUE= 432

PREPROCESS VOLUME VALID FUNCTION

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$VOLSC --

= 1 MODULE NAME = MDSUB
RQCND$ OFFSET VALUE= 424

RELEASE CONTROLLER

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$VOLVD --

= 1 MODULE NAME = MDSUB
RQCNC$ OFFSET VALUE= 416

= 1 MODULE NAME = OLRSR
VOLSC$ OFFSET VALUE= 446

DECREMENT I/O COUNT VIA ADB

VERSION NUMBER
ROUTINE
VECTOR TABLE OFFSET NAME

= 1 MODULE NAME = IOSUB
DECIO$ OFFSET VALUE= 454

;

$DECIP --

DECREMENT I/O COUNT PARTITION ONLY

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

7-58

= 1 MODULE NAME = IOSUB
DECIP$ OFFSET VALUE= 462

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS

$GTPKT --

GET I/O PACKET FROM REQUEST QUEUE

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$GSPKT --

GET SELECTIVE I/O PACKET FROM REQUEST QUEUE

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$TSTBF --

1 MODULE NAME = IOSUB
GTPKT$ OFFSET VALUE= 470

= 1 MODULE NAME = IOSUB
GSPKT$ OFFSET VALUE= 476

TEST IF I/O BUFFERING SHOULD BE INITIATED

ROUTINE
VERSION NUMBER
= 1 MODULE NAME = IOSUB
VECTOR TABLE OFFSET NAME = TSTBF$ OFFSET VALUE= 504

$INIBF --

INITIATE I/O BUFFERING

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$QUEBF --

QUEUE BUFFERED I/O FOR COMPLETION

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$REQUE --

= 1 MODULE NAME = IOSUB
QUEBF$ OFFSET VALUE= 520

REQUEUE A REGION LOAD AST TO A TASK AST

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$REQU1 --

= 1 MODULE NAME = IOSUB
INIBF$ OFFSET VALUE= 512

= 1 MODULE NAME = IOSUB
REQUE$ OFFSET VALUE= 526

REQUEUE A REG LOAD AST (ALTERNATE ENTRYPOINT)

ROUTINE
VERSION NUMBER
= 1 MODULE NAME = IOSUB
VECTOR TABLE OFFSET NAME = REQU1$ OFFSET VALUE= 534

7-59

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS
$IOALT --

I/O DONE ALTERNATE ENTRY POINT (ERRORS)

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$IODON --

= 1 MODULE NAME = IOSUB
IOALT$ OFFSET VALUE= 542

I/O DONE

ROUTINE
VERSION NUMBER
= 1 MODULE NAME = IOSUB
VECTOR TABLE OFFSET NAME = IODON$ OFFSET VALUE= 550

$IOFIN --

I/O FINISH

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$DECAL --

DECREMENT ALL I/O COUNTS AND UNBLK TASK.

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$DECBF --

= 1 MODULE NAME = IOSUB
IOKIL$ OFFSET VALUE= 600

SCAN DEVICE TABLES

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$SCDVl --

= 1 MODULE NAME = IOSUB
DECBF$ OFFSET VALUE= 572

I/O KIL

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$SCDVT --

1 MODULE NAME = IOSUB
DECAL$ OFFSET VALUE= 564

DECREMENT ALL PARTITION I/O CNTS & UNBLK TASK

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$IOKIL --

= 1 MODULE NAME = IOSUB
IOFIN$ OFFSET VALUE= 556

= 1 MODULE NAME = IOSUB
SCDVT$ OFFSET VALUE= 606

SCAN DEVICE TABLES (ALTRN. ENTRYPT)

7-60

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS
ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$SRNAM --

SEARCH FOR NAMED PARTITION

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$SETCR --

= 1 MODULE NAME = IOSUB
SCDV1$ OFFSET VALUE= 614

= 1 MODULE NAME = PLSUB
SRNAM$ OFFSET VALUE= 622

SET CONDITIONAL SCHEDULE REQUEST

ROUTINE
VERSION NUMBER
= 1 MODULE NAME = REQSB
VECTOR TABLE OFFSET NAME = SETCR$ OFFSET VALUE= 630

$SETRQ --

SET SCHEDULE REQUEST

ROUTINE
VERSION NUMBER
= 1 MODULE NAME = REQSB
VECTOR TABLE OFFSET NAME = SETRQ$ OFFSET VALUE= 636

$SETRT --

SET SCHEDULE REQUEST FOR CURRENT TASK

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$SETMG --

SET EVENT FLG & UNLCK W/EVNT FLG MASK

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$SETFG --

= 1 MODULE NAME = REQSB
SETMG$ OFFSET VALUE= 652

SET EVENT FLAG AND UNLOCK W/EFN NUMBER

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$DASTT --

MODULE NAME = REQSB
SETRT$ OFFSET VALUE= 644

= 1

= 1 MODULE NAME = REQSB
SETFG$ OFFSET VALUE= 660

DECLARE AST TRAP

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

7-61

= 1 MODULE NAME = REQSB
DASTT$ OFFSET VALUE= 666

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS

$QASTC --

QUEUE AST TO TASK (USED

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$QASTT --

= 1 MODULE NAME = REQSB
STPTK$ OFFSET VALUE= 724

ASSIGN NEXT REGION TO PARTITION

VERSION NUMBER
ROUTINE
VECTOR TABLE OFFSET NAME

$TSPAR --

= 1 MODULE NAME = REQSB
STPCT$ OFFSET VALUE= 716

STOP TASK

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$NXTSK --

= 1 MODULE NAME = REQSB
SRSTD$ OFFSET VALUE= 710

STOP CURRENT TASK

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$STPTK --

= 1 MODULE NAME = REQSB
QASTT$ OFFSET VALUE= 702

SEARCH SYSTEM TASK DIRECTORY

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$STPCT --

= 1 MODULE NAME = REQSB
QASTC$ OFFSET VALUE= 674

QUEUE AST TO TASK

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$SRSTD --

W/CINT$)

= 1 MODULE NAME = REQSB
NXTSK$ OFFSET VALUE= 732

TEST IF PARTITION IN MEMORY FOR KERNEL AST

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

7-62

= 1 MODULE NAME = REQSB
TSPAR$ OFFSET VALUE= 740

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS

$ICHKP --

INITIATE CHECKPOINT

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$EXRQP --

EXEC REQUEST WITH QUEUE INSERT BY PRIORITY

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$EXRQF --

EXRQU$ OFFSET VALUE= 776

1 MODULE NAME = REQSB
EXRQS$ OFFSET VALUE= 1004

TASK REQUEST (DEFAULT UCB)

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$TSKRQ --

= 1 MODULE NAME = REQSB

EXEC REQUEST WITH NO SCHEDULE REQUEST

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$TSKRT --

= 1 MODULE NAME = REQSB
EXRQN$ OFFSET VALUE= 770

EXEC REQUEST AND UNSTOP WITH NO INSERT

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

; $EXRQS --

= 1 MODULE NAME = REQSB
EXRQF$ OFFSET VALUE= 762

EXEC REQUEST WITH NO QUEUE INSERT

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$EXRQU --

= 1 MODULE NAME = REQSB
EXRQP$ OFFSET VALUE= 754

EXEC REQUEST WITH QUEUE INSERT FIFO

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$EXRQN --

1 MODULE NAME = REQSB
ICHKP$ OFFSET VALUE= 746

= 1 MODULE NAME = REQSB
TSKRT$ OFFSET VALUE= 1012

TASK REQUEST (SPECIFY UeB)

7-63

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$TSKRP --

TASK REQUEST (SPECIFY DEFAULT UIC)

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$FORK --

= 1 MODULE NAME = SYSXT
FORK1$ OFFSET VALUE= 1042

FORK AND CREATE SYSTEM PROCESS

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$FORK2 --

= 1 MODULE NAME = SYSXT
FORK$ OFFSET VALUE= 1034

FORK AND CREATE SYSTEM PROCESS

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$FORKO --

= 1 MODULE NAME = REQSB
TSKRP$ OFFSET VALUE= 1026

FORK AND CREATE SYSTEM PROCESS

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$FORK1 --

= 1 MODULE NAME = REQSB
TSKRQ$ OFFSET VALUE= 1020

= 1 MODULE NAME = SYSXT
FORKO$ OFFSET VALUE= 1050

FORK AND CREATE SYSTEM PROCESS USED W/CINT$

ROUTINE
VERSION NUMBER
= 1 MODULE NAME = SYSXT
VECTOR TABLE OFFSET NAME = FORK2$ OFFSET VALUE= 1056

$QFORK --

INSERT FORK BLOCK AT END OF FORK QUEUE

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$NONSI -ROUTINE

= 1 MODULE NAME = SYSXT
QFORK$ OFFSET VALUE= 1064

NONSENSE INTERRUPT ENTRY POINT
VERSION NUMBER
7-64

= 1 MODULE NAME

SYSXT

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS
VECTOR TABLE OFFSET NAME

$DSPKA --

DISPATCH KERNEL AST

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$SGFIN --

NONSI$ OFFSET VALUE= 1072

1 MODULE NAME = SYSXT
DSPKA$ OFFSET VALUE= 1100

SEGMENT FAULT AND TRAP 4 INTERCEPT ROUTINE

ROUTINE
VERSION NUMBER
= 1 MODULE NAME = SYSXT
VECTOR TABLE OFFSET NAME = SGFIN$ OFFSET VALUE= 1106

$NLTMO --

NULL TIMEOUT ROUTINE

= 1 MODULE NAME = TDSCH
ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME = NLTMO$ OFFSET VALUE= 1114

$MUL --

INTEGER MULTIPLY MAGNITUDE NUMBERS

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$DIV --

INTEGER DIVIDE MAGNITUDE NUMBERS

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$DBDIV --

= 1 MODULE NAME = UTSUB
DIV$ OFFSET VALUE= 1130

DOUBLE PRECISION DIVIDE MAGNITUDE NUMBERS

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

$CAT5 --

= 1 MODULE NAME = UTSUB
MUL$ OFFSET VALUE= 1122

= 1 MODULE NAME = UTSUB
DBDIV$ OFFSET VALUE= 1136

CONVERT ASCII TO RAD50

ROUTINE
VERSION NUMBER
VECTOR TABLE OFFSET NAME

7-65

= 1 MODULE NAME = UTSUB
CAT5$ OFFSET VALUE= 1144

EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS

$SAVNR --

SAVE NON VOLATILE REGISTERS

VERSION NUMBER
= 1 MODULE NAME = UTSUB
ROUTINE
VECTOR TABLE OFFSET NAME = SAVNR$ OFFSET VALUE= 1152

$DRQRQ --

QUEUE I/O REQUEST (INTERNAL ENTRYPT)

VERSION NUMBER
ROUTINE
VECTOR TABLE OFFSET NAME

7-66

= 1 MODULE NAME = DRSUB
DRQRQ$ OFFSET VALUE= 1160

CHAPTER 8
HANDLING SPECIAL USER BUFFERS

Some drivers need to handle user buffers in addition to the buffer
that the Executive address-checks and relocates in a normal transfer
request. Address-checking and relocation operations must take place
in the context of the task issuing the I/O request, because the
mapping registers are set for the issuing task.
However,
in the
normal ,driver interface, the task context after the call to $GTPKT is
not, in general, that of the issuing task.
Thus, drivers that need to handle special buffers must be able to
refer to the I/O packet before it is queued, while the context of the
issuing task is still intact.

8.1

DRIVER CODE

The coding shown in this chapter is an excerpt from a driver that
The key points
illustrates the handling of a special user buffer.
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:
1.

Retrieves the user virtual address and address-checks it

Relocates the virtual address and stores the result
into the packet

Inserts the packet into the I/O queue and continues
execution inline to the entry point BMINI, which calls
$GTPKT

8-1

back

DRIVER CODE
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
MASSACHUSETTS. ALL RIGHTS'RESERVED.
iTHIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED
iAND COPIED ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE
iAND WITH THE INCLUSION OF THE ABOVE COPYRIGHT NOTICE.
THIS
iSOFTWARE OR ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR
iOTHERWISE MADE AVAILABLE TO ANY OTHER PERSON.
NO TITLE TO AND
iOWNERSHIP OF THE SOFTWARE IS HEREBY TRANSFERRED.
iTHE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT
iNOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL
iEQUIPMENT CORPORATION.
iDIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF
iITS SOFTWARE 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
iDEFINE
;DEFINE
;DEFINE

CLOCK BLOCK OFFSETS
HARDWARE REGISTERS
SCB OFFSETS
UCB OFFSETS

$BMDAT::
BM DCB

8-2

DRIVER CODE

$BMDCB: :
. WORD
. WORD
.ASCII
.BYTE
. WORD
• WORD

0
.BMO
JBMj
0,1-1
BMND-BMST
$0

. 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+1
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

PRO=O

.IF
. WORD
.ENDC

OF M$$MUP
0

. WORD
. WORD
.BYTE
.BYTE
.WORD
. WORD
. WORD
. WORD
. WORD
.WORD
. WORD
.WORD

$BMDCB
.-2
UC.QUE,O
O,US.OFL
DV.REC
0

.BMO::

72.
$BMO
0
0,0
0

U.DCB
U.RED
U.CTL,U.STS
U.UNIT,U.ST2
U.CW1
U.CW2
U.CW3
u.CW4
U.SCB
U.ATT
U.BUF,U.BUF+2
U.CNT

BMND=.

8-3

DRIVER CODE

BM SCB'S

$BMO::

. WORD
. WORD
. WORD
• .WORD
.BYTE
.BYTE
. WORD
. WORD

0, . -2
0,0,0,0

0,0
0,0

a
a

S.LHD
S.FRK
S.KS5
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/

iCOPYRIGHT (c) 1981,1982 BY DIGITAL EQUIPMENT CORPORATION.
iALL RIGHTS RESERVED.
iTHIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED
iOR COPIED ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE.
i
i
i

i
i
i

THIS IS A SAMPLE DRIVER WHICH DEMONSTRATES HOW TO USE SOME
OF THE MORE SOPHISTICATED EXECUTIVE SERVICES AVAILABLE TO
I/O DRIVERS. THIS DRIVER DEMONSTRATES:
1 ) THE CHECKING OF ADDITIONAL USER BUFFERS PRIOR TO QUEUEING
AN I/O PACKET.
2 ) USE OF THE CLOCK QUEUE FROM A DRIVER.
3 ) USE OF THE BUFFERED I/O MECHANISM
4 ) USE OF THE GENERAL BUFFERED I/O KERNEL AST MECHANISM

5 ) USE OF REGION LOAD KERNEL ASTS
6 ) USE OF BLXIO

THIS DRIVER UNDERSTANDS PRECISELY ONE QIO, WHICH IS:

8-4

DRIVER CODE
IO.WLB, .•..• ,<DEST-BUFFER,LENGTH,TIME,SRC-BUFFER)
OR
IO.WVB
DRIVER QUEUES A CLOCK BLOCK FOR TIME TICKS AND AT THE
END OF THAT TIME INTERVAL COPIES THE SOURCE BUFFER TO THE
DESTINATION BUFFER. IF POSSIBLE, THE REQUEST IS BUFFERED
INTERNALLY WHILE THE CLOCK REQUEST IS POSTED.
TH~

. MCALL

CLKDF$, PKTDF$

CLKDF$
PKTDF$

iDEFINE CLOCK BLOCK OFFSETS
iDEFINE I/O PACKET OFFSETS

DEFINE MAXIMUM TRANSFER LENGTH WHICH WILL BE BUFFERED

BUFLIM

100.

DDT$

BM"NONE",NEW

i** - BMINI - I/O INITIATION ENTRY POINT
iINPUTS:
DRQIO (BECAUSE THE UC.QUE BIT IS SET IN THE UCB) SETS THE
REGISTERS TO THE FOLLOWING:
R1
R4
R5

= ADDRESS OF I/O PACKET
ADDRESS OF SCB
ADDRESS OF UCB

iOUTPUTS:
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/O QUEUE THREAD WORD.
REQUEST PRIORITY, EVENT FLAG NUMBER.

8-5

DRIVER CODE
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 ADDRESS (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

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+10
I.PRM+12

,. -

I.PRM+14
I.PRM+16

.ENABL

LSB

*************************************************************

*
*
*

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

*
*
*
*
*

*************************************************************
MOV
MOV

R1,R3
I.PRM+10(Rl),RO

MOV

I . P RM + 4 ( R 3 ) , R1

COpy ADDRESS OF I/O PACKET
GET VIRTUAL ADDRESS OF SOURCE
BUFFER
AND LENGTH OF SOURCE BUFFER

+------------------------------------------------------------+

I
I

THE INPUT PARAMETERS FOR $CKBFR ARE:

8-6

DRIVER CODE

RO = STARTING ADDRESS OF BLOCK TO BE CHECKED
Rl = 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
C
1 IF CHECK UNSUCCESFUL OR I.AADA, I.AADA
ALREADY FILLED IN

+------------------------------------------------------------+
CALL

$CKBFR

BCC

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

*
*

*************************************************************
MOV
CLR

iIE.SPC&377,RO
R1

SET COMPLETION STATUS
AND NUMBER OF BYTES TRANSFERRED

+-----------------------------------------------------------+
THE INPUT PARAMETERS FOR $IOFIN ARE:
RO
R1
R3

FIRST WORD OF I/O STATUS TO RETURN
SECOND WORD OF I/O STATUS TO RETURN
ADDRESS OF I/O PACKET

THE OUTPUT PARAMETERS ARE:
R4 IS DESTROYED

+-----------------------------------------------------------+
CALLR

$IOFIN

COMPLETE I/O AND EXIT DRIVER

*************************************************************

*
8-7

DRIVER CODE
BUFFER WAS LEGAL, CONVERT VIRTUAL ADDRESS TO
ADDRESS DOUBLEWORD AND STORE PARAMETERS

*
*

*************************************************************
+-----------------------------------------------------------+

I
l
I
I
I
I
I
I
I
I

THE INPUT PARAMETERS FOR $RELOC ARE:
RO

= 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
I

+-----------------------------------------------------------+
CALL
MOV
MOV
CLR

10$:

$RELOC
Rl,I.PRM+l0(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

+-----------------------------------------------------------+
THE INPUT PARAMETERS FOR $QINSP ARE:
RO
Rl

= ADDRESS OF THE TWO WORD LISTHEAD
ADDRESS OF THE PACKET TO BE INSERTED

NO OUTPUT PARAMETERS

+-----------------------------------------------------------+
CALL

$QINSP

; INSERT PACKET IN QUEUE

8-8

DRIVER CODE

*************************************************************
*

*
*

BEGIN SERIAL PROCESSING OF I/O PACKETS

*
*

*************************************************************

+-----------------------------------------------------------+
THE INPUT PARAMETERS FOR $GTPKT ARE:
RS = 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
RS = UCB ADDRESS OF UNIT
C = 1 IF UNIT BUSY OR NO PACKETS QUEUED
+-----------------------~-----------------------------------+

BMIN1:

CALL
BCC
RETURN

$GTPKT
20$

20$:

ATTEMPT TO GET A REQUEST
IF CC WE GOT ONE
DEVICE BUSY OR QUEUE EMPTY
; REFERENCE LABEL

*************************************************************

*
*

ATTEMPT TO ALLOCATE CLOCK BLOCK

*
*

*************************************************************
MOV
MOV

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 IS CURRENTLY AVAILABLE
8-9

DRIVER CODE

+-----------------------------------------------------------+
$ALOCB
ATTEMPT TO ALLOCATE
IF CC SUCCESSFUL
30$
#IE.NOD&377,RO
MOV
SET I/O STATUS
+-----------------------------------------------------------+
CALL

Bec

;

I
I
I
I
I
I
I
I
I
I
I
I
I

THE INPUT PARAMETERS FOR $IOALT ARE:
RO
R1
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

+-----------------------------------------------------------+
CALL
BR
MOV

30$:

$IOALT
BMIN1
RO,I.PRM+14(R3)

AND COMPLETE T~E 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
C

o IF REQUEST MAY BE BUFFERED
1 IF REQUEST MAY NOT BE BUFFERED

+-----------------------------------------------------------+
CALL
BCS

$TSTBF
40$

TEST FOR BUFFERABLE I/O REQUEST
IF CS CAN'T ALLOCATE A BUFFER

8-10

DRIVER CODE

*************************************************************

*
*
*

ATTEMPT TO ALLOCATE A BUFFER

*
*
*

*************************************************************
MOV
CMP
BHI

I.PRM+4(R3),Rl
Rl,#BUFLIM
40$

GET LENGTH OF BUFFER
BIGGER THAN BUFFER LIMIT ?
IF HI YES, DON'T BUFFER

+-----------------------------------------------------------+
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

*
*
*

*************************************************************
MOV
MOV
MOV
MOV
MOV
BIC
BIS
MOV

RO,R4
R3,R5
I.PRM+4(R5),RO
I.PRM+l0(R5),Rl
I.PRM+12(R5),R2
#140000,R2
#120000,R2
R4,I.PRM+l0(R5)

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 APR5
SET INTERNAL BUFFER ADDRESS INTO
PACKET

+-----------------------------------------------------------+
8-11

DRIVER CODE
THE INPUT PARAMETERS FOR $BLXIO ARE:
RO
R1
R2
R3
R4

= NUMBER OF BYTES TO MOVE
= SOURCE APR 5 BIAS
= SOURCE DISPLACEMENT
= DESTINATION APR6 BIAS
= DESTINATION DISPLACEMENT

THE OUTPUT PARAMETERS ARE:
RO ALTERED
R1,R3 PRESERVED
R2,R4 POINT TO LAST BYTE OF SOURCE/DESTINATION +1

+-----------------------------------------------------------+
CALL

$BLXIO

COPY TO INTERNAL BUFFER

*************************************************************
*
CONVERT TO BUFFERED I/O REQUEST

*
*

*
*
*

*************************************************************
MOV

RS,R3

COpy I/O PACKET ADDRESS BACK

+-----------------------------------------------------------+
I
I
I
I
I
I
I

THE INPUT PARAMETERS FOR $INIBF ARE:
R3 = ADDRESS OF THE I/O PACKET TO BUFFER
NO OUTPUT PARAMETERS.

+-----------------------------------------------------------+
CALL

$INIBF

INITIALIZE BUFFERED I/O

*************************************************************

*
*
*

QUEUE THE CLOCK BLOCK

*
*
*

*************************************************************

8-12

DRIVER CODE
MOV
MOV
CLR
MOV
MOV
MOV

40$:

I.PRM+14(R3),RO ;
#CLKSRV,C.SUB(RO)
Rl
I.PRM+6(R3),R2
iC.SYST,R4
R3,RS

GET ADDRESS OF CLOCK BLOCK
; SET ADDRESS OF SUBROUTINE
HIGH ORDER DELTA TIME
LOW ORDER PART
SET REQUEST TYPE
USE PACKET ADDRESS AS IDENTIFIER

+-----------------------------------------------------------+
THE INPUT PARAMETERS FOR $CLINS ARE:
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
RS
ADDRESS OF REQUESTING TASK OR IDENTIFIER

;

NO OUTPUT PARAMETERS.

I
I
I
I
I
I
I
I
I
I
I

+-----------------------------------------------------------+
CALLR

$CLINS

QUEUE CLOCK BLOCK AND TEMPORARILY
EXIT THE DRIVER

*************************************************************

*
*

C L 0 C K

E N TRY

POI N T

*
*
*

*************************************************************

CHECK TO SEE IF THE I/O WAS BUFFERED

*
*
*

*************************************************************

CLKSRV: MOV
TST
BNE

C.TCB(R4),R5
I.PRM+16(RS)
50$

GET ADDRESS OF I/O PACKET
WAS IT BUFFERED I/O
IF NE YES, GO QUEUE KERNEL AST

*************************************************************

*
*
*

COULDN'T BUFFER, PERFORM COpy HERE AND NOW

*
*
*

*************************************************************
8-13

DRIVER CODE

MOV
MOV
MOV
BIC
BIS
MOV
MOV

I.PRM+4(R5),RO
I.PRM+10(R5),R1
I.PRM+12(R5),R2
#140000,R2
#120000,R2
I.PRM(R5),R3
I.PRM+2(R5),R4

SET LENGTH T.o TRANSFER
BIAS OF SOURCE BUFFER
DISPLEACEMENT OF SOURCE
STRIP OFF APR6 ADDRESS BITS
AND CONVERT TO APR5
SET BIAS OF DESTINATION
SET DISPLACEMENT

+-----------------------------------------------------------+
THE INPUT PARAMETERS FOR $BLXIO ARE:
RO
R1
R2
R3
R4

NUMBER OF BYTES TO MOVE
SOURCE APR5 BIAS
SOURCE DISPLACEMENT
DESTINATION APR6 BIAS
DESTINATION DISPLACEMENT

THE OUTPUT PARAMETERS ARE:
RO ALTERED
R1,R3 PRESERVED
R2,R4 POINT TO LAST BYTE OF SOURCE/DESTINATION +1
+-----------------------------------------------------------+

COpy BUFFER
CALL
$BLXIO
MOV
GET ADDRESS OF CLOCK BLOCK
I.PRM+14(R5),RO
MOV
#:C.LGTH,R1
GET LENGTH OF CLOCK BLOCK
+-----------------------------------------------------------+
THE INPUT PARAMETERS FOR $DEACB ARE:
RO
Rl

ADDRESS OF BLOCK TO DEALLOCATE
LENGTH OF BLOCK TO DEALLOCATE

NO OUTPUT PARAMETERS.
+-----------------------------------------------------------+

BMSUC:

CALL
MOV
MOV
MOV

$DEACB
R5,R3
#:IS.SUC&377,RO
I.PRM+4(R3),R1

DEALLOCATE IT
COpy PACKET ADDRESS FOR $IODON
SET FINAL I/O STATUS
AND LENGTH OF TRANSFER = REQUESTED
8-14

DRIVER CODE

BMDON:

MOV

I.UCB{R3) ,RS

; GET UCB ADDRESS OF DEVICE

+-----------------------------------------------------------+

;

I
I
I
I
I
I
I
I
I
I
I
I
I

THE INPUT PARAMETERS FOR $IODON ARE:
RO = FIRST WORD OF I/O STATUS BLOCK
Rl = SECOND WORD OF I/O STATUS BLOCK
R2 = STARTING AND FINAL RETRY COUNTS
(IF AN ERROR LOGGING DEVICE)
RS = 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

+-----------------------------------------------------------+
CALL
BR

$IODON
BMINl

; COMPLETE THE I/O
; GO LOOK FOR MORE WORK

*************************************************************
*
BUFFERED I/O, CONVERT I/O PACKET TO KERNEL
AST AND EXIT FROM DRIVER

*
*
*

*
*
*
*

*************************************************************
SO$:

MOV
MOV
TST
MOV
MOV
MOV
MOV

R4,R3
I.TCB(RS),RO
(R4)+
#AK.GBI,{R4)+
KISARS,{R4)+
#KATSRV, (R4) +
RS, {R4 }

COpy CLOCK BLOCK ADDRESS FOR $REQUE
POINT TO TCB OF TASK
SKIP 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

+-----------------------------------------------------------+
THE INPUT PARAMETERS FOR $REQUE ARE:
RO
TCB ADDRESS TO QUEUE AST BLOCK TO
R3 = ADDRESS OF THE PACKET TO QUEUE
NO OUTPUT PARAMETERS.

;

+-----------------------------------------------------------+
CALLR

$REQUE

; QUEUE AST TO TASK

*************************************************************

*
*

K ERN E L

A S T

8-1S

E N TRY

POI N T

*
*

DRIVER CODE

*************************************************************

*
*

GET PCB ADDRESS AND SEE IF PARTITION IS RESIDENT

*
*
*

*************************************************************
KATSRV: MOV
MOV
BEQ

10(R3) ,R5
I.PRM+16(R5),R1
70$

GET I/O PACKET ADDRESS
GET PCB ADDRESS OF BUFFER REGION
IF EQ THERE IS NO COpy TO PERFORM

+-----------------------------------------------------------+

;
i

I
I
I
I
I
I
I
I
I
I
I
I
I

THE INPUT PARAMETERS FOR $TSPAR ARE:
RO = ADDRESS OF THE PACKET (THE KERNEL AST BLOCK)
R1 = PCB ADDRESS OF THE PCB CONTAINING THE BUFFER
R5 = TCB ADDRESS OF ASSOCIATED TASK
THE OUTPUT PARAMETERS ARE
C O I F REGION IS RESIDENT AND CAN BE ACCESSED
C = 1 IF REGION IS NOT RESIDENT AND AST HAS
BEEN QUEUED

+-----------------------------------------------------------+
CALL
BCC
RETURN

$TSPAR
60$

REGION IN MEMORY ?
IF CC REGION IN MEMORY
ELSE PARTITION AST HAS BEEN QUEUED

*************************************************************

*
*
*

PERFORM BUFFER COpy OPERATION

*
*
*

*************************************************************

60$:

MOV
MOV
MOV
ADD
MOV

I.PRM+4(R5),RO
I.PRM+10(R5),R2
P . REL ( R1 ) , R3
I.PRM(R5),R3
I.PRM+2(R5),R4

GET COUNT OF BYTES
SET SOURCE BUFFER ADDRESS
GET STARTING BIAS OF PARTITION
AND ADD IN OFFSET
SET DISPLACEMENT

+-----------------------------------------------------------+
THE INPUT PARAMETERS FOR $BLXIO ARE:

8-16

DRIVER CODE
NUMBER OF BYTES TO MOVE
RO
R1 = SOURCE APR 5 BIAS
R2 = SOURCE DISPLACEMENT
DESTINATION APR6 BIAS
R3
DESTINATION DISPLACEMENT
R4
THE OUTPUT PARAMETERS ARE
RO ALTERED
R1,R3 PRESERVED
R2,R4 POINT TO LAST BYTE OF SOURCE/DESTINATION +1
+-----------------------------------------------------------+
CALL
MOV
MOV

$BLXIO
I.PRM+10(R5),RO
I.PRM+4(R5),R1

COpy THE BUFFER
GET BUFFER ADDRESS AGAIN
GET LENGTH OF BUFFER

+~----------------------------------------------------------+

I
I
I
I
I
I
I
I

THE INPUT PARAMETERS FOR $DEACB ARE:
RO
R1

ADDRESS OF BLOCK TO DEALLOCATE
LENGTH OF BLOCK TO DEALLOCATE

NO OUTPUT PARAMETERS.

I
I
I
I
I
I
I
I

+-----------------------------------------------------------+
CALL

$DEACB

; DEALLOCATE IT

*************************************************************
*
*
IF THIS WASN'T A REGION LOAD AST, FINISH THE I/O

*
*

*************************************************************

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

#C.LGTH,Rl

SET LENGTH OF CLOCK BLOCK

+-----------------------------------------------------------+
THE INPUT PARAMETERS FOR $DEACB ARE:
RO
R1

ADDRESS OF BLOCK TO DEALLOCATE
LENGTH OF BLOCK TO DEALLOCATE

8-17

DRIVER CODE
NO OUTPUT PARAMETERS.
i.

+-----------------------------------------------------------+
CALL
MOV
MOV
MTPD$
MOV
MTPD$
CLR
MOV
JMP

DEALLOCATE CLOCK BLOCK
GET VIRTUAL ADDRESS OF I/O STATUS
BLOCK
iIS.SUC&377,-{SP) ; SET FIRST I/O STATUS WORD
WRITE FIRST WORD OF STATUS (MAY
(R3)+
TRAP)
I.PRM+4{R5),-{SP) ; SET SECOND WORD OF I/O STATUS
WRITE SECOND WORD (MAY TRAP)
(R3)
PREVENT $IODON ATTEMPT TO WRITE
I.IOSB(R5)
STATUS
COPY I/O PACKET ADDRESS
R5,R3
FINISH IN COMMON CODE
BMSUC
$DEACB
I.IOSB(R5),R3

*************************************************************

*
*
*

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

+-----------------------------------------------------------+
THE INPUT PARAMETERS FOR $REQUE ARE:
RO
R3

TCB ADDRESS TO QUEUE AST BLOCK TO
ADDRESS OF THE PACKET TO QUEUE

NO OUTPUT PARAMETERS.
+-----------------------------------------------------------+
CALLR

$REQUE

REQUEUE TASK AST AND EXIT AST
SERVICE

*************************************************************

*
*
*

MISCELLANEOUS ENTRY POINTS

*************************************************************

*
*
*

CAN C E L

E N TRY

POI N T

*
*
*

8-18

DRIVER CODE
WE COULD DEQUEUE PENDING CLOCK REQUEST, ETC HERE,
BUT WE DON'T, WE JUST LET THEM COMPLETE LATER

*
*
*

*************************************************************

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-19

CHAPTER 9
ACCESSING VIDEO HARDWARE AND TERMINAL SUBSYSTEM

This chapter provides reference information for programmers needing
access to the Professional's video hardware, as well as to the
text-handling component of the Terminal Subsystem.
(For information
on the graphics capabilities, see the PROIGIDIS Manual.)
To use the information provided here, you should be familiar with the
Professional
hardware at the level of detail provided in the
Professional 300 Series Technical Manual. Also, your familiarity with
PIOS should include an understanding of the Executive directives and
the Application Task Builder.
This chapter does
not
include
step-by-step instruction.

9.1

APPLICATION LEVEL ACCESS TO THE VIDEO HARDWARE

Under PIOS, the video generator device registers and display memory
are generally accessed only by the Terminal Subsystem, with a
higher-level interface provided for applications. However, it is also
possible for an application to directly access the hardware.
The main reasons for having an application access
directly are that the application might be able to:
o

Achieve faster throughput
supported system services.

than

Provide functionality
support.

the

system

that

The main reasons for NOT having an
directly are as follows:
o

application

went

the

through

software

access

hardware

the

doesn't
hardware

Future versions of the system
software
may
interact
differently with the video hardware. An application that
accesses the hardware directly may not work under all
versions of P/OS.
DIGITAL is not and will not attempt to
9-1

APPLICATION LEVEL ACCESS TO THE VIDEO HARDWARE
achieve this type of compatibility.
o

The video hardware may change. The system software keeps up
with such changes, but if the application accesses the
hardware directly (thus does not use the system services), it
will also have to be adapted to account for the video
hardware changes.

Developing an application that accesses the hardware directly
requires considerable familiarity with the hardware. The
relevant sections of the Professional 300 Series Technical
Manual, along with the contents of this document, are
pre-requisites to acquiring this familiarity, but are not
necessarily sufficient by themselves.

This document deals only with a Professional running PIOS, but some of
the information may be useful for applications running under other
operating systems.

9.1.1

Disabling the Terminal Subsystem

Before directly accessing the video hardware, an application must
ensure that the Terminal Subsystem is not active. Failure to disable
the Terminal Subsystem can have unpredictable results, including
system software failure.
Steps for disabling the Terminal
later) are as follows.

Subsystem

(P/OS

Versions

1.7

and

Send a reset-to-initial-state (RIS) sequence, <ESC>c.
This
resets the Terminal Subsystem to its initial state and clears
the screen.

Send a disable cursor sequence, <ESC>[?25l.
text mode cursor off.

This

turns

the

After disabling the cursor, the Terminal Subsystem accesses the video
harQware only when it is requested to display something, or when it
blanks the screen at the end of its time-out period.
If the application combines requests to the Terminal Subsystem with
its own manipulation of the video hardware, it must save and restore
the contents of the following device registers:
o

Control and Status Register

9-2

APPLICATION LEVEL ACCESS TO THE VIDEO HARDWARE
o

Plane 1 Control Register

Plane 2 and 3 Control Register

Memory Base Register (should not be modified at all)
CAUTION
DO NOT SET THE INTERRUPT ENABLE BITS

The results of doing so are unpredictable,
and
probably undesirable. The system could hang or crash.

9.1.2

Accessing the Video Device Registers

In the CTI architecture, as on other PDP-ll buses, devices are
controlled via device registers, which appear as memory in the top 8KB
(the I/O page) of the bus address space.
However, unlike those on UNIBUS and Q-BUS devices, the device
registers on a CTI device do not have fixed addresses on the bus.
Instead, each option slot has a 128-byte device register address
space, the location of which can be found in the Professional 300
Series Technical Manual.
The registers on a given module appear at a fixed displacement within
the address space of the slot containing the module. This means that
in order to access the device registers on the video, software must
determine at run-time which slot it is in. The WIMPS Executive
Directive provides the means for doing this.
The WIMPS Directive returns a dump of the configuration table,
including the IDs of the devices in all the slots. Scan the list to
find out which slot contains the video controller.
The PIOS System
Reference Manual lists the device IDs.
NOTE

The ID value for the PC350 video controller
different from that of the PC380 video controller.
sure to use the correct ID.
The slot number gives you the bus address.
your application in a resident common
covers the I/O page.

9-3

is
Be

You can then taskbuild
in partition CTPAGE, which

APPLICATION LEVEL ACCESS TO THE VIDEO HARDWARE

9.1.3

Accessing Video Memory Through the Bus

Because the Terminal Subsystem puts the video display memory on the
CTI bus at boot time, the CPU can read from and write to this memory
without using the device registers.
P/OS uses this capability.
The video memory occupies a
called TFWBMP fills this
TFWBMP and places it on the
attach the region and map a

partition called BITMAP, and a
region
partition. The Terminal Subsystem creates
bus at boot time.
An application can
portion of it.

TFWBMP is 32KB (PC350) or 128KB (PC380).
The displayed portion of
TFWBMP is the first 30KB (PC350, or PC380 low resolution) or 60KB
(PC380 high resolution). A bit in the CSR indicates the resolution,
as described in the Technical Manual.
Note that the least significant portion of the first word of the
region corresponds to the upper left corner of the screen.
If there
is an Extended Bit Option (EBO) in the system, all three planes of
memory share the same bus address space.
(To determine if a system
has an EBO option, check the CSR of the video hardware.)
To read from or write to any of the planes (whether or not there is an
EBO),
the memory reference enable bit (bit 5) in its plane control
re~ister must be set to 1.
If there is an EBO, the memory reference
enable bit can be set for more than one plane.
Reads will come in ascending order (1, 2, 3) from each plane that has
the memory reference enable bit set.
plane numbers are defined by the
hardware and do not necessarily correspond to any software numbering
scheme.
Writes will go to all planes that have the memory reference
enable bit set.
Remember that a transfer, once started, can take a long time.
Check
the Done bit before modifying any registers other than the X and Y
registers, unless you are certain that the transfer is complete.

9.1.4

The Screen Timer

A screen time-out feature is built into the Terminal Subsystem to
prevent the burn-in of a static image in the screen phosphor. The
Terminal Subsystem blanks the screen if there has been no keyboard or
video activity for 30 minutes. This is accomplished by setting the
horizontal resolution to off in the Plane 1 Control Register.
For applications that process input from the keyboard,
the screen
timer is not a problem, but for display-only applications it can be a
problem because the Terminal Subsystem cannot detect the ongoing video
activity.
9-4

APPLICATION LEVEL ACCESS TO THE VIDEO HARDWARE
One solution to this problem is to send a null byte to the screen (via
the Terminal Subsystem) at regular intervals (at least every 30,
minutes). This will cause the Terminal Subsystem to reset its timer,
without causing any visual effects.

9.1.5

Returning the Video Hardware to the System

After the application has completed, it must restore the hardware
device registers, especially the Plane 1 control register. Failure to
do so may cause the system to crash during a split-screen scroll or
insert/delete
operation.
You should re-initialize the Terminal
Subsystem by issuing a RIS sequence.

9-5

APPENDIX A
P/OS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS

This appendix describes the P/OS system macros that
offsets for data structures listed in Table A-i.

supply

symbolic

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$

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.
All of these macros
are
in
the
Executive
macro
library,
LB:[1,5]EXEMC.MLB.
All except FliDF$ and ITBDF$ are also in the
Executive definition library, LB:[l,l]EXELIB.OLB.

A-l

Table A-1:

Macro

Summary of System Data Structure Macros

Arguments

Data structures

ABODF$

Task abort and termination
notification message codes

ACNDF$

UAB definitions

ACTDF$

Account file definitions

BCKDF$

Bugcheck code

CLKDF$

<:>,<=>

Clock queue control block

CTBDF$

<:>,<=>

Controller table

DCBDF$

<:>,<=>,SYSDEF

Device control block

DDT$
FiiDF$

Macro to generate driver dispatch
table
<:>,<=>,SYSDEF

GTPKT$

Files-ii data structures
(volume control block, mount list
entry, file control block, file
window block, locked block list
node)
Macro to generate $GTPKT UCB
address

HDRDF$

<:>,<=>

Task header and window block

HWDDF$

<:>,<=>,SYSDEF

Hardware register addresses and
feature mask definitions

INTSV$

Macro to generate interrupt entry
code to determine UCB address

ITBDF$

<:>,<=>,SYSDEF

Interrupt transfer block

KRBDF$

<:>,<=>

Controller request block

LBLDF$

Task image file label block
definitions

LNMDF$

Logical name block (LNB)

A-2

PCBDF$

<:>,<=>,SYSDEF

Partition control block and
attachment descriptor

PKTDF$

<:>,<=>

I/O packet, AST control block,
offspring conttol block, group
global event flag control block,
and CLI parser block

QIOSY$

I/O error function code definition

SCBDF$

<:>,<=>,SYSDEF

status control block

TCBDF$

<:>,<=>,SYSDEF

Task control block

TTSYM$
UCBDF$

Terminal driver symbols
<:>,<=>,TTDEF,SYSDEF Unit control block

A-3

ABODF$

A.1

ABODF$

TASK ABORT CODES
NOTE: S.COAD-S.CFLT ARE ALSO SST VECTOR OFFSETS
i-

177774
177776
000000
000002
000004
000006
000010
000012
000014
000016
000020
000022
000024
000026
000030
000032
000034
000036
000040
000042
000044
000046
000050
000052

• 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.
S.CTKN=42.

iTASK STILL ACTIVE
iTASK EXITED NORMALLY
iODD ADDRESS AND TRAPS TO 4
iSEGMENT FAULT
iBREAK POINT OR TRACE TRAP
iIOT INSTRUCTION
iILLEGAL OR RESERVED INSTRUCTION
iNON RSX EMT INSTRUCTION
iTRAP INSTRUCTION
ill/40 FLOATING POINT EXCEPTION
iSST ABORT-BAD STACK
iAST ABORT-BAD STACK
iABORT VIA DIRECTIVE
iTASK LOAD REQUEST FAILURE
iTASK CHECKPOINT READ FAILURE
iTASK EXIT WITH OUTSTANDING I/O
iTASK MEMORY PARITY ERROR
iTASK ABORTED WITH PMD REQUEST
iTI: VIRTUAL TERMINAL WAS ELIMINATED
iTASK INSTALLED IN 2 DIFFERENT SYSTEMS
iTASK ABORTED DUE TO BAD AFFINITY (REQUIRED BUS
iRUNS ARE OFFLINE OR NOT PRESENT)
iBAD CSM PARAMETERS OR BAD STACK
iTASK HAS RUN OVER ITS TIME LIMIT
iABORT VIA DIRECTIVE WITH NO TKTN MESSAGE

TASK TERMINATION NOTIFICATION MESSAGE CODES
000000
000002
000004
000006
000010
000012
000014
000016
000020
000022
000024
000026
000030

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.

iDEVICE NOT READY
iDEVICE SELECT ERROR
iCHECKPOINT WRITE FAILURE
iCARD READER HARDWARE ERROR
iDISMOUNT COMPLETE
iUNRECOVERABLE ERROR
iLINK DOWN (NETWORKS)
iLINK UP (NETWORKS)
iCHECKPOINT FILE INACTIVE
iUNRECOVERABLE DEVICE ERROR
iMEMORY PARITY ERROR
jVCODE LOADER NOT INSTALLED
iACCOUNTING ALLOCATION FAILURE
A-4

ABODF$
000032
000034
000036
000040

T.NTAF=26.
T.NDEB=28.
T.NRCT=30.
T.NWBL=32.

000042

T.NVER=34.

iACCOUTING TAB ALLOCATION FAILURE
iTASK HAS NO DEBUGGING AID
iREPLACEMENT CONTROL TASK NOT INSTALLED
iWRITE BACK CACHING DATA LOST. UNIT WRITE
iLOCKED
iMOUNT VERIFICATION TASK NOT INSTALLED

A-S

ACNDF$

A.2

ACNDF$

ACCOUNTING BLOCK OFFSET AND STATUS DEFINITIONS
FOR EACH TRANSACTION TYPE.
HEADER COMMON TO ALL TRANSACTIONS
i-

000000
000000

.ASECT
.=0

000000
000002
000003
000004
000012
000012

B. LNK: . BLKW
B.TYP:.BLKB
B. LEN: . BLKB
B. TIM: . BLKW
B.HID=.
B.UID: .BLKW

1
1
1
3

000016
000020

B .ACN: . BLKW
B.TID: .BLKB

1
1

000021
000022
000022

.BLKB
1
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
i FIRST WORD-RADIX-50, SECOND-BINARY
iACCOUNT NUMBER
iASCII TERMINAL TYPE (V,T, OR C)
i(VIRTUAL,REAL,BATCH, OR CONSOLE)
iUNIT NUMBER
iEND OF HEADER 10 AREA
iHEADER LENGTH

i+
i ACCUMULATION FIELDS FOR TAB,
i -

000022
000026
000032
000036
000042
000050
000056
000062
000064
000065

B . CPU: . BLKW
B . DI R: . BLKW
B. QIO: . 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

UAB, AND SAB
iTOTAL CPU TIME USED
iTOTAL DIRECTIVE COUNT
iTOTAL QIO$ COUNT
iTOTAL TASK COUNT
iRESERVED
iBEGINNING/LOGIN TIME
jCPU LIMIT
jPOINTER TO HIGHER LEVEL TOTALS
jSTATUS MASK
iTOTAL'S LENGTH

i+
j

USER ACCOUNT BLOCK (UAB)
NOTE:
UAB'S MUST END ON A WORD BOUNDARY

000065

000065
.=$$$TLN
B.USE:.BLKB
1

jSTART AFTER TOTALS
COUNT

iUSE

A-6

ACNDF$

000066
000070
000072
000074
000102
000104

B.ACT:.BLKW
B.UUIC:.BLKW
B.UCB:.BLKW
B.LGO:.BLKW
B.ULNK:.BLKW
B.RNA:.BLKW

000112
000130
000131
000132

B.NAM:.BLKB
14.
.BLKB
1
.BLKB
1
B.LDS:.BLKB
10.
.IF OF R$$PRO
B.CBT:.BLKW
1
iPOINTER TO CHANNEL BLOCK TABLE
.ENDC
000146 B.ULEN=.
iUAB LENGTH
000002 $$$=
<.+77>/100
iUAB LENGTH (ROUNDED UP TO 32
iWORD BOUND)

000144

1
1
1

3
1

OF CURRENTLY ACTIVE TASKS
;LOGIN UIC
;POINTER TO UCB
;LOGOFF TIME
;LINK TO NEXT UAB
;LOC IN SYSACCT FILE (OFFSET,VBN-HI,
iVBN-LO)
iLAST NAME OF USER
iFIRST INITIAL OF USER
iFLAG BYTE FOR UAB (bs.sil) etc.
;LOGIN DIRECTORY STRING

~NUMBER

A-7

ACTDF$

A.3

ACTDF$

000000
000062

ACTDF$
.ASECT
000000

000000
000003
000006
000014
000032
000046
000054
000056
000062
000064
000070
000074
000076
000100
000113
000114
000116

.=0
A.GRP:
A.MBR:
A.PSWD:
A.LNM:
A.FNM:
A.LDAT:

.BLKB
.BLKB
.BLKB
.BLKB
.BLKB
.BLKB

3
3
6
14.
12.
6

.BLKB
.BLKB
.BLKW
.BLKW
.BLKW
A. LPRV: . BLKW
. BLKW
A . SID:
A.DDS:
.BLKB
.BLKB
A.FPRO: .BLKW
A.RLVL: .BLKW
AR.LVL=401
A. SALT: . BLKW
A.ENCT: .BLKB

2
4
1
2
2
1
1
11.
1
1
1

A.NLOG:
A.SYDV:
A.ACN:
A.CLI:

000401
000120
000122

1
1
i

000123
000124

A.HPW:

000134
000135

AH.TYP: .BLKB
AH. S Z1: . BLKB

000136

AH.HOM:

000136
000144
000145
000163
000164
000174

AH.NOD: .BLKB
AH.SZ2: .BLKB
AH.USN: .BLKB
AH. SZ3: .BLKB
AH.HPW: .BLKB

.BLKB 1
.BLKW 4
.IF DF R$$PRO
1
1

6
1
14.
1
8.

GROUP CODE (ASCII)
MEMBER CODE
PASSWORD
LAST NAME
FIRST NAME
LAST LOG ON-DD/MM/YY HH:MM:SS
i TOTAL NUMBER OF LOGONS
DEFAULT SYSTEM DEVICE
iACCOUNT NUMBER (BINARY)
i RADIX-50 USER CLI
i UNUSED
iLOGIN PRIVILEGE WORD
i SESSION IDENTIFIER
iDEFAULT DIRECTORY STRING
iUNUSED BYTE
iDEFAULT FILE PROTECTION
iACCOUNT RECORD REV. LEVEL
i16-BIT ENCRYPTION SALT VALUE
iENCRYPTION TYPE
o = PLAIN TEXT OR ENCRPT
1 = PURDY-V ALGORITHM
iUNUSED
iHASHED PASSWORD
iTYPE OF HOME DEFINITION
iIF AH.TYP=l,LENGTH OF NODENAME
iIF AH.TYP=2,LENGTH OF
iDEVICE SPEC
iIF AH.TYP=2,START OF
iDEVICE SPEC
iIF AH.TYP=l,NODENAME IN ASCII
iLENGTH OF USERNAME
iUSERNAME IN ASCII
iLENGTH OF PASSWORD
iHASHED PASSWORD

AH.RLN=
BIT DEFINITIONS FOR AH.TYP
000000
000001
000002

AH.NUL= a
AH.CLL= 1
AH.DVS= 2
.ENDC

iHOME VALUE IS NULL
iHOME VALUE IS CLUSTER LOG TRIO
iHOME VALUE IS A DEVICE SPEC
iDF R$$PRO
A-8

ACTDF$

000200

128.

A.LEN

LENGTH OF CONTROL BLOCK

BIT DEFINITIONS ON A.LPRV - LOGIN PRIVILEGE BITS
i.

000001
000002
000004

AL.SLV= 1
AL.DDS= 2
AL.SIL= 4
AL.AUT=
AL.BND=
AL.RMT=
AL.NET=
AL.DIS=
AL.PRI=
AL.SEC=

002000
004000
010000
020000

AL.NDL=
AL.NMD=
AL.NFL=
AL.FPC=

iSLAVE TERMINAL ON LOGIN
iINDICATOR FOR PROLOGUE 2 FORMAT
iSILENT LOGIN/LOGOUT
.IF OF A$$LOG

(,*)
iAUTO LOGIN ENABLED
( , Y)
iBINDING ENABLED
iREMOTE DIALUP l=NO
iNETWORK LOGIN l=NO
iDISABLE THIS ACCOUNT FROM LOGIN
iPRIMARY DAYS LIMIT SET
iSECONDARY DAYS LIMIT SET

10
20
40
100
200
400
1000

.ENDC i OF A$$LOG
.IF OF R$$PRO
iRECORD MARKED FOR NO DELETE
2000
iRECORD CANNOT BE MODIFIED
4000
10000
iFOREGROUND LOGIN'S DISABLED
iFORCE PASSWD CHANGE
20000
.ENDC iDF R$$PRO

A-9

BCKDF$

A.4

BCKDF$

000100
000200
100400
000300
000000
000001
000002
000003
000004
000005
000006

BF.PKS=000100
BF.TTD=000200
BF.PTS=100400
BF.EXE=000300
BE.IOT=OOOOOO
BE.STK=OOOOOl
BE.BPT=000002
BE.ILI=000003
BE.ODD=000004
BE.SGF=000005
BE.NPA=000006

000007
000010
000011

BE.EMT=000007
BE.TRP=000010
BE.NOD=OOOOll

P/OS Keyboard Handler
Terminal Driver
P/OS Terminal Subsystem
Exec - SSTSR, General
lOT in System State
Stack Overflow
Trace Trap or Breakpoint
Illegal Instruction Trap
Odd Address or Other Trap 4
Segment Fault
A Task on P/OS Without a
Parent Aborted
EMT Trap
TRAP Trap
Out of POOL

000400
000001
000002
000003
000007

BF.UP =000400
BE.IN1=000001
BE.SP1=000002
BE.SP2=000003
BE.FNF=000007

System Startup Processing
Can't Install Task CBOOT
Can't Spawn Task CBOOT
Can't Spawn Task CMAIN
Required File Not Found

; PRO/DECnet startup failure codes
000010
000011
000012
000013
000014
000015
000016

BE.DSC=000010
BE.BDP=OOOOll
BE.NWB=000012
BE.DAF=000013
BE.VIU=000014
BE.NPD=000015
BE.NSD=000016

DSR corrupt
Bad dispatch
No way to Boot via DECNA (Cluster)
DSR Allocation Failure
DDM Vector in use
Required PDV not found.
Required Hardware not present.

P/OS Server network failure codes

,
000500

SCA facility code

BF.SCA= 000500

SCA network

;

; SCAINT bugcheck codes
000001

BE.NCS= 000001

000002

BE.NSP= 000002

000003
000004
000005

BE.ECL= 000003
BE.SYC= 000004
BE.SAF= 000005

No PDV index for a required Cluster
process
Error creating Cluster secondary
pool
Error creating FS: logicals
Error creating system channel
Error allocating structures from
A-10

BCKDF$

000006

BE.ASY= 000006

000007
000010
000011
000012

BE.PAF= 000007
BE.OVL= 000010
BE.NFS= 000011
BE.NCL= 000012

000013

BE.ISL= 000013

Cluster secondary pool
; CCB allocation failure during system
channel creation
Error allocating from primary pool
Error creating device list
No FS: device
COMINI spawned SCAINT without a
command line
Command line string invalid length

PPO bugcheck codes
000101

BE.ANI= 000101

000102

BE.POV= 000102

000103

BE.CTL= 000103

000104

BE.UAQ= 000104

000105
000106
000107

BE.IMT= 000105
BE.REG= 000106
BE.SB = 000107

000110
000111
000112
000113
000114

BE.IOT= 000110
BE.CTM= 000111
BE.XMT= 000112
BE.XMC= 000113
BE.VCS= 000114

Allocation failure during network
startup
Required PDV index not found (UNA or
EPM)
Decnet control function completed
unsuccessfully (enable port,start
channel,set protocol type)
Entry not found in unacknowledged
queue
Illegal message type (datagram)
No entry in retransmit queue
System block address not in link
list
Illegal entry into dispatch table
Unack'd queue empty (CHKTMR routine)
Unack'd queue empty (XMIT routine)
Unack'd queue empty (XMITC routine)
VCSTART timed out, can't communicate
with the fileserver

SCS bugcheck codes
000201
000202

BE.ILM= 000201
BE.SCB= 000202

000203

BE.CNT= 000203

000204
000205

BE.OSP= 000204
BE.CNB= 000205

000206
000207
000210
000211
000212
000213

BE.LST= 000206
BE.CNN= 000207
BE.ACC= 000210
BE.RJC= 000211
BE.XCT= 000212
BE.SNT= 000213

Illegal message type (datagram)
Connect block address not in link
list (at VCHALT processing)
Usage count not = 0 (at
VCHALT processing)
Illegal entry into dispatch table
Connect block address not in link
list (in DCBCT)
Not enough info passed in listen vadd
Not enough info passed in connect vadd
Not enough info passed in accept vadd
Not enough info passed in reject vadd
Illegal transmission of control msg
Invalid entry into send table

;

; FSD bugcheck codes
A-ll

BCKDF$

000301

BE.NET= 000301
BE.DSL= 000302

000303

BE.CHN= 000303

000304

BE.ACO= 000304

000305

BE.COF= 000305

000306
000307

BE.DEV= 000306
BE.ASD= 000307

000310
000311

BE.NST= 000310
BE.CAF= 000311

000312

BE.SND= 000312

000313
000314
000315

BE.ATT= 000313
BE.IOP= 000314
BE.NCB= 000315

000316
000317

BE.NCD= 000316
BE.NRF= 000317

000320

BE.ILE= 000320

000321
000322

BE.VCH= 000321
BE.IOQ= 000322

000323
000324

BE.SYS= 000323
BE.CBF= 000324

Unable to communicate with
fileserver during channel processing
Unable to communicate with
fileserver during device select proc
Error during channel processing, no
entry in clock block queue
Allocation failure during connection
processing
Connect failed for reason other
than allocation failure
Too many devices in device list
Unable to allocate system data
structures (VCB, UCB extension)
No TCB for startup task SCAINT
CCB allocation failure in retry
routine
Unable to communicate with the
fileserver during wlb/wvb/ctl/ulk/rlb
Attribute list spans a CTNA buffer
I/O packet not in queue
Channel block not in link list for
delete channel
QIO to LUN without concealed device
Deaccess can't find RFCB entry in
queue
Illegal entry point in dispatch
table
.
VCHALT, fileserver has gone down
Queue length is <>the number of
entries in the I/O queue
No matching system at login
Channel block table full (V3.0 only)

;

; FSI/FSA bugcheck codes
000401
000402
000403
000404
000405
000406
000407

BE.DBA= 000401
BE.DBI= 000402
BE.SNF= 000403
BE.ENT= 000404
BE.LDR= 000405
BE.VCP= 000406
BE.HLT= 000407

BAD DISPATCH OFFSET - FSA
BAD DISPATCH OFFSET - FSI
STRUCTURE NOT FOUND IN ACTIVE LIST
BAD ENTRY POINT
LOADR NOT FOUND IN ATL
VCP NOT ACTIVE
BAD DISPATCH FOR VCH

bugcheck codes for cluster subroutines that are
built with the POS exec
000501

BE.BDB= 000501

DLBOB. - BOB address not in active
list

A-12

CLKDF$

A.S

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

000000
000002

C.MRKT=O
C.SCHD=2

000004
000006

C.SSHT=4
C.SYST=6

000010

C.SYTK=8

000012

C.CSTP=10.

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)
CLOCK QUEUE CONTROL BLOCK TYPE INDEPENDENT
OFFSET DEFINTIONS

.ASECT
000000
000002
000003
000004

.=0
C.LNK:
C.RQT:
C.EFN:
C.TCB:

.BLKW
.BLKB
.BLKB
.BLKW

000006

C.TIM:

.BLKW

1
1
1
1
2

CLOCK QUEUE THREAD WORD
REQUEST TYPE
EVENT FLAG NUMBER (MARK TIME ONLY)
TCB ADDRESS OR SYSTEM SUBROUTINE
IDENTIFICATION
ABSOLUTE TIME WHEN REQUEST COMES DUE
CLOCK QUEUE CONTROL BLOCK-MARK TIME
DEPENDENT OFFSET DEFINITIONS

000012
000012
000014
000016
000020

.=C.TIM+4
C.AST:
.BLKW
C.SRC:
.BLKW
C.DST:
.BLKW
. BL'KW

1
1
1
1

START OF DEPENDENT AREA
AST ADDRESS
FLAG MASK WORD FOR 'BIS' SOURCE
ADDRESS OF 'BIS' DESTINATION
UNUSED

A-13

CLKDF$
CLOCK QUEUE CONTROL BLOCK-PERIODIC
RESCHEDULING DEPENDENT OFFSET
DEFINITIONS
000012
000012
000016
000020

.=C.TIM+4
C.RSI: .BLKW
C . UI C : . BL KW
C.UAB: .BLKW

2
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
000012
000016
000020

.=C.TIM+4
.BLKW
.BLKW
.BLKW

2
1
1

START OF DEPENDENT AREA
TWO UNUSED WORDS
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
000012
000014

.=C.TIM+4
C.SUB:
.BLKW
C. AR5 :
.BLKW

1
1

000016

C.URM:

.BLKW

000020
000022

.BLKW
1
C.LGTH=.

000000

.PSECT

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

A-14

CTBDF$

A.6

CTBDF$

CONTROLLER TABLE (CTB)
THE CONTROLLER TABLE IS A CONTROL BLOCK THAT CONTAINS A VECTOR
OF KRB ADDRESSES. THIS VECTOR MAY BE ADDRESSED BY THE CONTROLLER
INDEX TAKEN FROM THE' INTERRUPT PS BY $INTSI.
i-

.ASECT
.=177754
177754

L.CLK:'L'

.BLKW 8.

177774

L.DID: 'L'

.BLKW 1

177776
000000
000002
000004
000006
000007
000010

L. ICB: ' L'
L.LNK:'L'
L. NAM: ' L'
L.DCB:'L'
L. NUM: ' L'
L.STS:'L'
L.KRB:'L'

.BLKW 1
.BLKW 1
.BLKW 1
.BLKW 1
.BLKB 1
.BLKB 1
.BLKW 1

iSTART OF CLOCK BLOCK (CLK BLK IS

iOPTIONAL, AND DRIVER DEPENDENT.
iALtOCATION OF THESE 8 WORDS IS NOT
iREQUIRED IN THE DRIVER'S DATA BASE
iUNLESS USED BY THE DRIVER ITSELF)
iHARDWARE DEVICE ID (WORD ALLOCATION
iALWAYS REQUIRED. MAY BE 0).
iICB CHAIN FOR THIS CTB
iCTB LINK WORD
iGENERIC CONTROLLER NAME (ASCII)
iDCB ADDRESS OF THIS DEVICE
iNUMBER OF KRB ADDRESSES IN TABLE
iCTB STATUS BYTE
iSTART OF KRB ADDRESSES

NOTE: THE SYMBOL $XXCTB:: IS DEFINED FOR EACH CTB, WHERE THE
SYMBOL IS NOT THE START OF THE CTB, BUT INSTEAD THE START OF
THE KRB .TABLE AT THE END OF THE CTB (L.KRB). THE SYMBOL XXCTB (NO"$")
IS GENERATED BY THE DDT$ MACRO AND IS USED TO IDENTIFY THE
WORD IN THE DRIVER WHICH CONTAINS THE ADDRESS OF THE CONTROLLER'S
CTB IN PRIMARY POOL. XXCTB IS REFERENCE BY THE CODE GENERATED IN THE
INTSV$ MACRO WHEN DETERMINING THE UCB ADDRESS.

i+
i

CONTROLLER TABLE STATUS BYTE BIT DEFINITIONS

i -

LS.CLK='B'l
LS.MDC='B'2
LS.CBL='B'4

iCLOCK BLOCK AT TOP OF CTB (l=YES)
iMULTIDRIVER CTB (l=YES)
iCLOCK BLK LINKED INTO CLK Q (l=YES)
A-15

CTBDF$
LS.CIN='B'10
LS.NET'B'=20

iCONT. USE COMMON INT TABLE (l=YES)
;THIS IS DECNET DEVICE
;ICB LISTHEAD IN K.PRM, L.DCB INVALID (l=YES)

A-16

DCBDF$

A.7

DCBDF$

DEVICE CONTROL BLOCK
THE DEVICE CONTROL BLOCK (DCB) DEFINES GENERIC INFORMATION
ABOUT THE LOGICAL ACCESS TO THE DEVICE. THIS INCLUDES THE
LOWEST AND HIGHEST LOGICAL UNIT NUMBERS (NOT THE PHYSICAL
UNIT NUMBERS FOUND IN U.UNIT), THE LENGTH OF THE ASSOCIATED
UCB(S), A POINTER TO THE FIRST UCB (ADDITIONAL UCBS IMPLIED
BY D.UNIT ARE ALLOCATED CONTIGUOUSLY TO THE FIRST UCB), THE
CLASSIFICATION OF EACH POSSIBLE I/O FUNCTION CODE, AND A
POINTER TO THE DEVICE DRIVER AND ITS DISPATCH TABLE. THE IS
AT LEAST ONE DCB FOR EVERY LOGICAL DEVICE NAME IN THE SYSTEM.
FOR EXAMPLE THE LOGICAL DEVICE NAME 'TT' IS ASSOCIATED WITH
THE BITMAP VIDEO (TTl:) AND THE PRINTER PORT (TT2:). BOTH ARE
MANAGED BY THE FULL DUPLEX TERMINAL DRIVER AND SINCE
IO.RSD/IO.WSD ARE TTl: SPECIFIC, TWO DCBS ARE USED RATHER THAN
ONE SINCE THE FUNCTION CODE MASKS ARE DIFFERENT. IT IS
CONCEPTUALLY POSSIBLE TO ADD A USER WRITTEN DRIVER THAT HAS THE
LOGICAL DEVICE NAME 'TT' THOUGH IT MUST HAVE DIFFERENT LOGICAL
UNIT NUMBERS (IE:TT3:)

,. 000022
000000
000000
000002
000004
000006

.ASECT
.=0
D.LNK:
D.UCB:
D.NAM:
D.UNIT:

000007

.BLKW
.BLKW
.BLKW
.BLKB

1
1
1
1

.BLKB

000010

D.UCBL:

.BLKW

000012
000014
000016
000020
000022
000024
000026
000030
000032
000034

D.DSP:
D.MSK:

.BLKW
.BLKW
.BLKW
.BLKW
.BLKW
.BLKW
.BLKW
.BLKW
.BLKW
.BLKW

1
1
1
1
1
1
1
1
1
1

D.PCB:

LINK TO NEXT DCB
POINTER TO FIRST UNIT CONTROL BLOCK
GENERIC DEVICE NAME
LOWEST UNIT NUMBER COVERED BY THIS
DCB
HIGHEST UNIT NUMBER COVERED BY THIS
DCB
LENGTH OF EACH UNIT CONTROL BLOCK
IN BYTES
POINTER TO DRIVER DISPATCH TABLE
LEGAL FUNCTION MASK CODES 0-15.
CONTROL FUNCTION MASK CODES 0-15.
NOP'ED FUNCTION MASK CODES 0-15.
ACP FUNCTION MASK CODES 0-15.
LEGAL FUNCTION MASK CODES 16.-31.
CONTROL FUNCTION MASK CODES 16.-31.
NOP'ED FUNCTION MASK CODES 16.-31.
ACP FUNCTION MASK CODES 16.-31.
LOADABLE DRIVER PCB ADDRESS

.PSECT

A-17

DCBDF$

i+
i DRIVER DISPATCH TABLE OFFSET DEFINITIONS
i-

177770

D.VTOU=-10

177772

D.VTIN=-6

177774

D.VCHK=-4

177774

D.VNXC=-4

177776
000000
000002
000004
000006
000010
000012

D.VDEB=-2
D.VINI=O
D.VCAN=2
D.VOUT=4
D.VPWF=6
D.VKRB=10
D.VUCB=12
.IF NB

000014

D.VINT=14

ADDRESS OF ROUTINE IN TTDRV CALLED
FOR OUTPUT COMPLETION
ADDRESS OF ROUTINE IN TTDRV CALLED
FOR INPUT FROM THE CT FIRMWARE TASK
ADDRESS OF ROUTINE CALLED TO VALIDATE
AND CONVERT THE LBN. USED BY DRIVERS
THAT SUPPORT SEEK OPTIMIZATION.
ADDRESS OF ROUTINE IN TTDRV CALLED TO
HAVE IT SEND THE NEXT COMMAND IN THE -.
TYPEAHEAD BUFFER TO MCR (NOT USED BY
P/OS)
DEALLOCATE BUFFER(S)
DEVICE INITIATOR
CANCEL CURRENT I/O FUNCTION
DEVICE TIMEOUT
POWERFAIL RECOVERY
CONTROLLER STATUS CHANGE ENTRY
UNIT STATUS CHANGE ENTRY
SYSDF
iBEGINNING OF INTERRUPT STUFF
.ENDC

A-18

DDT$
A.S

OOT$

i+
i GENERATE
i-

THE I/O DEVICE DRIVER DISPATCH TABLE -- DDT$

. MACRO DDT$
DEV,NCTRLR,INY,INX,UCBSV,NEW,BUF,OPT
<OPT>
· IF NB
. WORD
'DEV'CHK
.ENDC
.IF NB <BUF>
· WORD
' DEV' DEA
.IFF
.IF NB <OPT>
.WORD
172361
jENTRY SHOULD NOT BE USED - CRASH
.ENDC
.ENDC
.ENABL LSB
.IF B
<INX>
$'DEV'TBL::.WORD DEV'INI
.IFF
$'DEV'TBL::.WORD DEV'INX
.ENDC
. WORD
DEV'CAN
. WORD
DEV'OUT
<NEW>
· IF B
. WORD
65533$
. WORD
o
. WORD
65531$
.IFF
. WORD
DEV'PWF
. WORD
DEV'KRB
. WORD
DEV'UCB
.ENDC
.IF DIF <INY>,<NONE>
.ASCII /DEV/
.IF B
<INY>
. WORD
$'DEV'INT
.IFF
X,<INY>
· IRP
$' DEV' , X
.WORD
.ENDM
.ENDC
.WORD
0
'DEV'CTB:
.WORD
0
.ENDC
$'DEV'TBE::.WORD 0
.IF NB <UCBSV>
UCBSV:
.BLKW
NCTRLR
.ENDC
<NEW>
· IF B
A-19

DDT$
65531$:
65533$:
65532$:

BITB
BEQ
BCS
JMP
RETURN
.ENDC
. DSABL
.ENDM

#UC.PWF,U.CTL(R5)
65532$
65532$
DEV'PWF
LSB

A-20

FllDF

A.9

F11DF
VOLUME CONTROL BLOCK
.ASECT

000174
000000

.=0

000000
000002
000000
000001
000002
000010
000011
000003
000001
000002
000004
000010
000020

V . TRCT: . BLKW
V.TYPE:.BLKB
VT.FOR= 0
VT.SL1= 1
VT.SL2= 2
VT.ANS= 10
VT.UNL= 11
V. VCHA: . BLKB
VC.SLK= 1
VC.HLK= 2
VC.DEA= 4
VC.PUB= 10
VC.DUP= 20

000004
000020
000024
000024
000026
000032
000033
000034
000036
000040

V.LABL:.BLKB
V . PKSR: . BLKW
V.SLEN:
V . I FW I : . BL KW
V . FCB: . BLKW
V. IBLB: . BLKB
V . I BS Z : . BLKB
.BLKW
V . FMAX: . BLKW
V.WISZ:.BLKB

000041
000042
000044
000045
000046
000050
000'052
000054
000056
000057
000060
000062
000001
000002
000063
000064
000066

V. SBCL: . BLKB
V • S B S Z : • BL KW
V . SBLB: . BLKB
V. FlEX: . BLKB
.BLKW
V. VOWN: . BLKW
V . VPRO: . BLKW
V. FPRO: . BLKW
V . FRBK: . BLKB
V.LRUC:.BLKB
.BLKW
V. STS : . BLKB
VS.IFW= 1
VS.BMW= 2
V . F FNU: . BL KB
V . EXT: . BLKW
V.HBLB:.BLKW

1
1

14
2
1
2
1
1
1
1
1

1
1

1
1
1
1

1
1

1
1
1
1

1
2

TRANSACTION COUNT
VOLUME TYPE DESCRIPTOR
FOREIGN VOLUME STRUCTURE
FILES-ll STRUCTURE LEVEL 1
FILES-11 STRUCTURE LEVEL 2
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
DUPLICATE VOL NAME;
DON'T DELETE LOGICALS
VOLUME LABEL (ASCII)
PACK SERIAL NUMBER FOR ERROR LOGGING
LENGTH OF SHORT VCB
INDEX FILE WINDOW
FILE CONTROL BLOCK LISTHEAD
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
FREE BLOCKS ON VOLUME HIGH BYTE
AVAILABLE LRU SLOTS IN FCB LIST
FREE BLOCKS ON VOLUME LOW BITS
VOLUME STATUS BYTE, CONTAINING:
INDEX FILE IS WRITE ACCESSED
STORAGE BITMAP FILE IS WRITE ACCESSED
FIRST FREE INDEX FILE BITMAP BLOCK
POINTER TO VCB EXTENSION
LBN OF HOME BLOCK

A-21

FllDF

000076

V.HBCS:.BLKW
2
; HOME BLOCK CHECKSUMS
V.LGTH: ; SIZE IN BYTES OF VCB

MOUNT LIST ENTRY
EACH ENTRY ALLOWS ACCESS TO A SPECIFIED USER FOR A NON-PUBLIC DEVICE
TO ALLOW EXPANSION, ONLY THE ONLY TYPE CODE DEFINED IS "1" FOR
DEVICE ACCESS BLOCKS
.ASECT

000076
000000

.=0

000000
000002
000001
000003
000004
000006
000010

M.LNK:.BLKW
1
LINK WORD
TYPE OF ENTRY
M.TYPE:.BLKB
1
MOUNTED VOLUME USER ACCESS LIST
MT.MLS= 1
NUMBER OF ACCESSES
M.ACC:.BLKB
1
DEVICE UCB
M.DEV:.BLKW
1
M.TI:.BLKW
1
ACCESSOR TI: UCB
M.LEN:
; LENGTH OF ENTRY

FILE CONTROL BLOCK
.ASECT

000010
000000

.=0

000000
000002
000004
000006
000010
000012
000014
000015
000016

F.LINK:.BLKW
F.FNUM:.BLKW
F.FSEQ:.BLKW
F.DREF:.BLKW
F.FOWN:.BLKW
F.FPRO:.BLKW
F.UCHA:.BLKB
F.SCHA:.BLKB
F.HDLB:.BLKW

1
1
1
1
1
1
1
1

000022

F.LBN:.BLKW

000026
000032
000033
000012
000034
000034
000035
100000
040000

F.SIZE:.BLKW
F.NACS:.BLKB
F.NLCK:.BLKB
S.STBK=.-F.LBN
F.STAT:
F.NWAC:.BLKB
.BLKB
FC.WAC= 100000
FC.DIR= 40000

2
1
1

1
1

FCB CHAIN POINTER
FILE NUMBER
FILE SEQUENCE NUMBER
DIRECTORY EOF BLOCK 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
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
A-22

FllDF
020000
010000
004000

SET IF DIRECTORY EOF NEEDS UPDATING
SET IF TRYING TO FORCE DIRECTORY CONTIG
SET IF DIRECTORY NAME IS VALID

FC.CEF= 20000
FC.FCO= 10000
FC.DNV= 4000

IF FC.DNV IS SET, THEN THIS FCB IS ENTERED IN THE DIRECTORY FCB LRU
CACHE. IN THIS CASE, F.DRNM IS THE FIRST WORD OF THE DIRECTORY NAME,
F.LKL AND F.WIN ARE REUSED FOR THE SECOND AND THIRD WORDS OF THE
DIRECTORY NAME, RESPECTIVELY, AND F.DID IS THE FILE 10 OF THE
DIRECTORY THAT THIS DIRECTORY IS ENTERED IN. IF FC.DNV IS CLEAR,
F.DRNM IS ZERO, F.LKL IS USED AS ADVERTISED BELOW, F.WIN IS RESERVED
FOR FUTURE USE AS THE WINDOW BLOCK LISTHEAD, AND F.DID IS ZERO.
000036
000040
000042

F.DRNM: .BLKW
F. FEXT : . BLKW
F.FVBN: .BLKB

1
1
1

000043
000044
000046
000050
000052

F.FSQN: .BLKB
.BLKW
F . LKL: . BL KW
F.WIN: .BLKW
F . DID: . BLKW

1
1
1
1
1

000054

F.LGTH:

1ST WORD OF DIRECTORY NAME
POINTER TO EXTENSION FCB
HIGH ORDER BYTE: STARTING VBN
FILE SEGMENT
FILE SEGMENT NUMBER
LOW ORDER VBN WORD OF FILE SEGMENT
POINTER TO LOCKED BLOCK LIST FOR FILE
WINDOW BLOCK LIST FOR THIS FILE
ID OF DIRECTORY THIS DIRECTORY IS
ENTERED IN
SIZE IN BYTES OF FCB

WINDOW
000054
000000

.=0

000000

W.ACT:

000000

W.BLKS:

000000

W. CTL : . BLKW

000400
001000
002000
004000
010000
020000
040000
100000
000002
000003
000004
000006
000010
000012

WI.RDV= 400
WI. WRV= 1000
WI.EXT= 2000
WI.LCK= 4000
WI.DLK= 10000
WI.PND= 20000
WI.EXL= 40000
WI.WCK= 100000
W. IOC: . BLKB
.BLKB
W. FCB: . BLKW
W. T CB: . BL KW
W. UCB: . BL KW
W. LKL: . BLKW

1
1
1
1
1
1

.ASECT
NUMBER OF ACTIVE MAPPING POINTERS
WHEN NO SECONDARY POOL
BLOCK SIZE OF SECONDARY POOL SEGMENT
WHEN SECONDARY POOL
LOW BYTE = NO. 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
TCB address of accessor
Original UCB address of device
POINTER TO LIST OF USERS LOCKED BLOCKS
A-23

FllDF
000014

W.WIN: .BLKW
.IF
.IF

NB,SYSDEF
NDF,P$$WND

WINDOW BLOCK LIST LINK WORD
IF SYSDEF SPECIFIED IN CALL
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:
W.MAP:

.BLKB

W.WISZ:

.BLKB
.BLKW

1
1

; HIGH BYTE OF 1ST VBN MAPPED BY WINDOW
; DEFINE LABEL WITH ODD ADDRESS 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

W.RTRV:
W.SLEN=-4
.IFF

Dummy definition to prevent incorrect reference
(-4 when rounded "up" is a VERY large block)
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.
000016

W. MAP: . BL KW

000020

W. SLEN:

ADDR TO THE MAPPING
PTRS IN SECONDARY POOL
Length of primary pool stub

SECONDARY POOL WINDOW
IF SECONDARY POOL WINDOW BLOCKS ARE ENABLED, THE RETRIEVAL
POINTERS ARE MAINTAINED IN SECONDARY POOL IN THE FOLLOWING
FORMAT.
000000

.:=0

000000

ASSUME W.CTL,O
.IIF NE <W.CTL>-<O>
. ERROR

000000
000001
000002

.BLKB
W. USE: . BLKB
W.VBN:.BLKB

1
1

;EXPRESSIONS NOT EQUAL

NUMBER OF ACTIVE MAPPING POINTERS
STATUS OF BLOCK
HIGH BYTE OF 1ST VBN MAPPED BY WINDOW
A-24

FllDF
000003
000004
000006

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 WIND

.~NDC

END SECONDARY POOL WINDOW CONDITIONAL

.ENDC

END SYSDEF CONDITIONAL

LOCKED BLOCK LIST NODE
.ASECT

000006
000000

.=0

000000
000002
000004
000005
000006
000010

L.LNK: .BLKW
L. Wll: . BLKW
L.VB1:.BLKB
L.CNT: .BLKB
.BLKW
L.LKSZ:

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

END OF DEFINITIONS

A-25

GTPKT$

A.10

GTPKT$

GET I/O PACKET MACRO -- AUTOMATES UNIT DETERMINATION -- GTPKT$
. MACRO
CALL
.IF B
BCC
RETURN

GTPKT$
$GTPKT
<ADDR>
65535$

DEV,NCTRLR,ADDR,UCBSV,SUC

65535$:
· IFF
BCS
.ENDC
.IF B
· IF B
MOV
.ENDC
.IFF
· IF GT
MOV
.IFF
MOV
.ENDC
.ENDC
.ENDM

ADDR
<UCBSV>
<SUC>
R5,S.OWN(R4)
NCTRLR-l
R5,UCBSV(R3)
R5,UCBSV

A-26

HDRDF$

A.11

HDRDF$

i+
i 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
H . IPS: . BLKW
H . I PC: . BLKW
H • I S P : • B L KW
H. ODVA: . BLKW
H.ODVL: .BLKW
H. TKVA: . BLKW
H.TKVL:.BLKW
H . P FVA: . BLKW
H. FPVA: . BLKW
H.RCVA: .BLKW
H . EFSV: . BLKW
H.FPSA: .BLKW
H.WND: .BLKW
H.DSW: .BLKW
H.FCS: .BLKW
H. FORT: . BLKW
H.OVLY:.BLKW
H . VEXT: . BLKW
H.SPRI:.BLKB
H.NML: .BLKB
H. RRVA: . BLKW
H.X25: .BLKB
.BLKB
.BLKW
H.GARD:.BLKW
H . NLUN: . BLKW
H.LUN: .BLKW

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
2
1
1
2

iCURRENT STACK POINTER
iHEADER LENGTH IN BYTES
iSUPERVISOR D SPACE OVERMAP MASK
iUSER D SPACE OVERMAP MASK
iRESERVED
iCURRENT TASK UTC
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 ADDR
iRECEIVE AST CONTROL BLOCK ADDRESS
iEVENT FLAG ADDRESS SAVE ADDRESS
iPOINTR 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 MAILBOX LUN
iRECEIVE BY REF AST CONTROL BLOCK ADDR
iFOR USE BY x25 SOFTWARE
i5 RESERVED BYTES
iPOINTER TO HEADER GUARD WORD
iNUMBER OF LUN'S
iSTART OF LOGICAL UNIT TABLE

i+
i LENGTH OF FLOATING POINT SAVE AREA
i-

H.FPSL=25.*2
i+
i WINDOW BLOCK OFFSETS

A-27

HDRDF$

,.000000
000002
000004
000006
000010
000012
000014
000015
000016
000020

.=0
W. BPCB : . BLKW
W.BLVR:.BLKW
W. BHVR: . BLKW
W.BATT: .BLKW
W.BSIZ:.BLKW
W. BOFF : . BLKW
W.BFPD:.BLKB
W.BNPD: .BLKB
W.BLPD:.BLKW
W.BLGH:

1
1
1
1
1
1
1
1
1

iPARTITION CONTROL BLOCK ADDRESS
iLOW VIRTUAL ADDRESS LIMIT
iHIGH VIRTUAL ADDRESS LIMIT
iADDRESS OF ATTACHMENT DESCRIPTOR
iSIZE OF WINDOW IN 32W BLOCKS
iPHYSICAL MEMORY OFFSET IN 32W BLOCKS
iFIRST PDR ADDRESS
iNUMBER OF PDRs TO MAP
iCONTENTS OF LAST PDR
iLENGTH OF WINDOW DESCRIPTOR

BIT DEFINITION FOR W.BLPD
WB.NBP=20
WB.BPS=40

iCACHE BYPASS IS NOT DESIRED FOR THIS
iWINDOW
iALWAYS BYPASS THE CACHE FOR THIS
iWINDOW

.PSECT

A-28

HWDDF$

A.12

HWDDF$

i+
i MACROS
i-

FOR DEFINING MAPPING REGISTER DEFINITIONS
. MACRO CRESET NAM,ADDR
$$$=0
.REPT
8.
CRENAM NAM,ADDR+<$$$*2),\$$$
$$$=$$$+1
.ENDR
.ENDM
. MACRO CRENAM
'NAM' 'N'==ADDR
.ENDM

NAM,ADDR,N

i+
i HARD~ARE REGISTER ADDRESSES AND STATUS CODES
i -

177746
172100
177772
000000
000040
000200
000240
000300
000340
177776
177570
177564

MPCSR=177746
MPAR=172100
PIRQ=177772
PRO=O
PR1=40
PR4=200
PR5=240
PR6=300
PR7=340
PS=177776
SWR=177570
TPS=177564

iADDRESS OF PDP-11/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

i+
i EXTENDED
i-

ARITHMETIC ELEMENT REGISTERS

.IF DF

E$$EAE

AC=177302
MQ=177304
SC=177310

iACCUMULATOR
iMULTIPLIER-QUOTIENT
;SHIFT COUNT

.ENDC

i+
i MEMORY MANAGEMENT HARDWARE REGISTERS AND STATUS CODES
i-

A-29

HWOOF$
172340
172342
172344
172346
172350
172352
172354
172356
172300
172302
172304
172306
172310
172312
172314
172316
172360
172362
172364
172366
172370
172372
172374
172376
172320
172322
172324
172326
172330
172332
172334
172336
172240
172242
172244
172246
172250
172252
172254
172256
172200
172202
172204
172206
172210
172212
172214
172216
172260
172262
172264

KINARO
KINAR1
KINAR2
KINAR3
KINAR4
KINAR5
KINAR6
KINAR7
KINDRO
KINDR1
KINDR2
KINDR3
KINOR4
KINDR5
KINDR6
KINDR7
KDSARO
KOSAR1
KDSAR2
KDSAR3
KDSAR4
KDSAR5
KDSAR6
KDSAR7
KDSDRO
KDSDR1
KDSDR2
KDSDR3
KDSDR4
KDSDR5
KDSDR6
KDSDR7
SISARO
SISAR1
SISAR2
SISAR3
SISAR4
SISAR5
SISAR6
SISAR7
SISDRO
SISDR1
SISDR2
SISDR3
SISDR4
SISDR5
SISDR6
SISDR7
SDSARO
SDSAR1
SDSAR2
A-30

HWDDF$
172266
172270
172272
172274
172276
172220
172222
172224
172226
172230
172232
172234
172236
177640
177642
177644
177646
177650
177652
177654
177656
177600
177602
177604
177606
177610
177612
177614
177616
177660
177662
177664
177666
177670
177672
177674
177676
177620
177622
177624
177626
177630
177632
177634
177636
172340
172342
172344
172346
172350
172352

SDSAR3
SDSAR4
SDSAR5
SDSAR6
SDSAR7
SDSDRO
SDSDR1
SDSDR2
SDSDR3
SDSDR4
SDSDR5
SDSDR6
SDSDR7
UINARO
UINAR1
UINAR2
UINAR3
UINAR4
UINAR5
UINAR6
UINAR7
UINDRO
UINDR1
UINDR2
UINDR3
UINDR4
UINDR5
UINDR6
UINDR7
UDSARO
UDSAR1
UDSAR2
UDSAR3
UDSAR4
UDSAR5
UDSAR6
UDSAR7
UDSDRO
UDSDR1
UDSDR2
UDSDR3
UDSDR4
UDSDR5
UDSDR6
UDSDR7
KISARO
KISAR1
KISAR2
KISAR3
KISAR4
KISAR5
A-31

HWDDF$
172354
172356
172300
172302
172304
172306
172310
172312
172314
172316
177640
177642
177644
177646
177650
177652
177654
177656
177600
177602
177604
177606
177610
177612
177614
177616

KISAR6
KISAR7
KISORO
KISOR1
KISOR2
KISOR3
KISOR4
KISOR5
KISDR6
KISOR7
UISARO
UISAR1
UISAR2
UISAR3
UISAR4
UISAR5
UISAR6
UISAR7
UISORO
UISOR1
UISOR2
UISOR3
UISOR4
UISDR5
UISDR6
UISDR7

170200
140000
030000
040000
010000
177572
172516
177766
177744
177746

UBMPR=170200
CMODE=140000
PMODE=30000
CSMODE=40000
PSMODE=10000
SRO=177572
SR3=172516
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
;PREVIOUS MODE = SUPERVISOR PS WORD BITS
;SEGMENT STATUS REGISTER 0
iSEGMENT STATUS REGISTER 3
iCPU ERROR REGISTER
iMEMORY SYSTEM ERROR REGISTER
;MEMORY CONTROL REGISTER

;+
i DEFINE THE LOCATIONS USED IN THE NON-VOLATILE RAM
i FOR XT SYSTEMS
;-

173054
173064
173074
173104
173114
173116
173120

N.KEY=173054
N.UPT=173064
N.DZA=173074
N.DWA=173104
N.DAY=173114
N.MON=173116
N.YEA=173120

(NVR)

iNUMBER OF KEYS PRESSED
iUPTIME IN MINUTES
iNUMBER OF I/OS DONE ON THE DZ
iNUMBER OF I/OS DONE ON THE DW
iDATE THAT THE NVR WAS LAST INITIALIZED
I

•••

, ...
A-32

HWDDF$

i+
i FEATURE
i-

000001
000002
000004
000010
000020
000040
000100
000200
000400
001000
002000
004000
010000
020000
040000
100000

SYMBOL DEFINITIONS
FE.EXT=l
FE.MUP=2
FE. EXV=4
FE.DRV=10
FE.PLA=20
FE.CAL=40
FE.PKT=100
FE.EXP=200
FE.LSI=400
FE.OFF=1000
FE.FDT=2000
FE.X25=4000
FE.DYM=10000
FE.CEX=20000
FE.MXT=40000
FE.NLG=100000

i22-BIT EXTENDED MEMORY SUPPORT
iMULTI-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-ll
iPARENT/OFFSPRING TASKING SUPPORTED
iFULL DUPLEX TERMINAL DRIVER SUPPORTED
iX.25 CEX IS LOADED
iDYNAMIC MEMORY ALLOCATION SUPPORTED
iCOM EXEC IS LOADED
iMCR EXIT AFTER EACH COMMAND MODE
iLOGINS DISABLED - MULTI-USER SUPPORT

i+
i FEATURE
i-

000001
000002
000004
000010
000020
000040
000100
000200
000400
001000
002000
004000
010000
020000
040000
100000

MASK DEFINITIONS (SECOND WORD)
F2.DAS=1
F2.LIB=2
F2.MP=4
F2.EVT=10
F2.ACN=20
F2.SDW=40
F2.POL=100
F2.WND=200
F2.DPR=400
F2.IRR=1000
F2.GGF=2000
F2.RAS=4000
F2.AHR=10000
F2.RBN=20000
F2.SWP=40000
F2.STP=100000

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)

i+
i THIRD FEATURE MASK SYMBOL DEFINITIONS
i-

000001
000002
000004
000010
000020

F3.CRA=1
F3.XCR=2
F3.EIS=4
F3.STM=10
F3.UDS=20

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
A-33

HWDDF$
000040
000100
000200
000400
001000
002000
004000
010000
020000
040000

F3.PRO=40
F3.XHR=100
F3.AST=200
F3.11S=400
F3.CLI=1000
F3.TCM=2000
F3.PMN=4000
F3.WAT=10000
F3.RLK=20000
F3.SHF=40000

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

i+
i FOURTH FEATURE MASK BITS
i-

000001
000002
000002
000004
000010
000020
000040
000100
000200
000400
001000
002000
004000
010000
020000
040000
100000
000001

F4.CXD=1
F4.XT=2
F4.POS=F4.XT
F4.ERL=4
F4.PTY=10
F4.DVN=20
F4.LCD=40
F4.NIM=100
F4.CHE=200
F4.LOG=400
F4.NAM=1000
F4.FMP=2000
F4.DCL=4000
F4.DDS=10000
F4.ACD=20000
F4.NCT=40000
F4.LSD=100000
FS.P3X=1

iCOMM EXEC IS DEALLOCATED (NON-I/O ONLY)
iSYSTEM IS AN XT SYSTEM (l=YES)
iSYNONYM -- SYSTEM IS A P/OS SYSTEM (l=YES)
iSYSTEM SUPPORTS ERROR LOGGING (l=YES)
iSYSTEM SUPPORTS PARITY MEMORY (l=YES)
iSYSTEM SUPPORTS DECIMAL VERSIONS (l=YES)
iSYSTEM SUPPORTS LOADABLE CRASH (l=YES)
iSYSTEM SUPPORTS DELETED TASK IMAGES (l=YES)
iSYSTEM SUPPORTS DISK DATA CACHING (l=YES)
iSYSTEM SUPPORTS LOGICAL NAMES (l=YES)
iSYSTEM SUPPORTS NAMED DIRECTORIES (l=YES)
iSYSTEM SUPPORTS FAST MAP DIRECTIVE
iDCL IS DEFAULT CLI (l=YES)
iNAMED DIRECTORY MODE IS THE DEFAULT (l=YES)
iSYSTEM SUPPORTS ACDs (l=YES)
iSYSTEM HAS NCT SUPPORT (l=YES)
iSYSTEM HAS LUT SCAN DISABLED
iSYSTEM SUPPORTS PROFESSIONAL 3XX SERIES

HARDWARE FEATURE MASK BIT DEFINITIONS
HF.CIS,HF.FPP DEFINED AS SIGN BITS FOR RUN TIME SPEED
i-

000001
000002
000004
000010
000200
100000

HF.UBM=l
HF.EIS=2
HF.QB=4
HF.DSP=10
HF.CIS=200
HF.FPP=100000

iPROCESSOR HAS A UNIBUS MAP (l=YES)
iPROCESSOR HAS EXTENDED INSTRUCION SET
iSYSTEM HAS A QBUS (l=YES)
iHARDWARE SUPPORTS DATA SPACE
iPROCESSOR SUPPORTS COMMERCIAL INSTRUCTION SET
i(l=PROC. HAS NO FLOATING POINT UNIT)

i+
i SECOND HARDWARE FEATURE MASK BIT DEFINITIONS
i THIS WORD IS RESERVED FOR XT HARDWARE FEATURES
i-

A-34

HWDDF$
000001
000002
000004
000010

H2.NVR=1
H2. INV=2
H2.CLK=4
H2.ITF=10

000020
000040
000100
100000

H2.PRO=20
H2.WS=40
H2.FS=100
H2.BRG=100000

NON-VOLATILE RAM PRESENT (l=YES)
iNON-VOLATILE RAM IS INVALID (l=YES)
iXT CLOCK IS PRESENT (l=YES)
iINVALID TIME FORMAT IN NON-VOLATILE RAM
i(l=YES)
iRUNNING ON PRO/3XX HARDWARE
iSYSTEM IS A WORKSTATION (l=YES)
iSYSTEM IS A FILESERVER (l=YES)
iXT BRIDGE MODULE PRESENT (l=YES)
iXT

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 RECORDED FOR OUR INFORMATIONAL
PURPOSES ONLY. THEY CANNOT BE TESTED LIKE BITS IN THE FEATURE MASK
SINCE THIS ONLY EXISTS IN THE RSXllM.STB FILE. NO BITS IN MEMORY ARE
USED. THEY ARE ONLY INTENDED TO BE PRINTED FROM THE STB FILE BY CDA.
i-

000001
000002

iSTANDARD EXEC SELECTED
iSYSTEM WAS PRE-GENERATED (EX.
iRL02/RC25 SYSTEM)

SF.STD=l
SF.PGN=2

i+
i MULTIPROCESSOR STATUS TABLE DEFINITIONS (TEMPORARY)
i-

100000
040000
020000
010000
000004
007777

MP.CRH=100000
MP.PWF=40000
MP.RSM=20000
MP.NOP=10000
MP.STP=4
MP.INT=7777

iCRASH PROCESSOR IMMEDIATELY
iPOWERFAIL ON ONE CPU
iRESET INTERRUPT MASKS
iNOP FUNCTION FOR TRANSMISSION CHECK
jSTOP PROCESSOR IN ORDERLY FASHION
iSIC MASK FOR INTERRUPT LVL FUNCTIONS

. MACRO
.ENDM

X,Y,Z

HWDDF$

A-35

INTSV$

A.13

INTSV$

INTERRUPT SAVE GENERATION FOR NON-ERROR LOGGING DEVICES -- INTSV$

. MACRO
GTUCB$
.ENDM

INTSV$ DEV,PRI,NCTRLR,PSWSV,UCBSV
UCBSV,NCTRLR,DEV

GENERATE CODE TO LOAD UCB ADDRESS INTO R5 -- CALLED
ONLY BY INTSV$, AND TTSET$ (IN TTDRV) .

. MACRO
.IF NB
.IF GT
MOV
.IFF
MOV
.ENDC
.IFF
MOV
ADD
MOV
MOV
.ENDC
.ENDM

GTUCB$ UCBSV,NCTRLR,DEV
<UCBSV>
NCTRLR-l
UCBSV(R4),R5
UCBSV,R5

'DEV'CTB,R5
R4,R5
(R5) ,R5
K.OWN(R5),R5

;;;GET ADDRESS OF KRB TABLE IN CTB
;;;ADD CONTROLLER INDEX
;;;GET KRB ADDRESS FROM CTB
;;;RETRIEVE OWNER'S UCB ADDRESS

A-36

ITBDF$

A.14

ITBDF$

i+
i INTERRUPT
i-

TRANSFER BLOCK (ITB) OFFSET DEFINITIONS
.IF OF

A$$TRP

• MCALL
PKTDF$

PKTDF$
DEFINE AST BLOCK OFFSETS

.ENDC
.ASECT

000000

.=0
X.LNK:

000002
000006
000007
000010
000012
000012
000014
000016
000020

X.JSR: JSR
X.PSW:
.BLKB
.BLKB
X. ISR:
.BLKW
X.FORK:
.BLKW
.BLKW
.BLKW
.BLKW

RS,@#O

.IF OF

M$$MGE

.BLKW

X.REL: .BLKW

1
1
1

1
1
1
1

LINK WORD FOR ITB LIST STARTNG IN
TCB
CALL $INTSC
LOW BYTE OF PSW FOR ISR
UNUSED
ISR ENTRY POINT (APRS MAPPING)
FORK BLOCK
THREAD WORD
FORK PC
SAVED RS
SAVED R4

RELOCATION BASE FOR APRS

.BLKW
.BLKW

ADDRESS OF DIS. INT. ROUTINE
TCB ADDRESS OF OWNING TASK

.IF NB

SYSDF

.IF OF

A$$TRP

.BLKW
.BLKB

1
A.PRM

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

000022
000024

X.DSI:
X.TCB:

X.AST:

.ENDC

000026

X.VEC:

.BLKW

000030
000032

X.VPC:
X.LEN:

.BLKW

.ENDC

A-37

ITBDF$

.PSECT

A-38

KRBDF$

A.15

KRBDF$

CONTROLLER REQUEST BLOCK (KRB)

,. -

THE CONTROLLER REQUEST BLOCK DEFINES THE ENVIRONMENT OF A
DEVICE CONTROLLER.
ONE KRB EXISTS FOR EVERY DEVICE CONTROLLER
IN A P/OS SYSTEM.
THE KRB CONTAINS CERTAIN DEVICE STATUS
INCLUDING THE CSR -- FIRST DEVICE REGISTER, VECTOR ADDRESS,
INTERUPT CONTROLLER 'A' CSR AND THE SLOT NUMBER FOR THE
CONTROLLER .

.ASECT
.=177764
177764
K.PRM:
177766
K.ICSR:

.BLKW
.BLKW

1
1

177770
177771
177772
177773
177774
177775
177776
000000

.BLKB
.BLKB
.BLKB
.BLKB
.BLKB
.BLKB
.BLKW
.BLKW

1
1
1
1
1
1
1
1

K.SLT:
K.PRI:
K.VCT:
K.CON:
K.IOC:
K.STS:
K.CSR:

iDEVICE DEPENDANT PARAMETER WORD
iINTERRUPT 'A' CONTROLLER CSR (ADD 6
iFOR ICSR IF APPROPRIATE TO DEVICE)
iSLOT NUMBER
iRESERVED
iCONTROLLER PRIORITY
iINTERRUPT VECTOR ADDRESS
iCONTROLLER INDEX WITHIN THE SYSTEM
iCONTROLLER I/O COUNT
iCONTROLLER STATUS
iADDRESS OF CONTROL STATUS REGISTER

i NOTE: K.CSR MUST BE THE ZERO OFFSET!
000002
000004
000005
000006
000010
000014
000016

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
iOWNER OF CONTROLLER
iCONTROLLER REQUEST QUEUE
iRESERVED FOR FUTURE USE
iPOSSIBLE KRB FORK BLOCK

OFFSETS FOR THE KRB EXTENSION REACHED BY ADDING .(K.OFF) TO
THE STARTING ADDRESS OF THE KRB.

WHEN ONE ADDS (K.OFF) TO THE KRB ADDRESS, IT YIELDS AN
ADDRESS WHICH POINTS TO HERE.
i-

000020

KE.UCB:

.BLKW

iOFFSET TO UCB TABLE (IF KS.UCB SET)

.PSECT
i+
i

CONTROLLER REQUEST BLOCK (KRB) STATUS BIT DEFINITIONS

A-39

KRBDF$

,· 000001
000002
000004
000010
000020

KS.OFL=l
KS.MOF=2
KS.UOP=4
KS.MBC=10
KS.SDX=20

000040 •
000100
000200
000400

KS.POE=40
KS.UCB=100
KS.DIP=200
KS.PDF=400

001000

KS.EXT=1000

002000

KS.SLO=2000

iCONTROLLER OFFLINE (l=YES)
iCONTROLLER MARKED FOR OFFLINE (l=YES)
iSUPPORTS OVERLAPPED OPERATION (l=YES)
i(RESERVED)
;SEEKS ALLOWED DURING DATA XFERS
(l=YES)
iPARALLEL OPERATION ENABLED (l=YES)
;UCB TABLE PRESENT (l=YES)
iDATA TRANSFER IN PROGRESS (l=YES)
;PRIVILEGED DIAGNOSTIC FUNCTIONS ONLY
;
(l=YES)
;EXTENDED 22-BIT UNIBUS CONTROLLER
(l=YES)
;CONTROLLER IS SLOW COMING ONLINE
(l=YES)

;+
; DEFINE THE CONTIGUOUS SCB OFFSETS
;000022
177756
177760
177761
177762
177763
177764
177765
177766
177770
177772
177774
177775
177776

.ASECT
.=177756
S . I CSR: . BLKW
S.SLT: .BLKB
.BLKB
S.PRI: .BLKB
S.VCT: .BLKB
S.CON: .BLKB
.BLKB
.BLKW
S.CSR: .BLKW
.BLKW
.BLKB
.BLKB
S.OWN: .BLKW

1
1
1
1
1
1
1
1
1
1
1
1
1

;INTERRUPT 'A' CONTROLLER CSR
iSLOT NUMBER
;RESERVED
iCONTROLLER PRIORITY
;INTERRUPT VECTOR ADDRESS
;CONTROLLER INDEX
;CONTROL AND STATUS REGISTER

;DISTRIBUTED CNTBL

;+
SUBCONTROLLER REQUEST BLOCK (KRB1)
THE SUBCONTROLLER REQUEST BLOCK DEFINES THE ENVIRONMENT OF
A DEVICE SUBCONTROLLER.
EXACTLY ONE KRBl EXISTS FOR EVERY
DEVICE SUBCONTROLLER IN AN RSX-llM+ SYSTEM.
;-

.ASECT
177774

.=-4
Kl.CON: .BLKB

;SUBCONTROLLER INDEX WITHIN THE SYSTEM
A-40

KRBDF$

177775
177776
000000

.BLKB
K1.STS:.BLKW
K1.MAS:.BLKW

1
1
1

iUNUSED BYTE
iSUBCONTROLLER STATUS
iUCB ADDRESS OF THE MASTER UNIT

;
i. NOTE:

K1.MAS MUST BE THE ZERO OFFSET

;

000002
000004
000010

K1 . OWN: . BLKW
K1 . CRQ: . BLKW
K1.UCB:

1
2

iOWNER OF SUBCONTROLLER
iSUBCONTROLLER REQUEST QUEUE
iSTART OF THE UCB TABLE (IF ANY)

.PSECT

A-41

LBLDF$

A.16

LBLDF$

TASK IMAGE FILE LABEL BLOCK DEFINITIONS
RESIDENT LIBRARY DESCRIPTOR OFFSETS
j-

.ASECT

000010
000000
000004
000006
000010
000012
000014
000016

000000
.=0
R$LNAM: . BLKW
R$LSA: .BLKW
R$LHGV: . BLKW
R$LMXV: . BLKW
R$LLDZ:.BLKW
R$LMXZ:.BLKW
R$LOFF:.BLKW

000020
000022
000024
000026
000034

R$LWND: . BLKW
R$LSEG:.BLKW
R$LFLG:.BLKW
R$LDAT:.BLKW
R$LSIZ:.BLKW

RADIX-50 LIBRARY NAME
LIBRARY STARTING VIRTUAL ADDRESS
LIBRARY ADDRESS WINDOW 0 BOUND
LIBRARY HIGH VIRTUAL ADDRESS LIMIT
LIBRARY LOAD SIZE (32W BLOCKS)
LIBRARY MAX. SIZE (32W BLOCKS)
LIBRARY OFFSET INTO PARTITION
(32W BLOCKS)
NUMBER OF LIBRARY ADDRESS WINDOWS
SIZE OF LIBRARY SEGMENT DESCRIPTORS
LIBRARY FLAGS WORD
LIBRARY CREATION DATE (YR., MO., DAY)
LENGTH OF LIBRARY DESCRIPTOR

1
1

1
1
1
1

1
1
1
3

; LIBRARY LIST ENTRY FLAGS

100000
040000
020000
000010
000004
000002

LD$ACC=100000
LD$RSV=040000
LD$CLS=020000
LD$SUP=000010
LD$REL=000004
LD$TYP=000002

ACCESS INTENT (l=RW, O=RO)
APR RESERVATION FLAG (l=APR RESERVED)
LIBRARY IS PART OF A CLUSTER
SUPERVISOR MODE LIBRARY (l=YES)
PIC FLAG (l=POSITION INDEPENDANT)
SHARED REGION IS LIB (=0) OR COMMON (=1)

LABEL BLOCK OFFSETS
000000
000000

.=0
L$BTSK:.BLKW

RADIX-50 TASK NAME

*** NOTE ***
LABEL BLOCK PARAMETERS BETWEEN THIS OFFSET AND THE START OF THE
TASK LIBRARY DESCRIPTORS MUST BE IDENTICAL IN FORMAT AND CONTENT
TO A RESIDENT LIBRARY DESCRIPTOR ENTRY.

A-42

LBLDF$
000004
000010
000012
000014
000016
000020
000022
000024
000025
000026
000030
000032
000040
000346
000350
000352
000354
000356
000360
000362
000364
000366
000370
000372
000374
000376
000400
000402
000404
001000
000340

RADIX-SO PARTITION NAME
TASK STARTING VIRTUAL ADDRESS
WINDOW 0 VIRTUAL ADDRESS LIMIT
TASK HIGH VIRTUAL ADDRESS LIMIT
TASK LOAD SIZE (32W BLOCKS)
TASK MAX. SIZE (32W BLOCKS)
TASK OFFSET INTO PARTITION
(32W BLOCKS)
1
NUMBER OF TASK WINDOWS
L$BWND:.BLKB
(LESS LIBRARIES)
1
SYSTEM IDENTIFICATION
L$BSYS:.BLKB
1
SIZE OF TASK SEGMENT DESCRIPTORS (BYTES
L$BSEG: . BLKW
1
TASK FLAGS WORD
L$BFLG: .-BLKW
3
; TASK CREATION DATE (YR., MO., DAY)
L$BDAT: . BLKW
<7.*<R$LSIZ/2»+1 ; RESIDENT LIBRARY ENTRIES
L$BLIB:.BLKW
1
TASK PRIORITY
L$BPRI:.BLKW
1
TASK TRANSFER ADDRESS
L$BXFR:.BLKW
1
TASK EXTEND SIZE (32W BLOCKS)
L$BEXT:.BLKW
1
RELATIVE BLOCK NUMBER OF SEGMENT
L$BSGL:.BLKW
LENGTH LIST
RELATIVE BLOCK NUMBER OF TASK
L$BHRB:.BLKW
1
IMAGE HEADER
NUMBER OF BLOCKS IN LABEL
L$BBLK:.BLKW
1
NUMBER OF LOGICAL UNITS
L$BLUN:.BLKW
1
RELATIVE BLOCK NUMBER OF R/O
L$BROB:.BLKW 1
TASK IMAGE
L$BROL:.BLKW
1
R/O LOAD SIZE (32W BLOCKS)
L$BRDL:.BLKW
1
R/O DATA LOAD SIZE (32W BLOCKS)
L$BHDB:.BLKW
1
RELATIVE BLOCK NUMBER OF DATA HEADER
L$BDHV:.BLKW
1
DATA WINDOW 1 HIGH VIRTUAL ADDRESS
L$BDMV:.BLKW
1
DATA HIGH VIRTUAL ADDRESS
L$BDLZ:.BLKW
1
DATA LOAD SIZE
L$BDMZ:.BLKW
1
; DATA MAX SIZE
.BLKW
<512.-.>/2
L$BASG:.BLKW
0
START OF DEVICE ASSIGNMENT TABLES
$LBXL=<8.*<R$LSIZ»
LENGTH OF EXTRA WINDOWS ADDED FOR
M+ TASK'S
L$BPAR: . BLKW
L$BSA: . BLKW
L$BHGV: . BLKW
L$BMXV: . BLKW
L$BLDZ:.BLKW
L$BMXZ: . BLKW
L$BOFF:.BLKW

2
1
1
1
1
1
1

OFFSETS AT END OF LABEL BLOCK
000772
000772
000774
000776

.=772
L$BFL2:.BLKW
L$BLRL:.BLKW
L$AME:
.BLKW
.IIF NE .-1000

SECOND TASK FLAGS WORD
LABEL BLOCK REVISION NUMBER
MUST ALWAYS BE NULL
. ERROR jDEFINITIONS OVERLAP NEXT LABEL BLOCK

1
1
1

DEFINE LABEL BLOCK REVISION NUMBER. THIS SHOULD BE INCREMENTED
WHENEVER A NEW FIELD IS ADDED TO THE LABEL BLOCK. IT IS
A-43

LBLDF$
STRUCTURED WITH MAJOR/MINOR REVISION NUMBERS IN THE HIGH/LOW
BYTES, RESPECTIVELY. L$BLRL IS VALID ONLY IF TS$NEW IS SET.
LABEL BLOCKS WITHOUT TS$NEW SET ARE CONSIDERED REVISION O. THIS
TURNS OUT HANDY, SINCE WE BELIEVE THEY ALL HAVE ZEROS IN THE
L$BLRL OFFSET, ANYWAY.
000400

LB$REV=000400

MAJOR REVISION LEVEL = 1
MINOR REVISION LEVEL = 0

LABEL BLOCK TASK FLAG WORD DEFINITIONS
100000
040000
020000
010000
004000
002000
000400
000200
000100
000040
000020
000010
000004
000002
000001

TS$PIC=100000
TS$NHD=040000
TS$ACP=020000
TS$PMD=010000
TS$SLV=004000
TS$NSD=002000
TS$PRV=000400
TS$CMP=000200
TS$CHK=000100
TS$RES=000040
TS$IOP=000020
TS$SUP=000010
TS$XHR=000004
TS$NXH=000002
TS$NEW=OOOOOl

TASK IS PIC (l=YES)
NO HEADER IN TASK IMAGE (l=YES)
TASK IS ANCILLARY CONTROL PROCESSOR (l=YES)
GENERATE POST-MORTEM DUMP (l=YES)
TASK IS SLAVEABLE (l=YES)
NO SEND TO TASK IS PERMITTED (l=YES)
TASK IS PRIVELEGED (l=YES)
TASK BUILT IN COMPATIBILITY MODE (l=YES)
TASK IS CHECKPOINTABLE (O=YES)
TASK HAS RESIDENT OVERLAYS (l=YES)
PRIVILEGED TASK NOT MAPPED TO I/O PAGE
TASK LINKED TO A SUPER MODE LIBRARY (l=YES)
TASK HAS AN EXTERNAL HEADER (l=YES)
TASK CAN NOT HAVE AN EXTERNAL HEADER (l=YES)
LABEL BLOCK USES NEW FORMAT
(MEANS L$BLRL DESCRIBES FORMAT)

SECOND TASK FLAGS WORD
000002
000001

T2$FMP=000002
T2$CLI=OOOOOl

000000
. MACRO
.ENDM

.PSECT
LBLDF$

TASK USES FAST MAP DIRECTIVE (l=YES)
TASK IS A CLI (l=YES)
X,Y

A-44

LNMDF$

A.17

LNMDF$

LOGICAL NAME BLOCK (LNB)

,. 001000
000000
000000
000002
000004
000006
000010
000012
000016
000016

.ASECT
.=0
L.NLNK: .BLKW
L.NLNS: .BLKW
L.NENS: .BLKW
L.NMOD: .BLKW
L.NCNT: .BLKW
L.NCBT: .BLKW
L.NNAM:
L.NHSZ=.

1
1
1
1
1
2

iLINK WORD
iSIZE OF LOGICAL NAME STRING
iLENGTH OF EQUIVALENCE NAME STRING
iMODIFIER VALUE
iUSE COUNT
iCHANNEL BLOCK TABLE BIAS AND OFFSET
iVARIABLE LENGTH LOGICAL NAME STRING
iSIZE OF LOGICAL NAME BLOCK HEADER

,. -

TABLE NUMBER DEFINITIONS

000000
000001
000002
000003
000004

LT.SYS=O
LT.GRP=l
LT.USR=2
LT.TSK=3
LT.SES=4

iSYSTEM WIDE LOGICAL NAME
iGROUP LOGICAL NAME (UIC GROUP NUMBER)
iUSER SPECIFIC LOGICAL NAME
iTASK SPECIFIC LOGICAL NAME
iSESSION LOGICAL NAME

STATUS BITS
i-

000001
000000
000001

LS.TRM=l
. MACRO
.ENDM
. END

iTERMINAL LOGICAL
.PSECT
LNMDF$

X,Y,Z

A-45

PCBDF$

A.18

PCBDF$

i+
i MAIN PARTITION PCB
i-

.ASECT
.=0
P.LNK:
P.NAM:
P.SUB:
P.MAIN:
P.REL:

000016
000016
000020
000024
000030
000032

P.BLKS:
P . S I ZE : . BL KW
P.WAIT: .BLKW
.BLKW
P.STAT: .BLKW
P • ST2 :
• B L KW

1
1

000034

.BLKW

iSIZE OF PARTITION IN 32W BLOCKS
jPARTITION WAIT QUEUE LISTHEAD
j (UNUSED)
jPARTITION STATUS FLAGS
jSTATUS EXTENSION FOR COMMON AND MAIN
iPCBs
j (UNUSED)

.BLKB
.BLKB

1
1

jSIZE OF EXTERNAL HEADER IN 32W BLOCKS
jPARTITION I/O COUNT

. BL KW

jREQUIRED RUN MASK

000042
000043

P.HDLN:
P.IOC:

.BLKW
.BLKW
.BLKW
.BLKW
.BLKW
.BLKW

jLINK TO NEXT MAIN PARTITION PCB

000000
000002
000004
000010
000012
000014

1
1

2
1
1
1

2
2

i (UNUSED)

iPARTITION NAME IN RADIX-50
iPOINTER TO FIRST SUBPARTITION
iPOINTER TO SELF
jSTARTING PHYSICAL ADDRESS IN 32W
jBLOCKS

$$$=.
P . RRM :

.IF NDF M$$PRO
.=$$$
.ENDC
.IF NB
000044

SYSDF
jPARTITION CONTROL BLOCK LENGTH

P.LGTH= .
. ENDC

i+
i TASK REGION PCB
i -

000000
000002
000003

.=0
P.LNK:
.BLKW
P . PRI :
. BLKB
P • RM CT : . B L KB

1
1
1

iUTILITY LINK WORD
iPRIORITY OF PARTITION
iRESIDENT MAPPED TASKS COUNT
A-46

PCBDF$
000004
000010
000012
000014
000016
000016
000020
000022
000024
000026
000030
000032
000034
000036

.BLKW
.BLKW
. BLKW
.BLKW

2
1
1
1

. BL KW
.BLKW
.SWSZ: .BLKW
P . 0 PCB: . BL KW
P. TCB:
. P,LKW
P.STAT: .BLKW
P.HDR:
.BLKW
.BLKW
P.ATT:
.BLKW

1
1
1
1
1
1
1
1
2

iPARTITION SWAP SIZE
iCHECKPOINT ALLOCATION PCB
iTCB ADDRESS OF OWNER TASK
iPARTITION STATUS FLAGS
iPOINTER TO HEADER CONTROL BLOCK
i (UNUSED)
iATTACHMENT DESCRIPTOR LISTHEAD

000042
000043

P. HDLN:
P.IOC:

1
1

iSIZE OF EXTERNAL HEADER IN 32W BLOCKS
iPARTITION I/O COUNT

P.NAM:
P.SUB:
P . MAl N :
P.REL:
P.BLKS:
P • S I ZE :

. BLKB
.BLKB

000044
000044

iPARTITION NAME IN RADIX-50
iPOINTER TO NEXT SUBPARTITION
iPOINTER TO MAIN PARTITION
iSTARTING PHYSICAL ADDR IN 32W BLOCKS
iSIZE OF PARTITION IN 32W BLOCKS
i (UNUSED)

$$$=.

P . RRM: . BLKW

iREQUIRED RUN MASK

.BLKW
.BLKB
.BLKB
.BLKW
.BLKW
.BLKW
• B L KW

1
1

;UTILITY LINK WORD
;PRIORITY OF PARTITION
iRESIDENT MAPPED TASKS COUNT
iPARTITION NAME IN RADIX-50
;POINTER TO NEXT SUBPARTITION
;POINTER TO MAIN PARTITION
iSTARTING PHYSICAL ADDR IN 32W BLOCKS

.IF NDF M$$PRO
.=$$$
.ENDC

i+
i COMMON REGION PCB
i -

.=0
000000
000002
000003
000004
000010
000012
000014
000016
000016
000020
000022
000024
000026
000030
000032

P.LNK:
P.PRI:
P.RMCT:
P.NAM:
P.SUB:
P.MAIN:

P.CBDL:
P. SWSZ:
P.DPCB:
P.OWN:
P.STAT:
P.ST2:

• BL KW
.BLKW
. BLKW
.BLKW
.BLKW
.BLKW
.BLKW

1
1
1
1
1
1
1

000034

P.PRO:

.BLKW

P • RE L :

2
1
1

P.BLKS:
P • S I ZE :

;SIZE OF PARTITION IN 32W BLOCKS
iCOMMON BLOCK DIRECTORY LINK
iPARTITION SWAP SIZE
iPOINTER TO DISK PCB
iOWNING UIC OF REGION
iPARTITION STATUS FLAGS
iSTATUS EXTNSN FOR COMMON AND MAIN
iPCBS
iPROTECTION WORD [DEWR,DEWR,DEWR,DEWR]
A-47

PCBDF$
000036

P .ATT:

. BLKW

iATTACHMENT DESCRIPTOR LISTHEAD

000042
000043

P • HDLN : . BLKB
P. IOC:
. BLKB

1
1

iSIZE OF EXTERNAL HEADER IN 32W BLOCKS
iPARTITION I/O COUNT

iREQUIRED RUN MASK

$$$=.
000044

P • RRM: . BLKW

.IF NDF M$$PRO
.=$$$
.ENDC
.PSECT
i+
i PARTITION STATUS WORD BIT DEFINITIONS
i-

PS.OUT=100000
PS.CKP=40000
PS.CKR=20000

iPARTITION IS OUT OF MEMORY(l=YES)
iPARTITION CHECKPOINT IN PROGRESS
i(l=YES)
iPARTITION CHECKPOINT IS REQUESTED

i(l=YES)
PS.CHK=10000

iPARTITION IS NOT CHECKPOINTABLE

i(l=YES)
PS.FXD=4000
PS.CAF=2000

;PARTITION IS FIXED (l=YES)
iCHECKPOINT SPACE ALLOCATION FAILURE

i(l=YES)
PS.LIO=1000

;MARKED BY SHUFFLER FOR LONG I/O

PS.NSF=400
PS.COM=200
PS.LFR=100
PS.PER=40

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
i(l=YES)
iPARTITION SHOULD BE DELETED WHEN NOT
iATTACHED (l=YES)
iPARTITION HAS REGION LOAD AST PENDING

i(l=YES)

PS.DEL=10
PS.AST=4
i+
i REQUIRED RUN MASK
i-

PR.UBT=100000
PR.UBS=40000
PR.UBR=20000
PR.UBP=10000
PR.UBN=4000

;UNIBUS
iUNIBUS
;UNIBUS
;UNIBUS
;UNIBUS
A-48

RUN T
RUN S
RUN R
RUN P
RUN N

PCBDF$
PR.UBM=2000
PR.UBL=1000
PR.UBK=400
PR.UBJ=200
PR.UBH=100
PR.UBF=40
PR.UBE=20
PR.CPD=10
PR.CPC=4
PR.CPB=2
PR.CPA=l

iUNIBUS RUN M
iUNIBUS RUN
iUNIBUS RUN K
iUNIBUS RUN J
iUNIBUS RUN H
iUNIBUS RUN F
iUNIBUS RUN E
iPROCESSOR D
iPROCESSOR C
iPROCESSOR
iPROCESSOR A

i+
STATUS EXTENSION WORD BIT DEFINITIONS
(THESE BITS CAN ONLY BE EXAMINED IN COMMON OR MAIN
PCBs)
i -

iDON'T SHUFFLE,DELETE SPINDLE OR MUTILATE
iTHIS PARTITION (ACTUALLY ON P/OS Vl.7 AND V2.0
iTHIS BIT HAS TAKEN ON THE EXACT OPPOSITE
iMEANING SINCE IT HAS YET TO BE IMPLEMENTED ON
iM-PLUS. TEMPORARILY, IT HAS BEEN REDEIFNED TO
iMEAN "THIS COMMON IS PART OF THE APPL.
iAND SHOULD BE REMOVED FROM THE SYSTEM (IF
iPOSSIBLE) WHEN THE APPLICATION EXITS")
p2.CPC=20000
iCPCR INITIATED CHECKPOINT PENDING
P2.SEC=4000
iTHIS IS RO SECTION OF MU TASK WITH TCB IN SEC. POOL
P2.PAR=2000
iTHE FIXER TASK HAS HANDLED A PARITY ERROR
P2.POL=1000
iSECONDARY POOL PARTITION
P2.CPU=400
iMULTIPROCESSOR CPU PARTITION
P2.PIC=200
iPOSITION INDEPENDENT LIBRARY OR COMMON (l=YES)
P2.RON=100
iREAD-ONLY COMMON (l=YES)
P2.DRV=40
iDRIVER COMMON PARTITION (l=YES)
P2.APR=7 iSTARTING APR NUMBER MASK FOR NON-PIC COMMON
P2.LMA=40000

i+
i CHECKPOINT FILE PCB
i.ASECT
000000
000002
000004
000006
000010
000012
000014

.=0
P.LNK:
P.UCB:
P.LBN:
P.SUB:

.BLKW
.BLKW
.BLKW
.BLKW
.BLKW

1
1
1
1
1

P.MAIN:
P.REL:

.BLKW
.BLKW

1
1

iLINK WORD OF CHECKPOINT FILE PCBs
iUCB ADDRESS OF CHECKPOINT FILE DEVICE
iHIGH PART OF STARTING LBN
iLOW PART OF STARTING LBN
iPOINTER TO FIRST CHECKPOINT
iALLOCATION PCB
iMUST BE 0 (FOR $RLPR1)
iCONTAINS 0 IF FILE IN USE, 1 IF NOT
iIN USE
A-49

PCBDF$
000016

P.SIZE:

000020

P.DLGH=.

.BLKW

iSIZE OF CHECKPOINT FILE IN 256W
iBLOCKS
iLENGTH OF ALL DISK PCBs

i+
i CHECKPOINT ALLOCATION PCB

,. -

.=0
000000
000010

P.SUB:

.BLKW
.BLKW

4
1

000012
000014

P.MAIN:
P.REL:

.BLKW
.BLKW

1
1

000016

P.SIZE:

.BLKW

j (UNUSED)
iLINK TO NEXT CHECKPOINT ALLOCATION
iPCB
iADDRESS OF CHECKPOINT FILE PCB
iRELATIVE POSITION IN FILE IN 256W
jBLOCKS
iSIZE ALLOCATED IN 256W BLOCKS

i+
i COMMON TASK IMAGE FILE PCB

,. -

000000
000002
000004
000006
000010
000012
000014
000016

.=0
P.FID1:
P.UCB:
P.LBN:
P.FID2:
P.MAIN:
P.REL:
P.FID3:

.BLKW
.BLKW

1
1

.BLKW
.BLKW
.BLKW
.BLKW
.BLKW
.BLKW

1
1
1
1
1
1

iFILE ID WORD FOR SAVE

iUCB ADDRESS OF DEVICE ON WHICH
iCOMMON RESIDES
jHIGH PART OF STARTING LBN
iLOW PART OF STARTING LBN
iFILE ID WORD FOR SAVE
iPOINTER TO SELF
jALWAYS CONTAINS A 0
iFILE ID WORD FOR SAVE

i+
i ATTACHMENT DESCRIPTOR OFFSETS
i-

000000
000002
000003
000004
000006
000010
000011

.ASECT
.=0
A.PCBL: .BLKW
A.PRI:
.BLKB
A. IOC:
.BLKB
A.TCB:
.BLKW
A.TCBL: .BLKW
A.STAT: .BLKB
A.MPCT: .BLKB

000012
000014

A.PCB:
.BLKW
A.LGTH=

1
1
1
1
1
1
1
1

iPCB ATTACHMENT QUEUE THREAD WORD
iPRIORITY OF ATTACHED TASK
iI/O COUNT THROUGH THIS DESCRIPTOR
;TCB ADDRESS OF ATTACHED TASK
;TCB ATTACHMENT QUEUE THREAD WORD
;STATUS BYTE
iMAPPING COUNT OF TASK THRU THIS
iDESCRIPTOR
iPCB ADDRESS OF ATTACHED TASK
iLENGTH OF ATTACHMENT DESCRIPTOR

;+
; ATTACHMENT DESCRIPTOR STATUS BYTE BIT DEFINITIONS
i-

A-50

PCBDF$
.PSECT
AS.PRO=100
AS.SBP=20
AS.RBP=40
AS.DEL=10
AS.EXT=4
AS.WRT=2
AS.RED=l

iA.TCB IS SEC POOL PROTO TCB BIAS (l=YES)
iCACHE BYPASS REQUESTED
iREQUEST TO NOT BYPASS CACHE
iTASK HAS DELETE ACCESS (l=YES)
iTASK HAS EXTEND ACCESS (l=YES)
iTASK HAS WRITE ACCESS (l=YES)
iTASK HAS READ ACCESS (l=YES)

A-51

PKTDF$

A.19

PKTDF$

SOME POSITIONAL DEPENDENCIES BETWEEN THE OCB AND THE AST CONTROL
BLOCK ARE RELIED UPON IN THE ROUTINE $FINXT IN THE MODULE SYSXT.
i-

177774
177776
000000
000002

.ASECT
.=177774
A.KSR5: .BLKW
A.DQSR: .BLKW
.BLKW
A.CBL:
.BLKW

1
1
1
1

000004

A.BYT:

.BLKW

000006
000010
000012

A.AST:
.BLKW
A.NPR:
.BLKW
A.PRM:
.BLKW
AS.FPA=l
AS.RCA=2
AS.RRA=3
AS.PEA=4
AS.REA=5
AS.PFA=6
AS.CM=7
AS.TEA=10

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
iSUBROUTINE POINTED TO BY A.DQSR
iMAPPED VIA APR 5 VALUE A.KSR5.
THIS
iIS CURRENTLY USED ONLY BY THE FULL
iDUPLEX TERMINAL DRIVER FOR UNSOLICITED
iCHARACTER ASTS. IF THE LOW BYTE OF
iA.CBL = 0, AND THE HIGH BYTE IS NOT
i= 0, THE AST CONTROL BLOCK IS A
iSPECIFIED 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 = 0 AND LOW BYTE IS
iNEGATIVE, THEN THE BLOCK IS A KERNEL
iAST BIT 6 IS SET IF $SGFIN SHOULD
iNOT BE CALLED PRIOR TO DISPATCHING
iTHE AST, AND THE LOW SIX BITS (5-0)
iREPRESENT THE INDEX/2 INTO THE
iKERNEL AST DISPATCH TABLE ($KATBL)
iNUMBER OF BYTES TO ALLOCATE ON TASK
iSTACK
iAST TRAP ADDRESS
;NUMBER OF AST PARAMETERS
iFIRST AST PARAMETER
iCODE FOR FLOATING POINT AST
iCODE FOR RECEIVE DATA AST
;CODE FOR RECEIVE BY REFERENCE AST
;CODE FOR PARITY ERROR AST
iCODE FOR REQUESTED EXIT AST
iCODE FOR POWER FAIL AST
;CODE FOR CLI COMMAND ARRIVAL AST
iCODE FOR TAST EXIT AST

; ABORTER SUBCODES FOR ABORT AST (AS.REA) TO BE RETURNED ON
A-52

PKTDF$
i USER'S STACK

AB.NPV=l
AB.TYP=2
A.PLGH=70
A.DUCB=10
A.DLGH=10.

iABORTER IS NONPRIVILEGED (l=YES)
iABORT FROM DIRECTIVE (O=YES)
iABORT 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

i KERNEL AST CONTROL CODES (A.CBL)

AK.BUF=200
AK.OCB=201
AK.GBI=202
AK.TBT=203
AK.DIO=204
AK.GGF=205

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

i+
i

I/O PACKET OFFSET DEFINITIONS

.ASECT
000000
000002
000003
000004
000006
000010
000012
000014
000016
000020
000022
000024
000026
000042
000044

000050

.=0
I.LNK:
I . PRI :
I . EFN:
I . T CB :
I . LN2 :
I . UCB :
I. FCN:

.BLKW
. BLKB
. BLKB
. BLKW
. BLKW
. BLKW
.BLKW
I • lOS B : • B L KW
.BLKW
.BLKW
I .AST:
. BLKW
I • P RM :
. B L KW
.BLKW
.BLKW
I.ATTL=.
I.AADA: .BLKW
I.LGTH=.
I.ATRL=6*8.

1
1
1

1
1
1
1
1
1

1
1
1

6
1

i+
i ANCILLARY CONTROL" BLOCK (ACB)
;-

iI/O QUEUE THREAD WORD
iREQUEST PRIORITY
iEVENT FLAG NUMBER
iTCB ADDRESS OF REQUESTOR
iPOINTER TO SECOND LUN WORD
iPOINTER TO UNIT CONTROL BLOCK
iI/O FUNCTION CODE
iVIRTUAL ADDRESS OF I/O STATUS BLOCK
iI/O STATUS BLOCK RELOCATON BIAS
iI/O STATUS BLOCK ADDRESS
iAST SERVICE ROUTINE ADDRESS
iRESERVED FOR MAPPING PARAMETER #1
iPARAMETERS 1 TO 6
iUSER MODE DIAGNOSTIC PARAMETER WORD
iMINIMUM LENGTH OF I/O PACKET (USED BY
iFILE SYSTEM TO CALCULATE MAXIMUM
iNUMBER OF ATTRIBUTES)
iSTORAGE FOR ATT DESCR PTRS WITH I/O
iLENGTH OF I/O REQUEST CONTROL BLOCK
iLENGTH OF FILE SYSTEM ATTRIBUTE BLOCK
DEFINITIONS

A-53

PKTDF$
.=0
A.REL:
A. DIS:
A.MAS:
A.NUM:

.BLKW
. BLKW
.BLKW
.BLKB
.BLKB
.BLKW
.BLKB
. BLKB

000000
000002
000004
000006
000007
000010
000012
000013
000014

A.LIN:
A.ACC:
A. STA:
A.LEN1=.

000010
000012
000014
000016

.=A.LIN
A. IMAP:
A. I BUF :
A.ILEN:
A.SMAP:

000020
000022
000024
000030
000034

A.SBUF: .BLKW
A.SLEN: .BLKW
A.IOS:
.BLKW
A.RES:
.BLKW
A.LEN2=.

. BLKW
. BLKW
.BLKW
.BLKW

1
1

1
1
1

2
2

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
iACD INTERRUPT BUFFER RELOCATION BIAS
iACD INTERRUPT BUFFER ADDRESS
iACD INTERRUPT BUFFER LENGTH
iACD SYSTEM STATE BUFFER RELOCATION
iBIAS
iACD SYSTEM STATE BUFFER ADDRESS
iACD SYSTEM STATE BUFFER LENGTH
iACD I/O STATUS
iRESERVED FOR USE BY THE ACD
iLENGTH OF FULL ACB
DEFINE THE FLAG VALUES IN THE OFFSET
U.AFLG

UA.ACC=l
UA.PRO=2
UA.ECH=4
UA.TYP=10
UA.SPE=20
UA.PUT=40
UA.CAL=100
UA.COM=200

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 INPUT BUFFER
iCALL THE ACD BACK AFTER THE TRANSFER
iCOMPLETE THE INPUT REQUEST

UA.ALL=400
UA.TRA=1000

iALLOW PROCESSING OF THIS I/O REQUEST
iTRANSFER CHARS. WHEN I/O COMPLETES

000000
000002
000004
000006
000010
000012
000014
000016
000020
000022

DEFINE THE ACD ENTRY POINTS (OFFSETS INTO THE DISPATCH TABLE)

.=0
A.ACCE: .BLKW
A.DEQU: .BLKW
A.POWE: .BLKW
A.INPU: .BLKW
A.OUTP: .BLKW
A.CONN: .BLKW
A.DISC: .BLKW
A.RECE: .BLKW
A. PROC: . BLKW
A.CALL: .BLKW

1
1
1
1
1
1

1
1
1
1

iI/O REQUEST ACCEPTANCE ENTRY POINT
iI/O REQUEST DEQUEUE ENTRY POINT
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
A-54

PKTDF$
jPOINT
DEFINE THE STATUS BITS IN A.STA OF THE PROTOTYPE ACB
000001
000002

jACD IS MARKED FOR DELETE
jACD IS DISABLED

AS.DEL=l
AS.DIS=2

j+
j

SECONDARY POOL COMMAND BUFFER BLOCKS

000000
000002
000004
000006

.=0
C.CLK:
C.CTCB:
C.CUCB:
C . CCT :

.BLKW
.BLKW
.BLKW
. BLKW

1
1
1
1

000010
000012
000012

C . CST S : . BLKW
C.CMCD:
C.CSO:
.BLKW

000014
000015

C. CTR:
C.CBLK:

000016

C.CTXT:

. BLKB
.BLKB

1
1

iLINK WORD
iTCB ADDRESS OF TASK TO RECEIVE COMMAND
iUCB ADDRESS OF RESPONSIBLE TERMINAL
jCHARACTER COUNT, EXCLUDING TRAILING
iCR
iSTATUS MASK
jSYSTEM MESSAGE CODE
jSTARTING OFFSET OF VALID COMMAND
jTEXT
iTERMINATOR CHARACTER
jSIZE OF PACKET IN SEC POOL (32 WD.)
jBLOCKS
iCOMMAND TEXT, FOLLOWED BY CR

i+
j BIT DEFINITIONS FOR THE GIN$ (AKA WIMPS) INFORMATION
; DIRECTIVE.

SF.PRV=100000
SF.IN= 40000

jFUNCTION IS PRIVILEGED
iFUNCTION IS AN INPUT FUNCTION

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

000000
000002
000004
000006
000010
000012
000014

.=0
O.LNK:
O.MCRL:
O.PTCB:
O.AST:
O.EFN:
O.ESB:
O.STAT:

000034

O.LGTH=.

.BLKW
.BLKW
.BLKW
.BLKW
.BLKW
.BLKW
.BLKW

1
1
1
1
1
1
8.

iOCB LINK WORD

iADDRESS OF MCR COMMAND LINE
iPARENT TCB ADDRESS
;EXIT AST ADDRESS
;EXIT EVENT FLAG
i EXIT STATUS BLOCK VIRTUAL ADDRESS
;EXIT STATUS BUFFER
;LENGTH OF OCB

A-55

PKTDF$
i++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
i THE FOLLOWING CPB,C.PSTS,AND C.CMCD ARE NOT CURRENTLY USED BY P/OS.
i THEY ARE, HOWEVER, RESERVED FOR A POSSIBLE FUTURE USE.

;-----------------------------------------------------------------------CLI PARSER BLOCK (CPB) DEFINITIONS
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
1

iADDRESS OF CLI'S TCB
iCLI NAME
iSTATUS MASK
iLENGTH OF DEFAULT PROMPT
iLENGTH 0 CNTRL/C PROMPT
iSTART OF PROMPT STRINGS. DEFAULT
iIS CONCATENATED WITH CONTROL C PROMPT

STATUS BIT DEFINITIONS
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
CP.CTC=2000

iPASS EMPTY COMMANDS TO CLI
iCLI DESIRES SYSTEM MESSAGES
iCLI WANTS COMMANDS FROM LOGGED OFF
iTTYS
iCLI IS DISABLED
iUSER MUST BE PRIV TO SET TTY TO THIS
iCLI
iDON'T HANDLE CONTINUATIONS (M-PLUS
iONLY)
iMCR ••• , HEL, BYE DO NO I/O TO TTY
iHEL, BYE DO NOT SET CLI ETC.
iABILITY TO SET TO THIS CLI IS
;RESTRICTED
iTO THE CLI ITSELF
;PASS TASK EXIT PROMPT REQUESTS TO CLI
iCLI TCB IS IN SECONDARY POOL
;AC NOTIFICATION PACKETS ARE WANTED

STATUS BITS FOR COMMAND BLOCKS
CC.MCR=l
CC.PRM=2
CC.EXT=4
CC.KIL=10
CC.CLI=20
CC.MSG=40
CC.TTD=100
CC.CTC=200

iFORCE COMMAND TO MCR
iISSUE DEFAULT PROMPT
;TASK EXIT PROMPT REQUEST
iDELETE ALL CONTINUATION PIECES FROM
iTHIS TTY
iCOMMAND TO BE RETREIVED BY GCCI$ ONLY
iPACKET CONTAINS SYSTEM MESSAGE TO CLI
;COMMAND CAME FROM TTDRV
iAC NOTIFICATION PACKET

A-56

PKTDF$

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

;CLI INITIALIZED ENABLED
;CLI' INITIALIZED DISABLED
;CLI ENABLED
;CLI DISABLED
;CLI BEING ELIMINATED
;CLI MUST EXIT IMMEDIATELY
;NEW TERMINAL LINKED TO CLI
;TERMINAL REMOVED FROM CLI
;GENERAL MESSAGE TO CLI

;+
; GROUP GLOBAL EVENT FLAG BLOCK OFFSETS
; (CURRENTLY NOT USED BY P/OS)
;

.=0
.BLKW
.BLKB
.BLKB
.BLKW
.BLKW

1
1
1
1
2

;LINK WORD
;GROUP NUMBER
iSTATUS BYTE
;ACCESS COUNT
; EVENT FLAGS

000000
000002
000003
000004
000006

G.LNK:
G.GRP:
G.STAT:
G.CNT:
G.EFLG:

000012

G.LGTH=.

;LENGTH OF GROUP GLOBAL EVENT FLAG
iBLOCK

GS.DEL=l

; STATUS BIT -- MARKED FOR DELETE

;+
; EXECUTIVE POOL MONITOR CONTROL FLAGS (HISTORICAL INTEREST
; ONLY)

$POLST IS THE SYNCHRONIZATION WORD BETWEEN THE EXEC AND POOL
MONITOR
PC.HIH=l
PC.LOW=2
PC.ALF=4
PC.XIT=200
PC.NRM=PC.HIH*400
PC.ALM=PC.LOW*400

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)
jPOOL TASK INHIBIT BIT FOR HIGH POOL
jPOOL TASK INHIBIT BIT FOR LOW POOL
i$POLFL IS THE POOL USAGE CONTROL WORD

A-57

PKTDF$

PF.INS=40
PF.LOG=100
PF.REQ=200

iREJECT NONPRIVILEGED INS/RUN/REM
iNONPRIVILEGED LOGINS ARE DISABLED
iSTALL REQUEST OF NONPRIV. TASKS

PF.ALL=177777

iTAKE ALL POSSIBLE ACTIONS TO SAVE POOL

.PSECT

A-58

QIOSY$
A.20

QIOSV$

SYSTEM STANDARD CODES, USED BY EXECUTIVE AND DRIVERS
DECIMAL

OCTAL

IE.BAD
IE.IFC
IE.DNR
IE.VER
IE.ONP
IE.SPC
IE. DNA
IE.DM
IE.DUN
IE.EOF
IE.EOV
IE.WLK
IE.DAO
IE.SRE
IE.ABO
IE.PRI
IE.RSU
IE.OVR
IE.BYT
IE.BLK
IE.MOD
IE.CON
IE.BBE
IE.STK
IE.FHE
IE.EOT
IE.OFL
IE.BCC
IE.NFW
IE.DIS

-01.
-02.
-03.
-04.
-05.
-06.
-07.
-08.
-09.
-10.
-11.
-12.
-13.
-14.
-15.
-16.
-17.
-18.
-19.
-20.
-21.
-22.
-56.
-58.
-59.
-62.
-65.
-66.
-69.
-69.

177777
177776
177775
177774
177773
177772
177771
177770
177767
177766
177765
177764
177763
177762
177761
177760
177757
177756
177755
177754
177753
177752
177710
177706
177705
177702
177677
177676
177673
177673

IE~~NDR

-72.
-95.
-96.
-99.
-100.

177670
177641
177640
177635
177634

IE··~"TMO

IE.CNR
IE.MII
IE.SPI

Bad parameters
Invalid function code
Device not ready
Parity error on device
Hardware option not present
Illegal user buffer
Device not attached
Device already attached
Device not attachable
End of file detected
End of volume detected
Write attempted to locked unit
Data overrun
Send/receive failure
Request terminated
Privilege violation
Sharable resource in use
Illegal overlay request
Odd byte count (or virtual address)
Logical· block number too large
Invalid UDC module #
UDC connect error
Bad block on device
Not enough stack space (FCS or FCP)
Fatal hardware error on device
End of tape detected
Device off line
Block check, CRC, or framing error
Path lost to partner ;THIS CODE MUST BE ODD
Path lost to partner ;DISCONNECTED (SAME
AS NFW)
No dynamic space available ; SEE ALSO IE.UPN
Timeout on request
; see also IS.TMO
Connection rejected
Media inserted incorrectly
Spindown ignored

FILE PRIMITIVE CODES
IE.NOD

-23.

177751

Caller's nodes exhausted
A-59

QIOSY$
IE.OFU
IE.IFU
IE.NSF
IE.LCK
IE.HFU
IE.WAC
IE.CKS
IE.WAT
IE.RER
IE.WER
IE.ALN
IE.SNC
IE.SQC
IE.NLN
IE.CLO
IE.OUP
IE.BVR
IE.BHD
IE.EXP
IE.BTF
IE.ALC
IE.ULK
IE.WCK
IE.OSQ

-24.
-25.
-26.
-27.
-28.
-29.
-30.
-31.
-32.
-33.
-34.
-35.
-36.
-37.
-38.
-57.
-63.
-64.
-75.
-76.
-84.
-85.
-86.
-90.

177750
177747
177746
177745
177744
177743
177742
177741
177740
177737
177736
177735
177734
177733
177732
177707
177701
177700
177665
177664
177654
177653
177652
177646

Oevice full
Index file full
N6 such file
Locked from read/write access
File header full
Accessed for write
File header checksum failure
Attribute control list format error
File processor device read error
File processor device write error
File already accessed on LUN
File 10, file number check
File 10, sequence number check
No file accessed on LUN
File was not properly closed
ENTER - duplicate entry in directory
Bad version number
Bad file header
File expiration date not reached
Bad tape format
Allocation failure
Unlock error
Write check failure
Disk quota exceeded

FILE CONTROL SERVICES CODES
IE.NBF
IE.RBG
IE.NBK
IE. ILL
IE.BTP
IE.RAC
IE.RAT
IE.RCN
IE.2DV
IE.FEX
IE.BDR
IE.RNM
IE.BDI
IE. FOP
IE.BNM
IE.BDV
IE.NFI
IE.ISQ
IE.NNC

-39.
-40.
-41.
-42.
-43.
-44.
-45.
-46.
-48.
-49.
-50.
-51.
-52.
-53.
-54.
:"'55.
-60.
-61.
-77.

177731
177730
177727
177726
177725
177724
177723
177722
177720
177717
177716
177715
177714
177713
177712
177711
177704
177703
177663

OPEN - no buffer space available for file
Illegal record size
File exceeds space allocated, no blocks
Illegal operation on file descriptor block
Bad record type
Illegal record access bits set
Illegal record attributes bits set
Illegal record number - too large
Rename - 2 different devices
Rename - new file name already in use
Bad directory file
Can't rename old file system
Bad directory syntax
File already open
Bad file name
Bad device name
File ID was not specified
Illegal sequential operation
Not ANSI 'D' format byte count

NETWORK ACP, PSI, AND DECDATAWAY CODES
A-60

QIOSY$

IE.NNN
IE.BLB
IE.URJ
IE.NRJ
IE.NDA
IE. IQU
IE.RES
IE.TML
IE.NNT
IE.UKN

-68.
-70.
-73.
-74.
-78.
-91.
-92.
-93.
-94.
-97.

177674
177672
177667
177666
177662
177645
177644
177643
177642
177637

No such node
Bad logical buffer
Connection rejected by user
Connection rejected by network
No data available
Inconsistent qualifier usage
Circuit reset during operation
Too many links to task
Not a network task
Unknown name

ICS/ICR ERROR CODES
IE.NLK
IE.NST
IE.FLN

-79.
-80.
-81.

177661
177660
177657

Task not linked to specified ICS/ICR interrupts
Specified task not installed
Device offline when offline request was issued

177656
177655

Invalid escape sequence
Partial escape sequence

TTY ERROR CODES
IE.IES
IE. PES

-82.
-83.

RECONFIGURATION CODES
IE. ICE
IE.ONL
IE.SZE

-47.
-67.
-98.

177721
177675
177636

Internal consistancy error
Device online
Unable to size device

177651
177650
177647

Task not triggered
Transfer rejected by recelvlng CPU
Event flag already specified

PCL ERROR CODES
IE.NTR
IE.REJ
IE.FLG

-87.
-88.
-89.

SUCCESSFUL RETURN CODES--IS.PND

+00.

OPERATION PENDING

A-61

QIOSY$
IS.SUC
IS.RDD

+01.
+02.

1
2

IS.TNC

+02.

IS.CHW

+04.

IS.BV

+05.

IS.DAO

+02.

OPERATION COMPLETE, SUCCESS
FLOPPY DISK SUCCESSFUL COMPLETION
OF A READ PHYSICAL, AND DELETED
DATA MARK WAS SEEN IN SECTOR HEADER
(PCL) SUCCESSFUL TRANSFER BUT MESSAGE
TRUNCATED (RECEIVE BUFFER TOO SMALL).
( IBM COMM) DATA READ WAS RESULT OF
IBM HOST CHAINED WRITE OPERATION
(A/D READ) AT LEAST ONE BAD VALUE
WAS READ (REMAINDER MAY BE GOOD).
BAD CHANNEL IS INDICATED BY A
NEGATIVE VALUE IN THE BUFFER.
SUCCESSFUL BUT WITH DATA OVERRUN
(NOT TO BE CONFUSED WITH IE.DAO)

TTY SUCCESS CODES
IS.CR
IS.ESC
IS.CC
IS.ESQ
IS.PES
IS.EOT
IS.TAB
IS.TMO

<015*400+1>
<33*400+1>
<3*400+1>
<0233*400+1>
<200*400+1>
<4*400+1>
<11*400+1>
+2.
2

CARRIAGE RETURN WAS TERMINATOR
ESCAPE (ALTMODE) WAS TERMINATOR
CTRL/C WAS TERMINATOR
ESCAPE SEQUENCE WAS TERMINATOR
PARTIAL ESCAPE SEQUENCE TERMINATOR
EOT WAS TERMINATOR (BLOCK MODE INPUT)
TAB WAS TERMINATOR (FORMS MODE INPUT)
REQUEST TIMED OUT

Professional Bisync Success Codes
IS.RVI
IS.CNV
IS.XPT

+2.
+3.
+5.

2
3
5

DATA SUCC. XMITTEDi HOST ACKED WIRVI
DATA SUCC. XMITTEDi HOST ACKED WICONVERSATION
DATA SUCC. RECVD IN TRANSPARENT MODE

Professional Bisync Abort Codes
These codes are returned in the high byte of the first word of the
IOSB when the low byte contains IE.ABO.
SB.KIL
SB.ACK
SB.NAK
SB.ENQ
SB.BOF
SB.TMO
SB.DIS

-1.
-2.
- 3.
-4.
-5.
-6.
-7.

377
376
375
374
373
372
371

ABORTED
ABORTED
ABORTED
ABORTED
ABORTED
ABORTED
ABORTED

BY IO.KIL
BECAUSE TOO MANY ACKS RECD OUT OF SEQ
BECAUSE NAK THRESHOLD EXCEEDED
BECAUSE ENQ THRESHOLD EXCEEDED
BECAUSE OF IO.RLB BUFFER OVERFLOW
BECAUSE OF TIMEOUT
BECAUSE HOST DISCONNECTED WI DLE, EOT

STANDARD ERROR CODES RETURNED BY DIRECTIVES IN THE DIRECTIVE

A-62

QIOSY$
; STATUS WORD
IE.UPN

-01.

177777

IE. INS
IE.PTS
IE.UNS
IE.ULN
IE.HWR
IE.ACT
IE. ITS
IE.FIX
IE.CKP
IE.TCH
IE.RBS
IE.PRI
IE.RSU
IE.NSW
IE.ILV
IE.ITN
IE.LNF

-02.
-03.
-04.
-05.
-06.
-07.
-08.
-09.
-10.
-11.
-15.
-16.
-17.
-18.
-19.
-20.
-21.

177776
177775
177774
177773
177772
177771
177770
177767
177766
177765
177761
177760
177757
177756
177755
177754
177753

Insufficient dynamic storage
SEE ALSO
IE.NOR
Specified task not installed
Partition too small for task
Insufficient dynamic storage for send
Un-assigned LUN
Device handler not resident
Task not active
Directive inconsistent with task state
Task already fixed/unfixed
Issuing task not checkpointable
Task is checkpointable
Receive buffer is too small
Privilege violation
Resource in use
No swap space available
Illegal vector specified
Invalid table number
Logical name not found

IE.AST
IE.MAP
IE. lOP
IE.ALG
IE.WOV
IE.NVR
IE.NVW
IE.ITP
IE.IBS
IE.LNL
IE. lUI
IE. IDU
IE.ITI
IE.PNS
IE. IPR
IE.ILU
IE.IEF
IE.ADP
IE.SDP

-80.
-81.
-83.

177660
177657
177655
177654
177653
177652
177651
177650
177647
177646
177645
177644
177643
177642
177641
177640
177637
177636
177635

Directive issued/not issued from AST
Illegal mapping specified
Window has I/O in progress
Alignment error
Address window allocation overflow
Invalid region 10
Invalid address window ID
Invalid TI parameter
Invalid send buffer size ( .GT. 255.)
LUN locked in use
Invalid UIC
Invalid device or unit
Invalid time parameters
partition/region not in system
Invalid priority ( .GT. 250.)
Invalid LUN
Invalid event flag ( .GT. 64.)
Part of DPB out of user's space
DIC or DPB size invalid

-84.
-85.
-86.
-87.
-88.
-89.
-90.
-91.
-92.
-93.
-94.
-95.
-96.
-97.
-98.
-99.

; SUCCESS CODES FROM DIRECTIVES - PLACED IN THE DIRECTIVE STATUS WORD
IS.CLR

IS.SET

IS.SPD

EVENT FLAG WAS CLEAR
FROM CLEAR EVENT FLAG DIRECTIVE
EVENT FLAG WAS SET
FROM SET EVENT FLAG DIRECTIVE
TASK WAS SUSPENDED
A-63

QIOSY$
IS.SUP

LOGICAL NAME SUPERSEDED

;

THE FOLLOWING LIST IS PROVIDED FOR COMPLETENESS AND INFORMATIVE OR
; SUGGESTIVE PURPOSES. NOT ALL OF THE I/O FUNCTION CODES AND DEVICES
; ARE SUPPORTED ON P/OS.
;

; COLUMN HEADINGS:
;
;
;
;
;

WORD
CODE
EQUIVALENT (HIGH
BYTE)

SUBCODE
(LOW
BYTE)

GENERAL I/O QUALIFIER BYTE DEFINITIONS
IQ.X
IQ.Q
IQ.S
IQ.UMD
IQ.LCK

000001
000002
000004
000004
000200

000
000
000
000
000

001
002
004
004
200

NO ERROR RECOVERY
QUEUE REQUEST IN EXPRESS QUEUE
SYNONYM FOR IQ.UMD
USER MODE DIAGNOSTIC STATUS REQUIRED
MODIFY IMPLIED LOCK FUNCTION

012
022
042
050
060
030

KILL CURRENT REQUEST
I/O RUNDOWN
UNLOAD I/O HANDLER TASK
LOAD A TASK IMAGE FILE
RECORD A TASK IMAGE FILE
SET CHARACTERISTICS FUNCTION

EXPRESS QUEUE COMMANDS
IO.KIL
IO.RDN
IO.UNL
IO.LTK
IO.RTK
IO.SET

000012
000022
000042
000050
000060
000030

000
000
000
000
000
000

; GENERAL DEVICE HANDLER CODES
IO.WLB
IO.RLB
IO.LOV
IO.LDO
IO.ATT
IO.DET

000400
001000
001010
001110
001400
002000

001
002
002
002
003
004

000
000
010
110
000
000

WRITE LOGICAL BLOCK
READ LOGICAL BLOCK
LOAD OVERLAY (DISK DRIVER)
LOAD D-SPACE OVERLAY (DISK)
ATTACH A DEVICE TO A TASK
DETACH A DEVICE FROM A TASK

; DIRECTORY PRIMITIVE CODES
IO.FNA
IO.RNA
IO.ENA

004400
005400
006000

011
013
014

000
000
000

FIND FILE NAME IN DIRECTORY
REMOVE FILE NAME FROM DIRECTORY
ENTER FILE NAME IN DIRECTORY

000

CLOSE OUT LUN

; FILE PRIMITIVE COPES
IO.CLN

003400

007

A-64

QIOSY$
IO.ULK
IO.ACR
IO.ACW
IO.ACE
IO.DAC
IO.RVB
IO.WVB
IO.EXT
IO.CRE
IO.DEL
IO.RAT
IO.WAT
IO.APV
IO.APC

005000
006400
007000
007400
010000
010400
011000
011400
012000
012400
013000
013400
014010
014000

012
015
016
017
020
021
022
023
024
025
026
027
030
030

000
000
000
000
000
000
000
000
000
000
000
000
010
000

UNLOCK BLOCK
ACCESS FOR READ
ACCESS FOR WRITE
ACCESS FOR EXTEND
DE-ACCESS FILE
READ VIRTUAL BLOCK
WRITE VIRTUAL BLOCK
EXTEND FILE
CREATE FILE
DELETE FILE
READ FILE ATTRIBUTES
WRITE FILE ATTRIBUTES
PRIVILEGED ACP CONTROL
ACP CONTROL

; IIO FUNCTION CODES FOR SPECIFIC DEVICE DEPENDENT FUNCTIONS
IO.WLV
IO.WLS
IO.WNS
IO.WAL
IO.WMS
IO.CCO
IO.WBT
IO.WLT
IO.WLC
IO.WPB
IO.WDD

000500
000410
0.00420
000410
000420
000440
000500
000410
000420
000440
000540

001
001
001
001
001
001
001
001
001
001
001

100
010
020
010
020
040
100
010
020
040
140

IO.RSN
IO.RLV
IO.RST
IO.RAL
IO.RNE
IO.RNC
IO.RTM
IO.RDB
IO.SCF
IO.RHD
IO.RNS
IO.CR'C
IO.RPB
IO.RLC

001140
001100
001001
001010
001020
001040
001200
001200
001200
001010
001020
001040
001040
001020

002
002
002
002
002
002
002
002
002
002
002
002
002
002

140
100
001
010
020
040
200
200
200
010
020
040
040
020

IO.ATA
IO.GTS

001410
002400

003
005

010
000

IO.R1C
IO.INL
IO.TRM
IO.RWD

002400
002400
002410
002400

005
005
005
005

000
000
010
000

(DECTAPE) WRITE LOGICAL REVERSE
(COMM.) WRITE PRECEDED BY SYNC TRAIN
(COMM.) WRITE, NO SYNC TRAIN
(TTY) WRITE PASSING ALL CHARACTERS
(TTY) WRITE SUPPRESSIBLE MESSAGE
(TTY) WRITE WITH CANCEL CTRLIO
(TTY) WRITE WITH BREAKTHROUGH
(DISK) WRITE LAST TRACK
(DISK) WRITE LOGICAL WI WRITECHECK
(DISK) WRITE PHYSICAL BLOCK
(FLOPPY DISK) WRITE PHYSICAL WI
DELETED DATA
(MSCP DISK) READ VOLUME SERIAL NUMBER
(MAGTAPE,DECTAPE) READ REVERSE
(TTY) READ WITH SPECIAL TERMINATOR
(TTY) READ PASSING ALL CHARACTERS
(TTY) READ WITHOUT ECHO
(TTY) READ - NO LOWER CASE CONVERT
(TTY) READ WITH TIME OUT
(CARD READER) READ BINARY MODE
(DISK) SHADOW COpy FUNCTION
( COMM.) READ, STRIP SYNC
( COMM.) READ, DON'T STRIP SYNC
( COMM.) READ, DON'T CLEAR CRC
(DISK) READ PHYSICAL BLOCK
(DISK,MAGTAPE) READ LOGICAL
WI READCHEC;**-l
(TTY) ATTACH WITH AST'S
(TTY) GET TERMINAL SUPPORT
CHARACTERISTICS
(AFC,AD01,UDC) READ SINGLE CHANNEL
(COMM. ) INITIALIZATION FUNCTION
(COMM.) TERMINATION FUNCTION
(MAGTAPE,DECTAPE) REWIND
A-65

QIOSY$
IO.SPB
IO.RPL

002420
002420

005
005

020
020

IO.SPF
IO.STC
IO.SMD
IO.SEC
IO.RWU
IO.SMO
IO.HNG
IO.HLD
IO.BRK
IO.RBC

002440
002500
002510
002520
002540
002560
003000
003100
003200
003000

005
005
005
005
005
005
006
006
006
006

040
100
110
120
140
160
000
100
200
000

IO.MOD
IO.HDX
IO.FDX
IO.SYN
IO.EOF
IO.ERS
IO.DSE
IO.RDF
IO.RTC
IO.SAO
IO.SSO
IO.RPR
IO.MSO
IO.RTT
IO.SLO
IO.MLO
IO.LED
IO.SDO
IO.SDI
IO.SCS
IO.REL
IO.MCS
IO.ADS
IO.CCI
IO.LOD
IO.MDI
IO.DCI
IO.PAD
HT.RPP
IO.XMT

003000
003010
003020
003040
003000
003020
003040
003110
003400
004000
004400
004400
005000
005001
005400
006000
012000
012400
013000
013000
013400
013400
014000
014000
014000
014400
014400
014400
000010
014400

006
006
006
006
006
006
006
006
007
010
011
011
012
012
013
014
024
025
026
026
027
027
030
030
030
031
031
031
000
031

000
010
020
040
000
020
040
110
000
000
000
000
000
001
000
000
000
000
000
000
000
000
000
000
000
000
000
000
010
000

IO.XNA
IO.INI
IO.HIS
IO.RCI
IO.RCV

014410
014400
015000
015000
015000

031
031
032
032
032

010
000
000
000
000

(MAGTAPE) SPACE "N" BLOCKS
(DISK) REPLACE LOGICAL BLOCK
(RESECTOR)
(MAGTAPE) SPACE !'N" EOF MARKS
SET CHARACTERISTIC
(FLOPPY DISK) SET MEDIA DENSITY
SENSE CHARACTERISTIC
(MAGTAPE,DECTAPE) REWIND AND UNLOAD
(MAGTAPE) MOUNT & SET CHARACTERISTICS
(TTY) HANGUP DIAL-UP LINE
(TMS) HANGUP BUT LEAVE LINE ON HOLD
(PRO/TTY) SEND SHORT OR LONG BREAK
READ MULTICHANNELS (BUFFER DEFINES
CHANNELS)
(COMM.) SETMODE FUNCTION FAMILY
(COMM.) SET UNIT HALF DUPLEX
(COMM.) SET UNIT FULL DUPLEX
(COMM.) SPECIFY SYNC CHARACTER
(MAGTAPE) WRITE EOF
(MAGTAPE) ERASE TAPE
(MAGTAPE) DATA SECURITY ERASE
(DISK) READ DISKETTE FORMAT
READ CHANNEL - TIME BASED
(UDC) SINGLE CHANNEL ANALOG OUTPUT
(UDC) SINGLE SHOT, SINGLE POINT
(TTY) READ WITH PROMPT
(UDC) SINGLE SHOT, MULTI-POINT
(TTY) READ WITH TERMINATOR TABLE
(UDC) LATCHING, SINGLE POINT
(UDC) LATCHING, MULTI-POINT
(LPS11) WRITE LED DISPLAY LIGHTS
(LPS11) WRITE DIGITAL OUTPUT REGISTER
(LPS11) READ DIGITAL INPUT REGISTER
(UDC) CONTACT SENSE, SINGLE POINT
(LPS11) WRITE RELAY
(UDC) CONTACT SENSE, MULTI-POINT
(LPS11) SYNCHRONOUS A/D SAMPLING
(UDC) CONTACT INT - CONNECT
(LPAll) LOAD MICROCODE
(LPSll) SYNCHRONOUS DIGITAL INPUT
(UDC) CONTACT INT - DISCONNECT
(PSI) DIRECT CONTROL OF X.29 PAD
(PSI) RESET PAD PARAMETERS SUBFUNCTION
(COMM.) TRANSMIT SPECIFIED BLOCK WITH
ACK
(COMM.) TRANSMIT WITHOUT ACK
(LPA11) INITIALIZE
(LPSll) SYNCHRONOUS HISTOGRAM SAMPLING
(UDC) CONTACT INT - READ
(COMM.) RECEIVE DATA IN BUFFER
SPECIFIED
A-66

QIOSY$
IO.CLK
IO.CSR
IO.MDO
IO.CTI
IO.CON

015000
015000
015400
015400
015400

032
032
033
033
033

000
000
000
000
000

IO.ORG

015410

033

010

IO.ANS

015420

033

020

IO.STA

015400

033

000

IO.DTI
IO.DIS

016000
016000

034
034

000
000

IO.MDA
IO.DPT

016000
016010

034
034

000
010

IO.RTI
IO.CTL
IO.STP

016400
016400
016400

035
035
035

000
000
000

IO.SWI
IO.CNT

016400
017000

035
036

000
000

IO.ITI

017000

036

000

PRO 300 SERIES BITMAP

(LPAll) START CLOCK
(BUS SWITCH) READ CSR REGISTER
(LPSll) SYNCHRONOUS DIGITAL OUTPUT
(UDC) TIMER - CONNECT
(COMM.) CONNECT FUNCTION
(VTll) - CONNECT TASK TO DISPLAY
PROCESSOR
(BUS SWITCH) CONNECT TO SPECIFIED BUS
(COMM./PRO) DIAL TELEPHONE AND ORIGINATE
(COMM.) INITIATE CONNECTION IN
ORIGINATE MODE
(COMM.) INITIATE CONNECTION IN
ANSWER MODE
(LPAll) START DATA TRANSFER
(XJDRV) - SHOW STATE
(UDC) TIMER - DISCONNECT
(COMM.) DISCONNECT FUNCTION
(VTll) - DISCONNECT TASK FROM DISPLAY
PROCESSOR
(BUS SWITCH) SWITCHED BUS DISCONNECT
(LPSll) SYNCHRONOUS D/A OUTPUT
(BUS SWITCH) DISCONNECT TO SPECIF
PORT NO.
(UDC) TIMER - READ
(COMM.) NETWORK CONTROL FUNCTION
(LPSll,LPAll) STOP IN PROGRESS
FUNCTION
(VTll) - STOP DISPLAY PROCESSOR
(BUS SWITCH) SWITCH BUSSES
(VTll) - CONTINUE DISPLAY PROCESSOR
(XJDRV) - SHOW COUNTERS
(UDC) TIMER - INITIALIZE

FU~CTIONS

NOTE: THESE FUNCTIONS ARE FOR DEC USE ONLY AND ARE SUBJECT
TO CHANGE
IO.RSD
IO.WSD

006030 014
005410 013
SO. TXT
SD.GDS

o
1

READ SPECIAL DATA
030
WRITE SPECIAL DATA
010
TEXT DATA TYPE FOR SPECIAL DATA
GIDIS DATA TYPE FOR SPECIAL DATA

PROFESSIONAL 300 BISYNC DRIVER (XJDRV) FUNCTIONS
SB.PRT
SB.CLR

001420
017010

003
036

020
010

SB.RDY

015410

033

010

ATTACH AS A PRINTER
CLEAR COUNTERS (IO.CNT
SUBFUNCTION)
SET DEVICE STATE READY (IO.STA SUBFUNC)
A-67

QIOSY$
SB.NRD

015420

033

020

SET DEVICE STATE NOT READY

IO.LBK

016400

035

000

PERFORM LOOPBACK TEST

SB.CBL
SB.CLK

016410
016420

035
035

010
020

PERFORM CABLE LOOPBACK TEST
DEVICE PERFORMS LINE CLOCKING

; COMMUNICATIONS FUNCTIONS
;

IO.CPR
IO.CAS
IO.CRJ
IO.CBO
IO.CTR
IO.GNI
IO.GLI
IO.GLC
IO.GRI
IO.GRC
IO.GRN
IO.CSM
IO.CIN
IO.SPW
IO.CPW
IO.NLB
IO.DLB

015410
015420
015440
015510
015610
016410
016420
016430
016440
016450
016460
016470
016500
016510
016520
016530
016540

033
033
033
033
033
035
035
035
035
035
035
035
035
035
035
035
035

010
020
040
110
210
010
020
030
040
050
060
070
100
110
120
130
140

CONNECT NO TIMEOUTS
CONNECT WITH AST
CONNECT REJECT
BOOT CONNECT
TRANSPARENT CONNECT
GET NODE INFORMATION
GET LINK INFORMATION
GET LINK INFO CLEAR COUNTERS
GET REMOTE NODE INFORMATION
GET REMOTE NODE ERROR COUNTS
GET REMOTE NODE NAME
CHANGE SOLO MODE
CHANGE CONNECTION INHIBIT
SPECIFY NETWORK PASSWORD
CHECK NETWORK PASSWORD.
NSP LOOPBACK
DDCMP L90PBACK

000
000
000
010
000
020
000
030
000
040
000
000
000
000

CONNECT TO TERMINAL INTERRUPTS
DISCONNECT FROM TERMINAL INTERRUPTS
LINK TO DIGITAL INTERRUPTS
UNLINK FROM DIGITAL INTERRUPTS
LINK TO COUNTER MODULE INTERRUPTS
UNLINK FROM COUNTER MODULE INTERRUPTS
LINK TO REMOTE TERMINAL INTERRUPTS
UNLINK FROM REMOTE TERMINAL INTERRUPTS
LINK TO ERROR INTERRUPTS
UNLINK FROM ERROR INTERRUPTS
UNLINK FROM ALL INTERRUPTS
UNIT ONLINE
UNIT OFFLINE
READ ACTIVATING DATA

010
010

MULTIPLE ANALOG OUTPUTS
LINK EVENT FLAGS TO INTERRUPT

ICS/ICR I/O FUNCTIONS
IO.CTY
IO.DTY
IO.LDI
IO.UDI
IO.LTI
IO.UTI
IO.LTY
IO.UTY
IO.LKE
IO.UER
IO.NLK
IO.ONL
IO.FLN
IO.RAD

003400
006400
007000
011410
007400
011420
010000
011430
012000
011440
011400
017400
012400
010400

007
015
016
023
017
023
020
023
024
023
023
037
025
021

IPll I/O FUNCTIONS
IO.MAO
IO.LEI

003410
007410

007
017

A-68

QIOSY$
IO.RDD
IO.RMT
IO.LSI
IO.UEI
IO.USI
IO.CSI
IO.DSI
IO.RAM

010010
010020
011000
011450
011460
013000
013400
015000

020
020
022
023
023
026
027
032

010
020
000
050
060
000
000
000

READ DIGITAL DATA
READ MAPPING TABLE
LINK TO DSI INTERRUPTS
UNLINK EVENT FLAGS
UNLINK FROM OSI INTERRUPTS
CONNECT TO DSI INTERRUPTS
DISCONNECT FROM DSI INTERRUPTS
READ ANALOG MAPPING TABLES

000
000
000
000
000

ATTEMPT TRANSMISSION
ACCEPT TRANSFER
CONNECT FOR RECEPTION
DISCONNECT FROM RECEPTION
REJECT TRANSFER

PCLll I/O FUNCTIONS
IO.ATX
IO.ATF
IO.CRX
IO.DRX
IO.RTF

000400
001000
014400
015000
015400

001
002
031
032
033

DEFINE THE GENERAL USER-MODE I/O QUALIFIER BIT.
;

IQ.UMD

000004

000

004

USER MODE DIAGNOSTIC REQUEST

; DEFINE USER-MODE DIAGNOSTIC FUNCTIONS.
IO.HMS
IO.BLS
IO.OFF
IO.RDH
IO.WDH
IO.WCK
IO.RNF
IO.RNR
IO.RDS
IO.LPC

004000
004010
004020
004030
004040
004050
004060
004070
004070
004100

010
010
010
010
010
010
010
010
010
010

000
010
020
030
040
050
060
070
070
100

IO.~TD

IO.WTD
IO.TDD

004120
004130
004140

010
010
010

120
130
140

IO.DGN
IO.WPD
IO.RPD
IO.CER
IO.CEW

004150
004160
004170
004200
004210

010
010
010
010
010

150
160
170
200
210

(DISK) HOME SEEK OR RECALIBRATE
(DISK) BLOCK SEEK
(DISK) OFFSET POSITION
(DISK) READ DISK HEADER
(DISK) WRITE DISK HEADER
(DISK) WRITECHECK (NON-TRANSFER)
(DECTAPE) READ BLOCK NUMBER FORWARD
(DECTAPE) READ BLOCK NUMBER REVERSE
(OISK-RX50) RETURN DISKETTE SPEED
(MAGTAPE) READ LONGITUDINAL PARITY
CHAR
(DISK) READ TRACK DESCRIPTOR
(DISK) WRITE TRACK DESCRIPTOR
(DISK) WRITE TRACK DESCRIPTOR
DISPLACED
DIAGNOSE MICRO PROCESSOR FIRMWARE
(DISK) WRITE PHYSICAL BLOCK
(DISK) READ PHYSICAL BLOCK
(DISK) READ CE BLOCK
(DISK) WRITE CE BLOCK

A-69

SCBDF$

A.21

SCBDF$

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. NORMALLY, AN
SCB EXISTS FOR EACH "PROCESS" THAT A DRIVER CAN POSSIBLY HAVE
CONCURRENTLY ACTIVE. FOR EXAMPLE, A DISK THAT SUPPORTS
OVERLAPPED SEEK OPERATIONS REQUIRES THAT THERE EXIST A
SEPARATE SCB FOR EACH UNIT THAT CAN BE ACTIVE. IN THIS CASE,
THE FORKBLOCK IN THE SCB IS USED TO SUSPEND THE DRIVER PROCESS
DURING GTPKT AND IS LINKED INTO THE CONTROLLER REQUEST QUEUE
WHOSE LISTHEAD IS IN THE KRB OF THE ASSIGNED CONTROLLER
(USUALLY STATIC S.KRB).
IN ADDITION TO CONTAINING THE DRIVER'S PROCESS CONTEXT AND
; DEFINING THE STATE OF THE CURRENT CONTROLLER STATE (NOT
NECESSARILY THE PHYSICAL CONTROLLER STATE) A LISTHEAD IS
MAINTAINED OF ALL PENDING I/O PACKETS TO BE PROCESSED.
i -

. IF NB

SYSDF
.ASECT

.=0
000000

S. LHD:

. BLKW

000004
000006
000010
000012
000014
000016
000020
000021
000022
000023
000024
000026
000030

.BLKW
.BLKW
.BLKW
.BLKW
S.KS5:
.BLKW
S . PKT :
. BLKW
S.CTM:
.BLKB
S.ITM:
.BLKB
S . STS :
. BLKB
S.ST3:
.BLKB
S. ST2 :
. BLKW
S.KRB:
.BLKW
S . RCNT : . BLKB

000031

S . ROFF:

. BLKB

000032

S . EMB :

. BLKW

000034

S . KTB :

. BLKW

S.FRK:

1
1
1
1
1
1
1

1
1
1
1
1

iPENDING I/O REQUEST (PACKET) QUEUE
LISTHEAD
iFORK BLOCK LINK WORD
iFORK-PC
iFORK-R5
iFORK-R4
iFORK KISAR5
iADDRESS OF CURRENT I/O PACKET
iCURRENT TIMEOUT COUNT
iINITIAL TIMEOUT COUNT
iSTATUS (O=FREE, NE O=BUSY)
iSTATUS EXTENSION BYTE
iSTATUS EXTENSION
iADDRESS OF KRB
iNUMBER OF REGISTERS TO COpy
;(NOT IN USE)
iOFFSET TO FIRST DEV REG TO COPY
i (NOT IN USE)
iERROR MESSAGE BLOCK POINTER
; (NOT IN USE)
iSTART OF MULTI-ACCESS KRBS (OPTIONAL)

.PSECT

A-70

SCBDF$
.IFF
i+
i STATUS CONTROL BLOCK STATUS EXTENSION BIT DEFINITIONS
i-

iERROR IN PROGRESS (l=YES)
iERROR LOGGING ENABLED (O=YES)
iERROR LOGGING SUPPORTED (l=YES)
iMULTIACCESS DEVICE (l=YES)
iLOAD SHARING ENABL. (l=YES, MUST BE
iO ON P/OS)
iSUPPORTS EXECUTIVE BLOCK CHECKING
i (MAX LBN)
iSUPPORTS ACCOUNTING STATISTICS
iAND MIGHT SUPPORT SEEK OPTIMIZATION
i(DEPENDS ON S3.0PT)
iSCB AND KRB ARE CONTIGUOUS (l=YES)
iTHESE TWO BITS DEFINE THE OPTIMIZATION
iMETHOD.
iOP2,OP1=O,0 INDICATES NEAREST CYLINDER
iOP2,OP1=0,1 INDICATES ELEVATOR
iOP2,OP1=1,0 INDICATES C-SCAN
;OP2,OP1=1,1 RESERVED
iDRIVER HAS OPERATION OUTSTANDING
i(l=YES)
iEXTERNAL HEADER AND NEW I.LN2 SUPPORT
;(0 FOR FILES-ll OR ANSI MAGTAPE ACPS)

S2.EIP=1
S2.ENB=2
S2.LOG=4
S2.MAD=10
S2.LDS=40
S2.0PT=100

S2.CON=200
S2.0Pl=400
S2.0P2=1000

S2.ACT=2000
S2.XHR=4000

i+
i STATUS CONTROL BLOCK STATUS EXTENSION (S.ST3) DEFINITIONS
i-

S3.DRL=1
S3.NRL=2
S3.SIP=4
S3.ATN=10
S3.SLV=20
S3.SPA=40
S3.SPB=100
S3.0PT=200
S3.SPU=S3.SPA!S3.SPB

iMULTI-ACCESS DRIVE IN RELEASED STATE
i(l=YES)
iDRIVER SHOULDN'T RLS MULTI-ACCESS
iDRIVE (l=YES)
iSEEK IN PROGRESS (l=YES)
iDRIVER MUST CLEAR ATTENTION BIT
i(l=YES)
iDEVICE USES SLAVE UNITS (l=YES)
iPORT 'A' SPINNING UP
iPORT SPINNING UP
iSEEK OPTIMIZATIONS ENABLED (l=YES)
i.OR. OF PORT SPINUP BITS

i+
i

KRB ADDRESS TABLE (S.KTB) PORT OFFLINE FROM THIS SCB FLAG.

KP.OFL=l

iKRB ADDRESS POINTS TO OFFLINE PORT (l=YES)

A-71

SCBDF$

;+
MAPPING ASSIGNMENT BLOCK (FOR UNIBUS MAPPING REGISTER
ASSIGNMENT) .. OF HISTORICAL INTEREST ONLY ON PIOS AND
; QBUS PROCESSORS

,. -

.ASECT

.=0
M.LNK:
M.UMRA:
M.UMRN:
M.UMVL:

.BLKW
.BLKW
.BLKW
.BLKW

1
1
1
1

M.UMVH:
M.BFVH:

.BLKB
.BLKB

1
1

M.BFVL:

.BLKW

M.LGTH=

;LINK WORD
;ADDRESS OF FIRST ASSIGNED UMR
;NUMBER OF UMR'S ASSIGNED * 4
;LOW 16 BITS MAPPED BY 1ST ASSIGNED
;UMR
;HIGH 2 BITS MAPPED IN BITS 4 AND 5
;HIGH 6 BITS OF PHYSICAL BUFFER
;ADDRESS
iLOW 16 BITS OF PHYSICAL BUFFER
iADDRESS
iLENGTH OF MAPPING ASSIGNMENT BLOCK

. ENDC
.PSECT

A-72

TTSYM$

A.22

TTSYM$
DECIMAL

TC.WID
TC.LPP
TC.RSP
TC.XSP
TC.STB
TC. ISL
TC.RAT
TC.TTP
TC.SCR
TC.SCP
TC.HFL
TC.VFL
TC.NL
TC.SFF
TC.HFF
TC.LVF
TC.HHT
TC.NST
TC.BSP
TC.ACR
TC.SMR
TC.SMP
TC.SMO
TC.CCF
TC.ALT
TC. IMG
TC.NKB
TC.NPR
TC.ESQ
TC.LCP
TC.PAR
TC.EPA
TC.DLU
TC.BLK
TC,. FRM
TC.HLD
TC.TAP
TC.CEQ
TC.NEC
TC.SLV
TC.PRI
TC.UCO
TC.UCl
TC.UC2
TC.UC3
TC.UC4

OCTAL

3.
4.
5.
6.

5
6
7

8.
9.
10.
11.
12.
13.
14.

15.
16.

17.
18.

19.
20.

21
22
23
24

21.

22.

23.
24.

27
30

25.
28.

31
32
33
34

29.
30.

26.

27.

31.
32.

33.
34.

35.
36.

37.
38.
39.
40.

12
13
14

15
16

35
37
40
41
42
43
44

45
46

44.
45.

47
50
51
52
53
54
55

46.

41.
42.
43.

LINE WIDTH
LINES PER PAGE
RECEIVER SPEED
TRANSMITTER SPEED
TWO STOP BITS
SUBLINE ON INTERFACE
READ-AHEAD TYPE
TERMINAL TYPE
SCRIPT LINE
SCOPE
HORIZONTAL FILL REQUIREMENT
VERTICAL FILL
ASCII NEWLINE TERMINAL
SIMULATE FORMFEED AND VERTAB
HARDWARE FORMFEED AND VERTAB
LA36 VERTICAL FILL
HARDWARE HORIZONTAL TAB
NON-STANDARD HARDWARE TAB
HARDWARE BACKSPACE
AUTOMATIC CARRIAGE RETURN REQUIRED
SMALL CHARACTER INPUT ENABLED
SMALL CHARACTER INPUT REQUIRED
(/LOWERCASEINPUT)
SMALL CHARACTER OUTPUT ENABLED
CTRL/C FLUSHES TYPEAHEAD AND READ
ALTERNATIVE ALTMODE RECOGNITION
lAS - MESSAGES INHIBITED
NO KEYBOARD
NO PRINTER
ESCAPE SEQUENCE RECOGNITION
LOCAL COpy LINE
PARITY RECOGNITION/GENERATION REQUIRED
EVEN PARITY
DIALUP LINE
BLOCK MODE TERMINAL
FORMS MODE TERMINAL
TERMINAL HOLD MODE
LOW SPEED PAPER TAPE READER
COMPATIBLE ESCAPE SEQUENCES
TERMINAL IN NO-ECHO MODE
TERMINAL IN SLAVE MODE
TERMINAL IS PRIVILEGED
USER CHARACTERISTIC 0
USER CHARACTERISTIC 1
USER CHARACTERISTIC 2
USER CHARACTERISTIC 3
USER CHARACTERISTIC 4

A-73

TTSYM$
TC.UC5
TC.UC6
TC.UC7
TC.UC8
TC.UC9
TC.FDX
TC.BIN

47.
48.
49.
50.
51.
52.
53.

57
60
61
62
63
64
65

TC.REM
TC.8BC
Tc.p8B
TC.TBF
TC.CTS
TC.ANS
TC.CSQ
TC.CTC
TC.ASP
TC.ABD
TC.TBS
TC.TBM
TC.NBR
TC.ACD
TC.ARC
TC.TRN
TC.XMM
TC.FSZ
XT.DLM
XT.DMD
XT.DTT
XT.DIT
XT.MTP
XT.SDE
XT.TAK
XT.GOV

54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
68.
69.
70.
71.
72.
73.
74.
75.
76.
77.
78.
79.

66
67
70
71
72
73
74
75
76
77
100
101
102
103
104
105
106
107
110
111
112
113
114
115
116
117

XT.TSP
XT.TTO
TC.ANI
TC.AVO
TC.DEC
TC.EDT
TC.RGS
TC.INT

80.
81.
82.
83.
84.
85.
86.
87.

120
121
122
123
124
125
126
127

TC.TLC
TC.MAX

88.
89.

130
131

USER CHARACTERISTIC 5
USER CHARACTERISTIC 6
USER CHARACTERISTIC 7
USER CHARACTERISTIC 8
USER CHARACTERISTIC 9
LINE HAS FULL DUPLEX CAPABILITY
TERMINAL HAS BINARY INPUT (DO NOT
RECOGNIZE IMMEDIATE CONTROL CHARS)
TERMINAL IS REMOTE (CONNECTED VIA MODEM)
ACCEPT 8-BIT CHARACTERS
PASS 8 BITS ON READ PASS ALL
TYPEAHEAD BUFFER CHARACTER COUNT
CTRL/S STATE
ESCAPE SEQUENCES ARE ANSI FORMAT
ONLY PASS CTRL/S,Q ON READ PASS ALL
ONLY PASS CTRL/S,Q,C ON REAL PASS ALL
REMOTE ANSWER SPEED
AUTO-BAUD SPEED DETECTION
TYPEAHEAD BUFFER SIZE
TYPEAHEAD BUFFER MODE (TASK OR CLI)
DON'T BROADCAST TO THIS TERMINAL
ANCILLARY CONTROL DRIVER
AUTOANSWER RING COUNT
SET DIALING TRANSLATE TABLE
MAINTENANCE MODE
FRAME SIZE, DATA BITS + PARITY BIT (IF ANY)
DIALING MODE (TONE, PULSE, ... )
DATA MODE (SERIAL, CODEC, VOICE, DTMF)
DTMF TONE LENGTH (10MS MULTIPLES)
DTMF INTERDIGIT LENGTH
MODEM TYPE
SET DTMF ESCAPE SEQUENCE
AUX KEYBOARD INTERPRETATION EN/DISABLE
GO VOICE (I.E. DELAY LOSS OF CARRIER
DISCONNECT)
MONITOR LINE (TURN TMS SPEAKER ON/OFF)
HARDWARE SILENCE TIMEOUT (SECONDS)
ANSI CRT TERMINAL
VT100-FAMILY TERMINAL DISPLAY
DIGITAL CRT TERMINAL
LOCAL TERMINAL EDITING
REGIS GRAPHICS
HANDLE AC (OR INT-DO) DIFFERENTLY FOR IO.RTT
FOR P/OS
INDICATE CLI SHOULD GET AC NOTIFICATION
THIS MUST BE ONE GREATER THAN THE HIGHEST
VALUE USED FOR A SYMBOL

; SET CHARACTERISTIC ERROR CODES
;-

A-74

TTSYM$

SE. ICN
SE.FIX
SE.BIN
SE.VAL
SE.TER
SE.SPD
SE.SPL
SE.PAR
SE.LPR
SE.NSC

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.

1
2
3
4
5
6
7
10
11
12

SE.UPN
SE.NIH

11.
12.

13
14

ILLEGAL CHARACTERISTIC NAME
ATTEMPT TO CHANGE FIXED CHARACTERISTIC
ILLEGAL VALUE FOR BINARY CHARACTERISTIC
ILLEGAL VALUE FOR NON-BINARY CHARACTERISTIC
ILLEGAL TERMINAL TYPE
ILLEGAL SPEED FOR INTERFACE
ILLEGAL SPLIT SPEED FOR INTERFACE
ILLEGAL PARITY TYPE FOR INTERFACE
OTHER ILLEGAL LINE PARAMETERS
INTERFACE DOES NOT HAVE SETTABLE
CHARACTERISTICS
NO SPACE TO SAVE DEFAULT CHARACTERISTICS
CHARACTERISTIC NOT ASSEMBL~D IN HANDLER

i+
i NOW THE SUBFUNCTION CODES FOR THE SET CHARACTERISTICS FUNCTION
i-

SF.SSC
SF.SMC
SF.RDF
SF.STT
SF.STS
SF.GSC
SF.GMC
SF.GAC
SF.SAC

24001020
24001040
2400 060
2400 100
2400 120
2400 140
2400 160
2400 200
2400 220

SET SINGLE CHARACTERISTIC
SET MULTIPLE CHARACTERISTICS
RESTORE DEFAULT
SET TERMINAL TYPE
SET TERMINAL TYPE AND SPEED
GET SINGLE CHARACTERISTIC
GET MULTIPLE CHARACTERISTICS
GET ALL CHARACTERISTICS
SET ALL CHARACTERISTICS

SF.DEF

010

SET DEFAULT CHARACTERISTICS

i+
i NOW THE SPEED TYPES
i-

5.0
S.50
S.75
S.100
S.110
S.134
S.150
S.200
S.300
S.600
S.1200
S.1800
S.2000
S.2400
S.3600
S.4800

1
2
3
4
5
6
7
8
9

10
11
12
13
14
15
16

1.
2.
3.
4.
5.
6.
7.
10.
11.
12.
13.
14.
15.
16.
17.
20.
A-75

TTSYM$
S.7200
S.9600
S.EXTA
S.EXTB
S.19.2
S.38.4

17
18
19
20
21.
22.

21.
22.
23.
24.
25
26

19.2KBPS
38.4KBPS

i+
i

NOW THE TERMINAL TYPES

T.UNKO
T.AS33
T.KS33
T.AS35
T.L30S
T.L30P
T.LA36
T.VT05
T.VT50
T.VT52
T. VTS'5
T.VT61
T.L180
T.VI00
T.L120
T.SCRO
T.LA12
T.LI00
T.LA34
T.LA38
T.VI0l
T.VI02
T.VI05
T.V125
T.V131
T.V132
T.LA50
T.LQPl
T.LQP2
T.BMPl
T.USRO
T.USRl
T.USR2
T.USR3
T.USR4

1.
2.
3.

1
2
3

6.
7.

6
7

8.
10
9.
11
10.
12
11.
13
12.
14
13.
15
14.
16
15.
17
16.
20
17.
21
18.
22
19.
23
20.
24
21.
25
22.
26
23.
27
24.
30
25.
31
26.
32
27.
33
28.
34
29.
35
128.
200
T.USRO+l
T.USR1+1
T.USR2+1
T.USR3+1

UNKNOWN (UNSPECIFIED)
ASR33
KSR33
ASR35
LA30S
LA30P
LA36
VT05
VT50
VT52
VT55
VT61
LA180S
VT100
LA120
SCRIPT LINE
LA12
LAI00
LA34
LA38
VT101
VT102
VT105
VT125
VT131
VT132
LA50
LQP I
LQP II
BIT MAP TERMINAL #1 (ORIGINAL PRO 350)
USER TERMINAL 0
USER TERMINAL 1
USER TERMINAL 2
USER TERf1INAL 3
USER TERMINAL 4

; DIAL MODES
XT.DIA
XT.DTM

DIAL PULSE, 10 PULSES PER SEC
DTMF
A-76

TTSYM$
XT.D20
XT.OHS

2
3

DIAL PULSE, 20 PULSES PER SEC
OFF-HOOK SERVICE (EXTERNAL FIXED NUMBER)

1
2

1
2
3

VOICE TELEPHONE (NO DATA)
SERIAL DATA
ENCODED VOICE
DTMF DATA

; DATA MODES
XT.VOI
XT.SER
XT.ENC
XT.DTD

; MODEM TYPE
XTM.NO
XTM.FS
XTM.PS
XTM.21
XTM.Ml
XTM.M2
XTM.US

-1.

o
1
5
6

7
10.

177777

o
1
5
6
7

NO MODEM, HARD-WIRED LINE
US FSK, 0 .. 300 BAUD BELL 103
US DPSK, 1200 BAUD BELL 212
CCITT V.21, 0 .. 300 BAUD EUROPEAN
CCITT V.23 MODE 1, 75/0 .. 600
CCITT V.23 MODE 2, 75/0 .. 1200
MICRO-SWITCH

; UNSOLICITED EVENT TYPES
XTU.UI
XTU.CD
XTU.CL
XTU.DR
XTU.OF
XTU.ON
XTU.RI
XTU.TU
XTU.TD

4
6

4
6
10
12
14
16
20

8.
10.
12.
14.
16.

UNSOLICITED INPUT
CARRIER DETECT NOTIFICATION
ARRIER LOSS
DTMF ESCAPE SEQUENCE RECEIVED
XOFF RECEIVED
XON RECEIVED
RING
TELSET OFF HOOK
TELSET ON HOOK

BITS FOR RETURN FROM 'GET TERMINAL SUPPORT'
BIT MASK
Fl.ACR
Fl.BTW
Fl'. BUF
Fl.UIA
Fl.CCO
Fl.ESQ
Fl.HLD
Fl.LWC
Fl.RNE
Fl.RPR
F1.RST
F1.RUB
F1.SYN

000001
000002
000004
000010
000020
000040
000100
000200
000400
001000
002000
004000
010000

AUTO CR/LF ON LONG LINES
BREAK THROUGH WRITE
INTERMEDIATE BUFFERING
UNSOLICITED INPUT AST'S
CANCEL CTRL-O ON WRITE
ESCAPE SEQUENCE SUPPORT
HOLD SCREEN SUPPORT
LOWER CASE CONVERSION
READ NO ECHO
READ WITH PROMPT
READ WITH SPECIAL TERMINATORS
SCOPE RUBOUTS
XON/XOFF
A-77

TTSYM$
Fl.TRW
Fl.UTB
Fl.VBF
F2.SCH
F2.GCH
F2.DCH
F2.DKL
F2.ALT
F2.SFF
F2.CUP
F2.FDX

020000
040000
100000
000001
000002
000004
000010
000020
000040
000100
000200

TRANSPARENT READ/WRITE
BUFFERING IN TASK BUFFER
EXEC BUFFERS ARE VARIABLE LENGTH
SET CHARACTERISTICS
GET CHARACTERISTICS
DUMP/RESTORE CHARACTERISTICS
HISTORICAL 11D/IAS IO.KIL
ALTMODE IS ECHOED
FORMFEED CAN BE SIMULATED
DEVICE INDEPENDENT CURSOR POSITIONING
FULL DUPLEX TERMINAL DRIVER

SUBFUNCTION BITS FOR TERMINAL HANDLER QIO'S.
MUST REFLECT THE REALITY IN QIOMAC.MAC.
TF.RST
TF.BIN
TF.RAL
TF.RNE
TF.RNC
TF.XOF
TF.TMO
TF.RCU
TF.WAL
TF.WMS
TF.CCO
TF.WBT
TF. SYN
TF.XCC
TF.NOT
TF.AST
TF.ESQ
TF.UCH

001
002
010
020
040
100
200
001
010
020
040
100
200
001
002
010
020
040

NOTE THAT THIS

[IO.RLB/IO.RPR] READ WITH SPECIAL TERMINATORS
SEND PROMPT AS 'PASS ALL'
READ PASS ALL
READ WITH NO ECHO
READ WITH NO CASE CONVERSION
SEND XOF AFTER PROMPT
READ WITH TIMEOUT
[IO.WLB] RESTORE CURSOR POSITION
WRITE PASS ALL
WRITE SUPPRESSIBLE MESSAGE
CANCEL CTRL/O
BREAK THROUGH READ
SYNCHRONOUS WRITE (lAS ONLY)
[IO.ATT] DO NOT TRAP CTRL/C
NOTIFICATION ONLY FOR TYPEAHEAD
SPECIFY AST'S IN ATTACH
RECOGNIZE ESCAPE SEQUENCES
CHARACTER AST NOTIFICATION (lAS)

A-78

TCBDF$

A.23

TCBDF$

TASK CONTROL BLOCK OFFSET AND STATUS DEFINITIONS
TASK CONTROL BLOCK
i-

000000
000002
000003
000004
000006
000012
000016
000022
000026
000030
000032
000034
000036
000040
000041
000044
000046
000050

.ASECT
.=0
T.LNK:
.BLKW
T.PRI:
.BLKB
T. IOC:
. BLKB
T.PCBV: .BLKW
T.NAM:
.BLKW
T.RCVL: .BLKW
T.ASTL: .BLKW
T.EFLG: .BLKW
T.UCB:
.BLKW
T.TCBL: .BLKW
T . STAT: . BL KW
T . ST 2 :
• BLKW
T • ST 3 :
• B L KW
T.DPRI: .BLKB
T.LBN:
.BLKB
T.LDV:
.BLKW
T.PCB:
.BLKW
T.MXSZ: .BLKW

000052
000054
000060
000062
000063
000064
000065
000066
000072
000074
000076
000077

T.ACTL: .BLKW
T.ATT:
.BLKW
T • ST 4 :
• B L KW
T . HDLN: . BLKB
.BLKB
T.GGF:
.BLKB
T.TIO:
.BLKB
T.EFLM: .BLKW
T.TKSZ: .BLKW
T.OFF:
.BLKW
.BLKB
T.SRCT: .BLKB

000100
000104
000110
000112

T.RRFL:
T.OCBH:
T.RDCT:
T. SAST:

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
1

iUTILITY LINK WORD
iTASK PRIORITY
iI/O PENDING COUNT
;POINTER TO COMMON PCB VECTOR
;TASK NAME IN RADIX-50
iRECEIVE QUEUE LISTHEAD
iAST QUEUE LISTHEAD
;TASK LOCAL EVENT FLAGS 1-32
;UCB ADDRESS FOR PSEUDO DEVICE 'TI'
iTASK LIST THREAD WORD
;FIRST STATUS WORD (BLOCKING BITS)
iSECOND STATUS WORD (STATE BITS)
;THIRD STATUS WORD (ATTRIBUTE BITS)
;TASK'S DEFAULT PRIORITY
iLBN OF TASK LOAD IMAGE
iUCB ADDRESS OF LOAD DEVICE
;PCB ADDRESS OF TASK PARTITION
;MAXIMUM SIZE OF TASK IMAGE (MAPPED
iONLY)
;ADDRESS OF NEXT TASK IN ACTIVE LIST
iATTACHMENT DESCRIPTOR LISTHEAD
;FOURTH TASK STATUS WORD
iLENGTH OF HEADER (0 IF HDR IN POOL)
;UNUSED
iGROUP GLOBAL USE COUNT FOR TASK
iBUFFERED I/O IN PROGRESS COUNT
iTASK WAITFOR MASK/ADDRESS
;TASK LOAD SIZE IN 32 WD BLOCKS
iOFFSET TO TASK IMAGE IN PARTITION
iRESERVED
iSREF WITH EFN COUNT IN ALL RECEIVE
iQUEUES

.BLKW
.BLKW
.BLKW
. BLKW

1
1

.IF NB

SYSDF

.BLKW
. B L KW

1
1

2
2

iRECEIVE BY REFERENCE LISTHEAD
iOFFSPRING CONTROL BLOCK LISTHEAD
iOUTSTANDING OFFSPRING AND VT: COUNT
iSPECIFY AST LISTHEAD

$$$ = .
000114
000116

T.RRM:
T • I RM :

;REQUIRED RUN MASK (NOT USED)
;INITIAL RUN MASK SET UP BY INSTALL
A-79

TCBDF$
i (NOT USED)

000120

T.CPU:

000121

.BLKB

iPROCESSOR NUMBER ON WHICH TASK LAST
iEXECUTED
; (UNUSED)

.=$$$
$$$=.
T.ACN:

.BLKW 1 iPOINTER TO ACCOUNTING BLOCK
.IF NDF A$$CNT iNOT CURRENTLY USED

.=$$$
.ENDC
$$$=.
T.ISIZ:

.BLKW 1 iSIZE OF ROOT I SPACE
.IF NDF U$$DAS

.=$$$
.ENDC
T.LGTH=.
T.EXT=O

NDF U$$DAS
iLENGTH OF TASK CONTROL BLOCK
iLENGTH 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 (l=YES)
iI/O RUN DOWN IN PROGRESS (l=YES)
;ABORT MESSAGE BEING OUTPUT (l=YES)
iTASK BLOCKED FOR CHECKPOINT IN PROGRESS
i(l=YES)
iTASK IS RUNNING ON ANOTHER PROCESSOR (l=YES)
iTASK BLOCKED BY CLI COMMAND
iTASK HAS CKP REQUEST (MP SYSTEM ONLY) (l=YES)
;INCREMENT BLOCKING COUNT MASK

A-80

TCBDF$

i+
i TASK BLOCKING STATUS MASK
i-

TS.BLK=177777
i+
i SECOND STATUS WORD (STATE BITS)
i-

T2.AST=100000
T2.DST=40000
T2.CHK=20000
T2.REX=10000
T2.SEF=4000
T2.SIO=1000
T2.AFF=400
T2.HLT=200
T2.ABO=100
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,SEE PCB AS
iWELL)
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)

i+
i

THIRD STATUS WORD (ATTRIBUTE BITS)

T3.ACP=100000
T3.PMD=40000
T3.REM=20000
T3.PRV=10000
T3.MCR=4000
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

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 FUNCTION
i(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
iTASK HAS CHtCKPOINT 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 SPM-11, (NOT AVAILABLE ON P/OS,
iTHIS BIT HAS BEEN TEMPORARILY REDEFINED
iTO DISTINGUISH APPLICATION TASKS
iFROM SYSTEM TASKS. THE FORMER ARE REMOVED
iWHEN APPLICATION EXITS. IT IS SOMETIMES
;REFERRED TO AS THE "BEAT ME" BIT).
A-81

TCBDF$

T3.GFL=1

iGROUP GLOBAL EVENT FLAG LOCK

i+
i STATUS BIT DEFINITIONS FOR FOURTH STATUS WORD (T.ST4)
i -

T4.VCT=100
T4.MUT=40

T4.LDD=20
T4.PRO=10
T4.PRV=4
T4.DSP=2
T4.SNC=1

iTASK HAS BEEN VICTIMIZED (BLASTED)
iTASK IS A MULTI-USER TASK (MEANING SEPARATED
iREAD ONLY AND READ/WRITE FOR TASK REGION. THIS
iHAS PERFORMANCE ADVANTAGES OVER A NON MU TASK
iAND IS FULLY SUPPORTED ON P/OS)
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/D SPACE
iTASK USES COMMONS FOR SYNCHRONIZATION

i+
i

REQUIRED RUN MASK

TR.UBT=100000
TR.UBS=40000
TR.UBR=20000
TR.UBP=10000
TR.UBN=4000
TR.UBM=2000
TR.UBL=1000
TR.UBK=400
TR.UBJ=200
TR.UBH=100
TR.UBF=40
TR.UBE=20
TR.CPD=10
TR.CPC=4
TR.CPB=2
TR.CPA=l

iUNIBUS RUN T
iUNIBUS RUN S
iUNIBUS RUN R
iUNIBUS RUN P
iUNIBUS RUN N
iUNIBUS RUN M
iUNIBUS RUN
iUNIBUS RUN K
iUNIBUS RUN J
iUNIBUS RUN H
iUNIBUS RUN F
iUNIBUS RUN E
iPROCESSOR D
iPROCESSOR C
iPROCESSOR
iPROCESSOR A

.ENDC
.PSECT

A-82

UCBDF$

A.24

UCBDF$

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
i 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. A UCB EXISTS FOR EVERY LOGICAL
UNIT ON THE SYSTEM AND DEFINES UNIT CHARACTERISTICS AS WELL AS
CURRENT UNIT STATUS.
i-

.ASECT
.=177772
.IF NB

SYSDEF

.IF OF

A$$CNT

.BLKW

;POINTER TO USER ACCOUNT BLOCK (DV.TTY ONLY)

1 ; (-6) MULTI-USER PROTECTION WORD (DV.TTY
; ONLY)
1 ;(-4) LOGIN UIC (DV.TTY ONLY)
1 ;(-2) OWNING TERMINAL(DEVICE ALLOCATION)
1 iBACK POINTER TO DCB
1 iPOINTER TO REDIRECT UNIT UCB
1 iCONTROL PROCESSING FLAGS
1 iUNIT STATUS
1 iPHYSICAL UNIT NUMBER
1 iUNIT STATUS EXTENSION
1 iFIRST DEVICE CHARACTERISTICS WORD
1 iSECOND DEVICE CHARACTERISTICS WORD
1 iTHIRD DEVICE CHARACTERISTICS WORD
1 iFOURTH DEVICE CHARACTERISTICS WORD
1 iPOINTER TO SCB

.=177770
U.UAB:

.IFF
U.UAB:
.ENDC
.ENDC
177772

U.MUP:

.BLKW

177774
177776
000000
000002
000004
000005
000006
000007
000010
000012
000014
000016
000020

U.LUIC:
U.OWN:
U.DCB:
U.RED:
U.CTL:
U.STS
U.UNIT:
U.ST2:
U.CW1:
U.CW2:
U.CW3:
U.CW4:
U.SCB:

.BLKW
.BLKW
.BLKW
.BLKW
.BLKB
.BLKB
.BLKB
.BLKB
.BLKW
.BLKW
.BLKW
.BLKW
.BLKW

A-83

UCBDF$
000022
000024
000026
000030

U.ATT:
U.BUF:

000032
000034
000036
000032
000040
000042
000046
000050
000046
000050
000052

U.UCBX=U.CNT+2
U.ACP=U.CNT+4
U.VCB=U.CNT+6
U.CBF=U.CNT+2
U.UMB=U.CNT+i0
U.PRM=U.CNT+12
U.UTMO=U.CNT+16
U.LHD=U.CNT+20
U.ICSR=U.CNT+16
U.SLT=U.CNT+20
U.SPRM=U.CNT+22

U.CNT:

.BLKW
.BLKW
.BLKW
.BLKW

1
1
1
1

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
i(DV.MSD)
iBIAS OF UCB EXTENSION IN SEC POL
iADDRESS 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
iCSR ADDRESS (P/OS Vi DRIVER ACCESS ONLY)
iSLOT NUMBER (P/OS Vi DRIVER ACCESS ONLY)
i4 WD SAVED I/O PACKET AREA (DV.MSD AND
iUSAGE

iOF $VOLSC) USED AT I/O COMPLETION TO RESTORE
iI/O PACKET IF STALLED I/O CONDITION IN EFFECT)

000054
000060

U.BPKT=U.CNT+24
U.UC2X=U.CNT+30

000062

U.OTRF=U.CNT+32

000064

U.CMST=U.CNT+34

iUNIT BAD BLOCK PACKET WAITING LIST
iPOINTER TO SECOND EXTENSION IN
iSECONDARY POOL
iOUTSTANDING COMMAND STATUS REQUEST
iREGISTER
iCOMMAND STATUS PROGRESS REGISTER

MAGTAPE DEVICE DEPENDANT UCB OFFSETS
000040
000042
000044

U.SNUM=U.CNT+i0
U.FCDE=U.CNT+12
U.KRB1=U.CNT+14

iSLAVE UNIT NUMBER
iFUNCTION CODE
iSUBCONTROLLER KRBi POINTER

DEFINE SECONDARY POOL UCB EXTENSION OFFSETS
(DV.MSD DEVICES ONLY)
.=0
000000
000022
000026
000032
000033
000034
000035
000036

_X. NAME:
X. IOC:
X.ERHL:
X.ERSL:
X.ERSC:
X.ERHC:
X.WCNT:

.BLKW
.BLKW
.BLKW
.BLKB
.BLKB
.BLKB
.BLKB
.BLKW

9.iFIXED ACCOUNTING TRANSACTION HEADER
2 ;DRIVE NAME IN RADIX-50
2 i I/O COUNT
1 iHARD ERROR LIMIT
1 iSOFT ERROR LIMIT
1 iSOFT ERROR COUNT
1 iHARD ERROR COUNT
2 iWORDS TRANSFERED COUNT

A-84

UCBDF$

DEFINE OFFSETS FOR SEEK OPTIMIZATION DEVICES
000042
000046
000050
000051
000051

X.CYLC:
X.CCYL:
X.FCUR:
X.FLIM:
X.DSKD:

.BLKW
.BLKW
.BLKB

000052
000054
000055
000056
000012
000010
000005

X.DNAM:
X.UNIT:

.BLKW
.BLKB
.BLKB

.BLKB

X.LGTH=.
X.DFFL=10.
X.DFSL=8.
X.DFHL=5.

2 iCYLINDERS CROSSED COUNT
1 iCURRENT CYLINDER
1 iCURRENT FAIRNESS COUNT
iFAIRNESS COUNT LIMIT
1 iDISK DIRECTION (HIGH BIT l=OUT)
1 iDEVICE NAME FOR ACCOUNTING
1 iUNIT NUMBER FOR ACCOUNTING
1 iUNUSED FOR NOW
iLENGTH OF THE UCB EXTENSION
iDEFAULT FAIRNESS COUNT LIMIT
iDEFAULT SOFT ERROR LIMIT
iDEFAULT HARD ERROR LIMIT

DEFINE OFFSETS FOR DISK MSCP CONTROLLERS (SECOND UCB
EXTENSION)

CHARACTERISTICS OBTAINED FROM "GET UNIT STATUS" END
PACKETS

000000
000002
000004
000010
000020
000024
000026
000030
000032
000034
000036
000037
000040
000042
000043

.=0
X.MLUN:
X.UNFL:

.BLKW
.BLKW
.BLKW
X.UNTI: .BLKW
X.MEDI: .BLKW
X. SHUN: .BLKW
X.SHST: .BLKW
X.TRCK: .BLKW
X.GRP:
.BLKW
X.CYL:
.BLKW
X.USVR: .BLKB
X.UHVR: .BLKB
X.RCTS: .BLKW
X.RBNS: .BLKB
X.RCTC: .BLKB

1
1
2
4
2
1
1
1
1

1
1
1
1
1

iMULTI-UNIT CODE
iUNIT FLAGS
iRESERVED
iUNIT IDENTIFIER
iMEDIA IDENTIFIER
iSHADOW UNIT
iSHADOW UNIT STATUS
iUNIT TRACK SIZE
iUNIT GROUP SIZE
iUNIT CYLINDER SIZE
iUNIT SOFTWARE VERSION
iUNIT HARDWARE VERSION
iUNIT RCT TABLE SIZE
iUNIT RBN 's / TRACK
iUNIT RCT COPIES

CHARACTERISTICS OBTAINED FROM "ONLINE" OR "SET UNIT
CHARACTERISTICS" END PACKETS
000044
000050

X.UNSZ:
X.VSER:

.BLKW
.BLKW

2 iUNIT SIZE
2 iVOLUME SERIAL NUr1BER

A-85

UCBDF$
000054

iSIZE OF DISK MSCP CONTROLLER UCB

X.DUSZ=.

i EXTENSION

.IF NB

TTDEF

TERMINAL DRIVER DEFINITIONS
000024
000026
000036
000040
000041
000042
000044
000045
000046
000047
000050

.=U.BUF
U.TUX:
U.TSTA:
U.UIC:
U.TLPP:
U.TFRQ:
U . T F LK :
U.TCHP:
U . TCVP :
U.TTYP:
U . TMT I:
U.TTAB:

.BLKW
.BLKW
.BLKW
.BLKB
.BLKB
. BL KW
.BLKB
. BLKB
.BLKB
. BLKB
.BLKW

1
4
1
1
1
1
1
1
1
1
1

.=.-2
000050

U.TECO:

.BLKB

000051
000052
000054
000056

U.TBSZ:
U.ACB:
U.AFLG:
U.ADMA:

.BLKB
.BLKW
.BLKW
.BLKW

1
1
1
1

iPOINTER TO UCB EXTENSION (UCBX)
iSTATUS QUADRUPLE-WqRD
iDEFAULT UIC <====(ANY DV.TTY DEVICE)
iLINES PER PAGE
iFORK REQUEST BYTE
iFORK LIST LINK WORD
iCURRENT HORIZONTAL POSITION
iCURRENT VERTICAL POSITION
iTERMINAL TYPE
iMODEM TIMER
iIF 0: U.TTAB+1 IS SINGLE-CHARACTER
TYPEAHEAD BUFFER, CURRENTLY EMPTY
iIF ODD: U.TTAB+1 IS SINGLE-CHARACTER TYPEAHEAD BUFFER AND HOLDS A CHARACTER
iIF NON-O AND EVEN: POINTER TO MULTICHARACTER TYPEAHEAD BUFFER
iTHE NEXT TWO OFFSETS OVERLAP U.TTAB WHEN
THE TYPEAHEAD BUFFER IS IN
SECONDARY POOL
iECHO BUFFER FOR DMA OPERATIONS WHEN UCBX
IS SECONDARY POOL AND THUS NOT
MAPPED BY A UMR
iTYPEAHEAD BUFFER SIZE
iANCILLARY CONTROL DRIVER BLOCK ADDR
iANCILLARY CONTROL DRIVER FLAGS WORD
iANCILLARY CONTROL DRIVER DMA BUFFER

DEFINE BITS IN STATUS WORD 1 (U.TSTA)
i

Sl.RST=l
Sl.RUB=2
Sl.ESC=4
Sl.RAL=10
Sl.RNE=20
Sl.CTO=40
Sl.0BY=100
Sl.IBY=200
Sl.BEL=400
Sl.DPR=1000
Sl.DEC=2000

iREAD WITH SPECIAL TERMINATORS IN PROGRESS
iRUBOUT SEQUENCE IN PROGRESS (NON-SCOPE)
;ESCAPE SEQUENCE IN PROGRESS
iREAD ALL IN PROGRESS
;ECHO SUPPRESSED
;OUTPUT STOPPED BY CTRL-O
iOUTPUT BUSY
;INPUT BUSY
iBELL PENDING
;DEFER PROCESSING OF CHAR. IN U.TECS
;DEFER ECHO OF CHAR. IN U.TECS
A-86

UCBDF$
Sl.DSI=4000
Sl.CTS=lOOOO
Sl.USI=20000
Sl.0BF=40000
Sl.IBF=100000

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)
S2.ACR=1
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
(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)
S3.RAL=10
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
iTYPEAHEAD 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 TYPEAHEAD BUFFER
iHAS PARITY ERROR
iLAST CHAR. IN TYPEAHEAD BUFFER
iHAS FRAMING ERROR
iLAST CHAR. IN TYPEAHEAD BUFFER
iHAS DATA OVERRUN ERROR
iNOTE - THE 3 BITS ABOVE MUST CORRESPOND
iTO THE RESPECTIVE ERROR FLAGS IN THE
iHARDWARE RECEIVE BUFFER
iPOSITION CURSOR BEFORE WRITE

DEFINE BITS IN STATUS WORD 4 (U.TSTA+6)
A-87

UCBDF$

iAC INT-DO HANDLED DIFFERENTLY FOR
iIO.RTT ON P/OS
iDIAL-OUT LINE (IMPLIES U2.RMT)
iANSI CRT TERMINAL
iVT100-FAMILY TERMINAL DISPLAY
iBLOCK MODE TERMINAL
iDIGITAL CRT TERMINAL
iTERMINAL HAS LOCAL EDITING FUNCTIONS
iTERMINAL SUPPORTS REGIS GRAPHICS
iTERMINAL WANTS CLI TO HAVE AC
iNOTIFICATION

S4.INT=40
S4.DLO=100
S4.ANI=400
S4.AVO=1000
S4.BLK=2000
S4.DEC=4000
S4.EDT=10000
S4.RGS=20000
S4.CTC=40000

.ENDC
VIRTUAL TERMINAL UCB DEFINITIONS

000006
000024
000026
000030
000032
000034

U.OCNT:
.=U.BUF
U.RPKT:
U.WPKT:
U. lAST:
U.OAST:
U.AAST:

.=U.UNIT
.BLKB
1 iOFFSPRING WITH THIS AS TI:
iCURRENT OFFSPRING READ I/O PACKET
iCURRENT OFFSPRING WRITE I/O PACKET
iINPUT AST ROUTINE ADDRESS
iOUTPUT AST ROUTINE ADDRESS
iATTACH AST ROUTINE ADDRESS

.BLKW
.BLKW
.BLKW
.BLKW
.BLKW

1
1
1
1
1

.IF NB

TTDEF

.IIF NE U.AAST+2-U.UIC .ERROR

iADJACENCY ASSUMED

.ENDC

000040

.=U.AAST+4
U.PTCB:.BLKW

1 iPARENT TCB ADDRESS

CONSOLE DRIVER DEFINITIONS
i

000026
000030
000034

.-=U.BUF+2
U.CTCB: .BLKW
U.COTQ: .BLKW
U.RED2: .BLKW

1 iADDRESS OF CONSOLE LOGGER TCB
2 iI/O PACKET LIST QUEUE
1 iREDIRECT UCB ADDRESS

.PSECT

A-88

UCBDF$

DEVICE TABLE STATUS DEFINITIONS
DEVICE CHARACTERISTICS WORD 1 (U.CW1) DEVICE TYPE
DEFINITION
BITS.
i-

DV.REC=1
DV.CCL=2
DV.TTY=4
DV.DIR=10
DV.SDI=20
DV.SQD=40
DV.MSD=100
DV.UMD=200
DV.MBC=400
DV.EXT=400
DV.SWL=1000
DV.ISP=2000
DV.OSP=4000
DV.PSE=10000
DV.COM=20000
DV.F11=40000
DV.MNT=100000

iRECORD ORIENTED DEVICE (1=YES)
jCARRIAGE CONTROL DEVICE (l=YES)
iTERMINAL DEVICE (1=YES)
jFILE STRUCTURED DEVICE (1=YES)
iSINGLE DIRECTORY DEVICE (1=YES)
jSEQUENTIAL DEVICE (1=YES)
jMASS STORAGE DEVICE (1=YES)
jUSER MODE DIAGNOSTICS SUPPORTED (1=YES)
iRESERVED
iRESERVED
iUNIT SOFTWARE WRITE LOCKED (1=YES)
iINPUT SPOOLED DEVICE (1=YES)
iOUTPUT SPOOLED DEVICE (1=YES)
iPSEUDO DEVICE (1=YES)
iRESERVED
iDEVICE IS MOUNTABLE AS F11 DEVICE (1=YES)
iDEVICE IS MOUNTABLE (1=YES)

; TERMINAL (DV.TTY)DEPENDENT CHARACTERISTICS WORD 2
i (U.CW2) BIT DEFINITIONS

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.VT5=2

iUNIT IS A MULTIPLEXER (l=YES)
iUNIT IS A DJ11 (1=YES)
iUNIT IS REMOTE (l=YES)
iUNIT DOES HRDWRE FORM FEEDS(1=YES)
JOLD NAME FOR U2.HFF
iDON'T ECHO SOLICITED INPUT (1=YES)
jUNIT IS A CRT (l=YES, ANY DV.TTY IMPLIES
i(DEL=BSP,SPC,BSP AND TERM TYP INDEPENDENT
CURS POSITIONING))
iUNIT GENERATES ESCAPE SEQ. (l=YES,ANY DV.TTY)
iUSER LOGGED ON TERMINAL (O=YES) (ANY DV.TTY)
iUNIT IS SLAVE TERM(l=YES) (RESRVD ANY
iDV.TTY)
iUNIT IS A DZ11 (l=YES)
iTERMINAL IS IN HOLD SCREEN MODE (l=YES)
(VT52)
i (RESERVED)
iUNIT IS A PRIVILEGED TERM. (l=YES, ANY
iDV.TTY)
iUNIT IS A LA30S TERMINAL (l=YES)
iUNIT IS A VT05B TERMINAL (l=YES)
A-89

UCBDF$
U2.LWC=1

iLOWER CASE TO UPPER CASE CONVERSION ON INPUT
i(O=YES)

i+
i BIT DEFINITIONS FOR U.MUP (NOT USED CURRENTLY, DV.TTY ONLY)
iUM.OVR=l
iOVERRIDE CLI INDICATOR
UM.CLI=36
iCLI INDICATOR BITS
UM.DSB=200
iTERMINAL DISABLED SINCE CLI ELIMINATED
UM.NBR=400
iNO BROADCAST
UM.CNT=1000
iCONTINUATION LINE IN PROGRESS
iCOMMAND IN PROGRESS
UM.CMD=2000
UM.SER=4000
iSERIAL COMMAND RECOGNITION ENABLED
UM.KIL=10000
iTTDRV SHOULD SEND KILL PKT ON CNTRL/C

i+
i

TERMINAL SECONDARY POOL OFFSETS FOR THE UCB EXTENSION AND

i TYPEAHEAD BUFFER
i-

U.TAPR=24
U.TTBF=46

iOFFSET WITHIN UCB WHICH POINTS TO UCB
EXTENSION
iOFFSET WITHIN UCB EXTENSION WHICH POINTS
TO TYPEAHEAD BUFFER

i+
i TERMINAL DEPENDENT CHARACTERISTICS WORD 3 (U.CW3)
i DEFINITIONS

BIT

U3.UPC=20000
U3.PAR=40000
U3.0PA=100000

iUPCASE OUTPUT FLAG
iPARITY GENERATION AND CHECKING
iPARITY SENSE (1=000 PARITY)

i+
i VIRTUAL TERMINAL 3RD CHARACTERISTICS WORD DEFINITIONS
i (DRIVER SPECIFIC)
iiFULL DUPLEX MODE (l=YES)
U3.FDX=1
U3.DBF=2
;INTERMEDIATE BUFFERING DISABLED (l=YES)
U3.RPR=4
iREAD W/PROMPT IN PROGRESS (l=YES)
i+
; TERMINAL DEPENDENT CHARACTERISTICS WORD 4 (U.CW4) BIT DEF.
i (DRIVER SPECIFIC)
;-

U4.CR=100

iLOOK FOR CARRIAGE RETURN

i+
i UNIT CONTROL PROCESSING FLAG DEFINITIONS
i -

UC.ALG=200

iBYTE ALIGNMENT ALLOWED (l=NO)
A-90

UCBDF$
UC.NPR=100
UC.QUE=40
UC.PWF=20
UC.ATT=10
UC.KIL=4
UC.LGH=3

iDEVICE IS AN NPR DEVICE (l=YES)
iCALL DRIVER BEFORE QUEUING (l=YES)
iCALL DRIVER AT POWERFAIL ALWAYS (l=YES)
iCALL DRIVER ON ATTACH/DETACH (l=YES)
iCALL DRIVER AT I/O KILL ALWAYS (l=YES)
iTRANSFER LENGTH MASK BITS

UNIT STATUS BIT DEFINTIONS

US.BSY=200
US.MNT=100
US.FOR=40
US.LAB=4
US.MDM=20
US.PWF=10

iUNIT IS BUSY (l=YES)
iUNIT IS MOUNTED (0= YES)<=CAREFUL OF
POLARITY!
iUNIT IS MOUNTED AS FOREIGN VOLUME (l=YES)
iUNIT HAS LABELED TAPE ON IT (l=YES)
i(HAS MEANING FOR DV.MNT AND
(US.MNT!US.FOR=O))
iUNIT IS MARKED FOR DISMOUNT (l=YES)
iPOWERFAIL OCCURED (l=YES).

;+
; CARD READER DEPENDENT UNIT STATUS BIT DEFINITIONS
;

US.ABO=l
US.MDE=2

iUNIT IS MARKED FOR ABORT IF NOT READY
i
(l=YES)
;UNIT IS IN 029 TRANSLATION NODE (l=YES)

;+
; DV.MSD DEPENDENT UNIT STATUS BITS
;-

US.WCK=10
US.SPU=2
US.W=l

iWRITE CHECK ENABLED (l=YES)
iUNIT IS SPINNING UP (l=YES)
iVOLUME VALID IS SET (l=YES)

; TERMINAL DEPENDENT UNIT STATUS BIT DEFINITIONS
;

US.CRW=4
US.DSB=2
US.OIU=l

iUNIT IS WAITING FOR CARRIER (l=YES)
iUNIT IS DISABLED (l=YES)
iOUTPUT INTERRUPT IS UNEXPECTED ON UNIT
(l=YES)

i+
i UNIT STATUS EXTENSION
i-

US.OFL=l
US.RED=2
US.PUB=4
US.UMD=10
US.PDF=20

(U.ST2) BIT DEFINITIONS
iUNIT 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)
A-91

UCBDF$
US.MUN=40
US.TRN=100
US.SIO=200

iMULTI-UNIT FLAG
iUNIT TRANSITION HAS OCCURRED (l=YES)
iSTALL I/O TO UNIT (l=YES)
(ANY DEVICE)

i+
i MAGTAPE DENSITY SUPPORT DEFINITION IN U.CW3
i-

UD.UNS=O
UD.200=1
UD.556=2
UD.800=3
UD.160=4
UD.625=5

UNSUPPORTED
200BPI, 7 TRACK
556BPI, 7 TRACK
800BPI, 7 OR 9 TRACK
1600BPI, 9 TRACK
6250BPI, 9 TRACK

.ENDM

A-92

APPENDIX B
TASK BUILDING AND CLUSTER LIBRARIES

This appendix provides an overview and examples of conceptual and
detailed
information on overlaying task structures and cluster
libraries for PDP-11 and RSX systems. Note that the information is
generic.
For more detail, also see the Task Builder Manual.

B.l

AN OVERVIEW OF OVERLAYING

This

discussion

of overlaying covers a complex
subject.
The
and Micro/RSX Task Builder Manual provides more detail
on the material covered here, plus information on the extended
overlaying facilities that involve mapping via the PLAS directives and
memory-resident libraries.

RSX-IIM/M-PLUS

The complexity of task structure on RSX and related PDP-11 systems
reflects both the utility and the limitations of the system hardware
and software. Over the years, users have found the PDP-11 a suitable
base for increasingly ambitious applications.
The sizes of these
applications have grown far beyond the hardware's 16-bit (64 Kbyte)
direct addressing capabilities. Therefore, task structure extensions
have evolved to meet the increased addressing needs
of
such
applications in as transparent a manner as possible.
The focus for these extensions has been the PDP-11 Task Builder (TKB),
which is a powerful, complex utility. The TKB utility is sometimes
c~iticized for its complexity.
Note, however, that it must support
run-time transparency (by and large its mechanisms must be transparent
to code execution),
structural transparency (by and large
its
structures must continue to support flexible handling of program
sections), and performance requirements (whatever it does should not
bring the task to its knees). Obviously, providing these level of
support will require some assistance from the program's designer. The
various DIGITAL products (e.g.,
language object-time systems, data
management service~ like RMS and FeS, and the Forms Management System)
each provide pre-packaged task configuration aids designed to make
task-building as automated as possible.
If application size requires
8-1

AN OVERVIEW OF OVERLAYING
further packaging efforts, however, the user must become more actively
involved in this process.
The following overview supplements the
detailed
descriptions
of overlaying in the RSX-IIM/M-PLUS and

Micro/RSX Task Builder Manual.

B.1.1

Basic Overlay Concepts and Constraints

When total program size grows beyond the virtual addressing limits of
the task "envelope," some tradeoffs must be made. Arrangements must
be made to allow currently-executing code and currently-accessed data
to reside in virtual memory while currently-unneeded code and data
reside elsewhere (typically on disk), and to allow the configuration
of resident segments to change dynamically with changing demands.
One way to accomplish the required tradeoff is with a "code cache" (in
this discussion, data segments are included with program code, since
even if are separated, they are treated analagously).
Also,
presume
that developers generate code/data segments that are sufficiently
small and modular to be easily moved, vector any external CALLs or
data references into control structures that specify the module
required, and finally, create a wholly-transparent software "paging"
scheme along the lines of VAX hardware paging.
Examining some of the difficulties with
explain the mechanism we actually use:
1.

this

approach

will

help

The major problem is the data references.
They cannot be
"caught" without interpreting the entire instruction stream
in software. This tends to defeat the purpose of the PDP-11
instruction set.
Also, despite the advantages of "clean"
inter-module data linkages,
they shouldn't be absolutely
mandatory.
If they were,
it would be necesary for us to
detect cases in which pointers to external data
(in data
structures,
the general registers, etc.) are passed as input
arguments, and vector these references as well
(possibly
through multiple levels of indirection).
The performance overhead (perhaps 100-to-1) of software
instruction
interpretation
rules out mandatory "clean"
inter-module data linkages. Also,
the goal of reasonable
coding transparency rules out the extremely strict rules on
inter-module data references that we would need without such
interpretation.
The conclusion is that data, when present,
must always appear at the same virtual address.
If the software
supports
the
"PC-relative"
hardware
addressing modes for external data, then code, when present,
also must appear at the same virtual address.
In fact,
even
without external data references it could be awkward for code
8-2

AN OVERVIEW OF OVERLAYING
to move around - consider the case of nested subroutines with
RETURN addresses on the stack.
2.

Having constant data addresses solves
only
half
the
interpretation problem.
structure conventions are needed,
perhaps supported by semi-automated mechanisms,
to ensure
that the desired data is actually resident in virtual memory
when it is referred to by an instruction.
The instruction
itself won't be able to verify this.
Any conventions, of course,
limit our flexibility
for
configuring overlaid data.
To allow for special cases, we
should consider providing an escape mechanism so that the
user code can explicitly request a data segment be loaded
prior to referring to it.

Normal external CALL and JMP transfers of control can be
intercepted
fairly
easily.
TKB
must
resolve
the
destinations, and can route them through a loading routine
that preserves the general registers and stack depth while it
demand-loads the target code segment if it is not already
resident.
Given the lack of "save/restore condition codes" instructions
in the hardware,
trying to preserve them across CALL/JMP
transfers of control would be difficult, and would increase
instruction overhead during the transfer. Transfers should
be as efficient as possible when the code segment is already
resident.
Since passing condition code information as an
input argument to an external routine is fairly unusual,
it
should be viewed as a coding restriction.
Returning condition codes as output from a CALLed routine is
not unusual,
however,
and they should be preserved.
The
easiest way to ensure their preservation is to require that
the CALLing routine remain resident while the target routine
executes.
In that way,
the RETURN requires no special
handling.
Using this approach as described,
not
only
optimizes
CALL/RETURN linkage performance, but also solves the problem
of how to re-load the CALLer transparently should it be .
displaced by the target routine.
It isn't feasible to keep
loading information describing the CALLer on the stack (since
stack depth is frequently relevant to the target routine),
and would have to maintain a special overlay run-time system
stack for this purpose. Also, some routine linkages use the
RETURN address as a pointer to in-line input arguments.
It
would be best not to tamper with it.

8-3

AN OVERVIEW OF OVERLAYING

8.1.2

Other less common transfer-of-control mechanisms include
coroutines and tables containing external dispatch addresses.
Some of the same issues mentioned above apply to them.
It
may be reasonable to restrict generality of support for such
linkages, but be certain you understand what is entailed.

Even creating vectoring information for just the external
CALL/JMP references could result in very large vector tables,
which in turn would increase pressure on the very virtual
memory resources we are trying to conserve. Instead of
"paging" on a module-by-module basis, it is better to provide
a way of grouping related modules together so that (a)
references that occur within the group need not be vectored
at all (the group is "paged" as a unit), and (b) a single
structure descriptor can serve the entire group (though
individual vectors will still be needed for each entry point
referred to externally).

Another good reason to page related modules as a group is
that performance will degrade if many small modules are
"paged" individually, as several short disk "read" operations
typically take much longer than a single long "read" of
equivalent content.

The Overlay Structure

Our main implementation constraints so far are thus:
o

To support the way the hardware performs data references in
executing instructions. When a given segment of code or data
appears in the overlay cache area, it should always appear at
the same virtual address.

To support frequently-used subroutine linkage mechanisms.
The CALLing routine should remain resident while the CALLed
routine executes.

To achieve reasonable performance. Groups of related modules
should be pageable as single units ("overlay segments"). The
vector table overhead is minimized, since purely intra-group
references need not be vectored.

B.1.2.1 Overlaying Code Segments - The requirement stated in Section
8.1 above that CALLers remain resident in the "code cache" while the
target routine executes, plus the desirability of allowing CALLed
8-4

AN OVERVIEW OF OVERLAYING
routines to be nested, means that the logical structure for organizing
code segment overlays in virtual memory is a "tree".
With such a tree structure, the "root" of the tree is not overlaid.
It permanently resides at a fixed location in the task's virtual
address space. Routines in the root may CALL routines in one of the
multiple overlay segments in the first level above the root level.
(They may of course CALL other routines in the root level as well.)
When a Level 1 routine is CALLed in this manner, TKB has actually
caused the CALL to be redirected to an "autoload vector" in the root
segment.
This vector passes a "segment descriptor" address (in the
root segment) plus the virtual address of the target routine within
that segment to a common "autoload" routine in the root segment's
overlay run-time system. This system uses the segment descriptor
information to load the segment into virtual memory, if it is not
already resident, and then passes control to the real target routine
as if it had been CALLed directly.
One autoload vector can service all references from the root to a
single Levell routine. A single such segment descriptor can service
all references to all routines in a single Level 1 overlay segment.
Each routine in Level 1 may in turn CALL routines in the overlay
segments directly above its segment in the second level of the
structure, as well as routines in its own overlay segment.
Each Level
1 to Level 2 CALL is similarly redirected through an appropriate
autoload vector, which resides in the Levell segment rather than in
the root.
Therefore, use of valuable non-overlaid virtual memory
space in the root will not be affected.
Note that while a routine in the root may CALL routines in any Level 1
segment,
a Level 1 routine may CALL only the sub-set of Level 2
routines directly above its segment.
Other Level 2 routines
(and
routines in other Levell segments) are inaccessible and invisible to
it, because of the "CALLer must remain resident" requirement that led
to the tree structure and the rules for its use.
A sample 4-level overlay tree is diagrammed below. Each entity marked
with brackets []
(except the root)
represents an overlay segment
containing potentially multiple routines in multiple modules.
The
segment names are arbitrary, but useful, for the discussion.

B-5

AN OVERVIEW OF OVERLAYING

Level 3
Level 2
Level 1
Root Level

[AB]
[CAl [CB] [CC]
/
\
1 /
[A]
[C]
\
/
1
[non-overlaid portion of the task]

[AA]

[BBA] [BBB] [BBC]
\1 /
[BA] [BB] [BC] [BD]
\
1 1 /
[B]

Before analyzing transfers of control in this structure,
is advisable to look at two possible extensions:
o

however,

The "CALLer must remain resident" rule, when applied to
subroutine nesting, implies that whenever we are executing
within an overlay segment, all lower segments along the
"path" from that segment to the root are also resident. For
example, if executing in segment BBC, then BB, B, and of
course the root are resident.
There is no reason not to
allow a routine in segment BBC to CALL routines in BB, B, and
the root - and CALL them directly, without vectoring. This
is a "down-tree" CALL.
.
Such "down-tree" CALLs are allowed, but are conditional. For
instance, assume a BBC routine CALLs a BB routine. Before
RETURNing to the BBC routine, the BB routine MUST NOT itself
CALL "up-tree" (as it would normally be able to do had it not
been CALLed from above). If the BB routine CALLed aBBA
routine, for example, the BBA routine could successfully
RETURN to the BB routine, but when the BB routine then
RETURNed to the BBC routine it would find the BBA segment
resident instead of the BBC segment. Since the program could
not detect this, the program would quickly run into trouble.
In other words, CALLing up-tree presents no problems, but
when
CALLing
down-tree, watch out for nested up-tree
excursions that would violate the "CALLer must
remain
resident" rule.

While it is reasonable to .distribute autoload vectors into
the overlay segments that actually use them, it is awkward to
distribute segment descriptors in the same manner (e.g., with
sharable
and/or
read-only
PLAS-mapped
memory-resident
libraries).
Therefore, you should
place
all
segment
descriptors in the task root segment. Given their typical
size and numbers, they should present no problems.
Placing task root segments in the segment descriptor allows
you to relax the requirement that up-tree CALLs go up just
one tree level. You link the segment descriptors into an
actual tree structure that mirrors the conceptual overlay
B-6

AN OVERVIEW OF OVERLAYING
tree. Then you modify the autoload routine to load ALL
segments on the path between the CALLer and the target.
Thus, for example, when a "B" segment routine CALLs a "BBB"
segment routine, the CALL is redirected to an autoload vector
in the B segment that specifies the actual target virtual
address plus the segment descriptor address of the BBB
segment. The autoload routine then checks to see if BBB is
resident and, if not, loads the BBB segment and works its way
down the segment descriptor tree toward the root, loading
additional segments as necessary.
Under the assumption that a segment is resident only if all
lower segments on the path between it and the root are also
resident, this approach should achieve the desired result.
However, to guarantee that assumption, the autoload routine
must mark all segments that do not share the new path
non-resident, even if some of them do not conflict with the
virtual memory used by the new path.
This ususally has
little
effect
upon
the overlay cache, since overlay
configurations frequently conflict. Cases to the contrary
can often be optimized through use of the co-tree structures
discussed below.
The previous description of
translate into the following:

the

basic

code-overlaying

mechanisms

Any "node" (overlay segment) in the tree can "see" and CALL
directly all routines in the same node and in any lower nodes
that lie on the path between it and the root.

Any node in the tree can "see" and CALL indirectly (through
an autoload vector) all routines in nodes directly above it
in the overlay tree. In our sample tree, a routine in node B
could CALL routines in any node whose name begins with B but no node whose name begins with A or C. A routine in the
task root can clearly CALL routines in any node in the
structure.

Except as discussed in the first two items above, nodes
cannot "see" (or CALL) each other. You may normally place
routines with the same globally-defined entry point names in
nodes that cannot see each other without conflict. However,
if a reference to such a duplicated entry point is made by a
lower node which can "see" both instances of it, TKB cannot
determine which node should be used to satisfy the up-tree
CALL and will generate a diagnostic message indicating the
ambiguity.

B-7

AN OVERVIEW OF OVERLAYING
4.

Down-tree CALLs should always be carefully examined
nested up-tree CALLs that would displace the CALLer.

Any use of overlays at task AST (asynchronous) level also
runs a risk. The task-level overlay context could easily be
changed "underneath" the running code.
Isolating segments
used at AST level from those used at task level in separate
co-trees is one possible way to avoid this. A few products
such as RMS-11 have special asynchronous versions with
internal controls that allow mixed task/AST level operation,
but most do not.

Wherever a CALL is specified in the above list, a JMP
usable.

would

for

also

B.1.2.2 Making the Tree More Flexible - The structure described above
works well for applications that fall naturally into tree-structured
organization of control flow. Though applications in many cases do
lend themselves to such organization, and in many others can be made
to comply with minimal changes, there are times
when
strict
tree-structuring imposes significant penalties in use of task virtual
address space and/or task image size on disk due to excessive module
duplication throughout the structure.

One way to add flexibility to the available control flow mechanisms is
to build some explicit extensions into selected portions of the code.
For example, suppose that the Faa routine in node BBC of our sample
tree would benefit from access to the copy of the BAR routine in node
AB of the tree. We could legally just duplicate the BAR routine in
node BBC (as long as the root does not CALL BAR, since duplicating BAR
would then result in an ambiguous up-tree reference), but if BAR is
very large this could be awkward. Instead, however, we could create
the following "cross-tree" transfer mechanism:
[Faa routine in node BBC]
(Normal initial Faa code)

Faa: :
JMP

BAR1

F002: :

(We would normally CALL BAR
(Remainder of the Faa code)

[Special transfer routine in the root]
BAR1::

CALL
JMP

BAR
Faa2

B-8

here)

AN OVERVIEW OF OVERLAYING
The result of this is that FOO legally JMPs to the BARl transfer
routine (which must be low enough in the tree so that both FOO can see
it and it can see BAR), BARl legally CALLs BAR, BAR legally RETURNs to
BAR1, and BARl legally JMPs back to the proper point in FOO. The
stack depth has not been affected by this indirection.
For high-level languages that do not permit coding such a sequence
directly, one could add a second special MACRO-ll transfer module in
the CALLing overlay segment that JMPs to BARl and then RETURNs after
the root module JMPs back to it, and CALL this second module from the
high-level language code. Though such a linkage does not preserve
stack depth, due to the added CALL, it will be suitable in many cases
(e.g., routines that communicate using the "standard" PDP-ll R5
CALLing sequence).
While inelegant in some ways, the approach as described is a
reasonable way to avoid excessive module duplication and reduce
virtual address space use by effectively allowing a CALLed routine to
displace its CALLer.
One must of course be willing to accept the
performance overhead of loading the target (plus any non-resident
lower nodes) on every CALL and reloading the CALLer (plus any
displaced lower nodes) on every RETURN, but for infrequent operations
this may well be tolerable.
One must also ensure that the target
routine does not require access to any data (or codel) resident in the
portion of the tree that is displaced when the target is loaded, but
again for restricted use this may not be a difficult limitation.
Finally, remember that the condition codes are not preserved through
the RETURN to FOO in this case.

B.l.2.3 Co-trees - TKB makes another mechanism available for further
control
over
use
of
the overlay cache area:
the co-tree.
Conceptually, co-trees allow division of the cache into independent
segments that do not affect each other.
In effect, they become
multiple tree structures, each of which functions independently of the
others.

Since overlay activity in one tree does not affect the others, all
.nodes in each tree can "see" all entry points in all other trees just
as if these entry points were in the root segment (though the CALLs
must still be vectored through the autoload mechanism). Thus a CALL
to a different co-tree is much like a "down-tree" CALL.
In
particular, you must ensure that any nested CALLs back to the
originating tree's code do not change its overlay context such that
the CALLer becomes non-resident (the RMS-ll user-provided "get-space"
routine feature is an example of such a "CALL-back" situation that
must be handled with care).

B-9

AN OVERVIEW OF OVERLAYING
The Task Builder's normal processing of the default object module
library (typically SYSLIB)
is designed to avoid occurrences of such
inter-co-tree CALL-back situations in cases where their existence
would not be obvious due to the implicit natu~e of the references.
The /FULL switch may be used
with caution
to override this
behavior when necessary.
Because each co-tree must reserve its full complement of virtual
memory all the time, co-tree structures may be somewhat less efficient
in use of virtual memory (though more efficient in use of disk space)
than equivalent-function single-tree structures with increased module
duplication. The Task Builder Manual's descriptions and examples of
overlaying provide insights into optimizations and trade-offs among
virtual memory, task image size on disk, and performance for singleand multiple-tree structures, as does the RMS-11 "prototype" ODL file
RMS11.0DL for specific cases involving the RMS-11 co-tree.

B.1.2.4 OVerlaying Data - At the
beginning,
we
decided
that
intercepting
data
references
would
have
required on-the-fly
interpretation of the instruction stream with prohibitive performance
and complexity cost.
For this reason, all overlaying of data is left
to the user to do correctly.
TKB does, however, provide the tools for overlaying data.
Data
program sections (PSECTs) can be given the "local" attribute, in which
case they will be placed in the overlay segment where the module
containing them occurs. As long as such data is referred to only by
the code in that segment (or, optionally, by code in segments directly
above that segment in the tree structure), all should go well.
If
referred to by lower segments in the tree, or by segments in other
trees,
there is no guarantee that the correct data will be resident,
and the user is responsible for avoiding such references.
(Data may also occur in-line with code, though this is normally not
considered good programming practice.
Such data acts much the same as
data in a "local" PSECT.)
When a data PSECT is given the "global" attribute, on the other hand,
TKB merges all contributions to that PSECT on a given path downward so
that they in fact occur in the lowest segment on that path in which
any contribution to that PSECT is made. Thus all segments that make
contributions to that PSECT may freely refer to it in its entirety
without the danger of up-tree data references. Note, however, that
there is still no active protection against reference from lower in
the tree.

8-10

AN OVERVIEW OF OVERLAYING
A common programming error involves mixing local and global PSECTs
that have the same name.
Since the attributes differ, they are
treated as different PSECTs, and the local portions are not merged
with the global portions.
TKB recognizes use of routine addresses as data just as it recognizes
any up-tree CALL-type reference.
In a CALL or JMP table, for example,
an entry of the form .WORD Faa will be correctly resolved to an
autoload vector when the routine is up-tree (or in another tree) from
the reference to it. TKB has one unfortunate idiosyncracy in this
area:
when an up-tree module makes a contribution to a global data
PSECT that is forced down-tree to the lowest node in which references
to this PSECT occur,
any autoload -vectors associated with this
contribution are placed in the up-tree module's segment rather than in
the lower segment in which the reference actually winds up.
Thus if a
lower node refers to such a contribution, there is no guarantee that
the required autoload vector will be resident, and the results can be
both surprising and difficult to
diagnose.
Thankfully,
such
situations seldom occur in normal use of the overlay facilities.
Finally, TKB allows explicit loading of up-tree data segments via use
of the
. NAME directive and a "dummy" CALL. This can be useful when
large amounts of data must be referred to under program control.

B.2

CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS

Library clustering retains the performance and ease-of-development
advantages associated with use of memory-resident libraries, allows
more flexible and efficient use of physical memory by RSX-11M-PLUS and
RSTS/E operating systems,
and competes favorably with disk overlay
structures in use of task virtual memory.
This discussion reviews and supplements the extensive description in
the Task Builder Manual, which covers much of this material in
slightly different, and sometimes more detailed, form.

B.2.1

Simple Task Structure and Memory Mapping

The 16-bit byte-oriented architecture of the PDP-ll presents the user
with 32 KW of addressable memory in the address range 0 to 177777
(octal).
In multiprogramming systems, the operating system uses the
memory management hardware to map this range of VIRTUAL addresses (as
seen by the task)
onto one or more ranges of PHYSICAL memory
locations, and to ensure that the physical memory associated with each
task is suitably protected from unauthorized use by other tasks.
This
mapping is established through eight hardware Active Page Registers
(APRs), each of which controls the mapping and protection of up to 4
B-11

CLUSTER LI8RARIES AND THEIR USE IN APPLICATIONS
KW of task virtual address space, beginning on the appropriate 4 KW
virtual address boundary. The APR specifies the start address in
physical memory and the size of the task section (both in units of
32-word blocks, the mapping granularity).
The simplest structure is one in which task virtual memory maps onto a
continuous series of physical memory locations, as illustrated in
Figure 8-1. As shown in the figure, the task does not require a full
32 KW of physical memory, and APRs 5, 6, and 7 are set up to reflect
the limits of the task memory envelope. Mapping need not be static.
If the task is checkpointed to disk to give another task an
opportunity to use the physical memory, for example, it may on return
occupy a different area in physical memory. If the task requests more
space from the operating system, it will acquire access rights to
additional physical memory.
The physical memory associated with a task may, in fact, exceed 32 KW,
under software control of the operating system. The virtual memory
mapped under hardware control at any instant, however, can never
exceed eight "pages," each a maximum of 4 KW in size, and each
beginning on a 4 KW virtual address boundary.
This ignores systems
that support supervisor mode mapping and instruction/data space
separation in user tasks - these extend addressable virtual memory
through use of the additional APR sets available on PDP-ll/70 and
PDP-ll/44 processors.
For large applications, 32 KW may be inadequate to contain all the
necessary code and data for a task. The traditional solution is to
overlay the task code. This breaks it up into segments, which are
loaded on demand from disk and replaced with other segments when no
longer needed. Such disk overlaying (which decreases task performance
due to the extra disk I/O overhead) is performed under software
control of the task's integral overlay run-time system.
Overlay
segments can be loaded at any word-aligned virtual address boundary.
They do not change the virtual-to-physical mapping of the task in any
way.

8-12

CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS

PHYSICAL MEMORY
TASK VIRTUAL
MEMORY

Pt1YSICAL
ADDRESS
(octal)

VIRTUAL
ADDRESS
(octal)

APR 5

....
~

464000

330000

12(1000
APR 4
1110000

APR 3
60000
APR 2
411000

APR 1
211000

APR 0
0

Figure 8-1:

Simple Task Structure and Memory Mapping

8-13

CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS
8.2.2

Libraries and Virtual Address Windows

Having eight APRs to work with, a task can map to as many as eight
disjoint
sections
of
physical memory (und~r operating system
supervision, of course). Intermediate software structures called a
Virtual Address Windows in the system- controlled task header describe
each such disjoint section.
The example described in the previous section had the entire task
contained in a single continuous section of physical memory, and hence
required only a single window (Window 0). As illustrated in Figure
B-2, however, Task A has been linked to Library A, a memory-resident
library. Since there is no guarantee that the two wilY be loaded into
adjacent
sections of physical memory (or that they will have
equivalent hardware protection requirements), two virtual address
windows are needed. Window 0, as always, maps the task itself, using
APRs 0 through 4; the task is permitted both read and write access to
this section of memory. Window 1 maps the library using APRs 6 and 7;
typical libraries will allow only read access by tasks. Since APR 5
is not currently in use, the task could dynamically extend itself into
this virtual address range (libraries are conventionally mapped in the
highest available APRs to facilitate this), or could dynamically
create an additional virtual address window to map APR 5 to some other
portion of physical memory if space for a third window in the task
header was specified when the task was built.

B-14

CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS

APR 4
APR 3

TASK
WINDOW

APR 2

TASK

A
APR 1
APR 0

Figure B-2:

Libraries and Virtual Address Windows

B-15

CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS
8.2.3

Library Sharing and Multiple Libraries

Figure B-3 illustrates a more complex (and more typical) case, with
multiple tasks and libraries resident in physical memory at the same
time.
Task A is still mapped to Library A as before. Task B is also mapped
to the same physical copy of Library A. One of the benefits of using
sharable re-entrant memory-resident libraries - rather than linking
the library code into each task that uses it - is the saving in
physical memory use that sharing allows. If the code were resident in
the tasks, however, it might be possible to overlay it from disk.
ThiS would cut down on per-task physical memory requirements and
increase the amount of virtual memory available for the rest of the
code in the task (but also decrease performance due to the additional
I/O to disk required for task execution).
Whereas Task A maps Library A in APRs 6 and 7 (base virtual address
140000), Task B maps Library A in APRs 4 and 5 (base virtual address
100000). This can be done only if the code in the library is
position-independent (PIC - descriptions of position-independent code
and re-entrancy can be found in the PDP-11 Processor Handbook).
The
fact that both tasks use Window 1 to map the library is coincidental.
Task B is also mapped to Library B.

Two areas are worthy of note:

It is fortunate that Task B is small.
The two libraries
combined take up fully half the available virtual address
space (by using four APRs between them). Task A is too large
to be able to map to both libraries simultaneously. If their
code were instead disk-overlaid within Task A, there might be
room for it, though performance would suffer and the code for
Library A would no longer be sharable.

Whenever Task B is in memory, both libraries must also be in
memory.
A region is forced into physical memory whenever an
in-memory task maps any portion of it, and Task 8 cannot run
unless 25 KW of physical memory is available - a 9 KW block
for the task itself, and an 8 KW block for each library.

8-16

CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS

18SK 8

LIB

APR 7

TASK A

APR 6

WINDOW 1

LIB

18SK B

WINDOW 2

APR 7

APR 6

TASK B

WINDOW 1

APR 4

APR 5
APR 4

APR 3
TASK A

TASK
A

WINDOW f1

A P"R 2
APR 1

APR 1

APR 0

APR f1
4

WINDOW f1

TASK

Figure B-3:

Library Sharing and Multiple Libraries

B-17

CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS
8.2.4

Library with Memory-Resident Overlays

The RMS-ll Vl.8 full-function memory-resident library RMSRES is an
example of code which, for reasons of performance, and sharability, is
configured as a (re-entrant, position-independent) library but, for
reasons of size (about 23 KW), cannot reasonably be mapped "flat-out"
by tasks.
The Task Builder allows such large libraries to be
"resident-overlaid," using the Program Logical Address Space (PLAS)
directives to map within the library region. The mapping operation is
far less time-consuming than a disk overlay operation. with RMSRES,
one APR is continually mapped to common support code in the library
"root," and a second APR is used to map whichever library "leaf"
segment is currently in use (there are five of these).
Even though
the library is contained in a single region, the code is mapped in two
often discontinuous pieces, therefore an additional window is required
in the task.
This approach consumes only 8 KW (two APRs) of the task's virtual
address space, while giving the task the benefit of 23 KW of
(sharable) support code.
This all happens with no disk overlay
performance penalty
though disk-overlaid RMS can be contained in
about 5 KW per task virtual/physical memory. Despite the fact that no
more than 8 KW of the library is mapped by a single task at anyone
time, the entire library must be resident in physical memory when any
portion is mapped by a resident task, since regions cannot be loaded
piecemeal.
In Figure B-4, a single task is using both RMSRES (mapping to an
arbitrary "leaf" segment is shown) and the 7 KW DIBOL memory-resident
library - which is not PLAS-overlaid. Two points are worth noting:
1.

The two libraries again consume half the available task
virtual address space.
Even though the DIBOL library is
smaller than 8 KW, the fact that it exceeds 4 KW means that
two APRs are needed to map it. While the physical memory
required is 7 KW, the virtual memory impact on the task is 8
KW.
The "extra" 1 KW at the "top" of APR 5 is not available
for use by the task. No other task window can be mapped to
it, as it does not begin on an APR (4 KW) address boundary_
Similar smaller unusable virtual address ranges can be found
at the top of both of the APRs (6 and 7) used to map into
RMSRES. The unused 1 KW at the top of APR 3, however, could
be used by the task if necessary. It is continuous with the
task region, and task Window 0 could be extended to include
it.

To run at all, the task requires 45 KW of physical memory (15
KW for the task itself, 23 KW for RMSRES, and 7 KW for DIBOL,
in continuous blocks).

B-18

CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS

//~

R
M
SR
ES
APR 7

----

-~--

APR 6

Av
ES)

APR 5
APR 4

(Roor)

WINDOW

1
APR 3

D I B0 L
APR 2
WINDOW

APR 1
APR fI

TASK

·V/ /~,
Figure 8-4:

Library With Memory-Resident Overlays

8-19

CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS
8.2.5

Clustered Libraries

AS described in the previous section, multiple libraries are good for
performance and potential sharing of physical memory, but not so good
for task virtual address space, and
m1n1mum
physical
memory
requirement (at least when only a single task is using the libraries).
More flexibility is needed - and POP-ll task structure provides it in
the window mechanism.
Windows are not statically associated with
specific regions. They may be created and deleted as needed, at
relatively low performance cost. In particular, when two libraries do
not interact directly with one another (i.e., they do not need to be
mapped simultaneously), they may alternately make use of the same task
virtual address space (APR) range under control of the task's integral
overlay run-time system.
As Figure B-5 illustrates, this structure presents the same task
configuration as discussed in the previous section. NOw, however, RMS
and OIBOL share the same two APRs (6 and 7). At the moment, OIBOL is
mapped by the task, and RMS is not. Because of this, RMS need not
occupy physical memory (unless some other resident task is mapped to
RMSRES), and the instantaneous physical memory requirement for the
running task drops from 45 KW to 22 KW. If an RMS request occurs, of
course, RMSRES must be mapped. However, OIBOL must first be unmapped,
and hence again the instantaneous physical memory requirement is
reduced (38 KW vs. 45 KW).
Thus, the task can run in as little as 38 KW of physical memory,
though if there is less than 45 KW (appropriately distributed) RMSRES
and OI80L will "swap" against each other, resulting in disk I/O
similar to overlaying.
The effect is to use the physical memory
controlled by the operating system as a code cache. When the supply
is plentiful, performance approaches the optimal multiple library
case. When memory gets tight, performance degrades gradually as disk
I/O activity relieves the pressure (and improves again dynamically
when more physical memory becomes available).
Additional libraries
(such as an FMS library) may be added to the cluster as long as the
rule that all are independent of each other is followed.
In such a
case, the minimum physical memory requirement is unaffected unless one
of the libraries added is larger than the previous largest library in
the cluster.
P/OS and RSX-l1M-PLUS systems allow the most dynamic use of memory, as
described above.
RSTS/E systems tie libraries to specific areas in
physical.memory, but allow use of this physical memory for other
purposes when it is not required by the library that "owns" it.
RSX-llM systems do not support demand region loading, and hence do not
experience any reduction in required physical memory. All libraries
must always be resident.

B-20

CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS
Also, the largest VIRTUAL address space requirement of any library in
the cluster is all the user task sees. RMSRES, OAPRES (the library
supporting RMS remote access via DECNET), FMS, and OIBOL can,
for
example, all share the same 8 KW (two APRs) of task virtual address
space.
~his
was,
in fact,
the original impetus
for
library
clustering.
The advantages in using physical memory were recognized
later.

B-21

CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS

RM
SR
ES

---

fI;- (Task

APR 7
~

APR 6

_-'t

------

Window 2)

+----

(Task
Window 1)

E
AV

ES)

--~

(ROOr)

4-- ____

TASK - - - - - - - ~
WINDOW 1

DI B0 L

(

APR 3
TASK

APR 2

WINDOW

TASK

APR 1
APR 0
'(

Figure 8-5:

Clustered Libraries

8-22

CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS
8.2.6

Cluster Libraries - Implementation Detail

The library clustering mechanism is implemented as an extension to
existing Task Builder overlay structures. To the overlay run-time
system, a library cluster resembles a null-rooted PLAS- overlaid
co-tree, with each library a sub-tree. with the optional exception of
the first library in the cluster, each of these sub- trees must itself
have a null root.
This structure simply aids the TKB in using its
normal tree processing mechanisms to build the task structure.
When the first library in the cluster has a non-null root segment, TKB
builds the task such that the loader will load and map this library
root when the task itself is loaded.
Thereafter, the task-r~sident
overlay run-time system keeps watch over the co-tree mapping. If a
reference into the library cluster causes its APR mapping to change
from one library (region) to another, the mapping context for the
displaced library (region) is saved on the stack and is restored upon
exit from the newly-called library.
The first library in the cluster (assuming it has a non-null root) is
always the initial library mapped.
Therefore, any reference to
another library in the cluster will always displace it, and it will
always be re-mapped on exit. It is thus termed the "default" member
of the cluster, for two reasons. First, mapping reverts to it when no
other library has a routine in progress, and second, references made
to it normally do not require any "push-down" mapping context to be
saved on the stack - since the reference will not normally displace
one of the other libraries' mapping.
In other words, the default
member of the cluster may usually be treated by the task just as if it
were a non-clustered library.
TKB takes advantage of this by
suppressing generation of overlay run-time system autoload vectors for
references to the non-null root of the default cluster member.
The
four words per root entry point saved by such direct addressing can be
significant for default libraries with large numbers of entry points
in the root - such as language OTS libraries. (If such libraries have
PLAS-mapped "leaves" above the root, reference to entry points in the
leaves will be autoload-vectored as usual).
If all libraries in the cluster have null roots, the first library to
be called by the task takes the role of the default member of the
cluster. Once it has been mapped, any reference to another cluster
member will displace it, and restore its mapping on exit. Since it
(as well as the other libraries) has a null root, autoload vectors
will be generated for ALL entry points referenced by the task.
Note that this implementation does not require that all libraries in
the cluster use the same number of APRs or the same number of virtual
address windows. It does require, however, that they all be mapped,
starting at the same task virtual address (APR boundary). This, in
turn, means that all member libraries in a cluster must either be PIC,
or Juilt at the same virtual address.
8-23

CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS
8.2.7

Summary arid Implications

Understanding how cluster libraries work makes it easier to understand
(and remember) how to design and use them properly. To summarize:
o

Library clustering allows tasks to use the same virtual
address space range (APRs) for multiple purposes (leaving a
larger range of virtual address space free for other use),
while retaining the ease-of-development and code-sharability
features of normal memory-resident libraries.
There are two costs associated with use of cluster libraries:
1.

The overlay run-time system and its data structures
(several hundred words total) must be built into the root
of your task. If your task already required the overlay
run-time system for other reasons, the additional size
increase is relatively small.

A reference to a non-default member of the cluster causes
mapping/re-mapping operations to occur.
The typical
overhead is 2-10 milliseconds per reference (far less
than
a
typical disk I/O operation), depending on
processor speed and the number of windows in the affected
libraries.

Library clustering allows P/OS, RSX-11M-PLUS and RSTS/E
operating systems to make more flexible use of physical
memory, since a task maps only one library at a time.
When
memory is in short supply, a task may be able to run (albeit
more slowly) which could not run at all if the libraries were
not clustered. When a library is not mapped for long periods
of time, the physical memory may be put to other use.

Library clustering is not transparent to the libraries in the
cluster.
They must make no direct reference to each other
(see below), and any which are not PIC must be built at the
same starting virtual address.

Library clustering is not fully transparent to the user task:
1.

The nature of the "push-down" mapping mechanism requires that
any CALL into the cluster be of the form JSR PC, ...
(rather
than, for example, JSR R5, ... ). While JMPs into the cluster
are acceptable, co-routine linkages are unacceptable.

8-24

CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS
2.

In general, the task must access the cluster only as
described above.
The task must not "remember" virtual
addresses within the cluster, and cannot use the . NAME
facility to load library data tables.

Since push-down mapping affects the stack depth, parameters
may be passed on the stack across the task/cluster interface
only if an argument pointer is used.

The above three restrictions are relaxed only in the case of the
default member of the cluster, and only then when it is known that no
other member is currently "pushed down" on the stack (see next
section) .

8.2.8

Inter-Library References and Miscellaneous Points

That completes this description of how clustering works and what its
limitations are. One of the limitations clearly needs a work-around.
For example, a language or FMS library needs access to the FCS or RMS
library for file access, and to say that such combinations cannot be
clustered is just not acceptable.
Any work-around is not a part of the clustering mechanism per see
It
is a cooperative effort on the part of the interacting libraries. FCS
and RMS, for example, both provide linkage routines (modules FCSVEC
and RORMSC, respectively) which must be built into any library whose
code contains direct references to the FCS/RMS functions (e.g.,
OPEN$/$OPEN).
These special modules field any FCS/RMS request made
within the library and pass it - using the low-core absolute linkage
to the FCS or RMS task-resident impure area - to another FCS or RMS
routine which exists in the task itself. This routine then calls into
the FCS/RMS library, thus avoiding any direct inter-library call. (In
the case of FCS, the "routine" is simply a JMP through an autoload
vector.)
Note, however, that the FCS/RMS global entry point symbols now appear
in the calling library's symbol table. They will be visible to the
~ser task, unless the calling library is built with .GBLXCL statements
for each such symbol. Since it is not normally desirable to "vector"
RMS references from the task through some intermediate library, the
.GBLXCL mechanism is generally appropriate. In the case of FCS, it is
mandatory, as these same symbols are used as the entry points to the
FCS library and will conflict if not suppressed.
The mechanism described above is equally useful for non-clustered
libraries which need access to FCS or RMS without being bound to
specific external routine entry points.
This is independent of
whether the FCS/ RMS code is task-resident or in a library of its own.
An alternative approach is for the calling library to invoke a service
B-25

CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS
routine of
directly.

its

own

the

task, which then dispatches to FCS/RMS

Finally, the calling library must contain nothing (data structures,
file specification strings, etc.) that the FCS/RMS library needs to
"see" in the execution of its duties. This is the caller's end of the
bargain.
RMS completion routines are called from the in-task RMS
linkage code after exit from RMSRES, and hence may be present in the
caller's library (which has by then been re-mapped). "Get space"
(GSA) routines provided by the user are called with the RMS library
mapped, but will execute correctly regardless of location provided the
address given to RMS reflects an in-task autoload vector (the RMS
mapping will be "pushed down" if necessary to map the GSA routine, and
will be restored transparently on GSA routine exit).
This last situation reflects one of the potential pitfalls of
"default" libraries.
If such a library is clustered with RMS and
provides a GSA routine address in its (non-null) root segment, when an
RMS operation is performed, the callout of RMSRES to the GSA routine
will, in fact, transfer control to some random location within the RMS
library. This is because the default member is not mapped at the time
and the overlay run-time system is not invoked on the reference (no
autoload vector was generated). There are three possible remedies:
1.

Place the GSA routine in the task rather than in the library.

Place the GSA routine in a PLAS-overlaid "leaf" of the
default library - whose entry points are autoload-vectored.

Build the first library as the other cluster members with a
null root - which will force autoload vectoring throughout.

A situation similar to the above applies to synchronous traps.
Any
trap service routine in the cluster must be suitably autoload-vectored
through the controlling task, as the routine may not be mapped at the
moment the trap occurs.
At present, the overlay run-time system's
handling of its data structures is not suited to any use of overlaying
during asynchronous trap processing unless it is the only time
overlaying occurs. An enhancement is under development, and when it
appears, asynchronous trap servicing may be handled as described for
synchronous trap servicing.

8.2.9

WRITE Access to Clustered Libraries

For P/OS Vi.7, the overlay run-time system has been modified to allow
write access to (non-"default") clustered libraries that have not been
installed read-only.

8-26

CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS
Such libraries may be useful for the following purposes:
o

Passing information between cooperating application tasks
(the tasks should provide their own access synchronization)

To extend the effective available read/write
usable for task impure data

virtual

memory

In both cases, the task(s) must ensure that the library is mapped by
calling a routine in the library that does not RETURN to the caller
until any access to the read/write data is completed.
This is not
normally necessary for a non-null-rooted 'default' cluster member,
since it is usually already mapped as desired.

B.2.10

NULLIB

The special non-null-rooted default cluster member NULLIB was provided
in previous P/OS releases for two purposes:
o

to guard against potential memory fragmentation problems that
might cause task deadlock in certain instances.

to provide better performance in cases when a null-rooted
cluster member would otherwise become the 'effective' default
member of the cluster and would be re-mapped (and potentially
re-Ioaded
from
disk)
unnecessarily.
Assuming
that,
typically, the application would access other cluster members
than the first one accessed, re-mapping that first member
after every access to some other one could prove costly.

physical memory now standard for P/OS makes the memory
fragmentation problems considerably less likely for most applications.
Also now that the RMSRES and POSSUM resident libraries are fixed in
memory, there is no possibility of disk loading overhead when one of
these becomes the effective default member of a cluster.
The~ncreased

AS a general rule, when all members of a library cluster have null
roots, the application should attempt to ensure that the first library
accessed (which will become the effective default cluster member) is
the one that the application will refer to most frequently. This will
minimize the likelihood of unnecessary mapping and possible disk
loading.

8-27

OPTIONS IN TASK ORGANIZATION

B.3

OPTIONS IN TASK ORGANIZATION

The following examples have been chosen to demonstrate the options for
organizing a task which needs to use the following PIOS services:
RMS, Callable System Services (POSSUM), and User Interface Services
(POSRES).
o

Option 1:

FLAT.TSK

Completely flat task structure. All task modules are in a
single segment.
The three resident libraries are mapped in
their own APRs.
Advantages:
Easiest taskbuild command file to construct. No
special attention has to be made to placement of data.
Less
mapping activity necessary.

Disadvantages:

Most costly in terms of virtual memory space.

Option 2:

CLUST.TSK

Task region is a flat structure.
clustered against each other.

The resident libraries

are

APR

required

Advantages:
Because the
resident libraries
mapping, other APRs are freed for task use.
Disadvantages:
More
runtime services.
o

Option 3:

mapping

and

unmapping

VECTOR.TSK

Task space contains minimal code.
Most code has been
relocated to a user-written cluster library (USRRES).
This
library is clustered against RMSRES,
POSSUM,
and POSRES.
Data required by USRRES must reside in task address space.
Advantages:

Even more address space available in task area.

Disadvantages: More difficult to organize task code and
data.
A vectoring scheme must be implemented for library
data references and subroutine calls from one library in the
cluster to another.
Extra mapping and unmapping by the
~verlay runtime system.
o

Option 4:

OVERLAY.TSK

Task itself is overlaid. All code and data which are needed
to call RMSRES,
POSSUM, and POSRES reside in one branch of
the tree.
Code not using these libraries is overlaid against
code using libraries.

B-28

OPTIONS IN TASK ORGANIZATION
Advantages: Extends task virtual address space considerably
because code/data for library references are removed from
root segment of task and are consequently able to be
unmapped.
Disadvantages: More complicated .ODL file.
Requires some
knowledge of library-specific requirements. Requires logical
separation of functionality.
Implementation details follow.

8-29

OPTIONS IN TASK ORGANIZATION

8.3.1

FLAT.TSK

This is the simplest structure to concoct.
In a flat task structure,
task
control
can
be
directly transferred to mainline code.
Nevertheless, the example uses the control module ROOT in order to
provide a basis for comparison with the alternative options.

B.3.1.1

FLATBLD.CMDcontrol mainline
module
code

RMS,POSSUM
& POSRES
data
FLAT, FLAT = ROOT, MAINLINE, ROOT DATA

/
each
LIBR
LIBR
LIBR

library will have its own apr assignment
POSRES:RO
RMSRES:RO
POSSUM:RO

TASK

FLAT

; define and assign logical units needed by this task:
UNITS = 7
ASG = SY:1:2:3:4:7
ASG = TI:5
GBLDEF
TRGTLN:1
lun for target file (call to PROATR)
GBLDEF
HL$LUN:2
lun for help file (not used in this example)
lun for menu file
GBLDEF
MN$LUN:3
GBLDEF
MS$LUN:4
lun for message file (not used in this example)
GBLDEF
TT$LUN:5
lun for POSRES services terminal I/O
GBLDEF
WC$LUN:7
lun for POSRES wildcard directory search
GBLDEF
TT$EFN:2
event flag for POSRES terminal I/O
EXTSCT
EXTSCT
EXTSCT

FL$BUF:2000
MM$BUF:2000
MN$BUF:2000

lprovide a buffer for file specs (OLDFIL)
lbuffer for multi-choice menu (OLDFIL)
lbuffer for additional options menu (OLDFIL)

B.3.1.2 ROOT.MAC.title
coderoot
.ident
/01.00/
.enabl
.mcall

lc
exit$s

;+
i

The operational code for this test task is found in MAINLINE.MAC.
Necessary data structures are in ROOTDATA.MAC.
8-30

OPTIONS IN TASK ORGANIZATION
;

.sbttl
.psect
START:
MOV
CALL
EXIT$S

Task root code

.sbttl
.psect
DATATBL:
. WORD
. WORD

Data table to drive mainline code
roodat,d,rw,con
OLFPAR
FAB

. WORD
. WORD
. WORD

LUN
FIDBUF
POSPAR

.END

START

*DATATBL,RO
MAINLN

;table of subroutine parameter bloc
imainline task code
;done

;call oldfil first
;will need· FAB address to set up
;call to rms
;three-word buffer for file id
iPossum (proatr) parameter block)

B.3.1.3 MAINLINE.MAC.title
Mainline code
.ident
/01.00/
.enabl
lc
.mcall
.mcall
.mcall
fhdof$

qiow$s, alun$s
$parse, $search, $compare, $fetch, $store
fhdof$
;define file header offsets for
;UC.CON

;+
Mainline code for test task.
This module will:
1. Establish proper lun assignments for terminal and target file
2. Call OLDFIL in POSRES to allow choice of target file.
3. Call RMS to determine FILE-ID of target file.
4. Call PROATR in POSSUM to determine whether file is contiguous
5. Output result to screen.
Most data for this module lives in ROOTDATA.MAC. This will permit
this module to be incorporated into a resident library which may
cluster against RMSRES, POSSUM, and POSRES and to share data with
that library.
There is some read-only data in this module which is included to
demonstrate its possible use in a cluster library.

B-31

OPTIONS IN TASK ORGANIZATION
; Inputs:

outputs:

RO -) Data table in the format:
.word
oldfil parameter block
.word
address of rms FAB
.word
address of lun for target file
.word
address of 3-word buffer for file id
.word
address of parameter block for possum
none

j -

.sbttl
.psect
MAINLN: :
MOV
MOV
MOV
CALL
MOV
MOV
TST
BLE
MOV
$STORE
MOV
$STORE

Mainline code
(RO)+,RS
RO,-(SP)
RS,-(SP)
OLOFIL
(SP)+,RS
(SP)+,RO
@2(RS)
10$

iparameter block for oldfil
ipreserve input pointer across call
iand also oldfil parameter block address
iget a file spec
jrestore oldfil parameter block
;restore input table
isuccessful?
ino

(RO)+,R2 jget fab address
@8.(RS),FNS,R2
jstore size of filespec (from oldfil)
@(RO)+,Rl
Rl,LCH,R2 ienter lun in FAB

$PARSE
R2
$COMPARE #SU$SUC,STS,R2
BNE
10$

icall RMS
jsuccess?

$SEARCH
R2
$COMPARE #SU$SUC,STS,R2
BNE
10$

iget file id into nam block
isuccessful?
ina, error

$FETCH
MOV
$FETCH

Rl,NAM,R2
(RO)+,R3
O(R3),FIO,Rl

MOV

(RO)+,RS

ino

jget NAM block address
ibuffer to receive file id
jretrieve File 10 into buffer

iproatr parameter block address

The proatr parameter looks as follows:
.word
5
addr. of 8-word status block
.word
.word
addr. of request word
addr. of buffer to construct attribute list
.word
.word
addr. of file-id buffer
. word
lun addr .
i
MOV

#O,@4(RS)

iinitialize request - get file attributes
by file id
B-32

OPTIONS IN TASK ORGANIZATION
MOV
iget address of attribute buffer
6 (R5) , RO
fill in attribute list:
MOVB
#3,(RO)+ iattribute type is file characteristics
MOVB
#2,(RO)+ itwo words
MOV
RO, (RO )
iconstruct a buffer address
ADD
#4,(RO)+ ipoint past attribute list
CLR
iend of attribute list
(RO)+
iinitialize cell to receive
CLR
(RO)
icharacteristics
.BYTE
.WORD
.WORD
1$:

3,2
1$

. WORD

CALL
MOV
TST
BLE.

PROATR
2 (R5 ) , Rl
2(Rl)
10$

BIC

#"C<UC.CON),(RO)

iattribute type, size
ilocation of output
inull ends attribute list
ireturned value from proatr
iget attributes
istatus block address
isuccess?
ino, pass back error
iclear all but contiguous bit in
i
attribute word
iif bit set, then file contiguous
iif bit clear, then file
not-contiguous
and (RO)=O

ipick up address of messages
code must be pic since this will go into a IPI library
MOV
PC,Rl
iassume contiguous
ADD
#CONTIG-.,Rl
MOV
#CONTIZ,R2
TST
(RO)
icontiguous if non-zero
BNE
5$
iyes, contiguous
PC,Rl
MOV
inon-contiguous
ADD
#NOCONT-.,Rl
MOV
#NOCONZ,R2
5$:
ALUN$S
#5,#"TI
ipoint terminal lun to the right place
CLR
-(SP)
icreate io status block
CLR
-(SP)
MOV
SP,R3
ipoint to it
QIOW$S
#IO.WVB,#5,#1"R3,,<Rl,R2,#40) ientertain
MOV
(SP)+,(SP)+
iclear off iosb
10$:
RETURN
.sbttl
.psect

Miscellaneous data
misdat,d,ro
B-33

OPTIONS IN TASK ORGANIZATION

contig:
.ascii
<33>/[2J/<33>/[10il0H/
.ascll
/The file you have chosen is contiguous/
contiz = .-contig
nocont:
.ascii
<33>/[2J/<33>/[10il0H/
.ascii
/The file you have chosen is not contiguous/
noconz = .-nocont
.even
.end

B.3.1.4 ROOTDATA.MAC.TITLE
DATA FOR TASK ROOT
.ident
/01.00/

.enabl

.mcall

fab$b, nam$b, pool$b

; This module contains data needed by resident libraries (and in some
i cases in-task root).
Data must be mapped when resident library is
; called.
i-

.psect

roodat,d,rw,con

.SBTTL

DATA FOR OLDFIL

prompt:
.ascii
promz = .-prompt
.even
prompz:
.word

/Step right up!

See if file is contiguous/
;indirect reference for

promz
ioldfil

olfpar::
.word
.word
.word
.word
.word

olfpaz
olfsts
numcho
fna
ofsiz

.word
nowild
.word
nosiz
.word
prompt
.word
prompz
.word
nomsg
.word
nosiz
.word
nomsg
.word
nosiz
olfpaz = <.-01fpar>/2 - 1

;size of parameter block
istatus block address
;number of choices
;file name string
;array (1 element) for
ifilespec size(s)
ina wildcard default
ina length for no wildcard default
itext
ino

B-34

message

OPTIONS IN TASK ORGANIZATION

olfsts:
numcho:
ofsiz:
nowild:
nomsg:
nosiz:
.SBTTL

.blkw
.word
.blkw

1
1

.word

DATA FOR RMS CALLS

lun: :

.word

trgtln

fidbuf::

.blkw

.SBTTL

itarget lun

DATA FOR POSSUM CALL

pospar::
.word
. word
. word
. word
. word
.word

stablk
bufl
buf2
fidbuf
lun

;addr .
;addr .
;addr .
;addr .
;addr.

stablk:
bufl:
buf2:

.blkw
.word
.blkw

8.
0
8.

.SBTTL

istatus block
ione choice only
iwill contain size of filespec
ina wildcard
ina message
ina size

of 8-word status block
of request word
of buffer to construct call
of buffer containing file-id
of lun for file
;request word
;enough for an attribute

RMS DATA STRUCTURES

fna: . blkb

256.

;buffer for file specification

dna: .ascii
dns = .-dna
.even
dnasiz:

/SY:;O/

;look for the latest version on default volume

.word

;force even boundary
dns
iindirect reference for oldfil

rss =
rsa: . blkb

255.

ess =
esa: .blkb
.even
fab: :
f$nam
f$fna
f$dna
f$dns

rss

;resultant string

255.

ess

;expanded string

fab$b
nam
fna
dna
dns

inam block address
;file specification address
;default file spec. addr.
idna size
B-35

OPTIONS IN TASK ORGANIZATION

fab$e
nam: nam$b
n$esa
n$ess
n$rsa
n$rss
nam$e
pool$b
p$fab
p$buf
p$bdb
pool$e

esa
ess
rsa
rss

iexpanded string address
isize of esa buffer
; resultant string address
isize of rsa buffer

ione fab
ione-block buffer
ione buffer descriptor block

512.
1

.end

8-36

OPTIONS IN TASK ORGANIZATION

8.3.2

CLUST.TSK

This task makes use of the cluster library facility to free some APRs
which would otherwise be used to map to resident libraries. The task
itself is still a flat structure.
Because the cluster library
facility uses the overlay runtime system the task incorporates an
overlay descriptor file.
The .ODL file describes this flat structure
in a manner similar to the specification of modules in the previous
example (FLAT.TSK).
Only one member of a library cluster may have a non-null root.
If
there is a library which meets this description, it must be the
default library of the cluster (appear first in the CLSTR option
line).
Mapping to this default library is always restored after the
completion of a call to another member of the cluster.
Normally a
higher-level language OTS falls into this category.
In the case in which there is no library with a non-null root,
the
library which is INVOKED first becomes the default library de facto,
regardles~ of its position in the CLSTR option line.
The consequence
of this is that if the task makes repeated calls to a particular
library, it would be advantageous to make a call to the most often
invoked library before calling any less frequently used library.

B.3.2.1 CLUSTBLD.CMDCLUST, CLUST = CLUST/MP
CLSTR = RMSRES,POSRES,POSSUM:RO
TASK = CLUST
UNITS = 7
ASG = SY:l:2:3:4:7
ASG = TI:5
GBLDEF
TRGTLN:l
GBLDEF
HL$LUN:2
GBLDEF
MN$LUN:3
GBLDEF = MS$LUN:4
GBLDEF
TT$EFN:2
GBLDEF
TT$LUN:5
GBLDEF
WC$LUN:7
EXTSCT
EXTSCT
EXTSCT

FL$BUF:2000
MN$BUF:2000
MM$BUF:2000

B-37

OPTIONS IN TASK ORGANIZATION
B.3.2.2

CLUST.ODL-

control
module
. ROOT

ROOT- OTHER- RMSROT

mainline RMS,POSSUM
code
& POSRES
data
OTHER:

.FCTR

MAINLINE- ROOTDATA

; include RMS root modules (RMSROT) so that POSRES routines
;
can call RMS (see discussion of USRRES, below)
@LB:[1,5]RMSRLX
.END

8-38

OPTIONS IN TASK ORGANIZATION

8.3.3

VECTOR.TSK and USRRES.TSK

This example demonstrates
1.

How to remove code from task space and place it in a resident
library.

How to build a resident library with a null root so that the
library may be used as part of a cluster of resident
libraries.

How to address data
library.

How to provide a facility to call other members
cluster from the user-written cluster library.

the

task

root

from

the

resident
of

the

In this example, the user-written library is intended to be installed
read-only and the library cluster mapped RO. As a result, there
cannot be any read/write data in the library; there is, however,
some
read-only data in this library for demonstration purposes.
Note
In the following discussion, the terms "task space",
"task root", and "task" all refer to a task which maps
to the resident library USRRES.

B.3.3.1 USRRESBLD.CMDBuild a PIC
resident library
Include .STB
file for
tasks which
map to this
library

USRRES/-HD/PI/LI, USRRES, USRRES

USRRES/MP

PAR = USRRES:O:O
STACK = 0
Insure that the symbol table for this library will contain
references to the externally available entry point(s):

GBLREF

= MAINLN

; Force the task builder to check that the root vectoring module

B-39

OPTIONS IN TASK ORGANIZATION
; is included in the task using this library for cross-cluster calls
; and accessing data in the root.
;

GBLINC = YANKME
;

; This library calls POSRES and POSSUM services (OLDFIL and
PROATR, respectively). The entry point names must be resolved
when building this library, but cannot be included in the library
; .STa, since references to these symbols from the task must be
resolved by the library which contains the routine. (See discussion
of cross-cluster calls.)
GBLXCL
GBLXCL
//

PROATR
OLDFIL

B.3.3.2 USRRES.ODL - Resident Library
The following
.OOL file
describes the resident library.
It is a non-overlaid resident library
with a null root. Any module without code or data allocation will
suffice as a root; SYSLIB includes the module NULL for this purpose.
. ROOT
CODE:

LB:[l,l]SYSLIB/LB:NULL- !(COOE)
.FCTR

*MAINLINE- RESVEC- SYSLIB/LB:RORMSC:RMSSYM

.END

B.3.3.3 Discussion - The module MAINLINE is declared autoloadable,
indicating to the task builder to mark its global entry point(s)
appropriately in the symbol table of USRRES.
Calls to these
routines
from the task will generate autoload vectors.
The autoload indicator
is used in conjunction with the GBLREF option in the taskbuild command
file.
The GBLREF option instructs the taskbuilder to place the symbol
in the .STB file for this library. This permits the calling task to
have access to that entry point.
The modules RORMSC and RMSSYM from SYSLIB permit this resident library
to call. RMSRES,
which may be clustered against USRRES.
This is
accomplished by vectoring these calls through the task root.
The
vectoring module RESVEC illustrates the use of this scheme for those
components which do not already provide a similar facility
(see
below).

B-40

OPTIONS IN TASK ORGANIZATION
Vectoring is required for two purposes:
1.

Accessing data in the task root from the library.

Cross-cluster calls.

Since the library must be taskbuilt before the referencing task,
the
library cannot reference the task directly. The task may pass data
addresses,
for example,
as
parameters
to
library
routines.
Alternatively, the library may address task space via a limited number
of fixed addresses which remain meanings from task to task. This area
is referred to as the "low-core" context of the task image.
As part of the low-core context,
the taskbuilder automatically
deposits the address of the first word of the psect $$VEXl in the
location $VEXT.
Since $VEXT is always at the same address in all
tasks,
a library may use this location to find the beginning of the
$$VEXl psect, whose actual virtual location will undoubtedly vary from
task to task.
Negative offsets from the beginning of the $$VEXl PSECT are reserved
for Digital impure area vectors.
Users may employ any positive
offset; however,
care should be taken to guarantee that other
applications
(e.g.
high-level languages) are not already using the
locations in $$VEX1.
The psect has the following attributes:
.PSECT $$VEX1,D,GBL,REL,OVR
The OVR attribute allows contributions to the PSECT
different sources while maintaining a fixed point of
the beginning of the PSECT. A SYSLIB module contains a
pointing to the beginning of this PSECT. The address
is deposited by the taskbuilder in the location $VEXT.

to come from
reference from
global symbol
of this symbol

Therefore a library routine may execute the following
point Rn to the beginning of $$VEX1.

instruction

Rn is anyone of the general purpose Registers.
The absolute
addressing mode (@ ) is required to guarantee position independence of
the library.
The library routine RESVEC makes use of the fact that a task built
against this library will contain impure area vectors required by
USRRES. The resident library can insure that the vector-declaring
module is included in the task by using the GBLINC option; this option
results in an error in a task built against this library if the
specified symbol is not resolved.

8-41

OPTIONS IN TASK ORGANIZATION
A module in USRRES callS PROATR by a normal JSR, pc:
CALL

PROATR

A module must be included in the resident library to vector this
through the task root.

call

B.3.3.4 Excerpt from RESVEC.MAC ; This global symbol must be excluded from the .STB of USRRES.
Otherwise, the taskbuilder would not be able to resolve the symbol
unambiguously between USRRES and POSSUM. The GBLXCL option in the
USRRES taskbuild command line instructs the taskbuilder to exclude
the symbol.
PROATR::
This code is written in this manner so as to preserve all registers.
MOV
@#$VEXT,-(SP) ;get pointer to $$VEXl psect
i (SP) address of MYVECT (see below)
MOV
@(SP)+,-(SP)
ipoint to table
; (SP) addr of INDIRECT
ADD
#2,(SP)
;PROATR transfer point is second in table; (SP) addr. of 2nd word in table
MOV
@(SP)+,-(SP)
iget contents of 2nd word of table
i (SP) addr. of "PROATR"
In actuality, the stack contains the address of an overlay runtime
autoload vector.
JMP
@(SP)+
;transfer to "PROATR" (overlay runtime
isystem)
At this point, the task is executing in the overlay runtime system,
which will save the mapping context of USRRES, remap to POSSUM, and
transfer control to PROATR. At the conclusion of PROATR, the overlay
runtime system will restore mapping to USRRES and return control to
the instruction following the call to PROATR.
A similar procedure would be followed to address the data space in the
task root. Here a register is available.
MOV
MOV
MOV

@#$VEXT,RO
(RO),RO
4(RO),RO

iaddress of MYVECT
ipoint to INDIRECT (vector table)
;contents of entry is address of data
table

B.3.3.5 VECTOR.MAC (Root vector module) ; Define symbol required by USRRES
YANKME == 0
.PSECT $$VEX1,D,GBL,REL,OVR
B-42

OPTIONS IN TASK ORGANIZATION

; This label will be equivalent to the value which the taskbuilder has
deposited in $VEXT because the psect $$VEX1 is OVR (overlaid).
MYVECT:
It is good practice to add a level of indirection. This will insure
that this use of this particular psect will consume only a single
word .
• WORD

INDIRECT

.PSECT JMPTBL,D,RO,CON
INDIRECT:
;used in cross-cluster calls
. WORD OLDFIL
. WORD PROATR
;used in cross-cluster calls
. WORD PNTDAT
;used to point to data in task root
.PSECT IMPURE,D,RW,CON
PNTDAT:
;read/write data area
.BLKB 120 .
. END

B.3.3.6

VECTORBLD.CMD-

; Command file to build task which maps to user-written resident
; cluster library
VECTOR, VECTOR = VECTOR/MP
CLSTR = RMSRES,POSRES,POSSUM,USRRES:RO
TASK = VECTOR
UNITS = 7
ASG = SY:1:2:3:4:7
ASG = TI:5
GBLDEF
TRGTLN:1
GBLDEF = HL$LUN:2
GBLDEF
MN$LUN:3
MS$LUN:4
GBLDEF
TT$EFN:2
GBLDEF
GBLDEF
TT$LUN:5
GBLDEF
WC$LUN:7
EXTSCT
EXTSCT
EXTSCT

FL$BUF:2000
MN$BUF:2000
MM$BUF:2000

B-43

OPTIONS IN TASK ORGANIZATION

B.3.3.7 VBCTOR.ODL• ROOT ROOT- OTHER- RMSROT

task root
vectoring
module
OTHER:

.FCTR

ROOTDATA- VECTOR

@LB:[l,S]RMSRLX
. END

8-44

OPTIONS IN TASK ORGANIZATION

8.3.4

OVERLAY.T5K

This example shows that a program can separate functionality in such a
way that the data required by a resident clustered library need not
always be.mapped.
In order to achieve this goal, one must first carefully analyze the
potential for functional independence of routines. The example is
structured to demonstrate a group of routines which call services in
RMSRES,
POSSUM, and POSRES and a second group of routines which do
some computation and QIO's to the terminal.
The second stage in the process is to determine which moduleS are
required by the resident library in question, and then force the
taskbuilder (through the .ODL file) to place these modules in the
appropriate branch of the overlay tree structure.
If the modules were
not specified by the .ODL file, they would be in the task root rather
than in a branch and therefore would consume shared virtual address
space and be mapped even when not needed.

B.3.4.1

OVERLAY.ODL-

The root module has changed from previous examples because of the
added calls (to COMPUTE and WTRES)
. ROOT ROOT2- (LEFT, RIGHT)
The module CLLWTR is included to call WTRES (wait for resume
key) in POSRES. The module COMPUTE displays a message to press
<RESUME> when the user is ready to continue.
In order to keep
all references to POSRES in the "left" branch of the tree, the
.ODL forces the root to transfer control up-tree in order to
call POSRES .
LEFT:
. FCTR *MAINLINE- *CLLWTR- ROOTDATA- BUFS- RMSROT- LIB
; Force other syslib references into this branch
LIB: .FCTR LB:[1,5]SYSLIB/DL
; These are the buffers required by POSRES services in this example
BUFS:
.FCTR SYSLIB/LB:PTIMP:PTFLF:FLFAB:PTDUM
RIGHT:

.FCTR

*COMPUTE- SYSLIB/LB:EDTMG

@LB:[1,5]RMSRLX
.END

B-45

OPTIONS IN TASK ORGANIZATION

B.3.4.2 OVERLABLD.CMDOVERLAY, OVERLAY = OVERLAY/MP
CLSTR = RMSRES,POSRES,POSSUM:RO
TASK = OVERLY
UNITS = 7
ASG = SY:1:2:3:4:7
ASG = TI:5
GBLDEF = TRGTLN:1
GBLDEF = HL$LUN:2
GBLDEF = MN$LUN:3
GBLDEF = MS$LUN:4
GBLDEF
TT$EFN:2
GBLDEF
TT$LUN:5
GBLDEF
WC$LUN:7
EXTSCT = FL$BUF:2000
EXTSCT = MN$BUF:2000
EXTSCT = MM$BUF:2000

B.3.4.3 ROOT2.MAC.TITLE ROOT2
.ident 101.001
.enabl lc
.mcall exit$s
i+

The operational code for this test task is found in MAINLINE.MAC
(Section B.3.1.3).
Necessary data structures are in ROOTDATA.MAC.
(Section B.3.1.4).
The alternate mapping is COMPUTE.MAC.
is in the same module.

All data for that segment

.SBTTL TASK ROOT CODE
.psect
START:
MOV
#DATATBL,RO
;table of subroutine parameter blocks
CALL
MAINLN
imainline task code - "LEFT"
CALL

COMPUTE

ido something else - "RIGHT"

CALL

CLLWTR

iwait for the resume key - "LEFT"
do the waiting in the posres services
branch of the tree
B-46

OPTIONS IN TASK ORGANIZATION
#DATATBL,RO
MOV
MAINLN
CALL
EXIT$S

ijust for fun, call first operation again
i

idone

.SBTTL DATA TABLE TO DRIVE MAINLINE CODE
.psect roodat,d,rw,con
DATATBL:
.WORD OLFPAR
icall oldfil first
. WORD FAB
iwill need FAB address to set up call to rms
. WORD LUN
ithree-word buffer for file id
. WORD FIDBUF
. WORD POSPAR
iPossum (proatr) parameter block)
.END

START

B.3.4.4 CLLWTR.MAC.TITLE CLLWTR - CALL WTRES FROM OVERLAY
.ident /01.00/
i+

This module will call the POSRES service WTRES (Wait for Resume key).
It is placed in an overlay branch in order to segregate all posres
calls from the root and/or other branches, i.e. to localize virtual
address requirements for calling posres services.
i-

CLLWTR: :
CALL
WTRES
RETURN
. END

B.3.4.5 COMPUTE.MAC.TITLE COMPUTE
.ident /01.00/
.enabl Ie
.mcall qiow$s, mrkt$s, wtse$s
i+

This module will consume space and time. The overlay branch which
shares this virtual address space will do more interesting things,
e.g. call RMS, POSSUM, and POSRES.
After this module does its thing, it will instruct the observer to
press the resume key. Since all calls to POSRES are in the other
branch, this will return to ROOT2 to allow the root to transfer
control to the POSRES-calling overlay.
i-

B-47

OPTIONS IN TASK ORGANIZATION
MRKEF = 3

;event flag to mark time

.psect
COMPUTE: :
MRKT$S #MRKEF,#2,#2

;mark time for 2 seconds

MOV
MOV
MOV

#DATBUF,RO
#DATBUZ,Rl
#1,R2

;address of data buffer
;size in words
;fill buffer with miscellaneous garbage

MOV
INC
SOB

R2, (RO ) +
R2
Rl,l$

;enter first word
;bump data

MOV
MOV
CLR
CLR

#DATBUF,RO
#DATBUZ,Rl
R2
R3

;now add it up

ADD
ADC
SOB

(RO)+,R3
R2
Rl,3$

MOV
MOV

R2,DPHIGH
R3,DPLOW

;copy to memory

MOV
MOV
MOV
CALL

#OUTBUF,RO
#FORMAT,Rl
#ARGBLK,R2
$EDMSG

iset up for $edmsg
;input string
iargument block
;format output

1$:

2$:
;double precision

3$:

4$:
5$:

10$:
WTSE$S #MRKEF

;let user read previous message

15$:
QIOW$S #IO.WVB,#5,#1,,#IOSB,,<#OUTBUF,Rl,#40> iprint new one
20$:
RETURN
.SBTTL DATA FOR THIS BORING ROUTINE
.psect boring,d,rw
DATBUZ = 100.
DATBUF:
.BLKW

ia hundred bottles of beer on the wall
DATBUZ

i KEEP THESE TWO VALUES TOGETHER, IN THIS ORDER:
DPHIGH:
.WORD 0
DPLOW:
. WORD 0

OUTBUF:

.SLKS

200.

ibuffer for output message

.NLIST SEX
FORMAT:
.ASCII <33>/[2J/<33>/[10i10H/ iclear screen and
B-48

OPTIONS IN TASK ORGANIZATION
;locate cursor
.ASCII /This is the total: %T. Whoopee!/
.ASCIZ /Press <RESUME> to continue./
. EVEN
.LIST BEX
ARGBLK:
. WORD

.WORD

IOSB:

.BLKW

DPHIGH
2

. END

B-49

APPENDIX C
FILES-11 ON-DISK STRUCTURE SPECIFICATION

This appendix provides a specification of the on-media structure
that is used by Files-ll. Files-ll is a general purpose file
structure which is intended to be the standard file structure for
all medium to large POP-ll systems. Small systems such as RT-ll
have been specifically excluded because the complexity
of
Files-ll would impose too great a burden on their simplicity and
small size.
This document describes structure level 1 of Files-ll, also
called 005-1 (On-Disk Structure Version 1).
This has been
implemented on PIOS and on RSX.
This document describes the
final level of functionality for 005-1.
Structure level 2
(005-2) has been implemented on VMS and is the basis for all new
disk structure enhancements.

C.1

MEDIUM

Files-ll is a structure which is imposed on a medium.
That
medium must have certain properties, which are described in the
following section. Generally speaking, block addressable storage
devices such as disks and oectape ar~ suitable for Files-ll.
Therefore, Files-ll structured media are generically disks.

C.1.1

Volume

The basic medium that carries a Files-ll structure is a volume
(also often called a unit), and is defined as an ordered set of
logical blocks. A logical block is an array of 512 a-bit bytes.
The logical blocks in a volume are consecutively numbered from 0
to n-l, where the volume contains n logical blocks.
The number
assigned to a logical block is called its logical block number,
or LBN. Files-ll is theoretically capable of describing volumes
up to 2 32 blocks in size. In practice, a volume should be at
A

C-l

MEDIUM
least 100 blocks in size to be useful.
Current implementations
of Files-ll will handle volumes up to 2A24 blocks.
The logical blocks of a volume must be randomly addressable. The
volume must also allow transfers of any length up to 65k bytes,
in multiples of four bytes. When a transfer is longer than 512
bytes, consecutively numbered logical blocks are transfered until
the byte count is satisfied. In other words, the volume can be
viewed as a partitioned array of bytes. It must allow reads and
writes of arrays of any length less than 65k bytes, provided that
they start on a logical block boundary and that the length is a
multiple of four bytes. When only part of a block is written,
the contents of the remainder of that logical block will be
undefined.

C.1.2

Volume Sets

ODS-l does not support volume sets. A volume set is a collection
of related units that are normally treated as one logical device
in the usual operating system concept. Each unit contains its
own Files-l1 structure. However, files on the various units in a
volume set may be referenced with a relative volume number, which
uniquely determines which unit in the set the file is located on.
Other sections in this specification will make
occasional
reference to volume sets and relative volume numbers where hooks
for their implementation exist. Since volume sets have not been
implemented
as yet, however, no complete specification is
provided here.

C.2

FILES

Any data in a volume or volume set that is of any interest (i.e.,
all blocks not available for allocation) is contained in a file.
A file is an ordered set of virtual blocks, where a virtual block
is an array of 512 8 bit bytes. The virtual blocks of a file are
consecutively numbered from 1 to n, where n blocks have been
allocated to the file. The number assigned to a virtual block is
called (obviously) its virtual block number, or VBN.
Each
virtual block is mapped to a unique logical block in the volume
set by Files-ll. Virtual blocks may be processed in the same
manner as logical blocks. Any array of bytes less than 65k in
length may be read or written, provided that the transfer starts
on a virtual block boundary and that its length is a multiple of
four.

C-2

FILES
C.2.1

File 10

Each file in a volume set is uniquely identified by a File ID. A
File ID is a binary value consisting of 48 bits (3 POP-ll words).
It is supplied by the file system when the file is created, and
must be supplied by the user whenever he wishes to reference a
particular file.
The three words of the File
•

are used as follows:

Word 1 - File Number
Locates the file within a particular unit of the volume
set.
File numbers must lie in the range 1 through
65535. The set of file numbers on a unit is moderately
(but not totally) dense. At any instant in time, a file
number uniquely identifies one file within that unit.

•

Word 2 - File Sequence Number
Identifies the current use of an individual file number
on a unit.
File numbers are re-used. When a file is
deleted its file number becomes available for future use
for some other file.
Each time a file number is
re-used, a different file sequence number is assigned to
distinguish the uses of that file number. The file
sequence number is essential since it is perfectly legal
for users to remember and attempt to use a File 10 long
after that file has been deleted.

•

Word 3 - Relative Volume Number
Identifies which unit of a volume set the file is
located on. Volume sets are at present not implemented.
The only legal value for the relative volume number in
any context is zero.

C.2.2

File Header

Each file on a Files-ll volume is described by a file header.
The file header is a block that contains all the information
necessary to access the file. It is not part of the file. It is
contained in the volume's index file.
(The index file is
described in Section C.4.1. The header block is organized into
four areas, of which the first three are variable in size.

C-3

FILES
Header Area - The information in the header area permits
the file system to verify that this block is in fact a file
header and, in particular, is the header being sought by the
user.
It contains the file number and file sequence number of
the file, as well as its ownership and protection codes.
This
area also contains offsets to the other areas of the file header,
thus defining their size. Finally, the header area contains a
user attribute area, which may be used by the user to store a
limited amount of data describing the file.
C.2.2.1

Ident Area - The ident area of a file header contains
identification and accounting data about the file. Stored here
are the primary name of the file, its creation date and time,
revision count, date, and time, and expiration date.

C.2.2.2

C.2.2.3 Map Area - The map area describes the mapping of virtual
blocks of the file to the logical blocks of the volume. The
mapping data consists of a list of retrieval pointers.
Each
retrieval pointer describes one logically contiguous segment of
the file. The map area also contains the linkage to the next
extension header of the file, if such exists.

End Checksum - The last two bytes of the file header
contain a 16 bit additive checksum of the remalnlng 255 words of
the file header. The checksum is used to help verify that the
block is in fact a file header.

C.2.2.4

C.2.3

Extension Headers

Since the file header is of fixed size, it is inevitable that for
some files the mapping information will not fit in the allocated
space. A file with a large amount of mapping data is therefore
represented with a chain of file headers. Each header maps a
consecutive set of virtual blocks. The extension linkage in the
map area links the headers together in order of ascending virtual
block numbers.
Multiple headers are also needed for files that span units in a
volume set. A header may only map logical blocks located on its
unit. Therefore, a multi-volume file is represented by headers
on all units that contain portions of that file.

C-4

FILES
C.2.4

File Header - Detailed Description

This section describes in detail the items contained in the file
header. Each item is identified by a symbol which represents the
offset address of that item within its area in the file header.
Any item may be located in the file header by locating the area
to which it belongs and then adding the value of its offset
address.
Users who concern themselves with the contents of file
headers are strongly urged to use the offset symbols.
The
symbols may be defined in assembly language programs by calling
and invoking the macro FHDOF$, which may be found in the macro
library of any system that supports Files-ll.

C.2.4.1 Header Area Description - The header area of the file
header
always
starts at byte O.
It contains the basic
information needed for checking the validity of accesses to the
file.

H.IDOF:

1 Byte - Ident Area Offset

This byte contains the number of 16 bit words between
the start of the file header and the start of the ident
area. It defines the location of the ident area and
the size of the header area.
H.MPOF:

1 Byte - Map Area Offset

This byte contains the number of 16 bit words between
the start of the file header and the start of the map
area. It defines the location of the map area and,
together with H.IDOF, the size of the ident area.
H.FNUM:

2 Bytes - File Number

This word contains the file number of the file.
H.FSEQ:

2 Bytes - File Sequence Number

This word contains the
file.
H.FLEV:

file

sequence

number

the

2 Bytes - File Structure Level

The file structure level is used to identify different
versions of Files-ll as they affect the structure of
the file header. This permits upwards compatibility of,
file structures as Files-ll evolves, in that the
structure level word identifies the version of Files-ll
that created this particular -file.
This document
C-5

FILES
describes version 1 of Files-ll.
contents for H.FLEV is 401 octal.
H.FOWN:

2 Bytes - File Owner UIC

H.PROG

H.FOWN+O Programmer (Member) Number

H.PROJ

H.FOWN+l Project (Group) Number

The

only

legal

This word contains the binary user identification code
(UIC) of the owner of the file. The file owner is
usually (but not necessarily) the creator of the file.
H.FPRO:

2 Bytes - File Protection Code

This word controls what access all users in the system
may have to the file.
Accessors of a file are
categorized according to the relationship between the
UIC of the accessor and the UIC of the owner of the
file. Each category is controlled by a four bit field
in the protection word. The category of the accessor
is selected as follows:
•

System - Bits 0 - 3
The accessor is subject to system protection if the
project number of the UIC under which he is running
is 10 octal or less.

•

Owner - Bits 4 - 7
The accessor is subject to owner protection if the
UIC under which he is running exactly matches the
file owner UIC.

•

Group - Bits 8 - 11
The accessor is subject to group protection if the
project number of his UIC matches the project
number of the file owner UIC.

•

World - Bits 12 - 15
The accessor is subject to world protection if
does not fit into any of the above categories.

Four types of access intents are defined
in
Files-ll:
read, write, extend, and delete. Each
four bit field in the protection word is bit
encoded to permit or deny any combination of the
four types of access to that category of accessors.
C-6

FILES
Setting a bit denies that type of access to that
category. The bits are defined as follows (these
values
apply
to a right-justified protection
field):
FP.RDV Deny read access
FP.WRV Deny write access
FP.EXT Deny extend access
FP.DEL Deny delete access
When a user attempts to access a file, protection
checks are performed in all the categories to which
he is eligible, in the order system - owner - group
- world. The user is granted access to the file if
any of the categories to which he is eligible
grants him access.
H.FCHA:

2 Bytes - File Characteristics

H.UCHA
H.SCHA

H.FCHA+O User Controlled Char.
H.FCHA+l System Controlled Char.

The user controlled characteristics byte
following flag bits:

contains

1 Bit, Reserved.
UC.NID

Set if incremental dump (backup) is to
be disabled for this file.

UC.WBC

Set if the file is to be write-back
cached. For example, if a cache is used for
the file data, data written by a user is
only written back to the disk ~hen is it
removed from the cache. Clear for
write-through cache operation.

UC.RCK

Set if the file is to be read-checked.
All read operations on the file,
including reads of the file header(s),
will be performed with a read,
read-compare to assure data integrity.

UC.WCK

Set if the file is to be write-checked.
All write operations on the file,
including modifications of the file
C-7

the

FILES
header(s), will be performed with a
write, read-compare to assure data
integrity.
UC.CNB

Set if the file is allocated contiguous
best effort. In other words, as contiguous as
possible.

UC.DLK

Set if the file is deaccess-Iocked.
This bit is used as a flag warning that
the file was not properly closed and may
contain inconsistent data. Access to
the file is denied if this bit is set.

UC.CON

Set if the file is logically contiguous.
For example, if for all virtual blocks in the
file, virtual block i maps to logical
block k+i on one unit for some constant
k. This bit may be implicitly set or
cleared by file system operations that
allocate space to the file. The user
may only clear it explicitly.

The system controlled characteristics byte contains the
following flag bits:
3 Bits, Reserved.
Reserved (Access Control List).

H.UFAT:

SC.SPL

Set if the file is an intermediate file
for spooling.

SC.DIR

Set if the file is a directory.

SC.BAD

Set if there is a bad data block in the
file. This bit is as yet unimplemented.
It is intended for dynamic bad block
handling.

SC.MDL

Set if the file is marked for delete.
If this bit is set, further accesses to
the file are denied, and the file will
be physically deleted when no users are
accessing it.

32 Bytes - User Attribute Area

C-8

FILES
This area is intended for the storage of a limited
quantity of "user file attributes", i.e., any data the
user deems useful for processing the file that is not
part of the file itself. An example of the use of the
user attribute area is presented in Section C.S.1
(FCS
File Attributes).
S.HDHD:

46 Bytes - Size of Header Area

This symbol represents the total size of
area containing all of the above entries.

the

header

C.2.4.2 Ident Area Description - The ident area of the file
header begins at the word indicated by H.IDOF.
It contains
identification and accounting data about the file.
I.FNAM:

6 Bytes - File Name

These three words contain the name of the file,
packed
three Radix-50 characters to the word.
This name
usually, but not necessarily, corresponds to the name
of the file's primary directory entry.
I.FTYP:

2 Bytes - File Type

This word contains the type of the file in the form
three Radix-50 characters.
I.FVER:

2 Bytes - Version Number

This word contains the version number of
binary form.
I.RVNO:

the

file

2 Bytes - Revision Number

This word contains the revision count of the file.
The
revision count is the number of times the file has been
accessed for write.
I.RVDT:

7 Bytes - Revision Date

The revision date is the date on which the file was
last deaccessed after being accessed for write.
It is
stored in ASCII in the form "DDMMMYY", where DO is two
digits representing the day of the month, MMM is three
characters representing the month, and YY is the last
two digits of the year.
I.RVTI:

6 Bytes - Revision Time
C-9

FILES
The reV1Slon time is the time of day on which the file
was last deaccessed after being accessed for write. It
is stored in ASCII in the format "HHMMSS" , where HH is
the hour, MM is the minute, and 55 is the second.
I.CRDT:

7 Bytes - Creation Date

These seven bytes contain the date on which the file
was created.
The format is the same as that of the
revision date above.
I.CRTI:

6 Bytes - Creation Time

These six bytes contain the time of day at which the
file was created.
The format is the same as that of
the revision time above.
I.EXDT:

7 Bytes - Expiration Date

These seven bytes contain the date on which the file
becomes eligible to be deleted. The format is the same
as that of the revision and creation dates above.
1

Byte - (unused)

This unused byte is present to round up the size if the
ident area to a word boundary.
S.IDHD:

46 Bytes - Size of Ident Area

This symbol represents the size of
containing all of the above entries.

the

ident

area

Map Area Description - The map area of the file header
starts at the word indicated by H.MPOF.
It contains the
information necessary to map the virtual blocks of the file to
the logical blocks of the volume.

C.2.4.3

M.ESQN:

1 Byte - Extension Segment Number

This byte contains the value n, where this header is
the n+lth header of the file. In other words, headers
of a file are numbered sequentially starting with O.
M.ERVN:

Byte - Extension Relative Volume No.

C-I0

FILES
This byte contains the relative volume number of the
unit
in
the volume set that contains the next
sequential extension header for this file. If there is
no extension header, or if the extension header is
located on the same unit as this header, this byte
contains O.
M.EFNU:

2 Bytes - Extension File Number

This word contains the file number of the
next
sequential extension header for this file. If there is
no extension header, this word contains O.
M.EFSQ:

2 Bytes - Extension File Sequence Number

This word contains the file sequence number of the next
sequential extension header for this file. If there is
no extension header, this word contains O.
M.CTSZ:

1 Byte - Block Count Field Size

This byte contains a count of the number of bytes used
to represent the count field in the retrieval pointers
in the map area.
The retrieval pointer format is
described under M.RTRV below.
M.LBSZ:

1 Byte - LBN Field Size

This byte contains a count of the number of bytes used
to represent the logical block number field in the
retrieval pointers in the map area.
The contents of
M.CTSZ and M.LBSZ must add up to an even number.
M.USE:

Byte - Map Words In Use

This byte contains a count of the number of words in
the map area that are presently occupied by retrieval
pointers.
M.MAX:

1 Byte - Map Words Available

This byte contains the total number of words
for retrieval pointers in the map area.
M.RTRV:

available

variable - Retrieval Pointers

This area contains the retrieval pointers that actually
map the virtual blocks of the file to the logical
blocks of the volume. Each retrieval pointer describes
a consecutively numbered group of logical blocks which
is part of the file.
The count field contains the
C-ll

FILES
binary value n to represent a group of n+l logical
blocks. The logical block number field contains the
logical block number of the first logical block in the
group. Thus each retrieval pointer maps virtual blocks
j through j+n into logical blocks k through k+n,
respectively, where j is the total number plus one of
virtual blocks represented by all preceding retrieval
pointers in this and all preceding headers of the file,
n is the value contained in the count field, and k is
the value contained in the logical block number field.
Although the data in the map area provides
for
arbitrarily
extensible
retrieval pointer formats,
Files-11 has defined only three. Of these, only the
first is currently implemented.
The other two are
presented out of historical interest. They will never
be supported.
Format 1: M.CTSZ
M.LBSZ = 3

The total retrieval pointer length is
four bytes. Byte 1 contains the high
order bits of the 24 bit LBN. Byte 2
contains the count field, and bytes 3
and 4 contain the low 16 bits of the
LBN.

1----------1----------1
1 Count 1 High 1
1----------1-I
1
Low Order LBN
1
1---------------------1
Format 2: M.CTSZ = 2
M.LBSZ = 2
The total retrieval pointer length is
four bytes. The first word contains a
16 bit count field and the second word
contains a 16 bit LBN field.

1---------------------1
1

Count

1---------------------1
1

LBN

1---------------------1

C-12

FILES
Format 3: M.CTSZ = 2
M.LBSZ = 4
The total retrieval pointer length is
six bytes. The first word contains a 16
bit count field and the second and third
words contain a 32 bit LBN field.

1---------------------1
1 Count
1
1---------------------1
1

High

1-1

LBN

--I

Low

1---------------------1
S.MPHD:

10 Bytes - Size of Map Area

This symbol represents the size of the map area, not
including the space used for the retrieval pointers.

End Checksum Description - The header check sum occupies
the last two bytes of the file header. It is verified every time
a header is read, and is recomputed every time a header is
written.
C.2.4.4

H.CKSM:

2 Bytes - Block Checksum

This word is a simple additive checksum of all other
words in the block. It is computed by the following
PDP-11 routine or its equivalent:

10$:

MOV
CLR
MOV
ADD
SOB
MOV

Header-address,RO
R1
#255.,R2
(RO)+,R1
R2,10$
R1,(RO)

C-13

FILES

C.2.4.S File Header Layout Header Area
I~------------------I-------------------I

H.MPOF

1 Map Area Offset 1 Ident Area Offset 1
1-------------------1-------------------1
1
File Number
1
1---------------------------------------1
1

File Sequence Number

1--------------------------------------File Structure Level
1--------------------------------------File Owner UIC
1--------------------------------------File Protection
1

H.PROJ

H.SCHA

1-------------------1------------------1

System Char.

User Char.

1-------------------1------------------1

H.IDOF
H.FNUM
H.FSEQ
H.FLEV
H.FOWN
H.PROG
H.FPRO
H.FCHA
H.UCHA
H.UFAT

1
1
1

User Attribute Area

1
1

1---------------------------------------

C-14

S.HDHD

FILES

Ident Area

---------------------------------------1

I.FNAM

--I
File Name

--I
1

---------------------------------------1
File Type

---------------------------------------1
Version Number

---------------------------------------1
Revision Number

I.FTYP
I.FVER
I.RVNO
I.RVDT

Revision Date

-------------------1

I.RVTI

1------------------Revision Time

-------------------1
1-------------------

I.CRDT

Creation Date

I.CRTI

--I
Creation Time

--I
1

---------------------------------------1
1

1-1

Expiration Date

1--

--I

1-------------------1
1

I.EXDT

--I

(not used)

--I

1-------------------1-------------------1

C-15

S. IDHD

FILES
Map Area
M.ERVN

1-------------------1-------------------1
1 Extension RVN 1 Ext. Seg. Num.
1
1-------------------1-------------------1
1
Extension File Number
1
1---------------------------------------1
Extension File Seq. Num.
1-------------------1-------------------1
1 LBN Field Size 1 Count Field Size 1
1-------------------1-------------------1
1 Map Words Avail. 1 Map Words in Use 1
1-------------------1-------------------1
1

M.LBSZ
M.MAX

Retrieval Pointers

1---------------------------------------1
File Header Checksum

M.EFNU
M.EFSQ
M.CTSZ
M.USE
S.MPHD
M.RTRV

M.ESQN

H.CKSM

1---------------------------------------1

C.3

DIRECTORIES

Files-11 provides directories to allow the organization of files
in a meaningful way. While the File 10 is sufficient to locate a
file uniquely on a volume set, it
is
hardly
mnemonic.
Directories are files whose sole function is to associate file
name strings with File ID's.

C.3.1

Directory Hierarchies

Since directories are files with
no
special
attributes,
directories may list files that are in turn directories. Thus,
an operating system may construct directory hierarchies of
arbitrary depth and complexity.

User File Directories - This implementation of Files-11
supports a multilevel directory hierarchy. This hierarchy is a
simple tree structure with root as the master file directory
(MFD).
There
are
two
forms of valid directory names:
alphanumeric and numeric. Alphanumeric directory names can be

C.3.1.1

C-16

DIRECTORIES
any legal file name consisting of up to nine characters.
Alphanumeric directory
names
are
created
in
the
form
"yyyyyyyyy.DIRj1."
Numeric
directory names consist of two
three-digit octal numbers, in the range a through 377. If fewer
than nine characters are used, the name is padded with leading
zeros.
Numeric directory names are created in
the
form
"nnnmmm.DIRj1."

C.3.2

Directory Structure

A directory is a file consisting of 16 byte records.
It is
structured as an FCS fixed length record file, with no carriage
control attributes (see Section C.S for a description of FCS
files).
Each record is a directory entry. The entries are not
required to be ordered, or densely packed, nor do they have any
other relationship to each other, except that no two entries in
one directory may contain the same name, type, and version. Each
entry contains the following:
File ID

The three word binary File ID of the file that
this directory entry represents.
If the file
number portion of the File ID field is zero, then
this record is empty and may be used for a new
directory entry.

Name

The name of the file may be up to 9 characters.
It is stored as three words, each containing three
Radix-50 packed characters.

Type

The type of the file (also historically referred
to
as
the
extension) may be up to three
characters. It is stored as one word of Radix-50
packed characters.

Version

The version number of the file is stored in binary
in one word.

1---------------------1
1
1
1-1

--I

File ID

1--

--I

1---------------------1
1

1--

--I
Name

1--

--I
C-17

DIRECTORIES

1
1
1---------------------1
1
Type
1
1---------------------1
Version
1---------------------1
1

C.3.3

Directory Protection

Since directories are files with no special characteristics, they
may be accessed like all other files, and are subject to the same
protection mechanism.
However, implementations of
Files-11
support
three
special
functions
for
the management of
directories, namely FIND, REMOVE, and ENTER. A user performing
such a directory operation must have the following privileges to
be allowed the various functions:
Find:
Remove:
Enter:

READ
READ, WRITE
READ, WRITE

Note that the same privilege is required for both enter and
remove.
The recovery for an operation that involves a remove at
the beginning of the sequence is an enter.

C-18

KNOWN FILES

C.4

KNOWN FILES

Clearly any file system must maintain some data structure on the
medium which is used to control the file organization.
In
Files-ll this data is kept in five files.
These files are
created when a new volume is initialized. They are unique in
that their File IO's are known constants. These five files have
the following uses:
File ID 1,1,0 is the index file.
The index file is the root of
the
entire
Files-ll structure.
It contains the volume's
bootstrap block and the home block, which is used to identify the
volume and locate the rest of the file structure. The index file
also contains all of the file headers for the volume,
and a
bitmap to control the allocation of file headers.
File IO 2,2,0 is the storage bitmap file.
It is used to
the allocation of logical blocks on the volume.

control

File IO 3,3,0 is the bad block file.
It is a file containing all
of the known bad blocks on the volume.
File IO 4,4,0 is the volume master file directory (or MFO).
It
forms the root of the volume's directory structure. The MFD
lists the five known files, all first level user directories, and
whatever other files the user chooses to enter.
File IO 5,5,0 is the system core image file.
Its use is
operating system dependent.
Its basic purpose is to provide a
file of known File IO for the use of the operating system.

C.4.1

Index File

The index file is File ID 1,1,0. It is listed in the MFO as
INOEXF.SYS;l.
The index file is the root of the Files-ll
structure in that it provides the means for identification and
initial access to a Files-ll volume, and contains the access data
for all files on the volume (including itself).

C.4.1.1 Bootstrap Block - Virtual block 1 of the index file is
the volume's boot block.
It is always mapped to logical block
of the volume.
If the volume is the system device of an
operating system,
the boot block contains an operating system
dependent program which reads the operating system into memory
when the boot block is read and executed by a machine's hardware
bootstrap.
If the volume is not a system device, the boot block
contains a small program that outputs a message on the system
C-19

KNOWN FILES
console to inform the operator to that effect.

C.4.1.2 Home Block - Virtual block 2 of the index file is the
volume's home block. The logical block containing the home block
is the first good block on the volume out of the sequence 1, 256,
512, 768, 1024, 1280, .... 256n. The purpose of the home block
is to identify the volume as Files-ll, establish the specific
identity of the volume, and serve as the ground zero entry point
into the volume's file structure. The home block is recognized
as a home block by the presence of checksums in known places and
by the presence of predictable values in certain locations.

•
•

Items contained in the home block are identified by symbolic
offsets in the same manner as items in the file header. The
symbols may be defined in assembly language programs by calling
and invoking the macro HMBOF$, which may be found in the macro
library of any system that supports Files-ll .

H.IBSZ:

2 Bytes - Index File Bitmap Size

This 16 bit word contains the number of blocks that
make up the index file bitmap. (The index file bitmap
is discussed in Section C.4.1.3. This value must be
non-zero for a valid home block.
H.IBLB:

4 Bytes - Index File Bitmap LBN

This double word contains the starting logical block
address of the index' file bitmap. Once the home block
of a volume has been found, it is this value that
provides access to the rest of the index file and to
the volume. The LBN is stored with the high order in
the first 16 bits, followed by the low order portion.
This value must be non-zero for a valid home block.
H.FMAX:

2 Bytes - Maximum Number of Files

This word contains the maximum number of files that may
be present on the volume at any time. This value must
be non-zero for a valid home block.
H.SBCL:

2 Bytes - Storage Bitmap Cluster Factor

This word contains the cluster factor used in the
storage bitmap file. The cluster factor is the number
of blocks represented by each bit in the storage
bitmap.
Volume clustering can not be implemented in
C-20

KNOWN FILES
ODS-1.

H.DVTY:

The only legal value for this item is 1.

2 Bytes - Disk Device Type

This word is an index identifying the type of disk that
contains this volume.
It is currently not used and
always contains O.
H.VLEV:

2 Bytes - Volume Structure Level

This word identifies the volume's structure level.
Like the file structure level, this word identifies the
version of Files-11 which created this volume and
permits upwards compatibility of media as Files-11
evolves. The volume structure level is affected by all
portions of the Files-11 structure except the contents
of the file header. This document describes Files-11
version 1.
The only legal values for the structure
level are 401 and 402 octal. The former (401)
is the
standard value for most volumes. The latter (402) is
an advisory that the volume contains a multiheader
index file.
(A multiheader index file is required to
support more than about 26,000 files.
The index file
may in fact be multiheader without the volume having a
structure level of 402).
H.VNAM:

12 Bytes - Volume Name

This area contains the volume label as an ASCII string.
It is padded out to 12 bytes with nulls. The volume
label is used to identify individual volumes.
_.

4 Bytes - Not Used

H.VOWN:

2 Bytes - Volume Owner UIC

This word contains the binary UIC of the owner of the
volume.
The format is the same as that of the file
owner UIC stored in the file header.
H.VPRO:

2 Bytes - Volume Protection Code

This word contains the protection code for the entire
volume.
Its contents are coded in the same manner as
the file protection code stored in the file header, and
it is interpreted in the same way in conjunction with
the volume owner UIC. All operations on all files on
the volume must pass both the volume and the file
protection check to be permitted.
(Refer to the
discussion on file protection described earlier under
H.FPRO.
C-21

KNOWN FILES
H.VCHA:

2 Bytes - Volume Characteristics

This word contains bits which provide
additional
control over access to the volume. The following bits
are defined:
•

CH.NDC - Obsolete, used by RSX-llD/IAS.
Set if
device control functions are not permitted on this
volume. Device control functions are those which
can threaten the integrity of the volume, such as
direct reading and writing of logical blocks, etc.

•

CH.NAT - Obsolete, used by RSX-llD/IAS. Set if the
volume may not be attached, i.e., reserved for the
sole use by one task.

•

CH.SDI - Set if the volume contains only a single
directory.
If this bit is set, no directories
should be created on the volume other than the MFD.
The access methods should also be informed of this
situation, e.g. by setting the DV.SDI bit in the
device characteristics word.

H.DFPR:

2 Bytes - Default File Protection

This word contains the file protection that will be
assigned to all files created on this volume if no file
protection is specified by the user.
_.

6 Bytes - Not Used

H.WISZ:

1 Byte - Default Window Size

This byte contains the number of retrieval pointers
that will be used for the "window" (in core file access
data) when files are accessed on the volume, if not
otherwise specified by the accessor.
H.FIEX:

1 Byte - Default File Extend

This byte contains the number of blocks that will be
allocated to a file when a user extends the file and
asks for the system default value for allocation.
H.LRUC:

1 Byte - Directory Pre-access Limit

This byte contains a count of the number of directories
to be stored in the file system's directory access
cache. More generally, it is an estimate of the number
of concurrent users of the volume and its use may be
C-22

KNOWN FILES
generalized in the future.
H.REVD:

7 Bytes - Date of Last Home Block Revision

This field is in the standard ASCII date format and
reflects the date of the last modifications to fields
in the home block.
H.REVC:

2 Bytes - Count of Home Block Revisions

This field reflects
modifications.
_.

the

number

above

mentioned

2 Bytes - Not Used

H.CHK1:

2 Bytes - First Checksum

This word is an additive checksum of all entries
preceding in the home block (i.e., all those listed
above). It is computed by the same sort of algorithm
as the file header checksum (see H.CKSM).
H.VDAT:

14 Bytes - Volume Creation Date

This area contains the date and time that the volume
was initialized. It is in the format "DDMMMYYHHMMSS",
followed followed by a single null.
(The same format
is used in the ident area of the file header, Section
C.2.4.2.
_.

382 Bytes Not Used
This area is reserved for the relative volume table for
volume sets.
This field will not be used, although
some versions of DSC referenced this area.

H.PKSR:

•
•

4 Bytes - Pack Serial Number

This area contains the manufacturer supplied serial
number
for the physical volume.
For last track
devices, the pack serial number is contained on the
volume in the manufacturer data. For other devices the
user must supply this information manually. The serial
number is contained in the home block for convenience
and consistency .

12 Bytes - Not Used

C-23

KNOWN FILES
This field is reserved for the volume set name.

•
•

H.INON:

12 Bytes - Volume Name

This area contains another copy of the ASCII volume
label. It is padded out to 12 bytes with spaces.

•
•

H.INOO:

12 Bytes - Volume Owner

This area contains an ASCII expansion of the volume
owner UIC in the form "[proj,prog]". Both numbers are
expressed in decimal and are padded to three digits
with leading zeroes.
The area is padded out to 12
bytes with trailing spaces.

•
•

H.INDF:

12 Bytes - Format Type

This field contains the ASCII string "DECFILEllA"
padded out to 12 bytes with spaces. It identifies the
volume as being of Files-ll format.

•
•
-.

2 Bytes - Not Used

H.CHK2:

2 Bytes - Second Checksum

It
This word is the last word of the home block.
contains an additive checksum of the preceding 255
words of the home block, computed according to the
algorithm listed under H.CKSM.
Home Block Layout

1---------------------------------------1
1
Index File Bitmap Size
1
1---------------------------------------1
1
Index File
1
1---I
Bitmap LBN
1---------------------------------------1
Maximum Number of Files
1---------------------------------------1

H. IBSZ
H. IBLB

H.FMAX

H.SBCL

Storage Bitmap Cluster Factor

1---------------------------------------1
C-24

KNOWN FILES
\

Disk Device Type

H.DVTY

\--------------------------------------\
Volume Structure Level
\---------------------------------------

H.VLEV
H.VNAM

\-\

Volume Name

\-\

(not used)
Volume Owner UIC

H.VOWN

Volume Protection

H.VPRO

Volume Characteristics

H.VCHA

Default File Protection

H.DFPR

1--

--I
(not used)

H.FIEX
H.REVD

-------------------1------------------Def. File Extend
Def. Window Size
-------------------1------------------Directory Limit
1------------------1

H.WISZ

H.LRUC

Volume Modification Date

Volume Modification Count

H.REVC

(not used)
First Checksum

H.CHKl

---------------------------------------\
\

C-2S

H.VDAT

KNOWN FILES

I-I
I-I
I-I
I-I
I-I

--I
I
--I
I
Volume Creation Date

1--

(not used)

H.PKSR

-I

Pack Serial Number

(not used)

H. INDN

Volume Name

I-I

--I
I
C-26

KNOWN FILES

H.INDO

Volume Owner

H.INDF

Format Type

(not used)
\

Second Checksum

\---------------------------------------

H.CHK2

Index File Bitmap - The index file bitmap is used to
control the allocation of file numbers (and hence file headers).
It is simply a bit string of length n, where n is the maximum
number of files permitted on the volume (contained in offset
H.FMAX in the home block). The bitmap spans over as many blocks
as is necessary to hold it, i.e., maximum number of files divided
by 4096 and rounded up. The number of blocks in the bitmap is
contained in offset H.IBSZ of the home block.
C.4.1.3

The bits in the index file bitmap are numbered sequentially from
to n-1 in the obvious manner, i.e., from right to left in each
byte, and in order of increasing byte address. Bit j is used to
represent file number j+1:
if the bit is 1, then that file
number is in use. If the bit is 0, then that file number is not
in use and may be assigned to a newly created file.

The index file bitmap starts at virtual block 3 of the index file
and continues through VBN 2+m, where m is the number of blocks in
the bitmap. It is located at the logical block indicated by
C-27

KNOWN FILES
offset H.IBLB in the home block.

C.4.1.4 File Headers - The rest of the index file contains all
the file headers for the volume. The first 16 file headers (for
file numbers 1 to 16) are logically contiguous with the index
file bitmap to facilitate their location.
The rest may be
allocated wherever the file system sees fit.
Thus the first 16
file headers may be located from data in the home block (H.IBSZ
and H.IBLB) while the rest must be located through the mapping
data in the index file header. The file header for file number n
is located at virtual block 2+m+n (where m is the number of
blocks in the index file bitmap).

C.4.2

Storage Bitmap File

The storage bitmap file is File ID 2,2,0.
It is listed in the
MFD as BITMAP.SYS;l. The storage bitmap is used to control the
available space on a unit.
It consists of a storage control
block which contains summary information about the unit, and the
bitmap itself which lists the availablilty of individual blocks.

C.4.2.1 storage Control Block - Virtual block 1 of the storage
bitmap is the storage control block.
It contains summary
information intended to optimize allocation of space on the unit.
The storage control block has the following format for disks with
less than 4096*126, (516,096) blocks:
(3
(1
(2
(2

bytes)
byte)
bytes)
bytes)

(2 bytes)
(2 bytes)
(4 bytes)

Not used (zero)
Number of storage bitmap blocks (less than 127)
Number of free blocks in 1st bitmap block
Free block pointer in 1st bitmap block

Number of free blocks in nth bitmap block
Free block pointer in nth bitmap block
Size of the unit in logical blocks

For larger disks the following format is used:
(3 bytes)
(1 byte)
(4 bytes)
(246 bytes)

Not used (zero)
Number of storage bitmap blocks (greater than 126)
Size of the unit in logical blocks
Not used (zero)

C-28

KNOWN FILES
NOTE
Current implementations of Files-ii
do
not
correctly initialize the word pairs containing
number of free blocks and free block pointer for
each
bitmap
block,
nor
are these values
maintained as space is allocated and freed on the
unit.
They are therefore best looked upon as 2n
garbage words and should not be used by future
implementations
of
Files-ll until the disk
structure is formally updated.

C.4.2.2 storage Bitmap - Virtual blocks 2 through n+l are the
storage bitmap itself.
It is best viewed as a bit string of
length m, numbered from 0 to m-l, where m is the total number of
logical blocks on the unit rounded up to the next multiple of
4096. The bits are addressed in the usual manner
(packed right
to left in sequentially numbered bytes).
Since each virtual
block holds 4096 bits, n blocks, where n = m/4096,
are used to
hold the bitmap. Bit j of the bitmap represents logical block j
of the volume.
If the bit is set, the block is free.
If clear,
the block is allocated. Clearly the last k bits of the bitmap
are always clear, where k is the difference between the true size
of the volume and m, the length of the bitmap.

The size of the bitmap is limited to 256 blocks.
In fact, due to
existing implementations on all RSX systems,
the retrieval
pointers must be in one of the following two forms:
1.

A single retrieval pointer mapping the entire BITMAP.SYS
file.

Two retrieval pointers, the first mapping the storage
control block only, and the second mapping the entire
bitmap proper.
This restriction limits 005-1 to a volume of 4096*255
blocks (1,044,480 blocks or about 500 megabytes).

C.4.3

Bad Block File

The bad block file is File 10 3,3,0. It is listed in the MFO as
BAOBLK.SYSji. The bad block file is simply a file containing all
of the known bad blocks on the volume.

C-29

KNOWN FILES
C.4.3.1 Bad Block Descriptor - The last virtual block of the bad
block file is the bad block descriptor for the volume. It is
always located on the last good block of the volume. This block
may contain a listing of the bad blocks on the volume produced by
a bad block scan program or diagnostic. The format of the bad
block data is identical to the map area of a file header, except
that the first four entries (M.ESQN, M.ERVN, M.EFNU, and M.EFSQ)
are not present. The last word of the block contains the usual
additive checksum.
(See earlier in this
chapter
for
a
description of the map area.) This block is included in the bad
block file to save
the
data
it
contains
for
future
re-initialization of the volume.

Bad Block Descriptor Layout

-------------------1-------------------1
LBN Field Size
1 count Field Size 1
-------------------1-------------------1
Map words Avail.
Map Words in Use
-------------------1-------------------1
1

1
1

Retrieval Pointers

1
1
1
1

---------------------------------------1
Block Checksum

---------------------------------------1

C.4.4

•
•

Master File Directory

The master file directory is File 10 4,4,0. It is listed in the
MFO (itself) as OOOOOO.OIR;l.
The MFO is the root of the
volume's directory structure. It lists the five known files,
plus whatever the user chooses to enter .

C.4.S

Core Image File

The core image file is File 10 5,5,0. It is listed in the MFO as
CORIMG.SYS;l.
Its use is operating system dependent.
In
general, it provides a file of known File 10 for the use of the
operating system, for use as a swap area, for example, or as a
monitor overlay area, etc.
C-30

FCS FILE STRUCTURE
C.S

FCS FILE STRUCTURE

File Control Services (FCS) is a user level interface to
Files-ll.
Its principal feature is a record control facility
that allows sequential processing of variable length records and
sequential and random access to fixed length record files. FCS
interfaces to the virtual block facility provided by the basic
Files-ll structure.

C.S.l

FCS File Attributes

FCS stores attribute information about the file in the file's
user attribute area. (Refer to the discussion of the H.UFAT byte
in Section C.2.4.1.) It uses only the first 7 words.
The rest
are ignored by FCS, but are reserved by DEC. (RMS uses an
additional 3 words, 10 words in all, for relative and indexed
file attributes.) The following items are contained in the
attribute area.
They are identified by the usual symbolic
offsets (relative to the start of the attribute area). The
offsets may be defined in assembly language programs by calling
and invoking the macro FDOFF$ DEF$L. Flag values and bits may be
defined by calling and invoking the macro FCSBT$.
These macros
are in the system macro library of any operating system that
supports Files-ll. Alternatively, all these values are defined
in the system object library of any system that supports
Files-ii, and may be obtained at link time.

C.S.1.1 F.RTYP: 1 Byte - Record Type - This byte identifies
which type of records are contained in this file. The following
three values are legal:

R.FIX
R.VAR
R.SEQ

Fixed length records.
Variable length records.
Sequenced Variable Length records

F.RATT: 1 Byte - Record Attributes - This byte contains
record attribute bits that control the handling of records under
various contexts. The following flag bits are defined:
C.S.1.2

FD.FTN

Use Fortran carriage control if set.
The first byte of each record is to be
interpreted as
a
standard
Fortran
carriage
control character when the
record is copied to a carriage control
device.
C-31

FCS FILE STRUCTURE
FD.CR

Use implied carriage control if set.
When the file is copied to a carriage
control device, each record is to be
preceded by a line feed and followed by
a carriage return. Note that the FD.FTN
and FD.CR bits are mutually exclusive.

FD.PRN

Used to indicate that the two byte
sequence number field for R.SEQ record
format is to be interpreted as print
control information. See later in this
appendix for format of print information.

FD.BLK

Records do not cross block boundaries if
set. Generally, there will be
dead
space at the end of each block. How
this is handled is explained in the
description of record structure in Section
C.S.2.1.

F.RSIZ: 2 Bytes
Record Size - In a fixed length
record file, this word contains the size of the records in bytes.
In a variable or sequenced variable length record file, this word
contains the size in bytes of the longest record in the file.

C.S.l.3

C.S.l.4 F.HIBK: 4 Bytes - Highest VBN Allocated - This 32 bit
number is a count of the number of virtual blocks allocated to
the file. Since this value is maintained by FCS, it is usually
correct, but it is not guaranteed since FCS is a user level
package.

C.S.l.S F.EFBK: 4 Bytes - End of File Block - This 32 bit
number is the VBN in which the end of file is located. Both
F.HIBK and F.EFBK are stored with the high order half in the
first two bytes, followed by the low order half.

F.FFBY: 2 Bytes - First Free Byte - This word is a
count of the number of bytes in use in the virtual block
containing the end of file. In other words, it is the offset to
the first byte of the file available for appending. Note that an
end of file that falls on a block boundary may be represented in
either of two ways.
If the file contains precisely n blocks,
F.EFBK may contain nand F.FFBY will contain 512., or F.EFBK may

C.S.l.6

C-32

FCS FILE STRUCTURE
contain n+l and F.FFBY will contain O.

C.S.1.7 S.FATT: 14 Bytes
symbol represents the total
attribute block.

C.S.1.8

Size of Attribute Block - This
number of bytes in the FCS file

FCS File Attributes Layout -

-------------------1-------------------1
Record Attr.
1 Record Type
1
-------------------1-------------------1

F.RATT

Record Size (Bytes)

---------------------------------------1
Highest VBN

F.RTYP
F.RSIZ
F.HIBK

--I
Allocated

---------------------------------------1
End of File
VBN

---------------------------------------1
First Free Byte

---------------------------------------1

C.S.2

F.EFBK

--I
I
F.FFBY
S.FATT

Record Structure

This section describes how records are packed in the virtual
blocks of a disk file.
In general, FCS treats a disk file as a
sequentially numbered array of bytes.
Records are numbered
consecutively starting with 1.

C.S.2.1 Fixed Length Records - In a file consisting of fixed
length records, the records are simply packed end to end with no
additional control information.
If the record length is odd,
each record is padded with a single byte. The content of the pad
byte is undefined.
For direct access, the address of a record is
computed as follows:
Let:

n
k
m

record number
record size (in bytes)
byte address of record in file
C-33

FCS FILE STRUCTURE
q
j

i
then

h
m
j
i

number of records per block
VBN containing the start of the record
byte offset within VBN j
((k+1}/2}2 (rounded up record length)
(n-1}h
m/512+1 (truncated)
m mod 512

The previous discussion assumes that records
cross
block
boundaries (that is, FD.BLK is not set).
If records do not cross
block boundaries,
they are limited to 512 bytes,
and the
following equations apply (the variables are defined as above):
h
q
j

((k+1}/2)2 (rounded up record length)
512/k (truncated)
(n-1)/q+1 (truncated)
((n-1) mod q)h

C.S.2.2 Variable Length Records - In a file consisting
of
variable length records,
records may be up to 32767 bytes in
length. Each record is preceded by a two byte binary count of
the bytes in the record (the count does not include itself).
For
example, a null record is represented by a single zero word.
The
byte count is always word aligned.
For example,if a record ends
on an odd byte boundary, it is padded with a single byte.
The
content of the pad byte is undefined.
If records do not cross block boundaries (FD.BLK is set),
they
are limited to a size of 510 bytes. A byte count of -1 is used
as a flag to signal that there are no more records in a
particular block. The remainder of that block is then dead space
and the next record in the file starts at the beginning of the
next block.

C.S.2.3 Sequenced Variable Length Records - The format of a
sequenced file is identical to a variable length record file
except that a two byte sequence number field is
located
immediately after the byte count field of each record. This
field contains a binary value which is usually interpreted as the
line number of that record (see F.RATT,
FD.PRN and Section
C.5.2.3.1. The sequence number is not returned as part of the
data when a record is read, but is available separately. Note
that the record byte count field counts the sequence number field
as well as the data of the record.

C-34

FCS FILE STRUCTURE

Format of Two Byte Print Control Field in R.SEQ Records - If the
FD.PRN bit is set in the record attribute then the two byte
"sequence number" field is used to contain carriage control data
for the record. Byte 0 is print control information to act upon
before the record data is output to a unit record device. Byte 1
is print control information to act upon after the record data
has been output to a unit record device.

C-35

APPENDIX 0
FILES-ll 010 INTERFACE TO THE ACPS

This appendix describes the QIO level interface to the file
processors
(ACPs).
These include F11ACP for Files-11 disks and
MTAACP for ANSI magnetic tape.
F11ACP supports the following functions:
IO.CRE
IO.DEL
IO.ACR
IO.ACW
IO.ACE
IO.DAC
IO.EXT
IO.RAT
IO.WAT
IO.FNA
IO.RNA
IO.ENA
IO.ULK

0.1

Create file
Delete file
Access file for read only
Access file for read/write
Access file for read/write/extend
Deaccess file
Extend file
Read file attributes
Write file attributes
Find file name in directory
Remove file name from directory
Enter file name in directory
Unlock block

010 PARAMETER LIST FORMAT

The device-independent part of a file processing QIO parameter
list is identical to all other QIO parameter lists. The file
processor QIOs require the following six additional words in the
parameter lists:
Parameter Word 1
Parameter Word 2

Address
of
a
3-word
block
containing the file identifier
Address of the attribute list

Parameter words 3 & 4

Size and extend control information

Parameter Word 5

Window size information and
control
D-1

access

QIO PARAMETER LIST FORMAT
Address of the file name block

Parameter word 6

NOTE

The P/OS Executive treats File Identifier Blocks,
filename blocks, and attribute list entries as
read/write data. For this reason, they may not
be used in read-only code segments or libraries.

0.1.1

File Identification Block

The File Identification Block is a 3-word
file number and the file sequence number.
Identification Block is as follows:

block containing the
The format of the File

1
File Number
1
1-------------------------------1
File Sequence Number
1-------------------------------1
1

Reserved

FllACP uses the file number as an index to the file header in the
index file. Each time a header block is used for a new file, the
file sequence number is incremented. This insures that the file
header is always unique. The third word is not currently used
but is reserved for the future.

0.1.2

The Attribute List

The file attribute list controls FllACP reads or writes.
File
attributes are fields in the file header, described later in this
appendix.
The attribute list contains a variable number of
entries
terminated by a byte containing zero (0). The maximum number of
entries in the attribute list is six.
An entry in the attribute list has the following format:
.BYTE
. WORD

<Attribute type), Attribute size
Pointer to the attribute buffer

0-2

QIO PARAMETER LIST FORMAT
The Attribute Type - This field identifies the individual
attribute to be read or written. The sign of the attribute type code
determines whether the transfer is a read or write operation. If the
type code is negative, the ACP reads the attribute into the buffer.
If the type code is positive, the ACP writes the attribute to the file
header.
Note that the sign of the type code must agree with the
direction implied by the operation. For example, if the type code is
positive, the operation must be an IO.WAT or IO.DAC.
D.l.2.1

The attribute type is one of the following:
o

File owner (H.FOWN)
The file owner UIC is a binary word.
The low byte
owner number and the high byte is the group number.
File protection (H.FPRO)
The file protection word is a
format:

bit

mask

with

the

following

Each of the fields contains four bits, as follows:
Bit 1
Bit 2
Bit 3
Bit 4
o

File characteristics (H.UCHA)
The following user characteristics are currently contained
the i-byte H.UCHA field:
UC.CON
UC.OLK

Read Access
Write Access
Extend Access
Delete Access

200
100

Logically contiguous file
File improperly closed

Record I/O Area (U.UFAT)
This field contains a copy of the first seven*
file descriptor block.

words

the

File name (I.FNAM)
The file name is stored as nine Radix-50 characters.
the
fourth word of this block contains the file type and the fifth
word contains the version number.

File type (I.FTYP)
The file type is stored as three Radix-50 characters.

Version number (I.FVER)

1. RMS uses 32 bytes.
sequential files.

The first seven are

0-3

compatible

with

FCS

for

QIO PARAMETER LIST FORMAT
The version number is stored as a binary number.
o

Expiration date (I.EXOT)
Creation date (I.CROT)
Revision date (I.RVOT)
The expiration date is currently unused.
When the file
is
created,
the ACP initializes the creation date to the current
date and time.
It initializes the expiration and revision
dates to O.
The ACP sets the revision date to the current
date and time each time the file is deaccessed.

Statistics block
This block is described later in this appendix.

Read entire file header
This buffer is assumed to be 1000
write this attribute.

blocks

long.

You

cannot

Revision number (I.RVNO)
The ACP sets the revision number to 0, and increments it every
time the file is deaccessed.

Placement Control

D.1.2.2 Attribute Size - This word specifies the number of bytes of
the attribute to be transferred.
Legal values are from 1 to the
maximum size of the particular attribute.
Table D-l shows the maximum
size for each attribute type.

Table 0-1:

Maximum Size for Each File Attribute

Attribute
Type Code

Attribute
Type

Maximum
Attribute Size
in Octal Bytes

File owner

Protection

File characteristics

Record I/O area

0-4

QIO PARAMETER LIST FORMAT
12

File name,type,version number

File type

Version number

Expiration date

Statistics block

Entire file header

Block Size (magtape only)

Revision number and
creation/revision/expiration dates

Placement control

D.l.2.3 Attribute Buffer Address - The attribute Buffer
Address
field contains the address of the buffer in the user's task space to
or from which the attribute is to be transferred.

0.1.3

Size and Extend Control

These two parameters specify how many blocks the file processor
allocated to a new file or adds to an existing file. These
parameters also control the type of block allocation.
The format is as follows:
.BYTE
.WORD

The size field specifies the number of blocks to be allocated to a
file on IO.CRE and IO.EXT operations, and the final file size on
IO.DEL operations.
The extend control field controls the manner in which an
operation is to be done. The following bits are defined:
EX.AC1=1

The extend size is to be
block.

EX.AC2=2

Extend by the largest available
up to the specified size.

0-5

added

extend

contiguous

piece

QIO PARAMETER LIST FORMAT

0.1.4

EX. FCO=4

The file must end up contiguous.

EX.AOF=10

Use the default rather than the specified size.
The default extend size is the size that was
specified when the volume was mounted.

EX.ALL=20

Placement control (see Section 0.2.

EX.ENA=200

Enable extend.

Window Size and Access Control

This parameter specifies the window
information in the following format:
.BYTE

size

and

access

control

the

access

control

This word is only processed if the high bit of
byte (AC.ENB) is set.

Window size is the number of mapping entries.
Specifying a negative
window size minimizes window turns.
If this byte is zero, the file
processor uses the volume default. The size of the window allocated
in the dynamic storage region is 6 times the number of mapping
entries (each mapping entry is 3 words),
plus 10 bytes for the
window
control block.
The mapping entries are allocated in
secondary pool. The window control block and a pointer to secondary
pool are located in primary pool.
The following access control bits are defined:
AC.LCK=l
AC.OLK=2

AC.LKL=4
AC.EXL=10
AC.WCK=40
AC.ENB=200

Lock out further accesses for Write or Extend
Enable Oeaccess lock
The deaccess lock sets the lock bit in the file
header if the file is deaccessed as the result of a
task exit without explicitly deaccessing the file.
The lock bit is set by the executive. The lock bit
is not set when the system crashes.
Enable block locking
Enable explicit block unlocking
Initiate driver write-checking
Enable Access
NOTE

0-6

QIO PARAMETER LIST FORMAT
Both AC.LKL and AC.EXL must be set if
you want block locking. If you do not
want block locking, both bits must be
clear.
Any other combination is an
error.

0.1.5

File Name Block Pointer

This word contains the address of a lS-word block in the issuing
task's space.
This block is called the file name block. The file
name block is described in detail later in this appendix.
The fields of the file name block that are particularly
file-processing operations are:
o

Directory identification (N.DID)
This field is required for all disk operations.
the directory to which the operation applies.
not used for tape operations.

important

It specifies
This field is

File identification (N.FID)
This field is required as input for enter operations.
This
field is returned as output by find and remove operations.

File name (N.FNAM), type (N.FTYP), and version number (N.FVER)
These fields are required as input to enter, find, and remove
operations.
For
find and remove operations, the file
processor locates the appropriate entry by matching the
information in these fields with the directory entries.

Status word (N.STAT)

Wildcard context (N.NEXT)
This field is required as input for wildcard operations.
It
specifies the point at which to resume processing. It is
updated for the next operation. It must initially be set to

0.2

PLACEMENT CONTROL

The placement control attribute list entry controls the placement of a
file in a particular place on the disk. You can specify either exact
or approximate placement on IO.CRE and IO.EXT operations.

D-7

PLACEMENT CONTROL
The placement control entry must be the first entry in
list.
The format of
follows:
.BYTE
. WORD
. WORK
.BLKW

the

placement

control

attribut~

list

the

attribute

entry

placement control,O
high-order bits of VBN or LBN
low-order bits of VBN or LBN
4
Buffer to receive starting and ending LBN if
AL.LBN is set.

The following bits are defined for the placement control field:
AL.VBN=1
AL.APX=2
AL.LBN=4

0.3

Set if block specified is a VBN;
otherwise,
the
block is the LBN
Set if you want approximate placement;
otherwise, placement is exact
Set if you want starting and ending LBN information

BLOCK LOCKING

Block locking only occurs when the user accesses a
file with AC.LKL
and AC.EXL set in the access control byte of the parameter list. Any
read or write operation causes a check to see if the block is locked.
A write access locks a block for exclusive access. A write operation
can only access a block that is not locked by any accessor.
The only
exception to this is an exact match with a previous lock owned by the
same accessor.
A read access locks a block for shared access.
access any block locked for shared access.

A read

operation

can

The user must unlock a block with an explicit unlock request,
IO.ULK may be used to unlock one or all blocks.

IO.ULK.

If all accessors to a file have not requested block locking,
returns an error.

the

ACP

accessor

are

When the file is deaccessed, all
released.

locks

owned

the

Each active lock requires eight bytes from the dynamic storage region.
This storage is deallocated when the file is deaccessed.

D-8

SUMMARY OF F11ACP FUNCTIONS
0.4

SUMMARY OF FllACP FUNCTIONS

The following is a summary of the functions implemented in F11ACP.
A
list of accepted parameters follows each function. All parameters are
required unless specified as optional. Parameters other than those
listed are illegal for that function and must be O.
IO.CRE

Create file
#1

The file identifier block is filled in with the file
identifier and sequence number of the created file.

Write Attribute and/or
Placement
Control
list
(optional)
#3 & #4 Extend Control (optional)
The amount allocated to the file is returned in the
high byte of IOST(l) plus IOST(2).
#5
IO.DEL

May be nonzero but must be disabled
Delete or truncate file

Optional if the file is accessed

#3 & #4 Size to truncate the file to. If not enabled, the
file is deleted. If enabled, the remaining 31 bits
specify the size the file is to be after truncation.
The change in file allocation is returned in the high
byte of IOST(l) plus IOST(2). This amount will be
zero or negative.
IO.ACR

Access file for read only

IO.ACW

Access file for read/write

IO.ACE

Access file for read/write/extend
#1

File identifier pointer

Read attributes control (optional)

Access control must be enabled

IO.OAC

Oeaccess file
#1

File identifier pointer (optional)

Write attributes control list

May be nonzero but must be disabled

0-9

SUMMARY OF F11ACP FUNCTIONS
IO.EXT

Extend file
#1

Optional if file is accessed

Placement control attribute list (optional)

#3 & #4 Extend control
The amount allocated to the file is returned
high byte of IOST(l) plus IOST(2).
IO.RAT

the

Read attributes
access~d

Optional if file is

Read attributes control list

IO.FNA

Find name in directory

IO.RNA

Remove name from directory

IO.ENA

Enter name in directory
#S

May be nonzero but must be disabled

File name block pointer

IO.ULK

Unlock block

o or count of blocks to unlock

#4 & #S Starting VBN to unlock or 0 to unlock all blocks.
IO.RVB

Read virtual block

IO.WVB

Write virtual block
#1

User buffer

Buffer length

#4 & #S·VBN

0.5

HOW TO USE THE ACP OIOS

Although the operations described in this section are normally
performed by the file-access methods (RMS and FCS), your application
~ay issue the ACP QIOs.
The required parameters for each QIO are
described above. The necessary steps for common operations follow.

D-10

HOW TO USE THE ACP QIOS
NOTE
The file identifier is the only
file.

0.5.1

way

refer

Creating a File

To create a file:
o

Use IO.CRE to create it.

Enter it in the Master
directory with IO.ENA.

0.5.2

File