Commit | Line | Data |
---|---|---|
4ddbd0b7 PP |
1 | lttng-gen-tp(1) |
2 | =============== | |
3 | :object-type: program | |
4 | ||
5 | ||
6 | NAME | |
7 | ---- | |
8 | lttng-gen-tp - Generate LTTng-UST tracepoint provider code | |
9 | ||
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
13 | [verse] | |
14 | *lttng-gen-tp* [option:--verbose] [option:--output='FILE'.c] | |
15 | [option:--output='FILE'.h] [option:--output='FILE'.o] 'TEMPLATE' | |
16 | ||
17 | ||
18 | DESCRIPTION | |
19 | ----------- | |
20 | The `lttng-gen-tp` tool simplifies the generation of LTTng-UST | |
21 | tracepoint provider files. It takes a simple template file, 'TEMPLATE', | |
22 | and generates the necessary C code to use the defined tracepoints in | |
23 | your application. See the <<template-file-format,Template file format>> | |
24 | section below for more information about the format of 'TEMPLATE'. | |
25 | ||
26 | Currently, `lttng-gen-tp` can generate the `.h`, `.c`, and `.o` files | |
27 | associated with your tracepoint provider. The generated `.h` file can be | |
28 | included directly in your application. You can let `lttng-gen-tp` | |
29 | generate the `.o` file or compile the `.c` file yourself. See | |
30 | man:lttng-ust(3) for more information about compiling LTTng-UST | |
31 | tracepoint providers. | |
32 | ||
33 | By default, `lttng-gen-tp` generates the `.h`, `.c`, and `.o` files, | |
34 | their basename being the basename of 'TEMPLATE'. You can generate one or | |
35 | more specific file types with the option:--output option, repeated if | |
36 | needed. | |
37 | ||
38 | ||
39 | [[template-file-format]] | |
40 | Template file format | |
41 | ~~~~~~~~~~~~~~~~~~~~ | |
42 | The template file, which usually has the `.tp` extension, contains a | |
43 | list of `TRACEPOINT_EVENT()` definitions and other optional definition | |
44 | entries, like `TRACEPOINT_LOGLEVEL()`. See man:lttng-ust(3) for | |
45 | the complete list of available definitions. | |
46 | ||
47 | The `TRACEPOINT_EVENT()` definitions are written as you would write them | |
48 | in an LTTng-UST template provider header file. C comments are supported | |
49 | (`/* */` and `//`), as well as lines starting with `#`. | |
50 | ||
51 | NOTE: The provider name (the first argument of `TRACEPOINT_EVENT()`) | |
52 | must be the same in all the `TRACEPOINT_EVENT()` macros of 'TEMPLATE'. | |
53 | ||
54 | Here's an example: | |
55 | ||
56 | --------------------------------------- | |
57 | TRACEPOINT_EVENT( | |
58 | // Tracepoint provider name | |
59 | my_provider, | |
60 | ||
61 | // Tracepoint/event name | |
62 | my_event, | |
63 | ||
64 | // Tracepoint arguments (input) | |
65 | TP_ARGS(char *, text), | |
66 | ||
67 | // Tracepoint/event fields (output) | |
68 | TP_FIELDS( | |
69 | ctf_string(message, text) | |
70 | ) | |
71 | ) | |
72 | --------------------------------------- | |
73 | ||
74 | ||
75 | OPTIONS | |
76 | ------- | |
77 | option:-o, option:--output='FILE':: | |
78 | Do not generate default files: generate 'FILE'. | |
79 | + | |
80 | The extension of 'FILE' determines what is generated, amongst `.h`, | |
81 | `.c`, and `.o`. This option can be used more than one time to generate | |
82 | different file types. | |
83 | ||
84 | option:-v, option:--verbose:: | |
85 | Increase verbosity. | |
86 | ||
87 | option:-h, option:--help:: | |
88 | Show command help. | |
89 | ||
90 | ||
91 | ENVIRONMENT VARIABLES | |
92 | --------------------- | |
93 | `CC`:: | |
94 | C compiler to use. Default: `cc`, then `gcc` if `cc` is not found. | |
95 | This option is only relevant when generating the `.o` file. | |
96 | ||
97 | `CFLAGS`:: | |
98 | Flags and options passed directly to the compiler (`$CC`). | |
99 | This option is only relevant when generating the `.o` file. | |
100 | ||
101 | ||
102 | EXIT STATUS | |
103 | ----------- | |
104 | *0*:: | |
105 | Success | |
106 | ||
107 | *Non-zero*:: | |
108 | Error | |
109 | ||
110 | ||
111 | include::common-footer.txt[] | |
112 | ||
113 | ||
114 | COPYRIGHTS | |
115 | ---------- | |
116 | `lttng-gen-tp` is part of the LTTng-UST project. | |
117 | ||
118 | `lttng-gen-tp` is distributed under the | |
119 | http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html[GNU General | |
120 | Public License, version 2]. See the | |
f596de62 | 121 | https://github.com/lttng/lttng-ust/blob/v{lttng_version}/COPYING[`COPYING`] file |
4ddbd0b7 PP |
122 | for more details. |
123 | ||
124 | ||
125 | AUTHOR | |
126 | ------ | |
127 | `lttng-gen-tp` was originally written by | |
128 | mailto:yannick.brosseau@gmail.com[Yannick Brosseau]. It is currently | |
129 | maintained by mailto:mathieu.desnoyers@efficios.com[Mathieu Desnoyers]. | |
130 | ||
131 | ||
132 | SEE ALSO | |
133 | -------- | |
134 | man:lttng-ust(3) |