Explicit Memory Allocation

OZ 4.6 provides a new series of API calls to manage large explicit memory allocation, up to one bank (16K) at once. This new feature is convenient for applications since all actual Z88 are generally expanded with at least 512K of RAM. The allocation follow the general rule by opening memory pool with OS_Mop, allocating memory, doing stuff, releasing memory and closing pool with OS_Mcl. All call entries are expressed in pages (256 bytes), for explicit address and for memory length. Four new calls are provided :

OS_Fma, Find Memory for Allocation
OS_Axm, Allocate eXplicit Memory
OS_Axp, Allocate eXplicit Page
OS_Fxm, Free eXplicit Memory

Preparing the allocation

Before allocating memory, the application has to know in which bank the requested memory area is located. OS_Fma provides that job with plenty of options. All those options have to be specified if required, they are not copied from OS_Mop. An even bank number can be requested since segment 0 can only be allocated with such banks (FM_EVN option). Remember that if an odd RAM bank is bound to segment 0, the upper half of the previous even bank will be bound to $2000-$3FFF (an even bank number is bound to $2000-$3FFF with lower half of that bank). A fixed memory (not subject to swapping) can be requested (FM_FIX option), this is useful if your application is not a popdown and does not release this memory when suspended. An explicit slot (FM_Cx option) can be specified or any (FM_ANY option) of them letting routine scan all slots for requested memory. If successful, the bank number is returned in B. Offset address can be automatically generated by OS_Fma with the FM_NOF option. This feature is often used when memory offset does not matter like data storage, buffers or relocatable code. In that case, it is preferable and easiest to use OS_Mal with large block specified in BC.

Allocating memory

Memory allocation is provided by OS_Axp or OS_Axm following an OS_Mop. During opening, memory allocations options are set for all the pool : MM_SLT, MM_EXC, MM_MUL, MM_FIX. Those allocation options are ignored by explicit allocation calls, they are only relevant for OS_Mal. OS_Mop returns a memory handle which will be mandatory for all further allocation calls.

OS_Axp, allocates an explicit page at AH (it was already existing in previous OZ but was not functional).

OS_Axm, allocates an explicit memory area of L pages at BH.

Several allocations (with both calls) can be done under the same memory handle, thus the application should keep a track of explicit address and length for future release of the memory. To get more memory (contiguous to previous or not), OS_Fma can be called again many times after previous allocation (with different options). In conclusion, it is possible to allocate under the same memory handle several large area in different banks.

Releasing memory

Memory release is really flexible. It is provided by OS_Fxm with bank, page offset and length specified. A partial release is possible, pages are relinked together during de-allocation. Notice that a call of OS_Fxm with wrong values does not crash OZ like OS_Mfr did in previous OZ (OS_Mfr has been fixed too). This flexibility is really handy if the application wants to decrease memory pool but not release all memory at once. At least, a brutal release of all allocated memory is always possible by calling OS_Mcl directly without calling OS_Fxm before. This sandbox feature protects system against incomplete release of memory pool.

These new calls completely follow the OZ rules. They use the existing memory routines which have been improved or fixed. The different memory tables are unchanged and updated dynamically during allocation/release, especially the out-of-memory tables which speed up allocation. OZ memory allocation is strong and sandbox feature can recover lost pages. However, corruption of MAT is unrecoverable. Applications are strongly advised to not use MAT and OOM table directly.