mirror of
https://git.rtems.org/rtems-docs/
synced 2025-05-15 05:26:39 +08:00
169 lines
7.2 KiB
ReStructuredText
169 lines
7.2 KiB
ReStructuredText
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
|
|
|
.. Copyright (C) 2018 Vidushi Vashishth <vidushivashishth96@gmail.com>
|
|
|
|
.. _CaptureEngine:
|
|
|
|
Capture Engine
|
|
**************
|
|
|
|
Capture Engine is a trace tool built inside the RTEMS operating system. Capture
|
|
Engine is designed to cause the lowest load on the system when operating. Hence
|
|
it does not effect RTEMS when operating or when disabled. It binds to RTEMS at
|
|
runtime and does not require RTEMS or your application to be rebuilt in order
|
|
to use it.
|
|
|
|
The Capture Engine's sample testcase for the `sparc/erc32` is available in
|
|
build directory created when building RTEMS in the path
|
|
file: `sparc-rtems5/c/erc32/testsuites/samples`. In order to access the capture
|
|
testcase perform the following set of operations inside the RTEMS build
|
|
directory.
|
|
|
|
.. code-block:: none
|
|
|
|
$ cd /sparc-rtems5/c/erc32/testsuites/samples
|
|
$ sparc-rtems5-run ./capture.exe
|
|
|
|
|
|
*** BEGIN OF TEST CAPTURE ENGINE ***
|
|
*** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8
|
|
*** TEST STATE: USER_INPUT
|
|
*** TEST BUILD: RTEMS_NETWORKING RTEMS_POSIX_API
|
|
*** TEST TOOLS: 7.3.0 20180125 (RTEMS 5, RSB a3a6c34c150a357e57769a26a460c475e188438f, Newlib 3.0.0)
|
|
Press any key to start capture engine (20s remaining)
|
|
Press any key to start capture engine (19s remaining)
|
|
Press any key to start capture engine (18s remaining)
|
|
|
|
Monitor ready, press enter to login.
|
|
|
|
1-rtems $
|
|
|
|
Capture Engine comes with a set of commands to perform various actions.
|
|
|
|
Capture Engine Commands
|
|
-----------------------
|
|
|
|
1) ``copen <buffer-size>``: Used to initialize the Capture Engine with the
|
|
trace buffer size in bytes. By default the Capture Engine is not initialized
|
|
and not running.
|
|
|
|
2) ``cwceil <priority-value>``: Capture Engine filter used to put an upper
|
|
limit on the event priority to be captured.
|
|
|
|
3) ``cwfloor <priority-value>``: Capture Engine filter used to put a lower
|
|
limit on the event priority to be captured.
|
|
|
|
4) ``cwglob <on/off>``: Enable or disable the global watch.
|
|
|
|
5) ``cenable``: Enables the Capture Engine. Capture Engine is by default
|
|
disabled after being opened.
|
|
|
|
6) ``cdisable``: Disables the Capture Engine.
|
|
|
|
7) ``ctlist``: Lists the watch and trigger configurations.
|
|
|
|
8) ``ctrace``: Dumps the recorded traces. By default this command displays 24
|
|
trace records. Repeated use of this command will display all the recorded
|
|
traces.
|
|
|
|
9) ``cwadd <task-name>``: Add watch on a particular task.
|
|
|
|
10) ``cwtctl <task-name> <on/off>``: Enable or disable watch on a particular
|
|
task.
|
|
|
|
11) ``ctset``: Used to set a trigger. The general form of the command is:
|
|
|
|
``ctset [-?] type [to name/id] [from] [from name/id]``
|
|
|
|
`type` in the above command refers to the type of trigger needed. The types of
|
|
triggers that currently exist are:
|
|
|
|
- switch : a context switch from one task to another task
|
|
- create : the executing task creates a task
|
|
- start : the executing task starts a task
|
|
- restart : the executing task restarts a task
|
|
- delete : the executing task deletes a task
|
|
- begin : a task is beginning
|
|
- exitted : a task is exitting
|
|
|
|
Example
|
|
-------
|
|
|
|
The following is a sample run of the capture testsuite. The `test1` command on
|
|
the Capture Engine Command Line Interface (CLI) makes the `RMON` task invoke a
|
|
call to the `capture_test_1()` command. This function (in the `test1.c` source
|
|
code) creates and starts three tasks : `CT1a`, `CT1b` and `CT1c`. These tasks
|
|
are passed the object id of a semaphore as a task argument. This run through
|
|
traces the context switches between these tasks. ``cwceil`` and ``cwfloor`` are
|
|
set to a narrow range of task priorities to avoid creating noise from a large
|
|
number of context switches between tasks we are not interested in.
|
|
|
|
.. code-block:: none
|
|
|
|
*** BEGIN OF TEST CAPTURE ENGINE ***
|
|
*** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8
|
|
*** TEST STATE: USER_INPUT
|
|
*** TEST BUILD: RTEMS_NETWORKING RTEMS_POSIX_API
|
|
*** TEST TOOLS: 7.3.0 20180125 (RTEMS 5, RSB a3a6c34c150a357e57769a26a460c475e188438f, Newlib 3.0.0)
|
|
Press any key to start capture engine (20s remaining)
|
|
Press any key to start capture engine (19s remaining)
|
|
Press any key to start capture engine (18s remaining)
|
|
Press any key to start capture engine (17s remaining)
|
|
|
|
Monitor ready, press enter to login.
|
|
|
|
1-rtems $ copen 50000
|
|
capture engine opened.
|
|
1-rtems $ cwceil 100
|
|
watch ceiling is 100.
|
|
1-rtems $ cwfloor 102
|
|
watch floor is 102.
|
|
1-rtems $ cwglob on
|
|
global watch enabled.
|
|
1-rtems $ ctset RMON
|
|
trigger set.
|
|
1-rtems $ cenable
|
|
capture engine enabled.
|
|
1-rtems $ test1
|
|
1-rtems $ cdisable
|
|
capture engine disabled.
|
|
1-rtems $ ctrace
|
|
0 0:18:17.462314124 0a010003 CT1a 102 102 102 4096 TASK_RECORD
|
|
0 0:18:17.462398963 0 0a010003 CT1a 102 102 CREATED
|
|
0 0:18:17.462647987 249024 0a010003 CT1a 102 102 STARTED
|
|
0 0:18:17.462904334 256347 0a010003 CT1a 102 102 SWITCHED_IN
|
|
0 0:18:17.463069129 164795 0a010003 CT1a 102 102 BEGIN
|
|
0 0:18:17.463335853 266724 0a010003 CT1a 102 102 SWITCHED_OUT
|
|
0 0:18:18.461348547 0a010004 CT1b 101 101 101 4096 TASK_RECORD
|
|
0 0:18:18.461433997 998098144 0a010004 CT1b 101 101 CREATED
|
|
0 0:18:18.461683631 249634 0a010004 CT1b 101 101 STARTED
|
|
0 0:18:18.461934485 250854 0a010004 CT1b 101 101 SWITCHED_IN
|
|
0 0:18:18.462099891 165406 0a010004 CT1b 101 101 BEGIN
|
|
0 0:18:19.460935339 998835448 0a010004 CT1b 101 101 SWITCHED_OUT
|
|
0 0:18:19.461431555 0a010005 CT1c 100 100 100 4096 TASK_RECORD
|
|
0 0:18:19.461516394 581055 0a010005 CT1c 100 100 CREATED
|
|
0 0:18:19.461765418 249024 0a010005 CT1c 100 100 STARTED
|
|
0 0:18:19.462019324 253906 0a010005 CT1c 100 100 SWITCHED_IN
|
|
0 0:18:19.462184119 164795 0a010005 CT1c 100 100 BEGIN
|
|
0 0:18:19.462475257 291138 0a010005 CT1c 100 100 SWITCHED_OUT
|
|
0 0:18:19.462551551 76294 0a010004 CT1b 101 101 SWITCHED_IN
|
|
0 0:18:19.960935645 498384094 0a010004 CT1b 101 101 SWITCHED_OUT
|
|
0 0:18:19.961012549 76904 0a010003 CT1a 102 100 SWITCHED_IN
|
|
0 0:18:19.961341528 328979 0a010003 CT1a 102 102 SWITCHED_OUT
|
|
1-rtems $ ctrace
|
|
0 0:18:19.961418433 0 0a010005 CT1c 100 100 SWITCHED_IN
|
|
0 0:18:19.961672339 253906 0a010005 CT1c 100 100 SWITCHED_OUT
|
|
0 0:18:19.961749854 77515 0a010004 CT1b 101 101 SWITCHED_IN
|
|
0 0:18:20.460967077 499217223 0a010004 CT1b 101 101 SWITCHED_OUT
|
|
0 0:18:20.461219763 252686 0a010005 CT1c 100 100 SWITCHED_IN
|
|
0 0:18:20.461424231 204468 0a010005 CT1c 100 100 TERMINATED
|
|
0 0:18:20.461747107 322876 0a010005 CT1c 100 100 SWITCHED_OUT
|
|
0 0:18:20.461824011 76904 0a010004 CT1b 101 101 SWITCHED_IN
|
|
0 0:18:20.462015052 191041 0a010004 CT1b 101 101 TERMINATED
|
|
0 0:18:20.462336707 321655 0a010004 CT1b 101 101 SWITCHED_OUT
|
|
0 0:18:20.462414222 77515 0a010003 CT1a 102 102 SWITCHED_IN
|
|
0 0:18:20.462608924 194702 0a010003 CT1a 102 102 TERMINATED
|
|
0 0:18:20.462933021 324097 0a010003 CT1a 102 102 SWITCHED_OUT
|
|
1-rtems $ ctrace
|
|
1-rtems $
|