For the first release (v1.0), this page describes the necessary steps to install WRTD and its dependencies.
This is not (yet) part of the WRTD documentation, because at the time of the release, the OHWR deployment procedures were undergoing significant changes (in particular with respect to packaging). Once these procedures have been finalised and tested, the contents o
f this page will be merged with the official documentation.
It is necessary to program the FPGAs of the WRTD Nodes prior to using them. To this end, it is highly suggested that users download the latest binaries and flash the FPGA bitstreams permanently to the Nodes, so that they always come up pre-programmed after a power cycle.
Flashing the SPEC FPGA
If you are using a SPEC carrier, you can flash the FPGA with the WRTD Node bitstream by following these steps:
Flashing the SVEC FPGA
If you are using a SVEC carrier, you can flash the FPGA with the WRTD Node bitstream by following these steps:
Use the svec-flasher tool (it will be located under /usr/local/bin) to flash the bitstream to the FPGA, following the instructions provided in section 4.1 of the SVEC Gateware Manual.
That's it. If it happens that your SVEC carrier has an outdated bootloader and you cannot complete step 3 above, then you can download v3 of the bootloader from here and follow the instructions provided in section 4.3 of the SVEC Gateware Manual.
If the bootloader of your SVEC is corrupt and you cannot do any of the above, then you can again download v3 of the bootloader from here and follow the instructions provided in section 4.4 of the SVEC Gateware Manual to flash the board using JTAG.
The installation process will automatically create a user group called wrtd. It is necessary to add (once) your user to this group to be able to access WRTD Nodes without superuser privileges.
Installation via Scripts
These instructions are known to work well on Linux CentOS7, which is the only officially supported Linux distribution.
Furthermore, these instructions are also known to work (from the point of view of not producing any errors during installation) in the following distributions:
Ubuntu 18.04 LTS
However, there is no guarantee that WRTD will properly work on these distributions, once installed. In particular, there is a known issue with DMA transfers causing a kernel crash, which prohibits the retrieval of ADC samples from the WRTD SPEC150T-ADC reference Node.
Build scripts are provided for the following targets:
WRTD SPEC150T-ADC reference Node
$ git clone https://gitlab.cern.ch/dlamprid/ohwr-build-scripts.git$ cd ohwr-build-scripts/scripts$ sh ./wrtd_ref_spec150t_adc_install.sh
The above will install everything necessary to work with the SPEC150T-ADC reference Node. Assuming the the FPGA is pre-programmed, it is enough to reboot the host once and everything should be loaded and ready to be used.
WRTD SVEC-TDC-FD reference Node
$ git clone https://gitlab.cern.ch/dlamprid/ohwr-build-scripts.git$ cd ohwr-build-scripts/scripts$ sh ./wrtd_ref_svec_tdc_fd_install.sh
The above will install everything necessary to work with the SVEC-TDC-FD reference Node. Assuming the the FPGA is pre-programmed, it is enough to reboot the host once, use the provided VME tools to register your SVEC-TDC-FD nodes to the system and load the necessary driver.
This is because VME does not provide "plug-n-play" functionality, although we are currently preparing a workaround for this to make the user experience similar to that provided by PCI.
See below for more details on VME registration.
To load the driver, simply do:
$ sudo modprobe -v wrtd-ref-svec-tdc-fd
IMPORTANT: Only load the driver after you have registered your VME cards. A good approach would be to append the command to load the driver at the end of your VME registration script, to ensure the correct order of execution.
VME registration example
This is a sample shell script that declares a registration function and then proceeds to use it to register two SVEC-TDC-FD cards at VME slots #2 and #4:
You can copy, modify and use the above script in your setup. It needs to be executed once after each host system reboot. Please make sure that you adjust the slot, addr and irq arguments according to your setup, to avoid conflicts with other VME cards.
Drivers, Libraries, Tools
$ git clone https://gitlab.cern.ch/dlamprid/ohwr-build-scripts.git$ cd ohwr-build-scripts/scripts$ sh ./wrtd_build.sh
The above will install all the WRTD host software. Note that if you use any of the reference design targets mentioned before, there is no need to perform this step; the reference design targets will automatically install all the host software as well. This target is only useful to people developing their own WRTD Nodes.
To verify that everything is working, and assuming that you have added your user to the newly-created wrtd group, you can simply check the output of the command: