[FEATURE] Expose explicit original-device durability barriers #3

Closed
opened 2026-09-30 21:29:01 +02:00 by erikinkinen · 0 comments
Owner

Problem and motivation

Persistent filesystem metadata needs an explicit device durability boundary. The block contract currently exposes reads and writes but no flush request or declaration of whether durability can be established. FAT publication tracking stops after uncertain writes; it is not a rollback journal. Complete FAT metadata and later fsync/fdatasync must not infer storage persistence from an unqualified transport success.

Proposed behavior and scope

Add a receipt-free block flush family (0x704): a 16-byte request binds request ID, operation and original device ID; a 24-byte response repeats those identities, includes a known result and zero reserved word. Add a descriptive FLUSH_SUPPORTED device flag and BlockDevice::flush; its default refuses rather than inventing success. The client uses only its supplied endpoint, validates the entire response, and never resubmits an accepted request.

Blockd resolves the requested original whole disk or partition under its current provider binding, admits only writable media with an explicit durability guarantee, and forwards one barrier to that exact backing device. It never fans out to other devices or converts a range check into a whole-device write. Success covers writes completed before the barrier, not concurrent future writes. Partition flush may persist the backing device cache but grants no additional read, write or endpoint access.

Preserve the current Virtio feature negotiation. With FLUSH offered, but neither FLUSH nor CONFIG_WCE negotiated, the specification requires completed writes to be stable. Retain this precise original negotiation evidence and advertise flush support only for that known writable case. Since this driver serializes one request at a time, a flush after its operational-state check can succeed from that established write-through guarantee. Unknown guarantees and read-only devices refuse. Do not negotiate writeback caching and thereby weaken existing write acknowledgments. A future hardware-flush/writeback implementation must preserve this public durability contract.

Derive this policy from the OASIS Virtio 1.3 initialization and operation requirements, sections 5.2.5 and 5.2.6.2. No third-party implementation code is used. Provider wrappers must forward the explicit barrier and retain their uncertain-publication accounting.

Authority, security and reliability

The original block endpoint remains the sole authority. Numeric device IDs and the support flag are descriptive, not grants. No new startup capability, provider discovery route, DMA mapping, transferred receipt or retained caller is added. Validate request and reply storage before any effect; reject malformed, unknown-result, miscorrelated and unavailable-provider outcomes. Preserve the existing provider-binding retirement on uncertain transport/reply failure. Read-only and unsupported devices never claim a successful flush.

The result relies on the hardware/provider contract and is not proof against faulty hardware, host storage configured to lie about persistence, or an unimplemented filesystem recovery algorithm. Complete FAT metadata, journal recovery and compatibility fsync/fdatasync remain separate unfinished work.

Acceptance criteria

Checklist
  • Exact independently specified wire fixtures, atomic encoding and hostile-input/correlation controls.
  • Explicit client method and refusal default; no ambient endpoint or fabricated success.
  • Original partition/whole-device routing, capability flag propagation, read-only/unsupported denial and failure cleanup.
  • Retained original Virtio negotiation evidence, operational-state admission and refusal for unknown/writeback modes.
  • Original provider wrapper forwarding and publication uncertainty handling.
  • Meaningful native VM witness through the mounted block path; author controls without claiming runtime power-loss proof.
  • Inline/component/manual documentation and coherent signed dependency publication with exact issue/PR/master readbacks.

Alternatives and tradeoffs

Automatically negotiating FLUSH without changing every existing writer could switch to writeback and regress current persistence. Requiring a redundant hardware command on a proven write-through device would add I/O without establishing a stronger guarantee. Returning success for any unsupported provider would fabricate evidence. The explicit operation therefore separates known completion semantics from unavailable durability while keeping current device negotiation intact.

Tracking and rollout

This is a prerequisite for complete source-qualified file status and the phase completion requirements. Coordinate LibBlock, Blockd, the Virtio block driver, filesystem wrappers, the native workload and maintained documentation before publishing the immutable graph. Existing read/write APIs remain supported; the new default is a refusal for providers without an explicit guarantee.

