tfgrid/zosstorage
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: sync with code (topologies, mount scheme, CLI flags, UEFI/BIOS, fstab) and fix relative src links in docs/ to ../src/

Browse Source
This commit is contained in:
Jan De Landtsheer
2025-09-29 23:24:25 +02:00
parent 7cef73368b
commit b0d8c0bc75
9 changed files with 451 additions and 373 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
PROMPT.md
View File

@@ -24,7 +24,7 @@ Device Discovery
Partitioning Requirements
- Use GPT exclusively. Honor 1 MiB alignment boundaries.
- For BIOS compatibility, create a small `bios_boot` partition (exact size TBD—assume 1 MiB for now, placed first).
- For BIOS compatibility on BIOS systems, create a small `bios_boot` partition (size 1 MiB, placed first). When running under UEFI (`/sys/firmware/efi` present), the BIOS boot partition is suppressed.
- Create a 512 MiB FAT32 ESP on each disk, label `ZOSBOOT`. Each ESP is independent; synchronization will be handled by another tool (out of scope). Ensure unique partition UUIDs while keeping identical labels.
- Remaining disk capacity is provisioned per configuration (see below).
- Before making changes, verify the device has no existing partitions or filesystem signatures; abort otherwise.
@@ -51,11 +51,11 @@ Filesystem Provisioning
Configuration Input
- Accept configuration via:
* Kernel command line parameter (name TBD, e.g., `zosstorage.config=`) pointing to a YAML configuration descriptor.
* Optional CLI flags when run in user space (must mirror kernel cmdline semantics).
* On-disk YAML config file (default path TBD, e.g., `/etc/zosstorage/config.yaml`).
- Establish clear precedence: kernel cmdline overrides CLI arguments, which override config file defaults. No interactive prompts inside initramfs.
- YAML schema must at least describe disk selection rules, desired filesystem layout, boot partition preferences, filesystem options, mount targets, and logging verbosity. Document the schema and provide validation.
* Kernel command line parameter `zosstorage.config=` pointing to a YAML configuration descriptor.
* Optional CLI flags when run in user space (mirror kernel cmdline semantics).
* On-disk YAML config file (default path `/etc/zosstorage/config.yaml`).
- Precedence: kernel cmdline overrides CLI arguments, which override config file, which override built-in defaults. No interactive prompts inside initramfs.
- YAML schema must describe disk selection rules, desired filesystem layout, boot partition preferences, filesystem options, mount targets, and logging verbosity. See [docs/SCHEMA.md](docs/SCHEMA.md) and [src/types.rs](src/types.rs:1).
State Reporting
- After successful provisioning, emit a JSON state report (path TBD, e.g., `/run/zosstorage/state.json`) capturing:
@@ -70,7 +70,7 @@ Logging
- By default, logs go to stderr; design for optional redirection to a file (path TBD). Avoid using `println!`.
System Integration
- Decide whether to generate `/etc/fstab` entries; if enabled, produce deterministic ordering and documentation. Otherwise, document alternative mount management.
- `/etc/fstab` generation: optional via CLI/config. When enabled, write only the four final subvolume/subdir mount entries (system, etc, modules, vm-meta) with `UUID=` sources in deterministic order. Root mounts under `/var/mounts/{UUID}` are runtime-only and excluded from fstab.
- After provisioning, ensure the initramfs can mount the new filesystems (e.g., call `udevadm settle` if necessary). No external services are invoked.
- No responsibility for updating `vmlinuz.efi`; another subsystem handles kernel updates.
@@ -95,11 +95,17 @@ Documentation & Deliverables
- Include architectural notes describing module boundaries (device discovery, partitioning, filesystem provisioning, config parsing, logging, reporting).
Open Items (call out explicitly)
- Exact sizes and ordering for `bios_boot` partition awaiting confirmation; note assumptions in code and documentation.
- Mount point naming scheme under `/var/cache` (per-UUID vs. config-defined) still to be finalized.
- Filesystem-specific tuning parameters (compression, RAID values, `bcachefs` options) require explicit defaults from stakeholders.
- Path/location for YAML config, kernel cmdline key, JSON report path, and optional log file path need final confirmation.
- Decision whether `/etc/fstab` is generated remains pending.
- BIOS vs UEFI: `bios_boot` partition size fixed at 1 MiB and created only on BIOS systems; suppressed under UEFI (`/sys/firmware/efi` present).
- Mount scheme finalized:
- Root mounts for each data filesystem at `/var/mounts/{UUID}` (runtime only).
- Final subvolume/subdir mounts from the primary data filesystem to `/var/cache/{system,etc,modules,vm-meta}`.
- Filesystem-specific tuning parameters (compression, RAID values, `bcachefs` options) remain open for refinement; sensible defaults applied.
- Config paths and keys stabilized:
- Kernel cmdline key: `zosstorage.config=`
- Default config file: `/etc/zosstorage/config.yaml`
- Default report path: `/run/zosstorage/state.json`
- Optional log file: `/run/zosstorage/zosstorage.log`
- `/etc/fstab` generation policy decided: optional flag; writes only the four final subvolume/subdir entries.
Implementation Constraints
- Stick to clear module boundaries. Provide unit tests where possible (e.g., config parsing, device filtering).