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

Closed
opened 2026-09-17 14:37:48 +02:00 by erikinkinen · 0 comments
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.

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.

Related records and contracts
Repository Links
docs issue 10
## 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. 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. <details> <summary>Related records and contracts</summary> | Repository | Links | | --- | --- | | docs | [issue 10](https://git.erikinkinen.fi/erix/docs/issues/10) | </details>
erikinkinen added this to the Alpha 1 milestone 2026-10-30 09:33:39 +01:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
erix/docs#10
No description provided.