Epics driver for Libera Electron Beam Position Monitor (EBPM)

This software provides an EPICS interface to the Libera electron beam position monitor, allowing the performance of the electron beam to be monitored through EPICS channels.

This version of the EPICS driver is designed to work with with any version of the Libera device driver from 1.46 up to and including version 2, as distributed by Instrumentation Technologies, http://www.i-tech.si, and has been built to support the operation of the Diamond light source, http://www.diamond.ac.uk.

The normal distribution point for this software is the Diamond controls download site, from http://controls.diamond.ac.uk/downloads/libera.

The author, Dr. Michael Abbott, can be contacted at Diamond Light Source at michael.abbott@diamond.ac.uk.

To be notified of updates to this software please subscribe to the EPICS tech-talk mailing list http://www.aps.anl.gov/epics/tech-talk/index.php.

Do please read the following attached files:

COPYING
This contains the standard GNU license, and all files in this release are distributed under this license.
INSTALL.{txt,html}
Read this file for installation instructions using the pre-built distribution.
CHANGES.{txt,html}
Records the change history of this driver.

This release of the Libera EPICS driver provides the following functionality:

First Turn Data
This is designed for monitoring transfer paths and behaviour during injection of the first turn into a synchrotron. A hardware trigger is required a few microseconds before the event.
Turn-by-turn Data
Very long waveforms (up to 524,288 points) can be captured on a hardware trigger and then read out in 32768 point segments. This is designed specifically for tune measurements at frequencies up to 1/2 the synchrotron revolution frequency, and for detailed noise investigations.
Booster Ramp Data
Waveforms are provided giving an overview of the booster ramp. This is done by reducing 100ms of ramp data to two sample rates: 1/1024 turn frequency, and 1/64 turn frequency.
Slow Acquisition Data
The electron beam position is filtered down to an update rate of 10Hz. Automatic button switching should be enabled for high precision slow acquisition data.
Postmortem Data
On receipt of a postmortem trigger a dedicated 16384 point buffer of turn-by-turn data preceding the trigger is captured.
Interlock Control
A hardware interlock output is generated by Libera to confirm that the electron beam position is within a configured window: this is designed for machine protection.
Clock Control
Correct synchronisation and detuning of the Libera sample clock to the machine clock is essential for accurate operation, and for fast feedback operation it is necessary for all clocks to operate synchronously. The clock control PVs allow control over the clock.

All Libera EPICS records follow a uniform naming convention of the form

<device>:<group>:<record>

where:

<device>
is normally derived from the host name of the EPICS IOC, but can be configured to any string at startup.
<group>
is the major function (FT = "First Turn", etc.)
<record>
is the remainder of the record name as specified below.

In the list of records below we use a number of abbreviations:

<channel>
Refers to four channel numbers 1, 2, 3, 4 corresponding to four input RF processing channels. The correspondence between channel and buttons depends on the multiplexer switch setting.
<iq>
refers to eight names AI, AQ, BI, BQ, CI, CQ, DI, CQ referring to button values in quadrature (typically at turn-by-turn rate).
<buttons>
refers to four names, A, B, C, D, referring to the four beam position monitor buttons.
<positions>
refers to four names, X, Y, Q, S referring to the computed electron beam position (X, Y), a skew factor (Q) and the total beam intensity (S). The intensity S is in arbitrary units, normally scaled to 0.5822*231 full scale; the positions are in nm for waveforms and in mm for single points. The skew factor is unscaled with maximum value +-1.
<axis>
refers to the two names, X, Y only.
..._S

Records of the form <name>_S are used to write values into the driver. Many of these written values are remembered over IOC restart, these are all marked with a * in the list below.

The persistent variables are stored between restarts in the file /opt/state/<device>.state.

The following documents all of the Libera EPICS records used in the operation of Libera.

First Turn (<group> = FT)

RAW<channel>

Unprocessed ADC readings, one per input channel: 1024 points at approximately 8.5ns sample intervals. The permutation between channel and button depends on the switch position.

Note that the ADC readings are adjusted to 16 bits full scale independently of the actual full scale range of the ADC.

MAXADC, MAXADC_PC
Maximum ADC reading in the entire 1024 point capture, across all channels, both as a raw 16-bit ADC value and as a percentage of full scale.
WF<buttons>
256 point arrays at approximately 34ns sampling interval, updated on trigger.
WF<positions>
Estimated intra-turn positions computed from the WF<buttons> array and thresholded for sensible display: all X, Y and Q for positions where S < MAXS/2 are set to 0.
MAXS
Maximum S value over the WFS array.
<buttons>
Button values integrated within the window specified by OFF and LEN.
<positions>
Position data derived from <buttons>, in mm.
OFF_S*, LEN_S*
These two fields determine the window within WF<buttons> used to compute the integrated <buttons> values.
ENABLE_S*
If set to Disabled then FT processing will not occur.
CHARGE
Train charge as integrated within the integration window, and scaled by CF:ISCALE.
AXIS
Waveform in microseconds that can be used to label WF<...> waveforms.

Free Running (<group> = FR)

