FPGA Projects

Directory structure:

Source code for the FPGA example projects is organized into the following subdirectories under the fpga_reference_design/src/fpga/ directory:

Directory	Contents
NDI_Dec/	VHDL files for the NDI Decoder core. All files should be compiled into the NDI_Dec VHDL library rather than the default work library
NDI_Enc/	VHDL files for the NDI Encoder core. All files should be compiled into the NDI_Enc VHDL library rather than the default work library
ip/altera	Altera specific implementations of memory and FIFO blocks
ip/common	Source code common to all example designs
ip/extern	External (3rd party) IP used in the example designs
ip/packages	VHDL Packages defining various types used in the logic
ip/xilinx	Xilinx specific implementations of memory and FIFO blocks
Agilex7-Enc	Quartus Pro 25.1.1 NDI Encode project directory targeting the DK-SI-AGI027FA Agilex-7 SoC DevKit
a10-socdk-enc/	Quartus Pro 22.2 NDI Encode project directory targeting the Arria-10 SoC DevKit
a10-socdk-dec/	Quartus Pro 22.2 NDI Decode project directory targeting the Arria-10 SoC DevKit
SoCKit-Dec/	Deprecated Quartus 22.1 NDI Decode project directory targeting the Terasic SoCKit
ZCU104-Enc/	Vivado 2022.1 NDI Encode project directory targeting the Xilinx ZCU104
ZCU104-Dec/	Vivado 2022.1 NDI Decode project directory targeting the Xilinx ZCU104
Zybo-Z7-20-Enc/	Vivado 2024.2 NDI Encode project directory targeting the Digilent Zybo-Z7-20
Zybo-Z7-20-Dec/	Vivado 2024.2 NDI Decode project directory targeting the Digilent Zybo-Z7-20
Zybo-Z7-20-Enc-Lite/	"Lightweight" Vivado 2024.2 NDI Encode project directory targeting the Digilent Zybo-Z7-20 with 16-bit SDRAM interface
Arty-Z7-20-Enc/	Vivado 2024.2 NDI Encode project directory targeting the Digilent Arty-Z7-20
KV260-Enc/	Vivado 2022.1 NDI Encode project directory targeting the Xilinx Kria KV260

Build Dependencies

Xilinx

ZCU104

These projects require Vivado version 2022.1. Any edition of Vivado 2022.1 will work, including the "WebPACK" edition available via free download from Xilinx.

You must have a valid license for the Xilinx HDMI IP core used in the ZCU104-based example designs. You may use a full license or a free evaluation license, but the license must be installed prior to launching Vivado to build the project: https://www.amd.com/en/products/adaptive-socs-and-fpgas/intellectual-property/hdmi.html

Zybo-Z7-20 / Zybo-Z7-20-Lite / Arty-Z7-20

These projects require Vivado version 2024.2. Any edition of Vivado 2024.2 will work, including the "WebPACK" edition available via free download from Xilinx.

Board files from Digilent must be installed prior to launching Vivado in order to build the Zybo example designs. The board files may be obtained from github and installation instructions are available on the Digilent website.

Digilent periodically updates their board files repository which can lead to errors when opening projects caused by a discrepancy in the BoardPart property. For reference, the current version of Zybo and Arty example designs were built with commit hash 3f67d8f827bf83bb6a16b4879e4fdad68b8443e8. The ZCU104 example designs are built with board file revision 1.1 and should have been installed by Vivado 2022.1. This can be verified from the Vivado Tcl console with the command get_boards *zcu104*. Older or missing board files are a common source of failures to build Xilinx example designs.

Due to changes in Xilinx recommendations, these projects show critical warnings when loaded in recent versions of Vivado. These warnings may be ignored, as explained by the Digilent reference manual.

Kria KV260

These projects require Vivado version 2022.1. Any edition of Vivado 2022.1 will work, including the "WebPACK" edition available via free download from Xilinx.

The Kria KV260 example design deviates significantly from others supplied with the NDI Advanced SDK. See the README file in the src/fpga/KV260-Enc directory for details on how to create designs targeting this platform.

Altera

The NDI IP cores are available in two versions for Altera. Other than the encryption method used, these two versions are identical.

Designs using newer versions of Quartus (currently the Arria-10 and Agilex-7 examples) should use the *_Altera_1735.vhd files which are encrypted using IEEE 1735 and support development with Quartus as well as simulation with Synopsis and Mentor products.

