Subject: [sv-cc] Proposal for Disables and DPI interaction
From: Warmke, Doug (doug_warmke@mentorg.com)
Date: Fri Oct 17 2003 - 23:51:26 PDT
Joao,
My compliments on an excellent write-up of the DPI
disable problem and its 3 possible solution spaces.
All,
I would like to formalize a proposal for handling disables.
This will apply both to the future (hopefully with dpi tasks)
and the past (dpi functions, via protocol item 1)).
The "protocol solution" that Michael and I advocate has the
advantage that it is the most functionally correct and robust
of the three possible solution approaches. Also, it is the
solution that provides behavior most like native SV tf's.
Here is the protocol I am proposing:
1) It is illegal for an exported SV function to return
to the C side via a disable. If code executed within
the SV function executes a disable, it is a fatal error.
2) All DPI tasks (both import and export) correspond to C
functions with int return values. When a task returns
due to a disable event, it must return a 1. When a task
returns normally, it must return a 0.
3) It is an error for a C-side DPI import task to call any
further exported SV tasks or functions after it has been
notified of a disable via the return value of an exported task.
4) Items 2) and 3) are mandatory behavior for C-side DPI
imported tasks. It is the responsibility of the DPI
programmer to implement the correct behavior.
5) SystemVerilog simulators must detect non-compliant behavior
and issue a fatal error in such cases.
6) SystemVerilog simulators must cause DPI exported tasks to
exhibit the behavior in 2) under all circumstances.
7) During disable processing, it is acceptable for C-side DPI
imported tasks to call VPI and PLI code during cleanup
operations (e.g. to free allocated handles).
Observations on three disable targets of interest:
i) If an exported SV task is itself the target of a disable,
it returns a normal return value of 0 to the C side.
The C side can't even tell that the SV task was disabled.
ii) If an imported SV task is itself the target of a disable,
the imported task must abide by rules 2) and 3) above.
Rule 2) is in effect so that the simulator can ascertain
positive protocol compliance by the DPI import task.
iii) If the target of the disable is a SV task or block higher
up the call chain, the DPI import task must abide by rules
2) and 3) above.
The Downsides of the protocol solution are as follows.
Each has a Remedy that is described.
D1) Users may forget to check return values of exported tasks,
and may not follow the protocol.
R1) Protocol item 5) ensures that this cannot happen.
D2) User code will have more overhead.
R2) If the DPI C-side code is complex, it is already verbose.
If it's simple, and no disables are ever expected,
then DPI import tasks can ignore return values from
calls to export tasks and simply always return 0.
Note: This is basically like Joao's solution I,
i.e. making disables illegal. If the user returns a 0
during a disable propagation, the disable will be
rendered illegal and a fatal error will occur.
In a nutshell, the protocol solution provides the most robustness
and flexibility to users. Users can choose to stay simple and
ignore the protocol. This will work in most cases. In cases
when it won't work, a fatal simulation error is guaranteed.
Users get full control over resource cleanup as well.
Here is an example of an imported task that follows protocol
and has interesting cleanup properties:
#include "complexclass.h"
#include "svdpi.h"
// Prototype for SV exported task
extern "C"
int myExportedTask(int, int*);
// Imported task implementation
extern "C"
int myImportedTask(int theInput, int* theOutput)
{
ComplexClassT cc; // Allocates file handles, memory, the works...
// Initialize output to default value in case of disable
*theOutput = -1;
int someThing;
if (myExportedTask(theInput, &someThing) == 1)
return 1;
*theOutput = cc.processThing(theThing);
return 0;
}
Note that the same class implemented without the protocol
(i.e. assuming that a disable can never happen) is only two
lines shorter. (The two "return" statements would be gone).
Thanks and regards,
Doug
> -----Original Message-----
> From: Swapnajit Mittra [mailto:mittra@juno.com]
> Sent: Friday, October 17, 2003 1:55 PM
> To: sv-cc@eda.org
> Subject: Re: [sv-cc] Disables and DPI interaction
>
>
>
>
> I am assigning an issue number 1.1 to track this better.
>
> --
> Swapnajit Mittra
> Project VeriPage ::: http://www.angelfire.com/ca/verilog
>
> -- "Joao Geada" <Joao.Geada@synopsys.com> wrote:
> So as to summarize the various points people have made so far:
>
> 1- the issue arises whenever some SV code "X" invokes a C
> function/task "Y"
> which then invokes an exported SV function/task "Z" which,
> through one some
> means or another causes "X" to be disabled.
>
> As an alternate way of stating the same thing, the issue
> arises whenever a
> SV call chain containing DPI calls is disabled.
>
> 2- this is not a new issue: the problem exists already in SV 3.1
> (Y and Z are constrained to be functions, and Z disables X)
>
> 3- this was not an issue in Verilog 2001, as up to SV 3.1 C
> code could never
> give control back to Verilog code without returing. Thus
> it was not possible
> to be in a state where a callchain could be disabled *and*
> contained C functions
> in the call chain (BECAUSE the only means to disable are
> the disable stmts
> in Verilog itself)
>
> 4- the problem is simply to figure out how to "disable" the C
> portion of the call
> stack, which has two primary components:
> a) unwinding the C stack back to its SystemVerilog root
> b) providing a mechanism to enable C code to cleanup
> any resources
> it possessed in that call stack
>
>
> Disable usage notes:
> In Verilog, disables were primarily used to effect exception
> control jumps.
> (note: there were other uses of disable, but such uses were rarer)
> In SV 3.1 that purpose of disable is largely superceded by
> the provision of
> additional control constructs (break, continue, return, etc);
> However, due to all the testbench process control constructs
> it is possible
> that disables will be used to control "transactions" within
> the testbench.
>
>
> In terms of purely high level terms, the solution space is
> quite constrained:
>
> I) we make this an unsupported feature. ie causing the
> disable of a callstack
> containing C tasks/functions is an error
> II) we define some protocol such that users that must
> implement and so cause
> items 4a and 4b above to occur
> It would be an error to disable a C task/function that
> did not implement
> the protocol
> III) we automatically cause 4a to occur and provide some
> means to inform the user
> code that this unwinding has occurred. Users are not
> required to do 3b
> unless their code has consumed non-stack resources that
> must be released
> or finalized
>
> Doug's and Michael's proposals are all variants on II, though
> neither addresses
> the behavior when both Y and Z are purely functions and not
> tasks (as in such
> a case return codes cannot be used)
>
> Personally I have concerns on relying on or trusting users to
> accomplish 4a,
> and I believe this can be effected completely automatically
> within the simulator,
> by harnessing the internal, simulator specific knowledge of
> how multiple C
> functions are permitted to be "in progress" at a single time;
> note that this is
> itself a side-effect of the task donation, regardless of the
> technology used to
> implement the mechanism (doesn't matter if using threads,
> co-routines, continuations
> or any other alternative: the simulator *must* have a
> mechanism to suspend and
> resume the execution of arbitrary C code.
> However, solving 4a still, clearly, leaves the 4b issue.
> During the meeting
> I suggested a "protocol" mechanism to address 4b using a
> callback functions.
>
> OK, I think this is a full summary. On to the discussions and
> proposals ;-)
>
> Joao
> ==============================================================
> ================
> Joao Geada, PhD Principal Engineer
> Verif Tech Group
> Synopsys, Inc
> TEL: (508) 263-8083
> 377 Simarano Drive, Suite 300,
> FAX: (508) 263-8069
> Marlboro, MA 01752, USA
> ==============================================================
> ================
>
> ________________________________________________________________
> The best thing to hit the internet in years - Juno SpeedBand!
> Surf the web up to FIVE TIMES FASTER!
> Only $14.95/ month - visit www.juno.com to sign up today!
>
This archive was generated by hypermail 2b28 : Fri Oct 17 2003 - 23:53:14 PDT