![[SLAC Controls Department]](/grp/cd/soft/images/logo_cd.gif){kind=logo}
![[SLAC Home Page]](/grp/cd/soft/images/logo_slac.gif){kind=logo}
3.1 INTRODUCTION . . . . . . . . . . . . . . . . . . . 3-1
3.1.1 Hardware . . . . . . . . . . . . . . . . . . . . 3-2
3.1.2 Functions Available From SCP . . . . . . . . . . 3-3
3.1.2.1 Calibration . . . . . . . . . . . . . . . . . 3-3
3.1.2.2 Measurement . . . . . . . . . . . . . . . . . 3-4
3.1.2.3 Diagnostics . . . . . . . . . . . . . . . . . 3-5
3.1.3 Basic Protocol For Calibration And Measurement . 3-6
3.2 SCP CODE . . . . . . . . . . . . . . . . . . . . . 3-8
3.2.1 Panels . . . . . . . . . . . . . . . . . . . . . 3-8
3.2.2 Driver Routine (BPMDRVR) . . . . . . . . . . . . 3-9
3.2.3 Measurement Definitions . . . . . . . . . . . 3-10
3.2.3.1 Rationale . . . . . . . . . . . . . . . . . 3-12
3.2.3.2 Setting Parameters (BPMDRVR, BPM_RANGE,
3.2.3.3 Manipulating Measurement Definitions . . . . 3-14
3.2.3.3.1 Creation . . . . . . . . . . . . . . . . . 3-14
3.2.3.3.2 Selection . . . . . . . . . . . . . . . . 3-15
3.2.3.3.3 Saving And Restoring Measurement
3.2.4 Calibration Routines (BPMCAL, BPMCAL_*) . . . 3-16
3.2.4.1 Calibratione Downloading (BPMCAL_DOWNLOAD) . 3-19
3.2.5 Data Accumulation (BPMDATON And Entries BPMDAT,
3.2.6 Data Display (BPMDISP, BPMDISPZ, BPMDISPV) . . 3-21
3.2.7 Data Accumulation For Applications (BPM_AVG) . 3-22
3.2.8 Coroutines And Status Routine . . . . . . . . 3-23
3.2.9 Diagnostics . . . . . . . . . . . . . . . . . 3-24
3.2.9.1 TIMING (BPMSYNC) . . . . . . . . . . . . . . 3-24
3.2.9.2 Single Unit Functions . . . . . . . . . . . 3-24
3.2.10 Clean-up (BPMUNLOCK, BPMSTOP, BPMCANDEF) . . . 3-24
3.2.11 Miscellany . . . . . . . . . . . . . . . . . . 3-24
3.2.11.1 Logical Name Initialization (BPMINIT) . . . 3-24
3.2.11.2 Damping Ring Lifetime Display (BPM_DRLIFE) . 3-24
3.2.11.3 Damping Ring Ungated Read . . . . . . . . . 3-24
3.3 MICRO . . . . . . . . . . . . . . . . . . . . . 3-24
3.3.1 Over-all Control Structure (BPMO_DRVR) . . . . 3-24
3.3.2 Structure And Handling Of Beam Segments
3.3.3 Initialization (BPMINIT) . . . . . . . . . . . 3-25
3.3.4 Common Elements Of Calibration And Measurement: 3-25
3.3.4.1 Hardware Checks (PDU_CHECK, ONLINE, Re-get
3.3.4.2 Preparation (set Up Timing And Reading Camac
3.3.5 Calibration (CALBPREP, BEAMSEG$INIT, MUXSET,
3.3.6 Measurement (MEASPREP, BEAMSEG$PREP, ATTENPACK,
3.3.7 Clean-up (BEAMSEG$STOP, BEAMSEG$DEL, BPMCAN) . 3-25
3.3.8 Miscellany: . . . . . . . . . . . . . . . . . 3-25
3.3.8.1 Communication Between Fortran And PLM
3.3.8.2 Initialize When Crate Goes On (BPMPINIT) . . 3-26
3.4 (APPENDIX) DATABASE . . . . . . . . . . . . . . 3-26
3.5 (APPENDIX) OTHER DATA STRUCTURES . . . . . . . . 3-26
3.5.1 Calibration Files . . . . . . . . . . . . . . 3-26
3.5.2 Measurement Definition Files . . . . . . . . . 3-27
3.6 (APPENDIX) FUNCTION CODES (WITH FORM OF DATA) . 3-27
3.7 (APPENDIX) ROUTINES . . . . . . . . . . . . . . 3-27
3.7.1 Alphabetical, With Description Of Arguments . 3-27
3.7.2 By Function (who Calls Whom) . . . . . . . . . 3-27
3.8 (APPENDIX) DATABASE . . . . . . . . . . . . . . 3-27 CHAPTER 3 BPM SOFTWARE INTERNALS
3.1 INTRODUCTION The chief funtion of the BPM software is to enable the operator to take a "snapshot" of the particular beam he is interested in. Ideally (and in fact, in some parts of the SLC, such as the linac), the data returned to the operator should report the location of a single pulse as it travels along the operator-specified range within the SLC. In some parts of the SLC hardware limitations make this impossible. In such cases several pulses are required to return data for all the requested monitors. In any case readings along the range are synchronized by means of a request to the MPG to broadcast a special non-zero "YY" byte along with a particular "PP", corresponding to the beam for which the operator requests BPM measurement data. Software complications peculiar to the BPM code arise from the following considerations: 1. A single operator is likely to want BPM data from several parts of the SLC for several beams during a typical session.
BPM SOFTWARE INTERNALS Page 3-2 2. Several operators may want BPM data from from overlapping sets of micros at roughly the same time. 3. The entire procedure necessary to obtain BPM measurement data includes several steps which will, in general, be strung out over time. Information from earlier stages, peculiar to the beam code and particular SCP requesting the measurement, must be saved (some in the SCP; most in the micro) in a manner allowing reasonably speedy access and a minimum of wasted space. These considerations primarily affect the micro, where both time and space are at more of a premium.3.1.1 Hardware BPMs are logically and physically divided into two parts: a monitor and a processor. The monitor consists of four (or, in some parts of the machine, e.g. collider arcs, two) strips in which electrical charge is induced when the beam passes. Information pertaining to the monitors is stored in the database under the primary BPMS (or, for the two-strip monitors, BPMX or BPMY). The processor (database primary BPMP) takes the signals from the monitors and outputs digitized sum and (two) difference signals. In the linac each monitor is connected to a processor, but in other parts of the machine up to ten monitors may be multiplexed into a single BPMP by means of SP10T multiplexers. A detailed description of the hardware may be found in the appropriate chapter of the Hardware Manual. See also SLAC-TN-84-2, "SLC BPM System Maintenance and Diagnostics Manual."
BPM SOFTWARE INTERNALS Page 3-3 SLC Toroids are also controlled by the BPM software. Toroids are never multiplexed, so there is no reason to separate processor from monitor. All information pertaining to a toroid can be found in the primary TORO. A variety of analog devices read out through gated ADC's (primary GADC) are also accessed through BPM software. These devices (collectively and colloquially known as DUGADC's) include SLIT, GAPM, ARRY and WIRE. For them the GADC plays a role rather similar to the BPMP, while SLIT, GAPM, ARRY and WIRE are similar to BPMS (or BWMS). For a description of the BPMP, BPMS and TORO secondaries see the database appendix to this chapter.3.1.2 Functions Available From SCP
3.1.2.1 Calibration - Before the raw data output from BPM processors may be meaningfully converted to X- and Y- locations, the processors must be calibrated. The operator selects all the parameters relevant to the beam he wishes to measure (namely PP, bunch number, attenuation, range of micros, etc.) and stores them in a "Measurement Definition" on the BPMO START panel. He then attempts to calibrate. Possibly he will have to re-select some of the parameters before he can obtain usable calibration data. The calibration procedure is designed to determine the characteristics of the ADC's in the BPM processor when gathering data in the environment provided by the selected PP beam number. In particular,
BPM SOFTWARE INTERNALS Page 3-4 the calibration procedure measures pedestals for each ADC and the gains of the two difference ADC's relative to the sum ADC (note: calibration procedure will be different when hardware other than the standard BPMP processor is used). Data from the calibration is displayed and written to an unformatted disk file on the SCP end. Those pieces of information needed to calculate measurement data are also saved in the micro as long as the requesting SCP might need them.3.1.2.2 Measurement - Measurement data may be collected in two ways: by pushing the DATA START-STOP button on the BPMO MEASUREMENT PANEL (normally either the values or bar display will also be selected on this panel), or by a call to the routine BPM_AVG (in which case the data is not displayed in any form by the BPMO facility software). In either case, the data is stored in a common block accessible to all routines which include the file SLCSYS:BPMSCP.TXT. (Note: in the very near future the common block will be eliminated. Instead data will be stored in dynamically-allocated storage. Utility routines analogous to DBGET, DBLIST, etc. will be provided for callers of BPM_AVG to access the data.) The procedure actually followed to collect the data depends on the hardware in the sectors in the current range, being somewhat more complex in those sectors having multiplexed monitors. The differences are transparent to the operator. The returned data has the same form regardless of the type of hardware.
BPM SOFTWARE INTERNALS Page 3-53.1.2.3 Diagnostics - Several diagnostics are supported by the BPM facility software: 1. TIMING The TIMING button on the BPMO START panel allows the operator to take measurement data for a single sector, whether or not the sector has been calibrated. This is possible because only the raw data read from the three ADC's is returned; X- and Y-position are not reported. TIMING is used to determine the best value to set for BUNCH DELAY when a measurement definition is being created. It is classed as a diagnostic because, under normal operating circumstances, BUNCH DELAY should always be zero. In a future release of the BPM software the calculation of the optimum BUNCH DELAY will be done automatically during calibration. The TIMING button will be moved to the BPM DIAGNOSTICS panel so that the operator may override the automatic calculation. 2. Ungated read (rings only) Once beam has been stored in a ring, the appropriate time to take data can no longer be calculated as a fixed offset from fiducial time. Any such fixed offset will give readings with intolerably high variance. Instead, it is preferable to take data asynchronously, when the beam is strongest. This facility is provided by the UNGATED READ button on the BPMO DIAGNOSTICS panel. When it is pushed, data for any measurement definition whose range is one of the rings will be taken in ungated mode.
BPM SOFTWARE INTERNALS Page 3-6 3. Histograms (see also Correlation Plots) The BPM facility software provides several histograms, which may be selected from the BPMO DIAGNOSTICS panel. The histograms will be created as data is collected when the DATA START-STOP button is in its ON state. More sophisticated histograms of BPM data may be created by means of the Correlation Plots software. 4. HSTA toggles Operators may toggle the hardware status of any BPMS (monitor), BPMP (processor) or toroid from buttons on the BPMO DIAGNOSTICS panel. 5. DBS displays for a single unit All database information for a single BPMS, BPMP or toroid may be displayed by means of buttons on the BPMO DIAGNOSTICS panel.3.1.3 Basic Protocol For Calibration And Measurement BPM calibration and data-taking have the peculiar property of involving, at a minimum, three rather than two computers: the Vax, the micro with control over the sector from which data is requested, and the Master Pattern Generator (for synchronization). The protocol is as follows:
BPM SOFTWARE INTERNALS Page 3-7 1. Preparation When a start-up of data-taking has been requested, the SCP sends a request to each micro in the current range to prepare (but not execute) camac packages. The camac packages vary according to the hardware available in the sector. They may contain packets to program PDU's, set multiplexers, set attenuation in the BPMP's, and read the BPMP ADC's. The micro is requested to associate each camac package with a particular YY. The package will be executed when the YY is seen by the micro. At this time the BPM job may also need to request the TIMING job to program PDU's for a particular YY. 2. MPG request The SCP sends a request to the MPG to broadcast the YY's when it is also broadcasting the PP that is part of the current measurement definition. 3. Data processing in micro Upon receipt of the second YY in a pair the BPMO subjob is woken up by a "trickle-down" message. The raw data is massaged into a form suitable for the SCP. Finally, a response message may be sent to the SCP. 4. Data accumulation in SCP If the operation is calibration, data is stored in the SCP in dynamically allocated memory, one segment per micro in the current range (the memory is allocated when a measurement definition is created or selected). The data is also written
BPM SOFTWARE INTERNALS Page 3-8 to two disk files, one unformatted and one Ascii. The Ascii file is a permanent, human-readable record of the calibration results. The unformatted file is used by the SCP to recover calibration data in case the operator de-selects, then re-selects the measurement definition. It could also be used to restore calibration data to a micro which has been booted since its BPM's were last calibrated (not yet implemented). If the operation is measurement (includes the diagnostic TIMING), returned data is stored in a common block. The common block is accessible to any routine including SLCSYS:BPMSCP.TXT. In particular, it is accessible to application code, such as the Correlation Plot software, as well as to the BPM facility. It will probably be necessary in the near future to move to a dynamic allocation scheme for measurement data storage just as is now done for calibration. When this is done, a routines will be provided to allow access to the data to applications code.3.2 SCP CODE We now take a detailed look at the SCP code. The discussion here is organized by function. See Appendix ?? for an alphabetical list of routines with a short description of each.
3.2.1 Panels There are three panels for the BPMO facility software: BPMO Start-up
BPM SOFTWARE INTERNALS Page 3-9 (BPMSTART.PNL), BPMO Measurement (BPMOMEAS.PNL), and BPMO Diagnostics (BPMDIAG.PNL). On the Start-up panel measurement definitions are created (and may also be selected), calibrations are done, and the TIMING diagnostic may be used (because it may be necessary to do timing in order to find a workable value for bunch delay in the measurement definition). Measurements may be started or stopped from the Measurement panel, and the operator may toggle between the two available displays (values display or BPM versus Z) and between the different devices (BPM's or toroids). A measurement definition may also be re-selected from this panel. The Diagnostics panel supports single-unit displays for BPMP's, BPMS's or toroids, hardware status toggles for each of these three kinds of devices, histograms, and a toggle for ungated reading in the rings.3.2.2 Driver Routine (BPMDRVR) Most of the buttons for strictly BPMO functions on the BPMO START and BPMO MEASUREMENT panels cause BPMDRVR to be called. The major exceptions are the calibration buttons, the set of switches to select Display Group, the buttons for choosing measurement display, and the TIMING button. Several different button variables are used, depending on the function requested by the operator. [Note: this should be cleaned up. Certainly we could get by with fewer variables than are currently used.] If the CHANGE MICRO LIMITS button is pushed, the variable BPMRANGE will get the value ENTR. If a new display group is selected, the switch variable BPMDGRP will get a new value (and the entry BPM_RANGE_CLEAR will be called). If any of the other components of
BPM SOFTWARE INTERNALS Page 3-10 the measurement definition are to be changed, the variable BEAMDEFN will get an appropriate value (PP, BUNCH, etc.). If the UNLOCK button is pushed [Note: this function is nearly obsolete. It should be eliminated altogether or at least moved to the DIAGNOSTICS panel.] then BPMODIAG gets the value UNLOCK. If a new measurement definition is to be created or selected (by pushing one of the measurement definition buttons) BPMBEAM will get a value of BEAMDEF1, BEAMDEF2, etc., depending on the button pushed. When any of the buttons CREATE MEAS DEF, SAVE MEAS DEF or RESTOR MEAS DEF is pushed, the variable BPMDEF receives a value. If data is to be started or stopped, or if a new device for data-taking is to be selected, the variable BPMSAMPL gets a value. Where the function requested consists merely of updating the panel and internal variables, the work will generally be done entirely by BPMDRVR (although in many cases if data-taking is ongoing at the time the button is pushed, BPMDATOFF will be called first to turn it off; then BPMDRVR will do the updating). The more profound functions are handled by separate routines. For example, If data-taking is to be started BPMDRVR will call BPMDATON. If measurement definitions are to be created, selected, saved, or restored BPMDRVR will call the appropriate entry in BPMDEF_CREATE. In all cases BPMDRVR clears whatever button variable has been set by the button push.3.2.3 Measurement Definitions A Measurement Definition is a collection of parameter values which determine the conditions under which a set of BPM measurements (and the corresponding calibration) will be taken. The values are set by
BPM SOFTWARE INTERNALS Page 3-11 the operator or may be read in from a previously-saved Measurement Definition file (in the future, certain Measurement Definitions may be fixed and available with no operator action; e.g., the Measurement Definition appropriate for normal operation in CID). Currently the parameters composing a Measurement Definition are: the display group, the first and last micros in the range of micros from which the data is to be taken (must be consistent with display group), the PP beam number, the time slot, the bunch number (1, 2 or 3), the attenuation value to be set in the BPMP's (the same value is used throughout the range), the bunch delay (timing fudge factor which is normally zero), and the sign of the bunch (e- or e+). Soon the new display group parameter will be added. Ideally, at some time in the future attenuation and bunch delay will, by default, be set automatically and so will not appear on the BPMO START panel (but might be left on the Diagnostics panel for those who want to override the automatic settings). Internally, all this information is kept for each Measurement Definition in a set of arrays whose size is determined by the value of the parameter MAXDEFS (currently =5). The arrays are in the common block BPM_BEAMDEFS, defined in the include file SLCSYS:BPMBTNDEF.TXT. Certain other information pertinent to each Measurement Definition is also kept in arrays in this common block. For example, the logical array CAL_DEFS keeps track of which Measurement Definitions have valid calibrations. The array BPM_CALOK(2,MAXDEFS) consists of 64-bit masks for each Measurement Definition, indicating which micros have successful BPM calibrations for this Measurement Definition. The variable CURR_DEF (in BPM_BEAMDEFS) keeps track of which Measurement
BPM SOFTWARE INTERNALS Page 3-12 Definition, if any, is the currently active one; i.e., the one for which measurements will be taken if the DATA ON-OFF button is pushed, for which a calibration will be done if the CAL BPMO button is pushed, etc. If no Measurement Definition is selected CURR_DEF is set to zero. Similarly, CURR_SEG is the index used by the micro in its array of tokens (one for each active measurement definition). For now, CURR_SEG = 8*SCP_ID + CURR_DEF. Another group of variables carries much of the same information for the currently-selected Measurement Definition (or, if there is none, for the values of the parameters as displayed on the BPMO START panel). Most of these variable are in one of the common blocks BPM_BEAM_DEF or BPMPANEL, both defined in the file SLCSYS:BPMPANEL.TXT. Examples of such variables are PP, BUNCH, TS (in BPM_BEAM_DEF) and FMIC, LMIC, CFMIC, CLMIC (in BPMPANEL).3.2.3.1 Rationale - The rationale for the existence of Measurement Definitions is two-fold: 1. To allow the operator to move his attention from one group of BPM measurements (in one area of the machine, for a particular PP) to another (maybe in another area, for a possibly different PP) and back again as painlessly as possible.
BPM SOFTWARE INTERNALS Page 3-13 2. To allow different SCPs to take interleaved measurements over possibly overlapping sets of micros (this is accomplished by keeping sufficient information in the micro for each existing Measurement Definition, for each active SCP).3.2.3.2 Setting Parameters (BPMDRVR, BPM_RANGE, Entries BPM_AUTORANGE, - BPM_RANGE_CLEAR) Before creating a new Measurement Definition the operator will in general want to change one or more parameter values. As soon as the operator changes such a parameter, CURR_DEF and CURR_SEG are set to zero and the bar on the currently-selected Measurement Definition, if any, is erased. If data-taking has been going on, it is stopped. The simpler parameters (PP, BUNCH, TS, ATTENUATION, PARTICLE {e- or e+} and BUNCH DELAY) are handled entirely by BPMDRVR. Input is solicited from the operator if necessary, the panel is updated, and appropriate variables are changed. If a new DGRP is selected, the entry BPM_RANGE_CLEAR gets rid of the old micro range (since it usually will not be consistent with the new DGRP) in addition to stopping data-taking, setting CURR_DEF to zero, etc. If the values for the first or last micros are to be changed, BPMDRVR calls BPM_RANGE. BPM_RANGE solicits operator input, checks to make sure this range is consistent with the current DGRP, then flows into the entry BPM_AUTORANGE (which is called directly when a Measurement Definition is selected--see below). BPM_AUTORANGE sets up DISP_LIST, the list of all micros in the selected DGRP, and finds the location of the operator-chosen first and last micros in this list. It also initializes the display range to 'ALL'.
BPM SOFTWARE INTERNALS Page 3-143.2.3.3 Manipulating Measurement Definitions -
3.2.3.3.1 Creation - The process of creating a Measurement Definition with the current value of the parameters begins when the operator pushes the CREATE MEAS DEF button on the BPMO START panel. BPMDRVR sets the flag CREATE and returns control to the operator. To finish the process, the operator must push one of the Measurement Definition buttons on the bottom of the panel. The button variable BPMBEAM gets one of the values BEAMDEF1, BEAMDEF2, etc., depending on which Measurement Definition button has been pushed. The parameter values are then "stored in the button" by BPMDEF_CREATE (called by BPMDRVR). If the button previously contained a Measurement Definition, it is now lost. BPMDEF_CREATE updates internal Measurement Definition arrays with the information on the panel and, in some cases, with default initial values (e.g., CAL_FLAGS(idef) is set to .FALSE.). Certain simple variables are also set to default values (e.g., DEV_BPM is set to .TRUE. and DEV_TOR is set to FALSE.). A mask of the micros in the current range is created in the quadword CURR_MICROS and also stored in DGRP_MICROS(*,CURR_DEF). A bar is written to the appropriate Measurement Definition button and the previous bar, if any, is erased. FInally, BPMDEF_CREATE calls BPMGETDB to get current HSTA and other information for the relevant hardware and calls BPMGETVM to give back old virtual memory and get the right amount of new virtual memory in which to store calibration information.
BPM SOFTWARE INTERNALS Page 3-153.2.3.3.2 Selection - When the operator pushes a Measurement Definition button without first pushing the CREATE MEAS DEF button BPMDRVR instead calls BEAMDEF_SELECT, an entry in BEAMDEF_CREATE. This routine copies values from the Measurement Definition arrays to variables used to store current parameter values (e.g., PP, TS, etc.) and updates the BPMO START panel (if it is the currently selected panel) with these values. It also calls BPM_AUTORANGE, BPMGETDB and BPMGETVM. Finally, it reads in calibration data, if any, for this Measurement Definition so that it can be displayed on operator request.
3.2.3.3.3 Saving And Restoring Measurement Definitions - A set of currently defined Measurement Definitions may be "saved" (i.e., written to a disk file for later retrieval) by pushing the SAVE MEAS DEF button. The button variable BPMDEF gets the value BPMSAVE, so that BPMDRVR knows to call the entry BPMDEF_SAVE (in the routine BPMDEF_CREATE). BPDMEF_SAVE prompts the user for file name (directory is always SLCBPM: and filetype is always DEF) and writes out the necessary information. No changes are made to the Measurement Definitions themselves. Similarly, Measurement Definitions may be restored from a previously-written file by pushing the RESTORE MEAS DEF button. In this case BPMDEF gets the value BPMRSTOR and BPMDRVR calls the entry BPMDEF_RESTORE. This routine prompts for file name in the same manner as BPMDEF_SAVE, then reads the information into the Measurement Definition arrays. A Measurement Definition existing on the panel
BPM SOFTWARE INTERNALS Page 3-16 before the RESTORE button is pushed will be over-written iff there is a saved Measurement Definition corresponding to the same Measurement Definition button. The BPMO START panel is updated appropriately.3.2.4 Calibration Routines (BPMCAL, BPMCAL_*) Once a Measurement Definition has been selected, the operator may obtain new calibration data by pushing the CAL BPMO button on the BPMO START panel. DEXEC and the display BPMCAL are scheduled and the button variable BPMOCALI gets the value CALB. To display old calibration data, the CAL DISPLAY button must be pushed (on either BPMO START or BPMO MEASUREMENT), in which case the entry BPMCALD in BPMCAL is scheduled instead of BPMCAL, and the value of the variable is CALD. BPMCAL sets up two (64-bit) masks of micros in the selected range; one of those micros with cluster status on for BPMP's (BPM_CLUSTAT), the other with good cluster status for TORO's (TOR_CLUSTAT). These masks are part of the declared as two-dimensional arrays (e.g., BPM_CLUSTAT(2,MAXDEF)). The union of these two masks are the micros to which the SCP now sends a prep. message. The new mask BPM_CALOK (resp. TOR_CALOK) is then the intersection of those micros replying successfully to the prep. command and BPM_CLUSTAT (resp. TOR_CLUSTAT). These masks are also part of arrays indexed by Measurement Definition number. For a complete description of the data for the prep. message, see the Appendix???? Since there is no data (except for a single longword of status) in the micro acknowledgement to the prep. command, this return message is handled by the co-routine BPM_MSGCO, the least complex of the coroutine entries in
BPM SOFTWARE INTERNALS Page 3-17 the file SLCSYS:BPRMEAD.FOR. "Calibration" of the toroids is now complete; actual hardware calibration of toroids is, for now, done off-line. The SCP orchestrates calibration of the BPMP's by sending two sets of requests to the MPG. The first is used in the micro to make gain measurements, the second for pedestals. A set consists of ten separate requests, each for one pair of YY's to be broadcast. The reason for breaking up the broadcasts this way is so that one SCP does not monopolize the MPG with a single long chain. This way, other SCP's, working in other (disjoint) micro ranges, may continue BPM activities interleaved with the calibration. After the very first MPG request the SCP waits for acknowledgement from all micros in the BPM_CALOK mask. The coroutine used is again BPM_MSGCO. If no micros respond, it may mean that the MPG did not fulfill the broadcast request within the time limit, probably because the requested combination of PP and TS is not being braodcast, and calibration is aborted with an appropriate message to the operator. If some, but not all, micros respond, it probably means the non-responding micros have some defective hardware (e.g., PRIM or CAR) so that they never received the broadcast. BPM_CALOK is updated accordingly, since there is no point in attempting to calibrate such a micro. The next eight chain requests are sent without waiting for acknowledgement from the micros, but the SCP does wait for a reply after the last chain request used for gain measurement (this allows the micro to switch BPMP mode from gain to pedestal without danger of
BPM SOFTWARE INTERNALS Page 3-18 losing synchronization with the SCP). The coroutine is again BPM_MSGCO. Again, any micros which fail to respond with good status are deleted from the mask BPM_CALOK. Finally, the last chain request is made to the MPG. This time the SCP waits for the returned calibration data from the micros, stored by the coroutine BPMCALRD in the virtual memory obtained when the current Measurement Definition was selected. BPM_CALOK is updated the last time, to indicate which micros in the range completed the entire calibration procedure successfully. If calibration was at all successful (i.e., if at least one micro with BPM's or toroids was successfully calibrated), BPMCAL next call the routine BPMCAL_OPEN_FILE to open two disk files to contain the calibration results and to write appropriate header information to the files. One (VxxxPPppp.Bb, where xxx is the SCP id, ppp is the PP number for this Measurement Definition, and b is the button number -- between 1 and MAXDEF, inclusive -- for this Measurement Definition) is an Ascii file of essentially the same format as the video display, the other (VxxxPPpp.Ub) will contain the information unformatted. BPMCAL then updates the panel and does some other minor clean-up before flowing into the entry BPMCALD, in which the results are displayed. BPMCALD writes a couple header lines to the display. Then, for each micro it calls the routine BPMCAL_WRT_MICRO to display the data for that micro and, if a new calibration has been done, write information for the micro to the disk files. Finally, BPMCAL_FILE_CLOSE closes the files.
BPM SOFTWARE INTERNALS Page 3-193.2.4.1 Calibratione Downloading (BPMCAL_DOWNLOAD) - At times circumstances may be such that it is impossible or undesirable to re-calibrate, but old calibration data is known to be valid. For example it becomes impossible to accurately measure pedestals in the Damping Rings when there is stored beam. It is possible to download calibration data for one or more micros in the current range by pressing the CAL DOWNLOAD button on the BPMO START panel. The routine BPMCAL_DOWNLOAD prompts for micro (can be ALL*) and calibration file. The file must be a standard unformatted file such as is normally created upon successful calibration. BPMCAL_DOWNLOAD checks to see that the current DGRP is the same as the one in the file. If the attenuation values are not the same, the operator is warned and given an opportunity to abort. BPMCAL_DOWNLOAD then searches the file for the requested micro, calls BPMCAL_PTR to set up pointers into the dynamic storage allocated for the calibration data for this micro, calls BPMCAL_RSTR_MICRO to restore the data from the file to the dynamic storage, and calls BPMCAL_SEND to send the data accross the network. If the "micro" specified was actually ALL*, BPMCAL_DOWNLOAD simply reads through the entire calibration file. Whenever it finds a micro in the current range, it proceeds with all the steps listed above. Finally BPMCAL_DOWNLOAD writes a new unformatted calibration file which merges the new calibration data with any pre-existing calibration data for othermicros in the range. The same routines (BPMCAL_FILE_INIT, BPMCAL_WRT_MICRO, BPMCAL_FILE_CLOSE) are used as are used in a regular calibration, but they are called with arguments which specify that only the unformatted file is to be written. No formatted file is written nor is there any video display (although the operator can get it by pushing the CAL
BPM SOFTWARE INTERNALS Page 3-20 DISPLAY button).3.2.5 Data Accumulation (BPMDATON And Entries BPMDAT, BPMDATOFF) The operator initiates (resp. stops) data accumulation for display by pushing the START-STOP DATA button on the BPMO MEASUREMENT panel. The button variable BPMSAMPL gets the value DATA and BPMDRVR is called. BPMDRVR calls BPMDATON (resp. BPMDATOFF) and clears the button variable. BPMDAT and BPMDATOFF are both entries in the routine BPMDATON (file is SLCSYS:BPMDAT.FOR). BPMDATON starts up data-taking by sending a prep. request (see Appendix??? for data in the request) to all micros in the current range which completed calibration successfully for the selected hardware (BPM or toroid). The data for each micro in the range is slightly different (because T_NOMINAL may be different) so the prep. requests are sent with one MSG_WAIT for each micro in the range, followed by a single MSG_WAIT to accept all acknowledgements. BPM_MSGCO, the simplest coroutine, is used to handle the micro replies. If the preparation succeeds (i.e., if at least one micro is successful) the 64-bit mask MEAS_MASK is set to those micros which were successful, the routine (acutally group) BPMDAT is scheduled to do the actual data-taking, and, if selected, a LIST_PUT is done for one of the displays BPMDISPZ or BPMDISPV. Finally, BPMDAT is scheduled (NOW and CYCLE). BPMDAT handles the actual data collection for the displays. An appropriate request is sent to the MPG (varies depending on whether any multiplexed readings are to be done -- if so, 9 pairs of YY's are
BPM SOFTWARE INTERNALS Page 3-21 requested, otherwise just one pair) and the SCP waits for the data all with a single call to MPG_SYNC. The co-routine used is BPMREAD, which both collects status information and stores the data in fixed arrays in the common block BPM_DATA. If sufficiently severe error conditions occur (e.g., no response from any micros in the range) BPMDAT de-schedules itself, takes the bar off the DATA START-STOP button, etc.3.2.6 Data Display (BPMDISP, BPMDISPZ, BPMDISPV) BPMDISP and its entries BPMDISPZ and BPMDISPV handle all matters relating to the BPM data displays. At ACNTRL(1) .EQ. -1 BPMDISP initializes a number of variables used in the bar display (e.g. variables like NTICS and SECTO_XARRAY) and does a couple of LIST_VARS. BPMDISP will be called from the BPMO MEASUREMENT panel if the operator chooses to change the scale of the BPM vs. Z display. BPMDISPZ handles the BPM vs. Z display (background and foreground). If BPMDISPZ is being called for the first time after data has started coming in, if the operator has just changed the display range (possible values are ALL, FIRST and LAST, where these refer to the selected micro range), or if the operator has just changed the scale, code for generating the background display will be executed. This includes getting display Z's for the sectors and for the hardware (For now the bar display is only supported for BPMS's. Eventually toroids will also have a bar display); creating the axes, labels, and tics; and, if the sectors to be displayed are in the linac and the number of sectors is not too large, getting Z-positions for quads and correctors and displaying them. Whether or not the background display is
BPM SOFTWARE INTERNALS Page 3-22 generated on a particular call to BPMDISPZ, the foreground will be generated. Data has been stored in the common block BPMDATA by the co-routine BPMREAD. BPMDISPZ makes two passes through the data. The first is to find the maximum value of TMIT, used for normalizing the TMIT bar display. In the second pass display positions and colors are calculated and the data is displayed. BPMDISPV is called when the values display has been selected. BPMDISPV loops over the micros in the display range. Some of the information needed for the display is in the BPMDATA common block; a variable IND_DAT ("INDex into DATa arrays") is kept in order to locate this information. Other information needed for the display is in the database arrays initialized by BPMGETDB. For indexing into these arrays the variable STA_PTR is used. Finally, the values display needs to know the status of the processor corresponding to each BPMS displayed. This information is in the dynamic storage used for calibration information, which is moved to the local array STATP as needed, one micro at a time. The values display is also supported for toroids in a similar manner (except in this case there is no corresponding processor to worry about).3.2.7 Data Accumulation For Applications (BPM_AVG) Application code for correlation plots (of different sets of BPM data or of BPM data versus other variables) and for modeling needs acces to BPM data and needs to control when (and to some extent how) the data is collected. These needs are met by the routine BPM_AVG. Before applications code can successfully call BPM_AVG the operator must have as current a valid measurement definition which has been calibrated.
BPM SOFTWARE INTERNALS Page 3-23 Calls to BPM_AVG will then collect data from the micros in the current range. BPM_AVG is an I*4 function which will return .FALSE. if some problem occured serious enough to prevent valid data from being collected for ALL of the micros in the range. If some micros fail and some succeed, BPM_AVG will return some TRUE status. The calling sequence is ISS = BPM_AVG(NMEAS, DEVICE) where NMEAS is an INTEGER*4 variable which is the number of measurements to be averaged (between one and ten, inclusive) and DEVICE is a BYTE variable which may take on the values 1 (measure BPM's only), 2 (measure toroids only) or 3 (measure both). DEVICE is optional. If omitted it defaults to "measure BPMs only". Parameters for the values DEVICE may take on are defined in the include file SLCSYS:BPMPARAM.TXT. Essentially BPM_AVG does the work of a call to BPMDATON followed by a call to BPMDAT (except that there is no group scheduling) or, if it is determined that no measurement preparation is necessary, just a call to BPMDAT. The protocol is changed slightly because of the added flexibility needed to support the input arguments, and a small amount of extra code is needed to determine just when measurement preparation is necessary.3.2.8 Coroutines And Status Routine
BPM SOFTWARE INTERNALS Page 3-243.2.9 Diagnostics
3.2.9.1 TIMING (BPMSYNC) -
3.2.9.2 Single Unit Functions - 1. Select unit (BPMUNIT) 2. Display unit (BPMUNITD) 3. Toggle HSTA (BPMUNITH) 4. Histograms (BPMGET)
3.2.10 Clean-up (BPMUNLOCK, BPMSTOP, BPMCANDEF)
3.2.11 Miscellany
3.2.11.1 Logical Name Initialization (BPMINIT) -
3.2.11.2 Damping Ring Lifetime Display (BPM_DRLIFE) -
3.2.11.3 Damping Ring Ungated Read -
3.3 MICRO
3.3.1 Over-all Control Structure (BPMO_DRVR)
BPM SOFTWARE INTERNALS Page 3-253.3.2 Structure And Handling Of Beam Segments (relevant Parts Of BEAMDEF.P86; rationale for splitting code into Fortran and PLM pieces)
3.3.3 Initialization (BPMINIT)
3.3.4 Common Elements Of Calibration And Measurement:
3.3.4.1 Hardware Checks (PDU_CHECK, ONLINE, Re-get Relevant HSTAs) -
3.3.4.2 Preparation (set Up Timing And Reading Camac Packages; TIMEPACK, BPMPACK) - Trickle-down messages Data processing, reply to SCP
3.3.5 Calibration (CALBPREP, BEAMSEG$INIT, MUXSET, CALBPROC, BEAMSEG$CAL, MEASMULT)
3.3.6 Measurement (MEASPREP, BEAMSEG$PREP, ATTENPACK, BEAMSEG$PROC)
3.3.7 Clean-up (BEAMSEG$STOP, BEAMSEG$DEL, BPMCAN)
3.3.8 Miscellany:
BPM SOFTWARE INTERNALS Page 3-263.3.8.1 Communication Between Fortran And PLM (MISSING_LINK) -
3.3.8.2 Initialize When Crate Goes On (BPMPINIT) -
3.4 (APPENDIX) DATABASE
3.5 (APPENDIX) OTHER DATA STRUCTURES
3.5.1 Calibration Files Whenever a calibration is done, two files are written. One is an Ascii file which is essentially the same as the display generated. This file has several header records: a title line including a time stamp and SCP id, individual records for Display Group, micro range, PP, TS, bunch, bunch delay, attenuation, and beam button number, and then a couple of blank records. Then, for each micro there is a line for the Ascii microname. If the micro was successfully calibrated, this is followed by one record of calibration information for each BPMP. If the micro was not successfully calibrated, there is an explanatory line (e.g., "CALIBRATION FAILED" or "BPMs OFFLINE") The unformatted file only contains information for the micros which have successfully-calibrated BPMs (toroid-only sectors won't be included). This file has two header records. The first contains the name of the Display Group, the second a bitmap of the successfully calibrated micros. Then for each such micro there is a record containing the bitid of the micro, a record containing the number of BPMP units in the sector, and one record of calibration information for each BPMP.
BPM SOFTWARE INTERNALS Page 3-273.5.2 Measurement Definition Files
3.6 (APPENDIX) FUNCTION CODES (WITH FORM OF DATA)
3.7 (APPENDIX) ROUTINES
3.7.1 Alphabetical, With Description Of Arguments
3.7.2 By Function (who Calls Whom)
3.8 (APPENDIX) DATABASE