govpp

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 3, 2019 License: Apache-2.0 Imports: 4 Imported by: 0

README

GoVPP

The GoVPP projects provides the API for communication with VPP from Go.

It consists of the following packages:

  • adapter: adapter between GoVPP core and the VPP binary/stats API
  • api: API for communication with GoVPP core
  • cmd/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: essential 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.

                                       +--------------+
    +--------------+                   |              |
    |              |                   |    plugin    |
    |              |                   |              |
    |     App      |                   +--------------+
    |              |            +------+  GoVPP API   |
    |              |            |      +--------------+
    +--------------+   GoVPP    |
    |              |  channels  |      +--------------+
    |  GoVPP core  +------------+      |              |
    |              |            |      |    plugin    |
    +------+-------+            |      |              |
           |                    |      +--------------+
           |                    +------+  GoVPP API   |
           | binary API                +--------------+
           |
    +------+-------+
    |              |
    |  VPP process |
    |              |
    +--------------+

Quick Start

Generate binapi (Go bindings)

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

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

Here is a usage sample of the generated binapi messages:

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

	// Open channel
	ch, _ := conn.NewAPIChannel()
	defer ch.Close()

	// Prepare messages
	req := &vpe.ShowVersion{}
	reply := &vpe.ShowVersionReply{}

	// Send the request
	err := ch.SendRequest(req).ReceiveReply(reply)
}

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

Build & Install

GoVPP now supports pure Go implementation for VPP binary API. This does not depend on CGo or any VPP library and can be easily compiled.

There are two packages providing pure Go implementations in GoVPP:

Using vppapiclient library wrapper (requires CGo)

GoVPP also provides vppapiclient package which actually uses vppapiclient.so library from VPP codebase to communicate with VPP API. 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 pkg-deb
cd build-root
sudo dpkg -i vpp*.deb

To build & install GoVPP:

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

Generating Go bindings with binapi-generator

Once you have binapi-generator installed, you can use it to generate Go bindings for VPP binary API using 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=acl.api.json --output-dir=binapi
binapi-generator --input-dir=/usr/share/vpp/api/core --output-dir=binapi

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func AsyncConnect

func AsyncConnect(shm string, attempts int, interval time.Duration) (*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 SetVppAdapter

func SetVppAdapter(a adapter.VppAPI)

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

Types

This section is empty.

Directories

Path Synopsis
Package adapter provides an interface between govpp core and the VPP.
Package adapter provides an interface between govpp core and the VPP.
mock
Package mock is an alternative VPP adapter aimed for unit/integration testing where the actual communication with VPP is not demanded.
Package mock is an alternative VPP adapter aimed for unit/integration testing where the actual communication with VPP is not demanded.
mock/binapi
Package binapi is a helper package for generic handling of VPP binary API messages in the mock adapter and integration tests.
Package binapi is a helper package for generic handling of VPP binary API messages in the mock adapter and integration tests.
socketclient
Package socketclient is a pure Go implementation of adapter.VppAPI, which uses unix domain sockets as the transport for connecting to the VPP binary API.
Package socketclient is a pure Go implementation of adapter.VppAPI, which uses unix domain sockets as the transport for connecting to the VPP binary API.
statsclient
Package statsclient is pure Go implementation of VPP stats API client.
Package statsclient is pure Go implementation of VPP stats API client.
vppapiclient
Package vppapiclient is the default VPP adapter being used for the connection to VPP binary & stats API via shared memory.
Package vppapiclient is the default VPP adapter being used for the connection to VPP binary & stats API via shared memory.
Package api defines interfaces required by every file generated with binapi-generator
Package api defines interfaces required by every file generated with binapi-generator
cmd
binapi-generator
Generator of Go structs out of the VPP binary API definitions in JSON format.
Generator of Go structs out of the VPP binary API definitions in JSON format.
Package codec provides methods allowing to encode and decode message structs to/from binary format accepted by VPP.
Package codec provides methods allowing to encode and decode message structs to/from binary format accepted by VPP.
Package core provides connectivity to VPP via the adapter: sends and receives the messages to/from VPP, marshalls/unmarshalls them and forwards them between the client Go channels and the VPP.
Package core provides connectivity to VPP via the adapter: sends and receives the messages to/from VPP, marshalls/unmarshalls them and forwards them between the client Go channels and the VPP.
examples
binapi/acl
Package acl is a generated VPP binary API for 'acl' module.
Package acl is a generated VPP binary API for 'acl' module.
binapi/af_packet
Package af_packet is a generated VPP binary API for 'af_packet' module.
Package af_packet is a generated VPP binary API for 'af_packet' module.
binapi/interfaces
Package interfaces is a generated VPP binary API for 'interface' module.
Package interfaces is a generated VPP binary API for 'interface' module.
binapi/ip
Package ip is a generated VPP binary API for 'ip' module.
Package ip is a generated VPP binary API for 'ip' module.
binapi/memclnt
Package memclnt is a generated VPP binary API for 'memclnt' module.
Package memclnt is a generated VPP binary API for 'memclnt' module.
binapi/memif
Package memif is a generated VPP binary API for 'memif' module.
Package memif is a generated VPP binary API for 'memif' module.
binapi/vpe
Package vpe is a generated VPP binary API for 'vpe' module.
Package vpe is a generated VPP binary API for 'vpe' module.
perf-bench
Binary simple-client is an example VPP management application that exercises the govpp API on real-world use-cases.
Binary simple-client is an example VPP management application that exercises the govpp API on real-world use-cases.
rpc-service
service-client is an example VPP management application that exercises the govpp API using generated service client.
service-client is an example VPP management application that exercises the govpp API using generated service client.
simple-client
simple-client is an example VPP management application that exercises the govpp API on real-world use-cases.
simple-client is an example VPP management application that exercises the govpp API on real-world use-cases.
union-example
union-example is an example to show how to use unions in VPP binary API.
union-example is an example to show how to use unions in VPP binary API.
extras
libmemif
Package libmemif is a Golang adapter for the libmemif library (extras/libmemif in the VPP repository).
Package libmemif is a Golang adapter for the libmemif library (extras/libmemif in the VPP repository).
libmemif/examples/gopacket
gopacket is a simple example showing how to answer APR and ICMP echo requests through a memif interface.
gopacket is a simple example showing how to answer APR and ICMP echo requests through a memif interface.
libmemif/examples/icmp-responder
icmp-responder is a simple example showing how to answer APR and ICMP echo requests through a memif interface.
icmp-responder is a simple example showing how to answer APR and ICMP echo requests through a memif interface.
libmemif/examples/jumbo-frames
jumbo-frames is simple example how to send larger and larger jumbo packets with libmemif adapter.
jumbo-frames is simple example how to send larger and larger jumbo packets with libmemif adapter.
libmemif/examples/raw-data
raw-data is a basic example showing how to create a memif interface, handle events through callbacks and perform Rx/Tx of raw data.
raw-data is a basic example showing how to create a memif interface, handle events through callbacks and perform Rx/Tx of raw data.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL