ACO Interface

Table of Contents

Introduction

Please note the architecture of the b2b system (click).

Please note the minutes of the CCT decision decision meeting click).

There are multiple sets of set-values

• set-values are multiplexed by Sequence ID (SID) in the range 0..15
• each Central B2B Unit (CBU) has its own sets of set-values
• set-values are supplied to the CBUs only
• FESA classes for the CBU
  • on the CBU frontend only
  • reminder
    • CBU controls the entire transfer ('fast extraction', 'bunch to coasting beam', 'bunch to bucket')
    • example: a transfer from SIS18 to ESR is managed by the SIS18 CBU (and the ESR CBU is not part of the game)
  • the main job of the FESA classes is to push the set-valus to the relevant CBU
  • only basic status information from the CBU should be obtained from the lm32 firmware (status, version, error ...)
  • acquisition and redistribution of get-values is out of scope
    • complex and requires in-depth understanding of the b2b system
    • must be done on a physically different frontend
    • if this should be done via FESA, this would by another very special FESA class on some other frontend connected to the White Rabbit network

At present there are two CBUs, one for SIS18 and one for ESR. There are 2 x 16 = 32 sets of set-values

Set-Values

• the set-values from the table below must be supplied per Sequence ID
• it should be possible to trim all values individually (especially the harmonic number is important for tweaking)
• data supply uses routines that are available via a shared library
• it requires two FESA classes so supply an FPGA embedded firmware of a few kilobytes with data

abbreviation	FESA [5]	short description	range	typical value	unit	used by mode	mandatory (LSA)	remark
SID_ext	ext	Sequence ID of extraction ring	0..15	1..14	N/A	0..4	X	bunch to bucket does indexing by Sequence ID; this is the SID for extraction
GIDR_ext	ext	Group ID of extraction ring	0x000..0x3ff	0x12c	N/A	0..4		(the FESA class should know this parameter implicitly)
mode	ext	operation mode	0..4	2, 3	N/A		X
				0				operation mode 'off'; in this mode the b2b system will not react to the timing message of the specified SID_ext
				1				operation mode 'EVT_KICK_START', used for equipment tests; extraction kicker is triggered upon EVT_KICK_START
				2				operation mode 'bunch 2 extraction', used for fast extraction to fixed targets
				3				operation mode 'bunch 2 coasting beam', legacy transfer mode between ring machines
				4				operation mode 'bunch 2 bucket'
