DSP - BLOCK THRESHOLD COUNT

Introduction link

The Block Threshold Count block chops the input stream into consecutive blocks of N samples and, at the end of each block, publishes how much of that block sat above and below a reference threshold $t$ driven on the THRESHOLD pin. With $d_i = x_i - t$:

$$ \mathrm{ABOVE_COUNT} = #{, i : d_i > 0 ,}, \qquad \mathrm{BELOW_COUNT} = #{, i : d_i < 0 ,} $$

$$ \mathrm{DUTY_CYCLE} = \frac{\mathrm{ABOVE_COUNT}}{N} ;\in; [0, 1] $$

Both comparisons are strict, so a sample sitting exactly on the threshold is counted in neither - see The on-threshold convention, which is the one place in this family where that rule is directly visible in a number.

N is a runtime input, not a property. You drive the exponent on the EXP pin and the block size is $N = 2^{\mathrm{EXP}}$:

Because N is a power of two, the division by N is an exact arithmetic shift. There is no divider, no reciprocal ROM and no rounding beyond the single final requantisation of the duty cycle into your Q format - which is also why the block size can be changed while the design is running, for free.

What it is FOR link

This is a discriminator plus a counter, and that combination is the standard way to measure, without leaving the fabric:

• a duty cycle - what fraction of the block a switching or gated signal spent in its high state;
• a comparator hit rate - with THRESHOLD at a discriminator level, ABOVE_COUNT is a time-over-threshold measure and, divided by N, an occupancy;
• a dead-time fraction - BELOW_COUNT over a busy/veto level;
• a threshold occupancy scan - THRESHOLD is a PIN, so a slow control loop can sweep it and read one point of the amplitude distribution per block, or servo it to hold a target occupancy;
• a baseline-referred activity measure - drive THRESHOLD from a slow baseline tracker and the counts follow the baseline automatically.

Cost link

One subtractor for $d = x - t$, one comparator per enabled direction, one counter of Max Block Exponent + 1 bits per counted direction, a hold register for each, and - if the duty cycle is on - one barrel shifter and one requantiser. No multiplier, no divider, no square root, and no serial arithmetic: the tail is a constant 2 clocks whatever is enabled.

When to use this instead of Block Statistics link

The all-in-one Block Statistics block is not deprecated and computes these same counts (under the names POS_COUNT and NEG_COUNT) among twenty other statistics. The rule is simple:

• you want several statistics of the SAME block - the counts and the mean and the RMS of the same N samples - use Block Statistics. They share one accumulator and one serial tail, so the second and third statistic are nearly free.
• you want exactly these numbers - use this block. Then you synthesise only them: the pin list, the logic and the tail are all that the counts need, and nothing else reaches the synthesiser. This block also adds the duty cycle, which the all-in-one block does not have - there you would divide POS_COUNT by N yourself.

Two Block Statistics blocks side by side would duplicate the accumulators; two per-operator blocks side by side duplicate them too. One Block Statistics block never does.

Pin Description link

Properties link

The on-threshold convention link

BOTH COUNTS ARE STRICT. A sample with $d = 0$ - one lying exactly on the threshold - is counted in NEITHER direction. Therefore

$$ \mathrm{ABOVE_COUNT} + \mathrm{BELOW_COUNT} ;\le; N $$

with equality only when no sample sits exactly on the threshold, and a flat signal parked exactly on it reports 0 and 0.

This is the block where that convention is observable. Everywhere else in the family an on-level sample contributes zero to a sum and is invisible; here it changes a count you can read. Three things follow, and they are worth reading twice:

• Do not assume BELOW_COUNT = N - ABOVE_COUNT. It is only true when no sample sits on the threshold. On quantised data, and especially with the threshold at a round number or on a signal that rests at its baseline, that assumption fails routinely.
• For “>=” semantics, drive THRESHOLD one LSB lower. That is the whole fix: the strict comparison against $t - 1,\mathrm{LSB}$ is the non-strict comparison against $t$.
• The two counts and the duty cycle are all consistent with each other, because they all come from the same strict comparisons of the same latched threshold.

