\hypertarget{LSU_8h}{
\section{LSU.h File Reference}
\label{LSU_8h}\index{LSU.h@{LSU.h}}
}
Linear Scaling Utilities for unsigned 32-bit integers.  




This graph shows which files directly or indirectly include this file:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=38pt]{LSU_8h__dep__incl}
\end{center}
\end{figure}
\subsection*{Data Structures}
\begin{CompactItemize}
\item 
struct \hyperlink{struct__LSU__factors}{\_\-LSU\_\-factors}
\begin{CompactList}\small\item\em Structure to hold the calculated scale factors for a given unsigned numerator and denominator. \item\end{CompactList}\end{CompactItemize}
\subsection*{Typedefs}
\begin{CompactItemize}
\item 
typedef \hyperlink{struct__LSU__factors}{\_\-LSU\_\-factors} \hyperlink{LSU_8h_a0}{LSU\_\-factors}
\begin{CompactList}\small\item\em Typedef for struct \hyperlink{struct__LSU__factors}{\_\-LSU\_\-factors}. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
void \hyperlink{LSU_8h_a1}{LSU\_\-atomic\-Calc} (\hyperlink{struct__LSU__factors}{LSU\_\-factors} $\ast$factors, unsigned int numerator, unsigned int denominator)
\begin{CompactList}\small\item\em Calculates the scaling factors based on {\em numerator\/} and {\em denominator\/}. \item\end{CompactList}\item 
unsigned int \hyperlink{LSU_8h_a2}{LSU\_\-atomic\-Scale} (const \hyperlink{struct__LSU__factors}{LSU\_\-factors} $\ast$factors, unsigned int dx)
\begin{CompactList}\small\item\em Returns the scaled value of dx. \item\end{CompactList}\item 
void \hyperlink{LSU_8h_a3}{LSU\_\-calc} (\hyperlink{struct__LSU__factors}{LSU\_\-factors} $\ast$factors, unsigned int numerator, unsigned int denominator)
\begin{CompactList}\small\item\em Calculates the scaling factors based on {\em numerator\/} and {\em denominator\/}. \item\end{CompactList}\item 
unsigned int \hyperlink{LSU_8h_a4}{LSU\_\-scale} (const \hyperlink{struct__LSU__factors}{LSU\_\-factors} $\ast$factors, unsigned int dx)
\begin{CompactList}\small\item\em Returns the scaled value of dx. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Linear Scaling Utilities for unsigned 32-bit integers. 

\begin{Desc}
\item[Author:]JJRussell - \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc}


\footnotesize\begin{verbatim}

   CVS $Id: LSU.h,v 1.2 2005/05/02 15:39:39 russell Exp $
\end{verbatim}\normalsize


\begin{Desc}
\item[Basic Operation]These routines perform integer linear scaling, i.e. the following operation, on unsigned 32-bit integers.\end{Desc}


\footnotesize\begin{verbatim}         y = x * Numerator / Denominator
\end{verbatim}\normalsize


\begin{Desc}
\item[Goals]They seek to satisfy two goals\end{Desc}
\begin{enumerate}
\item Avoid overflow and round off error.\item Efficiency\end{enumerate}


\begin{Desc}
\item[Overflow and Round Off Error]Arthimetically there are three naive ways to compute this\end{Desc}
\begin{enumerate}
\item Convert everything to floating point\item As y = (x $\ast$ Numerator) / Denominator\item As y = x $\ast$ (Numerator / Denominator)\end{enumerate}


\begin{Desc}
\item[Floating Point Option]The first of these solutions, converting to floating point is ruled out as impractical. Many times the embedded execution environment does not allow the use of floating point.\end{Desc}
\begin{Desc}
\item[Multiple, then Divide]If done in straight 32-bit arthimetic, this solution runs the very real risk of overflowing. The alternative would be to perform the multiple as a 64-bit operation. This would lead to a very lengthy 64-bit divide by 32-bit.\end{Desc}
\begin{Desc}
\item[Divide, then Multiple]If done in straight 32-bit arthimetic, the value of the division {\em Numerator\/} / {\em Denominator\/} would certainly lose precision, and in the very real case of {\em Numerator\/} $<$ Denominator, the value would be zero.\end{Desc}
\begin{Desc}
\item[The Solution]The solution is to first scaling up {\em Numerator\/} by some power of 2, then doing the division as a 64-bit by 32-bit value. With this tactic not much has been gained over the first method. However, one can save the result of this calculation plus the power of 2 used. Subsequent calculations can then be reduced to something like\end{Desc}


