Introduction to Ruckus and SURF by TID-AIR Electronics
Ruckus and SURF are key frameworks developed by TID-AIR Electronics. Ruckus, a Vivado build system, simplifies Vivado project environments and integrates git repositories. Meanwhile, SURF, the SLAC Ultimate RTL Framework, offers various libraries for firmware development. Both are controlled and maintained by TID-AIR Electronics, promoting efficient firmware/IP management. Learn about revision control on GitHub before accessing the repositories.
Download Presentation
Please find below an Image/Link to download the presentation.
The content on the website is provided AS IS for your information and personal use only. It may not be sold, licensed, or shared on other websites without obtaining consent from the author. Download presentation by click this link. If you encounter any issues during the download, it is possible that the publisher has removed the file from their server.
E N D
Presentation Transcript
Sept 28, 2020 TID-AIR Electronics: An Introduction to Ruckus and SURF Larry Ruckman
What is Ruckus? Ruckus is our Vivado build system https://github.com/slaclab/ruckus (Released to public domain) Makefile/TCL based Ruckus is not an acronym - Naming inspired by the Rogue software naming convention (just name something without acronym or name being directly related to what it does) Ruckus provides the following: - Able to reproduce a Vivado project environment without revision controlling the entire Vivado project - Integrates the git repo into the Vivado build Prevents building uncommitted code Automatically generates local git tags for each build - Provides a basic framework for organizing firmware source code - Provides TCL helper functions for common task Example: setting up a chipscope ILA core after synthesis - Ruckus is Controlled and maintained by TID-AIR Electronics 2
What is SURF? SURF = SLAC Ultimate RTL Framework https://github.com/slaclab/surf (Released to public domain) TID-AIR Electronics Firmware IP repository - Ethernet Library: UDP) - AXI4 Library: - AXI4-Lite Library: - AXI4 stream Library: - Device Library: - Synchronization Library: - Wrapped Xilinx Library: - Serial Protocols Library: - SLAC Protocols: https://confluence.slac.stanford.edu/display/ppareg/SLAC+Protocols SURF is Controlled and maintained by TID-AIR Electronics (1000BASE-KX, 10Gbase-KR, XAUI, IPv4, ARP, DHCP, ICMP, (Crossbar, DMA, FIFO, etc.) (Crossbar, AXI4-to-AXI4-Lite bridge, etc.) (DMA, MUX, FIFO, etc) (ADI, Linear, Micron, TI, etc.) (Synchronize bits, buses, vectors, resets, etc) (clock managers, SEM, DNA, IPROG) (I2C, SPI, UART, G-Link, JESD204B, etc) 3
TID-AIR ES: Revision Control: Overview All firmware/software is revision controlled on GITHUB: - https://github.com/ TID-AIR ES GIT repositories: - https://github.com/orgs/slaclab/teams/tidaires/repositories 4
Before you clone the GIT repository from github . 1. Create a github account: https://github.com/ 2. On the Linux machine that you will clone the github from, generate a SSH key: https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/ 3. Add a new SSH key to your GitHub account: https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/ 4. Setup for large filesystems on github (line command below): $ git lfs install 5
dev-board-examples: How to build the firmware 1. Clone the repository: $ git clone --recursive git@github.com:slaclab/dev-board-examples 2. Setup Xilinx licensing: In C-Shell: $ source dev-board-examples/firmware/setup_env_slac.csh In Bash: $ source dev-board-examples/firmware/setup_env_slac.sh Note: This example shows setting up licensing on the SLAC network. 3. Make a directory (or symbolic link) to the firmware/build directory: If directory: $ mkdir amc-carrier-project-template/firmware/build If symbolic link: $ ln -s pathToHardDrive/build amc-carrier-project-template/firmware/build Note: symbolic link to local hard drive is recommended if git clone is on a network drive (AFS, NFS, etc) 4. Go to the target directory and build the targeted firmware: $ cd dev-board-examples/firmware/targets/XilinxAC701DevBoard/Ac701GigE/ $ make Note: This example shows building the 1000BASE-SX for the Xilinx AC701 development board 5. After build completes, open the GUI and review the design reports: $ make gui 6
dev-board-examples: How to build and run the software 1. Setup setup environment scripts : $ cd dev-board-examples/software/ In C-Shell: $ source setup_template.csh In Bash: $ source setup_template.sh Note: This example shows setting up environment on the SLAC network. These scripts are designed to be used as a template for generating your own scripts if not on the SLAC network. There are notes in the setup_template scripts of what environment variables and software dependence are required. 1. Build the software: $ make 1. Confirm that you have network connection to dev board: $ ping 192.168.1.153 Note: In this example, 192.168.1.153 is the IP address set by DHCP. If DHCP is not allowed on your network, modify the AppCore.vhd DHCP_G generic from true to false and the IP address is be AppCore.vhd IP_ADDR_G generic 2. Launch the software GUI: $ python3 scripts/DevBoardGui.py 192.168.1.153 7
dev-board-examples: Software GUI Firmware Version (manually set in firmware s Makefile) GIT SHA-1 Hash at the time of firmware build Build String (automatically generated during firmware build) 8
Ruckus Build System https://confluence.slac.stanford.edu/x/n4-jCg Based on a combination of Makefile scripts and TCL scripts Support both a GUI and batch mode design flow Version 2014.1 through Version 2020.1 Supported Vivado Linux install Better runtime performance than a Windows install Windows users can use Cygwin or Linux Virtual Machine Support the following Vivado software tools in our build system: Vivado (RTL programming) - VCS Simulation - Incremental Compile - Partial Configuration - IP Integrator (Example: Microblaze) Vivado HLS (C/C++ programming) System Generator (Matlab s Simulink programming) Build System Support Homepage 9
Ruckus Build System: File Structure: Overview/Definition ProjectBase - The base directory for both the firmware and software firmware : - This directory maintains a standard for file structuring - No file structure requirements on the software because independent of the ruckus build system submodules : - Contains all external git repo source code targets : - Contains the top level projects information and Makefiles - minimal source lives here build : - Common output directory for the targets and simulations - Typically, build is soft-linked to a directory on the server s hard drive to improve runtime performance common : - Contains source code common to all targets software ProjectBase firmware build common targets submodules more submodules ExampleTargetA ExampleTargetB ExampleTargetC ruckus surf 10
Ruckus Build System: File Structure: Submodules submodules directory Contains all external git repo source code Only ruckus and surf are required for ruckus build system Unless you are developing inside a submodule, users should ONLY work off of git tagged submodules - Example: v2.0.2 Required! ruckus surf submodules GitRepoA GitRepoB ruckus tag = GitRepoC surf tag = v2.0.0 11
Ruckus Build System: Example File Structure All development board examples for multiple protocols Virtex-7 Artix-7 Kintex-7 Kintex Ultrascale Includes software 12
Ruckus Build System: Whats inside a target directory $ tree -R dev-board-examples/firmware/targets/XilinxAC701DevBoard/Ac701GigE/ Local Makefile |-- Makefile |-- build.info |-- hdl | |-- Ac701GigE.vhd | `-- Ac701GigE.xdc |-- images | |-- Ac701GigE_0x00000001_20170216194654_1e6f1f1.mcs | |-- Ac701GigE_0x00000001_20170216194654_1e6f1f1.mcs.gz | |-- Ac701GigE_0x00000001_20170216194654_1e6f1f1.bit | `-- Ac701GigE_0x00000001_20170216194654_1e6f1f1.bit.gz |-- ruckus.tcl `-- vivado `-- promgen.tcl Generated at the start of each build and documents the git configuration at the start of the build Local sources Image Output Directory Compressed Versions of .mcs and .bit for commiting to GIT repo Steering file for adding source code to vivado project Version Number Build Short version of GIT HASH Timestamp If generating .MCS file, promgen.tcl contains PROM configurations 13
Ruckus Build System: Whats inside a target directory $ tree -R dev-board-examples/firmware/targets/XilinxAC701DevBoard/Ac701GigE/ |-- Makefile |-- build.info |-- hdl | |-- Ac701GigE.vhd | `-- Ac701GigE.xdc |-- images | |-- Ac701GigE_0x00000001_20170216194654_1e6f1f1.mcs | |-- Ac701GigE_0x00000001_20170216194654_1e6f1f1.mcs.gz | |-- Ac701GigE_0x00000001_20170216194654_1e6f1f1.bit | `-- Ac701GigE_0x00000001_20170216194654_1e6f1f1.bit.gz |-- ruckus.tcl `-- vivado `-- promgen.tcl For .bit file, only Makefile and ruckus.tcl required For .mcs, a promgen.tcl file in the vivado will also be required 14
Ruckus Build System: targets/DESIGN/Makefile 1 2 3 4 5 6 Notes: 1. 2. 3. 4. 5. 6. If only .bit file, change to target: bit Manually set by user FPGA part (must match Vivado part number convention) Optional: Only required if you have Microblaze in design Point to where the firmware/ directory is located Point to the ruckus/system_vivado.mk file 15
Ruckus Build System: targets/DESIGN/ruckus.tcl 1 2 3 Notes: 1. 2. Loads the RUCKUS TCL environment Points to other ruckus.tcl file that will point to other ruckus.tcl files, which will eventual load all the source code (explained detail in a later slide) Loads the local target source code 3. 16
Ruckus Build System: loading source code TCL procedures https://github.com/slaclab/ruckus/blob/master/vivado_proc.tcl loadRuckusTcl(): Used to recursively load source load from a different ruckus.tcl Creates a hierarchy of steering files loadSource(): Used to load source code (.vhd, .v, .vh, .sv, or .dcp files) into Vivado project flag for tagging source code as simulation only flags for pointing to single file or all files in a directory (non-recursive) loadIpCore(): Used to load Xilinx IP cores (.xci or .xcix files) into Vivado project flags for pointing to single file or all files in a directory (non-recursive) loadBlockDesign(): Used to load Xilinx IP integrator designs (.bd or tcl files) into Vivado project flags for pointing to single file or all files in a directory (non-recursive) loadConstraints(): - Used to load constraints (.xdc or .tcl files) into Vivado project - flags for pointing to single file or all files in a directory (non-recursive) 17
ruckus.tcl examples: Creating a hierarchy of steering files https://github.com/slaclab/dev-board-examples/blob/master/firmware/targets/XilinxAC701DevBoard/Ac701GigE/ruckus.tcl # Load common and sub-module ruckus.tcl files loadRuckusTcl $::env(PROJ_DIR)/../../../ points here https://github.com/slaclab/dev-board-examples/blob/master/firmware/ruckus.tcl # Load ruckus files loadRuckusTcl "$::DIR_PATH/submodules/surf" loadRuckusTcl "$::DIR_PATH/common" points here https://github.com/slaclab/surf/blob/master/ruckus.tcl points here and so on https://github.com/slaclab/dev-board-examples/blob/master/firmware/common/ruckus.tcl and so on 18
ruckus.tcl examples: Loading source code (part 1) Only load a single file (both synthesis and simulation): loadSource -path "$::DIR_PATH/hdl/Ac701GigE.vhd" Load all source code from a directory (both synthesis and simulation): loadSource -dir "$::DIR_PATH/hdl" Only load a single simulation file (simulation only): loadSource -sim_only -path "$::DIR_PATH/tb/Ac701GigETb.vhd" Load all source code from a directory (simulation only): loadSource -sim_only -dir "$::DIR_PATH/tb" Only load a single constraints file: loadConstraints -path "$::DIR_PATH/hdl/Ac701GigE.xdc" Load all constraints files from a directory: loadConstraints -dir "$::DIR_PATH/hdl" 19
ruckus.tcl examples: Loading source code (part 2) Only loading a single Xilinx IP core file: loadIpCore -path "$::DIR_PATH/ip/PcieCore.xci" Loading all Xilinx IP core files from a directory: loadIpCore -dir "$::DIR_PATH/ip" Only loading a single Xilinx block design file: loadBlockDesign -path "$::DIR_PATH/bd/SoftProcessor.bd" Loading all Xilinx block design files from a directory: loadBlockDesign -dir "$::DIR_PATH/bd" 20
Build System: Design Flow: Both GUI and Batch mode Start Batch Mode Support both a GUI and batch mode Batch mode: - Pros: High performance building No X11 forwarding required Minimal build overhead - Cons: Cryptic error messaging Difficult to analysis design from terminal printouts GUI mode: - Pros: Native Vivado interaction and design analysis tools User friendly error messaging - Cons: Very X11 intensive Increased runtime compared to batch mode $ make Start GUI Mode $ make gui Typical Design Flow: 1. Enter the GUI mode 2. Find all synthesizing errors 3. Analysis the synthesized design (clock constraints, resource usage, pinouts, and etc.) 4. Exit the GUI 5. Launch the batch mode 6. Wait for the batch mode to generate the .bit and/or .mcs file If an error occurs (timing error or placement error), launch the GUI mode (without make clean) to analysis the implementation error(s) 7. Optional: Once batch mode is complete, launch the GUI mode (without make clean) to review the implementation reports (resources, timing, power estimates, and etc.) 22
Build System: Simulation Support two simulation modes: Vivado Native Simulator: - Pros: Quickly prototype and simulate firmware - Cons: No external software interface Synopsys VCS Simulator: - Uses to the Vivado framework to generate the VCS build scripts - Pros: Able to attach a software interface via shared memory interface Able to simulate mixed signals (analog + digital) - Cons: Some additional setup time compared to Vivado Native simulator 23
Design Flow: IP Core Generation Typical Design Flow: 1. Open the GUI mode ( make gui ) 2. Open the IP Catalog 3. Select the IP that you want to configure 4. Generate the IP core 5. Close the GUI mode 6. Copy the IP core s .xci file from the build/ directory to the firmware/common directory 7. Update the ruckus.tcl file to point to the new Xilinx IP core file 8. Remove the obsolete files in the build/ directory with a make clean command 9. Re-open the GUI mode ( make gui ) 10. Confirm that your new IP got included into the IP Sources 24
