UPF Command Cheat Sheet - Complete Reference (IEEE 1801)

A comprehensive reference for UPF (Unified Power Format) commands based on IEEE 1801. Use this as a quick lookup when writing or reviewing UPF files.

Table of Contents

• Supply Network Commands
• Power Domain Commands
• Power State Commands
• Power Switch Commands
• Isolation Commands
• Level Shifter Commands
• Retention Commands
• Navigation Commands
• Simulation Commands
• File Management Commands

Supply Network Commands

Define the power distribution infrastructure.

create_supply_port

Creates a supply port for power or ground connection at the design boundary.

create_supply_port port_name
  -domain domain_name
  [-direction in|out|inout]
  [-default_value value]

-domain

Power domain where port is created

-direction

Port direction (default: in)

Example:

create_supply_port VDD -domain PD_TOP -direction in
create_supply_port VSS -domain PD_TOP -direction in

create_supply_net

Creates a supply net to distribute power within a domain.

create_supply_net net_name
  -domain domain_name
  [-reuse]
  [-resolve unresolved|parallel|one_hot|...]

-domain

Power domain containing the net

-reuse

Reuse existing net from parent domain

-resolve

Resolution function for multiple drivers

Example:

create_supply_net VDD_net -domain PD_TOP
create_supply_net VDD_net -domain PD_CORE -reuse
create_supply_net VDD_SW -domain PD_GATED -resolve one_hot

create_supply_set

Creates a named collection of supply nets (power + ground + optional bias).

create_supply_set set_name
  [-function {func_name supply_net_name}]...

-function

Map function to supply net (power, ground, nwell, pwell)

Example:

create_supply_set SS_VDD_1V0 \
    -function {power VDD_1V0} \
    -function {ground VSS}

connect_supply_net

Connects a supply net to ports or other nets.

connect_supply_net net_name
  -ports port_list
  [-pg_type pg_type]

Example:

connect_supply_net VDD_net -ports {VDD}
connect_supply_net VSS_net -ports {VSS}

set_domain_supply_net

Associates supply nets with a power domain.

set_domain_supply_net domain_name
  -primary_power_net net_name
  -primary_ground_net net_name

Example:

set_domain_supply_net PD_CORE \
    -primary_power_net VDD_CORE \
    -primary_ground_net VSS

Power Domain Commands

Define logical groupings of design elements that share power characteristics.

create_power_domain

Creates a power domain containing specified design elements.

create_power_domain domain_name
  [-include_scope]
  [-elements element_list]
  [-supply {supply_set_handle supply_set_name}]
  [-atomic]

-include_scope

Include all elements in current scope

-elements

List of instances/hierarchies to include

-supply

Associate supply set with domain

-atomic

Treat domain as atomic (no internal power management)

Example:

# Top-level domain including everything
create_power_domain PD_TOP -include_scope

# Domain for specific blocks
create_power_domain PD_CPU -elements {u_cpu u_cache}

# Always-on domain
create_power_domain PD_AON -elements {u_pmu u_wakeup}

Tip: Use set_scope before create_power_domain -include_scope to set the correct hierarchy level.

Power State Commands

Define the valid operating states of supply networks and domains.

add_power_state

Defines power states for a supply set or power domain.

add_power_state object_name
  [-supply|-domain]
  -state {state_name
    [-supply_expr {boolean_expression}]
    [-logic_expr {boolean_expression}]
    [-simstate simstate]
    [-legal|-illegal]}

-supply_expr

Boolean expression defining supply conditions

-logic_expr

Boolean expression for logic state

-simstate

Simulation state (NORMAL, CORRUPT, etc.)

-legal/-illegal

Mark state as legal or illegal

Example:

# Supply set states
add_power_state SS_VDD_CORE \
    -state {ON  -supply_expr {power == FULL_ON && ground == FULL_ON}} \
    -state {OFF -supply_expr {power == OFF}}

# Domain states with simstate
add_power_state PD_GATED \
    -state {ACTIVE  -logic_expr {pwr_on} -simstate NORMAL} \
    -state {SLEEP   -logic_expr {!pwr_on && ret_en} -simstate RETENTION} \
    -state {POWERED_OFF -logic_expr {!pwr_on && !ret_en} -simstate CORRUPT}

create_pst (Legacy)

Creates a Power State Table. Deprecated in UPF 2.0+, use add_power_state instead.

create_pst pst_name -supplies supply_list

Example (Legacy):

