{"id":26153968,"url":"https://github.com/SzymonKubica/micro-bpf","last_synced_at":"2025-03-11T08:03:03.718Z","repository":{"id":219821478,"uuid":"744236244","full_name":"SzymonKubica/micro-bpf","owner":"SzymonKubica","description":"µBPF - a framework for microcontroller compartmentalization using eBPF","archived":false,"fork":false,"pushed_at":"2024-06-20T18:10:49.000Z","size":80691,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-06-21T02:52:16.657Z","etag":null,"topics":["compartmentalization","ebpf","embedded-systems","fault-isolation","internet-of-things","microcontrollers","middleware","virtual-machine"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SzymonKubica.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-16T22:11:12.000Z","updated_at":"2024-06-21T02:52:18.793Z","dependencies_parsed_at":"2024-03-09T11:30:21.500Z","dependency_job_id":"a391dbd1-3cc1-4705-973f-f26c3f9685ac","html_url":"https://github.com/SzymonKubica/micro-bpf","commit_stats":null,"previous_names":["szymonkubica/mibpf","szymonkubica/micro-bpf"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SzymonKubica%2Fmicro-bpf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SzymonKubica%2Fmicro-bpf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SzymonKubica%2Fmicro-bpf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SzymonKubica%2Fmicro-bpf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SzymonKubica","download_url":"https://codeload.github.com/SzymonKubica/micro-bpf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242995900,"owners_count":20218828,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["compartmentalization","ebpf","embedded-systems","fault-isolation","internet-of-things","microcontrollers","middleware","virtual-machine"],"created_at":"2025-03-11T08:02:11.151Z","updated_at":"2025-03-11T08:03:03.684Z","avatar_url":"https://github.com/SzymonKubica.png","language":"Rust","funding_links":[],"categories":["BPF and eBPF Projects"],"sub_categories":["Notes"],"readme":"# µBPF\n\n\u003cpicture\u003e\n  \u003cimg src=\"examples/docs/logo-square-shadow-dark.png\" width=\"150\"\u003e\n\u003c/picture\u003e\n\nUsing eBPF for microcontroller compartmentalization.\n\n* [Description](#description)\n* [Project directory structure](#project-directory-structure)\n* [System architecture and programming model](#system-architecture-and-programming-model)\n* [Deployment workflow](#deployment-workflow)\n* [Getting started](#getting-started)\n*  [Detailed overview](#detailed-overview)\n\n\n## Description\n\nThis repository contains an end-to-end system for deploying and executing\neBPF programs on embedded devices.\n\n`micro-bpf` consists of an eBPF virtual machine (VM), a just-in-time (JIT)\ncompiler targeting the ARMv7-eM architecture, server infrastructure compatible\nwith RIOT and a set of tools allowing to send eBPF program logic to\nmicrocontroller devices and execute it there.\n\neBPF (extended Berkeley Packet Filter) is an instruction set architecture (ISA)\nused in the Linux kernel to allow for executing custom user-defined code inside\nof the kernel in a safe way. Although originally eBPF was intended to run in the\nkernel, it can be used as a general-purposed fault isolation technology.\n\nBecause of its simplicity and support for program verification, eBPF can be\nused in the context of embedded devices to provide a container-like environment\nfor sandboxed execution similar to docker.\n\nThe general idea is to compile programs written in a constrained subset of C\n(or any other compatible front end) into eBPF bytecode and then send the\nbytecode instructions to the target embedded device where they can later be\nexecuted in an isolated VM envrionment. This allows for isolating the\nunderlying system from the code running in the VM. Additionally, being able to\nload arbitrary programs means that the business logic deployed on the target\ndevices can be updated over-the-air without the need to reboot/reflash the\nmicrocontroller.\n\n## Project directory structure\n\n`micro-bpf` repository consists of four main components:\n\n- `RIOT` - a fork of RIOT - a popular operating system used in IoT applications\n   it is used as the host OS on top of which runs the server infrastructure responsible\n   for loading, managing and executing programs.\n- `micro-bpf-server` - the server infrastructure that needs to be flashed onto the\n   target devices, it contains a CoAP server used to communicate with the device\n   and modules responsible for loading, verifying and executing eBPF code.\n- `tools` - a suite of tools allowing to compile, verify, cryptographically\n   sign and send eBPF programs to the deployed devices. It also provides a CLI\n   tool to control program deployment and request execution.\n- `vm` - the implementation of the eBPF VM used by `micro-bpf`, it contains a\n   fork of [`rbpf`](https://github.com/qmonnet/rbpf) and an implementation\n   of an eBPF-to-ARMv7 JIT compiler.\n\nThis repository also contains a set of example eBPF programs and applications\nbuilt on top of `micro-bpf`. Those are located under `examples`. Additionally,\na set of convenience scripts is provided in `scripts`.\n\n## System architecture and programming model\n\n### Deployment model\n\nµBPF divides the process of deploying eBPF programs into two steps: deployment\nstage and execution stage. The first stage involves compiling, verifying and\nloading the program into memory of the target device. After that, in the\nexecution stage, clients can send requests to run previously-deployed programs.\n\nTo learn how to send a deployment and execution request to the target device,\nrefer to the README of the [`tools`](https://github.com/SzymonKubica/micro-bpf-tools) submodule.\n\nThe deployment pipeline used by µBPF can be seen below.\n\n\u003cpicture\u003e\n  \u003cimg src=\"examples/docs/architecture-final-rev3-with-logo.png\" width=\"800\"\u003e\n\u003c/picture\u003e\n\nThe deployment pipeline of µBPF consists of four steps: compila- tion, signing,\nfirmware upload, and verification. Figure above shows the pipeline. Grey boxes\nrepresent existing infrastructure, whereas the contribution of µBPF is marked\nin blue.\n\n### Start of the pipeline\n\nAt the start of the the pipeline, source files in C are compiled into eBPF\nbytecode. After that follows an optional bytecode patching step required for\nbackwards compatibility with Femto-Containers. µBPF supports 4 different eBPF\nbinary formats so this step can be skipped and a raw object file can\nbe fed into the next step of the pipeline.\n\n### SUIT firmware update\n\nNext step involves sending the program binary to the target device using the\nSUIT update workflow provided by RIOT. First, the produced binaries are signed\nwith encryption keys matching the ones stored in the OS image running on the\ntarget device. Then, a manifest file is created and signed. It is then stored\ntogether with the program binary in the root directory of the CoAP fileserver.\nThe manifest provides information required by the target device to verify that\nthe loaded program has not been tampered with and originates from a trusted\nsource. The device then fetches the compiled eBPF bytecode and its manifest\nfile from the CoAP fileserver, verifies the signature and loads the program\ninto one of the RAM storage slots provided by the RIOT’s SUIT subsystem.\n\n### Execution stage\n\nAfter the deployment stage is complete, clients can begin sending requests to\nstart executing the loaded programs. Clients can choose between executing the\nprogram using the VM interpreter or using the JIT compiler and then executing\nthe emitted native code. After a given program is JIT-compiled, its bytecode is\nstored in an additional JIT program storage (see Figure 1). Upon receiving a\nrequest to rerun the program, the compilation process can be skipped. Here we\nnote that when using the JIT compiler additional memory is required as the\neBPF bytecode needs to be translated into the native instructions and written\ninto a new memory buffer. However, after this is done, the original eBPF\nprogram can be discarded allowing to save memory\n\n\u003cpicture\u003e\n  \u003cimg src=\"examples/docs/jit-storage.png\" width=\"600\"\u003e\n\u003c/picture\u003e\n\nFigure above illustrates how the µBPF JIT compiler gets access to one of the\nprogram buffers in the JIT program storage, translates the source eBPF program\ninto native machine code instructions and writes them into the buffer. After\nthat, the program is stored in the JIT-compiled program storage. It can then be\nretrieved and executed multiple times allowing to amortise the cost of JIT\ncompilation.\n\n## Getting started\n\n## Detailed overview\n\nA thorough documentation of the implementation process and an evaluation of\nthe system performance can be found in my Master's thesis [here](examples/docs/paper.pdf)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSzymonKubica%2Fmicro-bpf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSzymonKubica%2Fmicro-bpf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSzymonKubica%2Fmicro-bpf/lists"}