diff --git a/src/std/rec/histogramRecord.dbd.pod b/src/std/rec/histogramRecord.dbd.pod index 075400fc6..a459e08d9 100644 --- a/src/std/rec/histogramRecord.dbd.pod +++ b/src/std/rec/histogramRecord.dbd.pod @@ -6,14 +6,141 @@ # EPICS BASE is distributed subject to a Software License Agreement found # in file LICENSE that is included with this distribution. #************************************************************************* + +=title Histogram Record (histogram) + +The histogram record is used to store frequency counts of a signal into an array +of arbitrary length. The user can configure the range of the signal value that +the array will store. Anything outside this range will be ignored. + +=head2 Parameter Fields + +The record-specific fields are described below. + +=recordtype histogram + +=cut + menu(histogramCMD) { choice(histogramCMD_Read,"Read") choice(histogramCMD_Clear,"Clear") choice(histogramCMD_Start,"Start") choice(histogramCMD_Stop,"Stop") } + recordtype(histogram) { - include "dbCommon.dbd" + +=head3 Read Parameters + +The SVL is the input link where the record reads its value. It can be a +constant, a database link, or a channel access link. If SVL is a database or +channel access link, then SGNL is read from SVL. If SVL is a constant, then SGNL +is initialized with the constant value but can be changed via dbPuts. The C device support module can be specified in the DTYP field. + +The ULIM and LLIM fields determine the usable range of signal values. Any value +of SGNL below LLIM or above ULIM is outside the range and will not be stored in +the array. In the NELM field the user must specify the array size, e.g., the +number of array elements. Each element in the NELM field holds the counts for an +interval of the range of signal counts, the range specified by ULIM and LLIM. +These intervals are determined by dividing the range by NELM: + + (ULIM - LLIM) / NELM. + +=fields SVL, SGNL, DTYP, NELM, ULIM, LLIM + +=head3 Operator Display Parameters + +These parameters are used to present meaningful data to the operator. These +fields are used to display the value and other parameters of the histogram +either textually or graphically. See L for +more on the record name (NAME) and description (DESC) fields. + +=fields NAME, DESC + +=head3 Alarm Parameters + +The Histogram record has the alarm parameters common to all record types. +L lists other fields related to a alarms that are common to all +record types. + +=head3 Monitor Parameters + +The MDEL field implements the monitor count deadband. Only when MCNT is greater +than the value given to MDEL are monitors triggered, MCNT being the number of +counts since the last time the record was processed. If MDEL is -1, everytime +the record is processed, a monitor is triggered regardless. + +If SDEL is greater than 0, it causes a callback routine to be called. The number +specified in SDEL is the callback routines interval. The callback routine is +called every SDEL seconds. The callback routine posts an event if MCNT is +greater than 0. + +=fields MDEL, SDEL + +=head3 Run-time and Simulation Mode Parameters + +These parameters are used by the run-time code for processing the histogram. +They are not configurable by the user prior to run-time. They represent the +current state of the record. Many of them are used to process the histogram more +efficiently. + +The BPTR field contains a pointer to the unsigned long array of frequency +values. The VAL field references this array as well. However, the BPTR field is +not accessible at run-time. + +The MCNT field keeps counts the number of signal counts since the last monitor +was invoked. + +The collections controls field (CMD) is a menu field with five choices: + +=menu histogramCMD + +When CMD is C, the record retrieves its values and adds them to the signal +array. This command will first clear the signal counts which have already been +read when it is first invoked. + +The C command erases the signal counts, setting the elements in the array +back to zero. Afterwards, the CMD field is set back to C. + +The C command simply causes the record to read signal values into the +array. Unlike C, it doesn't clear the array first. + +The C command disables the reading of signal values into the array. + +The C command waits until the C or C command has been issued +to start counting. + +The CSTA or collections status field implements the CMD field choices by +enabling or disabling the reading of values into the histogram array. While +FALSE, no signals are added to the array. While TRUE, signals are read and added +to the array. The field is initialized to TRUE. The C command is the only +command that sets CSTA to FALSE. On the other hand, the C command is the +only command that sets it to TRUE. Thus, C must be invoked after each +C command in order to enable counting; invoking C will not enable +signal counting after C has been invoked. + +A typical use of these fields would be to initialize the CMD field to C +(it is initialized to this command by default), to use the C command to +disable counting when necessary, after which the C command can be invoked +to re-start the signal count. + +The WDTH field is a private field that holds the signal width of the array +elements. For instance, if the LLIM was configured to be 4.0 and ULIM was +configured to be 12.0 and the NELM was set to 4, then the WDTH for each array +would be 2. Thus, it is (ULIM - LLIM) / NELM. + +=fields BPTR, VAL, MCNT, CMD, CSTA, WDTH + +The following fields are used to operate the histogram record in simulation +mode. See L for more information on the +simulation mode fields. + +=fields SIOL, SVAL, SIML, SIMM, SIMS + +=cut + + include "dbCommon.dbd" field(VAL,DBF_NOACCESS) { prompt("Value") asl(ASL0) @@ -141,6 +268,152 @@ recordtype(histogram) { interest(1) prop(YES) } + +=head2 Record Support + +=head3 Record Support Routines + +=head4 init_record + +Using NELM, space for the unsigned long array is allocated and the width WDTH of +the array is calculated. + +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 and a device support read +routine are available. If device support includes C, it is +called. + +=head4 process + +See next section. + +=head4 special + +Special is invoked whenever the fields CMD, SGNL, ULIM, or LLIM are changed. + +If SGNL is changed, add_count is called. + +If ULIM or LLIM are changed, WDTH is recalculated and clear_histogram is called. + +If CMD is less or equal to 1, clear_histogram is called and CMD is reset to 0. +If CMD is 2, CSTA is set to TRUE and CMD is reset to 0. If CMD is 3, CSTA is set +to FALSE and CMD is reset to 0. + +clear_histogram zeros out the histogram array. add_count increments the +frequency in the histogram array. + +=head4 cvt_dbaddr + +This is called by dbNameToAddr. It makes the dbAddr structure refer to the +actual buffer holding the array. + +=head4 get_array_info + +Obtains values from the array referenced by VAL. + +=head4 put_array_info + +Writes values into the array referenced by 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 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 writing the new value. In this case, the processing +routine merely returns, leaving PACT TRUE. + +=item 4. + +Add count to histogram array. + +=item 5. + +Check to see if monitors should be invoked. Alarm monitors are invoked if the +alarm status or severity has changed. Archive and value change monitors are +invoked if MDEL conditions are met. NSEV and NSTA are reset to 0. + +=item 6. + +Scan forward link if necessary, set PACT and INIT to FALSE, and return. + +=back + +=head2 Device Support + +=head3 Fields Of Interest To Device Support + +The device support routines are primarily interested in the following fields: + +=fields PACT, DPVT, UDF, NSEV, NSTA, SVL, SGNL + +=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 called by the record support C routine. It makes +sure that SGNL is a CONSTANT, PV_LINK, DB_LINK, or CA_LINK. It also retrieves a +value for SVL from SGNL. If SGNL is none of the above, an error is generated. + +=head4 read_histogram + + read_histogram(*precord) + +This routine is called by the record support routines. It retrieves a value for +SVL from SGNL. + +=head3 Device Support For Soft Records + +Only the device support module C is currently provided, though +other device support modules may be provided at the user's site. + +=head4 Soft Channel + +The C device support routine retrieves a value from SGNL. SGNL +must be CONSTANT, PV_LINK, DB_LINK, or CA_LINK. + +=cut + } variable(histogramSDELprecision, int)