>There should be a ticket associated with your project that it would >make sense to add a line in the commit message: "Updates #2xxx"?
I ll make a documentation related ticket and reframe the commit message. >Is all of this Chris' writing? Or did you write some of this? You >should put your copyright and current year on the files with words >that you create, if any Some of this is Chris, some is mine and some is with changes in Chris' documentation. I will make the copyright changes too. >These two sections "Function Wrapping" and "Function Signatures" seem >misplaced. I suspect they belong before Generators, maybe merged with >the "Function Sections" part? I will merge them with the Function Section. On Wed, Jun 13, 2018 at 6:49 PM, Gedare Bloom <ged...@rtems.org> wrote: > Sorry, I didn't see v6, but my comments still apply. I suspect v7 will > be mergeable. > > On Wed, Jun 13, 2018 at 9:18 AM, Gedare Bloom <ged...@rtems.org> wrote: > > I think we're almost there. ;) A bit more below: > > > > On Wed, Jun 13, 2018 at 5:22 AM, Vidushi Vashishth <reachv...@gmail.com> > wrote: > >> - Completed Trace Linker Section > >> - Added Trace Examples section > >> - Removed CTF section > >> - Removed Use cases section > >> - Incorporated changes asked by Chris > > > > It would be best to provide the "summary of changes" in reply to the > > patch, and instead continue to have a useful commit message that will > > make sense when someone looks in the git-log. For example, looking in > > the log and seeing "Removed CTF section" one would ask where that was > > to begin with. Also, that you incorporated asked for changes can be > > omitted, since this is usually the case for all commits. So make sure > > your commit message only accurately reflects what is in the commit. > > > > There should be a ticket associated with your project that it would > > make sense to add a line in the commit message: "Updates #2xxx"? > > > >> --- > >> user/index.rst | 2 + > >> user/tracing/captureengine.rst | 182 +++++++++++++++ > >> user/tracing/examples.rst | 185 +++++++++++++++ > >> user/tracing/index.rst | 30 +++ > >> user/tracing/introduction.rst | 105 +++++++++ > >> user/tracing/tracelinker.rst | 501 ++++++++++++++++++++++++++++++ > +++++++++++ > >> 6 files changed, 1005 insertions(+) > >> create mode 100644 user/tracing/captureengine.rst > >> create mode 100644 user/tracing/examples.rst > >> create mode 100644 user/tracing/index.rst > >> create mode 100644 user/tracing/introduction.rst > >> create mode 100644 user/tracing/tracelinker.rst > >> > >> diff --git a/user/index.rst b/user/index.rst > >> index 8cbcd1b..a764fe8 100644 > >> --- a/user/index.rst > >> +++ b/user/index.rst > >> @@ -52,6 +52,8 @@ to the Community Project hosted at > http://www.rtems.org/. > >> > >> tools/index > >> > >> + tracing/index > >> + > >> support/index > >> > >> glossary/index > >> diff --git a/user/tracing/captureengine.rst > b/user/tracing/captureengine.rst > >> new file mode 100644 > >> index 0000000..b4c1123 > >> --- /dev/null > >> +++ b/user/tracing/captureengine.rst > >> @@ -0,0 +1,182 @@ > >> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 > >> + > >> +.. comment: Copyright (c) 2016 Chris Johns <chr...@rtems.org> > > > > Is all of this Chris' writing? Or did you write some of this? You > > should put your copyright and current year on the files with words > > that you create, if any > > > >> +.. comment: All rights reserved. > >> + > >> +.. _capturengine: > >> + > >> +Capture Engine > >> +************** > >> + > >> +Capture Engine is a trace tool built inside the RTEMS operating > system. Capture > >> +Engine is designed to cause the lowest load on the system when > operating. Hence > >> +it does not effect RTEMS when operating or when disabled. It binds to > RTEMS at > >> +runtime and does not require RTEMS or your application to be rebuilt > in order > >> +to use it. > >> + > >> +The Capture Engine's sample testcase for the `sparc/erc32` is > available in > >> +build directory created when building RTEMS in the path > >> +file: `sparc-rtems5/c/erc32/testsuites/samples` directory. > >> +In order to access the capture testcase perform the following set of > >> +operations inside the RTEMS build directory. > >> + > >> +.. code-block:: shell > >> + > >> + $ cd /sparc-rtems5/c/erc32/testsuites/samples > >> + $ sparc-rtems5-run ./capture.exe > >> + > >> + > >> + *** BEGIN OF TEST CAPTURE ENGINE *** > >> + *** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8 > >> + *** TEST STATE: USER_INPUT > >> + *** TEST BUILD: RTEMS_NETWORKING RTEMS_POSIX_API > >> + *** TEST TOOLS: 7.3.0 20180125 (RTEMS 5, RSB > >> + a3a6c34c150a357e57769a26a460c475e188438f, Newlib 3.0.0) > >> + Press any key to start capture engine (20s remaining) > >> + Press any key to start capture engine (19s remaining) > >> + Press any key to start capture engine (18s remaining) > >> + > >> + Monitor ready, press enter to login. > >> + > >> + 1-rtems $ > >> + > >> +Capture Engine comes with a set of commands to perform various actions. > >> + > >> +Capture Engine Commands > >> +----------------------- > >> + > >> +1) ``copen <buffer-size>``: Used to initialize the Capture Engine with > the > >> + trace buffer size in bytes. By default the Capture Engine is not > initialized > >> + and not running. > >> + > >> +2) ``cwceil <priority-value>``: Capture Engine filter used to put an > upper > >> + limit on the event priority to be captured. > >> + > >> + > >> +3) ``cwfloor <priority-value>``: Capture Engine filter used to put a > lower > >> + limit on the event priority to be captured. > >> + > >> + > >> +4) ``cwglob <on/off>``: Enable or disable the global watch. > >> + > >> + > >> +5) ``cenable``: Enables the Capture Engine. Capture Engine is by > default > >> + disabled after being opened. > >> + > >> + > >> +6) ``cdisable``: Disables the Capture Engine. > >> + > >> + > >> +7) ``ctlist``: Lists the watch and trigger configurations. > >> + > >> + > >> +8) ``ctrace``: Dumps the recorded traces. By default this command > displays 24 > >> + trace records. Repeated use of this command will display all the > recorded > >> + traces. > >> + > >> +9) ``cwadd <task-name>``: Add watch on a particular task. > >> + > >> + > >> +10) ``cwtctl <task-name> <on/off>``: Enable or disable watch on a > particular > >> + task. > >> + > >> + > >> +11) ``ctset``: Used to set a trigger. The general form of the command > is: > >> + > >> +``ctset [-?] type [to name/id] [from] [from name/id]`` > >> + > >> +`type` in the above command refers to the type of trigger needed. The > types of > >> +triggers that currently exist > >> +are: > >> + > >> +- switch : a context switch from one task to another task > >> +- create : the executing task creates a task > >> +- start : the executing task starts a task > >> +- restart : the executing task restarts a task > >> +- delete : the executing task deletes a task > >> +- begin : a task is beginning > >> +- exitted : a task is exitting > >> + > >> +Example > >> +------- > >> + > >> +The following is a sample run of the capture testsuite. The `test1` > command on > >> +the Capture Engine Command Line Interface (CLI) makes the `RMON` task > invoke a > >> +call to the `capture_test_1()` command. This function (in the > `test1.c` source > >> +code) creates and starts three tasks : `CT1a`, `CT1b` and `CT1c`. > These tasks > >> +are passed the object id of a semaphore as a task argument. This run > through > >> +traces the context switches between these tasks. ``cwceil`` and > ``cwfloor`` are > >> +set to a narrow range of task priorities to avoid creating noise from > a large > >> +number of context switches between tasks we are not interested in. > >> + > >> +.. code:: shell > >> + > >> + *** BEGIN OF TEST CAPTURE ENGINE *** > >> + *** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8 > >> + *** TEST STATE: USER_INPUT > >> + *** TEST BUILD: RTEMS_NETWORKING RTEMS_POSIX_API > >> + *** TEST TOOLS: 7.3.0 20180125 (RTEMS 5, RSB > >> + a3a6c34c150a357e57769a26a460c475e188438f, Newlib 3.0.0) > >> + Press any key to start capture engine (20s remaining) > >> + Press any key to start capture engine (19s remaining) > >> + Press any key to start capture engine (18s remaining) > >> + Press any key to start capture engine (17s remaining) > >> + > >> + Monitor ready, press enter to login. > >> + > >> + 1-rtems $ copen 50000 > >> + capture engine opened. > >> + 1-rtems $ cwceil 100 > >> + watch ceiling is 100. > >> + 1-rtems $ cwfloor 102 > >> + watch floor is 102. > >> + 1-rtems $ cwglob on > >> + global watch enabled. > >> + 1-rtems $ ctset RMON > >> + trigger set. > >> + 1-rtems $ cenable > >> + capture engine enabled. > >> + 1-rtems $ test1 > >> + 1-rtems $ cdisable > >> + capture engine disabled. > >> + 1-rtems $ ctrace > >> + 0 0:18:17.462314124 0a010003 CT1a 102 102 102 4096 > TASK_RECORD > >> + 0 0:18:17.462398963 0 0a010003 CT1a 102 102 > CREATED > >> + 0 0:18:17.462647987 249024 0a010003 CT1a 102 102 > STARTED > >> + 0 0:18:17.462904334 256347 0a010003 CT1a 102 102 > SWITCHED_IN > >> + 0 0:18:17.463069129 164795 0a010003 CT1a 102 102 BEGIN > >> + 0 0:18:17.463335853 266724 0a010003 CT1a 102 102 > SWITCHED_OUT > >> + 0 0:18:18.461348547 0a010004 CT1b 101 101 101 4096 > TASK_RECORD > >> + 0 0:18:18.461433997 998098144 0a010004 CT1b 101 101 > CREATED > >> + 0 0:18:18.461683631 249634 0a010004 CT1b 101 101 > STARTED > >> + 0 0:18:18.461934485 250854 0a010004 CT1b 101 101 > SWITCHED_IN > >> + 0 0:18:18.462099891 165406 0a010004 CT1b 101 101 BEGIN > >> + 0 0:18:19.460935339 998835448 0a010004 CT1b 101 101 > SWITCHED_OUT > >> + 0 0:18:19.461431555 0a010005 CT1c 100 100 100 4096 > TASK_RECORD > >> + 0 0:18:19.461516394 581055 0a010005 CT1c 100 100 > CREATED > >> + 0 0:18:19.461765418 249024 0a010005 CT1c 100 100 > STARTED > >> + 0 0:18:19.462019324 253906 0a010005 CT1c 100 100 > SWITCHED_IN > >> + 0 0:18:19.462184119 164795 0a010005 CT1c 100 100 BEGIN > >> + 0 0:18:19.462475257 291138 0a010005 CT1c 100 100 > SWITCHED_OUT > >> + 0 0:18:19.462551551 76294 0a010004 CT1b 101 101 > SWITCHED_IN > >> + 0 0:18:19.960935645 498384094 0a010004 CT1b 101 101 > SWITCHED_OUT > >> + 0 0:18:19.961012549 76904 0a010003 CT1a 102 100 > SWITCHED_IN > >> + 0 0:18:19.961341528 328979 0a010003 CT1a 102 102 > SWITCHED_OUT > >> + 1-rtems $ ctrace > >> + 0 0:18:19.961418433 0 0a010005 CT1c 100 100 > SWITCHED_IN > >> + 0 0:18:19.961672339 253906 0a010005 CT1c 100 100 > SWITCHED_OUT > >> + 0 0:18:19.961749854 77515 0a010004 CT1b 101 101 > SWITCHED_IN > >> + 0 0:18:20.460967077 499217223 0a010004 CT1b 101 101 > SWITCHED_OUT > >> + 0 0:18:20.461219763 252686 0a010005 CT1c 100 100 > SWITCHED_IN > >> + 0 0:18:20.461424231 204468 0a010005 CT1c 100 100 > TERMINATED > >> + 0 0:18:20.461747107 322876 0a010005 CT1c 100 100 > SWITCHED_OUT > >> + 0 0:18:20.461824011 76904 0a010004 CT1b 101 101 > SWITCHED_IN > >> + 0 0:18:20.462015052 191041 0a010004 CT1b 101 101 > TERMINATED > >> + 0 0:18:20.462336707 321655 0a010004 CT1b 101 101 > SWITCHED_OUT > >> + 0 0:18:20.462414222 77515 0a010003 CT1a 102 102 > SWITCHED_IN > >> + 0 0:18:20.462608924 194702 0a010003 CT1a 102 102 > TERMINATED > >> + 0 0:18:20.462933021 324097 0a010003 CT1a 102 102 > SWITCHED_OUT > >> + 1-rtems $ ctrace > >> + 1-rtems $ > >> + > >> + > >> diff --git a/user/tracing/examples.rst b/user/tracing/examples.rst > >> new file mode 100644 > >> index 0000000..533997e > >> --- /dev/null > >> +++ b/user/tracing/examples.rst > >> @@ -0,0 +1,185 @@ > >> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 > >> + > >> +.. comment: Copyright (c) 2016 Chris Johns <chr...@rtems.org> > >> +.. comment: All rights reserved. > >> + > >> +.. _examples: > >> + > >> +Tracing Examples > >> +**************** > >> + > >> +The following example executes RTEMS trace using trace buffering for > the > >> +`fileio` sample testcase. > >> + > >> +Prerequisites > >> +------------- > >> + > >> +1. Setup RTEMS for the `sparc/erc32` architecture-bsp pair to run the > >> + following example. > >> +2. Download the fileio `configuration file <https://devel.rtems.org/ > attachment > >> + /wiki/Developer/Tracing/Trace_Buffering/fileio-trace.ini>`_ and > store it on > >> + the top of the installed BSP's directory. > >> +3. Change the value of the keys: `rtems-path` and `prefix` according > to your > >> + rtems installation. The `rtems-path` is the path to the bsp > installation > >> + and `prefix` is the path to the tools used to build rtems. Also set > the > >> + value of the `rtems-bsp` key to `sparc/erc32`. > >> + > >> +Demonstration > >> +------------- > >> + > >> +Inside the RTEMS build directory (the directory where the fileio > configuration > >> +has been stored) run the following commands to generate traces: > >> + > >> +BSP is configured with the following command - > >> + > >> +.. code:: shell > >> + > >> + ../rtems/configure --target=sparc-rtems5 > --prefix=/development/rtems/5 \ > >> + --enable-networking --enable-tests --enable-rtemsbsp=erc32 > --enable-cxx > >> + > >> +The next two commands are used to link the fileio executable.The `-B` > option > >> +signifies the use of the complete path to the required directory or > file. Write > >> +the full path instead of the path file: `sparc-rtems5/erc32/lib/` in > the > >> +following commands according to your installation. Also confirm the > path of the > >> +fileio’s executable and object files in the last line of the command > according > >> +to your installation. > >> + > >> +.. code:: shell > >> + > >> + sparc-rtems5-gcc -Bsparc-rtems5/erc32/lib/ \ > >> + -specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections \ > >> + -fdata-sections -Wall -Wmissing-prototypes > >> -Wimplicit-function-declaration > \ > >> + -Wstrict-prototypes -Wnested-externs -Wl,--gc-sections -mcpu=cypress > \ > >> + -o sparc-rtems5/c/erc32/testsuites/samples/fileio.exe > sparc-rtems5/c/erc32/\ > >> + testsuites/samples/fileio/fileio-init.o > >> + > >> +This is the trace linker command to generate and compile the wrapper c > file for > >> +the application. The link command follows the escape sequence "--". > "-C" option > >> +denotes the name of the user configuration file and "-W" specifies the > name of > >> +the wrapper c file. > >> + > >> +.. code:: shell > >> + > >> + rtems-tld -C fileio-trace.ini -W fileio-wrapper -- > -Bsparc-rtems5/erc32/lib/ \ > >> + -specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections \ > >> + -fdata-sections -Wall -Wmissing-prototypes > >> -Wimplicit-function-declaration > \ > >> + -Wstrict-prototypes -Wnested-externs -Wl,--gc-sections -mcpu=cypress > \ > >> + -o sparc-rtems5/c/erc32/testsuites/samples/fileio.exe > sparc-rtems5/c/erc32/\ > >> + testsuites/samples/fileio/fileio-init.o > >> + > >> +The following command is used to run the application. Hit enter key > quickly and > >> +type "s" and "root" and "pwd" to run the rtems shell. Use the `rtrace > status`, > >> +`rtrace trace` and `rtrace save` commands to know the status of the > tracing, > >> +display the contents of the trace buffer and save the buffer to disk > in the form > >> +of binary files. > >> + > >> +.. code:: shell > >> + > >> + sparc-rtems5-run sparc-rtems5/c/erc32/testsuites/samples/fileio.exe > >> + > >> +The output from the above commands will be as follows: > >> + > >> +.. code:: shell > >> + > >> + *** BEGIN OF TEST FILE I/O *** > >> + *** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8 > >> + *** TEST STATE: USER_INPUT > >> + *** TEST BUILD: RTEMS_NETWORKING RTEMS_POSIX_API > >> + *** TEST TOOLS: 7.3.0 20180125 (RTEMS 5, RSB > a3a6c34c150a357e57769a26a460c475e > >> + 188438f, Newlib 3.0.0) > >> + Press any key to start file I/O sample (20s remaining) > >> + Press any key to start file I/O sample (19s remaining) > >> + Press any key to start file I/O sample (18s remaining) > >> + Press any key to start file I/O sample (17s remaining) > >> + Press any key to start file I/O sample (16s remaining) > >> + Press any key to start file I/O sample (15s remaining) > >> + Press any key to start file I/O sample (14s remaining) > >> + ========================= > >> + RTEMS FILE I/O Test Menu > >> + ========================= > >> + p -> part_table_initialize > >> + f -> mount all disks in fs_table > >> + l -> list file > >> + r -> read file > >> + w -> write file > >> + s -> start shell > >> + Enter your selection ==>s > >> + Creating /etc/passwd and group with four useable accounts: > >> + root/pwd > >> + test/pwd > >> + rtems/NO PASSWORD > >> + chroot/NO PASSWORD > >> + Only the root user has access to all available commands. > >> + ========================= > >> + starting shell > >> + ========================= > >> + > >> + Welcome to rtems-5.0.0 (SPARC/w/FPU/erc32) > >> + COPYRIGHT (c) 1989-2008. > >> + On-Line Applications Research Corporation (OAR). > >> + > >> + Login into RTEMS > >> + /dev/foobar login: root > >> + Password: > >> + > >> + RTEMS Shell on /dev/foobar. Use 'help' to list commands. > >> + SHLL [/] # rtrace status > >> + RTEMS Trace Bufferring: status > >> + Running: yes > >> + Triggered: yes > >> + Level: 0% > >> + Traces: 25 > >> + SHLL [/] # rtrace stop > >> + RTEMS Trace Bufferring: stop > >> + SHLL [/] # rtrace trace > >> + RTEMS Trace Bufferring: trace > >> + Trace buffer: 0x20921d8 > >> + Words traced: 1487 > >> + Traces: 25 > >> + 0:00:40.983197010 2081910 0a010002 [ 2/ 2] > malloc((size_t) > 00000130) > >> + 0:00:40.983333119 136109 0a010002 [ 2/ 2] < malloc => (void*) > 0x219bb88 > >> + 0:00:40.983471669 138550 0a010002 [ 2/ 2] > malloc((size_t) > 00000006) > >> + 0:00:40.983606557 134888 0a010002 [ 2/ 2] < malloc => (void*) > 0x219bcc0 > >> + 0:00:40.983684682 78125 0a010002 [ 2/ 2] > malloc((size_t) > 00000007) > >> + 0:00:40.983819569 134887 0a010002 [ 2/ 2] < malloc => (void*) > 0x219bcd0 > >> + 0:00:40.983909901 90332 0a010002 [ 2/ 2] > malloc((size_t) > 000003fc) > >> + 0:00:40.984046620 136719 0a010002 [ 2/ 2] < malloc => (void*) > 0x219bce0 > >> + 0:00:40.986624137 2577517 0a010003 [200/200] > malloc((size_t) > 00000080) > >> + 0:00:40.986767569 143432 0a010003 [200/200] < malloc => (void*) > 0x219bce0 > >> + 0:00:40.987531119 763550 0a010003 [200/200] > calloc((size_t) > 00000001, (size_t) 0000005d) > >> + 0:00:40.987603751 72632 0a010003 [200/200] > malloc((size_t) > 0000005d) > >> + 0:00:40.987744743 140992 0a010003 [200/200] < malloc => (void*) > 0x219bce0 > >> + 0:00:40.987824699 79956 0a010003 [200/200] < calloc => (void*) > 0x219bce0 > >> + 0:00:40.988302604 477905 0a010003 [200/200] > malloc((size_t) > 00000080) > >> + 0:00:40.988446647 144043 0a010003 [200/200] < malloc => (void*) > 0x219bd48 > >> + 0:00:40.988667595 220948 0a010003 [200/200] > calloc((size_t) > 00000001, (size_t) 00000080) > >> + 0:00:40.988740837 73242 0a010003 [200/200] > malloc((size_t) > 00000080) > >> + 0:00:40.988884880 144043 0a010003 [200/200] < malloc => (void*) > 0x219bdd0 > >> + 0:00:40.988964836 79956 0a010003 [200/200] < calloc => (void*) > 0x219bdd0 > >> + 0:00:40.989042961 78125 0a010003 [200/200] > calloc((size_t) > 00000001, (size_t) 00000080) > >> + 0:00:40.989110100 67139 0a010003 [200/200] > malloc((size_t) > 00000080) > >> + 0:00:40.989254143 144043 0a010003 [200/200] < malloc => (void*) > 0x219be58 > >> + 0:00:40.989334099 79956 0a010003 [200/200] < calloc => (void*) > 0x219be58 > >> + 0:00:40.990118401 784302 0a010003 [200/200] > calloc((size_t) > 00000001, (size_t) 00000061) > >> + 0:00:40.990176995 58594 0a010003 [200/200] > malloc((size_t) > 00000061) > >> + 0:00:40.990309441 132446 0a010003 [200/200] < malloc => (void*) > 0x219bd48 > >> + 0:00:40.990384515 75074 0a010003 [200/200] < calloc => (void*) > 0x219bd48 > >> + 0:00:40.990870355 485840 0a010003 [200/200] > malloc((size_t) > 00000080) > >> + 0:00:40.991011346 140991 0a010003 [200/200] < malloc => (void*) > 0x219bee0 > >> + 0:00:40.991227411 216065 0a010003 [200/200] > calloc((size_t) > 00000001, (size_t) 00000080) > >> + 0:00:40.991296380 68969 0a010003 [200/200] > malloc((size_t) > 00000080) > >> + 0:00:40.991438593 142213 0a010003 [200/200] < malloc => (void*) > 0x219bf68 > >> + 0:00:40.991514276 75683 0a010003 [200/200] < calloc => (void*) > 0x219bf68 > >> + 0:00:40.991589349 75073 0a010003 [200/200] > calloc((size_t) > 00000001, (size_t) 00000080) > >> + 0:00:40.991653437 64088 0a010003 [200/200] > malloc((size_t) > 00000080) > >> + 0:00:40.991794428 140991 0a010003 [200/200] < malloc => (void*) > 0x219bff0 > >> + 0:00:40.991871332 76904 0a010003 [200/200] < calloc => (void*) > 0x219bff0 > >> + 0:00:40.992283320 411988 0a010003 [200/200] > malloc((size_t) > 00000008) > >> + SHLL [/] # rtrace save fileio-trace.bin > >> + RTEMS Trace Bufferring: trace > >> + Trace File: fileio-trace.bin > >> + Trace buffer: 0x20921d8 > >> + Words traced: 1487 > >> + Traces: 25 > >> + SHLL [/] # > >> + > >> diff --git a/user/tracing/index.rst b/user/tracing/index.rst > >> new file mode 100644 > >> index 0000000..b75261d > >> --- /dev/null > >> +++ b/user/tracing/index.rst > >> @@ -0,0 +1,30 @@ > >> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 > >> + > >> +.. comment: Copyright (c) 2016 Chris Johns <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 the operation of applications, 3rd party packages, > and the > >> +kernel in real time. > >> + > >> +Software based tracing is a complex process which requires components > on both > >> +the target and the host to work together. However its portability > across all > >> +architectures and board support packages makes it a useful asset. A key > >> +requirement in RTEMS trace process is to take existing code in > compiled format > >> +(ELF) and instrument it in order to log various events and records in > real time. > >> +However instrumenting of the code for tracing should happen without > rebuilding > >> +the code from the source and without annotating the source with trace > code. > >> + > >> +.. toctree:: > >> + > >> + introduction > >> + examples > >> + captureengine > >> + tracelinker > >> + > >> diff --git a/user/tracing/introduction.rst b/user/tracing/introduction. > rst > >> new file mode 100644 > >> index 0000000..7b9e1d3 > >> --- /dev/null > >> +++ b/user/tracing/introduction.rst > >> @@ -0,0 +1,105 @@ > >> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 > >> + > >> +.. comment: Copyright (c) 2016 Chris Johns <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 their BSP and > invokes the > >> +trace linker using a command to link the application executable. The > trace > >> +linker uses the application files in compiled format (ELF) and the > libraries > >> +used to build the application for performing this link. > >> + > >> +Step 2: The RTEMS Trace Linker reads the user’s configuration file and > that > >> +results in it reading the standard Trace Buffering Configuration files > >> +installed with the RTEMS Trace Linker. The trace linker uses the target > >> +compiler and linker to create the trace enabled application > executable. It > >> +wraps the functions defined in the user’s configuration with code that > captures > >> +trace records into the statically allocated buffer. The trace wrapper > code is > >> +compiled with the target compiler and the resulting ELF object file is > added to > >> +the standard link command line used to link the application and the > application > >> +is re-linked using the wrapping option of the GNU linker. > >> + > >> +Step 3: The trace linker creates an executable which is capable of > running on > >> +the target hardware or simulator. > >> + > >> +Step 4: RTEMS shell provides the “rtrace” command to display and save > trace > >> +buffers. > >> + > >> +.. comment: taken from https://devel.rtems.org/wiki/Developer/Tracing > >> +.. figure:: ../../images/user/rtems-trace-buffering.png > >> + :align: center > >> + :width: 75% > >> + > >> +.. _printk: > >> + > >> +RTEMS Trace Using Printk > >> +======================== > >> + > >> +This scheme of tracing goes through the flow of events described in a > subsequent > >> +flowchart: > >> + > >> +Step 1: The user creates an RTEMS application in the normal manner as > well as a > >> +Trace Linker configuration file. The configuration file specifies > using the > >> +Printk trace mode and the functions to trace. The user invokes the > Trace Linker > >> +with the configuration and the normal link command line used to the > link the > >> +application executable. The application ELF object files and libraries, > >> +including the RTEMS libraries are standard and do not need to be built > >> +specially. > >> + > >> +Step 2: The RTEMS Trace Linker reads the user's configuration file and > that > >> +results in it reading the standard Printk Trace Configuration files > installed > >> +with the RTEMS Trace Linker. The trace linker uses the target compiler > and > >> +linker to create the trace enabled application executable. It wraps the > >> +functions defined in the user's configuration with code that prints > the entry > >> +with arguments and exit and return value if any. The trace wrapper > code is > >> +compiled with the target compiler and the resulting ELF object file is > added to > >> +the standard link command line used to link the application and the > application > >> +is relinked using the wrapping option of the GNU linker. > >> + > >> +Step 3: The trace linker creates and RTEMS ELF executable that can be > run on the > >> +target hardware or simulator. > >> + > >> +Step 4: The application is run in the hardware directly or using a > debugger. The > >> +printk() output appears on the target console and the user can save > that to a > >> +file. > >> + > >> +.. comment: taken from https://devel.rtems.org/wiki/Developer/Tracing > >> +.. figure:: ../../images/user/rtems-trace-printk.png > >> + :align: center > >> + :width: 75% > >> + > >> +The :ref:`examples` section describes generation of traces using both > of the > >> +aforementioned techniques using the `fileio` testsuite available with > RTEMS > >> +installation. > >> diff --git a/user/tracing/tracelinker.rst b/user/tracing/tracelinker.rst > >> new file mode 100644 > >> index 0000000..a95ec41 > >> --- /dev/null > >> +++ b/user/tracing/tracelinker.rst > >> @@ -0,0 +1,501 @@ > >> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 > >> + > >> +.. comment: Copyright (c) 2016 Chris Johns <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 > > s/Rtems/RTEMS > > > > It is ok to use 'rtems' or 'RTEMS' but 'Rtems' is strange. > > > >> + printf. > >> + > >> +The configuration files are in the *INI file format* which is composed > of > >> +`sections`. Each section has a section name and set of *keys* which > consist of > >> +*names* and *values*. A typical key is of the form ``name=value``. > Keys can be > >> +used to include other INI files using the include key name. This is > shown in the > >> +following example where the values indicate rtems and rtld-base > configuration > >> +files: > >> + > >> +.. code-block:: shell > >> + > >> + include = rtems.ini, rtld-base.ini > >> + > >> +The trace linker also uses values in keys to specify other sections. > In this > >> +example the functions name lists `test-trace-funcs` and that section > contains a > >> +headers key that further references a section called `test-headers`: > >> + > >> +.. code-block:: shell > >> + > >> + functions = test-trace-funcs, rtems-api > >> + > >> + [test-trace-funcs] > >> + ; Parsed via the 'function-set', not parse as a 'trace'. > >> + headers = test-headers > >> + > >> + [test-headers] > >> + header = '#include "test-trace-1.h"' > >> + > >> +The format of a configuration file is explained next. Snippets of the > file: > >> +`test-trace.ini` have been used for explicit understanding. This file > can > >> +be found in the rtems-tools directory of the rtems installation. > >> + > >> +Tracer Section > >> +-------------- > >> + > >> +The topmost level section is the ``tracer`` section. It can contains > the > >> +following keys: > >> + > >> +- ``name``: The name of trace being linked. > >> + > >> +- ``options``: A list of option sections. > >> + > >> +- ``defines``: A list of sections containing defines or define record. > >> + > >> +- ``define``: A list of define string that are single or double quoted. > >> + > >> +- ``enables``: The list of sections containing enabled functions to > trace. > >> + > >> +- ``triggers``: The list of sections containing enabled functions to > trigger > >> + trace on. > >> + > >> +- ``traces``: The list of sections containing function lists to trace. > >> + > >> +- ``functions``: The list of sections containing function details. > >> + > >> +- ``include``: The list of files to include > >> + > >> +The tracer section of the file:`test-trace.ini` is shown below with > explanatory > >> +comments. > >> + > >> +.. code-block:: shell > >> + > >> + ; > >> + ; RTEMS Trace Linker Test Configuration. > >> + ; > >> + ; We must provide a top level trace section. > >> + ; > >> + [tracer] > >> + ; > >> + ; Name of the trace. > >> + ; > >> + name = RTEMS Trace Linker Test > >> + ; > >> + ; The BSP. > >> + ; > >> + bsp = sparc/sis > >> + ; > >> + ; Functions to trace. > >> + ; > >> + traces = test-trace, test-trace-funcs, rtems-api-task > >> + ; > >> + ; Specify the options. > >> + ; > >> + options = test-options > >> + ; > >> + ; Define the function sets. These are the function's that can be > >> + ; added to the trace lists. > >> + ; > >> + functions = test-trace-funcs, rtems-api > >> + ; > >> + ; Include RTEMS Trace support. > >> + ; > >> + include = rtems.ini, rtld-base.ini > >> + > >> +Options section > >> +--------------- > >> + > >> +The options section in the fileio-trace.ini is called the > `fileio-options`. A > >> +general options section can contain following sets of keys: > >> + > >> +- ``dump-on-error``: Dump the parsed configuration data on error. The > value can > >> + be true or false. > >> + > >> +- ``verbose``: Set the verbose level. The value can be true or a > number value. > >> + > >> +- ``prefix``: The prefix for the tools and an install RTEMS if > rtems-path is not > >> + set. > >> + > >> +- ``cc``: The compiler used to compile the generated wrapper code. > Overrides the > >> + BSP configuration value if a BSP > >> + is specified. > >> + > >> +- ``ld``: The linker used to link the application. The default is the > cc value > >> + as read from the BSP configuration if specified. If your application > contains > >> + C++ code use this setting to the change the linker to g++. > >> + > >> +- ``cflags``: Set the CFLAGS used to compiler the wrapper. These flags > are > >> + pre-pended to the BSP read flags if a BSP is specified. This option > is used > >> + to provide extra include paths to header files in your application > that > >> + contain types referenced by functions being traced. > >> + > >> +- ``rtems-path``: The path to an install RTEMS if not installed under > the prefix. > >> + > >> +- ``rtems-bsp``: The BSP we are building the trace executable for. The > is an > >> + arch and bsp pair. For example sparc/erc32. > >> + > >> +The options section of the file: `test-trace.ini` uses two of the > aforementioned > >> +keys as shown below: > >> + > >> +.. code-block:: shell > >> + > >> + ; > >> + ; Options can be defined here or on the command line. > >> + ; > >> + [test-options] > >> + prefix = /development/rtems/5 > >> + verbose = true > >> + > >> +Trace Section > >> +-------------- > >> + > >> +A trace section defines how trace wrapper functions are built. To > build a trace > >> +function that wraps an existing function in an ELF object file or > library > >> +archive we need to have the function's signature. A signature is the > function's > >> +declaration with any types used. The signature has specific types and > we need > >> +access to those types which means the wrapper code needs to include > header files > >> +that define those types. There may also be specific defines needed to > access > >> +those types. A trace section can contain the following keys: > >> + > >> +- ``generator``: The generator defines the type of tracing being used. > >> + > >> +- ``headers``: List of sections that contain header file's keys. > >> + > >> +- ``header``: A header key. Typically the include code. > >> + > >> +- ``defines``: List of sections that contain defines. > >> + > >> +- ``define``: A define key. Typically the define code. > >> + > >> +- ``signatures``: List of function signature sections. > >> + > >> +- ``trace``: Functions that are instrumented with trace code. > >> + > >> +The trace section of the file: `test-trace.ini` is shown below. A > trace section > >> +can reference other trace sections of a specific type. This allows a > trace > >> +sections to build on other trace sections. > >> + > >> +.. code:: shell > >> + > >> + ; User application trace example. > >> + ; > >> + [test-trace] > >> + generator = printf-generator > >> + ; Just here for testing. > >> + trace = test_trace_3 > >> + > >> + [test-trace-funcs] > >> + ; Parsed via the 'function-set', not parse as a 'trace'. > >> + headers = test-headers > >> + header = '#include "test-trace-2.h"' > >> + defines = test-defines > >> + define = "#define TEST_TRACE_2 2" > >> + signatures = test-signatures > >> + ; Parsed via the 'trace', not parsed as a function-set > >> + trace = test_trace_1, test_trace_2 > >> + > >> + [test-headers] > >> + header = '#include "test-trace-1.h"' > >> + > >> + [test-defines] > >> + define = "#define TEST_TRACE_1 1" > >> + > >> + [test-signatures] > >> + test_trace_1 = void, int > >> + test_trace_2 = test_type_2, test_type_1 > >> + test_trace_3 = float, float* > >> + > >> +Function Section > >> +---------------- > >> + > >> +Function sections define functions that can be traced. They provide > any required > >> +defines, header files, and the function signatures. Defining a > function so it > >> +can be traced does not mean it is traced. The function must be added > to a trace > >> +list to be traced. A function section can consist of the following > keys: > >> + > >> +- ``headers``: A list of sections containing headers or header records. > >> +- ``header``: A list of include string that are single or double > quoted. > >> +- ``defines``: A list of sections containing defines or define record. > >> +- ``defines``: A list of define string that are single or double > quoted. > >> +- ``signatures``: A list of section names of function signatures. > >> +- ``includes``: A list of files to include. > >> + > >> +Function signatures are specified with the function name being the > key's name > >> +and the key's value being the return value and a list of function > arguments. You > >> +need to provide void if the function uses void. Variable argument list > are > >> +currently not supported. There is no way to determine statically a > variable > >> +argument list. The function section in the file: `test-trace.ini` has > been > >> +labeled as `test-trace-funcs`. This can be seen in the file snippet of > the > >> +previous section. > >> + > >> +Generators > >> +---------- > >> + > >> +Generator section specify how to generate trace wrapping code. The > trace > >> +linker and generator section must match to work. The trace linker > expects a some > >> +things to be present when wrapping functions. The section's name > specifies the > >> +generator and can be listed in a generator key in a tracer or trace > section. If > >> +the generator is not interested in a specific phase it does not need > to define > >> +it. Nothing will be generated in regard to this phase. For example > code to > >> +profile specific functions may only provide the entry-trace and > exit-trace code > >> +where a nano-second time stamp is taken. > >> + > >> +The generate code will create an entry and exit call and the generator > code > >> +block can be used to allocate buffer space for each with the lock > held. The > >> +entry call and argument copy is performed with the lock released. The > buffer > >> +space having been allocated will cause the trace events to be in > order. The same > >> +goes for the exit call. Space is allocated in separate buffer allocate > calls so > >> +the blocking calls will have the exit event appear in the correct > location in > >> +the buffer. > >> + > >> +The following keys can be a part of the generator configuration: > >> + > >> +- ``headers``: A list of sections containing headers or header records. > >> +- ``header``: A list of include string that are single or double > quoted. > >> +- ``defines``: A list of sections containing defines or define record. > >> +- ``define``: A list of define string that are single or double quoted. > >> +- ``entry-trace``: The wrapper call made on a function's entry. > Returns bool > >> + where true is the function is being traced. This call is made > without the lock > >> + being held if a lock is defined. > >> +- ``arg-trace``: The wrapper call made for each argument to the trace > function > >> + if the function is being traced. This call is made without the lock > being held > >> + if a lock is defined. > >> +- ``exit-trace``: The wrapper call made after a function's exit. > Returns bool > >> + where true is the function is being traced. This call is made > without the lock > >> + being held if a lock is defined. > >> +- ``ret-trace``: The wrapper call made to log the return value if the > function > >> + is being traced. This call is made without the lock being held if a > lock is > >> + defined. > >> +- ``lock-local``: The wrapper code to declare a local lock variable. > >> +- ``lock-acquire``: The wrapper code to acquire the lock. > >> +- ``lock-release``: The wrapper code to release the lock. > >> +- ``buffer-local``: The wrapper code to declare a buffer index local > variable. > >> +- ``buffer-alloc``: The wrapper call made with a lock held if defined > to > >> + allocate buffer space to hold the trace data. A suitable 32bit > buffer index is > >> + returned. If there is no space an invalid index is returned. The > generator > >> + must handle any overhead space needed. The generator needs to make > sure the > >> + space is available before making the alloc all. > >> +- ``code-blocks``: A list of code block section names. > >> +- ``code``: A code block in <<CODE --- CODE (without the single quote). > >> +- ``includes``: A list of files to include. > >> + > >> +The following macros can be used in wrapper calls: > >> + > >> +- ``@FUNC_NAME@``: The trace function name as a quote C string. > >> +- ``@FUNC_INDEX@``: The trace function index as a held in the sorted > list of > >> + trace functions by the trace linker. It can be used to index the > names, > >> + enables, and triggers data. > >> +- ``@FUNC_LABEL@``: The trace function name as a C label that can be > referenced. > >> + You can take the address of the label. > >> +- ``@FUNC_DATA_SIZE@``: The size of the data in bytes. > >> +- ``@FUNC_DATA_ENTRY_SIZE@``: The size of the entry data in bytes. > >> +- ``@FUNC_DATA_RET_SIZE@``: The size of the return data in bytes. > >> +- ``@ARG_NUM@``: The argument number to the trace function. > >> +- ``@ARG_TYPE@``: The type of the argument as a C string. > >> +- ``@ARG_SIZE@``: The size of the type of the argument in bytes. > >> +- ``@ARG_LABEL@``: The argument as a C label that can be referenced. > >> +- ``@RET_TYPE@``: The type of the return value as a C string. > >> +- ``@RET_SIZE@``: The size of the type of the return value in bytes. > >> +- ``@RET_LABEL@``: The return value as a C label that can be > referenced. > >> + > >> +The `buffer-alloc`, `entry-trace`, and `exit-trace` can be transformed > using the > >> +following macros: > >> + > >> +- ``@FUNC_NAME@`` > >> +- ``@FUNC_INDEX@`` > >> +- ``@FUNC_LABEL@`` > >> +- ``@FUNC_DATA_SZIE@`` > >> +- ``@FUNC_DATA_ENTRY_SZIE@`` > >> +- ``@FUNC_DATA_EXIT_SZIE@`` > >> + > >> +The `arg-trace` can be transformed using the following macros: > >> + > >> +- ``@ARG_NUM@`` > >> +- ``@ARG_TYPE@`` > >> +- ``@ARG_SIZE@`` > >> +- ``@ARG_LABEL@`` > >> + > >> +The `ret-trace` can be transformed using the following macros: > >> + > >> +- ``@RET_TYPE@`` > >> +- ``@RET_SIZE@`` > >> +- ``@RET_LABEL@`` > >> + > >> +The file: `test-trace.ini` specifies ``printf-generator`` as its > generator. This > >> +section can be found in the file: `rtld-print.ini` in the rtems-tools > directory > >> +and is shown below: > >> + > >> +.. code:: shell > >> + > >> + ; > >> + ; A printf generator prints to stdout the trace functions. > >> + ; > >> + [printf-generator] > >> + headers = printf-generator-headers > >> + entry-trace = "rtld_pg_printf_entry(@FUNC_NAME@, (void*) > &@FUNC_LABEL@);" > >> + arg-trace = "rtld_pg_printf_arg(@ARG_NUM@, @ARG_TYPE@, @ARG_SIZE@, > (void*) &@ARG_LABEL@);" > >> + exit-trace = "rtld_pg_printf_exit(@FUNC_NAME@, (void*) &@FUNC_LABEL@ > );" > >> + ret-trace = "rtld_pg_printf_ret(@RET_TYPE@, @RET_SIZE@, (void*) > &@RET_LABEL@);" > >> + code = <<<CODE > >> + static inline void rtld_pg_printf_entry(const char* func_name, > >> + void* func_addr) > >> + { > >> + printf (">>> %s (0x%08x)\n", func_name, func_addr); > >> + } > >> + static inline void rtld_pg_printf_arg(int arg_num, > >> + const char* arg_type, > >> + int arg_size, > >> + void* arg) > >> + { > >> + const unsigned char* p = arg; > >> + int i; > >> + printf (" %2d] %s(%d) = ", arg_num, arg_type, arg_size); > >> + for (i = 0; i < arg_size; ++i, ++p) printf ("%02x", (unsigned int) > *p); > >> + printf ("\n"); > >> + } > >> + static inline void rtld_pg_printf_exit(const char* func_name, > >> + void* func_addr) > >> + { > >> + printf ("<<< %s (0x%08x)\n", func_name, func_addr); > >> + } > >> + static inline void rtld_pg_printf_ret(const char* ret_type, > >> + int ret_size, > >> + void* ret) > >> + { > >> + const unsigned char* p = ret; > >> + int i; > >> + printf (" rt] %s(%d) = ", ret_type, ret_size); > >> + for (i = 0; i < ret_size; ++i, ++p) printf ("%02x", (unsigned int) > *p); > >> + printf ("\n"); > >> + } > >> + CODE > >> + > >> + [printf-generator-headers] > >> + header = "#include <stdio.h>" > >> + > >> +Function Wrapping > >> +================= > >> + > >> +The trace linker's major role is to wrap functions in the existing > executable > >> +with trace code. The directions on how to wrap application functions > is provided > >> +by the generator configuration. The wrapping function uses a GNU > linker option > >> +called --wrap=symbol. The GNU Ld manual states: > >> + > >> +"Use a wrapper function for symbol. Any undefined reference to symbol > will be > >> +resolved to __wrap_symbol. Any undefined reference to __real_symbol > will be > >> +resolved to symbol." > >> + > >> +The trace linker generates C code with a wrapper for each function to > be > >> +instrumented. The trace code generated is driven by the configuration > INI files. > >> + > >> +Function Signatures > >> +=================== > >> + > >> +A function signature is the function's declaration. It is the name of > the > >> +function, the return value, and the arguments. Tracing using function > wrappers > >> +requires that we have accurate function signatures and ideally we > would like to > >> +determine the function signature from the data held in ELF files. ELF > files can > >> +contain DWARF data, the ELF debugging data format. In time the trace > project > >> +would like to support libdwarf so the DWARF data can be accessed and > used to > >> +determine a function's signature. This work is planned but not > scheduled to be > >> +done and so in the meantime we explicitly define the function > signatures in the > >> +configuration files. > >> + > > > > These two sections "Function Wrapping" and "Function Signatures" seem > > misplaced. I suspect they belong before Generators, maybe merged with > > the "Function Sections" part? > > > >> + > >> +Development > >> +=========== > >> + > >> +The Trace Linker is part of the RTEMS tools git repository available > at : > >> +https://git.rtems.org/rtems-tools > >> +The RTEMS tools project utilizes the waf build system. Use the > following > >> +commands in the topmost build directory to build the tools project: > >> + > >> +First we configure using: > >> + > >> +.. code-block:: shell > >> + > >> + $./waf configure --prefix=$HOME/development/rtems/5 > >> + > >> +Then we build and install using: > >> + > >> +.. code-block:: shell > >> + > >> + $./waf build install > >> + > >> + > >> -- > >> 2.7.4 > >> > >> _______________________________________________ > >> devel mailing list > >> devel@rtems.org > >> http://lists.rtems.org/mailman/listinfo/devel >
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
