Automatic Tuning and Troubleshooting System User's Guide

Table of Contents

1 Introduction

The Automatic Tuning and Troubleshooting System (ATS) is a binary reoptimization and recompilation tool that can be used for tuning and troubleshooting applications. By default, ATS works by rebuilding a Portable Executable Code (PEC) binary, which means that the original source code is not required when tuning or troubleshooting the application.

ATS contains many easy-to-use scripts to perform simple and complex tasks. For example, ATS can:

• 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

1.1 Tuning Your Application

You can use ATS scripts like autotuning and combo to tune your applications.

The ATS script autotuning will recompile and run your application with different sets of compiler flags. Flags that improve performance are accumulated and used in the next compilation. Flags that do not improve performance are set aside to be used later in new combinations if time permits.

For example, to create a PEC binary (from C source code) and run the autotuning script, all you need to do is:

% cc -xO3 -xpec *.c
% ats -i 'script:autotuning' a.out

The autotuning script is the default action, so the above ATS command can be rewritten simply as:

% ats a.out

The ATS script combo will generate all combinations of a set of given options. This may be useful if you know a few compiler options that improve the performance of your application and you would like to find out which combination of options is the best.

For example, the following ats command:

% ats -i 'script:combo 3 -f1 "-f2a -f2b" -f3 -f4' a.out

would recompile and run a.out with the following sets of flags:

-f1 -f2a -f2b -f3
-f1 -f2a -f2b     -f4
-f1           -f3 -f4
    -f2a -f2b -f3 -f4

1.2 Troubleshooting Your Application

You can use ATS scripts like modulesearch and sweep to troubleshoot your application.

The ATS script sweep will help you identify which option is causing a failure. If your application fails when compiled with a long set of options, then sweep will first compile with all the options, and then repeatably remove one option and recompile the application.

For example, the following ats command:

% ats -i 'script:sweep 3 -f1 "-f2a -f2b" -f3 -f4' a.out

would recompile and run a.out with the following sets of flags:

-f1 -f2a -f2b -f3 -f4
-f1 -f2a -f2b -f3
-f1 -f2a -f2b
-f1

The ATS script modulesearch will help you find which module (source code file) is causing a failure. If your application generates different results when compiled with two different sets of options, then modulesearch will search for the single module (or set of modules) that generates the different results.

For example, if you had an application that produced different results when compiled with the -xO3 and -fast options, then you could create the PEC binary and run the modulesearch script like this:

% cc -xO3 -xpec *.c
% ats -i 'script:modulesearch -xO3 -fast' a.out

2 Using ATS

To use ATS you need to:

• Creating a PEC Binary
• Running ATS

There are some situations where the following alternatives may be useful:

• Running ATS without Compiling a PEC File
• Running ATS in a Browser

2.1 Creating a PEC Binary

Portable Executable Code (PEC) binary files are executables or shared objects that contain extra information that enable the PEC files to be recompiled with new compiler options without requiring the source code or original build infrastructure (for example, make files or build scripts).

PEC binary files can be created using the Ceres Sun Studio and later compilers for C, C++, and FORTRAN, as well as the GCC for SPARC Systems, hereafter referred to as "gccfss". Here are the compiles supported by ATS:

Note:
Compiling with the PEC option requires an optimization level of 3 or higher.

The following example shows how to specify the PEC option for the cc compiler, and similary for CC, f95, gcc and g++:

% cc -O3 -xpec *.c

2.2 Running ATS

To use ATS you must specify information about the application and what actions you would like ATS to execute.

• Specifying the Application Information
• Specifying the Experiment Actions

2.2.1 Specifying the Application Information

To use ATS you need to give ATS information about the application like:

• How to rebuild the application (usually just a list of PEC files)
• How to run the application
• How to verify the application completed with success
• How to quantify the results (for comparison with other builds)

Here is an example that uses the default build, run, verify, and benchmark commands:

% ats a.out

This command above tells ATS, by default, to:

• build using the specified PEC file ("a.out")
• run using the executable name ("a.out")
• verify using the status of the run command
• benchmark using the time of the run command

