# quic/ufs-tools architecture

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

- Interactive diagram: https://gitdiagram.com/quic/ufs-tools
- Repository: https://github.com/quic/ufs-tools

## Overview

#### 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: [`ufs-cli/lsufs.c`](https://github.com/quic/ufs-tools/blob/main/ufs-cli/lsufs.c) (lsufs dispatcher), [`ufs-cli/ufs_eom.c`](https://github.com/quic/ufs-tools/blob/main/ufs-cli/ufs_eom.c) (ufseom collector), [`ufs-cli/ufs_bsg.c`](https://github.com/quic/ufs-tools/blob/main/ufs-cli/ufs_bsg.c) (Linux BSG transport), [`ufs-cli/query.c`](https://github.com/quic/ufs-tools/blob/main/ufs-cli/query.c) (UFS Query control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_target["Linux target"]
  node_build["Native build<br/>Makefile"]
  node_lsufs["lsufs dispatcher<br/>CLI entry point<br/>[lsufs.c]"]
  node_shell["CLI shell support<br/>CLI runtime<br/>[shell.c]"]
  node_common["Shared runtime<br/>native utility<br/>[common.c]"]
  node_uic["UIC control<br/>protocol handler<br/>[uic.c]"]
  node_query["UFS Query control<br/>protocol handler<br/>[query.c]"]
  node_query_trans["Query translation<br/>transport adapter<br/>[query_trans.c]"]
  node_query_desc["Query descriptors<br/>protocol definitions<br/>[query_desc.h]"]
  node_bsg{{"Linux BSG transport<br/>device boundary<br/>[ufs_bsg.c]"}}
  node_linux_ufs{{"Linux UFS stack<br/>external dependency"}}
  node_ufseom["ufseom collector<br/>native CLI<br/>[ufs_eom.c]"]
  node_pm_state["Power-management state<br/>operational constraint"]
end

subgraph group_host["Host automation"]
  node_host_eom["ADB EOM orchestration<br/>Python script<br/>[ufs-eom.py]"]
  node_adb{{"ADB<br/>external dependency"}}
  node_plot["Eye diagram plotter<br/>Python script<br/>[ufs-eom-plot.py]"]
end

node_report["EOM reports<br/>.eom output"]

node_build -->|"builds"| node_lsufs
node_build -->|"builds"| node_ufseom
node_lsufs -->|"uses"| node_shell
node_lsufs -->|"uses"| node_common
node_lsufs -->|"routes uic"| node_uic
node_lsufs -->|"routes query"| node_query
node_uic -->|"sends commands"| node_bsg
node_query -->|"translates"| node_query_trans
node_query -->|"uses definitions"| node_query_desc
node_query_trans -->|"submits"| node_bsg
node_ufseom -->|"collects through"| node_bsg
node_bsg -->|"uses endpoint"| node_linux_ufs
node_host_eom -->|"connects through"| node_adb
node_adb -->|"invokes remotely"| node_lsufs
node_host_eom -->|"writes"| node_report
node_ufseom -->|"writes"| node_report
node_report -->|"renders"| node_plot
node_pm_state -.->|"bounds valid capture"| node_ufseom
node_pm_state -.->|"bounds valid capture"| node_host_eom

click node_build "https://github.com/quic/ufs-tools/blob/main/ufs-cli/Makefile"
click node_lsufs "https://github.com/quic/ufs-tools/blob/main/ufs-cli/lsufs.c"
click node_shell "https://github.com/quic/ufs-tools/blob/main/ufs-cli/shell.c"
click node_common "https://github.com/quic/ufs-tools/blob/main/ufs-cli/common.c"
click node_uic "https://github.com/quic/ufs-tools/blob/main/ufs-cli/uic.c"
click node_query "https://github.com/quic/ufs-tools/blob/main/ufs-cli/query.c"
click node_query_trans "https://github.com/quic/ufs-tools/blob/main/ufs-cli/query_trans.c"
click node_query_desc "https://github.com/quic/ufs-tools/blob/main/ufs-cli/query_desc.h"
click node_bsg "https://github.com/quic/ufs-tools/blob/main/ufs-cli/ufs_bsg.c"
click node_ufseom "https://github.com/quic/ufs-tools/blob/main/ufs-cli/ufs_eom.c"
click node_host_eom "https://github.com/quic/ufs-tools/blob/main/scripts/ufs-eom.py"
click node_plot "https://github.com/quic/ufs-tools/blob/main/scripts/ufs-eom-plot.py"

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_build,node_lsufs,node_shell,node_common,node_uic,node_query,node_query_trans,node_query_desc,node_bsg,node_linux_ufs,node_ufseom,node_pm_state toneBlue
class node_host_eom,node_adb,node_plot toneAmber
class node_report toneNeutral
```

## Components

### Linux target

Native tools run beside the UFS BSG endpoint.

- [Native build](https://github.com/quic/ufs-tools/blob/main/ufs-cli/Makefile): Makefile · Builds the lsufs and ufseom binaries. · `ufs-cli/Makefile`
- [lsufs dispatcher](https://github.com/quic/ufs-tools/blob/main/ufs-cli/lsufs.c): CLI entry point · Routes UIC and UFS Query commands. · `ufs-cli/lsufs.c`
- [CLI shell support](https://github.com/quic/ufs-tools/blob/main/ufs-cli/shell.c): CLI runtime · `ufs-cli/shell.c`
- [Shared runtime](https://github.com/quic/ufs-tools/blob/main/ufs-cli/common.c): native utility · `ufs-cli/common.c`
- [UIC control](https://github.com/quic/ufs-tools/blob/main/ufs-cli/uic.c): protocol handler · Configures and inspects the UFS interconnect layer. · `ufs-cli/uic.c`
- [UFS Query control](https://github.com/quic/ufs-tools/blob/main/ufs-cli/query.c): protocol handler · Processes descriptor, attribute, and flag requests. · `ufs-cli/query.c`
- [Query translation](https://github.com/quic/ufs-tools/blob/main/ufs-cli/query_trans.c): transport adapter · `ufs-cli/query_trans.c`
- [Query descriptors](https://github.com/quic/ufs-tools/blob/main/ufs-cli/query_desc.h): protocol definitions · `ufs-cli/query_desc.h`
- [Linux BSG transport](https://github.com/quic/ufs-tools/blob/main/ufs-cli/ufs_bsg.c): device boundary · Encapsulates UFS commands sent through the driver. · `ufs-cli/ufs_bsg.c`
- **Linux UFS stack**: external dependency · Provides the BSG endpoint and required permissions.
- [ufseom collector](https://github.com/quic/ufs-tools/blob/main/ufs-cli/ufs_eom.c): native CLI · Direct target-side EOM acquisition and report writer. · `ufs-cli/ufs_eom.c`
- **Power-management state**: operational constraint · 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](https://github.com/quic/ufs-tools/blob/main/scripts/ufs-eom.py): Python script · Drives remote lsufs and writes compatible reports. · `scripts/ufs-eom.py`
- **ADB**: external dependency · Connects host automation to the target.
- [Eye diagram plotter](https://github.com/quic/ufs-tools/blob/main/scripts/ufs-eom-plot.py): Python script · Renders UFS eye diagrams from EOM reports. · `scripts/ufs-eom-plot.py`

### Other components

- **EOM reports**: .eom output · Lane scan results consumed by visualization.

## Connections

- 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