3. UPF文件结构与命令语义

UPF（Unified Power Format）本质上是一组以 Tcl 为载体的低功耗意图描述命令。它并不直接改变 RTL 的功能逻辑，而是向综合、布局布线、时序与功耗签核工具声明“电源从哪里来、经过哪些开关、供给哪些域、以什么电压工作”。理解 UPF，关键是理解它的对象模型与作用域规则：电源域（power domain）、供电端口（supply port）、供电网络（supply net）是三类基础对象，而 connect_supply_net 与 set_domain_supply_net 负责把它们连接成一张可被工具求解的供电拓扑。

一、UPF 的层次结构与作用域

UPF 命令通常写在 create_power_domain 建立的域作用域内，或写在顶层作用域中。作用域决定了命令中相对名称的解析基准：在某个 power domain 内声明的 supply net，默认属于该域；在顶层声明的，则属于顶层。工具按“当前作用域 → 上层作用域”的顺序解析名称，这与 Tcl 的命名空间查找一致。因此，一个常见工程约定是：先建域，再在域内建端口与网络，最后在顶层做跨域连接，避免名称歧义。

典型文件骨架如下（示例，非实测结果）：

# 1. 定义电源域
create_power_domain PD_CPU -include_scope
create_power_domain PD_GPU -elements {u_gpu}

# 2. 定义供电端口（芯片边界）
create_supply_port VDD   -domain PD_CPU
create_supply_port VDD_G -domain PD_GPU
create_supply_port VSS   -domain PD_CPU

# 3. 定义供电网络
create_supply_net VDD   -domain PD_CPU
create_supply_net VDD_G -domain PD_GPU
create_supply_net VSS   -domain PD_CPU -reuse

# 4. 端口与网络连接
connect_supply_net VDD   -ports {VDD}
connect_supply_net VDD_G -ports {VDD_G}
connect_supply_net VSS   -ports {VSS}

# 5. 指定域的主供电
set_domain_supply_net PD_CPU -primary_power_net VDD -primary_ground_net VSS
set_domain_supply_net PD_GPU -primary_power_net VDD_G -primary_ground_net VSS

二、create_power_domain：域的边界与包含关系

create_power_domain 定义一个电源域，语法要点是域名称与元素集合。常用选项包括 -include_scope（把当前作用域内所有未归属的实例纳入该域）、-elements（显式列出实例或模块）、-scope（指定域的作用范围）。域是后续所有供电关系的主体：一个实例只能属于一个电源域，域之间可以有不同的电压、不同的开关策略。若一个模块被多个域引用，必须通过 -elements 明确划分，否则工具会报“实例归属冲突”。

需要强调的是，域不是物理区域，而是逻辑归属。物理实现时，同一域的元素可能被摆放得很分散，但它们的供电网络与电源状态必须一致。这也是为什么 UPF 要在综合前就确定域边界：它直接影响电平转换器（level shifter）、隔离单元（isolation cell）和电源开关（power switch）的插入位置。

三、create_supply_port 与 create_supply_net：电源的入口与载体

create_supply_port 声明芯片或模块边界的供电端口，相当于电源的“入口”。它通常与 -domain 一起使用，表示该端口属于哪个域。端口本身不携带电压值，电压由后续的 create_supply_net 或 set_voltage 关联。

create_supply_net 声明一条供电网络，是电流实际流经的载体。常用选项有 -domain（归属域）、-reuse（复用已存在的网络，避免重复创建）、-resolve（处理同名冲突）。一个域通常至少需要一条 power net 和一条 ground net。若同一域内存在多电压，可创建多条 net 并用 set_voltage 分别指定电压值，例如 0.9V 与 1.2V。

四、connect_supply_net 与 set_domain_supply_net：连接与主供电

connect_supply_net 把供电网络连接到端口、引脚或其它网络，语法核心是“网络 + 目标”。它解决的是“这条 net 接到哪里”的问题。常见形式包括：-ports 连接边界端口，-pins 连接单元引脚，-nets 连接内部网络。连接方向由工具根据端口方向自动推断，因此同一命令既可表达输入供电，也可表达输出供电。

set_domain_supply_net 则回答“这个域的主供电是谁”。它通过 -primary_power_net 与 -primary_ground_net 指定域内默认使用的电源与地网络。当域内单元未显式指定供电时，工具就使用主供电网络。若域内存在多个供电网络（如 always-on 与可关断），主供电应指向默认工作网络，其余网络通过 connect_supply_net 或 set_port_attributes 单独处理。

五、命令作用域与常见错误

作用域错误是 UPF 调试中最常见的问题。例如在顶层用相对名创建 net，却在域内引用，工具会找不到对象；或者在域内创建了 net，却忘记用 connect_supply_net 把它接到端口，导致该域“悬空”，综合时出现未驱动供电的告警。另一个高频问题是 set_domain_supply_net 指定的网络与域内实际连接的网络不一致，造成工具在插入隔离单元时选错供电轨。

建议的检查顺序是：先用 check_power_domain 或工具自带的 UPF 检查命令确认域归属无冲突；再用报告命令列出每个域的 primary power/ground net；最后核对端口、网络、域三者的连接是否闭合。若某条 net 同时被两个域声明为主供电，必须拆分为两条 net 或明确复用关系，否则签核阶段会出现电压冲突。

六、小结与工程建议

把本节五条命令串起来看：create_power_domain 划定“谁属于哪个域”，create_supply_port 定义“电从哪里进来”，create_supply_net 定义“电走哪条线”，connect_supply_net 完成“线接到哪里”，set_domain_supply_net 指定“域默认用哪条线”。五者构成一个从边界到域内的完整供电声明链。实际项目中，建议把域定义、端口网络定义、连接关系分成三个文件或三个段落维护，并在每次修改后重新运行 UPF 检查，确保作用域与连接关系始终一致。