Pyromaniac

Pyromaniac PRM: Application Memory

Pyromaniac PRM: Application Memory

RISC OS PyromaniacApplication Memory

Introduction

RISC OS memory is managed by Dynamic Areas. All areas of memory are assigned to a Dynamic Area which controls the sizing of the area, what is mapped into the area, and what access control is applied to it. These areas can themselves have certain properties which are managed by the Kernel - being sparse, and being able to be shrunk on demand would be examples of these properties.

Some modules using dynamic areas can provide operations to manage the content of those areas. A typical example of such management would be the Sprite Area which will be resized as operations are performed on it. One area that is considered special is the application space. This dynamic area is managed within the Operating System, and is treated a little differently by some parts of the system.

The application space is managed as a special dynamic area whose contents can be switched in and out on demand. The contents of these areas are known as 'Application Memory Blocks'. There is a dedicated SWI, SWI OS_AMBControl, which mananges the contents of the application space and these 'AMBs'.

This specialised management of the application space is largely historical, although there are certain performance improvements that are gained by the management being given preferential treatment.

Overview

Dynamic Area -1, known as the Application Space, usually contains the user mode code being executed by the system. This is the main place where code and data is stored for execution by the user. The application space lives at &8000, and contains a single continous block of paged memory. This area of memory, and the dynamic area which describes it, is able to controlled by the SWI OS_AMBControl SWIs.

Initially, only a single AMB exists, and is mapped into the application space. However, the WindowManager will manipulate the Dynamic Area to allow tasks to be switched in and out of the application space. The WindowManager concept of a 'Task' is its view on to the AMBs that it manages. The WindowManager hides the switching of application space from the user mode application tasks through the use of SWI Wimp_Poll.

Historically, the WindowManager usurped the management of the application space from the Kernel to perform the task switches. With the introduction of RISC OS 3.7, OS_AMBControl returned the control of the application space to the Kernel. This allows other managers to also perform application space management in a similar manner to that of the WindowManager.

Technical details

The application space is managed through OS_AMBControl through an 'AMB handle'. This is an opaque identifier which identifies a specific mapping of memory - the AMB. AMBs must be created, destroyed and managed through the SWI OS_AMBControl SWI. However, other SWIs may also have an effect on the region.

Application Memory Blocks

Application Memory Blocks ('AMBs') have a number of properties which are managed by the OS_AMBControl system:

  • They define the contents of a region of memory.
  • The memory to which they refer can be visible to the system ('mapped in') or inaccessible ('mapped out').
  • The memory may be mapped within the application space (at &8000), or to an arbitary location in memory. This is used under special circumstances by the WindowManager for performance reasons.
  • The number of pages which are used by the AMB.

The system keeps track of the Current AMB. This is the AMB which is mapped at the base of the application space. AMBs mapped into other areas of memory are a concession to the historic operation of the WindowManager. The Current AMB is reflected in the sizes returned from OS_ChangeDynamicArea and OS_DynamicArea.

The operating system interfaces which interact with the Current AMB are:

  • SWI OS_ReadDynamicArea

    Calls to read the application space size will return the size of the current AMB.

  • SWI OS_ChangeDynamicArea

    On RISC OS Classic: Calls to change the application space size will fail. The size of the free pool must be changed to affect the AMB size. Removing pages from the Free Pool will add them to the AMB. Adding pages to the Free Pool will remove them from the AMB.

    On RISC OS Pyromaniac: Calls to change the application space will change the AMB. The Free Pool does not exist.

  • SWI OS_DynamicArea

    The Application Space is never enumerated by OS_DynamicArea.

  • SWI OS_ChangeEnvironment 0

    Environment Handler 0 contains the memory limit. This is the maximum address occupied by the Current AMB. This value is updated by when the Current AMB is changed, or the size of the Current AMB is updated.

  • SWI OS_ChangeEnvironment 14

    Environment Handler 14 contains the application space size. This value is updated by when the Current AMB is changed, or the size of the Current AMB is updated.

    On RISC OS Classic: Writing to this environment handler will directly manipulate the logical size of the dynamic area, and may have undesireable effects on the system.

  • SWI Wimp_SlotSize

    Changes the size of the WindowManager's understanding of the current AMB, and the 'next' slot.

