!TITLE Introduction
! Programs running in a user process in EMAS 2900 have access to
!
!    * the un-privileged instruction set of the 2900 series
!    * a virtual memory, currently of 32 Mbytes
!    * a set of procedures, collectively known as the "Director
!      interface", which enables the process to do the following:
!
!        a) create and access files
!        b) perform interactive I/O
!        c) handle error and asynchronous contingencies
!        d) access "private" magnetic tapes
!        e) send and accept inter-process messages
!
! Since the procedures comprising the Director interface do not provide
! facilities for program compilation, loading or execution, it is
! assumed that most users of the System will wish either to adopt an
! existing set of such facilities or to write their own.  Such a set
! of facilities is known as a "subsystem".  The appearance of EMAS
! 2900 to a user is determined by the appearance of the subsystem he
! is using.
!
! There is available with EMAS 2900 the "Edinburgh Subsystem", which
! provides facilities for developing and running user programs and
! packages.  This subsystem is used in Edinburgh University, its
! appearance to users is described in Ref. 1.
!
! It is not intended, however, that the Edinburgh Subsystem need
! provide the only user interface to the System, but that other
! installations should be free to provide their own subsystems,
! reflecting their particular requirements.  This manual describes
! the facilities available to the writers of such subsystems.
! Familiarity with "EMAS 2900: Concepts" (Ref. 2) is essential.
!
! It has been a design principle of EMAS 2900 that a user process may
! not interfere, intentionally or otherwise, with any other process.
! At the same time, if a subsystem does not use the Director interface
! correctly, the process can easily disappear without trace,
! particularly before establishing workable contingency handling.  The
! facilities described here are intended to allow a subsystem to be
! built in an incremental way from an interactive terminal, and
! avoiding such pitfalls.  Since a very considerable amount of basic
! work has already been established in the form of the Edinburgh
! Subsystem, it would be reasonable to expect that:
!
! a) A new subsystem would be prepared using the facilities of the
!    Edinburgh Subsystem.
!
! b) A new subsystem would be created in the Edinburgh standard object
!    file format.
!<Conventions
! In general, use should be made of the "EMAS 2900: Concepts" manual
! (Ref. 2), which contains a glossary of terms used in this and other
! EMAS 2900 documents.  The following notes supplement that glossary
! and describe additional relevant terms.
!
! Local Controller, Supervisor
!    In this manual the terms "Local Controller" and "Supervisor" are
!    used to describe resident supervisory code concerned with
!    controlling the user process.
!
! File system number, disc number
!    EMAS disc-packs have two decimal digits as the last two characters
!    of the 6-character label, e.g. EMAS02.  The decimal number which
!    the pair of digits represent is called the disc number or the
!    file system number (interchangeably).
!
! System disc
!   System start-up comprises IPL followed by the loading into main
!   store of a Supervisor (Global Controller, Local Controller and
!   device handlers) from a specified site on a specified disc.
!   That disc is called the "System disc" (or IPL disc or SLOAD disc)
!   for the session, since from that same disc various System components
!   are used by default: Director, permanent processes 1, 2, 3 and 4
!   (respectively called DIRECT, VOLUMS, SPOOLR and MAILER), and the
!   Edinburgh Subsystem.  The sites containing the code and GLAP (see
!   below) for these components are connected into the virtual memory of
!   each user process, as appropriate, and paged from their respective
!   sites on the System disc.
!
! GLAP, GLA
!   In the Edinburgh standard object file format, code and certain
!   other areas are shareable.  However, the area which contains the
!   following components is fundamentally unshareable, it also needs
!   to be written to at program load time and during execution:
!
!     a) global variables (perhaps having initialisation values)
!     b) references to code and data areas in other modules
!     c) code and data entry descriptors in this module
!
!   This area in the object file is called the GLAP (General Linkage
!   Area Pattern).  The initial action of a program load is to
!   connect the object file into virtual memory, and then to make a
!   copy of the GLAP into another segment which is writeable, and
!   unshared by any other user process, leaving the complete object
!   file (including the GLAP) available for shared use by other
!   processes.  The copy of the GLAP in the unshared segment is
!   called the GLA (General Linkage Area).
!
! Main log and Director log
!   System components are able to note chosen events either in the "main
!   log" or in the Director log, 'DIRLOG'.  When a current log file is
!   full, or when the command D/PRINT (or D/DIRPRINT) is given to DIRECT,
!   a new file is supplied and the old one is passed to SPOOLR.  It is
!   queued by SPOOLR until the JOURNAL system (Ref. 3) accepts it for
!   analysis and long-term storage.  When the D/PRINT command is given,
!   a copy of the current file may also sent to the line printer queue,
!   in SPOOLR.  Director is able to monitor process start-up and other
!   events - as described in this manual - by writing either to DIRLOG
!   or, if specified, to a file belonging to the process owner.
!
! IMP80 programming language
!   In this manual, programming entities and record formats are
!   described in terms of the IMP80 programming language (Ref. 4).
!>
!<The File System
! The main principles and features are as follows:
!
!   a) Each disc-pack is treated as a unit, all the files described by
!      the indexes on a disc, reside on that disc.
!
!   b) The file system is implemented "in process" and comprises
!      provision of the following primitives, to be called by outer code
!      (higher ACR, less privileged), in particular a subsystem:
!
!              CREATE file
!              CHANGE file SIZE
!              DESTROY file
!              CONNECT file
!              DISCONNECT file
!
!      Interfaces to lower ACR code are limited to the following
!      requests:
!
!       * MOVE or CLEAR section of disc space
!
!       * CLAIM or FREE semaphore number conventionally associated with a
!         file index or "bitmap".
!
!       * For CONNECT and DISCONNECT, writing into or deleting from the
!         "Master Page Tables" the relationships between the segment
!         numbers of the virtual memory and groups of sections of disc
!         space.  The "Master Page Tables" reside in the Local Controller
!         stack for the process, and the Local Controller organises the
!         virtual memory hierarchy and the satisfying of page faults
!         from the information therein.
!
!   c) Just as the user accesses a file by requesting that it be
!      CONNECTed into his virtual memory and then referencing the
!      appropriate virtual addresses obtained, so the Director code,
!      which implements the file system, creates and accesses the indexes
!      and the "bitmaps" by CONNECTing them also into the virtual memory
!      at a lower ACR level (more privileged) than that of the subsystem
!      and the user.
!
! Director organises the file system in terms of epage units (see the
! Glossary in Ref. 2).  A 100 Mbyte disc pack contains 24000 epages
! (approximately X'5E00'), and currently Director uses from X'40' or 
! X'800' to X'5000' for the file system.  (On a disc which may be used
! as a System disc, epages below X'800' are used for the IPL supervisor
! (Chopsupe), 3 versions of a main supervisor, 4 versions of Director,
! and so on.)  The first 128 pages of the file system space are used for
! the "bitmap" for the disc pack, and for the file indexes for the files
! which reside on the disc-pack.
!
! The "bitmap" is an area containing one bit representing each epage on
! the pack, numbered from 0 to X'5E00' approximately.  A zero bit means
! that the epage is free, a one bit that it is allocated.  The bitmap
! is located at the start of the file system space, the indexes follow,
! and the users' file pages start beyond the indexes.  The actual start
! page numbers are all constants in Director's code.
!
! Director allocates the users' files in maximum-sized units of one
! "section", 128 Kbytes.  A file consisting of 1 segment has either 1 or
! 2 sections, and larger files have more sections as necessary. The file
! index contains a file descriptor giving the name of the file and a list
! of the starting epage numbers of each section of the file.  When a
! CREATE request is made, Director searches the bitmap for
! a group or groups of the required numbers of free pages and sets the
! bits accordingly.  For a CONNECT request, Director extracts the
! starting epage numbers of the sections of the file from the index and
! inserts them into the "claimed block" table and puts pointers from the
! "secondary segment" table to the claimed block table entries.  The
! addresses of the starts of these tables are passed to Director at
! process start-up.
!
! To reference a file index, Director first searches the "name-number
! table", which relates owner names to index page numbers.  When the
! entry for the file owner has been found, Director connects the relevant
! pages into virtual memory.
!
! N.B. Director connects bitmaps, name-number tables and indexes "on     
!      demand" into the user's virtual memory in segments (not
!      accessible to the user) numbered between 16 and 31.  For
!      efficiency, the bitmap and name-number table for the pack on
!      which the process owner's file index and files reside, and also
!      the section containing the file index itself, are left
!      connected for the duration of the process.
!>
!<References
!    1  EMAS 2900: User's Guide (describes the facilities of the
!       Edinburgh Subsystem).  ERCC (1979).
!    2  EMAS 2900: Concepts.  ERCC, 2nd Edition (1978).
!    3  EMAS 2900: The JOURNAL System.  ERCC (1979).
!    4  The IMP Language and Compiler.  Stephens, P.D., Computer Journal,
!       Vol. 17 no. 3 (1974).
!    5  The Primitive Level Interface.  ICL internal document PSD 2.5.1
!       (1975).
!    6  EMAS 2900 Subsystem Note 9: Edinburgh Standard Object File
!       Format. ERCC (1979).
!    7  The EMAS Director.  Rees, D.J., Computer Journal, Vol. 18 no. 2
!       (1975).
!    8  EMAS 2900 System Note 4: EMAS 2900 System Calls.  ERCC (1977).
!    9  EMAS 2900 Supervisor Note 4: Local Stacks.  ERCC (1977).
!   10  EMAS 2900 Supervisor Note 1: PON Mechanism for Director.  ERCC
!       (1978).
!   11  EMAS 2900 Supervisor Note 15: Communications Record Format.  ERCC
!       (1979).
!>