How axboe/fio works
Project type and purpose
• Fio is an open-source, command-line I/O workload generator and benchmark tool written in C. It reads “job files” or command-line parameters to spawn threads/processes that execute customizable I/O patterns across many storage APIs and back-ends. Its key value is flexibility and extensibility via pluggable I/O engines.
High-level file-structure analysis
• Top level: configure/build scripts (configure, Makefile), documentation (doc/, README.rst), CI definitions (.github/, ci/), examples/, tools/, unittests/
• Core C sources: fio.c (entrypoint), parser (parse.c, compiler/), job scheduler (flow.c, helper_thread.c), I/O engines (engines/), OS abstraction (os/, oslib/), architecture‐specific code (arch/), shared libraries/utilities (lib/)
• Extensibility points: each file in engines/ is a plugin implementing a struct of callbacks that the scheduler invokes; JSON, log, statistics modules for output; tools/ for post-processing and visualization.
Key README insights
• Fio spawns threads/processes per job, each inheriting global parameters
• Engines are compiled in or enabled by configure (libaio, HTTP, gfio GUI)
• Cross-platform support via os/ and oslib/ abstractions
• Documentation generated via Sphinx from doc/
Main components
a. CLI Front-end & Job Parser
• fio.c, parse.c, compiler/*: parse .fio jobfiles or CLI args into in-memory job descriptions
b. Job Scheduler & Control Plane
• flow.c, helper_thread.c, thread_options.h: spawn threads/processes, assign per-job runtimes, collect stats
c. I/O Engine Manager & Plugin Layer
• ioengines.c/ioengines.h: engine registry
• engines/*.c: individual back-ends (libaio, mmap, HTTP, POSIX AIO, GPU Direct RDMA, etc.)
d. OS Abstraction & Architecture Layer
• os/, oslib/: wrap platform syscalls (threads, file I/O, networking, timers)
• arch/: architecture-specific optimizations (e.g., CRC acceleration)
e. Utility Libraries
• lib/: common data structures (rbtree, bloom, rand), math utilities, memory align, logging, JSON output
f. Output & Reporting
• log.c/iolog.c: result logging, histogram generation
• tools/: post-processing scripts (fio2gnuplot, fiograph)
g. Testing & CI
• t/: unit and integration tests, fuzzers
• unittests/: C-level unit tests
• .github/ and ci/: automated build, QEMU VM integration, fuzz testing pipelines
Relationships and data flow
• User → CLI front-end → Job Parser → Job Descriptor objects
• Scheduler/Controller → spawns Worker threads/processes
• Each Worker → Engine Manager → Engine Plugin → OS Abstraction → Host Kernel/Storage Hardware
• Worker → gathers performance metrics → Controller → Aggregator → Logger/Output
• External tools consume output logs for visualization
• CI pipelines enforce build → test → fuzz → package
Architectural patterns & design principles
• Plugin architecture for I/O engines (dynamic registration via ioengines.c)
• Layered design: CLI/Parser → Scheduler → Engines → OS → Hardware
• Abstraction for portability (os/, oslib/)
• Separation of concerns: parsing, scheduling, I/O, logging, utilities
• Test harness isolated from production code (t/, unittests/)
Elements
• Clear labels for each component block and layer
• CLI → Parser → Scheduler → Worker → Engine → OS → Hardware
• Worker → Stats Aggregator → Logger → Tools
• Core engine (blue)
• Engine plugins (green)
• Platform abstractions (orange)
• Utilities & tools (gray)
• Tests/CI (purple)