YuuichiNakamura commented on a change in pull request #1955: URL: https://github.com/apache/incubator-nuttx/pull/1955#discussion_r505931387
########## File path: Documentation/guides/tasktraceuser.rst ########## @@ -0,0 +1,348 @@ +===================== +Task Trace User Guide +===================== + +Installation +============ + +Install Trace Compass +--------------------- + +Task Trace uses the external tool `"Trace Compass" <https://www.eclipse.org/tracecompass/>`_ to display the trace result. + +Download it from https://www.eclipse.org/tracecompass/ and install into the host environment. +After the installation, execute it and choose ``Tools`` -> ``add-ons`` menu, then select ``Install Extensions`` to install the extension named "Trace Compass ftrace (Incubation)". + +NuttX kernel configuration +-------------------------- + +To enable the task trace function, the NuttX kernel configuration needs to be modified. + +The following configurations must be enabled. + +- ``CONFIG_SCHED_INSTRUMENTATION`` : Enables the feature of scheduler notes. +- ``CONFIG_SCHED_INSTRUMENTATION_FILTER`` : Enables the filter logic of the notes. +- ``CONFIG_SCHED_INSTRUMENTATION_SYSCALL`` : Enable system call instrumentation. +- ``CONFIG_SCHED_INSTRUMENTATION_IRQHANDLER`` : Enables IRQ instrumentation. +- ``CONFIG_DRIVER_NOTE`` : Enables note driver support. +- ``CONFIG_DRIVER_NOTERAM`` : Enables ``/dev/note`` in-memory buffering driver. +- ``CONFIG_DRIVER_NOTECTL`` : Enables ``/dev/notectl`` filter control driver. +- ``CONFIG_SYSTEM_TRACE`` : Enables "``trace``" command +- ``CONFIG_SYSTEM_SYSTEM`` : Enables "``system``" command (required by :ref:`trace_cmd`) + + +The following configurations are configurable parameters for trace. + +- ``CONFIG_SCHED_INSTRUMENTATION_FILTER_DEFAULT_MODE`` + + - Specify the default filter mode. + If the following bits are set, the corresponding instrumentations are enabled on boot. + + - Bit 0 = Enable instrumentation + - Bit 1 = Enable syscall instrumentation + - Bit 2 = Enable IRQ instrumentation + +- ``CONFIG_SCHED_INSTRUMENTATION_NOTERAM_BUFSIZE`` + + - Specify the note buffer size in bytes. + Higher value can hold more note records, but consumes more kernel memory. + +- ``CONFIG_SCHED_INSTRUMENTATION_NOTERAM_DEFAULT_NOOVERWRITE`` + + - If enabled, stop overwriting old notes in the circular buffer when the buffer is full by default. + This is useful to keep instrumentation data of the beginning of a system boot. + +After the configuration, rebuild the NuttX kernel and application. + +If the trace function is enabled, "``trace``" :doc:`../components/nsh/builtin` will be available. Review comment: `NSH “Built-In” Applications` is different to NSH commands. > In addition to these commands that are a part of NSH, external programs can also be executed as NSH commands. These external programs are called "Built-In" Applications for historic reasons. Based on this description in components/nsh/builtin.rst, "trace" is a built-in application. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
