Helper Tools

The operation of MBF is assisted by numerous scripts.

Startup Scripts

./load_fpga

Usage: load_fpga [-f bit-file] [addresses]
    -f bit-file
        Optionally specify location of bit file, otherwise $BIT_FILE will
        be loaded from the current directory

Loads an FPGA image onto the AMC card.

./start_ioc

start_ioc ioc-name

This script should be passed the name of an IOC configured in the iocs directory.  The IOC is launched (using epics/runioc) under procServ.

iocs/start-ioc

An IOC is configured by creating a soft link to this script with the name of the IOC in the iocs directory.

epics/runioc

Usage: runioc [options] config-file
Starts MBF IOC with configured options.
    -v      Run with valgrind memory checker enabled
    -l      Add leak check to valgrind (must specify -v first)
    -t      Add track origins to valgrind (must specify -v first)
    -q      Disable PV logging
    -u      Don't lock hardware registers
    -z      Disable delay compensation

This is the main launcher for running the EPICS IOC.  Don't use the -v option for normal operation as it slows things down too much.  The -z option is only for use with delay compensation measurement.

This script should not normally be run directly, instead use start_ioc or the launcher link in iocs.

epics/setup_mbf

setup_mbf ioc-config

This script is run as part of IOC initialisation to initialise the hardware.  The main work is programming the three devices (PLL, ADC, DAC) on the FMC500 card.  An IOC configuration file must be passed as the only argument.

epics/initial-state

initial-state ioc-name

This helper script can be run after the first run of an EPICS IOC or when the state file has been deleted.  The compensation filters and ADC limits are reset, the bunch output gains are all set to 1, and some initial bank configurations are set.

epics/runopi

This script launches an EDM panel with access to the available MBF systems.

GUI Helper Scripts

All of the scripts described here are run as helpers for the EDM screens.

epics/opi/scripts/run-command

This is a wrapper script for running other helper scripts in a temporary xterm terminal.  This is done so that if the script fails then the output can be reviewed.

epics/opi/scripts/mbf-help

This script launches Firefox to view the appropriate help page when the help button  on a GUI screen is pressed.

epics/opi/scripts/mbf-setup-tune

This script is called in response to each of the "Tune" setup buttons at the bottom of the MBF Overview page.

usage: mbf-setup-tune [-h] [-c CONFIG] [-d] [-m RING_MODE] [-t TUNE] [-n]
                      device mode

Configure device in specified setup mode.

positional arguments:
  device        TMBF device name to configure
  mode          Configuration mode, must be one of TUNE, AP, FB

optional arguments:
  -h, --help    show this help message and exit
  -c CONFIG     Alternative configuration file
  -d            Enable debug mode
  -m RING_MODE  Specify ring mode, otherwise PV will be consulted
  -t TUNE       Specify tune, otherwise config file will be consulted
  -n            Dry run, don't actually write to device

The configuration mode is set according to the button name as follows:

The setup is read from two files:

epics/opi/scripts/mbf-set-waveform

mbf-set-waveform PV value [bunch]

This helper function is called from the detector bunch setup screen, and is used to update a waveform PV.  If bunch is not specified the entire waveform is set to value, otherwise only the selected bunch is updated.

epics/opi/scripts/mbf-set-one-bunch

This helper function is called from the bunch bank setup screen and is used for a variety of update functions.

Tune Fitter

The tune fitter is managed by the following scripts.

tune_fit/runioc

Script for launching the tune fitter.

iocs/start-fitter

Helper script for launching tune fitter IOC.

tune_fit/plot_replay

Used to run tune fitter algorithm on canned data.

Development Scripts

Note that build scripts are not documented here.

epics/measure/measure_delays

This script should be run when changes have been made to the firmware.  An IOC must be started in TMBF mode with the -z flag and then this script is launched with the name of the IOC passed as the only argument.  The output from this script is then used to update the file epics/hardware_delays.

tools/reg

usage: reg [-h] [-a ADDR] bank [reg] [value]

Read/write raw registers

positional arguments:
  bank        Register bank to access according to mapping: 0 SYS - System
              control registers; 1 CTRL - Shared DSP management registers; 2
              DSP0 - First DSP channel control; 3 DSP1 - Second DSP channel
              control
  reg         Register to read or write. If not specified, entire bank is read
  value       Value to write to register if specifed

optional arguments:
  -h, --help  show this help message and exit
  -a ADDR     Set physical address of card. If not specified then card 0

Provides direct access to FPGA registers by register number.  Use with care!

tools/spi

tools/spi spi reg [value]

Provides direct access to the FMC 500 SPI registers.  Use with care!  If no value is given the register is read, otherwise value is written to the register.  The spi parameter determines which device is addressed:

tools/scan_idelay

usage: scan_idelay [-h] [-a ADDR] [-f F_RF] [-s IDELAY] [-n CAPTURE_COUNT]
                   [-m CLOCK_MODE]

Scan for best IDELAY setting

optional arguments:
  -h, --help        show this help message and exit
  -a ADDR           Set physical address of card. If not specified then use
                    card 0
  -f F_RF           RF frequency, used to calculate number of samples
  -s IDELAY         If set, set IDELAY to this after test
  -n CAPTURE_COUNT  Number of data points captured for each sample
  -m CLOCK_MODE     Configure clock mode before running scan

Scans through ADC clock to data delays and shows result from reading test pattern.  Needs to be run on initial commissioning of new hardware, and should be checked after updating firmware.

Areas of Concern for Portability

The following issues will need to be sorted out.

• Many of the scripts have DLS specific configuration
• There is no support for procServ logging.
• Large parts of mbf-setup-tune are DLS specific.
• The configuration of mbf-setup-tune needs to be documented.