--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/2002/REC-xhtml1-20020801/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+
+<head>
+ <title>The LTTng trace format</title>
+</head>
+
+<body>
+
+<h1>The LTTng trace format</h1>
+
+<p>
+<em>Last update: 2008/06/02</em>
+</p>
+
+<p>
+This document describes the LTTng trace format. It should be useful mainly to
+developers who code the LTTng tracer or the traceread LTTV library, as this
+library offers all the necessary abstractions on top of the raw trace data.
+</p>
+
+<p>
+A trace is contained in a directory tree. To send a trace remotely, the
+directory tree may be tar-gzipped. The trace <tt>foo</tt>, placed in the home
+directory of user john, /home/john, would have the following contents:
+</p>
+
+<pre><tt>
+$ cd /home/john
+$ tree foo
+foo/
+|-- control
+| |-- facilities_0
+| |-- facilities_1
+| |-- facilities_...
+| |-- interrupts_0
+| |-- interrupts_1
+| |-- interrupts_...
+| |-- modules_0
+| |-- modules_1
+| |-- modules_...
+| |-- network_0
+| |-- network_1
+| |-- network_...
+| |-- processes_0
+| |-- processes_1
+| `-- processes_...
+|-- cpu_0
+|-- cpu_1
+`-- cpu_...
+
+</tt></pre>
+
+<p>
+The root directory contains a tracefile for each cpu, numbered from 0,
+in .trace format. A uniprocessor thus only contains the file cpu_0.
+A multi-processor with some unused (possibly hotplug) CPU slots may have some
+unused CPU numbers. For instance an 8 way SMP board with 6 CPUs randomly
+installed may produce tracefiles named 0, 1, 2, 4, 6, 7.
+</p>
+
+<p>
+The files in the control directory also follow the .trace format and are
+also per cpu. The "facilities" files only contain "core" marker_id,
+marker_format and time_heartbeat events. The first two are used to describe the
+events that are in the trace. The other control files contain the initial
+system state and various subsequent important events, for example process
+creations and exit. The interest of placing such subsequent events in control
+trace files instead of (or in addition to) in the per cpu trace files is that
+they may be accessed more quickly/conveniently and that they may be kept even
+when the per cpu files are overwritten in "flight recorder mode".
+</p>
+
+<h2>Trace format</h2>
+
+<p>
+Each tracefile is divided into equal size blocks with a header at the beginning
+of the block. Events are packed sequentially in the block starting right after
+the block header.
+</p>
+
+<p>
+Each block consists of :
+</p>
+
+<pre><tt>
+block start/end header
+trace header
+event 1 header
+event 1 variable length data
+event 2 header
+event 2 variable length data
+....
+padding
+</tt></pre>
+
+<h3>The block start/end header</h3>
+
+<pre><tt>
+begin
+ * the beginning of buffer information
+ uint64 cycle_count
+ * TSC at the beginning of the buffer
+ uint64 freq
+ * frequency of the CPUs at the beginning of the buffer.
+end
+ * the end of buffer information
+ uint64 cycle_count
+ * TSC at the end of the buffer
+ uint64 freq
+ * frequency of the CPUs at the end of the buffer.
+uint32 lost_size
+ * number of bytes of padding at the end of the buffer.
+uint32 buf_size
+ * size of the sub-buffer.
+</tt></pre>
+
+
+
+<h3>The trace header</h3>
+
+<pre><tt>
+uint32 magic_number
+ * 0x00D6B7ED, used to check the trace byte order vs host byte order.
+uint32 arch_type
+ * Architecture type of the traced machine.
+uint32 arch_variant
+ * Architecture variant of the traced machine. May be unused on some arch.
+uint32 float_word_order
+ * Byte order of floats and doubles, sometimes different from integer byte
+ order. Useful only for user space traces.
+uint8 arch_size
+ * Size (in bytes) of the void * on the traced machine.
+uint8 major_version
+ * major version of the trace.
+uint8 minor_version
+ * minor version of the trace.
+uint8 flight_recorder
+ * Is flight recorder mode activated ? If yes, data might be missing
+ (overwritten) in the trace.
+uint8 has_heartbeat
+ * Does this trace have heartbeat timer event activated ?
+ Yes (1) -> Event header has 32 bits TSC
+ No (0) -> Event header has 64 bits TSC
+uint8 alignment
+ * Are event headers in this trace aligned ?
+ Yes -> the value indicates the alignment
+ No (0) -> data is packed.
+uint8 tsc_lsb_truncate
+ * Used for compact channels
+uint8 tscbits
+ * Used for compact channels
+uint8 compact_data_shift
+ * Used for compact channels
+uint32 freq_scale
+ event time is always calculated from :
+ trace_start_time + ((event_tsc - trace_start_tsc) * (freq / freq_scale))
+uint64 start_freq
+ * CPUs clock frequency at the beginnig of the trace.
+uint64 start_tsc
+ * TSC at the beginning of the trace.
+uint64 start_monotonic
+ * monotonically increasing time at the beginning of the trace.
+ (currently not supported)
+start_time
+ * Real time at the beginning of the trace (as given by date, adjusted by NTP)
+ This is the only time reference with the real world : the rest of the trace
+ has monotonically increasing time from this point (with TSC difference and
+ clock frequency).
+ uint32 seconds
+ uint32 nanoseconds
+</tt></pre>
+
+
+<h3>Event header</h3>
+
+<p>
+Event headers differ according to the following conditions : does the
+traced system have a heartbeat timer? Is tracing alignment activated?
+</p>
+
+<p>
+Event header :
+</p>
+<pre><tt>
+{ uint32 timestamp
+ or
+ uint64 timestamp }
+ * if has_heartbeat : 32 LSB of the cycle counter at the event record time.
+ * else : 64 bits complete cycle counter.
+uint8 facility_id
+ * Numerical ID of the facility corresponding to the event. See the facility
+ tracefile to know which facility ID matches which facility name and
+ description.
+uint8 event_id
+ * Numerical ID of the event inside the facility.
+uint16 event_size
+ * Size of the variable length data that follows this header.
+</tt></pre>
+
+<p>
+Event header alignment
+</p>
+
+<p>
+If trace alignment is activated (<tt>alignment</tt>), the event header is
+aligned. In addition, padding is automatically added after the event header so
+the variable length data is automatically aligned on the architecture size.
+</p>
+
+<!--
+<h2>System description</h2>
+
+<p>
+The system type description, in system.xml, looks like:
+</p>
+
+<pre><tt>
+<system
+ node_name="vaucluse"
+ domainname="polymtl.ca"
+ cpu=4
+ arch_size="ILP32"
+ endian="little"
+ kernel_name="Linux"
+ kernel_release="2.4.18-686-smp"
+ kernel_version="#1 SMP Sun Apr 14 12:07:19 EST 2002"
+ machine="i686"
+ processor="unknown"
+ hardware_platform="unknown"
+ operating_system="Linux"
+ ltt_major_version="2"
+ ltt_minor_version="0"
+ ltt_block_size="100000"
+>
+Some comments about the system
+</system>
+</tt></pre>
+
+<p>
+The system attributes kernel_name, node_name, kernel_release,
+ kernel_version, machine, processor, hardware_platform and operating_system
+come from the uname(1) program. The domainname attribute is obtained from
+the "hostname --domain" command. The arch_size attribute is one of
+LP32, ILP32, LP64 or ILP64 and specifies the length in bits of integers (I),
+long (L) and pointers (P). The endian attribute is "little" or "big".
+While the arch_size and endian attributes could be deduced from the platform
+type, having these explicit allows analysing traces from yet unknown
+platforms. The cpu attribute specifies the maximum number of processors in
+the system; only tracefiles 0 to this maximum - 1 may exist in the cpu
+directory.
+</p>
+
+<p>
+Within the system element, the text enclosed may describe further the
+system traced.
+</p>
+
+
+<h2>Bookmarks</h2>
+
+<p>
+Bookmarks are user supplied information added to a trace. They contain user
+annotations attached to a time interval.
+</p>
+
+
+<pre><tt>
+<bookmarks>
+ <location name=name cpu=n start_time=t end_time=t>Some text</location>
+ ...
+</bookmarks>
+</tt></pre>
+
+<p>
+The interval is defined using either "time=" or "start_time=" and
+"end_time=", or "cycle=" or "start_cycle=" and "end_cycle=".
+The time is in seconds with decimals up to nanoseconds and cycle counts
+are unsigned integers with a 64 bits range. The cpu attribute is optional.
+</p>
+
+-->
+</body>
+</html>
projects / lttv.git / blobdiff