lcpfs 2026.1.102

// Copyright 2025 LunaOS Contributors
// SPDX-License-Identifier: Apache-2.0
//
// Kernel Integration Guide
// Reference patterns for integrating LCPFS into OS kernels.

//! # Kernel Integration Guide
//!
//! This module provides reference implementations and patterns for integrating
//! LCPFS into operating system kernels. It covers:
//!
//! - VFS (Virtual File System) integration
//! - Memory allocator setup for `no_std`
//! - Block device driver integration
//! - System call interface
//! - Error handling and kernel<->LCPFS boundary

use alloc::boxed::Box;
use alloc::string::String;
use alloc::vec::Vec;

/// VFS operations interface
///
/// This trait defines the interface that a kernel's VFS layer
/// should implement to integrate LCPFS.
///
/// # Example Integration (Linux)
///
/// ```ignore
/// // In Linux kernel module
/// static struct file_operations lcpfs_fops = {
///     .open = lcpfs_open,
///     .read = lcpfs_read,
///     .write = lcpfs_write,
///     .llseek = lcpfs_seek,
///     .release = lcpfs_release,
/// };
/// ```
pub trait VfsOperations {
    /// Open file
    ///
    /// # Arguments
    /// * `path` - File path
    /// * `flags` - Open flags (O_RDONLY, O_WRONLY, etc.)
    /// * `mode` - Permission mode
    ///
    /// # Returns
    /// File descriptor on success
    fn open(&mut self, path: &str, flags: u32, mode: u32) -> Result<i32, i32>;

    /// Read from file
    ///
    /// # Arguments
    /// * `fd` - File descriptor
    /// * `buf` - Buffer to read into
    /// * `count` - Number of bytes to read
    ///
    /// # Returns
    /// Number of bytes read
    fn read(&mut self, fd: i32, buf: &mut [u8], count: usize) -> Result<usize, i32>;

    /// Write to file
    ///
    /// # Arguments
    /// * `fd` - File descriptor
    /// * `buf` - Data to write
    /// * `count` - Number of bytes to write
    ///
    /// # Returns
    /// Number of bytes written
    fn write(&mut self, fd: i32, buf: &[u8], count: usize) -> Result<usize, i32>;

    /// Seek in file
    ///
    /// # Arguments
    /// * `fd` - File descriptor
    /// * `offset` - Seek offset
    /// * `whence` - Seek mode (SEEK_SET, SEEK_CUR, SEEK_END)
    ///
    /// # Returns
    /// New file position
    fn seek(&mut self, fd: i32, offset: i64, whence: i32) -> Result<i64, i32>;

    /// Close file
    ///
    /// # Arguments
    /// * `fd` - File descriptor
    fn close(&mut self, fd: i32) -> Result<(), i32>;

    /// Create directory
    fn mkdir(&mut self, path: &str, mode: u32) -> Result<(), i32>;

    /// Remove file
    fn unlink(&mut self, path: &str) -> Result<(), i32>;

    /// Rename file
    fn rename(&mut self, old_path: &str, new_path: &str) -> Result<(), i32>;

    /// Get file status
    fn stat(&mut self, path: &str) -> Result<FileStat, i32>;
}

/// File status information (similar to POSIX stat)
#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct FileStat {
    /// Device ID
    pub st_dev: u64,
    /// Inode number
    pub st_ino: u64,
    /// File mode (permissions + type)
    pub st_mode: u32,
    /// Number of hard links
    pub st_nlink: u32,
    /// User ID
    pub st_uid: u32,
    /// Group ID
    pub st_gid: u32,
    /// Device ID (if special file)
    pub st_rdev: u64,
    /// Total size in bytes
    pub st_size: u64,
    /// Block size for I/O
    pub st_blksize: u32,
    /// Number of 512B blocks allocated
    pub st_blocks: u64,
}