Here is an example where the user specified the run (-r), verify (-c), and benchmark (-metric) commands:

% ats -r "a.out < input.txt > output.txt" \
      -c "head output.txt | diff - output.gold" \
      -metric "grep TOTAL output.txt" \
      a.out

This command above tells ATS to:

• build using the PEC file a.out
• run using input from "input.txt" and output to "output.txt"
• verify by comparing the top 10 lines of output.txt with output.gold
• benchmark by searching for the string "TOTAL" in output.txt

This example uses scripts to specify the same run, verify, and benchmark commands as above:

% cat run.csh
a.out < input.txt > output.txt
% cat check.csh
head output.txt | diff - output.gold
% cat metric.csh
grep TOTAL output.txt
% ats -r run.csh \
      -c check.csh \
      -metric metric.csh \
      a.out

2.2.2 Specifying the Experiment Actions

Here are some examples of different experiment actions:

% ats a.out
% ats -i 'script:autotuning' a.out
% ats -i 'script:combo 3 -f1 "-f2a -f2b" -f3 -f4' a.out
% ats -i 'script:sweep 3 -f1 "-f2a -f2b" -f3 -f4' a.out
% ats -i 'script:modulesearch -xO3 -fast' a.out
% ats -i '-xO4' a.out

The first two commands above are equivalent because autotuning is the default ATS experiment action. The final example above will compile the PEC file a.out with the -xO4 compiler option and then run the new executable file.

You can find more detail on specifying scripts and other experiment actions in the ATS Scripts and ATS Experiment Actions sections below.

2.3 Running ATS without Compiling a PEC File

There are some situations where there may be advantages to running ATS without building a PEC binary. For these situations, you can provide the ATS software with a build command instead of a PEC binary file. ATS will set environment variables like CC, GCC, F90C, CFLAGS, CCFLAGS, and GCFLAGS that the build command can use. Therefore, ATS can select the flags used to recompile the application.

Here are a few examples of using the ats command with the --build option:

% ats --build '$CC $CFLAGS hello.c' \
      -r 'a.out' -i '-xO4'
% ats --build '$GCC $GCFLAGS hello.c' \
      -r 'a.out' -i '-O4'
% ats --build 'make  CC=$CC  CFLAGS="$CFLAGS"  clean a.out' \
      -r 'a.out' -i '-xO4'
% ats --build 'make CC=$GCC CFLAGS="$GCFLAGS" clean a.out' \
      -r 'a.out' -i '-O4'
% ats --build 'build_it' \
      -r 'a.out' -i '-xO4'

Note: The --build option requires that a -r option (the run command option) is also specified.

2.4 Running ATS in a Browser

You can access all ATS features from both the command-line interface and the browser interface.

The ATS command-line interface is very useful for batch or automated jobs (such as running ATS as part of a test suite).

The browser interface provides a simple form that may be helpful for learning the ATS software, and it may help with the initial setup of a new ATS job. You can use the browser interface's dryrun checkbox to generate an equivalent ats tool command.

To use the ATS software in a browser, first start the ATS server on the machine where you want to recompile and execute your binary file, and then you control and observe the ATS server by way of the ATS software's web interface HTML page.

For example, you can start an ATS server like this:

% rlogin some_machine
% ats --server
Go to file:///some_very_long_path/ats.html in a browser
Use the following when prompted in browser
User Name: harry
Password : 371425

Then you enter the specified URL in a browser, fill out the ATS form, and click on the "Run Experiment" button. At that time ATS will ask you for a "User Name & Password" and you enter the information printed when you started the server.

The ats.html page has helpful links to an ats_info.html page which contains instructions on how to fill in the ATS form.

3 ATS Scripts

The ATS software has many easy-to-use scripts that you can use to perform a variety of simple and complex tasks. The ATS scripts include:

• autotuning
• binarysearch
• combo
• deepsweep
• findbug
• fixbug
• modulesearch
• sweep

3.1 autotuning

autotuning will recompile and run your application with different sets of compiler flags. Flags that improve performance are accumulated and used in the next compilation. Flags that do not improve performance are set aside and used later in new combinations if time permits.

