From 6d35572a24bb6d7b1d21d0bf88dc49e5bfac5e20 Mon Sep 17 00:00:00 2001 From: Mathieu Desnoyers Date: Mon, 15 Mar 2021 16:33:31 -0400 Subject: [PATCH] Document public event and session structures Signed-off-by: Mathieu Desnoyers Change-Id: I50cd2a5d122eed9fe5b333919bbba351dd0867d3 --- include/lttng/ust-events.h | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/include/lttng/ust-events.h b/include/lttng/ust-events.h index f7915d7d..d9e15d34 100644 --- a/include/lttng/ust-events.h +++ b/include/lttng/ust-events.h @@ -355,6 +355,10 @@ enum lttng_ust_event_type { }; /* + * IMPORTANT: this structure is part of the ABI between the probe and + * UST. Fields need to be only added at the end, never reordered, never + * removed. + * * struct lttng_ust_event_common is the common ancestor of the various * public event actions. Inheritance is done by composition: The parent * has a pointer to its child, and the child has a pointer to its @@ -383,6 +387,10 @@ struct lttng_ust_event_common { struct lttng_ust_event_recorder_private; /* + * IMPORTANT: this structure is part of the ABI between the probe and + * UST. Fields need to be only added at the end, never reordered, never + * removed. + * * struct lttng_ust_event_recorder is the action for recording events * into a ring buffer. It inherits from struct lttng_ust_event_common * by composition to ensure both parent and child structure are @@ -407,6 +415,10 @@ struct lttng_ust_event_recorder { struct lttng_ust_event_notifier_private; /* + * IMPORTANT: this structure is part of the ABI between the probe and + * UST. Fields need to be only added at the end, never reordered, never + * removed. + * * struct lttng_ust_event_notifier is the action for sending * notifications. It inherits from struct lttng_ust_event_common * by composition to ensure both parent and child structure are @@ -560,12 +572,18 @@ struct lttng_ust_session_private; * IMPORTANT: this structure is part of the ABI between the probe and * UST. Fields need to be only added at the end, never reordered, never * removed. + * + * The field @struct_size should be used to determine the size of the + * structure. It should be queried before using additional fields added + * at the end of the structure. */ struct lttng_session { uint32_t struct_size; /* Size of this structure */ struct lttng_ust_session_private *priv; /* Private session interface */ int active; /* Is trace session active ? */ + + /* End of base ABI. Fields below should be used after checking struct_size. */ }; int lttng_probe_register(struct lttng_probe_desc *desc); -- 2.34.1