J6 Ucp Perfetto Trace Catcher

UCP Trace Catcher

Capture Perfetto-based UCP traces from a remote J6 development board and bring them back to the X86 host for analysis.

What this skill does

Automates the full lifecycle of UCP Perfetto trace capture:

1. Transfer config files to the dev board
2. Set up the trace environment and run the application
3. Pull the captured trace back to the host
4. Tell the user what to do next

Only Perfetto trace is in scope — ignore DSP trace and Chrome trace.

Never modify original files in this skill's directory. Copy config files to a temp location under the local current workspace (pwd), edit the copy there, then transfer.

Before starting

You need the following information from the user. Ask for anything not provided:

If mode is not specified, ask the user:

• in_process: captures only UCP process-internal trace (track_event). Does NOT support thread scheduling states, ftrace, memory stats, process stats, or BPU trace. No daemon needed. Good for UCP scheduling logic analysis.
• system: captures UCP trace + thread scheduling states (ftrace), memory stats, and process stats by default (uses ucp_system.cfg). When BPU trace is enabled, the same ucp_system.cfg is used but BPU trace is additionally turned on via sysfs commands; BPU trace data will appear alongside ftrace data. Needs tracebox daemons. Use system mode when you need system-level visibility beyond UCP internals.

Important: The pre-built config files in reference/ cover all modes. Select the right one by mode — do NOT modify config files unless you have a specific reason (e.g., adjusting buffer size or duration).

Step 1: Transfer config files to the board

Config files are in this skill's reference/ directory. Select the right cfg file based on mode:

All system mode configs share the same ucp_system.json (it just sets "backend": "system"). System mode always uses ucp_system.cfg regardless of BPU trace — BPU trace is controlled by sysfs commands, not the cfg file.

Transfer via scp:

For in_process mode

scp reference/ucp_in_process.cfg reference/ucp_in_process.json <board_user>@<board_ip>:<work_dir>/

For system mode

scp reference/ucp_system.cfg reference/ucp_system.json <board_user>@<board_ip>:<work_dir>/

If you edited a config copy (e.g., adjusting duration_ms or output_path), scp the copy instead of the original reference/ file.

Step 2: Set up environment and run the application

Environment variables and the app must run in the same SSH session, otherwise the variables are lost. Always combine setup and app execution into a single SSH heredoc.

For in_process mode

ssh <board_user>@<board_ip> << 'EOF'
cd <work_dir>

# Remove old trace file if it exists (Perfetto cannot overwrite)
rm -f <output_name>

# Set environment variables
export HB_UCP_PERFETTO_CONFIG_PATH=ucp_in_process.json
export HB_UCP_ENABLE_PERFETTO=true

# Run the UCP application
<App command>
EOF

For system mode

ssh <board_user>@<board_ip> << 'EOF'
cd <work_dir>

# Remove old trace file if it exists
rm -f <output_name>

# Kill existing tracebox processes to avoid interference
pkill -f "tracebox" 2>/dev/null || true
sleep 1

# Start Perfetto daemons
tracebox traced --background
tracebox traced_probes --background --reset-ftrace

# If BPU trace is enabled, query BPU core count and turn on BPU trace on ALL cores
if <enable_bpu>; then
    BPU_CORE_NUM=$(cat /sys/devices/system/bpu/core_num)
    for i in $(seq 0 $(expr $BPU_CORE_NUM - 1)); do
        echo 0 > /sys/devices/system/bpu/bpu${i}/power_enable 2>/dev/null || true
        echo 1 > /sys/devices/system/bpu/bpu${i}/trace
    done
fi

# Start trace capture in background and record its PID
tracebox perfetto --txt -c <cfg_file_from_step1> -o <output_name> &
PERFETTO_PID=$!

# Set UCP environment variables
export HB_UCP_PERFETTO_CONFIG_PATH=ucp_system.json
export HB_UCP_ENABLE_PERFETTO=true

# Run the UCP application
<App command>

# Wait for the background perfetto process to finish writing trace data
wait $PERFETTO_PID

# If BPU trace was enabled, disable it on ALL cores
if <enable_bpu>; then
    BPU_CORE_NUM=$(cat /sys/devices/system/bpu/core_num)
    for i in $(seq 0 $(expr $BPU_CORE_NUM - 1)); do
        echo 0 > /sys/devices/system/bpu/bpu${i}/trace
    done
fi
EOF

Important: in system mode, the tracebox perfetto process must remain running for the entire duration of the UCP application. If it exits before the app, the trace will be incomplete. After the app finishes, wait $PERFETTO_PID ensures the perfetto process completes writing all trace data before cleanup.

Step 3: Pull the trace file back to the host

After the application finishes:

scp <board_user>@<board_ip>:<work_dir>/<output_name> ./

Verify the file was transferred and has reasonable size (should be > 0 bytes).

Step 4: Tell the user what to do next

Inform the user:

• The trace file is saved at <local_path>/<output_name>
• They can open it in Perfetto UI for visualization
• If BPU trace was captured, they need the hbperfetto tool (contact Horizon support) to view BPU-specific data
• Key Perfetto UI shortcuts: w/s to zoom in/out, a/d to pan left/right, ? for help

Handling common issues

Config file reference

All config files are in this skill's reference/ directory. Read them when you need to inspect or modify the configurations before transfer.

Key parameters you might want to adjust: