From 3f43b0bb8a488fca320eaed6826748964cfd8c5c Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Mon, 4 Oct 2021 23:57:01 -0500 Subject: [PATCH] Record POD updates Mostly fixing links and adding some field tables. Some rewriting of descriptions. --- .../database/src/std/rec/aaoRecord.dbd.pod | 12 ++-- modules/database/src/std/rec/aiRecord.dbd.pod | 5 +- modules/database/src/std/rec/aoRecord.dbd.pod | 6 +- modules/database/src/std/rec/biRecord.dbd.pod | 13 +++-- modules/database/src/std/rec/boRecord.dbd.pod | 56 ++++++------------- .../database/src/std/rec/calcRecord.dbd.pod | 8 ++- .../src/std/rec/compressRecord.dbd.pod | 17 +++--- .../src/std/rec/dfanoutRecord.dbd.pod | 5 +- .../database/src/std/rec/eventRecord.dbd.pod | 13 +++-- .../src/std/rec/longoutRecord.dbd.pod | 5 +- .../src/std/rec/mbbiDirectRecord.dbd.pod | 3 +- .../src/std/rec/mbboDirectRecord.dbd.pod | 44 +++++++++------ .../database/src/std/rec/printfRecord.dbd.pod | 7 ++- 13 files changed, 99 insertions(+), 95 deletions(-) diff --git a/modules/database/src/std/rec/aaoRecord.dbd.pod b/modules/database/src/std/rec/aaoRecord.dbd.pod index d4e8c5b59..fb47672d0 100644 --- a/modules/database/src/std/rec/aaoRecord.dbd.pod +++ b/modules/database/src/std/rec/aaoRecord.dbd.pod @@ -32,9 +32,10 @@ The record-specific fields are described below, grouped by functionality. =head3 Scan Parameters The array analog output 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. I/O event scanning is only available when supported by device support. +circumstances the record will be processed. +These fields are described in L. + +=fields SCAN, PHAS, EVNT, PRIO, PINI =head3 Write Parameters @@ -43,8 +44,9 @@ writes its data. The OUT field determines where the array analog output writes i output. It can be a hardware address, a channel access or database link, or a constant. Only in records that use soft device support can the OUT field be a channel access link, a database link, or a constant. Otherwise, the OUT field must -be a hardware address. See L
for information on the format -of hardware addresses and database links. +be a hardware address. See L
+for information on the format of hardware addresses and database links. =head4 Fields related to array writing diff --git a/modules/database/src/std/rec/aiRecord.dbd.pod b/modules/database/src/std/rec/aiRecord.dbd.pod index ca0a82c7e..4515368b2 100644 --- a/modules/database/src/std/rec/aiRecord.dbd.pod +++ b/modules/database/src/std/rec/aiRecord.dbd.pod @@ -45,8 +45,9 @@ hardware address information that the device support uses to determine where the input data should come from. The format for the INP field value depends on the device support layer that is selected by the DTYP field. -See L
for a description of the various hardware -address formats supported. +See L
+for a description of the various hardware address formats supported. =head3 Units Conversion diff --git a/modules/database/src/std/rec/aoRecord.dbd.pod b/modules/database/src/std/rec/aoRecord.dbd.pod index 5fef0d09e..5c7dc61bb 100644 --- a/modules/database/src/std/rec/aoRecord.dbd.pod +++ b/modules/database/src/std/rec/aoRecord.dbd.pod @@ -161,9 +161,9 @@ The analog output record sends its desired output to the address in the OUT field. For analog outputs that write their values to devices, the OUT field must specify the address of the I/O card. In addition, the DTYP field must contain the name of the device support module. Be aware -that the address format differs according to the I/O bus used. See -Address Specification for information on the format of hardware -addresses. +that the address format differs according to the I/O bus used. See L
+for information on the format of hardware addresses. For soft records the output link can be a database link, a channel access link, or a constant value. If the link is a constant, no output diff --git a/modules/database/src/std/rec/biRecord.dbd.pod b/modules/database/src/std/rec/biRecord.dbd.pod index 491c06011..40ecd0293 100644 --- a/modules/database/src/std/rec/biRecord.dbd.pod +++ b/modules/database/src/std/rec/biRecord.dbd.pod @@ -37,6 +37,8 @@ The binary input record has the standard fields for specifying under what circumstances the record will be processed. These fields are described in L. +=fields SCAN, PHAS, EVNT, PRIO, PINI + =head3 Read and Convert Parameters The read and convert fields determine where the binary input gets its @@ -44,14 +46,15 @@ input from and how to convert the raw signal to engineering units. The INP field contains the address from where device support retrieves the value. If the binary input record gets its value from hardware, the address of the card must be entered in the INP field, and the name of the device support -module must be entered in the DTYP field. See L
for -information on the format of the hardware address. Be aware that the format -differs between types of cards. +module must be entered in the DTYP field. See L
+for information on the format of the hardware address. For records that specify C or C device support routines, the INP field can be a channel or a database link, or a -constant. If a constant, VAL can be changed directly by dbPuts. See -L
for information on the format of database and +constant. If a constant, VAL can be changed directly by dbPuts. See L
+for information on the format of database and channel access addresses. Also, see L in this chapter for information on soft device support. diff --git a/modules/database/src/std/rec/boRecord.dbd.pod b/modules/database/src/std/rec/boRecord.dbd.pod index bfbc8e820..2c9f0d7ce 100644 --- a/modules/database/src/std/rec/boRecord.dbd.pod +++ b/modules/database/src/std/rec/boRecord.dbd.pod @@ -15,29 +15,6 @@ values into other records via database or channel access links. This record can implement both latched and momentary binary outputs depending on how the HIGH field is configured. -=head2 Parameter Fields - -The binary output's fields fall into the following categories: - -=over 1 - -=item * -scan parameters - -=item * -convert and write parameters - -=item * -operator display parameters - -=item * -alarm parameters - -=item * -run-time parameters - -=back - =recordtype bo =cut @@ -47,13 +24,10 @@ recordtype(bo) { =head3 Scan Parameters The binary output record has the standard fields for specifying under what -circumstances the record will be processed. The fields are listed in +circumstances the record will be processed. +These fields are described in L. -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. - -=fields SCAN +=fields SCAN, PHAS, EVNT, PRIO, PINI =head3 Desired Output Parameters @@ -70,9 +44,9 @@ database link or a channel access link, but not a constant. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field. -L
presents more information on database addresses -and links. L explaines the effect of database -linkage on scanning. +See L
+for information on hardware addresses and links. =fields DOL, OMSL @@ -130,15 +104,17 @@ The OUT field specifies where the binary output record writes its output. It must specify the address of an I/O card if the record sends its output to hardware, and the DTYP field must contain the corresponding 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. +I/O bus used. See L
+for information on the format of hardware addresses. -Otherwise, if the record is configured to use the soft device support -modules, then it can be either a database link, a channel access link, or a -constant. Be aware that nothing will be written when OUT is a constant. See -L
for information on the format of the database and -channel access addresses. Also, see L in -this chapter for more on output to other records. +Otherwise, if the record is configured to use the soft device support modules, +then it can be either a database link, a channel access link, or a constant. Be +aware that nothing will be written when OUT is a constant. See L
+for information on the format of the database and channel access addresses. +Also, see L in this chapter for more on output +to other records. =head3 Operator Display Parameters diff --git a/modules/database/src/std/rec/calcRecord.dbd.pod b/modules/database/src/std/rec/calcRecord.dbd.pod index f017abdba..df1c60c81 100644 --- a/modules/database/src/std/rec/calcRecord.dbd.pod +++ b/modules/database/src/std/rec/calcRecord.dbd.pod @@ -28,8 +28,9 @@ recordtype(calc) { The Calc record has the standard fields for specifying under what circumstances the record will be processed. -These fields are listed in L. +These fields are described in L. +=fields SCAN, PHAS, EVNT, PRIO, PINI =head3 Read Parameters @@ -40,8 +41,9 @@ channel access link. If they are constants, they will be initialized with the value they are configured with and can be changed via C. They cannot be hardware addresses. -See L
for information on how to specify database -links. +See L
+for information on how to specify database links. =fields INPA, INPB, INPC, INPD, INPE, INPF, INPG, INPH, INPI, INPJ, INPK, INPL diff --git a/modules/database/src/std/rec/compressRecord.dbd.pod b/modules/database/src/std/rec/compressRecord.dbd.pod index d421fff5a..0365203c9 100644 --- a/modules/database/src/std/rec/compressRecord.dbd.pod +++ b/modules/database/src/std/rec/compressRecord.dbd.pod @@ -67,11 +67,12 @@ The record-specific fields are described below, grouped by functionality. =head3 Scanning Parameters The compression record has the standard fields for specifying under what -circumstances the record will be processed. These fields are listed in +circumstances the record will be processed. Since the compression record +supports no direct interfaces to hardware, its SCAN field cannot be set to C<<< +I/O Intr >>>. +These fields are described in L. -L. In addition, L -explains how these fields are used. Since the compression record supports no -direct interfaces to hardware, its SCAN field cannot specify C<<< I/O Intr >>>. +=fields SCAN, PHAS, EVNT, PRIO, PINI =head3 Algorithms and Related Parameters @@ -88,9 +89,11 @@ The following fields determine what channel to read and how to compress the data As stated above, the ALG field specifies which algorithm to be performed on the data. -The INP should be a database or channel access link. Though INP can be a constant, -the data compression algorithms are supported only when INP is a database link. See -L
for information on specifying links. +The INP should be a database or channel access link. Though INP can be a +constant, the data compression algorithms are supported only when INP is a +database link. See L
+for information on specifying links. IHIL and ILIL can be set to provide an initial value filter on the input array. diff --git a/modules/database/src/std/rec/dfanoutRecord.dbd.pod b/modules/database/src/std/rec/dfanoutRecord.dbd.pod index 6b5040091..d1f4d4dc8 100644 --- a/modules/database/src/std/rec/dfanoutRecord.dbd.pod +++ b/modules/database/src/std/rec/dfanoutRecord.dbd.pod @@ -59,8 +59,9 @@ undergoes no conversions before it is sent out to the output links. =head3 Write Parameters The OUTA-OUTH fields specify where VAL is to be sent. Each field that is to -forward data must specify an address to another record. See -L
for information on specifying links. +forward data must specify an address to another record. See L
+for information on specifying links. The SELL, SELM, and SELN fields specify which output links are to be used. diff --git a/modules/database/src/std/rec/eventRecord.dbd.pod b/modules/database/src/std/rec/eventRecord.dbd.pod index 811c387da..964c3973c 100644 --- a/modules/database/src/std/rec/eventRecord.dbd.pod +++ b/modules/database/src/std/rec/eventRecord.dbd.pod @@ -37,10 +37,10 @@ recordtype(event) { =head3 Scan Parameters The event record has the standard fields for specifying under what circumstances -it will be processed. If the SCAN field specifies C, then device -support will provide an interrupt handler, posting an event number when an I/O -interrupt occurs. -These fields are listed in L. +it will be processed. +These fields are described in L. + +=fields SCAN, PHAS, EVNT, PRIO, PINI =head3 Event Number Parameters @@ -73,8 +73,9 @@ 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
for information on the format of -hardware addresses and specifying links. +type used. See L
+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. diff --git a/modules/database/src/std/rec/longoutRecord.dbd.pod b/modules/database/src/std/rec/longoutRecord.dbd.pod index 7308d1138..52f5d9e5a 100644 --- a/modules/database/src/std/rec/longoutRecord.dbd.pod +++ b/modules/database/src/std/rec/longoutRecord.dbd.pod @@ -68,8 +68,9 @@ For soft records, the OUT output link can be a constant, a database link, or a channel access link. If the link is a constant, the result is no output. The DTYP field must then specify the C<<< Soft Channel >>> device support routine. -See L
for information on the format of hardware addresses -and database links. +See L
+for information on the format of hardware addresses and database links. =fields OUT, DTYP diff --git a/modules/database/src/std/rec/mbbiDirectRecord.dbd.pod b/modules/database/src/std/rec/mbbiDirectRecord.dbd.pod index df0914d03..ce27f0f8c 100644 --- a/modules/database/src/std/rec/mbbiDirectRecord.dbd.pod +++ b/modules/database/src/std/rec/mbbiDirectRecord.dbd.pod @@ -14,7 +14,8 @@ an array of 32 unsigned characters, each representing a bit of the word. These fields (B0-B9, BA-BF, B10-B19, B1A-B1F) are set to 1 if the corresponding bit is set, and 0 if not. -This record's operation is similar to that of the multi-bit binary input record, +This record's operation is similar to that of the +L, and it has many fields in common with it. This record also has two available soft device support modules: C and C. diff --git a/modules/database/src/std/rec/mbboDirectRecord.dbd.pod b/modules/database/src/std/rec/mbboDirectRecord.dbd.pod index 649e752c8..b2acc1b67 100644 --- a/modules/database/src/std/rec/mbboDirectRecord.dbd.pod +++ b/modules/database/src/std/rec/mbboDirectRecord.dbd.pod @@ -31,6 +31,8 @@ The mbboDirect record has the standard fields for specifying under what circumstances it will be processed. These fields are listed in L. +=fields SCAN, PHAS, EVNT, PRIO, PINI + =head3 Desired Output Parameters The mbboDirect record, like all output records, must specify where its output @@ -56,25 +58,32 @@ record writes the VAL field's value without any conversion. For records that are to write values to hardware devices, the OUT output link 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. +according to the I/O bus used. See L
+for information on the format of hardware addresses. -If the mbboDirect record does not use the C<<< Soft Channel >>> device support -module, then VAL is converted to RVAL, and RVAL is the actual 16-bit word sent -out. RVAL is set equal to VAL and then shifted left by the number of bits -specified in the SHFT field (the SHFT value is set by device support and is not -configurable by the user). RVAL is then sent out to the location specified in -the OUT field. +During record processing VAL is converted into RVAL, which is the actual 32-bit +word to be sent out. RVAL is set to VAL shifted left by the number of bits +specified in the SHFT field (SHFT is normally set by device support). RVAL is +then sent out to the location specified in the OUT field. -For mbboDirect records that specify a database link, a channel access link, or a -constant, the DTYP field must specify either one of two soft device support -routines--{Soft Channel} or C<<< Raw Soft Channel >>>. The difference between -the two is that C<<< Soft Channel >>> writes the desired output value from VAL -directly to the output link while C<<< Raw Soft Channel >>> writes the value -from RVAL to the output link after it has undergone the conversion described -above. +The fields NOBT and MASK can be used by device support to force some of the +output bits written by that support to be zero. By default all 32 bits can be +sent, but the NOBT field can be set to specify a smaller number of contiguous +bits, or MASK can specify a non-contiguous set of bits. When setting MASK it is +often necessary to set NOBT to a non-zero value as well, although in this case +the actual value of NOBT may be ignored by the device support. If a device +support sets the SHFT field it will also left-shift the value of MASK at the +same time. -=fields OUT, RVAL, SHFT, B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, BA, BB, BC, BD, BE, BF +For mbboDirect records writing to a link instead of to hardware, the DTYP field +must select one of the soft device support routines C<<< Soft Channel >>> or +C<<< Raw Soft Channel >>>. The C<<< Soft Channel >>> support writes the contents +of the VAL field to the output link. The C<<< Raw Soft Channel >>> support +allows SHFT to be set in the DB file, and sends the result of ANDing the shifted +MASK with the RVAL field's value. + +=fields OUT, RVAL, SHFT, MASK, NOBT =head3 Operator Display Parameters @@ -166,7 +175,8 @@ These parameters are used by the run-time code for processing the mbbo Direct record. MASK is used by device support routine to read the hardware register. Record -support sets low order NOBT bits. Device support can shift this value. +support sets the low order NOBT bits of MASK at initialization, and device +support is allowed to shift this value. MLST holds the value when the last monitor for value change was triggered. diff --git a/modules/database/src/std/rec/printfRecord.dbd.pod b/modules/database/src/std/rec/printfRecord.dbd.pod index 557cc9fb1..04c443471 100644 --- a/modules/database/src/std/rec/printfRecord.dbd.pod +++ b/modules/database/src/std/rec/printfRecord.dbd.pod @@ -25,7 +25,9 @@ recordtype(printf) { The printf record has the standard fields for specifying under what circumstances it will be processed. -These fields are listed in L. +These fields are described in L. + +=fields SCAN, PHAS, EVNT, PRIO, PINI =head3 String Generation Parameters @@ -144,7 +146,8 @@ which type of the data is requested through the appropriate input link. As with C a C<*> character may be used in the format to specify width and/or precision instead of numeric literals, in which case additional input links are used to provide the necessary integer parameter or parameters. See L
for information on specifying links. +Specification|https://docs.epics-controls.org/en/latest/guides/EPICS_Process_Database_Concepts.html#address-specification> +for information on specifying links. The formatted string is written to the VAL field. The maximum number of characters in VAL is given by SIZV, and cannot be larger than 65535. The LEN