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
attach	Profile a running process started with XPTI_ATTACHABLE=1 by PID	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.

---

attach mode

Use xtop attach to profile a running PXL application that was prepared for attach when it started. This guide uses standalone PID attach: start the application with XPTI_ATTACHABLE=1, then connect directly to that process.

Native host

In the first terminal, start the target:

XPTI_ATTACHABLE=1 ./your_application [args...] &
target_pid=$!
printf 'Target PID: %s\n' "$target_pid"

In another terminal, run xtop attach as the same user:

# Replace 12345 with the PID printed above.
xtop attach --pid 12345

XPTI_ATTACHABLE=1 only makes the process available for a later attach; collection starts when xtop attach runs.

Docker

Use the same standalone flow inside Docker. Run the target and xtop attach in the same container.

If the container uses --rm, bind-mount an output directory so the profiles survive container removal:

If the application is the container command, add XPTI_ATTACHABLE=1 to the existing docker run command:

mkdir -p "$PWD/xtop-out"
docker run <existing-options> \
  -e XPTI_ATTACHABLE=1 \
  -v "$PWD/xtop-out:/xtop-out" \
  --name <container> xcenadev/sdk:<tag> \
  ./your_application [args...]

If the container is already running with an interactive shell, start the target inside it and save its PID:

XPTI_ATTACHABLE=1 ./your_application [args...] &
target_pid=$!
printf 'Target PID: %s\n' "$target_pid"
printf '%s\n' "$target_pid" > /tmp/xtop-target.pid

Open another terminal in the same container:

docker exec -it <container> bash

If the target uses a custom container user, add --user <target-user-or-uid> so the new shell runs as the target’s user.

Then use the PID saved by the first shell and attach as the same user:

target_pid=$(cat /tmp/xtop-target.pid)
ps -p "$target_pid" -o pid,user,args
# /dev/null is intentionally not a Unix socket: force standalone attach even
# when the hardware setup exposes /run/pxl/pxl_prof.sock in this container.
XPTI_DAEMON_SOCKET=/dev/null xtop attach --pid "$target_pid" -o /xtop-out

The XCENA SDK image already includes xtop. This standalone flow needs no xpti-profiled service or /run/xpti socket mount. If the hardware setup mounts /run/pxl, xtop may otherwise discover the shared profiling daemon before trying the per-process endpoint; use the override above for this standalone flow. Device access still uses the normal Docker hardware setup.

Important behavior

• Attach follows only the specified PID. Worker or child processes are not included. Do not attach to a launcher, wrapper script, or container PID 1 that merely spawns the workload; attach to the process that actually runs the PXL workload.
• Press Ctrl-C to stop profiling. The target application keeps running.
• For isolated device metrics, use this standalone flow when no other workload is using the same device.

---

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 xtop attach, and inside the TUI for xtop view.

---

Troubleshooting

• Permission denied errors: standalone attach must run as the same effective user as the target (use sudo xtop attach ... for a root target). On hardware, xtop view and xtop run may require sudo when device permissions demand it; analysis commands (xtop task, xtop map, xtop convert, xtop export, xtop open) do not. If the target runs as root, start it with sudo XPTI_ATTACHABLE=1 ... or XPTI_ATTACHABLE=1 sudo -E ... so sudo’s default env_reset does not remove the variable.
• 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.
• no control socket for pid ...: the target was not started with XPTI_ATTACHABLE=1, xtop attach is running in a different container or as a different user, the PID is a launcher/wrapper/container PID 1 rather than the PXL workload, or the two shells disagree on XDG_RUNTIME_DIR. The target binds $XDG_RUNTIME_DIR/xpti/ first; export the same value in both shells, or unset it before starting both target and attach.
• The target is already profiling itself: stop its existing profiling session, then restart it with only XPTI_ATTACHABLE=1 and retry.
• START rejected: ERR already_active: another attach is active for this target. Stop it and retry.
• START rejected: ERR start_failed: the device profiler could not be armed, typically because a recording-mode xtop view or another capture is holding the same device. Stop it and retry.
• profiler busy: a shared profiling daemon was discovered before the per-process endpoint. For standalone attach, set XPTI_DAEMON_SOCKET=/dev/null; for daemon mode, configure the target to report to that daemon instead.
• Docker target unavailable: run the target and xtop attach in the same container and follow Attach inside Docker.