-## GoVPP
+# GoVPP
-This set of packages provide the API for communication with VPP from Go. It consists of the following packages:
+[](https://github.com/ligato/vpp-agent/releases/latest) [](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](cmd/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,
+generator of Go bindings for the VPP binary API and various other tooling for VPP.
-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 |
- | |
- +--------------+
-```
+Here is a brief overview for the repository structure.
+- [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/
+ - [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
-## 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:
-```
-binapi-generator --input-dir=/usr/share/vpp/api/ --output-dir=bin_api
-```
+## Quick Start
+
+Below are some code examples showing GoVPP client interacting with VPP API.
+
+### Using raw messages directly
+
+Here is a code for low-level way to access the VPP API using the generated messages directly for sending/receiving.
-Usage of the generated bindings:
```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/cmd/simple-client/simple_client.go)
-for more examples, including the example on how to use the Go channels directly.
+For a complete example 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
-```
+```go
+package main
-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
-```
+import (
+ "context"
+ "log"
+ "git.fd.io/govpp.git"
+ "git.fd.io/govpp.git/binapi/vpe"
+)
-## 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.:
+func main() {
+ // Connect to VPP API socket
+ conn, _ := govpp.Connect("/run/vpp/api.sock")
+ defer conn.Disconnect()
-```
-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
-```
+ // Init vpe service client
+ client := vpe.NewServiceClient(conn)
-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/cmd/simple-client/simple_client.go):
-```go
-// go:generate binapi-generator --input-dir=bin_api --output-dir=bin_api
+ reply, err := client.ShowVersion(context.Background(), &vpe.ShowVersion{})
+ if err != nil {
+ log.Fatal("ERROR: ", err)
+ }
+
+ log.Print("Version: ", reply.Version)
+}
```
-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.
+For a complete example see [rpc-service](examples/rpc-service).
-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 ./...
-```
-Invokes all `go:generate` rules in all Go packages recursively.
+### More code examples
+
+More examples can be found in [examples](examples) directory.
+
+- [api-trace](api-trace) - trace sent/received messages
+- [binapi-types](binapi-types) - using common types from generated code
+- [multi-vpp](multi-vpp) - connect to multiple VPP instances
+- [perf-bench](perf-bench) - very basic performance test for measuring throughput
+- [rpc-service](rpc-service) - effortless way to call VPP API via RPC client
+- [simple-client](simple-client) - send and receive VPP API messages using GoVPP API directly
+- [stats-client](stats-client) - client for retrieving VPP stats data
+- [stream-client](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
Code Review / govpp.git / blobdiff