%
% perf.tex - the final performance report which includes the rest
%   of the data.
% 
% Copyright (c) 1998 Phil Maker <pjm@gnu.org>
% All rights reserved.
%
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions
% are met:
% 1. Redistributions of source code must retain the above copyright
%    notice, this list of conditions and the following disclaimer.
% 2. Redistributions in binary form must reproduce the above copyright
%    notice, this list of conditions and the following disclaimer in the
%    documentation and/or other materials provided with the distribution.
%
% THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
% ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
% IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
% ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
% FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
% DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
% OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
% HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
% LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
% OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
% SUCH DAMAGE.
%
% $Id: perf.tex,v 1.1.1.1 1999/09/12 03:26:49 pjm Exp $
%

\documentclass[a4paper]{article}

\begin{document}
\title{Nana Performance Summary}
\author{P.J.Maker}
\maketitle

This document contains some measurements for the space and time costs
for the nana library. Data provided includes:

\begin{itemize}
\item Time cost in ns. 
\item Space in bytes.
\item Generated assembler code.
\item Results for various compiler options such as optimisation. 
\end{itemize}

These test results were generated using:

\begin{itemize}
\item Operating System, release and cpu: \input{uname.mtex}
\item CPU speed is analysed by the supplied \verb+bogomips+ program
  which gives a value of \input{bogomips.mtex}. BogoMips (bogus
  millions of instructions per seconds) are a standard unit of measure
  invented by Linus Torvalds for use in Linux. They represent something
  vaguely related to the number of instructions executed per second.
\item Note: nana should be installed using \verb|I_DEFAULT=fast ./configure|
for these measurements.
\end{itemize}

The following table contains a summary of the results:

    \input{summary.mtex}    

Note:

\begin{itemize}
\item \verb|assert()| is your systems standard assert macro.
\item \verb|TRAD_assert()| is the traditional implementation of assert
  which calls \verb|fprintf()| and \verb|exit()| directly.
\item \verb|I()| is the nana equivelant of \verb|assert|.
\item \verb|DI()| is implemented using the debugger. It is very space efficent
  but takes longer than inline C code (such as \verb|I()|).
\item \verb|I(A(...))| is checking that all 10 values in the array
  \verb|a| are positive. 
\item \verb|now()| measures the current time and returns a |double|
  value.
\item \verb|L()| optionally prints a debugging message.
\item \verb|DL()| is the debugger equivelant of \verb|L()|. 
\end{itemize}

Note that measurement code depends on GNU CC extensions and is not
a thing of great beauty. 

\section{How was is it measured?}

See \verb|Makefile.am| and \verb|measure.sh| for the true story, a
quick summary would be:

\begin{itemize}
\item The code fragments are stored one per line in a file such 
  as \verb|summary.tst|. 
\item The \verb|measure.sh| program takes as arguments a set of
  compiler flags such as \verb|-O| which are used for each line
  in the input file.
\item The code fragment is copied 256 times by a macro inside a 
  loop which in turn executes 1024 times. For small examples 
  it is expected that the entire loop will fit inside the cache.
\item Time is measured using the nana \verb|now()| function.
\end{itemize}

The variables and code fragments used defined in \verb|prelude.c|
and \verb|postlude.c|. All variables are declared \verb|volatile|
to prevent the compile optimising access to variables.

In addition all programs are compiled with the following options:

\begin{itemize}
\item \verb|-g| -- debugger information is always turned on since we
  need it for parts of the nana library. Note that \verb|gcc| happily 
  optimises code with \verb|-g| enabled.
\item \verb|-fno-defer-pop| -- \verb|gcc| by default only pops
  arguments off the stack after a number of calls. This option 
  causes each call to immediately pop its arguments off the stack.
\end{itemize}

\section{Detailed results}
This section contains some more detailed results.

\subsection{Assert}
\input{assert.mtex}

\subsection{Quantifiers}
\input{quantifiers.mtex}

\subsection{Log}
\input{log.mtex}

\subsection{Nop}
\input{nop.mtex}

\subsection{C Operations}
\input{c_ops.mtex}

\subsection{Data cache testing}
These are are just some tests using a large array which should
hopefully exceed the size of the D-cache on your machine.

\input{dcache.mtex}

\section{Code}
This section contains a listing of all the generated code fragments. 

\begin{itemize}
\input{code.mtex}
\end{itemize}

\section{Conclusion}
Finally, if you have used this package on an interesting (or
uninteresting) architecture please mail me a copy of the results for
the nana home page. 

\end{document}
