Automating

Testbench Tasks
with Tcl
Webinar 7 Aug 2008

Jonathan Bromley
Senior Consultant, Doulos

As presented
Copyright at the
2004-7 by Doulos Ltd. AllWebinar,
Rights Reservedwith minor corrections to slides 9 and 10 1
Automating Testbench Tasks with Tcl

AGENDA

Why scripting?

Tcl in the Aldec simulators

Simple macros for tool flow automation

Management of testbench files

Automation of breakpoints
 Why Scripting?
Repeatability:
Compilation order is important in both VHDL and Verilog
Wrong order can give mysterious errors or wrong functionality
Run options are important

Convenience:
GUI/Project systems are fine, but...
Some users are not familiar with tool intricacies -
hide details in a script, make all users productive

Functionality - examples in this webinar:

Management of testbench input/output files -
file operations (copy, rename) are difficult or impossible in
VHDL/Verilog
Automation of breakpoints

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 3

Automating Testbench Tasks with Tcl

AGENDA

Why scripting?

Tcl in the Aldec simulators

Simple macros for tool flow automation

Management of testbench files

Automation of breakpoints
 Tcl in the Aldec Simulators
Native command language in Aldec tools is not Tcl
Tcl for programmability, manipulation of external files, ...
Tcl script must be in a file with .tcl suffix or use do -tcl

Square brackets -
Create and set a Tcl variable use result of command

Display to console

Native command "do"

Filename .tcl -
use Tcl automatically

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 5

 Quotes in Tcl
Double-quotes "..." have only one effect in Tcl:
whitespace and semicolon lose their meaning as separators

puts A_silly_string
puts A_silly_string
A_silly_string

command separator ; $ gets value of variable

puts A;
puts set AA junk;
A; set puts $A
junk; puts $A
A
junk

set AA test
set test $ works inside quotes!
puts "A;
puts "A; set
set AA junk;
junk; puts
puts $A"
$A"
A; set A junk; puts test

use braces for literal quoting

puts {the $64,000
puts {the $64,000 question}
question}
the $64,000 question
Copyright 2004-7 by Doulos Ltd. All Rights Reserved 6
Automating Testbench Tasks with Tcl

AGENDA

Why scripting?

Tcl in the Aldec simulators

Simple macros for tool flow automation

Management of testbench files

Automation of breakpoints
 Simple Flow Automation Macros
Tcl script (macro) replaces repetitive GUI or command-line actions

all simulator commands available

simulator variables are visible in Tcl

alib my_library
alib my_library
set worklib my_library
set worklib my_library
vlog
vlog webinar_Tcl/dut/fsm.v
webinar_Tcl/dut/fsm.v
vlog
vlog webinar_Tcl/testbench/vector_fsmtf.v
webinar_Tcl/testbench/vector_fsmtf.v
asim
asim vector_fsmtf
vector_fsmtf
Linux-style filenames
even when using Windows

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 8

 Lists and foreach
Do the same thing to each item in a list
central, single list of files - easier to maintain

create a variable containing a list braces enclose list

set source_file_list
set source_file_list {{
newline or space
webinar_Tcl/dut/fsm.v
webinar_Tcl/dut/fsm.v separates list elements
webinar_Tcl/testbench/vector_fsmtf.v
webinar_Tcl/testbench/vector_fsmtf.v
}}
list to scan - use $
scan the list foreach
foreach source
source $source_file_list
$source_file_list {{
vlog
vlog $source
$source
braces enclose code
}}
loop variable -
note use of $

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 9

 Manipulating Filenames
Tcl has a rich set of operations on filenames and files
Often easier than native operating-system commands
Completely portable across platforms (Windows/Linux)

set
set source_file
source_file webinar_Tcl/dut/fsm.v
webinar_Tcl/dut/fsm.v Linux-style filenames

puts
puts [file normalize $source_file]
[file normalize $source_file] get absolute pathname
/home/verilog0/webinar_Tcl/dut/fsm.v

get pathname without last (file) part

set
set source_dir
source_dir [file dirname $source_file]
[file dirname $source_file]
puts
puts [file join $source_dir
[file join $source_dir other.v]
other.v] build pathname from pieces
webinar_Tcl/dut/other.v

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 10

 Manipulating Files
Directory lookup, copy, rename, delete....
Read and write files

