Commit f95b9597 authored by ROOL's avatar ROOL 🤖
Browse files

This commit was manufactured by cvs2git to create branch 'Daytona'.

Sprout from Black 1996-11-05 09:41:48 UTC Neil Turton <nturton@gitlab.riscosopen.org> 'Import from cleaned 360 CD'
Cherrypick from master 1997-05-14 12:40:00 UTC Kevin Bracey <kbracey@gitlab.riscosopen.org> 'Taught AMBControl about shrinkable dynamic areas':
    BlackLog
    Docs/5thColumn/+Access,ffd
    Docs/5thColumn/+SrcIndex
    Docs/5thColumn/+SrcIndexO
    Docs/MemMaps/+Access,ffd
    Docs/MemMaps/+SrcIndex
    Docs/MemMaps/+SrcIndexO
    Docs/PrivDoc/+Access,ffd
    Docs/PrivDoc/+SrcIndex
    Docs/PrivDoc/+SrcIndexO
    Docs/PrivDoc/5thColumn/+Access,ffd
    Docs/PrivDoc/5thColumn/+SrcIndex
    Docs/PrivDoc/5thColumn/+SrcIndexO
    Makefile
    MkRom,fd7
    MkRomInst,fd7
    TestSrc/Begin
    TestSrc/ExtIO
    TestSrc/Ioc
    TestSrc/Mem1IOMD
    TestSrc/Mem2
    TestSrc/Mem3
    Version
    hdr/ExportVals/s/GetVals
    hdr/ExportVals/values
    hdr/KernelWS
    hdr/KeyWS
    hdr/PublicWS
    hdr/RISCOS
    hdr/VduExt
    s/AMBControl/growp
    s/ARM600
    s/Arthur2
    s/ArthurSWIs
    s/ChangeDyn
    s/Convrsions
    s/GetAll
    s/HeapMan
    s/KbdResPC
    s/Kernel
    s/MemInfo
    s/Middle
    s/ModHand
    s/NewIRQs
    s/NewReset
    s/PMF/i2cutils
    s/PMF/mouse
    s/PMF/osbyte
    s/PMF/osinit
    s/SWINaming
    s/SysComms
    s/vdu/vdudecl
    s/vdu/vdudriver
    s/vdu/vdugrafl
    s/vdu/vdumodes
    s/vdu/vdupal20
    s/vdu/vdupointer
    s/vdu/vduswis
Cherrypick from StrongARM 1997-05-07 06:30:31 UTC Kevin Bracey <kbracey@gitlab.riscosopen.org> 'Correct RISC OS 3.71 import':
    Docs/!ReadMe
    Docs/0197276.02
    Docs/5thColumn/Manual
    Docs/A540Extend
    Docs/AMBControl
    Docs/Kernel
    Docs/KernlSplit
    Docs/MMUControl
    Docs/MemMaps/130
    Docs/MemMaps/258
    Docs/Mode22
    Docs/Modes
    Docs/MonLead
    Docs/PaletteV
    Docs/PrivDoc/5thColumn/Concept
    Docs/PrivDoc/MMPM
    Docs/PrivDoc/ScreenMode
    Docs/ReadSysInf
    Docs/TVmodesMed,dde
    s/AMBControl/AMB
    s/AMBControl/Memory
    s/AMBControl/Options
    s/AMBControl/Workspace
    s/AMBControl/allocate
    s/AMBControl/deallocate
    s/AMBControl/growshrink
    s/AMBControl/main
    s/AMBControl/mapslot
    s/AMBControl/mapsome
    s/AMBControl/memmap
    s/AMBControl/readinfo
    s/AMBControl/service
    s/AMBControl/shrinkp
    s/Copro15ops
Cherrypick from Spin_xx 1996-11-21 12:14:21 UTC Neil Turton <nturton@gitlab.riscosopen.org> 'Import from SrcFiler':
    TestSrc/InitModule
    TestSrc/LEDDelay
    TestSrc/ROMCard
    TestSrc/ShowIOMDRs
    TestSrc/ToggleLED
Delete:
    Doc/!ReadMe
    Doc/0197276.02
    Doc/A540Extend
    Doc/Kernel
    Doc/KernlSplit
    Doc/MMUControl
    Doc/Mode22
    Doc/Modes
    Doc/MonLead
    Doc/PaletteV
    Doc/ReadSysInf
    Doc/TVmodesMed,dde
