config_ip_cache - 2020.2 English

Manage the IP instance Synthesis cache. Lists out the IP Cache entries if no options are specified.

Syntax

config_ip_cache [‑use_cache_location <arg>] [‑use_project_cache]
    [‑disable_cache] [‑clear_output_repo] [‑clear_local_cache]
    [‑cache_has_match] [‑cache_was_used] [‑get_id]
    [‑get_entry_location <arg>] [‑remove] [‑vlnv <arg>] [‑old_swvers]
    [‑unused] [‑swver <arg>] [‑num_days_old <arg>] [‑num_days_unused <arg>]
    [‑obs_synth_crc] [‑disk_usage_output_repo] [‑report] [‑rptfile <arg>]
    [‑csvfile <arg>] [‑zip_cache <arg>] [‑import_from_project]
    [‑filter <arg>] [‑regexp] [‑nocase] [‑purge] [‑quiet] [‑verbose] [<ip>]

Usage

Name	Description
`[-use_cache_location]`	Set current project properties to use the specified cache location
`[-use_project_cache]`	Set current project properties to use the default project IP cache location
`[-disable_cache]`	Disable cache use.
`[-clear_output_repo]`	Delete from disk and in memory all cache entries that exist in the current project's designated cache (local or remote).
`[-clear_local_cache]`	Delete from disk and in memory all local cache entries for this project.
`[-cache_has_match]`	Returns the cache-ID of the cache entry that would work for this IP instance; else ''.
`[-cache_was_used]`	Returns '1' if the cache was used to obtain the IP's current synthesis results; else '0'.
`[-get_id]`	Calculate and return IP cache ID string for specified <ip>
`[-get_entry_location]`	Return directory where this cache-ID entry is located.
`[-remove]`	Remove the corresponding cache entry for the specified IP instance or specified cachedInst; return cache ID string if successful, otherwise blank.
`[-vlnv]`	Used with -purge or -get_resource_data, specifies the VLNV of the cache entries to delete or find. May use a wildcard ('*') in one or more fields in the VLNV.
`[-old_swvers]`	Used with -purge to delete cache entries created with old Vivado SW Versions.
`[-unused]`	Used with -purge to delete cache entries that have never been used.
`[-swver]`	Used with -purge to delete any cache entries created from this specific Vivado SW Version (i.e., '2017.1').
`[-num_days_old]`	Used with -purge to delete any cache entries that are this number of days old or older.
`[-num_days_unused]`	Used with -purge to delete any cache entries that have not been used for this number of days or longer.
`[-obs_synth_crc]`	Used with -purge to delete cache entries whose component synth checksum is not the same as the IP Catalog's current component synthesis checksum.
`[-disk_usage_output_repo]`	Return total disk usage in MB for all cache entries in the current project's ip_output_repo.
`[-report]`	Report cache statistics for the specified IP or cache object, or for the current cache location if none specified. If -rptfile is specified, write statistics to that file. If -dir is specified, write statistics for cache entries found under that directory.
`[-rptfile]`	Used with -report, specifies the text file to write the cache statistics to.
`[-csvfile]`	Used with -report, specifies the csv file to write the cache statistics to, in csv format.
`[-zip_cache]`	Zip up all cache entries used by the current project and write to the given filename.
`[-import_from_project]`	Import existing synthesized IP from the project into the cache.
`[-filter]`	Filter result of '-list'
`[-regexp]`	Use regular expressions instead of globs in '-filter' argument(s)
`[-nocase]`	Use case insensitive matching in '-filter' argument(s)
`[-purge]`	Delete all cache entries that match the specified type(s): -vlnv, -obs_swvers, -obs_synth_crc, and/or -swver. Returns the number of entries deleted.
`[-quiet]`	Ignore command errors
`[-verbose]`	Suspend message limits during command execution
`[<ip>]`	IP instance object, IP file, or IP name pattern

Description

This command lets you manage the Vivado Design Suite out-of-context (OOC) IP cache. The Vivado Design Suite caches the synthesis results for customized OOC IP in an IP repository, so multiple IP that use the same customization profile can share OOC synthesis results to decrease run time. The cached synthesis results can be reused in a single project from the project cache, or across multiple projects using a remote cache location.

