The EPICS driver and device support for the booster QDRs provides a variety of EPICS records to program the QDRs and read their beam position data. Each time the QDRs receive an external "gate" trigger (SLS booster: 3.125 Hz) their fill internal 8K FIFOs with the data of the four BPM buttons ("gated acquisition mode"). The time that is required to fill the FIFO depends on the QDR filter setting and may exceed 320 ms. In this case the FIFOs are not filled at every gate trigger, but only every n-th gate trigger, since the QDRs ignore the triggers while the FIFO is not empty. The FIFO readout is handled by two vxWorks tasks created by the QDR EPICS driver. A high-priority task (common to all QDRs) polls the "FIFO full" flags in the QDR status register. When the FIFOs are full, a task with lower priority is triggered that reads the button data from the FIFOs, calculates beam positions, RMS values, FFTs of the beam positions etc. and triggers the device support of various EPICS records (with SCAN="I/O Intr"). The BPM data can be read from different records, e.g. waveform records for the FFT data or for beam positions as a function of time, analog input records for beam position RMS values etc.

The QDRs can also be programmed via EPICS records, e.g. by an analogue output record for the frequency of the numerical oscillator of the mixer in the digital downconverter ICs, by a mbbo record that switches between different QDR filter settings etc.. The driver software supports direct download of QDR filter data files that were generated with the DBPM development tool from Instrumentation Technologies.

Software Installation

File Overview

The C and C++ sources are compiled and put into the library QDRBoLib.o. Assuming the sources are compiled with the usual EPICS Makefiles it is often necessary to include the line

since many vxWorks installations do not support C++ exceptions (resulting in "missing symbol" errors when loading QDRBoLib.o).

IOC Startup Script

Arguments 7,8 and 9 are used for an SLS-specific purposes (access to the SLS RF frontends gain control DACs, see section "Gain Calibration File"). QDR users from other labs most probably do not need these features and therefore should set these argument to the dummy values given in the example above. You can check if the installation of the driver was successful by typing

QDRBo_Cmd "info","all"

in the VxWorks shell after booting the IOC. The command will generate a list of successfully installed QDR drivers. If QDRs are missing in this list the respective error message of the QDRBo_Create command should explain why (invalid or nonexistend QDR configuration file, wrong VMEbus address, same QDR name or VMEbus slot number used for two different QDRs, ...). If a QDR driver was not installed successfully then every EPICS record that tries to use the driver will generate an error message when EPICS is initialised. An example output of the above "QDRBo_Cmd" command (taken from an SLS test VMEbus crate that contains two QDRs) may look like this:

QDR Slot Address Vers. FIFO Cntrl #Trig. read[ms] read_max[ms] -------------------------------------------------------------------------- qdr3 5 0x11400000 11/0e 0x04cc 0x0007 14197 15 32 -------------------------------------------------------------------------- qdr5 7 0x11c00000 12/0e 0x04cc 0x0007 14198 32 55 -------------------------------------------------------------------------- value = 0 = 0x0

QDR Configuration File

# Names and ID numbers of QDR filter files
# (generated with the DBPM development tool
# of Instrumentation Technologies):

qdr_coeff 0 cfg/qdr_conf_bo-001_turns-420khz.txt
qdr_coeff 1 cfg/qdr_conf_bo-002_turns-210khz.txt
qdr_coeff 2 cfg/qdr_conf_bo-004turns-100khz.txt
qdr_coeff 3 cfg/qdr_conf_bo-008turns-50khz.txt
qdr_coeff 4 cfg/qdr_conf_bo-016turns-25khz.txt
qdr_coeff 5 cfg/qdr_conf_bo-032turns-12.5khz.txt
qdr_coeff 6 cfg/qdr_conf_bo-064turns-6.25khz.txt
qdr_coeff 7 cfg/qdr_conf_bo-128turns-3.125khz.txt
qdr_coeff 8 cfg/qdr_conf_bo-256turns-1.56khz.txt

# QDR filter setting to be loaded after reboot
# --------------------------------------------
coeff_init_id 0

# Frequency of the front panel input clock signal
# of the QDR in [Hz]
# -----------------------------------------------
qdr_clk_freq_hz 27758600

Lines in the file that begin with the character "#" are comments that are ignored by the QDR driver. The first string in each regular line of a configuration file is a keyword that tells the driver how to use the argument(s) after the keyword. The 1st argument after "qdr_coeff" is a positive integer (should start at 0, increment by 1 from line to line), the 2nd argument is the name of a QDR filter data file as generated with the DBPM development tool (a MS Windows program) from Instrumentation Technologies.

The record template file for the QDR software contains an "mbbo" record named "$(DEVICE):BANDW-SET" (see list of record names below). When the integer number (1st argument of "qdr_coeff") of a filter data file is written to the VAL field of this EPICS record the driver will download the filter file data to QDR memory. The contents of the configuration file and of the filter data files are read and parsed only once when the IOC is bootet. They are stored in IOC memory by the driver, in order to accelerate the download of the filter data and to avoid a (slow) NFS file access each time the QDR filter setting is changed. After reboot the driver will consequently ignore modifications of the files. However, if someone wants the driver to reread the file without rebooting the IOC he can write the filename of the QDR configuration file to the "stringout" record "$(DEVICE):CONFFILE" (see below) and the driver will load the configuration file and the filter data file specified in it.The integer after the keyword "coeff_init_id" in the configuration file is the number of the QDR filter data file the driver will load after reboot (when the command "QDRBo_Create" is executed). This feature may be useful for quick testing of QDRs on an IOC without using EPICS. The driver is basically independent of EPICS and can also be used in vxWorks systems without EPICS (the only EPICS-dependent feature of the driver is the use of the "epicsPrintf" function which may be renamed to "printf").

