
\chapter{How to Read this Book}
\label{ch-howto}

{\small
\begin{flushright}
Documentation: Cristina [Nov 01]
\end{flushright}
}

This book represents documentation on the design and development
of the \uqbt\ framework, a resourceable and retargetable binary
translation framework for experimentation with different types of
translations.  The documentation has not necessarily kept up to 
date, and some views of the framework have evolved throughout the
years.  The following is a summary of the main three frameworks 
that are described in different parts of this book, followed by 
a roadmap on where to find information within the chapters of this
book.  


\section{The UQBT Frameworks}
There are three main frameworks described in this book: the original 
1997 framework which were Cristina's and Norman's ideas on how to 
build a retargetable binary translation system.  
In 1999 we published a variation of the 1997 framework, the 1999 framework 
was based on the implemetation of the 1997 ideas and as such represents the 
pragmatic choices Cristina and Mike made to have the framework up and
running with several source and target machines.
The 2001 framework represents an extension of the 1999 framework, 
which mainly has tried to address the backend issues of the 
framework.  As such, four different experimental translators were 
written.  The 2001 framework represents Cristina's and Brian's 
ideas on this matter. 


\subsection{The Proposed 1997 UQBT Framework}
The UQBT framework was initially designed in 1997 by Cristina Cifuentes
and Norman Ramsey.  The main aim of the design was to allow for 
separation of machine-dependent from machine-independent concerns, 
by using specifications to describe machine-dependent information, 
and building a framework that could make use of such specifications 
in a machine-independent way.  

Figures~\ref{fig-architecture'} and~\ref{fig-dataflow'} represent the 
architecture and data flow framework of the proposed system.  This 
framework is described in Chapter~\ref{ch-uqbt-framework}, 
Section~\ref{sec-arch}.

