RTEMS  5.1
Data Structures | Macros | Typedefs | Enumerations | Functions
RTEMS Capture Engine

Data Structures

struct  rtems_capture_from
 Task id and mask for the from trigger. More...
 
struct  rtems_capture_control
 Capture control structure for a group of tasks. More...
 
struct  rtems_capture_record
 
struct  rtems_capture_task_record
 
struct  rtems_capture_record_lock_context
 Capture record lock context. More...
 

Macros

#define RTEMS_CAPTURE_INIT   (1u << 0)
 
#define RTEMS_CAPTURE_ON   (1U << 1)
 
#define RTEMS_CAPTURE_NO_MEMORY   (1U << 2)
 
#define RTEMS_CAPTURE_TRIGGERED   (1U << 3)
 
#define RTEMS_CAPTURE_GLOBAL_WATCH   (1U << 4)
 
#define RTEMS_CAPTURE_ONLY_MONITOR   (1U << 5)
 
#define RTEMS_CAPTURE_OVERFLOW   (1U << 0)
 
#define RTEMS_CAPTURE_READER_ACTIVE   (1U << 1)
 
#define RTEMS_CAPTURE_READER_WAITING   (1U << 2)
 
#define RTEMS_CAPTURE_TRIGGER_TASKS   (32)
 
#define RTEMS_CAPTURE_CONTROL_FROM_MASK(_s)   (UINT32_C(1) << (RTEMS_CAPTURE_TRIGGER_TASKS - ((_s) + 1)))
 
#define RTEMS_CAPTURE_WATCH   (1U << 0)
 
#define RTEMS_CAPTURE_SWITCH   (1 << 0)
 
#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)
 
#define RTEMS_CAPTURE_INIT_TASK   (1U << 1)
 
#define RTEMS_CAPTURE_RECORD_TASK   (1U << 2)
 
#define RTEMS_CAPTURE_REAL_PRI_EVENT_MASK   UINT32_C (0x000000ff)
 
#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
 A capture timestamp. More...
 
typedef struct rtems_capture_from rtems_capture_from
 Task id and mask for the from trigger. More...
 
typedef struct rtems_capture_control rtems_capture_control
 Capture control structure for a group of tasks. More...
 
typedef struct rtems_capture_record rtems_capture_record
 
typedef struct rtems_capture_task_record rtems_capture_task_record
 
typedef enum rtems_capture_trigger_mode rtems_capture_trigger_mode
 Capture trigger modes. More...
 
typedef enum rtems_capture_trigger rtems_capture_trigger
 Capture trigger. More...
 
typedef void(* rtems_capture_timestamp) (rtems_capture_time *time)
 Capture timestamp callout handler. More...
 

Enumerations

enum  rtems_capture_trigger_mode { rtems_capture_to_any, rtems_capture_from_any, rtems_capture_from_to }
 Capture trigger modes. More...
 
enum  rtems_capture_trigger {
  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_set_control (bool enable)
 Capture control trace enable/disable. More...
 
rtems_status_code rtems_capture_set_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 mode, rtems_capture_trigger 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 mode, rtems_capture_trigger trigger)
 Capture clear trigger. More...
 
rtems_status_code rtems_capture_read (uint32_t cpu, size_t *read, const void **recs)
 Capture read records from capture buffer. More...
 
rtems_status_code rtems_capture_release (uint32_t cpu, uint32_t count)
 Capture release records. More...
 
bool rtems_capture_filter (rtems_tcb *task, uint32_t events)
 Capture filter. More...
 
void rtems_capture_get_time (rtems_capture_time *time)
 Capture returns the current time. More...
 
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...
 
void rtems_capture_record_lock (rtems_capture_record_lock_context *context)
 Capture record lock. More...
 
void rtems_capture_record_unlock (rtems_capture_record_lock_context *context)
 Capture record unlock. More...
 
void * rtems_capture_record_open (rtems_tcb *task, uint32_t events, size_t size, rtems_capture_record_lock_context *context)
 Capture record open. More...
 
