Clarify use of underscores for fields

[ctf.git] / common-trace-format-specification.txt

diff --git a/common-trace-format-specification.txt b/common-trace-format-specification.txt
index a8603ba49f1b42ed2124debe642d2797069ea8f2..cb28d6afee7aecb7a730aed9a605bf6c75a54b68 100644 (file)
--- a/common-trace-format-specification.txt
+++ b/common-trace-format-specification.txt
@@ -420,7 +420,8 @@ 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.
+underscore-prefixed field names is recommended. Fields starting with an
+underscore should have their leading underscore removed by the CTF parser.
 
 A nameless structure can be declared as a field type or as part of a typedef:
 
@@ -461,7 +462,9 @@ 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.
+underscore-prefixed field names is recommended. Fields starting with an
+underscore should have their leading underscore removed by the CTF parser.
+
 
 A named variant declaration followed by its definition within a structure
 declaration:
@@ -1085,7 +1088,9 @@ 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.
+field name. Consequently, fields starting with an underscore should have
+their leading underscore removed by the CTF parser.
+
 
 The information available in the dynamic scopes can be thought of as the
 current tracing context. At trace production, information about the
@@ -1263,8 +1268,13 @@ clock {
        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;
+       absolute = FALSE;
 };
 
 The mandatory "name" field specifies the name of the clock identifier,
@@ -1275,10 +1285,16 @@ 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.
+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. The field "absolute" is TRUE if the clock is a global reference
+across different clock uuid (e.g. NTP time). Otherwise, "absolute" is
+FALSE, and the clock can be considered as synchronized only with other
+clocks that have the same uuid.
+
 
 Secondly, a reference to this clock should be added within an integer
 type: