libdragon
Loading...
Searching...
No Matches
Data Structures | Macros | Functions | Variables

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
bufPointer 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
bufPointer to the RDP command
outOuput 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
bufPointer to the RDP command
flagsFlags that configure the validation
[out]errsIf provided, this variable will contain the number of validation errors that were found.
[out]warnsIf provided, this variable will contain the number of validation warnings that were found.