(nuttx) 12/13: coresight: add document for coresight

[xi...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

xiaoxiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git

commit b98d68599e74e68e13f843a3d1626762fa0ff3d9
Author: liaoao <li...@xiaomi.com>
AuthorDate: Thu Sep 12 17:08:42 2024 +0800

    coresight: add document for coresight
    
    Signed-off-by: liaoao <li...@xiaomi.com>
---
 Documentation/guides/coresight.rst | 78 ++++++++++++++++++++++++++++++++++++++
 Documentation/guides/index.rst     |  1 +
 2 files changed, 79 insertions(+)

diff --git a/Documentation/guides/coresight.rst b/Documentation/guides/coresight.rst
new file mode 100644
index 0000000000..66899fee31
--- /dev/null
+++ b/Documentation/guides/coresight.rst
@@ -0,0 +1,78 @@
+======================================
+Coresight - HW Assisted Tracing on ARM
+======================================
+
+Overview
+--------
+
+Coresight is an umbrella of technologies allowing for the debugging of ARM
+based SoC.  It includes solutions for JTAG and HW assisted tracing.  This
+document is concerned with the latter.
+
+HW assisted tracing is becoming increasingly useful when dealing with systems
+that have many SoCs and other components like GPU and DMA engines. Developers
+can monitor the behavior of their software as it runs on the device, view
+real-time data about its execution, and identify and debug issues quickly.
+
+Coresight omponents are generally categorised as source, link and sinks.
+The source devices generats a compressed stream representing the processor
+instruction path based on tracing scenarios. The link devices are responsible
+for transferring the stream from the source device to the sink device. The sink
+devices serve as as endpoints to the coresight implementation, either storing
+the compressed stream in a memory buffer or creating an interface to the
+outside world where data can be transferred to a host without fear of filling
+up the onboard coresight memory buffer.
+
+refer to the following document for more details:
+https://developer.arm.com/documentation/102520/latest/
+
+
+Acronyms and Classification
+---------------------------
+
+Acronyms:
+
+PTM:
+    Program Trace Macrocell
+ETM:
+    Embedded Trace Macrocell
+STM:
+    System trace Macrocell
+ETB:
+    Embedded Trace Buffer
+ITM:
+    Instrumentation Trace Macrocell
+TPIU:
+     Trace Port Interface Unit
+TMC-ETR:
+        Trace Memory Controller, configured as Embedded Trace Router
+TMC-ETF:
+        Trace Memory Controller, configured as Embedded Trace FIFO
+
+Classification:
+
+Source:
+   ETM, STM, ITM
+Link:
+   Funnel, replicator, TMC-ETF
+Sinks:
+   ETB, TPIU, TMC-ETR
+
+Framework and implementation
+----------------------------
+
+The coresight framework provides a central point to represent, configure and
+manage coresight devices on a platform.  Any coresight compliant device can
+register with the framework for as long as they use the right APIs:
+
+.. c:function:: int coresight_register(FAR struct coresight_dev_s *csdev, FAR const struct coresight_desc_s *desc);
+.. c:function:: void coresight_unregister(FAR struct coresight_dev_s *csdev);
+
+``struct coresight_desc *desc`` describes the type of current coresight device
+and where it connects to. When all the coresight devices are registered,
+devices throught the tracing stream path can be enablea by calling:
+
+.. c:function:: int coresight_enable(FAR struct coresight_dev_s *srcdev, FAR struct coresight_dev_s *destdev);
+
+The ``coresight_enable`` function will build the path through srcdev and
+destdev according the ``struct coresight_desc *desc``.
diff --git a/Documentation/guides/index.rst b/Documentation/guides/index.rst
index c25644a14e..11e43cc421 100644
--- a/Documentation/guides/index.rst
+++ b/Documentation/guides/index.rst
@@ -22,6 +22,7 @@ Guides
   nestedinterrupts.rst
   cortexmhardfaults.rst
   coredump.rst
+  coresight.rst
   gdbserver.rst
   gdbwithpython.rst
   ofloader.rst