diff --git a/src/std/rec/mbbiDirectRecord.dbd.pod b/src/std/rec/mbbiDirectRecord.dbd.pod index 3fa3d8823..724cbfb55 100644 --- a/src/std/rec/mbbiDirectRecord.dbd.pod +++ b/src/std/rec/mbbiDirectRecord.dbd.pod @@ -6,8 +6,158 @@ # EPICS BASE is distributed subject to a Software License Agreement found # in file LICENSE that is included with this distribution. #************************************************************************* + +=head1 B + +The mbbiDirect record retrieves a sixteen-bit hardware value and converts it to +an array of sixteen unsigned characters, each representing a bit of the word. +These fields (B0-B9, BA-BF) are set to 1 if a bit is set, and 0 if not. + +This record's operation is similar to that of the multi-bit binary input record, +and it has many fields in common with it. This record also has two available +soft device support modules: C and C. + +=head1 L + +=over + +=item * L + +=over + +=item * L + +=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 mbbiDirect + +=cut + recordtype(mbbiDirect) { - include "dbCommon.dbd" + +=head2 Parameter Fields + +The fields fall into the following categories: + +=over + +=item * L + +=item * L + +=item * L + +=item * L + +=item * L + +=back + +=cut + +=head3 Scan Parameters + +The mbbiDirect record has the standard fields for specifying under what +circumstances the record 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. + +=cut + +=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 mbbiDirect 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 INP value but can be changed at +run-time via dbPutField or dbPutLink. See L
for +information on how to database links. + +For records that don't use C<<< Soft Channel >>> device support, RVAL is used to +determine VAL as follows: + +=over + +=item 1. RVAL is assigned to a temporary variable I = RVAL + +=item 2. I is shifted right SHFT number of bits. + +=item 3. VAL is set equal to I. + +=back + +Each of the fields, B0-BF, represents one bit of the word. + +=fields VAL, INP, RVAL, SHFT, B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, BA, BB, BC, BD, BE, BF + +=cut + +=head3 Operator Display Parameters + +These parameters are used to present meaningful data to the operator. + +See L for more on the record name (NAME) and +description (DESC) fields. + +=fields NAME, DESC + +=cut + + include "dbCommon.dbd" field(VAL,DBF_USHORT) { prompt("Current Value") promptgroup("40 - Input") @@ -49,6 +199,27 @@ recordtype(mbbiDirect) { promptgroup("40 - Input") interest(1) } + +=head3 Run-time and Simulation Mode Parameters + +These parameters are used by the run-time code for processing the mbbi direct +record. They are not configurable prior to run-time. + +MASK is used by device support routine to read hardware register. Record support +sets low order NOBT bits in MASK. Device support can shift this value. + +MLST holds the value when the last monitor for value change was triggered. + +=fields NOBT, ORAW, MASK, MLST + +The following fields are used to operate the mbbiDirect 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") @@ -67,6 +238,20 @@ recordtype(mbbiDirect) { interest(1) menu(menuSimm) } + +=head3 Alarm Parameters + +The possible alarm conditions for multi-bit binary input direct records are the +SCAN and READ alarms. These alarms are not configurable by the user since they +are always of MAJOR severity. See L for a complete +explanation of Scan and Read alarms. No fields exist for the mbbi direct record +to have state alarms. + +L lists other fields related to a alarms that are common to all +record types. + +=cut + field(SIMS,DBF_MENU) { prompt("Sim mode Alarm Svrty") promptgroup("90 - Simulate") @@ -153,4 +338,223 @@ recordtype(mbbiDirect) { pp(TRUE) interest(1) } + +=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. + +refresh_bits is then called to refresh all the bit fields based on a hardware +value. + +=head4 process + +See next section. + +=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 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_mbbiDirect + +=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 + +=item * Set VAL = RVAL + +=back + +=item * If status is 1, return 0 + +=item * If status is 2, set status = 0 + +=back + +=item 5. + +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 6. + +Scan forward link if necessary, set PACT FALSE, and return. + +=back + +=begin html + +


+ +=end html + +=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_mbbiDirect 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 + +=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 IEO event scan list. cmd has the value (0,1) if the +record is being (added to, deleted from) an IEO event list. It must be +provided for any device type that can use the ioEvent scanner. + +=head4 read_mbbiDirect + + read_mbbiDirect(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 and SHFT. + +=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 direct records not related to +actual hardware devices. The INP link type must be either CONSTANT, DB_LINK, or +CA_LINK. + +=head4 Soft Channel + +For this module, read_mbbiDirect 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_mbbiDirect calls recGblGetLinkValue to read the current value of VAL. + +See L for a further explanation. + +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_mbbiDirect returns a value of 0. Thus the record +processing routine will determine VAL in the normal way. + +=cut + }