diff --git a/src/std/rec/mbbiRecord.dbd.pod b/src/std/rec/mbbiRecord.dbd.pod index 1f5724c92..2bbda6686 100644 --- a/src/std/rec/mbbiRecord.dbd.pod +++ b/src/std/rec/mbbiRecord.dbd.pod @@ -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 + +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 + +=over + +=item * L + +=over + +=item * L + +=item * L + +=item * L + +=item * L + +=item * L + +=item * L + +=back + +=item * L + +=over + +=item * L + +=item * L + +=back + +=item * L + +=over + +=item * L + +=item * L + +=item * L + +=back + +=back + +=begin html + +

+ +=end html + +=recordtype mbbi + +=cut + recordtype(mbbi) { + +=head2 Parameter Fields + +The multi-bit binary input fields fall into the following categories: + +=over + +=item * L + +=item * L + +=item * L + +=item * L + +=item * L + +=item * L + +=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. In addition, L 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
for +information on the format of hardware addresses. + +Two soft device support modules can be specified in DTYP C 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
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 EE 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 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 for a complete +explanation of discrete alarms and these fields. L 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 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 + +

+ +=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, 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 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 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 + +

+ +=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 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 init_record + + init_record(precord) + +This routine is optional. If provided, it is called by the record support +C 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, 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. + +read_mbbi calls recGblGetLinkValue to read the current value of VAL. See L. + +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 + }