Setting up the Board and Application Deployment

Introduction

This document shows how to set up the board and run the Built-In Self Test (BIST) application.

This guide and its prebuilts are targeted for AMD EDF 26.06 and AMD 2026.1 toolchain.

Revision History

Version - v1.3

Refreshed app for AMD EDF 26.06 compatibility with updates across test files and documentation.

Change Log

Test Updates:

  • CAN: Ensure interface is down before configuration

  • Ethernet: Replaced python3-ping3 dependency with system ping and included endX interfaces in filtering

  • Display: Unified config structure and now detects active display driver via sysfs

  • TPM: Updated PCR validation for EFI boot flow and explicitly select kernel TPM device for all tpm2-tools calls

  • Video: Updated Golden Images for filesink tests(No functional change in the tests)

  • IIO: Updated to use new hwmon-style interface exposed by the newer kernel.

Documentation:

  • Updated for compatibility with AMD EDF 26.06

Version - v1.2

Refreshed app for Ubuntu 24.04 compatibility with updates across test files and documentation.

Change Log

Test Updates:

  • Ethernet: Refined interface detection logic to ensure correct enumeration of interfaces.

  • CAN: Updated python-can usage to align with the latest API and remove deprecated parameters.

  • Display & PWM: Standardized timeout handling by replacing inputimeout with timeout_handler.

  • GPIO: Addressed a corner case in 1wire_brake_ctrl to ensure correct test passes.

  • TTY: Adjusted pymodbus imports and parameters for compatibility with Ubuntu 24.04.

  • Common: Introduced timeout_handler.py for consistent user input timeout management across tests.

Documentation:

  • Updated for compatibility with Ubuntu 24.04.

  • Added known issues specific to Ubuntu 24.04.

Version - v1.1

Added additional support for KD240 starter kit on Ubuntu 22.04.

Version - v1.0

Initial release on Ubuntu 22.04 with support for KV260 and KR260 starter kits.

Set up the Host Machine

Note: Setting up the host machine is only required to test the ethernet and SFP+ interfaces. If this is skipped, the tests for these interfaces fail.

  • Install the NIC card into the host machine.

  • The host machine can be assigned an IP in two ways:

    • DHCP IP Assignment

    • Static IP Assignment

  • Configure the host machine to have a DHCP/Static IP and set the BIST_REMOTE_HOST_IP environment variable on the AMD Kria ™ board.

    Example:

      export BIST_REMOTE_HOST_IP=<IP_Address>

  • Install iperf3.

    • For Ubuntu, use the following command:

      sudo apt install iperf3

    • For Windows, use the appropriate download link from this page.

  • Start an iperf3 server on the host machine using the following command:

    iperf3 -s -p 5201

Set up the Board

Supported Starter Kits

The BIST application requires the following hardware setup to run the full suite of hardware tests. See the board specific pages:

  1. KV260 Board Setup

  2. KR260 Board Setup

  3. KD240 Board Setup

Tested Artifacts

Testing was performed with the following artifacts:

KD240 platform artifacts

Component Version
Boot Firmware K24-BootFW-01.06.bin
Linux Kernel 6.18.10
kd240-bist-firmware v1.2

KR260 platform artifacts

Component Version
Boot Firmware K26-BootFW-01.07.bin
Linux Kernel 6.18.10
kr260-bist-firmware v1.2

KV260 platform artifacts

Component Version
Boot Firmware K26-BootFW-01.07.bin
Linux Kernel 6.18.10
kv260-bist-firmware v1.2

Please refer to the Kria Wiki to obtain latest linux image and boot firmware.

Application docker image

Docker Image Version
xilinx/kria-bist 1.3-edf-26.06

Boot Linux

Before continuing with the BIST application specific instructions, if not yet done so, boot Linux with instructions from:

  1. Kria Starter Kit Linux Boot on KV260

  2. Kria Starter Kit Linux Boot on KR260

  3. Kria Starter Kit Linux Boot on KD240

Download BIST Docker Image

  • Pull the docker image

    sudo docker pull xilinx/kria-bist:1.3-edf-26.06

  • The storage volume on the SD card can be limited with multiple docker images installed. If there are space issues, use the following command to remove existing docker images.

    sudo docker rmi --force <image>

  • You can find the images installed with the following command:

    sudo docker images

  • This docker image is common across all three boards which contains kria-bist application, board firmwares, dependent packages, kernel modules and libraries including motor control library for kria motor control for KD240.

Install BIST PL Firmware on the Host

