trace.h File Reference

User and kernel code definitions for system-wide tracing. More...

Data Structures
struct	trace_event
	Trace event. More...
struct	trace_buffer
	Trace buffer. More...

Macros
#define	TRACE_EVENT(s, e, a)   ((uint64_t)(s)<<48|(uint64_t)(e)<<32|(a))

Functions
errval_t	trace_init (void)
	Initialize per-core tracing buffer. More...
errval_t	trace_disable_domain (void)
	Turn off tracing for this domain.
void	trace_reset_buffer (void)
	Reset the trace buffer on the current core. More...
void	trace_reset_all (void)
	Reset all trace buffers discarding the current trace. More...
errval_t	trace_setup_on_core (struct capref *retcap)
	Set up the trace buffer on the current core and notify the kernel. More...
errval_t	trace_setup_child (struct cnoderef taskcn, dispatcher_handle_t handle)
	Setup the tracing buffer for a child domain. More...
errval_t	trace_control (uint64_t start_trigger, uint64_t stop_trigger, uint64_t duration)
	Specify the trigger events which start and stop tracing. More...
errval_t	trace_wait (void)
	Wait for a trace to complete.
size_t	trace_dump (char *buf, size_t buflen, int *number_of_events)
	Dump the contents of the trace buffers. More...
void	trace_flush (struct event_closure callback)
	Flush the trace buffer to the "best" destination. More...
void	trace_set_autoflush (bool enabled)
	Enable/Disable the autoflush mechanism of the tracing framework. More...
errval_t	trace_prepare (struct event_closure callback)
	Optional call to do "extra" preparation of the tracing framework. More...
errval_t	trace_set_subsys_enabled (uint16_t subsys, bool enabled)
	Enable/Disable the logging of a given subsytem. More...
errval_t	trace_set_all_subsys_enabled (bool enabled)
	Enable/Disable all subsystems.
void	trace_init_disp (void)

Detailed Description

User and kernel code definitions for system-wide tracing.

Macro Definition Documentation

#define TRACE_EVENT	(		s,
			e,
			a
	)		((uint64_t)(s)<<48|(uint64_t)(e)<<32|(a))

The constants for the subsystems and events are generated from the file trace_definitions/trace_defs.pleco that can be included after compiling with #include <trace_definitions/trace_defs.h>

Function Documentation

errval_t trace_control	(	uint64_t	start_trigger,
		uint64_t	stop_trigger,
		uint64_t	duration
	)

Specify the trigger events which start and stop tracing.

Parameters

start_trigger	- Raw event value which starts the trace
stop_trigger	- Raw event value which stops the trace
duration	- Maximum trace duration in cycles (0 is infinite)

size_t trace_dump	(	char *	buf,
		size_t	buflen,
		int *	number_of_events_dumped
	)

Dump the contents of the trace buffers.

buf : The buffer to write the trace log into. buflen : Length of buf. number_of_events_dumped : (optional) Returns how many events have been written into the buffer.

void trace_flush

(

struct event_closure

callback

)

Flush the trace buffer to the "best" destination.

This function automatically determines if bfscope is running and if someone is connected over the network. If so, the buffer is flushed over the network. If nobody is connected or bfscope is not running, the buffer is flushed onto the console.

errval_t trace_init

(

void

)

Initialize per-core tracing buffer.

This function creates a cap for the tracing buffer in taskcn. It is called from init at startup.

Note that it does not map the buffer into its own vspace.

void trace_init_disp

(

void

)

Sets up tracing framework for current dispatcher

errval_t trace_prepare

(

struct event_closure

callback

)

Optional call to do "extra" preparation of the tracing framework.

Call this method to prepare for tracing. This is not a preparation in a strict sense, i.e. tracing will also work when you do not call this method, but it provides some benefits.

Currently it provides a mechanism for clock synchronization between cores.

void trace_reset_all

(

void

)

Reset all trace buffers discarding the current trace.

Reset head and tail pointers.

void trace_reset_buffer

(

void

)

Reset the trace buffer on the current core.

Reset head and tail pointers.

void trace_set_autoflush

(

bool

enabled

)

Enable/Disable the autoflush mechanism of the tracing framework.

If autoflush is enabled, the tracing framework will automatically flush the content of the buffer periodically.

NOTE: This only works when bfscope is running!

NOTE: If you enable autoflush, it will affect your performance during the time period you are flushing, as the buffer might be flushed at any given time.

errval_t trace_set_subsys_enabled	(	uint16_t	subsys,
		bool	enabled
	)

Enable/Disable the logging of a given subsytem.

subsys: A subsystem, i.e. the macro generated by the DSL. enabled: True iff the events should be logged.

errval_t trace_setup_child	(	struct cnoderef	taskcn,
		dispatcher_handle_t	handle
	)

Setup the tracing buffer for a child domain.

Assumes that the child domain is currently being spawned (because we rely on libspawndomain having the right state to allow us to map the trace buffer into the child's vspace).

trace_init must already have been called

errval_t trace_setup_on_core

(

struct capref *

retcap

)

Set up the trace buffer on the current core and notify the kernel.

Clear the buffer. Return the cap for the buffer. Should be called once on each core.