WimpExtension document: Common Data Area                              Doc 04
============================================================================

This document describes the Common Data Area, a system whereby you can store
data in unswitched memory which can be accessed by non-Wimp code. Do not use
this if you are a Wimp task unless you really need to, use the Heap manager
instead.

Note: Blocks can move over filing system calls.


WimpExt_CDA              &46392
-------------------------------
R0 = reason code
other registers as appropriate for reason code

This SWI provides access to a CDA management system which resides in the
system sprite area on an Archimedes and in a special 'WimpExt CDA' on a Risc
PC. Each block is given a block identifier which is a special unique value
that is assigned to each block that is created. Unlike the Heap manager,
the CDA can shuffle at will (due to it being in the system sprite area) so
there is a special call to locate your block.

Most of these calls can return the errors 'Bad WimpExt_CDA operation'
(&457A8) and 'CDA identifier not found' (&457AA).

R0 = 1 - Describe CDA:
----------------------
Exit:
R0 = Dynamic area number (3=system sprite area)
R1 = size of area
R2 = total free
R3 = number of blocks in use by your task
R4-> LocateBlock

Returns information about the CDA. If R1=0 then R2,R3 are corrupt. R4
returns a pointer to the CDA find routine that is used when you pass the
reason code as a block identifier.

R0 = 2 - Allocate block:
------------------------
R2 = size of block required
Exit:
R0-> block
R1 = block identifier

Tries to find a block of the required size. Increases the CDA if necessary.
If increasing fails then zero will be returned.

R1 is the block identifier and R0 contains the address of the block but this
may change over time - pass R1 as the reason code (as explained below) to
get the present block pointer.

Can return 'Not enough memory' (&457AB).

R0 = 3 - Free block:
--------------------
R1 = block identifier

Frees the memory used by the specified block.

R0 = 4 - Reallocate block:
--------------------------
R1 = block identifier
R2 = new size required
Exit:
R0-> block

Tries to resize the specified block. Can return 'Not enough memory' (&457AB)
if you are increasing the size.

R0 = 5 - Free all blocks:
-------------------------

Frees all blocks in the CDA belonging to your task.

R0 = block identifier (>&1000) - Locate block:
----------------------------------------------
Exit:
R0-> block

Locates your block in the CDA.
