
			GNU SUPEROPTIMIZER

The superoptimizer is a function sequence generator that uses a exhaustive
generate-and-test approach to find the shortest instruction sequence for a
given function.  You have to tell the superoptimizer which function and
which CPU you want to get code for, and how many instructions you can
accept.

The superoptimizer can't generate very long sequences, unless you have a
very fast computer or very much spare time.  The time complexity of the
used algorithm is approximately

	     2 n
	O(m n )

where m is the number of available instructions on the architecture and n
is the shortest sequence for the goal function.

The superoptimizer can't guarantee that it finds the best possible
instruction sequences for all possible functions.  For example, it doesn't
even try to include immediate constants (other that -1, 0, +1, and the
smallest negative and biggest positive numbers) in the sequences.  It often
makes a good job for functions that depend on registers only.

WARNING!  The generated sequences might be incorrect with a very small
probability.  Always make sure a sequence is correct before using it.  So
far, I have never discovered any incorrect sequences.  If you find one,
please let me know about it!


			USAGE INSTRUCTIONS

The superoptimizer supports these CPUs: SPARC, Motorola 68000, 68020, and
88000, IBM POWER and PowerPC, AMD 29000, Intel 80x86, Pyramid, DEC Alpha,
HP PA-RISC, and Hitatchi SH.  Mips is not supported, since it doesn't have
instructions whose use in non-obvious.

You need an ANSI C compiler, for example GCC, to compile the
superoptimizer.  Type

	make CPU=-D<cpuname> superopt

where <cpuname> is one of SPARC, MC68000, MC68020, M88000, POWER, POWERPC,
AM29K, I386, PYR, ALPHA, HPPA, or SH.  The compilation might take a long
while, especially for HPPA.

You can also build all superoptizers by typing:

	make all

This will create superopt-sparc, superopt-power, etc.

By default, the superoptimizer doesn't try all immediate shift counts.
Doing so makes the branching factor in the search tree be considerably
larger.  To enable all shift counts, pass -DSHIFTS in the EXTRA make
variable.  If you want to use bitfield extract instructions, pass -DEXTRACTS
in the EXTRA make variable.  For example,

	make all EXTRA="-DSHIFTS -DEXTRACTS"

build all available superoptimizers with both shift and (for the CPUs that
have them) extract instructions enabled.

There are also install targets, use `make install' to install a single
superoptizer and `make install-all' to install all of them.

To run the superoptimizer, type

	superopt -f<goal-function> [-assembler] [-max-cost n] [-no-carry-insns]
	   [-extra-cost n]

and wait until the found instructions sequences are printed.  For example,

	superopt -flts0 -as

will print all sequences computing the statement

	{ r = (signed_word) v0 < 0; }.

See below for possible goal functions.


			OPTIONS

The `-f' option has always to be defined to tell the superoptimizer for
which function it should try to to find an instruction sequence.  See below
for possible function names.

Option names may be abbreviated.

-assembler
	Output assembler suitable to feed /bin/as instead of pseudo-code
	suitable for humans.

-max-cost n
	Limit the `cost' of the instruction sequence to n.  May be used to
	stop the search if no instruction sequence of that length or
	shorter is found.  By default this is 5.

-extra-cost n
	Search for sequences n more expensive than the cheapest found
	sequence.  Default is 0 meaning that only the cheapest sequence(s)
	are printed.

-no-carry-insns
	Don't use instructions that use the carry flag.  This might be
	desirable on RISCs to simplify instruction scheduling.

-f<goal-function-name>
	
	where <goal-function-name> is one of eq, ne, les, ges, lts, gts,
	leu, geu, ltu, gtu, eq0, ne0, les0, ges0, lts0, gts0, neq, nne,
	nles, nges, nlts, ngts, nleu, ngeu, nltu, ngtu, neq0, nne0, nles0,
	nges0, nlts0, ngts0, maxs, mins, maxu, minu, sgn, abs, nabs, gray,
	or gray2, etc, etc.

	eq, ne, les, etc, computes the C expression "a == b", "a != b", "a
	<= b", etc, where the operation codes ending in `s' indicates
	signed comparison; `u` indicates unsigned comparison.

	eq0,... computes "a == 0", ...

	The `n' before the names means that the corresponding function
	value is negated, e.g. nlt is the C expression "-(a < b)".

	maxs, mins, maxu, minu are binary (i.e. two argument) signed
	respectively unsigned max and min.

	sgn is the unary sign function; -1 for negative, 0 for zero, and +1
	for positive arguments.

	abs and nabs are absolute value and negative absolute value,
	respectively.

	For a complete list of goal function and their definitions, look in
	the file goal.def.  You can easily add your own goal functions to
	that file.  After having added a new function, you have to recompile
	the superoptimizer.


		READING SUPEROPTIMIZER OUTPUT

The superoptimizer by default outputs sequences in high-level language like
syntax.  For example, this is the output for M88000/abs:

1:	r1:=arith_shift_right(r0,0x1f)
	r2:=add_co(r1,r0)
	r3:=xor(r2,r1)
2:	r1:=arith_shift_right(r0,0x1f)
	r2:=add(r1,r0)
	r3:=xor(r2,r1)
3:	r1:=arith_shift_right(r0,0x1f)
	r2:=xor(r1,r0)
	r3:=adc_co(r2,r1)

r1:=arith_shift_right(r0,0x1f) means "shift r0 right 31 steps
arithmetically and put the result in r1".  add_co is "add and set carry".
adc_co is the subtraction instruction found on most RISCs, i.e. "add with
complement and set carry".  This may seem dumb, but there is an important
difference in the way carry is set after an addition-with-complement and a
subtraction.  The suffixes "_ci" and "_cio" means respectively that carry
is input but not affected, and that carry is both input and generated.

The interesting value is always the value computed by the last instruction.


		*********************************

Please send comments, improvements and new ports to tege@gnu.ai.mit.edu.

The GNU superoptimizer was written by Torbjorn Granlund (currently with
Cygnus Support).  Tom Wood (at the time with Data General, now at Motorola)
made major improvements, like the clean way to describe goal functions and
internal instructions.  The original superoptimizer idea is due to Henry
Massalin.

The GNU superoptimizer and it's application for tuning GCC are described in
the proceedings of the ACM SIGPLAN conference on Programming Language
Design an Implementation (PLDI), 1992.
