[FEATURE] Define and validate the pure POSIX compatibility ABI #1

Open
opened 2026-09-12 07:56:23 +02:00 by erikinkinen · 4 comments
Owner

Problem and motivation

Libc and the POSIX service need a shared ABI for layouts, errors, identifiers and wire framing. Independent definitions would permit mismatched sizes, ambiguous ownership and inconsistent malformed-input handling.

Proposed behavior and scope

Define the x86_64 LP64/System V C integer and IPC contracts in a pure library, with matching C declarations, checked file/time and byte-extent arithmetic, stable identifiers and independent layout probes. Use POSIX.1-2024 Base as the semantic reference; optional interfaces, locale behavior and complete development-workload coverage remain separate obligations.

EriX owns its append-only errno numbering. The checked scalar currently recognizes assignments 1–40, including ERANGE=40; zero, negative and unassigned values preserve their complete signed integer on refusal. The raw C alias remains signed-int storage. Exact four-byte little-endian encoding is separate from any containing packet. Compatibility 1.25, NBF1 and NJR1 retain their original assignments 1–39: a new local scalar cannot widen an unchanged wire contract. Earlier values, layouts, version tags, validation precedence and no-write failures remain fixed. See the errno contract and ordinary thread framing.

Native error mapping requires operation context. User-service transport RETRY retains an accepted pending request; a completed kernel wait can report no event only when queue initialization is established; process-stop RETRY can follow an already-issued kill. Unknown codes, missing context, pending effects and uncertain cleanup must remain distinct and cannot trigger resubmission or a generic errno. Confirmed partial byte progress takes precedence over interruption or nonblocking refusal; failed replies and unchecked lengths cannot assert progress.

Permission metadata is deny-only. UID zero has no bypass, a matched class cannot fall through, duplicate ACL qualifiers refuse and a combined group request must be covered by one matching entry. Unknown ACL support cannot become absence. Credential intake, coherent provider observations and native permission enforcement remain runtime duties; the helper must not be inserted indiscriminately before operations on already-open descriptors. See the permission contract and mediator design.

Authority, security and reliability

The library borrows caller storage, allocates no memory and performs no syscall, service discovery, capability operation or thread-local errno access. Numeric identities, generations, paths, byte extents, capability counts and native-completion assertions remain descriptive. Their validation does not establish authentication, access, freshness, native completion or cleanup. Runtime owners retain original sender/route/object custody, transferred capabilities, pending effects and independent teardown obligations. A parsed reply never permits replay of an unknown effect.

Report suspected vulnerabilities privately through SECURITY.md. Preserve exact error precedence and complete output on structural or capacity refusal, and publish compatibility rules before dependent consumers adopt a changed protocol.

Acceptance criteria

Checklist
  • Define x86_64 C ABI sizes, signedness, alignment, byte order, calling conventions,
    structure layouts and ABI version negotiation.
  • Define errno values and a complete native-error mapping table, including missing
    authority, absence, unsupported operation, interruption, would-block, exhaustion, stale
    identity and partial I/O.
  • Define fd/open-description, PID/process-generation, process-group, session, thread
    and realm identifiers as non-authoritative compatibility data.
    Implemented and validated at edc4fdca7edcc717380979fe79f80602f9cc6429 with
    independent integer/domain probes and warning-free push CI 3
    and PR CI 4.
    Definitions and dedicated tests remain unchanged in the scalar successor.
    Actual object identity, generation freshness and authority remain runtime-owner duties.
  • Define file/status/mode/credential/ACL, seek/offset, directory, time,
    signal/action/set, wait and resource-limit types/constants.
  • Define IPC shapes with exact validation, request correlation,
    version/reserved-field rules and normalized capability transfer expectations; keep pure ABI
    parsing free of syscalls or service lookup.
  • Define checked 64-bit file/time arithmetic, C pointer/length handling, integer
    conversion and deterministic overflow/error behavior.
  • Provide reviewed C header declarations corresponding to Rust ABI definitions; test
    layout/constant agreement with independent C and Rust probes.
  • Test malformed/old versions, unknown flags, invalid identifiers, overflow, nonzero
    reserved fields, extra capabilities and noncanonical errors.
  • Publish documented ABI compatibility rules and pass strict crate, header,
    cross-target and exact-head CI gates before consumers depend on it.

For each implementation slice, retain actual formatting, strict Clippy, unit/doctest and warning-denied build results for all altered Rust repositories and valid configurations. Add relevant runtime VM coverage, monitor older unit/VM regressions in exact-head CI, and update canonical component documents and affected technical-manual/API material. Every authored code file must remain below 1,000 physical lines, with meaningful inline documentation and missing_docs enforcement in Rust crates.

