Skip to content

W
White Rabbit Switch - Gateware

Fordevelopers

Last edited by Grzegorz Daniluk
Page history

Getting started with switch gateware development

This page provides information for people who want to contribute to the development of the WR switch gateware (HDL). It is meant to explain first steps to get going with the simulation and synthesis assuming a developer installed HDLmake (explained below), Xilinx ISE, ModelSim (supporting mixed-language simulation) in the Linux environment.

A sketch (unfinished) depicting architecture of switch HDL can be found here. The figure provides a high level of details when zoomed in; while when zoomed out, it should be handy in getting a global idea of HDL architecture. Note that the switch is under development and some details of the drawing might be out of date, the general picture remains.

A description of registers that are used to control HDL modules by software can be found here (v3.3 and v4)

HDLmake

HDLmake is a tool for generating multi-purpose Makefiles for FPGA projects that are used to simulate and synthesize gateware. The instructions in the following sections assume that you have HDLmake already installed and its location is added to your PATH environment variable. If you need more information on this tool, please visit one of the following places:

Beware: we are currently using ISYP branch of HDLmake*

HDL directory structure

  • ip_cores - contains external cores used by the project (included in the git repo as submodules)
  • modules - include switch-specific & FPGA-independent VHDL modules
  • platform - contains FPGA-dependent VHDL code
  • sim - contains SystemVerilog models, drivers and register layouts used by testbenches
  • syn - contains ISE project files for synthesis, e.g. if you want to synthesize 18-port WRS version, you should go to syn/scb_18ports
  • testbench - contains testbenches for the top-level of the switch, some of the modules and a network of switches
  • top - contains top-level and constraint files

The top/bare_top/ contains scb_top_bare.vhd which is a configurable top level entity of the switch. This entity is used by both, synthesis and testbench top levels. In other words, this is a configurable IP which needs some more VHDL to simulate or synthesize.

WRS gateware synthesis (v4.2)

ISE projects for switch synthesis are defined for different number of ports (i.e. 8, 15, and 18) in the syn directory (e.g.: syn/scb_18ports for 18 port synthesis). The 8-port version is used by developers to speed up testing all new functionalities and bugfixes since the full 18-port synthesis takes ~3h. The ISE project in syn/scb_18ports relates to the top entity and UCF files in top/scb_18ports directory (scb_top_synthesis.vhd and scb_top_sythesis.ucf). The scb_top_sythesis.vhd instantiates top/bare_top/scb_top_bare.vhd with proper parameters.

You need to make sure that you have all the tools for the switch synthesis. You will need:

  • git - to download the sources from our official repository
  • hdlmake and make - to create a project file and run the synthesis
  • 64-bit version of Xilinx ISE 14.5 or above - for the actual synthesis and bitstream generation

# First you need to setup your environment

/opt/Xilinx/<version>/ISE_DS/settings64.sh
export XILINX=/opt/Xilinx/<version>/ISE_DS

# Download the HDL sources

git clone git:https://www.ohwr.org/white-rabbit/wr-switch-hdl.git
cd wr-switch-hdl
git checkout wr-switch-sw-v4.2
git submodule init
git submodule update

# Generate SDB Metadata package with synthesis information

cd top/bare_top
./gen_sdbsyn.py --user <your name> --project WRS_18p --ver <ISE version>

# Run the synthesis

cd ../../syn/scb_18ports

a) If you use the ISYP version of hdlmake, run the hdlmake with proper arguments

hdlmake --ise-proj --make-ise
make

b) If you use the version v2.1 of hdlmake, you need to add the following line to the Manifest.py file located in syn/scb_18ports

syn_tool="ise"

and only then run the hdlmake (no arguments)

hdlmake
make

This can take ~3 hours

# Deploy your new gateware

 scp scb_top_synthesis.bin root@<your_switch_ip_address>:/wr/lib/firmware/18p_mb-LX240T.bin
  1. Reboot the switch so that your new gateware is loaded

WRS gateware simulation

The testbench of the switch is written in SystemVerilog and is located in the testbench/scb_top/main.sv. It uses top/bare_top/scb_top_bare.vhd indirectly:

  • scb_top_bare.vhd is instantiated in top/bare_top/scb_top_sim.vhd
  • scb_top_sim.vhd is wrapped by testbench/scb_top/scb_top_sim_svwrap.svh
  • scb_top_sim_svwrap.svh is used in the main testbench: testbench/scb_top/main.sv

The following steps are needed to simulate the switch

# Clone the repository with submodules (you can skip this step if you've already downloaded the repository for synthesis)

git clone --recursive git:https://www.ohwr.org/white-rabbit/wr-switch-hdl.git
cd wr-switch-hdl
git submodule update

# Add a symbolic link in the sim directory to wr-cores simulation drivers

cd sim
ln -s ../ip_cores/wr-cores/sim wr-hdl

# Go to the main testbench location and generate a Makefile using HDLmake

cd testbench/scb_top
hdlmake --make-sim

# Most likely you will see messages about dependency problem - they can be ignored

Generating makefile for simulation...
Cannot depending file for file /home/mlipinsk/Development/new_repos/wr-switch-hdl-ni/testbench/scb_top/main.sv: simdrv_wrsw_nic.svh
Cannot depending file for file /home/mlipinsk/Development/new_repos/wr-switch-hdl-ni/testbench/scb_top/main.sv: simdrv_txtsu.svh
Cannot depending file for file /home/mlipinsk/Development/new_repos/wr-switch-hdl-ni/testbench/scb_top/main.sv: if_wb_master.svh
Cannot depending file for file /home/mlipinsk/Development/new_repos/wr-switch-hdl-ni/testbench/scb_top/main.sv: if_wb_slave.svh
Cannot depending file for file /home/mlipinsk/Development/new_repos/wr-switch-hdl-ni/testbench/scb_top/main.sv: wb_packet_source.svh
Cannot depending file for file /home/mlipinsk/Development/new_repos/wr-switch-hdl-ni/testbench/scb_top/main.sv: wb_packet_sink.svh
Cannot depending file for file /home/mlipinsk/Development/new_repos/wr-switch-hdl-ni/testbench/scb_top/main.sv: scb_top_sim_svwrap.svh

# HDLmake should generate a proper Makefile. You should now compile the whole design

make

# Simulate the switch by opening ModelSim, changing the directory to testbench/scb_top, and by running run.do script

do run.do
  1. You should see frames being forwarded by the switch

30 October 2015

Files