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.
Preparation
FPGA programming
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:
TODO
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:
- Follow first the installation instructions below, to install all drivers and software.
- Download and extract the latest binary.
- 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.
Linux permissions
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:
- Debian 10
- 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:
#!/bin/sh
function vme_register_instance
{
slot=$1
addr=$2
irq=$3
/usr/local/bin/vme-register --slot $slot --address-modifier 0x39 --address $addr --size 524288 --irq-vector $irq --irq-level 2 --name fmc-svec-a24
/usr/local/bin/vme-module --slot $slot --disable --ader 1,$addr,0x39,0,0
/usr/local/bin/vme-module --slot $slot --enable
}
vme_register_instance 2 0x580000 0xd9
vme_register_instance 4 0x680000 0xda
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.
Testing
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:
$ wrtd-tool list-nodes -v
-> WRTD Node detected with ID: 4
Current time = 20xx-yy-zz,21:14:03.756.661.189+000
2 Applications detected:
# wrtd-tdc
# wrtd-fd
0 Alarms defined.
0 Rules defined.
The above output shows that one WRTD SVEC-TDC-FD reference Node was detected.