.TH osCreateLog 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
osCreateLog, osLogEvent, osFlushLog \- logging utility
.SH SYNOPSIS
.nf
\f3
.Op c
#include <ultra64.h>
.sp .8v
void osCreateLog(OSLog \(**log, u32 \(**base, s32 len);
.sp .8v
void osLogEvent(OSLog \(**log, s16 code, s16 numArgs, ...);
.sp .8v
void osFlushLog(OSLog \(**log);
.Op
\f1
.fi
.SH DESCRIPTION
Logging provides an alternate mechanism to
.IR osSyncPrintf (3P)
for formatted character string output that has a lesser immediate
performance impact.
Logging works by buffering the output information in DRAM for later,
delaying the relatively expensive transfer to and formatting by the host.
Conversely,
.I osSyncPrintf
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 the debug of real-time problems
or performance analysis.
.PP
An
.I OSLog
data structure acts as a handle by which an individual log is referenced
by the logging routines.
The
.I osCreateLog
function initializes this structure.
The
.I base
argument is a pointer to a memory region of
.I len
32 bit words that will hold the actual log data.
.PP
The
.I osLogEvent
routine adds an entry to the given
.I log.
The log entry begins with a 16 bit
.I code,
followed by an additional argument
count
.I numArgs,
and finally the additional
arguments themselves.
There may be no more than
.I 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.
.PP
The
.I osFlushLog
routine transfers the log data to the host,
where the
.IR gload (1P)
program will interpret and print the log.
The
.I gload
program will look up the logging code in a format file and apply the
format string to the remaining arguments.
For example, suppose the format file had the following line:
.Ex
10	"The hexadecimal equivalent of %d is 0x%x"
.Ee
Then the following call:
.Ex
osLogEvent(log, 10, 2, 16, 16);
.Ee
Would cause
.I gload
to output:
.Ex
0xXXXXXXX (0010): The hexadecimal equivalent of 16 is 0x10
.Ee
.SH "SEE ALSO"
.IR gload (1P)