spex (spectrometer executive) : programming manual

COO-3130-TB-168

SPEX (Spectrometer Executive) : *

Programming Manual

* * J . T. Massimo, B.A.Nelson , L. J . Levmson

Brown Unive r s i t y High Energy Phys ics

I n t e r n a l Report #124

August 1972

This report was prepared as an account of work sponsored by the United States Government. Neither the United States nor the United States Atomic Energy Commission, nor any of their employees, nor any of their contractors, subcontractors, or their employees, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness or'usefulness of any information, apparatus, product or process disclosed, or represents that its use would not infringe privately owned rights.

* io rk supported in p a r t by the U.S. under Contrac t No. AT (11-1)-3130 TB ** of t h e Massachuset t s I n s t i t u t e of Technology

Atomic Energy Commission

DISTRIBUTION OF THIS DOCUMENT IS

DISCLAIMER

This report was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor any agency Thereof, nor any of their employees, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represents that its use would not infringe privately owned rights. Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or any agency thereof. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or any agency thereof.

DISCLAIMER

Portions of this document may be illegible in electronic image products. Images are produced from the best available original document.

SPEX Programming •Manual

Contents

General The Normal Directives The Conversion Directive The QTRAN Directive Interrupt Programming and I/O Handlers The Nature of Globals and Csects Preparation of the XSTL Preparation of the XCOM The Phase Communication File PH&COM

appendices

Device Names and Logical Unit Numbers Summary List of TRAP Directives Summary List of System Globals The System Control Block

SPM/7-72 SPEX Programming Manual

Chapter 1

General

1.1 Creating Tasks and Associated Modules 1.2 The TCB and Task Structure 1.3 Example of a SPEX Task Module

Page 1-1

SPM/7-72 SPEX Programming Manual Page 1-2

1.1 Creating Tasks and Associated Modules

The basic purpose and concepts of SPEX are described in the manual "Elements of SPEX". The generation of object modules into an ensemble of tasks (i.e. a program), how to call a SPEX system into operation, console operations and debugging facilities, are discussed in the "SPEX Operations Manual". This document, the "SPEX Programming Manual", is concerned with the preparation of the source modules of a SPEX system. A complete SPEX program is generated by coding several kinds of modules, and this manual contains programming information for each type.

Task Modules. The form of a task " module is given in Sections 1.2 and 1.3 of this chapter, with details of the Task Control Block and conventions of the user stack. Chapter 2 contains alphabetically ordered descriptions of the "normal directives" that may be issued by a task. Chapter 3 describes the "conversion directive" for alphanumeric manipulations. Chapter 4 discusses in detail the QTRAN directive, the basic I/O transfer command. Also included there is the MESSAGE directive, an I/O method for the console teletype only, particularly suitable for control and error messages. The information in these first four chapters includes virtually all one needs to know in order to write workable SPEX tasks. Two other pieces of information that may be necessary are (1) conventions to be observed if the task alters the hardware priority of the CPU, which is discussed in Chapter 5, and (2) conventions for passing of common information between tasks, which is discussed in Chapter 8.

Interruption Servicing Modules. To write such a module, whether it is independent or imbedded in the coding of a task module, requires a knowledge of the SPEX conventions and special directives described in Chapter 5.

Common Data Modules. The preparation of "common blocks" of data, which are to be accessed by several independent tasks, is discussed in Chapter 8. How such modules may be modified at run time by disk overlay is described there.


The System Task List. The preparation of a list of all tasks that are to be run under SPEX is, in the simplest arrangement, confined to one module called the XSTL, and is described in Chapter 7.

The Phase Communication File. The function and preparation of this file (PHACOM), which governs the initialization of a run-phase system and communication with DOS files, is described in Chapter 9.

Other Details. Task references to Executive globals and COMMONS are resolved by the program BUILDX when it creates the task swap image on the disk. Chapter 6 describes the nature of globals and csects. The definition of a node pool area has been included as part of the contents of the XCOM module (where commons are declared) in Chapter 8. Allocation of space for the PHACOM file is also assumed to be made in this module. Ordinarily, I/O handler tasks will exist in SPEX for all standard input-output devices. However, as it may occasionally be desirable to modify these tasks, or write new ones, the structure of an IOHT is described in Chapter 5.


1.2 The TCB and Task Structure

One of the most important functions of SPEX is the effective expansion of a moderate-sized PDP-11 by allowing for extensive swapping of tasks between core and a disk. Essentially every task executable by SPEX is first generated as a contiguous file on the disk, by means of the the task builder BUILDX, in such a way that it will execute as proper coding when brought into a particular area of core defined at building time. All external references to globals and CSECTS are pre-resolved at BUILDX time, so that execution of a task resident on the disk may be initiated by simply loading it into place in core by a single DMA transfer of the entire image and a branch to a particular starting location. Similarly, provision exists for "rolling out" a task (see the PAUSE directive) in the form in which it currently exists in core to a secondary task area, and for recalling the paused task at a later time.

Every SPEX-executable task has its own stack, which is imbedded in the the task coding at a location selected by the programmer. The location of the start of the task, and the top and bottom of the stack, are transmitted to SPEX by means of the Task Control Block (TCB). The TCB is a set of ten words which must be the first ten words of the task. Since both the TCB and the stack are part of the task, and since SPEX stores the current value of the task stack pointer within the TCB when necessary, a task can always be placed in a completely self-contained state suitable for rollout to the disk. That is, there is no structural difference between a task that is always resident in core during SPEX operations, and a task which is frequently rolled in and out of core in the normal course of execution.

The contents of the TCB serve the following functions:

Word Byte Function 1 0 Current value of Stack Pointer 2 2 Lowest Core address of task 3 4 Upper core limit of task (Last word + 2) 4 6 First instruction of task 5 10 Reserved 6 12 Task name (SAD50) 7 14 Reserved 8 16 Initial Stack pointer setting (top of stack) 9 20 Bottom of stack 10 22 Reserved

The programmer must arrange, in coding the TCB, that the correct values are set for words 2, 3, 4, 6, 8 and 9. Further comments on these words are given below. The values of all other words

• , > SPM/7-72 SPEX Programming Manual Page 1-5 * >

are handled by or reserved to the system. Their initial values are of no significance, but they are not to be modified by the task during execution.

Core limits (Words 2 and 3) The most convenient way of setting these words is by means of the .LIMIT Macro of the assembler, in the position of Word 2. This

generates two words which are filled in by the task builder BUILDX, and correspond to the desired contents of these two locations. This is particularly convenient if the task is built up from a number of modules linked by BUILDX, since the upper limit will be posted as that of the entire set of modules. Note that the module containing the TCB must be linked first, since the TCB must form the first ten words of the task in any case.

Starting instruction (Word 4) The label of the first instruction to be executed when the task is started is placed here. Note that SPEX does not use any information generated by the .END assembler statement.

Task name (Word 6) While this word is not currently used by SPEX, it should be filled in to avoid incompatibility with future versions of the system.

Stack location (Words 8 and 9) Word 8 is the value that SPEX stores in the stack pointer (SP) when the task is started. Since most coding always pushes onto the stack initially, this word is generally set to a value two bytes higher than the highest word address of the stack area. When, as frequently occurs, the stack area is the highest area of the task, this word may be set by use of the .LIMIT statement at the position of Word 7. The bottom (low address) of the stack area is entered in word 9 in order that SPEX may check against stack overflow (too many words on the stack) during task execution. This check is made only during the execution of normal directives, so it is by no means fool-proof,

In allocating the stack area, the programmer should note the following points:

(1) Hardware interrupts use the stack of the interrupted task. In a PDP-11/20, with four hardware interrupt levels, one must allow for the worst case of four nested interrupts, as a possible degree of stack penetration beyond the control of the


task. In addition one should regard the servicing of directives by the system as essentially equivalent to one more level of interrupt in its effect on the task stack (this is a slight over-estimate). Therefore one should allow for five "register saves" beyond the actual use of the stack by the task itself.

(2) A "register save" requires either eight or eleven words, depending on whether the executive has been assembled to save the EAE registers or not. The executive may be assembled conditionally to include saving three additional words to make the EAE re-entrant. Thus a minimum of forty (decimal) words without EAE saving, or fifty-five words with EAE saving, must be allocated for the task stack regardless of the task use of the stack.

(3) Task use of the stack is essentially additive on this figure. However, one should note that one register save is credited to executive implementation of directives, an operation that is controlled by the task. In determining the size of his stack area, the programmer should observe how deep his own use of the stack will be during the implementation of a directive. In many cases, his own use will complement the use of the stack in directive handling, and the minimum described above may be used as the actual stack size,

