XCENA Debugging Helper CLI Guide
xcena_cli is a command-line tool useful for debugging XCENA devices. It can perform various device information queries and configuration changes.
Installation Requirements
Before using the CLI tool, you need to install the required Python modules. Install them using pip:
pip install click # Command line interface creation kit
pip install pandas # Data manipulation library
pip install pyvcd # Value Change Dump file manipulation
pip install serial # Serial port communication
pip install pexpect # Automation of interactive applications
Getting Started
To run the CLI, execute the xcena_cli file as follows:
user@linux-pc:~$ xcena_cli
Basic Options
--help: Displays command usage and descriptions.
Usage: xcena_cli [OPTIONS] COMMAND [ARGS]...
XCENA Debugging Helper
Options:
--help Show this message and exit.
Commands:
num-device
device-info <device_id>
csr-slave <device_id> <msub_id> <cluster_id> <mu_id>
debug-pc <device_id>
debug-error <device_id>
dump <device_id> <start_addr(hex)> <size(hex) <= 0x2000 > [length=2] [-l littleEndian]
fw-info <device_id>
fw-update <device_id> <slot_id> <firmware_path>
fw-switch <device_id> <slot_id>
Command List
num-device
- Displays the number of currently connected devices.
# Input example
user@linux-pc:~$ xcena_cli num-device
# Output example
Number of devices : 1
device-info
- Queries information about a specific device.
# Input example
# device-info <device_id>
user@linux-pc:~$ xcena_cli device-info 0
# Output example
[Device 0]
Target : mx1p # Device target
BDF : 0000:95:00.0 # PCIe Bus:Device.Function
CXL Memory : 233GB # Total CXL memory capacity
Computable : Yes # Whether the device supports compute
MU Cores : 3,072 (24 Subsystem × 4 Cluster × 32 MU Core) # Total MU Cores with topology breakdown
csr-slave
- Queries the CSR of Slave MU.
- The target MU must exist in the device info bitmap.
# Input example
# csr-slave <device_id> <msub_id> <cluster_id> <mu_id>
user@linux-pc:~$ xcena_cli csr-slave 0 0 0 0
# Output example
MU 0 0 0 0 400c0000
MV_TOP_CSR_MON_MU_ID = 0x0000_0000_0000_0000
MV_TOP_CSR_MON_PERFORMANCE = 0x0000_0000_0000_0000
MV_TOP_CSR_REG_FETCH_STALL = 0x0000_0000_0000_0001
MV_TOP_CSR_REG_W1C = 0x0000_0000_0000_0000
MV_TOP_CSR_REG_REMAP_4M = 0x0000_0000_0000_0000
REG_REMAP_BASE_4M_SEG[30:0] = 0 (0x0)
REG_REMAP_L0C_EN[31:31] = 0 (0x0)
# Invalid target example
# csr-slave <device_id> <msub_id> <cluster_id> <mu_id>
user@linux-pc:~$ xcena_cli csr-slave 0 0 0 8
Invalid MSUB0_CLST0_MU8 (Bitmap: 0xff)
user@linux-pc:~$ xcena_cli csr-slave 0 0 1 0
Invalid MSUB0_CLST1 (Bitmap: 0x1)
user@linux-pc:~$ xcena_cli csr-slave 0 1 0 0
Invalid MSUB1 (Bitmap: 0x1)
debug-pc
- Debugs the program counter of a specific device.
# Input example
# debug-pc <device_id>
user@linux-pc:~$ xcena_cli debug-pc 0
# Output example
======== MSUB[0] CLST[0] ========[Admin: 0x21814]========[Master: 0x213f4]========
| S0 | S1 | S2 | S3 | S4 | S5 | S6 | S7 |
T0 | 0x0 | 0x0 | 0x0 | 0x0 | 0x0 | 0x0 | 0x0 | 0x0 |
T1 | 0x0 | 0x0 | 0x0 | 0x0 | 0x0 | 0x0 | 0x0 | 0x0 |
T2 | 0x0 | 0x0 | 0x0 | 0x0 | 0x0 | 0x0 | 0x0 | 0x0 |
T3 | 0x0 | 0x0 | 0x0 | 0x0 | 0x0 | 0x0 | 0x0 | 0x0 |
debug-error
- Debugs the error log of a specific device.
# Input example
# debug-error <device_id>
user@linux-pc:~$ xcena_cli debug-error 0
# Output example
===== HIO[0] print_mu_error =====
MV_TOP_CSR_MON_IRQ = 0x0000_0000_0000_0000
my_error[0:0] = 0 (0x0)
ext_error[1:1] = 0 (0x0)
clust_mu_error[2:2] = 0 (0x0)
mon_irq_sw_break[7:4] = 0 (0x0)
mon_irq_inst0[11:8] = 0 (0x0)
mon_irq_error_dmb_lock[15:12] = 0 (0x0)
mon_irq_error_wb_lock[19:16] = 0 (0x0)
mon_irq_trap_error_vec[23:20] = 0 (0x0)
mon_irq_axi_bresp_error[27:24] = 0 (0x0)
mon_axi_berror_id[31:28] = 0 (0x0)
mon_irq_axi_rresp_error[35:32] = 0 (0x0)
mon_axi_rerror_id[39:36] = 0 (0x0)
mon_irq_cop_div_zero[43:40] = 0 (0x0)
mon_cop_error_tid[47:44] = 0 (0x0)
...
dump
- Queries a memory dump from a specific address.
start_addr(hex): Starting address (hex format)size(hex) <= 0x2000: Query size (hex format) (maximum 0x2000)[length=2]: Unit length (default: 2)[-l littleEndian]: Endian format (default: little endian)
# Input example
# dump <device_id> <start_addr(hex)> <size(hex) <= 0x2000 > [length=2] [-l littleEndian]
user@linux-pc:~$ xcena_cli dump 0 0x2000A000000 0x100
# Output example
============================================
| M L | M L |
============================================
0x2000a000000 |0x0000_0000_0000_1234|0x0000_0000_0000_0008|
0x2000a000010 |0x0000_0000_0000_2f00|0x0000_0000_0000_0000|
0x2000a000020 |0x0000_0000_0000_0001|0x0000_0000_0000_0000|
0x2000a000030 |0x0000_0000_0000_0000|0x0000_0000_0000_0001|
0x2000a000040 |0x0000_0000_0000_0000|0x0000_0000_0000_0000|
0x2000a000050 |0x0000_0000_0000_0000|0x0000_0000_0000_0000|
0x2000a000060 |0x0001_0000_0000_0000|0x0000_0000_0000_0002|
0x2000a000070 |0x0000_0000_0000_0001|0x0000_0000_0000_0001|
0x2000a000080 |0x0000_0000_0000_0000|0x0000_0000_0000_0020|
0x2000a000090 |0x0000_0000_0000_0004|0x0000_0000_0000_0008|
0x2000a0000a0 |0x0000_0000_0000_0004|0x0000_0200_0a00_0198|
0x2000a0000b0 |0x0000_0000_0000_0008|0x0000_0200_0a00_01a0|
0x2000a0000c0 |0x0000_0000_0000_0100|0x0000_0200_0a00_02a0|
0x2000a0000d0 |0x0000_0000_0000_0100|0x0000_0000_4000_0000|
0x2000a0000e0 |0x0000_0200_0000_0000|0x0000_0201_0000_0000|
0x2000a0000f0 |0x0000_0000_0100_0000|0x0000_0201_0200_0000|
fw-info
- Displays CXL firmware/device information for the specified device.
# Input example
# fw-info <device_id>
user@linux-pc:~$ xcena_cli fw-info 0
# Output example
Device Information for 0000:11:00.0:
Firmware Revision: xcena-1.0.0
Total Capacity: 4,294,967,296 bytes
FW Slots Supported: 4
Active Slot: 1
Staged Slot: 0
Online Activation: No
Slot Revisions:
SLOT1: 1.0
SLOT2: 1.1
SLOT3: 1.2
SLOT4: 1.3
fw-update
- Updates CXL firmware for the specified device via mailbox. Arguments are positional:
<device_id> <slot_id> <firmware_path>.
# Input example
# fw-update <device_id> <slot_id> <firmware_path>
user@linux-pc:~$ xcena_cli fw-update 0 2 fw.bin
# Output example
args: device_id=0, firmware='fw.bin', slot=2
resolved BDF: mem0 -> 0000:11:00.0
matched index: 0 (0000:11:00.0)
start firmware update: slot=2, file='fw.bin'
Firmware update completed successfully!
fw-switch
- Switches the active firmware slot on a CXL device. Automatically detects online activation support and selects the appropriate activation method.
# Input example
# fw-switch <device_id> <slot_id>
user@linux-pc:~$ xcena_cli fw-switch 0 3
# Output example (cold reset device)
Current active slot: 2
Target slot: 3 (revision: 1.0.1)
Activating firmware in slot 3...
Firmware slot 3 staged. Cold reset required to apply.
# Output example (online activation device)
Current active slot: 2
Target slot: 3 (revision: 1.0.1)
Activating firmware in slot 3...
Firmware activation completed. Active slot switched to 3.
# Edge cases
# Already active slot
user@linux-pc:~$ xcena_cli fw-switch 0 3
Slot 3 is already the active slot.
# Empty slot
user@linux-pc:~$ xcena_cli fw-switch 0 2
Error: Slot 2 is empty. Cannot activate an empty firmware slot.