RTEMS CPU Kit with SuperCore  4.10.99.0
capture.h
Go to the documentation of this file.
1 
11 /*
12  ------------------------------------------------------------------------
13 
14  Copyright Objective Design Systems Pty Ltd, 2002
15  All rights reserved Objective Design Systems Pty Ltd, 2002
16  Chris Johns (ccj@acm.org)
17 
18  COPYRIGHT (c) 1989-2014
19  On-Line Applications Research Corporation (OAR).
20 
21  The license and distribution terms for this file may be
22  found in the file LICENSE in this distribution.
23 
24  This software with is provided ``as is'' and with NO WARRANTY.
25 
26  ------------------------------------------------------------------------
27 
28  RTEMS Performance Monitoring and Measurement Framework.
29  This is the Capture Engine component.
30 
31 */
32 
33 #ifndef __CAPTURE_H_
34 #define __CAPTURE_H_
35 
44 #ifdef __cplusplus
45 extern "C" {
46 #endif
47 
48 #include <rtems.h>
49 #include <rtems/rtems/tasksimpl.h>
50 
54 #define RTEMS_CAPTURE_TRIGGER_TASKS (32)
55 
61 typedef uint64_t rtems_capture_time_t;
62 
72 typedef struct rtems_capture_from_s
73 {
74  rtems_name name;
75  rtems_id id;
76  uint32_t trigger;
78 
91 {
92  rtems_name name;
93  rtems_id id;
94  uint32_t flags;
95  uint32_t to_triggers;
96  uint32_t from_triggers;
97  uint32_t by_triggers;
98  uint32_t by_valid;
100  struct rtems_capture_control_s* next;
102 
106 #define RTEMS_CAPTURE_CONTROL_FROM_MASK(_s) \
107  (UINT32_C(1) << (RTEMS_CAPTURE_TRIGGER_TASKS - ((_s) + 1)))
108 
112 #define RTEMS_CAPTURE_WATCH (1U << 0)
113 
117 #define RTEMS_CAPTURE_SWITCH (1 << 0)
118 #define RTEMS_CAPTURE_CREATE (1 << 1)
119 #define RTEMS_CAPTURE_START (1 << 2)
120 #define RTEMS_CAPTURE_RESTART (1 << 3)
121 #define RTEMS_CAPTURE_DELETE (1 << 4)
122 #define RTEMS_CAPTURE_BEGIN (1 << 5)
123 #define RTEMS_CAPTURE_EXITTED (1 << 6)
124 #define RTEMS_CAPTURE_TERMINATED (1 << 7)
125 
126 #define RTEMS_CAPTURE_FROM_TRIGS (RTEMS_CAPTURE_SWITCH | \
127  RTEMS_CAPTURE_CREATE | \
128  RTEMS_CAPTURE_START | \
129  RTEMS_CAPTURE_RESTART | \
130  RTEMS_CAPTURE_DELETE)
131 
132 #define RTEMS_CAPTURE_TO_TRIGS (RTEMS_CAPTURE_SWITCH | \
133  RTEMS_CAPTURE_CREATE | \
134  RTEMS_CAPTURE_START | \
135  RTEMS_CAPTURE_RESTART | \
136  RTEMS_CAPTURE_DELETE | \
137  RTEMS_CAPTURE_BEGIN | \
138  RTEMS_CAPTURE_EXITTED)
139 
143 #define RTEMS_CAPTURE_TRACED (1U << 0)
144 #define RTEMS_CAPTURE_INIT_TASK (1U << 1)
145 #define RTEMS_CAPTURE_RECORD_TASK (1U << 2)
146 
147 /*
148  * @brief Capture record.
149  *
150  * This is a record that is written into
151  * the buffer. The events includes the priority of the task
152  * at the time of the context switch.
153  */
155 {
156  uint32_t events;
157  rtems_capture_time_t time;
158  size_t size;
159  rtems_id task_id;
161 
162 /*
163  * @brief Capture task record.
164  *
165  * This is a record that is written into
166  * the buffer. The events includes the priority of the task
167  * at the time of the context switch.
168  */
170 {
172  rtems_name name;
173  rtems_task_priority start_priority;
174  uint32_t stack_size;
176 
180 #define RTEMS_CAPTURE_REAL_PRI_EVENT_MASK UINT32_C (0x000000ff)
181 #define RTEMS_CAPTURE_CURR_PRI_EVENT_MASK UINT32_C (0x0000ff00)
182 #define RTEMS_CAPTURE_REAL_PRIORITY_EVENT (0)
183 #define RTEMS_CAPTURE_CURR_PRIORITY_EVENT (8)
184 #define RTEMS_CAPTURE_EVENT_START (16)
185 #define RTEMS_CAPTURE_CREATED_BY_EVENT UINT32_C (0x00010000)
186 #define RTEMS_CAPTURE_CREATED_EVENT UINT32_C (0x00020000)
187 #define RTEMS_CAPTURE_STARTED_BY_EVENT UINT32_C (0x00040000)
188 #define RTEMS_CAPTURE_STARTED_EVENT UINT32_C (0x00080000)
189 #define RTEMS_CAPTURE_RESTARTED_BY_EVENT UINT32_C (0x00100000)
190 #define RTEMS_CAPTURE_RESTARTED_EVENT UINT32_C (0x00200000)
191 #define RTEMS_CAPTURE_DELETED_BY_EVENT UINT32_C (0x00400000)
192 #define RTEMS_CAPTURE_DELETED_EVENT UINT32_C (0x00800000)
193 #define RTEMS_CAPTURE_TERMINATED_EVENT UINT32_C (0x01000000)
194 #define RTEMS_CAPTURE_BEGIN_EVENT UINT32_C (0x02000000)
195 #define RTEMS_CAPTURE_EXITTED_EVENT UINT32_C (0x04000000)
196 #define RTEMS_CAPTURE_SWITCHED_OUT_EVENT UINT32_C (0x08000000)
197 #define RTEMS_CAPTURE_SWITCHED_IN_EVENT UINT32_C (0x10000000)
198 #define RTEMS_CAPTURE_TIMESTAMP UINT32_C (0x20000000)
199 #define RTEMS_CAPTURE_EVENT_END (29)
200 
207 {
208  rtems_capture_to_any,
209  rtems_capture_from_any,
210  rtems_capture_from_to
212 
219 {
220  rtems_capture_switch,
221  rtems_capture_create,
222  rtems_capture_start,
223  rtems_capture_restart,
224  rtems_capture_delete,
225  rtems_capture_begin,
226  rtems_capture_exitted,
227  rtems_capture_terminated
229 
238 typedef void (*rtems_capture_timestamp)(rtems_capture_time_t* time);
239 
257 rtems_capture_open (uint32_t size,
258  rtems_capture_timestamp timestamp);
259 
271 rtems_capture_close (void);
272 
285 rtems_capture_control (bool enable);
286 
301 rtems_capture_monitor (bool enable);
302 
303 /*
304  * @brief Capture flush trace buffer.
305  *
306  * This function flushes the trace buffer. The prime parameter allows the
307  * capture engine to also be primed again.
308  *
309  * @param[in] prime The prime after flush flag.
310  *
311  * @retval This method returns RTEMS_SUCCESSFUL if there was not an
312  * error. Otherwise, a status code is returned indicating the
313  * source of the error.
314  */
316 rtems_capture_flush (bool prime);
317 
335 
352 
369  rtems_id id,
370  bool enable);
371 
386 rtems_capture_watch_global (bool enable);
387 
396 bool
398 
416 
427 
445 
456 
487  rtems_id from_id,
488  rtems_name to_name,
489  rtems_id to_id,
491  rtems_capture_trigger_t trigger);
492 
513  rtems_id from_id,
514  rtems_name to_name,
515  rtems_id to_id,
517  rtems_capture_trigger_t trigger);
518 
544 rtems_capture_read (uint32_t cpu,
545  uint32_t* read,
546  rtems_capture_record_t** recs);
547 
561 rtems_capture_release (uint32_t cpu, uint32_t count);
562 
563 /*
564  * @brief Capture nano-second time period.
565  *
566  * This function returns the time period in nano-seconds.
567  *
568  * @param[out] uptime The nano-second time period.
569  */
570 void
571 rtems_capture_time (rtems_capture_time_t* uptime);
572 
584 const char*
585 rtems_capture_event_text (int event);
586 
595 
604 
613 static inline bool rtems_capture_task_recorded( rtems_tcb* tcb ) {
614  return ( (tcb->Capture.flags & RTEMS_CAPTURE_RECORD_TASK) != 0 );
615 }
616 
625 static inline bool rtems_capture_task_initialized( rtems_tcb* tcb ) {
626  return ( (tcb->Capture.flags & RTEMS_CAPTURE_INIT_TASK) != 0 );
627 }
628 
638 static inline rtems_id
639 rtems_capture_task_id (rtems_tcb* tcb)
640 {
641  return tcb->Object.id;
642 }
643 
653 static inline States_Control
654 rtems_capture_task_state (rtems_tcb* tcb)
655 {
656  if (tcb)
657  return tcb->current_state;
658  return 0;
659 }
660 
670 static inline rtems_name
671 rtems_capture_task_name (rtems_tcb* tcb)
672 {
673  rtems_name name;
674  rtems_object_get_classic_name( tcb->Object.id, &name );
675  return name;
676 }
677 
687 static inline uint32_t
688 rtems_capture_task_flags (rtems_tcb* tcb)
689 {
690  return tcb->Capture.flags;
691 }
692 
702 static inline rtems_capture_control_t*
703 rtems_capture_task_control (rtems_tcb* tcb)
704 {
705  return tcb->Capture.control;
706 }
707 
717 static inline uint32_t
718 rtems_capture_task_control_flags (rtems_tcb* tcb)
719 {
720  rtems_capture_control_t* control = tcb->Capture.control;
721  if (!control)
722  return 0;
723  return control->flags;
724 }
725 
737 static inline rtems_task_priority
738 rtems_capture_task_start_priority (rtems_tcb* tcb)
739 {
742  );
743 }
744 
754 static inline rtems_task_priority
755 rtems_capture_task_real_priority (rtems_tcb* tcb)
756 {
757  return tcb->real_priority;
758 }
759 
769 static inline rtems_task_priority
770 rtems_capture_task_curr_priority (rtems_tcb* tcb)
771 {
772  return tcb->current_priority;
773 }
774 
786 
798 static inline rtems_capture_control_t*
799 rtems_capture_next_control (rtems_capture_control_t* control)
800 {
801  return control->next;
802 }
803 
813 static inline rtems_id
814 rtems_capture_control_id (rtems_capture_control_t* control)
815 {
816  return control->id;
817 }
818 
828 static inline rtems_name
829 rtems_capture_control_name (rtems_capture_control_t* control)
830 {
831  return control->name;
832 }
833 
843 static inline uint32_t
844 rtems_capture_control_flags (rtems_capture_control_t* control)
845 {
846  return control->flags;
847 }
848 
858 static inline uint32_t
859 rtems_capture_control_to_triggers (rtems_capture_control_t* control)
860 {
861  return control->to_triggers;
862 }
863 
873 static inline uint32_t
874 rtems_capture_control_from_triggers (rtems_capture_control_t* control)
875 {
876  return control->from_triggers;
877 }
878 
888 static inline uint32_t
889 rtems_capture_control_all_by_triggers (rtems_capture_control_t* control)
890 {
891  return control->by_triggers;
892 }
893 
904 static inline int
905 rtems_capture_control_by_valid (rtems_capture_control_t* control, int slot)
906 {
907  return control->by_valid & RTEMS_CAPTURE_CONTROL_FROM_MASK (slot);
908 }
909 
920 static inline rtems_name
921 rtems_capture_control_by_name (rtems_capture_control_t* control, int by)
922 {
924  return control->by[by].name;
925  return control->by[0].name;
926 }
927 
935 static inline rtems_id
936 rtems_capture_control_by_id (rtems_capture_control_t* control, int by)
937 {
939  return control->by[by].id;
940  return control->by[0].id;
941 }
942 
950 static inline uint32_t
951 rtems_capture_control_by_triggers (rtems_capture_control_t* control,
952  int by)
953 {
955  return control->by[by].trigger;
956  return control->by[0].trigger;
957 }
958 
968 static inline uint32_t
969 rtems_capture_control_count (void)
970 {
972  uint32_t count = 0;
973 
974  while (control)
975  {
976  count++;
977  control = rtems_capture_next_control (control);
978  }
979 
980  return count;
981 }
982 
983 #ifdef __cplusplus
984 }
985 #endif
986 
988 #endif
rtems_status_code rtems_capture_watch_floor(rtems_task_priority floor)
Capture set watch floor.
Priority_Control current_priority
This field is the current priority state of this thread.
Definition: thread.h:582
rtems_status_code rtems_capture_watch_del(rtems_name name, rtems_id id)
Capture delete watch.
rtems_status_code rtems_capture_watch_global(bool enable)
Capture enable/disable global watch.
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)
Capture clear trigger.
Objects_Id rtems_id
Used to manage and manipulate RTEMS object identifiers.
Definition: types.h:80
struct rtems_capture_control_s rtems_capture_control_t
Capture control structure for a group of tasks.
rtems_capture_trigger_mode_e
Capture trigger modes.
Definition: capture.h:206
rtems_status_code rtems_capture_monitor(bool enable)
Capture monitor enable/disable.
void rtems_capture_record_task(rtems_tcb *tcb)
Capture record task.
bool rtems_capture_watch_global_on(void)
Get global watch state.
void(* rtems_capture_timestamp)(rtems_capture_time_t *time)
Capture timestamp callout handler.
Definition: capture.h:238
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)
Capture set trigger.
Thread_Start_information Start
This field contains information about the starting state of this thread.
Definition: thread.h:645
rtems_status_code rtems_capture_close(void)
Capture close.
rtems_status_code rtems_capture_release(uint32_t cpu, uint32_t count)
Capture release records.
#define RTEMS_CAPTURE_TRIGGER_TASKS
The number of tasks in a trigger group.
Definition: capture.h:54
rtems_status_code rtems_capture_watch_add(rtems_name name, rtems_id id)
Capture add watch.
Objects_Control Object
This field is the object management structure for each thread.
Definition: thread.h:576
Priority_Control rtems_task_priority
Define the type for an RTEMS API task priority.
Definition: tasks.h:79
rtems_status_code
Classic API Status.
Definition: status.h:46
uint64_t rtems_capture_time_t
A capture timestamp.
Definition: capture.h:61
rtems_task_priority rtems_capture_watch_get_floor(void)
Capture set watch floor.
uint32_t rtems_name
Classic API object name type.
Definition: types.h:74
void rtems_capture_initialize_task(rtems_tcb *tcb)
Capture initialize task.
rtems_status_code rtems_capture_control(bool enable)
Capture control trace enable/disable.
rtems_status_code rtems_capture_watch_ctrl(rtems_name name, rtems_id id, bool enable)
Capture enable/disable watch.
Task id and mask for the from trigger.
Definition: capture.h:72
rtems_capture_control_t * rtems_capture_get_control_list(void)
Capture get control list.
Priority_Control initial_priority
This field is the initial priority.
Definition: thread.h:233
rtems_status_code rtems_object_get_classic_name(rtems_id id, rtems_name *name)
Obtain Name of Object.
uint32_t States_Control
The following type defines the control block used to manage a thread's state.
Definition: states.h:41
rtems_task_priority rtems_capture_watch_get_ceiling(void)
Get watch ceiling.
const char * rtems_capture_event_text(int event)
Capture get event text.
enum rtems_capture_trigger_e rtems_capture_trigger_t
Capture trigger.
RTEMS_INLINE_ROUTINE rtems_task_priority _RTEMS_tasks_Priority_from_Core(Priority_Control priority)
Converts a core priority into an RTEMS API priority.
Definition: tasksimpl.h:125
struct rtems_capture_from_s rtems_capture_from_t
Task id and mask for the from trigger.
enum rtems_capture_trigger_mode_e rtems_capture_trigger_mode_t
Capture trigger modes.
Capture control structure for a group of tasks.
Definition: capture.h:90
#define RTEMS_CAPTURE_CONTROL_FROM_MASK(_s)
The from_valid mask.
Definition: capture.h:106
rtems_status_code rtems_capture_watch_ceiling(rtems_task_priority ceiling)
Set watch ceiling.
States_Control current_state
This field is the current execution state of this thread.
Definition: thread.h:580
This structure defines the Thread Control Block (TCB).
Definition: thread.h:574
rtems_status_code rtems_capture_read(uint32_t cpu, uint32_t *read, rtems_capture_record_t **recs)
Capture read records from capture buffer.
rtems_status_code rtems_capture_open(uint32_t size, rtems_capture_timestamp timestamp)
Capture open.
rtems_capture_trigger_e
Capture trigger.
Definition: capture.h:218
Priority_Control real_priority
This field is the base priority of this thread.
Definition: thread.h:584
Definition: capture.h:154
Classic Tasks Manager Implementation.
Definition: capture.h:169
Objects_Id id
This is the object's ID.
Definition: object.h:237