From cd41f97c42df5747599d1c8d107d7afc3968ee32 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Wed, 17 Dec 2014 16:34:39 -0500 Subject: [PATCH] Clarify TRACEPOINT_DEFINE and multi TP Signed-off-by: Philippe Proulx --- .../building-linking/dynamic-linking.md | 21 ++++++++++++++++-- .../building-linking/static-linking.md | 22 ++++++++++++++----- .../probing-the-application-source-code.md | 9 +++++--- .../c-application/tracepoint-provider.md | 4 ++-- 4 files changed, 43 insertions(+), 13 deletions(-) diff --git a/contents/using-lttng/instrumenting/c-application/building-linking/dynamic-linking.md b/contents/using-lttng/instrumenting/c-application/building-linking/dynamic-linking.md index 1284be6..e52363b 100644 --- a/contents/using-lttng/instrumenting/c-application/building-linking/dynamic-linking.md +++ b/contents/using-lttng/instrumenting/c-application/building-linking/dynamic-linking.md @@ -19,11 +19,27 @@ The process to create the tracepoint provider shared object is pretty much the same as the static library method, except that: * since the tracepoint provider is not part of the application - anymore, `TRACEPOINT_DEFINE` _must_ be defined in one translation - unit (C source file) of the _application_; + anymore, `TRACEPOINT_DEFINE` _must_ be defined, for each tracepoint + provider, in exactly one translation unit (C source file) of the + _application_; * `TRACEPOINT_PROBE_DYNAMIC_LINKAGE` must be defined next to `TRACEPOINT_DEFINE`. +Regarding `TRACEPOINT_DEFINE` and `TRACEPOINT_PROBE_DYNAMIC_LINKAGE`, +the recommended practice is to use a separate C source file in your +application to define them, and then include the tracepoint provider +header files afterwards, e.g.: + +~~~ c +#define TRACEPOINT_DEFINE +#define TRACEPOINT_PROBE_DYNAMIC_LINKAGE + +/* include the header files of one or more tracepoint providers below */ +#include "tp1.h" +#include "tp2.h" +#include "tp3.h" +~~~ + `TRACEPOINT_PROBE_DYNAMIC_LINKAGE` makes the macros included afterwards (by including the tracepoint provider header, which itself includes LTTng-UST headers) aware that the tracepoint provider is to be loaded @@ -67,3 +83,4 @@ LTTng-UST tracing support: 
 ./app
+ diff --git a/contents/using-lttng/instrumenting/c-application/building-linking/static-linking.md b/contents/using-lttng/instrumenting/c-application/building-linking/static-linking.md index 4f53e2b..23e049a 100644 --- a/contents/using-lttng/instrumenting/c-application/building-linking/static-linking.md +++ b/contents/using-lttng/instrumenting/c-application/building-linking/static-linking.md @@ -39,10 +39,11 @@ int my_func(int a, const char* b) /* ... */ ~~~ -Again, `TRACEPOINT_CREATE_PROBES` and `TRACEPOINT_DEFINE` must be -defined in one, **and only one**, translation unit. Other C source -files of the same application may include `tp.h` to use tracepoints -with `tracepoint()`, but must not define +Again, before including a given tracepoint provider header file, +`TRACEPOINT_CREATE_PROBES` and `TRACEPOINT_DEFINE` must be defined in +one, **and only one**, translation unit. Other C source files of the +same application may include `tp.h` to use tracepoints with +the `tracepoint()` macro, but must not define `TRACEPOINT_CREATE_PROBES`/`TRACEPOINT_DEFINE` again. This translation unit may be built as an object file by making sure to @@ -63,8 +64,17 @@ separate object file by using a dedicated C source file to create probes: `TRACEPOINT_DEFINE` must be defined by a translation unit of the application. Since we're talking about static linking here, it could as -well be defined in the file above, before `#include "tp.h"`. This is -actually what [`lttng-gen-tp`](#doc-lttng-gen-tp) does. +well be defined directly in the file above, before `#include "tp.h"`: + +~~~ c +#define TRACEPOINT_CREATE_PROBES +#define TRACEPOINT_DEFINE + +#include "tp.h" +~~~ + +This is actually what [`lttng-gen-tp`](#doc-lttng-gen-tp) does, and is +the recommended practice. Build the tracepoint provider: diff --git a/contents/using-lttng/instrumenting/c-application/probing-the-application-source-code.md b/contents/using-lttng/instrumenting/c-application/probing-the-application-source-code.md index 89cf267..95830a3 100644 --- a/contents/using-lttng/instrumenting/c-application/probing-the-application-source-code.md +++ b/contents/using-lttng/instrumenting/c-application/probing-the-application-source-code.md @@ -55,9 +55,12 @@ int main(int argc, char* argv[]) } ~~~ -`TRACEPOINT_DEFINE` must be defined into exactly one translation unit (C -source file) of the user application, before including the tracepoint provider -header file. `TRACEPOINT_DEFINE` is discussed further in +For each tracepoint provider, `TRACEPOINT_DEFINE` must be defined into +exactly one translation unit (C source file) of the user application, +before including the tracepoint provider header file. In other words, +for a given tracepoint provider, you cannot define `TRACEPOINT_DEFINE`, +and then include its header file in two separate C source files of +the same application. `TRACEPOINT_DEFINE` is discussed further in [Building/linking tracepoint providers and the user application](#doc-building-tracepoint-providers-and-user-application). As another example, remember this definition we wrote in a previous diff --git a/contents/using-lttng/instrumenting/c-application/tracepoint-provider.md b/contents/using-lttng/instrumenting/c-application/tracepoint-provider.md index 3a68abe..7a45591 100644 --- a/contents/using-lttng/instrumenting/c-application/tracepoint-provider.md +++ b/contents/using-lttng/instrumenting/c-application/tracepoint-provider.md @@ -129,8 +129,8 @@ Include guard follows: #define _TP_H ~~~ -Add this precompiler conditionals to ensure the tracepoint event generation -can include this file more than once. +Add these precompiler conditionals to ensure the tracepoint event +generation can include this file more than once. The `TRACEPOINT_EVENT()` macro is defined in a LTTng-UST header file which must be included: -- 2.34.1