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

Annotation of /to_be_filed/uculib01/doc/manual/c_msc0/c_msc0.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 30 - (hide annotations) (download) (as text)
Sat Oct 8 07:22:17 2016 UTC (7 years, 5 months ago) by dashley
File MIME type: application/x-tex
File size: 24575 byte(s)
Initial commit.
1 dashley 30 %$Header: /home/dashley/cvsrep/uculib01/uculib01/doc/manual/c_msc0/c_msc0.tex,v 1.11 2010/06/11 15:38:58 dashley Exp $
2    
3     \chapter{Miscellaneous Functions}
4     \label{cmsc0}
5    
6     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
7     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
8     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
9     \section{Introduction and Overview}
10     %Section tag: iov0
11     \label{cmsc0:siov0}
12    
13     This chapter documents functions that couldn't be easily classified elsewhere.
14    
15     \begin{itemize}
16     \item \S{}\ref{cmsc0:slfv0} (p. \pageref{cmsc0:slfv0}) documents functions that
17     make available library version information.
18     \end{itemize}
19    
20     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
21     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
22     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
23     \section{Library Version Functions}
24     %Section tag: lvf0
25     \label{cmsc0:slfv0}
26    
27    
28    
29     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
30     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
31     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
32     \subsection[\emph{UcuMfLibVerMajRxx(\protect\mbox{\protect$\cdot$})}]
33     {\emph{UcuMfLibVerMajRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
34     %Section tag: lvf0
35     \label{cmsc0:slvf0}
36    
37     \index{UcuMfLibVerMajRxx()@\emph{UcuMfLibVerMajRxx($\cdot$)}}%
38    
39     \noindent\textbf{PROTOTYPE}
40     \begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
41     \item
42     \begin{verbatim}
43     UCU_UINT16 UcuMfLibVerMajRxx(void)
44     \end{verbatim}
45     \end{list}
46     \vspace{2.8ex}
47    
48     \noindent\textbf{SYNOPSIS}
49     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
50     \item
51     Returns the major version number of the library. (For example,
52     if the library is version 2.5c, the integer returned would be 2.)
53     \end{list}
54     \vspace{2.8ex}
55    
56     \noindent\textbf{INPUT}
57     \begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
58     \item None.
59     \end{list}
60     \vspace{2.8ex}
61    
62     \noindent\textbf{OUTPUT}
63     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
64     \item The major version number of the library.
65     \end{list}
66     \vspace{2.8ex}
67    
68     \noindent\textbf{TYPICAL USAGE}
69     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
70     \item This function is typically used to guard against project build accidents
71     where an unintended version of the library is linked in. A typical
72     approach is that the software will not function if an unexpected version
73     of the library is present.
74     \end{list}
75     \vspace{2.8ex}
76    
77     \noindent\textbf{INTERRUPT COMPATIBILITY}
78     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
79     \item This function may be used from both non-ISR and ISR software.
80     \item This function is thread-safe.
81     \end{list}
82     \vspace{2.8ex}
83    
84     \noindent\textbf{EXECUTION TIME}
85     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
86     \item TBD.
87     \end{list}
88     \vspace{2.8ex}
89    
90     \noindent\textbf{FUNCTION NAME MNEMONIC}
91     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
92     \item \emph{Lib}: library. \emph{Ver}: version. \emph{Maj}: major.
93     \end{list}
94    
95    
96     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
97     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
98     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
99     \subsection[\emph{UcuMfLibVerMinMicRxx(\protect\mbox{\protect$\cdot$})}]
100     {\emph{UcuMfLibVerMinMicRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
101     %Section tag: lvm0
102     \label{cmsc0:slvm0}
103    
104     \index{UcuMfLibVerMinMicRxx()@\emph{UcuMfLibVerMinMicRxx($\cdot$)}}%
105    
106     \noindent\textbf{PROTOTYPE}
107     \begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
108     \item
109     \begin{verbatim}
110     UCU_UINT16 UcuMfLibVerMinMicRxx(void)
111     \end{verbatim}
112     \end{list}
113     \vspace{2.8ex}
114    
115     \noindent\textbf{SYNOPSIS}
116     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
117     \item
118     Returns the minor version number and micro version number of the library;
119     with the minor version number packed in the most significant byte of the
120     result and the micro version number packed in the least significant byte
121     of the result.
122     \end{list}
123     \vspace{2.8ex}
124    
125     \noindent\textbf{INPUT}
126     \begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
127     \item None.
128     \end{list}
129     \vspace{2.8ex}
130    
131     \noindent\textbf{OUTPUT}
132     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
133     \item The minor version number and micro version number, packed as
134     described in the synopsis.
135     \item The minor and micro version numbers are described more fully
136     in \S\ref{ciov0:slcv0:slvn0}, p. \pageref{ciov0:slcv0:slvn0}.
137     \end{list}
138     \vspace{2.8ex}
139    
140     \noindent\textbf{DETAILED DESCRIPTION}
141     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
142     \item Returns the minor version number and micro version number of the library;
143     with the minor version number packed in the most significant byte of the
144     result and the micro version number packed in the least significant byte
145     of the result.
146     \item The minor and micro version numbers are described more fully
147     in \S\ref{ciov0:slcv0:slvn0}, p. \pageref{ciov0:slcv0:slvn0}.
148     \item As an example,
149     if the library is version 2.5c, the integer returned would be $5 \times 2^{8} + 2$.
150     \end{list}
151     \vspace{2.8ex}
152    
153     \noindent\textbf{TYPICAL USAGE}
154     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
155     \item This function is typically used to guard against project build accidents
156     where an unintended version of the library is linked in. A typical
157     approach is that the software will not function if an unexpected version
158     of the library is present.
159     \end{list}
160     \vspace{2.8ex}
161    
162     \noindent\textbf{INTERRUPT COMPATIBILITY}
163     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
164     \item This function may be used from both non-ISR and ISR software.
165     \item This function is thread-safe.
166     \end{list}
167     \vspace{2.8ex}
168    
169     \noindent\textbf{EXECUTION TIME}
170     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
171     \item TBD.
172     \end{list}
173     \vspace{2.8ex}
174    
175     \noindent\textbf{FUNCTION NAME MNEMONIC}
176     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
177     \item \emph{Lib}: library. \emph{Ver}: version. \emph{Min}: minor.
178     \emph{Mic}: micro.
179     \end{list}
180    
181    
182     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
183     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
184     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
185     \subsection[\emph{UcuMfLibVerCpuRxx(\protect\mbox{\protect$\cdot$})}]
186     {\emph{UcuMfLibVerCpuRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
187     %Section tag: lvc0
188     \label{cmsc0:slvc0}
189    
190     \index{UcuMfLibVerCpuRxx()@\emph{UcuMfLibVerCpuRxx($\cdot$)}}
191    
192     \noindent\textbf{PROTOTYPE}
193     \begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
194     \item
195     \begin{verbatim}
196     UCU_UINT16 UcuMfLibVerCpuRxx(void)
197     \end{verbatim}
198     \end{list}
199     \vspace{2.8ex}
200    
201     \noindent\textbf{SYNOPSIS}
202     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
203     \item Returns the CPU core / development tool chain identifier and the CPU core variant identifier,
204     with the CPU core / development tool chain identifier in the most
205     significant byte and the CPU core variant identifier in the least significant byte.
206     \end{list}
207     \vspace{2.8ex}
208    
209     \noindent\textbf{INPUT}
210     \begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
211     \item None.
212     \end{list}
213     \vspace{2.8ex}
214    
215     \noindent\textbf{OUTPUT}
216     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
217     \item The CPU core / development tool chain identifier and the CPU core variant identifier, packed
218     as described in the synopsis. The CPU core / development tool chain identifiers
219     that can be returned are listed in
220     Table \ref{tbl:ciov0:sscv0:01}, p. \pageref{tbl:ciov0:sscv0:01}.
221    
222     Within the STM8/Cosmic combination, the CPU core variant codes are
223     listed in
224     Table \ref{tbl:ciov0:sscv0:02}, p. \pageref{tbl:ciov0:sscv0:02}.
225    
226     Within the CPU08/Cosmic combination, the CPU core variant codes are
227     listed in
228     Table \ref{tbl:ciov0:sscv0:03}, p. \pageref{tbl:ciov0:sscv0:03}.
229     \end{list}
230     \vspace{2.8ex}
231    
232     \noindent\textbf{TYPICAL USAGE}
233     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
234     \item This function is typically used to guard against project build accidents
235     where an unintended version of the library is linked in. A typical
236     approach is that the software will not function if an unexpected version
237     of the library is present.
238     \end{list}
239     \vspace{2.8ex}
240    
241     \noindent\textbf{INTERRUPT COMPATIBILITY}
242     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
243     \item This function may be used from both non-ISR and ISR software.
244     \item This function is thread-safe.
245     \end{list}
246     \vspace{2.8ex}
247    
248     \noindent\textbf{EXECUTION TIME}
249     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
250     \item TBD.
251     \end{list}
252     \vspace{2.8ex}
253    
254     \noindent\textbf{FUNCTION NAME MNEMONIC}
255     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
256     \item \emph{Lib}: library. \emph{Ver}: version. \emph{Cpu}: CPU.
257     \end{list}
258    
259    
260     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
261     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
262     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
263     \subsection[\emph{UcuMfLibVerCmpRxx(\protect\mbox{\protect$\cdot$})}]
264     {\emph{UcuMfLibVerCmpRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
265     %Section tag: lcp0
266     \label{cmsc0:slcp0}
267    
268     \index{UcuMfLibVerCmpRxx()@\emph{UcuMfLibVerCmpRxx($\cdot$)}}%
269    
270     \noindent\textbf{PROTOTYPE}
271     \begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
272     \item
273     \begin{verbatim}
274     UCU_BOOLEAN UcuMfLibVerCpuRxx(
275     UCU_UINT16 in_majorversion,
276     UCU_UINT8 in_minorversion,
277     UCU_UINT8 in_microversion,
278     UCU_UINT8 in_cpucore,
279     UCU_UINT8 in_cpucorevariant
280     )
281     \end{verbatim}
282     \end{list}
283     \vspace{2.8ex}
284    
285     \noindent\textbf{SYNOPSIS}
286     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
287     \item
288     Compares the passed version information against the actual version
289     of the library and returns UCU\_TRUE if the passed information matches
290     the actual library version or UCU\_FALSE otherwise.
291     \end{list}
292     \vspace{2.8ex}
293    
294     \noindent\textbf{INPUTS}
295     \begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
296     \item \emph{\textbf{in\_majorversion}}\\
297     The major version number used to compare against the actual version
298     number. A value of $2^{16}-1$ will cause the major version number
299     to be ignored in the comparison.
300     \item \emph{\textbf{in\_minorversion}}\\
301     The minor version number used to compare against the actual version
302     number. A value of $2^{8}-1$ will cause the minor version number
303     to be ignored in the comparison.
304     \item \emph{\textbf{in\_microversion}}\\
305     The micro version number used to compare against the actual version
306     number. A value of $2^{8}-1$ will cause the micro version number
307     to be ignored in the comparison.
308     \item \emph{\textbf{in\_cpucore}}\\
309     The CPU core identifier used to compare against the actual CPU core
310     identifier for which the library was compiled.
311     A value of $2^{8}-1$ will cause the CPU core identifier
312     to be ignored in the comparison.
313     \item \emph{\textbf{in\_cpucorevariant}}\\
314     The CPU core variant identifier used to compare against the actual CPU core
315     variant identifier for which the library was compiled.
316     A value of $2^{8}-1$ will cause the CPU core variant identifier
317     to be ignored in the comparison.
318     \end{list}
319     \vspace{2.8ex}
320    
321     \noindent\textbf{OUTPUTS}
322     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
323     \item UCU\_TRUE if the version information of the library matches
324     the information provided, or UCU\_FALSE otherwise.
325     \end{list}
326     \vspace{2.8ex}
327    
328     \noindent\textbf{EXCEPTION CASES}
329     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
330     \item If all of the inputs are set to the ``ignore'' values,
331     the function will return UCU\_TRUE.
332     \end{list}
333     \vspace{2.8ex}
334    
335     \noindent\textbf{TYPICAL USAGE}
336     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
337     \item This function is most often used near reset to ensure that the
338     version of \emph{\productname{}} linked into the software is
339     the expected version. A typical approach would be that the
340     embedded software does not function if the library linked in is
341     not the expected version for the expected CPU.
342     \item Figure \ref{fig:cmsc0:slcp0:00} (p. \pageref{fig:cmsc0:slcp0:00})
343     shows a typical usage of the function. The code snippet
344     shown in the figure checks both that the \texttt{UCULIB.H} file
345     is consistent with the library, and that library is the expected
346     version built for the expected CPU.
347     \end{list}
348     \vspace{2.8ex}
349    
350     \begin{figure}
351     \begin{small}
352     \begin{verbatim}
353     //Halt the compilation if the UCULIB .H file isn't the expected
354     //version.
355     #if (UCU_LIBVER_MAJOR != 0) || (UCU_LIBVER_MINOR != 1) || \
356     (UCU_LIBVER_MICRO != 0) || \
357     (UCU_LIBVER_CPUCORE != UCU_CPUCORE_STM8) || \
358     (UCU_LIBVER_CPUCOREVAR != UCU_CPUCOREVAR_STM8_BASE)
359     //The UCULIB .H file isn't the right version. Error out.
360     #error "UCULIB .H file is unexpected version."
361     #endif
362    
363     //If the .H file doesn't match the actual library, this
364     //should prevent operation of the product.
365     if (! UcuMfLibVerCmpRxx(UCU_LIBVER_MAJOR,
366     UCU_LIBVER_MINOR,
367     UCU_LIBVER_MICRO,
368     UCU_LIBVER_CPUCORE,
369     UCU_LIBVER_CPUCOREVAR))
370     {
371     while(1)
372     ;
373     }
374     \end{verbatim}
375     \end{small}
376     \caption{Typical Usage of the \emph{UcuMfLibVerCmpRxx($\cdot$)} Function}
377     \label{fig:cmsc0:slcp0:00}
378     \end{figure}
379    
380     \noindent\textbf{INTERRUPT COMPATIBILITY}
381     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
382     \item This function may be used from both non-ISR and ISR software.
383     \item This function is thread-safe.
384     \end{list}
385     \vspace{2.8ex}
386    
387     \noindent\textbf{EXECUTION TIME}
388     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
389     \item TBD.
390     \end{list}
391     \vspace{2.8ex}
392    
393     \noindent\textbf{FUNCTION NAME MNEMONIC}
394     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
395     \item \emph{Lib}: library. \emph{Ver}: version. \emph{Cmp}: compare.
396     \end{list}
397    
398    
399     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
400     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
401     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
402     \section{CPU Register Manipulation Functions}
403     \label{cmsc0:scpu0}
404    
405    
406     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
407     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
408     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
409     \subsection[\emph{UcuMfCpuCcrGetRxx(\protect\mbox{\protect$\cdot$})}]
410     {\emph{UcuMfCpuCcrGetRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
411     \label{cmsc0:scpu0:sccg0}
412    
413     \index{UcuMfCpuCcrGetRxx()@\emph{UcuMfCpuCcrGetRxx($\cdot$)}}%
414    
415     \noindent\textbf{PROTOTYPE}
416     \begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
417     \item
418     \begin{verbatim}
419     UCU_CPU_CCR UcuMfCpuCcrGetRxx(void)
420     \end{verbatim}
421     \end{list}
422     \vspace{2.8ex}
423    
424     \noindent\textbf{SYNOPSIS}
425     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
426     \item
427     Returns the value of the CPU condition code register.
428     \end{list}
429     \vspace{2.8ex}
430    
431     \noindent\textbf{INPUT}
432     \begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
433     \item None.
434     \end{list}
435     \vspace{2.8ex}
436    
437     \noindent\textbf{OUTPUT}
438     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
439     \item The value of the CPU condition code register.
440     \item Because this is a function and a function call is involved,
441     certain bits or bitfields in the condition code register may not
442     be meaningful in a higher-level language program. However, some
443     bits or bitfields may be meaningful, especially those involving
444     the interrupt mask.
445     \end{list}
446     \vspace{2.8ex}
447    
448     \noindent\textbf{TYPICAL USAGE}
449     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
450     \item This function is typically used to test the interrupt mask bits.
451     \end{list}
452     \vspace{2.8ex}
453    
454     \noindent\textbf{INTERRUPT COMPATIBILITY}
455     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
456     \item This function may be used from both non-ISR and ISR software.
457     \item This function is thread-safe.
458     \end{list}
459     \vspace{2.8ex}
460    
461     \noindent\textbf{EXECUTION TIME}
462     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
463     \item TBD.
464     \end{list}
465     \vspace{2.8ex}
466    
467     \noindent\textbf{FUNCTION NAME MNEMONIC}
468     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
469     \item \emph{Cpu}: CPU. \emph{Ccr}: condition code register. \emph{Get}: get.
470     \end{list}
471    
472    
473     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
474     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
475     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
476     \subsection[\emph{UcuMfCpuCcrSetRxx(\protect\mbox{\protect$\cdot$})}]
477     {\emph{UcuMfCpuCcrSetRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
478     \label{cmsc0:scpu0:sccs0}
479    
480     \index{UcuMfCpuCcrSetRxx()@\emph{UcuMfCpuCcrSetRxx($\cdot$)}}%
481    
482     \noindent\textbf{PROTOTYPE}
483     \begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
484     \item
485     \begin{verbatim}
486     void UcuMfCpuCcrSetRxx(UCU_CPU_CCR in_ccr)
487     \end{verbatim}
488     \end{list}
489     \vspace{2.8ex}
490    
491     \noindent\textbf{SYNOPSIS}
492     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
493     \item Atomically sets the CPU condition code register to the value specified.
494     \item \emph{Atomic} in this sense means that the new condition code register
495     value is set in an atomic instruction or atomic sequence of instructions. This
496     is particularly important for the interrupt mask bits (to ensure that an
497     interrupt may not occur with these bits set to values that are not the original
498     values and not the \emph{in\_ccr} value.
499     \end{list}
500     \vspace{2.8ex}
501    
502     \noindent\textbf{INPUT}
503     \begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
504     \item \emph{\textbf{in\_ccr}}\\
505     The value to which the CPU condition code register should be atomically set.
506     \end{list}
507     \vspace{2.8ex}
508    
509     \noindent\textbf{OUTPUT}
510     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
511     \item None.
512     \end{list}
513     \vspace{2.8ex}
514    
515     \noindent\textbf{TYPICAL USAGE}
516     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
517     \item This function is typically used to atomically set the interrupt mask bits.
518     \item Because the compiler generally assumes that CCR bits are not preserved
519     across a function call, there is no advantage to providing this function
520     in a form that modifies only the interrupt mask bits (the modifications
521     to the other bits will be discarded).
522     \end{list}
523     \vspace{2.8ex}
524    
525     \noindent\textbf{INTERRUPT COMPATIBILITY}
526     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
527     \item This function may be used from both non-ISR and ISR software.
528     \item This function is thread-safe.
529     \end{list}
530     \vspace{2.8ex}
531    
532     \noindent\textbf{EXECUTION TIME}
533     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
534     \item TBD.
535     \end{list}
536     \vspace{2.8ex}
537    
538     \noindent\textbf{FUNCTION NAME MNEMONIC}
539     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
540     \item \emph{Cpu}: CPU. \emph{Ccr}: condition code register. \emph{Set}: set.
541     \end{list}
542    
543    
544     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
545     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
546     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
547     \subsection[\emph{UcuMfCpuSptrPcGetRxx(\protect\mbox{\protect$\cdot$})}]
548     {\emph{UcuMfCpuSptrPcGetRxx(\protect\mbox{\protect\boldmath $\cdot$})}}
549     \label{cmsc0:scpu0:sspg0}
550    
551     \index{UcuMfCpuSptrPcGetRxx()@\emph{UcuMfCpuSptrPcGetRxx($\cdot$)}}%
552    
553     \noindent\textbf{PROTOTYPE}
554     \begin {list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
555     \item
556     \begin{verbatim}
557     UCU_CPU_SPTR_PC UcuMfCpuSptrPcGetRxx(void)
558     \end{verbatim}
559     \end{list}
560     \vspace{2.8ex}
561    
562     \noindent\textbf{SYNOPSIS}
563     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
564     \item
565     Returns the value of the program counter stack pointer at the time
566     the function is called.
567     \end{list}
568     \vspace{2.8ex}
569    
570     \noindent\textbf{INPUT}
571     \begin{list}{}{\setlength{\leftmargin}{0.5in}\setlength{\itemindent}{-0.25in}\setlength{\topsep}{0.0in}\setlength{\partopsep}{0.0in}}
572     \item None.
573     \end{list}
574     \vspace{2.8ex}
575    
576     \noindent\textbf{OUTPUT}
577     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
578     \item The value of the program counter stack pointer at the time the
579     function is called.
580     \item In order to calculate the value of the program counter stack pointer
581     at the time the function is called,
582     the stack pointer is adjusted by the number of bytes required
583     to call the function. This offset can vary with the processor and
584     memory model.
585     \end{list}
586     \vspace{2.8ex}
587    
588     \noindent\textbf{TYPICAL USAGE}
589     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
590     \item This function is typically used to assist in debugging
591     programs, or to test whether a called function corrupts the stack pointer.
592     \end{list}
593     \vspace{2.8ex}
594    
595     \noindent\textbf{INTERRUPT COMPATIBILITY}
596     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
597     \item This function may be used from both non-ISR and ISR software.
598     \item This function is thread-safe.
599     \end{list}
600     \vspace{2.8ex}
601    
602     \noindent\textbf{EXECUTION TIME}
603     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
604     \item TBD.
605     \end{list}
606     \vspace{2.8ex}
607    
608     \noindent\textbf{FUNCTION NAME MNEMONIC}
609     \begin{list}{}{\setlength{\leftmargin}{0.25in}\setlength{\topsep}{0.0in}}
610     \item \emph{Cpu}: CPU.
611     \emph{Sptr}: stack pointer.
612     \emph{Pc}: program counter.
613     \emph{Get}: get.
614     \end{list}
615    
616    
617     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
618     \noindent\begin{figure}[!b]
619     \noindent\rule[-0.25in]{\textwidth}{1pt}
620     \begin{tiny}
621     \begin{verbatim}
622     $RCSfile: c_msc0.tex,v $
623     $Source: /home/dashley/cvsrep/uculib01/uculib01/doc/manual/c_msc0/c_msc0.tex,v $
624     $Revision: 1.11 $
625     $Author: dashley $
626     $Date: 2010/06/11 15:38:58 $
627     \end{verbatim}
628     \end{tiny}
629     \noindent\rule[0.25in]{\textwidth}{1pt}
630     \end{figure}
631    
632     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
633     %$Log: c_msc0.tex,v $
634     %Revision 1.11 2010/06/11 15:38:58 dashley
635     %Addition of UcuMfCpuCcrSetRxx() function.
636     %
637     %Revision 1.10 2010/02/14 02:37:44 dashley
638     %Function names changed.
639     %
640     %Revision 1.9 2010/02/14 02:20:54 dashley
641     %Two functions added.
642     %
643     %Revision 1.8 2010/02/04 17:51:12 dashley
644     %Exception case explanation added.
645     %
646     %Revision 1.7 2010/02/04 16:16:23 dashley
647     %Documentation updates.
648     %
649     %Revision 1.6 2010/01/28 21:18:32 dashley
650     %a)Chapter start quotes removed.
651     %b)Aesthetic comment line added at the bottom of most files.
652     %
653     %Revision 1.5 2010/01/27 21:52:15 dashley
654     %Edits.
655     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
656     %End of $RCSfile: c_msc0.tex,v $.
657     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
658    

dashley@gmail.com
ViewVC Help
Powered by ViewVC 1.1.25