The base board firmware

This is a description of what the firmware of the SuperMuSR ADC120 (DAQ1x1) base board does once it is running on the instrument: what it shows, what it monitors, what the DAQ can ask of it and how it is updated. For how to compile it, see README.md.

The base board is the hub of the instrument. The four DAQ boards (A to D) plug into it, and it is the base that distributes the clock, the sync and the T0 to them, routes the sixteen front-panel LEMO connectors, powers and reads the staves, and carries the OLED display and the three buttons on the front panel. Inside its Kintex-7 FPGA there is a MicroBlaze processor, and the firmware described here is the application that runs on it.

At a glance

The firmware never takes part in data acquisition: it is the monitoring, display and maintenance processor of the board. Acquisition runs in the FPGA fabric and on the DAQ boards.

What happens at power up

The FPGA always configures itself from address 0 of the SPI flash, which holds the bootloader image. The first thing the application does is decide whether to stay there or hand over to the firmware image:

1. it reads the configuration status register of the FPGA through the HWICAP
2. it reads the three front-panel buttons
3. then:

So, in normal operation, the board configures itself twice at every power up: once from the bootloader, once from the firmware. The whole sequence takes well under a second and is not visible from the outside, except that the display starts in the firmware image.

Bootloader mode is the recovery state of the board. It is reached on purpose, by holding the centre button while powering up, and by itself whenever the firmware image is missing or half written. The display shows:

BOOTLOADER
This device entered in bootloader mode.
The base can be reprogrammed from DAQ.

In this state nothing is monitored and no screen can be browsed: the board waits for the DAQ to rewrite the firmware image. This is why the bootloader is never updated in the field - as long as it is intact, a board can always be recovered.

The front panel display

Three buttons, and they mean the same thing everywhere:

Buttons are debounced over about an eighth of a second, and one press is one action: holding a button down does not repeat it.

The screens, in order

Starting from the home screen and pressing right:

Two screens appear by themselves, whatever was being shown:

• BASE FW UPGRADE, while the DAQ is rewriting the base firmware (see below)
• EMERGENCY - All DAQ have been disabled due over-temperature. The firmware raises it as soon as the over-temperature flag of the temperature monitor is set; pressing any button acknowledges it, and it comes back if the condition clears and sets again

Resetting the IP addresses of the DAQ boards

This is the one setting that can be changed from the panel, and it is deliberately awkward to reach by accident: from the IP screen, press centre to get the IP RESET screen, then press centre five times. The firmware then asks all four DAQ boards to go back to their default address as a static address, and confirms:

IP of all DAQ has been restored to default values and set as static.

The counter on the screen shows how many of the five presses have been registered; leaving the screen at any point cancels it.

What the firmware monitors, and where it comes from

Everything on the screens is read fresh at every refresh. There is no history and nothing is stored: the display is a window on the current state.

The temperatures are the only quantity this firmware measures itself, and it publishes them back into the shared memory so that the DAQ software can read them too.

What the DAQ can ask of the base

The DAQ talks to this firmware through a small command window in the shared memory: it writes a command, the firmware executes it and writes back a status (not executed, in progress, success, error). The command register is cleared as soon as it is read, so each command is executed once.

Updating the base firmware

The base firmware is updated from the DAQ, over the shared memory, while the board keeps running from the bootloader or from the current firmware. The DAQ software drives the whole sequence; what this firmware contributes is the flash access and the progress on the display:

The new image takes effect at the next power cycle, because it is the FPGA that has to be reconfigured from it. Only the firmware image is ever written this way: the bootloader at address 0 is left alone, which is what guarantees that an interrupted update can be retried rather than leaving a dead board.

If an update is interrupted - power lost halfway, a corrupted file - the FPGA fails to configure from the firmware image, falls back, and the board comes up in bootloader mode ready for another attempt. Nothing has to be done on the bench to recover it.

Installing the two images on a new board

The package daq1x1-base-fpga publishes the two images separately:

A board that has never been programmed needs both, written with a JTAG programmer. After that, only the firmware image is ever replaced, and it can be replaced from the DAQ.

The two files are built from the same design and differ only in which half of the flash they are meant for; writing them the other way round leaves a board that configures but never reaches normal operation.

Known limitations

• HV screen. The current of the four channels always reads 0uA, and the value shown as the voltage is in fact the current register: the firmware overwrites the voltage with it while refreshing. The HV values reported by the DAQ software are the ones to trust
• No history. Temperatures, rates and states are shown live only; nothing is logged on the board. Trends have to be collected by the DAQ software
• Bootloader mode is blind. While in bootloader mode the board monitors nothing and shows no screen other than its own: this is by design, but it means a board held in bootloader mode looks the same as a board with a broken firmware image

Troubleshooting