source: rtems/cpukit/include/rtems/capture.h @ ef900ab

Last change on this file since ef900ab was ef900ab, checked in by Sebastian Huber <sebastian.huber@…>, on Mar 7, 2018 at 12:01:19 PM

capture: Fix get priority methods

  • Property mode set to 100644
File size: 32.3 KB
Line 
1/**
2 * @file rtems/capture.h
3 *
4 * @brief Capture Engine Component of the RTEMS Measurement and
5 * Monitoring System
6 *
7 * This is the Capture Engine component of the RTEMS Measurement and
8 * Monitoring system.
9 */
10
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#include <rtems/score/schedulerimpl.h>
38
39/**
40 *  @defgroup libmisc_capture RTEMS Capture Engine
41 *
42 *  @ingroup libmisc
43 *
44 *  Capture Engine Component of the RTEMS Measurement and Monitoring System
45 */
46/**@{*/
47#ifdef __cplusplus
48extern "C" {
49#endif
50
51/*
52 * Global capture flags.
53 */
54#define RTEMS_CAPTURE_INIT           (1u << 0)
55#define RTEMS_CAPTURE_ON             (1U << 1)
56#define RTEMS_CAPTURE_NO_MEMORY      (1U << 2)
57#define RTEMS_CAPTURE_TRIGGERED      (1U << 3)
58#define RTEMS_CAPTURE_GLOBAL_WATCH   (1U << 4)
59#define RTEMS_CAPTURE_ONLY_MONITOR   (1U << 5)
60
61/*
62 * Per-CPU capture flags.
63 */
64#define RTEMS_CAPTURE_OVERFLOW       (1U << 0)
65#define RTEMS_CAPTURE_READER_ACTIVE  (1U << 1)
66#define RTEMS_CAPTURE_READER_WAITING (1U << 2)
67
68/**
69 * The number of tasks in a trigger group.
70 */
71#define RTEMS_CAPTURE_TRIGGER_TASKS (32)
72
73/**
74 * @brief A capture timestamp.
75 *
76 * This is a nanosecond capture timestamp
77 */
78typedef uint64_t rtems_capture_time;
79
80/**
81 * @brief Task id and mask for the from trigger.
82 *
83 * A from capture is a task id and a mask for the type of
84 * from trigger we are interested in. The mask uses the same
85 * bit maps as the flags field in the control structure. There
86 * will only be a from type trigger if the flags in the control
87 * structure has the specific *_BY bit set.
88 */
89typedef struct rtems_capture_from
90{
91  rtems_name name;
92  rtems_id   id;
93  uint32_t   trigger;
94} rtems_capture_from;
95
96/**
97 * @brief Capture control structure for a group of tasks.
98 *
99 * RTEMS control holds the trigger and watch configuration for a group of
100 * tasks with the same name. The flags hold global control flags.
101 *
102 * The to_triggers fields holds triggers TO this task. The from_triggers holds
103 * triggers from this task. The by_triggers is an OR or triggers which are
104 * caused BY the task listed TO this task. The by_valid flag which entries
105 * in by are valid.
106 */
107typedef struct rtems_capture_control
108{
109  rtems_name                    name;
110  rtems_id                      id;
111  uint32_t                      flags;
112  uint32_t                      to_triggers;
113  uint32_t                      from_triggers;
114  uint32_t                      by_triggers;
115  uint32_t                      by_valid;
116  rtems_capture_from            by[RTEMS_CAPTURE_TRIGGER_TASKS];
117  struct rtems_capture_control* next;
118} rtems_capture_control;
119
120/**
121 * The from_valid mask.
122 */
123#define RTEMS_CAPTURE_CONTROL_FROM_MASK(_s) \
124 (UINT32_C(1) << (RTEMS_CAPTURE_TRIGGER_TASKS - ((_s) + 1)))
125
126/**
127 * Control flags.
128 */
129#define RTEMS_CAPTURE_WATCH         (1U << 0)
130
131/**
132 * Control triggers.
133 */
134#define RTEMS_CAPTURE_SWITCH        (1 << 0)
135#define RTEMS_CAPTURE_CREATE        (1 << 1)
136#define RTEMS_CAPTURE_START         (1 << 2)
137#define RTEMS_CAPTURE_RESTART       (1 << 3)
138#define RTEMS_CAPTURE_DELETE        (1 << 4)
139#define RTEMS_CAPTURE_BEGIN         (1 << 5)
140#define RTEMS_CAPTURE_EXITTED       (1 << 6)
141#define RTEMS_CAPTURE_TERMINATED    (1 << 7)
142
143#define RTEMS_CAPTURE_FROM_TRIGS    (RTEMS_CAPTURE_SWITCH  | \
144                                     RTEMS_CAPTURE_CREATE | \
145                                     RTEMS_CAPTURE_START | \
146                                     RTEMS_CAPTURE_RESTART | \
147                                     RTEMS_CAPTURE_DELETE)
148
149#define RTEMS_CAPTURE_TO_TRIGS      (RTEMS_CAPTURE_SWITCH | \
150                                     RTEMS_CAPTURE_CREATE | \
151                                     RTEMS_CAPTURE_START | \
152                                     RTEMS_CAPTURE_RESTART | \
153                                     RTEMS_CAPTURE_DELETE | \
154                                     RTEMS_CAPTURE_BEGIN | \
155                                     RTEMS_CAPTURE_EXITTED)
156
157/**
158 * Task flags.
159 */
160#define RTEMS_CAPTURE_TRACED      (1U << 0)
161#define RTEMS_CAPTURE_INIT_TASK   (1U << 1)
162#define RTEMS_CAPTURE_RECORD_TASK (1U << 2)
163
164/*
165 * @brief Capture record.
166 *
167 * This is a record that is written into
168 * the buffer. The events includes the priority of the task
169 * at the time of the context switch.
170 */
171typedef struct rtems_capture_record
172{
173  size_t             size;
174  uint32_t           events;
175  rtems_id           task_id;
176  rtems_capture_time time;
177} RTEMS_PACKED rtems_capture_record;
178
179/*
180 * @brief Capture task record.
181 *
182 * This is a record that is written into
183 * the buffer. The events includes the priority of the task
184 * at the time of the context switch.
185 */
186typedef struct rtems_capture_task_record
187{
188  rtems_name          name;
189  rtems_task_priority start_priority;
190  uint32_t            stack_size;
191} RTEMS_PACKED rtems_capture_task_record;
192
193/**
194 * The capture record event flags.
195 */
196#define RTEMS_CAPTURE_REAL_PRI_EVENT_MASK UINT32_C (0x000000ff)
197#define RTEMS_CAPTURE_CURR_PRI_EVENT_MASK UINT32_C (0x0000ff00)
198#define RTEMS_CAPTURE_REAL_PRIORITY_EVENT (0)
199#define RTEMS_CAPTURE_CURR_PRIORITY_EVENT (8)
200#define RTEMS_CAPTURE_EVENT_START         (16)
201#define RTEMS_CAPTURE_CREATED_BY_EVENT    UINT32_C (0x00010000)
202#define RTEMS_CAPTURE_CREATED_EVENT       UINT32_C (0x00020000)
203#define RTEMS_CAPTURE_STARTED_BY_EVENT    UINT32_C (0x00040000)
204#define RTEMS_CAPTURE_STARTED_EVENT       UINT32_C (0x00080000)
205#define RTEMS_CAPTURE_RESTARTED_BY_EVENT  UINT32_C (0x00100000)
206#define RTEMS_CAPTURE_RESTARTED_EVENT     UINT32_C (0x00200000)
207#define RTEMS_CAPTURE_DELETED_BY_EVENT    UINT32_C (0x00400000)
208#define RTEMS_CAPTURE_DELETED_EVENT       UINT32_C (0x00800000)
209#define RTEMS_CAPTURE_TERMINATED_EVENT    UINT32_C (0x01000000)
210#define RTEMS_CAPTURE_BEGIN_EVENT         UINT32_C (0x02000000)
211#define RTEMS_CAPTURE_EXITTED_EVENT       UINT32_C (0x04000000)
212#define RTEMS_CAPTURE_SWITCHED_OUT_EVENT  UINT32_C (0x08000000)
213#define RTEMS_CAPTURE_SWITCHED_IN_EVENT   UINT32_C (0x10000000)
214#define RTEMS_CAPTURE_TIMESTAMP           UINT32_C (0x20000000)
215#define RTEMS_CAPTURE_EVENT_END           (29)
216
217/**
218 * @brief Capture trigger modes
219 *
220 * The types of trigger modes that exist.
221 */
222typedef enum rtems_capture_trigger_mode
223{
224  rtems_capture_to_any,
225  rtems_capture_from_any,
226  rtems_capture_from_to
227} rtems_capture_trigger_mode;
228
229/**
230 * @brief Capture trigger.
231 *
232 * The types of triggers that exist.
233 */
234typedef enum rtems_capture_trigger
235{
236  rtems_capture_switch,
237  rtems_capture_create,
238  rtems_capture_start,
239  rtems_capture_restart,
240  rtems_capture_delete,
241  rtems_capture_begin,
242  rtems_capture_exitted,
243  rtems_capture_terminated
244} rtems_capture_trigger;
245
246/**
247 * @brief Capture timestamp callout handler.
248 *
249 * This defines the callout handler to obtain a time stamp. The
250 * value returned is time count since the last read.
251 *
252 */
253
254typedef void (*rtems_capture_timestamp)(rtems_capture_time* time);
255
256/**
257 * @brief Capture record lock context.
258 *
259 * This structure is used to lock a per CPU buffer when opeining recording. The
260 * per CPU buffer is held locked until the record close is called. Locking
261 * masks interrupts so use this lock only when needed and do not hold it for
262 * long.
263 *
264 * The lock first masks the CPU interrupt before taking the interrupt
265 * lock. This stops a thread context taking the lock and then an interrupt on
266 * the same CPU attempting to take the lock so creating a deadlock.
267 *
268 */
269typedef struct {
270  rtems_interrupt_lock_context lock_context;
271  rtems_interrupt_lock*        lock;
272} rtems_capture_record_lock_context;
273
274/**
275 * @brief Capture open
276 *
277 * This function initialises the realtime trace manager allocating the
278 * capture buffer. It is assumed we have a working heap at stage of
279 * initialisation.
280 *
281 * @param[in] size The number of capture records to define.
282 * @param[in] timestamp The timestamp callout handler to use. If the
283 *            the handler is NULL a default  nano-second timestamp
284 *            will be used.
285 *
286 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
287 *         error. Otherwise, a status code is returned indicating the
288 *         source of the error.
289 */
290rtems_status_code rtems_capture_open (uint32_t                size,
291                                      rtems_capture_timestamp timestamp);
292
293/**
294 * @brief Capture close
295 *
296 * This function shutdowns the tracer and release any claimed
297 * resources.
298 *
299 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
300 *         error. Otherwise, a status code is returned indicating the
301 *         source of the error.
302 */
303rtems_status_code rtems_capture_close (void);
304
305/**
306 * @brief Capture control trace enable/disable.
307 *
308 * This function allows control of tracing at a global level.
309 *
310 * @param[in]  enable The trace enable/disable flag.
311 *
312 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
313 *         error. Otherwise, a status code is returned indicating the
314 *         source of the error.
315 */
316rtems_status_code rtems_capture_set_control (bool enable);
317
318/**
319 * @brief Capture monitor enable/disable.
320 *
321 * This function enable the monitor mode. When in the monitor mode
322 * the tasks are monitored but no data is saved. This can be used
323 * to profile the load on a system.
324 *
325 * @param[in]  enable The monitor enable/disable flag.
326 *
327 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
328 *         error. Otherwise, a status code is returned indicating the
329 *         source of the error.
330 */
331rtems_status_code rtems_capture_set_monitor (bool enable);
332
333/*
334 * @brief Capture flush trace buffer.
335 *
336 * This function flushes the trace buffer. The prime parameter allows the
337 * capture engine to also be primed again.
338 *
339 * @param[in]  prime The prime after flush flag.
340 *
341 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
342 *         error. Otherwise, a status code is returned indicating the
343 *         source of the error.
344 */
345rtems_status_code rtems_capture_flush (bool prime);
346
347/**
348 * @brief Capture add watch
349 *
350 * This function defines a watch for a specific task given a name. A watch
351 * causes it to be traced either in or out of context. The watch can be
352 * optionally enabled or disabled with the set routine. It is disabled by
353 * default.
354 *
355 * @param[in]  name The name of the @a capture_controls entry
356 * @param[in]  id The id of the @a capture_controls entry.
357 *
358 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
359 *         error. Otherwise, a status code is returned indicating the
360 *         source of the error.
361 */
362rtems_status_code rtems_capture_watch_add (rtems_name name, rtems_id id);
363
364/**
365 * @brief Capture delete watch.
366 *
367 * This function removes a watch for a specific task given a name. The task
368 * description will still exist if referenced by a trace record in the trace
369 * buffer or a global watch is defined.
370 *
371 * @param[in]  name The name of the @a capture_controls entry
372 * @param[in]  id The id of the @a capture_controls entry.
373 *
374 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
375 *         error. Otherwise, a status code is returned indicating the
376 *         source of the error.
377 */
378rtems_status_code rtems_capture_watch_del (rtems_name name, rtems_id id);
379
380/**
381 * @brief Capture enable/disable watch.
382 *
383 * This function allows control of a watch. The watch can be enabled or
384 * disabled.
385 *
386 * @param[in]  name The name of the @a capture_controls entry
387 * @param[in]  id The id of the @a capture_controls entry.
388 * @param[in]  enable The enable/disable flag for the watch.
389 *
390 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
391 *         error. Otherwise, a status code is returned indicating the
392 *         source of the error.
393 */
394rtems_status_code rtems_capture_watch_ctrl (rtems_name name,
395                                            rtems_id   id,
396                                            bool       enable);
397
398/**
399 * @brief Capture enable/disable global watch.
400 *
401 * This function allows control of a global watch. The watch can
402 * be enabled or disabled. A global watch configures all tasks below
403 * the ceiling and above the floor to be traced.
404 *
405 * @param[in]  enable The enable/disable flag for the watch.
406 *
407 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
408 *         error. Otherwise, a status code is returned indicating the
409 *         source of the error.
410 */
411rtems_status_code rtems_capture_watch_global (bool enable);
412
413/**
414 * @brief Get global watch state
415 *
416 * This function returns the global watch state.
417 *
418 * @retval This method returns true  if the global watch
419 *         is on.  Otherwise, it returns false.
420 */
421bool rtems_capture_watch_global_on (void);
422
423/**
424 * @brief Set watch ceiling.
425 *
426 * This function sets a watch ceiling. Events from tasks at or greater
427 * than the ceiling priority are ignored. This is a simple way to
428 * monitor an application and exclude system tasks running at a higher
429 * priority level.
430 *
431 * @param[in] ceiling specifies the priority level immediately above
432 *     that at which events from tasks are not captured.
433 *
434 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
435 *         error. Otherwise, a status code is returned indicating the
436 *         source of the error.
437 */
438rtems_status_code rtems_capture_watch_ceiling (rtems_task_priority ceiling);
439
440/**
441 * @brief Get watch ceiling.
442 *
443 * This function gets the watch ceiling.
444 *
445 * @retval The priority level immediately above that at which events
446 *         from tasks are not captured.
447 */
448rtems_task_priority rtems_capture_watch_get_ceiling (void);
449
450/**
451 * @brief Capture set watch floor.
452 *
453 * This function sets a watch floor. Tasks at or less than the
454 * floor priority are not watched. This is a simple way to monitor
455 * an application and exclude system tasks running at a lower
456 * priority level.
457 *
458 * @param[in] floor specifies the priority level immediately below
459 *     that at which events from tasks are not captured.
460 *
461 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
462 *         error. Otherwise, a status code is returned indicating the
463 *         source of the error.
464 */
465rtems_status_code rtems_capture_watch_floor (rtems_task_priority floor);
466
467/**
468 * @brief Capture set watch floor
469 *
470 * This function gets the watch floor.
471 *
472 * @retval The priority level immediately below
473 *     that at which events from tasks are not captured.
474 */
475rtems_task_priority rtems_capture_watch_get_floor (void);
476
477/**
478 * @brief Capture set trigger
479 *
480 * This function sets a trigger.
481 *
482 * This set trigger routine will create a trace control for the
483 * target task. The task list is searched and any existing tasks
484 * are linked to the new control.
485 *
486 * We can have a number of tasks that have the same name so we
487 * search using names. This means a number of tasks can be
488 * linked to single control.
489 *
490 * Some events captured such as context switch include two
491 * tasks. These are referred to as being "from" and "to"
492 * Some events may only have one task specified.
493 *
494 * @param[in] from_name specifies the name of the from task.
495 * @param[in] from_id specifies the id of the from task.
496 * @param[in] to_name specifies the name of the to task.
497 * @param[in] to_id specifies the id of the to task.
498 * @param[in] mode specifies the trigger mode.
499 * @param[in] trigger specifies the type of trigger.
500 *
501 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
502 *         error. Otherwise, a status code is returned indicating the
503 *         source of the error.
504 */
505rtems_status_code
506rtems_capture_set_trigger (rtems_name                 from_name,
507                           rtems_id                   from_id,
508                           rtems_name                 to_name,
509                           rtems_id                   to_id,
510                           rtems_capture_trigger_mode mode,
511                           rtems_capture_trigger      trigger);
512
513/**
514 * @brief Capture clear trigger.
515 *
516 * This function clears a trigger.
517 *
518 * This clear trigger routine will not clear a watch.
519 *
520 * @param[in] from_name specifies the name of the from task.
521 * @param[in] from_id specifies the id of the from task.
522 * @param[in] to_name specifies the name of the to task.
523 * @param[in] to_id specifies the id of the to task.
524 * @param[in] mode specifies the trigger mode.
525 * @param[in] trigger specifies the type of trigger.
526 *
527 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
528 *         error. Otherwise, a status code is returned indicating the
529 *         source of the error.
530 */
531rtems_status_code
532rtems_capture_clear_trigger (rtems_name                 from_name,
533                             rtems_id                   from_id,
534                             rtems_name                 to_name,
535                             rtems_id                   to_id,
536                             rtems_capture_trigger_mode mode,
537                             rtems_capture_trigger      trigger);
538
539/**
540 * @brief Capture read records from capture buffer
541 *
542 * This function reads a number of records from the capture buffer.
543 *
544 * The function returns the number of record that is has that are
545 * in a continous block of memory. If the number of available records
546 * wrap then only those records are provided. This removes the need for
547 * caller to be concerned about buffer wrappings. If the number of
548 * requested records cannot be met due to the wrapping of the records
549 * less than the specified number will be returned.
550 *
551 * The user must release the records. This is achieved with a call to
552 * rtems_capture_release. Calls this function without a release will
553 * result in at least the same number of records being released.
554 *
555 * @param[in]  cpu The cpu number that the records were recorded on
556 * @param[out] read will contain the number of records read
557 * @param[out] recs The capture records that are read.
558 *
559 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
560 *         error. Otherwise, a status code is returned indicating the
561 *         source of the error.
562 */
563rtems_status_code rtems_capture_read (uint32_t     cpu,
564                                      size_t*      read,
565                                      const void** recs);
566
567/**
568 * @brief Capture release records.
569 *
570 * This function releases the requested number of record slots back
571 * to the capture engine. The count must match the number read.
572 *
573 * @param[in] count The number of record slots to release
574 *
575 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
576 *         error. Otherwise, a status code is returned indicating the
577 *         source of the error.
578 */
579rtems_status_code rtems_capture_release (uint32_t cpu, uint32_t count);
580
581/**
582 * @brief Capture filter
583 *
584 * This function this function specifies if the given task and events should be
585 * logged.
586 *
587 * @param[in] task specifies the capture task control block
588 * @param[in] events specifies the events
589 *
590 * @retval This method returns true if this data should be filtered from the
591 *         log. It returns false if this data should be logged.
592 */
593bool rtems_capture_filter (rtems_tcb* task, uint32_t events);
594
595/**
596 * @brief Capture returns the current time.
597 *
598 * This function returns the current time. If a handler is provided
599 * by the user the time is gotten from that.
600 *
601 * @param[in] time specifies the capture time
602 *
603 * @retval This method returns a nano-second time if no user handler
604 * is provided.  Otherwise, it returns a resolution defined by the handler.
605 */
606void rtems_capture_get_time (rtems_capture_time* time);
607
608/**
609 * @brief Capture get event text.
610 *
611 * This function returns a string for an event based on the bit in the
612 * event. The functions takes the bit offset as a number not the bit
613 * set in a bit map.
614 *
615 * @param[in] event specifies the event to describe
616 *
617 * @retval This method returns a string description of the given event.
618 */
619const char* rtems_capture_event_text (int event);
620
621/**
622 * @brief Capture initialize task
623 *
624 * This function initializes capture control in the tcb.
625 *
626 * @param[in] tcb is the task control block for the task
627 */
628void rtems_capture_initialize_task (rtems_tcb* tcb);
629
630/**
631 * @brief Capture record task.
632 *
633 * This function records a new capture task record.
634 *
635 * @param[in] tcb is the task control block for the task
636 */
637void rtems_capture_record_task (rtems_tcb* tcb);
638
639/**
640 * @brief Capture record lock.
641 *
642 * This does a lock acquire which will remain in effect until
643 * rtems_capture_record_unlock is called.
644 *
645 * @param[out] context specifies the record context
646 */
647void rtems_capture_record_lock (rtems_capture_record_lock_context* context);
648
649/**
650 * @brief Capture record unlock.
651 *
652 * This unlocks the record lock.
653 *
654 * @param[in] context specifies the record context
655 */
656void rtems_capture_record_unlock (rtems_capture_record_lock_context* context);
657
658/**
659 * @brief Capture record open.
660 *
661 * This function allocates a record and fills in the header information. It
662 * does a lock acquire which will remain in effect until
663 * rtems_capture_record_close is called. The size is the amount of user data
664 * being recorded. The record header is internally managed.
665 *
666 * @param[in] task specifies the caputre task block
667 * @param[in] events specifies the events
668 * @param[in] size specifies the user's capture data size
669 * @param[out] context specifies the record context
670 *
671 * @retval This method returns a pointer to the next location in
672 * the capture record to store data.
673 */
674void* rtems_capture_record_open (rtems_tcb*                         task,
675                                 uint32_t                           events,
676                                 size_t                             size,
677                                 rtems_capture_record_lock_context* context);
678
679/**
680 * @brief Capture record close.
681 *
682 * This function closes writing to capure record and releases the lock that was
683 * held on the per CPU buffer.
684 *
685 * @param[out] context specifies the record context
686 */
687void rtems_capture_record_close (rtems_capture_record_lock_context* context);
688
689/**
690 * @brief Capture append to record to the per CPU buffer.
691 *
692 * This function appends data of a specifed size into a capture buffer.
693 *
694 * @param[in] rec specifies the next write point in the capture record
695 * @param[in] data specifies the data to write
696 * @param[in] size specifies the size of the data
697 *
698 * @retval This method returns the next write point in the capture record.
699 */
700static inline void*
701rtems_capture_record_append (void* rec, const void* data, size_t size)
702{
703  memcpy (rec, data, size);
704  return ((uint8_t*) rec) + size;
705}
706
707/**
708 * @brief Capture read a record from the per CPU buffer.
709 *
710 * This function reads data of a  specifed size from a capture buffer.
711 *
712 * @param[in] rec specifies the next read point in the capture record
713 * @param[in] data specifies where to write the data
714 * @param[in] size specifies the size of the data
715 *
716 * @retval This method returns the next write point in the capture record.
717 */
718static inline void*
719rtems_capture_record_extract (const void* rec, void* data, size_t size)
720{
721  memcpy (data, rec, size);
722  return ((uint8_t*) rec) + size;
723}
724
725/**
726 * @brief Capture task recorded
727 *
728 * This function returns true if this task information has been
729 * recorded.
730 *
731 * @param[in] tcb is the task control block for the task
732 */
733static inline bool rtems_capture_task_recorded (rtems_tcb* tcb) {
734  return ((tcb->Capture.flags & RTEMS_CAPTURE_RECORD_TASK) != 0);
735}
736
737/**
738 * @brief Capture task initialized
739 *
740 * This function returns true if this task information has been
741 * initialized.
742 *
743 * @param[in] tcb is the task control block for the task
744 */
745static inline bool rtems_capture_task_initialized (rtems_tcb* tcb) {
746  return ((tcb->Capture.flags & RTEMS_CAPTURE_INIT_TASK) != 0);
747}
748
749/**
750 * @brief Capture get task id.
751 *
752 * This function returns the task id.
753 *
754 * @param[in] task The capture task.
755 *
756 * @retval This function returns the task id.
757 */
758static inline rtems_id
759rtems_capture_task_id (rtems_tcb* tcb)
760{
761  return tcb->Object.id;
762}
763
764/**
765 * @brief Capture get task API.
766 *
767 * This function returns the task API as an int.
768 *
769 * @param[in] task The capture task.
770 *
771 * @retval This function returns the task API as an int.
772 */
773static inline int
774rtems_capture_task_api (rtems_id id)
775{
776  return _Objects_Get_API (id);
777}
778
779/**
780 * @brief Capture get task state.
781 *
782 * This function returns the task state.
783 *
784 * @param[in] task The capture task.
785 *
786 * @retval This function returns the task state.
787 */
788static inline States_Control
789rtems_capture_task_state (rtems_tcb* tcb)
790{
791  if (tcb)
792    return tcb->current_state;
793  return 0;
794}
795
796/**
797 * @brief Capture get task name.
798 *
799 * This function returns the task name.
800 *
801 * @param[in] task The capture task.
802 *
803 * @retval This function returns the task name.
804 */
805static inline rtems_name
806rtems_capture_task_name (rtems_tcb* tcb)
807{
808  rtems_name  name;
809  rtems_object_get_classic_name( tcb->Object.id, &name );
810  return name;
811}
812
813/**
814 * @brief Capture get task flags.
815 *
816 * This function returns the task flags.
817 *
818 * @param[in] task The capture task.
819 *
820 * @retval This function returns the task flags.
821 */
822static inline uint32_t
823rtems_capture_task_flags (rtems_tcb* tcb)
824{
825  return tcb->Capture.flags;
826}
827
828/**
829 * @brief Capture get task control
830 *
831 * This function returns the task control if present.
832 *
833 * @param[in] task The capture task.
834 *
835 * @retval This function returns the task control if present.
836 */
837static inline rtems_capture_control*
838rtems_capture_task_control (rtems_tcb* tcb)
839{
840  return tcb->Capture.control;
841}
842
843/**
844 * @brief Capture get task control flags.
845 *
846 * This function returns the task control flags if a control is present.
847 *
848 * @param[in] task The capture task.
849 *
850 * @retval This function returns the task control flags if a control is present.
851 */
852static inline uint32_t
853rtems_capture_task_control_flags (rtems_tcb* tcb)
854{
855  rtems_capture_control*  control = tcb->Capture.control;
856  if (!control)
857    return 0;
858  return control->flags;
859}
860
861/**
862 * @brief Capture get task start priority.
863 *
864 * This function returns the tasks start priority. The tracer needs this
865 * to track where the task's priority goes.
866 *
867 * @param[in] task The capture task.
868 *
869 * @retval This function returns the tasks start priority. The tracer needs this
870 * to track where the task's priority goes.
871 */
872static inline rtems_task_priority
873rtems_capture_task_start_priority (rtems_tcb* tcb)
874{
875  return _RTEMS_Priority_From_core (_Thread_Scheduler_get_home( tcb ),
876                                    tcb->Start.initial_priority);
877}
878
879/**
880 * @brief Capture get task real priority.
881 *
882 * This function returns the tasks real priority.
883 *
884 * @param[in] task The capture task.
885 *
886 * @retval This function returns the tasks real priority.
887 */
888static inline rtems_task_priority
889rtems_capture_task_real_priority (rtems_tcb* tcb)
890{
891  return SCHEDULER_PRIORITY_UNMAP (tcb->Real_priority.priority);
892}
893
894/**
895 * @brief Capture get task current priority.
896 *
897 * This function returns the tasks current priority.
898 *
899 * @param[in] task The capture task.
900 *
901 * @retval This function returns the tasks current priority.
902 */
903static inline rtems_task_priority
904rtems_capture_task_curr_priority (rtems_tcb* tcb)
905{
906  return SCHEDULER_PRIORITY_UNMAP (_Thread_Get_priority (tcb));
907}
908
909/**
910 * @brief Capture get control list.
911 *
912 * This function returns the head of the list of controls in the
913 * capture engine.
914 *
915 * @retval This function returns the head of the list of controls in the
916 * capture engine.
917 */
918rtems_capture_control*
919rtems_capture_get_control_list (void);
920
921/**
922 * @brief Capture get next capture control.
923 *
924 * This function returns the pointer to the next control in the list. The
925 * pointer NULL terminates the list.
926 *
927 * @param[in] control the current capture control.
928 *
929 * @retval This function returns the pointer to the next control in the list. The
930 * pointer NULL terminates the list.
931 */
932static inline rtems_capture_control*
933rtems_capture_next_control (rtems_capture_control* control)
934{
935  return control->next;
936}
937
938/**
939 * @brief Capture get capture control id.
940 *
941 * This function returns the control id.
942 *
943 * @param[in] control the capture control.
944 *
945 * @retval This function returns the control id.
946 */
947static inline rtems_id
948rtems_capture_control_id (rtems_capture_control* control)
949{
950  return control->id;
951}
952
953/**
954 * @brief Capture get capture control name.
955 *
956 * This function returns the control name.
957 *
958 * @param[in] control the capture control.
959 *
960 * @retval This function returns the control name.
961 */
962static inline rtems_name
963rtems_capture_control_name (rtems_capture_control* control)
964{
965  return control->name;
966}
967
968/**
969 * @brief Capture get capture control flags.
970 *
971 * This function returns the control flags.
972 *
973 * @param[in] control the capture control.
974 *
975 * @retval This function returns the control flags.
976 */
977static inline uint32_t
978rtems_capture_control_flags (rtems_capture_control* control)
979{
980  return control->flags;
981}
982
983/**
984 * @brief Capture get capture control to triggers.
985 *
986 * This function returns the task control to triggers.
987 *
988 * @param[in] control the capture control.
989 *
990 * @retval This function returns the task control to triggers.
991 */
992static inline uint32_t
993rtems_capture_control_to_triggers (rtems_capture_control* control)
994{
995  return control->to_triggers;
996}
997
998/**
999 * @brief Capture get capture control from triggers.
1000 *
1001 * This function returns the task control from triggers.
1002 *
1003 * @param[in] control the capture control.
1004 *
1005 * @retval This function returns the task control from triggers.
1006 */
1007static inline uint32_t
1008rtems_capture_control_from_triggers (rtems_capture_control* control)
1009{
1010  return control->from_triggers;
1011}
1012
1013/**
1014 * @brief Capture get capture control by triggers.
1015 *
1016 * This function returns the task control by triggers.
1017 *
1018 * @param[in] control the capture control.
1019 *
1020 * @retval This function returns the task control by triggers.
1021 */
1022static inline uint32_t
1023rtems_capture_control_all_by_triggers (rtems_capture_control* control)
1024{
1025  return control->by_triggers;
1026}
1027
1028/**
1029 * @brief Capture get capture control valid by flags.
1030 *
1031 * This function returns the control valid BY flags.
1032 *
1033 * @param[in] control The capture control.
1034 * @param[in] slot The slot.
1035 *
1036 * @retval This function returns the control valid BY flags.
1037 */
1038static inline int
1039rtems_capture_control_by_valid (rtems_capture_control* control, int slot)
1040{
1041  return control->by_valid & RTEMS_CAPTURE_CONTROL_FROM_MASK (slot);
1042}
1043
1044/**
1045 * @brief Capture get capture control by task name.
1046 *
1047 * This function returns the control @a by task name.
1048 *
1049 * @param[in] control The capture control.
1050 * @param[in] by The by index.
1051 *
1052 * @retval This function returns the control @a by task name.
1053 */
1054static inline rtems_name
1055rtems_capture_control_by_name (rtems_capture_control* control, int by)
1056{
1057  if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
1058    return control->by[by].name;
1059  return control->by[0].name;
1060}
1061
1062/**
1063 * @brief Capture get capture control by task id.
1064 *
1065 * This function returns the control @a by task id
1066 *
1067 * @retval This function returns the control @a by task id.
1068 */
1069static inline rtems_id
1070rtems_capture_control_by_id (rtems_capture_control* control, int by)
1071{
1072  if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
1073    return control->by[by].id;
1074  return control->by[0].id;
1075}
1076
1077/**
1078 * @brief Capture get capture control by task triggers.
1079 *
1080 * This function returns the control @a by task triggers.
1081 *
1082 * @retval This function returns the control @a by task triggers.
1083 */
1084static inline uint32_t
1085rtems_capture_control_by_triggers (rtems_capture_control* control,
1086                                   int                      by)
1087{
1088  if (by < RTEMS_CAPTURE_TRIGGER_TASKS)
1089    return control->by[by].trigger;
1090  return control->by[0].trigger;
1091}
1092
1093/**
1094 * @brief Capture get capture control count.
1095 *
1096 * This function returns the number of controls the capture
1097 * engine has.
1098 *
1099 * @retval This function returns the number of controls the capture
1100 * engine has.
1101 */
1102static inline uint32_t
1103rtems_capture_control_count (void)
1104{
1105  rtems_capture_control* control = rtems_capture_get_control_list ();
1106  uint32_t               count = 0;
1107
1108  while (control)
1109  {
1110    count++;
1111    control = rtems_capture_next_control (control);
1112  }
1113
1114  return count;
1115}
1116
1117#ifdef __cplusplus
1118}
1119#endif
1120/**@}*/
1121
1122#endif
Note: See TracBrowser for help on using the repository browser.