Subject: [sv-cc] Draft proposal for DPI import/export syntax
From: Joao Geada (Joao.Geada@synopsys.com)
Date: Mon Mar 03 2003 - 11:30:36 PST
========================================
REQUIREMENTS (as given to sv-ec)
========================================
1. Export declarations require:
- a means to declare that a SV function is to be made accessible to a
foreign programming language (e.g. C);
- specifying a function as exported does not change its semantics or
usage
- must allow an optional identifier to be used in the foreign code; by
default foreign name and System Verilog name will be identical
- must provide full hierarchical path identifying a unique instance
(unless $root scope function)
Note: tasks may not be exported; therefore there is no need for
redundant keyword "function"; similarly there is no need for repeating
function result types and argument specification. However such
redundancy may be desirable for language consistency.
2. Extern declarations require:
- a means to declare that a SV visible function is to be provided by a
foreign programming language (eg C) (ie function's body is foreign)
- must provide function result type and directions and types of formal
arguments; the syntax should be as close as possible to the syntax for
SV function declarations; note that DirectC extends the syntax for
specifying types of formal arguments by allowing unsized ranges,
denoted by '[]'.
- in SV syntax, invocation of the functions declared as extern must be
identical to invocation of any other normally declared SV function
- additionally provide further information about the
function. Specifically, as SV compiler will not have visibility into
the implementation of the function, it needs to know:
1. whether the function is 'pure', meaning all invocations with same
arguments result in the same output values and have no side effects
whatsoever; 'pure' function must not have inout or output arguments.
2. whether the function needs to be aware of its context (such as
current instance)
3. whether the function will make use of any other SV API such that it
may access (read or write) signals other than those being passed
through the function's argument list.
Actually, we plan to bundle 2 and 3 together, they are also mutually
exclusive with 1; therefore there are 3 possible combinations:
1) default
2) 'pure'
3) 'context' denoting (ii)+(iii)
Note: It is an option to have an identifier representing the foreign
function name. This is only supported for symmetry with export
declaration, if required, but this is not required by SV-CC.
========================================
Original syntax:
========================================
SV functions to be made available to C:
[in $root scope only]
export ["cname"] [path.] svfuncname;
C functions to be made available to SV:
[in $root scope only]
extern [pure|context] cname(ansi-style-arguments);
========================================
Existing externs/exports in SV
========================================
declaration of out-of-block definitions for class methods (section 11.20)
(approximately) in class declaration context:
extern [public|protected|private|virtual]+ [function return-type|task] ( ansi-arguments );
for exact syntax, see grammar productions for function_prototype (page 233 in SV3.1 draft 3)
and task_prototype (page 234, SV3.1draft3)
modport declarations:
(approximately) in interface context:
{import|export} {task|function} named_prototype
(for exact syntax, see section 18.2, page 180)
extern declaration:
(approximately) in interface context:
extern {forkjoin task|function} named_prototype;
(for syntax, see section 18.5, page 188)
========================================
Issues with original SV-CC syntax
========================================
1. Syntax has a somewhat different "feel" than all other extern/export usages in SV.
a) all omit function/task keyword
Sure, this is redundant in SV3.1 as the DPI interface only accepts functions,
but are we sure that this constrait is going to be there forever ?
b) export def does not have a prototype
Again, theoretically this is redundant as it is supposed to match the declaration,
but repeating this will help ensure consistency of prototypes across the DPI,
particularly since I would assume that the C coder would prefer to be referring to the
export declaration rather than searching for/looking at the source code of the definition
========================================
Proposed solution
========================================
My proposal would be as follows:
At any scope where a function declaration can occur, permit the following
declarations:
import DPI [pure|context] [cname=] <named_function_proto>;
export DPI [cname =] function fname;
This syntax does not require any new keywords: DPI is an identifier qualifying
the type of import/export. For SV3.1 only the identifier "DPI" is recognized
at this location.
PS: alternative syntax preferred by Andrzej:
import extern [pure|context] [cname=] <named_function_proto>;
export extern [cname=] function fname;
Note that the <named_function_proto>, as defined in SV3.1 draft3 spec (page 233)
must be modified slightly so that the argument list permits open arrays. Only
imported DPI functions can use this argument type. We may additionally also
want to relax the prototype syntax to permit unnamed arguments, but this will
be harder to sell to sv-ec.
Semantics:
in both cases, cname is the name of the C side function (imported/exported),
fname is the SV name for the same function.
If cname not explicitly given, it will be the same as the SV function fname.
An error will be generated iff the SV function name has characters that are
not valid in a C function identifier.
For any given cname, all declarations, regardless of scope, *must* have exactly
the same type signature (ie return type, number and types of all arguments).
Only 1 extern declaration (import or export) is permitted in any given scope.
More specifically, for an "import", the import must be the sole declaration of
fname in the given scope. For an "export", the function must be declared in the
scope where the "export" occurs and there must be only one "export" in that scope.
Argument names and default values are permitted to differ between "import externs"
declared at different scopes *as long as* the type compatibility constraints are met.
For exported functions, the exported function must be declared in the same scope
that contains the "export extern" declaration.
Note that DPI functions declared this way can be invoked by hierarchical reference
the same as any normal SV function.
This:
a) uses consistent syntax with other similar SV 3.1 constructs
b) permits straightforward extension later to extern/exported tasks
c) permits all information needed by DPI coder to be put in the scope
where such usage occurs.
d) by permitting import/export declarations to be inside module scope,
this simplifies (permits) use of DPI inside library modules using just
normal library resolution mechanisms.
Also, having alias in both directions (SV->C, C->SV) permits independent systems to
develop naming conventions to prevent link time clashes.
e) allows for later extension of DPI to handle tasks (if such is ever necessary)
without syntax conflict with existing usage
f) permits later extension to address other interfaces (eg "import VPI function $foobar;")
without syntax conflict with existing usage
g) use of import/export is more symmetrical and was recommended by sv-ec and by
Friday's all-committees meeting
Joao
==============================================================================
Joao Geada, PhD Principal Engineer Verif Tech Group
Synopsys, Inc TEL: (508) 263-8083
344 Simarano Drive, Suite 300, FAX: (508) 263-8069
Marlboro, MA 01752, USA
==============================================================================
This archive was generated by hypermail 2b28 : Mon Mar 03 2003 - 11:31:55 PST