libmemif: refactor examples

- icmp_responder: responds to ICMPv4 and ARP requests
- loopback: connects two interfaces and sends a
  verification packet from master memif to slave memif
  where it is looped back
- loopback (reverse path): reverses direction of packet
  in loopback application (slave memif to master memif)

Type: refactor

Signed-off-by: Jakub Grajciar <jgrajcia@cisco.com>
Change-Id: Ie90aaa3367269408efb6c5d538ad5aa827432238
Signed-off-by: Dave Wallace <dwallacelf@gmail.com>

1 files changed, 73 insertions, 28 deletions

diff --git a/extras/libmemif/examples/examples_doc.rst b/extras/libmemif/examples/examples_doc.rst
index 3fb8c3127f8..64029773378 100644
--- a/extras/libmemif/examples/examples_doc.rst
+++ b/extras/libmemif/examples/examples_doc.rst
@@ -1,42 +1,87 @@
 .. _libmemif_examples_doc:
 
-Examples
-========
+Libmemif 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.
+Example source code is located in `.../vpp/extras/libmemif/examples/` directory.
+The compiled binaries are located in `.../vpp/extras/libmemif/build/examples/`.
 
-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:
+ICMP Responder
+--------------
+**Application Source Code**: `.../vpp/extras/libmemif/examples/icmp_responder`
 
-::
+In this example, memif endpoint connects to an external application. The example
+application can resolve ARP and reply to ICMPv4 packets. The program will exit
+once the interface is disconnected Memif receive mode: interrupt.
 
-   # docker run -it --entrypoint=/bin/bash -i --rm --name icmp-responder --hostname icmp-responder --privileged -v "/run/vpp/:/run/vpp/" ligato/libmemif-sample-service
+VPP (memif master) <--> icmp_responder app (memif slave)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+Start VPP and configure memif interface::
 
-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.
+    make run
+    ...
+    DBGvpp# create interface memif id 0 master
+    DBGvpp# set int state memif0/0 up
+    DBGvpp# set int ip address memif0/0 192.168.1.2/24
 
-* ``extras/libmemif/examples/icmp_responder``
+Start icmp_responder example app::
 
-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.
+    ./examples/icmp_responder
 
-* ``extras/libmemif/examples/icmp_responder-epoll``  (run in container by default)
+Memif in slave mode will try to connect every 2 seconds. If connection
+establishment is successful, the `memif connected` message will show::
 
-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.
+    INFO: memif connected!
 
-* ``extras/libmemif/examples/icmp_responder-mt``
+**Note**: Error messages like "unmatched interface id" are printed only in debug mode.
 
-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.
+Verify that the memif is connected on VPP side::
+
+    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 icmp_responder (Default IPv4: 192.168.1.1)::
+
+    DBGvpp# ping 192.168.1.1
+    64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=.1888 ms
+    64 bytes from 192.168.1.1: icmp_seq=3 ttl=64 time=.1985 ms
+    64 bytes from 192.168.1.1: icmp_seq=4 ttl=64 time=.1813 ms
+    64 bytes from 192.168.1.1: icmp_seq=5 ttl=64 time=.1929 ms
+
+    Statistics: 5 sent, 4 received, 20% packet loss
+
+
+Loopback
+--------
+**Application Source Code**: `.../vpp/extras/libmemif/examples/loopback`
+
+In this example, two memif endpoints are connected to create a loopback.
+Once connected, a test packet is sent out the memif master interface to
+the memif slave interface, which replies with the same packet in a
+zero-copy way.
+In reverse mode, the packet is sent from the slave interface and is
+looped back by the master interface.
+
+Running The Loopback Application
+++++++++++++++++++++++++++++++++
+Start the loopback example::
+
+    ./examples/loopback
+
+You should see the `Received correct data.` message::
+
+    INFO: Received correct data.
+    INFO: Stopping the program