Scaler Record (v 3.2) and related software

Tim Mooney

Contents

Overview

This documentation describes version 3.2 of the EPICS scaler record, and related EPICS software required to build and use it. This version of the record is compatible with EPICS 3.13.0, and is incompatible with any earlier version of EPICS.

The scaler record provides support for a bank of up to 16 32-bit counters (scaler channels) controlled by a common start/stop mechanism. The record divides scaler channels into two groups according to the values of each channel's gate-control field (Gn): simple counters [Gn = "N" (0)], and preset counters [Gn = "Y" (1)]. Simple counters are zeroed immediately before counting begins, and count upwards. Preset counters are simple counters that will not count higher than a preset value. The first preset counter to reach its preset value stop all counters. (The hardware may actually implement a preset counter by loading in the preset value, and counting down to zero. If so, device support is expected to maintain the fiction that all counters count up from zero.) Currently device support exists for the Joerger VSC8 and VSC16 family of VME scalers (TTL, NIM, and ECL versions).

Scaler channel 1 receives special treatment: it is presumed to count a fixed-frequency clock signal, and its value is presumed to indicate the time interval during which counting was enabled. The fields

satisfy the following equations: 
	T = S1 / FREQ
	TP = PR1 / FREQ
It is the user's job to make sure that FREQ actually contains the frequency of the clock signal input to scaler channel 1.

Scaler channel 1 does not have to be used in this way: if FREQ, TP, and T are ignored, then this counter behaves like any other counter.

This is how the scaler record is intended to be used:

  1. The user sets FREQ to the frequency of the clock signal input to scaler channel 1.
  2. The user sets TP (time preset) and/or PRn (preset value for scaler channel n)
  3. The user sets CNT to "Count" (1), initiating counting.
  4. The counters count until one of them reaches its preset value, whereupon the record resets CNT to "Done" (0), or the user manually resets CNT to "Done" (0), causing couting to stop.

This version of the scaler record maintains two counting modes: normal and background (also called AutoCount). Normal counting is controlled by the CNT ("Count/Done") field, the time preset, and other presets, as described above. Background counting is controlled by the CONT ("OneShot/AutoCount") field, normally ignores user preset values, and is intended to give the user continuous updates whenever the scaler would otherwise be idle.

When CONT = "AutoCount" (1), and no normal counting operation is already in progress, the scaler waits for the AutoCount delay (DLY1); counts for the AutoCount period (TP1); and displays the result. If the AutoCount period (TP1) is less than .001 s, we default to the normal criteria for determining the count period. If the AutoCount Display Rate (RAT1) is greater than zero (Hz), then the scaler values are displayed at that rate while background counting is in progress. Background counting is interrupted immediately whenever a normal counting operation is started with the CNT field, and the results of a normal counting operation are held for one second after the scaler finishes that operation before background counting begins again. Background counting never affects the state of the CNT field, so this field can always be used to determine when a normal counting operation has begun and finished.

The scaler record is unlike most other EPICS records in that its processing is neither "synchronous" nor "asynchronous", as these terms are used in the EPICS Record Reference Manual. Currently, the PACT field is always FALSE after record processing has completed, even though the scaler may be counting. This means the record always responds to channel-access puts, and that counting can be stopped at any time. The record's forward link is not executed until the scaler has stopped counting.

Field Descriptions

In addition to fields common to all record types (see the EPICS Record Reference Manual for these) the scaler record has the fields described below.

Alphabetical list of record-specific fields

NOTE: Hot links in this table take you only to the section in which the linked item is described in detail. You'll probably have to scroll down to find the actual item.
Name Access Prompt Data type Comment
CARD R Card Number SHORT Which VME card
CNT R/W* Count RECCHOICE (0:"Done", 1:"Count")
CONT R/W* OneShot/AutoCount RECCHOICE (0:"OneShot", 1:"AutoCount")
D1...D16 R/W Count Direction n RECCHOICE (0:"Up", 1:"Dn")
DLY R/W Delay FLOAT before counting
DLY1 R/W Auto-mode Delay FLOAT before counting
EGU R/W Units Name STRING 8 characters
FREQ R/W Time base freq DOUBLE e.g., 1e7
G1...G16 R/W Gate Control n RECCHOICE preset? (0:"N", 1:"Y")
NCH R Number of Channels SHORT from device
NM1...NM16 R/W Scaler n name STRING user's field
OUT R Output SpecificationOUTLINK link to hardware
PCNT R Prev Count RECCHOICE private
PREC R/W Display Precision SHORT num decimal places
PR1...PR16 R/W Preset n LONG preset values
RATE R/W Display Rate (Hz.) FLOAT in [0..60] Hz
RAT1 R/W Auto Display Rate (Hz.) FLOAT in [0..60] Hz
S1...S16 R Scaler n LONG results
SS r Scaler state SHORT state of hardware
T R Timer DOUBLE elapsed time
TP R/W Time Preset DOUBLE preset time
TP1 R/W Time Preset DOUBLE preset time (auto mode)
US r User state SHORT state of user request
VAL R/W Result DOUBLE not used
VERS R Code Version FLOAT code version
Note: In the Access column above:
R Read only
r Read only, not posted
R/W Read and write are allowed
R/W* Read and write are allowed; write triggers record processing if the record's SCAN field is set to "Passive."
N No access allowed

