Add support for the Alibaba Cloud AS02MC04 Kintex UltraScale+ PCIe board

[dkozel]

I'm starting to add support for this PCIe accelerator board as it is currently available inexpensively on eBay and Aliexpress. It had a Xilinx KU3P FPGA, which is supported by Vivado's zero cost license.

Some basic documentation and reverse engineering has been done by other people:

https://essenceia.github.io/projects/alibaba_cloud_fpga/
https://gist.github.com/Chester-Gillon/765d6286b1c34c7dc26a7b4c4dd0c48c

I'm collecting the info from external posts and will make some test projects and notes here:
https://github.com/dkozel/Alibaba-Cloud-FPGA

The current status of my board addition is here:

platforms/alibaba_xcku3p.py
targets/alibaba_xcku3p.py

Todo:

• Resolve basic build issues
• Add JTAG UART support for Ultrascale+
• Test LED chaser
• Add LiteScope example
• Add QSPI Flash (mt25qu256-spi-x1_x2_x4)
• Test SFP+ interfaces up to 25 Gb/s Ethernet
• Test PCIe Gen3 x4
• Test PCIe Gen3 x8
• ??
• Document how to Add a new board

[enjoy-digital]

Thanks @dkozel for the initial support. I just also received the board I ordered. If you don't mind, I'm going to create a PR from your fork, merge it and do some tests (and eventual fixes) from there.

[enjoy-digital]

The PR: #715.

[enjoy-digital]

@dkozel: I just did some cosmetic cleanups and added the commands I tested succesfully on my setup:
ed0a360

        __   _ __      _  __
       / /  (_) /____ | |/_/
      / /__/ / __/ -_)>  <
     /____/_/\__/\__/_/|_|
   Build your hardware, easily!

 (c) Copyright 2012-2025 Enjoy-Digital
 (c) Copyright 2007-2015 M-Labs

 BIOS built on Dec 31 2025 09:26:02
 BIOS CRC passed (1f8f58e7)

 LiteX git sha1: 67932fdfb

--=============== SoC ==================--
CPU:		VexRiscv @ 100MHz
BUS:		wishbone 32-bit @ 4GiB
CSR:		32-bit data big ordering
ROM:		128.0KiB
SRAM:		8.0KiB

--============== Boot ==================--
Booting from serial...
Press Q or ESC to abort boot completely.
sL5DdSMmkekro
Timeout
No boot medium found

--============= Console ================--

litex> ident
Ident: LiteX SoC on Alibaba Cloud KU3P Board 2025-12-31 09:25:45

[enjoy-digital]

PCIe Gen3 X4 is working with: 84b01ca

[dkozel]

Thanks! That's great. I have it working over JTAG UART now and will install it in the PC soon.

Should the jtag-config file be prog/openocd_xcu_ft232.cfg? I authored that file and it's been merged, but I think it is not completely correct.

I'm getting this output for the command you used/documented:

