Documentation updates

mubes · mubes · commit cfe1da3ce15f · 2021-05-04T23:56:40.000+01:00
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -28,6 +28,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinxcontrib.mermaid'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/docs/source/users/conops.rst b/docs/source/users/conops.rst
@@ -3,24 +3,42 @@ Purpose
 
 Orbtrace performs two essential functions, with a number of other supporting bits and pieces around the edges. Specifically it;
 
-1. Presents a *Debug Interface* to which CMSIS-DAP v1 or v2 compliant interface software can attach, to control and debug the target device over either a SWD or JTAG interface.
-2. Collects data from the *Parallel Trace Port* of the target device over a 1, 2 or 4 bit parallel interface and presents it to software on the host PC. These data can be used for reporting on the progress of the software running on the target device, and also reconstruct it's recent actions.
+1. Presents a *Debug Interface* to which CMSIS-DAP v1 or v2 compliant interface software can attach, to control and debug a target device over either a SWD or JTAG interface.
+2. Collects data from the *Parallel Trace Port* of the target device over a 1, 2 or 4 bit interface and presents it to software on the host PC. These data can be used for reporting on the progress of the software running on the target device, and optionally to reconstruct it's recent actions.
 
-In addition to the above, Orbtrace can also, depending on the hardware it's running on, provide power to the target and measure its current consumption during program execution, it can also provide secondary serial links to the target.  All of these data streams are carried over a single USB2-HS communnication link.
+In addition to the above, Orbtrace can also, depending on the hardware it's running on, provide power to the target and measure its current consumption during program execution. It can also provide secondary serial links.  All of these data streams are carried over a single USB2-HS communnication link between Orbtrace and the host PC.
 
-In respect of (1) above, typically software that would communicate with Orbtrace would be [BlackMagic Probe](https:https://github.com/blacksphere/blackmagic) or [PyOCD](https://github.com/pyocd/pyOCD). These would then connect to 
+The normal connection between Orbtrace and the target is the 2x10-way 0.05" connector you will see on the target PCB.  When doing debug only (i.e. no tracing functions) then the smaller 2x5-way 0.05" connector is typically used instead. Details on these connectors are available from the `Keil Website <https://www2.keil.com/coresight/coresight-connectors>`_.
 
+In respect of (1) above, typically software that would communicate with Orbtrace would be `BlackMagic Probe <https://github.com/blacksphere/blackmagic>`_ or `PyOCD <https://github.com/pyocd/pyOCD>`_. These would then connect to a debugger such as gdb.
 
 .. mermaid::
 
-    sequenceDiagram
-      participant Alice
-      participant Bob
-      Alice->John: Hello John, how are you?
-      loop Healthcheck
-          John->John: Fight against hypochondria
-      end
-      Note right of John: Rational thoughts <br/>prevail...
-      John-->Alice: Great!
-      John->Bob: How about you?
-      Bob-->John: Jolly good!
+    graph LR
+        A(Target) -- JTAG or SWD ---- B((Orbtrace))
+        A -- TRACE --> B((Orbtrace))
+        A -- Serial ---- B((Orbtrace))
+        B -- USB-HS ---- Z[Demux]
+        
+        subgraph Host PC
+            Z --- C(Debug Server) -- gdb remote protocol --- G(GDB)
+            Z --> D(Orbuculum)
+            Z --- H(Serial Server)
+            D -- Socket --> E(Orb Client 1)
+            D -- Socket --> F(Orb Client n)
+            H -- ACM --- I(Serial Client)
+        end
+
+        classDef green fill:#9f6,stroke:#333,stroke-width:2px;
+        classDef yellow fill:#ffff00,stroke:#333,stroke-width:2px;
+        classDef blue fill:#00f0ff,stroke:#333,stroke-width:2px;
+        classDef pink fill:#ffB0ff,stroke:#333,stroke-width:2px;
+        classDef brown fill:#bfb01f,stroke:#333,stroke-width:2px;
+        class A green
+        class B yellow
+        class C,G blue
+        class D,E,F pink
+        class H,I brown
+        
+
+In respect of (2) above, exploiting the trace flow from Orbtrace, the reader is directed to the `Orbuculum <https://github.com/orbcode/orbuculum>`_ suite for detailed information.

Original file line number	Diff line number	Diff line change
`@@ -28,6 +28,7 @@`
`28`	`28`	`# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom`
`29`	`29`	`# ones.`
`30`	`30`	`extensions = [`
	`31`	`+ 'sphinxcontrib.mermaid'`
`31`	`32`	`]`
`32`	`33`
`33`	`34`	`# Add any paths that contain templates here, relative to this directory.`