Far Memory

Normally, CamelForth provides access to a maximum of just under 40K of memory, which must be shared between your Forth program and its data. However, there is a mechanism that allows you to allocate further memory for data during the execution of your program, up to the maximum memory available in the Z88.

This is done by creating a far memory pool and then allocating and freeing memory as required. The pool (also known as a "heap") can manage up to 4Mb of memory, and uses up 2 bytes of conventional memory for every 256 bytes that it can manage. Far memory is then accessible using the special "long" memory words C@L, C!L, @L, !L and CMOVEL.

Far memory isn't quite as convenient as normal memory (no words, except those listed above, can access it), and it is slightly slower to access, but it does provide an easy way to give your applications access to as much memory as they are ever going to need.

The Pool

Your memory pool is defined by providing a double number to the word POOL, specifying the maximum amount of memory your pool will be able to provide at any one time. The newly-defined word must be executed before attempting to allocate any memory. Note that only one pool should be defined (there would be no advantage to defining others in any case). For example, a pool providing up to 128K of memory:

    128 1024 UM* POOL MYPOOL
    MYPOOL

This process does not actually allocate any memory; it simply sets aside enough workspace to handle the maximum memory required. Note also that when making allocations, an extra 2 bytes are allocated internally to hold the length information, and each allocation (including these 2 bytes) takes up a multiple of 256 bytes. Therefore, allocations of 5 bytes and 200 bytes would each actually consume 256 bytes from the pool, whereas an allocation of 256 bytes would consume 512 bytes. So, make sure you aren't too stingy when determining the size of your pool.

Allocating and freeing memory

Far memory can now be allocated from your pool, used and then released after use. The following words are provided to manage memory allocations:

ALLOCATE ( ud -- dl-addr ior )

This allocates ud bytes and returns the far address dl-addr. Note that both these parameters are double numbers. The returned ior is zero for success, or -263 (rc_room) for failure.

FREE ( dl-addr -- ior )

Frees the allocation at dl-addr, returning zero for success or -9 (invalid memory address) for failure.

FREEALL ( -- )

Frees all memory associated with the far memory pool, including memory handles which are never freed by FREE. Therefore, this word should always be executed before terminating your application.

Using Far Memory

The following words allow you to access far memory. Ordinary memory addresses can be converted to far memory addresses and used with these words using the >FAR word. This allows, for example, data to be moved between far and standard memory using CMOVEL.

>FAR ( c-addr -- dl-addr )

Converts standard address to far address

C@L ( dl-addr -- char )

Fetches a character

C!L ( char dl-addr -- )

Stores a character

@L ( dl-addr -- x )

Fetches a cell

!L ( x dl-addr -- )

Stores a cell

CMOVEL ( dl-addr1 dl-addr2 u -- )

Copies u characters from dl-addr1 to dl-addr2 (from lowest address first)

More about CamelForth

Back to the Z88 home page