Re: [PATCH v3 2/2] Adding trace documentation
I was using Sublime text. It appeared okay on the editor. I have changed my editor and sent another patch. Thanks. On Tue, Jun 12, 2018 at 9:46 PM, Gedare Bloom wrote: > On Tue, Jun 12, 2018 at 11:15 AM, Vidushi Vashishth > wrote: > > > > Adjusted line length to 79-80 > > --- > > user/index.rst | 2 + > > user/tracing/captureengine.rst | 188 ++ > > user/tracing/examples.rst | 12 ++ > > user/tracing/index.rst | 33 + > > user/tracing/introduction.rst | 184 ++ > > user/tracing/tracelinker.rst | 294 ++ > +++ > > user/tracing/usecases.rst | 129 ++ > > 7 files changed, 842 insertions(+) > > create mode 100644 user/tracing/captureengine.rst > > create mode 100644 user/tracing/examples.rst > > create mode 100644 user/tracing/index.rst > > create mode 100644 user/tracing/introduction.rst > > create mode 100644 user/tracing/tracelinker.rst > > create mode 100644 user/tracing/usecases.rst > > > > diff --git a/user/index.rst b/user/index.rst > > index 8cbcd1b..a764fe8 100644 > > --- a/user/index.rst > > +++ b/user/index.rst > > @@ -52,6 +52,8 @@ to the Community Project hosted at > http://www.rtems.org/. > > > > tools/index > > > > +tracing/index > > + > > support/index > > > > glossary/index > > diff --git a/user/tracing/captureengine.rst > b/user/tracing/captureengine.rst > > new file mode 100644 > > index 000..b80d7d0 > > --- /dev/null > > +++ b/user/tracing/captureengine.rst > > @@ -0,0 +1,188 @@ > > +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 > > + > > +.. comment: Copyright (c) 2016 Chris Johns > > +.. comment: All rights reserved. > > + > > +.. _capturengine: > > + > > +Capture Engine > > +** > > + > > +Capture Engine is a trace tool built inside the RTEMS operating system. > Capture > > +Engine > > It is not right to just blanket wrap to 80 characters. This one word > on a line by itself is no good. Many text editors can make the > wrapping work in a nice way, but I don't know what editor you use. For > example, I use vim, and text formatting can be done by highlighting > text in Visual mode and using 'gq' command to reformat. > > > +is designed to cause the lowest load on the system when operating. > Hence it > > +does not > > +effect RTEMS when operating or when disabled. It binds to RTEMS at > runtime and > > +does not > > +require RTEMS or your application to be rebuilt in order to use it. > > + > > +The Capture Engine's sample testcase for the `sparc/erc32` is available > in the > > +"$HOME/development/rtems/kernel/erc32/sparc-rtems5/c/ > erc32/testsuites/samples" > > +directory, > > +provided you followed the installation directions of the quickstart > section. In > > +order to > > +access the capture testcase perform the following set of operations. > > + > > +.. code-block:: shell > > + > > + $ cd > > + $HOME/development/rtems/kernel/erc32/sparc-rtems5/c/ > erc32/testsuites/samples > > + $ ../samples > > + $ sparc-rtems5-run ./capture.exe > > + > > + > > + *** BEGIN OF TEST CAPTURE ENGINE *** > > + *** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8 > > + *** TEST STATE: USER_INPUT > > + *** TEST BUILD: RTEMS_NETWORKING RTEMS_POSIX_API > > + *** TEST TOOLS: 7.3.0 20180125 (RTEMS 5, RSB > > + a3a6c34c150a357e57769a26a460c475e188438f, Newlib 3.0.0) > > + Press any key to start capture engine (20s remaining) > > + Press any key to start capture engine (19s remaining) > > + Press any key to start capture engine (18s remaining) > > + > > + Monitor ready, press enter to login. > > + > > + 1-rtems $ > > + > > +Capture Engine comes with a set of commands to perform various actions. > > + > > +Capture Engine Commands > > +--- > > + > > +1) ``copen ``: 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 ``: Capture Engine filter used to put an > upper > > + limit on the event priority to be captured. > > + > > + > > +3) ``cwfloor ``: Capture Engine filter used to put a > lower > > + limit on the event priority to be captured. > > + > > + > > +4) ``cwglob ``: 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 ``: Add watch on a particular task. > > + > > + > > +10) ``cwtctl ``: Enable or disable watch on a > particular > > +task. > > + > > + > > +11)
[PATCH v3 2/2] Adding trace documentation
Adjusted line length to 79-80 --- user/index.rst | 2 + user/tracing/captureengine.rst | 188 ++ user/tracing/examples.rst | 12 ++ user/tracing/index.rst | 33 + user/tracing/introduction.rst | 184 ++ user/tracing/tracelinker.rst | 294 + user/tracing/usecases.rst | 129 ++ 7 files changed, 842 insertions(+) create mode 100644 user/tracing/captureengine.rst create mode 100644 user/tracing/examples.rst create mode 100644 user/tracing/index.rst create mode 100644 user/tracing/introduction.rst create mode 100644 user/tracing/tracelinker.rst create mode 100644 user/tracing/usecases.rst diff --git a/user/index.rst b/user/index.rst index 8cbcd1b..a764fe8 100644 --- a/user/index.rst +++ b/user/index.rst @@ -52,6 +52,8 @@ to the Community Project hosted at http://www.rtems.org/. tools/index +tracing/index + support/index glossary/index diff --git a/user/tracing/captureengine.rst b/user/tracing/captureengine.rst new file mode 100644 index 000..b80d7d0 --- /dev/null +++ b/user/tracing/captureengine.rst @@ -0,0 +1,188 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2016 Chris Johns +.. comment: All rights reserved. + +.. _capturengine: + +Capture Engine +** + +Capture Engine is a trace tool built inside the RTEMS operating system. Capture +Engine +is designed to cause the lowest load on the system when operating. Hence it +does not +effect RTEMS when operating or when disabled. It binds to RTEMS at runtime and +does not +require RTEMS or your application to be rebuilt in order to use it. + +The Capture Engine's sample testcase for the `sparc/erc32` is available in the +"$HOME/development/rtems/kernel/erc32/sparc-rtems5/c/erc32/testsuites/samples" +directory, +provided you followed the installation directions of the quickstart section. In +order to +access the capture testcase perform the following set of operations. + +.. code-block:: shell + + $ cd + $HOME/development/rtems/kernel/erc32/sparc-rtems5/c/erc32/testsuites/samples + $ ../samples + $ sparc-rtems5-run ./capture.exe + + + *** BEGIN OF TEST CAPTURE ENGINE *** + *** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8 + *** TEST STATE: USER_INPUT + *** TEST BUILD: RTEMS_NETWORKING RTEMS_POSIX_API + *** TEST TOOLS: 7.3.0 20180125 (RTEMS 5, RSB + a3a6c34c150a357e57769a26a460c475e188438f, Newlib 3.0.0) + Press any key to start capture engine (20s remaining) + Press any key to start capture engine (19s remaining) + Press any key to start capture engine (18s remaining) + + Monitor ready, press enter to login. + + 1-rtems $ + +Capture Engine comes with a set of commands to perform various actions. + +Capture Engine Commands +--- + +1) ``copen ``: 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 ``: Capture Engine filter used to put an upper + limit on the event priority to be captured. + + +3) ``cwfloor ``: Capture Engine filter used to put a lower + limit on the event priority to be captured. + + +4) ``cwglob ``: 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 ``: Add watch on a particular task. + + +10) ``cwtctl ``: 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
