X-Git-Url: https://gerrit.fd.io/r/gitweb?a=blobdiff_plain;f=README.md;h=5581928cde14f3c75ccdecffbaccff197bd13133;hb=a4112fac7b86fe09650d2bb57969fe46404edd7d;hp=a5088f641f9cf4886c8a6bc7cf7c54c6b94cfff2;hpb=2d07847237e754d9050f06f565baa430c70ed937;p=govpp.git diff --git a/README.md b/README.md index a5088f6..5581928 100644 --- a/README.md +++ b/README.md @@ -1,144 +1,128 @@ -## 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](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