Bit-Vector Functions

Check grant vectors, enables and buses with $onehot, $onehot0, $isunknown, $countones and $countbits, and know what each does with x and z.

You Will Be Able To

  • Choose $onehot or $onehot0 for a rule about a grant or select vector.
  • Catch x and z on a bus with $isunknown, on the edges where the bus must be known.
  • Use $countones as a number, and say what it means as a Boolean.
  • Count any mix of 0, 1, x and z bits with $countbits.
Lesson
A1.8
Time
20 min
Runs on
Verilator
Check
5 questions

An arbiter drives a 4-bit grant vector, and the rule bgack |-> $onehot(gnt) passed in every test. Then a gate-level run showed gnt = 01x0 for a whole burst, and the rule still passed.

gnt$countones$onehot$onehot0$isunknown
00000010
01001110
01102000
01x01111
xxxx0011
1z102001

Five results for six vectors, measured on Icarus 12. An x or a z is never counted as a 1, so 01x0 has exactly one 1 and is "one-hot".

All five functions count bits, and each row of the table follows from what its function counts.

One Counter Under Five Names

$countbits(v, ...) counts the bits of v that have one of the values you list. The other four functions are fixed uses of that counter.

Two Counts Feed Four FunctionsThe vector 01x0 goes through two counts. Arrows show which count each function reads.
  • Neutral
  • Result
  • Step
  • Data