. ■ SPM/7-72 SPEX Programming Manual Page 1-7

1.3 Example of a SPEX Task Module

A simple example is given showing the source coding of a task called "TSK". It indicates the generation of a TCB, the allocation of a stack area, and the method by which the task starting point and stack area are designated within the TCB.


EXAMPLE OF A SPEX TASK CODING STARTS WITH A TCB

.WORD

.LIMIT

. WORD

. WORD

.RAD50

.WORD

.WORD

.WORD

.WORD

0 START 0 /TSK/ 0 TOPSTK BOTSTK 0

EXECUTIVE SAVES SP HERE GENERATES TWO-WORD TASK LIMITS FIRST EXECUTED INSTRUCTION RESERVED TASK NAME RESERVED INITIAL VALUE OF SP BOTTOM OF STACK AREA RESERVED

;EXECUTION STARTED HERE START: MOV X,-(SP)

ETC. ETC.

;SYSTEM HAS INITIALIZED SP

STACK AT END OF MODULE IN THIS CASE STKSIZ=120. BOTSTK: .=.+STKSIZ TOPSTK:

.END


C h a p t e r 2

The Normal D i r e c t i v e s


The following pages contain detailed descriptions of the "normal" SPEX directives, ordered alphabetically.

All arguments to SPEX are "call by name" rather than "call by value" arguments. That is, the word on the stack contains the address of the desired value, not the desired value. This allows passing a whole array or block of values as a single argument. DEC's DOS and other operating systems do not consistently follow this convention. (e.g. The values to be converted and the conversion code in the CONVERT directive and the BSX QTRAN device argument.)

Optional arguments of the directives are denoted by enclosing them in parentheses, for example (EV). When such arguments are not relevant to the call, their corresponding position on the stack must contain a zero. Since ALL directive arguments are addresses of variables rather than actual variables, there is no ambiguity in this method of denoting an unused optional argument. All arguments of normal directives are cleared from the stack on return to the caller.

An event variable in the directive argument list is uniformly denoted by "EV". An I/O device is uniformly denoted as "DEV". Either the RAD50 device name or the corresponding logical unit number, as denoted in Appendix A, may be used to specify the I/O device. A task name is uniformly denoted by "TASK", and the RAD50 version of the alphameric string is assumed. A priority is uniformly denoted as "PRI".


ALLOC ALBLK , (EV) Expansion:

MOV #EV,-(SP) MOV #ALBLK,-(SP) TRAP 13

This directive allocates a contiguous area within the disk scratch file allocated from DOS at the initiation of the SPEX run phase. The number of blocks in the area requested is set by the caller as the first of the two-word allocation block ALBLK. The starting block within the file (absolute disk location) is returned as the second word of ALBLK. Note that the RF11 disk contains 64 (dec) words per block. The RK11 disk contains 256 (dec) words per block.

Returned event variables: -2 Insufficient space -1 Number of requested blocks is neqative or zero +1 Allocation successful


ASKCOR PAGE , PART , NPART , (EV) Expansion:

MOV #EV,-(SP) MOV #NPART,-(SP) MOV #PART,-(SP) MOV #PAGE,-(SP) TRAP 31

This directive tests the availability of the core area designated by the page number PAGE, the starting partition PART, and the number of partitions NPART. If the core is available it is allocated to the caller by this directive, which is then equivalent to GETCOR, The difference is that the ASKCOR directive will not suspend the caller until the requested area becomes available, as the GETCOR directive will (core requests are not queued in SPEX). Besides error returns involving the "syntax" of the request, there is one which notes that the area overlaps the executive, so that it can never be allocated. Otherwise, the event variable signifies whether or not the allocation has been made. Returned event variables:

-4 Core not available -3 Reguest overlaps executive -2 Paging error -1 Invalid page number +1 Core allocation successful


ATTACH DEV , (EV) Expansion:

MOV #EV,-(SP) MOV #DEV,-(SP) TRAP 11

This directive attaches the device named or numbered by DEV to the caller task for its exclusive use until the task issues a subsequent DETACH directive. When attached, all calls to the device by other tasks are queued by priority behind those of the attached task, which are FIFO ordered. The ATTACH request is itself priority queued in a busy device queue.

Returned event variables: -4 Device already attached to task -3 Device is not attachable -2 IOHT not resident -1 Invalid device name or number 0 Request has been enqueued +1 Device has been attached to task


BREAK DEV , (EV) Expansion:


This directive places an instruction in the queue head of the specified device requesting that the associated device EXIT at the next appropriate time. It is the standard method of effecting the exiting of a transient I/O handler task.

Returned event variables: -4 IOHT is permanently resident -3 Device break already made -2 IOHT not in core -1 Invalid device name or number 0 Reguest is pending +1 IOHT has exited


DEALLOC ALBLK , (EV) Expansion:

MOV #EV,-(SP) MOV #ALBLK,-(SP) TRAP 14

This directive releases a contiguous area within the disk scratch file allocated from DOS at the initiation of the SPEX run phase. The number of blocks is specified in the first of the two-word block ALBLK, and the absolute disk location is specified by the second word. This corresponds to the formation of ALBLK following an ALLOC directive.

Returned event variables: -3 Improper length or starting address +1 Deallocation complete


DECLARE Expansion:

TRAP 7

This directive triggers a scan of the Active Task List (ATL). As a result of the scan, CPU control will be turned over to the highest priority task ready for execution. When the task is or becomes the caller, control returns at the instruction following the DECLARE.


DETACH DEV , (EV) Expansion:


This directive detaches the specified device from the caller, following a previous attach directive. The request will be enqueued if necessary in a busy device queue, FIFO within the set of I/O directives issued by the task since the ATTACH directive.

Returned event variables: -3 Task already issued DETACH -2 Device never ATTACHED by caller -1 Invalid device name or number 0 Request has been enqueued +1 Device has been DETACHED from task

SPM/7-72 SPEX P r o g r a m m i n g Manua l P a g e 2 - 1 0

ERASE NAME , (EV)

E x p a n s i o n :

MOV # E V , - ( S P )

MOV #NAME,-(SP)

TRAP 35 This is one of the three directives involved in the transfer of (typically transient) data between tasks without common data areas. The named data block previously created by a POST directive is deleted, from the executive storage area.

Returned event variables: -1 Data block does not exist +1 Deletion completed


EXIT (EV) Expansion:

MOV #EV,-(SP) TRAP 6

This directive terminates execution of the caller task and removes it from the Active Task List. Unless the task is fixed in core (see the FIX directive) the core occupied by the task is freed. An exit does not free any additional core acguired by the task via ASKCOR or GETCOR directives. If such core is to be released, it must be done by the exiting task (or any other): via the FREECOR directive. The EXIT directive should not be issued until any pending actions that may affect the task core area, such as pending I/O operations or the posting of event variables, have been completed. The optional event variable is obviously useful only for transferring information to some other task that the exit has taken place.

Returned event variables: +1 Task exit complete


FIX TASK , (PRI) , (EV) Expansion:

MOV #EV,-(SP) MOV #PRI,-(SP) MOV #TASK,-(SP) TRAP 15

