osCreateRegion, osMalloc, osFree, osGetRegionBufCount, osGetRegionBufSize
Provides arbitrary region memory allocation routines
#include <ultra64.h> /* ultra64.h */ void *osCreateRegion(void *startAddress, u32 length, u32 bufferSize, u32 alignSize); void *osMalloc(void *region); void osFree(void *region, void *addr); long osGetRegionBufCount(void *region); long osGetRegionBufSize(void *region);
These routines provide an easy and fast way to allocate and free fixed-size buffers from an arbitrary memory area. A region is a user-defined, physically contiguous block of memory. You can create any number of memory regions at run-time by calling osCreateRegion You must supply a block of memory large enough for the specific buffer size, including a certain overhead for the control structure.
This memory allocation scheme takes a small portion at the beginning of the input memory area to use as the region control header. The rest of the region is organized simply as a pool of equal-sized buffers. The buffer size is aligned to the number of bytes defined in the alignSize argument.
Upon creation, each region is given a unique region identifier. You can use this id to reference the region. because the id is actually the address of the control header for the region, any reference leads directly to it, without any searching.
Two easy calls, osMalloc and osFree, provide fast, dynamic allocation and de-allocation of buffers. No searching is needed - osMalloc takes the buffer at the head of the region's free list, and osFree puts the buffer back at the head of the free list.
The osCreateRegion routine creates a region from a given contiguous memory area starting at the address specified by the startAddress argument and extending for the number of bytes specified by the length argument.. This region is initialized to contain buffers of at least the size in bytes specified by the bufferSize argument. The alignSize argument specifies the number of bytes (including 2, 4, 8, and 16 bytes) used for aligning the buffer address and size. These values are defined in region.h as OS_RG_ALIGN_2B, OS_RG_ALIGN_4B, OS_RG_ALIGN_8B, and OS_RG_ALIGN_16B, respectively. If alignSize is 0, then the default value ( (OS_RG_ALIGN_DEFAULT) that is 8 bytes (64 bits) is used.
The osCreateRegion function returns an opaque pointer to where the region starts. This pointer is used as a unique region identifier in other region routines.
osMalloc returns a pointer to a buffer from the region that is aligned according to the byte boundary specified by the osCreateRegion function's alignSize argument. The buffer size is defined when osCreateRegion routine is called.
The addr argument in osFree is the pointer to a buffer previously allocated by osMalloc. The osFree routine returns this buffer to the region's free list after it performs a sanity check on the buffer address.
The osGetRegionBufCount function returns the total number of buffers created for the region. The osGetRegionBufSize function returns the size (in bytes) allocated for each buffer in the region.
Currently, a region can have up to a maximum of 32,768 buffers. Upon initialization, the region's starting address is automatically aligned to the boundary specified by the alignSize argument. Its buffer size (in bytes) is rounded up to be alignSize aligned.
You need to be extremely careful that you do not create multiple regions pointing to the same memory address. This will cause unexpected behavior because this scheme does not perform any memory check during region creation.
osCreateRegion returns a NULL pointer if one of the following conditions is encountered:
osMalloc also returns a NULL if there is no available free buffer in the region.
osCreateRegion, osGetRegionBufCount, and osGetRegionBufSize
1999/04/30 Changed format