quicklogic

SymbiFlow for QuickLogic FPGAs

Currently, the supported families are:

• pp3 (EOS-S3 SoC)
• qlf_k4n8

Quickstart guide

1. Build F4PGA Architecture Definitions

Clone the repository:

git clone https://github.com/SymbiFlow/f4pga-arch-defs

Set up the environment:

make env

The command will automatically clone all GIT submodules, setup a Conda environment with all the necessary packages and generate the build system by invoking CMake.

2. Generate a bitstream for a sample design

Once the SymbiFlow environment is set up, you can perform the implementation (synthesis, placement and routing) of an example FPGA designs.

Go to the quicklogic/<family>/tests directory and choose a design you want to implement e.g:

cd quicklogic/pp3/tests/counter
make counter-ql-chandalar_bit

This will generate a binary bitstream file for the design. The resulting bitstream will be written to the top.bit file in the working directory of the design.

Currently supported basic designs in pp3 faimly are:

• btn_counter
• consts
• counter
• lut
• wire

For details of each of the test design please refer to its README.md file.

3. Programming the EOS S3 SoC

To simplify the programming process, some helper scripts were integrated with the flow. The scripts can automatically configure the IOMUX of the SoC so that all top-level IO ports of the design are routed to the physical pads of the chip.

In order to generate the JLink programming script, build the following target:

make counter-ql-chandalar_jlink

or to generate OpenOCD script:

make counter-ql-chandalar_openocd

The script will contain both the bitstream and IOMUX configuration.

Naming convention

The naming convention of all build targets is: <design_name>-<board_name>_<stage_name>

The <design_name> corresponds to the name of the design. The <board_name> defines the board that the design is targetted for, possible values are ql-chandalar and ql-quickfeather The last part <stage_name> defines the last stage of the flow that is to be executed.

The most important stages are:

• eblif Runs Yosys synthesis and generates an EBLIF file suitable for VPR. The output EBLIF file is named top.eblif

• pack Runs VPR packing stage. The packed design is written to the top.net file.

• place Runs VPR placement stage. Design placement is stored in the top.place file. IO placement constraints for VPR are written to the top_io.place file.

• route Runs VPR pack, place and route flow. The packed design is written to the top.net file. design placement and routing data is stored in the top.place and top.route files respectively. IO placement constraints for VPR are written to the top_io.place file.

• analysis Runs VPR analysis, writes post-route netlists in BLIF and Verilog format plus an SDF file with post routing timing analysis.

• fasm Generates the FPGA assembly file (a.k.a. FASM) using the routed design. The FASM file is named top.fasm.

• bit Generates a binary bitstream file from the FASM file using the qlfasm.py tool. The bitstream is ready to be loaded to the FPGA.

• jlink For convenience of programming the EOS S3 SoC, the jlink stage generates a command script which configures the IOMUX of the SoC and loads the bitstream to the FPGA. The script is ready to be executed via the JLink commander tool.

• openocd The openocd stage generates an OpenOCD script with load_bitstream process which configures the IOMUX of the SoC and loads the bitstream to the FPGA. The script is ready to be executed via the GDB tool. To do so, connect to target with OpenOCD, append the generated script to command set: -f top.openocd and execute in GDB session monitor load_bitstream.

• bit_v Runs the fasm2bels tool on the bitstream generated by the bit target. The fasm2bels tool converts a bitstream or a FASM file to a Verilog file containing basic elements (BELs) and connections between them. The resulting file is named top_bit.v

Executing a particular stage implies that all stages before it will be executed as well (if needed). They form a dependency chain.

Note: stages jlink, openocd, bit_v are available only for the pp3 family.

Adding new designs to SymbiFlow

To to add a new design to the flow, and use it as a test follow the guide:

1. Create a subfolder for your design under the quicklogic/<family>/tests folder.

2. Add inclusion of the folder in the quicklogic/<family>/tests/CMakeLists.txt by adding the following line to it:

   add_subdirectory(<your_directory_name>)
   

3. Add a CMakeLists.txt file to your design. Specify your design settings inside it:

   add_fpga_target(
     NAME            <your_design_name>
     BOARD           <target_board_name>
     SOURCES         <verilog sources list>
     INPUT_IO_FILE   <PCF file with IO constraints>
     SDC_FILE        <SDC file with timing constraints>
     )
   

   The design name can be anything. For available board names please refer to the quicklogic/<family>/boards.cmake file. Input IO constraints have to be given in the PCF format. The SDC file argument is optional. Please also refer to CMake files for existing designs. All the files passed to add_fpga_target have to be added to the flow with add_file_target e.g:

   add_file_target(FILE counter.v SCANNER_TYPE verilog)
   add_file_target(FILE chandalar.pcf)
   

   The verilog scanner will automatically add all the verilog dependecies explicitely included in the added file.

4. Once this is done go back to the SymbiFlow root directory and re-run the make env command to update build targets:

   make env

5. Now enter the build directory of your project and run the appropriate target as described:

   cd build/quicklogic/<family>/tests/<your_directory_name>
   make <your_design_name>-<target_board_name>_bit