From 147c6f7fc4f80e38b970052de8bcab28f4f45acc Mon Sep 17 00:00:00 2001 From: pmf Date: Fri, 30 May 2008 15:15:31 +0000 Subject: [PATCH] format.html: update lttng trace format git-svn-id: http://ltt.polymtl.ca/svn@2935 04897980-b3bd-0310-b5e0-8ef037075253 --- ltt/branches/poly/doc/developer/format.html | 321 +++----------------- 1 file changed, 35 insertions(+), 286 deletions(-) diff --git a/ltt/branches/poly/doc/developer/format.html b/ltt/branches/poly/doc/developer/format.html index 254700af..e19b5d19 100644 --- a/ltt/branches/poly/doc/developer/format.html +++ b/ltt/branches/poly/doc/developer/format.html @@ -8,34 +8,22 @@

The LTTng trace format

-This document describes the LTTng trace format. It should be used only by +Last update: 2008/05/23 + +

+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.

-A trace is contained in a directory tree. To send a trace remotely, -the directory tree may be tar-gzipped. Trace foo, placed in the home -directory of user john, /home/john, would have the following content: +A trace is contained in a directory tree. To send a trace remotely, the +directory tree may be tar-gzipped. The trace foo, placed in the home +directory of user john, /home/john, would have the following contents: 


 $ cd /home/john
 $ tree foo
 foo/
-|-- eventdefs
-|   |-- core.xml
-|   |-- fs.xml
-|   |-- ipc.xml
-|   |-- kernel.xml
-|   |-- memory.xml
-|   |-- network.xml
-|   |-- process.xml
-|   |-- s390_kernel.xml
-|   |-- socket.xml
-|   |-- timer.xml
-|   `-- ...
-|-- info
-|   |-- bookmarks.xml
-|   `-- system.xml
 |-- control
 |   |-- facilities_0
 |   |-- facilities_1
@@ -55,50 +43,23 @@ foo/
-

-The eventdefs directory contains the events descriptions for all the -facilities used. The syntax is a simple subset of XML; XML is widely -known and easily parsed or hand edited. Each file contains one or more -... elements. Indeed, several -facilities may have the same name but different content (and thus will -generate a different checksum). It typically happens when, while tracing -is enabled, a module using the named facility is unloaded, modified -(along with the description of some events), recompiled and reloaded. -Then, the trace will contain events from two different, similarly named, -facility versions. - -

-A small number of events are predefined, part of the "core" facility, -and are not present there. These "core" events include "facility_load", -"facility_unload", "time_heartbeat" and "state_dump_facility_load". -

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 a 8 way SMP board with 6 CPUs randomly +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.

-The files in the control directory also follow the .trace format and are also -per cpu. -The "facilities" file only contains "core" facility_load, facility_unload, -time_heartbeat and state_dump_facility_load events -and is used to determine the facilities used and the code range assigned -to each facility. 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". - -

-The info directory contains in system.xml a description of the system on which -the trace was created as well as different user annotations in bookmark.xml. -This directory may also contain various information about the trace, generated -during trace analysis (statistics, index...). - +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".

Trace format

@@ -119,8 +80,7 @@ event 2 variable length data padding -

-The block start/end header +

The block start/end header


 begin
@@ -132,7 +92,7 @@ begin
 end
 	* the end of buffer information
 	uint64 cycle_count
-		* TSC at the beginning of the buffer
+		* TSC at the end of the buffer
 	uint64 freq
 		* frequency of the CPUs at the end of the buffer.
 uint32 lost_size
@@ -143,8 +103,7 @@ uint32 buf_size
 
 
 
-

-The trace header
+
The trace header

 
 

 uint32 magic_number
@@ -169,10 +128,13 @@ 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 has_alignment
-	* Is the information in this trace aligned ?
-		Yes (1) -> aligned on min(arch size, atomic data size).
+uint8 alignment
+	* Are event headers in this trace aligned ?
+		Yes -> the value indicates the alignment
 		No (0) -> data is packed.
+uint8 tsc_lsb_truncate
+uint8 tscbits
+uint8 compact_data_shift
 uint32 freq_scale
 		event time is always calculated from :
 			trace_start_time + ((event_tsc - trace_start_tsc) * (freq / freq_scale))
@@ -193,12 +155,11 @@ start_time
 

 
 
-

-Event header
+
Event header

 
 

-Event headers differs depending on those conditions : does the traced system has
-a heartbeat timer ? Is tracing alignment activated ?
+Event headers differ according to the following conditions : does the
+traced system have a heartbeat timer? Is tracing alignment activated?
 
 

 Event header :
@@ -222,13 +183,12 @@ uint16 event_size
 Event header alignment
 
 

-If trace alignment is activated (has_alignment), the event header is aligned
-on the architecture size (void pointer size). In addition, a padding is
-automatically added after the event header so the variable length data is
-automatically aligned on the architecture size.
+If trace alignment is activated (alignment), 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.
 
 

-
+
 
 
-
-
-
-
-- 
2.34.1