# ktdumper/fs-tools architecture

> Architecture diagram of the GitHub repository ktdumper/fs-tools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ktdumper/fs-tools
- Repository: https://github.com/ktdumper/fs-tools

## Overview

##### Project Type and Purpose
- fs-tools is a multi-component suite focused on file system-related operations. It appears to combine file system emulation, low-level kernel module integration, and file extraction/conversion utilities. Notice that several subdirectories (fsr_f, fsr_ll, ssr200, ssr200_old_flavor, and xsr2) each represent different modules or flavors of tools for handling, emulating, or converting file systems. This hints at a design where multiple tools (both user-land scripts and kernel-level drivers) coexist and sometimes overlap in functionality.

##### File Structure
- Top-Level Grouping:
– fsr_f: Contains a Python-based emulator (emu.py) alongside a binary blob (secondbl.bin). This suggests a high-level, possibly prototyping or simulation layer.
– fsr_ll: Offers a combination of Python (emu.py) and C (main.c) components, as well as Linux kernel modules (fsr.ko and fsr_stl.ko). It indicates a low-level implementation that integrates directly with the OS kernel.
– ssr200 and ssr200_old_flavor: These directories house Python scripts (with names like carve_msdos50_fat.py, convert_ssr200.py, extract.py, etc.), an installation script, and even a patch diff (pyfatfs.diff). They focus on tasks such as carving file system images, converting formats, and extractions—likely dealing with FAT file systems.
– xsr2: Contains a C file (main.c) and a kernel module (xsr_stl.ko), which suggest a specialized low-level tool module.
- Notice also the README files in nearly every subdirectory. While minimal, their existence is a sign that each module has its own nuances or operational guidelines.

##### README File
- The top-level README only presents the project title “fs-tools,” reinforcing that the overall suite is sum of multiple file system tools and drivers.
- Additional READMEs in the subdirectories (like in fsr_f, fsr_ll, etc.) may contain implementation details and usage notes that hint at component responsibilities without overcomplicating the system design.

a. Main components:
– Emulation Modules: fsr_f (Python-based emulation) and fsr_ll (emulation plus kernel integration).
– Kernel-Level Drivers/Modules: Kernel modules in fsr_ll (fsr.ko, fsr_stl.ko) and xsr2 (xsr_stl.ko). These represent the low-level integration with the operating system.
– Extraction/Conversion Utilities: ssr200 and ssr200_old_flavor provide Python scripts for tasks such as carving, converting, and extracting file systems, with their own variant support.
– Supporting Binaries/Source Code: Files like secondbl.bin (likely used by the emulator) and main.c (for kernel module compilation) are auxiliary and critical for building the modules.

b. Relationships and interactions:
– The Python emulation scripts might simulate or test the behavior of low-level modules before actual kernel integration.
– The kernel modules in fsr_ll and xsr2 are compiled from C source code and are loaded into the system, serving as the bridge between user-space operations and kernel-level file system access.
– The extraction/conversion modules (ssr200 series) likely process file system images and depend on external libraries (evidenced by the pyfatfs.diff file), interfacing with both Python emulators and possibly the kernel modules.
– There is an apparent evolution over time with “ssr200” and “ssr200_old_flavor” indicating versioning or flavor-specific implementations.

c. Architectural patterns or design principles:
– Separation of Concerns and Layering: Different directories clearly demarcate the boundaries between emulation (userland), low-level kernel integration, and extraction/conversion utilities.
– Modularity: Each component (fsr_f, fsr_ll, ssr200, etc.) is a self-contained module, suggesting that they are designed to be developed or tested independently.
– Versioning/Flavors: The existence of “old flavor” indicates backward compatibility considerations.

d. Relevant technologies:
– Python – for emulation, file carving, and conversion utilities.
– C – for implementing kernel modules and low-level system components.
– Linux Kernel Modules (.ko files) – for directly interfacing with the OS.
– Scripting & Shell (install.sh, run.sh) – for deployment and execution automation.
– Patching/Library Modifications – implied by pyfatfs.diff which affects how external libraries function during FAT file system processing.

## Diagram (Mermaid)