% 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 -xpec *.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
#

3.2 binarysearch

% ats -i "script:binarysearch --h" --build foo -r bar
=== Starting Automatic Tuning System ===
Will try the following set of options:
	script:binarysearch --h
# Usage: binarysearch [--h] <opts with %d> pass_no fail_no
# where:
#    <opts with %d> is a set of options like "-foo=%d"
#    pass_no  when %d is replaced by this number the test passes
#    fail_no  when %d is replaced by this number the test fails
#
# Example 1: Search the option -foo=%d between values 0 and 175
#
# If -foo=0 passes and -foo=175 fails and you want to find
# a number (n) such that -foo=(n) passes and -foo=(n+1) fails,
# then you can use this command:
#
#   % ats -i 'script:binarysearch "-foo=%d" 0 175' a.out
#

3.3 combo

combo takes a set of compiler options and recompiles them using different combinations of the same options. If your application runs faster or slower when you add a long string of options, then combo will let you know how each flag (or sets of flags) affects performance.

% ats -i "script:combo --h" --build foo -r bar
=== Starting Automatic Tuning System ===
Will try the following set of options:
	script:combo --h
# Usage: combo [--h] <how-many-at-a-time> [options...]
#
# Example 1: Four flags combined three-at-a-time
#
#   % ats -i 'script:combo 3 -a -b -c -d' a.out
#
# The above command will try these options:
#
#   -a -b -c
#   -a -b -d
#   -a -c -d
#   -b -c -d
#

3.4 deepsweep

% ats -i "script:deepsweep --h" --build foo -r bar
=== Starting Automatic Tuning System ===
Will try the following set of options:
	script:deepsweep --h
# Usage: deepsweep [--h] options....
#
# Example 1: Sweep through some options
#
#   % ats -i 'script:deepsweep -a -fast -c -d' a.out
#
# The above command will try these options:
#
#   -a -fast -c -d
#   -a -fast -c
#   -a -fast
#   -a -xO5 -fns -fsimple=2 -xmemalign=8s -xtarget=native -xlibmil -xlibmopt
#   -a -xO5 -fns -fsimple=2 -xmemalign=8s -xtarget=native -xlibmil
#   -a -xO5 -fns -fsimple=2 -xmemalign=8s -xtarget=native
#   -a -xO5 -fns -fsimple=2 -xmemalign=8s
#   -a -xO5 -fns -fsimple=2
#   -a -xO5 -fns -fsimple=1
#   -a -xO5 -fns
#   -a -xO5
#   -a -xO4
#   -a -xO3
#   -xO3
#

3.5 findbug

% ats -i "script:findbug --h" --build foo -r bar
=== Starting Automatic Tuning System ===
Will try the following set of options:
	script:findbug --h
# Usage: findbug [--h] options....
#
# IMPORTANT NOTE: uses modulesearch (requires PEC; no --build)
#
# Example 1: Find options and module that causes failure
#
#   % ats -i 'script:findbug -a -b -c' a.out
#
# The above command starts by issuing these options:
#
#   DEEPSWEEP_STOP_ON_PASS=1
#   script:deepsweep '-a' '-b' '-c'
#   script:modulesearch "" ""
#
# You can see by the lines above that findbug first
# does a deepsweep and then a modulesearch.
#

3.6 fixbug

% ats -i "script:fixbug --h" --build foo -r bar
=== Starting Automatic Tuning System ===
Will try the following set of options:
	script:fixbug --h
# Usage: fixbug [--h] options....
#
# Example 1: Do a findbug and then create executable without bug
#
#   % ats -i 'script:fixbug -a -b -c' a.out
#

3.7 modulesearch

modulesearch will help you find which module (source code file) is causing a failure. If your application generates different results when compiled with two different sets of options, then the modulesearch script will search for the single module (or set of modules) that generates the different results.

% ats -i "script:modulesearch --h" --build foo -r bar
=== Starting Automatic Tuning System ===
Will try the following set of options:
	script:modulesearch --h
