Subversion Repositories openrisc

@c Copyright (c) 2006 Free Software Foundation, Inc.

@c Free Software Foundation, Inc.

@c This is part of the GCC manual.

@c For copying conditions, see the file gcc.texi.

@c ---------------------------------------------------------------------

@c Loop Representation

@c ---------------------------------------------------------------------

@node Loop Analysis and Representation

@chapter Analysis and Representation of Loops

GCC provides extensive infrastructure for work with natural loops, i.e.,

strongly connected components of CFG with only one entry block.  This

chapter describes representation of loops in GCC, both on GIMPLE and in

RTL, as well as the interfaces to loop-related analyses (induction

variable analysis and number of iterations analysis).

@menu

* Loop representation::         Representation and analysis of loops.

* Loop querying::               Getting information about loops.

* Loop manipulation::           Loop manipulation functions.

* LCSSA::                       Loop-closed SSA form.

* Scalar evolutions::           Induction variables on GIMPLE.

* loop-iv::                     Induction variables on RTL.

* Number of iterations::        Number of iterations analysis.

* Dependency analysis::         Data dependency analysis.

* Lambda::                      Linear loop transformations framework.

@end menu

@node Loop representation

@section Loop representation

@cindex Loop representation

@cindex Loop analysis

This chapter describes the representation of loops in GCC, and functions

that can be used to build, modify and analyze this representation.  Most

of the interfaces and data structures are declared in @file{cfgloop.h}.

At the moment, loop structures are analyzed and this information is

updated only by the optimization passes that deal with loops, but some

efforts are being made to make it available throughout most of the

optimization passes.

In general, a natural loop has one entry block (header) and possibly

several back edges (latches) leading to the header from the inside of

the loop.  Loops with several latches may appear if several loops share

a single header, or if there is a branching in the middle of the loop.

The representation of loops in GCC however allows only loops with a

single latch.  During loop analysis, headers of such loops are split and

forwarder blocks are created in order to disambiguate their structures.

A heuristic based on profile information is used to determine whether

the latches correspond to sub-loops or to control flow in a single loop.

This means that the analysis sometimes changes the CFG, and if you run

it in the middle of an optimization pass, you must be able to deal with

the new blocks.

Body of the loop is the set of blocks that are dominated by its header,

and reachable from its latch against the direction of edges in CFG.  The

loops are organized in a containment hierarchy (tree) such that all the

loops immediately contained inside loop L are the children of L in the

tree.  This tree is represented by the @code{struct loops} structure.

The root of this tree is a fake loop that contains all blocks in the

function.  Each of the loops is represented in a @code{struct loop}

structure.  Each loop is assigned an index (@code{num} field of the

@code{struct loop} structure), and the pointer to the loop is stored in

the corresponding field of the @code{parray} field of the loops

structure.  Index of a sub-loop is always greater than the index of its

super-loop.  The indices do not have to be continuous, there may be

empty (@code{NULL}) entries in the @code{parray} created by deleting

loops.  The index of a loop never changes.  The first unused index is

stored in the @code{num} field of the loops structure.

Each basic block contains the reference to the innermost loop it belongs

to (@code{loop_father}).  For this reason, it is only possible to have

one @code{struct loops} structure initialized at the same time for each

CFG.  It is recommended to use the global variable @code{current_loops}

to contain the @code{struct loops} structure, especially if the loop

structures are updated throughout several passes.  Many of the loop

manipulation functions assume that dominance information is up-to-date.

The loops are analyzed through @code{loop_optimizer_init} function.  The

argument of this function is a set of flags represented in an integer

bitmask.  These flags specify what other properties of the loop

structures should be calculated/enforced and preserved later:

@itemize

@item @code{LOOPS_HAVE_PREHEADERS}: Forwarder blocks are created in such

a way that each loop has only one entry edge, and additionally, the

source block of this entry edge has only one successor.  This creates a

natural place where the code can be moved out of the loop, and ensures

that the entry edge of the loop leads from its immediate super-loop.

@item @code{LOOPS_HAVE_SIMPLE_LATCHES}: Forwarder blocks are created to

force the latch block of each loop to have only one successor.  This

ensures that the latch of the loop does not belong to any of its

sub-loops, and makes manipulation with the loops significantly easier.

Most of the loop manipulation functions assume that the loops are in

this shape.  Note that with this flag, the ``normal'' loop without any

