# mroz59/hermes-kms architecture

> Architecture diagram of the GitHub repository mroz59/hermes-kms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mroz59/hermes-kms
- Repository: https://github.com/mroz59/hermes-kms

## Overview

Hermes-KMS is a Linux virtual-display DRM/KMS driver whose main workflow is: a userspace owner claims an output and receives a session capability; a compositor drives that output; an authorized capture client waits for and acquires scanout DMA-BUFs; and a real GPU imports them for encoding. The driver also supports cursor capture, synthetic EDID, multiple outputs/cards and runtime card creation. The graph includes documented reference and diagnostic tools. Kernel internals beyond the supplied excerpts are grouped by responsibility; links to unsampled subsystems use README evidence only.

Main entry points: [`include/uapi/drm/hermes_kms_drm.h`](https://github.com/mroz59/hermes-kms/blob/main/include/uapi/drm/hermes_kms_drm.h) (DRM ioctl UAPI), [`kernel/hermes-kms/hermes_kms.c`](https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms.c) (DRM/KMS driver), [`tools/hermes-kms-import-check/hermes_kms_import_check.c`](https://github.com/mroz59/hermes-kms/blob/main/tools/hermes-kms-import-check/hermes_kms_import_check.c) (VAAPI import check), [`tools/hermes-egl-import-check/hermes_egl_import_check.c`](https://github.com/mroz59/hermes-kms/blob/main/tools/hermes-egl-import-check/hermes_egl_import_check.c) (EGL import check)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_display["Virtual display"]
  node_driver["DRM/KMS driver<br/>[hermes_kms.c]"]
  node_outputs["Virtual outputs<br/>[hermes_kms.c]"]
  node_edid["Synthetic EDID<br/>[hermes_kms_edid.h]"]
  node_vblank["Vblank and modeset<br/>[hermes_kms.c]"]
  node_configfs["Runtime card creation<br/>[hermes_kms.c]"]
end

subgraph group_capture["Capture and sessions"]
  node_uapi["DRM ioctl UAPI<br/>[hermes_kms_drm.h]"]
  node_tracking["Scanout tracking<br/>[hermes_kms.c]"]
  node_sessions["Session authorization<br/>[hermes_kms.c]"]
  node_frame["Frame export<br/>[hermes_kms.c]"]
  node_cursor["Cursor capture<br/>[hermes_kms.c]"]
end

subgraph group_clients["Reference clients"]
  node_sessionhelper["Session helper<br/>[hermes_session.h]"]
  node_kmsctl["KMS control client<br/>[hermes_kmsctl.c]"]
  node_vaapi["VAAPI import check"]
  node_egl["EGL import check"]
  node_pitch["Pitch detector<br/>[pitch_detect.c]"]
  node_pixel["Pixel inspection"]
end

subgraph group_diagnostics["Diagnostics"]
  node_cursorprobe["Cursor probe"]
  node_vblankmeter["Vblank meter"]
end

node_owner(("Output owner"))
node_compositor(("Desktop compositor"))
node_consumer(("Capture consumer"))
node_gpu(("Real GPU"))

node_owner -->|"claims output"| node_uapi
node_uapi -->|"authorizes access"| node_sessions
node_owner -->|"transfers token"| node_consumer
node_consumer -->|"binds and requests"| node_uapi
node_compositor -->|"drives display"| node_outputs
node_driver -->|"exposes outputs"| node_outputs
node_driver -->|"uses generator"| node_edid
node_driver -->|"creates cards"| node_configfs
node_outputs -->|"tracks scanout"| node_tracking
node_tracking -->|"exports frames"| node_frame
node_consumer -->|"acquires DMA-BUF"| node_frame
node_consumer -->|"acquires cursor"| node_cursor
node_gpu -->|"imports DMA-BUF"| node_frame
node_compositor -->|"drives refresh"| node_vblank
node_sessionhelper -->|"binds credentials"| node_sessions
node_kmsctl -->|"controls and queries"| node_uapi
node_vaapi -->|"waits and acquires"| node_uapi
node_vaapi -->|"imports with VAAPI"| node_gpu
node_egl -->|"acquires frames"| node_uapi
node_egl -->|"imports with EGL"| node_gpu
node_pitch -->|"checks row pitch"| node_gpu
node_pixel -->|"reads scanout"| node_uapi
node_cursorprobe -->|"inspects cursor"| node_uapi
node_vblankmeter -->|"measures vblank"| node_uapi

click node_uapi "https://github.com/mroz59/hermes-kms/blob/main/include/uapi/drm/hermes_kms_drm.h"
click node_driver "https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms.c"
click node_outputs "https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms.c"
click node_edid "https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms_edid.h"
click node_vblank "https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms.c"
click node_tracking "https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms.c"
click node_sessions "https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms.c"
click node_frame "https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms.c"
click node_cursor "https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms.c"
click node_sessionhelper "https://github.com/mroz59/hermes-kms/blob/main/tools/hermes_session.h"
click node_kmsctl "https://github.com/mroz59/hermes-kms/blob/main/tools/hermes-kmsctl/hermes_kmsctl.c"
click node_vaapi "https://github.com/mroz59/hermes-kms/blob/main/tools/hermes-kms-import-check/hermes_kms_import_check.c"
click node_egl "https://github.com/mroz59/hermes-kms/blob/main/tools/hermes-egl-import-check/hermes_egl_import_check.c"
click node_pitch "https://github.com/mroz59/hermes-kms/blob/main/tools/hermes-egl-import-check/pitch_detect.c"
click node_pixel "https://github.com/mroz59/hermes-kms/blob/main/tools/hermes-pixel-peek/hermes_pixel_peek.c"
click node_cursorprobe "https://github.com/mroz59/hermes-kms/blob/main/tools/hermes-cursor-probe/hermes_cursor_probe.c"
click node_vblankmeter "https://github.com/mroz59/hermes-kms/blob/main/scripts/hermes-vblank-meter.c"
click node_configfs "https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_driver,node_outputs,node_edid,node_vblank,node_configfs toneBlue
class node_uapi,node_tracking,node_sessions,node_frame,node_cursor toneAmber
class node_sessionhelper,node_kmsctl,node_vaapi,node_egl,node_pitch,node_pixel toneMint
class node_cursorprobe,node_vblankmeter toneRose
class node_owner,node_compositor,node_consumer,node_gpu toneIndigo
```

## Components

### Virtual display

- [DRM/KMS driver](https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms.c): `kernel/hermes-kms/hermes_kms.c`
- [Virtual outputs](https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms.c): `kernel/hermes-kms/hermes_kms.c`
- [Synthetic EDID](https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms_edid.h): `kernel/hermes-kms/hermes_kms_edid.h`
- [Vblank and modeset](https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms.c): `kernel/hermes-kms/hermes_kms.c`
- [Runtime card creation](https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms.c): `kernel/hermes-kms/hermes_kms.c`

### Capture and sessions

- [DRM ioctl UAPI](https://github.com/mroz59/hermes-kms/blob/main/include/uapi/drm/hermes_kms_drm.h): `include/uapi/drm/hermes_kms_drm.h`
- [Scanout tracking](https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms.c): `kernel/hermes-kms/hermes_kms.c`
- [Session authorization](https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms.c): `kernel/hermes-kms/hermes_kms.c`
- [Frame export](https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms.c): `kernel/hermes-kms/hermes_kms.c`
- [Cursor capture](https://github.com/mroz59/hermes-kms/blob/main/kernel/hermes-kms/hermes_kms.c): `kernel/hermes-kms/hermes_kms.c`

### Reference clients

- [Session helper](https://github.com/mroz59/hermes-kms/blob/main/tools/hermes_session.h): `tools/hermes_session.h`
- [KMS control client](https://github.com/mroz59/hermes-kms/blob/main/tools/hermes-kmsctl/hermes_kmsctl.c): `tools/hermes-kmsctl/hermes_kmsctl.c`
- [VAAPI import check](https://github.com/mroz59/hermes-kms/blob/main/tools/hermes-kms-import-check/hermes_kms_import_check.c): `tools/hermes-kms-import-check/hermes_kms_import_check.c`
- [EGL import check](https://github.com/mroz59/hermes-kms/blob/main/tools/hermes-egl-import-check/hermes_egl_import_check.c): `tools/hermes-egl-import-check/hermes_egl_import_check.c`
- [Pitch detector](https://github.com/mroz59/hermes-kms/blob/main/tools/hermes-egl-import-check/pitch_detect.c): `tools/hermes-egl-import-check/pitch_detect.c`
- [Pixel inspection](https://github.com/mroz59/hermes-kms/blob/main/tools/hermes-pixel-peek/hermes_pixel_peek.c): `tools/hermes-pixel-peek/hermes_pixel_peek.c`

### Diagnostics

- [Cursor probe](https://github.com/mroz59/hermes-kms/blob/main/tools/hermes-cursor-probe/hermes_cursor_probe.c): `tools/hermes-cursor-probe/hermes_cursor_probe.c`
- [Vblank meter](https://github.com/mroz59/hermes-kms/blob/main/scripts/hermes-vblank-meter.c): `scripts/hermes-vblank-meter.c`

### Other components

- **Output owner**
- **Desktop compositor**
- **Capture consumer**
- **Real GPU**

## Connections

- Output owner → DRM ioctl UAPI: claims output (evidence: `README.md`)
- DRM ioctl UAPI → Session authorization: authorizes access (evidence: `README.md`)
- Output owner → Capture consumer: transfers token (evidence: `README.md`)
- Capture consumer → DRM ioctl UAPI: binds and requests (evidence: `README.md`)
- Desktop compositor → Virtual outputs: drives display (evidence: `README.md`)
- DRM/KMS driver → Virtual outputs: exposes outputs (evidence: `README.md`)
- DRM/KMS driver → Synthetic EDID: uses generator (evidence: `kernel/hermes-kms/hermes_kms.c`)
- DRM/KMS driver → Runtime card creation: creates cards (evidence: `README.md`)
- Virtual outputs → Scanout tracking: tracks scanout (evidence: `kernel/hermes-kms/hermes_kms.c`)
- Scanout tracking → Frame export: exports frames (evidence: `README.md`)
- Capture consumer → Frame export: acquires DMA-BUF (evidence: `README.md`)
- Capture consumer → Cursor capture: acquires cursor (evidence: `README.md`)
- Real GPU → Frame export: imports DMA-BUF (evidence: `README.md`)
- Desktop compositor → Vblank and modeset: drives refresh (evidence: `README.md`)
- Session helper → Session authorization: binds credentials (evidence: `tools/hermes_session.h`)
- KMS control client → DRM ioctl UAPI: controls and queries (evidence: `tools/hermes-kmsctl/hermes_kmsctl.c`)
- VAAPI import check → DRM ioctl UAPI: waits and acquires (evidence: `tools/hermes-kms-import-check/hermes_kms_import_check.c`)
- VAAPI import check → Real GPU: imports with VAAPI (evidence: `tools/hermes-kms-import-check/hermes_kms_import_check.c`)
- EGL import check → DRM ioctl UAPI: acquires frames (evidence: `tools/hermes-egl-import-check/hermes_egl_import_check.c`)
- EGL import check → Real GPU: imports with EGL (evidence: `tools/hermes-egl-import-check/hermes_egl_import_check.c`)
- Pitch detector → Real GPU: checks row pitch (evidence: `tools/hermes-egl-import-check/pitch_detect.c`)
- Pixel inspection → DRM ioctl UAPI: reads scanout (evidence: `tools/hermes-pixel-peek/hermes_pixel_peek.c`)
- Cursor probe → DRM ioctl UAPI: inspects cursor (evidence: `tools/hermes-cursor-probe/hermes_cursor_probe.c`)
- Vblank meter → DRM ioctl UAPI: measures vblank (evidence: `scripts/hermes-vblank-meter.c`)