The integer after the keyword "qdr_clk_freq_hz" is the clock frequency of the "CLK" front panel input of the QDR in Hz. The keyword "<INCLUDE" (with 0 as 1st and a filename as 2nd argument) may be used to include another configuration file.

Each line of a filter data file simply contains an address offset (relative to the base address specified in the startup script) and the value to be written to the QDR memory location with that address offset. The beginning of such a file may look like this:

40      40404040
1000    180e88
2000    180e80
4000    180e88
8000    180e88
f004    4f9ff7f6
f008    0
f00c    275a8d29
f010    0
f014    0
f018    0
f01c    2fc627
f020    1a8a600
.
.
.

The address offsets (1st column) and values (2nd column) are in hexadecimal format, but without "0x" prefixes.

Gain Calibration File

At the SLS booster the QDR driver is also be used to set the gains of the BPM RF frontends. This feature is SLS-specific and most probably irrelevant for users of the QDR driver from other labs, who therefore may skip this section. If the gain control feature of the QDR driver is not used it is recommended to set the PINI field of the record $(DEVICE):GAINFILE to 0. This avoids an error message when the QDR driver tries to load a nonexistent gain configuration file specified in the VAL field of the record.

Due to manufacturing tolerances of the SLS BPM RF frontends, the four DAC set values that set the gains of the RF frontends for the four BPM buttons have to be slightly different from each other in order to obtain equal signal values for the BPM buttons readings after sampling, filtering and downconversion by the QDR (assuming identical input power of the four RF frontend inputs). The QDR driver allows the user to set the desired average gain for the four BPM channels so that the differences in the channels are automatically compensated. This is achieved by a gain calibration file. Each line of the file must begin with the keyword "gaincal", followed by 5 integers: the average button gain and the individual gains for the RF fontend channels A,B,C and D that equalize the QDR output values for the four channels. The SLS RF frontends have 16-bit ADCs. Since the nonlinearities of the amplifiers in the frontend are not systematic it is recommended to provide gain calibration values at least every 500 DAC set value steps for DAC settings below 30000 and at least every 1000 DAC set value steps for DAC settings above 30000. The driver uses linear interpolation to obtain the four button DAC settings for average gain values that do not exactly match one of the values in the configuration file. Due to nonlinearities the gain increments in the configuration file must be sufficiently small to achieve small BPM position measurement errors for any average gain value.

A gain calibration file is loaded by writing the filename to the record "$(DEVICE):GAINFILE". Loading a gain calibration file will cause the driver to "forget" the contents of the previously loaded gain calibration files. If only the file contents has changed but not the filename one can also reread the file by writing the value "1" to the record "$(DEVICE):GAIN-UPD" (see list of records below).

As mentioned above the QDR driver is independent of any other VMEbus board. It contains only code to access QDR memory. In order to set the gains of the BPM RF frontends by the QDR driver one must provide the name of a function to access the RF frontend DACs. The function name is specified as 7th argument of "QDRBo_Create" in the IOC startup script. Example (SLS booster):

QDRBo_Create("qdr1",5,0x11400000,5,0,"cfg/qdr_conf.dat","GCM_GainControl","gcm1",5)

At SLS the function "GCM_GainControl" is provided by the gcm (GainControlModule) driver "drvGCM.cc" that uses Wiese DSP boards to set and read the gains DACs. After loading a gain control file and writing the desired average RF gain to the record "$(DEVICE):GAIN-AVG-SET" (see list of EPICS records below) the QDR driver will call the function GCM_GainControl with the following arguments:


Argument No.	Example Value	Description	Type
1	0	value=0: set the RF frontend gain DAC value=1: read the RF frontend gain DAC	int
2	"gcm1"	argument no. 8 of `"QDRBo_Create`" (SLS booster: symbolic name of the gain control board as specified in the GCM_Create command in the startup script).	char*
3	5	argument no. 9 of `"QDRBo_Create`" (SLS booster: number of the serial gain control line. Values: 0...5).	int
4		value=0: pilot generator gain value=1: gain button A value=2: gain button B value=3: gain button C value=4: gain button D	int
5		pointer to an integer variable that contains the gain set value or that the gain readback value is written to.	int*

Each Wiese DSP board can control the gains of 6 RF frontends by 6 serial lines numbered 0,...,5 (argument 3). Each line controls 5 DACs on the RF frontend, 1 DAC (no. 0) for the pilot gain and 4 DACs (no. 1,2,3,4) for the BPM buttons A,B,C and D (argument 4).

EPICS Records

Example substitutions file for QDRBo_BPM.template (SLS booster):

file QDRBo_BPM.template {
pattern {DEVICE CARD S}
    {ABODI-BPM-6G qdr0 257060}
    {ABODI-BPM-6H qdr1 262810}
    {ABODI-BPM-6S qdr2 266275}
    {ABODI-BPM-1S qdr3 3725}
    {ABODI-BPM-1H qdr4 7190}
    {ABODI-BPM-1G qdr5 12940}
}