/// Block device interface
///
/// This trait defines the interface for block devices that LCPFS
/// can use for storage.
///
/// # Example Integration
///
/// ```ignore
/// struct NvmeDevice {
///     controller: NvmeController,
///     namespace_id: u32,
/// }
///
/// impl BlockDevice for NvmeDevice {
///     fn read_blocks(&mut self, lba: u64, count: u32, buf: &mut [u8]) -> Result<(), i32> {
///         self.controller.read(self.namespace_id, lba, count, buf)
///     }
///
///     fn write_blocks(&mut self, lba: u64, count: u32, buf: &[u8]) -> Result<(), i32> {
///         self.controller.write(self.namespace_id, lba, count, buf)
///     }
///
///     fn block_size(&self) -> u32 {
///         4096 // 4KB blocks
///     }
///
///     fn total_blocks(&self) -> u64 {
///         self.controller.namespace_size(self.namespace_id) / 4096
///     }
/// }
/// ```
pub trait BlockDevice {
    /// Read blocks from device
    ///
    /// # Arguments
    /// * `lba` - Logical block address
    /// * `count` - Number of blocks to read
    /// * `buf` - Buffer to read into (must be >= count * block_size)
    fn read_blocks(&mut self, lba: u64, count: u32, buf: &mut [u8]) -> Result<(), i32>;

    /// Write blocks to device
    ///
    /// # Arguments
    /// * `lba` - Logical block address
    /// * `count` - Number of blocks to write
    /// * `buf` - Data to write (must be >= count * block_size)
    fn write_blocks(&mut self, lba: u64, count: u32, buf: &[u8]) -> Result<(), i32>;

    /// Flush device write cache
    fn flush(&mut self) -> Result<(), i32>;

    /// Get block size in bytes
    fn block_size(&self) -> u32;

    /// Get total number of blocks
    fn total_blocks(&self) -> u64;

    /// Get device capacity in bytes
    fn capacity(&self) -> u64 {
        self.total_blocks() * self.block_size() as u64
    }
}

/// Memory allocator interface for `no_std`
///
/// LCPFS requires a custom allocator in `no_std` environments.
/// This shows how to set up the allocator.
///
/// # Example: Linux Kernel Module
///
/// ```ignore
/// use core::alloc::{GlobalAlloc, Layout};
///
/// struct KernelAllocator;
///
/// unsafe impl GlobalAlloc for KernelAllocator {
///     unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
///         // Call kernel's kmalloc
///         extern "C" {
///             fn kmalloc(size: usize, flags: u32) -> *mut u8;
///         }
///         kmalloc(layout.size(), 0x14) // GFP_KERNEL
///     }
///
///     unsafe fn dealloc(&self, ptr: *mut u8, _layout: Layout) {
///         extern "C" {
///             fn kfree(ptr: *mut u8);
///         }
///         kfree(ptr);
///     }
/// }
///
/// #[global_allocator]
/// static ALLOCATOR: KernelAllocator = KernelAllocator;
/// ```
pub struct AllocatorSetup;

impl AllocatorSetup {
    /// Example allocator setup for a custom kernel
    ///
    /// This is a reference implementation showing the pattern.
    /// Real implementations should use kernel-specific allocation functions.
    pub fn example_setup() -> &'static str {
        r#"
// 1. Define allocator wrapping kernel allocation functions
use core::alloc::{GlobalAlloc, Layout};

struct MyKernelAllocator;

unsafe impl GlobalAlloc for MyKernelAllocator {
    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
        // Call your kernel's malloc/kmalloc equivalent
        kernel_malloc(layout.size(), layout.align())
    }

    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
        // Call your kernel's free/kfree equivalent
        kernel_free(ptr, layout.size());
    }
}

#[global_allocator]
static ALLOCATOR: MyKernelAllocator = MyKernelAllocator;

// 2. Define panic handler (required for no_std)
#[panic_handler]
fn panic(info: &core::panic::PanicInfo) -> ! {
    kernel_panic(info);
    loop {}
}

