I was using Sublime text. It appeared okay on the editor. I have changed my editor and sent another patch.
Thanks. On Tue, Jun 12, 2018 at 9:46 PM, Gedare Bloom <ged...@rtems.org> wrote: > On Tue, Jun 12, 2018 at 11:15 AM, Vidushi Vashishth <reachv...@gmail.com> > wrote: > > > > Adjusted line length to 79-80 > > --- > > user/index.rst | 2 + > > user/tracing/captureengine.rst | 188 ++++++++++++++++++++++++++ > > user/tracing/examples.rst | 12 ++ > > user/tracing/index.rst | 33 +++++ > > user/tracing/introduction.rst | 184 ++++++++++++++++++++++++++ > > user/tracing/tracelinker.rst | 294 ++++++++++++++++++++++++++++++ > +++++++++++ > > user/tracing/usecases.rst | 129 ++++++++++++++++++ > > 7 files changed, 842 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..b80d7d0 > > --- /dev/null > > +++ b/user/tracing/captureengine.rst > > @@ -0,0 +1,188 @@ > > +.. 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 > > It is not right to just blanket wrap to 80 characters. This one word > on a line by itself is no good. Many text editors can make the > wrapping work in a nice way, but I don't know what editor you use. For > example, I use vim, and text formatting can be done by highlighting > text in Visual mode and using 'gq' command to reformat. > > > +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: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..f51613e > > --- /dev/null > > +++ b/user/tracing/examples.rst > > @@ -0,0 +1,12 @@ > > +.. 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..a879207 > > --- /dev/null > > +++ b/user/tracing/index.rst > > @@ -0,0 +1,33 @@ > > +.. 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..b4925b2 > > --- /dev/null > > +++ b/user/tracing/introduction.rst > > @@ -0,0 +1,184 @@ > > +.. 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 > > +.. comment: 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 http://diamon.org/ctf/img/ctf-stream-packet.png > > +.. comment: Not generating a copyright in the high chance we decide to > not keep > > +.. comment: 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..4bef4e5 > > --- /dev/null > > +++ b/user/tracing/tracelinker.rst > > @@ -0,0 +1,294 @@ > > +.. 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/filei > > +o-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 specificed. 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..20ce43d > > --- /dev/null > > +++ b/user/tracing/usecases.rst > > @@ -0,0 +1,129 @@ > > +.. 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
