libmemif

Makefile.am

@@ -13,17 +13,77 @@
 
 AUTOMAKE_OPTIONS = foreign subdir-objects
 
+ACLOCAL_AMFLAGS = -I m4
+
+AM_CPPFLAGS = -g -DMEMIF_DBG -DICMP_DBG
+
+SRCS_C := $(shell find . -name "*.c" )
+SRCS_H := $(shell find . -name "*.h" )
+
+.PHONY: release
+release:
+	$(MAKE) AM_CPPFLAGS="-O3"
+
+.PHONY: doc
+doc:
+	@echo Building doxygen documentation...
+	doxygen doxygen.conf
+	@echo Doxygen documentation built in docs directory.
+
+.PHONY: fixstyle
+fixstyle:
+	@echo Fixing code style...
+	indent $(SRCS_C) $(SRCS_H)
+	@echo Code style fixed!
+
+#
+# unit_test
+#
+unit_test_SOURCES = test/unit_test.c \
+                    test/main_test.c \
+                    test/socket_test.c \
+                    src/main.c \
+                    src/socket.c
+# macro MEMIF_UNIT_TEST -> compile functions without static keyword
+# and declare them in header files, so they can be called from unit tests
+unit_test_CPPFLAGS = $(AM_CPPFLAGS) -Itest -Isrc -DMEMIF_UNIT_TEST -g $(CHECK_CFLAGS)
+unit_test_LDADD = $(CHECK_LIBS)
+
 #
 # main lib
 #
-libmemif_la_SOURCES = src/main.c
-lib_LTLIBRARIES = libmemif.la
-include_HEADERS = src/libmemif.h
+libmemif_la_SOURCES = src/main.c src/socket.c
+libmemif_la_CPPFLAGS = $(AM_CPPFLAGS) -Isrc
 
 #
 # ICMP responder example
 #
-icmp_responder_SOURCES = examples/icmp_responder/main.c
-icmp_responder_LDADD = libmemif.la
-icmp_responder_CPPFLAGS = $(AM_CPPFLAGS) -Isrc
-noinst_PROGRAMS = icmp_responder
+icmpr_SOURCES = examples/icmp_responder/main.c examples/icmp_responder/icmp_proto.c
+icmpr_LDADD = libmemif.la
+icmpr_CPPFLAGS = $(AM_CPPFLAGS) -Isrc -Iexamples/icmp_responder
+
+#
+# ICMP responder libmemif event polling example
+#
+icmpr_epoll_SOURCES = examples/icmp_responder-epoll/main.c \
+                    examples/icmp_responder/icmp_proto.c
+icmpr_epoll_LDADD = libmemif.la
+icmpr_epoll_CPPFLAGS = $(AM_CPPFLAGS) -Isrc -Iexamples/icmp_responder
+
+#
+# ICMP responder multi-thread example
+#
+icmpr_mt_SOURCES = examples/icmp_responder-mt/main.c \
+                      examples/icmp_responder/icmp_proto.c
+icmpr_mt_LDADD = libmemif.la -lpthread
+icmpr_mt_CPPFLAGS = $(AM_CPPFLAGS) -Isrc -Iexamples/icmp_responder
+
+noinst_PROGRAMS = icmpr icmpr-epoll icmpr-mt
+
+check_PROGRAMS = unit_test
+
+include_HEADERS = src/libmemif.h
+
+lib_LTLIBRARIES = libmemif.la
+
+TESTS = $(check_PROGRAMS)

README.md

