[PATCH] core: net: document udp-demo server client

Also document broadcast mode and fix mistakes
---
 content/core/net/udp-demo.md | 123 ++++++++++++++++++++++++++++++++---
 1 file changed, 114 insertions(+), 9 deletions(-)

diff --git a/content/core/net/udp-demo.md b/content/core/net/udp-demo.md
index 2b7807f..3f4aa9c 100644
--- a/content/core/net/udp-demo.md
+++ b/content/core/net/udp-demo.md
@@ -21,7 +21,8 @@ is out-of-band capable.
 The general usage of this demo is as follows:
 
 ```
-oob-net-udp -a <IP-address> [-p <port>][-m <text>][-n <msgcount>][-i <iterations>][-d][-s][-R|-S]
+oob-net-udp -a <IP-address> [-p <port>][-m <text>][-n <msgcount>][-i <iterations>]
+  [-w <wait-time-us>][-d][-s][-b][-T|-R|-C|-S]
 ```
 
 where:
@@ -40,16 +41,27 @@ where:
   
 - -i<iterations> defines the number of datagrams which should be sent
   or received.
-  
+
+- -w<wait-time-us> is the time in us before a new package is sent. This is valid
+  for _transmitter_ / _client_. (defaults to 1000000)
+
 - -d raises the verbosity of the demo to debug mode, such as
   displaying the content of the packets received.
   
 - -s tames down the verbosity of the demo to silent mode, no output
   will be produced in this mode.
+
+- -b enables broadcast mode. This is only valid for _transmitter_.
   
 - -R switches the demo to _receiver_ mode.
 
-- -S switches the demo to _sender_ mode.
+- -T switches the demo to _transmitter_ mode.
+
+- -S switches the demo to _server_ mode. This mode receives a packet from a client and
+  immediately sends a response to the address / port where the package was received from.
+
+- -C switches the demo to _client_ mode. This mode sends a packet to a server and waits
+  for a response. The round trip time is measured.
 
 You need to set up a basic out-of-band network as described by this
 [document]({{% relref "core/net/setup#evl-net-setup-vlan" %}}). For
@@ -69,24 +81,29 @@ peers [set up for out-of-band communications]({{% relref
   network device with a IPv4 address set to 10.10.10.10
 ```
 ~# /usr/bin/oob-net-udp -a 10.10.10.10 -R
-== sender mode (=> 127.0.0.1:42042)
+== receiver mode (<= 10.10.10.10:42042)
+bind--------
+IP-Address: 10.10.10.10
+Port:       42042
+Family:     2
 = 14 bytes received: Mellow sword!
 = 14 bytes received: Mellow sword!
 = 14 bytes received: Mellow sword!
 ```
 
-## Running the UDP sender {#evl-net-udp-sender}
+## Running the UDP transmitter (sender) {#evl-net-udp-sender}
 
-In its receiver form (`-S` switch is given), the UDP demo program
+In its transmitter form (`-T` switch is given), the UDP demo program
 emits datagrams to the specified address and port (42042 by default).
 
 > On the second host which has established an out-of-band port on some
   network device with a IPv4 address set to 10.10.10.11
 ```
-~# /usr/bin/oob-net-udp -a 10.10.10.10 -S
+~# /usr/bin/oob-net-udp -a 10.10.10.11 -T
+== sender mode (=> 10.10.10.11:42042)
 ```
 
-## Running the demo in loopback mode
+## Running the transmit / receive demo in loopback mode
 
 As mentioned earlier, you can run this simple demo on the loopback
 device of a single machine, as follows:
@@ -96,7 +113,10 @@ device of a single machine, as follows:
 ~# oob-net-udp -R -a 127.0.0.1&
 [1] 516
 == receiver mode (<= 127.0.0.1:42042)
-== bound to port 42042
+bind--------
+IP-Address: 127.0.0.1
+Port:       42042
+Family:     2
 
 ~# oob-net-udp -S -a 127.0.0.1 
 == sender mode (=> 127.0.0.1:42042)
@@ -107,6 +127,91 @@ device of a single machine, as follows:
 = 14 bytes received: Mellow sword!
 ...
 ```
+
+## Running the UDP server {#evl-net-udp-server}
+
+In its server form (`-S` switch is given), the UDP demo program
+waits for datagram on the specified address / port and immediately sends
+an answer to the the address / port where the package was received from.
+Say we have two peers [set up for out-of-band communications]({{% relref
+"core/net/setup" %}}):
+
+> On the first host which has established an out-of-band port on some
+  network device with a IPv4 address set to 10.10.10.10
+```
+~# /usr/bin/oob-net-udp -a 10.10.10.10 -S
+== server mode (<= 10.10.10.10:42042)
+bind--------
+IP-Address: 10.10.10.10
+Port:       42042
+Family:     2
+= 14 bytes received: Mellow sword!
+= 14 bytes received: Mellow sword!
+= 14 bytes received: Mellow sword!
+```
+
+## Running the UDP client {#evl-net-udp-client}
+
+In its client form (`-C` switch is given), the UDP demo program
+emits a datagram to the specified address and port (42042 by default).
+After the datagram is sent, it waits for a response and prints the round trip time.
+The call to connect automatically assigns a port where the client will receive the
+response.
+
+> On the second host which has established an out-of-band port on some
+  network device with a IPv4 address set to 10.10.10.11
+```
+~# /usr/bin/oob-net-udp -a 10.10.10.10 -C
+== client mode (<= 10.10.10.10:42042)
+send address--------
+IP-Address: 10.10.10.10
+Port:       42042
+Family:     2
+receive address--------
+IP-Address: 10.10.10.10
+Port:       42671
+Family:     2
+= 15 bytes received rtt=56.6us: Mellow sword!
+= 15 bytes received rtt=57.1us: Mellow sword!
+= 15 bytes received rtt=51.7us: Mellow sword!
+```
+
+## Running the server / client demo in loopback mode
+
+As mentioned earlier, you can run this simple demo on the loopback
+device of a single machine, as follows:
+
+```
+~# evl net -ei lo
+~# oob-net-udp -S -a 127.0.0.1 -m "I am the server" &
+[1] 516
+== server mode (<= 127.0.0.1:42042)
+bind--------
+IP-Address: 127.0.0.1
+Port:       42042
+Family:     2
+
+~# oob-net-udp -C -a 127.0.0.1 -m "I am the client"
+== client mode (<= 127.0.0.1:42042)
+send address--------
+IP-Address: 127.0.0.1
+Port:       42042
+Family:     2
+receive address--------
+IP-Address: 127.0.0.1
+Port:       37204
+Family:     2
+... (the server is now displaying the incoming frames)
+... (the client is also displaying the incoming frames and the round trip time rtt)
+... (the messages might be displayed out of order)
+= 16 bytes received: I am the client
+= 16 bytes received rtt=51.7us: I am the server
+= 16 bytes received: I am the client
+= 16 bytes received rtt=56.6us: I am the server
+= 16 bytes received: I am the client
+= 16 bytes received rtt=57.1us: I am the server
+...
+```
 ---
 
 {{<lastmodified>}}
-- 
2.47.3