Getting started with Xillinux for Cyclone V SoC (SoCKit)

5 Making modifications

5.1 Integration with custom logic

The Xillinux distribution is set up for easy integration with application logic. The front end for connecting data sources and sinks is the xillydemo.v or xillydemo.vhd file (depending on the preferred language). All other HDL files in the boot image kit can be ignored for the purpose of using the Xillybus IP core as a transport of data between the Linux host and the logic fabric.

Additional HDL files with custom logic designs may be added to the project handled in paragraph 3.4, and then rebuilt the same way it was done the first place. For a boot of the system with the updated logic, soc_system.rbf needs to be regenerated as described in paragraph 3.4 and written to the microSD card as described in paragraph 3.6. There is no need to repeat the other steps of the initial distribution deployment, so the development cycle for logic is fairly quick and simple.

When attaching the Xillybus IP core to custom application logic, it is warmly recommended to interact with the Xillybus IP core only through FIFOs, and not attempt to mimic a FIFO’s behavior with logic, at least not in the first stage.

An exception for this is when connecting memories or register arrays to Xillybus, in which case the method shown in the xillydemo module should be followed.

In the xillydemo module, FIFOs are used to loop back data arriving from the host back to it. Both of the FIFOs’ sides are connected to the Xillybus IP core, which makes the core function as its own data source and sink.

In a more useful scenario, only one of the FIFO’s ends is connected to the Xillybus IP core, and the other end to an application data source or sink.

The FIFOs used in the xillydemo module accept only one common clock for both sides, as both sides are driven Xillybus’ main clock. In a real-life application, it may be desirable to replace them with FIFOs having separate clocks for reading and writing, allowing data sources and sinks to be driven by a clock other than the bus clock. By doing this, the FIFOs serve not just as mediators, but also for proper clock domain crossing.

Note that the Xillybus IP core expects a plain FIFO interface, (as opposed to First Word Fall Through) for streams from the FPGA to host.

The following documents are related to integrating custom logic:

• The API for logic design: Xillybus FPGA designer’s guide

• Basic concepts with the Linux host: Getting started with Xillybus on a Linux host

• Programming applications: Xillybus host application programming guide for Linux

• Requesting a custom Xillybus IP core: The guide to defining a custom Xillybus IP core

5.2 Using other boards

Before attempting to run Xillinux on a board other than the SoCKit board, certain modifications may be necessary.

Among others, these involve replacing pins and clocks:

• The attributes of the clock PLL defined in xillybus.v must be set up to match the free-running clock that is connected to clk_bot1, if it’s not 50 MHz (and the SDC file updated accordingly).

• The VGA output needs to be matched to the intended board.

• The HPS’ multiplexed pins: The ARM core has I/O pins which are routed to physical pins on the chip with a fixed placement. The ARM core is configured in Qsys to assign specific roles to these pins (e.g. USB interface, Ethernet etc.), which must match what these pins are wired to on the board.

The latter issue is important, not only because crucial hardware functions may fail, but illegal physical signal conditions on the board may result in damage to the hardware (even though actual damage is very rare).

Inconsistencies in HPS pin assignments are rectified in three steps:

• Correcting these assignments in Qsys.

• Building the entire project (including FPGA part) and generating an updated boot loader based upon the new handoff files (it’s the SPL part of U-boot that sets up the relevant registers on the processor).

• Updating the DTS file to match the device assignments, and performing a compilation of this file, producing the DTB file to perform boot of the system with.

5.3 Custom build projects and preflow.tcl

If the sources of the demo bundle are adopted into another Quartus II project, the common practices for transferring information between QSF files apply. Extra care must be taken to handle a non-standard script, preflow.tcl, which resides in the demo bundle’s soc_system subdirectory.

The script’s main purpose is to rewire the toplevel module of the SoC infrastructure which was generated by Qsys, in order to bypass buggy AXI bus logic that implements interconnect. Without this rewiring, the data transport over the AXI bus may appear to work properly, but sporadic data corruptions are observed.

The script is executed automatically by Quartus II before compilation takes place. This is a result of the following line in xillydemo.qsf:

set_global_assignment -name PRE_FLOW_SCRIPT_FILE \
           quartus_sh:../soc_system/preflow.tcl

In order to make sure that a Xillybus-based FPGA design doesn’t accidentally use infrastructure that hasn’t been rewired, preflow.tcl also modifies the names of some top-level ports, making them incompatible with the original. The said ports are those named xillybus_0_conduit_*.

It’s easy to tell if the module has been modified by the script: The first line of the modified file, soc_system/soc_system/synthesis/soc_system.v contains

// soc_system.v (mangled by preflow.tcl)

if the file is indeed rewired.

To include the SoC infrastucture in a custom project, adopt the entire SoC module tree by copying the files from an already fully built demo bundle, and add the following line to the QSF file

set_global_assignment -name QIP_FILE path/to/soc_system.qip

5.4 Changes in the Qsys project

Due to the automatic modification of one of the Verilog files that is generated by Qsys, it’s not recommended to modify the Qsys project. There is no guarantee that a modified Qsys project will be fixed correctly by the script, in particular if the project’s topology is altered.

Changes to attributes of the elements are probably fine, e.g. modifying the processor’s pin multiplexing. Note however that if changes are made to the HPS processor’s attributes, they take effect through changes in C files that are included in the preloader, and not through the logic.