#||

README
~~~~~~~

Authors: Disha Puri, Sandip Ray, Kecheng Hao, Fei Xie
Last Updated: 12th April 2014

Loop pipelining is an important transformation in verification of high level synthesis framework.
This code is part of an ongoing attempt to create a certified loop pipelining algorithm.

*******************************************************************************************
* OVERVIEW
********************************************************************************************

We are trying to establish that if a pipelined CCDFG (with
no relevant data-hazards) is created from a sequential CCDFG
using our algorithm (superstep-construction function), then
the execution of full sequential and pipelined CCDFG
produces same results.

One of the crucial steps of certifying correctness is
proving the link between the back loop edge in sequential
CCDFG and the back loop edge in pipelined CCDFG. We have
formalized an invariant which we describe in this paper. We
prove that our algorithm is such that the invariant is true.
We also prove that correctness of invariant implies that
execution of pipelined CCDFG is same as execution of
sequential CCDFG.

*******************************************************************************************
* INSIGHT INTO ALGORITHM: THE BIGGER PICTURE
*******************************************************************************************

We do not discuss the complete algorithm in these scripts.
However, here is a little insight into the algorithm:

Input: Sequential CCDFG in the form of basic-block-list-p (list of basic blocks)
1. Separate the first iteration by resolving the branch statements.
The CCDFG is now in the form = (list pre loop) where pre is the first
iteration of sequential CCDFG. Since, we do not allow branching in between the scheduling steps,
this step also resolves the branch statements.
2. Resolve the phi statement. Future CCDFG have no phi-statements after this step.
3. Remove the necessary data hazards based on pipeline interval.
4. "Superstep construction step" to create pipelining supersteps - the pipelined CCDFG of the form
(list pre loop post)
5. Convert into a single basic-block-list-p by adding the branch statements for transitions.
Output: Pipelined CCDFG in the form of basic-block-list-p

******************************************************************************************
* Current Status
******************************************************************************************

The main correctness theorem is in file
seq-pp-equivalence.lisp. At present, we have shown that if
we can create a pipelined CCDFG using the superstep
construction function (no hazards) without any error, the
invariant is true. Also, that invariant implies correctness
statement is true.

The proof is a sketch that can be submitted to ACL2 to prove
our correctness criteria of loop pipelines.
Note that theorem related to no-conflict is "skip-proof"-ed.
It relates to proving that if there are no data hazards and
no branches in two adjacent blocks, then the order of execution
of the two blocks does not matter.
We have used this as an assumption currently as our focus was
on proving that if we can create a pipelined CCDFG when there
are no data-hazards, then our algorithm follows the invariant.

The functions for superstep construction step are in
"superstep-construction.lisp". It involves first creating
pipeline prologue, full pipeline and epilogue.

****************************************************************************************
  Loading "MakeFile.lisp" loads and certifies the entire code.
****************************************************************************************

"Makefile.lisp" loads a sequence of files each of which are explained below:

The first file "functions.lisp" contains the functions to
define the syntax of a CCDFG. It also contains functions to
combine the two iterations as required in parallel
execution.

"semantics.lisp" contains the functions to define the
semantics of execution of a CCDFG.

"general-theorems.lisp" contains the common theorems to be
used related to branches, phi-statements, execution of a
CCDFG etc.

"superstep-construction.lisp" contains the functions to create a pipelined CCDFG.

"seq-pp-equivalence.lisp" contains the formalization and
proof of the invariant and the correctness statement.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

SOME DETAILS ON HOW TO READ THE DEFINITIONS

A Glimpse of the main functions:

As part of testing, see the constant *seq-ccdfg* which is the sequential CCDFG
of the form (list pre loop).

We can check that it is a seq-ccdfg with no phi or branch statements

ACL2 !>VALUE (seq-ccdfg-p *seq-ccdfg*)
T

ACL2 !>VALUE (phi-restriction-ccdfg (car *seq-ccdfg*))
T
ACL2 !>VALUE (branch-restriction-ccdfg (car *seq-ccdfg*))
T

We can apply the superstep construction function to create the prologue, pipeline full
and epilogue CCDFG's

For example, for prologue:
ACL2 !>VALUE (pre-supersteps-in-parallel 2 (car *seq-ccdfg*) (second *seq-ccdfg*) 1)

||#
