Clarity variant vs enum mapping requirements

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

diff --git a/common-trace-format-specification.txt b/common-trace-format-specification.txt
index 00ffe4a81ae8dbf571e28bd5335766562be03979..7d013d071108dcc7fd3d6bcbbea1c008cd01f935 100644 (file)
--- a/common-trace-format-specification.txt
+++ b/common-trace-format-specification.txt
@@ -41,12 +41,12 @@ Table of Contents
        4.1.6 GNU/C bitfields
        4.1.7 Floating point
        4.1.8 Enumerations
-4.2 Compound types
-    4.2.1 Structures
-    4.2.2 Variants (Discriminated/Tagged Unions)
-    4.2.3 Arrays
-    4.2.4 Sequences
-    4.2.5 Strings
+   4.2 Compound types
+       4.2.1 Structures
+       4.2.2 Variants (Discriminated/Tagged Unions)
+       4.2.3 Arrays
+       4.2.4 Sequences
+       4.2.5 Strings
 5. Event Packet Header
    5.1 Event Packet Header Description
    5.2 Event Packet Context Description
@@ -214,8 +214,9 @@ size (8-bit) correspond to the C99 standard integers. In addition,
 integers with alignment and/or size that are _not_ a multiple of the
 byte size are permitted; these correspond to the C99 standard bitfields,
 with the added specification that the CTF integer bitfields have a fixed
-binary representation. A MIT-licensed reference implementation of the
-CTF portable bitfields is available at:
+binary representation. Integer size needs to be a positive integer.
+Integers of size 0 are forbidden. A MIT-licensed reference
+implementation of the CTF portable bitfields is available at:
 
   http://git.efficios.com/?p=babeltrace.git;a=blob;f=include/babeltrace/bitfield.h
 
@@ -357,9 +358,10 @@ ranges (or single values) to strings. Instead of being limited to simple
 "value -> string" mappings, these enumerations map
 "[ start_value ... end_value ] -> string", which map inclusive ranges of
 values to strings.  An enumeration from the C language can be represented in
-this format by having the same start_value and end_value for each element, which
-is in fact a range of size 1. This single-value range is supported without
-repeating the start and end values with the value = string declaration.
+this format by having the same start_value and end_value for each
+mapping, which is in fact a range of size 1. This single-value range is
+supported without repeating the start and end values with the value =
+string declaration.  Enumerations need to contain at least one entry.
 
 enum name : integer_type {
   somestring          = start_value1 ... end_value1,
@@ -460,12 +462,15 @@ A CTF variant is a selection between different types. A CTF variant must
 always be defined within the scope of a structure or within fields
 contained within a structure (defined recursively). A "tag" enumeration
 field must appear in either the same static scope, prior to the variant
-field (in field declaration order), in an upper static scope , or in an
+field (in field declaration order), in an upper static scope, or in an
 upper dynamic scope (see Section 7.3.2). The type selection is indicated
 by the mapping from the enumeration value to the string used as variant
 type selector. The field to use as tag is specified by the "tag_field",
 specified between "< >" after the "variant" keyword for unnamed
-variants, and after "variant name" for named variants.
+variants, and after "variant name" for named variants. It is not
+required that each enumeration mapping appears as variant type tag field.
+However, it is required that any enumeration mapping encountered within a
+stream has a matching variant type tag field.
 
 The alignment of the variant is the alignment of the type as selected by
 the tag value for the specific instance of the variant.  The size of the
@@ -816,6 +821,12 @@ located in inner structures (those with a higher number in the listing
 above) can refer to the fields of outer structures (with lower number in
 the listing above). See Section 7.3 TSDL Scopes for more detail.
 
+The total length of an event is defined as the difference between the
+end of its Event Payload and the end of the previous event's Event
+Payload. Therefore, it includes the event header alignment padding, and
+all its fields and their respective alignment padding. Events of length
+0 are forbidden.
+
 6.1 Event Header
 
 Event headers can be described within the meta-data. We hereby propose, as an