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