For legacy Quartus versions which require a license file, the *_Altera.vhd files should be used and the contents of the file NDI_Enc/Encode_Altera.lic (for Encode) and NDI_Dec/Decode_Altera.lic (for Decode) must be appended to your Quartus license file. If you do not have a license file, you must create one.

Agilex-7 projects require Quartus Pro 25.1.1.

Arria-10 projects require Quartus Pro 22.2.0.

Cyclone-V projects require Quartus 22.1. The examples were compiled using the free "Lite" version, however the "Standard" edition should work as well.

Follow the Altera instructions for installation, including the required manual installation of WSL if you are using Windows.

If you plan to rebuild the NIOS code which reconfigures the GXB transceivers and PLLs, you need to manually install Eclipse per the Altera Quartus installation instructions. These instructions can also typically be found in the file: <Quartus installation directory>/nios2eds/bin/README

Rebuilding

Xilinx

All required dependencies (see above) MUST be installed prior to launching Vivado. Once you have all required dependencies installed, simply open the desired project and build normally. The contents for the block design elements (hard processor system, PLLs, etc) will be regenerated on the first build.

Altera

Agilex-7 Projects

To rebuild the Agilex-7 projects, simply open the project and Start Compilation. When opening the project for the first time, you will see the following warning:

Warning(125092): Tcl Script file support_logic/agx_hdmi21_frl_demo_auto_tiles.qip not found.

This warning can be safely ignored as the missing file is created during the Support-Logic Generation step of the build process.

After the build is finished, the rbf and jic files must be created. See the mk.jic.sh file in the quartus/output_files directory of the corresponding project for example commands, which must be run from a NIOS V command shell.

Other Altera Projects

For other Altera projects, you must generate the hps platform logic from the qsys file as described below.

Rebuild the hps platform

• Launch Platform Designer

• Open ndi_hps.qsys

• Click "Generate HDL..."

• Select VHDL Synthesis output (optional)

• Click "Generate"

• Once the qsys project has been generated, run a normal Quartus compilation

Known Issues and Limitations:

The video I/O logic (eg: HDMI to SDRAM and SDRAM to HDMI) is intended as an easy to understand minimally functional example and is not recommended for use in production. In particular, the input logic does not gracefully handle corrupt video data, unexpected cable removal, and similar signal quality issues.

It is expected the user of this SDK will have their own custom video I/O logic specific to their target hardware. If this is not the case and a production capable video I/O solution is desired, there are numerous IP cores available from Xilinx, Altera, and 3rd parties capable of supporting all major video interfaces (SDI, HDMI, Display Port, CSI/DSI, etc.).

NDI IP Files and Use

IP Core Configuration

The NDI encoder and decoder cores expose three generics that allow users to enable or disable some features at compile time. This can reduce the amount of hardware resources for each instantiated core. In particular, disabling 16-bit formats by setting FORMAT_16B => false will significantly reduce the block RAM utilization of the raw video buffers.

PLANAR_ALPHA : boolean : Enables support for a separate planar alpha channel

PLANAR_VIDEO : boolean : Enables support for semi-planar video formats (NV16, P216, NV12, P016)

FORMAT_16B : boolean : Enables support for 16-bit formats (UYVW, Y216, P216, 420W, P016)

NDI Encoder

Two VHDL files are required to use the NDI Encoder. Both files should be compiled into the NDI_Enc library in the following order:

• Xilinx Projects:

  `Encode_Xilinx.vhdp`
  `Encode_x4.vhd`

• Legacy Altera Projects:

  `Encode_Altera.vhd`
  `Encode_x4.vhd`

• Recent Altera Projects:

  `Encode_Altera_1735.vhd`
  `Encode_x4.vhd`

There is also a component declaration file Enc_Core_Comp.vhd for use as a reference when instantiating the encoder core. Each encoder core Enc_Core_E includes a register I/O interface, a read-only bus master interface for reading raw video data, and a write-only bus master interface for writing compressed NDI data. Note the raw video memory and the compressed NDI memory do not need to be the same physical bank of memory. Using two memory banks can improve system performance, particularly on lower-end devices such as the Zynq 7000 and Cyclone-V families.

NDI Decoder

NDI Decoder

