Add offset_s to deal with offset overflow
[ctf.git] / common-trace-format-specification.txt
index 83d0fc144c46bf47083297f92354ae7905264428..545fbc7ebaa98ffeb602e481fcf038935c476ade 100644 (file)
@@ -1250,44 +1250,48 @@ struct {
 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 increment once per nanosecond.
+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.:
 
-enum clocks {
-       cycle_counter,
-};
-
-clock[cycle_counter] {
+clock {
+       name = cycle_counter_sync;
        uuid = "62189bee-96dc-11e0-91a8-cfa3d89f3923";
-       description = "Local CPU cycle counter";
+       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 * (1/freq) */
-       offset = 1326476837897235420;
+       /*
+        * clock value offset from Epoch is:
+        * offset_s + (offset * (1/freq))
+        */
+       offset_s = 1326476837;
+       offset = 897235420;
 };
 
-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" field indicates the offset from POSIX.1 Epoch,
-1970-01-01 00:00:00 +0000 (UTC), to the zero of value of the clock, in
-(1/freq) units. If the "offset" field is not present, it is assigned the
-0 value.
+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].value;
+       map = clock.cycle_counter_sync.value;
 } := uint64_ccnt_t;
 
 Thirdly, stream declarations can reference the clock they use as a
This page took 0.03137 seconds and 4 git commands to generate.