Subject: [sv-cc] Comments on proposed VPI for SystemVerilog
From: Swapnajit Mittra (mittra@juno.com)
Date: Wed Nov 12 2003 - 21:03:43 PST
Fwding email from Stuart Suthreland.
-- Swapnajit Mittra Project VeriPage ::: http://www.angelfire.com/ca/verilog---------- Forwarded Message ---------- >From owner-sv-cc Wed Nov 12 20:32:23 2003 Received: from mail.larkspurhotels.com (gw.larkspurhotels.com [12.149.151.130] (may be forged)) by server.eda.org (8.12.0.Beta7/8.12.0.Beta7) with ESMTP id hAD4WJ8h016694 for <sv-cc@eda.org>; Wed, 12 Nov 2003 20:32:22 -0800 (PST) Received: from WILE-E-COYOTE.sutherland-hdl.com ([12.146.131.193]) by mail.larkspurhotels.com with Microsoft SMTPSVC(5.0.2195.6713); Wed, 12 Nov 2003 20:28:36 -0800 Message-Id: <5.1.0.14.2.20031112201442.027c7188@mail.sutherland-hdl.com> X-Sender: stuart@mail.sutherland-hdl.com X-Mailer: QUALCOMM Windows Eudora Version 5.1 Date: Wed, 12 Nov 2003 20:29:30 -0800 To: sv-cc@server.eda.org From: Stuart Sutherland <stuart@sutherland-hdl.com> Subject: Comments on proposed VPI for SystemVerilog Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii"; format=flowed X-OriginalArrivalTime: 13 Nov 2003 04:28:36.0594 (UTC) FILETIME=[9AF15520:01C3A99E]
All,
I was asked to review the proposed VPI extensions to support SystemVerilog, using a draft dated "September 2003".
I am very impressed at how well all the new SystemVerilog objects have been integrated into the VPI standard. Great job!
I only did a cursory review due to time limitations, but noticed a number of things in the proposed VPI diagrams. I was primarily looking for readability and consistency. I did not have time to look for how well the access methods in the diagram compare to the descriptions of the objects in the SV 3.1 LRM. Some of my notes are errors, some are questions, and some are trivial nits.
I hope my comments are useful...
Stu
-------------------------------- Interface/Module/Program diagram: -------------------------------- - IMPORTANT: There are too many differences between modules, interfaces and programs to try to lump them into one diagram. For example, the diagram as shown says a program can contain instances of program arrays, programs, modules, interfaces, always procedural blocks, etc. There should be a separate, unique diagram for module, interface and program.
- The access method constant from program array to Instances is not readable on my hard copy.
- Should the object "refobj" should be "ref obj"? Elsewhere in the document, the constant used for this object is "vpiRefObj". The rule in the 1364 LRM is that each word of the object name has a leading capital letter in the constant name. So "refobj" should be represented by "vpiRefobj", not "vpiRefObj".
- Modules, interfaces and programs can be declared with a lifetime of automatic or static. Should there be a "lifetime" property? Since this declaration only affects tasks and functions within the module, interface or program, it may not be necessary to have the property on this diagram.
- The "concurrent assert" object should be "concurrent assertions" (per the diagram with the definition of this object) and should be in a dotted enclosure.
- The access method from "concurrent assert" back to instances is too much clutter for this diagram. It should only be shown on the "concurrent assertions" diagram.
- Note 3 mentions a `file directive. This was an errata in the 1364-2001 LRM that has been corrected (there is no such directive).
- IMPORTANT: Note 5 says "...to get all top-level modules specified in the design, the user must do "vipIterate(vpiModuleRoot_handle)". First, the function is vpi_iterate(), not vipIterate. More importantly, Note 1 (from the 1364 standard) says "Top-level modules shall be accessed using vpi_iterate with a NULL reference object". These two notes conflict with each other, and note 5 is not backward compatible with 1364. I suggest deleting note 5, and changing Note 1 to: - vpi_handle(vpiRoot) returns a handle to $root, which represents the top-level of a SystemVerilog hierarchy. If there is no $root (e.g. in a Verilog 1364-2001 hierarchy, then vpi_handle(vpiRoot) shall return NULL. In either case, passing the return from vpi_handle(vpiRoot) to vpi_iterate() shall return handles to all top-level Verilog modules.
-------------------------------- Modport diagram: -------------------------------- - The object "mpport" should be "modport port"
-------------------------------- Task TF Declaration diagram: -------------------------------- - The object "TF decl" should be "tf decl" (all object names are in lower case in the VPI diagrams).
- The object name and title of this section are too easily confused with the existing "Task Function Declaration" diagram. I suggest renaming the object to "modport task func" (with the type constant "vpiModportTaskFunc".
- There should not be both a one-to-one and a one-to-many relationship from "tf decl" to "task" and to "function". All that is needed is a one-to-many relationship to "task func". All access types except vpiForkJoin will only find one object in the one-to-many iteration, but that is fine.
- Change the NOTE to read: "vpi_iterate(vpiTaskFunc) can return more than one task/function declaration for modport tasks/functions with an access type of vpiForkJoin, because the task or function can be imported from multiple module instances."
-------------------------------- Mpport diagram: -------------------------------- - The section name should be "Modport ports" (something more descriptive than "Mpport"
- The object "ModPortPort" should be "modport port" (all object names are in lower case in the VPI diagrams).
- The object "expr/refobj" should be split to two objects "expr" in a dotted enclosure and "ref obj" in a solid enclosure, with both objects grouped into an unnamed dotted enclosure.
- Note 1, "HighComm" should be "vpiHighConn".
- Note 1, Change "...in the interface (type expr)" to "...in the interface, and shall be an expr object".
- Note 2, "HighComm" should be "vpiHighConn".
- Note 2, Change "...will be a RefObj of type vpiModPort" to "...shall be a ref obj object of type vpiModPort".
- Note 3, Change "...should be vpiUndefined" to "...shall be vpiUndefined".
-------------------------------- Ports diagram: -------------------------------- - The object "expr/refobj" should be split to two objects, "expr" in a dotted enclosure, and "ref obj" in a solid enclosure, with both objects grouped into an unnamed dotted enclosure.
- Note 1 says "...depends on the formal site, not on the actual". What does this mean? Are the terms "formal site" and "actual" defined somewhere?
- Note 2: change "vpi_get/put delays..." to "vpi_get_delays() and vpi_put_delays()...".
- Note 5: "vpiMpPort" should be "vpiModportPort".
-------------------------------- Ports diagram: -------------------------------- - Change the object name "refobj" to "ref obj" (to match the constant vpiRefObj).
- Expand the enclosure with "interface modport net/reg/variable" out to an unnamed dotted enclosure with "interface", "modport", "net" (or should it be "nets"?), "reg" (or should it be "regs"?) and "variables". Use the appropriate solid or dotted enclosure for each object.
- Note 1: Can named events also be passed through ref ports? I know named events can now be passed to tasks, but I'm not sure if they can be passed through ref ports.
- Examples, 2nd paragraph says "...have a pointer to the original object". Is it a pointer or a handle?
- Examples, change the line "childi1 i1 (i)" to "child1 i1 (i)" (child1 is spelled wrong).
- Examples, the comments for port i1 says: "vpiHighConn = vpiRefObj where vpiRefObjType = vpiInterface But the comments for port c_1 says: "vpiHighConn is a RefObj where full type is vpiInterface First, the way these comments are worded should be consistent. Second, why is the property vpiRefObjType in one case, and full type in the other?
-------------------------------- Variable diagram (first occurrence of this title) -------------------------------- - What is the "bit" at the bottom of the named enclosure? Is it a second name for the same enclosure? Is an object? It makes no sense to me.
- What are the strange access methods to the left of the variables enclosure labeled "vpiParent" and "vpiBit"? There is no reference object for these methods.
- The object "char var" should be "byte var"
- The second object "real var" should be "shortreal var"
- The Verilog "integer" data type is not listed.
- The objects "struct var", union var, "enum var" and "class var" are in bold, indicating this is the full definition of these objects. Is that the intent?
- The object "variable driver" should be in a dotted enclosure (two places).
- The object "variable load" should be in a dotted enclosure (two places).
- The properties "vpiMember", "vpiPacArray", "vpiMultiPacArray", and "vpiMultiArray" do not specify a data type. Are the int, bool, or what?
- Should user-defined type variables be included in the variable class?
- IMPORTANT: The types "logic" and "bit" should be grouped with "reg", not variables. "logic" is a synonym for "reg", and has the exact same functionality. Only "bit", "logic" and "reg" can be packed arrays (and nets, of course, but that is a different diagram). All the other data types in the variable class can only have unpacked arrays.
- Note 11: change "vpiSizeChange will be ..." to "vpiSizeChange shall be..."
-------------------------------- Variable diagram (second occurrence of this title) -------------------------------- - The "variables" object should be in a dotted enclosure
- Note 1: change "vpiDrivers/Loads...will include..." to "vpiDrivers and vpiLoads...include..."
- Note 2: change "vpiDrivers/Loads for any variable array should include the following: Driver/Load for the whole array" to "vpiDrivers and vpiLoads for a variable array include drivers or loads for the whole array".
-------------------------------- Instance arrays diagram -------------------------------- - Are interface arrays also possible?
- It is not possible to tell of the method vpiParamAssign is for the whole "instance array" enclosure or just the "module array" object.
-------------------------------- Scope diagram -------------------------------- - The scope enclosure should include "root" (which may be changing names to "local root" or "unit", based proposed changes to $root by the BC committee)
-------------------------------- IO declaration diagram -------------------------------- - The vpiExpr method is using vpiExpr differently than all other diagrams. Either there should be a special method constant to access this unnamed group, or it should just use the "expr" object.
- NOTE: Change "vpiDirection returns ref..." to "vpiDirection returns vpiRef...".
-------------------------------- Clocking domain diagram -------------------------------- - The "expr" object should be in a dotted enclosure (4 places).
- The "vpiExpr" object should be "expr".
- Are the "direction" and "name" objects supposed to be objects, or are they properties? If objects, I could not find the diagrams that define them.
-------------------------------- Clocking domain diagram -------------------------------- - The "NULL" object should be a small, unlabeled circle.
- The property label "useDefn" should be "user defined".
- The object "task/function" should be "task func".
- Is the relationship from "class defn" to "instances" one-to-one or one-to-many?
- The method tag "vpiVariable" going to the object "variable" should be deleted. It is the same name as the object, and therefore does not need a tag.
-------------------------------- Constraint diagram -------------------------------- - Is the relationship from "constraint" to "instances" one-to-one or one-to-many?
- There should be a one-to-one relationship from "constraint ordering", "constraint dist" and "constraint expr" back to "constraint". This is per the diagrams for "constraint ordering" and "constraint dist". The diagram for "constraint expr" does not show if it is possible to get back to "constraint".
- The "scope" object should be in a dotted enclosure
- The "constraint expr" object should be in a dotted enclosure.
- The "expr" object should be in a dotted enclosure
- The access method tags "vpiExpr" and "vpiDistItem" coming from "constraint dist" object should be deleted. They are accessing objects that are the same name as the method.
-------------------------------- Variable diagram (third occurrence of this title) -------------------------------- - Why isn't this diagram part of the "variables" diagram?
- The "class" object should be in bold text
- The "variables" object should be in a dotted enclosure.
- The "expr" object should be in a dotted enclosure
- Could not find the object diagram that defines the "method" object.
- Note 1: Change "vpiWaiting/Process iterator..." to "vpiWaiting and vpiProcess iterators...".
- Note 1, second bullet: Change "The assumption is..." to definitive wording, using "shall, "shall not" or "can".
Note 2: Change "...should return..." to "...shall return...".
Note 4: Change "vpiActualDefn returns the ClassDefn the handle object..." to "vpiActualDefn returns the ClassDefn that the handle object...".
Note 5: Change "vpiClassDefn/vpiActualDefn both should return null..." to "vpiClassDefn and vpiActualDefn shall return NULL..."
-------------------------------- Structure/Union diagram -------------------------------- - The "variables" object class is already defined in another diagram. This diagram should be merged with the diagram, or the "variables" class enclosure should be deleted from this diagram.
- The "structure/union" object should be two objects, "structure" and "union".
- Are these "structure/union" objects supposed to be the same as the "struct var" and "union var" objects defined in the variables diagram (first occurrence)?
- The "variables" object should be in a dotted enclosure
-------------------------------- Enum, Enum Constant diagram -------------------------------- - The "variables" object class is already defined in another diagram. This diagram should be merged with the diagram, or the "variables" class enclosure should be deleted from this diagram.
- Is this "enum" object supposed to be the same as the "enum var" object defined in the variables diagram (first occurrence)?
-------------------------------- vpiNamedEvent diagram -------------------------------- - The title for this section should be "Named events".
NOTE: Change the first person "we" and weak "assume" to more formal, standard-like wording (use "shall", "shall not" or "can").
-------------------------------- Task function declaration diagram -------------------------------- - The "variables" object should be in a dotted enclosure
- Can the "vpiMethod" constant be used as a property? There is a "method" object that would have a "vpiMethod" type constant in the Variables diagram (third occurrence).
- Note 2 has several typos: - "vpiInterfaceTask/vpiInterfaceFunction" should be in bold. - "...will be true if task/function..." should be "...shall be true if the task or function...". - "...inside and interface..." should be "...inside an interface...". - "...modport off an interface" should be "...modport of an interface".
Note 3: Change "...vpi_handle(vpiReturn/Function_handle should..." to "...vpi_handle(vpiReturn, function_handle) shall...".
Note 3: Change "...of that UDT" to "...of that user-defined type".
Note 3: I do not like this concept of the VPI returning a "dummy variable handle"! There must be a better way to handle this. The 1364 VPI standard already says that a function contains an implicit variable the same name as the function. Can this implicit variable be used instead?
-------------------------------- Alias stmt diagram -------------------------------- - Change the section title to "Alias statement".
- Is the relationship from "constraint" to "instances" one-to-one or one-to-many?
- The access methods "vpiLHS" and "vpiRHS" should be "vpiLhs" and "vpiRhs", respectively.
- How is the following declaration handled by this diagram? alias a = b = c = d; What is the vpiLhs? What is the vpiRhs?
-------------------------------- Frames diagram -------------------------------- - Why is the "frame" object in an unnamed dotted enclosure? It is not grouped with any other objects.
- The "scope" object should be in a dotted enclosure.
- The "variables" object should be in a dotted enclosure.
- Can a frame also have a localparam or specparam?
- Note 1: Change "...should be..." to "...shall be...".
- Note 1: Will the cbEndOfFrame callback occur before or after the destruction of any storage and/or handles in the frame?
- Note 2: "Please note that..." is not professional, standards-like wording.
- Note 2: This change in access method from the 1364 standard is not backward compatible. BUT. the 1364 committee is making other changes to frames that are not backward compatible, based on the fact that no simulators have implemented frames. Accellera should as the 1364 committee to make this change to 1364 now, so as to avoid possible future compatibility issues.
-------------------------------- Threads diagram -------------------------------- - Why is the "thread" object in an unnamed dotted enclosure? It is not grouped with any other objects.
- The "stmt" object should be in a dotted enclosure.
- The "NULL" object should be a small, unnamed circle.
- NOTES: "Change "...should be..." to "...shall be..."
- NOTES: Will the cbEndOfThread callback occur before or after the destruction of any storage and/or handles in the thread?
-------------------------------- Concurrent assertions diagram -------------------------------- - What are the "(or null) comments under several of the objects? If these are notes, then they should be listed in the notes section, not in the diagram.
- The note "All objects have the property int: vpiType" should be deleted. This is already stated in the 1364 VPI standard and applies to all VPI objects.
- The "property spec" object property "compliment" uses the constant "vpiNot". So does the "property expr" object property "compliment consequent". "Not" is a keyword, so this constant will be used as a type constant. Is there a conflict with using this constant as a property also?
- The properties "implication" and "delayed implication" both show the operator "|=>". Is the same token used in both places?
- The "property inst" object has a one-to-many relationship to an "arguments" object. I could not find a diagram that defines "arguments".
- The "formal list item" object has a one-to-one relationship to an "identifier" object. I could not find a diagram that defines "identifier".
- The "formal list item" object has a one-to-one relationship to an "event expression" object. I could not find a diagram that defines "event expression". The object is in a solid enclosure in this diagram, but it is in a dotted enclosure in the "actual arg expr" object diagram that immediately follows. Which is it?
- The note below the "sequence expr" named class should say "NOTE, the vpiSeqOpType is one of...". The operators listed in this note should use the constant names for the operators.
-------------------------------- instances diagram -------------------------------- - The "task/func" object should be "task func", and should be in a dotted enclosure.
- The "variables" object should be in a dotted enclosure.
- The "primitive" object should be in a dotted enclosure.
- The "stmt" object should be in a dotted enclosure.
- The "concurrent assertions" object should be in a dotted enclosure.
-------------------------------- immediate assert diagram -------------------------------- - What are the "(or null) comments under several of the objects? If these are notes, then they should be listed in the notes section, not in the diagram.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Stuart Sutherland Sutherland HDL Inc. stuart@sutherland-hdl.com 22805 SW 92nd Place phone: 503-692-0898 Tualatin, OR 97062
Sutherland HDL, Inc. -- Training Engineers to be Verilog, SystemVerilog and VHDL Wizards! www.sutherland-hdl.com ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
________________________________________________________________ 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 : Wed Nov 12 2003 - 21:06:29 PST