control flow inside and with one exit consists of two basic blocks.

@item @code{LOOPS_HAVE_MARKED_IRREDUCIBLE_REGIONS}: Basic blocks and

edges in the strongly connected components that are not natural loops

(have more than one entry block) are marked with

@code{BB_IRREDUCIBLE_LOOP} and @code{EDGE_IRREDUCIBLE_LOOP} flags.  The

flag is not set for blocks and edges that belong to natural loops that

are in such an irreducible region (but it is set for the entry and exit

edges of such a loop, if they lead to/from this region).

@item @code{LOOPS_HAVE_MARKED_SINGLE_EXITS}: If a loop has exactly one

exit edge, this edge is stored in @code{single_exit} field of the loop

structure.  @code{NULL} is stored there otherwise.

@end itemize

These properties may also be computed/enforced later, using functions

@code{create_preheaders}, @code{force_single_succ_latches},

@code{mark_irreducible_loops} and @code{mark_single_exit_loops}.

The memory occupied by the loops structures should be freed with

@code{loop_optimizer_finalize} function.

The CFG manipulation functions in general do not update loop structures.

Specialized versions that additionally do so are provided for the most

common tasks.  On GIMPLE, @code{cleanup_tree_cfg_loop} function can be

used to cleanup CFG while updating the loops structures if

@code{current_loops} is set.

@node Loop querying

@section Loop querying

@cindex Loop querying

The functions to query the information about loops are declared in

@file{cfgloop.h}.  Some of the information can be taken directly from

the structures.  @code{loop_father} field of each basic block contains

the innermost loop to that the block belongs.  The most useful fields of

loop structure (that are kept up-to-date at all times) are:

@itemize

@item @code{header}, @code{latch}: Header and latch basic blocks of the

loop.

@item @code{num_nodes}: Number of basic blocks in the loop (including

the basic blocks of the sub-loops).

@item @code{depth}: The depth of the loop in the loops tree, i.e., the

number of super-loops of the loop.

@item @code{outer}, @code{inner}, @code{next}: The super-loop, the first

sub-loop, and the sibling of the loop in the loops tree.

@item @code{single_exit}: The exit edge of the loop, if the loop has

exactly one exit and the loops were analyzed with

LOOPS_HAVE_MARKED_SINGLE_EXITS.

@end itemize

There are other fields in the loop structures, many of them used only by

some of the passes, or not updated during CFG changes; in general, they

should not be accessed directly.

The most important functions to query loop structures are:

@itemize

@item @code{flow_loops_dump}: Dumps the information about loops to a

file.

@item @code{verify_loop_structure}: Checks consistency of the loop

structures.

@item @code{loop_latch_edge}: Returns the latch edge of a loop.

@item @code{loop_preheader_edge}: If loops have preheaders, returns

the preheader edge of a loop.

@item @code{flow_loop_nested_p}: Tests whether loop is a sub-loop of

another loop.

@item @code{flow_bb_inside_loop_p}: Tests whether a basic block belongs

to a loop (including its sub-loops).

@item @code{find_common_loop}: Finds the common super-loop of two loops.

@item @code{superloop_at_depth}: Returns the super-loop of a loop with

the given depth.

@item @code{tree_num_loop_insns}, @code{num_loop_insns}: Estimates the

number of insns in the loop, on GIMPLE and on RTL.

@item @code{loop_exit_edge_p}: Tests whether edge is an exit from a

loop.

@item @code{mark_loop_exit_edges}: Marks all exit edges of all loops

with @code{EDGE_LOOP_EXIT} flag.

@item @code{get_loop_body}, @code{get_loop_body_in_dom_order},

@code{get_loop_body_in_bfs_order}: Enumerates the basic blocks in the

loop in depth-first search order in reversed CFG, ordered by dominance

relation, and breath-first search order, respectively.

@item @code{get_loop_exit_edges}: Enumerates the exit edges of a loop.

@item @code{just_once_each_iteration_p}: Returns true if the basic block

is executed exactly once during each iteration of a loop (that is, it

does not belong to a sub-loop, and it dominates the latch of the loop).

@end itemize

@node Loop manipulation

@section Loop manipulation

@cindex Loop manipulation

The loops tree can be manipulated using the following functions:

@itemize

@item @code{flow_loop_tree_node_add}: Adds a node to the tree.

@item @code{flow_loop_tree_node_remove}: Removes a node from the tree.