set
set vectors_file
vectors_file webinar_Tcl/vectors.txt
webinar_Tcl/vectors.txt
file copy $vectors_file
file copy $vectors_file temp.txt
temp.txt copy the file

set
set f_id
f_id [open
[open user.txt
user.txt w]
w] open file for writing
puts $f_id "Using
puts $f_id "Using $vectors_file"
$vectors_file" write one line to file
close $f_id
close $f_id close the file

move file to
file rename user.txt
file rename user.txt webinar_Tcl/user.txt
webinar_Tcl/user.txt
another directory

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 11

 Getting System Information
All environment variables are visible to Tcl through variable env:

puts
puts $env(LM_LICENSE_FILE)
$env(LM_LICENSE_FILE)
1700@artemis

Current working directory available through command pwd:

puts
puts [pwd]
[pwd]
/home/verilog0

Some useful information available through variable tcl_platform:

puts
puts $tcl_platform(user)
$tcl_platform(user)
verilog0

env, tcl_platform are Tcl array variables - see any Tcl text for details

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 12

 Aldec Scripting: Macro Arguments
Tcl has a source command to execute other Tcl scripts:

source Cannot pass information to the

source "some_filename.tcl"
"some_filename.tcl"
sourced script

Aldec command do is similar

but supports arguments:

do show_args.tcl
do show_args.tcl First
First Second
Second

puts
puts "start
"start show_args"
show_args" show_args.tcl
puts
puts "first
"first arg
arg is
is $1"
$1" start show_args
puts
puts "second
"second arg
arg is
is $2"
$2" first arg is First
second arg is Second

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 13

Automating Testbench Tasks with Tcl

AGENDA

Why scripting?

Tcl in the Aldec simulators

Simple macros for tool flow automation

Management of testbench files

Automation of breakpoints
 Example: Simulation Control
Our project has two Verilog source files
fsm.v, vector_fsmtf.v
The testbench expects a file of test vectors vectors.txt
The testbench creates a results file results.txt both in simulator's
current directory