Two VHDL files are required to use the NDI Decoder. Both files should be compiled into the NDI_Dec library in the following order:

• Xilinx Projects:

  `Decode_Xilinx.vhdp`
  `Decode_x4.vhd`

• Legacy Altera Projects:

  `Decode_Altera.vhd`
  `Decode_x4.vhd`

• Recent Altera Projects:

  `Decode_Altera_1735.vhd`
  `Decode_x4.vhd`

There is also a component declaration file Dec_Core_Comp.vhd for use as a reference when instantiating the encoder core. Each decoder core Dec_Core_E includes a register I/O interface, a read-only bus master interface for reading compressed NDI data, and a write-only bus master interface for writing raw video data. Note the raw video memory and the compressed NDI memory do not need to be the same physical bank of memory. Using two memory banks can improve system performance, particularly on lower-end devices such as the Zynq 7000 and Cyclone-V families.

SDRAM Bus Interfaces

The bus-mastering memory interfaces are natively a sub-set of the Altera Avalon interface specification. These buses may be tied directly to an Avalon interface port in an Altera design. For Xilinx designs, clear-text bus shim logic is provided to convert the Avalon bus subset used by the Encoder core into a more standard AXI interface:

File	Function
Avl_Axi_Rd.vhd	Translates Avalon read bus to AXI read bus
Avl_Axi_Wr.vhd	Translates Avalon write bus to AXI write bus
Avl2_Axi_rd.vhd	Merges 2 Avalon read buses into one AXI read bus
AXI_Reg_Wr.vhd	Interface AXI write bus to simple register write bus
AXI_Reg_Rd.vhd	Interface AXI read bus to simple register read bus

Usage examples for these files can be found in the top-level files for the example designs.

NDI Encode

Writes (compressed NDI data)

There is clear-text logic in the Encode_x4 file which merges the four lower bandwidth compressed write streams into a single write stream. The raw (uncompressed) audio data is also merged into this stream.

This write bus is connected to a cache coherent port to the hard processor system, eliminating the need for a kernel mode DMA driver.

Reads (raw video data)

For maximum performance, the four read streams are all brought out to the top level to provide maximum flexibility in scheduling SDRAM transactions. The NDI Encoder cores will tolerate fairly high latency on raw video reads, but require sufficient overall bandwidth to avoid stalling the NDI cores. Each of the NDI cores can process one pixel element (Y or C) per clock.

NDI Decode

Reads (compressed NDI data)

There is clear-text logic in the Decode_x4 file which merges the four lower bandwidth compressed Read streams into a single AXI read stream.

This read bus is connected to a cache coherent port to the hard processor system, eliminating the need for a kernel mode DMA driver.

Writes (raw video data)

For maximum performance, the four write streams are all brought out to the top level to provide maximum flexibility in scheduling SDRAM transactions. The NDI Decoder cores will tolerate fairly high latency on raw video writess, but require sufficient overall bandwidth to avoid stalling the NDI cores. Each of the NDI cores can process one pixel element (Y or C) per clock. For maximum performance, the four write streams are all brought out to the top level.

Full vs. Lite Encode Designs

The Zybo-Z7-20-Lite and Arty-Z7-20 example designs are intended as a reference for a more limited platform. Only one SDRAM chip is used (16-bit SDRAM interface) and only two encoder cores are instantiated. This implementation is still capable of operation at resolutions up to 1080p60.

All other example designs instantiate a "full" implementation which includes four NDI Encode or Decode cores providing maximum performance and minimum latency.

HDMI Input Logic

Agilex-7 SoC DevKit

The Agilex7-Enc design targeting the DK-SI-AGI027FA Agilex-7 SoC Development Kit uses a modified version of the Altera HDMI FPGA IP Design Example. An HPS configuration based on the GHRD example and the NDI logic are added to the top-level HDMI example design file (agx_hdmi21_frl_demo.v). Due to the extensive and complex constraints required for the HDMI example design, the top level design file and all HDMI related entity names are unchanged, the rx_vid and rx_audio buses are simply routed to the NDI subsystem as well as the existing rxtx_link module from the HDMI example design.

Arria-10 SoC DevKit

