InTime Tcl Reference

This reference guide describes the InTime Tcl language. It is derived from Tcl/tk and uses similar syntax, notations and design rules. It is not intended as a tutorial. The list of commands can be displayed in the InTime Tcl console by typing help. The commands generally organized hierarchically and can consist of several consecutive command invocations. Commands are also variadic, as per Tcl.

Examples

Multiple commands To retrieve the project filename, three commands are required, project and info, followed by <file_name>

plunify> project info file_name

Multiple commands with an argument To retrieve a summary of the job, two commands are required, job and summary, followed by jobID=2

plunify> job summary 2

For more example scripts, please refer to Using Tcl Scripts.

Top-level Commands

Typing the top-level command in the tcl console will display the list of secondary commands. For example, typing flow will give you a list of commands under flow.

Commands Description
exit Exit InTime
flow Control and execute the InTime flow
flow_steps Allows execution of individual steps in the InTime flow
help Displays this help message
history Shows the commands history
job Operations on existing jobs
license License management functions and displays the current license file for InTime.
log <message> <type> Send specific log messages to the InTime session log. Example: log something failed error
Supported types: <info>, <warning>, <error>
misc Miscellaneous helper functions
project Details and control of the open vendor project
project info A subset of the project command. It returns information about the project. Used together with the Project command
results Provides details about the current results set
run_target Operations to configure, test and perform actions specific to different run targets
strategy Provides details of the currently active strategy/result
vendors Allows configuration of vendor tool settings
msgbox (Deprecated) Show or get feedback from user using a message box

FLOW

Control and execute the InTime flow To use this command,

Argument Description
add <property_name> <value> Add the value into certain flow property
clear <options> Clears the value of strategy_custom or strategy_export_impl,synth_name or strategy_prefix.
Supported options: <strategy_custom> <strategy_export_impl_name> <strategy_export_impl_name> <strategy_prefix>
get <property_name> Gets the value of a flow property.
properties List and describe all customizable configuration properties of the flow.
recipe errors Prints all errors logged during the execution of the last run recipe.
recipe is_experimental <recipe_tcl_alias> Indicates if <recipe_tcl_alias> is an experimental recipe.
recipe is_supported <recipe_tcl_alias> Indicates if <recipe_tcl_alias> is supported by the open project.
recipe is_user_defined <recipe_tcl_alias> Indicates if <recipe_tcl_alias> is an user defined recipe.
recipe stopped Returns true if a stop request from the user has been achieved during the execution of the last run recipe.
recipes <supported,all> Returns a list of recipe tcl aliases. By defaults, it lists only supported recipes for the vendor. Use flow run_recipe <recipe_tcl_alias> to run a recipe.
remove <property_name> <value> Remove the value of certain flow property
rerun Reruns marked strategies.
reset Resets the internal flow history. Subsequent flows will start again with a root parent revision.
restore_defaults Restores the default flow properties to their defaults.
restore_point load <name> Restores the flow configuration from the given restore point.
restore_point save <name> Creates a restore point with the given name.
run Runs the InTime flow: Analyze design, strategize and run generated strategies.
run_recipe <recipe_tcl_alias> Runs the specified recipe.
set <property_name> <value> Sets the value of a flow property.
toolchain_steps clear_custom Clears any previously set custom step.
toolchain_steps clear_custom_args Clears any previously set custom step arguments.
toolchain_steps get_custom Gets the custom toolchain step to use.
toolchain_steps get_custom_args Gets the arguments to use for the custom toolchain step.
toolchain_steps is_custom_supported Indicates if the current vendor backend supports custom enabling/disabling of toolchain steps.
toolchain_steps list <match_expr> Returns a list of toolchain steps. Possible match expressions: <all,enabled,disabled>. Default: <all>.
toolchain_steps set_custom <custom_step_name> Sets the custom toolchain step to use.
toolchain_steps set_custom_args <args> Sets the arguments to use for the custom toolchain step.
toolchain_steps toggle <step_name,all> <enable, disable> Enables/disables the specified toolchain step, or all steps.

FLOW_STEPS

Allows execution of individual steps in the InTime flow.

Argument Description
analyze_parent_revision Analyze the parent revision of the open vendor project.
download_results Download outstanding results for the current job.
finalize_job Finalizes the current job.
generate_strategies Generate a set of goal orientated strategies and apply them to the open vendor project.
initialize_job Initializes a new job.
learn Learn from the results in the current result set and tag outcome with current job id.
post_recipe_analysis Performs analysis on all results generated during the last recipe.
prepare_training_data Analyze the runs database and fill active result set with data required for learning.
run_strategies Runs all strategies generated using flow_steps generate_strategies.

JOB

Operations on existing jobs

Argument Description
cancel <remote_job_id> <run_target> Cancels the specified remote job.
summary <local_job_id> Download outstanding results for the current job.

LICENSE

License management functions and displays the current license file for InTime.

