Software setup from scratch
The instructions below assume that
- you want to set up an FMC ADC on a SPEC carrier board
- the build process happens on the target machine, a more or less up to date Linux system
- kernel sources for the running version of the target machine kernel are installed
- the target has access to the ohwr.org host where repositories are hosted
Note: If you are looking for instructions to setup the software for the FMC-ADC Production Test Suite (PTS), you should instead use this guide.
These instructions have been tested and are known to work with Ubuntu Linux 19.04.
Clone the software repository
$ git clone https://ohwr.org/project/fmc-adc-100m14b4cha-sw.git
Build all the software stack
Change dir into the freshly cloned repository, and check out the latest stable release:
$ cd fmc-adc-100m14b4cha-sw
$ git checkout fmc-adc-100m-4.1.1
After that, just type 'make', but exclude building of the White Rabbit NIC (it does not work with recent Linux kernels and it is not required at all by the FMC-ADC software):
$ CONFIG_WR_NIC=n make
This will build the FMC ADC drivers, libraries and test programs. In the process, the build will automagically resolve the dependent submodules (fmc-bus, spec-sw, zio) and build them recursively. After some minutes, depending on your hardware configuration, the build should have terminated successfully.
Prepare firmware
We are about to load the Linux device drivers for your FMC ADC. There is one more pre-requisite before doing so. Appropriate firmware binaries must be made accessible to initialise your hardware:
$ sudo mkdir -p /lib/firmware/fmc
$ cd /lib/firmware/fmc
$ sudo wget https://www.ohwr.org/project/fmc-adc-100m14b4cha-sw/uploads/72545736ae289aba2df7c8b47432956c/spec-fmc-adc-v4.1.bin
$ sudo ln -s spec-fmc-adc-v4.1.bin spec-fmc-adc-100m14b.bin
$ sudo wget https://www.ohwr.org/project/spec-sw/uploads/636e7eaa2e1c3a884e2f9f694fdfd1b9/spec-init.bin-2015-09-18
$ sudo ln -s spec-init.bin-2015-09-18 spec-init.bin
Load the kernel modules
Again, super user status is required for this. Change dir into the cloned repository, and load the modules in the proper order:
$ cd fmc-adc-100m14b4cha-sw
$ sudo insmod fmc-bus/kernel/fmc.ko
$ sudo insmod spec-sw/kernel/spec.ko
$ sudo insmod zio/drivers/zio/zio.ko
$ sudo insmod zio/drivers/zio/buffers/zio-buf-vmalloc.ko
$ sudo insmod kernel/fmc-adc-100m14b.ko
These are the required modules to drive an FMC ADC (or more) carried by SPEC boards.
Note: Because these modules are not officially signed, the kernel will refuse to load them if Secure Boot is enabled. Please make sure that Secure Boot is disabled in your BIOS. If you really need to have the Secure Boot feature enabled, please have a look on how to sign your own modules and use your own keys to sign all five modules listed above.
If this step is successful, your kernel module list should display at least the following:
$ lsmod
Module Size Used by
[...other modules...]
spec 22358 0
fmc_adc_100m14b 60343 0
fmc 19119 2 spec,fmc_adc_100m14b
zio 67461 1 fmc_adc_100m14b
[...other modules...]
If you got to this point, congratulations! Your kernel device drivers are ready to go, and the installed boards should be recognized by them. Look into the directory /dev/zio to see your device nodes in full glory:
$ ls -l /dev/zio
crw-rw---- 1 root root 247, 8 May 18 11:41 /dev/zio/adc-100m14b-0400-0-i-ctrl
crw-rw---- 1 root root 247, 9 May 18 11:41 /dev/zio/adc-100m14b-0400-0-i-data
Do note the hexadecimal number after the "adc-100m14b" in the example above, you will need this when doing an acquisition later.
Finally, do an acquisition
Chapter 13 of the manual describes how to use the FMC ADC workhorse program fald-simple-acq, which will allow you to acquire samples from your ADC. Instructions in the manual are sufficient to get you started, so we will not duplicate them here.
As a quick example, to perform an acquisition of 20 samples with an internal threshold of 0V on channel 1, do the following:
$ cd fmc-adc-100m14b4cha-sw/libtools
$ sudo ./fald-acq -b 10 -a 10 -n 1 -t 0 -c 1 0x400
(The 0x400 comes from /dev/zio as seen in the example before).