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	%$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 $.