Capture Engine Component of the RTEMS Measurement and Monitoring System. More...

Data Structures
struct	rtems_capture_from_s
	Task id and mask for the from trigger. More...

struct	rtems_capture_control_s
	Capture control structure for a group of tasks. More...

struct	rtems_capture_record_s

struct	rtems_capture_task_record_s

Macros
#define	RTEMS_CAPTURE_TRIGGER_TASKS (32)
	The number of tasks in a trigger group.

#define	RTEMS_CAPTURE_CONTROL_FROM_MASK(_s) (UINT32_C(1) << (RTEMS_CAPTURE_TRIGGER_TASKS - ((_s) + 1)))
	The from_valid mask.

#define	RTEMS_CAPTURE_WATCH (1U << 0)
	Control flags.

#define	RTEMS_CAPTURE_SWITCH (1 << 0)
	Control triggers.

#define	RTEMS_CAPTURE_CREATE (1 << 1)

#define	RTEMS_CAPTURE_START (1 << 2)

#define	RTEMS_CAPTURE_RESTART (1 << 3)

#define	RTEMS_CAPTURE_DELETE (1 << 4)

#define	RTEMS_CAPTURE_BEGIN (1 << 5)

#define	RTEMS_CAPTURE_EXITTED (1 << 6)

#define	RTEMS_CAPTURE_TERMINATED (1 << 7)

#define	RTEMS_CAPTURE_FROM_TRIGS

#define	RTEMS_CAPTURE_TO_TRIGS

#define	RTEMS_CAPTURE_TRACED (1U << 0)
	Task flags.

#define	RTEMS_CAPTURE_INIT_TASK (1U << 1)

#define	RTEMS_CAPTURE_RECORD_TASK (1U << 2)

#define	RTEMS_CAPTURE_REAL_PRI_EVENT_MASK UINT32_C (0x000000ff)
	The capture record event flags.

#define	RTEMS_CAPTURE_CURR_PRI_EVENT_MASK UINT32_C (0x0000ff00)

#define	RTEMS_CAPTURE_REAL_PRIORITY_EVENT (0)

#define	RTEMS_CAPTURE_CURR_PRIORITY_EVENT (8)

#define	RTEMS_CAPTURE_EVENT_START (16)

#define	RTEMS_CAPTURE_CREATED_BY_EVENT UINT32_C (0x00010000)

#define	RTEMS_CAPTURE_CREATED_EVENT UINT32_C (0x00020000)

#define	RTEMS_CAPTURE_STARTED_BY_EVENT UINT32_C (0x00040000)

#define	RTEMS_CAPTURE_STARTED_EVENT UINT32_C (0x00080000)

#define	RTEMS_CAPTURE_RESTARTED_BY_EVENT UINT32_C (0x00100000)

#define	RTEMS_CAPTURE_RESTARTED_EVENT UINT32_C (0x00200000)

#define	RTEMS_CAPTURE_DELETED_BY_EVENT UINT32_C (0x00400000)

#define	RTEMS_CAPTURE_DELETED_EVENT UINT32_C (0x00800000)

#define	RTEMS_CAPTURE_TERMINATED_EVENT UINT32_C (0x01000000)

#define	RTEMS_CAPTURE_BEGIN_EVENT UINT32_C (0x02000000)

#define	RTEMS_CAPTURE_EXITTED_EVENT UINT32_C (0x04000000)

#define	RTEMS_CAPTURE_SWITCHED_OUT_EVENT UINT32_C (0x08000000)

#define	RTEMS_CAPTURE_SWITCHED_IN_EVENT UINT32_C (0x10000000)

#define	RTEMS_CAPTURE_TIMESTAMP UINT32_C (0x20000000)

#define	RTEMS_CAPTURE_EVENT_END (29)

Typedefs
typedef uint64_t	rtems_capture_time_t
	A capture timestamp. More...

typedef struct rtems_capture_from_s	rtems_capture_from_t
	Task id and mask for the from trigger. More...

typedef struct rtems_capture_control_s	rtems_capture_control_t
	Capture control structure for a group of tasks. More...

typedef struct rtems_capture_record_s	rtems_capture_record_t

typedef struct rtems_capture_task_record_s	rtems_capture_task_record_t

