Digital PDFs

AA-L680B-TC

April 1983

465 pages

Original

27MB

Document:	RSX-11M/M-PLUS Task Builder Manuai
Order Number:	AA-L680B-TC
Revision:	0
Pages:	465
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V4.1_Apr83/4_ProgramDevelopment/AA-L680B-TC_tkb_198304.pdf

OCR Text

RSX-11 M/M-PLUS
Task Builder Manuai
Order No. AA-L6808-TC

RSX-11 M Version 4.1
RSX-11 M-PLUS Version 2.1

digital equipment corporation . maynard, massachusetts

First Printing: June 1979
Revised, January 1982
Revised, April 1983
The information in this d-0cument is subject to change without notice
and should not be construed as a commitment by Digital Equipment
Corporatione Digital Equipment Corporation assumes no responsibility
for any errors that may appear in this document.
The software described in this document is furnished under a license
and may be used or copied only in accordance with the terms of such
license.
No responsibility is assumed for the use or reliability of software on
equipment that is not supplied by Digital Equipment Corporation or its
affiliated companies.

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

DIBOL
EduSystern
IAS
MAS SB US
PDP
PDT
RSTS

RSX
UNIBUS
VAX
VMS
VT

~nmnomo
ZK2250

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

800-258-1710

In New Hampshire, Alaska, and Hawaii call
In Canada call

603-884-6660

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

DIRECT MAIL ORDERS (USA & PUERTO RICO}*
Digital Equipment Corporation
P.O. Box CS2008
Nashua. New Hampshire 03061

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

DIRECT MAIL ORDERS (INTERNATIONAL}
Digital Equipment Corporation
A&SG Business Manager
clo Digital's local subsidiary or
approved distributor

*Any prepaid order from Puerto Rico must be placed
with the local Digital subsidiary (809-754-7575)
Internal orders should be placed through the Software Distribution Ceriter (SLJCJ. D1g1tai Equiprneni
Corporation. Northboro. Massachusetts 01532

CONTENTS

Page
PREFACE

SUMMARY OF TECHNICAL CHANGES

xix

CHAPTER 1
1.1
1.1.1
1.1.2
1.2
1.3
1.4
1.5
1.6
1. 7
1.8
CHAPTER 2
2.1
2 .1.1
2.1.1.1
2.1.1.2
2 .1. 2
2.2
2.3
2.4
2.4.1
2.4.2
2.4.3
2.4.4
2.5
2.5.1
2 .. 6''
'2 .. 6'.l
2.7
2.8
2.9
CHAPTER 3
3.1
3 .1.1
3 .1. 2
3.2
3.2.1
3.2.2

INTRODUCTION AND COMMAND SPECIFICATIONS
TASK COMMAND LINE
• • • • • • •
Printing the Map File
••••
Omitting Specific Output Files
MULTILINE INPUT
. • . • •
OPTIONS
• . • • • • • • • •
MULTIPLE TASK SPECIFICATIONS •
INDIRECT COMMAND FILES
COMMENTS IN LINES
FILE SPECIFICATIONS
SUMMARY OF SYNTAX RULES
• • • •

•
• • • • • • • •
•
• • • • •
•
. •
•
• • • • • • • •
•

•
•
•
•
•
•
•
•

1-2
1-2
1-3
1-3
1-4
1-5
1-5
1-8
1-8
1-10

TASK BUILDER FUNCTIONS
LINKING OBJECT MODULES • • • • • • •
Allocating Program Sections
• •
Access-code and Allocation-code
Type-Code and Scope-Code •
• • • • •
Resolving Global Symbols
• • • • • •
THE TASK STRUCTURE • •
OVERLAYS • • • • • • • • • • • • • •
ADDRESSING CONCEPTS
• • •
Physical, Virtual, and Logical Addresses •
Unmapped Systems • • .
Mapped Systems
Regions
TASK MAPPING AND WINDOWS • • • • •
Task Windows • • • • .
• • •
RSX-llM-PLUS SUPERVISOR MODE •
• •
Supervisor-Mode Mapping
PRIVILEGED TASKS . _- . • • •
MULTIUSER TASKS (RSX-llM-PLUS ONLY)
USER-MODE I- AND D-SPACE TASKS (RSX-llM-PLUS)

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

• • 2- 7
• • 2- 7
• 2-8
2-10
• 2-13
2-13
2-14
2-14
2-18
2-20

2-20
• ' ,2-,,24
•
2:..2,4

2-25
2-28

2-28

OVERLAY CAPABILITY
OVERLAY STRUCTURES • • . • • • • . • • • • .
• 3-1
Disk-Resident Overlay Structures • • • • • • • • 3-2
Memory-Resident Overlay Structures (Not
Supported on RSX-llS)
• • • 3-5
OVERLAY TREE • . • • • . . • •
3-15
Loading Mechanism
••..•
3-16
Resolution of Global Symbols in a Multisegment
Task . . . • • • • . . . • • • • • • • • . • • 3-16
iii

CONTENTS
Page
3.2.3

Resolution of Global Symbols from the Default
Library
• • • • • • • • • • •
Allocation of Program Sections in a
Multisegment Task
••••••••••••••
OVERLAY DATA STRUCTURES AND RUN-TIME ROUTINES
Overlaid Conventional Task Structures

3.2.4
3.3
3.3.1

'~··~·~·~·~{,:.>;' .··c;~.g~l~~·~'&~~:2if:~16~~2~·gij·~~~1i:~ :·~~·~µ;::t;~l?~~·"; 2' •

•

3.4.1
3.4.2
3.4.3
3.4.3.l
3.4.3.2
3.4.3.3

.ROOT and .END Directives • • • • • • • • • •
.FCTR Directive • • • • • • • • • • • • • • •
Arguments for the .FCTR and .ROOT Directives •
Named Input File • • • • • • • • • • • • • •
Specific Library Modules • • • • • • •
A Library to Resolve References Not
Previously Resolved
• • • • • • • • • • • •
3.4.3.4
A Section Name Used in a .PSECT Directive
A Segment Name Used in a .NAME Directive • •
3.4.3.5
3.4.4
Exclamation Point Operator • • • • • • • • • •
.NAME Directive
••••••••••
3.4.5
Example of The Use of The .NAME Directive
3.4.5.1
.PSECT Directive • • • • •
• ••••
3.4.6
Indirect Command Files • • • • • •
• •••
3.4.7
MULTIPLE-TREE STRUCTURES • • • • • • • • • • • •
3.5
3.5.1
Defining a Multiple-Tree Structure • • • • • •
Defining Co-trees With a Null Root by Using
3.5.1.1
• NAME • • • • • • • • • • • • • • • • • • •
3.5.2
Multiple-Tree Example • • • • • • • • • • • •
CREATING AN ODL FILE FROM A VIRTUAL ADDRESS SPACE
3.6
ALLOCATION DIAGRAM • • • • • • • • • • • • • • •
3.6.1
Creating a .ROOT Statement by Using a Virtual
Address Space Allocation Diagram • • • • • • •
3.6.2
Creating a .FCTR Statement by Using a Virtual
Address Space Allocation Diagram • • • • • • •
3.6.3
Creating an ODL Statement for a Co-Tree by
Using a Virtual Address Space Diagram • • • •
3.7
OVERLAYING PROGRAMS WRITTEN IN A HIGH-LEVEL
LANGUAGE
• • • • • • • • • • • • • • • • • • •
3.8
EXAMPLE 3-1: BUILDING AN OVERLAY • • • • • • • •
SUMMARY OF THE OVERLAY DESCRIPTION LANGUAGE
3.9
CHAPTER 4
4.1
4 .1.1
4 .1. 2
4 .1.3
4 .1. 4
4.2
4.2.1

.4.,4·. 2.·
4.2.3

4ii2·

4.3'
4.4
4.5

CHAPTER 5
5.1
5 .1.1
5 .1. 2

3-18
3-19
3-19
3-20
·····64~1'

·,·f.:2;3·
3-23
3-25
3-25
3-25
3-26
3-26
3-26
3-26
3-26
3-27
3-28
3-29
3-30
3-30
3-30
3-31
3-31
3-35
3-37
3-38
3-39
3-40
3-41
3-49

OVERLAY LOADING METHODS
AUTOLOAD • • • • • •
• • • • • 4-1
Autoload Indicator •
• • • •
• • 4-2
Path Loading • • •
. • • •
• • • • • 4-3
Autoload Vectors •
• 4-4
Autoloadable Data Segments • • • • • • • • • • • 4-7
MANUAL LOAD • • • • • • • • •
• • • •
• • 4-7
MACR0-11 Manual Load Calling Sequence • • • • • 4-7
· MACR0-11 Manual Loaq C~ll;in9 ·,se:q:u:~n;c~. F9r· I~ ';:i.nd;',;/ ;
.o-Spaqe Tasks . • • ~: ·." .• :·· :- ··: ... · •: ·,,,g:;.,, • ,,. .... ,'.. :. ~a·
FORTRAN Manual Load Calling Sequence • •
• : 4·_:9

· ·: ·:EiORT;~~N,~M~hua;;t:' ;Lpa.~·: .;a~~~ iir\9'. "~e·gµ~n~~ :·.;Ao.i;

... :•:.~Af~R~~x''fi~q.}{·~·.:~:/~·:r,.'.<)~.· ··~g;:::;··~·".;,.G;_,?:·~1.:(~~;~;;/tAx.

ERROR HANDLING • • • • • • • • • • • • • • •
GLOBAL CROSS-REFERENCE OF AN OVERLAID TASK •
USE AND SIZE OF OVERLAY RUNTIME ROUTINES • • • •

1
4-12
4-14

SHARED REGION CONCEPTS AND EXAMPLES
SHARED REGIONS DEFINED
. • • • •
The Symbol Definition File . • • •
Position-Independent Shared Regions
iv

• 5-1
• 5-4
. 5-5

CONTENTS
Page
Position-Independent Shared Region Mapping • • 5-5
Specifying a Position-Independent Region • • • 5-5
Absolute Shared Regions
• • • • • • •
5-7
Absolute Shared Region Mapping • • • • •
• 5-7
Specifying an Absolute Shared Region • •
5-7
Absolute Shared Region .STB File • • • •
• 5-9
Shared Regions with Memory-Resident Overlays • • 5-9
Considerations About Building an Overlaid
Shared Region
•••••••••••••
5-9
Example of Building a Memory-Resident
5.1.4.2
Overlaid Shared Region • • • • • • • • •
5-10
Options for Use in Overlaid Shared Regions • 5-10
5.1.4.3
Autoload Vectors and .STB Files for Overlaid
5.1.4.4
Shared Regions • • • • • • • • • • • • • • • 5-11
Run-Time Support for Overlaid Shared Regions • 5-13
5.1.5
Linking to a Shared Region • • • • • • • • • • 5-13
5.1.6
Number and Size of Shared Regions
• • • • 5-17
5.1.7
5.1.8
Example 5-1: Building and Linking to a Common
in MACR0-11
• • • • • • • • • • • • • • • • • 5-17
5.1.9
Linking Shared Regions Together
• • • • • 5-25
Example 5-2: Building and Linking to a Device
5.1.10
Common in MACR0-11 • • • • • • • • • • • • • • 5-26
Example 5-3: Building and Linking to a Resident
5.1.11
Library in MACR0-11
• • • • •
5-31
5.1.11.1
Resolving Program Section Names in a
Shared Region • • • • • • • • • • • • • • • 5-39
Example 5-4: Building a Task That Creates a
5.1.12
Dynamic Region • • • • • • • .
• •••
5-40
CLUSTER LIBRARIES
• • • • •••••
5.2
5-43
5.2.1
Building the Libraries
• • • • • • • • • 5-44
5.2.1.1
Summary of Rules for Building the Libraries
5-44
5.2.1.2
Rule 1: All Libraries but the First Require
Resident Overlays
• • • • • • • • • • • • • 5-45
5.2.1.3
Rule 2: User Task Vectors Indirectly Resolve
all Interlibrary References
• • • • • • • • 5-46
5.2.1.4
Rule 3:
Revectored Entry Point Symbols Must
Not Appear in the "Upstream" .STB File •
5-47
5.2.1.5
Rule 4: A Called Library Procedure Must Not
Require Parameters on the Stack
5-47
5.2.1.6
Rule 5:
All the Libraries Must be PIC or
Built for the Same Address • • • • • • •
5-47
5.2.1.7
Rule 6:
Trap or Asynchronous Entry Into a
Library is not Permitted • • • • • • • • • • 5-47
5.2.2
Building Your Task • • • • • • • • • • • •
5-48
5.2.3
Examples • • • • • • • • • • • • • • • • •
5-48
5.2.3.l
F77CLS -- Build the Default Library for the
FORTRAN-77 OTS • • • • • • • • • • • • • • • 5-48
5.2.3.2
FDVRES -- Build an FMS-11/RSX Vl.O Shareable
Library
• • • • • • • • • • • • • •
5-49
5.2.3.3
FDVRESBLD.ODL -- Overlay Description for
FMS-11/RSX Vl.O Cluster Library • • • •
5-51
5.2.3.4
FCSRES Library Build • • • • • • • • • •
5-51
5.2.3.5
F77TST.CMD -- File to Build the FMS-11/RSX
Vl.O FORDEM Test Task
•.•••••
5-51
Overlay Run-Time Support Requirements
• • • • 5-51
5.2.4
5.3
VIRTUAL PROGRAM SECTIONS •
• • • • • • • • • 5-53
FORTRAN Run-Time Support for Virtual Program
5.3.1
Sections • • • • • • • •
5-56
Example 5-5: Building a Program that Uses a
5.3.2
Virtual Program Section
• • • • • • • • • • • 5-58
5.1.2.1
5.1.2.2
5.1.3
5.1.3.1
5.1.3.2
5.1.3.3
5.1.4
5.1.4.1

CHAPTER 6
6.1

PRIVILEGED TASKS
INTRODUCTION • • • • • • • • • • • • • • • • • • • 6-1
v

CONTENTS

6.2
6.3
6.4
6.5
6.6
6.7
6.8
6.9

CHAPTER 7

7.1
7.2
7 •.3

T.4
7.5
7.6

7.7
7.8
7.8.l
7.9

PRIVILEGED AND NONPRIVILEGED TASK DISTINCTION
PRIVILEGED TASK HAZARDS
. . • • •
SPECIFYING A TASK AS PRIVILEGED
PRIVILEGED TASK MAPPING
/PR:O PRIVILEGED TASK
• ~ ••
/PR:4 PRIVILEGED TASK • • • •
/PR:5 PRIVILEGED TASK
EXAMPLE 6-1:
BUILDING A PRIVILEGED TASK TO
EXAMINE UNIT CONTROL BLOCKS • • • • • •

7.9.2
CHAPTER 8

8.1
8.2
8.3
8.4
8.5
8.5.1
8.5.2

6-6

OSER-MODE l- AND D-SPACE (RSX-UM-PLUS ONLY).
USER TASK DATA SPACE DEFINED • • • • • • • • •.•.•. ··r-1
1- AND D-SPACE TASK IDENTIFICATION • • • • • •.•• 7~1
COMPARISON OF CONVENTIONAL TASKS AND I- AND
D-SPACE TASKS
• • ~ • • • • •
7-.2
CONVENTIONAL TASK MAPPING
• • • • •
. 7-2
I- AND D-SPACE TASK MAPPING • • • • • • • •
.• 7-3
TASK WINDOWS IN I- AND D-SPACE TASKS
7-5
• 7-5.
SPECIFYING DATA SPACE IN YOUR TASK •
• • 7 .... 5.
OVERLAID I- AND D-SPACE TASKS
• • • •
Autoload Vectors and .STB Files
• 7-9
I- AND D-SPACE TASK MEMORY ALLOCATION AND EXAMPLE
M,APS

7.9.l

• • 6-1
• • 6-1
6-2
. 6-2
• 6-4
. . 6-5
. 6-5

•

Virtual Memory Allocation for MAIN.TSK • •
Virtual Memory Allocation for MAINID.TSK • • •

7-9
7-10
7-10

SUPERVISOR-MODE LIBRARIES (RSX-llM-PLUS ONLY)
INTRODUCTION • • • • • •
• • • • •
MODE-SWITCHING VECTORS •
•
COMPLETION ROUTINES
• • • •
RESTRICTIONS ON THE CONTENTS OF SUPERVISOR-MODE
LIBRARIES
• • • • • • • • •
• •••••••
SUPERVISOR-MODE LIBRARY MAPPING
• • • • • • • •
Supervisor Mode Library Data • • • • • • • • •
Supervisor Mode Libraries with I- and D-Space

• 8-1
• 8-1
.. 8-2
• 8-2
• 8-3
• 8-3

Tasks
• • • • • • • • • • • • • • • • • • • • • 8-3
BUILDING AND LINKING TO SUPERVISOR-MODE LIBRARIES 8-7
8.6
8.6.1
Relevant TKB Options • • • • •
• • • • • 8-7
8.6.2
Building the Library • • • • • • • • • •
• 8-7
8.6.3
Building the Referencing Task
••••
• 8-7
8.6.4
Mode Switching Instruction •
• 8-8
8.7
CSM LIBRARIES
• • • • • • • • • • • • •
• • 8-8
Building a CSM Library • • • • •
8.7.1
• 8-8
8.7.2
Linking to a CSM Library • • ~
• 8-9
Example CSM Library and Linking Task • •
8.7.3
8-10
8.7.3.1
Building SUPER • • • • • • • • • • •
8-18
Building TSUP • • • • • • • • • • •
8.7.3 .. 2
8-18
8.7.3.3
Running TSUP • • • • • • • • • • • • • • • • 8-19
The CSM Library Dispatching Process
8.7.4
8-19
8.8
CONVERTING SCAL LIBRARIES TO CSM LIBRARIES •
.8-20
USING SUPERVISOR-MODE LIBRARIES AS RESIDENT
8.9
LIBRARIES
••••.••••••••••••
8-20
8.10
MULTIPLE SUPERVISOR-MODE LI BRAR I ES • .. • , • · •
8-20
8 .11
LINKING A RESIDENT LIBRARY TO A SUPERVISOR-MODE
L I BR~ RY
• • • • • • • • • • • • • • .• • , • • • _•
8-21
8 .12
LINKING SUPERVISOR-MODE LIBRARIES
• ~ • • • • • 9;:..21
WRITING YOUR OWN VECTORS AND COMPLETION ROUTINES 8-21
8.13
8 .14
OVERLAID SUPERVISOR-MODE LIBRARIES • • • • • • • 8-21

CONTENTS
Page
MULTIUSER TASKS
~r.1

9 .1.1
9.1·.2·
9.1.3
~L2

CHAPTER 10

··.INTRODUCTION • •
• • • • •
• • • • • • • 9~1·
Overlaid Multiuser Task.·.... • •
• ·9-2
Disk Image 0£ ~ MUltius~t Task •
• • • • • ·~ ~-2.
I- and D-Space Multiuse.r Tasks .'• • • . • • .' • • ·• ... 9-3
EXAMPLE 9-1 :· BUILDING A MULTIUSE.R TASK •
9-5
SWITCHES

10-1
SWITCHES • • • • . • • • • • • . • . • .
10.l
10-5
/AC[:n] -- Ancillary Control Processor •
10.1.l
10-6
/AL
Allocate Checkpoint Space • • • •
10.1.2
/CC
Concatenated Object Modules • • • • • • 10-7
10.1.3
10-8
/CM
Compatibility Mode Overlay Structure
10 .1. 4
10-9
/CO
Build a Common Block Shared Region
10.1.5
• • 10-10
/CP
Checkpointable
. • • •
10.1.6
10-11
/CR
Cross-Reference .
10.1.7
10 .1. 8
/DA
Debugging Aid • •
• • 10-14
10-15
/DL
Default Library .
10.1.9
/EA
Extended Arithmetic Element •
• • 10-16
10.1.10
• • 10-17
/EL
Extend Library
10.1.11
• • 10-18
/FP
Floating Point
•••••
10.1.12
• 10-19
/FU
Full Search . •
• • • •
10.1.13
• • 10-20
/HD
Header
• • • •
• • • •
10.1.14
lQ,.I.15
/ID
I;.... and D-space Task (RSX..;1,lM ..... PLUS Only)·. 10 ..;:.,21
'
' 10-22
/IP
Task Maps I/O Page • . • • • •
10.1.16
• • 10-23
/LB
Library File
••••••
10.1.17
/LI
Build a Library Shared Region •
• • 10-25
10.1.18
• • 10-26
/MA
Map Contents of File
10.1.19
• • • • • 10-27
/MM[:n] -- Memory Management .
10.1.20
• • 10-28
/MP
Overlay Description • •
10.1.21
10.1.22
/MU
Multiuser (RSX-llM-PLUS Only) .• • • ., • 101""29
/NM
No Diagnostic Messages
• • 10-30
10.1.23
10.1.24
/PI
Position Independent
• 10-31
/PM
Postmortem Dump •
• • • •
• 10-32
10.1.25
10.1.26
/PR[:n] -- Privileged
. • . • • . • • • 10-33
/RO
Resident Overlay
. • • • • • • • 10-34
10.1.27
• • 10-35
10.1.28
/SE
Send
• • • • •
/SG
Segregate Program Sections
10-36
10.1.29
10.1.30
/SH
Short Map • • • • . • • • • • • • • • • 10-37
• • 10-44
/SL
Slave • • • • • • •
10.1.31
/SP
Spool Map Output
10.1.32
• • 10-45
/SQ
Sequential
• • • • • • • • • • • 10-46
10.1.33
• • 10-4 7
10.1.34
/SS
Selective Search
/TR
Traceable • • • •
• • • 10-50
10.1.35
/WI
Wide Listing Format
10.1.36
• • 10-51
/XH
External Header (RSX-llM~PLUS only) • .. 10-52
10.1.37
10.1.38
/XT[:n] -- Exit on Diagnostic
• • • • • 10-53

CHAPTER 11
11.1
11.1.1
11.1. 2
1LL3
11.1. 4
11.1. 5

11. l. 6

OPTIONS
OPTIONS
ABORT -- Abort the Task-Build
ABSPAT -- Absolute Patch .
ACTFIL -- Number of Active Files
ASG -- Device Assignment • • • •
CLSTR -- System-Owned Cluster of Resident
Libraries or Commons • • . • • • . • • • •
CMPRT -- Completion Routine -- RSX-llM-PLGS

o.n l y
11.1.7

11-1
11-4
11-5
11-6
11-7
11-8

• • • • • • • • • • • • • • • • • • • • • 11-10
COMMON or LIBR -- System-Owned Resident Common
or System-Owned Resident Library • • • • • • • 11-11

vii

CONTENTS
Page
<tl•l~.~:· .

11.1. 9
11.1.10
11.1.11
11.1.12
11.1.13
11.1.14
11.1.15
11.1.16
11.1.17
11.1.18
11.1.19
11.1.20
11.1.21
11.1.22

Absolute .. ,p~tch .fQr .. D'-:space: • •
J.l::.:13:
EXTSCT
Program Section Extension
. • 11-14
EXTTSK
Extend Task Memory • • •
• • • • 11-15
FMTBUF
Format Buffer Size • • • • •
. • 11-16
GBLDEF
Global Symbol Definition •
11-17
GBLINC
Include Global Symbols •
11-18
GBLPAT
Global Relative Patch
11-19
GBLREF
Global Symbol Reference
• • • • • • 11-20
GBLXCL
Exclude Global Symbols • • • • • • • 11-21
LIBR -- System-Owned Library • • •
• 11-22
MAXBUF -- Maximum Record Buffer Size • •
11-23
ODTV -- ODT SST Vector • • •
• 11-24
PAR -- Partition . • . • • • • • • .
11-25
PRI -- Priority
• • • • • • • • • •
• • 11-27
RESCOM or RESLIB -- Resident Common or
Resident Library • • • • • •
• 11-28
~E~~.IB -:,. . . Re,. ~. id~n~ ...Lil:>:rc:i:rX ~ . '.
. •.... ~ .•. ·. • 11.-}9
···.R~SS···pp: :•-:- ·R.es·ia.·•en.t: ·$:upe.i:::vi.s;or .... !\1aa.:e J~ipr~r;y -:,;; . , ....·. · ; : ·

os·pPA'Jl

; . Rs.~.-tl.1~:-;PL.US .··o,.n l y. .•• · · .· ••• • ·....··,; .

. ..· .•• .....;:'. ,... :.:; ·:.: .. L...

f.•. IJ;:~~l

:ROPA;R --~··:Rea~Oniy J?:arti'tiq·n. 7'";... .RSX-.111.:11;...Plt'Q'Sfl".
~Oril,y,,, •,, :•.:~ ;'.~ ',,·,·,.~,= O·~,~/- .; . l"•·:.·,

.,:.• ~ ~.,;,,,,, . '=~· .;~,.:;,, ,~·,/,,
..·

STACK -- Stack Size

·: ;sti.Pr.irn
11.1.28
11.1. 29
11.1.30
11.1.31
11.1.32
11.1. 33
APPENDIX A
A.l
A.1.1
A. l . 2
A. l. 3
A. l . 4
A. l . 5
A. l . 6
A. l . 7

A.1.8
A. l . 9

A.2
A.3
A.4
A.4.1
A.4.2
Ae4e3
A.4.4
A.4.5
A.4.6
A.4.7
A.4.8
A.4.9
A.4.10
A.4.11
A.4.12
A.4.13
A.4.14
A.4.15
A.5
A.5.1

.. , .•:.

~.~--.:~-~<~ ·<~·~.,/

.· .sl,l~rvisor.-MOde ~:.±.hra.ry; .,_._

•.' .·!}~'·' ·~~t'"';~:~ 'l,i"\~:3::3
•

11-~1.

; ;'.

·.Rsx-;11M-.PLUS )Only
• • • •· ··• . • .
."114j5
TASK -- Task Name
• • • • • . • •
• • • • 11-36
TSKV -- Task SST Vector
• • • • •
• • • • 11-37
UIC -- User Identification Code
11-38
UNITS
Logical Unit Usage
• • • •
• 11-39
VSECT
Virtual Program Section •
11-40
WNDWS
Number of Address Windows •
11-41

TASK BUILDER INPUT DATA FORMATS
DECLARE GLOBAL SYMBOL DIRECTORY RECORD • •
•
Module Name (Type 0) • • •
Control Section Name (Type 1)
• • •
Internal Symbol Name (Type 2)
Transfer Address (Type 3)
Global Symbol Name (Type 4)
• • • •
Program Section Name (Type 5)
••••
•
Program Version Identification (Type 6)
Mapped Array Declaration (Type 7)
••••
Completion Routine Definition (Type 10)
END OF GLOBAL SYMBOL DIRECTORY RECORD • • • • •
TEXT INFORMATION RECORD
• • • •
. •••
RELOCATION DIRECTORY RECORD •
Internal Relocation (Type 1)
Global Relocation (Type 2) •
Internal Displaced Relocation (Type 3) • • • •
Global Displaced Relocation (Type 4)
Global Additive Relocation (Type 5)
Global Additive Displaced Relocation (Type 6)
Location Counter Definition (Type 7)
Location Counter Modification (Type 10)
Program Limits (Type .11) • • • • • •
Program Section Relocation (Type 12) • •
Program Section Displaced Relocation (Type 14)
Program Section Additive Relocation (Type 15)
Program Section Additive Displaced Relocation
(Type 16)
••••••••••••••••••
Complex Relocation (Type 17) • • • • • •
Resident Library Relocation (Type 20)
INTERNAL SYMBOL DIRECTORY RECORD
Overall Record Format
• • • • • •
viii

• A-2
• A-4
• A-5
• A-5
• A-6
• A-6
• A-7
A-10
A-10
A-11
A-11
A-11

A-12
A-14
A-15
A-15
A-16
A-16
A-17
A-17
A-18
A-18
A-19
A-19
A-20
A-21
A-22
A-23
A-24
A-24

CONTENTS
Page
A.5.2
A.5.2.l
A.5.2.2
A.5.2.3

A-25
A-25
A-26

TKB Generated Records (Type 1) • • . •
Start-of-Segment Item Type (1) • • •
Task Identification Item Type (2)
Autoloadable Library Entry Point Item Type
( 3)

•

A.5.3
Relocatable/Relocated Records (Type 2)
Module Name Item Type (1)
••••••
A.5.3.l
A.5.3.2
Global Symbol Item Type (2)
•••.••••
A.5.3.3
PSECT Item Type (3)
•••••••
Line-Number or PC Correlation Item Type {4)
A.5.3.4
Internal Symbol Name Item Type (5)
A.5.3.5
Literal Records (Type 4)
••••••••
A.5.4
END OF MODULE RECORD • • • • . • • . • •
A.6
APPENDIX B

DETAILED TASK IMAGE FILE STRUCTURE

B.l
B.2
B.3
B.3.1
B.3.2
B.4
B.4.1

..)3::~ :4,: 2"',: '

'8 ~ 4. 3 '
0

B.4.4
B.4.5
APPENDIX C
C.l
C.2

APPENDIX D
D.l
D.2
D.2.1
D.2.2
D.2.3

LABEL BLOCK GROUP
• • B-1
CHECKPOINT AREA
• B-9
HEADER • • • • • •
B-10
Low-Memory Context
• • • • • • • • B-10
Logical Unit Table Entry
••••
B-14
TASK IMAGE • • • • •
. • • • • • B-14
Autoload Vectors for Conventional Tasks
• • • B-17
:1ru~.b;'JZoaiJ/ v~c\:'or~·./£0.i:::} ;::r.:"' .~nd.i:: ;o~.9pa~: ~t:~sJNJ}.::·.,'. .

·s-·ra·

Window Descriptor
Region Descriptor

B-20
B-21

HOST AND TARGET SYSTEMS
INTRODUCTION . • • • • • • • • • • • • . • . • • • C-1
EXAMPLE C-1: TRANSFERRING A TASK FROM A HOST TO A
TARGET SYSTEM • • • • • • • • • • • • • • • • • • C-2
MEMORY DUMPS
POSTMORTEM DUMPS
SNAPSHOT DUMP • • • •
Format of the SNPBK$ Macro
Format of the SNAP$ Macro
Example of a Snapshot Dump
RESERVED SYMBOLS

APPENDIX F

IMPROVING TASK BUILDER PERFORMANCE

F.l
F .1.1

F .1. 2
F .1.3

APPENDIX G

;Bi"':t::t'·.

se'gment bescdptor " . . .. :' ..'' ~ . '' ""' . " '"" "'

APPENDIX E

F.2
F.3

A-26
A-27
A-27
A-28
A-29
A-29
A-30
A-30
A-30

EVALUATING AND IMPROVING
Table Storage • • • •
Input File Processing
Summary • • • • • • •
MODIFYING COMMAND SWITCH
THE SLOW TASK BUILDER •
THE FAST TASK BUILDER

• • D-1
• • D-5
• D-6
•

• •

•

• D- 7

• • • • D-8

TASK BUILDER THROUGHPUT • F-1
•
• • • •
• • • F-2
• • • • • •
• • F-6
• • • • • •
• • • • • F-6
DEFAULTS
• • F-7
• • • • •
F-11

CONTENTS
Page

ERROR MESSAGES

APPENDIX H
GLOSSARY
INDEX

EXAMPLES
EXAMPLE 3-1
3-2
4-1
5-1
5-1
5-1
5-1
5-1
5-2
5-2
5-2
5-2
5-3
5-3
5-3
5-3
5-4
5-4
5-5
5-5
6-1
6-1

7-:li
7H2,
8-:J.;

s:-2 '
9~~

'I•

8~4!

S-IS
c··
9:-rli
.1

~d~'
l0-1

10-2
C-1
C-1
D-1
D-2
D-3
D-4

Map File for OVR.TSK • • • • • • • • • • • • • • 3-44
Map File for RESOVR.TSK • • • • • • • •
3-47
Cross-Reference Listing of Overlaid Task •
4-13
Part 1 Common Area Source File in MACR0-11
5-18
Part 2 Task Builder Map for MACCOM.TSK • • • • 5-19
Part 3 MACR0-11 Source Listing for MCOMl
5-21
Part 4 MACR0-11 Source Listing for MCOM2
5-22
Part 5 Task Builder Map for MCOMl.TSK •
5-24
Part 1 Assembly Listing for TTCOM •
5-27
Part 2 Task Builder Map for TTCOM • •
5-28
Part 3 Assembly Listing for TEST
5-29
Part 4 Memory Allocation Map for TEST • • • • • 5-31
Part 1 Source Listing for Resident Library
LIB.MAC • • . • • • • • • • • • • • • • • • • • 5-32
Part 2 Task Builder Map for LIB.TSK • •
5-34
Part 3 Source Listing for MAIN.MAC
• • • •
5-35
Part 4 Task Builder Map for MAIN.TSK • • • • • 5-37
Part 1 Source Listing for DYNAMIC.MAC •
5-41
Part 2 Task Builder Map for DYNAMIC.TSK •
5-43
Part 1 Source Listing for VSECT.FTN • • •
5-59
Part 2 Task Builder Map for VSECT.TSK • • • • • 5-61
Part 1 Source Code for PRIVEX • • • • •
• • 6-7
Part 2 Task Builder Map for PRIVEX
6-10
Map o'f Overlaid Task MAIN•TSK
• •. • •
7-·12
Map qf ov:er:J:a;id ·I- a!nd D-Spa:ce Tja~k MAI~ID.:!1!$~;
; :7-jM
Oode, !for SOPE,R. MAO .' • • • • • • • • •• •! •
8-!lQ
Metnbri~l 'Al'.ld,cati.on Malp for: SU:PER • • • .; •
':8-ili
Cdnlpll~tidn :.~o;uti:ne ,' i$CMPCS, from• SYSLIB~jOLO
:gBJ 1;

od<fe ;f qr :T;S,0,~.'M~O ... ~ • •· :• • • •• • •· • .•:
M;~P~:Y.!Al'.l1~qa,t;i~O]y,i :~~p for :.~SUP .• ,•' ,. •

•. . . :1

"t:'

J?ia;r;t :1.· i ·~Oqr1Qe .iMJ.<St~,ng fa:>ri' '~RTAS,.K~M~C ~j:
P:c:lr'~: :~ . . . . •!Ifa~;~:·sµ,•:i.i;l'd'e1~r .·:~~B' "~9~I:":ir~qT;AS,K'.;'~sK:t• ··•

•.

•
.;

-:t

S;.,17
·:: 9j--6
i

• ,;· ,g_,g

Cross-Reference Listing for OVR.TSK
lO~li
Memory Allocation File (Map) Example • •
• • 10-37
Part 1 Task Builder Map for LIB. TSK • •
• • C-3
Part 2 Task Builder Map for MAIN.TSK • • • • • • C-4
Sample Postmortem Dump (Truncated) • • •
• • D~2
Sample Program That Calls for Snapshot Dumps • • • D-9
Sample Snapshot Dump (in Word Octal and Radix-50) D-10
Sample Snapshot Dump (in Byte Octal and ASCII) • D-11

FIGURES
FIGURE

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

Relocatable Object Modules • • • • • • • • • •
Modules Linked for Mapped and Unmapped Systems
Allocation of Task Memory
Disk Image of the Task • • • • •
•
•
•
Memory Image • • • • • • •
• • •

• • 2-2
• • 2-3
• • 2-6
..,

•

~- J

• • 2-9

CONTENTS
Page
Simple 2-Segment, Disk-Resident Overlay Calling
Sequence • . • • • • . • • • • • • • • . • • • • 2-11
Simple 2-Segment, Memory-Resident Overlay Calling
2-7
Sequence • • • • • • • • • • • . • • • • • • • • 2-12
Virtual and Logical Address Space Coincidence
2-8
in an Unmapped System • • . • • • • .
2-15
Memory Layout for Unmapped System • • • • •
2-16
2-9
Task Relocation in a Mapped System • • • • •
2-17
2-10
Memory Management Unit's Division of Virtual
2-11
Address Space
• • • . • • • • • •
2-18
Mapping for 4K-Word and 6K-Word Tasks
2-19
2-12
Window Block 0 • • • • • • • • • • • •
2-21
2-13
Virtual to Logical Address Space Translation • • 2-23
2-14
2...;J:i.6 ·...... Mapp·.·T.,·.n.9. •. fa.r::··. a·· :.co·n.ven
. . ·.;tion~:.I: ·US;e.'.r.·.• ·.~a.·s'.k
.. ·:····.·.:.an. ~. :·a <~:jts.:i:em' '
~t_:;,;4. . '.:CQ1):t:~J,ni!;l'.:g: . ·;a.'_,' . s.up~_r,'7--i',~;~--i7<M~·(;,<~~.:i-.1»;--a;:r:¥ ,,'..,-±~~,-' .;~ri:,-::-:--~~,,,;,.:,, _ ·~,~-:_ _ _ ,
~>t'.--<?/,:$
' , ,,;/ .:'·.n,s',;, ·.,l:M·
.· : nr:u·:!'.<,··· C"' ·:·· "~ ' ' .' •.'' ,: '.: ; ,.><'/ ·"} ;, :" ;' " . ,:' ''.: \; ; ':' :: ,,'/' )' "" ,t
n.;: ..:..,6·,'.
'.:,~ > :··~ ~·~~-~'.~, . ~~r:;~'. \;o· ::~Y$:'.t;~: ...• .. :· . _:•~- .:· ~ . . '· ~_;:· -'"'~i,
~-'*' :..·.:·,•-,= - ,~~; .:···•_,~ ----~--·. 7 .•___ , -.=· -~ y~~ ~~
·. .:'(MaJPP,tn.~·: .3t,O,:r< ,a·. :.con:ve.~t:·~·<:!n.::rt/:P&~'.r;· :IJJa~ky ;Us}ng/.a:··.::.//. ' .. 't:·, ·, / J
:. .supe.r:v.isprfMode, . ti'h,ra·r~··':it:r.·~an,. ,·.:Rs;x~11.M~Pf,,PS;f,.y$t· . :'2~~7
2-6

·=

•_:·.-

.-."'

:?}roJ?·i:r~f~9, ~g~· :J1a,plfifns, ·(q~:· ··a!i" .:1t-:-'.·:.. fl:llo . :· of:~'P~·i:i~/1~.s.... /?'~,.2·~··

TKl Built As a Single-Segment Task • • • • •
• 3-4
TKl Built As a Multisegment Task • • • • • •
• 3-5
TKl Built with Additional Overlay Defined
. • • • 3-7
TK2 Built As a Single-Segment Task • ~ • •
• • 3-8
TK2 Built As a Memory-Resident Overlay • •
• • 3-9
Relationship Between Virtual Address Space and
3-11
Physical Memory -- Time 1
• • • • •
Relationship Between Virtual Address Space and
3-6B
Physical Memory -- Time 2 • • • • •
3-12
Relationship Between Virtual Address Space and
3-7A
Physical Memory -- Time 3
• • • • •
3-13
Relationship Between Virtual Address Space and
3-7B
Physical Memory -- Time 4
•••••
3-14
Overlay Tree for TKl • • • • • • • •
3-16
3-8
Resolution of Global Symbols in a Multisegment
3-9
Task • • • • • • • • • • • • • • • • •
3-1 7
3-10
Resolution of Program Sections for TKl • • • • • 3-19
3-11
Typical Overlay Root Segment Structure . • • • • 3-21
/3i"::i·2.• ;::··, ."T,yptca1.·p~~.r.,la ~d:· ··r=::· iiifld·:·.:I~;spa.o~>T,a&l$'/ .~.i'.~b ::·up;;:.."~!t~e' :J.f/l,· .> .t
3-2
3-3
3-4
3-5
3-6A

··j,,~"l{;.· ,.: · . :~~:t!<?~~·~,.~:irt:·~ai:·;id·~··r~~;~·· ··~P·~;~~/;'ti1;:~·~'.~~;:·,~:/. :·:o:_···:: .:·.:· ::.:·:::;·~·~!~·
3-14
3-15
3-16
3-17
3-18
3-19
3-20
3-21
3-22
4-1
4-2
4-3
4_,4

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

Overlay Tree for Modified TKl
• • • • • • • 3-31
Virtual Address Space and Physical Memory for
Modified TKl • • • • • • • • • • • • • • • • • • 3-33
Overlay Co-Tree for Modified TKl • • • • • • • • 3-34
Virtual Address Space and Physical Memory for TKl
As a Co-Tree • • • • • • • • • • • • • • • • • • 3-35
Virtual Address Space Allocation Diagram • • • • 3-36
Virtual Address Space Allocation for a Main Tree
and Its Co-Tree
• • • • • • • • • • • • • • • • 3-40
Overlay Tree of Virtual Address Space for OVR.TSK 3-43
Allocation of Virtual Address Space for OVR.TSK
3-46
Allocation of Virtual Address Space for
RESOVR.TSK • • • • • • • • • • • • • •
3-48
Details of Segment C of TKl
• • • • • •
• 4-2
Path-Loading Example •
• • • • • • •
4-4
Autoload Vector Format for Conventional Tasks
4-4
Autoload Vector Format for .I;_ and D-space Tasks • 4-5
Example Autoload Code Sequence for a Conventional
Task • • • • • • • • • • • • • • • • •
• • • • 4-5
Autoload Overlay Tree Example
4-12
Typical Resident Common
• • • • • • • 5-2
Typical Resident Library • • •
• • • 5-3
Interaction of the /LI, /CO, and /PI Switches
5-4
Specifying APRs for a Position-Independent Shared
Region • • • • • • • • • • • • • • • • • • • • • • 5-6
xi

CONTENTS
Page
5-5
5-6
5-7
5-8
5-9
5-10
5-11
5-12
5-13
5-14
6-1
6-2
6-3
7:;..;1

7i-:z,,''

Mapping for an Absolute Shared Region
• • • • • • 5-8
Windows for Shared Region and Referencing Task • 5-15
Allocation Diagram for MACCOM.TSK
• • • • • • • 5-20
Assigning Symbolic References within a Common
5-23
Allocation of Virtual Address Space for MAIN.TSK 5-38
Example Library and Task Structure • • • • • • • 5-44
Example of an Unbalanced Tree with Null Segment
5-45
Example of an Overlay Cluster Library Structure
5-45
Example of a Vectored Call Between Libraries
5-46
VSECT Option Usage • • • • • .
• • • • • • • 5-55
Privileged Task Mapping
• . • • • • • . • • • • • 6-3
Mapping for /PR:4 and /PR:5
. • • • •
• 6-4
Allocation of Virtual Address Space for PRIVEX • 6-11
., tonvent'iofia1, ,Ta:$k' ,tiriked'tb'/c:f ,R~g,fo»n;,,Ji( :ari'
',anq,,"
, D-space, 'Sys t'em .' .~ , ., ' ., .• , • . • '.• · •. ',. :• .,.~ ,' ·.," ~" • ,. , .~ , •.
I- and p.,..'spac~ Task Mapping.' in Jan
an,d'. 1 ':01:«~pacES!
1

s·ys t~m· ,~
7;-4
T-5

7-6
7-7
7-8
7-9
8-1
8-:2

8-3
8-4

9-1
9-2
9-3
9.;..4
A-1
A-2
A-3
A-4
A-5
A-6
A-7
A-8
A-9
A-10
A-11
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

•.. •

•

.•. .• , .~ .•

•

•. ~-'

•

Simplified pisk. Image of a Non-,Qverlald
D-Space .Tas:k • • ·• • , .., ·., • • • • • • • ,·~ ,~,: . • ~ . i't-6'
Overlaid I- and D...;Space· Task Virtfoal Addr.es.s. Spac,~\'11:..,7
. E!xample Overlay 'Tree· for Overlaid I;_; and. b'.:..Spa:c'e, ··. ,:'.>,,
, Task ·rAND • . • • • • • • • •' • • • .;
·.,. • ,.,, • ·
Simplified Disk Image ·of Overlafd I-:' a.nd o-:space",
Task IAND' • • • · ' . • • • • • • •. •.
•' • ·• "·' • ;7,;._g:
Memory Allocation· Diag!ram for MAIN.TSK, '· ,. • • •.' 7[.:..1Q
,Memory Allocat,ion Diagram for MAI,NID.TSK I-Space 7J-:.ll
Memory Allocation Diagram for MAI,NID.TSK D-Space, 7;-'11
Mapping of a 24K Conve'ntionaT •us'er' ,1TasJ< That Links 1 ·
to a 16K Supervisor-Mode Library • '· • • • .' • • • i8-4'
Mapping of a 2.0K ·conventional us:er Task .that Links
to a 12K Superv isor-M0:de Libr~rY! ,ccmtaining 4K of . :
Data. • • • • •~ • • • ~ • • . • . •: .; .: , ••. r• '• ., • • • ·ist_:5
Mapping of a 40K I- a:nd D-Space' :Tas1k Tlfat :Links to 1an
8K Supervisor-Mode Li1brary •' • • : i•; •••• '•' ;• • • • ,. js...;;6
Overlay Configuration Allowed for Supetvisor..:Mode
Libraries
• • • • •• • • •• • • ··: • • • • • •. ·• • ~-22
Allocation of :Program Sections i:n a Multiuse:i:;; fTask;~.191~2
Windows for a Multiuser Task • • • •. •
• .•:9-3
Example Allocation of Program Sections in an
;.o:t:9-4
and 'D-Space• MUilti~ser1iTask ...,.. • •·•· ••••. ,.:J •
Windows for an •I: ·and ::o-spaae Mul:ti•user r:·Tast
ti '9'.'"'15
General Object Module Format • • • • •
• A-3
Global Symbol Directory Record Format
• A-4
Module Name Entry Format • • • • •
• A-4
Control Section Name Entry Format
• A-5
Internal Symbol Name Entry Format
• A-5
Transfer Address Entry Format
A-6
Global Symbol Name Entry Format
• • • • • • • • • A-6
Program Section Name Entry Format
• • • •
A-8
Program Version Identification Entry Format
A-10
Mapped Array Declaration Entry Format
A-10
Completion Routine Entry Format
• • • • • •
A-11
End of Global Symbol Directory Record Format
A-11
Text Information Record Format • • • • • • •
A-12
Relocation Directory Record Format •
A-14
Internal Relocation Entry Format • • • • • • • • A-15
Global Relocation Entry Format • • • • • • •
A-15
Internal Displaced Relocaton Entry Format
A-16
Global Displaced Relocation Entry Format • •
A-16
Global Additive Relocation Entry Format
A-17
Global Additive Displaced Relocation Entry Format A-17
Location Counter Definition Entry Format • •
A-18
Location Counter Modification Entry Format •
A-18
Program Limits Entry Format
• • • • • • • • A-19
Program Section Relocation Entry Format
A-19
xii

CONTENTS
Page

A-25
A-26
A-27
A-28
A-29
A-30
A-31
A-32
A-33
A-34

Program Section Displaced Relocation Entry Format
Program Section Additive Relocation Entry Format
Program Section Additive Displaced Relocation
Entry Format • • • • • • • • • • . • • • • • • •
Complex Relocation Entry Format
• • • • •
Resident Library Relocation Entry Format •
General Format of All ISO Records
. • • •
General Format of a TKB Generated Record
Format of TKB Generated Start-of-Segment Item (1)
Format of TKB Generated Task Identification Item
(2)
• • • • • • • • • • • • • • • • • • • • • •
Format of an Autoloadable Library Entry Point

A-20
A-21
A-21
A-23
A-23
A-25
A-25
A-26
A-26

A-27
Format of a Module Name Item Type (1)
A-28
Format of a Global Symbol Item Type (2)
• • • • A-28
Format of a PSECT Item Type (3)
• • • • • • • • A-29
Format of a Line-Number or PC Correlation Item
Type ( 4 ) .• • • • • • • • • • • • • • • • • • • • A-30
A-31
Format of an Internal Symbol Name Item Type (5)
A-39
Format of a Literal Record Type
A-31
A-40
A-32
End-of-Module Record Format
• • • • •
A-41
Image on Disk of Non-Overlaid Conventional Task
. B-2
B-1
Image on Disk of Conventional Non-Overlaid Task
B-2
Linked to Overlaid Library • • • • . • • •
• • B-2
B-3
Image on Disk of Conventional Overlaid Task
• B-3
~:EfA~Y;~ ;..£ f:f iI~g~;o~· :n1;$;~' :;O~) Eoy:~r la:l'.o ':t;- . ' and' t)~Sp.ace; _:'.Tasik
. ·B-4
B-5
Label Block 0 -- Task and Resident Library Data • B-7
B-6
Label Blocks 1 and 2 -- Table of LUN Assignments • B-9
B-7
Label Block-3 -- Segment Load List • • • • • • • • B-9
B-8
Task Header, Fixed Part
B-11
B-9
Task Header, Variable Part •
• • • •
B-12
B-10
Vector Extension Area Format • • • • •
B-13
B-11
Logical Unit Table Entry . .
B-14
B-12
Task-Resident Overlay Data Base for a
Conventional Overlaid Task • • • • • • •
B-15
·9~1;3:
.;k'~~~f;-~'.d~~!tj}J~:~:~la:y :P~:~~.; J??l?~: f.9,r. an I~. "and:
t: :, I,· '2
. . S,pq,~-~ i ~~~~l;qf<1't :"fa,Rl,<.' :' :~; ~; :~.' )<,: •.•: ::•• • : •.; ·• ....... ,:·.:_ ••. :B~l6 .
'8':14
Autoload Vector Entry for Conventional Tasks • • B-17
Autoload Vector Entry for I- and D-Space Tasks . B-18
B-15
Segment Descriptor .
. •••
B-16
B-19
Window Descriptor
• • • . •
B-21
B-17
B-18
Region Descriptor
•••••
B-21
Snapshot Dump Control Block Format
• • D-6
D-1
A-35
A-36
A-37
A-38

TABLES
TABLE

2-1
2-2
2-3
2-4
4-1
5-1
7-1
10-1
10-2
11-1
A-1
A-2
A-3
B-1
B-2

Program Section Attributes • • • • • •
• • 2-4
Program Sections for Modules INl, IN2, and IN3 • • 2-6
Individual Program Section Allocations
• • 2-6
Resolution of Global Symbols for INl, IN2, and IN3 2-7
Comparison of Overlay Run-Time Module Sizes
4-16
Comparison of Overlay Run-Time Module Sizes
5-52
Mapping Comparison Summary
• • • 7-2
Task Builder Switches
10-2
10-47
Files for SEL.TSK • • • •
Task Builder Options • • •
. • • • • 11-2
Symbol Declaration Flag Byte -- Bit Assignments
• A-7
Program Section Name Flag Byte -- Bit Assignments A-8
Relocation Directory Command Byte -- Bit
Assignments
• • • • • • • • . • •
• . • • A-13
Task and Resident Library Data • • • • • • • • • • B-4
Resident Library/Common Name Block Data
• • • • • B-8
xiii

CONTENTS
Page

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

Task File Switch Defaults • • • •
Map File Switch Defaults • • • • • •
Symbol Table File Switch Defaults
Input Fi 1 e Sw i t ch Def au 1 ts • • • • •

xiv

• • • F-8
F-10
F-10
F-11

PREFACE

MANUAL OBJECTIVES
This manual describes the
RSX-llM/M-PLUS Task Builder.

concepts

and

capabilities

the

Working examples are used throughout this manual to introduce and
describe features of the Task Builder.
Because RSX-llM systems
support a large number of progranu~ing languages, it is not practical
to illustrate the Task Builder features
in all of the languages
supported.
Instead, most of the examples in the main text of this
manual are written in MACR0-11.

INTENDED AUDIENCE
Before reading this manual, you should be familiar
with
the
fundamental
concepts
of
your
operating
system
(RSX-llM or
RSX-llM-PLUS) and with the operating procedures described in the
RSX-llM/M-PLUS MCR Operations Manual.
In addition, you should be
fam1l1ar with the programming concepts described in the RSX-llM/M-PLUS
Guide to Program Development.

STRUCTURE OF THIS DOCUMENT
This manual
follows:

has

chapters.

Their

contents

are

summarized

•

Chapter 1 describes the Task Builder command
you use to interact with the Task Builder.

•

Chapter 2 describes the basic Task
Builder
functions,
including the Task Builder's allocation of virtual address
space and the resolution of global symbols.
It also contains
an
introduction to supervisor-mode libraries, privileged
tasks, and multiuser tasks.

•

Chapter 3 describes the Task Builder's overlay capability
the language you use to define an overlay structure.

and

•

Chapter 4 describes the two methods available to you
overlay segments.

load

•

Chapter 5 describes some typical Task Builder features,
including tasks that access shared regions and device commons,
tasks that create dynamic regions, and virtual
program
sections.

sequences

that

PREFACE
•

Chapter 6 defines privileged tasks, describes their mapping,
and shows how to build a privileged task to examine unit
control blocks.

·• )cb;aipter, 7 .. descr;i:be,s 'use.r~m9f)e,· ·1~ :an(t•··tj~s~ace '· .the . jnappj.,ng .· ·(Jf;'..
l , thj~$e . $,~aces , :and the a(jv~Qtage'.,$· ,l9f, :u'sing · I-· · and D7'·spa:qe f,n ,
"t·!'+,.,';u·~e;r~ :inqqe:
·
.:·
·:: .:: tlJ r ..' 1 'i"i;.;s:L' · ·'

c/.·.~· .·.~: ~.. :t.··.:,('../_,: .:.'.-., ·l. • : :.= f. . ·.

,,J~··\
••• •

·1

,,,-

, ••, "

!, "

. .. .

.·.

·.·. •. .

.·.·

.· . ·..."'

••

•

';"J H' t",~ rl·ttl

.. ·.; ·! : · :'.·j·1;:·.·.· ~-"'.·~·'.:*,·.:~.·,
.tj:·.is:· . aescri,b'es/'.S~per'.v· ,·'~ ·rr,-~.:.~.:.··.:·.•.··
1'·"t~ij,,·:,,·'
r,,.··'

· ,..

..· '.. .

•

,:;,~'.~1·
~~~'.:"~: · ~~o.ws».: ·;·buw· · ;.
~~1-~~··H·r~
.·~·~,~~.·~~~w~~ ··~'.:09~,~~:~;fip~~:,<'~i~'~~I·,:~h~~;'.~~~:)~',·~tJ~l,,~,,
1 .:· .;·t.

, :.

•

Chapter 10 lists and describes the Task Builder switches.
switches are listed in alphabetical order.

The

•

Chapter 11 lists and describes the Task Builder options.
options are listed in alphabetical order.·

The

This manual also contains
summarized as follows:

eight

appendices.

Their

contents

are

•

Appendix A contains a detailed description of the Task Builder
input data structures.

•

Appendix B contains a detailed description of the
file structure.

•

Appendix C describes the considerations for building a task on
one system to run on a system with a different hardware
configuration.

•

Appendix D
snapshot.

•

Appendix E contains a list of the symbols and program
names reserved for Task Builder use.

section

•

Appendix F contains
performance.

Builder

•

Appendix G describes the fast Task Builder.

•

Appendix H contains the Task Builder error messages.

describes

two

memory

information

dumps:

task

image

postmortem

improving

Task

and

A Task Builder glossary follows the appendices.

ASSOCIATED DOCUMENTS
Other manuals closely allied with this document are described in the
Information Directory and Master Index for your operating system.
This directory defines the intended audience of each manual in the
documentation set and provides a brief synopsis of each manual's
contents.

X\7 i

PREFACE
CONVENTIONS USED IN THIS DOCUMENT
In this manual, horizontal ellipses ( ••• )
indicate that additional,
optional arguments in a statement format have been omitted. For
example:
input-spec, •••
means that one or more input-spec items, separated by commas,
specified.

can

vertical ellipses mean that lines in an example, command lines, or
lines in a Task Builder map file that are not pertinent to an example
have been omitted. For example:
TKB>input-line

means that one or more of the indicated TKB items have been omitted.
The words "Task Builder" in this manual have been abbreviated
acronym TKB.

the

Unless otherwise stated, references to tasks, their mapping, and their
structure imply a nonprivileged task in an RSX-llM mapped system.
In the examples of Task Builder command sequences, the portion of the
command sequence that you type is printed in red.
The Task Builder's
responses and prompts are printed in black.
Shading in the manual has the following meanings:
;/P~:n~...

",·.rnai,oa,:te,s,·.t.tliat. . tl:le ·...te;xt:baesq.r:iJ:>~~/·.:fe.a·tiI.:f.e.~ ··~PP~.a.r.ing/<Jql.,Y ·
· , . pn ·RSXi-J:lM · pperatin9 · · .syst·ems·."; · ·
·
1

<··~1~~ic;CT·¥~~;<fha~O::·t~·e ..·~~~·t:· c}e~scrt··bt?~··,,:f~.a.~·u.r:~;s· . ;~ppe~x;·iit~'<l'9.~~f.,i'.
.;:;.e.I?:.:~;R~.&·:-:HM~.P'LUS· :9p,er.at:'ln9· ·.s.ystems; . . ./"/ .. · ,: · <·;,. . · .:.: .. · :./ ·/,/·'.:

xvii

SUMMARY OF TECHNICAL CHANGES

This manual contains the changes for RSX-llM Version 4.1
and
RSX-llM-PLUS Version 2.1.
This manual has been extensively revised.
A study of the Table of Contents and this Summary of Technical Changes
is recommended before you look for information in the manual.

GENERAL CHANGES
Editorial changes were
typographical errors.

made

throughout

the

manual

correct

Small technical changes were made throughout the manual as a result of
ongoing development, SPR responses, and readers' comments.
The major technical changes to the manual are listed below.

TECHNICAL CHANGES
NEW OPTIONS
DSPPAT -- Allows object-level patching of a conventional task

•.ffB::l~~i.~~~~2 £.~~ft~i

J~b~;::Pt'~:,~:.~~~;ii·:W+fz~!
CHANGED OPT IONS

ABSPAT -- Allows object-level patching of a conventional task
'lt;ififg~~~tf~l;f:;'!?~ti';~~f:!l'~~}01t·;i::~pµE·~t1'.?r;'§t~~~.;

COMMON -- The COMMON option causes the common to be mapped with
,·''#,~ff,;~LfJ!>~~',~.~ ~ij<J~·tiif:.~~t§~:}J,~Im~bij.

' ' iair:f i:id ~; itia;p~ with ,·bo.tb

. t;q,' :~iP i~:- · ;a[l~ .P:ispa<::e task. ·

'R\ESGQM·~- fne:·RESqdM::op;f:i~o~· . ~aus·e~·:.tll~.··~b#(}h)t'~.::*'; ·lll~ppE!d·.: with
o...: .. Rpace ... ·APR.s~· .:~'her~f.or~ .: ; fO~ ·, ' .. and; :·p.:.:$'pi<;lc~: t\~sks 1: th~ <;pmmon
1
CElil ~::ntain tl'Gi't<i:· ph1ly.•.'
. r. ' I
' '
'
,

•

.;>

·~

~' :

, ..

RESLIB -~·.The R]:svrn. ()Ptio.n· CcFU.Ses 'the lib.~~ty: ',f6 ';be m.appe~: with·
both :IC:....space : artt:i o:...:spa.c.e. APRS" ·:when· 11.n:k'ed:
an ;l.-' and; ·o~sp9ce

:tor

task .• ,;

xix

SUMMARY OF TECHNICAL CHANGES
NEW ERROR MESSAGES
Module module-name contains incompatible autoload vectors
CHANGED ERROR MESSAGES
Lookup failure resident library file
changed to
Lookup failure resident library file - filename.ext
MISCELLANEOUS TECHNICAL CHANGES
Autoload vectors for conventional tasks have changed.
The call
to $AUTO is now made indirectly through .NAUTO in the overlay
impure area.

I··

and o-space task's in:ay 'be overlaid by using, e~ thet' autol,.q;~a,
manual load.
. l'
. Autoload vectors for I- and D-space tasks have a fq~rttat dt,C'f~t,ent
from those of conventional. tasks. The autoload .v~ctorS, 'for ·1-·
. and D-space tasks contain an !-space part locat;:ed
:the.> ,task~' s
I-space and a o-:space part ·located in: the task 1 ~ D'.""space:.. ·
·

Memory allocation diagrams may be used as an aid to
files.
Overlay Run-time System
previous release.

routines

have

changed

create

size

from

.ODL
the

MACR0-11 and FORTRAN manual load calling sequences for overlays
in I- and D-space tasks may not use asynchronous loading.
For versions of TKB that support I- and D-space tasks and that
were used to build libraries, TKB allocates autoload vectors in
the root of the task only for those autoloadable entry points in
the library referenced by the task.
I- and D-space tasks may link to commons, conventional libraries,
and supervisor-mode libraries.
Loading I- and D-space tasks into memory requires two disk
in
accesse.s.
Overlaid I- and D-space tasks may require,
addition, two disk accesses for
loading each segment if the
segment contains both I-space and D-space.
Segment descriptors for I- and D-space tasks contain an exteqsion
for the D-space part.
Only one level
libraries.

ov·erlay

allowed

I- and :o-space multi user task:s ,are· allr;:>w~.:,
.blocks to map these tasks.

supervi.sor-mode

1!KB: uses f~11r win~o~

Internal Symbol Directory Records, along with their formats,
described in Appendix A.
They consist of:

are

•

Type 1 records, generated by TKB and output to the .STB file

•

Type 2 records, generated by language processors

SUMMARY OF TECHNICAL CHANGES

•

Type 3 records, created from type 2 records and output to
.STB file

the

•

Type 4 records, written to the .STB file without modification

A new bit called LD$TYP distinguishes between a library or common.
See offset R$LFLG in the resident library name block data in Appendix
B.
The first library in a cluster may be overlaid and contain a
root.

non-null

New Task Builder reserved symbols have been added to Appendix E.
The Fast Task Builder supports the /EA switch and the TASK= option.
>'.ro'e':r,m'{lp,,"f~>,.rm.at'.~o:~,··.:~n/r~./anq,·.:1J:-f»pa,c,,~".'ta·sk~..~b~iws·,."bo~·~: ·..:~~·:·'.>~~d'J:O~.~I~~~·
:'c(?tit,:·~:"i,:li~);·~ton.~:·· ·.~q", :.a··:·'..·s~g~e~lt,'/, ~Q·g ";·.£,q.e•' . :' :'d.f.s:~ ·ti,l:eQ9'~~f.·thp:t' :'C:Qnta.:i,11 .'~~,,ta·,

,..s;e;e;ti.ons"'·
"''
-~ ,.

~,_/

..'

Other minor technical and editorial changes have been made also.

xxi

CHAPTER 1
INTRODUCTION AND COMMAND SPECIFICATIONS

The basic steps in developing a program are as follows:
1.

You write one or more routines in an RSX-llM/M-PLUS supported
source language and enter each routine as an ASCII text file,
through an editor.

You submit each text file to the appropriate language
translator (an assembler or compiler), which converts it to a
relocatable object module.

You specify the object modules as input to the Task Builder
(TKB), which combines the object modules into a single task
image output file.

You install and run the task.

If you find errors in the task when you run it, you make corrections
to the text file using the editor, and then repeat steps 2 through 4.
The Task Builder 1 s main function
is to convert relocatable object
modules (.OBJ files) into a single task image (.TSK file) that you can
install and run on a RSX-llM or RSX-llM-PLUS system. The task is the
fundamental executable unit in both systems.
If your program consists of a single object module, using the Task
Builder
(TKB) is appropriately simple. You specify as input only the
name of the file containing the object module produced from the
translation of the program, and specify as output the task image file.
Typically, however, programs consist of more than a single object
module.
In this case, you name each of the object module files as
input. TKB links the object modules, resolves references between
them, resolves references to the system library, and produces a single
task image ready to be installed and executed.
TKB makes a set of assumptions (defaults) about the
on typical usage and storage requirements. You
assumptions by including switches and options in
terminal sequence. Thus, you can build a task that
own input/output and storage requirements.

task image based
can override these
the task-building
is tailored to its

TKB also produces {upon request) a memory allocation (map)
file that
contains information describing the allocation of address space, the
modules that make up the task image, and the value of all alobal
symbols.
In addition, you can request that a list of global symbols,
accompanied by the name of each referencing module, be appended to the
file (global cross reference) •

1-1

INTRODUCTION AND COMMAND SPECIFICATIONS
Note that the examples in this manual use MCR as the operating system
language.
Refer to the RSX-llM-PLUS Command Language Manual and, in
particular, to the command in that manual for DIGITAL Command Language
equivalence.
The following example shows a simple sequence for building a task:
>MAC
>TKB
>INS
>RUN

PROG=PROG
PROG=PROG
PROG
PROG

The first command (MAC) causes the MACR0-11 assembler to translate the
source code of the file PROG.MAC into a relocatable object module in
the file PROG.OBJ.
The second command (TKB) causes TKB to process the
file PROG.OBJ and to produce the task image file PROG.TSK. The third
command (INS) causes the INSTALL processor to add the task to the
Executive's directory of executable tasks (System Task Directory).
The fourth command (RUN) causes the task to execute.
The example just given includes the command
>TKB PROG=PROG
This command illustrates the simplest use.of TKB.
It gives the name
of a single file as output and the name of a single file as input.
The following sections describe basic Task Builder command
sequences.

1.1

forms

and

TASK COMMAND LINE

The task command line contains the output file specifications,
followed by the input file specifications;
they are separated by an
equal sign (=).
You can specify up to three output files and any
number of input files.
The task command line has the following form:
task-image-file,map-file,symbol-definition-file=input-file, •••
You must give the output files in a specific order:
the first file
you name is the image
(.TSK)
file;
the second is the memory
allocation (.MAP) file;
and the third is the symbol definition (.STB)
file.
The map file lists information about the size and location of
components within the task.
The symbol definition file contains the
global symbol definitions in the task and their virtual or relocatable
addresses in a format suitable for reprocessing by TKB.
You specify
this file when you are building a resident library or coITuuon.
(Resident libraries and commons are described in Chapter 3.)
TKB
combines the input files to create a single task image that can be
installed and executed.

1.1.1

Printing the Map File

If you create a map file by specifying one in the TKB command line,
there are a number of ways that you can print the file.
The following
examples show you ways that you may print the map file.
1.

With the following two command lines, you can create a map
file and then print it later. The TKB command line tells TKB
to create a task file, a map file without printing it (by use

1-2

INTRODUCTION AND COMMAND SPECIFICATIONS
of the switch /-SP), and a symbol definition file.
The PRINT
command line tells the system to print the map file.
>TKB INV.TSK,INV.MAP/-SP,INV.STB=INV.OBJ
>PRINT INV. MAP
2.

With the next command line, you can print the map file
directly as it is created.
In this case, TKB tells the
system to print the file by use of the switch /SP.
However,
the system task PRT ••• or ••• PRT must be installed for this
method to work.
>TKB INV.TSK,INV.MAP/SP,INV.STB=INV.OBJ

With the next command line, you can print the map file on a
line printer that you specify.
It is best to use this
command line on an RSX-llM-PLUS system because that system
uses transparent spooling.
Using this command line on an
RSX-llM system may cause the printer to be unavailable to
other tasks.
See your system manager for specific details
about using the following command line.
>TKB INV.TSK,LPn:,SY:INV.STB=INV.OBJ

1.1.2

Omitting Specific Output Files

You can omit any output file by replacing the file specification with
the delimiting comma that would normally follow it. The following
commands illustrate the ways in which TKB interprets the output file
names.

1.2

Command

Output Files

>TKB IMGl,IMGl,IMGl=INl

The task image file is IMGl.TSK,
the
memory
allocation
(map)
file
is
IMGl.MAP, and the symbol definition file
is IMGl. STB.

>TKB IMGl=INl

The task image file is IMGl.TSK.

>TKB ,IMGl=INl

The map file is IMGl.MAP.

>TKB

The symbol definition file is IMGl.STB.

,,IMGl=INl

>TKB IMGl,,IMGl=INl

The task image file is IMGl.TSK and
symbol definition file is IMGl.STB.

>TKB =IN!

This is a diagnostic run with no
files.

the

output

MOLTILINE INPUT

Although you can specify a maximum of three output files,
you can
specify any number of input files. When you specify several input
files, a more flexible format
is sometimes necessary
one that
consists of several lines.
This multiline format is also necessary
when you want to include options in your command sequence (see Section
1. 3) •

1-3

INTRODUCTION AND COMMAND SPECIFICATIONS
If you type TKB, the Monitor Console Routine (MCR) activates the Task
Builder.
TKB then prompts for
input until it receives a line
consisting only of the terminating slash characters
(//).
For
example:
>TKB
TKB>IMGl,IMGl=INl
TKB> IN2 I IN3
TKB> //
This sequence produces tpe same result as the single line command
>TKB IMGl,IMGl=INl,IN2,IN3
Both command sequences produce the task image file
IMGl.TSK and the
map file IMGl.MAP from the input files INl.OBJ, IN2.0BJ, and IN3.0BJ.
You must specify the output file specifications and the equal sign (=)
on the first command line.
You can begin or- continue input file
specifications on subsequent lines.
When you type the terminating slash characters
(//), TKB
accepting input, builds the task, and returns control to MCR.

1. 3

stops

OPTIONS

You use options to specify the characteristics of the task you are
building.
To include options in a task, you must use the multiline
format.
If you type a single slash
(/)
following the input file
specification, TKB requests option information by displaying ENTER
OPTIONS:
and prompting for input. For example:
>TKB
TKB>IMGl,IMGl=INl
TKB> IN2 I IN3
TKB/
Enter Options:
TKB> PRI=lOO
TKB>COMMON=JRNAL:RO
TKB>//
In this sequence there are two options:
PRI=lOO and COMMON=JRNAL:RO.
The two slashes end option input, initiate the task build, and return
control to MCR upon completion.
NOTE
When you are building an overlaid task,
there are exceptions to the use of the
single slash (/).
Overlaid tasks are
described in Chapter 4.
The RSX-llM/M-PLUS Task Builder provides numerous options, which are
described
in Chapter 11. The general form of an option is a keyword
followed by an equal sign (=) and an argument list.
The arguments in
the list are separated from one another by a colon (:).
In the
example above, the first option consists of the keyword PRI and a
single argument indicating that the task is to be assigned the
priority 100. The second option consists of the keyword COMMON and an
argument list, JRNAL:RO, indicating that the task accesses a resident

1-4

INTRODUCTION AND COMMAND SPECIFICATIONS
common region named JRNAL and that the access is read-only.
You can
specify more than one option on a line by using an exclamation point
(!) to separate the options. For example, the command
TKB>PRI=lOO!COMMON=JRNAL:RO
is equivalent to the two lines:
TKB> PRI=lOO
TKB>COMMON=JRNAL:RO
Some options accept more than one set of argument lists.
You use a
comma (,) to separate the argument lists= For example 1 in the command
TKB>COMMON=JRNAL:RO,RFIL:RW
the first argument list indicates that the task has requested
read-only access to the resident coITu~on JRNAL.
The second argument
list indicates that the task has requested read/write access to the
resident common RFIL.
The following three sequences are equivalent:
TKB>COMMON=JRNAL:RO,RFIL:RW
TKB>COMMON=JRNAL:RO!COMMON=RFIL:RW
TKB>COMMON=JRNAL:RO
TKB>COMMON=RFIL:RW

1.4

MULTIPLE TASK SPECIFICATIONS

If you intend to build more than one task, you can use the single
slash
(/) following option input.
This directs TKB to stop accepting
input, build the task, and request information for the next task
build. For example:
> TKB
TKB> IMGl=INl
TKB> IN2, IN3
TKB> I
Enter Options:
TKB> PRI=lOO
TKB>COMMON=JRNAL:RO
TKB>/
TKB>IMG2=SUB1
TKB> //
TKB accepts the output and input file specifications and the option
input;
it then stops accepting input upon encountering the single
slash (/) during option input. TKB builds IMGl.TSK and then returns
to accept more input for building IMG2.TSK.

1.5

INDIRECT COMMAND FILES

You can enter commands to TKB directly from the keyboard, or
indirectly through the indirect command file facility.
To use the
indirect command file facility, you prepare a file that contains the
TKB commands you want to be executed. Later, after you invoke TKB,
you type an at sign (@) followed by the name of the indirect command
file.

1-5

INTRODOCTION AND COMMAND SPECIFICATIONS
For example, suppose you create a file called AFIL.CMD containing
following:

the

IMGl, IMGl=INl
IN2,IN3

I
PRI=lOO
COMMON=JRNAL:RO

II
Later, you can type:
>TKB
TKB>@AFIL
TKB>
or simply:
>TKB @AFIL
When TKB encounters the at sign
(@),
it directs its search for
commands to the file named AFIL.CMD.
The example above is equivalent
to the keyboard sequence
>TKB
TKB>IMGl,IMGl=INl
TKB> IN2, IN3
TKB>I
Enter Options:
TKB>PRI=lOO
TKB>COMMON=JRNAL:RO

TKB>ll
When TKB encounters two terminating slash characters
<II> in the
indirect command file, it terminates indirect command file processing,
builds the task, and exits to MCR.
When TKB encounters
the slash is the
for commands to the
in the last example

a single slash (I) in an indirect command file and
last character in the file, TKB directs its search
terminal. For example, suppose the file AFIL.CMD
is changed to read:

IMGl I IMGl= INl
IN2,IN3

I
Later, you can type:
>TKB
TKB>@AFIL
In this case, TKB goes to the terminal and prompts:
Enter Options:
TKB>
From this point, you input options to TKB directly from the keyboard.
If you then conclude option input from the keyboard with double
slashes <II>, TKB suspends command processing, as described above, and
exits to MCR following the task build.
If you conclude option input
with a single slash (I), TKB prompts for new command
input following
the task build of IMGl.TSK, as follows:
TKB>

1-6

INTRODUCTION AND COMMAND SPECIFICATIONS
Using the single slash (I) following option input in indirect command
files
is a convenient way to return control to your terminal between
successive task builds.
For example, suppose you create two indirect
command files.
The first, AFIL.CMD, contains:
IMGl, IMGl=INl
IN2, IN3

PRI=lOO
COMMON=JRNAL

I
The second, AFILl.CMD, contains:
IMG2, IMG2= IN4
INS, IN6

PRI=lOO

II
Then, the terminal sequence to build these two tasks is:
)TKB
TKB>@AFIL
TKB>@AF!Ll

>
NOTE
For
interaction with a TKB indirect
command file as described above, you
must use the multiline format when you
specify the indirect command file.
TKB permits two levels of indirection in file references.
That is,
the indirect command file referenced
in a
terminal sequence can
contain a reference to another indirect command file.
For example, if
the file BFIL.CMD contains all the standard options that are used by a
particular group of users at an installation, you can modify AFIL to
include an indirect command file reference to BFIL.CMD as a separate
line in the option sequence.
·
The contents of AFIL.CMD would then be:
IMGl, IMGl= INl
IN2, IN3

PRI=lOO
COMMON=JRNAL:RO
@BFIL

II
To build these files, you type:
>TKB
TKB> @AFIL
Suppose the contents of BFIL.CMD are:
STACK=lOO
UNITS=5!ASG=DT1:5

1-7

INTRODUCTION AND COMMAND SPECIFICATIONS
Then the terminal equivalent of building these files is:
>TKB
TKB>IMGl,IMGl=INl
TKB>IN2,IN3

TKB>I
Enter Options:
TKB>PRI=lOO
TKB>COMMON=JRNAL:RO
TKB>STACK=lOO
TKB>UNITS=5!ASG=DT1:5

TKB>ll
The indirect command file reference must appear on a separate line.
For example,
if you modify AFIL.CMD by adding the @BFIL reference on
the same line as the COMMON=JRNAL:RO option, the substitution would
not take place and TKB would report an error.

1.6

COMMENTS IN LINES

You can include comments at any point in the command sequence, except
in lines that contain file specifications.
You begin a comment with a
semicolon (;) and terminate it with a carriage return.
All text
between these delimiters is a comment.
For example, in the indirect command file AFIL.CMD, described
in
Section 1.5, you can add comments to provide more information about
the purpose and the status of the task.
TASK 33A
DATA FROM GROUP E-46 WEEKLY
;

IMGl,IMGl=
; PROCESSING ROUTINES
INl
;

; STATISTICAL TABLES
IN2
;

; ADDITIONAL CONTROLS
;

IN3

I
PRI=lOO
;

COMMON=JRNAL:RO ; RATE TABLES
;

; TASK STILL IN DEVELOPMENT
;

1.7

FILE SPECIFICATIONS

TKB adheres to the standard RSX-llMIM-PLUS conventions for file
specifications.
For any file, you can specify the device, the user
File Directory (UFO), the file name, the file type, the file version
number, and any number of switches.
1-8

INTRODUCTION AND COMMAND SPECIFICATIONS
The file specification has the form
device:[group,member]filename.type;version/swl/sw2 ••• /swn
When you specify files by name only, TKB applies the default
settings for device, group, member, type, and version.

switch

For example:
>TKB
TKB>IMGl,IMGl=INl
TKB>IN2,IN3
TKB>//
If the current User Identification Code (UIC) of the terminal that TKB
is running on is [200,200], the task image file specification of the
example is assumed to be:
SYO: [200,200]IMG1.TSK;l
That is, TKB creates the task image file on the system device
(SYO:)
under UFO [200,200]. The default type for a task image file is .TSK
and, if the name IMGl.TSK is new,
the version number is 1.
The
default settings for all the task image switches also apply. Switch
defaults are described in detail in Chapter 6.
For example:
>TKB
TKB>[(20,23]]IMG1/CP/DA,IMG1/CR=IN1
TKB>IN2;3,IN3
TKB>//
This sequence of commands instructs TKB to create a task image file
IMGl.TSK;l and a memory allocation (map) file IMGl.MAP;l (actually, it
produces IMGl.TSK and IMGl.MAP with versions one higher than the
current versions) under UFO [20,23] on the device SY:. The task image
is checkpointable and contains the standard debugging aid (ODT) •
TKB
outputs the map to the line printer with a global cross-reference
listing appended to it. TKB builds the task from the latest versions
of INl.OBJ and IN3.0BJ, and the specific version of IN2.0BJ. The
input files are all found on the system device.
The system device (SY:)
is always the default device unless you
specify otherwise.
If you specify another device on either side of
the equal sign, that device becomes the default device for the files
on that side of the equal sign. For example:
>TKB
TKB>[[20,23]]IMGl,IMGl,IMGl=DBl:IMGl,INl,IN2
This command line produces a task image file, map file,
and listing
file in UFO [20,23] on device SY:. All the object files are in UFO
[20,23] on device DBl.
In cases where files are scattered among
several devices, the devices must be specified in the command line.
For some files, a device specification is sufficient.
In the example
above, the map file could be fully specified by the device LP:.
The
map listing is produced on the line printer, but is not retained as a
file.
This example also used switches /CP, /CR, and /DA.
The code,
and meaning for each switch are given in Chapter 6.

1-9

syntax,

INTRODUCTION AND COMMAND SPECIFICATIONS
1.8

SUMMARY OF SYNTAX RULES

The syntax rules for issuing commands to TKB are as follows:
•

A task-build command can take any
first form is a single line:

one

four

forms.

The

>TKB task-command-line
The second form has additional lines for input file names:
>TKB
TKB>task-command-line
TKB>i npu t-li ne

TKB>terminating-symbol
The third form allows you to specify options:
>TKB
TKB>task-command-line

TKB>I
Enter Options:
TKB)option-11ne

TKB>terminating-symbol
The fourth form has both input lines and option lines:
>TKB
TKB>task-command-line
TKB>i npu t-li ne

TKB>I
Enter Options:
TKB>option-line

TKB>terminating-symbol
The terminating symbol can be:

•

if you intend to build more than one task

if you want TKB to return control to MCR

A task command line has one of the three forms:
output-file-list=input-file, •••
=input-file, •••
@indirect-command-file
The third form is an indirect command file
described in Section 1.5.

1-10

specification,

INTRODUCTION AND COMMAND SPECIFICATIONS
•

An output file list has one of the three forms:
task-image-file,map-file,symbol-definition-file
task-image-file,map-file
task-image-file
The task-image-file is the file specification for the task
image file; map-file is the file specification for the memory
allocation (map) file;
and symbol-definition-file is the file
specification for the symbol definition file.
Any of the
specfications can be omitted, so that, for example, the
following form is permitted:
task-image-file,,symbol-definition-file

•

An input line has one of two forms:
input-file, •••
@indirect-command-file
Both
input-file
specifications.

•

and

indirect-command-file

are

file

An option line has one of two forms:
option t •••
@indirect-command-file
The indirect-command-file is a file specification.

•

An option has the form:
keyword=argument-list, •••
The argument-list is:
arg: •••
The syntax for each option is given in Chapter 6.

•

A file specification conforms
conventions.
It has the form:

standard

RSX-lM/M-PLUS

device:[group,member]filename.type;version/swl/sw2 ••• /swn

device:
The name of the physical device on which the volume
The name consists
containing the desired file is mounted.
of two ASCII characters followed by an optional 1- or
for example, LP:
2-digit octal unit number and a colon;
or DTl:.
group
The group number, in the range of 1 through 377(8).

1-11

INTRODUCTION AND COMMAND SPECIFICATIONS
member
The member number, in the range 1 through 377(8).
filename
The name of the desired file.
to 9 alphanumeric characters.

The file name can contain up

type
The 3-character file type identification. Files having the
same name but a different function are distinguished from
one another by the file type;
for example, CALC.TSK and
CALC.OBJ.
version
The version number,
in octal, of the file.
Various
versions of the same file are distinguished from one
another by this number;
for example, CALC.OBJ;l and
CALC.OBJ;2.
All components of a file specification are optional.
The
combination of the group number and the member number is
the User File Directory (UFD) that contains the file name.

1-12

CHAPTER 2
TASK BUILDER FUNCTIONS

The process of building a task involves three
(TKB) functions:
1.

Linking object modules

Assigning addresses to the task image

Building data structures into the task

distinct

Task

Builder

First, TKB is a linker.
It collects and links the relocatable object
modules that you specify to it into a single task image, and resolves
references to global symbols across the module boundaries.
Second, TKB assigns addresses to the task image. On mapped systems,
TKB assigns addresses for a task beginning at O.
The Executive then
relocates the addresses at run time. On unmapped systems, TKB assigns
addresses for a task beginning at the base address of the partition in
which the task is to run.
The addresses of tasks that run on unmapped
systems are not relocated at run time.
NOTE
Unless otherwise indicated, references
to tasks that run on mapped systems
assume that the tasks are nonprivileged
and residing within system-controlled
partitions.
Third, TKB builds data structures into
required by the INSTALL processor to
Executive to run it.

the task image that are
install the task and by the

This chapter describes the three TKB functions
in detail.
It also
describes the concepts of mapped and unmapped systems.
In addition,
this chapter introduces regions, supervisor-mode libraries, overlays,
privileged tasks,
I- and D-space tasks, and many of the mapping
concepts necessary for an understanding of task mapping and Task
Builder functions.

2~1

LINKING OBJECT MODULES

TKB links object modules within the context of program sections
resolves references to global symbols across module boundaries.

and

When the language translators convert symbolic source code within a
module to object code, they assign provisional 16-bit addresses to the
code. A single assembly or compilation produces a single object

2-1

TASK BUILDER FUNCTIONS
module.
In its simplest form, each module begins at O and extends
upward to the highest address in the module.
Three object modules
produced at separate times might have the address limits shown in
Figure 2-1.
1000-r-:------

750

500

MODULE #1

MODULE #3
MODULE #2

RELOCATABLEO....._.__ _ __. RELOCATABLEO

------~-RELOCATABLEO
ZK-377-81

Figure 2-1

Relocatable Object Modules

If these modules represent the separate modules of a single program,
TKB links them together and modifies the provisional addresses to one
of the following:
•

For a mapped system, a single sequence of addresses beginning
at O and extending upward to the sum of the lengths of all the
modules (-1 byte)

•

For an unmapped system, a single sequence of addresses
beginning at a base address assigned at task-build time and
extending upward to the sum of the lengths of all the modules
(-1 byte)

For example, Figure 2-2 shows the three modules linked
system and the modules linked for an unmapped system.

2.1.1

for

mapped

Allocating Program Sections

The language translators process source code and TKB links object
modules within the context of program sections. A program section is
a block of code or data that consists of three elements:
•

A name

•

A set of attributes

•

A length

A program section is the basic unit used by TKB to determine the
placement of code and data in a task image.
The language translators
maintain a separate location counter for each program section in a
program.
The name of each program section, its attributes, and its
length are conveyed to TKB through the object module.

2-2

TASK BUILDER FUNCTIONS

2250 - . - - - - - -

3250

•

MODULE #3

11 MODULE #2

MODULE #2

MODULE #1

I_ _
ll
0

BASE 1000I-'-

MAPPED
SYSTEM

UNMAPPED
SYSTEM
ZK-378-81

Figure 2-2

Modules Linked for Mapped and Unmapped Systems

You can create as many program sections within a module as you wish by
explicitly declaring them (with the COMMON statement in FORTRAN or the
.PSECT directive in MACR0-11, for example} or by allowing the language
translator to create them.
If you do not explicitly create a program
section in your source code, the language translator you are working
with will create a "blank" program section within each module
translated. This program section will appear on your listings and
maps as
• BLK •• For more information on explicitly declared program
sections, see your language reference manual.
A program section's name is the name by which the language translator
and TKB reference it.
When processing files, both the language
translator and TKB create internal tables that contain program section
names, attributes, and lengths.
A named program section can be
declared more than once.
However, all occurrences of that named
program section must have identical attributes if the section occurs
more than once in the same module or if the section is a global
program section.
Identically named program sections within the same
module and global program sections with differing attributes cause TKB
to declare the program section as having multiple attributes, which is
an error. However, identically named program sections with differing
attributes may appear in different trees of an overlaid task if the
program sections have the local (LCL} attribute.

2-3

TASK BUILDER FUNCTIONS
Program section attributes define a program section's contents,
its
placement in a task image, and, in some cases, the allowed mode of
access (read/write or read-only).
A program section's length determines how much address space TKB
reserve for it.

must

When a program consists of more than one module, it is not unusual for
program sections of the same name to exist in more than one of the
modules. Therefore, as TKB scans the object modules,
it collects
scattered occurrences of program sections of the same name and
combines them into a single area of your task image file.
The
attributes listed in Table 2-1 control the way TKB collects and places
each program section in the task image.
Table 2-1
Program Section Attributes
Attribute

Meaning

Value
RW

Read/write: data can be read from,
written into, the pr~gram section.

Read-only: data can be read from, but
cannot
be written into,
the program
section.

CON

Concatenate: all references to a given
program section name are concatenated;
the total allocation is the sum of the
individual allocations.

OVR

Overlay:
all references to a
given
program section name overlay each other;
the total allocation is the length of the
longest individual allocation.

REL

Relocatable:
the base address of the
program section is relocated relative to
the base address of the task.

ABS

the
Absolute:
the base address
of
it is
program section is not relocated;
always O.

save

SAV

The program
section
has
attribute, and TKB forces
section into the root.

scope-code

GBL

Global:
the program section name is
recognized
across
overlay
segment
boundaries;
TKB allocates storage for
the
program
section from references
outside the defining overlay segment.

LCL

Local:
the program section name
is
recognized
only
within the defining
overlay segment; TKB allocates storage
for the program section from references
within the defining overlay segment only.

access-code

allocation-code

relocation-code

and

the
SAVE
the program

(continued on next page)

2-4

TASK BUILDER FUNCTIONS
Table 2-1 (Cont.)
Program Section Attributes
Attribute
type-code

Meaning

Value
D

Data:

the program section contains data.

Instruction:
the
program
section
contains either instructions, or data and
instructions.

2.1.1.1 Access-code and
Allocation-code - TKB
uses
a
program
section's access-code and allocation-code to determine its placement
and size in a task image.
If you specify /SG in the command sequence,
TKB divides address space into read/write and read-only areas, and
places the program sections in the appropriate area according to
access-code.
However, the default is to order the program sections
alphabetically.
TKB uses a program section's allocation-code to determine its starting
address and length.
If a program section's allocation-code indicates
that TKB is to overlay it (OVR), TKB places each allocation to the
program section from each module at the same address within the task
image. TKB determines the total size of the program section from the
length of the longest allocation to it.
If a program section's allocation-code indicates that TKB is to
concatenate it
(CON), TKB places the allocation from the modules one
after the other in the task image, and determines the total allocation
from the sum of the lengths of each allocation.
TKB always allocates address space for a program section beginning on
a word boundary.
If the program section has the D (data) and CON
(concatenate) attributes, TKB appends to the last byte of the previous
allocation all storage contributed by subsequent modules.
It does
this regardless of whether that byte is on a word or nonword boundary.
For a program section with the I (instruction) and CON attributes,
however, TKB allocates address space contributed by subsequent modules
beginning with the nearest following word boundary.
For example, suppose three modules, IN!, IN2, and IN3, are to be task
built.
Table 2-2 lists these modules with the program sections that
each contains and their access codes and allocation codes.
In this example, the program section named B, with the attribute CON
(concatenate), occurs twice.
Thus, the total allocation for B is the
sum of the lengths of each occurrence;
that is, 100 + 120 = 220.
The
program section named A also occurs twice.
However, it has the OVR
(overlay) attribute;
so its total allocation is the largest of the
two sizes, or 300.
Table 2-3 lists the individual program section
allocations.

2-5

TASK BUILDER FUNCTIONS
Table 2-2
Program Sections for Modules INl, IN2, and IN3
Program
Section
Name

Access
Code

Allocation
Code

Size
(Octal)

B
A

RW
RW
RO

CON
OVR
CON

100
300
150

IN2

A
B

RW
RW

OVR
CON

250
120

IN3

CON

File Name
INl

Table 2-3
Individual Program Section Allocations
Program Section
Name

Total
Allocation

B
A

220
300
220

TKB then groups the program sections according to their
and alphabetizes each group, as shown in Figure 2-3.

access

NOTE
The example
shown
in
Figure
2-3
represents the Task Builder's allocation
of program sections if the /SG or /MU
switches
are
used.
For
more
information, see the description of the
/MV, /SQ, and /SG switches in Chapter
10.

c (220)
B (220)
A (300)
STACK

READ-ONLY
ACCESS

READ/WRITE
ACCESS

TASK MEMORY

HEADER

ZK-379-81

Figure 2-3

Allocation of Task Memory

2-6

codes

TASK BUILDER FUNCTIONS
The save attribute (SAV) is useful in cases where the information in a
program section must be kept available to all task segments. The SAV
attribute of a program section causes TKB to force the program section
into the root of an overlaid task.
Therefore, the named common block
in the FORTRAN SAVE statement or the named program section in the
MACR0-11
.PSECT directive specified with the SAV attribute are in the
root of the task.

2.1.1.2 Type-Code and Scope-Code - The scope-code is meaningful only
when you define an overlay structure for a task.
The scope-code is
described in Chapters 3 and 4 within the context of the descriptions
of overlays.
{The type-code is meaningful in the context of program
sections within an I- and D-space task, as described in Chapter 7.}

2.1.2

Resolving Global Symbols

TKB resolves references to global symbols across module boundaries and
any references (explicit or implicit) to the system library. When the
language translators process a text file, they assume that references
to global symbols within the file are defined in other, separately
assembled or compiled modules. As TKB links the relocatable object
modules,
it creates an internal table of the global symbols it
encounters within each module.
If, after TKB examines and links all
the object modules,
references remain to symbols that have not been
defined, TKB assumes that it will find the definition for the symbols
within the default system object module library (LB:[l,l]SYSLIB.OLB).
If undefined symbols still remain after SYSLIB is examined, TKB flags
the symbols as undefined.
If you have not specified an output map in
your TKB command sequence, TKB reports the names of the undefined
symbols to you on your terminal.
If you have specified an output map,
TKB outputs to your terminal only the fact that the task contains
undefined symbols.
The names of the symbols appear on your map
listing.
When creating the task image file, TKB resolves global references, as
shown in the following example.
Table 2-4 lists the three files INl,
IN2, and IN3, showing the program sections within each file,
the
global symbol definitions within each program section, and the
references to global symbols in each program section.
Table 2-4
Resolution of Global Symbols for INl, IN2, and IN3
File
Name

Program Section
Name

Global
Definition

Global
Reference

INl

Bl
B2

A
Ll
Cl

xxx

c
IN2

A
Bl

B
IN3

B2
Bl

2-7

TASK BUILDER FUNCTIONS
In processing the first file, INl, TKB finds definitions for Bl and B2
and references to A, Ll, Cl, and XXX. Because no definition exists
for these references, TKB defers the resolution of these global
symbols.
In processing the next file, IN2, TKB finds a definition for
A, which resolves the previous reference, and a reference to B2, which
can be immediately resolved.
When all the object files have been processed, TKB has three
unresolved global reference: Cl, Ll, and XXX.
Assume that a search
of the system library LB:[l,l]SYSLIB.OLB resolves Ll and XXX, and TKB
includes the defining modules in the task's image.
Assume also that
TKB cannot resolve the global symbol Cl. TKB lists it as an undefined
global symbol.
The relocatable global symbol Bl is defined twice. TKB lists it as a
multiply defined global symbol. TKB uses the first definition of that
multiply defined symbol.
Finally, an absolute global symbol (for example, symbol=lOO)
can be
defined more than once without being listed as multiply defined, as
long as each occurrence of the symbol has the same value.

2.2

THE TASK STRUCTURE

TKB builds the data structures required by other system programs and
incorporates them into the task image.
The Executive (which is
responsible for the allocation of system resources) must have access
to the data for all tasks on the system.
It must know, for example, a
task's size and priority, and it must have information about the way
each task expects to use the system.
It is the Task Builder's
responsibility to allocate space in the task image for the data
structures required by the Executive.
For example, TKB allocates
space for the task header and initializes it.
The disk image file created by TKB contains the linked task and all of
the information required by the system programs to install and run it.
In its simplest form, the disk image file consists of three physically
contiguous parts:
•

The label block group

•

The task header

•

The task memory image

Figure 2-4 illustrates the basic simplified structure of this file.
The label block group contains data produced by TKB and used by
INSTALL command processing.
It contains information about the task,
such as the task's name, the partition in which it runs, its size and
priority, and the logical units assigned to it. When you install the
task, INSTALL command processing
(hereinafter called INSTALL)
uses
this information to create a Task Control Block (TCB) entry for the
task in the System Task Directory (STD) and to initialize the task's
header information.
The task's header contains information that the Executive uses when it
runs the task.
The header also provides a storage area for saving the
task's essential data when the task is checkpointed. TKB creates and
partially initializes the header;
INSTALL initializes the rest of the
header.

2-8

TASK BUILDER FUNCTIONS

0
:

MEMORY :

HEADER

LABEL
BLOCK
0
ZK-380-81

Figure 2-4

Disk Image of the Task

The task memory contains the linked modules of the program and,
therefore, the code and data.
It also contains the task's stack.
The
stack is an area of task memory that a task can use for
temporary
storage and subroutine linkage.
It can be referenced through general
register 6, the stack pointer (SP).
The label block g~oup, the task's
header, and the task memory are described in detail in Appendix B.
The task's memory image is the part of your task that the system reads
into physical memory at run time.
The label block group is not
required in physical memory.
Therefore, in its simplest form,
the
task's memory image consists of only two parts:
the task header and
task memory. Figure 2-5 shows the memory image.

TASK

•

MEMORY :

HEADER

o-----..
ZK-381-81

Figure 2-5

Memory Image

2-9

TASK BUILDER FUNCTIONS
2.3

OVERLAYS

This section is an introduction to overlaid tasks.
overlaid tasks can be found in Chapters 3 and 4.

Details

about

Using overlays can save memory space by reducing the size of the
executing portion of the task or the physical memory required by the
task. Parts of an overlaid task reside on disk, thereby saving memory
space.
An overlaid task is a task designed to have discrete parts. The parts
of a task designed this way can execute relatively independently of
other parts. Parts of an overlaid task reside on disk until they are
needed for their required function.
The common part of the task,
which stays in memory, is the root. The root calls the other parts of
the task, which are referred to as segments, from disk into memory.
The RSX-llM/M-PLUS systems have two types of overlaid tasks. One type
of overlaid task reads in segments from disk over other segments
already in memory. A task of this type is called a disk-resident
overlaid task.
In this task, segments reside on disk until they are
needed. The segments in disk-resident overlays that share the same
memory address space of the task with other segments must be logically
independent of those segments. The independence is necessary because
the other segments are on disk and cannot be referenced. For example,
Task A, an overlaid
ta~k
root,
can
call
either
of
two
segments: segment B or segment C. The root of Task A initially calls
segment B. Segments B and C occupy the same memory space. Segment B
cannot call segment C and segment C cannot call segment B. However,
if segment B returns control of the task to the root of task A, the
root can then call segment c.
Segment C would then be read into
memory over segment B. Figure 2-6 illustrates this sequence.
Because segments of a disk-resident overlaid task can occupy the same
memory space, a disk-overlaid task can occupy less memory than it
would if it were not overlaid. However, more disk I/O transfers (and,
therefore, more time) are needed for this type of task.
Another type of overlaid task is the memory-resident overlaid task.
In this task, the segments reside on disk until they are needed. At
that time, the needed segment is read into a sequentially adjacent
area of memory and resides there until the task ends. For example, a
memory-resident overlaid Task A has two segments:
segment B and
segment C.
If the root of task A calls segment B, segment B is read
into memory adjacent to the root. When the root regains control and
then calls segment C, segment C is read into memory adjacent to
segment B. Figure 2-7 illustrates this sequence.
Memory-resident overlaid tasks execute faster than disk-resident
overlaid tasks.
The increase in speed occurs because fewer disk I/O
transfers are needed during task execution.

2-10

TASK BUILDER FUNCTIONS

MEMORY

TASK A
ROOT

LOAD TASK

MEMORY

B
ROOT CALLS
SEGMENT B

TASK A
ROOT

MEMORY

c
ROOT CALLS
SEGMENT C

TASK A
ROOT

ZK-382-81

Figure 2-6

Simple 2-Segment, Disk-Resident Overlay Calling Sequence

2-11

TASK BUILDER FUNCTIONS
MEMORY

LOAD TASK

TASK A
ROOT

MEMORY

B
ROOT CALLS
SEGMENT B

TASK A
ROOT

MEMORY

c
B
ROOT CALLS
SEGMENT C

TASK A
ROOT

ZK-383-81

Figure 2-7

Simple 2-Segrnent, Memory-Resident Overlay Calling
Sequence

2-12

TASK BUILDER FUNCTIONS
2.4

ADDRESSING CONCEPTS

The primary addressing mechanism of the PDP-11 is the 16-bit computer
word.
The maximum physical address space that the PDP-11 can
reference at any one time is a function of the length of this word.
Because of the 16-bit word size, a task can have an address no larger
than 177777(octal) (32K words) within the task image for nonprivileged
tasks on an unmapped system.
In practice, the task size may be
limited to a few words less than 32K because of system design.

2~4~1

Physical, Virtual, and Logical Addresses

Physical, virtual, and logical addresses, and virtual and logical
address space, are concepts that provide a basis for understanding the
functions of task addressing and the use of task windows.
•

Physical addresses - A single, physical location in memory
called the physical address.

Memory is divided into parts called bytes. They are numbered
according to their position in memory. Therefore, the lowest
byte is O and the highest byte is whatever the upper limit of
memory may be for a particular system;
for example, 32K, 64K,
and so forth.
The assigned number is called the physical
address.
A task contains addresses (for example, O through 2200).
TKB
relocates the task's addresses in an unmapped system by a
number represented by the base address of the partition in
which
it is installed.
After installation, the task's
addresses refer to physical addresses of memory, which always
correspond to the same physical memory in an unmapped system.
Therefore, the task addresses have an actual one-to-one
relationship to physical memory. The same relationship exists
any time the task is in memory.
The memory (physical)
addresses will not be from O through 2200. For example, after
the task is installed in the partition, the task's address of
O may become physical address 17000 because the Task Builder
added in the offset, which is equal to the partition base
address.
In a mapped system, the task's addresses remain the same but
the physical memory addresses may change due to Executive
processes
(checkpointing,
swapping,
and
so
forth.).
Therefore, the task addresses do not always correspond to the
same physical memory.
If the task uses memory management
directives, the memory addressing can be changed by the task
to include any part of physical memory that it is allowed to
access.
•

Virtual addresses - A task's
addresses within the task.

virtual

addresses

are

the

The PDP-ll's 16-bit word length (a mapped system) imposes the
address
range
of 32K words on the virtual addresses.
Therefore, these task addresses could include addresses 0
through 177777(octal) depending on the length of the task.
These task addresses are not the same as the actual addresses
of the memory in which the task resides.

2-13

TASK BUILDER FUNCTIONS
•

Virtual address space - A task's virtual address space is that
space encompassed by the range of virtual addresses that the
task uses.
With the Create Address Window (CRAW$) memory management
directive, a task can divide its virtual address space into
By using address
segments called virtual address windows.
windows, you can manipulate the mapping of virtual addresses
to diDferent areas of physical memory.

•

Logical addresses - A task's logical addresses are the
physical memory addresses that the task can access.

actual

•

Logical address space - The task's logical address space is
the total amount of physical memory to which the task has
access rights.
The physical memory represented by the logical addresses may
or may not be continuous. The items in physical memory that
logical address space includes are the task itself, and static
and dynamic regions.

2.4.2

Unmapped Systems

In an unmapped system, the task's virtual address space and
logical address space coincide exactly, as shown in Figure 2-8.

its

In an unmapped system, the task's address space is limited to 32K
words.
All of the machine's physical memory and all of its device
registers are accessible to all tasks running on the system. The top
4K words of address space are reserved for the UNIBUS addresses that
correspond to the peripheral device registers (the I/O page), and a
segment of low memory is occupied by the Executive. Therefore, in an
unmapped system, the largest task size is 32K words minus the I/O page
and the size of the Executive. Figure 2-9 shows the memory layout for
an unmapped system.
Unmapped systems contain only user-controlled partitions.
When TKB
links the relocatable object modules of a task that is to run on an
unmapped system, it requires that you specify the partition in which
the task is to run, and the partition's base address and length. TKB
sets the base address of the task to the base address of the
partition.
This means that the task's location in physical memory is
bound to the partition and does not change. Because all of physical
memory in an unmapped system is directly addressable, and the task's
location within memory does not change, the addresses that TKB assigns
coincide exactly with the physical addresses of the machine and,
therefore, do not need to be relocated at run time.

2.4.3

Mapped Systems

A mapped system is one in which the processor contains a KT-11 memory
management unit.
The processor handbook for your machine contains a
complete description of the memory management unit.
Mapped processors have up to three modes of operation:
kernel,
superv,isor, and user
(the PDP-11/34 does not have supervisor mode).
The information in this section is relevant to user mode only.

2-14

TASK BUILDER FUNCTIONS

PHYSICAL
MEMORY

32K TASK

N+32K

32K

VIRTUAL
ADDRESS
SPACE
BEFORE
ASSIGNING
ADDRESSES

N = PARTITION
BASE ADDRESS

LOGICAL
ADDRESS
SPACE

0 - - - - - - --------~~

ZK-384-81

Figure 2-8

Virtual and Logical Address Space Coincidence
in an Unmapped System

In a mapped system, the relationship between virtual address space and
physical address space is different from that of an unmapped system.
The primary addressing mechanism for a mapped system is still the
16-bit word, and virtual address space is still 32K words.
However, a
mapped system has a much greater physical memory capacity and,
therefore, physical memory and virtual address space do not coincide.
To address all of physical memory in a mapped system, a machine must
have an effective word length of 18 or 22 bits, depending on the model
of the machine. When TKB links the relocatable object modules of a
task that is to run on a mapped system, it assigns 16-bit addresses to
the task image. The memory management unit's function (under control
of the Executive}
is to convert the task's 16-bit addresses to
effective 18- or 22-bit physical addresses.
The mechanical job of
task
relocation is performed by the Executive and the memory
management unit at task run time.
Figure 2-10
illustrates the
relationship between physical memory and virtual address space in a
mapped system.

2-15

TASK BUILDER FUNCTIONS

32 K WORDS
1/0

PAGE

• EXECUTIVE•

0
ZK-385-81

Figure 2-9

Memory Layout for Unmapped System

The memory management unit divides a machine's 32K words of virtual
address space into eight 4K-word segments or pages. Each page has two
registers associated with it:
•

A 16-bit Page Description Register
(PDR), which contains
control and access information about the page with which it is
associated

•

A 16-bit Page Address Register
relocation register

(PAR),

which

address

The PDRs and PARs are always used as a pair.
Each pair is called an
Active Page Register
(APR).
Figure 2-11 shows how the memory
management unit divides the 32K words of virtual address space.
The Executive allocates only as many APRs as are necessary to map a
given task into physical memory.
Therefore, a 4K-word task requires
one APR;
a 6K-word task requires two. Figure 2-12 illustrates this
mapping.

2-16

TASK BOILDER FUNCTIONS

•
•
•

HIGHEST
PHYSICAL
ADDRESS

TASK
MEMORY

32K------....MEMORY
MANAGEMENT
UNIT

HEADER

TASK
MEMORY
TASK
MEMORY

SYSTEM-CONTROLLED
PARTITION

HEADER
Q_.___
_ __
HEADER
VIRTUAL ADDRESS
SPACE
FOR 32 K WORD
TASK

TASK
MEMORY

HEADER
TASK
MEMORY

PARTITION _...__H_E_A_D_E_R_,..
BOUNDARY
• EXECUTIVE •
•
ETC.
•

•

•
0

I
PHYSICAL
MEMORY

Figure 2-10

Task Relocation in a Mapped System

2-17

ZK-386-81

TASK BUILDER FUNCTIONS

PAGE 7
VIRTUAL 160000 -

APR7 PAGE 6

VIRTUAL 140000 -

APR6 PAGE 5

VIRTUAL 120000 -

APR 5 PAGE 4

VIRTUAL 100000 -

APR4 -

32K WORDS OF
VIRTUAL ADDRESS
SPACE

PAGE 3
VIRTUAL 60000

APR3PAGE 2

VIRTUAL 40000

VIRTUAL 20000

VIRTUAL 0

APR 2 -

APR 1

PAGE 1

PAGE 0

APR 0
ZK-387-81

Figure 2-11

Memory Management Unit's Division of Virtual
Address Space

Finally, the layout of the virtual address space for a task that is to
run in a mapped system is different in most cases from that of a task
that is run in an unmapped system.
Unless a task is privileged,
the
I/O page and the Executive are not normally part of a task's virtual
address space and, unlike in an unmapped system, a task is inhibited
by the system from accessing any portion of physical memory that it
does not specifically own. Because the I/O page and the Executive are
not
part
of a
task's virtual address space, a task can be
approximately 32,767 words long (32K minus 32 words needed by the
loader)
on a mapped system. TKB can build a task of 32K minus 1 word
in size.
However, overlaid tasks, and tasks that become extended, may
use the entire 32K-word space.

2.4.4

Regions

This section briefly descr1oes regions and their relationship to and
use by tasks.
Regions and their use are more thoroughly described in
Chapter 5.
A region is a defined area of memory that can contain code or data.
It can also be a blank area reserved for use by one or more tasks.
The region is named and built like a task except that the /HD header
switch is negated (/-HD) because the ~egion is not a task and does not
need a task header.
Tasks can also create regions dynamically as they
execute.
Dynamic regions are useful because they increase the task's
logical address space while saving its virtual address space. Regions
also allow tasks to share code and data with other tasks.

2-18

TASK BUILDER FUNCTIONS

160000 APR 7 -

APR 7 -

140000 APR 6 =

Anoc.Mrn u

120000 APR 5 -

APR 5 -

100000 APR 4 -

APR4-

60000 APR 3 -

APR3-

40000 APR 2 -

APR2-

20000 APR 1 TASK
MEMORY

VIRTUAL 0 APR 0 -

HEADER &STACK
.________,

APR 1 -

4 K WORDS

TASK A (4 K WORDS)

APRO-

TASK
MEMORY

6 K WORDS

-----------1
HEADER & STACK

TASK B (6 K WORDS)
ZK-388-81

Figure 2-12

Mapping for 4K-Word and 6K-Word Tasks

Regions are named according to their use or the way in which they were
built. These regions are:
•

Task Region -- A continuous block of memory in which the
runs.

•

Common Shared Region -- On unmapped systems, a shared region
defined by an operator at run time or built into the system
during system generation;
for example, a global common area.

2-19

task

TASK BUILDER FUNCTIONS
Resident commons are usually called shared regions because
they are used as an area in which tasks share common data.
Shared regions can be absolute or position independent.
Shared regions and their use are described in Chapter 5.
•

Library Shared Region -- A shared region containing common
code or routines shared by tasks,
and in this way saving
virtual address space in the tasks.

•

Dynamic Region -- A region created dynamically at run time by
the Create Region (CRRG$) memory management directive in the
task.
This directive and associated directives are described
in the RSX-llM/M-PLUS Executive Reference Manual.

By convention, a shared region that contains code is a library
shared region that contains data is a common.

and

Tasks must map to a region by using task windows which must be defined
and numbered in the task when the task is built.
Usually, a task uses
one window for each region to which mapping must occur.
Task windows
are described in the next section, Task Mapping and Windows.
Figure 2-14 shows a sample collection of regions that could make up a
task's logical address space.
A task's logical address space can
expand and contract dynamically as the task issues the appropriate
memory management directives.
The header and root segment are always
part of the region.
Therefore,
the task header and root segment
always use window 0 (UAPR 0) and region O. Because a region occupies
a continuous area of memory, each region is shown as a separate block.

2.5

TASK MAPPING AND WINDOWS

As mentioned earlier,
tasks that run on mapped systems must be
relocated at run time.
When you build a task that is to run on a
mapped system, TKB creates and places in the header of the task one or
more 8-word data structures called window blocks. When you install a
task, INSTALL initializes the window block(s).
Once initialized, a
window block describes a range of continuous virtual addresses called
a window.

2.5.1

Task Windows

A window can be as small as 32 words or as large as 32K words. When a
task consists of one continuous range of addresses (a single region
task) only one window block is required to describe the entire task
from the beginning of its header to the highest virtual address in the
task.
When a task consists of two or more regions
(such as a
task
that references a
shared region as described in Chapter 5), each
region must have at least one window block associated with it that
describes all or a portion of the region.
When the Executive maps a task into physical memory, it extracts the
information it requires to set up the APRs of the memory management
unit from the task's window block.

2-20

TASK BUILDER FUNCTIONS
In;' ,an·' RSX~ HM. :system, 'rega,tdJ:ess. o.£' .·the: numbEir' :o,f .. regJo,ns: • 'asspcta ted
t.as·~;' "the· ,'re,gio'n ,'that.'.confa,~·p's, t:he :t~.sk' f3.' 'header a~d .r?c)t i.$
al.~a,¥f3' :def3pr,U~ed by :\tl~pdo,w o ~.·, Wirhd<)Ml,s: /0 ::.and ·l ,despribe· .tlfe ·:r'oo:t of ..::m·

with

a, :

.::.~.~.:,'a,~;' ,p':'·s,.1?.fi.· ·.· .: ,·~·~w .:Jn: ~.~1.:~~X-l;lt4:-·~LQS,/.sysf:e1n .• ·. ·.wi:n~ow.·c>.',.a.es.cr::ibes· ··t'tie'
:.Iff?P~~~.:' ,t.q~~tF ""~.d;' ,~ii10.()w' ::i:· :a:esq;7 ib'9s; ,t.he· ~D:--space,.: ·r:oot: aria.' task: . header·~
·E''\?i'r.~I!~otJe.~/',. itt-Ji·s ;'Jr~<Ji<:.>fl.: :~·~.'.·>'re:f'e:p:~d.: ,to .a.~ .::tqe .t«:~sk· .r.egi.on' and.is
i~~i:idifi~:;·,:<;lsr:C.~g.~aµ;'.:<.V~:

Figure 2-13 ill us.trates window block o for a
Wi.n9·ows: fbl{ ap.: :r~, .aricl .o~s.p·ae;e .task a·re·

'system wf thou FY..:· a'rid D-space.

,pffi,s.c.r0:i~~(:: ~·l;l x.t1!~#~:%:'

HIGHEST VIRTUAL
ADDRESS

1
I

TASK REGION -

WINDOW BLOCK

TASK
MEMORY

REGION 0

HEADER & STACK
LOWEST VIRTUAL
ADDRESS

Figure 2-13

ZK-389-81

Window Block 0

When you run your task, the Executive determines where in physical
memory the task 1s to reside.
The Executive then loads the Page
Address Register portion of the APRs with a relocation constant that,
when combined with the addresses of the task, yields the 18- or 22-bit
physical address range of the task.
Referring to Figure 2-14, which illustrates a mapped system without rand D-space, you can observe that a large 32K user task contains three
distinct areas of continuous space called "windows." The term "task
window"
is a construct that maps a continuous portion of the task's
virtual address space to a continuous portion of a
region in the
task's logical address space. Windows must have a specified size and
starting address.
The window size can be from 32 words to 32K minus

2-21

TASK BUILDER FUNCTIONS
32 words, and windows must start on a 4K address boundary.
Figure
2-14 shows three windows that are not continuous in the task's virtual
address space.
However, the space within each window is continuous.
In this task,
the size of window 0 is llK;
the size of window 1 is
llK;
and the size of window 2 is SK.
The concept of windows exists
for the following specific reason.
By using the concept of windows and the memory management directives,
a nonprivileged task can access a larger logical memory space than
that implied by the 32K virtual addressing range and normally
accessible by the 16-bit address.
A task can, in fact, only access
32K of memory at one time.
However, a nonprivileged 'task can change
its access to logical addresses (real, physical memory).
The area
that your program accesses can be changed by the program during
program execution.
The process of accessing different logical areas
of memory is called "mapping."
By referring to Figure 2-14, you can see that window 1 in the task is
mapped to region 1 in physical memory.
The task can change the window
1 mapping to region O in physical memory.
In effect, then, though a
task is limited to a range of 32K virtual addresses, a task can access
all the physical memory available to it (determined by the way that
you set up the mapping)
by changing the mapping of its windows to
different logical addresses.
Figure
2-14
provides
a
visual
description of the concept of mapping to different logical addresses.
The discussion now proceeds to setting up the task's windows.
done by defining task window blocks to TKB.

This is

To manipulate virtual address mapping to various logical areas, you
must first divide a task's 32K of virtual address space into segments.
These segments are task
(virtual address)
windows.
Each window
encompasses a continuous range of virtual addresses.
The first
address of the window address range must be a multiple of 4K
(the
first address must begin on a 4K boundary) because of the way that the
KT-11 memory management unit uses APRs.
On an RSX-llM system, you ,can
specify up to S!even : windows.,
Task
mapping for the task's code requir:es the use of lwindqw, o. Therefore,:
there is a total of eight windows.
However, window 0 j,5 not ,available
to nonprivileged tasks. ' The si'ze of each wi;ndow :can range from: a
minimum of 32 words to a maximum: of 32K minus 32 wor.d$.'

RSX-llM-PLUS tasks that use I- and D-space or
supervisor-mode
libraries have a
total of 16 windows.
You can specify u~ tQ 14
windows in this ,type of task. Windows 0 and 1 ane not available, to
nonprivileged tasks in this kind of system.
A task that includes directives that dynamically manipulate address
windows must have task window blocks set up in the task header as well
as Window Definition Blocks in the code for use by the Create Address
Window directive.
The Executive uses task window blocks to identify
and describe each currently existing window. When linking the task,
the programmer specifies the number of extra window blocks needed by
the task.
The number of blocks should equal the maximum number of
windows that will exist concurrently while the task is running.

2-22

PHYSICAL MEMORY

KT11 MEMORY MANAGEMENT UNIT
VIRTUAL ADDRESS SPACE
of 32K USER TASK

I APF
15

OF
13 12

APF
4K

SELECT
APR

PAR
4

3
I\)

]

-----HEADER

0
DIB

PDR

PAR

PAF

PDR

::iq

{

°'

Cl
H

y
(
17

CONTAINS
3 WINDOW BLOCKS

REGION 1
WINDOW 1

t"'
0
tzJ

KAPA OR UAPR
11 USER
00 KERNEL
DETERMINED BY BITS 14-15 OF PSW

REGION 0

t/l

TASK
LOGICAL
ADDRESS
SPACE

KERNEL
ACTIVE PAGE REGS

1
WINDOW 0

USER
ACTIVE PAGE REGS

I\)

PBN

REGION 2
WINDOW 2

t'Zj

z()
8
H

J
l
65

18-BIT PHYSICAL ADDRESS

]

t/l

TASK REGION
WINDOW 0

]

L._E-XEC-UTl-VE_

____,J
ZK-390-81

Figure 2-14

Virtual to Logical Address Space Translation

TASK BUILDER FUNCTIONS
In RSX-llM or RSX-llM-PLUS without I- and D-space, a window's
identification is a number from 0 to 7, which is an index to the
window's corresponding window block. The address window identified by
0 is the window that always maps the task's header and root segment.
TKB creates window O, which the Executive uses to map the task.
No
directive may specify window O; a directive that does so is rejected.

In' ~P' <RSX~lt~-:I?i:.us'/s,y~tem usLng an ;1~, 'and ;p~,space ,,' task·r· a window~,s
,'.ident,ifi:cat'i.o·~ .: .ls. '.<;t ..,nµmp~r , from . Oc'to 1·?~ wb'fcl) ·is· ari· inde~: to the···

5•1indo,w' $<·99:1;>r.espo,ndiI1~·· :window 'b1ock·~·. r;rne aodr·es'.s .. windows' }denti f'ied
by. o ··a.rid .1:.a,re the' wfod;o:ws/.tn·~t a,lw(iys'.,map·'.t.he, tas~'·s.)1ead~r·.,and. root':•;
·T·KB. c·r~~,a~es.: ;\V~(~o~~:·,o· ·~11(i 1,,,·whtc11. ·tll~ ~~~(:.,49.v~ ·l1s~·~· to· :ma}?: tb~, ta~k.'
'>N.9, . '.d;ir'~ct:i.v:e/;IllitY/;~;peci$y, V1irigo.ws'.·,o'.<'o,r./ J ;:· · ?v :d!'re:ct'i~e .~n~t: ¢10,e~·' sq· ·is":
':·t-eje<ited,·/,<·";" ,·'.·i,/" ./'<>
,' · ' ,, · ,··' , ', · ,' · ,. · · .· ·., .: · ··' ·
When a task uses memory management directives, the Executive views the
relationship between the task's virtual and logical address space in
terms of windows and regions. Unless a virtual address is part of an
existing address window, the address does not point anywhere. This is
a point to watch when setting up windows with the Create Address
Window directive (CRAW$). Similarly, a window can be mapped only to
an area that is all or part of an existing region within the task's
logical address space.
Once a task has defined the necessary windows and regions, the task
can issue memory management directives to perform operations such as
the following:

2.6

•

Map a window to all or part of a region.

•

Unmap a window from one region in order to map it
region.

•

Unmap a window from one part of a region in order to map it to
another part of the same region.

another

RSX-llM-PLUS SUPERVISOR MODE

Three modes of operation are possible in the PDP-11:
user mode,
supervisor mode, and kernel mode. Each mode has associated with it 16
APRs for mapping memory: 8 I-space APRs and 8 D~space APRs.
A task
in the RSX-llM:-PLUS system can use supervisor-mode 1.ibr.aries .and
thereby double the task's virtual address space to 64K words.
Supervisor-mode librari~s are described in Chapter 8. This section
bri'efly describes supervisor mode and the mapping that occurs when the
ta~k uses supeivisor mode.
·
Supervisor.,,mode libra'ries .are librades of routines that are. USE!d only
in s,upervisor to.ode~·. The task .switches to. supervisor mode when it
call~ a routine
within the supeivisor-mode library.
By u~irig a
supervisor mode lJbrai:y as described . i.n.,. . Chapter .. 8, you. mak,e. the
RSX-·llM-PLUS system, for large systems, use the. supervisor-Mode APRs.

·2. 6 • l

$uperv i sor-Mode Mapping

~ormall'y, a ,task has .an address space of 32K-wo.rds by using eight user
APRs •.. When a conventioria.l task 'links to a .supervisoI:-mode library and.
cal.ls ,a routine in the . li}Jrary,: the .ExecuHve· copies the user-mode .
·I-space AP~s into the supervisor-mode D-space APRs arid maps the
supervisor-mode. library·· with ·supervisor I-space APRs.
Therefore,
while. in supervis.or, .mod.e and within 'the .library,_ 'the task can access
32K-words of its 'own space with D-space AP~s ,and 32K~words of library

2-24

TASK BUILDER FUNCTIONS

.t:~,!~~!{~~!t:~~i~~:~t~~~~y~t }'~'i. ~y~,t ?~ ':~Oei~fB~-r.1-',h:i.d.l. ~ti~ice~:s
,.·wneri:·:.':~'n: .:'.J- arid 'D~;~p~c~' task 'i,i.:hks.'io. .a',' ~up~i~i~or-mode." ,l.ibrary, 'the
/ E:xe¢.ut'fy.e>·. cop'i·es ·' the.· user-mode' '.':[.)...:space .A.PRs '/into the· s'upervis'or
,:o:..:·:3pa,q~:.·1(pR~. . Th'ere,f,ore,;,, ,the, supervJs,or..:mo~e, :foutffiefo "ban· ·a6'~'esf$ u.s~'r·
','Q.at.a.,:, :::,;·~·pace.·:.: ,. J:tnl'.i:::, ·'ac(:ess ,· 9uperw~'sor-mode· i'ns·tr~cti.on · space· ·wi,th
· s:uf>ervis~r .· i~sp~c,e.... z~tPRs··~··,.,:Fig~r~·. ·a..:.,2,. i~i,ust~at:e~ .. ,;·.t:hi:s·,.fnap'.PJn9:.,,,, ,··. 'rh~·
'm,appirm . :',i'j,i1s~./,.'¢1.es,c/r·~·Oe;d1:,<'.r~·,, . tJJe'/,~e,~a,,ur1f.· map~i:n,9 fo"r, ,:'a'Q 1 ,i'l~. ·· ·~nd,:,D.:s'p~c~/
tas~k/~,.·,,, .. Ypu car("e:cp.l~.si.~li: 1.cr·ea't.e· . :,'s·\:lpei:,v~~~r~mq?,e, 'P~.sp~c·e, tn;appJf?g;· : .t,:9,·
'bv:e'rr'.ioe ' 'the"' .us·e'r'-mode',·· .'·D~:spac,~;.<>vermapp:i/nii
'that', odcurs' by. us'ing' the'
"MSIJS$ .":mxecuti~e . "tlirectdiv~~c" ehai)ter -,,$" ci&scu"SS~S the ,"u'se :'o,f :Msos$ ::,: '""'
m

.!#fJ~~~i#;~~j~~~~~l~t~f~i~JrZJ;t~ti1~iI~z¥A~;~~tn~
,. :l;J,.b·

~l~ ,i::; 'fa ,~.-' ·_ ii~~ ·~,
y

2.7

; ;·lfs.:,·shp:wn

iat>e ,2,-1,6....1· , ; ,..,,,"

~, ,,~ ~,/:' ~~~ ~/ ;'t '1;j,. .:· ~ (' ,;·

' :- ; /

,;_~,' 1 ~-; ~
<

~:. ~. ~~·,

;

i?" -~,: ';;=f

~:~

PRIVILEGED TASKS

RSX-llM/M-PLUS systems have two classes of tasks:
privileged and
nonprivileged.
However, the term "privileged" has meaning in mapped
systems only, because in mapped systems certain areas of memory are
protected from nonprivileged tasks.
In an unmapped system, any task
has the ability to access all of physical memory if so programmed.
Therefore, the distinction between these two classes of tasks is
primarily one of their mapping to memory in a mapped system.
Privileged tasks in a mapped system can access system data areas and
the Executive. Altering system data areas or the Executive can cause
obscure and difficult problems. Therefore, privileged tasks must be
programmed and used with all caution.
You can specify a task as privileged by using the /PR switch in the
TKB command line. The /PR:O switch allows a task to perform certain
privileged operations;
but, the /PR:O task cannot access
the
Executive or system data structures. The /PR:4 switch allows the task
to directly map the I/0 page, Executive routines, and system data
structures.
The /PR:4 switch is used for a privileged task in a
system that has an Executive of 16K or less. The /PR:5 switch allows
a task to directly map to the I/O page, Executive routines, and system
data structures. The /PR:5 switch is used for a privileged task in a
system that has an Executive of 20K or less.
Chapter 6 describes privileged tasks and their mapping in detail.

2-25

TASK BUILDER FUNCTIONS

TASKS

MEMORY

APRS
USER D

NONPRIVILEGED
USER
TASK

1/0 PAGE

32K
N+32K
USER I

USER
TASK

0
N

SPVSR D

7
SUPERVISORMODE
LIBRARY
32K

N+32K
SPVSR
MODE
LIBRARY

SPVSR I

KERNEL D
EXECUTIVE

--1---------1 36K
POOL,
COMMON,
TABLES,
ETC.

DATA

KERNELi
INSTRUCTIONS

CODE

l+D

__....__ _ _ _ _ _

"l------~
~~~~~___._

_LOW
_ _CORE
_ __.. 0

ZK-391-81

bser .

,F:i~\)~e" '~~·~,l 5, ,Ma;pp i ~9; . :e·o :i;:' /a'.'• Conve~ fj:bnaJ./
Ta,s k :a 9<1 a •. Sys:te,tl1
·:.5SP.n;i;.·~·~:ning . a .S9);~er;~i~.r.-::-·~od.e .. ·~i.Qp~r:Y . : in .. ~n· ·RSX~ll}~~·PLPS sy~te"'.
I

•

2-26

TASK BUILDER FUNCTIONS

MEMORY

APRS

TASKS

USER D
NONPRIVILEGED
USER
TASK

1/0 PAGE

32K
N+32K
USER I

USER
TASK

0
N

COPIED

SPVSR D

SUPERVISORMODE
LIBRARY

,,,___ _ _ ___,. N+32K
SPVSR
MODE
LIBRARY

SPVSR I

KERNEL D
EXECUTIVE
POOL,
COMMON,
TABLES,
ETC.

DATA

KERNELi
INSTRUCTIONS

CODE

l+D
LOW CORE

........~-~~~-'-----~o

--~----

ZK-392-81

3· ;,';<p·,~i;<j;tti~:h~:tG:5q;~i;Jpd..~tj /:f(jt'. ~: .·aoli:ven.til,<>~~:('.:dsetrtTTasJt: •· . . . . '.
O:S~fii,9. :µ:· ·~upe.rvfsor-.M,ode.· t . ibl:'a.ry /i.n an :RSX:.-:i]:M~.P;r.1is· "system':·
'

,::

;

·' :,

•

• '.

•

;

•

• '

;

•

2-27

•

·l:,

TASK BUILDER FUNCTIONS
2 .•·8.

MULTIUSER TASKS·· (Rsx .... liM-PLUS ONLY)

The followi~g section. f~ an: :introductio'n.
ful.ly de~cribed in ·chap~ei .9 ..

to. multi.usEfr ·tasks·., wh.ich·. are
'I

TKB'allo~s·you ·to build multiuser ··task·s.; .A: .multiuser.:. 't·ask ·1''s)·/,tha\t..
whicfr·has one portio·n· . of.f~s· ·code. 'and dat'a :des'igI1,at~d .as .:~i:·e9-a~.onli"'arid
I

an~ther; ..portion: ·.9esigJl'at~d ·.~s read/~rtte~· ·.)~ou ',specHy, ~he .. r~a·~6<,>t1f~.
"por'.~i9ris 9f ,your . t~sk ~~i,th'. prog,ram se(;:~io[)s t11'at nave ,the •:r;ea·a!"',otify,
acce,ss code •.. When yo·u~ . then. '.b'uiJd, your tasJ,<· ·wi~h J:pe /MU .. " swtt~h;t,. ,TKB'.
•pla'ces ;tp.e ,·read-only,. J;?Or'ti.ons', ,·in '.a'.•regi,09 that,ha~ . a' Q'i,gh -rir.ttra'.l",,
·aadress·and ttie· r.ead/writ.e po:rt'ion in .. a..·region. ,that . ~31s a·lo.w· .. virtua·~:
.,aadr,ess ...... ~ny.. other .i;:equests. to.·run the. !=as.kr if.:.the. task· i~ a.;lr',eady
· r.un·riinsn ·, ~;.e·su,lts ,in ·~· .co.P,y··· o~·. t~e. re)i~/wri t~.· po.rtto'rr of,,, the·, ,:t;a~k./, J,n
phy$ical memory. tor. the . other Jis~·r .•.. Ther.e, is always .b.n.Iy o,.ne ,qbpy. ',of
the. :tead..;.only code regardl·ess .of .the· nrimbe'r. of ·tasks, .·.that.· "may· b.e
running;.
·
··
I

:<The /MU ·switch is des.cdbed in Chapter 10;

2.9

OSER-MODE I- AND D-:SPACE TASKS (RSX-llM-PLUS)

user tasks that use both 1-'and'o-space differ from conventional tasks
because I- and D-space tasks . have specifically defined locations
within the task for both instructions and data.
Because of this
separation, the I- and D-space task image is structurally different.
Additionally, the separate instruction areas are mapped through
sepa.rate APRs in the memory management unit. Hence, up to 8 user-mode
instruction APRs map the task's instructions, and up to 8 user-mode
data APRs .map the task's data.
Also, overlaid I- and D-space tasks are more complex because each
overlaid part (segment) of such a: task may reside in both instruction
space and data space.

I- and D-space tasks differ from conventional tasks in
major ways:

the

following

•

PSECTs with the "I" attribute contain only instructions
PSECTs with .the "D" attribute contain o~ly data.

•

Two sets of APRs map the I- and
APRs and the o ... space APRs.

•

I- and'D-space tasks can use up to 64K words of virtual space
instead .. of 32K wor=ds because gf .their ... use of" .the two sets of
APRs. With supervisor~mode libraries, an ~- and D-space task
can use up to 96K words of virtual SP?Ce.

D-space

The following have,· data. contiguously · adjacent
instructions contiguously adjacent' i'n. mem9ry.:

task:

the

and

I-space

memory,

and

•

Non-overla,id I- and D-space ·.tasks

•

Segments ·in an overlai.d I.- and f?:-sp~ce 'task that .,contal"n . both
·I- and o..,.spac.e

2-28

TASK BOILDER FUNCTIONS
. In:;''t!lese ,·t.:~.s.k:s· ;·o~: . ·t3~'¥k:: ;s;egfueri't. s, .: .·:t:-:.s{:>ace.<'..PSECT$ · · :a~e.·: . segregated'.
.;D,~··s,c~.a~e.: :PS EQT!:? ·· in· ·rri~mo;i:t y ;·:·· :" · th;E!y. :cannot:.: be . intermixed • ·
·
·

f:r.om,
·

:;F'i.:g. uret },.,.17 ·shows a. user-.:rriod~. t~. :a.nd .Q-:"sp9ce,. ,task, with . data · se.p,ar at ed.
f:rpm:":the· hist.r·u:it.i,.q.n~ .and 'rriilcpped ·.;t!'.'o.· memory·· through: two sets of 'APRs ~

?n
USER-MODE
APRS

TASK
VIRTUAL
ADDRESS
SPACE
4K

MEMORY

DATA
D-SPACE

0
4K
DATA
INSTRUCTIONS
INSTRUCTIONS

I-SPACE
ZK-1049-82
~

~·

.,.

.:~fil? ..'.Jf>~S;l?~9~ ~· .!r?ifeS.k:

2-29

CHAPTER 3

OVERLAY CAPABILITY

TKB provides you with the means to reduce the memory and/or virtual
address space requirements of your task by using tree-like overlay
structures created with the Overlay Description Language
(ODL).
You
can divide your conventional task into pieces called segments, which
are loadable with one disk access.
<rn.;'an~:'.u"r:..r:
~~cf.tfJij.
J\i'

~e
segments a~
the discrete parts of the overlay structure that form the tree. You
can specify two kinds of overlay segments:
those that reside on disk,
and those that reside permanently in memory after being loaded from
disk.

3.1

OVERLAY STRUCTURES

To create an overlay structure, you divide a task
segments consisting of:

into

series

•

A single root segment, which is always in memory

•

Any number of overlay segments, you must consider which either
1) reside on disk and share virtual address space and physical
memory with one another
(disk-resident overlays);
or 2)
reside in memory and share only virtual address space with one
another (memory-resident overlays)l

Segments consist of one or more object modules, which in turn consist
of one or more program sections.
Segments that overlay each other
must be logically independent;
that is, the components of one segment
cannot reference the components of another segment with which it
shares virtual address space.
In addition to the logical independence
of the overlay segments, you must consider the general flow of control
within the task when creating overlay segments.
You must also consider the kind of overlay segment to create at a
given position in the structure, and how to construct it. Dividing a
task into disk-resident overlays saves physical space, but introduces
the overhead activity of loading these segments each time they are
needed -- but are
not
present -- in
memory.
Memory-resident
overlays, on the other hand, are loaded from disk only the first time
they are referenced.
Thereafter,
they remain in memory and are
referenced by remapping.

1. Note that memory-resident overlays can be used only if the hardware
has a memory management unit, and if support for the memory management
directives has been included in the system on which the task is to
run.

3-1

OVERLAY CAPABILITY
Several large classes of tasks can be handled effectively when built
as overlay structures.
For example, a task that moves sequentially
through a set of modules is well suited to use as an overlay
structure.
A task that selects one of a set of modules according to
the value of an item of input data is also well suited to use as an
overlay structure •
.Tasks: that·;h1iyE{,,sepa~.at¢· ;!;~ and o~~i>.a.c~ may·;~iso :use over,fays·· ..~her.e
. the· . ro<>;t .• '.has.·.1.n:st'r;u,c·ti'Ops' .and;; da'.ta :s.~para.t!elY d,ef,i.QEfd· by .f>s,:~qTs, . ·.~nd
·~ach J;n?:ividua,1 s~gment·o,f. .,'the ··:tatSkL a·lso· . pas instructions ·.and .' data ·
. s'.~par'fl;t~J.y: J :a~(f~ea ... }.'cti~Pf:e,~·.:1~.:A~~ta}~?: ii\9.,re ,i'flfl.f.()rmCitihn about· 1~·~ ~ujd
1

p;::-s,pac~ ·t.a~~~;c.,

3.1.1

· '· ,

Disk-Resident Overlay Structures

Disk-resident overlays conserve virtual address space and physical
memory by sharing them with other overlays.
Segments that are
logically independent need not be present in memory at the same time.
They,
therefore, can occupy a common physical area in memory (and,
therefore, common virtual address space) whenever either needs to be
used.
The use of disk-resident overlays is shown in this section by an
example,
task TKl, which consists of four input files.
Each input
file consists of a single module with the same name as the file.
The
task is built by the command
>TKB TKl=OVRLAY.ODL/MP
and the file OVRLAY.ODL contains the modules CNTRL, A,
B, C in an
overlay description for
the task being built.
The /MP switch
specifies that the input file is an Overlay Description Language (ODL)
file.
In this example, the modules A, B, and C
that is:

are

logically

independent;

A does not call B or C and does not use the data of B or

B does not call A or C and does not use the data of A or C.
C does not call A or B and does not use the data of A or B.
A disk-resident overlay structure can be defined in which A, B, and c
are overlay segments that occupy the same storage area in physical
The flow of control for the task is as follows:
memory.
CNTRL calls A and A returns to CNTRL.
CNTRL calls B and B returns to CNTRL.
CNTRL calls

c and c returns to CNTRL.

CNTRL calls A and A returns to CNTRL.
In this example, the loading of overlays occurs only four times during
the execution of the task.
Therefore, the virtual address space and
physical memory requirements of the task can be reduced without unduly
increasing the overhead activity.
The effect of the use of an overlay structure on allocating virtual
address space and physical memory for task TKl is described in the
following paragraphs.

3-2

OVERLAY CAPABILITY
The lengths of the modules are:
Module

Length (in Octal)

CNTRL

20000 bytes
30000 bytes
20000 bytes
14000 bytes

A
B

Figure 3-1 shows the virtual address space and physical memory
required as a result of building TKl as a single-segment task on a
system with memory management hardware.
The virtual address space and physical memory requirement to build TKl
as a single-segment task is 104000(octal) bytes.
In contrast, Figure 3-2 shows the virtual address space and physical
memory required as a result of building TKl as a multisegment task and
using the overlay capability.
The multisegment task requires 50000(octal) bytes.
NOTE
In addition to the storage required for
modules A, B, and C, storage is required
for overhead in handling the overlay
structures.
This
overhead
is not
reflected in this example.
In using the overlay capability, the total amount of virtual address
space and physical memory required for the task is determined by the
sum of the length of the root segment and the length of the longest
overlay segment.
Overlay segments A and B in this example are much
longer than overlay segment C.
If A and B are divided into sets of
logically independent modules, task storage requirements can be
further reduced.
Segment A can be divided into a control program (AO)
and two overlays (Al and A2). Segment A2 can then be divided into the
main part (A2) and two overlays (A21 and A22).
Similarly, segment B
can be divided
into a control module (BO) and two overlays (Bl and
B2) •
Figure 3-3 shows the virtual address space and physical memory
required for the task produced by the additional overlays defined for
A and B.
As a single-segment task, TKl requires 104000(octal) bytes of virtual
address space and physical memory.
The first overlay structure
reduces the requirement by 34000(octal)
bytes.
The second overlay
structure further reduces the requirement by 14000(octal) bytes.
The vertical and horizontal lines in the diagrams of Figures 3-2 and
3-3 represent the state of virtual address space and physical memory
at various times during the calling sequence of TKl. For example,
in
Figure 3-3 the leftmost vertical line in both diagrams shows virtual
address space and physical memory, respectively, when CNTRL, AO,
and
Al are loaded.
The next vertical line sho~s virtual address space and
physical memory when CNTRL, AO, A2, and A21 are loaded, and so on.

3-3

OVERLAY CAPABILITY
The horizontal lines in the diagrams of Figures 3-2 and 3-3
indicate
segments that share virtual address space and physical memory.
For
example, in Figure 3-3, the uppermost horizontal line of the task
region in both diagrams shows Al, A21, A22, Bl, B2, and C, all of
which can use the same virtual address space and physical memory.
The
next horizontal line shows Al, A2, Bl, B2, and C, and so on.

160000

APR 7-

140000

APR 6-

120000

APR 5-

100000

APR 4-

60000

APR 3-

40000

APR 2-

20000

104000
BYTES
A

CNTRL
(ROOT SEGMENT)

HEADER AND STACK

APR 1-

APR 0-

VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY
ZK-393-81

Figure 3-1

TKl Built As a Single-Segment Task

3-4

OVERLAY CAPABILITY

I
160000 APR 7-

140000 APR 6-

120000 APR 5-

100000 APR 4-

60000

APR 3-

40000

APR 2A

20000

APR 1-

APR 0-

lI )

CNTRL
(ROOT SEGMENT)

HEADER AND STACK

50000
BYTE

VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY
ZK-394-81

Figure 3-2

3.1.2

TKl Built As a Multisegment Task

Memory-Resident Overlay Structures (Not Supported on RSX-llS)

TKB provides for creating overlay segments that are loaded from disk
only the first time they are referenced.
Thereafter, they reside in
memory. Memory-resident overlays share virtual address space just as
disk-resident
overlays
do
but, unL1Ke disk-resident overlays,
memory-resident overlays do not share physical memory.
Instead, they
reside in separate areas of physical memory, each segment aligned on a
32-word boundary. Memory-resident overlays save time for a running
3-5

OVERLAY CAPABILITY
task because they do not need to be copied from a secondary storage
device each time they are to overlay other segments.
"Loading" a
memory-resident overlay reduces to mapping a set of shared virtual
addresses to the unique physical area of memory containing the
overlaying segment.
The use of memory-resident overlays is shown in this section by an
example, task TK2, which consists of four input files.
Each input
file consists of a single module with the same name as the file.
The
task is built by the command
>TKB TK2=0VRLAY2.0DL/MP
and the file OVRLAY2.0DL contains the modules CNTRL, D, E, and F in an
overlay description for the task being built.
The /MP switch
specifies that the input file is an Overlay Description Language (ODL)
file.
In this example, the modules D, E, and F
that is:

are

logically

independent;

D does not call E or F and does not use the data of E or F.

E does not call D or F and does not use the data of D or F.
F does not call D or E and does not use the data of D or E.
A memory-resident overlay structure can be defined in which o, E, and
F are overlay segments that occupy separate physical memory locations
but the same virtual address space.
The flow of control for the task
is as follows:
CNTRL calls D and D returns to CNTRL.
CNTRL calls E and E returns to CNTRL.
CNTRL calls F and F returns to CNTRL.
The effect of the use of a memory-resident overlay structure on
allocating virtual address space and physical memory for task TK2 is
described in the following paragraphs.
The lengths of the modules are:
Module

Length (in Octal)

CNTRL
D

20000
10000
14000
12000

Figure 3-4 shows the virtual address space and physical memory
requirements as a result of building TK2 as a single-segment task on a
system with memory management hardware.
The virtual address space and physical memory requirements when TK2 is
built as a single-segment task is 56000(octal) bytes.
If TK2 is built using the Task Builder's memory-resident overlay
capability, the relationship of virtual address space to physical
memory changes, as shown in Figure 3-5.

3-6

OVERLAY CAPABILITY

160000

APR 7-

140000

APR 6-

120000 APR 5-

100000

APR 4-

60000

APR 3-

40000

APR 2-

Bl~ C
20000

...

APR 1- t - - - - - - . . . . . __ _......._---1
CNTRL
(ROOT SEGMENT)

APR O- .....__H_E_A_D_E_R_A_N_D_ST_A_C_K__ _

f A2

Blk

lA21J A22 ·

CNTRL
(ROOT SEGMENT)

34000

HEADER AND STACK

VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY
ZK-395-81

Figure 3-3

TKl Built with Additional Overlay Defined

3-7

OVERLAY CAPABILITY

1
160000 APR 7-

14000

APR 6-

120000 APR 5-

100000 APR 4-

60000

40000

APR 3-

i\
F

APR 2-

I
I

20000

APR 1-

APR 0-

56000
BYTES

l
CNTRL
(ROOT SEGMENT)

CNTRL
(ROOT SEGMENT)

HEADER AND STACK

VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY
ZK-396-81

Figure 3-4

TK2 Built As a Single-Segment Task

3-8

OVERLAY CAPABILITY

160000

APR 7-

140000

APR 6-

120000

I
I

APR 5-

100000 APR 4-

60000

APR 3-

40000

APR 2E
56000
BYTES
D

20000

APR 1CNTRL
(ROOT SEGMENT)

APR 0-

D
34000(8)
BYTES

HEADER AND STACK

CNTRL
(ROOT SEGMENT)
HEADER AND STACK

VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY
ZK-397-81

Figure 3-5

TK2 Built As a Memory-Resident Overlay

The physical memory requirements for TK2 do not change
(56000(octal)
bytes) , but the virtual address space requirements have been reduced
to 34000(octal) bytes.
This represents a savings in virtual address
space of 22000{octal) bytes.

3-9

OVERLAY CAPABILITY
NOTE
In addition to the storage required for
modules D, E, and F, storage is required
for overhead
in handling the overlay
structures.
This
overhead
is not
reflected in this example.
In Figure 3-5, the vertical and horizontal lines
in the virtual
address space diagram represent the state of virtual address space at
various times during the calling sequence of TK2.
The leftmost
vertical
line shows virtual address space when CNTRL and D are loaded
and mapped.
The next vertical line shows virtual address space when
CNTRL and E are loaded and mapped.
The third vertical line shows
virtual address space when CNTRL and F are loaded and mapped.
The uppermost horizontal line of the task region shows
D, E, and F share virtual address space.

that

segments

When TK2 is activated, the Executive loads TK2's root segment into
physical memory.
The Executive loads segments D, E, and F into memory
as they are called.
Once all segments in the structure have been
called,
"loading" of the overlay segments reduces to the remapping of
virtual address space to the physical locations in memory where the
overlay segments permanently reside.
Figures 3-6 and 3-7 illustrate
the relationship between virtual address space and physical memory for
task TK2 during four time periods:
•

TIME 1 (Figure 3-GA) - TK2 is run and the system loads
root segment (CNTRL) into physical memory and maps to it.

the

2 (Figure 3-GB) - CNTRL calls segment D.
The system
• TIME
loads segment D into physical memory and maps to it.
Segment
D returns to CNTRL.
•

TIME 3 (Figure 3-7A) - CNTRL calls segment E.
The system
loads segment E into physical memory, unmaps from segment D,
and maps to segment E.
Segment E returns to CNTRL.

•

TIME 4 (Figure 3-7B) - CNTRL calls segment Fe
The system
loads segment F into physical memory, unmaps from segment E,
and remaps to segment F.
Segment F returns to CNTRL.

3-10

OVERLAY CAPABILITY
Figure 3-6A Time 1

160000

APR 7-

140000

APR 6-

120000

APR 5-

100000

APR 4-

60000

APR 3-

40000

APR 2-

...

CNTRL
(ROOT SEGMENT)
0

APR 0- ...___HEADER
_ _ _AND
_ _STACK
_ _ ___.

CNTRL
(ROOT SEGMENT)
HEADER AND STACK

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

VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY
ZK-398-81

Figure 3-6A

Relationship Between Virtual Address Space
and Physical Memory -- Time 1

3-11

OVERLAY CAPABILITY
Figure 3-68 Time 2

160000

APR 7-

140000

APR 6-

120000

APR 5-

100000

APR 4-

60000

APR 3-

40000

APR 2-

D
20000

APR 1- 1 - - - - - - - - - - - . . . . . i -

CNTRL
(ROOT SEGMENT)
HEADER AND STACK

...
...

CNTRL
(ROOT SEGMENT)
HEADER AND STACK

VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY
ZK-399-81

Figure 3-6B

Relationship Between Virtual Address Space
and Physical Memory -- Time 2

3-12

OVERLAY CAPABILITY
Figure 3-7A Time 3

160000

APR 7-

140000

APR 6-

120000

APR 5-

100000

APR 4-

60000

APR 3-

40000

APR 2-

--~- --

....
E

....

E
20000

APR 1- ~----------i...- __ CNTRL
(ROOT SEGMENT)

CNTRL
(ROOT SEGMENT)
HEADER AND STACK

APR 0- ___H_E_A_D_E_R_A_N_D_s_T_A_c_K_ _
VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY
ZK-400-81

Figure 3-7A

Relationship Between Virtual Address Space
and Physical Memory -- Time 3

3-13

OVERLAY CAPABILITY
Figure 3-78 Time 4

160000

APR 7-

140000

APR 6-

120000

APR 5-

100000

APR 4-

60000

APR 3-

40000

APR 2E

F
20000

APR 1-

APR 0-

CNTRL
(ROOT SEGMENT)

HEADER AND STACK

VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY
ZK-401-81

Figure 3-7B

Relationship Between Virtual Address Space
and Physical Memory -- Time 4

It is important to be careful
in choosing
whether
to
have
memory-resident overlays in a structure.
Carelessly using these
segments can result in inefficient allocation of virtual address
space, because TKB allocates virtual address space in blocks of 4K
words. Consequently,
the length of each overlay segment should
approach that limit if you are to minimize waste.
{A segment that is
one word longer than 4K words, for example, is allocated 8K words of
virtual address space.
All but one word of the second 4K words is
unusable.)
3-14

OVERLAY CAPABILITY
You can also conserve physical memory by maintaining control over the
contents
of
each
segment.
Including
a
module in several
memory-resident segments that overlay one another causes physical
memory to be reserved for each extra copy of that module. Common
modules,
including those from the system object module library
(SYSLIB),
should be placed in a segment that can be accessed from all
referencing segments.
The primary criterion for choosing to have memory-resident overlays is
the need to save virtual address space when disk-resident overlays are
either undesirable
(because they would slow
down
the
system
unacceptably) ,
or
impossible
(because the segments are part of a
resident library or other shared region that must permanently reside
in memory).
Memory-resident overlays can help you use large systems to better
advantage because of the time savings realized when a large amount of
physical memory is available.
Resident libraries, in particular, can
benefit from the virtual address space saved when they are divided
into memory-resident segments.

3.2

OVERLAY TREE

The arrangement of overlay segments within the virtual address space
of a task can be represented schematically as a tree-like structure.
Each branch of the tree represents a
segment.
Parallel branches
denote segments that overlay one another and therefore have the same
virtual address;
these segments must be logically independent.
Branches connected end to end represent segments that do not share
virtual address space with each other;
these segments need not be
logically independent.
TKB provides an Overlay Description Language (ODL)
overlay structure consisting of one or more
described in Section 3.4).

for representing an
trees
(the ODL is

The single overlay tree shown in Figure 3-8 represents the
of virtual address space for TKl (see Section 3.1.1).
The tree has a root (CNTRL) and three main branches (AO, BO,
It also has six leaves (Al, A21, A22, Bl, B2, and C).
The tree has as many paths as it has leaves.
from the leaf to the root.
For example:

allocation
and

C).

The path down is defined

A21-A2-AO-CNTRL
The path up is defined from the root to the leaf.

For example:

CNTRL-BO-Bl
Knowing the properties of the tree and
its paths is
important to
understanding the overlay loading mechanism and the resolution of
global symbols.

3-15

OVERLAY CAPABILITY

t_~2

CNTRL
ZK-402-81

Figure 3-8

3.2.1

Overlay Tree for TKl

Loading Mechanism

Modules can call other modules that exist on the same path.
The
module CNTRL
(Figure 3-8)
is common to every path of the tree and,
therefore, can call and be called by every module in the tree.
The
module A2 can call the modules A21, A22, AO, and CNTRL; but A2 cannot
call Al, Bl, B2, BO, or C.
When a module in one overlay segment calls a module in another overlay
segment,
the called segment must be in memory and mapped, or must be
brought into memory.
The methods for loading overlays are described
in Chapter 4.

3.2.2

Resolution of Global Symbols in a Multisegment Task

In resolving global symbols for a multisegment task, TKB performs the
same activities that it does for a single-segment task.
The rules
defined in Chapter 2 for resolving global symbols in a single-segment
task apply also in this case, but the scope of the global symbols is
altered by the overlay structure.
In a single-segment task, any module can refer to any global
definition.
In a multisegment task, however, a module can only refer
to a global symbol that is defined on a path that passes through the
called segment.
The following points, illustrated in the tree diagram in Figure 3-9,
describe the two distinct cases of multiply defined symbols and
ambiguously defined symbols.
In a single-segment task, if you define two global symbols with the
same name,
the symbols are multiply defined and an error message is
produced.
In a multisegrnent task, you can define two global symbols with the
same name if they are on separate paths, and not referenced from a
segment that is common to both.
If you define a global symbol more than once on separate paths, but
they are referenced from a segment that is common to both, the symbol
is ambiguously defined.
If you define a global symbol more than once
on a single path, it is multiply defined.

3-16

OVERLAY CAPABILITY
TKB's procedure for resolving global symbols is summarized as follows:
1.

TKB selects an overlay segment for processing.

TKB scans each module in the segment for
and references.

If the symbol is a definition, TKB searches all segments on
paths that pass through the segment being processed, and
looks for references that must be resolved.

If the symbol is a reference, TKB performs the tree search as
described in step 3, looking for an existing definition.

If the symbol is new, TKB enters it
symbols associated with the segment.

global

definitions

list

global

Overlay segments are selected for processing in an order corresponding
to their distance from the root.
That is, TKB processes the segment
farthest from the root first, before processing an adjoining segment.
When TKB processes a segment, its search for global
as follows:
1.

The segment being processed

All segments toward the root

All segments away from the root

All co-trees

symbols

proceeds

(see Section 3.5)
the

Figure 3-9 illustrates
multi segment task.

resolution

A21

A22

T (DEF)
S (REF)

R (REF)
0 (REF)

global

symbols

~EF)
A1

0 (REF)

R (REF)
S (REF)

R (DEF)

S(Ry
81

0 (REF)

S (REF)

Q (DEF)

0 (DEF)
S (DEF)

S (DEF)
T (DEF)

CNTRL
S (REF)
ZK-403-81

Figure 3-9

Resolution of Global Symbols in a Multisegment Task

3-17

OVERLAY CAPABILITY
The following notes discuss the resolution
3-9:

references

Figure

The global symbol Q is defined in both segment AO and segment
BO.
The references to Q in segment A22 and in segment Al are
resolved by the definition in AO.
The reference to Q in Bl
is resolved by the definition in BO.
The two definitions of
Q are distinct in all respects and occupy different overlay
paths.

The global symbol R is defined in segment A2.
The reference
to R in A22 is resolved by the definition in A2 because there
is a
path
to
the
reference
from
the
definition
(CNTRL-AO-A2-A22).
The reference to R in Al, however, is
undefined because there is no definition for
R on a path
through Al.

The global symbol S is defined in both segment AO and segment
BO.
References to S from segments Al,
A21, or A22 are
resolved by the definition in AO, and references to S in Bl
and B2 are resolved by the definition in BO.
However, the
reference to S in CNTRL cannot be resolved because there are
two definitions of S on separate paths through CNTRL.
The
global symbol S is ambiguously defined.

The global symbol T is defined
in both segment A21 and
segment AO.
Since there is a single path through the two
definitions
(CNTRL-AO-A2-A21),
the global symbol
T
is
multiply defined.

3.2.3

Resolution of Global Symbols from the Default Library

The process of resolving global symbols may require two passes over
the tree structure.
The global symbols discussed in the previous
section are included in user-specified input modules that TKB scans in
the first pass.
If any undefined symbols remain, TKB initiates a
second pass over the structure in an attempt to resolve such symbols
by
searching
the
default
object
module
library
(normally
LBO:[l,l]SYSLIB.OLB).
TKB reports any undefined symbols remaining
after its second pass.
When multiple tree structures (co-trees) are defined, as described in
Section 3.5, any resolution of global symbols across tree structures
during a second pass can result in multiple or ambiguous definitions.
In addition,
such references can cause overlay segments to be
inadvertently displaced from memory by the overlay loading routines,
thereby causing run-time failures.
To eliminate these conditions, the
tree search on the second pass is restricted to:
•

The segment in which the undefined reference has occurred

•

All segments in the current tree that are on
the segment

•

The root segment

path

through

When the current segment is the main root, the tree search is extended
to all segments.
You can unconditionally extend the tree search to
all segments by including the /FU (full) switch in the task image file
specification.
(Refer to Chapter 10 for a description of the /FU
switch.)

3-18

OVERLAY CAPABILITY
3.2.4

Allocation of Program Sections in a Multisegment Task

One of a program section's attributes indicates whether the program
section is local
(LCL)
to the segment in which it is defined or is
global (GBL) •
Local program sections with the same name can appear in any number of
segments.
TKB allocates virtual address space for each local program
section in the segment in which it is declared.
Global program
sections that have the same name, however, must be resolved by TKB.
When a global program section is defined in several overlay segments
along a common path, TKB allocates all virtual address space for the
program section in the overlay segment closest to the root.
FORTRAN common blocks are translated into global program sections with
the overlay (OVR) attribute.
In Figure 3-10, the common block COMA is
defined in modules A2 and A21.
TKB allocates the virtual address
space for COMA in A2 because that segment is closer to the root than
the segment that contains A21.
If the segments AO and BO use the common block COMAB, however, TKB
allocates the virtual address space for COMAB in both the segment that
contains AO and the segment that contains BO.
AO and BO cannot
communicate through COMAB. When the overlay segment containing BO is
loaded, any data stored in COMAB by AO is lost.
You can specify the allocation of program sections explicitly.
If AO
and BO need to share the contents of COMAB, you can force the
allocation of this program section into the root segment by the use of
the
.PSECT directive of the Task Builder's overlay description
language, described in Section 3.4.

A21

A22

COM AB

CNTRL
ZK-404-81

Figure 3-10

3.3

Resolution of Program Sections for TKl

OVERLAY DATA STRUCTURES AND RUN-TIME ROUTINES

it builds additional data
When TKB constructs an overlaid task,
structures and adds them to the task image. The data structures
contain information about the overlay segments and describe the

3-19

OVERLAY CAPABILITY
relationship of each segment in the tree to the other segments in the
tree.
TKB also
includes into the task
image a number of system
library routines (called overlay run-time routines).
The overlay
run-time routines use the data structures to facilitate the loading of
the segments and to provide the necessary linkages from one segment to
another at run time.
TKB links the majority of data structures and all of the overlay
run-time routines into the root segment of the task.
The number and
type of data structures, and the functions the routines perform,
depend on two considerations:
•

Whether the task is built to use the Task
or manual load facilities

Builder's

autoload

•

Whether the
resident

resident

overlay

segment

memory

disk

These considerations have a marked impact on the size and operation of
the task.
Chapter 4 describes the Task Builder's autoload and manual
load facilities and describes the methods for
loading overlays.
Appendix B describes the data structures and their contents in detail.
The contents of the root segment for a task with an overlay
are discussed briefly in the following sections.

3.3.1

structure

Overlaid Conventional Task Structures

Depending on the considerations just discussed, some or all of the
following data structures are required by the overlay run-time
routines:
•

Segment tables

•

Autoload vectors

•

Window descriptors

•

Region descriptors

Figure 3-11 shows a typical overlay root segment structure.
There is a segment descriptor for every segment in the task.
The
descriptor contains information about the load address, the length of
the segment, and the tree linkage.
In an autoloadable, overlaid task, autoload vectors appear in the root
segment and in every segment that calls modules in another segment
located farther away from the root of the tree.
All references to
resident libraries are resolved through autoload vectors in the root.
Window descriptors are allocated whenever a memory-resident overlay
structure
is
defined
for
the task.
The descriptor contains
information required by the Create Address Window system directive
(CRAW$). One descriptor is allocated for each memory-resident overlay
segment~

Region descriptors are allocated whenever a task is linked to a shared
region containing memory-resident overlays.
The descriptor contains
information required by the Attach Region system directive (ATRG$).

3-20

OVERLAY CAPABILITY

TASK CODE & DATA
WINDOW DESCRIPTORS
REGION DESCRIPTORS
SEGMENT DESCRIPTORS
OVERLAY
RUN-TIME
ROUTINES
AUTO LOAD VECTORS

TYPICAL
MAIN TREE
ROOT SEGMENT

TASK CODE
AND
DATA

HEADER AND STACK
ZK-405-81

Figure 3-11

Typical Overlay Root Segment Structure

•i · Regiort ·descriptors
•" A:l;itoload \rectO'rs ( th.e data part)

AuE.oioad vectors contain data

and instruct.ions. . Therefore 1 TKB
locates tpe ln$truction part of the autoload vector in I-space and the
.•. data. part in D-·space. Each segment: of an auto loadable overlaid I- and
D.-space tas~ .may have an instruction part and a data part~ Therefore;
each·r~ and D-$pace segment in such a
task would have its vectors
:separated into an instruction part and a data part.

3-21

OVERLAY CAPABILITY
,';I'be st~u'Ctur'e,s :10,catea· in instrucfio.11 space are:
.Auto.load,·, vect,()rs' (instruct.ion p(lrt)

:::·segmeh1:" r~turn point
segment only)

VIRTUAL I-SPACE

VIRTUAL D-SPACE
3.6K

I-SPACE PART OF
AUTOLOAD VECTORS

D-SPACE PART OF
AUTOLOAD VECTORS

UP-TREE
SEGMENT
DATA

CODE

1.SK

WINDOW DESCRIPTORS

OVERLAY RUN-TIME
ROUTINES

2740
REGION DESCRIPTORS

AUTOLOAD VECTORSI-SPACE PART

2720
SEGMENT DESCRIPTORS

2640
AUTOLOAD VECTORS
D-SPACE PART

2630
MAIN
TREE
ROOT
SEGMENT

TASK
DATA

TASK
CODE

1270
STACK SPACE

300

300
UNUSED HEADER COPY

TASK HEADER
USABLE COPY

)
ZK-1050-82

Figure 3-12

Typical Over,laid I- and ;D .... Space Task with Up-Tree Segment

3-22

OVERLAY CAPABILITY
3.4

OVERLAY DESCRIPTION LANGUAGE

TKB provides a language, called the Overlay Description Language
(ODL),
that allows you to describe the overlay structure of a task.
An overlay description is a text file consisting of a series of ODL
directives, one directive per line.
Each line may have as many as 132
characters. You enter the name of this file in a TKB command line,
and
identify it as an ODL file by specifying the /MP switch (see
Chapter 10) to the file name. For example, the following TKB command
line specifies an ODL file:
>TKB TASKl=OVRLAY/MP
If you specify an ODL file to TKB, it must be the only input file
specify.

you

A command line in an ODL file takes the form
label:

directive

argument-list

;comment

A label is required only for the .FCTR directive (see Section
Labels cannot be used with the other directives.
The ODL directives are listed below and described
through 3.4.6:

.ROOT and .END

.FCTR

.NAME

.PSECT

•

@ (at sign;

3.4.2).

Sections

3.4.1

indirect command file specifier)

The ODL directives can act upon the following
items:
named input
files,
overlay segments, program sections, and lines in the ODL file
itself.
These items follow each directive on the same line as the
directive, and form an argument-list. Operators, such as the hyphen,
exclamation point, and comma, group the argument-list items
(named
task elements) or attach attributes to them.
If the named task element is a file, you can enter a complete file
specification.
Defaults for omitted parts of the file specification
are as described in Chapters 1 and 10, except that the default device
is SYO:, and the default UFD is taken from the terminal UIC.
In addition, the following restrictions apply to argument-lists:

3.4.1

•

You can only use the dot character (.)

in a file name.

•

Comments cannot appear on a line ending with a file name.

.ROOT and .END Directives

The .ROOT directive defines the structure of the overlaid task.
Because
of
this,
.ROOT usually appears first
in the overlay
description. The .NAME directive may precede the .ROOT directive in
certain circumstances discussed
in Section 3.4.4.
Each overlay
description must end with one .END directive.
The
.ROOT directive
tells TKB where to start building the tree, and the .END directive
tells TKB where the input ends.

3-23

OVERLAY CAPABILITY

The arguments of the .ROOT directive use three operators to express
concatenation, memory residency, and overlaying.
These operators can
be used also in the .FCTR directive.
•

The hyphen (-) operator indicates the concatenation of virtual
address space.
For example, X-Y means that sufficient virtual
address space will be allocated to contain module X and module
Y simultaneously.
TKB allocates segment X and segment Y in
sequence to produce one segment.

•

The exclamation point (!) operator indicates memory residency
of overlays.
(This operator is discussed in Section 3.4.3.)

•

The comma
(,)
operator,
appearing
within
parentheses,
indicates the overlaying of virtual address space.
For
example, (Y,Z) means that virtual address space can contain
either segment Y or segment z.
If no exclamation point (!)
precedes the left parenthesis, segment Y and segment z also
share physical memory.
The comma (,) operator is also used to define
structures (as described in Section 3.5.1).

multiple

tree

You use parentheses to delimit a group of segments that start at the
same virtual address.
The number of nested parenthetical groups
cannot exceed 16.
For example:
.ROOT X-(Y,Z-(Zl,Z2))
.END
These directives describe the tree
address space shown in Figure 3-13:

and

its

corresponding

virtual

z
x
ZK-406-81

Figure 3-13

Tree and Virtual Address Space Diagram

To create the overlay description for
the task TKl
in Figure 3-3
(Section 3.1.1), you could create a file called TFIL.ODL that contains
the directives:
.ROOT CNTRL-(A0-(Al,A2-(A21,A22)) ,BO-(Bl,B2) ,C)
.END
To build the task with that overlay structure, you would type:
>TKB TKl=TFIL/MP
The /MP switch in the command strinq above tells TKB that there is
only one input file
(TFIL.ODL) ,- and
that this file contains the
overlay description for the task.

3-24

OVERLAY CAPABILITY
3.4.2

.FCTR Directive

The .FCTR directive allows you
represent them clearly.

build

large,

complex

trees

and

The .FCTR directive has a label at the beginning of the ODL line that
is pointed to by a reference in a .ROOT or another .FCTR statement.
The label must be unique with respect to module names and other
labels. The .FCTR directive allows you to extend the tree description
beyond a single line, enabling you to provide a clearer description of
the overlay.
(There can be only one .ROOT directive.)
For example, to simplify the tree given in the file TFIL (described in
Section 3.4.1), you could use the .FCTR directive in the overlay
description as· follows:
AFCTR:
BFCTR:

.ROOT CNTRL-(AFCTR,BFCTR,C)
.FCTR AO-(Al,A2-(A21,A22))
.FCTR BO-(Bl,B2)
.END

The label BFCTR is used in the .ROOT directive to designate the
argument BO-(Bl,B2)
of the .FCTR directive.
The resulting overlay
description is easier to interpret than the original description. The
tree consists of a root, CNTRL, and three main branches. Two of the
main branches have sub-branches.
The .FCTR directive can be nested to a level of 16.
could further modify TFIL as follows:
AFCTR:
A2FCTR:
BFCTR:

3.4.3

For example,

you

.ROOT CNTRL-(AFCTR,BFCTR,C)
.FCTR AO-(Al,A2FCTR)
.FCTR A2-(A21,A22)
.FCTR BO-(Bl,B2)
.END

Arguments for the .FCTR and .ROOT Directives

The arguments for the .FCTR and .ROOT directives may have different
forms or syntax. The examples in this chapter use forms such as Al,
Bl, x, and Y for clarity, but the actual arguments that you use may
have somewhat different names. This section lists the forms that the
arguments may take for these directives.
If you use an argument that
does not fall into one of the following five categories, TKB takes the
argument as that of the name of an object module file;
in other
words, the file name that you use must have an extension of .OBJ.

3.4.3.1 Named Input File - You may use a named input
the object file format. For example,
CALC:

.FCTR [7,54]MULT.OBJ

The default is .OBJ.

3-25

file

that

has

OVERLAY CAPABILITY
3.4.3.2 Specific Library Modules - You may name and therefore
specific object modules from a library file.
For example,
BAKER:

use

.FCTR [300,3]COOKIE/LB:CHIP:OAT

where COOKIE.OLB is the library file and CHIP and OAT are the modules
that you want to extract from the file.
The default extension is .OLB
and it need not be specified as part of the argument.

3.4.3.3 A Library to Resolve References Not Previously Resolved - You
may specify a library as an argument in a .FCTR statement after
extracting specific modules in a previous .FCTR statement.
TKB uses
the library to resolve symbols that may still be unresolved after
extracting the modules.
For example,
BAKER:
LIB:

.FCTR [300,3]COOKIE/LB:CHIP:OAT
.FCTR LB:[l,4]RECIPE/LB

3.4.3.4 A Section Name Used in a .PSECT Directive - You may use the
name that you used as a program section name in the .PSECT directive
as the argument in a .FCTR statement. For example,
FSTCOM:

.PSECT
.FCTR

COM,GBL,D,RW,OVR
COM

3.4.3.5 A Segment Name used in a .NAME Directive - You may use the
name that you specified as the name of a
segment in the .NAME
directive. For example,
OVLY:

3.4.4

.NAME
.FCTR

SEGl,GBL,DSK
SEG1-MOD1-MOD2

Exclamation Point Operator

The exclamation point operator allows you to specify memory-resident
overlay segments (see Section 3.1.2).
You specify memory residency by
placing an exclamation point
(!)
immediately before
the
left
parenthesis enclosing the segments to be affected.
The overlay
description for task TK2 in Figure 3-4 (Section 3.1.2) is as follows:
.ROOT CNTRL-! (D,E,F)
.END
In the example above, segments D,
E, F are declared resident in
separate areas of physical memory.
The Task Builder determines the
single starting virtual address for D, E, and F by rounding the octal
length of segment CNTRL up to the next 4K boundary.
The physical
memory allocated to segments D, E, and F is determined by rounding the
actual length of each segment to the next 32-word boundary (256-word
boundary if the /CM switch is in effect)
and adding this value to the
total memory required by the task.

3-26

OVERLAY CAPABILITY
The exclamation point operator applies to that segment immediately to
the right of the left parenthesis and those segments farther from the
root on the same level with that segment.
In other words, all
parallel segments must be of the same residency type (disk resident or
memory resident) •
The exclamation point operator applies to segments at the same level
from the root inside a pair of parentheses;
segments nested in
parenthesis within that level, but farther from the root, are not
affected.
It is therefore possible to define an overlay structure that combines
the space-saving attributes of disk-resident overlays with the speed
of memory-resident overlays. For example:
.ROOT A-! (Bl-(B2,B3) ,C)
.END
In this example, Bl and C are declared memory resident by the
exclamation point operator.
B2 and B3 are declared disk resident,
however, because no exclamation
point
operator
precedes
the
parentheses enclosing them.
Note that while a memory-resident overlay can call a disk-resident
overlay, the converse is not legal;
that is, you cannot use an
exclamation point for segments emanating from a disk-resident segment.
For example, you cannot build the following structure:
.ROOT A-(Bl-! (B2,B3) ,C)
.END

; this overlay description is illegal

In this example, Bl is declared disk resident; so it is illegal
use the exclamation point to declare B2 and B3 memory resident.

.NAME Directive

3.4.5

The .NAME directive allows you to name a segment, and assign
attributes to the segment. The name must be unique with respect to
file names, program section names, .FCTR labels, and other segment
names used in the overlay description. You use the .NAME directive
prior to using the .ROOT or
.FCTR directive.
The Task Builder
attaches attributes to a segment when it encounters the name in a
.ROOT or .FCTR directive that defines the overlay segment.
If you
apply multiple names to a segment, the attributes of the last name
given are in effect. This directive does the following:
•

Names uniquely a segment that is
load facility (see Chapter 4)

loaded

•

Permits a named data-only segment to
autoload mechanism

through

the

manual

loaded

through

the

The format of the .NAME directive is:
.NAME segname[,attr] [,attr]
segname
A 1- to 6-character name;
this name can consist of the Radix-50
characters A-Z, 0-9, and$ (the period (.) cannot be used).

3-27

OVERLAY CAPABILITY
attr
One of the following:
GBL

The name is entered in the segment's
table.

global

symbol

The GBL attribute makes it possible
to
load
data-only overlay segments by means of the autoload
mechanism (see Chapter 4).
No disk space is allocated to the named segment.

NODSK

If a data overlay segment has no initial values, but
will have its contents established by the running
task, no space for the named segment on disk need be
reserved.
If the code attempts to establish initial
values for data in a segment for which no disk space
is allocated
(a segment with the NODSK attribute),
TKB gives a fatal error.
NOGBL

The name is not
symbol table.
If the GBL
assumed.

DSK

entered

attribute

in
is

the
not

segment's
present,

global

NOGBL

Disk storage is allocated to the named segment.
If the NODSK
assumed.

attribute

not

present,

DSK

3.4.5.1 Example of The Ose of The .NAME Directive - In the following
modified ODL file for TKl (Figure 3-3 of Section 3.1.1), you provide
names for the three main branches, AO, BO, and C, by specifying the
names in the .NAME directive and using them in the .ROOT directive.
The default attributes NOGBL and DSK are in effect for BRNCHl and
BRNCH3, but BRNCH2 has the complementary attributes (GBL and NODSK)
that cause TKB to enter the name BRNCH2 into the segment's global
symbol table and suppress disk allocation for that segment. BRNCH2
contains uninitialized storage to be utilized at run time •

AFCTR:
BFCTR:

• NAME BRNCHl
.NAME BRNCH2,GBL,NODSK
.NAME BRNCH3
.ROOT CNTRL-!(BRNCH1-AFCTR,*BRNCH2-BFCTR,BRNCH3-C)
.FCTR A0-(Al,A2-(A21,A22))
.FCTR BO-*!(Bl,B2)
.END

(The asterisk (*)
Chapter 4.)

is the

autoload

indicator;

You can load the data overlay segment
following statement in the program:

discussed

BRNCH2

including

the

CALL BRNCH2
This action is immediately followed by an automatic return to the next
instruction in the program.

3-28

OVERLAY CAPABILITY
You can also use segment names in making patches with the
GBLPAT options (see Chapter 11).

ABSPAT

and

NOTE
In the absence of a
unique
.NAME
specification, TKB establishes a segment
name, using the first module name or
library module name occurring in the
segment.

3.4.6

.PSECT Directive

You can use the .PSECT directive to control the placement of a global
program section in an overlay structuree The name of the program
section
(a 1- to 6-character name consisting of the
Radix-50
characters A-Z, 0-9, and $) and its attributes are given in the .PSECT
directive. The attributes used in the .PSECT directive must match
those in the actual program section in the module.
Thus, you can use
the name in a .ROOT or .FCTR statement to indicate to the Task Builder
the segment to which the program section will be allocated. An
example of the use of .PSECT is given in the modified version of task
TKl
(the original version is shown in Figure 3-3 in Section 3.1.1)
shown below.
In this example, TKl has a disk-resident overlay structure.
The
example assumes that the programmer was careful about the logical
independence of the modules in the overlay segment, but failed to take
into account the requirement for logical independence in multiple
executions of the same overlay segment.
The flow of task TKl can be summarized as follows.
CNTRL calls each
of the overlay segments, and the overlay segment returns to CNTRL in
the order A, B, C, A.
Module A is executed twice.
The overlay
segment containing A must be reloaded for the second execution.
Module A uses a common block named DATA3. The Task Builder allocates
DATA3 to the overlay segment containing A. The first execution of A
stores some results in DATA3. The second execution of A requires
these values.
In this disk-resident overlay structure, however, the
values calculated by the first execution of A are overlaid. When the
segment containing A is read in for the second execution, the common
block is in its initial state.
To permit the two executions of A to communicate, a
.PSECT directive
is used to force the allocation of DATA3 into the root. The indirect
command file for TKl, TFIL.ODL, is modified as follows:

AFCTR:
BFCTR:

.PSECT DATA3,RW,GBL,REL,OVR
.ROOT CNTRL-DATA3-(AFCTR,BFCTR,C)
.FCTR AO-(Al,A2-(A21,A22))
.FCTR BO-(Bl,B2)
.END

The attributes RW, GBL, REL, and OVR are described in Chapter 2.

3-29

OVERLAY CAPABILITY

Indirect Command Files

3.4.7

The Overlay Description Language processor can accept ODL text
indirectly,
that is, specified in an indirect command file.
If an at
sign {@) appears as the first character in an ODL line, the processor
reads text from the file specified immediately after the at sign.
The
processor accepts the ODL text from the file as input at the point in
the overlay description where the file is specified.
For example, suppose you create a file, called BIND.ODL, that contains
the text:
B:

.FCTR Bl-{B2,B3)

A line beginning with @BIND can replace
where the text would have appeared:

this

Indirect
C:
@BIND

text

the

position

Direct

.ROOT A-(B,C)
.FCTR Cl-{C2,C3)

C:
B:

.END

.ROOT A-{B,C)
.FCTR Cl-{C2,C3)
.FCTR Bl-{B2,B3)
.END

The Task Builder allows two levels of indirection.

3.5

MULTIPLE-TREE STRUCTURES

You can define more than one tree within an overlay structure.
These
multiple tree structures consist of a main tree and one or more
co-trees. The root segment of the main tree is loaded by the
Executive when the task is made active, while segments within each
co-tree are loaded through calls to the overlay run-time routines.
Except
for
this' distinction, all overlay trees have identical
characteristics: a root segment that resides in memory, and two or
more overlay segments.
The main property of a structure containing more than one tree is that
storage is not shared among trees.
Any segment in a tree can be
referred to from another tree without displacing segments from the
calling tree.
Routines that are called from several main tree overlay
segments, for example, can overlay one another in a co-tree. The same
considerations in deciding whether to create memory-resident overlays
or disk-resident overlays in a single-tree structure apply in building
a structure containing co-trees.

Defining a Multiple-Tree Structure

3.5.l

Multiple-tree structures are specified within the Overlay Description
Language by extending the function of the comma operator.
As
described
in Section 3.4,
this operator, when included
within
parentheses, defines a pair of segments that share storage.
Including
the comma operator outside all parentheses delimits overlay trees.
The first overlay tree thus defined is the main tree.
Subsequent
trees are co-trees. For example:
X:
Y:

.ROOT
.FCTR
.FCTR
.END

X,Y
XO-(Xl,X2,X3)
YO-{Yl,Y2)

3-30

OVERLAY CAPABILITY
In this example, two overlay trees are specified:
1)
a main tree
containing the root segment XO and three overlay segments;
and 2) a
co-tree consisting of root segment YO and two overlay segments.
The
Executive loads segment XO
into memory when the task is activated.
The task then loads the remaining segments through calls to the
overlay run-time routines.

3.5.1.1 Defining Co-trees With a Null Root by Using .NAME - A co-tree
must have a root segment to establish linkage with its own overlay
segments. However, co-tree root segments need not contain code or
data and,
therefore, can be 0 length.
You can create a segment of
this type, called a null segment 1 by means of the
.NAME directive.
The previous example is modified, as shown below, to move file YO.OBJ
to the root and include a null segment •

x:
Y:

• ROOT
.FCTR
.NAME
.FCTR
.END

X,Y
XO-YO-(Xl,X2,X3)
YNUL
YNUL-(Yl,Y2)

The .null segment YNUL is created by using the
.NAME directive,
replaces the co-tree root that formerly contained YO.OBJ.

3.5.2

and

Multiple-Tree Example

The following example illustrates the use of multiple trees to
the size of the task.

reduce

In this example, the root segment CNTRL of task TKl
(described
in
Section 3.1.1)
has had two routines added to it:
CNTRLX and CNTRLY.
The routines are logically independent of each other,
and both are
approximately 4000(octal) bytes long.
However, the routines have been
placed in the root segment of TKl instead of being overlaid because
both routines must be accessed from modules on all paths of the tree.
In a single-tree overlay structure,
the root segment is the only
segment common to all paths of the tree.
The schematic diagram for
the modified structure is shown in Figure 3-14.

A22

A21

I
A1

I
CNTRLY

CNTRLX
I
CNTRL

ROOT
SEGMENT

ZK-407-81

Figure 3-14

Overlay Tree for Modified TKl

3-31

OVERLAY CAPABILITY
One possible overlay description for this structure is shown below:
.ROOT CNTRL-CNTRLX-CNTRLY-(AFCTR,BFCTR,C)
AFCTR:
.FCTR A0-(Al,A2FCTR)
A2FCTR: .FCTR A2-(A21,A22)
BFCTR:
.FCTR BO-(Bl,B2)
.END
Because TKl consists of disk-resident overlays and the new routines
are concatenated within the overlay structure, the new routines add
lOOOO(octal) bytes to both the virtual address space and physical
memory requirements of the task.
However, the added routines consume
more virtual address space than might be expected, as shown in Figure
3-15.
The expansion of TKl's virtual address space requirements caused the
task to extend 4000(octal)
bytes beyond the next highest 4K-word
boundary {APR 2).
Because the Executive must use an additional
mapping register
(APR2) , the apparent cost in virtual address space
above APR 2 of 4000(octal)
bytes is in fact 20000(octal)
bytes.
(Compare the diagram in Figure 3-15 with the diagram in Figure 3-3.)
The shaded portion of the unused virtual address space in Figure 3-15
represents the portion of virtual address space that is allocated but
is unusable as allocated.
Small tasks, such as TKl, are seldom adversely affected by the
inefficient allocation of virtual address space, but larger tasks may
be. For example, a large task that contains code to create dynamic
regions
{see Chapter 5)
or that contains Executive directives to
extend its task region {see the RSX-llM/M-PLUS Executive Reference
Manual)
requires at least 4K words of virtual address space to map
each region.
In such a task, using co-trees can often save virtual
address space and can, therefore, be of paramount importance. TKl can
be modified to reflect this.
As noted earlier, the routines CNTRLX and CNTRLY are logically
independent.
Logical independence is a primary requirement for all
segments that overlay each other. However, CNTRLX and CNTRLY cannot
be structured into either of the main branches of TKl's tree because
it is further required that the routines be accessible from modules on
all paths of the tree.
Therefore, the only way CNTRLX and CNTRLY can
be overlaid and still meet all of these requirements is through a
co-tree structure. Figure 3-16 shows the schematic representation of
TKl as a co-tree structure.
The root segment CNTRL2 of the co-tree is a null segment.
It contains
no code or data and has a length of O. As noted earlier, the Task
Builder requires the root segment in order to establish linkage with
the overlay segments. One possible overlay description for building
TKl as a 2-tree structure is shown below •
• NAME CNTRL2
.ROOT CNTRL-(AFCTR,BFCTR,C) ,CNTRL2-(CNTRLX,CNTRLY)
AFCTR:
.FCTR AO-(Al,A2FCTR)
A2FCTR: .FCTR A2-(A2l,A22)
BFCTR:
.FCTR BO-(Bl,B2)
.END
You define the co-tree in the .ROOT directive by placing the comma
operator outside all parentheses
(immediately before CNTRL2). The
.NAME directive creates the null root segment. Figure 3-16 shows the
new relationship between virtual address space and physical memory.

3-32

OVERLAY CAPABILITY

APR7-

APR6-

APR5-

APR4-

APR3-

APR2-

A21 A22

l A1

r AO I

B11-B2

CNTRLY

f.-

APR1-

- - - CNTRLX
- - -

t- -

ROOT
SEGMENT

APRO-

t- t- -

llA211A22j
l B1 ~
A2
B2
c
AO
BO
l
CNTRLY

- - - - - - CNTRLX
- - - - - - -

CNTRL

HEADER AND STACK

VIRTUAL ADDRESS
SPACE

PHYSICAL MEMORY
ZK-408-81

Figure 3-15

Virtual Address Space and Physical Memory
for Modified TKl

3-33

OVERLAY CAPABILITY

A21

A22

CNTRL
MAIN TREE

CO-TREE
ZK-409-81

Figure 3-16

Overlay Co-Tree for Modified TKl

The diagrams in Figure 3-17 illustrate the savings (4000(octal) bytes)
in both virtual address space and physical memory that is realized by
overlaying CNTRLX and CNTRLY. What may be more important in some
applications, however,
is that the top of TKl's task region has
dropped below the 4K-word boundary of APR 2. TKl has gained 4K words
of potentially usable virtual address space.
NOTE
The numbers used in this example have
been
simplified
for
illustrative
purposes.
In addition,
the
storage
required for overhead in handling the
overlay structures is not reflected
in
this example.
Because the null root CNTRL2 is O bytes long, it does not require any
virtual address space or physical memory and, therefore, does not
appear in the diagrams in Figure 3-17.
Finally, you can define any number of co-trees.
Additional
can access all modules in the main tree and other co-trees.

3-34

co-trees

OVERLAY CAPABILITY

APR 7-

APR 6-

APR 5-

APR 4-

APR 3-

APR 2CNTRLX

CNTRLY

__ NULL ROOT

i--~T-A-2-1J~A-2_2......._~~~~~---•-i-LENGTH=O

A11

A2
AO

B1§

CNTRLX

TA21TA22
A1r

A2
AO

CNTRLY

81~ c
B2

CNTRL
(ROOT SEGMENT)

HEADER AND STACK

VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY
ZK-410-81

Figure 3-17 Virtual Address Space
and Physical Memory for TKl As a Co-Tree

3.6

CREATING AN ODL FILE FROM
DIAGRAM

VIRTUAL

ADDRESS

SPACE

ALLOCATION

You can use a graphic method as an aid to converting a virtual address
space allocation diagram into the correct Task Builder ODL file.

3-35

OVERLAY CAPABILITY
First create a virtual address space allocation diagram of your
overlaid task, similar to that shown in Figure 3-18, without the
dotted-line path shown in the diagram.

.
..

A21
A1

A22

: _!" .................... ·..:..

~ ~

:.i-:.

..l
AO

--r..:
:.i-:

!
BO

=·····~···:
_!_

•

j_••••••••• ~···:

!
ROOT (CNTRL)

•
ZK-1052-82

Figure 3-18

Virtual Address Space Allocation Diagram

The dotted-line path will be the basis for writing the ODL statements
that you need.
To determine the path through your virtual address
space allocation diagram, follow these steps:
1.

Start in the lower left corner of the root segment.

Draw a dotted line upward as far as you can go without
passing through the top or into "empty" virtual space,
crossing into new segments as needed.

When you reach the top segment, proceed to
you reach a vertical line.

If the end of your dotted line is now opposite the vertical
line of the lowest segment, cross the vertical line and
continue again from step 2;
otherwise, proceed to step 5.

Because the end of your dotted line is not opposite the
vertical line of the lowest segment proceed downward until
you reach the lowest segment.

If you are not in the root, cross the vertical line to the
right and continue from step 2; otherwise, proceed to step

the

right

until

7.
7.

If your dotted line is in the lower right corner of the root,
you have finished the dotted-line walk.

3-36

OVERLAY CAPABILITY
Once you have drawn the dotted line, you should go back over it to
verify that you followed all the steps, While doing this, draw
arrowheads at each point where a line was crossed to indicate the
direction of the line.

Creating a .ROOT Statement by Using
Allocation Diagram

3.6.1

Virtual

Now you are ready to write the .ROOT statement.
1.

Address

Space

Follow these steps:

Write .ROOT followed by the name of the
this example 1 9ROOT CNTRL)

root

statement

(in

Follow the dotted-line path.

Add each successive ODL element to your root statement, using
the following syntax, based on the direction of your dotted
line.

At an upward crossing:

-("name of new segment"

At a horizontal crossing:

At a downward crossing:

,"name of new segment"

When you have returned to the root, your
complete.

root

statement

Using the dotted-line path in Figure 3-18 and the above associated
steps for writing the .ROOT statement, you can write as shown below:
1.

Step 1 :

Write .ROOT CNTRL

Step 3A:

Write .ROOT CNTRL-(AO

Step 3A:

Write .ROOT CNTRL-(AO-(Al

Step 3B:

Write .ROOT CNTRL-(AO-(Al,A2

Step 3A:

Write .ROOT CNTRL-(AO-(Al,A2-(A21

Step 3B:

Write .ROOT CNTRL-(AO-(Al,A2-(A21,A22

Step 3C:

Write .ROOT CNTRL-(A0-(Al,A2-(A21,A22)

Step 3C:

Write .ROOT CNTRL-(A0-(Al,A2-(A21,A22))

Step 3B:

Write .ROOT CNTRL-(AO-(Al,A2-(A21,A22)) ,BO

10.

Step 3A:

Write .ROOT CNTRL-(AO-(Al,A2-(A21,A22))-BO-(Bl

11.

Step 3B:

Write .ROOT CNTRL-(A0-(Al,A2-(A21,A22))-BO-(Bl,B2

12.

Step 3C:

Write .ROOT CNTRL-(A0-(Al,A2-(A21,A22))-BO-(Bl,B2)

13.

Step 3B:

Write .ROOT CNTRL-(A0-(Al,A2-(A21,A22))-BO-(Bl,B2) ,C

14.

Step 3C:

Write .ROOT CNTRL-(AO-(Al,A2-(A21,A22))-BO-(Bl,B2) ,C)

The steps for writing .FCTR statements and co-tree
next.

3-37

statements

OVERLAY CAPABILITY
3.6.2

Creating a .FCTR Statement by Using
Allocation Diagram

By using the steps for creating a
.ROOT
address space allocation diagram, you
statement •

Virtual

Address

Space

statement from a virtual
created the following .ROOT

• ROOT CNTRL-(AO-(Al,A2-(A21,A22))-BO-(Bl,B2) ,C)
It may be desirable to simplify your specific .ROOT statement into one
or more .FCTR statements.
A technique similar to the one used to
create the .ROOT statement may be used to create the .FCTR statement.
In this example, segments AO, Al, A2, A21, and A22 are selected to be
in the .FCTR statement.
Having selected these segments (normally
related as a "stack" of segments) you are now ready to write down the
.FCTR statement.
First, draw a virtual address space allocation diagram of the segments
that
you
have selected.
(You may use Figure 3-18 for this
explanation.) Then follow these next steps to draw a dotted-line path
through the diagram:
1.

Start in the lower left corner
segment (AO) in your diagram.

the

lowest

Draw a dotted line upward as far as you can go without
passing through the top or into empty virtual space, crossing
into new segments as needed.

When you reach the top segment, proceed to
you reach a vertical line.

If the end of your dotted line is now opposite the vertical
line of the lowest segment, cross the vertical line and
continue again from step 2; otherwise, proceed to step 5.

Because the end of your dotted line is not opposite the
vertical line of the lowest segment, proceed downward until
you reach the lowest segment.

If you are not in the base segment (AO), cross the vertical
line to the right and continue from step 2; otherwise,
proceed to step 7.

If your dotted line is in the lower right corner of the
segment, you have finished the dotted-line walk.

the

right

"base"

until

base

Once you have drawn the dotted line, you should go back over it to
verify that you followed all the steps.
While doing this, draw
arrowheads at each point where a line was crossed to indicate the
direction of the line.
Now you are ready to write the .FCTR
steps:

statement.

these

Write a label followed by .FCTR, which is in turn followed by
the name of the first segment (AO) (in this example, AFCTR
.FCTR AO)

Follow the dotted-line path.

3-38

OVERLAY CAPABILITY
3.

Add each successive ODL element to your root statement, using
the following syntax, based on the direction of your dotted
line.
A.

At an upward crossing:

At a horizontal crossing:

At a downward crossing:

When you have returned
statement is complete.

("name of new segment"
,"name of new segment"

the

base

segment,

your

Using the dotted line path and the above associated steps for
the .FCTR statement, you can write as shown below:
1.

Step 1 :

Write AFC TR .FCTR AO

Step 3A:

Write AFC TR .FCTR AO-(Al

Step 3B:

Write AFC TR .FCTR AO- (Al ,A2

Step 3A:

Write AFC TR .FCTR AO- (Al ,A2- (A21

Step 3B:

Write AFC TR .FCTR AO-(Al,A2-(A21,A22

Step 3C:

Write AFC TR .FCTR A0-(Al,A2-(A21,A22)

Step 3C:

Write AFC TR .FCTR A0-(Al,A2-(A21,A22))

You have now reached the base segment and have
statements:

ODL

The last step requires that you substitute the label, AFCTR, into
.ROOT statement, which results in:

the

AFCTR:

the

writing

two

AFCTR:

written

.FCTR

.ROOT CNTRL-(AO-(Al,A2-(A21,A22))-BO-(Bl,B2) ,C)
.FCTR AO-(Al,A2-(A21,A22))

.ROOT CNTRL-AFCTR-BO-(Bl,B2) ,C)
.FCTR AO-(Al,A2-(A21,A22))

Additional .FCTR statements would be determined and written in the
same way.
For example, you could write a .FCTR statement labeled
BFCTR for the segments BO, Bl, and B2.
The following section shows how to
co-tree by using the same methods.

3.6.3

write

Creating an ODL Statement for a
Address Space Diagram

Co-Tree

ODL

statement

Using

for

Virtual

Assuming that you want to write an ODL statement for a co-tree like
the one in Figure 3-19, you would have two virtual address space
allocation diagrams, one for the main tree and one for
the co-tree.
These two diagrams are shown in Figure 3-19.

3-39

OVERLAY CAPABILITY

A21
A1

A22

r--

CNTRLX

CNTRLY

ROOT (CNTRL)

CNTRL2

MAIN TREE

CO-TREE
ZK-1051-82

Figure 3-19

Virtual Address Space Allocation for a Main Tree
and Its Co-Tree

From Figure 3-19 you see that the co-tree is a stack of segments also.
Therefore,
it is possible to write the statement for the co-tree in
the same fashion and with the same rules as that described in Section
3.6. However, certain facts must be kept in mind.
These are that:
•

The co-tree has a null root

•

A .NAME statement must be used to name the null root

•

A comma must be placed outside of the parentheses and at the
end of that part of the .ROOT statement that defines the main
tree

Therefore, the ODL statement that we obtain before writing the co-tree
part is:

AFCTR:

.NAME CNTRL2
.ROOT CNTRL-AFCTR-BO-(Bl,B2) ,C),
.FCTR AO-(Al,A2-(A21,A22))

By following the rules in Section 3.6 and by using
Figure 3-19, you can then create the ODL statement:

AFCTR:

3.7

the

diagram

.NAME CNTRL2
.ROOT CNTRL-AFCTR-BO-(Bl,B2) ,CNTRL2-(CNTRLX,CNTRLY)
.FCTR A0-(Al,A2-(A21,A22))

OVERLAYING PROGRAMS WRITTEN IN A HIGH-LEVEL LANGUAGE

Programs written in a high-level language usually require the use of a
large number of library routines in order to execute. Unless care is
taken when overlaying such programs, the following problems can occur:
•

TKB throughput may be drastically reduced because
number of library references in each overlay segment.

3-40

the

OVERLAY CAPABILITY
•

Library references from the default object module library that
are
resolved
across
tree
boundaries
can
result in
unintentional displacement of segments from memory at run
time.

•

Attempts to task-build such programs can result in multiple
and ambiguous symbol definitions when a co-tree structure is
defined.

The following procedures are effective in solving these problems:
•

You can increase TKB throughput by linking
library routines into the main root segment.

commonly

used

•

You can eliminate ambiguous definitions, multiple definitions,
and cross-tree references by using the NOFU switch (the TKB
default) to restrict the scope of the default library search.
However, restricting the scope of the default library search
may also cause problems.

If sufficient memory is available, you can effectively place the
object time system in the root segment by building a memory-resident
library.
This also reduces total system memory requirements if other
tasks are also currently using the library.
If a memory-resident library cannot be built, you can force library
modules into the root by preparing a list of the appropriate global
references and linking the object module into the root segment.
For other ways to reduce task size, you
guide for the language you are using.

3.8

EXAMPLE 3-1:

should

consult

the

user's

BUILDING AN OVERLAY

The text in this section and the figures associated with it illustrate
the building of an overlay structure.
For this example, the routines
of the resident library LIB.TSK and the task that refers to it,
MAIN.TSK
(from Example 5-3, Chapter 5}, are assembled as separate
modules and built as an overlaid task.
This task is built first with
disk-resident overlays and then with memory-resident overlays.
The
disk-resident version of the task is named
OVR.TSK
and
the
memory-resident version is named RESOVR.TSK.
NOTE
This example is intended to provide you
with
a working
illustration of the
Overlay Description Language.
It does
not reflect the most efficient use of
it.
Two alterations were made to each of the routines for this example:
•

A .TITLE and
.END assembler directive was
routine to establish it as a unique module.

3-41

added

each

OVERLAY CAPABILITY
•

The following assembler directive was added to each arithmetic
routine to increase its allocation:
.BLKW 1024.*3
This was done to make TKB allocation
obvious for documentation purposes.

address

space

The operation of the overlaid task is identical to that of Example 5-3
in Chapter 5.
The routines and their titles as a result of the .TITLE
directives are as follows:

• The integer addition routine is named ADDOV •
• The integer subtraction routine is named SUBOV •

• The integer multiplication routine is named MULOV •
• The integer division routine is named DIVOV •
• The register save and restore routine is named SAVOV.
• The print routine is named PRNOV •
• The main calling routine is named ROOTM •
The lengths of the modules are:
Module

Length (in Octal)

AD DOV

14024 bytes

SUBOV

14024 bytes

MULOV

14024 bytes

DIVOV

14026 bytes

SAVOV

4042 bytes

PRNOV

4260 bytes

ROOTM

4104 bytes

The flow of control for OVR.TSK is as follows:
1.

ROOTM calls AD DOV and ADDOV returns to ROOTM.

ROOTM calls PRNOV to print the result and
ROOTM.

ROOTM calls SUBOV and SUBOV returns to ROOTM.

ROOTM calls PR NOV to print the result and
ROOTM.

ROOTM calls DIVOV and DIVOV returns to ROOTM.

ROOTM calls PRNOV to print the result and
ROOTM.

3-42

PRNOV

returns

OVERLAY CAPABILITY
7.

ROOTM calls MULOV and MULOV returns to ROOTM.

ROOTM calls PRNOV to print the result and
ROOTM.

PRNOV

returns

The print routine (contained in module PRNOV) is called between each
arithmetic operation by the control routine
(contained in module
ROOTM). To avoid loading it into physical memory each time it is
called, you can place PRNOV in the root segment of the task.
In
addition, each arithmetic routine calls SAVOV. Therefore, SAVOV must
be on a path common to all segments in the tree.
It too is placed in
the root segment of the task. One possible overlay configuration for
this task is shown in Figure 3-20.
SUBOV

I
MULOV

DIVOV

I
AD DOV

SAVOV

PR NOV

ROOTM
ZK-490-81

Figure 3-20

Overlay Tree of Virtual Address Space for OVR.TSK

To build this overlay, first create an ODL
contains its description:
.ROOT
.END

file

(OVERTREE.ODL)

that

ROOTM-PRNOV-SAVOV-*(MULOV,ADDOV-(SUBOV,DIVOV))

Then, after you have modified the modules and assembled them, you
build the task with the following command line:

can

TKB> OVR,OVR/-SP=OVRTREE/MP
This command instructs TKB to build a task image, OVR.TSK, and to
create a map file, CVR.MAP, under the UFD that corresponds to the
terminal UIC. The negated spool switch
(/-SP)
inhibits TKB from
spooling the map file to the line printer.
The overlay switch (/MP) attached to the input file tells TKB that the
input file is an ODL file.
Therefore, this file will be the only
input file specified. Refer to Chapter 10 for a description of the
switches used in this example.
A portion of the map that results from this task
Example 3-1.

3-43

build

shown

OVERLAY CAPABILITY
Example 3-1

Map File for OVR.TSK

Memory allocation map
Ol-JAN-82

OVR.TSK

Page 1

TKB M40.10
10:06

Partition name : GEN
Identification : 01
Task UIC
[7,62]
Stack
limits: 000260 001257 001000 00512.
PRG xfr address: 001264
Total address windows: 1. ~
Task image size
7488. words
Task address limits: 000000 035107
R-W disk blk limits: 000002 000073 000072 00058.
OVR.TSK Overlay description:
Base

Top

---- 0---

Length

000000 I 005033 I 005034
005034 021057 014024
005034 021057 014024
021060 035103 014024
021060 035107 014030

ROOTM

02588.
06164.
06164.
06164.
06168.

MULOV
AD DOV
SUBOV
DIVOV

*** Root segment:

ROOTM

R/W mem limits: 000000 005033 005034 02588.
Disk blk limits: 000002 000007 000006 00006.
Memory allocation synopsis:
Section

-------

. BLK.:(RW,I,LCL,REL,CON) 001260 002514 01356 •

ANS

001260
001362
001642
:(RW,D,GBL,REL,OVR) 003774
003774
003774

Title

I dent

File

ROOTM
PR NOV
SAVOY

01
01
01

ROOTM.OBJ;l
PRNOV.OBJ;l
SAVOV.OBJ;l

ROOTM
PR NOV

01
01

ROOTM.OBJ;l
PRNOV.OBJ;l

000102
000260
000042
000002
000002
000002

00066.
00176.
00034.
00002.
00002.
00002.

001550-R

Global symbols:
AADD
MULL

004032-R
004022-R

DIVV
SAVAL

004052-R
001642-R

*** Task builder statistics:
Total work file references: 6863.
Work file reads: o.
Work file writes: o.
Size of core pool: 7086. words ( 27.
Size of work file:
3072. words (12.
Elapsed time:OO:OO:l4

3-44

pages)
pages)

SUBB

004042-R

OVERLAY CAPABILITY
Figure 3-21 shows the allocation of virtual address space for OVR.TSK.
The circled numbers in Example 3-1 correspond to those in Figure 3-21.
Note that the root segment for OVR.TSK (ROOTM) has expanded with task
building while the segments containing the arithmetic routines have
not. Before task building, the sum of the modules
(in octal bytes)
that comprise the root segment is:
4104 + 4260 + 4042 = 14,426 bytes
After task building, the root segment is 20,677(octal)
bytes long.
TKB has added a header, a stack area, and the overlay run-time
routines to it~ The segments containing the arithmetic routines have
not changed.
If there had been calls from segments nearer the root to
segments farther up the tree, the Task Builder would have added data
structures to the calling segments as well.
(Refer to Chapter 4 for a
description of the overlay loading methods.)
You can build OVR as a memory-resident overlay by simply adding the
memory-resident operator (!) to the ODL file for OVR as shown below:
.ROOT
.END

ROOTM-PRNOV-SAVOV-*!(MULOV,ADDOV-! (SUBOV,DIVOV))

For this example, the name of the ODL file and the task image file
have
been
changed
to RESOVR.ODL to distinguish it from the
disk-resident version.
You can build RESOVR with the following
command line:
TKB> RESOVR,RESOVR/-SP=RESOVR/MP
This command directs TKB to build a task named RESOVR.TSK and to
create a map file named RESOVR.MAP.
The negated spooling switch
(/-SP) inhibits spooling of the map filee
The /MP switch on the input file tells TKB that the file is an ODL
file and that it will be the only input file for this task build.
Refer to Chapter 10 for a description of the switches used in this
example.
A portion of the map that results from this task
Example 3-2.

build

shown

Figure 3-19 shows the allocation of virtual address space for
RESOVR.TSK. The circled numbers in Example 3-2 correspond to those in
Figure 3-22.

3-45

OVERLAY CAPABILITY

160000

APR 7-

140000

APR 6-

120000

APR 5-

100000

APR 4-

60000

APR 3- 035107
SUBOV DIVOV

40000

APR 2-

- 021057
AD DOV

MULOV

~
- 005033

20000

APR 1-

SYSLIB
SAVOV
PR NOV
ROOTM

ROOT SEGMENT

- 001257

APR 0-

Figure 3-21

HEADER AND STACK

ZK-411-81

Allocation of Virtual Address Space for OVR.TSK

3-46

OVERLAY CAPABILITY
Example 3-2

Map File for RESOVR.TSK

Partition name : GEN
Identification : 01
Task UIC
[7,62]
Stack
limits: 000320 001317 001000 00512.
PRG xfr address: 001324
Total address windows: 3. f)
Task image size
13920. words
Task address limits: 000000 057777
R-W disk blk limits: 000003 000074 000072 00058.
RESOVR.TSK Overlay description:
Base

Top

---- 0---

Length

000000 I 005677 I 005100
020000 034077 014100
020000 034077 014100
040000 054077 014100
040000) 054077)1014100

ROOTM

03008.
06208.
06208.
06208.
06208.

MULOV
AD DOV
SUBOV
DIVOV

*** Root segment:

ROOTM

R/W mem limits: 000000 005677 005700 03008.
Disk blk limits: 000003 000010 000006 00006.
Memory allocation synopsis:
Title

Section

-------

!dent

. BLK.:(RW,I,LCL,REL,CON) 001320 002514 01356. ROOTM 01

ANS

001320
001422
001702
:(RW,D,GBL,REL,OVR) 004034
004034
004034

000102
000260
000042
000002
000002
000002

00066.
00176.
00034.
00002.
00002.
00002.

File

PRNOV
SAVOV

01
01

ROOTM.OBJ;l
PRNOV.OBJ;l
SAVOV.OBJ;l

ROOTM
PRNOV

01
01

ROOTM.OBJ;l
PRNOV.OBJ;l

Global symbols:
AADD
MULL

004072-R
004062-R

DIVV
SAVAL

004112-R
001702-R

001610-R

*** Task builder statistics:
Total work file references:
6938.
Work file reads
O.
Work file writes : O.
Size of core pool:
4178. words (16.
Size of work file:
3072. words (12.
Elapsed tirne:00:00:21

3-47

pages)
pages)

SUBB

004102-R

OVERLAY CAPABILITY
Note that TKB allocates virtual address space for each level of
overlay segment on a 4K-word boundary. When built as a disk-resident
overlay, this structure requires 12K words of virtual address space;
when built as a memory-resident overlay structure, it requires 16K
words of virtual address space.
As noted earlier, you must be careful
when using memory-resident overlays to ensure that virtual address
space is used efficiently.

160000

APR 7-

140000

APR 6-

120000

APR 5-

100000

60000

40000

20000

APR 1-

SYSLIB
SAVOV
PR NOV
ROOTM

ROOT SEGMENT

! - - - - - - - - - - - - - 001317

HEADER AND STACK
~ -.
APR 0- ..___ _ _ _ _ _ _ _____,, - ~

ZK-412-81

Figure 3-22

Allocation of Virtual Address Space for RESOVR.TSK

3-48

OVERLAY CAPABILITY
Finally, note in Figure 3-22 that TKB has allocated three window
blocks
to
map
RESOVR.TSK.
Each level of the overlay in a
memory-resident overlay requires a separate window block to map it.
In a disk-resident overlay, a single window block maps the entire
structure regardless of how many segment levels there are within the
structure.
This consideration can be important when you are building
an overlaid task that either creates dynamic regions or accesses a
resident library or common, because of the extra window blocks
required to use these features.

3.9

SUMMARY OF THE OVERLAY DESCRIPTION LANGUAGE
•

An overlay structure consists of one or more trees. Each tree
contains at least one segment.
A segment is one or more
modules containing one or more program sections that can be
loaded by a single disk access.
A tree can have only one root segment, but
number of overlay segments.

can

have

any

•

An ODL file is a text file consisting of a series of overlay
description directives, one directive per line. You enter
this file in the TKB command line, and identify it as an ODL
file by attaching the MP switch to the file name.
If you
enter an ODL file in the TKB command line, it must be the only
input file you specify.

•

The Overlay Description Language provides five directives for
specifying the tree representation of the overlay structure:
.ROOT and .END -- There can be only one .ROOT and one .END
directive;
the .END directive must be the last directive
because it terminates input •
• PSECT, .FCTR, and .NAME -- These can be used in any
in the ODL file.

•

order

You define the tree structure using the hyphen (-), comma (,),
and exclamation point (!) operators, and by using parentheses.
The hyphen operator (-) indicates that its arguments are to
be concatenated and thus are to coexist in memory.
The comma operator (,) within parentheses indicates that
its arguments are to overlay each other either physically,
if disk resident, or virtually, if memory resident.
The comma operator not within parentheses delimits
trees.

overlay

The exclamation point operator
(!)
immediately before a
left parenthesis declares the enclosed segments to be
memory resident. Nested segments in parentheses are not
affected by an exclamation point operator at a level closer
to the root.

3-49

OVERLAY CAPABILITY
The parentheses group segments that begin at the same point
in memory.
For example:
.ROOT A-B-(C,D-(E,F))
This ODL command line defines an overlay structure with a
root segment consisting of the modules A and B.
In this
structure, there are four overlay segments: C, D, E, and
F.
The outer pair of parentheses indicates that the
overlay segments C and D start at the same virtual address;
and similarly, the inner parentheses indicate that E and F
start at the same virtual address.
•

The .ROOT directive defines the beginning overlay structure.
The arguments of the .ROOT directive are one or more of the
following:
File specifications as described in Chapter 1
Factor labels
Segment names
Program-section names

•

The .END directive terminates input.

•

The .FCTR directive provides a means for replacing text by a
symbolic reference
(the factor label). This replacement is
useful for two reasons:
The .FCTR directive extends the text of the .ROOT directive
to more than one line and thus allows complex trees to be
represented.
The
.FCTR directive allows you to write the overlay
description in a form that makes the structure of the tree
more apparent.
For example:
.ROOT A-(B-(C,D) ,E-(F,G) ,H)
.END
Using the
.FCTR directive,
description as follows:

can

write

this

The second representation makes it clear
three main branches.

that

the

Fl:
F2:

•

you

overlay

.ROOT A-(Fl,F2,H)
.FCTR B-(C,D)
.FCTR E-{F,G)
.END
tree

has

The .PSECT directive provides a means for directly specifying
the segment in which a program section is placed.
It accepts
the name of the program section and its attributes~
For
example:
.PSECT ALPHA,CON,GBL,RW,I,REL

3-50

OVERLAY CAPABILITY
ALPHA is the program section name and the remaining arguments
are
the
program
section's attributes
(program section
attributes are described in Chapter 2).
The program section name (composed of the characters A-Z, 0-9,
$, or
.)
must appear first in the .PSECT directive, but the
attributes can appear in any order or can be omitted.
If an
attribute is omitted, a default condition is assumed.
The
defaults for program section attributes are RW, I, LCL,
REL,
and CON.
In the example above, therefore, you need only specify the
attributes that do not correspond to the defaults:
.PSECT
ALPHA,GBL
•

The .NAME directive provides you with the means to designate a
segment name for use in the overlay description, and to
specify segment attributes.
This directive is useful for
creating a null segment, naming a segment that is to be loaded
manually, or naming a nonexecutable segment that is to be
autoloadable.
(Refer to Chapter 4 of this manual for a
description of manually loaded and automatically
loaded
segments.)
If you do not use the .NAME directive, the Task
Builder uses the name of the first file, program section, or
library module in the segment to identify the segment.
The .NAME directive creates a segment name as follows:
.NAME segname,attr,attr
segname
is the designated name (composed
0-9, and$).

the

characters

A-Z,

is an optional attribute taken from
NODSK, NOGBL, DSK.

the

following:

GBL,

attr

The defaults are NOGBL and DSK.
The defined name must be
unique
with respect to the names of program sections,
segments, files, and factor labels.
•

You can define a co-tree by specifying an additional tree
structure in the
.ROOT directive.
The first overlay tree
description in the
.ROOT directive is the
main
tree.
Subsequent overlay descriptions are co-trees. For example:
.ROOT A-B-(C,D-(E,F)) ,X-(Y,Z) ,Q-(R,S,T)
The main tree in this example has the root segment consisting
of files A.OBJ and B.OBJ.
Two co-trees are defined;
the
first co-tree has the root segment X and the second co-tree
has the root segment Q.

3-51

CHAPTER 4

OVERLAY LOADING METHODS

The RSX-llM/M-PLUS systems
provide
two
disk-resident and memory-resident overlays:

methods

for

•

Autoload -- The overlay run-time routines are
called to load segments you have specified.

•

Manual Load -- You include in the task explicit calls
overlay run-time routines.

automatically

When you build an overlaid task, you must decide which one of
methods to use, because both cannot be used in the same task.

the
these

The loading process depends on the kind of overlay:
•

Disk resident -- A segment is loaded from disk into a shared
area of physical memory, writing over whatever was present.

•

Memory resident -- A segment is loaded by mapping a set of
shared virtual addresses to a unique unshared area of physical
memory, where the segment has been made permanently resident
(after having been initially brought in from the disk).

With the autoload method, the overlay run-time routines handle loading
and error recovery.
Overlays are automatically loaded by being
referenced through a transfer-of-control instruction
(CALL,
JMP, or
JSR).
No explicit calls to the overlay run-time routines are needed.
In the manual load method, you handle loading and error recovery
explicitly.
Manual
loading saves space and gives you full control
over the loading process, including the ability to specify whether
loading is to be done synchronously or asynchronously.
In the manual load method, you must provide for
loading the overlay
segments of the main tree, as well as the root segments and the
overlay segments of the co-trees.
Once loaded, the root segment of a
co-tree remains in memory.

4.1

AUTOLOAD

To specify the autoload method, you use the autoload
indicator, an
asterisk
(*). You place this indicator in the ODL description of the
task at the points where loading must occurw
The execution of a
transfer-of-control
instruction to an autoloadable segment up-tree
(farther away from the root) initiates the autoload process.

4-1

OVERLAY LOADING METHODS
4.1.1

Autoload Indicator

The autoload indicator (*) marks as autoloadable the segment or other
task element (as defined below).
If you apply the autoload indicator
to an ODL statement enclosed in parentheses, every task element within
the parentheses is marked as autoloadable.
Placing the autoload
indicator at the outermost level of parentheses in the ODL description
marks every module in the overlay segments as autoloadable.
In the TKl example of Chapter 3, Section 3.1.1, if segment C consisted
of a set of modules Cl, C2, C3, C4, and CS, the tree diagram would be
as shown in Figure 4-1.

A21
I

A1
I

I
AO

A22
I

I
BO
I
I
CNTRL

C2
C1
I
ZK-413-81

Figure 4-1

Details of Segment C of TKl

Placing the autoload indicator at the outermost level of parentheses
ensures that, regardless of the flow of control within the task, a
module will be properly loaded when it is called. The ODL description
for task TKl would be:
AFCTR:
BFCTR:
CFCTR:

.ROOT CNTRL-*(AFCTR,BFCTR,CFCTR}
.FCTR AO-(Al,A2-(A21,A22))
.FCTR BO-(Bl,B2)
.FCTR Cl-C2-C3-C4-C5
.END

When you use autoload, the root of a co-tree is loaded by path loading
if one of the branches of the co-tree is called before the root.
However, if the root of the co-tree is called before the branch is
called, the root must have an autoload indicator.
Also, when the root segment of a co-tree is not a null segment, you
must mark the co-tree's root segment (CNTRL2) as well as its outermost
level of parentheses to ensure that all modules of the co-tree are
properly loaded.
For example,
if the co-tree root (CNTRL2) of the
multiple tree example, Section 3.5.2, had contained code or data, it
would have been marked as follows:
.ROOT CNTRL-*(AFCTR,BFTCR,CFCTR) ,*CNTRL2-*(CNTRLX,CNTRLY)

You can apply the autoload indicator to the following elements:
•

File names -- to
autoloadable.

•

Portions
of
ODL
tree
descriptions
enclosed
in
parentheses -- to make all the elements within the parentheses
autoloadable,
including
elements
within
any
nested
parentheses.

make

all

4-2

the

components

the

file

OVERLAY LOADING METHODS
•

Program section names -- to
make
the
program
section
autoloadable.
The program section must have the instruction
(I) attribute.

•

Segment names defined by the .NAME directive -- to
components of the segment autoloadable.

•

.FCTR label names -- to make the first component of the factor
autoloadable.
All elements specified in the .FCTR statement
are autoloadable if they are enclosed in parentheses.

make

all

In the following example, two .PSECT directives and a .NAME directive
are introduced into the ODL description for TKl. Autoload indicators
are applied as follows:
AFCTR:
BFCTR:
CFCTR:

.ROOT CNTRL-(*AFCTR,*BFCTR,*CFCTR) 0
.FCTR AO-*ASUB1-ASUB2-*(Al,A2-(A21,A22))
.FCTR (BO-(Bl,B2))
.FCTR CNAM-Cl-C2-C3-C4-C5
.NAME CNAM,GBL 0
.PSECT ASUBl,I,GBL,OVR 8
.PSECT ASUB2,I,GBL,OVR
.END

The following notes are keyed to the example above.

The autoload
therefore:

indicator

*AFCTR=*AO

*BFCTR=*(BO-(Bl,B2))

*CFCTR=*CNAM

applied

each

factor

name;

CNAM, however, is an element defined by a
.NAME directive.
Therefore, all components of the segment to which the name
applies are made autoloadable, that is, Cl, C2, C3, C4, and

cs.

The autoload indicator is applied to the name of a program
section with the instruction (I) attribute (*ASUBl), so that
program section ASUBl is made autoloadable.
The autoload indicator is applied to a
description enclosed in parentheses:

portion

the

ODL

*(Al,A2-(A21,A22))
Thus, every element within
the
parentheses
is
autoloadable (that is, files Al, A2, A21, and A22).

made

The net effect of this ODL description is to make every element except
program section ASUB2 autoloadable.

4.1.2

Path Loading

The autoload method uses path loading;
that is, a call from one
segment to another segment up-tree
(farther away from the root)
ensures that all the segments on the path from the calling segment to
the called segment will reside in physical memory and be mapped.
Path
loading is confined to the tree in which the called segment resides.

4-3

OVERLAY LOADING METHODS
A call from a segment in one tree to a segment in another tree results
in the loading of all segments on the path in the second tree from the
root to the called module.
In Figure 4-2, if CNTRL calls A22, all the modules between the
and A2 are loaded.
In this case, modules AO and A2 are loaded.
A22

A21

CNTRL

C5
C4
C3
C2
C1

BO
CNTRL

ZK-414-81

Figure 4-2

Path-Loading Example

With the autoload method, the overlay run-time routines keep a record
of the segments that are loaded and mapped, and issue disk-load
requests only for segments that are not in memory.
If CNTRL calls A2
after calling Al, AO
is not loaded again because it is already in
memory and mapped.
A reference from one segment to another segment down-tree
(closer to
the root)
is resolved directly.
For example, A2 can immediately
access AO because AO was path loaded in the call to A2.

4.1.3

Autoload Vectors

To resolve a reference up-tree to a global symbol in an autoloadable
segment, TKB generates an autoload vector for the referenced global
symbol. The reference in the code is changed to a definition that
points to an autoload vector entry.
The format for the autoload
vector for conventional tasks is shown in Figure 4-3 and the format
for I- and D-space tasks is shown in Figure 4-4.
JSR

PC,@.NAUTO

PC RELATIVE OFFSET TO .NAUTO
SEGMENT DESCRIPTOR ADDR.
ENTRY POINT ADDRESS
ZK-415-81

Figure 4-3

Autoload vector Format for Conventional Tasks

For I- and D-space tasks, TKB generates the autoload vector in a
format that differs from the vector in a conventional task.
The r~
~nd D-space autoload vector is six words
long and consists of two
parts:
one part residing in I-space and the other part residing in
D-space. The I-space part consists of two 2-word instructions, and
the D-space part consists of two words of data. The data in the
vector are the segment descriptor address and the target entry point
address. The 1- and D-spacie vector is shown in Figure 4-4.

4-4

OVERLAY LOADING METHODS
,

~~·

·. ·'Th~":t·ask· :root:'ana the overlay. ·se9ments may contain autoloaa vectors;
· ~,t'he . r-·~pace · part '.o~ .the root ·or· segment c·ontains 'the I-space part of
.:the. vectors( and the 'D-space part of the root or s'egment contains the
.·p-space 'paJ:'t · <:>f the. v.ectors .•
::.The MOV in.'structi~n n the ·I-space pp rt . of the vector ·places the·
·"addre'ss
the D-space part of the ·vector on. the stack. The second
:-·lnstruc.':t:i.qh.. An th.e vecto.r 'executes :an indirect JMP . to $AUTO thr.ough·
'the ''locatiori ~NAUTO ..

'•

,,.

. .

~ ..

MOV (PC)+,-(SP)
ADDRESS OF PACKET (D-SPACE)
JMP @.NAUTO
PC RELATIVE OFFSET TO NAUTO
I-SPACE PORTION

ADDRESS OF SEGMENT DESCRIPTOR
ENTRY POINT ADDRESS
D-SPACE PORTION
ZK-1089-82

In Figures 4-3 and 4,;.;.4,~. a transfer-of-control instruction to the
up-tree global symbol generates an autoload vector in the shown
format.
An example of the code sequence used in a call to a global
symbol in an autoloadable segment is shown in Figure 4-5.

USER TASK ROOT

•

-- .

CALL GLOBAL

----~~

AUTOLOAD VECTOR
JSR PC,@.NAUTO
SEGMENT DESCRIPTOR ADDRESS
ENTRY POINT ADDRESS (GLOBAL)

$AUTO AUTOLOAD ROUTINE
$AUTO:
;LOAD
;SEGMENT
USER TASK SEGMENT
GLOBAL::
......
_ _ _ _ JMP GLOBAL ;GO TO
;GLOBAL IN
;SEGMENT
----RETURN

ZK-416-81

Figure 4-5

Example Autoload Code Sequence for a Conventional Task

4-5

OVERLAY LOADING METHODS
An exception to the procedure for generating autoload vectors is made
in the case of a program section with the data (D) attribute.
References from a segment to a global symbol up-tree in a program
section with the data (D) attribute are resolved directly.
Because TKB can obtain no information about the flow of control within
the task, it often generates more autoload vectors than are necessary.
However, your knowledge of the flow of control within your task,
and
of path loading, can help you determine where to place the autoload
indicators. By placing the autoload indicators only at the points
where loading is actually required, you can minimize the number of
autoload vectors generated for the task.
In the following example, all the calls to overlays originate in the
root segment. That is, no module in an overlay segment calls outside
its segment. The root segment CNTRL has the following contents:
PROGRAM CNTRL
CALL Al
CALL A21
CALL A2
CALL AO
CALL A22
CALL BO
CALL Bl
CALL B2
CALL Cl
CALL C2
CALL C3
CALL C4
CALL CS
END
If you place the autoload indicator at the outermost level of
parentheses,
13 autoload vectors are generated for this task;
however, because A2 and AO are loaded by path loading to A21,
the
autoload vectors for A2 and AO are unnecessary.
Moreover, because the
call to Cl loads the segment that contains C2, C3, C4, and CS,
autoload vectors for C2 through CS are unnecessary.
You can eliminate the unnecessary auto load vectors by placing the
autoload indicator only at the points where explicit loading is
required, as follows:
AFCTR:
BFCTR:
CFCTR:

.ROOT CNTRL-(AFCTR,*BFCTR,CFCTR)
.FCTR AO-(*Al,A2-*(A21,A22))
.FCTR (BO-{Bl,B2))
.FCTR *Cl-C2-C3-C4-C5
.END

With this ODL description, TKB generates seven autoload vectors -- for
Al, A21, A22, BO, Bl, B2, and Cl.

4-6

OVERLAY LOADING METHODS
4.1.4

Autoloadable Data Segments

You can make overlay segments that contain no executable code
autoloadable, as follows. First, you must include a .NAME directive
and specify the GBL attribute, as described in Section 3.4.4.
For
example:
.ROOT A-*(B,C)
.NAME BNAME,GBL
.FCTR BNAME-BFIL
.END

The global symbol BNAME is created and entered into the symbol table
of segment BNAME.
Because this segment is marked to be autoloaded;
root segment A calls segment BNAME as follows:
CALL BNAME
The segment is autoloaded and
occurs.

immediate

return

inline

code

The data of BFIL must be placed in a program section with the data (D)
attribute to suppress the creation of autoload vectors.

4.2

MANUAL LOAD

If you decide to use the manual-load method to load segments, you must
include in your program explicit calls to the $LOAD routine. These
load requests must supply the name of the segment to be loaded.
In
addition,
they
can
include
information necessary to perform
asynchronous load requests, and to handle load request failures.
The $LOAD routine does not path load. A call to $LOAD loads only the
segment named in the request. The segment is read in from disk and
mapped. For memory-resident overlays;
the segment is mapped, but
only read in if it was not previously read in.
A MACR0-11 programmer calls the $LOAD routine directly.
A
programmer calls $LOAD using the FORTRAN subroutine MNLOAD.

4.2.1

FORTRAN

MACR0-11 Manual Load Calling Sequence

A MACR0-11 programmer calls $LOAD as follows:
MOV
CALL

#PBLK,RO
$LOAD

PBLK is the address of a parameter block with the following format:
PBLK:

.BYTE length,event-flag
.RAD50 /seg-name/
.WORD [i/o-status] or 0
.WORD [ast-trp] or O

length

The length of the parameter block (3 to 5 words) •

4-7

OVERLAY LOADING METHODS
event-flag
The event flag number, used for
asynchronous loading.
If
event-flag number is O, synchronous loading is performed.

the

seg-name
The name of the segment to be loaded:
Radix-50 name, occupying two words.

6-character

i/o-status
The address of the I/O status doubleword.
codes apply.

Standard

QIO

status

ast-trp
The address of an asynchronous trap service routine to which
control is transferred at the completion of the load request.
The condition code
follows:

C-list

set

cleared

return,

•

If condition code C=O, the load request was accepted.

•

If condition code C=l, the load request was unsuccessful.

For a synchronous load request, the return of the condition code C=O
means that the desired segment is loaded and is ready to be executed.
For an asynchronous load request, the return of the code C=O means
that the load request was successfully queued to the device driver,
but the segment is not necessarily in memory.
Your program must
ensure that loading has been completed by waiting for the specified
event flag before calling any routines or accessing any data in the
segment.

4.2.2

MACR0-11 Manual Load Calling Sequence For I- and D-Space Tasks

A MACR0-11 programmer calls $LOAD as follows:

MOV

f PBLK,RO

CALL

$LOAD

PBLK is the. address of ~ parameter block with the following format
an I- and D-space task:

PBLK: BYTE 3,0
.RADSO /seg-name/
length
The length of the parameter block (3 words) •

4-8

OVERLAY LOADING METHODS
,event-flag
Specify this as o.. Only synchronous load requests
when loading I- and D-space segments.

are. .possible

se9-name
The name of the segment .to be loaded:
.Radix-50 name, occupying two words.

i.:..

6....;ch.aracter

The ·condition .code c;..list is set or cleared on retur'n., ·as· ·fo1iows:""
9

'If condition code C=O: the load request was accepted.

• lf

. c.ondi..tion code C=l, the load request was unsuoceS$fU.l
!.
''.
!• --~'

"=~'' !
J

,For, a' .synchron?us load re.quest, which· .is the only" one. p.o.ssible(~or >.I.-. :
,"ana·.: o.-.space segments, the return of' th.e condition cod.e: .C=O· ·means. · t}lat;..
·t,·he: .qesired .segment· is loaded· and is ready to be execu,ted.· · y'our
pr,,09.ram: mus.t ensure that loading·. has been successfu1 ·by c}leck'ing .·for
tpe conditi·on.cpde ·rather, them assuming that th~ segment:' ~.as bee,ri
I oa:ded~
· ·
· ' '· "

4.2.3

FORTRAN Manual Load Calling Sequence

To use the manual load mechanism in a FORTRAN program, your program
must refer to the $LOAD routine by means of the MNLOAD subroutine.
The subroutine call has the form:
CALL MNLOAD(seg-name,[event-flag] ,[i/o-status] ,[ast-trp] ,[ld-ind])
seg-name
A 2-word real variable containing the segment
format.

name

Radix-50

event-flag
An optional integer event flag number used for an asynchronous
load request. If the event flag number is O, the load request is
synchronous.
i/o-status
An optional 2-word integer array containing the I/O status
doubleword,
as
described
for
the QIO directive in the
RSX-llM/M-PLUS Executive Reference Manual.
ast-trp
An optional asynchronous trap subroutine
entered
at
the
completion of a request. MNLOAD requires that all pending traps
specify the same subroutine.

4-9

OVERLAY LOADING METHODS
ld-ind
An optional
integer variable containing the results of
subroutine call.
One of the following values is returned:
+l

Request was successfully executed.

-1

Request had
executed.

bad

parameters

You can omit optional arguments.

was

not

the

successfully

The following calls are legal:

Call

Effect

CALL MNLOAD (SEGAl)

Loads segment named in
SEGAl synchronously.

CALL MNLOAD (SEGAl,O,,,LDIND)

Loads segment named in
SEGAl synchronously and
returns success indicator to LDIND.

CALL MNLOAD (SEGAl,l,IOSTAT,ASTSUB,LDIND)
Loads segment named in
SEGAl
asynchronously,
transferring control to
ASTSUB upon completion
of the load request;
stores the I/0 status
doubleword
in
IOSTAT
and
the
success
indicator in LDIND.
The following example uses the program CNTRL, previously discussed in
Section 4.1.
In this example, there is sufficient processing between
the calls to the overlay segments to make asynchronous loading
effective.
The
autoload indicators are removed from the ODL
description and the FORTRAN programs are recompiled with explicit
calls to the MNLOAD subroutine, as follows:
PROGRAM CNTRL
EXTERNAL ASTSUB
DATA SEGAl /6RA1
DATA SEGA21 /6RA21

/
/

CALL MNLOAD (SEGAl,l,IOSTAT,ASTSUB,LDIND)

CALL Al

CALL MNLOAD (SEGA21,l,IOSTAT,ASTSUB,LDIND)

4-10

OVERLAY LOADING METHODS
CALL A21

END
SUBROUTINE ASTSUB
DIMENSIO~ IOSTAT(2)

END
When the AST trap routine is used, the I/O status
automatically supplied to the dummy variable IOSTAT •

doubleword

.;,,
',mµsf',,i',re.,f'e:r'·>' ·t',a.·. ,··.·t'he.·w./$.~&At>'wro.u·t·fl'le/·'ti.;{.$e'p'li1s:

)~~;*~;zz~~~;~;{~~~~]~;;~;~2*~~~1}.F>%~:,.
~::·::~7~~·~~::~:~·,:·:.·>';;,~.?/:·::·.·:,/<,-''
•!

,·,~ ::/:·· / )~·.,: ';':

·· ::,'A···· :2~'~oi·'a
/3~:t~·~t.'':,:
'

",:·

"~14...:,i;.Qd/ .'.' .,
~· ~·~ ,".: /<,;·

:'' /

{:"'* '!.,,,

< ~ ·;

. / CADL. MNLOAD

Only. synchr.onous load~ng is possible'
D-space task segments.

4.3

,when

manually

lo~dihg . 1-' and

ERROR HANDLING

If you use the autoload mechanism, a simple recovery procedure is
provided that checks the u1rective b~atus Word (DSW) for an error
indication. If the DSW indicates that no system dynamic storage is
available, the routine issues a Wait for Significant Event directive
and tries again;
if the problem is not dynamic storage, the recovery
4-11

OVERLAY LOADING METHODS
procedure generates a synchronous breakpoint trap.
If
the task
services the trap and returns without altering the state of the
program, the request will be retried.
If you select the manual-load method, you must provide error handling
routines that diagnose load errors and provide appropriate recovery.
A more comprehensive user-written error recovery subroutine can be
substituted
for
the
system-provided routine if the following
conventions are observed:
•

The error recovery routine must
$ALERR.

have

the

entry

point

•

The contents of all registers must be saved and restored.

name

On entry to $ALERR, R2 contains the address of the segment descriptor
that could not be loaded. Before recovery action can be taken, the
routine must determine the cause of the error by examining the
following words in the sequence indicated:

4.4

$DSW

The Directive Status word may contain an error
status
code,
indicating
that the Executive
rejected the I/O request to load the overlay
segment.

N.OVPT

The contents of this location, offset by N.IOST,
point to a 2-word I/O status block containing the
results of the load overlay request returned by
the device driver.
The status code occupies the
low-order byte of word O.
For example, for a
device-not-ready
condition, the code will be
IE.DNR.
(For more information on these codes,
refer to the IAS/RSX-11 I/0 Operations Reference
Manual.)
~-

GLOBAL CROSS-REFERENCE OF AN OVERLAID TASK

This section illustrates a global cross-reference that has been
created for an overlaid task. The task consists of a root segment
containing the module ROOT.OBJ, and overlay segments composed of
modules OVRl, OVR2, OVR3, and OVR4. The overlay description of the
file is as follows:
.ROOT
OVR: .FCTR

ROOT-(OVR,*OVR2)
OVR1-*(0VR3,0VR4}

Only segments OVR2, OVR3, and OVR4 are autoloadable.
the resulting overlay tree.
*OVR3

*OVR4

ROOT:

OVR1

*OVR2

Figure 4-6 shows

CALL OVR3
CALL OVR1
CALL OVR2

ROOT
ZK-417-81

Figure 4-6

Autoload Overlay Tree Example

4-12

OVERLAY LOADING METHODS
As shown, the global symbol OVRl is defined in module OVRl, and a
single nonautoloadable, up-tree reference is made to this symbol by
the module ROOT, as indicated by the circumflex.
Note that because
OVRl is not autoloadable, it depends on a call to OVR3 or OVR4 to get
loaded by path loading.
The asterisk indicates that the module
contains an autoloadable definition.
The modules shown with the
asterisk define the symbol.
The asterisks preceding the modules OVR2, OVR3, and OVR4 indicate that
the global symbols OVR2, OVR3, and OVR4 are autoload symbols and are
referenced from the module ROOT through an autoload vector, as shown
by the at-sign (@) character.
The asterisk and at-sign are shown in the cross-reference
Example 4-1.
Example 4-1
OVRTST

listing

Cross-Reference Listing of Overlaid Task

CREATED BY

TKB

ON 27-JUL-82 AT 12:04

GLOBAL CROSS REFERENCE

PAGE 1
CREF

SYMBOL

VALUE

REFERENCES •••

N.ALER
N. IOST
N.MRKS
N.OVLY
N.OVPT
N.RDSG
N.STBL
N.SZSG
OVRl
OVR2
OVR3
OVR4
ROOT
$ALBP1
$ALBP2
$ALERR
$AUTO
$DSW
$MARKS
$0TSV
$SAVRG
$VEXT
.FSRPT
.NALER
• NIOST
.NMRKS
.NOVLY
.NOVPT
.NRDSG
.NSTBL
.NSZSG

000010
000004
000016
000000
000054
000014
000002
000012
002014-R
002014-R
002014-R
002014-R
001176-R
001320-R
001416-R
001246-R
001302-R
000046
001546-R
000052
001452-R
000056
000050
001442-R
001436-R
001450-R
001432-R
000042
001446-R
001434-R
001444-R

AUTO
OVCTL
# OVRES
OVCTL
AUTO
# OVRES
# OVRES
# OVRES
# OVRl
* OVR2
* OVR3
* OVR4
# ROOT
# AUTO
# AUTO
# ALERR
# AUTO
ALERR
# OVCTL
# VCTDF
AUTO
# VCTDF
# VCTDF
# OVDAT
# OVDAT
# OVDAT
# OVDAT
# OVDAT
# OVDAT
# OVDAT
# OVDAT

# OVRES
# OVRES
# OVRES
OVCTL

ROOT
@ ROOT
@ ROOT
@ ROOT

OVDAT

# VCTDF
# SAVRG

4-13

# VCTDF

VOl

OVERLAY LOADING METHODS
Example 4-1
OVRTST

(Cont.)

CREATED BY

Cross-Reference Listing of Overlaid Task
TKB

ON 27-JUL-82 AT 12:04

PAGE 2
CREF

SEGMENT CROSS REFERENCE
SEGMENT NAME

RESIDENT MODULES

OVRl
OVR2
OVR3
OVR4
ROOT

OVRl
OVR2
OVR3
OVR4
ALERR
VCTDF

AUTO

OVCTL

CVDAT

OVRES

ROOT

VOl

SAVRG

Down-tree references to the global symbol ROOT are made from modules
OVRl, OVR2, OVR3, and OVR4.
These references are resolved directly.
The segment cross-reference shows the segment name and modules in each
overlay.

4.5

USE AND SIZE OF OVERLAY RUNTIME ROUTINES

TKB, when constructing an overlaid task, incorporates certain modules
from the system library to perform the actual overlay operations. An
overlay run-time routine in the task·loads overlays from disk or maps
resident overlays by issuing QIO$ or CRAW$ directives.
The modules and routines described below implement
mechanism as described in Section 4.1.

the

TKB

autoload

There are three major components to the autoload service, as follows:
AUTO

This module controls the overlay process, and the
autoload vecors indirectly call AUTO through .NAUTO.
AUTO determines whether the referenced overlay segment
is already in memory or mappede
It then jumps to the
required entry point if the entry point is available.
The AUTO module is supplied in two variations.
These
variations
are
separately named and described as
follows:
AUTO

Selected by TKB by default for all overlaid
tasks.
It manages disk-only, PLAS, and cluster
library overlay structures.

AUT OT

Manually selected by you by using an explicit
reference in the TKB .ODL file, as shown below.
This module disables the AST
traps
while
manipulating the overlay data structures. This
is required where user task AST traps might
cause modification of the overlay database. To
incorporate this module in your task image, you

4-14

OVERLAY LOADING METHODS
must include the following element in the
factor of the task's ODL file:

.ROOT

-LB:[l,l]SYSLIB/LB:AUTOTIn addition to including AUTOT in the .ROOT
factor,
the following code must be included in
your task as initialization prior to the AST
handling routines in your task:
MOV @:fl:.NOVPT,RO
BISB i200,N.FAST(RO)
MRKS

This routine traverses the overlay descriptor data
structure to mark any overlay segment that will be
displaced by a new overlay as "out of memory" and
consequently not available.

RDSG

The AUTO module calls the RDSG routine repeatedly to
read or map each segment along the overlay tree path
into the task's virtual address space.
This is referred
to as "path loading." When path loading is completed,
AUTO calls the required entry point.

Several versions of each component exist reflecting the various sizes
as appropriate for tasks having disk-only overlays, PLAS mapped
overlays, and/or cluster libraries.
TKB incorporates the smallest
support routines appropriate for the overlay structure of your task.
Depending on whether your task has disk-only overlays,
resident
overlays, or cluster libraries, TKB forces one of the following
modules into your task:
OVCTL
,;·;.~f:li~;r

Contain the MRKS and RDSG routines optimized for disk
overlays
only.
No
support
is
included
for
memory-resident or cluster overlays.
OVCTL is the
module incl.uded for convent.ional tasks, and fOV':C·J;)wr.·i.s·· the
~rm·
,,'.iric?·~ed,,';:'f·~itm:.+'·iancf::n;r.sna'c(:{r:..ask'$·:
? }!/:~.!'f'/; .;;'
~~~42 i~~
~> «;. <~~
~«; j ; ~/t'! ~·; '·~ ~; ~ ~·, / :'
<m

OVCTR
'n,;'.
'1•

;~;

.:·~.

OVCTC

·W

,j.;,

)";-

:;'>'

•••••••••

••

,•.,

Contain MRKS and RDSG routines assembled for disk and
memory resident overlays. TKB selects either of these
modules
if
the
task
overlay structure includes
memory-resident overlays or maps a
resident library
containing resident overlays.
OVCTR is the module
sei,ected ~or corwentional tasks·. ~n~ 3'.rj~~/d'f'etl,aj.d{·I.~' ·:')~1nq
·~~pa
.r·tas·k'~~ · ,.· .oytDR<".: i~s ·; .·t:n~·: :m.ocfole·: .:»is~·te'ctted<" ?iqi

:·'i,' if;N'

;o,.v:+;D(;

« ."'-#; .:;',;

/¥/:::'~~~: .:D~i.~a.'9~./t~~Ks,:;·: ......, .· .·.

. . . . . , ... .

Contain the MRKS, RDSG, and cluster library support
routines.
TKB includes OVCTC or OVIDC if cluster
libraries are included in your task.
OVCTC is the
module selected for conventional tasks and no.n~'overlaid
· 1~ · iand: t>-<~pace task's.· ·ov!oc ls the module select·ed· for
ove·rla~d ;r:- 'and' D...:,s;pace·',tasks •.

4-15

OVERLAY LOADING METHODS
Two other modules are incorporated into your task's image.

They are:

OVDAT

A small, impure data area used by AUTO, MRKS, and RDSG
routines.
TKB includes OVDAT in all overlaid tasks, and
its size is independent of the overlay structure of that
task.

ALERR

An error service module that AUTO invokes under
the following circumstances:

one

•

If an I/O error occurs while
disk overlay into memory

read

•

If a directive
attach or map
overlays

attempting

error occurs while attempting to
a
region containing memory resident

Table 4-1 compares the sizes of the overlay run-time support modules.
You can use it to determine when it is appropriate to force certain
variants into your task image.
Table 4-1
Comparison of Overlay Run-Time Module Sizes

Module

Program
Section

Number
of Bytes
Oct/Dec

Specific Use

One of the following modules is included in any overlaid task
that uses autoload and in any task that links to a PLAS overlaid
resident library.
AUTO

$$AUTO

122/82.

All tasks that use autoload

AU TOT

$$AUTO
$$RTQ
$$RTR

132/90.
32/26.
30/24.

All tasks with ASTs
disabled during autoload

One of the following modules
is
included
in any overlaid
conventional
task.
OVCTR
or OVCTC is
included in any
non-overlaid task (conventional or I- and D- space}
that links
to a PLAS overlaid resident library.
OVCTL

$$MRKS
$$RDSG
$$POLS

76/62.
160/112.
2/2.

Disk overlays only

OVCTR

$$MRKS
$$RDSG
$$POLS

234/156.
332/218.
12/10.

Disk and PLAS overlays with no
cluster libraries

OVCTC

$$MRKS
$$RDSG
$$POLS

254/172.
352/234.
120/80.

Disk and PLAS overlays
with cluster libraries
(continued on next page)

4-16

OVERLAY LOADING METHODS

Table 4-1 (Cont.}
Comparison of Overlay Run-Time Module Sizes

Module

Number
of Bytes
Oct/Dec

Program
Section

Specific use

one' of. t::he.: toi,'iowing·:· :th~ee· ·m.o.a·u'Ies H> included fo.
··f~· .:and· D.S·sp;ac~· task,~

,, .:' '..', ·

, '
,

$,$MRK$.
,, )76/6'2,.,
$$RDSG · < 2~4/14:8 .•.

·.·$$POLS · ... ' ;2,{2'~

<·

'..
,.

}

'Disk. over;t.ays :9p];y"

.·

$~~~~s .:3;;;J.96:, ·•.. i}I;k.. ,,,;"a i>LAS: Qve~ia~ '

:.:
."$.$Ros~:· . ·,,
,.·:· $$PE>.LS. · •
,.::~

502/32 :;L~. :" · . .w.u:·h /rio. «::iu:sl:e.r···.:itbrar.'.t:e·~ . .
0

12/i'o:.·'.
.· /, ·.· ,' ·
.>:: , .. '. ,'
~

*·

'.o~rDc.; .: .: . . r:;$:$:~R;~s·. ·.: 32Lt:2ii~
r :· ;

;

·./.:·.·. : ·. . .:·::/;' ::;,
;

"iif~1$:.·::~ri~{ .:~l~$:.·'.c},ye. t.:.J:a'¥$:.'..

'.$$'RDSG : .s·22:;/.3 3S·~·
wLth:· o'l uster. Tibr:ar.·ies'
"·$,.$.:'~[)LS,
1:2:0/80 io:' / · . :
•
· • • ·
«< .;· ·

The overlay data vector OVDAT is included in any overlaid task
and in any task that links to a PLAS overlaid resident library.
OVDAT

$$0VDT
$$SGDO
$$SGD2
$$RTQ
$$RTR
$$RTS

24/20.
0/0.
2/2.
0/0.
0/0.
2/2.

Included in all tasks
that perform overlay
operations

The overlay error service routine
OVDAT is included.
ALERR

$$ALER

24/20.

ALERR

$$LOAD
$$AUTO

252/170.
14/12.

included

whenever

Overlay error

Manual overlay control (LOAD) is used in
routine.
(See Section 4.2, Manual Load.}
LOAD

place

Manual overlay control

4-17

any

AUTO

CHAPTER 5

SHARED REGION CONCEPTS AND EXAMPLES

The Task Builder provides you with many ways of using shared regions
for tailoring your tasks to meet your specific requirements.
This
chapter describes some of these facilities and their applications.
This chapter contains five working examples. The discussion of the
examples assumes that you are familiar with the programming concepts
described in the RSX-llM/M-PLUS Guide to Program Development and with
the first four chapters of this manual-.-

5.1

SHARED REGIONS DEFINED

A shared region is a block of data or code that resides in memory and
can be used by any number of tasks. A shared region can contain data
for use by several tasks or it may be an area where one task writes
data for use by another task.
Also, a shared region can contain
routines for use by several tasks.
Shared regions are useful because they make more efficient
physical memory.
The two kinds of shared regions are:

use

•

A resident common that provides a way that two or
can share their data

tasks

•

A resident library that provides a way that two or more
can share a single copy of commonly used subroutines

tasks

The term "resident" denotes a shared region that is built and
installed into the system separately from the task that links to it.
In other words, you use TKB to build a shared region much as you would
use it to build a task. However, the region does not have a header or
a stack. Also, you can use switches to designate the kind of shared
region (a library or a common) to be built.
Figure 5-1 shows a typical resident common.
Task A stores some
results in resident common S, and Task B retrieves the data from the
common gt a later time.
Figure 5-2 shows a typical resident library.
In this case, common
reentrant subroutines are not included in each task image;
instead, a
single copy is shared by all tasks.

5-1

SHARED REGION CONCEPTS AND EXAMPLES

RESIDENT COMMON

TASK A

TASK B

EXECUTIVE

PHYSICAL MEMORY
TIME 1

PHYSICAL MEMORY
TIME 2
ZK-418-81

Figure 5-1

Typical Resident Common

When you build a shared region, you must specify an output image file
name for the region in the TKB command sequence. But, because a
shared region is not an executable unit, it is not a task, and does
not require a header or a stack area. Therefore, when you build a
shared region, you always attach the negated header switch (/-HD)
to
the region's image file specification.
This switch tells TKB to
suppress the header within the image. To suppress the stack area in
the Task Builder command sequence during option input, you specify
STACK=O.
(Refer to Chapters 10 and 11 for a complete description of
the /HD switch, the STACK option, and other switches and options.)
In either an RSX-llM or RSX-llM-PLUS system, when you build a shared
region, you use the PAR option to name the partition in which the
region is to reside. You specify the partition name in the TKB
command sequence during option input.
(Refer to Chapter 11 for a
description of the PAR option~) I1f an RSX'":'"llM system,. the partition
named· in the PAR option ·must previously exist when the.common is
installed. . It n~ed, not exist wh.en the: co;mmon •·is .being b.ui1;,;t '. by TKB.
In .an RSX-llMWP):.US .~yst.e:m, the .partitic.>n n~unea· in· the J?AR :option need
·,not .pr~viousl;{ exist·, .. but:. the :actual pa.rti:tion (le"faults . to, GEN.- · on
both systems, the name used in the PAR option must be the same name as
that of the region.
In. an RSX-llM system,·· a shared region ·must · teside in its·· own
partition.:
'.fherefore, when ·you generate . y9ur system·, you must
consider the physical memory requirements, in' terms of parfitions, for
any shared regions that you expect to reside within your system. If
you do not consider these require~ents . at system generation ti~e,
later I When YOU build a Shared region, YOU Will be forced, to 90 back
and create a common partition for the region.

5-2

SHARED REGION CONCEPTS AND EXAMPLES

RESIDENT LIBRARY
CONTAINING
ROUTINE R

ROUTINE R
TASK A
ROUTINE R

TASK A

TASK B

PART!T!ON BOUNDARY - - - - - - - - - -

EXECUTIVE

NONSHARED
PHYSICAL MEMORY

SHARED
PHYSICAL MEMORY
ZK-419-81

Typical Resident Library

Figure 5-2

..'.~;r:~:·•.?P.::···¥~:x;'~i;.i.~·;·.~.t. ~·~··,·~~·s·it·.~~.:':···.~s.~.~E~!1.· .:i;.~9,;i:~9~·~:·99,:.··~~J:,..:n:~{V;~:A<? •. ~·/=:€7·~·•¥·~·~·. ;;.~it·~·~.i:q
part1 t:.1.on,s , o.t: ·· t:hei'r,

.pwn; · ·you, .·ca•o

.:install ·a., pbared. reg1,0Il' 1n any .

;·ea·rt;itJot} 1·/latge /·'enougfi:
to· hold,· !i'~··~,:·' ·.;r,n; ·f.act,1 ·.the'· ·1Pa.:i:ti7bion. f.or ,··. wh:ich'.'
~ n~;:
~i.~.d:····': ': l;~gJ:oti1'.:.·'./'w~:s:. :'titi,:i,l•t'~.··a.<?~s. ·'. n.~.~·,,;:'~ ~.'V~;.·~t.9,:··.·~.·x··i.~:t:. ··J;n:':'.t:6.~::· .. ~il~·~.err\:'.. ·.~%,~:' . :
:.tb~· .... time. 1.:th.e· . sh~re,i-F.,~~9.ioh . 1'is.· :ins:tal:l~d:• . ' .· .T<hen'i ·.i;t f.~llo.ws .. ·tp:pt.· a:.:· ·T·K~.· .·

'.:in

:...

••

.~:~2::;i~r:~~1~;~~~i~~~i;1~~~1Elffi;[~~4~1i~f·:
'l;ii;;tx6~:~.s'o+k2/h1.~t~}J,;"s :· ~·t ,.:"rnrtfiJ:?·'· ·G;EJN.Y,jp~'rti1d.~n '~ri~: a:'i:'sp,:19¥$: ·t;ae/,::ft:>'1'.h<J>w~ ng: .: ,;

.~:,a~.~::~j·~~1'..-J.7~7:~~~:·,Y·.,.·:~~'.·· lJ)I:././'-.Z:/X·f/fF . !.HZ ·/t' .....
.·" :"' '."' "'.'tNp;~''..;-/i>!;~dij;3r'1·pN/p.i:i'£tia~~' :NOT; :1·rr'.:·$ysfr:E'M, 7tiEFl\U;LT'r:N(f,

i;>

<N'

.~ ~' \;i -~ .. ;~

XI<,,

>.,

,t' }' ',· ;

> }

,:~> :~>.;> ,.f } ::.'''; -</~

l:i' ,.,:·

}

·('·\

, .~-,., ,.'~ ~ .;:·> , :
"ii

';>\:

,->!> ,,, > '.:

,'>

> ->

~ <> t; ,,: ~
,

.i.;

).:~/' >;~~,
«'.·

_.,,''. '•• :'

•

;

·\i:E.~{'
/

<>, !_">;

Also, you should consider three switches when you build the region.
The /PI switch determines whether the region is relocatable. You can
use the /CO switch in the -'f'K'B command sequence to declare a region as
a shared common. The /CO switch specifies the use of the region as a
shared common rather than as a shared library. Alternatively, you can
use the /LI switch when you build the region to declare the region as
a shared library.
Using these three switches affects the contents of
the symbol definition file, which is described in Chapter 10 under the
/CO, /LI, and /PI switch headings.
See also Figure 5-3,
Interaction
of the /LI, /CO, and /PI Switches.
The contents of the symbol
definition file is described in the following sections.

5-3

SHARED REGION CONCEPTS AND EXAMPLES
5.1.1

The Symbol Definition File

When you build a shared region, you must specify a symbol definition
(.STB)
file in the TKB command sequence.
This file contains linkage
information about the region.
(The format at a .STB file as input to
TKB is the same as that of a .OBJ file.
See Appendix A.) Later, when
you build a task that links to the region, TKB uses this .STB file to
resolve calls from within the referencing task to locations within the
region.
The /PI switch declares a shared region
to
be
relocatable.
Conversely,
the /-PI switch declares a shared region to be absolute.
If you specify the /PI switch without the /CO or /LI switches to
indicate a relocatable region, TKB defaults to building relocatable
(position-independent)
shared regions with all program
sections
declared in the
.STB file.
TKB also defaults to building absolute
(position-dependent) shared regions with only the
• ABS.
program
section declared in the .STB file.
The contents of the .STB file when
these three switches are used are described in Chapter 10 under the
/CO, /LI, and /PI switch headings.
See also Figure 5-3, Interaction
of the /LI, /CO, and /PI Switches.

SWITCH
SPECIFIED
WITH /-HD

SHARED REGION
ABSOLUTE

RELOCATABLE

REGION PSECT
NAME

.STB FILE
PSECT

.STB FILE
SYMBOLS

ONE PSECT
RELOCATABLE

ALL SYMBOLS.
RELATIVE TO
START OF THE
PSECT

/Pl/LI

YES

SAME AS LIBRARY
ROOT

/Pl/CO

YES

ALL DECLARED
PSECT NAMES
INCLUDED

ALL DECLARED
PSECTS
RELOCATABLE

ALL PSECTS
AND SYMBOLS

/-Pl/LI*

YES

.ABS

ONE PSECT
ABSOLUTE

ALL SYMBOLS
ABSOLUTE

/-Pl/CO*

YES

ALL DECLARED
PSECT NAMES
INCLUDED

ALL DECLARED
PSECTS
ABSOLUTE

ALL SYMBOLS
ABSOLUTE

SAME AS /Pl/CO

YES

/Pl

/-Pl*

YES

NONE

YES

SAME AS /-Pl/LI

*/-Pl is the default of not using /Pl
ZK-420-81

Figure 5-3

Interaction of the /LI, /CO, and /PI Switches

5-4

SHARED REGION CONCEPTS AND EXAMPLES
If you do not use either /CO or /LI, the contents of an .STB file for
a shared region depend on the use of the /PI switch, which determines
whether the region is absolute or relocatable.
The effects of
declaring a shared region relocatable or absolute and the resulting
contents of the .STB file are described in the following sections.
Some .STB files include an entry in the .STB file for each program
section in the region.
Each entry declares the program section's
name, attributes, and length.
In addition, TKB includes in the .STB
file every symbol in the shared region and its value relative to the
beginning of the section in which it resides.

5.1.2

Position-Independent Shared Regions

A position-independent shared region can be placed anywhere in a
referencing task's virtual address space when the system on which the
task runs has memory management hardware.

5.1.2.1 Position-Independent Shared Region Mapping - In the example
of using the memory management APRs, shown in Figure 5-4, two tasks
refer to the shared region S:
task A and task B. The shared region S
is 4K words long and therefore requires that much space in the virtual
address space of both tasks.
Task A is 6K words long and requires two
APRs
(APRO and APRl) to map its task region. The first APR available
to map the shared region is APR 2. Thus, you can specify APR 2 when
task A is built.
Task B is 16.5K words long.
It requires five APRs to map its task
region.
The first APR available to map the shared region S in task B
is APR 5. Therefore, you can specify APR 5 when task B is built.
If you do not specify which APR is to be used
to
map
a
position-independent shared region, TKB selects the highest set of
APRs available in the referencing task's virtual address space.
In
Figure 5-4, for example, if APR 2 in task A and APR 5 in task B had
not been selected at task-build time, TKB would have selected APR 7 in
both cases.

5.1.2.2 Specifying a Position-Independent Region - You specify that a
shared region is position independent when you build it by attaching
the /PI switch to the image file specification for the region.
(Refer
to Chapter 10 for a description of the /PI switch.)
You should declare a region position independent if:
region contains code that
• The
regardless of its location in

execute
correctly
will
the address space of the

referencing task.
•

The region contains data that is not address dependent.

•

The region contains data that will be referenced by a
program (such data must reside in a named common) •

5-5

FORTRAN

SHARED REGION CONCEPTS AND EXAMPLES

4 K WORDS

SHARED
REGION

APR 7-

APR 6-

APR 6SHARED
REGION

APR 5-

APR 4-·

APR 4-

APR 3-

APR 3SHARED
REGION

TASK B

APR 2-

16.5 K
WORDS

APR 2-

APR 1TASK A

APR 0-

APR 1-

6 K WORDS

APR 0-

1-1
ZK-421-81

Figure 5-4

Specifying APRs for a Position-Independent Shared Region

5-6

SHARED REGION CONCEPTS AND EXAMPLES
Program section names are preserved in some shared regions.
All the
following switch combinations produce shared regions in which PSECT
names are preserved:
/PI/CO, /-PI/CO, and /PI
Therefore, you should observe the following precautions when
and referring to these regions:

building

•

No code or data in the region should be included in the
(. BLK.) program section.

blank

•

No code or data in a referencing task should appear in a
program section of the same name as a program section in the
shared region.

order in which memory is
• The
(alphabetic or sequential)

allocated to program sections
must be the same for the shared
its referencing tasks.
(Chapter 2 describes
region and
alphabetic
ordering of program sections.
Refer to the
description of the /SQ and /SG switches in Chapter 10 for an
explanation of sequential ordering of program sections.)

5.1.3

Absolute Shared Regions

When a shared region is absolute, you select the virtual addresses for
it when you build it. Thus, an absolute shared region is fixed in the
virtual address space of all tasks that refer to it.

5.1.3.1 Absolute Shared Region Mapping - Figure 5-5 shows three tasks
(task C,
task D, and task E) and a single absolute shared region, L.
The absolute shared region L is 6K words long and is built to occupy
virtual addresses 120000(octal)
to 150000(octal). These addresses
correspond to APR 5 and APR 6, respectively.
Tasks C and D can be
linked to region L because at the time they are built APR 5 and APR 6
are unused in both tasks.
However, task E is 23K words long and even
though it has SK words of virtual address space available to map the
shared region, APR 5 (which corresponds to virtual address 120000, the
base address of the shared region) has been allocated to the task
region.
If shared region L were position independent, task E could be
linked to it.

5.1.3.2 Specifying an Absolute Shared Region - You specify that a
shared region is absolute when you build it by using the /-PI switch
or omitting the /PI switch from the task image file.
You establish
the virtual address for the region by specifying the base address of
the region as a parameter of the PAR option.
You should build an absolute shared region if:
•

The region contains code that must appear
in a
location in the address space of a referencing task.

•

The region contains data that is address dependent.
The region contains program sections
program sections in referencing tasks.

5-7

same

specific

name

SHARED REGION CONCEPTS AND EXAMPLES

6 K WORDS

ABSOLUTE
SHARED
REGION
L

VIRTUALL
120000
-------

APR 7-

APR 6-

ABSOLUTE
SHARED
REGION
L

APR 7-

ABSOLUTE
SHARED
REGION
L

APR 6-

APR 5-

APR 4-

APR 3-

APR 2-

APR 1-

APR 0-

I
APRO-

TASK c

TASK D

APR 2-

L___J

TASK E

LJ
ZK-422-81

Figure 5-5

Mapping for an Absolute Shared Region

5-8

SHARED REGION CONCEPTS AND EXAMPLES
5.1.3.3 Absolute Shared Region .STB File - When a shared region is
created with the /-PI/LI or /-PI switches, or just the /-HD switch,
the only program section name that appears in the .STB file for the
region is the absolute program section name (. ABS.).
TKB includes in
the .STB file for the region each symbol in the region and its value.
But, because TKB does not include the program section names of an
absolute shared region in its .STB file, all code or data in the
region must be referred to by global symbol name. Also, because the
program section names are not in the
.STB file,
TKB places no
restrictions on the way the program sections are ordered in either the
absolute shared region or the tasks that reference it. You can order
program sections the way you want by using the /SQ and /SG switches
described in Chapter 10.

5.1.4

Shared Regions with Memory-Resident Overlays

Shared regions with memory-resident overlays are a primary resource
for conserving memory.
If the shared region is larger than the
available virtual address space in a task that must reference the
region, you can build the region -- both position-independent and
absolute -- with memory-resident overlays.
All segments of the
overlay structure are included in the shared region, but each task
referencing the shared region can include only part of the shared
region
that is, an overlay segment or series of segments in an
overlay path -- in its virtual address space.
Therefore, the task
need only have enough virtual address space for the largest shared
region overlay segment, or series of segments in an overlay path,
it
is likely to access. Hence, the virtual address space of the task can
be considerably smaller than the size of the shared region.

5.1.4.1 Considerations About Building an Overlaid Shared Region - In
general, overlays can be disk-resident or memory-resident, but those
in shared regions must, by their very nature, be memory-resident. TKB
marks each overlay segment in the shared region with the NODSK
attribute to suppress overlay load requests. When you build a shared
region with memory-resident overlays, you must define the overlay
structure through a conventional ODL file.
(See Chapters 3 and 4 of
this manual for
information on overlays and the Overlay Description
Language.) TKB does not include the overlay data base
(segment
descriptors, autoload vectors, and so forth) or the overlay run-time
routines within the region image.
Instead, this data base becomes a
part of the .STB file that is linked to the referencing task. When
this task is built, its root segment automatically includes both the
data base and global references to overlay support routines residing
in the system object module library.
The procedure for creating a shared
overlays can be summarized as follows:

region

with

memory-resident

containing

only

memory-resident

•

Define an overlay structure
overlays.

•

Include the GLBREF option, or provide in the root segment a
module
containing the appropriate global references for
defining entry points within those overlay segments~
TKB
generates autoload vectors and global definitions for the
overlay segments.

5-9

SHARED REGION CONCEPTS AND EXAMPLES
5.1.4.2 Example of Building a Memory-Resident Overlaid Shared Region
- The procedure for creating a shared region is illustrated in the
following example.
The shared region to be contructed consists of
reentrant code that resides within the overlay structure defined
below:
.ROOT A-!(B,C-0)
.NAME A
.END
Root segment A contains no code or data and has a length of O.
All
executable
code
exists within memory-resident overlay segments
composed of object modules B.OBJ, C.OBJ, and D.OBJ, containing global
entry points B, C, and D, respectively.
You generate the .TSK,
commands:

.MAP, and .STB files by using the following TKB

TKB>A/-HD/MM,LP:,SY:A=A/MP
Enter Options:
TKB>GBLREF=B,C,D
TKB>PAR=A:l60000:20000
TKB>STACK=O
TKB>/
NOTE
When building a shared region, you must
use the same name for the partition and
the .TSK and .STB files.
See the PAR, RESLIB, LIBR,
RESCOM,
COMMON options in Chapter 11.

and

TKB inserts references to entry points B, C, and D in the root segment
of the library which subsequently appear
in the
.STB file as
definitions.
TKB resolves the definitions for symbol C directly to the actual entry
point.
TKB resolves the definitions for symbols B and D to autoload
vectors that it includes in each referencing task.

5.1.4.3 Options for Use in Overlaid Shared Regions - Certain options
may prove useful to you when building and linking shared regions to a
task.
They are described next.
GBLDEF -- You can declare tne definition of a symbol by means
GBLDEF option.
The syntax of this option is:

the

GBLDEF= symbol-name:symbol-value
where symbol-name is a 1- to 6- character Radix-50 name of the defined
symbol and symbol-value is an octal number in the range of 0 through
177777 assigned to the symbol~
This option is frequently used in the
TKB build file for a task or shared region to allow you to alter the
value of a global symbol that resides in a module.
This saves you the
trouble of reassembling the source code for a module if changes are
necessary.

5-10

SHARED REGION CONCEPTS AND EXAMPLES
GBLINC -- By means of this option, you force TKB to include the
specified symbols in the .STB file being created by the linking
process in which this option appears.
The syntax of this option is:
GBLINC=syrnbol-name,syrnbol-name, ••• ,symbol-name
where symbol-name is the symbol or symbols to be included.
Use this
option when you want to force particular modules to be linked to the
task that references this library.
The global symbol references
specified by this option must be satisfied by some module or GBLDEF
specification when you build the task.
GLBREF -- You can force the inclusion of a global reference in the
root segment of the shared region by means of the GBLREF option.
In
this way, the necessary autoload vectors and definitions can be
generated without explicitly including such references in an object
module. The syntax of the option is:
GBLREF=[,name[,name ••• ]]
where the name consists of from one to six Radix-50 characters.
If
the definition resides within an autoloadable segment, TKB constructs
an autoload vector and includes it in the symbol definition file.
If
the definition is not autoloadable, TKB obtains the real value and
defines it in the root segment. No global symbol appears in the
.STB
file unless the symbol is either defined in the root segment or is
referenced in the root segment and defined elsewhere in the overlay
structure.
GBLXCL -- You can exclude a symbol or symbols from the symbol
definition file of a shared region by means of the GBLXCL option. The
syntax of this option is:
GBLXCL=symbol-name,symbol-name, ••• ,symbol-name
where symbol-name is the symbol or symbols to be excluded.
You can
use this option when you do not want the task to be aware of specific
symbols within the library. This option is particularly useful when
you cluster overlaid libraries together
(see the CLSTR option in
Chapter 11 and the Cluster Libraries section in this chapter).

5.1.4.4 Autoload Vectors and .STB Files for Overlaid Shared Regions When TKB builds a task image file containing memory-resident overlays,
TKB allocates autoload vectors in the task image.
If the task links
to a shared region, autoload vectors for the shared region are also
allocated in the task image. TKB allocates the autoload vectors in
the task's root segment, but not in the shared region.
Therefore, the
shared region cannot reference unloaded
(unmapped)
segments of its
overlay structure.
When the task executes, the shared region is effectively part of the
task.
In fact,
when the task loads overlay segments, it makes no
distinction between overlay segments of the task and those of the
shared region.
They are loaded as needed in a procedure that is
transparent insofar as the execution of the task is concerned.
For the Fast Task Builder (FTB) and older versions of TKB that do not
support overlaid I- and D-space tasks, each autoload vector in the
shared region's .STB file is allocated in the root of the task being
linked to the region, whether or not the entry point is referenced by
the task.

5-11

SHARED REGION CONCEPTS AND EXAMPLES

Howeve,r 1 if you use a version of TKB that supports overlpid, I..;., and
D-space tasks .and the library was ,built with one of ,these versiohs,,.,
TKB allocCates autoload vectors in the root of the task' .only for those
a:utoloadable entry poin'ts in the lib'.[ary. that the task, referenc~s .•
The .STB file contains ISO records . that , ailow . TKB. to
,:c'reate,.
dynami:ca,lly . auto load vectors when 1 inking the. t:a.sk to' "the. 'U:br'a1ry .. :
'l';Kit t~·no;res .th1: autoload· yector.s in 'the [.STB file i.f the . <isp.' r.eco.'rd~g,·
·are pr,esent •..· The:refore; tasks that link to o,verlaid. s;ha.r:ed ;r:e9i:on.s,
a'nd thatxare bu'il.t with newer versions· o:f·TKB tend ,to be : ~m.aH~r: Q,pd.
U:se . le.ss .. ·v.irtual · .add'ress space than ~hose .that are b,ui:'.l?t.:
FTIJ,:o'r;·
old~:r·· ~ve.r.ston~ of TKB.
·
·
· · ·· · , ·' ;· ·,,.
4

'bN.

NOTE
Libraries created with older versions of
TKB do not have the ISD records in the
.STB file that newer versions of TKB use
to include autoload vectors in the task
from the .STB file. Therefore, TKB must
create autoload vectors for every entry
point in the library.
If .Y:ou a.re using one ·o,f . these older
:libr[aries: a.nd y;ou are liinking an I- and'
D-sp:ace task to it:, TKB ,will give yQ,u
the ,fatal err.or message:

"Mcxfole
modu'.le-n'a!ne
cont'ains'
incompatible aut,oldad vedtor~s .. "
I

Th.i;s, mess·age occurs because the .. STB
f ilel
contains
conven~ional
autoload"
vectors that are qot usable by an ·I~ and
o-space task.
Only those global symbols defined or referenced in the root segment of
the shared region appear in the .STB file.
The .STB file also
contains the data base required by the overlay run-time system in
relocatable object module format. This data base includes:
•

All autoload vectors

•

Segment tables (linked as described in Appendix B)

•

Window descriptors

•

A single region descriptor

The overlay structure, as reflected in the segment table linkage, is
preserved and conveyed to the referencing task by the .STB file.
Thus, path loading for the shared region can occur exactly as it does
within a task.
Aside from address space restrictions, there are no
limitations on the overlay structures that can be defined for a shared
region.

5-12

SHARED REGION CONCEPTS AND EXAMPLES
Run-Time Support for Overlaid Shared Regions

5.1.5

Memory-resident overlays within a shared region require
little
additional support from the overlay run-time system. The shared
region overlay data base that is linked within the image of the
referencing task has a structure that is identical to the equivalent
data created- for an overlaid task.
Therefore,
memory-resident
overlays
within
the
shared region are indistinguishable from
memory-resident overlays that form a part of the task image.
The only
additional processing is that required to attach the shared region and
obtain its identification for use by the mapping directives.
Once this
identical
overlays.

initialization is complete, all further processing is
to memory-resident overlay processing performed on task

Several
restrictions
apply
memory-resident overlays:

shared

regions

existing

•

A shared region cannot use the autoload facility to reference
memory-resident overlays within itself or any other region.
If each segment is uniquely named, overlays can be mapped
through the manual load facility.

•

Named program sections in a shared region overlay segment
cannot be referenced by the task.
If reference to the storage
is required, such sections must be included in the root
segment of the region (with resultant loss of virtual address
space).

•

For FTB, and libraries built with versions of TKB that do not
support I- and D-space overlaid tasks, the number of autoload
vectors is independent of
the
entry
points
actually
referenced.
The maximum number of vectors will be allocated
within each referencing task.
In some cases the size of the
allocation will be large.

•

There is an overhead of six instructions
even _when the seg~-e~t i s m~pped ~ ___ ,_

,~~,~~~~~<::~;i;~~~~/i~~~r~:~/.t?Y/1~;~~~· · -~'~'.-i~~/;eyi·/:t~il. ___ . :-----L.J:::u:>J"""'·:·
As implied by the previous items, great care must be exercised if an
efficient memory-resident overlay structure for library routines such
as the FORTRAN IV OTS is to be implemented.

Linking to a Shared Region

5.1.6

When you build a task that links to a shared region, you must indicate
to TKB the name of the shared region and the type of access the task
requires to it (read/write or read-only).
In addition, if the shared
region is position independent, you can specify which APR TKB is to
allocate for mapping the region into the task's virtual address space.
Four options are available for this action:
•

RESLIB (resident library)

•

RESCOM (resident common)

•

LIBR (system-owned resident library)

•

COMMON (system-owned resident common)

5-13

SHARED REGION CONCEPTS AND EXAMPLES
RESLIB and RESCOM accept a complete file specification as one of their
arguments.
Thus, you can specify a device and UFO indicating to TKB
the location of the region's image file and, by implication, its
symbol definition file.
(Refer to Chapter 1 for more information on
file specifications and defaults.)
LIBR and COMMON accept a 1- to 6-character name.
When you specify
either of these options, the shared region's image file and symbol
definition file must reside under UFO [l,l] on device LBO:.
The RESLIB and RESCOM options require that all users of the shared
region know the UFO under which the shared region's image file and
.STB file reside. The LIBR and COMMON options require only that the
users of the shared region know the name of the shared region. When
you specify either LIBR or COMMON, by default, TKB expects to find the
shared region's image and .STB files on device LB: under UFO [1,1].
All four options accept two additional arguments:
•

The type of access that the task requires (RO or RW).

•

The first APR that TKB is to allocate for mapping the region
into the task's virtual address space. As stated earlier,
this argument is valid only when the shared region is position
independent.

When you specify any of these options, TKB expects to find a symbol
definition file of the same name as that of the shared region, but
with an extension of .STB, on the same device and under the same UFO
as those of the shared region's image file.
The syntax of these options is given in Chapter 11.
When TKB builds a task, it processes first any options that appear in
the TKB command sequence. When TKB processes one of the four options
above, it locates the disk image of the shared region named in the
option. The disk image of a shared region does not have a header, but
it does have a label block that contains the allocation information
about the shared region (for example, its base address, load size, and
the name of the partition for which it was built). TKB extracts this
data from the shared region's label block and places it in the LIBRARY
REQUEST section of the label block for the referencing task.
The .STB file associated with the shared region is an object module
file.
TKB processes it as an input file. If the shared region is
position independent, its .STB file contains program section names,
attributes, and lengths.
However, the program section names are
flagged within the file as "library" program sections and TKB does not
add their allocations to the task image it is building.
If the task links to only one shared region, and if neither the shared
region nor the task that links to it contain memory-resident overlays,
the Task Builder allocates two window blocks in the header of the
task.
(Overlays are described in Chapter 3.) When the task is
installed, the INSTALL processor will initialize these window blocks
as follows:
•

Window block 0 will describe the range
{the window) for the task region.

virtual

addresses

•

Window block 1 will describe the window for the shared region.

Figure 5-6 shows the window-to-region relationship of such a task.

5-14

SHARED REGION CONCEPTS AND EXAMPLES

HIGHEST VIRTUAL------.ADDRESS

SHARED
REGION

WINDOW BLOCK

1
WINDOW BLOCK

TASK
MEMORY

HEADER AND STACK
LOWEST VIRTUAL-----~
ADDRESS

Figure 5-6

ZK-423-81

Windows for Shared Region and Referencing Task

5-15

SHARED REGION CONCEPTS AND EXAMPLES
A shared region need not be installed before a task that links to it
is built.
The
.STB file that you specify when you build the shared
region contains all the information required by TKB to resolve
references from within a task to locations within the shared region.
The only requirement is that you install a shared region before you
install a task that links to it.
Unless you use the /LI switch, there is a restriction on the way TKB
processes tasks that link to relocatable shared regions.
TKB places
all program section names into its
internal control section table.
The program section names include those from the .STB file of the
shared region as well as those from the other
input modules.
A
conflict can arise when building a task that contains program sections
of the same name as those in the shared region to which the task
links.
The conflict arises because TKB tries to add the program
section allocation in the task to the already existing allocation for
the program section of the same name in the region.
This is not
possible because the region's image has already been built, is outside
the address space of the task currently being built, and cannot be
modified.
Therefore, to avoid this conflict,
the program section
names within a
task that links to a relocatable shared region must
normally be unique with respect to program section names within the
shared region.
TKB displays an error message under the following conditions:
•

A program section in the task and a
shared region have the same name.

program

section

•

The program section in the task contains data.

•

TKB tries to initialize the program section in the task.

the

The error message occurs when TKB tries to store data in an image
outside the address limits of the task it is building.
If this
conflict occurs, TKB prints the following message:
TKB--*DIAG*-load addr out of range in module module-name
One exception to the above
following conditions exist:

restriction

develops

when

all

the

(in the shared region and
in the
program sections
• Both
referencing task)
have the
(D)
data and the OVR (overlay)
attributes.
•

The program section in the task is equal to
the program section in the shared region.

shorter

•

The program section in the task does not contain data.

than

When all of these conditions exist, there is nothing to be initialized
within the shared region.
TKB binds the base address of the program
section in the task to the base address of the program section in the
shared region.
If the program section in the task contains global
symbols, TKB assigns addresses to them that reflect their location
relative to the beginning of the program section. You can use this
technique to establish symbolic offsets into resident
commons.
Examples 5-1 and 5-2 in the following sections illustrate how to
establish these offsets.

5-16

SHARED REGION CONCEPTS AND EXAMPLES
Number and Size of Shared Regions

5.1.7

The number of shared regions to which a task can link is a function of
the number of window blocks required to map the task and the regions.
, In .an RSX_:'llM" op,eratirig .system·, ,if a 'task is.· 4K w.otd's · .or . l~ss ~.. /al'}d ·
each: shared re.gion to .which the. task.· links .d.s,· 4I(\tlo.rds· or. less, · t.hen.
, non pr i V. i leged. t;aSk . can ac·ceSS., (jlS many. ,as.. seven' ·Sha red' .r.egions.• ,· '

a•

•

;

an.

·In·
RSX~liM;...puis operatinq system.:. if. a task· .is· 4K. words or. ''less,
·and· each shared .r.eg.ion:to·.whJch the. tas}< .Unks is '4K words o.r. ·less i a'
·I1onp:r;iyile<Jed J:as;.k cap. r.~f~·r ·t'<:>. .as ·m~.ny .as. I?· s;h?·r~~ :r;e9i.ons:!.. 7 · · fo:.
u,se.r , 'mode. ·.and. 8 'Jn .s'.upet)yi.sti~ mode;; . (S,Upe.r\d:s(;>r•m'ode i1hra'ri~s:.ar.e.
>desc.ri.bed .in Chapter
8 •. ) , ·
·
·
·
·~
~ ~: ,~
.~·
i

Example 5-1:

5.1.8

<>' '< ;·

Building and Linking to a Common in MACR0-11

The text in this section and the figures associated with it illustrate
the development of a MACR0-11 position-independent resident common and
the development of two MACR0-11 tasks that share the common.
The
steps
in building a position-independent common can be summarized as
follows:
1.

You create a source file that allocates the amount of space
required
for
the common.
In MACR0-11,
either of the
assembler directives, .BLKB or .BLKW, provide the means of
allocating this space.

You assemble the source file.

You build the assembled module, specifying both a task
file and a symbol definition file.
You specify the /-HD
(no header)
common with /CO.
You specify
independent with the /PI switch.

image

switch and declare the
the common to be position

Under options you specify:
STACK=O
PAR=parname
The parname in this PAR option is the name of the partition
in which the common is to reside.
(The /HD and /PI switches
and the STACK and PAR options are described in Chapter 10.)
If your system is an RSX-llM system, the common must reside
within a common partition of the same name as that of the
common.
If your system is an RSX-llM-PLUS system,
the common
reside within any partition large enough to hold it.

can

You install the common.

Example 5-1 below shows a MACR0-11 source file
that, when assembled
and built, creates a position-independent resident common area named
MACCOM. The common area consists of two program sections named COMl
and COM2,
respectively.
Each program section is 512(decimal) words
long.

5-17

SHARED REGION CONCEPTS AND EXAMPLES
Example 5-1, Part 1

Common Area Source File in MACR0-11
.TITLE MACCOM
COMl - 512 WORDS
COM2 - 512 WORDS

.PSECT COMl,RW,D,GBL,REL,OVR
.BLKW 512 •
• PSECT COM2,RW,D,GBL,REL,OVR
.BLKW 512 •
. END
Once this common has been assembled, the Task Builder command sequence
shown below can be used to build it.
>TKB
TKB>MACCOM/PI/-HD/CO,MACCOM/-SP,MACCOM=MACCOM
TKB>/
Enter Options:
TKB>STACK=O
TKB>PAR=MACCOM:0:4000
TKB>//
This command sequence directs TKB to build a position-independent
(/PI), headerless (/-HD) common image file named MACCOM.TSK.
It also
specifies that the Task Builder is to create a map file, MACCOM.MAP,
and a symbol definition file,
MACCOM.STB.
TKB creates all three
files -- MACCOM.TSK, MACCOM.MAP, and MACCOM.STB -- on device
SY:
under the UFO that corresponds to the terminal UIC. Because /-SP is
attached to the map file, TKB will not spool a map listing to the line
printer.
Under options, STACK=O suppresses the stack area in the common's
image.
The PAR option specifies that the common area will reside
within a common partition of the same name as that of the common,
MACCOM.
In addition, the parameters in the PAR option specify a base
of 0 and a length of 4000 octal bytes for the common.
(Refer to
Chapters 10 and 11 for descriptions of the switches and options used
in this example.)
Example 5-1,
sequence.

Part

shows

the

map

resulting

from

this

command

The task attributes section of this map reflects the switches and
options of the command string.
It indicates that the common resides
in a partition named MACCOM, that it was built under terminal UIC
[7,62], that it is headerless and position independent, and that it
requires one window block to map. The total length of the common is
1024(decimal)
words
and
its address limits range from 0 to
3777(octal). The common image (that portion of the disk image file
that eventually will be read into memory) begins at file-relative disk
block 2
The last block in the file is file-relative disk block
5 8 and the common image is four blocks long

«t .

The memory allocation synopsis details the Task Builder's allocation
for and the attributes of the program sections within the common. For
example, reading from left to right, the map indicates that the

5-18

SHARED REGION CONCEPTS AND EXAMPLES
program section COMl permits read/write access, that it contains data,
and that its scope is global.
It also indicates that COMl is
relocatable and that all contributions to COMl are to be overlaid.
Because COMl has the overlay attribute, the total allocation for it
will be equal to the largest allocation request from the modules that
contribute
to
it.
(For more information on program section
attributes, see Chapter 2.)
Continuing to the right, the first
6-digit number
is COMl's base
address, which is O ~.
The next two digits are its length (bytes) in
octal and decimal, respectively.
The next line down lists the first object module that contributes to
COMl.
In this case there is only one:
the module MACCOM from the
file MACCOM.OBJ;l.
The numbers on this line indicate the relative
base address of the contrjbution and the length of the contribution in
octal and decimal €) • If there had been more than one module input to
TKB that contained a program section named COMl, TKB would have listed
each module and its contribution in this section.
Notice that there is a program section named • BLK. shown on the map
just above the field for COMl.
This is the "blank" program section
that is created automatically by the language translators.
The
attributes shown are the default attributes.
The allocation for
• BLK.
is O because the program sections in MACCOM were explicitly
declared.
If the program sections had not been explicitiy declared,
all of the allocation for the common would have been within this
program section.
Example 5-1, Part 2
MACCOM.TSK;l

Task Builder Map for MACCOM.TSK
Page 1

Memory allocation map TKB M40.10
17-NOV-82
16:05

Partition name : MACCOM
Identification :
Task UIC
(7,62]
Task attributes: -HD,PI
Total address windows: 1.
Task image size
1024. WORDS
Task address limits: 000000 003777
R-W disk blk limits: 000002 000005 000004 00004.

*** Root segment: MACCOM 0

R/W mem limits: 000000 003777 004000 02048.
Disk blk limits: 000002 000005 000004 00004.
Memory allocation synopsis:
Title

Section
. BLK.: ( RW, I, LCL, REL ,CON) 000000 000000
COMl
: (RW,D,GBL,REL,OVR) 000000 002000
000000 002000
COM2
: (RW,D,GBL,REL,OVR) 002000 002000

00000.
01024.
01024.
01024.

!dent File

.MAIN.

MACCOM.OBJ;l

joo 2000 1oo2000 1 010 24. .MAIN.

MACCOM.OBJ;l

(continued on next page)

5-19

SHARED REGION CONCEPTS AND EXAMPLES
Example 5-1, Part 2 (Cont.)

Task Builder Map for MACCOM.TSK

*** Task builder statistics:
Total work file references: 183.
Work file reads: 0.
Work file writes: 0.
Size of core pool: 7086. WORDS (27. PAGES)
Size of work file: 768. WORDS (3. PAGES)
Elapsed time:00:00:05

Figure 5-7 is a diagram that represents the disk
image file for
MACCOM.
The circled numbers in Figure 5-7 correspond to the circled
numbers in Example 5-1, Part 2.
RELATIVE
LOAD
ADDRESSES

RELATIVE
DISK BLOCK
NUMBERS

•
•

000005

COM 2

002000

000004

000003

•

COM 1

002000 (BYTES)

000000

000002

000001

• 'i
•

LABEL BLOCK

000000

DISK IMAGE FILE
ZK-424-8'

Figure 5-7

Allocation Diagram for MACCOM.TSK

Once you have built MACCOM, you can install it.
If your system is an
Rsx::..11~ syst~mf' the coiiunon. is loaded into memory when yo.u install it.,
If your system is an RSX-llM-PLUS system, it remains there until you
explicitly remove it with the MCR command REMOVE.
The common will not
be loaded until either_one of the following occurs.:
•
•

A task that. is linked to it is run.
You expiicitiy fix +:he common in memory with the

FIX.

5-20

MCR

command

SHARED REGION CONCEPTS AND EXAMPLES
Example 5-1, Parts 3 and 4 show two programs:
MCOMl and MCOM2,
respectively. Both of these programs reference the common area MACCOM
created above. MCOMl in Example 5-1, Part 3 accesses the COMl portion
of MACCOM.
It inserts into the first 10 words of COMl the numbers 1
through 10 in ascending order.
It then issues an Executive directive
request for the task MCOM2 and suspends itself.
When MCOM2 runs, it adds together the integers left in COMl by MCOMl
and leaves the sum in the first word of COM2.
It then issues a resume
directive for MCOMl and exits.
When MCOMl resumes, it retrieves the answer left in COM2 and calls the
system library routine $EDMSG (edit message) to format the answer for
output to device TI:.
All of the Executive directives for both programs
(RQST$C, SPND$S,
QIOW$S, RSUM$C, and EXIT$S)
are documented in the RSX-llM-PLUS
Executive Reference Manual. The system library routine $EDMSG is
documented in the IAS/RSX-11 System Library Routines Reference Manual.
Example 5-1, Part 3

MACR0-11 Source Listing for MCOMl

.TITLE
.IDENT

MCOMl
/01/

.MCALL

EXIT$S,SPND$S,RQST$C,QIOW$S

OUT:
.BLKW
FORMAT: .ASCIZ
MES:
.ASCII
LEN = •
.EVEN

100.
/THE RESULT IS %D./
/ERROR FROM REQUEST/
- MES

; SCRATCH AREA

PSECT
COMl IS USED TO ACCESS THE FIRST 512. WORDS OF THE
COMMON •
INT:

• PSECT
.BLKW

COMl,GBL,OVR,D
10.

PSECT
COM2 IS USED TO ACCESS THE SECOND 512. WORDS OF THE
COMMON. IT WILL CONTAIN THE RESULT
ANS:

.PSECT
.BLKW

COM2,GBL,OVR,D
1

.PSECT
START:
MOV
MOV
MOV

#10.,RO
#1,Rl
#INT,R3

NUMBER OF INTEGERS TO SUM
START WITH A 1
PLACE VALUES IN lST 10 WORDS
OF COMMON

(continued on next page)

5-21

SHARED REGION CONCEPTS AND EXAMPLES
Example 5-1, Part 3 (Cont.)
10$:

MOV
INC

DEC
BNE
RQST$C
BCS
SPND$S
MOV
MOV
MOV
CALL
QIOW$S
EXIT$S

MACR0-11 Source Listing for MCOMl

Rl,(R3)+
Rl
RO
10$
MCOM2
ERRl

INITIALIZE COMMON
NEXT INTEGER
ONE LESS TIME
TO INITIALIZE
REQUEST THE SECOND TASK
REQUEST FAILED
WAIT FOR MCOM2 TO SUM THE INTEGERS
#OUT,RO
ADDRESS OF SCRATCH AREA
#FORMAT,Rl
FORMAT SPECIFICATION
#ANS,R2
ARGUMENT TO CONVERT
$EDMSG
; DO CONVERSION
#IO.WVB,#5,#l,,,,<#OUT,Rl,#40>

ERRl:
QIOW$S
EXIT$S
.END

#IO.WVB,#5,#1,,,,<#MES,#LEN,#40>
START

Example 5-1, Part 4

MES:

MACR0-11 Source Listing for MCOM2

.TITLE
• !DENT

MCOM2
/01/

.MCALL

EXIT$S,QIOW$S,RSUM$C

.ASCII /ERROR FROM RESUME/
LEN = • - MES
.EVEN
PSECT
COMl IS USED TO ACCESS THE FIRST 10. WORDS OF THE
COMMON •

INT:

• PSECT
.BLKW

COMl,GBL,OVR,D
10.

PSECT - COM2 IS USED TO ACCESS THE SECOND 10. WORDS OF THE
COMMON. IT WILL CONTAIN THE RESULT
ANS:

.PSECT
.BLKW

COM2,GBL,OVR,D
1

.PSECT
START:

10$:

MOV
MOV

#10. ,RO

CLR
ADD
DEC
BNE

ANS
(R3}+,ANS
10$

NUMBER OF INTEGERS TO SUM
PLACE VALUES IN lST 10 WORDS
OF COMMMON
INITIALIZE ANSWER
ADD IN VALUES
ONE LESS VALUE
TO SUM

RSUM$C
BCS
EXIT$S

MCOMl
ERR

RESUME MCOMl
RESUME FAILED

QIOW$S
EXIT$S
.END

#IO.WVB,#5,#1,,,,<#MES,#LEN,#40>

#INT,R3

ERR:
START

5-22

SHARED REGION CONCEPTS AND EXAMPLES
Note that both tasks MCOMl and MCOM2 contain .PSECT declarations
establishing program section names that are the same as program
section names within the position-independent common to which the task
is linked
(MACCOM).
As stated earlier, in most circumstances this
would be illegal.
In this application, however, the .PSECT directives
have been placed into the tasks to establish symbolic offsets in the
resident common. When either task is built, TKB assigns to the symbol
INT:
the base address of program section COMl, and to the symbol ANS:
the base address of program section COM2.
Figure 5-8 illustrates this
assignment.

ANS:

INT:

-- - -

COM 2

~-- -

- -- -

- - - - -

...._

- -

~--

_-:::::::-~

COM 1

--- -

- - - _-::_~

tN-2..:::=~---------------------------ZK-425-81

Figure 5-8

Assigning Symbolic References within a Common

Once you have assembled MCOMl and MCOM2, you can build them
following TKB command sequences:

with

the

>TKB
TKB>MCOMl,MCOMl/-SP=MCOMl
TKB>/
Enter Options:
TKB>RESCOM=MACCOM/RW
TKB>//
>TKB
TKB>MCOM2,MCOM2/-SP=MCOM2
TK~/

Enter Options:
TKB>RESCOM=MACCOM/RW
TKB>//
Under options in both of these command sequences, the RESCOM option
tells TKB that these programs intend to reference a common data area
named MACCOM and that the tasks require read/write access to it.
Because the RESCOM option is used, TKB expects to find the image file
and the symbol definition file for the common on device SY:
under the
UFD that corresponds to the terminal UIC.
In addition! because the
optional APR specification was omitted from the RESCOM option, TKB
allocates virtual address space for the common starting with APR7 in
both tasks (the highest APR available in both tasks).

5-23

SHARED REGION CONCEPTS AND EXAMPLES
The TKB map for MCOMl is shown in Example 5-1, Part 5.
The map for
MCOM2 is not essentially different from that of MCOMl and is therefore
not included here.
Example 5-1, Part 5
MCOMl.TSK;l

Task Builder Map for MCOMl.TSK
Page 1

Memory allocation map TKB M40.10
ll-DEC-82
16:12

Partition name : GEN
Identification : 01
Task UIC
[7,62]
Stack
limits: 000274 001273 001000 00512.
PRG xfr address: 001650
Total address windows: 2.
Task image size
1184. WORDS
Task address limits: 000000 004407
R-W disk blk limits: 000002 000006 000005 00005.

*** Root segment: MCOMl
R/W mem limits: 000000 004407 004410 02312.
Disk blk limits: 000002 000006 000005 00005.
Memory allocation synopsis:
Section

Title

!dent

File

MCOM

MCOMl.OBJ;l

MCOM

MCOMl.OBJ;l

MCOM

MCOMl.OBJ;l

MCOM

MCOMl.OBJ;l

-------

. BLK.: (RW,I,LCL,REL,CON) 001274 002664 01460.

001274
: (RW,D,GBL,REL,OVR) 160000
160000
COM2
: (RW,D,GBL,REL,OVR) 162000
162000
$DPB$$:(RW,I,LCL,REL,CON) 004160
004160
$$RESL:(RO,I,LCL,REL,CON) 004176

CO Ml

000574
002000
000024
002000
000002
000016
000016
000212

00380.
01024.
00020.
01024.
00002.
00014.
00014.
00138.

*** Task builder statistics:
Total work file references: 1924.
Work file reads: o.
Work file writes: 0.
Size of core pool: 7086. WORDS (27. PAGES)
Size of work file: 1024. WORDS ( 4. PAGES)
Elapsed time:00:00:04

5-24

SHARED REGION CONCEPTS AND EXAMPLES
Note that TKB has placed two window blocks in MCOMl's header.
When
MCOMl is installed, the INSTALL processor will initialize these window
blocks as follows:

5.1.9

•

Window block 0 will describe the range
(the window} for MCOMl's task region.

virtual

addresses

•

Window block 1 will describe the window for the shared
MACCOM.

region

Linking Shared Regions Together

Shared regions can link to other shared regions.
You may find
it
convenient to have code in a shared library and have access to
routines in another shared library to which it links.
The following text describes, as an example for a mapped system, the
TKB command sequence for building a resident library named FILEB.
That text is followed by a TKB command sequence that shows an example
of building another resident library named FORCOM that links to FILEB.
Following after that, a TKB command sequence shows the building of a
task that links to FORCOM.
In the TKB command sequences to follow, it
is assumed that you know the contents of the libraries an.d the task.
The examples show the linkage only.
The first shared region to be built is called FILEB.
The library
FILEB is a position-dependent library.
You use the /-PI switch to
signify that the library is absolute. You build.the library with the
/-HD switch to indicate that the library has no header.
The /LI
switch indicates that FILEB is to be a shared library.
The program
section name of the library is . ABS, which is the only one in the
library.
FILEB is to be loaded into a user-controlled partition on a
mapped system.
The name of the partition in which FILEB resides has
the same name, FILEB, that you specify in the PAR option.
The PAR
option also specifies the base address and the length of the
partition.
Because FILEB is absolute, a base address must be
specified;
here,
the base address is 160000.
The length in this
example is 4K bytes.
If neither the base nor the length is specified,
TKB tries to determine the length. The TKB command sequence follows:
>TKB
TKB>FILEB/-PI/-HD/LI,FILEB/-SP,FILEB=FILEB.OBJ
TKB>/
Enter Options:
TKB>STACK=O
TKB>PAR=FILEB:l60000:40000
TKB>//
The next TKB command sequence specifies a shared library called
FORCOM.
FORCOM links to the read-only library called FILEB. You
build FORCOM with the /LI switch to specify a library to the Task
Builder.
FORCOM is relocatable.
You specify in the RESLIB option
that the resident library to which FORCOM links is called FILEB.
The

5-25

SHARED REGION CONCEPTS AND EXAMPLES
access required is read-only, which /RO specifies in the RESLIB option
line. The TKB command sequence follows:
>TKB
TKB>FORCOM/-HD/LI/PI,FORCOM/-SP,FORCOM=FORCOM.OBJ
TKB>/
Enter Options:
TKB>STACK=O
TKB>PAR=FORCOM:0:4000
TKB>RESLIB=FILEB/RO
TKB>//
The next TKB command sequence builds the task and specifies that the
task links to the library called FORCOM.
The RESLIB option line
specifies the link to the resident library called FORCOM.
>TKB
TKB>FOTASK,FOTASK/-SP,FOTASK=FOTASK.OBJ
TKB>/
Enter Options:
TKB>RESLIB=FORCOM/RW
TKB>//
Build the libraries before you build the task, and install the
libraries before you run or install the task. See Chapters 10 and 11
for a description of the /PI, /HD, /CO, and /LI switches and the PAR,
RESCOM, and RESLIB options •

•
5.1.10

Example 5-2:
MACR0-11

Building and

Linking

Device

Common

A device common is a special type of common that occupies physical
addresses on the I/O page. When mapped into the virtual address space
of a task, a device common permits the task to manipulate peripheral
device registers directly.
NOTE
Because any access to the I/O page is
potentially hazardous to the running
extreme
system, you
must
exercise
caution
when
working
with
device
commons.
The remaining text in this section and the figures associated with it
illustrate the development and use of a device common.
Example 5-2,
Part l shows an assembiy iisting for a position-independent device
common named TTCOM.
When installed, TTCOM will map the control and
data registers of the console terminal.
Its physical base address
will be 777500.

5-26

SHARED REGION CONCEPTS AND EXAMPLES
Example 5-2, Part 1

$RCSR: :
$RBUF::
$XCSR::
$XBUF::

Assembly Listing for TTCOM

.TITLE TTCOM
.PSECT TTCOM,GBL,D,RW,OVR
.=.+60
.BLKW
1
.BLKW
1
.BLKW
1
.BLKW
1
.END

The PDP-11 Peripherals Handbook defines the control and data register
addresses for the console terminal.
In Example 5-2, Part 1, the
register addresses and the symbol names that correspond to them are as
follows:

Address

Symbol

Keyboard Status
Keyboard Data
Printer Status
Printer Data

777560
777562
777564
777566

$RCSR
$RBUF
$XCSR
$XBUF

The double colon (::) following each symbol in Example 5-2, Part 1
establishes the symbol as global. The first symbol, RCSR, is offset
from the beginning of TTCOM by 60{octal)
bytes.
Each
symbol
thereafter is one word removed from the symbol that precedes it.
Thus, when TTCOM is installed at 777500, each symbol will be located
at its proper address.
Once you have assembled TTCOM, you can build it
TKB command sequence:

using

the

following

>TKB
TKB>LB:[l,l]TTCOM/-HD/PI,LB: [l,l]TTCOM/-WI/SP,LB:[l,l]TTCOM=TTCOM
TKB>/
Enter Options:
TKB>STACK=O
TKB>PAR=TTCOM:O:lOO
TKB>//
This command sequence directs TKB to create a common image named
TTCOM.TSK and a symbol definition file named TTCOM.STB. TKB places
both files on device LB: under UFD [1,1]. The command sequence also
specifies that TKB is to spool a map listing to the line printer. The
/SP switch need not be present because it is the default.
The /-WI
switch specifies an 80-column line printer listing format.
NOTE
For the command sequence above to work
in a multiuser protection system, it
must be
input
from
a
privileged
terminal.
The STACK=O option suppresses the stack area in the common's image
file.
The PAR option specifies that the device common will reside
within a partition of the same name as that of the common.
As with
the data common in Example 5-1 (Sectiol"l 5.~~7), ,tl1is i.s a reqtiirem.el'lt
of the RSX-llM system;
. fo an ~RSX-llM'...:PLll~ Siyst,e;m 'it is not.: :The PA~ .
.option a1so spe.ctfies that the· base of the:. common Js; n a·nd that it· is;.
100 ( octa lJ by~es long~-.
5-27

SHARED REGION CONCEPTS AND EXAMPLES
The TKB map for TTCOM that results from the command sequence above is
shown in Example 5-2, Part 2.
The task attributes section of this map
indicates that the common is position independent and that no header
is associated with it.
The common's image and symbol definition file
reside on device LB:
under UFO [1,1].
The map in Example 5-2, Part 2 shows the global symbols defined in the
common with their relative offsets into the common region.
You
establish the virtual base address for
the common and the virtual
addresses for the symbols within it when you build the tasks that link
to the common.
You establish the physical addresses for the common with the MCR
command SET.
The keyword that you use with the SET command depends on
which system you are running.
I f your system js.. an. RSX'-'ll;M. s:y:~:te,~,.
use the command
>SET /MAIN=TTCOM: 7775.: 1 :DEV
If your syste,m is one that uses 22-bit
command

phy.sical

addres.ses 1

us.e

the

>SET /MAIN=TTCOM:l77775:l:DEV

:I'f lyour: sys!tem .:fs;. :an :RSX.;.;; llM'""l:PLiUS sy~t,~m, u:se the commµnd
; vw:4; ·• . ; : :· 1 . ; . : r . /' ! .•: . :· :! .· )' . :· 1 ..'. .; :; •
'. ; ~Si{E!J.1· ;:~~~~!-1'!·T77:rl1 5;: i::~:p~v
: :i
These previous SET command sequences create a main partition named
TTCOM that begins at physical address 777500 in 18-bit systems and
physical address 1777750 in 22-bit systems.
The partition is one
64-byte block long, (lOO(octal} bytes}.
The argument DEV identifies
the par ti ti on type. With the common built and the partition for it
created, you must install TTCOM in an RSX-llM system before using it'.
For example, use
>INS LB:[l,lJTTCOM
You can establish the partition for a device common at any time in
both the RSX-llM and the RSX-llM-PLUS systems.
Partitions created to
accommodate a device common are not a system generation consideration
because they represent areas of physical address space above memory
and therefore cannot conflict with memory partitions.
Example 5-2, Part 2
TTCOM.TSK;l

Task Builder Map for TTCOM

Memory allocation map TKB M40.10
l-DEC-82
17:02

Partition name
TTCOM
Identification
Task UIC
[7,62]
Task attributes: -HD,PI
Total address windows: 1.
Task image size : 32. WORDS

Page 1

TASK
ATTRIBUTES
SEC'!' ION

(continued on next page)

5-28

SHARED REGION CONCEPTS AND EXAMPLES
Example 5-2, Part 2 (Cont.)

Task Builder Map for TTCOM

Task address limits: 000000 000067
R-W disk blk limits: 000002 000002 000001 00001.

*** Root segment: TTCOM
R/W mem limits: 000000 000067 000070 00056.
Disk blk limits: 000002 000002 000001 00001.

Memory allocation synopsis:
Title

Section

Ident

• BLK.: (RW,I,LCL,REL,CON) 000000 000000 00000.
TTCOM :(RW,D,GBL,REL,OVR) 000000 000070 00056.
000000 000070 00056 • • MAIN.

File

TTCOM.OBJ;l

Global symbols:
$RBUF

000062-R

$RCSR

000060-R

$XBUF

000066-R

$XCSR

000064-R

*** Task builder statistics:
Total work file references: 214.
Work file reads: O.
Work file writes: 0.
Size of core pool: 6666. WORDS (26. PAGES)
Size of work file: 768. WORDS (3. PAGES)
Elapsed time:00:00:02

Example 5-2, Part 3 shows an assembly listing for a demonstration
program named TEST.
When built and installed, TEST will print the
letters A through Z on the console terminal by directly accessing the
console terminal status and data registers.
It will access the status
and data registers through the device common TTCOM.
Example 5-2, Part 3

Assembly Listing for TEST

.TITLE TEST
• !DENT /01/
.MCALL EXIT$S
START:

MOV
CALL
MOV
CALL
MOV
MOV

#15 I RO

OUTBYT

#12, RO
OUTBYT
#101,RO

#26.,Rl

START WITH A CARRIAGE RETURN
PRINT IT
THEN A LINE FEED
PRINT IT
FIRST LETTER IS AN "A"
NUMBER OF LETTERS TO PRINT
(continued on next page)

5-29

SHARED REGION CONCEPTS AND EXAMPLES
Example 5-2, Part 3 (Cont.)
OUTPUT: CALL
DEC
BNE
MOV
CALL
MOV
CALL
EXIT$S
OUTBYT: TSTB
BPL
MOV
INC
RETURN
.END

Assembly Listing for TEST

OUTBYT
Rl
OUTPUT
#15,RO
OUTBYT
#12,RO
OUTBYT

PRINT CURRENT LETTER
ONE LESS TIME
AGAIN
ANOTHER CARRIAGE RETURN

$XCSR
OUTBYT
RO,$XBUF
RO

OUTPUT BUFFER READY?
IF NOT WAIT
MOVE CHARACTER TO OUTPUT BUFFER
INITIALIZE NEXT LETTER

ANOTHER LINE FEED

START

Once you have assembled TEST, you can build it with the following
command sequence:

TKB

>TKB
TKB>TEST,TEST/-WI/MA=TEST
TKB>/
Enter Options:
TKB>COMMON=TTCOM:RW:l
TKB>//
The COMMON option in this command sequence tells TKB that TEST intends
to access the device common TTCOM and that TEST will have read/write
access to it.
It also directs TKB to reserve APR 1 for mapping the
common into TEST's virtual address space.
The TKB map that results from the command sequence above is
Example 5-2, Part 4.

shown

This map contains a global symbols section.
TKB included
it because
the /MA switch was applied to the memory allocation file at task-build
time.
Note that the global symbols
in this section, which were
defined in TTCOM,
now have virtual addresses assigned to them.
The
addresses assigned by TKB are the result of the APR 1 specification in
the COMMON= keyword during the task build.
It is important to remember that programs like TEST, which access the
I/O page,
take complete control of the registers they reference.
Therefore, coding errors in such programs can disable the devices they
reference and can even make it impossible for the device drivers to
regain control of the device.
If this happens, you must reboot the
system.

5-30

SHARED REGION CONCEPTS AND EXAMPLES
Example 5-2, Part 4
TEST.TSK;l

Memory Allocation Map for TEST

Memory allocation map TKB M40.10
l-DEC-82 17:03

Page 1

GEN
Partition name
Identification
01
Task UIC
[7,62]
Stack
limits: 000274 001273 001000 00512.
PRG xfr address: 001274
Total address windows: 2.
Task image size
384. WORDS
Task address limits: 000000 001377
R-W disk blk limits: 000002 000003 000002 00002.

*** Root segment:

TEST

R/W mem limits: 000000 001377 001400 00768.
Disk blk limits: 000002 000003 000002 00002.
Memory allocation synopsis:
Title

Section
• BLK.:(RW,I,LCL,REL,CON) 001274
001274
TTCOM : (RW,D,GBL,REL,OVR) 200000
200000

000100
000100
000070
000070

!dent

00068.
00068 • • MAIN.
00056.
00056. TTCOM

File

TEST.OBJ;!
TTCOM.STB;l

Global symbols:
$RBUF

020062-R

$RCSR

020060-R

$XBUF

020066-R

$XCSR

020064-R

*** Task builder statistics:
Total work file references: 243.
Work file reads: 0.
Work f i 1 e wr i t es : 0 •
Size of core pool: 6666. WORDS (26. pages)
Size of work file: 768. WORDS (3. pages)
Elapsed time:00:00:03

5.1.11

Example 5-3:
MACR0-11

Building and Linking to a

Resident

Library

Resident libraries consist of subroutines that are shared by two or
more tasks. When such tasks reside in physical memory simultaneously,
resident libraries provide a considerable memory savings because the
subroutines within the library appear in memory only once.

5-31

SHARED REGION CONCEPTS AND EXAMPLES
The text in this section and the figures associated with it illustrate
the development and use of a resident library, called LIB.
Example S-3, Part 1 shows five FORTRAN-callable subroutines:

• An integer addition routine, AADD
• An integer subtraction routine, SUBB

• An integer multiplication routine, MULL
• An integer division routine, DIVV
• A register save and restore coroutine, SAVAL
These subroutines are contained in a single source file,
LIB.MAC.
When assembled and built, they constitute an example of a resident
library. FORTRAN-callable routines were used in this example so that
the routines can be accessed by either FORTRAN or MACR0-11 programs.
Example S-3, Part 1

Source Listing for Resident Library LIB.MAC

• TITLE
• !DENT

LIB
/01/

.PSECT

AADD,RO,I,GBL,REL,CON

;** FORTRAN CALLABLE SUBROUTINE TO ADD TWO INTEGERS
AADD::

CALL
MOV
MOV
ADD
MOV
RETURN

$SAVAL
@2 (RS) ,RO
@4(RS),Rl
RO,Rl
Rl,@6(RS)

SAVE RO-RS
FIRST OPERAND
SECOND OPERAND
SUM THEM
STORE RESULT
RESTORE REGISTERS AND RETURN

.PSECT

SUBB,RO,I,GBL,REL,CON

;** FORTRAN CALLABLE SUBROUTINE TO SUBTRACT TWO INTEGERS
SUBB::

CALL
MOV
MOV
SUB
MOV
RETURN

$SAVAL
@2 (RS) ,RO
@4 (RS) ,Rl
Rl,RO
R0,@6(RS)

.PSECT

MULL,RO,I,GBL,REL,CON

SAVE RO-RS
FIRST OPERAND
SECOND OPERAND
SUBTRACT SECOND FROM FIRST
STORE RESULT
RESTORE REGISTERS AND RETURN

;** FORTRAN CALLABLE SUBROUTINE TO MULTIPLY TWO INTEGERS
(continued on next page)

5-32

SHARED REGION CONCEPTS AND EXAMPLES
Example 5-3, Part 1 (Cont.)
MULL::

Source Listing for Resident Library LIB.MAC
SAVE RO-R5
FIRST OPERAND
SECOND OPERAND
MULTIPLY
STORE RESULT
RESTORE REGISTERS AND RETURN

CALL
MOV
MOV
MUL
MOV
RETURN

$SAVAL
@2 (R5) ,RO
@4(R5),Rl
RO ,Rl
Rl,@6(R5)

.PSECT

DIVV,RO,I,GBL,REL,CON

;** FORTRAN CALLABLE SUBROUTINE TO DIVIDE TWO INTEGERS
DIVV::

CALL
MOV
MOV
CLR
DIV
MOV
RETURN

$SAVAL
@2 (R5) ,R3
@4 ( R5) I Rl
R2
Rl,R2
R2,@6(R5)

SAVE REGS RO-R5
FIRST OPERAND
SECOND OPERAND
LOW ORDER 16 BITS
DIVIDE
STORE RESULT
RESTORE REGISTERS AND RETURN

.PSECT

SAVAL,RO,I,GBL,REL,CON

;**ROUTINE TO SAVE REGISTERS
$SAVAL::
MOV
MOV
MOV
MOV
MOV
MOV
MOV
CALL
MOV
MOV
MOV
MOV
MOV
MOV
RETURN
.END

;SAVE R4
;SAVE R3
;SAVE R2
;SAVE Rl
;SAVE RO
;COPY RETURN
;SAVE R5
;CALL THE CALLER
;RESTORE RO
;RESTORE Rl
;RESTORE R2
;RESTORE R3
;RESTORE R4
;RESTORE R5

R4,-(SP)
R3,-(SP)
R2,-(SP)
Rl,-(SP)
RO,-(SP)
12 (SP) ,- (SP)
R5,14(SP)
@(SP)+
(SP)+,RO
{SP)+,Rl
(SP)+,R2
(SP)+,R3
(SP)+,R4
(SP)+,R5

Once you have assembled LIB, you can build it with the
command sequence:
TKB>LIB/PI/-HD/LI,LIB/-WI,LIB=LIB
TKB>/
Enter Options:
TKB>STACK=O
TKB>PAR=LIB:0:200
TKB>//

5-33

following

TKB

SHARED REGION CONCEPTS AND EXAMPLES
This command sequence instructs TKB to build a position-independent
(/PI), headerless
(/-HD)
library image named LIB.TSK.
It instructs
TKB to create a map file LIB.MAP and to output an 80-column listing
(/-WI) to the line printer.
It also specifies that TKB is to create a
symbol
definition
file,
LIB.STB.
TKB
creates
all
three
files -- LIB.TSK, LIB.MAP, and LIB.STB -- on device SY:
under the UFO
that corresponds to the terminal UIC. The /LI and /PI switches used
together cause TKB to name the program section LIB, which is the root
segment of the library. LIB becomes the only named program section in
the library.
If you used the command sequence above without
would create a common by default.

the

/LI

switch,

TKB

The STACK=O option suppresses the stack area within the resident
library's image.
The PAR option tells TKB that the resident library
will reside. \Yi'.thiq,a; parti.t::ipn. of .. th . e. same:. name. as .t::hat of ..the
library.
AS. :W)}th .· 1a:1L s,Jl;~red .. •r:eg.tons;,.· 'thi$ is·'.~·· requfreinent..in an
;;RSX:-11~. t's~;tiemi;'.'
];.pJftrl9ft
~~i1ttr'.';~~1;'!i'ffitj~\
In add i ti 0 n I
the PAR opt{on' sp~tci ies'"bthaf tile" ~base 0
t he*' Y"ib;;rary' iS 0 and that it
is 200(octal) bytes long.
(For more information on the switches and
options used in this example, refer to Chapters 10 and 11.)
1

'r···

.·..

Example 5-3, Part 2 shows the TKB map that results
sequence above.

from

the

command

Note in the global symbols section of the map in Example 5-3, Part 2
that TKB has assigned offsets to the symbols for each library
function. When the task that links to this library is built, TKB will
assign virtual addresses to these symbols.
The program MAIN in Example 5-3, Part 3 exercises the routines in the
resident library LIB.TSK. When you assemble and build it, MAIN will
call upon the library routines to add, subtract, multiply, and divide
the integers contained in the labels OPl and OP2 within the program.
MAIN will print the results of each operation to device TI:.
Example 5-3, Part 2
LIB.TSK;l

Task Builder Map for LIB.TSK

Memory allocation map TKB M40.10
ll-DEC-82
13:50

Page 1

Partition name
LIB
Identification
01
Task UIC
[7,62]
Task Attributes: -HD,PI
Total address windows: 1.
Task image size
64. WORDS
Task address limits: 000000 000163
R-W disk blk limits: 000002 000002 000001 00001.

*** Root segment: LIB
R/W mem limits: 000000 000163 000164 00116.
Disk blk limits: 000002 000002 000001 00001.
(continued on next page)

5-34

SHARED REGION CONCEPTS AND EXAMPLES
Example 5-3, Part 2 (Cont.)

Task Builder Map for LIB.TSK

Memory allocation synopsis:
Section

-------

BLK.: (RW,I,LCL,REL,CON) 000000 000000
AADD
:(RO,I,GBL,REL,CON) 000000 000024
000000 000024
DIVV :(RO,I,GBL,REL,CON) 000024 000026
000024 000026
MULL
:(RO,I,GBL,REL,CON) 000052 000024
000052 000024
SAVAL :(RO,I,GBL,REL,CON) 000076 000042
000076 000042
SUBB :(RO,I,GBL,REL,CON) 000140 000024
000140 000024

00000.
00020.
00020.
00022.
00022.
00020.
00020.
00034.
00034.
00020.
00020.

Title

Ident

File

LIB

LIB. OBJ; 2

LIB

LIB.OBJ;2

LIB

LIB.OBJ;2

LIB

LIB. OBJ; 2

LIB

LIB.OBJ;2

Global symbols:
AADD
DIVV

000000-R
000024-R

MULL

000052-R SUBB

000140-R

*** Task builder statistics:
Total work file references: 368.
Work file reads: Oo
Work file writes: O.
Size of core pool: 7086. WORDS (27. PAGES)
Size of work file: 768. WORDS (3. PAGES)
Elapsed time:00:00:03
Example 5-3, Part 3
• TITLE
• IDENT

Source Listing for MAIN.MAC

MAIN
/01/

;+
;**MAIN - CALLING ROUTINE TO EXERCISE THE ARITHMETIC ROUTINES
FOUND IN THE RESIDENT LIBRARY, LIB.TSK.

OPl:
OP2:
ANS:
OUT:

.MCALL

QIOW$S, EXIT$S

.WORD
.WORD
.BLKW
.BLKW

1
1
1
100.

OPERAND 1
OPERAND 2
RESULT
FORMAT MESSAGE
(continued on next page)

5-35

SHARED REGION CONCEPTS AND EXAMPLES
Example 5-3, Part 3 (Cont.)
FORMAT:

.ASCIZ
.EVEN
.ENABL

/THE ANSWER

Source Listing for MAIN.MAC

%D./

LSB

START:
MOV
MOV
MOV
MOV
MOV
CALL
CALL
MOV
CALL
CALL
MOV
CALL
CALL
MOV
CALL
CALL
EXIT$S

#ANS,-(SP)
#OP2,-(SP)
#OPl ,- (SP)
#3,-(SP)
SP,R5
AADD
PRINT
SP,R5
SUBB
PRINT
SP,RS
MULL
PRINT
SP,R5
DIVV
PRINT

TO CONTAIN RESULT
OPERAND 2
OPERAND 1
PASSING 3 ARGUMENTS
ADDRESS OF ARGUMENT BLOCK
ADD TWO OPERANDS
PRINT RESULTS
ADDRESS OF ARGUMENT BLOCK
SUBTRACT SUBROUTINE
PRINT RESULTS
ADDRESS OF ARGUMENT BLOCK
MULTIPLY SUBROUTINE
PRINT RESULTS
ADDRESS OF ARGUMENT BLOCK
DIVIDE SUBROUTINE
PRINT RESULTS

;+
•** PRINT - PRINT RESULT OF OPERATION.

PRINT:

MOV
MOV
MOV
CALL
QIOW$S
RETURN
.END

#OUT,RO
ADDRESS OF SCRATCH AREA
#FORMAT,Rl
FORMAT SPECIFICATION
#ANS,R2
ARGUMENT TO CONVERT
$EDMSG
; FORMAT MESSAGE
#IO.WVB,#5,#l,,,,<#OUT,Rl,#40>
; RETURN FROM SUBROUTINE
START

Once you have assembled MAIN, you can use the
sequence to build it:

following

TKB

command

TKB>MAIN,MAIN/MA/-WI/-SP=MAIN
TKB>/
Enter Options:
TKB>RESLIB=LIB/R0:3
TKB>//
This command sequence instructs TKB to build a task file named
MAIN.TSK on device SY: under the UFO that corresponds to the terminal
UIC.
It also specifies that TKB is to create a map file MAIN.MAP.
The /MA switch requests an extended map format.
In this example, /MA
was applied to the device specification so that TKB would include in
the map for the task the symbols within the library LIB. The negated
form of the wide listing switch
(/-WI)
was appended to the map
specification to obtain an 80-column map format.
In this example, TKB
will not output a map listing to the line printer
The RESLIB option specifies that the task MAIN is to access the
library LIB and that it requires read-only access to LIB. TKB uses
APR3 to map the library.
The TKB map that results
Example 5-3, Part 4.

from

this

5-36

command

sequence

shown

SHARED REGION CONCEPTS AND EXAMPLES

Example 5-3, Part 4
MAIN. TSK; 1

Task Builder Map for MAIN.TSK

Memory allocation map TKB M40.10
ll-DEC-82
13:51

Page 1

Partition name : GEN
Identification : 01
Task UIC
[7,62]
Stack
limits: 000274 001273 001000 00512.
PRG xfr address: 001634
Total address w-i ndows: 2.
Task image size
1152. WORDS
Task address limits: 000000 004327
R-W disk blk limits: 000002 000006 000005 00005.

*** Root segment: MAIN
R/W mem limits: 000000 004327 004330 02264.
Disk blk limits: 000002 000006 000005 00005.
Memory allocation synopsis:
Section

-------

BLK.: (RW,I,LCL,REL,CON) 001274
001274
002024
003074
003312
003406
003656
004004
AADD : (RO,I,GBL,REL,CON) 060000
060000
DIVV : (RO,I,GBL,REL,CON) 060024
060024
MULL :(RO,I,GBL,REL,CON) 060052
060052
SA VAL : (RO,I,GBL,REL,CON) 060076
060076
SUBB :(RO,I,GBL,REL,CON) 060140
060140
$$RESL:(RO,I,LCL,REL,CON) 004114
004114
004140
004226

002620
000530
001050
000216
000074
000250
000126
000110
000024
000024
000026
000026
000024
000024
000042
000042
000024
000024
000212
000024
000066
000100

01424.
00344.
00552.
00142.
00060.
00168.
00086.
00072.
00020.
00020.
00022.
00022.
00020.
00020.
00034.
00034.
00020.
00020.
00138.
00020.
00054.
00064.

Title

Ident

File

MAIN
EDTMG
CBTA
CATB
EDD AT
CDDMG
C5TA

01
15
04.3
03
03
00
02

MAIN .OBJ; 1
SYSLIB.OLB;l034
SYSLIB. OLB; 1034
SYSLIB. OLB; 1034
SYSLIB.OLB;l034
SYSLIB.OLB;l034
SYSLIB.OLB;l034

LIB

LIB. STB; 17

LIB

LIB.STB;l7

LIB

LIB.STB;l7

LIB

LIB. STB; 17

LIB

LIB. STB; 17

SAVRG 04
AR ITH 03.04
DARI TH 0007

SYSLIB.OLB;l034
SYSLIB.OLB;l034
SYS LIB. OLB; 1034

(continued on next page)

5-37

SHARED REGION CONCEPTS AND EXAMPLES
Example 5-3, Part 4 (Cont.)

Task Builder Map for MAIN. TSK

Global symbols:
AADD
DIVV
IO.WVB
MULL
SUBB
$CB DAT
$CBDMG

060000-R
060024-R
011000
060052-R
060140-R
003074-R
003102-R

$CBDSG 003110-R
$CBOMG 003116-R
$CBOSG 003124-R
$CBTA 003154-R
$CBTMG 003132-R
$CBVER 003116-R
$CDDMG 003656-R

$CDTB
$COTB
$C5TA
$DAT
$DDIV
$DIV
$DMUL

003312-R
003320-R
004004-R
003452-R
004264-R
004170-R
004226-R

$EDMSG
$MUL
$SAVRG
$TIM

002122-R
004140-R
004114-R
003532-R

*** Task builder statistics:
Total work file references: 2218.
Work file reads: O.
Work file writes: O.
Size of core pool: 2066. words (8. pages)
Size of work file: 1024. words (4. pages)
Elapsed time:OO:OO:l9

This map contains a global symbols section.
Note that the symbols
within the library now have virtual addresses assigned to them and
that these addresses begin at 60000(octal), the virtual base address
of APR 3.
The Task Builder's allocation of virtual address space for
MAIN.TSK is represented diagrammatically in Figure 5-9.

APR 7APR6-

APR 5APR4-

VIRTUAL 60000 APR 3·-

~---L-IB_._r_sK_ _.... }

i i~iil:I
1

APR 2-

1
APR 1-

WINDOW 1 REGION 1

_ _M_A_l_N_.T_s_K_ _ }w1NDOW 0 REGION 0

VIRTUAL 0 APR OZK-426-81

Figure 5-9

Allocation of Virtual Address Space for MAIN.TSK

5-38

SHARED REGION CONCEPTS AND EXAMPLES
The library LIB is position independent and can therefore be mapped
anywhere in the referencing task's virtual address space. APR 3 was
used in this example to contrast this mapping arrangement with the
mapping of MACCOM in the virtual address space of task MCOMl in
Example 5-1 (Section 5.1.7) • .If the optional APR parameter in the
RESLIB option above had been ieft blank, TKB would have allocated the
highest available APR to map the library.

5.1.11.1 Resolving Program Section Names in a Shared Region - As
described in earlier sections of this chapter, program section names
within position-independent shared regions must normally be unique
with respect to program section names within tasks that reference
them. When a shared region is a position-independent resident common
and you explicitly declare the program section names within it,
avoiding program section name conflicts is an easy matter.
However,
when a shared region is a position-independent resident library that
contains calls to routines within an object module library
(SYSLIB,
for example), conflicts may develop that are not apparent to you. The
problem arises when the position-independent resident library and one
or more tasks that link to it contain calls to separate routines
residing within the same program section of an object module library.
When TKB resolves a call from within a module that it is processing to
a routine within an object module library, it places the routine from
the library into the image it is building.
It also enters into its
internal table the name of the program section in the object module
library within which the routine resides.
If a position-independent
resident library contains a call to a routine within a given program
section of SYSLIB, for example, and then subsequently a task that
links to the resident library contains a call to a different routine
within the same program section of SYSLIB, both the resident library
and the referencing task will contain the program section name. When
you build the referencing task, the library's .STB file will contain
the program section name and a program section conflict will develop.
(Refer to Section 5.1.6 for additional information on the sequence in
which TKB processes tasks and the potential program section name
conflicts that can result.)
This situation and one possible solution to it can be illustrated with
Example 5-3. When this example was first created, only the arithmetic
routines were included in the source file of the resident library
(LIB.MAC in Example 5-3,
Part 1).
The system library coroutine
($SAVAL) was resolved from SYSLIB.
Because the first
instruction of
each arithmetic routine called $SAVAL, TKB included a copy of it in
the resident library's image at task-build time.
This turned out to
be unsatisfactory because of a call to the SYSLIB routine $EDMSG (edit
message) within the program MAIN that links to the resident library.
Both routines
($SAVAL and $EDMSG) reside within the unnamed or blank
program section (. BLK.) within SYSLIB. Therefore, a program section
name conflict developed when MAIN was built.
To circumvent this problem, the source code for $SAVAL was included in
the source file for the resident library under the explicitly declared
program section name SAVAL.
Another solution would have been to build the resident library
absolute.
In this case, TKB would not have included program section
names from the resident library into the .STB file for
the resident
library.

5-39

SHARED REGION CONCEPTS AND EXAMPLES
It is important to note that the above program section name conflict
develops only when two different routines residing within the same
program section of an object module library are involved.
It presents
no problem when a resident library and a task that links to it contain
a call to the same routine in an object module library.
In that case,
TKB copies the routine and the program section name in which it
resides into the resident library when the library is built.
Then,
when the task that calls the same routine is built, TKB resolves the
reference to the routine in the resident library instead of in the
object module library.

5.1.12

Example 5-4:

Building a Task That Creates a Dynamic Region

In all the examples of tasks shown thus far in this chapter, TKB has
automatically constructed and placed in the header of the task all of
the window blocks necessary to map all of the regions of the task's
image.
The INSTALL processor has been responsible for initializing
the window blocks when the task was installed.
In all the examples,
this has been possible because both TKB and the INSTALL processor have
had all the information concerning the regions available to them.
When a task creates regions while it is running (dynamic regions), the
information concerning the regions is not available to either the Task
Builder or INSTALL.
Therefore, when TKB builds such a task,
it does
not automatically create window blocks for the dynamic regions.
It
creates only the window blocks necessary to map the task region
(the
region containing the header and stack) and any shared regions that
the task references.
Dynamic regions are created and mapped with Executive directives that
are imbedded in the task's code. When you build a task that creates
dynamic regions, you must explicitly specify to TKB how many window
blocks
(in excess of those created by TKB for the task region and any
shared regions) it is to place in the task's header.
The Executive
will
initialize these window blocks when it processes the region and
mapping directives.
In all (including window blocks for the task
region and. sh a.red reg io11s) , yo~~ f;?J!; ;i;!c:l~~~~ ,;a2., ..~~n:Y,;__?~ .,.?~!!:~!l:EE~~ . E~!~2~~~.
to, .a ta~k 1n an: ::RSX-IlK system ,a;Q(L as •. man,y• as ,16 in :al)• RSJ(,....llM-PLUS
·s:;zr;~:t:eiri~

The text in the remainder of this section and the figures associated
with it illustrate the development of a task that creates dynamic
regions.
Example 5-4 shows a task (DYNAMIC.MAC) that creates a 128word dynamic region.
This task simply creates an unnamed region, maps
to it, and fills it with an ascending sequence of numbers beginning at
the region's base and moving upwards.
When the region is full,
DYNAMIC detaches from it and prints the following message on your
terminal:
DYNAMIC IS NOW EXITING
The region is automatically deleted on detach.
All of the Executive directives used by DYNAMIC
(RDBBK$, WDBBK$,
DTRG$S,
EXIT$S, CRRG$S, CRAW$S, QIOW$S, and QIOW$C) to create and
manipulate the region are described in the RSX-llM/M-PLUS Executive
Reference Manual.
These directives are SYSGEN options on RSX-llM
systems.

5-40

SHARED REGION CONCEPTS AND EXAMPLES
Example 5-4, Part 1

Source Listing for DYNAMIC.MAC

.TITLE
• IDENT
.MCALL
.MCALL

DYNAMIC
/VOl/
RDBBK$,WDBBK$,DTRG$S,EXIT$S,CRRG$S,CRAW$S
QIOW$C, QIOW$S

• NLIST

BEX

REGION DESCRIPTOR BLOCK
WORD 0 SIZE OF REGION IN 32 DECIMAL WORD BLOCKS
WORD 1 REGION NAME
1111
WORD 2
WORD 3 NAME OF SYSTEM CONTROLLED PARTITION IN
WORD 4 WHICH REGION WILL BE CREATED
WORD 5 STATUS WORD
WORD 6 PROTECTION WORD
RDB:

RDBBK$

128.,,GEN,<RS.MDL!RS.ATT!RS.DEL!RS.RED!RS.WRT>,170017

WINDOW DESCRIPTOR BLOCK
WORD 0 APR TO BE USED TO MAP REGION
WORD 1 SIZE OF WINDOW IN 32-WORD BLOCKS
WORD 2 REGION ID
WORD 3 OFFSET INTO REGION TO START MAPPING
WORD 4 LENGTH IN 32-WORD BLOCKS TO MAP
WORD 5 STATUS WORD
WDB:
MESl:
ERRl:
ERR2:
ERR3:

WDBBK$
.ASCIZ
Sl = •
.ASCII
SIZl =
.ASCII
SIZ2 =
.ASCII
SIZ3 =
.EVEN
.PAGE
.ENABL

7,128.,0,0,,WS.MAP!WS.WRT>
/DYNAMIC IS NOW EXITING/
- MESl
/CREATE REGION FAILED/
. - ERRl
/CREATE ADDRESS WINDOW FAILED/
• - ERR2
/DETACH REGION FAILED/
• - ERR3

CRRG$S
BCS
MOV
CRAW$S
BCS
MOV
MOV
.REPT
ASL
• ENDR
MOV
MOV
INC
DEC
BGT
DTRG$S
BCS
QIOW$C
EXIT$S

#RDB
; CREATE A 128 WORD UNNAMED REGION
1$
; FAILED TO CREATE REGION
RDB+R.GID,WDB+W.NRID ; COPY REGION ID INTO WINDOW BLOCK
#WDB
CREATE ADDR WINDOW AND MAP
2$
FAILED TO CREATE ADDR WINDOW
WDB+W.NBAS,RO
BASE ADDR OF CREATED REGION
WDB+W.NSIZ,R2
NUMBER OF 32. WORDS IN REGION
5
MULTIPLY
R2
BY
32 •
#1,Rl
INITIAL VALUE TO PLACE IN REGION
Rl,(RO)+
MOVE VALUE INTO REGION
Rl
NEXT VALUE TO PLACE IN REGION
R2
ONE LESS WORD LEFT
20$
TO FILL IN
iRDB
DETACH AND DELETE REGION
3$
; DETACH FAILED
IO.WVB,5,1,,,,<MESl,Sl,40>

LSB

START:

20$:

(continued on next page)

5-41

SHARED REGION CONCEPTS AND EXAMPLES
Example 5-4, Part 1 (Cont.)

Source Listing for DYNAMIC.MAC

ERROR ROUTINES
1$:
2$:
3$:
6$:

MOV
MOV
BR
MOV
MOV
BR
MOV
MOV
QIOW$S
EXIT$S
.END

#ERRl,RO
CREATE FAILED
SIZE OF MESSAGE
#SIZl,Rl
WRITE MESSAGE
6$
#ERR2,RO
CREATE ADDRESS WINDOW FAILED
#SIZ2,Rl
SIZE OF MESSAGE
6$
#ERR3,RO
DETACH FAILED
#SIZl,Rl
; SIZE OF MESSAGE
#IO.WVB,#5,#1,,,,<RO,Rl,#40>
START

Once you have assembled DYNAMIC, you can build it with
TKB command sequence:

the

following

TKB>DYNAMIC,DYNAMIC/-WI/-SP=DYNAMIC
TKB>/
Enter Options:
TKB>WNDWS=l
TKB> //
This command sequence directs TKB to create a task image -named
DYNAMIC.TSK and an 80-column
(/-WI)
map file named DYNAMIC.MAP on
device SY: under the terminal UIC. Because /-SP is attached to the
map file, TKB does not output the file to the line printer.
Under options, the WNDWS option directs TKB to create one window block
over and above that required to map the task region.
Note that one
window block must be created for each region the task expects to be
mapped to simultaneously.
The map that results from this command sequence is
5-4, Part 2.

shown

Example

Note that creating dynamic regions always involves the assumption that
there will be enough room in the partition named in the task's region
descriptor block to create the region when the task is run.
In this
example, if DYNAMIC were to be run in a system whose partition GEN was
not large enough to accommodate the region it creates, the CREATE
REGION directive would fail.

5-42

SHARED REGION CONCEPTS AND EXAMPLES
Example 5-4, Part 2

DYNAMIC.TSK;l

Task Builder Map for DYNAMIC.TSK

Memory allocation map TKB M40.10
ll-DEC-82 16:05

Page 1

Partition name : GEN
Identification : VOl
Task UIC
[7,62]
Stack
limits: 000274 001273 001000 00512.
PRG xfr address: 001470
Total address windows: 2.
Task image size
512. WORDS
Task address limits: 000000 001753
R-W disk blk limits: 000002 000003 000002 00002.

*** Root segment: DYNAMI
R/W mem limits: 000000 001753 001754 01004.
Disk blk limits: 000002 000003 000002 00002.
Memory allocation synopsis:
Section

Title

• BLK.:(RW,I,LCL,REL,CON) 001274
001274
$DPB$$:(RW,I!LCL,REL,CON) 001724
001724

000430
000430
000030
000030

Ident

00280.
00280. DYNAMI VOl
00024.
00024. DYNAMI VOl

File
DYNAMIC.OBJ;l
DYNAMIC.OBJ;l

*** Task builder statistics:
Total work file references: 549.
Work file reads: o.
Work file writes: o.
Size of core pool: 7086. words (27. pages)
Size of work file: 768. words (3. pages)
Elapsed time:00:00:06

5.2

CLUSTER LIBRARIES

The term "cluster libraries" refers to both a function and a structure
created by the Task Builder (TKB) that allow a task to dynamically map
memory-resident shared regions at run time. Cluster libraries permit
a task to use, for example, a F77CLS library, an FMS-11 library, and
an FCS-11 library, all mapped through the same task address window.
The run-time routines put into the task by the Task Builder remap the
library regions so that, instead of occupying 48K bytes of virtual
address space, they share 16K bytes of virtual address space.
One task address window (window 1) maps the libraries into the same
span of virtual address space (48Kb to 64Kb). TKB maps your task from
virtual 0 upward.

5-43

SHARED REGION CONCEPTS AND EXAMPLES
TKB implements the cluster library function in two parts.
The first
part,
revectoring of interlibrary calls, is independent of the actual
remap mechanism but is required for remapping to work.
The second
part executes the required MAP$ directives to map the appropriate
library.
The following examples use the library and task structure shown in
Figure 5-10.
Note that in the following examples, the FMS-11/RSX Vl.O
and FORTRAN-77 software products are sold under separate license and
are not included with the ~Q.i!tij' or :R~~ll~,.:;;pJ:...tJS,'· system. Cluster
library support may be used with RMS-11 V2.0 or later versions, and
operates in a fashion similar to the FCS-11 example. Also, the
particular FCSRES used below is generated by SYSGEN.
It consists of
two PLAS overlays and a null root.
VIRTUAL
ADDRESS
64KB
FORTRAN OTS LIBRARY
F77CLS

FCS-11 LIBRARY
FCSRES

FMS-11 LIBRARY
FMSCLS

48KB

l
USER
TASK

ZK-492-81

Figure 5-10

5.2.1

Example Library and Task Structure

Building the Libraries

You must follow several rules when designing and building shareable
clustered libraries.
The rules are summarized next and discussed in
detail following the summary.

5.2.1.1

Summary of Rules for Building the Libraries -

•

All libraries but the first require resident overlays.

•

User task vectors
references.

•

Revectored entry point
"upstream" .STB file.

the

•

A called library procedure must not require parameters on
stack.

the

•

All the libraries must be PIC or built for the same address.

•

Trap or asynchronous entry into a library is not permitted.

indirectly
symbols

resolve
must

The rules are discussed in detail as follows.

5-44

all

not

interlibrary

appear

SHARED REGION CONCEPTS AND EXAMPLES
5.2.1.2

Rule 1: All Libraries but the First Require
Resident
Overlays - The first library is the first named library in
the CLSTR option line. To obtain the required run-time overlay data
structures in your task, you must define all the libraries except
possibly the first by using memory resident overlays. Although it can
be an overlaid library, the first library need not be and can be a
single-segment structure. All the libraries, except the first, must
have a null root if overlaid. You can achieve this in cases where a
library is not normally overlaid by creating an unbalanced overlay
structure with a null module.
For example, the following ODL
specification for FMSCLS and a null module would suffice:

NULL:
FMSLIB:

.NAME FMSCLS
.ROOT FMSCLS-*(NULL,FMSLIB)
.FCTR LB:[l,l]SYSLIB/LB:NULL
.FCTR SY:FMSLIB-LB: [l,l]FDVLIB/LB
.END

The above ODL specification creates an unbalanced
shown in Figure 5-11:

;NULL MODULE
; FMS-11 ROUT INES
tree

the

form

FMS-11 ROUTINES

NULL

ZK-427-81

Figure 5-11

Example of an Unbalanced Tree with Null Segment

The effect, after you build your task, is an overlay structure that is
represented in the Figure 5-12.
TKB provides the
overlay segment
library.

FORTRAN OTS

cross-library linkage that it creates from the
data contained in the individual .STB files of each

FMS-11 ROUTINES

FCS-11 ROUTINES

NULL

USER TASK

ZK-428-81

Figure 5-12

Example of an Overlay Cluster Library Structure

5-45

SHARED REGION CONCEPTS AND EXAMPLES
5.2.1.3

Rule
2: User
Task
Vectors
Indirectly
Resolve
all
Interlibrary References - Figure ~-13 below illustrates rule
2 and is a part of the example in Figure 5-12.
In Figure 5-13, if the
FORTRAN OTS library references an FCS-11 entry point .OPEN, the
transfer of control from the FORTRAN OTS library to the FCS-11 library
must be resolved by a jump vector in your task.
Or, to state it in
another way, the CALL instruction in the FORTRAN OTS library must not
reference directly the target address (the address of .OPEN) in the
FCS-11 library.
The system library contains the modules that perform
the
indirect transfer for FCS-11 based libraries and user tasks.
If
you want to duplicate the indirect referencing mechanism for your own
purposes, Figure 5-13 and the following text describe the control flow
for FCS-11.
FORTRAN OTS

FCS-11 LIBRARY
.OPEN::

FCSVEC
.OPEN::

Sample code from FCSVEC module:
.OPEN::

DISPAT:

MOV

#30,-(SP)

DISPAT

MOV
MOV
ADD
MOV
MOV
RETURN

RO,-(SP)
@#.FSRPT,RO
A.JUMP(R0),2(SP)
(SP)+,RO
@(SP)+,-(SP)

; STACK OFFSET INTO USER TASK
; JUMP TABLE
; JOIN COMMON DISPATCH

; SAVE REGISTER
; GET FCS-11 POINTER
; ADD VECTOR BASE TO OFFSET
; RESTORE REGISTER
; PICK UP ADDRESS OF TARGET
; AND TRANSFER TO TARGET
ZK-429-81

Figure 5-13

Example of a Vectored Call Between Libraries

In this example, the module FCSVEC defines the .OPEN entry point.
The
code at that location stacks an offset or "entry number" and joins
common dispatch code.
The dispatch code, using the low core FCS-11
impure pointer called .FSRPT, obtains the address of the FCS-11 impure
data area.
At offset A.JUMP in that area is the address of a vector
of FCS-11 entry points. A return is executed, which transfers control
to the routine whose address is now on top of the stack.
If the
target routine is an overlaid library, the run-time support ($AUTO)
loads the appropriate overlay and relays the transfer of control.
You may use this vectoring mechanism to isolate the linkages between
two libraries whether or not you use them in the cluster library
scheme.
You can replace either the FORTRAN OTS or the FCS-11 library
in your system without relinking the other library.
However, you must
relink your task when you replace either of these libraries.

5-46

SHARED REGION CONCEPTS AND EXAMPLES
5.2.1.4

Rule 3: Revectored Entry Point Symbols Must Not Appear in
the
"Upstream"
.STB
File - This rule means that the
GBLXCL=symbol option must appear for each revectored symbol, as in
FORTRAN OTS in this example.
In the brief example above, the
following line must appear in the build file for the FORTRAN OTS
library:
GBLXCL=.OPEN

5.2.1.5

Rule 4: A Called Library Procedure Must
Not
Require
Parameters on the Stack - This rule applies to routines
contained in libraries other than the
"default"
library,
as
represented by the FMSCLS and FCSRES libraries of the above example.
In addition, the called procedures must use the JSR PC and RTS PC call
and return convention. The flow of control for a call into a cluster
library member other than the default proceeds as follows.
Only your task can call and reference the FCSRES library routine
.OPEN.
All references from other libraries are revectored as
described above. TKB resolves all such references to an appropriate
task resident autoload vector. As in the example, when the FORTRAN
OTS library calls .OPEN, the code revectors the call through your task
and hence to the autoload vector. At this point, the TKB run-time
routine $AUTO gets control and searches the overlay segment descriptor
tree, noting which segments are resident and which must be loaded or
mapped to access the target routine.
Next, $AUTO notes that a member of a library cluster must be unmapped
to comply with the map adjustments required to access the target
routine. The reference to the unmapped library and the segment within
the library is placed on the stack, the target library is mapped, and
the target routine is accessed through a JSR PC instruction.
That
target routine must not attempt to access parameters by offsets from
the stack pointer
(SP)
because of the presence of $AUTO saved
information.
Upon return from the target by an RTS PC instruction,
the target library is unmapped, and the previous library remapped
using the saved segment and library data on the stack. Finally, $AUTO
executes an RTS PC instruction to return to the caller.
Note that if your task contains a mix of cluster libraries and
noncluster libraries, the call format rule applies only to control
transfers to cluster library routines.
Other noncluster libraries
that you create may use any appropriate call and parameter passing
convention.

5.2.1.6

Rule 5: All the Libraries Must be PIC or Built for the Same
Address - TKB must be able to place each library of the
cluster at the same virtual address. To do this, the libraries must
be built as position independent or be built to the exact address
specified in the CLSTR command described below.

5.2.1.7

Rule 6: Trap or Asynchronous Entry Into a Library is not
Permitted - A routine built as part of a library that is to
be used in a cluster may not be specified as the service routine for a
synchronous trap, or for asynchronous entry as a result of I/O
completion or Executive service. This restriction is required because
at the moment of the trap or fault, the appropriate library may not be
the one that is mapped. For example, if the default library contains
the service routine to display an error message upon odd address trap
(the odd address fault occurs within one of the other libraries of the
5-47

SHARED REGION CONCEPTS AND EXAMPLES
cluster),
the routine will not be available to service the trap.
It
will have been unmapped by the run-time routines to map the called
library.
I/O completion and fault service vectors and routines must be placed
in libraries or task segments that are resident at all times that the
fault, trap, or I/O completion may occur.

5.2.2

Building Your Task

After building the individual libraries and placing the .TSK and
.STB
files for all the libraries into the LB:[l,l] directory, you may build
your task.
The TKB option line that you must use for your task has
the following syntax:
CLSTR=library l,library_2, ••• library_n:switch:apr
library_n
The first specification denotes the first or the default library,
which is the library to which the task maps when the task starts
up and remaps after any call to another library.
In an RSX-llM or RSX-llM-PLUS system,
the total number of
libraries to which a task may map is seven.
The number of the
component libraries in clusters is limited to a maximum of six.
A cluster must contain a minimum of two libraries.
It is
possible to have two clusters of three libraries each or three
clusters of two libraries each;
any combination of clusters and
libraries must equal at least two or a maximum of six.
If six
libraries are used
in clusters,
the task may map to only one
other, separate library.
:switch:apr
The switch :RW or :RO indicates whether the cluster is read-only
or read-write for this particular task.
The APR specification is
optional and indicates which APR is to be used as the starting
APR when mapping to cluster libraries.
If not specified, TKB
assigns the highest available APRs and as many as required to map
the library.

5.2.3

Examples

The sample build files for F77CLS, FDVRES, and FCSRES,
and for
the
FMS-11 demonstration task FMSDEM are appended as an example of the
cluster library-build process.

5.2.3.1

F77CLS -- Build the Default Library for the FORTRAN-77 OTS -

>TKB
TKB>F77CLS/-HD,F77CLS/CR/-SP/MA,F77CLS=F77RES
TKB>LB: [l,l]F770TS/LB
TKB>LB:[l,l]SYSLIB/LB:FCSVEC
; INCLUDE THE FCS JUMP VECTOR
TKB> I
Enter Options:
STACK=O
PAR=F77CLS:l40000:40000

5-48

SHARED REGION CONCEPTS AND EXAMPLES

FORCE THE JUMP TABLE TO BE LOADED FROM THE SYSTEM
LIBRARY WHEN THE USER TASK IS BUILT
; REFERENCE SYMBOL DEFINED IN
; THE MODULE SYSLIBILB:FCSJMP

GBLINC=.FCSJT
;

; PREVENT DEFINITIONS FOR FCS-11 ENTRY POINTS FROM APPEARING
; IN THE .STB FILE FOR THIS LIBRARY OR OTHER SYSTEM LIBRARY
GBLXCL=.CLOSE
GBLXCL=.CSil
GBLXCL=.CSI2
GBLXCL=.DLFNB
GBLXCL=.FINIT
GBLXCL=.GET
GBLXCL=.GETSQ
GBLXCL=.GTDID
GBLXCL=.MRKDL
GBLXCL=.OPFNB
GBLXCL=.PARSE
GBLXCL=.POINT
GBLXCL=.POSRC
GBLXCL=.PRINT
GBLXCL=.PUT
GBLXCL=.PUTSQ
GBLXCL=.SAVRl
GBLXCL=.READ
GBLXCL=.WAIT

II
The GBLINC option as shown above forces TKB to add a global reference
entry in the library .STB file.
This ensures that TKB links certain
modules required by the library, such as impure data areas or
root-only routines, without further user action.
These modules should
be in the system library (LB:[l,l]SYSLIB.OLB) or in a library always
referenced by your task, so that this forced loading mechanism is
entirely invisible to you.

5.2.3.2

FDVRES -- Build an FMS-lllRSX Vl.O Shareable Library TITLE OF THE EXAMPLE COMMAND FILE THAT BUILDS THE FORMS
MANAGEMENT PLAS-RESIDENT LIBRARY FOR USE WITH THE
TASK BUILDER CLSTR OPTION.
FDVRES.CMD
THE FOLLOWING CODE IS THE EXAMPLE COMMAND FILE:

;

LB:[l,l]FDVRESl-HDIMMISG,MP:[l,34]FVRESIMAl-SP,LB:[l,l]FDVRES=
SY:[l,24]FDVRESBLDIMP
STACK=O
PAR=FDVRES:l40000:40000
TASK=FDVRES
;

; THE FOLLOWING LINE FORCES THE FCS JUMP TABLE TO BE INCLUDED IN THE
; SYMBOL TABLE FILE FOR THE FORMS MANAGEMENT LIBRARY.
;

GBLINC=. FCSJT

5-49

SHARED REGION CONCEPTS AND EXAMPLES

THE FOLLOWING LINES FORCE LIBRARY ENTRY POINTS AND DEFINITIONS INTO
THE TASK ROOT:
;

GBLREF=CB$CUR,CB$REV,CB$TST,CB$132,DV$BLD,DV$BLK,DV$DHW,DV$DWD
GBLREF=DV$GRA,DV$REV,DV$UND,D$ATT1,D$ATT2,D$CLRC,D$FID,D$FXLN
GBLREF=D$LNCL,D$PICT,D$PLEN,D$RLEN,D$VATT,D$2ATT,Dl$ALN,Dl$ALP
GBLREF=Dl$ARY,Dl$COM,Dl$MIX,Dl$NUM,Dl$SCR,Dl$SNM,D2$DEC,D2$DIS
GBLREF=D2$FUL,D2$NEC,D2$REQ,D2$RTJ,D2$SPO,D2$TAB,D2$VRT,D2$ZFL
GBLREF=FC$ALL,FC$ANY,FC$CLS,FC$CSH,FC$DAT,FC$GET,FC$GSC,FC$LST
GBLREF=FC$0PN,FC$PAL,FC$PSC,FC$PUT,FC$RAL,RC$RTN,FC$SHO,FC$SLN
GBLREF=FC$SPF,FC$SPN,FC$TRM,FE$ARG,FE$DLN,FE$DNM,FE$DSP,FE$FCD
GBLREF=FE$FCH,FE$FLB,FE$FLD,FE$FNM,FE$FRM,FE$FSP,FE$ICH,FE$IFN
GBLREF=FE$IMP,FE$INI,FE$IOL,FE$IOR,FE$LIN,FE$NOF,FE$NSC,FE$STR
GBLREF=FE$UTR,FE$INC,FS$SUC,FT$ATB,FT$KPD,FT$NTR,FT$NXT,FT$PRV
GBLREF=FT$SBK,FT$SFW,FT$SNX,FT$SPR,FT$XBK,FT$XFW,F$ASIZ,F$CHN
GBLREF=F$FNC,F$IMP,F$LEN,F$NAM,F$NUM,F$REQ,F$RSIZ,F$STS
GBLREF=F$TRM,F$VAL,IS$ALT,IS$CLR,IS$DEC,IS$DSP,IS$ERR,IS$HFM
GBLREF=IS$HLP,IS$INS,IS$LST,IS$MED,IS$NMS,IS$SCR,IS$SGN,I$ADVO
GBLREF=I$ALLC,I$BADR,I$BEND,I$BPTR,I$BSIZ,I$CFRM,I$CURC,I$CURP
GBLREF=I$DISP,I$DLN1,I$DLN2,I$FADR,I$FBLK,I$FCHN,I$FDES,I$FDST
GBLREF=I$FDS1,I$FDS2,I$FIXD,I$FMST,I$FOFF,I$FORM,I$FSIZ,I$FXD1
GBLREF=I$FXD2,I$HLEN,I$HLPF,I$ILEN,I$IMPA,I$LCOL,I$LINE,I$LLIN
GBLREF=I$LNCL,I$LPTR,I$LVID,I$NBYT,I$NDAT,I$NFLD,I$PATN,I$PBLN
GBLREF=I$RESP,I$ROFF,I$STAT,I$STKP,I$SVST,I$VATT,L$CLSZ,L$FDES
GBLREF=L$LNCL,L$RESP,$$FDVT
GBLREF=$FDV
;

; THE FOLLOWING LINES PREVENT THE DEFINITIONS FOR FCS-11 ENTRY POINTS
; FROM APPEARING IN THE FORMS MANAGEMENT LIBRARY .STB FILE:
;

GBLXCL=.ASCPP
GBLXCL=.ASLUN
GBLXCL=.CLOSE
GBLXCL=.CTRL
GBLXCL=.DELET
GBLXCL=.DLFNB
GBLXCL=.ENTER
GBLXCL=.EXTND
GBLXCL=.FATAL
GBLXCL=.FCTYP
GBLXCL=.FIND
GBLXCL=. FINIT
GBLXCL=.FLUSH
GBLXCL=.GET
GBLXCL=.GETSQ
GBLXCL=.GTDID
GBLXCL=.GTDIR
GBLXCL=.MARK
GBLXCL=.MBFCT
GBLXCL=.MRKDL
GBLXCL=.OPEN
GBLXCL=.OPFID
GBLXCL=.OPFNB
GBLXCL=.PARSE
GBLXCL=. POINT
GBLXCL=.POSIT
GBLXCL=.POSRC
GBLXCL=.PPASC
GBLXCL=.PPR50
GBLXCL=. PRINT

5-50

SHARED REGION CONCEPTS AND EXAMPLES
GBLXCL=.PRSDI
GBLXCL=.PRSDV
GBLXCL=.PRSFN
GBLXCL=. PUT
GBLXCL=.PUTSQ
GBLXCL=.RDFDR
GBLXCL=.RDFFP
GBLXCL=.RDFUI
GBLXCL=.SAVRl

5.2.3.3

FDVRESBLD.ODL -- Overlay

Description

for

FMS-lllRSX

...... ,

v l.. v

Cluster Library THE FOLLOWING LINE IS THE FILENAME OF THE .ODL FILE FOR THE
PLAS-RESIDENT FORMS MANAGEMENT LIBRARY:
FDVRESBLD.ODL
THE FOLLOWING LINES OF CODE ARE CONTAINED IN THE .ODL FILE FOR THE
PLAS-RESIDENT FORMS MANAGEMENT LIBRARY:

NULO:
FCSV:
MAIN:

.NAME
.ROOT
.FCTR
.FCTR
.FCTR
.END

FDVROT
FDVROT-*!(MAIN,NULO)
LB: [l,l]SYSLIBILB:NULL
LB:[l,l]SYSLIBILB:FCSVEC
LB:[l,l]FDVLIBILB:FDV-LB:[l,l]FDVLIBILB-FCSV

5.2.3.4 FCSRES Library Build - FCSRSlBLD.BLD is distributed with the
RSX-llM and RSX-llM-PLUS distribution kits.
Refer to the build
command and overlay description contained in the files FCSRSlBLD.CMD
and FCSRSlBLD.ODL, which can be generated by SYSGEN if you want.

5.2.3.5

F77TST.CMD -- File to Build the FMS-11/RSX Vl.O
Task -

FORDEM

Test

FORDEMIFP,FORDEMIMAl-SP=FORDEM,HLLFOR
LB; [l,l]FDVLIBILB
LB:[l,l]F770TSILB

I
EXTSCT=$$FSR1:2000
CLSTR=F77CLS,FDVRES,FCSRES:RO
STACK=200

5.2.4

Overlay Run-Time Support Requirements

The Task Builder uses the .STB files of the cluster libraries to
obtain ~ne information needed to create the overlay data base. For
each PLAS overlaid cluster library TKB places autoload vectors,
segment descriptors, window descriptors, and a region descriptor in

5-51

SHARED REGION CONCEPTS AND EXAMPLES
the root of the task.
This information comprises the overlay run-time
support for the cluster libraries.
In Appendix B, Figure B-9 and the
accompanying text describe this information.
Table 5-1 describes the
space needed for
the overlay run-time system support that includes
cluster libraries.
For a complete description of overlay run-time
routine sizes, see Section 4.5.
Using cluster libraries conserves virtual space and may
one window.

require

only

Table 5-1
Comparison of Overlay Run-Time Module Sizes

Module

Program
Section

Number
of Bytes
Oct/Dec

Specific Use

One of the following modules is included in any overlaid task
that uses autoload./and in any task that links to a PLAS overlaid
resident library.~
AUTO

$$AUTO

122/82.

All tasks that use autoload

AU TOT

$$AUTO
$$RTQ
$$RTR

132/90.
32/26.
30/24.

All tasks with AST's
disabled during autoload

One of the following modules
is
included in any overlaid
conventional
task.
OVCTR
or OVCTC is included
in any
non-overlaid task (conventional or I~ ~id~D- space)
that links
to a PLAS overlaid resident library.
OVCTL

$$MRKS
$$RDSG
$$POLS

76/62.
160/112.
2/2.

Disk overlays only

OVCTR

$$MRKS
$$RDSG
$$POLS

234/156.
332/218.
12/10.

Disk and PLAS overlays with no
cluster libraries

OVCTC

$$MRKS
$$RDSG
$$POLS

254/172.
352/234.
120/80.

Disk and PLAS overlays
with cluster libraries

One of the following three.modules is includ~d in· any
r- and o~space task.
OVIDL

$$MRKS
$$RDSG
$$POLS

76/62.
224/148.
2/2.

Disk overlays only

OVIDR

$$MRKS
$$RDSG
$$POLS

304/196.
502/322.
12/10.

Disk- and PLAS overlays
with no cluster libraries

OVIDC

$$MRKS
$$RDSG
$$POLS

324/212.
522/338.
120/80.

Di~k

overlaid

and -PLAS overlays

with cluster libraries
(continued on next page)

5-52

SHARED REGION CONCEPTS AND EXAMPLES
Table 5-1 (Cont.)
Comparison of Overlay Run-Time Module Sizes

Module

Program
Section

Number
of Bytes
Oct/Dec

Specific Use

The overlay data vector OVDAT is included in any overlaid task
and in any task that links to a PLAS overlaid resident library.
OVDAT

$$0VDT
$$SGDO
$$SGD2
$$RTQ
$$RTR
$$RTS

24/20.
0/0.
2/2.
0/0.
0/0.
2/2.

Included in all tasks
that perform overlay
operations

The overlay error service routine
OVDAT is included.
ALERR

$$ALER

24/20.

ALERR

5.3

$$LOAD
$$AUTO

252/170.
14/12.

included

whenever

Overlay error

Manual overlay control (LOAD) is used
in
routine.
(See Section 4.2, Manual Load.)
LOAD

place

any

AUTO

Manual overlay control

VIRTUAL PROGRAM SECTIONS

A virtual program section is a special TKB storage allocation facility
that permits you to create and refer to large data structures by means
of the mapping directives. Virtual program sections are supported
in
TKB through the VSECT option and
in FORTRAN through a set of
FORTRAN-callable subroutines that issue
the
necessary
mapping
directives at run time. With the TKB VSECT option, you can specify
the following parameters for a relocatable program section or FORTRAN
common block that you have defined in your object module:
•

Base virtual address

•

Virtual length (window size)

•

Physical length

By specifying the base address, you can align the program section on a
4K
address
boundary
as
required by the mapping directives.
Thereafter, references within the program need only point to the base
of the program section or to the first element in the common block to
ensure proper boundary alignment.
By specifying the window size, you can fix
the amount of virtual
address space that T~~ allocates to the program section.
If the
allocation made by a module causes the total size to exceed this
limit, the allocation wraps around to the beginning of the window.

5-53

SHARED REGION CONCEPTS AND EXAMPLES
By specifying the physical size, you can allocate, before run time,
the physical memory that the program section will be mapped into at
run time.
TKB allocates this physical memory within an area that
precedes the task image.
This area is called the mapped array area.
The physical length parameter is optional.
If you intend to allocate
physical memory at run time through the Create Region directive, you
can specify a value of O.
Note that when you specify a nonzero value for
the physical memory
parameter,
the resulting allocation affects only the task's memory
image, not its disk image.
Note also that TKB attaches the virtual attribute to a relocatable
program section you have specified in the VSECT option only if the
section is defined in the root segment of your task through either a
FORTRAN COMMON or a MACR0-11
.PSECT statement.
The relocatable
program section with the virtual attribute in the root does not use
address space in your task;
using this procedure merely assigns an
address, window size, and physical length to a region yet to be mapped
at run time by your task.
For example:
TKB>VSECT=MARRAY:l60000:20000:2000
In this
window
address
mapping

example, virtual program section MARRAY is allocated with a
size of 4K words
(20000
(octal) bytes) and a base virtual
of 160000.
In physical memory, 32K words are reserved for
the section at run time.

Assume the program is written in FORTRAN, and includes
statement:

the

following

COMMON /MARRAY/ARRAY(4) ..•
This statement generates a program section to which TKB attaches the
virtual attribute.
However,
this program section is not a FORTRAN
virtual array. A reference to the first element of the section,
ARRAY(l), is translated by TKB to the virtual address 160000.
Figure 5-14 shows the effect of this use of the VSECT option.
As mentioned previously, TKB restricts the amount of virtual address
space allocated to the section to a value that is less than or equal
to the window size, wrapping around to the base if the window size is
exceeded.
This process is illustrated in the following example, in which three
modules,
A, B, and C, each contain a program section named VIRT that
is 3000 words long. A window size of 4K words has been set through
the VSECT option.
If the program section has the concatenate
attribute, the Task Builder allocates memory to each module as
follows:
Module

Low Limit

Length

High Limit

160000
174000
170000

14000
14000
14000

174000
170000
164000

The address limits for modules B and C illustrate the effect of
address wrap-around when a component of the total allocation exceeds
the window boundary.
Note that the addresses generated will be
properly aligned with the contents of physical memory if the virtual
section is remapped in increments of the window size.

5-54

SHARED REGION CONCEPTS AND EXAMPLES

WINDOW
160000 APR 7 -

l ! ::o~~s~~ ______ l\llllllllllillllllllll
'•(VIRTUAL BASE ADDRESS)

APR6-

APR 5 -

APR4-

TASK
IMAGE

APR3-

APR2-

(PROGRAM
0 SECTION
DEFINITION)

APR 1 -

APRO-

COMMON/MARRAY / ...

COMMON/MARRAY/ ...

HEADER & STACK

HEADER & STACK
------------- 7

VIRTUAL ADDRESS
SPACE

TKB>/
ENTER OPTIONS:
TKB>VSECT =MARRAY:160000:20000:2000

PHYSICAL LENGTH~
64-BYTE BLOCKS

MAPPED
ARRAY
AREA

o e o

111iltl\\I
PHYSICAL MEMORY

ZK-430-81

Figure 5-14

VSECT Option Usage

5-55

SHARED REGION CONCEPTS AND EXAMPLES
5.3.1

FORTRAN Run-Time Support for Virtual Program Sections

FORTRAN supports subroutines to make use of the mapping directives.
FORTRAN also supports calls to the following subroutines, which are
related to virtual program sections:
Subroutine

Function

ALSCT

Allocates a portion of physical memory
virtual section

for

use

RLSCT

Releases all physical memory
section

virtual

allocated

As mentioned earlier, the effect of one or more VSECT= declarations at
task-build time is to create a pool of physical memory below the task
image (the mapped array area) • Before a virtual section is referred
to,
the task must allocate a portion of this memory through a call to
ALSCT.
When space is no longer required, it is released through a
call to RLSCT.
Note that these subroutines issue no mapping directives.
They
allocate and release space using region and window descriptor arrays
that you supply. The resulting physical offsets are used
in the
task's subsequent calls that perform the actual mapping.
The subroutine ALSCT is called to
virtual program section as follows:

allocate

physical

memory

CALL ALSCT (ireg,iwnd[,ists])
ireg
A one-dimensional
integer array that is nine words
long.
Elements 1 through 8 of the array contain a region descriptor for
the physical memory to be mapped.
The descriptor has the
following format:
ireg(l)

Region ID.

ireg(2)

Size of region in units of 64-byte blocks.

ireg(3)

Name of region
characters).

ireg(4)

(Second three characters).

ireg(5)

Name of main partition containing region.

ireg(6)

The name is in Radix-50 format.

ireg(7)

Region status word.

ireg(8)

Region protection code.

ireg(9)

Thread word:
This element links window descriptors
that are used to map portions of the region.
It is
maintained by the subroutine.

Radix-50

format

(first

three

The elements of the array that you set up consist of ireg(l)
and
ireg(3)
through ireg(8).
The thread word, ireg(9), must be 0 on
the initial call;
thereafter, the subroutine maintains it.

5-56

SHARED REGION CONCEPTS AND EXAMPLES
When your task makes an allocation, ireg(l) and ireg(2) must be 0
on the initial call.
In this case, ALSCT obtains and stores the
region size in ireg(2). When the allocation is being made from a
separate region, the caller must supply both region ID and size.
The subroutine does not refer to elements 3 through 8 but rather
the caller must set them up as required by the applicable system
directives.
For a detailed description of these parameters,
refer to the RSX-llM/M-PLUS Executive Reference Manual.
iwnd
A one-dimensional array that is 11 words long.
The first
words contain a window descriptor in the following format:

eight

i wnd ( 1)

Base APR in bits 8 through 15;
bits 0 through 7 when the
directives are issued.

iwnd(2)

Virtual base address.

i wnd ( 3)

Window size in units of 64-byte blocks.

iwnd(4)

Region ID.

i wnd ( 5)

Offset into the region, in units of 64-byte blocks.

iwnd(6)

Length to map, in units of 64-byte blocks.

i wnd ( 7)

Status word.

i wnd ( 8)

Address of send/receive buffer.

iwnd(9)

Base offset of physical block allocated
in units of 64-byte blocks.

iwnd(lO)

Length of block in units of 64-byte blocks (supplied
by
caller);
set to maximum block offset by
subroutine.

iwnd(ll)

Thread word:
This element links window descriptors
that are used to map other portions of the region.
It is maintained by the subroutine.

the Executive sets
appropriate mapping

section

You must set up IWND(lO) before calling ALSCT.
The following array elements are
subroutine:

supplied

output

from

the

i wnd ( 4 ) , i wnd ( 5) , i wnd ( 9) , i wnd ( 10) , and i wnd ( 11)
The remaining elements must be set up as
required by the
Executive
directives.
Consult the RSX-llM/M-PLUS Executive
Reference Manual for a detailed description of these parameters.

5-57

SHARED REGION CONCEPTS AND EXAMPLES
ists
An area that receives the result
following values is returned:

the

call.

One

the

Block successfully allocated.
In this case, the region
and window descriptor arrays are set up as described
above.

-200.

Insufficient physical
allocating the block

memory

was

available

The subroutine RLSCT is called to deallocate
assigned to a virtual section as follows:

the

physical

for
memory

CALL RLSCT ( i reg , i wnd)
ireg
A one-dimensional integer array that is nine words long.
The
contents of the array are the same as those described for
subroutine ALSCT.
iwnd
A one-dimensional integer array that is 11 words long.
The
contents of the array are the same as those described for
subroutine ALSCT.
Upon return, element iwnd(lO) is the length
region in units of 64-byte blocks.
The procedure
follows:

5.3.2

for

using

these

subroutines

can

the
be

deallocated

summarized

You allocate storage in the program for one window descriptor
per VSECT, and for a single region descriptor.

Your task calls the subroutine ALSCT to reserve the
memory to which the program section will be mapped.

Your task issues the mapping directives to map the virtual
address space into a portion of the physical memory.
It is
the task's responsibility to ensure that the physical memory
to be mapped is always within the limits defined by iwnd(9)
and i wnd ( 10) •

When the space is no longer required, the task unmaps it
releases it with a call to RLSCT.

Example 5-5:
Section

Building a Program that uses

Virtual

physical

and

Program

Example 5-5, Part 1 shows the FORTRAN source file for a task named
VSECT.FTN.
It
illustrates the use of the ALSCT FORTRAN subroutine.
When you build, install, and run VSECT, it will allocate the mapped
array area below its header, create a 4K-word window, and map to the
area through the window. ALSCT will
then initialize the area and
prompt for an array subscript at your terminal by printing:
SUBSCRIPT?

5-58

SHARED REGION CONCEPTS AND EXAMPLES

When you input a subscript, it responds with ELEMENT= and the contents
of the array element for the subscript you typed. VSECT continues to
prompt until you type CTRL/Z.
Upon receiving a CTRL/Z, VSECT exits.
Once you have compiled VSECT, you can build it with the following Task
Builder command sequence:
TKB>VSECT,VSECT/-SP=VSECT,LB: [l,l]FOROTS/LB
TKB>/
Enter Options:
TKB>WNDWS=l
TKB>VSECT=MARRAY:l60000:20000:200
TKB>//
This command sequence directs TKB to create a task image file named
VSECT.TSK and a short (by default) map file VSECT.MAP. Because /-SP
is appended to the map file, TKB does not output the map to the line
printer.
The library switch (/LB) specifies that TKB is to search the FORTRAN
run-time library FOROTS.OLB to resolve any undefined references in the
input module VSECT.OBJ. Because the library switch was applied to the
FORTRAN library file without arguments, TKB extracts from the library
and includes in the task image any modules in which references are
defined.
The WNDWS option directs TKB to add a window block to the header in
the task image. The Executive initializes this window block when it
processes the mapping directives within the task.
The VSECT option directs TKB to establish for
the program section
named MARRAY a base address of 160000
(APR 7)
and a length of
20000(octal) bytes (4K words).
The program section VIRT is defined
within the task through the FORTRAN COMMON statement. The VSECT
option also specifies that TKB is to allocate 200 64-byte blocks of
physical memory in the task's mapped array area below the task's
header.
(For more information on the switches and options used in
this example, refer to Chapters 10 and 11.)
The map that results from this command sequence is
5-5, Part 2.
Example 5-5, Part 1

shown

Example

Source Listing for VSECT.FTN

c
C

VSECT.FTN
INTEGER *2 SUB,IRDB(9) ,IWDB(ll) ,DSW
INTEGER *2 IARRAY(4096)
COMMON /MARRAY/IARRAY
IWDB (1)
"3400
!USE APR 7 FOR WINDOW
IWDB (3) = 128
!WINDOW SIZE = 128*32 WORDS
IWDB (5) = 0
!OFFSET
IWDB (7) = "402
!STATUS = WS.64B!WS.WRT
IWDB (10) = 128
!SIZE TO ALLOCATE

(continued on next page)

5-59

SHARED REGION CONCEPTS AND EXAMPLES

Example 5-5, Part 1 (Cont.)

Source Listing for VSECT.FTN

c
C

ALLOCATE 4K MAPPED ARRAY TO IWDB,IRDB
CALL ALSCT {IRDB,IWDB,DSW)
IF {DSW .NE. 1) GOTO 100
CREATE A 4K ADDRESS WINDOW
CALL CRAW {IWDB,DSW)
IF {DSW .NE. 1) GOTO 200

MAP 4K' MAPPED ARRAY

CALL MAP {IWDB,DSW)
IF (DSW .NE. 1) GOTO 300
DO 1 I=l,4096
!ARRAY (I) = I

MAPPED ARRAY IS INITIALIZED, PROMPT FOR A SUBSCRIPT

3
5

WRITE (5,5)
FORMAT ('$SUBSCRIPT?')
READ (5,4,END=lOOO)SUB
FORMAT (!7)
WRITE (5,6)IARRAY (SUB)
FORMAT ( ' ELEMENT= ',!7)
GOTO 3

c
4
6

c
c
c
100
101
200
201
300
301
1000

ERROR ROUTINES
WRITE {5,lOl)DSW
FORMAT (' ERROR FROM ALSCT. ERROR= ',I7)
GOTO 1000
WRITE (5,20l)DSW
FORMAT {' ERROR FROM CREATING ADDRESS WINDOW. ERROR
GOTO 1000
WRITE (5,30l)DSW
I , I 7)
FORMAT (' ERROR FROM MAPPING. ERROR
CALL EXIT
END

5-60

I 7)

SHARED REGION CONCEPTS AND EXAMPLES
Example 5-5, Part 2
VSECT.TSK;l

Task Builder Map for VSECT.TSK

Memory allocation map TKB M40.10
ll-DEC-82
16:12

Page 1

Partition Name
GEN
Identification
FORV02
Task UIC
[303,1]
Stack
limits: 000300 001277 001000 00512.
PRG xfr address: 016270
Total address windows: 2.
Mapped array area: 4096. words
Task image size
8736. words
Task address limits: 000000 042043
R-W disk blk limits: 000002 000044 000043 00035.

*** Root segment: VSECT
R/W mem limits: 000000 042043 042044 17444.
Disk blk limits: 000002 000044 000043 00035.
Memory allocation synopsis:
Section

Title

-------

BLK.: (RW, I, LCL, REL ,CON) 001300 001160
MARRAY: (RW,D,GBL,REL,OVR) 160000 020000
160000 020000
OTS$F : (RW,I,GBL,REL,CON) 002460 002332
002460 000406
003066 001724
OTS$I : (RW,I,LCL,REL,CON) 005012 011220

Ident

File

00624.
08192.
08192. .MAIN. FORV02 VSECT.OBJ;3
01242.
00262. $CONVI F40003 FOROTS.OLB;2
F40006 FOROTS.OLB;2
00980. $FIO
04752.

Global symbols:
ADI$IA 005032-R

CAL$

005140-R

ICI$

022466-R

*** Task builder statistics:
Total work file references: 27855.
Work file reads: o.
Work file writes: o.
Size of core pool: 7086. words (27. PAGES)
Size of work file: 4325. words (17. PAGES)
Elapsed time:00:00:29

5-61

MOI$PS 006050-R

CHAPTER 6

PRIVILEGED TASKS

6.1

INTRODUCTION

This chapter discusses privileged tasks:
what they are,
their
possible hazards, how they are mapped, and an example of their usage.

6.2

PRIVILEGED AND NONPRIVILEGED TASK DISTINCTION

RSX-llM/M-PLUS systems have two classes of tasks:
privileged and
nonprivileged.
The distinction between privileged and nonprivileged
tasks is primarily based upon system-access capabilities. Because all
tasks in an unmapped system have access to all of memory, this
distinction is not hardware enforceable.
Therefore, if your system is
unmapped, your task must be responsible for observing the access rules
of your system.
In a mapped system, privileged tasks have special device and memory
access rights that nonprivileged tasks do not have.
A privileged task
can, with certain exceptions, access the Executive routines and data
structures;
a nonprivileged task cannot.
Some privileged tasks have
automatic I/O page mapping available to them;
nonprivileged tasks do
not.
Finally, a privileged task can bypass system security features,
whereas a nonprivileged task cannot.

6.3

PRIVILEGED TASK HAZARDS

Because of their special access rights, privileged
tasks
are
potentially hazardous to a
running system.
A privileged task with
coding errors can corrupt the Executive or system data structures.
Moreover, problems caused by such a privileged task can be obscure and
difficult to isolate.
For these reasons, you must exercise caution
when developing and running a privileged task.
Make certain that your privileged task has completed its operation
when you log off the system (type BYE). BYE does not abort privileged
tasks as it does nonprivileged tasks because the privileged task may
be in the process of changing the system data base.
Therefore, it
must be allowed to complete its processing. Also, if the privileged
task is in system state, neither BYE nor any other task can execute
until the privileged task completes its processing while in system
state.
However,
when ~ne privileged task leaves system state, BYE
runs and logs you off the system, leaving the privileged task still in
operation.

6-1

PRIVILEGED TASKS
If a processor trap occurs in a privileged task while the task is in
user state, the Executive aborts the task.
However, if the processor
trap occurs in the privileged task while the task is in system state,
the system crashes. However, even while in user state the privileged
task that is mapped to the Executive can cause a system crash by
incorrectly changing system data.
Please note that a privileged task
in user state should not be modifying system data.
All tasks in an unmapped system can access all of memory.
The
privileged or nonprivileged designation has no particular meaning in
an unmapped system. Therefore, be just as careful about modifying
Executive, device, or user data in an unmapped system.

6.4

SPECIFYING A TASK AS PRIVILEGED

You designate a task as privileged with the /PR
(privileged)
TKB
switch
(this switch is described in Chapter 10). TKB allocates
address space for a privileged task based on the memory management APR
that you specify as an argument to this switch. The argument is
optional;
the default is 5 but you can change it by modifying the
TKBBLD.CMD file and rebuilding TKB.
TKB accepts three arguments:
0,
4, and 5. Choosing which of these arguments to specify is based on
the considerations described below.

6.5

PRIVILEGED TASK MAPPING

When you specify an argument of O, your task is marked as privileged
but not mapped to the Executive or I/O page. Virtual address space
begins at virtual address 0 and extends upward as far as 32K words.
Your task cannot access the Executive routines or data structures, and
TKB does not reserve an APR to map the I/O page.
When you specify /PR:4 or /PR:5, TKB reserves APR 7 for mapping the
I/O page. Moreover, TKB makes the Executive available to your task by
reserving the APRs necessary to map the Executive into your task's
virtual address space. Therefore, if your task requires access to the
Executive, you must specify an argument of either 4 or 5. However,
5
is the default.
The choice between APR 4 and 5 is dictated by the size of the
Executive area.
If the Executive is 16K words or less, you may
specify an argument of 4 or 5. The value specified depends on the
task size. A /PR:4 task can be 12K in size and map the I/O page. TKB
applies a bias of 100000 (16K) to all addresses within your task.
If the Executive is 20K words, you must specify an argument of 5.
applies a bias of 120000 (20K) to all addresses within your task.

TKB

The mapping for privileged tasks is shown in Figure 6-1.
The mapping for APR 4 and 5 is shown in Figure 6-2.
When you specify an argument of 4, there will be 12K words of address
space between the beginning of the task and the start of the mapping
for the I/O page.
If your task expects to access the I/O page,
it
must not exceed this 12K-word limit.
If it does, TKB uses APR 7 to
map the task instead of the I/O page.
When you specify an argument of 5, there will be BK words of address
space between the beginning of the task and the start of the mapping
for the I/O page.
In this case, the task must not be greater than BK
words if it expects to access the I/O page.
6-2

PRIVILEGED TASKS

KT-11 MEMORY
MANAGEMENT UNIT

PHYSICAL MEMORY

1/0 PAGE

APRs (UISAR 0-7)

1/0 PAGE

8K
PRIVILEGED
TASK

Ht@§~~t:§f8!:§:f~ff!:::::::::::::::::
:::1:1:~:~::iY::g:~~::£§:~:::::::m1::::::
~::tt:fffi:Y.::fo~F§:~FI:::::mt::

VIRTUAL
ADDRESSES
177777
157777

120000

:JJ:::;s§.fa;:§f:F~1i:fa::::t:::::::::

lt::p?.;~Y§f8i1F~itlff

I:lll~~~~~~~illl1

• SHADING REPRESENTS
MAPPING THAT OCCURS
IN USER STATE

APRs (KISAR 0-7)

NOT USED NOW

8K
PRIVILEGED TASK

KISAR7 (1/0 PAGE)

MEMORY
OCCUPIED BY
TASKS AND
PARTITIONS

6
5

PHYSICAL
ADDRESSES

117777

20K
EXECUTIVE

NOT USED
NOW

KISAR4 16-20K

KISAR3 12-16K

KISAR2 8-12K
KISAR1

4-8K

Kl SARO 0-4K

20K
EXECUTIVE

MAPPING FOR 8K PRIVILEGED TASK IN USER STATE AND 20K EXECUTIVE

VIRTUAL
ADDRESSES
177777

110 PAGE

--------

157777

KT-11 MEMORY
MANAGEMENT UNIT

PHYSICAL MEMORY

APRs (UISAR 0-7)

1/0 PAGE

NOT USED NOW

8K
PRIVILEGED
TASK

PRIV TASK 4-8K

PRIV TASK 0-4K

KISAR 0-4 AND

7 COPIES NOT

8K
PRIVILEGED TASK

120000
2

USED IN SYSTEM
STATE BUT VALUES

• SHADING REPRESENTS
MAPPING THAT OCCURS
IN SYSTEM STATE

STILL EXIST
APRs (KISAR 0-7)

MEMORY
OCCUPIED BY
TASKS AND
PARTITIONS

COPIED FROM UISAR 5 + 6
PHYSICAL
ADDRESSES
11777

E_X_E_~-~-~-l

___

1
_V_E_ _ _•l.""""'""l""'l""l""l""l""l:,:,;l;,:,;1""1""1=411._

20K
EXECUTIVE

;

MAPPING FOR 8K PRIVILEGED TASK IN SYSTEM STATE AND 20K EXECUTIVE
ZK-431-81

Figure 6-1

Privileged Task Mapping

6-3

PRIVILEGED TASKS

1/0 PAGE

APR 7APR6-

VIRTUAL 160000-

APR6-

AVAILABLE
TASK SPACE

APR5-

APR 7 -

AVAILABLE
TASK SPACE

r
-

VIRTUAL 120000 -

APR 5 -

-VIRTUAL 100000 -

APR 4 -

·~

APR4~

APR3-

APR3APR2-

RESERVED FOR
EXECUTIVE
MAPPING

APR 2-

APR 1 APRO-

RESERVED FOR
EXECUTIVE
MAPPING

APR1-

-VIRTUALO-

APR 0 -

/PR:4

/PR:5
ZK-432-81

Figure 6-2

Mapping for /PR:4 and /PR:S

When a task overlaps the I/O page, TKB does not generate an error
message.
Before TKB generates an error message, a task designated to
be mapped with APR 4 must be greater than 16K words;
a task
designated to be mapped with APR 5 must be greater than 12K words.
Only when you install a task that overlaps the I/O page does INSTALL
generate the following message:
INS--WARNING--PRIVILEGED TASK NOT MAPPED TO THE I/0 PAGE
While this is not a fatal error message, you should consider the
condition to be fatal if you expect your task to access the I/0 page.
You can use the /-IP switch to inform TKB that the task is
over 12K and does not need to be mapped to the 1/0 page.

purposely

A /PR:4 or /PR:S task can access all of the Executive, system
control
blocks, and I/0 page.
It can use Executive routines and do logical
block I/0 to a volume that is physically mounted on a device.
Also,
the task can issue a $SWSTK macro to change from user to system state.
This ailows the task to access the Executive or system data structures
without interruptions or fear of the data being changed while it is
being accessed.

6.6

/PR:O PRIVILEGED TASK

Using the /PR:O switch causes TKB to build the task in the same way as
any other task. Virtual address space begins at virtual address 0 and
extends upwards as far as 32K minus 32 words. This task cannot access
the Executive routines and system data structures or directly access
the I/O page because the Task Builder has not reserved APRs for
these
purposes.

6-4

PRIVILEGED TASKS
There are advantages to using a /PR:O task and having it
APR 0. A /PR:O task can:
•

Bypass file protection.

•

Use the alter priority (ALTP$) directive.

•

Issue any directive that has a target task.

•

Specify a device name in spawn directives.

mapped

into

logical block I/O to a physically mounted volume,
• Write
regardless of who issued the Mount or Allocate command. For
example, the VMR task is a /PR:O task and writes to mounted
volumes during the SYSGEN process. However, this advantage
can be hazardous for obvious reasons.
A /PR:O task runs in user state and cannot switch to system state.
Also, a /PR:O task is not mapped to the Executive.
If you want to
write a privileged task that does I/0 processing, it is advantageous
to use the /PR:O switch for your task because there is less chance of
corrupting the Executive or system code and data.

6.7

/PR:4 PRIVILEGED TASK

If you want your privileged task to map to the Executive and I/O page,
and your Executive is 16K or less, use the /PR:4 switch in TKB command
line.
If you specify /PR:4 for your task, TKB reserves APR 7 to map
the I/O page and reserves APRs 0 through 3 to map the Executive as
part of your task's virtual address space. The /PR:4 switch can be
used only if your Executive size is 16K or less, because the 16K
Executive uses APRs 0 through 3 and your task is assigned mapping that
starts with APR 4.
Therefore, TKB applies a bias of 100000 (16K
decimal) to all virtual addresses within the task.
This specific
mapping of APRs 0 through 4 and 7 occurs whether the task is in user
or system state.
Up to 12K words of virtual address space are possible in a /PR:4 task.
The beginning of the task marks the end of the Executive code.
If the
task is 12K words in size, the end of the task marks the start of the
I/O page.
If the task is going to access the I/0 page through APR 7,
the task cannot exceed the 12K limit.
If the task does exceed the
limit, TKB is forced to assign APR 7 to the task code. When building
the task, TKB does not give you an error message if your task exceeds
the 12K limit.
However, when you install the task, INSTALL sends you
the following message:
"INS -- WARNING

6.8

PRIVILEGED TASK NOT MAPPED TO THE I/O PAGE"

/PR:S PRIVILEGED TASK

If you want your privileged task to map to the Executive and I/0 page,
and your Executive is between 16K and 20K, use the /PR:5 switch in TKB
command line.
If you specify /PR:5 for your task, TKB reserves APR 7
to map the I/O page and reserves APRs 0 through 4 to map the Executive
as part of your task's virtual address space. The /PR:5 switch can be
used only if your Executive size is between 16K and 20K, because the
20K Executive uses APRs 0 through 4 and your task is assigned APR 5.
(APR 5 may be used if the Executive is less than 16K, but this wastes
virtual address space.) Therefore, TKB applies a bias of 120000
(20K)

6-5

PRIVILEGED TASKS
to all virtual addresses within the task.
This specific mapping of
APRs 0 through 5 and 7 occurs whether the task is in user or system
state.
Up to BK words of virtual address space
(12K if the I/O page is
overmapped)
are possible in a /PR:5 task.
The beginning of the task
marks the end of the Executive code.
If the task is BK words in size,
the end of the task marks the start of the I/0 page.
If the task is
going to access the I/0 page through APR 7, the task cannot exceed the
BK limit.
If the task does exceed the limit, TKB is forced to assign
APR 7 to the task code. When building the task, TKB does not give you
an error message if your task exceeds the BK limit.
However, when you
install the task, INSTALL sends you the following message:
"INS -- WARNING -- PRIVILEGED TASK NOT MAPPED TO THE I/O PAGE"
NOTE
When you use a privileged task,
the
Executive has dedicated almost all the
APRs to the necessary mapping for the
Executive,
the I/0 page, and your task.
Your task can issue PLAS directives to
remap
any number of these APRs to
regions.
However,
such remapping can
cause
obscure
and difficult-to-find
system bugs. Also,
note that when a
directive unmaps a window that formerly
mapped the Executive or the I/O page,
the · Executive
restores
the former
mapping.

6.9

EXAMPLE 6-1:

BUILDING A PRIVILEGED TASK TO EXAMINE UNIT CONTROL BLOCKS

The MACR0-11 source program PRIVEX.MAC in Example 6-1 illustrates
possible use of a privileged task.

one

NOTE
The nature of a privileged task is such
that you must have a working knowledge
of system concepts to understand its
operation or to write one.
If this
example deals with Executive functions
that are unfamiliar to you, you may
prefer to skip this section and return
to it at a later time.
If you assemble, build, and install PRIVEX into your system,
it will
scan the system device tables and examine the UCBs of all nonpseudo
devices on your system.
It will determine whether each device is
attached by a task and print on your terminal the names of all
attached devices on your system with the name of each attached
program.

6-6

PRIVILEGED TASKS
PRIVEX accesses two Executive routines:
$SWSTK. (switch stack)
and
$SCDVT
(scan device tables).
The routine $SWSTK switches the
processor to system state (kernel mode). This switch to system state
is necessary because it inhibits all other processes from modifying
the Executive data structures until PRIVEX is finished with them. The
double semicolons
(;;)
indicate the portion of the task that is
running in system state.
The routine $SCDVT performs the actual scanning of the device
It returns to PRIVEX each time it accesses a new UCB.

tables.

PRIVEX also calls the system library routine $EDMSG (edit message)
to
format the data it has retrieved from the device tables. This routine
is documented in the IAS/RSX-11 System Library Routines Reference
Manual.
Example 6-1, Part 1
MACRO

Source Code for PRIVEX

LIBRARY CALLS
.TITLE PRIVEX
.MCALL ALUN$C,EXIT$S,QIOW$S

LOCAL DATA
.NLIST
ATTMES: .ASCIZ
BUFMES: .ASCIZ
.LIST
QIOBUF: .BLKB
.EVEN

BEX
/%2A%P: IS ATTACHED BY %2R/
/BUFFER OVERFLOW/
BEX
132.

;MESSAGE OUTPUT BUFFER

BUFFER INTO WHICH INFORMATION IS STORED AT SYSTEM STATE FOR
PRINTING AT USER STATE. AN ENTRY IS FOUR WORDS LONG:
ADDRESS IN DCB OF THE TWO ASCII CHARACTER DEVICE NAME
BINARY UNIT NUMBER
FIRST RADSO WORD OF NAME OF ATTACHED TASK
SECOND RADSO WORD OF NAME OF ATTACHED TASK
THE BUFFER IS TERMINATED BY A
0
-1
BUFFER: .BLKW
BUFEND=.-2

ALL UNITS IN THE SYSTEM HAVE BEE~ EXAMINED
THE BUFFER WAS FILLED BEFORE ALL UNITS COULD BE EXAMINED
4*200.+l
;ADDRESS OF LAST WORD OF BUFFER
(continued on next page)

6-7

PRIVILEGED TASKS
Example 6-1, Part l(Cont.)
START:

MOV
CLR
CLR

#BUFFER,R2
(R2)
Rl

Source Code for PRIVEX

;GET ADDRESS OF INFORMATION BUFFER
;ASSUME NO UNITS ARE ATTACHED
;INITIALIZE CURRENT DCB ADDRESS

"CALL $SWSTK,FORMAT" SWITCHES TO SYSTEM STATE. ALL REGISTERS
ARE PRESERVED ACROSS THE TRANSITION FROM USER MODE TO KERNEL
MODE. BEING IN SYSTEM STATE LOCKS OTHER PROCESSES OUT OF THE
EXECUTIVE (GUARANTEES THAT THE DATA BEING EXAMINED WILL NOT
CHANGE WHILE IT IS BEING EXAMINED). A "RETURN" WILL GIVE
CONTROL TO "FORMAT" AND WILL RESTORE THE CONTENTS OF THE
REGISTERS TO THEIR VALUES BEFORE THE "CALL $SWSTK".

20$:

CALL
MOV

$SWSTK,FORMAT
#$SCDVT ,- (SP)

CALL

@(SP)+

BCS

100$

;SWITCH TO SYSTEM STATE
;;GET ADDRESS OF SCAN DEVICE TABLES
; ;COROUTINE
;;GET NEXT NONPSEUDO DEVICE UCB
ADDRESS
;;
;;IF CS NO MORE UCBS

AT THIS POINT:
R3
ADDRESS OF THE DEVICE CONTROL BLOCK
R4
ADDRESS OF THE STATUS CONTROL BLOCK
RS
ADDRESS OF THE UNIT CONTROL BLOCK

40$:

60$:
80$:
100$:

CMP
BEQ
MOV
CLR
BISB
MOV
BEQ
CMP
BLOS
ADD
MOV
MOV
MOV
MOV
CLR
INC
BR
CALL
BCC
COM
RETURN

.ENABL
FORMAT: TST
BEQ
CMP
BNE
MOV
CALL
EXIT:
EXIT$S

Rl,R3
40$
R3,Rl
RO
D.UNIT(R3) ,RO
U.ATT(R5),R4
60$

;;IS THIS A NEW DCB?
;;IF EQ NO
;;REMEMBER THIS DCB
;;FORM LOWEST UNIT NUMBER ON
;; THIS DCB
;;IS A TASK ATTACHED?
; ; IF EQ NO
;;IF NE R4 IS TCB ADDRESS
#BUFEND,R2
;;ANY MORE ROOM IN BUFFER?
80$
;;IF LOS NO
#D.NAM,R3
;;FORM ADDRESS OF DEVICE NAME
R3,(R2)+
;;SAVE IT IN BUFFER
RO,(R2)+
;;SAVE UNIT NUMBER
T.NAM(R4) ,(R2)+ ;;SAVE NAME OF ATTACHED TASK
T • NAM+ 2 ( R4 ) , ( R2 ) + ; ;
(R2)
;;ASSUME NO MORE ATTACHED UNITS
RO
;;INCREMENT UNIT NUMBER
20$
;;
@(SP)+
;;GET $SCDVT TO CLEAN OFF STACK
80$
;;
(R2)
;;SHOW BUFFER OVERFLOW
;;RETURN TO USER STATE AT FORMAT
LSB
(R2)
EXIT
#-1, (R2)
40$
#BUFMES,Rl
PRINT

;ANY MORE INFORMATION IN BUFFER?
;IF EQ NO
;OVERFLOWED BUFFER?
;IF NE NO
;GET ADDRESS OF OVERFLOW MESSAGE
; PRINT IT
(continued on next page)

6-8

PRIVILEGED TASKS
Example 6-1, Part l(Cont.)
40$:

MOV
CALL
BR

#ATTMES,Rl
PRINT
FORMAT

.DSABL

LSB

Source Code for PRIVEX

;GET ADDRESS OF TEMPLATE
;FORMAT AND PRINT THE INFORMATION

PRINT - FORMAT AND PRINT A MESSAGE
INPUTS:
Rl
ADDRESS OF AN $EDMSG INPUT STRING
R2 - ADDRESS OF AN $EDMSG PARAMETER BLOCK
OUTPUTS:
R2 - ADDRESS OF NEXT PARAMETER IN THE $EDMSG PARAMETER BLOCK
RO, Rl, R3, R4 ARE DESTROYED
R5 IS PRESERVED
PRINT:

MOV
MOV
CALL

#QIOBUF I RO
RO,R3
$EDMSG

;GET ADDRESS OF OUTPUT BUFFER
; SAVE FOR QIOW$S
;FORMAT MESSAGE INTO OUTPUT BUFFER

REMOVE LEADING ZEROS FROM UNIT NUMBER

20$:

40$:

MOV
TST

R3,RO
(RO)+

MOV
DEC

RO,R4
Rl

CMPB
BEQ
INC
CMPB

#'O,(RO)+
20$
Rl
#':,-(RO)

BNE
MOVB
INC
MOVB
BNE

40$
# I 0, ( R4) +
Rl
(RO) +I ( R4) +
40$

;POINT AT OUTPUT BUFFER
;INCREMENT BY TWO (POINT PAST
; DEVICE NAME)
;REMEMBER THIS SPOT
;ASSUME NEXT BYTE IS A LEADING ZERO
; (REDUCE LENGTH OF MESSAGE)
;IS IT?
;IF EQ YES -- IGNORE IT
;COUNTERACT TOO MUCH DECREMENTING
;WAS THE BYTE A COLON (WAS THE UNIT
; NUMBER ZERO)?
;IF NE NO
;ADD A ZERO UNIT NUMBER
;INCREASE LENGTH OF MESSAGE
;TACK ON REST OF MESSAGE
;IF NE NOT DONE

PRINT THE MESSAGE ON LON "OUTLUN"
AND WAIT USING EVENT FLAG 1
QIOW$S
RETURN
.END

(DEFINED BY THE TASK BUILD FILE)

#IO.WVB,#OUTLUN,#l,,,,R3,Rl,#'

START

PRIVEX.MAC should be assembled with the
string:

following

assembler

command

MAC>PRIVEX,PRIVEX/-SP=DRO:[l,l]EXEMC/ML, [ll,10]RSXMC/PA:l,DR2:[303,l]PRIVEX
The file EXEMC is the Executive macro library and the t11e RSXMC is
the Executive prefix file.
The switches used in the command string
are described
in the IAS/RSX-11 MACR0-11 Programmer's Reference
Manual.
6-9

PRIVILEGED TASKS
The Task Builder command sequence for PRIVEX is as follows:
>TKB
TKB> PRIVEX/PR:S,PRIVEX/-SP=PRIVEX
TKB> ORO: [3,54]RSX11M.STB,DRO: [l,l]EXELIB/LB
TKB> /
Enter Options:
TKB> UNITS=l
;DEFINE NUMBER OF LUNS
TKB> GBLDEF=OUTLUN:l
;DEFINE LUN ON WHICH TO PRINT MESSAGES
TKB> ASG=TIO:l
;ASSIGN LUN TO DEVICE
TKB> //

>
This command sequence directs TKB to build PRIVEX as a privileged task
and to add a bias of 120000 to all locations within it. APR 5 was
chosen in this example because the Executive in the system on which
this example was originally built is 20K words long.
If the Executive
in your system is 16K words or less, you can use /PR:4 when you build
the task.
In the options section of the TKB command sequence, the UNITS=l option
specifies
that
PRIVEX
will use only one logical unit.
The
GBLDEF=OUTLUN:l option defines the symbol OUTLUN as being equal to 1,
and the ASG=TlO:l option associates device TIO: with logical unit 1.
The TKB map for PRIVEX is shown in Example 6-1, Part 2.
The GLOBAL
SYMBOL SECTION has been shortened to save space.
Note that the task's
address limits begin at virtual address
120000.
Figure
6-3
illustrates how TKB allocates virtual address space for the program.
Example 6-1, Part 2
PRIVEX.TSK;l

Task Builder Map for PRIVEX

Memory allocation map TKB M40.10
7-0CT-82
13:26

Page 1

Partition name : GEN
Identification : 01
Task UIC
[303,1]
Stack
limits: 120230 121227 001000 00512.
PRG xfr address: 124610
Task attributes: PR
Total address windows: 1.
Task image size
1920. words
Task address limits: 120000 127323
R-W disk blk limits: 000002 000011 000010 00008.

*** Root segment:PRIVEX
R/W mem limits: 120000 127323 007324 03796.
Disk blk limits: 000002 000011 000010 00008.

(continued on next page)

6-10

PRIVILEGED TASKS
Example 6-1, Part 2 (Cont.}

Task Builder Map for PRIVEX

Memory allocation synopsis:
Section

Title

• BLK.: (RW,I,LCL,REL,CON) 121230 005746 03046.
121230 003656 01966.
$$RESL:(RO,I,LCL,REL,CON) 127176 000124 00084.

PRIVEX 01

Ident

File
PRIVEX.OBJ;2

Global symbols:
AS.DEL
D.VOUT
AS.EXT
D.VPWF

000001
000004
000004
000006

$PDVTA 020000
$YHCTB 022674

BT.UAB
F.NWAC
B.DIR
F.SCHA

000002
000034
000026
000015

$REMOV 054044
.TT14 023770

DV.SDI
IE.DAA
DV.SQD
IE.DNA

000020
177770
000040
177771

D.RS81 177657

$SGFFR 020652

$TICLR 041032

D.RS83 177655

*** Task builder statistics:
Total work file references:
250535.
Work file reads: o.
Work file writes: o.
Size of core pool: 13486. words (52.
Size of work file:
12032. words ( 4 7.

PAGES}
PAGES)

Elapsed time:OO:OO:Sl

1/0 PAGE
APR 7- -

APR 6- -

....,_ _ _......,.""""'!i-VIRTUAL 160000

::~~~~~~

VIRTUAL 127147 }

PRIVEX. TSK
APR 5- -

TASK ADDRESS LIMITS
VIRTUAL 120000

APR4- -

APR3- EXECUTIVE
APR 2- -

APR 1- -

APR 0

-------VIRTUALO
ZK-433-81

Figure 6-3

Allocation of Virtual Address Space for PRIVEX

6-11

·.CHAPTER 7

< ~.

osE"R.:1'oDE .I~ ANt> .:o.:sJ?ACE. t.RSx:..tiM:.PLQs· ON.LY}:: .:
This· ,9hG1pte.:r, ,disc.usses. th~>Tas.k.. · B:ui1d~r·•·s. abU{ty··· . ·...i;;Q·.' ·c:u·yide ·a. ·user
"task' . into .·. instrQction ···and.· data ·space.·'. tr-· ariP,·, D~space.) ~' · A'··series' :o'{
'figures·· and· text. explain. '1:.a~k .mappin9·.and..:the· use,· of ..task windows. ·in·
an ·, RSX-llM:!>LUS ·. ·'.system .With··. ~n '. I->. and D:spa.ce. task.
In the.· te.xt.,
··compar.isoJ1.~· ..~re' 1Jta5le l;>~twe.en···c?n.ve:nti:onal, ,tasks . .· .a·nd
:an.d .· . o~space·
·t'asks. . A·· €.onventi.onal task., .is". one . that .·d.o·e·s riot;· .~epa,r:a.tely ·map·
·ins.t,ruction :~.Pace and: ga7a .space..; · '/.:'
·, ·.
, .. ,

·,1/ ·. . .

·Toe·. i,:-: arid' :n..:space ~eat;ur~.. ·i's. ·. a.n· ·.'.RSX~iIM:O·~t?s· • $ysteri\'. generation
option. , The· feature is ava,1lable .only. .on . specif1c. processor· hatdwar·e •.
Convent.ioria1.·ta.sks ·can .be,. r~n in ,an' T-'.· and· D.-.space system, but an. 1-.
and P-space task cannot· r·un :i,n :a. system· that does· ·not ·have the. o,ption·.
spe.ci fied.·
· ·· ·

7.1

USER .TASK DA'1A SPACE.DEFINED
'·

User ta~k cfata , spa~~· 1 ~hat . sp.ace .tha.t cont.ain's 'data' . and . wb'i ch . the
usei: .tas.k.... accesses . through ... D~space ... A)?R,s. " , .The fµnqtion o:f J-: and
D-space allows .·a ·total· of 16 ·APRS. to ·map your ta.sk: 8, AJ;>Rs . fo:r data
space .a.nd 8 AP.Rs fo.r. instruction .space.. . If. your task use~ ,both'.. I.-·· and
1)-.s~Cic~. t?· ·~·ts. max~mum. :apa:<?itt,, it cct.n .• :ont~in ·64.K: ·words . of 'Virtual
a~dre,ss space.~. ;tn ··adqi~·ion:.· . to ·'bo·tn-'.·~·7. ~nd · D-:s~ace ;". i~:· . y-.oi.n;:.: ·.task ·);inks
to a 32K wo:rd 'supervisor-mode· library·, .i t :·C~P .contain· . ~6K w·ords . of'
virtual .address· space.· · "
·
.:: . "
'·· " ...... ·
· · "·

"To ..sepa'rate. ··the di:rt"a ·and ·instructions.;. ,your: "task.... ca~ · · 11s~· · 'PSECTs' . to
··~:frn1t?in · . th.e· · 9a.t~ ..0£.:f.n'st:·~u9'tf<;:ms ..·

Also.;, ·,~·our' t,<:,1-sk ..¢~n ·use, th~ CRA~$
and:. CRRG$ di:rec:tives ·to. · dyn·amically· ·create :and. map. , to. · data.-spa.ce.
:region·s·. · ··See 'the RSX-'l1:M/M.:..PLus· Executive· Referen·ce M·anil'aI for the.
use of ~h~se ~i:rectives.

Conventional tasks. and tasks that sep·a'rate inst:ruction·. space arid data
space differ in only a few . areas. of interest. The next sections
discuss these areas.

7.2

I- AND D-SPACE TASK IDENTIFICATION

Two fields denote an I- and D-space task.
In the task header, the
byte that has the offset H.DMAP identifies the task D-space mapping
mask.

In the Task Control Block (TCB) , the T4. DSP bit in

the

fourth

task status word identifies the I- and D-space task to the system.
The system task ldader or the VMR FIX command initializes these two
fields at the time the task is loaded. Therefore, tasks built on a
system other than an I- and D-space system may be run without
rebuilding on an RSX-llM-PLUS system that supports I- and D-space.

7-1

USER-MODE I- ANO 0-SPACE

(RSX-llM-PLUS ON·LY)

The ·I~ and o..:.spad~ task is one in. which TKB separates the .'data. . areas
ins.fructions...
In this task, data. area.s shou~d be defined .by the
.MAC-RO-ll · ~PSECT. directive. that has the data attribute. Simila'riy,. tp·e·
'.:~·:P'sECT (lirc;ctive with the "I"· attr1bute defines instr'uct:iori areas.·

an:d
~-

;, >;q

;

~ '' ',

;;'

, I

··if'{3. . ·:·C'c)MPAR:fad~ · OF .coNVEN.TION:AL
x

TAsl~s ..ANQ I-; .AND ,.,o;.s.PACE · TASKS,

, '

;

~.·

~ ,;· ~'

:A·:.c!o'nvent:ional task· 'operatin<,;i.'in user mode ca·n .contain . 32Kw.ords · . of.:
'v·frtual · ,addres.s spa9,e: · ·and·. acc~ss ~approx.imately 32Kw.ord~· of 'physisi:l·f.
.:mempry •. · .However., .. a. task. us iq~ bot;h .r~ and o~"Space ..AP~s . c.an. ·. c6ntai:.ri/
.?,·4.KWP.:rds .'pf• ·\drtual .'<)lddre~s spa9e an.d · acc,ess appt·OXi,I1l<;ite!y · 6,,4.K~ords .·of·

f.·.

~·~~.o··. YA:· .: ... /

rf ,, .'_1;_'."',·'

.' .

. .. .

. '

.,.

,. ~ .'i

'Tlie':'co·n.~ention'a1 ·ta·s''k · in an I-· and D~space· ·syste~ u'ses " b'ot:h

s:ets of
~PR~·. ' · ·Hoytever,. ·the relo,cati6n addresses. in hoth ·!'...:space ·and .,n""."space·
APRs ate· "identical... ·Also·, the, task' :windows refer t,o I--space'."APRs' in a
,:task' tha,f .does"not, use· D,-space.. .
.
'•

:I...; and o.:..spa,ce task, can use separately 'both I- and D.-s·pac'e · APRs;
.t:hat . is, APRs used in this way are not overmapped •. Because· of this,·
the· task can use eig'ht D-space APRs .· to access . and use data, and eight
.!...;space" APRs to .access and execute instructions. Using i6 APRs allows
the: 1- and o~space task to access a· total of 64Kwords of phys,icai
·memory at one time.

'A'i.1

Table 7~1 contains a brief mapping summary of the combinations of I-·
and D-space tasks,
I- and D-space systems, and the APR mapping that
occurs.
Table 7-1
Mapping Comparison Summary
I/D
Task

I/D
System

Yes

I-space APRs and D-space APRs contain
relocation addresses.

I-space APRs contain relocation.

Yes

I-space APRs map instruction
APRs map data space.

.Yes

Not possible •

. 7.~·4.

Mapping Summary

space.

the

same

D-space

CONVENTIONAL TASK MAPPING

Conventi'onal ·tasks, map their virtual addresses to their . logical
'addresses through both !"."space and .D-space APRs.. 'rhat is, TKB does·
not separate instruction space or data space nor does. the' 'system.
c;H'fferent:late· the· spaces except b'y the logic inherent in the' task,,
The.r'efore, the task must map to its log ica 1 address spaq,e ·by both sets.·
of AJ?Rs '· .which. are Qvermapp~d .. ·
Fig.lire . 7.:..1 shows an 8K conven,tional task linked to an 8.K regipn that·
·maps . to its ' logical address space through bo'th D-space and r.;;.space
. APRs. i.n an I-· and D-space system.

7-2

PHYSICAL
MEMORY

D-SPACE
APRS

7
VIRTUAL
ADDRESS
SPACE
REGION
TASK

I-SPACE
APRS
8K

REGION

REGION MAPPING

MtttN TASK MAPPING
ZK-434-81

',Conventi:onal Task Linked, to a Reghin 'fn· ,/~a
, ,, ::i,..: and ',.-'D:..,;Space $ystem
.

,:7z:~"S;,;+:;r~:·,~NO.,.JJ~,S'PACE,·.TASK . 'l"JAPPING

'~iif~t~' 1::2, :s~o,wS ~n Jl ~ r- and D-space task.

TKB sep<>ra ted the data
Because of the way TKB processes· ta'sk
·~pal'.;:ie, the t.ask. header must physically reside at the beginning of
the
task in I-space·. TKB .puts the. header that the Executive uses for task
c<;>nt,ro1 in D-space. Also I the task Is stack is in D-space.
If the'
ta·sk · is· to,- have an external header (under control of the /XH switch) ,
,th~ '.Executive copies the header
in D-s·pace and puts it into the
contiguous space irr.mediately before the task's I-space in memory. For
more details, see Figure B....,.4, Image on Disk of Overlaid I- and D-Space
Task, in Append ix B.

,atixf, 'instruc,ti:ons' in this· task.

The task shown uses two APRs because of its size {8K).
maps the'task's header and stack and part of D-space.

7-3

D-space APR

USER-MODE I- 'AND·D-SPACE (RSX-llM-P.LUS .:ONLY)

PHYSICAL
MEMORY

D-SPACE
APRS

TASK
D-SPACE
HEADER USED BY
EXECUTIVE

UNUSED HEADER
COPY
COPY OF HEADER
IF EXTERNAL HEADER

Figure 7-2

I- and D-space Task Mapping in an

7-4

:t- and D-space System

..:· . ;os1s~~M9r>.E.· .l;....'.A'.No·Jri~SPAC,E.·· ,'<·~·~x~:l:'l~~·PLo.s·· .·oNI.:rj.,·, , ,.
~

••

•

••

...,

•~

•

< ;

•

-~ )."- ':'

-< l

TKB uses diff.erent w'in'..dow~ ·'to .map. vari<:>us ·portions· of ·an I- and·'
:task •.. :Window . o· . in· an I~ and D-·space task cannot be used
because it' maps the, root iri !-space. s·1mi,larly; you ·.cannot' us~ Y1indo,w
1 because. it maps the,:· p....;space ·part of'.t:he root •...The root of the task·,
which TKB divides into· ;r:.. and. D~spa'ce, .. therefore· requires two windows~.
TKB reserves the use, of: t::.he,se t~o windows ..• · You. can $Ped fy up to 14'
·windows for a ..t::.ask that .. us·es 1:.. ,a'pa· ..o. . :;pace~·
o~space

-~·

~A~·A SP~CE' .~N y~rn~·· TA.St.
';
:·.·Yq.u··.ae~-'ign .~n<r~····ai:i<l".n.~.~Pa.Y·~· .. ~ta'iK:·.by,··~·p4bir.itn~-'·a~.t~·.·sp.~ce·· .. s·epai;:~·t¢iy·,
7 .7

SPECIFYING

·from .. ~_.i1)s.t::.r'ucJ:ion··· ,$p'~·ce ..·,:·: .. GoQa pfo.g·+affin\i. n·g pracH'ce,.':·sugg'¢s't;s·~:·tbi3t·.:all·

··da.ta ·a.i;eas· ·and.·, b,uf,f'el'.'.s. · .·$bould··J;ae. <lo·ca,£ea ··:<lri, . aaj.a~.ent locatfons~
·simit'arly, .. all· .in.str~1d:i'o,ns'.:-shoulp.:b~:: ·lo,q«q;t~a'·in'adJa6ent' L()Cations;
::H'()~~v~r.,,·, T;~·..¥JP-i/~e:p:~~~;~:~·: . . .~.n9/ag<Jl:<?fri~r:~·~'e/.:ttt~:Gr,:u~. £tt;>r( ~f1:d: :·4~t.·fi. ·.· :sppce::
wheil it 'builds the..,t.ask.'~· ·• F?·r .:TKB· ;~·C{ d:o: :.this:·, .:·.you. must· .,use;' a·. method o·f·
inform,ing· . it: "aho~t· ,.:·'wli:fo.h· . st~ieme.nts ' ~x'e: ..d'a.ta '''.and' . ··whi.ch. ':. are·.
'inst.ruc·ti9n$. ·
. ,
'" ·' ··
1

For the MACR0-11 pr6gramme·r", the. w~Y tO .. s'~'~a.ra"fe.'d.a ta·•·a;ncf"1~fih'u,ctJoi1s"
is.' . to. use·theMACR0-11, .BS:l~:CT.·d.i·r.e·ctive •. Y:o·u.cari use th1s,.directive.
,w.ith the· instr,u.ctio~ · (I')'"·.·c:.tt):.i,hu'te .·fo.r~all: 't'.n.e 'instruct.i9n .· IocertJ,ons
in . your :·.task's c.od:e·.· .··. Als.o;.· .>you ...can.·.:· use .. ·.PSECT and the· data ,cbY:
attr"ibu.te· .fo:F :~11.<t.he· .da't,a ..loc~ti,. ons:.,;. ·... Yoµ· ~~st ·ae.fJne .·a. da:ta ..• J?SECT
in an .· 1- .~.nd. D,"'."space task . even :t.hough. no, actual. data. is co.ntai ned iP,
the task... . In. this ca'se, the .•. PSECT car,i :be of 0 length.. .
..
Note . that I'._; . arid. o~.sp~~.e .librad\~~ ha'Je. not .be~n.· def.ined. and .~~~ not a
..
. . , , . .,::· . .: .· . ,
, .. , ,

.r;>'o·s~ib1~:c.qf:t·flghra.ti().I\.• ·

} ~ 8 .. OVERLAl'D 1.;;..; AND. o.;..Sl'A:CE,TliS.KS
>,

<;,

:.:. : •

~, ~ ':

~. '·!

> .,

.::Ex·ceJ?t'.···ea.r·.,.:tt1e'.ma.J?J?'i'ng.':a,f:,· ~'n:·~~.::.,a·n'd,· .b,~spa~~e't'a. ~J( .~na:::·tri.e/: .... ~.o·oat:ion' ~·:f,
,ins·t.r,uct.ions.. and', .data,: the I.-. :a·na:.. D-s,pace·,.:ta,sk 'diff'ers little, from. a
.66nventi"ortal .·t:ask ~· .·: .Howe·v.e·r; ·.·tnet.e" .·a·r·e·: str;ud:ifrai ,'<'.fl ff~~·e'nces .· .betwee'n,
'a.".·no·n,_overlaid .an.~. ~ri···ove~"Ia.io···tl... aqd·:o-space,: ·task:•...·By· c·ompa:rJng· tl:l'e
·t\40· K:i'nds ·.of· tasks, the.··.fig·u~e·~f ·a:µa, t·ex:t ·:ih .. ·t:.he ·.:followin.9" ·. ~ectto.'1s·
.descr.ip¢ ..:the .·m'.m:·-oye:t:'iqfp :· •anq..";9v~r.1~~g· . ·.r:~: :§nia,.: O'-iSPac~ :'tasks •... ~lso . ,
:you' ma:y :wa.nt to: ref.er to .·the de.scri pfiCH1 .':'Of,·" ·QV,eria.fd conventional·
.tasks in Chapter ··3 •. · ··· ·, ·· · . · ... ,, ....:·".:" · ·.··
·.· ". "·.•.· ·
·
figure 7-3 shows· a s'impUfied disk, i'mage: of. 't::h'e : ·no,n--ove'rlaid .. I...; and
o'-space task. Thi.s' tasJ<=. c.ontains four I,-sp~ce P.SECTs and four' D-space
PSECTs. TKB col1ects all the I-space PSECTs together in. one .. part o·f,
the root and· ·an the o--space PSECTs in a,nother part of the ,root. ,

7-5

USER-MODE l- AND D-SPACE (RSX-llM-PLUS·

LABEL BLOCK AREA .

RELATIVE ·.DISK BLOCK n

HEADER (UNUSE,D)

. 'RELATIVE DISK BLOCK 0

•

CHECKPOINT AREA

ROOT

~ .. 1.:SPAGE
INSTRUCTIONS

HEADER{USER'S)'
··STACK·
ROOT
DATA.

Flgure 7-3

Simplified Disk Image of a N6n-Overlaid 1~ ·~nd
D-Space Task

Figure 7-4 shows the virtual address space and physical memory:
occupied by an overlaid I- and D-space task called !AND. The task has
a total physical size of 160000(octal)
bytes.
(You may want to
compare Figure 7-4, which is shown next, with Figure 3-1 in Chapter 3,
which shows a conventional overlaid task.) The instructions and data
occupy the same virtual address space and are of equal physical size;
but because they are mapped
through different APRs,
they occupy
different locations in physical memory.
The instructions in !AND
occupy four PSECTs that have the instruction (I)
attribute, and the
data in IAND occupy four PSECTs that have the data (D) attribute~
In Figure 7-4, the virtual instruction space contains PSECTs A, B, and
C, which are those that contain instructions, and ROOT I, which is the
PSECT in the root that contains instructions.
TKB places the unused
header in I-space part of the root.
Also, in Figure 7-4, the virtual data space contains PSECTs p,· E, and
F, which are those that contain data,·and ROOT D, which ts the PSECT
in the root that contains data.
TKB places the task '·s user head.er in
the D-space part of the root.
As an overlaid· task, a possible overlay tre:e may . look.
.shown in Figure 7-5.

7-6

like ·the

one

VIRTUAL I-SPACE

MODULES

VIRTUAL D-SPACE

160000

IAPR7

160000

140000

IAPR6

140000

IAPR511

llDAPR5

100000

IAPR4 --+------

- - - - - - - - + - DAPR4

60000

IAPR3

120000

40000

PSECT C

OVR3

PSECT G

PSECT B

OVR2

PSECT F

PSECT A

OVR1

PSECT E

IAPR2

---------STACK
----------

IAPR1

+-------UNUSED
HEADER

100000

DAPR3

60000

DAPR2

40000

DAPR1

20000

DA PRO

ROOT D

ROOT!
20000

120000

USER
HEADER

IAPRO

ZK-1099-82

OVR1

OVR2

OVR3

ROOTI
ZK-1100-82

~igure

7-5

Example Oyerlay '.l'ree for Over la id I- and D-.Sf>ace Task IA;ND

The accompanying ODL statement for this task is:
~ROOT

ROOT-(OVR1,0VR2,0VR3)

Notice that this ODL statement is not different .from any overlaid .task
with this tree structure.
In this statement, the module OVRl contains
the instruction PSECT A and the data PSECT E, the module OVR2 contains
the instruction PSECT B and the data PSECT F, and the module 0VR3
contains the instruction PSECT C and the data PSECT G.
A.lso, the ROOT
module contains the instruction PSECT I and the data PSECT D.

7-7

USER-MODE I- AND D-SPACE (RSX=llM=PL.U:S ONLY)
The disk image o·f this overlaid· task, shown in Figure 7-'6, ·contains
'the instruction and data PSECTs Ln separate areas. Figure 7...:6 also
illustrates the difference betw~en disk image·s- of overlaid and
non-over la id r- and D-space task disk images ..when you compare it with
the disk image shown in Figure 7-'3.. Notice that ':CKB separates the
segments of the overlaid l,AND task into instruction parts and data
parts. Ani autoload· ,vectors generated because of. calls, from these
segments are als.o included· .in. thg seg:Illent £irea. The . autoload vect.ors
for 'I-:· ·and D-space. tasks contain two parts: and I-:space part and a
o;..space part ...
TKB places each part' with its'dofrespondlng segment
part as shown in F1gu.re 7-6 ~ . A:uto:load vect~rs fo·r; · I;_" and D-space
tasks are discussed in detaU .in Cq~pter 4•
·
RELATIVE BLOCK 0

•
•
•

LABEL BLOCK GROUP

I---

SEGMENT LOAD LIST

RELATIVE BLOCK 3

CHECKPOINT AREA

•
•
•

TASK HEADER (UNUSED)
ROOT I -

INSTRUCTION SPACE

AUTOLOAD VECTORS FOR I-SPACE
TASK HEADER (USED)
TASK STACK AREA
ROOT D -

DATA SPACE

AUTOLOAD VECTORS FOR D-SPACE
SEGMENT DESCRIPTORS
WINDOW DESCRIPTORS
OVERLAY SEGMENT OVR1
I-SPACE PART (PSECT A)
OVERLAY SEGMENT OVR1
D-SPACE PART (PSECT E)
OVERLAY SEGMENT OVR2
I-SPACE PART (PSECT B)
OVERLAY SEGMENT OVR2
D-SPACE PART (PSECT F)
OVERLAY SEGMENT OVR3
I-SPACE PART (PSECT C)
OVERLAY SEGMENT OVR3
D-SPACE PART (PSECT G)
ZK-1101-82

Figure 7-6

Simplified riisk I~age of Ov~rlaid I- and D-Space Task IAND

7-8

7. 9 .1 .· Autoload Vectors and .• STB Files
If your I- and. D-space task.links to an' overla.id shared region,. ·that
region must have been built with a version of TKB that supports
overlaid r- and D-space tasks~· ·The reason '.for this is that .·the.·· .STB
files for overlaid shared regions built. by old.er versions. of TKB do
not contain the. ISD records that are needed to create the type of
auto load vectors that I:- and D-:space. tasks use•

For newer versions of TKB that support ·overlaid I-· and D-space tasks·,
TKB allocate.s autoloadable vec'tors ·in. tne· root oJ· the task o.nly for
th9se eptry points· in· the libr.ary re;Jferel;l,qed·. by th.e· ti?S.k:.·· .' To. c.re~te.
the auto load vectors I
TKB . uses. ISO records ;in the. ~STB file when
linking the ·task t.o the library, ·ff the. mo . reco:i;ds .. a·re ·present~
Therefore,. tas·ks. buii't with newer ·versions. of '.!'KB ·te"nd··
be sirialJ~.r
:because fewer aut.ol.oad vectors. ~.re.p:r:esent..
.
'.

•

'·

:·

For/ .the ·Fast .Ta~}< .Buflder ;fFTB}' ahd·.'Older.·v~psions qf::'TKB>that dO' n:qt
s·µpp,ort, . I -..•a~d . [>~space.· . tasks·,/ ea.ch. ··atl:to.load \1eqtpr ··in the ··sha,r.ed:
·reg.£ on) s ·· .• STB .file· i·s ·ano·qaJ:ed: tr:i· .t·l)·e.: rpot · o·f·. the. t;ask.· b~'i ng< , l,ink~d.·
to the.· region·, whether or 'riot· the'.·entry po int: 'is ·ref~.r~ric.ea by.;- :the,
task·.
.· ·
· · ·
"' ·
·
.·NOTE.

Librar~~s c:r.eated .'with ·older. 'versihn·s'·cif'
TKB do.·· not·· have :the· ISD r·ecords ·in the
• STB file.··. that' newer· versions· of TKB dse
to include autoload vectors in the task
from the· .. STB file.. ,Ther·efore, TKB .mus·t
. 'c~r~ate autoi<;>a~ 'vectQr$
ever,y: entry'
P?i.nt in . t.he .PJ:>ra.ry.
....

f:9r.

If,' yo9 are... U$ing one· of these, older
.librades . arid you i;ire Unking., an. ·,t:... arid
o:...space. task to it, ·ir,KB will' ·/g.ive .· you
the ..fa·tal ~rror +oessage!.
>

,..,

· ·.cont,:a ins.:
:••·Module
'roodtll~·-nam~ .
· incompatible ·au:toioad .:·vecfors"n
,, <•

, ...

· .Thf·~· mes·sage · ·occurs · becat.ise· ···the:' · ·•. STB
file
contains ·: c6nv.entiona1, . . a'ut.olo.ad
.vectors that' 'are not
ab.le by· .ctn I- and.

o--s:p,ac~ · ~t~s k. ~

For more information about linking shared regions to I- ·and · · o:...space
tasks, see the section in Chapters· entitled, Autoload Vectors and
.STB Files for Overlaid Shared Regions.

7.9

I- AND D~SPACE TASK MEMORY ALLOCATION AND EXAMPLE MAPS

The following section discusses and shows the differences between two
versions of a task that is built both as a conventional task and as an
!- and D-space. task..
The conv.entional task is called MAIN .. TSK and the
I- and D-space version of MAIN.TSK is called MAINID.TSK. Both of

7-9

OSER-MODE I- AND D-SPACE (RSX-llM..:PLtJS QNLYj
these tasks are similar to but not the 'Same as .·the .ta.sk· called
MAIN.TSK shown in Chapter 5. After MAIN.TSK was. coded, buiLt.," and.the
map printed, MAIN.TSK was rebuilt as an ·r- and o--space ta.sk ·to. create
MAINID.TSK.
To do this; the /ID switch was us'ed irf:t:he ~KJ3 command
1 ine. Both versions .of this task are over.laid a.nd liri;k tp. a li})rary ...'.,'.

7.9.1

Virtual Memory Allocation for MAIN.TSK

MAIN. TSK has a root called MAIN .and . three .overlay· .. "~·~gm,ents: :. . ,q'a;l.1,~~;
INPUT, CALC, and OUTPUT. By comparing the IU.aP Of, t~~s·':ta:·~k in;Ex,am~le
7-1 and the memory. allocation diagram i,n· .Figu,te. 7~.7,,'.' ydu,· ~wiAl b,e: ?tb.~~
to determine the virtual memory .space all'ocation ?:lr:td. ·9,tructµr~ ·of/.this
task. Note that the ·overlay segments.··,oocu.py,·the: :s,:ame··.·v:L,,;rtu:a·l ' . • ·.a_.d'<::lr~.·.~s·
space, and the root and. segmen~s ..~i;e ma{>ped 'J~ .. l:>oth t..:s~a. .c,e a,nd
D-space.
w.
006307

006307
005063
004607
004514
004513

005063

INPUT

004607

OUTPUT

CALC
004514

004513

MAIN
000000

000000

ZK-1107-82

Figure 7-7

7.9.2

Memory Allocation Diagram for MAIN.TSK

Virtual Memory Allocation for MAINID.TSK

MAINID.TSK has a root called MAIN and three overlay segments.
In this
way MAINID.TSK resembles MAIN.TSK.
However, the I-PSECTs and D-PSECTs
in MAINID.TSK are separated and they are mapped through their
respective I-space or D-space APRs. Therefore, MAINID.~SK has t~o
virtual address spaces: an I-space and a 'D-space.
Figures 7-8 and
7-9 show the memory allocation for the I-space and o~space in
MA I NID • TS K•
The three segments INPUT, CALC, and OUTPUT occupy the same virtual
I-space, because these three segments contain instrucooons · and;
the ref ore, I-PSECTs. However, the overlay segment OUTPUT is the·· only
segment that occupies virtual D-space because the_ segments. lNPUT~and
CALC do not contain data or D-space · PSECTs. Note th.at the:. two . overlay
segments INPUT and CALC have no D-space.. You can $ee this in both.
Figure 7-9 and the map in Example 7-2. The map in Example 7...,2 show~
the vi rtua1 address space allocation for both r....:space and D-'space ..

7-10

.{JS,ER"'.:'·M,ODE .I.- AND D-.SP:ACE (RSx..:11M .... P:LUS ON.L·Y}

·D-s~~~e i:a;k

J/t,

i\nd
,
uses ritor<e ·Vi rfoal .memor17 space. t)lan a
.~¢>i'\::v.e'n~!wir:1'.L·>·· t~sk.; ·.The' map"in Example 7-2··shows that MAINID.TSK uses
·rgff,a,.,,· wo:.ras. of. space· as. opposed .to the 1'66.4 •. wo.rds used by MAIN.~SK.
'Th~· .. reas.ons. for the ·incr.ease in size. of MAINID~TSK. over MAIN.TSK are
ii·~> ·f6liows·
£. · ·
. .
. :

,, >'

'.Anj"'." a.nd· o..:..~pace .t·ask contaLns an unused· task header.

Atl'bo·l6ad':v~ctors· i.rLah 'I...: and o:..space task

contain two· more
tpan ,.. comren.:tional. aut.oload vectors. PSECTs. $$'ALYD .and
·:$.$A):.y'r'.jo >E'x.amp~e 7,-:·4. · con'ta.i.n the. a:utoload ve~tors.. . You · can.
·. ·s.e'e.· · f·rom . . · thJ. s ma.p ',that .they. u,se more space. than the .•$$.ALVC
PSE,C.T ··in.c MAIN.~TSK,;. wh.:Lch con:tainS" converitio.nal.
autoload
. w:e~,t;or.s:;
...
. word~

''""'

·.·~:•< '.>~n~,.:~Eig~.ent· .d~sci;ipt 0 rs. ·:in arr o·verlaid' . r~ ·a.nd

. //..,,-1:~?~a!~J:•fi ~."t.et\s~~h: ··.

. .. . .

o.:..space · ta'sk

" . .

... ·a:d'chti'Oo '.to '..·tb~.~~·"':r-eas.ops . Jor· tbe> inctea«se 1n . . ·s.ize. of'. .. an ov.erl'aia

"::.'~fna·.'.'·, . ·b~·sp·ace' ··· . . i:~·s~.{·:a:.. memo·:try·~re'si~feri·t·.«;.ver1a:±a · •. l·~· .and,·.· o--spa'ce. · task
·¥ii;JJ~/.·1J~.:',~v~eri •e.larg~r·. ,qe.<;=·aus:¢ . :~:€' ,th'e;'·n~.~d' ·fq~· 'two· ' wind6w: descr'ip'tors
·*f::~~r/. ~~P,i,·.·me.!ll~~rYf~r'~?ide,.tjt ,.t:>'egm~~t:• · / · · ·
004413

004413
003263
003007

003263

INPUT

003007

OUTPUT

CALC
002714

002714

I00271...,

002713

MAIN
000000

__
q

--~~~~~~~~~~~~~~_o_o_o_oo

ZK-1108-82

002513

OUTPUT
002414
002413

002414
002413

MAIN
000000

000000

ZK-1109-82

Figure 7-9

Memory Allocation Diagram for MAINID.TSK D-Space

7-11

USER=-MODE I- ~ND D-$J?ACE Uf9},{-11M-:I::LU$ ONLY)

Example 7-·l
MAIN.TSK;l

Me~ory

Mpp of Overlaid Task M]\IN. T.SIC

alloc~tion

20-0CT-82

map TKB M40.10
10:08

T'ask
name
••• CBP
Partition name
GEN
!dent.if ication
voo •.oo
Task UIC
: [240,l]
Stack
~imits: .b00320 UOlil7 061000
PRG xfr address: 002350
'Total address windows: 3.
T'ask image size . • 1664. ·words
Task address limits: 000000 · 006307
R-W disk blk limits: 000002 000012·

·Page ml

· ··

MAIN.TSK;l Overlay description:
Base

Top

000000
004514
004514
004514

004513
005063
004607
006307

MAIN. TSK; l
MAIN

Length

-----004514 02380.
000350
000074
001574

00232.
00060.
00892.

MAIN
INPUT
CALC
OUTPUT

Memory allocation map TKB M40.10
20-0CT-82
10:08

Page 2

*** Root segment: MAIN
R/W mem limits: 000000 004513 004514 02380.
Disk blk limits: 000002 000006 000005 ~0005.
Memory allocation synopsis:
Title

Section

------. BLK.: (RW,I,LCL,REL,CON)
CO Ml

:(RO,D,GBL,REL,CON)

COM2

:(RW,D,GBL,REL,CON)

COM3

:(RW,D,GBL,REL,CON)

COM4

:(RW,D,GBL,REL,CON)

COM5

: ( RW, o, GBL, REL,CON)

001320
001320
001570
002006
002006
002032
002032
·002064
002064
002074
002074
002330

000466 00310 •
000250 00168. ED DAT
000216 00142. CBTA .
00:0024 00020.
000024 00020. MAIN
000032 00026.
000032 00026. MAIN·
000010 00008.
000010 00008. MAIN
00(>234 OOTS.6 ..
000234 0.0156. ·MAIN'
oolob20 00016.

I dent

File

03
04.3

SYSLIB. OLB; 5
SYSLIB. OLB; 5

voo.oo .MAIN. OBJ; 36
voo.oo MAIN.OBJ;36
voo.• 00 MAIN.OBJ;36
VOO. O'O MA IN. OBJ ; 3 6

(continued on next page)

7-12

...
H

· ·Exaffip·r·e ·7~l ·'_{cont ~j
'

, '

Map .of Overlaid Task MAIN.TSK

002330 OOOQ.20 00016. MAIN

trnRoT: (RW, 1/bat,·R·E£~coN).

VO.O. 00 MAIN. OBJ; 36

. ;· O()Q.00'0 000140 00096 •

. 000000 Ob0140 00096. LIBROT 03.0l LIBFSO.STB;l
00'235()'000142 00098.
·002350 000142 00098. MAIN
V00.00 MAIN.OBJ;36
. .002512· 000'024 00020.•
$$ALER,: (,Ro,1;.,LcL;;I~.EL:j'cgN); \.
··oo25l2 000000 00000 ~. OVCTR 15. 03 SYSLIB. OLB; 5
".· 0'()2512 ·000024 00040. ALERR 02.00 '. SYSLIB.;OLB;5.
002536. 000070 .0.0056 ~
: (RO~ I,LCL;REL,CON} .··

•MAIN
,.

;

. ;Gi«:i.ba {.: sym\;)9.l;s '.:·'. /I

~~~~·s·6·;~·.(.;·N..ta"JZQs·;:.rioo.o2«f: :.~:ifai)~T . ·001s7o:..·R· ... ~Fs;a·PT ·«moo so . ·..

iAoo· ..·

,:~~~at.~. :p~r2«M~--~/<;~"·:·~~~.1'.:·/~·q·~·~:~:/.:';; ·/~CJ\Df1{:; Q·Ol.57.6-R. ; :•.;NALER"::0033~'4-l( .
~ ~·'; <;

-~;. (;:' <.
\.,

••

•

t-tA.iN:·.r·s.I<;'r' · Meni'C,~~:·· ~i1ad·aition:· .ni~~ · . ·TKB. ·'.M4. o.~1o.-

"rnJ?U7'. . ,_.· '

·-.: 4o~ocT..:;.a·2
..'· ;..:10:
oa.:
" ·'''
' : '·
!; : ,
-,.

~:\

,'~

<.' <

* ·',

R/Wmem . limits: . QQ.4514 005063. -000350· 00.232.
J:?i.s.k .. mlJ~ . .lim.i .t:s : . · . 0.:00.~>0l .OJ>.:·~·001·:: ,0000·01 . 900.01 !' • :· ..; ...... .

Title

::{.-.~~~:7;.( .Rjfl:.~.i~f·~~,~~.~.:~.·~p.~·~i .: :"
;·I~PUT' ;: :·(RD, ,''r:cir:;I<E:t·:cori}
'

.;,"

·;·, •"

(."

•

;. •

,'. •

••

~: ,:. • .~·

:;" •

i--

•'

w'>

,'.

OOOGd ... .

. ,\

Ident

OQQ6tr ... C.A'l'B.· '.03 .;'.

. SYSLIB.OLB,; 5

00170 .•

INPUT· OI

'$·$f\tVC":"(RO,, .I·, L~.4.:~~.~d,.·C.~fQ
' .
.'
.. /' .~:" :/./ .;· .·· ...:· ..:·

-~---'

·... INPUT. OB.J i32

'•.'

~:,:; ·~

,
·;

',,,

;··
~··

;

Glo.bal §ymbo:ls :' · .i
I

INPUT.

0·04610-R . ~CDTB \\ 0.04?14;..,R. "$,COTB . 004522:-.R

(continued

7-13

011

next page)

USER-MODE I= AND D~SPACE (RSX:--1,lM-PLUS ONLY)
..Example 7..-1 (Cont:.)
M~IN.TSK~l

~ap of

Overlaid Task MAIN.TSl~

, ·Memory allocation map ' TKB M40 .10
20-0CT~S2
10:08

Page 5

r.,

Tas~ ·builde:i;-

statistics:

. Total work file references': 13626.
Work file reads: O;.
, . Work file writes: 0.
:.size pE.core 'pool: 51,98• .words'. (20.~ pages}
Size. of work.file:. 4.096 •. words.. (~6 ....Pages>'.
El~psed, time:OO:OO:l9

. Example 7-2
MAIN ID. TSK; 1

Map of Overlaid .I- and

D-Spac~

Memory allocation map TKB M40.10
15-0CT-82
11: 51

Task
Page . 1

Task
name
••• CBP
Partition name
GEN
Identification
V00.00
Task UIC
[240,l]
Stack
limits: 000256 001255 001000 00512.
PRG xfr address: 000744
Task attributes: ID
Total address windows: 4.
Task image size
1184. words, I-Space
704. words, D-Space
Task Address limits: 000000 004413 I-Space
000000 002513 D-Space
R-W disk blk limits: 000002 000014 000013 00011.

MAINID.TSK;l Overlay description:
Base

Top

000000
000000

002713
002413

002714
002414

01484. I
01292. D

002714
002414

003263
002413

000350
000000

00232. I
00000. D

INPU.T

002714
002414

003007
002413

000074
000000

00060. ·I
00000. D

CALC

002714
002414

004413
002513

001500
000100

00832. I
00064. D

·OUTPUT .

Length

------

MAIN

(continu'ed. on

7-14

next pa,ge}

l- ANDO..:.SPAC~ (RSX..:.llM-PLUS ONLY)
"

,. Map nf Overlaid .I- and D-Space Task MAINID. TSK
'.',

,'
,.

,~:

'·>

•

;

••

•••>

j.<

Memory· .·allo.ca'tion map TKB M40 .10
.
15~0CT"".'B2 ..
11:51

Page 2

1iinJt.s.:··.oirnooo.:. .od2iiJ /00;2·7H OH84 ..; 1,..space
· ,' · .... , P. O·Qog-o ··oo}~'.1),·op2414 01292. n.,...space

Ob:ClO.o~r dOCl03 ,; 1.,...space
000,003 00003. D-Space

fitle

!dent

File

· :.909~56 ·o.o04'66' :·003l() ~· .

¥4t;~ '., {R?\D','G~Il;?EJ. !<;o!J)
..i:af..12"' /~A~w,,:o·.:'c;stlRtr/
·c0N)~ .•
~;
;''.~"-i ~
'J· .; -. . .,

~' :' ~/ .,<· : x •·;

•

i<o

X•f;,"···>

.. . .

·.~~P~k !·f~w. ;•'E).; Q~:f"'i:·R~w.1 .ca:N:> . :
60~·4· .. ~)~~. ~:oi~kL.,1z~t :coN)
:.:~'od::/ :·''{,R~/rf;'GBL;;R'E:i,·coN')• ''"
·.rA:~~o.P
::. lRwJ:.i
·:G~fr :·Rfili.· do~>··:
" ,' , ,
\'
t
;~~~·~~: '.•;~.t,~o',::i' /i:cr. /REL;CoN1 <
I

'.f~i:~;~~:::j~:::~:::::·.···'

··'.~»#i~Vf;;?(.R;~ .~' t~ i.ci:;·R~t..:,/co·N): >'
~·

.. J r:::./,../i' .. ·~.·· , : ) ;"·

.....·.

. 000256 '000250 '00168. · EDDAT 03
000526. 00'0216 00142. CBTA
04.3
ncn2·56 .·000024 00020·.
voo.oo
0012'56 00002'4 00020 • MAIN
0.0~3.02 0000_32 ·00026.
001l02 000032 00026L MAIN
voo.oo
.0·01·334· ·0000/10 00.008.
voo.oo
001334 ,00001.0 00008. MAIN
Obl!44 000234 00156.
Q;Ol.344, 000234 00156. MAIN
voo.oo
001600 000020 00016~
0.01600 000020. 00016. MAIN
voo.oo
00.0000 Ob0140 00096;.
000000 000140 00096~ LIBROT 03.01
h~074~ ·000142 00098.
V00.00
0;0·0144 .'000142 00098 .. MAIN
·.001106:000024 00020 •
.'001106· ooo·o·oo oo·ooo. ovrnR 01
OO:·U:06'.·00QD.24 .00020 .. ALERR 02.00
001620 000034 00028.
- .0011~2 oorio10 ooos6.

SYSLIB.OLB;lO
SYSLIB. OLB; 10
MAIN.OBJ;34
MAIN.OBJ;34
MAIN. OBJ; 34
MAIN.OBJ;34
MAIN.OBJ;34
LIBFSO.STB;l
MAIN.OBJ;34
SYSLIB. OLB; 10
SYSLIB.OLB;lO

<,.

,/~~·9t;>~1 ~.Y~Qqls.:,

..AA.riri. ,• .6oiis2.-.R. N;.D'rDS 000020
'"ARGBLI( OOH16~B: · N. FAST OOOOT.3
~')

o,
·,~

$CBDAT 000526-R
$CBDMG 000534-R

$TIM
$VEXT

000402-R
000056

MA'INID.TSK; 1
INPUT

Memory allocation map TKB M40.10
15-0CT-82
11: 51

Page 4

{continued on next page)

7-15

Ex~mple

7-2 (Cont.)

*•~.segment:

Map of

Overl~id

I- arid

D~Spa~e

Task MAINID.TgK

INPUT

R/W mem. limits: 002:714 00326.3 000350 00232. !.;,.Space
002414 00241,3 ·000000 00000. · D..;.Space
Diskblk limits: 000010 000010 000001 00001. I-Space
000011 000011 000000 000.00. 0.-Space
· Memo~y allocation synopsis:

Section'
• BLK~': ('RW,l,.LCL',REL,CON)

INPUT .: {RO·, I, LCL, REL., CON)
$$ALVO·: (RO, o, Let., REL ~CON)
$$ALVI: (RO, !,LCL,REL,CON)
$$RTS : (RO, I ,GBL r REL,OVR)
$$SLVC: (RO, I 1 LCL, REL ,C()N)

Global symbols:
INPUT

003010-R

MAINID. TSK; l

CALC

$CDTB

002714-R

$COTB

002722-R

Memory allocation map TKB M40.10
15-0CT-82
11:51

*** Task builder statistics:
Total work file references: 13920.
Work file reads: o.
Work file writes: o.
Size of core pool: 5010. words (19. pages)
Size of work file: 4096. words (16. pages)
Elapsed time:00:00:28

7-16

Page 5

. CHAPTER 8
·.s.UPERVISOR-MODE LIBRARIES (RSX7llM-PL:US ONLY}

·.~···s\.lp~rvl~ot~mode library is a. resideirt'library "!;hat'· d.qubles· ·.a· " ri.~. e:r;

ta$k~s
virtual addr-ess ··space· .bY. mapping the ins.truction· space· ;of, t;he"'
·.. processor·'s supervisor mode. Supe.rvisor-mode libraries·. are. availa.ble
(,mly. on ~SX-.llM.,,;PLUS s:l"stems :r'unning on l'DP.:..11/44s ·and PDP-'"l1/70s .. ·

,''

,,·

8' .. 1· .INTRODUCTION·

call ·from within a user task to
a .. subr.outine . within .. ~·
. supe·rv iso:r:--mode · 1i brar;y causes the processor ·to switch from us.er . to.
supervisor 'mode. The user task transfers control ··to 'a mode·:..swit:chin'{;J
vector that TKB includes wi,.thin the task. The ,.mo.de-switching ·vectqr
performs. the ·mode switch and. then . transfers control to . the· ·ca'lled
subroutine· within the supervisor-mode library. The library routine
exe.cutes .wi.th the processor in supervisor ·mode. . When . the . libreirY
routine. finishes . exec'uting, it transfers control . to a completion
.routine withi(l .the. library•.. The· completion routine. mode. switches ... t.he
. processor back ... to us.e·r mode.·· The us.er· task· ·continues executihg with .
.the processor in use.r m.ode at the return address on the stack~
Thi.s
process r.ecurs . 'whepever the .. u.se't 'task .. calls a subr9u,:t:.ine in \he
supervisor:..mod'e library •

·A

. ·In,·~ ·task 'that. links:,~~'?'. ~upervi"sor-:-mode' . ,~f·brary, TKa· :. in.eludes .. ~,
:~ 7 yii.o.rd, '.. ;mod~-switchi'ng . 'vector
in .the usei;: t:'a,sk' s address · g,pa:ce fo'r·
~ach entry point ~efer~nced .of. a subroU:tiqe in, t,h.e 1ib~ary.· .
Th·e

follo~ing

shows the contents of a mode.:..swi tching vector:

MOV #COMPLETION-ROUTINE, - {SP)·
CSM #SUPERVISOR-MODE--ROU~INE ADDRESS
NOTE

When mode switching
from
user
to
supervisor mode, all registers of the
referencing task are preserved.
All
condition codes in the PS saved on the
.stack are cleared and must be restored
by the completion routine.

8-1

·LIBRARIES . (RSX...;.llM-PLUS ONLY.)
' ,, 1

,1i;·b~·r: . '/the·:: . subr6utJPec . , fi.tlishes · .· exe9uting ," .its', ·. RE'TORN

','statement

/~H:.<:fos·fEe.r:s· . . ·con'tr;:ol, to a. co;mpl'.etfon ·r.ou.Hn.e· <tha't.·mo'de~switche.s.·.. ·from the

t~:upkir.~:~~or:'.::t,p :i1~e,·i;·,· ·mode. ~:· . /.·Tl:i~ · :··:·bQmJ?le.t:~9n· :'r911~ine,· · 'r·etu(,ns, ·pro9·ram
:co·n.trp.l :oacK.·•fo:'.the. ref,:ere·n'cin9· ·.ta:S.J(,a:t/~.he.· instr\1ct·iori, ·after'.the Ci:ill
;:·~'<>./the. ·,~u~.rJ);uti.'n'EF.~ ,· T't;i~i:e :~.~E{ two compl,.e.~ion:,·.,rouq.ri~s: i'ri' sysLrB::
i

/..:hE~:.::/.· :e""·"···$·~~~b~:::r,es,f~~·~s. .'~~:1·~ ·the, ~a~iy ·.bit'.'.i.n .:eh~·.us~~;·mode·"Ps·.

~~~}'~lA~~~9 !' ¢~ i~i ~/,~~~. '¢0~ ;;~~ o~ ,b~. 11 t'~ • fn·:·:t~.e. . Use~'"m6d i
·~~~· .·~.~:Pifr~~iO~:~ .'T~ ·co~TIDITS' or ·S?.~~~i~~LHoDPl' "L1~RAR1Es
I

.... ' · : '

••

:·,/:

. ·.. ··

•

.··

'.~· ',f01'.1o~i~·., ·~e~f.i;lcti.i>ii~·,·. .
·.:~\'.!per:<i;f$or· . . moa'e·· .:J.~.orar.y·;

f: ,:· ;: ·: :'), ;' :

·\., ;; '.~'

. , .'

.. '"

)

>,'

,· /

·' ;::'

.''

•

'•

' . · .. •

...

c&n.ten:ts ·

, ··.. , · ·

'~ I~,,

• ,:/,on1y · s&hrol:itines .~~ing. t.he· "f·orro/
·' ,'w;i:th.i)i . . ;the~ :Ubra"~i ... "·
·

should 'be· used.

~·

' The Ubra·r·y must· not .contaih· s~h;routines ·that use the stack to

•ipa$S ·"parameters.

If·. bot:h the library and the referencing task link to a
su•oroutine · from SYSLIBi then the . entry point name of the
·subroutine must be excluded from the .STB file for the
librar. y.

•

Unless you include the MSDS$ directive within the library, the
librar'y must not contain data of any kind (even R/O) because
the user supervisor D-space APRs map the user task by default.
This includes user data, buffers, I/O status blocks, and
directive parameter blocks (only the $S directive form can be
used, because the DPB for this form is pushed onto the user
stack at run time).
Using the Map Supervisor D-space Executive Directive (MSDS$),
the library can map data within the instruction space of the
supe~visor-mode library by using the supervisor D-space
APRs.
The
directive . maps specific supervisor D-space. APRs to
supervisor instruction space by copying the supervisor I-space
AP.Rs that map the data portion of the library. Ta effectively
cont~in data within a superv~sor-mode library, you
must know
~h'ich APRs map· the data por.tions of your task and library.
NOTE
· " · You 'canno:t: use. t1SDS$ t9 map:· . superv i soi;
, D~sp~ce APR .o. ' Mapping 'libra. ry· data and
·the ·user .task,. s'imultaneously' should be·
d.one with }3X tr.eme ca re..• · . Se~. tJ'on 5 • 3 • 4 .~ 2
of ·
the ·, · RSX-.ll,.MfM•PLUS · Executive ·
Re.f'erence . · Maniial .• "9@.scusses the MSDS$ :
directive~n ~eta~1~J

8-2

, suE:E'Rvisn'R...:!itoo&:,iErsMR1!E~~,,',

·:~:e~=~::::~~;~~:~:i¥.t!,ixwi.~ · ~ ~ • ·~uW~1rA&~·.· f~ p~;~j.· ·A:
...

Supervisor :D..:space' ,:]\J?,Rs,, · . ,can'.,;':Il1ap /.,.:·the""'.'user,, ,J.a·s'k 1 : .•;,d.a~~.:··wltbin",.tpe,
libr.ary,..or J),~.th ·th.~:: "US~F.·,ta.$k•:, . ~,,qa, . ti:tir~1fy:·:aa.t;:a:',·'s,i.~ul,·~·a·r~9.uf3:i'.~/z'/ ':: ::~·ile'y·

:::

::;~:!::~~;~~:c:r~::;~~n i>~/;' ·~ai~ii

~hether·,th,e ,1·1.,bl:".:;iiy···c·o'otai:n.f?: :aAt:~·.".

' .

> ~<'

•i.,

'·

.,,

,.;

;:;,

. .'

~'.., 1 ,:: (.

,/ ,: :h _,-· <'/

;:.: -~; ~·

, : · ·"'.·

.. ...' . ., .. .,•

,sµ:P7~,y1s~k IJ~.sw,ac~·/r{~~~:·r:~~~/"S·Qf>F¢.s,:
entire: . us'e·r: :>task;;",.···.. 1.1hl::;;·:9,1:ve&:··,,:t

uSe~ .t;as~ ~ ~+1.ll!~/7}-': (1~.u!ff
~

J!/

}

.u.: · · · . ·e ···/~·PRs:.; ," :;·1ac/]Ar~:i:.n~F .;'the:,:·
E~ecutiv·e"./,,q:ir,:e<tti,:J.e'/('$·.e~· . · · tio,tr :< . J" "w.~.A:'b,1,:ii" . · · ·}l),i:~~"r:YJ
'ri
.t. J:re· 'r±l:>;tq_,ryt' .t6tina·f> :::aa;ta·:~"!1'fft: . ~. ·/?ts~: /6·\4n}}:in~itt,~;qt:J:. . .· ..· .· ".,i?,C:~· ~,
'task . m,a,"y: · ,),·e,,::,,· ~Ef·~i1\~el?,~.4;~"x/. '.~~·~'·/
~:~r:,i'.·!;ia'~·/ . .e,c:¢~,s.~::)~Q/~~.t.:l;t/~ . /:n,·::.l,,· )i"
iristruct1·9·!f .. ~pace,.:·.ad·&;·t.o;rBa:t:'a./Jn: .. ,:.:u?e.if.J't::a'eJt.::'1\;tii;l.~?'/i~;.;'tic:ftFJf~;u;efrn\~1ipe,a::
by the MSUS.$.: ,«~d"·i;7,G£.i,,y~'i<,..: .
. "
. :' :·, , :· ,:'///' "' .
APR~··.a·r~ •. "·qo·p·re's .'/.of',' ,",the:·,·.<":u·serr.·'

Figure aC:2.}

(f~lli~~~.;;{. ~~i'S, ~~~~~~..~,:

8-3

VIRTUAL
ADDRESS
SPACE

USER
D-SPACE

32KUN~0
OK

PHYSICAL
MEMORY

AP Rs

256K

c:.

32K
USER
I-SPACE

24K
USER
TASK

24K
USEFl
TASK

t:IJ

l:O

<
1-1
en
0
l:O
I

3
0
0

t:IJ
C"1
1-1

I
,i::-,

32K

o:i
l:O

24K

l:O

SUPERVISOR
D-SPACE

1-1

tel

USER
TASK
(COPIED)

en
16K
SUPERVISOR
LIBRARY

OK
32K

:;o

:><
I

.....

.....
SUPERVISOR
I-SPACE

3
I

16K

30K

LIBRAIW

C"1

TOK

to<

APR MAPPING
USER D-SPACE
USER I-SPACE
SUPERVISOR D-SPACE
SUPERVISOR I-SPACE

UNUSED
0-5 map entire user task
0-5 map entire user task
0-3 map library
ZK-439-81

Figure 8-1

Mapping of a 24K Conventional User Task That Links .to a
16K Supervisor-Mode Library

32KVIRTUAL
ADDRESS
SPACE

USER
D-SPACE

PHYSICAL
MEMORY

AP Rs

!SJ

OK~

~256K

SK
4K

20K
USER
TASK

12K
SUPERVISOR
LIBRARY

·r-------~""f SK

USER
I-SPACE

32K

co
I
U1

SUPERVISOR
D-SPACE

20K
12K
SK
OK
32K

SK
SUPERVISOR
11-SPACE

12K
SK

- - -

30K

INSTRUCTIONS
OK

_JOK

APR MAPPING
USER D-SPACE
USER I-SPACE
SUPERVISOR D-SPACE
SUPERVISOR I-SPACE

UNUSED
0-4 map entire user task
0-1 and 3-4 map user task
2 remapped to supervisor data using MSDS$
0-2 map library
ZK-440-81

PHYSICAL
MEMORY

AP Rs

USER
D-SPACE

256K

32K

16K
USER
DATA
32K

USER
I-SPACE

16K

----

USER
INSTRUCTIONS

24K

40K
I- and DUSER
TASK

USER
INSTRUCTIONS
OK

32K
8K
SUPERVISOR
LIBRARY

°'

SUPERVISOR
D-SPACE

16K

OK
32K

SUPERVISOR
I-SPACE

30K

APR MAPPING
USER D-SPACE
USER I-SPACE
SUPERVISOR D-SPACE
SUPERVISOR I-SPACE

0-3 map user data
0-5 map user instructions
0-3 map user data
0-1 map library
ZK-1105-82

Figure 8-3. Mapping of a 40K I- and D-Space ~ask ~fi~tjLlhks
to an BK Supervisor-Mode Library

LI:BRAQl>E~ . ·'(ris~:-"1.'.iM~PLtls.:. ~bt.Jr,;l'f ·. ,; .
;

>;;

~·

~·' ' > _;

,:"

i ;,

:a~.6·: .BOILDiNci:iND LINKING TO SUPERVISOR-MODE IJIBRARIES·

to'·

' ,

•

.Btriltl.ing and 1 in.king
a supervis:or_;mode,· llbrary fs·· essentially the,
.same . as . ·b~i lding . and <1 i,n.ki, n.~~l. · ,;t() •.' ~ ..~11v.~nt,.i9nal resi&ent llbrar·y·
(dfscus~ed in Chapter; . 5) •.
When you ouild,' a . . . super.vi.sor~rriode Hbrar.;t,
you suppress · the . header · by . a;t:bac.hJng· /-..HI? to the ·tas.k ·imag·e file.!'
'During option ·input, . you . suppre.ss the· ,·stack. area . by . specifying··.
·:. S.'l'ACJ<=O •.. ,,,jou speciJ:y tJ1e pai.tit.i()n in wb'tch.·th~ libr~l:'Y .Js tc) r~sid~'.·
',arid,· qptiona}ly, tne .. base address··an&.1en9th of· tt1e· ·library with· the'
~AR.option.~ .. : ·
·
··
·
·
· · ·
· ·

.
'

.l.,.,·

· .Ex,cludes .. a:.globatl,,synl'pol tram the .• S'l'~ :.file
'of the superV;isor,:...mode .library. . . • . .
. . ..

.. · ~BL~qi;,·.
~'

;

~ ;,~

~, <, '':>' ' »" , ; ,

,;<<

<$ l

;·

<~ 'i ,'

~ ;.= ~·

> '·

i; ,, .,

,,· <:;:· ,,

Whe~e ··PP.tJ~ris ai.~ ~iscu~sea, btier1i· . .:b~·~'o~·i',:apa, .. ·~17e'. ·~.~l~·}r.·.~~s~~·~nt.ea'.: .in··

Chapter 11.
:./

;

·'

'<>

Buil~Hng. t.he ·L,ibrp.ry

8 •. 6. 2
,,

•

'. <

..,.,

.You ..fndica.t·e ·~o·

, ,.,

,~~-.

•

,/' o.'

~/ . ' "

~,,,

the ., .Task· . ~~i:r<l.e.r. :tha.t:: ·, Y~.u.. ·.a.~~.·.. · . bdfra·ing.
a:
superyis,or~mode. ,;lib.rar,:y wit;h ·the. CMP;RT o'ption ..... ".·'l'he ,.a:i;:g.ume.nt: for. thi~
9pt ~·on. • .~de.n:~±·ti~s·.. ~h~:·.,~r1tr.y:·.:·st!I\l.l9l /'.()~ ·~he.·.(·q()~r:>::le'fi·?p::· ./·J:<:>Ji~.i:rl:~·: / .. wfien
i:tt.e''. ":Task'·:/s·~1:·1c1·er>. ·.pi<lcel~se,s··.::'.".·~~·?.~i .../,.op{?f(>.n.'/:...:··~.t::·Ji~a'~~·$i:'.·tYi·~...~. oJtiE.Ie:~4·~!l;
·r:0J:ItJ.ne .entry"'point. .in )th.e . Hbr.aryJJ; '.qTl3'.<f:i.J/e ..... /Tio· ·~}C~lua~. ,' .·a...-J.gl.·ob~f
sym°'91.: fr()rrt'.:· ~ne: ilbj:·~r.y:~s· ·····~.s·'l'~····.·f!~~·~:,,.·:·\·~,.o~u<,.S:P~:c}·~i· ~f)~'.··.I'l~?1~. ':a.i;··::4:·he.
'gl.o.p~l"5:ymbo;I.. · ap o,t:h~· ~rgumefrt .9~·, . tl1~.···9sµ)~.¢·~· :.oP~iPh,·•':· . ·~<iu'.mci~·~ ·'::~.xclua~
froIP· .the::· ... STB ·'q:l.$·" .<>~· ·a· .. sup·er..v'i;s,0~7m.oa·~.··.1·ibr.a.,i,'.Y :'.pny::s·ym.hoi·::defined" :ln
t:fa·~. :·Hhra·ry ....tha:t.;'.r·ep.r¢'s·e 11 t:~ ... ~:'rie":fo·llqw1ng . ~'. /: ::'.,, . · ..: .....

,:>'

·,,'~.::·.,·/... : ' · '

'·.,,";

';~"'.·'"~""

"""

"",

''",

,,,~

/.$.,i

~-"

:-,

>.. ·,,/,.·"· ·. ···. ·......··

~-,~"

.•.. An· entry point/to .a s9bt'6. uti'ne· th~t'.<u~·~$··"'. . .fhe·
parame.ter.s · ·
~

•

8. 6. 3

-<-- .o("''

.,'

·----

. ,,

,-.,.,;',·

·~t~9k :

to . : pa's·~'

mode

that

An entry poi,nt to. a subroutine .rp.ai~ped·' t~· user
~e~erencing u$er task . calls

'the

Building the Referencing· Task

When you build a task that references a supervisor-mode library, use
the RESSUP option if you are referencing a user-owned, supervisor-mode
library and SUPLIB if
you
are
referencing
a
system-owned,
supervisor-mode library.
(Like the RESLIB and LIBR options for
linking to conventional libraries, RESSUP and SOPLIB are . functionally
the same.) The arguments for these options are:
•

The filespec {R.ESSUP option) or name (SUPLIB) of· the
to be referenced

8-7

library

SUPERViSOR-MOOE LIBRARIES {RSX-llM-PLUS ONLY)
•

A· switch that tells TKB .whether 'to use system-supplied vectors
to perform mode switching from user to supervisor .mode.

.For position-independent libraries, the
first
available
supervisor-mode I-:space APR that yo.u want. to map t.he 1ib;rary.

8.6.4

Mode Switching Instruction

Mode switching occurs with' a new instruction available' on, the .11/44.
arid emulated by .the Ex.ecutive on the. 11/70. Througho.ut the rema.inder;
of the chapter, supervisor-mode libraries are ·referred· t:o . as, CSM
(change supervisor mode) libr~ries ~

8.7

CSM LIBRARIES

This section discusses how ~o~ build and lirik to 'csM libraries.
It
also shows an extended example of buildi.ng and linking to a CSM
library and explains the context-switching vectors ·and' completion
routines for CSM libraries.

8.7.1

Building a CSM Library

You indicate to the Task Builder that you are building a CSM library
by specifying the name of the completion routine as the argument for
the CMPRT option. This option places the name of the completion
routine into the library's .STB file.
Link the completion routine,
either $CMPAL or $CMPCS, located in LB: [l,2]SYSLIB.OLB, as the first
input file.
Although the completion routines are located in SYSLIB
(which is ordinarily referenced by default), you must explicitly
indicate it and link it as the first input file.
You must also
specify in the PAR option a 0 base for the partition in which the
library will reside. These two steps locate the completion routine at
virtual 0 of the library's virtual address space.
You specify the name of any global symbols that you would like to
exclude from the library's
.STB file as the argument to the GBLXCL
option. You must exclude from th.e
.STB file of a supervisor-mode
library any symbol defined in the library that represents the
following:
An entry point to a subroutine that uses
• parameters

stack

pass

entry point to a subroutine mapped in user mode
• An
referencing user task calls

that

the

[30'1,551

the

A sample TKB sequence for building a CSM library in
SY:
follows:
· ·
TKB>CSM/-HD/LI/PI,CSM/MA,CSM=
.
TKB>LB: [[1,2]] SYSLIB/LB:CMPAL,SY: [ [301,55] ]CSM
TKB>/
Enter Options:
TKB>STACK=O
TKB>PAR=GEN:-0:2000
·TKB>CMPRT=$CMPCS
TKB>GBLXCL=$SAVAL
TKB>//

8-8

UFD

,Th~ :library is buil't without, a 'header

Oi , ~tack, . like, ali
regions.
. It is position. independent' and, has only one ·pr,a<}ram'
·n,amed ·.ABS·. , The '/LI switch · accomplishes th.Ls,, eliminating
section
name conflicts between,
the library
)md ,the referencing
,
.
,.
..

. ,.

·The completion.· ·routine.module of. ·SYSLIB,'··CMPAL,... is specified.. first· in
the input line. The library will run· in par'tition GEN at o and. is. not
more 'than lK. These are · two aspects of building su'pervisor--mode
:libraries' specific to CSM"libraries: . the completion routine must . be
linked. first, and must reside at virtual. O. Why' the CSM library must .
. ·reside ,at virtual· 0 is discussed in Section $.8.5.
·
~

'\;

' •

•

• '

•

"'"

• "

•• " •

• '

• "I' .

'".

> • ~

" ;

•

·;

The. C.MPRT option specifies the global. ·symbol $CMJ?CS; which is· ·:th€?'
.entry point: .. of: the co@p1et..iori r·ou.tine •.. No'~e·Jiha~ the. SYSLIB m0du1.e:·
n~me is ''CMPCS" and its• corresponding global. symbol is 0 $CMPCS 0 •
The·:· GBLXCL op'ttcm excl~des' $.S.AVAL ·'from th~' 11;b,raryl,5' .:pT.B :ffle.' bec~u'~e'
.~})~· user· task {'C\ust 'reference. 'copy·
'$$AYAL· "tha:t. }s "mapp~d. 'wi t;h :us.ej:",

'~m~4.e; A_~RS •

,-<

i,.

of"

,'If your 'task links' to· a use·r-owned CSM libr. ary·, .you us.e . the RE$SiJP
,'opt:ton: If your task links to a system-owned CSM library, .you, ~se.' t;he<:

·SUPLIB option. These options tell TKB tha't the "task will' : lfnk" fo' . :a,
,·super.vis,or-mode 1Ibr·a·r~... ~Th~ ·apt:ton. t:ake~ . :.·'1:P ·,fo:tpree· ~.rg.u~ent;s;

•

The fi lespe.c .(RESSUP.. op{io.n) or .name (StJPLIB
. l.ibr.ary
·

opt,ioh) <. of. the

··,.,:A:,swit.ch· . that'.· te11s'.·. . the .·.Tas·k, ··.B11ild.er, .·whether
system-supplied, mode:-swi.tching vecto'r"~
··
·Fo.r. 'position-independent lihrar.ies., ·an "AJ?R· that: must be. ~PR a·
• 'so"
tha:t th(=!' ,library's comp1i::tion., ro,utine: is ·mapped a,t 'v.ir:tual.
',,,, Q,.~<·

,. .,~.

,'th'i:s Jtifor@~tion.··:etj~9le§:"'the,'.J;a'~,~ ~~i~:{l~.r· ,t,<?,' ~~~~.•.~t~1~ '.. ··.ST~ . · ~. il.~' . • fo':t'
the · CSM . library, ..include a :A-wo·ra.~ niode.~sw.1t.ch1ng vectqr· within ':·the''
· ~s~r, ,ta~k. for; each.· Ceil.1 tp a.' ':subroufan'e·. 'Within.·· th~ "~·~b.rary,." "a,nt'.(
:. correctly map the library' at ·~irt\}al' ·o· in:·,the hbrar·y fnia·g.e.,<·
1

. Th.e . ~allowing sample task:..;build. ,command,s;equen~e builds a... task , n'ame·d.
REF, . which references the library SUPER that: you built in' 'the "previous'
,section. :
TKB>RE.F.1 REF= REF
TKB>/
Enter Options:
TKB>RESSUP=SUPER/SV:O
TKB>//
This sequence tells TKB to include in the logical address space of REF
a user-owned, supervisor-mode library named SUPER. TKB will include a
4-word mode switching vector within the user task for each call to a
subroutine
within
the.
library.
T.he CSM library is position
independent and will be mapped with APR O.

8-9

;

"'I:

< «
,

<,,d •.

,.g .• ,-f •.3 ...Ex;ainp~;e; (!'SM.·Li:brar;Y ;anq ;.~jpki.ng· ·T·ask.

.ThJs· ··~~Cill'lt'J~ shows; y~u<the. q()('.]~ ,' maps,. and .TKJ;l QQmm.~nd .. sequences fo.r
pui:.lding · an:d. U'.nking.·. ·to· .. a '. .:CSM J ib,:r:;ary.that ·contains: no .?.ata in ·a

.• :S~s·tem' .not·:':l~avi'hg 1 JJ$f3«t:' .·.cla.t(i'·;spa9e.+· 'E.X.;am~1e: 8....:1.·sho~s··the :90de ·for. ;the

.. i:fl)d~i;y: :·$0PER:,.'.· : ; a·:nd: . .:. E.xaropJ;'e, '8-2 shows.· ·:1ts .accompanyJ ng map.• Example
'87·3; sMows< th:e,:);oqe. for ··th,e. comple.tiort .ro·ut·i'.nia\ .$CMPq5 th!a·~. ~s 'linked·.· ~n ·
.:t;o'.IStJ:BERf :·f·~~m . S¥SLIJ~.::· '.';E~ampl:Et a:...,4··s:h6ws ;~Jj~ · co·a~·~ ::for·.r·efetencfog. task
:T~OP .; . ;°a;hq :·Jft~ amp~;e · 8..;. 5 ,sbo;W.s: ~H::S, :·a99.u·mpa t1 Y<:i. ng :ma·p • ·... · .
·

:, ~ '.~~ ~,,,t :' j:~

~ ~ ~

>;l

•

4 ,;'

-~ ;,:,}, +:

$·sA.viri' :'

' SAVE:.. J\LJ:.:. }RiG i'~:'.J:'E~~

. · .•. · . . : .
~~~.\g;;:~S~?.~~E~i~~, M~AUMENTS ·.

{R5f+Y · .
.(RS) :+"RO'

(RSJ+:;,.R4 .

GET· ·ADDRESS: :op LENGTH .OF tiI ST
GE.;:£' 'LENGTH .:OF 'LIST
I.F. No.: ARGgt:iENTS .

(R4} ,R4. ·
4:0$
RO,RS .
i.

R4.

;

; COPY
COPY LENGTH OF LIST
·20$:

TST
CMP
BLE
··Mov
. MOV
MOV

(RO)+
(RS) , (RO)
30$
(R5),R2
{RO), (RS)
R2., (RO)

DEC
BGE
DEC
BLE
TST

10$

MOVE POINTER• TO NEXT ITEM
;. COMPARE ITEMS
IF LE IN CORRECT ORDER
SWAP ITEMS

30$. :

DECREMENT LOOP COUNT
IF NE .LOOP
DECREMENT
IF EQ SORT COMPLETED
GET .POINTER TO NEXT ITEM TO BE COMPARED

20$
R4

40$
(RS)+

40$:
RETURN

SEARCH::
CALL
CMP
BNE.

MOV.
MOV
:.1"!0Y'
MOV
BEQ
·MOV•
M:OV

$SA VAL
#4,(RS)+
20$
(RS).i;:,RO

(R5)+, Ri

. (R5)+·,R2
.· (R2) i,R2

20$

(RS·).,·~·5

R2,R3 .

SAVE ALL THE REGISTERS
FOUR ARGUMENTS?
,IF NE 1NO
GET ADDRESS OF. NUMBER TO LOCATE
; ADDRESS OF LIST SEARCHING
GET ADDRESS OF LENGTH OF 'LIST
GET'GENGTH OF LIST
.IF NP ~RGUMENTS
' ; ·ADDRESS OF .RETURNED VALUE .
. ; COPY' LENGTH

;.· .J:s• .T:Hr.S:· . THE NUMBER? .
i

I;F: EQ. l#~ .
IE' MI;. iNtJMBE.R NO.T . THERE
DECRiFMENT LOOP COUNT
J:f; tfE'NC)T AT END, OF .J:..lST
(continued .o.n 11~xt page)

8-10

; so:eERvr'SoR..:.Moo:E'. ::r;t~aARl::ss ,' <Rs:x:t1M~:PttiEf :' oit..,t.J',,,

.'. . . : ;' : · / ~i~:·.1·q~~t:i ,.~o~~-;~~·i)h~~~?f ·.· •

***, 'i'<ls'k b,uf1de,t ,is,ta,ti,sHc~: ,'
To'ta1 work fi l'~' re~e'r:enc,es';, ::320 f ,
, Work , ~ile , rea9s :« ,,0.,
Wotk file writes: 0.
Si,,ze of cor~ ,pool: 6988., words ,'(27. page$)
Size of work file:, 1024,. words (4~ pages) ,
Elapsed

time~00:00:04

8-11

SOPER'V!SOR-MODE LIBRARIES (RSX-llM-PLUS ONLY)
.Example ·a-3. Completion Routine, $CMPCS, from SYSLIB.OLD
.TITLE CMPAL
·.WENT · /OW4/

;
<

, COPYRIGHT· (c) · .1983 BY
'D.IG:J:TAL EQUIPMENT CORPORA'l'IOW~ MAYNARD
~.ASSACHUSETTS.
ALL RIGHTS RESERVED•

'i'

·i. THIS SOFTWARE . IS FURNISHED 'UNDER· A' LICENSE AND MAY BE USED
ANO COPIED ..ONLY IN ACCORDANCE WITH THE TERMS OF SUCH. LICENSE
·. i AND· WITH . THE INCLUSION OF THE AB~)VE COFYRIGHT. NOTICE.
THIS
;'·SOFTWARE· OR .. ANYO'.I'H:SR. COPIES THEREOF,. MAY NOT BE. PROVIDED OR·
. .i. OTHERW.ISE MADE 'AVAILABLE ·TO ANY. OTHER PE.RSON'. NO TITLE T9. AND
·; 0WNERSHIJ?. o:E'. THE SOfTWARE rs' ,·~rn·RtBY. TRANSFER·ED.. ..
. '.

THE INFORMATION

IN "rHIS DOCUME.NT

:rs

SUBJECT.· 'To CHANGE WITHOUT
BY DIGITAL

'NO'l'ICE AND SHOULD. NOT.BE CoNSTR,U'E'D,AS A 'COMMITMENT
EQUIPMENT ..CORPORATION ..
i

DIGJTAL ASSUMES NO R:ESPONSIBILITiY. lFOR THE .USE OR RELIABILITY OF
; . ITS $OF1!WARE ON EQUIPMENT. THAT IS :NOT SUPPLIED. BY DIGITAL •

• ENABL

This module supports the "new" transfer vector format generated by
the taskbuilder for entering super. mode libraries.
This format
optimized for speed and size and supports user data space tasks.
The CSM dispatcher routine and the standard completion routines,
$CMPAL and $CMPCS are included in this module due to the close
interaction between them.

**-CSM Dispatcher-Dispatch CSM ent~y
This module must be linked at virtual zero in the supervisor mode
library.
It is entered via a four word transfer vector of the form:
MOV

CSM

#completion-routine, .... (SP)
ifroutine
·
·

Note: Immediate mode emulation of the CSM instruction is required
in the executive.

The CSM instruction transfers control to the·address contained in
superv;i.sor mode virtual 10. · At. this point the stack is the following:
{SP)
2 (SP)
4{SP)
6{SP)

10 (SP)

routine address .
PC ·(past end of t'ran:sfer vector)
PS with condition; codes cleared
Completion-rout~file :atidress
Return address · · · · 11

(continued on next page)

8-12

'Example 8-3

<;:ompletiori Roµ~lne,, '$CMPCS, ;from SYSLtB.OLD'

{Corit •. )

A routine address of O,is special cased to support return to
;· supervisor mode from a user mode debugging aid (ODT}. In this case
'i 'sta·ck is the foll.owing:
'(SP)

zero
PC from CSM to. be di.scarded
PS from CSMto he .discarded
Super mode·Pc ·supplied by debugger
Super ~ode· PS 'supplied by debugger

2 (SP)
4 (SP)
6(SP)

10 (SP)

.,~,To· allow p()~'it:ior:Hng at V·irt'ua!' zero,' this·' code must be in .the blank.
(, ·l?S'ECT whi~h i's :fii:st in the TKBs PSECT orde:ting. ' ....
• ·PSECT
.'ENAJ3L, .LSB

/.rkbug~~·r irett.lbn tQ' supe~· .mqd'e entry.•' Must S:tarb: ~~:·.·vir;tual zero
>;".

••

;

~-·

()ff' . pS.' .and PC ·from ,'CSM.

(S.P;) +,(SP).+

'•,,
.
. '
; :Tl'l.is en:try poJnt 'performs the. neqessary stack m<lnagement' to allow·
· , :';:an RTf 'fr.om .:s:uper mode 'to elth:er supe:t; mode·
'mode.,
'The, :is as req.l.lired .
an RTi: ·
'

or· us.er

for

·".(SP},
2'(SP).

Returning to:usei;- mode?

2,(SP)
.70$,

$SRT! : : . TST

,BR

'• ·~.· ,CSM

' Super . mo.de. ·PC ·
Supe,r. mode Ps .. ·,
; Join common code

tra'.nsfer ~ddtess:, thi's' word must .·be' at virtual Yo in super m6de
· ·CSM dfspat~her· entry

. ' c'sMSVR: MOV'
:·.JMP:
~

,; , Set cq.rripletioh ro,qt'ioe addres.s for. RETURN,.
' ; Trans.fer-' to<supe+ mo,d:e · l,il:?rary' r·out;ine

6. (SP) .. ; i(SP)
@(SP)+,:
.

, ,
~··
./~
.> . :. ~· ·~." ~,r :· ·., ,; ' ,, '· ~- ,, .', ~ o;, .· ,:', .. , ~ .,·; '} . . ., ' .'
;~·
:; ~)*:-:$CM~~L-7Corpp1e~i«>p.:. r9'uti?~· 541:f.ich' ;·s~ts; .-·up. NZ.'\l'C ·~n F~·e . ps

;: ,, «

;,, ,;

••

'·

·'

•

;

' .> ;'·

I•

;·

• '

,,,

.·

)

,)"

, ;/~o.Py".a;tl c'ondit.i·9ri .cfJd~~··t?·~ta¢,ked ~s'. · current stac~:

,_, r
·•, '

,(Sl?)
2 (SP)
.4 (SP)

'$CMPAL: :BPL

BNE
BVC
BIS·

BR
10$:

BIS
BR

PS .. with· co"n¢iti6tt ,.:codes· .cl. eared . ·
CornpletLoi).. ·routine address (to be discarded),
· Returh address" .

40$
20$
10$ '

;

#16, (SP)

;· Set NZV

$CMPCS
H4, (SP)
$CM PCS

Set NZ

(continuea on next page)

8-13

: SUPERVISOR-MODE LIBRARIES (RSX-UM-PLUS ONLY)

. Example 8-3 ( c'ont.) . Completion Routine, $CMPC$,· from SYSLIB. OLD
BVC

30$

BIS

t12, (SP)
$CMPCS·
J,10, (SP)
$,CM.PC$

BN.E

6.0$

)

· BVC'/

SO$

;
; Set

~0$:

BR
B:IS.

30$:
:4Q$:

BlS
BR

BIS

50$.:

·BR'

60'$.:,

»/:,

'BVC ·

·,srs·;

#'6, (SP),
$CMPC$ ..
. t4·,:(S,PY
$CM PCS
.$CMPcs'.··
'~ 2, !'$]?):

Se.t NV
.i,,,

Set N

,.«,.

.; Set Z.
;
·'J

Se't V

'**·..;$'CMPC$~CompJehon :roui;:ine.· which set;s .up only c in the PS
, .. C<?PY only .carcry· to, .stacked 'PS..
(SP):
2.(SP)
4 (SP')

$CMPCS: :ADC
MOV
MOV
70$:

80$:

BPL

P,S with coridti<ih ·codes cleared
Completion routine address (to be discarded)
Return address

(SP)
4(SP) ,2(SP)

(SP)+,2(SP)
80$'

MOV

#6,-(SP)

ADD
MTPI

SP,(SP)

RTT

.DSABL

Current. 'stac'k:.

Set up carry
. ; Setup return address for RTT
And PS. Returning to super mode?
If PL yes
Number of bytes for (SP) , PS, and PC
Compute clean stack value
Set up previous stack pointer
Retµrn to previous mode and caller

LSB

.END

Example 8-4
.TITLE
• !DENT
.MCALL
WRITE:
QIOW$
READIN: QIOW$

!ARRAY:
LEN:
!ART:

INDEX:
OUT:
ARGBLK:
'•EDBUF:

Code for TSUP.MAC

TSUP
/01/

QIOW$,DIR$,QIOW$S
10 .. WVB, 5.11 r,, ,<QUT t1r4;0>
IO.RVB, 5, 1,,, 1 <OUT,;$>'

.BLKW

12 ~

.BLKW
.BLKW·.
.WORD

1
1
0

~BLKW

100.

.BLKW

(continued on next page)

8-14

, ,SQ'P~R~'.I·~Ofl~MODE/ ~li;IMRI);:s' ,,(RS~":",l,iM~'PLP$::',.QN:~.'fii<.''
//."'/''J ,/ ,/.,,·, /' },/; <<',:','}///;'; ' '. .: / ' .<. ~,"'' ,: : '; :;',' ,:"'

:·' i,:~~~~{il')i-::~: fcqit':l·' co~e ~f<>~?TslJ~ ·#~( .·

'/·i·2·$~f{~~·(.iri) ~/. ' '' ; ' '' ,:, '• '

FMT2,:,·, / .. ASCIZ ·/;%;N%2SNUMB.ER ·TO"<SEARCH. .~OR?/ ,
..
FM1.3: :··,.:· .... AS(:~'~ ''/%N%2$%D'WAS, FOUND TN', ARRAYC%D)/, ,
"f~'r4':' : ' .• 1,\SCTZ . ·/%'N%2'S%D;'WAS· NOT,' IN,'' ARRAY/ : ' '
:'F~tu5~ .. :!.•K·scu· )':%.2S~RRA:Y(%.PJ9%b/
.
i.:
. ,
'
. ,·
,
. '
f_,:'>.j ~~ ,<

. .,

~·.

·~.-

;· ;,

8-15

·~

••

, )

,;;

/:· ·. . ·(coritfn~.~a".·a,n:·,·ne.~t:.·,?ageJ.

" 'CALL,«

. ':READ

CA'LL
":

~:: . ~

HOV' ' ; IA:RGBLK I RS
·MOV ··• • ,'f41.(RS)"t· ..

'· .. Mdv' > '

.4t<tARit' ;JR5.),+.'/ "

\''MOV

. ···:1.:t.t,ARRAY;{RS,)f'.'

: ,MOV

tiov· ·

' :#LEN', '(·RS'f+ ,
.· ::t 1t4o~x1 (R!;')·

OUTt?UT 'MESSAGE,
, . READ RE'S•PONSE
i :.,
; SET NUMBER· OF ARGUME.NTS .'
,,;, SET:· ADl)RESS ·OF., NUMBER LOOKI'NG .FOR
• SET· r\DDRESS 0'F ·'ARRAY . • ·
. ., .SE'T ·At>'DRESS. OF :'r_;g~· ·OF.·)iRRAY · '
; ' AbDRESS,01? 'RESULT; , ..
,

!Mov· . . ;dARGBLK,RS/
C,ALL>: ,,\'SEARCH

. ., ... · ;' 'SEARCH :·FOR N.UMJ:3'ER · l,tF

'. ·~qP;t.isi·:'.for,'SEARCH :··~·~bro·~·ti,~e.

t;t·wAs: .Nu~ER ·FQU.ND?

NDEX'.'

., o~ ..... ···,

1
'; '

'A':··~IART·, EDBUF, ..

. ""::·INDEX.1 EDBUF+2: ·
"·:.:.;'fFMT3, Rl· '

tF. L,T NO

, ; , G.ET/NUMBER :LOOK~NG
GET . ·ARRAY. NUMBER·
.(?ET FORMAT ADDRESS'

·i?.i:PRINT .
'..~·:1~JOO$

DONE
GET FORMAT APDRESS

GET NUMBiER
EXIT WIT~ STATUS'
I

'PJtlN.~ :(
.
1

•;

CALL

···,i;·:lih1ov·

'""''t<''MOV ,

, 1!j,~:·:::.{. .·~.·.M··A.Lv•L
. .. 0
,

I•

$SAVAL

SAVE ALL; REG:ISTERS

·:·.:;;1~00T, Ro: ' :·
'');::'.';tEpBUF,R'.2

AbbRtEss. bF ouTPuT· BLOCK
ST;AR~ ADPJRES~ OF ARGpMENT BLOCK

.1
'''{$EPMSG ,
FORMAT•
>'.':,1'.'RL,WRIT~+9:.10P~+l2 ;.· iPU'f1 :LE~GTH; OF OUTPUT
"
•.
,•
,
.
; ; BLOCK 1IWI'O 1PiARAMETERi BLOCK

1
rWi~'.·+~.
;IR$.' .. '.,;\',WRI'-'E ,
,, , ''. RETURN :: '

MjE~sA'.GE

;
I

W~1lTE' ibutt!Ptw!
BLOCK
I
i
I

:·

•. '

•

{;;$SAVA(.; 1; i
·~
S;A;V;E ALLi jREQ;ISTERS
:;(\fREAP:1J.t:'; ~;E]At)!i REQUES'.T
I
, #OUT, RQ. . GE'r' KEYBOARD IN~~
, $CPTB
. ; CONVERT iKEYOOARD INPUT TO BINARY
'.:Rl, IAR~
~T';. ll'I~~: ;t~O' BUfFER
,: ~@·'.: ~ ,tl
I

•

,,;,

·;

·4 cl

START

.;g1:.~

8-16

i .,...

Example'»a'-'5., Memory All:ocation Map
i'

(

;

.,,

.',

}11emory allocation map, TKB M40.1()
.
29'.""'DEC.,..8:2
·15:·0:1 ·

'EarJ::'ttlon name; ·: . . GEN
IdentiUcation ·; · 01

::ra·sk. · fri;c . .

·· t3oi·, s·s:1 · .

.· .....

, :·sta'ck: ·:';'J:1mits: .<>0027,4 · 0·01z'73'.·ou+n<10 .·9os12~,i' ·
· · PR,G · xfr ·,ad9ress: · 002130
·,· ., .: . )'ptal '§\dct~es·s ~iJ:l4. o~s: 2~:, ........· <.:
·.·.·/·.:'7 • .ta;sl{ . .:'.'.ima<.ie.: ',si.z~ . . · : .. ,13/:t~/.word's.• ·•· ·
2

·;:*>:·>~·:: .:·:/Ta.slt: ~adie'ss' ii ml ts:' ·oooob·o oosi33· . . . . . .
·"',,:·.·/ .. :·R~w,·&~sk.. bfk',11.mit:·s:.<oc>o.oo.~? 00·0·0·01':'.oonoo.6,

:·::\,. .::,><~:~tt···,:~~.e~,<~~~~~~,;·,,:T,?uP: :··. ,., . " "· .. , .

·.

.~·· J~'K••.:·'{.R,w,,':r,. r.C:i:. ·' RED>f~~N'> · ~,, '' ""0012·i:4
,Q(Jl~-/.4'
'.CMPAt : ( Rw, CLCC,R~L·,c.oN}
·. ,PU~.$0 ,: (~o.,i ,LCL,REL,:CON)
·: PUR$.{· .! (RO,:'Ij LC.L, REL 1'CON)
..,.$,$ R,ES):;,: WO; I'.r.~CJ:., RE.L:,fXlN}
. $ $SLVC :'(RO~ I; LC'I.if"REL i CON)

000000
.' 0036'30

003726
. '00'47.00,' 00021~ ,.001,38,... "
'ff051·12. 0·0'0020.' QClOl6.~., . ·

c.a110.s:atiori ·m~P:. , /I;KB....M4·o·,.J,o
.'29•Dr;C~8"2 .... l,5: Ql

:irotal· WOrk '~hEi r . e.fe"r,e'nces !
1

·:::~~.~.,~:~·l~{::,:·w~,~~:.~.~·:, .g·:·,,.:'.·:.: . . ·,,

i .... ·.·

.Size,,.M,· ,core ppol :· 698'8 ...."wbrds
"·Si:ze 'q;f .:'.work: "fi'le: '1024. :·wo.rds'.

TSUP prompts you to 'enter . number's at ·your terminal..
I t calls' a
"subroutine in 'SUPER to sort the numbers. Then i t displays the numbers
you entered as array entries and prompts you to request a number to
search for.
TSUP calls a subroutine in SUPERLIB to search for the
numbe'r. Finally, TSUP indicates at your terminal either that the
number was not found or the array location in which the number is
stored.
·

8-17

SUPERV,ISOR·,;MODE LIBRARIES (RSX-11M-PLOS ONLY)

, ,.

'~r.1,d.1· ''Building, 'SOPER~.· To buiid SUPER in UFO [301,55] on
'the. ro1·1owi ng 'task-b'ui ld command ·$eque,nce·:
·,- x'.

'>,

•

, •

••

•••

SY: I

use

' ,.: TKB>StJPE·R/-HD/GI/PI ,SOPER/MA,SUPER=
· .: : ,TKB>~B :. [ [1, 2ll SYSLIB/LB:.CMPAL ,SY:' [J30l, 55']] SUPER
T.KS),/ ... · .. ·. . . , '
En~er ·options·:··
~.:KB)STAC.K:;;:O··· · ·
. T~S>.J>J\R=GEN::Cr:.:2000.
TKB>CMPRT=$CMPCS
.' 'TKB>GBl:tX~CL=$SAVAL
.' ;' .T;~B>//' · ; ·..
, .

; .

' .

.;. '"'

.l~;UP~R:'.::i.:~'..'.buil.a';·~.i,'thqti.t a,· heaa·er or: stack.~

It is position independent
::and,';«:· has$ . .cn:~Ty . a·n~:. progr~m ~ecti9n, nam~d .• BLK. · The /LI switch
·accomf>lishes ....this:, eliminating program sectidn name conflicts between
.t..n~· 'library and· the referencing .ta$k.
>

••••

,·.

•

);J:ie·:"~ompl~tfon.' ro}ltine ·module of;SYSLIB, .CMPAL~ is specified first
in
.;.the:'/i,'nput' .'lin.e. · . .Tbe library will run in partition G,EN at O and is not
more t:han · lK •

.The GBLXCL option excludes. $SAVAL. from the 1-ibrary' s .STB file.
You
e:xclude · $SAVAL fr·om' the .STB file because the 'referencing task, TSUP,
:<;ilso calls $SAVAL.
l f ·TSUP »finds $SAVAL in the .STB file of SUPER, i t
'Will ·not link a separate copy· of $SAVAL into its task image from
SYSLIB. If TSUP cannot; link to a copy of $SAVAL that is mapped
through user APRs, the TSUP would call $SAVAL as a subroutine residing
within the supervisor-mode library, but without
the
necessary
mode-switching vector and completion routine support. This option
forces TKB to link $SAVAL from SYSLIB into the task image for TSUP.
The memory allocation map in Example 8-2 shows the following:
•

SUPER begins at virtual O.

•

The completion routine, $CMPAL, is
from SYSLIB at virtual O.

•

The entry point $CMPAL is located at virtual 22, SEARCH is
located at 35, and sort is located at 274.
All of these entry
points are relocatable.

linked

into

the

library

8. 7. 3·• 2 Building 'TSo·p - Use the following task-build command sequence
to build a ta~k,· TSUP, that links to SUPER:
TKB>T$(JP, TSlJP::.TSUP
. T.KB>/
. Ent'er Opti.~ms·:
· TKB>R.E$SUP~SUPER/SV: 0
,TJ<·B>// .
::This command sequence tells TKB to include in the logical address
space "'of TSUP a. user-owned, supervisor-mode library named SUPER. TKB
fncludes a 4-word ·, mode-switching yector within the task image for
· e.ach ~all t6 a· subrqµtine within the library. The library is position
independent and i.s ·mapped with sµperviso:r I-space APRO.
This is a
:requirement .. for .. CSM librar.ies . because .the CSM expects to find the
:ent:rY.J:>c:>int:of' the completion· r·ou.t1ne .at location 10.

8-18

;

,.,"

The ~emory allocatio.n map .for TSUP ..<Ex~iUt>le.«·B:'sj .::s~Q~.~:
•

$CMPAL is linked from the :.STB f fle of. the·. lih·ra·.~.y .~·~:ci:.: ·J;e~.i. risj·;
at location o. ·

The mode-switchJ.ng vectors .begi..n···at· 005.f36 and. are" 1'6 •.., .:byt~s.•,,
That means that·· TSUP calls s.ubrouti11es 'Wi.t'hi:ri th·e.;'lip.~:ary· 2/
times (4 words p~r v~ctor}..
· : ·»
· · · : · · · ' ' ""

•

The initiatfon· rou~.ine ... $StJPL ]s''.Idcated· <:(t

~ ·~

•70,:q··-:;'\.
The sEARdH :·a:nd· 'so~Ii1t·S:uo~<iu·t:i·ne·s.:.th~t.·:w~.r.~:·.·i$l·d~i:ed:··.· . :i·i://'·!li<r;·~uar·
,,

•

' • }

·~

<·

;

o·

;;

32, ; re?pectiv.e{y~
i.n: ',the.. .vfrtual: . add:r.e·s.s.:jsp<:iqe ·0.if··,
been · :·r~locatea ,··to':·." th'e..... ·mo.ae·~s~viA;cl1.1n9. ·. "A1 ect'Orsi
residing. at 5I3'6·:: a:nd· '5i~·6· .respec;k:fvely· ..::in·' 'TSUP'.; .:· . :.: ./.: .::. ·'. . :/.:· ::·;/ ;' :·:: .

112

and

SUPER .. h9lve

' :.,: . ,· :;: . · . ,·... ' .... ·. •· '/ . "·.. <·>· . :· . .:t/:<.:·'..: , ·:.'·.: :',/.j'::/,t~,,'·";'...,. ''//.:·}./:;J~i·>·,.:·,,;/.:·> J ;./

•

The· SA;VAL" .niod~·~e .from:·s.~t.SL·IB.·coqt"a·r·ri.in9 .9SAV:At;.·li,a;~'/i;:lE;!ert/~i,~.
·into'. ·the··· t~.s.k ,· .Jir1~9.~'.:· . inst£3fl·~.:' ,.-0,f/: ..i:ri¢l·\jdfn9·:·$;~»A,V~l/j~:r=Ari:t"F~.:!f~:i.

library~s ;sTa we.:..

'···

" ·· ·

,, : .i'/i ~j'.%:·M;:M~)

ouiloi~~ .s0,P~1~·a 0a ·'rs'uJ?,,;~s i~d.{b~'~:~d' /:::a(
'.:/>.:/

·a.7.3.3 Running TSUP - After
the task-build ' command seque{ric~' .. d'fscussed.'; pt.evl'o.ils.lty;.:'.yo.fr"•;:rris.ta1it.:
SUPER and run TSUP •. · TSUP i;:fr·~mpts:· yo~):fo·t·.·~.:·:~rlrnhei:~··,;·'.''\' ';:,::·'.J:·'.'..
'"+ .f

ARRAY (x)
x

The position ·in which t<i ?te>r:~; 'the.·.n:umber, fo:'.:'th~: . .'~rra'y:~/,··· ...·:&·C>1.f/
enter a ·.number. . TSUP :sj::o.res . thEf numb.e·r. 'iJl J:_l)~
aJ;t~·;·
prompts you again ,.fp.r .: a.·: ,,n'umb~.r··~': '.':· t,I'.:Qis.: . ··.<;9P.ti~~f~~,s:;· :· :~.I}'~H/.i)":/p}~:;
either have entered a ·o, an .illegal:number, or.·lO . .n.umb,ers •.
Then TSUP ca 11 s ,.the .·~ORT. rqudp~. i.r);. ~.UI;'!~·~ ~~: " > ....... ,,. .
';

;;ariay.

You enter a number. TS.UP ca Hi» t:'hl~ ·~EARCH.. ··ro:tltirt~· ·'·,...irL .·::ia~i·~/·' ·'.'Th~~·~:
TSUP outputs ~ message· indi.cat.ing ~hethe.r ·tp.~ .;np.mbe. ~ :was.· ,.i.n; ·t~e· ·.a:I>~ · "

,... :' . . ; . : ; , .. - , :; .:.::·' ; .,: ' . <·.:~~/··:.~
' .

: .

.. .

The CSM. Library: Dispatching· J.>.toce·s·s:.

8. 7 •. 4

When

you buil4 the

l/. ..:. ;· . . ,·

~·:., :.·~ /;c:'. '"
. .. . .· :'/ . . ('/;///
.''/ . . 1 • ,e,
:/;,.;:;; /
•.'

refer~ncf~/~~~/ if ~~i~~~:f;y :~":sX--'~i~~~~/i~{

RESSUP
or· . SUP~IB·.·; .·opti.on,: . ·; . tlien·.;2,..,'/PJ<B,·:.,·:in.c.ltid~S· .:".a;: . .:. :4.,.~o~d'£
context-switching vecto.r 'fo;r:: each.' call'"'~o.'' a· ·'sµliroubirie.:':Lfr·' the .:fi'.J?l:'a~·~:.r:
This has been very generally .di.scus.sed in .Section· $'.;:2 •. : Tfri.s s~ctiori·
di'scusses the CSM library· 'vect:ot· tn deta·i t
· : · .::; ~ , ·/·
' :>',·:>:
the .

CSM mode switching occurs

as ·follows:

The vector is entered, with the· return addre.ss. on ·top ·.of
stack (TOS) •
·

'th.e

The vector pushes
stack.

the

A CSM instruction is executed with the supervisor-mode entry
point as the inunediate addressing mode parameter. The CSM
instruction:
a.

the

completion

routine ''addr'ess

Evaluates the source parameter and stores the entry point
address in a temporary register

8-19

. SOPERV!SOR-MODE LlBRARI.~S (RSX'°'.'llM=PLUS ONLY)

user st:ack pointe·r

b •. Copies the
pointer
·
c..

. ,to . the

supervisor

stack.

Pl·aces the current PS and PC on . t)1e
. c.+earing the condition codes in .the PS

su,pervts·ot

stack

•

Pushe?. the ,en:try poin.t· ad.dr.es·s .on .the. ~upervisp,r stack/., · ·

,d.

e. ·Places· 't:tie ..co'Ut~nts of loc'ation 10 in ·supervfsor
· in:to the l'C ·
,

l-·space.

, The. stack ·looks Tike . th,i s when, the processcn; ·~eg,i ns to· execute at
'c.o~tents. ·of virtual ·10 in s,\lpervisor mod~.:
, u~·er

Sp:_...,.;.'.'."")

. s.uper sp '"".'.--->

the

·•return addreS·S,
completion·. i::ou.tine address.'
. 'PS.
PC
entry point address ·

The most important' as,pect 'of how ·the. CSM ,library· mode-'switching vector··
works in that the processor begins executing at the contents of
vir.tual 10 in supervisor mode. This is why the completion ro.utine.
rnust be located at virtual O, so that virtual location 10 is within
the completion routine.

8.8

CONVERTING SCAL LIBRARIES TO CSM LIBRARIES

You can easily convert your SCAL libraries to CSM
libraries.
Rebuilding a task on an RSX-llM-PLUS V2.0 system or later that linked
to a library on a Vl. O system requires that you rebuild the library
also.
Rebuild the library specifying the completion routine as the
first input module. If the library was not built to run at a starting
address of 0 in its partition, rebuild it so that it does begin at 0
to enable TKB to find the completion routine.

8.9

USING SUPERVISOR-MODE LIBRARIES AS RESIDENT LIBRARIES

Supervisor-mode libraries can double
as
conventional
resident
libraries.
For position-independent, supervisor-mode libraries, you
rebuild the referencing task usin9 the RESJ:,IB option instead · of . the
RESSUP option.
Indicate the first available'user-mode APR that you
want to map the library. For CSM libraries this will always chan9e,
because you cannot map a shared. ,region ·with APR O. You do not have .to
rebuild the library.
·
'
.For .absolute supervisor-mode ·librar.ies, rebuild the. referencing · task
using the RESLlB option instead of the RESSUP option. Rebuild the
library only if the beginning partition address in th.e PAR option i:s
incompatib.le with the address H:mi ts of your referencing task.
·

8.10

MULTIPLE SUPERVISOR'.""MODE LIBRARIES

reference mul tipl:e supervis'or-mode. CSM l~braries.
However.,' · all the CSM libraries must use the completion routine tbat
. begins at virtua.l zero in supervisot-;-mode instruction space.

A user task can

8-20

faf1~

}

:illRl'l'UG 'YO!)R

''';>

,awi ~oinms·· ~i>''eOM'eliE-r10N' ROU'lti!Eif ;

, r , . , , · :, · . . .· .· ; , . .· . , ; , . ' «: : , : :, ,· · '. · , · : : .•· : • :: :: :: : •.: .·: ,: · • .:· ,· t ·,; , :: : ;: :· '. : .:; · .~ ,· .~ : .: .: 1 ,; s.: .:
,, 'Yo:u. '.ban; wr 1 te. yq ur · .:cn4'n' :in~d.e~sWh:dbi . ng .: \tee to~.~.: ano:· c . P;ltet i bn /fau,·ti nes·:~·,
:7;i'~fs:,·:~~:y:: ,;}:).~: :n~c~.:s;s~~Y:;M:r.~.;~:t~?.~·e~::::·gpkf~,; ·f .l~f:;;~.o.G\i:µ~.~::l1<?~::ri::~:~+.. ·' · ;~##~1:;~ ;f
:' b:ui·la: t;n·enl ::tnto ·;·t·ne ·' tasl:f :~n~: use: .:ttne· :·<~sv: '"S\fli: t'.ch.' :'·on·:·: t:he ·: .: .·
su·~· '..·or"
:."fii:;·~.Lte.;..opt.ion· ;\fijen.' you .:b,µj.fd.; :the,: ·fe.fer.en:c!r;ig:' task~·:. ·.Lt;. :'y9µ:: :cre,q~:e: ·· · ·, .
~Pitn ;c~~ eti.'ari.' t~ut-i:.nesi·,~ wri¥e •·. ~~i c~pt•e~ailli ~otit.l'rili~i> 7i~~emSte

. .~~'.I:D .$~:~·F;~vrSQR~MQij!,fL#ip~tt~

.'.:: .:;' :..:: .;· h: .:'t'. :·. ; ·,:"', ...· ,, ~:., .:' , :: ::·

:z: . ~.~: · .:·::; .:.< :; .:'. :" ;·,:/ :: i E'...

;

. . ,

:. ;iJ .'i:5- ;:,:possible· ::·t:o:: .i1s:e >. QVer:l'aid': · .stipe.:rv·i:sar7mo~.e::: UJ;;>.rarie,,s·~.::
;r;~J3,t.~}Qt;i:9ns:.m~s:t::};>e ;rioted, . when: ,:bu:t:ld:ifQ9<'t@es~ ....libJ;fl:. r:·ieis·:;, .'.;;:~ ·

The c<>;mpletlon',·rou~ine, ~?'r t~'~ .....~ib"~:a,r:(m~s .~"be :.:i·n t:h;e, roo~.

.: : ;z ·;: '"

:·dn.ly one :le~~l .' of·... ·ov~r,i~y: ,'i,s. ~·r,i~~~a:~;:; Th{~: .is
Figure 8-:4 . ,
·' ·
•~.

ili~~t:;a{~·~ .: fo: .
· · .' · :

link... to·
Al though· the· Fast
Task : • Builae·r:
'(FTBr
can:
supervisor:,;..mode . libraries,
it ·"cannot link . to oveJ;faid
supervisor-mo.de libraries .• ·

8-21

ROOT·
ALLOWED

:ROOT
·AL~OWEIJ.

)

·F'igU.te · 8-4

. . . : { ~ -~

ov·e~lay Conf ig.uratiori Ali'Q\Ved

S,uperviso'r-fiod~ ·Librades. · :,.. ,

8-22

ZK:-1J02~82

CHAPTER 9 .
. MO~TI u·S.ER .TA,S.KS.
?' /': ~}" . ~~:..,.

,,>'.,/{ -~·h.•: ~,,.·,·-.: ..

.:· .

••• •

•

••

: :'.'

·;·~t.··1····.1·NTl~:ODocip1mi
:;:~--':/J-~:;/~.~~<·':<-i..,,, ,;,: ,_' u'., , . ,:

~,//:~=·

,;,.

,,'/1\:···i,nu'I·~{µ·s·ei >tasi<:' .1s,..,.a·::t~sk.that·· share's tne· .pure. (re;:ld~only)

portion of

;·).~t'?::· .c9'd~/.~·~:t1L··two or· ~oi.e ,oco.pfes. ·of t.he impure Jread/wri te) ·portion of,
·~.:i,£.s~·):9d:e·.·." Wl)'f.fri .. the .syE?tem,. ,receives.. an · iriit i·al
run . :r::eqqest : fo:i; · a
~1n.q:~·:t;.fµs,e'.i··.,, ·.·t'asK,·'· .,a: .q~py .·~)'f :.both. the rea,d.:...only and. read/write portions

·::s<?~.··',,.;~he;·,;f:.a$,·J<·,··a.r,~.· re,ad· .i.n·t;:o physh;:al . memory.
As Tong ..as ·the task is
·.;U,nq:i:,ng·,/ ,.all ·',subseque11t .. run, . request? for it result in 'the system
.~. .g·qpl1.¢at~.·1)~9.P.rily"tbe
read/write::'portion 'of ·.th'e· 'task in·. physic'al
,;::me,mo,ry:·~. .T~us.;, :rhultiuser. ta.~ks are memory efficient.

;::#~~~·;§~ii· bu·iid ·~r'"t:;3·sk,: you' desigrtat'e it' as' m~l ti us.er by . applying

the
'This· switch directs the Task
,'. B,µi·~·gE7i"".to..,'create two regions
the. task.
One region (region 0)
.·:c,otJita~ns'the .read-write portion ·.of the task;
the other region (region
:"J)·:'P'o:(li;.q·i n,s · t;be ·read-:-only .P~n.tion. o,f..:the,. task ...
,;:fttQ·.:·.·.~w:i.1;cl,},

<•

~·

•

.t:Q .. the .task .. image:. f.i.1e.

for

·'

'• •

•

.'.,](s ,,:!fli:th' . all·q~lrer,·t'~sks, . T.~B uses .a ,program section's access

code to
It divides
,'.,a4d'rE,?s;:> .. ·SPa.c.e .·±nto.·read/write and. read-only sections.
Unlike in a
'.'..'~,fogJ.e :'t·us·er ... t'ask,, ho~~wer,
the read-only portiqn of the task is.
~.q,zi,rd~(llr~ .· ,p.x;ote~t:ed• .· 'In . addition, ·. TKB
separates the
read/write
:· ,po,rt.i<>u's . ·.°-.f". ."·a .. ·mult,i·user·, tas·k. from .the ·read-only. port.ions. and places
~; . t.:n.:e,mt·±µ:>,',S,e.P~t;:a:i::e ."re,gi,ons at:·. ·opposi te· ~nds ·of the task's. address space.
·,/~:t... :' aH.oca.~:eS. ·. the . " lo~-a4dress · AP.Rs to, the read/write portion (which
'/i'~.d.tud'e.s ·.the: t:as'kl·g' heade.r '·and stack' arern) and the
highest. available
·:J~. ~~~v·,. to ., ,··the · · read ... only .. portion.
Figure 9~1 illustrates this
:<d~~'te'rniine·.

'1ts' placement ·within a ·multiuser task's image·.

.'·:'~fl}1:~c~ 9P1: •. . .

.
·~~~.pac:e

';f~:r),. .. "p,nd
niultfuser 'tasks, ·in. 'addi Hon· to · having ·the
A:n:\lt ti.us,et · ta·sk .at v.ided into regions of· rea'a...;only PSECTs and read/wd te
'J;>'SEQ1's,. ·these. reg~ons themselves are divided into I-space areas and
.:.o...:·space areas.
. All of ,.tfie.. following combinations must be present in
an . I- and D-space mul t:iuser task:

•· .PSECT psectnamew, RO, I, . .
•,

• .PSECT psectnamex, RW, I,
• .PSECT psectnamey, RO, D,

• .PSECT psectnamez, RW, D,
If neither the read-only nor the read/write portion of the task
contains memory-resident overlays, TKB allocates two window blocks in
the header of the task. When the task is installed, the INSTALL
processor will initialize these window blocks as follows:
•

Window block 0 describes the range of virtual addresses
(the
window)
for the read/write portion of the task. This region
always contains the task's header.
9-1

MULTIUSER TASKS
•

Window block 1 describes the range of
the read-only portion.

Figure 9-2 be1ow
multiuser task.

showS,

the

virtual

window-to~reg ion .

addresses

.ielafior(shfp 'of

for
,a

... ><<:~U"N.usEo>:

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

APR 7 -

READ-ONLY
PROGRAM
SECTIONS

APR6-

APR 5 -

APR4-

APR3-

APR 2 -

READ/WRITE
PROGRAM
SECTIONS

APR 1 -

APRO-

HEADER & STACK
ZK-441-81

Figure 9-1

9.1.1

Allocation of Program Sections in a Multiuser Task

Overlaid Multiuser Task

If a multiuser task is an overlaid task (described in Chapter 3),
read-only portion of the task can, be made up of the following:

9 .L2

•

The read-only program sections of the root S,egment

•

Branches of an overlay structure if
memory resident and ·read-on 1 y

•

, A, co..;. tree

the

comptete

structure if the entire co-tree· is
and read-only.

branch

memory

the

resident

Disk Image of a Multiuser Task

Th"e disk image of a :multiuser task is somewhat diffe:i;ent fr.om that· of
a ,gingle-user task.
Theread-only portion of the, task is,placed at
the end of the disk image. The r,elative block number ·of the' read-.only
portion and the number of blocks it occupies appears in. the label
block. The ~ead-only poition of the image, is de~c~ibed in the first
library desciiptor of ,the, LIB'RARY REQU,EST section
the label block.
(Refer to, Append,ix B for more ·information - on the task image data
structures.)

9-2

HIGHEST VIRTUAL
ADDRESS

REGION 1

WINDOW BLOCK

READ/WRITE
REGION 0

LOWEST VIRTUAL
ADDRESS

ZK-442-81

,The APR and window Mock ass i~~~ent
an I'-, , and, ,D"7space , mu1,ti»u~e:r
,task di'~fers' fr,qm, that' in .a. conventional' mui ti,1.1se~ ·task •. '; ·"

in"

D-space Ai;>Rs map· the, read-writ·e.' and; 'read_:.only'. ,•PSECTs that have . the
data attribute.
Shnilarly, I-space APRs ·map the. read-write and
read-only PSECTs that have the instruction attribute.
Figure 9-3
show.s the APR , mapping for both· kinds of PSECTs in an I- and D-space
multiuser task.
·
TKB need~ f~ur window blocks to map an I- and D-space multluser task.
Window blocks 0 and 1 map region O, which contains the read-write
instruction and data PSECTs.. Window blocks 2 and 3 map region 1,
which contains the read-only instruction and data PSECTs. Figure 9-4
illustrates the mapping and assignment of these window blocks for an
I- and D-space multiuser task.

9-3

MULTIUSER TASKS

DATA APRS

INSTRUCTION APRS

UNUSED

READ-ONLY DATA
PROGRAM SECTIONS
DAPR7

IAPR7

READ-ONLY
INSTRUCTION
PROGRAM SECTIONS

DAPR6

IAPR6

IAPRS

DAPAS ---1

UNUSED

IAPR4 --i

DAPR4 ~

UNUSED

DAPR3 ---1

DAPR2

IAPR3 --I

IAPR2

IAPR1

READ-WRITE DATA
PROGRAM SECTIONS
DAPR1

DA PRO

HEADER + STACK

IAPRO

READ-WRITE
INSTRUCTION
PROGRAM SECTIONS

UNUSED HEADER
ZK-1103-82

Figure 9-3

Example Allocation of Program Sections in an I-, and
and D-Space Multiuser Task

9-4

PHYSICAL
MEMORY

TASK
WINDOW BLOCKS

READ-ONLY D

WINDOW BLOCK 3

READ-ONLY I

}EGION 1

WINDOW BLOCK 2

WINDOW BLOCK 1
WINDOW BLOCK 0

----R_E_A_D_-_W_R-IT_E_D_----1} REGION O
READ-WRITE I
r

ZK-1104-82

~~~D~~~

The;~e:x.:t· .·/l~ +tch:;i~,:· $ec·t,I:·O;~ •aill"d.+;ijhe .·:.f1~9·.ut'~S.· a~·OA];!~,t.~::~].'.:{;~ "~·t'..::,l(l:i:llJS':1:~~:~e;
:·t~::·' . X11eve:lapm~n't t.,~:£: 1 • ..
·~arl·t'i'u:s~:r~·::"·;t~is:kt~.> ·.qitji:S,i :~:x~~: :.:was~·µrea;1:~ by· .
l~,o.n¢at~i;l'atJ'rig ,'i.~t;P;: a>«stnig1:.e,' 1~;~i1e•":t:h¢' /~~:s)d~%n:tf·'.1J;q+;a·FY : ,•f:ille'·:; :;-({rj::r'a.~t-J~C.).
: a ri<r .:· ·::tli~: ··t;a.$~' .~tJ1a~ ,·lJ .ilks\. t.'c> . :i~·/fiM,At~N: •.;MA\Ci,«.;;f,,r.9iri . ~Xi3.It\p];~: ~s;-:3. ~: /I.~:!\:~~i 3noti
:it:ltend:ea· ·t:o.:r.e:pr'es¢'~'f/ a,.J:yptcal.:mu;1t:I.us;er . ".1=;as:k; ;appLi:cfJ:tio;n .• :•.i .: .11-pjwev.er ~·:
it· does · i llus'traf.e· t,.he· Ta:sk:. ·sui:ld,er 's al;:to•qa:tiq.n ··pf prdgr~m: secti'ons
in. a m.ultiuser t~sk an;a that. is .'ft$ prima'ry ya1u¢. , . ·The· concatiehqt~d.
sour:ce, file., ... named . ROTASK.MAC/ 'for, :thi$ e•xample is shown in Exa1clple

:a.. :

~-L.

9-5

'·l

''::'

, •

, ,, /'"

• '

• ,,

~ '!->'

., .~: ,'

J ,'

...-

,< ·N ;:,· ,;;

<·">

,;P~r't ;i:::"'So\it~e,>L,i~ting ·for· RO.'I'ASK:MAC
,;:,;-

-~»

'·'

,.,,

/" '

-..;;

,·

,.,;

.... ·,.>ti~s·.{..;'.,:-(:SP:j'} . '

:MOV'

'.'./tORl):~{~~~i'

;~:·jfoP2/~..{SP.j ,·.

·.cAt~

,'./

. · ·l\Abr{/' ·

· CALL

, J;>RIN'.l'

"' '' M0\1'

'•SP,'RS

, CALL
CALL
MOU
CALL·
CALL
.MOU
CALL
CALL

.' ·;/, To".cdN,'J;'AIN 'RESULT '
,;/ ';,· ,'QRER'~.ND' ·~I
I.;' OPE'RA!iD '1,, .· ,' ''' '•
. · ·; . ·,PA:SS'I.'~G ·3 ARGOMEN11!$
"''
BLOCK:
t.·. ·, ADDRE'SS.0F
. ,. . . .'. . .
,. ; . ' ·ARGUMENT:
. . '~ .:. .
:
~
t . ; ADD · TWO OPERANDS .. :'
>'
i.· PRI.NT' RESOL;f'S·,
, . ,
',; ADDRESS· OF ARGUMENT . BfaOCK
';. SUBTR·AC,T '8'Ul3ROQTTNE,· ',·'
; , PRINT 'RESULTS ·
ADDRESS OF ARGUMENT BLOCK
MULTIPLY SUBROUTINE·
PR1NT RESULTS
.
ADDRESS OF ARGUMENT BLOCK
DIUIDE SUBROUTINE
PRINT RESULTS
'

:M:OV' . . ·.. · .; :i3 '·· i~"""·{SP)
·.g'p 'RS 1 ~·

.:M0\1'.

r- ,

.~>

.M<)U

··M'cht

.;;

;

·"' •

;

,·

, I

StJBB ,
PRINT
SP,RS
MULL
PRINT
SP,RS
DIW
PRINT

•

• '

•

°1' i

EXIT$S

;** PRINT - PRINT RESULT OF OPERA'l'ION.
;
PRINT:

MOU
tOUT,RO
ADDRESS OF SCRATCH AREA
MOU
#FORMAT, Rl
. ; FORMAT SPECIFICATION
MOV
#ANS,R2
ARGUMENT TO CONVERT
CALL
$EDMSG
; FORMAT MESSAGE
QIOW$S
#IO.WVB,#5,#l,,,,<tOUT,Rl,#40>
RETURN
; RETURN FROM SUBROUTINE
.i** FORTRAN 'CALLABLE SUBROUTINE TO ADD TWO INTEGERS
• PSECT 'AADD, RQ, I , GBL, REl'.- 1.CON .

AADO.: :

CALL
MOU·"
. MOV
\.ADD
MOV ,

RETURN'

:$SAVAL

@2(R5) ,·RO.··
@~(RS) , Rl." .

/RO;F.l .
.R·l,@.6 (RS')

SAVE

RO-RS

.~~ 'FIRST·•OPERAND
;
S¥CONP• OPERAND,
1
.; .. SUM TH.EM
·:;'$TORE.· RESUL'T
jESTOR~ ·Rf!Gl~TER~ A.ND ·RETURN
,~ ,::t:~~}:'.~ ,· ' . :-·,
.
'· :! '.';

l•·

.·. t:.'. ~.~.:. '.·
_.

~"-~

:,~

' 0

9-6

.fc()n"t'il'}u~d. ·.on next; page)
'

. ..., .

·'x· i<,

.~**···/FOl~TRAN'
.. C:ALLAB·tE
SOBROUTIN.:E· ·TO SUBTRACT 'I'WO ·
~;
<~
-~
),•~
~
' '. ' '.
,,:.$.OB&': . :. CALL
· .. $SAVAL
.. · ·... · ;·'· SAVE 'RO.iRS
.
MpV:..
. ,· @·2 (RS) ;RO
· · · ·) FIRST ·OPERAND:. • · ·
·.MOY·.
:.@·f(:~S'),Rl
;.. SECOND ·a.PER.AND·
·,.~OB· · · , . ~·~ r RO . \ ..· . .
· ; SUBTRACT SECOr~m·
Ro··~·@fr'(RSl
·; ·sToRE.·REsur.·T· :/· . · ... · .·
. REW.URN.'(, .' ... · <. . ·. ·. •
. ,· i" :·:RESTORE · ~E'G;J:.STE~: AND/RET'p'R~/
,./'

. . ··'

'.<;

·:

'·'

, .

::._

·'.'"

, .

. ;

...

<:.

..,< .. ·. : '/.J>q. ECT· .. su~B,.Rp,,1,GaL,REL,CQN
<

••

·· .Mo.v :/. ·

~~.Q~~·~.~:~·.:.~A~;iA.~~(~·· ·~UBR~U~IN~·. ·,~o ··:.fu; vrbE··· ··~~b_'. . t·~~EG~R·s/··~ .
,DJV,\T 1:RO,I.1 GBL.,.REL,CON..

:..;,.t>SECT.

. . ·.· .. .

.>,c/i'.ti . / ..;·'.$s·Av~t·' .:· · ·• . ·. · · \· ·;.:: .siv·E: ·. R.EG.S· ··.-t<o~;R:s
1

,, ·.M~V. :; :' .· ,' :@.2· 'R~·) .)R~·. ' :'
/:~OV/./,;>,.· . @4':'(:,R5.·) ··~·Rl/ .·.
' ',; ,' cr;R, .',,:" '':' R.2·;) /: .·. :'" . ;

,·i.·· ·$.I RST. b'J?.ERAND; .'• . ; ;, .' . : '
·.;/.$E~ONU .. OP.ERAND/·/ .:· ;·:/
' .;. LO\Af·ORD'ER; lo: &lTS·''
:; ·~oi\'!oE.· .,' ·
·.:·,·:/··.
... ·
;;·"strio····RE·.·R.·E···su·LT····:·· ... ·:,.: . . ·. / ··".:'> . ,..:.. ;> .. :.:·. .;·.: . .
•t. .: '• .'"""' . " . :·· ..· ., .
•. . ; . . ., .·· ' •.
; "
,, ':·/.;···~ES'f'C)RE•:.;EE.G'IS,!'N!-:RS,·'J\:Nf>',·;~E':ttt1~:$;'/:;·'·

··, ··j a!v··. ·, ~:'.ih~R2« ::

.· ·,-"' ,'uo··.,y. 7• ' • ," "· .. • ·R2·@'6iRs··),
'
,
''\ '
,.. ~/.·.: L///RE:i1U;RN,+."-.·: '/J..:,;:i/'// :'
' .;... ' ~?.! '

' .:·

:. ',,··.::·:.·~c:..:·';··'.:;·,;>//,·:'.i'':.·:·,;;',:< ../;:,,,.·:/ ,.·

i•

. .· •...: ,"./;•

·... ·....

·,

,, .:

•

'·,

'"»

~· .~ .'~

·'

~-,

.=~

.'. o''; ..

' ; :' "

. ;

.'· . ,......· ':/:" ".::':/'/'.// .

.f,1r'f./'EbET<'RAN./.CA.ll<Ll\BLE.:'·suB'ROU''rIN-E', .'l10 .MUIJT.If>.tY' ···T.Wo··.:1N~EGERS···

, ,., _., ~ "~ <. 0·-'."fyo) .'~'.=<, ,. ~',»' .,.

,:· ,:· ~' ."·<~

/··~' .·:

,' ~:,.;,

·<>

,':

. /::' ,·

,:'·

:~~~~i/.r-fUt;i,:~q~~:G~t:~~E~iS6N· · . . ...
·O"AtL·, .' _.'·.$~.AVl~.t,·· ··.. .

~·.·

·.· .. ·o9.vv:·.:.:.<-'.

;./SAVE:· .f{.o.:.R:·s ·.·.:><:' ·
';
£{sir:·: OPER~ND ·

·P.i

." ' .:@,2 (Rsf, RO
/@4:([{. ~·J.:~.Rl:

... ttJu~.
.. Rp.,Rl . · · .
: · · MOV . . , .R~.~.@6J~5)

.._ .;;.,~'ETUifN . :' ... "
. '!·E~o.·· . ·

'; ;','SECO·NO·.·OPERAND:
..·,, .:; . M.UL.T:tPf.iY' · .... : ·
··.

'·:.

. ; ·STORE. RESULT ' .... .
.
... ;'.RES.TORE·'.REGI,STERS:'rA~D

.: ·

·:,Qil~·~:. ,,~·u·...,~·a.~e,;·.:a:s~e~·f>~·~a.· . Ro:TisK:, ·.y.o·~ 6~.r): ..:bJ..r.ia ·

.:~<>mm.a.ri~ ·~s~'<:;tu.e,h·C'e·:·

~»,~~=,

.; :

~;,~ ,··~";:

·.·.,. .,: ,·,
~

· ,... :.:
, /

. .-

.·: .·:

=~-

,, .

: •.·..,"' .:»,>·~.·K··' B.;'">,'.R.•·'f)T'A···s"...~· ''f~'U>,:...R."'o.3r.:.···~·~··.K.. ·z.:~.:·T&l;.·1,.1;~.'SP.;·.·.:~.·R' <?)'r.:;A·.·S•K'. .
~ ~
~ - ;~..'..f:'fl.•',/'/ I>:··::. /,>'".'":·" "•'/·.·
~ r·.·.111.,",· :.t.,.. /,; ":'
. ....·1:· ·.: ,·.
/ .>,;.'.'T"KB')/;

_J
"

.;://

•

·,, .:,

.:·"'

o,pt::~ i;>'?:~

<·': '• ·:. ". .' ::) ; / ' "'

·OPAR!:f;·RDON!iY.:.··

··.",;

/' . <·; :·'.:\'
:.'~;·,'. '.,.,./~.·

.<\./*'
·. .•. :./.·. ...,· . · . ·,":.:·=.;.

"·:;.: :·/.:~/

..· .. ·;; ... ,'• i'

,;:/:'•:))J:i~;~:·:

;~i~~~p~~~~'.~~~4~'.~i~~~~. ~kl~~;\~~i{~ ;a···i,.m~i·~~µs(¥w .o~~}'./:c~~;~-;;
'

< '< '

;

. "

; ) '<

'< '

.:i.m.a~:e·.'.. ,"nffiln\edt;' :ROTAS:K...:TS~

.,:

..a"nd.· .',to·." ·ere.ate a·n ..• so·"."dt)l.umn, :·"(/,,;.~IJ ."map i"'fiJLe".c

"..n~'rilea."/}ia~J\.si·.~.MAR::."',.: He·~ause.·.·. .~/~si? .is :~t:tached £0. the' ··ma·p ·. i:·t1'e<'~ , irtJ3'.,:··.:~q~,$·' ·

:j9.~· o:u~.J?.µ.t._ ~<~<7~.: ~9 ~he:.:H.ne...P,.;in.ter. <

··

· . ·..

" . "·· :., · '. .. ,:· . · ~/:': ·

·',t'b'.~. ·R.OP'A:R.·optfon': . spe9{f.i~s·. ~lta:,t· the syst.em .is
load., the :read.:.ori,l~.:.
··po,r. t.ion:,·Pf·.'the'.· .. tas·k into a·· pa.r~·ition :na+ned RDONJJY.·. Specify.ing'a-:
\separate parH:t.i.:On' ·f0:t the· ta.sk' s ··rea(l_;only region is hot a sy·stem;
.. ·I;equ,i reme.n.t.
The system wiq load the read/write portion into..
partition GEN• The· system will not load either region undl · . it
.rec.eives a· run· request for ·.the .. task.

The map that results from this command sequence is shown in Example
9. -1, Part ··2.,. 'Note that TKB has added one field to the task attributes.
section of this map describing the disk block limits of the read...;.6nly
portion of tne task.
It has al so added a field to the root segment,
·portion of the map t.hat describes the memory limits of . the read-only·
portio'n of the task.
Finally, note that TKB has allocated space for all the program
sections with the read-only attribute, beginning with the highes~
available APR (in this case, APR 7).
9-7

MULTIUSER TASKS,

. Example · 9-.l, Part ·2
ROTASK.TSK;l

Task Builder Map. for ROTASK .. TSK

Memory allocatJon map · TKB M40.10
10-DEC~82
1'4:42 ..
,

PAGE 1

Partftion name : GEN
Identi~ication : dl
Task . UIC
[ 7, 62]
stack
. Limits·: 000274 001273 OOlp.oo oos12.
PRG.xfr· address: 001634
Task· attribU.tes: MU"
,
Tol:al .address windows:· 2.
. .
Task · image sfze
1088. ·word~{; !
Task·· a:aar'ess l·im;'ft,s: ..: . 000000, 'o.o'4ls;7:
·· , .
'R:.-w,dis;k bl:k l:imits:. oqoo•o2· dooo:o 16L.oooecfs oaoo.s:·•.
R-0 disk blk' limits: .'OQoooq 00000'7\ o.Q'Q•OOl OO•OOL,'

*** Root . segment: ·ROTASK.
R/W mem
R-0 mem

limits: 000000 004157 0:04il60 02160 •.·
limits: 160000 1603 77 oo0!400. 00256.
'Disk blk limits: 000002 00.0006 0·00%005 0000'5;.
Memory allocation synopsis:
Section

------BLK. : ( RW I LCL, REL ,CON)

AADD

:(RO,I,LCL,REL,CON)

DDIV

:(RO,I,LCL,REL,CON)

MMUL

:(RO,I,LCL,REL,CON)

SSUB

:(RO,I,LCL,REL,CON)

$$RESL:(RO,I,LCL,REL,CON)

Title
001274 ~02662
001274 :qoo530
160000 ()!00024
160000 000024
160024 0!00026
160024 dooo26
160052 ®0024
1600,52, Q000,24
160076 '<l'.00024
160076 000024
160122 000212

0.1458 •
00.344.
00020.
00020.
00022.
00022.
0-0020.
0,0020.
00020.
00020.
00138.

Id'ent

File

ROTASK 01

ROT ASK.. OB,J ;: 1

ROT ASK 01

ROTASK.OBJ;l

ROTASK 01

ROTASK. OBJ';'l

ROTA,SK 01

,ROTAS,K.QBJ1l

ROT ASK 01

ROTASK.OBJ;l

Global symbols:
AADD

160000-R

DIVV

160024-R

MULL

160052-R

*** Task builder statistics:
Total work file refer.ences: 2'1'45.
Work file reads: O.
Work file writes: O.
Size of core pool: 7086. words· ( 27.· PAGES)
Size of work file: 1024. woids (4. PAGES)
Elapsed time:00:00:07

9-8

SOBS

160076.;.R

CHAPTER 10
SWITCHES

You use switches and options to control the construction of your task
image.
This chapter provides detailed reference information on all
the TKB switches. Chapter 11 describes the TKB options.

10.1

SWITCHES

The syntax for a file specification, as given in Chapter 1, is:
dev: [group,member]filename.type;version/swl/sw2 ••• /swn
Optionally, you can conclude a file specification with one or more
switches (swl,sw2, ••. swn). When you do not specify a switch, the Task
Builder establishes a default setting for it.
You designate a switch by a 2- to 4-character code preceded by a
slash (/).
If you precede the 2- to 4-character code with a minus
sign (-) or the letters NO, TKB negates the function of the two
characters.
For example, TKB recognizes the following settings for
the switch CP (checkpointable):
/CP
/-CP
/NOCP

The task is checkpointable.
The task is not checkpointable.
The task is not checkpointable.

In some cases, two particular switches cannot both be used in a
file
specification.
When
such a conflict occurs,
TKB selects the
overriding switch according to the following table:

Switch

Overriding Switch

/AC (Ancillary
Control Processor)

/PR (Privileged)

/AC

/EA (Extended
Arithmetic Element)

/FP (Floating
Point Processor)

/FP

/CC (Concatenated
object file)

/LB (Library file)

/LB

For example:
MCR>TKB IMGS=IN6,INS/LB/CC
TKB assumes that the input file INS is a library file.
It searches
T.L
....:1--- --.L. ,:J.Ul,.;.l.UUC
- - 1 .... ...:1.: .L.1-J.
uvco::>
J.U
the file for undefined global references.
task image all of the modules in INS.
~

10-1

UV~

~UC

SWITCHES
The switches that TKB recognizes are given in alphabetical order in
Table
10-1.
Sections
10.1.1
through
10.1.30 give detailed
descriptions of each switch, in alphabetical order, including:
•

The switch format

•

The file(s)

•

A description of the effect of the switch on the Task Builder

•

The default assumption made if the switch is not present

to which the switch can be applied

Table 10-1
Task Builder Switches
Applies
to File

Default

Task is an ancillary control processor.

.TSK

/-AC

/AL

Task can be checkpointed to space
allocated in the task image file.

.TSK

/-AL

/CC

Input file consists of concatenated
object modules.

.OBJ

/CC

/CM

Memory-resident overlays are aligned
on 256-word physical boundaries.

.TSK

/-CM

/CO

Causes TKB to build a
shared common.

.TSK
.STB

/CO

/CP

Task is checkpointable.

.TSK

/-CP

/CR

A global cross-reference listing
is appended to the memory allocation
file.

.MAP

/-CR

/DA

Task contains a debugging aid.

.TSK,
.OBJ

/-DA

/DL

Specified library file is a replacement for the system object
module library.

.OLB

/-DL

/EA

Task uses extended arithmetic
element.

.TSK

/-EA

/EL

Specifies library size according
to partition size.

.TSK

/-EL

/FP

Task uses the Floating Point
Processor.

.TSK

Format

Meaning

/AC[:n]

)~FP on '1isxLiiM'
-/"~P;;,,o.n/1~~~;.;.,JJ/t~?l>:,_u~:,, -

(continued on next page)

10-2

SWITCHES

Table 10-1 (Cont.)
Task Builder Switches

Format

Meaning

Applies
to File

Default

/FU

All co-tree overlay segments are
searched for matching definition or
reference when modules from the default object module library are
being processed.

.TSK

/-FU

/HD

Task image includes a header.

.TSK,
.STB

/HD

. ·:>t~Ip.
/IP

Allows TKB to inform INS that the
task purposely overmaps the
I/O page.

.TSK

/-IP

/LB

Input file is a library file.

.OLB

/-LB

/LI

Informs TKB to build a
shared library.

.TSK
.STB

/-LI

/MA

Map file includes information
from the file.

.MAP,
.OBJ

/MA or /-MAl

/MM

System on which the task is to
run has memory management.

.TSK

/MM or /-MM2

/MP

Input file contains an overlay
description.

.ODL

/-MP

;..<'r.a~.~/',~~,<~:·,~.~~ltJ~~·~J;·: . :~~.$~:'.~•·J.L·

. ··.!~I\:

/NM

Tells TKB to inhibit two
diagnostic messages.

.TSK

/-NM

/PI

Task is position independent.

.TSK,
.STB

/-PI

/PM

Postmortem Dump is requested.

.TSK

/-PM

/PR[:n]

Task has privileged access rights.

.TSK

/-PR

/RO

Memory-resident overlay operator
( ! ) is enabled.

.TSK

/RO

/SE

Messages can be directed to the
task by means of the Executive
SEND directive.

.TSK

/SE

1. The default is /MA for an input file, and /-MA for
and resident library .STB files.

system

j..;.;M.Q'
'

library

2. The default for the memory management switch is /MM if the host
system has memory managment hardware, and /-MM if the host system does
not have memory management hardware.
(continued on next page)

10-3

SWITCHES
Table 10-1 (Cont.}
Task Builder Switches

Format

Meaning

Applies
to File

Default

/SG

Allocates task program sections
alphabetically by access code (RW
followed by RO) •

.TSK

/-SG

/SH

Short memory allocation file is
requested.

.MAP

/SH

/SL

Task is slaved to an initiating
task.

.TSK

/-SL

/SP

Spool map output.

.MAP

/SP

/SQ

Allocates task program sections
in input order by access code.

.TSK

/-SQ

/SS

Selective search for global
symbols.

.OBJ

/-SS

/TR

Task is to be traced.

.TSK

/-TR

/WI

Memory allocation file is printed
at a width of 132 characters.

.MAP

/WI

/Xll

RSX-HM-PLUS only switch. Task is
to have an external header.

.TSK

/XT[:n]

TKB exits after n diagnostic.

.TSK

/-XT

3. The default is ultimately determined by the /XHR switch in
INSTALL command, which overrides the TKB setting except for /-XH.

10=4

the

SWITCHES

10.1.1

/AC[:n] -- Ancillary Control Processor

File
Task image
Syntax
file.TSK/AC:O=file.OBJ

or
file.TSK/AC:4=file.OBJ

or
file.TSK/AC:5=file.OBJ
Description
The /AC switch informs TKB that your task is an ancillary control
processor; that is, it is a privileged task that extends certain
Executive functions. For example, the system task FllACP is an
ancillary control processor that receives and processes FILES-11
related input and output requests on behalf of the Executive.
Effect
This switch also informs TKB that your task is privileged.
TKB
sets the AC attribute flag and the privileged attribute flag in
your task's label block flag word.
The value of n is an octal number that specifies the first KT-11
Active Page Register (APR) that you want the Executive to use to
map your task's image when your task is running in user mode.
Legal values are O, 4, and 5.
If you do not specify n, the Task
Builder assumes a value of 5.
If you do not explicitly specify that your task is to run on a
mapped system
(through the /MM switch) and it is not otherwise
implied (TKB is not running in a system with KT-11 hardware), TKB
merely tests the value of n for validity, but otherwise ignores
it.
Default
/-AC
NOTE
You should not use /AC and
same command line.

10-5

/PR

the

SWITCHES

10.1.2

/AL -- Allocate Checkpoint Space

File
Task image

Syntax
file.TSK/AL=file.O~J

Description
The /AL switch informs TKB that your task is checkpointable. The
system will checkpoint it to a space in your task's image file.
However, the system uses the system checkpoint file first if you
specified dynamic checkpointing.

Effect
As well as making your task checkpointable, this switch directs
TKB to allocate additional space in your task image file to
contain the checkpointed task image.

Default
/-AL
NOTES
Do not use /CP in the same command
in which you use /AL.

line

Also, the /AL switch should not be used
with the /-HD switch to build tasks.
Examples of tasks
that use the /-HD
switch
are:
the Executive, device
drivers, and commons.

10-6

SWITCHES

cc
10.1.3

/CC -- Concatenated Object Modules

File
Input
Syntax
file.TSK=file.OBJ/-CC
Description
/CC controls the way TKB extracts modules from your input file.
Effect
By default, TKB includes in your task's image all the modules of
your
input file.
If you negate this switch (as in the Syntax
section above) , TKB includes only the first module of your
input
file.
Default
/CC

10-7

SWITCHES

CM
10.1.4

/CM -- Compatibility Mode Overlay Structure

File
Task image

Syntax
file.TSK/CM=file.OBJ

Description
/CM causes the Task Builder to build your task
mode.

compatibility

Effect
overlay
segments
on
256-word
TKB aligns memory-resident
boundaries for compatibility with other implementations of the
mapping directives.

Default
/-CM

10-8

SWITCHES

co
10.1.5

/CO -- Build a Common Block Shared Region

File

Task image
.STB file
Syntax

file.TSK/CO=file.OBJ
or
,,file.STB/CO=file.OBJ
Description

The /CO switch informs TKB that a shared common is being built.
If you build a shared common, you should use the /CO switch and
the /-HD switch.
If you use the /-PI switch for an absolute shared common, all the
program sections in the common are marked absolute.
Using the
/-PI/-HD switches without the /CO switch causes TKB to build a
shared library.
If you use the /PI switch for a relocatable shared common,
program sections in the common are marked relocatable.

all

In either case, the .STB file contains all
the program section
names, attributes, length, and symbols.
TKB links common blocks
by means of program sections.
Therefore,
the
.STB file
of a
shared region built with the /CO switch contains all defined
program sections.
Using the /PI/-HD switches without the /CO switch causes
build a shared common.

TKB

The /CO switch does not have a /-CO form.
Effect

This switch causes TKB to
declarations in the .STB file.
Defaults

/CO

10-9

include

all

program

section

SWITCHES

CP
10.1.6

/CP -- Checkpointable

File
Task image
Syntax
file.TSK/CP=file.OBJ
Description
/CP causes TKB to mark your task as checkpointable.
The system
will checkpoint it to space that you have allocated in the system
checkpoint file on the system disk. This switch assumes that you
have allocated the checkpoint space through the MCR command ACS.
(Refer to the RSX-llM/M-PLUS MCR Operations Manual.)
Effect
The system writes your task to the system checkpoint file on
secondary storage when its physical memory is required by a task
of higher priority.
Default
/-CP
NOTE
Using
/AL
also
checkpointable.

makes

10-10

your

task

SWITCHES

CR
10.1.7

/CR -- Cross-Reference

File

Memory allocation (map)
Syntax

file.TSK,file.MAP/CR=file.OBJ
Description

The /CR switch directs TKB to add a
the map file of your task.

cross-reference

listing

Effect

TKB creates a special work file (file.CRF) that contains segment,
module, and global symbol information. The Task Builder then
calls the Cross-Reference Processor (CRF) to process the file.
CRF creates a cross-reference listing from the information
contained in the file, and then deletes file.CRF.
(Refer to the
RSX-11 Utilities Manual for more information on CRF.)
The Example section below describes the
and its contents.

cross-reference

listing

NOTE
For this switch to be effective,
must be installed in your system.

CRF

Default

/-CR
Example

Example 10-1 shows a cross-reference listing for task OVR.
The
numbered items in the notes correspond to the numbers in Example
10-1.

10-11

SWITCHES

CR (Cont.)
Example 10-1
CREF

Cross-Reference Listing for OVR.TSK

CREATED BY

TKB

ON 27-JUL-82 AT 09:46

GLOBAL CROSS REFERENCE

CREF

SYMBOL

VALUE

REFERENCES •••

AADD
ADDEXI
ARGBLK
BUFF
CALC
DIFR
DI VEX I
DIVR
DIVV
I
IE. EOF
INITL
INPUT
IOSB

020000-R
020060-R
001340-R
001366-R
003270-R
001360-R
020062-R
001364-R
020000-R
001350-R
177766
005664-R
003364-R
001334-R

* AADD
* AADD

@ CALC

CALC

# MAIN

CREF

# MAIN

OUTPUT

* CALC

@ MAIN

CALC

# MAIN

* DIVV

# MAIN

CALC
@ CALC

* DIVV

INPUT
INPUT
# INITL
* INPUT
INPUT

# MAIN
# QIOSYM
....

CREATED BY

MAIN

@ MAIN

# MAIN

TKB

ON 27-JUL-82 AT 09:46

SEGMENT CROSS REFERENCE
RESIDENT MODULES

AADD
CALC
DIVV
INPUT
LIBROT
MAIN

AADD
CALC
DIVV
AR ITH
INITL
ALERR
VCTDF
MULL
AR ITH
EDTMG
SUBB

SUBB

PAGE 2
CREF

SEGMENT NAME

MULL
OUTPUT

PAGE

VOl

CATB
SAVAL
AUTO

INPUT

QIOSYM

SAVRG

MAIN

OVCTR

OVDAT

OVRES

SAVRl

CATB
OUTPUT

CBTA
QIOSYM

CDDMG
SAVRG

C5TA

DARI TH

EDDAT

NOTES

The cross-reference page header gives the name of the memory
allocation file,
the originating task (TKB), the date and
time the memory allocation file was created, and
the
cross-reference page number.

The cross-reference list contains an alphabetic listing of
each global symbol along with its value and the name of each
referencing module. When a symbol is defined in several
segments within an overlay structure, the last defined value
is printed. Similarly, if a module is loaded in several
segments within the structure, the module name is displayed
more than once within each entry.

10-12

SWITCHES

CR (Cont.)
The suffix -R appears next to the
relocatable.

value

the

symbol

Pref ix symbols accompanying each module name define the
of reference as follows:
Pref ix Symbol
blank

is
type

Reference Type
Module contains a
reference
resolved in the same segment
segment toward the root.

that
is
or in a

Module contains a
reference
that
is
resolved directly in a segment away from
the root or in a co-tree.

Module contains a
reference
that
resolved through an autoload vector.

Module
contains
definition.

Module contains an autoloadable definition.

nonautoloadable

The segment cross-reference lists the name of each overlay
segment and the modules that compose it.
If the task is a
single-segment task, this section does not appear.

10-13

SWITCHES

DA
10.1.8

/DA -- Debugging Aid

File

Task image or input
Syntax
file.TSK/DA=file.OBJ
or
file.TSK=file.OBJ,file.OBJ/DA
Description
/DA causes TKB to include a debugging aid in
debugging aid controls the task's execution.

your

task.

The

Effect
If you apply this switch to your task image file,
TKB includes
the system debugging a id LBO: [ 1, 1] ODT. OBJ .in to .yo~r task ima.ge.
rf you use the /DA: ·swfteh wiith the' ' fro. swLt:;ch·, r TKB' · include:s·
LB::;f;J:'1 i) ffi!!E£;q:.··qBJ't ·ii~·~~~ ~a;Sl~'•:;
TKB passes control to the debugging
system starts task execution.

program

when

you

the

If you apply this switch to one of your input files, TKB assumes
that the file is a debugging aid that you have written.
Such
debugging programs can trace a task, printing out relevant
debugging information, or monitor· the task's performance for
analysis. The default file type for the debugging aid is .OBJ.
In either case, /DA has the following effects on your task image:
•

The transfer address of the debugging
task transfer address.

initializes the header of
• TKB
initial task load,
registers

aid

overrides

the

your task so that, on
RO through R4 contain the

following values:
RO - Transfer address of task.
Rl - Task name in Radix-50 format

(word #1).

R2 - Task name (word #2).
R3 - The first three of six RAD50 characters representing
the version of your task. TKB derives the version
from the first .IDENT directive it encounters in your
task.
If no .IDENT directive is in your task, this
value is 01.
R4 - The second three RAD50
version of your task.

Default
/-DA
10-14

characters

representing

the

SWITCHES

DL
10.1.9

/DL -- Default Library

File
Input

Syntax
file.TSK=file.OBJ,file.OLB/DL

Description
This switch causes the input file to be a
replacement for
the
system object module library.
The default file type for the
input file is .OBJ.

Effect
The library file you have
specified
replaces
the
file
LBO:[l,l]SYSLIB.OLB as the library file that the Task Builder
searches to resolve undefined global references.
The default
device for
the replacement file is SYO:.
TKB refers to it only
when undefined symbols remain after
it has processed all the
files you have specified.
You can apply the /DL switch to only
one input file.

Default
/-DL

10-15

SWITCHES

EA
10.1.10

/EA -- Extended Arithmetic Element

File
Task image
Syntax
file.TSK/EA=file.OBJ
Description
/EA informs TKB that
Arithmetic Element.

your

task

uses

the

KEll-A

Extended

Effect
TKB allocates three words in your task's header
state of the extended arithmetic element.

for

Default
/-EA
NOTE
You should not use /EA and
same command line.

10-16

/FP

the

saving

the

SWITCHES

EL
10.1.11

/EL -- Extend Library

File
Task image
Syntax
file.TSK/LI/-HD/EL=file.OBJ
Description
/EL places the upper address limit as determined by the PAR
option in the library's label block, though the actual size of
the library may be smaller. This switch is useful when you build
vectored libraries such as RMS, which are subject to size
changes.
Effect
This switch specifies the maximum possible size for
the library
according to the size specified in the PAR option.
The switch
specifies a larger library virtual address range than is actually
present in the library to allow RMS to map its vectored library
segments.
Default
/-EL

10-17

SWITCHES

FP
10.1.12

/FP -- Floating Point

File
Task image
Syntax
file.TSK/FP=file.OBJ
Description
/FP informs TKB that your task uses the Floating Point Processor.
Effect
TKB allocates 25 words in your task's header for saving the state
of the Floating Point Processor.
Default
/-FP on

R.sx;...1ut syst;em$

/F'P"'' '()fr''.:Rsx=IiM81l~lJ~''":~Y~t~ifS,*':
NOTES
1.

You should not use /FP
the same command line.

The /FP switch allocates space in
the task header to save the floating
point status if your task is context
switched.
Therefore, in an RSX-llM
system, if a task that uses the
Floating Point Processor is built
without the /FP switch, the task
will run correctly until a second
task that uses the Floating Point
Processor is run.
Then both tasks
will
either
crash
or
produce
incorrect results.
For information
on changing the
Task
Builder's
defaults, refer to Appendix F.

10-18

and

/EA

SWITCHES

FU
10.1.13

/FU -- Full Search

File
Task image
Syntax
file~TSK/FU=fileeODL/MP

Description
This switch controls the Task Builder's search for undefined
symbols when it is processing modules from the default library.
Effect
When TKB processes modules from the default object module
library,
and it encounters undefined symbols within those
modules, it normally limits its search for definitions to the
root of the main tree and to the current tree.
Thus, unintended
global references
between
co-tree
overlay
segments
are
eliminated.
When the /FU switch is appended to the task image
file of an overlaid task, TKB searches all co-tree segments for a
matching definition or reference.
See Sections 3.2.2 and 3.2.3
in Chapter 3 for more details.
Default
/-FU

10-19

SWITCHES

HD
10.1.14

/HD -- Header

File

Task image or symbol definition

Syntax
file.TSK/-HD,,file.STB=file.OBJ
or
file.TSK,,file.STB/-HD=file.OBJ

Description
The /-HD form of this switch directs TKB to exclude a header from
your task image.

Effect
TKB does not construct a header in your task image. You use the
negated form of this switch when you are building commons,
resident libraries, and loadable drivers.

Default
/HD

10-20

SWITCHES

10-21

SWITCHES

IP
10.1.16

/IP -- Task Maps 1/0 Page

File
Task image
Syntax
file.TSK/PR/-IP=file.OBJ
Description
You use the /-IP switch to inform TKB that the task is purposely
over 12K and does not need to be mapped to the I/O page.
Effect
TKB sets a bit in the task's label block that informs INSTALL
(INS)
that the task intentionally does not map the I/O page.
When this bit is set, INS does not display an error message when
it detects that the privileged task extends into APR 7.
Default
/IP

10-22

SWITCHES

LB
10.1.17

/LB -- Library File

File
Input
Syntax

file.TSK=file.OBJ,file.OLB/LB
or
fileeTSK=file.OBJ,file.OLB/LB:mod-l:mod-2 ••• :mod-8
Description
The file to which this switch is attached is an object module
library file.
The Task Builder's interpretation of this switch
depends upon which of the following forms you use:
•

Without arguments (the first syntax given above)

•

With arguments

(the second syntax given above)

The default file type is .OLB.
Effect
If you apply this switch without arguments, TKB assumes that your
input· file is a library file of relocatable object modules.
TKB
searches the file immediately to resolve undefined references
in
any
modules preceding the library specification.
It also
extracts from the library, for inclusion in the task image, any
modules that contain definitions for such references.
If you apply the switch with arguments, TKB extracts from the
library the modules named as arguments of the switch regardless
of whether the modules contain definitions for
unresolved
references.
If you want TKB to search an object module library file both to
resolve global references and to select named modules for
inclusion in your task image, you must name the library file
twice:
once, with the modules you want included in your task
image listed as arguments of the /LB switch; and a second time,
with the /LB switch and no arguments.
For example:
file.TSK=file.OLB/LB:mod-l:mod-2,file.OLB/LB

10-23

SWITCHES

LB (Cont.)
The position of the library file within TKB command
important.
The following rules apply:

sequence

library file must follow to the right of the input
• The
file(s)
that contain references to be defined
in the
library.

For example:

TKB>file.TSK=infilel.OBJ,lib.OLB/LB
The command above illustrates the correct usage of the /LB
switch;
the following command illustrates incorrect usage:
TKB>file.TSK=lib.OLB/LB,filel.OBJ
•

If you are using the Task Builder's multiline input,
you specify a given library more than once during
command sequence, you must attach the /LB switch to
library file each time you specify the library.
example:

and
the
the
For

>TKB
TKB>file.TSK=filel.OBJ,file2.0BJ,lib.OLB/LB
TKB>file3.0BJ,file4.0BJ,lib.OLB/LB

II
•

When you are building an overlay structure, you must
specify object module libraries for an overlay structure
within the Overlay Description Language (ODL) file for the
structure.
To do this, you must use the .FCTR directive to
specify the library. For example:
AFCTR:
BFCTR:
LIB:

.ROOT CNTRL-LIB-(AFCTR,BFCTR,C)
.FCTR AO-LIB-(Al,A2-(A21,A22))
.FCTR BO-LIB-(Bl,B2)
.FCTR LB: [303,3]LIBOBJ.OLB/LB
.END

The technique used in the ODL file above allows you to control
the placement of object module library routines into the
segments of your overlay structure.
(For more information on
overlaid tasks, see Chapter 3.)
NOTES
1.

You should not use the /LB switch
and the /CC switch in the same
command sequence.

You can use the /SS switch
in
conjunction
with the /LB switch
{with or without
arguments)
to
perform
a
selective search for
global definitions.

Default
/-LB
10-24

SWITCHES

LI
10.1.18

/LI -- Build a Library Shared Region

File
Task image
.STB file
Syntax
file.TSK/LI=file.OBJ
or
,,file.STB/LI=file.OBJ
Description
The /LI switch makes TKB build a shared library.
However, you
must use the /-HD switch with the /LI switch to build the shared
library. The /LI switch does not have a /-LI form.
Effect
TKB includes only one program section
file.

declaration

the

.STB

If you use the /-PI switch for an absolute library, TKB names the
program section • ABS, makes the library position dependent, and
defines all symbols as absolute.
Also,
if you use the /-PI
switch without the /LI switch, TKB assumes /LI to be the default.
If you use the /PI switch for a relocatable library, TKB names
the program section the same as the root segment of the library.
TKB forces this name to be the first and only declared program
section in the library. TKB declares all global symbols in the
.STB file relative to that program section. Also, if you use the
/PI switch without the /LI switch, TKB assumes that a shared
common is to be built (/CO is the default).
Default
/-LI

10-25

SWITCHES

MA
10.1.19

/MA -- Map Contents of File

File
Input or memory allocation
Syntax
file.TSK,file.MAP=file.OBJ,file.OBJ/-MA
or
file.TSK,file.MAP/MA=file.OBJ
Description
TKB is to include information from your input file in the
allocation output file.

memory

Effect
If you negate this switch and apply it to an input file,
TKB
excludes from the map and cross-reference listings all global
symbols defined or referred to in the file.
In addition, TKB
does not list the file in the "file contents" section of the map.
If you apply this switch to the map file, TKB includes in the map
file the names of routines it has added to your task from SYSLIB.
It also includes in the map file
information contained in the
symbol definition file of any shared region to which the task
refers.
Default
/MA for input files
/-MA for system library and resident library STB files

10-26

SWITCHES

MM
10.1.20

/MM[:n] -- Memory Management

File
Task image
Syntax
file.TSK/MM[:n]=file.OBJ
or
file.TSK/-MM[:n]=file.OBJ
Description
The /MM switch informs TKB whether the system on which your task
is to run has memory management hardware.
Specify n as the
decimal numbers 28 or 30.
Effect
If you use n with the /-MM switch {for an unmapped system), n
specifies the highest physical address in K-words of the task or
system being built. If you do not specify n with /-MM, the
default highest address of the task or system is 28K.
If you specify n with /MM, n is ignored.
Default
When you do not apply /MM or /-MM to your task image file, TKB
allocates memory according to the mapping status of the system on
which your task is being built. The maximum task size for a
mapped system is always 32K. The default highest address for a
task or system in an unmapped system is 28K.
NOTE
When you use /-MM, TKB
does
not
recognize
memory-resident overlay operator(!).
TKB checks
operator for correct syntax, but it does not create
resident overlay segments.

10-27

the
the
any

SWITCHES

MP
l0ele21

/MP -- Overlay Description

File
Input
Syntax
file.TSK=file.ODL/MP
Description
The /MP switch specifies that the
Description Language (ODL) file.

input

file

Overlay

Effect
TKB receives all the input file specifications from this file.
It allocates virtual address space as directed by the overlay
description.
If you use the Task Builder's multiline command
format
(see Section 1.3), TKB requests option information at the
console terminal by displaying:
ENTER OPTIONS:.

NOTES
1.

If you use the multiline command
format when you specify an ODL file,
TKB automatically prompts for option
input.
Therefore, you must not use
the single slash (/) to direct TKB
to switch to option input mode when
you have specified /MP on your input
file.

When you specify /MP on the input
file for your task, it must be the
only input file that you specify.
The default file type is .ODL.

Default
/-MP

10-28

SWITCHES

MU·

~~' ~ ' ,

pe f ~·~.l:t..

/..;:Mtf

10-29

SWITCHES

NM
10.1.23

/NM -- No Diagnostic Messages

File

Task image
Syntax
file.TSK/NM=file.OBJ
Description
The /NM switch controls the printing of diagnostic messages.
Effect
This switch eliminates two messages:
n Undefined symbols segment seg-name
and
Module module-name multiply defines P-section p-sect-name
Default
/-NM

10-30

SWITCHES

Pl
10.1.24

/PI -- Position Independent

File
Task image or symbol definition
Syntax
file.TSK/PI=file.OBJ
or
file.TSK,,file.STB/PI=file.OBJ
Description
/PI informs TKB that the task's shared region contains only
position-independent code or data.
Use this switch with /-HD and
either /CO or /LI.
Effect
TKB sets the position-independent code (PIC)
attribute
the label block flag word of the shared region.

flag

Be aware that if you specify /PI without using the /CO or /LI
switches, TKB builds a shared common (/CO default). Also, if you
specify /-PI without using the /CO or /LI switch, TKB builds a
shared library (/LI default).
Default
/-PI

10-31

SWITCHES

PM
10.1.25

/PM -- Postmortem Dump

File
Task image
Syntax
file.TSK/PM=file.OBJ
Description
If you use /PM and your task terminates abnormally,
the
automatically lists the contents of the memory image.

system

Effect
TKB sets the Postmortem Dump flag in your task's label flag word.
NOTES
1.

If your task issues an ABRT$
(abort
task) directive, the system will not
dump the task image even though TKB
has set the Postmortem Dump flag in
your task's label flag word.
In
this case, the system assumes that a
Postmortem Dump is not necessary
since you know why your task was
aborted.

The PMD utility must be installed in
your system and be able to get into
physical memory for this switch to
be effective.

Default
/-PM

10-32

SWITCHES

PR
10.1.26

/PR[:n] -- Privileged

File
Task image
Syntax
file.TSK/PR:O=file.OBJ
or
file.TSK/PR:4=file.OBJ
or
file.TSK/PR:5=file.OBJ
Description
The /PR switch informs TKB that your task is privileged with
respect to memory and device access rights.
If you specify PR:O,
your task does not have access to the I/O page or the Executive.
However,
if you specify PR:4 or PR:5, your task does have access
to the I/O page and the Executive, in addition to its own
partition.
Effect
TKB sets the Privileged Attribute flag in your task's label block
flag word.
The value of n is an octal number that specifies the first Active
Page register that you want the Executive to use to map your task
image when your task is running in user mode. Legal values are
O,
4, and 5.
If you do not specify one of these values, TKB
assumes a value of 5.
If you do not explicitly specify that your task is to run on a
mapped system, (through the /MM switch) and it is not implied (by
the presence of KT-11 hardware on the system upon which TKB is
running), TKB merely tests the value
(:n) of the switch for
validity; otherwise, TKB ignores it.
Privileged tasks are
described in Chapter 9.
Default
/-PR
NOTE
You should not use /PR and
same command line.

10-33

/AC

the

SWITCHES

RO
10.1.27

/RO

Resident Overlay

File
Task image
Syntax
file.TSK/-RO=file.ODL/MP
Description
The Task Builder's recognition
operator (!) is enabled.

the

memory-resident

overlay

Effect
The memory-resident overlay operator (!), when present in the
overlay description file,
indicates to TKB that it is to
construct a task image that contains one or more memory-resident
overlay segments.
If you negate this switch (as in the Syntax
section above), TKB checks the operator for correct syntactical
usage, but otherwise ignores it.
With the memory-resident
overlay operator thus disabled, TKB builds a disk-resident
overlay from the overlay description file.
Default
/RO

10-34

SWITCHES

SE
10.1.28

/SE -- Send

File

Task image
Syntax
file.TSK/-SE=file.OBJ
Description
This switch determines whether messages can be directed to your
task by means of the Executive Send directive.
(Refer to the
RSX-llM/M-PLUS Executive Reference Manual for information on the
Send directive)

Effect
By default, messages can be directed to your task by means of the
Executive Send directive.
If you negate this switch (as in the
Syntax section above), the system inhibits the queuing of
messages to your task.
Default
/SE

10-35

SWITCHES

SG
10.1.29

/SG -- Segregate Program Sections

File
Task image
Syntax
file.TSK/SG=file.OBJ
Description
The /SG switch allocates virtual address space to all
(RW)
program sections and then to all read-only (RO) program sections.
Effect
The /SG switch gives you control over the ordering of program
sections.
By using the /SG switch, you cause TKB to order
program sections alphabetically by name within access code
(RW
followed by RO).
If you specify the /SQ switch with the /SG
switch, TKB orders program sections in their input order by
access code.
See the description of the /SQ switch.
You use the negated switch, /-SG, to make TKB interleave the RW
and RO program sections. Thus, the combination /-SG/SQ results
in a task with its program sections allocated in input order and
its RW and RO sections interleaved. Additionally, you can use
/-SQ/-SG to make TKB order program sections alphabetically with
RW and RO sections interleaved.
However, /-SG is the default.
When taskbuilding multiuser tasks, the /MO switch causes TKB to
default to /SG.
Therefore, to correctly build read-only tasks,
you can use the /MU switch only.
Default
/-SG

10-36

SWITCHES

SH
10.1.30

/SH -- Short Map

File
Memory allocation (map)
Syntax
file.TSK,file.MAP/SH=file;OBJ
Description
If you specify /SH, TKB produces the short version of the
allocation file.

memory

Effect
TKB does not produce the "file contents" section
allocation file.

the

memory

Default
/SH
Example
The memory allocation file consists of the following items:
•

Page header

•

Task attributes section

•

Overlay description (if applicable)

•

Root segment allocation

•

Tree segment description (if applicable)

•

Undefined references (if applicable)

•

Task Builder statistics

An example of the memory allocation file
(map)
is shown in
Example 10-2.
The numbered and lettered items in the notes
correspond to the numbers and letters in Example 10-2.
Example 10-2
OVR.TSK;l

Memory Allocation File (Map)

Memory Allocation Map TKB M40.10
15-DEC-82
11:28

Partition name :
Identification :
Task UIC
Stack
limits:

Page 1

Example

GEN @) ~
01@)
[303,3]@) (!:I
000260 001257 001000 00512.:J;

(continued on next page)

10-37

SWITCHES

SH (Cont.)
Example 10-2 (Cont.)

Memory Allocation File (Map) Example

Prg xfr address: 001264 @ CE)
Total address windows: 1. CD ® Q)
Task
image size
: 7488. words @) @
Task address limits: 000000 035107@)
R-W disk blk limits: 000002 000073 000072 00058.@)

OVR.TSK Overlay description:
Base

Top

000000
005034
005034
021060
021060

005033
021057
021057
035103
035107

OVR.TSK
ROOTM

Length
005034
014024
014024
014024
014030

02588.
06164.
06164.
06164.
06168.

ROOTM
MULOV
AD DOV
SUBOV
DIVOV

Memory allocation map TKB M40.02
28-DEC-81
09:10

*** Root segment:

ROOTM

Page 2

R/W mem limits: 000000 005033 005034 02588.~
Disk blk limits: 000002 000007 000006 00006.@)
Memory allocation synopsis:
Section

-------

. BLK.: (RW,I,LCL,REL,CON) 001260 002514 01356.

ANS

Title

!dent

File

ROOTM
PRNOV
SAVOV

01 ®
01
01

ROOTM.OBJ;l
PRNOV.OBJ;l
SAVOV.OBJ;l

ROOTM
PR NOV

01
01

ROOTM.OBJ;l
PRNOV.OBJ;l

001260
001362
001642
003774
003774
003774
003774

000102
000260
000042
000002
000002
000002
000002

00066.
00176.
00034.
00002.
000002.
00002.
00002.

004052-R
004022-R

PRINT
SAVAL

001550-R
001642-R

: (RW,D,GBL,REL,OVR)

Global Symbols:
AADD
OVR.TSK
MULOV

004032-R

DIVV
MULL

Memory allocation map
28-DEC-81
09:10

SUBB

004042-R CD

@®CD CD®

TKB M40.02 Page 3

*** Segment: MULOV

R/W mem limits: 005034 021057 014024 06164.
Disk blk limits: 000010 000024 000015 00013.
(~ontinued

10-38

on next page)

SWITCHES

SH (Cont.)
Example 10-2 (Cont.)

Memory Allocation File (Map)

Example

Memory allocation synopsis:
Section
• BLK.: (RW, I,LCL,REL,CON)

005034
005034
$$ALVC: (RW,D,LCL,REL,CON) 021060
$$RTS :(RW,I,BGL,REL,OVRj 004250

014024
014024
000000
000002

06164.
06164.
00000.
00002.

Title

Ident

File

MULOV

MULOV.OBJ;l

Global symbols:
MULL

021034-R

J
*** Task builder statistics:
Total work file references: 7156. ~
Work file reads:
r0
Work file writes: 0. ® ®
Size of core pool: 7086. words (27. pages) Gt
Size of work file: 3072. words (12. pages)®

O.}

ELAPSED TIME:00:00:14

Notes:
.,

The page header shows the name of the task image file and the
overlay segment name
(if applicable), along with the date,
time, and version of TKB that created the map.

The task
attributes
information:

section

contains

the

following

Task name
The name specified in the TASK option.
If
you do not use the TASK option, TKB suppresses this
field.

(El

Partition name -- The partition specified in the PAR
option.
If you do not specify a partition, the default
is partition GEN.

Identification -- The task version as specified in the
.IDENT assembler directive.
If you do not specify the
task identification, the default is 01.
Task UIC -- The task UIC as specified in the UIC option.
If you do not specify the UIC,
the default is the
terminal U!C.

10-39

SWITCHES

SH (Cont.)
~

Task priority -- The priority of the task as specified in
the PR! option.
If you do not specify PRI, the default
is 50, and is not shown on the map.

Stack limits -- The low and high octal addresses of the
stack, followed by its length in octal and decimal bytes.

ODT transfer address -- The starting address of the ODT
debugging aid.
If you do not specify the ODT debugging
aid, this field is suppressed.

Program transfer address -- The address of the symbol
specified in the
.END directive of the source code of
your task.
If you do not specify a transfer address for
your
task, TKB automatically establishes a tranfer
address of 000001 for it.
TKB also suppresses this field
in the map if you do not specify a transfer address.
Task attributes -- These attributes are listed only if
they differ from the defaults.
One or more of the
following may be displayed:

Ancillary control processor.

Task is checkpointable, and task image
contains checkpoint space allocation.

Task is checkpointable, and task image file
will be checkpointed to system checkpoint file.

Task contains debugging aid.

Task uses KEll-A extended arithmetic element.

Task uses Floating Point Processor.

-HD

Task image does not contain header.

Task contains
data.

Postmortem Dump requested
abnormal task termination.

Task is privileged.

position-independent
in

the

file

code

and

event

-SE

Messages addressed to the task through the SEND
directive will be rejected by the Executive.

Task can be slaved.

Task initial PS word has T-bit enabled.

Task is I-: ,a,nfi

6-space :t:ask .

Total address windows -- The
allocated to the task.

10-40

number

window

blocks

SWITCHES

SH (Cont.)
CE)

Mapped array -- The amount of physical memory
{decimal
words) allocated through the VSECT option or Mapped Array
Declaration
(GSD type 7, described
in Appendix B);
mapped array is not shown if it does not apply.

physical
memory
Task extension -- The increment of
(decimal words)
allocated through the EXTTSK or PAR
option. Without these options,
task extension is not
shown.
Task image size -- The amount of memory
(decimal words)
required to contain your task's code.
This number does
not include physical memory allocated through the EXTTSK
option.

Total task size -- The amount of physical memory (decimal
words)
allocated,
including mapped array area and task
extension area. Total task size is not shown in this
example.

Task address limits -- The lowest and highest virtual
addresses allocated to the task, exclusive of virtual
addresses allocated to VSECTs and shared regions.

Read/write disk block limits -- From left to right:
the
first octal relative disk block number of the task's
header;
the last octal relative disk block number of the
task
image;
and the total contiguous disk blocks
required to accommodate the read/write portion of the
task image in octal and decimal.

Read-only disk block limits -- From left to right:
the
first octal relative disk block of the multiuser task's
read-only region;
the last octal relative disk block
number of the read-only region; and the total contiguous
disk blocks required to accommodate the read-only region
in octal and decimal.
This field appears only when you
are building a multiuser task.

The overlay description shows, for each overlay segment
in
the tree structure of an overlaid task, the beginning virtual
address {the base), the highest virtual address
(the top),
the length of the segment in octal and decimal bytes, and the
segment name.
Indenting is used to illustrate the ascending
levels in the overlay structure.
TKB prints the overlay
description only when an overlaid task is created.

The root segment allocation -- This section has the following
elements:

Root segment -- The name of the root segment.
task
is a single-segment task,
the entire
considered to be the root segment.

Read/write memory limits -- From left to right:
the
beginning virtual address of the root segment (the base);
the virtual address of the last byte in the segment
(the
top);
and the length of the segment in octal and decimal
bytes.

10-41

If your
task is

SWITCHES

SH (Cont.)
~

Disk block limits -- From left to right:
the first
relative block number of the beginning of the root
segment;
the last relative block number of the root
segment;
total number of disk blocks in octal; and the
total number of disk blocks in decimal.

Memory allocation synopsis -- From left to right:
the
program section name;
the program section attributes;
starting virtual address of the program section;
and
total length of the program section in octal and decimal
bytes.
The program section shown as • BLK.
in this field is the
unnamed relocatable program section.
Notice in this
example that there are 636(octal) bytes allocated to it
(2034 bytes - 1176 bytes = 636 bytes). This allocation
is the result of calls to routines that reside within the
unnamed
program
section
in
SYSLIB.
(For
more
information, see the description of the /MA switch in
Section 10.1.14.)

Module contributor -- This field lists the modules that
have contributed to each program section.
In this
example, the program section ANS was defined in module
ROOTM.
The module version is 01 (as a result of the
.!DENT assembler directive) and the file name from which
the module was extracted is ROOTM.OBJ;l.
If the program
section ANS had been defined in more than one module,
each contributing module and the file from which it was
extracted would have been listed here.
NOTE
The absolute section • ABS.
is not shown because
it appears in every module and always has a
length of O.

The global symbols section lists the global symbols
defined in the segment.
Each symbol is listed along with
its octal value. A -R is appended to the value if the
symbol is relocatable.
The list is alphabetized in
columns.

The file contents section (which is composed of the four
fields listed below) is printed only if you specify /-SH in
the TKB command sequence. TKB creates this section for each
segment in an overlay structure.
It lists the following
information:
~

Input file -- File name, module name as established by
the .TITLE assembler directive, and module version as
established by the .!DENT assembler directive.

(El

Program section -- Program section name, starting virtual
address of the program section, ending virtual address of
the program section, and length in octal and decimal
bytes.

10-42

SWITCHES

SH (Cont.)
CD

Global symbol -- Global symbol names within each program
section and their octal values.
If the segment is
autoloadable (see Chapter 3), this value is the address
of an autoload vector.
The autoload vector in turn
contains the actual address of the symbol.
A -R is appended
relocatable.

the

value

the

symbol

this

field

Program section
The contents
described in note g above.

Undefined References -- This field
global symbols in the segment.

lists

the

undefined

The tree segment description is printed for every overlay
segment in an overlay structure.
Its contents are the same
for each overlay segment as the root segment allocation is
for the root segment.

(i)

Task builder statistics lists the following
which can be used to evaluate TKB performance:

information,

times

that

TKB

Work file references
The number of
accessed data stored in its work file.

Work file reads -- The number of times that the work file
device was accessed to read work file data.

Work file writes -- The number of times that the
file device was accessed to write work file data.

Size of pool -- The amount of memory that
for work file data and table storage.

was

Size of work file -- The amount of device
was required to contain the work file.

storage

Elapsed time
The amount of wal 1-clock time required to
construct
the
task
image and produce the memory
allocation (map) file.
Elapsed time is measured from the
completion of option input to the completion of map
output. This value excludes the time required to process
the overlay description, parse the list of input file
names, and create the cross-reference
listing
(if
specified).

available

See Appendix F for a more detailed discussion of the work file.

10-43

work

that

SWITCHES

SL
10.1.31

/SL -- Slave

File
Task image
Syntax
file.TSK/SL=file.OBJ
Description
This switch directs TKB to mark
initiating task.

your

task

slave

Effect
TKB attaches the slave attribute to your task.
When your task
successfully executes a Receive Data directive, the system gives
the UIC and TI:
device of the sending task to it.
The slave
task then assumes the identity and privileges of the sending
task.
This switch only applies to your task if the system that you are
using has multiuser protection.
(Refer to your system generation
manual for more information on multiuser protection and slave
tasks.)
Default

/-SL

10-44

SWITCHES

SP
10.1.32

/SP -- Spool Map Output

File
Memory allocation (map)

Syntax
file.TSK,file.MAP/~SP=file.OBJ

Description
This switch determines whether TKB calls the print spooler
spool your memory allocation (map) file after task build.

Effect
By default, when you specify a map file
in a TKB command
sequence, TKB creates a map file on device SYO:
and then has the
file queued for listing on LPO:.
If you negate this switch (as shown in the Syntax section above),
TKB creates the map file on device SYO: but does not call the
print spooler to output it to LPO:

Default
/SP
NOTE

The PRT task must be installed
to
process the request to print the map.

10-45

SWITCHES

SQ
10.1.33

/SQ -- Sequential

File
Task image

Syntax
file.TSK/SQ=file.OBJ

Description
This switch causes TKB to construct your task image from the
program sections you specified, in the order that you input them.

Effect
If you use this switch, TKB collects all the references to a
given program section from your input object modules, groups them
according to their access code (RW followed by RO)
and, within
these groups, allocates memory for them in the order that you
input them.
However, the /SG switch affects program section
ordering and can be used with the /SQ switch.
See the /SG switch
for further details.
Without the /SQ
alphabetically.

switch,

TKB

reorders

the

program

sections

You use this switch to satisfy any adjacency requirements that
existing code may have when you are converting it to run under
RSX-11.
Using this feature
is otherwise discouraged for the
following reasons:
•

Standard library routines
(such as FORTRAN I/O handling
routines and FCS modules from SYSLIB) do not work properly.

•

Sequential allocation can result in errors if
order in which modules are linked.

you

alter

the

Alternatively, you can achieve physical adjacency of program
sections by selecting names alphabetically to correspond to the
desired order.

Default
/-SQ

10-46

SWITCHES

SS
10.1.34

/SS -- Selective Search

File
Input
Syntax
file.TSK=file.OBJ,file.OBJ/SS
or
file.TSK=file.OBJ,file.STB/SS
or
file.TSK=tile.OBJ,file.OLB/LB/SS
Description
The /SS switch directs TKB to
include in its
internal symbol
table only those global symbols for which there is a previously
undefined reference.
Effect
When processing an input file,
TKB normally includes in its
internal symbol table each global symbol it encounters within the
file whether or not there are references to it.
With the /SS
switch attached to an input file, TKB checks each global symbol
it encounters within that file against its list of undefined
references.
If TKB finds a match, it includes the symbol in its
symbol table.
Default
/-SS
Example
Assume that you are building a task named SEL.TSK.
The task is
composed of input files containing global entry points and
references (calls) to them as shown in Table 10-2.
Table 10-2
Input Files for SEL.TSK
Input
File Name

Global Definition

INl

Global Reference
A

IN2

IN3
IN4

c
B

c
10-47

SWITCHES

SS (Cont.)
File IN2 and IN4 contain global symbols of the same name that
represent
entry points to different routines within their
respective files.
Assume that you want TKB to resolve the
reference to global symbol A in INl to the definition for A in
IN2.
Assume further that you want TKB to resolve the reference
to global symbol C in IN3 to the definition for C in IN4. By
selecting the sequence of the input files properly and applying
the /SS switch to files IN2 and IN4, TKB resolves the references
correctly.
The following command sequence illustrates
the
correct sequence:
TKB>SEL.TSK=IN1.0BJ,IN2.0BJ/SS,IN3.0BJ,IN4.0BJ/SS
TKB processes input files from left to right;
therefore,
in
processing the above command sequence, TKB processes file INl
first and encounters the reference to symbol A.
There is no
definition for A within INl;
therefore, TKB marks A as undefined
and moves on to process file IN2.
Because the /SS switch is
attached to IN2, TKB limits its search of IN2 to symbols it has
previously listed as undefined, in this case, symbol A.
TKB
finds a definition for A and places A in its symbol table.
Because there are no undefined references to symbols B or C, TKB
does not place either of these symbols in its symbol table.
NOTE
It is important to realize that the /SS
switch affects only the way the Task
Builder constructs its internal symbol
table.
The routines for which symbols B
and C are entry points is included in
the task image even though there are no
references to them.
TKB moves on to IN3.
It encounters the references to symbol C.
Because TKB did not include symbol C from IN2 in its symbol
table, it cannot resolve the reference to C in IN3.
TKB marks
symbol C as undefined and moves on to IN4.
When TKB processes IN4, it encounters the definition for C in
that file and includes it in the table.
Again, since the /SS
switch is attached to IN4, TKB includes only C in its symbol
table.
When TKB has completed
its processing of the above command
sequence,
it has constructed a task image composed of all of the
code from all of the modules, INl through IN4.
However, only
symbols A from
IN2 and C from IN4 will appear in its internal
symbol table.

10-48

SWITCHES

SS (Cont.)

NOTE
The example above does not represent
good
programming
practice.
It is
included here to illustrate the effect
of the /SS switch on TKB during a search
sequence.

The /SS switch is particularly valuable when used to limit the
size of the Task Builder's internal symbol table during the
building of a privileged task that references the Executive's
routines and data structures.
By specifying the Executive's
Symbol Definition File {STB) as an input file and applying the SS
switch to it, TKB includes in its internal symbol table only
those symbols in the Executive that the task references.
An
example of a TKB command sequence that illustrates this is shown
below:
TKB>OUTFILE.TSK/PR:S=INFILE.OBJ,RSXllM.STB/SS
The above command sequence directs TKB to build a privileged task
named
OUTFILE.TSK
from
the
input file INFILE.OBJ.
The
specification of the Executive's STB file as an input file with
the SS switch applied to it directs TKB to extract from
RSXllM.STB only those symbols for which there are references
within OUTFILE.TSK.

10-49

SWITCHES

TR
10.1.35

/TR -- Traceable

File
Task image
Syntax
file.TSK/TR=file.OBJ
Description
This switch directs TKB to make your task traceable.
Effect
TKB sets the T-bit in the initial PS word of your task.
When
your task is executed, a trace trap occurs when each instruction
is completed.
Default
/-TR

10-50

SWITCHES

WI
10.1.36

/WI -- Wide Listing Format

File
Memory allocation (map)
Syntax
file.TSK,file.MAP/-WI=fileeOBJ
Description
This switch controls the width of your map file.
Effect
By default, TKB formats a map file 132 columns wide.
When you
negate this switch (as in the Syntax section above), TKB formats
the map file 80 ~olumns wide.
Default
/WI

10-51

SWITCHES

_/,.

> ~

,· ::"(~ti-~·:)~"x8 .s~.i··i:c~· .1nto. rm~
• ·<ex·ternaT ·header·.
«

·>Y;'<:

•

··,,'

;

•

;i.ffe·ct:···.···.
hL an RSX-UM-PLUS system,
the effec.t. of the.. /XH switch . · is
·two-fold.:.
the header space Jn the task image is n.ot · d:estroy¢d
.when the .task is checkpointed;
and . Executive.· pool space is
conserved• . A ·task built with the /XH switch does·· not have· a
header in Ex-ecuti ve pool, but has a COJ?Y of its ~eader, which the.
Executive· rises, in space allocated physically contiguous.to and
below the task image. Wh_en the task is checkpointed, the system
writes the entire task image and the header copy below the task
into a checkpoint file.
The header in the task image is left
unchanged.

Note that if the task is also built with the /FP switch, the
floating-point save area is not included in the task image but is
in the header copy found below the task image.
Interaction with the INSTALL command:
On RSX-llM-PLUS, the INSTALL switch /XHR interacts with the TKB
switch /XH.
If you use /'"'.'XH, the task will have a pool-resident.
header always unless you rebuild the task to have an external
header.
If you use /XH, the task wi 11 hav·e an external heade·r,
but the INSTALL switch /XHR can override this. The defau:l t
use
of /XH by TKB is /XH (external header) unless this is changed by
the ;,INSTALL command •
Defaul~
. ~ ~ ..
'

'/Xff for RSX-llM"'."'PL.iJS;

.o"vet:ridden by /XHR. on INSTALL

10-52

SWITCHES

XT
10.1.38

/XT[:n] -- Exit on Diagnostic

File
Task image
Syntax
file.TSK/XT:4=filecOBJ
Description
This switch specifies the number of acceptable errors.
n errors are not acceptable.

More than

Effect
TKB exits after encountering n errors. The number of errors can
be specified as a decimal or octal number, using the convention:

indicates a decimal number
be included) •

in or n

indicates an octal number.

(the decimal

If you do not specify n, TKB assumes that n is 1.
Default
/-XT

10-53

point

must

CHAPTER 11
OPTIONS

11.l

OPTIONS

Task Builder options provide you with the means
information about the characteristics of your task.

give

TKB

These options, which are listed in Table 11-1, can be
seven
categories.
The
identifying
abbreviation
description of each category are listed below:

divided into
and a brief

•

contr

You use control options to affect TKB execution.
ABORT is the only member of this category. You can
direct the Task Builder to abort the task build
with this option.

•

ident

You use identification options to identify your
task's characteristics.
You can specify the name
of your task,
its priority, user identification
code, and partition with options in this category.

•

alloc

You use allocation options to modify your task's
memory
allocation.
With the options in this
category, you can change the size of your task's
stack
and
program sections.
When you write
programs in a high-level language, you can change
the size of your work areas and buffers and declare
the virtual base address and size of program
sections.
Finally, you can declare the number of
additional window blocks {if any)
that your task
requires.

•

You use storage-sharing options to indicate to TKB
that your task intends to access a shared region.

•

device

You use device-specifying options to specify the
number of units required by your task, and the
assignment of logical unit numbers to physical
devices.

•

alter

You use the content-altering options to define a
global symbol and value, or to introduce patches in
your task image.

•

synch

You use synchronous trap
synchronous trap vectors.

options

define

Some TKB options are of interest to all users of the system;
others
are of interest only to high-level language programmers; and still
others are of interest only to MACR0-11 programmers. Table 11-1 lists
all the options alphabetically, and gives a brief description of each.

11-1

OPTIONS
Table 11-1
Task Builder Options
Option

Meaning

lnterestl

Category

GBLXCL2

Declares global symbols to be
excluded from the .STB file

H,M

alter

LIBR

Declares task's intention to access
a memory-resident shared region

H,M

MAXBUF

Declares an extension to the FORTRAN
record buff er

alloc

ODTV

Declares the address and size of
the debugging aid SST vector

synch

PAR

Declares partition name and
dimensions

H,M

ident

PRI

Declares priority

H,M

ident

RE SC OM
RESLIB

Declare task's intention to access
a memory-resident shared region

H,M

alloc

,~~~~::f~~{e~f~~!~~l~t~;e;~~W1?
·.J?eC'l'ares :Pa.tt'ft'i'¢n,::~n :~hlch-" ~e~;<;f.;orili,,:;:':.i .:· .·
"p<:>r.tio'ri'..oe'_in\.rtt~i,u$.er.·::t:as:1{·Js:·.·.fo, . . i::~i?'iQ:e"' ..··./

STACK

Declares the size of the stack

~tt'I?t·1s2.:,

~~~~~~~!~~k;~~~i~~~~~;tt~;~f

TASK

Declares the name of the task

H,M

ident

TSKV

Declares the address of the task
SST vector

synch

UIC

Declares the user identification code
under which the task runs

H,M

ident

UNITS

Declares the maximum number of units

H,M

device

VSECT

Declares the virtual base address and
size of a program section

H,M

alloc

WNDWS

Declares the number of additional
address windows required by the task.

H,M

alloc

<,.."

1. The user interest range is indicated as follows:
•

H indicates options of interest to high-level
as FORTRAN) programmers~

language

•

M indicates options of interest to MACR0-11 programmers.

2. These options are appiicable to RSX-11M-PLOS syste!1ls only.

11-3

(such

OPTIONS

ABORT
11.1.l

ABORT -- Abort the Task-Build

You use the ABORT option when you discover that an earlier error
in
the terminal sequence causes TKB to produce an unusable task image.
The Task Builder, on recognizing the keyword
input and restarts for another task build.

ABORT,

stops

accepting

Syntax
ABORT=n
n

An integer value.
The integer is required to satisfy the general
form of an option; however, the value is ignored in this case.
Default
None
NOTE
If you type a CTRL/Z at any time,
it
causes TKB to stop accepting input and
begin building the task.
The ABORT option is the only correct way
for you to restart TKB if you discover
an error and decide you do not want the
Task Builder output.

11-4

OPTIONS

ABSPAT
11.1.2

ABSPAT -- Absolute Patch

You use the ABSPAT option to declare a series of object-level patches
starting at a specified base address.
You may use this option for
?o r1 vent i.°, n a 1 . or :]:1;c;~'?'c1/,:,q'7~~~S~;·:+'§~$,~~'.h/.r~,~,,{~\S,+~~<'/!~tl/~~Pi<ti,r~~~~9'/.J:~~~F:~,f
/~~~·~:~~:t:~:~1i'~f~t.lf9P:~:~~,;,,>'.~·1;~i}~/,~1:7'.13J2~~'~:: See the DSPPAT option.
You can
sp~cify up to eight patch values.
Syntax
ABSPAT=seg-name:address:vall:val2 ••• :val8
seg-name
The 1- to 6-character Radix-50 name of the segment.
address
The octal address of the first patch. The address can be on a
byte boundary;
however, two bytes are always modified for each
patch: the addressed byte and the following byte.
vall
An octal number in the range of 0 through 177777 to be stored
address.

An octal number in the range of 0 through 177777 to be stored
address+2

An octal number in the range of O through 177777 to be stored
address+l6.

val2

val8

NOTE
All patches must be within the segment
address limits or TKB generates the
following error message:

TKB--*DIAG*--Load address out of range in module name

11-5

OPTIONS

ACTFIL
11.1.3

ACTFIL -- Number of Active Files

You use the ACTFIL option to declare the number of files that your
task can have open simultaneously.
For each active file that you
specify, TKB allocates approximately 512 bytes.
If you specify less than four active files (the default), the ACTFIL
option saves space.
If you want your task to have more than four
active files, you must use the ACTFIL option to make the additional
allocation.
You must include a language Object Time System (OTS), such as FORTRAN,
and record I/O service routines (FCS or RMS-11) in your task image for
the extension to take place. The program section that is extended has
the reserved name $$FSR1.
Syntax
ACTFIL=f ile-max
file-max
A decimal integer indicating the maximum number of files that can
be open at the same time.
Default
ACTFIL=4

11-6

OPTIONS

ASG
11.1.4

ASG -- Device Assignment

The ASG option declares the physical device that is assigned to one or
more logical units.
Syntax
ASG=device-name:unit-numl:unit-num2 ••• :unit-num8
device-name
A 2-character alphabetic device name followed by a 1- or 2-digit
octal unit number.
If your task uses more than six logical
units, you must use the UNITS option to specify the number of
logical units that your task will use.
unit-numl
unit-num2

unit-num8
Octal integers indicating the logical unit numbers.
Default
ASG=SY0:1:2:3:4,TI0:5,CL0:6

11-7

OPTIONS

CLSTR
11.1.5

CLSTR -- System-Owned Cluster of Resident Libraries or Commons

The CLSTR option allows you to link your program to one to six shared
regions, such as FMS, RMS, FORTRAN or BASIC+2, with a minimum of lost
virtual address space for your task. CLSTR allows two to six shared
regions in an ,Rsx..:.i1M:; system or an RSX-UM-PLUS system to reside in
the same virtual address space in your task.
You use CLSTR to declare a cluster or group of system-owned, resident
libraries or commons that your task intends to access and have reside
at the same virtual address in the address space of your task.
The term "system-owned" means that TKB expects to find the commons or
libraries named in the option and the symbol table associated with
them under UFO [1,1] on device LB:.
Syntax
CLSTR=library_l,library_2, .•• library_n:switch:apr
library_n
The library names must be 1- to 6- character Radix-50 names. TKB
expects to find a symbol definition file of the same name for
each specified shared region under UFO [1,1] on device LB:.
The
first specification denotes the first or the default library,
which is the library to which the task is mapped when the task
starts up and remaps after any call to another library.
In an RS;X.:'.".'.1111, or ,ti~~;ll~m:i~,~~H~ system, the total number of
libraries to which a task may map is seven.
The number of the
component libraries in clusters is limited to a maximum of six.
A cluster must contain a minimum of two libraries.
It is
possible to have two clusters of three libraries each or three
clusters of two libraries each; any combination of number of
clusters and libraries must equal at least two or a maximum of
six.
If six libraries are used in clusters, the task may map to
only one other, separate library.
:switch
The switch :RW (read/write) or :RO (read-only) indicates the type
of access the task requires. All shared regions in the cluster
have the same type of access.

:apr
The apr is an integer in the range of 1 through 7 that specifies
the first Active Page Register (APR) that you want TKB to reserve
for the cluster of shared regions. You can specify it for a
cluster made up of only position-independent shared regions.
If
you omit the APR parameter and all shared regions are position
independent, TKB selects the highest available APR to map the
cluster. A cluster can be made up of both position-independent
and absolute shared regions.
If one absolute shared region is
present
with
position-independent
shared
regions,
the
position-independent shared regions assume the same base address
as that of the absolute shared region. However, if you specify
more than one absolute shared region, all must be built with the
same base address.

11-8

OPTIONS

CLSTR (Cont.)
Default
None
NOTE
All but the first shared region in a
cluster must be memory-resident overlaid
libraries.
The first shared
region
specified in the cluster option can be a
single-segment structure
(nonoverlaid)
or an overlaid library.

11-9

OPTIONS

CMPRT
11.1.6

(;MPRT -- Completion Routine _ _: RSX-llM-PLUS'Only

The CMPRT option is ava'ilable on RSX-llM-PLUS systems only.
You ' use,,
this opt,ion to identify a shared region as a supervisor-:mode library.
The ,CMPRT option r.equi res an argument, that speCi fies, the entr,y ·point
of the completion routine in the library. The completfon routine
swi tch'es the processor from supervisor to, user mode 'and , returns
program control to, the user· task after the supervis'or,-,mode libra:t:,Y
·subroutine that' was called from the' us·er task has executed. '
Two completion ro..utines are a~aila~ie i~ SYSLIB:
e

$CMPCS restores only the caxry bit: in the user'.""'mode PS.

•

$CMPAL restores all the condition code ·,bi ts in
PS.

the

user-mode,

These routines perform all the necessary overhead to switch the
processor from supervisor to user mode and return program control t'o
the user task at the instruction following
the
call
to
·a
supervisor-mode library subroutine.
Although you can write your own completion routines, it is best to use
either $CMPCS or $CMPAL whenever possible.
Chapter 8 discusses
completion routines in detail.
Syntax
CMPRT=name
name

A 1- to 6-character
routine.

Radix-50

name

Default
None

11-10

identifying

the

completion

OPTIONS

COMMON or LIBR
11.1.7

COMMON or LIBR -- System-Owned Resident Common or System-Owned
Resident Library

The COMMON and LIBR options are functionally identical;
they both
declare that your task intends to access a system-owned shared region.
However, by convention, the COMMON option identifies a shared region
that contains only data, and the LIBR option identifies a shared
region that contains only code.

· · · :·

(i,f ;:. . ~b~ ' IJSe:· th!S: :coM~,p:!i optfOJl '.' wJ',th :·an ,,:I~ ·. ,a'l)d ,: 8~sJ?ac~> :t~ sk', : ' :~p~ Pefllm~n
;i7 ~ .:Jlla,pp.e(J·,·;~i .t·n,·-:o;..s.pacef::~~»as· .'.~)'r\J.iy: a;n:a,:.:t:n,,e,re~.o·re ··~u~t .·c:q·n~a~n· ,:a~,t.q: 'ot:l-~Yt;..
~

•

;

' •

,-;;

.,..

•

,.,

•

,_.

_;~'

;·

;=':~

:fl//;6.~/~.us~.::'.~he,:;::i£·i~·~·/ppfi:~·rl :~l:t·ti'/~itJ::~'i·~. . . ~na ··.iLsp:~c~ . . t~s.k ,·.,the..·1iprarY: ·~s
":~~!:::r,~·~·f?p~O; i.i tP:',:·~~~h·, .:r ~s.i>ape ..ji}1a:"<ri~.~·l?A~,e,,·,Jp?R~.;~.· _;· ;: · . . · · · , : · ....· . .
· ," / ,·
The term "system-owned" means that TKB expects to find the common or
library named in the keyword and the symbol definition file associated
with it under UFD [1,1] on device LB:.
Syntax
COMMON=name:access-code[:apr]
or
LIBR=name:access-code[:apr]
name
The 1- to 6-character Radix-50 name specifying the common or
library.
TKB expects to find a symbol definition file having the
same name as that of the common or library with an extension of
.STB under [1,1] of device LB:.
access-code
The code RW (read/write) or the code RO
the type of access the task requires.

(read-only)

indicating

NOTE
A privileged task can change data in or move data to a
resident common even though the task has been linked to
the common with read-only access.

11-11

OPTIONS

COMMON or LIBR {Cont.)
apr
An integer in the range of 1 through 7 that specifies the first
Active Page Register (APR) that you want TKB to reserve for the
shared region.
TKB recognizes the APR only for a mapped system;
you can specify it only for position-independent shared regions.
If you omit the APR parameter and the shared region is position
independent, TKB selects the highest available APR to map the
region.
When a shared region is absolute, the base address of the
region -- and therefore the APR that maps it -- is determined by
the arguments in the PAR option when the region is built.
Refer
to PAR in Section 11.1.18.

Default
None

11-12

OPTIONS

DSPPAT
11.1.8

DSPPAT -- Absolute Patch for D-space

You use the DSPPAT option to declare a series o~ obj~ct'"".leyel . patches
~~artin,~ ····.at the·.··. spec, Hie~. ~~se. ad~~es.s. :·:I'n;l£~{oe~iFdti,:~'.fs:1yifqr;,'1lta;kf~M··
;~~~~f;!,~::f,~,.~·jE,t,;~lJQJ!.:i$.e~i(C~:~/1~;t'i.:~~:fL~~~:(~r:~~~q~l:~~~·~-~,·~F." 'Y:~u "''"·ffi~·Y·· · ·a1~·0 ·· il'sMe
this option to patch a conventional task at any location.
You can
specify up to eight patch values.
Syntax
DSPPAT=seq-name:address:vall:val2: ••• :val8
segname
The 1- to 6-character Radix-50 name of the segment.
address
The octal address of the first patch. The address can be on a
byte boundary;
however, two bytes are always modified for each
patch: the addressed byte and the following byte.
vall
An octal number in the range of 0 through 177777 to be stored
address.

An octal number in the range of 0 through 177777 to be stored
address+2.

an octal number in the range Of 0 through 177777 to be stored
address+l6.

val2

val8

NOTE
All patches must be within the segment address limits
TKB generates the following error message:

TKB--*DIAG*--Load address out of range in module-name

11-13

OPTIONS

EXTSCT
11.1.9

EXTSCT -- Program Section Extension

You use the EXTSCT option to extend a program section.
If the program section to be extended
(concatenated), TKB extends the section
specify in the EXTSCT option.
If the
attribute OVR (overlay), TKB extends the
you specify in the EXTSCT option is greater
program section.

has the attribute
CON
by the number of bytes you
program section has the
section only if the length
than the length of the

Syntax
EXTSCT=p-sect-name:extension

p-sect-name
A 1- to 6-character radix-50 name specifying the program
to be extended.

section

extension
An octal integer that specifies the number of bytes by
extend the program section.

which

Example
In the following example, the program section BUFF is
long.

200

bytes

EXTSCT=BUFF:250
The number of bytes by which TKB extends the program section BUFF
depends on the CON/OVR attribute:
•

For CON, the extension is 250 bytes.

•

For OVR, the extension is 50 bytes.

TKB extends the program section if it encounters
section
name in an input object file or in
description file.

Default
None

11-14

the
the

program
overlay

OPTIONS

'.ihe'.·EXTtfSK····~opti.on·' dir:ect~· ''th~· .:'S.ys'terii·· t(>>~ll~)~a,ti addltiontii•.Illemot.y:«:foi:
.'yotrt. ',-ba::sk,,.whenit::.i,~,".:in,s.taJi'eir.:i:h/a.· sy!?tem~«i.d.nc::t::'t9'ti~Jp~J;t·i·tio11~·".·:/. ·.· ....:· ·•
~

.,'<~.,"~

;',':.\'',.~,,:,= ';,,~'

. ~.

_,,,,, ,,' •'".: .,,·,,,.,

,' ~=

-;,,..'

;_.

=~:

'.,

.<,.

~~~

.'"

--l~ ~·

,·:

J ~~. ':

',:;'

,·'/

+~e·:;attt<;>~,;r~."Af': i,n~~~.r,:~ ··.~~<\ t. ·.t,ne ··,·~·Y:.:st~!TI·A1·i«~~~~:~·~: ·t,:~·t·:···ioui/:: . t,a,s.k,·:: <.is'·.· ·,t~~i··

.'"°S.\Jm' o.,f" .tlte. ·.;t·asli'.·.· s'iz~·::PI.us·,.,·the.· .,:*nc~em~nt ,.J~Qu,:"spe(ti·f:y: . ·.i(:bou~~d .up.· ..tdt?~be;;
J·~·ea~est·· :~2~w·<>~~··1'>.?:iindary)'··~·: .·· ·..tf:, }:.h~·:·ta:sk ..:. t~ ·.bu'.!, l·~.· ·.f·o·r,.:. ~·• . .~.~5;?r:..;cori.t,*·0·1~.ep'/
:oa.r:titi.on, './the ,·,,a.I1oca::J:ieon::·.::o,f· .. ·.task , .,,,!nemo:t.v: i,eve,i:'ts, to ,'.the ,part·i':td.t»r;i . .
'"~~,,z~·~t/.</f; ·:,:/' /,:«>,/,;
. ';"; ' ~;,·,',:.-:;;<
.'/,','·:"i"';':·,." ':;'i/"''.:;·... :/J ,;,,.::' ,'· .'.' .:',,:''/,<,'

'/;' .'

•

·<..

,'<'

. i:'

,,_;

.. ;

'°<i

i%~

·,;rn,-"a·

'~:">'.>'~'.::~:/''
<~i»

, When ·:~b:>u ,',use.:':tbe. · · :E;XTTSK, ·qpt ton '.::.t(f

~~~4/:,~~~}}~~~~~~g:~~f~f·:~~;

.rw.i tn ·'t:n·e :. .JAL' :.swtl:cn ; . . '.fhe·".:cHec:J<' '·t?«iirit:
". 't.Iie.:,:·\f. itl'lJn:.:t:n~· .'t'a$·~ ..·,image.,/.i·s', .the·.·
·'s fze
:. , ,<)t,' · ,·t:11e:.::
.t·a's·]{:'. 'icis,;: bhe .$'1·z~' i'Qf ·"
f~~-»
-? / .- . "' ,' ' ~- "'_."....:.; _. _, ,~P, / "';.
~ , .~
=~
~
_;, / "

:;.;1,,..m,/ "'

,."<

_, ,,,,

t .'"' ,_

'«< "_,

..·.•the .·exbended,.,·task ,::area;·'·'

_ .... .::;.

,'.: "";

l1};:~~(s~~Ni"l~~~·;~4~~ .-~-:~'1/i~.: .a11<(...:, _../

/ . ~ .:: ' o.:·~e·q.c~, ,.' ;' J:;a $}<: /,: j:h,a.~ ::, )'' :: •. l) n k~d' i;o : .~; t ","
,'l,.f,;o~·a:ry ·:;wli;i'~h.,/ ,'~'c>'ri t~1i,h~1"' 1b'ot:'f)J ,:iJ«a.,f;. a; ,. 'a.nd""; :;' /
/

! •

~~~,,'i~ijij~tf~~Si~;fii;1~~§/

.i nta ·the .area :·mapp~d,. fo.r ··thE? · Hpi:a'ry :
, ,"or ·.•'th.e·/:1lbra':t.y·' ". ·w111"·, be.·,mapped .fl{i: .· .

."I-space ·only •.. ·

Syntax.

EXTT$K=lerigth
.length
A decimal n:umber
in the rang.e O<n<65, 535.
increase in task memory allocation (in words).

speci fyfog

the·.

Default
The task is extended to the size specified in the PAR option (see
Section 11.1.18).
11-15

OPTIONS

FMTBUF
11.1.11

FMTBUF -- Format Buffer Size

The FMTBUF option declares the length of the internal working storage
that you want TKB to allocate within your task for compiling format
specifications at run time.
The length of this area must equal or
exceed the number of bytes in the longest format string to be
processed.
Run-time compilation occurs whenever an array is referred to as
source of formatting information within a FORTRAN I/O statement.
program section that TKB extends has the reserved name $$0BF1.

the
The

Syntax
FMTBUF=max-format

max-format
A decimal integer, larger than the default, that specifies
number of characters in the longest format specification.

Default
FMTBUF=l32

11-16

the

OPTIONS

GBLDEF.
11.1.12

GBLDEF -- Global Symbol Definition

You use the GBLDEF option
symbol.

declare

the

definition

TKB considers this symbol definition to be absolute.
definition in your input object modules.

global

It overrides any

Syntax
GBLDEF=symbol-name:symbol-value
symbol=name
A 1- to 6-character Radix-50 name of the defined symbol.

symbol-value
An octal number in the range of 0 through 177777 assigned to
defined symbol.

Default
None

11-17

the

OPTIONS

GBLINC
11.1.13

GBLINC -- Include Global Symbols

The GBLINC option directs the Task Builder to include the symbol or
symbols specified in this option in the .STB file being generated by
the link operation in which this option appears.
This option is
intended for use when creating shared regions, in particular shared
libraries, when you want to force particular modules to be linked to
your task that references this library. The global symbol references
specified by this option must be satisfied by some module or GBLDEF
specification when you build the task.
Syntax
GBLINC=symbol-name,symbol-name, •••• ,symbol-name
symbol-name
The symbol to be included.
Default
None

11-18

OPTIONS

GBLPAT
11.1.14

GBLPAT -- Global Relative Patch

The GBLPAT option declares a series of object-level patch values
starting at an offset relative to a global symbol.
You can specify up
to eight patch values.

Syntax
GBLPAT=seg-name:sym-name[+/-offset] :vall:val2 ••• :val8

seg-name
The l= to

6~character

Radix-50 name of the segment.

sym-name
A 1- to 6-character Radix-50 name specifying the global symbol.

off set
An octal number specifying the offset from the global symbol.

val!
An octal number in the range of 0 through 177777 to be stored
the octal address of the first patch.

An octal number in the range of 0 through 177777 to be stored
the first address+2.

An octal number in the range of 0 through 177777 to be stored
the first address+l4.

val2

val8

Default
None
NOTE
All patches must be within the segment
address limits or TKB generates a fatal
error.

11-19

OPTIONS

GBLREF
11.1.15

GBLREF -- Global Symbol Reference

The GBLREF option declares a global symbol reference.
The reference
originates in the root segment of the task. This keyword is used for
memory-resident overlays of shared regions.
Syntax
GBLREF=symbol-name,symbol-name ••• ,symbol-name
symbol-name
A 1- to 6-character name of a global symbol reference.
Default
None

11-20

OPTIONS

GBLXCL
11.1.16

GBLXCL -- Exclude Global Symbols

The GBLXCL option keyword directs TKB to exclude from the symbol
definition file of a shared region the syrnbol(s) specified in the
option.
Syntax

GBLXCL=symbol-narne,symbol-name ••• ,syrnbol-name
symbol-name

The symbol(s)

to be excludede

Default

None

11-21

OPTIONS

LIBR
11.1.17

LIBR -- System-Owned Library

Refer to COMMON in Section 11.1.7.

11-22

OPTIONS

MAXBUF
11.1.18

MAXBUF -- Maximum Record Buffer Size

The MAXBUF option declares the maximum record buffer size required for
any file used by the task.
If your task requires a maximum record size that exceeds the
buffer length, you must use this option to extend the buffer.

default

You must also include a language Object Time

such

System

(OTS),

FORTRAN, in your task image for the extension-to take place.
program section that is extended has the reserved name $$IOB1.

as
The

Syntax
MAXBUF=max-record
max-record
A decimal integer, larger than the default,
maximum record size in bytes.
Default
MAXBUF=l33

11-23

that

specifies

the

OPTIONS

ODTV
11.1.19

ODTV -- ODT SST Vector

The ODTV option declares that a global symbol is the address of the
CDT Synchronous System Trap vector. You must define the global symbol
in the main root segment of your task.
Syntax
ODTV=symbol-name:vector-length
symbol-name
A 1- to 6-character Radix-50 name of a global symbol.
vector-length
A decimal integer in the range of 1
length of the SST vector in words.
Default
None

11-24

through

specifying

the

OPTIONS

PAR
11.1.20

PAR -- Partition

The PAR option identifies the partition for which your task is built.
In a mapped system, you can install your task in any system partition
or user partition large enough to contain it.
In an unmapped system,
your task is bound to physical memory.
Therefore, you must install
your task in a partition starting at the same memory address as that
of the partition for which it was built.
Syntax
PAR=pname[:base:length]
pname
The name of the partition.
base
The octal byte address defining the start of the partition.
On
an unmapped system, the physical address must be specified.
On a
mapped system, the base must be 0 for a task or a 4K boundary for
a shared region.
length
The octal number of bytes contained in the partition.
In a mapped system, a length of
partition.

implies

system-controlled

If the target system is mapped and you specify a partition length
that is greater than the length of your task, the Task Builder
automatically extends the length of your task to match the length
of the partition.
This procedure is equivalent to using the
EXTTSK keyword to increase the task memory.
If your task size is
greater than the partition size that you specify, TKB generates
the following error message:
TKB--*DIAG*-Task has illegal memory limits
Whether or not the target system is mapped, the Task Builder does
not extend the length of a
shared region, or any task built
without a header, to match the specified partition length.
If you do not specify the base and length, TKB tries to obtain that
If
information from the system on which you are building your task.
you have specified a partition that resides in that system, TKB can
obtain the base and length.

11-25

OPTIONS

PAR {Cont.)
TKB binds the task to the addresses defined by the partition base.
If
the partition is user controlled, TKB verifies that the task does not
exceed the length specification.

'mti~~:~fa7~~~1,~J~~{~$~i;1tH!t~~~~~~t!~t~t'.~,~
Default
PAR= GEN

11-26

OPTIONS

PRI
11.1.21

PRI -- Priority

The PRI option declares your task's execution priority.
On systems with multiuser protection, you cannot run a task at a
priority that is greater than the system priority (50) unless it is
installed or run from a privileged terminal.
If you are working from
a privileged terminal, and you do not override this option by
specifying a different priority when you install your task 1 the system
uses this priority.
Syntax
PRI=priority-number
priority-number
A decimal integer in the range of 1 through 250
Default
Established by Install;
refer
Operations Reference Manual.

11-27

the

RSX-llM/M-PLUS

MCR

OPTIONS

RESCOM or RESLIB
11.1.22

RESCOM or RESLIB -- Resident Common or Resident Library

The RESCOM and RESLIB options are functionally identical;
they both
declare that your task intends to access a user-owned, shared region.
However, by convention the RESCOM option identifies a shared region
that contains only data and the RESLIB option identifies a shared
region that contains only code.

The term "user-owned" means that the resident common or library and
the symbol definition file associated with it can reside under any UFD
that you choose.
You can specify the UFD and remaining portions of
the file specification for both options.
You must not place comments
on the same line with either option.
Syntax
RESCOM=file-specification/access-code[:apr]
or
RESLIB=file-specification/access-code[:apr]
file-specification
The memory image file of the resident common or resident library.
The file specification format is discussed in Chapter 1.
access-code
The code RW {read/write) or the code RO
the type of access required by the task.

(read-only),

indicating

NOTE
A privileged task can change data in or move data into a
resident common even though the task has been linked to
the common with read-only access.
apr
An integer in the range of 1 through 7 that specifies the first
Active Page Register (APR) that you want TKB to reserve for the
common or library.
TKB recognizes the APR argument only for a
mapped system.
You can specify it only for position-independent
shared regions.
If the APR parameter is omitted and the shared
region is position independent, TKB selects the highest available
APR to map the region.
When a shared region is absolute,
the base address of the
region -- and therefore the APR that maps it -- is determined by
~ne arguments in the PAR option when the region is built.
Refer
to PAR in Section 11.1.18.

11-28

OPTIONS

RESCOM or RESLIB {Cont.)
NOTES

The Task Builder expects to find a symbol definition
file having the same name as that of the memory image
file but with a file type of .STB, on the same device
and under the same UFD as that of the memory image
file.

Regardless of the version number you give in the file
specification, TKB uses the latest version of the
.STB file.

Default
When you omit portions of the file-specification,
defaults apply:
•

UFD - Taken from current terminal UIC

•

Device - SYO:

File type -

•

File version - Latest

.TSK

11-29

the

following

OPTIONS

RESLIB
11.1.23

RESLIB

Resident Library

Refer to RESCOM in Section 11.1.21.

11-30

OPTIONS

·.· <~ess·ut> ··
''·
,

~·

•

•••

~;; ,.. ~' ?,;·~}ii/~:!:'. '.i,
O;

~ > • .,

:'({4:;t::;;Ai~. JiEs·s.uP :--~ Re·s:id·e·ri.t' :sup7rviis.or--t-tpde: Libr.~iY. ~-. asx~ltr.t-P,Lus .. on.1y-::
~·/ ~ .

~·~n~·.·~&§:~·J;>::·:·.<?i>~~<?n:·:,·~ec1~·res .... ·th(l·(: :Y-<:>,ux •. task . intends.·· ~o · a9cess; .. ·'.a,./
:·'u'.se~;,-o~ed'r ·,sJ1perviso.I:;µwae···i.tprar.J:·~.·.·, .The ter:m. "use:r.:.:9wned": mean~:·~t:hat,···. .
Xn~;·.'.lJbr,a:ry;·,acyd,, th,~,· ~yiµbQl· ...de',fini:t.i,on . ,•fJ le.," ,ass~piat~d. wi~;h .. i~ . ,' ,q.a;-1 :~ ..
·.;~:$i5'~,9e(. ~,un~eF.:.' ··.~t:i'.li' . :. ·Vlf[) .:·. t,ha~.: yop ·<:hoose•.· ... Y<?p .c,arv Sf>~c1fy ·t~~ pE.D· .. q~d,··.·. ,·
I

·.r;·.·;P~~c~"'.{

;;~~~~~~~~!"iA,~;~;~1~~.~~~p~!~c·i·fl,ca~ i qµ. .· ...•¥9~····• .Jnn?~ .
'·Synt·a:x · .· ·

· ,, · . · . ·

· ·. ·

·:,.,,,,.,.~>, ', \ »·.·· ';'·.,.~.:,.,.,

."/·····«·>Rs

',,,•,•,

,'.':.

"··

uP~f·ii~-iJ·pec·i.frc'at'ion/·[~j,,s'vt':~pi,l ·"

',,'

· ,,': ·, ·

· .· · · ·

,:,·•.,

"·

<:<.'."

, ,·/ , '.,." , ,,::.,, ,,,.~,:

·:

,,:'/:,{".'.:"/·.,,' ."'<:: ","~,'?."'>',',~· /('::,,'
::. '.,,.'/'" ',:':,."·,. . ,: ,... :.'/,' \·':./,.:
;',/://";"'.(//::>,':,<?·~,~'/.::>,~:,:.
: .. ,' , ", ,
," /
, · ,. ." ·: . , .' '." , " : , · :, .
,,,f,i:·l:&Ts~,c1f,1cat1,on
~;"(

l:l:

.,,,.,

;,.

'« > :;::, <;: ,;- $::'

< ,

, ~

~ .,

~.,

;

~ /

~ ~

"'~ .,~

.....

«;};

<~ ~

., ~

:,',:~~,~:/~~~,~·;~:,,:f~,~:g~:. :.:~'i.:3:.~".\i ·.,~~~· :~~~er:~.i ~"~.~~in~~'e":,",.i {b:f~i,~·~ :": :~,,.::.!rli~ :::~,,~'{i'.~':)'..:

,s:,>;.>,'.~"\s.~e'.cJ/f.i:qa1t'i:'o.n'.: \":ha~", ",',the. ,:~"tza;i:t9i'ar.d, ,."Rs·~·-};lM~RS.~;-~'.l::~;-l?L.US· ,' ",'f3:~p:ffia,t,,>: ·,
r/. :',/,"'. '"'.d.fici
e<t i'ri ·,chapter L '
, '
'
·
"· ' "
· · · ',· ,' ', ", , /

~~;~i!~,~ti~p{~~~i;~~i~~r#~i~~ffa~>;t~=~~:tfr~i~~:~i~~1:~~f
i;~~;~~.
.....
:<<:'<'~<

i:~clp~,~·s·.".~· 4~~cfr·a/.'mo~·e-:~wi'ich.fng· yectbr ·.,~ftni·n'·u·'ftie . ·. "ad'.ar~ss:·~.:*"::

;,:·.",:..,>:: .sP·?lce:· ~.,£'.th~·. us~i "ta;.;·1{ .f.or' each cpl(· to. a .. sµpei:visor~m~~~ :'.1f~:r;,~j.:·y::~.

·. . :.·>·:;<·:";·~·u~.~·~'u;.~tne/:·'.;'..U:. ·:y:q,tj ·.·speq.iJy:· .:·/--;S'f,.; ....:;y,9u · .. ·µiH.~·t .·:; ,p·r',ov·~<I.e. ·. ·::y,.o,.q,~· . :..... o~ri ,,./·.

·'. ,,, '/"./.m'ode-..switching . veGt<lr,,.. .·Pr.qvidi ng..y6ur · own. moae.;.,switcliing'. 're«::t"o,:rf(· ·::
,:??'.:;:::?:1}:f;,:::~s:e·£ti':t>:'..~::~;:.,yoti.lf:.·1·~r?~~i'y,::,:<;,r3·1'\:~.~·.~,.n~:l":~.:!'.::h:r~.aq~9-:. .<~:~<?~.:~.:J. ·r.~ ..,::·~;s.;:::Jf.~~.~. ;;,..c·.:~:~··):.:,~
" ",J ;:· •· u.s.e . :th.e. s.y:s·~em-suppl··1ed w·ectors .wben.e.ver. poss1 ble
, .: , . , , ,·,

·~~({f{'~~;:>f~~:.~\?/?//. ;. ·. . . ·.~. ·.' . (?.:·..... .. . · ,:.':.·. ' , . . ?f.~:(.~:
· / ?·~ ·t·:'.:·,":~a

:.···.

"1:."i/ ,,' ,, '·.. ~,uP:e, .

) v ,~ '

,e:c:·.,,"JiO:./ tbe,/.:tr .

. ... Oi,·iJl· ..tJ:l.z;o,99·h, . ·;7:':thc;}t: . ·spe:c.1:f·1.e):~"/A:he/.:· .f..:i::x:st/.,./

· , '",.:'7A'c):'.J·:V:e:<P· .· . :. . ~,e<J.ts·ti'et<"t'lia~.~.··t:(H.r":w·~·rit··:·:rtB\:frt:·i~ei;e):Y.e:2' . "~"./;"'

,,.

:,.

; ,,

~' ~
••

-'The· 'T~!sk ·B~ilder·: ·~~i;>ects 'to· fin:a: a· :symbol

definition

hle havfo<J ·the same .name as that ·Of .t~e memory<. image

flle but with a file· type of .STB', on the same device
and under the same. UFD a.s that of the memory, image
file.
2~

Regardless of the version numbez you give in the file
specification; .TKB uses the latest version of the
• STB file •.

11-31

OPTIONS

11-32

OPTIONS

11-33

OPTIONS

STACK
11.1.26

STACK -- Stack Size

The STACK option declares the maximum size of the
your task.

stack

required

The stack is an area of memory that the MACR0-11 programmer uses for
temporary storage, subroutine calls, and synchronous trap service
linkage. The stack is referred to by hardware register 6
(SP, the
stack pointer) .
Syntax
STACK=stack-size
stack-size
A decimal integer specifying the number of words required for the
stack.
Default
STACK=256

11-34

OPTIONS

SUPLIB
ll~i.27 .SUPLIB-- Supervisor-Mode Library -- RSX-llM-PLUSOnly
·.T1:1fs:, op~io!l declares th.(it. your· task intend$ to access a. system-owned,
slJ;pervisor-mode library •... Th.e . term 0 system 7 owned" mearis that TKB
expects to find the supervisor-mode library. and the symbol definition
f.i.1¢. ,assoeiated w:lth it 'in UFO [ 1 ;'iJ on device LB:.
''

.·:.'.~ut?t1s;name::1..::J $VC :apr:1·
'
·~

;, '.

' l

.·· The.··1.: to 6-char ac.te.r Rad i,x·:-50. ti~me 'spec,i ~ying the system-o'wned .,
ve:·. ·.·.s~p'erv.~'so::.'"":rrto:ae libr~ry. .TKB' expec·ts.· to find a symbol de.f.inition
/'.:
/.f'.l:l'e.Jiaving.· ,the. sarri~ nain·e .a·s· t{lat, o·f the ·horar.y · witp. .a·· file
..:.,.:y·e·rs.i©n of •. S.TB· un¢ier. [l.,lJ of device LB:•.
· ·
'

f[:...J.SV'
...
/'
;

.:The· · c·oae /SV.· or . ;...;.sv· to. indi,c.ate
.whether
TKB
includes
':·ro.od·e:...swttchfng Vectors withi.n the user task.
H you specify /SV,
· · TKB.. iocl.udes. a 4.-word. mode-swi tchin.g vector within
the address.
' ~pace~bf.~h~·user ta~k fbi each call td a supervisor-mode libiary
· .s.ubroutine. If you specify /-SV, you must provide your own mode ...
· ;·. s.wi.tch,ing . vector..
Prqviding your own mode-switching vec.tors is
. use fut i f you'r 'library contains threaded code •. It 'is best to use
, ,tJ~-~. sy$t~xp.-sllpplied vectors whenever possi~le ~

ppr,
n>

'"'

~n.1nteger in ih~ range of d fhr~ugh 7 that specifies the fir~t
·sl1I>er\1·isor . ~ct~v~ . . ~age .. Regis'ter that' .TKB Ts to reserve for the
l,:il;kary". : ¥ou. can J3p.ecify· an APR..on'ly for. position-ind'ependent,
'supervisor-mode
, ;< ; ,

i Ai'-R~~

.librari~s.

. Th.e de·fault is the .lowest availa·qle

rphe: .lib:t;a,ry .·at virtual 0 must have the CSM dispatche.r present in
,· . :th~ system~sl.rgpljed c,otnple.tion routine described in Chapter 8.
·De.fault

None

11-35

OPTIONS

TASK
11.1.28

TASK -- Task Name

The TASK option gives your task an installed name different
task image name.

from

its

Syntax
TASK= task-name
task-name
A 1- to 6-character name identifying your task.
Default
The first six characters of the task image file name identify the
task when the task is installed.

11-36

OPTIONS

TSKV
11.1.29

TSKV -- Task SST Vector

The TSKV option declares that a global symbol is the address of the
task Synchronous System Trap (SST} vector.
You must define the global
symbol in the main root segment of your task.

Syntax
TSKV=symbol-name:vector-length

symbol-name
A 1- to 6-character name of a global symbol.

vector-length
A decimal integer in the range of 1
length of the SST vector in words.

Default
None

11-37

through

specifying

the

UIC
11.1.30

UIC -- User Identification Code

The UIC option declares the User Identification Code
(UIC)
task when you run it with a time-based schedule request.

for

your

Syntax
UIC=[group,member]
group
An octal number in the range of 1 through 377, or a decimal
number in the range of 1 through 255. Decimal numbers must be
followed by a decimal point (.).
member
An octal number in the range of 1 through 377, or a decimal
number in the range of 1 through 255. Decimal numbers must be
followed by a decimal point (.).
Default
The UIC that the Task Builder
terminal UIC).

11-38

running

under

(normally

the

OPTIONS

UNITS
11.1.31

UNITS -- Logical Unit Usage

The UNITS option declares the number of logical units that
uses.

your

task

Syntax
UNITS=max-units

max-units
A decimal integer in the range of 0 through 250 specifying the
maximum number of logical units. A 2-word block is allocated in
the task's header for every logical unit. A task that uses many
logical units can use a significant portion of dynamic memory
because the header is in dynamic memory when the task is
executing. The /XH switch affects pool usage by the task header.

Default
UNITS=6

11-39

OPTIONS

VSECT
11~1~32

VSECT -- Virtual Program Section

The VSECT option specifies the virtual base address, virtual length,
and, optionally,
the physical memory allocated to the named program
section.
Refer to Chapter 5 for more information on virtual program
sections.
Syntax
VSECT=p-sect-name:base:window[:physical-length]
p-sect-name
A 1- to 6-character program section name.
base
An octal value representing the virtual base address of the
program section in the range of 0 through 177777.
If you use the
mapping directives, the value you specify must be a multiple of
4K.
window
An octal value specifying the amount of virtual address space in
bytes allocated to the program section.
Base plus window must
not exceed 177777 (octal).
physical-length
An octal value specifying the m1n1mum amount of physical memory
to be allocated to the section in units of 64-byte blocks.
TKB
rounds this value up to the next 256-word limit.
This value,
when added to the task image size and any previous allocation,
must not cause the total to exceed 2048K bytes.
If you do not
specify a length, TKB assumes a value of O.
Default
Physical-length defaults to O.

11-40

OPTIONS

WNDWS
11.1.33

WNDWS -- Number of Address Windows

The WNDWS option declares the number of address windows required by
the task in addition to those needed to map the task image, and any
mapped array or shared region. The number specified is equal to the
number of simultaneously mapped regions the task will use.
Syntax
WNDWS=n
n

Default
WNDWS=O

11-41

APPENDIX A
TASK BUILDER INPUT DATA FORMATS

An object module is the fundamental unit of input to the Task Builder
(TKB).
You create an object module by using any of the standard
language processors (for example, MACR0-11 or FORTRAN) or by using TKB
itself
{symbol definition file).
The RSX-llM/M-PLUS librarian (LBR)
gives you the capability to combine a number of object modules into a
single library file.
An object module consists of variable-length records of
information
that describe the contents of the module.
These records guide TKB in
translating the object language into a task image.
Six record (block)
types are included in the object language~
•

Declare global symbol directory (GSD)

record

(type 1)

•

End of global symbol directory {GSD)

record

(type 2)

•

Text information (TXT)

•

Relocation directory (RLD)

•

Internal symbol directory {ISO)

•

End-of-module record

record

(type 3)

record

(type 4)

record (type 5)

(type 6)

TKB requires at least five of these record types
in each object
module.
The only record type that it does not require is the internal
symbol directory.
The various record types are defined according to a prescribed format,
as
illustrated in Figure A-1.
An object module must begin with a
declare-GSD record and end with an end-of-module record.
Additional
declare-GSD records can occur anywhere in the file, but must occur
before an end-of-GSD record.
An end-of-GSD record must appear before
the end-of-module record,
and at least one RLD record must appear
before the first TXT record.
Additional RLD and TXT records can
appear anywhere in the file.
The ISD records can appear anywhere in
the file between the initial declare-GSD record and the end-of-module
record.
Object module records are variable length and are identified by a
record type code in the first byte of the record.
The format of
additional information in the record depends on the record type.

A-1

TASK BUILDER INPUT DATA FORMATS
The following sections describe each of the six record types
greater detail.
The outline of these sections is as follows:
A.l
A.1.1
A. l. 2
A. l. 3
A. l. 4
A. l. 5

A.1.6
A.l. 7
A. l. 8
A. l. 9

A.2
A.3
A.4
A.4.1
A.4.2
A.4.3
A.4.4
A.4.5
A.4.6
A.4.7
A.4.8
A.4.9
A.4.10
A.4.11
A.4.12
A.4.13
A.4.14
A.4.15
A.5
A.6

A.l

Declare Global Symbol Directory Record
Module Name (Type 0)
Control Section Name (Type 1)
Internal Symbol Name (Type 2)
Transfer Address (Type 3)
Global Symbol Name (Type 4)
Program Section Name (Type 5)
Program Version Identification (Type 6)
Mapped Array Declaration (Type 7)
Completion Routine Name (Type 10)
End of Global Symbol Directory Record
Text Information Record
Relocation Directory Record
Internal Relocation (Type 1)
Global Relocation (Type 2)
Internal Displaced Relocation (Type 3)
Global Displaced Relocation (Type 4)
Global Additive Relocation (Type 5)
Global Additive Displaced Relocation (Type 6)
Location Counter Definition (Type 7)
Location Counter Modification (Type 10)
Program Limits (Type 11)
Program Section Relocation (Type 12)
Program Section Displaced Relocation (Type 14)
Program Section Additive Relocation (Type 15)
Program Section Additive Displaced Relocation
Type 16)
Complex Relocation (Type 17)
Resident Library Relocation (Type 20)
Internal Symbol Directory Record
End of Module Record

DECLARE GLOBAL SYMBOL DIRECTORY RECORD

The global symbol directory (GSD) record contains all the information
required by TKB to assign addresses to global symbols and to allocate
the virtual address space required by a task.
GSD records are the only records processed by TKB in its first pass;
therefore, you can save substantial time by placing all GSD records at
the beginning of a module (because the Task Builder has to read less
of the file) •
GSD records contain nine types of entries:

• Module name (type 0)
• Control section name (type 1)
• Internal symbol name (type 2)
• Transfer address (type 3)

• Global symbol name (type 4)

A-2

TASK BUILDER INPUT DATA FORMATS
•

Program section name (type 5)

•

Program version identification (type 6)

•

Mapped array declaration (type 7)

•

Completion routine name (type 10)
TASK BUILDER DATA FORMATS

GSD

Initial Declare GSD

RLD

Initial Relocation Directory

GSD

Additional GSD

TXT

Text Information

TXT

Text Information

RLD

Relocation Directory

GSD

Additional GSD

•
•

END GSD

End of GSD

ISD

Internal Symbol Directory

ISD

Internal Symbol Directory

TXT

Text Information

TXT

Text Information

TXT

Text Information

END MODULE

End of Module

ZK-444-81

Figure A-1

General Object Module Format

As
Each entry type is represented by four words in the GSD record.
shown in Figure A-2, the first two words contain six Radix-50
characters, the third word contains a flag byte and the entry type
identification, and the fourth word contains additional information
about the entry.

A-3

TASK BUILDER INPUT DATA FORMATS
A.1.1

Module Name (Type 0)

The module name entry (two words) declares the name of the object
module.
The name need not be unique with respect to other object
modules (that is, modules are identified by file,
not module name) ,
but only one such declaration can occur in any given object module.
Figure A-3 illustrates the module entry name format.
RECORD
TYPE

RAD50
NAME
ENTRY TYPE

FLAGS
VALUE
RAD50
NAME

TYPE

FLAGS
VALUE

•
•
•
RAD50
NAME

TYPE

FLAGS

VALUE
RAD50
NAME

TYPE

FLAGS

VALUE
ZK-445-81

Figure A-2

Global Symbol Directory Record Format
MODULE
NAME (2 WORDS)
ENTRY = O
TYPE

0
ZK-446-81

Figure A-3

Module Name Entry Format

A-4

TASK BUILDER INPUT DATA FORMATS

A.1.2

Control Section Name (Type 1)

Control sections, which include absolute sections (ASECTs}, blank, and
named control sections
(CSECTs) , are replaced in RSX-llM by program
sections
(PSECTs).
For compatibility with other
systems,
TKB
processes ASECTs and both forms of CSECTs. Section A.1.6 details the
entry generated for a .PSECT directive.
ASECTs and CSECTs are
follows:

defined

terms

For a blank CSECT, a program section is
attributes:

.PSECT

defined

with

directives,
the

following

.PSECT ,LCL,REL,CON,RW,I,LOW
For a named CSECT, the program section is defined as:
.PSECT name, GBL,REL,OVR,RW,I,LOW
For an ASECT, the program section is defined as:
.PSECT . ABS.,GBL,ABS,I,OVR,RW,LOW
TKB processes ASECTs and CSECTs as program sections with the fixed
attributes defined above. Figure A-4 illustrates the control section
entry name format.
CONTROL SECTION
NAME (2 WORDS)
ENTRY
=
TYPE

IGNORED

MAXIMUM LENGTH
ZK-447-81

Figure A-4

A.1.3

Control Section Name Entry Format

Internal Symbol Name (Type 2)

The internal symbol name entry (two words) declares the name of an
internal symbol
(with respect to the module). TKB does not support
internal symbol tables; therefore, the detailed format of this entry
is undefined.
If TKB encounters an internal symbol entry while
reading the GSD, it ignores that entry. Figure A-5 illustrates the
internal symbol name entry format.
SYMBOL
NAME (2 WORDS)
ENTRY
=
TYPE

UNDEFINED
ZK-448-81

Figure A-5

Internal Symbol Name Entry Format

A-5

TASK BUILDER INPUT DATA FORMATS
A.1.4

Transfer Address (Type 3)

The transfer address entry declares the transfer address of a module
relative to a program section.
The first two words of the entry
define the name of the program section, and the fourth word defines
the relative offset from the beginning of that program section.
If a
transfer address is not declared in a module, then a transfer address
must not be included in the GSD, or a transfer address of 000001
relative to the default absolute program section
(.
ABS.)
must be
specified. Figure A-6 illustrates the transfer address entry format.
NOTE
If the program section is absolute,
the
off set is the actual transfer address
(if not 000001).

SYMBOL
NAME (2 WORDS)

ENTRY
TYPE == 3

OFFSET
ZK-449-81

Figure A-6

A.1.5

Transfer Address Entry Format

Global Symbol Name (Type 4)

The global symbol name entry declares either a global reference or a
definition.
Definition entries must appear after the declaration of
the program section in which the global symbols are defined and before
the declaration of another program section
(see Section A.1.6).
Global references can be used anywhere within the GSD.
As shown in Figure A-7, the first two words of the entry define the
name of the global symbol. The flag byte of the third word declares
the attributes of the symbol, and the fourth word defines the value of
the symbol relative to the program section in which the symbol is
defined.
SYMBOL
NAME (2 WORDS)
ENTRY
TYPE

FLAGS

VALUE
ZK-450-81

Figure A-7

Global Symbol Name Entry Format

Table A-1 lists the bit assignments of the flag
declaration entry.

A-6

byte

the

symbol

TASK BUILDER INPUT DATA FORMATS
Table A-1
Symbol Declaration Flag Byte -- Bit Assignments
Bit Number and Name
0

Weak

qualifier

Setting

Meaning

The symbol
has
a
strong
definition and is resolved in
the normal manner.

The
symbol
has
a
weak
definition or reference.
TKB
ignores a weak reference
(bit
3
0).
It also ignores a
weak definition (bit 3
1)
unless a previous reference
has been made=
Not used.

1
2

Definition or
reference type

Definition

definition
Normal
reference.

Library definition.
If the
defined
in
a
symbol
is
resident library STB file, the
base address of the library is
added to the value and the
to
symbol
is
converted
absolute
(bit 5 is reset);
otherwise, the bit is ignored.

Global symbol reference.

Global symbol definition.
Not used.

4
5

Relocation

Absolute symbol value.

Relative symbol value.

Not used.

A.1.6

Program Section Name (Type 5)

The program section name entry declares the name of a program section
and its maximum length in the module.
It also uses the flag byte to
declare the attributes of the program section.

A-7

TASK BUILDER INPUT DATA FORMATS
You must construct GSD records such that once a program section name
has been declared, all global symbol definitions pertaining to it must
appear before another program section name is declared.
Global
symbols are declared with symbol declaration entries. Thus, the
normal format is a series of program section names each followed by
optional symbol declarations.
Figure A-8 illustrates the program
section name entry format.

PROGRAM SECTION
NAME

ENTRY
TYPE

= 5

FLAGS

MAXIMUM LENGTH
ZK-451-81

Figure A-8

Program Section Name Entry Format

Table A-2 lists the bit assignments of the flag byte
section name entry.

the

program

Table A-2
Program Section Name Flag Byte -- Bit Assignments
Bit Number and Name
0

Save

Library program
section

Allocation

Setting

Meaning

Normal program section.

The program section is forced
into the root of the task.

Normal program section.

The
program
section
relocatable
and refers
shared region.

is
a

Program section references are
to be concatenated with other
references to the same program
section to form the total memory
allocated to the section.

Program section references are
to
be
overlaid.
The total
memory allocated to the program
section is the largest request
made by individual references to
the same program section.
(continued on next page)

A-8

TASK BUILDER INPUT DATA FORMATS
Table A-2 (Cont.)
Program Section Name Flag Byte -- Bit Assignments
Bit Number and Name

Setting

Meaning
Not used;
reserved
DIGITAL use.

Access

Relocation

Scope

Type

for

future

The
program
section
read/write access.

has

The
program
section
read-only access.

has

The program section is absolute
and requires no relocation.

The
program
section
is
relocatable and references to
the control section must have a
relocation
bias added before
they become absolute.

The scope of the program section
is local.
References to the
same
program
section
are
collected
only
within
the
segment in which the program
section is defined.

The scope of the program section
is
global.
TKB
collects
references
to
the
program
section
across
segment
boundaries.
The Task Builder
determines the segment in which
storage is allocated
for
a
global program section either by
the first module that defines
the program section on a path,
or by direct placement of a
program section in a segment
using the ODL .PSECT directive.

The program section
contains
instruction (I) references.

The program section
data (D) references.
NOTE

The length of all absolute
0.

A-9

sections

contains

TASK BUILDER INPUT DATA FORMATS
A.1.7

Program Version Identification (Type 6)

The program version identification entry declares the version of the
module. TKB saves the version identification of the first module that
defines a nonblank version.
It then includes this identification on
the memory allocation map and writes the identification in the label
block of the task image file.
The first two words of the entry contain the version identification.
The flag byte and fourth words are not used and contain no meaningful
information.
Figure
A-9
illustrates
the
program
version
identification entry format.

SYMBOL
NAME
ENTRY
TYPE

= 6

0
ZK-452-81

Figure A-9

A.1.8

Program Version Identification Entry Format

Mapped Array Declaration (Type 7)

The mapped array declaration entry allocates space within the mapped
array area of task memory. The array name is added to the list of
task program section names and may be referred to by subsequent RLD
records.
The length
(in units of 64-byte blocks) is added to the
task's mapped array allocation. The total memory allocated to each
mapped array is rounded up to the nearest 512-byte boundary. The
contents of the flag byte are reserved and assumed to be 0.
One additional window block is allocated whenever a
declared.

mapped

array

Figure A-10 illustrates the mapped array declaration entry format.

MAPPED ARRAY
NAME
ENTRY
TYPE

FLAGS

LENGTH (NUMBER OF 64-BYTE BLOCKS)
ZK-453-81

Figure A-10

Mapped Array Declaration Entry Format

A-10

TASK BUILDER INPUT DATA FORMATS

',,,,t:, ,,} "',(/ /

')~,~,J.,:,9',., ',,¢0,~p;1-~tto:n, ',Routine, Defin'i'tioh '(Ty,pe ',lQJ,

-~h~- ~~mplei:iot\
routin~ il~fsupervisor.,.n\pde,
i~i tl ~n dee ~a re~. lil,>rary'!'
t~e . entiY.
Jp.;i;~~ :, fK{:S~~~
,i;ou,1:,ine,,of',
.. ' •Thfs. .
j :, '

co~,p~e.tio,n,"
',',?l,
,'qat:.a:'e'st;i'.tjq,6u+:e~,
J.$·'.'C!rE?~te~, py. <tll~ '.!'ask '8ui lde;r and ai;>pears Oniy in"~<$Ymh()l. ·''Q~fi"tj'$'t:J,~fi)
f i'le's, <»f' supe.rvi.sor--mode Ubrar ie.s.
, ,
'
<:, , , ·,~. ; , "" ,
~~·

..,' -~

' ; .,·,

,,,' .. ,.. !;,;' :"'

,. t

'}\"s',,~hq~~ '',,fti ~.i,gure, ~~11,,' the''' n:rf;t.' . ,t\>la,··,~ords'· . ,of.·,t:he','etjtr;~''"'.:.·~':f'~'~!~:,•-,,';'.~~~::.
",name' . .· O'f ,the 'enti::y, poirit,: . The third 'wo,rd' corit<;tinS' .:f'.h.e' "enl=:r,,¥;'' ~;ype," l'jyt~'.,:'
and. t;b'e.·fia«J, .hyte,., 'The,:fiag, byte contail)~',"no ,meanirigFiaJ:';'·;in~q:l;·Il)a~l?~~;{'
,T'.i:(e'::'fo,u+'.,t;n:,>~~:rr¢1. CO?,t~,lns:, t:11~ .fi:~bqJ,, ,v,~fye •. ' , .i ,,,_, ,<: ,./ .' /, '>."/:.:::'// "~,~<:>":««:.;·>:):
COMPLETION ROUTINE
NAME

rnTRY
TYPE

VALUE
ZK-454-81

A.2

END OF GLOBAL SYMBOL DIRECTORY RECORD

The end of global symbol directory (end-of-GSD) record declares that
no other GSD records are contained further on in the module. There
must be exactly one end-of-GSD record in every object module.
As
shown in Figure A-12, this record is one word long.
RECORD
TYPE

2
ZK-455-81

Figure A-12

A.3

End of Global Symbol Directory Record Format

TEXT INFORMATION RECORD

The text information (TXT)
record contains a byte
string
of
information that is to be written directly into the task image file.
The record consists of a load address followed by the byte string.
TXT records can contain words and/or bytes of information whose final
contents have not yet been determined. This information will be bound
by a relocation directory record that immediately follows the text
record {see Section A.4). If the TXT record needs no modification,
then no relocation directory record is needed.
Thus, multiple TXT
records can appear in sequence before a relocation directory record.
The load address of the TXT record is specified as an offset from the
current program section base.
At least one relocation directory
record must precede the first TXT record. This directory must declare
the current program section.

A-11

TASK BUILDER INPUT DATA FORMATS
TKB writes a text record directly into the task image file and
computes the value of the load address minus 4.
This value is stored
in anticipation of a subsequent relocation directory that modifies
words and/or bytes contained in the TXT record. When added to a
relocation directory displacement byte, this value yields the address
of the word and/or byte to be modified in the task image.
Figure A-13 illustrates the TXT record format.
RECORD
TYPE

LOAD ADDRESS
TEXT

TEXT

•
•
•

TEXT

TEXT
ZK-456-81

Figure A-13

A.4

Text Information Record Format

RELOCATION DIRECTORY RECORD

The relocation directory
(RLD)
record contains the
information
necessary to relocate and link the preceding TXT record.
Every module
must have at least one RLD record that precedes the first TXT record.
The first RLD record does not modify a preceding TXT record;
rather,
it defines the current program section and location.
RLD records
contain 15 types of entries, classified as relocation or location
modification entries:
•

Internal relocation (type 1)

•

Global relocation (type 2)

•

Internal displaced relocation (type 3)

•

Global displaced relocation (type 4)

A-12

TASK BUILDER INPUT DATA FORMATS
•

Global additive relocation (type 5)

•

Global additive displaced relocation (type 6)

•

Location counter definition (type 7)

•

Location counter modification (type 10)

•

Program limits (type 11)

•

Program section relocation (type 12)

•

Program section displaced relocation (type 14)

•

Program section additive relocation (type 15)

•

Program section additive displaced relocation (type 16)

•

Complex relocation (type 17)

•

Resident library relocation (type 20)

Each type of entry is represented by a command byte that specifies the
type
of
entry and the word/byte modification, followed by a
displacement byte, and then by the information required for the
particular type of entry. The displacement byte, when added to the
value calculated from the load address of the preceding TXT record
(see Section A.3), yields the virtual address in the image that is to
be modified.
Table A-3 lists the bit assignments of the command byte
entry.

each

RLD

Table A-3
Relocation Directory Command Byte -Bit Assignments
Bit Number and Name
0-6

Entry type

Modification

Meaning

Setting

Potentially, 128 command types
can be specified; currently,
15 are implemented.

The command modifies an entire
word.

The command modifies only one
for
byte.
TKB
checks
truncation errors
in
byte
If
modification
commands.
(that
truncation is detected
is,
if the modification value
is greater than 255), an error
occurs.

Figure A-14 illustrates the RLD record format.

A-13

TASK BUILDER INPUT DATA FORMATS

RECORD
TYPE

0
DISP

CMD

INFO

•

INFO

DISP

CMD

INFO

DISP

CMD

INFO

I
l

"'-

INFO

INFO
ZK-457-81

Figure A-14

A.4.1

Relocation Directory Record Format

Internal Relocation (Type 1)

The internal relocation entry relocates a direct pointer to an address
within a module.
TKB adds the current program section base address to
a specified constant, and writes the result into the task image file
at the calculated address (that is, a displacement byte is added to
the value calculated from the load address of the preceding text
block).

A-14

TASK BUILDER INPUT DATA FORMATS
For example:

MOV

#A,RO
or

.WORD

Figure A-15 illustrates the internal relocation entry format.

DISP

ENTRY
TYPE

CONSTANT
ZK-458-81

Figure A-15

A.4.2

Internal Relocation Entry Format

Global Relocation (Type 2)

The global relocation entry relocates a direct pointer to a global
symbol.
TKB obtains the definition of the global symbol and writes
the result into the task image file at the calculated address.
For example:
MOV

#GLOBAL,RO
or

.WORD

GLOBAL

Figure A-16 illustrates the global relocation entry format.

ENTRY
TYPE

DISP

SYMBOL
NAME
ZK-459-81

Figure A-16

A.4.3

Global Relocation Entry Format

Internal Displaced Relocation {Type 3)

The internal displaced relocation entry relocates a relative reference
to an absolute address from within a relocatable control section. TKB
subtracts the address plus 2 that the relocated value is to be written
into from the specified constant, and writes the result into the task
image file at the calculated address.
For example:
CLR

177550
or

MOV

177550,RO

A-15

TASK BUILDER INPUT DATA FORMATS
Figure A-17
format.

illustrates

the

internal

displaced

ENTRY
TYPE

DISP

relocation

entry

CONSTANT
ZK-460-81

Figure A-17

A.4.4

Internal Displaced Relocation Entry Format

Global Displaced Relocation (Type 4)

The global displaced relocation entry relocates a relative reference
to a global symbol. TKB obtains the definition of the global symbol;
subtracts the address plus 2 that the relocated value is to be written
into from the definition value;
and writes the result into the task
image file at the calculated address.
For example:
CLR

GLOBAL
or

MOV

GLOBAL,RO

Figure A-18 illustrates the global displaced relocation entry format.

ENTRY
TYPE

DISP

SYMBOL
NAME
ZK-461-81

Figure A-18

A.4.5

Global Displaced Relocation Entry Format

Global Additive Relocation (Type 5)

The global additive relocation entry relocates a direct pointer to a
global symbol with an additive constant. TKB obtains the definition
of the global symbol;
adds the specified constant to the definition
value;
and writes the result into the task image file at the
calculated address.
For example:
MOV

#GLOBAL+2,RO
or

.WORD

GLOBAL-4

Figure A-19 illustrates the global additive relocation entry format.

A-16

TASK BUILDER INPUT DATA FORMATS

ENTRY
TYPE

DISP

SYMBOL
NAME (2 WORDS)
CONSTANT
ZK-462-81

Figure A-19

A.4.6

Global Additive Relocation Entry Format

Global Additive Displaced Relocation (Type 6)

The global additive displaced relocation entry relocates a relative
reference to a global symbol with an additive constant. TKB obtains
the definition of the global symbol; adds the specified constant to
the definition value; subtracts the address plus 2 that the relocated
value is to be written into from the resultant additive value;
and
writes the result into the task image file at the calculated address.
For example:
CLR

GLOBAL+2
or

MOV

GLOBAL-5,RO

Figure A-20 illustrates the global additive displaced relocation entry
format.

DISP

ENTRY
=
TYPE

SYMBOL
NAME (2 WORDS)
CONSTANT
ZK-463-81

Figure A-20

A.4.7

Global Additive Displaced Relocation Entry Format

Location Counter Definition (Type 7)

The location counter definition entry declares a current program
section and location counter value.
TKB stores the control base as
the current control section; adds the current control section base to
the specified constant; and stores the result as the current location
counter value.
Figure A-21 illustrates the location counter definition entry format.

A-17

TASK BUILDER INPUT DATA FORMATS

ENTRY =
TYPE

PROGRAM SECTION
NAME (2 WORDS)
CONSTANT
ZK-464-81

Figure A-21

A.4.8

Location Counter Definition Entry Format

Location Counter Modification {Type 10)

The location counter modification entry modifies the ~urrent location
counter.
TKB adds the current program section base to the specified
constant and stores the result as the current location counter.
For example:
.=.+N
or
.BLKB
Figure A-22
format.

N
illustrates

the

location

counter

ENTRY
TYPE

modification

entry

CONSTANT
ZK-465-81

Figure A-22 Location Counter Modification Entry Format

A.4.9

Program Limits (Type 11)

The program limits entry is generated by the
.LIMIT assembler
directive.
TKB obtains the first address above the header (normally
the beginning of the stack) and the highest address allocated to the
task.
It then writes these two addresses into the task image file at
the calculated address and at the calculated address plus
2,
respectively.
For example:
.LIMIT
Figure A-23 illustrates the program limits entry format.

A-18

TASK BUILDER INPUT DATA FORMATS

ENTRY
TYPE

DISP

11
ZK-466-81

Figure A-23

A.4.10

Program Limits Entry Format

Program Section Relocation (Type 12)

The program section relocation entry relocates a direct pointer to the
beginning address of another program section (other than the program
section in which the reference is made) within a module.
TKB obtains
the current base address of the specified program section and writes
it into the task image file at the calculated address.
For example:
.PSECT A
B:

.PSECT C
MOV #B,RO
or
.WORD B
Figure A-24 illustrates the program section relocation entry format.

ENTRY
TYPE

DISP

PROGRAM SECTION
NAME (2 WORDS)
ZK-467-81

Figure A-24

A.4.11

Program Section Relocation Entry Format

Program Section Displaced Relocation (Type 14)

The program section displaced relocation entry relocates a relative
reference to the beginning address of another program section within a
module. TKB obtains the current base address of the specified program
section;
subtracts the address plus 2 that the relocated value is to
be written into from the base value; and writes the result into the
task image file at the calculated address.

A-19

TASK BUILDER INPUT DATA FORMATS
For example:
.PSECT A

.PSECT C
MOV B,RO
Figure A-25 illustrates the program section displaced relocation entry
format.

DISP

ENTRY
=
TYPE

PROGRAM SECTION
NAME (2 WORDS)
ZK-468-81

Figure A-25

A.4.12

Program Section Displaced Relocation Entry Format

Program Section Additive Relocation (Type 15)

The program section additive relocation entry relocates a direct
pointer to an address in another program section within a module.
TKB
obtains the current base address of the specified program section;
adds this address to the specified constant;
and writes the result
into the task image file at the calculated address.
For example:
.PSECT A

.PSECT D
MOV #B+lO,RO
MOV #C,RO
or
.WORD B+lO
.WORD C
Figure A-26 illustrates the program section additive relocation
format.

A-20

entry

TASK BUILDER INPUT DATA FORMATS

DISP

I B

ENTRY
=
TYPE

PROGRAM SECTION
NAME (2 WORDS)
CONSTANT
ZK-469-81

Figure A-26

Program Section Additive Relocation Entry Format

Program Section Additive Displaced Relocation (Type 16)

A.4.13

The program section additive displaced relocation entry relocates a
relative reference to an address in another program section within a
module. TKB obtains the current base address of the specified program
section;
adds this address to the specified constant;
subtracts the
address plus 2 that the relocated value is to be written into from the
resultant additive value; and writes the result into the task image
file at the calculated address.
For example:
.PSECT A
B:

.PSECT D
MOV B+lO,RO
MOV C,RO
Figure A-27 illustrates
relocation entry format.

DISP

the

program

1Bl

section

ENTRY
=
TYPE

additive

di placed

PROGRAM SECTION
NAME (2 WORDS)
CONSTANT
ZK-470-81

Figure A-27

Program Section Additive Displaced Relocation
Entry Format

A-21

TASK BUILDER INPUT DATA FORMATS
A.4.14

Complex Relocation (Type 17)

The complex relocation entry resolves a complex relocation expression.
Such an expression is one in which any of the MACR0-11 binary or unary
operations are permitted with any type of argument, regardless of
whether the argument is an unresolved global symbol;
is relocatable
to any program section base;
is absolute;
or is a
complex
relocatable subexpression.
The RLD command word is followed by a string of numerically specified
operation codes and arguments.
The operation codes each occupy one
byte. The entire RLD command must fit
in a single record.
The
following 15 operation codes are defined:
•

No operation

Byte 0

•

Addition (+)

Byte 1

•

Subtraction (-)

•

Multiplication (*) -- Byte 3

•

Division (/)

Byte 2

Byte 4

-- Byte 5
• Logical AND
• Logical inclusive OR ( ! ) -- Byte 6
(&)

• Negation

(-)

-- Byte 10

• Complement ( "'C) -- Byte 11
• Store result (command termination)
result
displaced
with
• Store
termination)
Byte 13

Byte 12
relocation

(command

•

Fetch global symbol -- Byte 16 (It is followed by four
containing the symbol name in Radix-50 representation.)

•

Fetch relocatable value -- Byte 17 (It is followed by one byte
containing
the
program
section number, and two bytes
containing the offset within the program section.)

•

Fetch constant -- Byte 20
containing the constant.)

•

Fetch resident library base address -- Byte 21 (If the file is
a resident library STB file,
the library base address is
obtained; otherwise, the base address of the task image is
fetched.)

(It

followed

The STORE commands indicate that the value is to be written
task image file at the calculated address.

two

into

bytes

the

All operands are evaluated as 16-bit signed quantities using two's
complement arithmetic.
The results are equivalent to expressions that
the assembler evaluates internally. The following rules should be
noted:
1.

An attempt to divide by 0 yields a 0 result.
The
Builder issues a nonfatal diagnostic error message.

A-22

Task

TASK BUILDER INPUT DATA FORMATS

All results are truncated from the left to fit into 16 bits.
No diagnostic error message is issued if the number is too
large.
If the result modifies a byte, TKB checks for
truncation errors as described in Section A.4.

All operations are performed
absolute 16-bit quantities.
the result only.

on relocated
(additive)
or
PC displacement is applied to

For example:
.PSECT

ALPHA

.PSECT

BETA

MOV

#A+B-Gl/G2&AC177120!G3>>,Rl

Figure A-28 illustrates the complex relocation entry format.
DISP

l Bl

ENTRY
TYPE

COMPLEX STRING

12
ZK-471-81

Figure A-28

A.4.15

Complex Relocation Entry Format

Resident Library Relocation (Type 20)

The library relocation entry relocates a direct pointer to an
within a resident library.

address

If the current file is a resident library symbol definition file
(STB), TKB obtains the base address of the library;
adds this address
to the specified constant;
and writes the result into the task
image
file at the calculated address.
If the file is not associated with a
resident library, TKB uses the task base address.
Figure A-29 illustrates the library relocation entry format.

ENTRY
TYPE

DISP

CONSTANT
ZK-472-81

Figure A-29

Resident Library Relocation Entry Format

A-23

TASK BUILDER INPOT DATA FORMATS
A.5

INTERNAL SYMBOL DIRECTORY RECORD

Internal symbol directory (ISO)

records have two purposes:

To pass information to symbolic debuggers via the .STB file

To create autoload vectors dynamically for the
of the library

entry

points

TBK looks for global symbol definitions in the input object modules
and
looks for !SD records if /DA is specified;
otherwise TKB ignores
the !SD records.
Some !SD records require no relocation and TKB can
copy
them
directly into the
.STB file.
Others will require
modification;
after being modified, they can be written to the
.STB
file.
In addition, TBK may need to generate some !SD records of its
own in the .STB file.
Except for autoloadable library entry points, TBK puts !SD records
into the
.STB file only if the /DA switch is used in the TKB command
line. When TKB outputs the .STB file, it writes three major types of
ISO records:
•

Type 1 records, TKB generated ISDs.
is language independent.

The form of these records

•

Type 3 records, written for any type 2 records
in an input
object module.
TKB does this after adding data and then
changing the type to 3.
Type 2 relocatable/relocated records
are those that contain both language dependent and independent
sections.
Language processors generate these records and TKB
modifies them.
They contain information that can be used to
find
the absolute task
image address of source program
entities (variables, program statements, etc.)

•

Type 4 records, written to the .STB file without modification.
Type 4 records are literal records that contain language
dependent information.
Apart from the first
few bytes, TKB
ignores the rest of the record.

These record formats are described in the following sections.

A.5.1

Overall Record Format

!SD records have the same basic structure as all object
records.
Because of the variety of different types, the
structure must include additional fields that are common to
record types.
The general
format of all ISO records is
Figure A-30.

A-24

language
skeleton
all
ISO
shown in

TASK BUILDER INPUT DATA FORMATS

8 7

MUST BE 0

RECORD TYPE = 5

RESERVED (0)

ISO RECORD TYPE

RECORD TYPE DEPENDENT

ZK-1058-82

Figure A-30

General Format of All ISO Records

ISO record types fall into general categories.

A.5.2

The categories are:

•

Illegal.

•

TKB-generated.

•

Compiler-generated relocatable.

•

Relocated (type 2 after TKB processing) •

•

4-127 -- not defined and reserved for future use.

•

128-255 -- literal records;
the type code identifies
generating language processor and the internal structure.

the

TKB Generated Records (Type 1)

The content of this record type is a string of individual items, each
with its own format.
The items are either start-of-segment items,
task identification items, or autoloadable entry point items. The TKB
generated record is similar to the structure of an RLO or GSO record.
The general format is shown in Figure A-31.
15

8 7
LENGTH (BYTES)

0
ITEM TYPE

CONTENT DEPENDS ON ITEM TYPE
ZK-1059-82

Figure A-31

General Format of a TKB Generated Record

A.5.2.1 Start-of-Segment Item
Type
(1) - The
start-of-segment item type is shown in Figure A-32.

A-25

format

the

TASK BUILDER INPUT DATA FORMATS

8 7

15
LENGTH= 8

0
ITEM TYPE= 1

SEGMENT NAME

SEGMENT DESCRIPTOR ADDRESS
ZK-1060-82

Figure A-32

Format of TKB Generated Start-of-Segment Item (1)

A.5.2.2 Task Identification Item Type (2) - The task identification
item type ensures that a .STB file and the task image being debugged
were generated at the same time.
Otherwise, symbols that are found
may not correspond to the actual task.
The task identification item type exists to make the correlation
between the .STB file and its related task possible. The contents of
this item type correspond exactly to the first ten words of an area in
a task image file, which is in the TKB created PSECT called $$DBTS.
The format of the task identification item type
A-33.

8 7

15
LENGTH= 22.

shown

Figure

0
ITEM TYPE= 2

EIGHT-WORD TIME STAMP 1
TWO-WORD NUMBER 2

1. Its form is that which is returned by RSX-11 M/M-PLUS directive
GTIM$.
2. TKB generates this number as an additional check on correspondence. Currently always zero.
ZK-1061-82

Figure A-33

Format of TKB Generated Task Identification Item (2)

A.5.2.3 Autoloadable Library Entry Point Item Type (3) - TKB outputs
the autoloadable library entry point item into a .STB file when
building overlaid resident libraries.
The ISD record contains, the
needed information for TKB to dynamically generate autoload vectors
for entry points in the library. Autoload vectors appear only for
those entry points that are referenced by the task.
Unlike the other
item types, the autoloadable library entry point item is not for use
by debuggers.

A-26

TASK BUILDER INPUT DATA FORMATS
The format of the autoloadable entry point item
A-34 ..

8 7

15
LENGTH= 12.

shown

Figure

0
ITEM TYPE= 3

SYMBOL
NAME

FLAGS BYTE

ENTRY POINT OFFSET FROM LIBRARY BASE
SEGMENT DESCRIPTOR OFFSET IN $$SGD1

ZK-1062-82

Figure A-34

A.5.3

Format of an Autoloadable Library Entry Point Item (3)

Relocatable/Relocated Records (Type 2)

These records are the central part of TKB's involvement in debugger
communication.
Every item type in these records must be standardized,
and only standard
items can appear.
The
general
format
of
relocatable/relocated records is the same as that shown in Figure
A-30.
A language processor outputs these record types as type 2.
When TKB
processes them,
it changes the type to type 3.
It also fills in or
modifies some fields.
In the descriptions of following
item types,
fields that are filled
in by TKB are marked with an asterisk (*).
They should be left as zero in language processor output.

A.5.3.1 Module Name Item Type (1) - A module name item should be the
first ISD entry of each object module.
A debugger can assume that all
following ISD information up to the next module name item relates to
this module.
The language code is included so that a debugger for a specific
language can determine whether to ignore a module if it is written for
another language. The language code has the same range of values as
that of a language-dependent ISD record (128-255) and has the same
meaning.
The format of the module name item type is shown in Figure A-35.

A-27

TASK BUILDER INPUT DATA FORMATS

8 7

LENGTH

ITEM TYPE= 1

MUST BE 0

LANGUAGE CODE

MODULE NAME 1

1. A counted ASCII string of the required length. A counted ASCII
string is a byte string in which the first byte indicates the number of
bytes to follow.
ZK-1063-82

Figure A-35

Format of a Module Name Item Type (1)

A.5.3.2 Global Symbol Item Type (2) - One type 2 item must appear for
each global symbol definition that the language processor wants the
debugger to understand.
It need not, however,
include definitions
generated for the language processor run-time system.
The format of the global symbol item type is shown in Figure A-36.
8 7

LENGTH

0
ITEM TYPE= 2

SYMBOL NAME
(RADIX-50)

VALUE*
DESCRIPTOR ADDRESS FOR CONTAINING
OVERLAY SEGMENT*
MUST BE ZERO

FLAGS

FULL SYMBOL NAME 1

1. Counted ASCII string of the required length. A counted ASCII
string is a byte string in which the first byte indicates the number of
bytes to follow.
ZK-1053-82

Figure A-36

Format of a Global Symbol Item Type (2)

A-28

TASK BUILDER INPUT DATA FORMATS
A.5.3.3 PSECT Item Type
(3) - A concatenated PSECT has two base
addresses:
one for
the whole PSECT, and another for the part of it
that belongs to this module.
It is the base address for the part that
belongs to this module that may be used by a debugger to convert local
symbol values to absolute addresses.
The segment descriptor address is necessary because PSECTs may move to
segments other than the one in which it was placed.
This address is
relevant to languages that provide semi-automatic overlay generation,
like COBOL-11.
This word may be zero if the PSECT has not moved to
another segment.
The flag word is a copy of the flag word built by TKB.
identification of VSECTs.

It allows

for

The full PSECT name may be needed for some languages.
The format of a PSECT item type is shown in Figure A-37e
15

8 7
LENGTH

0
ITEM TYPE= 3

PSECT NAME

1---

BASE ADDRESS OF PSECT IN THIS SEGMENT*
BASE ADDRESS OF PSECT FOR THIS MODULE*
LENGTH OF PSECT FOR THIS MODULE*
DESCRIPTOR ADDRESS FOR CONTAINING
SEGMENT*
FLAG WORD*
FULL PSECT NAME 1

1. A counted ASCII string of the required length. A counted ASCII
string is a byte string in which the first byte indicates the number of
bytes to follow.
ZK-1054-82

Figure A-37

Format of a PSECT Item Type

(3)

A.5.3.4 Line-Number or PC Correlation Item Type
(4) - This item
provides the information needed to translate a source line number into
a task image address, or a task image address into a
source line
number.
The format of a line-number or PC correlation item type
Figure A-38.

A-29

shown

TASK BUILDER INPUT DATA FORMATS

8 7

LENGTH

0
ITEM TYPE= 4

PSECT

t--

NAME
START PC 1
DESCRIPTOR ADDRESS OF CONTAINING OVERLAY SEGMENT*
START PAGE NUMBER
START LINE NUMBER
STRING OF ONE-BYTE ITEMS
1. Offset into PSECT in type 2 records; absolute address in type 3 records.
ZK-1055-82

Figure A-38

Format of a Line-Number or PC Correlation Item Type (4)

A.5.3.5 Internal Symbol Name Item Type (5) - The internal symbol name
item allows for the fact that a name may have more than one associated
address. For example, a COBOL variable may have three associated
addresses:
the address of the area that contains the data, the
address of a CIS descriptor, and the address of a picture string.
The internal symbol name item is shown in Figure A-39.

A.5.4

Literal Records {Type 4)

Literal records may take any form, but the two-byte
Figure A-40 must be present.

A.6

header

shown

END OF MODULE RECORD

The end-of-module record declares the end of an object module.
There
must be exactly one end-of-module record in every object module. As
shown in Figure A-41, this record is one word long.

A-30

TASK BUILDER INPUT DATA FORMATS

8 7

LENGTH

ITEM TYPE= 5

OFFSET TO NAME

OFFSET TO DATA

MUST BE ZERO

NUMBER OF ADDRESSES
PSECT

ADDRESS 1:

NAME
TASK IMAGE ADDRESS/OFFSET 1
SEGMENT DESCRIPTOR ADDRESS*
PSECT

ADDRESS 2:

NAME
TASK IMAGE ADDRESS/OFFSET (1)
SEGMENT DESCRIPTOR ADDRESS*

•

ADDRESS n:

•

•
•

•

LANGUAGE-DEPENDENT DATA
SYMBOL NAME 2

1. Modified by TKB
2. A counted ASCII string of the required length. A counted ASCII
string is a byte string in which the first byte indicates the number of
bytes to follow.
ZK-1056-82

Figure A-39

Format of an Internal Symbol Name Item Type (5)
15

8 7
RESERVED (0)

ISD RECORD TYPE

ZK-1057-82

Figure A-40

Format of a Literal Record Type

A-31

TASK BUILDER INPUT DATA FORMATS

RECORD
TYPE

6
ZK-473-81

Figure A-41

End-of-Module Record Format

A-32

APPENDIX B
DETAILED TASK IMAGE FILE STRUCTURE

Figures B-1 through B-4 illustrate how the Task Builder (TKB)
records
a
task image on disk.
As noted in the following sections, parts of
the task disk image shown in these figures are optional and may not be
recorded for every task image.
The following sections, which provide detailed information on the task
image file structure, are organized as follows:
B.l
B.2
B.3
B.3.1
B.3.2
B.4
B.4.1

Label Block Group
Checkpoint Area
Header
Low-memory Context
Logical Unit Table Entry
Task Image
Autoload Vectors for Conventional Tasks

B.4.3
B.4.4
B.4.5
B.4.6

Task-Resident Segment Descriptor
Window Descriptor
Region Descriptor
Supervisor-Mode Vector

~"~,f~:,~::2,?~_;'~lt~~lp'.;<:1:d:~Y~Rt~,,i;'.§;~j'¥9;. ,;r,J~,·~~~~',.~i·~~~i.~~tj~~:i;;

B.l

LABEL BLOCK GROUP

The label block group precedes the task on the disk and contains data
that is needed by the system to install and load a task but need not
reside in memory during task execution. This group consists of three
parts:
•

Task and resident library data (label block 0)

•

Table of LUN assignments (label blocks 1 and 2)

•

The segment load list (label block 3)

Table B-1 describes the task and resident library data.
Figure B-5
illustrates how TKB organizes this data in label block O.
The INSTALL
processor verifies the task and resident library data when entering
the tasks into the System Task Directory (STD) file.
You can obtain
the offsets shown in Figure B-5 by calling the LBLDF$ macro that
resides in macro library LB:[l,l] EXEMC.MLB.

B-1

DETAILED TASK IMAGE FILE STRUCTURE

LABEL BLOCK 0 - TASK AND
RESIDENT LIBRARY DATA

RELATIVE DISK BLOCK 0

LABEL BLOCK 1 - TABLE OF
LUN ASSIGNMENTS
RELATIVE DISK BLOCK 2

LABEL BLOCK 2 - TABLE OF
LUN ASSIGNMENTS (OPTIONAL)

•
•

CHECKPOINT AREA
(OPTIONAL)

•

TASK HEADERFIXED PART

LABEL BLOCK GROUP

HEADER

TASK HEADERVARIABLE PART

ROOT SEGMENT
TASK CODE AND DATA

TASK IMAGE

ZK-1064-82

Figure B-1

Image on Disk of Non-Overlaid Conventional Task

RELATIVE DISK BLOCK 0

LABEL BLOCK 0 - TASK AND
RESIDENT LIBRARY DATA

RELATIVE DISK BLOCK 1

LABEL BLOCK 1 - TABLE OF
LUN ASSIGNMENTS

RELATIVE DISK BLOCK 2

LABEL BLOCK 2 - TABLE OF
LUN ASSIGNMENTS (OPTIONAL)

•
•
•

CHECKPOINT AREA
(OPTIONAL)

LABEL BLOCK GROUP

TASK HEADERFIXED PART
HEADER
TASK HEADERVARIABLE PART
ROOT SEGMENT
~-----------------------I

[r-

OVERLAY RUN-TiME
SYSTEM ROUTINES IN
ROOT FOR LIBRARY
AUTOLOAD VECTORS

OVERLAY DATA BASE

REGION DESCRIPTORS
.....
SEGMEN ....I Dc::SCR1PTORS

WINDOW DESCRIPTORS

---

TASK IMAGE

-JJ
ZK-1065-82

Figure B-2

Image on Disk of Conventional Non-Overlaid Task
Linked to Overlaid Library

B-2

DETAILED TASK IMAGE FILE STRUCTURE

RELATIVE DISK BLOCK 0 - LABEL BLOCK 0 - TASK AND
RESIDENT LIBRARY DATA
RELATIVE DISK BLOCK 1 - LABEL BLOCK 1 - TABLE OF
LUN ASSIGNMENTS

LABEL BLOCK GROUP

RELATIVE DISK BLOCK 2 - LABEL BLOCK 2 - TABLE OF
LUN ASSIGNMENTS (OPTIONAL)
RELATIVE DISK BLOCK 3 - -

•
••

LABEL BLOCK 3 - SEGMENT
LOAD LIST (OPTIONAL)
CHECKPOINT AREA
(OPTIONAL)

TASK HEADERFIXED PART

HEADER

TASK HEADERVARIABLE PART
ROOT SEGMENT

r---------------OVERLAY RUN-TIME
SYSTEM ROUTINES IN ROOT
AUTOLOAD VECTORS
1---

----1

REGION DESCRIPTORS
OVERLAY DAT A BASE

1---

--t

SEGMENT DESCRIPTORS
1---

----t

WINDOW DESCRIPTORS
OVERLAY SEGMENT 1
1---

TASK IMAGE
---i

AUTOLOAD VECTORS

,___

OVERLAY SEGMENT 2
---1

AUTOLOAD VECTORS

OVERLAY SEGMENT N
AUTOLOAD VECTORS

ZK-1066-82

Figure B-3

Image on Disk of Conventional Overlaid Task

B-3

DETAILED TASK IMAGE FILE STRUCTURE

RELATIVE DISK BLOCK 0

LABEL BLOCK 0 -

LABEL BLOCK 1 -

RELATIVE DISK BLOCK 1

TABLE OF LUN ASSIGNMENTS

LABEL BLOCK GROUP

LABEL BLOCK 2 TABLE OF LUN ASSIGNMENTS (OPTIONAL)

RELATIVE DISK BLOCK 2
RELATIVE DISK BLOCK 3

•
•

TASK AND RESIDENT LIBRARY DATA

LABEL BLOCK 3 -

SEGMENT LOAD LIST (OPTIONAL)
~

CHECKPOINT AREA (OPTIONAL)
TASK HEADER (UNUSED COPY) FIXED PART

---------------TASK HEADER (UNUSED COPY) VARIABLE PART
TASK ROOT -

TASK ROOT
I-SPACE PART

INSTRUCTION SPACE

AUTOLOAD VECTORS -

I-SPACE PART

TASK HEADER (USER'S COPY) FIXED PART

---------------TASK HEADER (USER'S COPY) VARIABLE PART
TASK STACK AREA
TASK ROOT -

TASK ROOT
D-SPACE PART

DATA SPACE

AUTOLOAD VECTORS -

D-SPACE PART

-------------- - ----------------------------- -REGION DESCRIPTORS

SEGMENT DESCRIPTORS
WINDOW DESCRIPTORS

TASK IMAGE

..,__

OVERLAY SEGMENT 1 AUTOLOAD VECTORS -

I-SPACE

I-SPACE PART

---------------OVERLAY SEGMENT 1 -

D-SPACE

AUTOLOAD VECTORS -

D-SPACE PART

OVERLAY SEGMENT 2 -

I-SPACE

-- ------------OVERLAY SEGMENT 2 - D-SPACE
..,__
AUTOLOAD VECTORS - D-SPACE PART
AUTOLOAD VECTORS -

I-SPACE PART

•
••

•
••
OVERLAY SEGMENT N AUTOLOAD VECTORS -

OVERLAY SEGMENT N AUTOLOAD VECTORS -

I-SPACE

I-SPACE PART
D-SPACE

D-SPACE PART
ZK- 1 067-82

Table B-1
Task and Resident Library Data
Parameter

Definition

L$BTSK

Task name consisting of two words
in Radix-SO
This parameter is set by the TASK keyword.

L$BPAR

Partition name consisting of two words in Radix-50
format.
This parameter is set by the PAR keyword.

format.

(continued on next page)

B-4

DETAILED TASK IMAGE FILE STRUCTURE
Table B-1 (Cont.)
Task and Resident Library Data
Parameter

Definition

L$BSA

Starting address of task. Marks the lowest task virtual
address.
This parameter is set by the PAR keyword.

L$BHGV

Highest virtual address mapped by address window O.

L$BMXV

Highest task virtual address. When the task does not
have memory-resident overlays, the value is set to
L$BHGV.

L$BLDZ

Task load size in units of 64-byte blocks.
represents the size of the root segment.

L$BMXZ

Task maximum size in units of 64-byte blockse
This
value represents the size of the root segment plus any
additional physical memory needed to contain
task
overlays.

L$BOFF

Task offset into partition in units of 64-byte blocks.
This value represents the size of the mapped array area,
which precedes the task's code and data
in
the
partition.

L$BWND

Number of task window blocks less library window
-- Low byte

L$BSYS

System ID

L$BWND

Number of task windows (excluding resident libraries) •

L$BSEG

Size of overlay segment descriptors (in bytes).

L$BFLG

Task flags word.

This

value

blocks

High byte

The following flags are defined:

Meaning When Bit

Bit

Flag

TS$PIC

Task contains position-independent code
(PIC) •

TS$NHD

Task has no header.

TS$ACP

Task is ancillary control processor.

TS$PMD

Task generates Postmortem Dump.

TS$SLV

Task can be slaved.

TS$NSD

No SEND can be directed to task.

(Not used)

TS$PRV

Task is privileged.

TS$CMP

Task is built in compatibility mode.

TS$CHK

Task is not checkpointable.

TS$RES

Task has memory-resident overlays.
(continued on next page)

B-5

DETAILED TASK IMAGE FILE STRUCTURE
Table B-1 (Cont.)
Task and Resident Library Data
Definition

Parameter

L$BFLG
(Conte)

L$BDAT

Bit

Flag

Meaning When Bit = 1

TS$IOP

Privileged task does not map I/O page

TS$NXH

Task was built with pool resident
header (non external)

Three words containing the task creation date as 2-digit
integer values as follows:
•

Year since 1900

•

Month of year

•

Day of month

L$BLIB

Resident library entries.

L$BPRI

Task priority set by the PRI keyword.

L$BXFR

Task transfer address.
Used to initiate a bootable core
image, for example, the resident executive.

L$BEXT

Task extension size in units of 32-word
parameter is set by the EXTTSK keyword.

L$BSGL

Relative block number of segment load list.
no list is allocated.

L$BHRB

Relative block number of header.

L$BBLK

Number of blocks in label block group.

L$BLUN

Number of logical units.

L$BROB

Relative block number of R/0 image.

L$BROL

R/O load size in 32-word blocks.

L$BRDL

Size of R/O data in 32-word blocks.

L$BHDB

Relative block number of data header.

L$BDHV

High vitrual address of data window 1.

L$BDMV

High virtual address of data.

L$BDLZ

Load size of data

L$BDMZ

Maximum size of data

B-6

blocks.

This

Set to 0 if

DETAILED TASK IMAGE FILE STRUCTURE
Label
L$BTSK

Offset
0

Task

Name

L$BPAR

Task

Partition

L$BSA

Base address of task

L$BHGV

Highest window 0 virtual address

L$BMXV

Highest virtual address in task

L$BLDZ

Load size in 64-byte blocks

L$BMXZ

Maximum size in 64-byte blocks

L$BOFF

Task offset into partition

L$BWN D/L$BSYS

System I .D. J_ Number of window blocks"

L$BSEG

Size of overlay segment descriptors

L$BFLG

Task flag word

L$BDAT

Task creation date - Year

- Month

36
L$BLIB

-Day

Library/common

Name

R$LNAM

[ Base address of library

R$LSA

! Highest address in first library window

R$LHGV

Library
Request

'(maximum

[ Highest address in library

R$LMXV

Library load size (64-byte blocks)

R$LLDZ

l Library maximum size (64-byte blocks)

R$LMXZ

Library offset into region

[ Number of library window blocks

[ Size of library segment descriptors

Library flag word

[

- Month

- Day

Library creation date - Year

344

L$BPRI

346

Task priority

L$BXFR

350

Task transfer address

L$BEXT

352

Task extension (64-byte blocks)

L$BSGL

354

Block number of segment load list

L$BHRB

356

Block number of header

L$BBLK

360

Number of blocks in label

L$BLUN

362

Number of logical units

L$BROB

364

Relative block of R-0 image

L$BROL

366

R/O load size

L$BRDL

370

RIO data size in 32-word blocks

L$BHDB

372

Relative block number of data header

L$BDHV

374

High virtual address of data window 1

L$BDMV

376

High virtual address of data

L$BDLZ

400

Load size of data

L$BDMZ

402

Maximum size of data

of 7 ·
.14-word
~ntri~ .in.

' RSX.'1 lM SVstems

R$LOFF

and

R$LWND

·maX:irnum"
off5',· ·''t

R$LSEG

•.14:worci'<

R$LFLG

entries in:·
'R~~~,t'l~~·~~~p~),,'

R$LDAT

"Less library window blocks.
ZK-475·81

Figure B-5

Label Block O -- Task and Resident Library Data

Table B-2 describes the contents of the resident shared region name
block.
TKB constructs this block by referring to the disk image of
the resident shared region.
The format
is identical to words 3
through 16 of the label group block.

B-7

DETAILED TASK IMAGE FILE STRUCTURE
Table B-2
Resident Library/Common Name Block Data
Definition

Parameter
R$LNAM

Shared region name consisting of
format.

R$LSA

Base virtual address of library or common.

R$LHGV

Highest address mapped by first library window.

R$LMXV

Highest virtual address in library or common.

R$LLDZ

Shared region load size in 64-byte blocks.

R$LMXZ

Library maximum size in 64-byte blocks.
This value
represents the size of the root segment plus the sum of
all memory-resident overlays.

R$LOFF

resident
Size of mapped array space allocated by
library.
This value is added to the mapped array area
of the task.

R$LWND

Number of window blocks required by library.

R$LSEG

Size of library overlay segment descriptors in bytes.

R$LFLG

Library flags word.

words

Radix-50

The following flags are defined:

Bit

R$LDAT

Meaning

LD$ACC -- Access intent (l=read/write,
O=read-only)

LD$RSV

APR was reserved

LD$CLS

Library is part of a cluster

LD$REL -- Position-independent code (PIC)
(l=PIC)

LD$TYP -- Shared region type (1
0 = library)

common,

Three words containing the shared region
in 2-digit integer values as follows:

creation

•

Year since 1900

•

Month of year

•

Day of month

flag

date

The table of LUN assignments, illustrated in Figure B-6, contains the
name and logical unit number of each device assigned.
Label block 2
(the second block of LUN assignments) is allocated only if the number
of LUNs exceeds 128.

B-8

DETAILED TASK IMAGE FILE STRUCTURE
TKB creates the segment load list if the image contains only
memory-resident overlays.
The segment load list is used only in
RSX-llS systems for loading tasks that have resident overlays. Figure
B-7 illustrates the segment load list. Each entry in the list gives
the length, in bytes, of a memory-resident overlay segment.
Device name
LUN 1
Unit number
Label
Block

•••

Device name

LUN 128
Unit number

Device name
LUN 129
Unit number
Label
Block

••
•

Device name
LUN 255
Unit number
ZK-476-81

Figure B-6

Label Blocks 1 and 2 -- Table of LUN Assignments

Length of root segment
Length of first overlay segment
Length of second overlay segment

•••
0
ZK-477-81

Figure B-7

B.2

Label Block 3 -- Segment Load List

CHECKPOINT AREA

The checkpoint area is created by the /AL switch
(refer to Chapter
10). The checkpoint area is as large as the task image plus any areas
created by the EXTTSK, PAR, or VSECT options.
The checkpoint area
does not include space for the external header if the /XH switch was
specified.

B-9

DETAILED TASK IMAGE FILE STRUCTURE
B.3-

HEADER

As shown in Figures B-1 through B-4, the task header starts on a block
boundary and is immediately followed by the task image.
The header is
read into memory with the task image.
The header is divided into two parts:
a fixed part as shown in Figure
B-8;
and a variable part as shown in Figure B-9.
The offsets for the
fixed part are defined by macro HDRDF$ residing in LB:[l,l]EXEMC.MLB.
The variable part of the header contains window blocks
the following:
•

The task's virtual-to-physical mapping

•

Logical unit data

•

Task context

that

describe

Although the header is fully accessible to the task, you should
consider only the information in the low-memory context (H.DSW through
H.VEXT) in the fixed part of the header to be accurate.
In a mapped
system, the Executive copies the header of an active task to protected
memory.
Subsequent Executive updates to the header are made to this
copy, not to the header copy within the running task.
The following sections provide more detail on the low-memory context
and on Logical Unit Table entries (the Logical Unit Table is part of
the variable part of the header;
see Figure B-9).
NOTE
To save the identification, you should
move the initial value set by the Task
Builder to local storage.
When the
program is fixed
in memory and being
restarted without being reloaded, you
must test the reserved program words for
their
initial
values
to
determine
whether the contents of R3 and R4 should
be saved.
The contents of RO, Rl, and R2 are only
set when a debugging aid is included in
the task image.

B.3.1

Low-Memory Context

The low-memory context for a task consists of the Directive Status
Word and the impure area vectors.
TKB recognizes the following global
names:
Name

Meaning

.FSRPT

File Control Services work area and buffer pool vector

$0TSV

FORTRAN OTS work area vector

N.OVPT

Overlay run-time system work area vector

$VEXT

Vector extension area pointer

B-10

DETAILED TASK IMAGE FILE STRUCTURE

··}};Ji~£Jrii£~},

Label

Offset

H.CSP

Current Stack Pointer ( R6)

H.HDLN

Header length

: super~isor· roG>Cle,;floa·J~·i;iiliJ/ ·i

./c:);·~p~ce·:.mai>'P>.:li{~asks;' :. ·

. ;:·,w;./. :: -;·· ·:·:

Event flag mask

Event flag address

H.CUiC

Current UiC

H.DUIC

Default UIC

H.IPS

Initial PS

H.IPC

Initial PC (R7)

H.ISP

Initial Stack Pointer (R6)

H.ODVA

ODT SST vector address

H.ODVL

ODT SST vector length

H.TKVA

Task SST vector address

H.TKVL

Task SST vector length

H.PFVA

Power fail AST control block

H.FPVA

Floating-point AST control block

H.RCVA

Receive AST control block

H.EFSV

Address of event flag context

H.FPSA

Address of floating-point context

H.WND

Pointer to number of window blocks

H.DSW

Directive Status Word

H.EFLM

H.FCS

Address of FCS impure storage

H.FORT

Address of FORTRAN impure storage

H.OVLY

Address of overlay impure storage

H.VEXT

Address of impure vectors

H.SPRl/H.NML

Mailbox LUN

H.RRVA

Receive by reference AST control block

Reserved

H.GARD

Header guard word pointer

H.NLUN

Number of LUNs

·.

;·,.\·:is. . .

·-,.;;~/;,,*'"__/;.._~:xt...
,:~~~-'";;~...
=; _ _ _ _......,,.

Low-Core
Context

Swapping priority

H.X25

ZK-478-81

Figure B-8

Task Header, Fixed Part

The only proper reference to these pointers is by symbolic name.
The
pointers are read-only.
If you write into them, the result will be
lost on the next context switch.
The impure area pointers contain the addresses of the storage used
the reentrant library routines listed above.
B-11

DETAILED TASK IMAGE FILE STRUCTURE
The address contained in the vector extension pointer locates an
of memory that can contain additional impure area pointers.

H.LUN

area

I LUN Table (2 words per LUN)
•••
Number of window blocks

Offsets

Partition control block address

W.BPCB

Low virtual address limit

W.BLVR

High virtual address limit

W.BHVR

Address of attachment descriptor

W.BATT

Window size (in 32-word blocks)

W.BSIZ

Offset into partition (in 32-word blocks)

W.BOFF

Number of PD Rs to Map

First PDR Address

W.BNPD/W.BFPD
W.BLPD

Contents of last PDR

•
••
Current PS
Current PC

Initial Values

Current R5

Relative block number of header

Current R4

ldent. word #2

Current R3

ldent. word #1

Current R2

Task name word #2

Current R 1

Task name word #1

Current RO

Program transfer address

Header guard word
ZK-479-81

Figure B-9

Task Header, Variable Part

Figure B-10 illustrates the format of the vector extension area.
Each
location within this area contains the address of an impure storage
area that can be referred to by subroutines within a resident library;
these subroutines must be reentrant.
The address of this area
(location $VEXTA) is contained at absolute address $VEXT in the task
header.
Addresses below $VEXTA, referred to by negative offsets, are
reserved for DIGITAL applications. Addresses above $VEXTA, referred
to by positive offsets, are allocated for user applications.

B-12

DETAILED TASK IMAGE FILE STRUCTURE

$VEXT

•
•

•
.PSECT $$VEXO

~
$VEXTA

Reserved for
DIGITAL use

.PSECT $$VEX1

Reserved for
user applications

ZK-480-81

Figure B-10

Vector Extension Area Format

The program sections $$VEXO and $$VEX1 have the attributes D, GBL, RW,
REL, and OVR.
The program section attribute OVR facilitates defining the offset to
the vector and initializing the vector location at link time. For
example:
.GLOBL

$VEXTA

.PSECT

$$VEX1,D,GBL,REL,OVR

$$$=.

MAKE SURE VECTOR AREA IS LINKED

POINT TO BASE OF POINTER TABLE
.BLKW

LABEL:
.WORD
OFFSET==LABEL-BEG

OFFSET TO CORRECT LOCATION
IN VECTOR AREA

IMPURE

SET IMPURE AREA ADDRESS
DEFINE OFFSET

.PSECT
IMPURE:

You should centralize all offset definitions within a single module
from which the actual vector space allocation is made. Also, you
should write the source code with conditional statements to create two
object modules:
one that reserves the vector storage; and one that
defines the global offsets that will be referred to by your resident
library's subroutines.
Note that the sequence of instructions above intentionally redefines
the global symbol.
The Task Builder reports an error if this value
differs from the centralized definition.

B-13

DETAILED TASK IMAGE FILE STRUCTURE
You can locate your vector through a sequence of instructions
to the following:
MOV @#VEXT,RO
MOV OFFSET(RO) ,RO
• END

B.3.2

similar

GET ADDRESS OF VECTOR EXTENSIONS
POINT TO IMPURE AREA

Logical Unit Table Entry

Figure B-11 illustrates the format of each entry in the
Table.

Logical

Unit

UCB address
Window block pointer
ZK-481-81

Figure B-11

Logical Unit Table Entry

The first word contains the address of the device unit control block
in the Executive system tables.
That block contains device-dependent
information.
The second word is a pointer to the window block if the device is file
structured.
The UCB address is set during task installation if a corresponding ASG
parameter is specified at task-build time.
You can also set this word
at run time with the Assign LUN Directive to the Executive.
The window block pointer is set when a file is opened on the device
whose UCB address is specified by word 1. The window block pointer is
cleared when the file is closed.

B.4

TASK IMAGE

The system reads the task image into memory beginning with the task
header
(see Figures B-1 through B-4).
The root segment of a
conventional task image is a set of contiguous disk blocks;
it is
1:l'lE:!.ref ()re. loaded wi tl'l a. single disk access. . . However I
I- and
· ;o-~.pace las){: 'r9ot conta·i ns. 2 seti;. oE coptiguoq.s plo~ks •. · . Therefore, an
~'."." .. and . Q-space task .requ.i res two disk ac~esses, one.· .f.or .th,.~ D-spaq:~
,par·t. and one for th~. I-space part. .· .The p...,space part is loaded.. first .•
~9.~.~t:i.on~'.}; l.Y:r. £:?~.elf.· seg!llE?I'lt 9f· an . 9.ver.l a i.d .I- .apd · D-..sp~c~ ;: t.a~·:tt 'reqt;lit'es
~~o;,·~~$k . ,qc<:esses .. 'if i~ contains both I..;. .and·· p~space. ·
·

'an.

Each overlay segment of the task image begins on a block boundary (see
Figure B-3).
Note that a given overlay segment occupies as many
contiguous disk blocks as it needs to supply its space request.
The
maximum size for any segment,
including the root, is 32K minus 32
words.

B-14

DETAILED TASK IMAGE FILE STRUCTURE
NOTE
One exception to the block boundary
alignment of segments occurs when shared
regions contain resident overlays. When
this occurs,
the image is compressed
and, instead of being aligned on block
boundaries,
segments are aligned on
32-word boundaries.
This facilitates
the loading of regions.
Figures B-12 and B-13 illustrate the structure
components of the task-resident overlay data base.

and

principal

-----,
I

SEGMENT
DESCRIPTOR

AUTO LOAD
VECTOR

WINDOW
DESCRIPTOR
AUTOLOAD
VECTOR

SEGMENT
DESCRIPTOR

r-------,
AUTOLOAD
VECTOR

r--

SEGMENT
DESCRIPTOR

~
I

WINDOW
DESCRIPTOR

I
_l

_J_

T-

I I

REGION
DESCRIPTOR

I
I
I

L _ _ _ _ _ _ _JL ______ .J

@ Window descriptors are necessary for the
windows that the Overlay Run-Time
System uses to map memory resident
overlays. The Overlay Run-Time System
also needs window descriptors to map
disk-resident overlays that are up-tree
from memory-resident overlay segments.

@ The Overlay Run-Time System uses
region descriptors to map overlaid
libraries.
ZK-1068-82

Figure B-12 Task-Resident Overlay Data Base
for a Conventional Overlaid Task

B-15

DETAILED TASK IMAGE FILE STRUCTURE

- -,

r
AUTOLOAD
VECTOR

WINDOW
DESCRIPTOR
FOR I-SPACE

SEGMENT
DESCRIPTOR

D-SPACE PART

EXTENSION

WINDOW
DESCRIPTOR
FORD-SPACE

AUTOLOAD
VECTOR

SEGMENT
DESCRIPTOR

D-SPACE PART

WINDOW
DESCRIPTOR
FOR I-SPACE

EXTENSION

WINDOW
DESCRIPTOR
FORD-SPACE

@
AUTOLOAD
VECTOR
~-----

D-SPACE PART

r - -

l.--1

SEGMENT
DESCRIPTOR

_l
........._

WINDOW
DESCRIPTOR

I
j_ --'--I

I I

- - - - -,

REGION
DESCRIPTOR

I
I
I

L ______ _JL ______ J

Window descriptors are necessary for the
windows that the Overlay Run-Time
System uses to map memory resident
overlays. The Overlay Run-Time System
also needs window descriptors to map
disk-resident overlays that are up-tree
from memory-resident overlay segments.

® The
Overlay Run-Time System uses
region descriptors to map overlaid
libraries.
ZK-1069-82

Autoload vectors are generated whenever a reference is made to an
autoloadable entry point in a segment located farther away from the
root than the segment making the reference.
One segment descriptor is generated for each overlay segment in the
task or shared region.
The segment descriptor contains information on
the size, virtual address, and location of the segment within the task
image file.
In addition, it contains a set of link words that point
to other segments.
The overlay structure determines the link word
contents.
B-16

DETAILED TASK IMAGE FILE STRUCTURE

:'~,~l:i~e·tj,~:::&~~c.~'~·:PE1i~·:s:.·. ,t¢t··

J:. . )~11~.:,'·'J)~spa'.cre:· .t?s,~s'.:·pilve: .·:a11· :ex~~:riston,:··,,f~t/:tp·~.::
:vi<i:·tuar:: .

<P7$P'<i'c~>::.• pa·rt'....,tpat:·'/.~orrta.i;is .· "/the. . . ,'.·dist . ··· bl'ock·.

a.a.d.t.ess.·t ·

'.loaa.

: . ~~~i:.~:~:H~.:.,;·~.s,~·~~en7: ·~e.9';Jt:J: in .J:>~t::$.s·.1.: .and }'!~~~()Yf ·poi.:~t;.e~~:· . ,

· · · ·· · :

The window descriptor contains information required to issue the
mapping directives.
TKB allocates one window descriptor for each
memory-resident overlay in the structure.
The region descriptor contains information required to attach a
resident library or common block. There is one region descriptor for
each shared region containing memory-resident overlays.
The following sections describe each data base

component

greater

detail.

B.4.1

Autoload Vectors for Conventional Tasks

The autoload vector table consists of one entry (put into the task
image for each autoload entry point) in the form shown in Figure B-14.
JSR PC,@.NAUTO
PC RELATIVE OFFSET TO .NAUTO
SEGMENT DESCRIPTOR ADDRESS
ENTRY POINT ADDRESS
ZK-1070-82

Figure B-14

Autoload Vector Entry for Conventional Tasks

The autoload vector executes an indirect JSR instruction to $AUTO
through .NAUTO.
Following the JSR instruction is a pointer to the
descriptor for the segment to be loaded. Following the descriptor is
the real address of the required entry point.

~'f;~~,;~:.~~~~~:~~w~·:£~t/t7~t.~· ~~~eJt:t~13~_:i,

,'. :,..,_., :· .·."·}::~. •. ,\·::c,)

.:'.'.)!~:·,:~\l:tQ'.1:191¥>;ve~tor: t~b:I'e.:consJ.s,ts···of..;·t;w:o.. entries . . ·(put··into ·: :the ..... tas:J< .•

~ilr\lil~cl:()'if

;each ,;a"'ool~ ~t-ey pq.i~tJ in .·tile .·to= '5}Jowri 'in .t~a~~- s.,..i s,,"

~The,
.~~~ Part. ,ct; t~ ..a~to l<>.~<l · v~t~r < t.&iPi> . . i .!iQV •· 4pl>ti;!le;t;i~~ ·
.J:b~t:. ". . pia·ces ',th.e .·addr,ess'· ,<>f .t;he. u~s;pace part of: the"•.vect,or on':.the'
QO!l

··st~dl(, •.. The. yector 'then executes an' indir~ct JM,P to ·$AUTO '.t~rough:,.
~aAUTO.
'!;he , D-apace part ·of the vector contains the segment.'

·descriptor address

a:nd

the

entry

r9Utine;

point
·

B-17

address

the

required

DETAILED TASK IMAGE FILE STRUCTURE

MOV (PC)+, -(SP)
ADDRESS OF PACKET (D-SPACE)
JMP @.NAUTO
PC RELATIVE OFFSET TO .NAUTO
I-SPACE PORTION

ADDRESS OF SEGMENT DESCRIPTOR
ENTRY POINT ADDRESS
D-SPACE PORTION
ZK-1071-82

B.4.3

Segment Descriptor

The segment descriptor for a conventional task consists of a
fixed
part and two optional parts.
The fixed part is six words long.
If
the manual-load
feature
is used
($LOAD),
two words are
added
containing the segment name. When a memory-resident overlay structure
is included, a ninth word
is appended
that points to the window
descriptor.
The segment descriptor for an I- and D-space task consists of a
fixed
part that is 9 words long and an optional part that is 4 words long.
This optional part is always present: for task segments and not present
.f.or library segments.
Figure B-16 illustrates the contents of the segment descriptor.

B-18

DETAILED TASK IMAGE FILE STRUCTURE
TASK-RESIDENT SEGMENT DESCRIPTOR OFFSETS

12 11

FLAGS

BYTE

RELATIVE DISK BLOCK ADDRESS

VIRTUAL LOAD ADDRESS OF SEGMENT

LENGTH OF SEGMENT IN BYTES

LINK UP

LINK DOWN

LINK NEXT

~ SEGMENT NAME (2-WORD RADIX 50)

WINDOW DESCRIPTOR ADDRESS
FLAGS:

15-TASK RESIDENT FLAG (ALWAYS 1)
14-SEGMENT HAS DISK ALLOCATION (1=NO)
13-SEGMENT IS LOADED FROM DISK (1=YES)
12-SEGMENT IS LOADED AND MAPPED (O=YES)

:"f '·,.,;P~;s.c:~rvr:~.~1:::,Fo.~;:1i.·~Nl).·9L.$;P~~J;. ~ ~·~~:'(1,~VFSi,' ,

,,,,'

..:-

;

',.

, ,'

'1·>\S:J\~~6SJD~N1:::§EGfVl'.EN~ .D~S,GRIPT6R.:E~TEN9!0f':( :
:' . :· QFFSETS'FORl-.ANo·o..,SPACEJ:AS}(S ONLY ... · ·

1·' ·' .": .:

';:

•

<..tr

•

. ·b.igp'Ac~:·61sk·afOCK ;AeDRESs·"
:' ;·

;

·~ 0,' .~

.,...

;:, ».i

< ~

.,,

,~ , /

·,

;

.<~'

~~, > • t.

:<~

,/ ,, ' ~

¢-

,;;

x·>'

;· "'

1'~

1 }~2';E86!F···ot.J~v.1·~s:.p,.A:diE,sEGMEt4r,·'
~, --:;'

'<',

~l ,,'~

"'i;v .;::.·'

,, ,;

.i ;:

Figure B-16

.,:->

' ,

;

Segment Descriptor

Word O contains the relative disk address in bits 0 through 11 and the
segment status in bits 12 through 15.
Each segment in the task image
file begins on a disk block boundary. The relative disk address
is
the block number of the segment relative to the start of the root
segment. The segment status flags are defined as follows:

Bit

Setting

Always set to 1

0
l

Segment has disk allocation.
Segment does not have disk allocation.

Segment is not loaded from disk.
Segment is loaded from disk.

0
1

Segment is loaded and mapped.
Segment is either not loaded or not mapped.

B-19

DETAILED TASK IMAGE FILE STRUCTURE
Word 1 contains the load address of the segment.
This address is the
first virtual address of the area where the segment will be loaded.
Word 2 specifies the length of the segment in bytes.
Words 3, 4, and 5 point to the following segment descriptors:
•

Link up -- The next segment away from the root

•

Link down

•

Link next
The adjoining segment;
are linked in circular fashion.

(O=none) •

The next segment toward the root {O=none) •
the

link-next

pointers

When the system loads a segment, the overlay run-time system follows
the links to determine which segments are being overlaid and should
therefore be marked out of memory.
For example:

A21

A22

AO
The segment descriptors are linked as follows:

A21

A22

A~ A2

A22

A21

~,-J
A2

~r
AO

link up

link down

A22

Al~A2

link next

If there is a co-tree, the link next for the root
points to the co-tree root segment descriptor.

segment

descriptor

Words 6 and 7 contain the segment name in Radix-50 format.
Word 8 points to
(O=none).

B.4.4

the

window

descriptor

used

map

the

segment

Window Descriptor

TKB allocates window descriptors only
containing memory-resident overlays.
format of a window descriptor.

if you define a structure
Figure B-17 illustrates the

Words 0 through 7 constitute a
window descriptor
in the format
required by the mapping directives.
If the memory-resident overlay is
part of the task, the region ID is O.
If the memory-resident overlay
is part of a shared region, the overlay loading routine fills in the
ID at run time.
Words 8 and 9 contain additional data that
is
referred to by the
overlay routines.
Bit 15 of the flags word, if set, indicates that
the window is currently mapped into the task's address space.

B-20

DETAILED TASK IMAGE FILE STRUCTURE
Word 9 contains the address of the associated region descriptor.
If
the memory-resident overlay is part of the task, and no region
descriptor is allocated, this value is 0.
Word

8 7
Base Active Page Register

0
Window ID

Virtual base address

Window size in 64-byte blocks

Region ID

Offset in partition

Length to map

Status word

Send/receive buffer address (always 0)

Flags word

Address of region descriptor
ZK-485-81

Figure B-17

B.4.5

Window Descriptor

Region Descriptor

The region descriptor is allocated only when the memory-resident
overlay structure is part of a shared region.
Figure B-18 illustrates
the format of a region descriptor.
Word
Region ID

Size of region

Region

name

Region

partition

Region status

Protection codes (always O)

Flags
ZK-486-81

Figure B-18

Region Descriptor

B-21

DETAILED TASK iMAGE FILE STRUCTURE
Words 0 through 7 constitute a region descriptor in the format
required by the mapping directives.
The flags word is referred to by
the overlay load routine. Bit 15 of the flags word, if set, indicates
that a valid region identification is in word O.
If this bit is
clear, the overlay load routine issues an Attach Region directive
(with protection code set to 0) to obtain the identification.

B-22

APPENDIX C
HOST AND TARGET SYSTEMS

C.l

INTRODUCTION

You can build a task on one system (the host), and run it on another
(the target).
For example, your installation might consist of one
large computer system with mapping hardware, and several smaller
unmapped systems.
On the large system you could create and debug
tasks, and then transfer them to the smaller systems to run.
For example, if you are developing a task named TK3, using the default
partition of your host system, the TKB command could be:
>TKB TK3,TK3=SQ1,SQ2
When you are ready to move TK3 to a target system, you build it again,
indicating the mapping status of the target system and naming the
partition in which the task is to reside:
>TKB
TKB>TK3/-MM,TK3=SQ1,SQ2
TKB>/
Enter Options:
TKB>PAR=PART1:100000:40000
TKB>//
The resulting task image is
system.

ready

run

the

unmapped

You can transfer a task from the host system to the target
following these steps:

target

system

Build the task image specifying the partition in which the
task will run.
If the target system is an unmapped system,
specify the partition's base address and size.

Ensure that any shared regions
present in both systems.

If the target system and the host system do not have the same
mapping status, set the Memory Management switch (/MM or
/-MM) to reflect the mapping status of the target system.

accessed

the

task

are

The task code must not use any hardware options (FPP, EIS, EAE, and so
forth)
that
are not present on the target system.
This is
particularly important if you are a FORTRAN user because FORTRAN tasks
often use mathematics routines that are hardware dependent.
(Refer to
the IAS/RSX-11 FORTRAN IV Installation Guide and the IAS/RSX-11
FORTRAN IV User's Guide for more informatio~FORTRAN requirements).

C-1

HOST AND TARGET SYSTEMS

C.2

EXAMPLE C-1:

TRANSFERRING A TASK FROM A HOST TO A TARGET SYSTEM

In this section, the resident library LIB and the task that refers to
it, MAIN
(from Example 4, Chapter 5), are rebuilt to run on an
unmapped system.
To save space, only the Task Builder command
sequences are shown.
Assuming that the target system has a partition within it named LIB,
you need to make only two changes to the original command sequence
that builds the library:
1.

You must attach the negated memory management
to the image file specification.

You must specify the partition base and length.

switch

(/-MM)

The modified command sequence is as follows:
TKB>LIB/-HD/PI/-MM,LIB/-WI,LIB=LIB
TKB>/
Enter Options:
TKB>STACK=O
TKB>PAR=LIB:l36000:20000
TKB>//
If the target system does not contain a partition of the same name as
that of the shared region, you must change the name of the shared
region to match the name of an existing partition in the target
system. This is a requirement of RSX-llM; on RSX-llM-PLUS systems it
is not.
Assuming that the target system has a partition named GEN and that the
task MAIN is to run in that partition in the target system, you must
make three changes to the command sequence that builds the task MAIN:
1.

You must attach the negated memory management
to the task image file specification.

switch

(/-MM)

You must eliminate the APR parameter of the RESLIB keyword.

You must explicitly specify the base address and
the partition in which the task is to reside.

length

The modified command sequence is as follows:
TKB>MAIN/-MM,MAIN/MA/-WI=MAIN
TKB>/
Enter Options:
TKB>RESLIB=LIB/RO
TKB>PAR=GEN:30100:40000
TKB>//
Example C-1, Part 1 shows the map file of the resident library LIB for
an unmapped system. LIB is bound to the partition base specified by
the PAR keyword in the task-build command sequence.
Note that the
shared region is declared position independent even though it is bound
to the partition base 136000. The position-independent declaration is
not necessary in this example because the referencing task MAIN does
not require the program section names within the library in order to
refer to it.
However, in applications involving tasks that require
the program section names from the library, you must declare the
library position independent so that TKB will place the program
section names in the library's symbol definition file.

C-2

HOST AND TARGET SYSTEMS
Example C-1, Part 1
LIB.TSK;l

Task Builder Map for LIB.TSK

Memory allocation map TKB M40.10
10-DEC-82
11:50

Page 1

Partition name
LIB
Identification
01
Task ore
[303,3]
Task attributes: -HD,PI
Total address windows: 1.
Task image size
64. words
Task address limits: 000000 000163
R-W disk blk limits: 000002 000002 000001 00001.

*** Root segment: LIB
R/W mem limits: 000000 000163 000164 00116.
Disk blk limits: 000002 000002 000001 00001.
Memory allocation synopsis:
Section
• BLK.: (RW,I,LCL,REL,CON) 000000 000000
AADD :(RO,I,GBL,REL,CON) 000000 000024
000000 000024
DIVV : (RO,I,GBL,REL,CON) 000024 000026
000024 000026
MULL : (RO,I,GBL,REL,CON) 000052 000024
000052 000024
SAVAL : (RO,I,GBL,REL,CON) 000076 000042
000076 000042
SUBB :(RO,I,GBL,REL,CON) 000140 000024
000140 000024

00000.
00020.
00020.
00022.
00022.
00020.
00020.
00034.
00034.
00020.
00020.

Title

Ident

File

LIB

LIB.OBJ; 1

LIB

LIB.OBJ;l

LIB

LIB.OBJ;l

LIB

LIB.OBJ; 1

LIB

LIB.OBJ;l

Global symbols:
AADD
DIVV

000000-R
000024-R

MULL
SAVAL

000052-R
000076-R

SUBB

000140-R

*** Task builder statistics:
Total work file references: 368.
Work file reads: O.
Work file writes: 0.
Size of core pool: 7086. words (27. PAGES)
SIZE OF WORD FILE: 768. words (3. PAGES)
Elapsed time:00:00:03

C-3

HOST AND TARGET SYSTEMS
Example C-1, Part 2 shows the map file of the task MAIN for an
unmapped system.
The task is bound to the partition base 30100 and
linked to the shared region LIB, which begins at 136000.
Example C-1, Part 2
MAIN. TSK; 1

Task Builder Map for MAIN.TSK

Memory allocation map TKB M40.10
ll-DEC-82
13:41

Page 1

Partition name : GEN
Identification : 01
Task UIC
[303,3]
Stack
limits: 000274 001273 001000 00512.
PRG xfr address: 001634
Total address windows: 2.
Task image size
1152. WORDS
Task address limits: 00000 004327
R-W disk blk limits: 000002 000006 000005 00005.

*** Root segment: MAIN
R/W mem limits: 000000 004327 004330 02264
Disk blk limits: 000002 000006 000005 00005.
Memory allocation synopsis:
Title

Section

• BLK.: (RW,I,LCL,REL,CON) 001274 002620 01424.
001274 000530 00344. MAIN

!dent

File

MAIN. OBJ; 1

Global symbols:
AADD
DIVV
IO.WVB
MULL

160000-R
160000-R
011000
060000-R

SAVAL
SUBB
$CBDAT
$CBDMG

060000-R
060000-R
003074-R
003102-R

$CBDSG
$CBOMG
$CBOSG
$CBTA

003110-R
003116-R
003124-R
003154-R

*** Task builder statistics:
Total work file references: 1889.
Work file reads: 0.
Work file writes~ O.
Size of core pool: 7086. WORDS (27. PAGES)
Size of work file: 1024. WORDS (4. PAGES)
Elapsed time:00:00:07

C-4

$CBTMG
$CBVER
$CDDMG
$CDTB

003132-R
003116-R
003656-R
003312-R

APPENDIX D

MEMORY DUMPS

The RSX-llM/M-PLUS Postmortem Dump task
(PMD)
generates postmortem
memory dumps of tasks that are abnormally terminated.
In addition,
PMD can produce edited dumps, called snapshot dumps, for tasks that
are running.
Section D.l describes Postmortem Dumps in general;
Section D.2 discusses the specific case of snapshot dumps. Both types
of dumps are very useful debugging aids.

D.l

POSTMORTEM DUMPS

You can make a task eligible for a Postmortem Dump
ways:
•

any

three

At task-build time, by specifying the /PM switch for the task
file. /-PM disables dumps;
it is the default condition.

you install a task by using the /PMD switch to override
• When
the taskbuild option.
/PMD=YES enables dumping; /PMD=NO
disables dumping.
•

When you use the MCR command ABORT
(described in
the
RSX-llM/M-PLUS MCR Operations Manual) I by including the PMD
switch in the command line to specify a dump.

You should install PMD in a 4K partition in which all other tasks are
checkpointable.
This allows the dump to be generated in a timely
manner, and prevents the system from being locked up while the dump is
being generated.
PMD can dump either from memory or from the
checkpoint image of your task. The PMD is sensitive to the location
of the aborted task; therefore, if the aborted task is checkpointed
during the dump, PMD switches to reading the checkpoint image.
Once
the task is checkpointed, PMD locks it out of memory until it has
completed formatting the dump.
Dumps are always generated on the system disk under UFD [1,4];
therefore, to avoid errors from PMD, you must create a UFD for [1,4]
before installing the task. When PMD finishes generating the dump, it
attempts to queue the dump to the print spooler for subsequent
printing.
If no spooler is installed, the dump file is left on the
disk and can be printed at a later time using the Peripheral
Interchange Program (PIP, described in the RSX-11 Utilities Manual).
NOTE
Dump files tend to
The dump of an
about 340 blocks.
is little space
important to print

be somewhat large.
SK partition averages
Therefore, if there
on the disk,
it is
and delete the dump
D-1

MEMORY DUMPS
file without delay.
The print spooler
automatically deletes all files with the
type .PMD after printing them.
Example D-1 shows the contents of a Postmortem Dump and snapshot dump;
the notes that follow the figure are keyed to the figure and provide a
description of the dumps contents. Snapshot Dumps are explained more
fully in Section D.2.
Example D-1

Sample Postmortem Dump (Truncated)
POST-MORTEM DUMP . ,
TIME: S-OCT-76 1S:06

TASK: TT6@
PC: 000720

€)

REGS:

RO - 00034S

IOT EXECUTION

€)

Rl - 074400
0

R4 - 000000

RS - 000000

R3 -

SP - 000304

PS - 17 0000

MSG AST DST -CHK HLT STP REM MCR

TASK STATUS:

14013~} 0

R2 - 000120

EVENT FLAG MASK FOR <1-16> 000001 (i)
CURRENT UIC:

DSW: 1. f.)

(007 ,001]

PRIORITY: DEFAULT - SO.

RUNNING - SO.

I/O COUNT: O.

TI DEVICE - TT6: (i)

LBN: 1, 160034 Ci)

LOAD DEVICE - DBO:
FLOATING POINT UNIT
STATUS - 000000
RO
Rl
R2
R3
R4
RS

000000
000000
000000
000000
000000
000000

LOGICAL UNITS
UNIT

DEVICE

1
2
3
4

DBO:
DBO:
DBO:
DBO:

FILE STATUS

OVERLAY SEGMENTS LOADED AND RESIDENT LIBRARIES MAPPED
STARTING RELATIVE BLOCK: 000002
STARTING RELATIVE BLOCK: 000004

BASE: 000000
BASE: 0014S4

LENGTH: 0014S4}
LENGTH: 000264

' ~ Q)

TASK STACK

ADDRESS CONTENTS ASCII RADSO
000304

00004S

TASK IMAGE
ZK-487/1-81

(continued on next page)
D-2

MEMORY DUMPS
Example D-1 (Cont.)
PARTITION: GEN
000000
000010
000020
000030
000040
000050
000060
000070
000100
000110
000120
000130
000140
000150
000160

***

000304
304 000
003401
001 007
000304
304 000
000000
000 000
000000
000 000
000000
000 000
000373
373 000
000000
000 000
000000
000 000
000000
000 000
067020
020 156
000020
020 000
170000
000 360
140130
130 300
000000
000 000

000162
162 000
003401
001 007
000000
000 000
000000
000 000
140162
162 300
000000
000 000
000000
000 000
074150
150 17 0
051646
246 123
051646
246 123
000000
000 000
000000
000 000
000720
320 001
000120
120 000
000000
000 000

Sample Postmortem Dump (Truncated)
VIRTUAL LIMITS: 000000 - 001777
000001
001 000
170017
017 360
000000
000 000
000000
000 000
074106
l 06 17 0
001104
104 002
000000
000 000
000004
004 000
000000
000 000
000000
000 000
001777
377 003
000600
200 001
000000
000 000
074400
000 171
000000
000 000

DUPLICATE THROUGH 000236

000240
00250
000260
00270
000300
000310
000320
000330
000340
000350
000360

000000
000 000
001454
054 003
000001
001 000
063014
014 146
001051
051 002
000000
000 000
000524
124 001
000000
000 000
131574
17 4 263
000000
000 000
001037
037 002

000000
000 000
000264
264 000
001612
212 003
131574
174 263
000001
001 000
000001
001 000
000000
000 000
000000
000 000
047123
123 116
016746
346 035
104377
377 210

067426
026 157
000352
352 000
000000
000 000
000000
000 000
000001
001 000
000000
000 000
000000
000 000
051646
246 123
051646
246 123
000001
001 000
061404
004 143
007406
006 017
000000
000 000
000345
345 000
000000
000 000

! D6

A Q08
D

!AD3 AD3 8PQ

E4
p

;

D6
D
! .

OlZ SIO

A.
r@ Fx

NT
D
Fk
SJX

D MON

MON

&S!

&S
!QXP

YW 03.

IX BPF

!8P

!01

p p
SNP

E/
y e

x@ P

***

001110
110 002
000000
000 000
074360
360 17 0
000000
000 000
000045
045 000
000100
100 000
000000
000 000
000000
000 000
052120
120 124
177734
334 377
103456
056 207

000000
000 000
000000
000 000
003413
013 007
000000
000 000
050114
114 120
000304
304 000
000000
000 000
063014
014 146
052123
123 124
012746
346 025
005046
046 012

NX
H
TL

vz SN

4
AEC
px

!PMD
3

A
A

7 L36.
!}
AX D6!

LP!

D !

HT
!T
PMD 1
f !
! ••• LUK MSX MS$

3 SN PT ST!
DIN

7T CTF
f

MW U61 UYF AX8
& !
ZK-48712-81

D-3

MEMORY DUMPS
~

Type of dump:
Postmortem or snapshot.
If it is
dump, the dump identification is printed.

The name of the task being dumped, and the date and time
dump was generated.

The program counter at the time of the dump.
If it is a
Postmortem Dump, the reason the task was aborted is printed.

(»

The general registers, stack pointer, and processor status at
the time of the dump.

The task status flags at the time of the dump.
See
description
of
ATL or TAL in the RSX-llM/M-PLUS
Operations Manual for the meaning of the flags.

(S)

The task event flag mask word at the time of the dump.
If
the dump is a snapshot dump, the efn specified in the SNAP$
macro will be ON (see Section D.2.2).

The task UIC and the current value of
word.

the

directive

snapshot
the

the
MCR

status

The task's priority and default
priority,
number
of
outstanding I/0 requests,
and the terminal from which the
task was initiated (TI:).

€)

The task load device and the logical block
start of the task image on the device.

The floating-point unit
(FPU)
registers or the extended
arithmetic element
(EAE) registers if the task is using one
of these hardware features.
If the task is not using the FPU
or EAE,
these registers are not printed.
If the task uses
the FPU and does not specify /FP on the task image file,
or
if it uses the EAE unit and has not specified the /EA switch,
the registers are not printed.
If the machine you are using
has both an FPU and an EAE, PMD assumes you are using the FPU
because it is the unit of choice for arithmetic computations.

The logical unit assignments at the time of the dump.
UNIT
is the logical unit number, and DEVICE is the device to which
the logical unit is assigned.
For snapshot dumps,
the file
names of any open files are displayed under FILE STATUS.
Postmortem Dumps do not display this information because all
of the files have been closed as a result of the I/O rundown
on the aborted task.

The following are displayed:
the overlay segments loaded and
resident libraries mapped at the time of the dump;
the
relative block number of the segment; the base address;
the
length of the segment;
and, for tasks using manual load, the
segment names. For resident libraries, the library name is
also displayed.
The block number can be used to determine
which segment is loaded, by reference to
the
memory
allocation file generated by the Task Builder. The starting
block number for each segment is the relative block number of
the segment.
By obtaining a match, you can determine the
name of the segment in memory.
Zero-length segments are
usually co-tree roots.

D-4

number

for

the

MEMORY DUMPS

The task stack at the time of the dump.
The address is
displayed, along with the contents,
in octal, ASCII, and
Radix-50.
Each word on the stack is dumped.
If the stack
pointer is above the initial value of the stack (H.ISP), only
one word is dumped. The rest is dumped as part of the task
image.

The task image itself. The partition being dumped and the
limits of interest are displayed. For Postmortem Dumps, all
address windows in use are dumped. For snapshot dumps, the
virtual task limits that you request are displayed.
The dump
routine rounds the requested low limit down to the nearest
multiple of eight bytes and rounds the requested high limit
up to the nearest multiple of eight bytes~
The dump image
displays the virtual starting address of a 4-word block of
memory, the data in both octal and Radix-50 on the first
line, and byte octal and ASCII on the second line. A 4-word
block that is repeated in a contiguous region of memory is
printed once, and then noted by the message

***

DUPLICATE THROUGH xxxxxx

***

where xxxxxx indicates the last word that is duplicated.
If
the task was aborted, all address windows in use are dumped.
If the dump is a snapshot dump, up to four contiguous blocks
of memory can be dumped, if requested.

D.2

SNAPSHOT DUMP

Snapshot dumps are edited dumps produced for running tasks.
You can
request a snapshot dump any number of times during the execution of a
task.
The information generated is under the control of
the
programmer.
Snapshot dumps are generated by the following macros:
•

SNPDF$ -- Defines offsets in the snapshot dump control block
and defines control bits, which control the format of the dump

•

SNPBK$ -- Allocates the snapshot dump control block (see Table
D-1)

SNAP$

Causes a snapshot dump to be generated

SNPBK$ and SNAP$ issue calls to SNPDF$;
so, you need not explicitly
issue the SNPDF$ macro call. Sections D.2.1 and D.2.2 describe the
SNPBK$ macro and the SNAP$ macro, respectively.

D-5

MEMORY DUMPS

Label

Offset

SB.CTL

CONTROL FLAGS

SB.DEV

DEVICE MNEMONIC

SB.UNT

UNIT NUMBER

SB.EFN

EVENT FLAG

SB.ID

SNAP IDENTIFICATION

(L 1)

12
14

MEMORY BLOCK
LIMITS

(H1)
(L2)

16
20

MEMORY BLOCK
LIMITS

(H2)
(L3)

22
24

MEMORY BLOCK
LIMITS

(H3)
(L4)

26
30

MEMORY BLOCK
LIMITS

(H4)

SB.LM1

SB.PMD

32
34

"PMD ... "
IN RADIX-50
ZK-488-81

Figure D-1

D.2.1

Snapshot Dump Control Block Format

Format of the SNPBK$ Macro

The format of the SNPBK$ macro call is:
SNPBK$ dev,unit,ctl,efn,id,Ll,Hl,L2,H2,L3,H3,L4,H4
dev

The 2-character ASCII name of the device to which the dump is
directed.
If it is a directory device, the UFD [1,4] must be on
the volume.
The dump is written to the disk and then spooled to
the line printer.
If there is no print spooler, the file is left
on the disk.
If the device is not a directory device, the dump
goes directly to the device.
unit
The unit number of the device to which the dump is directed.
ctl
The set of flags that control the format of the dump and the data
to be printed.
The flags are:
SC.HOR

Print the dump header ( i terns 3 to 10 in
Items 1 and 2 are always printed.
D-1).

SC.LON

Print information on all assigned LUNs

SC.OVL

Print information about all loaded overlay segments
{ i tern 12) •

D-6

Figure

( i tern 11) •

MEMORY DUMPS
SC.STK

Print the user stack (item 13).

SC.WRD

Print the requested
Radix-50 (item 14).

SC.BYT

Print the requested memory in octal bytes and ASCII
{ i tern 14) •

memory

octal

words

and

ef n
The event flag to be used to synchronize your program and PMD.

id
A number that identifies the snapshot dump. Because dumps can be
requested at different times and under different conditions, this
ID is used to identify the place or reason for the dump.

Ll,L2,L3,L4
The starting addresses of the memory blocks to be dumped.

Hl,H2,H3,H4
The ending addresses of the memory blocks to be dumped.
NOTE
If no memory is to be dumped, each limit
(Ll,L2,L3,L4,Hl,H2,H3,H4) should be o.
Only one snapshot dump control block is
global label •• SPBK.

allowed.

generates

the

NOTE
Because SNPBK$
is used to
allocate
storage for
the snapshot dump control
block, all arguments except dev must be
valid
arguments for
.WORD or
.BYTE
directives.

D.2.2

Format of the SNAP$ Macro

The format of the SNAP$ macro is:
SNAP$ ctl,efn,id,Ll,Hl,L2,H2,L3,H3,L4,H4

ctl
The set of flags that control the format of the dump and the data
to be printed.
The flags are:
SC.HOR

Print the dump header.

SC.LUN

Print information on all assigned LUNs.

SC.STK

Print the user stack.

SC.OVL

Print information
segments.
D-7

about

all

loaded

overlay

MEMORY DUMPS
SC.WRD

Print the
Radix-SO.

requested

memory

octal

words

and

SC.BYT

Print the
ASCII.

requested

memory

octal

bytes

and

efn
The event flag to be used to synchronize your program and PMD. A
Wait-For-Single-Event-Flag
directive is always generated to
perform synchronization.

id
A number that identifies the snapshot dump. Because dumps can be
requested at different times and under different conditions, this
ID is used to identify the place or reason for the dump.
Ll,L2,L3,L4
The starting addresses of memory blocks to be dumped.
Hl,H2,H3,H4
The ending addresses of memory blocks to be dumped.
NOTES

D.2.3

If no memory is to be dumped, each limit
(Ll,L2,L3,L4,Hl,H2,H3,H4) should be o.

You can set the control flags in
any
combination;
they
are
not
mutually
exclusive. Thus, any number of options can
be
obtained;
for
example,
SC.HDR!SC.LUN!SC.WRD prints
the
header,
LUNs, and the requested memory in word octal
and Radix-50 mode.

Arguments should be specified
only
override the information already in
snapshot dump control block.

Because SNAP$ generates instructions to move
data into the snapshot dump control block,
its arguments must be valid source operands
for MOV instructions.

to
the

Example of a Snapshot Dump

The sample program shown in Example D-2 causes two snapshot dumps to
be printed directly on LPO:.
The first dump uses the parameters
defined in the snapshot dump control block. The header is generated,
and the data in relative locations BLK to BLK+220 is displayed, in
word octal and Radix-50.
The identification on the dump is 1.
The second dump causes the data in the locations BLK to BLK+220 to be
displayed in byte octal and ASCII.
A header is also generated. The
dump identification is 64 (100 octal).
Figures D-3 and D-4 show the
dumps generated by the sample program.

D-8

SNPTST - TEST SNAP DUMP AND PMD MACRO Ml010
1
2
3
4 000000
1,)

000036
000041
000044

123
124
000

116
123

120
124

03-SEP-76 15:57

BLK:
BUF:

7 000046
8

000216

START:
012700

000036'

9 000222

10 000226
11 000412
12

CJ
I
\.0

000004
000046'

SNPTST - TEST SNAP DUMP AND PMD MACRO MlOlO
SYMBOL TABLE
BLK
BUF
IE.ACT:=
SB.CTL=
SB.DEV=

OOOOOOR
000036R

SB.EFN= 000006
SB. ID = 000010
SB.LMl= 000012
SB.PMD= 000032
SB.ONT= 000004

****** GX
000000
000002

ABS.

000000
000414
ERRORS DETECTED:

PAGE 1

.TITLE
.IDENT
.MCALL
SNPBK$
.ASCIZ

SNPTST - TEST SNAP DUMP AND PMD
/01/
SNPBK$,SNAP$,CALL
LP,O,SC.HDR!SC.OVL!SC.WRD,l,l,BLK,BLK+220
/SNPTST/

.EVEN
SNAP$
MOV
CALL
SNAP$
IOT
.END

#BUF,RO
$CAT5
#SC.HDR!SC.OVL!SC.BYT,,#100
START

03-SEP-76 15:57

3:
3:

t:lil

PAGE 1-1

SC.BYT=
SC.HOR=
SC.LON=
SC.OVL=

000040
000001
000002
000004

SC.STK= 000010
SC.WRD= 000020
START
000046R
$CAT5 = ****** GX

000
001
0

VIRTUAL MEMORY USED:
1335 WORDS
( 6 PAGES)
DYNAMIC MEMORY AVAILABLE FOR 30 PAGES
ASSEMBLY TIME (ELAPSED):
00:00:14
SNPTST,SNPTST=SNPTST

Example D-2

Sample Program That Calls for Snapshot Dumps

$DSW
$$$T2
•• SPBK
.•• SNP=

****** GX
000027
OOOOOORG
000032

~
~

:i:
~

MEMORY DUMPS
Example D-3

Sample Snapshot Dump (in Word Octal and Radix-50)
SNAPSHOT DUMP

ID: 1

TASK: TT6

TIME: S-OCT-76 1S:06

PC: OOOS22
REGS:

RO - 000000

Rl -

R4 -

RS - 000000

TASK STATUS:

000000

100104

R2 - 000000

R3 - 140130

SP -

PS - 170000

000304

MSG -CHK STP WFR REM MCR

EVENT FLAG MASK FOR 1-16> 000001
CURRENT UIC:

[007,001]

PRIORITY: DEFAULT LOAD DEVICE - DBO:

DSW: 1.

SO.

RUNNING - SO.

I/O COUNT: O.

TI DEVICE - TT6:

LBN: 1,160034

FLOATING POINT UNIT
STATUS RO
Rl
R2
R3
R4
RS

000000

000000
000000
000000
000000
000000
000000

OVERLAY SEGMENTS LOADED AND RESIDENT LIBRARIES MAPPED
STARTING RELATIVE BLOCK: 000002

BASE: 000000

LENGTH: 0014S4

TASK IMAGE

PARTITION: GEN
000300
000310
000320
000330
000340
000350
000360
000370
000400
000410
000420
000430
000440
000450
000460
000470
000500
000510
000520

001051
000000
OOOS24
000000
131574
000000
001037
012746
017646
000002
012746
005046
012746
062766
000002
104377
000046
016746
104377

000001
000001
000000
000000
04 7123
016746
104377
000304
000000
017666
0002S07
005046
000336
000002
000002
103006
001402
177576
012700

VIRTUAL LIMITS: 000304 00002S
000001
000000
000000
052120
177734
103456
012746
062766
000002
104377
005046
017646
000002
012746
022737
000261
012746
000342

050114
000304
000000
063014
052123
012746
005046
000336
000002
000002
01343S
005046
000000
017666
003413
177771
000405
001051
004767

D-10

000524

u L36

HT
PMD
LUK MSX MS$
DlN 7T CTF
MW U61 UYF AXB
CTF D6 CTF EV
EBV
PLV
B!
B
B EBB
B!
CTF 31 U61 UX/!
AXB AXB AXB AXB!
CTF EV EBV
PLV
B
B EBB!
B
B CTF AEC!
U61 UQO FBO BI!
8 SJ DQ FU!
DlN SF CTF M3!
U61 CSH EZ AWl!

MEMORY DUMPS
Example D-4

Sample Snapshot Dump (in Byte Octal and ASCII)
SNAPSHOT DUMP

ID: 64

TASK: TT6

TIME: 5-0CT-76 15:06

PC: 000716
REGS:

RO - 000345

Rl - 074400

R2 - 000120

R3 - 140130

R4 - 000000

RS - 000000

SP - 000304

PS - 170000

TASK STATUS:

MSG -CHK STP WFR REM MCR

EVENT FLAG MASK FOR 1-16> 000001
CURRENT UIC:

[007001]

DSW: 1.

PRIORITY: DEFAULT - 50.
LOAD DEVICE - DBO:

RUNNING - 50e

I/0 COUNT: O.

TI DEVICE - TT6:

LBN: 1,160034

FLOATING POINT UNIT
STATUS - 000000
RO
Rl
R2
R3
R4
RS

000000
000000
000000
000000
000000
000000

OVERLAY SEGMENTS LOADED AND RESIDENT LIBRARIES MAPPED
STARTING RELATIVE BLOCK: 000002
STARTING RELATIVE BLOCK: 000004

BASE: 000000
BASE: 001454

LENGTH: 001454
LENGTH: 000264

(continued on next page)

D-11

MEMORY DUMPS
Example D-4 (Cont.)

Sample Snapshot Dump (in Byte Octal and ASCII)

TASK IMAGE
PARTITION: GEN
000300
000310
000320
000330
000340
000350
000360
000370
000400
000410
000420
000430
000440
000450
000460
000470
000500
000510
000520

051
000
124
000
174
000
037
346
246
002
346
046
346
366
002
377
046
346
377

002
000
001
000
263
000
002
025
037
000
025
012
025
145
000
210
000
035
210

001 000
001 000
000 000
000 000
123 116
346 ·035
377 210
304 000
000 000
266 037
107 005
046 012
336 000
002 000
002 000
006 206
002 003
176 377
300 025

VIRTUAL LIMITS: 000304 - 000524
045 000
100 000
000 000
000 000
120 124
334 377
056 207
346 025
366 145
002 000
377 210
046 012
246 037
002 000
346 025
337 045
261 000
346 025
342 000

114
304
000
014
123
346
046
336
002
002
035
046
000
266
013
371
005
051
367

120
000
000
146
124
025
012
000
000
000
207
012
000
037
007
377
001
002
011

D-12

LP!

D !

!T
f!
! 3 SN PT ST!
f \
f
&
!f D f
ve
!&
6
!f G
!& & & & !
!f
&
!ve
6
f
%y
r
!&
f
!f
@ b
w !
A

APPENDIX E
RESERVED SYMBOLS

Several global symbols and program section namesl are reserved for use
by TKB.2 Special handling occurs when TKB encounters a definition of
one of these names in a task image.
The definition of a reserved global symbol in the root segment causes
a word in the task image to be modified with a value calculated by
TKB. The relocated value of the symbol is taken as the modification
address.
The following global symbols are reserved by TKB:
Global
Symbol

Modification
Value

. FSRPT

Address of file storage region work area (.FSRCB) •

• MBLUN

Mailbox logical unit number •

• MOLON

Error message output device •

.NLUNS

The number of logical units used by the task,
including the message output and overlay units.

• NOVLY

The overlay logical unit number •

N.OVPT

Address of overlay run-time system work area (.NOVLY).

.NSTBL

The address of the segment description tables.
This
location is modified only when the number of segments
is greater than one.

• ODTLl

Logical unit number for the ODT terminal device TI: •

.ODTL2

Logical unit number for the
CL:.

ODT

line

printer

not

device

1. In RSX .... HM and ::~'.X...::1-,J.M.;Pl.USr absolute sections
(ASECTs)
and both
blank and named control sections {CSECTs) are supplanted by program
sections (PSECTs).
The .PSECT assembler directive eliminates the need
for
.ASECT and .CSECT directives, except for compatibility with other
systems. This manual refers to all sections as program sections,
unless the specific characteristics of ASECTs or CSECTs apply.

2. All symbols and program section names containing a period (.) or
dollar sign ($) are reserved for DIGITAL-supplied software.

E-1

RESERVED SYMBOLS
Modification
Value

Global
Symbol
• SUMLl

P/OS standard utility module LON •

• PTLUN

Logical unit number for plotter/graphics software •

$0TSV

Address of Object Time System work area ($0TSVA).

• TRLUN

The trace subroutine output logical unit number •

• USLUl

Logical unit number for special purpose user software •

• USLU2

Logical unit number for special purpose user software •

$VEXT

Address of vector extension area {$VEXTA) •

TKB reserves the following program section names.
In some cases, the
definition of a reserved program section causes that program section
to be extended if you specify the appropriate option.
Source
Location

Section
Name

TKB

$$ALER

Description
Contains code to process or trap Overlay Run-time
System segment load errors.
Provides named areas
in the task for the FORTRAN-IV Object Time System
and the RSX-llM Overlay Run-time System.

thie /s~gment aut;oload;

·oontaI·ns,:

wi~thdut ·~-.' 1a:tliid1 ;D-'.space•

1·

l .'

$$AI~VD

<·

: ·~ t'

v;ec'.tors

for

~· t

i .: 1 . : ,
:
' ''
. .
.
;
qont~ins .:· -q~ej . :D:-15;Pace: : ·p~rtiions. : ·of , the
'

•i

:'.

;

tasks

;

. ': ,

se<1men:t

auit;olioa'd';'.vedtlo!r:ls .1i'nl ad,.»Il- [a:nd iD-!Space: task;

. Contains ~the: J...:s·pace· portions i of the segment
autQloa(l. ~eotor.s .in an I- and. o....s;pace task.
TKB

$$AUTO

Contains code to determine if a called subroutine
in an overlay segment is already in memory or if
that overlay segment should be read into memory
before control is passed to the subroutine that is
called.

Input
Module

$$DBTS

This symbol should appear in the debugger
module with the symbol $DBTS as follows:
.PSECT

input

$$DBTS

$DBTS::
.PSECT
The task builder extends $$DBTS and fills it with
time stamp information followed by the filename
information of the .STB file.
SYS LIB

$$DEVT

The extension length (in bytes)
the formula:
EXT

is calculated from

= <S.FDB+52>*UNITS

The definition of S.FDB is obtained from the root
segment symbol table, and UNITS is the number of
logical units used by the task, excluding the
message output, overlay, and ODT units.

E-2

RESERVED SYMBOLS
Source
Location

Section
Name

SYSLIB

$$FSR1

The extension of this section is specified by
ACTFIL option.

the

SYSLIB

$$1081

The extension of this option is specified
MAXBUF option.

the

TKB

$$IOB2

A zero length .PSECT containing a label,
IOBFND,
that is stored in the work area offset, W.BEND,
representing the upper bound of the I/O buffer,
$$IOB1.
TKB uses $$IOB2 as a boundary value to
determine whether the I/0 buffer has overflowed.

TKB

$$LOAD

Overlay manual load routine.

TKB

$$MRKS

Contains code to properly mark those segments that
are not needed any longer or have been overlaid by
another segment as being out of memory.
This
ensures that a fresh copy of the overlay segment
will be read in the next time the overlay segment
is needed.

SYSLIB

$$0BF1

FORTRAN OTS uses this area to parse array type
format
specifications.
This section can be
extended by the FMTBUF keyword.

TKB

$$0BF2

A zero length .PSECT containing a label, OBFH,
that is stored in the work area offset, W.OBFH,
which represents the upper bound of the run-time
format
buffer,
$$0BF1.
TKB uses $$0BF2 to
determine whether the run-time format buffer has
overflowed.

TKB

$$0VDT

The Overlay Run-time System impure data area. The
symbol
.NOVPT in low memory points to this area.
This area defines the operational parameters with
which the Overlay Run-time System operates on
disk-resident
and
memory-resident
overlay
structures.

TKB

$$0VRS

The .ABS. program section that redefines the
Overlay Run-time System impure data area with
different symbols, defined as offsets and relative
to zero.
These offsets are necessary for proper
linkages between the subroutines in the Overlay
Run-time System.
This program section is never
included in the memory allocation of the task
because of its absolute program section attribute.

TKB

$$PDLS

Cluster library service routine.

TKB

$$RDSG

Contains the code that reads into memory the
overlay segment selected by the code contained in
the programs section $$AUTO.

TKB

$$RGDS

Contains the region descriptors
libraries referred to by the task.

TKB

$$RTQ

Defines the PSECT used for selective enabling of
AST recognition in the Overlay Run-time System.
$$RTQ is 0 in length if $AUTOT is not included.

Description

E-3

for

resident

RESERVED SYMBOLS
Source
Location

Section
Name

TKB

$$RTR

Defines the PSECT used for selective disabling of
AST recognition in the Overlay Run-time System.
$$RTR is 0 in length if $AUTOT is not included.

TKB

$$RTS

Contains the return instruction.

TKB

$$SGDO

Contains the program section
segment descriptors.

TKB

$$SGD1

Contains the task segment descriptors.

TKB

$$SGD2

Contains a .WORD
descriptors.

FORTRAN

$$TSKP

TKB fills in the following words in the PSECT:

TKB

$$WNDS

Description

adjoining

following

the

task

segment

•

APR bit map in word $APRMP

•

Task offset into region in word $LBOFF

•

Maximum physical read/write memory
task in word $MXLGH

needed

for

•

Maximum physical read-only
task in word $MXLGH+2

needed

for

•

Task extension in 32-word blocks in word $LBEXT

memory

Contains task window descriptors

E-4

APPENDIX F

IMPROVING TASK BUILDER PERFORMANCE

This appendix contains procedures to assist you in maximizing
Builder (TKB) performance. These procedures include:

Task

•

Evaluating and improving TKB throughput

•

Modifying command switch defaults to provide a more
user interface

efficient

•

Using the Slow Task Builder when
required

space

These procedures assume
features not found
in
Appendix G.

that the
the Fast

large

work

file

program to be linked requires
Task Builder
(FTB) described in

Using the procedures described in this appendix may require relinking
TKB.
You can do this only in a system that has, as a minimum, a 14K
user-controlled or system-controlled partition.
In some cases, you
can make the modifications without relinking by using the binary patch
program ZAP (see the RSX-11 Utilities Manual).
Modifications to the TKB build file imply one or more of the following
files located under UFO [1,24] (mapped) or [1,20] (unmapped):
,RSX"'."'llM sys terns :
'.I'KBBLD.CMD
ST'K:SL,U. CMD",

These files reside on the disk containing the utility object files.

F.l

EVALUATING AND IMPROVING TASK BUILDER THROUGHPUT

Task Builder throughput is determined by three factors:
•

The amount of disk latency incurred because of overlays

•

The amount of memory available for table storage

•

The amount of disk latency due to input file processing

The following sections outline methods
each of these last two cases.

F-1

for

improving

throughput

IMPROVING TASK BUILDER PERFORMANCE
F.1.1

Table Storage

The principal factor governing TKB performance is the amount of memory
available for table storage.
To reduce memory requirements, a work
file is used to store symbol definitions and other tables. This work
file cannot exceed 65,543 bytes. As long as the size of these tables
is within the limits of available memory, the contents of this file
are kept in memory and the disk is not accessed.
If the tables exceed
this limit, some information must be displaced and moved to the disk,
degrading performance accordingly.
You can gauge work file performance by consulting the statistics
portion of the TKB map.
The map displays the following parameters:
Number of work file references -- Total number of
• work
file data was referred to.

times

that

file reads -- Number of work file references
• Work
resulted in disk accesses to read work file data.

that

file writes -- Number of work file references
• Work
resulted in disk accesses to write work file data.

that

•

Size of core pool -- Amount of in-core table storage in words.
This value is also expressed in units of 256-word pages
(information is read from and written to disk in blocks of 256
words) •

•

Size of work file -- Amount of work file storage in words.
If
this value is less than the pool size, the number of work file
reads and writes is O.
That is, no work file pages are
removed to the disk.
This value is also expressed in pages
(256-word blocks).

•

Elapsed time -- Amount of time required to build the task
image and output the map.
This value excludes ODL processing,
option processing, and the time required to produce the global
cross-reference.

You can reduce the overhead for gaining access to the work file in one
or more of the following ways:
•

By increasing the amount of memory available for table storage

•

By placing the work file on the fastest random access device

•

By decreasing system overhead required to gain access
file

•

By reducing the number of work file references

the

You can increase the amount of table storage by installing TKB in a
larger partition or,
if TKB is running in a system-controlled
partition, by using the INSTALL/INC keyword to allocate more space.
In a system that includes support for the Extend Task directive, TKB
automatically increases its size if it is checkpointable and installed
in a system-controlled partition.
You set the maximum limit. You can
increase this maximum by issuing the MCR command SET /MAXEXT.
Increasing the proportion of resident dynamic memory reduces the
amount of I/O necessary for access to TKB internal data structures.
As stated above, once the resident memory has been filled,
the data
structures overflow into a temporary work file on the device assigned

F-2

IMPROVING TASK BUILDER PERFORMANCE
to the work file logical unit number.
This logical unit number
(W$KLUN)
is specified in the build command file.
Preferably, this
unit number should be assigned to a device other than the system
device, for example a fixed-head disk.
Displacement of pages to the work file is done on a
least recently
used basis. The work file extends automatically as necessary to hold
all pages displaced. The parameter W$KEXT is provided in the build
command file of TKB and defines the file extension properties.
A
negative value indicates that the extend is noncontiguous; a positive
value indicates that the extend is contiguous.
If a contiguous extend
fails, a noncontiguous request is attempted;
if a noncontiguous
extend fails, a fatal work file I/O error is reported.
As long as the
work file remains contiguous, a higher access rate can be obtained.
It is not possible to state exactly how many symbols TKB can process,
because there are many data structures included in virtual memory.
The following is a list of the structures that are stored in the
virtual memory.
All the sizes given are approximate only (sizes vary
with characteristics of the task being built and may vary from release
to release).
Structure Name

Description

Approximate Size
(in words)

Segment Descriptor

Contains listhead
sizes, the pointers
defining the overlay
tree, the segment name.
Part of this structure
becomes the segment
descriptor in the
resultant task image.

80.

P-section Descriptor

Contains the name,
address size, and
attributes of a
p-section.

10.

Symbol Descriptor

Contains symbol name,
value, flags, and
pointers to defining
segment and program
section descriptors.

(nonoverlaid task)

15.

(overlaid task)

Element Descriptor

Contains module
name, ident, filename,
count of program
section and some
flags.

8.-18.

Control Section
Mapping Table

Table of program
section size and
program section
descriptor addresses.

Two words per
program section in
each module

The maximum usage of virtual memory occurs during phase three of TKB,
when the symbol table is built.
However, phase one makes significant
use of virtual memory when an overlaid task is being built.
It is at
this point that all the segment descriptors are allocated, as well as
an element descriptor for every file name encountered during the
parsing of the tree description.
In addition, a p-section descriptor
is produced for every .PSECT directive encountered in the overlay
description.

F-3

IMPROVING TASK BUILDER PERFORMANCE
The parsing of the overlay description also makes use of dynamic
memory during the processing of each directive.
This memory is
released upon completion of the analysis;
during the analysis,
however, the whole tree description must fit into the resident portion
of the storage.
If sufficient storage cannot be obtained in the
resident
dynamic memory, the error message NO DYNAMIC STORAGE
AVAILABLE is returned. The method for increasing the ratio of dynamic
storage to virtual memory can be applied here, possibly to allow a
task with a large overlay description to be built.
The amount of memory required during analysis depends on:
•

The number of directives

•

The length of .FCTR lines

•

The number of
parentheses)

•

The number of file names encountered

operators,

that

is,

commas,

dashes,

and

TKB links all DEC-supplied tasks in a 14K partition.
There are a number of ways to reduce the amount of virtual memory
required during the build of a specific task.
Reducing the data
structures in virtual memory also increases the speed of searching the
tables and reduces the amount of paging to the work file.
1.

Extract object modules by name from relocatable object
libraries (for example., LIBRY/LB:MODl:MOD2). This technique
requires smaller element descriptors and fewer file name
descriptors and is also faster because there are fewer files
to open and close.

Use concatenated object
above.

Use shared regions (resident libraries and common areas)
for
language and overlay run-time systems and file control
services. Such use of shared regions allows symbols and
p-sections to be defined only once, rather than on multiple
branches of the tree.

Place modules that occur on parallel branches of the tree in
a common segment (for example, closer to root) for the same
reasons as in 3 above.

Use the /SS switch on symbol table files (.STB) that describe
absolute symbol definitions so that only those symbols
referenced are extracted from the module.

Minimize the number of segments and keep the tree balanced.
For example,
if one segment is very long, there is no value
in putting a tree structure in parallel unless creating one
segment in parallel would be longer.

modules

for

the

same

reasons

In addition to the above, a version of TKB can be built which has less
throughput but requires less virtual memory per element than TKB.
This version is built using the command file STKBLD.CMD supplied on
the RKOS utility disk, or the RK06 and RP system disks under UFD
[1,20) (unmapped) or [1,24) (mapped).

F-4

IMPROVING TASK BUILDER PERFORMANCE
There are four error
system:

messages

associated

with

the

virtual

memory

•

NO DYNAMIC STORAGE AVAILABLE.
This error occurs when there is
insufficient
resident
storage
for
creating some data
structures. As much as possible of the data already allocated
(all unlocked pages)
has been paged to the work file, but
there is still not enough free memory. Such a situation might
arise during the analysis of the overlay description, early in
the task-build run, and particularly if it is a complex tree.
Reducing the ODL and extending the Task Builder memory
allocation
(see
above)
are
the
recommended
recovery
procedures.

•

UNABLE TO OPEN WORKFILE.
are:

The probable causes

Device assigned to logical unit 8 of the
not mounted.

of
Task

this

error

Builder

The device is not FILES-11.
There is no space on the volume.
The device is off line, not ready, write locked, or faulty.
There is no such device.
The MCR function LUN ••• TKB may be used to determine
device the Task Builder is attempting to use.
•

WORKFILE I/O ERROR.

which

The probable causes of this error are:

Hardware error (for example, parity error on the disk).
Device is not ready, or is write-locked.
An extend failure has occurred (for example,

the

disk

full) •

•

NO VIRTUAL MEMORY STORAGE AVAILABLE. The addressable limit of
the virtual memory has been reached.
There is no recovery
other than to reduce the virtual memory requirements of the
task being built along the lines suggested earlier.

The work file normally resides on the device from which TKB was
installed.
You can change the device by reassigning logical unit 8
through the Monitor Console Routine or by editing the build file and
relinking TKB.
System overhead for work file accesses is incurred in translating a
relative block number in the file to a physical disk address.
To
minimize this overhead, TKB requests disk space in
contiguous
increments.
The size of each increment is equal to the value of
symbol W$KEXT defined in TKB build file.
A larger positive value
causes the file to be extended in larger contiguous increments and
reduces the overhead required to gain access to the file.
The
increment should be set to a reasonable value because TKB resorts to
noncontiguous allocation whenever contiguous allocation fails.
;.b
You can reduce the size of the work file by:
Linking your task to a core-resident library containing
• commonly
used routines
(for example, FORTRAN Object Time
System) whenever possible

F-5

IMPROVING TASK BUILDER PERFORMANCE
•

Including common modules, such as components of an object time
system, in the root segment of an overlaid task

•

Using an object library or file of concatenated object modules
if many modules are to be linked

When you use either of the last two procedures, system overhead is
also significantly reduced because fewer files must be opened to
process the same number of modules.
You can reduce the number of work file references by eliminating
unneeded output files and cross-reference processing, or by obtaining
the short map.
In addition, you can usually exclude selected files,
such as the default system object module library, from the map.
In
this case you can obtain, and retain, a full map at less frequent
intervals.

F.1.2

Input File Processing

The procedures for minimizing the size of the work file and number of
work file accesses also drastically reduce the amount of input file
processing.
A given module can be read up to four times when the task is built:
•

To build the symbol table

•

To produce the task image

•

To produce the long map

•

To produce the global cross-reference

Files that are excluded from the long map are read only twice.
The
third and fourth passes are eliminated for all modules when you
request a short map without a global cross reference.

F.1.3

Summary

In summary, you can
throughput:

use

the

following

procedures

improve

TKB

table

•

Use the INSTALL/INC or EXTTSK keyword to allocate
space.

•

Increase maximum task size by raising
dynamic task extension.

•

Reduce disk latency by placing the work file
random access device.

•

Reduce system overhead by modifying the command file
allocate work file space in larger contiguous increments.

•

Decrease work file size by
using
resident
concatenated object files, and object libraries.

F-6

the

system
on

limit
the

for

fastest
to

libraries,

IMPROVING TASK BUILDER PERFORMANCE

F.2

•

Decrease work file size by including common modules
root segment of an overlaid task~

into

the

•

Decrease the number of work file references by eliminating the
map and global cross-reference, obtaining the short map, or
excluding files from the map.

MODIFYING COMMAND SWITCH DEFAULTS

The default switch settings and values provided by the Task Builder as
released may not suit the requirements of all installations. For
example, the default /-EA (no KEll Extended Arithmetic Element)
would
be unsatisfactory at an installation that made frequent use of this
hardware.
You can thus tailor the switch defaults by altering the contents of
the words that contain initial switch states. Modifying TKB in this
way is a 3-step process:
1.

Consult Tables F-1 through F-4 to determine the
and bit to be altered.

switch

word

Edit the appropriate TKB command file to include the switch
word modification through a GBLPAT keyword referring to the
global switch word name.

Relink TKB using the modified command file.

The command files for system tasks, as provided with the released
system, require the standard set of TKB defaults;
therefore, you must
retain and use an unmodified copy of TKB whenever such tasks are
relinked.
You use Tables F-1 through F-4 to alter the defaults as follows:
1.

You identify the switch and the file to which it applies.

You consult the switch category entry in each table to locate
the applicable switch words.

You look at the
associated bit.

You specify the revised value and switch word as arguments in
a GBLPAT keyword.

You relink TKB to produce
appropriate defaults.

switch

settings

find

version

the

switch

containing

For example, to change the TKB Extended Arithmetic Element default
/EA, perform the steps described below.

and

the
to

By consulting Table F-1, you determine that two switch words, $DFSWT
and $DFTSK, contain task file switches.
Of these, $DFTSK contains the
default setting for the /EA switch in bit 13. Setting this bit to 1
changes the initial switch setting to /EA.
This new value is combined
with the initial contents to yield the revised setting 120002.
The
required keyword input is:
TKB>GBLPAT=TASKB:$DFTSK:l20002

F-7

IMPROVING TASK BUILDER PERFORMANCE
NOTE
The setting of bit positions not listed
in the tables must not be altered.
The only switches that have associated values are /AC and /PR.
In
these cases, the value is the number of the initial APR used to map
the task. You can alter the default by changing the value of the
GBLDEF keyword for the symbol D$FAPR in TKB build file.
Only values 4
or 5 can be used.
Table F-1
Task File Switch Defaults
Switch Category:
Switch Word:

Task file

$DFSWT

Initial Contents:

Switch Settings:
Bit

Initial
State

/-XT Not abort after n diagnostics

/-SQ Not sequential PSECT allocation

0
0

/-FU Not full overlay tree search
/RO Recognize memory-resident overlay
operator.

Switch Category:
Switch Word:

Initial
Condition

Task file

$DFTSK

Initial Contents:

100002

Switch Settings:
Bit

Initial
State

Initial
Condition

/-CP, /-AL Not checkpointablel

/-FP Not Floating Point Processor

/-EA Not Extended Arithmetic Element

1. The combination of not checkpointable with
checkpoint
allocation (100000) is illogical and should not be used.
(continued on next page)

F-8

IMPROVING TASK BUILDER PERFORMANCE
Table F-1 (Cont.)
Task File Switch Defaults
Switch Settings:

(Cont.)

Bit

Initial
State

/HD

/-CM Not compatibi 1i ty mode

/-DA No debugging aid

/-PI Not position independent

/-PR Not privileged

/-TR No trace

/-PM No Postmortem Dump

/-SL Not slave task

/SE

/-AC Not ancillary control processor

/-AL No checkpoint allocation

Initial
Condition
Header

Send to task allowed

j~~;
Switch Category:
Switch Word:

Task File

$DFTSO

Initial Contents:

000010

Switch Settings:
Initial
State

Bit

Initial
Condition

/~~< ·:i.~·/~.:{i~.1~~'1:el.:;'./~lj/{l,;::.:,:z~·~fi,• :~/~~~~:~.~'.~i,;;/<iieairJeJer
3

/-SG RO and RW PSECTs

F-9

IMPROVING TASK BUILDER PERFORMANCE
Table F-2
Map File Switch Defaults
Switch Category:
Switch Word:

Map file

$DFLBS

Initial Contents:

120000

Switch Settings:

Bit

Initial
State

/-MA Do not include system library and STB
files in map

Switch Category:
Switch Word:

Initial
Condition

Map file

$DFMAP

Initial Contents:

2040

Switch Settings:

Bit

Initial
State

Initial
Condition

/SH

Short map

/SP

Spool

/-CR No CREF

/WI

Wide format

Table F-3
Symbol Table File Switch Defaults
Switch Category:
Switch Word:

Symbol table file

$DFSTB

Initial Contents:

Switch Settings:

Bit

Initial
State

Initial
Condition

/HD Build task with header

/-PI

Task is not position independent

F-10

IMPROVING TASK BUILDER PERFORMANCE
Table F-4
Input File Switch Defaults
Switch Category:
Switch Word:

Input file

$DFINP

Initial Contents:

000100

Switch Settings:

F.3

Bit

Initial
State

Initial
Condition

/MA Include file contents in map

/CC File contains two or more concatenated
object modules

THE SLOW TASK BUILDER

TKB.TSK uses a symbol table structure that can be searched quickly,
but which requires more work file space than that of previous
versions.
You may thus receive the following message in some
instances:
NO VIRTUAL MEMORY STORAGE AVAILABLE
If this occurs, you should try to reduce the work file size by using
the procedures described in Section F.l.
If these procedures do not
sufficiently reduce the work file size, you can link another version
of TKB, the Slow Task Builder. This version requires less storage,
but runs considerably slower than the other versions.
The build file
is STKBLD.CMD, which resides on the same device and UFD as the other
Task Builder command files.
The default name of STK.TSK, the Slow
Task Builder, is
••• TKB.
It may be convenient to install the Slow
Task Builder with a different name if you want to use both Task
Builders in your system.

F-11

APPENDIX G
THE FAST TASK BUILDER

The Fast Task Builder (FTB) allows you to build simple tasks about
four times faster than the Task Builder (TKB).
However, FTB has
limited functionality.
It can only link single-segment, nonprivileged
tasks, and supports a limited number of switches and options.
The (FTB) is intended for use as a load-and-go type
contains very few options and does not support:
•

New map format

•

Overlaid programs

•

FORTRAN virtual arrays

•

Production of symbol table files

•

Creation of resident libraries

•

Privileged tasks

•

Cluster libraries

linker.

The only supported switches are:

• /SP on map file

(default

/SP)

• /CP on task file (default /CP)l
• /EA on task file (default /-EA)
• /MM on task file (default /MM)
• /FP on task file (default /FP)
• /DA on input or task image (default
• /LB on an input file in the form:

/-DA)

>TKB TASK=PROG.OBJ,LIBRARY/LB
but not in the form:
>TBK TASK=PROG.OBJ,LIBRARY/LB:MODULE

1. No checkpoint space is allocated in the task image file.
G-1

THE FAST TASK BUILDER
The supported option inputs are:

• ASG (same defaults as TKB)
• STACK (same default as TKB)

• UNITS
• TASK (same default as TKB)
• EXTSCT
• ACTFIL (same default as TKB)
• MAXBUF (same default as TKB)
• LIBR

• COMMON
• RESLIB
•

RE SC OM

(same defaults as TKB)
(same defaults as TKB)

• SUPLIB
• RESSUP
FTB supports linking to shared regions but not
region.
FTB cannot link to clustered libraries.
to
.supel:~isor\.-.mod~.
'.l!1 i~f(~~~~~i~·; . ;~i~~~~:~!
su,perviso;r:...mode 'ljcb~aip;'.i,e~r~·: · '' "rn' .,.

r,t

_,'

'·>'}'«'i;:,.,

~··<',"

shared

,;~~~~~

:-,k'~i'o;.-:;\

FTB allocates symbol table space from the end of its image to the end
of the partition.
It does not have a virtual symbol table. An Extend
Task or equivalent of BK is recommended.
FTB does not dynamically
extend itself at run time.
FTB runs approximately four times faster than TKB on an 11/70 with
RP04s when TKB is running with a totally resident symbol table.
In
smaller systems with slower disks, the ratio should be much higher.
FTB also supports shared regions.
FTB uses asynchronous system traps
support in the Executive.

(ASTs) and therefore

G-2

requires

AST

APPENDIX H
ERROR MESSAGES

The Task Builder (TKB) produces diagnostic and fatal
Error messages are printed in the following forms:

error

messages.

TKB -- *DIAG*-error-message
or
TKB -- *FATAL*-error-message
Some errors are correctable when command input is from a terminal.
In
such a case,
a diagnostic error message can be printed, the error
corrected, and the task-building sequence continued.
However, if the
same error is detected
in an indirect command file, a correction
cannot be made and the Task Builder aborts.
Some diagnostic error messages merely advise you of an unusual
condition.
If you consider the condition normal for your task, you
can install and run the task image.
NOTE
The Task
Builder
exits
with
two
statuses:
it returns an ERROR status
when it encounters a diagnostic error,
and a SEVERE ERROR when it encounters a
fatal error.
(For more
information
about the Exit-With-Status directive,
see
the
RSX-llM/M-PLUS
Executive
Reference Manual.)
This appendix tabulates the error messages produced by TKB.
Most of
the messages are self-explanatory.
In some cases, the line in which
the error occurred is printed.
A Software Performance Report (SPR) should be submitted to DIGITAL in
cases where the explanation accompanying a message refers to a system
error.

Allocation failure on file file-name
TKB could not acquire sufficient disk ~pace to store the task
image file,
or did not have write-access to the UFD or volume
that was to contain the file.

H-1

ERROR MESSAGES
Blank P-section name is illegal
overlay-description-line
The overlay-description-line printed contains a .PSECT
that does not have a p-section name.

directive

Cluster library element library-name does not have null root
This is a fatal error. All libraries, except the first, must be
PLAS-overlaid and have a null root. The first library in the
group can be nonoverlaid or overlaid with a null or non-null
root.
Command I/O error
An I/O error occurs on a command input device.
be on line, or possible hardware error.)

(Device

may

not

Command syntax error
command-line
The command-line printed has incorrect syntax.
Complex relocation error - divide by zero:
module-name

module

A divisor having the value 0 was detected in a
complex
expression.
The result of the divide was set to 0.
(Probable
cause: division by a global symbol whose value is undefined.)
Conflicting base addresses in cluster library
This conflict arises when you specify APRs, for both PIC and
non-PIC libraries that are included in the cluster. See the APR
parameter as described in the CLSTR option.
This is a fatal
error.
Disk image core allocation too large
invalid-line
The minimum disk allocation specified
greater than 128.

the

invalid

line

initialize

File file-name attempted to store data in virtual section
The file contains a module that has
virtual section with data.

attempted

File file-name has illegal format
The file file-name contains an object module whose format is
valid.

not

Illegal APR reservation
An APR specified in a COMMON, LIBR, RESCOM, or RESLIB keyword
outside the range 0-7.

Illegal cluster configuration
If the cluster contains a non-overlaid library, that library must
be the first library in the cluster. Check the configuration of
the libraries in the cluster. This is a fatal error.

H-2

ERROR MESSAGES
Illegal default priority specified
option-line
The option-line printed contains a priority greater than 250.
Illegal device/volume
i nvalid-1 i ne
The
invalid
specification.

line

printed

contains

illegal

device

Illegal directory
invalid-line
The invalid line printed contains an illegal directory name.
Illegal error-severity code octal-list
System error (no recovery).
An SPR should be submitted with
copy of the message containing the octal-list as printed.

Illegal filename
invalid-line
The invalid-line printed contains a wildcard
specification.
Using wildcards is prohibited.

(*)

file

Illegal get command line error code
System error

(no recovery) •

Illegal logical .unit number
invalid-line
The invalid-line printed contains a device assignment to a unit
number larger than the number of logical units specified by the
UNITS keyword, or assumed by default if the UNITS keyword is not
used.
Illegal multiple parameter sets
invalid-line
The invalid-line printed contains multiple sets of parameters for
a keyword that allows only a single parameter set.
Illegal number of logical units
invalid-line
The invalid-line printed contains a logical unit
than 250.

number

greater

Illegal ODT or task vector size
ODT or SST vector size specified is greater than 32 words.
Illegal overlay description operator
invalid-line
The invalid-line printed contains an unrecognizable operator
in
an overlay description.
This error occurs if the first character
in a p-section or segment name is a dot (.).

H-3

ERROR MESSAGES
Illegal overlay directive
invalid-line

The invalid-line
directive.

printed

contains

unrecognizable

overlay

Illegal partition/common block specified
invalid-line

User-defined base or length is not on a 32-word boundary.
Illegal P-section/segment attribute
invalid-line

The invalid-line printed contains a program
attribute that is not recognized.

section

segment

Illegal reference to library P-section p-sect-name

A task has attempted to reference a p-sect-name existing in a
shared region but has not named the shared region in a keyword.
This error occurs when you explicitly specify an STB file as an
input file, but you have not specified the library to which the
STB file belongs in an option.
Illegal switch
file-specification

The file-specification printed
switch value.

contains

illegal

switch

Incompatible reference to library P-section p-sect-name

A task has attempted to reference more storage in a shared region
than exists in the shared region definition.
Incorrect library module specification
invalid-line

The invalid-line contains
character.

module

name

with

non-Radix-50

Indirect command syntax error
invalid-line

The invalid-line printed contains
indirect file specification.

syntactically

incorrect

Indirect file depth exceeded
invalid-line

The invalid-line printed gives the file reference
the permissible indirect file depth (2).

that

exceeded

Indirect file open failure
invalid-line

The invalid-line contains a reference to
that could not be located.

command
,

input

file

,'t

!rKB cuuld .n.ot. fi·nd. ~riough ,·,free· ·1\:ERs to ·map 'the· re.a~·..;.only .· po;~l~n.
of a . >.multius.e'r .·tas:k •·
·

H-4

ERROR MESSAGES
Insufficient parameters
invalid-line
The invalid-line contains a keyword with an
of parameters to complete its meaning.

insufficient

number

Invalid APR reservation
invalid-line
APR is specified on a keyword for an absolute library.
Invalid keyword identifier
invalid-line
The invalid-line printed contains an unrecognizable keyword.
Invalid partition/common block specified
invalid-line
A partition is invalid for one of the following reasons:
•

TKB cannot find the partition name in the host system in order
to get the base and length.

•

The system is mapped, but the base address of the partition is
not on a 4K boundary for a nonrunnable task or is not 0 for a
runnable task.

•

The memory bounds for the partition overlap a shared region.

•

The partition name is identical to the name
defined COMMON or LIBR shared region.

•

The top address of the partition for a runnable task exceeds
32K minus 32 words for a mapped system, or exceeds 28K minus 1
for an unmapped system.

•

A system-controlled partition was specified
system.

for

previously

unmapped

Invalid reference to mapped array by module module-name
The module has attempted to initialize the mapped array with
data.
An SPR should be submitted if DIGITAL-supplied software
caused this problem.
Invalid window block specification
invalid-line
The number of extra address windows specified exceeds the number
pemitted. . .~ an. ·~~.~~~~'~2·
. e~.~t:.Cl.","'?~.!l.ti?! }~~<?.C:.1<:5-L ;· ·?~n:}~q . R~~ -1} r-\~~~us;. s·~$.;~,em.:,.:/~~. u:.,.-~il;~ . :, .~P!~~. ~Y::.
a's many as. lS. ex·t:ra· ··windo,w"·bloc.ks.· · · ·
If you build a task on an RSX-llM system and specify more ·window
blocks, you get this error message, but the task will build.
However, it cannot be install·ed and run on. an RSX-llM system.
I/O error lib£ary image file
An I/O error has occurred during an attempt to open or
Task Image File of a shared region.

H-5

read

the

ERROR MESSAGES

I/O error on input file file-name
This error occurs when TKB cannot
read
an
input
file
specification (for example, when the command line is greater than
80 characters).

I/O error on output file file-name
Label or name is multiply defined
invalid-line
The invalid-line printed defines a name that has already appeared
as a .FCTR, .NAME, or .PSECT directive.
Library file filename has incorrect format
A module has been requested from a library file that has an empty
module name table.

Library library-name not found in any cluster
All task image and symbol table files to be included
elements must reside in LB: (1,1].

cluster

Library references overlaid library
invalid-line
An attempt was made to link the resident library being built to a
shared region that has memory-resident overlays.
Load addr out of range in module module-name
An attempt has been made to store data in the task image outside
the address limits of the segment.
This problem is usually
caused by one of the following:
•

An attempt to initialize a p-section
region

contained

shared

•

An attempt to initialize an absolute location
limits of the segment or in the task header

•

A patch outside the limits of the segment to which it applies

•

An attempt to initialize a segment having the NODSK attribute

outside

the

Lookup failure on file file name
invalid-line
The invalid-line printed contains a
located in the directory.

file

name

that

cannot

Lookup failure on system library file
TKB cannot find the system Library (SYO: [l,l]SYSLIB.OLB)
resolve undefined symbols.

H-6

file

ERROR MESSAGES
Lookup failure resident library file - filename.ext
No symbol table or task image file can be found
for the shared
region "filename.ext." If the shared region was linked to another
shared region, ensure that the task image of both regions and the
symbol table files exist on the same device and in the same UIC
as the UIC referenced by the option RESLIB, RESCOM, LIBR, COMMON,
}tt~$pP~,··o,:r;.,SOP,IB;.

Module module-name ambiguously defines P-section p-sect-name
The p-section p-sect-name has been defined in two modules not on
a common path, and referenced from a segment that is common to
both paths.
Module module-name ambiguously defines symbol sym-name
Module module-name references or defines a symbol sym-name whose
definition exists on two different paths, but is referenced from
a segment that is common to both paths.

·. ·looat:~n.:Sr~'~;~t0.t>~ii0b1~. .:~•uh1:>1·i:>a:Q+·,~~e:t,q·?':~·,,·
/~/ :~.:··· ·,.,·;,: ,;
,f ;j ;,!)j'f .·:·) '. :.)··.::c',,':.:-·.. ·'./.···:· t. ": ·~ :··~?. '.! / ····:<·;. ·:< '.' · :. ~: <·•·.·· :·,· ·:;· •. ~<· :.··~. ' :. ;· '•' ·.·; }·: .·.~f'.'. ~·:?,.'.··,'
ll09•·':t;Q· b;u· ..... ran:·.,,r·~ ·'ilndr. o~s·pa~:.·.ta;$:k;"and.'1:i'nk.·;:'it·<·t.~,,···'8;n"
,~~t=.fi:.~~/"'1;±,~:r:·/.·'if }s~ati'.:...c~~:t.~(in·~ ..~r(.'~.1.a;~Ji;~y,i¢· ··:v.~~i:~'..i·: . .·~:o;rrtr~:f:~/
1

.//,,, -' . ;,.··.·. .:"•:

..• ·I,1,.f?'t·aJ:;1":~,1t~. . :·tl,le;/ R~·~"7·,l·~t4~.~.1;su~:·N~r·S'~Q.n · ·. 2....;~ .·.· ;<>,·r.· .'.:·~:q·~~t;\·..
new-st:y:1e. vedtors :f<:>'r ,.th:e; ;l·l'l:>~.at:·J.l~,:

i\t ;'·l/ .."•··R..· "··,,1

··:-·;;·/,"·:"y'efr;S,~~
'sk; BU"i'rd'er'· t'o cr'.eat'e
/ '5\..,,~;/.s/!;rtie~n~'reDu'i:l:d~/~lillr;-;<-;/tasKx. ~ ,.., /",~,,,,,,./',_,
0

<Y«

,~'I,-

=/'"

.>,~);.'<

..>,,'1,.:,,:,•~

;

-i'

;-.>.>

->,,h .

.-~,,_ ..

-i.

~%,h

"~/
y

v/
0.

'~~;:

~ *:i

~;,>

Module module-name illegally defines xfr address p-sect-name addr
This message occurs under any one of the following conditions:
•

The start address printed is odd.

•

The module module-name is in an overlay segment and has a
start address.
The start address must be in the root segment
of the main tree.

•

The address is in a p-section that has not yet been defined.
An SPR should be submitted DIGITAL-supplied software caused
this problem.

Module module-name multiply defines P-section p-sect-name
•

The p-section p-sect-name has been defined more than
the same segment with different attributes.

once

A global p-section has been defined more than once with
• different
attributes in more than one segment along a common
path.
Module module-name multiply defines symbol sym-name
Two definitions for the relocatable symbol sym-name have occurred
on a common path. Or two definitions for an absolute symbol with
the same name but different values have occurred.

Module module-name multiply defines xfr addr in seg
segment-name
This error occurs when more than one module making
has a start address.

H-7

the

root

ERROR MESSAGES
Module module-name not in library
TKB could not find the module named
library.

the

switch

the

obtain

it.

the

No dynamic storage available
TKB needs additional symbol table storage and cannot
(If possible, install TKB in a larger partition.)
No memory available for library library-name
TKB could not find enough
specified shared region.

free

virtual

memory

map

No root segment specified
The overlay description did not contain a .ROOT directive.
No virtual memory storage available
Maximum permissible size of the work file is exceeded.
The user
should consult Appendix F for suggestions on reducing the size of
the work file.
Open failure on file file-name
Option syntax error
invalid-line
The invalid-line printed contains unrecognizable syntax.
Overlay directive has no operands
invalid-line
All overlay directives except .END require operands.
Overlay directive syntax error
invalid-line
The invalid-line printed contains a syntax error or references
line that contains an error.

Partition partition-name has illegal memory limits
The partition-name defined in the host system has a base
• address
alignment that
is not compatible with the target
system.
The user has attempted to build a privileged task in a
• partition
whose length exceeds the task's available address
space (SK or 12K).
Pass control stack overflow at segment segment-name
System error.
An SPR should be submitted with a copy of the
file associated with the error.

ODL

PIC libraries may not reference other libraries
invalid-line
The user has attempted to build a position-independent
region that references another shared region.

H-8

shared

ERROR MESSAGES
P-section p-sect-name has overflowed
A section greater than 32K has been created.

Required input file missing
At least one input file is required for a task build.

Required partition not specified
The PAR keyword was not used when running TKB on an RSX-110 host
system.
The keyword must contain explicit base address and
length specifications.

Resident library has incorrect address alignment
invalid-line
The invalid-line specifies a shared region that has
following problems:

one

the

•

The library references another library with
invalid address
bounds (that is, not on 4K boundary in a mapped system).

•

The library has invalid address bounds.

Resident library mapped array allocation too large
invalid-line
The invalid-line printed contains a reference to a shared region
that has allocated too much memory in the task's mapped array
area.
The total allocation exceeds 2.2 million bytes.

Resident library memory allocation conflict
keyword-string
One of the following problems has occurred:
•

More than seven shared regions have been specified.

•

A shared region has been specified more than once.

•

Non-position-independent
shared
regions
allocations overlap have been specified.

whose

memory

The invalid-line printed contains the second
.ROOT
encountered.
Only one .ROOT directive is allowed.

directive

Root segment is multiply defined
invalid-line

Segment seg-name has addr overflow:

allocation deleted

Within a segment, the program has attempted to allocate more than
32,764 words (32K-l words).
A map file is produced, but no task
image file is produced.

Segment seg-name not found for patch
The Task Builder could not locate the named segment for a
patch.
The option used was GBLPAT=X:Y:O.

H-9

global

ERROR MESSAGES

'.;·,;r·~; ·co~J.d not locate ,t!l~ ,:sYmb~i ,i.:X;1 i .l«f;Jk.1.:cu

~ .CM:PR.'.,r,~x· op.t"i:o~i~ ·

·· · ·

Symbol sym-name not found for patch
TKB could not locate symbol Y for a
used was GBLPAT=X:Y:O.

global

The

patch.

option

Task has illegal memory limits
An attempt has been made to build a task whose size exceeds the
partition boundary.
If a task image file was produced, it should
be deleted.
Task has illegal physical memory limits
mapped-array
task-image
task extension
The sum of the parameters displayed -- mapped array size, task
image size, and task extension -- exceeds 2.2 million bytes.
The
quantities are shown as octal numbers in units of 64-byte blocks.
Any resulting task image file should be deleted.
Task image file filename is noncontiguous
Insufficient contiguous disk space was available to contain the
task
image.
A noncontiguous file was created. After deleting
unnecessary files, the /CO switch in PIP should be used to create
a contiguous copy.
Task requires too many window blocks
The number of address windows required by the task and any shared
regions exceeds 8 for
RSX-llM tasks and 16 for RSX-llM-PLUS
tasks.
Task-build aborted via request
option-line
The option-line contains a request from the
task build.

user

abort

the

Too many nested .ROOT/.FCTR directives
invalid-line
The invalid-line printed contains a .FCTR directive that
the maximum nesting level (16).

exceeds

Too many parameters
invalid-line
The invalid-line printed contains a keyword with more
than required.

parameters

Too many parentheses levels
invalid-line
The invalid-line printed contains a parenthesis that exceeds
maximum nesting level (16).

H-10

the

ERROR MESSAGES
Truncation error in module module-name
An attempt has been made to load a global value greater than +127
or less than -128 into a byte. The low-order eight bits are
loaded.
Unable to open work file
The work file device is not mounted.
(The work file
located on the same device as is the Task Builder.)

usually

Unbalanced parentheses
invalid-line
The invalid-line printed contains unbalanced parentheses.
n Undefined symbols segment seg-name
The segment named contains n undefined symbols.
If no memory
allocation file is requested,
the symbols are printed on the
terminal.
Virtual section has illegal address limits
option-line
The option-line printed contains a VSECT
address plus window size exceeds 177777.

keyword

whose

base

Work file I/O error
An I/O error occurs during an attempt to reference data stored by
TKB in its work file.

H-11

TASK BUILDER GLOSSARY OF TERMS

ABSOLUTE SHARED REGION
A shared region that has the same virtual addresses in all
that refer to it=

tasks

AUTO LOAD
The method of loading overlay segments,
in which the Overlay
Run-Time routines automatically load overlay segments when they
are needed and handles any unsuccessful load requests.
AUTOLOAD VECTOR
A transfer of control instruction generated by the Task
to resolve an up-tree reference to a global symbol.

Builder

CO-TREE
One of one or more secondary tree structures within a multiple
tree overlay structure. When a co-tree's root segment contains
code or data, the root segment of the co-tree is made resident in
physical memory through calls to the Overlay Run-Time routines.
COMMON BLOCK
Another name for resident common.
DISK-RESIDENT
That which resides on disk storage until needed.
DISK-RESIDENT OVERLAY SEGMENT
An overlay segment that shares the same physical memory and
virtual address space with other segments.
The segment is read
in from disk each time it is loaded
(compare Memory-Resident
Overlay Segment) •
GLOBAL CROSS-REFERENCE
A list of global symbols, in alphabetical order,
the name of each referencing module.

accompanied

GLOBAL SYMBOL
A symbol whose definition is known outside the defining module.
HEADER
That portion of a task image that
contains
the
task's
characteristics and status.
Shared regions, although built like
a task, do not have a header.

Glossary-1

TASK BUILDER GLOSSARY OF TERMS
HOST SYSTEM
The system on which a task is built.
LOGICAL ADDRESSES
The actual physical addresses that the task can access.
LOGICAL ADDRESS SPACE
The total amount of physical memory to which the task has
rights.

access

MAIN TREE
An overlay tree whose root segment is
when the task is made active.

loaded

the

Executive

MANUAL LOAD
The method of loading overlay segments in which the user includes
explicit calls in his routines to load overlays and handles
unsuccessful load requests.
MAPPED ARRAY AREA
An area of the task's physical memory, preceding the task image,
that is used for storage of large arrays. Space in the area 1s
reserved by means of the VSECT keyword or through a Mapped Array
Declaration contained in an object module. Access is through the
mapping directives issued at run time.
MEMORY ALLOCATION FILE
The output
information
task.

file created by the Task Builder
that
lists
about the size and location of components within a

MEMORY-RESIDENT
In general, that which resides in memory all the time.
The
entity, as in the case of memory-resident overlays, may initially
reside on disk.
MEMORY-RESIDENT OVERLAY SEGMENT
An overlay segment that shares virtual address space with other
segments, but which resides in its own physical memory. The
segment is loaded from disk only the first time it is referenced;
thereafter, mapping directives are issued in place of disk load
requests.
OVERLAY DESCRIPTION LANGUAGE
A language that allows you to describe the overlay structure of a
task.

Glossary-2

TASK BUILDER GLOSSARY OF TERMS

OVERLAY RUNTIME ROUTINES
A set of system library subroutines linked as part of an overlaid
task that are called to load segments into memory.
OVERLAY SEGMENT
A segment that shares virtual address space with other
and is loaded when needed.

segments,

OVERLAY TREE
A tree structure consisting of a root segment and optionally
or more overlay segments.

one

A route that is traced from one segment in the
another segment in that tree. ,

PATH
overlay

tree

PATH-DOWN
A path toward the root of the tree.
PATH-LOADING
The technique used by the autoload method to load all segments on
the path between a calling segment and a called segment.
PATH-UP
A path away from the root of the tree.
PHYSICAL ADDRESS
The assigned byte location in physical memory, which
located in the processing unit.

usually

POSITION-INDEPENDENT REGION
A shared region that can be placed anywhere in a referencing
task's virtual address space when the system on which the task
runs has memory management hardware.
PRIVILEGED TASK
A task that has privileged memory access rights.
A privileged
task can access the Executive and the I/O page in addition to its
own partition and referenced shared regions.
PROGRAM SECTION
A section of memory that is a unit of the total allocation.
A
source program is translated into object modules that consist of
program sections with attributes describing access, allocation,
relocatability, and so forth.
REGION
A contiguous block of physical addresses in which
task, a resident common, or library resides.

Glossary-3

driver,

TASK BUILDER GLOSSARY OF TERMS

RES ID ENT COMMON
A shared region in which data resides that can be shared
or more tasks.

two

RESIDENT LIBRARY
shared region
in which single copies of commonly
subroutines reside that can be shared by two or more tasks.

used

ROOT SEGMENT
The segment of an overlay tree that,
once
memory during the execution of the task.

loaded,

remains

A task that has a header and stack and that can be installed
executed.

and

RUNNABLE TASK

SHARED REGION

A shared region is a block of data or code that resides in
physical memory and can be used by any number of tasks.
A shared
region is built and installed separately from the task.

:lm~-,~~Ait.i123~tRJY;.

: i' ·

!! ul !L! ; l)ir: l \:LI ): ; •. ! J • .• .• . 1:i;' I . . ' . · ..· . . . . ! .• ;.
,1,i·.~ l~ · l:ft ··r•·:O,. f!;A,u~N\e~~; , '*t:,hf,;t ~,0.~s,ei&..• ,th~ , N11?rlri"~1i},spit:-:rtPP~, f?'Ji~·l'iY,
!

. ::lffl:Fl,

j '

;

. . • i.

.~fl~·,~.~i .;~l :rtJ.o,:: ~fi\P• '.tP1 potri·\'11~~. :ta~~: ar~; :~r~i 1°\WPJ rnµ~;m~r.·1~[·.f~f'

SYMBOL DEFINITION FILE
The output object file created by the Task Builder that contains
the global
symbol definitions and values and sometimes program
section names, attributes, and allocations in a
format suitable
for
reprocessing by the Task Builder.
Symbol definition files
contain linkage information about shared regions.
TARGET SYSTEM
The system on which a task executes.
TASK IMAGE FI LE
The output file created by the Task
executable portion of the task.

Builder

that

contains

the

The addresses within the task.
Task addresses can range
zero through 177777(8) depending on the length of the task.

from

VIRTUAL ADDRESSES

VIRTUAL ADDRESS SPACE
That space encompassed by the range of virtual addresses that the
task uses.
VIRTUAL PROGRAM SECTION
A program section that has virtual memory allocated to
it, but
not physical memory.
Virtual address space is mapped into
physical memory at run-time by means of the mapping directives.

Glossary-4

TASK BUILDER GLOSSARY OF TERMS
WINDOW
A continuous virtual address space that can be moved to allow the
task to examine different parts of a region or different regions.
WINDOW BLOCK
A structure defined by the Task Builder that describes a range of
continuous virtual addresses.

Glossary-5

INDEX

Abort
TKB
during input, 11-4
ABORT option, 11-4
Absolute region
See Reg ion
ABSPAT option, 11-5
I AC switch, 10-5
Access-code, 2-4 to 2-5
grouping program section by,
10-36
ACP
specifying APR, 10-5
specifying task as, 10-5
ACTFIL option, 11-6
Active Page Register
See APR
Address
assigning, 2-1
concepts, 2-13
logical, 2-14
mapped system, 2-18
physical, 2-13
mapped system, 2-17
space, 2-14
virtual, 2-14
virtual and logical
coincidence, 2-15
space translation, 2-23
transfer, A-5
virtual, 2-13
mapped system, 2-17 to 2-18
virtual and logical
relationship, 2-17, 2-21
virtual space
co-tree and main tree, 3-40
disk-resident overlay, 3-1
to 3-4
division, 2-18
division by memory
management, 2-18
in overlay tree, 3-24
memory-resident overlay,
3-6
overlaid task, 3-10, 3-14
overlay, 3-5, 3-33 to 3-35
reducing usage of, 3-1
virtual space allocation,

diagram
creating ODL file, 3-36
virtual space and memory
overlaid task, 3-11 to 3-14
/AL switch, 10-6
$$ALER
reserved PSECT name, E-2

ALERR module, 5-53
Allocation-code, 2-4 to 2-5
ALSCT FORTRAN subroutine, 5-56
to 5-58
$$ALVC
PSECT, 7-11
reserved PSECT name, E-2
$$ALVO
PSECT, 7-11
reserved PSECT name, E-2
$$ALVI
PSECT, 7-11
reserved PSECT name, E-2
Ancillary control processor
See ACP
APR, 2-16
I- and D-space
allocation in multiuser
task, 9-3
relocatable region
specifying for, 5-6
resident common
system-owned, 11-11
resident library
system-owned, 11-11
specifying for ACP, 10-5
supervisor-mode, 8-2 to 8-3
Arithmetic element
extended
specifying, 10-16
Array declaration
mapped, A-10
ASG option, 11-7
Asterisk (*)
See also Autoload indicator
cross-reference
of overlaid task, 4-13
cross-reference listing,
10-12
At sign (@)
cross-reference
of overlaid task, 4-13
cross-reference listing,
10-12 to 10-13
indirect file, 1-5
Attribute
in .NAME directive
OSK, 3-28
GBL, 3-28
NODSK, 3-28
NOGBL, 3-28
program section
restriction, 2-3
save, 2-4

Index-1

INDEX
$$AUTO
PSECT, 5-52 to 5-53
reserved PSECT name, E-2
AUTO module, 5-52
AUTOL module, 5-52
Autoload, 4-1
applying indicator
co-tree root, 4-2
.FCTR label name, 4-3
file name, 4-2
portions of ODL tree, 4-2
program section name, 4-3
segment name, 4-3
code sequence
conventional task, 4-5
error handling, 4-11 to 4-12
indicator, 4-2
efficiently placed, 4-6
overhead in region, 5-13
path loading, 4-3 to 4-4
specifying, 4-1
vector, 4-4
eliminating unnecessary,
4-6
I- and D-space, 7-9, 7-11
overlay, 3-20
vector format
conventional task, 4-4
I- and D-space, 4-4 to 4-5
Autoloadable
data segment, 4-7
making file
using file name, 4-2
making program section, 4-3
.BLK
See Program section
Block
label, 2-8
Buff er record
maximum size, 11-23
Build file
modifying
to improve performance, F-1,
F-5
/CC switch, 10-7
Checkpoint
area
in task image, B-9
space
allocating, 10-6, 10-10
Checkpointable task
specifying a, 10-6, 10-10
Circumflex ()
cross-reference listing,
10-12 to 10-13
global cross-reference
of an overlaid task, 4-13
CLSTR option, 11-8 to 11-9
Cluster library, 5-44
See also Library
/CM switch, 10-8 -

$CMPAL
completion routine, 8-8 to
8-9
CMPAL option, 8-9
$CMPCS
completion routine, 8-8
CMPCS module, 8-9
CMPRT option, 8-9, 11-10
use in CSM library, 8-3, 8-8
use in supervisor-mode
library, 8-7
/CO switch, 10-9
Code
access, 2-4 to 2-5
allocation, 2-4 to 2-5
relocation, 2-4
scope, 2-4, 2-7
type, 2-5, 2-7
Comma (,)
See ODL operator
Command
file
indirect, 1-5
interaction with indirect,
1-5 to 1-6
level of indirection, 1-7
with ODL, 3-30
line
comments in, 1-8
form, 1-2
multi-line input, 1-3
option input, 1-3
output file interpretation,
1-3
terminating character, 1-3,
1-5 to 1-6
to build a task, 1-2
UFD convention, 1-9
sequence
comments in, 1-8
simple, 1-2
Comment
in command sequence, 1-8
in line, 1-8
Common, 5-1, 5-26 to 5-31
See also Region
allocation diagram, 5-20
assigning references, 5-23
building a linking task, 5-21
to 5-22
building and linking to, 5-14,
5-17 to 5-18
building and linking to a
device, 5-26 to 5-31
device, 5-26 to 5-31
See also Device common
establishing offset in, 5-28
in MACR0-11
building and linking to,
5-17 to 5-18
building and linking to a
See Region

Index-2

INDEX
Common {Cont.)
installing in RSX-llM, 5-2 to
5-3, 5-20
installing in RSX-llM-PLUS,
5-2 to 5-3, 5-20
linking to region, 5-14
map, 5-19
PSECT
building a linking task,
5-23
reg ion , 2-19
resident, 5-1 to 5-2
declaring, 11-11, 11-28
name block data, B-8
specifying a, 10-9
typical, 5-2
COMMON option, 11-11 to 11-12
Completion routine
$CMPAL, 8-2, 8-8 to 8-9, 8-18
$CMPCS, 8~2, 8-8
content of a, 8-12 to 8-14
CSM library, 8-13
definition, A-11
identification, A-11
name, A-11
supervisor-mode library, 8-2,
8-7
user-written, 8-21
Complex relocation, A-22
entry, A-23
operation codes, A-22
Concatenated object module
using to reduce overhead, F-4
Control section
name, A-5
name entry, A-5
Cotree, 3-31
and main tree
virtual address space, 3-40
global symbol resolution,
3-17
null root, 3-31
ODL statement
from allocation diagram,
3-39 to 3-40
overlay, 3-34 to 3-35
segment
affecting symbol search on,
10-19
segment loading, 4-2
Counter
location
definition, A-17
modification, A-18
/CP switch, 10-10
/CR switch, 10-11 to 10-13
Cross-reference
global
of overlaid task, 4-12 to
4-14
listing
specifying a, 10-11

CSM library
completion routinef 8-12 to
8-14
dispatching, 8-19
linking task
example of, 8-9
supervisor-mode, 8-7
building, 8-7 to 8-8
.STB file, 8-8
CTRL/Z
effect on Task Builder, 11-4
/DA switcht 10-14
Data
adjacency in memory, 2-28
segment
autoloadable, 4-7
structure
building a, 2-1
overlay of a, 3-19
Data base
overlay, B-15
I- and D-space task, B-16
Data format
input
Task Builder, A-1
$$DBTS
reserved PSECT name, E-2
Debugging aid
including a, 10-14
Declaration flag byte
symbol, A:.-7
Default of switch
modifying, F-7 to F-11
Descriptor
reg ion, B-21
segment, B-18
window, B-20 to B-21
Development step
program, 1-1
Device
assignment, 11-7
common, 5-29
building and linking to a,
5-26 to 5-31
$$DEVT
reserved PSECT name, E-2
Directive
memory management
in mapping, 2-24
.NAME, 3-27
attributes for, 3-28
example of use, 3-28
ODL, 3-23 to 3-24
• END, 3-23
• FCTR, 3-25
introduction, 3-23
.ROOT, 3-23
.PSECT, 3-29
use of parentheses, 3-24
Directory record
declare global symbol, A-2
end of global symbol, A-11

Index-3

INDEX
Directory record (Cont.)
global symbol
end of, A-11
internal symbol, A-24
relocation, A-12
Disk image, 2-8 to 2-9
conventional task, 7-6
Disk-resident
overlay, 3-1 to 3-2
loading, 4-1
overlay structure, 3-2
Displaced relocation
internal, A-15
/DL switch, 10-15
DSPPAT option, 11-13
Dump
See Postmortem dump
See Snapshot dump
memory, D-1
Dynamic region, 2-20, 5-40 to
5-43
/EA switch, 10-16
/EL switch, 10-17
Element
extended arithmetic
specifying, 10-16
.END directive, 3-23
End of global symbol directory,
A-11

End of module record, A-24
Error
exit TKB commands on, 11-4
handling
$ALERR entry, 4-12
for autoload, 4-11 to 4-12
for manual load, 4-12
overlay, 4-12
message, H-1
Exclamation point (!)
See ODL operator
operator
See ODL operator
Extend Task directive
to improve performance, F-2
EXTSCT option, 11-14
EXTTSK option, 11-15
Factor
auto loadable
making first component of,
4-3
Fast Task Builder, G-1
speed of, G-2
supported
features, G-1 to G-2
options, G-2
switches, G-1
unsupported features, G-1 to
G-2
.FCTR directive, 3-25
argument
library modules, 3-26

.FCTR directive
argument (Cont.)
library to resolve
references, 3-26
named input file, 3-25
PSECT name, 3-26
segment name, 3-26
arguments for, 3-25
use of label in, 3-25
.FCTR statement
allocation diagram
creating from, 3-38 to 3-39
File
command
level of indirection, 1-7
declaring number of active,
11-6
indirect command, 1-5
input
designating as debugging
aid, 10-14
designating as library file,
10-23
directing selective symbol
search, 10-47 to 10-49
including content of in map,
10-26
processing to reduce
overhead, F-6
specifying as default
library, 10-15
library
declaring a, 10-23
making file autoloadable
using name, 4-2
map
pr inti ng , 1- 2
omitting a specific output,
1-3
open at one·time, 11-6
specification
convention for, 1-8
default for, 1-8
Floating Point Processor
specifying, 10-18
FMTBUF option, 11-16
FORTRAN
common block
in overlays, 3-19
manual load calling sequence,
4-9 to 4-10
for I- and D-space task,
4-11

run-time support
virtual program section,
5-56 to 5-57
/FP switch, 10-18
$$FSR1
reserved PSECT name, E-3
.FSRPT
low-memory context, B-10
reserved global symbol, E-1

Index-4

INDEX

Host system (Cont.)
transferring from task, C-1
Hyphen (-)
See ODL operator

FTB library
overlaid region, 5-13
/FU switch, 10-19
GBLDEF option, 11-17
GBLINC option, 11-18
GBLPAT option, 11-19
GBLREF option, 11-20
GBLXCL option, 11-21
use in CSM library, 8-3, 8-7
tO 8-8 I 8-18
Global
additive relocation, A-16
relocation, A-15
additive displaced, A-17
displaced, A-16
symbol
address of ODT SST routine,
11-24
ambiguously defined in
overlay, 3-16 ,
declaration directory
record, A-2
directory record format,
A-4
end of directory record,
A-11
from the default library,
3-18
in autoloadable segment,
4-4, 4-6
in cross-reference listing,
10-12 to 10-13
multiplydefined, 3-16
multisegment task, 3-16
name, A-6
name entry, A-6
overlay search sequence,
3-17
resolution, 2-7
search sequence in overlays,
3-16
undefined, 2-7
symbol resolution
co-tree, 3-17
default library, 3-18
in multisegment task, 3-16
/HD switch, 10-20
Header, 2-8
excluding task, 10-20
I- and D-space task, 7-11
in task image, B-10
task
fixed part, B-11
variable part, B-12
vector extension area, B-13
High- level language
overlay program in, 3-40 to
3-41
Host system, C-1
building a task for another
system, C-1

I- and D-space
specifying, 10-21
I- and D-space task
See Task
I/O page
specifying, 10-22
/ID switch, 10-21
Image
disk, 2-8 to 2-9
memory, 2-8 to 2-9
Indirect command file, 1-5,
3-30
with ODL, 3-30
Information record
text, A-11
Input
data format
Task Builder, A-1
multi-line
to the Task Builder, 1-3
Internal displaced relocation,
A-15
Internal symbol
directory record, A-24
name entry, A-5
$$IOB1
reserved PSECT name, E-3
$$IOB2
reserved PSECT name, E-3
/IP switch, 10-22
Label block, 2-8
group, B-1
Language
high-level
overlay program in, 3-40
/LB switch, 10-23 to 10-24
LBLDF$ macro, B-1
/LI switch, 10-25
LIBR
linking to region, 5-14
option, 11-11 to 11-12
Library
build i ng a , 5-1 4
cluster, 5-44
building, 5-44, 5-48 to
5-51
building example, 5-48 to
5-51
building rule 1: overlays,
5-45
building rule 2: references,
5-46
building rule 3: .STB file,
5-47
building rule 4: stack,
5-47
building rule 5: PIC, 5-47

Index-5

INDEX

Library
cluster (Cont.)
building rule 6: traps,
5-47
building rule summary, 5-44
examples, 5-47
overlay run-time support,
5-51 to 5-53
resolving interlibrary
references, 5-49
declaring a, 10-23
default
controlling symbol search,
10-15, 10-19
global symbol resolution,
3-18
specifying a, 10-15
extending a, 10-17
file
declaring a, 10-23
FTB
overlaid region, 5-13
linking resident to
supervisor-mode, 8-21
modules
.FCTR directive, 3-26
object module
placing in overlay
structure, 10-24
old
overlaid region, 5-13
reg ion, 2-20
specifying, 10-25
relocation
resident, A-23
resident, 5-1, 5-3
building and linking to a,
5-14, 5-31 to 5-38
data in task image, B-4 to
B-6
declaring, 11-11, 11-28
label block O, B-7
label block 1, B-9
label block 2, B-9
label block 3, B-9
name block data, B-8
relocation, A-23
search, 10-23
resolving references
.FCTR directive, 3-26
restriction in I- and D-space
task, 7-9
supervisor-mode, 2-24, 8-1
building, 8-7
building linking task, 8-17
to 8-18
building the referencing
task, 8-7
building with relevant
options, 8-3, 8-7, 8-17
to 8-18
completion routine, 8-2,
n

..,

""',.

o- I r o-"'J.

Library
supervisor-mode (Cont.)
converting SCAL to CSM,
8-20
data in, 8-3
definition, 8-1
example of, 8-10 to 8-17
linking, 8-7
linking a resident, 8-20
linking to, 8-21
linking to SYSLIB, 8-2, 8-7
to 8-9, 8-18
linking with relevant
options, 8-3, 8-8, 8-18
mapping of, 8-3
method of mode switching,
8-1, 8-19
mode switching, 8-1, 8-7
mode switching compared,
8-1
mode-switching vector, 8-1
$MSDS directive, 8-2
$MSDS directive restriction,
8-2
multiple, 8-20
overlaid, 8-21 to 8-22
overlay restriction, 8-21
to 8-22
parameter passing, 8-2
restrictions on contents,
8-2
using as resident, 8-20
using system supplied
vector, 8-19
with I- and D-space task,
8-3
your own completion
routines in, 8-21
your own vector in, 8-21
supervisor-mode mapping
with conventional task, 8-4
to 8-5
with I- and D-space task,
8-6
SYS LIB
replacing as default, 10-23
Linking
module, 2-3
Listing
global cross-reference
generating as, 10-11
wide
specifying a, 10-51
$$LOAD
PSECT, 5-53
reserved PSECT name, E-3
LOAD module, 5-53
$LOAD routine
in manual load, 4-7
Loading
asynchronous example of, 4-10
mechanism
overlay, 3-16

Index-6

INDEX
Location counter
definition, A-17
modification, A-18
Logical
address, 2-14
address space, 2-14
unit number
assigning physical device
to a, 11-7
unit table entry, B-9, B-14
units
number of, 11-39
Low-memory context, B-10
LUN
See Logical unit number
/MA switch, 10-26
Macro
SNAP$, D-6
SNPBK$, D-6
SNPDF$, D-6
MACR0-11 calling sequence
manual load, 4-7
I- and D-space tasks, 4-8
to 4-9
Manual load
calling sequence, 4-7 to 4-8
error handling, 4-12
FORTRAN calling sequence, 4-9
to 4-10
for I- and D-space task,
4-11
MACR0-11 calling sequence,
4-7
I- and D-space tasks, 4-8
to 4-9
Map
common, 5-19
file
adding cross-reference to a,
10-11
content, 10-37 to 10-43
description, 10-37 to 10-43
example, 10-37 to 10-43
general, 10-37 to 10-43
inhibiting spooling of a,
10-45
printing, 1-2
specifying, 10-26
including SYSLIB contribution,
10-26
multiuser task, 9-7
overlaid I- and D-space task,
7-12 to 7-16
privileged task, 6-10 to 6-11
region, 5-19
resident region
including symbol definition,
10-26
short
specifying a, 10-37 to
10-43
spooling to print, 10-45

Map (Cont.)
task
I- and D-space, 7-9
linked to a common, 5-24
Mapped
array
area, 5-56, 5-58
declaration, A-10
declaration entry, A-10
reg ion
declaring address window,
11-41
system, 2-14, 2-18
Mapping
concept, 2-22
conventional task
supervisor-mode library,
2-26 to 2-27
conventional task linked to
reg ion
I- and D-space system, 7-3
I- and D-space task, 7-3 to
7-4
in I- and D-space system,
7-4
in supervisor-mode, 2-24
task, 2-15
MAXBUF option, 11-23
.MBLUN
reserved global symbol, E-1
Memory
allocation
I- and D-space task, 7-9
allocation file
See Map file
dump, D-1
image, 2-8 to 2-9
layout
unmapped system, 2-16
management
specifying for target
system, 10-27
physical
disk-resident overlay, 3-3
to 3-4
memory-resident overlay,
3-6
overlay, 3-5, 3-33 to 3-35
reducing to build a task, F-4
reducing usage of, 3-1
resident overlay structure,
3-6
saving
overlaid task, 3-9 to 3-10
virtual allocation
I- and D-space task, 7-10
Memory management
use by task, 2-15 to 2-16
Memory Management Unit, 2-14
Memory-resident
overlay
loading, 4-1
overlay, 3-1

Index-7

INDEX

Message
diagnostic
eliminating, 10-30
error, H-1
virtual memory system, F-5
inhibiting system queuing of,
10-35
/MM switch, 10-27
Mode
compatibility
in a task, 10-8
Mode-switching
to supervisor-mode, 8-8, 8-12
to 8-13
vector
supervisor library, 8-1,
8-19
Module
extracting from library,
10-23
linking, 2-3
name, A-4
name entry format, A-4
object
extracting by name, F-4
linking, 2-1
placing in segment
reducing overhead, F-4
record
end of, A-24
.MOLUN
reserved global symbol, E-1
/MP switch, 10-28
$$MRKS
PSECT, 5-52
reserved PSECT name, E-3
/MU switch, 10-29
Multi-line input, 1-3
Multiple-tree
example, 3-32
structure, 3-31 to 3-32
defining a, 3-31 to 3-32
Multisegment task
See Overlay
Multiuser task, 2-28, 9-1
as an overlaid task, 9-2
building a, 9-5
declaring read-only partition
for I 11-33
defined, 9-1
disk image, 9-2
example, 9-6 to 9-7
example map, 9-7
I- and D-space, 9-3
APR allocation, 9-3
PSECT allocation, 9-4
PSECT in, 9-3
windows, 9-5
program section allocation,
9-1 to 9-2
specifying a, 10-29
TKB command sequence, 9-7

Multiuser task (Cont.)
window block assignment, 9-1,
9-3
N.OVPT
low-memory context, B-10
reserved global symbol, E-1
Name
global symbol, A-6
.NAME directive, 3-27
attribute
DSK, 3-28
GBL, 3-28
NODSK, 3-28
NOGBL, 3-28
example of use of, 3-28
.NLUNS
reserved global symbol, E-1
/NM switch, 10-30
.NOVLY
reserved global symbol, E-1
.NSTBL
reserved global symbol, E-1
Null
root, 3-31
in ODL, 3-31
segment
in ODL, 3-31
Number sign (#)
in cross-reference listing,
10-12 to 10-13
$$0BF1
reserved PSECT name, E-3
$$0BF2
reserved PSECT name, E-3
Object code
patching, 11-5
Object module
concatenating, 10-7
content of, A-1
format, A-3
linking, 2-1
overriding definition in,
11-17
relocatable, 2-2
selective global symbol
using /SS to include, 10-47
to 10-49
Object Time System
usage to extend record buffer,
11-16
ODL
autoload indicator, 4-2
directive, 3-23 to 3-24
• END, 3-23
example use of .NAME, 3-28
• FCTR, 3-25
introduction, 3-23
.NAME, 3-27
.NAME attributes, 3-28
.PSECT, 3-29
n"'l""\m

el'\UU.Lt

Index-8

,,.,,...,

.:;,-L..:J

INDEX
ODL (Cont.)
efficiently placing in
autoload indicator, 4-6
enabling operator
memory-resident overlay,
10-34
file
declaring a, 10-28
multiple-tree
defining structure, 3-30
example, 3-31 to 3-32
structure, 3-30
operator
, (comma) , 3-2 4
! (exclamation point), 3-24,
3-26 to 3-27
- (hyphen) , 3-24
introduction, 3-24
summary, 3-49 to 3-52
using indirect file with,
3-30
ODL file
creating
start of procedure, 3-36
with allocation diagram,
3-35 to 3-36
.FCTR statement
creating from allocation
diagram, 3-38 to 3-39
.ROOT statement
creating from allocation
diagram, 3-37
virtual address space
in allocation diagram, 3-36
ODL statement
co-tree
from allocation diagram,
3-39 to 3-40
ODT vector, 11-24
.ODTLl
reserved global symbol, E-1
.ODTL2
reserved global symbol, E-1
ODTV option, 11-24
Opera tor
ODL, 3-24
, (comma) , 3-24
! (exclamation point), 3-24,
3-26 to 3-27
- (hyphen) , 3-24
introduction, 3-24
Option
category of, 11-1
general form of, 1-4
input
in command line, 1-3
linking to region, 5-14
separation of argument list,
1-4 to 1-5
summary, 11-2
Task Builder, 1-4, 11-1
ABORT, 11-4

ABSPAT, 11-5

Option
Task Builder (Cont.)
ACTFIL, 11-6
ASG, 11-7
CLSTR, 11-8 to 11-9
CMPRT, 11-10
COMMON or LIBR, 11-11 to
11-12
DSPPAT, 11-13
EXTSCT, 11-14
EXTTSK, 11-15
FMTBUF I 11-16
GBLDEF, 11-1 7
GBLINC, 11-18
GBLPAT, 11-19
GBLREF, 11-20
GBLXCL, 11-21
MAXBUF I 11-23
ODTV, 11-24
PAR, 11-25 to 11-26
PRI, 11-27
RESCOM or RESLIB, 11-28 to
11-29
RESSUP, 11-31 to 11-32
ROPAR, 11-33
STACK, 11-34
SUPLIB, 11-35
TASK, 11-36
TSKV, 11-37
UICI 11-38
UNITS, 11-39
VSECT, 11-40
WNDWS, 11-41
Option summary, 11-3
OTS
usage to extend record buffer,
11-16
$0TSV
low-memory context, B-10
reserved global symbol, E-2
Output files
omitting specific, 1-3
OVCTC module, 5-52
OVCTL module, 5-52
OVCTR module, 5-52
OVDAT module, 5-53
$$0VDT
PSECT, 5-53
reserved PSECT name, E-3
Overlay, 2-10
allocation diagram
creating ODL file with,
3-35 to 3-40
autoload vector in, 3-20
building an, 3-41 to 3-48
building memory-resident
for region, 5-9
capability of an, 3-1
choosing a memory-resident,
3-14
co-tree, 3-34 to 3-35
data base, B-15
I- and D-space task, B-16

Index-9

INDEX

Overlay (Cont.)
data structure, 3-19
linked into root, 3-20
defining a multiple-tree,
3-31 to 3-32
description
effect on performance, F-4
disk-resident, 3-1 to 3-2
defined, 4-1
effect of
on physical memory, 3-5
on virtual address space,
3-5
effect of virtual address
space
on disk-resident, 3-1 to
3-4
effect on memory
of a disk-resident, 3-2
of disk-resident, 3-1, 3-3
to 3-4
effect on physical memory
of memory-resident, 3-6
effect on virtual address
space
of a memory-resident, 3-6
error handling, 4-12
example of building a, 3-41
to 3-48
I- and D-space task
disk image, 7-8
in I- and D-space task, 3-21,
7-5
PSECT, 7-6
loading
asynchronously, 4-10
disk-resident, 4-1
mechanism, 3-16
memory-resident, 4-1
methods, 4-1
synchronously, 4-8 to 4-9
memory-resident, 3-1, 3-6
conserving physical memory,
3-14
defined, 4-1
physical memory usage, 3-6
reg ion, 5-9
virtual address space, 3-14
multiuser task, 9-2
of program
in high-level language,
3-40 to 3-41
operator
enabling recognition of,
10-34
suppression of a
memory-resident, 10-34
path loading in an, 4-4
physical memory, 3-33 to 3-35
program section
specifying, 3-19
region
autoload vector, 5-11

Overlay
region (Cont.)
building, 5-9
building option, 5-10 to
5-11
descriptor in, 3-20
example of building, 5-10
global symbols in .STB file,
5-11

resolving symbol, 5-10 to
5-11

.STB file, 5-11
vectors in I- and D-space
task, 5-11
region restrictions, 5-12
root segment structure, 3-21
run-time, 3-19
comparison of sizes in
routine, 4-16
module sizes, 5-52 to 5-53
routine, 3-19, 4-16
size of routine, 4-16
support requirements, 5-12,
5-51 to 5-53
use of routine, 4-14 to
4-15
segment
alignment, 10-8
arrangement, 3-15
descriptor in, 3-20
processing order, 3-17
symbol processing, 3-17
structure
considerations in creating,
3-1
most effective, 3-2
multiple-tree, 3-18
multiply defined global
symbol, 3-16
specifying library search
in a, 10-23
task, 3-7, 3-9
global cross-reference of,
4-12 to 4-14
segment calls, 3-10
virtual address space, 3-10
tree, 3-15
calling segments in an, 4-6
virtual
address space, 3-33 to 3-35
address space and memory,
3-11 to 3-14
window
block, 3-49
descriptor in, 3-20
written in high-level
language, 3-40 to 3-41
Overlay Description Language
introduction, 3-15
Overlay Description Operator
See ODL
Overlay structure
global symbol

Index-10

INDEX
overlay structure
global symbol {Cont.)
ambiguously defined, 3-16
Overlay tree
for I- and D-space task, 7-7
Overlay tree diagram
virtual address space, 3-24
OVIDC module, 5-52
OVIDL module, 5-52
OVIDR module, 5-52
$$0VRS
reserved PSECT name, E-3
Page Address Register
See PAR
Page Description Register
See PDR
PAR, 2-16
option, 11-25
PAR option, 11-26
building region, 5-2
Parentheses
use of
in ODL, 3-24
Partition
declaring, 11-25
in region, 5-28
naming for target system, C-1
option, 11-25
requirement
shared region, 5-3
requirements
reg ion, 5-2
size
for TKB, F-2
specifying for region, 5-28
Patch
D-space, 11-13
declaring an object level,
11-5
global relative, 11-19
Path loading, 4-3 to 4-4
See also Overlays
example of, 4-4
in autoload, 4-3 to 4-4
$$POLS
PSECT, 5-52
reserved PSECT name, E-3
PDR, 2-16
Performance
improving TKB, F-1
Physical
address, 2-13
mapped system, 2-17
/PI switch, 10-31
/PM switch, 10-32
PMD task
installation for timely
operation, D-1
Postmortem dump, D-1
content, D-3 to D-5
example, D-2
sample, D-3 to D-5

Postmortem dump (Cont.)
specifying a, 10-32
/PR switch, 6-2, 10-33
/PR:O privileged task, 6-2, 6-4
to 6-5
/PR:O privileged task, uses of,
6-5
/PR:4 privileged task, 6-2, 6-4
to 6-5
/PR:4 privileged task, uses of,
6-5
/PR:S privileged task, 6-2, 6-4
to 6-6
/PR:5 privileged task, uses of,
6-5
PRI option, 11-27
Priority
task
declaring, 11-27
Privileged and nonprivileged
task
distinction between, 6-1
Privileged task, 2-25, 6-1
accessing
Executive with a, 6-4
I/O page with a, 6-4
building a, 6-6 to 6-11
comparison of nonprivileged
and, 6-1
hazards of a, 6-1 to 6-2
in a mapped system, 6-1
logging off from, 6-1
MAC command sequence, 6-9
map of, 6-10 to 6-11
mapping of, 6-2 to 6-3
/PR:O, 6-2, 6-4 to 6-5
/PR:4, 6-2, 6-4 to 6-5
/PR:5, 6-2, 6-4 to 6-6
processor trap in a, 6-2
specifying, 2-25
specifying a, 6-2
TKB command sequence, 6-10
to examine unit control block,
6-6 to 6-11
Program
development step, 1-1
limit, A-18
section, 5-53
additive displaced
relocation, A-21
additive relocation, A-20
adjacency requirement for,
10-46
allocation, 2-2
attribute, 2-4
attribute restriction, 2-3
blank (.BLK), 2-3
creation, 2-3
displaced relocation, A-19
element, 2-2
extension of, 11-14
in shared region, 5-7
making autoloadable, 4-3

Index-11

INDEX
Program
section (Cont.)
name, 2-3
name conflict, 5-7, 5-39 to
5-40
naming restriction, 5-7
ordering, 5-7, 10-36, 10-46
overlay allocation, 3-19
relocation, A-19
resolution of, 3-19
resolving names, 5-7, 5-39
to 5-40
resolving names in region
and task, 5-16
save attribute, 2-7
segregating, 10-36, 10-46
sequential ordering of,
10-36, 10-46
space allocation, 2-5 to
2-6
specifying explicitly in
overlay, 3-29
specifying in overlay, 3-19
virtual, 5-53
section name, A-7
applying autoload indicator,
4-3
section name entry, A-8
section name flag byte, A-8
to A-9
version
identification, A-10
Program section
$$ALVC, 7-11
$$ALVD, 7-11
$$ALVI, 7-11
I- and D-space task
overlay, 7-6
multiuser task
I- and D-space, 9-3
named
i n reg ion , 5-13
virtual
allocating physical memory
to a, 5-56
attaching virtual attribute
to a, 5-56
building a task using, 5-58
to 5-61
creating a, 5-56, 5-58 to
5-61
FORTRAN run-time support
for, 5-56 to 5-57
option usage, 5-55
specifying, 11-40
specifying base address for
a, 5-56
specifying length, 5-54
specifying physical size,
5-54
specifying window size,
5-54
support for a, 5-56 to 5-57

PSECT
See also Program section
See Program section
.PSECT directive, 3-29
PSECT name
.FCTR directive
argument, 3-26
• PTLUN
reserved global symbol, E-2
$$RDSG
PSECT, 5-52
reserved PSECT name, E-3
Reg ion, 2-18
absolute, 5-9
building precautions, 5-7
mapping for, 5-8
mapping of, 5-7
specifying an, 5-7
symbol definition file, 5-9
allocation
diagram, 5-20
of window block for, 5-25
APR
specifying, 5-6
assigning references, 5-23
building
a linking task, 5-21 to
5-22
and linking to a, 5-14,
5-1 7 to 5-18
interaction of /CO/LI/PI
switch, 5-3
options
in an overlaid, 5-10
options in an overlaid,
5-11
use of /CO/LI/PI switch,
5-3
with PAR option, 5-2
common, 2-19 to 2-20
descriptor, B-21
descriptor in overlay, 3-20
dynamic, 2-20, 5-40 to 5-43
building a task that
creates a, 5-40 to 5-43
installing in RSX-llM, 5-2 to
5-3, 5-20
installing in RSX-llM-PLUS,
5-2 to 5-3, 5-20
library, 2-20
linked to a region, 5-26
linked with a region, 5-25
linking to a, 5-13 to 5-14,
5-26
map, 5-19
mapping of an absolute, 5-7
memory-resident overlaid, 5-9
building, 5-9
example of building, 5-10
number of, 5-1 7

Index-12

options fur building, 5-17 to
5-18

INDEX
Reg ion (Cont.)
options for linking to, 5-14
overlaid, 5-9
autoload call overhead,
5-13
autoload in, 5-13
autoload vector, 5-11
FTB and old libraries, 5-13
global symbols in .STB file,
5-11
I- and D-space task vectors,
5-11
named program section, 5-13
run-time support for, 5-12
to 5-13
.STB file, 5-11
partition, 5-28
requirements, 5-2
procedure for building a,
5-17 to 5-18
program section in, 5-7
PSECT
building a linking task,
5-23
relocatable, 5-5
mapping, 5-5
specifying, 5-5
specifying APR for, 5-6
.STB file for a, 5-9, 5-14,
5-16
resident relocatable, 5-5
resolving PSECT names, 5-39
to 5-40
shared, 2-20, 5-1
allocation of window block
for I 5-14
autoload vectors in, 5-12
defined, 5-1
initializing window block
for, 5-14
installing, 5-16
partition requirement, 5-3
resolving PSECT names, 5-16
restrictions for overlaid,
5-12
symbol definition file,
5-16
use of /CO/LI/PI switches,
5-9
windows in, 5-14
size of, 5-17
specifying
as position independent,
10-9, 10-31
partition for, 5-28
.STB file, 5-4 to 5-5, 5-14,
5-16
for an absolute, 5-7, 5-9,
5-12
using /CO/LI/PI switches,
5=4
symbol definition file, 5-9
task, 2-18 to 2-20

Reg ion (Cont.)
task building options, 5-13
to 5-14
type of access to, 5-14
use of /CO/LI/PI switches,
5-5
window, 5-15, 5-25
with linked task
in I- and D-space system,
7-3
Relocatable region
See Region
Relocation
code, 2-4
complex, A-22
entry, A-23
operation codes, A-22
directory command byte, A-13
directory record, A-12
entries, A-12 to A-13
format, A-14
displaced
global, A-16
global, A-15
additive, A-16
global additive displaced,
A-17
internal, A-14
displaced, A-15
library
resident, A-23
program section, A-19
additive, A-20
additive displaced, A-21
displaced, A-19
resident library,_A-23
RE SC OM
linking to region, 5-14
option, 11-28 to 11-29
Reserved symbol
for the Task Builder, E-1
Resident
common
name block data, B-8
library
name block data, B-8
relocation, A-23
memory
for TKB performance, F-3
overlay operator
enabling recognition of,
10-34
reg ion
using to reduce overhead,
F-4
Resident region
map file
including symbol definition
in, 10-26
RESLIB
linking to region, 5-14
option, 11-28 to 11-29

Index-13

INDEX
RES LIB
option (Cont.)
in supervisor-mode library,
8-20 to 8-21
RESSUP
option, 8-9, 11-31 to 11-32
use in CSM library, 8-3,
8-8, 8-19 to 8-21
use in supervisor-mode
library, 8-7
Restarting TKB option, 11-4
$$RGDS
reserved PSECT name, E-3
RLSCT FORTRAN subroutine, 5-56,
5-58
/RO switch, 10-34
Root
in a co-tree, 3-31
null, 3-31
in ODL, 3-31
structure
overlay, 3-21
.ROOT directive, 3-23
.ROOT statement
allocation diagram
creating from, 3-37
ROPAR option, 11-33
$$RTQ
PSECT, 5-52 to 5-53
reserved PSECT name, E-3
$$RTR
PSECT, 5-52 to 5-53
reserved PSECT name, E-4
$$RTS
PSECT I 5-53
reserved PSECT name, E-4
Run-time support
overlaid region, 5-12 to 5-13
autoload, 5-13
autoload call overhead,
5-13
FTB and old libraries, 5-13
named program sections,
5-13
Save attribute, 2-4
SCAL to CSM library
converting, 8-20
Scope-code, 2-4, 2-7
/SE switch, 10-35
Segment
autoloadable
data, 4-7
global symbol in, 4-4
call, 3-10
to up-tree, 4-6
definition of a, 3-1
descriptor, B-19
I- and D-space task, 7-11
in overlay, 3-20
limiting number
reducinq overhead. F-4
loading ·

Segment
loading (Cont.)
as part of co-tree, 4-2
when called, 4-4, 4-6
making autoloadable, 4-3
mapping, 2-10
disk-resident, 2-11
memory-resident, 2-12
multiple, 3-5
global symbol in, 3-16
global symbol resolution,
3-17
symbol resolution, 3-16
name
applying autoload indicator
to, 4-3
.FCTR directive argument,
3-26
null
in ODL, 3-31
overlay
arrangement, 3-15
root structure, 3-21
symbol processing, 3-17
processing order, 3-17
single, 3-4, 3-8
up-tree
I- and D-space, 3-22
Semicolon (;), 1-8
SEND directive
enabling for your task, 10-35
/SG switch, 10-36
$$SGDO
PSECT, 5-53
reserved PSECT name, E-4
$$SGD1
reserved PSECT name, E-4
$$SGD2
PSECT, 5-53
reserved PSECT name, E-4
/SH switch, 10-37
Shared region, 5-1
See Region
Single segment task, 3-8
/SL switch, 10-44
Slash
double (//) , 1-6
single (/), 1-5 to 1-6
Slow TKB
to improve overhead, F-11
$$SLVC
reserved PSECT name, E-4
SNAP$ macro, D-6
format of, D-8
Snapshot dump, D-5 to D-6
example of, D-10 to D-12
format of macro for creating,
D-7
SNPBK$ macro, D-6
format of, D-7
SNPDF$ macro, D-6
/SP switch, 10-45
/SQ switch, 10-46

Index-14

INDEX
/SS switch
symbol definition file
reducing overhead, F-4
SST vector address
declaring, 11-27
Stack
declaring size, 11-34
supervisor-mode, 8-20
STACK option, 11-34
• STB file, 5-9
absolute region, 5-7, 5-9
content of a, 5-5
excluding symbol from, 5-11
for region, 5-4 to 5-5, 5-14,
5=16
I- and D-space task, 7-9
including symbol in, 5-11
interaction of /CO/LI/PI
switches, 5-4
overlaid region, 5-11 to 5-12
global symbols in, 5-11
program sections, 5-16
program sections in, 5-5
relocatable region, 5-9, 5-16
use of /CO/LI/PI switches,
5-5' 5-9
Structure
in TKB
size of, F-3
.SUMLl
reserved global symbol, E-2
Supervisor-mode, 2-24
library, 2-24
See Library
mapping, 2-24, 2-26 to 2-27
mode switching, 8-8, 8-12 to
8-13
stack, 8-20
SUPLIB
option, 8-9, 11-35
use in CSM library, 8-3,
8-19
use in supervisor-mode
library, 8-7
Switch
conflict in, 10-1
default
modifying, F-7 to F-11
modifying default of, F-7 to
F-11
summary, 10-2 to 10-4
syntax, 10-1
Task Builder, 10-1
/AC[:n], 10-5
/AL, 10-6
/CC, 10-7
/CM, 10-8
/CO, 10-9
/CP, 10-10
/CR, 10-11 to 10-13
I

JT"\ ._.

LJ.M.1

Switch
Task Builder {Cont.)
/EL, 10-17
/FP, 10-18
/FU, 10-19
/HD, 10-20
/ID, 10-21
/IP, 10-22
/LB, 10-23 to 10-24
/LI, 10-25
/MA, 10-26
/MM, 10-27
/MP, 10-28
/MU, 10-29
/NM, 10-30
/PI, 10-31
/PM, 10-32
/PR [: n] , 10-3 3
/RO, 10-34
/SE, 10-35
/SG, 10-36
/SH, 10-37
/SL, 10-44
/SP, 10-45
/SQ, 10-46
/SS, 10-47 to 10-49
/TR, 10-50
/WI, 10-51
/XH, 10-52
/X T [ : n] , 1 0 -5 3
Symbol
affecting search for, 2-7
declaration flag byte, A-7
definition file
excluding symbol from a,
11-21
for system-owned region,
11-11
for user-owned region,
11-29
including symbols, 11-18
reducing overhead, F-4
directory record
declare global, A-2
end of global, A-11
internal, A-24
full search in overlays
specifying, 10-19
global
address of ODT SST routine,
11-24
ambiguously defined in
overlay, 3-16
declaring definition in a
task, 11-17
default library resolution,
3-18
directory record, A-2
directory record format,
A-4

, n
1 A
.1. v-..L<:t

A-11
excluding in a task, 11-21

/DL, 10-15
/EA, 10-16

Index-15

INDEX

Symbol
global (Cont.)
from the default library,
3-18
in autoloadable segment,
4-4' 4-6
in cross-reference listing,
10-12 to 10-13
including in a task, 11-18
multiplydefined, 3-16
multisegment task, 3-16
name, A-6
name entry, A-6
overlaid region .STB file,
5-11
overlay search sequence,
3-17
resolution, 2-7, 3-17
resolution in co-tree, 3-17
resolution in multisegment
task, 3-16
undefined, 2-7
in cross-reference listing,
10-12
internal
autoloadable library, A-26
to A-27
end-of-module, A-30
end-of-module format, A-32
global, A-28
internal symbol name, A-30
internal symbol name format,
A-31
line-number, A-29 to A-30
literal record, A-30
literal record format, A-31
module name, A-27 to A-28
overall format, A-24 to
A-25
PC correlation, A-29 to
A-30
PSECT item, A-29
relocatable/relocated, A-27
start-of-segment, A-25 to
A-26
task identification, A-26
TKB generated, A-25
name entry
internal, A-5
number of processed for
performance, F-3
reserved for the Task Builder,
E-1
resolving
overlay region, 5-11
search
selective, 10-47 to 10-49
Symbol definition
SYSLIB.OLB, 2-7
Symbol definition file
See also .STB fil

Symbol definition file
supervisor-mode library
(Cont.)
user-owned, 11-31
Syntax rule
summary of, 1-10
SYS LIB
including contribution in map,
10-26
linking to
by supervisor-mode
libraries, 8-2, 8-7 to
8-9, 8-18
replacing as default, 10-23
SYSLIB.OLB
for symbol definition, 2-7
System
host and target, C-1
mapped, 2-14
physical and virtual space,
2-15
object module library, 2-2
See also Library
See also SYSLIB.OLB
target
memory management, 10-27
unmapped, 2-14
System-controlled partition
extending memory for task in,
11-15
T-bit trace trap, 10-50
Table storage, F-2
memory for
to improve performance, F-2
Target system, C-1
transfering task to a, C-1
Task
access
system-owned common or
library, 11-11
system-owned
supervisor-mode library,
11-35
user-owned common, 11-28
user-owned library, 11-28
user-owned supervisor-mode
library, 11-31
active files
declaring number of, 11-6
additional memory for, 11-15
address windows
declaring an additional,
11-41
ancillary control processor
specifying as, 10-5
assigning physical device to
LUN, 11-7
attaching slave attribute to,
10-44
building for target system,

supervisor-mode l brary
system-owned, 1 -35

C-1
changing name of, 11-36

Index-16

INDEX
Task {Cont.)
checkpointable
specifying, 10-10
command line to build a, 1-2
comparison
conventional and I- and
D-space, 7-2
completion routine for a,
11-10
conventional
autoload vector, B-17
disk image, 7-6
mapping compared to I- and
D-space task, 7-2
creating a dynamic region,
5-40
creating multiuser, 10-29
D-space
overlay structure, 3-21
data
in task image, B-4 to B-6
needed by system to install,
B-1
declaring
execution priority for,
11-27
maximum stack size of,
11-34
number of LUNs for, 11-39
object-level patch for,
11-5
ODT SST vector in, 11-24
disk image, 2-8
enabling
postmortem Dump for, 10-32
T-bit trace trapping in,
10-50
extending
a program section in a,
11-14
memory of, 11-15
to partition length, 11-15
external header
specifying, 10-52
floating point processor in
specifying, 10-18
format buffer
declaring length of, 11-16
global relative patch
declaring, 11-19
global symbol
excluding a, 11-21
including in, 11-18
global symbol definition
declaring a, 11-17
global symbol reference
declaring a, 11-20
header, 2-8
allocating additional
(checkpoint) space in,
10-6

checkpoint area within, B-9

Task
header (Cont.)
controlling creation of,
10-20
fixed part, B-11 to B-12
I- and D-space, 7-11
space for EAE context,
10-16
space for floating-point
context, 10-18
host to target system
example of transferring,
C-2
I- and D-space, 2-28, 7-1
autoload vector, 7-9, B-17
to B-18
differing from conventional
task, 2-28
manual load calling
sequence, 4-8 to 4-9,
4-11
map, 7-9
mapped in I- and D-space
system, 7-4
mapping, 7-3
mapping summary of, 7-2
memory allocation, 7-9
overlaid, 7-5
overlay region vector, 5-11
overlay structure, 3-21
patching, 11-13
PSECT in overlay, 7-6
simplified mapping, 2-29
specifying, 10-21
.STB file, 7-9
with up-tree segment, 3-22
I-and-D and conventional
mapping compared, 7-2
identification
for I- and D-space, 7-1
identifying partition for,
11-25
image, B-1, B-14
file structure, B-1
image on disk
non-overlaid, B-2
non-overlaid as lkinked to
library, B-2
overlaid, B-3
overlaid I- and D-space,
B-4
including debugging aid (ODT)
in, 10-14
inhibiting queuing message to,
10-35
installed name
de c 1 a r i ng , 11 - 3 6
label block, 2-8
label block O, B-7
label block 1, B-9
label block 2, B-9
label block 3, B-9
linking

Index-17

INDEX
Task
linking (Cont.)
to a supervisor-mode
library, 8-10 to 8-12
to region, 5-13
to region in I- and D-space
system, 7-3
to several libraries, 11-8
to 11-9
list of attributes, 10-37
logical units
number of, 11-39
making checkpointable, 10-6
map
linked to a common, 5-24
mapping, 2-15, 2-20
maximum record buffer size
declaring, 11-23
memory, 2-10
memory-resident overlay
opera tor
enabling, 10-34
memory-resident overlay
segment
changing alignment of, 10-8
multisegment, 3-5
global symbol resolution,
3-17
multiuser, 2-28
See Multiuser task
declaring read-only
partition, 11-33
specifying a, 10-29
ODT vector, 11-24
overlaid, 3-7, 3-9
global cross-reference of,
4-12 to 4-14
memory savings, 3-9 to 3-10
segment calls, 3-10
virtual address space, 3-10
overlaid ~- and D-space
disk image, 7-8
map, 7-12 to 7-16
tree, 7-7
virtual address, 7-7
overlay, 2-10
partition
declaring, 11-25
patching of
with object code, 11-5
privileged, 2-25
See Privileged task
specifying, 2-25
specifying a, 10-33
privileged access right for
establishing, 10-33
program section order
effect in creating, 10-36,
10-46
region, 2-18 to 2-20
relocation of, 2-2
resident common
system-owned, 11-11

Task (Cont.)
resident library
system-owned, 11-11
single segment, 3-4, 3-8
slave
specifying a, 10-44
specifications
multiple, 1-5
specifying
data space in an I- and
D-space, 7-5
KEll-A in, 10-16
SST vector address
declaring, 11-37
stack size
declaring, 11-34
structure, 2-8
label block, 2-8
supervisor-mode library for a,
11-31, 11-35
system mapping status of
indicating, 10-26
time-based schedule request
declaring UIC for, 11-38
traceable
specifying a, 10-50
UIC
declaring, 11-38
use of memory management,
2-15 to 2-16
user
data space definition, 7-1
vector address
declaring system SST trap,
11-37
virtual program section
specifying, 11-40
window, 2-20 to 2-22
in I- and D-space, 7-5
linking to region, 5-15
Task Builder
command line, 1-2
fast
See Fast Task Builder
function, 2-1
option, 1-4
switch, 10-1
TASK option, 11-36
Text information record, A-ii
to A-12
format, A-12
Throughput
improving TKB, F-1
TKB
slow
to improve performance,
F-11
/TR switch, 10-50
Transfer
address, A-6
address entry, A-6

Index-18

INDEX
Tree
applying autoload indicator,
4-2
calling segments in, 4-6
calling up-tree segments, 4-6
multiple
defined, 3-30
defining, 3-31
structure, 3-18, 3-32
• TRLUN
reserved global symbol, E-2
$$TSKP
reserved PSECT name, E-4
TSKV option, 11-37
Type-code, 2-5, 2-7
UFD conventions in command line,
1-9
UIC
declaring in task, 11-38
option, 11-38
UNITS option, 11-39
Unmapped
system, 2-14
memory layout, 2-16
Unnamed program section
See Program section
.USLUl
reserved global symbol, E-2
.USLU2
reserved global symbol, E-2
Vector
autoload, 3-20, 4-4
conventional task, B-17
eliminating unnecessary,
4-6
I- and D-space, 7-11
I- and D-space format, 4-5
I- and D-space task, 7-9,
B-17
in region, 5-12
in task header
extension area format, B-13

Vector (Cont.)
mode-switching
supervisor library, 8-19
supervisor-mode library,
8-1
ODT I 11-24
overlaid region, 5-11
I- and D-space task, 5-11
SST address, 11-27
$VEXT
low-memory context, B-10
reserved global symbol, E-2
VSECT option, 11-40
/WI switch, 10-51
Window, 2-20 to 2-22
block, 2-20 to 2-22
creating a, 5-14
for a region, 5-14
in overlay, 3-49
definition block, 2-22
descriptor, B-20 to B-21
in overlay, 3-20
for region and linking task,
5-15
in I- and D-space task, 7-5
option, 11-41
reg ion, 5-2 5
wrap around
in virtual sections, 5-54
$$WNDS
reserved PSECT name, E-4
WNDWS option, 11-41
Work file
accesses
system overhead, F-2, F-5
to F-7
parameters for, F-2
performance
changing device to improve,
F-5
/XH switch, 10-52
/XT switch, 10-53

Index-19

RSX-llM/M-PLUS
Task Builder Manual
AA-L680B-TC
READER'S COMMENTS
NOTE: This form is for document comments only. DIGITAL will use comments submitted on this form at the
company's discretion. If you require a written reply and are eligible to receive one under Software
Performance Report (SPR) service, submit your comments on an SPR form.

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

Did you find errors in this manual? If so, specify the error and the page number.

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

Organization
Street
State _ _ _ _ _ _ Zip Code _ _ _ _ __
or Country

Do Not Tear- Fold Here and Tape -

~nmnoma

No Postage
Necessary
if Mai led in the
United States

111111

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

BSSG PUBLICATIONS ZK1-3/ J35
DIGITAL EQUIPMENT CORPORATION
110 SPIT BROOK ROAD
NASHUA, NEW HAMPSHIRE 03061

Do Not Tear - Fold Here