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
$onehotor$onehot0for 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
$countonesas 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 |
|---|---|---|---|---|
0000 | 0 | 0 | 1 | 0 |
0100 | 1 | 1 | 1 | 0 |
0110 | 2 | 0 | 0 | 0 |
01x0 | 1 | 1 | 1 | 1 |
xxxx | 0 | 0 | 1 | 1 |
1z10 | 2 | 0 | 0 | 1 |
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.
01x0 goes through two counts. Arrows show which count each function reads.- Neutral
- Result
- Step
- Data
- Count the ones
01x0has one bit that is 1. The x is not a 1, so the count is 1. - Three functions read that count
$countonesreturns 1.$onehotasks "is it exactly 1?" and$onehot0asks "is it at most 1?". Both say yes. - Count the unknown bits
A second count looks only for x and z.
01x0has one such bit. - One function reads that count
$isunknownasks "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.
$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.
The rule is rvalid |-> !$isunknown(rdata). The all-x idle bus at the third edge is not checked.
Tempting check for d = 10x1 | Result | Why it does not work |
|---|---|---|
d == 4'bxxxx | x, read as false | a comparison with an x bit is unknown, never true |
d != 4'b10x1 | x, read as false | the same: == and != cannot match an x |
d === 4'bxxxx | 0 | it matches only the vector that is x in every bit |
$isunknown(d) | 1 | it 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.
| Rule | Written 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.
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_x01x | Counts | Result |
|---|---|---|
$countbits(v, '1) | ones | 2 |
$countbits(v, '0) | zeros | 2 |
$countbits(v, 'x) | x bits | 2 |
$countbits(v, 'z) | z bits | 2 |
$countbits(v, 'x, 'z) | unknown bits | 4 |
$countbits(v, '1, '1) | ones: a repeated control bit counts once | 2 |
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.
| Case | Standard (IEEE 1800-2023 20.9) | Verilator 5.052 (measured) | Icarus 12 (measured) |
|---|---|---|---|
$isunknown(4'b10x1) | 1 | 0: the x is stored as 0 | 1 |
$countbits(v, 'x, 'z) on 10x1 | 1 | 0 | 1 |
a control bit 2'b10 | counts zeros (lowest bit used) | counts zeros | the run aborts with an internal error |
a variable assigned 4'b0xz0, then 4'b0110 in the same time step | 0110 is printed | 0000 is printed | 0110 is printed |
the same writes with #1 between them, read one time step later | 0110 is printed | 0110 is printed | 0110 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.
t=25 no_fight failed: gnt=0101 t=45 one_owner failed: gnt=0000 t=65 no_gift failed: req=0000 gnt=1000Check Yourself
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.
assert property (@(posedge clk)
$onehot(gnt)) else errors++;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
$onehotmeans exactly one 1;$onehot0means at most one 1, so all zeros passes.- An x or a z is never counted as a 1:
01x0is one-hot. $isunknownis 1 when any bit is x or z; negate it in a rule, and check only where the value is used.$countonesreturns a number; used alone as a condition it means "not zero".$countbitscounts the bits that match any of the control bits you list.