capture.h

Go to the documentation of this file.

/*
  ------------------------------------------------------------------------

  Copyright Objective Design Systems Pty Ltd, 2002
  All rights reserved Objective Design Systems Pty Ltd, 2002
  Chris Johns (ccj@acm.org)

  COPYRIGHT (c) 1989-2014
  On-Line Applications Research Corporation (OAR).

  The license and distribution terms for this file may be
  found in the file LICENSE in this distribution.

  This software with is provided ``as is'' and with NO WARRANTY.

  ------------------------------------------------------------------------

  RTEMS Performance Monitoring and Measurement Framework.
  This is the Capture Engine component.

*/

#ifndef __CAPTURE_H_
#define __CAPTURE_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <rtems.h>
#include <rtems/rtems/tasksimpl.h>

#define RTEMS_CAPTURE_TRIGGER_TASKS (32)

typedef uint64_t rtems_capture_time_t;

typedef struct rtems_capture_from_s
{
  rtems_name name;
  rtems_id   id;
  uint32_t   trigger;
} rtems_capture_from_t;

typedef struct rtems_capture_control_s
{
  rtems_name                      name;
  rtems_id                        id;
  uint32_t                        flags;
  uint32_t                        to_triggers;
  uint32_t                        from_triggers;
  uint32_t                        by_triggers;
  uint32_t                        by_valid;
  rtems_capture_from_t            by[RTEMS_CAPTURE_TRIGGER_TASKS];
  struct rtems_capture_control_s* next;
} rtems_capture_control_t;

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

#define RTEMS_CAPTURE_TO_TRIGS      (RTEMS_CAPTURE_SWITCH | \
                                     RTEMS_CAPTURE_CREATE | \
                                     RTEMS_CAPTURE_START | \
                                     RTEMS_CAPTURE_RESTART | \
                                     RTEMS_CAPTURE_DELETE | \
                                     RTEMS_CAPTURE_BEGIN | \
                                     RTEMS_CAPTURE_EXITTED)

#define RTEMS_CAPTURE_TRACED      (1U << 0)
#define RTEMS_CAPTURE_INIT_TASK   (1U << 1)
#define RTEMS_CAPTURE_RECORD_TASK (1U << 2)

/*
 * @brief Capture record.
 *
 * This is a record that is written into
 * the buffer. The events includes the priority of the task
 * at the time of the context switch.
 */
typedef struct rtems_capture_record_s
{
  uint32_t              events;
  rtems_capture_time_t  time;
  size_t                size;
  rtems_id              task_id;
} rtems_capture_record_t;

/*
 * @brief Capture task record.
 *
 * This is a record that is written into
 * the buffer. The events includes the priority of the task
 * at the time of the context switch.
 */
typedef struct rtems_capture_task_record_s
{
  rtems_capture_record_t rec;
  rtems_name             name;
  rtems_task_priority    start_priority;
  uint32_t               stack_size;
} rtems_capture_task_record_t;

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

typedef enum rtems_capture_trigger_mode_e
{
  rtems_capture_to_any,
  rtems_capture_from_any,
  rtems_capture_from_to
} rtems_capture_trigger_mode_t;

typedef 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
} rtems_capture_trigger_t;

typedef void (*rtems_capture_timestamp)(rtems_capture_time_t* time);

rtems_status_code
rtems_capture_open (uint32_t                size,
                    rtems_capture_timestamp timestamp);

rtems_status_code
rtems_capture_close (void);

rtems_status_code
rtems_capture_control (bool enable);

rtems_status_code
rtems_capture_monitor (bool enable);

/*
 * @brief Capture flush trace buffer.
 *
 * This function flushes the trace buffer. The prime parameter allows the
 * capture engine to also be primed again.
 *
 * @param[in]  prime The prime after flush flag.
 *
 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
 *         error. Otherwise, a status code is returned indicating the
 *         source of the error.
 */
rtems_status_code
rtems_capture_flush (bool prime);

rtems_status_code
rtems_capture_watch_add (rtems_name name, rtems_id id);

rtems_status_code
rtems_capture_watch_del (rtems_name name, rtems_id id);

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

rtems_status_code
rtems_capture_watch_global (bool enable);

bool
rtems_capture_watch_global_on (void);

rtems_status_code
rtems_capture_watch_ceiling (rtems_task_priority ceiling);

rtems_task_priority
rtems_capture_watch_get_ceiling (void);

rtems_status_code
rtems_capture_watch_floor (rtems_task_priority floor);

