rdpq_debug.c File Reference

RDP Command queue: debugging helpers. More...

Data Structures
struct	rdp_buffer_t
	A buffer sent to RDP via DMA. More...
struct	colorcombiner_t
	Decoded SET_COMBINE command. More...
struct	setothermodes_t
	Decoded SET_OTHER_MODES command. More...
struct	.busy
struct	.__unnamed10__
struct	.col
struct	.tex
struct	.clip

Macros
#define	RDPQ_CMD_DEBUG_SHOWLOG   0x00010000
	RDP Debug command: turn on/off logging.
#define	RDPQ_CMD_DEBUG_MESSAGE   0x00020000
	RDP Debug command: debug message.
#define	RDPQ_DEBUG_DEBUG   0
	Internal debugging of rdpq_debug.
#define	intdebugf(...)   ({ })
	Like debugf, but guarded by RDPQ_DEBUG_DEBUG.
#define	BITS(v, b, e)   ((unsigned int)((v) << (63-(e)) >> (63-(e)+(b))))
	Extract bits from word.
#define	BIT(v, b)   BITS(v, b, b)
	Extract bit from word.
#define	SBITS(v, b, e)   (int)BITS((int64_t)(v), b, e)
	Extract bits from word as signed quantity.
#define	CMD(v)   BITS((v), 56, 61)
	Extract command ID from RDP command word.
#define	CMD_IS_TRI(cmd)   ((cmd) >= 0x8 && (cmd) <= 0xF)
	Check if a command is a triangle.
#define	FX(n)   (1.0f / (1<<(n)))
	Multiplication factor to convert a number to fixed point with precision n.
#define	FX32(hi, lo)   ((int16_t)(hi) + (lo) * (1.f / 65536.f))
	Convert a 16.16 fixed point number into floating point.
#define	EMIT_TYPE   0x3
	Type of message (mask)
#define	EMIT_CRASH   0x0
	Message is a RDP crash.
#define	EMIT_ERROR   0x1
	Message is an error.
#define	EMIT_WARN   0x2
	Message is a warning.
#define	EMIT_CTX_SOM   0x4
	Message context must show last SOM.
#define	EMIT_CTX_CC   0x8
	Message context must show last CC.
#define	EMIT_CTX_TEX   0x10
	Message context must show last SET_TEX_IMAGE.
#define	EMIT_CTX_TILES   (0xFF << 5)
	Message context must show SET_TILE (mask)
#define	EMIT_CTX_TILE(n)   (0x20 << (n))
	Message context must show tile n.
#define	EMIT_CTX_TILESIZE   0x2000
	Message context must show LOAD_TILE/SET_TILE_SIZE instead of SET_TILE.
#define	__VALIDATE(flags, cond, msg, ...)
	Internal validation macros (for both errors and warnings)
#define	VALIDATE_CRASH(cond, msg, ...)   __VALIDATE(0, cond, msg, ##__VA_ARGS__)
	Check and trigger a RDP crash.
#define	VALIDATE_CRASH_SOM(cond, msg, ...)   __VALIDATE(4, cond, msg, ##__VA_ARGS__)
	Validate and trigger a crash, with SOM context.
#define	VALIDATE_CRASH_CC(cond, msg, ...)   __VALIDATE(8, cond, msg, ##__VA_ARGS__)
	Validate and trigger a crash, with CC context.
#define	VALIDATE_CRASH_TEX(cond, msg, ...)   __VALIDATE(16, cond, msg, ##__VA_ARGS__)
	Validate and trigger a crash, with SET_TEX_IMAGE context.
#define	VALIDATE_CRASH_TILE(cond, tidx, msg, ...)   __VALIDATE(EMIT_CRASH | EMIT_CTX_TILE(tidx), cond, msg, ##__VA_ARGS__)
	Validate and trigger a crash, with tile context.
#define	VALIDATE_CRASH_TILESIZE(cond, tidx, msg, ...)   __VALIDATE(EMIT_CRASH | EMIT_CTX_TILE(tidx) | EMIT_CTX_TILESIZE, cond, msg, ##__VA_ARGS__)
	Validate and trigger a crash, with tile extents context.
