X-Git-Url: http://git.efficios.com/?p=ctf.git;a=blobdiff_plain;f=common-trace-format-specification.txt;h=545fbc7ebaa98ffeb602e481fcf038935c476ade;hp=ebad3ba7f6a9edf5417a351236cc1d81744a7b78;hb=a40cccda464fe11361936121b51cdaa635508c29;hpb=980015f9c9d06b3b2bc978554f1a70dd3701659f

diff --git a/common-trace-format-specification.txt b/common-trace-format-specification.txt
index ebad3ba..545fbc7 100644
--- a/common-trace-format-specification.txt
+++ b/common-trace-format-specification.txt
@@ -65,6 +65,7 @@ Table of Contents
        7.3.1 Lexical Scope
        7.3.2 Static and Dynamic Scopes
    7.4 TSDL Examples
+8. Clocks
 
 
 1. Preliminary definitions
@@ -752,7 +753,6 @@ struct event_packet_context {
   uint32_t cpu_id;
   uint32_t/uint16_t content_size;
   uint32_t/uint16_t packet_size;
-  uint8_t  stream_packet_count_bits;	/* Significant counter bits */
   uint8_t  compression_scheme;
   uint8_t  encryption_scheme;
   uint8_t  checksum_scheme;
@@ -1245,6 +1245,84 @@ struct {
 }
 
 
+8. Clocks
+
+Clock metadata allows to describe the clock topology of the system, as
+well as to detail each clock parameter. In absence of clock description,
+it is assumed that all fields named "timestamp" use the same clock
+source, which increments once per nanosecond.
+
+Describing a clock and how it is used by streams is threefold: first,
+the clock and clock topology should be described in a "clock"
+description block, e.g.:
+
+clock {
+	name = cycle_counter_sync;
+	uuid = "62189bee-96dc-11e0-91a8-cfa3d89f3923";
+	description = "Cycle counter synchronized across CPUs";
+	freq = 1000000000;	       /* frequency, in Hz */
+	/* precision in seconds is: 1000 * (1/freq) */
+	precision = 1000;
+	/*
+	 * clock value offset from Epoch is:
+	 * offset_s + (offset * (1/freq))
+	 */
+	offset_s = 1326476837;
+	offset = 897235420;
+};
+
+The mandatory "name" field specifies the name of the clock identifier,
+which can later be used as a reference. The optional field "uuid" is the
+unique identifier of the clock. It can be used to correlate different
+traces that use the same clock. An optional textual description string
+can be added with the "description" field. The "freq" field is the
+initial frequency of the clock, in Hz. If the "freq" field is not
+present, the frequency is assumed to be 1000000000 (providing clock
+increment of 1 ns). The optional "precision" field details the
+uncertainty on the clock measurements, in (1/freq) units. The "offset_s"
+and "offset" fields indicate the offset from POSIX.1 Epoch, 1970-01-01
+00:00:00 +0000 (UTC), to the zero of value of the clock. The "offset_s"
+field is in seconds. The "offset" field is in (1/freq) units. If any of
+the "offset_s" or "offset" field is not present, it is assigned the 0
+value.
+
+Secondly, a reference to this clock should be added within an integer
+type:
+
+typealias integer {
+	size = 64; align = 1; signed = false;
+	map = clock.cycle_counter_sync.value;
+} := uint64_ccnt_t;
+
+Thirdly, stream declarations can reference the clock they use as a
+time-stamp source:
+
+struct packet_context {
+	uint64_ccnt_t ccnt_begin;
+	uint64_ccnt_t ccnt_end;
+	/* ... */
+};
+
+stream {
+	/* ... */
+	event.header := struct {
+		uint64_ccnt_t timestamp;
+		/* ... */
+	}
+	packet.context := struct packet_context;
+};
+
+For a N-bit integer type referring to a clock, if the integer overflows
+compared to the N low order bits of the clock prior value, then it is
+assumed that one, and only one, overflow occurred. It is therefore
+important that events encoding time on a small number of bits happen
+frequently enough to detect when more than one N-bit overflow occurs.
+
+In a packet context, clock field names ending with "_begin" and "_end"
+have a special meaning: this refers to the time-stamps at, respectively,
+the beginning and the end of each packet.
+
+
 A. Helper macros
 
 The two following macros keep track of the size of a GNU/C structure without
@@ -1316,6 +1394,7 @@ keyword: is one of
 align
 const
 char
+clock
 double
 enum
 event