%$Header: /home/dashley/cvsrep/uculib01/uculib01/doc/manual/comps/workprfa.tex,v 1.14 2010/03/16 21:56:02 dashley Exp $
\chapter{Preface}

The product described in this document, the 
\emph{\productbasenamelong{} Version \productversion{}}
(identified more compactly as 
\emph{\productbasenameshort{}-\productversion{}}\footnote{Mnemonic:
\emph{microcontroller} is often abbreviated \emph{uC} or $\mu$\emph{C}, hence the
loose acronym \emph{\productbasenameshort{}} for \emph{\productbasenamelong{}}.}),
is an open-source utility library for inexpensive microcontrollers
and microprocessors.

The functions provided in \emph{\productbasenameshort{}} fall into these categories:

\begin{itemize}
\item Arithmetic.
\item Bounded arithmetic.
\item Fixed-point arithmetic.
\item Large-operand and extended-precision arithmetic.
\item Block memory operations.
\item Bit-mapped set functions.
\item Searching.
\item Sorting.
\item Array manipulation.
\item Linear filters.
\item Non-linear filters.
\item Vertical counters.
\item Control system components.
\item CRC, checksums, and non-cryptographic hashes.
\item Cryptographic hashes.
\item Ciphers.
\item Miscellaneous functions.
\item Utility functions.
\item Speed-enhanced development tool replacement functions.
\end{itemize}

\emph{\productbasenameshort{}-\productversion{}}
is packaged as two libraries, each with
a different purpose:

\begin{itemize}
\item The \index{general library}``general library'' contains functions not normally provided
      with development tools.  The general library is described by
      every chapter in this document except Chapter \ref{csef0}.
\item The \index{replacement library}``replacement library'' contains
      speed-enhanced replacements
      for functions packaged with development tools, in those cases
      where some optimization could be performed or where an alternate
      and faster algorithm is known.  The replacement library is covered by 
      Chapter \ref{csef0}.  Functions in the replacement library
      generally are designed to boost speed at the expense of program
      memory and/or RAM\@.  Use of the replacement library is optional.
      The replacement library may not exist for all platforms.
\end{itemize}

\emph{\textbf{Part I: General Information}} provides introductory
and general information about \emph{\productbasenameshort{}}.

\begin{itemize}
\item \emph{\textbf{Chapter \ref{ciov0}: Introduction and Overview}}
      provides an overview of \emph{\productbasenameshort{}},
      including naming conventions and usage.
\end{itemize}

\emph{\textbf{Part II: Library Documentation}} describes
usage of the library and the actual library functions.

\begin{itemize}
\item \emph{\textbf{Chapter \ref{cuuc0}: How to Use \productbasenameshort{}}}
      explains how to use \productbasenameshort{} in a project.
\item \emph{\textbf{Chapter \ref{cafn0}: Arithmetic Functions}}
      documents arithmetic functions.
\item \emph{\textbf{Chapter \ref{cbaf0}: Bounded Arithmetic Functions}}
      documents arithmetic functions that clip at extremes or operate in
      a restricted range.
\item \emph{\textbf{Chapter \ref{cfpa0}: Fixed-Point Arithmetic Functions}}
      documents arithmetic functions that use representions of rational or real
      numbers as integers with the radix point shifted to the left or right.
\item \emph{\textbf{Chapter \ref{claf0}: Large-Operand and Extended-Precision Arithmetic Functions}}
      documents functions that perform arithmetic on operands
      larger than are natively handled by the machine or the compiler; or
      calculate with extended precision.
\item \emph{\textbf{Chapter \ref{cbmf0}: Block Memory Functions}}
      documents functions that operate on blocks of memory
      (setting, copying, shifting, etc.).
\item \emph{\textbf{Chapter \ref{cbsf0}: Bit-Mapped Set Functions}}
      documents functions that operate on sets represented
      as arrays of bits.
\item \emph{\textbf{Chapter \ref{csea0}: Search Functions}}
      documents functions that perform searches; such as linear searches
      and binary searches.
\item \emph{\textbf{Chapter \ref{csol0}: Sort Functions}}
      documents functions re-order arrays.
\item \emph{\textbf{Chapter \ref{cami0}: Array Manipulation Functions}}
      documents functions that manipulate arrays.
\item \emph{\textbf{Chapter \ref{clfi0}: Linear Filter Functions}}
      documents functions that implement classic discrete-time linear filters.
\item \emph{\textbf{Chapter \ref{cnfi0}: Non-Linear Filter Functions}}
      documents functions that implement non-linear discrete-time filters.
\item \emph{\textbf{Chapter \ref{cvco0}: Vertical Counter Functions}}
      documents functions that implement vertical counters.
\item \emph{\textbf{Chapter \ref{ccso0}: Control System Components}}
      documents functions that implement control system components such as 
      integrators and differentiators.
\item \emph{\textbf{Chapter \ref{ccrc0}: CRC, Checksum, and Non-Cryptographic Hash Functions}}
      documents functions that calculate and manipulate
      CRCs, checksums, and non-cryptographic hashes.
