Clarify integer size

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

diff --git a/common-trace-format-specification.txt b/common-trace-format-specification.txt
index 46c1013890bcbf5a3d047ffa0c80d32b3db1a62f..ecdd26f3389e2323e6acb95ee72fe4c7ed8410aa 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
 
@@ -360,6 +361,7 @@ 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.
+Enumerations need to contain at least one entry.
 
 enum name : integer_type {
   somestring          = start_value1 ... end_value1,
@@ -717,7 +719,11 @@ Event packet context (all fields are optional, specified by TSDL meta-data):
   while (or before) writing the first event and while (or after) writing the
   last event in the packet. The inclusive range between these timestamps should
   include all event timestamps assigned to events contained within the packet.
-  See Section 8. Clocks for more detail.
+  The timestamp at the beginning of an event packet is guaranteed to be
+  below or equal the timestamp at the end of that event packet.
+  The timestamp at the end of an event packet is guaranteed to be below
+  or equal the timestamps at the end of any following packet within the
+  same stream. See Section 8. Clocks for more detail.
 - Events discarded count
   - Snapshot of a per-stream free-running counter, counting the number of
     events discarded that were supposed to be written in the stream after
@@ -812,6 +818,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