osCreateLog osCreateLog (function)

osCreateLog, osLogEvent, osFlushLog

Is a logging utility


#include <ultra64.h>     /* ultra64.h */
void osCreateLog(OSLog *log, u32 *base, s32 len);
void osLogEvent(OSLog *log, s16 code, s16 numArgs, ....);
void osFlushLog(OSLog *log);


Logging provides an alternate mechanism to the osSyncPrintf tool for formatted character string output that has a lesser immediate performance impact. Logging is a relatively expensive transfer to formatting by the host. Conversely, the osSyncPrintf tool formats the given character string on the target and flushes the string back to the host immediately upon its invocation. Logging may be preferable for cases such as real-time debugging or for performance analysis.

An OSLog data structure acts as a handle by which an individual log is referenced by the logging routines.

The osCreateLog function initializes this structure. The base argument is a pointer to a memory region of len 32-bit words that will hold the actual log data.

The osLogEvent routine adds an entry to the given log. The log entry begins with a 16-bit code, followed by an additional argument count (numArgs), and finally the additional arguments themselves. There may be no more than OS_LOG_MAX_ARGS, or 16, additional arguments. The arguments are limited to 32-bit quantities, and may not be address pointers, including character strings.

The osFlushLog routine transfers the log data to the host, where the gload program interprets and print the log. The gload program looks up the logging code in a format file and applies the format string to the remaining arguments. Suppose the format file has this line:

10 "The hexadecimal equivalent of %d is 0x%x"

Then this call:

osLogEvent(log, 10, 2, 16, 16);

causes gload to output:

0xXXXXXXX (0010): The hexadecimal equivalent of 16 is 0x10

See Also


Revision History

1999/04/30 Changed format