From 8a39ca74891e327f051f091030aa4bcbf7d126ff Mon Sep 17 00:00:00 2001 From: Joao Paulo Martins Date: Tue, 3 Sep 2019 14:20:24 +0200 Subject: [PATCH] Preparing the waveform record DBD-POD file; Creation of the menuFtype DBD-POD file --- .../db/{menuFtype.dbd => menuFtype.dbd.pod} | 9 + src/std/rec/waveformRecord.dbd.pod | 517 +++++++++++++++++- 2 files changed, 499 insertions(+), 27 deletions(-) rename src/ioc/db/{menuFtype.dbd => menuFtype.dbd.pod} (88%) diff --git a/src/ioc/db/menuFtype.dbd b/src/ioc/db/menuFtype.dbd.pod similarity index 88% rename from src/ioc/db/menuFtype.dbd rename to src/ioc/db/menuFtype.dbd.pod index ff20e0ca4..fd643f625 100644 --- a/src/ioc/db/menuFtype.dbd +++ b/src/ioc/db/menuFtype.dbd.pod @@ -7,6 +7,15 @@ # and higher are distributed subject to a Software License Agreement found # in file LICENSE that is included with this distribution. #************************************************************************* + +=head1 Menu menuFtype + +This menu is used for the C field of all record types. + +=menu menuFtype + +=cut + menu(menuFtype) { choice(menuFtypeSTRING,"STRING") choice(menuFtypeCHAR,"CHAR") diff --git a/src/std/rec/waveformRecord.dbd.pod b/src/std/rec/waveformRecord.dbd.pod index db2fa05fb..e40aa2a21 100644 --- a/src/std/rec/waveformRecord.dbd.pod +++ b/src/std/rec/waveformRecord.dbd.pod @@ -1,35 +1,13 @@ -#************************************************************************* -# Copyright (c) 2002 The University of Chicago, as Operator of Argonne -# National Laboratory. -# Copyright (c) 2002 The Regents of the University of California, as -# Operator of Los Alamos National Laboratory. -# EPICS BASE is distributed subject to a Software License Agreement found -# in file LICENSE that is included with this distribution. -#************************************************************************* +=pod =title Waveform Record (waveform) -... - -=head2 Record-specific Menus - -=head3 Menu waveformPOST - -The MPST and APST fields use this menu to determine when to post new value -and archive monitors respectively. - -=menu waveformPOST - -... - -=head2 Parameter Fields - -The record-specific fields are described below. +The waveform record type is used to interface waveform digitizers. The record +stores its data in arrays. The array can contain any of the supported data +types. =recordtype waveform -... - =cut menu(waveformPOST) { @@ -39,7 +17,492 @@ menu(waveformPOST) { recordtype(waveform) { -=fields VAL, FTVL, MPST, APST +=pod + +=head1 Contents + +=over + +=item * L + +=over + +=item * L + +=item * L + +=item * L + +=item * L + +=back + +=item * L + +=over + +=item * L + +=item * L + +=back + +=item * L + +=over + +=item * L + +=item * L + +=item * L + +=back + +=back + +=begin html + +
+ +=end html + +=head2 Parameter Fields + +The waveform's fields fall into the following categories: + +=over + +=item * L; + +=item * L; + +=item * L; + +=item * L; + +=back + +=head3 Scan Parameters + +The waveform record has the standard fields for specifying under what +circumstances the record will be processed. These fields are listed in L. In addition, L explains how these fields are +used. Note that I/O event scanning is only supported for those card types that +interrupt. + +=head3 Read Parameters + +These fields are configurable by the user to specify how and from where the +record reads its data. How the INP field is configured determines where the +waveform gets its input. It can be a hardware address, a channel access or +database link, or a constant. Only in records that use soft device support can +the INP field be a channel access link, a database link, or a constant. +Otherwise, the INP field must be a hardware address. See L
for information on the format of hardware addresses and database +links. + +=head4 Fields related to waveform reading + +=fields DTYP, INP, NELM, FTVL, RARM + +The DTYP field must contain the name of the appropriate device support module. +The values retrieved from the input link are placed in an array referenced by +VAL. (If the INP link is a constant, elements can be placed in the array via +dbPuts.) NELM specifies the number of elements that the array will hold, while +FTVL specifies the data type of the elements. +The RARM field causes the device to re-arm when this field is set to 1. + +=head4 Possible data types for FTVL + +=begin html + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IndexIdentifierChoice String
0menuFtypeSTRINGSTRING
1menuFtypeCHARCHAR
2menuFtypeUCHARUCHAR
3menuFtypeSHORTSHORT
4menuFtypeUSHORTUSHORT
5menuFtypeLONGLONG
6menuFtypeULONGULONG
7menuFtypeFLOATFLOAT
8menuFtypeDOUBLEDOUBLE
9menuFtypeENUMENUM
+ + +=end html + +=head3 Operator Display Parameters + +These parameters are used to present meaningful data to the operator. They +display the value and other parameters of the waveform either textually or +graphically. + +=head4 Fields related to I + +=fields EGU, HOPR, LOPR, PREC, NAME, DESC + +EGU is a string of up to 16 characters describing the units that the waveform +measures. It is retrieved by the C<<< get_units >>> record support routine. + +The HOPR and LOPR fields set the upper and lower display limits for array +elements referenced by the VAL field. Both the C<<< get_graphic_double >>> and +C<<< get_control_double >>> record support routines retrieve these fields. + +The PREC field determines the floating point precision with which to display the +array values. It is used whenever the C<<< get_precision >>> record support +routine is called. + +See L for more on the record name (NAME) and +description (DESC) fields. + + +=head3 Alarm Parameters + +The waveform record has the alarm parameters common to all record types. L lists other fields related to a alarms that are common to all record +types. + +=head3 Monitor Parameters + +These parameters are used to determine when to send monitors placed on the VAL +field. The APST and MPST fields are a menu with choices "Always" and "On +Change". The default is "Always", thus monitors will normally be sent every time +the record processes. Selecting "On Change" causes a 32-bit hash of the VAL +field buffer to be calculated and compared with the previous hash value every +time the record processes; the monitor will only be sent if the hash is +different, indicating that the buffer has changed. Note that there is a small +chance that two different value buffers might result in the same hash value, so +for critical systems "Always" may be a better choice, even though it re-sends +duplicate data. + +=head4 Record fields related to I + +=fields APST, MPST, HASH + +=head4 Menu choices for C and C fields + +=menu waveformPOST + +=head3 Run-time Parameters + +These parameters are used by the run-time code for processing the waveform. They +are not configured using a configuration tool. Only the VAL field is modifiable +at run-time. + +VAL references the array where the waveform stores its data. The BPTR field +holds the address of the array. + +The NORD field holds a counter of the number of elements that have been read +into the array. It is reset to 0 when the device is rearmed. The BUSY field +indicates if the device is armed but has not yet been digitized. + +=fields VAL, BPTR, NORD, BUSY + +The following fields are used to operate the waveform in the simulation mode. +See L for more information on the simulation mode fields. + +=fields SIOL, SIML, SIMM, SIMS + +=begin html + +
+
+
+ +=end html + +=head2 Record Support + +=head3 Record Support Routines + +=head4 init_record + + static long init_record(waveformRecord *prec, int pass) + +Using NELM and FTVL space for the array is allocated. The array address is +stored in the record. + +This routine initializes SIMM with the value of SIML if SIML type is CONSTANT +link or creates a channel access link if SIML type is PV_LINK. VAL is likewise +initialized if SIOL is CONSTANT or PV_LINK. + +This routine next checks to see that device support is available and a device +support read routine is defined. If either does not exist, an error message is +issued and processing is terminated + +If device support includes C, it is called. + +=head4 process + + static long process(waveformRecord *prec) + +See L section below. + +=head4 cvt_dbaddr + + static long cvt_dbaddr(DBADDR *paddr) + +This is called by dbNameToAddr. It makes the dbAddr structure refer to the +actual buffer holding the result. + +=head4 get_array_info + + static long get_array_info(DBADDR *paddr, long *no_elements, long *offset) + +Obtains values from the array referenced by VAL. + +=head4 put_array_info + + static long put_array_info(DBADDR *paddr, long nNew) + +Writes values into the array referenced by VAL. + +=head4 get_units + + static long get_units(DBADDR *paddr, char *units) + +Retrieves EGU. + +=head4 get_prec + + static long get_precision(DBADDR *paddr, long *precision) + +Retrieves PREC if field is VAL field. Otherwise, calls C<<< recGblGetPrec() >>>. + +=head4 get_graphic_double + + static long get_graphic_double(DBADDR *paddr, struct dbr_grDouble *pgd) + +Sets the upper display and lower display limits for a field. If the field is VAL +the limits are set to HOPR and LOPR, else if the field has upper and lower +limits defined they will be used, else the upper and lower maximum values for +the field type will be used. + +Sets the following values: + + upper_disp_limit = HOPR + lower_disp_limit = LOPR + +=head4 get_control_double + + static long get_control_double(DBADDR *paddr, struct dbr_ctrlDouble *pcd) + +Sets the upper control and the lower control limits for a field. If the field is +VAL the limits are set to HOPR and LOPR, else if the field has upper and lower +limits defined they will be used, else the upper and lower maximum values for +the field type will be used. + +Sets the following values + + upper_ctrl_limit = HOPR + lower_ctrl_limit = LOPR + +=head3 Record Processing + +Routine process implements the following algorithm: + +=over + +=item 1. + +Check to see that the appropriate device support module exists. If it doesn't, +an error message is issued and processing is terminated with the PACT field +still set to TRUE. This ensures that processes will no longer be called for this +record. Thus error storms will not occur. + +=item 2. + +Call device support read routine. + +=item 3. + +If PACT has been changed to TRUE, the device support read routine has started +but has not completed writing the new value. In this case, the processing +routine merely returns, leaving PACT TRUE. + +=item 4. + +Check to see if monitors should be invoked. + +=over + +=item * + +Alarm monitors are invoked if the alarm status or severity has changed. + +=item * + +Archive and value change monitors are invoked if APST or MPST are Always or if +the result of the hash calculation is different. + +=item * + +NSEV and NSTA are reset to 0. + +=back + +=item 5. + +Scan forward link if necessary, set PACT FALSE, and return. + +=back + +=begin html + +
+
+
+ +=end html + +=head2 Device Support + +=head3 Fields Of Interest To Device Support + +Each waveform record must have an associated set of device support routines. The +primary responsibility of the device support routines is to obtain a new array +value whenever read_wf is called. The device support routines are primarily +interested in the following fields: + +=fields PACT, DPVT, NSEV, NSTA, INP, NELM, FTVL, RARM, BPTR, NORD, BUSY + +=head3 Device Support Routines + +Device support consists of the following routines: + +=head4 long report(int level) + +This optional routine is called by the IOC command C and is passed the +report level that was requested by the user. +It should print a report on the state of the device support to stdout. +The C parameter may be used to output increasingly more detailed +information at higher levels, or to select different types of information with +different levels. +Level zero should print no more than a small summary. + +=head4 long init(int after) + +This optional routine is called twice at IOC initialization time. +The first call happens before any of the C calls are made, with +the integer parameter C set to 0. +The second call happens after all of the C calls have been made, +with C set to 1. + +=head4 init_record + + init_record(precord) + +This routine is optional. If provided, it is called by the record support +C routine. + +=head4 get_ioint_info + + get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt) + +This routine is called by the ioEventScan system each time the record is added +or deleted from an I/O event scan list. cmd has the value (0,1) if the +record is being (added to, deleted from) an I/O event list. It must be +provided for any device type that can use the ioEvent scanner. + +=head4 read_wf + + read_wf(precord) + +This routine must provide a new input value. It returns the following values: + +=over + +=item * + +0: Success. + +=item * + +Other: Error. + +=back + +=head3 Device Support For Soft Records + +The C<<< Soft Channel >>> device support module is provided to read values from +other records and store them in arrays. If INP is a constant link, then read_wf +does nothing. In this case, the record can be used to hold arrays written via +dbPuts. If INP is a database or channel access link, the new array value is read +from the link. NORD is set. + +This module places a value directly in VAL. + +If the INP link type is constant, then NORD is set to zero. If the INP link type +is PV_LINK, then dbCaAddInlink is called by C. + +read_wf calls recGblGetLinkValue which performs the following steps: + +=over + +=item * + +If the INP link type is CONSTANT recGblGetLinkValue does nothing. + +=item * + +If the INP link type is DB_LINK, then dbGetLink is called to obtain a new input +value. If dbGetLink returns an error, a LINK_ALARM with a severity of +INVALID_ALARM is raised. + +=item * + +If the INP link type is CA_LINK, then dbCaGetLink is called to obtain a new +input value. If dbCaGetLink returns an error, a LINK_ALARM with a severity of +INVALID_ALARM is raised. + +=item * + +NORD is set to the number of values returned and read_wf returns. + +=back =cut