\end_layout
\begin_layout Itemize
-Early process tracing (from the beginning of the main() function
+Early process tracing (from the beginning of the main() function)
\end_layout
\begin_layout Itemize
\end_layout
\begin_layout Itemize
-Support of dynamic instrumentation (being implemented in
+Support for dynamic instrumentation
+\end_layout
+
+\begin_layout Itemize
+Per thread or per CPU buffers
\end_layout
\begin_layout Standard
Performance
\end_layout
+\begin_layout Section
+Installation
+\end_layout
+
+\begin_layout Subsection
+Obtain the code
+\end_layout
+
+\begin_layout Standard
+To compile UST, you need:
+\end_layout
+
+\begin_layout Itemize
+the UST code
+\end_layout
+
+\begin_layout Itemize
+libkcompat
+\end_layout
+
+\begin_layout Itemize
+liburcu-pmf
+\end_layout
+
+\begin_layout Subsection
+Configure libkcompat
+\end_layout
+
+\begin_layout Standard
+Edit kcompat.h and uncomment the architecture of the target system.
+\end_layout
+
+\begin_layout Subsection
+Configure libust
+\end_layout
+
+\begin_layout Standard
+If the code was obtained through git, first generate a Makefile by running
+ autogen.sh.
+\end_layout
+
+\begin_layout Standard
+Then, run ./configure, specifying the directories of liburcu and libkcompat.
+ Example:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+./configure --with-urcu=/home/pmf/liburcu-pmf --with-kcompat=/home/pmf/libkcompat
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Build liburcu
+\end_layout
+
+\begin_layout Standard
+Go to the liburcu directory and run:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+make
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Build ust
+\end_layout
+
+\begin_layout Standard
+Go to the ust directory and run:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+make
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
\begin_layout Section
Instrumenting an Application
\end_layout
\begin_layout Standard
There are no limitations on the type of code that may be instrumented.
Multi-threaded programs may be instrumented without problem.
- Signal handler may be instrumented as well.
+ Signal handlers may be instrumented as well.
\end_layout
\begin_layout Standard
\begin_layout Plain Layout
-void function()
+int main(int argc, char **argv)
\end_layout
\begin_layout Plain Layout
\begin_layout Plain Layout
+\end_layout
+
+\begin_layout Plain Layout
+
+ return 0;
+\end_layout
+
+\begin_layout Plain Layout
+
}
\end_layout
Compiling the Application
\end_layout
+\begin_layout Standard
+See the
+\begin_inset Quotes eld
+\end_inset
+
+hello
+\begin_inset Quotes erd
+\end_inset
+
+ directory for an example application and makefile.
+\end_layout
+
+\begin_layout Itemize
+The compiler must have access to the include path for the libust headers.
+\end_layout
+
+\begin_layout Itemize
+The application should be statically or dynamically linked to libust.
+\end_layout
+
\begin_layout Section
Recording a Trace
\end_layout
+\begin_layout Standard
+These preliminary steps need to be done before recording a trace.
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+Create the directory for the communication sockets.
+ Eventually this should be somewhere in /var.
+\end_layout
+
+\begin_layout Plain Layout
+
+$ mkdir /tmp/socks
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+Create the directory where ustd will write the trace.
+ This will become configurable.
+\end_layout
+
+\begin_layout Plain Layout
+
+$ mkdir /tmp/trace
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+Start the daemon
+\end_layout
+
+\begin_layout Plain Layout
+
+$ ustd
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
\begin_layout Subsection
Basic Recording
\end_layout
+\begin_layout Standard
+Tracing on a running program is controlled with the ust helper program.
+ Ust can start the tracing, stop the tracing, enable markers, disable markers
+ and list the markers.
+ Another program, ustd, is a daemon that collects the trace events and write
+ them to a file.
+\end_layout
+
+\begin_layout Standard
+In order to record a trace, the daemon must first be started with the following
+ command.
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+ustd
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Markers can be listed with the following command (for PID 1234).
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+ust --list-markers 1234
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+A marker can be enabled with the following command (for PID 1234).
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+ust --enable-marker ust/mymark 1234
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Then, the trace can be started.
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+ust --start-trace 1234
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Eventually it can be stopped and destroyed.
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+ust --stop-trace 1234
+\end_layout
+
+\begin_layout Plain Layout
+
+ust --destroy-trace 1234
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
\begin_layout Subsection
Early Tracing
\end_layout
\begin_layout Plain Layout
-$ UST_TRACE=1 UST_AUTOPROBE=1 ./prog
+# In another terminal, start the daemon.
+\end_layout
+
+\begin_layout Plain Layout
+
+ustd
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+# Start
+\begin_inset Quotes eld
+\end_inset
+
+prog
+\begin_inset Quotes erd
+\end_inset
+
+ with early tracing.
+\end_layout
+
+\begin_layout Plain Layout
+
+UST_TRACE=1 UST_AUTOPROBE=1 ./prog
\end_layout
\end_inset
point.
\end_layout
+\begin_layout Standard
+Such an example can be found in the libmallocwrap directory of the ust code
+ package.
+\end_layout
+
\begin_layout Subsection
Tracing Programs Without Linking them to the Tracing Library
\end_layout
or from float to double is also not supported.
\end_layout
+\begin_layout Section
+Environment variables
+\end_layout
+
+\begin_layout Standard
+The following environment variables change the behavior of libust.
+\end_layout
+
+\begin_layout Description
+UST_TRACE When defined, automatically enables tracing.
+\end_layout
+
+\begin_layout Description
+UST_AUTOPROBE When value is 1, enable all markers automatically.
+ When value is a regular expression, enable all markers whose name matches
+ the regular expression.
+\end_layout
+
+\begin_layout Description
+UST_DAEMON_SOCKET If not set, the default location of the daemon socket
+ is used.
+ If set, the value is used as path to the ustd socket.
+\end_layout
+
\end_body
\end_document
projects / ust.git / blobdiff