Commit | Line | Data |
---|---|---|
a8afdd3c PMF |
1 | #LyX 1.6.1 created this file. For more info see http://www.lyx.org/ |
2 | \lyxformat 345 | |
3 | \begin_document | |
4 | \begin_header | |
5 | \textclass article | |
6 | \use_default_options true | |
7 | \language english | |
8 | \inputencoding auto | |
9 | \font_roman default | |
10 | \font_sans default | |
11 | \font_typewriter default | |
12 | \font_default_family default | |
13 | \font_sc false | |
14 | \font_osf false | |
15 | \font_sf_scale 100 | |
16 | \font_tt_scale 100 | |
17 | ||
18 | \graphics default | |
19 | \paperfontsize default | |
20 | \use_hyperref false | |
21 | \papersize default | |
22 | \use_geometry false | |
23 | \use_amsmath 1 | |
24 | \use_esint 1 | |
25 | \cite_engine basic | |
26 | \use_bibtopic false | |
27 | \paperorientation portrait | |
28 | \secnumdepth 3 | |
29 | \tocdepth 3 | |
30 | \paragraph_separation indent | |
31 | \defskip medskip | |
32 | \quotes_language english | |
33 | \papercolumns 1 | |
34 | \papersides 1 | |
35 | \paperpagestyle default | |
36 | \tracking_changes false | |
37 | \output_changes false | |
38 | \author "" | |
0ce2af7f | 39 | \author "" |
a8afdd3c PMF |
40 | \end_header |
41 | ||
42 | \begin_body | |
43 | ||
44 | \begin_layout Title | |
45 | LTTng Userspace Tracer Manual | |
46 | \end_layout | |
47 | ||
48 | \begin_layout Author | |
49 | Pierre-Marc Fournier | |
50 | \end_layout | |
51 | ||
52 | \begin_layout Section | |
53 | What is the LTTng Userspace Tracer? | |
54 | \end_layout | |
55 | ||
56 | \begin_layout Subsection | |
57 | Overview | |
58 | \end_layout | |
59 | ||
0ce2af7f PMF |
60 | \begin_layout Standard |
61 | The LTTng Userspace Tracer (UST) is a tracing system for userspace applications. | |
62 | It is designed to trace efficiently applications that produce events at | |
63 | a very high rate. | |
64 | UST is derived from LTTng, a tracer for the Linux kernel. | |
65 | It has the same trace format. | |
66 | \end_layout | |
67 | ||
68 | \begin_layout Standard | |
69 | Users may choose at runtime and even at trace time what instrumentation | |
70 | should be activated. | |
71 | Custom probes may be used to trace events conditionally. | |
72 | \end_layout | |
73 | ||
a8afdd3c PMF |
74 | \begin_layout Subsection |
75 | Features | |
76 | \end_layout | |
77 | ||
78 | \begin_layout Itemize | |
79 | Arbitrary number of channels | |
80 | \end_layout | |
81 | ||
82 | \begin_layout Itemize | |
83 | One buffer per process (multiple threads share the same buffer) | |
84 | \end_layout | |
85 | ||
86 | \begin_layout Itemize | |
7c2343de | 87 | Early process tracing (from the beginning of the main() function) |
a8afdd3c PMF |
88 | \end_layout |
89 | ||
0ce2af7f PMF |
90 | \begin_layout Itemize |
91 | Support for custom probes | |
92 | \end_layout | |
93 | ||
a8afdd3c PMF |
94 | \begin_layout Standard |
95 | Still to implement: | |
96 | \end_layout | |
97 | ||
0ce2af7f | 98 | \begin_layout Itemize |
7c2343de PMF |
99 | Support for dynamic instrumentation |
100 | \end_layout | |
101 | ||
102 | \begin_layout Itemize | |
103 | Per thread or per CPU buffers | |
0ce2af7f PMF |
104 | \end_layout |
105 | ||
106 | \begin_layout Standard | |
107 | Complementary systems: | |
108 | \end_layout | |
109 | ||
110 | \begin_layout Itemize | |
111 | A extension to gdb tracepoints that will allow the tracing of applications | |
112 | with dynamic instrumentation is under development. | |
113 | \end_layout | |
114 | ||
a8afdd3c PMF |
115 | \begin_layout Subsection |
116 | Performance | |
117 | \end_layout | |
118 | ||
7c2343de PMF |
119 | \begin_layout Section |
120 | Installation | |
121 | \end_layout | |
122 | ||
a8afdd3c PMF |
123 | \begin_layout Section |
124 | Instrumenting an Application | |
125 | \end_layout | |
126 | ||
127 | \begin_layout Standard | |
128 | In order to record a trace of events occurring in a application, the application | |
129 | must be instrumented. | |
0ce2af7f PMF |
130 | Instrumentation points resemble function calls. |
131 | When the program reaches an instrumentation point, an event is generated. | |
a8afdd3c PMF |
132 | \end_layout |
133 | ||
134 | \begin_layout Standard | |
135 | There are no limitations on the type of code that may be instrumented. | |
136 | Multi-threaded programs may be instrumented without problem. | |
7c2343de | 137 | Signal handlers may be instrumented as well. |
a8afdd3c PMF |
138 | \end_layout |
139 | ||
140 | \begin_layout Standard | |
141 | There are two APIs to instrument programs: markers and tracepoints. | |
142 | Markers are quick to add and are usually used for temporary instrumentation. | |
143 | Tracepoints provide a way to instrument code more cleanly and are suited | |
144 | for permanent instrumentation. | |
145 | \end_layout | |
146 | ||
147 | \begin_layout Subsection | |
148 | Markers | |
149 | \end_layout | |
150 | ||
0ce2af7f PMF |
151 | \begin_layout Standard |
152 | Markers were ported from the Linux Kernel Markers implementation. | |
153 | Therefore, their usage is almost identical. | |
154 | \end_layout | |
155 | ||
a8afdd3c PMF |
156 | \begin_layout Subsubsection |
157 | Inserting Markers | |
158 | \end_layout | |
159 | ||
160 | \begin_layout Standard | |
161 | Adding a marker is simply a matter of insert one line in the program. | |
162 | \end_layout | |
163 | ||
164 | \begin_layout Standard | |
165 | \begin_inset listings | |
166 | inline false | |
167 | status open | |
168 | ||
169 | \begin_layout Plain Layout | |
170 | ||
171 | #include <marker.h> | |
172 | \end_layout | |
173 | ||
174 | \begin_layout Plain Layout | |
175 | ||
7c2343de | 176 | int main(int argc, char **argv) |
a8afdd3c PMF |
177 | \end_layout |
178 | ||
179 | \begin_layout Plain Layout | |
180 | ||
181 | { | |
182 | \end_layout | |
183 | ||
184 | \begin_layout Plain Layout | |
185 | ||
186 | int v; | |
187 | \end_layout | |
188 | ||
189 | \begin_layout Plain Layout | |
190 | ||
191 | char *st; | |
192 | \end_layout | |
193 | ||
194 | \begin_layout Plain Layout | |
195 | ||
196 | \end_layout | |
197 | ||
198 | \begin_layout Plain Layout | |
199 | ||
200 | /* ... | |
201 | set values of v and st ... | |
202 | */ | |
203 | \end_layout | |
204 | ||
205 | \begin_layout Plain Layout | |
206 | ||
207 | \end_layout | |
208 | ||
209 | \begin_layout Plain Layout | |
210 | ||
211 | /* a marker: */ | |
212 | \end_layout | |
213 | ||
214 | \begin_layout Plain Layout | |
215 | ||
216 | trace_mark(main, myevent, | |
217 | \begin_inset Quotes eld | |
218 | \end_inset | |
219 | ||
220 | firstarg %d secondarg %s | |
221 | \begin_inset Quotes erd | |
222 | \end_inset | |
223 | ||
224 | , v, st); | |
225 | \end_layout | |
226 | ||
227 | \begin_layout Plain Layout | |
228 | ||
229 | \end_layout | |
230 | ||
231 | \begin_layout Plain Layout | |
232 | ||
233 | /* a marker without arguments: */ | |
234 | \end_layout | |
235 | ||
236 | \begin_layout Plain Layout | |
237 | ||
238 | trace_mark(main, myotherevent, MARK_NOARGS); | |
239 | \end_layout | |
240 | ||
241 | \begin_layout Plain Layout | |
242 | ||
7c2343de PMF |
243 | \end_layout |
244 | ||
245 | \begin_layout Plain Layout | |
246 | ||
247 | return 0; | |
248 | \end_layout | |
249 | ||
250 | \begin_layout Plain Layout | |
251 | ||
a8afdd3c PMF |
252 | } |
253 | \end_layout | |
254 | ||
255 | \end_inset | |
256 | ||
257 | ||
258 | \end_layout | |
259 | ||
260 | \begin_layout Standard | |
261 | The invocation of the trace_mark() macro requires at least 3 arguments. | |
262 | The first, here | |
263 | \begin_inset Quotes eld | |
264 | \end_inset | |
265 | ||
266 | main | |
267 | \begin_inset Quotes erd | |
268 | \end_inset | |
269 | ||
270 | , is the name of the event category. | |
271 | It is also the name of the channel the event will go in. | |
272 | The second, here | |
273 | \begin_inset Quotes eld | |
274 | \end_inset | |
275 | ||
276 | myevent | |
277 | \begin_inset Quotes erd | |
278 | \end_inset | |
279 | ||
280 | is the name of the event. | |
281 | The third is a format string that announces the names and the types of | |
282 | the event arguments. | |
283 | Its format resembles that of a printf() format string; it is described | |
284 | thoroughly in Appendix x. | |
285 | \end_layout | |
286 | ||
287 | \begin_layout Standard | |
288 | A given Marker may appear more than once in the same program. | |
289 | Other Markers may have the same name and a different format string, although | |
290 | this might induce some confusion at analysis time. | |
291 | \end_layout | |
292 | ||
293 | \begin_layout Subsubsection | |
294 | Registering the Markers | |
295 | \end_layout | |
296 | ||
297 | \begin_layout Standard | |
298 | In order to inform to register the Markers present in the module, a macro | |
299 | must be inserted at global scope. | |
300 | Only one such macro is needed per exacutable or per shared object. | |
301 | Adding it more than once, however, is harmless. | |
302 | \end_layout | |
303 | ||
304 | \begin_layout Standard | |
305 | \begin_inset listings | |
306 | inline false | |
307 | status open | |
308 | ||
309 | \begin_layout Plain Layout | |
310 | ||
311 | MARKER_LIB; | |
312 | \end_layout | |
313 | ||
314 | \end_inset | |
315 | ||
316 | ||
317 | \end_layout | |
318 | ||
319 | \begin_layout Subsection | |
320 | Tracepoints | |
321 | \end_layout | |
322 | ||
323 | \begin_layout Standard | |
324 | The Tracepoints API uses the Markers, but provides a higher-level abstraction. | |
325 | Whereas the markers API provides limited type checking, the Tracepoints | |
326 | API provides more thorough type checking and discharges from the need to | |
327 | insert format strings directly in the code and to have format strings appear | |
328 | more than once if a given marker is reused. | |
329 | \end_layout | |
330 | ||
331 | \begin_layout Standard | |
332 | A tracepoint in the code looks like this: | |
333 | \end_layout | |
334 | ||
335 | \begin_layout Standard | |
336 | \begin_inset listings | |
337 | inline false | |
338 | status open | |
339 | ||
340 | \begin_layout Plain Layout | |
341 | ||
342 | #include <marker.h> | |
343 | \end_layout | |
344 | ||
345 | \begin_layout Plain Layout | |
346 | ||
347 | \end_layout | |
348 | ||
349 | \begin_layout Plain Layout | |
350 | ||
351 | void function() | |
352 | \end_layout | |
353 | ||
354 | \begin_layout Plain Layout | |
355 | ||
356 | { | |
357 | \end_layout | |
358 | ||
359 | \begin_layout Plain Layout | |
360 | ||
361 | int v; | |
362 | \end_layout | |
363 | ||
364 | \begin_layout Plain Layout | |
365 | ||
366 | char *st; | |
367 | \end_layout | |
368 | ||
369 | \begin_layout Plain Layout | |
370 | ||
371 | \end_layout | |
372 | ||
373 | \begin_layout Plain Layout | |
374 | ||
375 | /* ... | |
376 | set values of v and st ... | |
377 | */ | |
378 | \end_layout | |
379 | ||
380 | \begin_layout Plain Layout | |
381 | ||
382 | \end_layout | |
383 | ||
384 | \begin_layout Plain Layout | |
385 | ||
386 | /* a tracepoint: */ | |
387 | \end_layout | |
388 | ||
389 | \begin_layout Plain Layout | |
390 | ||
391 | trace_main_myevent(v, st); | |
392 | \end_layout | |
393 | ||
394 | \begin_layout Plain Layout | |
395 | ||
396 | } | |
397 | \end_layout | |
398 | ||
399 | \end_inset | |
400 | ||
401 | ||
402 | \end_layout | |
403 | ||
404 | \begin_layout Standard | |
405 | \begin_inset listings | |
406 | inline false | |
407 | status open | |
408 | ||
409 | \begin_layout Plain Layout | |
410 | ||
411 | DEFINE_TRACE(); | |
412 | \end_layout | |
413 | ||
414 | \end_inset | |
415 | ||
416 | ||
417 | \end_layout | |
418 | ||
419 | \begin_layout Standard | |
420 | \begin_inset listings | |
421 | inline false | |
422 | status open | |
423 | ||
424 | \begin_layout Plain Layout | |
425 | ||
426 | TRACEPOINT_LIB; | |
427 | \end_layout | |
428 | ||
429 | \end_inset | |
430 | ||
431 | ||
432 | \end_layout | |
433 | ||
434 | \begin_layout Subsection | |
435 | Compiling the Application | |
436 | \end_layout | |
437 | ||
7c2343de PMF |
438 | \begin_layout Standard |
439 | See the | |
440 | \begin_inset Quotes eld | |
441 | \end_inset | |
442 | ||
443 | hello | |
444 | \begin_inset Quotes erd | |
445 | \end_inset | |
446 | ||
447 | directory for an example application and makefile. | |
448 | \end_layout | |
449 | ||
450 | \begin_layout Itemize | |
451 | The compiler must have access to the include path for the libust headers. | |
452 | \end_layout | |
453 | ||
454 | \begin_layout Itemize | |
455 | The application should be statically or dynamically linked to libust. | |
456 | \end_layout | |
457 | ||
a8afdd3c PMF |
458 | \begin_layout Section |
459 | Recording a Trace | |
460 | \end_layout | |
461 | ||
462 | \begin_layout Subsection | |
463 | Basic Recording | |
464 | \end_layout | |
465 | ||
466 | \begin_layout Subsection | |
467 | Early Tracing | |
468 | \end_layout | |
469 | ||
0ce2af7f PMF |
470 | \begin_layout Standard |
471 | Sometimes, an application must be traced as soon as it is started. | |
472 | In these cases, the Basic Recording method is not satisfactory, as important | |
473 | events may be lost before the tracing is started. | |
474 | \end_layout | |
475 | ||
476 | \begin_layout Standard | |
477 | By using the Early Tracing method, it is guaranteed that the tracing is | |
478 | started when the execution of the main() function of the program starts. | |
479 | \end_layout | |
480 | ||
481 | \begin_layout Standard | |
482 | Early Tracing may be enabled by defining the UST_TRACE environment variable | |
483 | to a non-empty value when the program starts. | |
484 | Additionally, the UST_AUTOPROBE may be set to a non-empty value to automaticall | |
485 | y connect all markers to the default probe. | |
486 | For example: | |
487 | \end_layout | |
488 | ||
489 | \begin_layout Standard | |
490 | \begin_inset listings | |
491 | inline false | |
492 | status open | |
493 | ||
494 | \begin_layout Plain Layout | |
495 | ||
496 | $ UST_TRACE=1 UST_AUTOPROBE=1 ./prog | |
497 | \end_layout | |
498 | ||
499 | \end_inset | |
500 | ||
501 | ||
502 | \end_layout | |
503 | ||
504 | \begin_layout Standard | |
505 | In order for the trace to be saved, ustd must be running when the traced | |
506 | program is started. | |
507 | \end_layout | |
508 | ||
a8afdd3c PMF |
509 | \begin_layout Section |
510 | Viewing and Analyzing the Trace | |
511 | \end_layout | |
512 | ||
0ce2af7f PMF |
513 | \begin_layout Standard |
514 | LTTV may be used for opening the trace. | |
515 | If an appropriate time source was used, it may be opened concurrently with | |
516 | other application traces and kernel traces. | |
517 | \end_layout | |
518 | ||
a8afdd3c PMF |
519 | \begin_layout Section |
520 | Advanced Concepts | |
521 | \end_layout | |
522 | ||
523 | \begin_layout Subsection | |
0ce2af7f | 524 | Using Custom Probes for Conditional Tracing |
a8afdd3c PMF |
525 | \end_layout |
526 | ||
527 | \begin_layout Subsection | |
528 | Instrumenting Calls to Library Functions without Recompilation | |
529 | \end_layout | |
530 | ||
531 | \begin_layout Standard | |
532 | Calls to uninstrumented libraries may be instrumented by creating a wrapper | |
533 | library that intercepts calls to the library, trigger an instrumentation | |
534 | point. | |
535 | \end_layout | |
536 | ||
537 | \begin_layout Subsection | |
538 | Tracing Programs Without Linking them to the Tracing Library | |
539 | \end_layout | |
540 | ||
541 | \begin_layout Standard | |
542 | Programs that were not instrumented nor linked with the tracing libraries | |
543 | may still be traced. | |
544 | In order to produce events, they must be linked to instrumented libraries | |
545 | or use instrumented library wrappers as described in section xx. | |
546 | \end_layout | |
547 | ||
548 | \begin_layout Standard | |
549 | \begin_inset listings | |
550 | inline false | |
551 | status open | |
552 | ||
553 | \begin_layout Plain Layout | |
554 | ||
555 | LD_PRELOAD=... | |
556 | program | |
557 | \end_layout | |
558 | ||
559 | \end_inset | |
560 | ||
561 | ||
562 | \end_layout | |
563 | ||
564 | \begin_layout Section | |
565 | \start_of_appendix | |
566 | Format of Marker Format Strings | |
567 | \end_layout | |
568 | ||
0ce2af7f PMF |
569 | \begin_layout Standard |
570 | The format of Marker format strings is inspired from printf() format strings. | |
571 | As with printf(), it is used to indicate to the parsing function the type | |
572 | of the arguments that are passed. | |
573 | Additionally, format strings indicate the name of each argument and the | |
574 | format of that argument in the trace. | |
575 | The structure of a typical format string is the following. | |
576 | \end_layout | |
577 | ||
578 | \begin_layout Standard | |
579 | \begin_inset listings | |
580 | inline false | |
581 | status open | |
582 | ||
583 | \begin_layout Plain Layout | |
584 | ||
585 | \begin_inset Quotes eld | |
586 | \end_inset | |
587 | ||
588 | field_name1 #tracetype1 %ctype1 field_name2 #tracetype2 %ctype2 | |
589 | \begin_inset Quotes erd | |
590 | \end_inset | |
591 | ||
592 | ||
593 | \end_layout | |
594 | ||
595 | \end_inset | |
596 | ||
597 | ||
598 | \end_layout | |
599 | ||
600 | \begin_layout Description | |
601 | field_name: The name of the field, as it will be seen when the trace is | |
602 | parsed. | |
603 | \end_layout | |
604 | ||
605 | \begin_layout Description | |
606 | tracetype: The type of the argument as it will be written in the trace. | |
607 | \end_layout | |
608 | ||
609 | \begin_layout Description | |
610 | ctype: The C type of the argument passed to the Marker (this is very similar | |
611 | to the %... | |
612 | types in a printf() format string) | |
613 | \end_layout | |
614 | ||
615 | \begin_layout Standard | |
616 | Both field_name and tracetype are optional. | |
617 | These are all valid format strings: | |
618 | \end_layout | |
619 | ||
620 | \begin_layout Standard | |
621 | \begin_inset listings | |
622 | inline false | |
623 | status open | |
624 | ||
625 | \begin_layout Plain Layout | |
626 | ||
627 | \end_layout | |
628 | ||
629 | \end_inset | |
630 | ||
631 | ||
632 | \end_layout | |
633 | ||
634 | \begin_layout Subsection | |
635 | tracetype | |
636 | \end_layout | |
637 | ||
638 | \begin_layout Standard | |
639 | A typical Marker format string looks like this: | |
640 | \end_layout | |
641 | ||
642 | \begin_layout Standard | |
643 | The serialization format string supports the basic printf format strings. | |
644 | \end_layout | |
645 | ||
646 | \begin_layout Standard | |
647 | In addition, it defines new formats that can be used to serialize more | |
648 | \end_layout | |
649 | ||
650 | \begin_layout Standard | |
651 | complex/non portable data structures. | |
652 | \end_layout | |
653 | ||
654 | \begin_layout Standard | |
655 | Typical use: | |
656 | \end_layout | |
657 | ||
658 | \begin_layout Standard | |
659 | field_name %ctype | |
660 | \end_layout | |
661 | ||
662 | \begin_layout Standard | |
663 | field_name #tracetype %ctype | |
664 | \end_layout | |
665 | ||
666 | \begin_layout Standard | |
667 | field_name #tracetype %ctype1 %ctype2 ... | |
668 | \end_layout | |
669 | ||
670 | \begin_layout Standard | |
671 | A conversion is performed between format string types supported by GCC and | |
672 | \end_layout | |
673 | ||
674 | \begin_layout Standard | |
675 | the trace type requested. | |
676 | GCC type is used to perform type checking on format | |
677 | \end_layout | |
678 | ||
679 | \begin_layout Standard | |
680 | strings. | |
681 | Trace type is used to specify the exact binary representation | |
682 | \end_layout | |
683 | ||
684 | \begin_layout Standard | |
685 | in the trace. | |
686 | A mapping is done between one or more GCC types to one trace | |
687 | \end_layout | |
688 | ||
689 | \begin_layout Standard | |
690 | type. | |
691 | Sign extension, if required by the conversion, is performed following | |
692 | \end_layout | |
693 | ||
694 | \begin_layout Standard | |
695 | the trace type. | |
696 | \end_layout | |
697 | ||
698 | \begin_layout Standard | |
699 | If a gcc format is not declared with a trace format, the gcc format is | |
700 | \end_layout | |
701 | ||
702 | \begin_layout Standard | |
703 | also used as binary representation in the trace. | |
704 | \end_layout | |
705 | ||
706 | \begin_layout Standard | |
707 | Strings are supported with %s. | |
708 | \end_layout | |
709 | ||
710 | \begin_layout Standard | |
711 | A single tracetype (sequence) can take multiple c types as parameter. | |
712 | \end_layout | |
713 | ||
714 | \begin_layout Standard | |
715 | c types: | |
716 | \end_layout | |
717 | ||
718 | \begin_layout Standard | |
719 | see printf(3). | |
720 | \end_layout | |
721 | ||
722 | \begin_layout Standard | |
723 | Note: to write a uint32_t in a trace, the following expression is recommended | |
724 | \end_layout | |
725 | ||
726 | \begin_layout Standard | |
727 | si it can be portable: | |
728 | \end_layout | |
729 | ||
730 | \begin_layout Standard | |
731 | ("#4u%lu", (unsigned long)var) | |
732 | \end_layout | |
733 | ||
734 | \begin_layout Standard | |
735 | trace types: | |
736 | \end_layout | |
737 | ||
738 | \begin_layout Standard | |
739 | Serialization specific formats : | |
740 | \end_layout | |
741 | ||
742 | \begin_layout Standard | |
743 | Fixed size integers | |
744 | \end_layout | |
745 | ||
746 | \begin_layout Standard | |
747 | #1u writes uint8_t | |
748 | \end_layout | |
749 | ||
750 | \begin_layout Standard | |
751 | #2u writes uint16_t | |
752 | \end_layout | |
753 | ||
754 | \begin_layout Standard | |
755 | #4u writes uint32_t | |
756 | \end_layout | |
757 | ||
758 | \begin_layout Standard | |
759 | #8u writes uint64_t | |
760 | \end_layout | |
761 | ||
762 | \begin_layout Standard | |
763 | #1d writes int8_t | |
764 | \end_layout | |
765 | ||
766 | \begin_layout Standard | |
767 | #2d writes int16_t | |
768 | \end_layout | |
769 | ||
770 | \begin_layout Standard | |
771 | #4d writes int32_t | |
772 | \end_layout | |
773 | ||
774 | \begin_layout Standard | |
775 | #8d writes int64_t | |
776 | \end_layout | |
777 | ||
778 | \begin_layout Standard | |
779 | i.e.: | |
780 | \end_layout | |
781 | ||
782 | \begin_layout Standard | |
783 | #1u%lu #2u%lu #4d%lu #8d%lu #llu%hu #d%lu | |
784 | \end_layout | |
785 | ||
786 | \begin_layout Standard | |
787 | * Attributes: | |
788 | \end_layout | |
789 | ||
790 | \begin_layout Standard | |
791 | n: (for network byte order) | |
792 | \end_layout | |
793 | ||
794 | \begin_layout Standard | |
795 | #ntracetype%ctype | |
796 | \end_layout | |
797 | ||
798 | \begin_layout Standard | |
799 | is written in the trace in network byte order. | |
800 | \end_layout | |
801 | ||
802 | \begin_layout Standard | |
803 | i.e.: #bn4u%lu, #n%lu, #b%u | |
804 | \end_layout | |
805 | ||
806 | \begin_layout Standard | |
807 | TODO (eventually) | |
808 | \end_layout | |
809 | ||
810 | \begin_layout Standard | |
811 | Variable length sequence | |
812 | \end_layout | |
813 | ||
814 | \begin_layout Standard | |
815 | #a #tracetype1 #tracetype2 %array_ptr %elem_size %num_elems | |
816 | \end_layout | |
817 | ||
818 | \begin_layout Standard | |
819 | In the trace: | |
820 | \end_layout | |
821 | ||
822 | \begin_layout Standard | |
823 | #a specifies that this is a sequence | |
824 | \end_layout | |
825 | ||
826 | \begin_layout Standard | |
827 | #tracetype1 is the type of elements in the sequence | |
828 | \end_layout | |
829 | ||
830 | \begin_layout Standard | |
831 | #tracetype2 is the type of the element count | |
832 | \end_layout | |
833 | ||
834 | \begin_layout Standard | |
835 | GCC input: | |
836 | \end_layout | |
837 | ||
838 | \begin_layout Standard | |
839 | array_ptr is a pointer to an array that contains members of size | |
840 | \end_layout | |
841 | ||
842 | \begin_layout Standard | |
843 | elem_size. | |
844 | \end_layout | |
845 | ||
846 | \begin_layout Standard | |
847 | num_elems is the number of elements in the array. | |
848 | \end_layout | |
849 | ||
850 | \begin_layout Standard | |
851 | i.e.: #a #lu #lu %p %lu %u | |
852 | \end_layout | |
853 | ||
854 | \begin_layout Standard | |
855 | Callback | |
856 | \end_layout | |
857 | ||
858 | \begin_layout Standard | |
859 | #k callback (taken from the probe data) | |
860 | \end_layout | |
861 | ||
862 | \begin_layout Standard | |
863 | The following % arguments are exepected by the callback | |
864 | \end_layout | |
865 | ||
866 | \begin_layout Standard | |
867 | i.e.: #a #lu #lu #k %p | |
868 | \end_layout | |
869 | ||
870 | \begin_layout Standard | |
871 | Note: No conversion is done from floats to integers, nor from integers to | |
872 | \end_layout | |
873 | ||
874 | \begin_layout Standard | |
875 | floats between c types and trace types. | |
876 | float conversion from double to float | |
877 | \end_layout | |
878 | ||
879 | \begin_layout Standard | |
880 | or from float to double is also not supported. | |
881 | \end_layout | |
882 | ||
a8afdd3c PMF |
883 | \end_body |
884 | \end_document |