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