This commit was generated by cvs2git to track changes on a CVS vendor branch.

.gitattributes

 hdr/** gitlab-language=armasm linguist-language=armasm linguist-detectable=true
+s/** gitlab-language=armasm linguist-language=armasm linguist-detectable=true
+**/s/** gitlab-language=armasm linguist-language=armasm linguist-detectable=true
+*,ffb gitlab-language=bbcbasic linguist-language=bbcbasic linguist-detectable=true

Doc/!ReadMe

+> !ReadMe
+
+Instructions on how to make/modify Arthur.
+
+Directory Asm contains the Exec files.
+
+Asm.A500 assembles the A500 kernel and then does *Asm.BuildA500
+Asm.BuildA500 glues modules to the kernel to make an image for 27512's.
+Asm.BigA500 glues modules to the kernel to make an image for 1Mbit devices.
+
+Asm.Test assembles the Archimedes kernel, for 300 and 400 series machines.
+  NB. This uses Hdr.Archie, not Hdr.Test !!!
+Asm.Test2 glues modules to the kernel to make an image for 1Mbit devices.
+
+Asm.MoveFS takes a new copy of FileSwitch (and headers) from the net.
+Asm.TransTim takes a new copy of Tim's stuff from the net.
+
+
+Directory Hdr has the header files for the various assemblies.
+
+
+Directory Text has various files, only one of which is important:
+Text.Changes should be updated whenever changes are made to Arthur.
+Text.Still has my list of things still to do.
+
+
+Quick guide to the source files:
+
+Kernel is the first, and has the SWI dispatcher, plus the initialized variables
+to copy into RAM, plus some Brazil swi handlers.
+
+Middle contains the rest of the Brazil swi stuff, plus supervisor routines.
+
+NewReset is the reset code - if you need to change this, you will need to use
+the AddTubeBashers flag, which lives in Kernel. The TubeChar macro should then
+function.
+
+Super1 is the supervisor loop, plus more Brazil oddsnsods.
+
+ArthurSWIs is ReadUnsigned, vectors, services, ValidateAddress. Note that
+the version of ChangeDynamic in here is NOT the one that's assembled.
+
+Arthur2 is variables, GSTRANs
+
+Arthur3 is command code, including Status/Configure.
+
+Other files are hopefully obvious from their names.
+
+
+Backing Up.
+===========
+
+You need to copy the whole tree from $.Kernel to the backup medium.
+You also need to take a copy of all the current header files from $.Hdr.
+A copy of all the tools in $.Library and $.Utils would also be handy.
+
+                             Have fun!

Doc/5thColumn/Manual

+; > 5thColumn
+
+ RISC OS Support for extension ROMs
+ ==================================
+
+ Author:        Tim Dobson
+ Status:        Draft
+ Issue:         0.03
+ History:
+
+  Date          Revision        Changes
+
+  11-Oct-90     0.00            Started
+  16-Oct-90     0.01            Completed first draft
+  08-Feb-91     0.02            Updated to reflect reality
+  23-Apr-91     0.03            Added note about directly executable
+                                 extension ROMS
+
+This document describes the enhancements to RISC OS to support extension (or
+"5th column") ROMs.
+
+Extension ROMs are ROMs fitted in addition to the main ROM set, which
+provide software modules which are automatically loaded by RISC OS on
+power-on.
+
+The availability, size and number of extension ROM sockets depends on which
+type of RISC OS computer you are using.
+
+In general, however, RISC OS recognises extension ROMs or ROM sets which are
+8, 16 or 32 bits wide, provided the ROM adheres to the specification below.
+
+32 bit wide extension ROM sets are directly executable in place, saving on
+user RAM. 8 or 16 bit wide sets have to be copied into RAM to execute.
+
+ Creating an extension ROM
+ =========================
+
+Extension ROMs appear in the ROM area of the memory map, ie between
+&03400000 and &03FFFFFF. An extension ROM set must end on a 64K boundary or
+at the start of another extension ROM. This is normally not a problem as it
+is unlikely you would want to use a ROM smaller than a 27128 (16K), and the
+normal way of addressing this would mean that the ROM would be visible in 1
+byte out of each word, ie within a 64K addressable area.
+
+Extension ROMs have a header at the end of the ROM image which indicates the
+presence of a valid extension ROM. The header is at the end because RISC OS
+scans the ROM area downwards from the top.
+
+At the end of each ROM set of size 'n' bytes must be a 16-byte header as
+follows:-
+
+        Byte address    Contents
+
+        n-16            1-word size field containing n
+        n-12            1-word checksum (bottom 32 bits of the sum of all
+                         words from addresses 0 to n-16 inclusive)
+        n-8             2-word id "ExtnROM0" indicating a valid extension
+                         ROM, ie
+
+        n-8             &45     ; "E"
+        n-7             &78     ; "x"
+        n-6             &74     ; "t"
+        n-5             &6E     ; "n"
+        n-4             &52     ; "R"
+        n-3             &4F     ; "O"
+        n-2             &4D     ; "M"
+        n-1             &30     ; "0"
+
+Note that the ROM header will not necessarily appear in the memory map in
+the last 16 bytes if the ROM set is 8 or 16 bits wide. In the 8-bit case,
+the header will appear in one of the four byte positions of the last 16
+words, and in the 16-bit case, in one of the two half-word positions of the
+last 8 words. However, RISC OS copes with this.
+
+Extension ROMs also have a header at the *start* of the ROM set, which is
+identical to the format of an expansion card's identity space. This is
+because the Podule manager module handles much of the extension ROM
+processing.
+
+The format of the header at the start is as follows:-
+
+        Byte address    Contents        Meaning
+
+        0               &00             Extended expansion card identity,
+                                         not requesting IRQ or FIQ
+        1               &03             bit 0 set => there is a chunk
+                                         directory
+                                        bit 1 set => interrupt status
+                                         pointers defined (necessary because
+                                         bit 0 is set)
+                                        bits 2,3 = 0 => 8-bits wide (NB this
+                                         should be set to 0 irrespective of
+                                         the actual width of the ROM set)
+        2               &00             Reserved, must be zero
+        3               &87             Product type (lo-byte)
+        4               &00             Product type (hi-byte)
+                                         See below
+        5               Manuf(lo)       Manufacturer code (lo-byte)
+        6               Manuf(hi)       Manufacturer code (hi-byte)
+                                         See below
+        7               Country         Country code - see below
+
+        8 to 15         &00             Interrupt status pointers (extension
+                                         ROMs do not generate interrupts!)
+        16 onwards      Chunk directory - see below
+
+Product type code: Note that &0087 has been allocated as a product type code
+for all extension ROMs.
+
+Manufacturer code: All manufacturers of expansion cards and/or extension
+ROMs should have a code for manufacturer. If you have not already been
+allocated one, you should consult Acorn.
+
+Country code: Every extension ROM should have a code for the country of
+origin. These match those used by the International module, except that the
+UK has a country code of 0 for expansion cards and extension ROMs. If you do
+not already know the correct country code for your country, you should
+consult Acorn.
+
+The chunk directory in an extension ROM is identical to that in an expansion
+card - see the chapter "Expansion Cards: Technical Details" in the RISC OS
+Programmer's Reference Manual.
+
+ Note
+ ====
+
+In extension ROMs which are directly executable (ie which are 32 bits wide),
+the word immediately preceding the start of each module must contain (size
+of module +4), ie an offset from itself to the first word after the module.
+It is recommended that all extension ROMs be created like this, irrespective
+of whether they are directly executable.
+
+ Additional interfaces to support extension ROMs
+ ===============================================
+
+ Changes to Podule manager
+ =========================
+
+The Podule manager module is responsible for recognising extension ROMs,
+although it is the kernel which is responsible for loading modules contained
+in them.
+
+The numbering scheme for expansion card slots has been extended to include
+extension ROMs. The numbers for extension ROMs are -2, -3, -4... (-1 is
+reserved for the main ROM, although the Podule manager itself does not
+accept -1 for any of its SWI calls).
+
+All Podule manager SWIs which take an expansion card slot number as a
+parameter allow an extension ROM specifier instead.
+
+The SWIs Podule_ReadID, Podule_ReadHeader, Podule_EnumerateChunks,
+Podule_ReadChunk operate as one would expect when presented with an
+extension ROM specifier.
+
+The SWIs Podule_ReadBytes, Podule_WriteBytes, Podule_CallLoader will
+normally fail because extension ROMs have no code space or loader.
+
+SWI Podule_RawRead will read successive bytes out of the extension ROM,
+taking the ROM width into account.
+
+SWI Podule_RawWrite must not be used with an extension ROM specifier, as
+writing to the ROM area can reprogram the memory and video controllers.
+
+SWI Podule_HardwareAddress returns the base address of the specified
+extension ROM, although this is not in general useful as the ROM width can
+vary.
+
+ New SWIs
+ --------
+
+SWI Podule_EnumerateChunksWithInfo
+
+ in:    R0 = chunk number (zero to start)
+        R3 = expansion card slot number or extension ROM number
+
+ out:   R0 = next chunk number (zero if final chunk enumerated)
+        R1 = size (in bytes) if R0<>0 on exit
+        R2 = operating system identity byte if R0<>0 on exit
+        R4 = pointer to a copy of the module name if the chunk is a relocatable module, else preserved
+        R5 = pointer to a copy of the module's help string if the chunk is a relocatable module, else preserved
+        R6 = address of module if the chunk is a directly executable relocatable module
+             or 0 if the chunk is a non-directly-executable relocatable module
+             else preserved
+
+SWI Podule_HardwareAddresses
+
+ in:    R3 = expansion card slot number or extension ROM number
+
+ out:   R0 = raw hardware address
+        R1 = combined hardware address
+
+For an expansion card, the "raw hardware address" is the base address of the
+expansion card, and the "combined hardware address" is the raw hardware
+address (in bits 12-25) combined with the base address of the expansion
+card's private CMOS RAM (in bits 0-11) (as returned by SWI
+Podule_HardwareAddress).
+
+For an extension ROM, the two addresses are the same, and are the start
+address of the extension ROM (ie the address of the first byte of the ROM).
+
+ Star commands
+ -------------
+
+*Podules now displays the extension ROMs in the system as well as expansion cards.
+
+ Changes to kernel
+ =================
+
+ SWI OS_Module
+ -------------
+
+OS_Module 17 (Add expansion card module) - This call now allows R3 to be
+either an expansion card slot number or an extension ROM number.
+
+OS_Module 19 (Enumerate ROM modules) - This call now enumerates
+over all ROM sections, ie extension ROM modules as well as main ROM and
+expansion card modules. R2 on entry now specifies the ROM section number to
+start scanning from, with the order of enumeration as follows:-
+
+-1 (main ROM), 0, 1, 2, 3 (expansion cards), -2, -3, -4,... (extension ROMs)
+
+Edition 1 of the PRM is incorrect when it states that on exit R1 (the
+module number to scan from) is incremented and R2 (the expansion card number
+to scan from) is preserved.
+
+In fact R1 returns the module number of the found module plus one, where
+modules are numbered from zero within each ROM section, and R2 returns the
+ROM section number of the found module, which may be in a different ROM
+section from the value passed in R2 on entry, if there are insufficient
+modules in the specified section.
+
+The values returned in R1 and R2 are therefore set up for the next call to
+OS_Module 19.
+
+The call returns the error "No more modules" (error number &107) if there
+are no more modules from the point specified in the ordering.
+
+ New call
+ --------
+
+OS_Module 20 (Enumerate ROM modules with version)
+
+This call is identical to OS_Module 19, except that on exit R6 holds a BCD
+(binary coded decimal) form of the module's version number, as derived from
+the module's help string. The top 16 bits of this value hold the integer
+part of the version number, and the bottom 16 bits hold the fractional part,
+eg if the version number of the module is "3.14" then the value returned
+would be &00031400.
+
+ Module initialisation
+ ---------------------
+
+The way in which the kernel initialises modules has been changed. If there
+is more than one version of the same module present in the ROM (which
+includes all ROM sections) then only the newest version of the module is
+initialised, where newest means the version with the highest version number.
+(If there are two copies of the same version, then directly executable
+versions (ie in main ROM or in a 32-bit wide extension ROM) are considered
+"newer". If they are equal in this respect, then the later one in scanning
+order is considered to be newer.)
+
+The kernel first scans down the list of modules in the main ROM. For each
+module in this list, the kernel initialises the newest version of that
+module.
+
+For each module in the main ROM, the newest version of that module
+ If an extension ROM contains a newer version of a module in the
+main ROM, then the newer version will be initialised at the point in the
+initialisation sequence where the main ROM version would have been
+initialised. This allows main ROM modules to be replaced without the
+problems associated with initialisation order.
+
+The kernel then applies the same rule to all of the expansion cards in turn.
+In each case the newest version of the module is initialised, but with the
+hardware address (in R11) corresponding to that of the expansion card.
+
+The kernel finally initialises any extension ROM modules that are the newest
+versions, but which have not already been initialised in lieu of a module in the
+main ROM or on an expansion card.
+
+ Star commands
+ -------------
+
+*ROMModules now displays the version number of each module, as well as the
+other information. Extension ROM modules are now included in the list. Note
+that extension ROMs are numbered 1, 2, 3... in this command - these
+correspond to ROM section numbers -2, -3, -4... respectively.
+
+*Unplug can now unplug extension ROM modules, as well as modules in the main
+ROM or in expansion cards. The syntax is now
+
+        *Unplug [<moduletitle> [<ROM section number>]]
+
+*Unplug with no parameters does the same as it used to, ie display any
+unplugged modules.
+
+*Unplug with a module name but no ROM section number specified unplugs all
+versions of that module in the system, and kills off any active module of
+that name.
+
+If a ROM section number is specified then only versions of that module
+in that ROM section are unplugged.
+
+The action of *RMReInit has changed slightly. If the specified module is
+active, then the effect is as before, ie the module is killed and then
+re-initialised.
+
+If the specified module is not active, but is in the ROM, then the unplug
+bit in CMOS RAM is cleared for all versions of the specified module, and
+then the newest version of the module is initialised.
+
+ New star command
+ ----------------
+
+*RMInsert <moduletitle> [<ROM section number>]
+
+If no ROM section number is specified, then this command clears the unplug
+bit for all versions of the specified module, without reinitialising any of
+them.
+
+If a ROM section number is specified, then this command clears the unplug
+bit for all versions of the specified module present in the given section,
+without reinitialising any of them.

Doc/A540Extend

+; A540Extend
+
+ Title:         A540Extend
+ Author:        Tim Dobson
+ Version:       1.01
+ Started:       01-Nov-90
+ Last updated:  25-Nov-91
+ Status:        Release
+ History:
+  01-Nov-90 TMD         Created
+  25-Nov-91 TMD         Updated for RISC OS 3.03
+
+Additions to the mode extension system for A540 and similar machines
+====================================================================
+
+This document describes extensions to the RISC OS mode extension system for
+machines which have programmable VIDC clock speeds and sync polarities, such
+as the A540. Familiarity with the RISC OS 2.00 mode extension system is
+assumed (this is described in the existing Programmer's Reference Manual).
+
+The A540 has extra hardware to allow the selection of different VIDC clocks
+and to determine the polarity of the sync lines. VIDC uses its clock
+together with a set of internal dividers to provide a range of pixel rates.
+
+The format of the "VIDC list" returned from Service_ModeExtension (&50) has
+been extended to allow the pixel rate and sync polarities to be specified.
+
+On original Archimedes machines, the VIDC clock is fixed at 24MHz, and the
+pixel rate is only determined by VIDC's internal dividers, as specified in
+bits 0 and 1 of the Control Register (VIDC address &E0). This would be
+stored in the VIDC list as a word of the form &E00000xx.
+
+RISC OS now supports two different format VIDC lists.
+
+The original (type 0) VIDC list format is as follows:-
+
+        Offset          Value
+
+        0               0
+        4               VIDC base mode
+        8               VIDC parameter
+        12              VIDC parameter
+        ..              ..
+        n               -1
+
+The new (type 1) VIDC list format is as follows:-
+
+        Offset          Value
+
+        0               1
+        4               VIDC base mode
+        8               VIDC parameter
+        12              VIDC parameter
+        ..              ..
+        n               -1
+        n+4             Extended parameter
+        n+8             Extended parameter
+        ..              ..
+        m               -1
+
+where extended parameters are of the form
+
+        (0 << 24) + (pixel rate in kHz)
+
+or
+
+        (1 << 24) + (sync polarity)
+
+or
+
+        (2 << 24) + (true VIDC clock rate in kHz)
+        ** This option available only from RISC OS 3.03 onwards **
+
+The sync polarity is defined as follows:-
+
+        bit 0 = 0 => HSync +ve (as on a standard Archimedes)
+              = 1 => HSync -ve
+
+        bit 1 = 0 => VSync +ve (as on a standard Archimedes)
+              = 1 => Vsync -ve
+
+        bits 2..23 must be zero
+
+A pixel rate specifier in a type 1 VIDC list will override the settings of
+bits 0 and 1 of a Control Register specifier in the main body of the list.
+If no pixel rate is specified, then the VIDC clock is set to 24MHz, and the
+settings of the divider in the Control Register are used as normal.
+
+The A540 hardware provides the following pixel rates:-
+
+        24000 kHz, 25175 kHz, 36000 kHz         with a multiplier of 2/2
+        16000 kHz, 16783 kHz, 24000 kHz         with a multiplier of 2/3
+        12000 kHz, 12587 kHz, 18000 kHz         with a multiplier of 1/2
+         8000 kHz,  8392 kHz, 12000 kHz         with a multiplier of 1/3
+
+If the pixel rate specified is not achievable with the hardware on the
+machine, the nearest available pixel rate is used.
+
+Note: when specifying a pixel rate for a hi-res-mono display, the pixel rate
+specified should be the actual pixel rate divided by 4, ie 24000 not 96000.
+
+If no sync polarity is specified, a default of 0 is used (ie the same as a
+normal Archimedes).
+
+The true VIDC clock rate specifier (only on RISC OS 3.03 or later) is
+intended to be used in systems where the clock rate fed to VIDC is under the
+control of some external device, rather than being selected by the clock
+select latch. (For example, on the portable machine, the LCD ASIC feeds
+either 8MHz or 16MHz into VIDC when LCD modes are selected).
+
+The values programmed into the clock select latch and the VIDC divider are
+still determined either from the control register specifier or a pixel rate
+specifier assuming the same range of clock speeds as on the A540, but the
+VIDC clock rate specifier is used to determine the video memory rate,
+which in turn determines the VIDC FIFO Request Pointer values (bits 4 and 5
+of the VIDC control register). The VIDC clock rate specifier is also stored
+in VDU variable VIDCClockSpeed (&AC), which is used by the SoundDMA module
+to determine the VIDC Sound Frequency Register value.

Doc/Kernel

+> net#arf:$.a500.RiscOS+.doc.Kernel
+
+ Description: Documentation of changes to kernel for PRM
+ Author:  Tim Dobson
+ Status:  Preliminary
+ History:
+    06-Oct-89  TMD     Created
+    13-Oct-89  TMD     Added documentation of OS_RemoveCallBack
+    27-Oct-89  TMD     Added documentation of VDU variable VIDCClockSpeed
+    01-Dec-89  NRaine  Added documentation of OS_FindMemMapEntries
+    04-Dec-89  TMD     Documentation of OS_FindMemMapEntries updated slightly
+
+The description of bug fixes below is in a very rough state at the moment -
+it will need to be tidied up before publication. Not all of the information
+below is relevant to the average user.
+
+ Documentation updates since RISC OS 2.00 release
+ ------------------------------------------------
+
+ Changes applying to RISC OS 2.01
+ --------------------------------
+
+A new SWI, OS_ChangeRedirection, has been added, to allow the reading and
+writing of the handles associated with OS_CLI input/output redirection. This
+call was provided for future versions of the task window module, so that
+these handles can be made local to the task running in a task window.
+
+        SWI OS_ChangeRedirection
+
+        Read or write OS_CLI input/output redirection handles
+
+in:     R0 = new input  handle (0 => not redirected, -1 => leave alone)
+        R1 = new output handle (0 => not redirected, -1 => leave alone)
+
+out:    R0 = old input  handle (0 => not redirected)
+        R1 = old output handle (0 => not redirected)
+
+****************************************************************************
+
+In RISC OS 2.00, the SWI OS_AddCallBack allowed interrupt routines to
+request a callback, which was granted later when RISC OS was about to
+exit to a user mode routine with IRQs enabled. However there was no way to
+cancel a callback request before it was granted. This could cause problems,
+for example if a module is being killed, and it has outstanding callback
+requests, it must refuse to die, otherwise the callback may be granted after
+that memory has been reused for something else. For this reason a new SWI,
+OS_RemoveCallBack, has been added.
+
+        SWI OS_RemoveCallBack
+
+        Remove a transient callback from the list
+
+in:     R0 = address that was to be called
+        R1 = value of R12 that the routine was to be called with
+
+out:    R0 = preserved
+        R1 = preserved
+
+****************************************************************************
+
+A new VDU variable, VIDCClockSpeed (variable number 172), has been added.
+The value of this variable is the current VIDC clock rate, in kHz. This
+value changes when a screen mode is selected which requires a different
+clock rate. The value is read in the same way as other VDU variables, by
+issuing the SWI OS_ReadVduVariables.
+
+Typical values are 24000 (ie 24MHz) for TV standard modes, 25175 (ie
+25.175MHz) for VGA modes, and 36000 (ie 36MHz) for super-VGA modes.
+
+****************************************************************************
+
+A number of routines were changed to improve IRQ latency:-
+
+a) New version of ChangeDynamicArea which reenables interrupts.
+
+b) Heap manager extend block has improved IRQ latency.
+
+c) Made OS_Byte &87 restore caller's IRQ state during call.
+
+d) Made OS_Word &0E,0 enable IRQs during call.
+
+e) Made OS_Word &15,0 enable IRQs during call.
+
+The heap manager has been optimised in a few places.
+
+The routine that converts a date and time value (in hours, minutes, seconds
+etc) into a 5-byte centisecond value has been made smaller and much faster.
+
+ Bug fixes
+ ---------
+
+Fixed bug in extend heap call (stack imbalance when returning 'No RAM for
+extending heap' error)
+
+Fixed "*%" (LDREQB not LDREQ).
+
+Fixed OS_ReadArgs with a /E argument that evaluates to a string (always used
+to give 'Buffer full' - also fixed 2 other bugs lurking in the background,
+viz. did STRB of buffer addr assuming it was non-zero to indicate a string,
+and didn't allow for length and type bytes in amount free value.
+
+Fixed OS_Word &15 reason code 4 (Read unbuffered mouse position) - it used
+to generate undefined instruction trap due to stack mismatch.
+
+Fixed OS_SWINumberToString with negative numbers.
+
+Fixed ROMModules never saying 'Running'.
+
+Made OS_SpriteOp reentrant by pushing register dump area on stack.
+
+Fixed sideways scroll by one 'byte' in MODEs 3 and 6.
+
+Fixed incarnation names being terminated by 1st character.
+
+Fixed *Unplug using address as extra terminator for module name.
+
+Fixed podule IRQ despatcher corrupting R0 (prevented it from correctly
+disabling the podule IRQ (or podule FIQ-as-IRQ) interrupt if no handler)
+
+RR-2047: Fixed bug in GSRead with quoted termination.
+
+RR-2060: Fixed bug in AddCallBack which freed the wrong heap node.
+
+RR-2066: Fixed bug which occasionally left soft cursors on the screen.
+
+RR-2067: Fixed bug in keyboard driver (pressing Break (as escape) key when
+keyboard buffer full did nothing)
+
+RR-2079: Fixed bug in CallAfter/Every which returned duff error pointers.
+Changed error message from null string to 'Invalid time interval'.
+
+RR-2080: Fixed rename incarnation bug.
+
+RR-2099: Fixed bug in monadic plus/minus in EvaluateExpression (eg *Eval
+50*-3)
+
+RR-2105: Added help on LEN in *Help Eval.
+
+RR-2108: Fixed bug in prefer incarnation which returned duff error pointers.
+
+
+ Changes applying to RISC OS 2.04
+ --------------------------------
+
+A new SWI OS_FindMemMapEntries has been added to allow fast scanning of the
+soft CAM map to find the correct page numbers for a given range of addresses.
+For efficiency, the caller supplies the  probable page numbers as well as the
+addresses, so that the routine can take a quick look to check if the page
+number is already correct before scanning the rest of the CAM map.
+
+        SWI OS_FindMemMapEntries
+        In:  R0 -> table of 12-byte page entries
+                +0      4       probable page number (0..npages-1) (use 0 if no idea)
+                +4      4       logical address to match with
+                +8      4       undefined
+             terminated by a single word containing -1
+        Out: table of 12-byte entries updated:
+                +0      4       actual page number (-1 => not found)
+                +4      4       address (preserved)
+                +8      4       page protection level
+             terminator preserved
+

Doc/KernlSplit

+; > KernlSplit
+
+Feasibility of splitting the RISC OS kernel
+===========================================
+
+Author:                 Tim Dobson
+Name:                   KernlSplit
+Document version:       0.01
+Last modified:          19-Apr-90
+
+Cbange record:
+
+ Date       Name        Description of change
+ ----       ----        ---------------------
+ 19-Apr-90  TDobson     Started
+
+This document discusses the feasibility of splitting the RISC OS kernel into
+separate modules/code segments for each device driver.
+
+Suggested device drivers to be split off:-
+
+ VDU
+        Screen hardware drivers
+                VIDC
+                Pointer
+                Palette
+                Hardware scroll/multiple display banks
+                Allocation of screen memory
+        Bitmap manipulation
+                Wrch
+                Sprites
+                Draw
+                Fonts
+                ColourTrans
+
+ Keyboard/mouse
+
+ IIC
+                Real time clock
+                CMOS RAM
+ Serial
+
+ Centronics
+
+ Memory control

Doc/MMUControl

+; Available from RISC OS 3.30 onwards
+
+ SWI OS_MMUControl (&6B)
+
+ On entry:
+        R0 = reason code/flags (must be zero)
+        R1 = XOR mask
+        R2 = AND mask
+
+ On exit:
+        R1 = old value of control register
+        R2 = new value of control register
+
+ Interrupts:
+        Interrupt status is undefined
+        Fast interrupts are enabled
+
+ Processor mode:
+        Processor is in SVC mode
+
+ Re-entrancy:
+        Not defined
+
+ Use:
+        This call performs a read-modify-write operation on the ARM MMU
+        control register. The new value of the register is
+
+          ((old value AND R2) XOR R1)
+
+        The old value of the register is returned in R1, and the new value
+        in R2. If the call results in the C (Cache enable) bit being
+        changed, the cache is flushed.
+
+        This call is intended for internal system use only. Users wishing to
+        enable or disable the cache should use the *Cache command instead.

Doc/MemMaps/130

+        000     App space
+        01C     System heap/svc stack
+        01E     Soft CAM copy/und stack
+        01F     Sound/pointer/random
+        020     RMA
+        02C     L2PT and L1PT
+        030     I/O
+        038     ROM
+        040     Screen
+        060     Free pool
+        0E2     Sprites
+        164     Font cache
+        1E6     RAM disc
+        268     Another area 1
+        2EA     Another area 2
+        36C     Another area 3
+        3EE     Another area 4
+        470     Another area 5
+        4F2     Another area 6
+        574     Another area 7
+        5F6     Another area 8
+        678     Another area 9
+        6FA     Another area 10
+        77C     Another area 11
+        7FE     Nothing
+        800     Phys space copy
+        A00     Another area 12
+        A82     Another area 13
+        B04     Another area 14
+        B86     Another area 15
+        C08     Another area 16
+        C8A     Another area 17
+        D0C     Another area 18
+        D8E     Another area 19
+        E10     Another area 20
+        E92     Another area 21
+        F14     Another area 22
+        F96     Nothing

Doc/MemMaps/258

+        000     App space
+        01C     System heap/svc stack
+        01E     Soft CAM copy/und stack
+        01F     Sound/pointer/random
+        020     RMA
+        02C     L2PT and L1PT
+        030     I/O
+        038     ROM
+        040     Screen
+        060     Free pool
+        162     Sprites
+        264     Font cache
+        366     RAM disc
+        468     Another area 1
+        56A     Another area 2
+        66C     Another area 3
+        76E     Nothing
+        800     Phys space copy
+        A00     Another area 4
+        B02     Another area 5
+        C03     Another area 6
+        D04     Another area 7
+        E05     Another area 8
+        F06     Nothing

Doc/Mode22

+
+ Title: Mode22
+ Author: Tim Dobson
+ History:
+        05-Dec-91 TMD Created
+
+From RISC OS 3.03 onwards a new screen mode (22) is available, on monitor
+types 0 and 1 only, which is suitable for use by visually impaired people.
+
+In terms of pixels and colours the mode is equivalent to mode 35 (an
+overscan mode), ie 16 colours, 768 pixels by 288 rows.
+
+However, the ratio of OS coordinates to pixels is changed so that instead of
+the screen being 1536 by 1152 coordinates like mode 35, it is only 768 by
+576 coordinates. This results in most text and graphics in the desktop being
+drawn twice as large in both X and Y directions, thus making them easier to
+see.
+
+There are currently a number of problems associated with this mode:-
+
+ a) The desktop tool sprites (ie the sprites used in window borders and the
+like) are inappropriate for this mode, causing some horizontal lines to
+become double thickness, and some vertical lines to disappear entirely.
+
+ b) Some applications (including those in the ROM) create windows of a
+certain size without scroll bars, and assume that the screen will be big
+enough in one or both directions to accommodate the whole of the window.
+Some parts of these windows may then be inaccessible.
+
+ Examples of this are:-
+
+ Filer windows with 'Full info' selected
+ !Alarm 'Setup','Set clock', 'Set alarm' (particularly repeating alarms)
+   windows
+ !Chars window
+ !Draw toolbox (goes partly off bottom)
+ !Edit 'Find text' window (particularly with 'Magic characters' or
+   'Wildcarded expressions' turned on
+
+
+ c) Some applications may create windows and then assume that the
+window has been created that size, and then create icons in that
+window assuming that size. The icons will then appear in the wrong
+place, eg overlapping other icons.
+
+ Examples of this are:-
+
+ !Paint tool window with various tools selected (eg use sprite as brush)
+
+ d) Some applications may create windows aligned with the bottom of the
+screen, such that the title bar goes completely off the top of the screen.
+The window therefore cannot be moved.
+
+ Examples of this are:-
+
+ Some !Impression windows.
+
+ e) Some applications which use sprites to update their windows, always use
+a fixed number of pixels for their windows. The inside of the window
+therefore does not appear double size.
+
+ Examples of this are:-
+
+ PC emulator (in a window).

Doc/Modes

+Modes we can do:
+
+DRAM-only system:                       Peak bandwidth used (x 1E6 bytes/sec)
+Total bandwidth available
+ = 46.5E6 bytes/sec
+
+  640 x 480 (72Hz) at 8bpp              31.5
+
+  800 x 600 (56Hz) at 8bpp              36
+  800 x 600 (60Hz) at 8bpp              40
+  800 x 600 (72Hz) at 4bpp              25
+
+ 1024 x 768 (60Hz) at 4bpp              32.5
+ 1024 x 768 (70Hz) at 4bpp              37.5
+
+1M VRAM system:
+Total bandwidth available
+= 80E6 bytes/sec
+
+  640 x 480 (72Hz) at 16bpp             63
+
+  800 x 600 (56Hz) at 16bpp             72
+  800 x 600 (60Hz) at 16bpp             80
+  800 x 600 (72Hz) at 8bpp              50
+
+ 1024 x 768 (60Hz) at 8bpp              65
+ 1024 x 768 (70Hz) at 8bpp              75
+
+2M VRAM system:
+Total bandwidth available
+= 160E6 bytes/sec
+
+  640 x 480 (72Hz) at 32bpp             126
+
+  800 x 600 (56Hz) at 32bpp             144
+  800 x 600 (60Hz) at 32bpp             160
+  800 x 600 (72Hz) at 16bpp             100
+
+ 1024 x 768 (60Hz) at 16bpp             130
+ 1024 x 768 (70Hz) at 16bpp             150

Doc/MonLead

+; > Doc.MonLead
+
+ Title:         MonLead
+ Author:        Tim Dobson
+ Version:       0.04
+ Started:       19-Mar-91
+ Last updated:  24-Apr-92
+ Status:        Incomplete
+ History:
+  19-Mar-91 TMD Created
+  19-Mar-91 TMD Updated
+  10-Apr-91 TMD Added documentation of Service_MonitorLeadTranslation
+  24-Apr-92 TMD Corrected information to match bodge for LiteOn monitor
+
+ Automatic detection of monitor type from monitor lead ID pins
+ =============================================================
+
+Some RISC OS computers have circuitry which allows the detection of the
+state of ID pins on the monitor connector. This allows the computer to
+distinguish between most types of monitor, and adjust its video output
+accordingly.
+
+To support this, a number of changes have been made to RISC OS:-
+
+a) To simplify the interface, the commands *Configure Mode and
+*Configure WimpMode have been merged. Both commands control the same CMOS
+location. Therefore the same screen mode will be selected on startup
+irrespective of whether the desktop is being used.
+
+b) The commands *Configure Mode/WimpMode, *Configure MonitorType, and
+*Configure Sync now take the keyword Auto as an alternative to a numeric
+parameter. If this option is configured, then RISC OS will determine a
+reasonable default for the particular parameter, based on the type of
+monitor plugged in.
+
+As the default is for all three to be set to Auto, the user should only have
+to change the settings if he has a type of monitor which is not recognised
+properly, or if he wishes to use a different screen mode from the chosen
+default.
+
+c) The effect of holding certain keys down on power-on is slightly changed:-
+
+Key held down on power-on       Settings of CMOS RAM
+
+R or Delete                     MonitorType Auto, Mode/WimpMode Auto, Sync Auto, and all the rest it used to
+T or Copy                       MonitorType Auto, Mode/WimpMode Auto, Sync 0 (separate syncs), and all the rest
+Keypad 0 to 9                   MonitorType 0 to 9
+Keypad dot                      MonitorType Auto, Mode/WimpMode Auto, Sync Auto
+
+d) A new service has been added which allows unknown values of the monitor
+ID to be recognised by modules and converted into the appropriate monitor
+type number, sync type and default mode, as follows:-
+
+Service_MonitorLeadTranslation (&76)
+
+ in:    R1 = service code (&76)
+        R2 = monitor lead ID (see below)
+
+ out:   If monitor lead ID is recognised, then the module should set
+        R1 = 0 (claim service)
+        R3 = default screen mode number to use on this type of monitor
+        R4 = monitor type number to use (as used in *Configure MonitorType)
+        R5 = sync type to use on this type of monitor
+         (0 => separate syncs, 1 => composite sync)
+        All other registers must be preserved.
+
+        If the monitor lead ID is not recognised, the module should preserve
+        all registers.
+
+The monitor connector provides 4 ID pins, ID0-ID3. Each of these may be
+connected to 0v, +5v or to the Hsync pin. The monitor lead ID therefore
+represents the state of the 4 ID pins by 8 bits as follows:-
+
+ Bit 0  Bit 1   State of ID0
+ Bit 2  Bit 3   State of ID1
+ Bit 4  Bit 5   State of ID2
+ Bit 6  Bit 7   State of ID3
+
+   0      0     Tied to 0v
+   1      0     Tied to +5v
+   0      1     Tied to Hsync
+   1      1     Inderminate - either the state is fluctuating
+                or machine is not capable of reading the ID
+
+The service is issued when SWI OS_ReadSysInfo is called with R0=1 (see
+document 'ReadSysInf') if any of the configured Mode/MonitorType/Sync are
+set to Auto.
+
+If the service is not claimed, then RISC OS checks the monitor lead ID
+against the following list of recognised IDs:-
+
+Monitor ID pins         Monitor type            Sync type       Default mode
+0=0v,1=+5v,H=Hsync,
+X=don't care
+ Pin 0 1 2 3
+
+     1 1 H X            1 (Multisync)           1 (composite)       27
+     1 0 1 X            3 (Mono VGA)            0 (separate)        27
+     0 1 1 X            3 (Colour VGA)          0 (separate)        27
+     0 1 0 X            1 (Multisync) *         0 (separate)        27
+     H 1 1 X            0 (TV standard)         1 (composite)       12
+
+For all other ID values RISC OS uses the TV standard monitor settings.
+
+* This entry should really be monitor type 4 (Super VGA). However the LiteOn
+monitor returns this monitor ID, even though it can do the TV standard
+modes. RISC OS therefore selects monitor type 1 instead, so the TV standard
+and VGA standard modes can be selected on this monitor.

Doc/PaletteV

+
+ Title: PaletteV
+ Author: Tim Dobson
+ History:
+        11-Nov-91 TMD Adapted from ColourTrans.Doc.PaletteV
+        25-Nov-91 TMD Changed a bit about setting flashing colours
+
+From RISC OS 3.03 onwards, the kernel has a default entry on PaletteV. Also,
+a number of additional reason codes have been added, to facilitate the
+implementation of the LCD drivers for Perth.
+
+The new specification for PaletteV is as follows:-
+
+R4 holds a reason code on entry to the vector. Any owner of the vector which
+has carried out the operation requested should set R4 to zero and claim the
+vector.
+
+ Reason codes
+ ============
+
+        1 - Read palette
+
+        in:     R0 = logical colour
+                R1 = type of colour (16,17,18,24,25)
+                R4 = 1 (reason code)
+
+        out:    R2 = 1st flash colour (&BBGGRRSS) - device colour
+                R3 = 2nd flash colour (&BBGGRRSS) - device colour
+                R4 = 0 => operation complete
+
+        2 - Set palette
+
+        in:     R0 = logical colour
+                R1 = type of colour (16,17,18,24,25)
+                R2 = &BBGGRRSS - device colour
+                R4 = 2 (reason code)
+
+        out:    R4 = 0 => operation complete
+
+        3 - Set first flash state
+
+        in:     R4 = 3 (reason code)
+
+        out:    R4 = 0 => operation complete
+
+        4 - Set second flash state
+
+        in:     R4 = 4 (reason code)
+
+        out:    R4 = 0 => operation complete
+
+        5 - Set default palette
+
+        in:     R4 = 5 (reason code)
+
+        out:    R4 = 0 => operation complete
+
+        6 - Blank/unblank screen (only available from RISC OS 3.08 onwards)
+
+        in:     R0 = -1 (read blank state)
+                   or 0 (unblank screen)
+                   or 1 (blank screen)
+                R4 = 6 (reason code)
+
+        out:    R0 = old state (0=unblanked, 1=blanked)
+                R4 = 0 => operation complete
+
+        This call blanks or unblanks the screen, independently of the current
+        palette settings.
+
+In the SS bits mentioned in calls 1 and 2 above, bit 7 is the current
+supremacy bit, other bits are reserved.
+
+ How old OS calls map onto PaletteV
+ ----------------------------------
+
+Initial suggestions were that VDU 19 and OS_Word(12) should ignore the
+bottom 4 bits of RGB values passed to them, and duplicate the top 4 bits in
+the bottom 4 bits before calling PaletteV. This was so that old style
+programs which set the low nybbles to zero would work correctly on machines
+with 8-bit per gun palette hardware.
+
+However, I believe that this damages the usefulness of the above calls
+unnecessarily. As long as the default palettes read back true 8-bit values,
+and the PaletteUtil module duplicates the nybbles when setting the colours,
+it should not be necessary to alter the parameters to VDU 19 and
+OS_Word(12).
+
+So the OS will pass the values through to PaletteV, and, assuming there is
+no-one else on the vector, will get the values itself. At this point it will
+just store the top 4 bits of each value in its soft copy, and in the
+hardware if appropriate (when setting the 1st and 2nd flashing colours it
+only updates the hardware if that flash state is current).
+
+The calls to read the palette on earlier versions of the OS return a value
+which corresponds to how the palette entry was programmed, ie 0..15 if a BBC
+style colour was selected, 16 if steady RGB colours were used, 17 or 18 for
+flashing colours, 24 for border colours and 25 for pointer colours.
+
+Since PaletteV does not return this information, the OS will try to make up
+this information itself. It can easily cope with the 24,25 cases. If the two
+colours returned are different, it will substitute 17 or 18 as appropriate,
+otherwise it will use 16. It will no longer return values in the range 0 to
+15.
+
+Also, when setting the palette, PaletteV does not understand BBC colours
+0..15. In order to provide the necessary functionality, the OS calls to set
+the palette will trap these values and convert them to type 16 calls (for
+0..7) or pairs of type 17 and type 18 calls.
+
+This requires a slight change to the specification of what type 17 and 18
+calls do. At the moment, these calls NEVER update the VIDC palette, instead
+they only update the relevant soft copy, and when/if the flash state
+changes, the colours are updated. But programming a BBC flashing colour
+takes effect immediately even if the flash state is 'frozen'.
+
+I therefore propose to make the 17 and 18 calls also update the VIDC palette
+if the current state is 1st or 2nd respectively. It's still not quite ideal
+because you really want to update both flash colours atomically, in case the
+state changed in between the two calls.

Doc/PrivDoc/5thColumn/Concept

+; > 5thColumn.Concept
+
+ RISC OS Support for extension ROMs
+ ==================================
+
+ Author:        Tim Dobson
+ Status:        Draft
+ Issue:         0.02
+ History:
+
+  Date          Revision        Changes
+
+  11-Oct-90     0.00            Started
+  16-Oct-90     0.01            Completed first draft
+  04-Feb-91     0.02            Updated to reflect reality
+
+This document describes the purpose of the extension ROM system and
+discusses various design issues. For the full technical documentation, refer
+to the document "5thColumn.Manual".
+
+The extension ROM system allows the development of hardware platforms fitted
+with a normal 32 bit wide RISC OS ROM set plus one or more 8, 16 or 32 bit
+ROMs or EPROMs containing software modules which add to or replace modules
+in the main ROM set. This allows the same main ROM set to be used in a wider
+variety of hardware platforms, removing the extra cost and lead times of
+re-romming, and possibly reducing costs by allowing bulk purchase of the
+main ROM set.
+
+The extension ROM(s) appear in the memory map in unused parts of the low
+(&03400000 to &037FFFFF) or high (&03800000 to &03FFFFFF) ROM areas. A 32
+bit wide extension ROM set is directly executable in place, saving on user
+RAM. 8 or 16 bit wide sets have to be copied into RAM to execute. By using
+the low ROM area (whose access time is programmable independently from the
+high area containing the main ROM set) slow EPROMs can be used.
+
+A particularly attractive configuration might be to have 8 ROM sockets on
+the board, 4 for the main ROM set, and the other 4 capable of taking either
+one 32 bit wide set (eg a large set of applications eg Internet) or up to 4
+individual 8 bit wide ROMs containing smaller applications or utilities.
+
+The scheme also allows a machine to have limited protection against
+unauthorised access, if the extension ROM contains a module which requires a
+password to be entered before continuing.
+
+In order to allow different sizes of EPROMs to be used without having to
+have links on the board, the software will look for extension ROMs at higher
+addresses first, and work backwards. This means that the high order address
+lines (which should be tied to +5v on smaller sizes of EPROM) will be pulled
+high initially, although they will be pulled low later on when looking for
+further extension ROMs.
+
+The way in which the kernel initialises modules has been changed. If there
+is more than one version of the same module present in the ROM (which
+includes the main ROM, expansion card ROMs and extension ROMs) then only the
+newest version of the module is initialised. If an extension ROM contains a
+newer version of a module in the main ROM, then the newer version will be
+initialised at the point in the initialisation sequence where the main ROM
+version would have been initialised. This allows main ROM modules to be
+replaced without the problems associated with initialisation order.

Doc/PrivDoc/MMPM

+; > PrivDoc.MMPM
+
+Still to do on memory management, as of 26-May-93:
+
+; Must be TMD
+
+ + Make SoftCAMMap variable size
+ + Finish routine to allocate backing L2 for an area
+ + Write routine to allocate logical addresses for areas
+ + Write routine to check for overlapping areas
+ + Complete Create dynamic area routine
+    (done apart from final OS_ChangeDynamicArea to get required size)
+ + Write Remove dynamic area routine
+    (done apart from initial OS_ChangeDynamicArea to shrink to zero size)
+ + Write Return info on dynamic area routine
+ + Write Enumerate dynamic areas routine
+ + Write Renumber dynamic areas routine
+ + Change OS_ReadDynamicArea to use new list
+ + Change OS_ValidateAddress to use new list
+ + Put in new error messages properly
+ * If CreateArea fails to grow area to required size, it should kill area and return error
+ * Change ChangeDynamicArea code to use lists:
+    + Check enough is working for Wimp_ClaimFreeMemory to use OS_DynamicArea(create)
+    * Check PreShrink and PostShrink work completely OK
+    * Check PreGrow and PostGrow work (apart from passing in page blocks)
+    * Migrate existing areas to new world:
+        * Update InitDynamicAreas initially to fake up a node for the RMA, and check it works
+        * Use DynamicArea_Create to create RMA from scratch (if feasible)
+        * Update InitDynamicAreas to fake up a node for the system heap + check it (no way of using create routine)
+        * Change OS_ReadRAMFsLimits to use OS_ReadDynamicArea
+        * Write RAMFS area handlers
+        * Create RAMFS dynamic area using DynamicArea_Create, + check it works
+        * Do similar for font cache, sprite area
+
+    * Put in code to split grow block into chunks, and create page blocks (without checking for updates from PreGrow)
+    * Put in checks for PreGrow requesting particular pages, and call alternative code:
+        * Do the double shuffle
+        * Issue Service_PagesUnsafe/Safe
+        * Stop it getting the static pages (esp. cursor/sound page, L1 and maybe L2)
+    * Put in extra code to cope with doubly-mapped areas
+    * Write area handlers for screen, and move it to new world
+ * Change size of application space to 24M (check all refs to 16M in whole image)
+ * Put in indirections for hardware vector poking
+ * Change FPE to use indirections (KWelton)
+ * Move RMA to &02100000, and change size of app space to 28M
+ * Conversion to do late aborts
+ 
+; Could be done by ANOther
+
+ * OS_Memory:
+        a) conversion bits
+        b) read phys.memory arrangement
+        c) read amounts of various sorts of memory
+        d) read controller addresses
\ No newline at end of file

Doc/PrivDoc/ScreenMode

+; > PrivDoc.ScreenMode
+
+Still to do on screen mode selection, as of 21-Jul-93:
+
+Key:    +  Done and tested
+        -  Done but not tested
+        *  Still to do
+        x  Not done for a good reason
+
+ + Make OS_ReadModeVariable work with mode selectors
+ + OS_ScreenMode(ReturnMode)
+ + OS_ScreenMode(EnumerateModes)
+     + Create variable holding video bandwidth
+     + Add this reason code to just load up video bandwidth, VideoSize and issue service
+ + Service_ModeExtension additions
+     + Load up r4 and r5 with video bandwidth, VideoSize respectively
+ + Change vdugrafg:SetUpSprModeData:04 to check for mode selector, and goto 10 if so
+ + Check other occurrences of BranchIfKnownMode to look for similar bits
+ + Put code to handle new sprite mode word into PushModeInfo (any monitor only?)
+ + Remove new sprite mode word fudging in vdugrafg:SetupSprModeData and 
+    vdugrafl:SwitchOutputToSprite
+ + Make SwitchOutputToSprite(new format) set up ECFIndex (it doesn't at the moment!)
+ + Make sure tests for equal mode numbers don't assume equal ptrs to mode selectors are equivalent
+ + Modify NewModes module to respond to Service_EnumerateScreenModes, to test enumeration.
+ + OS_ScreenMode(SetMonitorType)
+     + Allocate soft copy for monitortype
+     + Write routine to update soft copy from CMOS
+     + Call this routine in initialisation
+     + Make *Configure MonitorType update soft copy
+     + Change ReadMonitorType to read from soft copy
+     + Add this reason code to either store given value or update from CMOS
+ + Make sprites which have mode selectors as their mode word illegal
+     + Move conversion of mode selectors to new format sprite mode words
+        into PreCreateHeader, rather than PostCreateHeader, so that it
+        doesn't call SetupSprModeData with a (now illegal) mode selector
+ -> MT ScreenModes module
+
+ -> AG Make switch output to sprite for a new format sprite make mode selector for current mode?
+
+ -> AG *ScreenSave in mode 50 seems to produce a sprite with a palette.
+
+ -> NK Trying to set a WimpMode with XEigFactor=27 caused data abort.
+       Investigate and/or range-limit values.
+
+ -> AG Put in support for returning errors from PushModeInfo (for bad mode
+       selectors and new format sprite mode words):
+     + Make mode change routine check for error from PushModeInfo and FindOKMode
+     + Make FindSubstitute check errors from PushModeInfo
+     + Make FindOKMode check errors from FindSubstitute
+     + Make CheckModeValid check errors from FindOKMode
+     + Make SetupSprModeData capable of returning errors:
+         + Ditto SpriteV handler (already OK)
+         + Ditto PreCreateHeader
+         + Ditto CreateHeader
+         + Ditto GetSprite
+     -> AG Make SwitchOutputToSprite/Mask check errors from PushModeInfo
+
+ - Design and code algorithm for working out FIFO reload position for VIDC20
+   (Still need explanation from ARM of why 7 quad-words doesn't always work)
+
+ * OS_ScreenMode(SelectMode)
+     + Make normal mode selection routine into a subroutine
+     + Write veneers to put round call to this in OS_ScreenMode(SelectMode)
+     * Change actual mode change code to cope with mode selectors
+         + Prevent main routine looking at shadow bit in mode selector
+         + Modify FindOKMode to cope with mode selector
+         + Modify OS_CheckModeValid to cope with mode selector
+         + Make all pushed mode variables into words (not bytes)
+         + Modify PushModeInfo to cope with mode selector
+         + Make YEigFactor default to 2 if yres < xres/2 (and change spec. to reflect that)
+         + Make numbered modes work after loading mode file
+         + Allocate space for OS copy of mode selector
+         x Make OS mode selector part of saved VDU context
+            (not needed since sprites can't have mode selectors as their mode)
+         x Sort out internal mode variables PalIndex, ECFIndex wrt
+            converting existing mode numbers into mode selectors (no need, still use old workspace-getting code)
+         x Make mode selector blocks for all existing numbered modes
+            (no need, constructed on fly since only needed during svc call)
+         * Check that copying mode selector has no adverse effects
+         * Sort out why issuing a mode change with invalid mode selector doesn't give error
+         * Modify FindOKMode to cope with 16 and 32 bpp modes somehow
+
+ * Prevent pointer position from going into the sync pulse (causes screen picture disruption)
+
+ * Adjust borders on all modes, to cope with VIDC20 problem
+   (Needs algorithm from ARM that works!)
+
+ * Mode change happily passes round any old rubbish to Service_ModeExtension - it should:-
+        * First check that value is word-aligned - if not it may be a new sprite mode word
+        * Do a Validate_Address on fixed bit of block?
+
+ * What should *ScreenLoad do with a new format sprite?

Doc/ReadSysInf

+; > Doc.ReadSysInf
+
+ Title:         ReadSysInf
+ Author:        Tim Dobson
+ Version:       0.03
+ Started:       19-Mar-91
+ Last updated:  21-Oct-91
+ Status:        Preliminary
+ History:
+  19-Mar-91 TMD         Created
+  04-Apr-91 TMD         Updated OS_ReadSysInfo(2)
+
+ Extensions to SWI OS_ReadSysInfo in RISC OS 2.11 and later versions
+ ===================================================================
+
+SWI OS_ReadSysInfo has been extended since RISC OS 2.00 - the full
+specification is as follows:-
+
+*****************************************************************************
+
+        SWI OS_ReadSysInfo - Read various system information
+
+ in:    R0 = reason code
+
+ out:   Depends on reason code
+
+ Reason codes:-
+
+-------------------------------------------------------------------------
+
+ in:    R0 = 0
+ out:   R0 = amount of configured screen memory, in bytes
+
+This sub-call is the same as on RISC OS 2.00, with the exception that two
+bugs in the call have been fixed:-
+
+ a) It no longer goes wrong if less than 20K configured on 8K or 16K page
+size machine;
+
+ b) It now properly ignores the top bit of the CMOS location holding the
+configured value.
+
+-------------------------------------------------------------------------
+
+ in:    R0 = 1
+ out:   R0 = Configured Mode/WimpMode
+        R1 = Configured MonitorType
+        R2 = Configured Sync
+
+Note that from RISC OS 2.09 onwards, the configured Mode and WimpMode have
+been merged. Both *Configure Mode and *Configure WimpMode control the same
+CMOS RAM location.
+
+Note also that if any of Mode/WimpMode, MonitorType or Sync have been
+configured to Auto (see "Doc.MonLead"), then the appropriate value for the
+attached monitor will be returned.
+
+-------------------------------------------------------------------------
+
+ in:    R0 = 2
+ out:   R0 = IOEB ASIC presence flag
+             0 => absent
+             1 => present (type 1)
+             Other values are reserved for future versions of IOEB which are
+              not backwards compatible.
+
+        R1 = 82C710 (or similar) presence flag
+             0 => absent
+             1 => present
+
+        R2 = LCD ASIC presence flag
+             0 => absent
+             1 => present (type 1)
+             Other values are reserved for future versions of LCD ASIC which
+              are not backwards compatible.
+
+        R3 = word 0 of unique machine ID
+        R4 = word 1 of unique machine ID
+
+Some RISC OS computers are fitted with a chip providing a machine ID number
+which is unique to each computer. Machines not fitted with an ID will return
+zero in both R3 and R4.
+
+-------------------------------------------------------------------------
+
+ in:    R0 = 3 (*** Only available from RISC OS 3.01 onwards ***)
+ out:   R0 = 82C710/82C711 basic features mask       82C710  82C711
+                Bits 0..3   Basic IDE type              1       1
+                Bits 4..7   Basic FDC type              1       1
+                Bits 8..11  Basic parallel port type    1       1
+                Bits 12..15 Basic 1st serial port type  1       1
+                Bits 16..19 Basic 2nd serial port type  0       1
+                Bits 20..23 Basic Configuration type    1       2
+                Bits 24..31 Reserved
+
+        R1 = 82C710/82C711 extra features mask
+                Reserved for upwards compatible additional functionality
+
+        R2-R4 Undefined (reserved for future expansion)
+
+The 82C710 family of chips are composed of several sub-units, each of which
+might change under future revisions of the chip. Current sub-units are as
+follows:
+
+        IDE hard disc interface
+        Floppy disc interface
+        Parallel port
+        Serial port 1
+        Serial port 2 (only present in 82C711)
+        Chip configuration (different on 82C710 and 82C711)
+
+New versions of the chip may have some sub-units which are incompatible with
+earlier versions, while leaving the functionality of other sub-units
+unchanged.
+
+This call allows drivers which are only interested in particular sub-units
+to tell whether they can work on the particular hardware running in the
+machine.
+
+Different values of each sub-field correspond to incompatible versions of
+the corresponding sub-unit. A sub-field of zero indicates that the sub-unit
+is not present.
+
+If a sub-unit gains additional backwards-compatible functionality in future
+versions of the chip, this will be indicated by having bits set in the value
+returned in R1.
+
+Information on extra sub-units will be accomodated in the remaining bits of
+R0, or in R2-R4.