DUTY_CYCLE is free link

N is a power of two, so $\mathrm{ABOVE_COUNT}/N$ is an arithmetic SHIFT: the count is shifted by $\mathrm{EXP}$ places and requantised into the DUTY_CYCLE Q format in the same final state that presents the counts. No divider, no extra clocks, no DSP - the tail is the same 2 clocks with the duty cycle on as without it.

The default format is Q1.15 unsigned, which spans 0.0 .. 1.0 with 1.0 landing exactly on 0x8000 - an all-above block reads as exactly one half of full scale, which is the natural reading of an unsigned Q1.15 number.

The duty cycle ALWAYS refers to the ABOVE count. There is no below-fraction output. If you want one, take BELOW_COUNT and divide it yourself; subtracting the duty cycle from 1 is only correct if you know that no sample sits exactly on the threshold - see the convention above.

DUTY_CYCLE is derived from the above-counter, so enabling it keeps that counter alive even when the ABOVE_COUNT pin itself is off. That configuration - duty cycle only - is a normal one and costs exactly one counter, one shifter and one requantiser.

Accuracy link

ABOVE_COUNT and BELOW_COUNT are bit exact: they are plain counters and the host regression demands tolerance ZERO against a Python golden that evaluates the definitions in exact integer arithmetic.

DUTY_CYCLE is exact too, up to the single final requantisation into the Q format you chose for it: the value $\mathrm{ABOVE_COUNT} \cdot 2^{-\mathrm{EXP}}$ is produced by a shift of an exact integer, with the selected rounding applied once. Give it enough fractional bits to resolve $1/N$ - with fewer fractional bits than EXP, neighbouring counts collapse onto the same output code.

Accumulation and IN_DV link

IN_DV is the only qualifier. It says “this clock carries a sample”: a sample is compared, counted, and counts towards N, exactly on the clocks where IN_DV is high. Clocks with IN_DV low are ignored completely - whatever sits on IN during them cannot corrupt the counts - while the tail keeps running, which is what you want: the tail has nothing to do with the input stream.

Unconnected, IN_DV ties to '1', EXP ties to 10 (N = 1024) and THRESHOLD ties to all zeros, so the block free-runs with nothing wired except IN and reports the occupancy above and below zero.

There is deliberately no CE pin. On the all-in-one Block Statistics block an earlier revision had one, and it did not survive synthesis: with nothing but internal state gated by it, Vitis could reason the frozen path away and delete the port from the generated entity while SciCompiler’s wrapper still wired it, which failed a real Vivado build with [VRFC 10-718] formal port <ce> does not exist in entity. The whole per-operator family was built without one. To stall this block, gate its IN_DV - a block that only counts on IN_DV has no need to be frozen.

The THRESHOLD pin link

THRESHOLD is an input pin in the input Q format, not a property - it is compared against the samples, so a separate format would only be a way to get it wrong. Like EXP, it is latched on the first accepted sample of a block and held for that whole block, so a mid-block change takes effect on the NEXT block and a count is never a mixture of two thresholds. That is what makes a threshold sweep meaningful: every published count belongs to exactly one threshold value, and SAMPLE_COUNT tells you the N it was taken over.

When EXP changes link

EXP is clamped to Max Block Exponent and then latched on the first accepted sample of a block, and held for that whole block. A change therefore takes effect on the NEXT block: a block in progress always finishes against the N it was started with, and a block is never emitted against a different N than the one it was counted over - which matters here more than elsewhere, because the duty cycle divides by exactly that N.

Timing: the latency contract link

OUT_DV pulses for one clock, L clocks after the clock on which the N-th sample of the block was accepted - not when that sample arrives. Every enabled output is updated on that same clock and on no other. For this block

$$ L = 2 $$

and it is a constant: there is no serial arithmetic here at all, so L does not depend on the input width, on the duty cycle format, on which outputs are enabled, on Max Block Exponent or on EXP. The two clocks are one to enter the final state and one to present the registered results.

