RTEMS  5.0.0
capture.h
Go to the documentation of this file.
1 
11 /*
12  ------------------------------------------------------------------------
13 
14  Copyright 2002, 2016 Chris Johns <chrisj@rtems.org>.
15  All rights reserved.
16 
17  COPYRIGHT (c) 1989-2014
18  On-Line Applications Research Corporation (OAR).
19 
20  The license and distribution terms for this file may be
21  found in the file LICENSE in this distribution.
22 
23  This software with is provided ``as is'' and with NO WARRANTY.
24 
25  ------------------------------------------------------------------------
26 
27  RTEMS Performance Monitoring and Measurement Framework.
28  This is the Capture Engine component.
29 
30 */
31 
32 #ifndef __CAPTURE_H_
33 #define __CAPTURE_H_
34 
35 #include <rtems.h>
36 #include <rtems/rtems/tasksimpl.h>
38 
39 #include <string.h>
40 
49 #ifdef __cplusplus
50 extern "C" {
51 #endif
52 
53 /*
54  * Global capture flags.
55  */
56 #define RTEMS_CAPTURE_INIT (1u << 0)
57 #define RTEMS_CAPTURE_ON (1U << 1)
58 #define RTEMS_CAPTURE_NO_MEMORY (1U << 2)
59 #define RTEMS_CAPTURE_TRIGGERED (1U << 3)
60 #define RTEMS_CAPTURE_GLOBAL_WATCH (1U << 4)
61 #define RTEMS_CAPTURE_ONLY_MONITOR (1U << 5)
62 
63 /*
64  * Per-CPU capture flags.
65  */
66 #define RTEMS_CAPTURE_OVERFLOW (1U << 0)
67 #define RTEMS_CAPTURE_READER_ACTIVE (1U << 1)
68 #define RTEMS_CAPTURE_READER_WAITING (1U << 2)
69 
73 #define RTEMS_CAPTURE_TRIGGER_TASKS (32)
74 
80 typedef uint64_t rtems_capture_time;
81 
91 typedef struct rtems_capture_from
92 {
93  rtems_name name;
94  rtems_id id;
95  uint32_t trigger;
97 
109 typedef struct rtems_capture_control
110 {
111  rtems_name name;
112  rtems_id id;
113  uint32_t flags;
114  uint32_t to_triggers;
115  uint32_t from_triggers;
116  uint32_t by_triggers;
117  uint32_t by_valid;
119  struct rtems_capture_control* next;
121 
125 #define RTEMS_CAPTURE_CONTROL_FROM_MASK(_s) \
126  (UINT32_C(1) << (RTEMS_CAPTURE_TRIGGER_TASKS - ((_s) + 1)))
127 
131 #define RTEMS_CAPTURE_WATCH (1U << 0)
132 
136 #define RTEMS_CAPTURE_SWITCH (1 << 0)
137 #define RTEMS_CAPTURE_CREATE (1 << 1)
138 #define RTEMS_CAPTURE_START (1 << 2)
139 #define RTEMS_CAPTURE_RESTART (1 << 3)
140 #define RTEMS_CAPTURE_DELETE (1 << 4)
141 #define RTEMS_CAPTURE_BEGIN (1 << 5)
142 #define RTEMS_CAPTURE_EXITTED (1 << 6)
143 #define RTEMS_CAPTURE_TERMINATED (1 << 7)
144 
145 #define RTEMS_CAPTURE_FROM_TRIGS (RTEMS_CAPTURE_SWITCH | \
146  RTEMS_CAPTURE_CREATE | \
147  RTEMS_CAPTURE_START | \
148  RTEMS_CAPTURE_RESTART | \
149  RTEMS_CAPTURE_DELETE)
150 
151 #define RTEMS_CAPTURE_TO_TRIGS (RTEMS_CAPTURE_SWITCH | \
152  RTEMS_CAPTURE_CREATE | \
153  RTEMS_CAPTURE_START | \
154  RTEMS_CAPTURE_RESTART | \
155  RTEMS_CAPTURE_DELETE | \
156  RTEMS_CAPTURE_BEGIN | \
157  RTEMS_CAPTURE_EXITTED)
158 
162 #define RTEMS_CAPTURE_TRACED (1U << 0)
163 #define RTEMS_CAPTURE_INIT_TASK (1U << 1)
164 #define RTEMS_CAPTURE_RECORD_TASK (1U << 2)
165 
166 /*
167  * @brief Capture record.
168  *
169  * This is a record that is written into
170  * the buffer. The events includes the priority of the task
171  * at the time of the context switch.
172  */
173 typedef struct rtems_capture_record
174 {
175  size_t size;
176  uint32_t events;
177  rtems_id task_id;
178  rtems_capture_time time;
180 
181 /*
182  * @brief Capture task record.
183  *
184  * This is a record that is written into
185  * the buffer. The events includes the priority of the task
186  * at the time of the context switch.
187  */
189 {
190  rtems_name name;
191  rtems_task_priority start_priority;
192  uint32_t stack_size;
194 
198 #define RTEMS_CAPTURE_REAL_PRI_EVENT_MASK UINT32_C (0x000000ff)
199 #define RTEMS_CAPTURE_CURR_PRI_EVENT_MASK UINT32_C (0x0000ff00)
200 #define RTEMS_CAPTURE_REAL_PRIORITY_EVENT (0)
201 #define RTEMS_CAPTURE_CURR_PRIORITY_EVENT (8)
202 #define RTEMS_CAPTURE_EVENT_START (16)
203 #define RTEMS_CAPTURE_CREATED_BY_EVENT UINT32_C (0x00010000)
204 #define RTEMS_CAPTURE_CREATED_EVENT UINT32_C (0x00020000)
205 #define RTEMS_CAPTURE_STARTED_BY_EVENT UINT32_C (0x00040000)
206 #define RTEMS_CAPTURE_STARTED_EVENT UINT32_C (0x00080000)
207 #define RTEMS_CAPTURE_RESTARTED_BY_EVENT UINT32_C (0x00100000)
208 #define RTEMS_CAPTURE_RESTARTED_EVENT UINT32_C (0x00200000)
209 #define RTEMS_CAPTURE_DELETED_BY_EVENT UINT32_C (0x00400000)
210 #define RTEMS_CAPTURE_DELETED_EVENT UINT32_C (0x00800000)
211 #define RTEMS_CAPTURE_TERMINATED_EVENT UINT32_C (0x01000000)
212 #define RTEMS_CAPTURE_BEGIN_EVENT UINT32_C (0x02000000)
213 #define RTEMS_CAPTURE_EXITTED_EVENT UINT32_C (0x04000000)
214 #define RTEMS_CAPTURE_SWITCHED_OUT_EVENT UINT32_C (0x08000000)
215 #define RTEMS_CAPTURE_SWITCHED_IN_EVENT UINT32_C (0x10000000)
216 #define RTEMS_CAPTURE_TIMESTAMP UINT32_C (0x20000000)
217 #define RTEMS_CAPTURE_EVENT_END (29)
218 
225 {
226  rtems_capture_to_any,
227  rtems_capture_from_any,
228  rtems_capture_from_to
230 
237 {
238  rtems_capture_switch,
239  rtems_capture_create,
240  rtems_capture_start,
241  rtems_capture_restart,
242  rtems_capture_delete,
243  rtems_capture_begin,
244  rtems_capture_exitted,
245  rtems_capture_terminated
247 
256 typedef void (*rtems_capture_timestamp)(rtems_capture_time* time);
257 
271 typedef struct {
272  rtems_interrupt_lock_context lock_context;
273  rtems_interrupt_lock* lock;
275 
293  rtems_capture_timestamp timestamp);
294 
306 
319 
334 
335 /*
336  * @brief Capture flush trace buffer.
337  *
338  * This function flushes the trace buffer. The prime parameter allows the
339  * capture engine to also be primed again.
340  *
341  * @param[in] prime The prime after flush flag.
342  *
343  * @retval This method returns RTEMS_SUCCESSFUL if there was not an
344  * error. Otherwise, a status code is returned indicating the
345  * source of the error.
346  */
347 rtems_status_code rtems_capture_flush (bool prime);
348 
365 
381 
397  rtems_id id,
398  bool enable);
399 
414 
424 
441 
451 
468 
478 
509  rtems_id from_id,
510  rtems_name to_name,
511  rtems_id to_id,
512  rtems_capture_trigger_mode mode,
513  rtems_capture_trigger trigger);
514 
535  rtems_id from_id,
536  rtems_name to_name,
537  rtems_id to_id,
538  rtems_capture_trigger_mode mode,
539  rtems_capture_trigger trigger);
540 
566  size_t* read,
567  const void** recs);
568 
581 rtems_status_code rtems_capture_release (uint32_t cpu, uint32_t count);
582 
595 bool rtems_capture_filter (rtems_tcb* task, uint32_t events);
596 
608 void rtems_capture_get_time (rtems_capture_time* time);
609 
621 const char* rtems_capture_event_text (int event);
622 
631 
640 
650 
659 
677  uint32_t events,
678  size_t size,
680 
690 
702 static inline void*
703 rtems_capture_record_append (void* rec, const void* data, size_t size)
704 {
705  memcpy (rec, data, size);
706  return ((uint8_t*) rec) + size;
707 }
708 
720 static inline void*
721 rtems_capture_record_extract (const void* rec, void* data, size_t size)
722 {
723  memcpy (data, rec, size);
724  return ((uint8_t*) rec) + size;
725 }
726 
735 static inline bool rtems_capture_task_recorded (rtems_tcb* tcb) {
736  return ((tcb->Capture.flags & RTEMS_CAPTURE_RECORD_TASK) != 0);
737 }
738 
747 static inline bool rtems_capture_task_initialized (rtems_tcb* tcb) {
748  return ((tcb->Capture.flags & RTEMS_CAPTURE_INIT_TASK) != 0);
749 }
750 
760 static inline rtems_id
761 rtems_capture_task_id (rtems_tcb* tcb)
762 {
763  return tcb->Object.id;
764 }
765 
775 static inline int
776 rtems_capture_task_api (rtems_id id)
777 {
778  return _Objects_Get_API (id);
779 }
780 
790 static inline States_Control
791 rtems_capture_task_state (rtems_tcb* tcb)
792 {
793  if (tcb)
794  return tcb->current_state;
795  return 0;
796 }
797 
807 static inline rtems_name
808 rtems_capture_task_name (rtems_tcb* tcb)
809 {
810  rtems_name name;
811  rtems_object_get_classic_name( tcb->Object.id, &name );
812  return name;
813 }
814 
824 static inline uint32_t
825 rtems_capture_task_flags (rtems_tcb* tcb)
826 {
827  return tcb->Capture.flags;
828 }
829 
839 static inline rtems_capture_control*
840 rtems_capture_task_control (rtems_tcb* tcb)
841 {
842  return tcb->Capture.control;
843 }
844 
854 static inline uint32_t
855 rtems_capture_task_control_flags (rtems_tcb* tcb)
856 {
857  rtems_capture_control* control = tcb->Capture.control;
858  if (!control)
859  return 0;
860  return control->flags;
861 }
862 
874 static inline rtems_task_priority
875 rtems_capture_task_start_priority (rtems_tcb* tcb)
876 {
877  return _RTEMS_Priority_From_core (_Thread_Scheduler_get_home( tcb ),
878  tcb->Start.initial_priority);
879 }
880 
890 static inline rtems_task_priority
891 rtems_capture_task_real_priority (rtems_tcb* tcb)
892 {
894 }
895 
905 static inline rtems_task_priority
906 rtems_capture_task_curr_priority (rtems_tcb* tcb)
907 {
909 }
910 
922 
934 static inline rtems_capture_control*
935 rtems_capture_next_control (rtems_capture_control* control)
936 {
937  return control->next;
938 }
939 
949 static inline rtems_id
950 rtems_capture_control_id (rtems_capture_control* control)
951 {
952  return control->id;
953 }
954 
964 static inline rtems_name
965 rtems_capture_control_name (rtems_capture_control* control)
966 {
967  return control->name;
968 }
969 
979 static inline uint32_t
980 rtems_capture_control_flags (rtems_capture_control* control)
981 {
982  return control->flags;
983 }
984 
994 static inline uint32_t
995 rtems_capture_control_to_triggers (rtems_capture_control* control)
996 {
997  return control->to_triggers;
998 }
999 
1009 static inline uint32_t
1010 rtems_capture_control_from_triggers (rtems_capture_control* control)
1011 {
1012  return control->from_triggers;
1013 }
1014 
1024 static inline uint32_t
1025 rtems_capture_control_all_by_triggers (rtems_capture_control* control)
1026 {
1027  return control->by_triggers;
1028 }
1029 
1040 static inline int
1041 rtems_capture_control_by_valid (rtems_capture_control* control, int slot)
1042 {
1043  return control->by_valid & RTEMS_CAPTURE_CONTROL_FROM_MASK (slot);
1044 }
1045 
1056 static inline rtems_name
1057 rtems_capture_control_by_name (rtems_capture_control* control, int by)
1058 {
1059  if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
1060  return control->by[by].name;
1061  return control->by[0].name;
1062 }
1063 
1071 static inline rtems_id
1072 rtems_capture_control_by_id (rtems_capture_control* control, int by)
1073 {
1074  if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
1075  return control->by[by].id;
1076  return control->by[0].id;
1077 }
1078 
1086 static inline uint32_t
1087 rtems_capture_control_by_triggers (rtems_capture_control* control,
1088  int by)
1089 {
1090  if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
1091  return control->by[by].trigger;
1092  return control->by[0].trigger;
1093 }
1094 
1104 static inline uint32_t
1105 rtems_capture_control_count (void)
1106 {
1108  uint32_t count = 0;
1109 
1110  while (control)
1111  {
1112  count++;
1113  control = rtems_capture_next_control (control);
1114  }
1115 
1116  return count;
1117 }
1118 
1119 #ifdef __cplusplus
1120 }
1121 #endif
1122 
1124 #endif
rtems_status_code rtems_capture_watch_floor(rtems_task_priority floor)
Capture set watch floor.
Definition: capture.c:997
struct rtems_capture_from rtems_capture_from
Task id and mask for the from trigger.
rtems_status_code rtems_capture_set_monitor(bool enable)
Capture monitor enable/disable.
Definition: capture.c:731
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 mode, rtems_capture_trigger trigger)
Capture clear trigger.
Definition: capture.c:1135
ssize_t read(int fd, void *buffer, size_t count)
Definition: read.c:27
void(* rtems_capture_timestamp)(rtems_capture_time *time)
Capture timestamp callout handler.
Definition: capture.h:256
Task id and mask for the from trigger.
Definition: capture.h:91
Capture control structure for a group of tasks.
Definition: capture.h:109
RTEMS_INLINE_ROUTINE Objects_APIs _Objects_Get_API(Objects_Id id)
Definition: object.h:250
rtems_status_code rtems_capture_watch_del(rtems_name name, rtems_id id)
Capture delete watch.
Definition: capture.c:848
rtems_status_code rtems_capture_watch_global(bool enable)
Capture enable/disable global watch.
Definition: capture.c:939
rtems_status_code rtems_capture_set_control(bool enable)
Capture control trace enable/disable.
Definition: capture.c:703
struct rtems_capture_control rtems_capture_control
Capture control structure for a group of tasks.
uint32_t rtems_name
Classic API object name type.
Definition: types.h:77
uint64_t rtems_capture_time
A capture timestamp.
Definition: capture.h:80
Thread_Start_information Start
Definition: thread.h:828
void rtems_capture_record_task(rtems_tcb *tcb)
Capture record task.
Definition: capture.c:452
Inlined Routines Associated with the Manipulation of the Scheduler.
bool rtems_capture_watch_global_on(void)
Get global watch state.
Definition: capture.c:963
RTEMS_INLINE_ROUTINE Priority_Control _Thread_Get_priority(const Thread_Control *the_thread)
Returns the priority of the thread.
Definition: threadimpl.h:1140
Priority_Control priority
The priority value of this node.
Definition: priority.h:106
rtems_capture_trigger
Capture trigger.
Definition: capture.h:236
rtems_capture_control * rtems_capture_get_control_list(void)
Capture get control list.
Definition: capture.c:1367
rtems_status_code rtems_capture_close(void)
Capture close.
Definition: capture.c:643
rtems_status_code rtems_capture_release(uint32_t cpu, uint32_t count)
Capture release records.
Definition: capture.c:1288
#define RTEMS_CAPTURE_TRIGGER_TASKS
Definition: capture.h:73
rtems_status_code rtems_capture_watch_add(rtems_name name, rtems_id id)
Capture add watch.
Definition: capture.c:817
rtems_status_code rtems_capture_read(uint32_t cpu, size_t *read, const void **recs)
Capture read records from capture buffer.
Definition: capture.c:1234
ISR lock control.
Definition: isrlock.h:56
void rtems_capture_record_close(rtems_capture_record_lock_context *context)
Capture record close.
Definition: capture.c:418
void rtems_capture_record_lock(rtems_capture_record_lock_context *context)
Capture record lock.
Definition: capture.c:356
rtems_status_code
Classic API Status.
Definition: status.h:43
Definition: thread.h:728
rtems_task_priority rtems_capture_watch_get_floor(void)
Capture set watch floor.
Definition: capture.c:1007
Objects_Control Object
Definition: thread.h:730
void rtems_capture_initialize_task(rtems_tcb *tcb)
Capture initialize task.
Definition: capture.c:424
#define SCHEDULER_PRIORITY_UNMAP(priority)
Returns the plain priority value.
Definition: schedulerimpl.h:47
States_Control current_state
Definition: thread.h:752
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 mode, rtems_capture_trigger trigger)
Capture set trigger.
Definition: capture.c:1057
rtems_capture_trigger_mode
Capture trigger modes.
Definition: capture.h:224
Used for passing and retrieving registers content to/from real mode interrupt call.
Definition: realmode_int.h:43
Definition: intercom.c:74
rtems_status_code rtems_capture_watch_ctrl(rtems_name name, rtems_id id, bool enable)
Capture enable/disable watch.
Definition: capture.c:897
Priority_Control initial_priority
Definition: thread.h:196
rtems_status_code rtems_object_get_classic_name(rtems_id id, rtems_name *name)
Obtain Name of Object.
Definition: rtemsobjectgetclassicname.c:25
uint32_t States_Control
Definition: states.h:41
void * rtems_capture_record_open(rtems_tcb *task, uint32_t events, size_t size, rtems_capture_record_lock_context *context)
Capture record open.
Definition: capture.c:372
rtems_task_priority rtems_capture_watch_get_ceiling(void)
Get watch ceiling.
Definition: capture.c:985
void rtems_capture_record_unlock(rtems_capture_record_lock_context *context)
Capture record unlock.
Definition: capture.c:366
const char * rtems_capture_event_text(int event)
Capture get event text.
Definition: capture.c:1355
unsigned context
Definition: tlb.h:108
Capture record lock context.
Definition: capture.h:271
Objects_Id rtems_id
Used to manage and manipulate RTEMS object identifiers.
Definition: types.h:83
Definition: capture.h:188
#define RTEMS_CAPTURE_CONTROL_FROM_MASK(_s)
Definition: capture.h:125
Local ISR lock context for acquire and release pairs.
Definition: isrlock.h:65
rtems_status_code rtems_capture_watch_ceiling(rtems_task_priority ceiling)
Set watch ceiling.
Definition: capture.c:975
RTEMS_INLINE_ROUTINE rtems_task_priority _RTEMS_Priority_From_core(const Scheduler_Control *scheduler, Priority_Control priority)
Converts the SuperCore priority to the corresponding RTEMS API priority.
Definition: tasksimpl.h:105
unsigned size
Definition: tte.h:74
Definition: capture.h:173
Priority_Node Real_priority
The base priority of this thread in its home scheduler instance.
Definition: thread.h:757
void rtems_capture_get_time(rtems_capture_time *time)
Capture returns the current time.
Definition: capture.c:148
rtems_status_code rtems_capture_open(uint32_t size, rtems_capture_timestamp timestamp)
Capture open.
Definition: capture.c:587
bool rtems_capture_filter(rtems_tcb *task, uint32_t events)
Capture filter.
Definition: capture.c:486
Classic Tasks Manager Implementation.
Objects_Id id
Definition: objectdata.h:43
uint32_t rtems_task_priority
Definition: tasks.h:54