src/common/ust-context-provider.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2016 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
   5  *
   6  * The context provider feature is part of the ABI and used by the Java jni
   7  * interface. This header should be moved to the public header directory once
   8  * some test code and documentation is written.
   9  */
  10
  11 #ifndef _LTTNG_UST_CONTEXT_PROVIDER_H
  12 #define _LTTNG_UST_CONTEXT_PROVIDER_H
  13
  14 #include <stddef.h>
  15 #include <lttng/ust-events.h>
  16
  17 #include "common/dynamic-type.h"
  18
  19 struct lttng_ust_registered_context_provider;
  20 struct lttng_ust_probe_ctx;
  21
  22 /*
  23  * Context value
  24  *
  25  * IMPORTANT: this structure is part of the ABI between the probe and
  26  * UST. Additional selectors may be added in the future, mapping to new
  27  * union fields, which means the overall size of this structure may
  28  * increase. This means this structure should never be nested within a
  29  * public structure interface, nor embedded in an array.
  30  */
  31
  32 struct lttng_ust_ctx_value {
  33         enum lttng_ust_dynamic_type sel;        /* Type selector */
  34         union {
  35                 int64_t s64;
  36                 uint64_t u64;
  37                 const char *str;
  38                 double d;
  39         } u;
  40 };
  41
  42 /*
  43  * Context provider
  44  *
  45  * IMPORTANT: this structure is part of the ABI between the probe and
  46  * UST. Fields need to be only added at the end, never reordered, never
  47  * removed.
  48  *
  49  * The field @struct_size should be used to determine the size of the
  50  * structure. It should be queried before using additional fields added
  51  * at the end of the structure.
  52  */
  53
  54 struct lttng_ust_context_provider {
  55         uint32_t struct_size;
  56
  57         const char *name;
  58         size_t (*get_size)(void *priv, struct lttng_ust_probe_ctx *probe_ctx,
  59                         size_t offset);
  60         void (*record)(void *priv, struct lttng_ust_probe_ctx *probe_ctx,
  61                         struct lttng_ust_ring_buffer_ctx *ctx,
  62                         struct lttng_ust_channel_buffer *chan);
  63         void (*get_value)(void *priv, struct lttng_ust_probe_ctx *probe_ctx,
  64                         struct lttng_ust_ctx_value *value);
  65         void *priv;
  66
  67         /* End of base ABI. Fields below should be used after checking struct_size. */
  68 };
  69
  70 /*
  71  * Application context callback private data
  72  *
  73  * IMPORTANT: this structure is part of the ABI between the probe and
  74  * UST. Fields need to be only added at the end, never reordered, never
  75  * removed.
  76  *
  77  * The field @struct_size should be used to determine the size of the
  78  * structure. It should be queried before using additional fields added
  79  * at the end of the structure.
  80  */
  81
  82 struct lttng_ust_app_context {
  83         uint32_t struct_size;
  84
  85         struct lttng_ust_event_field *event_field;
  86         char *ctx_name;
  87
  88         /* End of base ABI. Fields below should be used after checking struct_size. */
  89 };
  90
  91 /*
  92  * Returns an opaque pointer on success, which must be passed to
  93  * lttng_ust_context_provider_unregister for unregistration. Returns
  94  * NULL on error.
  95  */
  96 struct lttng_ust_registered_context_provider *lttng_ust_context_provider_register(struct lttng_ust_context_provider *provider);
  97
  98 void lttng_ust_context_provider_unregister(struct lttng_ust_registered_context_provider *reg_provider);
  99
 100 #endif /* _LTTNG_UST_CONTEXT_PROVIDER_H */