Subject: Re: DirectC: C layer revised
From: Andrzej Litwiniuk (Andrzej.Litwiniuk@synopsys.com)
Date: Tue Jan 14 2003 - 08:03:09 PST
> I have embedded a few comments and suggestions for clarifications
> and embellishments. Great job.
>
> Regards,
> Doug
Thanks, Doug!
My comments are after yours.
> > Overview of C layer
> > ===================
> >
>
> DOUG: This document discusses the C layer, but it only addresses
> the case in which SV calls C functions.
You are absolutely right (sigh ...).
This document addresses solely SV-to-C calls.
> Most of the material
> in here applies to C calling SV, however.
Let's hope you are right :-)
> Would it be possible to extend the detailed presentation of
> the intricate details such that C calling SV is addressed as well?
I'll try to do this.
> Some points I can think of that would need addressing:
> - delinearization and denormalization of C array ranges
Will [n] ---> [0:n-1] do?
> - Handling of char* args passed from the C side
They should be treated as opaque pointers.
> - Call-by-reference details
> - Opaque pointer details (and usefulness?)
> The John/Joao proposal has some information on C-calling-SV,
> but nothing equivalent to the details in your work here.
> I would really like it if this document could be extended
> to discuss these issues. A few paragraphs and examples is
> probably all it would take.
> > There are also functions for bit selects and limited (up to
> > 32 bits) partial bit
> > selects.
> >
> > Array slices are not supported.
>
> DOUG: The difference between "array slices" and "part selects" is
> not perfectly clear. Perhaps a little elaboration here would
> be a good clarification. For part selects, you probably
> mean a slice of a packed array of bit or logic type, right?
You are right again. What about the following wording:
"There are also functions for bit selects and limited (up to 32 bits) partial
bit selects ("partial bit selects" refer here to slices of packed arrays of
types 'bit' or 'logic').
Array slices are not supported for unpacked arrays."
> > Argument passing
> > =================
> >
>
> DOUG: This section is one area that would need to be updated to
> address the C-calls-SV direction.
Yes.
> > Include files
> > =================
> >
> > (All names are provisional and subject to discussion and improvment.)
> >
> > The C layer of SV DirectC interface defines two include files
> > corresponding to
> > the two levels of compatibility (binary level and source code level):
> > - "svc_bin.h"
> > - "svc_src.h"
>
> DOUG: My suggestion for these file names is:
> - "svc.h" - SVC interface functions required by standard.
> Provides for binary compatability.
> - "svc_impl.h" - Implementation-specific SVC functions.
> Provides for source compatability.
>
> The svc_bin.h and svc_src.h names are fine with me if my
> suggestions are not popular.
Either version is fine with me. Folks, which names do you like more?
Or perhaps you've got better suggestions?
> > "svc_bin.h"
> > =================
> >
> > /* 2-state and 4-state vectors, modelled upon PLI's avalue/bvalue */
> > #define VEC32_NEEDED(WIDTH) (((WIDTH)+31)>>5)
> >
> > typedef unsigned int
> > svBitVec32; /* (a chunk of) packed bit array */
> >
> > typedef struct { unsigned int c; unsigned int d;} /* as in VCS */
> > svLogicVec32; /* (a chunk of) packed logic array */
>
> DOUG: This name should be more descriptive IMO:
> WORDS_NEEDED_FOR_VEC32(WIDTH)
> -or-
> VEC32_WORDS_NEEDED(WIDTH)
Well, actually the macro calculates the number of elements(chunks) of an array
of type 'svBitVec32' or 'svLogicVec32' rather than a number of memory words.
A wild idea: what about CANONICAL_SIZE(WIDTH) ?
> > void svGetPartSelectBit(svBitVec32* d, svBitPackedArr s,
> > int i, int w);
> > void svPartGetSelectLogic(svLogicVec32* d, svLogicPackedArr
> > s, int i, int w);
> DOUG: The "PartGet" portion of this function name is transposed.
Corrected it (to svGetPartSelectLogic) . Thanks!
> > Open (Unsized) Arrays and Abstract Access - Overview
> > ====================================================
> >
> >
> > The programmer will always have a choice, whether to specify a formal
> > argument as a sized array or as an open (unsized) array.
>
> DOUG: It would be nice to cross-reference the pertinent part
> of "17 items" that shows the syntactic differences on the SV side.
Something like "see item 16th of '17 items' document"?
Perhaps the following example might be helpful:
Example 2.5 - sized vs. unsized array [2.5 because between 2 and 3]
=====================================
SV:
// both unpacked arrays are 64 by 8 elements, packed 16-bit each
logic [15: 0] a_64x8 [63:0][7:0];
logic [31:16] b_64x8 [64:1][-1:-8];
extern void foo(input logic [] i [][]);
// 2-dimensional unsized unpacked array of unsized packed logic
extern void boo(input logic [31:16] i [64:1][-1:-8]);
// 2-dimensional sized unpacked array of sized packed logic
foo(a_64x8);
foo(b_64x8); // C code may use original ranges [31:16][64:1][-1:-8]
boo(b_64x8); // C code must use normalized ranges [15:0][0:63][0:7]
> > In the former case all indices will be normalized on the C
> > side (i.e. 0 and up)
> > and the programmer is assumed to know the size of an array.
> > Programmer is also assumed to be capable of figuring out how
> > the ranges of
> > the actual argument will map onto C-style ranges.
> > Hint: programmers may decide to stick to [n:0]name[0:k] style
> > ranges in SV.
>
> DOUG: I would like to see this exposition part briefly discuss
> array range direction topics:
> - When using the term "LSB" in this document, exactly what is
> it referring to? The LSB of the normalized C array?
> Or the LSB of the formal SV argument?
> When referring to the LSB of the actual argument it seems we
> are referring to the rightmost bit of the argument.
> When referring to the LSB of the formal argument it seems we
> are referring to the 0'th bit of the normalized C array.
> I'm thinking about the following kind of situations on the SV side:
>
> extern "C" void userSvFuncDesFormal(input logic[31:0] formalArg);
> extern "C" void userSvFuncAscFormal(input logic[0:31] formalArg);
>
> reg [31:0] descendingReg;
> reg [0:31] ascendingReg;
> reg someScalar;
>
> userSvFuncDesFormal(ascendingReg);
> userSvFuncDesFormal(descendingReg);
> userSvFuncDesFormal({descendingReg[30:0], someScalar});
> userSvFuncAscFormal(ascendingReg);
> userSvFuncAscFormal(descendingReg);
> userSvFuncAscForma({someScalar, ascendingReg[2:31], someScalar);
> - When using the word "ascending" (or "incrementing", as you have done)
> what exactly is it referring to? It must be referring to the
> actual SV argument side.
>
> I hope these thoughts give you some ideas on how to clarify this topic.
> I think clarifications will be necessary for unambiguous reading
> of the spec. For the open array case, it does seem we need to
> index based on the SV actual. What will happen if concatenation
> cases such as above are used?
I'm not sure I can answer all those valid questions.
Generally I don't see any issues with open arrays and abstract access,
because then SV indexing along with SV semantics is used.
There are obvious issues, however, with direct access, where C layout is used.
I'm not sure what would be the mapping from SV indices to C indices.
In particular, if an array is declared as [n:k] in SV, which element will
have index 0 in C: [n] or [m]?
I'll appreciate some help in clearing it out.
LRM 13.7 (page 11) seems to suggest that any packed array (or structure) may
be treated as declared as [n-1:0]:
"One or more elements of the packed array may be selected assuming an [n-1:0]
numbering".
> > Open array querying functions
> > =============================
> >
> > These functions are modelled upon SV array querying functions, with
> > the same semantics (cf. LRM 16.3):
> >
> > /* h= handle to open array, d=dimension */
> >
> > /* For unpacked part */
> > int svUnpackedLeft(svHandle h, int d);
> > int svUnpackedRight(svHandle h, int d);
> > int svUnpackedLow(svHandle h, int d);
> > int svUnpackedHigh(svHandle h, int d);
> > int svUnpackedIncrement(svHandle h, int d);
>
> DOUG: The name of this function could be improved.
Following Francoise's suggestion, I skipped "Unpacked"/"Packed" part of the
names, and now they are as follows:
int svLeft(svHandle h, int d);
int svRight(svHandle h, int d);
int svLow(svHandle h, int d);
int svHigh(svHandle h, int d);
int svIncrement(svHandle h, int d);
int svLength(svHandle h, int d);
int svDimensions(svHandle h);
Note that they mimic names from LRM 16.3: $NAME --> svNAME.
> Instead of a 1 or -1 return, I think it makes more
> sense to treat this as a boolean:
>
> int svUnpackedIsAscending(svHandle h, int d);
>
> Return 1 if true, 0 if false.
> Please consider the suggestion, which I think
> will improve readability in the C code.
> Same kind of suggestion applies to other
> functions relating to Ascending/Incrementing ranges.
> > int svUnpackedLength(svHandle h, int d);
> DOUG: Suggest renaming to
> int svUnpackedDimensionLength(svHandle h, int dimension);
> for clarity (a la Francoise commentary)
Although I generally agree with you, nevertheless I believe that preserving
the names from LRM 16.3 and their relevant semantics will be easier for
the users.
It might be confusing that the same info, say, the number of elements in the
dimension, is provided by $Length() in SV code, but by svDimensionLength() in
C code. The pair $Length()/svLength() seems more intuitive.
> > Access via canonical representation
> > -----------------------------------
> >
> > Element of an array is identified by indices bound by the
> > ranges of the
> > actual argument. In other words, original SV values are used
> > for indexing.
>
> DOUG: This is clear, as I mentioned above.
> However, what happens for fancy cases in the actual argument,
> like concatenations, or some kinds of coercions.
Whatever is the form of the actual argument, it shall have well specified
semantics in SV (I hope!). That semantics is supposed to include the ranges.
The interface will merely use such ranges, whatever they are.
For example, SV is supposed to provide semantics for construct like this:
{ a[5:3], 1'b0, b[12:20] } [5]
So I hope we could simply refer to LRM here.
This archive was generated by hypermail 2b28 : Tue Jan 14 2003 - 08:04:28 PST