std/rec: add pod documentation content for int64out
This commit is contained in:
Ralph Lange
@@ -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<supervisory> 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<closed_loop> 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<lt>= 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<get_units>,
|
||||
C<get_precision>, C<get_graphic_double>, and C<get_control_double>
|
||||
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<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 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<mdash> Process Active, used to indicate asynchronous completion
|
||||
|
||||
=item *
|
||||
DPVT E<mdash> Device Private, reserved for device support to use
|
||||
|
||||
=item *
|
||||
OUT E<mdash> Output Link, provides addressing information
|
||||
|
||||
=back
|
||||
|
||||
=head3 Device Support routines
|
||||
|
||||
Device support consists of the following routines:
|
||||
|
||||
=over
|
||||
|
||||
=item C<long report(int level)>
|
||||
|
||||
This optional routine is called by the IOC command C<dbior> 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<level> 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<long init(int after)>
|
||||
|
||||
This optional routine is called twice at IOC initialization time.
|
||||
The first call happens before any of the C<init_record()> calls are made, with
|
||||
the integer parameter C<after> set to 0.
|
||||
The second call happens after all of the C<init_record()> calls have been made,
|
||||
with C<after> set to 1.
|
||||
|
||||
=item C<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
|
||||
C<write_int64out()> routine to work properly.
|
||||
|
||||
=item C<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<I/O Intr> 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<I/O Intr> at all.
|
||||
|
||||
The C<cmd> 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<void scanIoInit(IOSCANPVT *piosl)> 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<void scanIoRequest(IOSCANPVT iosl)>
|
||||
which will arrange for the appropriate records to be processed in a suitable
|
||||
thread.
|
||||
The C<scanIoRequest()> routine is safe to call from an interrupt service routine
|
||||
on embedded architectures (vxWorks and RTEMS).
|
||||
|
||||
=item C<long write_int64out(int64outRecord *prec)>
|
||||
|
||||
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<process()> routine to be called later once the write operation is over. When
|
||||
that happens the C<write_int64out()> 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<dbPutLink> 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
|
||||
|
||||
Reference in New Issue
Block a user