clock plugin example: use shift and mul

[lttng-ust.git] / doc / man / lttng-ust.3

diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3
index 117fe985ffa6f391b288705e12d2862c0b0a62fc..7dae8b538d8d4161e57f54bee9e5a872815e6f02 100644 (file)
--- a/doc/man/lttng-ust.3
+++ b/doc/man/lttng-ust.3
@@ -92,11 +92,11 @@ TRACEPOINT_EVENT(
        sample_component,
 
        /*
-        * tracepoint name, same format as sample provider. Does not
-        * need to be declared before. in this case the name is
-        * "message"
+        * tracepoint name, characters permitted follow the same
+        * constraints as the provider name. The name of this example
+        * event is "sample_event".
         */
-       message,
+       sample_event,
 
        /*
         * TP_ARGS macro contains the arguments passed for the tracepoint
@@ -265,7 +265,7 @@ debug information.
    debug information with line-level scope (TRACEPOINT_EVENT default)
 
    TRACE_DEBUG           14
-   debug-level message (trace_printf default)
+   debug-level message
 
 See lttng(1) for information on how to use LTTng-UST loglevels.
 
@@ -290,6 +290,33 @@ Even though LTTng-UST supports tracepoint() call site duplicates having
 the same provider and event name, it is recommended to use a
 provider event name pair only once within the source code to help
 map events back to their call sites when analyzing the trace.
+
+Sometimes arguments to the probe are expensive to compute (e.g.
+take call stack). To avoid the computation when the tracepoint is
+disabled one can use more 'low level' tracepoint_enabled() and
+do_tracepoint() macros as following:
+
+       if (tracepoint_enabled(ust_tests_hello, tptest)) {
+               /* prepare arguments */
+               do_tracepoint(ust_tests_hello, tptest, i, netint, values,
+                       text, strlen(text), dbl, flt);
+       }
+
+Here do_tracepoint() doesn't contain check if the tracepoint is enabled.
+Using tracepoint() in such scenario is dangerous since it also contains
+enabled check and thus race condition is possible in the following code
+if the tracepoint has been enabled after check in tracepoint_enabled()
+but before tracepoint():
+
+       if (tracepoint_enabled(provider, name)) { /* tracepoint is disabled */
+               prepare(args);
+       }
+       /* tracepoint is enabled by 'lttng' tool */
+       tracepoint(provider, name, args); /* args wasn't prepared properly */
+
+Note also that neither tracepoint_enabled() nor do_tracepoint() have
+STAP_PROBEV() call so if you need it you should emit this call yourself.
+
 .fi
 
 .SH "BUILDING/LINKING THE TRACEPOINT PROVIDER"
@@ -299,17 +326,13 @@ There are 2 ways to compile the Tracepoint Provider with the
 application: either statically or dynamically. Please follow
 carefully:
 
-  1.1) Compile the Tracepoint provider with the application, either
-       directly or through a static library (.a):
-    - Into exactly one object of your application: define
+  1) Compile the Tracepoint Provider with the application, either
+     directly or through a static library (.a):
+    - Into exactly one object of your application, define
       "TRACEPOINT_DEFINE" and include the tracepoint provider.
     - Use "\-I." for the compilation unit containing the tracepoint
-      provider include (e.g. tp.c).
-    - Link application with "\-ldl".
-    - If building the provider directly into the application,
-      link the application with "\-llttng-ust".
-    - If building a static library for the provider, link the static
-      library with "\-llttng-ust".
+      provider include (e.g., tp.c).
+    - Link the application with "\-llttng-ust" and "\-ldl".
     - Include the tracepoint provider header into all C files using
       the provider.
     - Examples:
@@ -424,7 +447,7 @@ line number lookup are traced by LTTng.
 
 .PP
 .IP "LTTNG_UST_DEBUG"
-Activate liblttng-ust debug output.
+Activate liblttng-ust debug and error output.
 .PP
 .IP "LTTNG_UST_REGISTER_TIMEOUT"
 The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to