Facilities to trace progress of kernel execution. More...

Enumerations
enum	TraceEventID { EVENT_NONE = 0 , EVENT_CPU_BOOT , EVENT_THREAD_SWITCH , EVENT_SYSCALL , EVENT_NOTIFY_WAIT_INIT , EVENT_NOTIFY_WAITING , EVENT_NOTIFY_PENDING , EVENT_WAIT_PENDING , EVENT_WAIT_SUSPEND , EVENT_ISR_HANDLER , EVENT_KERNEL_TICK }

Functions
bool	trace_init (void start_addr, void end_addr)
	Initialize trace buffer.

void	trace_event (enum TraceEventID event, uint32_t arg)
	Trace event.

Detailed Description

Facilities to trace progress of kernel execution.

Sometimes the current state of system as inspected by the debugger is not enough to fully understand what happens and why it happens. For these rough days the kernel tracing infrastructure offers facility to track certain events as they happened.

If tracing infrastructure is enabled by CMake option then tracing infrastructure support is built into kernel. This infrastructure is called from certain places. As of now tracing is all or nothing. Once tracing is enabled all trace events currently present in the code are recorded if they happen.

Trace buffer is a circular buffer that overwrites oldest recorded entries if new events are traced and the buffer is not large enough to store them.

Enabling tracing

In order for tracing to be active the developer needs to turn on CMake option named CMRX_KERNEL_TRACING. Then it is necessary to call function trace_init() which will tell the tracing infrastructure where the tracing buffer can be stored.

Tracing buffer is not allocated normally, rather it is developer's task to find a suitable space outside of normally used memory where it can be placed.

This buffer will be "formatted" during the initialization and subsequent calls to trace_event() will record events there.

If buffer is not initialized then calls to trace_event() do nothing.

Retrieving trace data

Trace data is stored in RAM. In order to process them one has to dump them to the computer. This can be done in many ways. One possible way is to use the provided GDB script. This script is available in CMRX kernel repository in gdb/trace_log.gdb file. It provides dump_trace command. This command will dump trace in human readable form into file trace.log into current working directory.

Enumeration Type Documentation

◆ TraceEventID

enum TraceEventID

Enumerator
EVENT_NONE
EVENT_CPU_BOOT
EVENT_THREAD_SWITCH
EVENT_SYSCALL
EVENT_NOTIFY_WAIT_INIT
EVENT_NOTIFY_WAITING
EVENT_NOTIFY_PENDING
EVENT_WAIT_PENDING
EVENT_WAIT_SUSPEND
EVENT_ISR_HANDLER
EVENT_KERNEL_TICK

Function Documentation

◆ trace_event()

void trace_event	(	enum TraceEventID	event,
		uint32_t	arg
	)

Trace event.

This will trace event into trace buffer.

Parameters

event	The event that happened
arg	optional argument to the event, event-specific

Note: If trace buffer was not initialized then this call does nothing. Please mind that even then the call happens and consumes CPU cycles.

◆ trace_init()

bool trace_init	(	void *	start_addr,
		void *	end_addr
	)

Initialize trace buffer.

Trace buffer is usually put outside of the allocated RAM so it can occupy otherwise unused and unallocated RAM space.