[PATCH v5 2/2] Adding Trace Docuemntation
Gedare Bloom
gedare at rtems.org
Wed Jun 13 13:18:06 UTC 2018
I think we're almost there. ;) A bit more below:
On Wed, Jun 13, 2018 at 5:22 AM, Vidushi Vashishth <reachvidu at gmail.com> wrote:
> - Completed Trace Linker Section
> - Added Trace Examples section
> - Removed CTF section
> - Removed Use cases section
> - Incorporated changes asked by Chris
It would be best to provide the "summary of changes" in reply to the
patch, and instead continue to have a useful commit message that will
make sense when someone looks in the git-log. For example, looking in
the log and seeing "Removed CTF section" one would ask where that was
to begin with. Also, that you incorporated asked for changes can be
omitted, since this is usually the case for all commits. So make sure
your commit message only accurately reflects what is in the commit.
There should be a ticket associated with your project that it would
make sense to add a line in the commit message: "Updates #2xxx"?
> ---
> user/index.rst | 2 +
> user/tracing/captureengine.rst | 182 +++++++++++++++
> user/tracing/examples.rst | 185 +++++++++++++++
> user/tracing/index.rst | 30 +++
> user/tracing/introduction.rst | 105 +++++++++
> user/tracing/tracelinker.rst | 501 +++++++++++++++++++++++++++++++++++++++++
> 6 files changed, 1005 insertions(+)
> create mode 100644 user/tracing/captureengine.rst
> create mode 100644 user/tracing/examples.rst
> create mode 100644 user/tracing/index.rst
> create mode 100644 user/tracing/introduction.rst
> create mode 100644 user/tracing/tracelinker.rst
>
> diff --git a/user/index.rst b/user/index.rst
> index 8cbcd1b..a764fe8 100644
> --- a/user/index.rst
> +++ b/user/index.rst
> @@ -52,6 +52,8 @@ to the Community Project hosted at http://www.rtems.org/.
>
> tools/index
>
> + tracing/index
> +
> support/index
>
> glossary/index
> diff --git a/user/tracing/captureengine.rst b/user/tracing/captureengine.rst
> new file mode 100644
> index 0000000..b4c1123
> --- /dev/null
> +++ b/user/tracing/captureengine.rst
> @@ -0,0 +1,182 @@
> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +.. comment: Copyright (c) 2016 Chris Johns <chrisj at rtems.org>
Is all of this Chris' writing? Or did you write some of this? You
should put your copyright and current year on the files with words
that you create, if any
> +.. comment: All rights reserved.
> +
> +.. _capturengine:
> +
> +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` directory.
> +In order to access the capture testcase perform the following set of
> +operations inside the RTEMS build directory.
> +
> +.. code-block:: shell
> +
> + $ 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:: shell
> +
> + *** 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 $
> +
> +
> diff --git a/user/tracing/examples.rst b/user/tracing/examples.rst
> new file mode 100644
> index 0000000..533997e
> --- /dev/null
> +++ b/user/tracing/examples.rst
> @@ -0,0 +1,185 @@
> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +.. comment: Copyright (c) 2016 Chris Johns <chrisj at rtems.org>
> +.. comment: All rights reserved.
> +
> +.. _examples:
> +
> +Tracing Examples
> +****************
> +
> +The following example executes RTEMS trace using trace buffering for the
> +`fileio` sample testcase.
> +
> +Prerequisites
> +-------------
> +
> +1. Setup RTEMS for the `sparc/erc32` architecture-bsp pair to run the
> + following example.
> +2. Download the fileio `configuration file <https://devel.rtems.org/attachment
> + /wiki/Developer/Tracing/Trace_Buffering/fileio-trace.ini>`_ and store it on
> + the top of the installed BSP's directory.
> +3. Change the value of the keys: `rtems-path` and `prefix` according to your
> + rtems installation. The `rtems-path` is the path to the bsp installation
> + and `prefix` is the path to the tools used to build rtems. Also set the
> + value of the `rtems-bsp` key to `sparc/erc32`.
> +
> +Demonstration
> +-------------
> +
> +Inside the RTEMS build directory (the directory where the fileio configuration
> +has been stored) run the following commands to generate traces:
> +
> +BSP is configured with the following command -
> +
> +.. code:: shell
> +
> + ../rtems/configure --target=sparc-rtems5 --prefix=/development/rtems/5 \
> + --enable-networking --enable-tests --enable-rtemsbsp=erc32 --enable-cxx
> +
> +The next two commands are used to link the fileio executable.The `-B` option
> +signifies the use of the complete path to the required directory or file. Write
> +the full path instead of the path file: `sparc-rtems5/erc32/lib/` in the
> +following commands according to your installation. Also confirm the path of the
> +fileio’s executable and object files in the last line of the command according
> +to your installation.
> +
> +.. code:: shell
> +
> + sparc-rtems5-gcc -Bsparc-rtems5/erc32/lib/ \
> + -specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections \
> + -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration \
> + -Wstrict-prototypes -Wnested-externs -Wl,--gc-sections -mcpu=cypress \
> + -o sparc-rtems5/c/erc32/testsuites/samples/fileio.exe sparc-rtems5/c/erc32/\
> + testsuites/samples/fileio/fileio-init.o
> +
> +This is the trace linker command to generate and compile the wrapper c file for
> +the application. The link command follows the escape sequence "--". "-C" option
> +denotes the name of the user configuration file and "-W" specifies the name of
> +the wrapper c file.
> +
> +.. code:: shell
> +
> + rtems-tld -C fileio-trace.ini -W fileio-wrapper -- -Bsparc-rtems5/erc32/lib/ \
> + -specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections \
> + -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration \
> + -Wstrict-prototypes -Wnested-externs -Wl,--gc-sections -mcpu=cypress \
> + -o sparc-rtems5/c/erc32/testsuites/samples/fileio.exe sparc-rtems5/c/erc32/\
> + testsuites/samples/fileio/fileio-init.o
> +
> +The following command is used to run the application. Hit enter key quickly and
> +type "s" and "root" and "pwd" to run the rtems shell. Use the `rtrace status`,
> +`rtrace trace` and `rtrace save` commands to know the status of the tracing,
> +display the contents of the trace buffer and save the buffer to disk in the form
> +of binary files.
> +
> +.. code:: shell
> +
> + sparc-rtems5-run sparc-rtems5/c/erc32/testsuites/samples/fileio.exe
> +
> +The output from the above commands will be as follows:
> +
> +.. code:: shell
> +
> + *** BEGIN OF TEST FILE I/O ***
> + *** 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 a3a6c34c150a357e57769a26a460c475e
> + 188438f, Newlib 3.0.0)
> + Press any key to start file I/O sample (20s remaining)
> + Press any key to start file I/O sample (19s remaining)
> + Press any key to start file I/O sample (18s remaining)
> + Press any key to start file I/O sample (17s remaining)
> + Press any key to start file I/O sample (16s remaining)
> + Press any key to start file I/O sample (15s remaining)
> + Press any key to start file I/O sample (14s remaining)
> + =========================
> + RTEMS FILE I/O Test Menu
> + =========================
> + p -> part_table_initialize
> + f -> mount all disks in fs_table
> + l -> list file
> + r -> read file
> + w -> write file
> + s -> start shell
> + Enter your selection ==>s
> + Creating /etc/passwd and group with four useable accounts:
> + root/pwd
> + test/pwd
> + rtems/NO PASSWORD
> + chroot/NO PASSWORD
> + Only the root user has access to all available commands.
> + =========================
> + starting shell
> + =========================
> +
> + Welcome to rtems-5.0.0 (SPARC/w/FPU/erc32)
> + COPYRIGHT (c) 1989-2008.
> + On-Line Applications Research Corporation (OAR).
> +
> + Login into RTEMS
> + /dev/foobar login: root
> + Password:
> +
> + RTEMS Shell on /dev/foobar. Use 'help' to list commands.
> + SHLL [/] # rtrace status
> + RTEMS Trace Bufferring: status
> + Running: yes
> + Triggered: yes
> + Level: 0%
> + Traces: 25
> + SHLL [/] # rtrace stop
> + RTEMS Trace Bufferring: stop
> + SHLL [/] # rtrace trace
> + RTEMS Trace Bufferring: trace
> + Trace buffer: 0x20921d8
> + Words traced: 1487
> + Traces: 25
> + 0:00:40.983197010 2081910 0a010002 [ 2/ 2] > malloc((size_t) 00000130)
> + 0:00:40.983333119 136109 0a010002 [ 2/ 2] < malloc => (void*) 0x219bb88
> + 0:00:40.983471669 138550 0a010002 [ 2/ 2] > malloc((size_t) 00000006)
> + 0:00:40.983606557 134888 0a010002 [ 2/ 2] < malloc => (void*) 0x219bcc0
> + 0:00:40.983684682 78125 0a010002 [ 2/ 2] > malloc((size_t) 00000007)
> + 0:00:40.983819569 134887 0a010002 [ 2/ 2] < malloc => (void*) 0x219bcd0
> + 0:00:40.983909901 90332 0a010002 [ 2/ 2] > malloc((size_t) 000003fc)
> + 0:00:40.984046620 136719 0a010002 [ 2/ 2] < malloc => (void*) 0x219bce0
> + 0:00:40.986624137 2577517 0a010003 [200/200] > malloc((size_t) 00000080)
> + 0:00:40.986767569 143432 0a010003 [200/200] < malloc => (void*) 0x219bce0
> + 0:00:40.987531119 763550 0a010003 [200/200] > calloc((size_t) 00000001, (size_t) 0000005d)
> + 0:00:40.987603751 72632 0a010003 [200/200] > malloc((size_t) 0000005d)
> + 0:00:40.987744743 140992 0a010003 [200/200] < malloc => (void*) 0x219bce0
> + 0:00:40.987824699 79956 0a010003 [200/200] < calloc => (void*) 0x219bce0
> + 0:00:40.988302604 477905 0a010003 [200/200] > malloc((size_t) 00000080)
> + 0:00:40.988446647 144043 0a010003 [200/200] < malloc => (void*) 0x219bd48
> + 0:00:40.988667595 220948 0a010003 [200/200] > calloc((size_t) 00000001, (size_t) 00000080)
> + 0:00:40.988740837 73242 0a010003 [200/200] > malloc((size_t) 00000080)
> + 0:00:40.988884880 144043 0a010003 [200/200] < malloc => (void*) 0x219bdd0
> + 0:00:40.988964836 79956 0a010003 [200/200] < calloc => (void*) 0x219bdd0
> + 0:00:40.989042961 78125 0a010003 [200/200] > calloc((size_t) 00000001, (size_t) 00000080)
> + 0:00:40.989110100 67139 0a010003 [200/200] > malloc((size_t) 00000080)
> + 0:00:40.989254143 144043 0a010003 [200/200] < malloc => (void*) 0x219be58
> + 0:00:40.989334099 79956 0a010003 [200/200] < calloc => (void*) 0x219be58
> + 0:00:40.990118401 784302 0a010003 [200/200] > calloc((size_t) 00000001, (size_t) 00000061)
> + 0:00:40.990176995 58594 0a010003 [200/200] > malloc((size_t) 00000061)
> + 0:00:40.990309441 132446 0a010003 [200/200] < malloc => (void*) 0x219bd48
> + 0:00:40.990384515 75074 0a010003 [200/200] < calloc => (void*) 0x219bd48
> + 0:00:40.990870355 485840 0a010003 [200/200] > malloc((size_t) 00000080)
> + 0:00:40.991011346 140991 0a010003 [200/200] < malloc => (void*) 0x219bee0
> + 0:00:40.991227411 216065 0a010003 [200/200] > calloc((size_t) 00000001, (size_t) 00000080)
> + 0:00:40.991296380 68969 0a010003 [200/200] > malloc((size_t) 00000080)
> + 0:00:40.991438593 142213 0a010003 [200/200] < malloc => (void*) 0x219bf68
> + 0:00:40.991514276 75683 0a010003 [200/200] < calloc => (void*) 0x219bf68
> + 0:00:40.991589349 75073 0a010003 [200/200] > calloc((size_t) 00000001, (size_t) 00000080)
> + 0:00:40.991653437 64088 0a010003 [200/200] > malloc((size_t) 00000080)
> + 0:00:40.991794428 140991 0a010003 [200/200] < malloc => (void*) 0x219bff0
> + 0:00:40.991871332 76904 0a010003 [200/200] < calloc => (void*) 0x219bff0
> + 0:00:40.992283320 411988 0a010003 [200/200] > malloc((size_t) 00000008)
> + SHLL [/] # rtrace save fileio-trace.bin
> + RTEMS Trace Bufferring: trace
> + Trace File: fileio-trace.bin
> + Trace buffer: 0x20921d8
> + Words traced: 1487
> + Traces: 25
> + SHLL [/] #
> +
> diff --git a/user/tracing/index.rst b/user/tracing/index.rst
> new file mode 100644
> index 0000000..b75261d
> --- /dev/null
> +++ b/user/tracing/index.rst
> @@ -0,0 +1,30 @@
> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +.. comment: Copyright (c) 2016 Chris Johns <chrisj at rtems.org>
> +.. comment: All rights reserved.
> +
> +.. _tracing-framework:
> +
> +RTEMS Tracing Framework
> +***********************
> +.. index:: Tracing Framework
> +
> +RTEMS Tracing Framework is an on-target software based system which helps track
> +the ongoings inside the operation of applications, 3rd party packages, and the
> +kernel in real time.
> +
> +Software based tracing is a complex process which requires components on both
> +the target and the host to work together. However its portability across all
> +architectures and board support packages makes it a useful asset. A key
> +requirement in RTEMS trace process is to take existing code in compiled format
> +(ELF) and instrument it in order to log various events and records in real time.
> +However instrumenting of the code for tracing should happen without rebuilding
> +the code from the source and without annotating the source with trace code.
> +
> +.. toctree::
> +
> + introduction
> + examples
> + captureengine
> + tracelinker
> +
> diff --git a/user/tracing/introduction.rst b/user/tracing/introduction.rst
> new file mode 100644
> index 0000000..7b9e1d3
> --- /dev/null
> +++ b/user/tracing/introduction.rst
> @@ -0,0 +1,105 @@
> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +.. comment: Copyright (c) 2016 Chris Johns <chrisj at rtems.org>
> +.. comment: All rights reserved.
> +
> +.. _introduction:
> +
> +Introduction to Tracing
> +***********************
> +
> +Tracing is an important function which has several applications including
> +identification of complex threading, detection of deadlocks, tracing
> +functions along with their argument values, and return values through
> +progression of several function calls and audit the performance of an
> +application according to required specifications.
> +
> +RTEMS tracing framework is under development and welcomes contribution by users.
> +
> +RTEMS has the following trace components:
> +
> +- RTEMS :ref:`tracelinker`
> +- RTEMS :ref:`capturengine`
> +- Common Trace Format Integration
> +
> +
> +RTEMS trace framework can currently function using the following methods. Both
> +of the methods make use of the :ref:`tracelinker` :
> +
> +.. _tracebuffering:
> +
> +RTEMS Trace Using Trace Buffering
> +=================================
> +
> +This scheme of tracing goes through the flow of events described in a
> +subsequent flowchart:
> +
> +Step 1: The user creates an application and user configuration file. The
> +configuration file specifies the use of the trace buffer generator and other
> +standard initializations. The user then configures their BSP and invokes the
> +trace linker using a command to link the application executable. The trace
> +linker uses the application files in compiled format (ELF) and the libraries
> +used to build the application for performing this link.
> +
> +Step 2: The RTEMS Trace Linker reads the user’s configuration file and that
> +results in it reading the standard Trace Buffering Configuration files
> +installed with the RTEMS Trace Linker. The trace linker uses the target
> +compiler and linker to create the trace enabled application executable. It
> +wraps the functions defined in the user’s configuration with code that captures
> +trace records into the statically allocated buffer. The trace wrapper code is
> +compiled with the target compiler and the resulting ELF object file is added to
> +the standard link command line used to link the application and the application
> +is re-linked using the wrapping option of the GNU linker.
> +
> +Step 3: The trace linker creates an executable which is capable of running on
> +the target hardware or simulator.
> +
> +Step 4: RTEMS shell provides the “rtrace” command to display and save trace
> +buffers.
> +
> +.. comment: taken from https://devel.rtems.org/wiki/Developer/Tracing
> +.. figure:: ../../images/user/rtems-trace-buffering.png
> + :align: center
> + :width: 75%
> +
> +.. _printk:
> +
> +RTEMS Trace Using Printk
> +========================
> +
> +This scheme of tracing goes through the flow of events described in a subsequent
> +flowchart:
> +
> +Step 1: The user creates an RTEMS application in the normal manner as well as a
> +Trace Linker configuration file. The configuration file specifies using the
> +Printk trace mode and the functions to trace. The user invokes the Trace Linker
> +with the configuration and the normal link command line used to the link the
> +application executable. The application ELF object files and libraries,
> +including the RTEMS libraries are standard and do not need to be built
> +specially.
> +
> +Step 2: The RTEMS Trace Linker reads the user's configuration file and that
> +results in it reading the standard Printk Trace Configuration files installed
> +with the RTEMS Trace Linker. The trace linker uses the target compiler and
> +linker to create the trace enabled application executable. It wraps the
> +functions defined in the user's configuration with code that prints the entry
> +with arguments and exit and return value if any. The trace wrapper code is
> +compiled with the target compiler and the resulting ELF object file is added to
> +the standard link command line used to link the application and the application
> +is relinked using the wrapping option of the GNU linker.
> +
> +Step 3: The trace linker creates and RTEMS ELF executable that can be run on the
> +target hardware or simulator.
> +
> +Step 4: The application is run in the hardware directly or using a debugger. The
> +printk() output appears on the target console and the user can save that to a
> +file.
> +
> +.. comment: taken from https://devel.rtems.org/wiki/Developer/Tracing
> +.. figure:: ../../images/user/rtems-trace-printk.png
> + :align: center
> + :width: 75%
> +
> +The :ref:`examples` section describes generation of traces using both of the
> +aforementioned techniques using the `fileio` testsuite available with RTEMS
> +installation.
> diff --git a/user/tracing/tracelinker.rst b/user/tracing/tracelinker.rst
> new file mode 100644
> index 0000000..a95ec41
> --- /dev/null
> +++ b/user/tracing/tracelinker.rst
> @@ -0,0 +1,501 @@
> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +.. comment: Copyright (c) 2016 Chris Johns <chrisj at rtems.org>
> +.. comment: All rights reserved.
> +
> +.. _tracelinker:
> +
> +Trace Linker
> +************
> +
> +RTEMS trace linker is a post link tool central to the RTEMS trace framework. It
> +is installed as a part of the RTEMS Tool Project. The RTEMS Trace Linker is a
> +post link tool that performs a re-link of your application to produce a trace
> +executable. A trace executable has been instrumented by the RTEMS Trace Linker
> +with additional code that implements software tracing. A key requirement of the
> +trace process in RTEMS is to take existing code in a compiled format (ELF) and
> +instrument it without rebuilding that code from source and without annotating
> +that source with trace code.
> +
> +Command Line
> +============
> +
> +A typical command to invoke the trace linker consists of two parts separated by
> +``--``. The first part controls the trace linker and provides the various
> +options it needs and the second part is a standard linker command line you would
> +use to link an RTEMS application. The current command line for trace linker
> +consists of:
> +
> +.. code-block:: shell
> +
> + $ rtems-tld -h
> + rtems-trace-ld [options] objects
> + Options and arguments:
> + -h : help (also --help)
> + -V : print linker version number and exit (also --version)
> + -v : verbose (trace import parts), can supply multiple times
> + to increase verbosity (also --verbose)
> + -w : generate warnings (also --warn)
> + -k : keep temporary files (also --keep)
> + -c compiler : target compiler is not standard (also --compiler)
> + -l linker : target linker is not standard (also --linker)
> + -E prefix : the RTEMS tool prefix (also --exec-prefix)
> + -f cflags : C compiler flags (also --cflags)
> + -r path : RTEMS path (also --rtems)
> + -B bsp : RTEMS arch/bsp (also --rtems-bsp)
> + -W wrapper : wrapper file name without ext (also --wrapper)
> + -C ini : user configuration INI file (also --config)
> + -P path : user configuration INI file search path (also --path)
> +
> +The trace linker generates code that needs to be compiled and linked to the
> +application executable so it needs to know the target compiler and `CFLAGS`.
> +There are a couple of ways to do this. The simplest is to provide the path to
> +RTEMS using the `-r` option and the architecture and BSP name in the standard
> +RTEMS format of arch/bsp. The trace linker will extract the compiler and flags
> +used to build RTEMS and will use them. If you require specific options you can
> +use the `-f`, `-c`, `-l`, and `-E` options to provide them. If the functions you
> +are tracing use types from your code then add the include path to the `CFLAGS`.
> +
> +The trace linker requires you to provide a user configuration file using the
> +`-C` or ``--config`` option. This is an INI format file detailed in the
> +Configuration section. You can also provide an INI file search path using the
> +`-P` option.
> +
> +If you are working with new configuration files and you want to view the files
> +the trace linker generates, add the `-k` option to keep the temporary files, and
> +`-W` to specify an explicit wrapper C file name. If you set the
> +``dump-on-error`` option in the configuration options section you will get a
> +dump of the configuration on an error.
> +
> +Configuration (INI) files
> +=========================
> +
> +The Trace Linker is controlled using configuration files. Configuration files
> +are categorized into 3 types:
> +
> +- User Configuration: These are specific to the user application to be traced.
> + This file initializes the values of the trace generator, triggers, enables,
> + and traces.
> +
> +- Tracer Configuration: These are like a library of common or base trace
> + functions that can be referenced by an application. These files tend to hold
> + the details needed to wrap a specific set of functions. Examples provided with
> + the RTEMS Linker are the RTEMS API and Libc.
> +
> +- Generator Configuration: This is used to encapsulate a specific method of
> + tracing. Rtems currently provides generators for trace buffering, printk, and
s/Rtems/RTEMS
It is ok to use 'rtems' or 'RTEMS' but 'Rtems' is strange.
> + printf.
> +
> +The configuration files are in the *INI file format* which is composed of
> +`sections`. Each section has a section name and set of *keys* which consist of
> +*names* and *values*. A typical key is of the form ``name=value``. Keys can be
> +used to include other INI files using the include key name. This is shown in the
> +following example where the values indicate rtems and rtld-base configuration
> +files:
> +
> +.. code-block:: shell
> +
> + include = rtems.ini, rtld-base.ini
> +
> +The trace linker also uses values in keys to specify other sections. In this
> +example the functions name lists `test-trace-funcs` and that section contains a
> +headers key that further references a section called `test-headers`:
> +
> +.. code-block:: shell
> +
> + functions = test-trace-funcs, rtems-api
> +
> + [test-trace-funcs]
> + ; Parsed via the 'function-set', not parse as a 'trace'.
> + headers = test-headers
> +
> + [test-headers]
> + header = '#include "test-trace-1.h"'
> +
> +The format of a configuration file is explained next. Snippets of the file:
> +`test-trace.ini` have been used for explicit understanding. This file can
> +be found in the rtems-tools directory of the rtems installation.
> +
> +Tracer Section
> +--------------
> +
> +The topmost level section is the ``tracer`` section. It can contains the
> +following keys:
> +
> +- ``name``: The name of trace being linked.
> +
> +- ``options``: A list of option sections.
> +
> +- ``defines``: A list of sections containing defines or define record.
> +
> +- ``define``: A list of define string that are single or double quoted.
> +
> +- ``enables``: The list of sections containing enabled functions to trace.
> +
> +- ``triggers``: The list of sections containing enabled functions to trigger
> + trace on.
> +
> +- ``traces``: The list of sections containing function lists to trace.
> +
> +- ``functions``: The list of sections containing function details.
> +
> +- ``include``: The list of files to include
> +
> +The tracer section of the file:`test-trace.ini` is shown below with explanatory
> +comments.
> +
> +.. code-block:: shell
> +
> + ;
> + ; RTEMS Trace Linker Test Configuration.
> + ;
> + ; We must provide a top level trace section.
> + ;
> + [tracer]
> + ;
> + ; Name of the trace.
> + ;
> + name = RTEMS Trace Linker Test
> + ;
> + ; The BSP.
> + ;
> + bsp = sparc/sis
> + ;
> + ; Functions to trace.
> + ;
> + traces = test-trace, test-trace-funcs, rtems-api-task
> + ;
> + ; Specify the options.
> + ;
> + options = test-options
> + ;
> + ; Define the function sets. These are the function's that can be
> + ; added to the trace lists.
> + ;
> + functions = test-trace-funcs, rtems-api
> + ;
> + ; Include RTEMS Trace support.
> + ;
> + include = rtems.ini, rtld-base.ini
> +
> +Options section
> +---------------
> +
> +The options section in the fileio-trace.ini is called the `fileio-options`. A
> +general options section can contain following sets of keys:
> +
> +- ``dump-on-error``: Dump the parsed configuration data on error. The value can
> + be true or false.
> +
> +- ``verbose``: Set the verbose level. The value can be true or a number value.
> +
> +- ``prefix``: The prefix for the tools and an install RTEMS if rtems-path is not
> + set.
> +
> +- ``cc``: The compiler used to compile the generated wrapper code. Overrides the
> + BSP configuration value if a BSP
> + is specified.
> +
> +- ``ld``: The linker used to link the application. The default is the cc value
> + as read from the BSP configuration if specified. If your application contains
> + C++ code use this setting to the change the linker to g++.
> +
> +- ``cflags``: Set the CFLAGS used to compiler the wrapper. These flags are
> + pre-pended to the BSP read flags if a BSP is specified. This option is used
> + to provide extra include paths to header files in your application that
> + contain types referenced by functions being traced.
> +
> +- ``rtems-path``: The path to an install RTEMS if not installed under the prefix.
> +
> +- ``rtems-bsp``: The BSP we are building the trace executable for. The is an
> + arch and bsp pair. For example sparc/erc32.
> +
> +The options section of the file: `test-trace.ini` uses two of the aforementioned
> +keys as shown below:
> +
> +.. code-block:: shell
> +
> + ;
> + ; Options can be defined here or on the command line.
> + ;
> + [test-options]
> + prefix = /development/rtems/5
> + verbose = true
> +
> +Trace Section
> +--------------
> +
> +A trace section defines how trace wrapper functions are built. To build a trace
> +function that wraps an existing function in an ELF object file or library
> +archive we need to have the function's signature. A signature is the function's
> +declaration with any types used. The signature has specific types and we need
> +access to those types which means the wrapper code needs to include header files
> +that define those types. There may also be specific defines needed to access
> +those types. A trace section can contain the following keys:
> +
> +- ``generator``: The generator defines the type of tracing being used.
> +
> +- ``headers``: List of sections that contain header file's keys.
> +
> +- ``header``: A header key. Typically the include code.
> +
> +- ``defines``: List of sections that contain defines.
> +
> +- ``define``: A define key. Typically the define code.
> +
> +- ``signatures``: List of function signature sections.
> +
> +- ``trace``: Functions that are instrumented with trace code.
> +
> +The trace section of the file: `test-trace.ini` is shown below. A trace section
> +can reference other trace sections of a specific type. This allows a trace
> +sections to build on other trace sections.
> +
> +.. code:: shell
> +
> + ; User application trace example.
> + ;
> + [test-trace]
> + generator = printf-generator
> + ; Just here for testing.
> + trace = test_trace_3
> +
> + [test-trace-funcs]
> + ; Parsed via the 'function-set', not parse as a 'trace'.
> + headers = test-headers
> + header = '#include "test-trace-2.h"'
> + defines = test-defines
> + define = "#define TEST_TRACE_2 2"
> + signatures = test-signatures
> + ; Parsed via the 'trace', not parsed as a function-set
> + trace = test_trace_1, test_trace_2
> +
> + [test-headers]
> + header = '#include "test-trace-1.h"'
> +
> + [test-defines]
> + define = "#define TEST_TRACE_1 1"
> +
> + [test-signatures]
> + test_trace_1 = void, int
> + test_trace_2 = test_type_2, test_type_1
> + test_trace_3 = float, float*
> +
> +Function Section
> +----------------
> +
> +Function sections define functions that can be traced. They provide any required
> +defines, header files, and the function signatures. Defining a function so it
> +can be traced does not mean it is traced. The function must be added to a trace
> +list to be traced. A function section can consist of the following keys:
> +
> +- ``headers``: A list of sections containing headers or header records.
> +- ``header``: A list of include string that are single or double quoted.
> +- ``defines``: A list of sections containing defines or define record.
> +- ``defines``: A list of define string that are single or double quoted.
> +- ``signatures``: A list of section names of function signatures.
> +- ``includes``: A list of files to include.
> +
> +Function signatures are specified with the function name being the key's name
> +and the key's value being the return value and a list of function arguments. You
> +need to provide void if the function uses void. Variable argument list are
> +currently not supported. There is no way to determine statically a variable
> +argument list. The function section in the file: `test-trace.ini` has been
> +labeled as `test-trace-funcs`. This can be seen in the file snippet of the
> +previous section.
> +
> +Generators
> +----------
> +
> +Generator section specify how to generate trace wrapping code. The trace
> +linker and generator section must match to work. The trace linker expects a some
> +things to be present when wrapping functions. The section's name specifies the
> +generator and can be listed in a generator key in a tracer or trace section. If
> +the generator is not interested in a specific phase it does not need to define
> +it. Nothing will be generated in regard to this phase. For example code to
> +profile specific functions may only provide the entry-trace and exit-trace code
> +where a nano-second time stamp is taken.
> +
> +The generate code will create an entry and exit call and the generator code
> +block can be used to allocate buffer space for each with the lock held. The
> +entry call and argument copy is performed with the lock released. The buffer
> +space having been allocated will cause the trace events to be in order. The same
> +goes for the exit call. Space is allocated in separate buffer allocate calls so
> +the blocking calls will have the exit event appear in the correct location in
> +the buffer.
> +
> +The following keys can be a part of the generator configuration:
> +
> +- ``headers``: A list of sections containing headers or header records.
> +- ``header``: A list of include string that are single or double quoted.
> +- ``defines``: A list of sections containing defines or define record.
> +- ``define``: A list of define string that are single or double quoted.
> +- ``entry-trace``: The wrapper call made on a function's entry. Returns bool
> + where true is the function is being traced. This call is made without the lock
> + being held if a lock is defined.
> +- ``arg-trace``: The wrapper call made for each argument to the trace function
> + if the function is being traced. This call is made without the lock being held
> + if a lock is defined.
> +- ``exit-trace``: The wrapper call made after a function's exit. Returns bool
> + where true is the function is being traced. This call is made without the lock
> + being held if a lock is defined.
> +- ``ret-trace``: The wrapper call made to log the return value if the function
> + is being traced. This call is made without the lock being held if a lock is
> + defined.
> +- ``lock-local``: The wrapper code to declare a local lock variable.
> +- ``lock-acquire``: The wrapper code to acquire the lock.
> +- ``lock-release``: The wrapper code to release the lock.
> +- ``buffer-local``: The wrapper code to declare a buffer index local variable.
> +- ``buffer-alloc``: The wrapper call made with a lock held if defined to
> + allocate buffer space to hold the trace data. A suitable 32bit buffer index is
> + returned. If there is no space an invalid index is returned. The generator
> + must handle any overhead space needed. The generator needs to make sure the
> + space is available before making the alloc all.
> +- ``code-blocks``: A list of code block section names.
> +- ``code``: A code block in <<CODE --- CODE (without the single quote).
> +- ``includes``: A list of files to include.
> +
> +The following macros can be used in wrapper calls:
> +
> +- ``@FUNC_NAME@``: The trace function name as a quote C string.
> +- ``@FUNC_INDEX@``: The trace function index as a held in the sorted list of
> + trace functions by the trace linker. It can be used to index the names,
> + enables, and triggers data.
> +- ``@FUNC_LABEL@``: The trace function name as a C label that can be referenced.
> + You can take the address of the label.
> +- ``@FUNC_DATA_SIZE@``: The size of the data in bytes.
> +- ``@FUNC_DATA_ENTRY_SIZE@``: The size of the entry data in bytes.
> +- ``@FUNC_DATA_RET_SIZE@``: The size of the return data in bytes.
> +- ``@ARG_NUM@``: The argument number to the trace function.
> +- ``@ARG_TYPE@``: The type of the argument as a C string.
> +- ``@ARG_SIZE@``: The size of the type of the argument in bytes.
> +- ``@ARG_LABEL@``: The argument as a C label that can be referenced.
> +- ``@RET_TYPE@``: The type of the return value as a C string.
> +- ``@RET_SIZE@``: The size of the type of the return value in bytes.
> +- ``@RET_LABEL@``: The return value as a C label that can be referenced.
> +
> +The `buffer-alloc`, `entry-trace`, and `exit-trace` can be transformed using the
> +following macros:
> +
> +- ``@FUNC_NAME@``
> +- ``@FUNC_INDEX@``
> +- ``@FUNC_LABEL@``
> +- ``@FUNC_DATA_SZIE@``
> +- ``@FUNC_DATA_ENTRY_SZIE@``
> +- ``@FUNC_DATA_EXIT_SZIE@``
> +
> +The `arg-trace` can be transformed using the following macros:
> +
> +- ``@ARG_NUM@``
> +- ``@ARG_TYPE@``
> +- ``@ARG_SIZE@``
> +- ``@ARG_LABEL@``
> +
> +The `ret-trace` can be transformed using the following macros:
> +
> +- ``@RET_TYPE@``
> +- ``@RET_SIZE@``
> +- ``@RET_LABEL@``
> +
> +The file: `test-trace.ini` specifies ``printf-generator`` as its generator. This
> +section can be found in the file: `rtld-print.ini` in the rtems-tools directory
> +and is shown below:
> +
> +.. code:: shell
> +
> + ;
> + ; A printf generator prints to stdout the trace functions.
> + ;
> + [printf-generator]
> + headers = printf-generator-headers
> + entry-trace = "rtld_pg_printf_entry(@FUNC_NAME@, (void*) &@FUNC_LABEL@);"
> + arg-trace = "rtld_pg_printf_arg(@ARG_NUM@, @ARG_TYPE@, @ARG_SIZE@, (void*) &@ARG_LABEL@);"
> + exit-trace = "rtld_pg_printf_exit(@FUNC_NAME@, (void*) &@FUNC_LABEL@);"
> + ret-trace = "rtld_pg_printf_ret(@RET_TYPE@, @RET_SIZE@, (void*) &@RET_LABEL@);"
> + code = <<<CODE
> + static inline void rtld_pg_printf_entry(const char* func_name,
> + void* func_addr)
> + {
> + printf (">>> %s (0x%08x)\n", func_name, func_addr);
> + }
> + static inline void rtld_pg_printf_arg(int arg_num,
> + const char* arg_type,
> + int arg_size,
> + void* arg)
> + {
> + const unsigned char* p = arg;
> + int i;
> + printf (" %2d] %s(%d) = ", arg_num, arg_type, arg_size);
> + for (i = 0; i < arg_size; ++i, ++p) printf ("%02x", (unsigned int) *p);
> + printf ("\n");
> + }
> + static inline void rtld_pg_printf_exit(const char* func_name,
> + void* func_addr)
> + {
> + printf ("<<< %s (0x%08x)\n", func_name, func_addr);
> + }
> + static inline void rtld_pg_printf_ret(const char* ret_type,
> + int ret_size,
> + void* ret)
> + {
> + const unsigned char* p = ret;
> + int i;
> + printf (" rt] %s(%d) = ", ret_type, ret_size);
> + for (i = 0; i < ret_size; ++i, ++p) printf ("%02x", (unsigned int) *p);
> + printf ("\n");
> + }
> + CODE
> +
> + [printf-generator-headers]
> + header = "#include <stdio.h>"
> +
> +Function Wrapping
> +=================
> +
> +The trace linker's major role is to wrap functions in the existing executable
> +with trace code. The directions on how to wrap application functions is provided
> +by the generator configuration. The wrapping function uses a GNU linker option
> +called --wrap=symbol. The GNU Ld manual states:
> +
> +"Use a wrapper function for symbol. Any undefined reference to symbol will be
> +resolved to __wrap_symbol. Any undefined reference to __real_symbol will be
> +resolved to symbol."
> +
> +The trace linker generates C code with a wrapper for each function to be
> +instrumented. The trace code generated is driven by the configuration INI files.
> +
> +Function Signatures
> +===================
> +
> +A function signature is the function's declaration. It is the name of the
> +function, the return value, and the arguments. Tracing using function wrappers
> +requires that we have accurate function signatures and ideally we would like to
> +determine the function signature from the data held in ELF files. ELF files can
> +contain DWARF data, the ELF debugging data format. In time the trace project
> +would like to support libdwarf so the DWARF data can be accessed and used to
> +determine a function's signature. This work is planned but not scheduled to be
> +done and so in the meantime we explicitly define the function signatures in the
> +configuration files.
> +
These two sections "Function Wrapping" and "Function Signatures" seem
misplaced. I suspect they belong before Generators, maybe merged with
the "Function Sections" part?
> +
> +Development
> +===========
> +
> +The Trace Linker is part of the RTEMS tools git repository available at :
> +https://git.rtems.org/rtems-tools
> +The RTEMS tools project utilizes the waf build system. Use the following
> +commands in the topmost build directory to build the tools project:
> +
> +First we configure using:
> +
> +.. code-block:: shell
> +
> + $./waf configure --prefix=$HOME/development/rtems/5
> +
> +Then we build and install using:
> +
> +.. code-block:: shell
> +
> + $./waf build install
> +
> +
> --
> 2.7.4
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
More information about the devel
mailing list