tincr Namespace Reference

All of the Tcl procs provided in the design package are members of the tincr namespace. More...

Namespaces
	bel_pins
	The bel_pins ensemble encapsulates the bel_pin class from Vivado's Tcl data structure.
	bels
	The bels ensemble encapsulates the bel class from Vivado's Tcl data structure.
	cells
	The cells ensemble encapsulates the cell class from Vivado's Tcl data structure.
	clocks
	The clocks ensemble encapsulates the clock class from Vivado's Tcl data structure.
	designs
	The designs ensemble encapsulates the design class from Vivado's Tcl data structure.
	lib_cells
	The lib_cells ensemble encapsulates the lib_cell class from Vivado's Tcl data structure.
	lib_pins
	The lib_pins ensemble encapsulates the lib_pin class from Vivado's Tcl data structure.
	libs
	The libs ensemble encapsulates the lib class from Vivado's Tcl data structure.
	macros
	The macros ensemble encapsulates the macro class from Vivado's Tcl data structure.
	nets
	The nets ensemble encapsulates the net class from Vivado's Tcl data structure.
	nodes
	The noes ensemble encapsulates the node class from Vivado's Tcl data structure.
	package_pins
	The package_pins ensemble encapsulates the package_pin class from Vivado's Tcl data structure.
	parts
	The parts ensemble encapsulates the part class from Vivado's Tcl data structure.
	pblocks
	The pblocks ensemble encapsulates the pblock class from Vivado's Tcl data structure.
	pins
	The pins ensemble encapsulates the pin class from Vivado's Tcl data structure.
	pips
	The pips ensemble encapsulates the pip class from Vivado's Tcl data structure.
	ports
	The ports ensemble encapsulates the port class from Vivado's Tcl data structure.
	site_pins
	The site_pins ensemble encapsulates the site_pin class from Vivado's Tcl data structure.
	site_pips
	The site_pips ensemble encapsulates the site_pip class from Vivado's Tcl data structure.
	sites
	The sites ensemble encapsulates the site class from Vivado's Tcl data structure.
	tiles
	The tiles ensemble encapsulates the tile class from Vivado's Tcl data structure.
	wires
	The wires ensemble encapsulates the wire class from Vivado's Tcl data structure.

Functions
	get_default_value cell config
	reset_configuration cell config_list
	get_supported_libcells
	get_supported_leaf_libcells
	get_supported_macro_cells
	random_placer ?seed? ?verbose?
	parse_argsx flags options statements args
	refresh_packages
	diff_files args
	print args
	print_list args
	set_tcl_display_limit limit
	reset_tcl_display_limit
	parse_options _args
	parse_flags_and_options _args
	parse_args options flags optional required arguments
	extract_flag flag var_name args_name
	parse_args2 flags options statements args
	parse_arguments provided_args args
	generate_namespace_export_list args
	assert condition ?message?
	binary_search list search
	dict_difference dict1 dict2 ?nesting_level?
	count_dict_leaves dict nesting_levels ?count_as?
	lequal l1 l2
	list_match search values
	foreach_element cmd list
	build_list args
	lpop varName
	lremove varName index
	min args
	max args
	minimum_index list
	maximum_index list
	contains_substring string substring
	ends_with string1 string2
	starts_with string1 string2
	is_valid_filename filename
	add_extension args
	suffix string token
	report_runtime cmd ?format?
	average_runtime args
	format_time value ?format?
	catch_info cmd
	print_verbose message ?newline?
	compare_objects obj1 obj2
	diff_objects obj1 obj2
	list_properties objects ?property_regex?
	print_object_properties obj
	remove_speedgrade partname
	process_handler chan
	spawn_vivado_run script
	run_in_temporary_project args
	organize_by elements ?property?
	get_name obj
	get_type obj
	get_class obj
	run_rapidsmith_command cmd
	test_routethrough bel expected_inpin expected_outpin
	test_static_sources bel
	report_property_values cell property_list
	report_cell_placement_info cell
	report_physical_net_info net
	report_vcc_routing_info
	report_gnd_routing_info
	report_used_site_count
	report_used_site_pips site
	test_default_cell cell
	test_port_placement port expected_port_loc
	write_tcp filename
	write_rscp args
	read_tcp args
	sort_cells_for_export cells
	write_design_info args
	write_placement_xdc args
	write_routing_xdc args
	get_design_info args
	get_pins_to_lock cell
	write_macros ?filename?
	write_placement_rs2 ?filename?
	get_internal_macro_nets macro
	write_routing_rs2 args
	read_tcp_ooc_test filename
	write_tcp_ooc_test filename
	write_tcp_for_pblock filename pblock nets
	get_internal_nets pblock
	group_cells_by_clock_region
	get_closest_clb_tile tile ?direction?
	get_leftmost_slice clb
	get_rightmost_slice clb
	is_clb_tile tile
	write_macro_xml macro outfile
	print_rapidSmith_license outfile
	create_xml_cell_library ?part? ?filename? ?threshold?
	test_cell_library ?part?
	create_xml_device_info directory partname
	create_xml_family_info filename family ?vsrt_bels_file?
	write_xdlrc args
	write_xdlrc_tile tile outfile brief
	append_primitive_def site_type outfile
	write_primitive_defs args
	write_partial_primitive_def site filename ?includeConfigs?
	write_vcc_primitive_def directory
	write_gnd_primitive_def directory
	get_primitive_def_cover_set parts ?trials?
	write_all_partial_primitive_defs ?includeConfigs?
	extract_all_partial_primitive_defs path ?arch? ?includeConfigs?
	get_parts_unique ?arch?

Detailed Description

All of the Tcl procs provided in the design package are members of the tincr namespace.

All of the Tcl procs provided in the BYU packages are members of the byu namespace.

Function Documentation

append_primitive_def()

tincr::append_primitive_def			site_type outfile

Appends the primitive definition corresponding to site_type of the current device to the output stream provided by output.

Parameters

site_type	The site type of the corresponding primitive definition.
outfile	The output stream that the primitive definition is to be written to.

assert()

tincr::assert			condition ?message?

Asserts that the specified condition is true if assertions are enabled. Example Usage: assert {$temperature < 100} "Temperature is too high"

Parameters

condition	The condition to check
message	Optional message to print if the assertion fails

create_xml_cell_library()

tincr::create_xml_cell_library			?part? ?filename? ?threshold?

Creates a cell library XML file that can be used by RapidSmith version 2.0. This function should not be called if a project is currently opened.

Parameters

filename	Optional parameter to specify the generated cell library name. The default name is "cellLibrary_part.xml"
part	Xilinx FPGA part to generate a cell library for
threshold	Threshold of configurable pin mappings to compute before quitting. (currently not used but will be used in the future)

create_xml_device_info()

tincr::create_xml_device_info			directory partname

Creates a new device info XML in the specified directory for the specified part. Currently, the device info XML stores additional information about pads in a device (i.e. clock pads and bel to package pin mappings). Other useful information may be added in the future. NOTE: any open projects will be closed when this function is called.

Example Usage: tincr::create_xml_device_info /home/ xcku025-ffva1156-1-c

This will create the file "/home/device_info_xcku025ffva1156.xml"

Parameters

directory	Directory to create the device info file in. If this parameter is not an existing directory, an error will be thrown.
partname	Full partname of a Vivado device

create_xml_family_info()

tincr::create_xml_family_info			filename family ?vsrt_bels_file?

Creates a new familyInfo.xml file for the specified family This XML file contains additional device information/corrections that are not included in the XDLRC generated from <tincr::write_xdlrc>"()".

Parameters

filename	Output XML file. If the file does not end in ".xml", then ".xml" will be appended.
family	The family to generate the family info for. Possible options include:

• artix7
• kintex7
• virtex7
• zynq
• kintexu
• kintexuplus
• virtexu
• virtexuplus
• zynquplus

Parameters

vsrt_bels_file

(Optional) The VSRT "addedBels.txt" file generated while creating primitive defs in VSRT. If you don't know what this means, you can safely ignore it.

extract_all_partial_primitive_defs()

tincr::extract_all_partial_primitive_defs			path ?arch? ?includeConfigs?

Produces a partial .def file for each primitive site of each part in the xilinx family. This function should be called only when a new xilinx series is released. The files produced from this script are intended to be used by the VSRT tool of the RapidSmith2 repository.

NOTE: When the script is running, some warnings will be printed to the screen, but they can be ignored.

Parameters

cfg	Add this option if you want to include cfg strings in your primitive def files.
path	The path you want the family directories and files to be written to.
arch	Architecture to generate primitive defs for currently, possible options include

• artix7
• kintex7
• virtex7
• zynq
• kintexu
• kintexuplus
• virtexu
• virtexuplus
• zynquplus

get_default_value()

tincr::get_default_value			cell config

Gets the default value of a configuration for a given cell. For example, calling tincr::cells::get_default_value $cell IS_C_INVERTED on a Flip Flop cell will return the CONFIG.IS_C_INVERTED.DEFAULT property of the backing library cell.

