Refine default orchestration flow and documentation
- Document defaults-only configuration, kernel topology override, and deprecated CLI flags in README - Mark schema doc as deprecated per ADR-0002 - Warn that --topology/--config are ignored; adjust loader/main/context flow - Refactor orchestrator run() to auto-select mount/apply, reuse state when already provisioned, and serialize topology via Display - Add Callgraph/FUNCTION_LIST/ADR docs tracking the new behavior - Derive Eq for Topology to satisfy updated CLI handling
This commit is contained in:
294
docs/FUNCTION_LIST.md
Normal file
294
docs/FUNCTION_LIST.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# Function Reference - Call Graph Analysis
|
||||
|
||||
> This documentation is automatically derived from [`Callgraph.svg`](Callgraph.svg) and provides a comprehensive overview of all functions in the zosstorage project, organized by module.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Main Entry Points](#main-entry-points)
|
||||
- [CLI & Configuration](#cli--configuration)
|
||||
- [Orchestration](#orchestration)
|
||||
- [Device Discovery](#device-discovery)
|
||||
- [Partition Management](#partition-management)
|
||||
- [Filesystem Operations](#filesystem-operations)
|
||||
- [Mount Operations](#mount-operations)
|
||||
- [Idempotency & State](#idempotency--state)
|
||||
- [Reporting](#reporting)
|
||||
- [Utilities](#utilities)
|
||||
- [Logging](#logging)
|
||||
- [Type Definitions](#type-definitions)
|
||||
|
||||
---
|
||||
|
||||
## Main Entry Points
|
||||
|
||||
### [`src/main.rs`](../src/main.rs)
|
||||
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `main()` | Application entry point; initializes the program and handles top-level errors |
|
||||
| `real_main()` | Core application logic; orchestrates the main workflow after initialization |
|
||||
|
||||
---
|
||||
|
||||
## CLI & Configuration
|
||||
|
||||
### [`src/cli/args.rs`](../src/cli/args.rs)
|
||||
|
||||
**Structs:** `Cli`, `LogLevelArg` (enum)
|
||||
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `from_args()` | Parses command-line arguments and returns a `Cli` configuration object |
|
||||
|
||||
### [`src/config/loader.rs`](../src/config/loader.rs)
|
||||
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `load_and_merge()` | Loads configuration from multiple sources and merges them into a unified config |
|
||||
| `validate()` | Validates the merged configuration for correctness and completeness |
|
||||
| `to_value()` | Converts configuration structures to internal value representation |
|
||||
| `merge_value()` | Recursively merges configuration values, handling conflicts appropriately |
|
||||
| `cli_overlay_value()` | Overlays CLI-provided values onto existing configuration |
|
||||
| `kernel_cmdline_topology()` | Extracts topology information from kernel command line parameters |
|
||||
| `parse_topology_token()` | Parses individual topology tokens from kernel cmdline |
|
||||
| `default_config()` | Generates default configuration values when no config file is present |
|
||||
|
||||
---
|
||||
|
||||
## Orchestration
|
||||
|
||||
### [`src/orchestrator/run.rs`](../src/orchestrator/run.rs)
|
||||
|
||||
**Structs:** `Context`
|
||||
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `Context::new()` | Creates a new orchestration context with default settings |
|
||||
| `Context::with_show()` | Builder method to enable show/dry-run mode |
|
||||
| `Context::with_apply()` | Builder method to enable apply mode (actual execution) |
|
||||
| `Context::with_report_path()` | Builder method to set the report output path |
|
||||
| `Context::with_mount_existing()` | Builder method to configure mounting of existing filesystems |
|
||||
| `Context::with_report_current()` | Builder method to enable reporting of current system state |
|
||||
| `Context::with_topology_from_cli()` | Builder method to set topology from CLI arguments |
|
||||
| `Context::with_topology_from_cmdline()` | Builder method to set topology from kernel cmdline |
|
||||
| `run()` | Main orchestration function; coordinates all storage operations |
|
||||
| `build_device_filter()` | Constructs device filter based on configuration and user input |
|
||||
| `enforce_empty_disks()` | Validates that target disks are empty before proceeding |
|
||||
| `role_str()` | Converts partition role enum to human-readable string |
|
||||
| `build_summary_json()` | Builds a JSON summary of operations performed |
|
||||
|
||||
---
|
||||
|
||||
## Device Discovery
|
||||
|
||||
### [`src/device/discovery.rs`](../src/device/discovery.rs)
|
||||
|
||||
**Structs:** `Disk`, `DeviceFilter`, `SysProvider`
|
||||
**Traits:** `DeviceProvider`
|
||||
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `DeviceFilter::matches()` | Checks if a device matches the configured filter criteria |
|
||||
| `SysProvider::new()` | Creates a new sysfs-based device provider |
|
||||
| `SysProvider::list_block_devices()` | Lists all block devices found via sysfs |
|
||||
| `SysProvider::probe_properties()` | Probes detailed properties of a specific device |
|
||||
| `discover()` | Entry point for device discovery using default provider |
|
||||
| `discover_with_provider()` | Device discovery with custom provider (for testing/flexibility) |
|
||||
| `is_ignored_name()` | Checks if device name should be ignored (loop, ram, etc.) |
|
||||
| `sys_block_path()` | Constructs sysfs path for a given block device |
|
||||
| `base_name()` | Extracts base device name from path |
|
||||
| `is_removable_sysfs()` | Checks if device is removable via sysfs |
|
||||
| `is_partition_sysfs()` | Checks if device is a partition via sysfs |
|
||||
| `read_disk_size_bytes()` | Reads disk size in bytes from sysfs |
|
||||
| `read_rotational()` | Determines if disk is rotational (HDD) or not (SSD) |
|
||||
| `read_model_serial()` | Reads device model and serial number |
|
||||
| `read_optional_string()` | Utility to safely read optional string values from sysfs |
|
||||
|
||||
---
|
||||
|
||||
## Partition Management
|
||||
|
||||
### [`src/partition/plan.rs`](../src/partition/plan.rs)
|
||||
|
||||
**Structs:** `PartitionSpec`, `DiskPlan`, `PartitionPlan`, `PartitionResult`
|
||||
**Enums:** `PartRole`
|
||||
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `plan_partitions()` | Creates partition plans for all target disks based on topology |
|
||||
| `apply_partitions()` | Executes partition plans using sgdisk tool |
|
||||
| `type_code()` | Returns GPT partition type code for a given partition role |
|
||||
| `part_dev_path()` | Constructs device path for a partition (e.g., /dev/sda1) |
|
||||
| `sector_size_bytes()` | Reads logical sector size of disk |
|
||||
| `parse_sgdisk_info()` | Parses output from sgdisk to extract partition information |
|
||||
|
||||
---
|
||||
|
||||
## Filesystem Operations
|
||||
|
||||
### [`src/fs/plan.rs`](../src/fs/plan.rs)
|
||||
|
||||
**Structs:** `FsSpec`, `FsPlan`, `FsResult`
|
||||
**Enums:** `FsKind`
|
||||
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `plan_filesystems()` | Plans filesystem creation for all partitions |
|
||||
| `make_filesystems()` | Creates filesystems according to plan (mkfs.* tools) |
|
||||
| `capture_uuid()` | Captures UUID of newly created filesystem |
|
||||
| `parse_blkid_export()` | Parses blkid export format to extract filesystem metadata |
|
||||
| `probe_existing_filesystems()` | Detects existing filesystems on partitions |
|
||||
|
||||
---
|
||||
|
||||
## Mount Operations
|
||||
|
||||
### [`src/mount/ops.rs`](../src/mount/ops.rs)
|
||||
|
||||
**Structs:** `PlannedMount`, `PlannedSubvolMount`, `MountPlan`, `MountResult`
|
||||
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `fstype_str()` | Converts FsKind enum to mount filesystem type string |
|
||||
| `plan_mounts()` | Creates mount plans for all filesystems |
|
||||
| `apply_mounts()` | Executes mount operations and creates mount points |
|
||||
| `maybe_write_fstab()` | Conditionally writes /etc/fstab entries for persistent mounts |
|
||||
|
||||
---
|
||||
|
||||
## Idempotency & State
|
||||
|
||||
### [`src/idempotency/mod.rs`](../src/idempotency/mod.rs)
|
||||
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `detect_existing_state()` | Detects existing partitions and filesystems to avoid destructive operations |
|
||||
| `is_empty_disk()` | Checks if a disk has no partition table or filesystems |
|
||||
| `parse_blkid_export()` | Parses blkid output to identify existing filesystems |
|
||||
| `read_proc_partitions_names()` | Reads partition names from /proc/partitions |
|
||||
| `base_name()` | Extracts base name from device path |
|
||||
| `is_partition_of()` | Checks if one device is a partition of another |
|
||||
|
||||
---
|
||||
|
||||
## Reporting
|
||||
|
||||
### [`src/report/state.rs`](../src/report/state.rs)
|
||||
|
||||
**Structs:** `StateReport`
|
||||
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `build_report()` | Builds comprehensive state report of operations performed |
|
||||
| `write_report()` | Writes report to specified output path (JSON format) |
|
||||
|
||||
---
|
||||
|
||||
## Utilities
|
||||
|
||||
### [`src/util/mod.rs`](../src/util/mod.rs)
|
||||
|
||||
**Structs:** `CmdOutput`
|
||||
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `which_tool()` | Locates external tool in PATH (sgdisk, mkfs.*, etc.) |
|
||||
| `run_cmd()` | Executes shell command and returns exit status |
|
||||
| `run_cmd_capture()` | Executes command and captures stdout/stderr |
|
||||
| `udev_settle()` | Waits for udev to process device events |
|
||||
| `is_efi_boot()` | Detects if system booted in EFI mode |
|
||||
|
||||
---
|
||||
|
||||
## Logging
|
||||
|
||||
### [`src/logging/mod.rs`](../src/logging/mod.rs)
|
||||
|
||||
**Structs:** `LogOptions`
|
||||
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `LogOptions::from_cli()` | Creates logging configuration from CLI arguments |
|
||||
| `level_from_str()` | Converts string to log level enum |
|
||||
| `init_logging()` | Initializes logging subsystem with configured options |
|
||||
|
||||
---
|
||||
|
||||
## Type Definitions
|
||||
|
||||
### [`src/types.rs`](../src/types.rs)
|
||||
|
||||
**Core Configuration Structures:**
|
||||
|
||||
- `Config` - Top-level configuration structure
|
||||
- `LoggingConfig` - Logging configuration
|
||||
- `DeviceSelection` - Device selection criteria
|
||||
- `Topology` - Storage topology definition (enum)
|
||||
- `Partitioning` - Partition layout specification
|
||||
- `BiosBootSpec`, `EspSpec`, `DataSpec`, `CacheSpec` - Partition type specifications
|
||||
- `FsOptions`, `BtrfsOptions`, `BcachefsOptions`, `VfatOptions` - Filesystem options
|
||||
- `MountScheme`, `MountSchemeKind` - Mount configuration
|
||||
- `ReportOptions` - Report generation configuration
|
||||
|
||||
### [`src/errors.rs`](../src/errors.rs)
|
||||
|
||||
**Error Types:**
|
||||
|
||||
- `Error` - Main error enum for all error conditions
|
||||
- `Result<T>` - Type alias for `std::result::Result<T, Error>`
|
||||
|
||||
---
|
||||
|
||||
## Call Graph Relationships
|
||||
|
||||
### Main Execution Flow
|
||||
|
||||
```
|
||||
main() → real_main() → orchestrator::run()
|
||||
↓
|
||||
├─→ cli::from_args()
|
||||
├─→ config::load_and_merge()
|
||||
├─→ logging::init_logging()
|
||||
├─→ device::discover()
|
||||
├─→ partition::plan_partitions()
|
||||
├─→ partition::apply_partitions()
|
||||
├─→ fs::plan_filesystems()
|
||||
├─→ fs::make_filesystems()
|
||||
├─→ mount::plan_mounts()
|
||||
├─→ mount::apply_mounts()
|
||||
└─→ report::build_report() / write_report()
|
||||
```
|
||||
|
||||
### Key Dependencies
|
||||
|
||||
- **Orchestrator** (`run()`) calls: All major subsystems
|
||||
- **Device Discovery** uses: Utilities for system probing
|
||||
- **Partition/FS/Mount** operations use: Utilities for command execution
|
||||
- **All operations** call: `util::run_cmd()` or `util::run_cmd_capture()`
|
||||
- **Idempotency checks** called by: Orchestrator before destructive operations
|
||||
|
||||
---
|
||||
|
||||
## Function Count Summary
|
||||
|
||||
- **Main Entry**: 2 functions
|
||||
- **CLI & Config**: 9 functions
|
||||
- **Orchestration**: 13 functions
|
||||
- **Device Discovery**: 14 functions
|
||||
- **Partition Management**: 6 functions
|
||||
- **Filesystem Operations**: 5 functions
|
||||
- **Mount Operations**: 4 functions
|
||||
- **Idempotency**: 6 functions
|
||||
- **Reporting**: 2 functions
|
||||
- **Utilities**: 6 functions
|
||||
- **Logging**: 3 functions
|
||||
|
||||
**Total: 70 documented functions** across 15 source files
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- Original call graph visualization: [`docs/Callgraph.svg`](Callgraph.svg)
|
||||
- Architecture documentation: [`docs/ARCHITECTURE.md`](ARCHITECTURE.md)
|
||||
- API documentation: [`docs/API.md`](API.md)
|
||||
Reference in New Issue
Block a user