From 224adf06d8d4c60f4d07359c6c55a5665028006d Mon Sep 17 00:00:00 2001 From: Jan De Landtsheer Date: Mon, 20 Oct 2025 14:21:47 +0200 Subject: [PATCH] Standardize 2-copy bcachefs topology naming to 'bcachefs-2copy' across code and docs; align parser and Display; update docs and ADR --- docs/API.md | 4 ++-- docs/SCHEMA.md | 4 ++-- docs/SPECS.md | 10 +++++----- docs/adr/0002-defaults-only-no-external-config.md | 10 +++++----- src/config/loader.rs | 6 ++++-- src/types.rs | 11 +++++------ 6 files changed, 23 insertions(+), 22 deletions(-) diff --git a/docs/API.md b/docs/API.md index 97efc48..4e240be 100644 --- a/docs/API.md +++ b/docs/API.md @@ -75,7 +75,7 @@ Configuration types - [struct Config](../src/types.rs:1) - The validated configuration used by the orchestrator, containing logging, device selection rules, topology, partitioning, filesystem options, mount scheme, and report path. - [enum Topology](../src/types.rs:1) - - Values: btrfs_single, bcachefs_single, dual_independent, bcachefs2_copy, ssd_hdd_bcachefs, btrfs_raid1 (opt-in). + - Values: btrfs_single, bcachefs_single, dual_independent, bcachefs-2copy, ssd_hdd_bcachefs, btrfs_raid1 (opt-in). - [struct DeviceSelection](../src/types.rs:1) - Include and exclude regex patterns, minimum size, removable policy. - [struct Partitioning](../src/types.rs:1) @@ -201,7 +201,7 @@ Behavioral notes and contracts - btrfs_single: one data filesystem (btrfs) on the sole disk. - bcachefs_single: one data filesystem (bcachefs) on the sole disk. - dual_independent: independent btrfs filesystems on each eligible disk (one or more). - - bcachefs2_copy: multi-device bcachefs across two or more data partitions with `--replicas=2` (data and metadata). + - bcachefs-2copy: multi-device bcachefs across two or more data partitions with `--replicas=2` (data and metadata). - ssd_hdd_bcachefs: bcachefs spanning SSD (cache/promote) and HDD (backing), labeled ZOSDATA. - btrfs_raid1: only when explicitly requested; otherwise default to independent btrfs. - UEFI vs BIOS: when running under UEFI (`/sys/firmware/efi` present), the BIOS boot partition is suppressed. diff --git a/docs/SCHEMA.md b/docs/SCHEMA.md index 05be410..5648c12 100644 --- a/docs/SCHEMA.md +++ b/docs/SCHEMA.md @@ -32,7 +32,7 @@ device_selection: allow_removable: false # future option; default false min_size_gib: 10 # ignore devices smaller than this (default 10) topology: # desired overall layout; see values below - mode: btrfs_single # btrfs_single | bcachefs_single | dual_independent | bcachefs2_copy | ssd_hdd_bcachefs | btrfs_raid1 + mode: btrfs_single # btrfs_single | bcachefs_single | dual_independent | bcachefs-2copy | ssd_hdd_bcachefs | btrfs_raid1 partitioning: alignment_mib: 1 # GPT alignment in MiB require_empty_disks: true # abort if any partition or FS signatures exist @@ -73,7 +73,7 @@ Topology modes - btrfs_single: One eligible disk. Create BIOS boot (if enabled), ESP 512 MiB, remainder as data. Create a btrfs filesystem labeled ZOSDATA on the data partition. - bcachefs_single: One eligible disk. Create BIOS boot (if enabled), ESP 512 MiB, remainder as data. Create a bcachefs filesystem labeled ZOSDATA on the data partition. - dual_independent: One or more eligible disks. On each disk, create BIOS boot (if enabled) + ESP + data. Create an independent btrfs filesystem labeled ZOSDATA on each data partition. No RAID by default. -- bcachefs2_copy: Two or more eligible disks (minimum 2). Create data partitions and then a single multi-device bcachefs labeled ZOSDATA spanning those data partitions. The mkfs step uses `--replicas=2` (data and metadata). +- bcachefs-2copy: Two or more eligible disks (minimum 2). Create data partitions and then a single multi-device bcachefs labeled ZOSDATA spanning those data partitions. The mkfs step uses `--replicas=2` (data and metadata). - ssd_hdd_bcachefs: One SSD/NVMe and one HDD. Create BIOS boot (if enabled) + ESP on both as required. Create cache (on SSD) and data/backing (on HDD) partitions named zoscache and zosdata respectively. Create a bcachefs labeled ZOSDATA across SSD(HDD) per policy (SSD cache/promote; HDD backing). - btrfs_raid1: Optional mode if explicitly requested. Create mirrored btrfs across two disks for the data role with raid1 profile. Not enabled by default. diff --git a/docs/SPECS.md b/docs/SPECS.md index 38d012e..199c133 100644 --- a/docs/SPECS.md +++ b/docs/SPECS.md @@ -184,7 +184,7 @@ Per-topology specifics - btrfs_single: All roles on the single disk; data formatted as btrfs. - bcachefs_single: All roles on the single disk; data formatted as bcachefs. - dual_independent: On each eligible disk (one or more), create BIOS boot (if applicable), ESP, and data. -- bcachefs_2copy: Create data partitions on two or more disks; later formatted as one multi-device bcachefs spanning all data partitions. +- bcachefs-2copy: Create data partitions on two or more disks; later formatted as one multi-device bcachefs spanning all data partitions. - ssd_hdd_bcachefs: SSD gets BIOS boot + ESP + zoscache; HDD gets BIOS boot + ESP + zosdata; combined later into one bcachefs. - btrfs_raid1: Two disks minimum; data partitions mirrored via btrfs RAID1. @@ -203,12 +203,12 @@ Application Kinds - Vfat for ESP, label ZOSBOOT. - Btrfs for data in btrfs_single, dual_independent, and btrfs_raid1 (with RAID1 profile). -- Bcachefs for data in bcachefs_single, ssd_hdd_bcachefs (SSD cache + HDD backing), and bcachefs_2copy (multi-device). +- Bcachefs for data in bcachefs_single, ssd_hdd_bcachefs (SSD cache + HDD backing), and bcachefs-2copy (multi-device). - All data filesystems use label ZOSDATA. Defaults - btrfs: compression zstd:3, raid_profile none unless explicitly set; for btrfs_raid1 use -m raid1 -d raid1. -- bcachefs: cache_mode promote, compression zstd, checksum crc32c; for bcachefs_2copy use `--replicas=2` (data and metadata). +- bcachefs: cache_mode promote, compression zstd, checksum crc32c; for bcachefs-2copy use `--replicas=2` (data and metadata). - vfat: ESP label ZOSBOOT. Planning and execution @@ -267,7 +267,7 @@ Kernel cmdline Help text sections - NAME, SYNOPSIS, DESCRIPTION - CONFIG PRECEDENCE -- TOPOLOGIES: btrfs_single, bcachefs_single, dual_independent, bcachefs_2copy, ssd_hdd_bcachefs, btrfs_raid1 +- TOPOLOGIES: btrfs_single, bcachefs_single, dual_independent, bcachefs-2copy, ssd_hdd_bcachefs, btrfs_raid1 - SAFETY AND IDEMPOTENCY - REPORTS - EXIT CODES: 0 success or already_provisioned, non-zero on error @@ -280,7 +280,7 @@ Scenarios to scaffold in [tests/](tests/) - Single disk 40 GiB virtio: validates btrfs_single topology end-to-end smoke. - Dual NVMe 40 GiB each: validates dual_independent topology (independent btrfs per disk). - SSD NVMe + HDD virtio: validates ssd_hdd_bcachefs topology (bcachefs with SSD cache/promote, HDD backing). -- Three disks: validates bcachefs_2copy across data partitions using `--replicas=2`. +- Three disks: validates bcachefs-2copy across data partitions using `--replicas=2`. - Negative: no eligible disks, or non-empty disk should abort. Test strategy diff --git a/docs/adr/0002-defaults-only-no-external-config.md b/docs/adr/0002-defaults-only-no-external-config.md index a93f654..3baedf7 100644 --- a/docs/adr/0002-defaults-only-no-external-config.md +++ b/docs/adr/0002-defaults-only-no-external-config.md @@ -26,17 +26,17 @@ Decision - Allowed cmdline overrides: btrfs_single, bcachefs_single - 2 eligible disks: - Default: dual_independent - - Allowed cmdline overrides: dual_independent, ssd_hdd_bcachefs, btrfs_raid1, bcachefs_2copy + - Allowed cmdline overrides: dual_independent, ssd_hdd_bcachefs, btrfs_raid1, bcachefs-2copy - >2 eligible disks: - Default: btrfs_raid1 - - Allowed cmdline overrides: btrfs_raid1, bcachefs_2copy -- Accept both snake_case and hyphenated forms for VALUE; normalize to [enum Topology](../../src/types.rs:1): + - Allowed cmdline overrides: btrfs_raid1, bcachefs-2copy +- Accept both snake_case and hyphenated forms for VALUE; canonical for two-copy bcachefs is bcachefs-2copy; normalize to [enum Topology](../../src/types.rs:1): - btrfs_single | btrfs-single - bcachefs_single | bcachefs-single - dual_independent | dual-independent - ssd_hdd_bcachefs | ssd-hdd-bcachefs - btrfs_raid1 | btrfs-raid1 - - bcachefs_2copy | bcachefs-2copy + - bcachefs-2copy - Kernel cmdline parsing beyond topology is deferred; future extensions for VM workflows may be proposed separately. Rationale @@ -67,7 +67,7 @@ Defaults (authoritative) - Filesystems: - ESP: vfat labeled ZOSBOOT - Data: label ZOSDATA - - Backend per topology (btrfs for btrfs_*; bcachefs for ssd_hdd_bcachefs and bcachefs_2copy) + - Backend per topology (btrfs for btrfs_*; bcachefs for ssd_hdd_bcachefs and bcachefs-2copy) - Mount scheme: - Root-mount all data filesystems under /var/mounts/{UUID}; final subvolume/subdir mounts from the primary data FS to /var/cache/{system,etc,modules,vm-meta}; fstab remains optional. - Idempotency: diff --git a/src/config/loader.rs b/src/config/loader.rs index c4cc8f3..5304be8 100644 --- a/src/config/loader.rs +++ b/src/config/loader.rs @@ -292,7 +292,8 @@ pub fn kernel_cmdline_topology() -> Option { None } -/// Helper to parse known topology tokens in kebab- or snake-case. +//// Helper to parse known topology tokens (canonical names only). +//// Note: underscores are normalized to hyphens prior to matching. fn parse_topology_token(s: &str) -> Option { let k = s.trim().to_ascii_lowercase().replace('_', "-"); match k.as_str() { @@ -300,7 +301,8 @@ fn parse_topology_token(s: &str) -> Option { "bcachefs-single" => Some(Topology::BcachefsSingle), "dual-independent" => Some(Topology::DualIndependent), "ssd-hdd-bcachefs" => Some(Topology::SsdHddBcachefs), - "bcachefs2-copy" | "bcachefs-2copy" | "bcachefs-2-copy" => Some(Topology::Bcachefs2Copy), + // Canonical single notation for two-copy bcachefs topology + "bcachefs-2copy" => Some(Topology::Bcachefs2Copy), "btrfs-raid1" => Some(Topology::BtrfsRaid1), _ => None, } diff --git a/src/types.rs b/src/types.rs index 34beeed..02fa62a 100644 --- a/src/types.rs +++ b/src/types.rs @@ -65,11 +65,9 @@ pub enum Topology { #[value(alias = "ssd-hdd-bcachefs")] SsdHddBcachefs, /// Multi-device bcachefs with two replicas (data+metadata). - #[value( - alias = "bcachefs2-copy", - alias = "bcachefs-2copy", - alias = "bcachefs-2-copy" - )] + /// Canonical token: bcachefs-2copy + #[serde(rename = "bcachefs-2copy")] + #[value(alias = "bcachefs-2copy")] Bcachefs2Copy, /// Optional mirrored btrfs across two disks when explicitly requested. #[value(alias = "btrfs-raid1")] @@ -83,7 +81,8 @@ impl std::fmt::Display for Topology { Topology::BcachefsSingle => "bcachefs_single", Topology::DualIndependent => "dual_independent", Topology::SsdHddBcachefs => "ssd_hdd_bcachefs", - Topology::Bcachefs2Copy => "bcachefs2_copy", + // Canonical single notation for two-copy bcachefs topology + Topology::Bcachefs2Copy => "bcachefs-2copy", Topology::BtrfsRaid1 => "btrfs_raid1", }; f.write_str(s)