data: where the transaction goes
Two counts feed four functionsThe vector `01x0` goes through two counts. Arrows show which count each function reads. neutral Vector gnt = 01x0 result Count of 1 bits $countbits(v, '1) result Count of x and z $countbits(v, 'x, 'z) step $countones the count itself step $onehot count == 1 step $onehot0 count <= 1 step $isunknown count != 0 bitsbits1111
  1. neutral Vectorgnt = 01x0
    • bits → Count of 1 bits
    • bits → Count of x and z
  2. result Count of 1 bits$countbits(v, '1)
    • 1 → $countones
    • 1 → $onehot
    • 1 → $onehot0
  3. step $countonesthe count itself
  4. step $onehotcount == 1
  5. step $onehot0count <= 1
  6. result Count of x and z$countbits(v, 'x, 'z)
    • 1 → $isunknown
  7. step $isunknowncount != 0
  1. Count the ones

    01x0 has one bit that is 1. The x is not a 1, so the count is 1.

  2. Three functions read that count

    $countones returns 1. $onehot asks "is it exactly 1?" and $onehot0 asks "is it at most 1?". Both say yes.

  3. Count the unknown bits

    A second count looks only for x and z. 01x0 has one such bit.

  4. One function reads that count

    $isunknown asks "is it more than 0?". It says yes. Only this function notices the x.

Read the diagram as text
  • Vector: gnt = 01x0
  • Count of 1 bits: $countbits(v, '1)
  • Count of x and z: $countbits(v, 'x, 'z)
  • $countones: the count itself
  • $onehot: count == 1
  • $onehot0: count <= 1
  • $isunknown: count != 0
  • Vector → Count of 1 bits: bits
  • Vector → Count of x and z: bits
  • Count of 1 bits → $countones: 1
  • Count of 1 bits → $onehot: 1
  • Count of 1 bits → $onehot0: 1
  • Count of x and z → $isunknown: 1

The one-hot functions never look at the second count. A rule that needs a known vector must ask for it.

You can call all five in any expression: in a concurrent assertion, an immediate assertion, an if or an assign. $countbits and $countones return an int. The other three return one bit.

$onehot: Exactly One Bit Is 1

$onehot(v) is 1 when exactly one bit of v is 1. Use it where one owner must exist: a grant vector while the bus is owned, a one-hot state register, a decoded select.

A grant vector at six edges
012345gnt000101000000011010001111ones10214$onehot(gnt)no ownertwo ownersfour owners
Scroll horizontally ↔

$onehot is 0 for no ones and for more than one. A check on every edge fails three times here.

$onehot0: At Most One Bit Is 1

$onehot0(v) is 1 when no bit or exactly one bit is 1. The 0 in the name stands for "or zero". Use it where idle is legal: a grant vector on an idle bus, a chip-select bus, an interrupt-acknowledge vector.

The bus may be idle

no_fight: assert property (@(posedge clk)
  $onehot0(gnt)) else errors++;

All zeros passes. Two grants fail.

The bus is owned

one_owner: assert property (@(posedge clk)
  bgack |-> $onehot(gnt)) else errors++;

While bgack is 1, all zeros fails too.

Most vectors need both rules. $onehot0 holds on every edge. $onehot holds only while something must be selected, so it sits behind an antecedent.

$isunknown: Some Bit Is x or z

$isunknown(v) is 1 when at least one bit of v is x or z. It is the "bad" answer, so a rule negates it: !$isunknown(v).

An idle bus is often x or z by design. So check only on the edges where the value is used, such as while rvalid is 1.

A read data bus at four edges
0123rvalidrdata001111000011x100xxxxxxxxzzzz0001$isunknown(rdata)rule fails?noyesno: idleyesone x bit is enoughz counts too
Scroll horizontally ↔

The rule is rvalid |-> !$isunknown(rdata). The all-x idle bus at the third edge is not checked.

Tempting check for d = 10x1ResultWhy it does not work
d == 4'bxxxxx, read as falsea comparison with an x bit is unknown, never true
d != 4'b10x1x, read as falsethe same: == and != cannot match an x
d === 4'bxxxx0it matches only the vector that is x in every bit
$isunknown(d)1it asks about any bit

Measured on Icarus 12. Only $isunknown answers "is any bit unknown?".

A One-Hot Rule That Also Needs Known Bits

Back to the hook. $onehot(01x0) is 1, because the vector has exactly one 1. If the x may hide a second grant, join the two questions.

Counts ones only

bgack |-> $onehot(gnt)

Passes on 01x0 and z010.

One 1, and every bit known

bgack |-> $onehot(gnt) && !$isunknown(gnt)

Fails on any x or z.

$countones: The Number of 1 Bits

$countones(v) returns how many bits of v are 1, as an int. Compare it with a limit, or with another count.

RuleWritten with $countones
At most two lanes are active$countones(lane_en) <= 2
Never more grants than requests$countones(gnt) <= $countones(req)
A pointer changes at most one bit per step$countones(ptr ^ $past(ptr)) <= 1
An even number of bits is set$countones(v) % 2 == 0

A count turns many "which bits?" rules into one comparison.

$countones as a Boolean

A count used where a condition is expected is true when it is not 0. So $countones(v) alone means "at least one bit is 1", the same as |v.

That is useful on purpose: req_seen |-> $countones(gnt) says "some grant is up". It is also an easy slip. If you meant "exactly one", the comparison == 1 must be there.

The same vector, read two ways
01234gnt00010110000011110100$countones(gnt)12041as a Booleantruefalsetrue== 1truefalsetrue2 is true4 is true
Scroll horizontally ↔

As a Boolean, two and four grants look fine. Only the zero is false.

$countbits: You Choose What to Count

$countbits(v, c1, c2, ...) counts the bits of v whose value equals one of the control bits. A control bit is '0, '1, 'x or 'z. You must give at least one.

Call on v = 10zz_x01xCountsResult
$countbits(v, '1)ones2
$countbits(v, '0)zeros2
$countbits(v, 'x)x bits2
$countbits(v, 'z)z bits2
$countbits(v, 'x, 'z)unknown bits4
$countbits(v, '1, '1)ones: a repeated control bit counts once2

Measured on Icarus 12. Every bit has exactly one of the four values, so the four single counts add up to the width, 8.

Two details. A control bit wider than one bit uses only its lowest bit, so 2'b10 counts zeros. A control bit can be a variable, which lets one rule count different values in different modes.

CaseStandard (IEEE 1800-2023 20.9)Verilator 5.052 (measured)Icarus 12 (measured)
$isunknown(4'b10x1)10: the x is stored as 01
$countbits(v, 'x, 'z) on 10x1101
a control bit 2'b10counts zeros (lowest bit used)counts zerosthe run aborts with an internal error
a variable assigned 4'b0xz0, then 4'b0110 in the same time step0110 is printed0000 is printed0110 is printed
the same writes with #1 between them, read one time step later0110 is printed0110 is printed0110 is printed

Where the two simulators leave the standard. The script that measures these rows is in the site repository.

Try It

Each bug breaks one rule. Two grants at 25 break $onehot0. At 45 the bus is owned with no grant: $onehot0 accepts all zeros, but $onehot behind bgack does not.

At 65 one grant is up on an idle bus. Both one-hot rules accept that. Only the count against req sees a grant that nobody asked for.

Change no_gift to $countones(gnt) |-> $countones(req), which reads both counts as Booleans. Predict which of the three bugs it still reports.

RUNVerilator · simulator service
Edit the code, then run it
Expected: t=25 no_fight failed: gnt=0101 t=45 one_owner failed: gnt=0000 t=65 no_gift failed: req=0000 gnt=1000

Check Yourself

Predict the outputIcarus keeps the x. The line prints $onehot, $onehot0, $isunknown and $countones, in that order. Predict the exact output.
module tb;
  logic [3:0] gnt = 4'b0x10;
  initial $display("%b %b %b %0d", $onehot(gnt), $onehot0(gnt), $isunknown(gnt), $countones(gnt));
endmodule
Spot the bugA chip-select bus may be idle (all zeros), and two selects at once is a bug. Each option is a rule for it. Which rule fails on legal traffic?
ConceptA rule reads bgack |-> $countones(gnt). What does it check while bgack is 1?
Read the waveformThe rule is rvalid |-> !$isunknown(rdata), on a four-state simulator. At which edges does it fail?
Sampled values at five edges
01234edge12345rvalidrdataxxxx101010z0x0000x00
Scroll horizontally ↔

One sample per rising edge.

ConceptWhat does $countbits(bus, 'x, 'z) == 0 say about bus?

Common Mistakes

Wrong Use $onehot(gnt) on every edge for a bus that may be idle.

All zeros has no 1, so the rule fails on every idle edge.

Fix Use $onehot0 on every edge, and $onehot only behind the condition that says the bus is owned.

Before
assert property (@(posedge clk)
  $onehot(gnt)) else errors++;
After
assert property (@(posedge clk)
  bgack |-> $onehot(gnt)) else errors++;

Wrong Trust $onehot to reject a vector with an x or a z in it.

It counts only the 1 bits, so 01x0 and z010 pass.

Fix Add !$isunknown(v) when the bits must also be known.

Wrong Write rvalid |-> $isunknown(rdata) to catch unknown data.

$isunknown is 1 for the bad case, so this rule passes on unknown data and fails on good data.

Fix Negate it: rvalid |-> !$isunknown(rdata).

Wrong Leave out the comparison and write bgack |-> $countones(gnt) for "exactly one grant".

A bare count is true for any number above 0, so two grants pass.

Fix Compare the count: $countones(gnt) == 1.

Remember

  • $onehot means exactly one 1; $onehot0 means at most one 1, so all zeros passes.
  • An x or a z is never counted as a 1: 01x0 is one-hot.
  • $isunknown is 1 when any bit is x or z; negate it in a rule, and check only where the value is used.
  • $countones returns a number; used alone as a condition it means "not zero".
  • $countbits counts the bits that match any of the control bits you list.

Practice

Report a problem with this page