@item @code{add_bb_to_loop}: Adds a basic block to a loop.

@item @code{remove_bb_from_loops}: Removes a basic block from loops.

@end itemize

The specialized versions of several low-level CFG functions that also

update loop structures are provided:

@itemize

@item @code{loop_split_edge_with}: Splits an edge, and places a

specified RTL code on it.  On GIMPLE, the function can still be used,

but the code must be NULL.

@item @code{bsi_insert_on_edge_immediate_loop}: Inserts code on edge,

splitting it if necessary.  Only works on GIMPLE.

@item @code{remove_path}: Removes an edge and all blocks it dominates.

@item @code{loop_commit_inserts}: Commits insertions scheduled on edges,

and sets loops for the new blocks.  This function can only be used on

GIMPLE.

@item @code{split_loop_exit_edge}: Splits exit edge of the loop,

ensuring that PHI node arguments remain in the loop (this ensures that

loop-closed SSA form is preserved).  Only useful on GIMPLE.

@end itemize

Finally, there are some higher-level loop transformations implemented.

While some of them are written so that they should work on non-innermost

loops, they are mostly untested in that case, and at the moment, they

are only reliable for the innermost loops:

@itemize

@item @code{create_iv}: Creates a new induction variable.  Only works on

GIMPLE.  @code{standard_iv_increment_position} can be used to find a

suitable place for the iv increment.

@item @code{duplicate_loop_to_header_edge},

@code{tree_duplicate_loop_to_header_edge}: These functions (on RTL and

on GIMPLE) duplicate the body of the loop prescribed number of times on

one of the edges entering loop header, thus performing either loop

unrolling or loop peeling.  @code{can_duplicate_loop_p}

(@code{can_unroll_loop_p} on GIMPLE) must be true for the duplicated

loop.

@item @code{loop_version}, @code{tree_ssa_loop_version}: These function

create a copy of a loop, and a branch before them that selects one of

them depending on the prescribed condition.  This is useful for

optimizations that need to verify some assumptions in runtime (one of

the copies of the loop is usually left unchanged, while the other one is

transformed in some way).

@item @code{tree_unroll_loop}: Unrolls the loop, including peeling the

extra iterations to make the number of iterations divisible by unroll

factor, updating the exit condition, and removing the exits that now

cannot be taken.  Works only on GIMPLE.

@end itemize

@node LCSSA

@section Loop-closed SSA form

@cindex LCSSA

@cindex Loop-closed SSA form

Throughout the loop optimizations on tree level, one extra condition is

enforced on the SSA form:  No SSA name is used outside of the loop in

that it is defined.  The SSA form satisfying this condition is called

``loop-closed SSA form'' -- LCSSA.  To enforce LCSSA, PHI nodes must be

created at the exits of the loops for the SSA names that are used

outside of them.  Only the real operands (not virtual SSA names) are

held in LCSSA, in order to save memory.

There are various benefits of LCSSA:

@itemize

@item Many optimizations (value range analysis, final value

replacement) are interested in the values that are defined in the loop

and used outside of it, i.e., exactly those for that we create new PHI

nodes.

@item In induction variable analysis, it is not necessary to specify the

loop in that the analysis should be performed -- the scalar evolution

analysis always returns the results with respect to the loop in that the

SSA name is defined.

@item It makes updating of SSA form during loop transformations simpler.

Without LCSSA, operations like loop unrolling may force creation of PHI

nodes arbitrarily far from the loop, while in LCSSA, the SSA form can be

updated locally.  However, since we only keep real operands in LCSSA, we

cannot use this advantage (we could have local updating of real

operands, but it is not much more efficient than to use generic SSA form

updating for it as well; the amount of changes to SSA is the same).

@end itemize

However, it also means LCSSA must be updated.  This is usually

straightforward, unless you create a new value in loop and use it

outside, or unless you manipulate loop exit edges (functions are

provided to make these manipulations simple).

@code{rewrite_into_loop_closed_ssa} is used to rewrite SSA form to

LCSSA, and @code{verify_loop_closed_ssa} to check that the invariant of

LCSSA is preserved.

@node Scalar evolutions

@section Scalar evolutions

@cindex Scalar evolutions

@cindex IV analysis on GIMPLE

Scalar evolutions (SCEV) are used to represent results of induction

variable analysis on GIMPLE.  They enable us to represent variables with