# Usage: modulesearch [--h] "working options" "faulty options"
# internal usage:  modulesearch [--h] "working options" "faulty options"
#                    output.html start end mid failing_mid known_bad ...
#
# IMPORTANT NOTE: requires PEC and is not compatible with the ats --build option
#
# Example 1: Find module that passes with -xO4 but fails with -fast
#
#   % ats -i 'script:modulesearch "-xO4" "-fast"' a.out
#

3.8 sweep

% ats -i "script:sweep --h" --build foo -r bar
=== Starting Automatic Tuning System ===
Will try the following set of options:
	script:sweep --h
# Usage: sweep [--h] options....
#
# Example 1: Sweep through some options
#
#   % ats -i 'script:sweep -a -fast -c -d' a.out
#
# The above command will try these options:
#
#   -a -fast -c -d
#   -a -fast -c
#   -a -fast
#   -xO3 -a
#   -xO3
#

4 ATS Experiment Actions

An ATS experiment action can be one of the following:

• a set of compiler options
• a file that contains other ATS actions
• a script command
• an environment variable specification
• a blank line or comment

Here are examples of each of these ATS experiment actions:

-xO4 -xipo
my.opts
script:combo -xO5 -fns -fsimple=2
MY_ENV_VAR_OPTS="-xO3"

# this is a comment below a blank line

Compiler options that should be applied only to a certain compiler can be given in parentheses and prefixed with the compiler name. This is useful for applications and binaries that use more than one language.

Examples:

-xO4 -xipo cc[-xdepend -xalias_level=strong] f90[-xia]
-fast CC[-xlinkopt]

Advanced users can do more. Each line above can be of one of following forms:

1. Recompilation options, run command, and verify command

   set_of_options [;; overriding_run_command [;; overriding_verify_cmd]]
   -xO3 -xO5
   -xO3 -xO5 ;; collect pec.out
   -xO3 -xO5 ;; truss pec.out ;; check_for_errors 

2. Script invocation
   The script can print on stdout the sets of options that ATS should try. Lines printed by scripts can be of any of the general forms.

   script:progname [args ...]
   script:testpl
   script:binarysearch 1 100 

   Scripts are also passed ATS environment variables corresponding to the preceding run
   ATS_LAST_STATUS - empty if there was no previous run
   ATS_LAST_METRIC - empty if there was no previous run

3. Environment Variable Setting (scripts can use them)

   VAR=value
   LOW=0
   HIGH=100 

5 Command-Line Option Descriptions

The ats command accepts the following options.

5.1 -? or --help Option

This option prints the following ats command usage message:

% ats
usage: ats [options] file...  Use 'ats --help' for details
% ats --help
usage: ats [options] file...
       ats {-s|--server} [{-p|--port} <port>]
where options include:
  {-?|--help}             output this help message
  {-b|--build} <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)
  {-B|--bin} <dir>        compiler driver directory or compiler list file; default = /import/backend-blds/compilers/current_ceres/bin
  {-c|--check} <cmd>      verify command to be called after each run
  {-C|--continue} <dir>   reuse the results from a previous run; (can be specified more than once)
  {-d|--distr}            distribute and run each --input <options> experiment
  {-D|--distr-cmd} <cmd>  specify the command used to distribute experiments
  {-f|--file} <tarfile>   get source files from a tarfile
  {-g|--global} <options> options added to all builds
  {-H|--halt} <state>     halt on {fail|pass|change|completion|runs=nn|duration=hh:mm|time='mm/dd/yyyy hh:mm'}
  {-i|--input} <options>  options or a file with list of options; (can be specified more than once); default = script:autotuning
  {-I|--ignore-app-status}        ignore application status; default = false
  {-k|--keepbin}          do not delete rebuilt binaries; default = false
  {-m|--metric} <cmd>     command that prints a numerical metric
  {-M|--metric-higher-is-better}  use if higher is better; default = lower is better
  {-n|--no-auto-detect} {libs|xarch}      do not auto detect shared libraries and/or -xarch
  {-o|--output} <dir>     results directory; default=location of the first binary
  {-p|--port} <port>      port for communication with browser; default = 21000
  {-q|--quiet}            quiet mode (no screen output)
  {-r|--run} <cmd>        run command
  {-R|--rebuild-from-source}      rebuilds the PEC binaries using their source files
  {-s|--server}           start the ats server (accepts requests from a browser)
  {-t|--timeout} <seconds>        application killed after timeout
  {-T|--timeout-status} {exit0|exit1|pass|fail}        specify exit status for timeout
  {-v|--verbose}          print verbose information
  {-V|--version}          report current version of ats
  {-w|--work} <dir>       working directory
  <file>                  either a PEC file (with options) or a text file containing a list of PEC files (with options); for example: 'libx.so -G' 'liby.so -G' a.out 'b.out -g' myPECfiles.txt
  To use the browser interface, first start the ATS server:
    % ats --server
  and then, in a browser, enter the following URL:
    file:///some_long_path/ats.html

