Cosm API - Main Include and Self-tests

[Cosm Logo]

Main Include and Self-tests

Build Setup, Porting, and Debugging Tools

Required Defines
Optional Defines

Data Types and Predefined Strings

Data Types
Defined Strings and Things

Macros

_COSM_SET
_COSM_EQ

Self Tests

CosmTest

Required Defines

The required defines are: CPU bits, CPU type, and OS type. You will find a TEMPLATE file in the make/ directory of the source. Unless you are porting the libraries to a new platform, these will already be set and usable with the `build` script.

CPU_64BIT or CPU_32BIT - CPU bitness

Either CPU_32BIT or CPU_64BIT must be defined, not both.

CPU_TYPE - CPU type

The CPU type is set by defining CPU_TYPE to be one of the following. Note that valid values of CPU_TYPE are from 0 to COSM_CPU_TYPE_MAX inclusive. The array COSM_CPU_TYPES of CPU names will also be of use to programmers, see below.

CPU_UNKNOWN
CPU_X86
CPU_PPC
CPU_PPC64
CPU_MIPS
CPU_MIPS64
CPU_ALPHA
CPU_68K
CPU_SPARC
CPU_SPARC64
CPU_IA64
CPU_ARM
CPU_X64

OS_TYPE - OS type

The OS is set by defining OS_TYPE to be one of the following. Note that valid values of OS_TYPE are from 0 to COSM_OS_TYPE_MAX inclusive. The array COSM_OS_TYPES of OS names will also be of use to programmers, see below.

OS_UNKNOWN
OS_WIN32
OS_WIN64
OS_MACOSX
OS_LINUX
OS_NETBSD
OS_FREEBSD
OS_OPENBSD
OS_IRIX
OS_IRIX64
OS_SUNOS
OS_SOLARIS
OS_QNX
OS_TRU64

Optional Defines

NO_FLOATING_POINT: Compile Cosm libraries without floating point support.
NO_NETWORKING: Compile Cosm libraries without support for network functions.
NO_CRYPTO: Compile Cosm libraries without support for non-hash cryptographic functions, this allows for worldwide product export from the US. Products with crypto should involve one or more people outside the US.
ALLOW_UNSAFE_C: cosm.h will redefine dangerous or replaced functions from the standard C library. To use the replaced functions you must use this define. If you do use these functions, your code will NOT be portable and you will not be warned about DANGEROUS functions.
MEM_LEAK_FIND: Enable CosmMemDumpLeaks and related functionality for doing memory leak hunting.
NET_LOG_PACKETS: Enable packet logging to files. This can generate VERY large log files quickly, but is extremely useful for debugging.

Data Types

Cosm defines the following portable data types:

Note that the 32, 16, and 8-bit types can be used normally, however the 64-bit and 128-bit types must use special functions (os_math) for math, and special macros (_COSM_SET and _COSM_EQ) for setting constants to maintain portability.

Integer Types

  u8    Unsigned 8-bit integer.
  s8    Signed 8-bit integer.
  u16   Unsigned 16-bit integer.
  s16   Signed 16-bit integer.
  u32   Unsigned 32-bit integer.
  s32   Signed 32-bit integer.
  u64   Unsigned 64-bit integer.
  s64   Signed 64-bit integer.
  u128  Unsigned 128-bit integer.
  s128  Signed 128-bit integer.

Floating Point Types

  f32   32-bit floating point value, ~7 significant digits.
  f64   64-bit floating point value, ~16 significant digits.
  f128  Longest floating point value available up to 128-bits.
        ~16-34 significant digits depending on the system.

Make no assumptions about the size of f128. Not only the CPU, but the compiler and the system libraries must support f128 types for it to work at all. This is for hardcore math, those who need it know what it is, and if you don't then you probably only need to use f32.

Text Types

  ascii     ASCII type. Cosm apps never use char, not even in CPU/OS.
  utf8      Unicode UTF-8 type for strings. For user interaction.
  utf8char  Single Unicode codepoint, 32-bit.

Since UTF-8 is fully compatable with ASCII, you can feed any utf8 function a normal ascii string with a simple typecast to eliminate the compiler warning.

It's very important to understand that "utf8 string[128];" is 128 bytes for storing UTF-8, not 128 unicode characters. Some reading about Unicode and UTF-8 is required before using many of the functions in os_io and interfacing with your operating syetem's GUI API.

Time Type

  cosmtime  Time value.

Times are signed s128's of type cosmtime, 64b.64b format based 0 = 00:00:00 UTC, Jan 1, 2000 AD. This gives a Range of +/- 2.923E11 years and a resolution of 5.421E-20 seconds. This allows times from bang to crunch - assuming a closed universe (if it's not closed, we have bigger problems). It's also useful for timing the half lives of particles like neutral sigma baryons.

For all math on cosmtime values, CosmS128* functions must be used. If all you need is the seconds for timestamps, that is always a s64 in cosmtime.hi, and the fraction of a second is a u64 in cosmtime.lo - both still then require CosmSave to be used. You should never be stuffing data back into a cosmtime except with CosmU128Load, since once you discard the precision it is gone.

Defined Strings and Things

