\hypertarget{FFS_8h}{
\section{FFS.h File Reference}
\label{FFS_8h}\index{FFS.h@{FFS.h}}
}
Provides the interface and implementation of the Find First Set routines. 

{\tt \#include \char`\"{}EDS/impl/FFS.xx-xxx-xxx.h\char`\"{}}\par
\subsection*{Functions}
\begin{CompactItemize}
\item 
static \_\-\_\-inline int \hyperlink{FFS_8h_ec71821fb31b404187634c72ebfde3ea}{FFS} (unsigned int word)
\begin{CompactList}\small\item\em Finds the first set bit (MSB = bit 0) in a 32-bit word. \item\end{CompactList}\item 
static \_\-\_\-inline unsigned int \hyperlink{FFS_8h_114baa0efb85cbd2fd08c6a7b4db3296}{FFS\_\-eliminate} (unsigned int word, int bit)
\begin{CompactList}\small\item\em Eliminates the specified bit, {\em bit\/} from {\em word\/}. \item\end{CompactList}\item 
static \_\-\_\-inline unsigned int \hyperlink{FFS_8h_e5bff61da2e88a36a6dd1085fad6a129}{FFS\_\-mask} (int bit)
\begin{CompactList}\small\item\em Converts the bit to a bit mask. \item\end{CompactList}\item 
static \_\-\_\-inline unsigned int \hyperlink{FFS_8h_43a1ad98c22b6b97d60950de22356683}{FFS\_\-insert} (unsigned int word, int bit)
\begin{CompactList}\small\item\em Inserts the specified bit, {\em bit\/} into {\em word\/}. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Provides the interface and implementation of the Find First Set routines. 

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


\footnotesize\begin{verbatim}
  CVS $Id: FFS.h,v 1.3 2005/10/13 22:00:55 russell Exp $
\end{verbatim}
\normalsize


\begin{Desc}
\item[ABSTRACt]This facility provides the interface and implementation of the Find First Set routines. These routines provide a machine independent interface to a machine dependent implementation to find the first set bit in a 32 bit word. On most machines, this consists of a single machine instruction\end{Desc}
\begin{Desc}
\item[USAGE]Two routines are provided, {\em FFS()\/} and \hyperlink{FFS_8h_114baa0efb85cbd2fd08c6a7b4db3296}{FFS\_\-eliminate()}. These routines find and then eliminate the first set bit in a 32 bit word.\end{Desc}
\begin{Desc}
\item[Example]As example, consider counting the number of set bits in a 32-bit word.\end{Desc}


\begin{Code}\begin{verbatim}     int count_bits (unsigned int word)
     {
        int cnt = 0;
        while (word)
        {
            int bit;
            bit  = FFS (word);
            cnt += 1;
            word = FFS_eliminate (word, bit);
        }
        return cnt;
     }
\end{verbatim}
\end{Code}

 

\subsection{Function Documentation}
\hypertarget{FFS_8h_ec71821fb31b404187634c72ebfde3ea}{
\index{FFS.h@{FFS.h}!FFS@{FFS}}
\index{FFS@{FFS}!FFS.h@{FFS.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int FFS (unsigned int {\em word})\hspace{0.3cm}{\tt  \mbox{[}static\mbox{]}}}}
\label{FFS_8h_ec71821fb31b404187634c72ebfde3ea}


Finds the first set bit (MSB = bit 0) in a 32-bit word. 

\begin{Desc}
\item[Returns:]Returns the bit number of the first set bit\end{Desc}
\begin{Desc}
\item[Overview]This routine scans a 32 bit longword from left (MSB) to right (LSB) looking for the first bit set. If it finds a bit it returns a value in the range 0-31. The routine is {\bf not} protected against 0 as an input and the result is undefined.\end{Desc}
\begin{Desc}
\item[PPC Implementation]On the PowerPCs, this is a direct map to the PPC instruction 'cntlz', count leading zeros.\end{Desc}
\begin{Desc}
\item[X86 Implementation]The Intel implementation is an 'bsr' instruction with the bit numbers reversed to match a big endian machine.\end{Desc}
\begin{Desc}
\item[Generic]The generic implementation is a straighforward piece of C code, that scans MSB to LSB for the first set bit. \end{Desc}
\hypertarget{FFS_8h_114baa0efb85cbd2fd08c6a7b4db3296}{
\index{FFS.h@{FFS.h}!FFS_eliminate@{FFS\_\-eliminate}}
\index{FFS_eliminate@{FFS\_\-eliminate}!FFS.h@{FFS.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}static \_\-\_\-inline unsigned int FFS\_\-eliminate (unsigned int {\em word}, int {\em bit})\hspace{0.3cm}{\tt  \mbox{[}static\mbox{]}}}}
\label{FFS_8h_114baa0efb85cbd2fd08c6a7b4db3296}


Eliminates the specified bit, {\em bit\/} from {\em word\/}. 

\begin{Desc}
\item[Returns:]The value of the input word with the specified bit eliminated.\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em word}]The word to eliminate the bit from \item[{\em bit}]The bit (MSB = 0) to eliminate\end{description}
\end{Desc}
\begin{Desc}
\item[]This is merely a convenience routine. Nothing fancy is going on here, just a straightforward elimination of the specified bit using a mask operation. It is provided to eliminate the inevitable mistake of misspecifying the mask word (0x80000000 $>$$>$ bit), for instance by omitting one of the trailing 0's. That kind of mistake is almost impossible to spot. \end{Desc}
\hypertarget{FFS_8h_43a1ad98c22b6b97d60950de22356683}{
\index{FFS.h@{FFS.h}!FFS_insert@{FFS\_\-insert}}
\index{FFS_insert@{FFS\_\-insert}!FFS.h@{FFS.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int FFS\_\-insert (unsigned int {\em word}, int {\em bit})\hspace{0.3cm}{\tt  \mbox{[}static\mbox{]}}}}
\label{FFS_8h_43a1ad98c22b6b97d60950de22356683}


Inserts the specified bit, {\em bit\/} into {\em word\/}. 

\begin{Desc}
\item[Returns:]The value of the input word with the specified bit inserted\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em word}]The word to insert the bit into \item[{\em bit}]The bit (MSB = 0) to add\end{description}
\end{Desc}
\begin{Desc}
\item[]This is merely a convenience routine. Nothing fancy is going on here, just a straightforward insertion of the specified bit using an OR operation. It is provided to eliminate the inevitable mistake of misspecifying the mask word (0x80000000 $>$$>$ bit), for instance by omitting one of the trailing 0's. That kind of mistake is almost impossible to spot. \end{Desc}
\hypertarget{FFS_8h_e5bff61da2e88a36a6dd1085fad6a129}{
\index{FFS.h@{FFS.h}!FFS_mask@{FFS\_\-mask}}
\index{FFS_mask@{FFS\_\-mask}!FFS.h@{FFS.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}static \_\-\_\-inline unsigned int FFS\_\-mask (int {\em bit})\hspace{0.3cm}{\tt  \mbox{[}static\mbox{]}}}}
\label{FFS_8h_e5bff61da2e88a36a6dd1085fad6a129}


Converts the bit to a bit mask. 

\begin{Desc}
\item[Returns:]A 32 bit value with the specified bit set (MSB = bit 0)\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em bit}]The bit (MSB = 0) to set.\end{description}
\end{Desc}
\begin{Desc}
\item[]Nothing fancy, this routine exists for consistency across the FFS routines. \end{Desc}