# sys-ai-foundation/f2fs-tools architecture

> Architecture diagram of the GitHub repository sys-ai-foundation/f2fs-tools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sys-ai-foundation/f2fs-tools
- Repository: https://github.com/sys-ai-foundation/f2fs-tools

## Overview

This repository is a userspace toolkit for creating and maintaining F2FS filesystems. The primary workflow is to select a storage device, format it with mkfs.f2fs, and then mount the resulting filesystem with the operating system. Separate fsck.f2fs-family commands check, inspect, defragment, resize, and populate filesystems; additional tools manage encryption keys and report runtime filesystem statistics. The README and sampled entry points support the main formatting and command-dispatch relationships; internal wiring for unsampled utilities is not inferred.

Main entry points: [`fsck/main.c`](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/fsck/main.c) (fsck command dispatcher), [`lib/libf2fs_io.c`](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/lib/libf2fs_io.c) (Device I/O), [`mkfs/f2fs_format_main.c`](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/mkfs/f2fs_format_main.c) (mkfs.f2fs), [`tools/f2fscrypt.c`](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/tools/f2fscrypt.c) (Encryption manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_format["Filesystem formatting"]
  node_mkfs_cli["mkfs.f2fs<br/>[f2fs_format_main.c]"]
  node_formatter["F2FS formatter<br/>[f2fs_format.c]"]
end

subgraph group_maintenance["Filesystem maintenance"]
  node_fsck_cli["fsck command dispatcher<br/>[main.c]"]
  node_fsck_engine["Filesystem checker<br/>[fsck.c]"]
  node_metadata_reader["Metadata reader<br/>[mount.c]"]
  node_dump["Filesystem dump<br/>[dump.c]"]
  node_defrag["Defragmentation<br/>[defrag.c]"]
  node_resize["Filesystem resize<br/>[resize.c]"]
  node_sload["Filesystem loader<br/>[sload.c]"]
end

subgraph group_shared["Shared device support"]
  node_shared_lib["F2FS utilities<br/>[libf2fs.c]"]
  node_device_io["Device I/O<br/>[libf2fs_io.c]"]
  node_zoned_support["Zoned devices<br/>[libf2fs_zoned.c]"]
end

subgraph group_tools["Administration tools"]
  node_crypt_tool["Encryption manager<br/>[f2fscrypt.c]"]
  node_sha512["SHA-512 implementation<br/>[sha512.c]"]
  node_stat_tool["Filesystem statistics<br/>[f2fstat.c]"]
  node_other_tools["Filesystem helper tools"]
end

node_operator(("Operator"))
node_block_device[("Storage device")]
node_keyring[("Linux keyring")]
node_kernel_status[("Kernel F2FS status")]

node_operator -->|"runs formatter"| node_mkfs_cli
node_mkfs_cli -->|"formats device"| node_formatter
node_mkfs_cli -->|"initializes configuration"| node_shared_lib
node_formatter -->|"writes filesystem"| node_device_io
node_device_io -->|"reads and writes"| node_block_device
node_operator -->|"runs maintenance"| node_fsck_cli
node_fsck_cli -->|"checks filesystem"| node_fsck_engine
node_fsck_cli -->|"dispatches dump"| node_dump
node_fsck_cli -->|"dispatches defrag"| node_defrag
node_fsck_cli -->|"dispatches resize"| node_resize
node_fsck_cli -->|"dispatches load"| node_sload
node_fsck_cli -->|"loads metadata"| node_metadata_reader
node_metadata_reader -->|"reads device"| node_device_io
node_defrag -->|"migrates blocks"| node_device_io
node_operator -->|"manages encryption"| node_crypt_tool
node_crypt_tool -->|"derives keys"| node_sha512
node_crypt_tool -->|"searches keys"| node_keyring
node_operator -->|"requests statistics"| node_stat_tool
node_stat_tool -->|"reads status"| node_kernel_status
node_operator -->|"runs helper"| node_other_tools
node_shared_lib -.->|"supports zoned devices"| node_zoned_support

click node_mkfs_cli "https://github.com/sys-ai-foundation/f2fs-tools/blob/master/mkfs/f2fs_format_main.c"
click node_formatter "https://github.com/sys-ai-foundation/f2fs-tools/blob/master/mkfs/f2fs_format.c"
click node_fsck_cli "https://github.com/sys-ai-foundation/f2fs-tools/blob/master/fsck/main.c"
click node_fsck_engine "https://github.com/sys-ai-foundation/f2fs-tools/blob/master/fsck/fsck.c"
click node_metadata_reader "https://github.com/sys-ai-foundation/f2fs-tools/blob/master/fsck/mount.c"
click node_dump "https://github.com/sys-ai-foundation/f2fs-tools/blob/master/fsck/dump.c"
click node_defrag "https://github.com/sys-ai-foundation/f2fs-tools/blob/master/fsck/defrag.c"
click node_resize "https://github.com/sys-ai-foundation/f2fs-tools/blob/master/fsck/resize.c"
click node_sload "https://github.com/sys-ai-foundation/f2fs-tools/blob/master/fsck/sload.c"
click node_shared_lib "https://github.com/sys-ai-foundation/f2fs-tools/blob/master/lib/libf2fs.c"
click node_device_io "https://github.com/sys-ai-foundation/f2fs-tools/blob/master/lib/libf2fs_io.c"
click node_zoned_support "https://github.com/sys-ai-foundation/f2fs-tools/blob/master/lib/libf2fs_zoned.c"
click node_crypt_tool "https://github.com/sys-ai-foundation/f2fs-tools/blob/master/tools/f2fscrypt.c"
click node_sha512 "https://github.com/sys-ai-foundation/f2fs-tools/blob/master/tools/sha512.c"
click node_stat_tool "https://github.com/sys-ai-foundation/f2fs-tools/blob/master/tools/f2fstat.c"
click node_other_tools "https://github.com/sys-ai-foundation/f2fs-tools/tree/master/tools"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mkfs_cli,node_formatter toneBlue
class node_fsck_cli,node_fsck_engine,node_metadata_reader,node_dump,node_defrag,node_resize,node_sload,node_block_device,node_keyring,node_kernel_status toneAmber
class node_shared_lib,node_device_io,node_zoned_support toneMint
class node_crypt_tool,node_sha512,node_stat_tool,node_other_tools toneRose
class node_operator toneIndigo
```

## Components

### Filesystem formatting

- [mkfs.f2fs](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/mkfs/f2fs_format_main.c): `mkfs/f2fs_format_main.c`
- [F2FS formatter](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/mkfs/f2fs_format.c): `mkfs/f2fs_format.c`

### Filesystem maintenance

- [fsck command dispatcher](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/fsck/main.c): `fsck/main.c`
- [Filesystem checker](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/fsck/fsck.c): `fsck/fsck.c`
- [Metadata reader](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/fsck/mount.c): `fsck/mount.c`
- [Filesystem dump](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/fsck/dump.c): `fsck/dump.c`
- [Defragmentation](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/fsck/defrag.c): `fsck/defrag.c`
- [Filesystem resize](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/fsck/resize.c): `fsck/resize.c`
- [Filesystem loader](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/fsck/sload.c): `fsck/sload.c`

### Shared device support

- [F2FS utilities](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/lib/libf2fs.c): `lib/libf2fs.c`
- [Device I/O](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/lib/libf2fs_io.c): `lib/libf2fs_io.c`
- [Zoned devices](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/lib/libf2fs_zoned.c): `lib/libf2fs_zoned.c`

### Administration tools

- [Encryption manager](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/tools/f2fscrypt.c): `tools/f2fscrypt.c`
- [SHA-512 implementation](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/tools/sha512.c): `tools/sha512.c`
- [Filesystem statistics](https://github.com/sys-ai-foundation/f2fs-tools/blob/master/tools/f2fstat.c): `tools/f2fstat.c`
- [Filesystem helper tools](https://github.com/sys-ai-foundation/f2fs-tools/tree/master/tools): `tools`

### Other components

- **Operator**
- **Storage device**
- **Linux keyring**
- **Kernel F2FS status**

## Connections

- Operator → mkfs.f2fs: runs formatter
- mkfs.f2fs → F2FS formatter: formats device
- mkfs.f2fs → F2FS utilities: initializes configuration
- F2FS formatter → Device I/O: writes filesystem
- Device I/O → Storage device: reads and writes
- Operator → fsck command dispatcher: runs maintenance
- fsck command dispatcher → Filesystem checker: checks filesystem
- fsck command dispatcher → Filesystem dump: dispatches dump
- fsck command dispatcher → Defragmentation: dispatches defrag
- fsck command dispatcher → Filesystem resize: dispatches resize
- fsck command dispatcher → Filesystem loader: dispatches load
- fsck command dispatcher → Metadata reader: loads metadata
- Metadata reader → Device I/O: reads device
- Defragmentation → Device I/O: migrates blocks
- Operator → Encryption manager: manages encryption
- Encryption manager → SHA-512 implementation: derives keys
- Encryption manager → Linux keyring: searches keys
- Operator → Filesystem statistics: requests statistics
- Filesystem statistics → Kernel F2FS status: reads status
- Operator → Filesystem helper tools: runs helper
- F2FS utilities → Zoned devices: supports zoned devices