Function Memory.allocMem

AllocMem -- Allocate memory

void* allocMem (
  ulong byteSize,
  MemFlags requirements
);

SYNOPSIS void* AllocMem( Memory* SysBase, uint byteSize, uint requirements );

FUNCTION This is the memory allocator to be used by system code and applications. It provides a means of specifying that the allocation should be made in a memory area accessible to the chips, or accessible to shared system code.

Memory is allocated based on requirements and options. Any "requirement" must be met by a memory allocation, any "option" will be applied to the block regardless. AllocMem will try all memory spaces until one is found with the proper requirements and room for the memory request.

Parameters

NameDescription
byteSize the size of the desired block in bytes. (The operating system will automatically round this number to a multiple of the system memory chunk size (MEM_BLOCKSIZE) )
requirements requirements If no flags are set (MEMF_ANY), the system will return the best available memory block. For expanded systems, the fast memory pool is searched first.

MEMF PUBLIC

Memory that must not be mapped, swapped, or otherwise made non-addressable. ALL MEMORY THAT IS REFERENCED VIA INTERRUPTS AND/OR BY OTHER TASKS MUST BE EITHER PUBLIC OR LOCKED INTO MEMORY! This includes both code and data.

MEMF FAST

This is cpu-local memory. If no flag is set MEMF_FAST is taken as the default.

DO NOT SPECIFY MEMF_FAST unless you know exactly what you are doing! If MEMF_FAST is set, AllocMem() will fail on machines that only have chip memory! This flag may not be set when MEMF_CHIP is set.

MEMF VIDEO

This is video memory. Some graphics chips allow to use the graphics mem like usual memory. Useful for allocating BitMaps etc.

MEMF VIRTUAL

This is mapped memory. This flag requests memory, that can be swapped out to HD, if your system cpu that. MMU required. Other allocation will fail.

MEMF PERMANENT

This is memory that will not go away after the CPU RESET instruction. Normally, autoconfig memory boards become unavailable after RESET while motherboard memory may still be available. options

MEMF CLEAR

The memory will be initialized to all zeros.

MEMF REVERSE

This allocates memory from the top of the memory pool. It searches the pools in the same order, such that FAST memory will be found first. However, the memory will be allocated from the highest address available in the pool. MemFlags.No_Expunge This will prevent an expunge to happen on a failed memory allocation. If a memory allocation with this flag set fails, the allocator will not cause any expunge operations. (See AddMemHandler())

Result

memoryBlock - a pointer to the newly allocated memory block. If there are no free memory regions large enough to satisfy the request, zero will be returned. The pointer must be checked for zero before the memory block may be used! The memory block returned is long word aligned.

Warning

The result of any memory allocation MUST be checked, and a viable error handling path taken. ANY allocation may fail if memory has been filled.

Example

AllocMem(64,0L) - Allocate the best available memory AllocMem(25,MEMF_CLEAR) - Allocate the best available memory, and clear it before returning. AllocMem(128,MEMF_FAST) - Allocate cpu-local memory AllocMem(128,MEMF_VIDEO|MEMF_CLEAR) - Allocate cleared gfx memory AllocMem(821,MEMF_FAST|MEMF_PUBLIC|MEMF_CLEAR) - Allocate cleared, public, cpu-local memory.

Note

If the free list is corrupt, the system will panic with alert SEN_MemCorrupt.

This function may not be called from interrupts.

See

FreeMem()