"Device" is the name of the BPM (prefix of all record names for that BPM). "Card" is the symbolic name of the QDR as specified in the startup script (see section "Startup Script" below). "S" is the location of the BPM in the ring in [mm] with respect to the moving coordinate system. "S" is not used or required by the driver software, it is only provided for convenience in a soft record e.g. for GUI plots. The following sections describe the records that are generated by the template file. The record name prefix $(DEVICE) is replaced with the BPM name.

BPM Beam Pipe Calibration Factors


Record Name	Description	Type
$(DEVICE):KX-SET	Horizontal beam position (x) calibration factor KX (set value): x[mm]=KX*(A+D-C-B)/(A+B+C+D) Buttons A and B are at the upper outer and inner side of the SLS rings, buttons D and C are at the lower outer and inner side of the SLS ring: `Orientation of SLS BPM buttons:` `-------------------------------` `up: y>0` `buttons: A B` `/-----------\` `outside (x>0) \| beam pipe \| inside (x<0)` `\-----------/` `buttons: D C` `down: y<0` SLS booster: KX = 8.33	ao
$(DEVICE):KX	Readback value	ai
$(DEVICE):KY-SET	Vertical beam position (y) calibration factor KY (set value): y[mm]=KY*(A+B-C-D)/(A+B+C+D) SLS booster: KY = 7.69	ao
$(DEVICE):KY	Readback value.	ai

QDR BPM Data Readout Control


Record Name	Description	Type
$(DEVICE):SW-SET	Disable/enable BPM data acquisition, i.e. readout and processing of the QDR FIFO data. Used by Operators to start/stop GUI updates.	bo
$(DEVICE):SW	Readback value.	bi
$(DEVICE):ENABLE-SET	Disable/enable BPM data aquisition. Used by experts to enable/disable faulty BPMs permanently.	bo
$(DEVICE):ENABLE	Readback value.	bi
$(DEVICE):NSAMP-SET	Number of samples that the QDR driver will read from each of the four QDR FIFOs (starting with the first FIFO word). Should be small enough not to overload the IOC, since reading and processing 4*8k samples of several QDRs at several Hz may require lots of CPU time. At SLS dedicated Motorola mv2306 BPM IOCs work with 6 QDRs, 8192 FIFO points, 3 Hz, some 10 ms FIFO filling time. However, 2k or 3k points are usually sufficient for orbit analysis, so be merciful with your CPUs ...	longout
$(DEVICE):NSAMP	Readback value.	longin
$(DEVICE):BANDW-SET	BPM bandwidth control. Writing a value "N" to the VAL field will of this record will program the QDR with the filter data file that has the index "N" (specified as 1st argument of the `"qdr_coeff`" keyword in the QDR configuration file). The string values for this record (and for $(DEVICE):BANDW) in the record template are SLS specific and should be modified depending on the contens of the filter data files.	mbbo
$(DEVICE):BANDW	Readback value.	mbbi
$(DEVICE):IMIN-SET	Minimum intensity for QDR driver at which it triggers record processing (for all records with SCAN="I/O Intr"). The QDR FIFOs are read at every external gate trigger of the QDRs (except if the filling time exceeds the CLK period, see above), but the records are not updated if the intensity (sum of 4 button raw values) is below this trigger threshold for all FIFO samples. Useful to update GUIs only if there is sufficient beam in the accelerator.	longout
$(DEVICE):IMIN	Readback value.	longin
$(DEVICE):PSRCH0-SET	Number of the 1st QDR FIFO sample that is used for the calculation of average and RMS values and for the intensity peak detection (that gave the record its name: PeakSeaRCH). If a QDR receives an external gate trigger there is usually still old data in the internal data pipeline of the Intersil downconverter chips of the QDRs that are connected to the FIFOs. Therefore typically 10-20 samples at the beginning of the FIFOs contain invalid data and should be discarded (the data is a filtered mix of old and new ADC data, usually resulting in a strange- looking spike). The VAL field of this record should be sufficiently large to ignore such invalid samples.	longout
$(DEVICE):PSRCH0	Readback value.	longin

Beam Position Waveforms (Data Window)

The waveforms below are used to display a "data window" that contains 200 samples of the usually much larger number of data samples that were read from the QDR FIFOs. The figure 200 is arbitrary and may be modified in the template file (NELM field). Waveforms are provided for the four QDR button channels (A,B,C,D), for beam position (X,Y), sum of button readings (I=intensity), sample number (INDEX) and button symmetry error (ERR). The 1st sample that is displayed in the window is adjusted with the record $(DEVICE):WF-SMP0-SET (value 0 = beginning of FIFO).