Copy and install the application firmware from the container into the host system (in /lib/firmware/Xilinx). This installation only needs to be performed once per target board.

  • Export the FW_NAME Environment Variable. Set FW_NAME variable to correct firmware for desired board

    export FW_NAME=kv260-bist      #For kv260-bist
export FW_NAME=kr260-bist      #For kr260-bist
export FW_NAME=kd240-bist      #For kd240-bist

  • Create Firmware directory on target Host

    sudo mkdir -p /lib/firmware/xilinx/${FW_NAME}

  • Install BIST firmware for KR260/KD240

    sudo docker run --rm \
    -v /lib/firmware/xilinx/${FW_NAME}:/opt/firmware/xilinx/${FW_NAME} \
    xilinx/kria-bist:1.3-edf-26.06 sh -c "
    dfx-fw-install     --fw-name ${FW_NAME}"

  • Install BIST firmware for KV260 which requires an additional ap1302 firmware installation

    sudo docker run --rm \
    -v /lib/firmware/xilinx/${FW_NAME}:/opt/firmware/xilinx/${FW_NAME} \
    -v /lib/firmware:/opt/firmware/xilinx/ap1302 \
    xilinx/kria-bist:1.3-edf-26.06 sh -c "
    dfx-fw-install     --fw-name ${FW_NAME} &&
    dfx-fw-install --fw-name ap1302 --src /lib/firmware/ap1302 \
    "

Setup SSH with X-forwarding

NOTE: Setting up an SSH connection is only required to test the ximagesink tests of the video module on KV260 board. If this is skipped, those tests will fail

  • To run the bist test suite, the test instructions should run over an SSH connection with X-forwarding enabled.

    Examples:

    • On Host, run:

      ssh -X amd-edf@<Kria Starter Kit IP address>

      NOTE: If all ethernet cables are plugged in, feel free to use any IP.

    • On Windows, download Mobaxterm, which automatically enables X-forwarding when creating a new ssh connection.

Miscellaneous Preparation

  • Verify if the SSH terminal is using the correct authority file.

    • Install xauth application package

    sudo dnf install xauth

    • The Xauthority output should look something like this.

    xauth -v list
Using authority file /home/amd-edf/.Xauthority
amd-edf/unix:11  MIT-MAGIC-COOKIE-1  dac917db82c1ae575d74e94b44e75aba

    • If incorrect or no authority file is present, do the following steps:

    rm -rf ~/.Xaut*

    • Reboot the target board.

    sudo reboot

    • Check the xauth -v list after reboot(in SSH terminal), it should display the correct authority file on the output console.

  • The BIST application tests the fan. Therefore, if a fan is present stop the fancontrol service before running the docker for the testing to function as intended.

    sudo systemctl stop fancontrol

  • On KV260/KR260 disable desktop environment before running the docker for the display testing to function as intended. On KD240 this step can be skipped as we are using a headless Server image.

      sudo systemctl stop kmsconvt@tty1

  • Remember to start the fancontrol service after exiting the docker container.

    sudo systemctl start fancontrol

  • After running the application and exiting the docker container, the desktop environment can be enabled again.

      sudo systemctl start kmsconvt@tty1

Run BIST Docker Image

  • Launch the docker container using the following command:

    sudo docker run --rm -it --privileged \
    --net=host \
    -v /dev:/dev \
    -v /sys:/sys \
    --volume=/home/amd-edf/.Xauthority:/root/.Xauthority:rw \
    -v /var/run/dfx-mgrd.socket:/var/run/dfx-mgrd.socket  \
    -e DISPLAY -e XDG_SESSION_TYPE \
    xilinx/kria-bist:1.3-edf-26.06 \
    /bin/bash

  • It launches the bist image in a new container and drops the user into a bash shell.

    bash-5.2#

NOTE: Unless otherwise specified, the commands in the following sections are intended to be executed from within the running BIST container.

Load BIST Firmware and Modules

Before running the test suite, load BIST application firmware and the required kernel modules from as shown below.

  • Export the FW_NAME Environment Variable

    export FW_NAME=kv260-bist      #For kv260-bist
export FW_NAME=kr260-bist      #For kr260-bist
export FW_NAME=kd240-bist      #For kd240-bist

  • List the installed application firmware binaries.

    Execute below command to verify that it is captured under the listPackage function, and to have dfx-mgrd, re-scan and register all accelerators in the firmware directory tree.

    bash-5.2# dfx-mgr-client -listPackage

