This library aims to implement the main communication layer between the Application VMs and the Appliance VMs.

Requirements

To build Vinetalk you will require cmake, ccmake and (optionaly but recomened) libpoco:

ArchLinux

sudo pacman -S cmake poco

CentOS

sudo yum install cmake poco-foundation poco-net

Ubuntu

sudo apt-get install cmake cmake-curses-gui libpoco-dev

Folder layout

• docs - Documentation
• examples - Usage examples of the code
• 3rdparty - Third-party libraries.
• include - Header files that expose the public interface
• src - Source code
  • core - The core implementation of the program/library
  • arch - The architectural specific implementations
  • utils: Contains helper modules, such as data structures, wrappers to external libraries, etc.
• tests - Contain the tests that should be run with make test

API Documentation

Documentation

Building

Vinetalk is built as a shared library(libvine.so), using cmake and make:

First build and navigate to your build folder:

mkdir build;cd build

You must then configure your build using ccmake or cmake directly:

Configure with CCMake

Run ccmake .. in your build folder and press c once:

Every line correspond to a build option(see below for option descriptions). To change/set an option press enter, this will toggle a Boolean flag or allow you to edit a string option. For string press enter again to end string input.

Once you have configured your build, press c followed by g.

Configure with CMake

To configure using, on the build folder you type:

cmake [Configuration Options] ..

Configuration Options

| Option | Description | |--------------------------------------------------|--------------------------------------------------------------------------------------| |-DALLOCSTATS=ON|OFF | Enable Allocator Statistics | |-DARCHALLOCMAXSPACE=NUMBER | Set maximum usable allocator space | |-DBREAKSENABLE | Enable breakdown reporting | |-DBUILDTESTS=ON|OFF | Build unit tests | |-DCMAKEBUILDTYPE=Debug | Produce debug symbols | |-DCOVERAGE=ON|OFF | Enable gcov coverage | |-DJVineTalk | Build java Vinetalk wrappers | |-DTRACEENABLE=ON|OFF | Enable trace file creation | |-DMMAPPOPULATE=ON|OFF | Add MAPPOPULTE flag in mmap. This will make vinetalkinit() slower, use wisely. | |-DUTILSQUEUECAPACITY=NUMBER | Maximum number of outstanding tasks per task queue (Up to 65536), MUST BE power of 2 | |-DVINECONFIGFILE=FILE | Vinetalk configuration file | |-Dasyncarchitecture=spin|mutex|ivshmem | Method used to ensure ordering | |-Dtarget_architecture=shm | Method used to transfer data |

CCMake

Run ccmake .. in your build forder and press c:

Build with Make

After configuring, run make

Testing

After building with tests enabled, you can run tests with make test.

Install

VineTalk can be 'installed' in two ways. System Wide install is the recomened method if deploying on a dedicated machine and have root/sudo access. User Specific installation is recomended if deploying in a shared machine with multiple users and dont have root/sudo access.

System Wide Install

After a successful build, run make install, with root privileges.

User Specific Install

You can use the LDLIBRARYPATH eviroment variable to load VineTalk from the build path.

export LDLIBRARYPATH=

To find the apropriate VineTalk build path, run:

make VineTalkBuildPath

Using the Vine Talk Library

After a successful build your build directory will have a libvine.so file as well as an include folder. Add your build path as a library path and link with vinetalk -lvine. Also add the build/includes folder to your gcc include paths -Ibuild/includes.

Configuration

In order to configure the vine_pipe endpoints, the user must provide architecture specific options.

These configuration options are stored at ~/.vinetalk and follow the format specified in utils/config.h.

This is a minimum working configuration:

shm_file vine_talk

The sections bellow specify the required keys for each supported vinetalk architecture:

Breakdowns

The BREAKS_ENABLE allow the generation of breakdowns(.brk) and headers (.hdr) for performance evaluation of the VineTalk system.

Steps: - Enable BREAKS_ENABLE option and rebuild VineTalk. - Run applications... - When the controller terminates, you will have .hdr and .brk files for all procedures that run.

Vdf

Vdf is a program located at the examples folder, allowing run time inspection of allocator statistics and breakdowns(and more to come). To be built it requires the Poco framework to be installed.

After running it spawns a web server at localhost:8888. The web ui allows inspection of allocator statistics and breakdowns.

shm

Shm implements the vinetalk API/protocol over a shared segment (POSIX or ivshmem).

Required Configuration Keys

| Option | Description | |----------|--------------------------------------------------| | shmfile | A file path specifying the shared segments file. | | shmsize | The size of the shared segment in bytes. |

Optional Configuration Keys

| Option | Description | |-------------|-------------------------------------------------------------------------------------------------------------------------| | shmtrunc | A boolean (0,1) setting if the shmfile should be truncated during initialization. | | shmoff | Start mmap from the given byte offset instead from 0.Can be used to split a single shm to multiple vinepipe instances. | | shm_ivshmem | Boolean , set to 1 if running inside a Vm with ivshmem. |

tracer

Tracer implements an api that tracing vine_talk interface.

Required Configuration Keys

Optional Configuration Keys

| Option | Description | |--------------------|-----------------------------------------------------------------------| | tracerbuffersize | The size of log buffer in bytes,default is 100 entries | | tracer_path | Existing folder, where trace log files will be placed, default is cwd |

VDF

VDF is a monitoring tool for Vinetalk, exposing statistics through a web interface. It accepts the following arguements:

| Arguement | Description | |--------------------|-----------------------------------------------------------------------| | embed | Skips html and head tags from output, allowing output to be embeded | | noalloc | Dont show allocation statistics | | noobj | Dont show object statistics | | nobreak | Dont show breakdowns |