Empowering UPF Commands With Effective Elements Lists

Become more accurate, productive, and consistent by understanding the inherent features of UPF commands and options.


The Unified Power Format (UPF) is intended for power management, power aware verification, and low power implementation. The more we explore the inherent features of UPF commands and options, and comprehend their interrelation, the more we become accurate, productive, and consistent in developing UPF for our intended purposes.

Although the UPF is very well defined through the IEEE 1801 LRM, it is often difficult to comprehend many primitive and inherent features of individual UPF commands-options. In this article, we provide a simple approach to find inherent links between UPF commands-options through their transitive nature. We also explain how these inherent features help to foster and establish exact relationships between UPF and DUT objects in order to develop UPF for power management, implementation, and, as well, conducting power aware verification.

Effective Elements and Transitive Commands
UPF commands are, in general, transitive in nature. For any given instance included in a power domain, all child instances of that given instance are transitively included in the power domain, unless any child instance is explicitly excluded from this particular power domain or is explicitly included in the definition of another power domain.

This explicit exclusion or inclusion from the ultimate instance list is strongly and precisely defined in the UPF LRM as an effective_elements_list because it influences the construction of design objects into UPF objects. Thus, the effective elements and the transitive nature of UPF commands are related. However, none of these exclusion or inclusion element lists are actual UPF commands.

Although some commands do have explicit –transitive <TRUE | FALSE> as an option, for many other commands it is implied in the semantics; specifically, for denoting power domain extents through instances or through lists of ports to apply strategies with –elements or to exclude some part of the design with –exclude_elements. It may also be implied for model names in specifying a list of models to attributes with –models, library name to specify all models with –lib, etc.

The effective elements list captures the information of the extent of power domains and strategies written as:

List 1: LRM Denotation of Effective Elements List


This list is actually constructed from the following derivatives:

List 2: Constituent Parts of Effective Elements List

aggregate_exclude_list, and
prefilter_element_list etc.

The element_list and exclude_list are the lists that contain the elements specified by an instance of the command. The effective_element_list, aggregate_element_list, and aggregate_exclude_list are associated with the named object of the command. Here the named object can be any UPF or HDL object that has a given name; for example, module name or power domain name.

The latest version of the UPF LRM 1801-2018 also defines a new elements list, termed the resolved_element_list, based on precedence rules of resolution on how variants of options for any UPF command takes precedence for a specific or generic situation.

The resolved_element_list is actually a set (or a subset) of elements from the effective_element_list that is determined by the application of precedence rules. For example, a create_power_domain command that explicitly includes a given instance in its extent shall take precedence over the one that applies to an instance transitively (i.e., applies to an ancestor of the instance and, therefore, to all of its descendants).

A resolved_element_list will be either the effective_element_list or a subset of the effective_element_list if a given element is referenced in the effective_element_list for more than one strategy. As each element may ultimately only have one strategy applied to it, then precedence rules shall be used to determine which strategy will be applied. A resolved_element_list is associated with the named object of a command and represents the set of elements actually affected by a particular strategy.

None of these lists are UPF commands or options, but they help power aware verification and analytical tools to identify, maintain, and manipulate relevant UPF commands and options, such as:

List 3: UPF Commands Benefitting from Effective Elements List

-libs, and
-transitive etc.

For example, create_power_domain domain_name –elements <list> –exclude_elements <list> inherently defines an effective list, <effective_element_list>, which is the result of the application of –elements and ‑exclude_elements. Please note that, here, –elements {} is implicitly followed by –transitive TRUE options, although -transitive is not an explicitly defined option for the create_power_domain command. The transitive nature impacts the resultant design elements or the <effective_element_list> of a power domain through the ‑elements {} and –exclude_elements {} options.

Transitive Relationships
Let’s take a closer look at the transitive nature of design elements. The following hierarchical diagram and examples explain the UPF semantics of inherent transitive TRUE natures in design (DUT) objects to UPF object creations and mapping. Our example design has a current scope A, containing child elements B, C, and D. The child element B further branches to E and F, C branches to G and H, and D branches to I and J elements, respectively, as shown in Figure 1.

Figure 1. Understanding effective_element_list and implied transitive TRUE natures of UPF commands.

The obvious question is “What will be the <effective_elements_list> here?” Due to its transitive nature, the resultant <effective_elements_list> will be {A A/B A/B/E A/B/F A/C/H} as shown in Figure 2, where dashed lined boxes shows included and strike-through letters shows excluded instances respectively.