void rtems_capture_record_close (rtems_capture_record_lock_context *context)
 Capture record close. More...
 
rtems_capture_controlrtems_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_CONTROL_FROM_MASK

#define RTEMS_CAPTURE_CONTROL_FROM_MASK (   _s)    (UINT32_C(1) << (RTEMS_CAPTURE_TRIGGER_TASKS - ((_s) + 1)))

The from_valid mask.

◆ RTEMS_CAPTURE_FROM_TRIGS

#define RTEMS_CAPTURE_FROM_TRIGS
Value:
RTEMS_CAPTURE_CREATE | \
RTEMS_CAPTURE_START | \
RTEMS_CAPTURE_RESTART | \
RTEMS_CAPTURE_DELETE)
#define RTEMS_CAPTURE_SWITCH
Definition: capture.h:135

◆ RTEMS_CAPTURE_REAL_PRI_EVENT_MASK

#define RTEMS_CAPTURE_REAL_PRI_EVENT_MASK   UINT32_C (0x000000ff)

The capture record event flags.

◆ RTEMS_CAPTURE_SWITCH

#define RTEMS_CAPTURE_SWITCH   (1 << 0)

Control triggers.

◆ RTEMS_CAPTURE_TO_TRIGS

#define RTEMS_CAPTURE_TO_TRIGS
Value:
RTEMS_CAPTURE_CREATE | \
RTEMS_CAPTURE_START | \
RTEMS_CAPTURE_RESTART | \
RTEMS_CAPTURE_DELETE | \
RTEMS_CAPTURE_BEGIN | \
RTEMS_CAPTURE_EXITTED)
#define RTEMS_CAPTURE_SWITCH
Definition: capture.h:135

◆ RTEMS_CAPTURE_TRACED

#define RTEMS_CAPTURE_TRACED   (1U << 0)

Task flags.

◆ RTEMS_CAPTURE_TRIGGER_TASKS

#define RTEMS_CAPTURE_TRIGGER_TASKS   (32)

The number of tasks in a trigger group.

◆ RTEMS_CAPTURE_WATCH

#define RTEMS_CAPTURE_WATCH   (1U << 0)

Control flags.

Typedef Documentation

◆ rtems_capture_control

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

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

typedef uint64_t rtems_capture_time

A capture timestamp.

This is a nanosecond capture timestamp

◆ rtems_capture_timestamp

typedef void(* rtems_capture_timestamp) (rtems_capture_time *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

Capture trigger.

The types of triggers that exist.

◆ rtems_capture_trigger_mode

Capture trigger modes.

The types of trigger modes that exist.

Enumeration Type Documentation

◆ rtems_capture_trigger

Capture trigger.

The types of triggers that exist.

◆ rtems_capture_trigger_mode

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  mode,
rtems_capture_trigger  trigger 
)

Capture clear trigger.

This function clears a trigger.

This clear trigger routine will not clear a watch.

Parameters
[in]from_namespecifies the name of the from task.
[in]from_idspecifies the id of the from task.
[in]to_namespecifies the name of the to task.
[in]to_idspecifies the id of the to task.
[in]modespecifies the trigger mode.
[in]triggerspecifies the type of trigger.
Return values
Thismethod 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
Thismethod returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

◆ 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]eventspecifies the event to describe
Return values
Thismethod returns a string description of the given event.

◆ rtems_capture_filter()

bool rtems_capture_filter ( rtems_tcb task,
uint32_t  events 
)

Capture filter.

This function this function specifies if the given task and events should be logged.

Parameters
[in]taskspecifies the capture task control block
[in]eventsspecifies the events
Return values
Thismethod returns true if this data should be filtered from the log. It returns false if this data should be logged.

◆ rtems_capture_get_control_list()

rtems_capture_control* 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
Thisfunction returns the head of the list of controls in the capture engine.

◆ rtems_capture_get_time()

