13.2.12 Interrupt Frequency In [T-Series Datasheet]

Overview

T4 Capable DIO: DIO4, DIO5, DIO6, DIO7, DIO8, DIO9 (aka FIO4, FIO5, FIO6, FIO7, EIO0, EIO1)

T7 Capable DIO: DIO0, DIO1, DIO2, DIO3, DIO6, DIO7 (aka FIO0, FIO1, FIO2, FIO3, FIO6, FIO7)

T8 Capable DIO: DIO0, DIO1, DIO2, DIO3, DIO4, DIO5, DIO6, DIO7, DIO8, DIO9, DIO10, DIO11, DIO12, DIO13, DIO14, DIO15 (aka FIO0, FIO1, FIO2, FIO3, FIO4, FIO5, FIO6, FIO7, EIO0, EIO1, EIO2, EIO3, EIO4, EIO5, EIO6, EIO7)

Requires Clock Source: No. Uses core clock / 2.

Index: 11

Streamable: Yes—integer READ registers only.

Interrupt Frequency In will measure the frequency of a signal on the associated DIO line.

This interrupt-based digital I/O extended feature (DIO-EF) is not purely implemented in hardware, but rather firmware must service each edge.  See the discussion of edge rate limits at the bottom of this page.

To measure the frequency, the T-series device will measure the duration of one or more periods. There are several option available to control the way the LabJack does this. The number of periods to be averaged, the edge direction to trigger on, and whether to measure continuously or in one-shot mode can all be specified.

The clock source for this feature is simply half the core frequency (See the Clock Speed section for information about your device clock speed settings):

ClockFrequency = CoreFrequency / 2
Period(s) = DIO#_EF_READ_A / ClockFrequency
Frequency (Hz) = ClockFrequency / DIO#_EF_READ_A

The maximum measurable time is 107 s. The number of periods to be averaged multiplied by the maximum expected period must be less than 107 s or the result will overflow:

107 > (NumToAverage * MaxPeriod)

By default, Interrupt Frequency In operates in one-shot mode where it will measure the frequency once after being enabled and a new measurement only once after each read. The other option is continuous mode, where the frequency is constantly measured (every edge is processed) and READ registers return the most recent result. Running in continuous mode puts a greater load on the processor.

Configure

DIO#_EF_ENABLE: 0 = Disable, 1 = Enable
DIO#_EF_INDEX: 11
DIO#_EF_CLOCK_SOURCE: Not Used.
DIO#_EF_CONFIG_A: Default = 0.  Bit 0: Edge select; 0 = falling, 1 = rising. Bit 1: 0 = one-shot, 1 = continuous.
DIO#_EF_CONFIG_B: Default = 0 which equates to 1.  Number of periods to be measured and averaged.
DIO#_EF_CONFIG_C: Not used.
DIO#_EF_CONFIG_D: Not used.

One-Shot
When one-shot mode is enabled, the DIO_EF will complete a measurement then go idle. No more measurements will be made until the DIO_EF has been read or reset.

Continuous
When continuous mode is enabled, the DIO_EF will repeatedly make measurements. If a new reading is completed before the old one has been read the old one will be discarded.

Averaging
When averaging is enabled, the DIO_EF will wait for the specified number of measurements to be completed, then the average of the measurements will be made available in the READ registers.

CONFIG_A Value Map

To configure the DIO_EF measurement mode, refer to the table below for the mapping between the bit field value and the corresponding integer value which should be written to DIO#_EF_CONFIG_A.

Update

No update operations can be performed with Interrupt Frequency In.

Read

Results are read from the following registers.

DIO#_EF_READ_A: Returns the average period per cycle in ticks (core clock ticks / 2).
DIO#_EF_READ_B: Returns the total core clock tick count (Core_Timer) at time of measurement.
DIO#_EF_READ_A_F: Returns the average period per cycle in seconds. Takes into account the number of periods to be averaged and the core clock speed.
DIO#_EF_READ_B_F: Returns the average frequency in Hz. Takes into account the number of periods to be averaged and the core clock speed.

Note that all "READ_B" registers are capture registers.  All "READ_B" registers are only updated when any "READ_A" register is read.  Thus it would be unusual to read any B registers without first reading at least one A register.

Stream Read

All operations discussed in this section are supported in command-response mode.  In stream mode, you can read from the integer READ registers (A, B, A_AND_RESET), but as mentioned in the Stream Section those reads only return the lower 16 bits so you need to also use STREAM_DATA_CAPTURE_16 in the scan list to get the upper 16 bits.

Reset

