[lttng-dev] [PATCH] baddr: Added ust_baddr & ust_baddr_statedump docu

[Paul Woegerer]

Signed-off-by: Paul Woegerer <paul_woegerer at mentor.com>
---
 doc/Makefile.am        |  1 +
 doc/man/lttng-ust-dl.3 | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 doc/man/lttng-ust.3    | 34 +++++++++++++++++++++++++++++++++-
 3 files changed, 81 insertions(+), 1 deletion(-)
 create mode 100644 doc/man/lttng-ust-dl.3

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 4349713..72dcde2 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -2,6 +2,7 @@ SUBDIRS = . examples
 
 dist_man_MANS = man/lttng-gen-tp.1 \
 	man/lttng-ust.3 \
+	man/lttng-ust-dl.3 \
 	man/lttng-ust-cyg-profile.3
 
 dist_doc_DATA = java-util-logging.txt
diff --git a/doc/man/lttng-ust-dl.3 b/doc/man/lttng-ust-dl.3
new file mode 100644
index 0000000..ff46f6b
--- /dev/null
+++ b/doc/man/lttng-ust-dl.3
@@ -0,0 +1,47 @@
+.TH "LTTNG-UST-DL" "3" "December 19, 2013" "" ""
+
+.SH "NAME"
+lttng-ust-dl \(em LTTng UST 2.x Dynamic Linker Tracing
+
+.SH "SYNOPSIS"
+Launch your application with:
+.TP
+\fBLD_PRELOAD=liblttng-ust-dl.so\fP appname
+.PP
+This LD_PRELOAD library causes all calls to dlopen and dlclose in the
+application to be traced with LTTng. The following two events need to be
+enabled: ust_baddr:push and ust_baddr:pop.
+
+.SH "DESCRIPTION"
+The events have the following detailed definitions:
+.PP
+.IP "ust_baddr:push"
+This event is used to trace dlopen calls. The base address (where the dynamic
+linker has placed the shared object) is recorded in the baddr-field. The path
+to the shared object gets recorded in the sopath-field (as string). The file
+size of the loaded object (in bytes) is recorded to the size-field and its time
+of last modification (in seconds since Epoch) is recorded in the mtime-field.
+.IP "ust_baddr:pop"
+This event is used to trace dlclose calls. The base address of the shared
+object that got closed is recorded in the baddr-field.
+.PP
+
+.SH "SEE ALSO"
+lttng-ust(3), dlopen(3), lttng(1)
+.SH "BUGS"
+If you encounter any issues or usability problem, please report it on
+our mailing list <lttng-dev at lists.lttng.org> to help improve this
+project.
+.SH "CREDITS"
+liblttng-ust is distributed under the GNU Lesser General Public License
+version 2.1. The headers are distributed under the MIT license.
+
+See http://lttng.org for more information on the LTTng project.
+
+Mailing list for support and development: <lttng-dev at lists.lttng.org>.
+
+You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
+.SH "AUTHORS"
+liblttng-ust was originally written by Mathieu Desnoyers, with additional
+contributions from various other people. It is currently maintained by
+Mathieu Desnoyers <mathieu.desnoyers at efficios.com>.
diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3
index 7624e88..55de9fd 100644
--- a/doc/man/lttng-ust.3
+++ b/doc/man/lttng-ust.3
@@ -347,6 +347,13 @@ process namespace.
 .PP
 
 .PP
+.IP "ip"
+Instruction pointer: Enables recording of the exact location where a tracepoint
+was emitted. Can be used to reverse-lookup the source location that caused the
+event to be emitted.
+.PP
+
+.PP
 .IP "procname"
 Thread name, as set by exec() or prctl(). It is recommended that
 programs set their thread name with prctl() before hitting the first
@@ -359,6 +366,28 @@ Pthread identifier. Can be used on architectures where pthread_t maps
 nicely to an unsigned long type.
 .PP
 
+.SH "BASE ADDRESS STATEDUMP"
+
+.PP
+If an application that uses liblttng-ust.so becomes part of a session,
+information about its currently loaded shared objects will be traced to the
+session at session-enable time. To record this information, the following event
+needs to be enabled:
+.PP
+.IP "ust_baddr_statedump:soinfo"
+This event is used to trace a currently loaded shared object. The base address
+(where the dynamic linker has placed the shared object) is recorded in the
+baddr-field. The path to the shared object gets recorded in the sopath-field
+(as string). The file size of the loaded object (in bytes) is recorded to the
+size-field and its time of last modification (in seconds since Epoch) is
+recorded in the mtime-field.
+.PP
+If the event above is enabled, a series of ust_baddr_statedump:soinfo events is
+recorded at session-enable time, that represents the state of currently loaded
+shared objects (of the traced application). If this information gets combined
+with the lttng-ust-dl(3) instrumentation, all aspects of dynamic loading that
+are relevant for symbol and linenumber-lookup are traced by LTTng.
+.PP
 .SH "ENVIRONMENT VARIABLES"
 
 .PP
@@ -375,12 +404,15 @@ specified in milliseconds. The value 0 means "don't wait". The value
 recommended for applications with time constraints on the process
 startup time.
 .PP
+.IP "LTTNG_UST_WITHOUT_BADDR_STATEDUMP"
+Prevent liblttng-ust to perform a base-address statedump on session-enable.
+.PP
 
 .SH "SEE ALSO"
 
 .PP
 lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-ust-cyg-profile(3),
-lttng-sessiond(8)
+lttng-ust-dl(3), lttng-sessiond(8)
 .PP
 
 .SH "COMPATIBILITY"
-- 
1.8.5