create_pst my_pst -supplies {VDD_CORE VDD_IO VSS}
add_pst_state RUN  -pst my_pst -state {ON ON ON}
add_pst_state SLEEP -pst my_pst -state {OFF ON ON}

Power Switch Commands

Define switches that control power to domains.

create_power_switch

Creates a power switch (header or footer cell).

create_power_switch switch_name
  -domain domain_name
  -input_supply_port {port_name supply_net}
  -output_supply_port {port_name supply_net}
  -control_port {port_name control_signal}
  -on_state {state_name input_port {boolean}}
  [-off_state {state_name {boolean}}]
  [-ack_port {port_name ack_signal}]
  [-ack_delay {port_name delay}]

-input_supply_port

Always-on input supply

-output_supply_port

Switched output supply

-control_port

Signal controlling the switch

-on_state

State definition when switch is ON

-off_state

State definition when switch is OFF

-ack_port

Acknowledgment signal from switch

Example:

create_power_switch SW_CORE \
    -domain PD_GATED \
    -input_supply_port  {VDDIN VDD_AON} \
    -output_supply_port {VDDOUT VDD_SW} \
    -control_port {SLEEP_B pmu/sleep_n} \
    -on_state  {ON_STATE VDDIN {SLEEP_B}} \
    -off_state {OFF_STATE {!SLEEP_B}} \
    -ack_port  {ACK pmu/sw_ack} \
    -ack_delay {ACK 10ns}

map_power_switch

Maps a power switch to a specific library cell.

map_power_switch switch_name
  -lib_cells lib_cell_list
  [-port_map {{port net}...}]

Example:

map_power_switch SW_CORE \
    -lib_cells {HEADERSW_X1 HEADERSW_X2} \
    -port_map {{VDDIN VDD_AON} {VDDOUT VDD_SW}}

Isolation Commands

Define isolation strategies for signals crossing power domain boundaries.

set_isolation

Specifies isolation strategy for domain interface signals.

set_isolation strategy_name
  -domain domain_name
  [-elements element_list]
  [-exclude_elements exclude_list]
  -applies_to inputs|outputs|both
  -clamp_value 0|1|Z|latch|any
  [-source source_domain]
  [-sink sink_domain]
  [-isolation_supply supply_set]
  [-isolation_signal {signal [sense]}]
  [-location self|parent|fanout|automatic]
  [-no_isolation]

-applies_to

Which signals to isolate (inputs, outputs, or both)

-clamp_value

Value when isolated: 0, 1, Z (high-Z), latch (hold), any

-isolation_signal

Control signal and active sense

-location

Where to place isolation cell

-no_isolation

Explicitly disable isolation for specified elements

Example:

# Isolate outputs from gated domain
set_isolation ISO_GATED_OUT \
    -domain PD_GATED \
    -applies_to outputs \
    -clamp_value 0 \
    -isolation_signal {iso_en high} \
    -isolation_supply SS_AON \
    -location parent

# Isolate specific signals
set_isolation ISO_DATA \
    -domain PD_CORE \
    -elements {data_bus[*] valid} \
    -applies_to outputs \
    -clamp_value 0

# Latch isolation (hold last value)
set_isolation ISO_LATCH \
    -domain PD_GATED \
    -applies_to outputs \
    -clamp_value latch

set_isolation_control

Specifies control signal for an isolation strategy.

set_isolation_control strategy_name
  -domain domain_name
  -isolation_signal {signal sense}
  [-location self|parent]

Example:

set_isolation_control ISO_GATED_OUT \
    -domain PD_GATED \
    -isolation_signal {pmu/iso_ctrl high} \
    -location parent

map_isolation_cell

Maps isolation strategy to specific library cells.

map_isolation_cell strategy_name
  -lib_cells lib_cell_list
  [-port_map {{port net}...}]

Example:

map_isolation_cell ISO_GATED_OUT \
    -lib_cells {ISO_CLAMP0_X1 ISO_CLAMP0_X2}

Tip: Isolation must be enabled before the power domain is shut off, and disabled after power is restored.

Level Shifter Commands

Define level shifting for signals crossing voltage domains.

set_level_shifter

Specifies level shifter strategy for signals between voltage domains.

set_level_shifter strategy_name
  -domain domain_name
  [-elements element_list]
  [-exclude_elements exclude_list]
  -applies_to inputs|outputs|both
  -rule low_to_high|high_to_low|both
  [-threshold voltage_diff]
  [-input_supply supply_set]
  [-output_supply supply_set]
  [-location self|parent|fanout|automatic]
  [-no_shift]

