[FEATURE] Counted processor topology in the boot handoff #10

Open
opened 2026-11-13 13:24:28 +01:00 by erikinkinen · 0 comments
Owner

Problem and motivation

Kernel processor discovery should consume an immutable ID snapshot captured while the Bootloader still owns firmware access. Following firmware addresses during later native startup gives the consumer a source-access duty it does not need.

Proposed behavior and scope

Add BootKernel 2.2 topology data while preserving the 200-byte base and the existing startup descriptor at offsets 200–215. Critical header flag 0x2 selects this descriptor:

Offset Type Value
216 u64 ID-table blob offset
224 u32 Nonzero ID count
228 u32 Stride, exactly 4
232 u16 Snapshot version, exactly 1
234 u16 Snapshot flags, zero
236 u32 Reserved, zero

IDs are little-endian u32 values in producer order; zero and the full u32 range are valid. Provide a checked borrowed view and a fallible encoder that preflights before changing output. There is no replacement CPU ceiling.

Accept exactly minor 2.1 with flags 0/1, and 2.2 with flags 0/1/2/3. The topology flag requires a 240-byte fixed area. With flag 2 alone, offsets 200–215 are zero; flag 3 retains the existing startup descriptor there. Reject unknown minors, flags, snapshot versions and nonzero reserved fields. Absence remains distinct from malformed present-empty data.

Authority, security and reliability

The snapshot conveys IDs as data, never firmware-read authority or CPU ownership. Keep all memory-region flags unchanged. Check offset/count arithmetic, complete bounds and disjointness from every metadata table and startup record. Borrow only the caller's immutable blob; parsing allocates nothing.

The Bootloader retains enabled MADT entry order and rejects duplicate IDs across xAPIC/x2APIC records. Kernel intake independently rejects duplicates, matches its actual BSP and normalizes the list. These semantic checks and native startup grants belong to their consumers, avoiding a quadratic uniqueness scan in the codec.

Acceptance criteria

  • Implement the exact version/flag matrix, borrowed ID view and preflighted encoder.
  • Cover ID zero/full width, unaligned storage, one and many IDs, absent/empty data, truncation, overflow, reserved fields and every metadata overlap; errors leave output unchanged.
  • Preserve startup-resource offsets and existing 2.1 acceptance; document producer, consumer and source-lifetime obligations.
  • Pass formatting, strict Clippy, unit tests, freestanding builds, rustdoc and current component CI without compiler warnings.

Alternatives and tradeoffs

Keeping firmware walkers in Kernel requires continued firmware backing custody. Fixed CPU arrays impose another limit; inferred BSP or peer IDs lose the original topology. A counted data snapshot separates capture from startup while retaining complete identities. Native CPU ownership remains an independent requirement.

Tracking and rollout

Build on the startup-resource contract. Coordinate a Bootloader capture producer and a Kernel data-intake prerequisite for native private-address-space switching. Native 1/2/4-CPU image acceptance stays with that coordinated startup work; this component establishes only the data contract.

## Problem and motivation Kernel processor discovery should consume an immutable ID snapshot captured while the Bootloader still owns firmware access. Following firmware addresses during later native startup gives the consumer a source-access duty it does not need. ## Proposed behavior and scope Add BootKernel 2.2 topology data while preserving the 200-byte base and the existing startup descriptor at offsets 200–215. Critical header flag `0x2` selects this descriptor: | Offset | Type | Value | | --- | --- | --- | | 216 | u64 | ID-table blob offset | | 224 | u32 | Nonzero ID count | | 228 | u32 | Stride, exactly 4 | | 232 | u16 | Snapshot version, exactly 1 | | 234 | u16 | Snapshot flags, zero | | 236 | u32 | Reserved, zero | IDs are little-endian u32 values in producer order; zero and the full u32 range are valid. Provide a checked borrowed view and a fallible encoder that preflights before changing output. There is no replacement CPU ceiling. Accept exactly minor 2.1 with flags 0/1, and 2.2 with flags 0/1/2/3. The topology flag requires a 240-byte fixed area. With flag 2 alone, offsets 200–215 are zero; flag 3 retains the existing startup descriptor there. Reject unknown minors, flags, snapshot versions and nonzero reserved fields. Absence remains distinct from malformed present-empty data. ## Authority, security and reliability The snapshot conveys IDs as data, never firmware-read authority or CPU ownership. Keep all memory-region flags unchanged. Check offset/count arithmetic, complete bounds and disjointness from every metadata table and startup record. Borrow only the caller's immutable blob; parsing allocates nothing. The Bootloader retains enabled MADT entry order and rejects duplicate IDs across xAPIC/x2APIC records. Kernel intake independently rejects duplicates, matches its actual BSP and normalizes the list. These semantic checks and native startup grants belong to their consumers, avoiding a quadratic uniqueness scan in the codec. ## Acceptance criteria - [x] Implement the exact version/flag matrix, borrowed ID view and preflighted encoder. - [x] Cover ID zero/full width, unaligned storage, one and many IDs, absent/empty data, truncation, overflow, reserved fields and every metadata overlap; errors leave output unchanged. - [x] Preserve startup-resource offsets and existing 2.1 acceptance; document producer, consumer and source-lifetime obligations. - [x] Pass formatting, strict Clippy, unit tests, freestanding builds, rustdoc and current component CI without compiler warnings. ## Alternatives and tradeoffs Keeping firmware walkers in Kernel requires continued firmware backing custody. Fixed CPU arrays impose another limit; inferred BSP or peer IDs lose the original topology. A counted data snapshot separates capture from startup while retaining complete identities. Native CPU ownership remains an independent requirement. ## Tracking and rollout Build on [the startup-resource contract](https://git.erikinkinen.fi/erix/lib-handoff/pulls/9). Coordinate a Bootloader capture producer and a Kernel data-intake prerequisite for [native private-address-space switching](https://git.erikinkinen.fi/erix/kernel/pulls/123). Native 1/2/4-CPU image acceptance stays with that coordinated startup work; this component establishes only the data contract.
erikinkinen added this to the Alpha 1 milestone 2026-11-13 13:24:28 +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/lib-handoff#10
No description provided.