Add offset_s to deal with offset overflow
[ctf.git] / common-trace-format-specification.txt
index 19194c840c706db912caf72185403f2c5345b7cd..545fbc7ebaa98ffeb602e481fcf038935c476ade 100644 (file)
@@ -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
@@ -415,8 +416,11 @@ struct example {
   uint64_t second_field_name;  /* Named type declared in the meta-data */
 };
 
-The fields are placed in a sequence next to each other. They each possess a
-field name, which is a unique identifier within the structure.
+The fields are placed in a sequence next to each other. They each
+possess a field name, which is a unique identifier within the structure.
+The identifier is not allowed to use any reserved keyword
+(see Section C.1.2). Replacing reserved keywords with
+underscore-prefixed field names is recommended.
 
 A nameless structure can be declared as a field type or as part of a typedef:
 
@@ -454,6 +458,11 @@ containing the variant is independent of the variant alignment.  The size of the
 variant is the size as selected by the tag value for the specific instance of
 the variant.
 
+Each variant type selector possess a field name, which is a unique
+identifier within the variant. The identifier is not allowed to use any
+reserved keyword (see Section C.1.2). Replacing reserved keywords with
+underscore-prefixed field names is recommended.
+
 A named variant declaration followed by its definition within a structure
 declaration:
 
@@ -744,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;
@@ -935,12 +943,19 @@ tracer.
 
 The text-only meta-data file is a plain-text TSDL description. This file
 must begin with the following characters to identify the file as a CTF
-TSDL text-based metadata file:
+TSDL text-based metadata file (without the double-quotes) :
+
+"/* CTF"
+
+It must be followed by a space, and the version of the specification
+followed by the CTF trace, e.g.:
 
-/* TSDL */
+" 1.8"
 
-These characters allow automated discovery of file type. They are
-interpreted as a comment by the TSDL metadata parser.
+These characters allow automated discovery of file type and CTF
+specification version. They are interpreted as a the beginning of a
+comment by the TSDL metadata parser.  The comment can be continued to
+contain extra commented characters before it is closed.
 
 The packet-based meta-data is made of "meta-data packets", which each
 start with a meta-data packet header. The packet-based meta-data
@@ -965,6 +980,8 @@ struct metadata_packet_header {
   uint8_t  compression_scheme;         /* 0 if unused */
   uint8_t  encryption_scheme;          /* 0 if unused */
   uint8_t  checksum_scheme;            /* 0 if unused */
+  uint8_t  major;                      /* CTF spec version major number */
+  uint8_t  minor;                      /* CTF spec version minor number */
 };
 
 The packet-based meta-data can be converted to a text-only meta-data by
@@ -1036,9 +1053,8 @@ associated with a variant, and to lookup up the location of the length
 field associated with a sequence.
 
 Variants and sequences can refer to a tag field either using a relative
-path or an absolute path. The relative path starts with "." to ensure
-there are no conflicts with dynamic scope names. It is relative to the
-scope in which the variant or sequence performing the lookup is located.
+path or an absolute path. The relative path is relative to the scope in
+which the variant or sequence performing the lookup is located.
 Relative paths are only allowed to lookup within the same static scope,
 which includes its nested static scopes. Lookups targeting parent static
 scopes need to be performed with an absolute path.
@@ -1063,15 +1079,13 @@ The dynamic scope prefixes are thus:
 
 
 The target dynamic scope must be specified explicitly when referring to
-a field outside of the static scope (absolute scope reference).
-References to fields within the static scope (including local static
-scopes and nested static scopes) can be referenced by using a relative
-reference (starting with ".").
-
-As a matter of convenience, the leading "." in relative paths can be
-omitted. In case of conflict between relative and dynamic paths, the
-relative path is preferred. It is recommended to use the "." prefix for
-relative paths to ensure no path name conflict can occur.
+a field outside of the static scope (absolute scope reference). No
+conflict can occur between relative and dynamic paths, because the
+keywords "trace", "stream", and "event" are reserved, and thus
+not permitted as field names. It is recommended that field names
+clashing with CTF and C99 reserved keywords use an underscore prefix to
+eliminate the risk of generating a description containing an invalid
+field name.
 
 The information available in the dynamic scopes can be thought of as the
 current tracing context. At trace production, information about the
@@ -1115,9 +1129,11 @@ stream {
 };
 
 event {
-  name = event_name;
+  name = "event_name";
   id = value;                  /* Numeric identifier within the stream */
   stream_id = stream_id;
+  loglevel.identifier = "loglevel_identifier";
+  loglevel.value = value;
   context := struct {
     ...
   };
@@ -1229,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
@@ -1300,6 +1394,7 @@ keyword: is one of
 align
 const
 char
+clock
 double
 enum
 event
This page took 0.033828 seconds and 4 git commands to generate.