Caveats

Although the AMBs have been discussed in terms of their relationship to the Application Space dynamic area, there are special cases to be aware of.

AMB existence

On RISC OS Classic: The application space dynamic area may exist without a corresponding AMB to manage it. Only on starting the WindowManager do AMBs begin to be used. Until that time (or after the WindowManager has relinquished control), the application space is managed only through the standard DynamicArea operations. This is because the application space dynamic area and memory is controlled by the Kernel, with OS_AMBControl manipulating the state when it is used. Until OS_AMBControl is used, the application space essentially just another region of memory.

On RISC OS Pyromaniac: There is always an AMB handle present, and changes to it or dynamic areas will have the same effect. This is because the application space is owned by the OS_AMBControl system, and there is always a view on to application space which reflects OS_AMBControl's state.

Allocation of AMBs

On RISC OS Classic: On allocation of an AMB it will overlay the current mapping. If an AMB is already mapped into the application space, it may result in memory being present where the state of the dynamic areas (and OS_ValidateAddress) indicates there should not be any present. Always map out the AMB before use.

On RISC OS Pyromaniac: On allocation of an AMB, the Current AMB is always mapped out first.

Partial mapping of AMBs

On RISC OS Classic: AMBs may be mapped anywhere in memory. This is to allow the WindowManager to perform fast copies between applications.

On RISC OS Pyromaniac: AMBs may only be mapped into application space.

Lazy mapping

From RISC OS 4 onward, it is possible for the OS_AMBControl system to map regions of memory from the AMB only when required. The mapping still honours the maximum memory limits, and the pages are still allocated upfront, but page table updates may be deferred until an access requires the page. This was a performance improvement by avoiding large numbers of page table updates, and TLB or cache flushes on some systems. This behaviour was termed 'Lazy mapping'.

This behaviour is optional, and should be transparent to the user application. It may have an impact on applications relying on DMA, or which manipulate page tables directly. The behaviour can be controlled through SWI OS_AMBControl 5.

RISC OS Pyromaniac does not support this behaviour - it does not have page tables for this to have an effect.

SWI calls

OS_AMBControlSWI &70
Application Memory Block management
R0=Reason code and flag bits:
Bit(s)NameMeaning
0-7Reason code
ValueMeaning
0Allocate a new Application Memory Block
1Deallocate an Application Memory Block
2Change number of pages allocated to Application Memory Block
3Map in or out an Application Memory Block
4Read information on an Application Memory Block
5Control on demand mapping of Application Memory Blocks
6Reserved
7Reserved
8System information
9Read the current Application Memory Block system state
8-31Flags dependant on reason code
R0 - R3=Dependant on reason code
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

This SWI is used to control and read information about the Application Memory Blocks which manage the Application Space. Consult the individual reason codes for more information.

OS_AMBControl 0SWI &70
Allocate a new Application Memory Block
R0=Reason code and flag bits:
Bit(s)NameMeaning
0-7Reason code0
8-31Reserved, must be 0
R1=Number of pages requested
R1=Number of pages actually allocated
R2=New AMB handle
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

This SWI is used to allocate a new AMB. The AMB will be given the size specified by the number of pages requested, if they are available. If the requested size is not available, the number of pages which were able to be allocated will be returned.

The newly allocated AMB becomes the Current AMB and will replace any AMB which is currently mapped in.

Note: It is not guaranteed that the pages allocated will have been cleared; they may contain data from earlier system use.

OS_AMBControl 1SWI &70
Deallocate an Application Memory Block
R0=Reason code and flag bits:
Bit(s)NameMeaning
0-7Reason code1
8-31FlagsReserved, must be 0
R2=AMB handle
R0preserved
R2preserved
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

This SWI is used to deallocate a given AMB. The memory associated with the AMB will be discarded. If the AMB handle refers to the Current AMB, it will be mapped out.

Note: It is not guaranteed that the pages released will have been cleared; they may be available when mapped to other locations.