// 3. Define OOM handler
#[alloc_error_handler]
fn alloc_error(layout: Layout) -> ! {
    kernel_panic_fmt("Out of memory: {:?}", layout);
    loop {}
}
"#
    }
}

/// System call error codes (POSIX-compatible)
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(i32)]
pub enum SyscallError {
    /// Operation not permitted
    EPERM = 1,
    /// No such file or directory
    ENOENT = 2,
    /// I/O error
    EIO = 5,
    /// Bad file descriptor
    EBADF = 9,
    /// Out of memory
    ENOMEM = 12,
    /// Permission denied
    EACCES = 13,
    /// File exists
    EEXIST = 17,
    /// Not a directory
    ENOTDIR = 20,
    /// Is a directory
    EISDIR = 21,
    /// Invalid argument
    EINVAL = 22,
    /// File too large
    EFBIG = 27,
    /// No space left on device
    ENOSPC = 28,
    /// Read-only filesystem
    EROFS = 30,
}

/// Convert LCPFS errors to syscall error codes
///
/// # Example
///
/// ```ignore
/// use lcpfs::FsError;
///
/// fn handle_lcpfs_error(err: FsError) -> i32 {
///     match err {
///         FsError::NotFound => -(SyscallError::ENOENT as i32),
///         FsError::DiskFull { .. } => -(SyscallError::ENOSPC as i32),
///         FsError::PermissionDenied => -(SyscallError::EACCES as i32),
///         _ => -(SyscallError::EIO as i32),
///     }
/// }
/// ```
pub fn lcpfs_error_to_errno(error: &str) -> i32 {
    match error {
        "NotFound" => -(SyscallError::ENOENT as i32),
        "DiskFull" => -(SyscallError::ENOSPC as i32),
        "PermissionDenied" => -(SyscallError::EACCES as i32),
        "InvalidArgument" => -(SyscallError::EINVAL as i32),
        "IsDirectory" => -(SyscallError::EISDIR as i32),
        "NotDirectory" => -(SyscallError::ENOTDIR as i32),
        "Exists" => -(SyscallError::EEXIST as i32),
        _ => -(SyscallError::EIO as i32),
    }
}

/// Integration checklist
///
/// Steps to integrate LCPFS into a kernel:
///
/// # 1. Setup Memory Allocator
/// - Implement `GlobalAlloc` wrapping kernel allocator
/// - Set `#[global_allocator]`
/// - Implement `#[panic_handler]`
/// - Implement `#[alloc_error_handler]`
///
/// # 2. Implement Block Device Driver
/// - Create device struct implementing `BlockDevice` trait
/// - Handle device initialization
/// - Implement read/write/flush operations
/// - Handle device errors
///
/// # 3. Integrate VFS Layer
/// - Implement `VfsOperations` trait
/// - Register filesystem type with VFS
/// - Implement mount/unmount handlers
/// - Map LCPFS errors to errno
///
/// # 4. Create System Call Interface
/// - Implement syscall handlers (open, read, write, etc.)
/// - Validate user pointers
/// - Copy data to/from user space
/// - Handle interrupts/signals
///
/// # 5. Initialize LCPFS
/// ```ignore
/// // During kernel init:
/// let device = NvmeDevice::new(0, 0); // Controller 0, Namespace 0
/// let pool = Pool::import_pool(device, "mypool")?;
/// register_filesystem("lcpfs", pool);
/// ```
///
/// # 6. Handle Shutdown
/// ```ignore
/// // During kernel shutdown:
/// pool.sync(); // Flush all pending transactions
/// pool.export(); // Clean unmount
/// ```
pub struct IntegrationChecklist;

/// Example kernel module structure (pseudo-code)
///
/// This shows the overall structure of a kernel module integrating LCPFS.
pub fn example_kernel_module() -> &'static str {
    r#"
