Commit 5f9b5a63 authored by ROOL's avatar ROOL 🤖
Browse files

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

Sprout from Black 1996-11-05 09:41:48 UTC Neil Turton <nturton@gitlab.riscosopen.org> 'Import from cleaned 360 CD'
Cherrypick from master 1996-11-05 09:40:48 UTC Neil Turton <nturton@gitlab.riscosopen.org> 'Clean reimport of hdr.RISCOS (real commit date 2008-03-28 by bavison), without any of the 3rd party allocations.':
    hdr/RISCOS
Delete:
    Doc/!ReadMe
    Doc/0197276.02
    Doc/5thColumn/Manual
    Doc/A540Extend
    Doc/Kernel
    Doc/KernlSplit
    Doc/MMUControl
    Doc/MemMaps/130
    Doc/MemMaps/258
    Doc/Mode22
    Doc/Modes
    Doc/MonLead
    Doc/PaletteV
    Doc/PrivDoc/5thColumn/Concept
    Doc/PrivDoc/MMPM
    Doc/PrivDoc/ScreenMode
    Doc/ReadSysInf
    Doc/TVmodesMed,dde
    OldTestSrc/A600tlb
    OldTestSrc/Arm3
    OldTestSrc/Begin
    OldTestSrc/Cmos
    OldTestSrc/ExtCmd
    OldTestSrc/ExtIO
    OldTestSrc/Ioc
    OldTestSrc/MEMC1
    OldTestSrc/Mem1IOMD
    OldTestSrc/Mem1MEMC1
    OldTestSrc/Mem2
    OldTestSrc/Mem3
    OldTestSrc/Mem4
    OldTestSrc/Mem5
    OldTestSrc/TestMain
    OldTestSrc/Vidc