WF<iq>, WF<buttons>, WF<positions>
2048 point arrays updated on each trigger at turn-by-turn frequency.
DELAY_S
Configures the delay in samples from the trigger to the first captured point. A negative delay can be used for "pretriggering", ie to capture turn by turn data before the trigger.
ENABLE_S*
If set to Disabled then FR processing will not occur.
MEAN<axis>, STD<axis>, MIN<axis>, MAX<axis>, PP<axis>
The mean, standard deviation, minimum and maximum value and peak-to-peak deviation are computed over each FR waveform and reported in microns.

The following PVs are used to calculate the component of a selected frequency (ideally the tune frequency) in the position waveform. Normally these values are only meaningful if the tune frequency is correctly set and the beam is being excited at this frequency.

TUNE<axis>_S
This sets the frequency being probed by the PVs below. This frequency is in units of revolution frequency and can be set to any value between 0 and 0.5.
TUNEI<axis>, TUNEQ<axis>, TUNEMAG<axis>, TUNEPH<axis>

A sine and cosine waveform at the selected probe frequency is mixed with the X and Y waveforms to compute I and Q components, in nm, and the corresponding magnitude MAG, also in nm, and phase PH in degrees.

Note that the DC component is subtracted from the computed sine and cosine (with some integer rounding) and that thus the response at low frequencies is reduced: indeed, the response at TUNE<axis>_S = 0 is zero.

The following PVs are used to control the averaging of a sequence of FR waveforms. This can be useful if a sequence of repetitive experiments is being done, for example kicking the beam for machine physics investigations. Averaging is done by accumulating A, B, C, D waveforms. Note that the IQ waveforms are not affected by this processing at all and always show the most recent update (this is becase the IQ data from shot to shot is not coherent).

The default condition is AVERAGE_S = 1, AUTOSTOP_S = 0, which means that each waveform is displayed separately without any averaging.

AVERAGE_S
The number of waveforms in a single full update can be any power of 2 in the range 1 (20) to 65536 (216) -- this PV should be set to the corresponding superscript. A value of 0 causes every update to be displayed and processed normally.
ALLUPDATE_S
If this PV is set to 0 then the waveform and statistics will only be updated when all configured samples have been captured, otherwise every sample is shown.
SAMPLES
During accumulation of the waveforms this number counts up to the selected number of samples, 2^AVERAGE_S as triggers are received. This PV updates even if ALLUPDATE_S is set to 0.
AUTOSTOP_S
This PV configures what to do when a complete round of averaged waveforms has been captured. If set to 0 then a new round of samples will automatically start at the next trigger, otherwise RESET_S needs to be processed to trigger another round of capture.
RESET_S
Clears the currently averaged waveforms and restarts a fresh round of averaging. Note that writing to AVERAGE_S also has the same effect as processing this PV.

Turn by Turn (<group> = TT)

ARM
1 must be written to this record to enable capture of a full turn-by-turn waveform at the next trigger.
READY
This record becomes set to 1 when a waveform has been captured.
CAPLEN_S
Programs the number of points to be captured into the internal long waveform. A maximum of 524,288 points can be specified.
CAPTURED
Records how many points were captured. At Diamond's booster frequency (1.893MHz) something over 524,288 points can be reliably captured.
OFFSET_S, OFFSET
Used to set the offset into the long buffer for reading out waveforms, together with read-back used for synchronisation. Note that if channel access "put with callback" is used it is not necessary to check the readback.
LENGTH_S, MAXLENGTH
Used to set how many points are read from the long buffer. The default (and maximum) value is returned by MAXLENGTH, with default value 131072.
WF<iq>, WF<buttons>, WF<positions>
Waveforms of up to LENGTH_S points read from the internal captured long waveform using the specified OFFSET and LENGTH.
MEAN<axis>, STD<axis>, MIN<axis>, MAX<axis>, PP<axis>
Waveform statistics, as for FR, measured over the current window.
TUNE<axis>_S, TUNEI<axis>, TUNEQ<axis>, TUNEMAG<axis>, TUNEPH<axis>
Tune response, as for FR, measured over the current window.
DELAY_S
Just as for FR:DELAY_S, allows the delay from trigger to sampled data to be configured.
DECIMATION_S

This can be set to "1:1" or "1:64" -- in the latter case FPGA decimated data will be captured at one point per 64 turns.

Take care with decimated data: due to a device driver bug it is possible to make Libera hang if CAPLEN_S is set to values much larger than 32,000.

DOREFRESH_S

When this is set to 1, ("Update Data") every time a full turn-by-turn waveform is captured the windowed waveforms are also updated. Unfortunately when capturing large waveforms (CAPLEN_S > LENGTH_S) this can result in wasted processing time as first window is often simply discarded.

As an optimisation this PV can be set to 0 ("Stale Data"): in this case the windowed waveforms will only update when OFFSET_S is processed. Note that processing a full 131072 point window takes about 1 second.

The following protocol should be used when using this group of records. First the record must be armed, and then the trigger should be waited for. Segments should then be read by writing the offset and waiting for it to update before reading. To be explicit:

Triggering:

Reading:

If CAPLEN > LENGTH_S then the reading process should be repeated with <offset> set to 0, LENGTH_S, 2 * LENGTH_S, etc until the entire desired waveform has been retrieved.