complicated behavior in a simple and consistent way (we only use it to

express values of polynomial induction variables, but it is possible to

extend it).  The interfaces to SCEV analysis are declared in

@file{tree-scalar-evolution.h}.  To use scalar evolutions analysis,

@code{scev_initialize} must be used.  To stop using SCEV,

@code{scev_finalize} should be used.  SCEV analysis caches results in

order to save time and memory.  This cache however is made invalid by

most of the loop transformations, including removal of code.  If such a

transformation is performed, @code{scev_reset} must be called to clean

the caches.

Given an SSA name, its behavior in loops can be analyzed using the

@code{analyze_scalar_evolution} function.  The returned SCEV however

does not have to be fully analyzed and it may contain references to

other SSA names defined in the loop.  To resolve these (potentially

recursive) references, @code{instantiate_parameters} or

@code{resolve_mixers} functions must be used.

@code{instantiate_parameters} is useful when you use the results of SCEV

only for some analysis, and when you work with whole nest of loops at

once.  It will try replacing all SSA names by their SCEV in all loops,

including the super-loops of the current loop, thus providing a complete

information about the behavior of the variable in the loop nest.

@code{resolve_mixers} is useful if you work with only one loop at a

time, and if you possibly need to create code based on the value of the

induction variable.  It will only resolve the SSA names defined in the

current loop, leaving the SSA names defined outside unchanged, even if

their evolution in the outer loops is known.

The SCEV is a normal tree expression, except for the fact that it may

contain several special tree nodes.  One of them is

@code{SCEV_NOT_KNOWN}, used for SSA names whose value cannot be

expressed.  The other one is @code{POLYNOMIAL_CHREC}.  Polynomial chrec

has three arguments -- base, step and loop (both base and step may

contain further polynomial chrecs).  Type of the expression and of base

and step must be the same.  A variable has evolution

@code{POLYNOMIAL_CHREC(base, step, loop)} if it is (in the specified

loop) equivalent to @code{x_1} in the following example

@smallexample

while (...)

  @{

    x_1 = phi (base, x_2);

    x_2 = x_1 + step;

  @}

@end smallexample

Note that this includes the language restrictions on the operations.

For example, if we compile C code and @code{x} has signed type, then the

overflow in addition would cause undefined behavior, and we may assume

that this does not happen.  Hence, the value with this SCEV cannot

overflow (which restricts the number of iterations of such a loop).

In many cases, one wants to restrict the attention just to affine

induction variables.  In this case, the extra expressive power of SCEV

is not useful, and may complicate the optimizations.  In this case,

@code{simple_iv} function may be used to analyze a value -- the result

is a loop-invariant base and step.

@node loop-iv

@section IV analysis on RTL

@cindex IV analysis on RTL

The induction variable on RTL is simple and only allows analysis of

affine induction variables, and only in one loop at once.  The interface

is declared in @file{cfgloop.h}.  Before analyzing induction variables

in a loop L, @code{iv_analysis_loop_init} function must be called on L.

After the analysis (possibly calling @code{iv_analysis_loop_init} for

several loops) is finished, @code{iv_analysis_done} should be called.

The following functions can be used to access the results of the

analysis:

@itemize

@item @code{iv_analyze}: Analyzes a single register used in the given

insn.  If no use of the register in this insn is found, the following

insns are scanned, so that this function can be called on the insn

returned by get_condition.

@item @code{iv_analyze_result}: Analyzes result of the assignment in the

given insn.

@item @code{iv_analyze_expr}: Analyzes a more complicated expression.

All its operands are analyzed by @code{iv_analyze}, and hence they must

be used in the specified insn or one of the following insns.

@end itemize

The description of the induction variable is provided in @code{struct

rtx_iv}.  In order to handle subregs, the representation is a bit

complicated; if the value of the @code{extend} field is not

@code{UNKNOWN}, the value of the induction variable in the i-th

iteration is

@smallexample

delta + mult * extend_@{extend_mode@} (subreg_@{mode@} (base + i * step)),

@end smallexample

with the following exception:  if @code{first_special} is true, then the

value in the first iteration (when @code{i} is zero) is @code{delta +

mult * base}.  However, if @code{extend} is equal to @code{UNKNOWN},

then @code{first_special} must be false, @code{delta} 0, @code{mult} 1

and the value in the i-th iteration is

@smallexample

subreg_@{mode@} (base + i * step)

@end smallexample

The function @code{get_iv_value} can be used to perform these

