ir: add BT_CTF_BYTE_ORDER_NONE and make it the default trace's native BO

There's a problem now where you need to explicitly set the native byte
order of a trace you create with bt_ctf_trace_create() with
bt_ctf_trace_set_native_byte_order() before the trace object is frozen,
otherwise the function which would cause the freezing fails.

Some trace formats have no byte order concept. Other properties like
alignment and binary field sizes may have no meaning either. Source
component classes which implement the decoding of those formats should
do a best effort to represent their trace's metadata using CTF IR. That
said, choosing an arbitrary trace's native byte order imposes this byte
order when a ctf.fs sink writes the trace. Here, BT_CTF_BYTE_ORDER_NONE
means that we don't care about the byte order, that it was not
meaningful when decoding the original trace, therefore you can choose
any output byte order you want.

With this patch, the initial trace's native byte order is
BT_CTF_BYTE_ORDER_NONE, and this is a valid byte order when the trace
needs to be frozen. A non-CTF writer trace cannot be used by a CTF
writer object anyway; a CTF writer always creates its own trace object.
The initial native byte order of a CTF writer trace is the machine's
byte order. You cannot set a CTF writer trace's native byte order to
BT_CTF_BYTE_ORDER_NONE. Also, you cannot set any field type's byte order
to BT_CTF_BYTE_ORDER_NONE: it's only valid for a non-CTF writer trace.

