RTEMS: cpukit/include/rtems/capture.h Source File

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
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>
37
38#include <string.h>
39
48#ifdef __cplusplus
49extern "C" {
50#endif
51
52/*
53 * Global capture flags.
54 */
55#define RTEMS_CAPTURE_INIT (1u << 0)
56#define RTEMS_CAPTURE_ON (1U << 1)
57#define RTEMS_CAPTURE_NO_MEMORY (1U << 2)
58#define RTEMS_CAPTURE_TRIGGERED (1U << 3)
59#define RTEMS_CAPTURE_GLOBAL_WATCH (1U << 4)
60#define RTEMS_CAPTURE_ONLY_MONITOR (1U << 5)
61
62/*
63 * Per-CPU capture flags.
64 */
65#define RTEMS_CAPTURE_OVERFLOW (1U << 0)
66#define RTEMS_CAPTURE_READER_ACTIVE (1U << 1)
67#define RTEMS_CAPTURE_READER_WAITING (1U << 2)
68
72#define RTEMS_CAPTURE_TRIGGER_TASKS (32)
73
79 typedef uint64_t rtems_capture_time;
80
90 typedef struct rtems_capture_from
91{
92 rtems_name name;
93 rtems_id id;
94 uint32_t trigger;
95} rtems_capture_from;
96
108 typedef struct rtems_capture_control
109{
110 rtems_name name;
111 rtems_id id;
112 uint32_t flags;
113 uint32_t to_triggers;
114 uint32_t from_triggers;
115 uint32_t by_triggers;
116 uint32_t by_valid;
117 rtems_capture_from by[RTEMS_CAPTURE_TRIGGER_TASKS];
118 struct rtems_capture_control* next;
119} rtems_capture_control;
120
124#define RTEMS_CAPTURE_CONTROL_FROM_MASK(_s) \
125 (UINT32_C(1) << (RTEMS_CAPTURE_TRIGGER_TASKS - ((_s) + 1)))
126
130#define RTEMS_CAPTURE_WATCH (1U << 0)
131
135#define RTEMS_CAPTURE_SWITCH (1 << 0)
136#define RTEMS_CAPTURE_CREATE (1 << 1)
137#define RTEMS_CAPTURE_START (1 << 2)
138#define RTEMS_CAPTURE_RESTART (1 << 3)
139#define RTEMS_CAPTURE_DELETE (1 << 4)
140#define RTEMS_CAPTURE_BEGIN (1 << 5)
141#define RTEMS_CAPTURE_EXITTED (1 << 6)
142#define RTEMS_CAPTURE_TERMINATED (1 << 7)
143
144#define RTEMS_CAPTURE_FROM_TRIGS (RTEMS_CAPTURE_SWITCH | \
145 RTEMS_CAPTURE_CREATE | \
146 RTEMS_CAPTURE_START | \
147 RTEMS_CAPTURE_RESTART | \
148 RTEMS_CAPTURE_DELETE)
149
150#define RTEMS_CAPTURE_TO_TRIGS (RTEMS_CAPTURE_SWITCH | \
151 RTEMS_CAPTURE_CREATE | \
152 RTEMS_CAPTURE_START | \
153 RTEMS_CAPTURE_RESTART | \
154 RTEMS_CAPTURE_DELETE | \
155 RTEMS_CAPTURE_BEGIN | \
156 RTEMS_CAPTURE_EXITTED)
157
161#define RTEMS_CAPTURE_TRACED (1U << 0)
162#define RTEMS_CAPTURE_INIT_TASK (1U << 1)
163#define RTEMS_CAPTURE_RECORD_TASK (1U << 2)
164
165/*
166 * @brief Capture record.
167 *
168 * This is a record that is written into
169 * the buffer. The events includes the priority of the task
170 * at the time of the context switch.
171 */
172 typedef struct rtems_capture_record
173{
174 size_t size;
175 uint32_t events;
176 rtems_id task_id;
177 rtems_capture_time time;
178} RTEMS_PACKED rtems_capture_record;
179
180/*
181 * @brief Capture task record.
182 *
183 * This is a record that is written into
184 * the buffer. The events includes the priority of the task
185 * at the time of the context switch.
186 */
187 typedef struct rtems_capture_task_record
188{
189 rtems_name name;
190 rtems_task_priority start_priority;
191 uint32_t stack_size;
192} RTEMS_PACKED rtems_capture_task_record;
193
197#define RTEMS_CAPTURE_REAL_PRI_EVENT_MASK UINT32_C (0x000000ff)
198#define RTEMS_CAPTURE_CURR_PRI_EVENT_MASK UINT32_C (0x0000ff00)
199#define RTEMS_CAPTURE_REAL_PRIORITY_EVENT (0)
200#define RTEMS_CAPTURE_CURR_PRIORITY_EVENT (8)
201#define RTEMS_CAPTURE_EVENT_START (16)
202#define RTEMS_CAPTURE_CREATED_BY_EVENT UINT32_C (0x00010000)
203#define RTEMS_CAPTURE_CREATED_EVENT UINT32_C (0x00020000)
204#define RTEMS_CAPTURE_STARTED_BY_EVENT UINT32_C (0x00040000)
205#define RTEMS_CAPTURE_STARTED_EVENT UINT32_C (0x00080000)
206#define RTEMS_CAPTURE_RESTARTED_BY_EVENT UINT32_C (0x00100000)
207#define RTEMS_CAPTURE_RESTARTED_EVENT UINT32_C (0x00200000)
208#define RTEMS_CAPTURE_DELETED_BY_EVENT UINT32_C (0x00400000)
209#define RTEMS_CAPTURE_DELETED_EVENT UINT32_C (0x00800000)
210#define RTEMS_CAPTURE_TERMINATED_EVENT UINT32_C (0x01000000)
211#define RTEMS_CAPTURE_BEGIN_EVENT UINT32_C (0x02000000)
212#define RTEMS_CAPTURE_EXITTED_EVENT UINT32_C (0x04000000)
213#define RTEMS_CAPTURE_SWITCHED_OUT_EVENT UINT32_C (0x08000000)
214#define RTEMS_CAPTURE_SWITCHED_IN_EVENT UINT32_C (0x10000000)
215#define RTEMS_CAPTURE_TIMESTAMP UINT32_C (0x20000000)
216#define RTEMS_CAPTURE_EVENT_END (29)
217
223 typedef enum rtems_capture_trigger_mode
224{
225 rtems_capture_to_any,
226 rtems_capture_from_any,
227 rtems_capture_from_to
228} rtems_capture_trigger_mode;
229
235 typedef enum rtems_capture_trigger
236{
237 rtems_capture_switch,
238 rtems_capture_create,
239 rtems_capture_start,
240 rtems_capture_restart,
241 rtems_capture_delete,
242 rtems_capture_begin,
243 rtems_capture_exitted,
244 rtems_capture_terminated
245} rtems_capture_trigger;
246
255 typedef void (*rtems_capture_timestamp)(rtems_capture_time* time);
256
270 typedef struct {
271 rtems_interrupt_lock_context lock_context;
272 rtems_interrupt_lock* lock;
273} rtems_capture_record_lock_context;
274
291 rtems_status_code rtems_capture_open (uint32_t size,
292 rtems_capture_timestamp timestamp);
293
304 rtems_status_code rtems_capture_close (void);
305
317 rtems_status_code rtems_capture_set_control (bool enable);
318
332 rtems_status_code rtems_capture_set_monitor (bool enable);
333
334/*
335 * @brief Capture flush trace buffer.
336 *
337 * This function flushes the trace buffer. The prime parameter allows the
338 * capture engine to also be primed again.
339 *
340 * @param[in] prime The prime after flush flag.
341 *
342 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
343 * error. Otherwise, a status code is returned indicating the
344 * source of the error.
345 */
346 rtems_status_code rtems_capture_flush (bool prime);
347
363 rtems_status_code rtems_capture_watch_add (rtems_name name, rtems_id id);
364
379 rtems_status_code rtems_capture_watch_del (rtems_name name, rtems_id id);
380
395 rtems_status_code rtems_capture_watch_ctrl (rtems_name name,
396 rtems_id id,
397 bool enable);
398
412 rtems_status_code rtems_capture_watch_global (bool enable);
413
422bool rtems_capture_watch_global_on (void);
423
439 rtems_status_code rtems_capture_watch_ceiling (rtems_task_priority ceiling);
440
449 rtems_task_priority rtems_capture_watch_get_ceiling (void);
450
466 rtems_status_code rtems_capture_watch_floor (rtems_task_priority floor);
467
476 rtems_task_priority rtems_capture_watch_get_floor (void);
477
506 rtems_status_code
507 rtems_capture_set_trigger (rtems_name from_name,
508 rtems_id from_id,
509 rtems_name to_name,
510 rtems_id to_id,
511 rtems_capture_trigger_mode mode,
512 rtems_capture_trigger trigger);
513
532 rtems_status_code
533 rtems_capture_clear_trigger (rtems_name from_name,
534 rtems_id from_id,
535 rtems_name to_name,
536 rtems_id to_id,
537 rtems_capture_trigger_mode mode,
538 rtems_capture_trigger trigger);
539
564 rtems_status_code rtems_capture_read (uint32_t cpu,
565 size_t* read,
566 const void** recs);
567
580 rtems_status_code rtems_capture_release (uint32_t cpu, uint32_t count);
581
594bool rtems_capture_filter (rtems_tcb* task, uint32_t events);
595
607void rtems_capture_get_time (rtems_capture_time* time);
608
620const char* rtems_capture_event_text (int event);
621
629void rtems_capture_initialize_task (rtems_tcb* tcb);
630
638void rtems_capture_record_task (rtems_tcb* tcb);
639
648void rtems_capture_record_lock (rtems_capture_record_lock_context* context);
649
657void rtems_capture_record_unlock (rtems_capture_record_lock_context* context);
658
675void* rtems_capture_record_open (rtems_tcb* task,
676 uint32_t events,
677 size_t size,
678 rtems_capture_record_lock_context* context);
679
688void rtems_capture_record_close (rtems_capture_record_lock_context* context);
689
701static inline void*
702rtems_capture_record_append (void* rec, const void* data, size_t size)
703{
704 memcpy (rec, data, size);
705 return ((uint8_t*) rec) + size;
706}
707
719static inline void*
720rtems_capture_record_extract (const void* rec, void* data, size_t size)
721{
722 memcpy (data, rec, size);
723 return ((uint8_t*) rec) + size;
724}
725
734static inline bool rtems_capture_task_recorded (rtems_tcb* tcb) {
735 return ((tcb->Capture.flags & RTEMS_CAPTURE_RECORD_TASK) != 0);
736}
737
746static inline bool rtems_capture_task_initialized (rtems_tcb* tcb) {
747 return ((tcb->Capture.flags & RTEMS_CAPTURE_INIT_TASK) != 0);
748}
749
759static inline rtems_id
760rtems_capture_task_id (rtems_tcb* tcb)
761{
762 return tcb->Object.id;
763}
764
774static inline int
775rtems_capture_task_api (rtems_id id)
776{
777 return _Objects_Get_API (id);
778}
779
789static inline States_Control
790rtems_capture_task_state (rtems_tcb* tcb)
791{
792 if (tcb)
793 return tcb->current_state;
794 return 0;
795}
796
806static inline rtems_name
807rtems_capture_task_name (rtems_tcb* tcb)
808{
809 rtems_name name;
810 rtems_object_get_classic_name( tcb->Object.id, &name );
811 return name;
812}
813
823static inline uint32_t
824rtems_capture_task_flags (rtems_tcb* tcb)
825{
826 return tcb->Capture.flags;
827}
828
838static inline rtems_capture_control*
839rtems_capture_task_control (rtems_tcb* tcb)
840{
841 return (rtems_capture_control*) tcb->Capture.control;
842}
843
853static inline uint32_t
854rtems_capture_task_control_flags (rtems_tcb* tcb)
855{
856 rtems_capture_control* control = rtems_capture_task_control (tcb);
857 if (!control)
858 return 0;
859 return control->flags;
860}
861
873static inline rtems_task_priority
874rtems_capture_task_start_priority (rtems_tcb* tcb)
875{
876 return _RTEMS_Priority_From_core (_Thread_Scheduler_get_home( tcb ),
877 tcb->Start.initial_priority);
878}
879
889static inline rtems_task_priority
890rtems_capture_task_real_priority (rtems_tcb* tcb)
891{
892 return _Thread_Get_unmapped_real_priority (tcb);
893}
894
904static inline rtems_task_priority
905rtems_capture_task_curr_priority (rtems_tcb* tcb)
906{
907 return _Thread_Get_unmapped_priority (tcb);
908}
909
919 rtems_capture_control*
920 rtems_capture_get_control_list (void);
921
933static inline rtems_capture_control*
934rtems_capture_next_control (rtems_capture_control* control)
935{
936 return control->next;
937}
938
948static inline rtems_id
949rtems_capture_control_id (rtems_capture_control* control)
950{
951 return control->id;
952}
953
963static inline rtems_name
964rtems_capture_control_name (rtems_capture_control* control)
965{
966 return control->name;
967}
968
978static inline uint32_t
979rtems_capture_control_flags (rtems_capture_control* control)
980{
981 return control->flags;
982}
983
993static inline uint32_t
994rtems_capture_control_to_triggers (rtems_capture_control* control)
995{
996 return control->to_triggers;
997}
998
1008static inline uint32_t
1009rtems_capture_control_from_triggers (rtems_capture_control* control)
1010{
1011 return control->from_triggers;
1012}
1013
1023static inline uint32_t
1024rtems_capture_control_all_by_triggers (rtems_capture_control* control)
1025{
1026 return control->by_triggers;
1027}
1028
1039static inline int
1040rtems_capture_control_by_valid (rtems_capture_control* control, int slot)
1041{
1042 return control->by_valid & RTEMS_CAPTURE_CONTROL_FROM_MASK (slot);
1043}
1044
1055static inline rtems_name
1056rtems_capture_control_by_name (rtems_capture_control* control, int by)
1057{
1058 if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
1059 return control->by[by].name;
1060 return control->by[0].name;
1061}
1062
1070static inline rtems_id
1071rtems_capture_control_by_id (rtems_capture_control* control, int by)
1072{
1073 if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
1074 return control->by[by].id;
1075 return control->by[0].id;
1076}
1077
1085static inline uint32_t
1086rtems_capture_control_by_triggers (rtems_capture_control* control,
1087 int by)
1088{
1089 if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
1090 return control->by[by].trigger;
1091 return control->by[0].trigger;
1092}
1093
1103static inline uint32_t
1104rtems_capture_control_count (void)
1105{
1106 rtems_capture_control* control = rtems_capture_get_control_list ();
1107 uint32_t count = 0;
1108
1109 while (control)
1110 {
1111 count++;
1112 control = rtems_capture_next_control (control);
1113 }
1114
1115 return count;
1116}
1117
1118#ifdef __cplusplus
1119}
1120#endif
1123#endif
rtems_object_get_classic_name
rtems_status_code rtems_object_get_classic_name(rtems_id id, rtems_name *name)
Obtain Name of Object.
Definition: rtemsobjectgetclassicname.c:25
rtems_status_code
rtems_status_code
Classic API Status.
Definition: status.h:43
_RTEMS_Priority_From_core
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
rtems_name
uint32_t rtems_name
Classic API object name type.
Definition: types.h:77
rtems_task_priority
uint32_t rtems_task_priority
Definition: tasks.h:55
rtems_id
Objects_Id rtems_id
Used to manage and manipulate RTEMS object identifiers.
Definition: types.h:83
_Objects_Get_API
RTEMS_INLINE_ROUTINE Objects_APIs _Objects_Get_API(Objects_Id id)
Returns the API portion of the ID.
Definition: object.h:255
States_Control
uint32_t States_Control
Definition: states.h:46
_Thread_Get_unmapped_real_priority
RTEMS_INLINE_ROUTINE Priority_Control _Thread_Get_unmapped_real_priority(const Thread_Control *the_thread)
Returns the unmapped real priority of the thread.
Definition: threadimpl.h:1615
_Thread_Get_unmapped_priority
RTEMS_INLINE_ROUTINE Priority_Control _Thread_Get_unmapped_priority(const Thread_Control *the_thread)
Returns the unmapped priority of the thread.
Definition: threadimpl.h:1601
_Thread_Scheduler_get_home
RTEMS_INLINE_ROUTINE const Scheduler_Control * _Thread_Scheduler_get_home(const Thread_Control *the_thread)
Gets the home scheduler of the thread.
Definition: threadimpl.h:1393
rtems_capture_watch_ceiling
rtems_status_code rtems_capture_watch_ceiling(rtems_task_priority ceiling)
Set watch ceiling.
Definition: capture.c:975
rtems_capture_watch_get_floor
rtems_task_priority rtems_capture_watch_get_floor(void)
Capture set watch floor.
Definition: capture.c:1007
rtems_capture_filter
bool rtems_capture_filter(rtems_tcb *task, uint32_t events)
Capture filter.
Definition: capture.c:486
rtems_capture_record_close
void rtems_capture_record_close(rtems_capture_record_lock_context *context)
Capture record close.
Definition: capture.c:418
rtems_capture_watch_get_ceiling
rtems_task_priority rtems_capture_watch_get_ceiling(void)
Get watch ceiling.
Definition: capture.c:985
rtems_capture_set_monitor
rtems_status_code rtems_capture_set_monitor(bool enable)
Capture monitor enable/disable.
Definition: capture.c:731
rtems_capture_record_unlock
void rtems_capture_record_unlock(rtems_capture_record_lock_context *context)
Capture record unlock.
Definition: capture.c:366
rtems_capture_release
rtems_status_code rtems_capture_release(uint32_t cpu, uint32_t count)
Capture release records.
Definition: capture.c:1288
RTEMS_CAPTURE_CONTROL_FROM_MASK
#define RTEMS_CAPTURE_CONTROL_FROM_MASK(_s)
Definition: capture.h:124
rtems_capture_watch_add
rtems_status_code rtems_capture_watch_add(rtems_name name, rtems_id id)
Capture add watch.
Definition: capture.c:817
rtems_capture_trigger_mode
rtems_capture_trigger_mode
Capture trigger modes.
Definition: capture.h:224
rtems_capture_close
rtems_status_code rtems_capture_close(void)
Capture close.
Definition: capture.c:643
rtems_capture_watch_global_on
bool rtems_capture_watch_global_on(void)
Get global watch state.
Definition: capture.c:963
rtems_capture_trigger
rtems_capture_trigger
Capture trigger.
Definition: capture.h:236
rtems_capture_get_control_list
rtems_capture_control * rtems_capture_get_control_list(void)
Capture get control list.
Definition: capture.c:1367
rtems_capture_record_task
void rtems_capture_record_task(rtems_tcb *tcb)
Capture record task.
Definition: capture.c:452
rtems_capture_read
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
rtems_capture_record_lock
void rtems_capture_record_lock(rtems_capture_record_lock_context *context)
Capture record lock.
Definition: capture.c:356
rtems_capture_set_control
rtems_status_code rtems_capture_set_control(bool enable)
Capture control trace enable/disable.
Definition: capture.c:703
rtems_capture_open
rtems_status_code rtems_capture_open(uint32_t size, rtems_capture_timestamp timestamp)
Capture open.
Definition: capture.c:587
rtems_capture_set_trigger
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_watch_del
rtems_status_code rtems_capture_watch_del(rtems_name name, rtems_id id)
Capture delete watch.
Definition: capture.c:848
rtems_capture_timestamp
void(* rtems_capture_timestamp)(rtems_capture_time *time)
Capture timestamp callout handler.
Definition: capture.h:255
RTEMS_CAPTURE_TRIGGER_TASKS
#define RTEMS_CAPTURE_TRIGGER_TASKS
Definition: capture.h:72
rtems_capture_clear_trigger
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
rtems_capture_initialize_task
void rtems_capture_initialize_task(rtems_tcb *tcb)
Capture initialize task.
Definition: capture.c:424
rtems_capture_get_time
void rtems_capture_get_time(rtems_capture_time *time)
Capture returns the current time.
Definition: capture.c:148
rtems_capture_watch_floor
rtems_status_code rtems_capture_watch_floor(rtems_task_priority floor)
Capture set watch floor.
Definition: capture.c:997
rtems_capture_watch_global
rtems_status_code rtems_capture_watch_global(bool enable)
Capture enable/disable global watch.
Definition: capture.c:939
rtems_capture_record_open
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_capture_watch_ctrl
rtems_status_code rtems_capture_watch_ctrl(rtems_name name, rtems_id id, bool enable)
Capture enable/disable watch.
Definition: capture.c:897
rtems_capture_time
uint64_t rtems_capture_time
A capture timestamp.
Definition: capture.h:79
rtems_capture_event_text
const char * rtems_capture_event_text(int event)
Capture get event text.
Definition: capture.c:1355
rtems.h
ISR_lock_Context
Local ISR lock context for acquire and release pairs.
Definition: isrlock.h:65
ISR_lock_Control
ISR lock control.
Definition: isrlock.h:56
Objects_Control::id
Objects_Id id
Definition: objectdata.h:43
RTEMS_PACKED
Used for passing and retrieving registers content to/from real mode interrupt call.
Definition: realmode_int.h:43
Thread_Start_information::initial_priority
Priority_Control initial_priority
Definition: thread.h:201
_Thread_Control
Definition: thread.h:732
_Thread_Control::Object
Objects_Control Object
Definition: thread.h:734
_Thread_Control::current_state
States_Control current_state
Definition: thread.h:756
_Thread_Control::Start
Thread_Start_information Start
Definition: thread.h:832
control
Definition: intercom.c:74
rtems_capture_control
Capture control structure for a group of tasks.
Definition: capture.h:109
rtems_capture_from
Task id and mask for the from trigger.
Definition: capture.h:91
rtems_capture_record_lock_context
Capture record lock context.
Definition: capture.h:270
rtems_capture_record
Definition: capture.h:173
rtems_capture_task_record
Definition: capture.h:188
tasksimpl.h
Classic Tasks Manager Implementation.