Control/status fields
Name Access Prompt Data type Comments
CNT R/W* Count RECCHOICE (0:"Done", 1:"Count")
User sets this field to "Count" (1) to start counting. When a preset is reached, counting will stop, this field will be reset to "Done" (0), and the forward link will be fired. If this field is set to "Done" (0) while counting is in progress, counting will be stopped, the accumulated counts will be reported, and the forward link will be fired.
CONT R/W* OneShot/AutoCount RECCHOICE (0:"OneShot", 1:"AutoCount")
User sets this field to "AutoCount" (1) to enable background counting. (See also autocount delay (DLY1), autocount display rate (RAT1), and autocount time presetTP1.)
G1...G16 R/W Gate control RECCHOICE (0:"N", 1:"Y")
There are 16 of these fields, one per channel. These fields determine whether the associated scalers are to be used as simple scalers (Gn=0) or preset scalers (Gn=1). When Gn is set to 1, the record will ensure than PRn is nonzero (will set it to 1000, if it was zero). When PRn is set to any positive value, the record will set Gn to 1.
PR1...PR16 R/W Preset n LONG
Preset values for the associated scalers. If scaler n has been designated as a preset scaler (i.e., if Gn=1), then when the scaler reaches the count PRn, all scalers will be disabled, and the record will report counting has completed by setting CNT=0. If scaler n has not been designated as a preset scaler, the PRn is ignored. When PRn changes to any positive value, the record will set Gn to 1.
TP R/W Time preset DOUBLE
This field specifies for how long, in seconds, the scaler is to count if no other preset stops it. TP is effectively a proxy for the preset field, PR1, associated with scaler 1. Whenever TP changes, the record will set PR1 = TP*FREQ, and otherwise behave as though the user had changed PR1.
TP1 R/W AutoCount Time preset DOUBLE
This field specifies the background-counting period in seconds.
DLY R/W Delay (sec) FLOAT
The delay, in seconds, that the record is to wait after CNT goes to 1 before actually causing counting to begin.
DLY1 R/W AutoCount Delay (sec) FLOAT
The delay, in seconds, between successive background-counting periods.
RATE R/W Display rate (Hz.) FLOAT
This field specifies the rate in Hz. at which the scaler record posts scaler information while counting is in progress. If this field is zero, counts are displayed only after counting has stopped. Max. rate: 60 Hz.
RAT1 R/W AutoCount Display rate (Hz.) FLOAT
This field specifies the rate in Hz. at which the scaler record posts scaler information while background counting is in progress. If this field is zero, counts are displayed only after background counting has stopped. Max. rate: 60 Hz.

Data fields
Name Access Prompt Data type Comments
FREQ R/W Time base freq. (EGU) DOUBLE
The frequency (in Hz) of the clock signal counted by scaler 1. The record uses this field to convert between time values (T and TP, in seconds) and values associated with scaler 1 (S1 and PR1). It is the user's responsibility to ensure that this field has the correct value.
S1...S16 R Scaler n value (EGU) LONG
The counts accumulated by the scalers. These are posted periodically (at RATE Hz.) while counting is in progress, and once after counting stops.
T R Timer (EGU) DOUBLE
This field is a proxy for the value field, S1, associated with scaler 1. Whenever S1 changes, the record will set T = S1/FREQ.

Link fields
Name Access Prompt Data type Comments
OUT R Output Specification OUTLINK This field specifies the hardware to be controlled.

Miscellaneous fields
Name Access Prompt Data type Comments
NM1...NM16 R/W Scaler n name STRING Names the user has given to individual scaler channels.
PREC R/W Display Precision SHORT The number of digits to the right of the decimal that are to be displayed by MEDM and other channel-access clients.
EGU R/W Engineering Units STRING String sent to channel-access clients who ask for engineering units.
VERS R Code Version FLOAT Version number of the recScaler.c code.
CARD R Card Number SHORT
The VME card number, derived from the output link. Cards are numbered from zero according to their VME addresses. Joerger-scaler types VSC8 and VSC16 are in the same series, since they are handled by the same device-support module.
NCH R Number of channels SHORT The number of channels actually supported by the underlying hardware, as reported by device support.

Private fields
Name Access Prompt Data type Comments
D1...D16 R/W Count direction RECCHOICE (0:"Up", 1:"Dn")
These fields are intended for the private use of the record, and may disappear or become read-only in the future. For scaler n, Dn is direction in which the hardware actually counts.
PCNT R/W Previous count RECCHOICE (0:"Done", 1:"Count")
Previous value of CNT.
SS r Scaler state SHORT state of hardware
US r User state SHORT state of user's request
VAL R/W Result DOUBLE Not used.