fdV
fdV == $fopen("vectors.txt",
$fopen("vectors.txt", "r");
"r"); Verilog testbench
if
if (!fdV)
(!fdV) begin
begin
$display("Could
$display("Could not
not open
open vectors.txt");
vectors.txt");
$stop; Verilog cannot do anything about this error
$stop;
end
end
fdR
fdR == $fopen("results.txt", "a"); Open output file
$fopen("results.txt", "a");
in append mode

Filenames hard-coded - Verilog/VHDL have poor string handling

How do we manage multiple vector files, multiple results files?

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 15

 Control (1): Locating Input Files

User chooses vectors file as an argument to the Tcl macro

## Check
Check arguments
arguments
if
if {![file
{![file exists
exists $1]}
$1]} {{
error
error "Can't
"Can't read
read vectors
vectors file
file $1"
$1" Tcl generates error
}}

set
set vectors_file
vectors_file [file
[file normalize
normalize $1]
$1]

Tcl copies the user's vector file to where Verilog can find it

file
file copy
copy -force
-force $1
$1 vectors.txt
vectors.txt copy to simulator's
current directory

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 16

 Control (2): Writing Output Data

Tcl writes useful log data to Verilog's output file

set Verilog will append to this file

set ff [open
[open results.txt
results.txt w] w]
puts $f "SIMULATION
puts $f "SIMULATION RUN"
RUN"
puts $f "" username
puts $f username :: $tcl_platform(user)"
$tcl_platform(user)"
puts $f "" vectors
puts $f vectors inin :: $vectors_file"
$vectors_file"
puts $f "" start
puts $f start time
time :: [clock format $time_now
[clock format $time_now \\
-format
-format "%Y-%m-%d
"%Y-%m-%d %H:%M"]"
%H:%M"]"
close
close $f
$f Human-readable time
Write to the file

Now run the simulation: appends data to results.txt file

asim
asim vectors_fsmtf
vectors_fsmtf
run
run Riviera commands invoked in Tcl macro

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 17

 Control (3): Saving the Output File

Tcl creates output file name based on time of day

same directory
set
set time_now
time_now [clock
[clock seconds]
seconds] as vectors file
set
set vectors_dir
vectors_dir [file
[file dirname
dirname $vectors_file]
$vectors_file]
set
set results_file
results_file [file
[file join
join \\ line continuation with \
$vectors_dir
$vectors_dir \\
"results_${time_now}.txt"
"results_${time_now}.txt" ]]

embed a variable in other text

Tcl copies Verilog's output to the chosen file

file
file copy
copy -force
-force results.txt
results.txt $results_file
$results_file
puts
puts "SIMULATION
"SIMULATION RESULTS IN $results_file"
RESULTS IN $results_file"

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 18

Automating Testbench Tasks with Tcl

AGENDA

Why scripting?

Tcl in the Aldec simulators

Simple macros for tool flow automation

Management of testbench files

Automation of breakpoints
 Example: Custom Breakpoints
Riviera has when command:
Interrupt simulation on any change of a specified signal
Useful and powerful, but needs filtering
Most transitions on a signal are not interesting

Example: In simulation, identify transitions on an 8-bit signal that are

not Gray transitions (i.e. more than one bit changes)

Easy to do in VHDL or Verilog, but

perhaps we are not willing or able to change the source code
VHDL testbench cannot probe internal DUT signals,
but the simulator can easily do so

Impractical to inspect every change of a signal manually

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 20
 Breakpoints (1): Tcl Procedures

Counting the bits in a vector is not built-in: write a function

procedure name argument variable

proc countOnes
proc countOnes {{ vector
vector }} {{
set
set nBits
nBits 00 local variable
Tcl has all the usual while
while {$vector
{$vector !=
!= 0}
0} {
{
control constructs if {$vector
if {$vector && 1} 1} {{
incr nBits
incr nBits increment a variable
}}
set
set vector
vector [expr {$vector >>
[expr {$vector >> 1}]
1}]
}} compute C-style expression
return $nBits
return $nBits
}} return the result

Call the function like any other Tcl command:

puts
puts [countOnes
[countOnes 15]
15]
4

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 21

 Breakpoints (2): when, examine

Simulator when command: execute Tcl code on a value-change

Simulator examine command: Tcl can inspect signal values
Run this code whenever DUT signal Data changes
when DUT.Data
when DUT.Data {{
set
set value
value [examine
[examine -unsigned
-unsigned DUT.Data]
DUT.Data] Get signal value in
specified radix
set
set change
change [expr
[expr {$value
{$value ^^ $oldValue}]
$oldValue}]
XOR with old value
gets changed bits
if
if {[countOnes
{[countOnes $change]
$change] >> 1}
1} {{
puts
puts "***
"*** FAIL:
FAIL: $oldValue
$oldValue ->-> $value"
$value" message to a file??
}}
set
set oldValue
oldValue $value
$value remember old value for next time
continue
continue
}} back to simulation

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 22

 Breakpoints (3): Gotcha!
A few important issues to keep in mind:

remember to initialize oldvalue at start!

set oldValue 00
set oldValue Use a variable to hold
when DUT.Data {{
when DUT.Data this signal name?
set value [examine
set value [examine -unsigned
-unsigned DUT.Data]
DUT.Data]
set change [expr
set change [expr {$value
{$value ^^ $oldValue}]
$oldValue}]
if
if {[countOnes
{[countOnes $change]
$change] >> 1}
1} {{
This code
puts
puts adds
"***several
"*** variables
FAIL:
FAIL: $oldValue
$oldValue ->
-> $value"
$value"
to the global space -
}
risk of}conflict with simulator variables
set
set oldValue
oldValue $value
$value
continue
continue
}}
run
run simulation must run within
the same Tcl environment as the when command

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 23

 Signal Breakpoints in Action

Script can locate one interesting event

among hundreds of value-changes:

Simulator message
from when breakpoint

Message output from

user's testbench

non Gray transition

Message output from

the Tcl script

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 24

 Summary
Very simple Tcl scripting can make your life easier:
consistent compilation flow
making lists of related files

Just a little more understanding of Tcl can yield big benefits:

sophisticated management of testbench vector and log files
automated interaction with other tools (revision control, ...)

Easy access to Tcl scripting in the Aldec simulators

All simulator commands and variables accessible from Tcl
Breakpoint, force, examine commands
are well suited to scripting - automate repetitive actions

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 25

Copyright 2004-7 by Doulos Ltd. All Rights Reserved 26