Cosm API - Memory Functions

[Cosm Logo]

Memory Functions

CosmMemAlloc
CosmMemRealloc
CosmMemCopy
CosmMemSet
CosmMemCmp
CosmMemOffset
CosmMemFree
CosmMemSystem
CosmMemWarning
CosmMemDumpLeaks

CosmMemAlloc

Syntax

#include "cosm/os_mem.h"
void * CosmMemAlloc( 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 COSM_MEM_NORMAL no special requirements are needed.

If secure is COSM_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, CosmMemWarning 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;

  size = 0x0000000000000400LL;
  mem = CosmMemAlloc( size );
  if ( mem == NULL )
  {
    /* Error */
    return COSM_FAIL;
  }

CosmMemRealloc

Syntax

#include "cosm/os_mem.h"
void * CosmMemRealloc( 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 CosmMemAlloc. The secure flag will be treated as it is in CosmMemAlloc. 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;

  size = 0x0000000000000400LL;
  mem = CosmMemAlloc( size );
  if ( mem == NULL )
  {
    /* Error */
    return COSM_FAIL;
  }

  size = 0x0000000000000200LL;
  small = CosmMemRealloc( mem, size, 0 );
  if ( small == NULL )
  {
    /* Error */
    return COSM_FAIL;
  }

CosmMemCopy

Syntax

#include "cosm/os_mem.h"
s32 CosmMemCopy( void * dest, const void * src, u64 length );

Description

Copy length bytes of memory from src to dest.

Return Values

COSM_PASS on success, or COSM_FAIL on failure.

Errors

None.

Example

  void * old;
  void * new;
  u64 size;

  size = 0x0000000000000400LL;
  old = CosmMemAlloc( size );
  if ( old == NULL )
  {
    /* Error */
    return COSM_FAIL;
  }

  new = CosmMemAlloc( size );
  if ( new == NULL )
  {
    /* Error */
    return COSM_FAIL;
  }

  if ( CosmMemCopy( new, mem, size ) == COSM_FAIL )
  {
    /* Error */
    return COSM_FAIL;
  }

CosmMemSet

Syntax

#include "cosm/os_mem.h"
s32 CosmMemSet( void * memory, u64 length, u8 value );

Description

Set length bytes of memory to value.

Return Values

COSM_PASS on success, or COSM_FAIL on failure.

Errors

Passing a NULL parameter or wrapping around the top of memory.

Example

  u64 size;
  void * mem;
  void * small;

  size = 0x0000000000000400LL;
  mem = CosmMemAlloc( size );
  if ( mem == NULL )
  {
    /* Error */
    return COSM_FAIL;
  }

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

CosmMemCmp

Syntax

#include "cosm/os_mem.h"
s32 CosmMemCmp( 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;

  size = 0x0000000000000100LL;
  if ( ( diff = CosmMemCmp( memA, memB, size ) ) == 0 )
  {
    /* memory blocks are the same */
  }

CosmMemOffset

Syntax

#include "cosm/os_mem.h"
void * CosmMemOffset( 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;

  offset = 0x0000000000000100LL;

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

CosmMemFree

Syntax

#include "cosm/os_mem.h"
void CosmMemFree( void * memory );

Description

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

Return Values

None.

Errors

None.

Example

  u64 size;
  void * mem;

  size = 0x0000000000000400LL;
  mem = CosmMemAlloc( size );
  if ( mem == NULL )
  {
    /* Error */
    return COSM_FAIL;
  }

  CosmMemFree( mem );

CosmMemSystem

Syntax

#include "cosm/os_mem.h"
s32 CosmMemSystem( u64 * amount );

Description

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

Return Values

COSM_PASS on success, or COSM_FAIL on failure.

Errors

Possible causes of an failure:

This function is not supported correctly by all operating systems. Linux < 2.3.23 will not correctly report more then 4GiB of RAM.

Example

  u64 memory_size;
  void * mem;

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

CosmMemWarning

Syntax

#include "cosm/os_mem.h"
void * CosmMemWarning( 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

  CosmMemWarning();

CosmMemDumpLeaks

Syntax

#include "cosm/os_mem.h"
s32 CosmMemDumpLeaks( const ascii * filename );

Description

Write out a list of memory that has not been CosmMemFeee'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

COSM_PASS on success, or COSM_FAIL on failure.

Errors

Any errors will be related to opening the file..

Example

  CosmMemDumpLeaks( "leaks.txt" );