5.2 -b or --build <command> Option

The --build option can pass a command to the ats tool when it builds non-PEC binaries. (This option can be specified more than once).

The ATS software will set the following environmental variables: CC, CCC, FC, F90C, F95C, GCC, GXX, CFLAGS, CCFLAGS, FFLAGS, F90FLAGS, F95FLAGS, GCFLAGS, and GXFLAGS.

5.3 -B or --bin <dir> Option

Use the --bin option to specify the compiler directory. The compiler directory field (dir) can contain either a single directory or a file that contains a list of directories where the compiler drivers can be found.

The PEC binary file is examined to determine the name of the driver (cc, CC, f90, gcc, or g++) that was used to compile the modules of the binary file. The compiler directory and the driver name are then combined to create the driver used by the ATS software.

Examples of a single directory:

/compilers/current/bin
/opt/SUNWSPro/compiler/bin
/opt/gcc/bin 

Examples of a file that contains a list of directories:

/home/ron/ats/compiler.list
/home/harry/tmp/compilers

Where:

% more /home/ron/ats/compiler.list 
/compilers/current/bin 
/opt/SUNWSPro/compiler/bin

The default compiler directory is the directory where the ats script is located.

5.4 -c or --check <command> Option

Use the --check <command> option to verify that the execution of the run command either was completed successfully or failed. The status of the command is used for verification (a 0 status means the command ran successfully, and any other status means there was a failure). Examples of using the --check option:

% ats --run   "run.sh" \
      --check "verify.sh" \
      a.out
% ats -r "a.out < input.txt > output.txt" \
      -c "cmp output.txt gold.txt" \
      a.out

5.5 -C or --continue <dir> Option

Use the results from a previous run (can be specified more than once). For example:

% ats --continue ATS/run1 --continue ATS/run4 a.out

5.6 -d or --distr Option

Run each try associated with the -i <opt> distributedly. This flag requires the --file <tarfile> option. Each recompilation is done in a different sub directory under the default output directory, and all are done in parallel.

Examples of using the --distr option:

% ats --distr --file test.tar -i -O3 -i fast -i '-O3 -xipo=2' pec.out
% ats -d -f test.tar -D /opt/SUNWscs/bin/scsx -i '-O4' -i '-fast' pec.out

Note: When using the -i <opt> option with the --distr option, <opt> cannot be a file.

5.7 -D or --distr-cmd <command> Option

Use <command> to accomplish the parallelism. The default is to use the 'dmake' tool.

When 'dmake' is used, ATS will generate a Makefile containing separate ATS commands for each option specified. Then ATS will issue a dmake command. When the dmake command is complete, ATS will collect the results ("reuse") and present the results in a results file.

Read the documentation on 'dmake' or refer to the man pages of 'dmake' to learn how to use it.

The only other command accepted is 'scsx' (Sun Compiler Server). Please refer to 'scsx' documentaion on how to use it.

Note: For now, all distribute commands other than 'dmake' or 'scsx' will be ignored.

5.8 -f or --file <tarfile> Option

The --file option specifies a tarfile that contains all the user files required for an ATS run, i.e., the PEC files, run scripts, input files, verify scripts, etc...

