docs(workstation): update implementation workflow
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user