NAME

atime − time an assembly language instruction sequence

SYNOPSIS

atime [options] input_file [output_file]

DESCRIPTION

atime provides the means to time MC680X0 assembly code sequences.  It takes the input_file containing a code sequence and returns performance information to the user.  This information can then be compared against information from other code sequence analyses to determine an optimal code sequence.  Output is directed to standard output by default or if the output_file is -, or to output_file if specified. 

Additional features allow specifying sets of input data and the relative probability that each of these will occur, obtaining an execution profile of a code sequence being evaluated, automatically cross-checking results between analyses, and conveniently logging results. 

atime has three modes of operation.  Performance analysis is the default mode where a code sequence is executed many times in a loop with atime calculating and reporting the average time per iteration.  In the execution profiling mode, atime runs all or selected data sets and reports the number of times each executable instruction is hit.  The third mode is assertion listing.  Asserting particular values in a code sequence ensures that various algorithms produce identical results.  This mode causes asserted values for all or selected data sets to be listed.  This output can be used as verification data for subsequent performance analyses and execution profiles. 

Options

atime recognizes the following options and command-line arguments:

-afile Specify an assertion data file (created by a previous run with the -l option.) 

-icount Specify the minimum number of timing iterations. 

-l[name] Print asserted values.  name specifies a dataset in the input file.  Multiple -l options are allowed.  Omitting name causes assertions for all data sets to be listed.  Output can be used to create an assertion file for subsequent atime runs. 

-n Turn off code sequence listing. 

-p[name] Perform execution profiling and print the hit count for each timed instruction.  name specifies a dataset in the input file to analyze.  If there are multiple -p options, printed counts will be the sum for all designated data sets.  Omitting name causes profiling for all data sets. 

-t "text" Specify an output title. 

Instructions

The following atime instructions can appear in the input file and have a format similar to standard assembler instructions.  However, they cannot be labelled, each must be placed on a separate line, and comments cannot follow on the same line.  For instructions that have a corresponding command line option, the latter take precedence when used. 

assert.{b|w|l} name,location
Verify a datum. The name, an alphabetic character followed by zero or more alphanumeric or underscore characters, identifies an asserted datum across atime executions.  Any data addressing mode, such as %d0 or 4(%a4,%d2.w) can be used for location. Executing an assert instruction during performance analysis or execution profiling compares the asserted location with the corresponding name in an assertion data file.  Verification also occurs in the assertion listing mode if an assertion file is specified, although the primary function here is to print name/value pairs. 

assert "file" Specify an assertion data file created from a prior run of atime with the -l option. 

code even

code odd Change the code to even or odd word alignment. 

comment text Specify comment text for output. 

dataname name,name,...name
Define the names of the data entries in dataset instructions.  Names must begin with a $ and are followed by one or more alphanumeric or underscore characters. 

datasetname[(count)],datum,datum,...datum
Define one data set. name identifies the data set for use with the -l or -p options and must be an alphabetic character followed by zero or more alphanumeric or underscore characters.  An optional count indicates the relative number of times that the data set will be used during timing.  For example, a data set with a count of 10 will execute ten times for each seven times that a data set with a count of 7 is executed.  The default count is 1.  As a particular data set is under consideration, each of its data is treated as a string for replacing its corresponding dataname name in any assembly instruction where that name occurs. 

include "file" Include text from the given file. Nested includes are not allowed. 

iterate count Specify the number of timing iterations for performance analysis.  Because the actual count used by atime must be an integer multiple of the sum of the counts in all dataset instructions, the count specified here is taken as a minimum.  If neither this instruction nor a -i option appears, the default count is 1000000. 

ldopt options Specify options to pass to the link editor. 

nolist Turn off code sequence listing. 

output "file" Append output from a performance analysis to file.

stack even

stack odd Adjust the stack for even or odd word alignment. 

time Designate a code section for timing beginning after this instruction and continuing up to a verify instruction or end-of-file. 

title Specify an output title. 

verify Designate a section of code to be used for algorithm verification beginning after this line and continuing up to the end-of-file.  This section will usually contain one or more assert instructions. 

Input file

The input file contains assembly code source text and atime instructions and has the following four sections. 

atime initialization section − This starts at the beginning of the file and continues up to the first MC680X0 assembly instruction or a time, code, or stack instruction.  It can contain assert file, comment, dataname, dataset, include, iterate, ldopt, nolist, output, and title. 

code initialization section − The code following the atime initialization section continues up to a time instruction and typically does the setup for the code to be timed.  It can contain any valid MC680X0 assembler instruction or pseudo-op or any of the following atime instructions: code even, code odd, stack even, stack odd, or include.  It is only in this section that dataname names can be used, and each name replacement must yield a valid MC680X0 instruction. 

timed section − This section starts at the time pseudo-op and continues up to a verify instruction or end-of-file.  It can contain any valid MC680X0 assembler instruction or pseudo-op or the atime include instruction. 

verify section − This section starts at the verify instruction and continues up to the end-of-file.  It can contain any valid MC680X0 assembler instruction or pseudo-op or the atime instructions include or assert.{b|w|l}. 

There must be no branching between input file sections.  Each must be entered by falling into it from the previous section.  Macros for m4 are not supported, nor are multiple instructions per line (see m4(1)). Assembly code can have references to external variables or routines as long as it is guaranteed that these will be resolved during link editing.

DIAGNOSTICS

Error messages from atime are self-explanatory.  Additional error messages may be generated from the assembler or link editor.  If assembly fails, an intermediate temporary file is be retained with the error message, indicating its name.  This file contains a substantial number of comments to aid in correlating assembly errors back to the actual errors in the input file. 

EXAMPLES

To evaluate an algorithm to find the maximum of three integers, the input file to atime could contain the following code sequence:

WARNINGS

atime determines performance information empirically.  Therefore valid results are obtained only if it is run on a quiescent single-user system. 

AUTHOR

atime was developed by HP. 

FILES

/bin/as assembler, as(1)

/bin/ld link editor, ld(1)

SEE ALSO

as(1), gprof(1), ld(1), prof(1). 

Hewlett-Packard Company  —  HP-UX Release 9.0: August 1992