Update README to include responsive image support

Updated README with improved descriptions and badges.

.github/workflows/format.yml

@@ -15,8 +15,8 @@ jobs:
     name: Format
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
-    - uses: actions/setup-python@v5
+    - uses: actions/setup-python@v6
       with:
         python-version: "3.x"
     - uses: pre-commit/action@v3.0.1

.github/workflows/pip.yml

@@ -19,11 +19,11 @@ jobs:
     runs-on: ${{ matrix.platform }}
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
       with:
         submodules: true
 
-    - uses: actions/setup-python@v5
+    - uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
 

.github/workflows/wheels.yml

@@ -15,7 +15,7 @@ jobs:
     name: Build SDist
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
       with:
         submodules: true
 
@@ -39,12 +39,12 @@ jobs:
         arch: [x86_64]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
       with:
         submodules: true
 
     - name: Build wheels
-      uses: pypa/cibuildwheel@v2.17
+      uses: pypa/cibuildwheel@v3.2
       env:
         CIBW_PLATFORM: linux
         CIBW_ARCHS_LINUX: ${{ matrix.arch }}
@@ -80,7 +80,7 @@ jobs:
 
     steps:
     - name: Download all artifacts
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v5
       with:
         pattern: cibw-*
         path: dist

.gitignore

@@ -9,3 +9,4 @@ _generate/
 build/
 *venv/
 .idea/
+sudo-python.sh

CMakeLists.txt

@@ -4,8 +4,14 @@ project(pylibbpf)
 # pybind11
 include_directories(${CMAKE_SOURCE_DIR}/src)
 add_subdirectory(pybind11)
-pybind11_add_module(pylibbpf src/core/bpf_program.h src/core/bpf_exception.h
+pybind11_add_module(
-                    src/bindings/main.cpp src/core/bpf_program.cpp)
+  pylibbpf
+  src/core/bpf_program.h
+  src/core/bpf_exception.h
+  src/core/bpf_map.h
+  src/bindings/main.cpp
+  src/core/bpf_program.cpp
+  src/core/bpf_map.cpp)
 
 # --- libbpf build rules ---
 set(LIBBPF_SRC_DIR ${CMAKE_CURRENT_SOURCE_DIR}/libbpf/src)

MANIFEST.in

@@ -1,8 +1,7 @@
 include README.md LICENSE pybind11/LICENSE
 graft pybind11/include
 graft pybind11/tools
-recursive-include src *.cpp *.h
+include LICENSE
-recursive-include libbpf/src *.c *.h Makefile
-recursive-include libbpf/include *.h
 graft src
+graft libbpf
 global-include CMakeLists.txt *.cmake

README.md

@@ -1,24 +1,47 @@
-# Py-libbpf
+<picture>
-This library provides Python bindings for libbpf on Linux to make loading of eBPF object files easier. This is meant to
+  <source
-be used along with `pythonbpf`, the eBPF Python DSL compiler. This library makes it possible to attach these programs to
+    media="(prefers-color-scheme: light)"
-events in the kernel right from inside Python.
+    srcset="https://github.com/user-attachments/assets/dbd56f5b-4512-4c82-a404-30bce0ee5207"
+    width="450"
+    alt="pylibbpf light mode">
+  <img
+    src="https://github.com/user-attachments/assets/9e873d60-a834-4411-bc0c-361b14502f8b"
+    width="450"
+    alt="pylibbpf dark mode">
+</picture>
+<p align="center">
+  <!-- PyPI -->
+  <a href="https://www.python.org/downloads/release/python-3080/"><img src="https://img.shields.io/badge/python-3.8-blue.svg"></a>
+  <a href="https://pypi.org/project/pylibbpf"><img src="https://badge.fury.io/py/pylibbpf.svg"></a>
+  <!-- <a href="https://pypi.org/project/pythonbpf/"><img src="https://img.shields.io/pypi/status/pythonbpf" alt="PyPI Status"></a> -->
+  <a href="https://pepy.tech/project/pylibbpf"><img src="https://pepy.tech/badge/pylibbpf" alt="Downloads"></a>
+  <!-- Build & CI -->
+  <a href="https://github.com/pythonbpf/pylibbpf/actions"><img src="https://github.com/pythonbpf/pylibbpf/actions/workflows/wheels.yml/badge.svg" alt="Build Status"></a>
+  <!-- Meta -->
+  <a href="https://github.com/pythonbpf/pylibbpf/blob/master/LICENSE"><img src="https://img.shields.io/github/license/pythonbpf/pylibbpf" alt="License"></a>
+</p>
 