Explicit original-device durability barriers — 30 September 2026

LibBlock defines exact receipt-free 16/24-byte flush framing (0x704), full request/device correlation, atomic encoding, a descriptive support flag and a refusal default. Its client uses only supplied transport and never replays an accepted request. Blockd forwards one admitted whole-disk or partition barrier to its original provider, preserving read-only/unsupported refusal and existing provider-binding retirement. No new capability or data-access route is added.

Unknown guarantees refuse.

They cover independent wire evidence, atomic refusal, miscorrelation, no replay, original partition selection, negotiated-feature proof, witness order and failed persistence. Two native VM scenarios exercise the original mounted FAT partition: writable media rewrites original boot bytes, completes the barrier and compares a fresh read; read-only media must refuse without data I/O.

The full status/directory feature remains open for complete FAT metadata and integration; the wider durability item remains open for filesystem recovery, truncate/sparse growth and compatibility fsync/fdatasync. Both full EriX guest build generations and external Rust/LLVM rebuilding inside EriX remain required and unperformed.

Related records and contracts
Repository Links
blockd issue 3, PR 2
docs PR 4
drv-virtio-block PR 2
e2fsd PR 3
fatd PR 3
integration PR 12
lib-block PR 2, durability.md
rootd PR 2
## Problem and motivation Persistent filesystem metadata needs an explicit device durability boundary. The block contract currently exposes reads and writes but no flush request or declaration of whether durability can be established. FAT publication tracking stops after uncertain writes; it is not a rollback journal. Complete FAT metadata and later fsync/fdatasync must not infer storage persistence from an unqualified transport success. ## Proposed behavior and scope Add a receipt-free block flush family (`0x704`): a 16-byte request binds request ID, operation and original device ID; a 24-byte response repeats those identities, includes a known result and zero reserved word. Add a descriptive `FLUSH_SUPPORTED` device flag and `BlockDevice::flush`; its default refuses rather than inventing success. The client uses only its supplied endpoint, validates the entire response, and never resubmits an accepted request. Blockd resolves the requested original whole disk or partition under its current provider binding, admits only writable media with an explicit durability guarantee, and forwards one barrier to that exact backing device. It never fans out to other devices or converts a range check into a whole-device write. Success covers writes completed before the barrier, not concurrent future writes. Partition flush may persist the backing device cache but grants no additional read, write or endpoint access. Preserve the current Virtio feature negotiation. With FLUSH offered, but neither FLUSH nor CONFIG_WCE negotiated, the specification requires completed writes to be stable. Retain this precise original negotiation evidence and advertise flush support only for that known writable case. Since this driver serializes one request at a time, a flush after its operational-state check can succeed from that established write-through guarantee. Unknown guarantees and read-only devices refuse. Do not negotiate writeback caching and thereby weaken existing write acknowledgments. A future hardware-flush/writeback implementation must preserve this public durability contract. Derive this policy from the [OASIS Virtio 1.3 initialization and operation requirements](https://docs.oasis-open.org/virtio/virtio/v1.3/virtio-v1.3.html), sections 5.2.5 and 5.2.6.2. No third-party implementation code is used. Provider wrappers must forward the explicit barrier and retain their uncertain-publication accounting. ## Authority, security and reliability The original block endpoint remains the sole authority. Numeric device IDs and the support flag are descriptive, not grants. No new startup capability, provider discovery route, DMA mapping, transferred receipt or retained caller is added. Validate request and reply storage before any effect; reject malformed, unknown-result, miscorrelated and unavailable-provider outcomes. Preserve the existing provider-binding retirement on uncertain transport/reply failure. Read-only and unsupported devices never claim a successful flush. The result relies on the hardware/provider contract and is not proof against faulty hardware, host storage configured to lie about persistence, or an unimplemented filesystem recovery algorithm. Complete FAT metadata, journal recovery and compatibility fsync/fdatasync remain separate unfinished work. ## Acceptance criteria <details> <summary>Checklist</summary> - [x] Exact independently specified wire fixtures, atomic encoding and hostile-input/correlation controls. - [x] Explicit client method and refusal default; no ambient endpoint or fabricated success. - [x] Original partition/whole-device routing, capability flag propagation, read-only/unsupported denial and failure cleanup. - [x] Retained original Virtio negotiation evidence, operational-state admission and refusal for unknown/writeback modes. - [x] Original provider wrapper forwarding and publication uncertainty handling. - [x] Meaningful native VM witness through the mounted block path; author controls without claiming runtime power-loss proof. - [x] Inline/component/manual documentation and coherent signed dependency publication with exact issue/PR/master readbacks. </details> ## Alternatives and tradeoffs Automatically negotiating FLUSH without changing every existing writer could switch to writeback and regress current persistence. Requiring a redundant hardware command on a proven write-through device would add I/O without establishing a stronger guarantee. Returning success for any unsupported provider would fabricate evidence. The explicit operation therefore separates known completion semantics from unavailable durability while keeping current device negotiation intact. ## Tracking and rollout This is a prerequisite for [complete source-qualified file status](https://git.erikinkinen.fi/erix/posixd/issues/25) and the [phase completion requirements](https://git.erikinkinen.fi/erix/integration/issues/65). Coordinate LibBlock, Blockd, the Virtio block driver, filesystem wrappers, the native workload and maintained documentation before publishing the immutable graph. Existing read/write APIs remain supported; the new default is a refusal for providers without an explicit guarantee. ### Explicit original-device durability barriers — 30 September 2026 LibBlock defines exact receipt-free 16/24-byte flush framing (`0x704`), full request/device correlation, atomic encoding, a descriptive support flag and a refusal default. Its client uses only supplied transport and never replays an accepted request. Blockd forwards one admitted whole-disk or partition barrier to its original provider, preserving read-only/unsupported refusal and existing provider-binding retirement. No new capability or data-access route is added. Unknown guarantees refuse. They cover independent wire evidence, atomic refusal, miscorrelation, no replay, original partition selection, negotiated-feature proof, witness order and failed persistence. Two native VM scenarios exercise the original mounted FAT partition: writable media rewrites original boot bytes, completes the barrier and compares a fresh read; read-only media must refuse without data I/O. The full status/directory feature remains open for complete FAT metadata and integration; the wider durability item remains open for filesystem recovery, truncate/sparse growth and compatibility fsync/fdatasync. Both full EriX guest build generations and external Rust/LLVM rebuilding inside EriX remain required and unperformed. <details> <summary>Related records and contracts</summary> | Repository | Links | | --- | --- | | blockd | [issue 3](https://git.erikinkinen.fi/erix/blockd/issues/3), [PR 2](https://git.erikinkinen.fi/erix/blockd/pulls/2) | | docs | [PR 4](https://git.erikinkinen.fi/erix/docs/pulls/4) | | drv-virtio-block | [PR 2](https://git.erikinkinen.fi/erix/drv-virtio-block/pulls/2) | | e2fsd | [PR 3](https://git.erikinkinen.fi/erix/e2fsd/pulls/3) | | fatd | [PR 3](https://git.erikinkinen.fi/erix/fatd/pulls/3) | | integration | [PR 12](https://git.erikinkinen.fi/erix/integration/pulls/12) | | lib-block | [PR 2](https://git.erikinkinen.fi/erix/lib-block/pulls/2), [durability.md](https://git.erikinkinen.fi/erix/lib-block/src/branch/feature/posix-compat/docs/durability.md) | | rootd | [PR 2](https://git.erikinkinen.fi/erix/rootd/pulls/2) | </details>
erikinkinen added this to the Alpha 1 milestone 2026-10-30 09:33:33 +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/blockd#3
No description provided.