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 #include <rtems/rtems/tasksimpl.h>
00050 
00054 #define RTEMS_CAPTURE_TRIGGER_TASKS (32)
00055 
00061 typedef uint64_t rtems_capture_time_t;
00062 
00072 typedef struct rtems_capture_from_s
00073 {
00074   rtems_name name;
00075   rtems_id   id;
00076   uint32_t   trigger;
00077 } rtems_capture_from_t;
00078 
00090 typedef struct rtems_capture_control_s
00091 {
00092   rtems_name                      name;
00093   rtems_id                        id;
00094   uint32_t                        flags;
00095   uint32_t                        to_triggers;
00096   uint32_t                        from_triggers;
00097   uint32_t                        by_triggers;
00098   uint32_t                        by_valid;
00099   rtems_capture_from_t            by[RTEMS_CAPTURE_TRIGGER_TASKS];
00100   struct rtems_capture_control_s* next;
00101 } rtems_capture_control_t;
00102 
00106 #define RTEMS_CAPTURE_CONTROL_FROM_MASK(_s) \
00107  (UINT32_C(1) << (RTEMS_CAPTURE_TRIGGER_TASKS - ((_s) + 1)))
00108 
00112 #define RTEMS_CAPTURE_WATCH         (1U << 0)
00113 
00117 #define RTEMS_CAPTURE_SWITCH        (1 << 0)
00118 #define RTEMS_CAPTURE_CREATE        (1 << 1)
00119 #define RTEMS_CAPTURE_START         (1 << 2)
00120 #define RTEMS_CAPTURE_RESTART       (1 << 3)
00121 #define RTEMS_CAPTURE_DELETE        (1 << 4)
00122 #define RTEMS_CAPTURE_BEGIN         (1 << 5)
00123 #define RTEMS_CAPTURE_EXITTED       (1 << 6)
00124 #define RTEMS_CAPTURE_TERMINATED    (1 << 7)
00125 
00126 #define RTEMS_CAPTURE_FROM_TRIGS    (RTEMS_CAPTURE_SWITCH  | \
00127                                      RTEMS_CAPTURE_CREATE | \
00128                                      RTEMS_CAPTURE_START | \
00129                                      RTEMS_CAPTURE_RESTART | \
00130                                      RTEMS_CAPTURE_DELETE)
00131 
00132 #define RTEMS_CAPTURE_TO_TRIGS      (RTEMS_CAPTURE_SWITCH | \
00133                                      RTEMS_CAPTURE_CREATE | \
00134                                      RTEMS_CAPTURE_START | \
00135                                      RTEMS_CAPTURE_RESTART | \
00136                                      RTEMS_CAPTURE_DELETE | \
00137                                      RTEMS_CAPTURE_BEGIN | \
00138                                      RTEMS_CAPTURE_EXITTED)
00139 
00143 #define RTEMS_CAPTURE_TRACED      (1U << 0)
00144 #define RTEMS_CAPTURE_RECORD_TASK (1U << 1)
00145 
00146 /*
00147  * @brief Capture record.
00148  *
00149  * This is a record that is written into
00150  * the buffer. The events includes the priority of the task
00151  * at the time of the context switch.
00152  */
00153 typedef struct rtems_capture_record_s
00154 {
00155   uint32_t              events;
00156   rtems_capture_time_t  time;
00157   size_t                size;
00158   rtems_id              task_id;
00159 } rtems_capture_record_t;
00160 
00161 /*
00162  * @brief Capture task record.
00163  *
00164  * This is a record that is written into
00165  * the buffer. The events includes the priority of the task
00166  * at the time of the context switch.
00167  */
00168 typedef struct rtems_capture_task_record_s
00169 {
00170   rtems_capture_record_t rec;
00171   rtems_name             name;
00172   rtems_task_priority    start_priority;
00173   uint32_t               stack_size;
00174 } rtems_capture_task_record_t;
00175 
00179 #define RTEMS_CAPTURE_REAL_PRI_EVENT_MASK UINT32_C (0x000000ff)
00180 #define RTEMS_CAPTURE_CURR_PRI_EVENT_MASK UINT32_C (0x0000ff00)
00181 #define RTEMS_CAPTURE_REAL_PRIORITY_EVENT (0)
00182 #define RTEMS_CAPTURE_CURR_PRIORITY_EVENT (8)
00183 #define RTEMS_CAPTURE_EVENT_START         (16)
00184 #define RTEMS_CAPTURE_CREATED_BY_EVENT    UINT32_C (0x00010000)
00185 #define RTEMS_CAPTURE_CREATED_EVENT       UINT32_C (0x00020000)
00186 #define RTEMS_CAPTURE_STARTED_BY_EVENT    UINT32_C (0x00040000)
00187 #define RTEMS_CAPTURE_STARTED_EVENT       UINT32_C (0x00080000)
00188 #define RTEMS_CAPTURE_RESTARTED_BY_EVENT  UINT32_C (0x00100000)
00189 #define RTEMS_CAPTURE_RESTARTED_EVENT     UINT32_C (0x00200000)
00190 #define RTEMS_CAPTURE_DELETED_BY_EVENT    UINT32_C (0x00400000)
00191 #define RTEMS_CAPTURE_DELETED_EVENT       UINT32_C (0x00800000)
00192 #define RTEMS_CAPTURE_TERMINATED_EVENT    UINT32_C (0x01000000)
00193 #define RTEMS_CAPTURE_BEGIN_EVENT         UINT32_C (0x02000000)
00194 #define RTEMS_CAPTURE_EXITTED_EVENT       UINT32_C (0x04000000)
00195 #define RTEMS_CAPTURE_SWITCHED_OUT_EVENT  UINT32_C (0x08000000)
00196 #define RTEMS_CAPTURE_SWITCHED_IN_EVENT   UINT32_C (0x10000000)
00197 #define RTEMS_CAPTURE_TIMESTAMP           UINT32_C (0x20000000)
00198 #define RTEMS_CAPTURE_EVENT_END           (29)
00199 
00205 typedef enum rtems_capture_trigger_mode_e
00206 {
00207   rtems_capture_to_any,
00208   rtems_capture_from_any,
00209   rtems_capture_from_to
00210 } rtems_capture_trigger_mode_t;
00211 
00217 typedef enum rtems_capture_trigger_e
00218 {
00219   rtems_capture_switch,
00220   rtems_capture_create,
00221   rtems_capture_start,
00222   rtems_capture_restart,
00223   rtems_capture_delete,
00224   rtems_capture_begin,
00225   rtems_capture_exitted,
00226   rtems_capture_terminated
00227 } rtems_capture_trigger_t;
00228 
00237 typedef void (*rtems_capture_timestamp)(rtems_capture_time_t* time);
00238 
00255 rtems_status_code
00256 rtems_capture_open (uint32_t                size,
00257                     rtems_capture_timestamp timestamp);
00258 
00269 rtems_status_code
00270 rtems_capture_close (void);
00271 
00283 rtems_status_code
00284 rtems_capture_control (bool enable);
00285 
00299 rtems_status_code
00300 rtems_capture_monitor (bool enable);
00301 
00302 /*
00303  * @brief Capture flush trace buffer.
00304  *
00305  * This function flushes the trace buffer. The prime parameter allows the
00306  * capture engine to also be primed again.
00307  *
00308  * @param[in]  prime The prime after flush flag.
00309  *
00310  * @retval This method returns RTEMS_SUCCESSFUL if there was not an
00311  *         error. Otherwise, a status code is returned indicating the
00312  *         source of the error.
00313  */
00314 rtems_status_code
00315 rtems_capture_flush (bool prime);
00316 
00332 rtems_status_code
00333 rtems_capture_watch_add (rtems_name name, rtems_id id);
00334 
00349 rtems_status_code
00350 rtems_capture_watch_del (rtems_name name, rtems_id id);
00351 
00366 rtems_status_code
00367 rtems_capture_watch_ctrl (rtems_name    name,
00368                           rtems_id      id,
00369                           bool enable);
00370 
00384 rtems_status_code
00385 rtems_capture_watch_global (bool enable);
00386 
00395 bool
00396 rtems_capture_watch_global_on (void);
00397 
00413 rtems_status_code
00414 rtems_capture_watch_ceiling (rtems_task_priority ceiling);
00415 
00424 rtems_task_priority
00425 rtems_capture_watch_get_ceiling (void);
00426 
00442 rtems_status_code
00443 rtems_capture_watch_floor (rtems_task_priority floor);
00444 
00453 rtems_task_priority
00454 rtems_capture_watch_get_floor (void);
00455 
00484 rtems_status_code
00485 rtems_capture_set_trigger (rtems_name                   from_name,
00486                            rtems_id                     from_id,
00487                            rtems_name                   to_name,
00488                            rtems_id                     to_id,
00489                            rtems_capture_trigger_mode_t mode,
00490                            rtems_capture_trigger_t      trigger);
00491 
00510 rtems_status_code
00511 rtems_capture_clear_trigger (rtems_name                   from_name,
00512                              rtems_id                     from_id,
00513                              rtems_name                   to_name,
00514                              rtems_id                     to_id,
00515                              rtems_capture_trigger_mode_t mode,
00516                              rtems_capture_trigger_t      trigger);
00517 
00555 rtems_status_code
00556 rtems_capture_read (uint32_t                 threshold,
00557                     uint32_t                 timeout,
00558                     uint32_t*                read,
00559                     rtems_capture_record_t** recs);
00560 
00573 rtems_status_code
00574 rtems_capture_release (uint32_t count);
00575 
00576 /*
00577  * @brief Capture nano-second time period.
00578  *
00579  * This function returns the time period in nano-seconds.
00580  *
00581  * @param[out] uptime The nano-second time period.
00582  */
00583 void
00584 rtems_capture_time (rtems_capture_time_t* uptime);
00585 
00597 const char*
00598 rtems_capture_event_text (int event);
00599 
00607 void rtems_capture_record_task( rtems_tcb* tcb );
00608 
00617 static inline bool rtems_capture_task_recorded( rtems_tcb* tcb ) {
00618   return ( (tcb->Capture.flags & RTEMS_CAPTURE_RECORD_TASK) != 0 );
00619 }
00620 
00630 static inline rtems_id
00631 rtems_capture_task_id (rtems_tcb* tcb)
00632 {
00633   return tcb->Object.id;
00634 }
00635 
00645 static inline States_Control
00646 rtems_capture_task_state (rtems_tcb* tcb)
00647 {
00648   if (tcb)
00649     return tcb->current_state;
00650   return 0;
00651 }
00652 
00662 static inline rtems_name
00663 rtems_capture_task_name (rtems_tcb* tcb)
00664 {
00665   rtems_name  name;
00666   rtems_object_get_classic_name( tcb->Object.id, &name );
00667   return name;
00668 }
00669 
00679 static inline uint32_t
00680 rtems_capture_task_flags (rtems_tcb* tcb)
00681 {
00682   return tcb->Capture.flags;
00683 }
00684 
00694 static inline rtems_capture_control_t*
00695 rtems_capture_task_control (rtems_tcb* tcb)
00696 {
00697   return tcb->Capture.control;
00698 }
00699 
00709 static inline uint32_t
00710 rtems_capture_task_control_flags (rtems_tcb* tcb)
00711 {
00712   rtems_capture_control_t*  control = tcb->Capture.control;
00713   if (!control)
00714     return 0;
00715   return control->flags;
00716 }
00717 
00729 static inline rtems_task_priority
00730 rtems_capture_task_start_priority (rtems_tcb* tcb)
00731 {
00732   return _RTEMS_tasks_Priority_from_Core(
00733     tcb->Start.initial_priority
00734   );
00735 }
00736 
00746 static inline rtems_task_priority
00747 rtems_capture_task_real_priority (rtems_tcb* tcb)
00748 {
00749   return tcb->real_priority;
00750 }
00751 
00761 static inline rtems_task_priority
00762 rtems_capture_task_curr_priority (rtems_tcb* tcb)
00763 {
00764   return tcb->current_priority;
00765 }
00766 
00776 rtems_capture_control_t*
00777 rtems_capture_get_control_list (void);
00778 
00790 static inline rtems_capture_control_t*
00791 rtems_capture_next_control (rtems_capture_control_t* control)
00792 {
00793   return control->next;
00794 }
00795 
00805 static inline rtems_id
00806 rtems_capture_control_id (rtems_capture_control_t* control)
00807 {
00808   return control->id;
00809 }
00810 
00820 static inline rtems_name
00821 rtems_capture_control_name (rtems_capture_control_t* control)
00822 {
00823   return control->name;
00824 }
00825 
00835 static inline uint32_t
00836 rtems_capture_control_flags (rtems_capture_control_t* control)
00837 {
00838   return control->flags;
00839 }
00840 
00850 static inline uint32_t
00851 rtems_capture_control_to_triggers (rtems_capture_control_t* control)
00852 {
00853   return control->to_triggers;
00854 }
00855 
00865 static inline uint32_t
00866 rtems_capture_control_from_triggers (rtems_capture_control_t* control)
00867 {
00868   return control->from_triggers;
00869 }
00870 
00880 static inline uint32_t
00881 rtems_capture_control_all_by_triggers (rtems_capture_control_t* control)
00882 {
00883   return control->by_triggers;
00884 }
00885 
00896 static inline int
00897 rtems_capture_control_by_valid (rtems_capture_control_t* control, int slot)
00898 {
00899   return control->by_valid & RTEMS_CAPTURE_CONTROL_FROM_MASK (slot);
00900 }
00901 
00912 static inline rtems_name
00913 rtems_capture_control_by_name (rtems_capture_control_t* control, int by)
00914 {
00915   if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
00916     return control->by[by].name;
00917   return control->by[0].name;
00918 }
00919 
00927 static inline rtems_id
00928 rtems_capture_control_by_id (rtems_capture_control_t* control, int by)
00929 {
00930   if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
00931     return control->by[by].id;
00932   return control->by[0].id;
00933 }
00934 
00942 static inline uint32_t
00943 rtems_capture_control_by_triggers (rtems_capture_control_t* control,
00944                                    int                      by)
00945 {
00946   if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
00947     return control->by[by].trigger;
00948   return control->by[0].trigger;
00949 }
00950 
00960 static inline uint32_t
00961 rtems_capture_control_count (void)
00962 {
00963   rtems_capture_control_t* control = rtems_capture_get_control_list ();
00964   uint32_t                 count = 0;
00965 
00966   while (control)
00967   {
00968     count++;
00969     control = rtems_capture_next_control (control);
00970   }
00971 
00972   return count;
00973 }
00974 
00975 #ifdef __cplusplus
00976 }
00977 #endif
00978 
00979 #endif