// kernel_module.rs - Example LCPFS kernel integration

#![no_std]
#![feature(alloc_error_handler)]

extern crate alloc;

use lcpfs::Pool;
use alloc::boxed::Box;

// 1. Memory allocator setup
mod allocator {
    use core::alloc::{GlobalAlloc, Layout};

    struct KernelAllocator;

    unsafe impl GlobalAlloc for KernelAllocator {
        unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
            kernel::memory::alloc(layout.size(), layout.align())
        }

        unsafe fn dealloc(&self, ptr: *mut u8, _layout: Layout) {
            kernel::memory::free(ptr);
        }
    }

    #[global_allocator]
    static ALLOCATOR: KernelAllocator = KernelAllocator;

    #[panic_handler]
    fn panic(info: &core::panic::PanicInfo) -> ! {
        kernel::panic::panic(info);
        loop {}
    }

    #[alloc_error_handler]
    fn alloc_error(_layout: Layout) -> ! {
        kernel::panic::panic_str("Out of memory");
        loop {}
    }
}

// 2. Block device integration
struct MyBlockDevice {
    device_id: u32,
}

impl lcpfs::BlockDevice for MyBlockDevice {
    fn read_blocks(&mut self, lba: u64, count: u32, buf: &mut [u8]) -> Result<(), i32> {
        kernel::block::read(self.device_id, lba, count, buf)
    }

    fn write_blocks(&mut self, lba: u64, count: u32, buf: &[u8]) -> Result<(), i32> {
        kernel::block::write(self.device_id, lba, count, buf)
    }

    fn flush(&mut self) -> Result<(), i32> {
        kernel::block::flush(self.device_id)
    }

    fn block_size(&self) -> u32 { 4096 }
    fn total_blocks(&self) -> u64 { 1_000_000 }
}

// 3. VFS integration
static mut LCPFS_POOL: Option<Box<Pool>> = None;

#[no_mangle]
pub extern "C" fn lcpfs_init() -> i32 {
    let device = MyBlockDevice { device_id: 0 };

    match Pool::create_pool(device, "mypool") {
        Ok(pool) => {
            // SAFETY INVARIANTS:
            // 1. LCPFS_POOL is global mutable static, accessed only during this init
            // 2. Kernel calls lcpfs_init exactly once during module load
            // 3. No concurrent access (single-threaded initialization)
            // 4. All subsequent accesses via lcpfs_open/read/write happen-after init
            // 5. Pool ownership transferred to 'static via Box::new
            //
            // VERIFICATION: TODO - Prove initialization happens-before all file operations
            //
            // JUSTIFICATION:
            // Kernel modules require global state for pool handle. Rust forbids mutable
            // statics without unsafe. Kernel guarantees single-threaded module_init().
            unsafe { LCPFS_POOL = Some(Box::new(pool)); }
            0
        }
        Err(_) => -1,
    }
}

#[no_mangle]
pub extern "C" fn lcpfs_open(path: *const u8, path_len: usize, flags: u32, mode: u32) -> i32 {
    // SAFETY INVARIANTS:
    // 1. LCPFS_POOL was initialized by prior call to lcpfs_init
    // 2. Kernel guarantees lcpfs_init happens-before lcpfs_open
    // 3. No concurrent modification of LCPFS_POOL after init
    // 4. Pool remains valid for program lifetime ('static)
    //
    // VERIFICATION: TODO - Prove lcpfs_init precedes all file operations
    //
    // JUSTIFICATION:
    // Must access global pool state to service file operations. Kernel module
    // loading order guarantees initialization before filesystem use.
    let pool = unsafe {
        LCPFS_POOL.as_mut()
            .expect("FATAL: LCPFS pool not initialized - call lcpfs_init first")
    };

    // SAFETY INVARIANTS:
    // 1. path pointer is non-null and points to valid memory (kernel guarantee)
    // 2. path_len accurately represents allocated buffer size
    // 3. Buffer contains path_len accessible bytes
    // 4. Memory remains valid for duration of this function call
    // 5. from_raw_parts does not outlive kernel-provided buffer
    //
    // VERIFICATION: TODO - Prove kernel upholds FFI contract
    //
    // JUSTIFICATION:
    // FFI boundary requires converting C pointer + length to Rust slice.
    // Kernel VFS layer provides safety guarantees for syscall arguments.
    let path_slice = unsafe { core::slice::from_raw_parts(path, path_len) };
    let path_str = core::str::from_utf8(path_slice)
        .expect("FATAL: Invalid UTF-8 in path from kernel");

    match pool.create(path_str, mode) {
        Ok(fd) => fd as i32,
        Err(e) => handle_error(e),
    }
}

