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 } rtems_capture_record_t;
00195 
00199 #define RTEMS_CAPTURE_REAL_PRI_EVENT_MASK UINT32_C (0x000000ff)
00200 #define RTEMS_CAPTURE_CURR_PRI_EVENT_MASK UINT32_C (0x0000ff00)
00201 #define RTEMS_CAPTURE_REAL_PRIORITY_EVENT (0)
00202 #define RTEMS_CAPTURE_CURR_PRIORITY_EVENT (8)
00203 #define RTEMS_CAPTURE_EVENT_START         (16)
00204 #define RTEMS_CAPTURE_CREATED_BY_EVENT    UINT32_C (0x00010000)
00205 #define RTEMS_CAPTURE_CREATED_EVENT       UINT32_C (0x00020000)
00206 #define RTEMS_CAPTURE_STARTED_BY_EVENT    UINT32_C (0x00040000)
00207 #define RTEMS_CAPTURE_STARTED_EVENT       UINT32_C (0x00080000)
00208 #define RTEMS_CAPTURE_RESTARTED_BY_EVENT  UINT32_C (0x00100000)
00209 #define RTEMS_CAPTURE_RESTARTED_EVENT     UINT32_C (0x00200000)
00210 #define RTEMS_CAPTURE_DELETED_BY_EVENT    UINT32_C (0x00400000)
00211 #define RTEMS_CAPTURE_DELETED_EVENT       UINT32_C (0x00800000)
00212 #define RTEMS_CAPTURE_TERMINATED_EVENT    UINT32_C (0x01000000)
00213 #define RTEMS_CAPTURE_BEGIN_EVENT         UINT32_C (0x02000000)
00214 #define RTEMS_CAPTURE_EXITTED_EVENT       UINT32_C (0x04000000)
00215 #define RTEMS_CAPTURE_SWITCHED_OUT_EVENT  UINT32_C (0x08000000)
00216 #define RTEMS_CAPTURE_SWITCHED_IN_EVENT   UINT32_C (0x10000000)
00217 #define RTEMS_CAPTURE_TIMESTAMP           UINT32_C (0x20000000)
00218 #define RTEMS_CAPTURE_EVENT_END           (29)
00219 
00225 typedef enum rtems_capture_trigger_mode_e
00226 {
00227   rtems_capture_to_any,
00228   rtems_capture_from_any,
00229   rtems_capture_from_to
00230 } rtems_capture_trigger_mode_t;
00231 
00237 typedef enum rtems_capture_trigger_e
00238 {
00239   rtems_capture_switch,
00240   rtems_capture_create,
00241   rtems_capture_start,
00242   rtems_capture_restart,
00243   rtems_capture_delete,
00244   rtems_capture_begin,
00245   rtems_capture_exitted,
00246   rtems_capture_terminated
00247 } rtems_capture_trigger_t;
00248 
00257 typedef void (*rtems_capture_timestamp)(rtems_capture_time_t* time);
00258 
00275 rtems_status_code
00276 rtems_capture_open (uint32_t                size,
00277                     rtems_capture_timestamp timestamp);
00278 
00289 rtems_status_code
00290 rtems_capture_close (void);
00291 
00303 rtems_status_code
00304 rtems_capture_control (bool enable);
00305 
00319 rtems_status_code
00320 rtems_capture_monitor (bool enable);
00321 
00322 /*
00323  * @brief Capture flush trace buffer.
00324  *
00325  * This function flushes the trace buffer. The prime parameter allows the
00326  * capture engine to also be primed again.
00327  *
00328  * @param[in]  prime The prime after flush flag.
00329  *
00330  * @retval This method returns RTEMS_SUCCESSFUL if there was not an
00331  *         error. Otherwise, a status code is returned indicating the
00332  *         source of the error.
00333  */
00334 rtems_status_code
00335 rtems_capture_flush (bool prime);
00336 
00352 rtems_status_code
00353 rtems_capture_watch_add (rtems_name name, rtems_id id);
00354 
00369 rtems_status_code
00370 rtems_capture_watch_del (rtems_name name, rtems_id id);
00371 
00386 rtems_status_code
00387 rtems_capture_watch_ctrl (rtems_name    name,
00388                           rtems_id      id,
00389                           bool enable);
00390 
00404 rtems_status_code
00405 rtems_capture_watch_global (bool enable);
00406 
00415 bool
00416 rtems_capture_watch_global_on (void);
00417 
00433 rtems_status_code
00434 rtems_capture_watch_ceiling (rtems_task_priority ceiling);
00435 
00444 rtems_task_priority
00445 rtems_capture_watch_get_ceiling (void);
00446 
00462 rtems_status_code
00463 rtems_capture_watch_floor (rtems_task_priority floor);
00464 
00473 rtems_task_priority
00474 rtems_capture_watch_get_floor (void);
00475 
00504 rtems_status_code
00505 rtems_capture_set_trigger (rtems_name                   from_name,
00506                            rtems_id                     from_id,
00507                            rtems_name                   to_name,
00508                            rtems_id                     to_id,
00509                            rtems_capture_trigger_mode_t mode,
00510                            rtems_capture_trigger_t      trigger);
00511 
00530 rtems_status_code
00531 rtems_capture_clear_trigger (rtems_name                   from_name,
00532                              rtems_id                     from_id,
00533                              rtems_name                   to_name,
00534                              rtems_id                     to_id,
00535                              rtems_capture_trigger_mode_t mode,
00536                              rtems_capture_trigger_t      trigger);
00537 
00575 rtems_status_code
00576 rtems_capture_read (uint32_t                 threshold,
00577                     uint32_t                 timeout,
00578                     uint32_t*                read,
00579                     rtems_capture_record_t** recs);
00580 
00593 rtems_status_code
00594 rtems_capture_release (uint32_t count);
00595 
00596 /*
00597  * @brief Capture nano-second time period.
00598  *
00599  * This function returns the time period in nano-seconds.
00600  *
00601  * @param[out] uptime The nano-second time period.
00602  */
00603 void
00604 rtems_capture_time (rtems_capture_time_t* uptime);
00605 
00617 const char*
00618 rtems_capture_event_text (int event);
00619 
00629 rtems_capture_task_t*
00630 rtems_capture_get_task_list (void);
00631 
00643 static inline rtems_capture_task_t*
00644 rtems_capture_next_task (rtems_capture_task_t* task)
00645 {
00646   return task->forw;
00647 }
00648 
00660 static inline bool
00661 rtems_capture_task_valid (rtems_capture_task_t* task)
00662 {
00663   return task->tcb != NULL;
00664 }
00665 
00675 static inline rtems_id
00676 rtems_capture_task_id (rtems_capture_task_t* task)
00677 {
00678   return task->id;
00679 }
00680 
00690 static inline States_Control
00691 rtems_capture_task_state (rtems_capture_task_t* task)
00692 {
00693   if (rtems_capture_task_valid (task))
00694     return task->tcb->current_state;
00695   return 0;
00696 }
00697 
00707 static inline rtems_name
00708 rtems_capture_task_name (rtems_capture_task_t* task)
00709 {
00710   return task->name;
00711 }
00712 
00722 static inline uint32_t
00723 rtems_capture_task_flags (rtems_capture_task_t* task)
00724 {
00725   return task->flags;
00726 }
00727 
00737 static inline rtems_capture_control_t*
00738 rtems_capture_task_control (rtems_capture_task_t* task)
00739 {
00740   return task->control;
00741 }
00742 
00752 static inline uint32_t
00753 rtems_capture_task_control_flags (rtems_capture_task_t* task)
00754 {
00755   if (!task->control)
00756     return 0;
00757   return task->control->flags;
00758 }
00759 
00771 static inline uint32_t
00772 rtems_capture_task_switched_in (rtems_capture_task_t* task)
00773 {
00774   return task->in;
00775 }
00776 
00788 static inline uint32_t
00789 rtems_capture_task_switched_out (rtems_capture_task_t* task)
00790 {
00791   return task->out;
00792 }
00793 
00805 static inline rtems_task_priority
00806 rtems_capture_task_start_priority (rtems_capture_task_t* task)
00807 {
00808   return task->start_priority;
00809 }
00810 
00820 static inline rtems_task_priority
00821 rtems_capture_task_real_priority (rtems_capture_task_t* task)
00822 {
00823   if (rtems_capture_task_valid (task))
00824     return task->tcb->real_priority;
00825   return 0;
00826 }
00827 
00837 static inline rtems_task_priority
00838 rtems_capture_task_curr_priority (rtems_capture_task_t* task)
00839 {
00840   if (rtems_capture_task_valid (task))
00841     return task->tcb->current_priority;
00842   return 0;
00843 }
00844 
00856 uint32_t
00857 rtems_capture_task_stack_usage (rtems_capture_task_t* task);
00858 
00868 static inline uint32_t
00869 rtems_capture_task_stack_size (rtems_capture_task_t* task)
00870 {
00871   return task->stack_size;
00872 }
00873 
00883 static inline uint32_t
00884 rtems_capture_task_stack_used (rtems_capture_task_t* task)
00885 {
00886   return task->stack_size - task->stack_clean;
00887 }
00888 
00898 static inline uint64_t
00899 rtems_capture_task_time (rtems_capture_task_t* task)
00900 {
00901   return task->time;
00902 }
00903 
00915 static inline uint64_t
00916 rtems_capture_task_delta_time (rtems_capture_task_t* task)
00917 {
00918   uint64_t t = task->time - task->last_time;
00919   task->last_time = task->time;
00920   return t;
00921 }
00922 
00932 static inline uint32_t
00933 rtems_capture_task_count (void)
00934 {
00935   rtems_capture_task_t* task = rtems_capture_get_task_list ();
00936   uint32_t              count = 0;
00937 
00938   while (task)
00939   {
00940     count++;
00941     task = rtems_capture_next_task (task);
00942   }
00943 
00944   return count;
00945 }
00946 
00956 rtems_capture_control_t*
00957 rtems_capture_get_control_list (void);
00958 
00970 static inline rtems_capture_control_t*
00971 rtems_capture_next_control (rtems_capture_control_t* control)
00972 {
00973   return control->next;
00974 }
00975 
00985 static inline rtems_id
00986 rtems_capture_control_id (rtems_capture_control_t* control)
00987 {
00988   return control->id;
00989 }
00990 
01000 static inline rtems_name
01001 rtems_capture_control_name (rtems_capture_control_t* control)
01002 {
01003   return control->name;
01004 }
01005 
01015 static inline uint32_t
01016 rtems_capture_control_flags (rtems_capture_control_t* control)
01017 {
01018   return control->flags;
01019 }
01020 
01030 static inline uint32_t
01031 rtems_capture_control_to_triggers (rtems_capture_control_t* control)
01032 {
01033   return control->to_triggers;
01034 }
01035 
01045 static inline uint32_t
01046 rtems_capture_control_from_triggers (rtems_capture_control_t* control)
01047 {
01048   return control->from_triggers;
01049 }
01050 
01060 static inline uint32_t
01061 rtems_capture_control_all_by_triggers (rtems_capture_control_t* control)
01062 {
01063   return control->by_triggers;
01064 }
01065 
01076 static inline int
01077 rtems_capture_control_by_valid (rtems_capture_control_t* control, int slot)
01078 {
01079   return control->by_valid & RTEMS_CAPTURE_CONTROL_FROM_MASK (slot);
01080 }
01081 
01092 static inline rtems_name
01093 rtems_capture_control_by_name (rtems_capture_control_t* control, int by)
01094 {
01095   if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
01096     return control->by[by].name;
01097   return control->by[0].name;
01098 }
01099 
01107 static inline rtems_id
01108 rtems_capture_control_by_id (rtems_capture_control_t* control, int by)
01109 {
01110   if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
01111     return control->by[by].id;
01112   return control->by[0].id;
01113 }
01114 
01122 static inline uint32_t
01123 rtems_capture_control_by_triggers (rtems_capture_control_t* control,
01124                                    int                      by)
01125 {
01126   if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
01127     return control->by[by].trigger;
01128   return control->by[0].trigger;
01129 }
01130 
01140 static inline uint32_t
01141 rtems_capture_control_count (void)
01142 {
01143   rtems_capture_control_t* control = rtems_capture_get_control_list ();
01144   uint32_t                 count = 0;
01145 
01146   while (control)
01147   {
01148     count++;
01149     control = rtems_capture_next_control (control);
01150   }
01151 
01152   return count;
01153 }
01154 
01155 #ifdef __cplusplus
01156 }
01157 #endif
01158 
01159 #endif