[sv-cc] SV-CC: DPI Issues

Hi, 
 
There are three inter-related issues that have come up in the DPI API's
provided for 
putting and getting user data. Since these are inter-related I am
explaining all the
three in this mail below. 
 
The first two issues are related to explanation of svPutUserData and
svGetUserData in
section J.3, of Annex J (Include file svdpi.h). 
 
The third issue is a new requirement on providing a mechanism for
deleting a previously
created key on a specific scope.
 
Please do provide inputs on these issues, and I will appropriately
create a Mantis 
item.
 
Regards,
 
--Amit
 
P.S.: DPI Issues
 
Issue 1:
SystemVerilog standard version: P1800/D8, February 16, 2009, Section
J.3, Source code,
Page 1169(1203 of 1258), gives the following explanation for
svPutUserData:
 
 
/*
* Store an arbitrary user data pointer for later retrieval by
svGetUserData()
* The userKey is generated by the user. It must be guaranteed by the
user to
* be unique from all other userKey's for all unique data storage
requirements
* It is recommended that the address of static functions or variables in
the
* user's C code be used as the userKey.
* It is illegal to pass in NULL values for either the scope or userData
* arguments. It is also an error to call svPutUserData() with an invalid
* svScope. This function returns -1 for all error cases, 0 upon success.
It is
* suggested that userData values of 0 (NULL) not be used as otherwise it
can
* be impossible to discern error status returns when calling
svGetUserData()
*/
 
 
Issue:
There is an obvious contradiction in the paragraph explaining
svPutUserData. First it states that it is illegal to pass in NULL values
for either the scope of userData arguments. Then it is "suggested" that
userData value of 0 not be used. 
 
Proposed Resolution:
The explanation for svPutUserData needs to be corrected.The last
sentence can be modified as follows:
    From:
    "It is suggested that userData values of 0 (NULL) not be used as
otherwise it can
     be impossible to discern error status returns when calling
svGetUserData()"
 
  To:
  "The useData values of 0 (NULL) are illegal as otherwise it can be
impossible to discern error status
   return values when calling svGetUserData()".
 
Issue 2:
SystemVerilog standard version: P1800/D8, February 16, 2009, Section
J.3, Source code,
Page 1169(1203 of 1258), gives the following explanation for
svPutUserData:
/*
* Retrieve an arbitrary user data pointer that was previously
* stored by a call to svPutUserData(). See the comment above
* svPutUserData() for an explanation of userKey, as well as
* restrictions on NULL and illegal svScope and userKey values.
* This function returns NULL for all error cases, 0 upon success.
* This function also returns NULL in the event that a prior call
* to svPutUserData() was never made.
*/
XXTERN void* svGetUserData(const svScope scope, void* userKey);
 
Issue:
Again a contradiction appears above,as the paragraph says that 
 
"This function returns NULL for all error cases, 0 upon success".
 
Proposed Resolution:
The explanation for svGetUserData needs to be corrected. Following
change is recommended
for the explanation, as it will also make it consistent with the
proposed change for svPutUserData.
The explanation should be modified as follows: 
 
   From:
   "The function returns NULL for all error cases, 0 open success."
   To:
   "The function returns NULL for all error cases, and actual userData
put using svPutUserData upon success."
 
Issue 3: A new requirement
There is a new requirement to have support for deleting a key in a given
scope. 
 
Proposed Resolution:
In my opinion, this will be handled best by introducing a new API:
  
/*
* Delete a key defined for a scope in the SystemVerilog design. It is
illegal to 
* call svDeleteUserKey with a NULL svScope or a NULL userKey. It is also
illegal
* to svDeleteUserKey with an invalid scope.
* 
* This function returns -1 for all error cases, 0 upon successful
deletion of key.
* This function will not delete(free) any userData that was set using
the userKey.
*/
   XXTERN int svDeleteUserKey(const svScope scope, void *userKey);
 
which returns 0 on successful deletion of the key. Note, the API will
not delete 
(free) any userData that was passed using svPutUserData.  It will return
a -1 for 
all error cases, including userKey not found. Having such an API will
keep clear 
semantics.
 
An alternative is to modify the semantics of svPutUserData such that if
the user provides
a NULL for userData then the userKey can be deleted. However, I think
that such overloading 
of svPutUserData will conflict with the current explanation and may
confuse users.

-- 
This message has been scanned for viruses and
dangerous content by MailScanner, and is
believed to be clean.