When the -file is used with the -distr option, separate copies of the contents of the tarfile will be created and used by ATS in parallel to save time.

With the specified tarfile, ATS will create a directory (the "tardir"), expand ("untar") the tarfile into the tardir, and then set the working directory to the tardir. The default tardir is ./ATS/run/untar.

5.9 -g or --global <build_flags> Option

Use the --global build option to specify options that will always be used when recompiling the binary file. These specified options will be added after of all other options.

5.10 -H or --halt <state> Option

Use the --halt option to specify one of the following states:

5.11 -i or --input <options> Option

The --input option is used to specify a set of compiler options, a script, or a file that contains sets of options to be used by the ats command.

Examples of using the -i option:

% ats --input "-xO4" \
      --input "-xO5" \
      --input "-fast" \
      a.out
% ats -i "-xO4 -xprofile=collect" \
      -i "-script:autotuning" \
      a.out
% ats -i "my_opts.txt" a.out

Compiler options that should be applied only to a certain driver (cc, CC, f90, gcc, or g++) can be given in square brackets and prefixed with the driver name. Notating compiler options this way can be useful for applications and binaries that use more than one language, for example:

% ats -i "-xO4 -xipo cc[-xdepend -xalias_level=strong] f90[-xia]" a.out
% ats -i "-fast CC[-xlinkopt]" a.out

Using advanced options, you can do more. For example, each set of the above options can be used in one of following formats:

1. Recompilation options, run command, and verify command.

    set_of_options [;; overriding_run_command [;; overriding_verify_cmd]] 
   -xO3 -xO5
   -xO3 -xO5 ;; collect pec.out
   -xO3 -xO5 ;; truss pec.out ;; check_for_errors

2. Script invocation.
   The script can print the sets of options that ATS should try to stdout. Lines printed by scripts can be of any of the general format.

   script:progname [args ...] 
   script:testpl
   script:binarysearch 1 100
   

   Scripts are also passed ATS environment variables corresponding to the preceding run
   ATS_LAST_STATUS - empty if there was no previous run
   ATS_LAST_METRIC - empty if there was no previous run

3. Setting environment variables so that scripts can use them.

   VAR=value
   
   LOW=0
   HIGH=100 

5.12 -I or --ignore-app-status Option

The --ignore-app-status option informs the ATS software to ignore the status returned by the application. Use this option when the application does not follow the standard UNIX(R) convention of returning a zero for success.

The --ignore-app-status option is commonly used with the --check verification option. For example:

% ats --ignore-app-status --check "verify_status.sh" a.out

5.13 -k or --keepbin Option

By default, the ATS software deletes the intermediate binaries it creates. Use the --keepbin option to request to keep the generated binary files.

5.14 -m or --metric <command> Option

The --metric option specifies a command that prints out a performance metric number. The default sorting of the resulting metrics is done from lower values to higher values. (The default performance metric is the total run time.)

Examples of using the --metric option:

% ats --metric "cat timetaken" a.out
% ats -m "extract_benchmark_time" a.out

5.15 -M or --metric_higher_is_better Option

Use this option if a higher value of metric is preferred (which is opposite of the default).

5.16 -n or --no_auto_detect[={libs|xarch}] Option

When specified, the system attempts to link shared objects that the binaries depend on automatically, so that the shared objects do not need to be specified manually. For example, a -lm option used to link the math library is automatically done, so there is no need to use the --global (extra build) option.

5.17 -o or --output <dir> Option

Use the --output option to specify the results directory. Relative directory names are relative to the location of the first binary. The default value is "ATS", which is the "ATS" directory located in the same directory as the first binary.

5.18 -p or --port <port> Option

Use the -port option to specify the port to be used for communication with an ATS server (valid with the -server option). The default network port is 21000.

% ats --server --port 22345
Go to file:///opt/installed/compiler/html/ats.html in a browser
Use the following when prompted in browser
User Name: harry
Password : 943314

Then you would enter the indicated URL in a browser to use the ATS browser interface to specify your ATS command.

5.19 -q or --quiet Option

