X-Git-Url: https://git.efficios.com/?a=blobdiff_plain;f=include%2Fside%2Fabi%2Ftype-value.h;h=d445e26706707640211af459af57ba3794b5ed38;hb=35e4f870db53745e7c259e0270ebc746f93d6f8a;hp=9d489effa6e579e3d08078dab5efd382e13f5940;hpb=b8dfb3487e6b30e0ae8e0c8e337ae46885e9761b;p=libside.git

diff --git a/include/side/abi/type-value.h b/include/side/abi/type-value.h
index 9d489ef..d445e26 100644
--- a/include/side/abi/type-value.h
+++ b/include/side/abi/type-value.h
@@ -10,6 +10,30 @@
 #include <side/macros.h>
 #include <side/endian.h>
 
+/*
+ * SIDE ABI for type values.
+ *
+ * The extensibility scheme for the SIDE ABI for type values is as
+ * follows:
+ *
+ * * Existing type values are never changed nor extended. Type values
+ *   can be added to the ABI by reserving a label within enum
+ *   side_type_label.
+ * * Each union part of the ABI has an explicit size defined by a
+ *   side_padding() member. Each structure and union have a static
+ *   assert validating its size.
+ * * Changing the semantic of the existing type value fields is a
+ *   breaking ABI change.
+ *
+ * Handling of unknown type values by the tracers:
+ *
+ * * A tracer may choose to support only a subset of the type values
+ *   supported by libside. When encountering an unknown or unsupported
+ *   type value, the tracer has the option to either disallow the entire
+ *   event or skip over the unknown type, both at event registration and
+ *   when receiving the side_call arguments.
+ */
+
 enum side_type_label_byte_order {
 	SIDE_TYPE_BYTE_ORDER_LE = 0,
 	SIDE_TYPE_BYTE_ORDER_BE = 1,