epics/epics-base
0
0
Fork 0
Code Issues Pull Requests Projects Wiki Activity

Updated the Event Record reference docs

Browse Source 
Now covers named events, not numbers.
All links to other reference docs now work.
This commit is contained in:
Andrew Johnson
2025-03-04 22:11:46 -06:00
parent d724779abf
commit 4dd01aa9b6
1 changed files with 86 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
modules/database/src/std/rec/eventRecord.dbd.pod
View File

@@ -9,9 +9,12 @@
=title Event Record (event)
The normal use for this record type is to post an event and/or process a
forward link. Device support for this record can provide a hardware interrupt
handler routine for I/O Event-scanned records.
The normal use for this record type is to post a soft-event and/or process a
forward link.
C<Soft Channel> device support is provided to allow the soft-event name to be
read from an input link.
Hardware device support for this record can provide an interrupt handler routine
to trigger processing of the record when an I/O Intr event occurs.
=head2 Parameter Fields
@@ -37,18 +40,31 @@ recordtype(event) {
=head3 Scan Parameters
The event record has the standard fields for specifying under what circumstances
it will be processed.
it should be processed.
These fields are described in L<Scan Fields|dbCommonRecord/Scan Fields>.
=fields SCAN, PHAS, EVNT, PRIO, PINI
=head3 Event Number Parameters
=head3 Event Name Parameters
The VAL field contains the event number read by the device support routines. It
is this number which is posted. For records that use C<Soft Channel> device
support, it can be configured before run-time or set via dbPuts.
The VAL field is a string (prior to the Base-3.15.1 release it was a short
integer) providing the name of an IOC soft-event.
This named soft-event gets posted whenever the record is processed.
=fields VAL
When the soft-event name is known at design time, the VAL field should be set to
the name in a loaded database file.
Soft-event names do not have to be registered before use, a handle for the name
is automatically created and stored when a name is first seen and the same
handle returned later if the same name is re-used.
The EPVT field holds the handle for the soft-event named in the VAL field.
Looking up the handle for a soft-event name is fast and uses a hash table.
For records that use the default C<Soft Channel> device support, the soft-event
name can be fetched through the INP field link, written to the VAL field and the
handle looked up during record processing.
=fields VAL, EPVT
=cut
@@ -69,16 +85,18 @@ support, it can be configured before run-time or set via dbPuts.
=head3 Input Specification
The device support routines use the address in this record to obtain input. For
records that provide an interrupt handler, the INP field should specify the
The device support routines use the address in this record to obtain input.
For records that provide an interrupt handler, the INP field should specify the
address of the I/O card, and the DTYP field should specify a valid device
support module. Be aware that the address format differs according to the card
type used. See L<Address
support module.
The address format differs according to the card type used. See
L<Address
Specification|https://docs.epics-controls.org/en/latest/guides/EPICS_Process_Database_Concepts.html#address-specification>
for information on the format of hardware addresses and specifying links.
For soft records, the INP field can be a constant, a database link, or a channel
access link. For soft records, the DTYP field should specify C<Soft Channel>.
access link, and the DTYP field should be empty or set to C<Soft Channel>.
=fields INP, DTYP
@@ -93,24 +111,27 @@ access link. For soft records, the DTYP field should specify C<Soft Channel>.
=head3 Operator Display Parameters
See L<Fields Common to All Record Types|dbCommonRecord/Operator Display
Parameters> for more on the record name (NAME) and description (DESC) fields.
Parameters>
for more on the record name (NAME) and description (DESC) fields.
=fields NAME, DESC
=head3 Alarm Parameters
The Event record has the alarm parameters common to all record types. L<Alarm
Fields> lists other fields related to alarms that are common to all record
types.
The Event record has the alarm parameters common to all record types.
L<Alarm Fields|dbCommonRecord/Alarm Fields> lists other fields related to alarms
that are common to all record types.
=fields STAT, SEVR, AMSG, NSTA, NSEV, NAMSG, ACKS, ACKT, UDF
=head3 Simulation Mode Parameters
The following fields are used to operate the event record in the simulation
mode. See L<Fields Common to Many Record Types> for more information on these
fields.
mode.
See L<Fields Common to Input Record Types|dbCommonInput/Input Simulation Fields>
for more information on these fields.
=fields SIOL, SVAL, SIML, SIMM, SIMS
=fields SIOL, SVAL, SIML, SIMM, SIMS, SSCN, SDLY
=cut
@@ -179,38 +200,50 @@ initialized if SIOL is CONSTANT or PV_LINK.
If device support includes C<init_record()>, it is called.
The string in VAL is converted to a soft-event handle in EPVT.
=head4 process
See next section.
=head4 special
When the VAL field is set, the new string is converted to a soft-event handle in
EPVT.
=head3 Record Processing
Routine process implements the following algorithm:
Routine C<process()> implements the following algorithm:
=over
=item 1.
readValue is called. See L<Input Records> for more information.
C<readValue()> is called.
See L<Input Records|dbCommonInput/Input Records> for more information.
=item 2.
If PACT has been changed to TRUE, the device support read routine has started
but has not completed reading a new input value. In this case, the processing
routine merely returns, leaving PACT TRUE.
If PACT has changed to TRUE, the device support read routine has started
but has not completed reading a new soft-event name.
In this case, the processing routine returns immediately, leaving PACT TRUE.
=item 3.
If VAL E<gt> 0, post event number VAL.
Set PACT to TRUE.
=item 4.
Check to see if monitors should be invoked. Alarm monitors are invoked if the
alarm status or severity has chanet to 0.
Post the soft-event whose handle is in EPVT.
=item 5.
Scan forward link if necessary, set PACT FALSE, and return.
Check to see if monitors should be invoked.
Alarm monitors are invoked if the new alarm status or severity are non-zero.
=item 6.
Scan forward link if set, set PACT to FALSE, and return.
=back
@@ -221,13 +254,15 @@ Scan forward link if necessary, set PACT FALSE, and return.
Each record must have an associated set of device support routines. The device
support routines are primarily interested in the following fields:
=fields PACT, DPVT, UDF, NSEV, NSTA, INP, PRIO
=fields PACT, DPVT, UDF, NSEV, NSTA, INP, PRIO, VAL, EPVT
=head3 Device Support Routines
Device support consists of the following routines:
=head4 long report(int level)
=head4 report
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.
@@ -235,9 +270,11 @@ 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.
Level zero should print only a 1-line summary.
=head4 long init(int after)
=head4 init
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
@@ -247,23 +284,25 @@ with C<after> set to 1.
=head4 init_record
init_record(precord)
long init_record(precord)
This routine is optional. If provided, it is called by the record support
C<init_record()> routine.
=head4 get_ioint_info
get_ioint_info(int cmd, struct dbCommon *precord, IOSCANPVT *ppvt)
long 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. C<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.
This routine is called by the dbScan system each time the record is added
or deleted from an I/O event scan list.
C<cmd> has the value (0, 1) if the record is being (added to, deleted from) an
I/O event list.
The C<get_ioint_info> routine is optional, but must be provided by any device
support that implements C<I/O Intr> scanning for the event record type.
=head4 read_event
read_event(precord)
long read_event(precord)
This routine returns the following values:
@@ -281,15 +320,13 @@ Other: Error.
=head3 Device Support For Soft Records
The C<Soft Channel> device support module is available. The INP link type must
be either CONSTANT, DB_LINK, or CA_LINK.
A C<Soft Channel> device support module is available.
The INP link field is used to fetch the soft-event name.
If the INP link type is CONSTANT, then the constant value is stored into VAL by
C<init_record()>, and UDF is set to FALSE. If the INP link type is PV_LINK, then
dbCaAddInlink is called by C<init_record()>.
The C<read_event()> routine reads a string through INP and stores it in VAL,
then looks up the named soft-event handle and sets EPVT.
C<read_event> calls recGblGetLinkValue to read the current value of VAL. See
L<Input Records> for details on soft input.
See L<Input Records|dbCommonInput/Input Records> for details on soft input.
=cut