From 1235ad76e78bd48a6a56c325bb2ee33150821750 Mon Sep 17 00:00:00 2001 From: Ralph Lange Date: Tue, 2 May 2017 13:51:44 +0200 Subject: [PATCH] std/rec: add pod documentation content for int64out --- src/std/rec/int64outRecord.dbd.pod | 359 +++++++++++++++++++++++++++++ 1 file changed, 359 insertions(+) diff --git a/src/std/rec/int64outRecord.dbd.pod b/src/std/rec/int64outRecord.dbd.pod index fc088ed69..4abe969d2 100644 --- a/src/std/rec/int64outRecord.dbd.pod +++ b/src/std/rec/int64outRecord.dbd.pod @@ -6,7 +6,144 @@ # EPICS BASE is distributed subject to a Software License Agreement found # in file LICENSE that is included with this distribution. #************************************************************************* + +=title Int64 (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. +The record supports alarm, drive, graphics and control limits. + +=head2 Parameter Fields + +The record-specific fields are described below. + +=recordtype int64out + +=cut + recordtype(int64out) { + +=head3 Output Value Determination + +These fields control how the record determines the value to be output when it +gets processed: + +=fields OMSL, DOL, DRVH, DRVL, VAL + +The following steps are performed in order during record processing. + +=head4 Fetch Value + +The OMSL menu field is used to determine whether the DOL link field +should be used during processing or not: + +=over + +=item * +If OMSL is C the DOL link field is not used. +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. + +=back + +=head4 Drive Limits + +The output value is now 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. + +=fields DTYP, OUT + +=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. + +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. + +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. + +See Fields Common to All Record Types for more on the record name +(NAME) and description (DESC) fields. + +=fields EGU, HOPR, LOPR, NAME, DESC + +=head3 Alarm Parameters + +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. + +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. + +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. + +=fields HIHI, HIGH, LOW, LOLO, HHSV, HSV, LSV, LLSV, HYST, IVOA, IVOV + +=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. + +=fields ADEL, MDEL + +=head3 Run-time and Simulation Mode Parameters + +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 + +=cut + include "dbCommon.dbd" field(VAL,DBF_INT64) { prompt("Desired Output") @@ -182,3 +319,225 @@ recordtype(int64out) { interest(2) } } + +=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. + +=over + +=item init_record + +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. + +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. + +=item 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 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 * Call convert: +if Drive limits are defined then force value to be within 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 4. Check severity and write the new value. See Invalid Alarm +Output Action for details on how invalid alarms affect output records. + +=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. +In this case, the processing routine merely returns, leaving PACT TRUE. + +=item 6. 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 ADEL and MDEL +conditions are met. + +=item * NSEV and NSTA are reset to 0. + +=back + +=item 7. Scan forward link if necessary, set PACT FALSE, and return. + +=back + +=head2 Device Support + +=head3 Fields Of Interest To Device Support + +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: + +=over + +=item * +PACT E Process Active, used to indicate asynchronous completion + +=item * +DPVT E Device Private, reserved for device support to use + +=item * +OUT E Output Link, provides addressing information + +=back + +=head3 Device Support routines + +Device support consists of the following routines: + +=over + +=item C + +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. + +=item C + +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. + +=item C + +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 +C routine to work properly. + +=item C + +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 API 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). + +=item C + +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. + +=back + +=head2 Device Support For Soft Records + +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. + +=head3 Soft Channel + +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. + +=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. + +=cut