#[no_mangle]
pub extern "C" fn lcpfs_read(fd: i32, buf: *mut u8, count: usize) -> isize {
    // SAFETY INVARIANTS:
    // 1. LCPFS_POOL initialized by prior lcpfs_init call
    // 2. No concurrent modification after initialization
    // 3. Pool remains valid for program lifetime
    //
    // VERIFICATION: TODO - Same as lcpfs_open
    //
    // JUSTIFICATION:
    // Global pool access required for file I/O operations.
    let pool = unsafe {
        LCPFS_POOL.as_mut()
            .expect("FATAL: LCPFS pool not initialized - call lcpfs_init first")
    };

    // SAFETY INVARIANTS:
    // 1. buf is non-null, writable pointer to count bytes (kernel guarantee)
    // 2. Buffer is properly aligned and allocated by kernel
    // 3. No concurrent access to buf during this syscall
    // 4. Memory remains valid for duration of function call
    // 5. Mutable slice does not outlive kernel buffer
    //
    // VERIFICATION: TODO - Prove kernel VFS upholds buffer safety
    //
    // JUSTIFICATION:
    // Read syscall requires mutable buffer for kernel → userspace data copy.
    // Kernel VFS validates buffer pointer and size before entering filesystem.
    let buffer = unsafe { core::slice::from_raw_parts_mut(buf, count) };

    match pool.read(fd as u64, buffer) {
        Ok(n) => n as isize,
        Err(e) => handle_error(e) as isize,
    }
}

#[no_mangle]
pub extern "C" fn lcpfs_write(fd: i32, buf: *const u8, count: usize) -> isize {
    // SAFETY INVARIANTS:
    // 1. LCPFS_POOL initialized by prior lcpfs_init call
    // 2. No concurrent modification after initialization
    // 3. Pool remains valid for program lifetime
    //
    // VERIFICATION: TODO - Same as lcpfs_open
    //
    // JUSTIFICATION:
    // Global pool access required for file I/O operations.
    let pool = unsafe {
        LCPFS_POOL.as_mut()
            .expect("FATAL: LCPFS pool not initialized - call lcpfs_init first")
    };

    // SAFETY INVARIANTS:
    // 1. buf is non-null, readable pointer to count bytes (kernel guarantee)
    // 2. Buffer is properly aligned and allocated by kernel
    // 3. No concurrent modification of buf during this syscall
    // 4. Memory remains valid for duration of function call
    // 5. Immutable slice does not outlive kernel buffer
    //
    // VERIFICATION: TODO - Prove kernel VFS upholds buffer safety
    //
    // JUSTIFICATION:
    // Write syscall requires immutable buffer for userspace → kernel data copy.
    // Kernel VFS validates buffer pointer and size before entering filesystem.
    let buffer = unsafe { core::slice::from_raw_parts(buf, count) };

    match pool.write(fd as u64, buffer) {
        Ok(n) => n as isize,
        Err(e) => handle_error(e) as isize,
    }
}

fn handle_error(_e: lcpfs::FsError) -> i32 {
    -5 // EIO
}
"#
}

/// Performance tuning guide
pub struct PerformanceTuning;

