User Commands ats(1)
NAME
ats - Automatic Tuning and Troubleshooting System
SYNOPSIS
ats [-?] [-b cmd] [-B dir] [-c cmd] [-C dir] [-d] [-D cmd]
[-f tarfile] [-g options] [-H state] [-i options] [-I]
[-k] [-m cmd] [-M] [-n {libs|xarch}] [-o dir] [-q]
[-r cmd] [-R] [-t seconds] [-T {exit0|exit1|pass|fail}]
[-v] [-V] [-w dir] file ...
ats -s [-p port]
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 Express and later
compilers for C, C++, and FORTRAN, as well as the GCC for
SPARC Systems, hereafter referred to as 'gccfss'.
ats is able to recompile a binary either from a PEC binary
or through 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 is an example of how to specify the PEC
option for cc, and similarly for CC, f95, gcc and g++:
Last change: 2008/04/02 1
User Commands ats(1)
% cc -O3 -xpec files
The PEC binary (a.out produced from the 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 -O4,
then -O5, and then -fast) like this:
% ats -i '-O4' \
-i '-O5' \
-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 '-O4'
% ats --build '$CC $CFLAGS hello.c' \
-r 'a.out' -i '-O4'
% ats --build 'make CFLAGS=$CFLAGS clean a.out' \
-r 'a.out' -i '-O4'
% ats --build '$CCC $CCFLAGS hello.cc' \
-r 'a.out' -i '-O4'
% ats --build 'make CCC=$CCC CCFLAGS=$CCFLAGS clean a.out' \
-r 'a.out' -i '-O4'
OPTIONS
ats accepts the following options: (each option can also be
specified in long format, indicated in parentheses at the
end of each option description)
-? Output the help message. (--help)
-b cmd
Command to build non-PEC binaries; ats sets: CC CCC FC
F90C F95C GCC GXX CFLAGS CCFLAGS FFLAGS F90FLAGS
F95FLAGS GCFLAGS GXFLAGS (can be specified more than
once). (--build)
-B dir
Compiler driver directory or compiler list file;
default = where ats is. (--bin)
-c cmd
Verify command to be called after each run. (--check)
-C dir
Last change: 2008/04/02 2
User Commands ats(1)
Reuse the results from a previous run (can be specified
more than once). (--continue)
-d Distribute and run each -i options experiment.
(--distr)
-D cmd
Specify the command used to distribute experiments.
(--distr-cmd)
-f tarfile
Get source files (such as PEC files, input files, run
scripts) from a tarfile. (--file)
-g options
Options added to all builds. (--global)
-H state
Stop on the first occurrence of the run state, and
state is one of
fail
pass
change
completion
runs=num
duration=time
time=timestamp
where time has the format [hh:][mm], and timesatmp has
the format "mm/dd/yy hh:mm". (--halt)
-i options
Options or a file with list of options (can be speci-
fied more than once); default = script:autotuning.
(--input)
-I Ignore application status; default = false.
(--ignore-app-status)
-k Do not delete rebuilt binaries; default = false.
(--keepbin)
-m cmd
Command that prints a numerical metric. (--metric)
-M Use if a higher value of metric is preferred (default
is the opposite). (--metric-higher-is-better)
-n {libs|xarch}
Do not try to automatically link in shared libraries
and/or detect -xarch. (--no-auto-detect)
-o dir
Last change: 2008/04/02 3
User Commands ats(1)
Results directory; default = location of the first
binary. (--output)
-p port
Port to be used for communication with browser (valid
with --server); default = 21000. (--port)
-q Quiet mode (no screen output). (--quiet)
-r cmd
Run command. (--run)
-R Rebuilds the PEC binaries using their source files.
(--rebuild-from-source)
-s Start the ats server (accepts requests from a browser).
(--server)
-t seconds
Application killed after timeout. (--timeout)
-T {exit0|exit1|pass|fail}
Specify exit status for timeout. (--timeout-status)
-v Print debug info. (--verbose)
-V Display current version of ats. (--version)
-w dir
Working directory. (--work)
file ...
Either a list of PEC files with options specific to
each file (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:
autotuning
binarysearch
combo
deepsweep
findbug
fixbug
modulesearch
sweep
autotuning is the "default" script so these two commands are
equivalent:
Last change: 2008/04/02 4
User Commands ats(1)
% 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 -O3 -xpec *.c
# % ats a.out
#
# Example 2: Use existing profile
# % ats -i '-O3 -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 -O4 and executes it:
% cc -O3 -xpec *.c
% ats -i -O4 a.out
Last change: 2008/04/02 5
User Commands ats(1)
Remember: -O3 or above is needed to create a PEC executable
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 -O4 --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 make command using cc:
% ats -i -O3 --build 'make CC=$CC CFLAGS=$CFLAGS' -r a.out
If you perfer to use gcc of gccfss with the make command,
then specify the following:
% ats -i -O3 --build 'make 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 -O4 --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 CC:
% more build_app
#!/bin/bash
$CCC $CCFLAGS *.cc
% ats -i -O4 --build build_app -r a.out
If g++ of gccfss is to be used, then the build_app would
look like:
% more build_app
#!/bin/bash
$GXX $GXFLAGS *.cc
Last change: 2008/04/02 6
User Commands ats(1)
SEE ALSO
CC(1), cc(1), f95(1), gcc(1), g++(1).
Last change: 2008/04/02 7
Sign up or Log in to add a comment or watch this page.