Example output:
ID accelType   Base        slotLoc Accelerator
-- ----------- ----------- ------- -----------
1 RPU         rpu         -1      k26-r5-0-proxy-freertos
2 RPU         rpu         -1      k26-r5-0-matrix-freertos
3 RPU         rpu         -1      k26-r5-0-echo-freertos
4 XRT_FLAT    k26-star... 0       k26-starter-kits

  • Load Kernel Modules

    bash-5.2# kria-modules-load  --fw-name ${FW_NAME}

  • Load Application Firmware

    When there is already another accelerator/firmware being activated, unload it first, then load the desired BIST firmware.

    bash-5.2# dfx-mgr-client -unload 4                    #Previous FW ID(in above case)
bash-5.2# dfx-mgr-client -loadByName ${FW_NAME}       #Load desired BIST Firmware

    NOTE: The firmware consists of bitstream, device tree overlay (dtbo) file. The firmware is loaded dynamically on user request once Linux is fully booted.

  • On KR260 bring down the SFP 10G interface immediately after loading the firmware if a setup is not connected to test the peripheral. The reason being, when the link is not connected, the clock becomes unstable, and the block lock register of the XXV IP becomes inaccessible and results in a crash. Known Issues

    • Look for 10G interface after loading the Firmware. Speed should be listed as 10000

    bash-5.2# cd /sys/class/net/
bash-5.2# ls
docker0  end0  end1  eth0  eth1  eth2  lo  sit0

bash-5.2# cat eth0/speed
10000

    • Bring down the interface immediately if a setup is not connected

    bash-5.2# ifconfig eth0 down       #eth0 in this case

Setup IP addresses on the Kria board

  • Set the BIST_REMOTE_HOST_IP environment variable on Kria board

    Example:

      export BIST_REMOTE_HOST_IP=<IP_Address>

  • You can assign IP addresses in two ways:

    • DHCP IP Assignment - IP addresses are auto-assigned.

    • Static IP Assignment - You need to set a Static IP for the eth interfaces under test. Make sure that the Static IPs are in the same subnet as the remote host machine.

Run the BIST Application

The application is installed under /opt/xilinx/kria-bist. Navigate to the “tests” directory from where the BIST tests are to be run.

cd /opt/xilinx/kria-bist/tests

Usage

Commonly used command line switches for BIST.

pytest [OPTIONS]

OPTIONS:
  --collect-only                Collect the tests
  --board <target_board>        Specify target board
  -k <test_name>                Run an individual test
  -m <module_name>              Specify module name

Output and Logs

The pytest command line output has two separate sessions as follows:

  • Test session

    It displays the number of collected, deselected, and selected tests. Current running test is also shown.

    For example:

    ============================= test session starts ==============================
platform linux -- Python 3.12.12, pytest-8.0.2, pluggy-1.4.0
rootdir: /opt/xilinx/kria-bist/tests
configfile: pytest.ini
collected 34 items / 33 deselected / 1 selected

gpio/test_bist_gpio.py::test_gpio[pmod0]

  • Live Log call

    This displays the current status of the test.

    1. Start of test: Indicates that the test has started.

    2. Test observations: Prints the test observation on the command line.

    3. Test passed/failed: Declares the test result, that is, pass/fail.

    4. End of Test: Indicates that the test has ended.

    For example:

    -------------------------------- live log call ---------------------------------
------------------------------------------
Start of test
Write pattern: 0001, Read pattern 0001 : Match
Write pattern: 0010, Read pattern 0010 : Match
Write pattern: 0100, Read pattern 0100 : Match
Write pattern: 1000, Read pattern 1000 : Match
Test passed
End of test
PASSED                                                                   [100%]

======================= 1 passed, 33 deselected in 1.02s =======================

  • A log file (kria_bist_pytest.log) is created in the current directory.

Examples

  • Run the entire BIST test suite for a target board.

    pytest --board kv260     #For KV260
pytest --board kr260     #For KR260
pytest --board kd240     #For KD240

  • Run individual tests.

    The following example runs the pmod0 test on the KV260 as target board.

    pytest -k pmod0 --board kv260

============================= test session starts ==============================
platform linux -- Python 3.12.12, pytest-8.0.2, pluggy-1.4.0
rootdir: /opt/xilinx/kria-bist/tests
configfile: pytest.ini
collected 34 items / 33 deselected / 1 selected

