.TH osCreateRegion 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
osCreateRegion, osMalloc, osFree, osGetRegionBufCount, osGetRegionBufSize \- arbitrary region memory allocation routines
.SH SYNOPSIS
.nf
\f3
.Op c
#include <ultra64.h>
.sp .8v
void \(**osCreateRegion(void *startAddress, u32 length, 
				 u32 bufferSize, u32 alignSize);
.sp .8v
void \(**osMalloc(void *region);
.sp .8v
void osFree(void \(**region, void *addr);
.sp .8v
long osGetRegionBufCount(void \(**region);
.sp .8v
long osGetRegionBufSize(void \(**region);
.Op
\f1
.fi
.SH DESCRIPTION
These routines provide a simple and fast mechanism to allocate and free
fixed-size buffers from an arbitrary memory area.
A region is a user-defined, physically contiguous block of memory, divided
into a set of equal-sized buffers. Any number of memory regions can be
created at run-time, using the 
.I osCreateRegion 
call. The user must supply a block of memory large enough for the specific 
buffer size, including a certain overhead for control structure.
.PP
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
.I alignSize.
.PP
Upon creation, each region is given a unique region identifier. The
user uses this id to reference the region. Since the id is actually
the address of the control header for the region, any reference leads
directly to it, without any searching.
.PP
Two simple calls,
.I osMalloc
and
.I osFree, 
provide fast, dynamic allocation and de-allocation of buffers. 
No searching is needed - 
.I osMalloc 
takes the buffer at the head of the region's free list, 
.I osFree 
puts the buffer back at the head of the free list.
.PP
The
.I osCreateRegion
routine creates a region from a given contiguous memory area starting at address
.I startAddress
and extending for
.I length
bytes. This region is initialized to contain buffers of at-least size
.I bufferSize
(in bytes).
.I alignSize
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 
.I region.h
as
.I OS_RG_ALIGN_2B, OS_RG_ALIGN_4B, OS_RG_ALIGN_8B,
and
.I OS_RG_ALIGN_16B,
respectively. If 
.I alignSize
is 0, then the default value (
.I (OS_RG_ALIGN_DEFAULT)
which is 8 bytes (64 bits) is used.
.I osCreateRegion
returns an opaque pointer to where the region starts. This pointer is used 
as a unique region identifier in other region routines.
.PP
.I osMalloc
returns a pointer to an buffer from the 
.I region. 
that is aligned according to 
.I alignSize
bytes.
The buffer size is defined when calling the
.I osCreateRegion 
routine.
.PP
The argument
.I addr
in
.I osFree
is the pointer to a buffer previously allocated by
.I osMalloc.
.I osFree
returns this buffer to the region's free list after performs sanity check
on the buffer address.
.PP
.I osGetRegionBufCount 
returns the total number of buffers created for the 
.I region.
Similarly, 
.I osGetRegionBufSize 
returns the size (in bytes) allocated for each buffer in the 
.I region.
.PP
.SH DIAGNOSTICS
.I osCreateRegion 
returns a NULL pointer if one of the following conditions is encountered: 
(1) null start address, (2) length or buffer size is less than 0, or 
(3) buffer size is greater than the actual length remained for storing data.
.I osMalloc
will also return NULL if there is no available free buffer in the region.
.SH NOTES
Currently, a region can only have up to 32,768 buffers. Upon initialization,
the region's starting address is automatically aligned to 
.I alignSize
boundary; 
similarly, its buffer size (in bytes) is also rounded up to be 
.I alignSize
aligned.
.PP
The user must take extreme caution to not create multiple regions
pointing to the same memory address. This will cause unexpected
behavior since this scheme does not perform any memory check during
region creation.