-rule

Shifting direction: low_to_high, high_to_low, or both

-threshold

Minimum voltage difference requiring shift

-input_supply

Supply for input side

-output_supply

Supply for output side

-no_shift

Explicitly disable shifting for specified elements

Example:

# Low-to-high level shifter on outputs
set_level_shifter LS_LtoH \
    -domain PD_CORE_0V8 \
    -applies_to outputs \
    -rule low_to_high \
    -location self

# High-to-low on inputs
set_level_shifter LS_HtoL \
    -domain PD_CORE_0V8 \
    -applies_to inputs \
    -rule high_to_low \
    -location parent

# Both directions with threshold
set_level_shifter LS_BOTH \
    -domain PD_MIXED \
    -applies_to both \
    -rule both \
    -threshold 0.1

map_level_shifter_cell

Maps level shifter strategy to specific library cells.

map_level_shifter_cell strategy_name
  -lib_cells lib_cell_list
  [-port_map {{port net}...}]

Example:

map_level_shifter_cell LS_LtoH \
    -lib_cells {LVLSHIFT_LH_X1 LVLSHIFT_LH_X2}

Retention Commands

Define retention strategies for preserving state during power-down.

set_retention

Specifies retention strategy for registers in a domain.

set_retention strategy_name
  -domain domain_name
  [-elements element_list]
  [-exclude_elements exclude_list]
  [-retention_supply supply_set]
  [-retention_power_net net]
  [-retention_ground_net net]
  [-save_signal {signal edge}]
  [-restore_signal {signal edge}]

-elements

Specific registers/flops to retain

-retention_supply

Supply set for retention (always-on)

-save_signal

Signal and edge to save state (posedge/negedge)

-restore_signal

Signal and edge to restore state

Example:

# Basic retention
set_retention RET_CORE \
    -domain PD_GATED \
    -retention_supply SS_AON \
    -save_signal {ret_save posedge} \
    -restore_signal {ret_restore posedge}

# Retention for specific elements
set_retention RET_CONFIG \
    -domain PD_GATED \
    -elements {u_config/cfg_reg[*]} \
    -retention_supply SS_AON

# Exclude some registers
set_retention RET_ALL \
    -domain PD_GATED \
    -exclude_elements {u_datapath/tmp_reg[*]} \
    -retention_supply SS_AON

set_retention_control

Specifies control signals for retention.

set_retention_control strategy_name
  -domain domain_name
  -save_signal {signal edge}
  -restore_signal {signal edge}

Example:

# Same signal, different edges
set_retention_control RET_CORE \
    -domain PD_GATED \
    -save_signal {pmu/ret_ctrl posedge} \
    -restore_signal {pmu/ret_ctrl negedge}

map_retention_cell

Maps retention strategy to specific library cells.

map_retention_cell strategy_name
  -lib_cells lib_cell_list
  [-port_map {{port net}...}]

Example:

map_retention_cell RET_CORE \
    -lib_cells {DFFRET_X1 DFFRET_X2}

Tip: Save signal must be asserted before power-off. Restore signal must be asserted after power is stable.

Navigation Commands

Navigate and set context within the design hierarchy.

set_design_top

Sets the top-level design for UPF scope.

set_design_top design_name

Example:

set_design_top soc_top

set_scope

Sets the current hierarchical scope for subsequent UPF commands.

set_scope instance_path

Example:

# Set scope to subsystem
set_scope u_subsystem
create_power_domain PD_SUB -include_scope

# Return to top level
set_scope /

Simulation Commands

Control power-aware simulation behavior.

set_simstate_behavior

Defines how signals behave during simulation in different power states.

set_simstate_behavior behavior
  [-domain domain_name]
  [-elements element_list]

behavior

NORMAL, CORRUPT, HOLD, etc.

Example:

set_simstate_behavior CORRUPT -domain PD_GATED

set_port_attributes

Sets attributes on ports for simulation.

set_port_attributes port_list
  [-attribute value]...

Example:

set_port_attributes clk -attribute related_power_port VDD

File Management Commands

Load, save, and manage UPF files.

load_upf

Loads and executes a UPF file at specified scope.

load_upf filename
  [-scope instance_path]

Example:

# Load IP-level UPF
set_scope u_cpu
load_upf cpu_power.upf

# Or with -scope option
load_upf cpu_power.upf -scope u_cpu

save_upf

Saves current UPF state to a file.

save_upf filename
  [-scope instance_path]
  [-full]

Example:

save_upf output_power.upf -full

upf_version

