# projectceladon/drm-hwcomposer architecture

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

- Interactive diagram: https://gitdiagram.com/projectceladon/drm-hwcomposer
- Repository: https://github.com/projectceladon/drm-hwcomposer

## Overview

##### Project type and purpose
- drm_hwcomposer is a system‐level service and HAL implementation for Android’s hardware composer, using Linux DRM/KMS to drive displays. It implements both HWC2 (via hwc2_device) and HWC3 (via hwc3-server AIDL service), providing buffer inspection, atomic commits, vsync, hotplug handling, and composition planning on DRM‐capable hardware.

##### File structure
- Top-level modules:
- backend: core interfaces for managing DRM backends (clients, managers)
- bufferinfo: inspect and map graphic buffers (generic + legacy/platform-specific)
- compositor: plan atomic KMS compositions (DrmKmsPlan)
- drm: wrappers and helpers around DRM/KMS objects (connectors, CRTCs, planes, encoders, modes, atomic state)
- hwc2_device: Android HWC2 HAL entrypoint (implements HWC2 device callbacks)
- hwc3-server: Android HWC3 AIDL service implementation (Composer, ResourceManager, command engine)
- libhwcservice: shared client-side library for service interactions (icontrols, iservice, idiagnostic)
- utils: common utilities (UEvent listener, logging, spinlocks, property helpers)
- tests: unit and integration tests for key functionality
- Build and CI: Android.bp / Android.mk, GitLab CI, GitHub workflows, clang-format/tidy, build_deploy.sh, presubmit.sh.

##### README for additional insights
- Purpose: “universal HW composer implementation for Android”
- Encourages patches across porting, bugfixes, new features.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Android User Space Layer
    subgraph "Android User Space"
        direction TB
        SF["SurfaceFlinger"]:::android
        HWC2["HWC2 HAL\n(hwc2_device.cpp)"]:::android
        HWC3["HWC3 AIDL Service\n(Composer.cpp)"]:::android
        LIBCLI["libhwcservice\n(client API)"]:::android
    end

    %% Core drm_hwcomposer Library
    subgraph "Core drm_hwcomposer Library"
        direction TB
        BACKEND["Backend Manager/Client"]:::core
        BUFFER["BufferInfo & Legacy Plugins"]:::core
        COMP["Compositor\n(DrmKmsPlan)"]:::core
    end

    %% DRM Wrappers & Helpers
    subgraph "DRM Wrappers & Helpers"
        direction TB
        DRMDEV["DrmDevice"]:::drm
        RESMGR["ResourceManager"]:::drm
        ATOMSM["DrmAtomicStateManager"]:::drm
        UEVLIST["UEventListener"]:::drm
        VSWORK["VSyncWorker"]:::drm
    end

    %% Utilities & Tests
    subgraph "Utilities & Tests"
        direction TB
        UTILS["Utils"]:::grey
        TESTS["Tests"]:::grey
    end

    %% Kernel & Hardware
    subgraph "Kernel & Hardware"
        direction TB
        KDRM[(Linux DRM/KMS)]:::kernel
        HW["Physical Display Hardware"]:::hardware
    end

    %% Relationships
    SF -->|"calls HWC2 callbacks"| HWC2
    SF -->|"binder/AIDL"| HWC3
    SF -->|"uses"| LIBCLI

    HWC2 -->|"invokes API"| BACKEND
    HWC2 -->|"invokes API"| BUFFER
    HWC2 -->|"invokes API"| COMP

    HWC3 -->|"invokes API"| BACKEND
    HWC3 -->|"invokes API"| BUFFER
    HWC3 -->|"invokes API"| COMP

    BACKEND --> DRMDEV
    BUFFER --> DRMDEV
    COMP --> DRMDEV

    DRMDEV --> RESMGR
    RESMGR --> ATOMSM
    ATOMSM --> KDRM
    KDRM --> HW

    KDRM -->|uEvents/vsync| UEVLIST
    UEVLIST -->|- - -| BACKEND
    VSWORK -->|- - -| BACKEND

    BACKEND --> UTILS
    BUFFER --> UTILS
    COMP --> UTILS
    DRMDEV --> UTILS

    TESTS --> BACKEND
    TESTS --> BUFFER
    TESTS --> COMP
    TESTS --> DRMDEV

    %% Click Events
    click BACKEND "https://github.com/projectceladon/drm-hwcomposer/blob/main/backend/BackendManager.cpp"
    click BACKEND "https://github.com/projectceladon/drm-hwcomposer/blob/main/backend/BackendClient.cpp"
    click BUFFER "https://github.com/projectceladon/drm-hwcomposer/blob/main/bufferinfo/BufferInfo.h"
    click BUFFER "https://github.com/projectceladon/drm-hwcomposer/blob/main/bufferinfo/BufferInfoGetter.cpp"
    click COMP "https://github.com/projectceladon/drm-hwcomposer/blob/main/compositor/DrmKmsPlan.cpp"
    click DRMDEV "https://github.com/projectceladon/drm-hwcomposer/blob/main/drm/DrmDevice.cpp"
    click RESMGR "https://github.com/projectceladon/drm-hwcomposer/blob/main/drm/ResourceManager.cpp"
    click ATOMSM "https://github.com/projectceladon/drm-hwcomposer/blob/main/drm/DrmAtomicStateManager.cpp"
    click UEVLIST "https://github.com/projectceladon/drm-hwcomposer/blob/main/drm/UEventListener.cpp"
    click VSWORK "https://github.com/projectceladon/drm-hwcomposer/blob/main/drm/VSyncWorker.cpp"
    click HWC2 "https://github.com/projectceladon/drm-hwcomposer/blob/main/hwc2_device/hwc2_device.cpp"
    click HWC3 "https://github.com/projectceladon/drm-hwcomposer/blob/main/hwc3-server/default/Composer.cpp"
    click LIBCLI "https://github.com/projectceladon/drm-hwcomposer/blob/main/libhwcservice/hwcserviceapi.cpp"
    click UTILS "https://github.com/projectceladon/drm-hwcomposer/blob/main/utils/Worker.cpp"
    click TESTS "https://github.com/projectceladon/drm-hwcomposer/blob/main/tests/uevent_print.cpp"

    %% Styles
    classDef android fill:#cce5ff,stroke:#66a3ff,color:#000;
    classDef core fill:#d5f5e3,stroke:#28b463,color:#000;
    classDef drm fill:#fdebd0,stroke:#e67e22,color:#000;
    classDef grey fill:#f2f3f4,stroke:#7f8c8d,color:#000;
    classDef kernel fill:#000,stroke:#000,color:#fff;
    classDef hardware fill:#aed6f1,stroke:#2980b9,color:#000;
```
