Documentation Portal / FrontPanel HDL / AXI HDL / Getting Started
FrontPanel HDL

Getting Started

Install the FrontPanel SDK, build the ready-made PerfTest example bitstream on the SDK flow, and load it onto your board to confirm that everything works. To wire okHost into your own design instead of the example, see Integrating okHost on the System Design page. PerfTest is our shared FrontPanel-AXI example design; what it contains, and the pattern modes it exercises, are documented on the PerfTest example page.

Before You Begin

Before working through this tutorial, you need:

  • A FrontPanel-AXI board (an AXI board, for example the SZG-HUB1450-AU10P; see the supported boards on the Overview).
  • AMD Vivado, a release within your board’s supported range. okHost’s synthesis sources are encrypted and build in Vivado only. See Vivado Version Compatibility.
  • The FrontPanel SDK. One download delivers everything okHost needs. It includes the encrypted synthesis sources, the simulation BFM, and the FrontPanel API host software that drives the board. Download and install it from our downloads page. The FrontPanel Vivado IP Core is an alternative delivery of the same okHost gateware; see Choosing Your Path below.
  • Assumed knowledge. AXI4, AXI4-Lite, and AXI4-Stream basics, and a basic Vivado RTL project flow. These pages document okHost, not AXI or Vivado themselves; for the protocol, see the Arm AMBA specifications.

Simulating instead of building hardware? You do not need a board or the synthesis sources. You need only the simulation BFM, which comes in the same SDK, and your simulator. The cocotb path has its own package and prerequisites. See Simulation.

Choosing Your Path

The FrontPanel SDK and the FrontPanel Vivado IP Core deliver the same okHost. The IP Core repackages the SDK’s encrypted sources as a generated Vivado IP. The okHost netlist is identical; only the workflow and file handling differ. cocotb is a third, simulation-only option in Python.

FlowWhat It IsBest WhenGetting Started
FrontPanel SDK (raw HDL)The encrypted okHost HDL you add yourself (Tcl, scripted), with the synthesis sources and the Verilog simulation BFMYou want full control, scripted, CLI, or CI builds, or you do not use IP IntegratorThe SDK path below
FrontPanel Vivado IP CoreThe same okHost packaged as a generated Vivado IP (GUI, IP catalog, Block Design), with the synthesis sources and the Verilog simulation BFMYou want the easiest add, guided configuration, or you work in IP Integrator or a Block DesignIP Core Getting Started
cocotb (Python sim)A simulation-only Python BFM (Icarus Verilog), with no synthesis sourcesYour verification is Python or pytest centric, or you want cross-platform or CI simulation without Vivadococotb page

This tutorial takes the FrontPanel SDK path. To follow the IP Core or cocotb path instead, use its guide linked in the table above.

Build the PerfTest Example (SDK Path)

This build works with any Vivado release in your board’s supported range.

You need three inputs:

  • AMD Vivado, any release in your board’s supported range.
  • The PerfTest sample: perftest_top.v, perftest_core.v, perftest_csr.v, perftest_logic/*.v, szg-hub1450.xdc, project.tcl, and README.txt.
  • The encrypted HDL release for your board: the BWMode<N>/ folders under the Vivado-<year> key-year that covers your Vivado release. The file roles and the folder layout are on Delivery and Files; the key-year rule is on Vivado Version Compatibility.

Run these steps from Vivado’s Tcl console: launch Vivado, open the Tcl console, and enter the commands there. This is the common flow. A scripted or CI build can instead run them in Batch Mode (vivado -mode batch) or the Tcl shell (vivado -mode tcl).

Step 1: Copy the sample to a writable directory. Work from a copy so the release tree stays clean.

Step 2: Select the key-year folder that covers your Vivado release. Under your board, choose the Vivado-<year>/ folder whose window includes the Vivado release you build with.

Step 3: Stage the encrypted sources. Copy the BWMode<N>/ folder you want, which holds okHost.vp, okHost.veo, and okHost.xdc, into ./FrontPanel/BWMode<N>/ next to the sample. This ./FrontPanel/BWMode<N>/ layout is where project.tcl looks.

Step 4: Create the project. Set the bandwidth mode and source the project script:

set mode <N>
source project.tclCode language: HTML, XML (xml)

Step 5: Synthesize.

launch_runs synth_1

Step 6: Implement and write the bitstream.

launch_runs impl_1 -to_step write_bitstream

The project.tcl script requires mode, checks for FrontPanel/BWMode$mode/, creates the project on the xcau10p-ffvb676-1-e part, adds the PerfTest sources and szg-hub1450.xdc, imports okHost.vp and okHost.xdc (setting the imported okHost.xdc to PROCESSING_ORDER LATE), and sets the generic MODE=$mode. The PROCESSING_ORDER LATE setting and the message suppressions it applies are SZG-HUB1450 specifics; they are documented under Board-Specific Build Notes on the okHost Core page, and you apply them yourself when you build your own project.

On a verified BWMode3 run, synthesis, implementation, and write_bitstream all complete with timing met and zero errors, producing perftest_top.bit (2.6 MB).

Common pitfalls:

  • project.tcl ends with start_gui. It is a no-op in the GUI Tcl console, but neutralize it for a Batch Mode, Tcl shell, or CI build.
  • The ./FrontPanel/BWMode<N>/ layout in Step 3 is the usual failure point. Confirm the folder name and contents before sourcing the script.
  • On older Vivado releases, the build prints harmless IDELAYCTRL SIM_DEVICE and ADEF-911 warnings. The optional suppressions in Board-Specific Build Notes quiet them.

Load & Verify

Configure the FPGA with your .bit and run PerfTest to confirm the design works end to end. PerfTest ships with both a C++ host application and a FrontPanel Platform app, and the PerfTest example page gives the steps to run each. If anything looks wrong, start with the board smoke test on the Troubleshooting & Debugging page.

See Also