OS_AMBControl 2SWI &70
Change number of pages allocated to Application Memory Block
R0=Reason code and flag bits:
Bit(s)NameMeaning
0-7Reason code2
8-31FlagsReserved, must be 0
R1=Number of pages requested
R2=AMB handle
R1=Number of pages actually allocated
R3=Previous number of pages allocated
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

This SWI is used to change the number of pages which are allocated to the AMB, resizing it. If the AMB handle refers to the Current AMB, the pages will be mapped into memory. Otherwise, the AMB pages will be added or removed logically, but not physically in memory.

Note: The pages added or removed may not be cleared.

OS_AMBControl 3SWI &70
Map in or out an Application Memory Block
R0=Reason code and flag bits:
Bit(s)NameMeaning
0-7Reason code3
8MapSomeClear:Map entire address space
Set:Map partial address space
9-31FlagsReserved, must be 0
R1=Logical start address to map, or -1 to map out
R2=AMB handle
R3=Offset of start of mapping, in pages, if bit 8 of the flags is set
R4=Number of pages to map, if bit 8 of the flags is set
None
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

This SWI is used to control whether the AMB is mapped into the application space or not, or whether it is mapped into another area of memory (if bit 8 is set).

Partial address space mapping is only intended for specialised use for the WindowManager. It is not supported under RISC OS Pyromaniac.

OS_AMBControl 4SWI &70
Read information on an Application Memory Block
R0=Reason code and flag bits:
Bit(s)NameMeaning
0-7Reason code4
8-31FlagsReserved, must be 0
R2=AMB handle
R1=Current mapping start address, or -1 if mapped out (on RISC OS Classic, mapped out AMBs will return the address 'nowhere' - consult OS_ReadSysInfo for this location)
R3=Current number of pages
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

This SWI is used to read information about a specific AMB.

OS_AMBControl 5SWI &70
Control on demand mapping of Application Memory Blocks
R0=Reason code and flag bits:
Bit(s)NameMeaning
0-7Reason code5
8-31FlagsReserved, must be 0
R1=0 to disable laziness, 1 to enable laziness, -1 to read laziness
R2=AMB handle
R1=New laziness value
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

This SWI is used to control whether lazy mapping of AMBs is performed. Lazy mapping is not supported on RISC OS Pyromaniac and will always return 0, to indicate it is not supported.

OS_AMBControl 8SWI &70
System information
R0=Reason code and flag bits:
Bit(s)NameMeaning
0-7Reason code2
8-31FlagsReserved, must be 0
R1=Pointer to buffer for AMB information
R0 - R1preserved
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

This SWI is used for diagnostic purposes to return the information about all currently allocated AMBs. Call SWI OS_AMBControl 9 to read the number of AMBs currently in use, to size the buffer.

OffsetContents
0Number of AMBs present in the table
4Current AMB handle
8List of AMB descriptors:
OffsetContents
0AMB handle
4Number of pages
8Logical address mapped to
12Page protection flags

OS_AMBControl 9SWI &70
Read the current Application Memory Block system state
R0=Reason code and flag bits:
Bit(s)NameMeaning
0-7Reason code9
8-31FlagsReserved, must be 0
R2=Current AMB handle
R3=Number of AMBs present
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

This SWI is used to read information about the number of AMBs and the Current AMB handle.

Error messages

Error_AMBNoHandlesError &1F7
No AMB handles available

The error AMBNoHandles is returned if too many AMB handles have been created and a new one cannot be allocated.

Error_AMBBadHandleError &1F8
Bad AMB handle

The error AMBBadReason is returned when the AMB handle supplied to an OS_AMBControl SWI is not valid.

Error_AMBBadReasonError &1F9
Bad reason code supplied to OS_AMBControl

The error AMBBadReason is returned when reason code supplied to an OS_AMBControl SWI is not recognised.

Error_AMBInvalidFlagsError &1FA
Invalid flags supplied to OS_AMBControl

The error AMBInvalidFlags is returned when flags supplied to an OS_AMBControl SWI were not recognised.

Error_AMBBadMapSlotError &1FB
Invalid mapping request to OS_AMBControl

The error AMBBadMapSlot is returned when an attempt has been made to map a slot to an invalid location in memory.