# Contents of /to_be_filed/uculib01/doc/manual/c_laf0/c_laf0.tex

 1 %$Header: /home/dashley/cvsrep/uculib01/uculib01/doc/manual/c_laf0/c_laf0.tex,v 1.7 2010/05/12 18:56:18 dashley Exp$ 2 3 \chapter[Large-Operand and Extended-Precision Arithmetic Functions] 4 {Large-Operand and Extended-Precision Arithmetic Functions} 5 6 \chaptermark{Large-Operand and Extended-Precision} 7 8 \label{claf0} 9 10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 13 \section{Introduction and Overview} 14 \label{claf0:siov0} 15 16 17 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 18 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 19 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 20 \section{Unsigned Integer Division Functions} 21 \label{claf0:suid0} 22 23 TBD. 24 25 26 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 27 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 28 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 29 %\subsection[\emph{UcuLoU32U64U32DivQFRxn(\protect\mbox{\protect$\cdot$})}] 30 % {\emph{UcuLoU32U64U32DivQFRxn(\protect\mbox{\protect\boldmath $\cdot$})}} 31 %\label{claf0:suid0:sdsf0} 32 % 33 %\index{UcuLoU32U64U32DivQFRxn()@\emph{UcuLoU32U64U32DivQFRxn($\cdot$)}}% 34 % 35 %\noindent\textbf{PROTOTYPE} 36 %\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} 37 %\item 38 %\begin{verbatim} 39 %void UcuLoU32U64U32DivQFRxn( 40 % UCU_UINT32 *out_quotient, 41 % const UCU_UNION64 *in_dividend, 42 % const UCU_UINT32 *in_divisor 43 % ) 44 %\end{verbatim} 45 %\end{list} 46 %\vspace{2.8ex} 47 % 48 %\noindent\textbf{SYNOPSIS} 49 %\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} 50 %\item Calculates 51 % 52 % 53 % *out\_quotient = \left\lfloor \frac{*in\_dividend}{*in\_divisor} \right\rfloor 54 % 55 % 56 % using a 32-iteration classic shift/compare/subtract division 57 % algorithm where it is known in advance that the quotient will not exceed 32 bits.\footnote{The 58 % general case of division of a 64-bit unsigned integer dividend by a 32-bit unsigned integer 59 % divisor may produce up to a 64-bit unsigned integer quotient. This function is not a 60 % general division function and should only be used when it is known that the quotient 61 % cannot exceed 32 bits.} 62 %\end{list} 63 %\vspace{2.8ex} 64 % 65 %\noindent\textbf{INPUT} 66 %\begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}} 67 %\item \emph{\textbf{in\_dividend}}\\ 68 % Pointer to a buffer containing the 64-bit unsigned integer dividend. 69 % The buffer is not modified by the function. 70 % 71 % This pointer may not be NULL or otherwise invalid. 72 % 73 % This buffer may not be coincident with the \emph{*in\_quotient} or 74 % \emph{*in\_divisor} buffers. 75 %\item \emph{\textbf{in\_divisor}}\\ 76 % Pointer to a buffer containing the 32-bit unsigned integer divisor. 77 % The buffer is not modified by the function. 78 % 79 % This pointer may not be NULL or otherwise invalid. 80 % 81 % This buffer may not be coincident with the \emph{*in\_quotient} or 82 % \emph{*in\_dividend} buffers. 83 %\end{list} 84 %\vspace{2.8ex} 85 % 86 %\noindent\textbf{OUTPUT} 87 %\begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}} 88 %\item \emph{\textbf{out\_quotient}}\\ 89 % Pointer to a buffer that will be assigned with the quotient. 90 % 91 % This pointer may not be NULL or otherwise invalid. 92 % 93 % This buffer may not be coincident with the \emph{*in\_dividend} or 94 % \emph{*in\_divisor} buffers. 95 %\end{list} 96 %\vspace{2.8ex} 97 % 98 %\noindent\textbf{INTERRUPT COMPATIBILITY} 99 %\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} 100 %\item This function may be used from both non-ISR and ISR software. 101 %\item This function is thread-safe. 102 %\item This function does not ensure atomic access to the buffers pointed to, so 103 % it is not thread-safe when processes in different threads use this 104 % function to access the \emph{same} buffer(s). 105 %\end{list} 106 %\vspace{2.8ex} 107 % 108 %\noindent\textbf{EXECUTION TIME} 109 %\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} 110 %\item TBD. 111 %\end{list} 112 %\vspace{2.8ex} 113 % 114 %\noindent\textbf{FUNCTION NAME MNEMONIC} 115 %\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} 116 %\item \emph{U32}: produces a UCU\_UINT32 result. 117 % \emph{U64}: accepts an unsigned 64-bit argument as input. 118 % \emph{U32}: accepts a UCU\_UINT32 argument as input. 119 % \emph{Div}: division. 120 % \emph{Q}: produces only a quotient (no remainder). 121 % \emph{F}: the quotient is rounded down, consistent with the traditional 122 % \emph{floor($\cdot$)} function. 123 %\end{list} 124 % 125 % 126 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 127 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 128 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 129 \section{Unsigned Integer Squaring Functions} 130 \label{claf0:ssqf0} 131 132 TBD. 133 134 135 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 136 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 137 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 138 %\subsection[\emph{UcuLoU64U32SquareInPlaceRxn(\protect\mbox{\protect$\cdot$})}] 139 % {\emph{UcuLoU64U32SquareInPlaceRxn(\protect\mbox{\protect\boldmath $\cdot$})}} 140 %\label{claf0:ssqf0:susf0} 141 % 142 %\index{UcuLoU64U32SquareInPlaceRxn()@\emph{UcuLoU64U32SquareInPlaceRxn($\cdot$)}}% 143 % 144 %\noindent\textbf{PROTOTYPE} 145 %\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} 146 %\item 147 %\begin{verbatim} 148 %void UcuLoU64U32SquareInPlaceRxn( UCU_UNION64 *in_u64 ) 149 %\end{verbatim} 150 %\end{list} 151 %\vspace{2.8ex} 152 % 153 %\noindent\textbf{SYNOPSIS} 154 %\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} 155 %\item 156 %Calculates the square of a 32-bit unsigned integer, yielding a 157 %64-bit unsigned integer result. The squaring is done in place'', meaning that the 158 %32-bit integer to be squared is placed right-aligned into 159 %a 64-bit buffer, and when the function returns, the same buffer contains the 160 %result. 161 %\end{list} 162 %\vspace{2.8ex} 163 % 164 %\noindent\textbf{INPUT} 165 %\begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}} 166 %\item \emph{\textbf{in\_u64}}\\ 167 % Pointer to a buffer containing the unsigned 32-bit integer whose square is to be calculated. 168 % The integer should be right-aligned (placed in the least significant 169 % bit positions of the buffer). 170 % 171 % The 32 most significant bit positions of the buffer are ignored and 172 % overwritten, and will not affect the calculation result. These 173 % bit positions do not need to be assigned prior to the function call. 174 % 175 % This pointer may not be NULL or otherwise invalid. 176 %\end{list} 177 %\vspace{2.8ex} 178 % 179 %\noindent\textbf{OUTPUT} 180 %\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} 181 %\item The buffer pointed to by \emph{in\_u64} 182 % will contain the unsigned 64-bit integer square of the unsigned 32-bit integer 183 % provided in the rightmost position in the buffer before the function call. 184 % 185 % The original unsigned 32-bit integer provided is overwritten by the result. 186 %\end{list} 187 %\vspace{2.8ex} 188 % 189 %\noindent\textbf{INTERRUPT COMPATIBILITY} 190 %\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} 191 %\item This function may be used from both non-ISR and ISR software. 192 %\item This function is thread-safe. 193 %\item This function does not ensure atomic access to \emph{*in\_u64}, so 194 % it is not thread-safe when processes in different threads use this 195 % function to access the \emph{same} buffer. 196 %\end{list} 197 %\vspace{2.8ex} 198 % 199 %\noindent\textbf{EXECUTION TIME} 200 %\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} 201 %\item TBD. 202 %\end{list} 203 %\vspace{2.8ex} 204 % 205 %\noindent\textbf{FUNCTION NAME MNEMONIC} 206 %\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} 207 %\item \emph{U64}: produces an unsigned 64-bit result. 208 % \emph{U32}: accepts a UCU\_UINT32 as input. 209 % \emph{Square}: calculates the square. 210 % \emph{InPlace}: calculates in place'' (uses the same input and output buffer). 211 %\end{list} 212 % 213 % 214 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 215 \noindent\begin{figure}[!b] 216 \noindent\rule[-0.25in]{\textwidth}{1pt} 217 \begin{tiny} 218 \begin{verbatim} 219 $RCSfile: c_laf0.tex,v$ 220 $Source: /home/dashley/cvsrep/uculib01/uculib01/doc/manual/c_laf0/c_laf0.tex,v$ 221 $Revision: 1.7$ 222 $Author: dashley$ 223 $Date: 2010/05/12 18:56:18$ 224 \end{verbatim} 225 \end{tiny} 226 \noindent\rule[0.25in]{\textwidth}{1pt} 227 \end{figure} 228 229 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 230 %$Log: c_laf0.tex,v$ 231 %Revision 1.7 2010/05/12 18:56:18 dashley 232 %Removal of UcuLoU64U32SquareInPlaceRxn() function. 233 % 234 %Revision 1.6 2010/05/12 18:41:46 dashley 235 %Removal of UcuLoU32U64U32DivQFRxn() function. 236 % 237 %Revision 1.5 2010/04/15 17:09:38 dashley 238 %Addition of UcuLoU32U64U32DivQFRxn() function. 239 % 240 %Revision 1.4 2010/04/15 15:56:41 dashley 241 %Addition of UcuU64U32SquareInPlaceRxn() function. 242 % 243 %Revision 1.3 2010/01/28 21:18:32 dashley 244 %a)Chapter start quotes removed. 245 %b)Aesthetic comment line added at the bottom of most files. 246 % 247 %Revision 1.2 2010/01/24 05:37:27 dashley 248 %Addition and reorganization of content. 249 % 250 %Revision 1.1 2007/10/08 18:07:42 dtashley 251 %Initial checkin. 252 % 253 %End of $RCSfile: c_laf0.tex,v$. 254 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 255