\psfigbegin{figures/uqbt_architecture.eps}{6cm}
\psfigend{fig-architecture'}{The Proposed 1997 Architecture for UQBT} 

\psfigbegin{figures/uqbt_dataflow.eps}{10cm}
\psfigend{fig-dataflow'}{The Proposed 1997 UQBT Framework}


\subsection{The 1999 UQBT Framework}
The 1999 UQBT framework represents the original resourceable and 
retargetable implementation of the UQBT system that worked for several 
source and target machines.  This framework was designed by Cristina 
and Mike Van Emmerik, with input from students.  It was student's Trent 
Waddington's idea to try out using C as a suitable optimizer for our 
backend, we were initially using the VPO optimizer for one target 
machine only.  By using the C compiler, we would not be limited to one 
machine but instead would be able to compile for any of numerous 
target machines (we used GNU's gcc compiler).  

Figure~\ref{fig-uqbt'} illustrates the 1999 UQBT framework, which 
is described at length in Chapter~\ref{ch-uqbt-framework}, 
Section~\ref{sec-framework}. 

\psfigbegin{figures/uqbtImplementation.eps}{10cm}
\psfigend{fig-uqbt'}{The 1999 UQBT Framework}


\subsection{The 2001 UQBT Framework}
The 2001 UQBT framework concentrated on creating a retargetable 
backend, the current implementation reflects the experimentation 
done with four different backends--one that generates low-level C 
code (the 1999 backend), another that generates JVML code\footnote{
JVML stands for the Java Virtual Machine Language, otherwise known 
as the Java bytecode language.}, another
that generates VPO RTLs to interface with the VPO optimizer, and 
last, a backend to generate object code without performing register
allocation to interface with an optimizer of object code (such as 
a post optimizer).  This experimentation reflects the ideas of 
Cristina and Brian in this area, as well as input from intern Manel 
Fern\'{a}ndez.  

Figure~\ref{fig-uqbt2001'} represents the existing implementation 
of the UQBT framework.  This framework is explained in 
Chapter~\ref{ch-uqbt-framework}, Section~\ref{sec-2001framework}. 

\psfigbegin{figures/uqbtOverall2001.eps}{10cm}
\psfigend{fig-uqbt2001'}{The 2001 UQBT Framework}

Figure~\ref{fig-uqbt2001-2'} illustrates the final aim of building a 
retargetable backend that was capable of supporting code generation 
at different levels of abstraction (machine code, assembly, RTL, C 
or JVML).  Most of the infrastructure is in place at present for 
this framework, however, not all pieces have been factorized in order 
to have the common view represented in the diagram.  Some of the ideas 
in this area are documented in Chapter~\ref{ch-expander}, 
Section~\ref{sec-expander}. 

\psfigbegin{figures/uqbtOverall-2001-2.eps}{10cm}
\psfigend{fig-uqbt2001-2'}{The Ideal Framework}


\section{Roadmap}
There are numerous chapters in this book, some are not even part 
of the 2001 UQBT source code distribution, however, we have kept
such chapters for their value in experiments run at some point in
time.  The documentation is also not complete, there are parts of
the system that are not documented in these chapters, for those, 
you will have to refer to the source code.  The following roadmap 
helps in understanding which parts of this book are general, 
which are part of the 2001 distribution and which are of historical 
interest. 

The first part of this book---Introduction---is a general overview of 
binary translation (Chapter~\ref{ch-bintrans}), some previous 
work in the area (Chapter~\ref{ch-prevwork}), and a summary of the 
three UQBT frameworks that were documented in the history of the 
project: the proposed 1997 framework, the 1999 implementation and
the final 2001 implementation (Chapter~\ref{ch-uqbt-framework}).  

The Frontend part describes most of 
the components of the 1999 and 2001 UQBT frameworks when these components 
where built.  The binary-file format API is described in Chapter~\ref{ch-bff}, 
the decoding of machine instructions is described in Chapter~\ref{ch-decoding},
the specification of semantics of machine instructions is described in 
Chapter~\ref{ch-ssl}, and the internal UQBT intermediate representations 
used for RTL and HRTL levels are described in Chapter~\ref{ch-ir}. 

The Analysis part deals with {\em some} of the 
analyses performed in abstracting away from machine dependent information 
(RTLs) into a high-level representation (HRTL).  The analyses that are 
described are: how to eliminate condition codes (Chapter~\ref{ch-ccmatch}), 
how to remove delayed branches from the intermediate representation 
(Chapter~\ref{ch-delay}), how to recover parameter, local variable and 
function return information at procedure call sites (Chapter~\ref{ch-call}), 
and how to perform low-level type analysis recovery (Chapter~\ref{ch-type}). 

The Backends part deals with explanations of the 
four different backends that are implemented in the 2001 UQBT framework. 
These are: the original 1999 (low-level) C backend (Chapter~\ref{ch-cbackend}),
the 1999 and 2000 JVML backends (Chapter~\ref{ch-jvm}), the 
1998 and 2001 VPO backends (Chapter~\ref{ch-vpobackend}), and the object code
backend as well as the design of a retargetable 
backend (Chapter~\ref{ch-expander}).  There is also a standalone chapter 
on how to use the New Jersey Machine Code toolkit for encoding purposes, 
the chapter is a standalone experimentation with encoding of assembly 
code dynamically (Chapter~\ref{ch-njmcencoding}).  

The Results part of the book presents results of 5 initial experimental 
translators (SPARC to SPARC, SPARC to Pentium, Pentium to SPARC, Pentium 
to Pentium, and SPARC to JVML); the results were collected in Sep 1999 
(Chapter~\ref{ch-results}).  Chapter~\ref{ch-instantiation} provides 
guidelines on how to instantiate a new translator using the UQBT 
framework, Chapter~\ref{ch-experience} contains notes from 1999 and 
2001 on our experiences with building new frontends or backends for 
the UQBT framework. Last, Chapter~\ref{ch-debugging} has some notes on 
ways to tackle debugging in the UQBT framework, as no built-in debugging 
support exists in the framework. 

The Runtime Support part is slim and outdated, it contains notes from 
early 1999 on an interpreter that was built in that year; that interpreter
is not part of the distribution as it is obsolete 
(Chapter~\ref{ch-interpreter}).  

The only Appendix that is left deals with how to configure the UQBT 
framework to instantiate a particular translator.  These notes were 
written in 2001 after we stopped using multiple Makefiles and decided to 
use the \texttt{configure} system to generate our Makefile.  There is 
also information on how to run the regression test suite.

This book has not documented the graphical interface of the system, 
which was written in early 2000 using the tcl/tk system.  You will 
find this interface in the \texttt{gui} directory of the 2001 UQBT 
distribution.  The GUI allows for translations across some types of 
machines, and it produces its output in text and graphical forms. 
To run it, emit the following command:
\begin{verbatim}
     wish uqbt.tcl
\end{verbatim}

For most of the time, we used the UQBT system in a command-line 
fashion, as described in the Appendix.   


