Skip to content

Running the Tool

Jump to bottom
Julian Kemmerer edited this page Dec 1, 2024 · 140 revisions

Setup

image

The recommended way of getting started is to

  1. begin with the Verilog or VHDL 'blink an LED' example that comes with your development board.
    • You likely will not need to instantiate a PLL and can use a clock source provided by your board.
  2. Once that entire flow is confirmed working and you have your LED blinking in hardware, swap out the hand written HDL for PipelineC generated code.
    • PipelineC generates a single top level module. Try pipelinec examples/blink.c using blink.c.
    • The top level module name --top is set to top by default.

PipelineC is pure Python other than calls to the synthesis+simulation tools which need additional setup and configuration. It is possible to run PipelineC without specifying an FPGA part/synthesis tool, however there will be no automatic pipelining or timing feedback provided for you (i.e. only basic VHDL is generated). ghdl, yosys, and ghdl-yosys-plugin are required for --verilog and --verilator support. Currently only Linux based environments are supported, it is expected that the system has a C preprocessor cpp executable installed. Native Windows+Mac support requires work, the best option for Windows+Mac users at the moment is use PipelineC, synthesis, and simulation tools through either 1) Linux in a virtual machine or 2) Windows Subsystem for Linux (WSL).

  1. Install one or more synthesis tools:

    • Xilinx Vivado: Defaults to vivado executable in user path. Otherwise either set a XILINX_VIVADO environment variable (path like /Xilinx/Vivado/2019.2) or edit the VIVADO_DIR constant at the top of VIVADO.py
      • Test: pipelinec ./examples/tool_tests/vivado.c
    • Intel Quartus: Defaults to quartus_sh executable in user path. Otherwise Edit the QUARTUS_PATH constant at the top of QUARTUS.py
      • Test: pipelinec ./examples/tool_tests/quartus.c
    • Lattice Diamond: Defaults to diamondc executable in user path. Otherwise edit the DIAMOND_PATH and DIAMOND_TOOL constants at the top of DIAMOND.py
      • Test: pipelinec ./examples/tool_tests/diamond.c
    • ghdl + yosys + ghdl-yosys-plugin + nextpnr: The easiest install option is via the OSS CAD Suite. Extract the most recent nightly build archive and update the single constant OSS_CAD_SUITE_PATH at the top of OPEN_TOOLS.py. Otherwise defaults to executables in user path.
      • WARNING: Versions of tools installed using apt-get are likely too old to work.
        • Install and build latest versions of ghdl, yosys, and ghdl-yosys-plugin for --verilog and --verilator support. nextpnr is needed for autopipelining.
        • Older ghdl versions do not support the IEEE float library.
        • Yosys will fail to load the ghdl shared library if the ghdl-yosys-plugin is not installed.
      • Test: pipelinec ./examples/tool_tests/open_tools.c
    • Gowin EDA: Defaults to gw_sh executable in user path. Otherwise edit the GOWIN_PATH constant at the top of GOWIN.py
      • Test: pipelinec ./examples/tool_tests/gowin.c
    • Efinix Efinity: Defaults to efx_run.py executable in user path. Otherwise edit the EFINITY_PATH path at the top of EFINITY.py
      • Test: pipelinec ./examples/tool_tests/efinity.c
    • Cologne Chip Toolchain: Defaults to p_r executable in user path. Otherwise edit the CC_TOOLS_PATH path at the top of CC_TOOLS.py. In both cases it is expected that the most recent build of cc-toolchain directory has been extracted.
      • Test: pipelinec ./examples/tool_tests/cc_tools.c
    • PyRTL Models: Have the python3 packages pyrtl and its dependency pyparsing installed. Do not specify an FPGA PART pragma and these models will be used by default. Experimental for ~single MAIN function/pipeline designs only.
      • Test: pipelinec ./examples/tool_tests/pyrtl.c

  2. Optionally supply the --out_dir command line argument, otherwise a new pipelinec_output directory inside the current one is created for output files. Watch out for stale output directory files...

  3. If you plan to do simulation install one or more simulation tools:

    • Modelsim: Install Modelsim. Make sure the vsim executable is in your path or edit the MODELSIM_PATH constant defined at the top of MODELSIM.py. Use the --modelsim command line option.
    • Verilator or CXXRTL: The easiest install option is via the OSS CAD Suite. Extract the most recent nightly build archive and update the single constant OSS_CAD_SUITE_PATH at the top of OPEN_TOOLS.py. Otherwise defaults to executables in user path. Use --verilator or --cxxrtl command line options.
    • cocotb: See cocotb install instructions. Currently only ghdl is supported as the simulator. ghdl must be in the user path. Use: --cocotb --ghdl.

    Use --sim or --sim --comb for starting simulations. WARNING: The default tool for Lattice ECP5U parts is set to the GHDL+Yosys+NextPNR flow. See SYN.py to change.