libctfcopytrace is modified to only explicitly set the CTF writer
trace's native byte order if the original trace's native byte order is
not BT_CTF_BYTE_ORDER_NONE.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/include/babeltrace/ctf-ir/field-types-internal.h b/include/babeltrace/ctf-ir/field-types-internal.h
index 8de2e05d3711b583bdec767e653ad01c2658d2de..4c21cbd47457cf56be4ab3da3cd0980d804f864c 100644 (file)
--- a/include/babeltrace/ctf-ir/field-types-internal.h
+++ b/include/babeltrace/ctf-ir/field-types-internal.h
@@ -253,6 +253,8 @@ const char *bt_ctf_byte_order_string(enum bt_ctf_byte_order bo)
        switch (bo) {
        case BT_CTF_BYTE_ORDER_UNKNOWN:
                return "BT_CTF_BYTE_ORDER_UNKNOWN";
+       case BT_CTF_BYTE_ORDER_NONE:
+               return "BT_CTF_BYTE_ORDER_NONE";
        case BT_CTF_BYTE_ORDER_NATIVE:
                return "BT_CTF_BYTE_ORDER_NATIVE";
        case BT_CTF_BYTE_ORDER_LITTLE_ENDIAN:

diff --git a/include/babeltrace/ctf-ir/field-types.h b/include/babeltrace/ctf-ir/field-types.h
index 6b6a0d0a7efd200a490ea95edad7781ebfbcfd51..61dc291ae560b1555a27d06d80987b1247103c27 100644 (file)
--- a/include/babeltrace/ctf-ir/field-types.h
+++ b/include/babeltrace/ctf-ir/field-types.h
@@ -492,6 +492,12 @@ enum bt_ctf_byte_order {
        /// Native (default) byte order.
        BT_CTF_BYTE_ORDER_NATIVE = 0,
 
+       /**
+       No byte order; the initial native byte order of a
+       \link ctfirtraceclass CTF IR trace class\endlink.
+       */
+       BT_CTF_BYTE_ORDER_NONE,
+
        /// Little-endian.
        BT_CTF_BYTE_ORDER_LITTLE_ENDIAN,
 

diff --git a/include/babeltrace/ctf-ir/trace.h b/include/babeltrace/ctf-ir/trace.h
index 83e888b433081e48d640b3a35dc920243c0d0e8d..362cd707c8152223de0c4573bee5a527d2eedd4c 100644 (file)
--- a/include/babeltrace/ctf-ir/trace.h
+++ b/include/babeltrace/ctf-ir/trace.h
@@ -181,12 +181,8 @@ The created trace class has the following initial properties:
   with bt_ctf_trace_set_name().
 - <strong>UUID</strong>: none. You can set a UUID with
   bt_ctf_trace_set_uuid().
-- <strong>Native byte order</strong>: #BT_CTF_BYTE_ORDER_NATIVE. You
+- <strong>Native byte order</strong>: #BT_CTF_BYTE_ORDER_NONE. You
   can set a native byte order with bt_ctf_trace_set_native_byte_order().
-
-  Note that you \em must set the native byte order if any field type
-  contained in the created trace class, in its stream classes, or in
-  its event classes, has a byte order set to #BT_CTF_BYTE_ORDER_NATIVE.
 - <strong>Environment</strong>: empty. You can add environment entries
   with bt_ctf_trace_set_environment_field(),
   bt_ctf_trace_set_environment_field_integer(), and
@@ -269,6 +265,8 @@ extern enum bt_ctf_byte_order bt_ctf_trace_get_native_byte_order(
 - #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN
 - #BT_CTF_BYTE_ORDER_BIG_ENDIAN
 - #BT_CTF_BYTE_ORDER_NETWORK
+- <strong>If the trace is not in CTF writer mode<strong>,
+  #BT_CTF_BYTE_ORDER_NONE.
 
 @param[in] trace_class         Trace class of which to set the native byte
                                order.
@@ -277,8 +275,9 @@ extern enum bt_ctf_byte_order bt_ctf_trace_get_native_byte_order(
 
 @prenotnull{trace_class}
 @prehot{trace_class}
-@pre \p native_byte_order is either #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN,
-       #BT_CTF_BYTE_ORDER_BIG_ENDIAN, or
+@pre \p native_byte_order is either #BT_CTF_BYTE_ORDER_NONE (if the
+       trace is not in CTF writer mode),
+       #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN, #BT_CTF_BYTE_ORDER_BIG_ENDIAN, or
        #BT_CTF_BYTE_ORDER_NETWORK.
 @postrefcountsame{trace_class}
 

diff --git a/lib/ctf-ir/field-types.c b/lib/ctf-ir/field-types.c
index 78feecb9fa624715df70c2dc5b201f2fd853ac09..21794508a8c3c2c9e0565313fcb2f98b998ad14b 100644 (file)
--- a/lib/ctf-ir/field-types.c
+++ b/lib/ctf-ir/field-types.c
@@ -3223,7 +3223,7 @@ int bt_ctf_field_type_set_byte_order(struct bt_ctf_field_type *type,
                        byte_order != BT_CTF_BYTE_ORDER_LITTLE_ENDIAN &&
                        byte_order != BT_CTF_BYTE_ORDER_BIG_ENDIAN &&
                        byte_order != BT_CTF_BYTE_ORDER_NETWORK) {
-               BT_LOGW("Invalid parameter: unknown byte order: "
+               BT_LOGW("Invalid parameter: invalid byte order: "
                        "addr=%p, bo=%s", type,
                        bt_ctf_byte_order_string(byte_order));
                ret = -1;

diff --git a/lib/ctf-ir/trace.c b/lib/ctf-ir/trace.c
index fe0d362ea8d893b3fc819768545207ed426e76dc..6515dfe8ceb3387eadf957baafe21d954bf29c40 100644 (file)
--- a/lib/ctf-ir/trace.c
+++ b/lib/ctf-ir/trace.c
@@ -102,7 +102,7 @@ struct bt_ctf_trace *bt_ctf_trace_create(void)
        }
 
        BT_LOGD_STR("Creating trace object.");
-       trace->native_byte_order = BT_CTF_BYTE_ORDER_NATIVE;
+       trace->native_byte_order = BT_CTF_BYTE_ORDER_NONE;
        bt_object_init(trace, bt_ctf_trace_destroy);
        trace->clocks = g_ptr_array_new_with_free_func(
                (GDestroyNotify) bt_put);
@@ -1122,17 +1122,6 @@ int bt_ctf_trace_add_stream_class(struct bt_ctf_trace *trace,
                stream_class, bt_ctf_stream_class_get_name(stream_class),
                bt_ctf_stream_class_get_id(stream_class));
 
-       /*
-        * At the end of this function we freeze the trace, so its
-        * native byte order must NOT be BT_CTF_BYTE_ORDER_NATIVE.
-        */
-       if (trace->native_byte_order == BT_CTF_BYTE_ORDER_NATIVE) {
-               BT_LOGW_STR("Invalid parameter: trace's byte order cannot be BT_CTF_BYTE_ORDER_NATIVE at this point; "
-                       "set it with bt_ctf_trace_set_native_byte_order().");
-               ret = -1;
-               goto end;
-       }
-
        current_parent_trace = bt_ctf_stream_class_get_trace(stream_class);
        if (current_parent_trace) {
                /* Stream class is already associated to a trace, abort. */
@@ -1660,8 +1649,9 @@ int append_trace_metadata(struct bt_ctf_trace *trace,
        unsigned char *uuid = trace->uuid;
        int ret = 0;
 
-       if (trace->native_byte_order == BT_CTF_BYTE_ORDER_NATIVE) {
-               BT_LOGW("Invalid parameter: trace's byte order cannot be BT_CTF_BYTE_ORDER_NATIVE at this point; "
+       if (trace->native_byte_order == BT_CTF_BYTE_ORDER_NATIVE ||
+                       trace->native_byte_order == BT_CTF_BYTE_ORDER_NONE) {
+               BT_LOGW("Invalid parameter: trace's byte order cannot be BT_CTF_BYTE_ORDER_NATIVE or BT_CTF_BYTE_ORDER_NONE at this point; "
                        "set it with bt_ctf_trace_set_native_byte_order(): "
                        "addr=%p, name=\"%s\"",
                        trace, bt_ctf_trace_get_name(trace));
@@ -1863,6 +1853,15 @@ int bt_ctf_trace_set_native_byte_order(struct bt_ctf_trace *trace,
                goto end;
        }
 
+       if (trace->is_created_by_writer &&
+                       byte_order == BT_CTF_BYTE_ORDER_NONE) {
+               BT_LOGW("Invalid parameter: BT_CTF_BYTE_ORDER_NONE byte order is not allowed for a CTF writer trace: "
+                       "addr=%p, name=\"%s\"",
+                       trace, bt_ctf_trace_get_name(trace));
+               ret = -1;
+               goto end;
+       }
+
        if (byte_order != BT_CTF_BYTE_ORDER_LITTLE_ENDIAN &&
                        byte_order != BT_CTF_BYTE_ORDER_BIG_ENDIAN &&
                        byte_order != BT_CTF_BYTE_ORDER_NETWORK) {

diff --git a/plugins/libctfcopytrace/ctfcopytrace.c b/plugins/libctfcopytrace/ctfcopytrace.c
index 99a332bebce9e8c3c6227c6599e12d08a6ca249e..cd8f2d5c8b500404b89b682613b95fa71ed86b72 100644 (file)
--- a/plugins/libctfcopytrace/ctfcopytrace.c
+++ b/plugins/libctfcopytrace/ctfcopytrace.c
@@ -878,11 +878,19 @@ enum bt_component_status ctf_copy_trace(FILE *err, struct bt_ctf_trace *trace,
                goto end;
        }
 
-       ret = bt_ctf_trace_set_native_byte_order(writer_trace, order);
-       if (ret) {
-               fprintf(err, "[error] %s in %s:%d\n", __func__, __FILE__, __LINE__);
-               ret = BT_COMPONENT_STATUS_ERROR;
-               goto end;
+       /*
+        * Only explicitly set the writer trace's native byte order if
+        * the original trace has a specific one. Otherwise leave what
+        * the CTF writer object chooses, which is the machine's native
+        * byte order.
+        */
+       if (order != BT_CTF_BYTE_ORDER_NONE) {
+               ret = bt_ctf_trace_set_native_byte_order(writer_trace, order);
+               if (ret) {
+                       fprintf(err, "[error] %s in %s:%d\n", __func__, __FILE__, __LINE__);
+                       ret = BT_COMPONENT_STATUS_ERROR;
+                       goto end;
+               }
        }
 
        header_type = bt_ctf_trace_get_packet_header_type(writer_trace);