RRM 3-14 Pulse Train
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.
| Field | Summary | Type | DCT | Initial | Access | Modify | Rec Proc Monitor | PP |
|---|---|---|---|---|---|---|---|---|
| GTYP | Gate Type | RECCHOICE | Yes | 0 | Yes | Yes | No | No |
| HGV | Hardware Gate Value | SHORT | Yes | 0 | Yes | Yes | No | No |
| SGL | Soft Gate Location (Input Link) | INLINK | Yes | 0 | No | No | N/A | No |
| SGV | Soft Gate Value | RECCHOICE | Yes | 0 | Yes | Yes | No | No |
| CTYP | Clock Type | RECCHOICE | Yes | 0 | Yes | Yes | No | No |
| CEDG | Clock Signal Edge | RECCHOICE | Yes | 0 | Yes | Yes | No | No |
| ECS | External Clock Source | SHORT | Yes | 0 | Yes | Yes | No | No |
| ECR | External Clock Rate, in Hz | DOUBLE | Yes | 0 | Yes | Yes | No | No |
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.
| Field | Summary | Type | DCT | Initial | Access | Modify | Rec Proc Monitor | PP |
|---|---|---|---|---|---|---|---|---|
| UNIT | Units of time | RECCHOICE | Yes | 0 | Yes | Yes | No | No |
| PER | Period, in UNITs | DOUBLE | Yes | 0 | Yes | Yes | Yes | No |
| DCY | Duty Cycle, percent | DOUBLE | Yes | 0 | Yes | Yes | Yes | No |
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.
| Field | Summary | Type | DCT | Initial | Access | Modify | Rec Proc Monitor | PP |
|---|---|---|---|---|---|---|---|---|
| OUT | Output Link | OUTLINK | Yes | 0 | No | No | N/A | No |
| DTYP | Device Type | DEVCHOICE | Yes | 0 | Yes | No | No | No |
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.
| Field | Summary | Type | DCT | Initial | Access | Modify | Rec Proc Monitor | PP |
|---|---|---|---|---|---|---|---|---|
| HOPR | High Operating Range | FLOAT | Yes | 4.3e+9 | Yes | Yes | No | No |
| LOPR | Low Operating Range | FLOAT | Yes | 0 | Yes | Yes | No | No |
| PREC | Display Precision | SHORT | Yes | 0 | Yes | Yes | No | No |
| NAME | Record Name | STRING [29] | Yes | 0 | Yes | No | No | No |
| DESC | Description | STRING [29] | Yes | Null | Yes | Yes | No | No |
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.
| Field | Summary | Type | DCT | Initial | Access | Modify | Rec Proc Monitor | PP |
|---|---|---|---|---|---|---|---|---|
| OPER | Old Period, in UNITS | DOUBLE | No | 0 | Yes | No | Yes | Yes |
| ODCY | Old Duty Cycle, percent | DOUBLE | No | 0 | Yes | No | Yes | Yes |
| OSGV | Old Soft Gate Value | SHORT | No | 0 | Yes | No | No | No |
| VAL | Value | SHORT | No | 0 | Yes | Yes | Yes | Yes |
| LLOW | Low Logic Level | RECCHOICE | Yes | 0 | Yes | Yes | No | No |
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:
- 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.
- 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.
- Call write_pt routine. If device support set PACT to TRUE, then return.
- Set UDF to FALSE.
- 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.
- 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:
| Name | Summary | Description |
|---|---|---|
| UNIT | Units of time | This field will be used to identify the time units used for time fields. |
| OUT | Output Link | This field is used by the device support routines to locate its output. |
| PER | Period, in UNITs | Device support must use PER for pulse period. |
| DCY | Duty Cycle, percent | Device support must use DCY for the percent of time the signal is high. |
| LLOW | Low Logic Level | Device support must use to determine logic low level. |
| CEDG | Clock Signal Edge | This field is used by the device support routines to force counting on leading or falling edge of signal. |
| GTYP | Gate Type | Device support is responsible for using IGV to determine gating control if GTYP is internal, or SGV if GTYP is external. |
| SGV | Soft Gate Value | |
| CTYP | Clock 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. |
| ECS | External Cocksurely | |
| ECR | External 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
