AllocMemFromMemLists

Allocates a memory block from a list of memory lists.

Synopsis

void *AllocMemFromMemLists( List *l, int32 size, uint32 memflags)

Description

This procedure allocates a memory block of the specified type from a list of free memory lists. Although it is used most often by the kernel, it can also be called by user tasks that need to do their own memory management.

Note: Most applications do not need to do their own memory management. When you use standard memory-allocation procedures like AllocMem(), the details of memory management are handled for you by the kernel.

The free memory pools in Portfolio are implemented as lists of memory lists:

The system-wide free memory pool is the list of memory lists that contain the free memory pages owned by the system.
A task's free memory pool is a list of memory lists that have been allocated for the task. These include (1) the two memory lists - one for VRAM and one for DRAM -that are allocated automatically for a task when the task is created.

AllocMemFromMemLists() allocates memory directly from a particular memory pool. This is in contrast to AllocMemFromMemList(), which allocates memory from a specific memory list, typically one that was created by the task for doing its own memory management.

Note: Tasks can only allocate memory from memory lists that belong to them. This means that user tasks cannot use AllocMemFromMemLists() to allocate memory directly from the system-wide free memory pool, because the memory in that pool belongs to the system.

If a task requests more memory from its free memory pool than is available, the kernel automatically allocates the necessary additional memory pages from the system-wide free memory pool if they are available. The task gets ownership of the additional memory and, when the memory is later freed, it is added to the task's free memory pool.

Arguments

l: A pointer to the memory pool from which to allocate the block.

size: The size of the memory block to allocate, in bytes.

memflags: Flags that specify the type of memory to allocate. These flags can include MEMTYPE_ANY, MEMTYPE_VRAM, MEMTYPE_DRAM, MEMTYPE_BANKSELECT, MEMTYPE_BANK1, MEMTYPE_BANK2, MEMTYPE_DMA, MEMTYPE_CEL, MEMTYPE_AUDIO, MEMTYPE_DSP, MEMTYPE_FILL, MEMTYPE_INPAGE, MEMTYPE_TRACKSIZE, MEMTYPE_STARTPAGE, and MEMTYPE_MYPOOL. For information about these flags, see the description of AllocMem().

Return Value

The procedure returns a pointer to memory block that was allocated or NULL if the memory couldn't be allocated.

Implementation

Folio call implemented in kernel folio V20.

Associated Files

mem.h: ANSI C Prototype

clib.lib: ARM Link Library

Notes

To free a memory block allocated with AllocMemFromMemLists(), use the FreeMemToMemLists() procedure.

You can enable memory debugging in your application by compiling your entire project with the MEMDEBUG value defined on the compiler's command-line. Refer to the CreateMemDebug() function for more details.