Files, device support

The following table briefly describes all of the files required to implement and use the scaler record. The reader is assumed to be familiar with the IOC Applications: Building and Source/Release Control document which describes how to build an EPICS application tree into which these files are to be placed, and how to run "gnumake" to build record and device support. These files can all be obtained from the EPICS Software Distribution (in the custom-software section).

SOURCE CODE
files to be placed in <top>/<app>App/src/
scalerRecord.c Record support for the scaler record
devScaler.h Header included by record and device support
devScaler.c Device support for Joerger VSC8 and VSC16
scalerRecord.dbd This file defines all of the fields menus, etc. for the scaler record.
*Include.dbd This file is not included in the distribution. However, the user must edit this file and add the following lines: 
# Database definition for scaler record
include "scalerRecord.dbd"
# Device support for scaler record
device(scaler,VME_IO,devScaler,"Joerger VSC8/16")
Makefile.Vx This file is not included in the distribution. However, the user must edit this file and add, for example, the following lines: 

RECTYPES += scalerRecord.h
SRCS.c += ../scalerRecord.c ../devScaler.c
PROD += scalerRecord.o
PROD += devScaler.o

MEDM DISPLAY SCREENS
files to be placed in <top>/<app>App/op/adl/
scaler.adl tiny operator screen for 8-channel scaler
scaler16.adl same, but for 16-channel scaler
scaler_more.adl medium operator screen
scaler16_more.adl same, but for 16-channel scaler
scaler_full.adl big operator screen
scaler16_full.adl same, but for 16-channel scaler
scaler_full_calc.adl big operator screen with user calculations
scaler16_full_calc.adl same, but for 16-channel scaler
These files build medm screens to access the scaler record and related process variables in the database included with this distribution. To use one of them from the command line, type, for example 
medm -x -macro "P=XXX:,S=scaler1" scaler.adl

where XXX:scaler1 is the name of a scaler record in an IOC.

These files can also be used as related displays from other medm screens by passing the argument "P=XXX:,S=scaler1".

EPICS STARTUP FILES
files to be placed in <top>/iocBoot/ioc<name>/
st.cmd Startup script
This file is not included in the distribution. Here are annotated excerpts from a startup file that supports scalers: 
#######################################################################
# vxWorks startup script to load and execute system (iocCore) software.
Load standard EPICS software 
# Load EPICS base software
ld < bin/iocCore
Load custom EPICS software (including motor support) 
ld < bin/xxxApp.o
# Load scaler record and device support (if they're not included in xxxApp.o)
ld < bin/scalerRecord.o
ld < bin/devScaler.o
Scaler-related databases 
# Tell EPICS all about the record types, device-support modules, drivers,
# etc. in the software we just loaded (xxxApp)
dbLoadDatabase("dbd/xxxApp.dbd")

# scalers
dbLoadRecords("xxxApp/Db/Jscaler.db","P=xxx:,S=scaler1,C=0")
dbLoadRecords("xxxApp/Db/Jscaler.db","P=xxx:,S=scaler2,C=1")
Specify scaler-controller board address, interrupt vector, etc.
#VSCSetup(nCards, baseAddress, intVectBase)
VSCSetup(2, 0xD0000000, 200)
nCards the actual number of cards may be less, but not greater than this
baseAddress the base address of the first card of a series. This must agree with address jumpers on the actual card(s).

Joerger VSC8 and VSC16 have base addresses in the A32 address space, on a 256-byte (0x100) boundary. (I.e., these cards require 256 bytes each, and must all be addressed contiguously as, e.g., 0xD0000000, 0xD0000100,...).

intVectBase the interrupt vector that will be loaded into the first card of a series. Succeeding cards will be loaded with intVectBase+1, intVectBase+2, etc. Stay in the range [64..255]. (The interrupt level is read from the hardware.)
Start EPICS 
iocInit

BACKUP/RESTORE (BURT) REQUEST FILES
files to be placed in <top>/<app>App/op/burt/
scalerSettings.req sample request file to save settings of one scaler database. Edit this file, supplying names of the scaler records whose settings you want saved. (The sample file also saves the states of other records in the sample database, Jscaler.db, that control calculations done when the scaler finishes counting.)
yyScalerSettings.req save settings of a specified scaler record. This file is #include'd (once for each scaler) by scalerSettings.req.
These files tell the backup/restore tool how to save scaler settings. To use them from the command line, type, for example 
burtrb -f scalerSettings.req -o myScalerSettings.snap
To restore the scaler settings saved by the above commands, type 
burtwb -f myScalerSettings.snap

Restrictions

 When AutoCount is enabled, with a very short counting time (TP1) and delay time (DLY1), the scaler can swamp the network with data.
Suggestions and comments to:
Tim Mooney : (mooney@aps.anl.gov)
Last modified: November 24, 1997