f_ext	ext	freq h=1 Group DDS @ extraction	200 kHz .. 4 MHz	1 MHz	Hz	2..4	X	(LSA) revolution frequency at extraction [2]
fNueConv_ext	ext	flag: convert LSA to DDS	0..1	1	N/A	2..4		Important: LSA frequency values must be converted to true DDS frequency values; always set this flag unless there is a very special case
h_ext	ext	harmonic number @ extraction	1..255	1, 2, 4	N/A	4	X	harmonic number @ rf-cavity
cTrig_ext	ext	correction kicker trigger extr.	-T_ext .. +T_ext	0	ns	2..4	X	offset for kicker trigger [1], reasonable values are +/- the revolution time in the extraction ring
nBucket_ext	ext	bucket number @ extraction	-99 .. +99	1	N/A	4		extraction starts at this bucket number, required if extraction ring is larger than injection ring [3]
cPhase	ext	phase difference for B2B	-T_ext .. +T_ext	0	ns	4	X	phase difference between h=1 Group DDS for injection and extraction, reasonable values are +/- the revolution time in the extraction ring
fFineTune	ext	flag: use fine tuning	0..1	1	N/A	4		useful when extraction ring is larger than injection ring; enhances precision
fMultiBeatTune	ext	flag: use multi-beat tuning	0..1	0	N/A	4		useful with short beating periods; enhances precision but takes more time (multiple beating periods
SID_ext	inj	Sequence ID of extraction (sic!) ring	0..15	1..14	N/A	3, 4	X	this is not an error: the b2b system needs to merge set-values of extraction and injection; this value must match SID_ext of FESA ext in the 1st row
GIDR_inj	inj	Group ID of injection ring	0x154, 0xd2, 0x136	0x154	N/A	3, 4		(the FESA class should know this parameter implicitly)
f_inj	inj	freq h=1 Group DDS @ injection	200 kHz .. 4 MHz	1 MHz	Hz	4	X	(LSA) revolution frequency at injection [2]
fNueConv_inj	inj	flag: convert LSA to DDS	0..1	1	N/A	3, 4		Important: LSA frequency values must be converted to true DDS frequency values; always set this flag unless there is a very special case
h_inj	inj	period h=1 Group DDS @ injection	1..255	1, 2, 4	N/A	4	X	harmonic number @ rf-cavity
cTrig_inj	inj	correction kicker trigger @inj.	-T_ext .. +T_ext	0	ns	3, 4	X	offset for kicker trigger [1], reasonable values are similar to the ones at the extraction ring
nBucket_inj	inj	bucket number @ injection	-99 .. +99	1	N/A	4		injection starts at this bucket number, required if injection ring is larger than extraction ring [4]

Table: Set-Values for a single CBU handling a transfer: Such a CBU needs values from the extraction ring as well as values for the injection ring (see 2nd column [5]).

[1] The values for cTrig_ext and cTrig_inj are not really required. Instead, one could use the parameters 'kick offset' in ParamModi. [2] If preferred by the CCT, one could also enter the true DDS values. However, in most cases it will be easier to enter the LSA values (for technical reasons, DDS and LSA values might differ up to 46 mHz). [3] I (db) am not sure we really need this. As an example, SIS18 (h=4) to ESR (h=2) could also be parametrized as SIS18 (h=2) and ESR (h=1). [4] Simplified algorithm SIS18 (h=2) -> SIS100 (h=10). In case we'd like to fill buckets 5,6 in SIS100, we just wait for two additional h=1 revolutions in SIS18 (in reality it might not be so simple, as the mismatch between bunch and bucket will increase with each added revolution and a more suitable algorithm might be required). [5] It was decided that there will be two distinct FESA classes for each CBU. One for the extraction ring ('ext') and one for the injection ring ('inj').

Timing

Figure: Timing for writing set-values to or reading get-values from the FPGA by FESA. The order of writing the set-values does not matter. Shown are Data Master (DM), Central B2b Unit (CBU) the two FEA classes for the 'extraction device' and 'injection device' and flattop. Deadlines of timing messages are indicated by green vertical lines. A green box indicates kicker triggers for true bunch-to-bucket. A dark green line indicates kicker triggers for 'fast extraction'/'bunch-to-coasting-beam'. A forbidden interval for communication with the FPGA is indicated by rose boxes. The CBU becomes active upon a 'Bunch-2-Bucket-Start' (B2BS) event (grey boxes). A yellow box marks the flattop of extraction (and injection level). The orange box marks the actual beam transfer for 'bunch-to-bucket' (for 'fast-extraction'/'bunch-to-coasting-beam' the orange box will roughly coincide with EVT_KICK_START). The figure is not to scale. Details see text.

FESA

Writing set-values is triggered by the relevant 'CMD_SEQ_START' events. The order of those events and subsequent writing of set-values to the FPGA is irrelevant. Reading of set-values is only required for the 'extraction-fesa-device'. Both FESA classes must not communicate with the FPGA while the CBU is handling the transfer: It is proposed that the model

• foresees an interval of about 10 ms between the relevant CMD_SEQ_START events and the 'Bunch-2-Bucket-Start' event
• schedules the relevant 'CMD_BP_START' events following the transfer sufficiently later (~ 1 ms) than the 'Bunch-2-Bucket-Start' event

Conventions

Important for correct timing are the following boundary conditions.

• the model must foresee flattop of at least 10000 us length. If the flattop is shortened,
  • the model must make sure that the beating period is shortened by the same amount; T_{flattop, min} = 1500us + T_{beating period}.
  • an information to the b2b team will be appreciated, as the b2b system uses the full length of the flattop for a frequency measurement of the DDS systems
• the model must schedule the message CMD_B2B_Start exactly 500 us prior to the beginning of the flattop
• model/LSA must guarantee that the beating time is not longer than 8490 us. This assumes that the sum of 'Kick offset', time-of-flight and delays within kicker cables is within 10 us.
• the CBU schedules kicker trigger events
  • 'fast extraction', 'bunch-to-coasting beam': within an interval 2000us..(2000us + revolution time) following the message CMD_B2B_START. As the the typical revolution time in SIS18 is about 1 us, the kicker timing is very much predictable.
  • 'bunch-to-bucket': within an interval 2000..10000us after the the message CMD_B2B_START
• the model may schedule the event EVT_KICK_START1/2 at about 2000 us following the message CMD_B2B_START. EVT_KICK_START1/2 might be shifted for proper triggering of beam-instrumentation and other devices. A useful window for EVT_KICK_START1/2 might be 1750..2250us following the deadline of CMD_B2B_START.

Kicker Timing

The figure below shows the relationship of the correction values for extraction and injection kicker as well as the phase correction for mode 'bunch 2 bucket'.

Figure: All correction values are relative to the rising edge of the extraction ring h=1 Group DDS.

Get Values

It was decided that only the FESA class supplying the extraction data is required to publish get values. The following data are available.

abbreviation	FESA [5]	short description	range	typical value	unit	used by mode	remark
common stats
fwVersion	ext	firmware version	N/A	002233	N/A	0..4
state	ext	state of state machine	N/A	OPREADY	N/A	0..4	'major state' machine
nBadState	ext	# of 'bad state' incidents	N/A	0	N/A	0..4
statusArray	ext	array with status bits	N/A	1	N/A	0..4	bit 1: OK, bit 2: unspecified error, ...
nBadStatus	ext	# of 'bad status' incidents	N/A	N/A	N/A	0..4
nTransfer	ext	# of transfers	N/A	N/A	N/A	1..4
transfer stats
SID	ext	Sequence ID of extraction ring	0..15	1..14	N/A	0..4
B2B_GID_ext	ext	internal Group ID B2B	0x3a0..0x3cf	0x3a0	N/A	1..4
mode	ext	operation mode	0..4	2, 3	N/A
TH1Ext	ext	h=1 period extraction	250E9..5E12	1E12	as	2..4	DDS value used by the internal calculation [as] (!)
TH1Inj	ext	h=1 period injection	250E9..5E12	1E12	as	4	DDS value used by the internal calculation [as] (!)
TBeat	ext	period of beating	1E12..10E15	1E15	as	4	period of beating signal [as]

Table: Get-Values for a single CBU handling a transfer.

Shared Library

The communication to the lm32 should be identical for standard frontend or expert access and is encapsulated into a shared library that is made available by the b2b system.

routine	FESA Class Extraction	FESA Classs Injection	When
b2b_firmware_open	must	must	once when starting the FESA class
b2b_firmware_close	should	should	once when terminating the FESA class
b2b_context_ext_upload	must	N/A	prior each extraction/transfer
b2b_context_inj_upload	N/A	must	prior each transfer
b2b_common_read	should	may	following each transfer
b2b_info_read	should	may	following each transer, the value of TBeat might be interesting for operations
b2b_version_firmware	may	may
b2b_version_library	may	may

Table: Routines intended for use by FESA classes.

  // ---------------------------------
  // communication with lm32 firmware
  // ---------------------------------

  // open connection to firmware, returns error code
  uint32_t b2b_firmware_open(uint64_t       *ebDevice,         // EB device
                             const char*    device,            // EB device such as 'dev/wbm0'
                             uint32_t       cpu,               // # of CPU, 0..0xff
                             uint32_t       *wbAddr            // WB address of firmware
                             );
  
  // close connection to firmware, returns error code
  uint32_t b2b_firmware_close(uint64_t ebDevice                // EB device
                              );
  
  // get version of firmware, returns error code
  uint32_t b2b_version_firmware(uint64_t ebDevice,             // EB device
                                uint32_t *version              // version number
                                );

  // get version of library, returns error code
  uint32_t b2b_version_library(uint32_t *version               // version number
                               );
  
  // get info from firmware, returns error code
  uint32_t b2b_info_read(uint64_t ebDevice,                    // EB device
                         uint32_t *sid,                        // SID
                         uint32_t *gid,                        // GID
                         uint32_t *mode,                       // mode
                         uint64_t *TH1Ext,                     // period of h=1 extraction [as]
                         uint32_t *nHExt,                      // harmonic number extraction
                         uint64_t *TH1Inj,                     // period of h=1 injection [as]
                         uint32_t *nHInj,                      // harmonic number injection
                         uint64_t *TBeat,                      // period of beating signal [as]
                         int32_t *cPhase,                      // correction of phase [ns]
                         int32_t *cTrigExt,                    // correction of extraction kicker trigger [ns]
                         int32_t *cTrigInj,                    // correction of injection kicker trigger [ns]
                         int32_t *comLatency,                  // communication latency [ns]
                         int     printFlag                     // prints info on b2b firmware properties to stdout
                         );
  
  // get common properties from firmware, returns error code
  uint32_t b2b_common_read(uint64_t ebDevice,                  // EB device
                           uint64_t *statusArray,              // array with status bits
                           uint32_t *state,                    // state
                           uint32_t *nBadStatus,               // # of bad status incidents
                           uint32_t *nBadState,                // # of bad state incidents
                           uint32_t *version,                  // FW version
                           uint32_t *nTransfer,                // # of transfer
                           int      printDiag                  // prints info on common firmware properties to stdout
                           );
  
  // uploads configuration for the extraction machine, returns error code
  uint32_t b2b_context_ext_upload(uint64_t ebDevice,           // EB device
                                  uint32_t sid,                // SID
                                  uint32_t gid,                // GID of ring machine
                                  uint32_t mode,               // mode
                                  double   nueH1,              // h=1 frequency [Hz] of machine
                                  uint32_t fNueConv,           // flag: convert frequency to DDS (default '1')
                                  uint32_t nH,                 // harmonic number of machine
                                  int32_t  cTrig,              // trigger correction
                                  int32_t  nBucket,            // bucket number
                                  int32_t  cPhase,             // phase correction [ns]
                                  uint32_t fFineTune,          // flag: use fine tune (default '1')
                                  uint32_t fMBTune             // flag: use multi-beat tune (default '1')
                                  );

  // uploads configuration for a injection machine, returns error code
  uint32_t b2b_context_inj_upload(uint64_t ebDevice,           // EB device
                                  uint32_t sidExt,             // SID; NB: this is the SID of the extraction machine!!!
                                  uint32_t gid,                // GID of ring machine
                                  double   nueH1,              // h=1 frequency [Hz] of machine
                                  uint32_t fNueConv,           // flag: convert frequency to DDS (default '1')
                                  uint32_t nH,                 // harmonic number injection machine
                                  int32_t  cTrig,              // trigger correction injection
                                  int32_t  nBucket             // bucket number
                                  );

Remark The shared library also provides routines for its basic status information that could be made available as FESA properties. Real get-values are another story, as the CBU only knows 'its' status but does not collect information from other distributed components of the b2b system. It must be discussed if in-depth get-values are useful for operation purposes anyhow. If yes, this would require a major effort.

Further Distribution of Set- and Get-Values

Set- and get-values are distributed by the CBU via the White Rabbit network. There are no dedicated messages for data transfer only. Instead, the data are encoded into the 'parameter' field of timing messages that are required anyhow. This is described in a table that is available here.

Test System in INT (for FESA class testing)

Low Level

• there is only CBU available for extractions from SIS18
• the CBU lives on scuxl0288
• this SCU is 'boot-safe' everything described in this section will work even after a power-cut
• the system is triggered upon
  • EVT_KICK_START1 (2021)
  • CMD_B2B_START (2022)
• in order to see patterns with fast extraction try [root@scuxl0288 ~]# saft-ctl tr0 -vx snoop 0x0 0x0 0 | grep "EVTNO: 0x0031". These are messages sent by the Data Master. Please note the SID.
• to see the action of the b2b system, there are two possibilities
  • on scuxl0288, call frequently b2b-ctl dev/wbm0 diag
  • on scuxl0404, try saft-ctl -vx tr0 snoop 0x0 0x0 0 | grep "EVTNO: 0x08". These are messages sent by the b2b system. If everything is working, it should look like this (mode 'bunch-to-coasting beam'):

[root@scuxl0404 ~]# saft-ctl -vx tr0 snoop 0x0 0x0 0 | grep "EVTNO: 0x08"
tDeadline: 2021-07-16 16:40:18.968870001 FID: 0x1 GID: 0x03a1 EVTNO: 0x0800 FLAGS: 0x0 BPC: 0x0 SID: 0x0003 BPID: 0x00000 RES: 0x0000 Param: 0x010000e8d4a5674f!delayed (by 1249495 ns)          // sent by CBU: request phase measurement from PM
tDeadline: 2021-07-16 16:40:18.969370001 FID: 0x1 GID: 0x03a1 EVTNO: 0x0802 FLAGS: 0x0 BPC: 0x0 SID: 0x0003 BPID: 0x00000 RES: 0x0000 Param: 0x169252f2fa432a28!delayed (by 2067207 ns)          // sent by PM: result of phase measurement
tDeadline: 2021-07-16 16:40:18.969870336 FID: 0x1 GID: 0x012c EVTNO: 0x0804 FLAGS: 0x0 BPC: 0x0 SID: 0x0003 BPID: 0x00000 RES: 0x0000 Param: 0x00012fd800000000!delayed (by 2008664 ns)          // sent by CBU: trigger the SIS18 kicker
tDeadline: 2021-07-16 16:40:18.969870336 FID: 0x1 GID: 0x0154 EVTNO: 0x0805 FLAGS: 0x0 BPC: 0x0 SID: 0x0003 BPID: 0x00000 RES: 0x0000 Param: 0x0000000000000000!conflict (delayed by 2450216 ns) // sent by CBU: trigger the ESR kicker
tDeadline: 2021-07-16 16:40:18.989370001 FID: 0x1 GID: 0x03a1 EVTNO: 0x0808 FLAGS: 0x0 BPC: 0x0 SID: 0x0003 BPID: 0x00000 RES: 0x0000 Param: 0x000000bf00001388                                  // sent by PM: contains diagnostic data 

Higher Level (but still below FESA)

There exist text based user interfaces that might provide additional information (click).

These user interfaces are available for INT and PRO; at present (2021) there is no development system in DEV.

Nomen

• GS00ZB_E, SIS18 Extraktion
• GE00ZB_I, ESR Injektion
• GE00ZB_E, ESR Extraktion
• YR00ZB_I, CRYRING Injektion
• YR00ZB_E, CRYRING Extraktion

Bunch to Bucket FESA Class

The B2B FESA Class provides an interface to the B2B Firmware.

FESA Explorer

FESA Explorer can be used to interact with the FESA software directly.

From an asl commandline:

/common/usr/fesa/bin/fesa-explorer --config=dev --args /common/usr/fesa/htdocs/fex/B2B_DU_scuxl0288.zip

Or start from the Launcher Application, click "Load a Model from the web server", click Browse, select B2B_DU_scuxl0288.zip, OK. Select cmwint00a.acc.gsi nameserver from drop-down list.

For Status properties Cycle Selection must be Any (-1)

For Setting/Acquisition properties Cycle Selection must be Sequence Index = 0..15

Overview

The software consists of a single FESA deploy-unit containing a single class that manages communication with the b2b CBU firmware on the frontend.

The Class "B2B" includes all functionality for extraction and injection machines. This is not exported to the database.
The Class View "B2B_EXT" includes only the functionality for extraction machines. This is exported to the database.
The Class View "B2B_INJ" includes only the functionality for injection machines. This is exported to the database.

Applications will use either the B2B _EXT or B2B _INJ interface.
The B2B deploy unit can have Devices of type "B2B_EXT" and "B2B_INT", this is configured in the instance file.
If a device of type EXT has fields of type INJ set (and vice versa), these will be ignored (e.g. if set directly bypassing the database)

Test Configuration

Two Devices are deployed on scuxl0288:
GS00ZB_E type "B2B_EXT" Timing Group 300 (SIS18 ring)
GS00ZB_I type "B2B_INT" Timing Group 340 (ESR ring)

Operation:

SEQ_START event in the device's timing group loads settings for that sequence into the firmware.
B2B_START event triggers CBU >10ms later)
FESA must not communicate with FPGA until 10ms after B2B _START
[SEQ_START + offset] event triggers reading of acquisition values from the firmware with offset sufficient that the FPGA is not disturbed.
General status is also read using a periodic software timer.