Record Name	Description	Type
$(DEVICE):WF-BUT-A	Sample window for raw FIFO values, BPM button A.	waveform
$(DEVICE):WF-BUT-B	Sample window for raw FIFO values, BPM button B.	waveform
$(DEVICE):WF-BUT-C	Sample window for raw FIFO values, BPM button C.	waveform
$(DEVICE):WF-BUT-D	Sample window for raw FIFO values, BPM button D.	waveform
$(DEVICE):WF-X	Sample window for horizontal beam position (x).	waveform
$(DEVICE):WF-Y	Sample window for vertical beam position (y).	waveform
$(DEVICE):WF-I	Sample window for BPM intensity (= sum of BPM button raw values).	waveform
$(DEVICE):WF-ERR	ERR waveform. Used to check if the four BPM buttons channels a,b,c,d are working properly. Formula: error=\|\|a+c\|-\|b+d\|\|/\|a+b+c+d\|. Value is ideally 0 for a centered beam, and ~0.33 if a channel is "dead" (broken cable, ...) and thus delivers a zero signal.	waveform
$(DEVICE):WF-INDEX	Sample window for sample numbers of the above waveforms (may be used used as horizontal axis for 2D plots).	waveform
$(DEVICE):WF-SMP0-SET	Number of the first FIFO sample that will be displayed in all of the above waveforms. Since the waveforms only display a small data window of the QDR FIFO data (typically 200 points, may be changed), this record can be used to scroll through the FIFO data (that may consist of up to 8192 points).	longout
$(DEVICE):WF-SMP0	Readback value.	longin

Beam Position FFT Records

The following records are waveform and control records for a 1024-point FFT of the horizontal (X) and vertical (Y) beam position data.The FFTs are performed each time the FIFOs are read, provided the FFT calculation is enabled via $(DEVICE):SW-FFT. If $(DEVICE):FFT-REF0 is set to 1 the QDR driver will calculate a 2nd FFT for each beam plane (X and Y) that starts at a different FIFO sample and subtract the resulting two FFT amplitude vectors.


Record Name	Description	Type
$(DEVICE):WF-FX	FFT coefficients (absolute values) for X beam positions in [µm]. A value "VAL" in this record for a frequency f (that is obtained from the record $(DEVICE):WF-FF, see below) is equivalent to a beam oscillation of *`X[µm]=VAL sin (2 * PI * f * time + const_phase)`**	waveform
$(DEVICE):WF-FY	FFT coefficients for Y beam positions. Unit: [µm].	waveform
$(DEVICE):WF-FCX	Integrated squares of the above X FFT coefficients (integrated power spectrum). Unit: (µm)².	waveform
$(DEVICE):WF-FCY	Integrated squares of the above Y FFT coefficients (integrated power spectrum).	waveform
$(DEVICE):WF-FF	Frequencies for the above FFT amplitudes. May be used as horizontal axis data for 2D plots of any of the above waveforms.	waveform
$(DEVICE):FFT0-SET	Number of the first QDR FIFO sample that is used for the 1024-point FFT calculation. The record "$(DEVICE):NSAMP-SET" should be set to a sufficiently large value so that all samples in the FIFO readout buffer that are used for the FFT are updated. If only part of the samples are updated the spectrum may look strange ...	longout
$(DEVICE):FFT0	Readback	longin
$(DEVICE):SW-FFT	Enable/disable FFT calculation.	bo
$(DEVICE):SW-FFTREF	If this record is set to ON the QDR driver will calculate FFTs for two sample windows and write the difference of the two FFT amplitude vectors (resp. the difference of the squares in case of the :WF-FC... records) to the four FFT records $(DEVICE):WF-FX, $(DEVICE):WF-FY, $(DEVICE):WF-FCX, $(DEVICE):WF-FCY. The number of the first sample of the first FFT is determined by $(DEVICE):FFT0-SET, the number of the first sample of the second FFT ("reference spectrum") by $(DEVICE):FFT-REF0. Calculating differences between FFTs is used for tune measurement at the SLS booster to remove undesired systematic peaks in the spectrum.	bi
$(DEVICE):FFT-REF0	Index of 1st sample for FFT reference data, i.e. for the 2nd spectrum ("reference spectrum") that is subtracted from the 1st spectrum.	longout

Beam Position Data Records (All FIFO Data).

The following waveforms for the four BPM button channels (-A,-B,-C,-D), the beam positions (-X,-Y) and the intensity (-I) and button symmetry error (-ERR) contain all data for samples that were read from the QDR FIFOs, not just for a sample window as the waveforms above (that do not have "-ALL" in their name). The number of words that are read from the FIFOs are adjusted by the NELM fields of the wareform records. In principle all 8192 FIFO samples can be read. However, due to a size limitation in the EPICS Channel Access protocol NELM was chosen smaller than 8192 points.


Record Name	Description	Type
$(DEVICE):WF-ALL-BUT-A	Button A raw values.	waveform
$(DEVICE):WF-ALL-BUT-B	Button B raw values.	waveform
$(DEVICE):WF-ALL-BUT-C	Button C raw values.	waveform
$(DEVICE):WF-ALL-BUT-D	Button D raw values.	waveform
$(DEVICE):WF-ALL-X	X beam positions.	waveform
$(DEVICE):WF-ALL-Y	Y beam positions.	waveform
$(DEVICE):WF-ALL-I	BPM intensities.	waveform
$(DEVICE):WF-ALL-ERR	Button summetry errors.	waveform

Subarrays of Beam Position Data Records

The records below are subArray records of the above ...ALL... waveforms. They are intended for SLS beam dynamics applications that may read part of the BPM data samples independently of the value of $(DEVICE):WF-SMP0-SET (that is usually adjusted by operators via GUIs to scroll through the above "data window" waveforms $(DEVICE):WF-X etc.). The last two records in the table are used to adjust the number of elements to be contained in the subArray records.


