Confluence will be unusable 23-July-2024 at 06:00 due to a Crowd upgrade.
Table of Contents |
---|
The Bunch Length system is responsible for measuring the length of the bunch of electrons after the bunch compressors, using indirect measurement techniques. For a detailed and hopefully entertaining introduction on the physics and mathematics behind the system, please read the document How the Length of the Bunch is Measured.
The system is based on the High-Performance System (HPS) over ATCA built at SLAC. For an introduction, please read ATCA 101.
Gliffy Diagram | ||||
---|---|---|---|---|
|
The figures with white heads represent a person and the ones with grey head represent a system.
Anchor | ||||
---|---|---|---|---|
|
The goal is to receive inputs from sensors and other systems and calculate the maximum current and charge (called signal sum) of the electron beam. Those are indirect measurements representing the amplitude and area of a Gaussian, which are easily translated to a bunch length by the Physicists. Details on this process and the calculation itself are described in How the Length of the Bunch is Measured.
...
The sequence of actions of each thread is described in details below:
Anchor | ||||
---|---|---|---|---|
|
...
Gliffy Diagram | ||||||
---|---|---|---|---|---|---|
|
Anchor | ||||
---|---|---|---|---|
|
The system controls some optical filters and reads the position of the filters by using digital I/O located on the RTM attached to the blade dedicated to the Bunch Length system.
...
The EPICS database files are blenFilterDecoders.db, blenFilters.substitutions, blenFilters.template.
The system provides data related to two different bunch length measurements for the Operators, one for each pyrodetector. This is the PyDM screen that can be used to check the system:
The streaming of the waveforms can be turned on or off to reduce the data from the ATCA to the CPU. The Operator can choose 4 different status for the stream: Running, Maintenance, Test, and OFFLINE. The first 3 don't change the behavior of the streaming, they are used only for alerting other users. "OFFLINE" is the only status the effectively shut down the streaming. The database that controls the stream is streamControl.db. Anchor STREAM_CONTROL STREAM_CONTROL
...
The dashed blue lines indicate where the integration window is placed. The left side tells the system where to integrate the background noise while the right side configures where the real signal is. The chart below the raw waveform shows the result when multiplying the background by +1 and the signal by -1. The system will integrate this second waveform to get the non-calibrated length measurement. The calibration parameters and windows adjustments are described in the next topic.
TMIT and the integral of the raw waveform are used to calculate the bunch length. The parameters that need to be input in the system are the integration windows, plus a linear adjustment function [f(x)=a.x+b] for the sum of the signal, plus the coefficients of this equation:
...
Each group of elements will be broken into sections for better comprehension:
Anchor | ||||
---|---|---|---|---|
|
The system provides a way to adjust 3 regions for the signal. The leftmost region, shown as "Duration pre edge (ns)" on the picture below, integrates the background noise to be subtracted from the signal region. The rightmost region, shown as "Duration pos edge (ns)" on the picture below, integrates the signal. An optional "Duration inter edges (ns)" defines a region between the background noise and the signal where the integration is ignored. It is useful for removing the slope from the calculation. This middle region is not shown in the chart below.
...
The firmware doesn't work in terms of nanoseconds, but it uses clock ticks. A transformation must be done from clock ticks to nanoseconds and vice-versa. Also, the firmware doesn't accept odd values for tick counts. The first 28 bytes of the raw waveform sent by the firmware contains diagnostics data and not sampled data and have to be removed. All of these operations are described in the section "Waveform and integration windows".
This step ends with the result for ARAW for the formula described before. This step is performed by the firmware, not the software.
...
The last section of this document showed how the integration windows are adjusted. An EPICS database takes care of changing A0 and A1 automatically when the windows' width is changed. So, this guarantees that if the background and signal are approximately horizontal lines, no change in the window's width will change the final result of ARAW. A deep detail about this database is described in Auto adjustment of weight factors A0 and A1 below.
Revisiting the equation defined some sections above, we already have described the origin of two components:
...
Register name | Asyn parameter name | PV |
---|---|---|
/mmio/AppTop/AppCore/SysGenMr[0]/DspCoreConfigMr/CoefB | AMC0:CoefB | BLEN:$(AREA):$(POS):$(INST)_CoefB |
/mmio/AppTop/AppCore/SysGenMr[1]/DspCoreConfigMr/CoefB | AMC1:CoefB | BLEN:$(AREA):$(POS):$(INST)_CoefB |
/mmio/AppTop/AppCore/SysGenMr[0]/DspCoreConfigMr/CoefC | AMC0:CoefC | BLEN:$(AREA):$(POS):$(INST)_CoefC |
/mmio/AppTop/AppCore/SysGenMr[1]/DspCoreConfigMr/CoefC | AMC1:CoefC | BLEN:$(AREA):$(POS):$(INST)_CoefC |
/mmio/AppTop/AppCore/SysGenMr[0]/DspCoreConfigMr/CoefD | AMC0:CoefD | BLEN:$(AREA):$(POS):$(INST)_CoefD |
/mmio/AppTop/AppCore/SysGenMr[1]/DspCoreConfigMr/CoefD | AMC1:CoefD | BLEN:$(AREA):$(POS):$(INST)_CoefD |
/mmio/AppTop/AppCore/SysGenMr[0]/DspCoreConfigMr/CoefE | AMC0:CoefE | BLEN:$(AREA):$(POS):$(INST)_CoefE |
/mmio/AppTop/AppCore/SysGenMr[1]/DspCoreConfigMr/CoefE | AMC1:CoefE | BLEN:$(AREA):$(POS):$(INST)_CoefE |
/mmio/AppTop/AppCore/SysGenMr[0]/DspCoreConfigMr/CoefF | AMC0:CoefF | BLEN:$(AREA):$(POS):$(INST)_CoefF |
/mmio/AppTop/AppCore/SysGenMr[1]/DspCoreConfigMr/CoefF | AMC1:CoefF | BLEN:$(AREA):$(POS):$(INST)_CoefF |
/mmio/AppTop/AppCore/SysGenMr[0]/DspCoreConfigMr/CoefG | AMC0:CoefG | BLEN:$(AREA):$(POS):$(INST)_CoefG |
/mmio/AppTop/AppCore/SysGenMr[1]/DspCoreConfigMr/CoefG | AMC1:CoefG | BLEN:$(AREA):$(POS):$(INST)_CoefG |
/mmio/AppTop/AppCore/SysGenMr[0]/DspCoreConfigMr/CoefH | AMC0:CoefH | BLEN:$(AREA):$(POS):$(INST)_CoefH |
/mmio/AppTop/AppCore/SysGenMr[1]/DspCoreConfigMr/CoefH | AMC1:CoefH | BLEN:$(AREA):$(POS):$(INST)_CoefH |
Anchor | ||||
---|---|---|---|---|
|
The Bunch Length IOC application provides 4 parameters for the BSA (Beam Synchronous Acquisition) system. A brief introduction for BSA can be found here: Beam Synchronous Acquisition (BSA).
...
Code Block | ||||
---|---|---|---|---|
| ||||
int BlenBSA::createChannels(const char *stationName) { char param_name[64]; bsaChannels = new BsaChannel[NUM_CHANNELS]; /* Create NUM_CHANNELS BSA channels with the name formed by the * stationName that comes from the IOC shell, plus the channel * acronym defined by the constant array channelNames. */ using namespace std; for (int i = 0; i < NUM_CHANNELS; i++) { sprintf(param_name, "%s:%s", stationName, channelNames[i]); bsaChannels[i] = BSA_CreateChannel(param_name); } return 0; } |
As explained in Calculate the maximum current and signal sum, there is a thread responsible to store the data to the BSA Core as soon as the data is ready. The firmware sends the data to the software using a CPSW stream channel. The name of the stream channel is defined in the YAML file and must be informed to the BSA thread by the second parameter of the st.cmd function blenConfigure (explained before). Every time the data is ready, the firmware sends it asynchronously and the software must be prepared to read and process it. The complete data structure of this stream can be checked here. For what is in use by the current IOC application, this is the struct that is mapped to the stream packet:
Code Block | ||||
---|---|---|---|---|
| ||||
typedef struct { epicsTimeStamp time; epicsUInt32 mod[6]; epicsUInt32 edefAvgDoneMask; epicsUInt32 edefMinorMask; epicsUInt32 edefMajorMask; epicsUInt32 edefInitMask; } timing_header_t; typedef struct { epicsFloat32 sum; epicsFloat32 iMax; epicsFloat32 scaledTMIT; epicsUInt32 status0; epicsUInt32 status1; // Seven 32-bit words reserved for future use epicsUInt32 reservedWords[6]; } payload_t; /* This structure represents the entire content of the BSA stream message that * comes from the firmware. If the message content is changed, this structure * must be updated */ typedef struct { // Stream header is not described at the specification. epicsUInt64 streamHeader; epicsUInt32 headerWord; timing_header_t timingHeader; payload_t AMC0_Data; payload_t AMC1_Data; } stream_t; |
If you retake the BSA thread task activity diagram, the data receive some processing and is mapped to another data structure to make it easier to extract data to the BSA core. This is the structure:
Code Block | ||||
---|---|---|---|---|
| ||||
// Data to be sent to BSA channels typedef struct bsaData_t { epicsTimeStamp timeStamp; double aImax; double aSum; BsaStat aStat; BsaSevr aSevr; double bImax; double bSum; BsaStat bStat; BsaSevr bSevr; } bsaData_t; |
Once this structure is filled, the last step is to send the data to the BSA channels: Anchor BSA_STORE BSA_STORE
...
Code Block | ||||
---|---|---|---|---|
| ||||
# BSA records dbLoadRecords("db/Bsa.db", "DEVICE=BLEN:${AREA}:${POS},ATRB=AIMAX, SINK_SIZE=1") dbLoadRecords("db/Bsa.db", "DEVICE=BLEN:${AREA}:${POS},ATRB=BIMAX, SINK_SIZE=1") dbLoadRecords("db/Bsa.db", "DEVICE=BLEN:${AREA}:${POS},ATRB=ARAW, SINK_SIZE=1") dbLoadRecords("db/Bsa.db", "DEVICE=BLEN:${AREA}:${POS},ATRB=BRAW, SINK_SIZE=1") |
Anchor | ||||
---|---|---|---|---|
|
The IOC application provides an IOC shell function called blenReport to help the IOC Maintainer to diagnose the system. Once in the IOC shell, blenReport will output:
...
Message | Description |
---|---|
# FCOM messages received with success | The number of FCOM packets received from the BPM with success. These packets contain the information about TMIT, X beam position, and Y beam position. |
# timeouts | Number of times that a timeout happened while waiting for an FCOM packet. |
# FCOM messages arriving with error | Number of times that an FCOM packet arrived but was corrupted. |
# FCOM messages with message status error | Number of times that a valid FCOM packet was received successfully from the BPM, but contained any type of error flag. |
# FCOM messages transmitted with success | The number of FCOM packets transmitted successfully to the multicast network. These packets contain AIMAX, BIMAX, ASUM, and BSUM, calculated by the firmware, to be received by the Fast Feedback system. The IOC has no way to know if the packet arrived successfully at the destination, so this parameter can only be used to know when a multicast packet left the IOC. |
# errors when transmitting FCOM messages | The number of times when an error occurred when trying to send an FCOM packet. |
Last TMIT | Last TMIT value received from the BPM. |
Last X | Last X beam position received from the BPM. |
Last Y | Last Y beam position received from the BPM. |
Last transmitted aimax | Last AIMAX value transmitted to the Fast Feedback system. |
Last transmitted bimax | Last BIMAX value transmitted to the Fast Feedback system. |
Last timestamp high | The last timestamp processed (high word). |
Last timestamp low | The last timestamp processed (low word). |
Pulse ID | The last pulse ID processed. |
Anchor | ||||
---|---|---|---|---|
|
Sometimes the IOC Maintainer would like to check the content of the raw BSA message that the firmware is sending to the IOC. For this, the function blen_dumpBSAStream can be used. It accepts one parameter: the number of packets in the sequence that is going to be printed on the IOC shell. The content of the bytes for this function is described in this document. This is a partial output after this function finishes printing 2 packets.
Panel | ||||||
---|---|---|---|---|---|---|
| ||||||
BSA stream dump - 1 packets remaining (...) 32 00 00 00 00 BSA stream dump - 0 packets remaining (...) 32 00 00 00 00 |
Anchor | ||||
---|---|---|---|---|
|
All the algorithm is processed in the EPICS database layer.
...
The inter-edges window must be divided by 2 per firmware requirement. Also, we are guaranteeing that the size of the inter-edge window is never lower than the pre-edge window for the reason explained before in Adjustment of the integration windows. That's the function of the record TIME_MIDC.
...
The last feature provided by the weightFunctionXAxis.db is to generate an array for the X-axis of the chart, containing the translation to nanosecond for each tick count. This is held by the aSub record BLEN:$(AREA):$(POS):$(INST)_WF_TIME, using the function calcTimeArray() available in the file asubWeightXAxis.c. The input for the record is the PV AmcClkFreq already described before.
Anchor | ||||
---|---|---|---|---|
|
As seen before, moving the sliders to change the width of the integration windows changes the PVs NumSamp0 and NumSamp1, that, in sequence, send the value to the FPGA registers. This section is the continuation of this story.
...
Gliffy Diagram | ||||||
---|---|---|---|---|---|---|
|
Files in blenApp/Db
blenFilterDecoders.db | Contain mbbiDirect and mbboDirect records to encode/decode individual bits into integers that are read/sent to the firmware. Each bit represents a status for one of the filter positions or the actuator that commands one of them. Details on the bit mapping can be found in the section Control filters and check status of them. |
blenFilters.substitutions blenFilters.template | For status of filter position, read individual bits from the database blenFilterDecoders.db and translate them into single PVs. For filter actuators, provide single PVs to write to the mbboDirect record inside blenFilterDecoders.db. For a description of the filters, read section Control filters and check status of them. |
blenMR.substitutions | This is the file associated with all mapped registers of the FPGA. The mapping starts with the dictionary file yaml/blenMR.dict and entries of this dictionary are used in blenMR.substitutions to create the database blenMR.db. |
calculatedWF.db | The records in this file fill 3 purposes:
|
manual.req | Autosave file for PVs without info fields. For this application, we are autosaving the coefficients of the equation. The PVs come from blenMR.substitutions and are based on the ycpswAsyn database. |
processRawWFHeader.db | Remove the first 28 16-bit words from the raw signal stream because they are just a header and don't represent digitized data. Also reads the beam present flag from the header to update the waveform with digitized data only when we have beam. |
streamControl.db | |
weightFunctionXAxis.db |
...
Provide 4 different status for controlling the streaming of the raw signal from the ATCA to the CPU: Running, Maintenance, Test, and OFFLINE. For more details, check here. | |
weightFunctionXAxis.db | Convert the X-axis values of the many legs of the weight function from tick counts to nanoseconds and vice-versa. More details on the section Waveform and integration windows. |
Files in blenApp/src
asubWeightXAxis.c | Function for the asub record that builds an array containing the time in nanoseconds related to each tick count. This is used only for the X-axis of charts, for visualization purposes. More details on the section Waveform and integration windows. |
blenBSA.cpp blenBSA.h | Contain the class BlenBSA, responsible for creating the BSA channels during the IOC boot and storing the data in the BSA core architecture. |
blenDrv.dbd | Registrars for the IOC shell functions and the asub function inside asubWeightXAxis.c. |
blenFcom.cpp blenFcom.h | Contain the thread that deals with the FCOM tasks: read data from the BPM IOC, write data to the Fast Feedback system, send TMIT information to the firmware, register and show failure and success events for diagnostics logs. |
blenIOCFunctions.cpp | Contain the IOC shell function definition for blenConfigure, blenReport, and blen_dumpBSAStream. |
blenMain.cpp | Default EPICS main function. |
cpswStreamBSA.cpp cpswStreamBSA.h streamDataType.h |