The maximum window readout length of MAXLENGTH can be be modified at IOC start time by editing the configuration setting IOC_TT_WINDOW in the epics_ioc configuration file (installed in one of the directories /etc/sysconfig, /etc/defaults, /etc/libera depending on target architecture).

Booster (<group> = BN)

WF<iq>, WF<buttons>, WF<positions>
Decimated waveforms reduced from turn-by-turn frequency by a factor of 64, updated on each trigger. The length of each waveform is equal to 16 times the value IOC_BN_LENGTH, as defined in epics_ioc.
WFS<positions>
Decimated waveforms reduced from turn-by-turn frequency by a factor of 1024, equal in length to IOC_BN_LENGTH.
ENABLE_S*
If set to Disabled then BN processing will not occur.
AXIS, AXISS
Waveforms used to label position graphs. These are constant ramping waveforms in units of milliseconds.

Note that if BN processing is enabled then care should be taken to ensure that 1024*IOC_BN_LENGTH divided by machine revolution frequency is no longer than the interval between triggers, otherwise triggers will be lost.

Slow Acquisition (<group> = SA)

<buttons>, <positions>
Averaged button readings and positions updating at approximately 10Hz.
<buttons>N
Averaged button readings normalised by mean intensity. Useful for observing button drift in the presence of beam decay.
POWER
Absolute input power in dBm. The scaling here is hard-wired and not particularly accurate.
CURRENT
Beam current. This is scaled by CF:ISCALE.
MAXADC, MAXADC_PC
Maximum ADC reading over a single SA interval (approximately 100ms). This is a true maximum ADC value, but requires a Diamond specific register to be implemented in the FPGA.

Postmortem (<group> = PM)

WF<iq>, WF<buttons>, WF<positions>
16384 point postmortem waveforms of turn-by-turn data captured up to the point of the postmortem trigger.
<axis>_OFFSET, <axis>_OFL, ADC_OFFSET, ADC_OFL

Offset of the first turn in the waveform buffer where the selected interlock overflow event occurred (X position, Y position or ADC reading), together with a flag to indicate whether the overflow was seen at all in the buffer.

If overflow is seen at the first point the corresponding _OFFSET is set to 0; if no overflow is seen then _OFFSET is set to 16384 (the buffer length) and _OFL is false.

FLAGS

16384 point waveform of flags extracted from the bottom bit of each of the WF<iq> waveforms. The bits are numbered (from lsb to msb) thus:

0:Switching synchronisation flag
1:ADC overflow
2:X interlock error
3:Y interlock error

The remaining four bits repeat the same sequence.

MODE_S*, REARM_S, READY
Postmortem triggering can be configured for one-shot triggering if desired by setting MODE_S to "One Shot". In this mode READY indicates whether PM trigger will be captured, and REARM_S must be processed to re-enable capture once a postmortem has been captured.
OFFSET_S*
If a version 2 driver is installed then the postmortem trigger delay can be configured.

If a version 2 FPGA is installed then postmortem triggering can be configured from multiple sources:

SOURCE_S*
Configures the postmortem trigger source, can be one of "External" for normal triggering from the hardware PM trigger, "Interlock" to trigger on an interlock drop event, or "Settings" to trigger on the trigger settings below.
MAX<axis>_S*, MIN<axis>_S*, TIME_S*, OVER_S*, OVER_PC_S
These settings are the same as the correspong IL interlock settings, and configure the operation of the internally generated postmortem trigger when SOURCE_S is set to "Settings". These settings are not designed for general use.

Triggered Mean Sum (<group> = MS)

The following PVs provide access to current averaged between triggers. This is only available with a version 2 FPGA.

ENABLE_S*
Enables processing of mean sum calculations. The calculations are low cost, so there is little reason to disable this.
COUNT
Number of samples (in FA samples, approximately 10kHz) in this capture.
MEANS, MEANP, MEANI
Mean sum (in arbitrary units, equivalent to SA:S), input power (in dBm, subject to calibration), and computed current (as configured by CF:ISCALE_S) between the last two triggers.
DELTAS, DELTAI
Change in mean sum and computed current over the last three triggers.

Interlock Control (<group> = IL)

