From 21c4a44451dcc8a5b5935ad50e2d663c56098a39 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 30 Jan 2019 11:40:05 +0100 Subject: user: Add basic event recording documentation Update #3665. --- user/tracing/captureengine.rst | 2 +- user/tracing/eventrecording.rst | 58 +++++++++++++++++++++++++++++++++++++++++ user/tracing/index.rst | 1 + user/tracing/introduction.rst | 5 ++-- user/tracing/tracelinker.rst | 2 +- 5 files changed, 64 insertions(+), 4 deletions(-) create mode 100644 user/tracing/eventrecording.rst (limited to 'user/tracing') diff --git a/user/tracing/captureengine.rst b/user/tracing/captureengine.rst index b976825..fab8bed 100644 --- a/user/tracing/captureengine.rst +++ b/user/tracing/captureengine.rst @@ -2,7 +2,7 @@ .. Copyright (C) 2018 Vidushi Vashishth -.. _capturengine: +.. _CaptureEngine: Capture Engine ************** diff --git a/user/tracing/eventrecording.rst b/user/tracing/eventrecording.rst new file mode 100644 index 0000000..d799774 --- /dev/null +++ b/user/tracing/eventrecording.rst @@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019 embedded brains GmbH +.. Copyright (C) 2019 Sebastian Huber + +.. _EventRecording: + +Event Recording +=============== + +The `event recording` support focuses on the recording of high frequency +events such as + + * thread switches, + * thread queue enqueue and surrender, + * interrupt entry and exit, + * heap/workspace memory allocate/free, + * UMA zone allocate/free, + * Ethernet packet input/output, and + * etc. + +There is a fixed set of 512 system reserved and 512 user defined events which +are identified by an event number (:c:type:`rtems_record_event`). + +The event recording support allows post-mortem analysis in fatal error +handlers, e.g. the last events are in the record buffers, the newest event +overwrites the oldest event. It is possible to detect record buffer overflows +for consumers that expect a continuous stream of events, e.g. to display the +system state changes in real-time. + +The implementation supports high-end SMP machines (more than 1GHz processor +frequency, more than four processors). It uses per-processor ring buffers to +record the events. Synchronization is done without atomic read-modify-write +operations. The CPU counter is used to get the time of events. It is combined +with periodic uptime events to synchronize it with the monotonic system clock +(:c:macro:`CLOCK_MONOTONIC`). + +The application must configure the event recording via the configuration options +:c:macro:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` and +:c:macro:`CONFIGURE_RECORD_EXTENSIONS_ENABLED`. + +Events can be recorded for example with the :c:func:`rtems_record_produce` +function. + +.. code-block:: c + + #include + + void f( void ) + { + rtems_record_produce( RTEMS_RECORD_USER( 0 ), 123 ); + } + +Recorded events can be sent to a host computer with a very simple record server +started by :c:func:`rtems_record_start_server` via a TCP connection. + +On the host computer you may use the command line tool :file:`rtems-record` to +get recorded events from the record server running on the target system. diff --git a/user/tracing/index.rst b/user/tracing/index.rst index 3f0c90b..ed9028a 100644 --- a/user/tracing/index.rst +++ b/user/tracing/index.rst @@ -26,3 +26,4 @@ the code from the source and without annotating the source with trace code. examples captureengine tracelinker + eventrecording diff --git a/user/tracing/introduction.rst b/user/tracing/introduction.rst index a3b4904..d6f249f 100644 --- a/user/tracing/introduction.rst +++ b/user/tracing/introduction.rst @@ -17,8 +17,9 @@ RTEMS tracing framework is under development and welcomes contribution by users. RTEMS has the following trace components: -- RTEMS :ref:`tracelinker` -- RTEMS :ref:`capturengine` +- :ref:`RTEMS Trace Linker ` +- :ref:`RTEMS Capture Engine ` +- :ref:`RTEMS Event Recording ` - Common Trace Format Integration RTEMS trace framework can currently function using the following methods. Both diff --git a/user/tracing/tracelinker.rst b/user/tracing/tracelinker.rst index 0fd1757..8aad20f 100644 --- a/user/tracing/tracelinker.rst +++ b/user/tracing/tracelinker.rst @@ -2,7 +2,7 @@ .. Copyright (C) 2016 Chris Johns -.. _tracelinker: +.. _TraceLinker: Trace Linker ************ -- cgit v1.2.3