User Break Controller

Driver for the SH4's UBC More...

Files
file	ubc.h
	User Break Controller Driver.

Data Structures
struct	ubc_breakpoint_t
	UBC breakpoint structure. More...

Typedefs
typedef bool(*	ubc_break_func_t) (const ubc_breakpoint_t *bp, const irq_context_t *ctx, void *user_data)
	Breakpoint user callback.

Enumerations
enum	ubc_address_mask_t {   ubc_address_mask_none , ubc_address_mask_10 , ubc_address_mask_12 , ubc_address_mask_16 ,   ubc_address_mask_20 , ubc_address_mask_all }
	UBC address mask specifier. More...
enum	ubc_access_t { ubc_access_either , ubc_access_instruction , ubc_access_operand }
	UBC access condition type specifier. More...
enum	ubc_rw_t { ubc_rw_either , ubc_rw_read , ubc_rw_write }
	UBC read/write condition type specifier. More...
enum	ubc_size_t {   ubc_size_any , ubc_size_8bit , ubc_size_16bit , ubc_size_32bit ,   ubc_size_64bit }
	UBC size condition type specifier. More...

Functions
bool	ubc_add_breakpoint (const ubc_breakpoint_t *bp, ubc_break_func_t callback, void *user_data)
	Enables a breakpoint.
bool	ubc_remove_breakpoint (const ubc_breakpoint_t *bp)
	Disables a breakpoint.
void	ubc_clear_breakpoints (void)
	Disables all active breakpoints.

Detailed Description

Driver for the SH4's UBC

The SH4's User Break Controller (UBC) is a CPU peripheral which facilitates low-level software debugging. It provides two different channels which can be configured to monitor for certain memory or instruction conditions before generating a user-break interrupt. It provides the foundation for creating software-based debuggers and is the backing driver for the GDB debug stub.

The following break comparison conditions are supported:

• Address with optional ASID and 10, 12, 16, and 20-bit mask: supporting breaking on ranges of addresses and MMU operation.
• Bus Cycle: supporting instruction or operand (data) breakpoints
• Read/Write: supporting R, W, or RW access conditions.
• Operand size: byte, word, longword, quadword
• Data: 32-bit value with 32-bit mask for breaking on specific values or ranges of values (ubc_channel_b only).
• Pre or Post-Instruction breaking

Warning

This Driver is used internally by the GDB stub, so care must be taken to not utilize the UBC during a GDB debugging session!

Typedef Documentation

ubc_break_func_t

typedef bool(* ubc_break_func_t) (const ubc_breakpoint_t *bp, const irq_context_t *ctx, void *user_data)

Breakpoint user callback.

Typedef for the user function to be invoked upon encountering a breakpoint.

Warning

This callback is invoked within the context of an interrupt handler!

Parameters

bp	Breakpoint that was encountered
ctx	Context of the current interrupt
user_data	User-supplied arbitrary callback data

Return values

true	Remove the breakpoint upon callback completion
false	Leave the breakpoint active upon callback completion

See also

ubc_add_breakpoint()

Enumeration Type Documentation

ubc_access_t

enum ubc_access_t

UBC access condition type specifier.

This value specifies whether to break when the address given by ubc_breakpoint_t::address is used as as an instruction, an operand, or either.

Note

Instruction access is an access that obtains an instruction while operand access is any memory access for the purpose of instruction execution. The default value is either access type.

Enumerator
ubc_access_either	Instruction or operand.
ubc_access_instruction	Instruction.
ubc_access_operand	Operand.

ubc_address_mask_t

enum ubc_address_mask_t

UBC address mask specifier.

This value specifies which of the low bits are masked off and not included from ubc_breakpoint_t::address when configuring a breakpoint. By default, address masking is disabled, and the exact address given by ubc_breakpoint_t::address will be matched.

Remarks

Using a mask allows you to break on a range of instructions or addresses.

Enumerator
ubc_address_mask_none	Disable masking, all bits used.
ubc_address_mask_10	Mask off low 10 bits.
ubc_address_mask_12	Mask off low 12 bits.
ubc_address_mask_16	Mask off low 16 bits.
ubc_address_mask_20	Mask off low 20 bits.
ubc_address_mask_all	Mask off all bits.

ubc_rw_t

enum ubc_rw_t

UBC read/write condition type specifier.

This value is used with operand-access breakpoints to further specify whether to break on read, write, or either access. The default value is either read or write.

Enumerator
ubc_rw_either	Read or write.
ubc_rw_read	Read-only.
ubc_rw_write	Write-only.

ubc_size_t

enum ubc_size_t

UBC size condition type specifier.

This value is used with operand-access breakpoints to further specify the size of the operand access to trigger the break condition. It defaults to breaking on any size.

Enumerator
ubc_size_any	Any sizes.
ubc_size_8bit	Byte sizes.
ubc_size_16bit	Word sizes.
ubc_size_32bit	Longword sizes.
ubc_size_64bit	Quadword sizes.

Function Documentation

ubc_add_breakpoint()

bool ubc_add_breakpoint	(	const ubc_breakpoint_t *	bp,
		ubc_break_func_t	callback,
		void *	user_data )

Enables a breakpoint.

Reserves a channel within the UBC for the given breakpoint.

Parameters

bp	Configuration details for the breakpoint
callback	Handler which gets called upon breakpoint condition
user_data	Optional data to pass back to callback handler

Return values

true	The breakpoint was set successfully
false	The breakpoint failed to be set due to: Invalid configuration No available channel

See also

ubc_remove_breakpoint()

ubc_clear_breakpoints()

void ubc_clear_breakpoints

(

void

)

Disables all active breakpoints.

Removes any breakpoints from the UBC, freeing up all channels.

Note

This is automatically called for you upon program termination.

See also

ubc_remove_breakpoint()

ubc_remove_breakpoint()

bool ubc_remove_breakpoint

(

const ubc_breakpoint_t *

bp

)

Disables a breakpoint.

Removes a breakpoint from the UBC, freeing up a channel.

Parameters

bp	The breakpoint to remove

Return values

true	The breakpoint was successfully removed
false	The breakpoint was not found

See also

ubc_add_breakpoint(), ubc_clear_breakpoints()