I can't give a detailed review, but one possible problem I notice is the line lengths. I think in the docs we also have 79/80 character widths for lines. Please set your editor to hard-wrap at 79 or 80, and break the long lines. (Unless I'm mistaken about the line length in the doc files.)
On Sun, Jun 10, 2018 at 12:45 AM, Vidushi Vashishth <reachv...@gmail.com> wrote: > - Incorporated suggested changes (except making use case example as close to > the actual output) > - Added trace linker section (to be completed) > - Added capture engine section > - Added trace buffering and printk trace generation in introduction > - Added trace examples section (to be completed) > > The only tool to be installed is babeltrace which is in the introduction page > under the babeltrace heading. > This documentation covers the following links: > 1) https://devel.rtems.org/wiki/Developer/Tracing > 2) https://devel.rtems.org/wiki/Developer/Tracing/Trace_Buffering > 3) https://devel.rtems.org/wiki/Developer/Tracing/Trace_Linker > 4) > https://devel.rtems.org/attachment/wiki/Developer/Tracing/Trace_Buffering/fileio-trace.ini > 5) https://ftp.rtems.org/pub/rtems/people/chrisj/capture/capture-pc586.txt > 6) http://diamon.org/ctf/ > 7) http://diamon.org/babeltrace/ > --- > user/index.rst | 2 + > user/tracing/captureengine.rst | 167 +++++++++++++++++++++++++++ > user/tracing/examples.rst | 11 ++ > user/tracing/index.rst | 26 +++++ > user/tracing/introduction.rst | 150 ++++++++++++++++++++++++ > user/tracing/tracelinker.rst | 253 > +++++++++++++++++++++++++++++++++++++++++ > user/tracing/usecases.rst | 110 ++++++++++++++++++ > 7 files changed, 719 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 > create mode 100644 user/tracing/usecases.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..49f8a58 > --- /dev/null > +++ b/user/tracing/captureengine.rst > @@ -0,0 +1,167 @@ > +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 > + > +.. comment: Copyright (c) 2016 Chris Johns <chr...@rtems.org> > +.. 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 > the > +"$HOME/development/rtems/kernel/erc32/sparc-rtems5/c/erc32/testsuites/samples" > directory, > +provided you followed the installation directions of the quickstart section. > In order to > +access the capture testcase perform the following set of operations. > + > +.. code-block:: shell > + > + $ cd > $HOME/development/rtems/kernel/erc32/sparc-rtems5/c/erc32/testsuites/samples > + $ ../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:20:09.772382673 0a010003 CT1a 102 102 102 4096 > TASK_RECORD > + 0 0:20:09.772467512 0 0a010003 CT1a 102 102 > CREATED > + 0 0:20:09.772716535 249023 0a010003 CT1a 102 102 > STARTED > + 0 0:20:09.772972883 256348 0a010003 CT1a 102 102 > SWITCHED_IN > + 0 0:20:09.773137678 164795 0a010003 CT1a 102 102 > BEGIN > + 0 0:20:09.773404402 266724 0a010003 CT1a 102 102 > SWITCHED_OUT > + 0 0:20:10.771417096 0a010004 CT1b 101 101 101 4096 > TASK_RECORD > + 0 0:20:10.771502545 998098143 0a010004 CT1b 101 101 > CREATED > + 0 0:20:10.771752179 249634 0a010004 CT1b 101 101 > STARTED > + 0 0:20:10.772003034 250855 0a010004 CT1b 101 101 > SWITCHED_IN > + 0 0:20:10.772168439 165405 0a010004 CT1b 101 101 > BEGIN > + 0 0:20:11.771003888 998835449 0a010004 CT1b 101 101 > SWITCHED_OUT > + 0 0:20:11.771500104 0a010005 CT1c 100 100 100 4096 > TASK_RECORD > + 0 0:20:11.771584943 581055 0a010005 CT1c 100 100 > CREATED > + 0 0:20:11.771833966 249023 0a010005 CT1c 100 100 > STARTED > + 0 0:20:11.772087873 253907 0a010005 CT1c 100 100 > SWITCHED_IN > + 0 0:20:11.772252668 164795 0a010005 CT1c 100 100 > BEGIN > + 0 0:20:11.772543806 291138 0a010005 CT1c 100 100 > SWITCHED_OUT > + 0 0:20:11.772620100 76294 0a010004 CT1b 101 101 > SWITCHED_IN > + 0 0:20:12.271004193 498384093 0a010004 CT1b 101 101 > SWITCHED_OUT > + 0 0:20:12.271081097 76904 0a010003 CT1a 102 100 > SWITCHED_IN > + 0 0:20:12.271410077 328980 0a010003 CT1a 102 102 > SWITCHED_OUT > + 1-rtems $ ctrace > + 0 0:20:12.271486981 0 0a010005 CT1c 100 100 > SWITCHED_IN > + 0 0:20:12.271740888 253907 0a010005 CT1c 100 100 > SWITCHED_OUT > + 0 0:20:12.271818402 77514 0a010004 CT1b 101 101 > SWITCHED_IN > + 0 0:20:12.771035626 499217224 0a010004 CT1b 101 101 > SWITCHED_OUT > + 0 0:20:12.771288312 252686 0a010005 CT1c 100 100 > SWITCHED_IN > + 0 0:20:12.771492780 204468 0a010005 CT1c 100 100 > TERMINATED > + 0 0:20:12.771815656 322876 0a010005 CT1c 100 100 > SWITCHED_OUT > + 0 0:20:12.771892560 76904 0a010004 CT1b 101 101 > SWITCHED_IN > + 0 0:20:12.772083600 191040 0a010004 CT1b 101 101 > TERMINATED > + 0 0:20:12.772405256 321656 0a010004 CT1b 101 101 > SWITCHED_OUT > + 0 0:20:12.772482770 77514 0a010003 CT1a 102 102 > SWITCHED_IN > + 0 0:20:12.772677473 194703 0a010003 CT1a 102 102 > TERMINATED > + 0 0:20:12.773001570 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..f2beb7f > --- /dev/null > +++ b/user/tracing/examples.rst > @@ -0,0 +1,11 @@ > +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 > + > +.. comment: Copyright (c) 2016 Chris Johns <chr...@rtems.org> > +.. comment: All rights reserved. > + > +.. _examples: > + > +Tracing Examples > +**************** > + > +[TBD] > diff --git a/user/tracing/index.rst b/user/tracing/index.rst > new file mode 100644 > index 0000000..c321848 > --- /dev/null > +++ b/user/tracing/index.rst > @@ -0,0 +1,26 @@ > +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 > + > +.. comment: Copyright (c) 2016 Chris Johns <chr...@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 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 > + usecases > + examples > diff --git a/user/tracing/introduction.rst b/user/tracing/introduction.rst > new file mode 100644 > index 0000000..0a6e87e > --- /dev/null > +++ b/user/tracing/introduction.rst > @@ -0,0 +1,150 @@ > +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 > + > +.. comment: Copyright (c) 2016 Chris Johns <chr...@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 her 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. > + > +RTEMS Trace Using CTF > +===================== > + > +`Common Trace Format <http://diamon.org/ctf/>`_ (CTF) is a binary trace > format which is fast to write > +and has great flexibility. It allows traces to be developed by bare-metal > applications or by any > +other C/C++ system. RTEMS tracing framework can benefit from these features > of CTF. > + > +A typical CTF *trace* consists of multiple *streams* of binary *events*. The > *metadata* stream is a mandatory > +stream which describes the layout of all the other streams in a trace. This > metadata stream is written > +using *Trace Stream Description Language* (TSDL). > + > +.. comment: image taken from > view-source:http://diamon.org/ctf/img/ctf-trace.png > +.. comment: Not generating a copyright in the high chance we decide to not > keep a descriptive section on CTF > +.. figure:: ../../images/user/ctf-trace.png > + :align: center > + :width: 75% > + > +A binary *stream* is further a concatenation of several packets each > containing the following: > + > +- A packet header > +- An optional packet context > +- A set of concatenated events each containing: > + - An event header > + - A stream-specific context > + - An event-specific context > + - A payload > + > +.. comment: taken from > view-source:http://diamon.org/ctf/img/ctf-stream-packet.png > +.. comment: Not generating a copyright in the high chance we decide to not > keep a descriptive section on CTF > +.. figure:: ../../images/user/ctf-stream-packet.png > + :align: center > + :width: 75% > + > +All the headers, contexts and payloads are written in TSDL using CTF data > types. CTF supports a rich set of > +configurable datatypes which makes it possible to describe a larger variety > of binary structure. Moreover types > +in CTF are organized as type classes where type specifications can be > inherited to allow deriving types. These > +factors make CTF flexible. CTF enables fast writing of binary data as it > usually involves appending memory contents, > +as it is to a binary CTF stream. CTF streams are capable of being sent or > received over the network without any data > +being written to disk and hence can be useful in transporting traces from > the target to the host machine for analysis. > + > +Due to these advantages tracing using CTF will prove to be beneficial for > the users. This method of tracing is currently > +under development. Currently the RTEMS tracing framework is able to output > trace data in the form of trace buffers, > +console output and csv files. A conversion tool which transforms these trace > output formats to CTF will be viable > +approach to generating CTF traces. In this regard we utilize babeltrace, > which is described in the following section. > + > +Babeltrace > +---------- > + > +Babeltrace is an open source trace format converter which can be used to > convert RTEMS traces into CTF. > +It is also a reference parser implementation of CTF. Babeltrace currently > supports the following output > +formats for traces: > + > +- Text > +- CTF > +- CTF-metadata > +- Dummy > +- lttng-live > + > +Babeltrace comes in the form of a library, python bindings (python3) and > command line tool called ``babeltrace``. > +To install babeltrace on your host you can install a distribution package or > build from source using tarballs or > +git repositories of babeltrace. Refer to http://diamon.org/babeltrace/ for > further details. > diff --git a/user/tracing/tracelinker.rst b/user/tracing/tracelinker.rst > new file mode 100644 > index 0000000..6bd8f20 > --- /dev/null > +++ b/user/tracing/tracelinker.rst > @@ -0,0 +1,253 @@ > +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 > + > +.. comment: Copyright (c) 2016 Chris Johns <chr...@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 > 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 > references a further section 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 > fileio-trace.ini file have been used for > +explicit understanding. This file can be downloaded from `here > <https://devel.rtems.org/attachment/wiki/Developer/Tracing/Trace_Buffering/fileio-trace.ini>`_. > + > +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 > + > + > +.. code-block:: shell > + [tracer] > + name = File IO tracer > + ; > + ; The configuration > + ; > + options = fileio-options > + traces = fileio > + defines = fileio > + enables = fileio > + triggers = fileio > + functions = fileio-funcs, rtems-api, rtems-posix, libc-heap > + include = rtems.ini, rtld-base.ini, rtld-trace-buffer.ini, libc-heap.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 any functions being traced reference. > + > +- 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. > + > +.. code-block:: shell > + > + [fileio-options] > + dump-on-error = true > + ; > + ; Tools > + ; > + prefix = /development/rtems/5 > + rtems-path = /development/rtems/kernel/5 > + rtems-bsp = sparc/erc32 > + ; > + ; Generator options. > + ; > + gen-enables = enable > + gen-triggers = enable > + > + > +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 the signature has specific > types 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. > + > +- generator: The generator defines the type of tracing being used. > + > +- headers: List of sections that contain header files 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. > + > + > +[TBD] > + > + > +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 use 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. > + > + > +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 > + > diff --git a/user/tracing/usecases.rst b/user/tracing/usecases.rst > new file mode 100644 > index 0000000..95a283b > --- /dev/null > +++ b/user/tracing/usecases.rst > @@ -0,0 +1,110 @@ > +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 > + > +.. comment: Copyright (c) 2016 Chris Johns <chr...@rtems.org> > +.. comment: All rights reserved. > + > +.. _usecases: > + > +Tracing Use Cases > +***************** > + > +Following are the use cases of the tracing framework that are currently > under development: > + > +Function Tracing > +================ > + > +Tracing the entry and exit of a function as well as the values of the > arguments and > +return values can prove to be an important application for the tracing > framework. > + > +Objective > +--------- > + > +This use case can prove to be helpful in debugging of applications for the > users. It can also > +be used to understand the working of existing application code bases. > Capturing of argument and > +return values maybe useful in tracking unexpected output results from the > applications. > + > +Requirements > +------------ > + > +The current tracing framework provides this functionality with > :ref:`tracebuffering`. The output is > +provided in the form of printing on console or saving the buffer in the form > of a bin file. In order to > +develop this use case using CTF we need to be able to convert this RTEMS > trace output into CTF. This could > +be done using babeltrace. The converted CTF traces would then be sent over > to the host using a transport > +mechanism. > + > +Example > +------- > + > +As a start to the development of function tracing using CTF we can work on > the fileio > +sample testsuite and trace all the calls to malloc, calloc, free and realloc > functions. > +Along with the calls made to these functions the trace must also capture the > values of > +their arguments at entry and the return values at function exit. As an > example of an application > +having the following progression of function calls: > + > +.. code-block:: c > + > + #include <stdlib.h> > + int main(int argc, char** argv) > + { > + int* a = malloc(sizeof(int)); > + free(a); > + a = calloc(1, sizeof(int)); > + return 0; > + } > + > + > +The trace of such an application must be output of the following kind: > + > +.. code-block:: shell > + > + Timestamp1 entry of malloc > argument value > + Timestamp2 exit of malloc < return value > + Timestamp3 entry of free > argument value > + Timestamp4 exit of free < return value (null) > + Timestamp5 entry of calloc > argument1 value, argument2 value > + Timestamp6 exit of calloc < return value1 > + > +There could be additional columns of details including current priority, > task state etc. > + > + > +Tracing Thread Operations > +========================= > + > +Tracing thread creation, switching and termination operation in a thread's > lifetime within an application. > + > +Objective > +--------- > + > +Real time applications inherently utilize parallel programming which entails > several > +tasks executing simultaneously and competing for common resources. On single > processor systems > +the CPU performs context switching between each of these tasks rapidly. By > tracing the creation and > +termination of tasks as well as the context switches between them one can > possibly identify probable race > +conditions or complex threading operations. > + > +Requirements > +------------ > + > +[TBD] > + > +Example > +------- > + > +A sample trace tracking two tasks Ta and Tb could have an output of the > following kind: > + > +.. code-block:: shell > + > + Timestamp1 taskid Ta CREATED > + Timestamp1 taskid Ta SWITCHED-IN > + Timestamp1 taskid Ta BEGIN > + Timestamp1 taskid Tb CREATED > + Timestamp1 taskid Ta SWITCHED-OUT > + Timestamp1 taskid Tb SWITCHED-IN > + Timestamp1 taskid Tb BEGIN > + Timestamp1 taskid Tb SWITCHED-OUT > + Timestamp1 taskid Tb TERMINATED > + Timestamp1 taskid Ta SWITCHED-IN > + Timestamp1 taskid Ta SWITCHED-OUT > + Timestamp1 taskid Ta TERMINATED > + > + > + > -- > 2.7.4 > > _______________________________________________ > devel mailing list > devel@rtems.org > http://lists.rtems.org/mailman/listinfo/devel _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
