RTEMS: RTEMS Capture Engine

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Enumerations | Functions
RTEMS Capture Engine
API » Tracing

## 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.
typedef struct rtems_capture_from | rtems_capture_from
| Task id and mask for the from trigger.
typedef struct rtems_capture_control | rtems_capture_control
| Capture control structure for a group of tasks.
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.
typedef enum rtems_capture_trigger | rtems_capture_trigger
| Capture trigger.
typedef void(* | rtems_capture_timestamp) (rtems_capture_time *time)
| Capture timestamp callout handler.

## 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.
rtems_status_code | rtems_capture_close (void)
| Capture close.
rtems_status_code | rtems_capture_set_control (bool enable)
| Capture control trace enable/disable.
rtems_status_code | rtems_capture_set_monitor (bool enable)
| Capture monitor enable/disable.
rtems_status_code | rtems_capture_flush (bool prime)
rtems_status_code | rtems_capture_watch_add (rtems_name name, rtems_id id)
| Capture add watch.
rtems_status_code | rtems_capture_watch_del (rtems_name name, rtems_id id)
| Capture delete watch.
rtems_status_code | rtems_capture_watch_ctrl (rtems_name name, rtems_id id, bool enable)
| Capture enable/disable watch.
rtems_status_code | rtems_capture_watch_global (bool enable)
| Capture enable/disable global watch.
bool | rtems_capture_watch_global_on (void)
| Get global watch state.
rtems_status_code | rtems_capture_watch_ceiling (rtems_task_priority ceiling)
| Set watch ceiling.
rtems_task_priority | rtems_capture_watch_get_ceiling (void)
| Get watch ceiling.
rtems_status_code | rtems_capture_watch_floor (rtems_task_priority floor)
| Capture set watch floor.
rtems_task_priority | rtems_capture_watch_get_floor (void)
| Capture set watch floor.
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.
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.
rtems_status_code | rtems_capture_read (uint32_t cpu, size_t *read, const void **recs)
| Capture read records from capture buffer.
rtems_status_code | rtems_capture_release (uint32_t cpu, uint32_t count)
| Capture release records.
bool | rtems_capture_filter (rtems_tcb *task, uint32_t events)
| Capture filter.
void | rtems_capture_get_time (rtems_capture_time *time)
| Capture returns the current time.
const char * | rtems_capture_event_text (int event)
| Capture get event text.
void | rtems_capture_initialize_task (rtems_tcb *tcb)
| Capture initialize task.
void | rtems_capture_record_task (rtems_tcb *tcb)
| Capture record task.
void | rtems_capture_record_lock (rtems_capture_record_lock_context *context)
| Capture record lock.
void | rtems_capture_record_unlock (rtems_capture_record_lock_context *context)
| Capture record unlock.
void * | rtems_capture_record_open (rtems_tcb *task, uint32_t events, size_t size, rtems_capture_record_lock_context *context)
| Capture record open.
void | rtems_capture_record_close (rtems_capture_record_lock_context *context)
| Capture record close.
rtems_capture_control * | rtems_capture_get_control_list (void)
| Capture get control list.

## 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_SWITCH | \
RTEMS_CAPTURE_CREATE | \
RTEMS_CAPTURE_START | \
RTEMS_CAPTURE_RESTART | \
RTEMS_CAPTURE_DELETE)
RTEMS_CAPTURE_SWITCH
#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_SWITCH | \
RTEMS_CAPTURE_CREATE | \
RTEMS_CAPTURE_START | \
RTEMS_CAPTURE_RESTART | \
RTEMS_CAPTURE_DELETE | \
RTEMS_CAPTURE_BEGIN | \
RTEMS_CAPTURE_EXITTED)

## ◆ 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

typedef struct rtems_capture_control 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

typedef struct rtems_capture_from 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

typedef enum rtems_capture_trigger rtems_capture_trigger

Capture trigger.

The types of triggers that exist.

## ◆ rtems_capture_trigger_mode

typedef enum rtems_capture_trigger_mode rtems_capture_trigger_mode

Capture trigger modes.

The types of trigger modes that exist.

## Enumeration Type Documentation

## ◆ rtems_capture_trigger

enum rtems_capture_trigger

Capture trigger.

The types of triggers that exist.

## ◆ rtems_capture_trigger_mode

enum 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_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.

## ◆ 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_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] | task | specifies the capture task control block
  [in] | events | specifies the events

Return values

  This | method 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

  This | function 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] | time | specifies the capture time

Return values

  This | method 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] | tcb | is 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] | 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.

## ◆ 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] | 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.

## ◆ 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] | context | specifies 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] | context | specifies 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] | task | specifies the caputre task block
  [in] | events | specifies the events
  [in] | size | specifies the user's capture data size
  [out] | context | specifies the record context

Return values

  This | method 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] | tcb | is 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] | context | specifies 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] | 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.

## ◆ 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] | 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.

## ◆ 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] | 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.

## ◆ 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_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.

## ◆ 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.

## ◆ 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.

## ◆ 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.