The procedure for bringing up the Multi-Bunch Feedback processor system for the first time in a new environment is a little involved and is documented below.

Preparing Hardware

Hardware

Here we focus entirely on the control system.  A complete multi-bunch feedback system consists of a Beam Position Monitor button block, typically an RF hybrid assembly to convert button signals to scaled position and intensity, an RF front end to down-convert button signals at an intermediate frequency (1.5GHz at Diamond) before the signal is sampled and processed by the control system.  The output from the control system is then up-converted if necessary, amplified, and driven onto the beam, either through strip-lines (for transverse operation) or through a dedicated RF cavity for longitudinal operation.

The MBF control system at Diamond consists of the following hardware:

Populating the crate

• The two FMC cards must be placed in the AMC 525 carrier in the correct slots, with the Digital I/O card in slot 0 and the FMC 500 in slot 1 (more details and pictures in this section).  See the image below to verify the correct configuration:
  
  Note that because of an address conflict on the shared IPMI I²C bus between the programmable input threshold DAC on the CTI-FMC-DIO and a temperature sensor on the AMC525 (and thus a MTCA IPMI alert which won't go away), it is necessary to make a modification to the DIO card to reassign the address to an unused address. This done by cutting the track to ADDR1:
  
  
  
  
• When placing the AMC cards in the crate it seems that it is necessary to be careful about which cards are (logically) adjacent to the processor card.  To avoid problems, at DLS we installed the processor card in slot 6 and the carrier cards in slots 2 and 3 (note that these slot numbers don't correspond to the PCIe addresses which we'll encounter later).  Specifically, it seems that with the processor card in slot 6 we need to avoid placing a carrier card in slot 5, as otherwise the processor card tries to boot from non-existent mass storage in this slot!
• At this point its a good idea to ensure that all serial ports are configured with the same data rate.  The default line speed is 115200 8N1 for all ports except for the CPU console which defaults to 9600 8N1.
• Now e-keying must be configured.

Table of relevant serial ports

E-key configuration

Once the hardware has been configured as above the crate can be powered on and the e-keying for the CPU and AMC525 must be set up.  This will be particularly important to ensure that the PCIe link works properly.

CPU e-key

Payload SOL Port   : Serial1
Gbe Management Port: back0
Shutdown delay     : 30s

Commands:
  ekey          - Configure Electronic Keying
  lan           - Configure LAN Parameters
  plser         - Configure Payload Serial Port
  mgtport       - Configure Gbe Management Port
  wdcfg         - Configure Watchdog Parameters
  shutdowndelay - Configure shut down delay
> ekey

E-Keying configuration
*  1) Gigabit Ethernet - Port 0        *  2) Gigabit Ethernet - Port 1        
*  3) PCIe Root -  Ports 4-11             4) PCIe Root -  Ports 4-7           
   5) PCIe Root -  Ports 8-11             6) SATA Client - Port 2             
   7) SATA Client - Port 3             

Commands:
  1-7 to toggle option.
  save, cancel

Ensure that the following are configured:

Note: Port 1 is enabled but not used.

AMC e-key

Connect to the MGT-RS232 port on the AMC525 front panel, and type ekey at the prompt.  Adjust for the following settings:

AMC525 > ekey

E-Keying configuration
*  1) Gigabit Ethernet - Port 0        *  2) Gigabit Ethernet - Port 1        
   3) SATA Server - Port 2                4) SATA Client - Port 2             
   5) SATA Server - Port 3                6) SATA Client - Port 3             
   7) SAS - Port 2                        8) SAS - Port 3                     
   9) PCIe Root -  Ports 4-11            10) PCIe Root -  Ports 4-7           
  11) PCIe Root -  Ports 8-11          * 12) PCIe Node -  Ports 4-11          
  13) PCIe Node -  Ports 4-7             14) PCIe Node -  Ports 8-11          
  15) SRIO 3.125 Gbaud - Ports 4-7       16) SRIO 2.5   Gbaud - Ports 4-7     
  17) SRIO 1.25  Gbaud - Ports 4-7       18) SRIO 3.125 Gbaud - Ports 8-11    
  19) SRIO 2.5   Gbaud - Ports 8-11      20) SRIO 1.25  Gbaud - Ports 8-11    
  21) XAUI - Port 4-7                    22) XAUI - Port 8-11                 

Commands:
  1-22 to toggle option.
  save, cancel

Ensure that the following are configured:

Also the vadj setting must be configured as otherwise the FMC cards will not be powered on.

  FMC0 EEPROM is invalid / missing
  FMC1 VADJ range is 0.00V - 0.00V
  VADJ setting is 1.80V
AMC525 > vadj
0: 1.80V
c: Cancel
Select Voltage (0-0, c): 

If VADJ is not already set to 1.80V select 0 above to configure.

Cabling

Connections to Digital I/O card.

These are Lemo ERA.00.250 sockets taking FFS.00.250 connectors.  All inputs are configured as 3.3V TTL high impedance (though 50Ω termination can be configured in software if desired), all outputs are driven as 3.3V TTL.  All inputs are acted on once per machine revolution in response to a rising edge, but are continuously sampled (at machine RF frequency).