rtems_task_priority
rtems_capture_watch_get_floor (void);

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);

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);

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

rtems_status_code
rtems_capture_release (uint32_t cpu, uint32_t count);

/*
 * @brief Capture nano-second time period.
 *
 * This function returns the time period in nano-seconds.
 *
 * @param[out] uptime The nano-second time period.
 */
void
rtems_capture_time (rtems_capture_time_t* uptime);

const char*
rtems_capture_event_text (int event);

void rtems_capture_initialize_task( rtems_tcb* tcb );

void rtems_capture_record_task( rtems_tcb* tcb );

static inline bool rtems_capture_task_recorded( rtems_tcb* tcb ) {
  return ( (tcb->Capture.flags & RTEMS_CAPTURE_RECORD_TASK) != 0 );
}

static inline bool rtems_capture_task_initialized( rtems_tcb* tcb ) {
  return ( (tcb->Capture.flags & RTEMS_CAPTURE_INIT_TASK) != 0 );
}

static inline rtems_id
rtems_capture_task_id (rtems_tcb* tcb)
{
  return tcb->Object.id;
}

static inline States_Control
rtems_capture_task_state (rtems_tcb* tcb)
{
  if (tcb)
    return tcb->current_state;
  return 0;
}

static inline rtems_name
rtems_capture_task_name (rtems_tcb* tcb)
{
  rtems_name  name;
  rtems_object_get_classic_name( tcb->Object.id, &name );
  return name;
}

static inline uint32_t
rtems_capture_task_flags (rtems_tcb* tcb)
{
  return tcb->Capture.flags;
}

static inline rtems_capture_control_t*
rtems_capture_task_control (rtems_tcb* tcb)
{
  return tcb->Capture.control;
}

static inline uint32_t
rtems_capture_task_control_flags (rtems_tcb* tcb)
{
  rtems_capture_control_t*  control = tcb->Capture.control;
  if (!control)
    return 0;
  return control->flags;
}

static inline rtems_task_priority
rtems_capture_task_start_priority (rtems_tcb* tcb)
{
  return _RTEMS_tasks_Priority_from_Core(
    tcb->Start.initial_priority
  );
}

static inline rtems_task_priority
rtems_capture_task_real_priority (rtems_tcb* tcb)
{
  return tcb->real_priority;
}

static inline rtems_task_priority
rtems_capture_task_curr_priority (rtems_tcb* tcb)
{
  return tcb->current_priority;
}

rtems_capture_control_t*
rtems_capture_get_control_list (void);

static inline rtems_capture_control_t*
rtems_capture_next_control (rtems_capture_control_t* control)
{
  return control->next;
}

static inline rtems_id
rtems_capture_control_id (rtems_capture_control_t* control)
{
  return control->id;
}

static inline rtems_name
rtems_capture_control_name (rtems_capture_control_t* control)
{
  return control->name;
}

static inline uint32_t
rtems_capture_control_flags (rtems_capture_control_t* control)
{
  return control->flags;
}

static inline uint32_t
rtems_capture_control_to_triggers (rtems_capture_control_t* control)
{
  return control->to_triggers;
}

static inline uint32_t
rtems_capture_control_from_triggers (rtems_capture_control_t* control)
{
  return control->from_triggers;
}

static inline uint32_t
rtems_capture_control_all_by_triggers (rtems_capture_control_t* control)
{
  return control->by_triggers;
}

static inline int
rtems_capture_control_by_valid (rtems_capture_control_t* control, int slot)
{
  return control->by_valid & RTEMS_CAPTURE_CONTROL_FROM_MASK (slot);
}

static inline rtems_name
rtems_capture_control_by_name (rtems_capture_control_t* control, int by)
{
  if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
    return control->by[by].name;
  return control->by[0].name;
}

static inline rtems_id
rtems_capture_control_by_id (rtems_capture_control_t* control, int by)
{
  if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
    return control->by[by].id;
  return control->by[0].id;
}

static inline uint32_t
rtems_capture_control_by_triggers (rtems_capture_control_t* control,
                                   int                      by)
{
  if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
    return control->by[by].trigger;
  return control->by[0].trigger;
}

static inline uint32_t
rtems_capture_control_count (void)
{
  rtems_capture_control_t* control = rtems_capture_get_control_list ();
  uint32_t                 count = 0;

  while (control)
  {
    count++;
    control = rtems_capture_next_control (control);
  }

  return count;
}

#ifdef __cplusplus
}
#endif

#endif