Record Name	Description	Type
$(DEVICE):WF-SUB-BUT-A	Subarray for button A raw values.	subArray
$(DEVICE):WF-SUB-BUT-B	Subarray for button B raw values.	subArray
$(DEVICE):WF-SUB-BUT-C	Subarray for button C raw values.	subArray
$(DEVICE):WF-SUB-BUT-D	Subarray for button D raw values.	subArray
$(DEVICE):WF-SUB-X	Subarray of X beam positions.	subArray
$(DEVICE):WF-SUB-Y	Subarray of Y beam positions.	subArray
$(DEVICE):WF-SUB-I	Subarray of BPM intensities.	subArray
$(DEVICE):WF-SUB-ERR	Subarray of button summetry errors.	subArray
$(DEVICE):WF-SUB-NELM	number of elements to be displayed in the above subArray records.	longout
$(DEVICE):WF-SUB-INDX	1st sample to be displayed in the above subarray records.	longout

Single Sample BPM Data Records

The following records are used to read the data of a certain sample in the QDR FIFO. The absolute sample number with respect to the first FIFO sample is determined by the records $(DEVICE):SMP0-SET (relative sample number with respect to a reference sample number) and $(DEVICE):SMP0-REF (determines the reference sample number with respect to the first FIFO sample). The concept of a relative sample number with respect to a reference sample number allows e.g. to read the N-th sample after the beam was injected (reference = 1st sample where the BPM intensity exceeds a user-defined level), independent of the injection trigger delay with respect to the QDR gate trigger.


Record Name	Description	Type
$(DEVICE):BUT-A	Raw value button A.	ai
$(DEVICE):BUT-B	Raw value button B.	ai
$(DEVICE):BUT-C	Raw value button C.	ai
$(DEVICE):BUT-D	Raw value button D.	ai
$(DEVICE):X	horiz. beam position.	ai
$(DEVICE):Y	vertical beam position.	ai
$(DEVICE):I	BPM intensity (sum of the raw values of the four buttons).	longin
$(DEVICE):ERR	BPM button symmetry error.	ai
$(DEVICE):SMP0-SET	Relative QDR FIFO sample number for the above data.	longout
$(DEVICE):SMP0	Readback value.	longin
$(DEVICE):SMP0-REF	Mbbo record that determines the reference sample number that is added to the above relative sample number to obtain the absolute sample number. Possible values of $(DEVICE):SMP0-REF: "ext. trigger": the reference is the 1st FIFO sample ($(DEVICE):SMP0-REF0 = 0) "intens. peak": the reference is the number of the sample with the maximum intensity ($(DEVICE):SMP0-REF0 = $(DEVICE):PEAK-INDEX) "intens. level": the reference is the number of the first sample that exceeds the intensity trigger level specified in $(DEVICE):IMIN-SET".	mbbo
$(DEVICE):SMP0-REF0	Number of the reference sample (readback). The absolute sample number with respect to the first FIFO sample is $(DEVICE):SMP0-REF0.VAL + $(DEVICE):SMP0-SET.VAL.	longin

QDR Carrier Frequency and Gain Control

The records in the table below allow the adjustment of input and output gain of the DDC (Digital DownConverter) ICs of the QDR boards as well as the frequencies of their input mixer NCOs (Numerically Controlled Oscillators). If the record $(DEVICE):QDR-LOCK is set to 1 the QDR driver will ignore the NCO frequency setting and the QDR gains specified in the QDR filter data files. Instead, the QDR driver will use the gains specified in $(DEVICE):IGAIN-SET and $(DEVICE):OGAIN-SET (see table), and it will use the NCO frequency values that are required for signal carrier frequencies of either $(DEVICE):IF-MHZ-SET (beam signal carrier frequency) or $(DEVICE):PI-MHZ-SET (pilot signal carrier frequency). The record $(DEVICE):USE-PILOT is used to switch the QDR NCO between these two frequencies. If the record $(DEVICE):USE-PILOT is set to 0 the QDR NCO is set to the frequency required for the carrier $(DEVICE):IF-MHZ-SET (SLS: 36.029 MHz). If $(DEVICE):USE-PILOT is 1 the NCO will be set to a frequency required for the carrier $(DEVICE):PI-MHZ-SET (SLS: 34.375 MHz). At SLS the input clock frequency of the QDRs is smaller than the carrier frequencies of the QDR RF input signals, i.e. the QDRs use undersampling. Therefore a beam carrier frequency of 36.029 MHz and a clock input frequency of CLKIN=27.7586 MHz (SLS booster) results in an NCO frequency of 8.2704 MHz. In the SLS storage ring CLKIN is 31.2284 MHz, resulting in an NFO frequency of 4.8006 MHz for the beam carrier. In order to calculate the NCO frequencies CLKIN must be specified in the QDR configuration file as explained above.


