How quic/ufs-tools works
Purpose and deployment model
ufs-tools provides host-side Python utilities and target-side native CLI binaries for diagnosing Universal Flash Storage (UFS). The C tools run on a Linux target with access to the UFS driver’s Block SCSI Generic (BSG) interface; host automation can reach the target through ADB. Core paths: ufs-cli/Makefile, ufs-cli/lsufs.c, scripts/ufs-eom.py.
Native CLI entry points
The build produces two operational programs:
• lsufs: command dispatcher for UIC and UFS Query requests.
• ufseom: standalone Eye Opening Monitor (EOM) collector.
ufs-cli/lsufs.c owns the lsufs command-line entry and routing; ufs-cli/ufs_eom.c implements the standalone EOM executable; ufs-cli/shell.c supplies CLI/shell interaction support.
Linux BSG transport boundary
All target-side device control converges at the Linux BSG transport layer. ufs-cli/ufs_bsg.c and ufs-cli/ufs_bsg.h encapsulate sending UFS commands through the driver, separating CLI and protocol-specific operations from kernel/device access. ufs-cli/common.c provides shared command/runtime utilities. The external dependency is a Linux UFS stack exposing the required BSG endpoint and permissions.
UIC control path
UIC commands configure or inspect UFS interconnect-layer behavior, including the execution environment required by EOM. The lsufs uic command path is implemented by ufs-cli/uic.c and declared in ufs-cli/uic.h; it uses the BSG boundary in ufs-cli/ufs_bsg.c. This is the primary control-plane mechanism used by script-driven EOM collection.
UFS Query control path
UFS Query requests are a parallel protocol path for descriptors, attributes, and flags needed during device interaction. ufs-cli/query.c handles query command processing, ufs-cli/query_trans.c translates query operations to transport form, and ufs-cli/query_desc.h defines descriptor-related protocol structures. These operations also flow through ufs-cli/ufs_bsg.c.
EOM acquisition and report flow
EOM collection changes UIC-layer state, scans/collects lane data, and writes .eom reports. The native route is self-contained in ufs-cli/ufs_eom.c. The host route in scripts/ufs-eom.py invokes lsufs through ADB to issue required UIC and Query operations, then emits compatible report files. EOM execution is operationally bounded by UFS power-management state: clock scaling/gating, suspend/resume, and auto-hibernate should be disabled for valid captures.
Visualization and external integrations
scripts/ufs-eom-plot.py consumes generated .eom files and renders UFS eye diagrams. scripts/ufs-eom.py depends on ADB when orchestrating a remote lsufs binary; ufseom removes that dependency when run directly on the target. Neither collection route performs workload I/O itself, allowing external stress traffic during capture.
Main entry points: lsufs.c lsufs dispatcher · ufs_eom.c ufseom collector · ufs_bsg.c Linux BSG transport · query.c UFS Query control
Components 16
Linux target
Native tools run beside the UFS BSG endpoint.
- Native build · Builds the lsufs and ufseom binaries.
ufs-cli/Makefile - lsufs dispatcher · Routes UIC and UFS Query commands.
ufs-cli/lsufs.c - CLI shell support
ufs-cli/shell.c - Shared runtime
ufs-cli/common.c - UIC control · Configures and inspects the UFS interconnect layer.
ufs-cli/uic.c - UFS Query control · Processes descriptor, attribute, and flag requests.
ufs-cli/query.c - Query translation
ufs-cli/query_trans.c - Query descriptors
ufs-cli/query_desc.h - Linux BSG transport · Encapsulates UFS commands sent through the driver.
ufs-cli/ufs_bsg.c - Linux UFS stack · Provides the BSG endpoint and required permissions.
- ufseom collector · Direct target-side EOM acquisition and report writer.
ufs-cli/ufs_eom.c - Power-management state · Clock scaling/gating, suspend, and auto-hibernate must be disabled for valid captures.
Host automation
Python automation optionally controls a remote target.
- ADB EOM orchestration · Drives remote lsufs and writes compatible reports.
scripts/ufs-eom.py - ADB · Connects host automation to the target.
- Eye diagram plotter · Renders UFS eye diagrams from EOM reports.
scripts/ufs-eom-plot.py
Other components
- EOM reports · Lane scan results consumed by visualization.
Connections 19
- Native build → lsufs dispatcher: builds
- Native build → ufseom collector: builds
- lsufs dispatcher → CLI shell support: uses
- lsufs dispatcher → Shared runtime: uses
- lsufs dispatcher → UIC control: routes uic
- lsufs dispatcher → UFS Query control: routes query
- UIC control → Linux BSG transport: sends commands
- UFS Query control → Query translation: translates
- UFS Query control → Query descriptors: uses definitions
- Query translation → Linux BSG transport: submits
- ufseom collector → Linux BSG transport: collects through
- Linux BSG transport → Linux UFS stack: uses endpoint
- ADB EOM orchestration → ADB: connects through
- ADB → lsufs dispatcher: invokes remotely
- ADB EOM orchestration → EOM reports: writes
- ufseom collector → EOM reports: writes
- EOM reports → Eye diagram plotter: renders
- Power-management state → ufseom collector: bounds valid capture
- Power-management state → ADB EOM orchestration: bounds valid capture