AllocMem

allocate memory given certain requirements

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.

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)

attributes

Requirements flags: If no flags are set, the system will return the best available memory block. For expanded systems, the fast memory pool is searched first.

MEMF_CHIP

If the requested memory will be used by the Amiga custom chips, this flag *must* be set.

Only certain parts of memory are reachable by the special chip sets' DMA circuitry. Chip DMA includes screen memory, images that are blitted, audio data, copper lists, sprites and Pre-V36 trackdisk.device buffers.

MEMF_FAST

This is non-chip 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_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_LOCAL 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. This memory type is now automatically set in V36. Pre-V36 systems may not have this memory type and AllocMem() will then fail.

MEMF_24BITDMA

This is memory that is within the address range of 24-bit DMA devices. (Zorro-II) This is required if you run a Zorro-II DMA device on a machine that has memory beyond the 24-bit addressing limit of Zorro-II. This memory type is now automatically set in V36. Pre-V36 systems may not have this memory type and AllocMem() will then fail.

MEMF_KICK

This memory is memory that EXEC was able to access during/before the KickMem and KickTags are processed. This means that if you wish to use these, you should allocate memory with this flag. This flag is automaticly set by EXEC in V39. Pre-V39 systems may not have this memory type and AllocMem() will then fail. Also, *DO NOT* ever add memory the system with this flag set. EXEC will set the flag as needed if the memory matches the needs of EXEC.

Options flags:

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. This option is new as of V36. Note that this option has a bug in pre-V39 systems.

MEMF_NO_EXPUNGE

This will prevent an expunge to happen on a failed memory allocation. This option is new to V39 and will be ignored in V37. If a memory allocation with this flag set fails, the allocator will not cause any expunge operations. (See AddMemHandler())

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.

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.

Memory allocation and deallocation as well as querying how much memory is available requires a Task or, by extension, a Process. None of the exec kernel memory management operations is safe to call from interrupt code!

If the free list is corrupt, the system will panic with alert AN_MemCorrupt, $01000005.

This function may not be called from interrupts.

An AmigaDOS process will have its pr_Result2 field set to ERROR_NO_FREE_STORE if the memory allocation fails.

FreeMem(), "exec/memory.i", "exec/alerts.i", <exec/memory.h>, <exec/alerts.h>