typedef enum rtems_capture_trigger_mode_e	rtems_capture_trigger_mode_t
	Capture trigger modes. More...

typedef enum rtems_capture_trigger_e	rtems_capture_trigger_t
	Capture trigger. More...

typedef void(*	rtems_capture_timestamp) (rtems_capture_time_t *time)
	Capture timestamp callout handler. More...

Enumerations
enum	rtems_capture_trigger_mode_e { rtems_capture_to_any, rtems_capture_from_any, rtems_capture_from_to }
	Capture trigger modes. More...

enum	rtems_capture_trigger_e { rtems_capture_switch, rtems_capture_create, rtems_capture_start, rtems_capture_restart, rtems_capture_delete, rtems_capture_begin, rtems_capture_exitted, rtems_capture_terminated }
	Capture trigger. More...

Functions
rtems_status_code	rtems_capture_open (uint32_t size, rtems_capture_timestamp timestamp)
	Capture open. More...

rtems_status_code	rtems_capture_close (void)
	Capture close. More...

rtems_status_code	rtems_capture_control (bool enable)
	Capture control trace enable/disable. More...

rtems_status_code	rtems_capture_monitor (bool enable)
	Capture monitor enable/disable. More...

rtems_status_code	rtems_capture_flush (bool prime)

rtems_status_code	rtems_capture_watch_add (rtems_name name, rtems_id id)
	Capture add watch. More...

rtems_status_code	rtems_capture_watch_del (rtems_name name, rtems_id id)
	Capture delete watch. More...

rtems_status_code	rtems_capture_watch_ctrl (rtems_name name, rtems_id id, bool enable)
	Capture enable/disable watch. More...

rtems_status_code	rtems_capture_watch_global (bool enable)
	Capture enable/disable global watch. More...

bool	rtems_capture_watch_global_on (void)
	Get global watch state. More...

rtems_status_code	rtems_capture_watch_ceiling (rtems_task_priority ceiling)
	Set watch ceiling. More...

rtems_task_priority	rtems_capture_watch_get_ceiling (void)
	Get watch ceiling. More...

rtems_status_code	rtems_capture_watch_floor (rtems_task_priority floor)
	Capture set watch floor. More...

rtems_task_priority	rtems_capture_watch_get_floor (void)
	Capture set watch floor. More...

rtems_status_code	rtems_capture_set_trigger (rtems_name from_name, rtems_id from_id, rtems_name to_name, rtems_id to_id, rtems_capture_trigger_mode_t mode, rtems_capture_trigger_t trigger)
	Capture set trigger. More...

rtems_status_code	rtems_capture_clear_trigger (rtems_name from_name, rtems_id from_id, rtems_name to_name, rtems_id to_id, rtems_capture_trigger_mode_t mode, rtems_capture_trigger_t trigger)
	Capture clear trigger. More...

rtems_status_code	rtems_capture_read (uint32_t cpu, uint32_t read, rtems_capture_record_t *recs)
	Capture read records from capture buffer. More...

rtems_status_code	rtems_capture_release (uint32_t cpu, uint32_t count)
	Capture release records. More...

void	rtems_capture_time (rtems_capture_time_t *uptime)

const char *	rtems_capture_event_text (int event)
	Capture get event text. More...

void	rtems_capture_initialize_task (rtems_tcb *tcb)
	Capture initialize task. More...

void	rtems_capture_record_task (rtems_tcb *tcb)
	Capture record task. More...

rtems_capture_control_t *	rtems_capture_get_control_list (void)
	Capture get control list. More...

Detailed Description

Capture Engine Component of the RTEMS Measurement and Monitoring System.

Macro Definition Documentation

◆ RTEMS_CAPTURE_FROM_TRIGS

#define RTEMS_CAPTURE_FROM_TRIGS

Value:

(RTEMS_CAPTURE_SWITCH  | \
                                     RTEMS_CAPTURE_CREATE | \
                                     RTEMS_CAPTURE_START | \
                                     RTEMS_CAPTURE_RESTART | \
                                     RTEMS_CAPTURE_DELETE)

◆ RTEMS_CAPTURE_TO_TRIGS

#define RTEMS_CAPTURE_TO_TRIGS

Value:

