RRM 3-14 Pulse Train

From EPICSWIKI

EPICS Record Reference Manual


pulseTrain

The normal use for the pulseTrain record type is to generate a pulse train for output.

Parameter Fields

The fields fall into the following categories:

  • scan parameters
  • trigger parameters
  • pulse parameters
  • output parameters
  • operator display parameters
  • run-time parameters

Scan Parameters

The pulseTrain record has the standard fields for specifying under what circumstances the it will be processed. These fields are listed in Scan Fields. In addition, Scanning Specification explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

Trigger Parameters

These fields determine the source of the trigger for each train. At least the gate type (GTYP) field must be configured by the user. It can be either Hardware or Software. If Hardware, then the triggers are device dependent, and the HGV field determines gating control, HGV being device dependent.

If the user configures GTYP to be software, then the soft gate value (SGV) field provides gating control. This field has the same possible values as HGV, Active and Inactive, triggering a pulse when Active, or not triggering a pule when Inactive. The SGV value can be retrieved from the location specified in the Soft Gate Location (SGL) field, which must be a database link.

The CEDG, CTYP, ECS, and ECR field may not have significance for all device support modules. For the modules they apply to, they control the timing of pulses. The CEDG field determines whether clock timing occurs on the rising edge or falling edge of a signal. It has two choices: Rising Edge or Falling Edge. The CTYP field determines whether the timing is controlled externally or internally and has two choices: Internal and External. The ECS and ECR fields have significance only if CTYP specifies External.


FieldSummaryTypeDCTInitialAccessModifyRec Proc MonitorPP
GTYPGate Type RECCHOICEYes0YesYesNoNo
HGV Hardware Gate ValueSHORTYes0YesYesNoNo
SGLSoft Gate Location (Input Link)INLINKYes0NoNoN/ANo
SGVSoft Gate Value RECCHOICEYes0YesYesNoNo
CTYP Clock Type RECCHOICEYes0YesYesNoNo
CEDGClock Signal EdgeRECCHOICEYes0YesYesNoNo
ECSExternal Clock SourceSHORTYes0YesYesNoNo
ECRExternal Clock Rate, in HzDOUBLEYes0YesYesNoNo


Pulse Parameters

These parameters characterize the pulse train. The pulse train is characterized by the time duration of the entire train, which the user specifies in the Period (PER) field, and the percentage of that time when the signal is high, which the user specifies in the Duty Cycle (DCY) field. In the UNIT field, the user must specify the units of time which the time period is in. This field can be either Seconds, Milliseconds, Microseconds, Nanoseconds, or Picoseconds.


FieldSummaryTypeDCTInitialAccessModifyRec Proc MonitorPP
UNITUnits of timeRECCHOICEYes0YesYesNoNo
PERPeriod, in UNITs DOUBLEYes0YesYesYesNo
DCYDuty Cycle, percent DOUBLEYes0YesYesYesNo


Output Parameters

The OUT field contains the location where the pulse train record sends the actual pulse. If the pulseTrain uses hardware device support, it must specify the address of the I/O card, and the DTYP field must specify the appropriate 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. You can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

For records that use soft device support, OUT can be a constant, a database link or a channel access link, though if it's a constant, no output will be written. See Address Specification for information on how to specify database links.


FieldSummaryTypeDCTInitialAccessModifyRec Proc MonitorPP
OUTOutput Link OUTLINKYes0NoNoN/ANo
DTYPDevice TypeDEVCHOICEYes0YesNoNoNo


Operator Display Parameters

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the pulse train either textually or graphically. The operating range fields (HOPR and LOPR) for the pulse train record apply to the VAL, PER, or OPER fields. They are retrieved when the get_graphic_double and get_control_double record support routines are called for that field. The PREC field is used when the get_precision record routine is called. It is used only for the value in the VAL field.

See Fields Common to All Record Types for more on the record name (NAME) and description (DESC) fields.


FieldSummaryTypeDCTInitialAccessModifyRec Proc MonitorPP
HOPR High Operating RangeFLOATYes4.3e+9YesYesNoNo
LOPR Low Operating Range FLOATYes0YesYesNoNo
PRECDisplay Precision SHORTYes0YesYesNoNo
NAMERecord NameSTRING [29]Yes0YesNoNoNo
DESCDescriptionSTRING [29]YesNullYesYesNoNo


