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 three main modes:

Mode Purpose Output
view Real-time device monitoring Terminal UI
run Profile application execution .xpti profile file
open View traces in Perfetto UI Web browser

The collected .xpti profile 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

Screen Layout 

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

L1/L2 (Per Sub)
[ 0]    L1  99.9%  ||||||||||||||||||||    L2  0.0%  ||||||||||||||||||||
[ 1]    L1  99.6%  ||||||||||||||||||||    L2  0.0%  ||||||||||||||||||||
...

L3 (Per DDRSUB)
[0]  93.2% ||||||||||   [1]  92.9% ||||||||||

MTC (Per DDRSUB)
[0]   0.0% ||||||||||   [1]   0.0% ||||||||||

Gaia
[0] smcPage  0.0% ||||||||||||||||  smcTLB  0.0% ||||||||||||||||

Actual output depends on hardware topology (number of Subs, DDRSUBs, etc.)

  • L1/L2 (Per Sub): L1/L2 cache hit ratio per Sub
  • L3 (Per DDRSUB): L3 cache hit ratio per DDRSUB
  • MTC (Per DDRSUB): MTC (MeTa Cache) hit ratio per DDRSUB
  • Gaia: SMC Page/TLB hit ratio

The screen refreshes periodically (default 1 second).

run mode

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

Usage 

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

# Specify output directory
sudo xtop run -o ./my_profile -- ./your_application

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

Options:

Option Description Default
-o, --output <dir> Output directory for .xpti file ./xtop_profile/
--perfetto Auto-convert to Perfetto format (.perfetto-trace) after profiling off

Output

After execution completes, xtop generates:

[xtop] Profile saved: ./xtop_profile/profile_20260210_143022.xpti (245760 bytes)

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:

# Task-level analysis
xtop task profile.xpti

# Map summary (parallelism, balance, cache)
xtop map profile.xpti

# Perfetto timeline visualization
xtop convert profile.xpti
xtop open profile.xpti

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 directory of trace files
xtop open ./my_traces/

# Custom port
xtop open profile.xpti --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", "Gaia", "HostEvent", "DeviceEvent"]
enabledProbeTypes: []

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

# Output settings
device: 0

# view mode specific (CSV export for monitoring data)
view_csv: false
csv_path: null
csvAppendTimestamp: true

Troubleshooting

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