From: compudj <compudj@04897980-b3bd-0310-b5e0-8ef037075253>
Date: Tue, 20 Jan 2009 16:40:56 +0000 (+0000)
Subject: update
X-Git-Tag: v0.12.20~268
X-Git-Url: http://git.lttng.org./?a=commitdiff_plain;h=d4c85b6e5cb22061ee1f81efde2587db7c9152f9;hp=a41efeab7d736c72e949854642f3f481d7ecdb79;p=lttv.git

update

git-svn-id: http://ltt.polymtl.ca/svn@3221 04897980-b3bd-0310-b5e0-8ef037075253
---

diff --git a/trunk/lttv/doc/developer/ust.txt b/trunk/lttv/doc/developer/ust.txt
new file mode 100644
index 00000000..8812dee4
--- /dev/null
+++ b/trunk/lttv/doc/developer/ust.txt
@@ -0,0 +1,32 @@
+LTTng User-space Tracing Design
+
+A user-space application may contain static instrumentation, and be linked with
+an associated runtime library, in order to produce an execution trace. User
+space Tracepoints and Markers, analogous to Kernel Tracepoints and Markers,
+define program locations and arguments provided. Probes may then be connected to
+each Tracepoint and Marker before they are activated. The probes will typically
+call LTTng user-space event writing functions.
+
+When the instrumented application starts, a pipe is opened to allow external
+tracing control, asynchronous notification is requested when commands arrive in
+the pipe, and a signal handler is installed for SIGIO. Every time a SIGIO signal
+is received, the runtime library checks for commands received on the external
+tracing control pipe. The recognized commands are:
+
+- list the available Markers and Tracepoints;
+- dynamically load a library (presumably containing probes to connect);
+- connect a probe to a Tracepoint or Marker;
+- activate a Tracepoint or Marker;
+- initialize the tracing buffers;
+- flush the tracing buffers;
+- finalize the tracing buffers;
+
+The application may also spontaneously provide information to the pipe:
+
+- a buffer is full;
+- new tracepoints or markers are appearing or disappearing, because modules are
+  dynamically loaded or unloaded;
+
+In addition, the tracing control application should be notified when the
+application exits (to save the content of buffers if the application is
+crashing). Such notification may be obtained through utrace.