\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. 



This graph shows which files directly or indirectly include this file:\nopagebreak
\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=290pt]{ffs_8h__dep__incl}
\end{center}
\end{figure}
\subsection*{Functions}
\begin{CompactItemize}
\item 
static \_\-\_\-inline int \hyperlink{ffs_8h_b447f53b08b56f110883aa2fc8acfd81}{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}\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
\end{verbatim}
\normalsize


{\bf ABSTRACT} \par
 -------- \par
 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

{\bf USAGE} \par
 ----- \par
 Two routines are provided, {\em \hyperlink{ffs_8h_b447f53b08b56f110883aa2fc8acfd81}{FFS()}\/} and \hyperlink{ffs_8h_114baa0efb85cbd2fd08c6a7b4db3296}{FFS\_\-eliminate()}. These routines find and then eliminate the first set bit in a 32 bit word.

{\bf Example} \par
 ------- \par
 As example, consider counting the number of set bits in a 32-bit word.



\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_b447f53b08b56f110883aa2fc8acfd81}{
\index{ffs.h@{ffs.h}!FFS@{FFS}}
\index{FFS@{FFS}!ffs.h@{ffs.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}static \_\-\_\-inline int FFS (unsigned int {\em word})\hspace{0.3cm}{\tt  \mbox{[}static\mbox{]}}}}
\label{ffs_8h_b447f53b08b56f110883aa2fc8acfd81}


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

On the PowerPCs, this is a direct map to the PPC instruction 'cntlz', count leading zeros.

The Intel implementation is an 'bsr' instruction with the bit numbers reversed to match a big endian machine.

The non PPC604 implementation is a straighforward piece of C code. \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}
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. \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}
Nothing fancy, this routine exists for consistency across the FFS routines.