-Each tracefile is divided into equal size blocks with an uint32 at the block
-end giving the offset to the last event in the block. Events are packed
-sequentially in the block starting at offset 0 with a "block_start" event
-and ending, at the offset stored in the last 4 bytes of the block, with a
-block_end event. Both the block_start and block_end events
-contain the kernel timestamp (timespec binary structure,
-uint32 seconds, uint32 nanoseconds), the cycle counter (uint64 cycles),
-and the buffer id (uint64).
+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>
+Each block consists of :
+<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>
+
+<P>
+The block start/end header
+
+<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 beginning 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>
+
+
+
+<P>
+The trace header
+
+<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 has_alignment
+ * Is the information in this trace aligned ?
+ Yes (1) -> aligned on min(arch size, atomic data size).
+ No (0) -> data is packed.
+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>
+
+
+<P>
+Event header
+
+<P>
+Event headers differs depending on those conditions : does the traced system has
+a heartbeat timer ? Is tracing alignment activated ?