Skip to content

Running the Tool

Jump to bottom
Julian Kemmerer edited this page May 31, 2022 · 138 revisions

Setup

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). Currently only Linux based environments are supported (native Windows+Mac support requires work), the best option for Windows users at the moment is to use PipelineC, synthesis, and simulation tools through Windows Subsystem for Linux (WSL).

  1. Install one or more synthesis tools to enable automatic pipelining and timing closure feedback. Configure:

    • 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
    • Intel Quartus: Defaults to quartus_sh executable in user path. Otherwise Edit the QUARTUS_PATH constant at the top of QUARTUS.py
    • Lattice Diamond: Defaults to diamondc executable in user path. Otherwise edit the DIAMOND_PATH and DIAMOND_TOOL constants at the top of DIAMOND.py
    • GHDL+Yosys+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.
    • Efinix Efinity: Defaults to efx_run.py executable in user path. Otherwise edit the EFINITY_PATH path at the top of EFINITY.py
    • 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 --coarse ~single MAIN function/pipeline designs only.

  2. Optionally supply the --out_dir command line argument, otherwise a new pipelinec_output directory inside the current one is created for output 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.

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

See ./src/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. ./src/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.
    • Xilinx Vivado: A read_vhdl.tcl script is also generated
    • Intel Quartus: Refer to generated 'top' module project file, shell and tcl scripts in the output directory. (More info: TODO)
    • 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.
    • Efinix Efinity: Refer to generated 'top' module build script .sh and project .xml 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 vhdl_files.txt and 'top' module project files 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.
    • Efinix Efinity: Refer to generated vhdl_files.txt and 'top' module build script .sh and project .xml 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