readme-v1

README.md

@@ -1,16 +1,123 @@
-## My Project
+# aws-ebpf-sdk-go
 
-TODO: Fill this README out!
+Golang based SDK for kernel eBPF operations i.e, load/attach/detach eBPF programs and create/delete/update maps. SDK relies on Unix bpf() system calls.
 
-Be sure to:
+SDK currently supports below eBPF program types -
 
-* Change the title in this README
-* Edit your repository description on GitHub
+1. Traffic Classifiers
+2. XDP
+3. Kprobes/Kretprobes
+4. Tracepoint probes
+
+Ring buffer support is available and that would need kernel 5.10+. Map in Map support and perf buffer support is not yet available.
+
+Contributions welcome!
+
+Note: This is the first version of SDK and interface is subject to change so kindly review the release notes before upgrading.
+
+# Getting started
+
+## How to build SDK?
+
+Run `make buid-linux` - this will build the sdk binary.
+
+## How to build elf file?
+
+```
+clang -I../../.. -O2 -target bpf -c <C file> -o <ELF file>
+```
+
+## How to use the SDK?
+
+**Note:** SDK expects the BPF File System (/sys/fs/bpf) to be mounted.
+
+In your application, 
+
+1. Get the latest SDK -
+
+```
+GOPROXY=direct go get github.com/aws/aws-ebpf-sdk-go
+```
+
+2. Import the elfparser - 
+
+```
+goebpfelfparser "github.com/aws/aws-ebpf-sdk-go/pkg/elfparser"
+```
+
+3. Load the elf -
+
+```
+goebpfelfparser.LoadBpfFile(<ELF file>, <custom pin path>)
+```
+
+On a successful load, SDK returns -
+
+1. loaded programs (includes associated maps) 
+
+```
+This is indexed by the pinpath - 
+
+type BpfData struct {
+	Program ebpf_progs.BpfProgram       // Return the program
+	Maps    map[string]ebpf_maps.BpfMap // List of associated maps
+}
+```
+
+2. All maps in the elf file
+```
+This is indexed by the map name -
+
+type BpfMap struct {
+	MapFD       uint32
+	MapID       uint32
+	MapMetaData CreateEBPFMapInput
+}
+```
+
+Application can specify custom pinpath while loading the elf file.
+
+Maps and Programs pinpath location is not customizable with the current version of SDK and will be installed under the below locations by default -
+
+Program PinPath - "/sys/fs/bpf/globals/aws/programs/"
+
+Map PinPath - "/sys/fs/bpf/globals/aws/maps/"
+
+Map defintion should follow the below definition else the SDK will fail to create the map.
+
+```
+struct bpf_map_def_pvt {
+	__u32 type;
+	__u32 key_size;
+	__u32 value_size;
+	__u32 max_entries;
+	__u32 map_flags;
+	__u32 pinning;
+	__u32 inner_map_fd;
+};
+```
+## How to run unit-test
+
+Run `sudo make unit-test`
+
+Note: you would need to run this on you linux system
+
+## How to run functional tests
+
+Go to -
+
+```
+cd test/
+make run-test
+```
 
 ## Security
 
 See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
 
+If you think you’ve found a potential security issue, please do not post it in the Issues. Instead, please follow the
+instructions [here](https://aws.amazon.com/security/vulnerability-reporting/) or [email AWS security directly](mailto:[email protected]).
+
 ## License
 
 This project is licensed under the Apache-2.0 License.