|
| 1 | +# LIBREX |
| 2 | + |
| 3 | +`librex` serves as the loader library for Rex programs -- similar to what |
| 4 | +`libbpf` is to eBPF programs -- but in a simpler way. |
| 5 | + |
| 6 | +### APIs |
| 7 | + |
| 8 | +`librex` only contains the code that loads Rex programs from ELF binaries, |
| 9 | +other operations (e.g., attachment, map manipulation, etc) are delegated to |
| 10 | +the existing code in `libbpf`. |
| 11 | + |
| 12 | +Therefore, the library only exposes the following simple APIs: |
| 13 | +```c |
| 14 | +struct rex_obj *rex_obj_load(const char *file_path); |
| 15 | +struct bpf_object *rex_obj_get_bpf(struct rex_obj *obj); |
| 16 | +void rex_set_debug(int val); |
| 17 | +``` |
| 18 | +
|
| 19 | +The `rex_obj_load` function loads the Rex programs from the ELF binary |
| 20 | +identified by the `file_path` argument into the kernel. It returns a |
| 21 | +pointer to the corresponding `rex_obj` that encapsulates information about |
| 22 | +the loaded programs and created maps. If there is an error, a null pointer |
| 23 | +is returned. |
| 24 | +
|
| 25 | +The `rex_obj_get_bpf` returns a pointer to the equivalent `bpf_object` of |
| 26 | +the `obj` argument, which can be subsequently passed to `libbpf` APIs. If |
| 27 | +there is an error, a null pointer is returned. |
| 28 | +
|
| 29 | +**Note**: The returned pointer from both functions above are **non-owning** |
| 30 | +pointers, which means the caller of these function should not try to |
| 31 | +`free`/`realloc`/`delete` the pointer. The ownership of the pointers is |
| 32 | +managed by `librex` internally and will be automatically freed after the |
| 33 | +program terminates. |
| 34 | +
|
| 35 | +The `rex_set_debug` function can be used to toggle the internal logging |
| 36 | +mechanism of `librex` (with `(bool)val` determining whether logging is |
| 37 | +enabled). This will most likely be helpful during debugging. |
| 38 | +
|
| 39 | +### Build |
| 40 | +
|
| 41 | +Building `librex` requires a `c++23` compatible compiler and the `mold` |
| 42 | +linker. With dependencies installed, simply invoke the Makefile: |
| 43 | +
|
| 44 | +```bash |
| 45 | +make |
| 46 | +``` |
0 commit comments