This directive loads an inactive task into core, fixing it for rapid response to execution by the REQUEST directive. It is not activated by the FIX directive itself. However, if the task is an I/O handler, it is automatically initialized so that it is ready for I/O directives. In this case FIX and REQUEST are equivalent . . ( , A task which has been brought to core by FIX remains in core when it executes an EXIT, and can be re-activated immediately by a subsequent REQUEST. In order to effect a complete exit, an UNFIX directive must be issued before or after the task issues its EXIT. Except in the case of calling IOHT's, the optional priority of this directive does not assign the priority of the task being called, but does determine the priority of the associated disk reguest.

Returned event variables: -5 Task not on disk -4 Task already fixed in core -3 Task is active -2 Task not in System Task list 0 Task loading is underway

+1 Task is fixed in core


FREECOR PAGE, PART, NPART, (EV) Expansion:

MOV #EV,-(SP) MOV #NPART,-(SP) MOV #PART,-(SP) MOV #PAGE,-(SP) TRAP 32

This directive frees the core area designated by the page number PAGE, the starting partition PART, and the number of partitions NPART. When the core is freed, a scan of the Active Task List is automatically taken, since the action may enable a pending operation involving the core. Error returns include those regarding the "syntax" of the directive, and an attempt to release core that is part of the executive. If the core area was not occupied in whole or in part, it is not freed and the event variable is -4,

Returned event variables: -4 core has not been freed; the specified area was not

completely occupied -3 Reguest involves the executive area -2 Page violation -1 Invalid page number +1 Core has been released


GETCOR PAGE, PART, NPART, (EV) Expansion:

MOV #EV,-(SP) MOV #NPART,-(SP) MOV #PART,-(SP) MOV #PAGE,-(SP) TRAP 3n

This directive requests the allocation of the core area designated by the page number PAGE, the starting partition PART, and the number of partitions NPART. Since there is no queueing of core requests in SPEX, this directive will hold further execution of the task if the core is not available at the time of the request, and is therefore equivalent to a WAIT for core availability. The special case of a request for core that is part of the executive area, hence never available, leads to an immediate error return.

Note that the implied WAIT of the GETCOR directive may be avoided by use of the ASKCOR directive, which returns immediately if the core is not available when requested.

Returned event variables: -3 Core request involves executive area -2 Paqing violation -1 Invalid page number 0 caller is waiting for core +1 Core allocated to caller


IOINIT IOLINK Expansion:

MOV #IOLINK,-(SP) TRAP 25

This directive is used exclusively by I/O handler tasks to establish linkages that integrate the task with special control blocks of the executive relating to I/O services. The IOLINK is a control block within the IOHT that is in turn filled with information necessary for the interrupt logic of the handler task.

Details of the structure and operation of an IOHT are given in Chapter 5.


MESSAGE MSGBLK, (EV) Expansion:

MOV #EV,-(SP) MOV #MSGBLK,-(SP) TRAP 20

The message directive is implemented for special• information transfer between the console teletype and a task, over-riding the normal QTRAN priority with respect to this device. It is.used for control information and error message handling by normal tasks and I/O handlers.

Details of the MESSAGE directive and its relationship to a console QTRAN are given in Chapter 4.

Returned Event varibles: 0 message reguest is queued

+n number of BYTES transferred


ORWAIT EVTAB Expansion:

MOV #FVTAB,-(SP) TRAP 2

This directive is an extension of the WAIT directive to allow a task to test the status of an arbitrary number of event variables, entering the WAIT state until any one of the event variables goes non-zero.

EVTAB is a table of addresses of all event variables that are to be examined, and is terminated by a zero word. When the directive is issued a scan of the Active Task List is triggered. In this scan, and every subsequent ATL scan triggered by a significant event until the task leaves the ORWAIT state, the list of all event variables will be searched for a non-zero event variable.

When control returns to the caller at the instruction following the ORWAIT trap, the caller must examine, in the order best suited to its logic, which of the event variables has gone non-zero. Regardless of this order, it is clear that ATL scanning overhead is reduced if the list of event variables is arranged according to the expected frequency of occurrence of the associated events, the highest frequency appearing first.


PAUSE (RA) , (EV) Expansion:

MOV #EV,-(SP) MOV #RA,-(SP) TRAP 23

This directive is provided for long real-time tasks, where it is desirable to execute them in serial fashion over a number of time slots. Execution of the task is suspended and the current core image is moved to the secondary task area allocated on the disk during initiation of the run phase. A subsequent request for this task will bring in the paused version and continue its execution. This feature can be over-ridden by first issuing the REFRESH directive, which will cause a subsequent request for the task to transfer in the original image rather than the paused image,

The REQUEST-PAUSE-REQUEST sequence is used when the task is in the midst of some calculation which is to be continued later, but its core area is now needed. If, however, the whole task is to be repeated later, but for a different external buffer say, then the REQUEST-EXIT-REQUEST sequence is preferred. This eliminates the core to disk transfer. RA is an optional resumption address for the task. If it is not used, the paused image will be restarted at the instruction following the PAUSE. EV is useful only for communicating to another task the information that the paused task has been transferred to the disk and its core area is now free. NOTE: If the event variable is negative, control is returned immediately to the caller at the instruction following the TRAP, irrespective of the resume address. The same strictures with respect to pending requests that are mentioned in the EXIT directive should be observed here.

Returned event variables: -5 No disk space allocated for PAUSE image -4 NOW bit not set in STL -3 Task fixed or always resident 0 pause I/O is queued or underway +1 Task PAUSE image is on System Disk


POST NAME, DATBLK, (EV) Expansion:

MOV #EV,-(SP) MOV #DATBLK,-(SP) MOV #NAME,-(SP) TRAP 33

This is one of the three directives (POST, READ, ERASE) that manipulate seven-word information blocks for communication between tasks that have no common data areas. Seven words of data at the address DATBLK are transcribed into the dynamic queues of the executive, given the label specified by NAME, for later access by a READ directive. A POST directive for a named block which already exists rewrites the contents of the block. A block created by a POST directive is deleted only by the ERASE directive.

Returned event variables: +1 Named block is created +2 Named block is rewritten


QTRAN DEV, TRNBLK, (EV) Expansion:

MOV #EV,-(SP) MOV #TRNBLK,- (SP) MOV #DEV,-(SP) TRAP 10

This is the basic I/O directive for the transfer of data between devices and core. It effects the queueinq, priority ordered at the priority of the calling task, of an I/O reguest to the specified device. The operation requested is detailed in the five-word block TRNBLK, the first four of which correspond in qeneral to the contents of a DOS-type TRAN block (Device block number, Memory start address. Word count, and the Function-status word). The fifth word has a function which is device dependent. A detailed description of the QTRAN directive is given in Chapter 4,

Since completion of the operation is cooperative between the queuing logic of the system and the logic of individual handlers, not all possible event variables are listed here. Specifically, event variables less than -3 are reserved for handler error returns, while all positive return values denote successful completion in various ways (possibly simply +1, possibly the number of words or bytes transferred). Chapter 4 details these returns for individual handlers.

NOTE: As with all SPEX directive arguments, DEV is a word containing the device name or number; its address is stacked.

Returned event variables: -6 Handler is BROKEN -3 Handler finds invalid TRAN block -2 Associated handler not in core -1 Invalid device name or number 0 QTRAN reguest is queued

+X Handler completion code


READ NAME, DATBLK, (EV) Expansion:

MOV #EV,-(SP) MOV #DATBLK,-(SP) MOV #NAME,-(SP) TRAP 34

This is one of the three directives (POST, READ, ERASE) that enable short (and typically transient) data transfers between tasks that have no common data areas. The data block DATBLK within the task area must be seven words long, since this many words will be passed to it from pre-stored data in the executive area.

NAME is the name employed in a previous POST command that caused the storing of a seven-word data block within the executive. READ causes the transfer of this data to the caller's area DATBLK. The executive data block remains intact, and can be deleted only by the ERASE directive.

Returned event variables: -1 Data block does not exist +1 Data transfer completed


REFRESH TASK, (EV) Expansion:

MOV #EV,-(SP) MOV #TASK,-(SP) TRAP 17

This directive relates to the execution of tasks which may PAUSE and continue in serial time slots, being rolled out to the disk during their paused state. Ordinarily, a subsequent request for the task brinqs in the paused version of the task. The REFRESH directive resets the logic so that a subseguent request brings in the original version of the task.

In order to be effective, the REFRESH must be executed in the period while the subject task is in the paused state on the disk, and before the next request for it is issued. If the task is active when REFRESH is issued, its own PAUSE will automatically nullify the REFRESH logic.

Returned event variables: -3 Task is not in STL or not in paused state +1 Refresh logic is set


REQUEST TASK, (PRI) , (EV) Expansion:

MOV #EV,-(SP), MOV #PRI,-(SP) MOV #TASK,-(SP) TRAP 5

This directive requests the execution of a task at the specified priority if PRI is specified, or at the default priority given in the System Task List if PRI is not used. The task may be resident but inactive (a fixed task), or non-resident. In the latter case, action is begun to initiate the transfer of the task from the disk, during which time the event variable remains at zero. The event variable goes positive when the task is activated.

If the requested task is an I/O handler, activation implies that the task has also been initialized and is ready for QTRAN or other I/O directives.

Returned event variables: -5 Task not on disk -3 Task is active -2 Task is not is System Task List 0 Task loading underway +1 Task is activated

SPM/7-72 SPEX Programming Manual Page 2-24 *

RESUME TASK, (RA) , (EV) Expansion:

MOV #EV,-(SP) MOV #RA,-(SP) MOV #TASK,-(SP) TRAP 4

This directive calls for resumption of a task held-in the Active Task List whose execution was self-terminated by a SUSPEND directive. The resumption address RA is optional, and if not used, execution of the task continues at the instruction following the SUSPEND.

Unless the RESUME directive is erroneous, it triggers a scan of the Active Task List.

Returned event variables: -3 Task not in suspend state -2 Task not in System Task List -1 Task not in Active Task List +1 Task is resumed


SUSPEND Expansion

TRAP 3

This directive causes execution of the caller task to terminate. The task remains in the Active Task List, but is by-passed in all scans of the ATL until another task re-enables its execution by the RESUME directive.

Unless the RESUME reguest specifies a different address, the suspended task regains control at the instruction following SUSPEND.


UNFIX TASK, (EV) Expansion:

MOV #EV,-(SP) MOV #TASK,-(SP) TRAP 16

This directive nullifies a previous FIX directive relating to the specified task. If the task is active it will remain so until it issues an EXIT directive. If it is inactive, UNFIX is eguivalent to an exiting directive (but from another task), the core occupied by the specified task is freed, and a significant event declared.

Returned event variables: -2 Task not in STL +1 Task is unfixed


WAIT EV Expansion:

MOV #EV,-(SP) TRAP 0

This directive holds up execution of the caller task unless or until the event variable EV has a non-zero value. The value must be controlled by some other activity (a task or external signal) that will eventually cause resumption of the waiting task, if EV is zero at the execution of WAIT.

Issuance of a WAIT causes a scan of the Active Task List whether or not EV is zero at the time.


Chapter 3

The Conversion Directive

A


Documentation on the conversion directive is in preparation.

In the meantime, the user may reference the conversion support supplied by DOS via the CVT module, which SPEX has incorporated in sliahtly modified form. Arguments and error returns are identical, the only difference is that everywhere in the calling list as documented in the DOS Manual, the actual trap EMT 42 is to be replaced by TRAP 100.

The conversion services include (see DOS Manual) : .RADPK - Pack 3 ASCII characters to a RAD50 word .RADUP - Unpack a RAD50 word to 3 ASCII characters .D2BIN - Convert 5 decimal ASCII chars to one binary word .BIN2D - Convert a binary word to 5 decimal ASCII character .02BIN - Convert 6 octal ASCII characters to one binary word .BIN20 - Convert a binary word to 6 octal ASCII characters

NOTE: Convert codes and values to be converted are placed directly on the stack. This violates the SPEX convention of placing addresses of arguments on the stack.


Chapter 4

The QTRAN and MESSAGE Directives

4.1 The QTRAN Directive in General

4.2 The Console Teletype - QTRAN and MESSAGE 4.3 QTRAN to Disk and Dectape 4.4 QTRAN to Magnetic Tape

A


4. 1 The QTRAN Directive in general

With the exception of the console teletype, for which there is an additional directive implemented called the MESSAGE directive, the QTRAN directive is the unique command to cause the transfer of information between the standard devices of a PDP-11 system and the core area, as well as to control those devices which have non-data transfer characteristics (such as a magnetic tape rewind). The QTRAN directive has the expansion:

MOV #EV,-(SP) MOV #TRNBLK,-(SP) MOV #DEV,-(SP) TRAP 10

As with all directives involving I/O devices, "DEV" may contain either the logical unit number of the device or the standardized RAD50 name of the device, according the the following table:

Console teletype Console teletype The DF disk Magnetic tape Card reader Line printer Dectape The DK disk Video Tube

An additional device name, "DTJM", for which there is no corresponding logical number, allows for a dummy data transfer directive. The device name "SYS" is also defined as the System Disk, either DF or DK as the case may be. (See Section 4.3.) NOTE: As with all SPEX directive arguments, DEV is a word containing the device name or number; its address is stacked,

All the essential information about the action being requested on the device is contained in the five-word block referred to as "TRNBLK" in the sample call given. Since the directive is the same for all devices, not all five words of the TRAN block are relevant to a particular device, but the following are the functions of the individual words of the TRAN block:

1 Device Block Number 2 Memory Start Address 3 Word Count (positive number) 4 Function/Status 5 DDA (Device Dependent Auxiliary) word

1 2 3 4 5 6 7 10 11

KB KB DF MT CR LP DT DK VT


Device Block Number (Word 1) This word is significant only for random-access devices such as disk or Dectape, for which a starting block on the device is definable.

Memory Start Address (Word 2)

This is always relevant, since it defines the first word of a core buffer from or into which data is to be transferred.

Word Count (Word 3) Always relevant, it specifies the number of words involved in the transfer. In transfers out of core, the word count is exact, and transfers to byte-oriented devices should ensure an even number of bytes, including a null byte at the end of the data if necessary. In transfers into core, the count may be exact, when dealing with passive devices such as a disk, or it may simply represent the maximum input allowed (to protect overflowing a core buffer). The latter is the situation when dealing with a device such as the teletype, which can terminate the transfer at any point by the entry of a delimiter character.

Function Byte (Word 4 - Low Order Byte) The standard values of the function byte for data transfers are:

2 Output from core to device 4 Input from device to core

A negative function byte denotes a special device function (such as REWIND) and appropriate values are given under the devices for which such functions are defined.

Status Byte (Word 4 - High Order Byte) This byte must include the unit number where a multi-unit controller is involved, such as Dectape or Magtape.

DDA Word (Word 5) This is a SPEX extension of the transfer control block of DOS. It is useful for device-dependent options. Currently it is relevant only in console keyboard input, but for compatibility with possible future revisions, it should be set to zero in all cases where it is not currently used.


4.2 The Console Teletype - QTRAN and MESSAGE.

The console teletype is unique in havinq two modes of I/O access - the normal QTRAN mode and the MESSAGE facility. The QTRAN mode is priority queued in the same manner as with any other device. This creates problems with regard to getting out unexpected error messages or entering asynchronous control commands to tasks other than the one currently in control of the console. For this purpose, the MESSAGE facility, which over-rides current QTRAN activity, has been devised. Both methods of access are described in this section.

QTRAN to the Console Teletype. The console has the device name KB, and logical unit numbers 1 and 2 which may be used interchangeably. Output to the teletype utilizes only the first four words of the QTRAN block. When the transfer is complete, the event variable is set to the number of bytes (not words) transferred. Input from the keyboard utilizes all five words of the QTRAN block. The fifth word is used to specify arbitrary input delimiters. If it is zero, the delimiter is uniquely a carriage return. If it is non-zero, it is taken as the address of a delimiter list in the caller task. The delimiter list is a string of consecutive bytes, each of which is a typable character, terminated by a null byte. When any of the characters in the list is entered during the QTRAN it functions as a delimiter and input is terminated. The delimiter is always passed to the user buffer on input. Since the event variable on successful termination is egual to the number of bytes transferred, the actual delimiter used in any particular input is easily determined. Successful termination of QTRAN input is not guaranteed because of the over-riding priority of console transmissions via the message facility. If MESSAGE input or output is executed while the console is processing QTRAN input, the input is broken off and the QTRAN event variable will be set to -4. This technique allows the caller task to restart the input with some logical "prompting" output, thereby avoiding confusion as to where the previous input was broken. Since MESSAGE transfers will allow QTRAN output to terminate normally before intercepting the console, there is no possibility of a -4 event variable in output transfers.

The MESSAGE Directive.

This directive is implemented to provide an additional I/O channel to the console teletype only. It is particularly suitable


for control and error messages since it will over-ride QTRAN activity on the console. It incorporates the possibilities of messaging out to the console without reply expected, messaging out and priming the system for a reply, or simply priming the system for operator messages to a task, without taking over the exclusive control of the teletype that occurs in QTRAN operations.

The form of the directive is MESSAGE MSGBLK, (EV)

with the expansion: MOV #EV,-(SP) MOV #MSGBLK,-(SP) TRAP 20

where the message block consists of four words: 1 ID1/ID2 Identifier bytes 2 NOUT/NIN Count b y t e s 3 BUFOUT Output buffer address 4 BUFIN I n p u t B u f f e r a d d r e s s

The Identifier (Word 1) The bytes ID1 (low-order) and ID2 (high-order) are supplied by the task as identifier characters to be associated with the message. A full two-character identifer is specified by supplying typabie characters in both byte fields. A one-character identifier is specified by leaving the second byte (ID2) a null byte. The completely null identifier (ID1=ID2=0) is legal. On output, the message identifier is typed immediately after a couple of line feeds and an asterisk supplied by the handler. On input, the identifier is used to relate the message to a reply expected by a task which has previously issued the MESSAGE directive. To input such a message reply, the operator presses CONTROL/A. The handler will break off QTRAN input immediately and echo, or, if output is current, will echo as soon as the output is completed normally. The echo consists of a couple of line feeds and the characters "|A" (or the equivalent on an LA-30 teletype). The operator then types the one or two character identifier, a space and the message line. When the line is completed by a carriage return (the exclusive delimiter for MESSAGE input) or terminates on character count, it is signalled to the caller task via the MESSAGE event variable, and pending QTRAN activity resumes. Typing CONTROL/C (echoed by "|C") rather than CONTROL/A immediately associates the incoming message with a null-identifier message block. The convenience of not having to


include an input identifier makes this particularly useful for the most frequently contacted control task within the system. Obviously the identifiers issued by different tasks using the MESSAGE facility should be unique, or confusion will result. The system itself reserves the use of the identifiers which are the names of I/O handler tasks (DT, MT, and so on) as listed at the beginning of this chapter, for I/O error messages.

Byte Counts (Word 2) The low order byte NOUT controls the number of characters output, while the high order byte (NIN) specifies the maximum number of bytes to be input as a result of the message directive. Note that, unlike the QTRAN directive, the MESSAGE directive is totally byte (character) oriented. Also note that, although the delimiter of MESSAGE input is always a carriage return, it will propaqate to the caller buffer and be counted as an input character. If NOUT is greater than zero, the handler types a couple of line feeds, an asterisk, the identifier (if any), a space, and NOUT bytes from the task buffer specified in word 3. A carriage return and a couple more line feeds are automatically supplied to make the message visible. If NOUT is zero, the same output is generated, excluding a task message. This may be used to indicate that a task is primed for input on the specified identifiers. If NOUT is negative, no output at all takes place. This is the normal way to re-prime a task for input after a MESSAGE sequence has been completed (memory of pendinq input on a particular identifier is erased whenever a messaqe is input on that identifier) . NIN specifies the maximum number of characters to be transferred into the buffer specified in Word 4. The count recorded by the handler will include the delimiting carriage return, and may of course be less than NIN. If NIN is zero or negative, it signifies that no reply is expected for the given message. Input processing follows output processing, when both NOUT and NIN are positive in a message block. The event variable of MESSAGE is always set to the number of bytes transferred. When only output is specified (NIN zero or negative) the variable will be set to NOUT as soon as the output is completed. When input as well as output, or input only, is specified, the event variable is not set until an operator message has been received on the specified identifier.

Output Buffer (Word 3) Contains the address of when NOUT is greater unimportant,

& ■

the start of an output character string, than zero. Otherwise, its contents are


Input Buffer (Word 4) Contains the address of the start of an input buffer when NIN is greater than zero, otherwise its contents are unimportant. The buffer should have a byte length greater than or equal to NIN.


4.3 QTRAN to Disk and DECTape

Both these devices are block oriented. Neither has any Special Functions. The TRAN block is exactly as described in Section 4.1. The fifth word (DDA) is zero. For reference, the device block sizes (words) are:

DF 100 (64) DK 400 (256) DT 400 (256)

A certified DECTape has 1102 blocks, but blocks 0 and 1101 are used only for turn-around and never contain data. The high byte of word 4 must contain a device unit number (0-7) for DT and DK.

The System Disk SPEX is conditionally assembled so that either the DF disk or the DK disk is the "System Disk", independently of whether the other exists as a regular device. The System Disk is defined to be that disk on which all task image files, all NOW image files (including PHACOM.NOW), and COMMON files reside, If it is not known which disk is the current System Disk, it can be referred to with the RAD50 device name "SYS". (Its block size and PDB address is given in the System Control Block. See Appendix D.)


Chapter 5

Interrupt Programming and I/O Handlers

5. 1 Special Directives 5.2 Interruption Servicing and "Hold" Mode 5.3 ILSR Procedures and Register Protection 5.4 The Structure and Operation of an IOHT


5. 1 Special Directives

Previous chapters have dealt with the so-called "normal Directives"' used by general processing tasks running under SPEX, and with the "Conversion Directive" which is only abnormal in that it encompasses a number of conversion services and also flags errors in a non-standard fashion.

In this chapter we describe the purpose and operation of a set of so-called "Special Directives", all of which are related to the problems introduced by I/O Handler Tasks (IOHT's) and associated or independent interrupt level service routines (ILSR's). The concept of a "holding mode" is also introduced, which may be of use to normal tasks, although most special directives are designed for IOHT's and ILSR's.

Given their purpose, special directives are characterized by being executed at somewhat higher speed than normal directives, as the automatic register saving that occurs with the latter is suppressed by the directive handler. This is not to say that registers are not protected, but only that they are saved on an ad hoc basis by the logic of each directive processor as necessary. In order to speed up execution further, there are for some special directives an access method using a system global that saves the time necessary to decode a trap directive into a specific jump. The "trap" method provides location independence where this is felt to be desirable. The "global" method sacrifices this feature, but executes at higher speed. Ordinarily, the latter method will be favored, but both are available.


The six special services to be discussed are the following:

(1) Declaration of a significant event from an interrupt level, the "interrupt Directive".

(2) Performing a "logical RTI" at an interrupt level, by means of the "RTI Directive".

(3) Dropping hardware priority after it has been raised by software from the task level (priority 0 ) , by means of the "Drop Directive".

(4) Calling the next queued item from an I/O handler queue by means of the "IGET Directive". This is used only by IOHT's.

(5) Suspension of an IOHT while I/O is underway, by means of the "ISUSP Directive.

(6) Exiting of an IOHT by means of the "disconnect Directive".

The explicit forms of these directives appear on the following pages. Their roles are described in subsequent sections on interruption servicing in general, and on the structure of I/O Handler tasks in particular.

In connection with interrupt servicing, the status of the stack is of vital importance. Several of the special directives are based on a precise condition of the stack, by which the status of an interrupted task may be located. In the description of the special directives, it is specified when interrupted registers must be saved prior to issuance of the directive, and when they must not be. Saving registers and restoring them are simplified by the use of two globally accessible subroutines of the executive, and whether they are actually employed or. not, a "register save" implies a stacking of registers in the same order as that of the global subroutine. The two subroutines are S.RSAV, for saving registers, and S.RRES for restoring them:

JSR R5,S.RSAV Stacks the current registers in the order R5, R4, - - ,R0. If the executive has been conditionally assembled to protect EAE as well, then the AC (777302), the MQ (777304) and the SC/SR (777310) are also stacked in that order.

JSR R5,S.RRES Pops the stack into the EAE registers (conditionally) and then the general registers, in the reverse order consistent with a previous save by S.RSAV.


The Interrupt Directive

This directive constitutes the declaration of a significant event from an interrupt level. When it is issued, the registers of the interrupted logic must have been saved on the stack. The directive has both a TRAP and a global form. Furthermore, the call differs depending on whether the ILSR is a "pure" interrupt routine (not part of a task which it wishes to reactivate) or whether it is part of, for example, an I/O handler.

For the pure ILSR, a zero is pushed onto the stack: CLR -(SP) CLR -(SP) TRAP 300 • JMP $INT

For an ILSR which is also seeking activation of its associated task, the address of its IOLINK block (see the section on IOHT structure) is pushed onto the stack:

MOV #I0LINK,- (SP) MOV #I0LINK, - (SP) TRAP 300 JMP $INT


The RTI Directive

This directive must always be employed in lieu of a true RTI from an interrupt level service routine. The rationale is discussed in Section 5.2.

Since issuance of the RTI directive is logically equivalent to an RTI, the stack at the time it is issued should be in the precise state as it was at the time-of entry into the ILSR (only the PS and PC of the interrupted logic on the stack).

The directive has both a trap and global form:

TRAP 304 JMP $RTI


The Drop Directive

This directive is employed when a normal task has previously raised CPU priority above zero and wishes to return to the normal zero priority. As explained in Section 5.2, simply dropping the priority directly may cause the loss of the declaration of a significant event, memorized by the system during the high-priority interval. To protect against this, the task gives SPEX the opportunity to check this situation at the same time that it drops the priority. The directive exists in both trap and global form:

TRAP 305 MOV 3)#PS,-(SP) JSR PC,$DROP

