manual/comps/workprfa.tex

%$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 $.
1	dashley	30	%$Header: /home/dashley/cvsrep/uculib01/uculib01/doc/manual/comps/workprfa.tex,v 1.14 2010/03/16 21:56:02 dashley Exp $
2			\chapter{Preface}
3
4			The product described in this document, the
5			\emph{\productbasenamelong{} Version \productversion{}}
6			(identified more compactly as
7			\emph{\productbasenameshort{}-\productversion{}}\footnote{Mnemonic:
8			\emph{microcontroller} is often abbreviated \emph{uC} or $\mu$\emph{C}, hence the
9			loose acronym \emph{\productbasenameshort{}} for \emph{\productbasenamelong{}}.}),
10			is an open-source utility library for inexpensive microcontrollers
11			and microprocessors.
12
13			The functions provided in \emph{\productbasenameshort{}} fall into these categories:
14
15			\begin{itemize}
16			\item Arithmetic.
17			\item Bounded arithmetic.
18			\item Fixed-point arithmetic.
19			\item Large-operand and extended-precision arithmetic.
20			\item Block memory operations.
21			\item Bit-mapped set functions.
22			\item Searching.
23			\item Sorting.
24			\item Array manipulation.
25			\item Linear filters.
26			\item Non-linear filters.
27			\item Vertical counters.
28			\item Control system components.
29			\item CRC, checksums, and non-cryptographic hashes.
30			\item Cryptographic hashes.
31			\item Ciphers.
32			\item Miscellaneous functions.
33			\item Utility functions.
34			\item Speed-enhanced development tool replacement functions.
35			\end{itemize}
36
37			\emph{\productbasenameshort{}-\productversion{}}
38			is packaged as two libraries, each with
39			a different purpose:
40
41			\begin{itemize}
42			\item The \index{general library}``general library'' contains functions not normally provided
43			with development tools. The general library is described by
44			every chapter in this document except Chapter \ref{csef0}.
45			\item The \index{replacement library}``replacement library'' contains
46			speed-enhanced replacements
47			for functions packaged with development tools, in those cases
48			where some optimization could be performed or where an alternate
49			and faster algorithm is known. The replacement library is covered by
50			Chapter \ref{csef0}. Functions in the replacement library
51			generally are designed to boost speed at the expense of program
52			memory and/or RAM\@. Use of the replacement library is optional.
53			The replacement library may not exist for all platforms.
54			\end{itemize}
55
56			\emph{\textbf{Part I: General Information}} provides introductory
57			and general information about \emph{\productbasenameshort{}}.
58
59			\begin{itemize}
60			\item \emph{\textbf{Chapter \ref{ciov0}: Introduction and Overview}}
61			provides an overview of \emph{\productbasenameshort{}},
62			including naming conventions and usage.
63			\end{itemize}
64
65			\emph{\textbf{Part II: Library Documentation}} describes
66			usage of the library and the actual library functions.
67
68			\begin{itemize}
69			\item \emph{\textbf{Chapter \ref{cuuc0}: How to Use \productbasenameshort{}}}
70			explains how to use \productbasenameshort{} in a project.
71			\item \emph{\textbf{Chapter \ref{cafn0}: Arithmetic Functions}}
72			documents arithmetic functions.
73			\item \emph{\textbf{Chapter \ref{cbaf0}: Bounded Arithmetic Functions}}
74			documents arithmetic functions that clip at extremes or operate in
75			a restricted range.
76			\item \emph{\textbf{Chapter \ref{cfpa0}: Fixed-Point Arithmetic Functions}}
77			documents arithmetic functions that use representions of rational or real
78			numbers as integers with the radix point shifted to the left or right.
79			\item \emph{\textbf{Chapter \ref{claf0}: Large-Operand and Extended-Precision Arithmetic Functions}}
80			documents functions that perform arithmetic on operands
81			larger than are natively handled by the machine or the compiler; or
82			calculate with extended precision.
83			\item \emph{\textbf{Chapter \ref{cbmf0}: Block Memory Functions}}
84			documents functions that operate on blocks of memory
85			(setting, copying, shifting, etc.).
86			\item \emph{\textbf{Chapter \ref{cbsf0}: Bit-Mapped Set Functions}}
87			documents functions that operate on sets represented
88			as arrays of bits.
89			\item \emph{\textbf{Chapter \ref{csea0}: Search Functions}}
90			documents functions that perform searches; such as linear searches
91			and binary searches.
92			\item \emph{\textbf{Chapter \ref{csol0}: Sort Functions}}
93			documents functions re-order arrays.
94			\item \emph{\textbf{Chapter \ref{cami0}: Array Manipulation Functions}}
95			documents functions that manipulate arrays.
96			\item \emph{\textbf{Chapter \ref{clfi0}: Linear Filter Functions}}
97			documents functions that implement classic discrete-time linear filters.
98			\item \emph{\textbf{Chapter \ref{cnfi0}: Non-Linear Filter Functions}}
99			documents functions that implement non-linear discrete-time filters.
100			\item \emph{\textbf{Chapter \ref{cvco0}: Vertical Counter Functions}}
101			documents functions that implement vertical counters.
102			\item \emph{\textbf{Chapter \ref{ccso0}: Control System Components}}
103			documents functions that implement control system components such as
104			integrators and differentiators.
105			\item \emph{\textbf{Chapter \ref{ccrc0}: CRC, Checksum, and Non-Cryptographic Hash Functions}}
106			documents functions that calculate and manipulate
107			CRCs, checksums, and non-cryptographic hashes.
108			\item \emph{\textbf{Chapter \ref{ccrh0}: Cryptographic Hash Functions}}
109			documents functions that implement cryptographic hashes.
110			\item \emph{\textbf{Chapter \ref{ccip0}: Cipher Functions}}
111			documents functions that encrypt and decrypt data.
112			\item \emph{\textbf{Chapter \ref{cmsc0}: Miscellaneous Functions}}
113			documents functions that implement well-defined mappings but could not
114			be easily classified elsewhere.
115			\item \emph{\textbf{Chapter \ref{cnef0}: Utility Functions}}
116			documents functions that provide useful non-data-driven
117			functionality.
118			\item \emph{\textbf{Chapter \ref{csef0}: Speed-Enhanced Development Tool Replacement Functions}}
119			documents functions that may optionally be used to
120			boost the speed of the functions packaged with the development tool suite.
121			\end{itemize}
122
123			\emph{\textbf{Part III: Technical Background}} provides
124			ancillary technical information useful in understanding
125			the library.
126
127			\begin{itemize}
128			\item \emph{\textbf{Chapter \ref{ctbg0}: Technical Background}}
129			provides technical background on a variety of miscellaneous
130			topics where the amount of material to be presented
131			is small (i.e. a full chapter is not required).
132			\item \emph{\textbf{Chapter \ref{crla1}: Rational Linear Approximation}}
133			provides background and algorithms surrounding approximating
134			a function $f(x) = r_I x$ [where $r_I \in\vworkrealsetnonneg$]
135			by a function
136			$g(x) = \lfloor hx/k \rfloor$ (where
137			$h, k \in \vworkintsetnonneg$)\@.
138			Choosing $h$ and $k$ so as to place
139			$r_A = h/k$ as close as possible to $r_I$
140			subject to the constraints of a processor's
141			typical integer multiplication and division instructions is not a trivial
142			problem, and the necessary results from number theory
143			are presented.
144			\end{itemize}
145
146			\emph{\textbf{Part IV: Developer Information}} provides
147			information about building the library from source code and
148			extending the library.
149
150			\begin{itemize}
151			\item \emph{\textbf{Chapter \ref{cbpc0}: \productbasenameshort{} Build Procedures}}
152			documents how \emph{\productbasenameshort{}}
153			is built from source code.
154			\end{itemize}
155
156			%\emph{\textbf{Part V: Procedures and Checklists}} provides
157			%procedures and checklists for tasks where the procedure or
158			%checklist did not naturally fit into a different section
159			%of this document.
160			%
161			%%\begin{itemize}
162			%\item \emph{\textbf{Chapter \ref{cpck0}: Procedures and Checklists}}
163			% defines procedures and checklists that aren't most naturally
164			% placed elsewhere in this document.
165			%\end{itemize}
166
167			\emph{\textbf{Part V: Appendices, Bibliography, and Index}} provides
168			glossaries, references, and an index.
169			Individuals, products, companies, websites, and Internet newsgroups
170			are cited in the same framework
171			as traditional references in order to provide the reader with more
172			resources to obtain information.
173
174			Please feel free to contact me at \texttt{dashley@gmail.com} with
175			any suggestions for the \emph{\productbasenameshort{}}
176			library or associated documentation.
177
178			\vspace*{0.5in}
179
180			\noindent{}\hspace*{75mm}David T. Ashley \\
181			\hspace*{75mm}Marshall, Michigan, USA \\
182			\hspace*{75mm}January, 2010 \\
183
184			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
185
186			\noindent\begin{figure}[!b]
187			\noindent\rule[-0.25in]{\textwidth}{1pt}
188			\begin{tiny}
189			\begin{verbatim}
190			$RCSfile: workprfa.tex,v $
191			$Source: /home/dashley/cvsrep/uculib01/uculib01/doc/manual/comps/workprfa.tex,v $
192			$Revision: 1.14 $
193			$Author: dashley $
194			$Date: 2010/03/16 21:56:02 $
195			\end{verbatim}
196			\end{tiny}
197			\noindent\rule[0.25in]{\textwidth}{1pt}
198			\end{figure}
199
200			%$Log: workprfa.tex,v $
201			%Revision 1.14 2010/03/16 21:56:02 dashley
202			%Edits and corrections.
203			%
204			%Revision 1.13 2010/01/27 21:52:15 dashley
205			%Edits.
206			%
207			%Revision 1.12 2010/01/27 17:08:42 dashley
208			%Information about the general library versus the replacement library
209			%added.
210			%
211			%Revision 1.11 2010/01/26 18:52:39 dashley
212			%Edits.
213			%
214			%Revision 1.10 2010/01/26 16:16:18 dashley
215			%Edits.
216			%
217			%Revision 1.9 2010/01/24 05:56:25 dashley
218			%Edits.
219			%
220			%Revision 1.8 2010/01/24 05:37:27 dashley
221			%Addition and reorganization of content.
222			%
223			%Revision 1.7 2007/11/06 16:09:57 dtashley
224			%Addition of two chapters.
225			%
226			%Revision 1.6 2007/10/08 18:16:34 dtashley
227			%Edits.
228			%
229			%Revision 1.5 2007/10/07 04:59:51 dtashley
230			%Edits.
231			%
232			%Revision 1.4 2007/10/06 23:54:50 dtashley
233			%Edits.
234			%
235			%Revision 1.3 2007/10/06 22:54:43 dtashley
236			%Edits.
237			%
238			%Revision 1.2 2007/09/27 22:54:33 dtashley
239			%Edits.
240			%
241			%Revision 1.1 2007/08/30 02:58:09 dtashley
242			%Initial checkin.
243			%
244			%End of $RCSfile: workprfa.tex,v $.