RTS8V3.DOC DISCLAIMER This document file was created by scanning the original document and then editing the scanned text. As much as possible, the original text format was restored. Some format changes were made to insure this document would print on current laser printers using 60 lines per page. The original spelling and grammar has been preserved. 1-Sep-1996 RTS/8 User's Manual Order No. AA-0724D-TA February 1979 ABSTRACT This manual describes version 3 of RTS/8, the real-time operating system for the PDP-8 which allows up to 127 tasks to run concurrently. Described are the Executive Requests which permit intertask communication, the Monitor Console Routine which permits the user to control task execution from a terminal, and the message formats for DIGITAL supplied tasks. SUPERSESSION/UPDATE INFORMATION: This manual supersedes DEC-08-ORTMA-C-D. OPERATING SYSTEM AND VERSION: RTS/8, V3 -------------------------------------------------------- | To order additional copies of this document, contact | | the Software Distribution Center, Digital Equipment | | Corporation, Maynard, Massachusetts 01754 | -------------------------------------------------------- digital equipment corporation - maynard, massachusetts First Printing, February 1979 The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may only be used or copied in accordance with the terms of such license. No responsibility is assumed for the use or reliability of software on equipment that is not supplied by DIGITAL or its affiliated companies. Copyright (c) 1979 by Digital Equipment Corporation The postage-prepaid READER'S COMMENTS form on the last page of this document requests the user's critical evaluation to assist us in preparing future documentation. The following are trademarks of Digital Equipment Corporation: DIGITAL DECsystem-10 MASSBUS DEC DECtape OMNIBUS PDP DIBOL OS/8 DECUS EDUSYSTEM PHA UNIBUS FLIP CHIP RSTS COMPUTER LABS FOCAL RSX COMTEX INDAC TYPESET-8 DDT LAB-8 TYPESET-11 DECCOMM DECSYSTEM-20 TMS-11 ASSIST-11 RTS-8 ITPS-10 VAX VMS SBI DECnet IAS PDT DATATRIEVE TRAX 3/79-15 CONTENTS Page PREFACE vii CHAPTER 1 INTRODUCTION 1-1 1.1 RTS/8 DESCRIPTION 1-1 1.2 REAL-TIME OPERATION 1-3 CHAPTER 2 USING TASKS UNDER RTS/8 2-1 2.1 RTS/8 TASKS 2-1 2.2 CONCEPTS OF TASK COMMUNICATION 2-1 2.2.1 Task Synchronization 2-2 2.2.2 Intertask Messages 2-4 2.3 PRIORITY 2-5 2.4 TASK INTERRUPTS AND SCHEDULING 2-6 2.5 CREATING RTS/8 TASKS 2-6 2.6 RUNNING AN RTS/8 SYSTEM 2-8 CHAPTER 3 RTS/8 EXECUTIVE REQUESTS 3-1 3.1 COMMUNICATION WITH THE RTS/8 EXECUTIVE 3-1 3.2 EXECUTIVE REQUESTS 3-4 3.3 EXAMPLE OF EXECUTIVE REQUESTS FOR MESSAGE AND EVENT FLAGS 3-28 3.4 EXECUTIVE REQUEST WAIT STATES 3-30 CHAPTER 4 RTS/8 SYSTEM TASKS 4-1 4.1 RTS/8 SYSTEM TASK SUMMARY 4-1 4.2 CASSETTE HANDLER 4-3 4.2.1 Handler Function 4-3 4.2.2 Utility Function Handler 4-6 4.3 CASSETTE FILE SUPPORT HANDLER 4-8 4.4 CLOCK HANDLER 4-11 4.5 CONSOLE AND NONCONSOLE TERMINAL HANDLERS 4-16 4.5.1 EMT Task 4-21 4.6 EXIT TASK 4-23 4.7 FLOPPY DISK HANDLER 4-24 4.8 LINCTAPE HANDLER 4-29 4.9 LINE PRINTER HANDLER 4-32 4.10 MASS STORAGE HANDLERS 4-34 4.11 OS/8 FILE SUPPORT TASK 4-38 4.12 OS/8 SUPPORT TASK 4-40 4.12.1 OS/8-RTS/8 Communication (OS8COM) 4-41 4.12.2 Other Techniques 4-43 4.13 PDP-8A NULL TASK 4-44 4.14 POWER FAIL TASK 4-45 4.15 UDC/ICS HANDLER 4-46 4.15.1 AI (Analog Input) 4-48 iii CONTENTS (Cont.) Page 4.15.2 AO (Analog Output) 4-49 4.15.3 CS (Change of State) 4-50 4.15.4 DI (Digital Input) 4-51 4.15.5 DO (Digital Output) 4-51 4.15.6 DCT (Disable Contacts) 4-52 4.15.7 DC (Disable Counter) 4-53 4.15.8 ECT (Enable Contacts) 4-54 4.15.9 EC (Enable Counter) 4-55 4.15.10 GC (Generic Code) 4-56 4.15.11 RC (Read Counter) 4-57 4.15.12 UDC/ICS Status/Error Conditions 4-58 CHAPTER 5 MONITOR CONSOLE ROUTINE 5-1 5.1 MCR FUNCTIONS 5-1 5.2 MCR COMMAND SYNTAX 5-1 5.3 MCR COMMANDS 5-2 5.3.1 CANCEL 5-3 5.3.2 DATE 5-3 5.3.3 DEPOSIT 5-4 5.3.4 DISABLE 5-4 5.3.5 ENABLE 5-5 5.3.6 EXAMINE 5-5 5.3.7 EXIT 5-5 5.3.8 NAME 5-5 5.3.9 OPEN 5-6 5.3.10 POST 5-6 5.3.11 REQUEST 5-7 5.3.12 STOP 5-8 5.3.13 SYSTAT 5-8 5.3.14 TIME 5-10 5.3.15 MCR Errors 5-10 CHAPTER 6 NONRESIDENT TASKS 6-1 6.1 NONRESIDENT TASK DESCRIPTION 6-1 6.1.1 Checkpointable Tasks 6-2 6.1.2 Modified Tasks 6-3 6.1.3 Interaction Between Tasks 6-3 6.2 MEMORY PARTITIONS 6-3 6.2.1 FREE Command 6-4 6.2.2 Writing Nonresident Tasks 6-5 CHAPTER 7 PROGRAMMING TECHNIQUES 7-1 7.1 OVERVIEW 7-1 7.2 PERFORMING A RESCHEDULE 7-1 7.2.1 Writing Delicate Code 7-1 7.2.2 Inhibiting Task Switching 7-3 7.3 MULTIPLE EVENT FLAG WAITS 7-5 7.4 EXECUTIVE INTERNAL TASK TABLES 7-6 7.4.1 Task State Table (TSTABL) 7-7 7.4.2 Task Flags Table (TFTABL) 7-8 iv CONTENTS (Cont.) Page 7.4.3 Task Input Message Queue Header Table (MSGTBL) 7-10 7.4.4 Residency Table (RESTBL) 7-10 7.4.5 Partition Table (PARTBL) 7-11 7.4.6 Task Table Structure 7-11 7.4.7 Direct References to System Tables 7-14 7.5 KL8-A SUPPORT 7-15 APPENDIX A RTS/8 DISTRIBUTED SOURCE FILES AND MNEMONICS A-1 APPENDIX B RTS/8 FLOWCHARTS B-1 APPENDIX C GLOSSARY C-1 INDEX Index-1 FIGURES FIGURE 2-1 Message Format and Linking of Messages 2-4 4-1 Cassette Handler Unit Word Format 4-4 4-2 Cassette Handler Call Function Word Format 4-5 4-3 Cassette Handler Status Return Word Format 4-5 4-4 Cassette Handler Utility Call 4-7 4-5 Cassette File Support Handler Unit Word Format 4-10 4-6 Clock Handler Command Word Format 4-14 4-7 Terminal Handler I/O Mode Command and Length Word Format 4-20 4-8 Terminal Handler ASSGN Mode Command Word Format 4-20 4-9 Floppy Disk Handler Unit Word Format 4-27 4-10 Floppy Disk Handler Status Word Format 4-27 4-11 LINCtape Handler Unit Word Format 4-31 4-12 Line Printer Handler I/O Mode Command and Length Word Format 4-33 4-13 Line Printer Handler ASSGN Mode Command Word Format 4-33 4-14 Mass Storage Handlers Unit Word Format 4-36 4-15 Mass Storage Handlers Function Word Format 4-37 4-16 OS8F Call Function Word 4-39 4-17 UDC/ICS Handler Subchannel and Gain Word Format 4-48 4-18 UDC/ICS Handler Subchannel and Value Word Format 4-49 6-1 Nonresident Task Implementation 6-2 7-1 Executive Internal Task Table Structure 7-12 TABLES TABLE 1-1 RTS/8 System Tasks 1-2 2-1 Summary of Event Flag States 2-3 v CONTENTS (Cont.) Page TABLES (Cont.) TABLE 3-1 Summary of Executive Requests 3-2 3-2 Symbolic Names for Specifying WAITBITS 3-5 3-3 Summary of Wait States Incurred by Executive Requests 3-31 4-1 Cassette Handler Status Register Bits 4-4 4-2 Cassette Header Formats 4-9 4-3 Clock Handler Commands 4-12 4-4 Terminal Handler Commands 4-18 4-5 Floppy Status Bit Descriptions 4-26 4-6 OS/8 Floppy Disk Interleave Scheme 4-28 4-7 UDC/ICS Operations 4-47 4-8 Generic Code Values 4-57 4-9 UDC/ICS Messages 4-58 5-1 MCR Command Summary 5-2 7-1 Task Switch Flag (TSWFLG) States 7-5 7-2 Waitbit Descriptions 7-8 vi PREFACE This manual describes the PDP-8 Real-Time Operating System (RTS/8). RTS/8 is a system that you generate using the RTS/8 system generation procedures. The system that you create is individualized to your needs. Knowledge of PDP-8 assembly language programming (MACREL or PAL8) is essential for a complete understanding of this manual. In addition, you should be familiar with real-time systems in general and with the operation and use of the development system for the PDP-8, OS/8. This manual only describes how you use the RTS/8 operating system. See the RTS/8 System Generation Manual for information on how to _________________________________ generate this operating system. Chapters 1 and 2 present introductory information. If you have never used RTS/8 before, these chapters present sufficient information so that you can place the information in the remainder of this manual into a framework. Also, you should carefully read Section 2.5 which overviews the procedure which you should use when creating RTS/8 tasks. Chapter 3 documents RTS/8 Executive Requests. These requests serve two functions: they are the means by which tasks communicate with each other and they are the means by which a task communicates with the RTS/8 Executive. Chapter 4 discusses the message formats that user tasks must use when they request a DIGITAL-supplied handler to perform an I/O operation. Chapter 5 examines the RTS/8 Monitor Console Routine. This routine allows you to communicate interactively with an RTS/8 system. Chapter 6 describes non-resident tasks. A non-resident task is a task which the Executive brings into memory when it is executable. You use non-resident tasks when memory space is at a premium because more than one non-resident task can share the same part of memory. The information in Chapter 7, "Programming Techniques" is for the experienced PDP-8 user. You should read it only after you are familiar with RTS/8. vii The following PDP-8 manuals will be helpful for review and reference: Introduction to Programming (DEC-08-XINPA-A-D) ___________________________ OS/8 Handbook (DEC-S8-OSHBA-A-D) _____________ MACREL/LINK User's Manual (AA-5664B-TA) _________________________ Small Computer Handbook (90P45) _______________________ PDP-8A Minicomputer Handbook (EB0621976) ____________________________ UDC8 Universal Digital Control Subsystem Maintenance Manual ___________________________________________________________ (46H745) ICS8 Industrial Control Subsystem Maintenance Manual (EKOICS8MM) ____________________________________________________ This manual describes how you use an RTS/8 system if it was created using the RTS/8 system generation procedures as this procedure was distributed by DIGITAL. Because it is possible to modify the System Generation procedure, the RTS/8 system that is created may differ from the generalized RTS/8 system that this manual describes. Therefore, you must determine if there are any differences between the system you are using and that which the DIGITAL System Generation procedure can create. viii CHAPTER 1 INTRODUCTION 1.1 RTS/8 DESCRIPTION RTS/8 is a compact Real-Time System for the PDP-8 family of processors (except for the PDP-8S). This system allows you to run up to 127 tasks concurrently, each competing for system resources. As do other real-time systems, RTS/8 responds to both internal and external events. These events permit timely execution and scheduling of tasks. Thus, you may use RTS/8 for monitoring and controlling a number of processes. The RTS/8 Executive controls the execution and interaction of all tasks. This Executive decides which tasks should run (basing its decisions on the priorities of any other runnable task or tasks), services these tasks by means of Executive Requests (which are special processing routines within the Executive), and administers interactive communication. RTS/8 includes system tasks that control most standard I/O devices, including RK8, RK8E, and RL01 moving-head disks, DF32 and RF08 fixed-head disks, TC08 DECtape, RX8 floppy disks, LINCtape, DECcassette, and LS8, LS8E, LP8, and LV8 line printers. (Note that RTS/8 does not support TD8E DECtape.) These tasks, described in Chapter 4, are listed in Table 1-1. The Monitor Console Routine (see Chapter 5), provides you with an interface between the console terminal and the system. The Monitor Console Routine accepts a series of interactive commands which control, inspect, and, to some extent, debug the system. It also allows you to schedule and execute tasks at specified intervals, suspend task execution, and print system status information. RTS/8 also contains a system task that allows a single copy of the OS/8 operating system to run in the background. Thus, you may create a real-time foreground-OS/8 background system. With OS/8 in the background, you may assemble, debug, edit, and link programs. 1-1 INTRODUCTION Table 1-1 RTS/8 System Tasks ---------------------------------------------------------------------- | Task Name | File Name | Task Function | |-----------|-----------|--------------------------------------------| | _ | RTS8.MA | RTS/8 Executive | | CLOCK | CLOCK.MA | Clock Handler Task | | CSA | CSA.MA | Cassette Driver Task | | CSAF | CSAF.MA | Cassette File Support Task | | DTA | DTA.MA | TC08 DECtape Driver Task | | EXIT | EXIT.MA | Exit Task | | LPT | LPT.MA | Line Printer Driver Task | | LTA | LTA.MA | LINCtape Driver Task | | MCR | MCR.MA | Monitor Console Routine | | null task | MCR.MA | Null Task (contained within MCR) | | NULL8A | NULL8A.MA | Null Task for PDP-8A | | OS8 | OS8.MA | OS/8 Support Task | | OS8F | OS8F.MA | OS/8 File Support Task | | PWRF | PWRF.MA | Power Fail Task | | RF08/DF32 | RF08.MA | RF08/DF32 Fixed-Head Driver Task | | RK8 | RK8.MA | RK8 Disk Driver Task | | RK8E | RK8E.MA | RK8E Disk Driver Task | | RL01 | RL01.MA | RL01 Disk Driver Task | | RX8A | RX.MA | Floppy Disk Handler (1st Controller) | | RX8B | RX.MA | Floppy Disk Handler (2nd Controller) | | RX8C | RX.MA | Floppy Disk Handler (3rd Controller) | | RX8D | RX.MA | Floppy Disk Handler (4th Controller) | | SWAP | SWAP.MA | Nonresident Task Swapper | | TTY | TTY.MA | Terminal Driver Task (1st Driver) | | TTYl | TTY.MA | Terminal Driver Task (2nd Driver) | | TTY2 | TTY.MA | Terminal Driver Task (3rd Driver) | | TTY3 | TTY.MA | Terminal Driver Task (4th Driver) | | TTY4 | TTY.MA | Terminal Driver Task (5th Driver) | | UDC/ICS | UDCICS.MA | Universal Digital Controller | | | | Industrial Controller Subsystem | | | | Handler task | |--------------------------------------------------------------------| | | | NOTE | | | | TTYl-4 and RX8A-D are not on the | | distribution Medium. They are files which | | the RTS/8 System Generation Program | | creates. | ---------------------------------------------------------------------- RTS/8 supports both resident and nonresident tasks. (A resident task is a task that resides permanently in memory; a nonresident task is one in which a portion of the task resides on a mass storage device.) The Executive loads a nonresident task into memory only as it becomes executable. By allowing several tasks to share the same area of memory, RTS/8 minimizes the amount of memory that it needs to execute user tasks. 1-2 INTRODUCTION 1.2 REAL-TIME OPERATION RTS/8 is a real-time multiprogramming system; that is, it is a software framework that allows more than one task to share available resources (such as memory, CPU time, and peripheral devices) and to respond to events in real-time. A real-time system is a type of multiprogramming system that provides immediate or near immediate response to external events. Real-time multiprogramming operations require the precisely organized interaction of the following major elements: o Executive--the RTS/8 Executive is the kernel of the RTS/8 system; it is the software that directs task execution. o Tasks--a task is a sequence of instructions that directs the computer in manipulating data to achieve some goal. Tasks are either user-written or supplied by DIGITAL. o Memory--memory is the hardware storage medium in which tasks actually reside when they execute. Multiprogramming allows the execution of many tasks simultaneously. If a task is waiting for the completion of an I/O operation (or some other condition is blocking it), and thus cannot use the central processor, RTS/8 switches control to another task so that you may use available CPU time. This increases system efficiency; that is, you get more work done because no program puts the CPU on hold while it waits for an event or information. 1-3 CHAPTER 2 USING TASKS UNDER RTS/8 2.1 RTS/8 TASKS The RTS/8 Executive is the controlling program in the RTS/8 system. One of its major functions is to decide which task should run. It bases its decision on the priorities of the runnable (or active) tasks (those tasks not waiting for completion of any I/O or other events). It also services tasks by means of Executive Requests. (See Chapter 3 for a discussion of Executive Requests.) Each task in an RTS/8 system is given a unique task priority number when a user generates the system. Up to 127 (177 octal) tasks, each with its own task priority, can run at one time. A task number, once assigned, cannot change during the execution of the RTS/8 system because RTS/8 uses a fixed priority system. A task priority number serves the following purposes: o The RTS/8 Executive uses the number as an index to various system tables which contain information about each task. o Other tasks use this number to reference a particular task when performing certain Executive Requests (such as sending a message). o The task number determines the task's priority--the lower the number, the higher the priority of the task. The executive uses five internal tables to maintain information about the tasks in the system. Chapter 7 discusses these tables. 2.2 CONCEPTS OF TASK COMMUNICATION RTS/8 is event driven; that is, the highest-priority runnable task executes continuously until: o It completes its function, or o Some event or condition in the system suspends it. Another change or condition can reactivate the task. (Task scheduling is discussed in Section 2.4.) 2-1 USING TASKS UNDER RTS/8 -------------------- NOTE -------------------- | | | A task is self-starting if you include | | the appropriate instruction within the | | task (see Section 2.5). A task may also | | start another task, or you may start it | | at the terminal console by using the | | Monitor Console Routine. | ---------------------------------------------- RTS/8 performs two main types of task communication: 1. Task synchronization through the use of event flags 2. Intertask messages 2.2.1 Task Synchronization Whenever two processes execute independently, one process may need to wait until the other completes executing. For example, consider the PDP-8 terminal interface. The PDP-8, when it is ready to generate a character, alerts the terminal by issuing a Load Teleprinter Sequence (TLS) instruction. The PDP-8 must now wait in a loop if it wishes to do further I/O immediately. For example, TSF /SKIP ON TELEPRINTER FLAG JMP.-1 . . . The processor cannot transmit the next character until the terminal raises the ready flag to signal that it has printed the first character. When the terminal raises this flag, the processor exits from the wait loop and proceeds to load the next character. Similarly, RTS/8 provides event flags as signalling mechanisms. (An event flag is simply a location which you choose that contains the status of an event.) These flags synchronize tasks with each other. The events are either: 1. Physical processes such as a clock ticking or a valve closing, or 2. Conceptual occurrences such as a certain string of characters which you type, or the scheduling of a task for execution. Like device flags, an event flag can denote either a "busy" or a "completed" state (designated as PENDING and FINISHED, respectively). Thus, a task can direct another task to perform an action. At the time of the request, it sets the event flag to the PENDING value. When the second task completes the action, it issues the POST Executive Request. This request sets the event flag to the FINISHED value, a process known as "posting the event flag." 2-2 USING TASKS UNDER RTS/8 As a simple example, if the first task is waiting for the event flag with the following instructions: TAD event flag /LOAD EVENT FLAG IN AC SZA CLA /IF EVENT FINISHED, SKIP JMP .-2 /KEEP TRYING . . . then the posting of the event flag causes the first task to exit from its loop only when the second task completes its processing. Since this loop ties up the PDP-8 processor, event flags have an additional state, WAITING. In the above example, the addition of the WAITING state now allows the first task to tell the RTS/8 Executive that it will wait until the event flag signifies that the second task completes the event. The WAIT code is as follows: CAL WAITE event flag (CAL is a system mnemonic meaning JMS 20 and WAITE is the mnemonic for the RTS/8 Executive Request that waits for an event flag.) The WAIT returns execution control to the task issuing the WAITE if the event flag is zero (or FINISHED). If the flag is PENDING (or greater than zero), the Executive changes it to WAITING and the task issuing the WAITE becomes non-runnable (that is, its WAITBITS word is now non- zero). If the issuing task sends a message to a second task, the Executive automatically makes the event flag PENDING when the message is sent. If the issuing task is using the event flag to synchronize task actions, this task must change the flag to PENDING before issuing the WAIT. (It may set the flag with an ISZ command.) Table 2-1 summarizes RTS/8 event flag states. Table 2-1 Summary of Event Flag States ----------------------------------------------- | Event Flag State | Value | |-------------------|-------------------------| | FINISHED | 0 | | | | | PENDING | > 0 | | | | | WAITING | < 0 (4000 + Task No.) | ----------------------------------------------- 2-3 USING TASKS UNDER RTS/8 When an RTS/8 Executive Request posts the event flag, the task WAITING for it is automatically taken out of Event Flag Wait. (If no other blocking condition exists, the waiting task is again runnable. It resumes execution when higher priority tasks cannot run.) 2.2.2 Intertask Messages Just as event flags under RTS/8 are similar to hardware device flags, messages are similar to hardware I/O instructions (for example, TLS). That is, messages start a task (providing that the task is WAITING for a message) and, at the same time, they pass information to the task. All RTS/8 messages consist of a 3-word message header immediately followed by the information to be exchanged between the tasks. (Only the RTS/8 system uses the message header.) The first word of the message header is the event flag for the message. When a task sends a message, the RTS/8 Executive sets the event flag to the PENDING state. This signifies that a task has sent the message but the task receiving the messages has not finished processing the event associated with the flag. The receiving task must post the event flag when it finishes performing the action signalled by the message. This posting serves two purposes. 1. It informs the task that sent the message (the "sender") that the receiver performed the action. 2. It allows the task to send the message again (see Item 2, below). If a task is waiting to receive more than one message, RTS/8 uses the second and third words of the message header to link these messages together (see Figure 2-1). The second word is a CDF (Change Data Field) instruction to the field of the next message. If the second word is 0, then this is the last message. The third word of the message is a pointer to the next message. If the receiving task is not actively waiting for a message, RTS/8 places the message on the receiving task's "input message queue." The Executive queues all messages that a task receives in decreasing priority order. For example, the Executive queues a message from a priority 3 task ahead of any message sent by another task except the tasks with priorities 1 and 2. Also, RTS/8 queues messages from the same task in the order in which that task issues them. Sending a message does not physically move the message information to the receiving task; instead a SEND operation establishes a pointer to the location of the first data word of the message. The implications of RTS/8 not moving a message to the receiving task's work area are: 2-4 USING TASKS UNDER RTS/8 RTS/8 EXECUTIVE MESSAGE MESSAGE MESSAGE MSGTBL 1 2 3 --------- --------- --------- --------- | CDF | --->| Event | --->| Event | --->| Event | <- |-------| | | FLag | | | Flag | | | Flag | | | PTR |---- |-------| | |-------| | |-------| | Message --------- | CDF | | | CDF | | | 0 | | Header |-------| | |-------| | |-------| | | PTR |---- | PTR |---- | | <- |-------| |-------| |-------| | | | | | | <- | | | | | | | | | | | | | | Message | | | | | | | Content --------- | | | | | | | | | <- | | --------- --------- Figure 2-1 Message Format and Linking of Messages 1. You should not have the sender modify data in a message while the event flag for the message is PENDING. 2. A task cannot send the same message a second time before its event flag is FINISHED the first time. (Note, however, that the task can send other messages while a message is pending.) RTS/8 enforces this rule by checking the message event flag on a SEND Executive Request; it puts the sender into an Event Flag Wait State if the message is still PENDING. 3. It is legal for the receiving task to store information in the body of the message. In this way, a receiver can "answer" without the complications of sending a return message. For example, when a task sends a message to the disk driver task requesting I/O, the driver places the operation's status in a specific word in the message. Thus, this word indicates whether an error occurs. 2.3 PRIORITY The priority of a task is established when a user generates the system. This number is in the range 1 to 127 (decimal), where a lower number indicates a higher priority. The highest-priority task that has access to all the resources it needs controls the central processor. When that task becomes blocked (to wait for an I/O transfer to complete, for example), the Executive looks for another task to use the processor. The chosen task is the one that has the highest priority, has access to all the resources it needs, and is not waiting for any event to occur. 2-5 USING TASKS UNDER RTS/8 In an RTS/8 installation that mixes real-time applications with less urgent work, the real-time tasks usually have a high priority. This arrangement ensures that the Executive gives CPU time to the real-time tasks ahead of other, less urgent tasks. 2.4 TASK INTERRUPTS AND SCHEDULING A task, once it is running, releases the CPU only if an interrupt occurs or if the task itself issues an Executive Request that places it into a wait state. An interrupt is a break in the normal operation of the task caused by a signal from outside the processor. When the processor receives an interrupt, it looks for the appropriate interrupt service routine. The SKPINS Executive Request is the means by which you link these interrupt routines together into a skip chain. Note that this skip chain is the path which the Executive takes when looking for the interrupt service routine and is independent of the tasks in the system. When an interrupt occurs, the Executive follows the skip chain until it finds the appropriate interrupt service routine. After the interrupt routine services the request, control returns to either the interrupted task or the RTS/8 scheduler. If control passes to the scheduler, RTS/8 runs the highest priority task that is not waiting for an event or message. RTS/8 has a table of reserved words in its Executive. (Each word is called a WAITBITS word.) A task is runnable only when this word equals zero. If any bit is nonzero, then the task is waiting for some event to occur. The kinds of events are listed in Table 3-2. Thus, when the WAITBITS equals zero, the Executive can run a task because that task is not waiting for an event or action. This table of reserved words is ordered by task priority. When the RTS/8 scheduler examines this table, it selects the highest priority task that has a zero WAITBITS entry. Therefore, the only time that a higher-priority task can run after control passes to a lower priority task is when: 1. A lower priority task finishes processing the event which is the cause of a higher-priority event being in a wait state, or 2. An interrupt service routine removes the condition blocking the higher-priority task. 2.5 CREATING RTS/8 TASKS You create RTS/8 tasks in the same manner as you would create any other program on the PDP-8. The only influences RTS/8 has on these programs are: 1. You must include the MACREL .TASK macro in the task (this is explained below). 2-6 USING TASKS UNDER RTS/8 2. If the task is nonresident (see Chapter 6), 3. If there is to be intertask communication (see Chapter 3), or 4. If a task uses a DIGITAL-supplied task (see Chapter 4). All RTS/8 tasks must include the MACREL .TASK macro. This macro is placed in the parameter file during system generation. Its source is within the SCRIPT.MA source program distributed with RTS/8. The format for calling this macro is: .TASK TASK-NUMBER,TASK-NAME,STARTING-ADDRESS,INITIAL-WAIT,VERSION where: TASK-NUMBER is the RTS/8 task number which you must supply; DIGITAL recommends that you use the symbolic name that was or will be used when the system is generated. TASK-NAME is the symbolic name used when the RTS/8 system was generated. You may omit this parameter. If you omit it, the macro computes this string from TASK-NUMBER. STARTING-ADDRESS is optional. If you omit this symbolic address, it defaults to the START label in the task. You would provide this value in symbolic form so that MACREL may know the proper field (as MACREL labels have a field attribute). INITIAL-WAIT is an optional value. If you do not include this parameter, the task is runnable when you start the RTS/8 system. You may provide a symbolic or absolute WAITBITS value (see Section 3.2.1). (In previous versions of RTS/8, it was obligatory for you to include this value.) VERSION is an optional value. If you include this value, it is the initial value of the MQ. If you omit this value, it defaults to the value of the label VERS. RTS/8 requires Version 2 of MACREL. Examples: .TASK CLOCK This declaration uses all of the defaults. .TASK TEST,,STEST,RUNWT 2-7 USING TASKS UNDER RTS/8 This declaration is for task TEST which starts at symbolic location STEST and is in RUNWT when the RTS/8 system begins running. If a task wishes to communicate with another task, it should use one of the RTS/8 Executive Requests. Chapter 3 describes these requests and Table 3-1 summarizes them. If a task you write uses one of the DIGITAL-supplied tasks, it must send a message to that task. Chapter 4 presents the formats that your tasks must use when they send messages to these tasks. (Chapter 3 describes the way in which you send these messages.) Because you normally create an RTS/8 system that uses DIGITAL tasks and sends messages using Executive Requests, you should create the tasks before you generate the RTS/8 system. DIGITAL recommends that you write and add tasks to an RTS/8 system one at a time. That is, after you create one task, you should use the RTS/8 System Generation to create a minimum system that will support the task. In this way, you can effectively monitor the interaction between tasks as you are building the RTS/8 system. Experience has shown that this is the best method of locating bugs in real-time systems. 2.6 RUNNING AN RTS/8 SYSTEM In response to the period that the OS/8 monitor prints, type R Sname where: S is the default character supplied by the RTS/8 System Generation program. name is the 1 to 5 character name supplied by the person building the system. After you type this command, the RTS/8 system is running. For more information, see the RTS/8 System Generation Manual. ______________________________ 2-8 CHAPTER 3 RTS/8 EXECUTIVE REQUESTS 3.1 COMMUNICATION WITH THE RTS/8 EXECUTIVE RTS/8 tasks communicate with the RTS/8 Executive through Executive Requests. When an RTS/8 system is running, it normally uses locations 20-27 in a field as the communication region across field boundaries. (However, if a field contains OS/8, the Executive does not use these locations after OS/8 is running.) You may call the Executive in any field via a JMS 20 (or CAL) instruction. -------------------- NOTE -------------------- | | | When a user generates an RTS/8 system, | | it included the equate | | | | CAL = JMS 20 | | | | in its symbol table. Consequently, it | | is not necessary for you to include this | | equate in any task that you may write. | ---------------------------------------------- The data field (DF) does not have to be any specific value when a task issues a CAL because the code in location 20 o Sets the DF to the instruction field (IF), o Sets the IF to 0, and o Jumps to the RTS/8 Executive. Table 3-1 gives a summary of Executive Requests. Although this chapter presents all Executive Requests, full presentations of the RESCHED and FREE Executive Requests appear in Chapter 7. The RTS/8 Executive does not honor requests to switch tasks that come from an interrupt if the interrupted task's program counter (PC) is less than 100 (octal). This prevents a second Executive Request from destroying the RTS/8 Executive's entry point (location 20 in each field). Therefore, no task may have instructions that the central processor will execute below location 100 in any field (except as noted in Chapter 7). 3-1 RTS/8 EXECUTIVE REQUESTS -------------------- NOTE -------------------- | | | You should not write executable code in | | ZSECTs that the linker can place below | | location 100 (octal) in a field. This | | is usually a fatal error. Also, you | | must not write executable code which has | | an ASECT that may be linked below 1000 | | (octal) in field 0. These locations | | constitute the RTS/8 Executive. | | | | If you must include executable | | instructions in a ZSECT, you must insure | | that this code executes above location | | 77 (octal) in every field. Note that in | | the field containing the RTS/8 | | Executive, approximately one half of | | page 0 is available for user code. | | Also, if your RTS/8 system has OS/8, you | | have five auto-increment registers | | available. If OS/8 is not in the RTS/8 | | system, you have six available. | ---------------------------------------------- You use many of the Executive Requests for intertask communication. This, however, does not imply that tasks must communicate with each other. A task can execute independently of all other tasks. Table 3-1 Summary of Executive Requests ----------------------------------------------------- | | Symbolic | | | Code | Name | Description | |--------|-----------|------------------------------| | 0 | SEND | Send a message to a task | | | | | | 1 | RECEIVE | Look for and/or receive a | | | | message from a task | | | | | | 2 | WAITE | Wait for any event flag for | | | | a specific task to be | | | | posted | | | | | | 3 | RUN | Run a task | | | | | | 4 | SUSPND | Suspend execution of a task | | | | | | 5 | POST | Post an event flag | | | | | | 6 | SKPINS | Insert code into interrupt | | | | skip chain | ----------------------------------------------------- (continued on next page) 3-2 RTS/8 EXECUTIVE REQUESTS Table 3-1 (Cont.) Summary of Executive Requests ----------------------------------------------------- | | Symbolic | | | Code | Name | Description | |--------|-----------|------------------------------| | 7 | DERAIL | Derail (that is, force a | | | | task's execution to a new | | | | address) | | | | | | 8 | BLKARG | Block a task from running | | | | for a specified reason | | | | | | 9 | SENDW | Send a message and wait for | | | | it to be received | | | | | | 10 | UNBARG | Signal that a reason that a | | | | task is blocked from | | | | running no longer exists. | | | | (A task may be blocked for | | | | more than one reason) | | | | | | 11 | RESCHD | Force the RTS/8 Scheduler | | | | to run | | | | | | 12 | WAITX | Wait for a particular event | | | | flag to be posted | | | | | | 4000 | FREE | Allow another task to take | | | | control of a partition | ----------------------------------------------------- WAITM (which is discussed in Chapter 7) is a special RTS/8 mnemonic you use for waiting for multiple event flags. 3-3 RTS/8 EXECUTIVE REQUESTS 3.2 EXECUTIVE REQUESTS -------------- -------------- | | | | | BLKARG | | BLKARG | | -------------------------------------------- | | | | Use the BLKARG Executive Request to prevent a task from running. | | | | Format: | | TAD TSKNUM | | CAL | | BLKARG | | WAITBITS | | | | where: | | TSKNUM is the number of the task to be blocked. | | CAL is an RTS/8 mnemonic for JMS 20. | | BLKARG is an Executive Request mnemonic. | | WAITBITS is one or more of the values defined in Table 3-2. | | | ---------------------------------------------------------------------- You prevent a task from running (that is, you block it) by issuing a BLKARG Executive Request. This Executive Request sets one or more of the bits in a special, reserved location in a task's Task Table (see Section 7.3) called the Task Flags Word. The Executive checks this location whenever one task calls another or whenever the task is in a runnable position. Only when this word equals zero is a task runnable. TSKNUM is a location or literal that contains the number of the task to be blocked. If TSKNUM contains a zero, the issuing task blocks itself. ------------------- NOTE ------------------- | | | The TSKNUM=0 form of this Executive | | Request is the only legal way for a task | | to block itself. If TSKNUM is equal to | | the issuing task's number, the action of | | this Executive Request is undefined and | | unpredictable results will occur. | -------------------------------------------- The WAITBITS specify one or more bits to be set in a task's Task Flags Word. (They are called WAITBITS because the bits in the task's Task Flags Word indicate the reason or reasons that a task is not runnable.) Note that a task is runnable only when this word equals zero. Symbolic names for specifying the conditions for blocking (and unblocking) a task in the WAITBITS word are given in Table 3-2. The symbolic names listed in the table are equates established when the system was generated. 3-4 RTS/8 EXECUTIVE REQUESTS Table 3-2 Symbolic Names for Specifying WAITBITS ---------------------------------------------------------------------- | Symbolic | | | | Name | Value | Meaning | |-----------|---------|----------------------------------------------| | NONRWT | 4000 | Nonresident Wait--this task cannot run | | | | because it is not in memory. | | | | | | EFWT | 2000 | Event Flag Wait--this task is waiting for | | | | an event flag (which contains a WAITING | | | | value corresponding to this task) to be | | | | posted. | | | | | | RUNWT | 1000 | Run Wait--This task is waiting for a RUN ER | | | | to be executed with its number in the AC, | | | | or for the operator to type a REQUEST task | | | | command to the Monitor Console Routine (see | | | | Chapter 5). | | | | | | SWPWT | 0400 | Swap Wait--This task cannot run because it | | | | is in the process of being brought into | | | | memory. | | | | | | EORMWT | 0200 | Event or Message Wait--This task is waiting | | | | for an event flag to be posted or a message | | | | to arrive, whichever happens first. | | | | | | USERWT | 0100 | User Wait--This bit is reserved for use by | | | | user-written tasks. RTS/8 does not use | | | | this bit. | | | | | | ENABWT | 0040 | Enable Wait--This task is waiting to be | | | | enabled. Used only by the Monitor Console | | | | Routine. (See Chapter 5 for an explanation | | | | of the ENABLE and DISABLE commands.) | | | | | | MSGWT | 0020 | Message Wait--This task is waiting to be | | | | sent a message. | | | | | | | 0010 | Reserved for future expansion. | | | | | | | 0004 | Reserved for future expansion. | | | | | | | 0002 | Reserved for future expansion. | | | | | | DNEWT | 0001 | Task does not exist. A user task should | | | | never set or clear this bit. | ---------------------------------------------------------------------- 3-5 RTS/8 EXECUTIVE REQUESTS Examples: You place task 14 into User Wait by executing the following code. TAD (14) CAL BLKARG USERWT Task PRINT is placed into Run Wait by executing the following code. TAD (PRINT) CAL BLKARG RUNWT 3-6 RTS/8 EXECUTIVE REQUESTS -------------- -------------- | | | | | DERAIL | | DERAIL | | -------------------------------------------- | | | | Use the DERAIL Executive Request to modify the execution of a task | | by transferring control to a special subroutine when that task | | becomes runnable. | | | | Format: | | TAD TSKNUM | | CAL | | DERAIL | | ADDR | | | | where: | | TSKNUM is the number of the task to be derailed. | | CAL is an RTS/8 mnemonic for JMS 20. | | DERAIL is an Executive Request mnemonic. | | ADDR is the actual or symbolic starting location of the | | subroutine. | | | ---------------------------------------------------------------------- You use the DERAIL Executive Request to force a task's execution to a new address. This address is normally the address of a special subroutine of the task. Note that this Executive Request does not set or clear any of the WAITBITS. The DERAIL Executive Request simulates a "JMS ADDR" for the task whose number is in location TSKNUM (which is the derailed task). Note that RTS/8 assumes that ADDR is in the same field as the derailed task. The Executive stores the derailed task's program counter (from its Task State Table entry) in location ADDR, and also sets the program counter entry in its Task State entry to ADDR + 1. Two important points concerning the operation of the DERAIL Executive Request are: 1. The DERAIL Executive Request does not save the derailed task's accumulator, link, and data field settings; therefore, the derail subroutine must save and restore these values. In this sense, a derail subroutine is very much like an interrupt at the task level. 2. DERAIL does not alter the contents of the derailed task's Task Flags word. If the derailed task is not runnable, RTS/8 does not execute the derail subroutine until the task becomes runnable. Generally, a high priority task uses the DERAIL Executive Request to signal lower priority tasks that an emergency condition occurred. As an example, it is sometimes necessary to abort all processes in a process-control environment if the room temperature exceeds some critical value. You may program a task that checks for this 3-7 RTS/8 EXECUTIVE REQUESTS temperature every ten seconds. However, it is inefficient to include shutdown code in this "watchdog task" for all machinery that the processor controls. A better solution is to provide a location to which each equipment-controlling task can be derailed in order to shut down its own piece of equipment. Example: An example of a derail subroutine is as follows: DENTRY, 0 /DERAIL ROUTINE ENTRY POINT DCA SAVAC /SAVE AC RAR DCA SAVLNK /SAVE LINK RDF TAD (CDF) DCA SAVDF /SAVE DATA FIELD CDF .FLD . /HANDLE EMERGENCY CONDITION . . /BRANCH TO "RESUME" IF YOU WANT . / TO RESUME WHERE YOU LEFT OFF . /BRANCH TO "NOGO" IF NOT RESUME, TAD SAVLNK /RESTORE LINK CLL RAL TAD SAVAC SAVDF, HLT /RESTORE DF JMP I DENTRY /RESUME (SAME FIELD) NOGO, CLA CLL CDF .FLD JMP RESTRT /RESTART TASK SAVAC, 0 SAVLNK, 0 Dangers of DERAIL A task can get into serious trouble if the Executive derails it while it is already in a derail routine. If this situation occurs, the original processor state is lost. There is no simple solution to this problem. You cannot simply turn off the interrupts in the derail routine; a second derail may occur before the Executive executes the first derail routine. Consequently, you must ensure that a task can only be derailed by one other task in the system. Restrictions Using DERAIL If a task is not runnable, derailing it does not make it runnable. For example, if a task is in Event Flag Wait, it will remain in this state until the event occurs. When the task finally posts the event flag, the receiving task wakes up and begins to run in its derail routine rather than in the mainline routine. Thus, derailing a task so that it can perform some important job immediately may not always work because a task may be in a wait state and not be able to run for 3-8 RTS/8 EXECUTIVE REQUESTS some time. For example, if the task were in Message Wait at the time of the DERAIL Executive Request, the derail routine would not run until a message came in for that task. Furthermore, if some event causes the routine sending the message to shut off, then the receiving task will never run. A partial solution to this restriction is to code the task to be derailed so that it always waits for events by using the WAITX Executive Request instead of WAITE. If you subsequently derail this task, it is first taken out of MSGWT or EORMWT and then derailed. An example of the code for this situation is as follows: TAD TSKNUM CAL DERAIL DENTRY /DERAIL ADDRESS TAD TSKNUM CAL UNBARG /UNBLOCK THE TASK FROM MSGWT ! EORMWT / MESSAGE-RELATED WAITS . . . CAL WAITX EFLAG . . This works because both the RECEIVE and the WAITX Executive Requests move the program counter back to the location of the CAL before going into a wait state. Thus, no harm can occur if the Executive takes the task out of that wait state for an incorrect reason. When the task resumes running at that point, it re-executes the CAL (RECEIVE or WAITX) and goes back into the wait state as necessary. This method does not work if the task was in Event Flag Wait due to a WAITE Executive Request because the task would resume running as if the task posted the event flag when, in fact, it had not. A way to circumvent this problem (other than WAITX) is for the task to do WAITM instead of a WAITE, and then poll the event flag upon waking up. (WAITM is discussed in Chapter 7.) 3-9 RTS/8 EXECUTIVE REQUESTS -------------- -------------- | | | | | FREE | | FREE | | -------------------------------------------- | | | | Use the FREE Executive Request to indicate that the Executive can | | swap a nonresident task out of a partition if another nonresident | | task wishes to use it. | | | | Format: | | CAL | | COMMND+FREE | | | | where: | | CAL is an RTS/8 mnemonic. | | COMMND is an Executive Request that can put a task into a | | wait state. | | FREE is an Executive Request mnemonic. | | | ---------------------------------------------------------------------- When a nonresident task is in a wait state, you should allow another nonresident request to use its memory partition if it needs to. Thus, the FREE Request tells the Executive that it can swap the task currently in a portion of memory to the swapping device if another task is ready to execute in the same partition. If no other nonresident task is ready to run, the Executive does not swap out the task currently in memory. If the Executive Request to which you append the FREE Request does not put the nonresident task into a wait state, the Executive ignores the FREE request. Section 6.2.1 discusses the FREE request. 3-10 RTS/8 EXECUTIVE REQUESTS -------------- -------------- | | | | | POST | | POST | | -------------------------------------------- | | | | Use the POST Executive Request to set an event flag to the | | FINISHED (zero) state. | | | | Format: | | TAD EFPTR /POINTER TO EVENT FLAG | | CAL | | POST | | CDF EFFLD /FIELD OF EVENT FLAG | | | | where: | | EFPTR is the location of the event flag. | | CAL is an RTS/8 mnemonic for JMS 20. | | POST is an Executive Request mnemonic. | | EFFLD is the field of the event flag. | | | ---------------------------------------------------------------------- A task signals that it has received a message or completed an event by using a POST Executive Request. The POST Executive Request sets the event flag pointed to by the accumulator in the field of the CDF to the FINISHED (or zero) state. If its previous state was WAITING, the POST Executive Request clears the event flag wait bit of the waiting task's WAITBIT. (This is the EORMWT bit.) It also sets the PENDING flag to zero. This Executive Request never places the calling task into a wait state. If the task waiting for the event flag has a higher priority than the calling task, the Executive transfers control to the higher priority task. Note that the lower priority task remains runnable; that is, none of its WAITBITS are set. However, this lower-priority task runs only when no other higher priority task is runnable. See Section 3.3 for an example of the POST Executive Request. 3-11 RTS/8 EXECUTIVE REQUESTS -------------- -------------- | | | | | RECEIV | | RECEIV | | -------------------------------------------- | | | | Use a RECEIV Executive Request to specify that a task is to await | | a message before proceeding. | | | | Format: | | TAD TSKNUM | | CAL | | RECEIV | | MADDR, 0 | | | | where: | | TSKNUM is the task from which the receiving task will | | receive a message; or, if TSKNUM equals zero, the | | task can receive a message from any task. | | CAL is an RTS/8 mnemonic for JMS 20. | | RECEIV is an Executive Request mnemonic. | | MADDR is the address of the message. | | | ---------------------------------------------------------------------- The RECEIV Executive Request is the means by which a task tells the Executive that it wishes to receive a message. The Executive places both the address of the message in MADDR and a CDF to the message's field in the accumulator. If the accumulator is zero when a task issues the RECEIV Executive Request, the RTS/8 Executive examines the calling task's (that is, the task executing the RECEIV) input message queue. If there are messages in the calling task's input message queue, the Executive removes the first (i.e., the highest priority) message from the queue and places the address of its first data word in MADDR. It also stores a CDF to the field of the message in the accumulator. If the accumulator is nonzero when a task issues the RECEIV Executive Request, the Executive searches the calling task's input message queue. It looks for a message whose sender's task number is the same as the number in the accumulator. If it finds such a message, it removes it from the queue as specified above; if it does not find a message, it places the issuing task in Message Wait. ------------------- NOTE ------------------- | | | When a task is in Message Wait after | | executing a RECEIV Executive Request, | | its program counter, as stored in the | | Task State Table (see Section 7.3), | | points back to the location containing | | the CAL. Thus, when a message comes in, | | the task re-executes the RECEIV | | Executive Request and accepts the | | | 3-12 RTS/8 EXECUTIVE REQUESTS | | | message. This mechanism is normally | | transparent. One implication is that no | | harm is done by taking a task out of | | Message Wait because, once the task | | starts up again, it will re-execute the | | RECEIV Executive Request and go back | | into Message Wait. | -------------------------------------------- Normally, if there are no messages in the input message queue when a task performs a RECEIV, the task is put into Message Wait. However, a 1 in bit O of the accumulator (i.e., the accumulator is negative) when a task issues a RECEIV indicates that the task is not willing to wait. With no messages in the input message queue (or none sent by the task whose number is in the accumulator), the task will continue to run (at location CAL + 3) with the accumulator equal to zero. Thus, a zero accumulator is the means by which the RTS/8 Executive informs a task that there are no messages (of the desired type) PENDING. A major restriction in using this Executive Request is that a task cannot send the same message twice. If a task attempts to send the same message a second time, the Executive prevents this action from occurring by placing the task in Event Flag Wait until the first instance of the message has been processed and posted. The second instance of the message is then sent and the Executive removes the offending task from Event Flag Wait. However, if the same message (that is, the same event flag) is sent by two separate tasks, RTS/8 may stop executing as this is probably a user error. If this occurs, you must reload the RTS/8 system. See Section 3.3 for an example of the RECEIV command. 3-13 RTS/8 EXECUTIVE REQUESTS -------------- -------------- | | | | | RESCHD | | RESCHD | | -------------------------------------------- | | | | Use the RESCHD Executive Request to force the RTS/8 scheduler to | | run. | | | | Format: | | CAL | | RESCHD | | | | where: | | CAL is an RTS/8 mnemonic for JMS 20. | | RESCHD is an Executive Request mnemonic. | | | ---------------------------------------------------------------------- You use the RESCHD Executive Request in conjunction with writing code that more than one task uses. After a task finishes manipulating the shared code, you must check certain conditions and go directly to the RTS/8 scheduler. Checking these conditions is the function of the RESCHD Executive Request. Section 7.1.2 discusses the RESCHD request. 3-14 RTS/8 EXECUTIVE REQUESTS -------------- -------------- | | | | | RUN | | RUN | | -------------------------------------------- | | | | Use the RUN Executive Request to run a task. | | | | Format: | | TAD TSRNUM | | CAL | | RUN | | | | where: | | TSKNUM is the number of the task to be run. | | CAL is an RTS/8 mnemonic for JMS 20. | | RUN is an Executive Request mnemonic. | | | ---------------------------------------------------------------------- The RUN Executive Request is equivalent to the following instructions: TAD TSKNUM CAL UNBARG RUNWT This request exists because the Executive performs this function often enough to justify a shorthand version. See the UNBARG discussion for more information. An example of the RUN Executive Request is included with the SUSPND discussion. 3-15 RTS/8 EXECUTIVE REQUESTS -------------- -------------- | | | | | SEND | | SEND | | -------------------------------------------- | | | | Use the SEND Executive Request to send a message to a task. | | | | Format: | | CAL | | SEND | | TSKNUM | | MESSAG | | | | where: | | CAL is an RTS/8 mnemonic for JMS 20. | | SEND is an Executive Request mnemonic. | | TSKNUM is the number of the task to which a message is | | being sent. | | MESSAG is the location of the message being sent. | | | ---------------------------------------------------------------------- The SEND Executive Request sends the location of the message labelled MESSAG in the field of the CAL instruction to the task whose number is TSKNUM. If the receiving task has a higher priority than the sender and is waiting for a message, RTS/8 transfers control to the receiver. If this occurs, the sending task is still runnable; however, it does not regain control of the processor until all other higher priority tasks are in a wait state. A SEND Executive Request places the event flag into a PENDING state. If the event flag in location MESSAG is already PENDING (that is, the event flag is nonzero and the message is still busy from a previous SEND), the sender is put into Event Flag Wait on location MESSAG, and the Executive only performs the SEND when the event flag becomes FINISHED (zero). You should ensure that only one task sends a message because the Executive remembers only the last request to send a "busy" message; the first task could then remain permanently dormant in Event Wait because the Executive took the wrong task out of Event Wait. Only after a task acknowledges receipt can the task (or another task) send the same message. See Section 3.3 for an example of the SEND command. 3-16 RTS/8 EXECUTIVE REQUESTS -------------- -------------- | | | | | SENDW | | SENDW | | -------------------------------------------- | | | | Use the SENDW Executive Request to send a message and to wait for | | an acknowledging response. | | | | Format: | | CAL | | SENDW | | TSKNUM | | MESSAG | | | | where: | | CAL is an RTS/8 mnemonic for JMS 20. | | SENDW is an Executive Request mnemonic. | | TSKNUM is the number of the task that will receive the | | message. | | MESSAG is the address of the first word of the message. | | | ---------------------------------------------------------------------- The SENDW Executive Request is equivalent to a SEND Executive Request followed immediatly by a WAITE Executive Request; that is, the SENDW Executive Request is equivalent to the following sequence: CAL SEND /SEND THE MESSAGE TSKNUM MESSAG CAL WAITE /WAIT FOR RECEIVER TO ACKNOWLEDGE MESSAG See the SEND and WAITE discussions for further information. 3-17 RTS/8 EXECUTIVE REQUESTS -------------- -------------- | | | | | SKPINS | | SKPINS | | -------------------------------------------- | | | | Use the SKPINS Executive Request to insert an interrupt processing | | routine into the interrupt skip chain. | | | | Format: | | CAL | | SKPINS | | MODULE | | | | where: | | CAL is an RTS/8 mnemonic for JMS 20. | | SKPINS is an Executive Request mnemonic. | | MODULE is the address (in the current field) of an | | interrupt processing routine. | | | ---------------------------------------------------------------------- The RTS/8 Executive is able to receive and dismiss hardware interrupts and to perform interrupt-initiated task switching. However, it does not provide room for an interrupt skip chain. Instead, the skip chain is literally a chain which the Executive dynamically builds at system start-up time using SKPINS Executive Requests which you include in tasks. Whenever a task executes a SKPINS Executive Request, the Executive inserts the interrupt routine at the end of the interrupt skip chain. (This is usually done by tasks at system start-up time only.) The last interrupt routine which the Executive includes in the skip chain points to the RTS/8 interrupt dismiss routine as its "next module." In this way, you control the order in which RTS/8 links the skip chain. This means that the Executive encounters most-used interrupts first. For example, if a task is not runnable at system start- up, the Executive places its interrupt routine into the chain only when the task becomes runnable. SKPINS always inserts the interrupt routine at the end of the skip chain, and you usually execute a SKPINS Executive Request in a task as "once-only" code at system start-up time. Therefore, if all tasks are runnable, RTS/8 links the routines in the skip chain by priority of the task which inserts them. Note that the order of the skip chain can differ from the task priority order. If a higher-priority task is not runnable when you start up the system, then the Executive may link a task's interrupt routine into the skip chain in a position that is farther away from the beginning of the chain than that of a lower-priority request. It is important to remember that the function of the skip chain is not to order the priorities but rather the path that the Executive takes when it looks for an interrupt processing routine. 3-18 RTS/8 EXECUTIVE REQUESTS If you wish to control the order of the skip chain, you should create an RTS/8 system that contains only one runnable task when you start-up the system. The function of this task would be to make the tasks runnable in the order in which interrupt routines should link into the skip chain. This task should then block itself permanently after the Executive links all tasks. For example, you may use the following code to block a task permanently. CLA CAL BLKARG (-1) After this code executes, this task blocks itself on all the WAITBITS and frees its partition. Once an interrupt routine receives control, there are several restrictions on its execution: 1. The interrupt routine must clear the interrupt's hardware flag. 2. The interrupt routine is entered with the Data Field and Instruction Field of the next interrupt routine; you must correct this--as shown in the example interrupt processing routine example following this list--before the processor executes any indirect addressing. 3. An interrupt routine can not issue any RTS/8 Executive Requests. 4. An interrupt routine must not compute excessively when interrupts are off. Typical execution time should be under 75 microseconds. If you need considerably more computer time, you should schedule a task to perform this processing by posting an event flag. You use a POSTDS instruction (see 7 below) to wake up the task. 5. Interrupt routines must not turn on interrupts because a second interrupt destroys the processor state of the interrupted task. 6. Upon entering the interrupt routine, the Executive saves the processor state. However, it may not save the contents of the Multiplier Quotient, EAE, FPP, etc. Therefore, interrupt routines requiring the use of these resources must save them before processing the interrupt, and then restore them before leaving the interrupt routine. 7. Interrupt routines should dismiss the interrupt by setting the Instruction Field to RTS8 (which is a system mnemonic that equals the field in which the RTS/8 Executive resides) and issuing a POSTDS instruction. (POSTDS is simply an RTS/8 mnemonic for JMP I 24.) When the Executive dismisses the interrupt, it can post an event flag by setting the Data 3-19 RTS/8 EXECUTIVE REQUESTS Field to the field of the event flag and placing the location of the event flag in the accumulator prior to issuing the POSTDS. For example, CDF .FLD /DF = THIS FIELD TAD (EVFLG) /EVFLG CAN NOT BE AT LOCATION 0 CIF RTS8 /RTS8 = EXECUTIVE FIELD POSTDS /DISMISS INTERRUPT AND POST EVFLG If an interrupt routine will not post an event flag, the routine should clear the accumulator prior to issuing the POSTDS instruction. In this case, the data field DF is irrelevant. The following example illustrates the structure of an interrupt processing routine: MODULE, 0 /THIS WORD GETS A POINTER / TO THE NEXT MODULE 0 /MODULE ENTERED HERE--CONTAINS / CDF CIF TO NEXT MODULE FIELD SKDR /SKIP ON DEVICE READY JMP I MODULE /NOT READY--GO TO NEXT MODULE / IN CHAIN CDF CIF .FLD /THIS ONE IS MINE--SET DF AND IF / CORRECTLY . . /INTERRUPT PROCESSING . CIF RTS8 /DISMISS THE INTERRUPT, MAYBE POSTDS / POST AN EVENT FLAG DEPENDING / UPON THE CONTENTS OF THE AC Using the above interrupt format, an RTS/8 Paper Tape Punch handler task might contain the following sections of code: In the initialization code (contained in a task that is runnable at system start-up time): START, CAL /LINK THE PUNCH SKIP SKPINS / INTO THE SKIP CHAIN PTPINT GETREQ, CAL RECEIVE /WAIT FOR MESSAGE . . . As a character punch subroutine used by the main body of the task: 3-20 RTS/8 EXECUTIVE REQUESTS PUNCH, 0 /ENTER WITH CHAR IN AC DCA CHAR /SAVE CHAR CAL /WAIT UNTIL PUNCH IS READY WAITE PTPEF /SET PUNCH EVENT FLAG ISZ PTPEF / TO THE PENDING STATE TAD CHAR CIF RTS8 /SET INSTRUCTION FIELD TO THAT / OF RTS8 EXECUTIVE PLS /LOAD PUNCH BUFFER SEQUENCE CLA JMP I PUNCH /RETURN . . . In the interrupt skip chain code: PTPINT, ZBLOCK 2 /USED TO CHAIN SKIPS PSF /CHECK PUNCH FLAG JMP I PTPINT /NOT READY CDF CIF .FLD /SET CORRECT DF, IF PCF /CLEAR PUNCH FLAG - TAD (PTPEF) POSTDS /DISMISS INTERRUPT, . / POSTING PTPEF . . PTPEF, 0 /PUNCH INITIALLY READY CHAR, 0 ------------------- NOTE ------------------- | | | RTS/8 does not provide a mechanism for | | removal of entries from the interrupt | | skip chain. | -------------------------------------------- 3-21 RTS/8 EXECUTIVE REQUESTS -------------- -------------- | | | | | SUSPND | | SUSPND | | -------------------------------------------- | | | | Use the SUSPND Executive Request to suspend the execution of a | | task. | | | | Format: | | TAD TSKNUM | | CAL | | SUSPND | | | | where: | | TSKNUM is the number of the task to be blocked from | | running. | | CAL is an RTS/8 mnemonic for JMS 20. | | SUSPND is an Executive Request mnemonic. | | | ---------------------------------------------------------------------- The SUSPND Executive Request is equivalent to the following instructions: TAD TSKNUM CAL BLKARG RUNWT This Executive Request exists because the Executive performs this function often enough to justify a shorthand version. See the BLKARG discussion for more information. The following example shows how you use SUSPND in a task: A data collection task is to print a report every 1000 data points without interrupting the data collection/reduction process. At system start-up, the report generation task comes up running; this means that the first report occurs when it first receives information. (In this simplified example, the data upon which the report program operates may have been already updated for the next cycle before being reported. A full example would require a scheme such as double buffering to protect the data.) 3-22 RTS/8 EXECUTIVE REQUESTS Data Control Task DLOOP, TAD (-1750) /1000 DECIMAL DCA COUNT DATALP, CAL WAITE DATAEF /WAIT FOR DATA READY . / CODE TO STORE DATA . / POINT IN BUFFER . /GET A DATA POINT ISZ COUNT / AND PROCESS IT JMP DATALP /COUNT OFF 1000 POINTS TAD (REPORT) CAL /RUN REPORT TASK RUN JMP DLOOP /KEEP COLLECTING COUNT, 0 Report Generation Task RLOOP, CAL /AC=0, SUSPEND SUSPND / UNTIL NEEDED JMS TITLE /HAS BEEN RUN . . /PRINT REPORT . / WITH TITLE JMP RLOOP /REPORT OVER; GO BACK / AND WAIT To eliminate interference with the data collection, REPORT should have a lower priority than DATA. 3-23 RTS/8 EXECUTIVE REQUESTS -------------- -------------- | | | | | UNBARG | | UNBARG | | -------------------------------------------- | | | | Use the UNBARG Executive Request to specify that a condition | | preventing a task from running no longer exists. | | | | Format: | | TAD TSKNUM | | CAL | | UNBARG | | WAITBITS | | | | where: | | TSKNUM is the number of the task to be unblocked. | | CAL is an RTS/8 mnemonic for JMS 20. | | UNBARG is an Executive Request mnemonic. | | WAITBITS is one or more of the values defined in Table 3-2. | | | ---------------------------------------------------------------------- You use the UNBARG Executive Request to clear one or more bits in a task's Task Flags Word. These bits represent reasons why a task is not runnable. Note that a task may not be running because of several conditions; executing an UNBARG upon one condition may not make the task runnable. A task can be runnable only if all of the bits are zero. TSKNUM contains the number of the task to unblock, and WAITBITS specifies one or more bits to be cleared in task TSKNUM's Task Flags word. If the Task Flags word becomes zero as a result of this operation, TSKNUM becomes runnable. Note that if TSKNUM has a higher priority than the issuing task and becomes runnable, the Executive transfers control to the higher priority task. The lower priority task remains runnable; that is, none of its WAITBITS are set. However, the lower priority task will run only when no other higher priority task is runnable. This Executive Request is a no-op (no operation) if it has a TSKNUM equal to the issuing task's number. Example: The Executive takes task 14 out of User Wait when it executes the following code. TAD (14) CAL UNBARG USERWT However, if task 14 had been blocked with the following code 3-24 RTS/8 EXECUTIVE REQUESTS TAD (14) CAL BLKARG USERWT ! RUNWT then the execution of the above UNBARG would not unblock this task because the UNBARG does not clear the RUNWT bit. 3-25 RTS/8 EXECUTIVE REQUESTS -------------- -------------- | | | | | WAITE | | WAITE | | -------------------------------------------- | | | | Use a WAITE Executive Request to wait for any event flag for this | | task to be posted. | | | | Format: | | CAL | | WAITE | | EFLAG | | | | where: | | CAL is an RTS/8 mnemonic for JMS 20. | | WAITE is an Executive Request mnemonic. | | EFLAG is the location of the event flag. | | | ---------------------------------------------------------------------- The WAITE Executive Request prevents a task from running until the Executive posts any event flag. The WAITE Executive Request checks the status of location EFLAG and, if it is FINISHED, returns control to the caller. If the task is runnable and EFLAG is FINISHED, control returns immediately. If EFLAG is PENDING, the Executive changes its state to WAITING and puts the calling task into Event Flag Wait. After another task or interrupt routine posts location EFLAG, the calling task again becomes runnable. In most cases, you must initialize the event flag (that is, set it to 1) before using it; this is particularly true when a task is initiating an event to be completed by another task. Also, the waiting task must reset the event flag before using it again because the event flag does not reset itself. ------------------- NOTE ------------------- | | | In some applications, you may be waiting | | for multiple event flags. In this case, | | the task runs whenever a task posts an | | event flags, and not necessarily the one | | specified in the WAITE. To ensure that | | a task posts a particular event flag, | | use the WAITX Executive Request. | -------------------------------------------- See Section 3.3 for an example of the WAITE command. 3-26 RTS/8 EXECUTIVE REQUESTS -------------- -------------- | | | | | WAITX | | WAITX | | -------------------------------------------- | | | | Use the WAITX Executive Request to wait for a particular event to | | be posted. | | | Format: | | CAL | | WAITX | | EFLAG | | | | where: | | CAL is an RTS/8 mnemonic for JMS 20. | | WAITX is an Executive Request mnemonic. | | EFLAG is the location of the event flag to be posted. | | | ---------------------------------------------------------------------- The WAITX Executive Request causes a task to wait for a specific event posting, rather than any posting. The WAITX Executive Request, although similar in most respects to the WAITE Executive Request, differs from it in that if the event flag is not FINISHED, the task goes into EORMWT, Event or Message Wait (instead of EFWT); moreover, the task's program counter points back to the location containing the CAL of this Executive Request. (The program counter of a task executing a WAITE points to the location following EFLAG.) Thus, when the task resumes execution, it will re-execute the WAITX. If you or the Executive clear the EORMWT bit for some reason other than the posting of the event flag in question, the task immediately goes back into EORMWT. Consequently, control never flows past this Executive Request unless a task actually posts that event flag. If you use a WAITE and if the task is waiting for multiple event flags, then the task conceivably could start up after the WAITE Executive Request. This is because some other event flag--one that you no longer care about--was posted. This situation cannot occur with a WAITX. See Section 3.3 for an example of the WAITX Executive Request. 3-27 RTS/8 EXECUTIVE REQUESTS 3.3 EXAMPLE OF EXECUTIVE REQUESTS FOR MESSAGE AND EVENT FLAGS The following example illustrates the RTS/8 Executive Requests dealing with messages and event flags. A description of the execution sequence follows the example. Task A A1 ALOOP, CAL __ SEND /SEND TASK B MESSAGE 1 B MES1 CAL SEND /SEND TASK B MESSAGE 2 B MES2 A3 CAL __ WAITX /WAIT ONLY FOR MESSAGE 1 MES1 A4 JMP ALOOP /LOOP __ MES1, ZBLOCK 3 /MESSAGE 1 15 /RANDOM NUMBERS 37 23 MES2, ZBLOCK 3 /MESSAGE 2 -1 /RANDOM NUMBERS 4 Task B B1 BLOOP, CAL __ RECEIVE /GET A MESSAGE MADDR, 0 B2 DCA EFCDF /SAVE MESSAGE CDF FOR POST __ TAD EFCDF B4 DCA .+1 /PUT CDF INLINE __ B5 HLT /CDF TO MESSAGE FIELD __ B6 TAD I MADDR /GET 1ST DATA WORD OF MESSAGE __ / (DO NOTHING WITH IT) B7 CLA __ B8 STA CLL RTL /-3 IN AC __ B9 TAD MADDR /AC POINTS TO MESSAGE EVENT FLAG __ B10 CAL ___ POST /DECLARE MESSAGE RECEIVED EFCDF, HLT /CDF TO MESSAGE FIELD HERE Bll JMP BLOOP /LOOP ___ 3-28 RTS/8 EXECUTIVE REQUESTS The flow of execution in this example depends on which of the two tasks has higher priority. Assuming that at some time both A and B become runnable and that task A has higher priority, the sequence of execution is as follows: Sequence Reason for Execution ________ ____________________ A1 Task A has higher priority than Task B. __ A2 Task A has higher priority than Task B. __ A3 Task A has higher priority than Task B. __ B1 Task A is now in Event Flag Wait since MES1 was __ PENDING; MES1 is now in waiting state. B2-B10 Task A is still waiting; the RECEIVE at B1 received ______ MES1. A4 The post at B10 posted MES1 and "woke up" A, which has __ a higher priority than B. A1 A continues executing. __ A2 A tries to send MES2 again; B has not yet processed __ it; MES2 is pending. Bll Therefore, A is put into Event Flag Wait and B is ___ resumed; MES2 is not waiting. Bl-B10 B now RECEIVes and posts MES2. ______ A2 This brings A out of Event Flag Wait; the RTS/8 __ Executive has modified task A's program counter so that it will re-execute the offending SEND. A3 A3 now waits for MES1 to be posted. __ If Task B has higher priority, the sequence of execution is: B1 Task B has higher priority than Task A. __ A1 Task B is placed in Message Wait since there are no __ messages in its input queue. Task A then sends MES1 to Task B. B2-B10 Task A's message brings task B out of Message Wait; ______ since B has a higher priority, A is stopped and B runs. Bll The post at B10 sets MES1 to FINISHED but has no other ___ effect. B1 Now Task B tries to get another message. __ 3-29 RTS/8 EXECUTIVE REQUESTS A2 There are no other messages; therefore, Task B is put __ into Message Wait, and A is run. B2-Bll Task A sends MES2 which wakes up B; B processes MES2, ______ B1 Returns for more, __ A3 And is put into Message Wait. Since MES1 is FINISHED, __ A4 The WAITE at A3 has no effect and Task A __ A1 Loops back to A1 and sends MES1 again. __ 3.4 EXECUTIVE REQUEST WAIT STATES Table 3-3 is a summary of Executive Request Wait states. 3-30 RTS/8 EXECUTIVE REQUESTS Table 3-3 Summary of Wait States Incurred by Executive Requests ---------------------------------------------------------------------- | ER | Wait State | Condition | PC Suspended | | | | | at | |-------------|------------|-----------------------|-----------------| | | | | | | BLKARG | any (given | If task = self | "CAL"+3 | | | argument) | | | | | | | | | DERAIL | none | _ | _ | | | | | | | POST | none | _ | _ | | | | | | | RECEIVE | MSGWT | If no messages | "CAL" | | (No wait | | in input queue | | | if AC=4000) | | and AC positive | | | | | | | | RESCHD | none | _ | _ | | | | | | | RUN | none | _ | _ | | | | | | | SEND | none | EFWT for SEND if | "CAL" | | | | message busy at "CAL" | | | | | | | | SENDW | EFWT | If message free | "CAL"+3 | | | | but event flag | | | | | not FINISHED | | | | | | | | | EFWT | If message busy | "CAL" | | | | | | | SKPINS | none | _ | _ | | | | | | | SUSPND | RUNWT | If task = self | "CAL"+2 | | | | | | | UNBARG | none | _ | _ | | | | | | | WAITE | EFWT | If event flag | "CAL"+3 | | (No wait if | | | | | EF "done") | | | | | | | | | | WAITX | EORMWT | If specified event | "CAL" | | | | flag not FINISHED | | |____________________________________________________________________| | | | NOTE: (a) "CAL" denotes the address of the CAL instruction in the | | Executive Request. | | (b) A message is said to be busy if its event flag has not | | yet been posted by its previous user. | ---------------------------------------------------------------------- 3-31 CHAPTER 4 RTS/8 SYSTEM TASKS 4.1 RTS/8 SYSTEM TASK SUMMARY The RTS/8 system includes system tasks that control most of the standard DIGITAL PDP-8 I/O devices. Also included are tasks that provide interactive system control from the console terminal and that allow a single copy of the OS/8 operating system to run in the background of a foreground/background system. The system tasks in the RTS/8 system are as follows: 1. Cassette Handler--allows you to read data on a tape cassette. ________________ 2. Cassette File Support Handler--allows you to look up, enter, _____________________________ and delete files from a DECcassette in CAPS-8 format. 3. Clock Handler--performs actions after a specified time has _____________ elapsed. 4. Console and Non-console Terminal Handlers--handle a single __________________________________________ terminal in either line or character mode. 5. Exit Task--permits special processing before making an exit _________ from RTS/8. 6. Floppy Disk Handler--provides support for the use of single ___________________ and double density floppy disks. 7. LINCtape Handler--supports both OS/8 and DIAL-format _________________ LINCtapes. 8. Line Printer Handler--supports LS8, LS8E, LP8, or LV8 line ____________________ printer. 9. Mass Storage Handlers--control the passing of information _____________________ from these devices to and from memory for the RK8, RK8E, and RLO1 moving head disks, DF32 and RF08 fixed-head disks, and TC08 DECtape units. These handlers read and write data in the standard OS/8 block format. 10. OS/8 Files Support Task--allows you to look up, create, and _______________________ delete files in OS/8 directories from a foreground task. This task, when you use it with the mass storage handlers, provides the capability to read or write OS/8 files on mass storage devices. The OS/8 Support Task is not necessary for using this task. 4-1 RTS/8 SYSTEM TASKS 11. OS/8 Support Task--supports the execution of an OS/8 ___________________ operating system in the background. The OS/8 Files Support Task is not necessary for using this task. 12. PDP-8A Null Task--counts in decimal and displays this number ________________ on the LED display accumulator of the PDP-8A. 13. Power Fail Task--provides for an orderly shutdown when AC _______________ power is lost (if you have power fail hardware and core memory). Also allows a programmed restart when power returns. 14. UDC/ICS Handler--allows you to control the various types of _______________ UDC/ICS modules. The remainder of this chapter describes tasks supplied by DIGITAL. ------------------- NOTE ------------------- | | | The tasks actually in your RTS/8 system | | are dependent upon the configuration | | established when the system was | | generated. | -------------------------------------------- 4-2 RTS/8 SYSTEM TASKS 4.2 CASSETTE HANDLER The Cassette Handler (CSA) allows you to read and write variable-length records on DECcassettes, as well as to perform various special functions (such as rewind and write end-file marks). One copy of the Cassette Handler can operate up to eight units. There are two general categories of cassette operation: 1. Handler functions--read and write. 2. Utility functions--rewind, backspace file gap, write file gap, backspace block gap, and skip to file gap. 4.2.1 Handler Function ---------------------------------------------------------------------- | Use the Cassette Handler to perform I/O on a tape cassette. | | | | Message Format: | | ZBLOCK 3 | | CALL+UNIT | | RW+FIELD+NOSTORE | | BUFADD | | SIZE | | STATUS | | | | where: | | CALL specifies whether you are making a handler or | | utility call. | | UNIT is the device unit of the cassette. | | RW specifies whether you are performing a read or | | write operation. | | FIELD is the field of the I/O buffer in the standard | | mass storage handler format (see Section 4.10). | | NOSTORE specifies whether information will be stored. | | BUFADD is the address of the I/O buffer in field FIELD. | | SIZE is the record size. | | STATUS is a location where the Handler places I/O status | | messages. | ---------------------------------------------------------------------- You use the Cassette Handler to perform read and write operations on a cassette. Cassette conventions specify a record size of 200 (octal) bytes, but you can use any size up to 377 (octal); that is, the Handler transfers 8 bits. This record buffer cannot cross field boundaries. For a read operation, the buffer is optional (although you must include its word in the message), according to bit 11 of Word 5. You can use the NOSTORE capability for advancing through a long file. 4-3 RTS/8 SYSTEM TASKS Word 8 contains the contents of status register B, which is defined by the bit setting as follows: Table 4-1 Cassette Handler Status Register Bits ----------------------------- | Bit | Meaning | |-------|-------------------| | 4 | CRC/block error | | 5 | Timing | | 6 | EOT/BOT | | 7 | EOF | | 8 | Drive empty | | 9 | Read/write | | 10 | Write lockout | | 11 | Ready | ----------------------------- The following listing describes the words and meaningful bit positions of the Message Format. Word 4 bit 0 = 0 Utility Call bit 0 = 1 Handler Call bits 9-11 Cassette Unit Word 5 bit 0 = 0 Read 0 = 1 Write bits 6-8 Field of Buffer bit 11 Do not store data (applicable to read only) Word 6 Buffer Address Word 7 Record size in bits 4-11 Word 8 Status Return --------------------------------------------------- | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | --------------------------------------------------- ^ ^ \___________/ 0: Handler call \___| | | 1: Utility call / | | | | RL01 Mode ___________________| | | Unit _________________________________________________________| Figure 4-1 Cassette Handler Unit Word Format 4-4 RTS/8 SYSTEM TASKS --------------------------------------------------- | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | --------------------------------------------------- ^ \__________________/ ^ 0: Read \__________| | | 1: Write / | | | | Field _______________________________________________| | | 0: Read into memory \_____________________________________________| 1: Check data / Figure 4-2 Cassette Handler Call Function Word Format --------------------------------------------------- | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | --------------------------------------------------- ^ ^ ^ ^ ^ ^ ^ ^ CRC/block error _____________________| | | | | | | | | | | | | | | Timing __________________________________| | | | | | | | | | | | | EOT/BOT _____________________________________| | | | | | | | | | | EOF _____________________________________________| | | | | | | | | Drive empty _________________________________________| | | | | | | Read/write ______________________________________________| | | | | Write lookout ________________________________________________| | | Ready _____________________________________________________________| Figure 4-3 Cassette Handler Status Return Word Format At the end of each cassette operation, you should examine Word 8 to check for any errors that might occur during an I/O operation. Examples: A Cassette Handler message to write 100 bytes from a buffer starting at 21200 to cassette unit 3 is as follows: UNIT3=3 /INITIALIZE VARIABLES TO BE HANDLR=4000 / USED IN MESSAGE WRITE=4000 SIZE=100 . MSG1, ZBLOCK 3 HANDLR+UNIT3 /HANDLER OPERATION ON UNIT 3 +WRITE /WRITE FROM FIELD OF "BUFFER" BUFFER SIZE /100 BYTES LONG MSGER1, 0000 /STATUS RETURN 4-5 RTS/8 SYSTEM TASKS To read and not store 200 bytes from unit 2, the message is: READ=0 /INITIALIZE VARIABLES USED NOSTOR=1 / USED IN MESSAGE HANDLR=4000 UNIT2=2 SIZE=200 . . . MSG2, ZBLOCK 3 HANDLR+UNIT2 /HANDLER OPERATION ON UNIT 2 NOSTOR+READ /READ AND DON'T STORE 0000 /UNUSED SIZE /200 BYTES MSGER2, 0000 /STATUS RETURN 4.2.2 Utility Function Handler ---------------------------------------------------------------------- | Use the Utility Handler to perform auxiliary operations upon a | | CAPS-8 formatted cassette. | | | | Message Format: | | ZBLOCK 3 | | CALL+UNIT | | FUNCTN | | STATUS | | | | where: | | CALL specifies if the operation is a utility or handler | | call. | | UNIT is the logical device upon which the message | | performs the action. | | FUNCTN is the operation which the Handler performs. | | STATUS is a word indicating the status of the operation. | ---------------------------------------------------------------------- You use the Utility Function Handler to perform the following operations: 1. Rewind--place the cassette at its first record. 2. Backspace File Gap--place the read/write head at the last file gap marking. 3. Write File Gap--write a file gap at the current tape position. 4. Backspace Block Gap--place the read/write head at the previous record. 5. Skip--place the read/write head at the next file on the cassette. 4-6 RTS/8 SYSTEM TASKS If the Handler encounters an error, it normally retries the operation three times. The exceptions occur when a write lock out occurs on a write operation or when an error appears while reading a cyclic redundancy check. The CAPS-8 User's Manual (DEC-8E-OCASA-A-D) is suggested reading if you are unsure of cassette conventions. For a utility function, the words after the RTS/8 message header are as follows: Word 4 bit 0 = 0 Utility Call bit 0 = 1 Handler Call bits 9-11 Cassette Unit Word 5 (function in bits 6-8): 10 Rewind 30 Backspace File Gap 40 Write File Gap 50 Backspace Block Gap 70 Skip to File Gap Word 6 (see Figure 4-4) --------------------------------------------------- | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | --------------------------------------------------- \________/ Function: _______________________________________| 1 Rewind 3 Backspace file gap 4 Write file gap 5 Backspace block gap 7 Skip to file gap Figure 4-4 Cassette Handler Utility Call For example, to request a rewind on unit 1, the message is: UTILTY=0 /SET UP VARIABLES FOR USE IN UNITl=1 / MESSAGE FORMAT REWIND=10 . . . MSG3, ZBLOCK 3 UTILTY+UNIT1 /UTILITY OPERATION ON UNIT 1 REWIND /REWIND MSGER3, 0000 /STATUS RETURN 4-7 RTS/8 SYSTEM TASKS 4.3 CASSETTE FILE SUPPORT HANDLER ---------------------------------------------------------------------- | Use the Cassette File Support Handler to look up, enter, and | | delete files from a DECcassette in CAPS-8 format. | | | | Message Format: | | ZBLOCK 3 | | COMMND+UNIT | | ADRHED | | ADRFLD | | STATUS | | | | where: | | COMMND can be ENTER, LOOKUP, or CLOSE. | | UNIT is the device number. | | ADRHED is the address of the header for ENTER and LOOKUP, | | or the status return for a CLOSE operation. | | ADRFLD is the field of the header. | | STATUS is the status return location for ENTER and LOOKUP | | operations. | ---------------------------------------------------------------------- The Cassette File Support Handler (CSAF) supports the DECcassette CAPS-8 format. Thus, it allows a calling task to look up and enter files on cassettes in that format. This Handler requires the Cassette Handler Task (CSA) to perform the I/O operations. The Cassette File Support Handler performs the following cassette operations: o ENTER--enters a file name into the cassette directory. o LOOKUP--finds a file name in the cassette directory. o CLOSE--closes the currently open file, enters its directory information, and then rewinds the cassette. ENTER and LOOKUP require you to put appropriate information into the record header area which CSAF uses to perform the file operations. The header area is at least 40 (octal) words long and cannot cross field boundaries. For ENTER and LOOKUP, the format of the header area must conform with cassette standards (and therefore be compatible with CAPS-8). These formats are listed in Table 4-2. 4-8 RTS/8 SYSTEM TASKS Table 4-2 Cassette Header Formats ---------------------------------------------------- | Byte (octal) | Use | |---------------|----------------------------------| | 0-5 | Filename | | | | | 6-10 | Filename extension | | | | | 11 | File Type | | | 1 = ASCII | | | 0 = undefined | | | | | 12-13 | File Record Length | | | (currently word 12 must equal 0)| | | | | 14-15 | Unused | | | | | 16-23 | Date (ASCII) specified as | | | ddmmyy | | | | | 24-37 | Unused | |--------------------------------------------------| | Reference is to 8-bit bytes, one per word, right | | justified. | ---------------------------------------------------- For an ENTER operation, if the Handler finds a file with the name you specify in the header area on the unit, it deletes the file. For a LOOKUP operation, the Handler returns the record size of the file in location HEADER+13 (byte 13). If it cannot find the file or if an error occurs, this location contains a 0. A REWIND operation automatically follows a CLOSE operation. Word definitions for a CSAF message are as follows: Word 4 bit 0 = 1 ENTER bit 1 = 1 LOOKUP bit 2 = 1 CLOSE bits 9-11 UNIT Word 5 Address of header for ENTER and LOOKUP; status return for CLOSE Word 6 Field of header for ENTER and LOOKUP (bits 6-8) Word 7 Status return for ENTER and LOOKUP In all cases, the status return is the contents of status register B. For further information, see the CAPS-8 User's Manual. ____________________ 4-9 RTS/8 SYSTEM TASKS --------------------------------------------------- | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | --------------------------------------------------- \_________/ \___________/ | | Function: _________| | 1 Close | 2 Lookup | 4 Enter | | Unit ___________________________________________________| Figure 4-5 Cassette File Support Handler Unit Word Format Examples: MSG4, ZBLOCK 3 4000 /ENTER ON UNIT 0 6400 /INFORMATION IN HEADER / STARTING AT 6400 0010 / OF FIELD 1 0000 /STATUS RETURN MSG5, ZBLOCK 3 1003 /CLOSE ON UNIT 3 0000 /STATUS RETURN 4-10 RTS/8 SYSTEM TASKS 4.4 CLOCK HANDLER ---------------------------------------------------------------------- | Messages sent to the clock handler direct it to perform actions | | after time intervals which you also specify in the message. | | | | Message Format: | | CLKMSG, ZBLOCK 3 | | COMMND+CLASS+TSKNUM | | TIMEHI | | TIMELO | | EXTRA1 | | EXTRA 2 | | | | where: | | CLKMSG is a label identifying the start of the clock | | message (the Executive uses this location for an | | event flag). | | COMMND is one of the commands listed in Table 4-1. | | CLASS is an optional specification which allows the | | clock CANCEL command to remove groups of requests; | | you may add a CLASS designator to all clock | | requests other than a CANCEL request to label | | those requests for possible future cancelation. | | TSKNUM is the task to receive message beginning at | | CLKMSG, TSKNUM=0 means that the task sending the | | message is also the receiving task. | | TIMEHI/LO specify a time interval from the present time in | | terms of "system ticks" (TIMEHI is the high-order | | word and TIMELO is the low-order word of a double- | | precision number). | | EXTRA1 and EXTRA2 are words used by some of the commands | | listed in Table 4-1. | ---------------------------------------------------------------------- The Clock Handler accepts RTS/8 messages and inserts the entries into an internal clock queue. As the entries become due, the Handler removes them from the queue; the Handler then decodes and executes the request. ------------------- NOTE ------------------- | | | You should be careful that you do not | | exceed the queue length that