The implemented bounded ABI addition is a pure numeric byte extent. ByteExtentV1 stores private u64 address and byte-length fields, with one checked constructor, scalar getters, emptiness and a u128 mathematical exclusive end. It accepts precisely the extents whose mathematical end is at most 2^64; (u64::MAX, 1) and (1, u64::MAX) are valid endpoint cases, while true overflow returns the existing Error::Overflow.

A target-gated raw RawByteExtentV1 and C struct erix_posix_byte_extent_v1 each contain two unsigned 64-bit fields; the selected LP64 C declarations use unsigned long, size 16, alignment 8 and offsets 0/8. Raw-to-checked conversion validates arithmetic only. No pointer conversion/dereference, C callable function, wire message, errno assignment or dependency is added.

Numeric zero, empty extents, unaligned/high coordinates and lengths above the signed-count boundary remain representable if the extent fits. These choices do not establish a usable pointer, CPU canonicality, live mapping, provenance, permissions, ownership or lifetime. Operation-specific null/count rules, Rust reference requirements, mapping freshness, concurrent unmapping, cancellation and authority-backed intake remain required runtime contracts. Empty metadata cannot skip an operation's independent error checks.

Acceptance for this descriptive addition requires literal endpoint/domain regressions and an independent inclusive-end subtraction oracle; malformed raw storage must remain representable and fail only checked conversion. Rust and C size/alignment/offset/type assertions and actual C aggregate argument/return/callback/stack probes must preserve high-bit values and field order. Run the existing strict host/freestanding, default/all-feature, optimization, rustdoc and independent C validation without weakening gates. Update canonical component documentation and the selected manual/API reference after signed publication. This addition does not close the complete pointer-intake or runtime implementation criteria above.

Alternatives and tradeoffs

Keep byte contracts in the shared library rather than duplicating parsers in services. Separate descriptive scalar recognition from each negotiated packet vocabulary and from authenticated native operation results. Full libc/POSIX coverage requires coherent producer and consumer changes; host layout probes alone cannot establish it.

Tracking and rollout

Coordinate the library review, mediator review, Integration review and manual review. The phase completion issue tracks the supplementary requirements and both full guest builds plus the guest Rust/LLVM rebuild. The normative scope remains Phase 6 and AC1–AC24. Status updates belong in comments; unchecked criteria remain open.

