Difference between revisions of "VPP/HostStack/VCL"

From fd.io
< VPP‎ | HostStack
Jump to: navigation, search
(vcl { ... })
(vcl { ... })
Line 21: Line 21:
 
! Description
 
! Description
 
|-
 
|-
| <code>heapsize <bytes></code>
+
| <code>heapsize <nn bytes></code>
 
| Size of heap used by VCL for the application (one or multiple workers).
 
| Size of heap used by VCL for the application (one or multiple workers).
 
|-
 
|-
Line 33: Line 33:
 
| Path to app socket api socket file
 
| Path to app socket api socket file
 
|-
 
|-
| <code>segment-size <bytes>/code>
+
| <code>segment-size <nn bytes></code>
 
| Size of first shared memory segment requested from VPP
 
| Size of first shared memory segment requested from VPP
 +
|-
 +
| <code>add-segment-size <nn bytes></code>
 +
| Size of additional shared memory segments to be added by VPP
 +
|-
 +
| <code>add-segment-size <nn bytes></code>
 +
| Size of additional shared memory segments to be added by VPP
 +
|-
 +
| <code>rx-fifo-size <nn bytes></code>
 +
| Rx fifo size in bytes
 +
|-
 +
| <code>tx-fifo-size <nn bytes></code>
 +
| Tx fifo size in bytes
 
|-
 
|-
 
|}
 
|}

Revision as of 02:20, 10 November 2020

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
app-socket-api <filename> Path to app socket api socket file
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
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