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


{\tt \#include $<$IPBS/INT.ih$>$}\par
{\tt \#include $<$IPBS/LSU.h$>$}\par
{\tt \#include $<$LSU\_\-pvt.ih$>$}\par
\subsection*{Functions}
\begin{CompactItemize}
\item 
static \_\-\_\-inline unsigned int \hyperlink{LSU_8c_3c13236c3484c40713beff12c57313d3}{udiv\_\-qnhid} (unsigned int n1, unsigned int d)
\begin{CompactList}\small\item\em Divides only the upper 32 bits of a long long. \item\end{CompactList}\item 
static \hyperlink{struct__LSU__factors}{LSU\_\-factors} \hyperlink{LSU_8c_7d8b30ee8e56564549e0b86564dab616}{lsu\_\-calc} (unsigned int numerator, unsigned int denominator)
\begin{CompactList}\small\item\em Calculates the new scaling factors. \item\end{CompactList}\item 
void \hyperlink{LSU_8c_4385758724e8110d2611c511ddf31bfc}{LSU\_\-atomicCalc} (\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_8c_1d314f3210649f1b668ce70d5d7604c9}{LSU\_\-atomicScale} (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_8c_829c6b016255c6114b25b1ca835478eb}{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_8c_ca8d1894a531bca1ef110a0e62533363}{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.c,v 1.2 2011/03/25 21:14:41 saxton Exp $
\end{verbatim}
\normalsize
 

\subsection{Function Documentation}
\hypertarget{LSU_8c_4385758724e8110d2611c511ddf31bfc}{
\index{LSU.c@{LSU.c}!LSU\_\-atomicCalc@{LSU\_\-atomicCalc}}
\index{LSU\_\-atomicCalc@{LSU\_\-atomicCalc}!LSU.c@{LSU.c}}
\subsubsection[{LSU\_\-atomicCalc}]{\setlength{\rightskip}{0pt plus 5cm}void LSU\_\-atomicCalc ({\bf LSU\_\-factors} $\ast$ {\em factors}, \/  unsigned int {\em numerator}, \/  unsigned int {\em denominator})}}
\label{LSU_8c_4385758724e8110d2611c511ddf31bfc}


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\_\-atomicScale 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}


References INT\_\-\_\-lock(), INT\_\-\_\-unlock(), and lsu\_\-calc().\hypertarget{LSU_8c_1d314f3210649f1b668ce70d5d7604c9}{
\index{LSU.c@{LSU.c}!LSU\_\-atomicScale@{LSU\_\-atomicScale}}
\index{LSU\_\-atomicScale@{LSU\_\-atomicScale}!LSU.c@{LSU.c}}
\subsubsection[{LSU\_\-atomicScale}]{\setlength{\rightskip}{0pt plus 5cm}LSU\_\-atomicScale (const {\bf LSU\_\-factors} $\ast$ {\em factors}, \/  unsigned int {\em dx})}}
\label{LSU_8c_1d314f3210649f1b668ce70d5d7604c9}


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 PowerPC 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}


References INT\_\-\_\-lock(), INT\_\-\_\-unlock(), lsu\_\-\_\-scale(), \_\-LSU\_\-factors::mult, and \_\-LSU\_\-factors::shift.\hypertarget{LSU_8c_829c6b016255c6114b25b1ca835478eb}{
\index{LSU.c@{LSU.c}!LSU\_\-calc@{LSU\_\-calc}}
\index{LSU\_\-calc@{LSU\_\-calc}!LSU.c@{LSU.c}}
\subsubsection[{LSU\_\-calc}]{\setlength{\rightskip}{0pt plus 5cm}void LSU\_\-calc ({\bf LSU\_\-factors} $\ast$ {\em factors}, \/  unsigned int {\em numerator}, \/  unsigned int {\em denominator})}}
\label{LSU_8c_829c6b016255c6114b25b1ca835478eb}


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\_\-atomicScale 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\_\-atomicCalc and LSU\_\-atomicScale or be sure to provide some locking/protection scheme of your own. \end{Desc}


References lsu\_\-calc().\hypertarget{LSU_8c_7d8b30ee8e56564549e0b86564dab616}{
\index{LSU.c@{LSU.c}!lsu\_\-calc@{lsu\_\-calc}}
\index{lsu\_\-calc@{lsu\_\-calc}!LSU.c@{LSU.c}}
\subsubsection[{lsu\_\-calc}]{\setlength{\rightskip}{0pt plus 5cm}static {\bf LSU\_\-factors} lsu\_\-calc (unsigned int {\em numerator}, \/  unsigned int {\em denominator})\hspace{0.3cm}{\tt  \mbox{[}static\mbox{]}}}}
\label{LSU_8c_7d8b30ee8e56564549e0b86564dab616}


Calculates the new scaling factors. 

\begin{Desc}
\item[Returns:]The new scaling factors \end{Desc}


References FFSL(), \_\-LSU\_\-factors::mult, \_\-LSU\_\-factors::shift, and udiv\_\-qnhid().

Referenced by LSU\_\-atomicCalc(), and LSU\_\-calc().\hypertarget{LSU_8c_ca8d1894a531bca1ef110a0e62533363}{
\index{LSU.c@{LSU.c}!LSU\_\-scale@{LSU\_\-scale}}
\index{LSU\_\-scale@{LSU\_\-scale}!LSU.c@{LSU.c}}
\subsubsection[{LSU\_\-scale}]{\setlength{\rightskip}{0pt plus 5cm}LSU\_\-scale (const {\bf LSU\_\-factors} $\ast$ {\em factors}, \/  unsigned int {\em dx})}}
\label{LSU_8c_ca8d1894a531bca1ef110a0e62533363}


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 PowerPC 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\_\-atomicCalc and LSU\_\-atomicScale or arranging your own protection. \end{Desc}


References lsu\_\-\_\-scale(), \_\-LSU\_\-factors::mult, and \_\-LSU\_\-factors::shift.\hypertarget{LSU_8c_3c13236c3484c40713beff12c57313d3}{
\index{LSU.c@{LSU.c}!udiv\_\-qnhid@{udiv\_\-qnhid}}
\index{udiv\_\-qnhid@{udiv\_\-qnhid}!LSU.c@{LSU.c}}
\subsubsection[{udiv\_\-qnhid}]{\setlength{\rightskip}{0pt plus 5cm}unsigned int udiv\_\-qnhid (unsigned int {\em n1}, \/  unsigned int {\em d})\hspace{0.3cm}{\tt  \mbox{[}static\mbox{]}}}}
\label{LSU_8c_3c13236c3484c40713beff12c57313d3}


Divides only the upper 32 bits of a long long. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em n1}]The upper 32 bits of a long long numerator \item[{\em d}]The divisor\end{description}
\end{Desc}
\begin{Desc}
\item[]This code was pilfered from the GCC source library and adopted for use in this special case. The original routine performed an extended 64 by 32 bit divide, returning a 64 bit quotient plus a remainder. In this special case one knows, aprior that, the quotient can only be 32 bits and that the remainder is irrelevant. \end{Desc}


Referenced by lsu\_\-calc().