parent 3da129d2
This diff is collapsed.
directory
Manual fff 0 Mike_Stephens 28144883 31060a64 0
directory
Manual fff 1 Mike_Stephens 28144883 31060a64 0
; > 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.
MJS: last update 25-July-96
API for Application memory block control (SWI OS_AMBControl)
------------------------------------------------------------
For RISC OS 3.60, the Wimp implements the control of application space for
tasks. This has several disadvantages. Firstly, the Wimp must often manipulate
environment variables around calls to the kernel (OS_ChangeDynamicArea), to
ensure that the calls are accepted. Secondly, the Wimp must maintain page
blocks for each task, including their update in response to various memory
service calls. Thirdly, the Wimp uses generic memory manipulation routines
from the kernel, which are inefficient for the purposes of application space
control.
The problem of efficiency is the crucial one for StrongARM (and ARM 810).
Currently, the generic routines flush the processor cache and TLB for every
page (4 kbytes) remapped, so that they are safe for general use (eg. areas of
memory involved with interrupts). StrongARM will be both much slower to
perform the flush (because of the necessity to clean the cache of any non
written-back data) and more affected by the flush itself (because of the
larger cache(s) and much higher relative cost of cache reloading). For the
manipulation of application memory, it is safe to flush the cache and TLB
only once for each set of page remappings. Further efficiencies can be
gained because the application memory blocks are known to be contiguous in
logical address space, and to be of uniform protection levels (for each page)
at any given time. Hence, they can be defined by a list of page numbers
only (1 word per page), rather than page number, logical address, protection
level triples (3 words per page).
For RISC OS 3.7, the control of application space memory will be removed from the
Wimp and implemented in the kernel. A new SWI, OS_AMBControl, will be defined
for the control of the application memory blocks. The kernel will take
full advantage of the efficiency gains available. Meanwhile, the Wimp will
see only an abstract handle for each AMB. The Wimp will thereby be simplified,
and will no longer be interested in memory related service calls. The API
for the SWI is defined below.
OS_AMBControl (SWI &70)
----------------------
Control of application memory blocks.
entry:
R0 = reason code (bits 0-7) and flags (bits 8-31, reason code specific)
Other registers depend upon reason code
exit:
R0 preserved
Other registers depend upon reason code
Notes on use:
- AMBControl is initialised during kernel initialisation;
- it is the client's responsibility to avoid degenerate mappings to application
space (map out before allocate or map in);
- an allocation of 0 pages is allowed, and creates a node which may later grow;
- a shrink to 0 pages also frees the node (handle returned as 0);
OS_AMBControl 0
---------------
Allocate an AMB. The allocated pages are mapped in to application space.
entry:
R0 = reason code and flags
bits 0-7 0 (reason code)
bits 8-31 reserved (must be 0)
R1 = number of pages to allocate
exit:
R1 = number of pages allocated
R2 = abstract handle for AMB, or 0 if allocation failed
OS_AMBControl 1
---------------
Deallocate an AMB
entry:
R0 = reason code and flags
bits 0-7 1 (reason code)
bits 8-31 reserved (must be 0)
R2 = handle
exit:
R0,R2 preserved
OS_AMBControl 2
---------------
Change number of pages allocated to an AMB (grow or shrink). Note that a shrink
to 0 pages will free the node (handle returned as 0).
entry:
R0 = reason code and flags
bits 0-7 2 (reason code)
bits 8-31 reserved (must be 0)
R1 = new number of pages required
R2 = handle
exit:
R1 = new number of pages achieved
R3 = old number of pages
OS_AMBControl 3
---------------
Map (some) pages of an AMB in or out of application space.
entry:
R0 = reason code and flags
bits 0-7 3 (reason code)
bit 8 partial mapping only, if set (specified via registers R3,R4)
bits 9-31 reserved (must be 0)
R1 = start (logical) address of new mapping;
special values: 0 means map in to application start; -1 means map out
R2 = handle
R3 = offset (in pages) to start of mapping (if bit 8 of R0 set)
R4 = number of pages to map (if bit 8 of R0 set)
exit:
registers R0-R4 preserved
OS_AMBControl 4
---------------
Return information on an AMB.
entry:
R0 = reason code and flags
bits 0-7 4 (reason code)
bits 8-31 reserved (must be 0)
R2 = handle
exit:
R1 = current mapping start address; -1 means mapped out
R3 = currently allocated number of pages
Possible future work:
Take control of AMB-like part of Wimp's ClaimFreeMemory, and hence know when
free pool pages are dead. The latter allows avoidance of cache cleaning/flushing
when mapping pages out of free pool.
Offer other facilities; eg. uncacheable app space on a per node basis, to support
running old, dynamic code.
directory
130 fff 0 Mike_Stephens 2bf39672 31060a66 0
258 fff 0 Mike_Stephens 2bf395c1 31060a66 0
directory
130 fff 1 Mike_Stephens 2bf39672 31060a66 0
258 fff 1 Mike_Stephens 2bf395c1 31060a66 0
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
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
directory
5thColumn 1000 0 Mike_Stephens 2e05be22 30fd2d55 0
MMPM fff 0 Mike_Stephens 2c53f7f8 31060a6b 0
ScreenMode fff 0 Mike_Stephens 2c4d19fc 31060a6b 0
directory
5thColumn 1000 0 Mike_Stephens 2e05be22 30fd2d55 0
MMPM fff 1 Mike_Stephens 2c53f7f8 31060a6b 0
ScreenMode fff 1 Mike_Stephens 2c4d19fc 31060a6b 0
directory
Concept fff 0 Mike_Stephens 27ad92e9 31060a69 0
directory
Concept fff 1 Mike_Stephens 27ad92e9 31060a69 0
; > 5thColumn.Concept
RISC OS Support for extension ROMs
==================================
Author: Tim Dobson
Status: Draft
Issue: 0.02
History:
Date Revision Changes