gpio/test_bist_gpio.py::test_gpio[pmod0]
-------------------------------- live log call ---------------------------------
------------------------------------------
Start of test
Write pattern: 0001, Read pattern 0001 : Match
Write pattern: 0010, Read pattern 0010 : Match
Write pattern: 0100, Read pattern 0100 : Match
Write pattern: 1000, Read pattern 1000 : Match
Test passed
End of test
PASSED                                                                   [100%]

======================= 1 passed, 33 deselected in 1.01s =======================

  • Collect test cases.

    Collect all the tests for a target board.

    pytest --collect-only --board kv260

========================== test session starts ===============================
platform linux -- Python 3.12.12, pytest-8.0.2, pluggy-1.4.0
rootdir: /opt/xilinx/kria-bist/tests
configfile: pytest.ini
collected 40 items

<Module disk/test_bist_disk.py>
  <Function test_disk[usb1_read_performance]>
  <Function test_disk[usb1_write_performance]>
  <Function test_disk[usb2_read_performance]>
  <Function test_disk[usb2_write_performance]>
  <Function test_disk[usb3_read_performance]>
  <Function test_disk[usb3_write_performance]>
  <Function test_disk[usb4_read_performance]>
  <Function test_disk[usb4_write_performance]>
  <Function test_disk[sd_read_performance]>
  <Function test_disk[sd_write_performance]>
<Module display/test_bist_display.py>
  <Function test_display[display_connectivity]>
  <Function test_display[display_modetest]>
<Module eeprom/test_bist_eeprom.py>
  <Function test_eeprom[som_eeprom]>
  <Function test_eeprom[carrier_card_eeprom]>
<Module eth/test_bist_eth.py>
  <Function test_eth[ethernet1_ping]>
  <Function test_eth[ethernet1_perf]>
<Module gpio/test_bist_gpio.py>
  <Function test_gpio[pmod0]>
<Module i2c/test_bist_i2c.py>
  <Function test_i2c[ps_i2c_bus_main]>
  <Function test_i2c[axi_i2c_bus_main]>
  <Function test_i2c[axi_i2c_bus_ch0]>
<Module iio/test_bist_iio.py>
  <Function test_iio[ina260_current]>
<Module mtd/test_bist_mtd.py>
  <Function test_mtd[qspi_read_write]>
  <Function test_mtd[qspi_read_performance]>
  <Function test_mtd[qspi_write_performance]>
<Module pwm/test_bist_pwm.py>
  <Function test_pwm[fan]>
<Module tpm/test_bist_tpm.py>
  <Function test_tpm[tpm2_getcap]>
  <Function test_tpm[tpm2_selftest]>
  <Function test_tpm[tpm2_getrandom]>
  <Function test_tpm[tpm2_hash]>
  <Function test_tpm[tpm2_pcrread]>
  <Function test_tpm[tpm2_pcrextend]>
  <Function test_tpm[tpm2_pcrreset]>
<Module video/test_bist_video.py>
  <Function test_video[ar1335_ap1302_ximagesink]>
  <Function test_video[ar1335_ap1302_perf]>
  <Function test_video[tpg_ap1302_ximagesink]>
  <Function test_video[tpg_ap1302_perf]>
  <Function test_video[imx219_filesink]>
  <Function test_video[imx219_perf]>
  <Function test_video[ar1335_filesink]>
  <Function test_video[ar1335_perf]>

====================== 40 tests collected in 1.02s ===========================

  • Collect all tests for a specific testmodule for a target board.

    pytest --collect-only --board kv260 -m video

============================= test session starts ==============================
platform linux -- Python 3.12.12, pytest-8.0.2, pluggy-1.4.0
rootdir: /opt/xilinx/kria-bist/tests
configfile: pytest.ini
collected 34 items / 26 deselected / 8 selected

<Module video/test_bist_video.py>
  <Function test_video[ar1335_ap1302_ximagesink]>
  <Function test_video[ar1335_ap1302_perf]>
  <Function test_video[tpg_ap1302_ximagesink]>
  <Function test_video[tpg_ap1302_perf]>
  <Function test_video[imx219_filesink]>
  <Function test_video[imx219_perf]>
  <Function test_video[ar1335_filesink]>
  <Function test_video[ar1335_perf]>

================ 8/34 tests collected (26 deselected) in 0.99s =================

  • Run all tests for a target board and the module.

    pytest --board kv260 -m video

============================= test session starts ==============================
platform linux -- Python 3.12.12, pytest-8.0.2, pluggy-1.4.0
rootdir: /opt/xilinx/kria-bist/tests
configfile: pytest.ini
collected 34 items / 26 deselected / 8 selected