The a10-socdk-enc design targeting the Arria-10 SoC Development Kit uses a slightly modified version of the Altera Arria10 HDMI Rx-Tx Retransmit HDMI example design. The top-level of this example design is modified to export the recevied HDMI video, audio, and AVI data to the top-level where they are connected to the video and audio input logic.

Rebuilding the NIOS HDMI software

• Insure you have manually installed Eclipse per the Altera documentation

• In Quartus, select Tools -> Nios II Software Build Tools for Eclipse

• Use <NDI SDK Path>/ndi-fpga-refernce/a10-socdk-enc/software as the Workspace directory

• Create a new project and BSP in Eclipse

  • File -> New -> Nios II Application and BSP from Template

  • SOPC Information File name: <NDI SDK Path>/ndi-fpga-reference/a10-socdk-enc/rtl/nios/nios.sopcinfo

  • Project Name: tx_control

  • Project location: <NDI SDK Path>/ndi-fpga-refernce/a10-socdk-enc/software/tx_control

    • NOTE: Remove rtl from the default path

  • Project Template: Blank Project

  • Click: Finish

• Modify BSP settings

  • Right-click tx_control_bsp

  • Nios II -> BSP Editor...

  • In the Main tab, under Settings -> Common

    • Check: enable_small_c_library

    • Check: enable_reduced_device_drivers

    • File -> Save

    • Click: Generate BSP

  • Close BSP Editor

• Using a file browser, navigate to <NDI SDK Path>/ndi-fpga-refernce/a10-socdk-enc/software/tx_control_src

• Select all files, right-click, and select: Copy

• In Eclipse, right-click tx_control and select: Paste

• Build: Project -> Build All (or press ctrl+B)

• Update MIF file used to build FPGA

  • Right-click tx_control -> Make Targets -> Build

  • Select mem_init_generate

  • Click: Build

Zynq 7000 HDMI Input

The Zynq-7000 based designs (i.e., the Arty and Zybo Z7 boards) use RTL based on two open-source projects to process serial HDMI data into the parallel video required by the NDI encoder. Low-level, serial-to-parallel data conversion and lane alignment are performed by RTL from the Digilent DVI2RGB core. The aligned 10-bit characters are then processed as HDMI packets and subpackets by RTL from the Hamsterworks HDMI core. Additional RTL is also provided which merges these two cores together and produces the required video and audio data formats for the NDI encoder. For additional details, see the src/fpga/ip/extern/README.md file.

ZCU104 HDMI Input

The ZCU104 board uses the Xilinx HDMI 2.0 IP core. A full or evaluation license must be installed for this core prior to building the design with Vivado. This IP core also requires control software to monitor the incoming HDMI signal and make any adjustments required. This software is currently running "bare-metal" on one of the Cortex-R5 cores.

Rebuilding the Cortex-R5 HDMI Software (RX)

• If you have made any changes to the FPGA project:

  • Compile the ZCU104 FPGA design

  • Export the hardware to the SDK

    • Select File -> Export -> Export Hardware...

    • Select <Include bitstream> and click Next

    • Adjust path/filename if desired and click Finish

• Launch Vitis Classic IDE

  • This will raise a deprecation warning which can be neglected. The Vitis Unified IDE is not currently recommended.

  • Set the workspace directory as desired

• Create a new platform project File -> New -> Platform Project

  • Set platform project name to ZCU104-Enc

  • Click Next

  • Select Create new platform from hardware (XSA)

  • Click Browse

  • Select file ZCU104-Enc.xsa that was exported from Vivado

  • Click Next

  • Set operating system to standalone

  • Set CPU to psu_cortexr5_0

  • Uncheck Generate boot components

  • Click Finish

  • Wait for the platform project to be created

• Modify the board support package settings

  • Select Board Support Package in the platform editor window

  • Click Modify BSP Settings

  • Switch the console to UART1

    • Set the value for stdin to psu_uart_1

    • Set the value for stdout to psu_uart_1

  • Wait for the BSP regeneration to finish, which can take a while

• Import the HDMI RX example project

  • Select Board Support Package

  • Select the Drivers tab

  • Select the v_hdmi_rx_ss driver

  • Click Import Examples

  • Select RxOnly_R5

  • Click OK

  • Expand RxOnly_R5_1_system -> RxOnly_R5_1 -> src (all filenames are relative to this path)

