update README

koonwen · koonwen · commit 106e7534ca0c · 2024-07-01T13:58:14.000+02:00
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 [![OCaml-CI Build Status](https://img.shields.io/endpoint?url=https://ocaml.ci.dev/badge/koonwen/ocaml-libbpf/main&logo=ocaml)](https://ocaml.ci.dev/github/koonwen/ocaml-libbpf)
 
 # ocaml-libbpf
-Libbpf C-bindings for eBPF userspace programs.
+Libbpf C-bindings for loading eBPF ELF files into the kernel.
 
 Writing eBPF programs consist of two distinct parts. Implementing the
 code that executes in-kernel **and** user-level code responsible for
@@ -12,16 +12,23 @@ the raw low-level bindings as well as a set of high-level API's for
 handling your eBPF objects. As of now, the kernel part must still be
 written in [restricted
 C](https://stackoverflow.com/questions/57688344/what-is-not-allowed-in-restricted-c-for-ebpf)
-and compiled to eBPF bytecode.
+and compiled with llvm to eBPF bytecode.
 
 The full API set of Libbpf is quite large, see [supported](supported.json) for the list
 of currently bound API's. Contributions are welcome.
 
+### External dependencies
+ocaml\_libbpf depends on the system package of `libbpf`. This is
+automatically installed along with ocaml_libbpf
+
 # Usage
-See `examples` directory on how ocaml\_libbpf can be used to interact
-with eBPF kernel programs defined in *.bpf.c source files. The
-high-level API's provided in ocaml\_libbpf make it easy to perform
-repetitive tasks like open/load/linking/initializing/teardown.
+See `examples` directory on how ocaml\_libbpf can be used to load eBPF
+ELF files into the kernel and interact with the loaded kernel program.
+The eBPF kernel programs are defined in *.bpf.c source files and are
+compiled with clang as specified in the `dune` rules. ocaml\_libbpf
+exposes some high-level API's provided in ocaml\_libbpf make it easy
+to perform repetitive tasks like
+open/load/linking/initializing/teardown.
 
 To run these examples, clone this repository and set up the package with
 ```bash
@@ -31,17 +38,31 @@ opam install . --deps-only
 eval $(opam env)
 ```
 
-then use `make <minimal/kprobe/bootstrap>`. These examples are taken
-from [libbpf-bootstrap](https://github.com/libbpf/libbpf-bootstrap)
+then run `make < minimal | kprobe | bootstrap | tc >` to try out the
+different bpf programs. These examples are all taken from
+[libbpf-bootstrap](https://github.com/libbpf/libbpf-bootstrap)
 repository and rewritten in OCaml.
 
 ### Open/Load/Link
 Now let's run through an example of how we would use
 ocaml\_libbpf. This usage tutorial assumes some knowledge of how to
-write eBPF programs in C. If not, you can check out this
+write eBPF kernel programs in C compile them to ELF files. If not, you
+can check out this
 [resource](https://nakryiko.com/posts/libbpf-bootstrap/#the-bpf-side). ocaml\_libbpf
 provides an easy API to install your eBPF program into the kernel. Say
-your eBPF kernel program looks like this.
+your eBPF kernel program looks like this where we print something
+whenever the syscall `write` event occurs. We also want to implement a
+filtering mechanism to only print on `write` calls for our process. To
+do this, we initialize a BPF array map with a single entry that works
+like a holder for our global variable. The BPF map is neccessary to
+because it allows us to communicate values between user and kernel
+space.
+
+> libbpf in fact already supports declarations of global variables in
+> the usual form with the ability to manage them in user
+> space. However for various technical reasons, ocaml\_libbpf does not
+> enable that feature yet. So we use the old style of working with
+> global variables here.
 
 ```c
 // SPDX-License-Identifier: GPL-2.0 OR BSD-3-Clause
@@ -82,24 +103,49 @@ int handle_tp(void *ctx) {
 
 ```
 
-Users just need to provide the path to the compiled bpf
-object, the name of the program and optionally an initialization
-function.
+After compilation to eBPF ELF file as `minimal.o`. Users just need to
+provide the path to this ELF file along with the name of the program
+and optionally an initialization function. Note that the name of the
+program refers to the function identifier under the SEC(...)
+attribute, in this case it is "handle_tp".
 
 ```ocaml
 let obj_path = "minimal.bpf.o"
 let program_names = [ "handle_tp" ]
-let map = "globals"
 
-(* Load PID into BPF map*)
-let before_link obj =
-  let pid = Unix.getpid () |> Signed.Long.of_int in
-  let global_map = bpf_object_find_map_by_name obj map in
-  bpf_map_update_elem ~key_ty:Ctypes.int ~val_ty:Ctypes.long global_map 0 pid
+let () =
+  with_bpf_object_open_load_link ~obj_path ~program_names ~before_link
+    (fun obj link ->
+
+	< user code to interact with bpf program running in kernel >
+
+	)
+```
+
+The API provided by ocaml\_libbpf `with_bpf_object_open_load_link` is
+a context manager that ensures the proper cleanup of resources if a
+failure is encountered. Right now our loaded kernel program is
+attached to the kernel and then immediately unloaded, users are
+responsible for keeping the bpf program alive by looping within the
+function block.
+
+> Users may also pin the bpf program to persist after user code
+> exits. Do note that if pinning is desired, users should not use the
+> `with_bpf_object_open_load_link` API and instead manually load and
+> attach their bpf program since the context manager shutdowns all
+> resources on exit.
+
+Now let's add some looping logic to keep the loaded bpf program alive.
+
+```ocaml
+let obj_path = "minimal.bpf.o"
+let program_names = [ "handle_tp" ]
 
 let () =
   with_bpf_object_open_load_link ~obj_path ~program_names ~before_link
-    (fun _obj _link ->
+    (fun obj link ->
+
+	(* Set up signal handlers *)
       let exitting = ref true in
       let sig_handler = Sys.Signal_handle (fun _ -> exitting := false) in
       Sys.(set_signal sigint sig_handler);
@@ -109,26 +155,44 @@ let () =
         "Successfully started! Please run `sudo cat \
          /sys/kernel/debug/tracing/trace_pipe` to see output of the BPF \
          programs.\n\
-         %!";
+         %!"
 
-      (* Loop until Ctrl-C is called *)
+    (* Loop until Ctrl-C is called *)
       while !exitting do
         Printf.eprintf ".%!";
         Unix.sleepf 1.0
       done)
 ```
 
+Our bpf program is now running in the kernel until we decide to
+interrupt it. However, it doesn't do exactly what we want. In
+particular, it doesn't filter for our process PID. This is because we
+haven't loaded our process PID into the BPF map. To do this, we need
+the name of the map we declared in the `minimal.bpf.c` program. In
+this case, our BPF array map was named `globals`.
+
+```ocaml
+let map = "globals"
+
+(* Load PID into BPF map *)
+let before_link obj =
+  let pid = Unix.getpid () |> Signed.Long.of_int in
+  let global_map = bpf_object_find_map_by_name obj map in
+  (* When updating an element, users need to specify the type of the key and value
+     declared by the map which checks that the key and value size are consistent. *)
+  bpf_map_update_elem ~key_ty:Ctypes.int ~val_ty:Ctypes.long global_map 0 pid
+```
+
+Put together in [minimal.ml](./examples/minimal.ml), your bpf program
+runs in kernel and print to the trace pipe every second.
+
 ### Maps
 `ocaml_libbpf_maps` is an optional convenience package that provides
 wrappers for BPF maps. Currently only Ringbuffer maps are added. An
 example usage of them can be found in
 [examples/bootstrap.ml](./examples/bootstrap.ml). This has been
 packaged separately since it drags in `libffi` dependency.
 
-### External dependencies
-ocaml\_libbpf depends on the system package of `libbpf`. This is
-automatically installed along with ocaml_libbpf
-
 ## Notes on compatibility
 > Libbpf is designed to be kernel-agnostic and work across multitude
 > of kernel versions. It has built-in mechanisms to gracefully handle
