Array methods and with expressions

Methods that search

SystemVerilog arrays and queues have built-in locator methods that search them. A with clause gives the condition, and the name item stands for each element in turn.

find returns the matching elements, and find_index returns their indexes. find_first, find_last and their _index forms return at most one match. min, max and unique need no condition.

Every locator method returns a queue, because the answer may be empty. Check size() before you read element 0 of the result, or an empty search quietly reads as 0. Searching an empty array also returns an empty queue.

Every locator method leaves the original collection unchanged. Only the reordering methods described below modify the array they are called on.

The methods work on associative arrays too. There, find_index returns keys, so age.find_index with (item > 1000) on int age [int] gives the IDs of the stuck reads directly.

Methods that reduce

Reduction methods combine all the elements into one value: sum, product, and, or and xor. Without a with clause, the result has the element type, so the sum of a byte array wraps at 8 bits.

They are handy beyond counting. The xor of every data word in a burst gives a quick signature to compare against, and or tells you whether any beat set a given bit.

With a with clause, the standard gives the result the type of the with expression. A comparison such as item > 1000 is 1 bit wide, so the sum of the comparisons is 1 bit wide too, and it can only be 0 or 1.

To count matches, cast inside the clause: age.sum() with (int'(item > 1000)). Each match then contributes a 32-bit 1. A cast outside the call comes too late, because the carry bits have already been lost. The same typing rule applies to and, or and xor with a with clause.

n = age.sum() with (item > 1000);
// 1-bit result: 2 matches give 0

n = age.sum() with (int'(item > 1000));
// 32-bit result: 2 matches give 2

Methods that reorder

sort, rsort, reverse and shuffle rearrange the array itself and return nothing. sort accepts a with clause that gives the sort key, such as q.sort() with (item.id) for a queue of structs.

These methods apply to fixed arrays, dynamic arrays and queues. An associative array cannot be reordered, because its keys already fix the order.

Reordering destroys the arrival order, and arrival order may be exactly what you need to check. Sort a copy instead: after sorted = got; sorted.sort();, the original got still shows the order in which the responses came.

Finding duplicates and naming the iterator

unique returns one copy of each distinct value. If u = ids.unique(); leaves u.size() smaller than ids.size(), some ID appears more than once, which on many buses means two reads were issued with an ID still in use.

The name item is only a default; q.find(x) with (x > 1000) names the iterator x instead. The iterator also knows its own position: item.index is the index of the current element.

That makes order checks short. For a queue of beat numbers, q.find_index with (item != item.index) returns every position holding the wrong beat, so an empty result means the beats arrived in order.

Choosing between a method and a loop

A method states the question in one line, and a reader can check it at a glance. A foreach loop is longer, but it can stop early, report as it goes, or update several counters at once.

Either way, the same rule applies to the answer. Make the variable that holds a count as wide as the largest count you could see, and think about the empty case before you index a result.

Methods also make intent easy to review. pending.find_index with (item > 1000) reads almost like the sentence it implements, whereas a loop has to be read line by line to see what it does.

Try it

find_index on the associative array returned the keys, 7 and 12, which are the IDs of the stuck reads. The cast inside the with clause made the count 2, and the empty search returned an empty queue.

Sorting the copy left the arrival order intact. Change the threshold to 10 and predict every line before you run it.

Check yourself

module tb;
  int q [$];
  int r [$];
  initial begin
    q = '{4, 9, 1, 9};
    r = q.find_index with (item == 9);
    $display("%0d %0d %0d", r.size(), r[0], r[1]);
  end
endmodule

return q.sum() with (int'(item > lim));

int r[$];
r = q.find_first with (item > lim);
return r.size();

int r[$];
r = q.find with (item > lim);
return r.size();

int n = 0;
foreach (q[i]) if (q[i] > lim) n++;
return n;

Practice

• Wide population reduction Implement · Easy