Debug Utility Library

Data Structures
struct	_PspDebugRegBlock
	Structure to hold the register data associated with an exception. More...
struct	_PspDebugStackTrace
	Structure to hold a single stack trace entry. More...
struct	_PspDebugProfilerRegs
	Structure to hold the psp profiler register values. More...

Typedefs
typedef struct _PspDebugRegBlock	PspDebugRegBlock
	Structure to hold the register data associated with an exception.
typedef void(*	PspDebugErrorHandler )(PspDebugRegBlock *regs)
	Defines a debug error handler.
typedef int(*	PspDebugKprintfHandler )(const char *format, u32 *args)
	Type for Kprintf handler.
typedef struct _PspDebugStackTrace	PspDebugStackTrace
	Structure to hold a single stack trace entry.
typedef struct _PspDebugProfilerRegs	PspDebugProfilerRegs
	Structure to hold the psp profiler register values.
typedef int(*	PspDebugPrintHandler )(const char *data, int len)
	Type for the debug print handlers.
typedef int(*	PspDebugInputHandler )(char *data, int len)
	Type for the debug input handler.

Functions
void	pspDebugScreenInit (void)
	Initialise the debug screen.
void	pspDebugScreenInitEx (void *vram_base, int mode, int setup)
	Extended debug screen init.