• Update the DDR memory region in the linker script

  • Open the file src/lscript.ld

  • Set the psu_r5_ddr_0_MEM_0 region details to match the rproc_0_reserved reserved memory region in the device-tree and save the file Base Address : 0x3ed00000 Size : 0x80000

• Change HDMI code to use UART1

  • Open src/xhdmi_example.h

  • At line 86, change #define UART_BASEADDR XPAR_XUARTPS_0_BASEADDR to #define UART_BASEADDR XPAR_XUARTPS_1_BASEADDR to use UART1

  • Save the source file

• Update EDID data (optional)

  • Open src/xhdmi_edid.h

  • Edit constant Edid[] as desired

  • NOTE: EDID contents used for the example are in the file EDID.NDI.1080p60.dat

• Build the project Project -> Build Project

• Copy the ELF file to the ZCU104

  • The ELF file can be found at the following path

  • <workspace>/RxOnly_R5_1/Debug/RxOnly_R5_1.elf

  • Copy this file to /lib/firmware/ on the ZCU104

  • Rename the file as desired

  • Make sure you reference this filename when launching the R5 via remoteproc!

HDMI Output Logic

Arria-10 SoC DevKit

The a10-socdk-dec design targeting the Arria-10 SoC Development Kit uses a modified version of the Altera Arria10 HDMI Rx-Tx Retransmit HDMI example design. All Rx logic and the RxTx loopback logic is removed and the HDMI Tx fpll and iopll blocks use the REFCLK_SDI signal as a clock reference instead of the HDMI Rx clock. The tx_control NIOS code has been updated to reconfigure the output divisor for the fpll and iopll instance to switch between video modes.

Rebuilding the NIOS HDMI software

• Insure you have manually installed Eclipse per the Altera documentation

• In Quartus, select Tools -> Nios II Software Build Tools for Eclipse

• Use <NDI SDK Path>/ndi-fpga-refernce/a10-socdk-dec/software as the Workspace directory

• Create a new project and BSP in Eclipse

  • File -> New -> Nios II Application and BSP from Template

  • SOPC Information File name: <NDI SDK Path>/ndi-fpga-reference/a10-socdk-dec/rtl/nios/nios.sopcinfo

  • Project Name: tx_control

  • Project location: <NDI SDK Path>/ndi-fpga-refernce/a10-socdk-dec/software/tx_control

    • NOTE: Remove rtl from the default path

  • Project Template: Blank Project

  • Click: Finish

• Modify BSP settings

  • Right-click tx_control_bsp

  • Nios II -> BSP Editor...

  • In the Main tab, under Settings -> Common

    • Check: enable_small_c_library

    • Check: enable_reduced_device_drivers

    • File -> Save

    • Click: Generate BSP

  • Close BSP Editor

• Using a file browser, navigate to <NDI SDK Path>/ndi-fpga-refernce/a10-socdk-dec/software/tx_control_src

• Select all files, right-click, and select: Copy

• In Eclipse, right-click tx_control and select: Paste

• Build: Project -> Build All (or press ctrl+B)

• Update MIF file used to build FPGA

  • Right-click tx_control -> Make Targets -> Build

  • Select mem_init_generate

  • Click: Build

Zybo-Z7-20 HDMI Output

The Zybo-Z7 board uses the DVI output logic from the "Hamsterworks" HDMI project (ip/extern/HDMI/src/dvid_output.vhd). This is a simple DVI output and no HDMI features (e.g., emedded audio) are currently supported. Both 74.25 MHz (720p) and 148.5 MHz (1080p60) pixel rates are supported.

ZCU104 HDMI Output

The ZCU104 board uses the Xilinx HDMI 2.0 IP core. A full or evaluation license must be installed for this core prior to building the design with Vivado. This IP core also requires control software to configure the HDMI IP core. This software is currently running "bare-metal" on one of the Cortex-R5 cores.

Rebuilding the Cortex-R5 HDMI Software (TX)

• If you have made any changes to the FPGA project:

  • Compile the ZCU104 FPGA design

  • Export the hardware to the SDK

    • Select File -> Export -> Export Hardware...

    • Select <Include bitstream> and click Next

    • Adjust path/filename if desired and click Finish

• Launch Vitis Classic IDE

  • This will raise a deprecation warning which can be neglected. The Vitis Unified IDE is not currently recommended.

  • Set the workspace directory as desired

