SUPPORT DOCUMENTATION

      This report is intended as a more detailed guide to the inner
workings of the Non-Time-Sharing Director than is given in the Service
Routine Library Manual - the report is provided. as "support document­
ation" in the sense described in section 2 of that manual,

      The report is in two sections:-

        A A written description

        B Detailed flow charts

      It should be read in conjunction with the coding, which can be
obtained from the current NINEMASTER - see Service Routine Library

      The Director described is the Standard Non-Time-Sharing Director
and the report takes no account of optional extra facilities,

      The Company reserves the right to change the information
contained in this report without notice.

                                      Library Services
                                Systems Programming Department
                                      1st March 1965

KDF 9 DIRECTOR SUPPORT DOCUMENTATION This report is intended as a complete guide both for those wishing to dissect the official version of the Non-time-sharing Director, and for those who wish to write their own Directors. It is in four sections:- A. A written description. B. Complete flow diagrams. C. Coding (including reference table) of the Director. This report supersedes Reports A1002 (26.8.63) and AR2 (2nd Edition, 25.11.63).
SECTION A General Description CONTENTS Part I : Basic Concepts 1. Storage of Director. Interruption p.1 2. Hardware facilities available to Director p.2 3. Basic structure of Directors p.7 Part II: Description of the Director (KKNO0C310P1U) 4. Paths through Director p.10 5. FLEX, OUT, and some subroutines p.14 6. Peripheral operations and EDT. Subprograms p.18 7. Program failures, termination, and input p.24 8. Input and Storage of Director p.25 9. Errors - symptoms and diagnosis. p.26
The KDF 9 non-Time-Sharing Director Part I. Basic concepts 1. Storage of Director. Interruption 1.1 Operational modes KDF 9 operates in 2 modes, called "Director" mode and "Program" mode. The essential difference between these two modes is that whenever a "Reason for Interruption" (RFI) occurs while the machine is in Program mode, an Interruption takes place, whereas in Director mode, the occurrence of REIs - with one exception, RESET (double-clock) - does not affect the operation of the machine. The machine is set in Director mode either by "Initial Input" or, if in Program mode, by the occurrence of an Interruption; the switch from Director mode to Program mode can only be made by the execution of the instruction "EXIT D". All references to the core store in KDF 9 are "relative" i.e. all data and instruction addresses are augmented by the contents ( a multiple 32) of the Base Address (BA) Register to obtain the required "absolute" core address. Thus any program may be coded as if it, and its data area, occupy a continuous area of the core store starting at address 0, but the area it actually occupies in the machine may be anywhere, provided that it is still continuous, and whenever the program is operating the word it refers to as "0" has its absolute address set in the BA register. When the machine is switched into Director mode, the BA is automatically set to zero, so it is customary for routines operating in Director mode to be stored starting at absolute address 0. It is possible (in Director mode only) to change the value of BA by instruction, but this is normally only used just before switching to Program mode to set the value required by the program. The "Director" to be described in this report is stored at absolute address 0 onwards, and operates in Director mode. Its functions are mainly concerned with the input, execution, and supervision of routines obeyed in Program mode, which are stored in the area starting at the first word whose address is a multiple of 32 and which is not part of the Director, and extending to the very end of the store. The word "Program" is used henceforth to describe such a routine. The essential feature which, from the programmers viewpoint, distinguishes a Program from a routine working in Director mode, is that the former can virtually ignore input/output interlocks - these cause an RFI (Lock-out violation = LOV) to be set, and hence, in Program mode, an Interruption to occur, whenever a Program refers to a peripheral unit, or to an area of core store, which is still involved in an uncompleted peripheral input/output operation. In Director mode, the interlocks are still present, but Interruption is inhibited; the Director must test for their presence, and if necessary program its own evasive action, analogous to interruption, when it engages in input/output operations on its own account.
-2- 1.2 Interruption When an Interruption occurs, the following actions take place:- 1) BA is set equal to O. 2) The "No-Interrupt Flip-Flop" (NIFF) is set (this is what distinguishes Director mode from Program mode). 3) The return address (relative), to which control is to be returned on leaving the Director, is planted in the top cell of SJNS, which nests down 1 place. 4) Control is transferred to syllable 0 of word (absolute address) O. Thus, as well as switching to Director mode, and zeroing BA, Interruption causes a transfer of control (analogous to a "jump to subroutine") to the first syllable of address 0, so that not only must the Director be stored in the area starting at word 0, but it must have an actual entry at word 0, to deal with Interruptions. (There is, incidentally, a hardware restriction that the first instruction obeyed by Director after an Interruption entry may not be a Jump). The "return address" planted in SJNS is relative to the BA of the Program prior to interruption. The instruction EXITD functions like EXIT - i.e. its execution will restore control to the Program when it was interrupted, but at the same time clearing NIFF, i.e. switching back from Director into Program mode; this occurs in such a way that if another RFI is set before or during the execution of EXITD, Interruption occurs again immediately NIFF is cleared, with the same return address as before. Before obeying EXITD, the BA register has to be reset to the value required by the Program. This must be done by the Director itself when it has no more references to the core store to make - that includes instruction fetches. Therefore the last word of instructions obeyed by the Director usually contains: =K1; (Store new BA) ERASE; (remove it from N1) EXIT D; Note: The return address planted by an OUT interruption is the address of the OUT instruction itself. It must therefore be increased by 3 syllables before obeying EXITD, to resume at the next instruction. 2. Hardware facilities available to Director 2.1 Special instructions available only in Director mode These instructions, which cause the LIV RFI to be set if obeyed in program mode, fall into three categories:- 1) EXITD (already described). 2) "Peripheral" instructions (CLOQq and CTQq). 3) Special registers fetch (Kn) and store (=Kn).
-3- Only those used by the Non-Time-Sharing Director are described here (others are available for use by the Time-Sharing Director, etc.; some details are given in KDF 9 News 10). 2.1.1 CLO Qq. Clears peripheral lock-outs from the area of core store defined in the usual way, by Iq and Mq - i.e. from all blocks of 32 words wholly or partly contained in that area, regardless of whether or not lock-outs were present before. Cq is immaterial. 2.1.2 CT Qq. "Clears" any peripheral transfer on the unit given in Cq, also clearing any core store lock-outs associated with the transfer, Iq and Mq are immaterial. At present (9/64) this instruction does not take effect immediately if the unit in question is "unready" at the time, but acts when the "unready" condition is cleared by, e.g. depression of the "load" button on the paper-tape reader with a tape loaded. 2.1.3 =K1 (Store BA and "Number of Locations") Changes the value of BA to 32X where X is the number contained in D38-47 of N1. At the same time D24-33 of N1 are transferred to the "Number of Locations" (NOL) register, whose hardware significance is as follows:- if NOL contains a number N, then whenever any instruction refers to a (relative) core address whose value is greater than (32N + 31) - i.e. to an address whose m.s 10 bits exceed N - the "Lock-in Violation" (LIV) RFI is set. This instruction, like other =Kn instructions, does not nest up, so N1 is left undisturbed. When interruption occurs, although BA is zeroed automatically, the value of NOL is unchanged, and Director should deliberately set a high value in NOL to avoid setting the LIV RFI unnecessarily. 2.1.4 =K2(Store CPDAR) Transfers the contents of N1 to CPDAR without nesting up. CPDAR is a register normally only present on Time-sharing machines. Its various bits correspond individually to different peripheral units, thus D47 = unit 0, D46 = unit 1, D45 = unit 2, D32 = unit (octal) 17, etc. (The bit positions of CPDAR correspond to those of N1). If a unit is used in a peripheral operation when the corresponding bit in CPDAR is not a "one" the LIV RFI is set. This instruction is included in the non-Time-Sharing Director so that it may be used, if necessary, on a machine equipped with CPDAR. 2.1.5 K4 (Fetch RFIR and Clock) Fetches the state of the various reasons for interruption (represented by "1" if set, otherwise zero) into N1, nesting down. The important digits are: D0 Clock overflow D23 Typewriter interrupt (FLEX) D24 Lock-in violation (LIV)
-4- D25 Abuse of capacity of Nesting Store or SJNS (NOUV) D26 End of Director-called transfer (EDT) D27 OUT D29 RESET Execution of K4 automatically "clears" the original reasons for interruption if set, so that no RFI can be processed twice in error. As previously explained, the setting of any RFI in Program mode leads to Interruption: RFIs (except NOUV) may still be set in Director mode, and if not cleared (by K4) prior to returning to Program mode, will cause interruption immediately EXITD is obeyed. The hardware "clock" is a 16-bit counting register to which 1 is added automatcally every 16 microseconds. It thus overflows every 220 microseconds (=1.048576 seconds). It cannot be cleared by instruction, though the "overflow", which sets an RFI when it occurs, is cleared by K4. In addition, K4 brings the most significant 15 bits of the clock into D1-15 of N1. In order to maintain "software" clocks, it is necessary for Director to obey K4 at least once every 1.048576 seconds so that no occurrence of a clock overflow is missed. This particularly affects, e.g. "Busy" loops, which must obey K4 every time round the loop if the Director is liable to be stuck in the loop for more than a second. 2.2 Director's use of Nesting Stores, etc. There is only one Nesting Store, SJNS, overflow registers, test register (TR) and one set of 15 Q-stores in the non-Time-sharing KDF 9, to be used by Director and Programs alike. The Director must ensure that when it returns control to a Program after Interruption, all these registers are as the Program left them. Q-stores - Any Q-stores used by Director are "dumped" in core locations, and restored prior to EXITD. Overflow, TR - Their contents are recorded in a suitable form and reset prior to EXITD. Nesting Store, SJNS - Physically the Nesting Store consists of 3 registers - N1, N2 and N3 - and a "Stack", which is a block of 16 words (numbered 0-15) of core store, together with a 5-bit "stack counter" whose least significant 4 bits are used to address the stack. "Nesting down" causes the contents of register N3 to be written into the word addressed by the stack counter, which is then increased by 1. If this occurred in Program mode when the value of the stack counter was 16 (and is thus increased to 17), the RFI "NOUV" is set. The stack counter records at any time the number of Nesting Store cells occupied, and is used by the instructions JrEN and JrNEN to test for "empty Nesting Store" - the Nesting Store is empty as far as those instructions are concerned if, and only if, all 5 bits of the stack counter are zero. To complete the "nesting down" operation, the contents of N2 and N1 overwrite N3 and N2, respectively. "Nesting up" involves the reverse process: the contents of N2 and N3 overwrite N1 and N2, respectively: the stack counter is decreased by 1, and the contents of the stack word now addressed overwrite N3. If the value of the stack counter was zero, and is therefore now "all ones", and the machine is in Program mode, NOUV is set.
-5- The SJNS works in the same sort of way, except that there is only one register, for the top cell, besides the 16-(sixteen-bit) word stack, and NOUV is set in Program mode if the stack counter goes from 15 to 16, or from 0 to "all ones". One further point must be emphasised: information is never overwritten in a stack. When data is transferred to a word in either stack, what is finally stored is the logical sum (OR) of this data and the previous contents, which normally will be zero. The only way to zero a word in the stack is to read it out: thus nesting up, as described above, not only transfers information from a word in the stack (to a register), but also clears that word. The registers are overwritten. Some implications of this from the Director's viewpoint are described in separate sections below. 2.2.1 NOUV is not set in Director mode, and the Director may use 3 cells of Nesting Store and 1 cell of SJNS in addition to those legitimately used by the Program, without endangering the latter. 2.2.2 In order to obtain a properly "empty" Nesting Store, it is necessary not only that the stack counter be zero, but also that all the words of the stack, and all registers, contain zero. To guarantee the latter it is necessary to perform at least 19 "ERASE" operations (16 to zero each word in the stack and 3 more to then overwrite the registers with zero words from the stack). Both objectives can be achieved by obeying:- 1; ERASE; J1NEN; 2; ERASE; J2NEN; which zeros the stack counter and also performs at least 32 ERASES, in the second loop (label 2), since the stack counter is five bits long. Similarly the instructions:- 3; LINK; ERASE; J3NEJ; 4; LINK; ERASE; J4NEJ; always ensure a correctly empty SJNS. This procedure, involving 4 loops, is performed by the "Initial orders" preceding Director. Subsequently the first three loops must be performed before every new program. One of the SJNS loops may be omitted because it is safe to assume that no Program can leave the SJNS in such a state that it is non-empty and contains more non-zero words than the value of the stack counter - the worst that can happen is when the SJNS underflows, in which case the Director is entered with NOUV set and an apparently empty SJNS; though in fact the register (top cell) contains the return address. One loop will still cope with this situation since the SJNS will be nested up 32 times if it starts "empty". This is not true of the Nesting Store since some of the manipulative operations (e.g. REV;), if used with too little data, can misuse the Nesting Store, i.e. introduce non-zero information into unused cells, without setting NOUV.
-6- 2.2.3 When the Director is entered because of a NOUV Interruption, it is possible that the SJNS has been over-filled, in which case it will contain 17 items on entry (including the return address). In such cases, any further information sent to the SJNS will corrupt the 1st and the 17th items in the SJNS (because they would "share" the same word in the stack), and so the Director should not send information to the SJNS until it has established that NOUV has not occurred (unless it first "dumps" items to make room for new information). Since it is possible for the Nesting Store to be overfilled by up to 9 items before NOUV actually occurs, there is a finite possibility that its contents have already been corrupted before Interruption. There is nothing which can be done about this, beyond ensuring that no assumption of incorruptibility is made! However, it can be assumed that, subject to the conditions described above, the SJNS is uncorrupted when Interruption occurs. 2.3 Input-output operations in Director Mode When an input-output transfer (including a "skip" or "gap" type) operation is executed, the peripheral buffer concerned becomes "Busy", and all blocks of 32 words in the store wholly or partly engaged in the transfer are "Locked Out". Subsequently if while in Program Mode, any peripheral instruction (except "Test Busy" or "Interrupt if Busy") refers to the Busy buffer, an Interruption occurs (LOV RFI) before the instruction can be executed; the return address is that of the instruction itself, whose execution can therefore effectively be postponed automatically until the Busy condition clears. Similarly, any instruction (except "Test Lock- out") which refers to the Locked-out area (including to stores which may have no part in the actual transfer, but lie in a common block of 32 words) will have its execution postponed by a LOV Interruption. The Busy and Lock-out conditions are removed automatically at the end of the appropriate transfer. Thus, a Program need take no action to prevent itself from interfering with input/output transfers which are proceeding in parallel with it. The situation in Director mode is quite different, because no Interruption occurs. The Director is compelled to take action to avoid referring to Busy peripheral units or Locked-out core stores, and, should it have occasion to perform input/output actions which may proceed without requiring other activities of the Director or the Program to be suspended, the Director must organise its own "self-interruption" system - that is, some method whereby, whenever the Director finds itself (as it inevitably will) in a situation which, in Program mode, would lead to a LOV interruption, it suspends the particular activity it is currently engaged in and does something else - in such a way that, when the suspended activity can continue, Director reverts with the necessary alacrity to that activity. Should there be several of these "interruptible" activities, a complex system of "programmed time-sharing" within the Director itself must be organised. It is this need to program a set of concurrent activities, and methods of suspending and resuming each, in such a way that each may proceed independently of other activities of the Director or of the Program, which particularly characterises, and complicates, Director- writing. In a Time-sharing KDF 9 there is hardware provided for facilitating such independent activities in Program mode, but in Director mode there are no such automatic aids, and the whole system must be based primarily on software.
-7- The main hardware aid is the EDT RFI; since the suspension of one of these activities is almost invariably due to the execution of some peripheral transfer called by Director, EDT usually indicates the potential ending of such a suspension, and it is then the task of the system to discover which suspension, which activity to resume, and where. The hardware permits the Director to refer to a Locked-Out area of store, assuming that it knows what it is doing - usually such references are to core areas not actually involved in a transfer, but adjacent to them. In Director mode, a transfer may be called which Locks-Out stores already Locked-Out, without ill effect, though if a core area is involved in more than one transfer at a time, the first of those transfers to finish will cause the Lock-Out to be cleared regardless of whether the others are still going on. If Director attempts to perform a function on a Busy peripheral unit, which would itself make the unit Busy, that function just will not be executed, and control will pass to the next instruction as usual. This the Director should never do, and must take action to prevent. EDT will be set when a unit made "Busy" by Director ceases to be Busy. If the transfer which ended had Locked-Out part of the Program's core area, the EDT Interrupt will ensure that the program does not gain access to this area (when the Lock-Out is simultaneously removed) before the EDT Interrupt occurs - thus the Director may rely on being able to, e.g. check the results of a transfer it makes on behalf of a Program before the latter can get hold of the information transferred, even if the transfer ends while the machine is in Program mode. 3. 3.1 Operating phases Most Directors operate in four phases. Phase 1 comprises the sequences of instructions which are only obeyed following an Interruption entry at syllable 0 of word O. It may include several divergent paths, but one, and only one, is obeyed, once, at every Interruption. Each path inevitably starts in the same way, usually by examining the reasons for Interruption and branching accordingly. Phase 1 also includes housekeeping to record the Program's running time, and, depending on the path subsequently followed, may preserve overflow, TR, and the contents of registers which will be used later by the Director. Phase 1 usually leads to Phase 2 but occasionally may proceed straight into Phase 3. Phase 2 includes most of the instructions which provide the "facilities" offered by Director, e.g. the "concurrent activities" of 2.3., Typewriter interrupts etc. Phase 2 is particularly characterised by repeated examinations of the reasons for Interruption, the repetition of which is usually the consequence of enforced delay due to inability to pass control (via Phase 3) back to a Program due to the non- completion of functions (e.g. Program input) carried out in Phase 2. Phase 2 leads to Phase 3, but only when there are no further reasons for Interrupt set and when a Program can be re-entered. Phase 3 comprises the set of (usually convergent) paths leading to re-entry of the Program (EXIT D). It is the converse of Phase 1, and is obeyed once and only once per Interruption. It includes program timing routines and routines for restoring overflow, TR, and
-8- Q-stores, complementary to those employed in Phase 1. It terminates by restoring BA and NOL and obeying EXIT D. Phase 3 does not include examinations of the RFI register, because once Phase 3 is entered it is assumed that no more RFIs remain to be dealt with before returning to the Program. Phase 0 describes the sequence of instructions which may be carried out between first loading the Director into the machine and subsequently getting into the "normal" routine. Such instructions, for, e.g. setting up peripheral configurations, input of dates and times, etc., will probably only be obeyed once and so may be stored in an area which will subsequently be over-written by Programs. They cannot therefore be considered as part of the Director which is stored permanently in the machine. The entry to Director made after obeying Phase 0 is likely to be in Phase 2, at a point which may also be used after a failure during a program input procedure, when it is assumed that all relics of previous programs have been dealt with and the input of a new program can be instigated, automatically or otherwise. The detailed description of the non-Time-Sharing Director which follows attempts to relate the various routines described to the appropriate phase. The essential characteristics of the phases are:- Phase 1 is concerned with the program which has been interrupted, and is obeyed once in every interruption. Phase 3 is concerned with the program which is to be re-entered, and is obeyed once in every interruption. Phase 2 may, or may not be concerned with a particular program, depending on the reason for interruption. Experience shows that anyone embarking on the writing of a Director is well advised to build on this concept of Phases. In particular it is important to ensure that Phase 2 does not lead back into Phase 1, which, like Phase 3, must be obeyed once, and only once, per interruption. It is of course possible for sequences of instructions to "belong" to more than one Phase, depending on the contexts in which they are used (e.g. subroutines). 3.2. Timing considerations It is important not to underestimate the influence that the need to record various times for, e.g. accounting purposes, has on the structure of Directors. To record "real time" it is necessary to ensure that the occurrence of every CLOCK RFI causes the addition of 1.048576 seconds (i.e. 220 microseconds) to the value of the real time clock. The penalty for missing such an occurrence is severe; if the clock overflows again before the previous clock overflow bit has been cleared (by obeying K4) the RESET (double-clock) RFI occurs. If this RFI occurs in Director mode it can still cause interruption (being the exception which proves the rule) and therefore this must be regarded as catastrophic. However it may occur in Program mode without being regarded as more than a program failure, since certain incorrect instructions (e.g. jumps to syllable 6 or 7) can lead to its being set. Obviously the Director, and any routine running in Director mode (e.g. Director call programs) must examine K4 at least once every 1.048576 seconds to avoid the possibility of getting a "double clock" and in order to correctly maintain the real time record. If "double clock" occurs in program mode the real time record will miss
-9- a second. The need to examine the clock overflow RFI, and if it is present adjust the real time record, every time the RFI register is inspected, is an inducement to use a subroutine to carry out this inspection. The non-Time-Sharing Director has to record "run time" as well as "real time" - i.e. the time spent in Program mode. Every period spent in Program mode starts with an "EXITD" (transferring control from Director to program), preceded y (say) microseconds earlier by the last. K4 obeyed by Director; and ends t microseconds later with an Interrupt which is followed x microseconds later still by another execution of K4. If the difference between the clock "readings" at these two executions of K4 is T, then: t = T - (x+y) Therefore in order to maintain a run time record (RTR), the Director takes the following action in every interruption. - adds to RTR the first clock reading obtained after entering Director: + 1.048576 seconds if clock overflow is detected at this point. - subtracts from RTR the last clock reading (ignoring overflow) obtained before EXITD. - subtracts from RTR a correction which is the value of (x+y) for this interruption. The value of x is usually constant, but y may vary depending on the path followed through Director. By deliberately arranging that the various routes through Phases 1 and 3 are as uncomplicated as possible (in the sense that it always takes the same time to get from A to B) the number of paths, and therefore the number of different values of (x+y), can be reduced to a minimum. A fairly elegant method exists for the practical evaluation of the "path corrections" (x+y). The method is to have a program whose action is to obey OUT 3 (obtain run time from Director) twice in succession and difference the results; but arranging that the second OUT instruction is stored in a temporarily locked-out area, so that this time difference represents an interval during which the Director is continuously cycling - i.e. constantly returning control to the program and immediately interrupting again due to the lockout - and therefore during which no actual running time should be clocked up. By running this program with a Director subtly altered in the following respects (but without affecting its path times):- (a) the Director is forced to always follow the same path, the one which is to be timed. (b) the value of the correction for this path is made equal to -1, so that every time the path is executed 1 is added to RTR, which therefore becomes a "path execution counter". (c) the clock, and clock overflow, scaling factor, is made a power of 2 so that the clock values added or subtracted occupy a fixed field of RTR which does not overlap with the "path execution counter" (b), - then the OUT 3 difference shows both the number of times the relevant path has been executed, and the total execution time. By dividing one into the other the path time is obtained.