calculations.

@node Number of iterations

@section Number of iterations analysis

@cindex Number of iterations analysis

Both on GIMPLE and on RTL, there are functions available to determine

the number of iterations of a loop, with a similar interface.  In many

cases, it is not possible to determine number of iterations

unconditionally -- the determined number is correct only if some

assumptions are satisfied.  The analysis tries to verify these

conditions using the information contained in the program; if it fails,

the conditions are returned together with the result.  The following

information and conditions are provided by the analysis:

@itemize

@item @code{assumptions}: If this condition is false, the rest of

the information is invalid.

@item @code{noloop_assumptions} on RTL, @code{may_be_zero} on GIMPLE: If

this condition is true, the loop exits in the first iteration.

@item @code{infinite}: If this condition is true, the loop is infinite.

This condition is only available on RTL.  On GIMPLE, conditions for

finiteness of the loop are included in @code{assumptions}.

@item @code{niter_expr} on RTL, @code{niter} on GIMPLE: The expression

that gives number of iterations.  The number of iterations is defined as

the number of executions of the loop latch.

@end itemize

Both on GIMPLE and on RTL, it necessary for the induction variable

analysis framework to be initialized (SCEV on GIMPLE, loop-iv on RTL).

On GIMPLE, the results are stored to @code{struct tree_niter_desc}

structure.  Number of iterations before the loop is exited through a

given exit can be determined using @code{number_of_iterations_exit}

function.  On RTL, the results are returned in @code{struct niter_desc}

structure.  The corresponding function is named

@code{check_simple_exit}.  There are also functions that pass through

all the exits of a loop and try to find one with easy to determine

number of iterations -- @code{find_loop_niter} on GIMPLE and

@code{find_simple_exit} on RTL.  Finally, there are functions that

provide the same information, but additionally cache it, so that

repeated calls to number of iterations are not so costly --

@code{number_of_iterations_in_loop} on GIMPLE and

@code{get_simple_loop_desc} on RTL.

Note that some of these functions may behave slightly differently than

others -- some of them return only the expression for the number of

iterations, and fail if there are some assumptions.  The function

@code{number_of_iterations_in_loop} works only for single-exit loops,

and it returns the value for number of iterations higher by one with

respect to all other functions (i.e., it returns number of executions of

the exit statement, not of the loop latch).

@node Dependency analysis

@section Data Dependency Analysis

@cindex Data Dependency Analysis

The code for the data dependence analysis can be found in

@file{tree-data-ref.c} and its interface and data structures are

described in @file{tree-data-ref.h}.  The function that computes the

data dependences for all the array and pointer references for a given

loop is @code{compute_data_dependences_for_loop}.  This function is

currently used by the linear loop transform and the vectorization

passes.  Before calling this function, one has to allocate two vectors:

a first vector will contain the set of data references that are

contained in the analyzed loop body, and the second vector will contain

the dependence relations between the data references.  Thus if the

vector of data references is of size @code{n}, the vector containing the

dependence relations will contain @code{n*n} elements.  However if the

analyzed loop contains side effects, such as calls that potentially can

interfere with the data references in the current analyzed loop, the

analysis stops while scanning the loop body for data references, and

inserts a single @code{chrec_dont_know} in the dependence relation

array.

The data references are discovered in a particular order during the

scanning of the loop body: the loop body is analyzed in execution order,

and the data references of each statement are pushed at the end of the

data reference array.  Two data references syntactically occur in the

program in the same order as in the array of data references.  This

syntactic order is important in some classical data dependence tests,

and mapping this order to the elements of this array avoids costly

queries to the loop body representation.

Three types of data references are currently handled: ARRAY_REF,

INDIRECT_REF and COMPONENT_REF. The data structure for the data reference

is @code{data_reference}, where @code{data_reference_p} is a name of a

pointer to the data reference structure. The structure contains the

following elements:

@itemize

@item @code{base_object_info}: Provides information about the base object

of the data reference and its access functions. These access functions

represent the evolution of the data reference in the loop relative to

its base, in keeping with the classical meaning of the data reference

access function for the support of arrays. For example, for a reference

@code{a.b[i][j]}, the base object is @code{a.b} and the access functions,

one for each array subscript, are:

@code{@{i_init, + i_step@}_1, @{j_init, +, j_step@}_2}.

@item @code{first_location_in_loop}: Provides information about the first

location accessed by the data reference in the loop and about the access