@@ -0,0 +1,72 @@
+Shared Memory Packet Interface (memif) Library
+==============================================
+## Introduction
+
+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.
+
+![Architecture](docs/architecture.png)
+
+## Features
+
+- [x] Slave mode
+  - [x] Connect to VPP over memif
+  - [x] ICMP responder example app
+- [x] Transmit/receive packets
+- [x] Interrupt mode support
+- [x] File descriptor event polling in libmemif (optional)
+  - [x] Simplify file descriptor event polling (one handler for control and interrupt channel)
+- [x] Multiple connections
+- [x] Multiple queues
+  - [x] Multi-thread support
+- [x] Master mode
+	- [ ] Multiple regions (TODO)
+- [ ] Performance testing (TODO)
+
+## Quickstart
+
+This setup will run libmemif ICMP responder example app in container. Install [docker](https://docs.docker.com/engine/installation) engine.
+Useful link: [Docker documentation](https://docs.docker.com/get-started).
+
+Pull image:
+```
+# docker pull ligato/libmemif-sample-service
+```
+
+Now you should be able to see ligato/libmemif-sample-service image on your local machine (IMAGE ID in this README may be outdated):
+```
+# docker images
+REPOSITORY                       TAG                 IMAGE ID            CREATED              SIZE
+ligato/libmemif-sample-service   latest              32ecc2f9d013        About a minute ago   468MB
+...
+```
+
+Run container:
+```
+# docker run -it --rm --name icmp-responder --hostname icmp-responder --privileged -v "/run/vpp/:/run/vpp/" ligato/libmemif-sample-service
+```
+Example application will start in debug mode. Output should look like this:
+```
+ICMP_Responder:add_epoll_fd:204: fd 0 added to epoll
+MEMIF_DEBUG:src/main.c:memif_init:383: app name: ICMP_Responder
+ICMP_Responder:add_epoll_fd:204: fd 4 added to epoll
+LIBMEMIF EXAMPLE APP: ICMP_Responder (debug)
+==============================
+libmemif version: 1.0 (debug)
+memif version: 256
+commands:
+	help - prints this help
+	exit - exit app
+	conn <index> - create memif (slave-mode)
+	del  <index> - delete memif
+	show - show connection details
+	ip-set <index> <ip-addr> - set interface ip address
+	rx-mode <index> <qid> <polling|interrupt> - set queue rx mode
+```
+
+Continue with [Example setup](examples/ExampleSetup.md) which contains instructions on how to set up conenction between icmpr-epoll example app and VPP-memif.
+
+#### Next steps
+
+- [Build instructions](docs/BuildInstructions.md) Instructions on how to build/install libmemif.
+- [Examples](examples/README.md) More example apps presenting different features.
+- [Getting started](docs/GettingStarted.md) Introduction to libmemif API. Explaining library usage in custom app.

configure.ac

@@ -4,6 +4,8 @@ AM_INIT_AUTOMAKE
 AM_SILENT_RULES([yes])
 AC_PREFIX_DEFAULT([/usr])
 
+PKG_CHECK_MODULES([CHECK], [check])
+
 AC_PROG_CC
 
 AC_OUTPUT([Makefile])

dockerfile

@@ -0,0 +1,19 @@
+FROM ubuntu:xenial
+
+RUN apt-get update && \
+	apt-get install -y git build-essential autoconf pkg-config libtool sudo check
+RUN rm -rf /var/lib/apt/lists/*
+
+RUN git clone https://github.com/JakubGrajciar/libmemif.git /libmemif
+WORKDIR /libmemif
+RUN git checkout master
+RUN ./bootstrap
+RUN ./configure
+RUN make
+RUN make install
+
+RUN mkdir /var/vpp
+
+RUN ulimit -c unlimited
+
+CMD ./.libs/icmpr-epoll

docs/BuildInstructions.md

@@ -0,0 +1,54 @@
+## Build Instructions
+
+Install dependencies
+```
+# sudo apt-get install -y git autoconf pkg_config libtool check
+```
+
+Clone repository to your local machine. 
+```
+# git clone https://github.com/JakubGrajciar/libmemif.git
+```
+
+From root directory execute:
+For debug build:
+```
+# ./bootstrap
+# ./configure
+# make
+# make install
+```
+
+For release build:
+```
+# ./bootstrap
+# ./configure
+# make release
+# make install
+```
+Verify installation:
+```
+# ./.libs/icmpr-epoll
+```
+> Make sure to run the binary file from ./.libs. File ./icmp\_responder in libmemif root directory is script that links the library, so it only verifies successful build. Default install path is /usr/lib.
+Use _help_ command to display build information and commands:
+```
+ICMP_Responder:add_epoll_fd:204: fd 0 added to epoll
+MEMIF_DEBUG:src/main.c:memif_init:383: app name: ICMP_Responder
+ICMP_Responder:add_epoll_fd:204: fd 4 added to epoll
+LIBMEMIF EXAMPLE APP: ICMP_Responder (debug)
+==============================
+libmemif version: 1.0 (debug)
+memif version: 256
+commands:
+	help - prints this help
+	exit - exit app
+	conn <index> - create memif (slave-mode)
+	del  <index> - delete memif
+	show - show connection details
+	ip-set <index> <ip-addr> - set interface ip address
+	rx-mode <index> <qid> <polling|interrupt> - set queue rx mode
+```
+#### Examples
+
+Once the library is build/installed, refer to [Examples](../examples/README.md) and [Getting started](GettingStarted.md) for additional information on basic use cases and API usage.