Running the Tool

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. GHDL+Yosys+nextpnr are required for --verilog and --verilator support. 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
     • 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+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 place+route|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
   • 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
   • 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.
   • 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.
   • 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 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.

   • 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...