# AllocMem

Allocate a memory block of a specific type.

### Synopsis

`void *AllocMem( int32 s, uint32 t )`

### Description

This macro allocates a memory block of a specific type.

### Arguments

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

t
  Flags that specify the type, alignment, and fill characteristics of memory to allocate.

One of the following flags must be set:

MEMTYPE_ANY
  Any memory can be allocated.

MEMTYPE_VRAM
  Allocate only video random-access memory (VRAM).

MEMTYPE_DRAM
  Allocate only dynamic random-access memory (DRAM).

If a block of VRAM must come from a specific VRAM bank, the following flag must be set:

MEMTYPE_BANKSELECT
  Allocate VRAM from a specific VRAM bank. In addition, one of the following two VRAM bank selection flags must be set:

MEMTYPE_BANK1
  Allocate only memory from VRAM bank 1.

MEMTYPE_BANK2
  Allocate only memory from VRAM bank 2.

The following flags are provided for compatibility with future hardware. You can set them in addition to the preceding flags.

MEMTYPE_DMA
  Allocate only memory that is accessible via direct memory access (DMA). Currently, all memory is accessible via DMA, but this may not be true in future hardware. Set this flag if you know the memory must be accessible via DMA.

MEMTYPE_CEL
  Allocate only memory that is accessible to the cel engine. Currently, all memory is accessible to the cel engine, but this may not be true in future hardware. Set this flag if you know the memory will be used for graphics.

MEMTYPE_AUDIO
  Allocate only memory that can be used for audio data (such as digitized sound). Currently, all memory can be used for audio, but this may not be true in future hardware. Set this flag if you know the memory will be used for audio data.

MEMTYPE_DSP
  Allocate only memory that is accessible to the digital signal processor (DSP). Currently, all memory is accessible to the DSP, but this may not be true in future hardware. Set this flag if you know the memory must be accessible to the DSP.

The following flags specify alignment, fill, and other allocation characteristics:

MEMTYPE_FILL
  Set every byte in the memory block to the value of the lower eight bits of the flags. If this flag is not set, the previous contents of the memory block are not changed. (Using 0 as the fill value can be useful for debugging: Any memory that is inadvertently changed can easily be detected.)

MEMTYPE_INPAGE
  Allocate a memory block that does not cross page boundaries.
  MEMTYPE_STARTPAGE
    Allocate a memory block that starts on a page boundary.
  MEMTYPE_MYPOOL
    Specifies that the memory block must be allocated only from the task's free memory pool. This means that if there is not sufficient memory in the task's pool, the kernel must not allocate additional memory from the system-wide free memory pool (see Notes).
  MEMTYPE_SYSTEMPAGESIZE
    Use the system's protection page size for that type of memory and not the special feature page size. This is necessary for MEMTYPE_VRAM to distinguish between allocations on page boundaries for graphics operations (normally 2 K) and task page sizes (normally 16 K).

  ### Return Value

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

  ### Implementation

  Macro implemented in mem.h V20.

  ### Associated Files

  mem.h
    C Macro Definition

  ### Notes

  Use `FreeMem()` to free a block of memory that was allocated with `AllocMem()`.

  If there is insufficient memory in a task's free memory pool to allocate the requested memory, the kernel automatically transfers the necessary pages of additional memory from the system-wide free memory pool to the task's free memory pool. The only exceptions are (1) when there is not enough memory in both pools together to satisfy the request, or (2) when the MEMTYPE_MYPOOL memory flag-which specifies that the memory block must be allocated only from the task's free memory pool-is set.

  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.

  ### See Also

  ``AllocMemBlocks`(), AllocMemFromMemList(), AllocMemList(), ControlMem(), FreeMem(), FreeMemList(), FreeMemToMemList(), malloc(), ScavengeMem(),`

  #