1 |
%$Header: /home/dashley/cvsrep/uculib01/uculib01/doc/manual/c_bsf0/c_bsf0.tex,v 1.9 2010/05/13 14:11:43 dashley Exp $ |
2 |
|
3 |
\chapter{Bit-Mapped Set Functions} |
4 |
\label{cbsf0} |
5 |
|
6 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
7 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
8 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
9 |
\section{Introduction and Overview} |
10 |
\label{cbsf0:siov0} |
11 |
|
12 |
This chapter describes functions and data tables that operate on data |
13 |
as collections of bits. |
14 |
|
15 |
\begin{itemize} |
16 |
\item \S{}\ref{cbsf0:sctb0} (p. \pageref{cbsf0:sctb0}) |
17 |
describes constant lookup tables that are stored |
18 |
in FLASH or ROM memory. The primary purpose of these tables is |
19 |
to support the functions described by this chapter, but the tables |
20 |
are available publicly as well. |
21 |
\item \S{}\ref{cbsf0:sbcf0} (p. \pageref{cbsf0:sbcf0}) |
22 |
describes functions that calculate |
23 |
bit cardinality (number of bits set or cleared). |
24 |
\item \S{}\ref{cbsf0:srof0} (p. \pageref{cbsf0:srof0}) |
25 |
describes functions that rotate |
26 |
arrays of bits. |
27 |
\end{itemize} |
28 |
|
29 |
|
30 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
31 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
32 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
33 |
\section{Constant Lookup Tables} |
34 |
\label{cbsf0:sctb0} |
35 |
|
36 |
|
37 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
38 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
39 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
40 |
\subsection[\emph{UcuBtU8ByteCardNibpLut[\protect\mbox{\protect$\cdot$}]}] |
41 |
{\emph{UcuBtU8ByteCardNibpLut[\protect\mbox{\protect\boldmath $\cdot$}]}} |
42 |
\label{cbsf0:sctb0:suec0} |
43 |
|
44 |
\index{UcuBtU8ByteCardNibpLut[]@\emph{UcuBtU8ByteCardNibpLut[$\cdot$]}}% |
45 |
|
46 |
\noindent\textbf{PROTOTYPE} |
47 |
\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
48 |
\item |
49 |
\begin{verbatim} |
50 |
const UCU_UINT8 UcuBtU8ByteCardNibpLut[128] |
51 |
\end{verbatim} |
52 |
\end{list} |
53 |
\vspace{2.8ex} |
54 |
|
55 |
\noindent\textbf{SYNOPSIS} |
56 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
57 |
\item Contains the number of `1' bits (also called the bit cardinality of the byte) |
58 |
in each of the 256 possible bytes, packed |
59 |
into nibbles. If the byte value $b$ is $\leq$127, the |
60 |
bit cardinality is in the lower nibble of array element |
61 |
[$b$]. If the byte value $b$ is $\geq$128, the |
62 |
bit cardinality is in the upper nibble of array |
63 |
element [$b-128$]. |
64 |
\item For example, the value of element [11] is \$43. This indicates that that |
65 |
the number 11 (= \$0B = \%00001011) contains three `1' bits and that the number |
66 |
139 (= 128+11 = \$8B = \%10001011) contains four `1' bits. |
67 |
\end{list} |
68 |
\vspace{2.8ex} |
69 |
|
70 |
\noindent\textbf{TABLE NAME MNEMONIC} |
71 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
72 |
\item \emph{U8}: each element is of type UCU\_UINT8. |
73 |
\emph{ByteCard}: cardinality of a byte. |
74 |
\emph{Nibp}: nibble packed. |
75 |
\emph{Lut}: lookup table. |
76 |
\end{list} |
77 |
|
78 |
|
79 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
80 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
81 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
82 |
\subsection[\emph{UcuBtU32RmaskLut[\protect\mbox{\protect$\cdot$}]}] |
83 |
{\emph{UcuBtU32RmaskLut[\protect\mbox{\protect\boldmath $\cdot$}]}} |
84 |
\label{cbsf0:sctb0:srml0} |
85 |
|
86 |
\index{UcuBtU32RmaskLut[]@\emph{UcuBtU32RmaskLut[$\cdot$]}}% |
87 |
|
88 |
\noindent\textbf{PROTOTYPE} |
89 |
\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
90 |
\item |
91 |
\begin{verbatim} |
92 |
const UCU_UINT32 UcuBtU32RmaskLut[33] |
93 |
\end{verbatim} |
94 |
\end{list} |
95 |
\vspace{2.8ex} |
96 |
|
97 |
\noindent\textbf{SYNOPSIS} |
98 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
99 |
\item Array element [$b$] contains a UCU\_UINT32 integer with the |
100 |
rightmost $b$ bits set to `1' and the others `0'. |
101 |
\item For example, the value of element [5] is \%00000000 00000000 00000000 00011111. |
102 |
\item Element [0] contains 0, and element [32] contains $2^{32}-1$. |
103 |
\end{list} |
104 |
\vspace{2.8ex} |
105 |
|
106 |
\noindent\textbf{TABLE NAME MNEMONIC} |
107 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
108 |
\item \emph{U32}: each element is of type UCU\_UINT32. |
109 |
\emph{Rmask}: right mask. |
110 |
\emph{Lut}: lookup table. |
111 |
\end{list} |
112 |
|
113 |
|
114 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
115 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
116 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
117 |
\subsection[\emph{UcuBtU32BitByIndexLut[\protect\mbox{\protect$\cdot$}]}] |
118 |
{\emph{UcuBtU32BitByIndexLut[\protect\mbox{\protect\boldmath $\cdot$}]}} |
119 |
\label{cbsf0:sctb0:sbbi0} |
120 |
|
121 |
\index{UcuBtU32BitByIndexLut[]@\emph{UcuBtU32BitByIndexLut[$\cdot$]}}% |
122 |
|
123 |
\noindent\textbf{PROTOTYPE} |
124 |
\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
125 |
\item |
126 |
\begin{verbatim} |
127 |
const UCU_UINT32 UcuBtU32BitByIndexLut[32] |
128 |
\end{verbatim} |
129 |
\end{list} |
130 |
\vspace{2.8ex} |
131 |
|
132 |
\noindent\textbf{SYNOPSIS} |
133 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
134 |
\item Array element [$b$] contains a UCU\_UINT32 integer with |
135 |
bit $b$ bit set to `1' and the others `0'. (Bits are numbered starting |
136 |
with 0 from the right.) |
137 |
\item For example, the value of element [5] is \%00000000 00000000 00000000 00100000. |
138 |
\item Element [0] contains 1, and element [31] contains $2^{31}$. |
139 |
\end{list} |
140 |
\vspace{2.8ex} |
141 |
|
142 |
\noindent\textbf{TABLE NAME MNEMONIC} |
143 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
144 |
\item \emph{U32}: each element is of type UCU\_UINT32. |
145 |
\emph{BitByIndex}: indexing into the table by $b$ provides bit number $b$. |
146 |
\emph{Lut}: lookup table. |
147 |
\end{list} |
148 |
|
149 |
|
150 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
151 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
152 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
153 |
\section{Bit Cardinality Functions} |
154 |
\label{cbsf0:sbcf0} |
155 |
|
156 |
|
157 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
158 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
159 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
160 |
\subsection[\emph{UcuBtU8BitCardRxx(\protect\mbox{\protect$\cdot$})}] |
161 |
{\emph{UcuBtU8BitCardRxx(\protect\mbox{\protect\boldmath $\cdot$})}} |
162 |
\label{cbsf0:sbcf0:sbce0} |
163 |
|
164 |
\index{UcuBtU8BitCardRxx()@\emph{UcuBtU8BitCardRxx($\cdot$)}}% |
165 |
|
166 |
\noindent\textbf{PROTOTYPE} |
167 |
\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
168 |
\item |
169 |
\begin{verbatim} |
170 |
UCU_UINT8 UcuBtU8BitCardRxx(UCU_UINT8 arg) |
171 |
\end{verbatim} |
172 |
\end{list} |
173 |
\vspace{2.8ex} |
174 |
|
175 |
\noindent\textbf{SYNOPSIS} |
176 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
177 |
\item Calculates the number of bits set in a UCU\_UINT8. The return value cannot |
178 |
exceed 8. |
179 |
\end{list} |
180 |
\vspace{2.8ex} |
181 |
|
182 |
\noindent\textbf{INPUTS} |
183 |
\begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}} |
184 |
\item \emph{\textbf{arg}}\\ |
185 |
The UCU\_UINT8 for which the bit cardinality is to be calculated. |
186 |
\end{list} |
187 |
\vspace{2.8ex} |
188 |
|
189 |
\noindent\textbf{OUTPUT} |
190 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
191 |
\item The number of bits set in $arg$. The return value will not exceed 8. |
192 |
\end{list} |
193 |
\vspace{2.8ex} |
194 |
|
195 |
\noindent\textbf{EXCEPTION CASES} |
196 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
197 |
\item None. |
198 |
\end{list} |
199 |
\vspace{2.8ex} |
200 |
|
201 |
\noindent\textbf{INTERRUPT COMPATIBILITY} |
202 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
203 |
\item This function may be used from both non-ISR and ISR software. |
204 |
\item This function is thread-safe. |
205 |
\end{list} |
206 |
\vspace{2.8ex} |
207 |
|
208 |
\noindent\textbf{EXECUTION TIME} |
209 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
210 |
\item TBD. |
211 |
\end{list} |
212 |
\vspace{2.8ex} |
213 |
|
214 |
\noindent\textbf{FUNCTION NAME MNEMONIC} |
215 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
216 |
\item \emph{U8}: operates on unsigned UCU\_UINT8 operands. |
217 |
\emph{BitCard}: bit cardinality. |
218 |
\end{list} |
219 |
|
220 |
|
221 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
222 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
223 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
224 |
\subsection[\emph{UcuBtU16BitCardRxx(\protect\mbox{\protect$\cdot$})}] |
225 |
{\emph{UcuBtU16BitCardRxx(\protect\mbox{\protect\boldmath $\cdot$})}} |
226 |
\label{cbsf0:sbcf0:sbcs0} |
227 |
|
228 |
\index{UcuBtU16BitCardRxx()@\emph{UcuBtU16BitCardRxx($\cdot$)}}% |
229 |
|
230 |
\noindent\textbf{PROTOTYPE} |
231 |
\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
232 |
\item |
233 |
\begin{verbatim} |
234 |
UCU_UINT8 UcuBtU16BitCardRxx(UCU_UINT16 arg) |
235 |
\end{verbatim} |
236 |
\end{list} |
237 |
\vspace{2.8ex} |
238 |
|
239 |
\noindent\textbf{SYNOPSIS} |
240 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
241 |
\item Calculates the number of bits set in a UCU\_UINT16. The return value cannot |
242 |
exceed 16. |
243 |
\end{list} |
244 |
\vspace{2.8ex} |
245 |
|
246 |
\noindent\textbf{INPUTS} |
247 |
\begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}} |
248 |
\item \emph{\textbf{arg}}\\ |
249 |
The UCU\_UINT16 for which the bit cardinality is to be calculated. |
250 |
\end{list} |
251 |
\vspace{2.8ex} |
252 |
|
253 |
\noindent\textbf{OUTPUT} |
254 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
255 |
\item The number of bits set in $arg$. The return value will not exceed 16. |
256 |
\end{list} |
257 |
\vspace{2.8ex} |
258 |
|
259 |
\noindent\textbf{EXCEPTION CASES} |
260 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
261 |
\item None. |
262 |
\end{list} |
263 |
\vspace{2.8ex} |
264 |
|
265 |
\noindent\textbf{INTERRUPT COMPATIBILITY} |
266 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
267 |
\item This function may be used from both non-ISR and ISR software. |
268 |
\item This function is thread-safe. |
269 |
\end{list} |
270 |
\vspace{2.8ex} |
271 |
|
272 |
\noindent\textbf{EXECUTION TIME} |
273 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
274 |
\item TBD. |
275 |
\end{list} |
276 |
\vspace{2.8ex} |
277 |
|
278 |
\noindent\textbf{FUNCTION NAME MNEMONIC} |
279 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
280 |
\item \emph{U16}: operates on unsigned UCU\_UINT16 operands. |
281 |
\emph{BitCard}: bit cardinality. |
282 |
\end{list} |
283 |
|
284 |
|
285 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
286 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
287 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
288 |
\subsection[\emph{UcuBtU32BitCardRxx(\protect\mbox{\protect$\cdot$})}] |
289 |
{\emph{UcuBtU32BitCardRxx(\protect\mbox{\protect\boldmath $\cdot$})}} |
290 |
\label{cbsf0:sbcf0:sbct0} |
291 |
|
292 |
\index{UcuBtU32BitCardRxx()@\emph{UcuBtU32BitCardRxx($\cdot$)}}% |
293 |
|
294 |
\noindent\textbf{PROTOTYPE} |
295 |
\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
296 |
\item |
297 |
\begin{verbatim} |
298 |
UCU_UINT8 UcuBtU32BitCardRxx(UCU_UINT32 arg) |
299 |
\end{verbatim} |
300 |
\end{list} |
301 |
\vspace{2.8ex} |
302 |
|
303 |
\noindent\textbf{SYNOPSIS} |
304 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
305 |
\item Calculates the number of bits set in a UCU\_UINT32. The return value cannot |
306 |
exceed 32. |
307 |
\end{list} |
308 |
\vspace{2.8ex} |
309 |
|
310 |
\noindent\textbf{INPUTS} |
311 |
\begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}} |
312 |
\item \emph{\textbf{arg}}\\ |
313 |
The UCU\_UINT32 for which the bit cardinality is to be calculated. |
314 |
\end{list} |
315 |
\vspace{2.8ex} |
316 |
|
317 |
\noindent\textbf{OUTPUT} |
318 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
319 |
\item The number of bits set in $arg$. The return value will not exceed 32. |
320 |
\end{list} |
321 |
\vspace{2.8ex} |
322 |
|
323 |
\noindent\textbf{EXCEPTION CASES} |
324 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
325 |
\item None. |
326 |
\end{list} |
327 |
\vspace{2.8ex} |
328 |
|
329 |
\noindent\textbf{INTERRUPT COMPATIBILITY} |
330 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
331 |
\item This function may be used from both non-ISR and ISR software. |
332 |
\item This function is thread-safe. |
333 |
\end{list} |
334 |
\vspace{2.8ex} |
335 |
|
336 |
\noindent\textbf{EXECUTION TIME} |
337 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
338 |
\item TBD. |
339 |
\end{list} |
340 |
\vspace{2.8ex} |
341 |
|
342 |
\noindent\textbf{FUNCTION NAME MNEMONIC} |
343 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
344 |
\item \emph{U32}: operates on unsigned UCU\_UINT32 operands. |
345 |
\emph{BitCard}: bit cardinality. |
346 |
\end{list} |
347 |
|
348 |
|
349 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
350 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
351 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
352 |
\subsection[\emph{UcuBtU32BitCardRnRxx(\protect\mbox{\protect$\cdot$})}] |
353 |
{\emph{UcuBtU32BitCardRnRxx(\protect\mbox{\protect\boldmath $\cdot$})}} |
354 |
\label{cbsf0:sbcf0:sbcr0} |
355 |
|
356 |
\index{UcuBtU32BitCardRnRxx()@\emph{UcuBtU32BitCardRnRxx($\cdot$)}}% |
357 |
|
358 |
\noindent\textbf{PROTOTYPE} |
359 |
\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
360 |
\item |
361 |
\begin{verbatim} |
362 |
UCU_UINT8 UcuBtU32BitCardRnRxx(UCU_UINT32 arg, UCU_UINT8 n) |
363 |
\end{verbatim} |
364 |
\end{list} |
365 |
\vspace{2.8ex} |
366 |
|
367 |
\noindent\textbf{SYNOPSIS} |
368 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
369 |
\item Calculates the number of bits set among the rightmost |
370 |
$n$ bits in a $arg$. The return value cannot |
371 |
exceed 32. |
372 |
\end{list} |
373 |
\vspace{2.8ex} |
374 |
|
375 |
\noindent\textbf{INPUTS} |
376 |
\begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}} |
377 |
\item \emph{\textbf{arg}}\\ |
378 |
The UCU\_UINT32 for which the bit cardinality |
379 |
of the rightmost $n$ bits is to be calculated. |
380 |
\item \emph{\textbf{n}}\\ |
381 |
The number of bits at the right for which to |
382 |
calculate the cardinality. A value of 0 will |
383 |
result in 0 returned from this function. A |
384 |
value of 32 will result in behavior idential to the |
385 |
\emph{UcuBtU32BitCardRxx($\cdot$)} function. |
386 |
\end{list} |
387 |
\vspace{2.8ex} |
388 |
|
389 |
\noindent\textbf{OUTPUT} |
390 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
391 |
\item The number of bits set in $arg$ among the |
392 |
rightmost $n$ bits. The return value will not exceed 32. |
393 |
\end{list} |
394 |
\vspace{2.8ex} |
395 |
|
396 |
\noindent\textbf{EXCEPTION CASES} |
397 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
398 |
\item A value of $n$ greater than 32 will result in $n$ being treated |
399 |
as 32. |
400 |
\end{list} |
401 |
\vspace{2.8ex} |
402 |
|
403 |
\noindent\textbf{INTERRUPT COMPATIBILITY} |
404 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
405 |
\item This function may be used from both non-ISR and ISR software. |
406 |
\item This function is thread-safe. |
407 |
\end{list} |
408 |
\vspace{2.8ex} |
409 |
|
410 |
\noindent\textbf{EXECUTION TIME} |
411 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
412 |
\item TBD. |
413 |
\end{list} |
414 |
\vspace{2.8ex} |
415 |
|
416 |
\noindent\textbf{FUNCTION NAME MNEMONIC} |
417 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
418 |
\item \emph{U32}: operates on unsigned UCU\_UINT32 operands. |
419 |
\emph{BitCard}: bit cardinality. |
420 |
\emph{Rn}: a number of bits at the right. |
421 |
\end{list} |
422 |
|
423 |
|
424 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
425 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
426 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
427 |
\section{Rotation Functions} |
428 |
\label{cbsf0:srof0} |
429 |
|
430 |
|
431 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
432 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
433 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
434 |
\subsection[\emph{UcuBtU32RotLeftNInPlaceRxn(\protect\mbox{\protect$\cdot$})}] |
435 |
{\emph{UcuBtU32RotLeftNInPlaceRxn(\protect\mbox{\protect\boldmath $\cdot$})}} |
436 |
\label{cbsf0:srof0:srle0} |
437 |
|
438 |
\index{UcuBtU32RotLeftNInPlaceRxn()@\emph{UcuBtU32RotLeftNInPlaceRxn($\cdot$)}}% |
439 |
|
440 |
\noindent\textbf{PROTOTYPE} |
441 |
\begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
442 |
\item |
443 |
\begin{verbatim} |
444 |
void UcuBtU32RotLeftNInPlaceRxn(UCU_UINT32 *tgt, UCU_UINT8 n) |
445 |
\end{verbatim} |
446 |
\end{list} |
447 |
\vspace{2.8ex} |
448 |
|
449 |
\noindent\textbf{SYNOPSIS} |
450 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
451 |
\item Rolls the target UCU\_UINT32 left by $n$ bits. (By ``roll'' we mean |
452 |
that each bit shifted |
453 |
out of position 31 is copied into position 0.) |
454 |
\end{list} |
455 |
\vspace{2.8ex} |
456 |
|
457 |
\noindent\textbf{INPUTS} |
458 |
\begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}} |
459 |
\item \emph{\textbf{tgt}}\\ |
460 |
A pointer to the target UCU\_UINT32. This pointer may not be |
461 |
NULL or otherwise invalid. This function provides no guarantees |
462 |
about the order in which the bytes of the target will be accessed, |
463 |
how many times they will be accessed, or (if $n \bmod 32 = 0$) that |
464 |
they will be accessed at all. The only guarantee provided is that |
465 |
at function exit the correct value will be stored in the target location. |
466 |
\item \emph{\textbf{n}}\\ |
467 |
The number of bits to roll the target left. |
468 |
All UCU\_UINT8 input values including 0 |
469 |
are permitted and treated correctly. |
470 |
\end{list} |
471 |
\vspace{2.8ex} |
472 |
|
473 |
\noindent\textbf{OUTPUT} |
474 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
475 |
\item \emph{*tgt} will have been rolled left $n$ bits. |
476 |
\end{list} |
477 |
\vspace{2.8ex} |
478 |
|
479 |
\noindent\textbf{EXCEPTION CASES} |
480 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
481 |
\item None. |
482 |
\end{list} |
483 |
\vspace{2.8ex} |
484 |
|
485 |
\noindent\textbf{INTERRUPT COMPATIBILITY} |
486 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
487 |
\item This function may be used from both non-ISR and ISR software and |
488 |
is thread-safe, |
489 |
so long as the UCU\_UINT32 data items pointed |
490 |
to by \emph{*tgt} are unique. |
491 |
\end{list} |
492 |
\vspace{2.8ex} |
493 |
|
494 |
\noindent\textbf{EXECUTION TIME} |
495 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
496 |
\item TBD. |
497 |
\end{list} |
498 |
\vspace{2.8ex} |
499 |
|
500 |
\noindent\textbf{FUNCTION NAME MNEMONIC} |
501 |
\begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}} |
502 |
\item \emph{U32}: operates on unsigned UCU\_UINT32 operands. |
503 |
\emph{Rot}: rotate. |
504 |
\emph{Left}: left. |
505 |
\emph{N}: by $n$ bits. |
506 |
\emph{InPlace}: operates on the operand in place (rather than returning the |
507 |
modified operand). |
508 |
\end{list} |
509 |
|
510 |
|
511 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
512 |
\noindent\begin{figure}[!b] |
513 |
\noindent\rule[-0.25in]{\textwidth}{1pt} |
514 |
\begin{tiny} |
515 |
\begin{verbatim} |
516 |
$RCSfile: c_bsf0.tex,v $ |
517 |
$Source: /home/dashley/cvsrep/uculib01/uculib01/doc/manual/c_bsf0/c_bsf0.tex,v $ |
518 |
$Revision: 1.9 $ |
519 |
$Author: dashley $ |
520 |
$Date: 2010/05/13 14:11:43 $ |
521 |
\end{verbatim} |
522 |
\end{tiny} |
523 |
\noindent\rule[0.25in]{\textwidth}{1pt} |
524 |
\end{figure} |
525 |
|
526 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
527 |
%$Log: c_bsf0.tex,v $ |
528 |
%Revision 1.9 2010/05/13 14:11:43 dashley |
529 |
%Renaming of function UcuBtU32RotLeftNInPlaceRxx() to |
530 |
%UcuBtU32RotLeftNInPlaceRxn(). |
531 |
% |
532 |
%Revision 1.8 2010/05/12 22:24:57 dashley |
533 |
%Addition of UcuBtU32RotLeftNInPlaceRxx() function. |
534 |
% |
535 |
%Revision 1.7 2010/02/11 16:57:28 dashley |
536 |
%Addition of three functions. |
537 |
% |
538 |
%Revision 1.6 2010/02/10 20:04:37 dashley |
539 |
%Edits. |
540 |
% |
541 |
%Revision 1.5 2010/02/10 19:55:27 dashley |
542 |
%Edits. |
543 |
% |
544 |
%Revision 1.4 2010/02/10 16:46:56 dashley |
545 |
%Edits. |
546 |
% |
547 |
%Revision 1.3 2010/01/28 21:18:32 dashley |
548 |
%a)Chapter start quotes removed. |
549 |
%b)Aesthetic comment line added at the bottom of most files. |
550 |
% |
551 |
%Revision 1.2 2010/01/24 05:37:27 dashley |
552 |
%Addition and reorganization of content. |
553 |
% |
554 |
%Revision 1.1 2007/10/06 22:56:03 dtashley |
555 |
%initial checkin. |
556 |
%End of $RCSfile: c_bsf0.tex,v $. |
557 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
558 |
|