(RTEMS_CAPTURE_SWITCH | \
                                     RTEMS_CAPTURE_CREATE | \
                                     RTEMS_CAPTURE_START | \
                                     RTEMS_CAPTURE_RESTART | \
                                     RTEMS_CAPTURE_DELETE | \
                                     RTEMS_CAPTURE_BEGIN | \
                                     RTEMS_CAPTURE_EXITTED)

Typedef Documentation

◆ rtems_capture_control_t

typedef struct rtems_capture_control_s rtems_capture_control_t

Capture control structure for a group of tasks.

RTEMS control holds the trigger and watch configuration for a group of tasks with the same name. The flags hold global control flags.

The to_triggers fields holds triggers TO this task. The from_triggers holds triggers from this task. The by_triggers is an OR or triggers which are caused BY the task listed TO this task. The by_valid flag which entries in by are valid.

◆ rtems_capture_from_t

typedef struct rtems_capture_from_s rtems_capture_from_t

Task id and mask for the from trigger.

A from capture is a task id and a mask for the type of from trigger we are interested in. The mask uses the same bit maps as the flags field in the control structure. There will only be a from type trigger if the flags in the control structure has the specific *_BY bit set.

◆ rtems_capture_time_t

typedef uint64_t rtems_capture_time_t

A capture timestamp.

This is a nanosecond capture timestamp

◆ rtems_capture_timestamp

typedef void(* rtems_capture_timestamp) (rtems_capture_time_t *time)

Capture timestamp callout handler.

This defines the callout handler to obtain a time stamp. The value returned is time count since the last read.

◆ rtems_capture_trigger_mode_t

typedef enum rtems_capture_trigger_mode_e rtems_capture_trigger_mode_t

Capture trigger modes.

The types of trigger modes that exist.

◆ rtems_capture_trigger_t

typedef enum rtems_capture_trigger_e rtems_capture_trigger_t

Capture trigger.

The types of triggers that exist.

Enumeration Type Documentation

◆ rtems_capture_trigger_e

enum rtems_capture_trigger_e

Capture trigger.

The types of triggers that exist.

◆ rtems_capture_trigger_mode_e

enum rtems_capture_trigger_mode_e

Capture trigger modes.

The types of trigger modes that exist.

Function Documentation

◆ rtems_capture_clear_trigger()

rtems_status_code rtems_capture_clear_trigger	(	rtems_name	from_name,
		rtems_id	from_id,
		rtems_name	to_name,
		rtems_id	to_id,
		rtems_capture_trigger_mode_t	mode,
		rtems_capture_trigger_t	trigger
	)

Capture clear trigger.

This function clears a trigger.

This clear trigger routine will not clear a watch.

Parameters

[in]	from_name	specifies the name of the from task.
[in]	from_id	specifies the id of the from task.
[in]	to_name	specifies the name of the to task.
[in]	to_id	specifies the id of the to task.
[in]	mode	specifies the trigger mode.
[in]	trigger	specifies the type of trigger.

Return values

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

◆ rtems_capture_close()

rtems_status_code rtems_capture_close ( void )

Capture close.

This function shutdowns the tracer and release any claimed resources.

Return values

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

References rtems_interrupt_lock_acquire.

◆ rtems_capture_control()

rtems_status_code rtems_capture_control ( bool enable )

Capture control trace enable/disable.

This function allows control of tracing at a global level.

Parameters

[in] enable The trace enable/disable flag.

Return values

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

References rtems_interrupt_lock_acquire.

◆ rtems_capture_event_text()

const char* rtems_capture_event_text ( int event )

Capture get event text.

This function returns a string for an event based on the bit in the event. The functions takes the bit offset as a number not the bit set in a bit map.

Parameters

[in] event specifies the event to describe

Return values

This	method returns a string description of the given event.

◆ rtems_capture_get_control_list()

rtems_capture_control_t* rtems_capture_get_control_list ( void )

Capture get control list.

This function returns the head of the list of controls in the capture engine.

Return values

This	function returns the head of the list of controls in the capture engine.

Referenced by rtems_capture_print_watch_list().

◆ rtems_capture_initialize_task()

void rtems_capture_initialize_task ( rtems_tcb * tcb )

Capture initialize task.

This function initializes capture control in the tcb.

Parameters

[in] tcb is the task control block for the task

