.. _vpr_graphics: Graphics ======== VPR includes easy-to-use graphics for visualizing both the targeted FPGA architecture, and the circuit VPR has implemented on the architecture. .. image:: https://www.verilogtorouting.org/img/des90_routing_util.gif :align: center Enabling Graphics ----------------- Compiling with Graphics Support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ VPR's graphics are built on `Qt6 `_. A plain ``make`` builds the GUI **only if a suitable Qt6 (>= 6.9.3) is found**; otherwise VPR is built headless. The 6.9.3 floor exists because earlier Qt6 releases have QRhi (Render Hardware Interface, GPU accelerated) rendering bugs. The Qt6 GUI links against your system's OpenGL / EGL / xkbcommon runtime libraries. On Debian/Ubuntu these prerequisites are installed for you by ``./install_apt_packages.sh``, or manually with:: > sudo apt-get install libxkbcommon-dev libgl-dev libegl-dev libopengl0 libegl-mesa0 libgl1-mesa-dri With those in place, install Qt6 itself. On the currently supported distributions (e.g. Ubuntu 24.04) the system Qt6 is too old (24.04 ships Qt 6.4.2), so the recommended way to get a suitable Qt6 is the repo-local SDK installed by ``ensure_qt6_sdk.sh`` (no root required):: > ./dev/ensure_qt6_sdk.sh During configuration the build reports whether graphics were enabled. If a suitable Qt6 is found:: -- VPR Graphics: Enabled (Qt6 6.9.3 found) Otherwise (and VPR is built without graphics):: -- VPR Graphics: Disabled (no Qt6 >= 6.9.3; run ./dev/ensure_qt6_sdk.sh or install a system Qt6 if its version >= 6.9.3) .. note:: On future distributions that ship Qt6 >= 6.9.3 (Ubuntu 26.04 onward) you can instead install Qt6 system-wide and skip ``ensure_qt6_sdk.sh`` entirely — at which point the script becomes obsolete. The GUI needs the base, private (QRhi/QShader headers), SVG, and shader-tools (the ``qsb`` shader baker) packages:: > sudo apt-get install qt6-base-dev qt6-base-private-dev qt6-svg-dev qt6-shadertools-dev Two convenience targets make the choice explicit:: > make ensure-gui # build vpr WITH the GUI (runs ensure_qt6_sdk.sh first) > make ensure-headless # build vpr WITHOUT the GUI .. seealso:: :doc:`Building VTR ` for the full build instructions. Enabling Graphics at Run-time ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When running VPR provide :option:`vpr --disp` ``on`` to enable graphics. Saving Graphics at Run-time ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When running VPR provide :option:`vpr --save_graphics` ``on`` to save an image of the final placement and the final routing created by vpr to pdf files on disk. The files are named vpr_placement.pdf and vpr_routing.pdf. A graphical window will now pop up when you run VPR. Navigation ---------- * Click on the **Zoom Fit** button to get an over-encompassing view of the FPGA architecture. * Click and drag with the left mouse button to pan the view, or scroll the mouse wheel to zoom in and out. * Click on the **Zoom Select** button, then on the diagonally opposite corners of a box, to zoom in on a particular area. * Click on **Save** under the **Misc.** tab to save the image on screen to PDF, PNG, or SVG file. * **Next Step** tells VPR to continue with the next step in placing and routing the circuit. .. note:: Menu buttons will be greyed out when they are not selectable (e.g. VPR is working). Placement -------------------------------- By default VPR's graphics displays the FPGA floorplan (block grid) and current placement during global (analytical) placement and detailed (SA) placement. The FPGA floorplan during global placement does not preserve inter-block spacing and is therefore easy to distinguish. .. figure:: ../Images/analytical_place.png :align: center :width: 75% FPGA floorplan (block grid) during analytical placement .. figure:: ../Images/detailed_place.png :align: center :width: 75% FPGA floorplan (block grid) during detailed placement If the **Placement Macros** drop down is set, any placement macros (e.g. carry chains, which require specific relative placements between some blocks) will be highlighted. .. figure:: https://www.verilogtorouting.org/img/neuron_placement_macros.gif :align: center :width: 50% Placement with macros (carry chains) highlighted Nets ---------------- To visualize nets, first enable the **Display Nets** switch under the **Net** Tab. The user can choose between drawing nets as **Flylines** (direct connections between sources and sinks) or as **Routing** (the actual routed path of the net). Only the **Flylines** option is available during placement, as routing has not yet been performed. The Inter-Cluster Nets and Intra-Cluster Nets options allow the user to choose whether to visualize nets between clbs or within a clb, respectively. The Intra-Cluster Routed Nets option is currently only available when **flat routing is enabled**. .. figure:: ../Images/Net_Settings.png :align: center :width: 25% Net Tab If routing is shown, clicking on a pin or channel wire will highlight the whole net in magenta. Multiple nets can be highlighted by pressing ctrl + mouse click. .. figure:: ../Images/show_nets.gif :align: center :width: 100% Visualizing Nets When the **Highlight Block Fan-in and Fan-out** option is enabled, clicking on an internal block will draw its fan-in, fan-out, and internal flylines in blue, red, and yellow, respectively. .. figure:: ../Images/highlight_flylines.png :align: center :width: 50% Highlight Block Fan-in and Fan-out Flylines Clicking on a clb (not the internal physical blocks) will also highlight all the fan-in and fan-out routed nets in blue and red, respectively. Critical Paths ----------------------------- During placement and routing you can click on the **Display Critical Paths** switch under the **Net** tab to visualize the critical paths. The user can choose the number of critical paths to visualize (between 1 to 10) using the **Num Critical Paths** spinbox. If the requested number exceeds what are currently available, only the available paths are visualized. Each stage between primitive pins is shown in a different colour. .. figure:: ../Images/crit_paths.png :align: center :width: 75% Critical Path with all options enabled. * During placement the critical path is shown only as flylines. * During routing the critical path can be shown as both flylines and routed net connections. .. figure:: https://www.verilogtorouting.org/img/des90_cpd.gif :align: center :width: 50% Critical Path flylines during placement and routing Routing Architecture -------------------------------- During the route stage, the **Route** tab provides various options to visualize router resources and statistics. .. figure:: ../Images/Routing_Options.png :align: center :width: 25% Routing Options To visualize routing architecture, first enable the **Display Routing Resources** switch under the Route tab. Then, click on the checkboxes below to show/hide the types of nodes and edges you want to visualize. The intra-cluster options are currently only available when **flat routing is enabled**. The **Highlight Fan-In Fan-Out Edges** option will highlight the fan-in and fan-out edges of the selected routing resource in blue and red, respectively. Multiple routing resources can be highlighted by pressing ctrl + mouse click. .. figure:: ../Images/show_rr_graph.gif :align: center :width: 100% Visualizing Routing Architecture **Node Colors**: +------------+--------+ | Node Type | Color | +============+========+ | Channel | Black | +------------+--------+ | Input Pin | Purple | +------------+--------+ | Output Pin | Pink | +------------+--------+ **Edge Colors**: +-----------------------+---------------+ | Edge Type | Color | +=======================+===============+ | Pin to Output Pin | Light Pink | +-----------------------+---------------+ | Pin to Input Pin | Medium Purple | +-----------------------+---------------+ | Output Pin to Channel | Pink | +-----------------------+---------------+ | Channel to Input Pin | Purple | +-----------------------+---------------+ | Channel to Channel | Dark Green | +-----------------------+---------------+ | Non-Configurable Edge | Dark Grey | +-----------------------+---------------+ The points at which wiring segments connect to clb pins (connection box switches) are marked with an ``x``. Switch box connections will have buffers (triangles) or pass transistors (circles) drawn on top of them, depending on the type of switch each connection uses. Routing Congestion ------------------------------ When a routing is shown on-screen, clicking on the **Congestion** drop-down menu under the **Routing Options** tab will show a heat map of any overused routing resources (wires or pins). Lighter colours (e.g. yellow) correspond to highly overused resources, while darker colours (e.g. blue) correspond to lower overuse. The overuse range shown at the bottom of the window. .. figure:: https://www.verilogtorouting.org/img/bitcoin_congestion.gif :align: center :width: 50% Routing Congestion during placement and routing Routing Utilization ------------------------------- When a routing is shown on-screen, clicking on the **Routing Util** drop-down menu will show a heat map of routing wire utilization (i.e. fraction of wires used in each channel). Lighter colours (e.g. yellow) correspond to highly utilized channels, while darker colours (e.g. blue) correspond to lower utilization. .. figure:: https://www.verilogtorouting.org/img/bitcoin_routing_util.gif :align: center :width: 50% Routing Utilization during placement and routing Block Internals ------------------------------- During placement and routing you can adjust the level of block detail you visualize by using the **Block Internal** option under the **Block** tab. .. figure:: ../Images/Block_Settings.png :align: center :width: 100% Block Settings Each block can contain a number of flip flops (ff), look up tables (lut), and other primitives. The higher the number, the deeper into the hierarchy within the cluster level block you see. The format of the internal block names is []:. Layers Dropdown ----------------------------- .. figure:: ../Images/view_menu.png :align: center :width: 50% Items under the layers dropdown The layers dropdown is displayed when vpr is targeting a stacked multi-die architecture (more than 1 layer). Layers are drawn in ascending order for many drawing features (e.g. blocks); that is layer 0 is drawn first, and (if visible), layer 1 is drawn on top of it etc. The visibility and transparency of a layer can be changed, which will affect blocks, nets, routing, and critical path. Cross-layer connections refer to connections that are in different layers. Misc. Display Controls ---------------------- The **Misc.** drop-down menu provides several useful control tools to facilitate user interaction. .. figure:: ../Images/misc_tab.png :align: center :width: 25% Misc. Tab Proceed by Step ~~~~~~~~~~~~~~~ The **Proceed by Step** switch allows the user to frreze the graphics after a custom number of steps (see below the definition of step). The user can use the **Steps to Proceed** spinbox to set how many steps to proceed before the graphics freezes. During global (analytical) placement, step refers to every solver or legalizer iteration. During detailed (SA) placement, step refers to every temperature update. During routing, step refers to every router iteration. After freezing, clicking **Proceed** resumes the graphics until the next selected step boundary, unless another major program update (e.g. a state change) freezes the graphics early. In the latter case, the number of steps completed since the last freeze will not be carried over. A new step count will be performed from the current freeze. Turn off **Proceed by Step** to only freeze the graphics at major program updates. Save ~~~~ The **Save** button allows the user to output the current graphics into an image file. A popup will ask the user for file name and format. .. figure:: ../Images/save_popup.png :align: center :width: 50% Save Popup Debug ~~~~~ The CAD optimization algorithms can be paused at different user-specified points so you can examine the current placement and/or routing solution, as detailed `here `_. Manual Moves ~~~~~~~~~~~~ The manual moves feature allows the user to specify the next move in placement. If the move is legal, blocks are swapped and the new move is shown on the architecture. To enable the feature, activate the **Manual Move** checkbox and press Done. Alternatively, the user can activate the **Manual Move** checkbox and click on the block to be moved. .. figure:: https://www.verilogtorouting.org/img/draw_manual_moves_window.png :align: center :width: 50% On the manual move window, the user can specify the Block ID/Block name of the block to move and the To location, with the x position, y position and subtile position. For the manual move to be valid: - The To location requested by the user should be within the grid's dimensions. - The block to be moved is found, valid and not fixed. - The blocks to be swapped are compatible. - The location chosen by the user is different from the block's current location. If the manual move is legal, the cost summary window will display the delta cost, delta timing, delta bounding box cost and the placer's annealing decision that would result from this move. .. figure:: https://www.verilogtorouting.org/img/manual_move_cost_dialog.png :align: center :width: 50% The user can Accept or Reject the manual move based on the values provided. If accepted the block's new location is shown.