Clarify TRACEPOINT_DEFINE and multi TP

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

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 1284be60bca02dd7fd80d7bf330ff02c1d05b6d4..e52363bc78715ea0b5bf02f2f03e14ab6193d013 100644 (file)
--- 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:
 <pre class="term">
 ./app
 </pre>
+

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 4f53e2b656132e1ff690f5630c90881e98087244..23e049ad0c3b9b42e9eb6bc1b64c37cdf774557a 100644 (file)
--- 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 89cf26781453d0b5f6bda97fc6052affa45739ef..95830a309f0a5d215393f75441eb569b1d9de611 100644 (file)
--- 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 3a68abe5bf91936c8f35dc30b6c5415a0752b87d..7a4559177d9a9a92af135779afeeb70859e145cc 100644 (file)
--- 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: