Introspection

Thread introspection for core dumps, fault handling, the task watchdog and telemetry. More...

Data Structures
struct	pbl_thread_info
	Thread as seen by pbl_thread_foreach(). More...
struct	pbl_thread_saved_regs
	Registers of a thread that is not running, read from its saved context. More...
struct	pbl_thread_stack_info
	Stack bounds and usage of a thread. More...
struct	pbl_thread_stats
	Run-time statistics of a thread. More...

Typedefs
typedef void(*	pbl_thread_info_fn) (const struct pbl_thread_info *info, void *ctx)
	Callback of pbl_thread_foreach().

Enumerations
enum	pbl_thread_reg {   PBL_THREAD_REG_R0 , PBL_THREAD_REG_R1 , PBL_THREAD_REG_R2 , PBL_THREAD_REG_R3 ,   PBL_THREAD_REG_R4 , PBL_THREAD_REG_R5 , PBL_THREAD_REG_R6 , PBL_THREAD_REG_R7 ,   PBL_THREAD_REG_R8 , PBL_THREAD_REG_R9 , PBL_THREAD_REG_R10 , PBL_THREAD_REG_R11 ,   PBL_THREAD_REG_R12 , PBL_THREAD_REG_SP , PBL_THREAD_REG_LR , PBL_THREAD_REG_PC ,   PBL_THREAD_REG_XPSR , PBL_THREAD_REG_COUNT }
	Index of a register in pbl_thread_info::regs; the core dump format depends on it. More...

Functions
void	pbl_thread_foreach (pbl_thread_info_fn fn, void *ctx)
	Visit every live thread with its saved registers.
void	pbl_thread_saved_regs (const struct pbl_thread *t, struct pbl_thread_saved_regs *regs)
	Read the saved PC, LR and CONTROL of a thread.
void	pbl_thread_stack_info (const struct pbl_thread *t, struct pbl_thread_stack_info *info)
	Get the stack bounds and high-water mark of a thread.
size_t	pbl_thread_stats_snapshot (struct pbl_thread_stats *out, size_t max, uint32_t *total_run_time)
	Take a snapshot of the statistics of every live thread.
size_t	pbl_thread_count (void)
	Count the live threads, including the idle thread.
void	pbl_kernel_assert_failed (const char *filename, int line)
	Handle a failed kernel assertion.

Detailed Description

Thread introspection for core dumps, fault handling, the task watchdog and telemetry.

static void prv_print(const struct pbl_thread_info *info, void *ctx) {
  if (!info->current) {
    printf("%s pc=%08lx\n", info->name, info->regs[PBL_THREAD_REG_PC]);
  }
}
 
pbl_thread_foreach(prv_print, NULL);

---

Data Structure Documentation

pbl_thread_info

struct pbl_thread_info

Thread as seen by pbl_thread_foreach().

Data Fields
bool	current	The thread was running; its registers are live, not saved, and regs is zero.
uintptr_t	id	Identifier for debuggers; the address of the thread object.
const char *	name	Thread name.
uint32_t	regs[PBL_THREAD_REG_COUNT]	Saved registers, indexed by pbl_thread_reg.
struct pbl_thread *	thread	Thread object.

pbl_thread_saved_regs

struct pbl_thread_saved_regs

Registers of a thread that is not running, read from its saved context.

Data Fields
uint32_t	control	CONTROL register.
uintptr_t	lr	Link register.
uintptr_t	pc	Program counter.

pbl_thread_stack_info

struct pbl_thread_stack_info

Stack bounds and usage of a thread.

Data Fields
size_t	high_water	Bytes at the bottom of the stack never used since the thread was created.
size_t	size	Stack size in bytes.
uintptr_t	start	Lowest address of the stack.

pbl_thread_stats

struct pbl_thread_stats

Run-time statistics of a thread.

Data Fields
const char *	name	Thread name.
uint32_t	number	Sequence number assigned when the thread was started.
uint32_t	run_time	Time spent running, in ticks.
size_t	stack_high_water	Bytes of stack never used, see pbl_thread_stack_info::high_water.
enum pbl_thread_state	state	State at the time of the snapshot.
struct pbl_thread *	thread	Thread object.

Typedef Documentation

pbl_thread_info_fn

typedef void(* pbl_thread_info_fn) (const struct pbl_thread_info *info, void *ctx)

Callback of pbl_thread_foreach().

Parameters

info	Thread being visited, valid only during the call.
ctx	Context given to pbl_thread_foreach().

Enumeration Type Documentation

pbl_thread_reg

enum pbl_thread_reg

Index of a register in pbl_thread_info::regs; the core dump format depends on it.

Enumerator
PBL_THREAD_REG_R0	r0.
PBL_THREAD_REG_R1	r1.
PBL_THREAD_REG_R2	r2.
PBL_THREAD_REG_R3	r3.
PBL_THREAD_REG_R4	r4.
PBL_THREAD_REG_R5	r5.
PBL_THREAD_REG_R6	r6.
PBL_THREAD_REG_R7	r7.
PBL_THREAD_REG_R8	r8.
PBL_THREAD_REG_R9	r9.
PBL_THREAD_REG_R10	r10.
PBL_THREAD_REG_R11	r11.
PBL_THREAD_REG_R12	r12.
PBL_THREAD_REG_SP	Stack pointer, with the exception frame popped.
PBL_THREAD_REG_LR	Link register.
PBL_THREAD_REG_PC	Program counter.
PBL_THREAD_REG_XPSR	Program status register.
PBL_THREAD_REG_COUNT	Number of registers.

Function Documentation

pbl_kernel_assert_failed()

void pbl_kernel_assert_failed	(	const char *	filename,
		int	line
	)

Handle a failed kernel assertion.

Implemented by the platform.

Parameters

filename	Source file name of the assertion.
line	Line of the assertion.

pbl_thread_count()

size_t pbl_thread_count

(

void

)

Count the live threads, including the idle thread.

Returns

Number of threads.

pbl_thread_foreach()

void pbl_thread_foreach	(	pbl_thread_info_fn	fn,
		void *	ctx
	)

Visit every live thread with its saved registers.

Takes no lock; safe to call from a fault handler.

Parameters

fn	Called once per thread.
ctx	Passed to fn.

pbl_thread_saved_regs()

void pbl_thread_saved_regs	(	const struct pbl_thread *	t,
		struct pbl_thread_saved_regs *	regs
	)

Read the saved PC, LR and CONTROL of a thread.

Called from an ISR for the interrupted thread, it reads the live exception frame instead, so the result is where that thread actually is.

Parameters

	t	Thread.
[out]	regs	Registers.

pbl_thread_stack_info()

void pbl_thread_stack_info	(	const struct pbl_thread *	t,
		struct pbl_thread_stack_info *	info
	)

Get the stack bounds and high-water mark of a thread.

Scans the stack fill pattern, so the cost grows with the unused stack.

Parameters

	t	Thread.
[out]	info	Stack information.

pbl_thread_stats_snapshot()

size_t pbl_thread_stats_snapshot	(	struct pbl_thread_stats *	out,
		size_t	max,
		uint32_t *	total_run_time
	)

Take a snapshot of the statistics of every live thread.

Runs with interrupts locked.

Parameters

[out]	out	Array receiving the entries.
	max	Capacity of out; further threads are left out.
[out]	total_run_time	Uptime in ticks, the denominator of the run times; may be NULL.

Returns

Number of entries written.