The rule that governs the whole family is that the tail of one block must finish before the next block completes, i.e.

$$ 2^{\mathrm{EXP}} \ge L $$

If a block completes while the previous tail is still running, that block’s result is DROPPED: no OUT_DV for it, the counters are unaffected and later blocks come out correctly, but a result is silently skipped. There is no error pin for it.

With $L = 2$ that condition is $2^{\mathrm{EXP}} \ge 2$, i.e. EXP $\ge$ 1, so it cannot bite here: the only value that violates it is EXP = 0, a block of a single sample. The blocks where this rule really matters are the ones with a serial tail - Block RMS, Block Variance, Block Std Dev and Block Crest Factor, whose L runs to tens of clocks and whose minimum usable exponent the compiler prints in the compilation log.

Knowing where the block is: BUSY, INTEGRATING and SAMPLE_COUNT link

Three optional status outputs, all defaulting to NO. They answer different questions:

Every output of this block is a register, so each status bit is observed on the clock after the event that sets it:

• INTEGRATING rises on the clock after the FIRST sample of a block is accepted and falls on the clock after the N-th - it is high exactly while the block is ACCUMULATING.
• BUSY covers the accumulation and the tail. It rises with INTEGRATING, stays high across the tail, and its LAST HIGH CLOCK IS THE OUT_DV PULSE; it falls on the clock after.
• On a continuous stream the next block starts before the previous tail ends, so BUSY never drops and INTEGRATING dips for exactly one clock per block boundary - which makes it a free block marker.
• SAMPLE_COUNT is a fixed 32 bits and reads 1 after the first accepted sample, N after the N-th. It is NOT cleared at the block end: it HOLDS N through the tail and past OUT_DV, until the first sample of the next block takes it back to 1. So on the OUT_DV clock it reads the length of the block being presented - the exact denominator the counts should be read against, and the useful thing to latch alongside them. Only RESET clears it to 0.

Q formats link

IN and THRESHOLD share one fixed point format (integer bits, fractional bits, sign), the same convention as the Fixed P. family.

The counts have no Q format. They are integers, and their width is not a user choice: it is Max Block Exponent + 1 bits, which cannot overflow - neither count can exceed N. Nothing about them is ever requantised, so the Rounding and Saturation properties do not touch them.

DUTY_CYCLE has its own format and is the only output that is requantised, so it is the only place where Rounding (nearest / truncate) and Saturation (clip / wrap) apply. The default Q1.15 unsigned is the right choice for a fraction of 1: it cannot overflow, because the value is bounded by 1.0 and 1.0 is exactly representable.

Enabling and disabling outputs link

Each of the three outputs has its own enable. Turning one off removes the pin and all of its logic before synthesis (the enables are preprocessor switches on the HLS core, so nothing reaches the synthesiser at all). One internal dependency is resolved by the block, not by you: DUTY_CYCLE needs the above-counter, so enabling it builds that counter even when the ABOVE_COUNT pin is off. At least one output must be enabled - the property page refuses a configuration with all three off, because the block would have nothing to say.

Verification link

The core is regression tested by a host-side csim harness (tb/block-ops/run_tb.ps1) that runs one simulated clock at a time and follows OUT_DV. The expected values come from tb/block-ops/gen_golden.py, which evaluates the definitions above in exact arithmetic and shares no algorithm with the core; the tolerance is 0. Coverage includes pseudo-random input, a pulse train against a non-zero threshold, a signal with samples sitting exactly on the threshold (which pins the strict convention, and with it the fact that the two counts need not add up to N), a THRESHOLD pin that changes between blocks, a duty-cycle-only configuration with the ABOVE_COUNT pin disabled, an all-outputs configuration, and an EXP that changes half way through a block. The status outputs are checked clock by clock against the contract above. A cross-check compiles this core and the all-in-one block_stats.cpp into the same binary, drives them with identical stimulus, and compares the two clock by clock.