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