lib: add MIP 1 pre-conditions for functions taking a selector / length field class

MIP 1 deprecates referring to selector and length fields by passing a
field class pointer.

Add pre-condition checks for all functions that accept a selector or
length field class, to verify that the graph's MIP version is 0.

Add new macros in assert-cond.h to check for MIP version equality.

Philippe updated the documentation.

Change-Id: I980d8117c7460f79cfe802e2aba90eee71bc807a
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7315
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7198

diff --git a/doc/api/libbabeltrace2/Doxyfile.in b/doc/api/libbabeltrace2/Doxyfile.in
index eb13e9e8d204adb78280356e23a42824e72f5e06..5a4a1e40379b636cf0b7bb13c2810dcb78b97e5e 100644 (file)
--- a/doc/api/libbabeltrace2/Doxyfile.in
+++ b/doc/api/libbabeltrace2/Doxyfile.in
@@ -118,6 +118,10 @@ ALIASES                += bt_pre_is_pe_msg{1}="@pre \bt_p{\1} is a \link api-msg
 ALIASES                += bt_pre_is_sb_msg{1}="@pre \bt_p{\1} is a \link api-msg-sb stream beginning message\endlink."
 ALIASES                += bt_pre_is_se_msg{1}="@pre \bt_p{\1} is a \link api-msg-se stream end message\endlink."
 
+# Aliases: preconditions: MIP version
+ALIASES                += bt_pre_tc_with_mip{2}="@pre \bt_p{\1} was created from a \bt_comp which belongs to a trace processing \bt_graph with the effective \bt_mip version \2."
+ALIASES                += bt_pre_fc_with_mip{2}="@pre \bt_p{\1} was created from a \bt_trace_cls which was created from a \bt_comp which belongs to a trace processing \bt_graph with the effective \bt_mip version \2."
+
 # Aliases: field class object types: singular
 ALIASES                += bt_fc="\link api-tir-fc field class\endlink"
 ALIASES                += bt_ba_fc="\link api-tir-fc-ba bit array field class\endlink"

diff --git a/include/babeltrace2/trace-ir/field-class.h b/include/babeltrace2/trace-ir/field-class.h
index fdd2099502c4c1878cd57783a20b0be8081d3be7..869f8e2ec2846ce891ad1b57be1f40fcb49d3e0c 100644 (file)
--- a/include/babeltrace2/trace-ir/field-class.h
+++ b/include/babeltrace2/trace-ir/field-class.h
@@ -2869,6 +2869,7 @@ property values:
     New dynamic array field class reference, or \c NULL on memory error.
 
 @bt_pre_not_null{trace_class}
+@bt_pre_tc_with_mip{trace_class, 0}
 @bt_pre_not_null{element_field_class}
 @bt_pre_fc_not_in_tc{element_field_class}
 @pre
@@ -2916,6 +2917,7 @@ In the meantime, this function returns \c NULL.
 
 @bt_pre_not_null{field_class}
 @bt_pre_is_darray_wl_fc{field_class}
