-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME.bsa_only
345 lines (260 loc) · 13.4 KB
/
README.bsa_only
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
bsa.db template:
bsaDriver provides an epics database template for the BSA history buffer PVs.
The template has a few macros to set up PV name, BSA name and BSA buffer length
for the history buffer PVs.
Here is the structure of the template:
$(DEV):$(SECN)HST<n> ; BSA history for average value
$(DEV):$(SECN)CNTHST<n> ; number of samples for an average value
$(DEV):$(SECN)RMSHST<n> ; RMS value
$(DEV):$(SECN)PIDHST<n> ; pulse id
Macros:
$(DEV) ; device PV name
$(SECN) ; signal name as part of the PV name
$(BSAKEY) ; BSA key. It must match the bsa key string in bsaAdd() or
bsaAddSecondary() explained in the README file. This macro is
used in INP and OUT fields to connect with the device
support code.
$(TPR) ; an optional macro. If the IOC uses multiple different device
names for $(DEV), we need to add up $(TPR) which has a
single name in the ioc.
$(PORT) ; asyn port name for BSA driver. Must match the port name used
in the function bsaAsynDriverConfigure.
<n> ; given instance number / name
- For BSA buffer numbers for general use:
<n> = [21..49]
- For system buffers, it has two components:
<n> = <dest><freq>
<dest>
SCD = Diag0
SCL = Linac. This includes all bunches to BSY, HXR, and SXR.
SCB = BSYD
SCH = HXR
SCS = SXR
<freq>
1H = pre-programmed with 1Hz continuous acquisition
TH = pre-programmed with 10Hz continuous acquisition
HH = pre-programmed with 100Hz continuous acquisition
<n> will be the combination of all <dest> with all <freq>.
Examples: SCD1H, SCLTH, SCSHH, etc.
- For fault buffers:
<n> = FLTB0 reserved BSA slot for fault buffer
<n> = FLTB1 reserved BSA slot for fault buffer
<n> = FLTB2 reserved BSA slot for fault buffer
<n> = FLTB3 reserved BSA slot for fault buffer
Example 1: using the same $(DEV) for some of the signals in the ioc.
You don't need to load database records for all signals created with bsaAdd()
or bsaAddSecondary(). You can safely select only the set that makes sense for the
IOC.
Examples of prefix:
DEVICE_PREFIX = BPM:LI24:123
dbLoadRecords("db/bsa.db", "DEV=${DEVICE_PREFIX},PORT=bsaPort,BSAKEY=TMITAMC0,SECN=TMIT")
dbLoadRecords("db/bsa.db", "DEV=${DEVICE_PREFIX},PORT=bsaPort,BSAKEY=XFIXEDPAMC0,SECN=X")
dbLoadRecords("db/bsa.db", "DEV=${DEVICE_PREFIX},PORT=bsaPort,BSAKEY=YFIXEDPAMC0,SECN=Y")
# TMITAMC0 as the primary signal with 6 dependent secondary BSAs
dbLoadRecords("db/bsa.db", "DEV=${DEVICE_PREFIX},PORT=bsaPort,BSAKEY=TMIT0C0,SECN=TMITC0")
dbLoadRecords("db/bsa.db", "DEV=${DEVICE_PREFIX},PORT=bsaPort,BSAKEY=TMIT0C1,SECN=TMITC1")
dbLoadRecords("db/bsa.db", "DEV=${DEVICE_PREFIX},PORT=bsaPort,BSAKEY=TMIT0C2,SECN=TMITC2")
dbLoadRecords("db/bsa.db", "DEV=${DEVICE_PREFIX},PORT=bsaPort,BSAKEY=TMIT0C3,SECN=TMITC3")
dbLoadRecords("db/bsa.db", "DEV=${DEVICE_PREFIX},PORT=bsaPort,BSAKEY=TMIT0C4,SECN=TMITC4")
dbLoadRecords("db/bsa.db", "DEV=${DEVICE_PREFIX},PORT=bsaPort,BSAKEY=TMIT0C5,SECN=TMITC5")
This is the result for the example above with BSA user buffer 28:
BPM:LI24:123:TMITHST28 -> data array
BPM:LI24:123:TMITCNTHST28 -> number of samples for average array
BPM:LI24:123:TMITRMSHST28 -> RMS array
BPM:LI24:123:TMITPIDHST28 -> PID array
BPM:LI24:123:XHST28 -> data array
BPM:LI24:123:XCNTHST28 -> number of samples for average array
BPM:LI24:123:XRMSHST28 -> RMS array
BPM:LI24:123:XPIDHST28 -> PID array
BPM:LI24:123:YHST28 -> data array
BPM:LI24:123:YCNTHST28 -> number of samples for average array
BPM:LI24:123:YRMSHST28 -> RMS array
BPM:LI24:123:YPIDHST28 -> PID array
BPM:LI24:123:TMITC0HST28 -> data array
BPM:LI24:123:TMITC0CNTHST28 -> number of samples for average array
BPM:LI24:123:TMITC0RMSHST28 -> RMS array
BPM:LI24:123:TMITC0PIDHST28 -> PID array
(...)
BPM:LI24:123:TMITC5HST28 -> data array
BPM:LI24:123:TMITC5CNTHST28 -> number of samples for average array
BPM:LI24:123:TMITC5RMSHST28 -> RMS array
BPM:LI24:123:TMITC5PIDHST28 -> PID array
This is the result for the example above with BSA system buffer SCS at 10 Hz:
BPM:LI24:123:TMITHSTSCSTH -> data array
BPM:LI24:123:TMITCNTHSTSCSTH -> number of samples for average array
BPM:LI24:123:TMITRMSHSTSCSTH -> RMS array
BPM:LI24:123:TMITPIDHSTSCSTH -> PID array
BPM:LI24:123:XHSTSCSTH -> data array
BPM:LI24:123:XCNTHSTSCSTH -> number of samples for average array
BPM:LI24:123:XRMSHSTSCSTH -> RMS array
BPM:LI24:123:XPIDHSTSCSTH -> PID array
BPM:LI24:123:YHSTSCSTH -> data array
BPM:LI24:123:YCNTHSTSCSTH -> number of samples for average array
BPM:LI24:123:YRMSHSTSCSTH -> RMS array
BPM:LI24:123:YPIDHSTSCSTH -> PID array
BPM:LI24:123:TMITC0HSTSCSTH -> data array
BPM:LI24:123:TMITC0CNTHSTSCSTH -> number of samples for average array
BPM:LI24:123:TMITC0RMSHSTSCSTH -> RMS array
BPM:LI24:123:TMITC0PIDHSTSCSTH -> PID array
(...)
BPM:LI24:123:TMITC5HSTSCSTH -> data array
BPM:LI24:123:TMITC5CNTHSTSCSTH -> number of samples for average array
BPM:LI24:123:TMITC5RMSHSTSCSTH -> RMS array
BPM:LI24:123:TMITC5PIDHSTSCSTH -> PID array
Example 2: using different names of $(DEV) for signals in the IOC. In this case
we need to add the TPR macro.
Examples of prefixes:
TPR_PREFIX = TPR:GUNB:BP01:1
DEVICE1_PREFIX = BPM:GUNB:123
DEVICE2_PREFIX = BPM:GUNB:345
dbLoadRecords("db/bsa.db", "DEV=${DEVICE1_PREFIX},TPR=${TPR_PREFIX},PORT=bsaPort,BSAKEY=TMITAMC0,SECN=TMIT")
dbLoadRecords("db/bsa.db", "DEV=${DEVICE1_PREFIX},TPR=${TPR_PREFIX},PORT=bsaPort,BSAKEY=XFIXEDPAMC0,SECN=X")
dbLoadRecords("db/bsa.db", "DEV=${DEVICE1_PREFIX},TPR=${TPR_PREFIX},PORT=bsaPort,BSAKEY=YFIXEDPAMC0,SECN=Y")
dbLoadRecords("db/bsa.db", "DEV=${DEVICE2_PREFIX},TPR=${TPR_PREFIX},PORT=bsaPort,BSAKEY=TMITAMC1,SECN=TMIT")
dbLoadRecords("db/bsa.db", "DEV=${DEVICE2_PREFIX},TPR=${TPR_PREFIX},PORT=bsaPort,BSAKEY=XFIXEDPAMC1,SECN=X")
dbLoadRecords("db/bsa.db", "DEV=${DEVICE2_PREFIX},TPR=${TPR_PREFIX},PORT=bsaPort,BSAKEY=YFIXEDPAMC1,SECN=Y")
This is the result for the example above with BSA user buffer 25:
BPM:GUNB:123:TMITHST25 -> data array
BPM:GUNB:123:TMITCNTHST25 -> number of samples for average array
BPM:GUNB:123:TMITRMSHST25 -> RMS array
BPM:GUNB:123:TMITPIDHST25 -> PID array
BPM:GUNB:123:XHST25 -> data array
BPM:GUNB:123:XCNTHST25 -> number of samples for average array
BPM:GUNB:123:XRMSHST25 -> RMS array
BPM:GUNB:123:XPIDHST25 -> PID array
BPM:GUNB:123:YHST25 -> data array
BPM:GUNB:123:YCNTHST25 -> number of samples for average array
BPM:GUNB:123:YRMSHST25 -> RMS array
BPM:GUNB:123:YPIDHST25 -> PID array
BPM:GUNB:345:TMITHST25 -> data array
BPM:GUNB:345:TMITCNTHST25 -> number of samples for average array
BPM:GUNB:345:TMITRMSHST25 -> RMS array
BPM:GUNB:345:TMITPIDHST25 -> PID array
BPM:GUNB:345:XHST25 -> data array
BPM:GUNB:345:XCNTHST25 -> number of samples for average array
BPM:GUNB:345:XRMSHST25 -> RMS array
BPM:GUNB:345:XPIDHST25 -> PID array
BPM:GUNB:345:YHST25 -> data array
BPM:GUNB:345:YCNTHST25 -> number of samples for average array
BPM:GUNB:345:YRMSHST25 -> RMS array
BPM:GUNB:345:YPIDHST25 -> PID array
This is the result for the example above with BSA system buffer SCH at 100 Hz:
BPM:GUNB:123:TMITHSTSCHHH -> data array
BPM:GUNB:123:TMITCNTHSTSCHHH -> number of samples for average array
BPM:GUNB:123:TMITRMSHSTSCHHH -> RMS array
BPM:GUNB:123:TMITPIDHSTSCHHH -> PID array
BPM:GUNB:123:XHSTSCHHH -> data array
BPM:GUNB:123:XCNTHSTSCHHH -> number of samples for average array
BPM:GUNB:123:XRMSHSTSCHHH -> RMS array
BPM:GUNB:123:XPIDHSTSCHHH -> PID array
BPM:GUNB:123:YHSTSCHHH -> data array
BPM:GUNB:123:YCNTHSTSCHHH -> number of samples for average array
BPM:GUNB:123:YRMSHSTSCHHH -> RMS array
BPM:GUNB:123:YPIDHSTSCHHH -> PID array
BPM:GUNB:345:TMITHSTSCHHH -> data array
BPM:GUNB:345:TMITCNTHSTSCHHH -> number of samples for average array
BPM:GUNB:345:TMITRMSHSTSCHHH -> RMS array
BPM:GUNB:345:TMITPIDHSTSCHHH -> PID array
BPM:GUNB:345:XHSTSCHHH -> data array
BPM:GUNB:345:XCNTHSTSCHHH -> number of samples for average array
BPM:GUNB:345:XRMSHSTSCHHH -> RMS array
BPM:GUNB:345:XPIDHSTSCHHH -> PID array
BPM:GUNB:345:YHSTSCHHH -> data array
BPM:GUNB:345:YCNTHSTSCHHH -> number of samples for average array
BPM:GUNB:345:YRMSHSTSCHHH -> RMS array
BPM:GUNB:345:YPIDHSTSCHHH -> PID array
You see that the $(TPR) macro doesn't affect the final result for the list of
PVs available for usage. This macro is used with internal PVs and is required
in case you have different values for the $(DEV) macro.
In example 1, when not using the TPR macro, the internal PVs will result in:
BPM:LI24:123:PIDHST28
BPM:LI24:123:PIDHSTSCSTH
etc.
In example 2, by using the TPR macro the result will be:
TPR:GUNB:BP01:1:PIDHST25
TPR:GUNB:BP01:1:PIDHSTSCHHH
etc.
Example 3: Fault buffers
Prefixes:
TPR_PREFIX = TPR:GUNB:BP01:1
DEVICE_PREFIX = BPM:GUNB:123
BPM:GUNB:123:TMITHSTFLTB0 -> data array
BPM:GUNB:123:TMITCNTHSTFLTB0 -> number of samples for average array
BPM:GUNB:123:TMITRMSHSTFLTB0 -> RMS array
BPM:GUNB:123:TMITPIDHSTFLTB0 -> PID array
BPM:GUNB:123:XHSTFLTB0 -> data array
BPM:GUNB:123:XCNTHSTFLTB0 -> number of samples for average array
BPM:GUNB:123:XRMSHSTFLTB0 -> RMS array
BPM:GUNB:123:XPIDHSTFLTB0 -> PID array
BPM:GUNB:123:YHSTFLTB0 -> data array
BPM:GUNB:123:YCNTHSTFLTB0 -> number of samples for average array
BPM:GUNB:123:YRMSHSTFLTB0 -> RMS array
BPM:GUNB:123:YPIDHSTFLTB0 -> PID array
The same structure above is repeated for FLTB1, FLTB2, and FLTB3.
The 4 hidden PVs using $(TPR):
TPR:GUNB:BP01:1:PIDHSTFLTB0
TPR:GUNB:BP01:1:PIDHSTFLTB1
TPR:GUNB:BP01:1:PIDHSTFLTB2
TPR:GUNB:BP01:1:PIDHSTFLTB3
The database template loading can be located either before or after the driver
initialization.
=========== Consideration for NC/SC mode switching ===================
The bsa driver provides the following PV to enable and disable the bsa polling
$(TPR):SC_BSA_ENABLE
(0: Disable): BSA poll thread stops polling, we can use it for NC mode operation
(1: Enable): BSA poll thread poll BSA buffer status and process BSA history buffer PVs, we can use it for SC mode operation
IOC engineer (ioc application) can have a logic to integrate the SC_BSA_ENABLE PV to the NC/SC mode switching.
The default valuse is (1: Enable), the template doesn't support autosave and PINI==YES,
Suppose, the PV should be controlled by the NC/SC mode switching in the ioc application.
The bsa driver ioc shell command to enable and disable the bsa polling,
bsaAsynDriverDisable(["named root"]): disable BSA polling
bsaAsynDriverEnable(["named root"]): enable BSA polling
These commmands can be used after calling bsaAsynDriverConfigure() or, also works during ioc operation after iocInit().
=========== Known issue ==========
We've found out that sometimes the pProcessor->pending() and
pProcessor->update() fails to acquire data from the firmware. The reason for
this is still undiscovered in this version. When the IOC presents this fault,
one or more BSA buffers keep with old data and usually the IOC can't recover
from this condition. An IOC boot is required for it to recover.
There are two ways to check if this fault condition happened:
1. dbior bsaAsynDriver 1
Driver: bsaAsynDriver
named_root: root_0, port: bpmBsaPort, driver instace: 0x17727e0, number of BSA varibles: 8
bsa status: FAULT, fault cnt: 156
pend error: 0, update error: 4456
array update error (45): 4456
The report in the example above shows that the fault happened 4456 times and
the IOC transitioned from a normal status to a fault status 156 times. It also
shows that the BSA buffer number in fail is #45. All other BSA buffers are
running ok in this scenario.
2. EPICS PVs:
$(TPR):SC_BSA_STATUS -> Tells if the system is currently at a NORMAL or FAULT
status.
$(TPR):SC_BSA_FLTCNT -> Corresponds to the "fault cnt" number available with
dbior described above. It is the number of times that the IOC transitioned from
a normal status to a fault status.
=========== Instructions below are only for timing system engineers ===========
BSA buffer length change and Fault buffer length change
This is not supposed to be operated by IOC engineers. These are tools useful
for timing system engineers that are available for changing parameters for the
BSA system.
The BSA buffer length and fault buffer length are fixed (BSA length: 20,000 and
Fault buffer length: 1,000,000). bsaDriver has a way to allow for changes in the
lengths.
The buffer lengths are defined in epics ioc shell variables. You can check up
the values as in the following example:
epics>var bsa_length
bsa_length = 20000
epics>var fltb_length
fltb_length = 100000
You can change the variable with "var" command, but you must make the change
prior to any of the BSA driver related commands.
For example, we are going to double the length of both buffers.
epics>var bsa_length 40000
epics>var fltb_length 2000000
You must also change the waveform record length in bsa.db with two macros:
BSA_LENGTH and FLTB_LENGTH. If you do not specify the macros, they will assume
20,000 and 1,000,000 as default values.
Example:
dbLoadRecords("db/bsa.db", "DEV=TPG2:BSA,PORT=bsaPort,BSAKEY=PIDU,SECN=PIDU,BSA_LENGTH=40000,FLTB_LENGTH=2000000")
dbLoadRecords("db/bsa.db", "DEV=TPG2:BSA,PORT=bsaPort,BSAKEY=PIDL,SECN=PIDL,BSA_LENGTH=40000,FLTB_LENGTH=2000000")