parent 3da129d2
> !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!
Copyright (C) Acorn Computers Ltd. 1993 0197,276/FS Issue 2 **Live**
Medusa Memory Management Software Functional Specification
==========================================================
-----------------------------------------
| Drawing No : 0197,276/FS |
| Issue : 2 **Live** |
| Date : 15th April 1993 |
| Author : Tim Dobson |
| Sheets : n |
| Last Issue: ? |
-----------------------------------------
Contents
========
1 History
2 Outstanding Issues
3 Overview
4 Technical Background
5 User Interface
5.1 TaskManager and large RAM sizes
6 Programmer Interface
6.1 Logical memory map
6.2 Free pool
6.3 New SWI: OS_DynamicArea
6.3.1 Reason codes
6.3.1.1 Create dynamic area
6.3.1.2 Remove dynamic area
6.3.1.3 Return information on dynamic area
6.3.1.4 Enumerate dynamic areas
6.3.1.5 Renumber dynamic area
6.3.2 Dynamic area handler routine
6.3.2.1 PreGrow
6.3.2.2 PostGrow
6.3.2.3 PreShrink
6.3.2.4 PostShrink
6.3.3 Sequence Of Actions When OS_ChangeDynamicArea Is Called
6.3.3.1 Service_PagesUnsafe
6.3.3.2 Service_PagesSafe
6.3.4 Implementation Notes for OS_ChangeDynamicArea
6.3.5 OS_DynamicArea Service Calls
6.3.5.1 Service_DynamicAreaCreate (&90)
6.3.5.2 Service_DynamicAreaRemove (&91)
6.3.5.2 Service_DynamicAreaRenumber (&92)
6.4 New SWI: OS_Memory
6.4.1 OS_Memory Reasons 0-5: Convert Memory Address
6.4.2 OS_Memory Reasons 6-8: Physical Memory
6.4.2.1 Read Physical Memory Arrangement Table Size
6.4.2.2 Read Physical Memory Arrangement Table
6.4.2.3 Read Amounts Of Various Sorts Of Memory
6.4.3 I/O Space Information
6.4.3.1 Read Controller Presence
6.5 Old SWI OS_SetMemMapEntries (&53)
6.6 Old SWI OS_ReadDynamicArea (&5C)
6.7 New SWI OS_ClaimProcessorVector
7 External Dependancies
8 Development Test Strategy
9 Organisation
10 Future Enhancements
10.1 Abort trappping
10.1.1 Technical background
10.1.2 New SWI: OS_AbortTrap
10.1.2.1 Add abort trap
10.1.2.2 Remove abort trap
1. History
==========
TMD 05-Nov-92 Started initial draft
TMD 08-Mar-93 More detail added
Issue A TMD 21-Apr-93 Released for initial review
JSR 11-May-93 Input from review entered
JSR 24-May-93 Adjustments to area grow and deletion
behaviour.
Add 2 controllers to list: VIDC1 and VIDC20 to
allow ScreenTricks module to operate.
JSR 02-Jun-93 Added section to development test strategy for
Wimp and Switcher testing.
JSR 04-Jun-93 Comments on Issue 1 spec from DLowdell.
2. Outstanding Issues
=====================
What if anything should be done to the task manager's task display to cope
with large memory sizes?
The handling of Wimp_ClaimFreeMemory. This SWI claims the free pool making
it available for data transfers. The Wimp used to implement this by putting
the free memory on the end of the current task. This is no longer
necessarily going to work as there may not be any free space beyond the end
of the current task's memory. Also, it is quite likely that there won't be
enough space for all the free memory.
3. Overview
===========
This specification covers changes to the memory management system in RISC
OS for Medusa platforms.
The main features of Medusa platforms which require changes to RISC OS's
memory management are as follows:-
1) Ability to cope with RAM sizes up to 256+2Mbytes, rather than the
current maximum of 16Mbytes;
2) Ability to control DMA;
3) Requirements for second processor card drivers to claim memory;
4) Physical RAM no longer contiguous;
5) ARM600 MMU requires page table allocation;
6) Logical memory map expansion due to 32-bit address space.
7*) Changes to support emulation of VIDC1;
8*) Changes to support line-doubling;
Note: The implementation of the starred items above (VIDC1 emulation,
line-doubling) are not part of the Medusa project; however it is an aim of
the memory management work that it should be possible to implement these in
a soft-loaded module at a later date.
4. Technical Background
=======================
In RISC OS 2 and 3 (version 3.10) the memory management task was divided
between the kernel and the wimp. The kernel ordered the memory into dynamic
areas and an application space, and the wimp then bludgeoned the kernel into
not getting in the way of the wimp's model of having a free pool and
multiple application spaces, rather than just the one application space
which had all spare memory in it. For Medusa the free pool management will
be moved into the kernel so that there isn't such a wrestling match between
the kernel and the wimp. The wimp will still manage the multiple application
spaces - it being the module responsible for constructing and managing tasks
in the desktop. The main kernel interface for memory management was
OS_ChangeDynamicArea which simply allowed the resizing of dynamic areas.
This has been added to for Medusa with the OS_DynamicArea SWI for the
control, creation and deletion of dynamic areas.
The dynamic area management in RISC OS 2 and 3 (version 3.10) was somewhat
tied together with the dynamic area clients. The change dynamic area SWI
specifically called other modules depending on which dynamic area was being
resized. The result was that there was no flexibility with how dynamic areas
were used.
Other memory related services were not available. For example it was not
possible to find out what memory or hardware was available on the system
without knowing a great deal about the platform.
Memory is referred to in three ways: physcial address, logical address and
physical page number. The first two refer to the address of the memory in
the physical address space (what IOMD presents to ARM) and logical address
space (what the ARM memory manager presents to the ARM core) respectively.
The physical page number is an arbitrary number assigned to RAM pages. It is
necessary to have this last abstraction to save space. If it weren't there
then the storage and management overheads would be prohibitive on a small
memory machine, which, as Medusa is targetted at under 1000 pounds, is
likely to be a majority of users. The way physical page numbers are
allocated is that all the contiguous RAM section in physical address space
are bunched together and the page numbers allocated from 0 upwards.
There are several interfaces described here which use Page blocks. These are
tables of 3-word records:
word use
0 Physical page number
1 logical address
2 physical address
That is, a block of memory 12*N bytes big where N is the number of records
in the block. They are used to pass round lists of addresses or pages.
5. User Interface
=================
5.1 TaskManager and large RAM sizes
-----------------------------------
The TaskManager module's 'Task display' window does not cope well in this
area at present. The combination of a 16-fold increase in maximum RAM size
and an 8-fold decrease in page size means that the existing linear 1
pixel-per-page model will not be practical on large memory machines. A
number of options are possible:-
a) Do nothing. It is rare that anyone will want to manually drag an area's
size to anything particularly big. Most big programs will set their own
Wimp slot size;
b) Allow the user to click in the number fields and enter a number
(presumably still in K);
c) Make the scale exponential (ie at the small sizes it goes in units of
4K, but when the area gets bigger go in larger and larger steps).
d) Make the scale a modified exponential (1+log(x)/c).
5.2 *-Command *Cache On/Off
---------------------------
A module will be provided to give this functionality. It will switch both
caching and write-buffering on and off. The corresponding SWIs will not be
supplied as they are inapplicable to an ARM600/700 based system.
6. Programmer Interface
=======================
6.1 Logical Memory Map
----------------------
Address Size Use Public?
00000000 16k System workspace Private
00004000 16k Scratch space Public(1)
00008000 28M-32k Application space Public
01C00000 8k SVC stack Public(2)
01C02000 2M-8k System heap Private
01E00000 8k Undefined stack Public(2)
01E02000 1M-8k Soft CAM map Private
01F00000 32k Cursor/sound etc Private
01F08000 32k "nowhere" Private
01F10000 1M-64k Reserved for fake screen (480k) Private
02000000 12M RMA Public(3)
02C00000 4M Level 2 page tables Private
03000000 4M I/O space Private(4)
03400000 1M Reserved for VIDC1 emulation Private
03500000 1M VIDC20 Private
03600000 1M Reserved for Vinit &c emulation Private
03700000 1M Reserved for 2nd Proc ctrl regs Private
03800000 8M ROM Private
04000000 2G-64M Dynamic areas Public(5)
80000000 512M Copy of physical space Private
A0000000 1 1/2 G More dynamic areas Public(5)
Notes:
1) This may be used by any module. The rules for its use are:
Not in an IRQ routine
Not if you're going to call something which might use it while you
are
Example clients are: FileCore to hold structures whilst working out how to
allocate some free space; Filer to hold structures for OS_HeapSort.
2) It may be assumed that these end on a 1M boundary and will exception if
accessed beyond that end. However, the exact location of these stacks should
not be assumed.
3) The location of RMA and its maximum size may not be assumed. However, it
is guaranteed that it will be in low 64MBytes (ie can execute 26 bit code).
4) Except where particular device drivers export hardware addresses.
5) Only in so far as a client may make its own dynamic area.
6.2 Free pool
-------------
Large RAM sizes pose a problem for RISC OS, because the existing metaphor
that all spare memory lives in application space breaks down. The current
limit on application space size is 16MB, whereas the maximum RAM size on
Medusa platforms is 258MB. Although this limit can be moved up a little by
moving other areas out of the way, it is not possible to extend it enough
(eg I/O still has to live at &03000000 onwards).
To cope with this a new dynamic area is created, known as the "free pool"
(area number 6). The operation of SWI OS_ChangeDynamicArea is modified as
follows:-
a) When an area (other than the free pool) is grown, memory is taken from
the free pool, if any exists (the current application is not notified
of this).
If having shrunk the free pool to zero size, there is still not enough
memory for the growth, the kernel attempts to remove pages from the
application space as it does under existing versions of RISC OS.
b) When an area (other than the free pool) is shrunk, the pages recovered
are added to the free pool. The current application is not consulted.
c) If the free pool itself is grown, pages are taken from application
space to put in it (and the application consulted beforehand).
d) If the free pool is shrunk, the recovered pages are added to
application space (the application is consulted beforehand).
The WindowManager module also changes, to take this into account. In some
ways its operation is simplified, as it no longer needs to maintain its own
free pool. However the implementation of the following SWIs needs to
change:-
Wimp_TransferBlock at present puts all used task memory into application
space, and then copies the relevant bits over. It cannot do this any more,
as the total used task memory may not fit into application space. Instead
it must do the following:-
Split the transfer into chunks of no more than half of the maximum
application memory size. For each chunk, put the appropriate pages of the
source block in at the start of application space, and the appropriate
pages of the destination block above these, then perform the transfer.
After all chunks have been done, restore the current task's pages in
application space.
Wimp_ClaimFreeMemory needs to be modified, because the Wimp no longer
maintains control of the free pool.
6.3 New SWI: OS_DynamicArea (&66)
---------------------------------
This SWI performs miscellaneous operations on dynamic areas.
On entry, r0 provides a reason code which determines which operation is
performed.
Note that as all operations on dynamic areas work in physical page numbers
it is not possible to map anything other than RAM pages (DRAM and VRAM)
into a dynamic area. In particular EASI space cannot be mapped in.
6.3.1 Reason codes
------------------
6.3.1.1 Create dynamic area
---------------------------
This call creates a new dynamic area.
On entry: r0 = 0 (reason code)
r1 = new area number (-1 => RISC OS should allocate number)
(must not be 128-255 - see section 6.6)
r2 = initial size of area (in bytes)
r3 = base logical address of area (-1 => OS should allocate
base address)
r4 = area flags
bits 0..3 = access privileges to be given to each page
in the area (same format as for
OS_Read/SetMemMapEntries)
bit 4 = 0 => area is singly mapped
= 1 => area is doubly mapped
bits 5..31 must be zero
r5 = maximum size of area, or -1 if the area should be
capable of growing to the total RAM size of the
machine
r6 -> area handler routine, or 0 for no routine
r7 = workspace pointer to be passed in r12 on entry to
area handler (should be 0 if r6=0)
r8 -> area description string (null terminated), eg
"Font cache". This string will be displayed in the
TaskManager window.
On exit: r1 = allocated area number
r3 = specified or allocated base address of area
r5 = specified or allocated maximum size of area
r0,r2,r4,r6-r8 preserved
An error will be returned if:
* the given area number clashes with an existing area, or
* the logical address space occupied by the area at maximum size would
intersect with any other area at maximum size, or
* there is not enough contiguous logical address space to create the
area, or
* there is not enough memory in the free pool to allocate level 2 page
tables to cover the area at maximum size.
If r1 is -1 on entry the RISC OS will allocate an area number itself.
This will be greater than or equal to 256. This means (see section 6.6)
that OS_ReadDynamicArea on these areas will always return with r2
being the maximum area size.
For singly mapped areas the base logical address is the lowest logical
address used by that area. The area grows by adding pages at the high
address end.
For doubly mapped areas the base logical address is the (fixed) boundary
between the two mappings: the first mapping ends at r3-1, and the second
starts at r3. When one of these areas grows the pages in the first copy
move down to accommodate the new pages at the end, and the second copy
simply grows at the end.
On entry, r6 points to the area handler routine which gets called with
various reason codes when an an area is grown or shrunk. If zero is
passed in, then no routine will be called, and any shrink or growth will
be allowed.
Details of the entry and exit conditions for this routine are given
in section 6.3.2 below.
The area is created initially with size zero (ie no pages assigned to
it), and is then grown to the size specified in size r2, which involves
the area handler being called in the same way as if
OS_ChangeDynamicArea was called to grow the area.
The area is created with a maximum size equal to either the amount given
in r5 on entry, or the total RAM size of the machine, if this is
smaller. If r5 is -1 on entry, then the maximum size will be set to the
total RAM size of the machine.
If r3 on entry is -1, then RISC OS allocates a free area of logical
address space which is big enough for the maximum size of the area.
Once the area has been created Service_DynamicAreaCreate will be issued
to inform the rest of the system about this change.
Notes for application writers
-----------------------------
The following facilities:
* the ability to create areas with specific area numbers
* the ability to create areas at specific logical addresses
* the ability to create doubly-mapped areas
are intended for internal system use only.
Applications should in general create only singly-mapped areas, and
request that RISC OS allocate area numbers and logical addresses.
This will prevent clashes of area numbers or addresses.
6.3.1.2 Remove dynamic area
---------------------------
This call removes a previously created dynamic area.
On entry: r0 = 1 (reason code)
r1 = area number
On exit: All registers preserved
An error is returned if the area was not removed for any reason.
Before the area is removed, RISC OS attempts to shrink it to zero size.
This is done using ChangeDynamicArea. If the ChangeDynamicArea returns
an error then the area will be grown back to its original size using
ChangeDynamicArea and the remove dynamic area call will return with an
error. If the ChangeDynamicArea to reduce the area to 0 size worked then
the area will be removed.
Once the area has been removed Service_DynamicAreaRemove will be issued
to inform the rest of the system about this change.
6.3.1.3 Return information on dynamic area
------------------------------------------
This call returns various information on a dynamic area.
On entry: r0 = 2 (reason code)
r1 = area number
On exit: r2 = current size of area (in bytes)
r3 = base logical address of area
r4 = area flags
r5 = maximum size of area
r6 -> area handler routine
r7 = workspace pointer for area handler
r8 -> area description string (null terminated)
Note that for doubly-mapped areas, r3 on exit from this call returns the
address of the boundary between the first and second copies of the area,
whereas OS_ReadDynamicArea returns the start address of the first copy
(for backwards compatibility).
6.3.1.4 Enumerate dynamic areas
-------------------------------
On entry: r0 = 3 (reason code)
r1 = area number or -1
On exit: r1 = next area number or -1
This allows an application to find out what dynamic areas are defined.
-1 is used to start the enumeration and -1 indicates that the
enumeration has finished.
6.3.1.5 Renumber dynamic area
-----------------------------
This call renumbers a dynamic area.
On entry: r0 = 4 (reason code)
r1 = old area number
r2 = new area number
On exit: All registers preserved
An error is returned if the area specified by the old area number does
not exist or if the new number clashes with an existing area.
This call is intended for system use only.
Once the dynamic area has been renumbered Service_DynamicAreaRenumber
will be issued to inform the rest of the system about this change.
6.3.1.6 Read size of application space
--------------------------------------
This call returns the maximum size of application space
On entry: r0 = 5 (reason code)
On exit: r5 = maximum size of application space
This call is intended for system use only.
6.3.2 Dynamic area handler routine
----------------------------------
This section describes the reason codes passed to the dynamic area handler
routine, with their entry and exit conditions.
This routine is called when the size of an area is being changed.
On entry, r0 contains a reason code, which describes what is happening.
It should be noted that when called, OS_ChangeDynamicArea is currently at
work and will reject requests to resize dynamic areas. As a consequence
any SWIs which might resize a dynamic area should be avoided. Such things
as OS_Module to claim some workspace are an example, and hence most file
operations should be avoided (although I/O on an existing file is more
safe than other operations).
The reason codes are as follows:-
6.3.2.1 PreGrow (0)
-------------------
This reason code is issued when a call to OS_ChangeDynamicArea results
in an area growing. It is called before any pages are actually moved. It
allows the handler to specify particular physical pages if it needs them
(eg for the screen area), or to object to the size change.
On entry: r0 = 0 (reason code)
r1 -> Page block
The physical page number entries will be set to -1
r2 = number of entries in Page block (= number of pages
area is growing by)
r3 = number of bytes area is growing by (= r2 * pagesize)
r4 = current size of area (bytes)
r5 = page size
r12 -> workspace
On exit: If the growth is OK, then
r0 is preserved
If particular physical page numbers are required then all
the physical page number entries must be filled in with
the required pages. The other entries must be left alone.
V = 0
else
r0 -> error to return, or zero to return generic error
V = 1
endif
All other registers preseved
This call permits the dynamic area handler to request that specific
pages be used for growing the area. If this is the case then all pages
must be specified. The correspondence between the Page block and memory
is that the first entry in the page block corresponds to the lowest
memory address of the extension, and the last entry in the Page block
the highest memory address.
If an error is returned, then the area will not change size.
6.3.2.2 PostGrow (1)
--------------------
This reason code is issued when a call to OS_ChangeDynamicArea results
in an area growing. It is called after the PreGrow reason code has been
issued successfully and the memory pages have been moved. It provides
the handler with a list of which physical pages have been moved into the
area.
On entry: r0 = 1 (reason code)
r1 -> Page block
Only the physical page number entries are defined
r2 = number of entries in Page block (= number of pages