Record Name	Description	Type
$(DEVICE):IF-MHZ-SET	Beam signal carrier frequency of the QDR signal inputs. Used to program the mixer NCO of the QDR DDC ICs if $(DEVICE):USE-PILOT.VAL = 0.	ao
$(DEVICE):IF-MHZ	Readback value.	ai
$(DEVICE):PI-MHZ-SET	Pilot signal carrier frequency of the QDR signal inputs. Used to program the mixer NCO of the QDR DDC ICs if $(DEVICE):USE-PILOT.VAL = 1.	ao
$(DEVICE):PI-MHZ	Readback value.	ai
$(DEVICE):USE-PILOT	Switch between beam and pilot signal carrier frequency (0=beam, 1=pilot). At SLS this record is switched to 1 for a BPM test or calibration that uses the internal pilot signal generator of the RF frontend rather than the beam signal. A record value of 1 will also cause the driver to ignore the settings for the following records and use internal default values instead: $(DEVICE):NSAMP-SET (set to 1100 if previous value is < 1100) $(DEVICE):IMIN-SET (set to 0) $(DEVICE):PSRCH0-SET (set to 100) These default values allow a reproducible pilot signal calibration without having to adjust the above records manually. When setting $(DEVICE):USE-PILOT to 0 the QDR driver will set the pilot gain to 0, provided that an interface function for RF frontend gain control was specified in the QDRBo_Create command of the IOC startup script. Furthermore the driver will restore the previous set values for the above records.	bo
$(DEVICE):IGAIN-SET	Input gain at the input of the Intersil digital downconverter ICs of the QDR. The input gain control is implemented by a simple bit shifter, therefore the gain can only be incremented in 6 dB steps. Values larger than 0 dB may cause overflows, and not all gain values are not allowed for some QDR filter settings. See Intersil HSP50214B data sheet for details.	mbbo
$(DEVICE):IGAIN	Readback value.	mbbi
$(DEVICE):OGAIN-SET	Output gain of the Intersil digital downconverter ICs of the QDR. Large gain values may cause overflows in the DDC ICs that result in bad output data (with strange oscillations of the four raw values between ~13000 and ~19000). Overflows are avoided by reducing the output gain so that all button raw values are always smaller than ~13000. The output gain can be incremented in 0.1 dB steps (precision ~ 0.01 dB) from 0 to 96 dB.	ao
$(DEVICE):OGAIN	Readback value.	ai
$(DEVICE):QDR-LOCK	If the value of this record is 1 the EPICS QDR driver will ignore the NCO frequency setting and input gain setting in the QDR filter data files that are downloaded to the QDR. Instead, the values of the above records for gains and NCO frequency will be used. If the value of this record is 1 the respective QDR registers for gains and NCO are programmed when the above records are processed or when a filter data file is loaded that contains values for the respective QDR registers (the NCO and gain values of the file will be replaced by the record values). The readback values for gains and NCO frequency always show the last value that was written to the QDR memory, no matter if this was done by setting the above records (with $(DEVICE):QDR-LOCK = 1) or by loading a filter data file (with $(DEVICE):QDR-LOCK = 0).	bo

Intensity Peak Search Records

Values of beam position, button readings and intensity etc. at the QDR FIFO sample with the highest intensity. The peak search is performed from sample number $(DEVICE):PSRCH0-SET to sample number $(DEVICE):NSAMP-SET - 1.


Record Name	Description	Type
$(DEVICE):PEAK-X	X beam position at the intensity peak.	ai
$(DEVICE):PEAK-Y	Y beam position at the intensity peak.	ai
$(DEVICE):PEAK-INDEX	Sample number of the intensity peak.	longin
$(DEVICE):PEAK-A	Raw value of BPM button A at the intensity peak.	longin
$(DEVICE):PEAK-B	Raw value of BPM button B at the intensity peak.	longin
$(DEVICE):PEAK-C	Raw value of BPM button C at the intensity peak.	longin
$(DEVICE):PEAK-D	Raw value of BPM button D at the intensity peak.	longin
$(DEVICE):PEAK-I	Peak Intensity.	longin
$(DEVICE):PEAK-E	Button symmetry error at the intensity peak.	ai

BPM Data Averages

The table below contains average values of beam position, button readings and intensity etc. of the QDR FIFO data. The averaging is performed from sample number $(DEVICE):PSRCH0-SET to sample number $(DEVICE):NSAMP-SET - 1.


Record Name	Description	Type
$(DEVICE):AVG-X	Average horizontal (X) beam position value.	ai
$(DEVICE):AVG-Y	Average vertical (Y) beam position value.	ai
$(DEVICE):AVG-I	Average BPM intensity.	ai
$(DEVICE):AVG-ERR	Average BPM button symmetry error.	ai
$(DEVICE):AVG-A	Average BPM button A raw value.	ai
$(DEVICE):AVG-B	Average BPM button B raw value.	ai
$(DEVICE):AVG-C	Average BPM button C raw value.	ai
$(DEVICE):AVG-D	Average BPM button D raw value.	ai
$(DEVICE):AVG-NSMP	Number of samples that were used for averaging, RMS calculation etc. Samples with to little intensity (below $(DEVICE):IMIN-SET) or with a sample number below $(DEVICE):PSRCH0-SET are not used for averaging etc.	longin

BPM Data RMS Values

The table below contains RMS values of beam position and intensity of the QDR FIFO data. The calculation of RMS values is performed from sample number $(DEVICE):PSRCH0-SET to sample number $(DEVICE):NSAMP-SET - 1.


Record Name	Description	Type
$(DEVICE):RMS-X	X beam position RMS value.	ai
$(DEVICE):RMS-Y	Y beam position RMS value.	ai
$(DEVICE):RMS-I	Intensity RMS value.	ai

Readout Cycle Counters

