extras/libmemif/libmemif_doc.md

   1 Shared Memory Packet Interface (memif) Library    {#libmemif_doc}
   2 ==============================================
   3
   4 ## Introduction
   5
   6 Shared memory packet interface (memif) provides high performance packet transmit and receive between user application and Vector Packet Processing (VPP) or multiple user applications. Using libmemif, user application can create shared memory interface in master or slave mode and connect to VPP or another application using libmemif. Once the connection is established, user application can receive or transmit packets using libmemif API.
   7
   8 ![Architecture](docs/architecture.png)
   9
  10 ## Features
  11
  12 - [x] Slave mode
  13   - [x] Connect to VPP over memif
  14   - [x] ICMP responder example app
  15 - [x] Transmit/receive packets
  16 - [x] Interrupt mode support
  17 - [x] File descriptor event polling in libmemif (optional)
  18   - [x] Simplify file descriptor event polling (one handler for control and interrupt channel)
  19 - [x] Multiple connections
  20 - [x] Multiple queues
  21   - [x] Multi-thread support
  22 - [x] Master mode
  23         - [ ] Multiple regions (TODO)
  24 - [ ] Performance testing (TODO)
  25
  26 ## Quickstart
  27
  28 This setup will run libmemif ICMP responder example app in container. Install [docker](https://docs.docker.com/engine/installation) engine.
  29 Useful link: [Docker documentation](https://docs.docker.com/get-started).
  30
  31 Pull image:
  32 ```
  33 # docker pull ligato/libmemif-sample-service
  34 ```
  35
  36 Now you should be able to see ligato/libmemif-sample-service image on your local machine (IMAGE ID in this README may be outdated):
  37 ```
  38 # docker images
  39 REPOSITORY                       TAG                 IMAGE ID            CREATED              SIZE
  40 ligato/libmemif-sample-service   latest              32ecc2f9d013        About a minute ago   468MB
  41 ...
  42 ```
  43
  44 Run container:
  45 ```
  46 # docker run -it --rm --name icmp-responder --hostname icmp-responder --privileged -v "/run/vpp/:/run/vpp/" ligato/libmemif-sample-service
  47 ```
  48 Example application will start in debug mode. Output should look like this:
  49 ```
  50 ICMP_Responder:add_epoll_fd:233: fd 0 added to epoll
  51 ICMP_Responder:add_epoll_fd:233: fd 5 added to epoll
  52 LIBMEMIF EXAMPLE APP: ICMP_Responder (debug)
  53 ==============================
  54 libmemif version: 2.0 (debug)
  55 memif version: 512
  56 commands:
  57         help - prints this help
  58         exit - exit app
  59         conn <index> <mode> [<interrupt-desc>] - create memif. index is also used as interface id, mode 0 = slave 1 = master, interrupt-desc none = default 0 = if ring is full wait 1 = handle only ARP requests
  60         del  <index> - delete memif
  61         show - show connection details
  62         ip-set <index> <ip-addr> - set interface ip address
  63         rx-mode <index> <qid> <polling|interrupt> - set queue rx mode
  64         sh-count - print counters
  65         cl-count - clear counters
  66         send <index> <tx> <ip> <mac> - send icmp
  67 ```
  68
  69 Continue with @ref libmemif_example_setup which contains instructions on how to set up conenction between icmpr-epoll example app and VPP-memif.
  70
  71 #### Next steps
  72
  73 - @subpage libmemif_build_doc
  74 - @subpage libmemif_examples_doc
  75 - @subpage libmemif_example_setup_doc
  76 - @subpage libmemif_gettingstarted_doc
  77 - @subpage libmemif_devperftest_doc