/[dtapublic]/to_be_filed/uculib01/doc/manual/c_bsf0/c_bsf0.tex
ViewVC logotype

Contents of /to_be_filed/uculib01/doc/manual/c_bsf0/c_bsf0.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 30 - (show annotations) (download) (as text)
Sat Oct 8 07:22:17 2016 UTC (7 years, 4 months ago) by dashley
File MIME type: application/x-tex
File size: 20284 byte(s)
Initial commit.
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

dashley@gmail.com
ViewVC Help
Powered by ViewVC 1.1.25