\item \emph{\textbf{Chapter \ref{ccrh0}: Cryptographic Hash Functions}}
      documents functions that implement cryptographic hashes.
\item \emph{\textbf{Chapter \ref{ccip0}: Cipher Functions}}
      documents functions that encrypt and decrypt data.
\item \emph{\textbf{Chapter \ref{cmsc0}: Miscellaneous Functions}}
      documents functions that implement well-defined mappings but could not
      be easily classified elsewhere.
\item \emph{\textbf{Chapter \ref{cnef0}: Utility Functions}}
      documents functions that provide useful non-data-driven
      functionality.
\item \emph{\textbf{Chapter \ref{csef0}: Speed-Enhanced Development Tool Replacement Functions}}
      documents functions that may optionally be used to 
      boost the speed of the functions packaged with the development tool suite.
\end{itemize}

\emph{\textbf{Part III: Technical Background}} provides 
ancillary technical information useful in understanding
the library.

\begin{itemize}
\item \emph{\textbf{Chapter \ref{ctbg0}: Technical Background}}
      provides technical background on a variety of miscellaneous
      topics where the amount of material to be presented
      is small (i.e. a full chapter is not required).
\item \emph{\textbf{Chapter \ref{crla1}: Rational Linear Approximation}}
      provides background and algorithms surrounding approximating
      a function $f(x) = r_I x$ [where $r_I \in\vworkrealsetnonneg$]
      by a function 
      $g(x) = \lfloor hx/k \rfloor$ (where
      $h, k \in \vworkintsetnonneg$)\@.
      Choosing $h$ and $k$ so as to place
      $r_A = h/k$ as close as possible to $r_I$ 
      subject to the constraints of a processor's
      typical integer multiplication and division instructions is not a trivial
      problem, and the necessary results from number theory
      are presented.
\end{itemize}

\emph{\textbf{Part IV: Developer Information}} provides 
information about building the library from source code and
extending the library.

\begin{itemize}
\item \emph{\textbf{Chapter \ref{cbpc0}: \productbasenameshort{} Build Procedures}}
      documents how \emph{\productbasenameshort{}}
      is built from source code.
\end{itemize}

%\emph{\textbf{Part V: Procedures and Checklists}} provides 
%procedures and checklists for tasks where the procedure or
%checklist did not naturally fit into a different section
%of this document.
%
%%\begin{itemize}
%\item \emph{\textbf{Chapter \ref{cpck0}: Procedures and Checklists}}
%      defines procedures and checklists that aren't most naturally
%      placed elsewhere in this document.
%\end{itemize}

\emph{\textbf{Part V: Appendices, Bibliography, and Index}} provides
glossaries, references, and an index.
Individuals, products, companies, websites, and Internet newsgroups
are cited in the same framework
as traditional references in order to provide the reader with more
resources to obtain information.

Please feel free to contact me at \texttt{dashley@gmail.com} with
any suggestions for the \emph{\productbasenameshort{}}
library or associated documentation.

\vspace*{0.5in}

\noindent{}\hspace*{75mm}David T. Ashley                \\
           \hspace*{75mm}Marshall, Michigan, USA        \\
           \hspace*{75mm}January, 2010                  \\

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\noindent\begin{figure}[!b]
\noindent\rule[-0.25in]{\textwidth}{1pt}
\begin{tiny}
\begin{verbatim}
$RCSfile: workprfa.tex,v $
$Source: /home/dashley/cvsrep/uculib01/uculib01/doc/manual/comps/workprfa.tex,v $
$Revision: 1.14 $
$Author: dashley $
$Date: 2010/03/16 21:56:02 $
\end{verbatim}
\end{tiny}
\noindent\rule[0.25in]{\textwidth}{1pt}
\end{figure}

%$Log: workprfa.tex,v $
%Revision 1.14  2010/03/16 21:56:02  dashley
%Edits and corrections.
%
%Revision 1.13  2010/01/27 21:52:15  dashley
%Edits.
%
%Revision 1.12  2010/01/27 17:08:42  dashley
%Information about the general library versus the replacement library
%added.
%
%Revision 1.11  2010/01/26 18:52:39  dashley
%Edits.
%
%Revision 1.10  2010/01/26 16:16:18  dashley
%Edits.
%
%Revision 1.9  2010/01/24 05:56:25  dashley
%Edits.
%
%Revision 1.8  2010/01/24 05:37:27  dashley
%Addition and reorganization of content.
%
%Revision 1.7  2007/11/06 16:09:57  dtashley
%Addition of two chapters.
%
%Revision 1.6  2007/10/08 18:16:34  dtashley
%Edits.
%
%Revision 1.5  2007/10/07 04:59:51  dtashley
%Edits.
%
%Revision 1.4  2007/10/06 23:54:50  dtashley
%Edits.
%
%Revision 1.3  2007/10/06 22:54:43  dtashley
%Edits.
%
%Revision 1.2  2007/09/27 22:54:33  dtashley
%Edits.
%
%Revision 1.1  2007/08/30 02:58:09  dtashley
%Initial checkin.
%
%End of $RCSfile: workprfa.tex,v $.