First version of mbbi POD file
This commit is contained in:
Joao Paulo Martins
@@ -6,7 +6,186 @@
|
||||
# EPICS BASE is distributed subject to a Software License Agreement found
|
||||
# in file LICENSE that is included with this distribution.
|
||||
#*************************************************************************
|
||||
|
||||
=head1 B<Multi-Bit Binary Input Record (mbbi)>
|
||||
|
||||
The normal use for the multi-bit binary input record is to read contiguous,
|
||||
multiple bit inputs from hardware. The binary value represents a state from a
|
||||
range of up to 16 states. The multi-bit input record interfaces with devices
|
||||
that use more than one bit.
|
||||
|
||||
Most device support modules obtain values from hardware and place the value in
|
||||
RVAL. For these device support modules record processing uses RVAL to determine
|
||||
the current state (VAL is given a value between 0 and 15). Device support
|
||||
modules may optionally read a value directly into VAL.
|
||||
|
||||
Soft device modules are provided to obtain input via database or channel access
|
||||
links or via dbPutField or dbPutLink requests. Two soft device support modules
|
||||
are provided: C<<< Soft Channel >>> allows VAL to be an arbitrary unsigned short
|
||||
integer. C<<< Raw Soft Channel >>> reads the value into RVAL just like normal
|
||||
device support modules.
|
||||
|
||||
=head1 L<Contents>
|
||||
|
||||
=over
|
||||
|
||||
=item * L<Parameter Fields>
|
||||
|
||||
=over
|
||||
|
||||
=item * L<Scan Parameters>
|
||||
|
||||
=item * L<Read and Convert Parameters>
|
||||
|
||||
=item * L<Operator Display Parameters>
|
||||
|
||||
=item * L<Alarm Parameters>
|
||||
|
||||
=item * L<Run-time Parameters>
|
||||
|
||||
=item * L<Simulation Mode Parameters>
|
||||
|
||||
=back
|
||||
|
||||
=item * L<Record Support>
|
||||
|
||||
=over
|
||||
|
||||
=item * L<Record Support Routines>
|
||||
|
||||
=item * L<Record Processing>
|
||||
|
||||
=back
|
||||
|
||||
=item * L<Device Support>
|
||||
|
||||
=over
|
||||
|
||||
=item * L<Fields Of Interest To Device Support>
|
||||
|
||||
=item * L<Device Support Routines>
|
||||
|
||||
=item * L<Device Support For Soft Records>
|
||||
|
||||
=back
|
||||
|
||||
=back
|
||||
|
||||
=begin html
|
||||
|
||||
<br><hr><br>
|
||||
|
||||
=end html
|
||||
|
||||
=recordtype mbbi
|
||||
|
||||
=cut
|
||||
|
||||
recordtype(mbbi) {
|
||||
|
||||
=head2 Parameter Fields
|
||||
|
||||
The multi-bit binary input fields fall into the following categories:
|
||||
|
||||
=over
|
||||
|
||||
=item * L<Scan Parameters>
|
||||
|
||||
=item * L<Read and Convert Parameters>
|
||||
|
||||
=item * L<Operator Display Parameters>
|
||||
|
||||
=item * L<Alarm Parameters>
|
||||
|
||||
=item * L<Run-time Parameters>
|
||||
|
||||
=item * L<Simulation Mode Parameters>
|
||||
|
||||
=back
|
||||
|
||||
=head3 Scan Parameters
|
||||
|
||||
The multi-bit binary input record has the standard fields for specifying under
|
||||
what circumstances it will be processed. These fields are listed in L<Scan
|
||||
Fields>. In addition, L<Scanning Specification> explains how these fields are
|
||||
used. Note that I/O event scanning is only supported for those card types that
|
||||
interrupt.
|
||||
|
||||
=head3 Read and Convert Parameters
|
||||
|
||||
The device support routines obtain the record's input from the device or link
|
||||
specified in the INP field. For records that obtain their input from devices,
|
||||
the INP field must contain the address of the I/O card, and the DTYP field must
|
||||
specify the proper device support module. Be aware that the address format
|
||||
differs according to the I/O bus used. See L<Address Specification> for
|
||||
information on the format of hardware addresses.
|
||||
|
||||
Two soft device support modules can be specified in DTYP C<Soft Channel> and
|
||||
C<<< Raw Soft Channel >>>.
|
||||
|
||||
C<<< Raw Soft Channel >>> reads the value into RVAL,
|
||||
upon which the normal conversion process is undergone. C<<< Soft Channel >>>
|
||||
reads any unsigned integer directly into VAL. For a soft mbbi record, the INP
|
||||
field can be a constant, a database, or a channel access link. If INP is a
|
||||
constant, then the VAL is initialized to the constant value but can be changed
|
||||
at run-time via dbPutField or dbPutLink. See L<Address Specification> for
|
||||
information on the format of database addresses.
|
||||
|
||||
MASK is used by the raw soft channel read routine, and by typical device support
|
||||
read routines, to select only the desired bits when reading the hardware
|
||||
register. It is initialized to ((1 E<lt>E<lt> NOBT) - 1) by record
|
||||
initialization. The user can configure the NOBT field, but the device support
|
||||
routines may set it, in which case the value given to it by the user is simply
|
||||
overridden. The device support routines may also override MASK or shift it
|
||||
left by SHFT bits. If MASK is non-zero, only the bits specified by MASK will
|
||||
appear in RVAL.
|
||||
|
||||
Unless the device support routine specifies no conversion, RVAL is used to
|
||||
determine VAL as follows:
|
||||
|
||||
=over
|
||||
|
||||
=item 1.
|
||||
|
||||
RVAL is assigned to a temporary variable -- rval = RVAL
|
||||
|
||||
=item 2.
|
||||
|
||||
rval is shifted right SHFT number of bits.
|
||||
|
||||
=item 3.
|
||||
|
||||
A match is sought between rval and one of the state value fields, ZRVL-FFVL.
|
||||
|
||||
=back
|
||||
|
||||
Each of the fields, ZRVL-FFVL, represents one of the possible sixteen states
|
||||
(not all sixteen have to be used).
|
||||
|
||||
Alternatively, the input value can be read as a string, in which case, a match
|
||||
is sought with one of the strings specified in the ZRST-FFST fields. Then RVAL
|
||||
is set equal to the corresponding value for that string, and the conversion
|
||||
process occurs.
|
||||
|
||||
=fields VAL, INP, MASK, NOBT, RVAL, SHFT, ZRVL, ONVL, TWVL, THVL, FRVL, FVVL, SXVL, SVVL, EIVL, NIVL, TEVL, ELVL, TVVL, TTVL, FTVL, FFVL
|
||||
|
||||
=head3 Operator Display Parameters
|
||||
|
||||
These parameters are used to present meaningful data to the operator. They
|
||||
display the value and other parameters of the mbbi record either textually or
|
||||
graphically. The ZRST-FFST fields contain strings describing one of the possible
|
||||
states of the record. The C<<< get_enum_str >>> and C<<< get_enum_strs >>>
|
||||
record routines retrieve these strings for the operator. C<<< Get_enum_str >>>
|
||||
gets the string corresponding to the value set in VAL, and C<<< get_enum_strs
|
||||
>>> retrieves all the strings.
|
||||
|
||||
See L<Fields Common to All Record Types> for more on the record name (NAME) and
|
||||
description (DESC) fields.
|
||||
|
||||
=fields NAME, DESC, ZRST, ONST, TWST, THST, FRST, FVST, SXST, SVST, EIST, NIST, TEST, ELST, TVST, TTST, FTST, FFST
|
||||
|
||||
=cut
|
||||
|
||||
include "dbCommon.dbd"
|
||||
field(VAL,DBF_ENUM) {
|
||||
prompt("Current Value")
|
||||
@@ -281,6 +460,30 @@ recordtype(mbbi) {
|
||||
interest(1)
|
||||
size(26)
|
||||
}
|
||||
|
||||
=head3 Alarm Parameters
|
||||
|
||||
The possible alarm conditions for multi-bit binary inputs are the SCAN, READ,
|
||||
and state alarms. The state alarms are configured in the below severity fields.
|
||||
These fields have the usual possible values for severity fields: NO_ALARM,
|
||||
MINOR, and MAJOR.
|
||||
|
||||
The unknown state severity (UNSV) field, if set to MINOR or MAJOR, triggers an
|
||||
alarm when the record support routine cannot find a matching value in the state
|
||||
value fields for C<<< rval >>>.
|
||||
|
||||
The change of state severity (COSV) field triggers an alarm when any change of
|
||||
state occurs, if set to MAJOR or MINOR.
|
||||
|
||||
The other fields, when set to MAJOR or MINOR, trigger an alarm when VAL equals
|
||||
the corresponding state. See the See L<Alarm Specification> for a complete
|
||||
explanation of discrete alarms and these fields. L<Alarm Fields> lists other
|
||||
fields related to a alarms that are common to all record types.
|
||||
|
||||
=fields UNSV, COSV, ZRSV, ONSV, TWSV, THSV, FRSV, FVSV, SXSV, SVSV, EISV, NISV, TESV, ELSV, TVSV, TTSV, FTSV, FFSV
|
||||
|
||||
=cut
|
||||
|
||||
field(ZRSV,DBF_MENU) {
|
||||
prompt("State Zero Severity")
|
||||
promptgroup("71 - Alarm 0-7")
|
||||
@@ -417,6 +620,26 @@ recordtype(mbbi) {
|
||||
interest(1)
|
||||
menu(menuAlarmSevr)
|
||||
}
|
||||
|
||||
=head3 Run-time Parameters
|
||||
|
||||
These parameters are used by the run-time code for processing the multi-bit
|
||||
binary input.
|
||||
|
||||
ORAW is used by record processing to hold the prior RVAL for use in determining
|
||||
when to post a monitor event for the RVAL field.
|
||||
|
||||
The LALM field implements the change of state alarm severity by holding the
|
||||
value of VAL when the previous change of state alarm was issued.
|
||||
|
||||
MLST holds the value when the last monitor for value change was triggered.
|
||||
|
||||
SDEF is used by record support to save time if no states are defined.
|
||||
|
||||
=fields ORAW, LALM, MLST, SDEF
|
||||
|
||||
=cut
|
||||
|
||||
field(RVAL,DBF_ULONG) {
|
||||
prompt("Raw Value")
|
||||
pp(TRUE)
|
||||
@@ -451,6 +674,16 @@ recordtype(mbbi) {
|
||||
promptgroup("40 - Input")
|
||||
interest(1)
|
||||
}
|
||||
|
||||
=head3 Simulation Mode Parameters
|
||||
|
||||
The following fields are used to operate the mbbi record in the simulation mode.
|
||||
See L<Fields Common to Many Record Types> for more information on these fields.
|
||||
|
||||
=fields SIOL, SVAL, SIML, SIMM, SIMS
|
||||
|
||||
=cut
|
||||
|
||||
field(SIOL,DBF_INLINK) {
|
||||
prompt("Sim Input Specifctn")
|
||||
promptgroup("90 - Simulate")
|
||||
@@ -475,4 +708,278 @@ recordtype(mbbi) {
|
||||
interest(2)
|
||||
menu(menuAlarmSevr)
|
||||
}
|
||||
|
||||
=pod
|
||||
|
||||
=begin html
|
||||
|
||||
<br><hr><br>
|
||||
|
||||
=end html
|
||||
|
||||
=head2 Record Support
|
||||
|
||||
=head3 Record Support Routines
|
||||
|
||||
=head4 init_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. SVAL 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.
|
||||
|
||||
Clears MASK and then sets the NOBT low order bits.
|
||||
|
||||
If device support includes C<init_record()>, it is called.
|
||||
|
||||
init_common is then called to determine if any states are defined. If states are
|
||||
defined, SDEF is set to TRUE.
|
||||
|
||||
=head4 process
|
||||
|
||||
See next section.
|
||||
|
||||
=head4 special
|
||||
|
||||
Calls init_common to compute SDEF when any of the fields ZRVL, ... FFVL change
|
||||
value.
|
||||
|
||||
=head4 get_enum_str
|
||||
|
||||
Retrieves ASCII string corresponding to VAL.
|
||||
|
||||
=head4 get_enum_strs
|
||||
|
||||
Retrieves ASCII strings for ZRST,...FFST.
|
||||
|
||||
=head4 put_enum_str
|
||||
|
||||
Checks if string matches ZRST,...FFST and if it does, sets VAL.
|
||||
|
||||
=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.
|
||||
|
||||
readValue is called. See L<Input Records> for more information.
|
||||
|
||||
=item 3.
|
||||
|
||||
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.
|
||||
|
||||
=item 4.
|
||||
|
||||
Convert:
|
||||
|
||||
=over
|
||||
|
||||
=item * status=read_mbbi
|
||||
|
||||
=item * PACT = TRUE
|
||||
|
||||
=item * C<recGblGetTimeStamp()> is called.
|
||||
|
||||
=item * If status is 0, then determine VAL
|
||||
|
||||
=over
|
||||
|
||||
=item * Set rval = RVAL
|
||||
|
||||
=item * Shift rval right SHFT bits
|
||||
|
||||
=back
|
||||
|
||||
=item * If at least one state value is defined
|
||||
|
||||
=over
|
||||
|
||||
=item * Set UDF to TRUE
|
||||
|
||||
=back
|
||||
|
||||
=item * If RVAL is ZRVL,...,FFVL then set
|
||||
|
||||
=over
|
||||
|
||||
=item * VAL equals index of state
|
||||
|
||||
=item * UDF set to FALSE
|
||||
|
||||
=back
|
||||
|
||||
=item * Else set VAL = undefined
|
||||
|
||||
=over
|
||||
|
||||
=item * Else set VAL = RVAL
|
||||
|
||||
=back
|
||||
|
||||
=item * Set UDF to FALSE
|
||||
|
||||
=over
|
||||
|
||||
=item * If status is 1, return 0
|
||||
|
||||
=item * If status is 2, set status = 0
|
||||
|
||||
=back
|
||||
|
||||
=back
|
||||
|
||||
=item 5.
|
||||
|
||||
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.
|
||||
|
||||
=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 MLST is not equal to VAL.
|
||||
|
||||
=item * Monitors for RVAL are checked whenever other monitors are invoked.
|
||||
|
||||
=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 input record must have an associated set of device support routines.
|
||||
|
||||
The primary responsibility of the device support routines is to obtain a new raw
|
||||
input value whenever read_mbbi is called. The device support routines are
|
||||
primarily interested in the following fields:
|
||||
|
||||
=fields PACT, DPVT, UDF, NSEV, NSTA, NOBT, VAL, INP, RVAL, MASK, SHFT
|
||||
|
||||
=begin html
|
||||
|
||||
<br><hr><br>
|
||||
|
||||
=end html
|
||||
|
||||
=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<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.
|
||||
|
||||
=head4 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.
|
||||
|
||||
=head4 init_record
|
||||
|
||||
init_record(precord)
|
||||
|
||||
This routine is optional. If provided, it is called by the record support
|
||||
C<init_record()> routine. If it uses MASK, it should shift it as necessary and
|
||||
also give SHFT a value.
|
||||
|
||||
=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 I/O Event scanner.
|
||||
|
||||
=head4 read_mbbi
|
||||
|
||||
read_mbbi(precord)
|
||||
|
||||
This routine must provide a new input value. It returns the following values:
|
||||
|
||||
=over
|
||||
|
||||
=item *
|
||||
|
||||
0: Success. A new raw value is placed in RVAL. The record support module
|
||||
determines VAL from RVAL, SHFT, and ZEVL ... FFVL.
|
||||
|
||||
=item *
|
||||
|
||||
2: Success, but don't modify VAL.
|
||||
|
||||
=item *
|
||||
|
||||
Other: Error.
|
||||
|
||||
=back
|
||||
|
||||
=head3 Device Support For Soft Records
|
||||
|
||||
Two soft device support modules C<<< Soft Channel >>> and C<<< Raw Soft Channel
|
||||
>>> are provided for multi-bit binary input records not related to actual
|
||||
hardware devices. The INP link type must be either CONSTANT, DB_LINK, or
|
||||
CA_LINK.
|
||||
|
||||
=head4 Soft Channel
|
||||
|
||||
read_mbbi always returns a value of 2, which means that no conversion is
|
||||
performed.
|
||||
|
||||
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. VAL can be changed via dbPut
|
||||
requests. If the INP link type is PV_LINK, then dbCaAddInlink is called by
|
||||
C<init_record()>.
|
||||
|
||||
read_mbbi calls recGblGetLinkValue to read the current value of VAL. See L<Soft
|
||||
Input>.
|
||||
|
||||
If the return status of recGblGetLinkValue is zero, then read_mbbi sets UDF to
|
||||
FALSE. The status of recGblGetLinkValue is returned.
|
||||
|
||||
=head4 Raw Soft Channel
|
||||
|
||||
This module is like the previous except that values are read into RVAL, VAL is
|
||||
computed from RVAL, and read_mbbi returns a value of 0. Thus the record
|
||||
processing routine will determine VAL in the normal way.
|
||||
|
||||
|
||||
=cut
|
||||
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user