| 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 |
| 121 | https://github.com/lttng/lttng-ust/blob/v{lttng_version}/COPYING[`COPYING`] file |
| 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) |