Notice that the global form simply simulates the trap in: this case. If the status bits of the status word (PS=177776) are of no interest, the MOV instruction in the: global form may be replaced by CLR - (SP) . This will cause clearing of all status bits, since the directive simply clears the CPU priority bits of the stacked status word and returns with the result as the new CPU status word of the task.

It should be noted that execution of any Normal directive implies a "DROP".


5.2 Interruption Servicing and "Hold" Mode

The SPEX executive includes resident handlers for disk and teletype I/O. Handlers for other standard devices exist as SPEX tasks which can be located at the user's discretion via BUILDX and accessed by the QTRAN directive. But it is in the nature of the experiments for which SPEX was designed that there will be special user devices whose purpose is to generate interrupts and alter CPU control based on external conditions. In this section are discussed the SPEX conventions that need to be understood when designing software for such devices.

A recurrent theme in SPEX operations is the triggering of an ATL scan due to the occurrence of a significant event. Since the scan itself takes a finite amount of time, one must be certain that an external interrupt that changes the state of a task already scanned does not pass unnoticed. A similar problem arises with respect to the manipulation of the queue of an I/O device while action on the device is underway. To keep the response of the system to external interrupts rapid, the simplest solution, raising the CPU priority to high hardware levels during these extended operations, has been rejected. Instead, a software scheme is applied to permit hardware interrupts during these critical processes without causing erroneous scan decisions or misplaced queue entries. All interrupt level software must protect the integrity of this scheme, by appropriate use of the "INTERRUPT" and "RTI" directives.

