manual/c_afn0/c_afn0.tex

%$Header: /home/dashley/cvsrep/uculib01/uculib01/doc/manual/c_afn0/c_afn0.tex,v 1.37 2010/05/12 18:35:49 dashley Exp $

\chapter{Arithmetic Functions}

\label{cafn0}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction and Overview}
%Section tag:  iov0
\label{cafn0:siov0}

This chapter documents functions that perform arithmetic.

\begin{itemize}
\item \S{}\ref{cafn0:sscx0} (p. \pageref{cafn0:sscx0}) documents
      functions that compare UCU\_UINT16 data.
\item \S{}\ref{cafn0:slsf0} (p. \pageref{cafn0:slsf0}) documents
      functions that calculate or approximate functions of the form
      $y=mx$, where $y$ is a UCU\_UINT16.
\item \S{}\ref{cafn0:ssre0} (p. \pageref{cafn0:ssre0}) documents
      functions that calculate or approximate square roots.
\end{itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{UCU\_UINT16 Comparison Functions}
%Section tag:  scx0
\label{cafn0:sscx0}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection[\emph{UcuAtU16CmpDiffAbsGtRxx(\protect\mbox{\protect$\cdot$})}]
           {\emph{UcuAtU16CmpDiffAbsGtRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
%Subsection tag:  csx0
\label{cafn0:sscx0:scsx0}

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

\noindent\textbf{PROTOTYPE}
\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item
\begin{verbatim}
UCU_BOOLEAN UcuAtU16CmpDiffAbsGtRxx(
                                   UCU_UINT16 x1,
                                   UCU_UINT16 x2,
                                   UCU_UINT16 d
                                   )
\end{verbatim}
\end{list}
\vspace{2.8ex}

\noindent\textbf{SYNOPSIS}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item Returns UCU\_TRUE if $|x_1-x_2|>d$, or UCU\_FALSE otherwise.
\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{x1}}, \emph{\textbf{x2}}\\
      The UCU\_UINT16 arguments to compare.
\item \emph{\textbf{d}}\\
      The comparison threshold.
\end{list}
\vspace{2.8ex}

\noindent\textbf{OUTPUT}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item UCU\_TRUE if $|x_1-x_2|>d$, or UCU\_FALSE otherwise.
\end{list}
\vspace{2.8ex}

\noindent\textbf{DETAILED DESCRIPTION}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item \emph{UcuAtU16CmpDiffAbsGtRxx($\cdot$)} determines whether 
      $x_1$ and $x_2$ are more than $d$ apart.
\item The function is
      typically used to detect change in a value (either negative or positive)
      of a magnitude greater than $d$,
      or to determine if two values are within $d$ of each other.
\item \emph{UcuAtU16CmpDiffAbsGtRxx($\cdot$)} is symmetric with
      respect to its arguments:  $f(x_1, x_2) \equiv f(x_2, x_1)$.
\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{U16}:  arguments and return type are UCU\_UINT16.
      \emph{Cmp}: compare.
      \emph{Diff}:  difference.
      \emph{Abs}: absolute value.
      \emph{Gt}:  greater than.
\end{list}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\section{UCU\_SINT32 Complement and Negation Functions}
%\label{cafn0:scnf0}
%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\subsection[\emph{UcuAtS32NegationRxx(\protect\mbox{\protect$\cdot$})}]
%           {\emph{UcuAtS32NegationRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
%\label{cafn0:scnf0:sstf0}
%
%\index{UcuAtS32NegationRxx()@\emph{UcuAtS32NegationRxx($\cdot$)}}%
%
%\noindent\textbf{PROTOTYPE}
%\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item
%\begin{verbatim}
%UCU_SINT32 UcuAtS32NegationRxx( UCU_SINT32 x )
%\end{verbatim}
%\end{list}
%\vspace{2.8ex}
%
%\noindent\textbf{SYNOPSIS}
%\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item Returns the 1's complement of $x$, plus 1.  In most cases, this represents
%      $-x$, but $-2^{31}$ (the most negative representable value) maps to
%      $-2^{31}$ (this is a standard feature of the 2's complement representation of signed
%      integers).
%\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 UCU\_SINT32 integer to negate.
%\end{list}
%\vspace{2.8ex}
%
%\noindent\textbf{OUTPUT}
%\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item The 1's complement of $x$, plus 1
%\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{Negation}:  negates the argument.
%\end{list}
%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{UCU\_UINT16 Linear Scaling Functions, Zero Y-Intercept}
%Section tag:  lsf0
\label{cafn0:slsf0}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection[\emph{UcuAtU16LscZyiFAxdAxrRxx(\protect\mbox{\protect$\cdot$})}]
           {\emph{UcuAtU16LscZyiFAxdAxrRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
%Subsection tag:  faa0
\label{cafn0:slsf0:sfaa0}

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

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

\noindent\textbf{SYNOPSIS}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item Linearly scales (or projects) from $[0, x_{max}]$ to $[0, y_{max}]$,
      implementing the floor function (discarding any remainder resulting
      from the division).  The value calculated is
      $\displaystyle{\left\lfloor \frac{y_{max} x}{x_{max}} \right\rfloor}$,
      with the provision that the function output will never
      exceed $y_{max}$.

\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 $y_{max}$.
\item \emph{\textbf{y\_max}}\\
      The maximum output value of the function.
\end{list}
\vspace{2.8ex}

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

\noindent\textbf{EXCEPTION CASES}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item If $x>x_{max}$, $y_{max}$ is returned.
\item If $x_{max}=0$ or $y_{max}=0$, 0 is returned.  (In either of these
      cases, 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{U16}: operates on and returns UCU\_UINT16.
      \emph{Lsc}: linear scaling function.
      \emph{Zyi}: zero $y$ intercept.
      \emph{F}:   result floored (rather than rounded).
      \emph{Axd}: arbitrary maxima of domain.
      \emph{Axr}: arbitrary maxima of range.
\end{list}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection[\emph{UcuAtU16LscZyiRAxdAxrRxx(\protect\mbox{\protect$\cdot$})}]
           {\emph{UcuAtU16LscZyiRAxdAxrRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
%Subsection tag:  faa1
\label{cafn0:slsf0:sfaa1}

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

\noindent\textbf{PROTOTYPE}
\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item
\begin{verbatim}
UCU_UINT16 UcuAtU16LscZyiRAxdAxrRxx(
                                   UCU_UINT16 x, 
                                   UCU_UINT16 x_max, 
                                   UCU_UINT16 y_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, y_{max}]$, rounding the result
      to the nearest integer with a downward bias.  The result calculated is
      $\displaystyle{\left\lfloor \frac{y_{max} 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 $y_{max}$.
\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 $y_{max}$.
\item \emph{\textbf{y\_max}}\\
      The maximum output value of the function.
\end{list}
\vspace{2.8ex}

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

\noindent\textbf{EXCEPTION CASES}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item If $x>x_{max}$, $y_{max}$ is returned.
\item If $x_{max}=0$ or $y_{max}=0$, 0 is returned.  (In either
      of these cases, 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{U16}: operates on UCU\_UINT16 operands.
      \emph{Lsc}: linear scaling function.
      \emph{Zyi}: zero $y$ intercept.
      \emph{R}:   result rounded to nearest integer.
      \emph{Axd}: arbitrary maxima of domain.
      \emph{Axr}: arbitrary maxima of range.
\end{list}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Ratiometric Adjustment Functions}
%Section tag:  sraf0
\label{cafn0:sraf0}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection[\emph{UcuAtU16RatAdjRRxx(\protect\mbox{\protect$\cdot$})}]
           {\emph{UcuAtU16RatAdjRRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
%Subsection tag:  rat0
\label{cafn0:sraf0:srat0}

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

\noindent\textbf{PROTOTYPE}
\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item
\begin{verbatim}
UCU_UINT16 UcuAtU16RatAdjRRxx(
                             UCU_UINT16 arg, 
                             UCU_UINT16 arg_max, 
                             UCU_UINT16 adj_in, 
                             UCU_UINT16 adj_nom
                             )
\end{verbatim}
\end{list}
\vspace{2.8ex}

\noindent\textbf{SYNOPSIS}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item Ratiometrically adjusts $arg$ according to the formula
      $\displaystyle{\left\lfloor \frac{arg\;adj_{nom} + \left\lfloor \displaystyle{\frac{adj_{in} - 1}{2}} \right\rfloor}{adj_{in}} \right\rfloor}$,
      with the result then clipped at $arg_{max}$.
\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{arg}}\\
      The input to scale.
\item \emph{\textbf{arg\_max}}\\
      The maximum value of $arg$ that may be returned by the function.
\item \emph{\textbf{adj\_in}}\\
      The value of the adjustment parameter that should be used for calculation.
\item \emph{\textbf{adj\_nom}}\\
      The nominal value of the adjustment parameter that should leave $arg$ unchanged.  As
      $adj_{in}$ increases, the value returned will decrease, and vice-versa.
\end{list}
\vspace{2.8ex}

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

\noindent\textbf{EXCEPTION CASES}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item If $adj_{in}=0$ and $arg=0$, 0 is returned.
\item If $adj_{in}=0$ and $arg>0$, $arg_{max}$ is returned.
\item If $adj_{nom}=0$, 0 is returned.
\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{U16}: operates on UCU\_UINT16 operands.
      \emph{RatAdj}: ratiometric adjustment.
      \emph{R}:   result rounded to nearest integer.
\end{list}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Vector Functions, 2-Dimensional}
\label{cafn0:svft0}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\subsection[\emph{UcuAtS32S16v2CpRxx(\protect\mbox{\protect$\cdot$})}]
%           {\emph{UcuAtS32S16v2CpRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
%\label{cafn0:svft0:scpt1}
%
%\index{UcuAtS32S16v2CpRxx()@\emph{UcuAtS32S16v2CpRxx($\cdot$)}}%
%
%\noindent\textbf{PROTOTYPE}
%\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item
%\begin{verbatim}
%UCU_SINT32 UcuAtS32S16v2CpRxx(
%                             UCU_SINT16 a_x, 
%                             UCU_SINT16 a_y, 
%                             UCU_SINT16 b_x, 
%                             UCU_SINT16 b_y
%                             )
%\end{verbatim}
%\end{list}
%\vspace{2.8ex}
%
%\noindent\textbf{SYNOPSIS}
%\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item Calculates the signed magnitude of the $\hat{k}$-component of the
%      cross-product of $\vec{a}$ and $\vec{b}$:
%
%      \begin{equation}
%      \label{eq:cafn0:svft0:scpt1:01}
%      a_x b_y - a_y b_x .
%      \end{equation}
%\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{a\_x, a\_y, b\_x, b\_y}}\\
%      The $x$ and $y$ components of the two vectors.  The correct cross-product
%      will be returned over the entire domain of input arguments.
%\end{list}
%\vspace{2.8ex}
%
%\noindent\textbf{OUTPUT}
%\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item $a_x b_y - a_y b_x$.
%\end{list}
%\vspace{2.8ex}
%
%\noindent\textbf{EXCEPTION CASES}
%\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item None.
%\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{S32}:    returned value is a UCU\_SINT32.
%      \emph{S16v2}:  operates on 2-dimensional vecotrs with UCU\_SINT16 components.
%      \emph{Cp}:     cross-product.
%\end{list}
%\vspace{2.8ex}
%
%\noindent\textbf{DETAILED DESCRIPTION / ADDITIONAL INFORMATION}
%\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item The three-dimensional vector cross product is defined as
%
%      \begin{equation}
%      \label{eq:cafn0:svft0:scpt1:02}
%      \vec{a} \times \vec{b} = \left | 
%      {
%      \begin{array}{ccc}
%      \hat{i}    &     \hat{j}    &  \hat{k}    \\
%      a_x  &     a_y  &   a_z  \\
%      b_x  &     b_y  &   b_z
%      \end{array}
%      }
%      \right |.
%      \end{equation}
%\item In two dimensions ($a_z = b_z = 0$), the vector
%      cross-product is defined as
%
%      \begin{equation}
%      \label{eq:cafn0:svft0:scpt1:03}
%      \vec{a} \times \vec{b} = \left | 
%      {
%      \begin{array}{ccc}
%      \hat{i}    &     \hat{j}    &  \hat{k}    \\
%      a_x  &     a_y  &   0  \\
%      b_x  &     b_y  &   0
%      \end{array}
%      }
%      \right | = \hat{k} (a_x b_y - a_y b_x) .
%      \end{equation}
%
%      This function calculates the magnitude of the $\vec{k}$ component
%      of a 3-dimensional vector cross-product when $a_z = b_z = 0$.
%\item This function returns a maximum when $a_x = b_y = a_y = -2^{15}$
%      and $b_x = 2^{15} - 1$, leading to a maximum of $2^{31} - 2^{15}$.
%      Similarly, the minimum can be shown to be $-2^{31} + 2^{15}$\@.
%      Thus, the calculated result is always exact and always fits in a UCU\_SINT32.
%\end{list}
%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection[\emph{UcuAtU16v2CpDiva2FRxx(\protect\mbox{\protect$\cdot$})}]
           {\emph{UcuAtU16v2CpDiva2FRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
\label{cafn0:svft0:scpt0}

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

\noindent\textbf{PROTOTYPE}
\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item
\begin{verbatim}
UCU_UINT16 UcuAtU16v2CpDiva2FRxx(
                                UCU_UINT16 a_x, 
                                UCU_UINT16 a_y, 
                                UCU_UINT16 b_x, 
                                UCU_UINT16 b_y
                                )
\end{verbatim}
\end{list}
\vspace{2.8ex}

\noindent\textbf{SYNOPSIS}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item Calculates an approximation to

      \begin{equation}
      \label{eq:cafn0:svft0:scpt0:01}
      \left\lfloor \frac{| \vec{a} \times \vec{b} |}{| \vec{b} |} \right\rfloor
      = 
      \left\lfloor \frac{| \vec{a} | | \vec{b} | \sin \theta}{| \vec{b} |} \right\rfloor ,
      \end{equation}

      where $\vec{a}$ and $\vec{b}$ are in a special form as described below.
\item This function is a special purpose function and not especially portable.  In particular, the design
      of the interface is awkward.  This function will eventually be replaced in the library.
\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{a\_x, a\_y, b\_x, b\_y}}\\
      The $x$ and $y$ components of the two vectors.  Each is in ``excess-4096'' format, so that a value of 0 represents -4096, a value of 4096
      represents 0, and a value of 8192 represents 4096.

      Each of these parameters are clipped into [32, 8160] by the function before any calculation
      is performed, representing vector component values in [-4064, 4064].
\end{list}
\vspace{2.8ex}

\noindent\textbf{OUTPUT}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item   An approximation of 
        $\left\lfloor \frac{| \vec{a} \times \vec{b} |}{| \vec{b} |}\right\rfloor
        = 
        \left\lfloor\frac{| \vec{a} | | \vec{b} | \sin \theta}{| \vec{b} |}\right\rfloor$.
        The approximation is within several counts of the ideal value.
\end{list}
\vspace{2.8ex}

\noindent\textbf{EXCEPTION CASES}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item If $\vec{b} = \vec{0}$, 0 is returned.
\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{U16v2}:  operates on 2-dimensional vecotrs with UCU\_UINT16 components.
      \emph{Cp}:     cross-product.
      \emph{Diva2}:  divided by the second argument (the second vector).
      \emph{F}:      the result is floor'd.
\end{list}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\subsection[\emph{UcuAtS32S16v2CpDiva2FRxx(\protect\mbox{\protect$\cdot$})}]
%           {\emph{UcuAtS32S16v2CpDiva2FRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
%\label{cafn0:svft0:scpt2}
%
%\index{UcuAtS32S16v2CpDiva2FRxx()@\emph{UcuAtS32S16v2CpDiva2FRxx($\cdot$)}}%
%
%\noindent\textbf{PROTOTYPE}
%\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item
%\begin{verbatim}
%UCU_SINT32 UcuAtS32S16v2CpDiva2FRxx(
%                                   UCU_SINT16 a_x, 
%                                   UCU_SINT16 a_y, 
%                                   UCU_SINT16 b_x, 
%                                   UCU_SINT16 b_y
%                                   )
%\end{verbatim}
%\end{list}
%\vspace{2.8ex}
%
%\noindent\textbf{SYNOPSIS}
%\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item Calculates
%
%      \begin{equation}
%      \label{eq:cafn0:svft0:scpt2:01}
%      \left\lfloor \frac{\vec{a} \times \vec{b}}{| \vec{b} | \hat{k}} \right\rfloor ,
%      \end{equation}
%
%      where the floor function rounds negative values towards zero.  It should be noted that by definition
%
%      \begin{equation}
%      \label{eq:cafn0:svft0:scpt2:02}
%      \left\lfloor \left| \frac{\vec{a} \times \vec{b}}{| \vec{b} | \hat{k}} \right| \right\rfloor
%      =
%      \lfloor |\vec{a}| \sin \theta \rfloor ,
%      \end{equation}
%
%      where $\theta$ is the angle between $\vec{a}$ and $\vec{b}$, $0 \leq \theta \leq \pi$,
%      so that this function provides an excellent approximation to 
%      $\lfloor |\vec{a}| \sin \theta \rfloor$.
%\item For two vectors $\vec{a}$ and $\vec{b}$ that both begin at the origin,
%      the absolute value of this function's return value is
%      the floor of the shortest distance between the tip of $\vec{a}$ and the line coincident with
%      $\vec{b}$.
%\item The precise calculation method used by this function is described in
%      \S{}\ref{ctbg0:svec2} (p. \pageref{ctbg0:svec2}).
%\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{a\_x, a\_y, b\_x, b\_y}}\\
%      The $x$ and $y$ components of the two vectors.  All components are signed, and this function
%      will return correct results over the entire input domain.
%\end{list}
%\vspace{2.8ex}
%
%\noindent\textbf{OUTPUT}
%\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item $\displaystyle{\left\lfloor \frac{\vec{a} \times \vec{b}}{| \vec{b} | \hat{k}} \right\rfloor}$,
%      where the floor function rounds negative values towards zero.
%\end{list}
%\vspace{2.8ex}
%
%\noindent\textbf{EXCEPTION CASES}
%\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item None.
%\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{S32}:    the return value is UCU\_SINT32.
%      \emph{S16v2}:  operates on 2-dimensional vectors with UCU\_SINT16 components.
%      \emph{Cp}:     cross-product.
%      \emph{Diva2}:  divided by the second argument (the second vector).
%      \emph{F}:      the result is floor'd.
%\end{list}
%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\subsection[\emph{UcuAtU32S16v2MagSquaredRxx(\protect\mbox{\protect$\cdot$})}]
%           {\emph{UcuAtU32S16v2MagSquaredRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
%\label{cafn0:svft0:svmf0}
%
%\index{UcuAtU32S16v2MagSquaredRxx()@\emph{UcuAtU32S16v2MagSquaredRxx($\cdot$)}}%
%
%\noindent\textbf{PROTOTYPE}
%\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item
%\begin{verbatim}
%UCU_UINT32 UcuAtU32S16v2MagSquaredRxx(
%                                     UCU_SINT16 a_x, 
%                                     UCU_SINT16 a_y
%                                     )
%\end{verbatim}
%\end{list}
%\vspace{2.8ex}
%
%\noindent\textbf{SYNOPSIS}
%\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item Calculates $a_x^2 + a_y^2$.
%\item The maximum value of $a_x^2 + a_y^2$ is $2(2^{15})^2$ = $2^{31}$,
%      so the return value of this function may exceed the maximum value
%      of an UCU\_SINT32, hence the return type UCU\_UINT32 is necessary,
%      and the result of this function may not be safely cast to
%      UCU\_SINT32.
%\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{a\_x, a\_y}}\\
%      The $x$ and $y$ components of a vector.  The components are signed, and this function
%      will return correct results over the entire input domain.
%\end{list}
%\vspace{2.8ex}
%
%\noindent\textbf{OUTPUT}
%\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item $a_x^2 + a_y^2$.
%\end{list}
%\vspace{2.8ex}
%
%\noindent\textbf{EXCEPTION CASES}
%\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item None.
%\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{U32}:           the return value is UCU\_UINT32.
%      \emph{S16v2}:         operates on 2-dimensional vectors with UCU\_SINT16 components.
%      \emph{MagSquared}:    returns the vector magnitude squared.
%\end{list}
%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Square Root Extraction Functions}
%Section tag:  sre0
\label{cafn0:ssre0}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection[\emph{UcuAtU8SqrtFRxx(\protect\mbox{\protect$\cdot$})}]
           {\emph{UcuAtU8SqrtFRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
%Subsection tag:  lcp0
\label{cafn0:ssre0:suee0}

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

\noindent\textbf{PROTOTYPE}
\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item
\begin{verbatim}
UCU_UINT8 UcuAtU8SqrtFRxx( UCU_UINT8 x )
\end{verbatim}
\end{list}
\vspace{2.8ex}

\noindent\textbf{SYNOPSIS}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item
Calculates $\lfloor \sqrt{x} \rfloor$ using a 4-iteration
trial squaring algorithm.
\end{list}
\vspace{2.8ex}

\noindent\textbf{INPUT}
\begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
\item \emph{\textbf{x}}\\
      The unsigned 8-bit integer whose square root is to be calculated.
\end{list}
\vspace{2.8ex}

\noindent\textbf{OUTPUT}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item $\lfloor \sqrt{x} \rfloor$.
\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{U8}:   operates on UCU\_UINT8 operands.
      \emph{Sqrt}: square root.
      \emph{F}:    result is floor'd.
\end{list}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection[\emph{UcuAtU16SqrtFRxx(\protect\mbox{\protect$\cdot$})}]
           {\emph{UcuAtU16SqrtFRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
\label{cafn0:ssre0:suee1}

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

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

\noindent\textbf{SYNOPSIS}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item
Calculates $\lfloor \sqrt{x} \rfloor$ using an 8-iteration
trial squaring algorithm.
\end{list}
\vspace{2.8ex}

\noindent\textbf{INPUT}
\begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
\item \emph{\textbf{x}}\\
      The unsigned 16-bit integer whose square root is to be calculated.
\end{list}
\vspace{2.8ex}

\noindent\textbf{OUTPUT}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item $\lfloor \sqrt{x} \rfloor$.
\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{U16}:   operates on UCU\_UINT16 operands.
      \emph{Sqrt}:  square root.
      \emph{F}:     result is floor'd.
\end{list}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection[\emph{UcuAtU16SqrtX10FRxx(\protect\mbox{\protect$\cdot$})}]
           {\emph{UcuAtU16SqrtX10FRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
\label{cafn0:ssre0:suee2}

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

\noindent\textbf{PROTOTYPE}
\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item
\begin{verbatim}
UCU_UINT16 UcuAtU16SqrtX10FRxx( UCU_UINT16 val )
\end{verbatim}
\end{list}
\vspace{2.8ex}

\noindent\textbf{SYNOPSIS}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item
Calculates an approximation to $10 \sqrt{x}$ using the Babylonian method.
The value returned will be either $\lfloor 10 \sqrt{x} \rfloor$ 
or $\lfloor 10 \sqrt{x} \rfloor + 1$.
\end{list}
\vspace{2.8ex}

\noindent\textbf{INPUT}
\begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
\item \emph{\textbf{x}}\\
      The unsigned 16-bit integer whose square root is to be calculated.
\end{list}
\vspace{2.8ex}

\noindent\textbf{OUTPUT}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item $\lfloor 10 \sqrt{x} \rfloor$ or $\lfloor 10 \sqrt{x} \rfloor + 1$.  There is
      no rule as to which will be returned (i.e. the value returned does not
      represent rounding).  The possibility of returning either value is tied
      to the algorithm used.\footnote{This is a to-do item for this function.
      It should be modified to return $\lfloor 10 \sqrt{x} \rfloor$ in
      all cases.  Alternate algorithms should also be explored (for speed).}
\item This function is known to return a maximum of 2,559,
      corresponding to $x = 65535$.
\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{U16}:   operates on UCU\_UINT16 operands.
      \emph{Sqrt}:  square root.
      \emph{X10}:   result is multiplied by 10.
      \emph{F}:     result is floor'd.
\end{list}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\subsection[\emph{UcuAtU32SqrtFRxx(\protect\mbox{\protect$\cdot$})}]
%           {\emph{UcuAtU32SqrtFRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
%\label{cafn0:ssre0:suee5}
%
%\index{UcuAtU32SqrtFRxx()@\emph{UcuAtU32SqrtFRxx($\cdot$)}}%
%
%\noindent\textbf{PROTOTYPE}
%\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item
%\begin{verbatim}
%UCU_UINT16 UcuAtU32SqrtFRxx( UCU_UINT32 x )
%\end{verbatim}
%\end{list}
%\vspace{2.8ex}
%
%\noindent\textbf{SYNOPSIS}
%\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item
%Calculates $\lfloor \sqrt{x} \rfloor$ using a 16-iteration
%trial squaring algorithm.
%\end{list}
%\vspace{2.8ex}
%
%\noindent\textbf{INPUT}
%\begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
%\item \emph{\textbf{x}}\\
%      The unsigned 32-bit integer whose square root is to be calculated.
%\end{list}
%\vspace{2.8ex}
%
%\noindent\textbf{OUTPUT}
%\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item $\lfloor \sqrt{x} \rfloor$.
%\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{U32}:   operates on UCU\_UINT32 operands.
%      \emph{Sqrt}:  square root.
%      \emph{F}:     result is floor'd.
%\end{list}
%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\section{Sign Determination Functions}
%\label{cafn0:ssdf0}
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\subsection[\emph{UcuAtS32IsNegRxx(\protect\mbox{\protect$\cdot$})}]
%           {\emph{UcuAtS32IsNegRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
%\label{cafn0:ssdf0:sisn0}
%
%\index{UcuAtS32IsNegRxx()@\emph{UcuAtS32IsNegRxx($\cdot$)}}%
%
%\noindent\textbf{PROTOTYPE}
%\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item
%\begin{verbatim}
%UCU_BOOLEAN UcuAtS32IsNegRxx( UCU_SINT32 x )
%\end{verbatim}
%\end{list}
%\vspace{2.8ex}
%
%\noindent\textbf{SYNOPSIS}
%\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item
%Returns UCU\_TRUE if $x<0$ or UCU\_FALSE otherwise.
%\end{list}
%\vspace{2.8ex}
%
%\noindent\textbf{INPUT}
%\begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
%\item \emph{\textbf{x}}\\
%      The signed 32-bit integer to be tested for negativity.
%\end{list}
%\vspace{2.8ex}
%
%\noindent\textbf{OUTPUT}
%\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
%\item UCU\_TRUE if $x<0$ or UCU\_FALSE otherwise.
%\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{S32}:   operates on UCU\_SINT32 operands.
%      \emph{IsNeg}: tests if the argument \emph{is} \emph{neg}ative.
%\end{list}
%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Trigonometric Functions}
\label{cafn0:strf0}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection[\emph{UcuAtAtanIx100Odegx1RRxx(\protect\mbox{\protect$\cdot$})}]
           {\emph{UcuAtAtanIx100Odegx1RRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
\label{cafn0:strf0:sata0}

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

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

\noindent\textbf{SYNOPSIS}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item Calculates $\tan{}^{-1}x$ to 1-degree precision in the first quadrant
      only using a binary search on an internal 90-element lookup table.
\end{list}
\vspace{2.8ex}

\noindent\textbf{INPUT}
\begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
\item \emph{\textbf{x}}\\
      100 times the tangent whose arctangent is to be calculated.
      For example, 0.58 would be supplied to this function
      as $x=58$.
\end{list}
\vspace{2.8ex}

\noindent\textbf{OUTPUT}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item $\tan{}^{-1}x$, in the first quadrant, rounded approximately to the
      nearest degree.
\end{list}
\vspace{2.8ex}

\noindent\textbf{EXCEPTION CASES}
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
\item This function returns the expected value for all input arguments,
      so there are no exception cases.
      Input arguments from 11459 through $2^{16}-1$ will result
      in a returned value of 90.\footnote{The tangent of 89.5 degrees is approximately 114.5887,
      so an input argument of 11458 will result in a return value of 89, while an
      input argument of 11459 will result in a return value of 90.}
\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{Atan}:       arctangent.
      \emph{Ix100}:      input $\times$ 100.
      \emph{Odegx1}:     output in degrees $\times$ 1.
      \emph{R}:          rounded (to nearest degree).
\end{list}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\noindent\begin{figure}[!b]
\noindent\rule[-0.25in]{\textwidth}{1pt}
\begin{tiny}
\begin{verbatim}
$RCSfile: c_afn0.tex,v $
$Source: /home/dashley/cvsrep/uculib01/uculib01/doc/manual/c_afn0/c_afn0.tex,v $
$Revision: 1.37 $
$Author: dashley $
$Date: 2010/05/12 18:35:49 $
\end{verbatim}
\end{tiny}
\noindent\rule[0.25in]{\textwidth}{1pt}
\end{figure}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%$Log: c_afn0.tex,v $
%Revision 1.37  2010/05/12 18:35:49  dashley
%Removal of UcuAtS32S16v2CpDiva2FRxx() function.
%
%Revision 1.36  2010/05/12 18:29:49  dashley
%Removal of UcuAtS32S16v2CpRxx() function.
%
%Revision 1.35  2010/05/12 17:20:51  dashley
%Removal of UcuAtS32NegationRxx() function.
%
%Revision 1.34  2010/05/12 17:16:47  dashley
%Removal of UcuAtU32S16v2MagSquaredRxx() function.
%
%Revision 1.33  2010/05/12 17:09:42  dashley
%UcuAtS32IsNegRxx() function backed out.
%
%Revision 1.32  2010/05/12 17:04:17  dashley
%UcuAtU32SqrtFRxx() function backed out.  This function is not yet
%implemented.
%
%Revision 1.31  2010/04/16 19:35:41  dashley
%Missing word added.
%
%Revision 1.30  2010/04/16 19:33:37  dashley
%Addition of UcuAtS32NegationRxx() function.
%
%Revision 1.29  2010/04/15 20:21:07  dashley
%Typo corrected.
%
%Revision 1.28  2010/04/15 19:34:39  dashley
%Addition of UcuAtU32S16v2MagSquaredRxx() function.
%
%Revision 1.27  2010/04/15 17:34:52  dashley
%Addition of UcuAtS32IsNegRxx() function.
%
%Revision 1.26  2010/04/15 14:56:28  dashley
%Addition of UcuAtU32SqrtFRxx() function.
%
%Revision 1.25  2010/04/14 14:29:47  dashley
%Incorrect equation labels changed.
%
%Revision 1.24  2010/04/05 15:13:50  dashley
%Edits.
%
%Revision 1.23  2010/04/05 13:22:09  dashley
%Function documentation updated.
%
%Revision 1.22  2010/04/01 20:21:50  dashley
%Edits.
%
%Revision 1.21  2010/04/01 14:49:25  dashley
%Addition of UcuAtS32S16v2CpRxx() function.
%
%Revision 1.20  2010/02/20 16:55:52  dashley
%Function added.
%
%Revision 1.19  2010/02/19 17:12:55  dashley
%Function added.
%
%Revision 1.18  2010/02/18 17:05:57  dashley
%Edits.
%
%Revision 1.17  2010/02/17 19:07:34  dashley
%Documentation added.
%
%Revision 1.16  2010/02/16 23:38:42  dashley
%Description of Sqrtx10 function corrected.
%
%Revision 1.15  2010/02/15 20:33:56  dashley
%Minor typo corrected.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