void rtems_capture_get_time ( rtems_capture_time time)

Capture returns the current time.

This function returns the current time. If a handler is provided by the user the time is gotten from that.

Parameters
[in]timespecifies the capture time
Return values
Thismethod returns a nano-second time if no user handler is provided. Otherwise, it returns a resolution defined by the handler.

◆ 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]tcbis the task control block for the task

◆ 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]sizeThe number of capture records to define.
[in]timestampThe timestamp callout handler to use. If the the handler is NULL a default nano-second timestamp will be used.
Return values
Thismethod returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

◆ rtems_capture_read()

rtems_status_code rtems_capture_read ( uint32_t  cpu,
size_t *  read,
const void **  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]cpuThe cpu number that the records were recorded on
[out]readwill contain the number of records read
[out]recsThe capture records that are read.
Return values
Thismethod returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

◆ rtems_capture_record_close()

void rtems_capture_record_close ( rtems_capture_record_lock_context context)

Capture record close.

This function closes writing to capure record and releases the lock that was held on the per CPU buffer.

Parameters
[out]contextspecifies the record context

◆ rtems_capture_record_lock()

void rtems_capture_record_lock ( rtems_capture_record_lock_context context)

Capture record lock.

This does a lock acquire which will remain in effect until rtems_capture_record_unlock is called.

Parameters
[out]contextspecifies the record context

◆ rtems_capture_record_open()

void* rtems_capture_record_open ( rtems_tcb task,
uint32_t  events,
size_t  size,
rtems_capture_record_lock_context context 
)

Capture record open.

This function allocates a record and fills in the header information. It does a lock acquire which will remain in effect until rtems_capture_record_close is called. The size is the amount of user data being recorded. The record header is internally managed.

Parameters
[in]taskspecifies the caputre task block
[in]eventsspecifies the events
[in]sizespecifies the user's capture data size
[out]contextspecifies the record context
Return values
Thismethod returns a pointer to the next location in the capture record to store data.

◆ 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]tcbis the task control block for the task

◆ rtems_capture_record_unlock()

void rtems_capture_record_unlock ( rtems_capture_record_lock_context context)

Capture record unlock.

This unlocks the record lock.

Parameters
[in]contextspecifies the record context

◆ 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]countThe number of record slots to release
Return values
Thismethod returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

◆ rtems_capture_set_control()

rtems_status_code rtems_capture_set_control ( bool  enable)

Capture control trace enable/disable.

This function allows control of tracing at a global level.

Parameters
[in]enableThe trace enable/disable flag.
Return values
Thismethod returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

◆ rtems_capture_set_monitor()

rtems_status_code rtems_capture_set_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]enableThe monitor enable/disable flag.
Return values
Thismethod returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

◆ 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  mode,
rtems_capture_trigger  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_namespecifies the name of the from task.
[in]from_idspecifies the id of the from task.
[in]to_namespecifies the name of the to task.
[in]to_idspecifies the id of the to task.
[in]modespecifies the trigger mode.
[in]triggerspecifies the type of trigger.
Return values
Thismethod 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]nameThe name of the capture_controls entry
[in]idThe id of the capture_controls entry.
Return values
Thismethod 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]ceilingspecifies the priority level immediately above that at which events from tasks are not captured.
Return values
Thismethod 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]nameThe name of the capture_controls entry
[in]idThe id of the capture_controls entry.
[in]enableThe enable/disable flag for the watch.
Return values
Thismethod 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]nameThe name of the capture_controls entry
[in]idThe id of the capture_controls entry.
Return values
Thismethod 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]floorspecifies the priority level immediately below that at which events from tasks are not captured.
Return values
Thismethod 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
Thepriority level immediately above that at which events from tasks are not captured.

◆ 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
Thepriority level immediately below that at which events from tasks are not captured.

◆ 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]enableThe enable/disable flag for the watch.
Return values
Thismethod returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

◆ 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
Thismethod returns true if the global watch is on. Otherwise, it returns false.