add_force - 2022.1 English

Vivado Design Suite Tcl Command Reference Guide (UG835)

Document ID
UG835
Release Date
2022-05-05
Version
2022.1 English

Force value of signal, wire, or reg to a specified value

Syntax

add_force [‑radix <arg>] [‑repeat_every <arg>] [‑cancel_after <arg>]
    [‑quiet] [‑verbose] <hdl_object> <values>...

Returns

The force objects added.

Usage

Name Description
[-radix] Specifies which radix to use. Allowed values are: default, dec, bin, oct, hex, unsigned, ascii, smag
[-repeat_every] Repeat every time duration
[-cancel_after] Cancel after time offset
[-quiet] Ignore command errors
[-verbose] Suspend message limits during command execution
<hdl_object> Specifies the object upon which to add a force
<values> Adds a value and time offset to the force: {value [ time_offset ] }

Categories

Description

Force the value of a signal, wire, or reg to a certain value during simulation.

The add_force command has the same effect as the Verilog force/release commands in the test bench or the module definition. It forces an HDL object to hold the specified value for the specified time, or until released by the -cancel_after option, or the remove_forces command.

Important: If there are Verilog force/release statements on an HDL object in the test bench or module, these commands are overridden by the Tcl add_force command. When the Tcl force expires or is released, the HDL object resumes normal operation in the simulation, including the application of any Verilog forces.

This command returns the name of the force object created, or returns an error if the command failed. The name of the returned force object is important when using the remove_forces command, and should be captured in a Tcl variable for later recall, as shown in the examples.

Arguments

-radix <arg> - (Optional) The radix used when specifying the <values>. Allowed values are: default, dec, bin, oct, hex, unsigned, ascii, or smag. The default radix is binary, unless the specified HDL object type has an overriding radix defined.

-repeat_every <arg> - (Optional) Causes the add_force to repeat over some specified increment of time. This can be used to create a recurring force on the specified <hdl_object>.

Note: The specified time must be greater than the time period defined by any {<value> <time>} pairs defined by <values>, or an error will be returned.

-cancel_after <arg> - (Optional) Cancels the force effect after the specified period of time from the current_time. This has the same effect as applying the remove_forces command after the specified period of time.

-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.

<hdl_object> - (Required) Specifies a single HDL object to force the value of. The object can be specified by name, or can be returned as an object by the get_objects command. Valid objects are signal, wire, and reg.

<values> - (Required) The value to force the HDL object to. A single value can be specified, and the value will be held during simulation until the force is removed either through the use of the -cancel_after option, or through the use of the remove_forces command.

The specified <value> depends on the type of the <hdl_object>. HDL object types include: "logic", floating point, VHDL enumerated, and VHDL integral. For all but "logic" the -radix option is ignored.

  • "Logic" does not refer to an actual HDL object type, but means any object whose values are similar to those of VHDL std_logic, such as:
    • the Verilog implicit 4-state bit type,
    • the VHDL bit and std_logic predefined types,
    • any VHDL enumeration type which is a subset of std_logic, including the character literals '0' and '1'.
  • For logic types the value depends on the radix:
    • If the specified value has fewer bits than the logic type expects, the value is zero extended, but not sign extended, to match the expected length.
    • If the specified value has more bits than the logic type expects, the extra bits on the MSB side should all be zeros, or the Vivado® simulator will return a "size mismatch" error.
  • Accepted values for floating point objects are floating point values.
  • The accepted value for non-logic VHDL enumerated types is a scalar value from the enumerated set of values, without single quotes in the case of characters.
  • Accepted values for VHDL integral types is a signed decimal integer in the range accepted by the type.

The <value> can also be specified as {<value> <time>} pairs, which forces the HDL object to hold a specified <value> for a specified period of <time> from the current time, then hold the next <value> for the next period of <time>, until the end of the {<value> <time>} pairs.

Note: In {<value> <time>} pairs, the <time> is optional in the first pair, and will be assumed to be 0 if it is not specified. In all subsequent {<value> <time>} pairs, the <time> is required.
The <time> specified in {<value> <time>} pairs is defined relative to the current simulation time, and indicates a period of time from the current_time. For example, if the current simulation time is 1000 ns, a <time> of 20 ns defines a period from the current time to 1020 ns.
Important: The <times> must be specified in increasing order on the simulation time line, and may not be repeated, or an error will occur.

The <time> is specified in the default TIME_UNIT of the current simulation, or can be specified with the time unit included, with no white space. Valid units of time are: fs, ps, ns, us, ms, or s. A time of 50 defines a period of 50 ns (the default). A <time> of 50ps defines a period of 50 picoseconds.

Examples

The following example forces the reset signal high at 300 nanoseconds, using the default radix, and captures the name of the returned force object in a Tcl variable which can be used to later remove the force:
set for10 [ add_force reset 1 300 ]
The following example shows the use of {<value> <time>} pairs, repeated periodically, and canceled after a specified time.
add_force mySig {0} {1 50} {0 100} {1 150} -repeat_every 200
   -cancel_after 10000
Note: In the preceding example, the first {<value> <time>} pair does not include a time. This indicates that the specified value, 0, is applied at time 0 (the current_time).