@node Top
@top LTTng Userspace Tracer
-This manual is for UST 0.1.
+This manual is for UST 0.5.
@end ifnottex
@menu
* Recording a trace::
* Viewing traces::
* Performance::
+* Resource Usage::
+* List of environment variables detected by libust::
+* GDB integration::
@c * Copying:: Your rights and freedoms.
@end menu
@node Supported platforms
@section Supported platforms
-UST can currently trace applications running on Linux, on the x86-32 and x86-64 architectures.
+UST can currently trace applications running on Linux, on the x86-32, x86-64
+and PowerPC 32 architectures.
@node Installation
@chapter Installation
This contains the tracing library, the ustd daemon, trace control tools
and other helper tools.
-Repository: http://git.dorsal.polymtl.ca
-
-@item
-libkcompat
-
-This is a library that contains a userspace port of some kernel APIs.
-
-Repository: http://git.dorsal.polymtl.ca
+Repository: @url{http://git.dorsal.polymtl.ca}
@item
liburcu
Available in Debian as package liburcu-dev.
-Home page: http://lttng.org/?q=node/18
+Home page: @url{http://lttng.org/urcu}
@item
LTTV
LTTV is a graphical (and text) viewer for LTTng traces.
-Home page: http://lttng.org
+Home page: @url{http://lttng.org}
@end itemize
-Libkcompat and liburcu should be installed first. UST may then be compiled
-and installed. LTTV has no dependency on the other packages; it may therefore
-be installed on a system which does not have UST installed.
+Liburcu should be installed first. UST may then be compiled and installed. LTTV
+has no dependency on the other packages; it may therefore be installed on a
+system which does not have UST installed.
Refer to the README in each of these packages for installation instructions.
format strings directly in the code and to have format strings appear more than
once if a given marker is reused.
-@quotation Note Although this example uses @emph{mychannel} as the channel, the
+@quotation Note
+Although this example uses @emph{mychannel} as the channel, the
only channel name currently supported with early tracing is @strong{ust}. The
@command{usttrace} tool always uses the early tracing mode. When using manual
-mode without early tracing, any channel name may be used. @end quotation
+mode without early tracing, any channel name may be used.
+@end quotation
A function instrumented with a tracepoint looks like this:
When using @command{usttrace}, the early tracing is always active, which means
that the tracing is guaranteed to be started by the time the process enters its
-main() function.
+@code{main()} function.
Several @command{usttrace}'s may be run simultaneously without risk of
conflict. This facilitates the use of the tracer by idependent users on a
@end verbatim
@end example
+For more information about the manual mode, see the ustctl(1) man page.
+
@node Using early tracing
@section Using early tracing
use the timestamp counter for both. The TSC can however only be used on architectures
where it is synchronized across cores.
+@node Resource Usage
+@chapter Resource Usage
+
+The purpose of this section is to give an overview of the resource usage of libust. For
+a developer, knowing this can be important: because libust is linked with applications, it
+needs to share some resources with it. Some applications may make some assumptions that are in
+conflict with libust's usage of resources.
+
+In practice however, libust is designed to be transparent and is compatible
+with the vast majority of applications. This means no changes are required in
+the application (or library) being linked to libust.
+
+Libust is initialized by a constructor, which by definition runs before the
+@code{main()} function of the application starts. This constructor creates a
+thread called the @emph{listener thread}. The listener thread initializes a
+named socket and waits for connections for ustd or ustctl.
+
+Libust-specific code may:
+@itemize @bullet
+@item use @code{malloc()} and @code{free()}
+@item map shared memory segment in the process adress space
+@item intercept some library calls, specifically @code{fork()} and @code{clone()}
+@item do interprocess communication with the daemon or ustctl
+@item create and open named sockets
+
+@end itemize
+
+It will not:
+@itemize @bullet
+@item handle any signal (all signals are blocked in the listener thread)
+@item change any process-wide setting that could confuse the application
+@end itemize
+
+@node List of environment variables detected by libust
+@appendix List of environment variables detected by libust
+
+The behavior of tracing can be influenced by setting special environment
+variables in the environment of the traced application. This section
+describes these variables.
+
+@itemize @bullet
+
+@item
+@env{UST_TRACE}
+
+If set to 1, start tracing as soon as the program starts. Tracing is
+guaranteed to be started by the time the @code{main()} function starts.
+
+@item
+@env{UST_AUTOPROBE}
+
+If set to @code{1}, enable all markers by the time the @code{main()} function starts.
+
+@item
+@env{UST_AUTOCOLLECT}
+
+If set to @code{0}, disable notification of daemon on trace start. Useful for
+performance tests.
+
+@item
+@env{UST_OVERWRITE}
+
+If set to @code{1}, enable overwriting of buffers on overrun.
+
+@item
+@env{UST_SUBBUF_NUM}
+
+If set, defines the default number of subbuffers per buffer.
+
+@item
+@env{UST_SUBBUF_SIZE}
+
+If set, defines the default size of subbuffers, in bytes.
+
+@end itemize
+
+@node GDB integration
+@appendix GDB integration
+
+GDB, the GNU Debugger, can use UST markers as GDB tracepoints (note GDB has its
+own concept of tracepoint). This feature is called GDB Static Tracepoints. When
+a GDB tracepoint is hit, GDB collects the marker arguments, as well as the
+state of the registers.
+
+In UST, support for GDB integration is not compiled in by default because of
+the cost of saving registers when a marker is hit. To enable it, run the
+@command{./configure} script with the @code{-DCONFIG_UST_GDB_INTEGRATION} flag
+in the @env{CFLAGS} environment variable. For example:
+
+@example
+@verbatim
+
+CFLAGS=-DCONFIG_UST_GDB_INTEGRATION ./configure
+
+@end verbatim
+@end example
+
+As of this writing, GDB Static Tracepoints have been submitted
+(@url{http://sourceware.org/ml/gdb-patches/2010-06/msg00592.html}) to the GDB
+mailing list.
+
+GDB integration is currently only supported on x86-32 and x86-64.
+
@bye
projects / ust.git / blobdiff