## Problem and motivation Libc and the POSIX service need a shared ABI for layouts, errors, identifiers and wire framing. Independent definitions would permit mismatched sizes, ambiguous ownership and inconsistent malformed-input handling. ## Proposed behavior and scope Define the x86_64 LP64/System V C integer and IPC contracts in a pure library, with matching C declarations, checked file/time and byte-extent arithmetic, stable identifiers and independent layout probes. Use POSIX.1-2024 Base as the semantic reference; optional interfaces, locale behavior and complete development-workload coverage remain separate obligations. EriX owns its append-only errno numbering. The checked scalar currently recognizes assignments 1–40, including ERANGE=40; zero, negative and unassigned values preserve their complete signed integer on refusal. The raw C alias remains signed-int storage. Exact four-byte little-endian encoding is separate from any containing packet. Compatibility 1.25, NBF1 and NJR1 retain their original assignments 1–39: a new local scalar cannot widen an unchanged wire contract. Earlier values, layouts, version tags, validation precedence and no-write failures remain fixed. See the [errno contract](https://git.erikinkinen.fi/erix/lib-posixabi/src/commit/12b9906563f51f55bc52b562da1e129b1ad55da6/docs/errno.md) and [ordinary thread framing](https://git.erikinkinen.fi/erix/lib-posixabi/src/commit/12b9906563f51f55bc52b562da1e129b1ad55da6/docs/ordinary-threads.md). Native error mapping requires operation context. User-service transport RETRY retains an accepted pending request; a completed kernel wait can report no event only when queue initialization is established; process-stop RETRY can follow an already-issued kill. Unknown codes, missing context, pending effects and uncertain cleanup must remain distinct and cannot trigger resubmission or a generic errno. Confirmed partial byte progress takes precedence over interruption or nonblocking refusal; failed replies and unchecked lengths cannot assert progress. Permission metadata is deny-only. UID zero has no bypass, a matched class cannot fall through, duplicate ACL qualifiers refuse and a combined group request must be covered by one matching entry. Unknown ACL support cannot become absence. Credential intake, coherent provider observations and native permission enforcement remain runtime duties; the helper must not be inserted indiscriminately before operations on already-open descriptors. See the [permission contract](https://git.erikinkinen.fi/erix/lib-posixabi/src/branch/feature/posix-compat/docs/permissions.md) and [mediator design](https://git.erikinkinen.fi/erix/posixd/issues/10). ## Authority, security and reliability The library borrows caller storage, allocates no memory and performs no syscall, service discovery, capability operation or thread-local errno access. Numeric identities, generations, paths, byte extents, capability counts and native-completion assertions remain descriptive. Their validation does not establish authentication, access, freshness, native completion or cleanup. Runtime owners retain original sender/route/object custody, transferred capabilities, pending effects and independent teardown obligations. A parsed reply never permits replay of an unknown effect. Report suspected vulnerabilities privately through SECURITY.md. Preserve exact error precedence and complete output on structural or capacity refusal, and publish compatibility rules before dependent consumers adopt a changed protocol. ## Acceptance criteria <details> <summary>Checklist</summary> - [ ] Define x86_64 C ABI sizes, signedness, alignment, byte order, calling conventions, structure layouts and ABI version negotiation. - [ ] Define errno values and a complete native-error mapping table, including missing authority, absence, unsupported operation, interruption, would-block, exhaustion, stale identity and partial I/O. - [x] Define fd/open-description, PID/process-generation, process-group, session, thread and realm identifiers as non-authoritative compatibility data. Implemented and validated at `edc4fdca7edcc717380979fe79f80602f9cc6429` with independent integer/domain probes and warning-free [push CI 3](https://git.erikinkinen.fi/erix/lib-posixabi/actions/runs/3) and [PR CI 4](https://git.erikinkinen.fi/erix/lib-posixabi/actions/runs/4). Definitions and dedicated tests remain unchanged in the scalar successor. Actual object identity, generation freshness and authority remain runtime-owner duties. - [ ] Define file/status/mode/credential/ACL, seek/offset, directory, time, signal/action/set, wait and resource-limit types/constants. - [ ] Define IPC shapes with exact validation, request correlation, version/reserved-field rules and normalized capability transfer expectations; keep pure ABI parsing free of syscalls or service lookup. - [ ] Define checked 64-bit file/time arithmetic, C pointer/length handling, integer conversion and deterministic overflow/error behavior. - [ ] Provide reviewed C header declarations corresponding to Rust ABI definitions; test layout/constant agreement with independent C and Rust probes. - [ ] Test malformed/old versions, unknown flags, invalid identifiers, overflow, nonzero reserved fields, extra capabilities and noncanonical errors. - [ ] Publish documented ABI compatibility rules and pass strict crate, header, cross-target and exact-head CI gates before consumers depend on it. For each implementation slice, retain actual formatting, strict Clippy, unit/doctest and warning-denied build results for all altered Rust repositories and valid configurations. Add relevant runtime VM coverage, monitor older unit/VM regressions in exact-head CI, and update canonical component documents and affected technical-manual/API material. Every authored code file must remain below 1,000 physical lines, with meaningful inline documentation and missing_docs enforcement in Rust crates. The implemented bounded ABI addition is a pure numeric byte extent. `ByteExtentV1` stores private `u64` address and byte-length fields, with one checked constructor, scalar getters, emptiness and a `u128` mathematical exclusive end. It accepts precisely the extents whose mathematical end is at most `2^64`; `(u64::MAX, 1)` and `(1, u64::MAX)` are valid endpoint cases, while true overflow returns the existing `Error::Overflow`. A target-gated raw `RawByteExtentV1` and C `struct erix_posix_byte_extent_v1` each contain two unsigned 64-bit fields; the selected LP64 C declarations use `unsigned long`, size 16, alignment 8 and offsets 0/8. Raw-to-checked conversion validates arithmetic only. No pointer conversion/dereference, C callable function, wire message, errno assignment or dependency is added. Numeric zero, empty extents, unaligned/high coordinates and lengths above the signed-count boundary remain representable if the extent fits. These choices do not establish a usable pointer, CPU canonicality, live mapping, provenance, permissions, ownership or lifetime. Operation-specific null/count rules, Rust reference requirements, mapping freshness, concurrent unmapping, cancellation and authority-backed intake remain required runtime contracts. Empty metadata cannot skip an operation's independent error checks. Acceptance for this descriptive addition requires literal endpoint/domain regressions and an independent inclusive-end subtraction oracle; malformed raw storage must remain representable and fail only checked conversion. Rust and C size/alignment/offset/type assertions and actual C aggregate argument/return/callback/stack probes must preserve high-bit values and field order. Run the existing strict host/freestanding, default/all-feature, optimization, rustdoc and independent C validation without weakening gates. Update canonical component documentation and the selected manual/API reference after signed publication. This addition does not close the complete pointer-intake or runtime implementation criteria above. </details> ## Alternatives and tradeoffs Keep byte contracts in the shared library rather than duplicating parsers in services. Separate descriptive scalar recognition from each negotiated packet vocabulary and from authenticated native operation results. Full libc/POSIX coverage requires coherent producer and consumer changes; host layout probes alone cannot establish it. ## Tracking and rollout Coordinate the [library review](https://git.erikinkinen.fi/erix/lib-posixabi/pulls/3), [mediator review](https://git.erikinkinen.fi/erix/posixd/pulls/5), [Integration review](https://git.erikinkinen.fi/erix/integration/pulls/12) and [manual review](https://git.erikinkinen.fi/erix/docs/pulls/4). The [phase completion issue](https://git.erikinkinen.fi/erix/integration/issues/65) tracks the supplementary requirements and both full guest builds plus the guest Rust/LLVM rebuild. The normative scope remains [Phase 6 and AC1–AC24](https://git.erikinkinen.fi/erix/docs/src/branch/main/phases/6.md). Status updates belong in comments; unchecked criteria remain open.
erikinkinen changed title from [FEATURE] [P05] Define and validate the pure POSIX compatibility ABI to [FEATURE] Define and validate the pure POSIX compatibility ABI 2026-09-12 08:02:02 +02:00
Author
Owner

