Subject: $sv-ec Reference Proposal
From: Kevin Cameron (Kevin.Cameron@nsc.com)
Date: Fri Sep 27 2002 - 12:52:07 PDT
Here is a full proposal for references.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
5.7 References
References in SystemVerilog are syntactically similar to references in C++, with additional functionality to
mirror pointer usage in C. A reference is created by prefixing the equivalent variable declaration with '&', and
is made to refer to a particular variable or array element with the special assignment operator ":=". Any use
of a reference not involving a reference operator is equivalent to using the object that was assigned to the
reference. References are initially "null", and it is an error to use a null reference. A reference can be assigned
null to make it invalid. The following code creates an integer array and an integer reference:
integer i_array[5:0], &pia, // array and reference
index,data;
always @(index) pia := i_array[index]; // set reference
always @(data) pia = data; // assign data
always @(reset) pia := null; // need index first
If index changes to 2 then pia will refer to i_array[2], if data then changes to 10 i_array[2] will be assigned
10 immediately. If the index value for the array included X or Z values the reference would become invalid, the
same as if it was assigned null, and a subsequent attempt to use it would cause a runtime error.
References can be used in structs, but cannot be used in unions. References to references are disallowed.
5.7.1 Pass By Reference
Function and task argument identifiers can also be prefixed with "&" to indicate that data is not to be copied
and the function or task should use the same data as the caller. This is useful for functions that work on large
arrays. The size of an argument is dictated by the caller if the function argument is left unsized:
function int bin_find(integer item,integer &data[]); // binary search on ordered table
int l,r,i,t; // data assumed present
begin
l = $low(data); r = $high(data); // get array dimensions
t = (l+r)/2;
while (data[t] != item) begin
if (data[t] < item) l = t + 1;
else r = t - 1;
t = (l+r)/2;
end
bin_find = t;
end
endfunction
Functions can also return a value by reference, indicated by preceding the function name with "&".
Multi-dimensional array references can only be unsized in their outer dimension:
integer big_array [200:1][16:0],
sml_array [2:1][16:0],
& a_ref [] [16:0], // can refer to either big_array or sml_array
& s_ref[16:0]; // reference for the sub-dimension
...
a_ref := big_array;
s_ref := a_ref[12]; // big_array[12][16 .. 0]
s_ref[1] = 3; // big_array[12][1]
5.7.2 Reference Operators
When a reference refers to an element of an array the reference can be moved around within the array
by using the reference operators &++,&--,&+= and &-=. If the calculated step is beyond the valid
range of the array the reference will be considered invalid if dereferenced, but its value is held such
that it if the reverse step is applied it will have its original value. The operators have higher precedence
than assignments and return the new value of the reference. They can be thought of as operating on the
equivalent array index that the reference uses with ++,--,+= and -=, the following code fragments are
equivalent:
// without references
int i, array[6:0];
begin
i = 0;
array[i++] = 0;
array[i++] = 1;
// with references
int array[6:0],&pa;
begin
pa := array[0];
pa &++ = 0;
pa &++ = 1;
For symmetry with C a reference to a single item can be used with these reference operators, it is
treated the same as a reference to an array of one element.
The equivalence operators &== and &!= can be used to test that references are equivalent and valid,
an invalid reference dereferences as null for these operators.
The following code implements a linear search through an array of unknown size and returns
a reference to the found entry:
function int &lnr_find(integer item,integer &data[]); // linear search
integer &t;
begin
t := data[$low(data)];
while (t &!= null && t != item) t &++;
lnr_find := t; // will be an invalid reference if item not found
end
endfunction
The calling code can use a reference to hold the returned value, or assign to it
directly by using the call as the LHS of an assignment. The code below uses
the function above to maintain a table of values, if the return from the function
is null it adds the new value to the end of the table:
module table (input replace,input new_value)
int tbl_lst = 0;
integer &found,replace,new_value,table[1000];
always @ (replace)
found := lnr_find(replace,table);
if (found &== null) found := table[tbl_lst++];
found = new_value; // replace old value with new
end
end
5.7.3 Dynamic Objects
References are also used as handles to objects created dynamically with "new". Assigning
"new" to a reference creates an object of the type of the reference:
int &dyn_array[15:0];
...
dyn_array := new; // create new 16 value array
If the reference is unsized then the sized dimensions must be appended to "new":
integer &dyn_2d[][15:0];
...
dyn_2d := new[3:0]; // array is [3:0][15:0]
Objects created with new are destroyed immediately when there are no references to them.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Notes:
a) The proposal above does not mention the classes, semaphores and mailboxes which are
in the testbench donation. Their declaration would change slightly in that a class could
be declared statically or dynamically using a reference e.g.:
class Packet {...};
module foo;
Packet ps; // declare a static Packet
....
endmodule
function &new_pkt(input extra);
int extra;
begin
Packet &pd = new; // create a packet
pd.flags |= extra; // customize packet
new_pkt := pd; // return reference
end
endfunction
Semaphores and mailboxes would be handled similarly, and "var" is deprecated.
b) References are not pointers, so handing one to C code expecting a pointer is
not generally meaningful, however it would be possible to cast references into
pointers automatically if the data type follows C memory layout conventions.
Regards,
Kev.
This archive was generated by hypermail 2b28 : Fri Sep 27 2002 - 13:00:23 PDT