extras/libmemif/examples/example_setup_doc.md

   1 ## Example setup    {#libmemif_example_setup_doc}
   2
   3 #### VPP-memif master icmp_responder slave
   4
   5 > Libmemif example app(s) use memif default socket file: `/run/vpp/memif.sock`.
   6
   7 Run VPP and icmpr-epoll example (default example when running in container).
   8
   9 > Other examples work similar to icmpr-epoll. Brief explanation can be found in @ref libmemif_examples_doc .
  10
  11 VPP-side config:
  12 ```
  13 DBGvpp# create interface memif id 0 master
  14 DBGvpp# set int state memif0/0 up
  15 DBGvpp# set int ip address memif0/0 192.168.1.1/24
  16 ```
  17 icmpr-epoll:
  18 ```
  19 conn 0 0
  20 ```
  21 Memif in slave mode will try to connect every 2 seconds. If connection establishment is successful, a message will show.
  22 ```
  23 INFO: memif connected!
  24 ```
  25 > Error messages like "unmatched interface id" are printed only in debug mode.
  26
  27 Check connected status.
  28 Use show command in icmpr-epoll:
  29 ```
  30 show
  31 MEMIF DETAILS
  32 ==============================
  33 interface index: 0
  34         interface ip: 192.168.1.2
  35         interface name: memif_connection
  36         app name: ICMP_Responder
  37         remote interface name: memif0/0
  38         remote app name: VPP 17.10-rc0~132-g62f9cdd
  39         id: 0
  40         secret:
  41         role: slave
  42         mode: ethernet
  43         socket filename: /run/vpp/memif.sock
  44         rx queues:
  45                 queue id: 0
  46                 ring size: 1024
  47                 buffer size: 2048
  48         tx queues:
  49                 queue id: 0
  50                 ring size: 1024
  51                 buffer size: 2048
  52         link: up
  53 interface index: 1
  54         no connection
  55
  56 ```
  57 Use sh memif command in VPP:
  58 ```
  59 DBGvpp# sh memif
  60 interface memif0/0
  61   remote-name "ICMP_Responder"
  62   remote-interface "memif_connection"
  63   id 0 mode ethernet file /run/vpp/memif.sock
  64   flags admin-up connected
  65   listener-fd 12 conn-fd 13
  66   num-s2m-rings 1 num-m2s-rings 1 buffer-size 0
  67     master-to-slave ring 0:
  68       region 0 offset 32896 ring-size 1024 int-fd 16
  69       head 0 tail 0 flags 0x0000 interrupts 0
  70     master-to-slave ring 0:
  71       region 0 offset 0 ring-size 1024 int-fd 15
  72       head 0 tail 0 flags 0x0001 interrupts 0
  73 ```
  74
  75 Send ping from VPP to icmpr-epoll:
  76 ```
  77 DBGvpp# ping 192.168.1.2
  78 64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=.1888 ms
  79 64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=.1985 ms
  80 64 bytes from 192.168.1.2: icmp_seq=4 ttl=64 time=.1813 ms
  81 64 bytes from 192.168.1.2: icmp_seq=5 ttl=64 time=.1929 ms
  82
  83 Statistics: 5 sent, 4 received, 20% packet loss
  84 ```
  85 #### multiple queues VPP-memif slave icmp_responder master
  86
  87 Run icmpr-epoll as in previous example setup.
  88 Run VPP with startup conf, enabling 2 worker threads.
  89 Example startup.conf:
  90 ```
  91 unix {
  92   interactive
  93   nodaemon
  94   full-coredump
  95 }
  96
  97 cpu {
  98   workers 2
  99 }
 100 ```
 101 VPP-side config:
 102 ```
 103 DBGvpp# create memif id 0 slave rx-queues 2 tx-queues 2
 104 DBGvpp# set int state memif0/0 up
 105 DBGvpp# set int ip address memif0/0 192.168.1.1/24
 106 ```
 107 icmpr-epoll:
 108 ```
 109 conn 0 1
 110 ```
 111 When connection is established a message will print:
 112 ```
 113 INFO: memif connected!
 114 ```
 115 > Error messages like "unmatched interface id" are printed only in debug mode.
 116
 117 Check connected status.
 118 Use show command in icmpr-epoll:
 119 ```
 120 show
 121 MEMIF DETAILS
 122 ==============================
 123 interface index: 0
 124         interface ip: 192.168.1.2
 125         interface name: memif_connection
 126         app name: ICMP_Responder
 127         remote interface name: memif0/0
 128         remote app name: VPP 17.10-rc0~132-g62f9cdd
 129         id: 0
 130         secret:
 131         role: master
 132         mode: ethernet
 133         socket filename: /run/vpp/memif.sock
 134         rx queues:
 135                 queue id: 0
 136                 ring size: 1024
 137                 buffer size: 2048
 138                 queue id: 1
 139                 ring size: 1024
 140                 buffer size: 2048
 141         tx queues:
 142                 queue id: 0
 143                 ring size: 1024
 144                 buffer size: 2048
 145                 queue id: 1
 146                 ring size: 1024
 147                 buffer size: 2048
 148         link: up
 149 interface index: 1
 150         no connection
 151
 152 ```
 153 Use sh memif command in VPP:
 154 ```
 155 DBGvpp# sh memif
 156 interface memif0/0
 157   remote-name "ICMP_Responder"
 158   remote-interface "memif_connection"
 159   id 0 mode ethernet file /run/vpp/memif.sock
 160   flags admin-up slave connected
 161   listener-fd -1 conn-fd 12
 162   num-s2m-rings 2 num-m2s-rings 2 buffer-size 2048
 163     slave-to-master ring 0:
 164       region 0 offset 0 ring-size 1024 int-fd 14
 165       head 0 tail 0 flags 0x0000 interrupts 0
 166     slave-to-master ring 1:
 167       region 0 offset 32896 ring-size 1024 int-fd 15
 168       head 0 tail 0 flags 0x0000 interrupts 0
 169     slave-to-master ring 0:
 170       region 0 offset 65792 ring-size 1024 int-fd 16
 171       head 0 tail 0 flags 0x0001 interrupts 0
 172     slave-to-master ring 1:
 173       region 0 offset 98688 ring-size 1024 int-fd 17
 174       head 0 tail 0 flags 0x0001 interrupts 0
 175
 176 ```
 177 Send ping from VPP to icmpr-epoll:
 178 ```
 179 DBGvpp# ping 192.168.1.2
 180 64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=.1439 ms
 181 64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=.2184 ms
 182 64 bytes from 192.168.1.2: icmp_seq=4 ttl=64 time=.1458 ms
 183 64 bytes from 192.168.1.2: icmp_seq=5 ttl=64 time=.1687 ms
 184
 185 Statistics: 5 sent, 4 received, 20% packet loss
 186 ```
 187
 188 #### icmp_responder master icmp_responder slave
 189
 190 > 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.
 191
 192 Run two instances of icmpr-epoll example.
 193 > If not running in container, make sure folder /run/vpp/ exists before creating memif master.
 194 Instance 1 will be in master mode, instance 2 in slave mode.
 195 instance 1:
 196 ```
 197 conn 0 1
 198 ```
 199 instance 2:
 200 ```
 201 conn 0 0
 202 ```
 203 In 2 seconds, both instances should print connected! message:
 204 ```
 205 INFO: memif connected!
 206 ```
 207 Check peer interface names using show command.