govpp

README

GoVPP

This set of packages provide the API for communication with VPP from Go.

It consists of the following packages:

• adapter: adapter between GoVPP core and the VPP
• api: API for communication with GoVPP core
• binapi-generator: Generator for the VPP binary API definitions in JSON format to Go code
• codec: handles encoding/decoding of generated messages into binary form
• core: main functionality of the GoVPP
• examples: examples that use the GoVPP API in real use-cases of VPP management application
• extras: contains Go implementation for libmemif library
• govpp: provides the entry point to GoVPP functionality

The design with separated GoVPP API package and the GoVPP core package enables plugin-based infrastructure, where one entity acts as a master responsible for talking with VPP and multiple entities act as clients that are using the master for the communication with VPP. The clients can be built into standalone shared libraries without the need of linking the GoVPP core and all its dependencies into them.

                                       +--------------+
    +--------------+                   |              |
    |              |                   |  App plugin  |
    |              |                   |              |
    |     App      |                   +--------------+
    |              |            +------+  GoVPP API   |
    |              |            |      +--------------+
    +--------------+     Go     |
    |              |  channels  |      +--------------+
    |  GoVPP core  +------------+      |              |
    |              |            |      |  App plugin  |
    +------+-------+            |      |              |
           |                    |      +--------------+
binary API |                    +------+  GoVPP API   |
 (shmem)   |                           +--------------+
           |
    +------+-------+
    |              |
    |  VPP process |    
    |              |
    +--------------+

Quick Start

Code Generator

Generating Go bindings from the JSON files located in the /usr/share/vpp/api/ directory into the Go packages that will be created inside of the bin_api directory:

binapi-generator --input-dir=/usr/share/vpp/api/ --output-dir=bin_api

Example Usage

Usage of the generated bindings:

func main() {
	conn, _ := govpp.Connect()
	defer conn.Disconnect()

	ch, _ := conn.NewAPIChannel()
	defer ch.Close()
  
	req := &acl.ACLAddReplace{
		ACLIndex: ^uint32(0),
		Tag:      []byte("access list 1"),
		R: []acl.ACLRule{
			{
				IsPermit:       1,
				SrcIPAddr:      net.ParseIP("10.0.0.0").To4(),
				SrcIPPrefixLen: 8,
				DstIPAddr:      net.ParseIP("192.168.1.0").To4(),
				DstIPPrefixLen: 24,
				Proto:          6,
			},
			{
				IsPermit:       1,
				SrcIPAddr:      net.ParseIP("8.8.8.8").To4(),
				SrcIPPrefixLen: 32,
				DstIPAddr:      net.ParseIP("172.16.0.0").To4(),
				DstIPPrefixLen: 16,
				Proto:          6,
			},
		},
	}
	reply := &acl.ACLAddReplaceReply{}

	err := ch.SendRequest(req).ReceiveReply(reply)
}

The example above uses simple wrapper API over underlying go channels, see example client for more examples, including the example on how to use the Go channels directly.

Build & Installation Procedure

Govpp uses vppapiclient library from VPP codebase to communicate with VPP. To build GoVPP, vpp-dev package must be installed, either from packages or from sources.

To build & install vpp-dev from sources:

git clone https://gerrit.fd.io/r/vpp
cd vpp
make install-dep
make bootstrap
make pkg-deb
cd build-root
sudo dpkg -i vpp*.deb

To build & install all GoVPP binaries into your $GOPATH:

go get git.fd.io/govpp.git
cd $GOPATH/src/git.fd.io/govpp.git
make
make install

Building Go bindings from VPP binary APIs

Once you have binapi-generator installed in your $GOPATH, you can use it to generate Go bindings from VPP APis in JSON format. The JSON input can be specified as a single file (input-file argument), or as a directory that will be scanned for all .json files (input-dir). The generated Go bindings will be placed into output-dir (by default current working directory), where each Go package will be placed into a separated directory, e.g.:

binapi-generator --input-file=examples/bin_api/acl.api.json --output-dir=examples/bin_api
binapi-generator --input-dir=examples/bin_api --output-dir=examples/bin_api

In Go, go generate tool can be leveraged to ease the code generation process. It allows to specify generator instructions in any one of the regular (non-generated) .go files that are dependent on generated code using special comments, e.g. the one from example client:

//go:generate binapi-generator --input-dir=bin_api --output-dir=bin_api

Documentation

Overview

Package govpp provides the entry point to govpp functionality. It provides the API for connecting the govpp core to VPP either using the default VPP adapter, or using the adapter previously set by SetAdapter function (useful mostly just for unit/integration tests with mocked VPP adapter).

To create a connection to VPP, use govpp.Connect function:

conn, err := govpp.Connect()
if err != nil {
	// handle error!
}
defer conn.Disconnect()

Make sure you close the connection after using it. If the connection is not closed, it will leak resources. Please note that only one VPP connection is allowed for a single process.

In case you need to mock the connection to VPP (e.g. for testing), use the govpp.SetAdapter function before calling govpp.Connect.

Once connected to VPP, use the functions from the api package to communicate with it.

Index

• func AsyncConnect(shm string) (*core.Connection, chan core.ConnectionEvent, error)
• func Connect(shm string) (*core.Connection, error)
• func SetAdapter(ad adapter.VppAdapter)

Functions

func AsyncConnect

func AsyncConnect(shm string) (*core.Connection, chan core.ConnectionEvent, error)

AsyncConnect asynchronously connects the govpp core to VPP either using the default VPP Adapter, or using the adapter previously set by SetAdapter. This call does not block until connection is established, it returns immediately. The caller is supposed to watch the returned ConnectionState channel for Connected/Disconnected events. In case of disconnect, the library will asynchronously try to reconnect.

func Connect

func Connect(shm string) (*core.Connection, error)

Connect connects the govpp core to VPP either using the default VPP Adapter, or using the adapter previously set by SetAdapter (useful mostly just for unit/integration tests with mocked VPP adapter). This call blocks until VPP is connected, or an error occurs. Only one connection attempt will be performed.

func SetAdapter

func SetAdapter(ad adapter.VppAdapter)

SetAdapter sets the adapter that will be used for connections to VPP in the subsequent `Connect` calls.