DIO#_EF_READ_A_AND_RESET: Returns the same data as DIO#_EF_READ_A and then clears the result so that zero is returned by subsequent reads until another full period is measured (2 new edges).
DIO#_EF_READ_A_AND_RESET_F: Returns the same data as DIO#_EF_READ_A_F and then clears the result so that zero is returned by subsequent reads until another full period is measured (2 new edges).

One-shot, Continuous, Read, Read and Reset

When you configure this feature you can choose one-shot or continuous mode, and when you read from this feature you can do so without or with reset.  This leads to 4 different behaviors.

One common scenario is an application that should always display the most recent frequency measurement.  You don't want the display to go to 0 if you are reading faster than the pulses are coming in, but rather want it to keep returning the last measurement it did get.  This is typically accomplished with one-shot and read without reset, but continuous can also be used.

Another common scenario is where you are reading faster than pulses are coming in, you want 1 and only 1 read to return a measurement when available, and want extra reads to return 0.  This is typically accomplished with continuous and read with reset.

One-shot, read without reset:

• When a measurement has been completed, the value(s) are stored and the DIO_EF will be paused.
• When the READ_A register is read, the stored value for READ_A will be returned.
• Reading again, before another measurement has been completed, will return the previous result.
• At most, every other period will be measured. The delay between completing a measurement and the read causes come portion of a period to be missed.
• Use this mode when you need to be able to continuously read the most recent measurement and when you want to reduce the LabJack's processor loading.

One-shot, read with reset:

• When a measurement has been completed, the value is stored, and the DIO_EF will be paused.
• When the READ_A register is read, the stored value for READ_A will be returned and then that stored value will be set to zero. After the read has been completed, a new measurement will be started.
• Reading from READ_A again before another measurement has been completed will return zero.  READ_B will continue to return the most recent value.
• At most, every other period will be measured. The delay between completing a measurement and the read causes come portion of a period to be missed.
• Use this mode when you need to get a result once for each new measurement and zero otherwise. This mode is also useful for reducing the LabJack's processor loading.

Continuous, read without reset:

• Each time a measurement is completed, the value is stored. The previously stored value will be overwritten, even if it has not been read.
• When the READ_A register is read, the stored value for READ_A will be returned.
• Measures every period as long as the signal frequency and processor utilization allow.
• Use this mode when you need to measure every period, or you want the value from the most recent measurement.

Continuous, read with reset:

• Each time a measurement has been completed, the value is stored. The previously stored value will be overwritten, even if is has not been read.
• When the READ_A register is read, the stored value for READ_A will be returned and then that stored value will be set to zero.
• Read B, will always return the value from the most recent measurement.
• Measures every period as long as the signal frequency and processor utilization allow.
• Use this mode when you need to measure every period, and you only want a non-zero value when a new measurement has been completed.

Example

To configure Interrupt Frequency In on DIO6 you can simply write to 2 registers:

DIO6_EF_ENABLE = 0
DIO6_EF_INDEX = 11
DIO6_EF_ENABLE = 1

Now you can read the period in seconds from a 4th register DIO6_EF_READ_A_F.

Edge Rate Limits

This interrupt-based digital I/O extended feature (DIO-EF) is not purely implemented in hardware, but rather firmware must service each edge. This makes it substantially slower than other DIO-EF that are purely hardware-based.  To avoid missed edges, the aggregate limit for edges seen by all interrupt-based DIO-EF is 70k edges/second.  If stream mode is active, the limit is reduced to 20k edges/second.  Excessive processor loading (e.g. a busy Lua script) can also reduce these limits.  Note that interrupt features must process all edges, rising & falling, even if a given feature is configured to only look at one or the other. Additionally, note that intensive interrupt based features may limit the maximum streaming rates due to processor loading.

The more proper way to think of the edge limit, and understand error that could be introduced when using multiple interrupt-based DIO-EF, is to consider that the interrupt that processes an edge can take up to 14 μs to complete.  When a particular channel sees an applicable edge, an IF (interrupt flag) is set for that channel that tells the processor it needs to run an ISR (interrupt service routine) for that channel.  Once an ISR is started, it runs to completion and no other ISR can run until it is done (except that stream interrupts are higher priority and will preempt other interrupts).  When an ISR completes, it clears the IF for that channel.  So it is okay to have edges on multiple channels at the same time, as long as there is not another edge on any of those channels before enough time to process all the initial edges.

Say that channel A & B have an edge occur at the same time and an ISR starts to process the edge on channel A.  If channel A has another edge during the first 14 μs, that edge will be lost.  If channel B has another edge during the first 14 μs, the initial edge will be lost.  If channel B has another edge during the second 14 μs (during the ISR for channel B), the new edge will be lost.