xtop User Guide

xtop is a profiling and monitoring tool based on XPTI (XCENA Profiling and Tracing Interface). It provides real-time device monitoring and offline profiling data collection for PXL applications.

Overview

xtop provides live monitoring, profile collection, and post-mortem analysis commands:

Command	Purpose	Output
view	Real-time device monitoring	Terminal UI
run	Profile PXL application execution	Per-device `.xpti` profiles
map / task	Analyze collected profiles	Terminal summary, optional plots/JSON
convert / export / open	Produce Perfetto/CSV/raw outputs or open traces	`.perfetto-trace`, CSV/raw files, browser

The collected .xpti profiles can be analyzed with the Profiler tool for detailed performance analysis.

view mode

Monitors real-time performance metrics of the device on the terminal.

Usage

# Run view mode (default)
sudo xtop view

# Or simply
sudo xtop

xtop view auto-detects visible devices. Device selection is done inside the TUI; there is no user-facing -d/--device option.

Screen Layout

xtop view is organized as a multi-level terminal UI.

Level 1: device overview

When multiple devices are visible, Level 1 lists them with a process table below when active clients are detected.

xTop (yyyy-mm-dd hh:mm:ss)

[Computing]
    ID                  SUB                            CXL        L1       L2       L3
  >  0   ##########  16/16       ####------   128.0G/512.0G    98.7%   94.2%   91.8%

[Processes]
      PID   DEV    SUB              CXL        USER                  CMD
    12345     0     12     64.0G (12.5%)      user                  ./app

Up/Down Select  Enter Open  i Interval  q Quit

Level 1 is intended for quick comparison:

Computing: SUB usage, CXL memory usage, and aggregate L1/L2/L3 hit rates
Processes: active process usage by device

Level 2: computing device detail

Opening a computing device shows resource usage, per-Sub cache hit rates, aggregate L3/MTC data, and active processes for that device.

xTop - Device 0 (Computing)  yyyy-mm-dd hh:mm:ss

[Resource]
SUB  16/16             ########## 100.0%
IO   0B/64.0G          ----------   0.0%
CXL  128.0G/512.0G     ###-------  25.0%

[L1/L2 (Per Sub)]
>[ 0] L1  99.1% ##########  L2  95.0% #########-
 [ 1] L1  98.7% ##########  L2  94.4% #########-

[L3]
   91.8%  #########-

[MTC (Per DDRSUB)]
[0]  88.2% ########-  [1]  89.5% ########-

Esc Back  Up/Down Sub  Enter Detail  i Interval  q Quit

Actual output depends on hardware topology, terminal width, and active processes.

The screen refreshes periodically. Press i to change the refresh interval while the view is running.

run mode

Profiles a PXL application during execution. Collects Host/Device events and cache metrics into .xpti files (SQLite format).

By default, xtop run detects available devices and publishes profiles only for devices used by the application. Select the target device in the application itself; xtop run does not provide a user-facing -d/--device selector.

Usage

# Profile an application
sudo xtop run -- ./your_application [args...]

# Enable Perfetto trace generation after profiling
sudo xtop run --perfetto -- ./your_application

# Write profiles to a specific output directory
sudo xtop run -o ./xtop -- ./your_application

Options:

Option	Description	Default
`-o, --output <dir>`	Output directory for `.xpti` files	`./xtop/`
`--perfetto [path]`	Auto-convert to Perfetto format (`.perfetto-trace`) after profiling	off
`--no-perfetto`	Disable Perfetto conversion	off

CSV and raw exports are post-processing steps. xtop run writes .xpti files only; use xtop export after collection.

Output

After execution completes, xtop writes profiles under ./xtop/ by default:

[xtop] saved profile: ./xtop/computing_20260210_143022_123456_dev0.xpti

Profiles use the computing_..._devN.xpti prefix. Devices that were not used by the application are filtered out.

The .xpti file is a SQLite database containing:

Host events (API calls: TaskDispatch, TaskComplete, etc.)
Device events (kernel execution: Launch, Terminate)
Cache statistics (L1, L2, L3)
Hardware topology (Sub/Cluster/MU/Thread counts, frequencies)

What to do with the .xpti file

Use the Profiler tool for on-demand analysis:

# Map summary. A directory input auto-picks the latest computing profile.
xtop map ./xtop

# Task-level analysis
xtop task ./xtop/computing_20260210_143022_123456_dev0.xpti

# Perfetto timeline visualization
xtop convert ./xtop/computing_20260210_143022_123456_dev0.xpti
xtop open ./xtop/computing_20260210_143022_123456_dev0.xpti

# CSV/raw export
xtop export ./xtop/computing_20260210_143022_123456_dev0.xpti --csv ./stats_csv
xtop export ./xtop/computing_20260210_143022_123456_dev0.xpti --raw ./raw_csv

See the Profiler Guide for full details.

open mode

Starts a local web server and opens trace files in Perfetto UI for timeline visualization.

Usage

# Open a single .xpti file (auto-converts to Perfetto format)
xtop open profile.xpti

# Open a .perfetto-trace file
xtop open profile.perfetto-trace

# Open a directory of trace files
xtop open ./my_traces/

# Custom port
xtop open profile.perfetto-trace --port 9999

Supported file types: .xpti (auto-converts), .json, .perfetto-trace

Requires flask. Install with: pip install flask

Configuration

xtop settings are managed through xtop_config.yaml. Create this file in the current working directory to override defaults.

# ProfileMode: "HostOnly", "DeviceOnly", "HostAndDevice" (default)
mode: "HostAndDevice"

# Sampling intervals (ms, 0 = use default)
hostSamplingRate: 0      # default: 1000ms
deviceSamplingRate: 0    # default: 1ms

# Probe types to enable (empty = all enabled)
# Options: ["Mu", "L1", "L2", "L3", "MTC", "PCU", "HostEvent", "DeviceEvent"]
enabledProbeTypes: []

# Debug types: ["ProfileInfo", "Core", "Mu"]
enabledDebugTypes: []

csvAppendTimestamp: true

Output paths are command-line options, not configuration-file settings. Device selection is handled by the application for xtop run and inside the TUI for xtop view.

Troubleshooting

Permission denied errors: xtop view and xtop run require root privileges (sudo). Analysis commands (xtop task, xtop map, xtop convert, xtop export, xtop open) do not require root.
No profiling data collected: Ensure the application uses PXL APIs. On multi-device systems, confirm that the device the application targets is visible in xtop view.
Flask not installed (for xtop open): Install with pip install flask.
matplotlib not installed (for xtop map --plot): Install with pip install matplotlib.