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

Contents of /to_be_filed/uculib01/doc/manual/c_ami0/c_ami0.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: 23593 byte(s)
Initial commit.
1 %$Header: /home/dashley/cvsrep/uculib01/uculib01/doc/manual/c_ami0/c_ami0.tex,v 1.12 2010/02/24 14:50:36 dashley Exp $
2
3 \chapter{Array Manipulation Functions}
4
5 \label{cami0}
6
7
8 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
9 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11 \section{Introduction and Overview}
12 %Section tag: ami0
13 \label{cami0:siov0}
14
15
16 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
17 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
19 \section{Array Element Decrement Not Below Zero Functions}
20 %Section tag: adz0
21 \label{cami0:sdez0}
22
23
24 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
25 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
26 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
27 \subsection[\emph{UcuAmU8aDnbzU16nRxn(\protect\mbox{\protect$\cdot$})}]
28 {\emph{UcuAmU8aDnbzU16nRxn(\protect\mbox{\protect\boldmath $\cdot$})}}
29 %Section tag: dez0
30 \label{cami0:sadx0:sdez0}
31
32 \index{UcuAmU8aDnbzU16nRxn()@\emph{UcuAmU8aDnbzU16nRxn($\cdot$)}}%
33
34 \noindent\textbf{PROTOTYPE}
35 \begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
36 \item
37 \begin{verbatim}
38 void UcuAmU8aDnbzU16nRxn(
39 UCU_UINT8 *a,
40 UCU_UINT16 n
41 )
42 \end{verbatim}
43 \end{list}
44 \vspace{2.8ex}
45
46 \noindent\textbf{SYNOPSIS}
47 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
48 \item Decrements each element of an array of UCU\_UINT8, but not below zero.
49 \end{list}
50 \vspace{2.8ex}
51
52 \noindent\textbf{INPUTS}
53 \begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
54 \item \emph{\textbf{a}}\\
55 Pointer to the first element of the array. This pointer will only
56 be dereferenced if $n>0$.
57 \item \emph{\textbf{n}}\\
58 The number of elements to be decremented.
59
60 If $n=0$, \texttt{a} will not be
61 dereferenced and no elements of the array will be modified.
62
63 If $n>0$, \texttt{a}
64 will be dereferenced and must be a valid pointer.
65 \end{list}
66 \vspace{2.8ex}
67
68 \noindent\textbf{OUTPUTS}
69 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
70 \item None.
71 \end{list}
72 \vspace{2.8ex}
73
74 \noindent\textbf{INTERRUPT COMPATIBILITY}
75 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
76 \item This function may be called from non-ISR or ISR software.
77 \item This function does not protect array accesses in any way, and so
78 is not safe to use to operate on data shared with another thread.
79 At least two types of multi-threaded shared data defects may occur if
80 this function is used on data shared between threads:
81 \begin{itemize}
82 \item Race conditions may occur when accessing a single array element.
83 The test and decrement are not guaranteed to be atomic, and
84 the decrement is not guaranteed to be atomic.
85 \item The operation performed on the entire array is not guaranteed
86 to be atomics.
87 \end{itemize}
88 \end{list}
89 \vspace{2.8ex}
90
91 \noindent\textbf{EXECUTION TIME}
92 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
93 \item TBD.
94 \end{list}
95 \vspace{2.8ex}
96
97 \noindent\textbf{FUNCTION NAME MNEMONIC}
98 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
99 \item \emph{U8a}: operates on an array of UCU\_UINT8.
100 \emph{Dnbz}: decrement, but not below zero.
101 \emph{U16n}: the number of elements to operate on is specified
102 as a UCU\_UINT16.
103 \end{list}
104
105
106 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
107 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
108 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
109 \subsection[\emph{UcuAmU16aDnbzU16nRxn(\protect\mbox{\protect$\cdot$})}]
110 {\emph{UcuAmU16aDnbzU16nRxn(\protect\mbox{\protect\boldmath $\cdot$})}}
111 \label{cami0:sadx0:sdez1}
112
113 \index{UcuAmU16aDnbzU16nRxn()@\emph{UcuAmU16aDnbzU16nRxn($\cdot$)}}%
114
115 \noindent\textbf{PROTOTYPE}
116 \begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
117 \item
118 \begin{verbatim}
119 void UcuAmU16aDnbzU16nRxn(
120 UCU_UINT16 *in_arg,
121 UCU_UINT16 in_nelem
122 )
123 \end{verbatim}
124 \end{list}
125 \vspace{2.8ex}
126
127 \noindent\textbf{SYNOPSIS}
128 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
129 \item The \emph{UcuAmU16aDnbzU16nRxn($\cdot$)} function is identical in every
130 respect to the \emph{UcuAmU8aDnbzU16nRxn($\cdot$)} function
131 (\S{}\ref{cami0:sadx0:sdez0}, p. \pageref{cami0:sadx0:sdez0})
132 except that each element of the array is 16 bits
133 rather than 8.
134 \end{list}
135 \vspace{2.8ex}
136
137
138 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
139 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
140 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
141 \subsection[\emph{UcuAmU32aDnbzU16nRxn(\protect\mbox{\protect$\cdot$})}]
142 {\emph{UcuAmU32aDnbzU16nRxn(\protect\mbox{\protect\boldmath $\cdot$})}}
143 %Section tag: dez2
144 \label{cami0:sadx0:sdez2}
145
146 \index{UcuAmU32aDnbzU16nRxn()@\emph{UcuAmU32aDnbzU16nRxn($\cdot$)}}%
147
148 \noindent\textbf{PROTOTYPE}
149 \begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
150 \item
151 \begin{verbatim}
152 void UcuAmU32aDnbzU16nRxn(
153 UCU_UINT32 *in_arg,
154 UCU_UINT16 in_nelem
155 )
156 \end{verbatim}
157 \end{list}
158 \vspace{2.8ex}
159
160 \noindent\textbf{SYNOPSIS}
161 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
162 \item The \emph{UcuAmU32aDnbzU16nRxn($\cdot$)} function is identical in every
163 respect to the \emph{UcuAmU8aDnbzU16nRxn($\cdot$)} function
164 (\S{}\ref{cami0:sadx0:sdez0}, p. \pageref{cami0:sadx0:sdez0})
165 except that each element of the array is 32 bits
166 rather than 8.
167 \end{list}
168 \vspace{2.8ex}
169
170
171 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
172 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
173 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
174 \section{Right Shift Functions}
175 %Section tag: rsf0
176 \label{cami0:srsf0}
177
178
179 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
180 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
181 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
182 \subsection[\emph{UcuAmU8aRs1U16nRxn(\protect\mbox{\protect$\cdot$})}]
183 {\emph{UcuAmU8aRs1U16nRxn(\protect\mbox{\protect\boldmath $\cdot$})}}
184 %Section tag: rsh0
185 \label{cami0:srsf0:srsh0}
186
187 \index{UcuAmU8aRs1U16nRxn()@\emph{UcuAmU8aRs1U16nRxn($\cdot$)}}%
188
189 \noindent\textbf{PROTOTYPE}
190 \begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
191 \item
192 \begin{verbatim}
193 void UcuAmU8aRs1U16nRxn(
194 UCU_UINT8 *in_arr,
195 UCU_UINT16 in_nelem,
196 UCU_UINT8 in_pushval
197 )
198 \end{verbatim}
199 \end{list}
200 \vspace{2.8ex}
201
202 \noindent\textbf{SYNOPSIS}
203 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
204 \item Shifts an array of unsigned bytes one position to the right
205 (towards larger-numbered array subscripts) and places
206 a supplied byte into the leftmost (element [0]) position.
207 \end{list}
208 \vspace{2.8ex}
209
210 \noindent\textbf{INPUTS}
211 \begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
212 \item \emph{\textbf{in\_arr}}\\
213 Pointer to the first element of the array to be shifted. This pointer will be
214 dereferenced only if $in\_nelem > 0$.
215 \item \emph{\textbf{in\_nelem}}\\
216 The total number of elements in the array. This is frequently
217 calculated as \texttt{sizeof(arr) / sizeof(arr[0])}. (Note that this is
218 the \emph{number of elements} in the array, not the size of the array.)
219 \item \emph{\textbf{in\_pushval}}\\
220 The value to be assigned to array element [0].
221 \end{list}
222 \vspace{2.8ex}
223
224 \noindent\textbf{OUTPUTS}
225 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
226 \item None.
227 \end{list}
228 \vspace{2.8ex}
229
230 \noindent\textbf{INTERRUPT COMPATIBILITY}
231 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
232 \item This function may be called from non-ISR or ISR software.
233 \item This function does not protect array accesses in any way, and so
234 is not safe to use to operate on data shared with another thread.
235 \end{list}
236 \vspace{2.8ex}
237
238 \noindent\textbf{EXECUTION TIME}
239 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
240 \item TBD.
241 \end{list}
242 \vspace{2.8ex}
243
244 \noindent\textbf{FUNCTION NAME MNEMONIC}
245 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
246 \item \emph{U8a}: operates on an array of UCU\_UINT8.
247 \emph{Rs1}: right shift by one position.
248 \emph{U16n}: the number of elements in the array is specified
249 as a UCU\_UINT16.
250 \end{list}
251
252
253 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
254 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
255 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
256 \subsection[\emph{UcuAmU16aRs1U16nRxn(\protect\mbox{\protect$\cdot$})}]
257 {\emph{UcuAmU16aRs1U16nRxn(\protect\mbox{\protect\boldmath $\cdot$})}}
258 %Section tag: rsh1
259 \label{cami0:srsf0:srsh1}
260
261 \index{UcuAmU16aRs1U16nRxn()@\emph{UcuAmU16aRs1U16nRxn($\cdot$)}}%
262
263 \noindent\textbf{PROTOTYPE}
264 \begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
265 \item
266 \begin{verbatim}
267 void UcuAmU16aRs1U16nRxn(
268 UCU_UINT16 *in_arr,
269 UCU_UINT16 in_nelem,
270 UCU_UINT8 in_pushval
271 )
272 \end{verbatim}
273 \end{list}
274 \vspace{2.8ex}
275
276 \noindent\textbf{SYNOPSIS}
277 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
278 \item The \emph{UcuAmU16aRs1U16nRxn($\cdot$)} function is identical in every
279 respect to the \emph{UcuAmU8aRs1U16nRxn($\cdot$)} function
280 (\S{}\ref{cami0:srsf0:srsh0}, p. \pageref{cami0:srsf0:srsh0})
281 except that each element of the array is 16 bits
282 rather than 8.
283 \end{list}
284 \vspace{2.8ex}
285
286
287 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
288 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
289 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
290 \section{Average Functions}
291 %Section tag: afn0
292 \label{cami0:safn0}
293
294
295 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
296 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
297 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
298 \subsection[\emph{UcuAmU16aAvgFU16nRxn(\protect\mbox{\protect$\cdot$})}]
299 {\emph{UcuAmU16aAvgFU16nRxn(\protect\mbox{\protect\boldmath $\cdot$})}}
300 %Section tag: avg0
301 \label{cami0:safn0:savg0}
302
303 \index{UcuAmU16aAvgFU16nRxn()@\emph{UcuAmU16aAvgFU16nRxn($\cdot$)}}%
304
305 \noindent\textbf{PROTOTYPE}
306 \begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
307 \item
308 \begin{verbatim}
309 UCU_UINT16 UcuAmU16aAvgFU16nRxn(
310 const UCU_UINT16 *a,
311 UCU_UINT16 n
312 )
313 \end{verbatim}
314 \end{list}
315 \vspace{2.8ex}
316
317 \noindent\textbf{SYNOPSIS}
318 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
319 \item Calculates the floor of the average of the array elements,
320 $\displaystyle{\left\lfloor{\frac{\sum_{i=0}^{n-1}a_i}{n}}\right\rfloor}$.
321 \end{list}
322 \vspace{2.8ex}
323
324 \noindent\textbf{INPUTS}
325 \begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
326 \item \emph{\textbf{a}}\\
327 Pointer to the first element of the array to be averaged. If $n=0$,
328 this pointer is not dereferenced.
329 \item \emph{\textbf{n}}\\
330 The total number of elements in the array. This is frequently
331 calculated as \texttt{sizeof(a) / sizeof(a[0])}.
332 \end{list}
333 \vspace{2.8ex}
334
335 \noindent\textbf{OUTPUTS}
336 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
337 \item The floor of the average of the array elements,
338 $\displaystyle{\left\lfloor{\frac{\sum_{i=0}^{n-1}a_i}{n}}\right\rfloor}$.
339 \end{list}
340 \vspace{2.8ex}
341
342 \noindent\textbf{EXCEPTION CASES}
343 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
344 \item If $n = 0$, 0 is returned.
345 \end{list}
346 \vspace{2.8ex}
347
348 \noindent\textbf{INTERRUPT COMPATIBILITY}
349 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
350 \item This function may be called from non-ISR or ISR software.
351 \item This function does not protect array accesses in any way, and so
352 is not safe to use to operate on data written by another thread.
353 \end{list}
354 \vspace{2.8ex}
355
356 \noindent\textbf{EXECUTION TIME}
357 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
358 \item TBD.
359 \end{list}
360 \vspace{2.8ex}
361
362 \noindent\textbf{FUNCTION NAME MNEMONIC}
363 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
364 \item \emph{U16a}: operates on an array of UCU\_UINT16.
365 \emph{Avg}: average.
366 \emph{F}: result is floor'd.
367 \emph{U16n}: the number of elements in the array is specified
368 as a UCU\_UINT16.
369 \end{list}
370
371
372 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
373 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
374 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
375 \subsection[\emph{UcuAmU16aAvgFDmmU16nRxn(\protect\mbox{\protect$\cdot$})}]
376 {\emph{UcuAmU16aAvgFDmmU16nRxn(\protect\mbox{\protect\boldmath $\cdot$})}}
377 \label{cami0:safn0:savg1}
378
379 \index{UcuAmU16aAvgFDmmU16nRxn()@\emph{UcuAmU16aAvgFDmmU16nRxn($\cdot$)}}%
380
381 \noindent\textbf{PROTOTYPE}
382 \begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
383 \item
384 \begin{verbatim}
385 UCU_UINT16 UcuAmU16aAvgFDmmU16nRxn(
386 const UCU_UINT16 *a,
387 UCU_UINT16 n
388 )
389 \end{verbatim}
390 \end{list}
391 \vspace{2.8ex}
392
393 \noindent\textbf{SYNOPSIS}
394 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
395 \item Calculates the floor of the average of the array elements with the
396 minimum and maximum array elements discarded,
397 $\displaystyle{\left\lfloor{\frac{\sum_{i=0}^{n-1}a_i - a_{min} - a_{max}}{n-2}}\right\rfloor}$.
398 \end{list}
399 \vspace{2.8ex}
400
401 \noindent\textbf{INPUTS}
402 \begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
403 \item \emph{\textbf{a}}\\
404 Pointer to the first element of the array to be averaged. If $n=0$, this
405 pointer is not dereferenced.
406 \item \emph{\textbf{n}}\\
407 The total number of elements in the array. This is frequently
408 calculated as \texttt{sizeof(a) / sizeof(a[0])}.
409 \end{list}
410 \vspace{2.8ex}
411
412 \noindent\textbf{OUTPUTS}
413 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
414 \item The floor of the average of the array elements with the
415 minimum and maximum array elements discarded,
416 $\displaystyle{\left\lfloor{\frac{\sum_{i=0}^{n-1}a_i - a_{min} - a_{max}}{n-2}}\right\rfloor}$.
417 \end{list}
418 \vspace{2.8ex}
419
420 \noindent\textbf{EXCEPTION CASES}
421 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
422 \item If $n = 0$, 0 is returned.
423 \item If $n = 1$, the value of the single array element is returned.
424 \item If $n = 2$, the floored average of the two array elements,
425 $\lfloor (a_1 + a_0)/2 \rfloor$, is returned.
426 \end{list}
427 \vspace{2.8ex}
428
429 \noindent\textbf{INTERRUPT COMPATIBILITY}
430 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
431 \item This function may be called from non-ISR or ISR software.
432 \item This function does not protect array accesses in any way, and so
433 is not safe to use to operate on data shared with another thread.
434 \end{list}
435 \vspace{2.8ex}
436
437 \noindent\textbf{EXECUTION TIME}
438 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
439 \item TBD.
440 \end{list}
441 \vspace{2.8ex}
442
443 \noindent\textbf{FUNCTION NAME MNEMONIC}
444 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
445 \item \emph{U16a}: operates on an array of UCU\_UINT16.
446 \emph{Avg}: average.
447 \emph{F}: result is floor'd.
448 \emph{Dmm}: \emph{d}iscard \emph{m}inimum and \emph{m}aximum elements.
449 \emph{U16n}: the number of elements in the array is specified
450 as a UCU\_UINT16.
451 \end{list}
452
453 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
454 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
455 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
456 \subsection[\emph{UcuAmU16aAvgFDmmRmmU16nRxn(\protect\mbox{\protect$\cdot$})}]
457 {\emph{UcuAmU16aAvgFDmmRmmU16nRxn(\protect\mbox{\protect\boldmath $\cdot$})}}
458 \label{cami0:safn0:savg2}
459
460 \index{UcuAmU16aAvgFDmmRmmU16nRxn()@\emph{UcuAmU16aAvgFDmmRmmU16nRxn($\cdot$)}}%
461
462 \noindent\textbf{PROTOTYPE}
463 \begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
464 \item
465 \begin{verbatim}
466 void UcuAmU16aAvgFDmmRmmU16nRxn(
467 const UCU_UINT16 *a,
468 UCU_UINT16 n,
469 UCU_UINT16 *avg,
470 UCU_UINT16 *a_min,
471 UCU_UINT16 *a_max
472 )
473 \end{verbatim}
474 \end{list}
475 \vspace{2.8ex}
476
477 \noindent\textbf{SYNOPSIS}
478 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
479 \item Calculates the floor of the average of the array elements with the
480 minimum and maximum array elements discarded,
481 $\displaystyle{\left\lfloor{\frac{\sum_{i=0}^{n-1}a_i - a_{min} - a_{max}}{n-2}}\right\rfloor}$.
482 The values of the minimum and maximum elements are also returned.
483 \end{list}
484 \vspace{2.8ex}
485
486 \noindent\textbf{INPUTS}
487 \begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
488 \item \emph{\textbf{a}}\\
489 Pointer to the first element of the array to be averaged. If $n=0$, this
490 pointer is not dereferenced.
491 \item \emph{\textbf{n}}\\
492 The total number of elements in the array. This is frequently
493 calculated as \texttt{sizeof(a) / sizeof(a[0])}.
494 \end{list}
495 \vspace{2.8ex}
496
497 \noindent\textbf{OUTPUTS}
498 \begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
499 \item \emph{\textbf{*avg}}\\
500 The average of the array elements with the minimum and maximum
501 elements removed:
502 $\displaystyle{\left\lfloor{\frac{\sum_{i=0}^{n-1}a_i - a_{min} - a_{max}}{n-2}}\right\rfloor}$.
503 \item \emph{\textbf{*a\_min}}\\
504 The value of the minimum element of the array that was removed from
505 the average via subtraction. All cases with duplicate elements (for example, an
506 array with every element identical) are handled correctly so that this value represents the minimum
507 of the elements in the array.
508 \item \emph{\textbf{*a\_max}}\\
509 The value of the maximum element of the array that was removed from
510 the average via subtraction. All cases with duplicate elements (for example, an
511 array with every element identical) are handled correctly so that this value represents the maximum
512 of the elements in the array.
513 \end{list}
514 \vspace{2.8ex}
515
516 \noindent\textbf{EXCEPTION CASES}
517 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
518 \item If $n = 0$, 0 is returned for the average, the minimum element, and the maximum element.
519 \item If $n = 1$, the value of the single array element is returned for the average, the minimum element, and
520 the maximum element.
521 \item If $n = 2$, the floored average of the two array elements,
522 $\lfloor (a_1 + a_0)/2 \rfloor$, is returned as the average. The smaller element is
523 returned as the minimum element, and the larger element is returned as the maximum element.
524 \end{list}
525 \vspace{2.8ex}
526
527 \noindent\textbf{INTERRUPT COMPATIBILITY}
528 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
529 \item This function may be called from non-ISR or ISR software.
530 \item This function does not protect array accesses in any way, and so
531 is not safe to use to operate on data shared with another thread.
532 \end{list}
533 \vspace{2.8ex}
534
535 \noindent\textbf{EXECUTION TIME}
536 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
537 \item TBD.
538 \end{list}
539 \vspace{2.8ex}
540
541 \noindent\textbf{FUNCTION NAME MNEMONIC}
542 \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
543 \item \emph{U16a}: operates on an array of UCU\_UINT16.
544 \emph{Avg}: average.
545 \emph{F}: result is floor'd.
546 \emph{Dmm}: \emph{d}iscard \emph{m}inimum and \emph{m}aximum elements.
547 \emph{Rmm}: \emph{r}eturn the \emph{m}inimum and \emph{m}aximum elements
548 (that were discarded).
549 \emph{U16n}: the number of elements in the array is specified
550 as a UCU\_UINT16.
551 \end{list}
552
553
554 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
555 \noindent\begin{figure}[!b]
556 \noindent\rule[-0.25in]{\textwidth}{1pt}
557 \begin{tiny}
558 \begin{verbatim}
559 $RCSfile: c_ami0.tex,v $
560 $Source: /home/dashley/cvsrep/uculib01/uculib01/doc/manual/c_ami0/c_ami0.tex,v $
561 $Revision: 1.12 $
562 $Author: dashley $
563 $Date: 2010/02/24 14:50:36 $
564 \end{verbatim}
565 \end{tiny}
566 \noindent\rule[0.25in]{\textwidth}{1pt}
567 \end{figure}
568
569 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
570 %$Log: c_ami0.tex,v $
571 %Revision 1.12 2010/02/24 14:50:36 dashley
572 %Function documentation enhanced.
573 %
574 %Revision 1.11 2010/02/23 18:51:06 dashley
575 %Edits.
576 %
577 %Revision 1.10 2010/02/23 15:51:49 dashley
578 %Edits.
579 %
580 %Revision 1.9 2010/02/17 15:04:46 dashley
581 %Function documentation enhanced.
582 %
583 %Revision 1.8 2010/01/29 20:37:46 dashley
584 %Functions added.
585 %
586 %Revision 1.7 2010/01/29 06:59:20 dashley
587 %Addition of UcuAmU16aAvgFU16nRxn() function.
588 %
589 %Revision 1.6 2010/01/29 03:06:11 dashley
590 %Addition of UcuAmU16aRs1U16nRxn() function.
591 %
592 %Revision 1.5 2010/01/28 22:46:47 dashley
593 %Addition of UcuAmU8aRs1U16nRxn() function.
594 %
595 %Revision 1.4 2010/01/28 21:18:32 dashley
596 %a)Chapter start quotes removed.
597 %b)Aesthetic comment line added at the bottom of most files.
598 %
599 %Revision 1.3 2010/01/28 21:00:29 dashley
600 %Functions added.
601 %
602 %Revision 1.2 2010/01/28 19:13:55 dashley
603 %Integration of UcuAmU8aDnbzU16nRxn().
604 %
605 %Revision 1.1 2010/01/24 05:11:56 dashley
606 %Initial checkin.
607 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
608

dashley@gmail.com
ViewVC Help
Powered by ViewVC 1.1.25