<div dir="ltr"><div>Hi</div><div><br></div><div>I have made the changes you suggested. I am still working on CTF support. <br></div><div><span style="color:rgb(116,27,71)"><br></span></div><div><span style="color:rgb(116,27,71)">>> + $ ../samples<br>>What is this command?</span></div><div><br></div><div><font color="#000000">This is not a command. It is used to show which directory we are in. This method was used in the quickstart section. But I have removed this.</font></div><div><font color="#000000"><br></font></div><div><span style="color:rgb(76,17,48)">>There is some doco that would be good to have in master now and somewhich needs<br>
>to wait. Should this be split do we can do this?<br>
</span></div><div><br></div><div>I could complete the tracing examples page and the trace linker page and remove the CTF portion and submit another patch?</div><div>The section on use cases and CTF are under development. <br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Jun 13, 2018 at 7:26 AM, Chris Johns <span dir="ltr"><<a href="mailto:chrisj@rtems.org" target="_blank">chrisj@rtems.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi,<br>
<br>
This documentation looks good and I welcome this being done and added to the<br>
RTEMS project.<br>
<br>
I have some comments below I hope are easy to resolve.<br>
<br>
Thanks<br>
Chris<br>
<div><div class="h5"><br>
On 13/06/2018 11:23, Vidushi Vashishth wrote:<br>
> ---<br>
> user/index.rst | 2 +<br>
> user/tracing/captureengine.rst | 184 ++++++++++++++++++++++++++<br>
> user/tracing/examples.rst | 12 ++<br>
> user/tracing/index.rst | 29 +++++<br>
> user/tracing/introduction.rst | 182 ++++++++++++++++++++++++++<br>
> user/tracing/tracelinker.rst | 287 ++++++++++++++++++++++++++++++<wbr>+++++++++++<br>
> user/tracing/usecases.rst | 117 +++++++++++++++++<br>
> 7 files changed, 813 insertions(+)<br>
> create mode 100644 user/tracing/captureengine.rst<br>
> create mode 100644 user/tracing/examples.rst<br>
> create mode 100644 user/tracing/index.rst<br>
> create mode 100644 user/tracing/introduction.rst<br>
> create mode 100644 user/tracing/tracelinker.rst<br>
> create mode 100644 user/tracing/usecases.rst<br>
> <br>
> diff --git a/user/index.rst b/user/index.rst<br>
> index 8cbcd1b..a764fe8 100644<br>
> --- a/user/index.rst<br>
> +++ b/user/index.rst<br>
> @@ -52,6 +52,8 @@ to the Community Project hosted at <a href="http://www.rtems.org/" rel="noreferrer" target="_blank">http://www.rtems.org/</a>.<br>
> <br>
> tools/index<br>
> <br>
> + tracing/index<br>
> +<br>
> support/index<br>
> <br>
> glossary/index<br>
> diff --git a/user/tracing/captureengine.<wbr>rst b/user/tracing/captureengine.<wbr>rst<br>
> new file mode 100644<br>
> index 0000000..64b501a<br>
> --- /dev/null<br>
> +++ b/user/tracing/captureengine.<wbr>rst<br>
> @@ -0,0 +1,184 @@<br>
> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0<br>
> +<br>
> +.. comment: Copyright (c) 2016 Chris Johns <<a href="mailto:chrisj@rtems.org">chrisj@rtems.org</a>><br>
> +.. comment: All rights reserved.<br>
> +<br>
> +.. _capturengine:<br>
> +<br>
> +Capture Engine<br>
> +**************<br>
> +<br>
> +Capture Engine is a trace tool built inside the RTEMS operating system. Capture <br>
> +Engine is designed to cause the lowest load on the system when operating. Hence<br>
> +it does not effect RTEMS when operating or when disabled. It binds to RTEMS at<br>
> +runtime and does not require RTEMS or your application to be rebuilt in order<br>
> +to use it. <br>
> + <br>
> +The Capture Engine's sample testcase for the `sparc/erc32` is available in the<br>
> +"$HOME/development/rtems/<wbr>kernel/erc32/sparc-rtems5/c/<wbr>erc32/testsuites/samples" <br>
<br>
</div></div>Please use relative paths in the case. The<br>
"$HOME/development/rtems/<wbr>kernel/erc32" is specific to a user and while I have<br>
used this in the User Manual it does not mean it is mandatory.<br>
<br>
I suggest:<br>
<span class=""><br>
The Capture Engine's sample testcase for the `sparc/erc32` is available in the<br>
</span>build direct created when building RTEMS in the path<br>
file:`sparc-rtems5/c/erc32/<wbr>testsuites/samples` directory.<br>
<br>
Also please use file:`path` for paths and files.<br>
<span class=""><br>
> +directory, provided you followed the installation directions of the quickstart<br>
> +section. In order to access the capture testcase perform the following set of<br>
> +operations.<br>
> +<br>
> +.. code-block:: shell<br>
> +<br>
> + $ cd <br>
> + $HOME/development/rtems/<wbr>kernel/erc32/sparc-rtems5/c/<wbr>erc32/testsuites/samples<br>
<br>
</span>Please make relative.<br>
<br>
> + $ ../samples<br>
<br>
What is this command?<br>
<div><div class="h5"><br>
> + $ sparc-rtems5-run ./capture.exe<br>
> +<br>
> +<br>
> + *** BEGIN OF TEST CAPTURE ENGINE ***<br>
> + *** TEST VERSION: 5.0.0.<wbr>de9b7d712bf5da6593386fd4fbca0d<wbr>5f8b8431d8<br>
> + *** TEST STATE: USER_INPUT<br>
> + *** TEST BUILD: RTEMS_NETWORKING RTEMS_POSIX_API<br>
> + *** TEST TOOLS: 7.3.0 20180125 (RTEMS 5, RSB <br>
> + a3a6c34c150a357e57769a26a460c4<wbr>75e188438f, Newlib 3.0.0)<br>
> + Press any key to start capture engine (20s remaining)<br>
> + Press any key to start capture engine (19s remaining)<br>
> + Press any key to start capture engine (18s remaining)<br>
> +<br>
> + Monitor ready, press enter to login.<br>
> +<br>
> + 1-rtems $<br>
> +<br>
> +Capture Engine comes with a set of commands to perform various actions. <br>
> +<br>
> +Capture Engine Commands<br>
> +-----------------------<br>
> +<br>
> +1) ``copen <buffer-size>``: Used to initialize the Capture Engine with the <br>
> + trace buffer size in bytes. By default the Capture Engine is not initialized <br>
> + and not running.<br>
> +<br>
> +2) ``cwceil <priority-value>``: Capture Engine filter used to put an upper <br>
> + limit on the event priority to be captured. <br>
> +<br>
> +<br>
> +3) ``cwfloor <priority-value>``: Capture Engine filter used to put a lower <br>
> + limit on the event priority to be captured.<br>
> +<br>
> +<br>
> +4) ``cwglob <on/off>``: Enable or disable the global watch. <br>
> +<br>
> +<br>
> +5) ``cenable``: Enables the Capture Engine. Capture Engine is by default <br>
> + disabled after being opened.<br>
> +<br>
> +<br>
> +6) ``cdisable``: Disables the Capture Engine. <br>
> +<br>
> +<br>
> +7) ``ctlist``: Lists the watch and trigger configurations. <br>
> +<br>
> +<br>
> +8) ``ctrace``: Dumps the recorded traces. By default this command displays 24 <br>
> + trace records. Repeated use of this command will display all the recorded <br>
> + traces. <br>
> +<br>
> +9) ``cwadd <task-name>``: Add watch on a particular task.<br>
> +<br>
> +<br>
> +10) ``cwtctl <task-name> <on/off>``: Enable or disable watch on a particular <br>
> + task.<br>
> +<br>
> + <br>
> +11) ``ctset``: Used to set a trigger. The general form of the command is:<br>
> +<br>
> +``ctset [-?] type [to name/id] [from] [from name/id]``<br>
> +<br>
> +'type' in the above command refers to the type of trigger needed. The types of <br>
> +triggers that currently exist<br>
> +are:<br>
> +<br>
> +- switch : a context switch from one task to another task<br>
> +- create : the executing task creates a task<br>
> +- start : the executing task starts a task<br>
> +- restart : the executing task restarts a task<br>
> +- delete : the executing task deletes a task<br>
> +- begin : a task is beginning<br>
> +- exitted : a task is exitting<br>
> +<br>
> +Example<br>
> +-------<br>
> +<br>
> +The following is a sample run of the capture testsuite. The test1 command on the<br>
<br>
</div></div>Change test1 to `test1` and please change others below as needed. For example<br>
'RMON' to `RMON`, ie most '' to ``.<br>
<div><div class="h5"><br>
> +Capture Engine Command Line Interface (CLI) makes the 'RMON' task invoke a call <br>
> +to the 'capture_test_1()' command. This function (in the 'test1.c' source code)<br>
> +creates and starts three tasks : 'CT1a', 'CT1b' and 'CT1c'. These tasks are <br>
> +passed the object id of a semaphore as a task argument. This run through traces<br>
> +the context switches between these tasks. ``cwceil`` and ``cwfloor`` are set to <br>
> +a narrow range of task priorities to avoid creating noise from a large number of<br>
> +context switches between tasks we are not interested in. <br>
> +<br>
> +.. code:: shell<br>
> + <br>
> + *** BEGIN OF TEST CAPTURE ENGINE ***<br>
> + *** TEST VERSION: 5.0.0.<wbr>de9b7d712bf5da6593386fd4fbca0d<wbr>5f8b8431d8<br>
> + *** TEST STATE: USER_INPUT<br>
> + *** TEST BUILD: RTEMS_NETWORKING RTEMS_POSIX_API<br>
> + *** TEST TOOLS: 7.3.0 20180125 (RTEMS 5, RSB <br>
> + a3a6c34c150a357e57769a26a460c4<wbr>75e188438f, Newlib 3.0.0)<br>
> + Press any key to start capture engine (20s remaining)<br>
> + Press any key to start capture engine (19s remaining)<br>
> + Press any key to start capture engine (18s remaining)<br>
> + Press any key to start capture engine (17s remaining)<br>
> +<br>
> + Monitor ready, press enter to login.<br>
> +<br>
> + 1-rtems $ copen 50000<br>
> + capture engine opened.<br>
> + 1-rtems $ cwceil 100 <br>
> + watch ceiling is 100.<br>
> + 1-rtems $ cwfloor 102<br>
> + watch floor is 102.<br>
> + 1-rtems $ cwglob on<br>
> + global watch enabled.<br>
> + 1-rtems $ ctset RMON<br>
> + trigger set.<br>
> + 1-rtems $ cenable<br>
> + capture engine enabled.<br>
> + 1-rtems $ test1<br>
> + 1-rtems $ cdisable<br>
> + capture engine disabled.<br>
> + 1-rtems $ ctrace<br>
> + 0 0:18:17.462314124 0a010003 CT1a 102 102 102 4096 TASK_RECORD<br>
> + 0 0:18:17.462398963 0 0a010003 CT1a 102 102 CREATED<br>
> + 0 0:18:17.462647987 249024 0a010003 CT1a 102 102 STARTED<br>
> + 0 0:18:17.462904334 256347 0a010003 CT1a 102 102 SWITCHED_IN<br>
> + 0 0:18:17.463069129 164795 0a010003 CT1a 102 102 BEGIN<br>
> + 0 0:18:17.463335853 266724 0a010003 CT1a 102 102 SWITCHED_OUT<br>
> + 0 0:18:18.461348547 0a010004 CT1b 101 101 101 4096 TASK_RECORD<br>
> + 0 0:18:18.461433997 998098144 0a010004 CT1b 101 101 CREATED<br>
> + 0 0:18:18.461683631 249634 0a010004 CT1b 101 101 STARTED<br>
> + 0 0:18:18.461934485 250854 0a010004 CT1b 101 101 SWITCHED_IN<br>
> + 0 0:18:18.462099891 165406 0a010004 CT1b 101 101 BEGIN<br>
> + 0 0:18:19.460935339 998835448 0a010004 CT1b 101 101 SWITCHED_OUT<br>
> + 0 0:18:19.461431555 0a010005 CT1c 100 100 100 4096 TASK_RECORD<br>
> + 0 0:18:19.461516394 581055 0a010005 CT1c 100 100 CREATED<br>
> + 0 0:18:19.461765418 249024 0a010005 CT1c 100 100 STARTED<br>
> + 0 0:18:19.462019324 253906 0a010005 CT1c 100 100 SWITCHED_IN<br>
> + 0 0:18:19.462184119 164795 0a010005 CT1c 100 100 BEGIN<br>
> + 0 0:18:19.462475257 291138 0a010005 CT1c 100 100 SWITCHED_OUT<br>
> + 0 0:18:19.462551551 76294 0a010004 CT1b 101 101 SWITCHED_IN<br>
> + 0 0:18:19.960935645 498384094 0a010004 CT1b 101 101 SWITCHED_OUT<br>
> + 0 0:18:19.961012549 76904 0a010003 CT1a 102 100 SWITCHED_IN<br>
> + 0 0:18:19.961341528 328979 0a010003 CT1a 102 102 SWITCHED_OUT<br>
> + 1-rtems $ ctrace<br>
> + 0 0:18:19.961418433 0 0a010005 CT1c 100 100 SWITCHED_IN<br>
> + 0 0:18:19.961672339 253906 0a010005 CT1c 100 100 SWITCHED_OUT<br>
> + 0 0:18:19.961749854 77515 0a010004 CT1b 101 101 SWITCHED_IN<br>
> + 0 0:18:20.460967077 499217223 0a010004 CT1b 101 101 SWITCHED_OUT<br>
> + 0 0:18:20.461219763 252686 0a010005 CT1c 100 100 SWITCHED_IN<br>
> + 0 0:18:20.461424231 204468 0a010005 CT1c 100 100 TERMINATED<br>
> + 0 0:18:20.461747107 322876 0a010005 CT1c 100 100 SWITCHED_OUT<br>
> + 0 0:18:20.461824011 76904 0a010004 CT1b 101 101 SWITCHED_IN<br>
> + 0 0:18:20.462015052 191041 0a010004 CT1b 101 101 TERMINATED<br>
> + 0 0:18:20.462336707 321655 0a010004 CT1b 101 101 SWITCHED_OUT<br>
> + 0 0:18:20.462414222 77515 0a010003 CT1a 102 102 SWITCHED_IN<br>
> + 0 0:18:20.462608924 194702 0a010003 CT1a 102 102 TERMINATED<br>
> + 0 0:18:20.462933021 324097 0a010003 CT1a 102 102 SWITCHED_OUT<br>
> + 1-rtems $ ctrace<br>
> + 1-rtems $ <br>
> +<br>
> +<br>
> diff --git a/user/tracing/examples.rst b/user/tracing/examples.rst<br>
> new file mode 100644<br>
> index 0000000..f51613e<br>
> --- /dev/null<br>
> +++ b/user/tracing/examples.rst<br>
> @@ -0,0 +1,12 @@<br>
> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0<br>
> +<br>
> +.. comment: Copyright (c) 2016 Chris Johns <<a href="mailto:chrisj@rtems.org">chrisj@rtems.org</a>><br>
> +.. comment: All rights reserved.<br>
> +<br>
> +.. _examples:<br>
> +<br>
> +Tracing Examples<br>
> +****************<br>
> +<br>
> +[TBD]<br>
> +<br>
> diff --git a/user/tracing/index.rst b/user/tracing/index.rst<br>
> new file mode 100644<br>
> index 0000000..951ead2<br>
> --- /dev/null<br>
> +++ b/user/tracing/index.rst<br>
> @@ -0,0 +1,29 @@<br>
> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0<br>
> +<br>
> +.. comment: Copyright (c) 2016 Chris Johns <<a href="mailto:chrisj@rtems.org">chrisj@rtems.org</a>><br>
> +.. comment: All rights reserved.<br>
> +<br>
> +.. _tracing-framework:<br>
> +<br>
> +RTEMS Tracing Framework<br>
> +***********************<br>
> +.. index:: Tracing Framework<br>
> +<br>
> +RTEMS Tracing Framework is an on-target software based system which helps track<br>
> +the ongoings inside applications, 3rd party packages, and the kernel in real <br>
<br>
</div></div>ongoings inside => the operation of<br>
<div><div class="h5"><br>
> +time.<br>
> +<br>
> +Software based tracing is a complex process which requires components on both <br>
> +the target and the host to work together. However its portability across all <br>
> +architectures and board support packages makes it a useful asset. A key<br>
> +requirement in RTEMS trace process is to take existing code in compiled format<br>
> +(ELF) and instrument it in order to log various events and records in real time.<br>
> +However instrumenting of the code for tracing should happen without rebuilding<br>
> +the code from the source and without annotating the source with trace code.<br>
> +<br>
> +.. toctree::<br>
> +<br>
> + introduction<br>
> + usecases<br>
> + examples<br>
> +<br>
> diff --git a/user/tracing/introduction.<wbr>rst b/user/tracing/introduction.<wbr>rst<br>
> new file mode 100644<br>
> index 0000000..640eb0c<br>
> --- /dev/null<br>
> +++ b/user/tracing/introduction.<wbr>rst<br>
> @@ -0,0 +1,182 @@<br>
> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0<br>
> +<br>
> +.. comment: Copyright (c) 2016 Chris Johns <<a href="mailto:chrisj@rtems.org">chrisj@rtems.org</a>><br>
> +.. comment: All rights reserved.<br>
> +<br>
> +.. _introduction:<br>
> +<br>
> +Introduction to Tracing<br>
> +***********************<br>
> +<br>
> +Tracing is an important function which has several applications including<br>
> +identification of complex threading, detection of deadlocks, tracing<br>
> +functions along with their argument values, and return values through<br>
> +progression of several function calls and audit the performance of an<br>
> +application according to required specifications. <br>
> +<br>
> +RTEMS tracing framework is under development and welcomes contribution by users.<br>
> +<br>
> +RTEMS has the following trace components:<br>
> +<br>
> +- RTEMS :ref:`tracelinker`<br>
> +- RTEMS :ref:`capturengine`<br>
> +- Common Trace Format Integration<br>
> +<br>
> +<br>
> +RTEMS trace framework can currently function using the following methods. Both <br>
> +of the methods make use of the :ref:`tracelinker` :<br>
> +<br>
> +.. _tracebuffering:<br>
> +<br>
> +RTEMS Trace Using Trace Buffering<br>
> +=============================<wbr>====<br>
> +<br>
> +This scheme of tracing goes through the flow of events described in a<br>
> +subsequent flowchart:<br>
> +<br>
> +Step 1: The user creates an application and user configuration file. The <br>
> +configuration file specifies the use of the trace buffer generator and other<br>
> +standard initializations. The user then configures her BSP and invokes the<br>
<br>
</div></div>her => their<br>
<div><div class="h5"><br>
> +trace linker using a command to link the application executable. The trace <br>
> +linker uses the application files in compiled format (ELF) and the libraries<br>
> +used to build the application for performing this link.<br>
> +<br>
> +Step 2: The RTEMS Trace Linker reads the user’s configuration file and that <br>
> +results in it reading the standard Trace Buffering Configuration files<br>
> +installed with the RTEMS Trace Linker. The trace linker uses the target<br>
> +compiler and linker to create the trace enabled application executable. It<br>
> +wraps the functions defined in the user’s configuration with code that captures<br>
> +trace records into the statically allocated buffer. The trace wrapper code is<br>
> +compiled with the target compiler and the resulting ELF object file is added to<br>
> +the standard link command line used to link the application and the application<br>
> +is re-linked using the wrapping option of the GNU linker.<br>
> +<br>
> +Step 3: The trace linker creates an executable which is capable of running on <br>
> +the target hardware or simulator.<br>
> +<br>
> +Step 4: RTEMS shell provides the “rtrace” command to display and save trace<br>
> +buffers. <br>
> +<br>
> +.. comment: taken from <a href="https://devel.rtems.org/wiki/Developer/Tracing" rel="noreferrer" target="_blank">https://devel.rtems.org/wiki/<wbr>Developer/Tracing</a><br>
> +.. figure:: ../../images/user/rtems-trace-<wbr>buffering.png<br>
> + :align: center<br>
> + :width: 75%<br>
> +<br>
<br>
</div></div>White space.<br>
<div><div class="h5"><br>
> +<br>
> +.. _printk:<br>
> +<br>
> +RTEMS Trace Using Printk<br>
> +========================<br>
> +<br>
> +This scheme of tracing goes through the flow of events described in a subsequent<br>
> +flowchart:<br>
> +<br>
> +Step 1: The user creates an RTEMS application in the normal manner as well as a<br>
> +Trace Linker configuration file. The configuration file specifies using the <br>
> +Printk trace mode and the functions to trace. The user invokes the Trace Linker<br>
> +with the configuration and the normal link command line used to the link the<br>
> +application executable. The application ELF object files and libraries,<br>
> +including the RTEMS libraries are standard and do not need to be built<br>
> +specially. <br>
> +<br>
> +Step 2: The RTEMS Trace Linker reads the user's configuration file and that<br>
> +results in it reading the standard Printk Trace Configuration files installed<br>
> +with the RTEMS Trace Linker. The trace linker uses the target compiler and <br>
> +linker to create the trace enabled application executable. It wraps the <br>
> +functions defined in the user's configuration with code that prints the entry <br>
> +with arguments and exit and return value if any. The trace wrapper code is<br>
> +compiled with the target compiler and the resulting ELF object file is added to<br>
> +the standard link command line used to link the application and the application<br>
> +is relinked using the wrapping option of the GNU linker. <br>
> +<br>
> +Step 3: The trace linker creates and RTEMS ELF executable that can be run on the<br>
> +target hardware or simulator. <br>
> +<br>
> +Step 4: The application is run in the hardware directly or using a debugger. The<br>
> +printk() output appears on the target console and the user can save that to a file. <br>
> +<br>
> +.. comment: taken from <a href="https://devel.rtems.org/wiki/Developer/Tracing" rel="noreferrer" target="_blank">https://devel.rtems.org/wiki/<wbr>Developer/Tracing</a><br>
> +.. figure:: ../../images/user/rtems-trace-<wbr>printk.png<br>
> + :align: center<br>
> + :width: 75%<br>
> +<br>
> +The :ref:`examples` section describes generation of traces using both of the <br>
> +aforementioned techniques using the `fileio` testsuite available with RTEMS<br>
> +installation.<br>
> +<br>
> +RTEMS Trace Using CTF<br>
> +=====================<br>
> +<br>
> +`Common Trace Format <<a href="http://diamon.org/ctf/" rel="noreferrer" target="_blank">http://diamon.org/ctf/</a>>`_ (CTF) is a binary trace format <br>
> +which is fast to write and has great flexibility. It allows traces to be<br>
> +developed by bare-metal applications or by any other C/C++ system. RTEMS tracing<br>
> +framework can benefit from these features of CTF. <br>
<br>
</div></div>Is CTF support available for all users? If this is pushed to master it will be<br>
in the main doco.<br>
<br>
There is some doco that would be good to have in master now and somewhich needs<br>
to wait. Should this be split do we can do this?<br>
<div><div class="h5"><br>
> +<br>
> +A typical CTF *trace* consists of multiple *streams* of binary *events*. The<br>
> +*metadata* stream is a mandatory stream which describes the layout of all the<br>
> +other streams in a trace. This metadata stream is written using *Trace Stream<br>
> +Description Language* (TSDL).<br>
> +<br>
> +.. comment: image taken from view-source:<a href="http://diamon.org/ctf/img/ctf-trace.png" rel="noreferrer" target="_blank">http://diamon.org/<wbr>ctf/img/ctf-trace.png</a><br>
> +.. comment: Not generating a copyright in the high chance we decide to not keep <br>
> +.. comment: a descriptive section on CTF<br>
> +<br>
> +.. figure:: ../../images/user/ctf-trace.<wbr>png<br>
> + :align: center<br>
> + :width: 75%<br>
> +<br>
> +A binary *stream* is further a concatenation of several packets each containing <br>
> +the following:<br>
> +<br>
> +- A packet header<br>
> +- An optional packet context<br>
> +- A set of concatenated events each containing:<br>
> + - An event header<br>
> + - A stream-specific context<br>
> + - An event-specific context<br>
> + - A payload<br>
> +<br>
> +.. comment: taken from <a href="http://diamon.org/ctf/img/ctf-stream-packet.png" rel="noreferrer" target="_blank">http://diamon.org/ctf/img/ctf-<wbr>stream-packet.png</a><br>
> +.. comment: Not generating a copyright in the high chance we decide to not keep <br>
> +.. comment: a descriptive section on CTF<br>
> +<br>
> +.. figure:: ../../images/user/ctf-stream-<wbr>packet.png<br>
> + :align: center<br>
> + :width: 75%<br>
> +<br>
> +All the headers, contexts and payloads are written in TSDL using CTF data types.<br>
> +CTF supports a rich set of configurable datatypes which makes it possible to<br>
> +describe a larger variety of binary structure. Moreover types in CTF are <br>
> +organized as type classes where type specifications can be inherited to allow<br>
> +deriving types. These factors make CTF flexible. CTF enables fast writing of<br>
> +binary data as it usually involves appending memory contents, as it is to a<br>
> +binary CTF stream. CTF streams are capable of being sent or received over the<br>
> +network without any data being written to disk and hence can be useful in<br>
> +transporting traces from the target to the host machine for analysis. <br>
> +<br>
> +Due to these advantages tracing using CTF will prove to be beneficial for the <br>
> +users. This method of tracing is currently under development. Currently the<br>
> +RTEMS tracing framework is able to output trace data in the form of trace<br>
> +buffers, console output and csv files. A conversion tool which transforms <br>
> +these trace output formats to CTF will be viable approach to generating CTF<br>
> +traces. In this regard we utilize babeltrace, which is described in the<br>
> +following section. <br>
> +<br>
> +Babeltrace<br>
> +----------<br>
> +<br>
> +Babeltrace is an open source trace format converter which can be used to convert<br>
> +RTEMS traces into CTF. It is also a reference parser implementation of CTF. Babeltrace<br>
> +currently supports the following output formats for traces:<br>
> +<br>
> +- Text<br>
> +- CTF<br>
> +- CTF-metadata<br>
> +- Dummy<br>
> +- lttng-live <br>
> +<br>
> +Babeltrace comes in the form of a library, python bindings (python3) and command line<br>
> +tool called ``babeltrace``. To install babeltrace on your host you can install a<br>
> +distribution package or build from source using tarballs or git repositories of<br>
> +babeltrace. Refer to <a href="http://diamon.org/babeltrace/" rel="noreferrer" target="_blank">http://diamon.org/babeltrace/</a> for further details.<br>
> +<br>
> diff --git a/user/tracing/tracelinker.rst b/user/tracing/tracelinker.rst<br>
> new file mode 100644<br>
> index 0000000..3340794<br>
> --- /dev/null<br>
> +++ b/user/tracing/tracelinker.rst<br>
> @@ -0,0 +1,287 @@<br>
> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0<br>
> +<br>
> +.. comment: Copyright (c) 2016 Chris Johns <<a href="mailto:chrisj@rtems.org">chrisj@rtems.org</a>><br>
> +.. comment: All rights reserved.<br>
> +<br>
> +.. _tracelinker:<br>
> +<br>
> +Trace Linker<br>
> +************<br>
> +<br>
> +RTEMS trace linker is a post link tool central to the RTEMS trace framework. It <br>
> +is installed as a part of the RTEMS Tool Project.The RTEMS Trace Linker is a<br>
> +post link tool that performs a re-link of your application to produce a trace<br>
> +executable. A trace executable has been instrumented by the RTEMS Trace Linker<br>
> +with additional code that implements software tracing. A key requirement of the<br>
> +trace process in RTEMS is to take existing code in a compiled format (ELF) and <br>
> +instrument it without rebuilding that code from source and without annotating<br>
> +that source with trace code.<br>
> +<br>
> +<br>
> +Command Line<br>
> +============<br>
> +<br>
> +A typical command to invoke the trace linker consists of two parts separated by <br>
> +``--``. The first part controls the trace linker and provides the various<br>
> +options it needs and the second part is a standard linker command line you would<br>
> +use to link an RTEMS application. The current command line for trace linker consists<br>
> +of:<br>
> +<br>
> +.. code-block:: shell<br>
> +<br>
> + $ rtems-tld -h<br>
> + rtems-trace-ld [options] objects<br>
> + Options and arguments:<br>
> + -h : help (also --help)<br>
> + -V : print linker version number and exit (also --version)<br>
> + -v : verbose (trace import parts), can supply multiple times<br>
> + to increase verbosity (also --verbose)<br>
> + -w : generate warnings (also --warn)<br>
> + -k : keep temporary files (also --keep)<br>
> + -c compiler : target compiler is not standard (also --compiler)<br>
> + -l linker : target linker is not standard (also --linker)<br>
> + -E prefix : the RTEMS tool prefix (also --exec-prefix)<br>
> + -f cflags : C compiler flags (also --cflags)<br>
> + -r path : RTEMS path (also --rtems)<br>
> + -B bsp : RTEMS arch/bsp (also --rtems-bsp)<br>
> + -W wrapper : wrapper file name without ext (also --wrapper)<br>
> + -C ini : user configuration INI file (also --config)<br>
> + -P path : user configuration INI file search path (also --path)<br>
> +<br>
> +The trace linker generates code that needs to be compiled and linked to the <br>
> +application executable so it needs to know the target compiler and `CFLAGS`.<br>
> +There are a couple of ways to do this. The simplest is to provide the path to<br>
> +RTEMS using the `-r` option and the architecture and BSP name in the standard<br>
> +RTEMS format of arch/bsp. The trace linker will extract the compiler and flags <br>
> +used to build RTEMS and will use them. If you require specific options you can<br>
> +use the `-f`, `-c`, `-l` and `-E` options to provide them. If the functions you<br>
> +are tracing use types from your code then add the include path to the `CFLAGS`.<br>
> +<br>
> +The trace linker requires you to provide a user configuration file using the <br>
> +`-C` or ``--config`` option. This is an INI format file detailed in the<br>
> +Configuration section. You can also provide an INI file search path using the<br>
> +`-P` option.<br>
> +<br>
> +If you are working with new configuration files and you want to view the files <br>
> +the trace linker generates add the `-k` option to keep the temporary files, and<br>
> +`-W` to specify an explicit wrapper C file name. If you set the<br>
> +``dump-on-error`` option in the configuration options section you will get a<br>
> +dump of the configuration on an error.<br>
> +<br>
> +<br>
> +Configuration (INI) files<br>
> +=========================<br>
> +<br>
> +The Trace Linker is controlled using configuration files. Configuration files <br>
> +are categorized into 3 types:<br>
> +<br>
> +- User Configuration: These are specific to the user application to be traced. <br>
> + This file initializes the values of the trace generator, triggers, enables and <br>
> + traces. <br>
> +<br>
> +- Tracer Configuration: These are like a library of common or base trace <br>
> + functions that can be referenced by an application. These files tend to hold <br>
> + the details needed to wrap a specific set of functions. Examples provided with <br>
> + the RTEMS Linker are the RTEMS API and Libc.<br>
> +<br>
> +- Generator Configuration: This is used to encapsulate a specific method of <br>
> + tracing. Rtems currently provides generators for trace buffering, printk and <br>
> + printf.<br>
> +<br>
> +The configuration files are in the *INI file format* which is composed of <br>
> +`sections`. Each section has a section name and set of *keys* which consist of<br>
> +*names* and *values*. A typical key is of the form ``name=value``. Keys can be<br>
> +used to include other INI files using the include key name. This is shown in the<br>
> +following example where the values indicate rtems and rtld-base configuration files:<br>
> +<br>
> +.. code-block::shell<br>
> + include = rtems.ini, rtld-base.ini<br>
> +<br>
> +The trace linker also uses values in keys to specify other sections. In this <br>
> +example the functions name lists test-trace-funcs and that section contains a headers<br>
> +key that references a further section test-headers: <br>
> +<br>
> +.. code-block::shell<br>
> + functions = test-trace-funcs, rtems-api<br>
> +<br>
> + [test-trace-funcs]<br>
> + ; Parsed via the 'function-set', not parse as a 'trace'.<br>
> + headers = test-headers<br>
> +<br>
> + [test-headers] <br>
> + header = '#include "test-trace-1.h"'<br>
> +<br>
> +The format of a configuration file is explained next. Snippets of the fileio-trace.ini<br>
> +file have been used for explicit understanding. This file can be downloaded from `here <br>
> +<<a href="https://devel.rtems.org/attachment/wiki/Developer/Tracing/Trace_Buffering/filei" rel="noreferrer" target="_blank">https://devel.rtems.org/<wbr>attachment/wiki/Developer/<wbr>Tracing/Trace_Buffering/filei</a><br>
> +o-trace.ini>`_.<br>
> +<br>
> +Tracer Section<br>
> +--------------<br>
> +<br>
> +The topmost level section is the ``tracer`` section. It can contains the <br>
> +following keys:<br>
> +<br>
> +- name: The name of trace being linked. <br>
> +<br>
> +- options: A list of option sections. <br>
> +<br>
> +- defines: A list of sections containing defines or define record. <br>
> +<br>
> +- define: A list of define string that are single or double quoted. <br>
> +<br>
> +- enables: The list of sections containing enabled functions to trace. <br>
> +<br>
> +- triggers: The list of sections containing enabled functions to trigger trace <br>
> + on. <br>
> +<br>
> +- traces: The list of sections containing function lists to trace. <br>
> +<br>
> +- functions: The list of sections containing function details. <br>
> +<br>
> +- include: The list of files to include<br>
> +<br>
> +<br>
> +.. code-block:: shell<br>
> + [tracer]<br>
> + name = File IO tracer<br>
> + ;<br>
> + ; The configuration<br>
> + ;<br>
> + options = fileio-options<br>
> + traces = fileio<br>
> + defines = fileio<br>
> + enables = fileio<br>
> + triggers = fileio<br>
> + functions = fileio-funcs, rtems-api, rtems-posix, libc-heap<br>
> + include = rtems.ini, rtld-base.ini, rtld-trace-buffer.ini, libc-heap.ini<br>
> +<br>
> +<br>
> +Options section<br>
> +---------------<br>
> +<br>
> +The options section in the fileio-trace.ini is called the `fileio-options`. A <br>
> +general options section can contain following sets of keys:<br>
> +<br>
> +- dump-on-error: Dump the parsed configuration data on error. The value can be <br>
> + true or false. <br>
> +<br>
> +- verbose: Set the verbose level. The value can be true or a number value. <br>
> +<br>
> +- prefix: The prefix for the tools and an install RTEMS if rtems-path is not <br>
> + set. <br>
> +<br>
> +- cc: The compiler used to compile the generated wrapper code. Overrides the <br>
> + BSP configuration value if a BSP<br>
> + is specified. <br>
> +<br>
> +- ld: The linker used to link the application. The default is the cc value as <br>
> + read from the BSP configuration if specificed. If your application contains <br>
> + C++ code use this setting to the change the linker to g++. <br>
> +<br>
> +- cflags: Set the CFLAGS used to compiler the wrapper. These flags are <br>
> + pre-pended to the BSP read flags if a BSP is specified. This option is used<br>
> + to provide extra include paths to header files in your application that<br>
> + contain types any functions being traced reference. <br>
> +<br>
> +- rtems-path: The path to an install RTEMS if not installed under the prefix. <br>
> +<br>
> +- rtems-bsp: The BSP we are building the trace executable for. The is an arch <br>
> + and bsp pair. For example sparc/erc32. <br>
> +<br>
> +.. code-block:: shell<br>
> +<br>
> + [fileio-options]<br>
> + dump-on-error = true<br>
> + ;<br>
> + ; Tools<br>
> + ;<br>
> + prefix = /development/rtems/5<br>
> + rtems-path = /development/rtems/kernel/5<br>
> + rtems-bsp = sparc/erc32<br>
> + ;<br>
> + ; Generator options.<br>
> + ;<br>
> + gen-enables = enable<br>
> + gen-triggers = enable<br>
> +<br>
> +<br>
> +Trace Section<br>
> +--------------<br>
> +<br>
> +A trace section defines how trace wrapper functions are built. To build a trace <br>
> +function that wraps an existing function in an ELF object file or library<br>
> +archive we need to have the function's signature. A signature is the function's<br>
> +declaration with any types used. The the signature has specific types we need<br>
> +access to those types which means the wrapper code needs to include header files<br>
> +that define those types. There may also be specific defines needed to access<br>
> +those types.<br>
> +<br>
> +- generator: The generator defines the type of tracing being used. <br>
> +<br>
> +- headers: List of sections that contain header files keys. <br>
> +<br>
> +- header: A header key. Typically the include code. <br>
> +<br>
> +- defines: List of sections that contain defines. <br>
> +<br>
> +- define: A define key. Typically the define code. <br>
> +<br>
> +- signatures: List of function signature sections. <br>
> +<br>
> +- trace: Functions that are instrumented with trace code. <br>
> +<br>
> +<br>
> +[TBD]<br>
> +<br>
> +<br>
> +Function Wrapping<br>
> +=================<br>
> +<br>
> +The trace linker's major role is to wrap functions in the existing executable <br>
> +with trace code. The directions on how to wrap application functions is provided<br>
> +by the generator configuration. The wrapping function uses a GNU linker option<br>
> +called --wrap=symbol. The GNU Ld manual states:<br>
> +<br>
> +"Use a wrapper function for symbol. Any undefined reference to symbol will be <br>
> +resolved to __wrap_symbol. Any undefined reference to __real_symbol will be<br>
> +resolved to symbol."<br>
> +<br>
> +The trace linker generates C code with a wrapper for each function to be instrumented.<br>
> +The trace code generated is driven by the configuration INI files. <br>
> +<br>
> +<br>
> +Function Signatures<br>
> +===================<br>
> +<br>
> +A function signature is the function's declaration. It is the name of the<br>
> +function, the return value and the arguments. Tracing using function wrappers<br>
> +requires that we have accurate function signatures and ideally we would like to<br>
> +determine the function signature from the data held in ELF files. ELF files can<br>
> +contain DWARF data, the ELF debugging data format. In time the trace project<br>
> +would like to support libdwarf so the DWARF data can be accessed and use to determine<br>
> +a function's signature. This work is planned but not scheduled to be done and so in the<br>
> +meantime we explicitly define the function signatures in the configuration files. <br>
> +<br>
> +<br>
> +Development<br>
> +===========<br>
> +<br>
> +The Trace Linker is part of the RTEMS tools git repository available at : <br>
> +<a href="https://git.rtems.org/rtems-tools" rel="noreferrer" target="_blank">https://git.rtems.org/rtems-<wbr>tools</a><br>
> +The RTEMS tools project utilizes the waf build system. Use the following<br>
> +commands in the topmost build directory to build the tools project:<br>
> +<br>
> +First we configure using:<br>
> +<br>
> +.. code-block:: shell<br>
> + <br>
> + $./waf configure --prefix=$HOME/development/<wbr>rtems/5<br>
> +<br>
> +Then we build and install using:<br>
> +<br>
> +.. code-block:: shell<br>
> +<br>
> + $./waf build install<br>
> +<br>
> +<br>
> diff --git a/user/tracing/usecases.rst b/user/tracing/usecases.rst<br>
> new file mode 100644<br>
> index 0000000..5105650<br>
> --- /dev/null<br>
> +++ b/user/tracing/usecases.rst<br>
> @@ -0,0 +1,117 @@<br>
> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0<br>
> +<br>
> +.. comment: Copyright (c) 2016 Chris Johns <<a href="mailto:chrisj@rtems.org">chrisj@rtems.org</a>><br>
> +.. comment: All rights reserved.<br>
> +<br>
> +.. _usecases:<br>
> +<br>
> +Tracing Use Cases<br>
> +*****************<br>
> +<br>
> +Following are the use cases of the tracing framework that are currently under <br>
> +development:<br>
> +<br>
> +Function Tracing<br>
> +================<br>
> +<br>
> +Tracing the entry and exit of a function as well as the values of the arguments <br>
> +and return values can prove to be an important application for the tracing <br>
> +framework.<br>
> +<br>
> +Objective<br>
> +---------<br>
> +<br>
> +This use case can prove to be helpful in debugging of applications for the<br>
> +users. It can also be used to understand the working of existing application<br>
> +code bases. Capturing of argument and return values maybe useful in tracking<br>
> +unexpected output results from the applications.<br>
> +<br>
> +Requirements<br>
> +------------<br>
> +<br>
> +The current tracing framework provides this functionality with<br>
> +:ref:`tracebuffering`. The output is provided in the form of printing on<br>
> +console or saving the buffer in the form of a bin file. In order to develop this<br>
> +use case using CTF we need to be able to convert this RTEMS trace output into<br>
> +CTF. This could be done using babeltrace. The converted CTF traces would then be<br>
> +sent over to the host using a transport mechanism. <br>
> +<br>
> +Example<br>
> +-------<br>
> +<br>
> +As a start to the development of function tracing using CTF we can work on the <br>
> +fileio sample testsuite and trace all the calls to malloc, calloc, free and<br>
> +realloc functions. Along with the calls made to these functions the trace must<br>
> +also capture the values of their arguments at entry and the return values at<br>
> +function exit. As an example of an application having the following progression<br>
> +of function calls:<br>
> +<br>
> +.. code-block:: c<br>
> +<br>
> + #include <stdlib.h><br>
> + int main(int argc, char** argv)<br>
> + {<br>
> + int* a = malloc(sizeof(int));<br>
> + free(a);<br>
> + a = calloc(1, sizeof(int));<br>
> + return 0;<br>
> + }<br>
> +<br>
> +<br>
> +The trace of such an application must be output of the following kind:<br>
> +<br>
> +.. code-block:: shell<br>
> +<br>
> + Timestamp1 entry of malloc > argument value<br>
> + Timestamp2 exit of malloc < return value<br>
> + Timestamp3 entry of free > argument value<br>
> + Timestamp4 exit of free < return value (null)<br>
> + Timestamp5 entry of calloc > argument1 value, argument2 value<br>
> + Timestamp6 exit of calloc < return value1<br>
> +<br>
> +There could be additional columns of details including current priority, task <br>
> +state etc.<br>
> +<br>
> + <br>
> +Tracing Thread Operations<br>
> +=========================<br>
> +<br>
> +Tracing thread creation, switching and termination operation in a thread's<br>
> +lifetime within an application.<br>
> +<br>
> +Objective<br>
> +---------<br>
> +<br>
> +Real time applications inherently utilize parallel programming which entails <br>
> +several tasks executing simultaneously and competing for common resources.<br>
> +On single processor systems the CPU performs context switching between each of<br>
> +these tasks rapidly. By tracing the creation and termination of tasks as well<br>
> +as the context switches between them one can possibly identify probable race<br>
> +conditions or complex threading operations.<br>
> +<br>
> +Requirements<br>
> +------------<br>
> +<br>
> +[TBD]<br>
> +<br>
> +Example<br>
> +-------<br>
> +<br>
> +A sample trace tracking two tasks Ta and Tb could have an output of the<br>
> +following kind:<br>
> +<br>
> +.. code-block:: shell<br>
> +<br>
> + Timestamp1 taskid Ta CREATED<br>
> + Timestamp1 taskid Ta SWITCHED-IN<br>
> + Timestamp1 taskid Ta BEGIN<br>
> + Timestamp1 taskid Tb CREATED<br>
> + Timestamp1 taskid Ta SWITCHED-OUT<br>
> + Timestamp1 taskid Tb SWITCHED-IN<br>
> + Timestamp1 taskid Tb BEGIN<br>
> + Timestamp1 taskid Tb SWITCHED-OUT<br>
> + Timestamp1 taskid Tb TERMINATED<br>
> + Timestamp1 taskid Ta SWITCHED-IN<br>
> + Timestamp1 taskid Ta SWITCHED-OUT<br>
> + Timestamp1 taskid Ta TERMINATED <br>
> + <br>
> <br>
> <br>
> <br>
</div></div>> ______________________________<wbr>_________________<br>
> devel mailing list<br>
> <a href="mailto:devel@rtems.org">devel@rtems.org</a><br>
> <a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer" target="_blank">http://lists.rtems.org/<wbr>mailman/listinfo/devel</a><br>
> <br>
______________________________<wbr>_________________<br>
devel mailing list<br>
<a href="mailto:devel@rtems.org">devel@rtems.org</a><br>
<a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer" target="_blank">http://lists.rtems.org/<wbr>mailman/listinfo/devel</a></blockquote></div><br></div>