dbg Namespace Reference

The serial debug protocol. More...

Functions
void	begin (const char *hello)
	Start the protocol: at the top of setup().
void	poll ()
	Read and answer commands: at the top of loop(), before nextFrame().
void	markUpdateStart ()
	Frame timing for P: call when the logic tick starts.
void	markRenderStart ()
	Frame timing for P: call when drawing starts.
void	markRenderEnd ()
	Frame timing for P: call when drawing ends (before the flush).
void	print (const char *s)
	Send text to the host as it is (no newline added).
void	waitInput ()
	In the simulator, block until input may have arrived (elsewhere nothing).
uint32_t	parseNum (const char *&p, uint8_t base)
	Parse a number from a command's arguments, for a game's hook.
void	holdInto (bool(*busy)(char cmd), char *buf)
	Hold the game's commands while it is busy, in a caller's buffer.
void	holdWhile (bool(*busy)(char cmd))
	holdInto() with a buffer of its own (which exists only in a game that calls this).
void	frameStack (uint32_t *lo, uint32_t *hi)
	Report a second stack's high-water mark in P (fstk=): frames drawn from inside a search, for instance.
void	profStart ()
	Start a profiled frame (CHGAME_PROFILE builds): T reports averages per call.
void	prof (uint8_t slot)
	Charge the time since the previous prof() to a slot.

Variables
bool(*	hook )(char cmd, const char *args)
	The game's own commands, or nullptr.
static const uint8_t	LINE = 100
	The longest command line, in characters.

Detailed Description

The serial debug protocol.

Function Documentation

begin()

void dbg::begin

(

const char *

hello

)

Start the protocol: at the top of setup().

Parameters

hello

The line ? answers: the game's id and version (e.g. "CHCR 0.1"), so a tool can check it is talking to the right game. Each game needs its own id.

Also paints the stack for its high-water mark (P's stk=) and picks up the record of a crash before the last restart (!).

poll()

void dbg::poll

(

)

Read and answer commands: at the top of loop(), before nextFrame().

markUpdateStart()

void dbg::markUpdateStart

(

)

Frame timing for P: call when the logic tick starts.

markRenderStart()

void dbg::markRenderStart

(

)

Frame timing for P: call when drawing starts.

markRenderEnd()

void dbg::markRenderEnd

(

)

Frame timing for P: call when drawing ends (before the flush).

print()

void dbg::print

(

const char *

s

)

Send text to the host as it is (no newline added).

Parameters

s

The text.

waitInput()

void dbg::waitInput

(

)

In the simulator, block until input may have arrived (elsewhere nothing).

parseNum()

uint32_t dbg::parseNum	(	const char *&	p,
		uint8_t	base
	)

Parse a number from a command's arguments, for a game's hook.

Parameters

p	The text; skips leading spaces and commas, and is left after the number.
base	10 or 16.

Returns

The number (0 if there are no digits).

holdInto()

void dbg::holdInto	(	bool(*)(char cmd)	busy,
		char *	buf
	)

Hold the game's commands while it is busy, in a caller's buffer.

A game busy with something long (a search) can hold its commands: while busy(cmd) is true a command waits (answered HELD at once, OK/ERR once it has run) while N, S, P and the rest go on working.

Parameters

busy	Returns true while a command must wait.
buf	LINE bytes for the waiting command.

holdWhile()

void dbg::holdWhile ( bool(*)(char cmd)  busy )

inline

holdInto() with a buffer of its own (which exists only in a game that calls this).

Parameters

busy	Returns true while a command must wait.

frameStack()

void dbg::frameStack	(	uint32_t *	lo,
		uint32_t *	hi
	)

Report a second stack's high-water mark in P (fstk=): frames drawn from inside a search, for instance.

Parameters

lo,hi

The stack's bounds (it is painted now).

profStart()

void dbg::profStart

(

)

Start a profiled frame (CHGAME_PROFILE builds): T reports averages per call.

prof(i) charges the time since the previous prof() to slot i (0-11); T reports and resets the averages per profStart().

prof()

void dbg::prof

(

uint8_t

slot

)

Charge the time since the previous prof() to a slot.

Parameters

slot

0-11.

Variable Documentation

hook

bool(* dbg::hook) (char cmd, const char *args) ( char  cmd, const char *  args  )

extern

The game's own commands, or nullptr.

Called with the command's first character and the rest of the line; returns true if it handled the command (the host gets "OK"), false if not ("ERR").

LINE

const uint8_t dbg::LINE = 100

static

The longest command line, in characters.