void	pspDebugScreenPrintf (const char *fmt,...) __attribute__((format(printf
	Do a printf to the debug screen.
void void	pspDebugScreenKprintf (const char *format,...) __attribute__((format(printf
	Do a printf to the debug screen.
void void void	pspDebugScreenEnableBackColor (int enable)
	Enable or disable background colour writing (defaults to enabled)
void	pspDebugScreenSetBackColor (u32 color)
	Set the background color for the text.
void	pspDebugScreenSetTextColor (u32 color)
	Set the text color.
void	pspDebugScreenSetColorMode (int mode)
	Set the color mode (you must have switched the frame buffer appropriately)
void	pspDebugScreenPutChar (int x, int y, u32 color, u8 ch)
	Draw a single character to the screen.
void	pspDebugScreenSetXY (int x, int y)
	Set the current X and Y co-ordinate for the screen (in character units)
void	pspDebugScreenSetOffset (int offset)
	Set the video ram offset used for the screen.
void	pspDebugScreenSetBase (u32 *base)
	Set the video ram base used for the screen.
void	pspDebugScreenSetMaxX (unsigned int maxx)
	Set the X maximum coordinate (in character units)
void	pspDebugScreenSetMaxY (unsigned int maxy)
	Set the Y maximum coordinate (in character units)
int	pspDebugScreenGetX (void)
	Get the current X co-ordinate (in character units)
int	pspDebugScreenGetY (void)
	Get the current Y co-ordinate (in character units)
void	pspDebugScreenClear (void)
	Clear the debug screen.
int	pspDebugScreenPrintData (const char *buff, int size)
	Print non-nul terminated strings.
int	pspDebugScreenPuts (const char *str)
	Print a string.
int	pspDebugGetStackTrace (unsigned int *results, int max)
	Get a MIPS stack trace (might work :P)
void	pspDebugScreenClearLineEnable (void)
	Enable the clear line function that allows debug to clear the screen.
void	pspDebugScreenClearLineDisable (void)
	Disable the clear line function that causes flicker on constant refreshes.
int	pspDebugInstallErrorHandler (PspDebugErrorHandler handler)
	Install an error handler to catch unhandled exceptions.
void	pspDebugDumpException (PspDebugRegBlock *regs)
	Dump an exception to screen using the pspDebugScreen functions.
int	pspDebugInstallKprintfHandler (PspDebugKprintfHandler handler)
	Install a Kprintf handler into the system.
int	pspDebugGetStackTrace2 (PspDebugRegBlock *regs, PspDebugStackTrace *trace, int max)
	Do a stack trace from the current exception.
void	pspDebugProfilerEnable (void)
	Enables the profiler hardware.
void	pspDebugProfilerDisable (void)
	Disables the profiler hardware.
void	pspDebugProfilerClear (void)
	Clear the profiler registers.
void	pspDebugProfilerGetRegs (PspDebugProfilerRegs *regs)
	Get the profiler register state.
void	pspDebugProfilerPrint (void)
	Print the profiler registers to screen.
int	pspDebugInstallStdinHandler (PspDebugInputHandler handler)
	Install a handler for stdin (so you can use normal stdio functions)
int	pspDebugInstallStdoutHandler (PspDebugPrintHandler handler)
	Install a print handler for stdout (so you can use normal print functions)
int	pspDebugInstallStderrHandler (PspDebugPrintHandler handler)
	Install a print handler for stderr (so you can use normal print functions)
void	pspDebugSioPutchar (int ch)
	Put a character to the remote sio.
int	pspDebugSioGetchar (void)
	Get a character from the remote sio.
void	pspDebugSioPuts (const char *str)
	Write a string to the sio port.
int	pspDebugSioPutData (const char *data, int len)
	Write a set of data to the sio port.
int	pspDebugSioPutText (const char *data, int len)
	Write a set of data to the sio port converting single line feeds to CRLF and single CR to CRLF.
void	pspDebugSioInit (void)
	Initialise the remote SIO port (defaults to 4800 8N1).
void	pspDebugSioSetBaud (int baud)
	Set the baud rate of the SIO, e.g.
void	pspDebugEnablePutchar (void)
	Enable debug character output.
void	pspDebugSioInstallKprintf (void)
	Install a kprintf debug putchar handler.
void	pspDebugGdbStubInit (void)
	Install the gdb stub handler.
void	pspDebugBreakpoint (void)
	Generate a breakpoint exception.
void	pspDebugSioEnableKprintf (void)
	Enable the kprintf handler (once installed)
void	pspDebugSioDisableKprintf (void)
	Disable the kprintf handler (once installed)

Detailed Description

Typedef Documentation

typedef void(* PspDebugErrorHandler)(PspDebugRegBlock *regs)

Defines a debug error handler.

typedef int(* PspDebugInputHandler)(char *data, int len)

Type for the debug input handler.

typedef int(* PspDebugKprintfHandler)(const char *format, u32 *args)

Type for Kprintf handler.

typedef int(* PspDebugPrintHandler)(const char *data, int len)

Type for the debug print handlers.

typedef struct _PspDebugProfilerRegs PspDebugProfilerRegs

Structure to hold the psp profiler register values.

typedef struct _PspDebugRegBlock PspDebugRegBlock

Structure to hold the register data associated with an exception.

typedef struct _PspDebugStackTrace PspDebugStackTrace

Structure to hold a single stack trace entry.

Function Documentation

void pspDebugBreakpoint

(

void

)

Generate a breakpoint exception.

void pspDebugDumpException

(

PspDebugRegBlock *

regs

)

Dump an exception to screen using the pspDebugScreen functions.

Note

This function will not setup the screen for debug output, you should call sceDebugScreenInit before using it if it isn't already.

Parameters

regs	- Pointer to a register block.

References _PspDebugRegBlock::badvaddr, _PspDebugRegBlock::cause, _PspDebugRegBlock::epc, i, pspDebugScreenPrintf(), _PspDebugRegBlock::r, sceDisplayWaitVblankStart(), and _PspDebugRegBlock::status.

void pspDebugEnablePutchar

(

void

)

Enable debug character output.

Needs to be called in order for the default Kprintf handler to work.

Referenced by pspDebugSioInstallKprintf().

void pspDebugGdbStubInit

(

void

)

Install the gdb stub handler.

References _gdbSupportLibInit(), memset(), pspDebugInstallErrorHandler(), pspDebugInstallStderrHandler(), and pspDebugInstallStdoutHandler().

int pspDebugGetStackTrace	(	unsigned int *	results,
		int	max
	)

Get a MIPS stack trace (might work :P)

Parameters

results	- List of points to store the results of the trace, (up to max)
max	- Maximum number of back traces

Returns

The number of frames stored in results.

References ADJUST_STACKP_C, ADJUST_STACKP_C_MASK, ADJUST_STACKP_V, ADJUST_STACKP_V_MASK, CALL, FALSE, HASH, main(), OR_LOWER_C, OR_LOWER_C_MASK, pspGetReturnAddress(), pspGetStackPointer(), ra, _returnCache::raOffset, RESTORE_RETURNVAL, RESTORE_RETURNVAL2, RESTORE_RETURNVAL3, RESTORE_RETURNVAL_MASK, RETURN, _returnCache::returnAddress, SET_LOWER_C, SET_LOWER_C_MASK, SET_UPPER_C, SET_UPPER_C_MASK, sp, _returnCache::spAdjust, and TRUE.

int pspDebugGetStackTrace2	(	PspDebugRegBlock *	regs,
		PspDebugStackTrace *	trace,
		int	max
	)

Do a stack trace from the current exception.

Note

This function really isn't too general purpose and it is more than likely to generate a few false positives but I consider that better then missing out calls entirely. You have to use your discretion, your code and a objdump to work out if some calls are completely surprious or not ;)

Parameters

regs	- Pointer to a register block from an exception.
trace	- Pointer to an array of PspDebugStackTrace structures.
max	- The maximum number of traces to make.

Returns

The number of functions found.

References count, memset(), NULL, _PspDebugRegBlock::r, sceKernelGetThreadId(), sceKernelReferThreadStatus(), SceKernelThreadInfo::size, SceKernelThreadInfo::stack, and SceKernelThreadInfo::stackSize.

int pspDebugInstallErrorHandler

(

PspDebugErrorHandler

handler

)

Install an error handler to catch unhandled exceptions.

Parameters

handler

- Pointer to a handler function. If set to NULL it will default to resetting the screen and dumping the error.

Returns

< 0 on error

References _pspDebugExceptionHandler(), and sceKernelRegisterDefaultExceptionHandler().

Referenced by pspDebugGdbStubInit().

int pspDebugInstallKprintfHandler

(

PspDebugKprintfHandler

handler

)

Install a Kprintf handler into the system.

Parameters

handler

- Function pointer to the handler.

Returns

< 0 on error.

References NULL, and sceKernelRegisterKprintfHandler().

int pspDebugInstallStderrHandler

(

PspDebugPrintHandler

handler

)

Install a print handler for stderr (so you can use normal print functions)

Parameters

handler

- A pointer to print handler, NULL to disable.

Returns

< 0 on error, else 0.

References g_initialised.

Referenced by pspDebugGdbStubInit().

int pspDebugInstallStdinHandler

(

PspDebugInputHandler

handler

)

Install a handler for stdin (so you can use normal stdio functions)

Parameters

handler

- A pointer to input handler, NULL to disable.

Returns

< 0 on error, else 0.

References g_initialised.

int pspDebugInstallStdoutHandler

(

PspDebugPrintHandler

handler

)

Install a print handler for stdout (so you can use normal print functions)

Parameters

handler

- A pointer to print handler, NULL to disable.

Returns

< 0 on error, else 0.

References g_initialised.

Referenced by pspDebugGdbStubInit().

void pspDebugProfilerClear

(

void

)

Clear the profiler registers.

References i, PROFILER_REG_BASE, and PROFILER_REG_COUNT.

void pspDebugProfilerDisable

(

void

)

Disables the profiler hardware.

References PROFILER_REG_BASE.

void pspDebugProfilerEnable

(

void

)

Enables the profiler hardware.

References PROFILER_REG_BASE.

void pspDebugProfilerGetRegs

(

PspDebugProfilerRegs *

regs

)

Get the profiler register state.

Parameters

regs	- A pointer to a PspDebugProfilerRegs structure.

References i, NULL, PROFILER_REG_BASE, and PROFILER_REG_COUNT.

Referenced by pspDebugProfilerPrint().

void pspDebugProfilerPrint

(

void

)

Print the profiler registers to screen.

References _PspDebugProfilerRegs::bus_access, _PspDebugProfilerRegs::cached_load, _PspDebugProfilerRegs::cached_store, _PspDebugProfilerRegs::cop0_inst, _PspDebugProfilerRegs::copz, _PspDebugProfilerRegs::cpuck, _PspDebugProfilerRegs::d_miss, _PspDebugProfilerRegs::d_writeback, _PspDebugProfilerRegs::enable, _PspDebugProfilerRegs::fpu_inst, _PspDebugProfilerRegs::i_miss, _PspDebugProfilerRegs::internal, _PspDebugProfilerRegs::local_bus, _PspDebugProfilerRegs::memory, pspDebugProfilerGetRegs(), pspDebugScreenPrintf(), _PspDebugProfilerRegs::sleep, _PspDebugProfilerRegs::systemck, _PspDebugProfilerRegs::uncached_load, _PspDebugProfilerRegs::uncached_store, _PspDebugProfilerRegs::vfpu, and _PspDebugProfilerRegs::vfpu_inst.

void pspDebugScreenClear

(

void

)

Clear the debug screen.

void pspDebugScreenClearLineDisable

(

void

)

Disable the clear line function that causes flicker on constant refreshes.

void pspDebugScreenClearLineEnable

(

void

)

Enable the clear line function that allows debug to clear the screen.

void void void pspDebugScreenEnableBackColor

(

int

enable

)

Enable or disable background colour writing (defaults to enabled)

Parameters

enable

- Set 1 to to enable background color, 0 for disable

int pspDebugScreenGetX

(

void

)

Get the current X co-ordinate (in character units)

Returns

The X co-ordinate

int pspDebugScreenGetY

(

void

)

Get the current Y co-ordinate (in character units)

Returns

The Y co-ordinate

void pspDebugScreenInit

(

void

)

Initialise the debug screen.

void pspDebugScreenInitEx	(	void *	vram_base,
		int	mode,
		int	setup
	)

Extended debug screen init.

Parameters

vram_base	- Base address of frame buffer, if NULL then sets a default
mode	- Colour mode
setup	- Setup the screen if 1

void void pspDebugScreenKprintf	(	const char *	format,
			...
	)

Do a printf to the debug screen.

Note

This is for kernel mode only as it uses a kernel function to perform the printf instead of using vsnprintf, use normal printf for user mode.

Parameters

format	- Format string to print
...	- Arguments

int pspDebugScreenPrintData	(	const char *	buff,
		int	size
	)

Print non-nul terminated strings.

Parameters

buff	- Buffer containing the text.
size	- Size of the data

Returns

The number of characters written

void pspDebugScreenPrintf	(	const char *	fmt,
			...
	)

Do a printf to the debug screen.

Parameters

fmt	- Format string to print
...	- Arguments

Referenced by pspDebugDumpException(), pspDebugKbClearBox(), pspDebugKbDrawBox(), pspDebugKbDrawKey(), pspDebugKbDrawString(), and pspDebugProfilerPrint().

void pspDebugScreenPutChar	(	int	x,
		int	y,
		u32	color,
		u8	ch
	)

Draw a single character to the screen.

Parameters

x	- The x co-ordinate to draw to (pixel units)
y	- The y co-ordinate to draw to (pixel units)
color	- The text color to draw
ch	- The character to draw

int pspDebugScreenPuts

(

const char *

str

)

Print a string.

Parameters

str

- String

Returns

The number of characters written

void pspDebugScreenSetBackColor

(

u32

color

)

Set the background color for the text.

Note

To reset the entire screens bg colour you need to call pspDebugScreenClear

Parameters

color

- A 32bit RGB colour

Referenced by pspDebugKbClearBox(), pspDebugKbDrawBox(), pspDebugKbDrawKey(), and pspDebugKbDrawString().

void pspDebugScreenSetBase

(

u32 *

base

)

Set the video ram base used for the screen.

Parameters

base	- Base address in bytes

void pspDebugScreenSetColorMode

(

int

mode

)

Set the color mode (you must have switched the frame buffer appropriately)

Parameters

mode	- Color mode

void pspDebugScreenSetMaxX

(

unsigned int

maxx

)

Set the X maximum coordinate (in character units)

Note

Thus line length will be X + 1 characters.

Parameters

maxx	- The X maximum coordinate

void pspDebugScreenSetMaxY

(

unsigned int

maxy

)

Set the Y maximum coordinate (in character units)

Parameters

maxx	- The X maximum coordinate

void pspDebugScreenSetOffset

(

int

offset

)

Set the video ram offset used for the screen.

Parameters

offset

- Offset in bytes

void pspDebugScreenSetTextColor

(

u32

color

)

Set the text color.

Parameters

color

- A 32 bit RGB color

Referenced by pspDebugKbClearBox(), pspDebugKbDrawBox(), pspDebugKbDrawKey(), and pspDebugKbDrawString().

void pspDebugScreenSetXY	(	int	x,
		int	y
	)

Set the current X and Y co-ordinate for the screen (in character units)

Referenced by pspDebugKbClearBox(), pspDebugKbDrawBox(), pspDebugKbDrawKey(), and pspDebugKbDrawString().

void pspDebugSioDisableKprintf

(

void

)

Disable the kprintf handler (once installed)

void pspDebugSioEnableKprintf

(

void

)

Enable the kprintf handler (once installed)

int pspDebugSioGetchar

(

void

)

Get a character from the remote sio.

Returns

The character read or -1 if no characters available.

References PSP_UART4_FIFO, PSP_UART4_STAT, and PSP_UART_RXEMPTY.

Referenced by getDebugChar().

void pspDebugSioInit

(

void

)

Initialise the remote SIO port (defaults to 4800 8N1).

Note

will delay 2 seconds to wait for the power to come up.

References sceHprmEnd(), sceKernelDelayThread(), sceSysconCtrlHRPower(), and sceSysregUartIoEnable().

void pspDebugSioInstallKprintf

(

void

)

Install a kprintf debug putchar handler.

Implicitly calls pspDebugEnablePutchar so you do not need to call it explicitly. Sio must be initialised before calling this function however.

References pspDebugEnablePutchar(), and sceKernelRegisterDebugPutchar().

void pspDebugSioPutchar

(

int

ch

)

Put a character to the remote sio.

Parameters

ch	- Character to write.

References PSP_UART4_FIFO, PSP_UART4_STAT, and PSP_UART_TXFULL.

Referenced by pspDebugSioPutData(), pspDebugSioPuts(), pspDebugSioPutText(), and putDebugChar().

int pspDebugSioPutData	(	const char *	data,
		int	len
	)

Write a set of data to the sio port.

Parameters

data	- Pointer to the data to send.
len	- Length of the data.

Returns

Number of characters written.

References i, and pspDebugSioPutchar().

void pspDebugSioPuts

(

const char *

str

)

Write a string to the sio port.

Parameters

str	- String to write.

References pspDebugSioPutchar().

int pspDebugSioPutText	(	const char *	data,
		int	len
	)

Write a set of data to the sio port converting single line feeds to CRLF and single CR to CRLF.

Parameters

data	- Pointer to the data to send.
len	- Length of the data.

Returns

Number of characters written.

References i, and pspDebugSioPutchar().

void pspDebugSioSetBaud

(

int

baud

)

Set the baud rate of the SIO, e.g.

4800/9600..115200.

Parameters

baud	- The baudrate to set.

References PSP_UART4_CTRL, PSP_UART4_DIV1, PSP_UART4_DIV2, and PSP_UART_CLK.