Verilog-to-Routing Documentation Release 8.1.0-dev VTR Developers Sep 28, 2021 QUICK START 1 VTR Quick Start 3 1.1 Setting Up VTR.............................................3 1.2 Running VPR...............................................4 1.3 Running the VTR Flow.........................................8 1.4 Next Steps................................................ 15 2 Building VTR 17 2.1 Overview................................................. 17 2.2 Tested Compilers............................................. 17 2.3 Unix-like................................................. 17 2.4 Other platforms.............................................. 21 3 VTR 23 3.1 VTR CAD Flow............................................. 23 3.2 Get VTR................................................. 25 3.3 Install VTR................................................ 27 3.4 Running the VTR Flow......................................... 28 3.5 Benchmarks............................................... 29 3.6 Power Estimation............................................. 33 3.7 Tasks................................................... 45 3.8 run_vtr_flow............................................... 49 3.9 run_vtr_task............................................... 52 3.10 parse_vtr_flow.............................................. 54 3.11 parse_vtr_task.............................................. 55 3.12 Parse Configuration........................................... 56 3.13 Pass Requirements............................................ 57 3.14 VTR Flow Python library........................................ 58 4 FPGA Architecture Description 59 4.1 Architecture Reference.......................................... 59 4.2 Example Architecture Specification................................... 121 5 VPR 133 5.1 Basic flow................................................ 133 5.2 Command-line Options......................................... 135 5.3 Graphics................................................. 162 5.4 Timing Constraints............................................ 168 5.5 SDC Commands............................................. 169 5.6 File Formats............................................... 178 5.7 Debugging Aids............................................. 198 i 5.8 Placer and Router Debugger....................................... 199 6 Odin II 203 6.1 Quickstart................................................ 203 6.2 User guide................................................ 204 6.3 Verilog Support.............................................. 207 6.4 Contributing............................................... 208 6.5 Regression Tests............................................. 210 6.6 Verify Script............................................... 220 6.7 TESTING ODIN II............................................ 221 7 ABC 223 8 Tutorials 225 8.1 Design Flow Tutorials.......................................... 225 8.2 Architecture Modeling.......................................... 226 8.3 Running the Titan Benchmarks..................................... 281 8.4 Post-Implementation Timing Simulation................................ 283 9 Utilities 291 9.1 FPGA Assembly (FASM) Output Support................................ 291 9.2 Router Diagnosis Tool.......................................... 295 10 Developer Guide 297 10.1 Contribution Guidelines......................................... 297 10.2 Commit Procedures........................................... 300 10.3 Commit Messages and Structure..................................... 302 10.4 Code Formatting............................................. 303 10.5 Running Tests.............................................. 304 10.6 Debugging Failed Tests......................................... 308 10.7 Evaluating Quality of Result (QoR) Changes.............................. 309 10.8 Adding Tests............................................... 319 10.9 Debugging Aids............................................. 321 10.10 Speeding up the edit-compile-test cycle................................. 324 10.11 Speeding Compilation.......................................... 324 10.12 Profiling VTR.............................................. 325 10.13 External Subtrees............................................. 326 10.14 Finding Bugs with Coverity....................................... 327 10.15 Release Procedures............................................ 328 10.16 Sphinx API Documentation for C/C++ Projects............................. 329 10.17 Documenting VTR Code with Doxygen................................. 331 10.18 Developer Tutorials........................................... 335 10.19 VTR Support Resources......................................... 341 10.20 VTR License............................................... 342 11 VTR Change Log 343 11.1 Unreleased................................................ 343 11.2 v8.0.0 - 2020-03-24........................................... 343 11.3 v8.0.0-rc2 - 2019-08-01......................................... 345 11.4 v8.0.0-rc1 - 2019-06-13......................................... 346 12 Contact 349 12.1 Mailing Lists............................................... 349 12.2 Issue Tracker............................................... 349 ii 13 Glossary 351 14 Publications & References 353 15 VPR API 355 15.1 Contexts................................................. 355 15.2 Netlists.................................................. 359 15.3 Routing Resource Graph......................................... 377 16 VTRUTIL API 383 16.1 IDs - Ranges............................................... 383 16.2 Containers................................................ 389 16.3 Container Utils.............................................. 419 16.4 Logging - Errors - Assertions...................................... 422 16.5 Geometry................................................. 425 16.6 Other................................................... 429 17 Indices and tables 445 Bibliography 447 Index 451 iii iv Verilog-to-Routing Documentation, Release 8.1.0-dev Form more information on the Verilog-to-Routing (VTR) project see VTR and VTR CAD Flow. For documentation and tutorials on the FPGA architecture description langauge see: FPGA Architecture Description. For more specific documentation about VPR see VPR. QUICK START 1 Verilog-to-Routing Documentation, Release 8.1.0-dev 2 QUICK START CHAPTER ONE VTR QUICK START This is a quick introduction to VTR which covers how to run VTR and some if its associated tools (VPR, Odin II, ABC). 1.1 Setting Up VTR 1.1.1 Download VTR The first step is to download VTR and extract VTR on your local machine. Note: Developers planning to modify VTR should clone the VTR git repository. 1.1.2 Build VTR On most unix-like systems you can run: > make from the VTR root directory (hereafter referred to as $VTR_ROOT) to build VTR. Note: In the VTR documentation lines starting with > (like > make above), indicate a command (i.e. make) to run from your terminal. When the \ symbol appears at the end of a line, it indicates line continuation. Note: $VTR_ROOT refers to the root directory of the VTR project source tree. To run the examples in this guide on your machine, either: • define VTR_ROOT as a variable in your shell (e.g. if ~/trees/vtr is the path to the VTR source tree on your machine, run the equivalent of VTR_ROOT=~/trees/vtr in BASH) which will allow you to run the commands as written in this guide, or • manually replace $VTR_ROOT in the example commandss below with your path to the VTR source tree. Note: If VTR fails to build you may need to install the required dependencies. For more details on building VTR on various operating systems/platforms see Building VTR. 3 Verilog-to-Routing Documentation, Release 8.1.0-dev 1.2 Running VPR Lets now try taking a simple pre-synthesized circuit (consisting of LUTs and Flip-Flops) and use the VPR tool to implement it on a specific FPGA architecture. 1.2.1 Running VPR on a Pre-Synthesized Circuit First, lets make a directory in our home directory where we can work: #Move to our home directory > cd~ #Make a working directory > mkdir -p vtr_work/quickstart/vpr_tseng #Move into the working directory > cd ~/vtr_work/quickstart/vpr_tseng Now, lets invoke the VPR tool to implement: • the tseng circuit ($VTR_ROOT/vtr_flow/benchmarks/blif/tseng.blif), on • the EArch FPGA architecture ($VTR_ROOT/vtr_flow/arch/timing/EArch.xml). We do this by passing these files to the VPR tool, and also specifying that we want to route the circuit on a version of EArch with a routing architecture channel width of 100 (--route_chan_wdith 100): > $VTR_ROOT/vpr/vpr \ $VTR_ROOT/vtr_flow/arch/timing/EArch.xml \ $VTR_ROOT/vtr_flow/benchmarks/blif/tseng.blif \ --route_chan_width 100 This will produce a large amount of output as VPR implements the circuit, but you should see something similar to: VPR FPGA Placement and Routing. Version: 8.1.0-dev+2b5807ecf Revision: v8.0.0-1821-g2b5807ecf Compiled: 2020-05-21T16:39:33 Compiler: GNU 7.3.0 on Linux-4.15.0-20-generic x86_64 Build Info: release VTR_ASSERT_LEVEL=2 University of Toronto verilogtorouting.org [email protected] This is free open source code under MIT license. # #Lots of output trimmed for brevity.... # Geometric mean non-virtual intra-domain period: 6.22409 ns (160.666 MHz) Fanout-weighted geomean non-virtual intra-domain period: 6.22409 ns (160.666 MHz) VPR suceeded The entire flow of VPR took 3.37 seconds (max_rss 40.7 MiB) 4 Chapter 1. VTR Quick Start Verilog-to-Routing Documentation,