-# Warning
+This library provides Python bindings for **libbpf** on Linux, making it easier to load eBPF object files. It is designed to be used together with [PythonBPF](https://github.com/pythonbpf/python-bpf), the eBPF compiler for Python. With these bindings, you can attach eBPF programs to kernel events directly from Python.
-IN DEVELOPMENT. DO NOT USE.
+All programs written with this are to be run with a `sudo` Python interpreter.
 
-## Prerequisites
+> **Note**: This project is under active development and not ready for production use.
+
+## Dependencies
 
 * A compiler with C++11 support
 * Pip 10+ or CMake >= 4.1
 * Ninja or Pip 10+
 
-
 ## Installation
+`pip install pylibbpf`
 
-Just clone this repository and pip install. Note the `--recursive` option which is
+## Development
+
+Clone this repository and pip install. Note the `--recursive` option which is
 needed for the pybind11 submodule:
 
 ```bash
+sudo apt install libelf-dev
 git clone --recursive https://github.com/varun-r-mallya/pylibbpf.git
 pip install .
 ```

examples/execve.py

@@ -0,0 +1,54 @@
+import time
+from ctypes import c_int32, c_int64, c_uint64, c_void_p
+
+from pylibbpf import BpfMap
+from pythonbpf import BPF, bpf, bpfglobal, map, section
+from pythonbpf.maps import HashMap
+
+
+@bpf
+@map
+def last() -> HashMap:
+    return HashMap(key=c_uint64, value=c_uint64, max_entries=3)
+
+
+@bpf
+@section("tracepoint/syscalls/sys_enter_execve")
+def hello(ctx: c_void_p) -> c_int32:
+    print("entered")
+    print("multi constant support")
+    return c_int32(0)
+
+
+@bpf
+@section("tracepoint/syscalls/sys_exit_execve")
+def hello_again(ctx: c_void_p) -> c_int64:
+    print("exited")
+    key = 0
+    tsp = last().lookup(key)
+    print(tsp)
+    return c_int64(0)
+
+
+@bpf
+@bpfglobal
+def LICENSE() -> str:
+    return "GPL"
+
+
+b = BPF()
+b.load_and_attach()
+mp = BpfMap(b, last)
+mp[42] = 100  # Update entry
+value = mp[42]  # Lookup entry
+del mp[42]  # Delete entry
+mp[69] = 420
+mp[31] = 42
+mp[21] = 34
+print(mp.items())
+# Iterate through map
+for key in mp.keys():
+    print(mp[key])
+while True:
+    print("running")
+    time.sleep(1)

pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pylibbpf"
-version = "0.0.2"
+version = "0.0.5"
 description = "Python Bindings for Libbpf"
 authors = [
     { name = "r41k0u", email = "pragyanshchaturvedi18@gmail.com" },
@@ -69,9 +69,9 @@ line-length = 88
 
 [tool.ruff.lint]
 extend-select = [
-    "B",    # flake8-bugbear
+    "B", # flake8-bugbear
-    "I",    # isort
+    "I", # isort
-    "PGH",  # pygrep-hooks
+    "PGH", # pygrep-hooks
-    "RUF",  # Ruff-specific
+    "RUF", # Ruff-specific
-    "UP",   # pyupgrade
+    "UP", # pyupgrade
 ]

src/bindings/main.cpp

@@ -3,10 +3,12 @@
 #define MACRO_STRINGIFY(x) STRINGIFY(x)
 
 extern "C" {
-#include "libbpf.h"
+#include <libbpf.h>
 }
+
 #include "core/bpf_program.h"
 #include "core/bpf_exception.h"
+#include "core/bpf_map.h"
 
 namespace py = pybind11;
 
@@ -21,6 +23,7 @@ PYBIND11_MODULE(pylibbpf, m) {
            :toctree: _generate
 
            BpfProgram
+           BpfMap
            BpfException
     )pbdoc";
 
@@ -28,13 +31,33 @@ PYBIND11_MODULE(pylibbpf, m) {
     py::register_exception<BpfException>(m, "BpfException");
 
     py::class_<BpfProgram>(m, "BpfProgram")
-     .def(py::init<const std::string&>())
+            .def(py::init<const std::string &>())
-     .def(py::init<const std::string&, const std::string&>())
+            .def(py::init<const std::string &, const std::string &>())
-     .def("load", &BpfProgram::load)
+            .def("load", &BpfProgram::load)
-     .def("attach", &BpfProgram::attach)
+            .def("attach", &BpfProgram::attach)
-     // .def("detach", &BpfProgram::detach)
+            .def("destroy", &BpfProgram::destroy)
-     .def("is_loaded", &BpfProgram::is_loaded)
+            .def("load_and_attach", &BpfProgram::load_and_attach)
-     .def("is_attached", &BpfProgram::is_attached);
+            .def("is_loaded", &BpfProgram::is_loaded)
+            .def("is_attached", &BpfProgram::is_attached);
+
+    py::class_<BpfMap>(m, "BpfMap")
+            .def(py::init<BpfProgram *, py::object &>())
+            .def("lookup", &BpfMap::lookup)
+            .def("update", &BpfMap::update)
+            .def("delete", &BpfMap::delete_elem)
+            .def("get_next_key", &BpfMap::get_next_key, py::arg("key") = py::none())
+            .def("items", &BpfMap::items)
+            .def("keys", &BpfMap::keys)
+            .def("values", &BpfMap::values)
+            .def("get_name", &BpfMap::get_name)
+            .def("get_type", &BpfMap::get_type)
+            .def("get_key_size", &BpfMap::get_key_size)
+            .def("get_value_size", &BpfMap::get_value_size)
+            .def("get_max_entries", &BpfMap::get_max_entries)
+            .def("__getitem__", &BpfMap::lookup)
+            .def("__setitem__", &BpfMap::update)
+            .def("__delitem__", &BpfMap::delete_elem);
+
 
 #ifdef VERSION_INFO
     m.attr("__version__") = MACRO_STRINGIFY(VERSION_INFO);

src/core/bpf_exception.h

@@ -6,11 +6,13 @@
 
 class BpfException final : public std::runtime_error {
 public:
-    explicit BpfException(const std::string& message)
+    explicit BpfException(const std::string &message)
-        : std::runtime_error(message) {}
+        : std::runtime_error(message) {
+    }
 
-    explicit BpfException(const char* message)
+    explicit BpfException(const char *message)
-        : std::runtime_error(message) {}
+        : std::runtime_error(message) {
+    }
 };
 
 #endif // PYLIBBPF_BPF_EXCEPTION_H

src/core/bpf_map.cpp

@@ -0,0 +1,211 @@
+#include "bpf_map.h"
+
+#include "bpf_exception.h"
+
+BpfMap::BpfMap(BpfProgram *program_, const py::object &map_from_python) {
+    if (py::isinstance<py::function>(map_from_python)) {
+        const auto name = map_from_python.attr("__name__").cast<std::string>();
+        bpf_program = program_;
+        map_ = bpf_object__find_map_by_name(bpf_program->get_obj(), name.c_str());
+        if (!map_) {
+            throw BpfException("Failed to find map by name");
+        }
+        map_fd = bpf_map__fd(map_);
+        if (map_fd == -1) {
+            throw BpfException("Failed to open map File Descriptor");
+        }
+    } else {
+        throw BpfException("Invalid map object passed to function.");
+    }
+}
+
+std::vector<uint8_t> BpfMap::python_to_bytes(const py::object &obj, size_t size) {
+    std::vector<uint8_t> result(size, 0);
+
+    if (py::isinstance<py::int_>(obj)) {
+        const auto value = obj.cast<uint64_t>();
+        std::memcpy(result.data(), &value, std::min(size, sizeof(uint64_t)));
+    } else if (py::isinstance<py::bytes>(obj)) {
+        const auto bytes_str = obj.cast<std::string>();
+        std::memcpy(result.data(), bytes_str.data(), std::min(size, bytes_str.size()));
+    } else if (py::isinstance<py::str>(obj)) {
+        const auto str_val = obj.cast<std::string>();
+        std::memcpy(result.data(), str_val.data(), std::min(size, str_val.size()));
+    }
+
+    return result;
+}
+
+py::object BpfMap::bytes_to_python(const std::vector<uint8_t> &data) {
+    // Try to interpret as integer if it's a common integer size
+    if (data.size() == 4) {
+        uint32_t value;
+        std::memcpy(&value, data.data(), 4);
+        return py::cast(value);
+    } else if (data.size() == 8) {
+        uint64_t value;
+        std::memcpy(&value, data.data(), 8);
+        return py::cast(value);
+    } else {
+        // Return as bytes
+        return py::bytes(reinterpret_cast<const char *>(data.data()), data.size());
+    }
+}
+
+void BpfMap::update(const py::object &key, const py::object &value) const {
+    const size_t key_size = bpf_map__key_size(map_);
+    const size_t value_size = bpf_map__value_size(map_);
+
+    const auto key_bytes = python_to_bytes(key, key_size);
+    const auto value_bytes = python_to_bytes(value, value_size);
+
+    const int ret = bpf_map__update_elem(
+        map_,
+        key_bytes.data(),
+        key_size,
+        value_bytes.data(),
+        value_size,
+        BPF_ANY);
+    if (ret != 0) {
+        throw BpfException("Failed to update map element");
+    }
+}
+
+void BpfMap::delete_elem(const py::object &key) const {
+    const size_t key_size = bpf_map__key_size(map_);
+    std::vector<uint8_t> key_bytes;
+    key_bytes = python_to_bytes(key, key_size);
+
+    if (const int ret = bpf_map__delete_elem(map_, key_bytes.data(), key_size, BPF_ANY); ret != 0) {
+        throw BpfException("Failed to delete map element");
+    }
+}
+
+py::list BpfMap::get_next_key(const py::object &key) const {
+    const size_t key_size = bpf_map__key_size(map_);
+    std::vector<uint8_t> next_key(key_size);
+
+    int ret;
+    if (key.is_none()) {
+        ret = bpf_map__get_next_key(map_, nullptr, next_key.data(), key_size);
+    } else {
+        const auto key_bytes = python_to_bytes(key, key_size);
+        ret = bpf_map__get_next_key(map_, key_bytes.data(), next_key.data(), key_size);
+    }
+
+    py::list result;
+    if (ret == 0) {
+        result.append(bytes_to_python(next_key));
+    }
+    return result;
+}
+
+py::list BpfMap::keys() const {
+    py::list result;
+    const size_t key_size = bpf_map__key_size(map_);
+
+    std::vector<uint8_t> key(key_size);
+    std::vector<uint8_t> next_key(key_size);
+
+    int ret = bpf_map__get_next_key(map_, nullptr, key.data(), key_size);
+
+    while (ret == 0) {
+        result.append(bytes_to_python(key));
+        ret = bpf_map__get_next_key(map_, key.data(), next_key.data(), key_size);
+        key = next_key;
+    }
+
+    return result;
+}
+
+py::list BpfMap::values() const {
+    py::list result;
+    const size_t key_size = bpf_map__key_size(map_);
+    const size_t value_size = bpf_map__value_size(map_);
+
+    std::vector<uint8_t> key(key_size);
+    std::vector<uint8_t> next_key(key_size);
+    std::vector<uint8_t> value(value_size);
+
+    int ret = bpf_map__get_next_key(map_, nullptr, key.data(), key_size);
+
+    while (ret == 0) {
+        if (bpf_map__lookup_elem(map_, key.data(), key_size, value.data(), value_size, BPF_ANY) == 0) {
+            result.append(bytes_to_python(value));
+        }
+        ret = bpf_map__get_next_key(map_, key.data(), next_key.data(), key_size);
+        key = next_key;
+    }
+
+    return result;
+}
+
+std::string BpfMap::get_name() const {
+    const char *name = bpf_map__name(map_);
+    return name ? std::string(name) : "";
+}
+
+int BpfMap::get_type() const {
+    return bpf_map__type(map_);
+}
+
+int BpfMap::get_key_size() const {
+    return bpf_map__key_size(map_);
+}
+
+int BpfMap::get_value_size() const {
+    return bpf_map__value_size(map_);
+}
+
+int BpfMap::get_max_entries() const {
+    return bpf_map__max_entries(map_);
+}
+
+py::dict BpfMap::items() const {
+    py::dict result;
+    const size_t key_size = bpf_map__key_size(map_);
+    const size_t value_size = bpf_map__value_size(map_);
+
+    std::vector<uint8_t> key(key_size);
+    std::vector<uint8_t> next_key(key_size);
+    std::vector<uint8_t> value(value_size);
+
+    // Get first key
+    int ret = bpf_map__get_next_key(map_, nullptr, key.data(), key_size);
+
+    while (ret == 0) {
+        // Lookup value for current key
+        if (bpf_map__lookup_elem(map_, key.data(), key_size, value.data(), value_size, BPF_ANY) == 0) {
+            result[bytes_to_python(key)] = bytes_to_python(value);
+        }
+
+        // Get next key
+        ret = bpf_map__get_next_key(map_, key.data(), next_key.data(), key_size);
+        key = next_key;
+    }
+
+    return result;
+}
+
+py::object BpfMap::lookup(const py::object &key) const {
+    const __u32 key_size = bpf_map__key_size(map_);
+    const __u32 value_size = bpf_map__value_size(map_);
+
+    const auto key_bytes = python_to_bytes(key, key_size);
+    std::vector<uint8_t> value_bytes(value_size);
+
+    // The flags field here matters only when spin locks are used which is close to fucking never, so fuck no,
+    // im not adding it
+    const int ret = bpf_map__lookup_elem(
+        map_,
+        key_bytes.data(),
+        key_size,
+        value_bytes.data(),
+        value_size,
+        BPF_ANY);
+    if (ret != 0) {
+        return py::none();
+    }
+
+    return bytes_to_python(value_bytes);
+}

src/core/bpf_map.h

@@ -0,0 +1,55 @@
+#ifndef PYLIBBPF_MAPS_H
+#define PYLIBBPF_MAPS_H
+
+#include <libbpf.h>
+#include <pybind11/pybind11.h>
+#include <vector>
+#include <string>
+
+#include "bpf_program.h"
+
+namespace py = pybind11;
+
+class BpfMap {
+private:
+    struct bpf_map *map_;
+    int map_fd = -1;
+    //TODO: turn below into a shared pointer and ref count it so that there is no resource leakage
+    BpfProgram *bpf_program;
+
+public:
+    BpfMap(BpfProgram *program_, const py::object &map_from_python);
+
+    ~BpfMap() = default;
+
+    [[nodiscard]] py::object lookup(const py::object &key) const;
+
+    void update(const py::object &key, const py::object &value) const;
+
+    void delete_elem(const py::object &key) const;
+
+    py::list get_next_key(const py::object &key = py::none()) const;
+
+    py::dict items() const;
+
+    py::list keys() const;
+
+    py::list values() const;
+
+    [[nodiscard]] std::string get_name() const;
+
+    int get_type() const;
+
+    int get_key_size() const;
+
+    int get_value_size() const;
+
+    int get_max_entries() const;
+
+private:
+    static std::vector<uint8_t> python_to_bytes(const py::object &obj, size_t size);
+
+    static py::object bytes_to_python(const std::vector<uint8_t> &data);
+};
+
+#endif //PYLIBBPF_MAPS_H

src/core/bpf_program.cpp

@@ -1,19 +1,24 @@
 #include "bpf_program.h"
 #include "bpf_exception.h"
 #include <filesystem>
+#include <utility>
 
-BpfProgram::BpfProgram(const std::string& object_path, const std::string& program_name)
+BpfProgram::BpfProgram(std::string object_path, std::string program_name)
     : obj_(nullptr), prog_(nullptr), link_(nullptr),
-      object_path_(object_path), program_name_(program_name) {
+      object_path_(std::move(object_path)), program_name_(std::move(program_name)) {
 }
 
 BpfProgram::~BpfProgram() {
-    //TODO: detach here as well
+    destroy();
     if (obj_) {
         bpf_object__close(obj_);
     }
 }
 
+struct bpf_object * BpfProgram::get_obj() const {
+    return obj_;
+}
+
 bool BpfProgram::load() {
     // Open the eBPF object file
     obj_ = bpf_object__open_file(object_path_.c_str(), nullptr);
@@ -28,9 +33,12 @@ bool BpfProgram::load() {
             throw BpfException("Program '" + program_name_ + "' not found in object");
         }
     } else {
-        // Use the first program if no name specified
+        while ((prog_ = bpf_object__next_program(obj_, prog_)) != nullptr) {
-        prog_ = bpf_object__next_program(obj_, nullptr);
+            programs.emplace_back(prog_, nullptr);
-        if (!prog_) {
+        }
+
+        // throw if no programs found
+        if (programs.empty()) {
             throw BpfException("No programs found in object file");
         }
     }
@@ -44,15 +52,33 @@ bool BpfProgram::load() {
 }
 
 bool BpfProgram::attach() {
-    if (!prog_) {
+    for (auto [prog, link]: programs) {
-        throw BpfException("Program not loaded");
+        if (!prog) {
-    }
+            throw BpfException("Program not loaded");
+        }
 
-    link_ = bpf_program__attach(prog_);
+        link = bpf_program__attach(prog);
-    if (libbpf_get_error(link_)) {
+        if (libbpf_get_error(link)) {
-        link_ = nullptr;
+            link = nullptr;
-        throw BpfException("Failed to attach BPF program");
+            throw BpfException("Failed to attach BPF program");
+        }
     }
 
     return true;
 }
+
+bool BpfProgram::destroy() {
+    bool success = true;
+    for (auto [prog, link]: programs) {
+        if (!prog) {
+            throw BpfException("Program not loaded");
+        }
+        success = success & bpf_link__destroy(link);
+    }
+    return success;
+}
+
+void BpfProgram::load_and_attach() {
+    load();
+    attach();
+}

src/core/bpf_program.h

@@ -1,7 +1,7 @@
 #ifndef PYLIBBPF_BPF_PROGRAM_H
 #define PYLIBBPF_BPF_PROGRAM_H
 
-#include "libbpf.h"
+#include <libbpf.h>
 #include <pybind11/stl.h>
 #include <string>
 
@@ -9,21 +9,30 @@ namespace py = pybind11;
 
 class BpfProgram {
 private:
-    struct bpf_object* obj_;
+    struct bpf_object *obj_;
-    struct bpf_program* prog_;
+    struct bpf_program *prog_;
-    struct bpf_link* link_;
+    struct bpf_link *link_;
     std::string object_path_;
     std::string program_name_;
+    std::vector<std::pair<bpf_program *, bpf_link *> > programs;
 
 public:
-    explicit BpfProgram(const std::string& object_path, const std::string& program_name = "");
+    explicit BpfProgram(std::string object_path, std::string program_name = "");
+
     ~BpfProgram();
 
+    struct bpf_object *get_obj() const;
+
     bool load();
+
     bool attach();
 
-    bool is_loaded() const { return obj_ != nullptr; }
+    bool destroy();
-    bool is_attached() const { return link_ != nullptr; }
+
+    void load_and_attach();
+
+    [[nodiscard]] bool is_loaded() const { return obj_ != nullptr; }
+    [[nodiscard]] bool is_attached() const { return link_ != nullptr; }
 };
 
 #endif //PYLIBBPF_BPF_PROGRAM_H

tests/test_basic.py

@@ -2,6 +2,6 @@ import pylibbpf as m
 
 
 def test_main():
-    assert m.__version__ == "0.0.1"
+    assert m.__version__ == "0.0.5"
     prog = m.BpfProgram("tests/execve2.o")
     print(prog)