# CPUSim64 Library Reference

The CPUSim64 comes with many library functions to make programming in CPU64 assembly easier. These functions are defined in `.asm` files and included using the `#include` preprocessor directive. Functions use stack-based calling conventions for arguments and return a value in `R0` or `F0`.

Libraries also contain macros that use register-based calling conventions. Macros are defined in `.def` files along with the definitions for interrupts used by that library. When invoking macros, there is no guarantee that the registers `R0`, `R1`, `R2`, `F0`, `F1` or `F2` will be preserved. Most macros return a value in `R0` or `F0`.

### <system/debug.def>

These debug macros only compile into your code if the assembler is passed the `--DEBUG` option. This allows you to retain debugging instructions and still create "non-debug" code that doesn't have the debugging instructions present just by omitting the `--DEBUG` option.

Macro | Description
--- | ---
DEBUG_MSG | `DEBUG_MSG(fmt, ...)` Formats a printf-style format string using the variable number of arguments supplied and prints it as a debug message.
COND_DEBUG_MSG | `COND_DEBUG_MSG(cond, fmt, ...)` Formats a prinf-style format string using the variable number of arguments supplied and prints it as a debug message if the argument `cond` is true, otherwise it prints nothing.
PRINTCPU | `PRINTCPU`Prints the current state of the CPU.
SET_EXIT_ON_ASSERT_FAILURE | `SET_EXIT_ON_ASSERT_FAILURE(b)` Sets the mode for asserts. If the argument `b` is true, assert macros will print message and then exit the program if they fail. Otherwise assert macros will print a message if they fail but not exit. Default is true.
ASSERT_TRUE | `ASSERT_TRUE(isTrue, message)` Asserts that a condition is true. Prints the message if the assertion fails.
ASSERT_FALSE | `ASSERT_FALSE(isFalse, message)` Asserts that a condition is false. Prints the message if the assertion fails.
ASSERT_EQ | `ASSERT_EQ(expected, actual, message)` Asserts that integer values `expected` and `actual` are equal. Prints the message if the assertion fails.
ASSERT_NE | `ASSERT_NE(expected, actual, message)` Asserts that integer values `expected` and `actual` are not equal. Prints the message if the assertion fails.
ASSERT_GT | `ASSERT_GT(expected, actual, message)` Asserts that integer value `expected` is greater than `actual`. Prints the message if the assertion fails.
ASSERT_LT | `ASSERT_LT(expected, actual, message)` Asserts that integer value `expected` is less than `actual`. Prints the message if the assertion fails.
ASSERT_GE | `ASSERT_GE(expected, actual, message)` Asserts that integer value `expected` is greater than or equal to `actual`. Prints the message if the assertion fails.
ASSERT_LE | `ASSERT_LE(expected, actual, message)` Asserts that integer value `expected` is less than or equal to `actual`. Prints the message if the assertion fails.
ASSERT_EQ_FP | `ASSERT_EQ_FP(expected, actual, message)` Asserts that floating point values `expected` and `actual` are equal. Prints the message if the assertion fails.
ASSERT_NE_FP | `ASSERT_NE_FP(expected, actual, message)` Asserts that floating point values `expected` and `actual` are not equal. Prints the message if the assertion fails.
ASSERT_GT_FP | `ASSERT_GT_FP(expected, actual, message)` Asserts that floating point value `expected` is greater than `actual`. Prints the message if the assertion fails.
ASSERT_LT_FP | `ASSERT_LT_FP(expected, actual, message)` Asserts that floating point value `expected` is less than `actual`. Prints the message if the assertion fails.
ASSERT_GE_FP | `ASSERT_GE_FP(expected, actual, message)` Asserts that floating point value `expected` is greater than or equal to `actual`. Prints the message if the assertion fails.
ASSERT_LE_FP | `ASSERT_LE_FP(expected, actual, message)` Asserts that floating point value `expected` is less than or equal to `actual`. Prints the message if the assertion fails.

The floating point assertion macros require that both float values be registers. The integer assertion macros can use a register or a literal for the values.