◆ rtems_capture_monitor()

rtems_status_code rtems_capture_monitor ( bool enable )

Capture monitor enable/disable.

This function enable the monitor mode. When in the monitor mode the tasks are monitored but no data is saved. This can be used to profile the load on a system.

Parameters

[in] enable The monitor enable/disable flag.

Return values

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

References rtems_interrupt_lock_acquire.

◆ rtems_capture_open()

rtems_status_code rtems_capture_open	(	uint32_t	size,
		rtems_capture_timestamp	timestamp
	)

Capture open.

This function initialises the realtime trace manager allocating the capture buffer. It is assumed we have a working heap at stage of initialisation.

Parameters

[in]	size	The number of capture records to define.
[in]	timestamp	The timestamp callout handler to use. If the the handler is NULL a default nano-second timestamp will be used.

Return values

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

References RTEMS_SUCCESSFUL.

◆ rtems_capture_read()

rtems_status_code rtems_capture_read	(	uint32_t	cpu,
		uint32_t *	read,
		rtems_capture_record_t **	recs
	)

Capture read records from capture buffer.

This function reads a number of records from the capture buffer.

The function returns the number of record that is has that are in a continous block of memory. If the number of available records wrap then only those records are provided. This removes the need for caller to be concerned about buffer wrappings. If the number of requested records cannot be met due to the wrapping of the records less than the specified number will be returned.

The user must release the records. This is achieved with a call to rtems_capture_release. Calls this function without a release will result in at least the same number of records being released.

Parameters

[in]	cpu	The cpu number that the records were recorded on
[out]	read	will contain the number of records read
[out]	recs	The capture records that are read.

Return values

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

References RTEMS_INTERRUPT_LOCK_REFERENCE, and RTEMS_SUCCESSFUL.

Referenced by rtems_capture_print_trace_records().

◆ rtems_capture_record_task()

void rtems_capture_record_task ( rtems_tcb * tcb )

Capture record task.

This function records a new capture task record.

Parameters

[in] tcb is the task control block for the task

References _RTEMS_tasks_Priority_from_Core(), Objects_Control::id, Thread_Start_information::initial_priority, Thread_Start_information::Initial_stack, Thread_Control::Object, rtems_interrupt_lock_acquire, rtems_object_get_classic_name(), Stack_Control::size, and Thread_Control::Start.

◆ rtems_capture_release()

rtems_status_code rtems_capture_release	(	uint32_t	cpu,
		uint32_t	count
	)

Capture release records.

This function releases the requested number of record slots back to the capture engine. The count must match the number read.

Parameters

[in] count The number of record slots to release

Return values

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

References RTEMS_INTERRUPT_LOCK_REFERENCE, and RTEMS_SUCCESSFUL.

◆ rtems_capture_set_trigger()

rtems_status_code rtems_capture_set_trigger	(	rtems_name	from_name,
		rtems_id	from_id,
		rtems_name	to_name,
		rtems_id	to_id,
		rtems_capture_trigger_mode_t	mode,
		rtems_capture_trigger_t	trigger
	)

Capture set trigger.

This function sets a trigger.

This set trigger routine will create a trace control for the target task. The task list is searched and any existing tasks are linked to the new control.

We can have a number of tasks that have the same name so we search using names. This means a number of tasks can be linked to single control.

Some events captured such as context switch include two tasks. These are referred to as being "from" and "to" Some events may only have one task specified.

Parameters

[in]	from_name	specifies the name of the from task.
[in]	from_id	specifies the id of the from task.
[in]	to_name	specifies the name of the to task.
[in]	to_id	specifies the id of the to task.
[in]	mode	specifies the trigger mode.
[in]	trigger	specifies the type of trigger.

Return values

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

◆ rtems_capture_watch_add()

rtems_status_code rtems_capture_watch_add	(	rtems_name	name,
		rtems_id	id
	)

Capture add watch.

This function defines a watch for a specific task given a name. A watch causes it to be traced either in or out of context. The watch can be optionally enabled or disabled with the set routine. It is disabled by default.

Parameters

[in]	name	The name of the capture_controls entry
[in]	id	The id of the capture_controls entry.

Return values

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

◆ rtems_capture_watch_ceiling()

