source: rtems-docs/user/tracing/captureengine.rst @ 8f4f80d

5
Last change on this file since 8f4f80d was 8f4f80d, checked in by Vidushi Vashishth <reachvidu@…>, on 06/14/18 at 14:17:58

Adding Trace Documentation

  • Updates #3454
  • This commit adds Tracing Framework Chapter in the RTEMS User Manual
  • It comprises of subchapters on RTEMS Trace Linker, Capture Engine, Trace generation techniques explaining trace generation using Trace Buffering and Printk generators and sample demonstrations.
  • Property mode set to 100644
File size: 7.3 KB
Line 
1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. comment: Copyright (c) 2018 Vidushi Vashishth <vidushivashishth96@gmail.com>
4.. comment: All rights reserved.
5
6.. _capturengine:
7
8Capture Engine
9**************
10
11Capture Engine is a trace tool built inside the RTEMS operating system. Capture
12Engine is designed to cause the lowest load on the system when operating. Hence
13it does not effect RTEMS when operating or when disabled. It binds to RTEMS at
14runtime and does not require RTEMS or your application to be rebuilt in order
15to use it.
16
17The Capture Engine's sample testcase for the `sparc/erc32` is available in
18build directory created when building RTEMS in the path
19file: `sparc-rtems5/c/erc32/testsuites/samples`. In order to access the capture
20testcase perform the following set of operations inside the RTEMS build
21directory.
22
23.. code-block:: shell
24
25  $ cd /sparc-rtems5/c/erc32/testsuites/samples
26  $ sparc-rtems5-run ./capture.exe
27
28
29  *** BEGIN OF TEST CAPTURE ENGINE ***
30  *** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8
31  *** TEST STATE: USER_INPUT
32  *** TEST BUILD: RTEMS_NETWORKING RTEMS_POSIX_API
33  *** TEST TOOLS: 7.3.0 20180125 (RTEMS 5, RSB a3a6c34c150a357e57769a26a460c475e188438f, Newlib 3.0.0)
34  Press any key to start capture engine (20s remaining)
35  Press any key to start capture engine (19s remaining)
36  Press any key to start capture engine (18s remaining)
37
38  Monitor ready, press enter to login.
39
40  1-rtems $
41
42Capture Engine comes with a set of commands to perform various actions.
43
44Capture Engine Commands
45-----------------------
46
471) ``copen <buffer-size>``: Used to initialize the Capture Engine with the
48   trace buffer size in bytes. By default the Capture Engine is not initialized
49   and not running.
50
512) ``cwceil <priority-value>``: Capture Engine filter used to put an upper
52   limit on the event priority to be captured.
53
543) ``cwfloor <priority-value>``: Capture Engine filter used to put a lower
55   limit on the event priority to be captured.
56
574) ``cwglob <on/off>``: Enable or disable the global watch.
58
595) ``cenable``: Enables the Capture Engine. Capture Engine is by default
60   disabled after being opened.
61
626) ``cdisable``: Disables the Capture Engine.
63
647) ``ctlist``: Lists the watch and trigger configurations.
65
668) ``ctrace``: Dumps the recorded traces. By default this command displays 24
67   trace records. Repeated use of this command will display all the recorded
68   traces.
69
709) ``cwadd <task-name>``: Add watch on a particular task.
71
7210) ``cwtctl <task-name> <on/off>``: Enable or disable watch on a particular
73    task.
74
7511) ``ctset``: Used to set a trigger. The general form of the command is:
76
77``ctset [-?] type [to name/id] [from] [from name/id]``
78
79`type` in the above command refers to the type of trigger needed. The types of
80triggers that currently exist are:
81
82- switch  : a context switch from one task to another task
83- create  : the executing task creates a task
84- start   : the executing task starts a task
85- restart : the executing task restarts a task
86- delete  : the executing task deletes a task
87- begin   : a task is beginning
88- exitted : a task is exitting
89
90Example
91-------
92
93The following is a sample run of the capture testsuite. The `test1` command on
94the Capture Engine Command Line Interface (CLI) makes the `RMON` task invoke a
95call to the `capture_test_1()` command. This function (in the `test1.c` source
96code) creates and starts three tasks : `CT1a`, `CT1b` and `CT1c`. These tasks
97are passed the object id of a semaphore as a task argument. This run through
98traces the context switches between these tasks. ``cwceil`` and ``cwfloor`` are
99set to a narrow range of task priorities to avoid creating noise from a large
100number of context switches between tasks we are not interested in.
101
102.. code:: shell
103
104  *** BEGIN OF TEST CAPTURE ENGINE ***
105  *** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8
106  *** TEST STATE: USER_INPUT
107  *** TEST BUILD: RTEMS_NETWORKING RTEMS_POSIX_API
108  *** TEST TOOLS: 7.3.0 20180125 (RTEMS 5, RSB a3a6c34c150a357e57769a26a460c475e188438f, Newlib 3.0.0)
109  Press any key to start capture engine (20s remaining)
110  Press any key to start capture engine (19s remaining)
111  Press any key to start capture engine (18s remaining)
112  Press any key to start capture engine (17s remaining)
113
114  Monitor ready, press enter to login.
115
116  1-rtems $ copen 50000
117  capture engine opened.
118  1-rtems $ cwceil 100
119  watch ceiling is 100.
120  1-rtems $ cwfloor 102
121  watch floor is 102.
122  1-rtems $ cwglob on
123  global watch enabled.
124  1-rtems $ ctset RMON
125  trigger set.
126  1-rtems $ cenable
127  capture engine enabled.
128  1-rtems $ test1
129  1-rtems $ cdisable
130  capture engine disabled.
131  1-rtems $ ctrace
132  0 0:18:17.462314124           0a010003 CT1a 102 102 102   4096  TASK_RECORD
133  0 0:18:17.462398963         0 0a010003 CT1a 102 102             CREATED
134  0 0:18:17.462647987    249024 0a010003 CT1a 102 102             STARTED
135  0 0:18:17.462904334    256347 0a010003 CT1a 102 102             SWITCHED_IN
136  0 0:18:17.463069129    164795 0a010003 CT1a 102 102             BEGIN
137  0 0:18:17.463335853    266724 0a010003 CT1a 102 102             SWITCHED_OUT
138  0 0:18:18.461348547           0a010004 CT1b 101 101 101   4096  TASK_RECORD
139  0 0:18:18.461433997 998098144 0a010004 CT1b 101 101             CREATED
140  0 0:18:18.461683631    249634 0a010004 CT1b 101 101             STARTED
141  0 0:18:18.461934485    250854 0a010004 CT1b 101 101             SWITCHED_IN
142  0 0:18:18.462099891    165406 0a010004 CT1b 101 101             BEGIN
143  0 0:18:19.460935339 998835448 0a010004 CT1b 101 101             SWITCHED_OUT
144  0 0:18:19.461431555           0a010005 CT1c 100 100 100   4096  TASK_RECORD
145  0 0:18:19.461516394    581055 0a010005 CT1c 100 100             CREATED
146  0 0:18:19.461765418    249024 0a010005 CT1c 100 100             STARTED
147  0 0:18:19.462019324    253906 0a010005 CT1c 100 100             SWITCHED_IN
148  0 0:18:19.462184119    164795 0a010005 CT1c 100 100             BEGIN
149  0 0:18:19.462475257    291138 0a010005 CT1c 100 100             SWITCHED_OUT
150  0 0:18:19.462551551     76294 0a010004 CT1b 101 101             SWITCHED_IN
151  0 0:18:19.960935645 498384094 0a010004 CT1b 101 101             SWITCHED_OUT
152  0 0:18:19.961012549     76904 0a010003 CT1a 102 100             SWITCHED_IN
153  0 0:18:19.961341528    328979 0a010003 CT1a 102 102             SWITCHED_OUT
154  1-rtems $ ctrace
155  0 0:18:19.961418433         0 0a010005 CT1c 100 100             SWITCHED_IN
156  0 0:18:19.961672339    253906 0a010005 CT1c 100 100             SWITCHED_OUT
157  0 0:18:19.961749854     77515 0a010004 CT1b 101 101             SWITCHED_IN
158  0 0:18:20.460967077 499217223 0a010004 CT1b 101 101             SWITCHED_OUT
159  0 0:18:20.461219763    252686 0a010005 CT1c 100 100             SWITCHED_IN
160  0 0:18:20.461424231    204468 0a010005 CT1c 100 100             TERMINATED
161  0 0:18:20.461747107    322876 0a010005 CT1c 100 100             SWITCHED_OUT
162  0 0:18:20.461824011     76904 0a010004 CT1b 101 101             SWITCHED_IN
163  0 0:18:20.462015052    191041 0a010004 CT1b 101 101             TERMINATED
164  0 0:18:20.462336707    321655 0a010004 CT1b 101 101             SWITCHED_OUT
165  0 0:18:20.462414222     77515 0a010003 CT1a 102 102             SWITCHED_IN
166  0 0:18:20.462608924    194702 0a010003 CT1a 102 102             TERMINATED
167  0 0:18:20.462933021    324097 0a010003 CT1a 102 102             SWITCHED_OUT
168  1-rtems $ ctrace
169  1-rtems $
Note: See TracBrowser for help on using the repository browser.