Parameters

cell	Cell instance
config	Configuration to get the default value of

Returns

The default value of the specified config

get_design_info()

tincr::get_design_info			args

Parses a design.info file of a TCP and returns the requested information. Currently, it is used to parse the partname that a given design is implemented on.

USAGE: tincr::get_design_info filename info

Parameters

Argument

list shown in the usage statement above. The parameter "filename" is the design.info file to parse. The parameter "info" is the name of the key to parse (i.e. part).

Returns

The value of the specified key, or "" if the key is not found

get_internal_macro_nets()

tincr::get_internal_macro_nets			macro

Finds the nets inside of macro primitives that are NOT connected to a macro pin. The routing information for these nets need to be exported when creating a RSCP.

Parameters

macro

Macro cell instance

Returns

A list of internal macro nets

get_parts_unique()

tincr::get_parts_unique			?arch?

Returns a list of unique parts, ignoring speed grade and package type

Parameters

arch	Optional architecture parameter. Only parts that match the specified architecture will be returned.

get_pins_to_lock()

tincr::get_pins_to_lock			cell

For a LUT cell, this function returns the pin mappings of the LUTs input pins

Parameters

cell	Cell in the currently opened design

Returns

A list of pin mappings in the form "cellPin:belPin"

get_primitive_def_cover_set()

tincr::get_primitive_def_cover_set			parts ?trials?

Get the minimum set cover of parts that together contain all of the possible site types for the list of given parts.

Parameters

parts	The set of parts that comprise the universal set of site types.
trial	The number of trials (default is 300).

Returns

A subset of parts that comprise the universal set of site types.

get_supported_leaf_libcells()

tincr::get_supported_leaf_libcells

Creates a list of all supported leaf cells in the current device. Leaf cells are marked as supported if, when instantiated, the reference name of the cell instance matches the name of the library cell. Macro cells are excluded.

Returns

A list of supported leaf cells according to the criteria above.

get_supported_libcells()

tincr::get_supported_libcells

Creates a list of all supported cells in the current device. Cells are marked as supported if, when instantiated, the reference name of the cell instance matches the name of the library cell. Macro cells are included. TODO: update this

Returns

A list of supported cells.

get_supported_macro_cells()

tincr::get_supported_macro_cells

Creates a list of all supported MACRO primitive cells in the current device. Macro cells are marked as supported if, when instantiated, the reference name of the cell instance matches the name of the library cell.

Returns

A list of supported macro cells according to the criteria above.

parse_argsx()

tincr::parse_argsx			flags options statements args

Parses a list of arguments and generates a Usage statement when wrong tincr::parse_args {?{a|b}? c} {d ?e? {f|{g h}}} {i ?j? {k l}...}

print_list()

tincr::print_list			args

Prints a list to specified channel with the specified header

Parameters

print_list	The list to print
header	Optional header to print before the list
channel	Channel to print the list to. The default channel is stdout
newline	Specifies whether to print a new line between list elements. Default is no.

print_rapidSmith_license()

tincr::print_rapidSmith_license			outfile

Prints the RapidSmith license to the specified XML file

Parameters

outfile

XML file handle

print_verbose()

tincr::print_verbose			message ?newline?

Imports all commands currently in the ::byu namespace into the global namespace. This is simply an alias of the command namespace import tincr::*

read_tcp()

tincr::read_tcp			args

Parses a TCP design representation and creates an equivalent design in Vivado. The TCP format is extensively documented in the RapidSmith2 tech report at https://github.com/byuccl/RapidSmith2/tree/master/doc and Thomas Townsend's Masters thesis. The required rules to follow when formatting TCP is also found in TT's Masters thesis published at BYU.

USAGE: tincr::read_tcp [-quiet] [-verbose] [-ooc] filename

Parameters

args

Argument list shown in the usage statement above. The "-quiet " flag can be used to suppress console output. The "-verbose" flag can be used to print all messages to the console. This is useful for printing error messages. The flag "-ooc" can be used to load a design "out_of_context". The required filename parameter specifies the TCP to load into Vivado.

remove_speedgrade()

tincr::remove_speedgrade			partname

Removes the speedgrade on the specified part

Parameters

partname

Full name of the part

Returns

The partname with the speedgrade removed

report_cell_placement_info()

tincr::report_cell_placement_info			cell

Prints the placement information of a cell to standard out in the following format:
(1) sitename/belname ; what bel the cell is placed on
(2) cellpin1 belpin1 belpin2 ; the cell pin to bel pin mappings for a cell pin
(3) cellpin2 belpin1 belpin2 ;
...