Argument Description
details Displays details about the current license file registered for InTime (if any).
file_name Returns the file name of the current registered license file for InTime (if any).
register <license_file> Registers a new license file for InTime.
reset Unregisters the current license file for InTime (if any).
run_target <run_target> Checks if the specified run target is available under the current license.

MISC

Miscellaneous helper functions

Argument Description
examples_path <toolchain> Returns the path where example projects are extracted to by default. The toolchain is optional.
exec <R,perl> <script_file_path> args <arguments>
exec_mode Returns the execution mode of InTime.
Possible values: <console>, <batch>, <gui>.
find_path <options> Returns the directory where the files below are saved. Usage: To find out the path where recipes are saved misc find_path recipes
Possible options: <scripts> <recipes> <user_recipes> <intime_log> <user_home> <dot_plunify> <dot_plunify_user> <session_tmp_dir> <project_dir> <runs_db>
printenv Prints the active process environment.
produce_settings_analysis_data <search_dir> <base_revision_name> Produces settings analysis graph data from the results xml and settings csv files in search_dir.
set_path <user_recipes> <new_path> Sets the specified path.
set_stdout <level> Controls messages forwarded to stdout when running in tcl/batch modes. Supported levels: <all> <tcl>
settings get <scope> <key> nofail
settings set <scope> <key> <value> Set the value of a key in the ini file. Supported scopes: <global> <user>.
set user_args <value> Set the USER_ARGS value.
set runs_db <value> Change the runs database to use project mode or user mode.
Possible values: <project>, <user>.
get runs_db Show the active mode of the runs database.

PROJECT

Details and control of the open project.

Argument Description
clear_history Clears the complete history of all jobs that have been run on the current project for your InTime runs database.
close Closes the open vendor project file.
exec <command> Executes <command> using the active project\'s vendor shell.
extract <archive> <dest_dir> -toolchain <toolchain> -toolchain_version <toolchain_version> -overwrite Extracts the vendor archive to the directory specified.
history Prints a history of all jobs that have been run on the current project.
info <options> Please refer to info command.
is_open Returns 1 if a project is currently open, 0 otherwise.
open <project_file> -toolchain <toolchain> -toolchain_version <specific version,from_last_session> Opens the specified vendor project file. The -toolchain argument is required for certain projects. The -toolchain_version argument is optional.
open_dir <project_dir> -toolchain <toolchain> -toolchain_version <specific version, from_last_session> Searches for a known project file in the specified path, and if found opens it. The -toolchain argument is required for certain projects. The -toolchain_version argument is optional.
open_example <toolchain> <dest_dir> -overwrite Extracts and opens an example for the specified toolchain, the dest_dir is optional. Supported toolchain values: QuartusII,QuartusPP,ISE,Vivado,Vivado_dcp,Vivado_tcl,Vivado_xpr
open_last Opens the previously opened project
setting_filters List all settings in the open project\'s specified setting filters.
setting_filters <type> add <setting_name> <value> -step <step> Adds the specified setting to the specified list, with <value> being optional (except for locklists).
setting_filters <type> clear Clears the specified settings filter.
setting_filters <type> contains <setting_name> <value> -step <step> Checks if specified setting is contained in the specified list, with <value> being optional (except for locklists).
setting_filters <type> remove <setting_name> <value> -step <step> Removes the specified setting from the specified list, with <value> being optional (except for locklists).
setting_filters apply_template <file_path> Applies the setting filters from the specified setting filters template. Template is applied to project\'s current setting filters, clear first to load template as is.
setting_filters available_settings Lists all settings which can be used in the settings filter for the open project.
setting_filters clear <all, id_only, id_value_only> Clears all setting filters in the open project. Defaults to all.
setting_filters load_template <file_path> Clears the project\'s existing setting filters and load template as is.
setting_filters save_template <file_path> Saves the current setting filters to a setting filters template.
setting_filters verify

PROJECT INFO

Returns information about the project. This is to be used with the Project command, e.g. project info

Argument Description
all_job_ids Returns a list of all previously ran job ids on this project.
default_revision Returns the default revision in the open vendor project.
device <family,package,speed,part> Returns the current project\'s device details.
directory Returns the directory of the open vendor project.
file_name Returns the project file path of the open vendor project.
find_shadowed_result_job_id <strategy_name> <job_id> Returns the shadowed result\'s job id for the given result id.
first_job_id Returns the job id of the first job ran on this project.
last_job_id Returns the job id of the last job ran on this project.
local_to_remote_job_id <job_id> Returns the remote job ID for the specified local job ID.
name Returns the name of the open vendor project.
next_job_id <ref_job_id> Returns the job id of the next job after the specified <ref_job_id> ran on this project.
previous_job_id <ref_job_id> Returns the job id of the previous job before the specified <ref_job_id> ran on this project.
private_cloud_worker_path Returns the directory of the private cloud worker job path.
remote_to_local_job_id <job_id> Returns the local job ID for the specified remote job ID.
revisions Returns a list of all revisions in the current project.
toolchain The toolchain of the open vendor project (always returned as lowercase).
toolchain_version The toolchain version of the open vendor project.
vendor The vendor of the open vendor project (always returned as lowercase).

