blob: 20cd37bf5f7a10cd298835a05bb36d121ed9397c (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
# GoVPP
[](https://github.com/ligato/vpp-agent/releases/latest) [](https://pkg.go.dev/git.fd.io/govpp.git)
The GoVPP repository contains a Go client library for interacting with the VPP and also Go code generator for the VPP API.
## Overview
- [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
# Development version (master branch)
go install git.fd.io/govpp.git/cmd/binapi-generator@master
```
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
```
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() {
// Connect to VPP
conn, _ := govpp.Connect("/run/vpp/api.sock")
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)
if err != nil {
log.Fatal("ERROR: ", err)
}
log.Print("Version: ", reply.Version)
}
```
For more extensive example of using raw VPP API see [simple-client](examples/simple-client).
### Using RPC service client
Here is a sample code for an effortless way to access the VPP API using a generated RPC service client for calling.
```go
package main
import (
"context"
"log"
"git.fd.io/govpp.git"
"git.fd.io/govpp.git/binapi/vpe"
)
func main() {
// Connect to VPP API socket
conn, _ := govpp.Connect("/run/vpp/api.sock")
defer conn.Disconnect()
// Init vpe service client
client := vpe.NewServiceClient(conn)
reply, err := client.ShowVersion(context.Background(), &vpe.ShowVersion{})
if err != nil {
log.Fatal("ERROR: ", err)
}
log.Print("Version: ", reply.Version)
}
```
For more extensive example of using RPC service client see [rpc-service](examples/rpc-service).
|
