<div dir="ltr"><font color="#4c1130"><span style="font-size:12.8px;text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline">>There should be a ticket associated with your project that it would</span><br style="font-size:12.8px;text-decoration-style:initial;text-decoration-color:initial"><span style="font-size:12.8px;text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline">>make sense to add a line in the commit message: "Updates #2xxx"?</span></font><br><div><font color="#4c1130"><span style="font-size:12.8px;text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline"><br></span></font></div><div><span style="font-size:12.8px;text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline"><font color="#000000">I ll make a documentation related ticket and reframe the commit message.</font></span></div><div><span style="font-size:12.8px;text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline"><font color="#000000"><br></font></span></div><div><span style="font-size:12.8px;text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline"><font color="#4c1130"><span style="background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline">>Is all of this Chris' writing? Or did you write some of this? You</span><br style="background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial"><span style="background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline">>should put your copyright and current year on the files with words</span><br style="background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial"><span style="background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline">>that you create, if any</span></font><br></span></div><div><span style="font-size:12.8px;text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline"><font color="#4c1130"><span style="background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline"><br></span></font></span></div><div><span style="font-size:12.8px;text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline"><span style="background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline"><font color="#000000">Some of this is Chris, some is mine and some is with changes in Chris' documentation. I will make the copyright changes too. </font></span></span></div><div><span style="font-size:12.8px;text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline"><span style="background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline"><font color="#000000"><br></font></span></span></div><div><span style="font-size:12.8px;text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline"><span style="background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline"><font color="#4c1130"><span style="background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline">>These two sections "Function Wrapping" and "Function Signatures" seem</span><br style="background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial"><span style="background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline">>misplaced. I suspect they belong before Generators, maybe merged with</span><br style="background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial"><span style="background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline">>the "Function Sections" part?</span></font><br></span></span></div><div><span style="font-size:12.8px;text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline"><span style="background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline"><font color="#4c1130"><span style="background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline"><br></span></font></span></span></div><div><span style="font-size:12.8px;text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline"><span style="background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline"><span style="background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline"><font color="#000000">I will merge them with the Function Section.</font></span></span></span></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Jun 13, 2018 at 6:49 PM, Gedare Bloom <span dir="ltr"><<a href="mailto:gedare@rtems.org" target="_blank">gedare@rtems.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Sorry, I didn't see v6, but my comments still apply. I suspect v7 will<br>
be mergeable.<br>
<div class="HOEnZb"><div class="h5"><br>
On Wed, Jun 13, 2018 at 9:18 AM, Gedare Bloom <<a href="mailto:gedare@rtems.org">gedare@rtems.org</a>> wrote:<br>
> I think we're almost there. ;) A bit more below:<br>
><br>
> On Wed, Jun 13, 2018 at 5:22 AM, Vidushi Vashishth <<a href="mailto:reachvidu@gmail.com">reachvidu@gmail.com</a>> wrote:<br>
>> - Completed Trace Linker Section<br>
>> - Added Trace Examples section<br>
>> - Removed CTF section<br>
>> - Removed Use cases section<br>
>> - Incorporated changes asked by Chris<br>
><br>
> It would be best to provide the "summary of changes" in reply to the<br>
> patch, and instead continue to have a useful commit message that will<br>
> make sense when someone looks in the git-log. For example, looking in<br>
> the log and seeing "Removed CTF section" one would ask where that was<br>
> to begin with. Also, that you incorporated asked for changes can be<br>
> omitted, since this is usually the case for all commits. So make sure<br>
> your commit message only accurately reflects what is in the commit.<br>
><br>
> There should be a ticket associated with your project that it would<br>
> make sense to add a line in the commit message: "Updates #2xxx"?<br>
><br>
>> ---<br>
>> user/index.rst | 2 +<br>
>> user/tracing/captureengine.rst | 182 +++++++++++++++<br>
>> user/tracing/examples.rst | 185 +++++++++++++++<br>
>> user/tracing/index.rst | 30 +++<br>
>> user/tracing/introduction.rst | 105 +++++++++<br>
>> user/tracing/tracelinker.rst | 501 ++++++++++++++++++++++++++++++<wbr>+++++++++++<br>
>> 6 files changed, 1005 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>
>><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..b4c1123<br>
>> --- /dev/null<br>
>> +++ b/user/tracing/captureengine.<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>
><br>
> Is all of this Chris' writing? Or did you write some of this? You<br>
> should put your copyright and current year on the files with words<br>
> that you create, if any<br>
><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<br>
>> +build directory created when building RTEMS in the path<br>
>> +file: `sparc-rtems5/c/erc32/<wbr>testsuites/samples` directory.<br>
>> +In order to access the capture testcase perform the following set of<br>
>> +operations inside the RTEMS build directory.<br>
>> +<br>
>> +.. code-block:: shell<br>
>> +<br>
>> + $ cd /sparc-rtems5/c/erc32/<wbr>testsuites/samples<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<br>
>> +the Capture Engine Command Line Interface (CLI) makes the `RMON` task invoke a<br>
>> +call to the `capture_test_1()` command. This function (in the `test1.c` source<br>
>> +code) creates and starts three tasks : `CT1a`, `CT1b` and `CT1c`. These tasks<br>
>> +are passed the object id of a semaphore as a task argument. This run through<br>
>> +traces the context switches between these tasks. ``cwceil`` and ``cwfloor`` are<br>
>> +set to a narrow range of task priorities to avoid creating noise from a large<br>
>> +number of 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..533997e<br>
>> --- /dev/null<br>
>> +++ b/user/tracing/examples.rst<br>
>> @@ -0,0 +1,185 @@<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>
>> +The following example executes RTEMS trace using trace buffering for the<br>
>> +`fileio` sample testcase.<br>
>> +<br>
>> +Prerequisites<br>
>> +-------------<br>
>> +<br>
>> +1. Setup RTEMS for the `sparc/erc32` architecture-bsp pair to run the<br>
>> + following example.<br>
>> +2. Download the fileio `configuration file <<a href="https://devel.rtems.org/attachment" rel="noreferrer" target="_blank">https://devel.rtems.org/<wbr>attachment</a><br>
>> + /wiki/Developer/Tracing/Trace_<wbr>Buffering/fileio-trace.ini>`_ and store it on<br>
>> + the top of the installed BSP's directory.<br>
>> +3. Change the value of the keys: `rtems-path` and `prefix` according to your<br>
>> + rtems installation. The `rtems-path` is the path to the bsp installation<br>
>> + and `prefix` is the path to the tools used to build rtems. Also set the<br>
>> + value of the `rtems-bsp` key to `sparc/erc32`.<br>
>> +<br>
>> +Demonstration<br>
>> +-------------<br>
>> +<br>
>> +Inside the RTEMS build directory (the directory where the fileio configuration<br>
>> +has been stored) run the following commands to generate traces:<br>
>> +<br>
>> +BSP is configured with the following command -<br>
>> +<br>
>> +.. code:: shell<br>
>> +<br>
>> + ../rtems/configure --target=sparc-rtems5 --prefix=/development/rtems/5 \<br>
>> + --enable-networking --enable-tests --enable-rtemsbsp=erc32 --enable-cxx<br>
>> +<br>
>> +The next two commands are used to link the fileio executable.The `-B` option<br>
>> +signifies the use of the complete path to the required directory or file. Write<br>
>> +the full path instead of the path file: `sparc-rtems5/erc32/lib/` in the<br>
>> +following commands according to your installation. Also confirm the path of the<br>
>> +fileio’s executable and object files in the last line of the command according<br>
>> +to your installation.<br>
>> +<br>
>> +.. code:: shell<br>
>> +<br>
>> + sparc-rtems5-gcc -Bsparc-rtems5/erc32/lib/ \<br>
>> + -specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections \<br>
>> + -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-<wbr>declaration \<br>
>> + -Wstrict-prototypes -Wnested-externs -Wl,--gc-sections -mcpu=cypress \<br>
>> + -o sparc-rtems5/c/erc32/<wbr>testsuites/samples/fileio.exe sparc-rtems5/c/erc32/\<br>
>> + testsuites/samples/fileio/<wbr>fileio-init.o<br>
>> +<br>
>> +This is the trace linker command to generate and compile the wrapper c file for<br>
>> +the application. The link command follows the escape sequence "--". "-C" option<br>
>> +denotes the name of the user configuration file and "-W" specifies the name of<br>
>> +the wrapper c file.<br>
>> +<br>
>> +.. code:: shell<br>
>> +<br>
>> + rtems-tld -C fileio-trace.ini -W fileio-wrapper -- -Bsparc-rtems5/erc32/lib/ \<br>
>> + -specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections \<br>
>> + -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-<wbr>declaration \<br>
>> + -Wstrict-prototypes -Wnested-externs -Wl,--gc-sections -mcpu=cypress \<br>
>> + -o sparc-rtems5/c/erc32/<wbr>testsuites/samples/fileio.exe sparc-rtems5/c/erc32/\<br>
>> + testsuites/samples/fileio/<wbr>fileio-init.o<br>
>> +<br>
>> +The following command is used to run the application. Hit enter key quickly and<br>
>> +type "s" and "root" and "pwd" to run the rtems shell. Use the `rtrace status`,<br>
>> +`rtrace trace` and `rtrace save` commands to know the status of the tracing,<br>
>> +display the contents of the trace buffer and save the buffer to disk in the form<br>
>> +of binary files.<br>
>> +<br>
>> +.. code:: shell<br>
>> +<br>
>> + sparc-rtems5-run sparc-rtems5/c/erc32/<wbr>testsuites/samples/fileio.exe<br>
>> +<br>
>> +The output from the above commands will be as follows:<br>
>> +<br>
>> +.. code:: shell<br>
>> +<br>
>> + *** BEGIN OF TEST FILE I/O ***<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 a3a6c34c150a357e57769a26a460c4<wbr>75e<br>
>> + 188438f, Newlib 3.0.0)<br>
>> + Press any key to start file I/O sample (20s remaining)<br>
>> + Press any key to start file I/O sample (19s remaining)<br>
>> + Press any key to start file I/O sample (18s remaining)<br>
>> + Press any key to start file I/O sample (17s remaining)<br>
>> + Press any key to start file I/O sample (16s remaining)<br>
>> + Press any key to start file I/O sample (15s remaining)<br>
>> + Press any key to start file I/O sample (14s remaining)<br>
>> + =========================<br>
>> + RTEMS FILE I/O Test Menu<br>
>> + =========================<br>
>> + p -> part_table_initialize<br>
>> + f -> mount all disks in fs_table<br>
>> + l -> list file<br>
>> + r -> read file<br>
>> + w -> write file<br>
>> + s -> start shell<br>
>> + Enter your selection ==>s<br>
>> + Creating /etc/passwd and group with four useable accounts:<br>
>> + root/pwd<br>
>> + test/pwd<br>
>> + rtems/NO PASSWORD<br>
>> + chroot/NO PASSWORD<br>
>> + Only the root user has access to all available commands.<br>
>> + =========================<br>
>> + starting shell<br>
>> + =========================<br>
>> +<br>
>> + Welcome to rtems-5.0.0 (SPARC/w/FPU/erc32)<br>
>> + COPYRIGHT (c) 1989-2008.<br>
>> + On-Line Applications Research Corporation (OAR).<br>
>> +<br>
>> + Login into RTEMS<br>
>> + /dev/foobar login: root<br>
>> + Password:<br>
>> +<br>
>> + RTEMS Shell on /dev/foobar. Use 'help' to list commands.<br>
>> + SHLL [/] # rtrace status<br>
>> + RTEMS Trace Bufferring: status<br>
>> + Running: yes<br>
>> + Triggered: yes<br>
>> + Level: 0%<br>
>> + Traces: 25<br>
>> + SHLL [/] # rtrace stop<br>
>> + RTEMS Trace Bufferring: stop<br>
>> + SHLL [/] # rtrace trace<br>
>> + RTEMS Trace Bufferring: trace<br>
>> + Trace buffer: 0x20921d8<br>
>> + Words traced: 1487<br>
>> + Traces: 25<br>
>> + 0:00:40.983197010 2081910 0a010002 [ 2/ 2] > malloc((size_t) 00000130)<br>
>> + 0:00:40.983333119 136109 0a010002 [ 2/ 2] < malloc => (void*) 0x219bb88<br>
>> + 0:00:40.983471669 138550 0a010002 [ 2/ 2] > malloc((size_t) 00000006)<br>
>> + 0:00:40.983606557 134888 0a010002 [ 2/ 2] < malloc => (void*) 0x219bcc0<br>
>> + 0:00:40.983684682 78125 0a010002 [ 2/ 2] > malloc((size_t) 00000007)<br>
>> + 0:00:40.983819569 134887 0a010002 [ 2/ 2] < malloc => (void*) 0x219bcd0<br>
>> + 0:00:40.983909901 90332 0a010002 [ 2/ 2] > malloc((size_t) 000003fc)<br>
>> + 0:00:40.984046620 136719 0a010002 [ 2/ 2] < malloc => (void*) 0x219bce0<br>
>> + 0:00:40.986624137 2577517 0a010003 [200/200] > malloc((size_t) 00000080)<br>
>> + 0:00:40.986767569 143432 0a010003 [200/200] < malloc => (void*) 0x219bce0<br>
>> + 0:00:40.987531119 763550 0a010003 [200/200] > calloc((size_t) 00000001, (size_t) 0000005d)<br>
>> + 0:00:40.987603751 72632 0a010003 [200/200] > malloc((size_t) 0000005d)<br>
>> + 0:00:40.987744743 140992 0a010003 [200/200] < malloc => (void*) 0x219bce0<br>
>> + 0:00:40.987824699 79956 0a010003 [200/200] < calloc => (void*) 0x219bce0<br>
>> + 0:00:40.988302604 477905 0a010003 [200/200] > malloc((size_t) 00000080)<br>
>> + 0:00:40.988446647 144043 0a010003 [200/200] < malloc => (void*) 0x219bd48<br>
>> + 0:00:40.988667595 220948 0a010003 [200/200] > calloc((size_t) 00000001, (size_t) 00000080)<br>
>> + 0:00:40.988740837 73242 0a010003 [200/200] > malloc((size_t) 00000080)<br>
>> + 0:00:40.988884880 144043 0a010003 [200/200] < malloc => (void*) 0x219bdd0<br>
>> + 0:00:40.988964836 79956 0a010003 [200/200] < calloc => (void*) 0x219bdd0<br>
>> + 0:00:40.989042961 78125 0a010003 [200/200] > calloc((size_t) 00000001, (size_t) 00000080)<br>
>> + 0:00:40.989110100 67139 0a010003 [200/200] > malloc((size_t) 00000080)<br>
>> + 0:00:40.989254143 144043 0a010003 [200/200] < malloc => (void*) 0x219be58<br>
>> + 0:00:40.989334099 79956 0a010003 [200/200] < calloc => (void*) 0x219be58<br>
>> + 0:00:40.990118401 784302 0a010003 [200/200] > calloc((size_t) 00000001, (size_t) 00000061)<br>
>> + 0:00:40.990176995 58594 0a010003 [200/200] > malloc((size_t) 00000061)<br>
>> + 0:00:40.990309441 132446 0a010003 [200/200] < malloc => (void*) 0x219bd48<br>
>> + 0:00:40.990384515 75074 0a010003 [200/200] < calloc => (void*) 0x219bd48<br>
>> + 0:00:40.990870355 485840 0a010003 [200/200] > malloc((size_t) 00000080)<br>
>> + 0:00:40.991011346 140991 0a010003 [200/200] < malloc => (void*) 0x219bee0<br>
>> + 0:00:40.991227411 216065 0a010003 [200/200] > calloc((size_t) 00000001, (size_t) 00000080)<br>
>> + 0:00:40.991296380 68969 0a010003 [200/200] > malloc((size_t) 00000080)<br>
>> + 0:00:40.991438593 142213 0a010003 [200/200] < malloc => (void*) 0x219bf68<br>
>> + 0:00:40.991514276 75683 0a010003 [200/200] < calloc => (void*) 0x219bf68<br>
>> + 0:00:40.991589349 75073 0a010003 [200/200] > calloc((size_t) 00000001, (size_t) 00000080)<br>
>> + 0:00:40.991653437 64088 0a010003 [200/200] > malloc((size_t) 00000080)<br>
>> + 0:00:40.991794428 140991 0a010003 [200/200] < malloc => (void*) 0x219bff0<br>
>> + 0:00:40.991871332 76904 0a010003 [200/200] < calloc => (void*) 0x219bff0<br>
>> + 0:00:40.992283320 411988 0a010003 [200/200] > malloc((size_t) 00000008)<br>
>> + SHLL [/] # rtrace save fileio-trace.bin<br>
>> + RTEMS Trace Bufferring: trace<br>
>> + Trace File: fileio-trace.bin<br>
>> + Trace buffer: 0x20921d8<br>
>> + Words traced: 1487<br>
>> + Traces: 25<br>
>> + SHLL [/] #<br>
>> +<br>
>> diff --git a/user/tracing/index.rst b/user/tracing/index.rst<br>
>> new file mode 100644<br>
>> index 0000000..b75261d<br>
>> --- /dev/null<br>
>> +++ b/user/tracing/index.rst<br>
>> @@ -0,0 +1,30 @@<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 the operation of applications, 3rd party packages, and the<br>
>> +kernel in real 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>
>> + examples<br>
>> + captureengine<br>
>> + tracelinker<br>
>> +<br>
>> diff --git a/user/tracing/introduction.<wbr>rst b/user/tracing/introduction.<wbr>rst<br>
>> new file mode 100644<br>
>> index 0000000..7b9e1d3<br>
>> --- /dev/null<br>
>> +++ b/user/tracing/introduction.<wbr>rst<br>
>> @@ -0,0 +1,105 @@<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 their BSP and invokes the<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>
>> +.. _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<br>
>> +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>
>> diff --git a/user/tracing/tracelinker.rst b/user/tracing/tracelinker.rst<br>
>> new file mode 100644<br>
>> index 0000000..a95ec41<br>
>> --- /dev/null<br>
>> +++ b/user/tracing/tracelinker.rst<br>
>> @@ -0,0 +1,501 @@<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>
>> +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<br>
>> +consists 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>
>> +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,<br>
>> + and 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>
> s/Rtems/RTEMS<br>
><br>
> It is ok to use 'rtems' or 'RTEMS' but 'Rtems' is strange.<br>
><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<br>
>> +files:<br>
>> +<br>
>> +.. code-block:: shell<br>
>> +<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<br>
>> +headers key that further references a section called `test-headers`:<br>
>> +<br>
>> +.. code-block:: shell<br>
>> +<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 file:<br>
>> +`test-trace.ini` have been used for explicit understanding. This file can<br>
>> +be found in the rtems-tools directory of the rtems installation.<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<br>
>> + trace 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>
>> +The tracer section of the file:`test-trace.ini` is shown below with explanatory<br>
>> +comments.<br>
>> +<br>
>> +.. code-block:: shell<br>
>> +<br>
>> + ;<br>
>> + ; RTEMS Trace Linker Test Configuration.<br>
>> + ;<br>
>> + ; We must provide a top level trace section.<br>
>> + ;<br>
>> + [tracer]<br>
>> + ;<br>
>> + ; Name of the trace.<br>
>> + ;<br>
>> + name = RTEMS Trace Linker Test<br>
>> + ;<br>
>> + ; The BSP.<br>
>> + ;<br>
>> + bsp = sparc/sis<br>
>> + ;<br>
>> + ; Functions to trace.<br>
>> + ;<br>
>> + traces = test-trace, test-trace-funcs, rtems-api-task<br>
>> + ;<br>
>> + ; Specify the options.<br>
>> + ;<br>
>> + options = test-options<br>
>> + ;<br>
>> + ; Define the function sets. These are the function's that can be<br>
>> + ; added to the trace lists.<br>
>> + ;<br>
>> + functions = test-trace-funcs, rtems-api<br>
>> + ;<br>
>> + ; Include RTEMS Trace support.<br>
>> + ;<br>
>> + include = rtems.ini, rtld-base.ini<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<br>
>> + be 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<br>
>> + as read from the BSP configuration if specified. 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 referenced by functions being traced.<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<br>
>> + arch and bsp pair. For example sparc/erc32.<br>
>> +<br>
>> +The options section of the file: `test-trace.ini` uses two of the aforementioned<br>
>> +keys as shown below:<br>
>> +<br>
>> +.. code-block:: shell<br>
>> +<br>
>> + ;<br>
>> + ; Options can be defined here or on the command line.<br>
>> + ;<br>
>> + [test-options]<br>
>> + prefix = /development/rtems/5<br>
>> + verbose = true<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 signature has specific types and 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. A trace section can contain the following keys:<br>
>> +<br>
>> +- ``generator``: The generator defines the type of tracing being used.<br>
>> +<br>
>> +- ``headers``: List of sections that contain header file's 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>
>> +The trace section of the file: `test-trace.ini` is shown below. A trace section<br>
>> +can reference other trace sections of a specific type. This allows a trace<br>
>> +sections to build on other trace sections.<br>
>> +<br>
>> +.. code:: shell<br>
>> +<br>
>> + ; User application trace example.<br>
>> + ;<br>
>> + [test-trace]<br>
>> + generator = printf-generator<br>
>> + ; Just here for testing.<br>
>> + trace = test_trace_3<br>
>> +<br>
>> + [test-trace-funcs]<br>
>> + ; Parsed via the 'function-set', not parse as a 'trace'.<br>
>> + headers = test-headers<br>
>> + header = '#include "test-trace-2.h"'<br>
>> + defines = test-defines<br>
>> + define = "#define TEST_TRACE_2 2"<br>
>> + signatures = test-signatures<br>
>> + ; Parsed via the 'trace', not parsed as a function-set<br>
>> + trace = test_trace_1, test_trace_2<br>
>> +<br>
>> + [test-headers]<br>
>> + header = '#include "test-trace-1.h"'<br>
>> +<br>
>> + [test-defines]<br>
>> + define = "#define TEST_TRACE_1 1"<br>
>> +<br>
>> + [test-signatures]<br>
>> + test_trace_1 = void, int<br>
>> + test_trace_2 = test_type_2, test_type_1<br>
>> + test_trace_3 = float, float*<br>
>> +<br>
>> +Function Section<br>
>> +----------------<br>
>> +<br>
>> +Function sections define functions that can be traced. They provide any required<br>
>> +defines, header files, and the function signatures. Defining a function so it<br>
>> +can be traced does not mean it is traced. The function must be added to a trace<br>
>> +list to be traced. A function section can consist of the following keys:<br>
>> +<br>
>> +- ``headers``: A list of sections containing headers or header records.<br>
>> +- ``header``: A list of include string that are single or double quoted.<br>
>> +- ``defines``: A list of sections containing defines or define record.<br>
>> +- ``defines``: A list of define string that are single or double quoted.<br>
>> +- ``signatures``: A list of section names of function signatures.<br>
>> +- ``includes``: A list of files to include.<br>
>> +<br>
>> +Function signatures are specified with the function name being the key's name<br>
>> +and the key's value being the return value and a list of function arguments. You<br>
>> +need to provide void if the function uses void. Variable argument list are<br>
>> +currently not supported. There is no way to determine statically a variable<br>
>> +argument list. The function section in the file: `test-trace.ini` has been<br>
>> +labeled as `test-trace-funcs`. This can be seen in the file snippet of the<br>
>> +previous section.<br>
>> +<br>
>> +Generators<br>
>> +----------<br>
>> +<br>
>> +Generator section specify how to generate trace wrapping code. The trace<br>
>> +linker and generator section must match to work. The trace linker expects a some<br>
>> +things to be present when wrapping functions. The section's name specifies the<br>
>> +generator and can be listed in a generator key in a tracer or trace section. If<br>
>> +the generator is not interested in a specific phase it does not need to define<br>
>> +it. Nothing will be generated in regard to this phase. For example code to<br>
>> +profile specific functions may only provide the entry-trace and exit-trace code<br>
>> +where a nano-second time stamp is taken.<br>
>> +<br>
>> +The generate code will create an entry and exit call and the generator code<br>
>> +block can be used to allocate buffer space for each with the lock held. The<br>
>> +entry call and argument copy is performed with the lock released. The buffer<br>
>> +space having been allocated will cause the trace events to be in order. The same<br>
>> +goes for the exit call. Space is allocated in separate buffer allocate calls so<br>
>> +the blocking calls will have the exit event appear in the correct location in<br>
>> +the buffer.<br>
>> +<br>
>> +The following keys can be a part of the generator configuration:<br>
>> +<br>
>> +- ``headers``: A list of sections containing headers or header records.<br>
>> +- ``header``: A list of include string that are single or double quoted.<br>
>> +- ``defines``: A list of sections containing defines or define record.<br>
>> +- ``define``: A list of define string that are single or double quoted.<br>
>> +- ``entry-trace``: The wrapper call made on a function's entry. Returns bool<br>
>> + where true is the function is being traced. This call is made without the lock<br>
>> + being held if a lock is defined.<br>
>> +- ``arg-trace``: The wrapper call made for each argument to the trace function<br>
>> + if the function is being traced. This call is made without the lock being held<br>
>> + if a lock is defined.<br>
>> +- ``exit-trace``: The wrapper call made after a function's exit. Returns bool<br>
>> + where true is the function is being traced. This call is made without the lock<br>
>> + being held if a lock is defined.<br>
>> +- ``ret-trace``: The wrapper call made to log the return value if the function<br>
>> + is being traced. This call is made without the lock being held if a lock is<br>
>> + defined.<br>
>> +- ``lock-local``: The wrapper code to declare a local lock variable.<br>
>> +- ``lock-acquire``: The wrapper code to acquire the lock.<br>
>> +- ``lock-release``: The wrapper code to release the lock.<br>
>> +- ``buffer-local``: The wrapper code to declare a buffer index local variable.<br>
>> +- ``buffer-alloc``: The wrapper call made with a lock held if defined to<br>
>> + allocate buffer space to hold the trace data. A suitable 32bit buffer index is<br>
>> + returned. If there is no space an invalid index is returned. The generator<br>
>> + must handle any overhead space needed. The generator needs to make sure the<br>
>> + space is available before making the alloc all.<br>
>> +- ``code-blocks``: A list of code block section names.<br>
>> +- ``code``: A code block in <<CODE --- CODE (without the single quote).<br>
>> +- ``includes``: A list of files to include.<br>
>> +<br>
>> +The following macros can be used in wrapper calls:<br>
>> +<br>
>> +- ``@FUNC_NAME@``: The trace function name as a quote C string.<br>
>> +- ``@FUNC_INDEX@``: The trace function index as a held in the sorted list of<br>
>> + trace functions by the trace linker. It can be used to index the names,<br>
>> + enables, and triggers data.<br>
>> +- ``@FUNC_LABEL@``: The trace function name as a C label that can be referenced.<br>
>> + You can take the address of the label.<br>
>> +- ``@FUNC_DATA_SIZE@``: The size of the data in bytes.<br>
>> +- ``@FUNC_DATA_ENTRY_SIZE@``: The size of the entry data in bytes.<br>
>> +- ``@FUNC_DATA_RET_SIZE@``: The size of the return data in bytes.<br>
>> +- ``@ARG_NUM@``: The argument number to the trace function.<br>
>> +- ``@ARG_TYPE@``: The type of the argument as a C string.<br>
>> +- ``@ARG_SIZE@``: The size of the type of the argument in bytes.<br>
>> +- ``@ARG_LABEL@``: The argument as a C label that can be referenced.<br>
>> +- ``@RET_TYPE@``: The type of the return value as a C string.<br>
>> +- ``@RET_SIZE@``: The size of the type of the return value in bytes.<br>
>> +- ``@RET_LABEL@``: The return value as a C label that can be referenced.<br>
>> +<br>
>> +The `buffer-alloc`, `entry-trace`, and `exit-trace` can be transformed using the<br>
>> +following macros:<br>
>> +<br>
>> +- ``@FUNC_NAME@``<br>
>> +- ``@FUNC_INDEX@``<br>
>> +- ``@FUNC_LABEL@``<br>
>> +- ``@FUNC_DATA_SZIE@``<br>
>> +- ``@FUNC_DATA_ENTRY_SZIE@``<br>
>> +- ``@FUNC_DATA_EXIT_SZIE@``<br>
>> +<br>
>> +The `arg-trace` can be transformed using the following macros:<br>
>> +<br>
>> +- ``@ARG_NUM@``<br>
>> +- ``@ARG_TYPE@``<br>
>> +- ``@ARG_SIZE@``<br>
>> +- ``@ARG_LABEL@``<br>
>> +<br>
>> +The `ret-trace` can be transformed using the following macros:<br>
>> +<br>
>> +- ``@RET_TYPE@``<br>
>> +- ``@RET_SIZE@``<br>
>> +- ``@RET_LABEL@``<br>
>> +<br>
>> +The file: `test-trace.ini` specifies ``printf-generator`` as its generator. This<br>
>> +section can be found in the file: `rtld-print.ini` in the rtems-tools directory<br>
>> +and is shown below:<br>
>> +<br>
>> +.. code:: shell<br>
>> +<br>
>> + ;<br>
>> + ; A printf generator prints to stdout the trace functions.<br>
>> + ;<br>
>> + [printf-generator]<br>
>> + headers = printf-generator-headers<br>
>> + entry-trace = "rtld_pg_printf_entry(@FUNC_<wbr>NAME@, (void*) &@FUNC_LABEL@);"<br>
>> + arg-trace = "rtld_pg_printf_arg(@ARG_NUM@, @ARG_TYPE@, @ARG_SIZE@, (void*) &@ARG_LABEL@);"<br>
>> + exit-trace = "rtld_pg_printf_exit(@FUNC_<wbr>NAME@, (void*) &@FUNC_LABEL@);"<br>
>> + ret-trace = "rtld_pg_printf_ret(@RET_TYPE@<wbr>, @RET_SIZE@, (void*) &@RET_LABEL@);"<br>
>> + code = <<<CODE<br>
>> + static inline void rtld_pg_printf_entry(const char* func_name,<br>
>> + void* func_addr)<br>
>> + {<br>
>> + printf (">>> %s (0x%08x)\n", func_name, func_addr);<br>
>> + }<br>
>> + static inline void rtld_pg_printf_arg(int arg_num,<br>
>> + const char* arg_type,<br>
>> + int arg_size,<br>
>> + void* arg)<br>
>> + {<br>
>> + const unsigned char* p = arg;<br>
>> + int i;<br>
>> + printf (" %2d] %s(%d) = ", arg_num, arg_type, arg_size);<br>
>> + for (i = 0; i < arg_size; ++i, ++p) printf ("%02x", (unsigned int) *p);<br>
>> + printf ("\n");<br>
>> + }<br>
>> + static inline void rtld_pg_printf_exit(const char* func_name,<br>
>> + void* func_addr)<br>
>> + {<br>
>> + printf ("<<< %s (0x%08x)\n", func_name, func_addr);<br>
>> + }<br>
>> + static inline void rtld_pg_printf_ret(const char* ret_type,<br>
>> + int ret_size,<br>
>> + void* ret)<br>
>> + {<br>
>> + const unsigned char* p = ret;<br>
>> + int i;<br>
>> + printf (" rt] %s(%d) = ", ret_type, ret_size);<br>
>> + for (i = 0; i < ret_size; ++i, ++p) printf ("%02x", (unsigned int) *p);<br>
>> + printf ("\n");<br>
>> + }<br>
>> + CODE<br>
>> +<br>
>> + [printf-generator-headers]<br>
>> + header = "#include <stdio.h>"<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<br>
>> +instrumented. The trace code generated is driven by the configuration INI files.<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 used to<br>
>> +determine a function's signature. This work is planned but not scheduled to be<br>
>> +done and so in the meantime we explicitly define the function signatures in the<br>
>> +configuration files.<br>
>> +<br>
><br>
> These two sections "Function Wrapping" and "Function Signatures" seem<br>
> misplaced. I suspect they belong before Generators, maybe merged with<br>
> the "Function Sections" part?<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>
>> --<br>
>> 2.7.4<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><br>
</div></div></blockquote></div><br></div>