See pipelinec -h for all command line options.

Generate VHDL

  1. Write PipelineC code. Examples can be uncommented and included from main.c.
  2. Run the tool. pipelinec your_file.c. Defaults to main.c if file not specified.
  3. If the tool is stopped before completion you can rerun the tool specifying the same --out_dir to try and pick up where you left off. This is good for large designs / long synthesis sweeps. But bad for other yet-to-be-resolved reasons:
    • Stopping the tool after code parsing completes means the code will not be parsed again - delete your_file.c.parsed from your output directory if code is modified after parsing.
    • Stopping the tool during synthesis creates a failing synthesis run log - delete that log file (synthesis tool specific) before trying again.
  4. The output of the tool is generated VHDL in the output directory (see vhdl_files.txt):
    • Xilinx Vivado: A read_vhdl.tcl script is also generated
    • Intel Quartus: A pipelinec_top.qip Quartus IP file is also generated.
    • Lattice Diamond: Refer to generated 'top' module project file in the output directory.
    • GHDL+Yosys+NextPNR: Refer to generated 'top' module build script .sh in the output directory.
    • Gowin EDA: Refer to generated 'top' module build .tcl script in the output directory.
    • Efinix Efinity: Refer to generated 'top' module build script .sh and project .xml in the output directory.
    • Cologne Chip Toolchain: Refer to generated 'top' module build script .sh in the output directory.
    • PyRTL Models: Refer to generated 'top' module build script .sh in the output directory.

Generate Bitstream

  1. Include the generated PipelineC VHDL files in your project.

    • Xilinx Vivado: Can be done with Vivado Tcl command line like so that removes all old PipelineC files and sources all the newly generated VHDL.

      remove_files /home/user/pipelinec_output/*;
source /home/user/pipelinec_output/read_vhdl.tcl;

    • Intel Quartus: Refer to generated pipelinec_top.qip Quartus IP file in the output directory.

    • Lattice Diamond: Refer to generated vhdl_files.txt and 'top' module project file in the output directory.

    • GHDL+Yosys+NextPNR: Refer to generated vhdl_files.txt and 'top' module build script .sh in the output directory.

    • Gowin EDA: Refer to generated vhdl_files.txt and 'top' module files in the output directory.

    • Efinix Efinity: Refer to generated vhdl_files.txt and 'top' module build script .sh and project .xml in the output directory.

    • Cologne Chip Toolchain: Refer to generated vhdl_files.txt and 'top' module build script .sh in the output directory.

    • PyRTL Models: Refer to generated vhdl_files.txt and 'top' module build script .sh in the output directory.

  2. Proceed with normal bitstream generation flow.

    • PipelineC does not provide clock generation modules or timing constraints for the user. I.e. manufacturer generated clocking modules create constraints, user should make minimal wrapper VHDL module instantiating clock generators and the final connection to board IOs. See the Xilinx Vivado + Arty Board example project. ...Maybe some day the synthesis tool will take PipelineC description as the top level directly...
Clone this wiki locally