-## GoVPP
+# GoVPP
-This set of packages provide the API for communication with VPP from Go. It consists of the following packages:
+[![stable](https://img.shields.io/github/v/tag/fdio/govpp.svg?label=release&logo=github)](https://github.com/ligato/vpp-agent/releases/latest) [![PkgGoDev](https://pkg.go.dev/badge/git.fd.io/govpp.git)](https://pkg.go.dev/git.fd.io/govpp.git)
-- [govpp](govpp.go): provides the entry point to govpp functionality
-- [api](api/api.go): API for communication with govpp core using Go channels (without the need of importing the govpp core package itself),
-- [core](core/): main functionality of the govpp, sends and receives the messages to/from VPP using the adapter, marshalls/unmarshalls them and forwards them between the client Go channels and the VPP,
-- [adapter](adapter/): adapter between govpp core and the VPP, responsible for sending and receiving binary-encoded data via shared memory,
-- [binapi_generator](binapi_generator/generator.go): Generator of Go structs out of the VPP binary API definitions in JSON format,
-- [examples](examples/): example VPP management application that exercises the govpp API on real-world use-cases.
+The GoVPP repository contains a Go client library for interacting with the VPP and also Go code generator for the VPP API.
-The design with separated govpp API package ([api](api/api.go)) and the govpp core package ([core](core/)) enables
-plugin-based infrastructure, where one entity acts as a master responsible for talking with VPP (e.g. Agent
-Core on the schema below) and multiple entities act as clients that are using the master for the communication with
-VPP (Agent Plugins on the schema below). The clients can be built into standalone shared libraries without the need
-of linking the govpp core and all its dependencies into them.
+## Overview
-```
- +--------------+
- +--------------+ | |
- | | | Agent Plugin |
- | | | |
- | Agent Core | +--------------+
- | | +------+ govpp API |
- | | | +--------------+
- +--------------+ Go |
- | | channels | +--------------+
- | govpp core +------------+ | |
- | | | | Agent Plugin |
- +------+-------+ | | |
- | | +--------------+
-binary API | +------+ govpp API |
- (shmem) | +--------------+
- |
- +------+-------+
- | |
- | VPP |
- | |
- +--------------+
-```
+- [govpp](govpp.go) - the entry point for the GoVPP client
+ - [adapter](adapter) - VPP binary & stats API interface
+ - [mock](adapter/mock) - Mock adapter used for testing
+ - [socketclient](adapter/socketclient) - Go implementation of VPP API client for unix socket
+ - [statsclient](adapter/statsclient) - Go implementation of VPP Stats client for shared memory
+ - [vppapiclient](adapter/vppapiclient) - CGo wrapper of vppapiclient library (DEPRECATED!)
+ - [api](api) - GoVPP client API
+ - [binapigen](binapigen) - library for generating code from VPP API
+ - [vppapi](binapigen/vppapi) - VPP API parser
+ - [cmd](cmd)
+ - [binapi-generator](cmd/binapi-generator) - VPP binary API generator
+ - [vpp-proxy](cmd/vpp-proxy) - VPP proxy for remote access
+ - [codec](codec) - handles encoding/decoding of generated messages into binary form
+ - [core](core) - implementation of the GoVPP client
+ - [docs](docs) - documentation
+ - [examples](examples) - examples demonstrating GoVPP functionality
+ - [internal](internal) - packages used internally by GoVPP
+ - [proxy](proxy) - contains client/server implementation for proxy
+ - [test](test) - integration tests, benchmarks and performance tests
+
+## Install binapi-generator
+
+### Prerequisites
+
+- Go 1.13+ ([download]((https://golang.org/dl)))
+
+### Install via Go toolchain
+```shell
+# Latest version (most recent tag)
+go install git.fd.io/govpp.git/cmd/binapi-generator@latest
-## Example usage
-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:
+# Development version (master branch)
+go install git.fd.io/govpp.git/cmd/binapi-generator@master
```
-go run binapi_generator/generator.go --input-dir=/usr/share/vpp/api/ --output-dir=bin_api
+
+NOTE: Using `go install` to install programs is only supported in Go 1.16+ ([more info](https://go.dev/doc/go1.16#go-command)). For Go 1.15 or older, use `go get` instead of `go install`.
+
+### Install from source
+
+```sh
+# Clone repository anywhere
+git clone https://gerrit.fd.io/r/govpp.git
+cd govpp
+make install-generator
```
-Usage of the generated bindings:
+NOTE: There is no need to setup or clone inside `GOPATH` for Go 1.13+ ([more info](https://go.dev/doc/go1.13#modules))
+and you can simply clone the repository _anywhere_ you want.
+
+## Examples
+
+The [examples/](examples/) directory contains several examples for GoVPP
+
+- [api-trace](examples/api-trace) - trace sent/received messages
+- [binapi-types](examples/binapi-types) - using common types from generated code
+- [multi-vpp](examples/multi-vpp) - connect to multiple VPP instances
+- [perf-bench](examples/perf-bench) - very basic performance test for measuring throughput
+- [rpc-service](examples/rpc-service) - effortless way to call VPP API via RPC client
+- [simple-client](examples/simple-client) - send and receive VPP API messages using GoVPP API directly
+- [stats-client](examples/stats-client) - client for retrieving VPP stats data
+- [stream-client](examples/stream-client) - using new stream API to call VPP API
+
+### Documentation
+
+Further documentation can be found in [docs/](docs/) directory.
+
+- [Adapters](docs/ADAPTERS.md) - detailed info about transport adapters and their implementations
+- [Binapi Generator](docs/GENERATOR.md) - user guide for generating VPP binary API
+
+## Quick Start
+
+### Using raw messages directly
+
+Here is a sample code for low-level way to access the VPP API using the generated messages directly for sending/receiving.
+
```go
+package main
+
+import (
+ "log"
+
+ "git.fd.io/govpp.git"
+ "git.fd.io/govpp.git/binapi/interfaces"
+ "git.fd.io/govpp.git/binapi/vpe"
+)
+
func main() {
- conn, _ := govpp.Connect()
+ // Connect to VPP
+ conn, _ := govpp.Connect("/run/vpp/api.sock")
defer conn.Disconnect()
+ // Open channel
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{}
+ // Prepare messages
+ req := &vpe.ShowVersion{}
+ reply := &vpe.ShowVersionReply{}
+
+ // Send the request
err := ch.SendRequest(req).ReceiveReply(reply)
+ if err != nil {
+ log.Fatal("ERROR: ", err)
+ }
+
+ log.Print("Version: ", reply.Version)
}
```
-The example above uses simple wrapper API over underlying go channels, see [example_client](examples/example_client.go)
-for more examples, including the example on how to use the Go channels directly.
+For more extensive example of using raw VPP API see [simple-client](examples/simple-client).
+### Using RPC service client
-## 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](https://wiki.fd.io/view/VPP/Installing_VPP_binaries_from_packages) or
-[from sources](https://wiki.fd.io/view/VPP/Build,_install,_and_test_images#Build_A_VPP_Package).
+Here is a sample code for an effortless way to access the VPP API using a generated RPC service client for calling.
-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`:
-```
-cd govpp
-go build ./...
-go install ./...
-```
+```go
+package main
+import (
+ "context"
+ "log"
-## 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.:
+ "git.fd.io/govpp.git"
+ "git.fd.io/govpp.git/binapi/vpe"
+)
-```
-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
-```
+func main() {
+ // Connect to VPP API socket
+ conn, _ := govpp.Connect("/run/vpp/api.sock")
+ defer conn.Disconnect()
-In Go, [go generate](https://blog.golang.org/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](examples/example_client.go):
-```go
-// go:generate binapi_generator --input-dir=bin_api --output-dir=bin_api
-```
+ // Init vpe service client
+ client := vpe.NewServiceClient(conn)
-The comment must start at the beginning of the line and have no spaces between the `//` and the `go:generate`.
-After that marker, the rest of the line specifies a command for `go generate` to run.
+ reply, err := client.ShowVersion(context.Background(), &vpe.ShowVersion{})
+ if err != nil {
+ log.Fatal("ERROR: ", err)
+ }
-The `go generate` tool automatically traverses the code base, looks for the special comments in Go code and
-invokes the code generation, e.g.:
-```
-go generate ./...
+ log.Print("Version: ", reply.Version)
+}
```
-Invokes all `go:generate` rules in all Go packages recursively.
+
+For more extensive example of using RPC service client see [rpc-service](examples/rpc-service).