Man Page ats.1
NAME
ats - Automatic Tuning and Troubleshooting System
SYNOPSIS
ats [-build command]... [-c command] [-cc dir] [-d]
[-distr[ibute]] [-distr_cmd command] [-h]
[-i options]... [-ias] [-keepbin] [-metric command]
[-metric_higher_is_better]
[-no_auto_detect[={libs|xarch}]] [-o dir]
[-ob build_flags] [-r command] [-rebuild_from_source]
[-reuse dir]... [-s] [-stopon state]
[-tarfile tarfile]
[-timeout seconds {exit0|exit1|pass|fail}] [-V]
[-w dir] [binary_file...]
DESCRIPTION
ats is a binary reoptimization and recompilation tool that
can be used for tuning and troubleshooting applications.
ats works by rebuilding the compiled PEC binary - the origi-
nal source code is not required.
Examples of what can be achieved using ats are:
- Find the compiler options that give the best performance
- Find the object file and the optimization flag that is
causing a runtime problem
- Rebuild the application using new compiler options
ats can be used with the Sun(TM) Studio 11 compilers for C,
C++, and FORTRAN, as well as the GCC for SPARC® Systems,
hereafter referred to as 'gcc'.
ats is able to recompile a binary either from a PEC binary
or via a user supplied build command. If a PEC binary is
supplied, then source code is not required, and very fast
recompile times and module level control of recompilation
are possible. If a build command is supplied, then the user
has control of the build process.
"Portable Executable Code" or "PEC" files are binary files
(executables or shared objects) that contain extra informa-
tion which enable the PEC files to be recompiled with new
compiler options but without the source code or original
build infrastructure (like make files or scripts). PEC files
are used by ats for automatic tuning or troubleshooting of
applications.
Compiling with the PEC option requires optimization level 3
or higher. Here are examples of how to specify the PEC
option for each compiler:
% cc -xO3 -Wd,-pec *.c
% CC -xO3 -Qoption CC -pec *.C *.cc
% f77 -xO3 -Qoption f90 -pec *.f *.F
% f90 -xO3 -Qoption f90 -pec *.f90 *.ftn
% f95 -xO3 -Qoption f90 -pec *.f95
% gcc -O3 -xpec *.c
% g++ -O3 -xpec *.cc
The PEC binary (a.out produced from any line above) is ready
for ats. For example, you could run the default script,
autotuning, like this:
% ats a.out
Or the binary could be recompiled and run (first with -xO4,
then -xO5, and then -fast) like this:
% ats -i '-xO4' \
-i '-xO5' \
-i '-fast' a.out
Alternatively, if it is not feasible to build binaries with
PEC, ats can be used with ordinary (non-PEC) binaries using
the build and run command options like one of these exam-
ples:
% ats -build 'build_it' \
-r 'a.out' -i '-xO4'
% ats -build '$CC $CFLAGS hello.c' \
-r 'a.out' -i '-xO4'
% ats -build 'make CFLAGS=$CFLAGS clean a.out' \
-r 'a.out' -i '-xO4'
% ats -build '$GCC $GCFLAGS hello.c' \
-r 'a.out' -i '-O4'
% ats -build 'gmake CC=$GCC CFLAGS=$GCFLAGS clean a.out' \
-r 'a.out' -i '-O4'
OPTIONS
ats accepts the following options:
-build command
command to build non-PEC binaries. ats sets environment
variables CFLAGS, CCFLAGS, FFLAGS, F90FLAGS and GCFLAGS
-c command
verify command to be called after each run
-cc dir
compiler driver directory or compiler list file;
default = where ats is
-d print debug info
-distr[ibute]
distribute and run each -i <opt> experiment
-distr_cmd <command>
specify the command used to distribute experiments
-h output this help message
-i options
options or a file with list of options (can be speci-
fied more than once); default = script:autotuning
-ias ignore application status; default = false
-keepbin
do not delete rebuilt binaries; default = false
-metric command
command that prints a numerical metric
-metric_higher_is_better
use if a higher value of metric is preferred (default
is the opposite)
-no_auto_detect[={libs|xarch}]
do not try to automatically link in shared libraries
and/or detect -xarch
-o dir
results directory; default = location of the first
binary
-ob <build_flags>
options added to all builds
-p <port>
port to be used for communication with browser (valid
with -server); default = 21000
-r command
run command
-rebuild_from_source
Rebuilds the PEC binaries using their source files
-reuse <res_dir>
Reuse the results from a previous run (can be specified
more than once)
-s silent mode (no screen output)
-server
start the ats server (accepts requests from a browser)
-stopon <state>
stop on first [fail|pass|change|completion|runs <num>]
-tarfile <tarfile>
get source files (such as PEC files, input files, run
scripts) from a tarfile
-timeout <seconds> {exit0|exit1|pass|fail}
application killed after timeout and the specified exit
status is assumed
-V display current version of ats
-w dir
working directory
file...
Either a list of PEC binary with options specific to it
(e.g. a.out 'libx.so -G') or a text file listing one
PEC (with its specific options) per line.
SCRIPTS
An ats script directs ats to perform some useful function.
ats has the following predefined scripts (located in
prod/lib/ipo/ats):
autotuning
binarysearch
combo
deepsweep
findbug
fixbug
modulesearch
sweep
autotuning is the "default" script so these two commands are
equivalent:
% ats a.out
% ats -i 'script:autotuning' a.out
autotuning searches for a set of compiler flags that will
give the application the best performance (based on any
metric the user specifies, see -metric).
All scripts have a "--h" option that prints a usage message
and examples. For example, autotuning produces a message
like this:
% ats -i "script:autotuning --h" -build foo -r bar
=== Starting Automatic Tuning System ===
Will try the following set of options:
script:autotuning --h
# Usage: autotuning [--h|--i|--p|--s] [flags...]
#
# Default => automatic tuning using first class flags
# --h => print this help message
# --i => internal flags are also tried
# internal flags may not be supported
# --p => existing profile is used (no profile is collected)
# --s => only specified flags are tried. No predefined flags
# are tried (--i and --p are also ignored)
#
# Example 1: Default automatic tuning
# % cc -xO3 -Wd,-pec *.c
# % ats a.out
#
# Example 2: Use existing profile
# % ats -i '-xO3 -xprofile=collect ;; do_train_run' \
# -i 'script:autotuning --p' \
# -r 'do_run' a.out
#
# Example 3: Use all available preloaded options
# % ats -i 'script:autotuning --i' a.out
#
EXAMPLES
Example #1
This example first creates a PEC executable a.out and then
recompiles it with -xO4 and executes it:
% cc -xO3 -Wd,-pec *.c
% ats -i -xO4 a.out
Remember: -xO3 or above is needed to create a PEC executable
Note: when using gcc, -O<n> and -xpec are the options to use
Example #2
This example does not use PEC but uses the -build option to
tell ats how to build a.out with a make command:
% ats -i -xO4 -build 'make CFLAGS=$CFLAGS' -r a.out
Example #3
This example does not use PEC but uses the -build option to
tell ats how to build a.out with a gmake command using gcc:
% ats -i -O3 -build 'gmake CC=$GCC CFLAGS=$GCFLAGS' -r a.out
Example #4
This example does not use PEC but used the -build option to
tell ats how to build a.out with a build script ("doit")
using FORTRAN 90 compiler:
% more doit
#!/bin/bash
$F90C $F90FLAGS *.f
% ats -i -xO4 -build doit -r a.out
Example #5
This example does not use PEC but used the -build option to
tell ats how to build a.out with a build script
("build_app") using gcc:
% more build_app
#!/bin/bash
$GCC $GCFLAGS *.c
% ats -i -O4 -build build_app -r a.out
SEE ALSO
CC(1), cc(1), f77(1), f90(1), f95(1), gcc(1).
NOTICE
Copyright © 2006-2007 Sun Microsystems, Inc. All rights
reserved. Sun Microsystems, Inc. has intellectual property
rights relating to technology embodied in the product that
is described in this document. In particular, and without
limitation, these intellectual property rights may include
one or more of the U.S. patents listed at
http://www.sun.com/patents and one or more additional
patents or pending patent applications in the U.S. and in
other countries. U.S. Government Rights - Commercial
software. Government users are subject to the Sun Microsys-
tems, Inc. standard license agreement and applicable provi-
sions of the FAR and its supplements. Use is subject to
license terms. Sun, Sun Microsystems, the Sun logo,
Solaris and Sun[tm] ONE Studio are trademarks or registered
trademarks of Sun Microsystems, Inc. in the U.S. and other
countries. All SPARC trademarks are used under license and
are trademarks or registered trademarks of SPARC Interna-
tional, Inc. in the U.S. and other countries.
Copyright © 2006-2007 Sun Microsystems, Inc. Tous droits
réservés.Sun Microsystems, Inc. détient les droits de
propriété intellectuels relatifs à la technologie incorporée
dans le produit qui est décrit dans ce document. En particu-
lier, et ce sans limitation, ces droits de propriété intel-
lectuelle peuvent inclure un ou plus des brevets américains
listés à l'adresse http://www.sun.com/patents et un ou les
brevets supplémentaires ou les applications de brevet en
attente aux Etats - Unis et dans les autres pays.
L'utilisation est soumise aux termes du contrat de
licence.Sun, Sun Microsystems, le logo Sun, Solaris et
Sun[tm] ONE Studio sont des marques de fabrique ou des
marques déposées de Sun Microsystems, Inc. aux Etats-Unis et
dans d'autres pays.Toutes les marques SPARC sont utilisées
sous licence et sont des marques de fabrique ou des marques
déposées de SPARC International, Inc. aux Etats-Unis et dans
d'autres pays.
Man(1) output converted with man2html