litex_term jtag --jtag-config=openocd_xc7_ft232.cfg
Open On-Chip Debugger 0.12.0
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html
DEPRECATED! use 'adapter driver' not 'interface'
DEPRECATED! use 'ftdi vid_pid' not 'ftdi_vid_pid'
DEPRECATED! use 'ftdi channel' not 'ftdi_channel'
DEPRECATED! use 'ftdi layout_init' not 'ftdi_layout_init'
Info : auto-selecting first available session transport "jtag". To override use 'transport select <transport>'.
DEPRECATED! use 'adapter speed' not 'adapter_khz'
fpga_program
jtagstream_serve
Info : ftdi: if you experience problems at higher adapter clocks, try the command "ftdi tdo_sample_edge falling"
Info : clock speed 25000 kHz
Info : JTAG tap: xc7.tap tap/device found: 0x04a63093 (mfg: 0x049 (Xilinx), part: 0x4a63, ver: 0x0)
Warn : JTAG tap: xc7.tap       UNEXPECTED: 0x04a63093 (mfg: 0x049 (Xilinx), part: 0x4a63, ver: 0x0)
Error: JTAG tap: xc7.tap expected 1 of 35: 0x03622093 (mfg: 0x049 (Xilinx), part: 0x3622, ver: 0x0)
Error: JTAG tap: xc7.tap expected 2 of 35: 0x03620093 (mfg: 0x049 (Xilinx), part: 0x3620, ver: 0x0)
Error: JTAG tap: xc7.tap expected 3 of 35: 0x037c4093 (mfg: 0x049 (Xilinx), part: 0x37c4, ver: 0x0)
Error: JTAG tap: xc7.tap expected 4 of 35: 0x0362f093 (mfg: 0x049 (Xilinx), part: 0x362f, ver: 0x0)
Error: JTAG tap: xc7.tap expected 5 of 35: 0x037c8093 (mfg: 0x049 (Xilinx), part: 0x37c8, ver: 0x0)
Error: JTAG tap: xc7.tap expected 6 of 35: 0x037c7093 (mfg: 0x049 (Xilinx), part: 0x37c7, ver: 0x0)
Error: JTAG tap: xc7.tap expected 7 of 35: 0x037c3093 (mfg: 0x049 (Xilinx), part: 0x37c3, ver: 0x0)
Error: JTAG tap: xc7.tap expected 8 of 35: 0x0362e093 (mfg: 0x049 (Xilinx), part: 0x362e, ver: 0x0)
Error: JTAG tap: xc7.tap expected 9 of 35: 0x037c2093 (mfg: 0x049 (Xilinx), part: 0x37c2, ver: 0x0)
Error: JTAG tap: xc7.tap expected 10 of 3: 0x0362d093 (mfg: 0x049 (Xilinx), part: 0x362d, ver: 0x0)
Error: JTAG tap: xc7.tap expected 11 of 3: 0x0362c093 (mfg: 0x049 (Xilinx), part: 0x362c, ver: 0x0)
Error: JTAG tap: xc7.tap expected 12 of 3: 0x03632093 (mfg: 0x049 (Xilinx), part: 0x3632, ver: 0x0)
Error: JTAG tap: xc7.tap expected 13 of 3: 0x03631093 (mfg: 0x049 (Xilinx), part: 0x3631, ver: 0x0)
Error: JTAG tap: xc7.tap expected 14 of 3: 0x03636093 (mfg: 0x049 (Xilinx), part: 0x3636, ver: 0x0)
Error: JTAG tap: xc7.tap expected 15 of 3: 0x03647093 (mfg: 0x049 (Xilinx), part: 0x3647, ver: 0x0)
Error: JTAG tap: xc7.tap expected 16 of 3: 0x0364c093 (mfg: 0x049 (Xilinx), part: 0x364c, ver: 0x0)
Error: JTAG tap: xc7.tap expected 17 of 3: 0x03651093 (mfg: 0x049 (Xilinx), part: 0x3651, ver: 0x0)
Error: JTAG tap: xc7.tap expected 18 of 3: 0x03747093 (mfg: 0x049 (Xilinx), part: 0x3747, ver: 0x0)
Error: JTAG tap: xc7.tap expected 19 of 3: 0x03656093 (mfg: 0x049 (Xilinx), part: 0x3656, ver: 0x0)
Error: JTAG tap: xc7.tap expected 20 of 3: 0x03752093 (mfg: 0x049 (Xilinx), part: 0x3752, ver: 0x0)
Error: JTAG tap: xc7.tap expected 21 of 3: 0x03751093 (mfg: 0x049 (Xilinx), part: 0x3751, ver: 0x0)
Error: JTAG tap: xc7.tap expected 22 of 3: 0x03671093 (mfg: 0x049 (Xilinx), part: 0x3671, ver: 0x0)
Error: JTAG tap: xc7.tap expected 23 of 3: 0x036b3093 (mfg: 0x049 (Xilinx), part: 0x36b3, ver: 0x0)
Error: JTAG tap: xc7.tap expected 24 of 3: 0x036b7093 (mfg: 0x049 (Xilinx), part: 0x36b7, ver: 0x0)
Error: JTAG tap: xc7.tap expected 25 of 3: 0x036bb093 (mfg: 0x049 (Xilinx), part: 0x36bb, ver: 0x0)
Error: JTAG tap: xc7.tap expected 26 of 3: 0x036bf093 (mfg: 0x049 (Xilinx), part: 0x36bf, ver: 0x0)
Error: JTAG tap: xc7.tap expected 27 of 3: 0x03667093 (mfg: 0x049 (Xilinx), part: 0x3667, ver: 0x0)
Error: JTAG tap: xc7.tap expected 28 of 3: 0x03682093 (mfg: 0x049 (Xilinx), part: 0x3682, ver: 0x0)
Error: JTAG tap: xc7.tap expected 29 of 3: 0x03687093 (mfg: 0x049 (Xilinx), part: 0x3687, ver: 0x0)
Error: JTAG tap: xc7.tap expected 30 of 3: 0x03692093 (mfg: 0x049 (Xilinx), part: 0x3692, ver: 0x0)
Error: JTAG tap: xc7.tap expected 31 of 3: 0x03691093 (mfg: 0x049 (Xilinx), part: 0x3691, ver: 0x0)
Error: JTAG tap: xc7.tap expected 32 of 3: 0x03696093 (mfg: 0x049 (Xilinx), part: 0x3696, ver: 0x0)
Error: JTAG tap: xc7.tap expected 33 of 3: 0x036d5093 (mfg: 0x049 (Xilinx), part: 0x36d5, ver: 0x0)
Error: JTAG tap: xc7.tap expected 34 of 3: 0x036d9093 (mfg: 0x049 (Xilinx), part: 0x36d9, ver: 0x0)
Error: JTAG tap: xc7.tap expected 35 of 3: 0x036db093 (mfg: 0x049 (Xilinx), part: 0x36db, ver: 0x0)
Error: Trying to use configured scan chain anyway...
Warn : Bypassing JTAG setup events due to errors

