source: rtems/cpukit/libmisc/capture/capture.h @ a29d2e7

4.104.114.84.95
Last change on this file since a29d2e7 was cbd7691, checked in by Ralf Corsepius <ralf.corsepius@…>, on Dec 2, 2004 at 6:20:51 PM

2004-12-02 Ralf Corsepius <ralf.corsepius@…>

  • libmisc/capture/capture-cli.h, libmisc/capture/capture.h, libmisc/monitor/monitor.h, libmisc/rtmonuse/rtmonuse.h, libmisc/shell/shell.h: Partial doxygenification.
  • libmisc/capture/capture.h: Use INT32_C for constants.
  • Property mode set to 100644
File size: 19.7 KB
Line 
1/**
2 * @file rtems/capture.h
3 */
4 
5/*
6  ------------------------------------------------------------------------
7  $Id$
8  ------------------------------------------------------------------------
9
10  Copyright Objective Design Systems Pty Ltd, 2002
11  All rights reserved Objective Design Systems Pty Ltd, 2002
12  Chris Johns (ccj@acm.org)
13
14  COPYRIGHT (c) 1989-1998.
15  On-Line Applications Research Corporation (OAR).
16
17  The license and distribution terms for this file may be
18  found in the file LICENSE in this distribution.
19
20  This software with is provided ``as is'' and with NO WARRANTY.
21
22  ------------------------------------------------------------------------
23
24  RTEMS Performance Monitoring and Measurement Framework.
25
26  This is the Capture Engine component.
27
28*/
29
30#ifndef __CAPTURE_H_
31#define __CAPTURE_H_
32
33#ifdef __cplusplus
34extern "C" {
35#endif
36
37#include <rtems.h>
38
39/**
40 * The number of tasks in a trigger group.
41 */
42#define RTEMS_CAPTURE_TRIGGER_TASKS (32)
43
44/**
45 * rtems_capture_control_t
46 *
47 *  DESCRIPTION:
48 *
49 * RTEMS control holds the trigger and watch configuration for a group of
50 * tasks with the same name.
51 */
52typedef struct rtems_capture_control_s
53{
54  rtems_name                      name;
55  rtems_id                        id;
56  uint32_t                  flags;
57  rtems_name                      from[RTEMS_CAPTURE_TRIGGER_TASKS];
58  rtems_id                        from_id[RTEMS_CAPTURE_TRIGGER_TASKS];
59  struct rtems_capture_control_s* next;
60} rtems_capture_control_t;
61
62/**
63 * Control flags.
64 */
65#define RTEMS_CAPTURE_WATCH         (1 << 0)
66#define RTEMS_CAPTURE_FROM_ANY      (1 << 1)
67#define RTEMS_CAPTURE_TO_ANY        (1 << 2)
68#define RTEMS_CAPTURE_FROM_TO       (1 << 3)
69
70/**
71 * rtems_capture_control_t
72 *
73 *  DESCRIPTION:
74 *
75 * RTEMS capture control provdes the information about a task, along
76 * with its trigger state. The control is referenced by each
77 * capture record. This is* information neeed by the decoder. The
78 * capture record cannot assume the task will exist when the record is
79 * dumped via the target interface so task info needed for tracing is
80 * copied and held here.
81 *
82 * The inline heper functions provide more details about the info
83 * contained in this structure.
84 *
85 * Note, the tracer code exploits the fact an rtems_name is a
86 * 32bit value.
87 */
88typedef struct rtems_capture_task_s
89{
90  rtems_name                   name;
91  rtems_id                     id;
92  uint32_t               flags;
93  rtems_tcb*                   tcb;
94  uint32_t               in;
95  uint32_t               out;
96  rtems_task_priority          start_priority;
97  uint32_t               stack_size;
98  uint32_t               stack_clean;
99  uint32_t               ticks;
100  uint32_t               tick_offset;
101  uint32_t               ticks_in;
102  uint32_t               tick_offset_in;
103  uint32_t               last_ticks;
104  uint32_t               last_tick_offset;
105  rtems_capture_control_t*     control;
106  struct rtems_capture_task_s* next;
107} rtems_capture_task_t;
108
109/**
110 * Task flags.
111 */
112#define RTEMS_CAPTURE_TRACED  (1 << 0)
113
114/*
115 * rtems_capture_record_t
116 *
117 *  DESCRIPTION:
118 *
119 * RTEMS capture record. This is a record that is written into
120 * the buffer. The events includes the priority of the task
121 * at the time of the context switch.
122 */
123typedef struct rtems_capture_record_s
124{
125  rtems_capture_task_t* task;
126  uint32_t        events;
127  uint32_t        ticks;
128  uint32_t        tick_offset;
129} rtems_capture_record_t;
130
131/**
132 * The capture record event flags.
133 */
134#define RTEMS_CAPTURE_REAL_PRI_EVENT_MASK UINT32_C(0x000000ff)
135#define RTEMS_CAPTURE_CURR_PRI_EVENT_MASK UINT32_C(0x0000ff00)
136#define RTEMS_CAPTURE_REAL_PRIORITY_EVENT (0)
137#define RTEMS_CAPTURE_CURR_PRIORITY_EVENT (8)
138#define RTEMS_CAPTURE_EVENT_START         (16)
139#define RTEMS_CAPTURE_CREATED_BY_EVENT    UINT32_C(0x00010000)
140#define RTEMS_CAPTURE_CREATED_EVENT       UINT32_C(0x00020000)
141#define RTEMS_CAPTURE_STARTED_BY_EVENT    UINT32_C(0x00040000)
142#define RTEMS_CAPTURE_STARTED_EVENT       UINT32_C(0x00080000)
143#define RTEMS_CAPTURE_RESTARTED_BY_EVENT  UINT32_C(0x00100000)
144#define RTEMS_CAPTURE_RESTARTED_EVENT     UINT32_C(0x00200000)
145#define RTEMS_CAPTURE_DELETED_BY_EVENT    UINT32_C(0x00400000)
146#define RTEMS_CAPTURE_DELETED_EVENT       UINT32_C(0x00800000)
147#define RTEMS_CAPTURE_BEGIN_EVENT         UINT32_C(0x01000000)
148#define RTEMS_CAPTURE_EXITTED_EVENT       UINT32_C(0x02000000)
149#define RTEMS_CAPTURE_SWITCHED_OUT_EVENT  UINT32_C(0x04000000)
150#define RTEMS_CAPTURE_SWITCHED_IN_EVENT   UINT32_C(0x08000000)
151#define RTEMS_CAPTURE_TIMESTAMP           UINT32_C(0x10000000)
152#define RTEMS_CAPTURE_EVENT_END           (28)
153
154/**
155 * rtems_capture_trigger_t
156 *
157 *  DESCRIPTION:
158 *
159 * The types of triggers that exist. FIXME: add more here.
160 */
161typedef enum rtems_capture_trigger_t
162{
163  rtems_capture_to_any,
164  rtems_capture_from_any,
165  rtems_capture_from_to
166} rtems_capture_trigger_t;
167
168/**
169 * rtems_capture_timestamp
170 *
171 *  DESCRIPTION:
172 *
173 * This defines the callout handler to obtain a time stamp. The
174 * value returned is time count since the last read.
175 *
176 */
177
178typedef void (*rtems_capture_timestamp)
179                (uint32_t  * ticks, uint32_t  * micro);
180
181/**
182 * rtems_capture_open
183 *
184 *  DESCRIPTION:
185 *
186 * This function initialises the realtime trace manager allocating the capture
187 * buffer. It is assumed we have a working heap at stage of initialisation.
188 *
189 */
190rtems_status_code
191rtems_capture_open (uint32_t          size,
192                    rtems_capture_timestamp timestamp);
193
194/**
195 * rtems_capture_close
196 *
197 *  DESCRIPTION:
198 *
199 * This function shutdowns the tracer and release any claimed
200 * resources.
201 */
202rtems_status_code
203rtems_capture_close ();
204
205/**
206 * rtems_capture_control
207 *
208 *  DESCRIPTION:
209 *
210 * This function allows control of tracing at a global level.
211 */
212rtems_status_code
213rtems_capture_control (rtems_boolean enable);
214
215/*
216 * rtems_capture_flush
217 *
218 *  DESCRIPTION:
219 *
220 * This function flushes the trace buffer. The prime parameter allows the
221 * capture engine to also be primed again.
222 */
223rtems_status_code
224rtems_capture_flush (rtems_boolean prime);
225
226/**
227 * rtems_capture_watch_add
228 *
229 *  DESCRIPTION:
230 *
231 * This function defines a watch for a specific task given a name. A watch
232 * causes it to be traced either in or out of context. The watch can be
233 * optionally enabled or disabled with the set routine. It is disabled by
234 * default.
235 */
236rtems_status_code
237rtems_capture_watch_add (rtems_name name, rtems_id id);
238
239/**
240 * rtems_capture_watch_del
241 *
242 *  DESCRIPTION:
243 *
244 * This function removes a watch for a specific task given a name. The task
245 * description will still exist if referenced by a trace record in the trace
246 * buffer or a global watch is defined.
247 */
248rtems_status_code
249rtems_capture_watch_del (rtems_name name, rtems_id id);
250
251/**
252 * rtems_capture_watch_set
253 *
254 *  DESCRIPTION:
255 *
256 * This function allows control of a watch. The watch can be enabled or
257 * disabled.
258 */
259rtems_status_code
260rtems_capture_watch_ctrl (rtems_name name, rtems_id id, rtems_boolean enable);
261
262/**
263 * rtems_capture_watch_global
264 *
265 *  DESCRIPTION:
266 *
267 * This function allows control of a global watch. The watch can be enabled or
268 * disabled. A global watch configures all tasks below the ceiling and above
269 * the floor to be traced.
270 */
271rtems_status_code
272rtems_capture_watch_global (rtems_boolean enable);
273
274/**
275 * rtems_capture_watch_global_on
276 *
277 *  DESCRIPTION:
278 *
279 * This function returns the global watch state.
280 */
281rtems_boolean
282rtems_capture_watch_global_on ();
283
284/**
285 * rtems_capture_watch_ceiling
286 *
287 *  DESCRIPTION:
288 *
289 * This function sets a watch ceiling. Tasks at or greating that the
290 * ceiling priority are not watched. This is a simple way to monitor
291 * an application and exclude system tasks running at a higher
292 * priority level.
293 */
294rtems_status_code
295rtems_capture_watch_ceiling (rtems_task_priority ceiling);
296
297/**
298 * rtems_capture_watch_get_ceiling
299 *
300 *  DESCRIPTION:
301 *
302 * This function gets the watch ceiling.
303 */
304rtems_task_priority
305rtems_capture_watch_get_ceiling ();
306
307/**
308 * rtems_capture_watch_floor
309 *
310 *  DESCRIPTION:
311 *
312 * This function sets a watch floor. Tasks at or less that the
313 * floor priority are not watched. This is a simple way to monitor
314 * an application and exclude system tasks running at a lower
315 * priority level.
316 */
317rtems_status_code
318rtems_capture_watch_floor (rtems_task_priority floor);
319
320/**
321 * rtems_capture_watch_get_floor
322 *
323 *  DESCRIPTION:
324 *
325 * This function gets the watch floor.
326 */
327rtems_task_priority
328rtems_capture_watch_get_floor ();
329
330/**
331 * rtems_capture_set_trigger
332 *
333 *  DESCRIPTION:
334 *
335 * This function sets an edge trigger. Left is the left side of
336 * the edge and right is right side of the edge. The trigger type
337 * can be -
338 *
339 *  FROM_ANY : a switch from any task to the right side of the edge.
340 *  TO_ANY   : a switch from the left side of the edge to any task.
341 *  FROM_TO  : a switch from the left side of the edge to the right
342 *             side of the edge.
343 *
344 * This set trigger routine will create a trace control for the
345 * target task. The task list is searched and any existing tasks
346 * are linked to the new control.
347 *
348 * We can have a number of tasks that have the same name so we
349 * search using names. This means a number of tasks can be
350 * linked to single control.
351 */
352rtems_status_code
353rtems_capture_set_trigger (rtems_name              from,
354                           rtems_id                from_id,
355                           rtems_name              to,
356                           rtems_id                to_id,
357                           rtems_capture_trigger_t trigger);
358
359/**
360 * rtems_capture_read
361 *
362 *  DESCRIPTION:
363 *
364 * This function reads a number of records from the capture buffer.
365 * The user can optionally block and wait until the buffer as a
366 * specific number of records available or a specific time has
367 * elasped.
368 *
369 * The function returns the number of record that is has that are
370 * in a continous block of memory. If the number of available records
371 * wrap then only those records are provided. This removes the need for
372 * caller to be concerned about buffer wrappings. If the number of
373 * requested records cannot be met due to the wrapping of the records
374 * less than the specified number will be returned.
375 *
376 * The user must release the records. This is achieved with a call to
377 * rtems_capture_release. Calls this function without a release will
378 * result in at least the same number of records being released.
379 *
380 * The 'threshold' parameter is the number of records that must be
381 * captured before returning. If a timeout period is specified (non-0)
382 * any captured records will be returned. These parameters stop
383 * thrashing occuring for a small number of records, yet allows
384 * a user configured latiency to be applied for single events.
385 *
386 * The 'timeout' parameter is in micro-seconds. A value of 0 will disable
387 * the timeout.
388 *
389 */
390rtems_status_code
391rtems_capture_read (uint32_t           threshold,
392                    uint32_t           timeout,
393                    uint32_t  *        read,
394                    rtems_capture_record_t** recs);
395
396/**
397 * rtems_capture_release
398 *
399 *  DESCRIPTION:
400 *
401 * This function releases the requested number of record slots back
402 * to the capture engine. The count must match the number read.
403 */
404rtems_status_code
405rtems_capture_release (uint32_t   count);
406
407/**
408 * rtems_capture_tick_time
409 *
410 *  DESCRIPTION:
411 *
412 * This function returns the tick period in micro-seconds.
413 */
414uint32_t
415rtems_capture_tick_time ();
416
417/*
418 * rtems_capture_tick_time
419 *
420 *  DESCRIPTION:
421 *
422 * This function returns the tick period in micro-seconds.
423 */
424uint32_t
425rtems_capture_tick_time ();
426
427/**
428 * rtems_capture_event_text
429 *
430 *  DESCRIPTION:
431 *
432 * This function returns a string for an event based on the bit in the
433 * event. The functions takes the bit offset as a number not the bit
434 * set in a bit map.
435 */
436const char*
437rtems_capture_event_text (int event);
438
439/**
440 * rtems_capture_get_task_list
441 *
442 *  DESCRIPTION:
443 *
444 * This function returns the head of the list of tasks that the
445 * capture engine has detected.
446 */
447rtems_capture_task_t*
448rtems_capture_get_task_list ();
449
450/**
451 * rtems_capture_next_task
452 *
453 *  DESCRIPTION:
454 *
455 * This function returns the pointer to the next task in the list. The
456 * pointer NULL terminates the list.
457 */
458static inline rtems_capture_task_t*
459rtems_capture_next_task (rtems_capture_task_t* task)
460{
461  return task->next;
462}
463
464/**
465 * rtems_capture_task_valid
466 *
467 *  DESCRIPTION:
468 *
469 * This function returns true if the task control block points to
470 * a valid task.
471 */
472static inline rtems_boolean
473rtems_capture_task_valid (rtems_capture_task_t* task)
474{
475  return task->tcb != NULL;
476}
477
478/**
479 * rtems_capture_task_id
480 *
481 *  DESCRIPTION:
482 *
483 * This function returns the task id.
484 */
485static inline rtems_id
486rtems_capture_task_id (rtems_capture_task_t* task)
487{
488  return task->id;
489}
490
491/**
492 * rtems_capture_task_state
493 *
494 *  DESCRIPTION:
495 *
496 * This function returns the task state.
497 */
498static inline States_Control
499rtems_capture_task_state (rtems_capture_task_t* task)
500{
501  if (rtems_capture_task_valid (task))
502    return task->tcb->current_state;
503  return 0;
504}
505
506/**
507 * rtems_capture_task_name
508 *
509 *  DESCRIPTION:
510 *
511 * This function returns the task name.
512 */
513static inline rtems_name
514rtems_capture_task_name (rtems_capture_task_t* task)
515{
516  return task->name;
517}
518
519/**
520 * rtems_capture_task_flags
521 *
522 *  DESCRIPTION:
523 *
524 * This function returns the task flags.
525 */
526static inline uint32_t
527rtems_capture_task_flags (rtems_capture_task_t* task)
528{
529  return task->flags;
530}
531
532/**
533 * rtems_capture_task_control
534 *
535 *  DESCRIPTION:
536 *
537 * This function returns the task control if present.
538 */
539static inline rtems_capture_control_t*
540rtems_capture_task_control (rtems_capture_task_t* task)
541{
542  return task->control;
543}
544
545/**
546 * rtems_capture_task_control_flags
547 *
548 *  DESCRIPTION:
549 *
550 * This function returns the task control flags if a control is present.
551 */
552static inline uint32_t
553rtems_capture_task_control_flags (rtems_capture_task_t* task)
554{
555  if (!task->control)
556    return 0;
557  return task->control->flags;
558}
559
560/**
561 * rtems_capture_task_switched_in
562 *
563 *  DESCRIPTION:
564 *
565 * This function returns the number of times the task has
566 * been switched into context.
567 */
568static inline uint32_t
569rtems_capture_task_switched_in (rtems_capture_task_t* task)
570{
571  return task->in;
572}
573
574/**
575 * rtems_capture_task_switched_out
576 *
577 *  DESCRIPTION:
578 *
579 * This function returns the number of times the task has
580 * been switched out of context.
581 */
582static inline uint32_t
583rtems_capture_task_switched_out (rtems_capture_task_t* task)
584{
585  return task->out;
586}
587
588/**
589 * rtems_capture_task_curr_priority
590 *
591 *  DESCRIPTION:
592 *
593 * This function returns the tasks start priority. The tracer needs this
594 * to track where the task's priority goes.
595 */
596static inline rtems_task_priority
597rtems_capture_task_start_priority (rtems_capture_task_t* task)
598{
599  return task->start_priority;
600}
601
602/**
603 * rtems_capture_task_real_priority
604 *
605 *  DESCRIPTION:
606 *
607 * This function returns the tasks real priority.
608 */
609static inline rtems_task_priority
610rtems_capture_task_real_priority (rtems_capture_task_t* task)
611{
612  if (rtems_capture_task_valid (task))
613    return task->tcb->real_priority;
614  return 0;
615}
616
617/**
618 * rtems_capture_task_curr_priority
619 *
620 *  DESCRIPTION:
621 *
622 * This function returns the tasks current priority.
623 */
624static inline rtems_task_priority
625rtems_capture_task_curr_priority (rtems_capture_task_t* task)
626{
627  if (rtems_capture_task_valid (task))
628    return task->tcb->current_priority;
629  return 0;
630}
631
632/**
633 * rtems_capture_task_stack_usage
634 *
635 *  DESCRIPTION:
636 *
637 * This function updates the stack usage. The task control block
638 * is updated.
639 */
640uint32_t
641rtems_capture_task_stack_usage (rtems_capture_task_t* task);
642
643/**
644 * rtems_capture_task_stack_size
645 *
646 *  DESCRIPTION:
647 *
648 * This function returns the task's stack size.
649 */
650static inline uint32_t
651rtems_capture_task_stack_size (rtems_capture_task_t* task)
652{
653  return task->stack_size;
654}
655
656/**
657 * rtems_capture_task_stack_used
658 *
659 *  DESCRIPTION:
660 *
661 * This function returns the amount of stack used.
662 */
663static inline uint32_t
664rtems_capture_task_stack_used (rtems_capture_task_t* task)
665{
666  return task->stack_size - task->stack_clean;
667}
668
669/**
670 * rtems_capture_task_ticks
671 *
672 *  DESCRIPTION:
673 *
674 * This function returns the current execution time as ticks.
675 */
676static inline uint32_t
677rtems_capture_task_ticks (rtems_capture_task_t* task)
678{
679  return task->ticks;
680}
681
682/**
683 * rtems_capture_task_tick_offset
684 *
685 *  DESCRIPTION:
686 *
687 * This function returns the current execution time tick offset.
688 */
689static inline uint32_t
690rtems_capture_task_tick_offset (rtems_capture_task_t* task)
691{
692  return task->tick_offset;
693}
694
695/**
696 * rtems_capture_task_time
697 *
698 *  DESCRIPTION:
699 *
700 * This function returns the current execution time.
701 */
702static inline unsigned long long
703rtems_capture_task_time (rtems_capture_task_t* task)
704{
705  unsigned long long t = task->ticks;
706  return (t * rtems_capture_tick_time ()) + task->tick_offset;;
707}
708
709/**
710 * rtems_capture_task_delta_time
711 *
712 *  DESCRIPTION:
713 *
714 * This function returns the execution time as a different between the
715 * last time the detla time was and now.
716 */
717static inline unsigned long long
718rtems_capture_task_delta_time (rtems_capture_task_t* task)
719{
720  unsigned long long t = task->ticks - task->last_ticks;
721  uint32_t     o = task->tick_offset - task->last_tick_offset;
722
723  task->last_ticks       = task->ticks;
724  task->last_tick_offset = task->tick_offset;
725
726  return (t * rtems_capture_tick_time ()) + o;
727}
728
729/**
730 * rtems_capture_task_count
731 *
732 *  DESCRIPTION:
733 *
734 * This function returns the number of tasks the capture
735 * engine knows about.
736 */
737static inline uint32_t
738rtems_capture_task_count ()
739{
740  rtems_capture_task_t* task = rtems_capture_get_task_list ();
741  uint32_t        count = 0;
742
743  while (task)
744  {
745    count++;
746    task = rtems_capture_next_task (task);
747  }
748
749  return count;
750}
751
752/**
753 * rtems_capture_get_control_list
754 *
755 *  DESCRIPTION:
756 *
757 * This function returns the head of the list of controls in the
758 * capture engine.
759 */
760rtems_capture_control_t*
761rtems_capture_get_control_list ();
762
763/**
764 * rtems_capture_next_control
765 *
766 *  DESCRIPTION:
767 *
768 * This function returns the pointer to the next control in the list. The
769 * pointer NULL terminates the list.
770 */
771static inline rtems_capture_control_t*
772rtems_capture_next_control (rtems_capture_control_t* control)
773{
774  return control->next;
775}
776
777/**
778 * rtems_capture_control_id
779 *
780 *  DESCRIPTION:
781 *
782 * This function returns the control id.
783 */
784static inline rtems_id
785rtems_capture_control_id (rtems_capture_control_t* control)
786{
787  return control->id;
788}
789
790/**
791 * rtems_capture_control_name
792 *
793 *  DESCRIPTION:
794 *
795 * This function returns the control name.
796 */
797static inline rtems_name
798rtems_capture_control_name (rtems_capture_control_t* control)
799{
800  return control->name;
801}
802
803/**
804 * rtems_capture_control_flags
805 *
806 *  DESCRIPTION:
807 *
808 * This function returns the control flags.
809 */
810static inline uint32_t
811rtems_capture_control_flags (rtems_capture_control_t* control)
812{
813  return control->flags;
814}
815
816/**
817 * rtems_capture_control_from_name
818 *
819 *  DESCRIPTION:
820 *
821 * This function returns the control from task name.
822 */
823static inline rtems_name
824rtems_capture_control_from_name (rtems_capture_control_t* control, int from)
825{
826  if (from < RTEMS_CAPTURE_TRIGGER_TASKS)
827    return control->from[from];
828  return control->from[0];
829}
830
831/**
832 * rtems_capture_control_from_id
833 *
834 *  DESCRIPTION:
835 *
836 * This function returns the control from task id.
837 */
838static inline rtems_id
839rtems_capture_control_from_id (rtems_capture_control_t* control, int from)
840{
841  if (from < RTEMS_CAPTURE_TRIGGER_TASKS)
842    return control->from_id[from];
843  return control->from_id[0];
844}
845
846/**
847 * rtems_capture_control_count
848 *
849 *  DESCRIPTION:
850 *
851 * This function returns the number of controls the capture
852 * engine has.
853 */
854static inline uint32_t
855rtems_capture_control_count ()
856{
857  rtems_capture_control_t* control = rtems_capture_get_control_list ();
858  uint32_t           count = 0;
859
860  while (control)
861  {
862    count++;
863    control = rtems_capture_next_control (control);
864  }
865
866  return count;
867}
868
869#ifdef __cplusplus
870}
871#endif
872
873#endif
Note: See TracBrowser for help on using the repository browser.