Figure 2. The resultant <effective_elements_list> from create_power_domain UPF command and options.

Implicit versus Explicit Transitive Commands
What distinguishes UPF semantics that have explicit –transitive options from those which are implicitly transitive?

Let’s take two examples, shown in lists 4 and 5. The connect_supply_set command is for connecting a supply set to a particular element and set_retention_elements command that creates a list of elements whose collective state shall be maintained if retention is applied to any of the elements in the list.

List 4: Example of UPF Commands with Explicit–transitive Options

connect_supply_set supply_set_ref {-connect {supply_function pg_type_list}}*
[-elements element_list] 
[-exclude_elements exclude_list] 
[-transitive [<TRUE | FALSE>]]

List 5: Example of UPF Commands with Explicit –transitive Options

set_retention_elements retention_list_name -elements element_list
[-applies_to <required | optional | not_required | not_optional>] 
[-exclude_elements exclude_list] 
[-retention_purpose <required | optional>] 
[-transitive [<TRUE | FALSE>]]

Here both of these two commands contains explicit –transitive option but the inherent transitive nature comes into play through the use of the [-elements element_list] or [‑exclude_elements exclude_list] or their combination. That means, UPF commands with –elements and ‑exclude_elements will be effective with the transitive nature unless –transitive FALSE is mentioned.

The latest version of the UPF LRM 1801-2018 defines some new UPF semantics; such as: the sim_assertion_control command for controlling the behavior of user-assertions during UPF based verification; the sim_corruption_control command for providing the verification tool the ability to control or disable corruption semantics on specific design elements; and the set_replay_control command to specify and control the re-initialization of initial blocks at power up. It also accompanies –transitive explicitly.

However, like create_power_domain, there are other UPF commands, as shown in List 6, that are implicitly followed by transitive TRUE options; although -transitive is not an explicitly defined option for them.

List 6. Other UPF Commands-Options that Are Transitive in Nature

set_simstate_behavior, etc.

On the contrary, UPF strategies from 1801-2013 or UPF 2.1, as mentioned in List 7, are not implicitly followed by transitive TRUE options or are not transitive in nature.

List 7. UPF Commands-Options That Are Not Transitive in Nature

or port attribute command
set_port_attributes etc.

One of the main reasons that the transitive nature does not apply to these commands is because UPF strategies are either applied on power domain boundaries (isolation, level-shifter, repeater etc.) or on signals or sequential elements (retention), and port attributes are applied to ports. Also because of the –source, –sink, and ‑applies_to options in these strategies or port attribute commands consolidate to the aggregate_elements_list instead of the effective_elements_list for processing the final set of applied strategies on domain boundaries or signals or ports.

It is important to note that all of the commands in List 7 have –transitive as an explicit option in 1801-2009 or UPF 2.0.

From 1801-2013 or UPF 2.1 onward (i.e. in UPF 2.1, 3.0 or 3.1) the –transitive is no longer available as an option or inherent feature for these commands shown in List 7. And now they are not transitive in nature.

Nevertheless you can use UPF LRM specified and well-supported regular expression commands like query_upf and find_objects with the explicit –transitive option to populate their –elements {} or ‑exclude_elements lists for commands mentioned in List 7. The UPF regexp allows pattern matching (wildcarding) without tedious verbosity on instances and ports for populating –elements {}, –exclude_elements {}, ports {} lists for set_isolation, or set_port_attributes commands.

Even the UPF 3.0 specified UPF Information Model defines a class object upfExtentT for the property upf_effective_extents. The upfExtentT provides a pointer to the first element of the resolved_element_list for all relevant UPF objects (like power domain) and all strategies (like retention, isolation, level-shifter, and repeater, etc.) Even for the power switch it works for the –instance option of the create_power_switch command and UPF power models (macros) through apply_power_model command. This can be used with the UPF regexp command find_objects as well.

How to Utilize the Transitive Natures of UPF
Now we will utilize the transitive natures of UPF through the Questa PA simulator. Obviously the LRM specifications are universal for most power aware simulators — only compile, optimization, and simulation commands may vary among tools and vendors.

The following list shows the UPF syntax for the UPF find_objects command.

List 8: UPF find_objects Syntax