+@bt_pre_fc_with_mip{field_class, 0}
 */
 extern const bt_field_path *
 bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(
@@ -3393,6 +3395,7 @@ In the meantime, this function returns \c NULL.
 
 @bt_pre_not_null{field_class}
 @bt_pre_is_opt_ws_fc{field_class}
+@bt_pre_fc_with_mip{field_class, 0}
 */
 extern const bt_field_path *
 bt_field_class_option_with_selector_field_borrow_selector_field_path_const(
@@ -3446,6 +3449,7 @@ values:
     New option field class reference, or \c NULL on memory error.
 
 @bt_pre_not_null{trace_class}
+@bt_pre_tc_with_mip{trace_class, 0}
 @bt_pre_not_null{optional_field_class}
 @bt_pre_fc_not_in_tc{optional_field_class}
 @bt_pre_not_null{selector_field_class}
@@ -3564,6 +3568,7 @@ values:
     New option field class reference, or \c NULL on memory error.
 
 @bt_pre_not_null{trace_class}
+@bt_pre_tc_with_mip{trace_class, 0}
 @bt_pre_not_null{optional_field_class}
 @bt_pre_fc_not_in_tc{optional_field_class}
 @bt_pre_not_null{selector_field_class}
@@ -3658,6 +3663,7 @@ values:
     New option field class reference, or \c NULL on memory error.
 
 @bt_pre_not_null{trace_class}
+@bt_pre_tc_with_mip{trace_class, 0}
 @bt_pre_not_null{optional_field_class}
 @bt_pre_fc_not_in_tc{optional_field_class}
 @bt_pre_not_null{selector_field_class}
@@ -3751,6 +3757,7 @@ property values:
     New variant field class reference, or \c NULL on memory error.
 
 @bt_pre_not_null{trace_class}
+@bt_pre_tc_with_mip{trace_class, 0}
 @pre
     <strong>If \bt_p{selector_field_class} is not \c NULL</strong>,
     \bt_p{selector_field_class} is an \bt_int_fc.
@@ -4141,6 +4148,7 @@ In the meantime, this function returns \c NULL.
 
 @bt_pre_not_null{field_class}
 @bt_pre_is_var_ws_fc{field_class}
+@bt_pre_fc_with_mip{field_class, 0}
 */
 extern const bt_field_path *
 bt_field_class_variant_with_selector_field_borrow_selector_field_path_const(

diff --git a/src/lib/assert-cond.h b/src/lib/assert-cond.h
index 993edcc994922d352c2079331e3819475c6f50ae..62437c5aaf6a76a7e12014b894cf17a8f8d25db5 100644 (file)
--- a/src/lib/assert-cond.h
+++ b/src/lib/assert-cond.h
@@ -946,6 +946,26 @@
        BT_ASSERT_PRE_DEV_NON_NULL(_BT_ASSERT_PRE_GRAPH_ID, (_graph),   \
                _BT_ASSERT_PRE_GRAPH_NAME)
 
+#define _BT_ASSERT_PRE_MIP_VERSION_VALID_ID    "mip-version-is-valid"
+
+/* Asserts that the MIP version `_mip_version` is equal to `_val`. */
+#define BT_ASSERT_PRE_MIP_VERSION_EQ(_mip_version, _val)       \
+       BT_ASSERT_PRE(_BT_ASSERT_PRE_MIP_VERSION_VALID_ID,      \
+               _mip_version == _val,                           \
+               "MIP version is not equal to %" PRIu64, _val)
+
+/*
+ * Asserts that the effective MIP version for `_trace_class` is equal to `_val`.
+ */
+#define BT_ASSERT_PRE_TC_MIP_VERSION_EQ(_trace_class, _val)            \
+       BT_ASSERT_PRE_MIP_VERSION_EQ((_trace_class)->mip_version, _val)
+
+/*
+ * Asserts that the effective MIP version for `_field_class` is equal to `_val`.
+ */
+#define BT_ASSERT_PRE_FC_MIP_VERSION_EQ(_field_class, _val)            \
+       BT_ASSERT_PRE_MIP_VERSION_EQ((_field_class)->mip_version, _val)
+
 #define _BT_ASSERT_PRE_INTR_NAME       "Interrupter"
 #define _BT_ASSERT_PRE_INTR_ID         "interrupter"
 

diff --git a/src/lib/trace-ir/field-class.c b/src/lib/trace-ir/field-class.c
index a0f54a2a3468dbf6eb4fb739a346b15b2bb676a3..576241a7b1af7f83a5a06308a8e168e879e7b8f6 100644 (file)
--- a/src/lib/trace-ir/field-class.c
+++ b/src/lib/trace-ir/field-class.c
@@ -1335,6 +1335,7 @@ struct bt_field_class *bt_field_class_option_with_selector_field_bool_create(
                struct bt_field_class *selector_fc)
 {
        BT_ASSERT_PRE_NO_ERROR();
+       BT_ASSERT_PRE_TC_MIP_VERSION_EQ(trace_class, 0);
 
        return create_option_field_class(trace_class,
                BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD,
@@ -1354,6 +1355,7 @@ bt_field_class_option_with_selector_field_integer_unsigned_create(
                (const void *) u_range_set;
 
        BT_ASSERT_PRE_NO_ERROR();
+       BT_ASSERT_PRE_TC_MIP_VERSION_EQ(trace_class, 0);
        BT_ASSERT_PRE_INT_RANGE_SET_NON_NULL(range_set);
        BT_ASSERT_PRE_INT_RANGE_SET_NOT_EMPTY(range_set);
        fc = (void *) create_option_field_class(trace_class,
@@ -1385,6 +1387,7 @@ bt_field_class_option_with_selector_field_integer_signed_create(
                (const void *) i_range_set;
 
        BT_ASSERT_PRE_NO_ERROR();
+       BT_ASSERT_PRE_TC_MIP_VERSION_EQ(trace_class, 0);
        BT_ASSERT_PRE_INT_RANGE_SET_NON_NULL(range_set);
        BT_ASSERT_PRE_INT_RANGE_SET_NOT_EMPTY(range_set);
        fc = (void *) create_option_field_class(trace_class,
@@ -1435,6 +1438,7 @@ bt_field_class_option_with_selector_field_borrow_selector_field_path_const(
 
        BT_ASSERT_PRE_FC_NON_NULL(fc);
        BT_ASSERT_PRE_FC_IS_OPTION_WITH_SEL("field-class", fc, "Field class");
+       BT_ASSERT_PRE_FC_MIP_VERSION_EQ(fc, 0);
        return opt_fc->selector_field_path;
 }
 
@@ -1539,6 +1543,7 @@ struct bt_field_class *bt_field_class_variant_create(
 
        BT_ASSERT_PRE_NO_ERROR();
        BT_ASSERT_PRE_TC_NON_NULL(trace_class);
+       BT_ASSERT_PRE_TC_MIP_VERSION_EQ(trace_class, 0);
 
        if (selector_fc) {
                BT_ASSERT_PRE_FC_IS_INT("selector-field-class", selector_fc,
@@ -2014,6 +2019,7 @@ bt_field_class_variant_with_selector_field_borrow_selector_field_path_const(
        BT_ASSERT_PRE_DEV_FC_NON_NULL(fc);
        BT_ASSERT_PRE_DEV_FC_IS_VARIANT_WITH_SEL("field-class", fc,
                "Field class");
+       BT_ASSERT_PRE_FC_MIP_VERSION_EQ(fc, 0);
        return var_fc->selector_field_path;
 }
 
@@ -2155,6 +2161,7 @@ struct bt_field_class *bt_field_class_array_dynamic_create(
 
        BT_ASSERT_PRE_NO_ERROR();
        BT_ASSERT_PRE_TC_NON_NULL(trace_class);
+       BT_ASSERT_PRE_TC_MIP_VERSION_EQ(trace_class, 0);
        BT_ASSERT_PRE_NON_NULL("element-field-class", element_fc,
                "Element field class");
        BT_LOGD_STR("Creating default dynamic array field class object.");
@@ -2205,6 +2212,7 @@ bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(
                "dynamic-array-field-class-with-length-field",
                BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD,
                "Field class");
+       BT_ASSERT_PRE_FC_MIP_VERSION_EQ(fc, 0);
        return seq_fc->length_field_path;
 }