video/test_bist_video.py::test_video[ar1335_ap1302_ximagesink]
-------------------------------- live log call ---------------------------------
------------------------------------------
Start of test
Please observe the pop-up window
Do you see color bar test pattern in the window [Y/N]?

** (gst-launch-1.0:23): CRITICAL **: 18:29:06.145: Unsupported property type GstParamArray for property crop-bounds
y
User reports that pattern was observed in the window
Test passed
End of test
PASSED
video/test_bist_video.py::test_video[ar1335_ap1302_perf]
-------------------------------- live log call ---------------------------------
------------------------------------------
Start of test

** (gst-launch-1.0:23): CRITICAL **: 18:29:06.145: Unsupported property type GstParamArray for property crop-bounds
Actual fps: 30.0, Target fps:30 - Actual fps within accepted range
Test passed
End of test
PASSED
video/test_bist_video.py::test_video[tpg_ap1302_ximagesink]
-------------------------------- live log call ---------------------------------
------------------------------------------
Start of test
Please observe the pop-up window
Do you see color bar test pattern in the window [Y/N]?

** (gst-launch-1.0:23): CRITICAL **: 18:29:06.145: Unsupported property type GstParamArray for property crop-bounds
y
User reports that pattern was observed in the window
Test passed
End of test
PASSED
video/test_bist_video.py::test_video[tpg_ap1302_perf]
-------------------------------- live log call ---------------------------------
------------------------------------------
Start of test

** (gst-launch-1.0:23): CRITICAL **: 18:29:06.145: Unsupported property type GstParamArray for property crop-bounds
Actual fps: 30.003, Target fps:30 - Actual fps within accepted range
Test passed
End of test
PASSED
video/test_bist_video.py::test_video[imx219_filesink]
-------------------------------- live log call ---------------------------------
------------------------------------------
Start of test

** (gst-launch-1.0:23): CRITICAL **: 18:29:06.145: Unsupported property type GstParamArray for property crop-bounds

(gst-launch-1.0:89): GStreamer-CRITICAL **: 21:29:17.009: gst_structure_fixate_field_nearest_int: assertion 'IS_MUTABLE (structure)' failed

(gst-launch-1.0:89): GStreamer-CRITICAL **: 21:29:17.009: gst_structure_fixate_field_nearest_int: assertion 'IS_MUTABLE (structure)' failed

(gst-launch-1.0:89): GStreamer-CRITICAL **: 21:29:17.010: gst_structure_fixate_field_nearest_fraction: assertion 'IS_MUTABLE (structure)' failed
Test Image and Golden Image match
Test passed
End of test
PASSED
video/test_bist_video.py::test_video[imx219_perf]
-------------------------------- live log call ---------------------------------
------------------------------------------
Start of test

** (gst-launch-1.0:23): CRITICAL **: 18:29:06.145: Unsupported property type GstParamArray for property crop-bounds
Actual fps: 30.004, Target fps:30 - Actual fps within accepted range
Test passed
End of test
PASSED
video/test_bist_video.py::test_video[ar1335_filesink]
-------------------------------- live log call ---------------------------------
------------------------------------------
Start of test

** (gst-launch-1.0:23): CRITICAL **: 18:29:06.145: Unsupported property type GstParamArray for property crop-bounds

(gst-launch-1.0:89): GStreamer-CRITICAL **: 21:29:17.009: gst_structure_fixate_field_nearest_int: assertion 'IS_MUTABLE (structure)' failed

(gst-launch-1.0:89): GStreamer-CRITICAL **: 21:29:17.009: gst_structure_fixate_field_nearest_int: assertion 'IS_MUTABLE (structure)' failed

(gst-launch-1.0:89): GStreamer-CRITICAL **: 21:29:17.010: gst_structure_fixate_field_nearest_fraction: assertion 'IS_MUTABLE (structure)' failed
Test Image and Golden Image match
Test passed
End of test
PASSED
video/test_bist_video.py::test_video[ar1335_perf]
-------------------------------- live log call ---------------------------------
------------------------------------------
Start of test

** (gst-launch-1.0:23): CRITICAL **: 18:29:06.145: Unsupported property type GstParamArray for property crop-bounds
Actual fps: 30.004, Target fps:30 - Actual fps within accepted range
Test passed
End of test
PASSED                                                                   [100%]

==================== 8 passed, 26 deselected in 42.11s =======================

Next Steps

Copyright © 2025 Advanced Micro Devices, Inc

Terms and Conditions