# cr8t/udev architecture

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

- Interactive diagram: https://gitdiagram.com/cr8t/udev
- Repository: https://github.com/cr8t/udev

## Overview

##### Project Type and Purpose
- This is a Rust library (crate) that provides a safe, idiomatic Rust API for interacting with Linux’s devfs (`udev`), mirroring the public API of the C `eudev`/`libudev` library.
- It is an open-source tool (library) rather than a stand-alone application. Consumers link against it to enumerate devices, monitor udev events, query the hardware database (hwdb), and queue device events.

##### High-Level Architectural Components
a. Public API Layer (src/lib.rs)
- Re-exports and ties together the submodules under a unified, C-compatible-like API.
b. Context Management (src/context.rs)
- `Udev` context object: holds configuration and references needed for all subsystems.
c. Device Operations
- Enumeration (src/enumerate.rs → `UdevEnumerate`)
- Listing (src/list.rs → `UdevList`)
- Monitoring (src/monitor.rs → `UdevMonitor`)
- Queueing (src/queue.rs → `UdevQueue`)
d. Hardware Database (src/hwdb.rs + src/hwdb/)
- Loads on-disk hwdb files, parses lines (`hwdb/line.rs`), builds a compressed trie (`hwdb/trie/`) for fast lookups.
e. System Interaction Layer
- Netlink sockets (src/socket.rs) for events/enumeration
- File I/O (src/file.rs) for reading hwdb and sysfs nodes
- Utility modules (src/util/, src/murmur_hash.rs) for hashing, path handling, device node resolution
f. Cross-cutting Concerns
- Error handling (src/error.rs)
- Logging (src/log.rs)
- Modes/flags (src/mode.rs)

##### Relationships and Data Flow
- Consumer (application) → Public API → Context
- Context → opens netlink socket (socket module), file handles (file module)
- Enumeration/List → sends netlink requests → kernel → parses replies → returns `UdevDevice` objects
- Monitor → binds to socket → listens for events → wraps raw messages into `UdevDevice` events
- Queue → receives events from kernel → allows user to dequeue them
- Hwdb → on first query or at init, loads hwdb files into Trie structure → queries by device ID → returns metadata
- Utility modules and murmur-hash are invoked by hwdb loader and trie builder

##### Architectural Patterns and Principles
- Modularization: each udev subsystem lives in its own module, exposed via a flat public API
- Safe abstractions over `unsafe` blocks: low-level OS interactions confined to small modules with documented `SAFETY` sections
- Data-structure specialization: compressed trie for hwdb with child_entry, header, node, value_entry components
- Separation of concerns: socket I/O, file I/O, data parsing, and API layering are distinct

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "API & Context Layer"
        PublicAPI["Public API"]:::api
        Context["Context"]:::api
    end
    PublicAPI --> Context

    subgraph "Subsystems"
        Enumerate["Enumerate"]:::sub
        List["List"]:::sub
        Monitor["Monitor"]:::sub
        Queue["Queue"]:::sub
        HwdbFacade["Hwdb Facade"]:::sub
    end
    Context --> Enumerate
    Context --> List
    Context --> Monitor
    Context --> Queue
    Context --> HwdbFacade

    subgraph "I/O Layers"
        Socket["Socket I/O"]:::io
        FileIO["File I/O"]:::io
    end
    Enumerate -->|netlink request/response| Socket
    List -->|netlink request/response| Socket
    Monitor -->|bind/listen events| Socket
    Queue -->|receive events| Socket
    HwdbFacade -->|read files| FileIO

    Socket -->|netlink communication| Kernel["Linux Kernel"]:::ext
    FileIO -->|read hwdb files| Disk["hwdb files on disk"]:::ext

    subgraph "Hwdb Internal"
        Line["Line Parser"]:::hwdb
        TrieBuilder["Trie Builder"]:::hwdb
        subgraph "Trie Components"
            Child["Child Entry"]:::hwdb
            Header["Entry Header"]:::hwdb
            Node["Trie Node"]:::hwdb
            Value["Value Entry"]:::hwdb
        end
    end
    HwdbFacade --> Line --> TrieBuilder
    TrieBuilder --> Child
    TrieBuilder --> Header
    TrieBuilder --> Node
    TrieBuilder --> Value

    subgraph "Utilities & Cross-cutting"
        Utils["General Helpers"]:::util
        DevNode["Device Node Resolution"]:::util
        Murmur["Murmur Hash"]:::util
        Error["Error Handling"]:::util
        Log["Logging"]:::util
        Mode["Modes/Flags"]:::util
    end
    Enumerate -.->|uses| Utils
    Monitor -.->|uses| Utils
    Queue -.->|uses| Utils
    HwdbFacade -.->|uses| Murmur
    HwdbFacade -.->|uses| DevNode
    Enumerate -.->|error/log| Error
    Enumerate -.->|error/log| Log
    Monitor -.->|error/log| Error
    Monitor -.->|error/log| Log
    Queue -.->|error/log| Error
    Queue -.->|error/log| Log
    HwdbFacade -.->|error/log| Error
    HwdbFacade -.->|error/log| Log

    click PublicAPI "https://github.com/cr8t/udev/blob/main/src/lib.rs"
    click Context "https://github.com/cr8t/udev/blob/main/src/context.rs"
    click Enumerate "https://github.com/cr8t/udev/blob/main/src/enumerate.rs"
    click List "https://github.com/cr8t/udev/blob/main/src/list.rs"
    click Monitor "https://github.com/cr8t/udev/blob/main/src/monitor.rs"
    click Queue "https://github.com/cr8t/udev/blob/main/src/queue.rs"
    click HwdbFacade "https://github.com/cr8t/udev/blob/main/src/hwdb.rs"
    click Line "https://github.com/cr8t/udev/blob/main/src/hwdb/line.rs"
    click TrieBuilder "https://github.com/cr8t/udev/blob/main/src/hwdb/trie.rs"
    click Child "https://github.com/cr8t/udev/blob/main/src/hwdb/trie/child_entry.rs"
    click Header "https://github.com/cr8t/udev/blob/main/src/hwdb/trie/header.rs"
    click Node "https://github.com/cr8t/udev/blob/main/src/hwdb/trie/node.rs"
    click Value "https://github.com/cr8t/udev/blob/main/src/hwdb/trie/value_entry.rs"
    click Socket "https://github.com/cr8t/udev/blob/main/src/socket.rs"
    click FileIO "https://github.com/cr8t/udev/blob/main/src/file.rs"
    click Utils "https://github.com/cr8t/udev/blob/main/src/util.rs"
    click DevNode "https://github.com/cr8t/udev/blob/main/src/util/device_nodes.rs"
    click Murmur "https://github.com/cr8t/udev/blob/main/src/murmur_hash.rs"
    click Error "https://github.com/cr8t/udev/blob/main/src/error.rs"
    click Log "https://github.com/cr8t/udev/blob/main/src/log.rs"
    click Mode "https://github.com/cr8t/udev/blob/main/src/mode.rs"

    classDef api fill:#D0E6FF,stroke:#4A90E2,color:#004080;
    classDef sub fill:#E6F7D1,stroke:#3C763D,color:#336633;
    classDef io fill:#FFE5B4,stroke:#E67E22,color:#A84300;
    classDef hwdb fill:#E8EEF1,stroke:#7F8C8D,color:#2C3E50;
    classDef util fill:#F2F2F2,stroke:#BDC3C7,color:#7F8C8D;
    classDef ext fill:#FDEDEC,stroke:#C0392B,color:#922B21;
```
