docs(workstation): update implementation workflow

This commit is contained in:
tmk241
2026-08-17 07:54:05 +02:00
parent 90042d1d7b
commit 4f64017761
+17 -11
View File
@@ -4,7 +4,7 @@ description: >-
Use when configuring, implementing, debugging, porting, or reviewing XMM or its
compile-time workstation policy. Distinguish a local config.h edit from a new
product capability, then rebuild and prove the real path. Do not use for
requirements-only authoring, planning, orientation, or unrelated host dotfiles.
specification-only authoring, planning, orientation, or unrelated host dotfiles.
---
# XMM workstation
@@ -17,7 +17,7 @@ product slice when the capability does not exist.
## Choose the owner
Read `AGENTS.md`, the applicable `REQUIREMENTS.md` rows, and `config.def.h` or the
Read `AGENTS.md`, the applicable `SPEC.md` records, and `config.def.h` or the
owning production module.
- **Local configuration:** when the request changes only monitor profiles,
@@ -26,9 +26,9 @@ owning production module.
`config.h`. Copy `config.def.h` first only when `config.h` is absent. Do not
change requirements or tracked defaults.
- **Default policy:** when the user explicitly changes shipped defaults, revise
requirements first, then `config.def.h`, proof, and orientation as applicable.
the specification first, then `config.def.h`, proof, and orientation as applicable.
- **Capability:** when typed configuration cannot express the requested behavior,
revise or obtain requirement authority before changing C11 code or protocols.
revise or obtain specification authority before changing C11 code or protocols.
For local setup, inspect only evidence relevant to requested policy: connected
output connector/EDID/modes, current compositor config, XKB settings, input
@@ -43,9 +43,11 @@ coalesces damage behind one pending flip per output, while `src/render.c` must
submit through implicit fences without waiting for GPU completion on that loop;
direct libinput discovery, XKB compilation, typed device
policy, and event normalization are owned by `src/input.c`; `src/diagnostic_log.c`
owns the nonblocking stderr mirror and bounded XDG state log; `src/render.c` owns
the fixed EGL/GLESv2 composition path, nested EGL target, and single-plane
DMA-BUF EGLImage import; `src/dmabuf.c` owns the bounded linux-dmabuf v5 global,
owns the nonblocking stderr mirror and bounded XDG state log; `src/scheduling.c`
owns minimum-`SCHED_RR` compositor elevation plus fail-closed child reset, while
the installed direct binary's `cap_sys_nice=ep` is host policy; `src/render.c`
owns the fixed EGL/GLESv2 composition path, nested EGL target, and modifier-aware
multi-plane DMA-BUF EGLImage import; `src/dmabuf.c` owns the bounded linux-dmabuf v5 global,
feedback, parameter validation, wl_buffer lifetime, and release handoff; `src/presentation.c` owns presentation-time feedback lifetime while
`src/direct.c` supplies page-flip timestamps and refresh and `src/xmm.c` binds each
presented surface commit to that observation;
@@ -76,8 +78,9 @@ matter. Keep pinned source/data mechanisms (currently Spleen glyphs and the
minimal libgrapheme UAX #29 implementation/tables) at their owning local seam
with URL, revision/version, checksum, license, and modifications; do not replace
them with ambient host font or locale behavior. Keep reusable server-global
state machines such as activation and core data devices in their dedicated
`src/` modules, with seat/focus/surface policy supplied by the compositor owner
state machines such as activation, core data devices, and trusted same-session
ext-data-control clipboard access in their dedicated `src/` modules, with
seat/focus/surface policy supplied by the compositor owner
in `src/xmm.c`. Pinned xdg-shell and xdg-decoration XML, scanner generation, and
decoration negotiation remain one protocol slice; server-side mode suppresses
client titlebars and must not grow a drawn decoration framework. Write the
@@ -98,7 +101,10 @@ Never substitute sleeps, blind retries, ambient config, mock-only platform
claims, or line coverage for observable proof. The current `make check` nested
journeys require a running Sway host plus `swaymsg`, `grim`, `jq`, `xkbcli`, and
virtual-keyboard and virtual-pointer support; they also rebuild and repeat under
ASan/UBSan. Direct frame-stage diagnostics are compile-time-only: rebuild with
ASan/UBSan. Load-qualified direct input additionally requires the final `xmm`
executable to expose `cap_sys_nice=ep`; verify XMM is minimum `SCHED_RR` and its
children are `SCHED_OTHER` before saturating normal-priority workers. Direct
frame-stage diagnostics are compile-time-only: rebuild with
`-DXMM_PERF_TRACE` when a live timing journey needs input, spawn/surface-map,
client SHM copy, latch, upload, KMS-submit, and page-flip timestamps; summarize
stderr with `tools/xmm-perf-report.sh <log>`. A trace build also accepts `SIGUSR1`
@@ -116,7 +122,7 @@ never copy product semantics into it.
## Handoff
Report `owner: local config | shipped default | capability`, requirement impact,
Report `owner: local config | shipped default | capability`, specification impact,
changed anchors, tests and live journeys, and remaining target-specific risk. If
the real boundary is unavailable, name the blocked proof rather than claiming
support.