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

Hannes Diethelm <[email protected]> writes:

> 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>}}

Merged, thanks.

-- 
Philippe.