manual/c_fpa0/c_fpa0.tex

%$Header: /home/dashley/cvsrep/uculib01/uculib01/doc/manual/c_fpa0/c_fpa0.tex,v 1.4 2010/02/22 15:40:28 dashley Exp $

\chapter{Fixed-Point Arithmetic Functions}

\label{cfpa0}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction and Overview}
\label{cfpa0:siov0}

TBD.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{UCU\_UINT16 [0, 1024] [0,1] Bounded Functions}
\label{cfpa0:subf0}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection[\emph{UcuFpUm1024uProjIntoRU16aRxx(\protect\mbox{\protect$\cdot$})}]
           {\emph{UcuFpUm1024uProjIntoRU16aRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
%Subsection tag:  faa1
\label{cfpa0:subf0:sfaa0}

\index{UcuFpUm1024uProjIntoRU16aRxx()@\emph{UcuFpUm1024uProjIntoRU16aRxx($\cdot$)}}%

\noindent\textbf{PROTOTYPE}
\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item
\begin{verbatim}
UCU_UINT16 UcuFpUm1024uProjIntoRU16aRxx(
                                       UCU_UINT16 x, 
                                       UCU_UINT16 x_max, 
                                       )
\end{verbatim}
\end{list}
\vspace{2.8ex}

\noindent\textbf{SYNOPSIS}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item Linearly scales from $[0, x_{max}]$ to $[0, 1024]$, rounding the result
      to the nearest integer with a downward bias.  The result calculated is
      $\displaystyle{\left\lfloor \frac{1024 x + \left\lfloor \displaystyle{\frac{x_{max} - 1}{2}} \right\rfloor}{x_{max}} \right\rfloor}$,
      with the provision that the function output will never exceed 1024.
\end{list}
\vspace{2.8ex}

\noindent\textbf{INPUTS}
\begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
\item \emph{\textbf{x}}\\
      The input to scale.
\item \emph{\textbf{x\_max}}\\
      The value of $x$ that should correspond to 1024.
\end{list}
\vspace{2.8ex}

\noindent\textbf{OUTPUT}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item $\displaystyle{\left\lfloor \frac{1024 x + \left\lfloor \displaystyle{\frac{x_{max} - 1}{2}} \right\rfloor}{x_{max}} \right\rfloor}$,
      with a maximum of 1024.
\end{list}
\vspace{2.8ex}

\noindent\textbf{EXCEPTION CASES}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item If $x>x_{max}$, 1024 is returned.
\item If $x_{max}=0$, 0 is returned.  (In this
      case, it isn't possible to determine the intent of
      the caller, so 0 is the safest return value.)
\end{list}
\vspace{2.8ex}

\noindent\textbf{INTERRUPT COMPATIBILITY}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item This function may be used from both non-ISR and ISR software.
\item This function is thread-safe.
\end{list}
\vspace{2.8ex}

\noindent\textbf{EXECUTION TIME}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item TBD.
\end{list}
\vspace{2.8ex}

\noindent\textbf{FUNCTION NAME MNEMONIC}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item \emph{Um1024u}: unsigned maximum-1024 unsigned.
      \emph{Proj}:    projection.
      \emph{Into}:    into.
      \emph{R}:       result rounded to nearest integer.
      \emph{U16a}:    the argument is UCU\_UINT16.
\end{list}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection[\emph{UcuFpUm1024uMulRRxx(\protect\mbox{\protect$\cdot$})}]
           {\emph{UcuFpUm1024uMulRRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
\label{cfpa0:subf0:sfaa1}

\index{UcuFpUm1024uMulRRxx()@\emph{UcuFpUm1024uMulRRxx($\cdot$)}}%

\noindent\textbf{PROTOTYPE}
\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item
\begin{verbatim}
UCU_UINT16 UcuFpUm1024uMulRRxx(
                              UCU_UINT16 x_1, 
                              UCU_UINT16 x_2, 
                              )
\end{verbatim}
\end{list}
\vspace{2.8ex}

\noindent\textbf{SYNOPSIS}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item Calculates $x_1 x_2$, treating $x_1$ and $x_2$ as fixed-point numbers with 1024 corresponding
      to 1, and with $x_1$ and $x_2$ having a maximum of 1. The output is rounded to the nearest
      integer with a slight downward bias.
\item The precise function implemented is
      \begin{equation}
      \left\lfloor \frac{min(x_1, 1024) \; min(x_2, 1024) + 511}{1024} \right\rfloor.
      \end{equation}
\item The function output cannot exceed 1024.
\end{list}
\vspace{2.8ex}

\noindent\textbf{INPUTS}
\begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
\item \emph{\textbf{x\_1}}, \emph{\textbf{x\_2}} \\
      The inputs to multiply together.
\end{list}
\vspace{2.8ex}

\noindent\textbf{OUTPUT}
\vspace{0.4ex}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item  $\displaystyle{\left\lfloor \frac{min(x_1, 1024) \; min(x_2, 1024) + 511}{1024} \right\rfloor}$.
\end{list}
\vspace{2.8ex}

\noindent\textbf{EXCEPTION CASES}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item As indicated above, $x_1$ and $x_2$ are clipped at 1024 before being used
      in the calculation.
\end{list}
\vspace{2.8ex}

\noindent\textbf{INTERRUPT COMPATIBILITY}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item This function may be used from both non-ISR and ISR software.
\item This function is thread-safe.
\end{list}
\vspace{2.8ex}

\noindent\textbf{EXECUTION TIME}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item TBD.
\end{list}
\vspace{2.8ex}

\noindent\textbf{FUNCTION NAME MNEMONIC}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item \emph{Um1024u}: unsigned maximum-1024 unsigned.
      \emph{Mul}:     multiplication.
      \emph{R}:       result is rounded to nearest integer (with slight downward bias).
\end{list}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\noindent\begin{figure}[!b]
\noindent\rule[-0.25in]{\textwidth}{1pt}
\begin{tiny}
\begin{verbatim}
$RCSfile: c_fpa0.tex,v $
$Source: /home/dashley/cvsrep/uculib01/uculib01/doc/manual/c_fpa0/c_fpa0.tex,v $
$Revision: 1.4 $
$Author: dashley $
$Date: 2010/02/22 15:40:28 $
\end{verbatim}
\end{tiny}
\noindent\rule[0.25in]{\textwidth}{1pt}
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%$Log: c_fpa0.tex,v $
%Revision 1.4  2010/02/22 15:40:28  dashley
%Function added.
%
%Revision 1.3  2010/02/22 00:16:02  dashley
%Documentation added.
%
%Revision 1.2  2010/01/28 21:18:32  dashley
%a)Chapter start quotes removed.
%b)Aesthetic comment line added at the bottom of most files.
%
%Revision 1.1  2010/01/24 03:00:41  dashley
%Initial checkin.
%
%End of $RCSfile: c_fpa0.tex,v $.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

1	dashley	30	%$Header: /home/dashley/cvsrep/uculib01/uculib01/doc/manual/c_fpa0/c_fpa0.tex,v 1.4 2010/02/22 15:40:28 dashley Exp $
2
3			\chapter{Fixed-Point Arithmetic Functions}
4
5			\label{cfpa0}
6
7			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
8			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
9			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
10			\section{Introduction and Overview}
11			\label{cfpa0:siov0}
12
13			TBD.
14
15
16			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
17			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
19			\section{UCU\_UINT16 [0, 1024] [0,1] Bounded Functions}
20			\label{cfpa0:subf0}
21
22
23			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
24			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
25			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
26			\subsection[\emph{UcuFpUm1024uProjIntoRU16aRxx(\protect\mbox{\protect$\cdot$})}]
27			{\emph{UcuFpUm1024uProjIntoRU16aRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
28			%Subsection tag: faa1
29			\label{cfpa0:subf0:sfaa0}
30
31			\index{UcuFpUm1024uProjIntoRU16aRxx()@\emph{UcuFpUm1024uProjIntoRU16aRxx($\cdot$)}}%
32
33			\noindent\textbf{PROTOTYPE}
34			\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
35			\item
36			\begin{verbatim}
37			UCU_UINT16 UcuFpUm1024uProjIntoRU16aRxx(
38			UCU_UINT16 x,
39			UCU_UINT16 x_max,
40			)
41			\end{verbatim}
42			\end{list}
43			\vspace{2.8ex}
44
45			\noindent\textbf{SYNOPSIS}
46			\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
47			\item Linearly scales from $[0, x_{max}]$ to $[0, 1024]$, rounding the result
48			to the nearest integer with a downward bias. The result calculated is
49			$\displaystyle{\left\lfloor \frac{1024 x + \left\lfloor \displaystyle{\frac{x_{max} - 1}{2}} \right\rfloor}{x_{max}} \right\rfloor}$,
50			with the provision that the function output will never exceed 1024.
51			\end{list}
52			\vspace{2.8ex}
53
54			\noindent\textbf{INPUTS}
55			\begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
56			\item \emph{\textbf{x}}\\
57			The input to scale.
58			\item \emph{\textbf{x\_max}}\\
59			The value of $x$ that should correspond to 1024.
60			\end{list}
61			\vspace{2.8ex}
62
63			\noindent\textbf{OUTPUT}
64			\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
65			\item $\displaystyle{\left\lfloor \frac{1024 x + \left\lfloor \displaystyle{\frac{x_{max} - 1}{2}} \right\rfloor}{x_{max}} \right\rfloor}$,
66			with a maximum of 1024.
67			\end{list}
68			\vspace{2.8ex}
69
70			\noindent\textbf{EXCEPTION CASES}
71			\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
72			\item If $x>x_{max}$, 1024 is returned.
73			\item If $x_{max}=0$, 0 is returned. (In this
74			case, it isn't possible to determine the intent of
75			the caller, so 0 is the safest return value.)
76			\end{list}
77			\vspace{2.8ex}
78
79			\noindent\textbf{INTERRUPT COMPATIBILITY}
80			\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
81			\item This function may be used from both non-ISR and ISR software.
82			\item This function is thread-safe.
83			\end{list}
84			\vspace{2.8ex}
85
86			\noindent\textbf{EXECUTION TIME}
87			\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
88			\item TBD.
89			\end{list}
90			\vspace{2.8ex}
91
92			\noindent\textbf{FUNCTION NAME MNEMONIC}
93			\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
94			\item \emph{Um1024u}: unsigned maximum-1024 unsigned.
95			\emph{Proj}: projection.
96			\emph{Into}: into.
97			\emph{R}: result rounded to nearest integer.
98			\emph{U16a}: the argument is UCU\_UINT16.
99			\end{list}
100
101
102			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
103			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
104			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
105			\subsection[\emph{UcuFpUm1024uMulRRxx(\protect\mbox{\protect$\cdot$})}]
106			{\emph{UcuFpUm1024uMulRRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
107			\label{cfpa0:subf0:sfaa1}
108
109			\index{UcuFpUm1024uMulRRxx()@\emph{UcuFpUm1024uMulRRxx($\cdot$)}}%
110
111			\noindent\textbf{PROTOTYPE}
112			\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
113			\item
114			\begin{verbatim}
115			UCU_UINT16 UcuFpUm1024uMulRRxx(
116			UCU_UINT16 x_1,
117			UCU_UINT16 x_2,
118			)
119			\end{verbatim}
120			\end{list}
121			\vspace{2.8ex}
122
123			\noindent\textbf{SYNOPSIS}
124			\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
125			\item Calculates $x_1 x_2$, treating $x_1$ and $x_2$ as fixed-point numbers with 1024 corresponding
126			to 1, and with $x_1$ and $x_2$ having a maximum of 1. The output is rounded to the nearest
127			integer with a slight downward bias.
128			\item The precise function implemented is
129			\begin{equation}
130			\left\lfloor \frac{min(x_1, 1024) \; min(x_2, 1024) + 511}{1024} \right\rfloor.
131			\end{equation}
132			\item The function output cannot exceed 1024.
133			\end{list}
134			\vspace{2.8ex}
135
136			\noindent\textbf{INPUTS}
137			\begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
138			\item \emph{\textbf{x\_1}}, \emph{\textbf{x\_2}} \\
139			The inputs to multiply together.
140			\end{list}
141			\vspace{2.8ex}
142
143			\noindent\textbf{OUTPUT}
144			\vspace{0.4ex}
145			\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
146			\item $\displaystyle{\left\lfloor \frac{min(x_1, 1024) \; min(x_2, 1024) + 511}{1024} \right\rfloor}$.
147			\end{list}
148			\vspace{2.8ex}
149
150			\noindent\textbf{EXCEPTION CASES}
151			\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
152			\item As indicated above, $x_1$ and $x_2$ are clipped at 1024 before being used
153			in the calculation.
154			\end{list}
155			\vspace{2.8ex}
156
157			\noindent\textbf{INTERRUPT COMPATIBILITY}
158			\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
159			\item This function may be used from both non-ISR and ISR software.
160			\item This function is thread-safe.
161			\end{list}
162			\vspace{2.8ex}
163
164			\noindent\textbf{EXECUTION TIME}
165			\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
166			\item TBD.
167			\end{list}
168			\vspace{2.8ex}
169
170			\noindent\textbf{FUNCTION NAME MNEMONIC}
171			\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
172			\item \emph{Um1024u}: unsigned maximum-1024 unsigned.
173			\emph{Mul}: multiplication.
174			\emph{R}: result is rounded to nearest integer (with slight downward bias).
175			\end{list}
176
177
178			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
179			\noindent\begin{figure}[!b]
180			\noindent\rule[-0.25in]{\textwidth}{1pt}
181			\begin{tiny}
182			\begin{verbatim}
183			$RCSfile: c_fpa0.tex,v $
184			$Source: /home/dashley/cvsrep/uculib01/uculib01/doc/manual/c_fpa0/c_fpa0.tex,v $
185			$Revision: 1.4 $
186			$Author: dashley $
187			$Date: 2010/02/22 15:40:28 $
188			\end{verbatim}
189			\end{tiny}
190			\noindent\rule[0.25in]{\textwidth}{1pt}
191			\end{figure}
192
193			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
194			%$Log: c_fpa0.tex,v $
195			%Revision 1.4 2010/02/22 15:40:28 dashley
196			%Function added.
197			%
198			%Revision 1.3 2010/02/22 00:16:02 dashley
199			%Documentation added.
200			%
201			%Revision 1.2 2010/01/28 21:18:32 dashley
202			%a)Chapter start quotes removed.
203			%b)Aesthetic comment line added at the bottom of most files.
204			%
205			%Revision 1.1 2010/01/24 03:00:41 dashley
206			%Initial checkin.
207			%
208			%End of $RCSfile: c_fpa0.tex,v $.
209			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
210