This function is used to verify that a cell has been imported into RapidSmith correctly.Used for testing that cell of a design have been imported correctly

Parameters

cell	Name of the cell to

report_gnd_routing_info()

tincr::report_gnd_routing_info

Prints the wires, cell pins, and bel pins of ALL GND nets in the currently opened design The output format is the same as ::tincr::get_physical_net_info

report_physical_net_info()

tincr::report_physical_net_info			net

Prints the wires, cell pins, and bel pins of the net to standard out in the following format:

"wire1 wire2 ... \n"
"pin1 pin2 ... pin3"
"belpin1 belpin2 ... belpin3"

This function is used to verify that a net has been imported correctly into RapidSmith

report_property_values()

tincr::report_property_values			cell property_list

Prints the values of the properties in

property_list 

for the specified cell. The properties are printed in the following format:
"propertyName1 propertyValue1\n"
"propertyName2 propertyValue2\n"
...

This function is used to verify cell properties in RapidSmith

Parameters

cell	Name of a cell
property_list	list of property names

report_runtime()

tincr::report_runtime			cmd ?format?

Format a string so that it is valid XML. This replaces illegal characters with their proper entity references. This function is implemented as an alias of a string map function.

report_used_site_count()

tincr::report_used_site_count

Returns the number of used sites in the currently opened design

report_used_site_pips()

tincr::report_used_site_pips			site

Prints the used site pips for the specified site to standard out This function is used to verify that site pips in RapidSmith were imported correctly.

Parameters

site	Name of a site

report_vcc_routing_info()

tincr::report_vcc_routing_info

Prints the wires, cell pins, and bel pins of ALL VCC nets in the currently opened design The output format is the same as ::tincr::get_physical_net_info

reset_configuration()

tincr::reset_configuration			cell config_list

Resets the specified configuration of the cell to their default.

Parameters

cell	Cell instance
config_list	List of configurations to reset

reset_tcl_display_limit()

tincr::reset_tcl_display_limit

Resets the tcl display limit to the default of 500

run_rapidsmith_command()

tincr::run_rapidsmith_command			cmd

Executes a command send from a running instance of RapidSmith. The "rs_start" and "rs_end" are used to communicate with RapidSmith when the command has started or completed.

set_tcl_display_limit()

tincr::set_tcl_display_limit			limit

Sets the tcl standard out display limit. Passing in 0 will disable the tcl display limit completely.

Parameters

limit

tcl display limit. default is 500

sort_cells_for_export()

tincr::sort_cells_for_export			cells

Sorts the cells of SLICE sites in the the order that is required to import the design successfully.

Parameters

cells

List of cells to sort

Returns

A list of sorted cells

suffix()

tincr::suffix			string token

Splits the string by token, and returns the last element in the list. Helper function used to get the relative name of Vivado elements. For example, the call suffix "I/am/a/test" "/" will return the string "test."

Parameters

string	The string to split
token	The token to split the string on

test_cell_library()

tincr::test_cell_library			?part?

Function to test the create_xml_cell_library function with assertions and debugging enabled.

Parameters

part	Xilinx FPGA part

test_default_cell()

tincr::test_default_cell			cell

Tests that a the specified cell has only the default values for each configurable property This function is used to verify that cells in RapidSmith with no properties have all default properties.

Parameters

Name

of a cell

test_port_placement()

tincr::test_port_placement			port expected_port_loc

Tests that the placement of the port with the given name matches the expected port placement

Parameters

port	Name of the port to test
expected_port_loc	expected site location of the port

test_routethrough()

tincr::test_routethrough			bel expected_inpin expected_outpin

Tests if the specified bel is a routethrough under a certain configuration. Specifically, this function checks that [get_property CONFIG.EQN]="(expected_outpin)=(expected_inpin)"

Parameters

bel	Name of a bel
expected_inpin	Expected input pin of the routethrough
expected_outpin	Expected output pin of the routethrough

Returns

1 if the bel matches the expected pattern, 0 otherwise

test_static_sources()

tincr::test_static_sources			bel

Test that the specified Bel is a static source bel (i.e. the configuration equation is 0 or 1).

Parameters

bel	Name of a bel

Returns

1 if the bel is a static source, 0 otherwise

write_design_info()

tincr::write_design_info			args

Creates the "design.info" file of a RSCP.

USAGE: tincr::write_design_info [ooc] filename

Parameters

args	Argument list shown in the usage statement above. The optional parameter "ooc" is used to output the mode of the design. The filename parameter is the name for the generated design.info.