Specifies the UPF version for the file.

upf_version version

Example:

upf_version 2.1

Complete UPF Example

Here's a complete UPF example for an SoC with always-on and gated power domains:

##############################################
# UPF for SoC with Gated and Always-On Domains
##############################################
upf_version 2.1
set_design_top soc_top

#----- Supply Network -----
create_supply_port VDD     -domain PD_TOP -direction in
create_supply_port VDD_AON -domain PD_TOP -direction in
create_supply_port VSS     -domain PD_TOP -direction in

create_supply_net VDD_net     -domain PD_TOP
create_supply_net VDD_AON_net -domain PD_TOP
create_supply_net VSS_net     -domain PD_TOP
create_supply_net VDD_SW      -domain PD_TOP

connect_supply_net VDD_net     -ports {VDD}
connect_supply_net VDD_AON_net -ports {VDD_AON}
connect_supply_net VSS_net     -ports {VSS}

#----- Supply Sets -----
create_supply_set SS_TOP \
    -function {power VDD_net} \
    -function {ground VSS_net}

create_supply_set SS_AON \
    -function {power VDD_AON_net} \
    -function {ground VSS_net}

create_supply_set SS_GATED \
    -function {power VDD_SW} \
    -function {ground VSS_net}

#----- Power Domains -----
create_power_domain PD_TOP -include_scope \
    -supply {primary SS_TOP}

create_power_domain PD_AON -elements {u_pmu u_wakeup} \
    -supply {primary SS_AON}

create_power_domain PD_GATED -elements {u_cpu u_cache} \
    -supply {primary SS_GATED}

#----- Power Switch -----
create_power_switch SW_GATED \
    -domain PD_GATED \
    -input_supply_port  {VDDIN VDD_net} \
    -output_supply_port {VDDOUT VDD_SW} \
    -control_port {SLEEP_N u_pmu/pwr_en} \
    -on_state  {ON  VDDIN {SLEEP_N}} \
    -off_state {OFF {!SLEEP_N}} \
    -ack_port  {ACK u_pmu/sw_ack}

#----- Isolation -----
set_isolation ISO_GATED \
    -domain PD_GATED \
    -applies_to outputs \
    -clamp_value 0 \
    -isolation_supply SS_AON \
    -isolation_signal {u_pmu/iso_en high} \
    -location parent

#----- Retention -----
set_retention RET_GATED \
    -domain PD_GATED \
    -retention_supply SS_AON \
    -save_signal    {u_pmu/ret_save posedge} \
    -restore_signal {u_pmu/ret_restore posedge}

#----- Power States -----
add_power_state SS_TOP \
    -state {ON -supply_expr {power == FULL_ON && ground == FULL_ON}}

add_power_state SS_AON \
    -state {ON -supply_expr {power == FULL_ON && ground == FULL_ON}}

add_power_state SS_GATED \
    -state {ON  -supply_expr {power == FULL_ON && ground == FULL_ON}} \
    -state {OFF -supply_expr {power == OFF}}

add_power_state PD_GATED \
    -state {ACTIVE -logic_expr {SS_GATED == ON} -simstate NORMAL} \
    -state {RETENTION -logic_expr {SS_GATED == OFF} -simstate RETENTION} \
    -state {OFF -logic_expr {SS_GATED == OFF} -simstate CORRUPT}

Quick Reference Table

Category	Command	Purpose
Supply	create_supply_port	Define power/ground ports
Supply	create_supply_net	Define power distribution nets
Supply	create_supply_set	Group power+ground nets
Supply	connect_supply_net	Connect nets to ports
Domain	create_power_domain	Define power domain
Domain	set_domain_supply_net	Assign supplies to domain
State	add_power_state	Define valid power states
Switch	create_power_switch	Define power switch
Switch	map_power_switch	Map to library cell
Isolation	set_isolation	Define isolation strategy
Isolation	set_isolation_control	Specify control signal
Isolation	map_isolation_cell	Map to library cell
Level Shift	set_level_shifter	Define level shifter strategy
Level Shift	map_level_shifter_cell	Map to library cell
Retention	set_retention	Define retention strategy
Retention	set_retention_control	Specify save/restore signals
Retention	map_retention_cell	Map to library cell
Navigation	set_design_top	Set top-level design
Navigation	set_scope	Set hierarchical scope
File	load_upf	Load UPF file
File	save_upf	Save UPF file

Resources

• IEEE 1801-2024 Standard
• IEEE UPF Open Source Repository
• Accellera Systems Initiative