Use

Default settings are as described https://www-acc.gsi.de/wiki/BunchBucket/BunchBucketAcoInterface. Settings are persisted.
Timing groups for each device are set in the instance file.

For EXT:
Set "Setting" values using a cycle selector S=0 to S=15
Read "Acquisition" values using a cycle selector S=0 to S=15

For INJ:
Set "Setting" values using a cycle selector S=0 to S=15
Set "Setting:SIDExtRing" value using the sequence ID of the associated extraction ring

Interface fields

(The autogenerated interface description for the full class is here: https://www-acc.gsi.de/data/fesa/classes/B2B.html )

The property Setting is different for EXT and INT interfaces:

B2B _EXT Setting (Sequence Multiplexed)
Mode - enum B2B _MODE: value="0" symbol="OFF", value="1" symbol="EVT_KICK_START", value="2" symbol="BUNCH_TO_EXTRACTION", value="3" symbol="BUNCH_TO_COASTING_BEAM", value="4" symbol="BUNCH_TO_BUCKET"
Frequency - double - Hz
ConvertLSAtoDDS - bool
HarmonicNumber - int32
TriggerOffset - int32 - ns
BucketNumber - int32
PhaseDifference - int32 - ns
FineTune - bool
MultiBeatTune - bool

B2B_INJ Setting (Sequence Multiplexed)
Frequency - double - Hz
ConvertLSAtoDDS - bool
HarmonicNumber - int32
TriggerOffset - int32 - ns
BucketNumber - int32
SIDExtRing - int32

Frequency/HarmonicNumber/BucketNumber have _min/_max fields containing constant limits
The limits for PhaseDifference / TriggerOffset are calculated from the value of Frequency

The following Properties are common - note that a reset will affect all devices using the same CBU
Reset
Clears configuration and diagnostic statistics in firmware
Power
Nothing to control, reports as ON

Status

detailed status:

online - communication to firmware OK
opready - firmware reports opready
opready - firmware reports opready, modules OK

powerState - always on
control - always remote

Acquisition

state - int32
nBadState - int32
nBadStatus - int32
statusArray - int64
nTransfers - int32

ModuleStatus

B2BFW - connection to B2B firmware in FPGA OK
TrALive - Timing receiver ready to receive events
TrLock - Timing receiver locked to timing master

Errors

If FESA cannot communicate with the firmware or there is no timing, this is shown in DetailedStatus and ModuleStatus.
If the firmware does not indicate OPREADY, this is shown in DetailedStatus.
FESA will validate settings and throw an exception if values are out of range.
If there is a problem writing values to the firmware, a realtime exception will be sent to Graylog and recorded in the error history field. The StatusArray acquisition value corresponding to the sequence start event will contain more detailed error information.

Issues

FESA

fixed

Indexing

Currently, the b2b systems is multiplexed by SID. On the long run, it might be better to have it multiplexed by BPID (the FESA class). However, this would require an additional CMD_B2B_PREP event (similar to the CMD_FG_PREP).

Coupling of Patterns

Presently the SID of the extraction ring is used to 'join' the two data sets of extration and injection. As an alternative, one could think of using s.th. like the 'coupling ID' instead. Important: We have to keep the use-case SIS18 -> SIS100 (booster mode) in mind, where ~4 transfers are done involving two coupled patterns.

Limits

• trigger_offset
• frequency

must be discussed whether we keep them or not

ParamModi and LSA

• clearer names
  • example: mode '2extraction' -> 'fast extraction'
  • example: parameter/mode 'evt_kick_start' does not exist at CRYRING

• option for group DDS frequency meausurement with slow extraction
  • b2b mode: off
  • requires set-value for revolution frequency and message CMD_B2B_START

Set-Values

fixed

Schedule for Coupled Patterns

fixed

-- DietrichBeck - 10 February 2022