```mermaid
graph TD
    fs_tools["fs-tools Suite"]:::external

    subgraph "User-Space Emulation (fsr_f)"
        F_f1["emu.py"]:::pythonEmu
        F_f2["secondbl.bin"]:::binary
    end

    subgraph "Low-Level Kernel Integration (fsr_ll)"
        LL_emu["emu.py"]:::pythonLL
        LL_main["main.c"]:::cSource
        LL_ko["fsr.ko"]:::kernel
        LL_stl["fsr_stl.ko"]:::kernel
    end

    subgraph "Specialized Kernel Module (xsr2)"
        X_main["main.c"]:::cSource
        X_ko["xsr_stl.ko"]:::kernel
    end

    subgraph "File Extraction/Conversion Utilities (Modern) (ssr200)"
        SSR200_carve["carve_msdos50_fat.py"]:::pythonScript
        SSR200_convert["convert_ssr200.py"]:::pythonScript
        SSR200_extract["extract.py"]:::pythonScript
        SSR200_install["install.sh"]:::script
        SSR200_diff["pyfatfs.diff"]:::patch
        SSR200_run["run.py"]:::pythonScript
    end

    subgraph "File Extraction/Conversion Utilities (Old Flavor) (ssr200_old_flavor)"
        SSR200_old_carve["carve_msdos50_fat.py"]:::pythonScript
        SSR200_old_convert["convert_old_ssr200.py"]:::pythonScript
        SSR200_old_run["run.sh"]:::script
    end

    External_Lib["External Library (pyfatfs)"]:::external

    %% Global connections from fs-tools suite
    fs_tools -->|"initiate"| F_f1
    fs_tools -->|"initiate"| LL_emu
    fs_tools -->|"initiate"| SSR200_carve
    fs_tools -->|"initiate"| SSR200_old_carve
    fs_tools -->|"initiate"| X_main

    %% Inter-module interactions
    F_f1 -->|"simulate"| LL_emu
    SSR200_extract -->|"process"| LL_main
    SSR200_run -->|"process"| LL_main
    SSR200_old_convert -->|"process"| LL_main
    SSR200_convert -->|"patches"| SSR200_diff
    SSR200_diff -->|"modifies"| External_Lib
    LL_ko -->|"integrates with"| X_ko
    LL_stl -->|"integrates with"| X_ko

    %% Styling Definitions
    classDef pythonEmu fill:#ffe6e6,stroke:#ff3333,stroke-width:2px;
    classDef binary fill:#fff0b3,stroke:#d4a017,stroke-width:2px;
    classDef pythonLL fill:#e6ffe6,stroke:#339933,stroke-width:2px;
    classDef cSource fill:#e6f7ff,stroke:#3399ff,stroke-width:2px;
    classDef kernel fill:#f0e6ff,stroke:#8e44ad,stroke-width:2px;
    classDef pythonScript fill:#eafff0,stroke:#27ae60,stroke-width:2px;
    classDef script fill:#f0fff0,stroke:#2ecc71,stroke-width:2px;
    classDef patch fill:#f9e79f,stroke:#f39c12,stroke-width:2px;
    classDef external fill:#d5f5e3,stroke:#16a085,stroke-width:2px;

    %% Click Events for fsr_f components
    click F_f1 "https://github.com/ktdumper/fs-tools/blob/main/fsr_f/emu.py"
    click F_f2 "https://github.com/ktdumper/fs-tools/blob/main/fsr_f/secondbl.bin"

    %% Click Events for fsr_ll components
    click LL_emu "https://github.com/ktdumper/fs-tools/blob/main/fsr_ll/emu.py"
    click LL_main "https://github.com/ktdumper/fs-tools/blob/main/fsr_ll/main.c"
    click LL_ko "https://github.com/ktdumper/fs-tools/blob/main/fsr_ll/fsr.ko"
    click LL_stl "https://github.com/ktdumper/fs-tools/blob/main/fsr_ll/fsr_stl.ko"

    %% Click Events for ssr200 components
    click SSR200_carve "https://github.com/ktdumper/fs-tools/blob/main/ssr200/carve_msdos50_fat.py"
    click SSR200_convert "https://github.com/ktdumper/fs-tools/blob/main/ssr200/convert_ssr200.py"
    click SSR200_extract "https://github.com/ktdumper/fs-tools/blob/main/ssr200/extract.py"
    click SSR200_install "https://github.com/ktdumper/fs-tools/blob/main/ssr200/install.sh"
    click SSR200_diff "https://github.com/ktdumper/fs-tools/blob/main/ssr200/pyfatfs.diff"
    click SSR200_run "https://github.com/ktdumper/fs-tools/blob/main/ssr200/run.py"

    %% Click Events for ssr200_old_flavor components
    click SSR200_old_carve "https://github.com/ktdumper/fs-tools/blob/main/ssr200_old_flavor/carve_msdos50_fat.py"
    click SSR200_old_convert "https://github.com/ktdumper/fs-tools/blob/main/ssr200_old_flavor/convert_old_ssr200.py"
    click SSR200_old_run "https://github.com/ktdumper/fs-tools/blob/main/ssr200_old_flavor/run.sh"

    %% Click Events for xsr2 components
    click X_main "https://github.com/ktdumper/fs-tools/blob/main/xsr2/main.c"
    click X_ko "https://github.com/ktdumper/fs-tools/blob/main/xsr2/xsr_stl.ko"
```