The table below contains "longin" records that count the number of QDR FIFO readout cycles that fulfill certain conditions. As explained above a FIFO readout cycle is triggered by external gate triggers of the QDR, provided that the processing of the last readout cycle is finished and the FIFO is empty (again). If the readout is switched on ($(DEVICE):SW-SET = 1) and the QDR is enabled ($(DEVICE):ENABLE-SET = 1) the FIFO data is read and processed. However, the EPICS records with "I/O Intr" as SCAN field value are only triggered if the intensity (sum of the raw values of the four buttons) is at least $(DEVICE):IMIN-SET for at least one of the FIFO samples that have a sample number above $(DEVICE):PSRCH0-SET. However, in gain calibration mode ($(DEVICE):USE-PILOT = 1) the records are triggered for every readout cycle.


Record Name	Description	Type
$(DEVICE):NCYC-BEAM	The record is incremented by 1 for every QDR FIFO readout cycles that has a beam intensity above the theshold $(DEVICE):IMIN-SET. The value of the record is not incremented in gain calibration mode (i.e. is it not inremented when $(DEVICE):USE-PILOT is set to 1).	longin
$(DEVICE):NCYC-GCAL	No. of QDR FIFO readout cycles with the EPICS records in "I/O Intr" SCAN mode being triggered. Simular to $(DEVICE):NCYC-BEAM, only incremented in gain calibration mode (i.e. when $(DEVICE):USE-PILOT is set to 1).	longin
$(DEVICE):NCYC-ANY	This record is incremented for any BPM readout cycle with sufficient intensity (gain calibration mode or not)	longin
$(DEVICE):NCYC-FIFO	The record is incremented each time the FIFOs of the BPMs were read, for any intensity and for any mode (gain calib. mode or not)	longin

RF Frontend Gain Control Records

Gain control for the BPM RF frontends. Will only work if a gain control function was specified in the QDRBo_Create command in the IOC startup script (see section Gain Calibration File above).


Record Name	Description	Type
$(DEVICE):GAIN-P-SET	pilot signal gain.	longout
$(DEVICE):GAIN-P	Readback value.	longin
$(DEVICE):GAIN-A-SET	Gain BPM button A.	longout
$(DEVICE):GAIN-A	Readback value.	longin
$(DEVICE):GAIN-B-SET	Gain BPM button B.	longout
$(DEVICE):GAIN-B	Readback value.	longin
$(DEVICE):GAIN-C-SET	Gain BPM button C.	longout
$(DEVICE):GAIN-C	Readback value.	longin
$(DEVICE):GAIN-D-SET	Gain BPM button D.	longout
$(DEVICE):GAIN-D	Readback value.	longin
$(DEVICE):GAIN-AVG-SET	If this record is set, the gains of the four BPM buttons will be set to values calculated from gain calibration data in the QDR configuration file via linear interpolation between the gain values provided in this file. The calibration data in the file consists usually of several lines. Each line should consist of an average RF gain and the gains for the buttons A,B,C,D that are required to obtain four identical button readings if the RF input power for the buttons is identical for a certain pilot signal level. Due to nonlinearities in the RF frontends, the linear interpolation between the different gain settings results in an offset for the calculated x/y beam positions that may become quite large if the spacing between the average gains in the calibration file is large. A typical position error of some 10 microns max. due to the interpolation (for the SLS booster) requires calibrations at least every 500 digits for gains between 10000 and 30000 and at least every 1000 digits for gains above 30000.	longout
$(DEVICE):GAIN-AVG	Readback value.	longin

QDR Filter Data Records

The readonly records in the table below provide information about the filter settings of a QDR. All values in this section (decimation factors, frequencies) are obtained by parsing the QDR filter data file when it is loaded into the QDR memory, therefore at least one file must be loaded after reboot before the records provide valid data.


Record Name	Description	Type
$(DEVICE):CLKIN-MHZ	QDR front panel CLKIN frequency as specified in the QDR configuration file. All other frequencies are calculated from this one.	ai
$(DEVICE):FIFOCLK-HZ	Clock frequency of the QDR FIFO data clock. The fifo is filled with this clock rate. This record can only display frequencies up to 2.147 MHz (because it has a resolution of 1E-3 Hz and uses a 32 bit integer). Use $(DEVICE):DECIM-ALL and $(DEVICE):CLKIN-MHZ to calculate higher FIFOCLK frequencies.	ai
$(DEVICE):DECIM-CIC	Decimation factor of the DDC CIC filter.	longin
$(DEVICE):DECIM-HB1	Decimation factors of the halfband filter 1 .	longin
$(DEVICE):DECIM-HB2	Decimation factors of the halfband filter 2 .	longin
$(DEVICE):DECIM-HB3	Decimation factors of the halfband filter 3 .	longin
$(DEVICE):DECIM-HB4	Decimation factors of the halfband filter 4 .	longin
$(DEVICE):DECIM-HB5	Decimation factors of the halfband filter 5 .	longin
$(DEVICE):DECIM-FIR	Decimation factor of the FIR filter .	longin
$(DEVICE):DECIM-ALL	Overall decimation factor of the DDC chip.	longin

File Access Records


