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

[Yao Qi]

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 am not good at documentation, nor a native English speaker.  My 
suggestion can be wrong.

-- 
Yao (齐尧)