Interrupt support in SPEX includes the maintenance of a single flag to indicate that a significant event has occurred at some hardware level, The flag is set by issuing the "INTERRUPT" directive. While the form of the directive permits the simultaneous re-activation of an associated task (an IOHT), we are at the moment only interested in its effect in triggering an ATL scan. For this purpose, the stacked priority at the time of the interrupt is checked. If it is non-zero, the requested ATL scan is not made and the interrupted logic proceeds. If it is zero, the interrupted logic (a task) is appropriately "canned", in a form suitable for restoration of its registers, status, and stack when it is next the highest priority item in the ATL, and the ATL scan request is honored.

Because an ATL scan can be deferred by this process, any software operatinq at a non-zero priority (with the exceptions noted below) must permit a check of the interrupt declare flag when it is ready to relinquish the priority. An interrupt level service routine, if not itself declaring a significant event, must issue the "RTI directive". A normal task that raises priority for any reason must issue the "DROP directive". As an alternative for normal tasks, it should be noted that issuing any normal directive (codes less than 100) automatically clears the PS of the issuing task. Therefore any logic performed by a task at


raised priority may also terminate with directives such as DECLARE, WAIT, REQUEST, and so on.

Exceptions to the above rules apply to the two highest hardware levels of the PDP-11.

Level 7 is special in that the SPEX executive never employs this level. It is the philosophy of SPEX that this level should be reserved for interrupt activity that is essentially never blocked by CPU activity. To keep Level 7 open, it is imperative that no significant, event be declared from this level. Following a period in which ATL scanning could have been deferred due to non-zero hardware priority, SPEX rises to level 6 to check the interrupt declare flag. Declaring from level 7 poses the remote possibility that the flag may change just after inspection, deferring the intended scan for an indefinite interval.