Record Name	Description	Type
$(DEVICE):QDRNAME	Name of the QDR as specified in the QDRBo_Create command in the startup script.	stringin
$(DEVICE):GAINFILE	Writing the name of a gain calibration file to this record will load the file. All previously loaded gain calibration data will be discarded, and the QDR driver will use the new file to calculate the RF frontend gain DAC settings from the average gain DAC setting given in $(DEVICE):GAIN-AVG-SET. Set the PINI field of this record to 0 in the template file if you do not use gain calibration files, otherwise a (harmless) error message will occur when the record is processed after reboot and cannot field the file specified in the VAL field.	stringout
$(DEVICE):CONFFILE	Writing the name of a QDR configuration file to this record will load the file and thus overload the QDR config. file that was loaded in the IOC startup script. The record may be used to load new QDR filter data files without rebooting the IOC.	stringout
$(DEVICE):GAIN-UPD	Writing a "1" to this record will reread the gain calibration file that was specified in the record $(DEVICE):GAINFILE.	bo

BPM Error Detection Records

The records in the table below allow the detection of BPM button symmetry errors that may be caused by a broken BPM cable or by faulty electronics for one (or more) of the four BPM signals A,B,C,D. The button symmetry error is defined as

AVG_SYM_ERR = Average (||A+C|-|B+D|| / (A+B+C+D))

The average is calculated using all valid QDR FIFO raw values A,B,C and D of the four BPM buttons. The value of AVG_SYM_ERR is stored in the record $(DEVICE):AVG-ERR. The records in the table below allow the BPM readout to be switched of automatically when AVG_SYM_ERR for all valid QDR FIFO samples exceeds a predefined level. If all four BPM channels are O.K. and the beam is centered the value should be ~ 0. If one of four BPM cables is broken and the other three cables deliver identical beam signals the value of AVG_SYM_ERR is ~ 0.33. The error detection uses the average error instead of the symmetry error of each FIFO sample in order to avoid phony symmetry errors due to spikes or noise of a single sample. However, the symmetry errors for each FIFO sample may nevertheless be read via the records $(DEVICE):WF-ERR, $(DEVICE):WF-ALL-ERR and $(DEVICE):WF-SUB-ERR (waveforms) and $(DEVICE):ERR (analog input). It should be noted that the error detection is disabled in gain calibration mode (i.e when $(DEVICE):USE-PILOT is set to 1).


Record Name	Description	Type
$(DEVICE):EDET-SW	Enable/disable BPM button symmetry error detection.	bo
$(DEVICE):EDET-AUTO	If this record is set to 1 the BPM will be disabled (equivalent to setting $(DEVICE):ENABLE-SET to 0) by the driver if a symmetry error is detected. It can be enabled again (after being repaired) by setting $(DEVICE):ENABLE-SET to 1.	bo
$(DEVICE):EDET-LEV	Threshold of `AVG_SYM_ERR`=\|\|A+C\|-\|B+D\|\|/(A+B+C+D) for the detection of BPM button symmetry errors. The value should be large enough (0.1 to 0.2 is usually O.K.) in order to avoid phony symmetry errors due to extremely off-centered beams.	ao
$(DEVICE):EDET-IMIN	Min. BPM intensity (= sum of raw values of the 4 BPM readings from the 4 QDR FIFOs) that is required to detect BPM button symmetry errors.FIFO samples below the threshold are ignored. Avoids phony symmetry errors when the button readings are very low (e.g. 0 or 1).	longout
$(DEVICE):EDET-N	Counter for BPM button symmetry errors. Incremented by 1 for every QDR FIFO readout that resulted in an average symmetry error above the treshold $(DEVICE):EDET-LEV. The counter is only incremented as long as the BPM is enabled, therefore the counter is incremented only once when $(DEVICE):EDET-AUTO is 1 and an error is detected. The counter is reset to 0 when $(DEVICE):EDET-SW is switched to 0 or via $(DEVICE):EDET-RES.	longin
$(DEVICE):EDET-FLAG	Button symmetry error flag. The VAL field is and remains 1 if BPM button symmetry error was detected. Reset to 0 via $(DEVICE):EDET-RES or by switchting $(DEVICE):EDET-SW to 0.	bi
$(DEVICE):EDET-RES	Write 1 to this record to reset the button symmetry error detection flag & counter.	bo

IOC Names & Locations

The following table contains IOC names, rack numbers and BPM names of the SLS booster:


IOC	DI RACK	BPMs (ABODI-BPM-...)
ABODI-VME-BPM1	.19.0.14	6G, 6H, 6S, 1S, 1H, 1G
ABODI-VME-BPM2	.24.0.3	1F, 1E, 1D, 1C
ABODI-VME-BPM3	.28.0.3	1B, 1A, 2A, 2B
ABODI-VME-BPM4	.31.0.3	2C, 2D, 2E, 4F
ABODI-VME-BPM5	.37.0.12	2G, 2H, 2S, 3S, 3H, 3G
ABODI-VME-BPM6	.42.0.3	3F, 3E, 3D, 3C
ABODI-VME-BPM7	.48.0.3	3B, 3A, 4A, 4B
ABODI-VME-BPM8	.50.0.3	4C, 4D, 4E, 4F
ABODI-VME-BPM9	.55.0.21	4G, 4H, 4S, 5S, 5H, 5G
ABODI-VME-BPM10	.2.0.3	5F, 5E, 5D, 5C
ABODI-VME-BPM11	.6.0.12	5B, 5A, 6A, 6B
ABODI-VME-BPM12	.14.0.17	6C, 6D, 6E, 6F

SLS Booster DBPM System

Contents

Introduction