Use the --quiet option to stop the ATS software from printing any screen output ("quiet mode").

5.20 -r or --run <command> Option

Use the --run option to specify a binary file, a binary file name with additional arguments, or a script that uses the binary.

The default run command is just the binary file name, so, for example, the following two commands are the same:

% ats a.out
% ats --run a.out a.out

Here is an example that has input and output files:

% ats -r "a.out < input.txt > output.txt" a.out

And here is an example that uses a run script:

% ats -r "run.sh" a.out

5.21 -R or --rebuild-from-source Option

Use the --rebuild-from-source option to rebuild the PEC binaries using their source files.

5.22 -s or --server Option

The --server option starts an ATS server which then waits for requests from the ATS browser interface.

% ats --server
Go to file:///usr/installed/compilers/ats.html in a browser
Use the following when prompted in browser
User Name: harry
Password : 943314

Then you would enter the indicated URL in a browser and start using the ATS browser interface.

5.23 -t or --timeout <seconds> Option

The --timeout option permits you to specify a time (in seconds) when to terminate an application. For example:

% ats --timeout 30 a.out

5.24 -T or --timeout-status {exit0|exit1|pass|fail} Option

The --timeout-status option permits you to specify a status to return when an application times out. The default is fail.

If you have an application that does not terminate, or runs for too long as a result of an error, use the exit1 or fail option. The ATS software will terminate the application after the timeout has expired and consider it a failed run.

% ats -t 30 exit1 a.out
...or...
% ats -t 30 fail  a.out

If you have an application that fails quickly, but continues to run longer in case of a successful run, use the exit0 or pass option. The ATS software will terminate the application after the timeout expires and consider it a successful run. The ATS software will then execute the verification command if you specified one. For example:

% ats -t 30 exit0 a.out
...or...
% ats -t 30 pass  a.out

5.25 -v or --verbose Option

The --verbose option is used to enable ATS debugging messages.

Note: This option is used primarily for debugging the ATS software itself, and it may not be helpful for debugging your application.

% ats -v a.out

5.26 -V or --version Option

This option will display the current version of ats command:

% ats -V a.out
ats: Sun Automatic Tuning and Troubleshooting System 1.2 2007/01/09

5.27 -w or --work <dir> Option

The --work option specifies the working directory from which the build, run, and verification commands will be executed.

5.28 {<app>|<app-list>} ... Option

This option can be either a list of PEC binary files with options specific to the files (for example, a.out 'libx.so -G'), or a text file listing one PEC file (with its specific options) per line.

6 Examples

6.1 Example: recompile with PEC

This example first creates the PEC executable a.out. The example then recompiles the a.out PEC executable with the -xO4 option, and then it executes it:

% cc -xO3 -xpec *.c
% ats -i -xO4 a.out

The optimization level 3 or higher is required when compiling a PEC executable.

Note: When using gcc, use the -On and -xpec options.

6.2 Example: --build (without PEC) with make

This example does not use PEC binary, but it uses the --build option to tell the ats command how to build the a.out file using a make command:

% ats -i -xO4 --build 'make CFLAGS=$CFLAGS' -r a.out

6.3 Example: --build (without PEC) with gcc

This example does not use PEC binary, but it uses the --build option to tell the ats command how to build the a.out file with a make command using the gcc compiler:

% ats -i -O3 --build 'make CC=$GCC CFLAGS=$GCFLAGS' -r a.out

6.4 Example: --build (without PEC) with a script

This example does not use a PEC binary, but it uses the --build option to tell the ats command how to build the a.out file with a build script ("doit") using the FORTRAN 90 compiler:

% *more doit*
#!/bin/bash
$F90C $F90FLAGS *.f
% *ats -i -xO4 --build doit -r a.out*

6.5 Example: --build (without PEC) with a gcc script

This example does not use a PEC binary, but it uses the --build option to tell the ats command how to build the a.out file with a build script (build_app) using gcc compiler:

% *more build_app*
#!/bin/bash
$GCC $GCFLAGS *.c
% *ats -i -O4 --build build_app -r a.out*

(last updated 06/30/2008)