Level 6 is special in that it is equal to the maximum of SPEX operations and also does not have to worry about hiqher level declarations. Therefore it shares with level 7 the ability to employ a true RTI (if an interrupt routine is involved) or direct clearing of priority (if a normal task) without the need to check for a nested ATL scan request.

"Holdinq Mode"

The hardware priority conventions described are implemented in SPEX to handle two problems of interrupt logic with minimum overhead. Nested interrupts, in any mix of significant or non-significant termination, are taken care of in a direct manner. In addition, the scheme incorporates the concept of a "holding" priority which does not disturb the critical time response reguired by the hardware of certain devices. A "holding" priority is any innocuous hardware level above zero, typically priority one. Setting this priority places a task in "holding mode", which insures that the coding in process cannot lose CPU control to another task until a logical point of its own choosing, over-riding in effect the associated software priority of the task. Holding mode is employed by the executive during scan and gueueinq operations. The directives and globals mentioned have been developed to make it useful to tasks as well, for example to protect EAE operations or user queueing logic. A holding priority can usually be used in place of a high hardware level, and is preferable since it cannot cause troubles such as time-out errors on disk or dectape. Note, however, that the hard priority during and after a Normal Directive is zero. In fact, executing any Normal Directive executes the DROP directive as well.


Chapter 7

Preparation of the XSTL

7.1 purpose of the XSTL Module 7.2 The Form of an XSTL 7.3 Example of an XSTL Module


7.1 Purpose of the XSTL Module

A module which must be prepared by the experimenter and incorporated into the executive at build time is one which specifies all the tasks which are to be entered into the System Task List. This list excludes standard I/O handler tasks and other specific tasks within the executive that are not of direct concern to the experimenter. For this reason the task list referred to here is given the name XSTL, for Experimenter's System Task List, although the user of course has the option of choosing any file name and module name for his list.

The XSTL module contains, in the form - of linked nodes, a list of all the experimenter's tasks that may be called during a run. For each task, four pieces of information must be supplied:

(1) The three-character name by which the task will be referenced in the run.

(2) The file name under which the task image resides on the disk. The extent of this file is always SPX, and is not specified.

(3) The default software priority of the task, within the range of 0 to 77 (octal)., This priority may be over-ridden by directives calling the task.

(4) Whether or not a NOW file should be allocated for the task. A NOW file is a contiguous disk file equal in size to that of the task SPX file, with the same file name but the extent NOW. It is used for PAUSE or debugging images of the task during its execution.

7.2 The Form of an XSTL

The order in which tasks are listed in XSTL is of no significance. The first and last entries, however, must make reference to particular global names, two internal and two external, that effect the linkage of the XSTL list with the internal system task list of the executive.

SPM/7-72 SPEX Programming Manual Page 7

The globals internal to XSTL are:

$SSTL - the first of the experimenter's entries must be given this label (Start of STL). $ESTL - The last of the experimenter's entries must be given this label (End of STL).

The external globals to be specified are:

35BSTL - The first of the experimenter's entries must use this symbol as its back pointer (Back STL node) . $FSTL - The last of the experimenter's entries must use this symbol as its forward pointer (Forward STL node).

The general format of an STL entry is:

ford Byte Entry Remark Points to next node Points to previous node RAD50 0 •= no ; 20 = yes First RAD50 word Second RAD50 word

Software level (0 — 77)

1 2 3 4 5 6 7 8 9 10 -

o. 2 4 6 10 12 14 16 20 22

Fwd Ptr Back Ptr Task Name NOW Flag File Name File Name Reserved Reserved Priority Reserved


7.3 Example of an XSTL Module

On the following page is given an example of the coding of an XSTL that defines three tasks. It exhibits the use of the qlobals mentioned, in conjunction with words defining fixed displacements, to form the list as linked nodes.

The first task will be referenced in execution by the name "ONE". Its core image resides on the disk as the file MYONE.SPX, it runs at a default priority of 50, and reguires no secondary disk space for PAUSE or debugqing images.

The second task will be referenced in execution by the name "TWO". Its image file on the disk is named TWOV1.SPX, and it runs at a default priority of 60. Since the task may PAUSE, the flag is set to request allocation of a file TWOV1.NOW durinq preparation of the run phase of SPEX.

The third task is called "END", runs at priority 70, resides in core image on the disk as the file END.SPX, and requires no NOW file.

Any additional tasks may be placed after the first, with the same forward and back pointer declarations as the second task, without modifying other entries.


EXPERIMENTAL XSTL EXAMPLE

NOW=20 .TITLE XSTL .GLOBL $BSTL,$FSTL,$SSTL,$ESTL

;FLAG FOR NOW FILE

;TASK $SSTL:

;TASK

;TASK $ESTL:

ONE

TWO

END

• WORD .WORD .RAD50 • WORD .RAD50 .RAD50 • WORD .WORD .WORD

.WORD

.WORD

.RAD50

.WORD

.RAD50

.RAD50

.WORD

.WORD

.WORD

.WORD

.WORD

.RAD50

.WORD

.RAD50

.RAD50

. WORD

.WORD

.WORD

. + 24 $BSTL /ONE/ 0 /MYO/ /NE/ 0,0 50 0

.+24

.-26 /TWO/ NOW /TWO/ /TV 0,0 60 0

$FSTL .-26 /END/ 0 /END/ / / 0,0 70 0

POINT FWRD TO NEXT NODE POINT BACK TO EXECUTIVE TASK NAME no NOW FILE FILE NAME

TWO RESERVED WORDS DEFAULT PRIORITY RESERVED

; POINT TO NEXT NODE ;POINT TO LAST NODE ;ENTRIES AS ABOVE, BUT ;THIS REQUIRES NOW FILE

STL

;POINT FWRD TO EXECUTIVE STL ;POINT BACK TO LAST NODE ;AS ABOVE, AND FOR THIS TASK ;NO NOW FILE ;SINCE LESS THAN 4 CHARS IN FILNAM ;THIS COULD ALSO BE .WORD 0

END


Chapter 8

Preparation of the XCOM