ENABLE_S
If this is set to Disabled the interlock output is held active, or closed (unless OVERFLOW_S is also set to Enabled to enable overflow detection). When set to Enabled the interlock output is only active while the beam position lies within the interlock window.
IOFF_S*, ION_S*
Interlock checking is automatically disabled when the observed current (as reported through SA:CURRENT) is below IOFF_S, and is automatically enabled when the current is above ION_S. This function overrides ENABLE_S, but is overridden by the global CF:ENABLED_S setting.
MIN<axis>_S*, MAX<axis>_S*
Interlock window: when the interlock is enabled the interlock output is closed ("active") so long as the beam position lies within this window.
MIN<axis>2_S*, MAX<axis>2_S*, WINDOW
Secondary interlock window settings, only meaningful if VE:ILK2 indicates that secondary interlock support is present in the FPGA. In this case an external hardware signal (received on RS232 port #2) determines which interlock window is in force, and WINDOW indicates this.
OVER_S*, OVER_PC_S, TIME_S*
ADC overflow detection parameters: the interlock is dropped if the ADC input exceeds value OVER for at least TIME samples. The overflow threshold can be set as a 16 bit number (using OVER_S) or as a percentage of full scale (using OVER_PC_S).
IIRK_S*
This is a one pole IIR filter applied to ADC readings before ADC overflow detection is applied. The coefficient K corresponds to a pole at 1-2-K per sample for K in the range 0..6.
OVERFLOW_S*
This can be set to Enabled to enable ADC overflow detection even when the interlock is otherwise disabled.
STATE
STATE records whether the interlock is currently dropped or has been dropped within the last 0.5 seconds.
HOLDOFF_S*, IHOLDOFF_S*
When the attenuator setting is changed there is normally a small glitch in position which can unfortunately cause the interlock to be lost. These two settings are used to control a window during which the interlock is disabled after the attenuator setting is changed. The units are in 1/10 second.
REASON

When an interlock check is reported this PV records the interlock reason bits with the following meanings:

1:overflow in X
2:overflow in Y
8, 16:ADC overflow

This field should be manually set to zero after the interlock reason has been recorded.

TEST_S
Setting this PV to "Interlock Test" will unconditionally force the interlock output to be open. This overrides the action of ENABLE_S.

Configuration (<group> = CF)

ENABLED_S*
Configures whether the BPM is "enabled". If disabled then position interlock checking is disabled.
DIAG_S*
Configures button or stripline orientation. This affects the calculation of X and Y positions from A, B, C, D button readings. Note that the fast feedback data stream is not affected by this and assumes the "Diagonal" orientation: this also applies to interlock checking.
K<axis>_S*
Scaling factors in mm. These are determined by the physical geometry of the button or stripline pickups. At Diamond typical values are 17mm for the transfer path striplines and 10.6mm and 11mm (horizontal and vertical) for the booster buttons.
Q_0_S*
This is used to set the zero offset for the "skew" measurement. Large deviations from the zero point are a good diagnostic of electrical or button faults, as the skew does not normally change by much during normal beam movements.
BBA_<axis>_S*, BCD_<axis>_S, GOLDEN_<axis>_S*

Offsets on the position reported by the BPM are divided into three stages. First it is assumed that the nominal centre of the BPM will be discovered by a process of "beam based alignment": this produces offsets that should be written into the BBA_... PVs.

Note, however, that both changes to beam current and attenuator settings will result in perceived movement of the beam: this is compensated for by "beam current dependent" offsets. These are designed to be written into the BCD_... PVs.

Finally, if it is desired to introduce local bumps or other deviations from the nominal beam orbit, to ensure that the positions reported by the BPMs are purely errors (this helps with feedback correction, for example), the GOLDEN_... PVs are designed to be programmed with the value of such offsets.

Note that the BCD offsets are not persistent between Libera restarts.

G0_S*, G1_S*, G2_S*, G3_S*
Gain offsets can be set for individual RF channels to compensate for channel imbalances within Libera. This is only useful in FT mode, and is not recommended.
AUTOSW_S*
Controls automatic cycling of switches with "signal conditioning", for sub-kHz position measurements, or fixed switch positions for high frequency measurements.
TRIGSW_S*, DELAYSW_S*
These control the synchronisation of the multiplexing switch. If TRIGSW_S is set to "External" then the switch rotation will be synchronised to the external machine clock, in which case DELAYSW_S can be used to configure the delay from machine clock to rotation (in sample clock units).
SETSW_S*
Switch position to use when AUTOSW_S is set to "Fixed".
PERM

Switch permutations: when AUTOSW_S is set to Manual this can be used to convert the FT:RAW<channel> readings into buttons according to the rule

value at <button> = FT:RAW<FT:PERM [<button>] + 1> (A =0, ... D =3)

DSC_S*
Configures the operation of "signal conditioning" processing: this controls channel gains during automatic rotation of the multiplexing switch.
ATTEN_S*, ATTEN:DISP_S*

These two settings are added together to control the attenuator setting in dB. The final setting can be a value between 0 and 62dB for Libera Electron or between 0 and 31dB for Libera Brilliance.

The ATTEN:DISP_S setting can be set to any value between -62 and +62, while ATTEN_S is limited to the range 0 to 62 -- true attenuator settings will be clipped to the range supported by the machine.

These two settings are designed so that the same global attenuator setting can be written to ATTEN_S on all Liberas on a machine and individual Libera characteristics can be accounted for by setting individual offsets into ATTEN:DISP_S. This is particularly useful if Electron and Brilliance Liberas are mixed on the same system.

ATTEN:OFFSET_S*
Waveform of corrections for attenuator settings, one entry for each possible attenuator setting (63 for Libera Electron, 32 for Libera Brilliance). Affects SA:POWER, SA:CURRENT and CF:ATTEN:TRUE calculations.
ATTEN:TRUE
This reports the set attenuation taking into account the programmed attenuation, the configured displacement, clipping to a valid value, and the offset waveform.
ISCALE_S*
Nominal beam current at 0dBm input power as seen by Libera. This is used to compute SA:CURRENT and FT:CHARGE.
NOTCHEN_S
For certain machine physics investigations it can be helpful to turn off the notch filters in the fast feedback stream. Note that fast feedback will not work properly when this is disabled!
NOTCH1_S, NOTCH2_S

Five point waveforms providing direct access to the two notch filters in the FA stream. The programmed notch filter is

(a0 + a1 z-1 + a2 z-2) / (217 + a3 z-1 + a4 z-2)

where an is the nth coefficient of the waveform. These filters are initialised from the files notch1 and notch2 in the /opt/lib directory on Libera.

FIR_S
Waveform for controlling the FA FIR decimation filter. The length of this filter is 3 times the FA FIR decimation, as indicated by VE:FAFIR. For a consistent power level the sum of the coefficents should be 217. This filter is initialised from the file /opt/lib/polyphase_fir.
RESETFA_S
When processed this resets the three FA filters NOTCH1_S, NOTCH2_S and FIR_S to their original default values by reloading the corresponding /opt/lib files.
TRIGDLY_S*
This can be used to generate an internal delay on the Libera trigger, and can be set to any number between 0 and 2047. The delay is in Libera sample clocks, or steps of approximately 8ns. This setting is not particulary useful.
ATTEN:AGC_S*, ATTEN:AGC:UP_S*, ATTEN:AGC:DN_S*

If ATTEN:AGC_S is set to "AGC on" then a simple form of automatic gain control is enabled: this will only work on a version of Libera with a working SA:MAXADC reading.

Every 100ms the field SA:MAXADC_PC is compared with ATTEN:AGC:UP_S and ATTEN:AGC:DN_S. If the reading is too high then the attenuator setting ATTEN_S is incremented by 1dB, if too low then it is decremented by 1dB. This results in a quick tracking (10dB/s) of beam intensity within the configured limits.

The following configuration options are only available if a version 2.0 or higher FPGA is loaded.

SR:ENABLE_S*

The "spike removal" feature removes some of the switching transients from the fast feedback stream before down filtering -- this can significantly reduce the impact of switching artifacts. This PV controls whether this feature is enabled.

Note that although spike removal is performed on turn by turn data, it does not affect the normal turn by turn waveforms (FR, TT, PM, BN).

SR:AVESTOP_S*, SR:AVEWIN_S*, SR:SPIKEST_S*, SR:SPIKEWIN_S*
These settings control the operation of spike removal.
SR:DEBUGWF
This waveform allows the effect of spike removal to be viewed on one data stream (button A magnitude). To update this waveform either manually process it or set its .SCAN field to a suitable value.

Clock (<group> = CK)

TIMESTAMP_S*
Libera provides an internal system clock synchronised to an external 1MHz reference which can be used to provide precision timestamps. If this PV is set to "System time" then this will be used, otherwise the Linux system time (which should be synchronised by NTP) is used.
DETUNE_S*
This controls the detuning of the sample clock away from a precise integer multiple of the machine clock. A substantial detune (in the order of 100 or more) is recommended to avoid harmonic beating. A detune of 1 translates to a frequency shift of approximately 10Hz.
IFOFF_S*
This should be left set to zero.
PHASE_S*
This controls the phase of the filter reducing raw sampled waveforms down to turn-by-turn data relative to the machine clock -- but only when DETUNE_S is equal to zero, of course!
MC_SYNC_S
Processing this PV enables global machine clock synchronisation: on the next trigger Libera will reset the machine clock counter to zero and define a reference point for fast feedback generation. Over the next few seconds the machine clock will be slewed to ensure that all fast feedback (and turn-by-turn) processing is synchronised to the trigger point.
SC_SYNC_S

Processing this PV enables system clock synchronisation: on the next trigger Libera will synchronise its internal timestamp counter with the external trigger.

For this to work correctly two assumptions need to be satisfied: firstly, the external trigger is assumed to occur on the true start of the second; secondly, the local Linux system timestamp must already be accurate to with a few 100ms (this can be achieved using NTP).

Note: a 1Hz trigger can be used for system clock synchronisation. Note also, however, that the current implementation of the system time clock does not hold synchronisation long enough for this synchronisation to be worth doing, instead TIMESTAMP_S should be set to use NTP time.

MC_LOCK, SC_LOCK
Records whether the machine clock (MC_LOCK) or system timestamp clock (SC_LOCK) is currently locked to the external reference. The machine clock will report "Slewing" if the phase error is larger than 1 sample clock, but lock is not lost in this case.
MC_SYNC, SC_SYNC
Records whether the machine clock (MC_SYNC) or system timestamp clock (SC_SYNC) is currently synchronised to a global trigger. Synchronisation is lost whenever the corresponding clock becomes unlocked. Machine clock synchronisation is also lost when the detune (DETUNE_S) changes, and this release does not track system clock synchronisation over restarts of the EPICS IOC.
MC_DAC, SC_DAC
Readback of the currently machine and system clock VCXO settings. This is very sensitive to both temperature and frequency changes, and can provide a useful diagnostic.
MC_PHASE_E, SC_PHASE_E
Current machine and system clock phase errors. During normal operation MC_PHASE_E is 0+-1 unless the machine frequency changes very rapidly, and SC_PHASE_E should only be 0+-1.
MC_FREQ_E, SC_FREQ_E
Frequency error. Normally zero.
VERBOSE_S
Controls whether the values _DAC, _PHASE_E and _FREQ_E are reported for MC and SC. As these values are not normally useful and cost processing resources to generate, by default this is disabled.
OPEN_LOOP_S, MC_DAC_S, SC_DAC_S
These PVs are provided for studying the behaviour of the VCXO. If OPEN_LOOP_S is set to 'Open Loop' then the PLL controllers are disabled and writing to MC_DAC_S and SC_DAC_S will directly control the VCXO control voltage.
HEALTH
This PV provides a report of the overall health of the clocks by aggregating LOCK_MC, LOCK_SC and SYNC_MC. At present SYNC_SC is not included in this aggregation.
TICK
Counts the number of seconds (in 0.1s steps) since the last trigger, and records an alarm state if the delay is more than 1 second.
MISSED, MISSED_ALL, MISSED_PC, TICK_COUNT, RESET_CNTRS
These PVs are designed to be used to provide an indication of how many triggers are being missed. TICK_COUNT counts the total number of triggers reported by the low level driver, and MISSED_ALL accumulates triggers that are not processed by Libera EPICS. Processing RESET_CNTRS will set these counters to zero synchronously.
MCH, MCL
The machine clock of the last trigger: the number of machine revolutions since machine synchronisation (MC_SYNC). MCL contains the bottom 31 bits of the counter and MCH the remaining bits (note: 31 bits are used as EPICS integers are signed).
TIME_NTP, TIME_SC
Both NTP and system clock time for the last trigger formatted as UTC strings in ISO 8601 date and time formats.
NTPSTAT, STRATUM, SERVER

These three PVs monitor the status of the NTP client running on Libera. NTPSTAT can be one of the following values:

Not monitored:NTP monitoring has been disabled
No NTP server:We don't appear to be running an NTP client at all
No Sync:The local NTP client isn't synchronised to an NTP server. (This can mean that synchronisation is in progress, this can take up to 20 minutes.)
Synchronised:Libera is correctly synchronised to an NTP server.

STRATUM records the distance of Libera (in server hops) from the NTP synchronisation source (16 means not synchronised), and SERVER identifies the NTP server to which we are synchronised.

Sensors (<group> = SE)

TEMP, TEMP_MB, TEMP_RF1, TEMP_RF2

Internal Libera temperatures. TEMP_MB measures the Libera motherboard temperature. If the Brilliance RF board is installed then TEMP_RF1 and TEMP_RF2 measure the RF board temperature, otherwise it will read zero. These temperatures should be maintained at a stable level by the health daemon.

TEMP is the sensor actually monitored by the health daemon, and is either TEMP_MB on Libera Electron, or TEMP_RF1 on Libera Brilliance.

SETTEMP_S*
The health daemon has a very limit range of fan speeds available to it, so in practice it can only be expected to stabilise the temperature close to the natural target temperature. This PV sets the target temperature for the health daemon.
FAN<fan>, FAN<fan>_SET, FAN<fan>_ERR, FAN:OK
Internal fan speeds, normally running between 4200 and 5000 RPM, for <fan> = 1 or 2. FAN<fan>_SET is the set speed for each fan (as set by the health daemon) and FAN<fan>_ERR is the tracking error between the actual and set fan speeds -- an excessive tracking error can be a sign of a failed fan, and contributes to the overall health status, aggregated in FAN:OK.
FREE, RAMFS
FREE records free memory available, while RAMFS records how much memory is currently allocated in temporary files. RAMFS should be monitored to ensure that log files (in /var/log) don't consume all available memory.
CPU
CPU usage as a percentage.
TEMPMON
Aggregates the alarm status of the temperature sensors and the fan monitoring. This will indicate an alarm status if HEALTHD_S is set to "Healthd Silent", in which case sensor monitoring has been disabled.
HEALTH
Aggregates the alarm status of all of the above sensors. Only the alarm state of this record is significant.
UPTIME
Time since Libera was last rebooted in hours.
EPICSUP
Time since the EPICS IOC was restarted in hours.
VOLT<1-8>, VHEALTH
Eight internal power supply voltages are monitored by Libera and reported through the PVs VOLT1 to VOLT8. Voltages outside 5 or 10 percent are reported with minor and major severity EPICS alarms respectively, and VHEALTH aggregates the state of all voltages (except for VOLT2 which is unused).
HEALTHD_S*

This provides control over the sensor monitoring and the health daemon, and has three possible settings:

Healthd On
In this case the health daemon operates normally, maintaining fan speeds to try and keep the selected temperature sensor at the temperature set by SETTEMP_S.
Healthd Off
For very sensitive operation in a temperature stabilised environment is often turns out that the fan speed changes generated by the health daemon are counterproductive. This setting sets the fan speed to a nominal speed of 4,500 RPM and disables the health daemon.
Healthd Silent

For very low noise level studies the internal I2C bus can generate observable noise on the RF board -- selecting this mode disables both the health daemon and all monitoring of internal Libera sensors.

This mode of operation is not intended for normal operation: DO NOT OPERATE LIBERA IN THIS MODE FOR EXTENDED PERIODS. In particular fan faults or overheating will not be detected.

CACLNT, CAPVS
These two PVs monitor the channel access connection. CACLNT reports the number of connected channel access clients and CAPVS reports the total number of PVs being monitored.
NWBRX, NWPRX, NWMRX, NWBTX, NWPTX, NWMTX

These monitor the status of the network connection, reporting respectively the number of kilobytes, normal packets and broadcast packets received and sent, all over the last 10 seconds.

NWBRX:Kilobytes of data per second received.
NWPRX:Packets received per second
NWMRX:Broadcast packets received per second.
NWBTX:Kilobytes of data transmitted per second.
NWPTX:Packets sent per second.
NWMTX:Broadcast packets sent per second.

Signal Conditioning (<group> = SC)

CIIR_S*
Filter coefficient for one pole IIR for application of channel compensation change.
INTERVAL_S*
Interval in seconds between signal conditioning computations.
MAXDEV_S*
Maximum allowed deviation of signal for conditioning processing as a percentage of minimum signal level.
DEV
Measured signal deviation on last update.
STATUS
Status of last signal conditioning round.
PHASEB, PHASEC, PHASED
Measured button signal angles relative to button A in degrees.
C<channel>PHASE, C<channel>MAG, C<channel>VAR
Computed channel gains in phase and magnitude together with the measured variance on each channel.
IQDIGEST, WF<iq>, SETCOMP_S, COMP, LASTCOMP
Internal PVs for develoment and diagnostic use.
TRIGGERED_S*, TRIGDELAY_S*
If required the data captured for signal conditioning can be synchronised to the external trigger (in which case TRIGDELAY_S determines the delay between the trigger point and the captured data). With triggering not enabled data is captured as soon as INTERVAL_S has expired, when enabled conditioning will then wait for the next trigger.

Communication Controller (<group> = FF)

These PVs control the Diamond Fast Feedback Communication Controller, and are only enabled if the controller is detected by the EPICS driver on startup.

BPMID_S*
Configures the communication controller ID for this Libera. Each node on the network must have a unique ID in the range 0 to 255.
BPM_COUNT
Total number of nodes on the network detected by this Libera.
DATA_SELECT_S
Selects the data to be transmitted by this Libera: should normally be "Positions", but "Timestamps" can be selected for network debugging.
XPAYLOAD_S*, YPAYLOAD_S*
If VE:FAPAY is set these PVs can be used to select the data transmitted as "Position" data via the communication controller. Possible values are "A", "B", "C", "D", "S", "Q", "X", "Y".
FRAMELEN_S*
Duration of communication phase in communication control clock cycles (106.25MHz at Diamond). Incoming packets are ignored outside this period: a value between 5000 and 9000 is normally appropriate, depending on network topology.
PROCESS_TIME
Time from start of communication phase until last packet was received, in communication controller clock cycles.
STOP_S, START_S
To stop the communication controller process the STOP_S PV, to restart process STOP_S and then process START_S: communication will then resume on the next trigger.
TIMEFRAME
Counts total number of communication time frames, modulo 16-bits.
VERSION
Communication controller FPGA firmware version.

The following PVs manage the four communication links, and in the following descriptions <link> can be LINK1, LINK2, LINK3 or LINK4.

<link>:LOOPBACK_S
Controls link loopback. Options are: "No loopback" for normal communication, "Parallel" for loopback before 8B/10B conversion, "Serial" for physical loopback after serialisation.
<link>:PARTNER
Identifies the BPM Id of the node sending to this link.
<link>:TX_CNT, <link>:RX_CNT
Number of packets sent and received as a 16-bit counter.
<link>:RX_UP, <link>:TX_UP
Link status. Note that TX_UP will only be "down" when the link is enabled if there is an internal Rocket I/O port fault, whereas RX_UP records the presence of a valid input data stream.
<link>:ENABLE_S
Enables selected link for input and output.
<link>:FRAME_ERR, <link>:SOFT_ERR, <link>:HARD_ERR

Error counts per communication link. Frame Errors include (1) Corrupted Frames where "Start of Frame" arrives, but "End of Frame" does not arrive within a timeout period. (2) CRC errors.

Soft Errors include (1) Receiver disparity error which usually indicates data corruption (bit errors) or transmission of an invalid control character, (2) 8B/10B encoding error which means that the received data is not in the 8B/10B tables.

Hard Errors include (1) RX Buffer Status error which indicates if an overflow/underflow error has occurred on internal RocketIO RX buffers, (2) Realignment error which indicates whenever the serial data is realigned from a comma character in the data stream.

Version Identification (<group> = VE)

VERSION
Version of this release.
BUILD
Date and time this IOC was compiled.
EPICS
EPICS version used to build this IOC.
COMPILER, LIBRARY
Compiler version and libc version used to build this IOC.
ABI
ABI identification (3=>EABI). Newer ARM distributions use the "Embedded Application Binary Interface" to improve floating point performance. On Libera this update is also associated with a change from the old and somewhat buggy "linuxthreads" support to using "NPTL" (Native POSIX Thread Library).
UNAME
Kernel version (as reported by uname -r).
LIBC
C library version of target system.
DRIVER

Libera driver version. Depending on the version of the driver this can be surprisingly difficult to discover, and there are circumstances in which failure to identify the driver version can cause the EPICS driver to be misconfigured.

This problem can arise if /var/log/messages or /var/log/syslog (depending on architecture) has been cleared between loading the Libera driver and loading the EPICS driver. The solution is to load the two drivers together: this is normally done by running /etc/init.d/libera-driver start.

MSP
MSP driver version. The same caveats about identifying the version of this driver apply, but there are no consequences if it is not identified correctly.
ARCH

Architecture identification. This EPICS driver is designed to work correctly on the following distributions:

ITECH-v0:Libera 1.46 running on the original Libera Linux with 2.4 kernel and linuxthreads library.
ITECH-v1:Typically Libera 1.60 to 1.82 running on an updated Libera Linux with a 2.6 kernel, still using the linuxthreads library and the original ABI.
ITECH-v2:Libera 2.00 and beyond running on an updated version of the ITECH-v1 architecture: this uses the NPTL library and EABI to provide improved performance and stability.
DLS:A Diamond Light Source generated Linux distribution with a more recent kernel and libraries, using NPTL and EABI.
ROOTFS
This is an identification string used to identify the precise revision of the distribution. Unfortunately the validity of this depends hugely on the value of ARCH, in particular for ITECH-v0 there are no reliable identification strings!
FPGA
FPGA version
COMPILED
FPGA "compiled" register. This register was originally intended to be used to identify the build date of the FPGA. Unfortunately this register has been frozen with the value 0x07D70501, signifying the date 2007-05-01.
BUILDNO
FPGA build number register. Similarly, this register was originally intended to help identify the FPGA version, but at present it has only ever had two values: 1 for Libera Electron, and 0x10 for Libera Brilliance.
CUSTID, CUSTIDSTR
FPGA customer id register. This identifies the customer for whom the installed FPGA was built.
DDCDEC
Number of samples per machine revolution. The sample clock runs at approximately 110MHz, with the precise value chosen to match the target machine and satisfy signal processing constraints.
FADEC, FACIC, FAFIR
FADEC records the number of turns per FA update. Typically a fast feedback update occurs every 100us and so DDCDEC * FADEC is approximately 10,000. The decimation to FA rate is a two stage process, and the counts of the CIC and FIR stages are recorded as FACIC and FAFIR respectively.
CUSTOMER

Customer feature register. This is used to identify customer specific FPGA features. If the DLS FPGA is installed the top bit of this register will be set, and the following bits are defined:

Bits Description
0 Identified version 2+ FPGA features: spike removal, mean sum, postmortem triggers.
1 Extra secondary interlock limit controls
2 FA payload selection
3-30 Reserved for future expansion
31 Set to 1 for DLS feature identification
ITECH

i-Tech feature register. This is used to identify standard FPGA features as defined and maintained by Instrumentation Technologies. The following fields in this register are recognised by the EPICS driver:

Bits DLS? Name Description (if used)
0 No Grouping  
1 No Desy Molex  
2-3 No Gigabit Ethernet Not supported by DLS EPICS driver
4-5 No DDC filter 0 => Standard DDC filter, 1 => modified boxcar filter (MAF)
6 Yes DLS fast feedback This enables support for the fast feedback controller.
7-22 No Reserved  
23 Yes DLS FPGA If set used to identify DLS FPGA.
24-27 Yes Instrument Type 0 => Libera Electron, 1 => Libera Brilliance
28-31 Yes Instrument class Must be 0 for Electron Beam Position Monitor.
BR, BRHW
Libera Brillance detected. BR is set if the Libera Brilliance FPGA is configured and BRHW if the Brilliance RF board is detected. It is a serious error if these two do not match!
OLDBR
This detects a compatibility mode required for correct operation of Brilliance attenuator settings on older versions of the FPGA.
DLS
Set if the DLS FGPA installed.
FF
Diamond Fast Feedback communication controller enabled.
GBETH
I-Tech gigabit ethernet communication controller detected.
MAF
Boxcar filter present.
ITMAXADC
Detects presence of Instrumentation Technologies implementation of the SA MAXADC register.
DRIVER2
Detects presence of Libera 2.00+ kernel driver, required for postmortem trigger control. Actually mirrors ABI = 3.
FPGA2
Detects Libera 2.00+ version of FPGA, required for a number of more recent useful features.
ILK2
Detects secondary interlock window support (DLS only feature), used for alternative interlock window with hardware selection.
FAPAY
Detects FA payload selection option, DLS only feature. Enables selection of X and Y payloads for FA data.

Other (no group)

VERSION
Copy of VE:VERSION for compatibility.
BUILD
Copy of VE:BUILD for compatibility.
REBOOT_S
Processing this record will cause the Libera IOC to reboot.
RESTART_S
Processing this record will cause the EPICS process to restart.
HEALTH
This aggregates the overall health of Libera, except for the clock. Alarm status from the following SE: PVs are aggregated: FAN1, FAN2, VHEALTH, TEMP, FREE, RAMFS, CPU.