[lttng-dev] [PATCH] Teach babeltrace understand "native" and "network" for byte_order

[Mathieu Desnoyers]

* Yao Qi (yao at codesourcery.com) wrote:
> On 03/15/2013 10:33 PM, Mathieu Desnoyers wrote:
>>     byte_order = native OR network OR be OR le;	/* network and be are aliases */
>>
>> +Even though the trace description section is not per se a type, for sake
>> +of clarity, it should be noted that native and network byte orders are
>> +only allowed within type declaration. The byte_order specified in the
>> +trace description section only accepts be OR le values.
>> +
>
> The first and last sentence below is a little bit confusing to me.
>
> 4.1.3 Byte order
>
> By default, the native endianness of the source architecture is used.
> ....
> If not specified, the byte order is native.
>
>
> 1.  "native endianness" appear in the spec for the first time, without a  
> precise explanation.  After your explanation in the last mail, I got to  
> know it is the endianess described in the trace description.
>
> 2.  "source architecture" is not clear to me.
>
> Maybe, we can say something like:
>
> "By default, byte order of a basic type is the byte order described in  
> the trace description.  It can be overridden by specifying a  
> "byte_order" attribute for a basic type.  Typical use-case is to specify  
> the network byte order (big endian: "be") to save data captured from the  
> network into the trace without conversion."
>
> I also suggest that we get rid of the term "native" here.  IIUC, we have  
> four options for byte order, default, network, le and be.  The latter  
> three are easy to understand, and if attribute "byte_order" is not  
> specified, it is the default.  On the other hand, "native endianness"  
> means the endianness of underlying machine, which is a little different.

I added an explanatory paragraph for "native" in addition to your
recommended changes. We cannot remove an keyword from the specification
lightly, because this would break compatibility.

>
> I am not good at documentation, nor a native English speaker.  My  
> suggestion can be wrong.

Here is the update. Comments are welcome!

Thanks,

Mathieu

commit 237324a20398c5c8eaf92aff0eace177ef8a747f
Author: Mathieu Desnoyers <mathieu.desnoyers at efficios.com>
Date:   Fri Mar 15 11:32:03 2013 -0400

    Clarify byte order section
    
    Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers at efficios.com>

diff --git a/common-trace-format-specification.txt b/common-trace-format-specification.txt
index 4ab3ed9..797dec1 100644
--- a/common-trace-format-specification.txt
+++ b/common-trace-format-specification.txt
@@ -171,20 +171,23 @@ TSDL meta-data attribute representation of a specific alignment:
 
 4.1.3 Byte order
 
-By default, the native endianness of the source architecture is used.
-Byte order can be overridden for a basic type by specifying a "byte_order"
-attribute. Typical use-case is to specify the network byte order (big endian:
-"be") to save data captured from the network into the trace without conversion.
-If not specified, the byte order is native.
+By default, byte order of a basic type is the byte order described in
+the trace description.  It can be overridden by specifying a
+"byte_order" attribute for a basic type.  Typical use-case is to specify
+the network byte order (big endian: "be") to save data captured from the
+network into the trace without conversion.
 
 TSDL meta-data representation:
 
   byte_order = native OR network OR be OR le;	/* network and be are aliases */
 
+The "native" keyword selects the byte order described in the trace
+description. The "network" byte order is an alias for big endian.
+
 Even though the trace description section is not per se a type, for sake
-of clarity, it should be noted that native and network byte orders are
-only allowed within type declaration. The byte_order specified in the
-trace description section only accepts be OR le values.
+of clarity, it should be noted that "native" and "network" byte orders
+are only allowed within type declaration. The byte_order specified in
+the trace description section only accepts "be" or "le" values.
 
 4.1.4 Size
 


-- 
Mathieu Desnoyers
EfficiOS Inc.
http://www.efficios.com