8.1 Purpose of the XCOM Module 8.2 The Node Pool Area 8.3 The PHACOM Area 8.4 The Commons Area 8.5 Example of an XCOM Module


8.1 Purpose of the XCOM Module

In addition to the XSTL, the experimenter must also prepare and incorporate into the executive via BUILDX a module which defines and allocates space for common data which is to be accessible to all tasks during execution. It is also in this module that the space allocation is made for the node pool. While any name may be chosen for this module, it is referred to in this documentation as XCOM (for Experimenter's Communication section^,

There are three distinct areas in an XCOM module:

(1) The node pool area, which is given the global name SPOOL in order to resolve reference to it by the SPEX executive modules with which the XCOM is linked.

(2) The Phase Communication area into which the phase communication file PHACOM is placed at initialization of SPEX.

(3) The user commons area, headed by a descriptive table with the global name $COMTB, and followed by user commons, which are named CSECT's.


8.2 The Node Pool Area

The user allocates an area into which SPEX builds the set of linked free nodes which is used as the node pool of the system. The area must be given the global name SPOOL. The size of the area is communicated to SPEX by the contents of the labelled location SPOOL (the first word of the area). This word must contain the size of the area in words. In setting this value, the user should recall that ten. (decimal) words are required for each node. The number of nodes required durinq execution depends on the total activity ,-of the system. Typically, thirty to fifty nodes may be required, 'but only experimentation will determine an appropriate number.


8.3 The PHACOM Area

PHACOM.SPX is a disk file described in detail in Chapter 9. It forms the information link between operations performed under DOS and those performed under SPEX, principally with respect to disk files which are to be accessed by SPEX tasks. The contents of this file are entered into core at the beginning of the SPEX run phase, and remain posted there during SPEX operation.

It is the user who generates the PHACOM,SPX file on the disk and provides an area in XCOM into which the contents of the file can be placed. This area is given the global name PHACOM, and generally would be coded as a named CSECT for simplified access by all SPEX tasks. As explained in Chapter 9, the user determines the size of PHACOM above the minimum for required information, and he must be sure that the core area allocated is sufficient for the PHACOM file generated on the disk,

The first word of the allocated area must contain the size of the area in words. This word is checked by the initiator to be greater than or equal to the size of PHACOM.SPX.


8.4 The Commons Area

The orientation of SPEX being toward assembly language coding, a "common" is a named CSECT. The exact behavior of named CSECT's is detailed in chapter 6, Here it is sufficient to note that a named CSECT in the XCOM module, which is linked with the SPEX executive modules by BUILDX, is accessible to any task subsequently built by BUILDX. By "accessible" we mean that the task may contain a CSECT of the same name, and BUILDX will resolve all executable address references to the CSECT within the task as references to the CSECT created in the executive area. In this sense, a named CSECT behaves like a named FORTRAN common shared by several routines. It is important to note that we restrict the task references to executable instructions - the actual contents of such a common is not determined by the contents coded into the task CSECT, but rather by what was coded into the executive CSECT of the same name, The contents of an executive CSECT therefore always become the initial contents of a common. A "scratch" common, in which the initial values are of no importance, will always contain all zeroes, as will any area which is allocated by simply bumping the assembler location counter (,=.+X). Thus all CSECT's declared by the user in XCOM are not only commons for all tasks, but are in fact "block data" commons. This feature is exploited in SPEX by providing for the option of filling any of these executive CSECT's from disk files during the initialization of the run phase. The user may manipulate files under DOS, preparing the disk with data and parameters that will become the contents of the "block data" commons as SPEX goes into execution. This "automatic read" feature is clearly a convenience during initialization. Further transfers directly by the tasks between these commons and the disk may be executed at any time in the run phase. Automatic reading is specified in a table given the global symbol name SCOMTB. This table consists of a five-word entry for each CSECT using the auto-read feature. The list is terminated by a zero. If no commons are to be read into, the contents of the word SCOMTB (which must always be present to satisfy reference from the executive modules) itself should be zero, indicating a null list. Each entry in the list consists of four words:

1 RAD50 Name of CSECT (first word) 2 RAD50 Name of CSECT (second word) 3 1st block of associated file (entered by initializer) 4 Core location of CSECT 5 Size of common in words

The name of the CSECT must be identical to the file name of the associated disk file, which has the extent COM. If the common contents are such as can be generated in an assembly module (i.e. no floating point), the disk file is most conveniently created by


running an assembled module through BUILDX. However, PIP-11 should then be used to rename the extent to COM, since all disk files created by BUILDX are given the extent SPX. If the fifth word of the entry (the CSECT size) is zero or negative, auto-read is bypassed, and the coded contents of the CSECT will be the inital values. The user may therefore create an entry in SCOMTB for every common, and control the read process by a re-edit and reassembly involving the size-word only. Even when the size-word is positive, the initializor does not consider it a fatal error if it fails to find the associated disk file, although a message will be printed when this occurs. Therefore simply deleting the file from the system disk prior •to running SPEX will cause the contents of the common to default to their coded values.

If autoread is not bypassed, the third word of the table entry is filled in by the initiator. This enables transfer between the common's core area and its disk area during the run. If the file is shorter than the size specified in the fifth word, an error message is written, and the size is changed. (This protects the disk if the size word is used for a QTRAN output'word count.) If the file is not found, the size word is zeroed. The device is assumed to be the system disk.


8.5 Example of an XCOM Module

In the following example the user allocates a 30 (decimal) word area. Defining NODX10, which has a value of 10 (decimal) times the number of nodes wanted, makes future adjustment of this area automatic on this symbol,

The PHACOM area is allocated and similarily made convenient to adjust by means of the symbol PHSIZE. Its value in the sample corresponds to the size of one (DF) disk block, and is more than is needed for the sample PHACOM file of Chapter 8. This allows additions to the user file list without changing XCOM each time, but the experimenter will have to keep the maximum size of PHACOM in mind,

In SCOMTB two commons are declared for disk loading. However, only the first (MYC0M1) is currently expected to be disk loaded. The second (MYCOM2) is entered so that changing its size-word sign will make it disk loadable in the future.

The actual commons follow. It is expected that MYC0M3 (a scratch common) will never be initialized from the disk. Hence no mention of it is made in SCOMTB.


;EXPERIMENTER'S XCOM EXAMPLE .TITLE XCOM .GLOBL SPOOL,PHACOM,SCOMTB

ALLOCATE NODE POOL — GLOBAL FOR EXECUTIVE REFERENCE NODX10=300. SPOOL: .WORD NODX10 .=.+NODX10+NODX10

;30. NODES, 10. WORDS PER ;FIRST WORD IS SIZE IN WORDS ;RESERVE THE SPACE

.CSECT PHACOM ;ALLOCATE FOR PHACOM — GLOBAL FOR EXECUTIVE REFERENCE PHSIZE=64. ;AMPLE FOR SAMPLE PHACOM (SEE CHAP.9) PHACOM: .WORD PHSIZE ;FIRST WORD IS SIZE IN WORDS .=.+PHSIZE+PHSIZE

.CSECT EXPERIMENT COMMONS TABLE — GLOBAL FOR EXECUTIVE REFERENCE SCOMTB:

MYCOM1: .=.+5+5

MYCOM2:

.RAD50 /MYC/

.RAD50 /OM1/

.WORD 0

.WORD MYCOM1

.WORD 5

.RAD50 /MYC/

.RAD50 /OM2/

.WORD 0 •WORD MYCOH2 .WORD -5 .WORD 0

.CSECT MYCOM1

.CSECT MYCOM2 .WORD 1 .WORD 2 .WORD 3 .WORD 4 .WORD 5

MYCOM3: .=.+100+100

.CSECT MYCOM3

.END

;MYCOM1 IS A 5 WORD COMMON ;DISK BLOCK NO.—FILLED IN BY INITIALIZOR

;LOAD FROM DISK ;MYCOM2 IS A 5 WORD COMMON

;AUTO READ IS SUPPRESSED ;END OF TABLE

;ALL ZEROS IF NOT DISK LOADED

;VALUES WHEN DISK NOT LOADED

i


Chapter 9

The Phase Communication File PHACOM

9.1 PHACOM on Disk and in Core 9.2 The Purposes of PHACOM 9.3 The User File List 9.4 Example of a PHACOM Source File

SPM/7-72 SPEX Programming Manual Pacre 9-2

9.1 PHACOM on Disk and in Core

