[BUG] Syscall reference describes an obsolete return instruction and frame layout #10

New issue

Closed

opened 2026-09-17 14:37:48 +02:00 by erikinkinen · 0 comments

erikinkinen commented

2026-09-17 14:37:48 +02:00

Owner

Summary

The detailed syscall reference describes SYSRETQ, a 128-byte saved frame pushed on the user stack, and a 64-KiB kernel stack. The selected implementation returns through IRETQ, retains a 136-byte task resume prefix, and builds its 176-byte active entry reservation on a 256-KiB kernel stack. The stale text misidentifies the memory and return contracts consumed by architecture reviewers.

Reproduction

Compare Docs 0a0f305464f7df2b33e2ef7c86079d64c844e4b8, manual/6-kernel-api-reference/14-syscall-reference.tex, with Kernel e15a045d7701030e58d9e59517406f8c79694ff8, src/arch/x86_64/syscall/init.rs, dispatch.rs, and src/kobj/tcb/runtime.rs. The signed native diagnostic ELF independently contains IRETQ and a 176-byte kernel-stack reservation.

Expected and actual behavior

Expected: document the actual return instruction, saved user RSP, ownership and sizes of the task resume prefix and transient entry scratch, and the initial scheduled-entry shape.

Actual: six references name SYSRETQ, the resume table omits saved RSP, and the narrative describes writes before switching away from the user stack. The documented kernel stack size is also stale. The implementation's wire syscall selectors are unaffected by correcting this prose.

Environment and identity

Docs: 0a0f305464f7df2b33e2ef7c86079d64c844e4b8.
Kernel: e15a045d7701030e58d9e59517406f8c79694ff8; native x86-64 entry and scheduler resume code.
Original Docs CI 927/928 and its 45 tests pass; those checks do not compare all architectural prose against assembly.
First revision introducing the documentation drift is not established.

Evidence and prior checks

The original native entry has a 176-byte kernel-stack reservation, saves user RSP at offset 0x80, and constructs an IRETQ return frame. The TCB copy and initial frame contain seventeen eight-byte words. The active syscall kernel stack constant is 256 KiB. Preserve these distinctions while correcting the existing manual; do not introduce a new runtime ABI or claim complete memory-effect validation.

Run the existing documentation tests, Markdown/template checks, complete manual rendering, reference and layout checks, and original automatic CI. Runtime implementation validation belongs to its separately selected source and image.

Explicit entry-state checkpoint — 17 September 2026: signed Docs c7bfffc4a2ec46eeb496f001fd40735648843a01 corrects the syscall reference to IRETQ, a 136-byte retained prefix, a separate 176-byte kernel entry reservation, saved user RSP and the 256 KiB kernel stack. It documents the explicit live-direction contract and thirty query cases while preserving the limits of finite native evidence. This addresses issue 10; generated API snapshots are unchanged.

All 45 documentation tests and Markdown/template checks pass. The complete 2,387-page manual has 437,732 in-bounds word boxes and no final warnings; pages 146, 166, 168 and 169 were visually reviewed. Runtime tests are inapplicable to this documentation-only change. Original CI 929 and CI 930 both pass. All four complete terminal logs are classified; both full 2,387-page manual builds have zero final warnings. Issue 10 is closed for the corrected documentation drift. No complete guest build is established.

Tracking

Documentation review: #4. Owning plan: #1. The preceding selector-list defect is resolved separately in #9.

## Summary The detailed syscall reference describes SYSRETQ, a 128-byte saved frame pushed on the user stack, and a 64-KiB kernel stack. The selected implementation returns through IRETQ, retains a 136-byte task resume prefix, and builds its 176-byte active entry reservation on a 256-KiB kernel stack. The stale text misidentifies the memory and return contracts consumed by architecture reviewers. ## Reproduction Compare Docs `0a0f305464f7df2b33e2ef7c86079d64c844e4b8`, `manual/6-kernel-api-reference/14-syscall-reference.tex`, with Kernel `e15a045d7701030e58d9e59517406f8c79694ff8`, `src/arch/x86_64/syscall/init.rs`, `dispatch.rs`, and `src/kobj/tcb/runtime.rs`. The signed native diagnostic ELF independently contains IRETQ and a 176-byte kernel-stack reservation. ## Expected and actual behavior Expected: document the actual return instruction, saved user RSP, ownership and sizes of the task resume prefix and transient entry scratch, and the initial scheduled-entry shape. Actual: six references name SYSRETQ, the resume table omits saved RSP, and the narrative describes writes before switching away from the user stack. The documented kernel stack size is also stale. The implementation's wire syscall selectors are unaffected by correcting this prose. ## Environment and identity - Docs: `0a0f305464f7df2b33e2ef7c86079d64c844e4b8`. - Kernel: `e15a045d7701030e58d9e59517406f8c79694ff8`; native x86-64 entry and scheduler resume code. - Original Docs CI 927/928 and its 45 tests pass; those checks do not compare all architectural prose against assembly. - First revision introducing the documentation drift is not established. ## Evidence and prior checks The original native entry has a 176-byte kernel-stack reservation, saves user RSP at offset 0x80, and constructs an IRETQ return frame. The TCB copy and initial frame contain seventeen eight-byte words. The active syscall kernel stack constant is 256 KiB. Preserve these distinctions while correcting the existing manual; do not introduce a new runtime ABI or claim complete memory-effect validation. Run the existing documentation tests, Markdown/template checks, complete manual rendering, reference and layout checks, and original automatic CI. Runtime implementation validation belongs to its separately selected source and image. Explicit entry-state checkpoint — 17 September 2026: signed Docs `c7bfffc4a2ec46eeb496f001fd40735648843a01` corrects the syscall reference to IRETQ, a 136-byte retained prefix, a separate 176-byte kernel entry reservation, saved user RSP and the 256 KiB kernel stack. It documents the explicit live-direction contract and thirty query cases while preserving the limits of finite native evidence. This addresses [issue 10](https://git.erikinkinen.fi/erix/docs/issues/10); generated API snapshots are unchanged. All 45 documentation tests and Markdown/template checks pass. The complete 2,387-page manual has 437,732 in-bounds word boxes and no final warnings; pages 146, 166, 168 and 169 were visually reviewed. Runtime tests are inapplicable to this documentation-only change. Original [CI 929](https://git.erikinkinen.fi/erix/docs/actions/runs/929) and [CI 930](https://git.erikinkinen.fi/erix/docs/actions/runs/930) both pass. All four complete terminal logs are classified; both full 2,387-page manual builds have zero final warnings. Issue 10 is closed for the corrected documentation drift. No complete guest build is established. ## Tracking Documentation review: https://git.erikinkinen.fi/erix/docs/pulls/4. Owning plan: https://git.erikinkinen.fi/erix/docs/issues/1. The preceding selector-list defect is resolved separately in https://git.erikinkinen.fi/erix/docs/issues/9.

erikinkinen added the

bug

docs

phase-6

labels

2026-09-17 14:37:48 +02:00

erikinkinen referenced this issue

2026-09-17 15:00:30 +02:00

[FEATURE] Enforce complete inline documentation and warning-free documentation builds #1

erikinkinen referenced this issue

2026-09-17 15:00:32 +02:00

WIP: Document native authority and verify workspace and command evidence #4