Running the Tool

Setup

See Dev Board Setup for an intro to using PipelineC for the first time.

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 / without installing a synthesis tool, however there will be no automatic pipelining or timing feedback provided for you (i.e. only basic VHDL is generated in this --comb --no_synth mode).

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.

   • The output directory structure is subject to change but currently looks like:
     • <your_file>.parsed: Ex. main.c.parsed would be a cached already-parsed version of main.c file.
     • vhdl_files.txt is a plain text list of the VHDL files the tool intends for you to use.
       • As mentioned below, individual synthesis tools also have some specific output files generated just for them.
     • built_in/: this directory has the VHDL files for all basic built-into-C features (ex. simple operators, muxes)
     • top/: this directory is named based on the --top command line argument. By default top/top.vhd is the final output top level file produced by PipelineC.
     • Other directories are based on the file path to where code lives:
       • Ex. code generated from parsing examples/arty/top.c is put in an output directory called examples/arty/top.c/
   • Be aware of some things regarding generated output files:
     • There can be stale output directory files, recommend starting from a fresh output directory if any odd behavior is encountered.
       • Stopping the tool after code parsing completes means the code will not be parsed again - delete <your_file>.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.
     • Pipelining iterations produce many VHDL files, some simple setups like those for sim mistakenly include all VHDL files found in the output directory as opposed to just those listed in vhdl_files.txt.

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.
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 Dev Board Setup for more information.

...Maybe someday synthesis tools will take PipelineC description as the top level directly...