RTEMS CPU Kit with SuperCore  4.10.99.0
rtems/capture.h
Go to the documentation of this file.
00001 
00011 /*
00012   ------------------------------------------------------------------------
00013 
00014   Copyright Objective Design Systems Pty Ltd, 2002
00015   All rights reserved Objective Design Systems Pty Ltd, 2002
00016   Chris Johns (ccj@acm.org)
00017 
00018   COPYRIGHT (c) 1989-1998.
00019   On-Line Applications Research Corporation (OAR).
00020 
00021   The license and distribution terms for this file may be
00022   found in the file LICENSE in this distribution.
00023 
00024   This software with is provided ``as is'' and with NO WARRANTY.
00025 
00026   ------------------------------------------------------------------------
00027 
00028   RTEMS Performance Monitoring and Measurement Framework.
00029   This is the Capture Engine component.
00030 
00031 */
00032 
00033 #ifndef __CAPTURE_H_
00034 #define __CAPTURE_H_
00035 
00044 #ifdef __cplusplus
00045 extern "C" {
00046 #endif
00047 
00048 #include <rtems.h>
00049 
00053 #define RTEMS_CAPTURE_TRIGGER_TASKS (32)
00054 
00060 typedef uint64_t rtems_capture_time_t;
00061 
00071 typedef struct rtems_capture_from_s
00072 {
00073   rtems_name name;
00074   rtems_id   id;
00075   uint32_t   trigger;
00076 } rtems_capture_from_t;
00077 
00089 typedef struct rtems_capture_control_s
00090 {
00091   rtems_name                      name;
00092   rtems_id                        id;
00093   uint32_t                        flags;
00094   uint32_t                        to_triggers;
00095   uint32_t                        from_triggers;
00096   uint32_t                        by_triggers;
00097   uint32_t                        by_valid;
00098   rtems_capture_from_t            by[RTEMS_CAPTURE_TRIGGER_TASKS];
00099   struct rtems_capture_control_s* next;
00100 } rtems_capture_control_t;
00101 
00105 #define RTEMS_CAPTURE_CONTROL_FROM_MASK(_s) \
00106  (UINT32_C(1) << (RTEMS_CAPTURE_TRIGGER_TASKS - ((_s) + 1)))
00107 
00111 #define RTEMS_CAPTURE_WATCH         (1U << 0)
00112 
00116 #define RTEMS_CAPTURE_SWITCH        (1 << 0)
00117 #define RTEMS_CAPTURE_CREATE        (1 << 1)
00118 #define RTEMS_CAPTURE_START         (1 << 2)
00119 #define RTEMS_CAPTURE_RESTART       (1 << 3)
00120 #define RTEMS_CAPTURE_DELETE        (1 << 4)
00121 #define RTEMS_CAPTURE_BEGIN         (1 << 5)
00122 #define RTEMS_CAPTURE_EXITTED       (1 << 6)
00123 #define RTEMS_CAPTURE_TERMINATED    (1 << 7)
00124 
00125 #define RTEMS_CAPTURE_FROM_TRIGS    (RTEMS_CAPTURE_SWITCH  | \
00126                                      RTEMS_CAPTURE_CREATE | \
00127                                      RTEMS_CAPTURE_START | \
00128                                      RTEMS_CAPTURE_RESTART | \
00129                                      RTEMS_CAPTURE_DELETE)
00130 
00131 #define RTEMS_CAPTURE_TO_TRIGS      (RTEMS_CAPTURE_SWITCH | \
00132                                      RTEMS_CAPTURE_CREATE | \
00133                                      RTEMS_CAPTURE_START | \
00134                                      RTEMS_CAPTURE_RESTART | \
00135                                      RTEMS_CAPTURE_DELETE | \
00136                                      RTEMS_CAPTURE_BEGIN | \
00137                                      RTEMS_CAPTURE_EXITTED)
00138 
00157 typedef struct rtems_capture_task_s
00158 {
00159   rtems_name                   name;
00160   rtems_id                     id;
00161   uint32_t                     flags;
00162   uint32_t                     refcount;
00163   rtems_tcb*                   tcb;
00164   uint32_t                     in;
00165   uint32_t                     out;
00166   rtems_task_priority          start_priority;
00167   uint32_t                     stack_size;
00168   uint32_t                     stack_clean;
00169   rtems_capture_time_t         time;
00170   rtems_capture_time_t         time_in;
00171   rtems_capture_time_t         last_time;
00172   rtems_capture_control_t*     control;
00173   struct rtems_capture_task_s* forw;
00174   struct rtems_capture_task_s* back;
00175 } rtems_capture_task_t;
00176 
00180 #define RTEMS_CAPTURE_TRACED  (1U << 0)
00181 
00182 /*
00183  * @brief Capture record.
00184  *
00185  * This is a record that is written into
00186  * the buffer. The events includes the priority of the task
00187  * at the time of the context switch.
00188  */
00189 typedef struct rtems_capture_record_s
00190 {
00191   rtems_capture_task_t* task;
00192   uint32_t              events;
00193   rtems_capture_time_t  time;
00194   size_t                size;
00195 } rtems_capture_record_t;
00196 
00200 #define RTEMS_CAPTURE_REAL_PRI_EVENT_MASK UINT32_C (0x000000ff)
00201 #define RTEMS_CAPTURE_CURR_PRI_EVENT_MASK UINT32_C (0x0000ff00)
00202 #define RTEMS_CAPTURE_REAL_PRIORITY_EVENT (0)
00203 #define RTEMS_CAPTURE_CURR_PRIORITY_EVENT (8)
00204 #define RTEMS_CAPTURE_EVENT_START         (16)
00205 #define RTEMS_CAPTURE_CREATED_BY_EVENT    UINT32_C (0x00010000)
00206 #define RTEMS_CAPTURE_CREATED_EVENT       UINT32_C (0x00020000)
00207 #define RTEMS_CAPTURE_STARTED_BY_EVENT    UINT32_C (0x00040000)
00208 #define RTEMS_CAPTURE_STARTED_EVENT       UINT32_C (0x00080000)
00209 #define RTEMS_CAPTURE_RESTARTED_BY_EVENT  UINT32_C (0x00100000)
00210 #define RTEMS_CAPTURE_RESTARTED_EVENT     UINT32_C (0x00200000)
00211 #define RTEMS_CAPTURE_DELETED_BY_EVENT    UINT32_C (0x00400000)
00212 #define RTEMS_CAPTURE_DELETED_EVENT       UINT32_C (0x00800000)
00213 #define RTEMS_CAPTURE_TERMINATED_EVENT    UINT32_C (0x01000000)
00214 #define RTEMS_CAPTURE_BEGIN_EVENT         UINT32_C (0x02000000)
00215 #define RTEMS_CAPTURE_EXITTED_EVENT       UINT32_C (0x04000000)
00216 #define RTEMS_CAPTURE_SWITCHED_OUT_EVENT  UINT32_C (0x08000000)
00217 #define RTEMS_CAPTURE_SWITCHED_IN_EVENT   UINT32_C (0x10000000)
00218 #define RTEMS_CAPTURE_TIMESTAMP           UINT32_C (0x20000000)
00219 #define RTEMS_CAPTURE_EVENT_END           (29)
00220 
00226 typedef enum rtems_capture_trigger_mode_e
00227 {
00228   rtems_capture_to_any,
00229   rtems_capture_from_any,
00230   rtems_capture_from_to
00231 } rtems_capture_trigger_mode_t;
00232 
00238 typedef enum rtems_capture_trigger_e
00239 {
00240   rtems_capture_switch,
00241   rtems_capture_create,
00242   rtems_capture_start,
00243   rtems_capture_restart,
00244   rtems_capture_delete,
00245   rtems_capture_begin,
00246   rtems_capture_exitted,
00247   rtems_capture_terminated
00248 } rtems_capture_trigger_t;
00249 
00258 typedef void (*rtems_capture_timestamp)(rtems_capture_time_t* time);
00259 
00276 rtems_status_code
00277 rtems_capture_open (uint32_t                size,
00278                     rtems_capture_timestamp timestamp);
00279 
00290 rtems_status_code
00291 rtems_capture_close (void);
00292 
00304 rtems_status_code
00305 rtems_capture_control (bool enable);
00306 
00320 rtems_status_code
00321 rtems_capture_monitor (bool enable);
00322 
00323 /*
00324  * @brief Capture flush trace buffer.
00325  *
00326  * This function flushes the trace buffer. The prime parameter allows the
00327  * capture engine to also be primed again.
00328  *
00329  * @param[in]  prime The prime after flush flag.
00330  *
00331  * @retval This method returns RTEMS_SUCCESSFUL if there was not an
00332  *         error. Otherwise, a status code is returned indicating the
00333  *         source of the error.
00334  */
00335 rtems_status_code
00336 rtems_capture_flush (bool prime);
00337 
00353 rtems_status_code
00354 rtems_capture_watch_add (rtems_name name, rtems_id id);
00355 
00370 rtems_status_code
00371 rtems_capture_watch_del (rtems_name name, rtems_id id);
00372 
00387 rtems_status_code
00388 rtems_capture_watch_ctrl (rtems_name    name,
00389                           rtems_id      id,
00390                           bool enable);
00391 
00405 rtems_status_code
00406 rtems_capture_watch_global (bool enable);
00407 
00416 bool
00417 rtems_capture_watch_global_on (void);
00418 
00434 rtems_status_code
00435 rtems_capture_watch_ceiling (rtems_task_priority ceiling);
00436 
00445 rtems_task_priority
00446 rtems_capture_watch_get_ceiling (void);
00447 
00463 rtems_status_code
00464 rtems_capture_watch_floor (rtems_task_priority floor);
00465 
00474 rtems_task_priority
00475 rtems_capture_watch_get_floor (void);
00476 
00505 rtems_status_code
00506 rtems_capture_set_trigger (rtems_name                   from_name,
00507                            rtems_id                     from_id,
00508                            rtems_name                   to_name,
00509                            rtems_id                     to_id,
00510                            rtems_capture_trigger_mode_t mode,
00511                            rtems_capture_trigger_t      trigger);
00512 
00531 rtems_status_code
00532 rtems_capture_clear_trigger (rtems_name                   from_name,
00533                              rtems_id                     from_id,
00534                              rtems_name                   to_name,
00535                              rtems_id                     to_id,
00536                              rtems_capture_trigger_mode_t mode,
00537                              rtems_capture_trigger_t      trigger);
00538 
00576 rtems_status_code
00577 rtems_capture_read (uint32_t                 threshold,
00578                     uint32_t                 timeout,
00579                     uint32_t*                read,
00580                     rtems_capture_record_t** recs);
00581 
00594 rtems_status_code
00595 rtems_capture_release (uint32_t count);
00596 
00597 /*
00598  * @brief Capture nano-second time period.
00599  *
00600  * This function returns the time period in nano-seconds.
00601  *
00602  * @param[out] uptime The nano-second time period.
00603  */
00604 void
00605 rtems_capture_time (rtems_capture_time_t* uptime);
00606 
00618 const char*
00619 rtems_capture_event_text (int event);
00620 
00630 rtems_capture_task_t*
00631 rtems_capture_get_task_list (void);
00632 
00644 static inline rtems_capture_task_t*
00645 rtems_capture_next_task (rtems_capture_task_t* task)
00646 {
00647   return task->forw;
00648 }
00649 
00661 static inline bool
00662 rtems_capture_task_valid (rtems_capture_task_t* task)
00663 {
00664   return task->tcb != NULL;
00665 }
00666 
00676 static inline rtems_id
00677 rtems_capture_task_id (rtems_capture_task_t* task)
00678 {
00679   return task->id;
00680 }
00681 
00691 static inline States_Control
00692 rtems_capture_task_state (rtems_capture_task_t* task)
00693 {
00694   if (rtems_capture_task_valid (task))
00695     return task->tcb->current_state;
00696   return 0;
00697 }
00698 
00708 static inline rtems_name
00709 rtems_capture_task_name (rtems_capture_task_t* task)
00710 {
00711   return task->name;
00712 }
00713 
00723 static inline uint32_t
00724 rtems_capture_task_flags (rtems_capture_task_t* task)
00725 {
00726   return task->flags;
00727 }
00728 
00738 static inline rtems_capture_control_t*
00739 rtems_capture_task_control (rtems_capture_task_t* task)
00740 {
00741   return task->control;
00742 }
00743 
00753 static inline uint32_t
00754 rtems_capture_task_control_flags (rtems_capture_task_t* task)
00755 {
00756   if (!task->control)
00757     return 0;
00758   return task->control->flags;
00759 }
00760 
00772 static inline uint32_t
00773 rtems_capture_task_switched_in (rtems_capture_task_t* task)
00774 {
00775   return task->in;
00776 }
00777 
00789 static inline uint32_t
00790 rtems_capture_task_switched_out (rtems_capture_task_t* task)
00791 {
00792   return task->out;
00793 }
00794 
00806 static inline rtems_task_priority
00807 rtems_capture_task_start_priority (rtems_capture_task_t* task)
00808 {
00809   return task->start_priority;
00810 }
00811 
00821 static inline rtems_task_priority
00822 rtems_capture_task_real_priority (rtems_capture_task_t* task)
00823 {
00824   if (rtems_capture_task_valid (task))
00825     return task->tcb->real_priority;
00826   return 0;
00827 }
00828 
00838 static inline rtems_task_priority
00839 rtems_capture_task_curr_priority (rtems_capture_task_t* task)
00840 {
00841   if (rtems_capture_task_valid (task))
00842     return task->tcb->current_priority;
00843   return 0;
00844 }
00845 
00857 uint32_t
00858 rtems_capture_task_stack_usage (rtems_capture_task_t* task);
00859 
00869 static inline uint32_t
00870 rtems_capture_task_stack_size (rtems_capture_task_t* task)
00871 {
00872   return task->stack_size;
00873 }
00874 
00884 static inline uint32_t
00885 rtems_capture_task_stack_used (rtems_capture_task_t* task)
00886 {
00887   return task->stack_size - task->stack_clean;
00888 }
00889 
00899 static inline uint64_t
00900 rtems_capture_task_time (rtems_capture_task_t* task)
00901 {
00902   return task->time;
00903 }
00904 
00916 static inline uint64_t
00917 rtems_capture_task_delta_time (rtems_capture_task_t* task)
00918 {
00919   uint64_t t = task->time - task->last_time;
00920   task->last_time = task->time;
00921   return t;
00922 }
00923 
00933 static inline uint32_t
00934 rtems_capture_task_count (void)
00935 {
00936   rtems_capture_task_t* task = rtems_capture_get_task_list ();
00937   uint32_t              count = 0;
00938 
00939   while (task)
00940   {
00941     count++;
00942     task = rtems_capture_next_task (task);
00943   }
00944 
00945   return count;
00946 }
00947 
00957 rtems_capture_control_t*
00958 rtems_capture_get_control_list (void);
00959 
00971 static inline rtems_capture_control_t*
00972 rtems_capture_next_control (rtems_capture_control_t* control)
00973 {
00974   return control->next;
00975 }
00976 
00986 static inline rtems_id
00987 rtems_capture_control_id (rtems_capture_control_t* control)
00988 {
00989   return control->id;
00990 }
00991 
01001 static inline rtems_name
01002 rtems_capture_control_name (rtems_capture_control_t* control)
01003 {
01004   return control->name;
01005 }
01006 
01016 static inline uint32_t
01017 rtems_capture_control_flags (rtems_capture_control_t* control)
01018 {
01019   return control->flags;
01020 }
01021 
01031 static inline uint32_t
01032 rtems_capture_control_to_triggers (rtems_capture_control_t* control)
01033 {
01034   return control->to_triggers;
01035 }
01036 
01046 static inline uint32_t
01047 rtems_capture_control_from_triggers (rtems_capture_control_t* control)
01048 {
01049   return control->from_triggers;
01050 }
01051 
01061 static inline uint32_t
01062 rtems_capture_control_all_by_triggers (rtems_capture_control_t* control)
01063 {
01064   return control->by_triggers;
01065 }
01066 
01077 static inline int
01078 rtems_capture_control_by_valid (rtems_capture_control_t* control, int slot)
01079 {
01080   return control->by_valid & RTEMS_CAPTURE_CONTROL_FROM_MASK (slot);
01081 }
01082 
01093 static inline rtems_name
01094 rtems_capture_control_by_name (rtems_capture_control_t* control, int by)
01095 {
01096   if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
01097     return control->by[by].name;
01098   return control->by[0].name;
01099 }
01100 
01108 static inline rtems_id
01109 rtems_capture_control_by_id (rtems_capture_control_t* control, int by)
01110 {
01111   if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
01112     return control->by[by].id;
01113   return control->by[0].id;
01114 }
01115 
01123 static inline uint32_t
01124 rtems_capture_control_by_triggers (rtems_capture_control_t* control,
01125                                    int                      by)
01126 {
01127   if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
01128     return control->by[by].trigger;
01129   return control->by[0].trigger;
01130 }
01131 
01141 static inline uint32_t
01142 rtems_capture_control_count (void)
01143 {
01144   rtems_capture_control_t* control = rtems_capture_get_control_list ();
01145   uint32_t                 count = 0;
01146 
01147   while (control)
01148   {
01149     count++;
01150     control = rtems_capture_next_control (control);
01151   }
01152 
01153   return count;
01154 }
01155 
01156 #ifdef __cplusplus
01157 }
01158 #endif
01159 
01160 #endif