## HANGS, Hit Ctrl-C and it dropped me into the shell
litex> ident
Ident: LiteX SoC on Alibaba Cloud KU3P Board 2026-01-02 19:02:06

The matching device identifier is in the cpld/xilinx-xcu.cfg file:
https://github.com/openocd-org/openocd/blob/67153cf3d50173ce911176763f1d62d96a19eaac/tcl/cpld/xilinx-xcu.cfg#L22

However trying to use my openocd_xcu_ft232.cfg file results in:

litex_term jtag --jtag-config=openocd_xcu_ft232.cfg
Open On-Chip Debugger 0.12.0
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html
DEPRECATED! use 'adapter driver' not 'interface'
DEPRECATED! use 'ftdi vid_pid' not 'ftdi_vid_pid'
DEPRECATED! use 'ftdi channel' not 'ftdi_channel'
DEPRECATED! use 'ftdi layout_init' not 'ftdi_layout_init'
/usr/bin/../share/openocd/scripts/cpld/xilinx-xcu.cfg:44: Error: set CHIP to one of XCKU025 XCKU035 XCKU040 XCKU060 XCKU095 XCKU3P XCKU5P XCKU9P XCKU11P XCKU13P XCKU15P XCVU065 XCVU080 XCVU095 XCVU3P XCKU085 XCKU115 XCVU125 XCVU5P XCVU7P XCVU160 XCVU190 XCVU440 XCVU9P XCVU11P XCVU13P
in procedure 'script' 
at file "embedded:startup.tcl", line 28
at file "prog/openocd_xcu_ft232.cfg", line 7
at file "/usr/bin/../share/openocd/scripts/cpld/xilinx-xcu.cfg", line 44
Exception in thread Thread-1 (jtag2tcp):
Traceback (most recent call last):
  File "/home/dkozel/.local/share/uv/python/cpython-3.12.12-linux-x86_64-gnu/lib/python3.12/threading.py", line 1075, in _bootstrap_inner
    self.run()
  File "/home/dkozel/.local/share/uv/python/cpython-3.12.12-linux-x86_64-gnu/lib/python3.12/threading.py", line 1012, in run
    self._target(*self._args, **self._kwargs)
  File "/data/fpga/litex/litex/litex/tools/litex_term.py", line 167, in jtag2tcp
    prog.stream(self.port, self.chain)
  File "/data/fpga/litex/litex/litex/build/openocd.py", line 204, in stream
    self.call(["openocd", "-f", config, "-f", "stream.cfg", "-c", script])
  File "/data/fpga/litex/litex/litex/build/generic_programmer.py", line 101, in call
    raise OSError(msg)
OSError: Error occured during OpenOCD's call, please check:
- OpenOCD installation.
- Access permissions.
- Hardware and cable.
- Bitstream presence.
Exception in thread Thread-3 (tcp2pty):
Traceback (most recent call last):
  File "/home/dkozel/.local/share/uv/python/cpython-3.12.12-linux-x86_64-gnu/lib/python3.12/threading.py", line 1075, in _bootstrap_inner
    self.run()
  File "/home/dkozel/.local/share/uv/python/cpython-3.12.12-linux-x86_64-gnu/lib/python3.12/threading.py", line 1012, in run
    self._target(*self._args, **self._kwargs)
  File "/data/fpga/litex/litex/litex/tools/litex_term.py", line 176, in tcp2pty
    r = self.tcp.recv(1)
        ^^^^^^^^^^^^^^^^
OSError: [Errno 107] Transport endpoint is not connected

[dkozel]

Actually reading and thinking about the error message for a few minutes... I added set CHIP XCKU3P to the openocd_xcu_ft232.cfg file and it works smoothly now. Also the "HANG" was me not realizing I needed to hit enter to have the prompt appear.

I was just about to ask if it would be reasonable to add an additional openocd_xcku3p_ft232.cfg file which just sets the CHIP value then refers to the generic openocd_xcu_ft232.cfg file, then I noticed:
https://github.com/litex-hub/litex-boards/blob/master/litex_boards/prog/openocd_xcau25p_ft323.cfg

The XCAU25P file has copied in portions of xilinx-xcu.cfg. I think that was because it was added 3 years ago and the upstream config file might not have been available on most available OpenOCD installs?

I'll open a PR revising the generic Ultrascale Plus cfg file to a XCKU3P specific one.

[dkozel]

PR for OpenOCD config: #716

[enjoy-digital]

@dkozel: Ethernet support has been added and tested on both SFPs with: c32d61f