Login | Register
Login | Register

My pages Projects SunSource.net openCollabNet

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 -Wd,-pec *.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 -Wd,-pec *.c
% ats -i 'script:modulesearch -xO3 -fast' a.out

2 Using ATS

To use ATS you need to: There are some situations where the following alternatives may be useful:

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 Sun Studio 11 compilers for C, C++, and FORTRAN, as well as the GCC for SPARC Systems, hereafter referred to as "gcc". The PEC option is specified slightly differently for different compilers:

Language Compiler PEC Option
C gcc -O3 -xpec 
C cc -xO3 -Wd,-pec 
C++ CC -xO3 -Qoption CC -pec 
C++ g++ -O3 -xpec 
FORTRAN f77 f90 or f95 -xO3 -Qoption f90 -pec 

Note: All FORTRAN compilers require "f90" in the Option string.

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

The following examples show 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 *.90 *.ftn
% f95 -xO3 -Qoption f90 -pec *.95
% gcc  -O3             -xpec *.c
% g++  -O3             -xpec *.C *.cc

2.2 Running ATS

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

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 to:
  • [by default] build using the specified PEC file ("a.out")
  • [by default] run using the executable name ("a.out")
  • [by default] verify using the status of the run command
  • [by default] 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 'gmake 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:

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

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 -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.2 -c <command> Option

Use the -c 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 -c option: 
    % ats -r "a.out < input.txt > output.txt" \
      -c "cmp output.txt gold.txt" \
      a.out
% ats -r "run.sh" -c "verify.sh" a.out

5.3 -cc <dir> Option

Use the -cc 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/extra/sgcc/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 -d Option

The debug 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 -d a.out

5.5 -distribute Option

Run each try associated with the -i <opt> distributedly. This flag requires the -tarfile <file> 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 -dstribute option: 

    % ats -distribute -tarfile test.tar -i -O3 -i fast -i '-O3 -xipo=2' pec.out

% ats -distribute -distr_cmd /opt/SUNWscs/bin/scsx -tarfile test.tar -i '-O4' -i '-fast' pec.out
Note: When using the -i <opt> option with the -distribute option, <opt> cannot be a file.

5.6 -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.7 -h Option

This option prints the following ats command usage message: 
    % ats -h
Usage: ats [options] {<app>|<app-list>} ...
where options include:
  -build <command>      command to build non-PEC binaries (can be specified more than once)
                        ats sets CC CCC FC F90C F95C GCC GXX CFLAGS CCFLAGS FFLAGS F90FLAGS F95FLAGS GCFLAGS & GXFLAGS
  -c[heck] <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 specified 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 = lower is better
  -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[un] <command>      run command
  -rebuild_from_source  rebuilds the PEC binaries using their source files
  -reuse <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 <file>       get source files from a tarfile
  -timeout <seconds> {exit0|exit1|pass|fail}   application killed after timeout and specified exit status assumed
  -V                    display current version of ats
  -w <dir>              working directory
  <app>                 PEC binary with options specific to it (e.g. a.out 'libx.so -G')
  <app-list>            a text file listing one PEC (with its specific options) per line

5.8 -i <options> Option

The -i 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 -i "-xO4" \
      -i "-xO5" \
      -i "-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.9 -ias Option

The -ias 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 -ias option is commonly used with the -c verification option. For example: 

    % ats -ias -c "verify_status.sh" a.out

5.10 -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.11 -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 -metric "extract_benchmark_time" a.out

5.12 -metric_higher_is_better Option

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

5.13 -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 -ob (extra build) option.

5.14 -o <dir> Option

Use the -o 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.15 -ob <build_flags> Option

Use the -ob extra 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.16 -p <port> Option

Use the -p 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 -p 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.17 -r <command> Option

Use the -r run command 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 -r 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.18 -rebuild_from_source Option

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

5.19 -reuse <res_dir> Option

Reuse the results from a previous run (can be specified more than once). For example: 
    % ats -reuse ATS/run1 -reuse ATS/run4 a.out

5.20 -s Option

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

5.21 -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.22 -stopon <state> Option

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

Completion Do not stop (default)
Pass Stop on the first passing test
Fail Stop on the first failing test
Change Stop on a change (pass to fail or fail to pass)
Number of runs Limit the number of runs to the specified value
Example: 40
Duration Stop after the specified number of hours and minutes
Examples:
1:20 (One hour and twenty minutes)
40: (forty hours)
:70 (seventy minutes)
10 (ten minutes)
Time Stop at the specified date and time
Example: 01/14/05 14:40

5.23 -tarfile <file> Option

The -tarfile 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 -tarfile is used with the -distribute 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.24 -timeout <seconds> {exit0|exit1|pass|fail} Option

The -timeout option permits you to specify a time (in seconds) when to terminate an application. For example: 
    % ats -timeout 30 a.out
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 -timeout 30 exit1 a.out
...or...
% ats -timeout 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 -timeout 30 exit0 a.out
...or...
% ats -timeout 30 pass  a.out

5.25 -V 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.26 -w <dir> Option

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

5.27 {<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 -Wd,-pec *.c
% ats -i -xO4 a.out
The optimization level 3 or higher is required when creating 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 gmake command using the gcc compiler: 
    % ats -i -O3 -build 'gmake 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 03/20/2007)
Sun Microsystems Logo
Powered by
CoolThreads Server

By any use of this Website, you agree to be bound by these Policies and Terms of Use.
Copyright © 1995-2007 Sun Microsystems, Inc.