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 
00036 #ifdef __cplusplus
00037 extern "C" {
00038 #endif
00039 
00040 #include <rtems.h>
00041 
00045 #define RTEMS_CAPTURE_TRIGGER_TASKS (32)
00046 
00054 typedef uint64_t rtems_capture_time_t;
00055 
00067 typedef struct rtems_capture_from_s
00068 {
00069   rtems_name name;
00070   rtems_id   id;
00071   uint32_t   trigger;
00072 } rtems_capture_from_t;
00073 
00087 typedef struct rtems_capture_control_s
00088 {
00089   rtems_name                      name;
00090   rtems_id                        id;
00091   uint32_t                        flags;
00092   uint32_t                        to_triggers;
00093   uint32_t                        from_triggers;
00094   uint32_t                        by_triggers;
00095   uint32_t                        by_valid;
00096   rtems_capture_from_t            by[RTEMS_CAPTURE_TRIGGER_TASKS];
00097   struct rtems_capture_control_s* next;
00098 } rtems_capture_control_t;
00099 
00103 #define RTEMS_CAPTURE_CONTROL_FROM_MASK(_s) \
00104  (UINT32_C(1) << (RTEMS_CAPTURE_TRIGGER_TASKS - ((_s) + 1)))
00105 
00109 #define RTEMS_CAPTURE_WATCH         (1U << 0)
00110 
00114 #define RTEMS_CAPTURE_SWITCH        (1 << 0)
00115 #define RTEMS_CAPTURE_CREATE        (1 << 1)
00116 #define RTEMS_CAPTURE_START         (1 << 2)
00117 #define RTEMS_CAPTURE_RESTART       (1 << 3)
00118 #define RTEMS_CAPTURE_DELETE        (1 << 4)
00119 #define RTEMS_CAPTURE_BEGIN         (1 << 5)
00120 #define RTEMS_CAPTURE_EXITTED       (1 << 6)
00121 
00122 #define RTEMS_CAPTURE_FROM_TRIGS    (RTEMS_CAPTURE_SWITCH  | \
00123                                      RTEMS_CAPTURE_CREATE | \
00124                                      RTEMS_CAPTURE_START | \
00125                                      RTEMS_CAPTURE_RESTART | \
00126                                      RTEMS_CAPTURE_DELETE)
00127 
00128 #define RTEMS_CAPTURE_TO_TRIGS      (RTEMS_CAPTURE_SWITCH | \
00129                                      RTEMS_CAPTURE_CREATE | \
00130                                      RTEMS_CAPTURE_START | \
00131                                      RTEMS_CAPTURE_RESTART | \
00132                                      RTEMS_CAPTURE_DELETE | \
00133                                      RTEMS_CAPTURE_BEGIN | \
00134                                      RTEMS_CAPTURE_EXITTED)
00135 
00156 typedef struct rtems_capture_task_s
00157 {
00158   rtems_name                   name;
00159   rtems_id                     id;
00160   uint32_t                     flags;
00161   uint32_t                     refcount;
00162   rtems_tcb*                   tcb;
00163   uint32_t                     in;
00164   uint32_t                     out;
00165   rtems_task_priority          start_priority;
00166   uint32_t                     stack_size;
00167   uint32_t                     stack_clean;
00168   rtems_capture_time_t         time;
00169   rtems_capture_time_t         time_in;
00170   rtems_capture_time_t         last_time;
00171   rtems_capture_control_t*     control;
00172   struct rtems_capture_task_s* forw;
00173   struct rtems_capture_task_s* back;
00174 } rtems_capture_task_t;
00175 
00179 #define RTEMS_CAPTURE_TRACED  (1U << 0)
00180 
00181 /*
00182  * rtems_capture_record_t
00183  *
00184  *  DESCRIPTION:
00185  *
00186  * RTEMS capture record. This is a record that is written into
00187  * the buffer. The events includes the priority of the task
00188  * at the time of the context switch.
00189  */
00190 typedef struct rtems_capture_record_s
00191 {
00192   rtems_capture_task_t* task;
00193   uint32_t              events;
00194   rtems_capture_time_t  time;
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_BEGIN_EVENT         UINT32_C (0x01000000)
00214 #define RTEMS_CAPTURE_EXITTED_EVENT       UINT32_C (0x02000000)
00215 #define RTEMS_CAPTURE_SWITCHED_OUT_EVENT  UINT32_C (0x04000000)
00216 #define RTEMS_CAPTURE_SWITCHED_IN_EVENT   UINT32_C (0x08000000)
00217 #define RTEMS_CAPTURE_TIMESTAMP           UINT32_C (0x10000000)
00218 #define RTEMS_CAPTURE_EVENT_END           (28)
00219 
00227 typedef enum rtems_capture_trigger_mode_e
00228 {
00229   rtems_capture_to_any,
00230   rtems_capture_from_any,
00231   rtems_capture_from_to
00232 } rtems_capture_trigger_mode_t;
00233 
00241 typedef enum rtems_capture_trigger_e
00242 {
00243   rtems_capture_switch,
00244   rtems_capture_create,
00245   rtems_capture_start,
00246   rtems_capture_restart,
00247   rtems_capture_delete,
00248   rtems_capture_begin,
00249   rtems_capture_exitted
00250 } rtems_capture_trigger_t;
00251 
00262 typedef void (*rtems_capture_timestamp)(rtems_capture_time_t* time);
00263 
00274 rtems_status_code
00275 rtems_capture_open (uint32_t                size,
00276                     rtems_capture_timestamp timestamp);
00277 
00286 rtems_status_code
00287 rtems_capture_close (void);
00288 
00296 rtems_status_code
00297 rtems_capture_control (bool enable);
00298 
00308 rtems_status_code
00309 rtems_capture_monitor (bool enable);
00310 
00311 /*
00312  * rtems_capture_flush
00313  *
00314  *  DESCRIPTION:
00315  *
00316  * This function flushes the trace buffer. The prime parameter allows the
00317  * capture engine to also be primed again.
00318  */
00319 rtems_status_code
00320 rtems_capture_flush (bool prime);
00321 
00332 rtems_status_code
00333 rtems_capture_watch_add (rtems_name name, rtems_id id);
00334 
00344 rtems_status_code
00345 rtems_capture_watch_del (rtems_name name, rtems_id id);
00346 
00355 rtems_status_code
00356 rtems_capture_watch_ctrl (rtems_name    name,
00357                           rtems_id      id,
00358                           bool enable);
00359 
00369 rtems_status_code
00370 rtems_capture_watch_global (bool enable);
00371 
00379 bool
00380 rtems_capture_watch_global_on (void);
00381 
00392 rtems_status_code
00393 rtems_capture_watch_ceiling (rtems_task_priority ceiling);
00394 
00402 rtems_task_priority
00403 rtems_capture_watch_get_ceiling (void);
00404 
00415 rtems_status_code
00416 rtems_capture_watch_floor (rtems_task_priority floor);
00417 
00425 rtems_task_priority
00426 rtems_capture_watch_get_floor (void);
00427 
00443 rtems_status_code
00444 rtems_capture_set_trigger (rtems_name                   from_name,
00445                            rtems_id                     from_id,
00446                            rtems_name                   to_name,
00447                            rtems_id                     to_id,
00448                            rtems_capture_trigger_mode_t mode,
00449                            rtems_capture_trigger_t      trigger);
00450 
00460 rtems_status_code
00461 rtems_capture_clear_trigger (rtems_name                   from_name,
00462                              rtems_id                     from_id,
00463                              rtems_name                   to_name,
00464                              rtems_id                     to_id,
00465                              rtems_capture_trigger_mode_t mode,
00466                              rtems_capture_trigger_t      trigger);
00467 
00499 rtems_status_code
00500 rtems_capture_read (uint32_t                 threshold,
00501                     uint32_t                 timeout,
00502                     uint32_t*                read,
00503                     rtems_capture_record_t** recs);
00504 
00513 rtems_status_code
00514 rtems_capture_release (uint32_t count);
00515 
00516 /*
00517  * rtems_capture_time
00518  *
00519  *  DESCRIPTION:
00520  *
00521  * This function returns the time period in nano-seconds.
00522  */
00523 void
00524 rtems_capture_time (rtems_capture_time_t* uptime);
00525 
00535 const char*
00536 rtems_capture_event_text (int event);
00537 
00546 rtems_capture_task_t*
00547 rtems_capture_get_task_list (void);
00548 
00557 static inline rtems_capture_task_t*
00558 rtems_capture_next_task (rtems_capture_task_t* task)
00559 {
00560   return task->forw;
00561 }
00562 
00571 static inline bool
00572 rtems_capture_task_valid (rtems_capture_task_t* task)
00573 {
00574   return task->tcb != NULL;
00575 }
00576 
00584 static inline rtems_id
00585 rtems_capture_task_id (rtems_capture_task_t* task)
00586 {
00587   return task->id;
00588 }
00589 
00597 static inline States_Control
00598 rtems_capture_task_state (rtems_capture_task_t* task)
00599 {
00600   if (rtems_capture_task_valid (task))
00601     return task->tcb->current_state;
00602   return 0;
00603 }
00604 
00612 static inline rtems_name
00613 rtems_capture_task_name (rtems_capture_task_t* task)
00614 {
00615   return task->name;
00616 }
00617 
00625 static inline uint32_t
00626 rtems_capture_task_flags (rtems_capture_task_t* task)
00627 {
00628   return task->flags;
00629 }
00630 
00638 static inline rtems_capture_control_t*
00639 rtems_capture_task_control (rtems_capture_task_t* task)
00640 {
00641   return task->control;
00642 }
00643 
00651 static inline uint32_t
00652 rtems_capture_task_control_flags (rtems_capture_task_t* task)
00653 {
00654   if (!task->control)
00655     return 0;
00656   return task->control->flags;
00657 }
00658 
00667 static inline uint32_t
00668 rtems_capture_task_switched_in (rtems_capture_task_t* task)
00669 {
00670   return task->in;
00671 }
00672 
00681 static inline uint32_t
00682 rtems_capture_task_switched_out (rtems_capture_task_t* task)
00683 {
00684   return task->out;
00685 }
00686 
00695 static inline rtems_task_priority
00696 rtems_capture_task_start_priority (rtems_capture_task_t* task)
00697 {
00698   return task->start_priority;
00699 }
00700 
00708 static inline rtems_task_priority
00709 rtems_capture_task_real_priority (rtems_capture_task_t* task)
00710 {
00711   if (rtems_capture_task_valid (task))
00712     return task->tcb->real_priority;
00713   return 0;
00714 }
00715 
00723 static inline rtems_task_priority
00724 rtems_capture_task_curr_priority (rtems_capture_task_t* task)
00725 {
00726   if (rtems_capture_task_valid (task))
00727     return task->tcb->current_priority;
00728   return 0;
00729 }
00730 
00739 uint32_t
00740 rtems_capture_task_stack_usage (rtems_capture_task_t* task);
00741 
00749 static inline uint32_t
00750 rtems_capture_task_stack_size (rtems_capture_task_t* task)
00751 {
00752   return task->stack_size;
00753 }
00754 
00762 static inline uint32_t
00763 rtems_capture_task_stack_used (rtems_capture_task_t* task)
00764 {
00765   return task->stack_size - task->stack_clean;
00766 }
00767 
00775 static inline uint64_t
00776 rtems_capture_task_time (rtems_capture_task_t* task)
00777 {
00778   return task->time;
00779 }
00780 
00789 static inline uint64_t
00790 rtems_capture_task_delta_time (rtems_capture_task_t* task)
00791 {
00792   uint64_t t = task->time - task->last_time;
00793   task->last_time = task->time;
00794   return t;
00795 }
00796 
00805 static inline uint32_t
00806 rtems_capture_task_count (void)
00807 {
00808   rtems_capture_task_t* task = rtems_capture_get_task_list ();
00809   uint32_t              count = 0;
00810 
00811   while (task)
00812   {
00813     count++;
00814     task = rtems_capture_next_task (task);
00815   }
00816 
00817   return count;
00818 }
00819 
00828 rtems_capture_control_t*
00829 rtems_capture_get_control_list (void);
00830 
00839 static inline rtems_capture_control_t*
00840 rtems_capture_next_control (rtems_capture_control_t* control)
00841 {
00842   return control->next;
00843 }
00844 
00852 static inline rtems_id
00853 rtems_capture_control_id (rtems_capture_control_t* control)
00854 {
00855   return control->id;
00856 }
00857 
00865 static inline rtems_name
00866 rtems_capture_control_name (rtems_capture_control_t* control)
00867 {
00868   return control->name;
00869 }
00870 
00878 static inline uint32_t
00879 rtems_capture_control_flags (rtems_capture_control_t* control)
00880 {
00881   return control->flags;
00882 }
00883 
00891 static inline uint32_t
00892 rtems_capture_control_to_triggers (rtems_capture_control_t* control)
00893 {
00894   return control->to_triggers;
00895 }
00896 
00904 static inline uint32_t
00905 rtems_capture_control_from_triggers (rtems_capture_control_t* control)
00906 {
00907   return control->from_triggers;
00908 }
00909 
00917 static inline uint32_t
00918 rtems_capture_control_all_by_triggers (rtems_capture_control_t* control)
00919 {
00920   return control->by_triggers;
00921 }
00922 
00930 static inline int
00931 rtems_capture_control_by_valid (rtems_capture_control_t* control, int slot)
00932 {
00933   return control->by_valid & RTEMS_CAPTURE_CONTROL_FROM_MASK (slot);
00934 }
00935 
00943 static inline rtems_name
00944 rtems_capture_control_by_name (rtems_capture_control_t* control, int by)
00945 {
00946   if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
00947     return control->by[by].name;
00948   return control->by[0].name;
00949 }
00950 
00958 static inline rtems_id
00959 rtems_capture_control_by_id (rtems_capture_control_t* control, int by)
00960 {
00961   if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
00962     return control->by[by].id;
00963   return control->by[0].id;
00964 }
00965 
00973 static inline uint32_t
00974 rtems_capture_control_by_triggers (rtems_capture_control_t* control,
00975                                    int                      by)
00976 {
00977   if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
00978     return control->by[by].trigger;
00979   return control->by[0].trigger;
00980 }
00981 
00990 static inline uint32_t
00991 rtems_capture_control_count (void)
00992 {
00993   rtems_capture_control_t* control = rtems_capture_get_control_list ();
00994   uint32_t                 count = 0;
00995 
00996   while (control)
00997   {
00998     count++;
00999     control = rtems_capture_next_control (control);
01000   }
01001 
01002   return count;
01003 }
01004 
01005 #ifdef __cplusplus
01006 }
01007 #endif
01008 
01009 #endif