#define	VALIDATE_ERR(cond, msg, ...)   __VALIDATE(1, cond, msg, ##__VA_ARGS__)
	Check and trigger a RDP validation error.
#define	VALIDATE_ERR_SOM(cond, msg, ...)   __VALIDATE(5, cond, msg, ##__VA_ARGS__)
	Validate and trigger an error, with SOM context.
#define	VALIDATE_ERR_CC(cond, msg, ...)   __VALIDATE(9, cond, msg, ##__VA_ARGS__)
	Validate and trigger an error, with CC context.
#define	VALIDATE_ERR_TEX(cond, msg, ...)   __VALIDATE(17, cond, msg, ##__VA_ARGS__)
	Validate and trigger an error, with SET_TEX_IMAGE context.
#define	VALIDATE_ERR_TILE(cond, tidx, msg, ...)   __VALIDATE(EMIT_ERROR | EMIT_CTX_TILE(tidx), cond, msg, ##__VA_ARGS__)
	Validate and trigger an error, with tile context.
#define	VALIDATE_ERR_TILESIZE(cond, tidx, msg, ...)   __VALIDATE(EMIT_ERROR | EMIT_CTX_TILE(tidx) | EMIT_CTX_TILESIZE, cond, msg, ##__VA_ARGS__)
	Validate and trigger an error, with tile extents context.
#define	VALIDATE_WARN(cond, msg, ...)   __VALIDATE(2, cond, msg, ##__VA_ARGS__)
	Check and trigger a RDP validation warning.
#define	VALIDATE_WARN_SOM(cond, msg, ...)   __VALIDATE(6, cond, msg, ##__VA_ARGS__)
	Validate and trigger a warning, with SOM context.
#define	VALIDATE_WARN_CC(cond, msg, ...)   __VALIDATE(10, cond, msg, ##__VA_ARGS__)
	Validate and trigger a warning, with CC context.
#define	VALIDATE_WARN_TEX(cond, msg, ...)   __VALIDATE(18, cond, msg, ##__VA_ARGS__)
	Validate and trigger a warning, with SET_TEX_IMAGE context.
#define	VALIDATE_WARN_TILE(cond, tidx, msg, ...)   __VALIDATE(EMIT_WARN | EMIT_CTX_TILE(tidx), cond, msg, ##__VA_ARGS__)
	Validate and trigger an error, with tile context.
#define	VALIDATE_WARN_TILESIZE(cond, tidx, msg, ...)   __VALIDATE(EMIT_WARN | EMIT_CTX_TILE(tidx) | EMIT_CTX_TILESIZE, cond, msg, ##__VA_ARGS__)
	Validate and trigger a warning, with tile extents context.

Functions
int	rdpq_debug_disasm_size (uint64_t *buf)
	Return the size of the next RDP commands.
bool	rdpq_debug_disasm (uint64_t *buf, FILE *out)
	Disassemble a RDP command.
void	rdpq_validate (uint64_t *buf, uint32_t flags, int *r_errs, int *r_warns)
	Validate the next RDP command, given the RDP current state.

Variables
int	__rdpq_debug_log_flags
	Flags that configure the logging.
struct {
uint64_t *	buf
	Current instruction.
uint32_t	flags
	Flags (see RDPQ_VALIDATION_*)
int	warns
int	errs
	Validators warnings/errors (stats)
bool	crashed
	True if the RDP chip crashed.
}	vctx
	Validator context.

Detailed Description

RDP Command queue: debugging helpers.

---

Data Structure Documentation

rdp_buffer_t

struct rdp_buffer_t

A buffer sent to RDP via DMA.

Data Fields
uint64_t *	start	Start pointer.
uint64_t *	end	End pointer.
uint64_t *	traced	End pointer of already-traced commands.

colorcombiner_t

struct colorcombiner_t

Decoded SET_COMBINE command.

setothermodes_t

struct setothermodes_t

Decoded SET_OTHER_MODES command.

.busy

struct .busy

Data Fields
bool	pipe	True if the pipe is busy (SYNC_PIPE required)
bool	tile[8]	True if each tile is a busy (SYNC_TILE required)
uint8_t	tmem[64]	Bitarray: busy state for each 8-byte word of TMEM (SYNC_LOAD required)

