zosstorage/docs/FUNCTION_LIST.md

Function Reference - Call Graph Analysis

This documentation is automatically derived from Callgraph.svg and provides a comprehensive overview of all functions in the zosstorage project, organized by module.

Table of Contents

• Main Entry Points
• CLI & Configuration
• Orchestration
• Device Discovery
• Partition Management
• Filesystem Operations
• Mount Operations
• Idempotency & State
• Reporting
• Utilities
• Logging
• Type Definitions

---

Main Entry Points

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

Structs: Cli, LogLevelArg (enum)

Function	Purpose
from_args()	Parses command-line arguments and returns a Cli configuration object

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

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

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

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

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

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

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

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

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

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

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

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
• Architecture documentation: docs/ARCHITECTURE.md
• API documentation: docs/API.md