doc: add some diagrams

jiceatscion · Jan 10, 2025 · 0788ea4 · 0788ea4
1 parent f49d3cd
commit 0788ea4
Show file tree

Hide file tree

Showing 5 changed files with 33 additions and 1 deletion.
diff --git a/doc/data-plane.rst b/doc/data-plane.rst
@@ -15,4 +15,5 @@ Data Plane
    protocols/authenticator-option
    protocols/bfd
    protocols/assigned-protocol-numbers
+   protocols/stack
 
diff --git a/doc/fig/overview-topology.excalidraw.png b/doc/fig/overview-topology.excalidraw.png
diff --git a/doc/overview.rst b/doc/overview.rst
@@ -98,6 +98,29 @@ There are three types of links between ASes in SCION:
 - A **peering link** also includes at least one non-core AS. The ASes may be in different ISDs.
   Peering links are only available for use by children (direct or indirect) of the two linked ASes.
 
+Topology summary
+^^^^^^^^^^^^^^^^
+
+The following diagram provides a visual summary of the topology of a SCION network.
+
+.. figure:: fig/overview-topology.excalidraw.png
+
+Core links (in bright red) connect core ASes, thereby providing inter-ISD connectivity. Intra ISD
+links (in green) connect ASes within an ISD. AS-internal networks (in blue) connect the various
+hosts within an AS (including border routers). Peering links (in purple) provide restricted use
+shortcuts between ISDs. The dark red dashed arrows show examples of possible paths through the
+network.
+
+This diagram attempts to illustrate the variety of valid configurations. For example, notice that:
+
+- There may be multiple core ASes per ISD.
+- There may be multiple connections between a non-core AS and its core-ASes.
+- There may be multiple border routers per AS.
+- There may be any number of end-hosts (includng none) in an AS.
+- Border routers need not be dedicated to one particular kind of links.
+- Excludig core links, the ASes within an ISD form a directed acyclic graph (no other constraint).
+- The core ASes themselves form an arbitrary graph.
+
 Routing
 ^^^^^^^
 
@@ -123,7 +146,6 @@ The process of creating an end-to-end forwarding path consists of the following
 
 .. figure:: fig/overview-routing.excalidraw.png
 
-
 .. seealso::
 
    :doc:`control-plane`

diff --git a/doc/protocols/fig/stack.excalidraw.png b/doc/protocols/fig/stack.excalidraw.png
diff --git a/doc/protocols/stack.rst b/doc/protocols/stack.rst
@@ -0,0 +1,9 @@
+********************
+SCION Protocol Stack
+********************
+
+.. _stack:
+
+This document provides a visual summary of the SCION overall protocol stack.
+
+.. figure:: fig/stack.excalidraw.png