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 | |
---|
8 | Capture Engine |
---|
9 | ************** |
---|
10 | |
---|
11 | Capture Engine is a trace tool built inside the RTEMS operating system. Capture |
---|
12 | Engine is designed to cause the lowest load on the system when operating. Hence |
---|
13 | it does not effect RTEMS when operating or when disabled. It binds to RTEMS at |
---|
14 | runtime and does not require RTEMS or your application to be rebuilt in order |
---|
15 | to use it. |
---|
16 | |
---|
17 | The Capture Engine's sample testcase for the `sparc/erc32` is available in |
---|
18 | build directory created when building RTEMS in the path |
---|
19 | file: `sparc-rtems5/c/erc32/testsuites/samples`. In order to access the capture |
---|
20 | testcase perform the following set of operations inside the RTEMS build |
---|
21 | directory. |
---|
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 | |
---|
42 | Capture Engine comes with a set of commands to perform various actions. |
---|
43 | |
---|
44 | Capture Engine Commands |
---|
45 | ----------------------- |
---|
46 | |
---|
47 | 1) ``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 | |
---|
51 | 2) ``cwceil <priority-value>``: Capture Engine filter used to put an upper |
---|
52 | limit on the event priority to be captured. |
---|
53 | |
---|
54 | 3) ``cwfloor <priority-value>``: Capture Engine filter used to put a lower |
---|
55 | limit on the event priority to be captured. |
---|
56 | |
---|
57 | 4) ``cwglob <on/off>``: Enable or disable the global watch. |
---|
58 | |
---|
59 | 5) ``cenable``: Enables the Capture Engine. Capture Engine is by default |
---|
60 | disabled after being opened. |
---|
61 | |
---|
62 | 6) ``cdisable``: Disables the Capture Engine. |
---|
63 | |
---|
64 | 7) ``ctlist``: Lists the watch and trigger configurations. |
---|
65 | |
---|
66 | 8) ``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 | |
---|
70 | 9) ``cwadd <task-name>``: Add watch on a particular task. |
---|
71 | |
---|
72 | 10) ``cwtctl <task-name> <on/off>``: Enable or disable watch on a particular |
---|
73 | task. |
---|
74 | |
---|
75 | 11) ``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 |
---|
80 | triggers 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 | |
---|
90 | Example |
---|
91 | ------- |
---|
92 | |
---|
93 | The following is a sample run of the capture testsuite. The `test1` command on |
---|
94 | the Capture Engine Command Line Interface (CLI) makes the `RMON` task invoke a |
---|
95 | call to the `capture_test_1()` command. This function (in the `test1.c` source |
---|
96 | code) creates and starts three tasks : `CT1a`, `CT1b` and `CT1c`. These tasks |
---|
97 | are passed the object id of a semaphore as a task argument. This run through |
---|
98 | traces the context switches between these tasks. ``cwceil`` and ``cwfloor`` are |
---|
99 | set to a narrow range of task priorities to avoid creating noise from a large |
---|
100 | number 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 $ |
---|