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.