write_gnd_primitive_def()

tincr::write_gnd_primitive_def			directory

Creates a "GND.def" primitive definition for use in Ultrascale and later devices. This site does not actually exist on ultrascale parts, but is needed to create more accurate device descriptions.

Parameters

directory

Directory to create the "GND.def" file in

write_macro_xml()

tincr::write_macro_xml			macro outfile

Generates an XML cell-specification for the specified Macro cell.

Parameters

Macro	cell instance
outfile	XML file handle

write_macros()

tincr::write_macros			?filename?

Looks for macro cells in the design that aren't in the list of cells returned from the function call "get_lib_cells", and writes the cell library XML for these cells. TODO: add caching to this

Returns

A dictionary that maps macro cell type, to the internal nets of the macro These nets need to be included in the routing.rsc checkpoints

write_partial_primitive_def()

tincr::write_partial_primitive_def			site filename ?includeConfigs?

Produce a partial .def file for the given primitive site. All config strings will be put inside of bel elements. For Single Bel Sites (Sites where one BEL has over 80% of all bel pins in the site), some connections will be automatically inferred and generated.

Parameters

site	The site object you want to create a .def file for. Sites instanced by alternate types are acceptable.
filename	The output file.
includeConfigs	A boolean telling the proc whether or not to include configuration elements in the resulting .def file.

write_placement_rs2()

tincr::write_placement_rs2			?filename?

Creates the "placement.rsc" file within a RSCP. This contains all placement information about a design including:

• Cell to BEL mappings
• Cell pin to BEL pin mappings
• Top-level port placement
• Internal cell properties

Parameters

filename

The name of the placement checkpoint file, "placement.rsc" is the default.

write_placement_xdc()

tincr::write_placement_xdc			args

Writes a "placement.xdc" file for a TCP. This contains all placement information or a design.

Deprecated:

This function is no longer used to represent placement. See tincr::write_placement_rs2 instead.

write_primitive_defs()

tincr::write_primitive_defs			args

Appends all primitive defs of the current part to the end of a specified file.

Parameters

filename	Where to write the primitive definitions.
part	Part to generate the primitive definitions for.
append	Append to the existing file.

write_routing_rs2()

tincr::write_routing_rs2			args

Creates the "routing.rsc" file within a RSCP. This file includes:

• Used site pips for each site
• Pips in each net
• Site pins attached to each net
• BEL Routethroughs
• Static Source BELs
• Merged VCC/GND net information

USAGE: tincr::write_routing_rs2 [-global_logic] filename

Parameters

args

Argument list shown in the usage statement above. The flag "-global_logic" is used to include VCC and GND routing. The parameter "filename" is the name of the file to write the routing information to. The parameter "internal_net_map" is a list of internal macro nets so the routing information for these nets can be exported.

write_routing_xdc()

tincr::write_routing_xdc			args

Writes a "routing.xdc" file for a TCP. This contains all routing information for a design.

Deprecated:

This function is no longer used to represent routing. See tincr::write_routing_rs2 instead.

write_rscp()

tincr::write_rscp			args

Generates a RSCP. RSCPs are an external representation of a Xilinx design which can be used to reconstruct Vivado designs in external CAD tools. The format of RSCPs are extensively documented in the RapidSmith2 tech report found at https://github.com/byuccl/RapidSmith2/tree/master/doc and Thomas Townsend's Masters Thesis.

USAGE: tincr::write_rscp [-quiet] [-ooc] filename.rscp

args Argument list as defined above. The flag "-quiet" can be used to suppress console output. The flag "-ooc" needs to be set for designs implemented "out-of-context". The filename parameter is the name for the generated RSCP.

write_tcp()

tincr::write_tcp			filename

Writes a Tincr checkpoint to file. A Tincr checkpoint is able to store a basic design, its placement, and routing in a human-readable format. consists of five files: an EDIF netlist representation and XDC files that constrain the placement and routing of the design. Currently, designs with route-throughs are not supported, though this functionality is planned for a future release of Tincr.

Deprecated:

This function is no longer used to represent external Vivado designs. See tincr::write_rscp instead.

Parameters

filename

The path and filename where the Tincr checkpoint is to be written.

write_vcc_primitive_def()

tincr::write_vcc_primitive_def			directory

Creates a "VCC.def" primitive definition for use in Ultrascale and later devices. This site does not actually exist on ultrascale parts, but is needed to create more accurate device descriptions.

Parameters

directory

Directory to create the "VCC.def" file in