initial commit

Signed-off-by: Rastislav Szabo <raszabo@cisco.com>

1 files changed, 142 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7e70986
--- /dev/null
+++ b/README.md
@@ -0,0 +1,142 @@
+## GoVPP
+
+This set of packages provide the API for communication with VPP from Go. It consists of the following packages:
+
+- [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 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.
+
+```
+                                       +--------------+
+    +--------------+                   |              |
+    |              |                   | Agent Plugin |
+    |              |                   |              |
+    |  Agent Core  |                   +--------------+
+    |              |            +------+  govpp API   |
+    |              |            |      +--------------+
+    +--------------+     Go     |
+    |              |  channels  |      +--------------+
+    |  govpp core  +------------+      |              |
+    |              |            |      | Agent Plugin |
+    +------+-------+            |      |              |
+           |                    |      +--------------+
+binary API |                    +------+  govpp API   |
+  (shmem)  |                           +--------------+
+           |
+    +------+-------+
+    |              |
+    |      VPP     |    
+    |              |
+    +--------------+
+```
+
+
+## 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:
+```
+go run binapi_generator/generator.go --input-dir=/usr/share/vpp/api/ --output-dir=bin_api
+```
+
+Usage of the generated bindings:
+```go
+func main() {
+	conn, _ := govpp.Connect()
+	defer conn.Disconnect()
+
+	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{}
+
+	err := ch.SendRequest(req).ReceiveReply(reply)
+}
+```
+
+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.
+
+
+## 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).
+
+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 ./...
+```
+
+
+## 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.:
+
+```
+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
+```
+
+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
+```
+
+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. 
+
+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.