FD.io VPP  v17.10-9-gd594711
Vector Packet Processing
Getting started

Concept (Connecting to VPP)

For detailed information on api calls and structures please refer to libmemif.h.

  1. Initialize memif

If event occurres on any file descriptor returned by this callback, call memif_control_fd_handler function.

memif_err = memif_control_fd_handler (evt.data.fd, events);

If callback function parameter for memif_init function is set to NULL, libmemif will handle file descriptor event polling.

Api call memif_poll_event will call epoll_pwait with user defined timeout to poll event on file descriptors opened by libmemif.

/* main loop */
while (1)
if (memif_poll_event (-1) < 0)
DBG ("poll_event error!");

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.

  1. Creating interface
  2. Connection establishment
    • User application will poll events on all file descriptors returned in memif_control_fd_update_t callback.
    • On event call memif_control_fd_handler.
    • Everything else regarding connection establishment will be done internally.
    • Once connection has been established, a callback will inform the user about connection status change.
  3. Interrupt packet receive
    • If event is polled on interrupt file descriptor, libmemif will call memif_interrupt_t callback specified for every connection instance.
      on_interrupt (memif_conn_handle_t conn, void *private_ctx, uint16_t qid)
  4. Memif buffers
    • Packet data are stored in memif_buffer_t. Pointer data points to shared memory buffer, and unsigned integer data_len contains packet data length.
      typedef struct
      uint16_t desc_index;
      uint32_t buffer_len;
      uint32_t data_len;
      void *data;
  1. Packet receive
    • Api call memif_rx_burst will set all required fields in memif buffers provided by user application.
      err = memif_rx_burst (c->conn, qid, c->rx_bufs, MAX_MEMIF_BUFS, &rx);
    • User application can then process packets.
    • Api call memif_buffer_free will make supplied memif buffers ready for next receive and mark shared memory buffers as free.
      err = memif_buffer_free (c->conn, qid, c->rx_bufs, rx, &fb);
  2. Packet transmit
    • Api call memif_buffer_alloc will set all required fields in memif buffers provided by user application.
      err = memif_buffer_alloc (c->conn, qid, c->tx_bufs, n, &r);
    • User application can populate shared memory buffers with packets.
    • 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.
      err = memif_tx_burst (c->conn, qid, c->tx_bufs, c->tx_buf_num, &r);
  3. Helper functions
    • Memif details
      • Api call memif_get_details will return details about connection.
        err = memif_get_details (c->conn, &md, buf, buflen);
    • Memif error messages
      • Every api call returns error code (integer value) mapped to error string.
      • Call memif_strerror will return error message assigned to specific error code.
        if (err != MEMIF_ERR_SUCCESS)
        INFO ("memif_get_details: %s", memif_strerror (err));
        • 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.

Example app (libmemif fd event polling):

Optional argument: transmit queue id.

1 icmpr 1

Set transmit queue id to 1. Default is 0. 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.

Example app:

ICMP Responder custom fd event polling.

Example app (multi-thread queue polling)

ICMP Responder multi-thread.

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.

VPP config:

1 # create memif id 0 master
2 # set int state memif0 up
3 # set int ip address memif0
4 # ping

For multiple rings (queues) support run VPP with worker threads: example startup.conf:

1 unix {
2  interactive
3  nodaemon
4  full-coredump
5 }
7 cpu {
8  workers 2
9 }

VPP config:

1 # create memif id 0 master
2 # set int state memif0 up
3 # set int ip address memif0
4 # ping

Master mode queue number is limited by worker threads. Slave mode interface needs to specify number of queues.

1 # create memif id 0 slave rx-queues 2 tx-queues 2

Example applications use VPP default socket file for memif: /run/vpp/memif.sock For master mode, socket directory must exist prior to memif_create call.

Unit tests

Unit tests use Check framework. This framework must be installed in order to build unit_test binary. Ubuntu/Debian:

1 sudo apt-get install check

More platforms