Cosm API - Memory Functions

[Cosm Logo]

Memory Functions

v3MemAlloc
v3MemRealloc
v3MemCopy
v3MemSet
v3MemCmp
v3MemOffset
v3MemFree
v3MemSystem
v3MemWarning
v3MemDumpLeaks

v3MemAlloc

Syntax

#include "cosmmem.h"
void * v3MemAlloc( u64 bytes, u32 secure );

Description

Allocate a block of zeroed memory. Will allocate 16*floor((bytes+15)/16)) bytes, i.e. blocks of 16 bytes, and only on 16 byte boundaries.

If secure is V3_MEM_NORMAL no special requirements are needed.

If secure is V3_MEM_SECURE the program will expect the following:

The memory will be protected from read or write from any other process including supervisor run programs or other processes owned by the same user, unless explicitly given access.
The memory will not be swapped or otherwise copied out of live RAM including during a crash triggered dump by the process.
The memory will not cross CPU boundaries.
The parts of the kernel in supervisor space will not be modified after boot.

If the secure flag cannot be enforced, v3MemWarning will be called and the function will return NULL. The user will then be warned any time that the system is insecure and the program attempts to do secure operations.

Return Values

An aligned pointer to the RAM block, or NULL on failure.

Errors

None.

Example

  u64 size;
  void * mem;

  _V3_SET64( size, 00000000, 00000400 );
  mem = v3MemAlloc( size, V3_MEM_NORMAL );
  if ( mem == NULL )
  {
    /* Error */
    return( V3_FAIL );
  }

v3MemRealloc

Syntax

#include "cosmmem.h"
void * v3MemRealloc( void * memory, u64 bytes, u32 secure );

Description

Adjust the size of the ram block memory to bytes length, copying any old data. If memory is NULL, this function acts like v3MemAlloc. The secure flag will be treated as it is in v3MemAlloc. If bytes is zero, then free the memory, and return NULL.

Any expanded memory space will have unknown values.

Return Values

A pointer to the new memory space on success, or NULL if unable to change the size - leaving the old memory unmodified.

Errors

None.

Example

  u64 size;
  void * mem;
  void * small;

  _V3_SET64( size, 00000000, 00000400 );
  mem = v3MemAlloc( size, V3_MEM_NORMAL );
  if ( mem == NULL )
  {
    /* Error */
    return( V3_FAIL );
  }

  _V3_SET64( size, 00000000, 00000200 );
  small = v3MemRealloc( mem, size, 0 );
  if ( small == NULL )
  {
    /* Error */
    return( V3_FAIL );
  }

v3MemCopy

Syntax

#include "cosmmem.h"
s32 v3MemCopy( void * dest, const void * src, u64 length );

Description

Copy length bytes of memory from src to dest.

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

None.

Example

  void * old;
  void * new;
  u64 size;

  _V3_SET64( size, 00000000, 00000400 );
  old = v3MemAlloc( size, V3_MEM_NORMAL );
  if ( old == NULL )
  {
    /* Error */
    return( V3_FAIL );
  }

  new = v3MemAlloc( size, V3_MEM_NORMAL );
  if ( new == NULL )
  {
    /* Error */
    return( V3_FAIL );
  }

  if ( v3MemCopy( new, mem, size ) == V3_FAIL )
  {
    /* Error */
    return( V3_FAIL );
  }

v3MemSet

Syntax

#include "cosmmem.h"
s32 v3MemSet( void * memory, u64 length, u8 value );

Description

Set length bytes of memory to value.

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

None.

Example

  u64 size;
  void * mem;
  void * small;

  _V3_SET64( size, 00000000, 00000400 );
  mem = v3MemAlloc( size, V3_MEM_NORMAL );
  if ( mem == NULL )
  {
    /* Error */
    return( V3_FAIL );
  }

  if ( v3MemSet( mem, size, 0xFF ) == V3_FAIL )
  {
    /* Error */
    return( V3_FAIL );
  }

v3MemCmp

Syntax

#include "cosmmem.h"
s32 v3MemCmp( const void * blockA, const void * blockB,
  u64 max_bytes );

Description

Compare the memory blocks blockA and blockB, up to max_bytes will be compared.

Return Values

0 if the blocks are identical. If they are different then a positive or negative based on blockA[x] - blockB[x]. Due to endian issues the +/- result may or may not be relivant. If any parameter is NULL/0 then it returns -1 unless blockA == blockB.

Errors

None.

Example

  u64 size;
  void memA[256];
  void memB[256];
  s32 diff;

  _V3_SET64( size, 00000000, 00000100 );
  if ( ( diff = v3MemCmp( memA, memB, size ) ) == 0 )
  {
    /* memory blocks are the same */
  }

v3MemOffset

Syntax

#include "cosmmem.h"
void * v3MemOffset( const void * memory, u64 offset );

Description

Calculates the address of memory + offset.

Return Values

A pointer to the data location, or NULL if address space is exceeded.

Errors

None.

Example

  u64 offset;
  void * memory;
  void * ptr;

  _V3_SET64( offset, 00000000, 00000100 );

  ptr = v3MemOffset( memory, offset );
  /* ptr is a pointer to 256 bytes past memory */

v3MemFree

Syntax

#include "cosmmem.h"
void v3MemFree( void * memory );

Description

Free the requested memory block memory. memory may safely be NULL.

Return Values

None.

Errors

None.

Example

  u64 size;
  void * mem;

  _V3_SET64( size, 00000000, 00000400 );
  mem = v3MemAlloc( size, V3_MEM_NORMAL );
  if ( mem == NULL )
  {
    /* Error */
    return( V3_FAIL );
  }

  v3MemFree( mem );

v3MemSystem

Syntax

#include "cosmmem.h"
s32 v3MemSystem( u64 * amount );

Description

Set amount to the number of bytes of physical RAM in the system.

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

Possible causes of an failure:

This function is not supported by all operating systems.

Example

  u64 memory_size;
  void * mem;

  if ( v3MemSystem( &memory_size ) != V3_PASS )
  {
    /* couldn't get memory total */
  }

v3MemWarning

Syntax

#include "cosmmem.h"
void * v3MemWarning( void );

Description

Force display of a warning message to the user, when secure memory is requested but not available.

Return Values

None.

Errors

None.

Example

  v3MemWarning();

v3MemDumpLeaks

Syntax

#include "cosmmem.h"
s32 v3MemDumpLeaks( const ascii * filename );

Description

Write out a list of memory that has not been v3MemFeee'd yet to filename. Due to the overhead of this function you must define MEM_LEAK_FIND when compiling the cosm libraries and your code, otherwise it will not exist.

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

Any errors will be related to opening the file..

Example

  v3MemDumpLeaks( (ascii *) "leaks.txt" );