From 93b47f103e1e5aa85621e48f08aeea0d0eab0231 Mon Sep 17 00:00:00 2001 From: Ralph Lange Date: Wed, 3 May 2017 16:17:07 +0200 Subject: [PATCH] std/rec: add and improve pod for int64in and int64out --- src/std/rec/int64inRecord.dbd | 161 ------- src/std/rec/int64inRecord.dbd.pod | 528 +++++++++++++++++++++ src/std/rec/int64outRecord.dbd.pod | 731 ++++++++++++++++------------- 3 files changed, 920 insertions(+), 500 deletions(-) delete mode 100644 src/std/rec/int64inRecord.dbd create mode 100644 src/std/rec/int64inRecord.dbd.pod diff --git a/src/std/rec/int64inRecord.dbd b/src/std/rec/int64inRecord.dbd deleted file mode 100644 index b603c709e..000000000 --- a/src/std/rec/int64inRecord.dbd +++ /dev/null @@ -1,161 +0,0 @@ -#************************************************************************* -# Copyright (c) 2014 UChicago Argonne LLC, 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. -#************************************************************************* -recordtype(int64in) { - include "dbCommon.dbd" - field(VAL,DBF_INT64) { - prompt("Current value") - promptgroup(GUI_INPUTS) - asl(ASL0) - pp(TRUE) - } - field(INP,DBF_INLINK) { - prompt("Input Specification") - promptgroup(GUI_INPUTS) - interest(1) - } - field(EGU,DBF_STRING) { - prompt("Units name") - promptgroup(GUI_DISPLAY) - interest(1) - size(16) - prop(YES) - } - field(HOPR,DBF_INT64) { - prompt("High Operating Range") - promptgroup(GUI_DISPLAY) - interest(1) - prop(YES) - } - field(LOPR,DBF_INT64) { - prompt("Low Operating Range") - promptgroup(GUI_DISPLAY) - interest(1) - prop(YES) - } - field(HIHI,DBF_INT64) { - prompt("Hihi Alarm Limit") - promptgroup(GUI_ALARMS) - pp(TRUE) - interest(1) - prop(YES) - } - field(LOLO,DBF_INT64) { - prompt("Lolo Alarm Limit") - promptgroup(GUI_ALARMS) - pp(TRUE) - interest(1) - prop(YES) - } - field(HIGH,DBF_INT64) { - prompt("High Alarm Limit") - promptgroup(GUI_ALARMS) - pp(TRUE) - interest(1) - prop(YES) - } - field(LOW,DBF_INT64) { - prompt("Low Alarm Limit") - promptgroup(GUI_ALARMS) - pp(TRUE) - interest(1) - prop(YES) - } - field(HHSV,DBF_MENU) { - prompt("Hihi Severity") - promptgroup(GUI_ALARMS) - pp(TRUE) - interest(1) - menu(menuAlarmSevr) - } - field(LLSV,DBF_MENU) { - prompt("Lolo Severity") - promptgroup(GUI_ALARMS) - pp(TRUE) - interest(1) - menu(menuAlarmSevr) - } - field(HSV,DBF_MENU) { - prompt("High Severity") - promptgroup(GUI_ALARMS) - pp(TRUE) - interest(1) - menu(menuAlarmSevr) - } - field(LSV,DBF_MENU) { - prompt("Low Severity") - promptgroup(GUI_ALARMS) - pp(TRUE) - interest(1) - menu(menuAlarmSevr) - } - field(HYST,DBF_INT64) { - prompt("Alarm Deadband") - promptgroup(GUI_ALARMS) - interest(1) - } - field(AFTC, DBF_DOUBLE) { - prompt("Alarm Filter Time Constant") - promptgroup(GUI_ALARMS) - interest(1) - } - field(AFVL, DBF_DOUBLE) { - prompt("Alarm Filter Value") - special(SPC_NOMOD) - interest(3) - } - field(ADEL,DBF_INT64) { - prompt("Archive Deadband") - promptgroup(GUI_DISPLAY) - interest(1) - } - field(MDEL,DBF_INT64) { - prompt("Monitor Deadband") - promptgroup(GUI_DISPLAY) - interest(1) - } - field(LALM,DBF_INT64) { - prompt("Last Value Alarmed") - special(SPC_NOMOD) - interest(3) - } - field(ALST,DBF_INT64) { - prompt("Last Value Archived") - special(SPC_NOMOD) - interest(3) - } - field(MLST,DBF_INT64) { - prompt("Last Val Monitored") - special(SPC_NOMOD) - interest(3) - } - field(SIOL,DBF_INLINK) { - prompt("Sim Input Specifctn") - promptgroup(GUI_INPUTS) - interest(1) - } - field(SVAL,DBF_INT64) { - prompt("Simulation Value") - } - field(SIML,DBF_INLINK) { - prompt("Sim Mode Location") - promptgroup(GUI_INPUTS) - interest(1) - } - field(SIMM,DBF_MENU) { - prompt("Simulation Mode") - interest(1) - menu(menuYesNo) - } - field(SIMS,DBF_MENU) { - prompt("Sim mode Alarm Svrty") - promptgroup(GUI_INPUTS) - interest(2) - menu(menuAlarmSevr) - } -} diff --git a/src/std/rec/int64inRecord.dbd.pod b/src/std/rec/int64inRecord.dbd.pod new file mode 100644 index 000000000..fb8cb3f71 --- /dev/null +++ b/src/std/rec/int64inRecord.dbd.pod @@ -0,0 +1,528 @@ +#************************************************************************* +# Copyright (c) 2014 UChicago Argonne LLC, 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. +#************************************************************************* + +=title 64bit Integer Input Record (int64in) + +This record type is normally used to obtain an integer value of up to 64 bits +from a hardware input. +The record supports alarm limits, alarm filtering, graphics and control +limits. + +=head2 Parameter Fields + +The record-specific fields are described below. + +=recordtype int64in + +=cut + +recordtype(int64in) { + +=head3 Input Specification + +These fields control where the record will read data from when it is processed: + +=fields DTYP, INP + +The DTYP field selects which device support layer should be responsible for +providing input data to the record. +The int64in device support layers provided by EPICS Base are documented in the +L section. +External support modules may provide additional device support for this record +type. +If not set explicitly, the DTYP value defaults to the first device support that +is loaded for the record type, which will usually be the C support +that comes with Base. + +The INP link field contains a database or channel access link or provides +hardware address information that the device support uses to determine where the +input data should come from. +The format for the INP field value depends on the device support layer that is +selected by the DTYP field. +See L
for a description of the various hardware +address formats supported. + +=head3 Operator Display Parameters + +These parameters are used to present meaningful data to the operator. +They do not affect the functioning of the record. + +=over + +=item * +DESC is a string that is usually used to briefly describe the record. + +=item * +EGU is a string of up to 16 characters naming the engineering units +that the VAL field represents. + +=item * +The HOPR and LOPR fields set the upper and lower display limits for the VAL, +HIHI, HIGH, LOW, and LOLO fields. + +=back + +=fields DESC, EGU, HOPR, LOPR + +=head3 Alarm Limits + +The user configures limit alarms by putting numerical values into the HIHI, +HIGH, LOW and LOLO fields, and by setting the associated alarm severity in the +corresponding HHSV, HSV, LSV and LLSV menu fields. + +The HYST field controls hysteresis to prevent alarm chattering from an input +signal that is close to one of the limits and suffers from significant readout +noise. + +The AFTC field sets the time constant on a low-pass filter that delays the +reporting of limit alarms until the signal has been within the alarm range for +that number of seconds (the default AFTC value of zero retains the previous +behavior). + +The LALM field is used by the record at run-time to implement the alarm limit +functionality. + +=fields HIHI, HIGH, LOW, LOLO, HHSV, HSV, LSV, LLSV, HYST, AFTC, LALM + +=head3 Monitor Parameters + +These parameters are used to determine when to send monitors placed on the VAL +field. +The monitors are sent when the current value exceeds the last transmitted value +by the appropriate deadband. +If these fields are set to zero, a monitor will be triggered every time the +value changes; if set to -1, a monitor will be sent every time the record is +processed. + +The ADEL field sets the deadband for archive monitors (C events), while +the MDEL field controls value monitors (C events). + +The remaining fields are used by the record at run-time to implement the record +monitoring deadband functionality. + +=fields ADEL, MDEL, ALST, MLST + +=cut + + include "dbCommon.dbd" + field(VAL,DBF_INT64) { + prompt("Current value") + promptgroup(GUI_INPUTS) + asl(ASL0) + pp(TRUE) + } + field(INP,DBF_INLINK) { + prompt("Input Specification") + promptgroup(GUI_INPUTS) + interest(1) + } + field(EGU,DBF_STRING) { + prompt("Units name") + promptgroup(GUI_DISPLAY) + interest(1) + size(16) + prop(YES) + } + field(HOPR,DBF_INT64) { + prompt("High Operating Range") + promptgroup(GUI_DISPLAY) + interest(1) + prop(YES) + } + field(LOPR,DBF_INT64) { + prompt("Low Operating Range") + promptgroup(GUI_DISPLAY) + interest(1) + prop(YES) + } + field(HIHI,DBF_INT64) { + prompt("Hihi Alarm Limit") + promptgroup(GUI_ALARMS) + pp(TRUE) + interest(1) + prop(YES) + } + field(LOLO,DBF_INT64) { + prompt("Lolo Alarm Limit") + promptgroup(GUI_ALARMS) + pp(TRUE) + interest(1) + prop(YES) + } + field(HIGH,DBF_INT64) { + prompt("High Alarm Limit") + promptgroup(GUI_ALARMS) + pp(TRUE) + interest(1) + prop(YES) + } + field(LOW,DBF_INT64) { + prompt("Low Alarm Limit") + promptgroup(GUI_ALARMS) + pp(TRUE) + interest(1) + prop(YES) + } + field(HHSV,DBF_MENU) { + prompt("Hihi Severity") + promptgroup(GUI_ALARMS) + pp(TRUE) + interest(1) + menu(menuAlarmSevr) + } + field(LLSV,DBF_MENU) { + prompt("Lolo Severity") + promptgroup(GUI_ALARMS) + pp(TRUE) + interest(1) + menu(menuAlarmSevr) + } + field(HSV,DBF_MENU) { + prompt("High Severity") + promptgroup(GUI_ALARMS) + pp(TRUE) + interest(1) + menu(menuAlarmSevr) + } + field(LSV,DBF_MENU) { + prompt("Low Severity") + promptgroup(GUI_ALARMS) + pp(TRUE) + interest(1) + menu(menuAlarmSevr) + } + field(HYST,DBF_INT64) { + prompt("Alarm Deadband") + promptgroup(GUI_ALARMS) + interest(1) + } + field(AFTC, DBF_DOUBLE) { + prompt("Alarm Filter Time Constant") + promptgroup(GUI_ALARMS) + interest(1) + } + field(AFVL, DBF_DOUBLE) { + prompt("Alarm Filter Value") + special(SPC_NOMOD) + interest(3) + } + field(ADEL,DBF_INT64) { + prompt("Archive Deadband") + promptgroup(GUI_DISPLAY) + interest(1) + } + field(MDEL,DBF_INT64) { + prompt("Monitor Deadband") + promptgroup(GUI_DISPLAY) + interest(1) + } + field(LALM,DBF_INT64) { + prompt("Last Value Alarmed") + special(SPC_NOMOD) + interest(3) + } + field(ALST,DBF_INT64) { + prompt("Last Value Archived") + special(SPC_NOMOD) + interest(3) + } + field(MLST,DBF_INT64) { + prompt("Last Val Monitored") + special(SPC_NOMOD) + interest(3) + } + +=head3 Simulation Mode + +The record provides several fields to support simulation of absent hardware. +If the SIML field is set it is used to read a value into the SIMM field, which +controls whether simulation is used or not: + +=over + +=item * +SIMM must be zero (C) for the record to request a value from the device +support. + +=item * +If SIMM is C and the SIOL link field is set, a simulated value in +engineering units is read using the link into the SVAL field, from where it will +subsequently be copied into the VAL field. + +=back + +The SIMS field can be set to give the record an alarm severity while it is in +simulation mode. + +=fields SIML, SIMM, SIOL, SVAL, SIMS + +=cut + + field(SIOL,DBF_INLINK) { + prompt("Sim Input Specifctn") + promptgroup(GUI_INPUTS) + interest(1) + } + field(SVAL,DBF_INT64) { + prompt("Simulation Value") + } + field(SIML,DBF_INLINK) { + prompt("Sim Mode Location") + promptgroup(GUI_INPUTS) + interest(1) + } + field(SIMM,DBF_MENU) { + prompt("Simulation Mode") + interest(1) + menu(menuYesNo) + } + field(SIMS,DBF_MENU) { + prompt("Sim mode Alarm Svrty") + promptgroup(GUI_INPUTS) + interest(2) + menu(menuAlarmSevr) + } +} + +=head2 Record Support + +=head3 Record Support Routines + +The following are the record support routines that would be of interest +to an application developer. +Other routines are the C, C, +C and C routines, which are used to +collect properties from the record for the complex DBR data structures. + +=head4 init_record + +This routine first initializes the simulation mode mechanism by setting SIMM +if SIML is a constant, and setting SVAL if SIOL is a constant. + +It then checks if the device support and the device support's +C routine are defined. +If either one does not exist, an error message is issued +and processing is terminated. + +If device support includes C, it is called. + +Finally, the deadband mechanisms for monitors and level alarms are +initialized. + +=head4 process + +See next section. + +=head3 Record Processing + +Routine C implements the following algorithm: + +=over + +=item 1. + +Check to see that the appropriate device support module and its +C routine are defined. +If either one does not exist, an error message is issued and processing is +terminated with the PACT field set to TRUE, effectively blocking the record +to avoid error storms. + +=item 2. + +Determine the value: + +If PACT is TRUE, call the device support C routine and return. + +If PACT is FALSE, read the value, honoring simulation mode: + +=over + +=item * Get SIMM by reading the SIML link. + +=item * If SIMM is C, +call the device support C routine and return. + +=item * If SIMM is C, +read the simulated value into SVAL using the SIOL link, +then copy the value into VAL and set UDF to 0 on success. + +=item * Raise an alarm for other values of SIMM. + +=item * Set the record to the severity configured in SIMS. + +=back + +=item 3. + +If PACT has been changed to TRUE, the device support signals asynchronous +processing: its C output routine has started, but not +completed reading the new value. +In this case, the processing routine merely returns, leaving PACT TRUE. + +=item 4. + +Set PACT to TRUE. Get the processing time stamp. Set UDF to 0 if reading +the value was successful. + +=item 5. + +Check UDF and level alarms: This routine checks to see if the record is +undefined (UDF is TRUE) or if the new VAL causes the alarm status +and severity to change. In the latter case, NSEV, NSTA and LALM are set. +It also honors the alarm hysteresis factor (HYST): the value must change +by at least HYST between level alarm status and severity changes. +If AFTC is set, alarm level filtering is applied. + +=item 6. + +Check to see if monitors should be invoked: + +=over + +=item * Alarm monitors are posted if the alarm status or severity have +changed. + +=item * Archive and value change monitors are posted if ADEL and MDEL +conditions (see L) are met. + +=back + +=item 7. + +Scan (process) forward link if necessary, set PACT to FALSE, and return. + +=back + +=head2 Device Support + +=head3 Device Support Interface + +The record requires device support to provide an entry table (dset) which +defines the following members: + + typedef struct { + long number; + long (*report)(int level); + long (*init)(int after); + long (*init_record)(int64inRecord *prec); + long (*get_ioint_info)(int cmd, int64inRecord *prec, IOSCANPVT *piosl); + long (*read_int64in)(int64inRecord *prec); + } int64indset; + +The module must set C to at least 5, and provide a pointer to its +C routine; the other function pointers may be C if their +associated functionality is not required for this support layer. +Most device supports also provide an C routine to configure the +record instance and connect it to the hardware or driver support layer. + +The individual routines are described below. + +=head3 Device Support 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 long init_record(int64inRecord *prec) + +This optional routine is called by the record initialization code for each +int64in record instance that has its DTYP field set to use this device support. +It is normally used to check that the INP address is the expected type and that +it points to a valid device; to allocate any record-specific buffer space and +other memory; and to connect any communication channels needed for the +C routine to work properly. + +=head4 long get_ioint_info(int cmd, int64inRecord *prec, IOSCANPVT *piosl) + +This optional routine is called whenever the record's SCAN field is being +changed to or from the value C to find out which I/O Interrupt Scan +list the record should be added to or deleted from. +If this routine is not provided, it will not be possible to set the SCAN field +to the value C at all. + +The C parameter is zero when the record is being added to the scan list, +and one when it is being removed from the list. +The routine must determine which interrupt source the record should be connected +to, which it indicates by the scan list that it points the location at C<*piosl> +to before returning. +It can prevent the SCAN field from being changed at all by returning a non-zero +value to its caller. + +In most cases the device support will create the I/O Interrupt Scan lists that +it returns for itself, by calling C once for +each separate interrupt source. +That routine allocates memory and inializes the list, then passes back a pointer +to the new list in the location at C<*piosl>. + +When the device support receives notification that the interrupt has occurred, +it announces that to the IOC by calling C +which will arrange for the appropriate records to be processed in a suitable +thread. +The C routine is safe to call from an interrupt service routine +on embedded architectures (vxWorks and RTEMS). + +=head4 long read_int64in(int64inRecord *prec) + +This essential routine is called when the record wants a new value from the +addressed device. +It is responsible for performing (or at least initiating) a read operation, and +(eventually) returning its value to the record. + +If the device may take more than a few microseconds to return the new value, +this routine must never block (busy-wait), but use the asynchronous +processing mechanism. +In that case it signals the asynchronous operation by setting the record's +PACT field to TRUE before it returns, having arranged for the record's +C routine to be called later once the read operation is finished. +When that happens, the C routine will be called again with +PACT still set to TRUE; it should then set it to FALSE to indicate the read +has completed, and return. + +A return value of zero indicates success, any other value indicates that an +error occurred. + +=head3 Extended Device Support + +... + +=cut + +=head2 Device Support For Soft Records + +Two soft device support modules, Soft Channel and Soft Callback Channel, are +provided for input records not related to actual hardware devices. The +INP link type must be either a CONSTANT, DB_LINK, or CA_LINK. + +=head3 Soft Channel + +This module reads the value using the record's INP link. + +C calls C to read the value. + +=head3 Soft Callback Channel + +This module is like the previous except that it reads the value +using asynchronous processing that will not complete until an asynchronous +processing of the INP target record has completed. + +=cut diff --git a/src/std/rec/int64outRecord.dbd.pod b/src/std/rec/int64outRecord.dbd.pod index 4abe969d2..4903d2da4 100644 --- a/src/std/rec/int64outRecord.dbd.pod +++ b/src/std/rec/int64outRecord.dbd.pod @@ -7,7 +7,7 @@ # in file LICENSE that is included with this distribution. #************************************************************************* -=title Int64 (64bit Integer) Output Record (int64out) +=title 64bit Integer Output Record (int64out) This record type is normally used to send an integer value of up to 64 bits to an output device. @@ -45,279 +45,323 @@ The new output value is taken from the VAL field, which may have been set from elsewhere. =item * -If OMSL is C the DOL link field is read to obtain a value. +If OMSL is C the DOL link field is used to obtain a value. =back =head4 Drive Limits -The output value is now clipped to the range DRVL to DRVH inclusive, provided +The output value is clipped to the range DRVL to DRVH inclusive, provided that DRVH > DRVL. The result is copied into the VAL field. =head3 Output Specification -The int64 output record sends its desired output to the address in the -OUT field. For int64 outputs that write their values to devices, the -OUT field must specify the address of the I/O card. In addition, the -DTYP field must contain the name of the device support module. Be aware -that the address format differs according to the I/O bus used. See -Address Specification for information on the format of hardware -addresses. - -For soft records the output link can be a database link, a channel -access link, or a constant value. If the link is a constant, no output -is sent. See Address Specification for information on the format of -database and channel access addresses. +These fields control where the record will read data from when it is processed: =fields DTYP, OUT +The DTYP field selects which device support layer should be responsible for +writing output data. +The int64out device support layers provided by EPICS Base are documented in the +L section. +External support modules may provide additional device support for this record +type. +If not set explicitly, the DTYP value defaults to the first device support that +is loaded for the record type, which will usually be the C support +that comes with Base. + +The OUT link field contains a database or channel access link or provides +hardware address information that the device support uses to determine where the +output data should be sent to. +The format for the OUT field value depends on the device support layer that is +selected by the DTYP field. +See L
for a description of the various hardware +address formats supported. + =head3 Operator Display Parameters These parameters are used to present meaningful data to the operator. -They display the value and other parameters of the analog output either -textually or graphically. +They do not affect the functioning of the record. -EGU is a string of up to 16 characters describing the units that the -int64 output measures. It is retrieved by the get_units record support -routine. +=over -The HOPR and LOPR fields set the upper and lower display limits for the -VAL, HIHI, HIGH, LOW, and LOLO fields. -Both the get_graphic_double and get_control_double record support routines -retrieve these fields. If these values are defined, they must fulfill -LOPR E= HOPR. +=item * +DESC is a string that is usually used to briefly describe the record. -See Fields Common to All Record Types for more on the record name -(NAME) and description (DESC) fields. +=item * +EGU is a string of up to 16 characters naming the engineering units +that the VAL field represents. -=fields EGU, HOPR, LOPR, NAME, DESC +=item * +The HOPR and LOPR fields set the upper and lower display limits for the VAL, +HIHI, HIGH, LOW, and LOLO fields. -=head3 Alarm Parameters +=back -Possible alarm conditions for int64 outputs are UDF, SCAN, WRITE, -INVALID and limit alarms. The UDF, SCAN, WRITE, and INVALID alarms are -called by the record or device support routines. +=fields DESC, EGU, HOPR, LOPR -The limit alarms are configured by the user in the HIHI, LOLO, HIGH, -and LOW fields, which must be int64 values. For each of these -fields, there is a corresponding severity field which can be either -NO_ALARM, MINOR, MAJOR or INVALID. +=head3 Alarm Limits -See Alarm Specification for a complete explanation of alarms and these -fields. See Invalid Alarm Output Action for more information on the -IVOA and IVOV fields. Alarm Fields lists other fields related to a -alarms that are common to all record types. +The user configures limit alarms by putting numerical values into the HIHI, +HIGH, LOW and LOLO fields, and by setting the associated alarm severities +in the corresponding HHSV, HSV, LSV and LLSV menu fields. -=fields HIHI, HIGH, LOW, LOLO, HHSV, HSV, LSV, LLSV, HYST, IVOA, IVOV +The HYST field controls hysteresis to prevent alarm chattering from an input +signal that is close to one of the limits and suffers from significant readout +noise. + +The LALM field is used by the record at run-time to implement the alarm limit +hysteresis functionality. + +=fields HIHI, HIGH, LOW, LOLO, HHSV, HSV, LSV, LLSV, HYST, LALM =head3 Monitor Parameters -These parameters are used to specify deadbands for monitors on the VAL -field. The monitors are sent when the value field exceeds the last -monitored field by the specified deadband. If these fields have a value -of zero, everytime the value changes, a monitor will be triggered; if -they have a value of -1, everytime the record is processed, monitors -are triggered. ADEL is the deadband for archive monitors, and MDEL the -deadband for all other types of monitors. See Monitor Specification for -a complete explanation of monitors. +These parameters are used to determine when to send monitors placed on the VAL +field. +The monitors are sent when the current value exceeds the last transmitted value +by the appropriate deadband. +If these fields are set to zero, a monitor will be triggered every time the +value changes; if set to -1, a monitor will be sent every time the record is +processed. -=fields ADEL, MDEL +The ADEL field sets the deadband for archive monitors (C events), while +the MDEL field controls value monitors (C events). -=head3 Run-time and Simulation Mode Parameters +The remaining fields are used by the record at run-time to implement the record +monitoring deadband functionality. -These parameters are used by the run-time code for processing the -int64 output. They are not configurable. They represent the current -state of the record. The record support routines use some of them for -more efficient processing. - -The LALM, MLST, and ALST fields are used to implement the hysteresis -factors for monitor callbacks. - -=fields LALM, ALST, MLST - -The following fields are used to operate the analog output in the -simulation mode. See Fields Common to Many Record Types for more -information on these fields. - -=fields SIOL, SIML, SIMM, SIMS +=fields ADEL, MDEL, ALST, MLST =cut - include "dbCommon.dbd" - field(VAL,DBF_INT64) { - prompt("Desired Output") - promptgroup(GUI_OUTPUT) - asl(ASL0) - pp(TRUE) - } - field(OUT,DBF_OUTLINK) { - prompt("Output Specification") - promptgroup(GUI_OUTPUT) - interest(1) - } - field(DOL,DBF_INLINK) { - prompt("Desired Output Loc") - promptgroup(GUI_OUTPUT) - interest(1) - } - field(OMSL,DBF_MENU) { - prompt("Output Mode Select") - promptgroup(GUI_OUTPUT) - interest(1) - menu(menuOmsl) - } - field(EGU,DBF_STRING) { - prompt("Units name") - promptgroup(GUI_DISPLAY) - interest(1) - size(16) - prop(YES) - } - field(DRVH,DBF_INT64) { - prompt("Drive High Limit") - promptgroup(GUI_OUTPUT) - pp(TRUE) - interest(1) - prop(YES) - } - field(DRVL,DBF_INT64) { - prompt("Drive Low Limit") - promptgroup(GUI_OUTPUT) - pp(TRUE) - interest(1) - prop(YES) - } - field(HOPR,DBF_INT64) { - prompt("High Operating Range") - promptgroup(GUI_DISPLAY) - interest(1) - prop(YES) - } - field(LOPR,DBF_INT64) { - prompt("Low Operating Range") - promptgroup(GUI_DISPLAY) - interest(1) - prop(YES) - } - field(HIHI,DBF_INT64) { - prompt("Hihi Alarm Limit") - promptgroup(GUI_ALARMS) - pp(TRUE) - interest(1) - prop(YES) - } - field(LOLO,DBF_INT64) { - prompt("Lolo Alarm Limit") - promptgroup(GUI_ALARMS) - pp(TRUE) - interest(1) - prop(YES) - } - field(HIGH,DBF_INT64) { - prompt("High Alarm Limit") - promptgroup(GUI_ALARMS) - pp(TRUE) - interest(1) - prop(YES) - } - field(LOW,DBF_INT64) { - prompt("Low Alarm Limit") - promptgroup(GUI_ALARMS) - pp(TRUE) - interest(1) - prop(YES) - } - field(HHSV,DBF_MENU) { - prompt("Hihi Severity") - promptgroup(GUI_ALARMS) - pp(TRUE) - interest(1) - menu(menuAlarmSevr) - } - field(LLSV,DBF_MENU) { - prompt("Lolo Severity") - promptgroup(GUI_ALARMS) - pp(TRUE) - interest(1) - menu(menuAlarmSevr) - } - field(HSV,DBF_MENU) { - prompt("High Severity") - promptgroup(GUI_ALARMS) - pp(TRUE) - interest(1) - menu(menuAlarmSevr) - } - field(LSV,DBF_MENU) { - prompt("Low Severity") - promptgroup(GUI_ALARMS) - pp(TRUE) - interest(1) - menu(menuAlarmSevr) - } - field(HYST,DBF_INT64) { - prompt("Alarm Deadband") - promptgroup(GUI_ALARMS) - interest(1) - } - field(ADEL,DBF_INT64) { - prompt("Archive Deadband") - promptgroup(GUI_DISPLAY) - interest(1) - } - field(MDEL,DBF_INT64) { - prompt("Monitor Deadband") - promptgroup(GUI_DISPLAY) - interest(1) - } - field(LALM,DBF_INT64) { - prompt("Last Value Alarmed") - special(SPC_NOMOD) - interest(3) - } - field(ALST,DBF_INT64) { - prompt("Last Value Archived") - special(SPC_NOMOD) - interest(3) - } - field(MLST,DBF_INT64) { - prompt("Last Val Monitored") - special(SPC_NOMOD) - interest(3) - } - field(SIOL,DBF_OUTLINK) { - prompt("Sim Output Specifctn") - promptgroup(GUI_INPUTS) - interest(1) - } - field(SIML,DBF_INLINK) { - prompt("Sim Mode Location") - promptgroup(GUI_INPUTS) - interest(1) - } - field(SIMM,DBF_MENU) { - prompt("Simulation Mode") - interest(1) - menu(menuYesNo) - } - field(SIMS,DBF_MENU) { - prompt("Sim mode Alarm Svrty") - promptgroup(GUI_INPUTS) - interest(2) - menu(menuAlarmSevr) - } - field(IVOA,DBF_MENU) { - prompt("INVALID output action") - promptgroup(GUI_OUTPUT) - interest(2) - menu(menuIvoa) - } - field(IVOV,DBF_INT64) { - prompt("INVALID output value") - promptgroup(GUI_OUTPUT) - interest(2) - } + include "dbCommon.dbd" + field(VAL,DBF_INT64) { + prompt("Desired Output") + promptgroup(GUI_OUTPUT) + asl(ASL0) + pp(TRUE) + } + field(OUT,DBF_OUTLINK) { + prompt("Output Specification") + promptgroup(GUI_OUTPUT) + interest(1) + } + field(DOL,DBF_INLINK) { + prompt("Desired Output Loc") + promptgroup(GUI_OUTPUT) + interest(1) + } + field(OMSL,DBF_MENU) { + prompt("Output Mode Select") + promptgroup(GUI_OUTPUT) + interest(1) + menu(menuOmsl) + } + field(EGU,DBF_STRING) { + prompt("Units name") + promptgroup(GUI_DISPLAY) + interest(1) + size(16) + prop(YES) + } + field(DRVH,DBF_INT64) { + prompt("Drive High Limit") + promptgroup(GUI_OUTPUT) + pp(TRUE) + interest(1) + prop(YES) + } + field(DRVL,DBF_INT64) { + prompt("Drive Low Limit") + promptgroup(GUI_OUTPUT) + pp(TRUE) + interest(1) + prop(YES) + } + field(HOPR,DBF_INT64) { + prompt("High Operating Range") + promptgroup(GUI_DISPLAY) + interest(1) + prop(YES) + } + field(LOPR,DBF_INT64) { + prompt("Low Operating Range") + promptgroup(GUI_DISPLAY) + interest(1) + prop(YES) + } + field(HIHI,DBF_INT64) { + prompt("Hihi Alarm Limit") + promptgroup(GUI_ALARMS) + pp(TRUE) + interest(1) + prop(YES) + } + field(LOLO,DBF_INT64) { + prompt("Lolo Alarm Limit") + promptgroup(GUI_ALARMS) + pp(TRUE) + interest(1) + prop(YES) + } + field(HIGH,DBF_INT64) { + prompt("High Alarm Limit") + promptgroup(GUI_ALARMS) + pp(TRUE) + interest(1) + prop(YES) + } + field(LOW,DBF_INT64) { + prompt("Low Alarm Limit") + promptgroup(GUI_ALARMS) + pp(TRUE) + interest(1) + prop(YES) + } + field(HHSV,DBF_MENU) { + prompt("Hihi Severity") + promptgroup(GUI_ALARMS) + pp(TRUE) + interest(1) + menu(menuAlarmSevr) + } + field(LLSV,DBF_MENU) { + prompt("Lolo Severity") + promptgroup(GUI_ALARMS) + pp(TRUE) + interest(1) + menu(menuAlarmSevr) + } + field(HSV,DBF_MENU) { + prompt("High Severity") + promptgroup(GUI_ALARMS) + pp(TRUE) + interest(1) + menu(menuAlarmSevr) + } + field(LSV,DBF_MENU) { + prompt("Low Severity") + promptgroup(GUI_ALARMS) + pp(TRUE) + interest(1) + menu(menuAlarmSevr) + } + field(HYST,DBF_INT64) { + prompt("Alarm Deadband") + promptgroup(GUI_ALARMS) + interest(1) + } + field(ADEL,DBF_INT64) { + prompt("Archive Deadband") + promptgroup(GUI_DISPLAY) + interest(1) + } + field(MDEL,DBF_INT64) { + prompt("Monitor Deadband") + promptgroup(GUI_DISPLAY) + interest(1) + } + field(LALM,DBF_INT64) { + prompt("Last Value Alarmed") + special(SPC_NOMOD) + interest(3) + } + field(ALST,DBF_INT64) { + prompt("Last Value Archived") + special(SPC_NOMOD) + interest(3) + } + field(MLST,DBF_INT64) { + prompt("Last Val Monitored") + special(SPC_NOMOD) + interest(3) + } + +=head3 Simulation Mode + +The record provides several fields to support simulation of absent hardware. +If the SIML field is set it is used to read a value into the SIMM field, +which controls whether simulation is used or not: + +=over + +=item * +SIMM must be zero (C) for the record to write a value to the device +support. + +=item * +If SIMM is C and the SIOL link field is set, the value in engineering +units is written using the link. + +=back + +The SIMS field can be set to give the record an alarm severity while it is in +simulation mode. + +=fields SIML, SIMM, SIOL, SIMS + +=cut + + field(SIOL,DBF_OUTLINK) { + prompt("Sim Output Specifctn") + promptgroup(GUI_INPUTS) + interest(1) + } + field(SIML,DBF_INLINK) { + prompt("Sim Mode Location") + promptgroup(GUI_INPUTS) + interest(1) + } + field(SIMM,DBF_MENU) { + prompt("Simulation Mode") + interest(1) + menu(menuYesNo) + } + field(SIMS,DBF_MENU) { + prompt("Sim mode Alarm Svrty") + promptgroup(GUI_INPUTS) + interest(2) + menu(menuAlarmSevr) + } + +=head3 Invalid Alarm Output Action + +Whenever an output record is put into INVALID alarm severity, IVOA specifies +the action to take. + +=over + +=item C (default) + +Write the value. Same as if severity is lower than INVALID. + +=item C + +Do not write value. + +=item C + +Set VAL to IVOV, then write the value. + +=back + +=fields IVOA, IVOV + +=cut + + field(IVOA,DBF_MENU) { + prompt("INVALID output action") + promptgroup(GUI_OUTPUT) + interest(2) + menu(menuIvoa) + } + field(IVOV,DBF_INT64) { + prompt("INVALID output value") + promptgroup(GUI_OUTPUT) + interest(2) + } } =head2 Record Support @@ -325,128 +369,131 @@ information on these fields. =head3 Record Support Routines The following are the record support routines that would be of interest -to an application developer. Other routines are the C, -C, C, and C -routines. +to an application developer. +Other routines are the C, C, +C and C routines, which are used to +collect properties from the record for the complex DBR data structures. -=over +=head4 init_record -=item init_record +This routine first initializes the simulation mode mechanism by setting SIMM +if SIML is a constant. -This routine initializes SIMM if SIML is a constant or creates a -channel access link if SIML is PV_LINK. If SIOL is PV_LINK, a channel -access link is created. - -The routine next checks to see if the device support write routine is -defined. If either device support or the device support write routine -does not exist, an error message is issued and processing is -terminated. +It then checks if the device support and the device support's +C routine are defined. +If either one does not exist, an error message is issued +and processing is terminated. If DOL is a constant, then VAL is initialized with its value and UDF is set to FALSE. -If device support includes init_record, it is called. +If device support includes C, it is called. -=item process +Finally, the deadband mechanisms for monitors and level alarms are +initialized. + +=head4 process See next section. -=item get_alarm_double - -Sets the following values: - - upper_alarm_limit = HIHI - upper_warning_limit = HIGH - lower_warning_limit = LOW - lower_alarm_limit = LOLO - -=back - =head3 Record Processing Routine C 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 set to TRUE. This ensures that processes -will no longer be called for this record. Thus error storms will not -occur. +=item 1. -=item 2. Check PACT. If PACT is FALSE, do the following: +Check to see that the appropriate device support module and its +C routine are defined. +If either one does not exist, an error message is issued and processing is +terminated with the PACT field set to TRUE, effectively blocking the record +to avoid error storms. + +=item 2. + +Check PACT. If PACT is FALSE, do the following: =over -=item * Fetch value for closed loop mode: -if DOL is not a CONSTANT and OMSL is CLOSED_LOOP then get value from DOL. -In case of success, set UDF to FALSE. +=item * Determine value, honoring closed loop mode: +if DOL is not a CONSTANT and OMSL is CLOSED_LOOP then get value from DOL +setting UDF to FALSE in case of success, else use the VAL field. -=item * Call convert: -if Drive limits are defined then force value to be within limits. +=item * Call C: +if drive limits are defined then force value to be within those limits. =back -=item 3. Check alarms: This routine checks to see if the new VAL causes -the alarm status and severity to change. If so, NSEV, NSTA and LALM are -set. It also honors the alarm hysteresis factor (HYST). Thus the value -must change by at least HYST before the alarm status and severity is -changed. +=item 3. -=item 4. Check severity and write the new value. See Invalid Alarm -Output Action for details on how invalid alarms affect output records. +Check UDF and level alarms: This routine checks to see if the record is +undefined (UDF is TRUE) or if the new VAL causes the alarm status +and severity to change. In the latter case, NSEV, NSTA and LALM are set. +It also honors the alarm hysteresis factor (HYST): the value must change +by at least HYST between level alarm status and severity changes. -=item 5. If PACT has been changed to TRUE, the device support write -output routine has started but has not completed writing the new value. +=item 4. + +Check severity and write the new value. See L +for details on how invalid alarms affect output records. + +=item 5. + +If PACT has been changed to TRUE, the device support signals asynchronous +processing: its C output routine has started, but not +completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE. -=item 6. Check to see if monitors should be invoked: +=item 6. + +Check to see if monitors should be invoked: =over -=item * Alarm monitors are invoked if the alarm status or severity has +=item * Alarm monitors are posted if the alarm status or severity have changed. -=item * Archive and value change monitors are invoked if ADEL and MDEL -conditions are met. +=item * Archive and value change monitors are posted if ADEL and MDEL +conditions (see L) are met. =item * NSEV and NSTA are reset to 0. =back -=item 7. Scan forward link if necessary, set PACT FALSE, and return. +=item 7. + +Scan (process) forward link if necessary, set PACT to FALSE, and return. =back =head2 Device Support -=head3 Fields Of Interest To Device Support +=head3 Device Support Interface -Each analog output record must have an associated set of device support -routines. The primary responsibility of the device support routines is -to output a new value whenever write_ao is called. The device support -routines are primarily interested in the following fields: +The record requires device support to provide an entry table (dset) which +defines the following members: -=over + typedef struct { + long number; + long (*report)(int level); + long (*init)(int after); + long (*init_record)(int64outRecord *prec); + long (*get_ioint_info)(int cmd, int64outRecord *prec, IOSCANPVT *piosl); + long (*write_int64out)(int64outRecord *prec); + } int64outdset; -=item * -PACT E Process Active, used to indicate asynchronous completion +The module must set C to at least 5, and provide a pointer to its +C routine; the other function pointers may be C if their +associated functionality is not required for this support layer. +Most device supports also provide an C routine to configure the +record instance and connect it to the hardware or driver support layer. -=item * -DPVT E Device Private, reserved for device support to use +The individual routines are described below. -=item * -OUT E Output Link, provides addressing information +=head3 Device Support Routines -=back - -=head3 Device Support routines - -Device support consists of the following routines: - -=over - -=item C +=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. @@ -456,7 +503,7 @@ information at higher levels, or to select different types of information with different levels. Level zero should print no more than a small summary. -=item C +=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 @@ -464,16 +511,16 @@ 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. -=item C +=head4 long init_record(int64outRecord *prec) This optional routine is called by the record initialization code for each int64out record instance that has its DTYP field set to use this device support. -It is normally used to check that the OUT address has the expected type and -points to a valid device; to allocate any record-specific buffer space and -other memory; and to connect any communication channels needed for the +It is normally used to check that the OUT address is the expected type and that +it points to a valid device, to allocate any record-specific buffer space and +other memory, and to connect any communication channels needed for the C routine to work properly. -=item C +=head4 long get_ioint_info(int cmd, int64outRecord *prec, IOSCANPVT *piosl) This optional routine is called whenever the record's SCAN field is being changed to or from the value C to find out which I/O Interrupt Scan @@ -492,8 +539,9 @@ value to its caller. In most cases the device support will create the I/O Interrupt Scan lists that it returns for itself, by calling C once for each separate interrupt source. -That API allocates memory and inializes the list, then passes back a pointer to -the new list in the location at C<*piosl>. +That routine allocates memory and inializes the list, then passes back a pointer +to the new list in the location at C<*piosl>. + When the device support receives notification that the interrupt has occurred, it announces that to the IOC by calling C which will arrange for the appropriate records to be processed in a suitable @@ -501,29 +549,35 @@ thread. The C routine is safe to call from an interrupt service routine on embedded architectures (vxWorks and RTEMS). -=item C +=head4 long write_int64out(int64outRecord *prec) + +This essential routine is called when the record wants to write a new value +to the addressed device. +It is responsible for performing (or at least initiating) a write operation, +using the value from the record's VAL field. + +If the device may take more than a few microseconds to accept the new value, +this routine must never block (busy-wait), but use the asynchronous +processing mechanism. +In that case it signals the asynchronous operation by setting the record's +PACT field to TRUE before it returns, having arranged for the record's +C routine to be called later once the write operation is over. +When that happens, the C routine will be called again with +PACT still set to TRUE; it should then set it to FALSE to indicate the write +has completed, and return. -This essential routine is called whenever the record has a new output value to -send to the device. It is responsible for performing the write operation, using -the value found in the record's VAL field. A return value of zero indicates success, any other value indicates that an error occurred. -This routine must not block (busy-wait) if the device takes more than a few -microseconds to accept the new value. In that case the routine must use -asynchronous completion to tell the record when the write operation eventually -completes. It signals that this is an asynchronous operation by setting the -record's PACT field to TRUE before it returns, having arranged for the record's -C routine to be called later once the write operation is over. When -that happens the C routine will be called again with PACT still -set to TRUE; it should then set it to FALSE to indicate the write has completed, -and return. +=head3 Extended Device Support -=back +... + +=cut =head2 Device Support For Soft Records -Two soft device support modules Soft Channel and Soft Callback Channel are +Two soft device support modules, Soft Channel and Soft Callback Channel, are provided for output records not related to actual hardware devices. The OUT link type must be either a CONSTANT, DB_LINK, or CA_LINK. @@ -531,13 +585,12 @@ OUT link type must be either a CONSTANT, DB_LINK, or CA_LINK. This module writes the current value using the record's VAL field. -write_int64out calls C to write the current value. -See Soft Output for details. +C calls C to write the current value. =head3 Soft Callback Channel This module is like the previous except that it writes the current value -using asynchronuous processing that will not finish until an asynchronuous -processing of the target record has finished. +using asynchronous processing that will not complete until an asynchronous +processing of the target record has completed. =cut