【UG835】1 Vivado中Tcl 对象及其关系

1.3 第一类 Tcl 对象和关系

Vivado 中的 Tcl 命令直接访问网表、器件和项目中的对象模型。这些模型是Vivado 第一类 （first-class）模型，这代表他们不只是一个字符串表示，它们可以被操作和查询。除了一些例外情况，一般的“things”可以作为对象被查询，这些对象有一些可以查询的属性以及具有帮助获取其他相关对象的关系。

1.3.1 对象类型及定义

Vivado中有很多对象类型，最基本以及最重要的类型是与设计网表中的实体相关的类型，这些类型定义如下：

• Cell:
  Cell是一个实例，可以是网表中的硬件基元（Primitive），也可以是一个层级（hierarchical）。例子包括 flip-flop，LUT，I/O buffer，RAM和DSP。层级实例是其他Cell组合的封装。

• Pin:
  Pin是Cell中的一个逻辑连接点。Pin可以将cell的内部结构抽象出来并简化以方便使用，可以存在层级的或者硬件基元cell中。例子包括clock，data，reset，触发器的输出引脚。

• Port:
  Port是对象边界上的一个连接，用于将内部条目连接到对象的外部。顶层网表或设计中的Port通常连接到die(被封装的集成电路裸片)上的I/O pad，连接到fpga的引脚，并在系统级设计中连接外部与fpga。层次单元、模块或实体内部的Port表示为层次单元上的Pin。

• Net:
  Net是最终在物理上直接连接在一起的导线（wire）或导线列表。网可以是分层的，也可以是平面的，但总是将按Pin列表整理在一起。

• Clock:
  Clock是一种在设计中传播到时序逻辑的周期信号。Clock可以是主时钟域或由时钟原语如DCM、PLL或MMCM生成。一个时钟大致相当于一个TIMESPEC PERIOD约束，是静态时序分析算法的基础。

//------------------------------------begin

也就是说，在Vivado综合或实现后的网表中，Port一般指的是I/O Port，而内部模块的接口用Pin来查询。

//------------------------------------end

1.3.2 查询对象

所有的第一类对象都可以通过Tcl命令get_*进行查询，语法如下：

• get_object_type pattern

模式（pattern）是一个搜索模式，包括用层次分隔符来获得限定之下的名称。对象通常通过应用层次结构的每一层的字符串模式匹配进行查询，而且搜索模式还支持通配符样式的搜索模式，以便更容易地找到对象，例如:

• get_cells */inst_1

该命令在顶层下的层次结构的第一层中搜索名为inst_1的单元格。要在层次结构的每一层递归地搜索模式，请使用以下语法:

• get_cells -hierarchical inst_1

该命令在层次结构的每一层搜索与inst_1匹配的任何实例。

有关命令语法的完整介绍，请参阅个别命令的具体联机帮助:

• help get_cells
• get_cells -help

//------------------------------------begin
比如要获取这个实例顶层的aurora_64b66b_block_i下的inst 单元。我们知道inst是顶层下第一层级（aurora_64b66b_block_i）中的cell，就可以用*通配符表示第一层级，搜索所有第一层级下面的名为inst的Cell。

而如果使用-hierarchical选项，则会搜索出所有层级中名为inst的Cell。

//------------------------------------end

1.3.3 对象属性

对象具有可查询的属性。对于任何给定的对象类型属性名都是唯一的。要查询对象的特定属性，可以使用以下命令:

• get_property <property_name> <object>

例如，单元格对象上的lib_cell属性会告诉你一个给定实例映射到哪个UniSim组件:

• get_property lib_cell [get_cell inst_1]

要发现给定对象类型的所有可用属性，请使用report_property命令:

• report_property [get_cells inst_1]

为特定对象返回的属性:

关键词	值	类型
bel	OLOGICE1.OUTFF	string
class	cell	string
iob	TRUE	string
is_blackbox	0	bool
is_fixed	0	bool
is_partition	0	bool
is_primitive	1	bool
is_reconfigurable	0	bool
is_sequential	1	bool
lib_cell	FD	string
loc	OLOGIC_X1Y27	string
name	error	string
primitive_group	FD_LD	string
primitive_subgroup	flop	string
site	OLOGIC_X1Y27	string
type	FD & LD	string
XSTLIB	1	bool

有些属性是只读的，有些是用户可设置的。映射到可以在UCF或HDL中注释的属性的属性通常是用户可以通过Tcl使用set_property命令设置的, 如:

• set_property loc OLOGIC_X1Y27 [get_cell inst_1]

//------------------------------------begin
获取顶层下面一个FDRE（Single Data Rate D Flip-Flop with Synchronous Reset and Clock Enable (posedge clk)）的属性：

//------------------------------------end

1.3.4 基于属性的过滤

对象查询get_*命令有一个通用选项，可以根据附加到对象的任何属性值筛选查询。这是对象查询命令的强大功能。例如，要查询原始类型FD的所有单元格，请执行以下操作:

• get_cells * -hierarchical -filter “lib_cell == FD”

要进行更精细的字符串过滤，可以使用=~操作符进行字符串模式匹配。例如，要查询设计中的所有触发器类型，执行以下操作:

• get_cells * -hierarchical -filter “lib_cell =~ FD*”

多个筛选器属性可以与具有逻辑或(||)和的其他属性筛选器组合和(&&)操作符进行非常强大的搜索。查询设计中的每个单元格，如果是任何触发器类型，并且有放置位置约束:

• get_cells * -hierarchical -filter {lib_cell =~ FD* && loc != “”}

注意:在这个例子中，过滤器选项的值是用大括号{}括起来的，而不是双引号。这是正常的Tcl语法，它防止解释器替换命令，并允许用户将空字符串(" ")传递给loc属性。

1.3.5 处理对象列表

返回多个对象的命令，如get_cells或get_sites，将在Vivado工具中返回一个集合，该集合的外观和行为都类似于Tcl列表。当处理大型Tcl对象列表时，无需使用foreach_in_collection等特殊命令时，该特性可以提高性能。在Vivado Design Suite中，可以像Tcl列表一样使用内置命令(如lsort、lsearch和foreach)来处理集合。

通常，当运行get_*命令时，返回的结果将以Tcl字符串的形式回显到控制台和日志文件，而不是由于Tcl的一个称为“shimmering”的特性而以列表的形式回显。在内部，Tcl既可以将变量或值存储为字符串，也可以存储为更快的本机对象，如float或list对象。在Tcl中，当对象或值的表示从列表对象更改为字符串对象，或从字符串更改为列表时，就会发生shimmering。get_*命令返回Vivado对象列表，但shimmering的字符串表示被写入日志文件和Tcl控制台。

然而，为了提高性能和防止内存缓冲区超载，Vivado限制并将闪烁字符串截断为tcl定义的默认字符长度。参数collectionResultDisplayLimit，默认值为500。可以返回大量对象的命令，如get_cells或get_sites，将截断返回的字符串，以省略号(’…’)结尾。可以使用set_param命令更改tcl.collectionResultDisplayLimit参数值返回更多或更少的结果。

注意：Vivado中shimmering与tcl.collectionResultDisplayLimit参数的结合使用，避免使用列表操作符in和ni，因为因为从列表中闪烁的字符串可能会被截断，in 和ni 操作符不能有效地确定指定的对象是在对象列表中还是不在列表中。应该使用列表命令，如lsearch和lsort。
if {[lsearch -exact [get_cells *] $cellName] != -1} {...}

通过将结果赋值给Tcl变量获得get_*捕获完整的列表。

• set allSites [get_sites]

变量赋值中的实际列表包括完整的结果集，并没有被tcl.collectionResultDisplayLimit参数截断。这方面的一个例子可以在查询设计中的所有Cell时看到:

%set allCells [get_cells -hierarchical]
DataIn_pad_0_i_IBUF[0]_inst DataIn_pad_0_i_IBUF[1]_inst \
DataIn_pad_0_i_IBUF[2]_inst DataIn_pad_0_i_IBUF[3]_inst \
DataIn_pad_0_i_IBUF[4]_inst ...
%llength $allCells
42244
%lindex $allCells end
wbArbEngine/s4/next_reg

在前面的示例中，层级get_cells命令的结果被分配给$allCells变量。表面上结果被截断了。但是，对列表长度的检查报告有超过四万个cell对象，列表中的最后一个索引返回一个实际对象，而不是省略号。

提示:如果有必要，还可以使用join 命令来连接由get_*返回的对象列表Tcl命令，用换行符(\n)、制表符(\t)或空格(" ")显示未截断的对象列表:

join [get_parts] " "

//------------------------------------begin
这一部分说的是get_*获取的结果是一个列表，但是为了显示效果，会在Tcl Console和日志文件中显示为字符串。但是为了提高性能以及防止占用太多内存缓冲区，所以会限制字符串显示的列表的长度，这个长度可以通过tcl.collectionResultDisplayLimit参数值来设定。

//------------------------------------end

1.3.6 对象的关系

相关对象可通过相关get_*命令的-of选项查询。例如，要获取连接到Cell对象的Pin列表，执行以下操作:

• get_pins -of [get_cells inst_1]

下图显示了Vivado工具中的对象类型及其关系，其中从一个对象到另一个对象的箭头表示可以使用get_*命令的-of选项来遍历逻辑连接并获得对任何连接对象的Tcl引用。有关第一类对象及其关系的更多信息，参阅UG912。

//------------------------------------begin
查找顶层下面的aurora_64b66b_block_i所有的输入引脚：
get_pins -filter "DIRECTION == IN" -of [get_cells aurora_64b66b_block_i]

//------------------------------------end