Strings

cputypes.h defines the string arrays COSM_CPU_TYPES and COSM_OS_TYPES. These are mostly for debugging output, since the CPU and OS are not relivant in most cases.

Example

  const ascii * cpu_types[] = COSM_CPU_TYPES;
  const ascii * os_types[] = COSM_OS_TYPES;

  CosmPrint( "CPU = %.20s, OS = %.20s\n",
    cpu_types[( CPU_TYPE > COSM_CPU_TYPE_MAX ) ? 0 : CPU_TYPE],
    os_types[( OS_TYPE > COSM_OS_TYPE_MAX ) ? 0 : OS_TYPE] );

Endian

COSM_ENDIAN_CURRENT, COSM_ENDIAN_BIG, and COSM_ENDIAN_LITTLE are defined. COSM_ENDIAN_CURRENT is whichever one the machine is running in at the time. This allows you to check the endian at compile time or at run time. In almost all cases compile time checking leads to faster code, but for statistics/reporting you will need the run time value.

Example

  /* Compile time checking */

  #if ( COSM_ENDIAN_CURRENT == COSM_ENDIAN_BIG )
    /* do the big thing */
  #else
    /* do the little thing */
  #endif

  /* Runtime checking */

  if ( COSM_ENDIAN_CURRENT == COSM_ENDIAN_BIG )
  {
    /* do the big thing */
  }
  else
  {
    /* do the little thing */
  }

Misc

COSM_PASS, COSM_FAIL, and NULL are defined.

On a CPU_32BIT system the compiler directly provides a fake 64-bit type. This will generally be faster then using C code for 64-bit operations. But for specific code you may get better performance by #ifdef testing CPU_32BIT or CPU_64BIT and writing specific code for each.

_COSM_SET

Description

Sets or initializes a 64-bit or 128-bit integer (signed or unsigned) to a constant value.

64-bit Types

The first argument is the variable to be set, followed by the value in hex (without the '0x' prefix), in groups of 32 bits, 2 groups total.

Example

  u64 a;
  s64 b;

  a = 0x4FF4642312345678LL;
  /* a is now 0x4FF4642312345678 */

  b = 0x49FDC23887654321LL;
  /* b is now 0x49FDC23887654321 */

128-bit Types

The first argument is the variable to be set, followed by the value in hex (without the '0x' prefix), in groups of 32 bits, 4 groups total.

Example

  u128 a;
  s128 b;

  _COSM_SET128( a, 0123456789ABCDEF, FEDCBA9876543210 );
  /* a is now 0x0123456789ABCDEFFEDCBA9876543210 */

  _COSM_SET128( b, 32507DFFDAF85A34, 7AF51C3445A54391 );
  /* b is now 0x32507DFFDAF85A347AF51C3445A54391 */

_COSM_EQ

Description

Compares a 64-bit or 128-bit integer (signed or unsigned) variable to a constant. Returns non-zero if equal, and 0 if unequal.

64-bit Types

The first argument is the variable to be compared to a constant, followed by the constant to compare it to in hex (without the '0x' prefix), in groups of 32 bits, 2 groups total.

Example

  u64 a;
  s64 b;

  a = 0x4FF4642312345678LL;
  if ( ( a == 0x4FF4642312345678LL ) )
  {
    /* equal */
  }

  b = 0x49FDC23887654321LL;
  if ( ( b == 0x49FDC23887654321LL ) )
  {
    /* equal */
  }

128-bit Types

The first argument is the variable to be compared to a constant, followed by the constant to compare it to in hex (without the '0x' prefix), in groups of 32 bits, 4 groups total.

Example

  u128 a;
  s128 b;

  _COSM_SET128( a, 0123456789ABCDEF, FEDCBA9876543210 );
  if ( _COSM_EQ128( a, 0123456789ABCDEF, FEDCBA9876543210 ) )
  {
    /* equal */
  }

  _COSM_SET128( b, 32507DFFDAF85A34, 7AF51C3445A54391 );
  if ( _COSM_EQ128( a, 32507DFFDAF85A34, 7AF51C3445A54391 ) )
  {
    /* equal */
  }

CosmTest

Syntax

#include "cosm.h"
s32 CosmTest( s32 * failed_module, s32 * failed_test, s32 module_num );

Description

If module_num is 0, then test all Cosm functions and return a negative number corresponding to the module that failed. failed_module and failed_test will be set to the corresponding failed functions. Otherwise test only the module module_num.

See example below for useable of COSM_TEST_MODULE_MAX and __cosm_test_modules, defined in cosm.h.

Return Values

COSM_PASS on success, or a negative number corresponding to the module that failed.

Errors

A negative number will be returned corresponding to the module/test that failed.

Example

  s32 error;
  s32 error2;

  CosmPrint( "\nRunning system tests... " );
  if ( CosmTest( &error, &error2, 0 ) != COSM_PASS )
  {
    CosmPrint( "Test failure in module %.16s %i.\n",
      __cosm_test_modules[( -error > COSM_TEST_MODULE_MAX ) ?
      0 : -error].name, error2 );
    CosmProcessEnd( error );
  }
  CosmPrint( "all passed.\n" );