Alarm Parameters

The pulse train record has the alarm parameters common to all record types. Alarm Fields lists other fields related to a alarms that are common to all record types.


Run-time Parameters

The record uses these fields for processing and to implement monitors. The VAL field is not used.

The Old Period (OPER), Old Duty Cycle (ODCY), and Old Soft Gate Value (OSGV) fields are used to implement monitors for the PER, DCY, and SGV fields, respectively. When the current value doesn't equal the old value, monitors are called for that field.


FieldSummaryTypeDCTInitialAccessModifyRec Proc MonitorPP
OPEROld Period, in UNITSDOUBLENo0YesNoYesYes
ODCYOld Duty Cycle, percentDOUBLENo0YesNoYesYes
OSGVOld Soft Gate ValueSHORTNo0YesNoNoNo
VALValue SHORTNo0YesYesYesYes
LLOWLow Logic Level RECCHOICEYes0YesYesNoNo


Record Support

Record Support Routines

init_record

This routine first checks that device support is available. If SGL is a constant then HGV is initialized with its value or a channel access link is created if SGL type is PV_LINK.

Device support is then checked to see if write_pt is defined.

If device support includes init_record, it is called.

process

See next section.

get_value

Fills in the values of struct valueDes so that they refer to VAL.

get_precision

Retrieves PREC.

get_graphic_double

Sets the upper display and lower display limits for a field. If the field is VAL, PER, or OPER the limits are set to HOPR and LOPR, else if the field has upper and lower limits defined they will be used, else the upper and lower maximum values for the field type will be used.

get_control_double

Sets the upper control and the lower control limits for a field. If the field is VAL or PER the limits are set to HOPR and LOPR, else if the field has upper and lower limits defined they will be used, else the upper and lower maximum values for the field type will be used.


Record Processing

Routine process implements the following algorithm:

  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.
  2. If SGL is DB_LINK and GTYP is Software, get SGV from SGL. If SGV has changed, save the duty cycle DCY value, call the write_pt routine with duty cycle =0, reset the duty cycle to the saved value, and set alarms if return status not zero. Then set the old soft gate value OSGV to SGV.
  3. Call write_pt routine. If device support set PACT to TRUE, then return.
  4. Set UDF to FALSE.
  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 on PER and DCY are invoked if values have changed.
    • NSEV and NSTA are reset to 0.
  6. Scan forward link if necessary, set PACT FALSE, and return.


Device Support

Fields Of Interest To Device Support

Each record must have an associated set of device support routines. The primary responsibility of the device support routines is to issue commands to the output device. The device support routines are primarily interested in the following fields:

NameSummaryDescription
UNITUnits of timeThis field will be used to identify the time units used for time fields.
OUTOutput LinkThis field is used by the device support routines to locate its output.
PERPeriod, in UNITsDevice support must use PER for pulse period.
DCYDuty Cycle, percentDevice support must use DCY for the percent of time the signal is high.
LLOWLow Logic LevelDevice support must use to determine logic low level.
CEDGClock Signal EdgeThis field is used by the device support routines to force counting on leading or falling edge of signal.
GTYPGate Type Device support is responsible for using IGV to determine gating control if GTYP is internal, or SGV if GTYP is external.
SGVSoft Gate Value
CTYPClock Type If CTYP is external, device support is responsible for using ECR for the clock rate and if CTYP is internal, ECS is the clock source.
ECSExternal Cocksurely
ECRExternal Clock Rate, in Hz


Device Support Routines

Device support consists of the following routines:

report

report()

This routine is optional. If provided, it prints a report of all device modules.

init

init()

This routine is called once during IOC initialization.

init_record

init_record(precord)

This routine is optional. If provided, it is called by the record support init_record routine.

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 ioEvent scanner.

write_pt

write_pt(precord)

This routine issues commands to the output device. It returns the following values:

  • 0: Success.
  • Other: Error.


Soft Device Support

The Soft Channel device support module writes the current value of VAL.




EPICS Record Reference Manual - 19 MAY 1998