The timing/bsa package and the bsaDriver module are in charge of all acquisition services, namely: Beam Line Data (BLD), Beam Synchronous Acquisition (BSA), Beam Synchronous Acquisition Service (BSAS), and Beam Synchronous Scalar Service (BSSS) for the superconducting accelerator.
TBD
This contains a list of the capabilities of the module/package i detail. The reader should be able to understand the basic functionalities of this package/module by reading this text.
The timing/bsa requires paths that will denote the relevant registers/streams/and drams described in the YAML files. The necessary YAML files are as follows
The involved registers are as follows
Register Index | YAML File | Stream/Register name | Description |
---|---|---|---|
1 | BldAxiStream.yaml | packetSize | Maximum size of packets in 32b words |
2 | enable | service enable | |
3 | channelMask | Mask of enabled channels | |
4 | currPacketSize | Current size of packet in 32b words | |
5 | currPacketState | Current packet fill state. Relevant to the statemachine filling the packet in the firmware and irrelevant to the software engineer | |
6 | currPulseIdL | Current packet pulseID lower word | |
7 | currTimeStampL | Current packet timestamp lower word | |
8 | currDelta | Current compressed timestamp/pulseID | |
9 | packetCount | Generated packet count | |
10 | paused | Stream paused | |
11 | diagnClockRate | Diagnostic bus clock rate | |
12 | diagnStrobeRate | Diagnostic bus strobe rate | |
13 | eventSel0Rate | Event select0 rate | |
14 | EdefEnable[#EDEFS] | Enable a specific event definition | |
15 | EdefRateLimit[#EDEFS] | Event definition rate limit | |
16 | EdefRateSel[#EDEFS] | Event definition rate select | |
17 | EdefDestSel[#EDEFS] | Event definition destination select | |
Each file/associated classes will be described here. UML diagrams and text description can be used. A UML cheat sheet can be found here. Instantiation information (if applicable) can be mentioned. Flow diagrams for describing the class operation are also welcome. Everything can be developed in Gliffy.
Here you can mention if the package/module throws any exceptions, and you can also mention how these exceptions should be handled in upper layers.
Is the package extendable to add a new function or to modify an existing function? If so, it needs to be mentioned here.
All EPICS shell commands provided should be described here with their input parameters.
The PV list goes here. If any other page described some or all PVs, it can be referenced here. The register index can map the PV to the register described in the YAML section above.
Contains functions and structures to read the BLD/BSSS/BSAS stream coming from the firmware and call the registered callback functions with the stream data stored in buffers. It also provides functions to print statistics. This file forms an EPICS driver run at IOC boot automatically without any user setup or configuration.
This Asyn driver is used to initialize both BSSS and BLD since they both have identical firmware structures. This file contains some similar structures with bldStream.cpp file. A static pointer is declared globally in the file, and used to store different service drivers in a linked list.
A simple description of the linked list functions is as follows:
Several other independent functions exist in the file. A simple description of these functions is as follows:
Finally, the serviceAsynDriver class and methods are as follows
A description of the class methods is as follows:
serviceAsynDriver: Class constructor, Gets root Path from CPSW, creates the <Service>Yaml structure(s) provided by the timing/bsa package, and register callbacks
writeInt32: Asyn write 32 bit function used for passing PV values to firmware
writeOctet: Asyn write array function used currently only with BLD multicast address
updatePVA: Deletes the old PVA and calls initPVA again
initPVA: Instantiates the BLD payload PVAccess. IT described the content of the BLD packet
addBldChannelName: adds a name to a BLD channel. This replaces the channel key <bsakey> in BLD
MonitorStatus: method that reads status variables from the firmware and updates PVs
bsssCallback: BSSS built-in callback function
bldCallback: BLD built-in callback function
getServiceType: Return private variable serviceType
The BLD packet structure coming from the ATCA FPGA and the ones sent out to the BLD clients are described in these slides. The packet structure coming from the firmware contain a packet header, followed by the event's enabled channel data and finally by the severity mask. The firmware may send other event data appended as many times as necessary.
The BSSS firmware packet structure however are not described anywhere.
The packet structure extracted from the bsssCallback seems to be as follows:
struct firmwareBSSSPacket{ uint64_t sec; uint64_t pid; uint32_t channelMask; uint32_t serviceMask; uint32_t channelData0; ... uint32_t channelData30; uint64_t severityMask; }
The reported number channel data in the packet is variable and not necessarily all of the channels will have data. The BSSS callback source code uses the channelMask to identify if the channel data is available or not.
This device support for BSSS was developed to override the asyn parameters. Apparently the asyn based PVs increase the CPU load significantly. The header file contains functions that will be accessed by external source to update the relevant records. 2 device support records are created
The device support structures (DSET) are defined as follows
struct { long number; DEVSUPFUN report; DEVSUPFUN init; DEVSUPFUN init_record; DEVSUPFUN get_ioint_info; DEVSUPFUN read; }devBsssPid={ 5, NULL, NULL, init_record_pid, get_ioint_info, read_pid }; struct { long number; DEVSUPFUN report; DEVSUPFUN init; DEVSUPFUN init_record; DEVSUPFUN get_ioint_info; DEVSUPFUN read; DEVSUPFUN speical_linconv; }devBsssV={ 6, NULL, NULL, init_record_v, get_ioint_info, read_v, NULL }; epicsExportAddress(dset, devBsssPid); epicsExportAddress(dset, devBsssV);
More information about the DSET can be found here. The structure of these structures come from aiRecord.h and int64inRecord.h files. Once the functions are defined and their function addresses are given to the structure, the structures must be exported using the epicsExportAddress command.
The functions are namely as follows:
A graphical structure of t
At this point, the device supports exist, but are still not enabled for usage. the new device supports need to be added to the dbd file (bsaAsynDriver.dbd) using the following commands:
device(int64in, INST_IO, devBsssPid, "BSSS") device(ai, INST_IO, devBsssV, "BSSS")
These lines state that the device support devBsssPid overloads the device support of int64in record type, and the devBsssV overloads the device support of ai record type. The last parameter denotes the DTYP field in the db file. The following slides were taken from one of the EPICS trainings may help visualize what is what
BSA asyn driver also contains a global static pointer that points to a linkedList of all drivers instantiated, and contains the same set of linkedList functions that were described above. The node structure is as follows
(TODO: convert code into diagram, adding bsaAsynDriver, pBsaEllList, and pBsaBridge)
typedef struct { ELLNODE node; char *named_root; char *port; bsaAsynDriver *pBsaDrv; ELLLIST *pBsaEllList; void *_pBsaBridge; } pDrvList_t;
bsaAsynDriver is a class defined in bsaAsynDriver.h: class bsaAsynDriver:asynPortDriver.
The linked list pBsaEllList contains elements of the struct bsaList_t. This struct represents one BSA channel.
typedef struct { ELLNODE node; ELLLIST *pSlaveEllList; // slave node char bsa_name[64]; // bsa name char bsa_type[32]; // bsa datatype int firstParam; int p_num[MAX_BSA_ARRAY]; // asyn parameter for number of average, asynFloat64Array, RO int p_mean[MAX_BSA_ARRAY]; // asyn parameter for average value, asynFloat64Array, RO int p_rms2[MAX_BSA_ARRAY]; // asyn parameter for rms2 value, asynFloat64Array, RO int p_slope; // asyn parameter for linear conversion, asynFloat64, RW int p_offset; // asyn parameter for linear conversion, asynFloat64, RW int lastParam; double slope; double offset; bsaDataType_t type; devBsaPvt_t ppvt_num[MAX_BSA_ARRAY]; devBsaPvt_t ppvt_mean[MAX_BSA_ARRAY]; devBsaPvt_t ppvt_rms2[MAX_BSA_ARRAY]; char pname_num[MAX_BSA_ARRAY][64]; char pname_mean[MAX_BSA_ARRAY][64]; char pname_rms2[MAX_BSA_ARRAY][64]; char pname_slope[64]; char pname_offset[64]; bool doNotTouch; } bsaList_t;
_pBsaBridge receives pProcessor→getHardware(), a class defined in the timing/bsa module.
devBsaPvt_t is defined in the devScBsa.h file:
typedef struct { void *dpvt; epicsTimeStamp ts; int nreq; int entry_sz; void *bptr; } devBsaPvt_t;
The functions operating on the linked list are as follows:
bsaAdd initializes a bsaList_t structure and stores it in the pBsaEllList ELL linked list. pBsaEllList is stored in the structure pDrvList_t of the bsaAsynDriver.cpp file. There are different structures called pDrvList_t in other files of the bsaDriver EPICS module, so care must be taken to not get confused. This is a visual pointer structure operated by bsaAdd: