Merge pull request #18398 from benpicco/gnrc_ipv6_auto_subnets-doc

gnrc/ipv6_auto_subnets: improve documentation about subnet generation and RIO

dist/tools/whitespacecheck/ignore_list.txt

@@ -1,2 +1,3 @@
 */vendor/*
 dist/tools/fixdep/fixdep.c
+*.svg

doc/doxygen/src/gnrc_ipv6_auto_subnets-with_rio.puml

@@ -0,0 +1,32 @@
+' to generate SVG run plantuml -tsvg gnrc_ipv6_auto_subnets-with_rio.puml
+
+@startuml
+
+skinparam responseMessageBelowArrow true
+
+participant "2001:db8:0:0:<color:#9a9a9a>c8f4:13ff:fece:3f43\n2001:db8:0:8:<color:#9a9a9a>3c27:6dff:fe25:e95d" as A << (A,#ADD1B2) >>
+participant "2001:db8:0:0:<color:#9a9a9a>a7a2:12e0:48bc:7487" as B << (B,#ADD1B2) >>
+participant "2001:db8:0:8:<color:#9a9a9a>5075:35ff:fefa:30bc" as C << (C,#ADD1B2) >>
+
+A -> C: RA: I'm a default router, PIO: You can use 2001:db8:0:8::/61 **[broadcast]**
+A -> B: RA: I'm <i>not</i> a default router (ltime = 0), RIO: You can reach 2001:db8:0:8::/61 through me  **[broadcast]**
+group C sends request to B
+C -> A: forward PING request to 2001:db8:0:0:<color:#9a9a9a>a7a2:12e0:48bc:7487
+note right
+destination of off-link
+use default router to forward it
+end note
+A --> B: NS: Who has 2001:db8:0:0:<color:#9a9a9a>a7a2:12e0:48bc:7487</color>?  **[broadcast]**
+B -> A: NA: Me!
+A -> B: PING request from 2001:db8:0:8:<color:#9a9a9a>5075:35ff:fefa:30bc
+end
+group B sends reply to C
+B -> A: forward PING response to 2001:db8:0:8:<color:#9a9a9a>5075:35ff:fefa:30bc
+note right
+destination is in 2001:db8::/60
+but 2001:db8:0:8::/61 is a stronger match
+end note
+A -> C: PING response from 2001:db8:0:0:<color:#9a9a9a>a7a2:12e0:48bc:7487</color>
+
+end
+@enduml

doc/doxygen/src/gnrc_ipv6_auto_subnets-without_rio.puml

@@ -0,0 +1,29 @@
+' to generate SVG run plantuml -tsvg gnrc_ipv6_auto_subnets-without_rio.puml
+
+@startuml
+
+skinparam responseMessageBelowArrow true
+
+participant "2001:db8:0:0:<color:#9a9a9a>c8f4:13ff:fece:3f43\n2001:db8:0:8:<color:#9a9a9a>3c27:6dff:fe25:e95d" as A << (A,#ADD1B2) >>
+participant "2001:db8:0:0:<color:#9a9a9a>a7a2:12e0:48bc:7487" as B << (B,#ADD1B2) >>
+participant "2001:db8:0:8:<color:#9a9a9a>5075:35ff:fefa:30bc" as C << (C,#ADD1B2) >>
+
+A -> C: RA: I'm a default router, PIO: You can use 2001:db8:0:8::/61 **[broadcast]**
+group C sends request to B
+C -> A: forward PING request to 2001:db8:0:0:<color:#9a9a9a>a7a2:12e0:48bc:7487
+note right
+destination of off-link
+use default router to forward it
+end note
+A --> B: NS: Who has 2001:db8:0:0:<color:#9a9a9a>a7a2:12e0:48bc:7487</color>?  **[broadcast]**
+B -> A: NA: Me!
+A -> B: PING request from 2001:db8:0:8:<color:#9a9a9a>5075:35ff:fefa:30bc
+end
+group B sends reply to C
+B -->x A: NS: Who has 2001:db8:0:8:<color:#9a9a9a>5075:35ff:fefa:30bc</color>? **[broadcast]**
+note right
+destination is in the same subnet, so it must be on-link.
+Send NS to resolve address.
+end note
+end
+@enduml

doc/doxygen/src/gnrc_ipv6_auto_subnets_simple.puml

@@ -24,22 +24,25 @@ nwdiagDiagram {
 
 nwdiag {
 
-	network level1 {
+	network level0 {
 		address = "2001:db8::/60";
+		description = "level 0: <color:#9a9a9a>0000</color>";
 
 		router_a [address = "2001:db8::<color:#8a8a8a>c8f4:13ff:fece:3f43", description = "1st level router"];
 		leaf_a   [address = "2001:db8::<color:#8a8a8a>804b:fcff:feb6:43fb", description = "1st level leaf node"];
 	}
 
-	network level2 {
+	network level1 {
 		address = "2001:db8:0:8::/61";
+		description = "level 1: <b><i>1</i></b><color:#9a9a9a>000</color> ➜ 8";
 
 		router_a [address = "2001:db8:0:8:<color:#8a8a8a>3c27:6dff:fe25:e95d"];
 		router_b [address = "2001:db8:0:8:<color:#8a8a8a>5075:35ff:fefa:30bc", description = "2nd level router"];
 	}
 
-	network level3 {
+	network level2 {
 		address = "2001:db8:0:c::/62";
+		description = "level 2: <color:#9a9a9a>1</color><b><i>1</i></b><color:#9a9a9a>00</color> ➜ c";
 
 		router_b [address = "2001:db8:0:c:<color:#8a8a8a>2ca3:9eff:fea9:68f7"];
 		router_c [address = "2001:db8:0:c:<color:#8a8a8a>fc33:13ff:fe93:5ae4", description = "3rd level router"];
@@ -47,11 +50,20 @@ nwdiag {
 		leaf_b2  [address = "2001:db8:0:c:<color:#8a8a8a>5491:a2ff:fe98:61a2", description = "3rd level leaf node"];
 	}
 
-	network level4 {
-		address = "2001:db8:0:e::/63";
+	network level3_1 {
+		address = "2001:db8:0:d::/64";
+		description = "level 3.1: <color:#9a9a9a>11</color><b><i>01</i></b> ➜ d";
 
-		router_c [address = "2001:db8:0:e:<color:#8a8a8a>a8d9:e1ff:feab:d544"];
-		leaf_c   [address = "2001:db8:0:e:<color:#8a8a8a>1cf5:33ff:fe7c:c70c", description = "4th level leaf node"];
+		router_c [address = "2001:db8:0:d:<color:#8a8a8a>a8d9:e1ff:feab:d544"];
+		leaf_d   [address = "2001:db8:0:d:<color:#8a8a8a>1cf5:33ff:fe7c:c70c", description = "4th level leaf node"];
+	}
+
+	network level3_2 {
+		address = "2001:db8:0:e::/64";
+		description = "level 3.2: <color:#9a9a9a>11</color><b><i>10</i></b> ➜ e";
+
+		router_c [address = "2001:db8:0:e:<color:#8a8a8a>3495:ee42:11ef:dc86"];
+		leaf_e   [address = "2001:db8:0:e:<color:#8a8a8a>6dcf:6e6f:6a25:25c4", description = "4th level leaf node"];
 	}
 }
 @enduml

sys/net/gnrc/routing/ipv6_auto_subnets/gnrc_ipv6_auto_subnets.c

@@ -22,9 +22,10 @@
  * subnets from it by dividing it into sub-prefixes for each downstream interface.
  *
  * When using the `gnrc_ipv6_auto_subnets_simple` module, there can only be a single
- * routing node on each level of the network but an arbitrary number of leaf nodes.
+ * routing node on each level of the network but an arbitrary number of leaf nodes and
+ * downstream interfaces.
  *
- * !['Skinny Tree' Example Topology](gnrc_ipv6_auto_subnets_simple.svg)
+ * ![Example Topology with only one router on each level](gnrc_ipv6_auto_subnets_simple.svg)
  *
  * If there are multiple routing nodes on the same link, coordination between the
  * routers is required.
@@ -36,7 +37,7 @@
  * The layer 2 address of the sender then determines the order in which the prefixes
  * are assigned.
  *
- * ![Example Topology](gnrc_ipv6_auto_subnets.svg)
+ * ![Example Topology with multiple routers](gnrc_ipv6_auto_subnets.svg)
  *
  * The downstream network(s) receive the sub-prefix via Router Advertisements
  * and the process repeats until the bits of the prefix are exhausted.
@@ -50,6 +51,30 @@
  * so that upstream routers will no longer consider hosts in this subnet on-link,
  * but instead will use the downstream router to route to the new subnet.
  *
+ * The need for a Route Information Option
+ * ---------------------------------------
+ *
+ * All nodes that want to communicate with hosts in a downstream subnet must implement
+ * parsing of the Route Information Option. For routing RIOT nodes this is enabled by
+ * default, non-routing nodes need to enable the `gnrc_ipv6_nib_rio` module.
+ *
+ * This is because all addresses in the subnet are also within the original network, so
+ * without further information hosts would consider those addresses on-link and perform
+ * neighbor solicitation to communicate with them.
+ *
+ * E.g. if host Ⓒ  (`2001:db8:0:8:5075:35ff:fefa:30bc`) sends an ICMPv6 Echo request to
+ * Ⓑ  (`2001:db8:0:0:a7a2:12e0:48bc:7487`), it would not get a response:
+ *
+ * ![Auto-Subnets without RIO](gnrc_ipv6_auto_subnets-without_rio.svg)
+ *
+ * To solve this, the routing node Ⓐ  also sends a Router Advertisement to the <i>upstream</i>
+ * network that only contains a Route Information Option for each downstream network created
+ * by that router.
+ * This way hosts in the upstream network will prefer the route via Ⓐ  over link-local
+ * transmission as it is a stronger match than the upstream prefix:
+ *
+ * ![Auto-Subnets with RIO](gnrc_ipv6_auto_subnets-with_rio.svg)
+ *
  * Usage
  * =====
  *