Connections to FMC500 card

These are all SSMC sockets.  The connectors should not be tighter than finger tight, our experience is that over-tightening can use the inner conductor to lose contact.  The official documentation (see page 26) recommends 0.2 Nm coupling torque.

System Software Setup

At this point the MTCA crate and all cards should be in a position to power up.  Now tangle with the BIOS and install your choice of Linux (RHEL 7 for DLS, Debian 9 at the ESRF (see installation notes here)).  No special drivers (except for the MBF driver, we'll get onto that) need to be installed, but you'll probably want IPMI administration configured.

Networking

Two out of the four available network ports need to be configured:

The administration network connects to the MCH and the P2040 CPU on the AMC card.  By default the following addresses are assigned:

ipmitool -I lan -H 192.168.40.250 -U '' -P '' shell

We can now validate the system by logging on to the MCH and AMC525 cards through the internal network.

MBF Kernel Driver

At some point before running the software the MBF kernel driver will need to be installed on the AMC720 processor. The following top level makefile targets may be helpful:

The details of how to manage driver installation are somewhat distribution specific.  Once the module has been installed it should be automatically picked up when the FPGA is loaded.

Bringing up the FPGA

First of all the FPGA must be loaded onto the AMC card.  The ./load_fpga script does the work: this must be run on the AMC720 processor card:

./load_fpga -f path/to/amc525_mbf.bit

(The -f bit-file argument can be omitted if the bit file is in the working directory.)

At this point run lspci -v, and you should see something like the following:

04:00.0 Signal processing controller: Xilinx Corporation FPGA Card XC7VX690T
    Subsystem: Xilinx Corporation Device 0007
    Physical Slot: 0
    Flags: fast devsel
    Memory at <unassigned> (64-bit, non-prefetchable) [disabled]
    Memory at <unassigned> (64-bit, non-prefetchable) [disabled]
    Capabilities: <access denied>

If we see this then the FPGA has been successfully loaded and the PCIe link is working correctly.  Note however that the PCIe IO memory cannot be mapped at this stage because it is too late for the BIOS to identify it: hence the Memory at <unassigned> lines (we see Capabilities: <access denied> merely because we're not running lspci as root).  Now reboot the processor card and re-run lspci -v and we should now see:

04:00.0 Signal processing controller: Xilinx Corporation FPGA Card XC7VX690T
    Subsystem: Xilinx Corporation Device 0007
    Physical Slot: 0
    Flags: bus master, fast devsel, latency 0, IRQ 70
    Memory at fe300000 (64-bit, non-prefetchable) [size=1M]
    Memory at fe400000 (64-bit, non-prefetchable) [size=64K]
    Capabilities: <access denied>
    Kernel driver in use: amc525_mbf

If the kernel driver has not yet been installed, now install it and run ls /dev.  The following files should be present:

The system is now ready to run the software.  Note that once the processor has been booted with a loaded FPGA present it won't need to be rebooted again if a fresh FPGA image is loaded until the whole system is power-cycled.

Note also that reloading the FPGA while the software is running is likely to trigger a kernel panic on the main processor (interrupted PCIe transactions don't seem to be handled well!), and hot-swapping the AMC is equally likely to do this.

Bringing up Software

Preparing IOC Configuration

To prepare to run a new IOC a new configuration and startup file in the iocs/ directory:

ioc_name=new-ioc-name
cd iocs
ln -s start-ioc $ioc_name
cp TS-DI-TMBF-02.config $ioc_name

Now edit the .config file.  The options are as follows:

procserv_port

device_address

dio_termination

clock_mode

499_682

352_202

352_372

Passthrough

13 0 5 2 381 61

epics_name

axis0_name

axis1_name

lmbf_mode

bunches_per_turn

revolution_frequency

lmbf_fir_offset

mms_poll_interval

persistence_file

persistence_interval

pv_log_array_length

memory_readout_length

detector_length

data_port

Now the IOC can be started, either by running iocs/$ioc_name or preferably ./start_ioc $ioc_name to run the IOC under procServ.

Note: If the environmental variable EPICS_CA_MAX_ARRAY_BYTES is not defined in your environment, it is advised to set it to a higher value than the default one (16384 bytes) for both the client and the server.  At DLS, it is set to 6000000 in all profiles.

Initial State

When MBF is started for the first time, or when the state file is deleted, the initial state of nearly all PVs is set to zero.  Before trying to use the system the input and output compensation filters should be reset to passthrough and the control gains should be set to 1.  The tools/initial-state script will perform this operation:

tools/initial-state $ioc_name

Also note that every time MBF is restarted, the DAC output is disabled.  This is deliberate to avoid accidentally driving onto the beam after a restart, but means that after every restart the :DAC:ENABLE_S pvs must be manually set.

Helper Tools

A number of Helper Tools are documented on the linked page.

Restarting the IOC

The IOC can be restarted at any time.  If however the crate is power-cycled then the procedure is slightly more involved:

1. Power on crate, wait for PC to boot
2. Reload FPGA with ./load_fpga script run on PC
3. Reboot PC (without power cycling) to pick up full PCIe functionality
4. Start IOC
5. Renable DAC outputs, rearm triggers