\footnotesize\begin{verbatim}      y = (x * factor) >> shift
\end{verbatim}\normalsize


\begin{Desc}
\item[]This is not precisely what is done. For the truly stout of heart, the implementation is fully documented in the code.\end{Desc}
\begin{Desc}
\item[Efficiency]The final feather in the cap, is that once computed, the multipication and scale factors can be used over and over again, provided {\em numerator\/} and {\em denominator\/} do not change. In many applications, this is precisely the case, {\em x\/} keeps changing, but {\em numerator\/} and {\em denominator\/} do not. This prescription allows the very expensive 64-bit by 32-bit divide to be amortized over many operations\end{Desc}
\begin{Desc}
\item[Variants]On occasion, one may find that the values in the scaling factor structure, LSU\_\-factors, are being used and updated in an asynchonous fashion. In these cases the routines LSU\_\-atomic\-Calc and LSU\_\-atomic\-Scale should used to ensure coherent access and usage\end{Desc}


\subsection{Typedef Documentation}
\hypertarget{LSU_8h_a0}{
\index{LSU.h@{LSU.h}!LSU_factors@{LSU\_\-factors}}
\index{LSU_factors@{LSU\_\-factors}!LSU.h@{LSU.h}}
\subsubsection[LSU\_\-factors]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{struct__LSU__factors}{LSU\_\-factors}}}
\label{LSU_8h_a0}


Typedef for struct \hyperlink{struct__LSU__factors}{\_\-LSU\_\-factors}. 

\begin{Desc}
\item[Usage]The members of this structure should never be accessed directly by user code. In C++, language, this are private members. The structure is presented in the public interface for sole convenience of allowing the user to drop compiler instances of this structure, avoiding the need to allocate them from the heap; \end{Desc}


\subsection{Function Documentation}
\hypertarget{LSU_8h_a1}{
\index{LSU.h@{LSU.h}!LSU_atomicCalc@{LSU\_\-atomicCalc}}
\index{LSU_atomicCalc@{LSU\_\-atomicCalc}!LSU.h@{LSU.h}}
\subsubsection[LSU\_\-atomicCalc]{\setlength{\rightskip}{0pt plus 5cm}void LSU\_\-atomic\-Calc (\hyperlink{struct__LSU__factors}{LSU\_\-factors} $\ast$ {\em factors}, unsigned int {\em numerator}, unsigned int {\em denominator})}}
\label{LSU_8h_a1}


Calculates the scaling factors based on {\em numerator\/} and {\em denominator\/}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em factors}]The structure to receive the calculated scaling factors. \item[{\em numerator}]The numerator of the scale factor \item[{\em denominator}]The denominator of the scale factor\end{description}
\end{Desc}
\begin{Desc}
\item[]This routines calculates a multiply and a shift factor that can be used by LSU\_\-scale or LSU\_\-atomic\-Scale to scale a variable by the ratio of {\em numerator\/} to {\em denominator\/}.\end{Desc}
\begin{Desc}
\item[]This routine ensures atomic access to the scaling numbers. If your application does update the scale factors asynchronous to their use or your application has already arranged its own protection (perhaps be virtue of being called in interrupt code), then consider using the somewhat lighter-weight routines, LSU\_\-calc and LSU\_\-scale. \end{Desc}


Here is the call graph for this function:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=182pt]{LSU_8h_a1_cgraph}
\end{center}
\end{figure}
\hypertarget{LSU_8h_a2}{
\index{LSU.h@{LSU.h}!LSU_atomicScale@{LSU\_\-atomicScale}}
\index{LSU_atomicScale@{LSU\_\-atomicScale}!LSU.h@{LSU.h}}
\subsubsection[LSU\_\-atomicScale]{\setlength{\rightskip}{0pt plus 5cm}unsigned int LSU\_\-atomic\-Scale (const \hyperlink{struct__LSU__factors}{LSU\_\-factors} $\ast$ {\em factors}, unsigned int {\em dx})}}
\label{LSU_8h_a2}


