# zzu-andrew/ebpf architecture

> Architecture diagram of the GitHub repository zzu-andrew/ebpf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zzu-andrew/ebpf
- Repository: https://github.com/zzu-andrew/ebpf

## Overview

##### Main Components
- Library Core: Identify the core packages that make up the API:
- asm: Provides an assembler for writing eBPF assembly in Go.
- btf: Handles loading and parsing of the BPF Type Format data from the kernel.
- link: Manages attaching eBPF programs to kernel hooks.
- perf and ringbuf: Enable reading events and managing buffers from the kernel.
- rlimit: Adjusts resource limits (e.g., RLIMIT_MEMLOCK) before loading programs.
- pin: Wraps functionality for working with pinned objects on bpffs.
- Tooling:
- cmd/bpf2go: A command-line tool that compiles and auto-generates Go code for embedding eBPF programs written in C.
- Internal and Platform-Specific Modules:
- Various modules under internal/ (linux, epoll, kallsyms, etc.) that encapsulate low-level interactions with kernel syscalls and platform specifics.
- Examples and Documentation:
- The examples, docs, and test directories show how these components are used and provide integration samples.

##### Relationships and Interactions
- The API layer (the public packages) exposes functions that other applications integrate into long-running Go processes.
- The bpf2go tool takes in C source files for eBPF programs, invokes compilation, and generates Go bindings; these then interact with the lower-level libraries to load and control the programs.
- External users’ Go applications incorporate this library and call these components to manage eBPF programs, which then communicate with the kernel (and bpffs for pinned objects).

##### Architectural Patterns and Principles
- Layered Abstraction: Higher-level APIs (asm, link, bpf2go) rely on lower-level internal packages (internal/linux, internal/sys, etc.) to interact with kernel and system-level resources.

##### Technologies, Frameworks, and Libraries
- Go as the Core Language: Indicate that the entire library and tools are written in Go.
- Underlying C Toolchain: For compiling eBPF programs (via cmd/bpf2go) that uses clang or similar.
- Kernel Interfaces: The interaction with the Linux kernel (and bpffs) for loading and managing eBPF objects.
- CI/CD and Documentation: Although not central to the runtime, the CI workflows and documentation (docs directory, GitHub workflows) support ongoing collaboration and quality assurance.

##### Additional Detail
- Notes on the CI/CD and testing components if relevant—they demonstrate quality and architecture reliability.
- Mention that documentation and examples help in understanding the usage and integration, so a side note for “Examples & Docs” may be included.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Application
    ext["External Go Application"]:::external

    %% Tooling: bpf2go Command-line Tool
    bpf2go["bpf2go (C to Go binding tool)"]:::tool

    %% Public API / Library Core
    subgraph "Library Core"
        asm["asm (assembler)"]:::core
        btf["btf (BPF Type Format)"]:::core
        link["link (program attachment)"]:::core
        perf["perf (performance maps)"]:::core
        ringbuf["ringbuf (ring buffer reader)"]:::core
        rlimit["rlimit (resource limits)"]:::core
        pin["pin (pinned objects)"]:::core
    end

    %% Internal and Platform-Specific Modules
    internal["Internal Modules (platform-specific)"]:::internal

    %% Kernel and bpffs (System-level Interfaces)
    kernel["Kernel Interfaces"]:::kernel
    bpffs["bpffs (Pinned filesystem)"]:::kernel

    %% Documentation and Examples
    subgraph "Usage & Documentation"
        examples["Examples"]:::docs
        docs["Docs"]:::docs
    end

    %% Interactions
    ext -->|"uses"| asm
    ext -->|"uses"| btf
    ext -->|"uses"| link
    ext -->|"uses"| perf
    ext -->|"uses"| ringbuf
    ext -->|"uses"| rlimit
    ext -->|"uses"| pin

    bpf2go -->|"generates_bindings_for"| asm
    bpf2go -->|"generates_bindings_for"| btf
    bpf2go -->|"generates_bindings_for"| link

    asm -->|"relies_on"| internal
    btf -->|"relies_on"| internal
    link -->|"relies_on"| internal
    perf -->|"relies_on"| internal
    ringbuf -->|"relies_on"| internal
    rlimit -->|"relies_on"| internal
    pin -->|"relies_on"| internal

    link -->|"attaches_to"| kernel
    perf -->|"reads_from"| kernel
    ringbuf -->|"reads_from"| kernel
    pin -->|"interacts_with"| bpffs

    %% External usage of Documentation
    ext -->|"refers_to"| examples
    ext -->|"refers_to"| docs

    %% Styles
    classDef core fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef tool fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef internal fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef external fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef kernel fill:#DA70D6,stroke:#333,stroke-width:2px;
    classDef docs fill:#E0FFFF,stroke:#333,stroke-width:2px;

    %% Click Events
    click asm "https://github.com/zzu-andrew/ebpf/tree/main/asm/"
    click btf "https://github.com/zzu-andrew/ebpf/tree/main/btf/"
    click link "https://github.com/zzu-andrew/ebpf/tree/main/link/"
    click perf "https://github.com/zzu-andrew/ebpf/tree/main/perf/"
    click ringbuf "https://github.com/zzu-andrew/ebpf/tree/main/ringbuf/"
    click rlimit "https://github.com/zzu-andrew/ebpf/tree/main/rlimit/"
    click pin "https://github.com/zzu-andrew/ebpf/tree/main/pin/"
    click bpf2go "https://github.com/zzu-andrew/ebpf/tree/main/cmd/bpf2go/"
    click internal "https://github.com/zzu-andrew/ebpf/tree/main/internal/"
    click examples "https://github.com/zzu-andrew/ebpf/tree/main/examples/"
    click docs "https://github.com/zzu-andrew/ebpf/tree/main/docs/"
```