Add ERANGE as standalone EriX error value 40, preserving every existing assignment and the signed-int C representation. This provides a distinct range error for future caller-buffer and numeric conversion interfaces. It adds a scalar value and codec support; choosing a native operation result still requires that operation's own completion and ownership contract.

Keep the existing errno domains of compatibility 1.25, NBF1 birth refusals and NJR1 lifecycle replies unchanged. Their encoders and decoders must reject the new value before output writes, preserving current framing, correlation and error precedence. Use one explicit versioned-domain check rather than implicitly accepting every scalar assignment. Sending ERANGE through those protocols will require a separate coordinated version and consumer update.

The Cstd catalog currently describes its selected 39-value ABI. Its later range-error adoption, conventional error interfaces and native adapters remain separate work under the libc design.

Add `ERANGE` as standalone EriX error value 40, preserving every existing assignment and the signed-int C representation. This provides a distinct range error for future caller-buffer and numeric conversion interfaces. It adds a scalar value and codec support; choosing a native operation result still requires that operation's own completion and ownership contract. Keep the existing errno domains of compatibility 1.25, NBF1 birth refusals and NJR1 lifecycle replies unchanged. Their encoders and decoders must reject the new value before output writes, preserving current framing, correlation and error precedence. Use one explicit versioned-domain check rather than implicitly accepting every scalar assignment. Sending `ERANGE` through those protocols will require a separate coordinated version and consumer update. The Cstd catalog currently describes its selected 39-value ABI. Its later range-error adoption, conventional error interfaces and native adapters remain separate work under the [libc design](https://git.erikinkinen.fi/erix/lib-cstd/issues/1).
Author
Owner

ERANGE=40 is published as a local scalar and C constant. Existing compatibility 1.25, NBF1 and NJR1 packets keep assignments 1–39 and reject ERANGE before output writes. C runtime catalog and manual adoption are continuing; native mappings and guest acceptance remain open.

ERANGE=40 is [published](https://git.erikinkinen.fi/erix/lib-posixabi/src/commit/12b9906563f51f55bc52b562da1e129b1ad55da6/docs/errno.md) as a local scalar and C constant. Existing compatibility 1.25, NBF1 and NJR1 packets keep assignments 1–39 and reject ERANGE before output writes. C runtime catalog and manual adoption are continuing; native mappings and guest acceptance remain open.
Author
Owner

The POSIX ABI now pins LibIPC 61b43723 in 1964ab9e. This is part of the Vfsd dependency repair; the existing interfaces are unchanged, and Integration consumer adoption is in progress.

The POSIX ABI now pins LibIPC `61b43723` in [1964ab9e](https://git.erikinkinen.fi/erix/lib-posixabi/commit/1964ab9e922ee6d0758d080ba7ea8a78feab2ad5). This is part of the [Vfsd dependency repair](https://git.erikinkinen.fi/erix/vfsd/issues/34); the existing interfaces are unchanged, and Integration consumer adoption is in progress.
Author
Owner

Published 09e9c033 completes the pure signal-information and child-observation types: typed causes and payloads, full-width child exit status, explicit wait selectors and non-consuming intent. Missing information remains distinct from a supplied zero. The contract and matching manual describe the scope.

These values perform no signal delivery or wait operation. Authentication, child-status custody, runtime operations and the complete C ABI remain open.

Published `09e9c033` completes the pure signal-information and child-observation types: typed causes and payloads, full-width child exit status, explicit wait selectors and non-consuming intent. Missing information remains distinct from a supplied zero. The [contract](https://git.erikinkinen.fi/erix/lib-posixabi/src/commit/09e9c033ac287d69021459a53934790886f246de/docs/signal-and-wait-information.md) and matching manual describe the scope. These values perform no signal delivery or wait operation. Authentication, child-status custody, runtime operations and the complete C ABI remain open.
erikinkinen added this to the Alpha 1 milestone 2026-10-30 09:34:50 +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-posixabi#1
No description provided.