VPP/HostStack/VCL

VPP Comms Library (VCL) is meant to simplify application integration with VPP by offering APIs that are similar to but not POSIX compliant. Applications are not enforced to use VCL and, in fact, if more fine grained control is required, it's recommended that applications use the "raw" session layer apis. Nonetheless, it should be noted that such a choice come with significant overhead as apps need to handle session layer APIs, message queues, threading and the reimplementation of the async comms mechanisms (e.g., epoll).

VCL manages the interaction with the session layer, abstracts session to integer session handles, exposes its own async communication functions and it supports multi-worker applications. Notably, applications need to explicitly register their workers with VCL and they must ensure that sessions are never shared between multiple workers, i.e., VCL data structures are not thread safe.

If applications cannot be changed to avoid sharing sessions between multiple workers, or if they cannot be changed to explicitly register their workers, then they can use another shim layer built on top of VCL called VLS (VCL Locked Sessions). As the name suggests, VLS ensures through locking that only one of the application’s workers can interact at one time with a VCL session and in situations when the application has multiple threads that only one of those threads can interact with VCL.

Finally, for situations when an application cannot be changed, or changing it is too difficult, integration with VPP might be doable via LDP. LDP leverages LD_PRELOAD to intercept syscalls that are supposed to go into the kernel and reinjects them into VLS. It should however be noted that LDP is not expected to always work. Statically linked apps cannot be supported and most probably LDP does not support all the combinations of syscalls and options for syscalls combined with threading and forking app behavior.

For VCL and LDP examples see the tutorials section.

VCL Configuration

VCL tries to initialize by reading the configuration in the file pointed to by the VCL_CONFIG environment variable, or if that is not configured, by reading /etc/vpp/vcl.conf. If no file is found, VCL will fail to initialize.

Parameters that can be configured through the configuration file include:

vcl { ... }

Parameter	Description
heapsize <nn bytes>	Size of heap used by VCL for the application (one or multiple workers).
max-workers <nn>	Max number of workers to be pre-allocated for the application.
api-socket-name <filename>	Path to binary api socket file. On vpp side, this is configured via socksvr {socket-name <path>} in startup.conf.
app-socket-api <filename>	Path to app socket api socket file. To enable the api in vpp see session layer config. The default namespace socket is /var/run/vpp/app_ns_sockets/default
segment-size <nn bytes>	Size of first shared memory segment requested from VPP
add-segment-size <nn bytes>	Size of additional shared memory segments to be added by VPP
rx-fifo-size <nn bytes>	Rx fifo size in bytes
tx-fifo-size <nn bytes>	Tx fifo size in bytes
event-queue-size <nn>	Length requested for message queue from VPP to VCL
app-scope-local	Request local scope for app
app-scope-global	Request global scope for app
use-mq-eventfd	Request use of eventfd, as opposed to mutex/condvar, message queue notifications
namespace-id <string>	ID for namespace that is requested (binary api only)
namespace-secret <nn>	Secret for namespace that is requested (binary api only)

Note that only one of the two attachment options, i.e., binary api or the app socket api, can be used at one time. Moreover, if the session layer is configured to use the app socket api, it will take precedence over the binary api and all apps must be configured to use it.