rtems_status_code rtems_capture_watch_ceiling ( rtems_task_priority ceiling )

Set watch ceiling.

This function sets a watch ceiling. Events from tasks at or greater than the ceiling priority are ignored. This is a simple way to monitor an application and exclude system tasks running at a higher priority level.

Parameters

[in] ceiling specifies the priority level immediately above that at which events from tasks are not captured.

Return values

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

◆ rtems_capture_watch_ctrl()

rtems_status_code rtems_capture_watch_ctrl	(	rtems_name	name,
		rtems_id	id,
		bool	enable
	)

Capture enable/disable watch.

This function allows control of a watch. The watch can be enabled or disabled.

Parameters

[in]	name	The name of the capture_controls entry
[in]	id	The id of the capture_controls entry.
[in]	enable	The enable/disable flag for the watch.

Return values

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

◆ rtems_capture_watch_del()

rtems_status_code rtems_capture_watch_del	(	rtems_name	name,
		rtems_id	id
	)

Capture delete watch.

This function removes a watch for a specific task given a name. The task description will still exist if referenced by a trace record in the trace buffer or a global watch is defined.

Parameters

[in]	name	The name of the capture_controls entry
[in]	id	The id of the capture_controls entry.

Return values

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

◆ rtems_capture_watch_floor()

rtems_status_code rtems_capture_watch_floor ( rtems_task_priority floor )

Capture set watch floor.

This function sets a watch floor. Tasks at or less than the floor priority are not watched. This is a simple way to monitor an application and exclude system tasks running at a lower priority level.

Parameters

[in] floor specifies the priority level immediately below that at which events from tasks are not captured.

Return values

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

◆ rtems_capture_watch_get_ceiling()

rtems_task_priority rtems_capture_watch_get_ceiling ( void )

Get watch ceiling.

This function gets the watch ceiling.

Return values

The	priority level immediately above that at which events from tasks are not captured.

Referenced by rtems_capture_print_watch_list().

◆ rtems_capture_watch_get_floor()

rtems_task_priority rtems_capture_watch_get_floor ( void )

Capture set watch floor.

This function gets the watch floor.

Return values

The	priority level immediately below that at which events from tasks are not captured.

Referenced by rtems_capture_print_watch_list().

◆ rtems_capture_watch_global()

rtems_status_code rtems_capture_watch_global ( bool enable )

Capture enable/disable global watch.

This function allows control of a global watch. The watch can be enabled or disabled. A global watch configures all tasks below the ceiling and above the floor to be traced.

Parameters

[in] enable The enable/disable flag for the watch.

Return values

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

References rtems_interrupt_lock_acquire.

◆ rtems_capture_watch_global_on()

bool rtems_capture_watch_global_on ( void )

Get global watch state.

This function returns the global watch state.

Return values

This	method returns true if the global watch is on. Otherwise, it returns false.

Referenced by rtems_capture_print_watch_list().

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ RTEMS_CAPTURE_FROM_TRIGS

◆ RTEMS_CAPTURE_TO_TRIGS

Typedef Documentation

◆ rtems_capture_control_t

◆ rtems_capture_from_t

◆ rtems_capture_time_t

◆ rtems_capture_timestamp

◆ rtems_capture_trigger_mode_t

◆ rtems_capture_trigger_t

Enumeration Type Documentation

◆ rtems_capture_trigger_e

◆ rtems_capture_trigger_mode_e

Function Documentation

◆ rtems_capture_clear_trigger()

◆ rtems_capture_close()

◆ rtems_capture_control()

◆ rtems_capture_event_text()

◆ rtems_capture_get_control_list()

◆ rtems_capture_initialize_task()

◆ rtems_capture_monitor()

◆ rtems_capture_open()

◆ rtems_capture_read()

◆ rtems_capture_record_task()

◆ rtems_capture_release()

◆ rtems_capture_set_trigger()

◆ rtems_capture_watch_add()

◆ rtems_capture_watch_ceiling()

◆ rtems_capture_watch_ctrl()

◆ rtems_capture_watch_del()

◆ rtems_capture_watch_floor()

◆ rtems_capture_watch_get_ceiling()

◆ rtems_capture_watch_get_floor()

◆ rtems_capture_watch_global()

◆ rtems_capture_watch_global_on()