TRACE

Print a message in the debugging log.

Opcode	Bytes	Cycles	Form	Example
$12	1	1 + 5	`TRACE`	`TRACE`
$23	2	1 + 5	`TRACE {U_BYTE}`	`TRACE 123`
$B1	4	1 + 5	`TRACE {U_TRIO}`	`TRACE $12_3ABC`
$24	2	2 + 5	`TRACE I:_`	`TRACE I:4`

Notes

The TRACE instruction typically will print a message to the debugger's log output, which is useful to track the state of your program as it is running. However, its behavior is customizable.
This instruction implements the Hybrix language's KERNEL::TRACE() and KERNEL::TRACE_INT() functions.
This instruction invokes a CPU event handler, which adds 5 clock cycles, plus whatever time is spent handling the event.
The operand is a trace ID number. If the number is greater than 255, the debugger will interpret it as a memory address, and expect to find a string message there. Otherwise, the number is printed.
This instruction does not affect the CPU condition flags. By convention, before it returns the event handler implementation should restore the entire CPU state including flags.

Trace ID	Meaning
0	Reported by `TRACE` without an operand.
1 – 239	Custom IDs available for the user's program.
240 – 255	Reserved for usage by the Hybrix framework.
254	Reported during a manual garbage collection, immediately before the "mark" operation.
255	Reported during an automatically triggered garbage collection, immediately before the "mark" operation.
≥256	Values larger than 255 will be interpreted as a memory address containing a custom text string to display.