gnrc/ipv6_auto_subnets: document the role of the RIO

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

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

@@ -51,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
  * =====
  *