summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorSebastian Huber <sebastian.huber@embedded-brains.de>2019-01-30 11:40:05 +0100
committerSebastian Huber <sebastian.huber@embedded-brains.de>2019-02-01 09:52:03 +0100
commit21c4a44451dcc8a5b5935ad50e2d663c56098a39 (patch)
treec3a55674a1014cd2dd6aa63dd1f3f9695bf4dec8
parentc-user: Add event recording configuration (diff)
downloadrtems-docs-21c4a44451dcc8a5b5935ad50e2d663c56098a39.tar.bz2
user: Add basic event recording documentation
Update #3665.
-rw-r--r--user/tracing/captureengine.rst2
-rw-r--r--user/tracing/eventrecording.rst58
-rw-r--r--user/tracing/index.rst1
-rw-r--r--user/tracing/introduction.rst5
-rw-r--r--user/tracing/tracelinker.rst2
5 files changed, 64 insertions, 4 deletions
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 <vidushivashishth96@gmail.com>
-.. _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 <rtems/record.h>
+
+ 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 <TraceLinker>`
+- :ref:`RTEMS Capture Engine <CaptureEngine>`
+- :ref:`RTEMS Event Recording <EventRecording>`
- 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 <chrisj@rtems.org>
-.. _tracelinker:
+.. _TraceLinker:
Trace Linker
************