VHDL PLI IR number: 03 Classification: Netlist traversal and access VHDL PLI version: 0.1 Title: Creating and accessing signal drivers Summary: PLI support for the creation and access of signal drivers for scheduling value updates, registering callbacks and getting network connectivity information Related IRs: 02 Requestor Priority: Assigned Priority: Current Status: Open Date Submitted: 05/07/98 Key Words: signal, driver, process, resolved, unresolved, transaction, basic signal Related sections in the LRM: 4.3, 8.4, 9.5, 12.5 Author of Submission: Vish Raman Author's Affiliation: Synopsys Author's Phone Number: Author's Net Address: vishwa@synopsys.com Description of the problem -------------------------- PLI functionality to create and access signal drivers. The driver handles thus acquired can be used to post or query transactions, register callbacks (refer to IR02) and acquire connectivity information. Rationale --------- Signal updates can be scheduled on drivers of signals. These drivers could be the ones created during elaboration or could be created by the PLI. The users will have a handle to the drivers they create, but would have to be given mechanisms to acquire the handles for drivers created during elaboration. In the following sections drivers and handles to drivers are used interchangeably. The drivers acquired could be used to schedule signal updates or to register transaction maturity callbacks (IR02). Analysis -------- There are two cases of driver access mechanisms, one for scalar signals and the other for composite typed signals. To better understand the various situations that can exist with respect to signals, the following notation has been invented, Signals are either scalar or composite, represented by the letters S or C. A scalar signal can be resolved or unresolved. The notation S/R represents a resolved scalar signal and S/U represents an unresolved scalar signal. A composite can be resolved or unresolved. An unresolved composite can be resolved at any of it's subelement levels. In our new notation, the cases are, C/R - resolved composite C/U/R - unresolved composite resolved at the first subelement level C[/U]+/R[/x]* - unresolved composite resolved at some level down the sub element hierarchy. x stands for either U or R. If there are no elements that follow /R, then the composite is resolved at the level of it's scalar sub elements. C[/U]+ - unresolved composite, unresolved all the way down to the scalar subelements. For all composite typed signals, there exists a set of basic signals defined as follows, Basic signals correspond to the first level of resolved sub elements down the hierarchy of a composite typed signal. In the case of C[/U]+/R[/x]*, the level corresponding to /R defines the basic signals of the composite. For all composites of type C[/U]+, the basic signals correspond to the scalar sub elements, which are the leaves in the composite's sub element hierarchy. Note : Drivers will always be created at the granularity of the basic signals, according to the LRM. In the following discussion the term "sub signal" is used to refer to any slice of a composite. A sub signal could be a composite slice, thus making the definition recursive. Given a driver the following one to one relationships exist, 1. The signal that is being driven (could be a slice). 2. The process that corresponds to the driver. In addition to the above relationships, the following pieces of information can be obtained, 1. The current driving value of the driver. 2. The size, in bytes, of the driver. 3. The list of posted transactions for the driver. 4. Whether the driver is assignable or not. 5. Whether the driver is disconnected or not. Relationships that the PLI supports with respect to signals, sources, drivers and processes, 1. Signal to sources (includes signals, ports, conversion functions, resolution functions and drivers). 2. Source to it's sources. 3. Signal to drivers (PLI shortcut - a filter on sources). 4. Signal to processes. 5. Process to drivers. 6. Signal and process to driver. Given a signal and a process, a driver might exist or not. If the return value of the PLI function that takes a signal and a process as parameters to return a driver, is NULL, then no driver exists for that signal within that process. Therefore, the existence of a driver can be implicitly determined by using the return value of that function. Disconnected drivers will not be returned when traversing the list of drivers for a signal, but will be returned if the PLI users use the process to drivers relationship. A disconnected driver can be reconnected using the PLI by posting a transaction. Creation of drivers through the PLI ----------------------------------- A driver can be created only within a process, therefore the PLI will support the creation of processes. PLI processes or existing processes can be used to create drivers. For scalar signals, the PLI driver access method will return a scalar driver handle and for composite signals or slices of composites, the PLI will return one of the following, 1. A driver handle if the slice corresponds to a basic signal. 2. An error if the slice is a sub signal of a basic signal. 3. A bundle handle in all other cases. This bundle handle will contain a bundle of driver handles, with the granularity of the basic signals. a. For composites of type C[/U]+/R[/x]*, this will correspond to the first level of sub element resolution. b. For composites of type C[/U]+, this will correspond to the scalar sub elements. Creation of bundles through the PLI ----------------------------------- The PLI will support, as an enhanced feature, the ability to compose bundles of drivers. These bundles can be used exactly like driver handles to get the current driving value and schedule transactions, but at a lower level of granularity than possible with the drivers created according to the LRM. The following points hold with respect to bundles, 1. Bundles can be created only to a particular signal or sub signal. 2. A bundle cannot contain drivers that drive the same slice of a signal. The drivers have to drive non-overlapping slices of the signal. 3. A bundle can consist of a set of drivers that drive non-contiguous sub elements of the same composite. The vhpiHandleMany function can be used to compose a bundle. The list of drivers that form the bundle should be passed to the function. The users can intersperse drivers with bundles to create larger bundles. A bundle class can be considered as an extension over the aggregate class. Besides providing the methods available off of the aggregate class, a bundle class also contains some of the methods that are provided by the driver class. The types of signals, using the notation described above, and the properties that map onto them are enumerated below. Case of scalar signals ---------------------- S/U: In this case, there can be utmost one process with a driver. The following points hold with respect to these signals, 1. The signal to drivers relationship will return an iterator with utmost one driver. 2. The signal to process list iteration will return an iteration list with utmost one process. 3. The PLI create function can be used to create utmost one driver, if one does not already exist, within a PLI process or an existing process. 4. Bundles do not apply. S/R: In this case, there can be multiple processes with one driver per process. 1. The drivers list will be a list of all scalar drivers. 2. The processes list will contain all the driving processes. 3. The users can create as many drivers as needed with one driver created per process. 4. Bundles do not apply. Case of composite signals ------------------------- C/R: This represents a signal resolved at the composite level. In this case there can be multiple processes driving the signal, with the requirement that all drivers drive the signal in it's entirety. This is because the signal is resolved at the level of the whole composite. 1. An iteration on the drivers will return a list of all drivers, one per driving process. It is an error to ask for the drivers of any of the sub elements (sub signals) of this type of composite. 2. The processes list will be the list of all driving processes. 3. The PLI create function can be used to create drivers, such that each driver drives the entire signal. These drivers can be created within PLI processes or other processes in the design. Drivers cannot be created for any of the sub elements of this signal. 4. Bundles do not apply. C[/U]+/R[/x]*: This represents an unresolved composite signal, which is resolved at some level down the hierarchy. The drivers created for composites of this type will be at the level of the first level of resolution, which is the same as the level of the basic signals. The maximum granularity of driver access that is permitted here is at this level of resolution and not any deeper. 1. The users cannot traverse the list of drivers for any of the sub signals of the composite that are larger than the basic signals. The users will have to iterate over the sub elements of the composite to reach the basic signals before requesting drivers. The drivers thus obtained can be used to compose bundles (discussed above). 2. The processes list will be the list of all driving processes, including PLI processes. 3. The users can create drivers for any sub element or contiguous group of sub elements as long as they are not sub signals of basic signals. 4. Bundles can be created using drivers that are obtained using the driver access mechanisms, within the purview of the rules that govern bundling. C[/U]+: This is an unresolved composite signal which is unresolved all the way down to the scalar sub elements. In this case, there can be utmost one driver per scalar sub element. Composites of this type have driver implementations that vary accross simulators from different vendors as vendors create optimized drivers based on the design. It is believed that a portable solution can be achieved only if there are scalar drivers corresponding to the scalar sub elements of signals of this type. To enable this, the following mechanisms are proposed, 1. Identification of particular composite signals that would need scalar access by using an attribute. This attribute can be used for a particular signal or within a scope (architecture body, entity, subprogram, block). It can be applied to the entire scope using the "ALL" or "OTHERS" qualifier (refer to LRM 5.1 page 72). 2. The use of a declarative PLI function at elaboration time which can be used to declare certain signals as scalarized. This function called vhpiSetScalared, will ensure that scalar drivers are created. This function is provided to facilitate model developers, as models would require scalarization of drivers for portability, and would be able to identify signals to scalarize only during elaboration. The following holds with respect to scalarized signals of this composite type, 1. The iteration on drivers for the whole composite or any of it's sub elements other than the scalar sub elements, will be an error. 2. The iteration on processes will return the driving processes. 3. The PLI create function can be used to create drivers only to sections of the signal that do not already have drivers created. Further, the users can create utmost one driver for a slice. 4. Bundling in this case can be done at all levels of the sub element hierarchy as the drivers that are accessible are the scalar sub element drivers. The following holds with respect to non-scalarized signals of this composite type. 1. The iteration on drivers will return an error. 2. The iteration on processes will return the driving processes. 3. The PLI create function can be used to create drivers. The use of this function will automatically scalarize the signal and the return value of this function will be the same as in the case of scalarized composites. 4. No bundling, except for PLI created drivers due to automatic scalarization (point 3. above). The following table illustrates the PLI functions that will be available within various domains of driver access mapped with respect to the phases during simulation. PLI models PLI subprogrmas PLI processes PLI apps VHDL shell VHDL shell phase ----------------------------------------------------------------------------- compile? attribute attribute scalared for signal only by scalared for parameters of any mode modifications declared to VHDL signals source ----------------------------------------------------------------------------- bootstrap No network related information access/modification ----------------------------------------------------------------------------- elaborate create_process conc proc call create_process no modifs to create_driver create_driver create_driver elaborated set scalared set scalared set scalared model ----------------------------------------------------------------------------- initialize The following functionality applies accross the board ---------- ----------------------------------------------------- simulation is scalared?, is assignable?, current driving value, list of posted transactions, signal to drivers, signal to processes, processes to drivers, post transaction (potential reconnection of disconnected drivers), alter driving value, register callback on driving value change, disconnect driver. ----------------------------------------------------------------------------- dynamic elab? Will not be supported for the first version of the PLI (?) ----------------------------------------------------------------------------- terminate TBD ----------------------------------------------------------------------------- exceptions TBD (linked to error handling) ----------------------------------------------------------------------------- The following points hold with respect to the table and the discussion so far, 1. PLI foreign models can create drivers after creating an associated process. The process handle would have to be passed to the PLI create driver function. They can therefore create multiple drivers with multiple processes for all resolved signals or a single driver with a single process for unresolved signals. The create driver function will return a scalar driver or a bundle of drivers. 2. Foreign subprograms which are concurrent statements will have an associated implicit process. This process handle will be passed to the subprograms and they can create at most one driver using that process handle for a particular slice. Subprograms that are not cuncurrent will have an enveloping process, the handle to which will be passed to enable driver creation. PLI functions cannot create drivers. 3. PLI processes would be similar to subprograms wherein the PLI users can create at most one driver using the passed process handle for a particular signal or slice. As the design would have been partially elaborated at this stage none of the PLI functions, other than create driver and create process, will be available. Further, the signal for which drivers have to be created should be passed as a parameter to the PLI process, ensuring that none of the other signals in the design can be accessed for driver creation purposes. Only scheduling is permitted for out-of-scope signals. 4. PLI applications have only one mechanism to create drivers and that is by creating a dummy PLI subprogram or process or model, in which case points 1, 2 and 3 above, hold. 5. It is not mandatory for the PLI to support dynamic elaboration. 6. Read access to drivers implies the ability to read the current driving value of the driver and also the list of transactions that have been posted to that driver. Write access implies the ability to schedule transactions and also modify the current driving values of the drivers. Proposed solution ----------------- The following are the proposed pieces of functionality to be provided by the PLI. One to many relationships: 1. Signal to sources (includes signals, ports, conversion functions, resolution functions and drivers). 2. Source to it's sources. 3. The list of drivers for a signal (PLI shortcut - a filter on sources). 4. The list of driving processes for a signal. 5. The list of drivers within a process. 6. The list of fields within a record. 7. The list of elements of an array. 8. The list of posted transactions for a driver. 9. The list of drivers within a bundle. One to one relationships: 1. The signal being driven by a driver. 2. The process corresponding to a driver. 3. The subtype of a signal. Many to many relationships: 1. The driver corresponding to a process, signal tuple. The signal could be a slice. Object properties access/modification: 1. The size of a driver. 2. Whether a driver is assignable. 3. Whether a driver is disconnected. 4. Whether a signal is scalared. 5. The current driving value of a driver. 6. Change the current driving value of a driver. 7. Set the scalared attribute for a signal (only during elaboration). 8. Post a transaction on a driver. 9. Disconnect a driver. Creation calls: 1. Create process (only during elaboration). 2. Create driver/bundle (only during elaboration). 3. Composition of a bundle using a set of driver/bundle handles. This could also fall under the many to many relationships. The PLI should provide a call to register a callback against the maturity of a transaction for a driver. Issues ------ 1. The specification of values has to be worked out. 2. The error handling mechanism would have to be worked out, because they have a bearing on what we return on failure for functions that are covered by this proposal. 3. What would be the list of sources for a conversion or resolution function? 4. What would be returned when traversing the drivers list of a process for composites which are completely unresolved or resolved at some sub element level? Would we return drivers at the first resolved level or at the scalar sub element level depending on the type of composite? What about non-scalarized unresolved composites? 5. Should an iteration on the drivers of a composite resolved down the hierarchy be an error? Or could we return bundles here... probably too confusing, but worth a glance. 6. As part of driver creation through the PLI, should we return a driver for all cases and encapsulate bundling internally, or should we return drivers or bundles based on the case in point? Errors ------ 1. Creating a driver for an unresolved signal that already has a driver. 2. Passing a NULL signal handle for creating a driver. 3. Creating a driver without a process. 4. Attempt to create a driver for a buffer mode port. 5. Other errors that relate to the types of signals as mentioned in the appropriate sections above. Recommendation -------------- None. Recommendation for Future Revisions of Standard ----------------------------------------------- None. Special handling or differences with VHDL'87: --------------------------------------------- None.