extras/libmemif/docs/gettingstarted_doc.md

   1 ## Getting started    {#libmemif_gettingstarted_doc}
   2
   3 #### Concept (Connecting to VPP)
   4
   5 For detailed information on api calls and structures please refer to @ref libmemif.h.
   6
   7 1. Initialize memif
   8    - Declare callback function handling file descriptor event polling.
   9 ```C
  10 int
  11 control_fd_update (int fd, uint8_t events)
  12 {
  13 ...
  14 }
  15 ```
  16    - Call memif initialization function. memif\_init
  17 ```C
  18 err = memif_init (control_fd_update, APP_NAME);
  19 ```
  20
  21 > If event occurres on any file descriptor returned by this callback, call memif\_control\_fd\_handler function.
  22 ```C
  23 memif_err = memif_control_fd_handler (evt.data.fd, events);
  24 ```
  25 > If callback function parameter for memif\_init function is set to NULL, libmemif will handle file descriptor event polling.
  26   Api call memif\_poll\_event will call epoll\_pwait with user defined timeout to poll event on file descriptors opened by libmemif.
  27 ```C
  28 /* main loop */
  29     while (1)
  30     {
  31         if (memif_poll_event (-1) < 0)
  32         {
  33             DBG ("poll_event error!");
  34         }
  35     }
  36 ```
  37
  38 > Memif initialization function will initialize internal structures and create timer file descriptor, which will be used for sending periodic connection requests. Timer is disarmed if no memif interface is created.
  39
  40 2. Creating interface
  41    - Declare memif connction handle.
  42 ```C
  43 memif_conn_handle_t c;
  44 ```
  45 > example app uses struct that contains connection handle, rx/tx buffers and other connection specific information.
  46
  47    - Specify connection arguments.
  48 ```C
  49 memif_conn_args_t args;
  50 memset (&args, 0, sizeof (args));
  51 args.is_master = is_master;
  52 args.log2_ring_size = 10;
  53 args.buffer_size = 2048;
  54 args.num_s2m_rings = 2;
  55 args.num_m2s_rings = 2;
  56 strncpy ((char *) args.interface_name, IF_NAME, strlen (IF_NAME));
  57 strncpy ((char *) args.instance_name, APP_NAME, strlen (APP_NAME));
  58 args.mode = 0;
  59 args.interface_id = 0;
  60 ```
  61    - Declare callback functions called on connected/disconnected/interrupted status changed.
  62 ```C
  63 int
  64 on_connect (memif_conn_handle_t conn, void *private_ctx)
  65 {
  66 ...
  67 }
  68
  69 int
  70 on_disconnect (memif_conn_handle_t conn, void *private_ctx)
  71 {
  72     INFO ("memif connected!");
  73     return 0;
  74 }
  75 ```
  76    - Call memif interface create function. memif\_create
  77 ```C
  78 err = memif_create (&c->conn,
  79         &args, on_connect, on_disconnect, on_interrupt, &ctx[index]);
  80 ```
  81 > If connection is in slave mode, arms timer file descriptor.
  82 > If on interrupt callback is set to NULL, user will not be notified about interrupt. Use memif\_get\_queue\_efd call to get interrupt file descriptor for specific queue.
  83 ```C
  84 int fd = -1;
  85 err = memif_get_queue_efd (c->conn, data->qid, &fd);
  86 ```
  87
  88 3. Connection establishment
  89     - User application will poll events on all file descriptors returned in memif\_control\_fd\_update\_t callback.
  90     - On event call memif\_control\_fd\_handler.
  91     - Everything else regarding connection establishment will be done internally.
  92     - Once connection has been established, a callback will inform the user about connection status change.
  93
  94 4. Interrupt packet receive
  95     - If event is polled on interrupt file descriptor, libmemif will call memif\_interrupt\_t callback specified for every connection instance.
  96 ```C
  97 int
  98 on_interrupt (memif_conn_handle_t conn, void *private_ctx, uint16_t qid)
  99 {
 100 ...
 101 }
 102 ```
 103
 104 6. Memif buffers
 105     - Packet data are stored in memif\_buffer\_t. Pointer _data_ points to shared memory buffer, and unsigned integer *data\_len* contains packet data length.
 106 ```C
 107 typedef struct
 108 {
 109     uint16_t desc_index;
 110     uint32_t buffer_len;
 111     uint32_t data_len;
 112     void *data;
 113 } memif_buffer_t;
 114 ```
 115
 116 5. Packet receive
 117     - Api call memif\_rx\_burst will set all required fields in memif buffers provided by user application.
 118 ```C
 119 err = memif_rx_burst (c->conn, qid, c->rx_bufs, MAX_MEMIF_BUFS, &rx);
 120 ```
 121     - User application can then process packets.
 122     - Api call memif\_buffer\_free will make supplied memif buffers ready for next receive and mark shared memory buffers as free.
 123 ```C
 124 err = memif_buffer_free (c->conn, qid, c->rx_bufs, rx, &fb);
 125 ```
 126
 127 6. Packet transmit
 128     - Api call memif\_buffer\_alloc will set all required fields in memif buffers provided by user application.
 129 ```C
 130 err = memif_buffer_alloc (c->conn, qid, c->tx_bufs, n, &r);
 131 ```
 132     - User application can populate shared memory buffers with packets.
 133     - Api call memif\_tx\_burst will inform peer interface (master memif on VPP) that there are packets ready to receive and mark memif buffers as free.
 134 ```C
 135 err = memif_tx_burst (c->conn, qid, c->tx_bufs, c->tx_buf_num, &r);
 136 ```
 137
 138 7. Helper functions
 139     - Memif details
 140       - Api call memif\_get\_details will return details about connection.
 141 ```C
 142 err = memif_get_details (c->conn, &md, buf, buflen);
 143 ```
 144     - Memif error messages
 145       - Every api call returns error code (integer value) mapped to error string.
 146       - Call memif\_strerror will return error message assigned to specific error code.
 147 ```C
 148 if (err != MEMIF_ERR_SUCCESS)
 149     INFO ("memif_get_details: %s", memif_strerror (err));
 150 ```
 151         - Not all syscall errors are translated to memif error codes. If error code 1 (MEMIF\_ERR\_SYSCALL) is returned then libmemif needs to be compiled with -DMEMIF_DBG flag to print error message. Use _make -B_ to rebuild libmemif in debug mode.
 152
 153 #### Example app (libmemif fd event polling):
 154
 155 - @ref extras/libmemif/examples/icmp_responder
 156
 157 > Optional argument: transmit queue id.
 158 ```
 159 icmpr 1
 160 ```
 161 > Set transmit queue id to 1. Default is 0.
 162 > Application will create memif interface in slave mode and try to connect to VPP. Exit using Ctrl+C. Application will handle SIGINT signal, free allocated memory and exit with EXIT_SUCCESS.
 163
 164 #### Example app:
 165
 166 ICMP Responder custom fd event polling.
 167
 168 - @ref extras/libmemif/examples/icmp_responder-epoll
 169
 170 #### Example app (multi-thread queue polling)
 171
 172 ICMP Responder multi-thread.
 173 - @ref extras/libmemif/examples/icmp_responder-mt
 174
 175 > Simple example of libmemif multi-thread usage. Connection establishment is handled by main thread. There are two rx queues in this example. One in polling mode and second in interrupt mode.
 176
 177 VPP config:
 178 ```
 179 # create memif id 0 master
 180 # set int state memif0 up
 181 # set int ip address memif0 192.168.1.1/24
 182 # ping 192.168.1.2
 183 ```
 184 For multiple rings (queues) support run VPP with worker threads:
 185 example startup.conf:
 186 ```
 187 unix {
 188   interactive
 189   nodaemon
 190   full-coredump
 191 }
 192
 193 cpu {
 194   workers 2
 195 }
 196 ```
 197 VPP config:
 198 ```
 199 # create memif id 0 master
 200 # set int state memif0 up
 201 # set int ip address memif0 192.168.1.1/24
 202 # ping 192.168.1.2
 203 ```
 204 > Master mode queue number is limited by worker threads. Slave mode interface needs to specify number of queues.
 205 ```
 206 # create memif id 0 slave rx-queues 2 tx-queues 2
 207 ```
 208 > Example applications use VPP default socket file for memif: /run/vpp/memif.sock
 209 > For master mode, socket directory must exist prior to memif\_create call.
 210
 211 #### Unit tests
 212
 213 Unit tests use [Check](https://libcheck.github.io/check/index.html) framework. This framework must be installed in order to build *unit\_test* binary.
 214 Ubuntu/Debian:
 215 ```
 216 sudo apt-get install check
 217 ```
 218 [More platforms](https://libcheck.github.io/check/web/install.html)
 219