Mercurial > hg > Members > kono > nitros9-code
changeset 19:2caf0658040d
This is the first cut of the OS-9 Operating System: System Programmer's Manual
in Docbook format.
There is still a lot to do.
| author | roug |
|---|---|
| date | Fri, 05 Apr 2002 22:05:31 +0000 |
| parents | b304b9aab9f0 |
| children | 364868eddbc7 |
| files | docs/os9sysprog/makefile docs/os9sysprog/os9sysprog.docbook |
| diffstat | 2 files changed, 4857 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/os9sysprog/makefile Fri Apr 05 22:05:31 2002 +0000 @@ -0,0 +1,17 @@ +SRC=os9sysprog +STYLESHEET=docbook-utils.dsl + +$(SRC).pdf: $(SRC).docbook $(STYLESHEET) + docbook2pdf -d $(STYLESHEET) $(SRC).docbook + +$(SRC).ps: $(SRC).docbook $(STYLESHEET) + docbook2ps -d $(STYLESHEET) $(SRC).docbook + +book1.htm: $(SRC).docbook $(STYLESHEET) + rm -f *.htm *.html +# jade -t sgml -V html-index -d /usr/share/sgml/docbook/dsssl-stylesheets-1.64/html/docbook.dsl $(SRC).docbook +# collateindex.pl -p -o index.docbook HTML.index + docbook2html -d $(STYLESHEET) $(SRC).docbook + +print: + psnup -2 $(SRC).ps | lpr
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/os9sysprog/os9sysprog.docbook Fri Apr 05 22:05:31 2002 +0000 @@ -0,0 +1,4840 @@ +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> +<!-- $Id$ --> +<book id="os9sysman" lang="en"> +<bookinfo> + <title>OS-9 Operating System</title> + <subtitle>System Programmer's Manual</subtitle> + <titleabbrev>OS-9 System Programmer's Manual</titleabbrev> + +<copyright> +<year>1980</year> +<year>1982</year> +<holder>Microware Systems Corporation</holder> +</copyright> + +<legalnotice> +<para>This manual, the OS-9 Program, and any information contained +herein is the copyrighted property of Microware Systems Corporation. +Reproduction of this manual in part or whole by any means, electrical +or otherwise, is prohibited, ecept by written permission from +Microware Systems Corporation.</para> +<para>The information contained herein is believed to be accurate as of +the date of publication, however, Microware will not be liable for +any damages, including indirect or consequential, related to use of +the OS-9 Operating System or of this documentation. The information +contained herein is subject to change without notice.</para> +</legalnotice> +<revhistory> +<revision> +<revnumber>F-1</revnumber> +<date>January 1983</date> +</revision> +</revhistory> +</bookinfo> + +<chapter> +<title>INTRODUCTION</title> +<para>OS-9 Level One is a versatile multiprogramming/multitasking +operating system for computers utilizing the Motorola 6809 +microprocessor,. It is well-suited for a wide range of applications +on 6809 computers of almost any size or complexity. Its main features +are:</para> +<itemizedlist mark="bullet"> + <listitem><para>Comprehensive management of all system resources: memory, + input/output and Cpu time.</para></listitem> + <listitem><para>A powerful user interface that is easy to learn and use.</para></listitem> + <listitem><para>True multiprogramming operation.</para></listitem> + <listitem><para>Efficient operation in typical microcomputer configuratjons.</para></listitem> + <listitem><para>Expandable, device-independent unified I/O system.</para></listitem> + <listitem><para>Full Support for modular ROMed software.</para></listitem> + <listitem><para>Upward and downward compatibility with OS-9 Level Two</para></listitem> +</itemizedlist> +<para>This manual is intended to provide the information necessary to +install, maintain, expand, or write assembly-language software for +OS-9 systems. It assumes that the reader is familiar with the 6809 +architecture, instruction set, and assembly language.</para> +<sect1> +<title>HISTORY AND DESIGN PHILOSOPHY</title> +<para>OS-9 Level One is one of the products of the BASIC09 Advanced 8809 +Programming Language development effort undertaken by Microware and +Motorola from 1978 to 1980. During the course of the project it +became evident that a fairly sophisticated operating system would be +required to support BASIC09 and similar high- performance 6809 +software, OS-9's design was modeled after Bell Telephone +Laboratories' "UNIX" operating system, which is becoming +widely recognized as a standard for mini and micro multiprogramming +operating systems because of its versatility and relatively simple, +yet elegant structure, Even though a "clone" of UNIX for +the 6809 is relatively easy to implement, there are a number of +problems with this approach, UNIX was designed for fairly large-scale +minicomputers (such as large PDP-11s) that have high CPU throughput, +large fast disk storage devices and a static I/O environment, Also, +UNIX is not particularly time or disk-storage efficient, especially +when used with low-cost disk drives.</para> +<para>For these reasons, OS-9 was designed to retain the overall concept +and user interface of UNIX, but its implementation is considerably +different, OS-Vs design is tailored to typical microcomputer +performance ranges and operational environments, As an example, OS-9, +unlike UNIX, does not dynamically swap running programs on and off +disk This is because floppy disks and many lower-cost Winchester-type +hard disks are simply too slow to do this efficiently. Instead, OS-9 +always keeps running programs in memory and emphasizes more efficient +use of available ROM or RAM</para> +<para>OS-9 also introduces some important new features that are intended +to make the most of the capabilities of third-generation +microprocessors, such as support of reentrant, position- independent +software that can be shared by several users simultaneously to reduce +overall memory requirements</para> +<para>Perhaps the most innovative part of OS-9 is its "memory +module" management system, which provides extensive support for +modular Software, particularly ROMed software, This will play an +increasingly important role in the future as a method of reducing +software costs, The memory module" and LINE capabilities of OS- +9 permit modules to be automatically identified, linked together, +shared, updated or repaired, Individual modules in ROM which are +defective may be repaired (without reprogramming the ROM) by placing +a "fixed module,with the same name, but a higher revision number +into memory. Memory modules have many other advantages, for example, +OS-9 can allow several programs to share a common math subroutine +module, The same module could automatically be replaced with a module +containing drivers for a hardware arithmetic processor without any +change to the programs which call. the module</para> +<para>Users experienced with UNIX should have little difficulty adapting +to OS-9. Here are some of the main differences between the two +systems: +</para> +<orderedlist numeration="arabic"> + <listitem><para>OS-9 is written in 6809 assembly language, not C, This + improves program size and speed characteristics</para></listitem> + <listitem><para>OS-9 was designed for a mixed RAM/ROM microcomputer memory + environment and more effectively supports reentrant, + position-independent code.</para></listitem> + <listitem><para>OS-9 introduces the "memory module" concept for + organizing object code with built-in dynamic inter-module linkage.</para></listitem> + <listitem><para>OS-9 supports multiple file managers, which are modules that + interface a class of devices to the file system.</para></listitem> + <listitem><para>"Fork" and "Execute" calls are faster and + more memory efficient than the UNIX equivalents.</para></listitem> +</orderedlist> +</sect1> +<sect1> +<title>SYSTEM HARDWARE REQUIREMENTS +</title> +<para>The OS-9 Operating system consists of building blocks called +memory modules, which are automatically located and linked together +when the system starts up. This makes it extremely easy to +reconfigure the system. For example, reconfiguring the system to +handle additional devices is simply a matter of placing the +corresponding modules into memory, Because OS-9 is so flexible, the +minimum hardware requirements are difficult to define, A bare-bones +LEVEL I system requires 4K of ROM and 25 of RAM, which may be +expanded to 56K RAM</para> +<para>Shown below are the requirements for a typical OS-9 software +development system. Actual hardware requirements may vary depending +upon the particular application.</para> +<itemizedlist mark="bullet"> + <listitem><para>6809 MPU + </para></listitem> + <listitem><para>24K Bytes RAM Memory for Assembly Language Development. 40K + Bytes RAM Memory or High Level Languages such as BASIC09 (RAM Must + Be Contiguous From Address Zero Upward) + </para></listitem> + <listitem><para>4K Bytes of ROM: 2K must be addressed at $F800 - $FFFF, the + other 2K is Position-independent and self-locating. Some disk + systems may require three 2K ROMs.</para></listitem> + <listitem><para>Console terminal and interface using serial, parallel, or + memory mapped video.</para></listitem> + <listitem><para>Optional printer using serial or parallel interface.</para></listitem> + <listitem><para>Optional real-time clock hardware.</para></listitem> +</itemizedlist> +<para>I/O device controller addresses can be located anywhere in the +memory space, however it is good practice to place them as high as +possible to maximize RAM expansion capability, Standard +Microware-supplied OS-9 packages for computers made by popular +manufacturers usually conform to the system's customary memory map</para> +</sect1> +</chapter> +<chapter> +<title>BASIC SYSTEM ORGANIZATION</title> +<para>OS-9 is composed of a group of modules, each of which provides +specific functions, When OS-9 is configured for a specific system +various modules are selected to provide a given level of +functionality, For example, a small. control computer without a disk +does not need the disk-related OS-9 modules, Most examples in this +manual describe a fully-configured OS-9 system.</para> +<para>OS-9 COMPONENT MODULE ORGANIZATION</para> +<para>(Figure here)</para> +<para>RBF Device Descriptors SCF Device Descriptors</para> +<para>Notice that the diagram on the previous page indicates a +multilevel organization.</para> +<para>The first level is the KERNEL and the CLOCK MODULE, The kernel +provide basic system services such as multitasking, memory +management, and links all other system modules, The CLOCK module is a +software handler for the specific real-time-clock hardware, INIT is +an initialization table used by the kernel during system startup. It +specifies initial table sizes, initial system device names, etc.</para> +<para>The second level. is the Input/Output Manager. If provides common +processing all I/o operations. It is required if any OS-supported I/O +is to be performed.</para> +<para>The third level. is the rile Manager level, File managers perform +I/o request processing for similar classes of I/O devices, The Random +Block File Manager (R.BFMAN) processes all disk-type device +functions, and the Sequential Character File Manager (SCFMAN) handles +all non-mass storage devices that basically operate a character at a +time, such as terminals and printers, The user can add additional. +File Managers to handle classes of devices not covered by SCFMAN or +RBFMAN.</para> +<para>The fourth level is the Device Driver Level, Device drivers handle +basic physical I/O functions for specific I/O controller hardware, +Standard OS-9 systems are typically supplied with a disk driver, a +ACIA driver for terminals and serial printers, and a PIA driver for +parallel printers, Many users add customized drivers of their own +design or purchased from a hardware vendor.</para> +<para>The fifth level is the Device Descriptor Level, These modules are +small tables that are associate specific I/O ports with their logical +names, and the port's device driver and file manager, They also +contain the physical. address of the port and initialization data. By +use of device descriptors, only one copy of each driver is required +for each specific type of I/O controller regardless of how many +controllers the system uses.</para> +<para>One important component not shown is the Shell., which is the +command interpreter, It is technically a program and not part of the +operating system itself, and is described fully in the OS-9 Users +Manual.</para> +<para>Even though all modules can be resident in ROM, generally only the +KERNEL and INIT modules are ROMed in disk-based systems, All. other +modules are loaded into RAM during system Startup by a disk bootstrap +module (not shown on diagram) which is also resident in ROM.</para> +</chapter> +<chapter> +<title>BASIC FUNCTIONS OF THE KERNEL</title> +<para>The nucleus of OS-9 is the "kernel", which serves as the +system administrator, supervisor, and resource manager. It is about +3K bytes long and normally resides in two 2K byte ROMs: "P1" +residing at addresses $F800 - $FFFF, and "P2", which is +position-independent. P2 only occupies about half (lK) of the ROM, +the other space in the ROM is reserved for the disk bootstrap module.</para> +<para>The kernel's main functions are:</para> +<orderedlist numeration="arabic"> + <listitem><para>System initialization after restart.</para></listitem> + <listitem><para>Service request processing.</para></listitem> + <listitem><para>Memory management.</para></listitem> + <listitem><para>MPU management (multiprogramming).</para></listitem> + <listitem><para>Basic interrupt processing.</para></listitem> +</orderedlist> +<para>Notice that input/output functions were not included in the list +above; this is because the kernel does not directly process them. The +kernel passes I/O service requests directly to another the +Input/Output Manager (IOMAN) module for processing.</para> +<para>After a hardware reset, the kernel. will. initialize the system +which involves: locating ROMs in memory, determining the amount of +RAM available, loading any required modules not already in ROM from +the bootstrap device, and running the system startup task ( SYSGO ), +The INIT module is a table used during startup to specify initial. +table sizes and system device names.</para> +<sect1> +<title>KERNEL SERVICE REQUEST PROCESSING</title> +<para>Service requests (system calls) are used to communicate between +OS-9 and assembly-language-level. programs for such things as +allocating memory, creating new processes, etc, System calls use the +SWI2 instruction followed by a constant byte representing the code, +Parameters for system calls are usually passed in MPU registers, +...In addition to I/O and memory management functions, there are +other service request functions including interprocess control and +timekeeping.</para> +<para>A system-wide assembly la;guaqe equate file called OS9Defs defines +symbolic names for all. service requests, This file is included when +assembling hand-written or compiler-generated code. The OS-9 +Assembler has a built-in macro to generate system calls, for example:</para> +<para>OSS I$READ +</para> +<para>is recongnized and assembled as the equivalent to:</para> +<para>SWI2 +</para> +<para>FCB I$READ +</para> +<para>Service requests are divided into two categories:</para> +<para>I/O REQUESTS perform various input/output functions. Requests of +this type are passed by the kernel ot 1014AM for processing, The +Symbolic names for this category have a "I$ prefix, for example, +the "read service request is called "I$READ".</para> +<para>FUNCTION REQUESTS perform memory management, multiprogramming, and +miscellaneous functions, Most are processed by the kernel. The +symbolic names for this category begins with "F$. +</para> +</sect1> +<sect1> +<title>KERNEL MEMORY MANAGEMENT FUNCTIONS</title> +<para>Memory management is an important operating system function. OS-9 +manages both the physical. assignment of memory to programs <emphasis>and</emphasis> +the logical contents of memory, by using entities called "memory +modules". All programs are loaded in memory module format, +allowing OS-9 to maintain a directory which contains the name, +address, and other related information about each module in memory, +These structures are the foundation of OS-9's modular software +environment, Some of its advantages are: automatic run-time "linking" +of programs to libraries of utility modules; automatic "sharing" +of reentrant programs; replacement of small sections of large +programs for update or correction (even when in ROM); etc</para> +</sect1> +<sect1> +<title>MEMORY UTILIZATION</title> +<para>All usable RAM memory must be contiguous from address 0 upward, +During the OS-9 start-up sequence the upper bound of RAM is detemined +by an automatic search, or from the configuration module, Some RAM is +reserved by OS-9 for its own data structures at the top and bottom of +memory, The exact amount depends on the sizes of system tables that +are specified in the configuration module</para> +<para>All other RAM memory is pooled into a "free memory" +space. Memory space is dynamically taken from and returned to this +pool as it is allocated or deallocated for various purposes. The +basic unit of memory allocation is the 256-byte page , Memory is +always allocated in whole numbers of pages</para> +<para>The data structure used to keep track of memory allocation is a +32-byte bit-map located at addresses $0100 - $OIIF. Each bit in this +table is associated with a specific page of memory, Bits are cleared +to indicate that the page is free and available for assignment, or +set to indicate that the page is in use or that no RAM memory is +present at that address</para> +<para>Automatic memory allocation occurs when: +</para> +<para>1, Program modules are loaded into RAM</para> +<para>2, Processes are created</para> +<para>3. Processes request additional RAM</para> +<para>4, OS-9 needs I/O buffers, larger tables, etc</para> +<para>All of the above usually have inverse functions that cause +previously allocated memory to be deallocated and returned to the +tree memory pool</para> +<para>In general, memory is allocated for program modules and buffers +frotr high addresses downward, and for process data areas from lower +addresses upward.</para> +<literallayout> +TYPICAL MEMORY MAP +$FFFF +OS-9 ROMS (4K) + + + +I/O DEVICE ADDRESSES + + + + +SPACE FOR MORE +OPTIONAL ROMS + + + + +FILE MANAGERS +DEVICE DRIVERS, ETC. +(APPROXIMATELY 6K) + + + +SHELL (15) + +OS-9 DATA STRUCTURES +(APPROXIMATELY 1K) + + + + +FREE MEMORY FOR +GENERAL USE + + + + +OS-9 DATA STRUCTURES +AND DIRECT RAGE +$0000 BEGINNING OF RAM +MEMORY +</literallayout> +<para> +The map above is for a "typical system, Actual memory +sizes and addresses may vary depending on the exact system +configuration.</para> +</sect1> +<sect1> +<title>OVERVIEW OF MULTIPROGRAMMING</title> +<para>OS-9 is a multiprogramming operating system, which allows several +independent programs called "processes" can be executed +simultaneously. Each process can have access to any system resource +by issuing appropriate service requests to OS-9, Multiprogramming +functions use a hardware real-time clock that generates interrupts at +a regular rate of about 10 times per second, MPU time is therefore +divided into periods typically 100 milliseconds in duration, This +basic time unit is called a tick , Processes that are "active +(meaning not waiting for some event) are run for a specific +system-assigned period called a "time slice", The duration of +the time slice depends on a process's priority value relative to the +priority of all other active processes, Many OS-9 service requests +are available to create, terminate, and control processes</para> +</sect1> +<sect1> +<title>PROCESS CREATION</title> +<para>New processes are created when an existing process executes a fork +service request, Its main argument is the name of the program module +(called the "primary module ) that the new process is to +initially execute, OS-9 first attempts to find the module in the +"module directory , which includes the names of all program +modules already present in memory, If the module cannot be found +there, OS-9 usually attempts to load into memory a mass-storage file +using the requested module name as a file name</para> +<para>Once the module has been located, a data structure called a +"process descriptor is assigned to the new process, The process +descriptor is a 64-byte package that contains information about the +process, its state, memory allocations, priority, queue pointers, +etc. The process descriptor is automatically initialized and +maintained by OS-9, The process itself has no need, and is not +permitted to access the descriptor</para> +<para>The next step in the creation of a new process is allocation of +data storace (RAM) memory for the process, The primary module's +header contains a storage size value that is used unless the "fork +system call requested an optionally larger size. OS-9 then attempts +to allocate a CONTIGUOUS memory area of this size from the free +memory space</para> +<para>If any of the previous steps cannot be performed, creation of the +new process is aborted, and the process that originated the "fork +is informed of the error, Otherwise, the new process is added to the +active process queue for execution scheduling</para> +<para>The new process is also assigned a unique number called a "process +ID which is used as its identifier, Other processes can +</para> +<para>commnunciate with it by referring to its ID in various system +calls, The process also has associated with it a "user ID which +is used to identify all. processes and files belonging to a +particular user, The user ID is inherited from the parent process,</para> +<para>Processes terminate when they execute an "EXIT system service +request, or when they receive fatal signals, The process termination +closes any open paths, deallocates its memory, and unlinks its +primary module.</para> +</sect1> +<sect1> +<title>PROCESS STATES</title> +<para>At any instant, a process can be in one of three states:</para> +<para>ACTIVE - The process is active and ready for execution, +</para> +<para>WAITING - The process is suspended until a child process +terminates or a signal is received, +</para> +<para>SLEEPING - The process is suspended for a specific period of time +or until. a signal is received, +</para> +<para>There is a queue for each process state, The queue is a linked +list of the "process descriptors of processes in the +corresponding state, State changes are performed by moving a process +descriptor to another queue.</para> +<sect2> +<title>The Active State</title> +<para>This state includes all "runnabl.e processes, which are given +time slices for execution according to their relative priority with +respect to all other active processes, The scheduler uses a +pseudo-round-robin scheme that gives all active processes some CPU +time, even if they have a very low relative priority.</para> +</sect2> +<sect2> +<title>The Wait State</title> +<para>This state is entered when a process executes a WAIT system +service request. The process remains suspended until the death of any +of its descendant processes, or, until it receives a signal.</para> +</sect2> +<sect2> +<title>The Sleeping State</title> +<para>This state is entered when a process executes a SLEEP service +request, which specifies a time interval. (a specific number of +ticks) for which the process is to remain suspended, The process +remains asleep until the specified time has elapsed, or until. a +signal is received.</para> +</sect2> +</sect1> +<sect1> +<title>EXECUTION SCHEDULING</title> +<para>The kernel contains a scheduler that is responsible for allocation +of CPU time to active processes, OS-9 uses a Scheduling algorithm +that ensures all processes get some execution time</para> +<para>All active processes are members of the active process queue , +which is kept sorted by process "age", Age is a count of +how many process svitches have occurred since the process' last time +slice, When a process is moved to the active process queue from +another queue, its "age" is initialized by setting it to +the process' assigned priority, i.e., processes having relatively +higher priority are placed in the queue with an artificially higher +age, Also, whenever a new process is activated, the ages of all other +processes are incremented</para> +<para>Upon conclusion of the currently executing process' time slice, +the scheduler selects the process having the highest age to be +executed next, Because the queue is kept sorted by age, this process +will be St the bead of the queue, At this time the ages of a12. other +active Processes are incremented (ages are never incremented beyond +255)</para> +<para>An exception is newly-active processes that were previously +deactivated while they were in the system state, These processes are +noted and given higher priority than others because they are usually +executing critical routines that affect shared system resources and +therefore could be blocking other Unrelated processes</para> +<para>When there are no active processes, the kernel will. set itself up +to handle the next interrupt and then execute a CWAI instruction, +which decreases interrupt latency time</para> +</sect1> +<sect1> +<title>SIGNALS</title> +<para>"Signals" are an asynchronous control mechanism used for +interprocess communication and control, A signal behaves like a +software interrupt in that it can cause a process to suspend a +program, execute a specific routine, and afterward return to the +interrupted program, Signals can be sent from one process to another +process (by means of the SEND service request), or they can be sent +from OS-9 system routines to a process</para> +<para>Status information can be conveyed by the signal in the form of a +one-byte numeric value, Some of the signal "codes" (values) +have predefined meanings, but all the rest are user-defined, The +defined signal codes are: +</para> +<para>0 = KILL (non-interceptable process abort) +</para> +<para>1 = WAKEUP - wake up sleeping process +</para> +<para>2 = KEYBOARD ABORT +</para> +<para>3 = KEYBOARD INTERRUPT +</para> +<para>4 - 255 USER DEFINED +</para> +<para>When a signal is sent to a process, the signal. is noted and saved +in the process descriptor, If the process is in the sleeping or +waiting state, it is changed to the active state, It then becomes +eligible for execution according to the usual MPU scheduler criteria, +When it gets its next time slice, the signal is processed</para> +<para>What happens next depends on whether or not the process had +previously set up a "signal. trap (signal service routine) by +executing an INTERCEPT service request. If it had not, the process is +immediately aborted, It is also aborted if the signal code is zero, +The abort will be deferred if the process is in system mode: the +process dies upon its return to user state</para> +<para>If a signal intercept trap has been set up, the process resumes +execution at the address given in the INTERCEPT service request. The +signal code is passed to this routine, which should terminate with an +RTI instruction to resume normal execution of the process</para> +<para>NOTE: "Wakeup signals activate a sleeping process: they DO +NOT vector through the intercept routine</para> +<para>If a process has a signal pending (usually because it has not been +assigned a time slice since the signal was received), and some other +process attempts to send it another signal, the new signal is aborted +and the "send service request will return an error status. The +sender should then execute a sleep service request for a few ticks +before attempting to resend the signal, so the destination process +has an opportunity to process the previously pending signal</para> +</sect1> +<sect1> +<title>INTERRUPT PROCESSING</title> +<para>Interrupt processing is another important function of the kernel, +All hardware interrupts are vectored to specific processing routines, +IRQ interrupts are handled by a prioritized polling system (actually +part of IOMAN) which automatically identifies the source of the +interrupt and dispatches to the associated user or system defined +service routine, The real-time clock will generate IRQ interrupts, +SWI, SWI2, and SWI3 interrupts are vectored to 4ser-definable +addresses which are "local. to each procedure, except that SWI2 +is normally used for OS-9 service requests calls, The NMI and FIRQ +interrupts are not normally used and are vectored through a. RAM +address to sri RTI instruction</para> +<sect2> +<title>PHYSIcAL, INTERRUPT PROCESSING</title> +<para>The OS-9 kernel. ROMs contain the hardware vectors required by the +£809 MPU at addresses $FFIO through $FFFF, These vectors each +point to jump-extended-indirect instruction which vector the MPU to +the actual interrupt service routine, A RAM vector table in page zero +of memory contains the target addresses of the jump instructions as +follows; +</para> +<informaltable frame="none"> +<tgroup cols="2"> + <thead> + <row> + <entry>INTERRUPT</entry> + <entry>ADDRESS</entry> + </row> + </thead> + <tbody> + <row> + <entry>SWI3</entry> + <entry>$002C</entry> + </row> + <row> + <entry>SWI2</entry> + <entry>$002E</entry> + </row> + <row> + <entry>FIRQ</entry> + <entry>$0030</entry> + </row> + <row> + <entry>IRQ</entry> + <entry>$0032</entry> + </row> + <row> + <entry>SWI</entry> + <entry>$0034</entry> + </row> + <row> + <entry>NMI</entry> + <entry>$0036</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<para>OS-9 initializes each of these locations after reset to point to a +specific service routine in the kernel, The SWI, SWI2, and SWI3 +vectors point to specific routines which in turn read the +corresponding pseudo vector from the process' process descriptor and +dispatch to it, This is why the F$SSWI service request to be local to +a process since it only changes a pseudo vector in the process +descriptor. The IRQ routine points directly to the IRQ polling +system, or to it indirectly via the real-time clock device service +routine, The FIRQ and Nfl. vectors are not normally used by OS-9 and +point to RTI instructions</para> +<para>A secondary vector table located at $FFEO contains the addresses +of the routines that the RAM vectors are initialized to, They may be +used when it is necessary to restore the original service routines +after altering the RAM vectors, On the next page are the definitions +of both the actual. hardware interrupt vector table, and the +secondary vector table: +</para> +<literallayout> +VECTOR ADDRESS +Secondary Vector Table +TICK $FFEO Clock Tick Service +Routine +SWI3 $FFE2 +SWI2 $FFE4 +FIRQ $FFEE +IRQ $FFES +SWI +$FFEA +Nfl $FFEC +WARM $FFEE Reserved for warm-start + +Hardware Vector Table +SWI3 $FFF2 +SWI2 +$FFF4 +FIRQ +IRQ +SWI +NMI $FFFC +RESTART $FFFE +</literallayout> +<para>If it is necessary to alter the RAM vectors use the secondary +vector table to exit the substitute routine, The technique of +altering the IRQ pointer is usually used by the clock service +routines to reduce latency time of this frequent interrupt source.</para> +</sect2> +<sect2> +<title>LOGICAL INTERRUPT POLLING SYSTEM</title> +<para>In OS-9 systems, most I/O devices use IRQ-type interrupts, so OS-9 +includes a sophisticated polling system that automatically identifies +the source of the interrupt and dispatches to its associated +user-defined service routine, The information required for IRQ +polling is maintained in a data structure called the "IRQ +polling table", The table has a 9-byte entry for each possible +IRQ-generatinq device, The table size is static and defined by an +initialization constant in the System Configuration Module</para> +<para>The polling system is prioritized so devices having a relatively +greater importance (i.e., interrupt frequency) are polled before +those of lesser priority, This is accomplished by keeping the entries +sorted by priority, which is a number between 0 (lowest) and 255 +(highest), Each entry in the table has 6 variables: +</para> +<orderedlist numeration="arabic"> + <listitem><para>POLLING ADDRESS: The address of the device's status register, + which must have a bit or bits that indicate it is the source of an + interrupt</para></listitem> + <listitem><para>MASK BYTE; This byte selects one or more bits within the + device status register that are interrupt request flag(s), A set bit + identifies the active bit(s)</para></listitem> + <listitem><para>FLIP BYTE: This byte selects whether the bits in the device + status register are true when set or true when cleared, Cleared bits + indicate active when set</para></listitem> + <listitem><para>SERVICE ROUTINE ADDRESS: The user-supplied address of the + device's interrupt service routine</para></listitem> + <listitem><para>STATIC STORAGE ADDRESS; a user-supplied ter to the permanent + storage required by the device service routine</para></listitem> + <listitem><para>PRIORITY; The device priority number: 0 to 255. This value + determines the order in which the devices in the polling table will + be polled, Note; this is not the same as a process priority which is + used by the execution scheduler to decide which process gets the + next time slice for MPU execution</para></listitem> +</orderedlist> +<para>When an IRQ interrupt occurs, the polling system is entered via +the corresponding RAM interrupt vector, It starts polling the +devices, using the entries in the polling table in priority order, +For each entry, the status register address is loaded into +accumulator A using the device address from the table, An +exclusive-or operation using the flip-byte is executed, followed by a +logical-and operation using the mask byte, If the result is non-zero, +the device is assumed to be the cause of the interrupt</para> +<para>The device's static storage address and service routine address is +read from the table and executed</para> +<para>--> NOTE: The interrupt service routine should terminate with +an an RTS, not an RTI instruction</para> +<para>Entries can be made to the IRQ polling table by use of a special. +os-i service request called "F$IRQ", This is a priviledged +service request that can be executed only when OS-9 is in System Mode +(which is the case when device drivers are executed)</para> +<para>--> NOTE; The actual. code for the interrupt polling system is +</para> +<para>located in the IOMAN module, The kernel P1 and P2 modules contain +the physical. interrupt processing routines.</para> +</sect2> +</sect1> +</chapter> +<chapter> +<title>MEMORY MODULES</title> +<para>Any object to be loaded into the memory of an OS-9 system must use +the memory module format and conventions, The memory module concept +allows OS-9 to manage the logical contents as well. as the physical +contents of memory. The basic idea is that all programs are +individual., named objects</para> +<para>The operating system keeps track of modules which are in memory at +all times by use of a module directory , It contains the addresses +and a count of bow many processes are using each module, When modules +are loaded into memory, they are added to the directory, When they +are no longer needed, their memory is deallocated and their name +removed from the directory (except ROMs, which are discussed later). +In many respects, modules and memory in general, are managed just +like a disk, In fact, the disk and memory management sections of OS-9 +share many subroutines</para> +<para>Each module bts three parts; a module header, module body and a +cyclic-redundancy-check (CRC) value, The header contains information +that describes the module and its use, This information includes; the +modules size, its type (machine language, BASIC09 compiled code, +etc); attributes (executable, reentrant, etc), data storage memory +requirements, execution starting address, etc. The CRC value is used +to ver±f the integrity of a module</para> +<para>There are several different kinds of modules, each type having a +different usage and function, Modules do not have to be complete +programs, or even 6809 machine language, They may contain BASIC09 +I-code , constants, single subroutines, subroutine packages, etc. The +main requirements are that modules do not modify themselves arid that +they be position-independent so OS-9 can load or relocate them +wherever memory space is available, In this respect, the module +format is the OS-9 equivalent of "load records used in +older-style operating systems.</para> +<sect1> +<title>MEMORY MODULE STRUCTURE</title> +<para>At the beginning (lowest address) of the module is the module +header, which can have several. forms depending on the module's +usage, OS-9 family software such as BASIC09, Pascal, C, the +assembler, and many utility programs automatically generate modules +and headers, Following the header is the program/constant section +which is usually pure code, The module name string is included +somewhere in this area, The last three bytes of the module are a +three-byte Cyclic Redundancy Check (CRC) value used to verify the +integrity of the module.</para> +<literallayout> +MODULE FORMAT + +MODULE HEADER + + + +I PROGRAM I +OR CONSTANT$ I +</literallayout> +<para>I CRC</para> +<para>The 24-bit CRC is performed over the entire module from the first +byte of the module header to the byte just before the CRC itself, The +CRC polynomial. used is $800FE3.</para> +<para>Because most OS-9 family software (such as the assembler) +automatically generate the module header and CRC values, the +programner usually does not have to be concerned with writing +routines to generate them.</para> +</sect1> +<sect1> +<title>MODULE HEADER DEFINITIONS</title> +<para>The first nine bytes of all module headers are identical: +</para> +<literallayout> + +MODULE +DESCRIPTION +OFFSET +</literallayout> +<para>- Sync Bytes ($87,$CD), These two constant bytes are used to +locate modules, +</para> +<para>- Module Size, The overall size of the module in bytes (includes +CRC), +</para> +<para>- Offset to Module Name, The address of the module name string +relative to the start (first sync byte) of the module, The name +string can be located anywhere in the module and consists of a string +of ASCII characters having the sign bit set on the last character, +</para> +<para>$6 - Module Type/Language Type, See text. +</para> +<para>$7 - Attributes/Revision Level, See text, +</para> +<para>$8 - Header Check, The one's compliment of the vertical. parity +(exclusive OR) of the previous eight bytes</para> +<sect2> +<title>Type/Language Byte</title> +<para>The module type is coded into the tour most significant bits of +byte 6 of the module header, Eight types are pre-defined by +convention, some of which are for OS-9's internal use only, The type +codes are:</para> +<informaltable frame="none"> +<tgroup cols="2"> + <thead> + <row> + <entry>$1</entry> + <entry>Program module</entry> + </row> + </thead> + <tbody> + <row> + <entry>$2</entry> + <entry>Subroutine module</entry> + </row> + <row> + <entry>$3</entry> + <entry>Multi-module (for future use)</entry> + </row> + <row> + <entry>$4</entry> + <entry>Data module</entry> + </row> + <row> + <entry>$5-$B</entry> + <entry>User-definable</entry> + </row> + <row> + <entry>$C</entry> + <entry>OS-9 System module</entry> + </row> + <row> + <entry>$D</entry> + <entry>OS-9 File Manager module</entry> + </row> + <row> + <entry>$E</entry> + <entry>OS-9 Device Driver module</entry> + </row> + <row> + <entry>$F</entry> + <entry>OS-9 Device Descriptor module</entry> + </row> + <row> + <entry></entry> + <entry>NOTE: 0 is not a legal type code</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<para> "user-defined types having type codes of 0 through 9, They +have six more bytes in their headers defined as follows: +</para> +<informaltable frame="none"> +<tgroup cols="2"> + <thead> + <row> + <entry>MODULE OFFSET</entry> + <entry>DESCRIPTION</entry> + </row> + </thead> + <tbody> + <row> + <entry>$9,$A =</entry> + <entry>Execution Offset, The program or subroutine's starting + address, relative to the first byte of the sync code, Modules + having multiple entry points (cold start, warm start, etc.) may + have a branch table starting at this address.</entry> + </row> + <row> + <entry>$B,$C =</entry> + <entry>Permanent Storage Requirement. This is the minimum number of + bytes of data storage required to run, This is the number used by + FORK and CHAIN to allocate a process' data area.</entry> + <entry>If the module will not be directly executed by a CHAIN or FORK + service request (for instance a subroutine package), this entry + is not used by OS-9. It is commonly used to specify the maximum + stack size required by reentrant subroutine modules, The calling + program can check this value to determine if the subroutine has + enough stack space</entry> + </row> + </tbody> + </tgroup> +</informaltable> +</sect2> +</sect1> +<sect1> +<title>EXECUTABLE MEMORY MODULE FORMAT</title> +<literallayout> +Relative Usage Check Range +Address +4- aa......n...a4, +4... +$00 I I I +Sync Bytes ($87CD) "-4 1 +$01 I I I +I +4,... . a...a.e.,a4. I +$02 1 ++-- Module Size (bytes) --+ +I +$03 I I 1 1, +,.,.., ...m.aa..a.a.....in.a.,.......,...a4.. 1 +1 +$04 I I I I +4.-- Module Name Offset --4 header +sos I +parity +4,... I I +$06 I Type I Language I I +I 1 +$07 1 +Attributes I Revision I + +$OS I Header parity Check I CRC +$09 +I I +4.-- Execution Offset +$OA 1 1 +$OS I I I +4.-- +Permanent Storage Size --4 1 +SOC I I I + +SOD I (Add'l +optional. header I +I extensions located here) I I +I I I +I I +I +1 1 1 +I Module Body I I +I object code, constants, etc, 1 +1 +I I I +1 1 , 1 +1 1 I +4.-- a-4, I +I ORC Cheek Value +1 +4,m. a.a4, +</literallayout> +</sect1> +<sect1> +<title>ROMED MEMORY MODULES</title> +<para>When OS-9 starts after a system reset, it searches the entire +memory space for HOMed modules, It detects them by looking for the +module header sync code ($87,$CD) which are unused 6809 opcodes, When +this byte pattern is detected, the header check is performed to +verify a correct header, If this test succeeds, the module size is +obtained from the header and a 24-bit CRC is performed over the +entire module, If the CRC matches correctly, the module is considered +valid, and it is entered into the module directory, The chances of +detecting a "false module" are virtually nil</para> +<para>In this manner all ROMed modules present in the system at startup +are automatically included in the system module directory, Some of +the modules found initially are various parts of OS-9: file managers, +device driver, the configuration module, etc</para> +<para>After the module search OS-9 links to whichever of its component +modules that it found, This is the secret of OS-9 s extraordinary +adaptability to almost any 6809 computer; it automatically locates +its required and optional. component modules, wherever they are, and +rebuilds the system each time that it is started</para> +<para>ROMe containing non-system modules are also searched so any +user-supplied software is located during the start-up process and +entered into the module directory.</para> +</sect1> +</chapter> +<chapter> +<title>THE OS-9 UNIFIED INPUT/OUTPUT SYSTEM</title> +<para>OS-9 has a unified I/O system that provides system-wide +hardware-independent iio services for user programs and OS-9 itself. +All I/O service requests (system call) are received by the kernel and +passed to the Input/Output Manager (IOMAN) module for processing +IOMAN performs some processing (such as allocating data structures +for the 1/0 path) and calls the file managers and device drivers to +do much of the actual work. File manager, device driver, and device +descriptor modules are standard memory modules that can be loaded +into memory from files and used while the system is running.</para> +<para>The structural organization of I/O-related modules in an OS-9 +system is hierarchical, as illustrated below: +</para> +<para>I Input/Output Manager I +</para> +<literallayout> +(IOMAN) ++fleanana +I I +I Disk File Manager I Char, Pile Manager I +More +(RSPMAN) (SCFMAN) I -> opt +I I I I +I I I + +I £1 I I I I I +Disk! I Disk! I ACIA +II PtA I More +I Driver I I Driver I I Driver I I Driver -> +Opt +I I I I I I! I ++ + stfl.+ +I I I I I I I I +I I I I I I +£ £ +IDQ I ID]. I ID2 1 1D3 I IT]. I IT2 £ IP1 I +IP2 I-> More +4--+ +--+ i~a~+ +---f 4e+ ~ +---+ 4~--+ opt +RBF +Device Descriptors scr Device Descriptors +</literallayout> +<sect1> +<title>THE INPUT/OUTPUT MANAGER (IOMAN)</title> +<para>The Input/output Manager (IOMAN) module provides the first level +of service for I/O system calls by routing data on I/O paths from +processes to/from the appropriate file managers and device drivers. +It maintains two important internal OS-9 data structures: the device +table and the path tablet This module is used tn all OS-9 Level One +systems and should never be modified.</para> +<para>When a path is opened, IOMAN attempts to link to a memory module +having the device name given (or implied) in the pathlist. This +module is the device's descriptor, which contains the names of the +device driver and file manager for the device. This information is +saved by IOMAN so subsequent system call can be routed to these +modules.</para> +</sect1> +<sect1> +<title>FILE MANAGERS</title> +<para>OS-9 systems can have any number of File Manager modules. The +function of a file manager is to process the raw data stream to or +from device drivers for a similar class od devices to conform to the +09-9 standard I/O and file structure, removing as many unique device +operational characteristics as possible from I/O operations. They are +also responsible for mass storage allocation and directory processing +if applicable to the class of devices they service.</para> +<para>File managers usually buffer the data stream and issue requests to +the kernel for dynamic allocation of buffer memory. They may also +monitor and process the data stream, for example, adding line feed +characters after carriage return cbaracters. +</para> +<para>The file managers are reentrant and one file manager may be used +for an entire class of devices having similar operational +ctiaracteristics. The two standard OS-9 file managers are: +</para> +<para>REFMAN: The Random Block File Manager hi operates random-access, +block-structured devices such +</para> +<para>as disk systems, bubble memories, etc.</para> +<para>SCFMAN: Sequential Character Pile Manager which is used with +single-character-oriented devices such as +</para> +<para>CRT or hardcopy terminals, printers, mo e s etc. +</para> +</sect1> +<sect1> +<title>DEVICE DRIVER MODULES</title> +<para>The device driver modules are subroutine packages that perform +basic, low-level 1/0 transfers to or from a specific type of I/O +device hardware controller. These modules are reentrant so One copy +of the module can simultaneously run several different devices which +use identical I/O ccntrollers. For example the device driver for 6850 +serial interfaces is called "ACIA" and can communicate to +any number of serial terminals.</para> +<para>Device driver modules use a standard module header and are given a +module type of "device driver" (code $E).The +execution offset address in the module header points to a branch +table that has a minimum of six (three-byte) entries.Each +entry is typically a LBRA. to the corresponding subroutine. The File +Managers call specific routines in the device driver through this +table, passing a pointer to a path decriptor and the hardware control +register address in the MPU registers. The branch table looks like: +</para> +<literallayout> ++0 - Device Initialisation Routing ++3 - Read Prom Device ++6 - Write to Device ++9 - Get Device Status +- Set Device Status +a +Device Termination Routine +</literallayout> +<para>For a complete description of the parameters passed to these +subroutines see the file manager descriptions Also see +the appendicies on writing device drivers.</para> +</sect1> +<sect1> +<title>DEVICE DESCRIPTOR MODULES</title> +<para>Device descriptor modules are small, non-executable modules that +provide information that associates a specific I/O device with its +logical name, hardware controller address(es), device driver name, +file manager name, and initialization paramaters</para> +<para>Recall that device drivers and file managers both operate on +general classes of devices, not specific I/O ports. The +device descriptor modules tailor their functions to a specific I/O +device, One device descriptor module must exist for each I/O device +in the system</para> +<para>The name of the module is the name the device is known by to the +system and user (i.e. it is the device name given in pathlists}. Its +format consists of a standard module header that has a type "device +descriptor" (code $F). The rest of the device descriptor header +consists of: +</para> +<para>$9,$A = File manager name string relative address.</para> +<para>$B,$C = Device driver name string relative address</para> +<para>$D = Mode/Capabilities.(D $ PS PW PR LW R) +</para> +<para>$E,$F,$10 = Device controller absolute physical (24-bit) address +</para> +<para>$11 = Number of bytes ( "n" bytes in intialization +table)</para> +<para>$l2,$l2+n = Initialization table</para> +<para>The initialization table is copied into the "option section" +of the path descriptor when a path to the device is opened, The +values in this table may be used to define the operating parameters +that are changeable by the OS9 I$GSTT and I$SSTT service requests. +For example, a terminal's initialization parameters define which +control characters are used for backspace, delete, etc. The maximum +size of initialization table which may be used is 32 bytes, If the +table is less than 32 bytes long, the remaining values in the path +descriptor will be set to zero</para> +<para>You may wish to add additional devices to your system, If a +similar device controller already exists, all you need to do is add +the new hardware and load another device descriptor, Device +descriptors can be in ROM or loaded into RAM from mass-storage files +while the system is running</para> +<para>The diagram on the next page illustrates the device descriptor +module format</para> +</sect1> +<sect1> +<title>DEVICE DESCRIPTOR MODULE FORMAT</title> +<literallayout> +MODULE +OFFSET + ......4. ..e..ec 4... - 4...~ + +Sync Bytes ($B7CD) --4 I I +$1 I I I I +4%~.. a ~ ..... in,.~a.t, ++ 1 I +$2 +4.-- Module Size ~-+ I I +$3 I I I +~ +*5 *~StS~S5.5...~ *~~A ~ ~ + I +$4 I I I 1 +4-- Offset to Module +Name --+ header I +$5 I I parity I +4... ~ I I +I SF (TYPE) I +$1 (LANG) 1 I I +I I +$7 I Atributes I Revision I I I +$8 I +Header Parity Check £ I +I +$9 I +4-- Offset to +Pile Manager --+ 1 +I Name String I module +4... ~ CRC +SB I 1 +1 +4.-- Offset to Device Driver --+ I +Name String I +I +.s.....a...e.4. 1 +SD I ModeByte £ +1 +SE I I +4.-- +Device Controller --+ I +I absolute Physical Address I +4-- (24 +bit) --4 I +510 1 1 +$11 1 Initialization Table Size 1 +£ +I +$l2,$l2+N 1 1 +1 (Initialization Table) I I +1 1 +£ +4..,. ~ I +1 £ 1 +1 (Name Strings etc) £ +1 +I £ I +I +I CRC Check Value I I +4- aaaaa +</literallayout> +</sect1> +<sect1> +<title>PATH DESCRIPTORS</title> +<para>Every open path is represented by a data structure called a path +descriptor ("PD"), It contains the information required by +the file managers and device drivers to perform I/O functions. Path +descriptors are exactly 64 bytes long and are dynamically allocated +and deallocated by IOMAN as paths are opened and closed</para> +<para>PDs are INTERNAL data structures that are not normally referenced +from user or applications programs. In fact, it is almost impossible +to locate a path's PD when OS-9 is in user mode, The description of +PDs is mostly of interest to, and presented here for those +programmers who need to write custom file managers,, device drivers, +or other extensions to OS-9</para> +<para>FDa have three sections: the first 10-byte section is defined +universally for all file managers and device drivers, as shown below</para> +<para>Univers.l Path Descriptor Definitions +</para> +<literallayout> +Name Addr SJ.ze Description +PD.PD $00 1 Path number +PD.MOD +$01 1 Access mode: lread 2 wr4te 3-update +PD.CNT $02 1 Number of +paths using this PD +PD.DEV $03 2 Address of associated device +table entry +PD.CPn $05 user's process ID +PD.RGS $06 2 Caller's +MPU register stack address +PD.BUF $08 2 Address of 236-byte data +buffer (if used) +PD.PST $OA 22 Defined by file manager +PD.OPT +$20 32 Reserved for GETSTAT/SETSTAT options +</literallayout> +<para>The 22-byte section called "PD.FST" is reserved for and +defined by each type of file manager for file pointers, permanent +variables, etc</para> +<para>The 32-byte section called "PD.OPT" is used as an +"option" area for dynamically-alterable operating +parameters for the file or device, These variables are initialized at +the time the path is opened by copying the initialization table +contained in the device descriptor module, and can be altered later +by user programs by means of the GETSTAT and SETSTAT System calls</para> +<para>These two sections are defined each file manager's in the assembly +lanuuage equate file (SCFDef a for SCFMAN and RBFDef a for RBFMAN)</para> +</sect1> +</chapter> +<chapter> +<title>RANDOM BLOCK FILE MANAGER</title> +<para>The Random Block File Manager (RBFMAN) is a file manager module +that supports random access block-oriented mass storage devices such +as disk systems, bubble memory systems, and high-performance tape +systems. RBFMAN can handle any number or type of such systems +simultaneously. It is a reentrant subroutine package called by IOMAN +for I/O service requests to random-access devices. It is responsible +for maintaining the logical and physical file structures +</para> +<para>Th the course of normal operation, RBFMAN requests allocation and +deallocation of 256-byte data buffers; usually one is required for +each open file, When physical I/O functions are necessary, RBFMAN +directly calls the subroutines in the associated device drivers, All +data transfers are performed using 256-byte data blocks, RRFMAN does +not directly deal with physical addresses such as tracks, cylinders, +etc Instead, it passes to device driver modules address parameters +using a standard address called a logical sector number, +or WLSNU LSNs ate integers in the range of 0 to n-l, where n is the +maximum number of sectors on the media, The driver is responsible for +translating the logical sector number to actual cylinder/track/sector +values</para> +<para>Because RBFMAN is designed to support a wide range of devices +having different performance and storage capacity, it is highly +parameter-driven, The physical parameters it uses are stored on the +media itselfe On disk systems, this information is written on the +first few sectors of track number zero. The device drivers also use +this information, particularly the physical parameters stored on +sector 0, These parameters are written by the *formatrn program that +initializes and tests the media.</para> +<sect1> +<title>LOGICAL AND PHYSICAL DISK ORGANIZATION</title> +<para>All mass storage volumes (disk media) used by 06-9 utilize the +first few sectors of the volume to store basic identification, +structure, and storage allocation information,</para> +<para>Logical sector zero (LSN 0) is called the +<emphasis>Identification Sector</emphasis> which contains description of the +physical and logical format of the volume.</para> +<para>Logical sector one (LSN 1) contains an allocation map which +indicated which disk sectors ate free and available for use in new or +expanded files.</para> +<para>The voluine's root directory usually starts at logical sector two</para> +<sect2> +<title>Identification Sector</title> +<para>Logical sector number zero contains a description of the physical +and logical characteristics of the volume These are established by +the tmformattm command program when the media is initialized, the +table below gives the 06-9 mnemonic name, byte address, size, and +description of each value stored in this sector. +</para> +<literallayout> +name addr size +descr ption +DD.TOT $00 3 Total number of sectors on media +DD.TKS +$03 1 Number of sectors per track +DD.MAP $04 2 Number of bytes in +allocation map +DD.BIT $06 2 Number of sectors per cluster +DD.DIR +$08 3 Starting sector of root directory +DD.OWN $05 2 Owner's user +number +DD.ATT SOD 1 Disk attributes +DD.D$K $05 2 Disk +identification (for internal use) +DD.FMT $10 1 Disk format: +density, number of sides +DD.SPT $11 2 Number of sectors per +track +DD.REs $13 2 Reserved for future use +DD.BT $15 3 Starting +sector of bootstrap file +DD.BSZ $18 2 Size of bootstrap file (in +bytes) +DD.DAT $lA 5 Time of creation; Y:M:D:H;M +DD.NAM S1F 32 +Volume name: last char has sign bit set +</literallayout> +</sect2> +<sect2> +<title>Disk Allocation Map Sector</title> +<para>One sector (usually LSN 1) of the disk is used for the "disk +allocation map" that specifies which clusters on the disk are +available for allocation of file storage space The address of this +sector is always assigned logical sector 1 by the format proqram +DD,MAP specifies the number of bytes in this sector which are +actually used in the map.</para> +<para>Each bit in the map corresponds to a cluster of sectors on the +disk, The number of sectors per cluster is specified by the "DD.BIT" +variable in the identification sector, and is always an integral +power of two, i,e., 1, 2, 4, 8, 16, etc, There are a maximum of 4096 +bits in the map, so media such as double-density double-sided floppy +disks and hard disks will use a cluster size of two or more sectors, +Each bit is cleared if the corresponding cluster is available for +allocation, or set if the sector is already allocated, non-existent, +or physically defective, The bitmap is initially created by the +"format" utility program</para> +</sect2> +<sect2> +<title>File Descriptor Sectors</title> +<para>The first sector of every file is called a "file descriptor", +which contains the logical and physical description of the file.. The +table below describes the contents of the descriptor</para> +<literallayout> +name addr size description +* - . . * +FD,APT $0 1 File +Attributes: D S PS PW PR LW R +FD,OWN $1 2 Owner's User ID +rD,DAT +$3 5 Date Last Modified; Y M D H M +FD,LNK $8 1 Link Count +FD.5tZ +$9 4 File Size (number of bytes) +FD,DCR $D 3 Date Created; Y N +U +FD.SEG $10 240 Segment List: see below +</literallayout> +<para>The attribute byte contains the file permission bits, Bit 7 is set +to indicate a directory file, bit 6 indicates a "sharable" +file, bit 5 is public execute, bit 4 is public write, etc</para> +<para>The segment list consists of up to 48 five-byte entries that have +the size and address of each block of storage that comprise the file +in logical order, Each entry has a three-byte logical sector number +of the block, and a two-byte block size (in Sectors), The entry +following the last segment will be zero</para> +<para>When a file is created, it initially has no data segments +allocated to it, Write operations past the current end-of-file (the +first write is always past the end-of-file) cause additional sectors +to be allocated to the file, If the file has no segments, it is given +an initial segment having the number of sectors specified by the +minimum allocation entry in the device descriptor, or the number of +sectors requested if greater than the minimum, Subsequent expansions +of the file are also generally made in minimum allocation increments, +An attempt is made to expand the last segment wherever possible +rather than adding a new segment, When the file is closed, unused +sectors in the last segment are truncated</para> +<para>A note about disk allocation: OS-9 attempts to minimize the number +of storage segments used in a file, In fact, many files will only +have one segment in which case no extra read operations ate needed to +randomly access any byte on the file, Files can have multiple +segments if the free space of the disk becomes very fragmented, or if +a file is repeatedly closed, then opened and expanded at some later +time, This can be avoided by writing a byte at the highest address to +be used on a file before writing any other data</para> +</sect2> +<sect2> +<title>Directory Files</title> +<para>Disk directories are files that have the "D" attribute +set. Directory files contain an integral number of directory entries +each of which can bold the name and LSN of a single regular or +directory file,</para> +<para>Each directory entry is 32 b,ytes long, consisting of 29 bytes for +the file name followed by a three byte logical sector number of the +file's descriptor sector, The file name is left-justified in the +field with the sign bit of the last character set. Unused entries +have a zero byte in the first file name character position.</para> +<para>Every mass-storage media must have a master directory called the +"root directory". The beginning logical sector number of +this directory is stored in the identification sector, as previously +described.</para> +</sect2> +</sect1> +<sect1> +<title>RBFMAN Definitions of the Path Descriptor</title> +<para>The table below describes the usage of the file-manager- reserved +section of path descriptors used by RBFMAN.</para> +<literallayout> +Name Addr Size +Description +Universal Section (same for all file managers) +PD.PD $00 1 Path +number +PD.NOD $01 1 Mode (read/write/update) +PD.CNT $02 1 +Number of open images +PD.DEV $03 2 Address of device table +entry +PD.CPR $05 1 Current process ID +PD.RGS $06 2 Address of +callers register stack +PD.BUF $08 2 Buffer address +RBFMAN Path Descriptor Definitions +PD.SN2P $OA 1 State flags +PD.CP $OB 4 Current logical file position (byte +addr) +PD.SIZ $OF 4 File size +PD.SBL $13 3 Segment beginning +logical sector number +PD.SBP $16 3 Segment beginning physical +sector number +PD.SSZ $19 2 Segment size +PD.DSK $15 2 Disk ID +(for internal use only) +PD.DTB $lD 2 Address of drive table +RBFMAN Option Section Definitions (Copied from dev ez +riptor) +$20 1 Device class 0. SCF 1-NSF 2-PIPE $-SBF +PD.DRV $21 +1 Drive number (0,,N) +PD.STP $22 1 Step rate +PD.TYV $23 1 +.Device type +PD.UNS $24 1 Density capability +PD.CYL $25 2 +Number of cylinders (tracks) +PD.SID $27 1 Number of sides +(surfaces) +PD.VFY $28 1 0 verify disk writes +PD.SCT $29 2 +Default number of sectors/track +PD.TOS $213 2 Default number of +sectors/track (track 0) +PD.ILV $2D 1 Sector interleave +factor +PD.SAS $2E 1 Segment allocation size +(the following values are NOT copied from the device descriptor) +PD.ATT $33 1 File attributes (U S PE PW PR LW N) +PD.FD +$34 3 File descriptor PSN (physical sector 1) +PIXDFD $37 3 +Directory file descriptor PEN +PD.DCP $3A 4 Filers directory entry +pointer +PD.DVT $3E 2 Address of device table entry +State Flag (PD.SMF): the bits of this byte are defined as: +</literallayout> +<para>bit 0 - set if current buffer has been altered bit 1 - set if +current sector is in buffer +</para> +<para>bit 2 - set if descriptor sector in buffer +</para> +<para>The first section of the path descriptor is universal for all file +managers, the second and third sections are defined by RBFMAN and +RBFMAN-type device drivers, The option section of the path descriptor +contains many device operating parameters which may be read and/or +written by the OS9 I$GSTT and I$SSTT service requests. This section +is initialized by IOMAN which copies the initialization table of the +device descriptor into the option section of the path descriptor when +a path to a device is opened, Any values not determined by this table +will default to zero</para> +</sect1> +<sect1> +<title>RBF DEVICE DESCRIPTOR MODULES</title> +<para>This section describes the definitions and use of the +initialization table contained in device descriptor modules for +RSF-type devices,</para> +<literallayout> +MODULE +OFFSET +0-$11 Standard Device Descriptor Nodule +Header +$12 IT.DTP RNB 1 DEVICE TYPE (0-SCF 1-REF 2-PIPE 3SBF) +$13 +IT.DRV RMB 1 DRIVE NU,MBER +$14 IT.STP NMB 1 STEP RATE +$15 +IT.TYP RMB 1 DEVICE TYPE (See RBFMAN path descriptor) +$16 IT.DNS +Rm3 1 MEDIA DENSITY (0 - SINGLE, 1-DOUBLE) +$17 IT.CYL RZ4B 2 +NUMBER OF CYLINDERS (TRACXS) +$19 IT.SID RMB 1 NUMBER OF SURFACES +(SIDES) +$IA IT.VFY RMS 1 0 - VERIFY DISK WRITES +$113 IT.SCT RMB +2 Default Sectors/Track +IT.TOS RMJ3 2 Default Sectors/Track (Track +0) +$1F IT.ILV RMB 1 SECTOR INTERLEAVE FACTOR +$20 IT.SAS lIMB 1 +SEGMENT ALLOcATION SIZE +</literallayout> +<para> +IT.DRV - This location is used to associate a one byte integer +with each drive that a controller will handle, The drives for each +controller Should be numbered 0 to n-i, where n is the maximum number +of drives the controller can handle,</para> +<para>IT.STP - (Floppy disks) This location sets the head stepping rate +that will be used with a drive, The step rate should be set to the +fastest value that the drive is capable of to reduce access time, The +actual values stored depended on the specific disk controller and +disk driver module used, Below are the values which are used by the +popular Western Digital floppy disk controller IC: +</para> +<literallayout> + FDl77l FD179X Family +STEP +CODE +0 +4Oms I ZOms 3Oms l5ms +1 1 2Oms I lOins I 2Oins I lOins +2 1 +l2ins I Ems l2ins I Ems +3 1 l2ms I Ems I Ems I 3ins + + + +IT.TY * Device type (All types) + bit 0 -- 0 - 5" floppy disk +1 - 8" floppy disk +bit +6 -e o - Standard OS-9 format +1 - Non-standard format + +bit 7 -- 0 - Floppy disk + +1 - Hard disk + +IT.DNS - Density capabilities (Floppy disk only) + bit 0 -* 0 - Single bit density (FM) +1 - Double bit density +(MEN) + +bit 1 -- 0 - Single track density (5", 48 TPI) + 1 - Double track density (5". 96 TPI) + + +IT.SAS - This value specifies the minimum number of sectors to +be allocated at any one time. +</literallayout> +</sect1> +<sect1> +<title>RBF-TYPE DEVICE DRIVERS</title> +<para>An RBF type device driver module contains a package of subroutines +that perform sector oriented I/O to or from a specific hardware +controller, These modules are usually reentrant so that one copy of +the module can simultaneously run several different devices that use +identical I/O controllers, IOMAN will allocate a static storage area +for each device (which may control Several drives), The size of the +storage area is given in the device driver module header, Some of +this storage area will be used by IOMAN and RBFMAN, the device driver +is free to use the remainder in any manner, This static sto.rage is +used as follows: +</para> +<para>Static Storage Definitions +</para> +<literallayout> +OFFSET ORG 0 +0 V.PAGE RMB 1 PORT EXTENDED ADDRESS (A20 - AlE) +1 +V.PORT RItB 2 DEVICE BASE ADDRESS +3 V.LPRC lIMB 1 LAST ACTIVE +PROCESS ID +4 V.BUSY RMI3 I ACTIVE PROCESS ID (0 - NOT BUSY) +5 +V.WARS RMB 1 PROCESS ID TO REAWAKEN +V.USER EQU ND OF OS9 +DEFINITIONS +6 V.NDRV RMIS 1 NUMBER OF DRIVES +DRVBEG EQU . +BEGINNING OF DRIVE TABLES +7 TABLES RMI3 DRVMEic*N RESERVE N DRIVE +TABLES +FREE EQU , FREE FOR DRIVER TO USE + + + +</literallayout> +<para>NOTE: V.PAGE through V.USER are predefined in the OS9DEFS file. +V.NDRV. DRVBEG, DRVMEM are predefined in the RBFDEFS file.</para> +<para>V.PAGE, V.PORT These three bytes are defined by IOMAN as the 24- +bit device address.</para> +<para>V.LPRC This location contains the process ID of the last process +to use the device, Not used by REF-type device drivers</para> +<para>V.BUSY This location contains the process ID of the process +currently using the device, Defined by RBFMAN.</para> +<para>V.WAKE This location contains the process-ID of any process that +is waiting for the device to complete I/O (0 = NO PROCESS WAITING), +Defined by device driver</para> +<para>V.NDRV This location contains the number of drives that the +controller can use, Defined by the device driver as the maximum +number of drives that the controller can work with, RBFMAN will +assume that there Is a drive table for each drive, Also see the +driver INIT routine in this section,</para> +<para>TABLES This area contains one table for each drive that the +controller will handle (RBFMAN will assume that there are as many +tables as indicated by V.NDRV), Some time after the driver INIT +routine has been called, RBFMAN will issue a request for the driver +to read the identification sector (logical sector zero) from a drive, +At this time the driver will initialize the corresponding drive table +by, copying the first part of the identification sector (up to +DD,SIZ) into it, Also see the Identification Sector" section of +this manual, The format of each drive table is as given below:</para> +<literallayout> +OFFSET ORG 0 +$00 DD.TOT lIMB 3 TOTAL NUMBER OF SECTORS +$03 +DD,TKS RMB 1 TRACK SIZE ( IN SECTORS ) +$04 DD,MAP RMB 2 $ BYTES IN +ALLOcATION BIT NAP +$06 DD,BIT RMB 2 NUMBER OF SECTORS PER BIT +(CLUSTER SIZE) +$08 DD,DIR lIMB 3 ADDRESS OF ROOT DIRECTORY +$013 +DD,OWN RMB 2 .NER.S USER NUMBER +SOD DD,ATT lIMB 1 DISK +ATTRIBUTES +$OE DD,DSK RMI3 2 DISK ID +$10 DD.FMT RMB 1 MEDIA +FORMAT +$11 DD.SPT RMB 2 SECTORS/TRACK +$15 DD,RES RMB 2 RESERVED +FOR FUTURE USE +DD,SIZ LOU +$15 V. TRAE RMB 2 CURRENT TRACK +NUMBER +$17 V.13MB RMB I BIT-MAP USE FLAG +$18 DRVMEM SQU SIZE OF EACH DRIVE TABLE +</literallayout> +<para>DD.TOT This location contains the total number of +sectors +contained on the disk,</para> +<para>DD,TKS This location contains +the track size (in sectors),</para> +<para>DD,MAP This location contains the +number of bytes in the disk allocation bit map,</para> +<para>DD.BIT This location contains the number of sectors that each bit +represents in the disk allocation bit map, DD,DIR This location +contains the logical sector number of the disk root directory, DD,OWN +This location contains the disk owner's user number, DD,APT This +location contains the disk access permission attributes as defined +below: +</para> +<literallayout> +BIT 7 - U (DIRECTORY IF SET) +BITE-S (SHARABLEIFSET) +BIT +5 - PX (PUBLIC EXECUTE IF SET) +BIT 4 - PW (PUBLIC WRITE IF +SET) +BIT 3 - PR (PUBLIC READ I? SET) +BIT 2 - X (EXECUTE IF +SET) +BITI-W (WRITEIFSET). +BITO-R (READIFSET) +</literallayout> +<para> +DD.DSK This location contains a pseudo random number which is +used to identify a disk so that OS-9 may detect when a disk is +removed from the drive and another inserted in its place.</para> +<para>DD.FMT DISK FORMAT:</para> +<literallayout> +BIT 50 - SIDE +0 - SINGLE SIDED +1 - DOUBLE SIDED + +BIT 51 - DENSITY +0 - SINGLE DENSITY +1 - DOUBLE DENSITY + +BIT 132 - TRACK DENSITY +O - SINGLE (48 TFI) 1-DOUBLE (6 ) +</literallayout> +<para>DD,SPT Number of sectors per track (track zero may use a different +value, specified by IT.TOS in the device descriptor), DD,RES RESERVED +FOR FUTURE USE</para> +<para>V.TRAE This location contains the current track which the head is +on and is updated by the driver,</para> +<para>V.3MB This location is used by RBFMAN to indicate whether or not +the disk allocation bit map is currently in use (0 - not in use). The +disk driver routines must not alter this location.</para> +</sect1> +<sect1> +<title>RBFMAN DEVICE DRIVERS</title> +<para>As with all device drivers, REFMAN-type device drivers use a +standard executable memory module format with a module type of +"device driver" (CODE $E). The execution offset address in +the module header points to a branch table that has six three byte +entries, Each entry is typically a LENA to the corresponding +subroutine, The branch table is defined as follows: +</para> +<literallayout> +ENTRY LENA +XNIT INITIALIZE DRIVE +LBRA READ READ SECTOR +LENA WRITE WRITE +SECTOR +LENA GETSTA GET STATUS +LENA SETSTA SET STATUS +LENA +TERM TERMINATE DEVICE +</literallayout> +<para>Each subroutine should exit with the condition code register C bit +cleared if no error occurred, Otherwise the C bit should be set and +an appropriate error code returned in the B register, Below is a +description of each subroutine, its input parameters, and its output +pa eters.</para> +<sect2> +<title>NAME: INIT</title> +<para>INPUT: (U) - ADDRESS OF DEVICE STATIC STORAGE (Y) - ADDRESS OF THE +DEVICE DESCRIPTOR MODULE +</para> +<para>OUTPUT: NONE</para> +<para>ERROR OUTPUT: (CC) = C BIT SET</para> +<para>(B) = ERROR COOE</para> +<para>FUNCTION: INITIALIZE DEVICE AND ITS STATIC STORAGE AREA +</para> +<orderedlist numeration="arabic"> + <listitem><para>If disk writes are verified, use the F$SRQM service, request + to allocate a 256 byte buffer area where a sector may be read back + and verified after a write,</para></listitem> + <listitem><para>Initialize the device permanent storage, For floppy disk + controller typically this consists of initializing V.NDRV to the + number of drives that the controller will work with, initializing + DD,TOT in the drive table to a non-zero value so that sector zero + may be read or written to, and initializing V.TRAK to $FF so that + the first seek will find track zero,</para></listitem> + <listitem><para>Place the IRQ service routine on the IRQ polling list by + using the OS9 F$IRQ service request,</para></listitem> + <listitem><para>Initialize the device c ntro registers (enable interrupts if + necessary)</para></listitem> +</orderedlist> +<para>NOTE: Prior to being called, the device permanent storage will be +cleared (set to zero) except for V.PAGE and V.PORT which will contain +the 24 bit device address, The driver should initialize each drive +table appropriately for the type of disk the driver expects to be +used on the corresponding drive.</para> +</sect2> +<sect2> +<title>NAME: READ</title> +<para>INPUT: (U) s. ADDRESS OF THE DEVICE STATIC STORAGE +(Y. - +ADDRESS OF THE PATH DESCRIPTOR +(B) - NSB OF DISK LOGICAL SECTOR +NUMBER +(X) - LSB's OF DISK LOGICAL SECTOR NUMBER +</para> +<para>OUTPUT: SECTOR IS RETURNED IN THE SECTOR BUFFER</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para> +FUNCTION: READ A 256 BYTE SECTOR</para> +<para> +Read a sector from the disk and place it in the sector buffer +(256 byte). Below are the things that the disk driver must do:</para> +<para>1, Get the sector buffer address from PD.BUF in the path +descriptor,</para> +<para>2. Get the drive number from PD.,DRV in the path descriptor.</para> +<para>3, Compute the physical disk address from the logical Sector</para> +<para>number,</para> +<para>4, Initiate the read operation,</para> +<para>5. Copy V.BUSY to V.WAKE, then go to sleep and wait for the I/O to +complete (the IRQ service routine is responsible for sending a wake +up signal), After awakening, test V.WAKE to see if it is clear, if +not, go back to sleep,</para> +<para>If the disk controller can not be interrupt driven it will be +necessary to perform programmed I/O.</para> +<para> +NOTE 1: Whenever logical sector zero is read, the first part +of this sector must be copied into the proper drive table (get the +drive number from PD.DRV in the path descriptor). The number of bytes +to copy is DD.SIZ.</para> +<para> +NOTE 2: The drive number (PD.DRv) should be used to compute +the offset to the corresponding drive table as follows:</para> +<para>LDA PD.DRV.Y Get drive number +LDB *DRVMEM Get size of a drive +table +MU L +LEAK DRVBEG,U Get address of first table +LEAX +D,X Compute address of table N +</para> +</sect2> +<sect2> +<title>NAME: WRITE</title> +<para>INPUT: (U) = ADDRESS OF TEE DEVICE STATIC STORAGE AREA +(Y) +ADDRESS OF THE PATH DESCRIPTOR + (B) - MSB OF THE DISK LOGICAL +SECTOR NUMBER +(X) - LSB's OF THE DISK LOGICAL SECTOR NUMBER +</para> +<para>OUTPUT: THE SECTOR BUFFER IS WRITTEN OUT TO DISK</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para> +FUNCTION. WRITE A SECTOR</para> +<para> +Wtite the sector buffer (256 bytes) to the disk, Below are the +things that a disk driver must do:</para> +<para>1, Get the sector buffer address from PD.BUF in the path +descriptor,</para> +<para>2. Get the drive number from PD.DRV in the path descriptor,</para> +<para>3. Compute the physical disk address from the logical Sector</para> +<para>fl4mber,</para> +<para>4. Initiate the write operation,</para> +<para>5, Copy V.BtjSy to V.WAKE, then go to. sleep and wait for the I/O +to complete (the IRQ service routine is responsible for sending the +wakeup signal), After awakening, test V.WAXE to see if it is clear, +if it is not, then go back to sleep, If the disk controller can not +be interrupt-driven, it will be necessary to perform a programmed I/O +transfer,</para> +<para>6, If PD.VFY in the path descriptor is equal to zero, read the +sector back in and verify that it was written correctly, This usually +does not involve a compare of the data,</para> +<para>NOTE 1: If disk writes are to be verified, the INIT routine must +request the buffer where the sector may be placed when it is read +back in, Do not copy sector zero into the drive table when it is read +back to be verified,</para> +<para>NOTE 2: Use the drive number (PD.DRV) to compute the offset to the +corresponding drive table as shown for the READ routine.</para> +</sect2> +<sect2> +<title>NAME: GETSTA PUTSTA</title> +<para>INPUT: (U) - ADDRESS OF TEE DEVICE STATIC STORAGE AREA +(Y) - +ADDRESS OF THE PATH DESCRIPTOR +(A) - STATUS CODE +</para> +<para>OUTPUT: (DEPENDS UPON TEE FUNCTION CODE) +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>FUNCTION: GET/SET DEVICE S.TATUS +</para> +<para> + + +</para> +<para>These routines are wild card calls used to get (set) the device's +operating parameters as specified for the OS9 I$GSTT and I$SSTT +service requests,</para> +<para>It may be necessary to examine or change the register stack which +contains the values of MPU registers at the time of the I$GSTT or +I$SSTT service request, The address of the register stack may be +found in PD.RGS, which is located in the path descriptor, , The +following offsets may be used to access any particular value in the +register stack: +OFFSET MNEMONIC MPG REGISTER +$0 NSCC RMB I +CONDITION CODE REGISTER +$1 R$D LOU . U REGISTER +$1 NSA RMB 1 A +REGISTER +$2 R$B RMB 1 B REGISTER +$3 R$DP EMS 1 PP REGISTER +$4 +R$X NME 2 K REGISTER +$6 R$Y R143 2 Y REGISTER +$8 R$D RMB 2 U +REGISTER +SA R$PC EMS 2 PROGRAM COUNTER</para> +</sect2> +<sect2> +<title>NAME:TERM</title> +<para>INPUT: (U) = ADDRESS OF DEVICE STATIC STORAGE AREA +</para> +<para>OUTPUT: NONE +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>FUNCTION: TERMINATE DEVICE</para> +<para>This routine is called when a device is no longer in use in the +system, which is defined to be when the link count of~ its device +descriptor module becomes zero), The TERM routine must:</para> +<para>1. Wait until any pending I/O has completed,</para> +<para>2. Disable the device interrupts,</para> +<para>3. Remove the device from the IRQ polling list,</para> +<para>4. If ,tbe INIT routine reserved a 256 byte buffer for verifying +disk writes, return the memory with the F$MEM service request.</para> +</sect2> +<sect2> +<title>NAME: IRQ SERVICE ROUTINE</title> +<para>FUNCTION: SERVICE DEVICE INTERRUPTs +</para> +<para> +Although this routine is not included in the device driver +module branch table and is not called directly by RBFMAN, it is an +key routine in interrupt-driven device drivers, Its function is to:</para> +<para>1. Service device interrupts,</para> +<para>2. When the I/O is complete, the IRQ service routine should send</para> +<para>a wake up signal to the process whose process ID is in V.WAKE</para> +<para>Also clear V.WAKE as a flag to the mainline program that the IRQ</para> +<para>has indeed occurred. + + + +</para> +<para>NOTE: When the IRQ service routine finishes servicing an interrupt +it must clear the array and exit with an RTS instruction.</para> +</sect2> +<sect2> +<title>NAME: BOOT (Bootstrap Module)</title> +<para>INPUT: None,</para> +<para>OUTPUT: (U) - SIZE OF THE BOOT FILE (in bytes) +(X) - ADDRESS OF +WHERE THE BOOT FILE WAS LOADED IN MEMORY +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>FUNCTION. LOAD TEE BOOT FILE I 0 ORY FROM MASS-STORAGE + + + +</para> +<para>NOTE: The BOOT module is ncit~ part of the disk driver, It is a +separate module which is normally co-resident with the uOS9P2w module +in the system firmware,</para> +<para> +The bootstrap module contains one subroutine that loads the +bootstrap file and Some related information into memory, it uses the +standard executable module format with a module type of "system" +(code $C). The execution offset in the module header contains the +offset to the entry point of this subroutine,</para> +<para>It obtains the starting sector number and size of the "OS9Boot" +file from the identifIcation sector (LSN 0), OS-9 is called to +allocate a memory area large enough for the boot file, and then it +loads the boot file into this memory area,</para> +<para>1. Read the identification sector (sector zero) from the disk. +BOOT must pick its own buffer area, The identification sector +contains the values for DD.BT (the 24 bit logical sector number of +the bootstrap file), and PP.552 (the size of the bootstrap file in +bytes). For a full description of the identification sector, +See +6.1,1,</para> +<para>2. After reading the identification sector into the buffer, get +the 24 bit logical sector number of the bootstrap file from DD,BT.</para> +<para>3. Get the size (in bytes) of the bootstrap file from PP.1352, The +boot is contained in one logically contiguous block beginning at the +logical sector specified in DD,BT and extending for (PP.1352/256+1) +sectors,</para> +<para>4, Use the OS9 F$SRQM service request to request the memory area +where the boot file will be loaded into.</para> +<para>5, Read the boot file into this memory area,</para> +<para>6. Return the size of the boot file and its location.</para> +</sect2> +</sect1> +</chapter> +<chapter> +<title>SEQUENTIAL CHARACTER FILE MANAGER</title> +<para>The Sequential Character File Manager (SCFMAN) is the OS-9 file +manager module that supports devices that operate on a character- +by-character basis, such as terminals, printers, modems, etc. SCFMAN +can handle any number or type of such devices, It is a reentrant +subroutine package called by XOMAN for I/O service requests to +sequentia~ character ~oriented devices, It includes the extensive +input and output e~diting functions typical of line- oriented +operat~.on such as: backspace, line delete, repeat line, auto line +feed, Screen pause, return delay padding, etc</para> +<para>Standard OS-9 systems are supplied with SCFMAN and two SCF-type +device driver modules: ACIA, which run 6830 serial interfaces, and +PIA, which drives a 682l-type parallel interface for printers</para> +<sect1> +<title>SCFMAN LINE EDITING FUNCTIONS</title> +<para>I$READ and I$WRITE service requests (which correspond to Basic09 +GET and PUT statements) to SCFMAN-type devices pass data to/from the +device without any modification, except that keyboard interrupt, +keyboard abort, and pause character are filtered out of the input +(editing is disabled if the corresponding character in the path +descriptor contains a zero). In particular, carriage returns are not +automatically followed by line feeds or nulls, and the high order +bits are passed as sent/received</para> +<para>I$RDLN and I$WRLN service requests (which correspond to BasicQ9 +INPUT, PRINT, READ and WRITE statements) to SCFMAN-type devices +perform full line editing of all functions enabled for the paYticular +device, These functions are initialized when the device is first used +by copying the option table from the device descriptor table +associated with the specific device, They may be altered anytime +afterwards from assembly language programs using the I$SSTT and +I$GSST service requests, or from the keyboard using the T~CDE +command, Also, all bytes transfered in this mode will have the high +order bit cleared</para> +<para>The following path descriptor values control the line editing +functions: +</para> +<para>If PD.UPC <> 0 bytes input or output in the range ~ are made +~A. .Z~ +</para> +<para>If PD.rXO <> 0, input bytes are echoed, except that +undefined control characters in the range $0~~$lF print as ~ +</para> +<para>If PD.ALF <> 0, carriage returns are automatically followed +by line feeds</para> +<para>If PD.N17L <> 0~ After each CR/LF a PD.NUL unu~tlS~ (always +$00) are sent</para> +<para>If PD.PAU <> 0, Auto page pause will occur after every +PD.PAU lines since the last input</para> +<para>If PD.BSP <> 0. SCF will recognize PD.HSP as the ~input~ +backspace character, and will echo PD.8$E (the backspace echo +character) if PD.BSo 0, or PD.BSE, space, PD~8SE if PD.BSQ K> 0</para> +<para>If PD.DEL <> 0, SCF will. recognize PD.DEL the delete line +character (on input), and echo the backspace sequence over the entire +line if PD.DLO 0, or echo CR/LF it PD.DLO <> 0 +</para> +<para>PD.EOR defines the end of record character, This is the last +character an each line entered (I$RDLN), and terminates the output +</para> +<para>(I$WRLN) when this character is sent, Normally PD.EOR will be set +to $OD, If it is set to zero, SCF's READLN will NEVER terminate, +unless an EOF occurs,</para> +<para>It PD.EOF <> 0. it defines the end of file character, SCFMAN +will return an end-of-file error on I$READ or I$RDLN if this is the +first (and only) character input, It can be disabled by setting its +value to zero,</para> +<para>If PD.RPR <> 0. SCF (I$RDLN) will, upon receipt of this +character, echo a carriage return (optional line feedl, and then +reprint the current la~ne,</para> +<para>It PD.DUP <> 0, SCF (I$RDLN) will duplicate whatever js in +the input buffer through the first PD.EOH~ character,</para> +<para>It PD.PSC <> 0, output is suspended before the next "PD.EOR" +character when this character is input, This will also delete any +type abead~ input for I$RDLN,</para> +<para>If PD.INT <> 0, and is received on input, a keyboard +interrupt signal is sent to the last user of tbrs path, Also it will +terminate the current I/O request (it any) with an error identical to +the keyboard interrupt signal code, This location normally is set to +a control-C character,</para> +<para>If PD.QUT <> 0. and is received on input, a keyboard abort +signal is sent to the last user of this path, Also it will terminate +the current I/O request (if any) with an error code identical to the +keyboard interrrupt signal code, This location is normally set to a +control-Q character,</para> +<para>It PD.OVF <> 0, It is echoed when I$RDLN has satisfied its +input byte count without finding a wPD.EOR~ character,</para> +<para> + + +</para> +<para>NOTE: It is possible to disable most of these special editing +functions by setting the corresponding control character in the path +descriptor to zero by using the I$SSTT service request, or by running +the TMODE utility, A more permanent solution may be had by setting +the corresponding control character value in the device descriptor +module to zero,</para> +<para> +Device descriptors may be inspected to determine the default +settings for these values for specific devices.</para> +</sect1> +<sect1> +<title>SCFMAN Definitions of The Path Descriptor</title> +<para>The table below describes the path descriptors used by SCFMAN and +SCFMAN-type device drivers,</para> +<para>Name Offset Size Description</para> +<para> + + +</para> +<para>Universal Section (Same for all file managers) +PD.PD $00 1 Path +number +PD.MOD $01 I Mode (read/write/update) +PD.CNT $02 I +Number of open images +PD.DEV $03 2 Address of device table +entry +PD.CPR $03 I Current process ID +PD.RGS $06 2 Address of +callers MPU register stack +PD.BUF $08 I Butter address</para> +<para>SCFMAN Path Descriptor Definitions +PD.DVI $OA 2 Device table +addr of 2nd (echo) device +PD.RAW $OC I Edit flag: 0-raw mode, +1-edit mode +PD.MAX $OD 2 Headline maximum character count +PD.MIN +$OF 1. Devices are wininew it cleared +PD.STS $10 2 Status routine +module address +PD.STh $12 2 Reserved for status routine +</para> +<para>SCFMAN Option Section Definition +$20 1 Device class 0-SC F +2PIPE 35 +PD.UPC $21 1 Oase (0-BOTH, 1-UPPER ONLY) +PD.BSO $22 1 +Backsp (0-835, 1-835 SP 8SE) +PD.DLO $23 1 Delete (0 - 855 over +line, 1-CR LF) +PD.EXO $24 I Echo (0-no echo) +PD.AtF $25 1 Auto +LF (0-no auto LF) +PD.NtTL $26 1 End of line null count +PD.PAU +$27 1 Pause (0= no end of page pause) +PD.PAG $28 1 Lines per +page +PD.HSP $29 1 Backspace character +PD.DEL $2A I Delete line +character +PD.EOR $25 1 End of record character (read only) +PD.EoF +$2C I End of file character (read only) +PD.RPR $2D I Reprint line +character +PD.DUP $25 1 Duplicate last line character +PD.PSC $2F +I Pause character +PD,INT $30 I Meyboard interrupt character (CTL +C) +PD.QUT $31 1 Eeyboard abort character (CTL 0) +PD.BSE $32 1 +Backspace echo character (BSE) +PD.OVF $33 1 Line overflow +character (bell) +PD.PAR $34 1 Device initialization value +(parity) +PD.BAQ 335 1 Software settable baud rate +PD.D2P $36 2 +Offset to 2nd device name string +PD.STN $38 2 Offset of status +routine name +PD.ERR $3A 1 Most recent I/O error status + + + +</para> +<para>The first section is universal for all file managers, the second +and third section are specific~for SCFMAN and SCFMAN-type device +drivers, The option section of the path descriptor contains many +device operating parameters whicb may be read or written by the OS9 +I$GSTT or I$SSTT service requests, IOMAN initializes this section +when a path is opened to a device by copying the corresponding device +descriptor initialization table, Any values not determined by this +table will default to zero +</para> +<para>Special editing functions may be disabled by setting the +corresponding control character value to zero</para> +</sect1> +<sect1> +<title>SCF DEVICE DESCRIPTOR MODULES</title> +<para>Device descriptor modules for SCP-type devices contain the device +address and an initialization table which defines inital values for +the I/O editing features, as listed below,</para> +<para> +MODULE +OFFSET ORG $12 +TABLE 500 , BEGINING OF OPTION +TABLE +$12 IT.DVC HItS I DEVICE CLASS (0-SCF l-RBF 2-PIPE +3-8512) +$13 IT.UPC RMB I CASE (0-BOTH, J.UPPER ONLY) +$14 IT.BSO +HItS 1 SACS SPACE (0-855, l BSE,SP.BSE) +$15 IT.DLO HItS 1 DELETE +(0-885 OVER LINE, 1-CR) +$16 IT.EXO RItE 1 50130 (OWNO ECHO) +$17 +IT.A.LF RItE I. AUTO LINE FEED (0- NO AUTO LF) +$18 IT.NUL HItS 1 +END OF LINE NULL COUNT +$19 IT.PAU 5103 1 PAUSE (0 NO END OF PAGE +PAUSE) +$1A IT. PAG RItE 1 LINES PER PAGE +$13 IT. ES? HItS 1 +BACXSPACE CHARACTER +$10 IT.DED HItS 1 DEDETE LINE CHARACTER +$11) +IT.EOR RItE 1 END OF RECORD CHARACTER +$15 IT.EOF RItE 1 END OF +FILE CHARACTER +$1F IT.R~PR RItE 1 REPRINT LINE CHARACTER +$20 +IT.DUP RItE 1 SUP LAST LINE CHARACTER +$21 IT.PSC RItE 1 PAUSE +CHARACTER +$22 IT.INT RItE 1 INTERRUPT CHARACTER +$23 IT.00T RItE +1 QUIT CHARACTER +$24 IT.BSE RItE 1 BACKSPACE ECHO CHARACTER +$25 +IT.OVF RItE I LINE OVERFL~ CHARACTER (BELL) +$26 IT.PAR. RItE 1 +INITIALIZATION VALUE (PARITY) +$27 IT.UAI2 RItE I BAUD RATE +$28 +IT.D2F RItE 2 ATYACEED DEVICE NAME STING O12FSET +$2A IT.STN RItE 2 +OFPSET TO STATUS ROUTINE +320 IT.ERR RItE 1 INITIAL ERROR STATUS</para> +<para> +NOTES:</para> +<para>8012 editing functions will be ~turned off~ if the corresponding +special character is a zero, For example, it IT.EOF was a zero, there +would be no end of file character,</para> +<para>IT.PAR is typically used to intitialize the device s control +register when a path is opened to it.</para> +</sect1> +<sect1> +<title>SCF DEVICE DRIVER STORAGE DEFINITIONS</title> +<para>An SCF!,tAN-type device driver module contains a package of +subroutines that perform raw I/o transfers to or from a specific +hardware controller, These modules are usually reentrant so that one +copy of the module can simultaneously run several different devices +that use identical I/O controllers, For each +~ of the driver, +IOMAN will allocate a static storage area for that device, The siz7e +of the storage area is given in the device driver module header, Some +of this storage area will be used by IOMAN and SCFMAN, the device +driver is free to use the remainder in any way (typically as +variables and butters), This static storage is defined as: +OFFSET +ORG 0 +$0 V.PAGE RItE 1 PORT EXTENDED ADDRESS +$1 V.PCRT RItE 2 +DEVICE BASE ADDRESS +$3 V.LPRC RItE 1 LAST ACTIVE PROCESS ID +$4 +V.BUSY RItE I ACTIVE PROCESS ID (0 NOT BUSY) +$5 V. WAKE HItS I +PROCESS II) TO REAWAZEN +V. USER EQU . END OF OS9 DEFINITIONS +$6 +V.TYPE RItE I DEVICE TYPE OR PARITY +$7 V.LINt RItE 1 LINES LEFT +TILL END OF PAGE +$8 V.PAUS RItE 1 PAUSE REQUEST (0 - NO PAUSE) +$9 +V.DEV2 RItE 2 ATTACHEs DEVICE STATIC STORAGE +$5 V. INTH RItE 1 +INTERRUPT CHARACTER +$0 V.00IT RItE 1 QUIT CHARACTER +$1) V.PCHR +RItE I PAUSE CHARACTER +$E V. ERR RItE 1 ERROR ACCUMULATOR +$F +V.SCF EQU END OF SCFMAN DEFINITIONS +FREE EQU . FREE FOR DEVICE +DRIVER TO USE</para> +<para> + + +</para> +<para>V.PAGE, V.PORT These three bytes are defined by IOMAN to be the 24 +bit device address,</para> +<para>V.LPRC This location contains the process-Is of the last process +to use the device. The IRQ service routine is responsible for sending +this process the proper signal in case a "QUIT" character +or an "INTERRUPT" character is recieved, Defined by SCFMAN,</para> +<para> +V. BUSY This location contains the process ID of the process +currently using the device (zero if it is not being used), This is +used by SCFriAN to prevent more than one process from using the +device at the same moment, Defined by SCFMAN.</para> +<para>V.WAR~ This location contains the process ID of any process that +is waiting for the device to complete I/O (or zero if there is none +waiting), The interrupt service routine should check this location to +see if a process is waiting and if so, send it a wake up signal, +Defined by the device driver</para> +<para>V.TYPE This location contains any special characteristics of a +device, It is typically used as a value to initialize the device +control register, for parity etc. It is defined by SCFMAN which +copies its value from PP.PAR in the path descriptor</para> +<para>V.LINE This location contains the number of lines left till end of +page, Paging is handled by SCFMAN and not by the device driver</para> +<para>V.PROS This location is a flag used by SCFMAN to indicate that a +pause character has been recieved, Setting its value to anything +other than zero will cause SCFMAN to stop transmitting characters at +the end of the next line, Device driver input routines must set +V.PAUS in the ECHO devic&s static storage area, SCFMAN will check +this value in the ECHO device's static storage when output is sent</para> +<para>V.DEV2 This location contains the address of the ECHO (attached) +device's static storage area. Typically the device and the attached +device are one and the same, However they may be different as in the +case of a keyboard and a memory mapped video display, Defined by +SCFMAN</para> +<para>V.INTR Keyboard interrupt character, It is defined by SCFMAN, +which copies its value from PD.INT in the path descriptor</para> +<para>V.QUIT Keyboard abort character, It is defined by SCFMAN which +copies its value from PD.QUT in the path descriptor</para> +<para>V.PCHR Pause character. It is defined by SCFMAN which copies its +value from PD.PsC in the path descriptor</para> +<para>V.ERR This location is used to accumulate I/O errors. Typically it +is used by the IRQ service routine to record errors so that they may +be reported later when SCFMAN calls one of the device driver routines</para> +</sect1> +<sect1> +<title>SCFMAN DEVICE DRIVER SUBROUTINES</title> +<para>As with all device drivers, SCFMAN device drivers use a standard +executable memory module format with a module type of +edevice +drivers (CODE $5). The execution offset address in the +module +header points to a branch table that has six three byte entries, Each +entry is typically a LBRA to the corresponding subroutine, The branch +table is as follows: +ENTRY LERA INIT INITIALIZE DEVICE +LBHA +READ READ CHARACTER +LBRA WRITE IIRITE CHARACTER +LBRA GETSTA +GET DEVICE STATUS +LBRA SETSTA SET DEVICE STATUS +LBRA TERM +TERMINATE DEVICE +</para> +<para> +Each subroutine should exit with the condition code register C +bit cleared it no error occured, Otherwise the C bit should be set +and an appropriate error code returned in the B register. Below is a +description of each subroutine, its input parameters and its output +parameters.</para> +<sect2> +<title>NAME: INIT</title> +<para>INPUT: (U) - ADDRESS OP DEVICE STATIC STORAGE (Y) - ADDRESS OF +DEVICE DESCRIPTOR MODULE +</para> +<para>OUTPUT: NONE +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>FUNCTION: INITIALIZE DEVICE AND ITS STATIC STORAGE</para> +<para> +3. Initialize the device static storage,</para> +<para>2, Place the IRQ service routine on the IRQ polling list by using +the OS9 F$IRQ service request,</para> +<para>3, Initialize the device control registers (enable interrupts if +necessary),</para> +<para> + + +</para> +<para>NOTE: Prior to being called, the device static storage will be +cleared (set to zero) except for V.PAGE and V.PORT which will contain +the 24 bit device address. There is no need to initialize the portion +of static stora e used by 1011AM and SCFr4AN.</para> +</sect2> +<sect2> +<title>NAME: READ</title> +<para>INPUT: (U) - ADDRESS OF DEVICE STATIC STORAGE</para> +<para>(Y) - ADDRESs OP PATH DESCRIPTOR OUTPUT: (A) - CHARACTER READ</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>FUNCTION: GET PJEXT CHARACTER +</para> +<para> +This routine should get the next character from the input +buffer, If there is no data ready, this routine should copy its +process ID from V.BUSY into V.WAKE and then use the F$SLEP service +request to put itself to sleep.</para> +<para>Later when data is recieved, the IRQ service routine will leave +the data in a buffer, then check V.WAKE to see if any process is +waiting for the device to complete I/O, If so, the IP.Q service +routine should send a wakeup signal to it, + + + +</para> +<para>NOTE: Data buffers are NOT automatically allocated, It any are +used, they should be defined in the device's static storage area.</para> +</sect2> +<sect2> +<title>NAME: WRITE</title> +<para>INPUT: (U) = ADDRESS OF DEVICE STATIC STORAGE +(Y) = ADDRESS OF +THE PATH DESCRIPTOR +(A) - CHAR TO WRITE +</para> +<para>OUTPUT: NONE</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>FUNCTION: OUTPUT A CHARACTER</para> +<para>This routine places a data byte into an output buffer and enables +the device output interrupts, It the data buffer is already full, +this routine should copy its process ID from V.BUSY into V.WAKE and +then put itself to sleep,</para> +<para>Later when the IRQ service routine transmits a character and makes +room for more data in th. buffer, it will check V.WAKE to see if +there is a process waiting for the device to complete I/O, It there +is, it will send a wake up signal to that process.</para> +<para>NOTE: This routine must ensure that the IRQ service routine will +start up when data is placed into the buffer, After an interrupt is +generated the IRQ service routine will continue to transmit data +until the data butter is empty, and then it will disable the device's +"ready to transmit" interrupts,</para> +<para>NOTE: Data buffers are NOT automatically allocated, If any are +used, they should be defined in the device's static storage.</para> +</sect2> +<sect2> +<title>NAME: GETSTA/SETSTA</title> +<para>INPUT: (U) = ADDRESS OP DEVICE STATIC STORAGE +(Y) - ADDRESS OF +PATH DESCRIPTOR +(A) = STATUS CODE</para> +<para>OUTPUT: DEPENDS UPON FUNCTION CODE</para> +<para>FUNCTION: GET/SET DEVICE STATUS +</para> +<para> +This routine is a wild card call used to get (set) the device +parameters specified in the I$GSTT and I$SSTT service requests, +Currently all of the function codes defined by Microware for SCF- +type devices are handled by 1011AM or SCFMAN, Any codes not defined +by Microware will be passed to the device driver,</para> +<para>It may be necessary to examine or change the register packet which +contains the values of the 6809 registers at the time the OS9 service +request was issued, The address of the register packet may be found +in PD.RGS, which is located in the path descriptor, The following +offsets may be used to access any particular value in the register +packet: +OFFSET NMEMONIC MPU REGISTER +0 R$CC RItE I CO ITIO S +CODE REGISTER +$1 R$D EQU , S REGISTER +$1 R$A RItE 1 A +REGISTER +$2 R$B RItE 1 B REGISTER +$3 R$DP RItE 1 5? REGISTER +$4 +R$X RItE 2 X REGISTER +$6 R$Y RItE 2 Y REGISTER +$8 R$U RItE 2 U +REGISTER +R$PC RItE 2 PROGRAM COUNTER</para> +</sect2> +<sect2> +<title>NAME. TERM</title> +<para>INPUT: (U) - PTR TO DEVICE STATIC STORAGE +</para> +<para>OUTPUT: NONE +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>FUNCTION: TERMINATE DEVICE +</para> +<para>This routine is called when a device is no longer in use, defined +as when its device descriptor module's link count becomes zero), It +must perform the following:</para> +<para>1, Wait until the output buffer has been emptied (by the IRQ +service routine)</para> +<para>2. Disable device interrupts,</para> +<para>3, Remove device from the IRQ polling list,</para> +<para> +NOTE: Static storage used by device drivers is never returned +to the free memory pool, Therefore, it is desirable to NEVER +terminate any device that might be used again. Modules contained in +the BOOT tile will NEVER be terminated.</para> +</sect2> +<sect2> +<title>NAME: IRQ SERVICE ROUTINE</title> +<para>FUNCTION: SERVICE DEVICE INTERRUPTS +</para> +<para> +Although this routine is not included in the device drivers +branch table and not called directly from SCFMAN, it is an important +routine in device drivers, The,main things that it does are:</para> +<para>1. Service the device interrupts (recieve data from device or send +data to it), This routine should put its data into and get its data +from buffers which are defined in the device static storage,</para> +<para>2, Wake up any process waiting for I/O to complete by checking +to +see if there is a process ID in V.WAKE (non-zero) and it so +send +a wakeup signal to that process,</para> +<para>3, If the device is ready to send more data and the output buffer +is emoty, disable the device's "ready to transmit" +interrupts,</para> +<para>4, If a pause character is recieved, set V.PAUS in the attached +device static storage to a non-zero value, The address of the +attached device static storage is in V.DEV2,</para> +<para> +When the IRQ service routine finishes servicing an interrupt, +it must clear the carry and exit with an RTS instruction.</para> +</sect2> +</sect1> +</chapter> +<chapter> +<title>ASSEMBLY LANGUAGE PRORAMMING TECHNIQUES</title> +<para>There are four key rules for programmers writing OS-9 assembly +language programs:</para> +<orderedlist numeration="arabic"> + <listitem><para>All programs MUST use position-independent-code (PIC)~. OS9 + selects load addresses based on available memory at run-time, There + is no way to force a program to be loaded at a specific address.</para></listitem> + <listitem><para>All programs must use the standard OS-9 memory module formats + or they cannot be loaded and run, Programs must not use + self-moda~fying code, Programs must not change anything in a memory + module or use any art of ~t for varrables.</para></listitem> + <listitem><para>Storage for all variab e and data structures must be within +a + data area wb~cb is assigned by OS-9 at run-timer and is +separate + from the program memory module~</para></listitem> + <listitem><para>4, All input and output operations should be made using OS-9 + service request calls~</para></listitem> +</orderedlist> +<para>Fortunately~. the 6809's versatile addressing modes make the rules +above easy to follow,, The OS-9 Assembler also helps because it has +special capabilities to assist the programmer in creating programs +and memory modules for the OS-9 execution environment.</para> +<sect1> +<title>HOW TO WRITE POSITION-INDEPENDENT CODE</title> +<para>The 6809 irsstruct~on set was cpttmized to allow efficient use of +Position Independent Code (PIC)~ The basic technique is to always use +PC-relative addressing; for example BRA, LBRA, BSR and L8SR~ Get +addresses of constants and tables using LEA instructions instead of +load immediate instructions, If you use dispatch tables, use tables +of RELATIVE, not absolute, addresses.</para> +<literallayout> +INCORRECT CORRECT + +LDX =CONSTANT LEAX CONSTANT,PCR +JSR SUBR BSR SUBR or LBSR SUER +JMP LABEL SRA LABEL or LBRA LABEL +</literallayout> +</sect1> +<sect1> +<title> +ADDRESSING VARIABLES AND DATA STRUCTURES +</title> +<para>Programs executed as processes (by PORE and CHAIN system calls or +by the ShellI are assigned a RAM memory area for variables, stacks, +and data structures at execution-time, The addresses cannot be +determined or specified ahead of time, However, a minimum size for +this area is specified in the program~s module header, Again, thanks +to the ESOVs full compliment of addressing modes this presents no +problem to the OS-9 programmer</para> +<para>When the program is first entered, the Y register will have the +address of the top of the process~ data memory area, If the creating +process passed a parameter area, it will be located from the value of +the SP to the top of memory (Y)~ and the. U register will contain the +parameter area size in bytes, If the new process was called by the +shell, the parameter area will contain the part of the shell command +line that includes the argument (parameter~ text, The U register will +have the lower bound of the data memory area, and the UP register +will contain its page number</para> +<para>The most important rule is to NOT USE EXTENDED ADDRESSING! Indexed +and direct page addressing should be used exclusively to access data +area values and structures, Do not use program-counter relative +addressing to find addresses in the data area, but do use it to refer +to addresses within the program area</para> +<para>The most efficient way to handle tables, buffers, stacks, etc,, is +to have the program~s initialization routine compute their absolute +addresses using the data area bounds passed by OS-9 in the registers, +These addresses can then be saved in the direct page where they can +be loaded into registers quickly, using short instructions, This +technique has advantages: it is faster than extended addressing, and +the program is inherently reentrant</para> +</sect1> +<sect1> +<title>STACK REQUIREMENTS</title> +<para>Because OS-9 uses interrupts extensively, and also because many +reentrant 6809 programs use the MPU stack for local variable storage, +a generous stack should be maintained at all times,, The recommended +minimum is approximately 200 bytes,</para> +</sect1> +<sect1> +<title>INTERRUPT MASKS</title> +<para>User programs should keep the condition codes re~isrer F (FIRQ +mask) and I (IRQ mask) bits off, They can be set during critical +program sequences to avoid task-switching or interrupts, but this +time should be kept to a minimum, If they are set for longer than a +tick period, system timekeeping accuracy may be affected, Also, some +Level Two systems will abort programs having a set IRQ mask</para> +</sect1> +<sect1> +<title>WRITING INTERRUPT-DRIVEN DEVICE DRIVERS</title> +<para>OS-9 programs do not use interrupts directly, Any interrupt- +driven fLlnction should be implemented as a device driver module +which should handle all interrupt-related functions, When it is +necessary for a program to be synchronized to an interrupt-causing +event, a driver can send a semaphore to a program (or the reverse) +using OS-9's <emphasis>signal</emphasis> facilities.</para> +<para>It is important to understand that interrupt service routines are +asynchronous and somewhat nebulous in that they are not distinct +processes, They are in effect subroutines called by OS-9 when an +interrupt occurs</para> +<para>Therefore, all interrupt-driven device drivers have two basic +parts: the ~mainiine# subroutines that execute as part of the calling +process, and a separate interrupt service routine</para> +<para>THE TwO ROUTINES ARE ASYNCHRONOUS AND THEREFORE MUST USE SIGNALS +FOR COMMUNICATIONS AND COORDINATION.</para> +<para>The INIT initialization subroutine within the driver package +should allocate static storage for the service routine, get the +service routine address, and execute the F$IRQ system call to add it +to the IRQ polling table</para> +<para>When a device driver routine does something that will result in an +interrupt, it should immediately execute a P~SLEP service request, +This results in the process' deactivation, When the interrupt in +question occurs, its service routine is executed after some random +interval, It should then do the minimal amount of processing +required, and send a wwakeup~ signal to its associated process using +the F$SEND service request~ It may also put some data in its static +storage (I/O data and Status) which is shared with its associated +~sleeping~ process~ +</para> +<para>Some time later, the device driver ~inainline~ routine is awakened +by the signal, and can process the data or status returned by the +interrupt service routine.</para> +</sect1> +<sect1> +<title>USING STANDARD I/O PATHS</title> +<para>Programs should be written to use standard I/O paths wherever +practical, Usually, this involves I/O calls that are intended to +communicate to the user's term~nal, or any other case where the OS-9 +redirected I/O capability is desirable,</para> +<para>All three standard I/O paths will already be open when the program +is entered (they are uThsrited from the parent process), Programs +should n~jtt. close these paths except under ~ery special +circumstances,</para> +<para>Standard I/O paths are always assigned path numbers zero, one, and +two, as down below:</para> +<para>Path 0 Standard Input~ Analogcus to the keyboard or other main +data input source.</para> +<para>Path 1 Standard Output, Analoqous to the terminal display or other +main data output deatination +</para> +<para>Path 2 - Standard Error/Status. This path is provided so output +messages which are not part of the actual program output can be kept +separate, Many times paths 1 and 2 will be directed to the same +device. +</para> +</sect1> +<sect1> +<title>A SAMPLE PROCRAM</title> +<para>Tue OS-9 "list" utility command program is shown on this +and the next page as an example of assembly language programming,</para> +<programlisting> +Microware OS-9 Assembler 2,1 01/04/82 23:39:37 Page 001 +LIST - File List Utility + +* LIST UTILITY COMMAND +* Syntax: list <pathname> +* COPIES INPUT FROM SPECIFIED FILE TO STANDARD OLflTUT +0000 870D0048 mod LSTEND,LSTNAM,PRGRM+OBJCT, +REENT+I,,LSTENT, LSTMEM +000D 4C6973F4 LSTNAM fcs ~List~ +* STATIC STORAGE OFFSETS +* +00GB BU7FSIZ equ 200 size of input buffer +0000 ORG U +0000 IPATE rmb 1 input path number +0001 PRMPTR nab 2 parameter pointer +0003 BUFFER rmb BtIFSIZ allocate line buffer +0 003 rmb 200 allocate stack +0193 nab 200 roo for parameter list +0253 LSTXEM EQU +0011 9F01 LSTENT stx PRMPTR save parameter ptr +0013 8601 Ida tREAD, select read access mode +0015 103F84 os9 I$OPEN open input file +0018 252E bce LIST5O exit if error +OOlA 9700 sta IPATH save input path number +OOlC 9F01 stx PRMPTR save updated param ptr +OOIE 9600 LIST2O ida IPATH load input path number +0020 3043 leax BUFFER,U load buffer pointer +0022 lOBEOOc8 ldy #BUFSIZ maximum bytes to read +0026 103FeB os9 t$RDLN read line of input +0029 2509 bce LIST30 exit if error +0023 8601 ida #1 load std, out, path # +002D 103FBC os9 I$WRLN output line +0030 24EC bee LIST2O Repeat if no error +0032 2014 bra LIST5O exit if error +0034 CID3 LIST30 cmpb tE$EOF at end of file? +0036 2610 hue LIST5O branch if not +0038 9600 ida IPATH load input path number +003A 103FBF os9 ~$cLOs close input path +003D 2509 bce LISTSO .,exit if error +003F 9EOl idx PRMPTR restore parameter ptr +0041 A684 ida 0,X +0043 810D cmpa t~0D End of parameter line? +0045 26CA hue LSTENT .~no; list next file +0047 SF clrb +0048 103F06 LIST5O os9 F$EXIT ,,, terminate +0043 953358 emod Module CRC +004E LSTEND EQU * +</programlisting> +</sect1> +</chapter> +<chapter> +<title>ADAPTING OS-9 TO A NEW SYSTEM</title> +<para>Thanks to OS-9's modular structure, it is easily portable to +almost any 6809-based computer, and in fact it has been installed on +an incredible variety of hardware, Usually only device driver and +device descriptor modules need by rewritten or modified for the +target system's specific hardware devices, The larger and more +complex kernel and fi1e~manager modules almost never need adaptation</para> +<para>One essential point is that you will need a functional OS-9 +development system to use during installation of OS-9 on a new target +system. Although it is possible to use a non-OS-9 system, or if you +are truly masochistic, the target system itself, lack of facilities +to generate and test memory modules and create system disks can make +an otherwise straightforward job a time- consuming headache that is +seldom less costly than a commercial OS-9-equipped computer, Over a +dozen manufacturers offer OS-9 based development systems in all price +ranges with an excellent Selection of time-saving options such as +hard disks, line printers, PROM programmers, etc</para> +<para>Microware sells source code for standard I/O drivers, and a "User +Source Code Package" (On OS-9 format disk only) which contains +source code to the Kernel, Shell, INIT, SYSGO, device driver and +descriptor modules, and & selection of utility commands which can +be useful when moving OS-9 to a new target system</para> +<para>WARNING: Standard OS-9 software packages are licensed for use on a +single system, OS-9 cannot be resold or otherwise distributed (even +if modified) without a license,, Contact Microware for information +regarding software licenses</para> +<sect1> +<title>ADAPTING OS-9 TO DISK-BASED SYSTEMS</title> +<para>Usually, most of the work in moving OS-9 to a disk-based target +system is writing a device driver module for the target system~s disk +controller, Part of this task involves producing a subset of the +driver (mostly disk rea~ functions) for use as a bootstrap module</para> +<para>Ii terminal and/or parallel I/O for terminals, printers, etc., +will use ACIA and/or PIA-type devices, the standard ACIA and PIA +device driver modules may he used, or device drivers ci your own +design may be used in place of or in addition to these standard +modules Device descriptor modules may also require adaptation to +match device addresses and initialization required by the target +System</para> +<para>A CLOcK module may be adapted from a standard version, or a new +one may be created, All other component modules, such as IOMAN, +R~BFMAN, SCFMAN, SHELL, and utilities seldom require modification</para> +</sect1> +<sect1> +<title>USING OS-9 IN ROM-BASED SYSTEMS</title> +<para>One of OS-9's major features is its ability to reside in ROM +memory and work effectively with ROMed applications programs written +in assembler or high-level languages such as Basic09, Pascal, and C.</para> +<para>All the component modules of OS-9 (including all commands and +utilities) are directly ROMable without modification. In some cases, +particularly when the~ target system is to automatically execute an +application program upon system start-up, it may be necessary to +reassemble the two modules used during system startup, INIT and SYSGO</para> +<para>The first step in designing a ROM-based system is to select which +OS-9 modules to include in ROM, The following checklist is designed +to help you do so:</para> +<orderedlist numeration="Loweralpha"> + <listitem><para>Include OS9P1, OS9P2, SYSGO, and INIT. These modules are + required in any OS-9 system.</para></listitem> + <listitem><para>If the target system is perform any I/O or interrupt + functions include IOMAN.</para></listitem> + <listitem><para>If the target system is to perform I/O to character-oriented + I/O devices using ACIAs, PIAs, eta,,, include SCFM~AN, required + device drivers (such as ACIA and PIA, and/or your own), and device + descriptors as needed (such as TERM, TI, 1?, and/or your own),, If + device addresses and/or initialization functions need to be changed, + the device descriptor modules must be modified before being ROMed.</para></listitem> + <listitem><para>Ii the target system is to perform disk I/O, include RBFMAN, + and appropriate disk driver and device descriptor modules, As in (c) + above, change device addresses and initialization if needed, ii + RBFMAN ~JJJ, n~,t. be included, the INIT and SYSGO modules ~ be + altered to remove references to disk tiles.</para></listitem> + <listitem><para>Ii the target system requires multiprogramming, time-cf-day,~ + or other time-related functions, include a CLOCK module for the + target system's real-time clock, Also consider how the clock is to + be started,, You may want to ROM the "Setime" command, or + have SYSGQ start the clock.</para></listitem> + <listitem><para>It tne target system will receive commands manually, or if + any application program uses Shell functions, include the SHELL and + SYSGO modules, otherwise include a modified SYSGO module which calls + your application program instead of Shell.</para></listitem> +</orderedlist> +</sect1> +<sect1> +<title>ADAPTING THE INITIALIZATION MODULE</title> +<para>INIT is a module that contains system startup parameters. It ~J be +in ROM in any OS-9 system (it usually resides in the same ROM as the +kernel), It is a non-executable module named ~INIT~ and has type +~system (code $C). It is scanned once during the system startup, It +begins with the standard header followed by:</para> +<para> +MODULE OFFSET</para> +<para>$9,$A,$B This location contains an upper limit RAM memory address +used to override OS-9's automatic end-of- RAM search so that memory +may be reserved for I/O device addresses or other special purposes. +</para> +<para>Number of entries to create in the IRQ polling table. One entry is +required for each interrupt- generating device control register, +</para> +<para>Number of entries to create in the system device table, One entry +is required for each device in the system. +</para> +<para>$E,$F Offset to a string which is the name of the first module to +be executed after startup, usually "SYSG0", There must +always be a startup module. +$10,$11 Offset to the default +directory name string (normally /D0), This device is assumed when +device names are omitted from pathlists, If the system will not use +disks (e.g., RBFMAN will not be used) this offset <emphasis>must</emphasis>be +zero, +$12,$13 Offset to the initial standard path string +(typically /TERM). This path is opened as the standard paths for the +initial startup module. This offset <emphasis>must</emphasis> contain zero if there +is none.</para> +<para>$14,$15 Offset to bootstrap module name string, If OS-9 does not +find IOMAN in ROM during the start-up module search, it will execute +the bootstrap module named to load additional modules from a iLls on +a mass-storage device.</para> +<para>$16 to N All name strings referred to above go here, Each must +have the sign bit (bit 7) of the last character set.</para> +</sect1> +<sect1> +<title>ADAPTING THE SYSGQ MODULE</title> +<para>SYSGO is a program which is the first process started after the +system start-up sequence, Its function is threefold:</para> +<para>* It does additional high-level system initialization, for +example, disk system SYSGO call the shell to process the "Startup" +shell procedure file,</para> +<para>* It starts the first userw prDcess,</para> +<para>* It thereafter remains in a waite state as insurance against all +user processes terminating, thus leaving the system halted, If this +happens, SYSGO can restart the first user program.</para> +<para>The standard SYSGO module for disk systems cannot be used on +non-disk based systems unless it is modified to:</para> +<para>1. Remove initialization of the working execution directory,</para> +<para>2. Remove processing of the wStartupu procedure file.</para> +<para>3. Possibly change the name of the first user program from Shell +to the name of a applications program, Here are some example name +strings:</para> +<para>fcs /userpqm/ (object code module "userpgm")</para> +<para>fcs /RunB userpgm/ (compiled Basie09 program using RunB +run-time-only system)</para> +<para>fcs /Basico9 userpgm/ (compiled Basic09 program using Basic09) +</para> +</sect1> +</chapter> +<chapter> +<title>OS-9 SERVICE REQUEST DESCRIPTIONS</title> +<para>System calls are used to communicate between the OS-9 operating +system and assembly-language-level programs~ There are three general +categories:</para> +<para>1. User mode function requests +2. System mode function +requests +3. I/O requests +</para> +<para>System mode function reqests are privileged and may be executed +only while OS-9 is in the system state (when it is processinq another +service request, executing a file manager, device driversr etc.). +They are included in this manual primarily for the benefit of those +programmers who will be writing device drivers and other system-level +applications.</para> +<para>The system calls are performed by loading the MPU registers with +the appropriate parameters (if any), &nd executing a ~I2 +instruction immediately followed by a constant byte which is the +request code~ Parameters (if any) will be returned in the MPU +registers after OS-9 has processed the service request~ A standard +convention for reporting errors is used in all system calls~ if an +error occurred, the ~C bite of the condition code register will be +set and accumulator B will contain the appropriate error code~ This +permits a BUS or 9CC instruction immediately following the system +call to branch on error/no error~</para> +<para>9ere an e pie system call for the ~ULOSE~ service request:</para> +<para>LDA PATHNUM +SWI2 +FCB $8B +BCS ERROR +</para> +<para> +Using the assembler~s ~OS9~ directive simplifies the call:</para> +<para> +LDA PATHNUM +OS9 I$CLOS +BCS ERROR +</para> +<para>The I/O service requests are simpler to use than in many other +operating systems because the calling program does not have to +allocate and set up "file control blocks", "sector +buffers", etc. Instead OS-9 will return a one byte path number +when a path to a file/device is opened or created; then this path +number may be used in subsequent I/O re uests to identify the +file/device until the path is closed. OS-9 internally allocates and +maintains its +own data structures and users never have to deal +with them: in fact attempts to do so are memory violations.</para> +<para>All system calls have a mnemonic name that starts with "F$" +for system functions, or "I$" for I/O related requests. +These are defined in the assembler-input equate file called "OS9DEFS"</para> +<para>In the service request descriptions which follow, registers not +explicitly specified as input or output parameters are not altered. +Strings passed as parameters are normally terminated by having bit +seven of the last character set, a space character, or an end of line +cbaracter.</para> +<sect1> +<title>ABIT Set bits in an allocation bit map F$ABIT</title> +<para>ASSEMBLER CALL: OS9 F$ABIT +</para> +<para>MACHINE CODE: 103F 13</para> +<para>INPUT: (X) - Base address of glocation bit map. +(D) m Bit +number of first bit to set, +(Y) m Bit count (number of bits to +set) +</para> +<para>OUTPUT: None.</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>This system mode service request sets bits in the allocation bit +map specified by the X register~.</para> +<para>Bit numbers range from 0.,N-1, where N is the number of bits in +the allocation bit map,</para> +</sect1> +<sect1> +<title>CHAIN Load and execute a new primary module, F$CHAN</title> +<para>ASSEMBLER CALL: OS9 F$CHAN +</para> +<para>MACHINE CODE: 103F 05</para> +<para>INPUT: (X) - Address of module name or file name</para> +<para>(Y) = Parameter area sime (25~ byte pages)</para> +<para>(U) = Beginning address of parameter area</para> +<para>(A) - Lanquage / type code</para> +<para>(B) = Optional data area size (256 byte pages)</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>This system call is similar to FORR, but it does not create a new +process, It effectively uresets~ the calling process' program and +data memory areas and begins execution of a new primary module, Open +paths are not closed or otherwise affected</para> +<para>This system call is used when it is necessary to execute an +entirely new program, but without the overhead of creating a new +process, It is functionally similar to a FORK followed by an EXIT. +but with 1es~ processing overhe&d</para> +<para>The sequence of operations taken by CHAIN is as follows: +</para> +<para>1, The system parses the name string ot the new proces& +~priinary module~ - the program that will initially be executed, Then +the system module directory is searched to see if a module with the +same name and type / language is already in memory, If so ~c is +linked to, If not, the name string is used as the pathlist of a file +which is to be loaded into memory. Then the first module in this file +is linked to (several modules may have been loaded from a single +file)</para> +<para>2. The process' old primary module is UNLINKED</para> +<para>3. The data memory area is reconfigured to the size specified in +the new primary module's header</para> +<para>The diagram below shows bow CHAIN sets up the data memory area and +registers for the new module, ++-----------------+ <-- Y +(highest address) +I Parameter I +Area I +1 1 +Data Area I +I +I +I I</para> +<para>- + +I Direct Page 3 ++ <- U, DP (lowest address)</para> +<para> +O = parameter area size +PC = module entry point abs. +address +CC - F-C, I-C, others undefined</para> +<para>? (top of memory pointer) and U (bottom of memory pointer) will +always have a values at 256-byte page boundaries, If the parent does +not specify a parameter area, Y, X, and SP will be the same, and D +will aqua]. zero, The minimum overall data area size is one pa (2 6 +bytes),</para> +<para> +WARNING: The hardware stack pointer (SP) should be located +somewhere in the direct page before the F$CHAN service request is +executed to prevent a ~suicide attempts error or an actual suicide +(system crash), This will prevent a suicide from occurring in case +the new module requires a smaller data area than what is currently +being used. You should allow approximately 200 bytes of stack space +for execution of the F$CHAN service request and other system +woverhead~,</para> +<para> +For more information, please see the F$FORK service request +description,</para> +</sect1> +<sect1> +<title>COMPARE NAMES Compare two names, F$CNAM</title> +<para>ASSEMBLER CALL: OS9 F$CNAM +</para> +<para>MACHINE CODE: 103F 11 +</para> +<para>INPUT: (X) - Address of first name, +(B) =Length of first +name, +(Y) = Address of secorrd name,</para> +<para>OUTPUT: (CC) = C bit clear if the strings match,</para> +<para> +Given the address and length of a string, and the address of +a +second string, compares them and indicates whether they +match, +Typically used in conjunction with wparsename ~</para> +<para>The second name must bave the sign bit (bit 7) of the last +character set,</para> +</sect1> +<sect1> +<title>CRC ~. Compute CRC</title> +<para>ASSEMBLER CALL: OS9 F$CRC +</para> +<para>MACHINE CODE: 103F 17 +</para> +<para>INPUT: (X) m Starting byte address, +(Y) - Byte count, +(U) = +Address of 3 byte CRC accumulator.</para> +<para>OUTPUT: CRC accumulator is updated</para> +<para>ERROR OUTPUT: None</para> +<para>This service request calculates the CRC (cyclic redundancy count) +for use by compilers, assemblers, or other module generators, The CRC +is calculated starting at the source address over Wbyte Countu bytes, +it is not necessary to cover an entire module in one call, since the +CRC may be accumulated~ over several calls, The CRC accumulator can +be any three byte memory location and must be initialized to $FFFFFF +before the first F$CRC call</para> +<para>The last three bytes in the module (where the three CRC bytes will +be stored) are not included in the CRC generation</para> +</sect1> +<sect1> +<title>DBIT Deallocate in a bit map F$DBIT</title> +<para>ASSEMBLER CALL: OS9 F$DBIT +</para> +<para>MACHINE CODE: 103F 14 +</para> +<para>INPUT: (X) = B e address of an allocation bit map. +(D} - Bit +number of firs bit to clear, +(Y) - Bit count (number ~f bits to +clear), +</para> +<para>OUTPUT: None, +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>This system mode service request is used to clear bits in the +allocation bit map pointed to by X.</para> +<para>Bit numbers range from 0,,N-l, where N is the number of bits in +the allocation bit map,</para> +</sect1> +<sect1> +<title>EXIT Terminate the calling process. F$EXIT</title> +<para>ASSEMBLER CALL: OS9 F$EXIT +</para> +<para>MACHINE CODE: 103F 06 +</para> +<para>INPUT: (B) = Status code to be returned to the parent process</para> +<para>OUTPUT: Process is terminated.</para> +<para>This call kills the calling process and is the only means oy whicn +a process can terminate itself, Its data memory area is deallocated, +and its primary module is UNLINKed, All open paths are automatically +closed</para> +<para>The death of the process can be detected by the parent executing a +WAIT call, which returns to the parent the status byte passed by the +child in its EXIT call, The status byte can be an OS-9 error code the +terminating process wishes to pass back to its parent process (the +shell assumes this), or can be used to pass a user- defined status +value, Processes to be called directly by the shell should only +return an OS-9 error code or zero if no error occutred</para> +</sect1> +<sect1> +<title>FORK Create a new process. F$FORK</title> +<para>ASSEMBLER CALL: OS9 F$FORK +</para> +<para>MACHINE CODE: 103F 03 +</para> +<para>INPUT: (X) ? Addre s o module name or file name. +(Y) - +Parameter area size. +(U) - Beginning address of the parameter +area. +(A) = Language / Type code, +(B) = Optional data area size +(pages).</para> +<para>OUTPUT: (X) = Updated path the name string. +(A) - New process +ID number,</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>This system call creates a new process which becomes a ~~childa of +the caller, and sets up the new process' memory and MPU registers</para> +<para>The system parses the name string of the new process' "primary +module" - the program that will initially be executed, Then the +system module directory is searched to see if the program is already +in memory. If so, the module is linked to and executed, If not, the +name string is used as the pathlist of the file which is to b oaded +into memory. Then the first module in this file is linked to and +executed (several modules may have been loaded from a single file)</para> +<para>The primary module's module header is used to determine the +process' initial data area size, OS-9 then attempts to allocate a +contiguous RAM area equal tQ the required data storage size, +(includes the parameter passing area, which is copied from the parent +process' data area), The new process' registers are set up as shown +in the diagram on the next page, The execution offset given in the +module header is used to set the PC to the module's entry point</para> +<para>When the shell processes a command line it passes a string in the +parameter area which is a copy of the parameter part (if any) of the +command line. It also inserts an end-of-line character at the end of +the parameter string to simplify string-oriented processing. The X +register will point to the beginning of the parameter string. If the +command line included the optional memory size specification (In or +InK), the shell will pass that size as the requested memory size when +executing the FORK</para> +<para>If any of the above operations are unsuccessful, the FORK is +</para> +<para>aborted and the caller is returned an error, The diagram below +shows bow FORK sets up the data memory area and registers for a +newly-created process,</para> +<para>+ <-- Y (highest address) +</para> +<para>parameter +area ++ - -+ (-ax, SP +I I</para> +<para>data area +I I</para> +<para>direct page +4-, ------- -+ (-- U, DF (lowest address)</para> +<para>O - parameter area size +PC = module entry point abs. +address +CC - F-C, 1-0, others undefined</para> +<para>y (top of memory pointer) and U (bottom of memory pointer) will +always have a values at 256-byte page boundaries, If the parent does +not specify a parameter area, Y, X, and SP wi I b t e same, and 0 +will equal zero, The minimum overall data area size is one page (256 +bytes). Shell will always pass at least an end of line character in +the parameter area, +NOTE: Both the child and parent process will +execute +concurrently. If the parent executes a F$WAIT call +immediately after the fork, it will wait until the child dies before +it resumes execution, Caution should be exercised when recursively +calling a program that uses the F$FORK service request since another +child may be created with each "incarnation", This will +continue until the process table becomes full.</para> +</sect1> +<sect1> +<title>INTERCEPT Set up a signal intercept trap. F$ICFT</title> +<para>ASSEMBLER CALL: OS9 F$ICPT +</para> +<para>MACHINE CODE. 103F 09 +</para> +<para>INPUT: (X) = Address of the intercept routine. +(U) - Address of +the intercept routine local storage. +OUTPUT: None.</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>This system call tells OS-9 to set a signal intercept trap, where +X contains the address of the signal handler routine, and U contains +the base address of the routine's storage area, After a signal trap +has been set, whenever the process receives a signal, its intercept +routine will be executed. A signal will abort any process which has +not used the F$ICPT service request to set a signal trap, and its +termination status (B register) will be the signal óode, Many +interactive programs will set up an intercept routine to handle +keyboard abort (control 0), and keyboard interrupt (control C)</para> +<para>The intercept routine is entered asynchronously because a signal +may be sent at any time (it is like an interrupt) and is passed the +following: +</para> +<para>U = Address of intercept routine local storage</para> +<para>B - Signal code</para> +<para>NOTE: The value of PP may not be the same as it was when the +F$ICFT call was made</para> +<para>Whenever a signal is received, OS-9 will pass the signal code and +the base address of its data area (which was defined by a F$ICPT +service request) to the signal intercept routine. The base address of +the data area is selected by the user and is typically a pointer to +the process' data area</para> +<para>The intercept routine is activated when a signal is received, then +it takes some action based upon the value of the signal code such as +setting a flag in the process' data area. After the signal has been +processed, the handler routine should terminate with an RTI +instruction</para> +</sect1> +<sect1> +<title>GET ID Get process ID / user ID</title> +<para>ASSEMBLER CALL: OS9 F$ID</para> +<para>MACHINE CODE: 103F DC +</para> +<para>INPUT: None +</para> +<para>OUTPUT:(A) - Process ID.</para> +<para>(Y) " User ID. +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>Returns the caller's process ID number, which is a byte value in +the range of 1 to 255, and the user ID which is a integer in the +range 0 to 6553$. The process ID is assigned by OS-9 and is unique to +the process, The user ID is defined in the system password file, and +is used by the file security system and a few other functions, +Several processes can have the same user ID,</para> +</sect1> +<sect1> +<title>LINK: Link to memory module. F $LINK</title> +<para>ASSEMBLER CALL: OS9 F$LINK</para> +<para>MACHINE CODE: 103F 00</para> +<para>INPUT: (X) - Address of the module name string. +(A) - Module +type / language byte.</para> +<para>OUTPUT:(X) = Advanced past the module name, +(Y) = Module entry +point absolute address. +(U) - Module header absolute address. +(A) +- Module type / language. +(B) - Module attributes / revision +level.</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>This system call causes 08-9 to search the module directory for a +module having a name, language and type as given in the parameters. +If found, the address of the module's header is returned in U, and +the absolute address of the module's execution entry point is +returned in Y (as a convenience: this and other information can be +obtained from the module header). The module's link count' is +incremented whenever a LINK references its name, thus keeping track +of how many processes are using the module, If the module requested +has an attribute byte indicating it is not sharable (meaning it is +not reentrant) only one process may link to it at a time</para> +<para>Possible errors: +</para> +<para>(A) Module not found</para> +<para>(B) Module busy (not sha:able and in uae)</para> +<para>(C) Incorrect or defective module header</para> +</sect1> +<sect1> +<title>LOAD Load module(s) from a file, F$LOAD</title> +<para>ASSEMBLER CALL: OS9 F$LOAD</para> +<para>MACHINE CODE: 103F Dl</para> +<para>INPUT: (X) = Address of pathlist (file name) +(A) = Language / +type (0 = any language / type) +</para> +<para>OUTPUT:(X) - Advanced past pathlist +(Y) - Primary module entry +point address +(U) - Address of module header +(A; - Language / +type +(B) - Attributes / revision level +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>Opens a file specified by the pathlist, reads one or more memory +modules from the file into memory, then closes the file. All modules +~1oaded are added to the system module directory, and the first +module read is LINKed~ The parameters returned are the, same as the +LINK call and apply only to the first module loaded.</para> +<para>In order to be loaded, the file must have the "execute" +permission and contain a module or modules that have a proper module +header. The file will be loaded from the working execution directory +unless a complete pathlist is given.</para> +<para>Possible errors: module directory full; memory full; plus errors +that occur on OPEN, READ, CLOSE and LINK system calls,</para> +</sect1> +<sect1> +<title>MEM Resize data memory area, F$MEM</title> +<para>ASSEMBLER CALL: OS9 F$MEM +</para> +<para>MACHINE CODE: 103F 07 +</para> +<para>INPUT: (0) - Desired new memory area size in bytes</para> +<para>OUTPUT: (P) = Address of new memory area upper bound</para> +<para>(D) - Actual new memory .area size in bytes</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>Used to expand or contract the process' data memory area, The new +size requested is rounded up to the next 256-byte page boundary. +Additional memory is allocated contiguously u~ard (towards higher +addresses), or deallocated downward from the old highest address. If +0 " 0, then the current upper bound and size will be returned</para> +<para>This request can never return all of a process' memory, or the +page in which its SP register points to</para> +<para>In Level One systems, the request may return an error upon an +expansion request even though adequate free memory exists. This is +because the data area is always made contiguous, and memory requests +by other processes may fragment free memory into smaller, scattered +blocks that are not adjacent to the caller's present data area. Level +Two systems do not have this restriction because of the availability +of hardware for memory relocation, and because each process has its +own "address space"</para> +</sect1> +<sect1> +<title>PRERR Print error message. F$PERR</title> +<para>ASSEMBLER CALL: OS9 F$PERR +</para> +<para>MACHINE CODE: 103F 0F +</para> +<para>INPUT: (A) = Output path number,</para> +<para>(B) = Error code, +</para> +<para>OUTPUT: None,</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>This is the system's error reporting utility. It writes an error +message to the output path specified, Most OS-9 systems will display:</para> +<para>ERROR I(decimal number> +</para> +<para>by default. The error reporting routine is vectored and can be +replaced with a more elaborate reporting module, To replace this +routine use the F$SSVC service request</para> +</sect1> +<sect1> +<title>PARSENAME Parse a path name, F$PNAM</title> +<para>ASSEMBLER CALL: OS9 F$PNAM +</para> +<para>MACHINE CODE: 103F 10 +</para> +<para>INPUT: (X) = Address of the pathlist</para> +<para>OUTPUT: (X) - Updated past the optional / +</para> +<para>(Y) - Address of the 14st character of the name + 1~ +</para> +<para>(B) - Length of the name</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>(X) - Updated past space characters. + + + +</para> +<para>Parses the input text string for a legal OS-9 name, The name is +terminated by any character that is not a legal component character, +This system call is useful for processing pathlist arguments passed +to new processes. Also if X was at the end of a pathlist, a bad name +error will be returned and X will be moved past any space characters +so that the next pathlist in a command line may be parsed</para> +<para>Note that this system call processes only one name, so several +calls may be needed to process a pathlist that has more than one name</para> +<para>BEFORE F$PNAM CALL; +</para> +<para>£ I + + + +</para> +<para>X +</para> +<para>AFTER THE F$PNAM GALL: +</para> +<para>£/IDIOI/IFIIILIEI I I £ I +X Y (B)a2</para> +</sect1> +<sect1> +<title>SBMAP Search bit map for a free area F$SBIT</title> +<para> +ASSEMBLER CALL: OS9 F$SBIT + + + +</para> +<para>MACHINE CODE: 103F 12</para> +<para>INPUT: (X) - Beginning address of a bit map. +(0) - Beginning +bit number. +(Y) = Bit count (free bit block size). +(U) = End of +bit map address,</para> +<para>OUTPUT: (D) - Beginning bit number. +(Y) - Bit count,</para> +<para>This system mode service request searches the specified allocation +bit map starting at the "beginning bit number" for a free +block (cleared bits) of the required length.</para> +<para>If no b o k of the specified size exists, it returns with the +carry set, beginning bit number and size of the largest block.</para> +</sect1> +<sect1> +<title>SEND Send a signal to another process, F$SEND</title> +<para>ASSEMBLER CALL: OS9 F$SEND +</para> +<para>MACHINE CODE: 103F 08 +</para> +<para>INPUT: (A) = Receiver's process ID number + (B) = Signal code</para> +<para>OUTPUT: None</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>This system call sends a "signal" to the process +specified. The sianajL code is a single byte value of 1 - 255</para> +<para>If the signal's destination process is sleeping or waiting, it +will be activated so that it may process the signal. The signal +processing routine (intercept) will be executed if a signal trap was +set up (see F$ICPT), otherwise the signal will abort the destination +process, and the signal code becomes the exit status (see WAIT), An +exception is the WAKEUP signal, which activates a sleeping process +but does not cause the signal intercept routine to be executed</para> +<para>Some of the signal codes have meanings defined by convention: +</para> +<para>0 a System Abort (cannot be intercepted) +</para> +<para>I - Wake Up Process +</para> +<para>2 - Keyboard Abort +</para> +<para>3 = Keyboard Interrupt +</para> +<para>4-255 = user defined +</para> +<para>If an attempt is made to send a signal to a process that has an +unprocessed, previous signal pending, the current "send" +request will be cancelled and an error will be returned. An attempt +can be made to re-send the signal later, It is good practice to issue +a "sleep" call for a few ticks before a retry to avoid +wasting NPU time</para> +<para>For related information see the F$ICPT, F$WAIT. and F$SLEP service +request descriptions</para> +</sect1> +<sect1> +<title>SLEEP Put calling process to sleep. F$SLEP</title> +<para>ASSEMBLER CALL: OS9 F$SLEP</para> +<para>MACHINE CODE: 103F 0A</para> +<para>INPUT: (X) = Sleep time in ticks (0 a indefinitely) +</para> +<para>OUTPUT: (X) = Decremented by the number of ticks that the process +was asleep</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>Ibis call deactivates the calling process for a specified time, or +indefinitely if K - 0, If X = 1, the effect is to have the caller +give up its current time slice, The process will be activated before +the full time interval if a signal is received, therefore sleeping +indefinitely is a good way to wait for a signal or interrupt without +wasting CPU time</para> +<para>The duration of a tiek is system dependent but is wost commonly +100 milliseconds</para> +<para>Due to the fact that it is not known when the F$SLEP request was +made during the current tick, F$SLEP can not be used for precise +timing, A sleep of one tick is effectively a "give up remaining +time slice" request; the process is immediately inserted into +the active process queue and will resume execution when it reaches +the front of the queue, A sleep of two or more ticks causes the +process to be inserted into the active process queue after N-l ticks +occur and will resume execution when it reaches the front of the +queue</para> +</sect1> +<sect1> +<title>SETPR Set process priority. F$SPRI</title> +<para>ASSEMBLER CALL: OS9 F$SPRI</para> +<para>MACHINE CODE: 103F 00</para> +<para>INPUT: (A) = Process ID number, +(B) = Priority: +0 = +lowest +255 - highest</para> +<para>OUTPUT: None.</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>Changes the process' priority to the new value given. $FF is the +highest possible priority, $00 is the lowest. A process can change +another process' priority only if it has the same user ID.</para> +</sect1> +<sect1> +<title>SSVC Install function request F$SSVC</title> +<para>ASSEMBLER CALL: OS9 F$SSVC +</para> +<para>MACHINE CODE: 103F 32</para> +<para>INPUT: (Y) - Address of service request initialization table,</para> +<para>OUTPUT: None.</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>This system mode service request is used to add a new function +request to OS-9's user and privileged system service request tables, +or to replace an old one, The Y register passes the address of a +table which contains the function codes and offsets to the +corresponding service request handler routines. This table has the +following format:</para> +<para>OFFSET</para> +<para>4... +$00 1 Function Code £ (--- First entry +4.... +,.,e,, - r~, +$01 I Offset From Byte 3 £ +4.,... +$02 I +To Function Handler 1 +4-, +$03 I Function Code 1 <--a Second +entry +$04 I ofrset From Byte E £ +4.-.,</para> +<para>I To Function Handler I +</para> +<para>I (--- Third entry etc. +I MORE ENTRIES £ +I I +I +I +$80 I <--- End of table mark</para> +<para>NOTE: If the sign bit of the function code is set, on y the system +table will be updated. Otherwise both the system and user tables will +be updated. Privileged system service requests may be called only +while executing a system routine. +The service request handler +routine should process the service request and return from subroutine +with an RTS instruction, They may alter all MPU registers (except for +SP), The U register will pass the address of the register stack to +the service request handler as shown in the following diagram: +OFFSET +OSHDEFS +MNEMONIC +U---> I CC I $0 R$CC ++ ~ + $1 R$D +I A +I $1 R$A +I B I $2 R$B + +I DP I $3 R$DP +X I $4 R$X +- a +a am - - - - m~* + +Y I $6 R$Y +------- -"4. +U £ +$8 R$tY +4-.. +PC I $A R$PC +.-..m4 +</para> +<para> + + +</para> +<para>Function request codes are broken into the two cateqor±es +as Shown below:</para> +<para>$00 - $2? User mode service request codes, +$29 $34 Privileged +system mode service request codes, +When installing these service +request, the +sign bit should be set if it is to be placed +into +the system table only,</para> +<para> +NOTE: These categories are defined by convention and not +enforced by OS9,</para> +<para> +Codes $25.,$27, and S70..$7F will not be used by MICROWARE and +are free for user definition.</para> +</sect1> +<sect1> +<title>SETSWI Set SWI vector, F$SSWI</title> +<para>ASSEMBLER CALL: OS9 F$SSWI</para> +<para>MACHINE CODE: 103F QE</para> +<para>INPUT: (A) = SWI type code,</para> +<para>(X) = Address of user SWI service routine. +</para> +<para>OUTPUT: None</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>Sets up the interrupt vectors for SWI, ~I2 and SWI3 instructions. +Each process has its own local vectors, Each SETSWI call sets up one +type of vector according to the code number passed in A.</para> +<para>1 - SWI +2 - SWI2 +3 - ~4I3 +</para> +<para>When a process is created, all three vectors are initialized with +the address of the OS-9 service call processor.</para> +<para>WARNING: Microware-supplied software uses SWI2 to call OS-9. If +you reset this vector these programs will not work, If you chance all +three vectors, you will not be able to call OS-9 at all.</para> +</sect1> +<sect1> +<title>SETIME Set system date and time, F$STIM</title> +<para>ASSEMBLER CALL: OS9 F$STIM</para> +<para>MACHINE CODE: 103F 16 +</para> +<para>INPUT: (K) = Address of time packet (see below)</para> +<para>OUTPUT: Time/date is set,</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>This service request is used to set the current system date/time +and start the system real-time clock, The date and time are passed in +a time packet as follows: +OFFSET VALUE</para> +<para>0 £year +1 I month +2 Iday +3 1 hours +4 £ +minutes +5 1 seconds +</para> +</sect1> +<sect1> +<title>TIME Get system date and time, F$TIRE</title> +<para>ASSEMBLER CALL: OS9 F$TIME +</para> +<para>MACHINE CODE: 103F 15</para> +<para>INPUT: (KY - Address of place to store the time packet.</para> +<para>OUTPUT: Time packet (see below), +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>Thx~ returns the current system date and time in the form of a six +byte packet (in binary), The packet is copied to the address passed +in X, The packet looks like: +OFFSET VALUE + +0 I year +1 1 +month +2 1 day +3 1 hours +4 1 minutes +5 1 seconds</para> +</sect1> +<sect1> +<title>UNLINK Unlink a module, F$UNLK</title> +<para>ASSEMBLER CALL: OS9 F$UNLK +</para> +<para>MACHINE CODE: 103F 02 +</para> +<para>INPUT: (U) = Address of the module header</para> +<para>OUTPUT: None +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>Tells OS-9 that the module is no longer needed by the calling +process. The module's link count is decremented, and the module is +destroyed and its memory deallocated when the link count equals zero, +The module will not be destroyed if in use by any other process(es) +because its link count will be non-zero. In Level Two systems, the +module is usually switched out of the process' address space</para> +<para>oevice driver modules in use or certain system modules cannot he +unlinked, HOMed iodules can be unlinked but cannot be deleted from +the module directory</para> +</sect1> +<sect1> +<title>WAIT Wait for child process to die, F$WAIT</title> +<para>ASSEMBLER CALL: OS9 F$WAIT +</para> +<para>MACHINE CODE: 103F 04 +</para> +<para>INPUT: None +</para> +<para>OUTPUT: (A) = Deceased child process' process ID</para> +<para>(B) = Child process' exit status code</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>The calling process is deactivated until a child process +terminates by executing an EXIT system call, or by receiving a +signal, The child's ID number and exit status is returned to the +parent. If the child died due to a signal, the exit status byte (B +register) is the signal code</para> +<para>If the caller has several children, the caller is activated when +the fir~t one dies, so one WAIT system call is required to detect +termination of each child</para> +<para>If a child died before the WAIT call, the caller is reactivated +almost immediately. WAIT will return an error if the caller has no +children</para> +<para>See the EXIT description for more related information</para> +</sect1> +<sect1> +<title>A64 Allocate a 64 byte memory block F$A64</title> +<para>ASSEMBLER CALL: OS9 F$A64 +</para> +<para>MACHINE CODE: 103F 30 +</para> +<para>INPUT: (X) = Base address of page table (zero if the page table +has not yet been allocated)</para> +<para>OUTPUT: (X) Block number</para> +<para>(N) = Base address of page table</para> +<para>(Y) = Address of block</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>This system mode service request is used to dynamically allocate +64 byte blocks of memory by splitting whole pages (256 byte) into +tour sections. The first 64 bytes of the base page are used as a +"page table", which contains the MSB of all pages in the +memory structure, Passing a value of zero in the N register will +cause the F$A64 service request to allocate a new base page and the +first 64 byte memory block, Whenever a new page is needed, an F$SRQM +service request will automatically be, executed, The first byte of +each block contains the block number; routines using this service +request should not alter it. Below is a diagram to show how 7 blocks +might be allocated: +</para> +<para>ANY 256 BYTE ANY 256 BYTE +MEMORY PAGE MEMORY PAGE +BASE PAGE + +I S K +I PAGETABLE I BLOCK 4 1 +1 (64 bytes) I (64 bytes) +S + +IX LX +I BLOCK1 I S BLOCKS £ +(64 bytes) I I (64 +bytes) S + +IX IX I +1 BLOCK2 I S BLOCKE I +1 (64 byte) I 1 +(64 byte) +a., m4, 4- ..,*.a,,m + +IX £ IX 1 +I BLOCK3 I +BLOCK? I +£ (64 byte) £ 1 (64 byte) £ +4--a + +4.-mm +</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST +</para> +</sect1> +<sect1> +<title>APRC Insert process in active process queue F$APRC</title> +<para>ASSEMBLER CALL: OS9 F$APRC +</para> +<para>MACHINE CODE: 103F 2C +</para> +<para>INPUT: (N) - Address of process descriptor</para> +<para>OUTPUT: None</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>Tbie system mode service request inserts a process into the active +process queue so that it may be scheduled for execution</para> +<para>All processes already in the active process queue are aged, and +the age of the specified process is set to its priority If the +process is in system state, it is inserted after any other process~s +also in system state, but before any process in user state. If the +process is in user state, it is inserted according to its age</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>FIND-64 Find a 64 byte memory block F$F64</title> +<para>ASSEMBLER CALL: OS9 F$F64</para> +<para>MACHINE CODE: 103F 2F +</para> +<para>INPUT: (K) = Add ess o base page, (A) - Block number, +</para> +<para>OUTPUT: (Y) = Address of block</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>Thi~ system mode service request will return the address of a 64 +byte memory block as described in the F$A64 service request. 08-9 +used this service request to find process descriptors and path +descriptors when given their number,</para> +<para>Block numbers range from 1,.N</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST +</para> +</sect1> +<sect1> +<title>IODEL Delete I/O device from system F$IODL</title> +<para>ASSEMBLER CALL: OS9 F$IODL +</para> +<para>MACHINE CODE: 103F 33</para> +<para>INPUT: (K) - Address of an I/O module, (see description)</para> +<para>OUTPUT: None</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>This system mode service request is used to determine whether or +not an I/O module is being used, The N register passes the address of +a device descriptor module, device driver module, or file manager +module, The address .is used to search the device table, and if found +the use count is checked to see if it is zero, If it is not zero, an +error condition is returned</para> +<para>This service request is used primarily by IOMAN and may be of +limited or no use for other applications</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST +</para> +</sect1> +<sect1> +<title>IOQUEUE Enter I/O queue F$IOQU</title> +<para>ASSEMBLER CALL: OS9 F$IQQU</para> +<para>MACHINE CODE: 103F 2B</para> +<para>INPUT: (A) = Process Number,</para> +<para>OUTPUT: None,</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>~IIi~ system mode service request links the calling process into +the I/O queue of the specified process and performs an untimed sleep. +It is assumed that routines associated with the specified process +will send a wakeup signal to the calling process,</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>SETIRQ Add or remove device from IRQ table, F$IRQ</title> +<para>ASSEMBLER CALL: OS9 F$IRQ +</para> +<para>MACHINE CODE: 103F 2A +</para> +<para>INPUT: (X) - Zero to remove device from table, or the address of a +packet as defined below to add a device to +</para> +<para>the IRQ polling table: +</para> +<para>(xl = flip byte +</para> +<para>(X+1l = mask byte +</para> +<para>(X+21 - priority +</para> +<para>(U) - Address of service routine's static Storage area</para> +<para>(Y) - Device IRQ service routine address</para> +<para>(D) = Address of the device status register</para> +<para>OUTPUT: None</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>This service request is used to add a device to or remove a device +from the IRQ polling table, To remove a device from the table the +input should be (X)-0, (U)- Addr of service routine's static storage. +This service request is primarily used by device driver routines. See +the text of this manual for a complete discussion of the interrupt +polling system</para> +<para>PACKET DEFINITIONS: +</para> +<para>Flip Byte This byte selects whether the bits in the device +status +register are active when set or active when +cleared, A set bit(s) +identifies the active +bit(s).</para> +<para>Mask Byte This byte selects one or more bits within the device +status register that are interrupt request flag(s). A set bit +identifies an active bit(s)</para> +<para>Priority The device priority number: +0 = lowest +255 - +highest</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>NXTPRCS Start next process F$NPRC</title> +<para>ASSEMBLER CALL: OS9 F$NPRC</para> +<para>MACHINE CODE: 103F 2D</para> +<para>INPUT: None,</para> +<para>OUTPUT: Control does not return to caller,</para> +<para>This system mode service request takes the next process out of the +Active Process Queue and initiates its execution, If there is no +proess in the queue, OS-9 waits for an interrupt, and then checks the +active process queue again.</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>R64 Deallocate a 64 byte memory block F$R64</title> +<para>ASSEMBLER CALL: OS9 F$R64 +</para> +<para>MACHINE CODE: 103F 31 +</para> +<para>INPUT: (K) = Address of the base page.</para> +<para>(A) - Block number,</para> +<para>OUTPUT: None</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>This system mode service request deallocates a 64 byte block of +memory as described in the F$A64 service request</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>SRQMEM System memory request F$SRQM</title> +<para>ASSEMBLER CALL: OS9 F$SRQM</para> +<para>MACHINE CODE: 103F 28</para> +<para>INPUT: (D) - Byte count,</para> +<para>OUTPUT: (U) = Beginning address ,of memory area</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>Th~s system mode service request allocates a block of memory from +the top of available RAM of the specified size. The size requested is +rounded to the next 256 byte page boundary,</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST +</para> +</sect1> +<sect1> +<title>SRTMEM System memory request F$SRTMEM</title> +<para>ASSEMBLER CALL: OS9 F$SRTM</para> +<para>MACHINE CODE: 103F 29</para> +<para>INPUT: +</para> +<para>OUTPUT: +</para> +</sect1> +<sect1> +<title>VMODULE Validate module F$VMODUL</title> +<para>ASSEMBLER CALL: OS9</para> +<para>MACHINE CODE: 103F</para> +<para>INPUT: +</para> +<para>OUTPUT: +</para> +</sect1> +<sect1> +<title>ATTACH Attach a new device to the system, I$ATCH</title> +<para>ASSEMBLER CALL: OS9 I$ATCH +</para> +<para>MACHINE CODE: 103F 80 +</para> +<para>INPUT: (K) - Address of device name string</para> +<para>(A) - Access mode</para> +<para>OUTPUT: (U) = Address of device table entry</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>This service request is used to attach a new device to the system, +or verify that it is already attached. The device's name string is +used to search the system module directory to see if a device +descriptor module with the same name is in memory (this is the name +the device will be known by). The descriptor module will contain the +name of the device's file manager, device driver and other related +information, It it is found and the device is not already attached, +OS-9 will link to its file manager and device driver, and then place +their address' in a new device table entry. Any permanent storage +needed by the device driver is allocated, and the driver's +initialization routine is called (which usually initializes the +hardware)</para> +<para>If the device has already been attached, it will not be +reinitialized</para> +<para>An ATTACH system call is not required to perform routine I/O. It +does NOT reserve' the device in question - it just prepares it for +subsequent use by any process. Most devices are automatically +installed, so it is used mostly when devices are dynamically +installed or to verify the existence of a device</para> +<para>The access mode parameter specifies which subsequent read and/or +write operations will be permitted as follows: +</para> +<para>0 = Use device capabilities</para> +<para>1 = Read only</para> +<para>2 a = Write only</para> +<para>3 a = Both read and write</para> +</sect1> +<sect1> +<title>CHDIR Change working directory, I$CDIR</title> +<para>ASSEMBLER CALL: OS9 I$CDIR +</para> +<para>MACHINE CODE: 103F 86 +</para> +<para>INPUT: (X) - Address of the pathlist</para> +<para>(A) - Access mode</para> +<para>OUTPUT: None</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>Changes a process working directory to another directory file +specified by the pathlist, Dependinq on the access mode given, the +current execution or the current data directory may be changed (but +only one may be changed per call), The file specified must be a +directory file, and the caller must have read permission for it +(public read if not owned by the calling process)</para> +<para>ACCESS MODES +</para> +<para>1 a = Read +</para> +<para>2 = Write +</para> +<para>3 = Update (read or write) +</para> +<para>4 = Executr +</para> +<para>If the access mode is read, write, or update the current data +directory is changed. If the access mode is execute, the current +ex~cution directory is changed</para> +</sect1> +<sect1> +<title>CLOSE Close a path to a file/device. I$CLOS</title> +<para>ASSEMBLER CALL: OS9 I$OLOS +</para> +<para>MACHINE CODE: 103F 8F +</para> +<para>INPUT: (A) = Path number</para> +<para>OUTPUT: None</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>Terminates the I/O path specified by the path number, I/O can no +longer be performed to the file/device, unless another OPEN or CREATE +call is used, Devices that are non-sharable become available to other +requesting processes, All OS-9 internally managed buffers and +descriptors are deallocated</para> +<para>Note: Because the OS9 F$EXIT service request automatically closes +all open paths (except the standard I/O paths), it may not he +necessary to close them individually with the OS9 I$CLOS service r eq +U e St</para> +<para>Standard I/O paths are not typically closed except when it is +desired to change the files/devices they correspond to</para> +</sect1> +<sect1> +<title>CREATE Create a path to a new file, I$CREA</title> +<para>ASSEMBLER CALL: OS9 I$CREA +</para> +<para>MACHINE CODE: 103F 83 +</para> +<para>INPUT: (N) = Address of the pathlist</para> +<para>(A) - Access mode</para> +<para>(B) = File attributes</para> +<para>OUTPUT: (X) = Updated past the pathlist (trailing blanks skipped) +(A) = Path number</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>Used to create a new file on a mnu~1tifiIe mass storage device, +The pathlist is parsed, and the new file name is entered in the +specified (or default working) directory, The file is given the +attributes passed in the B register, which has individual bits +defined as follows</para> +<para>bit 0 = read permit +</para> +<para>bit 3. = write permit bit 2 = execute permit bit 3 = public read +permit bit 4 = public write permit bit $ - public execute permit bit +6 = sbarable file +</para> +<para>The access mode parameter passed in register A must be either +"WRITE" or "UPDATE". This only affects the file +until it is closed; it can be reopened later in any access mode +allowed by the file attributes (see OPEN). Files open for "WRITE" +may allow faster dat~i transfer than "UPDATE", which +sometimes needs to pre- read setors, These access codes are defined +as given below: +</para> +<para>2 = Write only</para> +<para>3 = Update (read and write)</para> +<para>NOTE: If the execute bit (bit 2) is set, the file will be created +in the working execution directory instead of the working data +directory</para> +<para>The path number returned by OS-9 is used to identify the file in +subsequent I/O service requests until the file is closed</para> +<para>No data storage is initially allocated for the file at the time it +is created; this is done automatically by WRITE or explicitly by the +PUTSTAT call</para> +<para>An error will occur if the file name already exists in the +directory. CREATE calls that specify non-multiple file devices (such +as printers, terminals, etc.) work correctly: the CREATE behaves the +same as OPEN, Create cannot be used to make directory files (see +MAKDIR)</para> +</sect1> +<sect1> +<title>DELETE Delete a file, I$DLET</title> +<para>ASSEMBLER CALL: OS9 I$DLET</para> +<para>MACHINE CODE: 103F 87</para> +<para>INPUT: (K) = Address of pathlist,</para> +<para>OUTPUT: (X) = Updated past pathlist (trailing spaces skipped),</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>This service request deletes the file specified by the pathlist, +The file must have write permission attributes (public write if ~ot +the owner), and reside on a multifile mass storage device, Attempts +to delete devices will result in an error,</para> +</sect1> +<sect1> +<title>DETACH Remove a device from the system. I$DTCH</title> +<para>ASSEMBLER CALL: OS9 I$DTCB +</para> +<para>MACHINE CODE: 103F 81</para> +<para>INPUT: (U) = Address of the device table entry.</para> +<para>OUTPUT: None,</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>Removes a device from the system device table if not in use by any +other process. The device driver's termination routine is called, +then any permanent storage assigned to the driver is deallocated, The +device driver and file manager modules associated with the device are +unlinked (and may be destroyed if not in use by another process</para> +<para>The I$DTCH service request must be used to un-attach devices that +were attached with the I$ATCH service request. Both of these are used +mainly by IOHAN and are of limited (or no use) to the typical user, +SCFMAN also uses ATTACH/DETACH to setup its second (echo) devile +</para> +</sect1> +<sect1> +<title>DUP Duplicate a path. I$DUP</title> +<para>ASSEMBLER CALL: OS9 I$DUP + + + +</para> +<para>MACHINE CODE: 103F 82 +</para> +<para>INPUT: (A) = Path number of path to duplicate.</para> +<para>OUTPUT: (B) = New path number, +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>Given the number of an existing path, returns another synonymous +path number for the same file or device, SHELL uses this service +request when it redirects I/O. Service requests using either the old +or new path numbers operate on the same file or device,</para> +<para> +NOTE. This only increments the "use count" of a path +descriptor and returns the synonymous path number, The path +descriptor is not copied.</para> +</sect1> +<sect1> +<title>GETSTAT Get file device status. I$GSTT</title> +<para>ASSEMBLER CALL: OS9 ISC$TI</para> +<para>MACHINE CODE: 103F 80</para> +<para>(A) = Path numter, +(B) Status code +(Other registers depend +upon status code) +</para> +</sect1> +<sect1> +<title>Write Write Data to File or Device I$WRITE</title> +<para>ASSEMBLER CALL: OS9 I$Write</para> +<para>MACHINE CODE: 103F</para> +<para>/3- Path number +</para> +<para>INPUT: ~" dl .1 Number of bytes to write (aO) Address of +buffer +</para> +<para>OUTPUT: I did Number of bytes actually written +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>DESCRIPTION:</para> +<para>I$Write outputs bytes to a file or device associated with the path +number specified. The path must have been opened or created in the +write or update access modes.</para> +<para>Data is written to the tile or device without processing or +editing. If data is written past the present end~of~file, the file is +automatically expanded.</para> +<para>NOTE: The IOMan module implements I$Write. +</para> +<para>NOTE: On RBF devices, any record that was locked is released. +</para> +<para>SEE ALSO: I$Open, I$Create, and I$WritLn</para> +<para>POSSIBLE ERRORS: E$BPNum, E$BMode, and E$Write</para> +</sect1> +<sect1> +<title>WritLn Write Line of Text with Editing</title> +<para>ASSEMBLER CALL: OS9 I$WritLn</para> +<para>MACHINE CODE: 103F 8C</para> +<para>INPUT: (A) Path number +</para> +<para>(Y) = Maximum number of bytes to write</para> +<para>(X ) = Address of buffer +</para> +<para>OUTPUT: (Y) Actual number of bytes written</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>DESCRIPTION:</para> +<para>I$WritLn is similar to I$Write except it writes data until a +carriage return character or (di) bytes are encountered. Line editing +is also activated for character~oriented devices such as terminals, +printers, etc. The line editing refers to auto line feed, null +padding at en&of line, etc.</para> +<para>The number of bytes actually written (returned in dl .1) does not +reflect any additional bytes that may have been added by file +managers or device drivers for device control. For example, if SCF +appends a line feed and nulls after carriage return characters, these +extrt bytes are not counted, + + + +</para> +<para>NOTE: On RBF devices, any record that was locked is released.</para> +<para>NOTE: The IOMan module implements I$WritLn</para> +<para> +SEE ALSO: I$Open, I$Create, and I$Write; OS-9 Technical I/O +Manual chapter on SCF Drivers</para> +<para>(line editing). +POSSIBLE ERRORS: E$BPNum, E$BMode, and E$Write</para> +</sect1> +</chapter> +<appendix> +<title>APPENDIX E</title> +<sect1> +<title>$3A*F$AllImg Allocate Image RAM blocks F$AllImg</title> +<para>ASSEMBLER CALL: OS9 F$AllImg</para> +<para>MACHINE CODE: 103F 3A</para> +<para>INPUT: (V B~~g block nu~er +</para> +<para>~ OI~ blocks +</para> +<para>Process Z~esc:iptor pointer +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>ItkM blocks for process OAT ~ The b~~s do ~ ree~ t be cc~tigt~ocs~ +</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>V ~ Allocate Process descriptor</title> +<para>ASSEMBLER CALL: OS9 ~AliPrc</para> +<para>MACHINE CODE: 103F 4B</para> +<para>INPUT: +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>&n~ italizes a ~l2~-bv~te process desc~ptor~ +</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>Allocate RAM blocks AllRAJ~!</title> +<para>ASSEMBLER CALL: OS9</para> +<para>MACHINE CODE: 103F ~9</para> +<para>U) a Desr~re~ block crocnt a t~eVto~ng PAM block numier +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>z ~ t~e Menor~ Block map for t1~s desired n~ber of ~oo:icuo~ RAM +blocks +</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST +</para> +</sect1> +<sect1> +<title>AlhC ~sk Allocate process Task number</title> +<para>ASSEMBLER CALL: OS9 F$AllTsk</para> +<para>MACHINE CODE: 103F 3F</para> +<para>X a Process Descrrptor pointer +</para> +<para> +ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>a Task. ~be: ~or tbe given process +</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST +</para> +</sect1> +<sect1> +<title>Bootstrap syste~r F$Bcc t</title> +<para>ASSEMBLER CALL: OS9 F$Boot</para> +<para>MACHINE CODE: 103F</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>~2~e modble i~aned ~Boet~ or as specified in t,~rt IIIT modblt. +~ked m~Wle~ and expects tbe return of a po±~nter and s~ze of + +a ea ~ ~ tbtn se&rclred for fl~ modules</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>Bootstrap M~ory request OS9 F$13tMen</title> +<para>ASSEMBLER CALL: OS9</para> +<para>MACHINE CODE: 103F 36</para> +<para>U a Byte count reouested~ +</para> +<para>U - Byte count cran~ed~ +- p~ ~ter to memory sIlo ~ated~ +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>-~ e3 r~uested me~nory (rounded up to nearest block a~ c~r~s menr +i~n tbe systesOs address space~</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST +</para> +</sect1> +<sect1> +<title>Clear specific Block</title> +<para>ASSEMBLER CALL: OS9 F$CIrBlk +</para> +<para>MACHINE CODE: 103F +</para> +<para>~ -Number of blocks +</para> +<para>aAl~ess of first block +</para> +<para>~0T~ Ncne~ +</para> +<para>~n process DAT ~ge as unallocated~</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST +</para> +</sect1> +<sect1> +<title>Copy external Memory F$CpyMem</title> +<para>ASSEMBLER CALL: OS9 F$CpyMem</para> +<para>MACHINE CODE: 103F</para> +<para>~F V (D)-Start~ng Memory Block number +</para> +<para>~X aCftset ~n block to begin copy QU -Byte count +</para> +<para>7h-(a~Aer s dest~ at~ron buffer +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>external memory tutu tbe user s buffer tur inspec~cn. Any n,esrc ~ +tue system ~iy be vrewed in t.his wav~</para> +</sect1> +<sect1> +<title>C nvert DAT block/offset to Doqical Addr 0 eq</title> +<para>ASSEMBLER CALL: OS9 Y~ATLcg</para> +<para>MACHINE CODE: 103F 44</para> +<para>P - ~AT xmaqe offset +- Block offset +</para> +<para>I - ~oqic&~. address~</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>a DAT inaqe block n~ber and block offset V. +a oo Al addreza~</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>Make Temporary DAT riuace</title> +<para>ASSEMBLER CALL: OS9 F$~DATTmp +</para> +<para>MACHINE CODE: 103F 45 +</para> +<para>U V. a Block number +7 - ~AT ~na~e porrter +ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>~pora~; DAD r~age to access ins given memory bloc</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST +</para> +</sect1> +<sect1> +<title>$3B* F$DelImg Deallocate tmaqe RAM blocks F$DelImg</title> +<para>ASSEMBLER CALL: OS9</para> +<para>MACHINE CODE: 103F</para> +<para>INPUT: +</para> +<para>OUTPUT: +</para> +</sect1> +<sect1> +<title>$4C* Deallocate Process descriptor F$DelPrc</title> +<para>ASSEMBLER CALL: OS9</para> +<para>MACHINE CODE: 103F</para> +<para>INPUT: +</para> +<para>OUTPUT: +</para> +</sect1> +<sect1> +<title>Deallocate RAM blocks</title> +<para>ASSEMBLER CALL: OS9</para> +<para>MACHINE CODE: 103F</para> +<para>OUTPUT: +</para> +<para>Ma V. boins n system taemcry block map as unallocated.</para> +</sect1> +<sect1> +<title>$40* F$DelTsk Deallocate process Task number F$DelTsk</title> +<para>ASSEMBLER CALL: OS9</para> +<para>MACHINE CODE: 103F</para> +<para>OUTPUT: +</para> +</sect1> +<sect1> +<title>$4D* F$ELink Link using module directory Entry F$ELink</title> +<para>ASSEMBLER CALL: OS9</para> +<para>MACHINE CODE: 103F</para> +<para>INPUT: +</para> +<para>OUTPUT: +</para> +<para>a a Ltrt3V given a pointer to a. module directory entry~ Note oail +differs from F$Link in that a pointer to the inodc~e +rec~ . ~y +ent~y is supplied rather than a pointer to a module name</para> +</sect1> +<sect1> +<title>$4E* F$FModul Find Module directory entry F$FModul</title> +<para>ASSEMBLER CALL: OS9</para> +<para>MACHINE CODE: 103F</para> +<para>OUTPUT: +</para> +<para>(B) - Appropriate error code, +</para> +</sect1> +<sect1> +<title>$3E* F$FreeHB get Free High block F$FreeHB</title> +<para>ASSEMBLER CALL: OS9</para> +<para>MACHINE CODE: 103F</para> +<para>INPUT: +</para> +<para>OUTPUT: +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +</sect1> +<sect1> +<title>$3D* F$FreeLB get Free Low block F$FreeLB</title> +<para>ASSEMBLER CALL: OS9 F$Free~La</para> +<para>MACHINE CODE: 103F 3D</para> +<para>OUTPUT: +</para> +<para>N V B a Block count +a DAT image pointer +</para> +<para>A, - Low block number</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>as tt DAT nags for the lowest free block of g van sire. + + + +</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>$19 F$GBlkMp Get system Block Map copy F$GBlkMp</title> +<para>ASSEMBLER CALL: OS9 F$OIlllkMp</para> +<para>MACHINE CODE: 103F 13 +>1 1 a 1014 byte buffer pointer,</para> +<para>73 - Number of bytes per block (M~MO block size depender t S = +Size of 5ystem~s memory block map></para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>as c a s sttmtu memory block rasp into the useVs hLtter V.</para> +</sect1> +<sect1> +<title>$1A F$GModDr Get Module Directory copy F$GModDr</title> +<para>ASSEMBLER CALL: OS9</para> +<para>MACHINE CODE: 103F 14</para> +<para>OUTPUT: +</para> +<para>(1 a 3048 byte buffer pointer</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>4 as toe svste~ s module directory into the cseVs ~ui= o +~0 +</para> +</sect1> +<sect1> +<title>$18 F$GPrDsc Get Process Descriptor copy F$GPrDsc</title> +<para>ASSEMBLER CALL: OS9 F$GPrDsc</para> +<para>MACHINE CODE: 103F 18 +"" (A) a Requested process +ED> +1 - 512 byte buffer pointer> +</para> +<para>£771 More +ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>a. process descriptor into the caLling process~ tufter fo +s~~~e<'x>en, There is no way to change dmts in a process +descrIptor></para> +</sect1> +<sect1> +<title>$37* F$GProcP Get Process Pointer F$GProcP</title> +<para>ASSEMBLER CALL: OS9 F$GIProcP</para> +<para>MACHINE CODE: 103F 37</para> +<para>OUTPUT: +</para> +<para>pp~'~ (A~ - Process ID +>7' - Pointer to Process Descriptor</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>a process ID number to the aodress at its ~"o ~ pt ~t the +system address space +</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>$49* F$LDABX Load A from 0,1 in task B F$LDABX</title> +<para>ASSEMBLER CALL: OS9 F$LDK3X</para> +<para>MACHINE CODE: 103F 49</para> +<para>OUTPUT: +</para> +<para>P (7' (II) a Ta.sk number += Data pointer +</para> +<para>X - 0a~a byte at 0,1 in task~s address space</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>7e Cyta is returned from the logical address in I) in tue +~ +address space> This is typically used to get one +</para> +<para>Von the current process's memory an a system state +~Ut Va</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST +</para> +</sect1> +<sect1> +<title>$46* F$LDAXY Load A [X, [Y] ] F$LDAXY</title> +<para>ASSEMBLER CALL: OS9</para> +<para>MACHINE CODE: 103F 46</para> +<para>I - Block offset +A = DAT i~ge pointer +</para> +<para>A' = cata tyte at (1) offset or ( 6) +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>5-c s one data byte in tte memory block specified by the DA~ in a +( S offset by (I)</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST +</para> +</sect1> +<sect1> +<title>$47* F$LDAXYP Load A [X+, [Y] ] F$LDAXYP</title> +<para>ASSEMBLER CALL: OS9 F$LDAXYP</para> +<para>MACHINE CODE: 103F 47</para> +<para>V I a Block offset +- DAT image pointer +</para> +<para>">~ >7. A ~ Data byte at (I) offset of ( SI +I - +incremented by one +ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>~a to the assembly instruction ~I~DA ,xe~', except that (I refers +"~c an offset in the memory block described by the DA'~' +at +7> + + + +</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>$48* F$LDDDXY Load D [D+X, [Y] ] F$LDDDXY</title> +<para>ASSEMBLER CALL: OS9</para> +<para>MACHINE CODE: 103F 48 +N = Uff~et to cffse>. +I) - Offset +S +- DAT nags</para> +<para>= bytes add essed by ~ +ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>two tytes from the memory block described by the 73A>~' Lma;e + +"so cc b~ (Y), The bytes loaded are at the offset (D'~'X) rz +", a rratr~~'r' bloak,</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>$4F* F$MapBlk Map specific Block F$MapBlk</title> +<para>ASSEMBLER CALL: OS9 F$MapBlk</para> +<para>MACHINE CODE: 103F 46</para> +<para>U -t'mter of blocks +<I -1.e~aon nq block number</para> +<para>~ ~ (1=Acdress of first block 3</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>~peo ~ ed block(s) into unallocated blocks of ~ro sea a + + + +</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>$38* F$Move Move data (low bound first) F$Move</title> +<para>ASSEMBLER CALL: OS9 F$Mo've</para> +<para>MACHINE CODE: 103F 38</para> +<para>5) = Source Task number +U = Dsstanataon Task number +~X) - +Source poInter +7') - Byte count += Deatinatior pointer +</para> +<para>N</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>cats bytes from one address space to anotber~ csuully fu~ 75 "ctu +to Cse>7s, or vice-versa, + + + +</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>$43* F$RelTsk Ralease Task number F$RelTsk</title> +<para>ASSEMBLER CALL: OS9 F$RelTsk +</para> +<para>MACHINE CODE: 103F 43 +""1 U) Task number</para> +<para>in</para> +<para>5 137 . (077 a C bit set, +(B) = Appropriate error code. +</para> +<para>a t,~e spec'>fred DAT Task number> + + + +</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>$42* F$ResTsk Reserve Task number F$ResTsk</title> +<para>ASSEMBLER CALL: OS9 F$ResTsk</para> +<para>MACHINE CODE: 103F 42</para> +<para>" +in 7' - ~>~~k' rcmber</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para> DAT task number, + + + +</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>$3C* F$SetImq Set process DAT Image F$SetImq</title> +<para>ASSEMBLER CALL: OS9 F$SetImq</para> +<para>MACHINE CODE: 103F 3C</para> +<para>A = 9e5>3nnarrg image block number +"13) - l3lock +count +(I - Process Descriptor pointer +7) New image pointer +</para> +<para>>5 'DT' None></para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para> lee a DAT image tote the process descriptor + + + +</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST +</para> +</sect1> +<sect1> +<title>$41* F$SetTsk Set process Task DAT registers F$SetTsk</title> +<para>ASSEMBLER CALL: OS9 F$SetTsk</para> +<para>MACHINE CODE: 103F 41</para> +<para>I) = Process Descriptor pointer +</para> +<para>F 7>7 +ERROR OUTPUT:</para> +<para>(CC) - C bit set.</para> +<para>(B) Appropriate error code.</para> +<para>a in roinss Task DAT registers,</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>$34* F$SLink System Link F$SLink</title> +<para>ASSEMBLER CALL: OS9 F$SLink</para> +<para>MACHINE CODE: 103F 34 +N' (A) = Mccc. e Type> +(I = Module +Name string pointer> +7 ) - Nazis string DAT image pointer></para> +<para>>7 " "4 = Moduts Type> +73' = Moc~u3Le +Revision, +Vt - tlpdated Name string pointer +7> - Module +Entry point +(73 - Module pointer></para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para>lc.k~ a moou~le whose name is outside the current (system) pro> +ess scAres space into the address space that contains its name.</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>$28* F$RqMem System Memory Request F$RqMem</title> +<para>ASSEMBLER CALL: OS9 F$RqMem</para> +<para>MACHINE CODE: 103F 22 +5 "' a b te count of requested +memory +a byte co~ ot of memory granted</para> +<para>37 = pointer to memory block allocated +ERROR OUTPUT:</para> +<para>(CC) - C bit set.</para> +<para>(B) Appropriate error code.</para> +<para>21. ~i e>3 ine reccssted memory (rounded up to the nearest +peoe) " a = t'en a add,res~ space> Useful for allocating 1 0 +bc/tars s '~ ~ in >iao'>'>pervanent system memory></para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST +</para> +</sect1> +<sect1> +<title>$29* F$SRtMem System Memory Return F$SRtMem</title> +<para>ASSEMBLER CALL: OS9 F$SRtMem + + + +</para> +<para>MACHINE CODE: 103F 29</para> +<para>- B~rte count of memory betng returned (17 - address of memory +block being returned +</para> +<para>ERROR OUTPUT:</para> +<para>(CC) = C bit set.</para> +<para>(B) = Appropriate error code.</para> +<para> +"o sve em memory (e.g, memory in tIre system a~cr a apt +ro onger needed + + + +</para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>$4A* F$STABX Store A at 0,X in task B F$STABX +</title> +<para>ASSEMBLER CALL: OS9</para> +<para>MACHINE CODE: 103F 4A +F' " - Data byte to store in Task~s +address space +~" Task numbs +tX) - Locical address an task +a address space to</para> +<para>"'" >7 N ne. +ERROR OUTPUT:</para> +<para>(CC) - C bit set.</para> +<para>(B) Appropriate error code.</para> +<para>~i sima~ar to the assembly anstruc aon ~$TA 04>7, +at X +refer~ to an a dre the n task a ace ass spain +r t ar inst the +current address space></para> +<para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> +</sect1> +<sect1> +<title>$1C F$SUser Set User ID number F$SUser +</title> +<para>ASSEMBLER CALL: OS9 F$SUser</para> +<para>MACHINE CODE: 103F 1C</para> +<para>- desired User ID number +</para> +<para>"F'~ ' +ERROR OUTPUT:</para> +<para>(CC) - C bit set.</para> +<para>(B) Appropriate error code.</para> +<para>t~ic current user 2730 to that specaf>ed, w±t>tout +erro a It' It,</para> +</sect1> +<sect1> +<title>$1D F$UnLoad Unlink module by name F$UnLoad</title> +<para>ASSEMBLER CALL: OS9 F$UnLoad</para> +<para>MACHINE CODE: 103F +I ""' 73) - Module Type</para> +<para>Vt = Module Name pointer +" ~ >" +ERROR OUTPUT:</para> +<para>(CC) - C bit set.</para> +<para>(B) Appropriate error code.</para> +<para>a tbe module to the module directory decrements ate lrrik +" +cc t arid removes it from the directory i>f the count re~ciaea ze +c 47 e inst tn~s call differs from F$DnLi>tik in that the a +pointer 37 +a no >u>' a rr&me is supplied rather than the +adcress of the trioc5) t.</para> +</sect1> +<sect1> +<title>DELETE Delete a file I$DeletX</title> +<para>ASSEMBLER CALL: OS9 I$Deletx</para> +<para>MACHINE CODE: 103F 90</para> +<para>INPUT: (X) - Address of pathlist +(A) = Access mode,</para> +<para>OUTPUT: (X) = Updated past pathlist (trailing spaces skipped)</para> +<para>ERROR OUTPUT:</para> +<para>(CC) - C bit set.</para> +<para>(B) Appropriate error code.</para> +<para>Tts service request deletes the file specified by the path>Last +</para> +<para>The file must have write permission attributes (public write if +not the owner) and reside on a multi-file mass storage device, +Attempts to delete devices will result in error> +</para> +<para>The access mode is used to specify the current working directory +or me cur erit execution directory (but not both) ~Ln the absence of +a full patttiist If the access mode is read, write, or update, ins +current crtata directory as assumed, 23~f the access mode as +execute~> the current execution directory is assumed> Mote that +if a full pathlist (a pathtJ.rtat beginning witt a ~ appears, the +access mode is ignored</para> +<para>ACCESS MODES' +</para> +<para>1 a Read +2 - WrIte +B = Update (read or write) +4 - +Execute + + + +</para> +</sect1> +</appendix> +</book>