find_objects scope -pattern search_pattern
[-object_type <model | inst | port | supply_port | net | process>] 
[-direction <in | out | inout>] 
[-transitive [<TRUE | FALSE>]] 
[-regexp | -exact] 
[-non_leaf | -leaf_only] 

To be specific, you can use find_object directly in your design UPF file to find logical hierarchical objects within a scope. Specifically, it will search for design elements, nets, or ports that are defined in the HDL. It works on the logical hierarchy and only searches in the scope or in and below the scope when –transitive is specified. Please refer to the following examples for different find_object based search patterns.

Example 1: Tcl glob Expression: When Neither -regexp Nor -exact Is Specified

# Find object for a pattern
find_objects top -pattern {a}
find_objects top -pattern {bc[0-3]}
find_objects top -pattern {e*}
find_objects top -pattern {d?f}
find_objects top -pattern {g\[0\]}
# Find net type objects
find_objects top -pattern { a* } -object_type net

Example 2: Regular Expression: When -regexp Is Specified

# Find port type object with direction output
find_objects top -pattern { a_.* } -object_type port -direction out -regex

Example 3: Exact Expression: When -exact Is Specified

# Find process objects
find_objects top -pattern { a_proc } -object_type process –exact

Questa PA supports the synthesis style hierarchical paths for generate blocks. When generated blocks are involved in the extents of power domain construction, as shown in Figure 3, find_objects requires specifying ‑transitive TRUE.

Figure 3. Design example hierarchical block diagram with generate block.

Note that in Questa10.6 and previous releases, find_objects also requires the following vopt option, shown in LIST 9, which is the default in Questa 10.7, Questa PA 2019.X, and onward.

List 9: Tool Option for Generate Blocks in Design Hierarchy

vopt –pa_upfextensions=genblk

The following two examples show Questa PA in default mode and in a mode when generate-block is recognizable through the vopt option specified in List 9.

Example 4: Default regexp Mode

# Default Mode
find_objects top -pattern {*} -object_type inst

   Returns: top/mid

find_objects top -pattern {*} -object_type inst -transitive TRUE

   Returns: top/mid top/gen1/bot

find_objects top/gen1 -pattern {*} -object_type inst

   Returns: Invalid Scope Error.

Example 5: Special regexp Mode when Generate Block Is Identified

# vopt –pa_upfextensions=genblk
find_objects top -pattern {*} -object_type inst

   Returns: top/mid top/gen1

find_objects top -pattern {*} -object_type inst -transitive TRUE

   Returns: top/mid top/gen1 top/gen1/bot

find_objects top/gen1 -pattern {*} -object_type inst

   Returns: top/gen1/bot

Questa PA allows users to dump the output of the search through the regexp UPF command find objects in a text file to analyze and add or remove any instance, ports in the UPF development process.

List 10: Tool Option for Dumping regexp Results in External File

vopt –pa_dbgfindobj=<filename>

The code examples on this page show the complete usage of UPF objects for the hierarchical DUT shown in Figure 4(a), the Design UPF with find_object commands shown in Figure 4(b), and the output results of find_objects written or dumped in a text file shown in Figure 4(c).

Figure 4(a). DUT generate block.

Figure 4(b). UPF with find_objects generate block.

Figure 4(c). Find object results generate block.

UPF commands-options are inherently transitive in nature through the implicit or explicit –transitive option. With the progression of UPF revisions from UPF 2.0 to 2.1, the transitive nature becomes more realistic and consistent with all UPF semantics, specifically for UPF strategies, as well as for UPF and DUT objects.

The transitive nature of query_upf and find_objects allows pattern matching (wildcarding) without tedious verbosity on instances and ports for populating –elements {}, –exclude_elements {}, and –ports {} lists for UPF strategies. Even the newly defined UPF 3.0 Information Model has a class object upfExtentT for the property upf_effective_extents that provides a pointer to identify and develop elements list for all relevant UPF objects from power domain to UPF strategies — even power switch and power models (macros).

The concepts and methods presented in this article empower the power management intent of any design by identifying the transitive natures of UPF commands and establishing links with design objects; such as instances, ports, and nets. This allows engineers to be more productive with power management and more intuitive during power aware verification.

For more information on low-power checking using UPF 3.0 download our whitepaper, Moving Beyond Assertions: An Innovative Approach to Low-Power Checking Using UPF Tcl Apps.

Leave a Reply

(Note: This name will be displayed publicly)