When generating the synthesis output products for an OOC IP, if a matching IP customization is found in the IP repository, the cached synthesis results will be used. If no suitable match is found in the IP repository, the synthesis output products will be generated as usual and the results, including the design checkpoint (DCP), will be copied into the IP synthesis cache for future use.

Tip: When cached results are used, an information message is displayed in the Tcl console indicating the IP cache location used.

You can specify a repository of cached IP synthesis results either within the current project, or at an external location. The location of the IP cache is defined by the IP_OUTPUT_REPO property on a project, with the value of a string defining a valid file system directory. You can set this property using the check_ip_cache command with either the -use_cache_location or the -use_project_cache options. The default IP synthesis cache location is in the current project folders.

The use of the IP synthesis cache is controlled by the IP_CACHE_PERMISSIONS property that can be set with the set_property command. The current values are:

disabled - Do not use the IP synthesis cache. This is the default setting.
read - Use the IP synthesis cache to read OOC synthesis results from and apply as appropriate in the current project.
write - Use the IP synthesis cache to write OOC synthesis results into, but do not use them to read IP into the current project.
read write - Use the IP synthesis cache for both writing results to, and using those results in the current project.

The config_ip_cache command should be followed by the update_ip_catalog command to read the specified IP cache repository into the Vivado tool.

Tip: The IP synthesis cache can be enabled, and the cache repository specified, in the Vivado Design Suite IDE using the Settings dialog box. Refer to the Vivado Design Suite User Guide: Designing with IP (UG896) for more information on using the cache.

By default, without any of the arguments specified below, the config_ip_cache command returns a list of entries in the IP synthesis cache, or returns an error if it fails.

Arguments

-use_cache_location <arg> - (Optional) Specify an external directory to use for the IP cache repository in the current project.

-use_project_cache - (Optional) This is the default behavior of the cached IP synthesis results. This option enables the current project to use the default IP cache location inside the local project directory. You can use this option to restore the default.

-disable_cache - (Optional) Disable the IP synthesis cache. This has the effect of setting the IP_CACHE_PERMISSIONS property to "disabled".

Tip: After disabling the cache, you will need to set the IP_CACHE_PERMISSIONS property, or use the Vivado Design Suite IDE to re-enable the cache.

-clear_output_repo - (Optional) This clears the IP synthesis cache of all existing cached results, whether the cache is local to the project or a remote directory that is shared across multiple projects.

CAUTION:

You will not be prompted to confirm this command before the cached results are deleted.

-clear_local_cache - (Optional) This clears the IP synthesis cache of all existing cached results, but only if it is local to the current project.

-cache_has_match - (Optional) Queries the IP cache against the specified IP and returns the Vendor:Library:Name:Version (VLNV) identifier of the IP in the cache if there is a match.

-cache_was_used - (Optional) Queries the IP cache against the specified IP and returns TRUE if the cache entity was used during synthesis.

-get_id - (Optional) Returns the ID string for the cached IP from the repository that is used for the specified <ip> object in the current project. The ID for the cache entity is the 'N' portion of the VLNV value.

-remove - (Optional) Remove entries from the current IP cache for IP cores specified by the get_ips command.

-purge - (Optional) Purge specific entries from the current IP cache. The specific entries are provided by the following options:

-vlnv <arg> - (Optional) Purge the specified IP as defined by the Vendor:Library:Name:Version (VLNV) identifier. The specified VLNV may use a wildcard '*' for any field in the VLNV.
Tip: The VLNV is the IPDEF property on individual IP.
-swver <arg> - (Optional) Purge any cache entries created by a specified software version. The software version can be specified as <version>.<revision>, for example 2017.2.
-old_swvers - (Optional) Purge any cache entries created by an older software version than the one currently in use.
-unused - (Optional) Purge cache entries that have never been used.
-num_days_old <arg> - (Optional) Purge any cache entries older than the specified number of days.
-num_days_unused <arg> - (Optional) Purge any cache entries that have not been used for the specified number of days.
-obs_synth_crc - (Optional) Purge any cache entries that were generated with the component's synthesis checksum that is different from the checksum found in the current IP catalog's component.