Returns the scaled value of dx. 

\begin{Desc}
\item[Returns:]The scaled value of dx\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em factors}]The scaling factors \item[{\em dx}]The value to be scaled\end{description}
\end{Desc}
\begin{Desc}
\item[What It Does]This routine scales {\em dx\/} by the ratio of numerator and denominator values used to calculate the scaling factor. The main claim to fame here is speed on the Power\-PC platforms, operating about 10 times faster than a 32 x 32 to 64 bit multiple followed by a 32-bit divide. It achieves this by precalculating factors that merely multiple and shift {\em dx\/}, avoiding the expensive divide operation everywhere but in the initial calculation of the multiple and shift factors.\end{Desc}
\begin{Desc}
\item[Atomic Operation ]On Power PC platforms only, the scaling factors are extracted in an indivisable fashion, protecting the routine from having these values recomputed out from underneath it. No such protection is offered on other platforms.\end{Desc}
\begin{Desc}
\item[Note:]If your application does not update these parameters asynchonously to their use, consider using the lighter-weight routines LSU\_\-calc and LSU\_\-scale. \end{Desc}


Here is the call graph for this function:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=190pt]{LSU_8h_a2_cgraph}
\end{center}
\end{figure}
\hypertarget{LSU_8h_a3}{
\index{LSU.h@{LSU.h}!LSU_calc@{LSU\_\-calc}}
\index{LSU_calc@{LSU\_\-calc}!LSU.h@{LSU.h}}
\subsubsection[LSU\_\-calc]{\setlength{\rightskip}{0pt plus 5cm}void LSU\_\-calc (\hyperlink{struct__LSU__factors}{LSU\_\-factors} $\ast$ {\em factors}, unsigned int {\em numerator}, unsigned int {\em denominator})}}
\label{LSU_8h_a3}


Calculates the scaling factors based on {\em numerator\/} and {\em denominator\/}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em factors}]The structure to receive the calculated scaling factors. \item[{\em numerator}]The numerator of the scale factor \item[{\em denominator}]The denominator of the scale factor\end{description}
\end{Desc}
\begin{Desc}
\item[What It Does]This routines calculates a multiply and a shift factor that can be used by LSU\_\-scale or LSU\_\-atomic\-Scale to scale a variable by the ratio of {\em numerator\/} to {\em denominator\/}.\end{Desc}
\begin{Desc}
\item[Warning:]If the scale factors are being update asynchronous of their use, then consider using LSU\_\-atomic\-Calc and LSU\_\-atomic\-Scale or be sure to provide some locking/protection scheme of your own. \end{Desc}


Here is the call graph for this function:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=150pt]{LSU_8h_a3_cgraph}
\end{center}
\end{figure}
\hypertarget{LSU_8h_a4}{
\index{LSU.h@{LSU.h}!LSU_scale@{LSU\_\-scale}}
\index{LSU_scale@{LSU\_\-scale}!LSU.h@{LSU.h}}
\subsubsection[LSU\_\-scale]{\setlength{\rightskip}{0pt plus 5cm}unsigned int LSU\_\-scale (const \hyperlink{struct__LSU__factors}{LSU\_\-factors} $\ast$ {\em factors}, unsigned int {\em dx})}}
\label{LSU_8h_a4}


Returns the scaled value of dx. 

\begin{Desc}
\item[Returns:]The scaled value of dx\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em factors}]The scaling factors \item[{\em dx}]The value to be scaled\end{description}
\end{Desc}
\begin{Desc}
\item[What It Does]This routine scales {\em dx\/} by the ratio of numerator and denominator values used to calculate the scaling factor. The main claim to fame here is speed on the Power\-PC platforms, operating about 10 times faster than a 32 x 32 to 64 bit multiple followed by a 32-bit divide. It achieves this by precalculating factors that merely multiple and shift {\em dx\/}, avoiding the expensive divide operation everywhere but in the initial calculation of the multiple and shift factors.\end{Desc}
\begin{Desc}
\item[Warning:]If your application does updates these parameters asynchonously to their use, then either consider using the routines LSU\_\-atomic\-Calc and LSU\_\-atomic\-Scale or arranging your own protection. \end{Desc}


Here is the call graph for this function:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=163pt]{LSU_8h_a4_cgraph}
\end{center}
\end{figure}