• Create a new platform project File -> New -> Platform Project

  • Set platform project name to ZCU104-Dec

  • Click Next

  • Select Create new platform from hardware (XSA)

  • Click Browse

  • Select file ZCU104-Dec.xsa that was exported from Vivado

  • Click Next

  • Set operating system to standalone

  • Set CPU to psu_cortexr5_0

  • Uncheck Generate boot components

  • Click Finish

  • Wait for the platform project to be created

• Modify the board support package settings

  • Select Board Support Package in the platform editor window

  • Click Modify BSP Settings

  • Switch the console to UART1

    • Set the value for stdin to psu_uart_1

    • Set the value for stdout to psu_uart_1

  • Wait for the BSP regeneration to finish, which can take a while

• Import the HDMI TX example project

  • Select Board Support Package

  • Select the Drivers tab

  • Select the v_hdmi_tx_ss driver

  • Click Import Examples

  • Select TxOnly_R5

  • Click OK

  • Expand TxOnly_R5_1_system -> TxOnly_R5_1 -> src (all filenames are relative to this path)

• Update the DDR memory region in the linker script

  • Open the file src/lscript.ld

  • Set the psu_r5_ddr_0_MEM_0 region details to match the rproc_0_reserved reserved memory region in the device-tree and save the file Base Address : 0x3ed00000 Size : 0x80000

  • Save the linker script

• Change the source code to use UART1

  • Open the file src/xhdmi_example.h

  • At line 99, change #define UART_BASEADDR XPAR_XUARTPS_0_BASEADDR to #define UART_BASEADDR XPAR_XUARTPS_1_BASEADDR to use UART1

  • Save the source file

• Update the default video mode

  • Open the file src/xhdmi_example.c

  • Edit the default video resolution at line 2506 (optional)

  • Change the colorspace on line 2507 to XVIDC_CSF_YCRCB_420 for 4Kp60 and XVIDC_CSF_YCRCB_422 for other modes

  • Possible values are listed in the XVidC_VideoMode enum in the file <workspace>/ZCU104-Dec/psu_cortexr5_0/standalone_domain/bsp/psu_cortexr5_0/include/xvidc.h

• Fix some build errors due to a missing pattern generator in the hardware design:

  • Copy the tpg header files xv_tpg.h and xv_tpg_hw.h from the SDK install directory into the src directory

    • From: /tools/Xilinx/Vitis/2024.2/data/embeddedsw/XilinxProcessorIPLib/drivers/v_tpg_v8_6/src/*.h

    • To: workspace/TxOnly_R5_1/src

  • Edit xhdmi_example.c

    • Comment the contents of the XV_ConfigTpg function (lines 329-380)

    • Comment the contents of the ResetTpg function (lines 385-390)

    • Comment the assignment to Pattern (line 1360)

    • Comment the call to XV_ConfigTpg (line 1363)

    • Save the file

  • Edit xhdmi_menu.c

    • Comment the assignment to Pattern (line 1514)

    • Comment the call to XV_ConfigTpg (line 1517)

    • Save the file

• Build the project Project -> Build Project

• Copy the ELF to the ZCU104

  • The ELF file can be found at the following path

  • <workspace>/TxOnly_R5_1/Debug/TxOnly_R5_1.elf

  • Copy this file to /lib/firmware/ on the ZCU104

  • Rename the file as desired

  • Make sure you reference this filename when launching the R5 via remoteproc!

SoCKit-Dec

The SoCKit project should be considered deprecated as the development board is no longer available for purchase. This design will be removed from future versions of the NDI Advanced SDK.

The SoCKit-Dec design targeting the Cyclone-V SoCKit Development board video output implementation (DVI_TX.vhd) converts the YUV video data from the NDI decoder into RGB and drives both the on-board VGA output and the (optional) Terasic DVH-HSMC daughtercard via the HSMC connector.

This is a simple DVI output and no HDMI features (e.g., emedded audio) are currently supported. Both 74.25 MHz (720p) and 148.5 MHz (1080p60) pixel rates are supported.

MIPI CSI Input Logic

Xilinx Kria KV260

This project uses the Xilinx MIPI CSI-2 Rx subsystem as configured for the "Smart Camera Accelerated Application" from Xilinx. A tap is added to the video output of the MIPI CSI core allowing pixels to be sent to the NDI Encode logic.