1API Quick-Reference    {#mipi_syst_api_page}
2======================================
3This page provides a quick reference for the SyS-T API macros. A
4detailed description of these APIs and their their parameter
5definitions is available by clicking on the individual API names.
6
7## State lifetime handling macros ##
8<table border=1 cols="3" align="left" width="100%">
9  <tr>
10    <td width="30%"><b>API Define</b></td>
11    <td><b>Description</b></td>
12  </tr>
13  <tr>
14    <td style="white-space:nowrap">
15       MIPI_SYST_INIT(f,p)
16    </td>
17    <td>SyS-T global platform initialization using an internal shared state header
18    </td>
19  </tr>
20  <tr>
21    <td style="white-space:nowrap">
22       MIPI_SYST_INIT_STATE(s, f,p)
23    </td>
24    <td>SyS-T platform initialization using a provided state header structure
25    </td>
26  </tr>
27  <tr>
28    <td style="white-space:nowrap">
29       MIPI_SYST_SHUTDOWN()
30    </td>
31    <td>SyS-T global platform shutdown
32    </td>
33  </tr>
34  <tr>
35    <td style="white-space:nowrap">
36       MIPI_SYST_SHUTDOWN_STATE(s)
37    </td>
38    <td>SyS-T platform shutdown using a provided state header structure
39    </td>
40  </tr>
41  <tr>
42    <td style="white-space:nowrap">
43       MIPI_SYST_INIT_HANDLE(h,p)
44    </td>
45    <td>Initialize a static (not heap allocated) SyS-T handle.
46    </td>
47  </tr>
48  <tr>
49    <td style="white-space:nowrap">
50       MIPI_SYST_INIT_HANDLE_STATE(s, h,p)
51    </td>
52    <td>Initialize a static (not heap allocated) SyS-T handle using a provided state header structure.
53    </td>
54  </tr>
55  <tr>
56    <td style="white-space:nowrap">
57       MIPI_SYST_ALLOC_HANDLE(p)
58    </td>
59    <td>Initialize heap allocated SyS-T handle.
60    </td>
61  </tr>
62  <tr>
63    <td style="white-space:nowrap">
64       MIPI_SYST_ALLOC_HANDLE_STATE(s, p)
65    </td>
66    <td>Initialize heap allocated SyS-T handle using a provided state header structure.
67    </td>
68  </tr>
69  <tr>
70    <td style="white-space:nowrap">
71       MIPI_SYST_DELETE_HANDLE(p)
72    </td>
73    <td>Delete a SyS-T handle.
74    </td>
75  </tr>
76  <tr>
77    <td style="white-space:nowrap">
78       MIPI_SYST_SET_HANDLE_ORIGIN(h, o)
79    </td>
80    <td>Set the client origin for the given SyS-T handle based on a mipi_syst_origin structure.
81    </td>
82  </tr>
83  <tr>
84    <td style="white-space:nowrap">
85       MIPI_SYST_SET_HANDLE_MODULE_UNIT(h,m,u)
86    </td>
87    <td>Specify module and unit ID of the given SyS-T handle.
88    </td>
89  </tr>
90  <tr>
91    <td style="white-space:nowrap">
92       MIPI_SYST_SET_HANDLE_GUID_UNIT(h, g, u)
93    </td>
94    <td>Specify GUID and unit ID of the given SyS-T handle.
95    </td>
96  </tr>
97  <tr>
98    <td style="white-space:nowrap">
99       MIPI_SYST_ENABLE_HANDLE_LENGTH(h, v)
100    </td>
101    <td>Enable or disable length field generation over the given SyS-T handle.
102    </td>
103  </tr>
104
105  <tr>
106    <td style="white-space:nowrap">
107       MIPI_SYST_ENABLE_HANDLE_CHECKSUM(h,v)
108    </td>
109    <td>Enable or disable checksum generation over the given SyS-T handle.
110    </td>
111  </tr>
112  <tr>
113    <td style="white-space:nowrap">
114       MIPI_SYST_ENABLE_HANDLE_TIMESTAMP(h, v)
115    </td>
116    <td>Enable or disable additional protocol times tamps over the
117        given SyS-T handle.
118    </td>
119  </tr>
120</table>
121The availability of the macros #MIPI_SYST_ALLOC_HANDLE, #MIPI_SYST_SET_HANDLE_GUID_UNIT,
122and #MIPI_SYST_ENABLE_HANDLE_CHECKSUM depend on
123platform feature enable defines. Attempting to use an unsupported API will result
124in a compile error.
125<BR>
126
127## String emitting macros ##
128<table border=1 cols="3" align="left" width="100%">
129  <tr>
130    <td width="30%"><b>API Define</b></td>
131    <td><b>Description</b></td>
132  </tr>
133  <tr>
134    <td style="white-space:nowrap">
135       MIPI_SYST_DEBUG(svh,sev,str,len)<BR>
136       MIPI_SYST_DEBUG_LOC16(svh,sev,file,str,len)<BR>
137       MIPI_SYST_DEBUG_LOC32(svh,sev,file,str,len)<BR>
138       MIPI_SYST_DEBUG_LOCADDR(svh,sev,str,len)
139    </td>
140    <td>Send A UTF-8 character string with given severity and length<BR>
141    </td>
142  </tr>
143  <tr>
144    <td style="white-space:nowrap">
145       \link MIPI_SYST_PRINTF MIPI_SYST_PRINTF(svh,sev,str, ...)\endlink<BR>
146       \link MIPI_SYST_PRINTF_LOC16 MIPI_SYST_PRINTF_LOC16(svh,sev,file,str, ...)\endlink<BR>
147       \link MIPI_SYST_PRINTF_LOC32 MIPI_SYST_PRINTF_LOC32(svh,sev,file,str, ...)\endlink<BR>
148       \link MIPI_SYST_PRINTF_LOCADDR MIPI_SYST_PRINTF_LOCADDR(svh,sev,str, ...)\endlink
149    </td>
150    <td>Send a C-language style *printf()* API format string and its
151        arguments. This API follows the calling convention of
152        printf() as defined by the C99 C-Language standard.<BR>
153        <B>Notes:</B> This API is enabled by the SyS-T platform
154        define @ref MIPI_SYST_PCFG_ENABLE_PRINTF_API that must be set in
155        addition to @ref MIPI_SYST_PCFG_ENABLE_STRING_API.<BR>
156        Enabling this API implies the availability of the C-Language
157        standard header files stdarg.h and stddef.h. These are needed
158        due to the variable argument support of the *printf()* calling
159        convention.
160    </td>
161  </tr>
162  <tr>
163    <td style="white-space:nowrap">
164       MIPI_SYST_FUNC_ENTER(svh,sev)<BR>
165       MIPI_SYST_FUNC_ENTER_LOC16(svh,sev,file)<BR>
166       MIPI_SYST_FUNC_ENTER_LOC32(svh,sev,file)<BR>
167       MIPI_SYST_FUNC_ENTER_LOCADDR(svh,sev)
168    </td>
169    <td>Send function enter string message. The payload is the
170        UTF-8 name of the surrounding function.
171    </td>
172  </tr>
173  <tr>
174    <td style="white-space:nowrap">
175       MIPI_SYST_FUNC_EXIT(svh,sev)<BR>
176       MIPI_SYST_FUNC_EXIT_LOC16(svh,sev,file)<BR>
177       MIPI_SYST_FUNC_EXIT_LOC32(svh,sev,file)<BR>
178       MIPI_SYST_FUNC_EXIT_LOCADDR(svh,sev)
179    </td>
180    <td>Send function exit string message. The payload is the
181        UTF-8 name of the surrounding function.
182    </td>
183  </tr>
184   <tr>
185    <td style="white-space:nowrap">
186       MIPI_SYST_ASSERT(svh,sev,cond)<BR>
187       MIPI_SYST_ASSERT_LOC16(svh,sev,file,cond)<BR>
188       MIPI_SYST_ASSERT_LOC32(svh,sev,file,cond)<BR>
189       MIPI_SYST_ASSERT_LOCADDR(svh,sev,cond)
190    </td>
191    <td>Send [file]:[line] assertion notice string message if the passed
192        condition is false
193    </td>
194  </tr>
195</table>
196The string emitting macros must be enabled by the SyS-T platform
197define #MIPI_SYST_PCFG_ENABLE_STRING_API, otherwise they expand to nothing
198inside the code.
199<BR>
200## Catalog message macros ##
201<table border=1 cols="3" align="left" width="100%">
202  <tr>
203    <td width="30%"><b>API Define</b></td>
204    <td><b>Description</b></td>
205  </tr>
206  <tr>
207    <td style="white-space:nowrap">
208        \link MIPI_SYST_CATALOG64(svh,sev,id, ...)\endlink<BR>
209    </td>
210    <td> Send catalog message with variable number of parameters defined
211         by the format string that matches the 64-bit catalog ID.</td>
212  </tr>
213  <tr>
214    <td style="white-space:nowrap">
215       MIPI_SYST_CATALOG64_0(svh,sev,id)<BR>
216       ...<BR>
217       MIPI_SYST_CATALOG64_6(svh, sev, id,p1,p2,p3,p4,p5,p6)
218    </td>
219    <td> Send catalog message with 0-6 parameters.The MIPI_SYST_CATALOG64*
220         defines build a family of macros that are used to send 64-bit wide
221         user defined catalog message IDs with up to six 32-bit wide
222         parameters into the trace stream.</td>
223  </tr>
224  <tr>
225     <td style="white-space:nowrap">
226        MIPI_SYST_CATPRINTF64_0(svh, sev, id, fmt)<BR>
227        ...<BR>
228        MIPI_SYST_CATPRINTF64_6(svh, sev, id, fmt, p1,p2,p3,p4,p5,p6)
229     </td>
230     <td> Printf style wrapper for the catalog functions that support an
231          additional fmt string parameter. The functions directly map to
232          their matching catalog call by dropping the fmt parameter.
233          Their purpose is to use printf style instrumentation in source
234          code together with catalog messages. The format strings are not
235          part of the message but can be extracted from source code to
236          pretty print catalog messages during trace decode.</td>
237  </tr>
238  <tr>
239    <td style="white-space:nowrap">
240       \link MIPI_SYST_CATALOG32(svh,sev,id, ...)\endlink<BR>
241    </td>
242    <td> Send catalog message with variable number of parameters defined
243         by the format string that matches the 32-bit catalog ID.</td>
244  </tr>
245  <tr>
246    <td style="white-space:nowrap">
247       MIPI_SYST_CATALOG32_0(svh, sev, id)<BR>
248       ...<BR>
249       MIPI_SYST_CATALOG32_6(svh, sev, id,p1,p2,p3,p4,p5,p6)
250    </td>
251    <td> Send catalog message with 0-6 parameters. The MIPI_SYST_CATALOG32*
252         defines build a family of macros that are used to send 32-bit wide
253         user defined catalog message IDs with up to six 32-bit wide
254         parameters into the trace stream.</td>
255  </tr>
256  <tr>
257     <td style="white-space:nowrap">
258        MIPI_SYST_CATPRINTF32_0(svh, sev, id, fmt)<BR>
259        ...<BR>
260        MIPI_SYST_CATPRINTF32_6(svh, sev, id, fmt, p1,p2,p3,p4,p5,p6)
261     </td>
262     <td> Printf style wrapper for the catalog functions that support an
263          additional fmt string parameter. The functions directly map to
264          their matching catalog call by dropping the fmt parameter. Their purpose is
265          to use printf style instrumentation in source code together with
266          catalog messages. The format strings are not part of the message
267          but can be extracted from source code to pretty print catalog
268          messages during trace decode.</td>
269  </tr>
270  <tr>
271    <td style="white-space:nowrap">
272        MIPI_SYST_HASH(fmt, offset)<BR>
273    </td>
274    <td> The MIPI_SYST_HASH macro computes a 32-bit hash value for the fmt
275         string constant that is usable as a numeric CatalogID parameter.
276         The offset parameter is used to change the result in case of hash
277         value collisions with other strings. It is initially set to zero
278         and is only changed to a different value if a collision occurs.
279         It is used together with automated catalog ID generation
280         decribed here: \link mipi_syst_catgen_page\endlink.</td>
281  </tr>
282</table>
283The catalog message macros must be enabled by the SyS-T platform
284defines #MIPI_SYST_PCFG_ENABLE_CATID32_API or #MIPI_SYST_PCFG_ENABLE_CATID64_API,
285otherwise they expand to nothing inside the code.
286
287
288## Raw data message macros ##
289<table border=1 cols="3" align="left" width="100%">
290  <tr>
291    <td width="30%"><b>API Define</b></td>
292    <td><b>Description</b></td>
293  </tr>
294  <tr>
295    <td style="white-space:nowrap">
296       MIPI_SYST_SHORT32(h, v)
297    </td>
298    <td> Send short data message with 28-bit user defined payload.
299         This API is intended for space and cpu restricted environments
300         that cannot support more complex message types.</td>
301  </tr>
302  <tr>
303    <td style="white-space:nowrap">
304       MIPI_SYST_SHORT64(h, v)
305    </td>
306    <td> Send short data message with 60-bit user defined payload.
307         This API is intended for space and cpu restricted environments
308         that cannot support more complex message types.</td>
309  </tr>
310  <tr>
311    <td style="white-space:nowrap">
312       MIPI_SYST_WRITE(h, sev, id, p, len)
313    </td>
314    <td> Send raw data message with user defined payload.</td>
315  </tr>
316</table>
317The #MIPI_SYST_WRITE API message macro must be enabled by the SyS-T platform
318define #MIPI_SYST_PCFG_ENABLE_WRITE_API, otherwise it expands to nothing inside
319the code. The #MIPI_SYST_SHORT32 and MIPI_SYST_SHORT64 APIs are always available.
320
321## Client software build ID message macros ##
322<table border=1 cols="3" align="left" width="100%">
323  <tr>
324    <td width="30%"><b>API Define</b></td>
325    <td><b>Description</b></td>
326  </tr>
327  <tr>
328    <td style="white-space:nowrap">
329       MIPI_SYST_BUILD(h, sev, ver, text, len)
330    </td>
331    <td> Send 64-bit client software build ID number and optional version text.</td>
332  </tr>
333  <tr>
334    <td style="white-space:nowrap">
335       MIPI_SYST_BUILD_COMPACT32(h, v)
336    </td>
337    <td> Send a 32-bit compact client software build ID message with 22-bit wide build number.
338    </td>
339  </tr>
340  <tr>
341    <td style="white-space:nowrap">
342       MIPI_SYST_BUILD_COMPACT64(h, v)
343    </td>
344    <td> Send a 64-bit compact client software build ID message value with a 54-bit wide build number.
345    </td>
346  </tr>
347</table>