.__unnamed10__

struct .__unnamed10__

Data Fields
bool	sent_scissor: 1	True if at least one SET_SCISSOR was sent since reset.
bool	sent_zprim: 1	True if SET_PRIM_DEPTH was sent.
bool	mode_changed: 1	True if there is a pending mode change to validate (SET_OTHER_MODES / SET_COMBINE)
bool	rendertarget_changed: 1	True if there is a pending render target change to validate (SET_COLOR_IMAGE / SET_SCISSOR)

.col

struct .col

Data Fields
uint8_t	fmt
uint8_t	size	Format & size (RDP format/size bits)
uint16_t	width
uint16_t	height	Dimensions of the color image.

.tex

struct .tex

Data Fields
uint32_t	physaddr	Physical address of the texture.
uint8_t	fmt
uint8_t	size	Format & size (RDP format/size bits)

.clip

struct .clip

Data Fields
uint16_t	x0
uint16_t	y0
uint16_t	x1
uint16_t	y1	Scissor extents.

Macro Definition Documentation

RDPQ_DEBUG_DEBUG

#define RDPQ_DEBUG_DEBUG   0

Internal debugging of rdpq_debug.

Define to 1 to active internal debugging of the rdpq debug module. This is useful to trace bugs of rdpq itself, but it should not be necessary for standard debugging sessions of application code, so it is turned off by default.

__VALIDATE

#define __VALIDATE	(		flags,
			cond,
			msg,
			...
	)

Value:

    ({ \
    if (!(cond)) validate_emit_error(flags, msg "\n", ##__VA_ARGS__); \
})

Internal validation macros (for both errors and warnings)

VALIDATE_CRASH

#define VALIDATE_CRASH	(		cond,
			msg,
			...
	)		__VALIDATE(0, cond, msg, ##__VA_ARGS__)

Check and trigger a RDP crash.

This is the most fatal error condition, in which the RDP chip freezes and stop processing commands until reboot.

VALIDATE_ERR

#define VALIDATE_ERR	(		cond,
			msg,
			...
	)		__VALIDATE(1, cond, msg, ##__VA_ARGS__)

Check and trigger a RDP validation error.

This should be triggered only whenever the commands rely on an undefined hardware behaviour or in general strongly misbehave with respect to the reasonable expectation of the programmer. Typical expected outcome on real hardware should be garbled graphcis.

VALIDATE_WARN

#define VALIDATE_WARN	(		cond,
			msg,
			...
	)		__VALIDATE(2, cond, msg, ##__VA_ARGS__)

Check and trigger a RDP validation warning.

This should be triggered whenever the commands deviate from standard practice or in general are dubious in their use. It does not necessarily mean that the RDP is going to misbehave but it is likely that the programmer did not fully understand what the RDP is going to do. It is OK to have false positives here – if the situation becomes too unwiedly, we can later add a way to disable classes of warning in specific programs.

Function Documentation

rdpq_debug_disasm_size()

int rdpq_debug_disasm_size

(

uint64_t *

buf

)

Return the size of the next RDP commands.

Parameters

buf	Pointer to RDP command

Returns

Number of 64-bit words the command is composed of

rdpq_debug_disasm()

bool rdpq_debug_disasm	(	uint64_t *	buf,
		FILE *	out
	)

Disassemble a RDP command.

This function allows to access directly the disassembler which is part of the rdpq debugging log. Normally, you don't need to use this function: just call rdpq_debug_log to see all RDP commands in disassembled format.

This function can be useful for writing tools or manually debugging a RDP stream.

Parameters

buf	Pointer to the RDP command
out	Ouput stream where to write the disassembled string

Returns

true if the command was disassembled, false if the command is being held in a buffer waiting for more commands to be appended.

See also

rdpq_debug_disasm_size

rdpq_validate()

void rdpq_validate	(	uint64_t *	buf,
		uint32_t	flags,
		int *	errs,
		int *	warns
	)

Validate the next RDP command, given the RDP current state.

Parameters

	buf	Pointer to the RDP command
	flags	Flags that configure the validation
[out]	errs	If provided, this variable will contain the number of validation errors that were found.
[out]	warns	If provided, this variable will contain the number of validation warnings that were found.