function used to represent evolution relative to this location. This data

is used to support pointers, and is not used for arrays (for which we

have base objects). Pointer accesses are represented as a one-dimensional

access that starts from the first location accessed in the loop. For

example:

@smallexample

      for1 i

         for2 j

          *((int *)p + i + j) = a[i][j];

@end smallexample

The access function of the pointer access is @code{@{0, + 4B@}_for2}

relative to @code{p + i}. The access functions of the array are

@code{@{i_init, + i_step@}_for1} and @code{@{j_init, +, j_step@}_for2}

relative to @code{a}.

Usually, the object the pointer refers to is either unknown, or we can't

prove that the access is confined to the boundaries of a certain object.

Two data references can be compared only if at least one of these two

representations has all its fields filled for both data references.

The current strategy for data dependence tests is as follows:

If both @code{a} and @code{b} are represented as arrays, compare

@code{a.base_object} and @code{b.base_object};

if they are equal, apply dependence tests (use access functions based on

base_objects).

Else if both @code{a} and @code{b} are represented as pointers, compare

@code{a.first_location} and @code{b.first_location};

if they are equal, apply dependence tests (use access functions based on

first location).

However, if @code{a} and @code{b} are represented differently, only try

to prove that the bases are definitely different.

@item Aliasing information.

@item Alignment information.

@end itemize

The structure describing the relation between two data references is

@code{data_dependence_relation} and the shorter name for a pointer to

such a structure is @code{ddr_p}.  This structure contains:

@itemize

@item a pointer to each data reference,

@item a tree node @code{are_dependent} that is set to @code{chrec_known}

if the analysis has proved that there is no dependence between these two

data references, @code{chrec_dont_know} if the analysis was not able to

determine any useful result and potentially there could exist a

dependence between these data references, and @code{are_dependent} is

set to @code{NULL_TREE} if there exist a dependence relation between the

data references, and the description of this dependence relation is

given in the @code{subscripts}, @code{dir_vects}, and @code{dist_vects}

arrays,

@item a boolean that determines whether the dependence relation can be

represented by a classical distance vector,

@item an array @code{subscripts} that contains a description of each

subscript of the data references.  Given two array accesses a

subscript is the tuple composed of the access functions for a given

dimension.  For example, given @code{A[f1][f2][f3]} and

@code{B[g1][g2][g3]}, there are three subscripts: @code{(f1, g1), (f2,

g2), (f3, g3)}.

@item two arrays @code{dir_vects} and @code{dist_vects} that contain

classical representations of the data dependences under the form of

direction and distance dependence vectors,

@item an array of loops @code{loop_nest} that contains the loops to

which the distance and direction vectors refer to.

@end itemize

Several functions for pretty printing the information extracted by the

data dependence analysis are available: @code{dump_ddrs} prints with a

maximum verbosity the details of a data dependence relations array,

@code{dump_dist_dir_vectors} prints only the classical distance and

direction vectors for a data dependence relations array, and

@code{dump_data_references} prints the details of the data references

contained in a data reference array.

@node Lambda

@section Linear loop transformations framework

@cindex Linear loop transformations framework

Lambda is a framework that allows transformations of loops using

non-singular matrix based transformations of the iteration space and

loop bounds. This allows compositions of skewing, scaling, interchange,

and reversal transformations.  These transformations are often used to

improve cache behavior or remove inner loop dependencies to allow

parallelization and vectorization to take place.

To perform these transformations, Lambda requires that the loopnest be

converted into a internal form that can be matrix transformed easily.

To do this conversion, the function

@code{gcc_loopnest_to_lambda_loopnest} is provided.  If the loop cannot

be transformed using lambda, this function will return NULL.

Once a @code{lambda_loopnest} is obtained from the conversion function,

it can be transformed by using @code{lambda_loopnest_transform}, which

takes a transformation matrix to apply.  Note that it is up to the

caller to verify that the transformation matrix is legal to apply to the

loop (dependence respecting, etc).  Lambda simply applies whatever

matrix it is told to provide.  It can be extended to make legal matrices

out of any non-singular matrix, but this is not currently implemented.

Legality of a matrix for a given loopnest can be verified using

@code{lambda_transform_legal_p}.

Given a transformed loopnest, conversion back into gcc IR is done by

@code{lambda_loopnest_to_gcc_loopnest}.  This function will modify the

loops so that they match the transformed loopnest.