RESULTS

Provides details about the current results set

Argument Description
activate_tcl_set <set_name> Activates specified results set for future Tcl commands.
add all Adds all results in the runs database to the current result set.
add job <job_id> <run_target> -r Adds the results of a specific job to the current results set. The run target defaults to <local>. Add
add last_job Adds the results of the last job to the current results set.
add project_history Adds all results in the current project history to the current result set.
add single <strategy_name> <job_id> Adds the single result specified to the current results set.
add training_data Adds all results in the runs database matching the training data filter to the current result set.
count_duplicates <local_job_id> -r Counts the number of duplicate strategies inside the specified job.
current_tcl_set_name Returns the name of the current Tcl set name.
download <job_id> <run_target> <-wait> <-overwrite> Gets the results of the job specified by <job_id> and <run_target>. With -wait, it will wait for the remote job to complete if it is still busy. With -overwrite it will download the results even if it is available locally. This action will overwrite values in the database with the downloaded values and the chosen job and this process is irreversible.
epaf_download <remote_job_id> Gets the epaf files <remote_job_id>
export <filename> Exports all results in current results set to the specified file in CSV format.
goal_met Returns 1 when the goal was met within the current results set, 0 otherwise
import job_dir <job_dir> <parent_revision_name> Imports and create a new job with all results in specified directory. <parent_revision_name> specifies which of the found revisions must be the parent of the new job.
import remote_job <remote_run_target> <remote_job_id> <parent_revision_name> Imports and create a new job with all results from specified remote run target.
Possible remote run target values: <plunify_cloud> <parent_revision_name> specifies which of the found revisions must be the parent of the new job.
package_logs <log_path> Archives the session log, job logs and revision logs in the current results set to intimelogs_yyyy
remove all Remove all results from the current results set.
remove job <job_id> <run_target> -r Removes the results of a specific job from the current results set. The run target defaults to <local>. Add -r to remove results recursively.
restore_default_tcl_set Restores the results set used for Tcl commands to the result set linked to the InTime user interface.
summary <match_expr> <detail_level> <type> <metric> <jobs_id> Lists results in the current results set that match the match expression.
Supported match expressions: all, best, best_including_estimates, busy, failed, not_started, pending, stopped, success, top3, top10, worst, worst_including_estimates (Default: all).
Supported detail levels: -brief, -count, -errors, -list, -preview, -verbose (Default: -brief).
Supported types: -all_types, -leaf, -parent, -root (Default: -all_types).
Supported metric: wns, tns, area, power (Default: goal value)
Supported jobs_id: -jobs

RUN_TARGET

Used for configuring and testing run_target. Available run targets: <local> <private_cloud> <plunify_cloud>

Argument Description
set <run_target> <parameter> <value> Tests the configuration of remote run targets.
test_connection <run_target> Tests the configuration of remote run targets.

STRATEGY

Provides details of the currently active strategy/result

Argument Description
export <target_file> <options> Exports the specified information for this strategy.
Supported options: -results_csv, -script_tcl, -summary_xml
results <options> Provides details about the results in this strategy. Default is -brief.
Supported options: -brief, -verbose, -errors, -field Field Name
set_active <revision_name> <job_id> Opens the specified strategy, setting it as the active strategy for all other strategy commands.
settings <options> Provides details about the settings in this strategy. Default is -all.
Supported options: -all, -non_default, -default, -list_all, -list_non_default, -list_default, -count
tag remove Removes a tag from an active strategy
tag set <tag_value> Adds a tag to an active strategy
unset_active Unsets whatever strategy was previously set with the set_active command.

VENDORS

Allows configuration of vendor tool settings. Example:

vendors auto_detect
Argument Description
auto_detect Auto-detect vendor toolchains installed on this machine.
current_path Returns the installation path of the toolchain version of the open vendor project.
current_toolchain Returns the toolchain for the open vendor project.
current_vendor Returns the vendor for the open vendor project.
current_version Returns the toolchain version of the open vendor project.
enable_vendor_backend <vendor_name> <vendor_toolchain> <project_directory> Enables the specified vendor backend for vendor specific operations even when a vendor project is not open.
fetch_global_config <-force> Fetches toolchains configured in the current InTime private cloud environment.
get_default <vendor> <toolchain> Gets the default version to use for the specified vendor toolchain.
register <vendor_name> <toolchain> <install_path> <license_file> -category <category> -version <version> Registers a new vendor configuration. If no <toolchain_version> is provided, the version will be auto-detected.
set_default <vendor> <toolchain> <default_version> Sets the default version to use for the specified vendor toolchain.
summary Prints a summary of all configured vendor environments.
unregister -all Unregisters all existing vendor configurations.
unregister <vendor_name> <toolchain> <toolchain_version> Unregisters an existing vendor configuration.
update <install_path,license_file,category> <vendor_name> <toolchain> <toolchain_version> <new_value> Updates the install or license file path of a registered environment.
versions <vendor> <toolchain> Returns a list of all registered versions for the specified vendor toolchain.