Subject: [sv-cc] collections in VHPI
From: Francoise Martinolle (fm@cadence.com)
Date: Wed Nov 12 2003 - 14:37:43 PST
The VHPI standard has added the concept of a collection of handles.
Collections of arbitrary handles can be created.
A collection is a very powerful concept. I extracted the relevant sections
of the VHDL standard draft. If you want to get the standard draft, you can
downloaded it from the vhdl.org/vhdlpli web site (click on Specs). The
latest pdf version version 4.0.
I also attached the UML class diagram describing the collection class.
Feel free to send any comments or questions.
1.1.1 Collection class
The vhpiKindP of a collection handle is either a vhpiAnyCollectionK or a
specialized collection of objects of the same kind, for example a
collection of drivers is vhpiDriverCollectionK. The collection class
represents a user-defined collection of VHPI objects. The collection
contains an arbitrarily sized, ordered set of VHPI objects. The collection
may be created at any time, provided, of course the desired object members
exist at the time. The purpose of the class is for the organizational
convenience of an application or model. Atomic operations are defined on
the collection class (see operations). The UML model defines a oneToMany
method to iterate over the members of the collection (vhpiMembers).
Iterating on the members of a collection handle only returns the valid handles.
1.1.1.1 Construction of a collection object
A collection object is created with vhpi_create. The first call provides a
handle to the first object to be added to the collection and returns a
handle to the collection object:
vphiHandleT myCollection;
myCollection = vhpi_create(vhpiAnyCollectionK, NULL, vhpiHandleT anyObject);
Objects may be added to the collection, one at a time, as follows:
myCollection = vhpi_create(vhpAnyCollectionK, myCollection, vhpiHandleT
anotherObject);
The return value is a handle to the modified collection object or NULL if
an error occured. The original collection object handle shall be passed as
the second parameter, the handle to the object to be added to the
collection shall be passed as the third parameter. The ordering of the
collection set corresponds to the order in which objects are added to it.
There is no restriction on when a collection may be created or when objects
may be added to an existing collection.
NOTE: As is the case for all VHPI handles, a handle to a collection does
not remain valid across process boundaries that may exist in the
architecture of a particular VHPI-compliant tool.
1.1.1.2 Collection Object Lifetime
A collection exists from the time it is created until its handle is
released. No navigation VHPI function ever returns collection handles. It
is the application/model responsibility to keep a handle to the collection
created. It is also its responsibility to release the collection handle
when it is no longer needed. Releasing the collection handle does not
release the handles the collection contains.
1.1.1.3 Referential Integrity
With respect to a collection of dynamic objects, if a handle to one of the
collection members is obtained by iterating over the vhpiMembers
relationship or accessed via vhpi_handle_by_index, it should always return
a handle that is safe to reference. It does not matter whether the handle
to the object of interest was released, this is a new handle obtained by
accessing the collection member object. Moreover, if the collection is a
collection of dynamic objects (callbacks for example), it does not matter
if the dynamic object was removed or ceased to exist, the reference to it
in the collection still exists in the same manner that a callback handle
kept by a user can be referenced even after the callback has been removed.
Another way of stating the expected behavior is that the referential
integrity of a collection transitively includes the referential integrity
of a handle to any of its underlying objects.
1.1.1.4 Operations on a collection
There is a powerful generality with a collection that is possible, but it
is being used in only one narrow context in the current VHPI specification.
VHPI operations are defined on some classes of the information model. A
VHPI operation can be applied to a class which possesses that operation,
the operation consists in modifying/accessing some of the class internal
data. Such operations are for example vhpi_put_value, vhpi_get_value,
vhpi_schedule_transaction, vhpi_register_cb… Operations operate on an
object which reference handle is passed as an argument to the VHPI
operation. It is desirable in many contexts to apply the same operation to
a set of objects by a series of identical sequential operation calls where
the reference handle changes to point to a different object. It would be a
very convenient shorthand to allow certain VHPI operations to accept a
handle to a collection. Such an operation would appear in the information
model as an operation defined on a collection, and you can think of its
definition being a "delegated" operation defined on the individual members
of the collection. There is no supported use of collections in this manner.
This is a also a mechanism that can be used when a series of operations on
separate handles must be treated as an atomic operation. A collection of
driver handles that represent the sub-element drivers of a composite
unresolved signal may be used as the reference handle with
vhpi_schedule_transaction to schedule a composite transaction. This is the
only context that is being proposed for a collection.
Property access or method navigation do not work by delegation: a common
property of the elements of a collection cannot be queried on a reference
handle of the collection.
1.1.1.5 Error Handling
An operation applied to a collection may have an error associated with one
or members of the collection. Such an operation will be recognized as a
single error which may be reflected in the return value of function as well
as be accessible with vhpi_check_error. The correctness of use of an
operation on a collection is the transitive correctness of that operation
on each member of the collection. Specific error conditions are defined
with the VHPI function that accepts a collection.
Future Considerations
---------------------
The formal information model may be extended with notation that reflects
operations on an object that may be delegated to collections of such
objects. That notation will indicate that the collection must be a
homogenous set of objects of the kind that support the operation and its
delegation. This will allow the actual C binding of the operation to
indicate that a collection handle or a object handle is allowed for this
function. The function reference may provide details of what kinds of
collections are allowed. This detail should be inferable from the formal
information model as well.
This concept of a collection may also extended to support other methods for
collection construction. For example, it may be reasonable to navigate an
association that returns the collection of drivers of a composite with a
simple call to vhpi_handle.
1.1 vhpi_create()
vhpi_create()
Synopsis:Create a vhpiProcessStmtK or a vhpiDriverK for a vhpi foreign
model or a vhpiDriverCollectionK or a vhpiAnyCollectionK
Syntax:vhpi_create(kind, refHdl, processHdl)
Type Description
Returns:vhpiHandleTA vhpiDriverK or vhpiProcessStmtK or
vhpiDriverCollection handle on success, null on failure.
Type Name Description
Arguments:vhpiClassKindTkindClass kind of the handle to be created
vhpiHandleTrefHdlHandle to a basic signal or to a foreign architecture
vhpiHandleTprocessHdlHandle to a vhpiProcessStmtK or null
Related functions:
vhpi_create () shall be used to create a vhpiDriverK of a VHDL basic signal
to drive a VHDL signal from a VHPI foreign model, or to create a
vhpiProcessStmtK within a vhpi foreign model, or to create a collection of
drivers. This function should only be called during elaboration of a
foreign model for creating drivers and processes. There is no restriction
on when creation of collections can occur.The first argument, kind,
specifies the kind of handle to be created (vhpiDriverK, vhpiProcessStmtK
or vhpiDriverCollectionK). If kind is set to vhpiDriverK, the function
creates and returns a driver for the basic signal/process pair respectively
denoted by the handles refHdl and processHdl. If kind is set to
vhpiProcessk, the function creates and returns a vhpiProcessStmtK for the
foreign architecture denoted by the handle refHdl, the last parameter is
set to null. For creation of collections, the reference handle must be null
for the first time the collection handle is created or must be the
collection handle for the subsequent calls when a driver handle is appended
to the collection. The third parameter handle can either be a driver handle
or a collection handle. The function returns a handle of the requested kind
on success and null on failure.
Example:
void create_vhpi_driver(archHdl)
vhpiHandleT archHdl; /* handle to a foreign architecture */
{
vhpiHandleT drivHdl, sigItr, sigHdl, processHdl;
vhpiHandleT arr_driv[MAX_DRIVERS];
int i = 0;
if (!vhpi_get(vhpiIsForeignP, archHdl))
return;
/* create a VHPI process */
processHdl = vhpi_create(vhpiProcessK, archHdl, NULL);
/* iterate on the signals declared in the architecture and create a
VHPI driver and process for each of them */
sigItr = vhpi_iterator(vhpiSigDecls, archHdl);
if (!sigItr) return;
while (sigHdl = vhpi_scan(sigItr)) {
drivHdl = vhpi_create(vhpiDriverK, sigHdl, processdl);
arr_driv[i] = drivHdl;
i++;
}
}
FIX code below
void create_vhpi_collection(sigHdl)
vhpiHandleT sigHdl; /* handle to a signal */
{
h = NULL;
for (;;) {
h = vhpi_create( (vhpiDriverCollectionK, h, driverH);
}
}
This archive was generated by hypermail 2b28 : Wed Nov 12 2003 - 14:40:28 PST