libmemif: docs md->rst

Type: improvement

Change-Id: Ibebd2d47a4268189f11601d004073e4858548f25
Signed-off-by: Nathan Skrzypczak <nathan.skrzypczak@gmail.com>

4 files changed, 290 insertions, 225 deletions

diff --git a/extras/libmemif/examples/example_setup_doc.md b/extras/libmemif/examples/example_setup_doc.md
deleted file mode 100644
index 136477ddebb..00000000000
--- a/extras/libmemif/examples/example_setup_doc.md
+++ /dev/null
@@ -1,207 +0,0 @@
-## Example setup    {#libmemif_example_setup_doc}
-
-#### VPP-memif master icmp_responder slave
-
-> Libmemif example app(s) use memif default socket file: `/run/vpp/memif.sock`.
-
-Run VPP and icmpr-epoll example (default example when running in container).
-
-> Other examples work similar to icmpr-epoll. Brief explanation can be found in @ref libmemif_examples_doc .
-
-VPP-side config:
-```
-DBGvpp# create interface memif id 0 master
-DBGvpp# set int state memif0/0 up
-DBGvpp# set int ip address memif0/0 192.168.1.1/24
-```
-icmpr-epoll:
-```
-conn 0 0
-```
-Memif in slave mode will try to connect every 2 seconds. If connection establishment is successful, a message will show.
-```
-INFO: memif connected!
-```
-> Error messages like "unmatched interface id" are printed only in debug mode.
-
-Check connected status.
-Use show command in icmpr-epoll:
-```
-show
-MEMIF DETAILS
-==============================
-interface index: 0
-	interface ip: 192.168.1.2
-	interface name: memif_connection
-	app name: ICMP_Responder
-	remote interface name: memif0/0
-	remote app name: VPP 17.10-rc0~132-g62f9cdd
-	id: 0
-	secret: 
-	role: slave
-	mode: ethernet
-	socket filename: /run/vpp/memif.sock
-	rx queues:
-		queue id: 0
-		ring size: 1024
-		buffer size: 2048
-	tx queues:
-		queue id: 0
-		ring size: 1024
-		buffer size: 2048
-	link: up
-interface index: 1
-	no connection
-
-```
-Use sh memif command in VPP:
-```
-DBGvpp# sh memif
-interface memif0/0
-  remote-name "ICMP_Responder"
-  remote-interface "memif_connection"
-  id 0 mode ethernet file /run/vpp/memif.sock
-  flags admin-up connected
-  listener-fd 12 conn-fd 13
-  num-s2m-rings 1 num-m2s-rings 1 buffer-size 0
-    master-to-slave ring 0:
-      region 0 offset 32896 ring-size 1024 int-fd 16
-      head 0 tail 0 flags 0x0000 interrupts 0
-    master-to-slave ring 0:
-      region 0 offset 0 ring-size 1024 int-fd 15
-      head 0 tail 0 flags 0x0001 interrupts 0
-```
-
-Send ping from VPP to icmpr-epoll:
-```
-DBGvpp# ping 192.168.1.2
-64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=.1888 ms
-64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=.1985 ms
-64 bytes from 192.168.1.2: icmp_seq=4 ttl=64 time=.1813 ms
-64 bytes from 192.168.1.2: icmp_seq=5 ttl=64 time=.1929 ms
-
-Statistics: 5 sent, 4 received, 20% packet loss
-```
-#### multiple queues VPP-memif slave icmp_responder master
-
-Run icmpr-epoll as in previous example setup.
-Run VPP with startup conf, enabling 2 worker threads.
-Example startup.conf:
-```
-unix {
-  interactive
-  nodaemon
-  full-coredump
-}
-
-cpu {
-  workers 2
-}
-```
-VPP-side config:
-```
-DBGvpp# create memif id 0 slave rx-queues 2 tx-queues 2
-DBGvpp# set int state memif0/0 up
-DBGvpp# set int ip address memif0/0 192.168.1.1/24
-```
-icmpr-epoll:
-```
-conn 0 1
-```
-When connection is established a message will print:
-```
-INFO: memif connected!
-```
-> Error messages like "unmatched interface id" are printed only in debug mode.
-
-Check connected status.
-Use show command in icmpr-epoll:
-```
-show
-MEMIF DETAILS
-==============================
-interface index: 0
-	interface ip: 192.168.1.2
-	interface name: memif_connection
-	app name: ICMP_Responder
-	remote interface name: memif0/0
-	remote app name: VPP 17.10-rc0~132-g62f9cdd
-	id: 0
-	secret: 
-	role: master
-	mode: ethernet
-	socket filename: /run/vpp/memif.sock
-	rx queues:
-		queue id: 0
-		ring size: 1024
-		buffer size: 2048
-		queue id: 1
-		ring size: 1024
-		buffer size: 2048
-	tx queues:
-		queue id: 0
-		ring size: 1024
-		buffer size: 2048
-		queue id: 1
-		ring size: 1024
-		buffer size: 2048
-	link: up
-interface index: 1
-	no connection
-
-```
-Use sh memif command in VPP:
-```
-DBGvpp# sh memif
-interface memif0/0
-  remote-name "ICMP_Responder"
-  remote-interface "memif_connection"
-  id 0 mode ethernet file /run/vpp/memif.sock
-  flags admin-up slave connected
-  listener-fd -1 conn-fd 12
-  num-s2m-rings 2 num-m2s-rings 2 buffer-size 2048
-    slave-to-master ring 0:
-      region 0 offset 0 ring-size 1024 int-fd 14
-      head 0 tail 0 flags 0x0000 interrupts 0
-    slave-to-master ring 1:
-      region 0 offset 32896 ring-size 1024 int-fd 15
-      head 0 tail 0 flags 0x0000 interrupts 0
-    slave-to-master ring 0:
-      region 0 offset 65792 ring-size 1024 int-fd 16
-      head 0 tail 0 flags 0x0001 interrupts 0
-    slave-to-master ring 1:
-      region 0 offset 98688 ring-size 1024 int-fd 17
-      head 0 tail 0 flags 0x0001 interrupts 0
-
-```
-Send ping from VPP to icmpr-epoll:
-```
-DBGvpp# ping 192.168.1.2
-64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=.1439 ms
-64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=.2184 ms
-64 bytes from 192.168.1.2: icmp_seq=4 ttl=64 time=.1458 ms
-64 bytes from 192.168.1.2: icmp_seq=5 ttl=64 time=.1687 ms
-
-Statistics: 5 sent, 4 received, 20% packet loss
-```
-
-#### icmp_responder master icmp_responder slave
-
-> This setup creates connection between two applications using libmemif. Traffic functionality is the same as when connection to VPP. App can receive ARP/ICMP request and transmit response.
-
-Run two instances of icmpr-epoll example.
-> If not running in container, make sure folder /run/vpp/ exists before creating memif master.
-Instance 1 will be in master mode, instance 2 in slave mode.
-instance 1:
-```
-conn 0 1
-```
-instance 2:
-```
-conn 0 0
-```
-In 2 seconds, both instances should print connected! message:
-```
-INFO: memif connected!
-```
-Check peer interface names using show command.
diff --git a/extras/libmemif/examples/example_setup_doc.rst b/extras/libmemif/examples/example_setup_doc.rst
new file mode 100644
index 00000000000..76ce78dab72
--- /dev/null
+++ b/extras/libmemif/examples/example_setup_doc.rst
@@ -0,0 +1,248 @@
+.. _libmemif_example_setup_doc:
+
+Example setup
+=============
+
+VPP-memif master icmp_responder slave
+-------------------------------------
+
+   Libmemif example app(s) use memif default socket file:
+   ``/run/vpp/memif.sock``.
+
+Run VPP and icmpr-epoll example (default example when running in
+container).
+
+   Other examples work similar to icmpr-epoll. Brief explanation can be
+   found in :ref:`libmemif_examples_doc` .
+
+VPP-side config:
+
+::
+
+   DBGvpp# create interface memif id 0 master
+   DBGvpp# set int state memif0/0 up
+   DBGvpp# set int ip address memif0/0 192.168.1.1/24
+
+icmpr-epoll:
+
+::
+
+   conn 0 0
+
+Memif in slave mode will try to connect every 2 seconds. If connection
+establishment is successful, a message will show.
+
+::
+
+   INFO: memif connected!
+
+..
+
+   Error messages like “unmatched interface id” are printed only in
+   debug mode.
+
+Check connected status. Use show command in icmpr-epoll:
+
+::
+
+   show
+   MEMIF DETAILS
+   ==============================
+   interface index: 0
+       interface ip: 192.168.1.2
+       interface name: memif_connection
+       app name: ICMP_Responder
+       remote interface name: memif0/0
+       remote app name: VPP 17.10-rc0~132-g62f9cdd
+       id: 0
+       secret:
+       role: slave
+       mode: ethernet
+       socket filename: /run/vpp/memif.sock
+       rx queues:
+           queue id: 0
+           ring size: 1024
+           buffer size: 2048
+       tx queues:
+           queue id: 0
+           ring size: 1024
+           buffer size: 2048
+       link: up
+   interface index: 1
+       no connection
+
+Use sh memif command in VPP:
+
+::
+
+   DBGvpp# sh memif
+   interface memif0/0
+     remote-name "ICMP_Responder"
+     remote-interface "memif_connection"
+     id 0 mode ethernet file /run/vpp/memif.sock
+     flags admin-up connected
+     listener-fd 12 conn-fd 13
+     num-s2m-rings 1 num-m2s-rings 1 buffer-size 0
+       master-to-slave ring 0:
+         region 0 offset 32896 ring-size 1024 int-fd 16
+         head 0 tail 0 flags 0x0000 interrupts 0
+       master-to-slave ring 0:
+         region 0 offset 0 ring-size 1024 int-fd 15
+         head 0 tail 0 flags 0x0001 interrupts 0
+
+Send ping from VPP to icmpr-epoll:
+
+::
+
+   DBGvpp# ping 192.168.1.2
+   64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=.1888 ms
+   64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=.1985 ms
+   64 bytes from 192.168.1.2: icmp_seq=4 ttl=64 time=.1813 ms
+   64 bytes from 192.168.1.2: icmp_seq=5 ttl=64 time=.1929 ms
+
+   Statistics: 5 sent, 4 received, 20% packet loss
+
+multiple queues VPP-memif slave icmp_responder master
+-----------------------------------------------------
+
+Run icmpr-epoll as in previous example setup. Run VPP with startup conf,
+enabling 2 worker threads. Example startup.conf:
+
+::
+
+   unix {
+     interactive
+     nodaemon
+     full-coredump
+   }
+
+   cpu {
+     workers 2
+   }
+
+VPP-side config:
+
+::
+
+   DBGvpp# create memif id 0 slave rx-queues 2 tx-queues 2
+   DBGvpp# set int state memif0/0 up
+   DBGvpp# set int ip address memif0/0 192.168.1.1/24
+
+icmpr-epoll:
+
+::
+
+   conn 0 1
+
+When connection is established a message will print:
+
+::
+
+   INFO: memif connected!
+
+..
+
+   Error messages like “unmatched interface id” are printed only in
+   debug mode.
+
+Check connected status. Use show command in icmpr-epoll:
+
+::
+
+   show
+   MEMIF DETAILS
+   ==============================
+   interface index: 0
+       interface ip: 192.168.1.2
+       interface name: memif_connection
+       app name: ICMP_Responder
+       remote interface name: memif0/0
+       remote app name: VPP 17.10-rc0~132-g62f9cdd
+       id: 0
+       secret:
+       role: master
+       mode: ethernet
+       socket filename: /run/vpp/memif.sock
+       rx queues:
+           queue id: 0
+           ring size: 1024
+           buffer size: 2048
+           queue id: 1
+           ring size: 1024
+           buffer size: 2048
+       tx queues:
+           queue id: 0
+           ring size: 1024
+           buffer size: 2048
+           queue id: 1
+           ring size: 1024
+           buffer size: 2048
+       link: up
+   interface index: 1
+       no connection
+
+Use sh memif command in VPP:
+
+::
+
+   DBGvpp# sh memif
+   interface memif0/0
+     remote-name "ICMP_Responder"
+     remote-interface "memif_connection"
+     id 0 mode ethernet file /run/vpp/memif.sock
+     flags admin-up slave connected
+     listener-fd -1 conn-fd 12
+     num-s2m-rings 2 num-m2s-rings 2 buffer-size 2048
+       slave-to-master ring 0:
+         region 0 offset 0 ring-size 1024 int-fd 14
+         head 0 tail 0 flags 0x0000 interrupts 0
+       slave-to-master ring 1:
+         region 0 offset 32896 ring-size 1024 int-fd 15
+         head 0 tail 0 flags 0x0000 interrupts 0
+       slave-to-master ring 0:
+         region 0 offset 65792 ring-size 1024 int-fd 16
+         head 0 tail 0 flags 0x0001 interrupts 0
+       slave-to-master ring 1:
+         region 0 offset 98688 ring-size 1024 int-fd 17
+         head 0 tail 0 flags 0x0001 interrupts 0
+
+Send ping from VPP to icmpr-epoll:
+
+::
+
+   DBGvpp# ping 192.168.1.2
+   64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=.1439 ms
+   64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=.2184 ms
+   64 bytes from 192.168.1.2: icmp_seq=4 ttl=64 time=.1458 ms
+   64 bytes from 192.168.1.2: icmp_seq=5 ttl=64 time=.1687 ms
+
+   Statistics: 5 sent, 4 received, 20% packet loss
+
+icmp_responder master icmp_responder slave
+------------------------------------------
+
+   This setup creates connection between two applications using
+   libmemif. Traffic functionality is the same as when connection to
+   VPP. App can receive ARP/ICMP request and transmit response.
+
+Run two instances of icmpr-epoll example. > If not running in container,
+make sure folder /run/vpp/ exists before creating memif master. Instance
+1 will be in master mode, instance 2 in slave mode. instance 1:
+
+::
+
+   conn 0 1
+
+instance 2:
+
+::
+
+   conn 0 0
+
+In 2 seconds, both instances should print connected! message:
+
+::
+
+   INFO: memif connected!
+
+Check peer interface names using show command.
diff --git a/extras/libmemif/examples/examples_doc.md b/extras/libmemif/examples/examples_doc.md
deleted file mode 100644
index 4422d42d44b..00000000000
--- a/extras/libmemif/examples/examples_doc.md
+++ /dev/null
@@ -1,18 +0,0 @@
-## Examples    {#libmemif_examples_doc}
-
-After build, root folder will contain scripts linking binary examples with library (same name as example apps). These scripts can be executed to run example apps without installing the library. Example apps binaries can be found in _libs_ filder. To run binaries directly, make sure that libmemif library is installed.
-
-#### Run in container
-
-`ligato/libmemif-sample-service` image contains built and installed libmemf. To run different examples, override docker CMD to start container in bash:
-
-```
-# docker run -it --entrypoint=/bin/bash -i --rm --name icmp-responder --hostname icmp-responder --privileged -v "/run/vpp/:/run/vpp/" ligato/libmemif-sample-service
-```
-Current WORKDIR is set to root repository directory. Example apps can be run from this directory (a script linking binary with library), or browse to `./.libs` folder and execute binary directly.
-
-Example app | Description
-------------|------------
-@ref extras/libmemif/examples/icmp_responder | Simplest implementation. Event polling is handled by libmemif. Single memif connection in slave mode is created (id 0). Use Ctrl + C to exit app. Memif receive mode: interrupt.
-@ref extras/libmemif/examples/icmp_responder-epoll (run in container by default) | Supports multiple connections and master mode. User can create/delete connections, set ip addresses, print connection information. @ref libmemif_example_setup_doc contains instructions on basic connection use cases setups. Memif receive mode: interrupt. App provides functionality to disable interrupts for specified queue/s for testing purposes. Polling mode is not implemented in this example.
-@ref extras/libmemif/examples/icmp_responder-mt) | Multi-thread example, very similar to icmpr-epoll. Packets are handled in threads assigned to specific queues. Slave mode only. Memif receive mode: polling (memif_rx_poll function), interrupt (memif_rx_interrupt function). Receive modes differ per queue.
diff --git a/extras/libmemif/examples/examples_doc.rst b/extras/libmemif/examples/examples_doc.rst
new file mode 100644
index 00000000000..3fb8c3127f8
--- /dev/null
+++ b/extras/libmemif/examples/examples_doc.rst
@@ -0,0 +1,42 @@
+.. _libmemif_examples_doc:
+
+Examples
+========
+
+After build, root folder will contain scripts linking binary examples
+with library (same name as example apps). These scripts can be executed
+to run example apps without installing the library. Example apps
+binaries can be found in *libs* folder. To run binaries directly, make
+sure that libmemif library is installed.
+
+Run in container
+----------------
+
+``ligato/libmemif-sample-service`` image contains built and installed
+libmemf. To run different examples, override docker CMD to start
+container in bash:
+
+::
+
+   # docker run -it --entrypoint=/bin/bash -i --rm --name icmp-responder --hostname icmp-responder --privileged -v "/run/vpp/:/run/vpp/" ligato/libmemif-sample-service
+
+Current WORKDIR is set to root repository directory. Example apps can be
+run from this directory (a script linking binary with library), or
+browse to ``./.libs`` folder and execute binary directly.
+
+* ``extras/libmemif/examples/icmp_responder``
+
+Simplest implementation. Event polling is handled by libmemif.
+Single memif connection in slave mode is created (id 0). Use Ctrl + C to exit app.
+Memif receive mode: interrupt.
+
+* ``extras/libmemif/examples/icmp_responder-epoll``  (run in container by default)
+
+Supports multiple connections and master mode. User can create/delete connections, set ip addresses,
+print connection information. :ref:`libmemif_example_setup_doc` contains instructions on basic
+connection use cases setups. Memif receive mode: interrupt. App provides functionality to disable
+interrupts for specified queue/s for testing purposes. Polling mode is not implemented in this example.
+
+* ``extras/libmemif/examples/icmp_responder-mt``
+
+Multi-thread example, very similar to icmpr-epoll. Packets are handled in threads assigned to specific queues. Slave mode only. Memif receive mode: polling (memif_rx_poll function), interrupt (memif_rx_interrupt function). Receive modes differ per queue.