When there is insufficient memory in a task's free memory pool to allocate a block of memory, the kernel automatically provides additional memory pages from the system-wide free memory pool. Tasks can also get pages from the system-wide free memory pool by calling AllocMemBlocks().
Note: Normal applications do not need to call this procedure. It should only be used by applications that need additional control over the memory-allocation process.
You must set MEMTYPE_TASKMEM in the typebits argument otherwise the memory will not be allocated to the current task.
AllocMemBlocks() is different from other memory-allocation procedures:
The pages of memory that are transferred are not automatically added to the task's free memory pool. To move the memory into its free memory pool, thereby making it available to tasks, the task must call one of the procedures for freeing memory (FreeMem(), FreeMemToMemList(), or FreeMemToMemLists()) with the pointer returned by AllocMemBlocks() as the argument. (Note that in the memory returned by AllocMemBlocks(), the first four bytes specify the amount of memory, in bytes, that was transferred. You should use this value as the size to be freed.)
Arguments
size
The amount of memory to transfer, in bytes. If the size is not an integer multiple of the page size for the type of memory requested, the system transfers the number of full pages needed to satisfy the request.
typebits
Flags that specify the type of memory to transfer. 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_TASKMEM. For information about these flags, see the description of AllocMem().
MEMTYPE_TASKMEM must always be set.
Return Value
The procedure returns a pointer to the pages of memory that were transferred or NULL if the memory couldn't be transferred. The first four bytes of the memory specify the amount of memory that was transferred, in bytes.
Implementation
SWI implemented in kernel folio V20.
Associated Files
mem.h
ARM C "swi" declaration
Notes
To return memory to the system-wide free memory pool, use ScavengeMem() or ControlMem(). ScavengeMem() finds pages of memory in the task's free memory pool from which no memory has been allocated and returns those pages to the system-wide memory pool. You can use ControlMem() to transfer ownership of memory to the system-wide memory pool.