1.. _samples_subsys_logging_syst:
2
3MIPI Sys-T Logging Sample
4#########################
5
6.. contents:: Table of Contents
7 :depth: 4
8 :local:
9 :backlinks: none
10
11Building and Running
12********************
13
14This project outputs a few sample log messages in MIPI Sys-T format.
15These Sys-T messages can be interpreted by a utility in
16:file:`<workspace>/modules/debug/mipi-sys-t/printer/`.
17
18Build the Sys-T Message Parser
19==============================
20
21.. code-block:: console
22
23 cd <workspace>/modules/debug/mipi-sys-t/printer/
24 mkdir build
25 cd build
26 cmake ../
27 make
28
29An newly built executable ``systprint`` can be found under
30:file:`<workspace>/modules/debug/mipi-sys-t/printer/build`.
31
32MIPI Sys-T Text Messages
33========================
34
35The Sys-T text messages are self contained strings that do not
36require additional artifacts to process.
37
38To build the sample printing text messages under ``qemu_x86``:
39
40.. zephyr-app-commands::
41 :zephyr-app: samples/subsys/logging/syst
42 :host-os: unix
43 :board: qemu_x86
44 :goals: build
45 :gen-args: -DCONFIG_LOG_BACKEND_SHOW_COLOR=n
46 :compact:
47
48Run the sample and capture the output in a text file:
49
50.. code-block:: console
51
52 west build -t run > /tmp/syst
53
54Since the output is being directed to a text file, there will not be
55any output printed on the terminal. So exit QEMU by pressing
56:kbd:`CTRL+A` :kbd:`x`.
57
58Sample Text Messages Output
59---------------------------
60
61The :file:`/tmp/syst` should contain something like this:
62
63.. code-block:: text
64
65 SeaBIOS (version zephyr-v1.0.0-0-g31d4e0e-dirty-20200714_234759-fv-az50-zephyr)
66 Booting from ROM..SYS-T RAW DATA: 020A000B490000000000000000002A2A2A20426F6F74696E67205A6570687972204F53206275696C64202573202573202A2A2A0A007A65706879722D76332E302E302D323036372D673166623436343433333731650000
67 SYS-T RAW DATA: 220A000B170001000000000000004572726F72206D657373616765206578616D706C652E00
68 SYS-T RAW DATA: 320A000B190001000000000000005761726E696E67206D657373616765206578616D706C652E00
69 SYS-T RAW DATA: 420A000B16000100000000000000496E666F206D657373616765206578616D706C652E00
70 SYS-T RAW DATA: 720A000B170001000000000000004465627567206D657373616765206578616D706C652E00
71 SYS-T RAW DATA: 720A000B1E0001000000000000004465627567206D657373616765206578616D706C652C2025640001000000
72 SYS-T RAW DATA: 720A000B260001000000000000004465627567206D657373616765206578616D706C652C2025642C202564000100000002000000
73 SYS-T RAW DATA: 720A000B2E0001000000000000004465627567206D657373616765206578616D706C652C2025642C2025642C20256400010000000200000003000000
74 SYS-T RAW DATA: 720A000B380001000000000000004465627567206D657373616765206578616D706C652C2025642C2025642C2025642C20307825780001000000020000000300000004000000
75 SYS-T RAW DATA: 720A000B0C000100000000000000636861722025630021000000
76 SYS-T RAW DATA: 720A000B1D0001000000000000007320737472202573202573007374617469632073747200632073747200
77 SYS-T RAW DATA: 720A000B1500010000000000000064207374722025730064796E616D69632073747200
78 SYS-T RAW DATA: 720A000B6B0001000000000000006D69786564207374722025732025732025732025732025732025732025730064796E616D696320737472002D2D2D0064796E616D696320737472002D2D2D00616E6F746865722064796E616D696320737472002D2D2D00616E6F746865722064796E616D69632073747200
79 SYS-T RAW DATA: 720A000B430001000000000000006D6978656420632F732025632025732025732025732025630021000000737461746963207374720064796E616D69632073747200737461746963207374720021000000
80 SYS-T RAW DATA: 720A000B220001000000000000004465627567206D657373616765206578616D706C652C20256600EA2E4454FB210940
81 SYS-T RAW DATA: 220A000B090001000000000000002573006672616D6500
82 SYS-T RAW DATA: 220A000B47000200000000000000257300303320643220303420303020303020303820303120303220203033203034203035203036203037203038202020202020207C2E2E2E2E2E2E2E2E202E2E2E2E2E2E202000
83 SYS-T RAW DATA: 320A000B090002000000000000002573006672616D6500
84 SYS-T RAW DATA: 320A000B47000200000000000000257300303320643220303420303020303020303820303120303220203033203034203035203036203037203038202020202020207C2E2E2E2E2E2E2E2E202E2E2E2E2E2E202000
85 SYS-T RAW DATA: 420A000B090002000000000000002573006672616D6500
86 SYS-T RAW DATA: 420A000B47000200000000000000257300303320643220303420303020303020303820303120303220203033203034203035203036203037203038202020202020207C2E2E2E2E2E2E2E2E202E2E2E2E2E2E202000
87 SYS-T RAW DATA: 720A000B090002000000000000002573006672616D6500
88 SYS-T RAW DATA: 720A000B47000200000000000000257300303320643220303420303020303020303820303120303220203033203034203035203036203037203038202020202020207C2E2E2E2E2E2E2E2E202E2E2E2E2E2E202000
89 SYS-T RAW DATA: 020A000B2200020000000000000068656C6C6F207379732D74206F6E20626F6172642025730A0071656D755F78383600
90 [ 0.020000] <err> syst: Error message example.
91 [ 0.020000] <wrn> syst: Warning message example.
92 [ 0.020000] <inf> syst: Info message example.
93 [ 0.020000] <dbg> syst: Debug message example.
94 [ 0.020000] <dbg> syst: Debug message example, 1
95 [ 0.020000] <dbg> syst: Debug message example, 1, 2
96 [ 0.020000] <dbg> syst: Debug message example, 1, 2, 3
97 [ 0.020000] <dbg> syst: Debug message example, 1, 2, 3, 0x4
98 [ 0.020000] <dbg> syst: char !
99 [ 0.020000] <dbg> syst: s str static str c str
100 [ 0.020000] <dbg> syst: d str dynamic str
101 [ 0.020000] <dbg> syst: mixed str dynamic str --- dynamic str --- another dynamic str --- another dynamic str
102 [ 0.020000] <dbg> syst: mixed c/s ! static str dynamic str static str !
103 [ 0.030000] <dbg> syst: Debug message example, %f
104 [ 0.030000] <err> syst: frame
105 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
106 [ 0.030000] <wrn> syst: frame
107 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
108 [ 0.030000] <inf> syst: frame
109 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
110 [ 0.030000] <dbg> syst: frame
111 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
112 hello sys-t on board qemu_x86
113 SYS-T RAW DATA: 220A000B170003000000000000004572726F72206D657373616765206578616D706C652E00
114 SYS-T RAW DATA: 320A000B190003000000000000005761726E696E67206D657373616765206578616D706C652E00
115 SYS-T RAW DATA: 420A000B16000300000000000000496E666F206D657373616765206578616D706C652E00
116 SYS-T RAW DATA: 720A000B170003000000000000004465627567206D657373616765206578616D706C652E00
117 SYS-T RAW DATA: 720A000B1E0003000000000000004465627567206D657373616765206578616D706C652C2025640001000000
118 SYS-T RAW DATA: 720A000B260003000000000000004465627567206D657373616765206578616D706C652C2025642C202564000100000002000000
119 SYS-T RAW DATA: 720A000B2E0003000000000000004465627567206D657373616765206578616D706C652C2025642C2025642C20256400010000000200000003000000
120 SYS-T RAW DATA: 720A000B380003000000000000004465627567206D657373616765206578616D706C652C2025642C2025642C2025642C20307825780001000000020000000300000004000000
121 SYS-T RAW DATA: 720A000B0C000300000000000000636861722025630021000000
122 SYS-T RAW DATA: 720A000B1D0003000000000000007320737472202573202573007374617469632073747200632073747200
123 SYS-T RAW DATA: 720A000B1500030000000000000064207374722025730064796E616D69632073747200
124 SYS-T RAW DATA: 720A000B6B0003000000000000006D69786564207374722025732025732025732025732025732025732025730064796E616D696320737472002D2D2D0064796E616D696320737472002D2D2D00616E6F746865722064796E616D696320737472002D2D2D00616E6F746865722064796E616D69632073747200
125 SYS-T RAW DATA: 720A000B430004000000000000006D6978656420632F732025632025732025732025732025630021000000737461746963207374720064796E616D69632073747200737461746963207374720021000000
126 SYS-T RAW DATA: 720A000B220004000000000000004465627567206D657373616765206578616D706C652C20256600EA2E4454FB210940
127 SYS-T RAW DATA: 220A000B090004000000000000002573006672616D6500
128 SYS-T RAW DATA: 220A000B47000400000000000000257300303320643220303420303020303020303820303120303220203033203034203035203036203037203038202020202020207C2E2E2E2E2E2E2E2E202E2E2E2E2E2E202000
129 SYS-T RAW DATA: 320A000B090004000000000000002573006672616D6500
130 SYS-T RAW DATA: 320A000B47000400000000000000257300303320643220303420303020303020303820303120303220203033203034203035203036203037203038202020202020207C2E2E2E2E2E2E2E2E202E2E2E2E2E2E202000
131 SYS-T RAW DATA: 420A000B090004000000000000002573006672616D6500
132 SYS-T RAW DATA: 420A000B47000400000000000000257300303320643220303420303020303020303820303120303220203033203034203035203036203037203038202020202020207C2E2E2E2E2E2E2E2E202E2E2E2E2E2E202000
133 SYS-T RAW DATA: 720A000B090004000000000000002573006672616D6500
134 SYS-T RAW DATA: 720A000B47000400000000000000257300303320643220303420303020303020303820303120303220203033203034203035203036203037203038202020202020207C2E2E2E2E2E2E2E2E202E2E2E2E2E2E202000
135 SYS-T RAW DATA: 020A000B2200040000000000000068656C6C6F207379732D74206F6E20626F6172642025730A0071656D755F78383600
136 QEMU: Terminated
137
138Parsing Text Messages
139^^^^^^^^^^^^^^^^^^^^^
140
141Use ``systprint`` to parse the output:
142
143.. code-block:: console
144
145 <workspace>/modules/debug/mipi-sys-t/printer/build/systprint -p /tmp/syst
146
147And the parsed messages:
148
149.. code-block:: text
150
151 Error message example.
152 Warning message example.
153 Info message example.
154 Debug message example.
155 Debug message example, 1
156 Debug message example, 1, 2
157 Debug message example, 1, 2, 3
158 Debug message example, 1, 2, 3, 0x4
159 char !
160 s str static str c str
161 d str dynamic str
162 mixed str dynamic str --- dynamic str --- another dynamic str --- another dynamic str
163 mixed c/s ! static str dynamic str static str !
164 Debug message example, 3.141593
165 frame
166 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
167 frame
168 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
169 frame
170 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
171 frame
172 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
173 hello sys-t on board qemu_x86
174
175 Warning message example.
176 Info message example.
177 Debug message example.
178 Debug message example, 1
179 Debug message example, 1, 2
180 Debug message example, 1, 2, 3
181 Debug message example, 1, 2, 3, 0x4
182 char !
183 s str static str c str
184 d str dynamic str
185 mixed str dynamic str --- dynamic str --- another dynamic str --- another dynamic str
186 mixed c/s ! static str dynamic str static str !
187 Debug message example, 3.141593
188 frame
189 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
190 frame
191 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
192 frame
193 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
194 frame
195 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
196 hello sys-t on board qemu_x86
197
198
199MIPI Sys-T Catalog Messages
200===========================
201
202Catalog messages are similar to dictionary logging where the format strings
203are being referenced by identification hashes, and the string arguments
204are encoded in the Sys-T message payload. The hashes and the encoded
205arguments can be combined offline with the collateral file (which contains
206the mapping between hashes and their corresponding format strings) to
207form the actual messages.
208
209To build the sample printing catalog messages under ``qemu_x86``:
210
211.. zephyr-app-commands::
212 :zephyr-app: samples/subsys/logging/syst
213 :host-os: unix
214 :board: qemu_x86
215 :goals: build
216 :gen-args: -DCONFIG_LOG_BACKEND_SHOW_COLOR=n -DCONFIG_LOG_MIPI_SYST_USE_CATALOG=y
217 :compact:
218
219Run the sample and capture the output in a text file:
220
221.. code-block:: console
222
223 west build -t run > /tmp/syst
224
225Since the output is being directed to a text file, there will not be
226any output printed on the terminal. So exit QEMU by pressing
227:kbd:`CTRL+A` :kbd:`x`.
228
229Sample Catalog Messages Output
230------------------------------
231
232The :file:`/tmp/syst` should contain something like this:
233
234.. code-block:: text
235
236 SeaBIOS (version zephyr-v1.0.0-0-g31d4e0e-dirty-20200714_234759-fv-az50-zephyr)
237 Booting from ROM..SYS-T RAW DATA: 020A000B490000000000000000002A2A2A20426F6F74696E67205A6570687972204F53206275696C64202573202573202A2A2A0A007A65706879722D76332E302E302D323036372D673166623436343433333731650000
238 SYS-T RAW DATA: 230A0001040001000000000000004C221100
239 SYS-T RAW DATA: 330A00010400010000000000000030221100
240 SYS-T RAW DATA: 430A00010400010000000000000018221100
241 SYS-T RAW DATA: 730A00010400010000000000000000221100
242 SYS-T RAW DATA: 730A000108000100000000000000E421110001000000
243 SYS-T RAW DATA: 730A00010C000100000000000000C42111000100000002000000
244 SYS-T RAW DATA: 730A000110000100000000000000A0211100010000000200000003000000
245 SYS-T RAW DATA: 730A0001140001000000000000006021110001000000020000000300000004000000
246 SYS-T RAW DATA: 730A0001080001000000000000003C21110021000000
247 SYS-T RAW DATA: 730A000115000100000000000000302111007374617469632073747200632073747200
248 SYS-T RAW DATA: 730A0001100001000000000000002421110064796E616D69632073747200
249 SYS-T RAW DATA: 730A0001500001000000000000000421110064796E616D696320737472002D2D2D0064796E616D696320737472002D2D2D00616E6F746865722064796E616D696320737472002D2D2D00616E6F746865722064796E616D69632073747200
250 SYS-T RAW DATA: 730A00013E000100000000000000E820110021000000737461746963207374720064796E616D696320737472007374617469632073747200210000000103050464796E616D69632073747200
251 SYS-T RAW DATA: 730A00010C000100000000000000CC201100EA2E4454FB210940
252 SYS-T RAW DATA: 230A00010A000100000000000000C92011006672616D6500
253 SYS-T RAW DATA: 220A000B47000100000000000000257300303320643220303420303020303020303820303120303220203033203034203035203036203037203038202020202020207C2E2E2E2E2E2E2E2E202E2E2E2E2E2E202000
254 SYS-T RAW DATA: 330A00010A000100000000000000C62011006672616D6500
255 SYS-T RAW DATA: 320A000B47000100000000000000257300303320643220303420303020303020303820303120303220203033203034203035203036203037203038202020202020207C2E2E2E2E2E2E2E2E202E2E2E2E2E2E202000
256 SYS-T RAW DATA: 430A00010A000200000000000000C32011006672616D6500
257 SYS-T RAW DATA: 420A000B47000200000000000000257300303320643220303420303020303020303820303120303220203033203034203035203036203037203038202020202020207C2E2E2E2E2E2E2E2E202E2E2E2E2E2E202000
258 SYS-T RAW DATA: 730A00010A000200000000000000C02011006672616D6500
259 SYS-T RAW DATA: 720A000B47000200000000000000257300303320643220303420303020303020303820303120303220203033203034203035203036203037203038202020202020207C2E2E2E2E2E2E2E2E202E2E2E2E2E2E202000
260 SYS-T RAW DATA: 020A000B2200020000000000000068656C6C6F207379732D74206F6E20626F6172642025730A0071656D755F78383600
261 [ 0.020000] <err> syst: Error message example.
262 [ 0.020000] <wrn> syst: Warning message example.
263 [ 0.020000] <inf> syst: Info message example.
264 [ 0.020000] <dbg> syst: Debug message example.
265 [ 0.020000] <dbg> syst: Debug message example, 1
266 [ 0.020000] <dbg> syst: Debug message example, 1, 2
267 [ 0.020000] <dbg> syst: Debug message example, 1, 2, 3
268 [ 0.020000] <dbg> syst: Debug message example, 1, 2, 3, 0x4
269 [ 0.020000] <dbg> syst: char !
270 [ 0.020000] <dbg> syst: s str static str c str
271 [ 0.020000] <dbg> syst: d str dynamic str
272 [ 0.020000] <dbg> syst: mixed str dynamic str --- dynamic str --- another dynamic str --- another dynamic str
273 [ 0.020000] <dbg> syst: mixed c/s ! static str dynamic str static str !
274 [ 0.020000] <dbg> syst: Debug message example, %f
275 [ 0.020000] <err> syst: frame
276 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
277 [ 0.020000] <wrn> syst: frame
278 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
279 [ 0.020000] <inf> syst: frame
280 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
281 [ 0.030000] <dbg> syst: frame
282 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
283 hello sys-t on board qemu_x86
284 SYS-T RAW DATA: 230A0001040003000000000000004C221100
285 SYS-T RAW DATA: 330A00010400030000000000000030221100
286 SYS-T RAW DATA: 430A00010400030000000000000018221100
287 SYS-T RAW DATA: 730A00010400030000000000000000221100
288 SYS-T RAW DATA: 730A000108000300000000000000E421110001000000
289 SYS-T RAW DATA: 730A00010C000300000000000000C42111000100000002000000
290 SYS-T RAW DATA: 730A000110000300000000000000A0211100010000000200000003000000
291 SYS-T RAW DATA: 730A0001140003000000000000006021110001000000020000000300000004000000
292 SYS-T RAW DATA: 730A0001080003000000000000003C21110021000000
293 SYS-T RAW DATA: 730A000115000300000000000000302111007374617469632073747200632073747200
294 SYS-T RAW DATA: 730A0001100003000000000000002421110064796E616D69632073747200
295 SYS-T RAW DATA: 730A0001500003000000000000000421110064796E616D696320737472002D2D2D0064796E616D696320737472002D2D2D00616E6F746865722064796E616D696320737472002D2D2D00616E6F746865722064796E616D69632073747200
296 SYS-T RAW DATA: 730A00013E000300000000000000E820110021000000737461746963207374720064796E616D696320737472007374617469632073747200210000000103050464796E616D69632073747200
297 SYS-T RAW DATA: 730A00010C000300000000000000CC201100EA2E4454FB210940
298 SYS-T RAW DATA: 230A00010A000300000000000000C92011006672616D6500
299 SYS-T RAW DATA: 220A000B47000300000000000000257300303320643220303420303020303020303820303120303220203033203034203035203036203037203038202020202020207C2E2E2E2E2E2E2E2E202E2E2E2E2E2E202000
300 SYS-T RAW DATA: 330A00010A000300000000000000C62011006672616D6500
301 SYS-T RAW DATA: 320A000B47000300000000000000257300303320643220303420303020303020303820303120303220203033203034203035203036203037203038202020202020207C2E2E2E2E2E2E2E2E202E2E2E2E2E2E202000
302 SYS-T RAW DATA: 430A00010A000400000000000000C32011006672616D6500
303 SYS-T RAW DATA: 420A000B47000400000000000000257300303320643220303420303020303020303820303120303220203033203034203035203036203037203038202020202020207C2E2E2E2E2E2E2E2E202E2E2E2E2E2E202000
304 SYS-T RAW DATA: 730A00010A000400000000000000C02011006672616D6500
305 SYS-T RAW DATA: 720A000B47000400000000000000257300303320643220303420303020303020303820303120303220203033203034203035203036203037203038202020202020207C2E2E2E2E2E2E2E2E202E2E2E2E2E2E202000
306 SYS-T RAW DATA: 020A000B2200040000000000000068656C6C6F207379732D74206F6E20626F6172642025730A0071656D755F78383600
307 QEMU: Terminated
308
309Notice the shorter payload of catalog messages compared to text messages.
310
311Parsing Catalog Messages
312^^^^^^^^^^^^^^^^^^^^^^^^
313
314Use ``systprint`` to parse the output:
315
316.. code-block:: console
317
318 <workspace>/modules/debug/mipi-sys-t/printer/build/systprint -c <build_dir>/zephyr/mipi_syst_collateral.xml -p /tmp/syst
319
320And the parsed messages:
321
322.. code-block:: text
323
324 Error message example.
325 Warning message example.
326 Info message example.
327 Debug message example.
328 Debug message example, 1
329 Debug message example, 1, 2
330 Debug message example, 1, 2, 3
331 Debug message example, 1, 2, 3, 0x4
332 char !
333 s str static str c str
334 d str dynamic str
335 mixed str dynamic str --- dynamic str --- another dynamic str --- another dynamic str
336 mixed c/s ! static str dynamic str static str !
337 Debug message example, 3.141593
338 frame
339 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
340 frame
341 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
342 frame
343 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
344 frame
345 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
346 hello sys-t on board qemu_x86
347
348 Error message example.
349 Warning message example.
350 Info message example.
351 Debug message example.
352 Debug message example, 1
353 Debug message example, 1, 2
354 Debug message example, 1, 2, 3
355 Debug message example, 1, 2, 3, 0x4
356 char !
357 s str static str c str
358 d str dynamic str
359 mixed str dynamic str --- dynamic str --- another dynamic str --- another dynamic str
360 mixed c/s ! static str dynamic str static str !
361 Debug message example, 3.141593
362 frame
363 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
364 frame
365 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
366 frame
367 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
368 frame
369 03 d2 04 00 00 08 01 02 03 04 05 06 07 08 |........ ......
370 hello sys-t on board qemu_x86
371