impl PerformanceTuning {
    /// Get performance tuning recommendations
    pub fn recommendations() -> &'static str {
        r#"
# LCPFS Kernel Integration Performance Tuning

## 1. Memory Configuration
- ARC cache: Allocate 50-75% of available RAM
- L2ARC: Use fast NVMe SSD, size 2-4x ARC size
- Prefetch: Enable ML-based prefetching for read-heavy workloads

## 2. I/O Scheduler
- Use noop/none for NVMe (bypass kernel I/O scheduler)
- Direct I/O for sequential large transfers (>1 MB)
- Keep default buffered I/O for small random access

## 3. Transaction Group (TXG) Tuning
- Sync interval: 5 seconds (default) for balanced performance
- Reduce to 1-2s for databases requiring low commit latency
- Increase to 10-30s for write-heavy batch workloads

## 4. Compression
- LZ4: Default, good balance (2-3x ratio, fast)
- ZSTD: Better ratio (3-5x), more CPU
- LZMA: Best ratio (5-10x), highest CPU cost
- Disable for already-compressed data (videos, images)

## 5. ZIL (Intent Log)
- Place on separate fast SSD for synchronous writes
- Use write-back cache if power loss protection available
- Disable for non-critical data (temp files, caches)

## 6. Deduplication
- Use Fast Dedup (RAM-only) for hot data
- 64K-128K entries typical (2-4 MB RAM)
- Full dedup only for datasets with high redundancy

## 7. RAID-Z Configuration
- RAID-Z1: Single parity, 1-disk fault tolerance
- RAID-Z2: Double parity, 2-disk fault tolerance (recommended)
- RAID-Z3: Triple parity, 3-disk fault tolerance (large arrays)
- Use dRAID for faster rebuilds (distributed spare)

## 8. CXL Memory Tiering (if available)
- Local DRAM: 16-64 GB for hot data
- CXL near: 128-256 GB for warm data
- CXL far: 256-512 GB for cold data
- Storage: Bulk data

## 9. Computational Storage (if available)
- Offload compression/decompression
- Offload checksum calculations
- Offload pattern scanning for scrubs
- ~80% CPU savings for offloaded operations
"#
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_error_conversion() {
        assert_eq!(
            lcpfs_error_to_errno("NotFound"),
            -(SyscallError::ENOENT as i32)
        );
        assert_eq!(
            lcpfs_error_to_errno("DiskFull"),
            -(SyscallError::ENOSPC as i32)
        );
        assert_eq!(
            lcpfs_error_to_errno("PermissionDenied"),
            -(SyscallError::EACCES as i32)
        );
        assert_eq!(lcpfs_error_to_errno("Unknown"), -(SyscallError::EIO as i32));
    }

    #[test]
    fn test_allocator_setup_docs() {
        let setup = AllocatorSetup::example_setup();
        assert!(setup.contains("GlobalAlloc"));
        assert!(setup.contains("#[global_allocator]"));
        assert!(setup.contains("#[panic_handler]"));
    }

    #[test]
    fn test_kernel_module_example() {
        let example = example_kernel_module();
        assert!(example.contains("lcpfs_init"));
        assert!(example.contains("lcpfs_open"));
        assert!(example.contains("lcpfs_read"));
        assert!(example.contains("lcpfs_write"));
    }

    #[test]
    fn test_performance_recommendations() {
        let recommendations = PerformanceTuning::recommendations();
        assert!(recommendations.contains("ARC cache"));
        assert!(recommendations.contains("Compression"));
        assert!(recommendations.contains("RAID-Z"));
    }

    #[test]
    fn test_file_stat_size() {
        // Ensure FileStat is correctly sized for C interop
        // Size is 64 bytes (8*4 u64s + 4*4 u32s = 32+16 = 48, rounded to 64 with padding)
        assert_eq!(core::mem::size_of::<FileStat>(), 64);
    }
}