====== AllocMemBlocks ======

Transfers pages of memory from the system-wide free memory pool.

==== Synopsis ====

''%%void *AllocMemBlocks( int32 size, uint32 typebits )%%''

==== Description ====

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.

==== See Also ====

''%%ControlMem%%''(), [[:documentation:development:opera:pf25:ppgfldr:pgsfldr:spr:01spr064#xref31542|FreeMem]](), [[:documentation:development:opera:pf25:ppgfldr:pgsfldr:spr:01spr066#xref14037|FreeMemToMemList]](), [[:documentation:development:opera:pf25:ppgfldr:pgsfldr:spr:01spr067#xref28914|FreeMemToMemLists]](), [[:documentation:development:opera:pf25:ppgfldr:pgsfldr:spr:01spr120#xref32080|ScavengeMem]]()

======  ======


----