PHACOM.SPX is the name of a contiguous file which must be present on the system disk when a run is started by the "RUN SPEX" command to DOS. It is the first file sought by the run phase initiator, and guides it in the preparation of the SPEX executive that will replace DOS in core. PHACOM is also the global name of a core area reserved in the user module XCOM for overlay by this disk file, as described in the previous chapter. The core form of PHACOM will have had information added during initialization. This modified form of PHACOM is automatically written back to the disk as a file called PHACOM.NOW, just before the initiator turns CPU control over to the SPEX executive. In this chapter the term PHACOM will be used interchangeably, except where the distinction between the original disk form and the core form is relevant. In that case PHACOM,SPX will mean the contents of the disk file, and PHACOM will mean the contents of core (and therefore also the contents of the PHACOM.NOW file).


9.2 The Purposes of PHACOM

PHACOM provides services for the run-phase initiator, the executive, and for SPEX tasks during execution. One of its functions is to preserve the complementarity of SPEX and DOS by passing file information to the run phase, so that SPEX can function within the DOS file structure. It also controls to some extent the form of the executive that will be initiated. A degree of object-time run control is therefore obtained by maintaining various PHACOM-like files on disk and calling a particular one into play by renaming it PHACOM.SPX just before issuing the "RUN SPEX" command to DOS.

The information in PHACOM is such that the file can easily be created as an assembly module that is passed through BUILDX to create a contiguous disk file. An example is given in Section 9.4 of a source PHACOM module.

Information provided in PHACOM.SPX includes:

(1) The file name of the executive module to be called into core. This allows different executives to be present on the system disk, and the one appropriate to the current run to be controlled by the selection of the PHACOM file.

(2) The name of the first user task to be requested when SPEX goes into execution, referred to as the BRR (Begin Run Routine). In general, tasks which appear in the STL of SPEX are located as disk files by the initiator for future calls from SPEX. The failure to find such a file is not considered a fatal error, since the task may not be called during the coming run. Failure to find the BRR file, however, is a fatal error during initialization, since the run cannot get off the ground without it.

(3) The name, device, and size of the "scratch" file to be used by the executive in handling disk allocation directives from tasks. The initiator arranges for the allocation of this contiguous file from DOS. Only the name is necessary, since the extent is taken to be "SCR".

(4) An optional list of files to be located and/or allocated by the initiator for access by tasks during the run phase. This list allows SPEX tasks to operate on any number of files on any file oriented device (disk or dectape) without conflicting with DOS file maintenance on the devices. The "User File List" is described in Section 9.3.


The contents of PHACOM are given in the following table. Only the "basic" information is specified, since the file may be of arbitrary length when a User File List is included in it, as explained in Section 9.3, Information that must be generated by the user is unmarked. Information filled in by the initializor is marked by a dollar sign ($) .

1 0 PHACOM length in words 2 2 Executive file name (1) - RAD50 3 4 Executive file name (2) - RAD50 4 6 BRR Task name - RAD50 5 10 Scratch file name (1) - RAD50 6 12 Scratch file name (2) - RAD50 7 14 Minimum scratch file size in words 8 16 Scratch file device name - RAD50 9 2^ Scratch file block size (words) ($) 10 22 Julian date from DOS ($) 11 24 PHACOM.NOW disk address ($) 12 26 Displacement (from Byte 0) to User File List 13 30 DOS time word (lo) (S) 14 32 DOS time word (hi) ($) 15 34 Number of nodes in pool ($) 16 36 Number of nodes used ($)

The first word of the file gives its length in words. Similarly, the first word of the core area allocated for PHACOM gives the size of the area in words. The file size must be less than or equal to the core area, or else the initiator will abort the run, since it cannot then place the file into the executive.


9.3 The User File List

The twelfth word of PHACOM points to the start of the User File List within PHACOM. The start is specified as the byte displacement relative to the start of PHACOM. The use of a pointer allows for the possibility of expanding "basic" PHACOM information (whatever is not the File List). If this word is zero, there is no File List. Otherwise it points to the start of an arbitrary number of eight-word file entries. The File List is terminated by a zero or by the end of PHACOM (the size of PHACOM.SPX is contained in its first word).

Each file entry in the User File List contains 1 File name (1) - RAD50 2 File Name (2) - RAD50 3 Extent - RAD50 -4 Device Name - RAD50 (as in Appendix A) 5 Unit # /Flag byte 6 Starting block 7 Size in words 8 Reserved

The file name and extent, and the device name and unit number, are supplied by the user in preparing PHACOM.SPX, and are not modified by the initializor. The starting block of the file is always supplied by the initializor, so its initial contents are of no importance. The word size of the file is supplied by the user, but may be modified by the initializor depending on the action requested in the Flag byte (see below) . The Flag byte must have preset information set by the user in PHACOM.SPX and in turn response information is placed there by the initializor. The bits of the Flag byte have the following functions:


Bits n,1,2 - Command Code These bits form an octal number supplied by the user which constitute a command to the initializor regarding the specified file. Currently only three codes are valid:

Code 0 - Seek the file. A seek is the only command in which the file can be specified as linked or contiguous in bit 5. The other commands involve possible allocation of the file, and only contiguous file allocations are made.

Code 1 - Allocate the file as specified, with the exception that an existent contiguous file at least as large as specified may be used to satisfy the reguest. The word size in PHACOM is modified to the actual size of the file which satisfies the reguest.

Code 2 - Allocate the file only if it is currently non-existent or non-contiguous, otherwise take the existent file. In effect, the user-supplied size is ignored (and modified) if a contiguous file with the correct name and extent is found on the unit. Caution: Both codes (1) and (2) imply that if the named file is a linked file it will be deleted so that a contiguous file can be allocated.

Bit 3 - Action on failure. This bit is set by the user. If the bit is one, any failure to carry out the command (file not found or cannot be allocated) is considered a fatal initialization error. The initializor will ultimately abort to DOS rather than enter the run phase. If the bit is zero, the failure is simply posted in bit 7, and SPEX execution is continued. Bit 4 - Unused Bit 5 - File Structure A zero in this bit denotes a linked file, a one denotes a contiguous file. Except in the case of a SEEK command, this bit is forced to one by the initiator. The rationale is that linked files are only useful when they are pre-existent, since the extensive unit directory and bit-map logic necessary to generate data into a linked file is best left to DOS.

Bit 6 - Status of the Supplied File Filled by the initiator. A zero indicates that an existent file was used to satisfy the file command, a one indicates that the initiator had to allocate a new file to do so.


Bit 7 - Status of the File Command Filled by the initiator. A zero indicates that the file does not exist, and a one indicates that the file command was satisfied. Obviously a zero will never be seen by a SPEX task if bit 3 was set to indicate that failure to satisfy the command should be considered a fatal error in initialization of the run phase.


9,4 A PHACOM Example

This is the source file which, when assembled and then passed through BUILDX, will result in the file PHACOM.SPX.

.TITLE PHACOM

PHACOM:

. = . +6

.WORD 100 •RAD50 / E X E / .RAD50 / C V 1 / .RAD50 /XCH/ •RAD50 / A P R / .RAD50 / I L / .WORD 10000 .RAD50 / D F /

; S I Z E OF PHACOM ;LOADS EXECUTIVE FROM THE FILE EXECV1.SPX

;BEGIN-RUN-ROUTINE TASK NAME ; SCRATCH FILE I S APRIL.SCR

;MINIMUM SCRATCH FILE SIZE I S 10000 WORDS ;SCRATCH FILE DEVICE NAME ;SAVE SPACE FOR SCRATCH FILE BLOCK S I Z E ,

; DATE WORD, AND PHACOM.NOW DISK ADDRESS

.WORD TJFL-PHACOM DISPLACEMENT OF USER FILE LIST FROM START . = . + 1 0 ;SAVE SPACE FOR TIME AND NODE WORDS

FATAL=10 AX=1 AC=2 SEEK=0

; S I Z E GIVEN IS 'GUARANTEED ; S I Z E GIVEN IS FILE SIZE ONLY I F I T DID NOT ALREADY EXIST ;JUST SEARCH FOR THE FILE

UFL: ;ENTRY FOR HISTO.DAT FILE

.RAD50 /HIS/

.RAD50 /TO/

.RAD50 /DAT/

.RAD50 /DK/

.BYTE AX+FATAL,0 ;UNIT=0

.WORD 0

.WORD 1000.

.WORD 0

ENTRY FOR DORADO. EL FILE .RAD50 /DOR/ .RAD50 /ADO/ ,RAD50 /EL/ .RAD50 /DT/ .BYTE SEEK,3 ;UNIT=3 .WORD 0,0,0

;END-OF-TABLE .WORD 0 .END PHACOM

spex (spectrometer executive) : programming manual

Documents