-disk_usage_output_repo - (Optional) Reports the disk usage of the IP synthesis cache in KBytes.

-report - (Optional) Generates a report of the IP cache including the IP represented and the number of hits on each cached entry.

-rptfile <arg> - (Optional) This option can be used with the -report option to direct the report output to the specified file name.

-import_from_project - (Optional) Populate the current IP cache with synthesis results from the current design. This can be used to populate an IP cache with the synthesis results of an existing project to be reused by other projects or design iterations.

-filter <args> - (Optional) Filter the results list with the specified expression. The -filter argument filters the results returned by config_ip_cache based on property values on the ip_cache_entry object. You can find the properties on a cached IP with the report_property or list_property commands. Any property/value pair can be used as a filter. In the case of the ip_cache_entry object, "INSTANCE_NAME", "CORE_VLNV", and "CUSTOMIZATION" are some of the properties that can be used to filter results.

The filter search pattern should be quoted to avoid having to escape special characters that may be found in net, pin, or cell names, or other properties. String matching is case-sensitive and is always anchored to the start and to the end of the search string. The wildcard “*” character can be used at the beginning or at the end of a search string to widen the search to include a substring of the property value.

Note: The filter returns an object if a specified property exists on the object, and the specified pattern matches the property value on the object. In the case of the "*" wildcard character, this will match a property with a defined value of "".

For string comparison, the specific operators that can be used in filter expressions are "equal" (==), "not-equal" (!=), "match" (=~), and "not-match" (!~). Numeric comparison operators <, >, <=, and >= can also be used. Multiple filter expressions can be joined by AND and OR (&& and ||). The following gets input pins that do NOT contain the “RESET” substring within their name:

get_pins * -filter {DIRECTION == IN && NAME !~ "*RESET*"}

Boolean (bool) type properties can be directly evaluated in filter expressions as true or not true:

-filter {IS_PRIMITIVE && !IS_LOC_FIXED}

-regexp - (Optional) Specifies that the search <patterns> are written as regular expressions. Both search <patterns> and -filter expressions must be written as regular expressions when this argument is used. Xilinx regular expression Tcl commands are always anchored to the start of the search string. You can add ".*" to the beginning or end of a search string to widen the search to include a substring. See http://perldoc.perl.org/perlre.html for help with regular expression syntax.

Note: The Tcl built-in command regexp is not anchored, and works as a standard Tcl command. For more information refer to http://www.tcl.tk/man/tcl8.5/TclCmd/regexp.htm.

-nocase - (Optional) Perform case-insensitive matching when a pattern has been specified. This argument applies to the use of -regexp only.

-quiet - (Optional) Execute the command quietly, returning no messages from the command. The command also returns TCL_OK regardless of any errors encountered during execution.

Note: Any errors encountered on the command-line, while launching the command, will be returned. Only errors occurring inside the command will be trapped.

-verbose - (Optional) Temporarily override any message limits and return all messages from this command.

Note: Message limits can be defined with the set_msg_config command.

<ip> - (Optional) A single IP instance object as returned by the get_ips command.

Example

This example returns the contents of the current IP cache, one cache entry per line:

join [config_ip_cache] \n

The following example specifies the use of an external IP cache location, and then updates the repository settings of the IP catalog:

config_ip_cache -use_cache_location C:/Data/ip  
update_ip_catalog

This example filters the ip_cache objects returned by the config_ip_cache command, returning the object with the specified instance name, and then reports the properties on that object:

report_property -all [config_ip_cache -filter {INSTANCE_NAME == base_mb_mdm_1_0}]

The following example disables the IP cache feature so that cached synthesis results are not used:

config_ip_cache -disable_cache

The following example gets the IP cache identifier for the specified IP core:

config_ip_cache -get_id [get_ips base_mb_mdm_1_0]  
d3e03f3ed484c174

The following example removes (purges) the IP cache entry for the specified IP:

config_ip_cache -remove [get_ips base_mb_mdm_1_0]  
config_ip_cache -purge -vlnv [get_property IPDEF [lindex [get_ips] 0 ]]

config_ip_cache - 2020.2 English

Vivado Design Suite Tcl Command Reference Guide (UG835)

Syntax

Usage

Categories

Description

Arguments

Example

See Also