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
|
Use when configuring, implementing, debugging, porting, or reviewing XMM or its
|
||||||
compile-time workstation policy. Distinguish a local config.h edit from a new
|
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
|
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
|
# XMM workstation
|
||||||
@@ -17,7 +17,7 @@ product slice when the capability does not exist.
|
|||||||
|
|
||||||
## Choose the owner
|
## 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.
|
owning production module.
|
||||||
|
|
||||||
- **Local configuration:** when the request changes only monitor profiles,
|
- **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
|
`config.h`. Copy `config.def.h` first only when `config.h` is absent. Do not
|
||||||
change requirements or tracked defaults.
|
change requirements or tracked defaults.
|
||||||
- **Default policy:** when the user explicitly changes shipped defaults, revise
|
- **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,
|
- **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
|
For local setup, inspect only evidence relevant to requested policy: connected
|
||||||
output connector/EDID/modes, current compositor config, XKB settings, input
|
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;
|
submit through implicit fences without waiting for GPU completion on that loop;
|
||||||
direct libinput discovery, XKB compilation, typed device
|
direct libinput discovery, XKB compilation, typed device
|
||||||
policy, and event normalization are owned by `src/input.c`; `src/diagnostic_log.c`
|
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
|
owns the nonblocking stderr mirror and bounded XDG state log; `src/scheduling.c`
|
||||||
the fixed EGL/GLESv2 composition path, nested EGL target, and single-plane
|
owns minimum-`SCHED_RR` compositor elevation plus fail-closed child reset, while
|
||||||
DMA-BUF EGLImage import; `src/dmabuf.c` owns the bounded linux-dmabuf v5 global,
|
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
|
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
|
`src/direct.c` supplies page-flip timestamps and refresh and `src/xmm.c` binds each
|
||||||
presented surface commit to that observation;
|
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
|
minimal libgrapheme UAX #29 implementation/tables) at their owning local seam
|
||||||
with URL, revision/version, checksum, license, and modifications; do not replace
|
with URL, revision/version, checksum, license, and modifications; do not replace
|
||||||
them with ambient host font or locale behavior. Keep reusable server-global
|
them with ambient host font or locale behavior. Keep reusable server-global
|
||||||
state machines such as activation and core data devices in their dedicated
|
state machines such as activation, core data devices, and trusted same-session
|
||||||
`src/` modules, with seat/focus/surface policy supplied by the compositor owner
|
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
|
in `src/xmm.c`. Pinned xdg-shell and xdg-decoration XML, scanner generation, and
|
||||||
decoration negotiation remain one protocol slice; server-side mode suppresses
|
decoration negotiation remain one protocol slice; server-side mode suppresses
|
||||||
client titlebars and must not grow a drawn decoration framework. Write the
|
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
|
claims, or line coverage for observable proof. The current `make check` nested
|
||||||
journeys require a running Sway host plus `swaymsg`, `grim`, `jq`, `xkbcli`, and
|
journeys require a running Sway host plus `swaymsg`, `grim`, `jq`, `xkbcli`, and
|
||||||
virtual-keyboard and virtual-pointer support; they also rebuild and repeat under
|
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,
|
`-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
|
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`
|
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
|
## 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
|
changed anchors, tests and live journeys, and remaining target-specific risk. If
|
||||||
the real boundary is unavailable, name the blocked proof rather than claiming
|
the real boundary is unavailable, name the blocked proof rather than claiming
|
||||||
support.
|
support.
|
||||||
|
|||||||
Reference in New Issue
Block a user