lttng/ust-context-provider.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * SPDX-FileCopyrightText: 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 enum lttng_ust_dynamic_type {
  18         LTTNG_UST_DYNAMIC_TYPE_NONE,
  19         LTTNG_UST_DYNAMIC_TYPE_S8,
  20         LTTNG_UST_DYNAMIC_TYPE_S16,
  21         LTTNG_UST_DYNAMIC_TYPE_S32,
  22         LTTNG_UST_DYNAMIC_TYPE_S64,
  23         LTTNG_UST_DYNAMIC_TYPE_U8,
  24         LTTNG_UST_DYNAMIC_TYPE_U16,
  25         LTTNG_UST_DYNAMIC_TYPE_U32,
  26         LTTNG_UST_DYNAMIC_TYPE_U64,
  27         LTTNG_UST_DYNAMIC_TYPE_FLOAT,
  28         LTTNG_UST_DYNAMIC_TYPE_DOUBLE,
  29         LTTNG_UST_DYNAMIC_TYPE_STRING,
  30         _NR_LTTNG_UST_DYNAMIC_TYPES,
  31 };
  32
  33 int lttng_ust_dynamic_type_choices(size_t *nr_choices,
  34                 const struct lttng_ust_event_field * const **choices)
  35         __attribute__((visibility("hidden")));
  36
  37 const struct lttng_ust_event_field *lttng_ust_dynamic_type_field(int64_t value)
  38         __attribute__((visibility("hidden")));
  39
  40 const struct lttng_ust_event_field *lttng_ust_dynamic_type_tag_field(void)
  41         __attribute__((visibility("hidden")));
  42
  43 struct lttng_ust_registered_context_provider;
  44 struct lttng_ust_probe_ctx;
  45
  46 /*
  47  * Context value
  48  *
  49  * IMPORTANT: this structure is part of the ABI between the probe and
  50  * UST. Additional selectors may be added in the future, mapping to new
  51  * union fields, which means the overall size of this structure may
  52  * increase. This means this structure should never be nested within a
  53  * public structure interface, nor embedded in an array.
  54  */
  55
  56 struct lttng_ust_ctx_value {
  57         enum lttng_ust_dynamic_type sel;        /* Type selector */
  58         union {
  59                 int64_t s64;
  60                 uint64_t u64;
  61                 const char *str;
  62                 double d;
  63         } u;
  64 };
  65
  66 /*
  67  * Context provider
  68  *
  69  * IMPORTANT: this structure is part of the ABI between the probe and
  70  * UST. Fields need to be only added at the end, never reordered, never
  71  * removed.
  72  *
  73  * The field @struct_size should be used to determine the size of the
  74  * structure. It should be queried before using additional fields added
  75  * at the end of the structure.
  76  */
  77
  78 struct lttng_ust_context_provider {
  79         uint32_t struct_size;
  80
  81         const char *name;
  82         size_t (*get_size)(void *priv, struct lttng_ust_probe_ctx *probe_ctx,
  83                         size_t offset);
  84         void (*record)(void *priv, struct lttng_ust_probe_ctx *probe_ctx,
  85                         struct lttng_ust_ring_buffer_ctx *ctx,
  86                         struct lttng_ust_channel_buffer *chan);
  87         void (*get_value)(void *priv, struct lttng_ust_probe_ctx *probe_ctx,
  88                         struct lttng_ust_ctx_value *value);
  89         void *priv;
  90
  91         /* End of base ABI. Fields below should be used after checking struct_size. */
  92 };
  93
  94 /*
  95  * Application context callback private data
  96  *
  97  * IMPORTANT: this structure is part of the ABI between the probe and
  98  * UST. Fields need to be only added at the end, never reordered, never
  99  * removed.
 100  *
 101  * The field @struct_size should be used to determine the size of the
 102  * structure. It should be queried before using additional fields added
 103  * at the end of the structure.
 104  */
 105
 106 struct lttng_ust_app_context {
 107         uint32_t struct_size;
 108
 109         struct lttng_ust_event_field *event_field;
 110         char *ctx_name;
 111
 112         /* End of base ABI. Fields below should be used after checking struct_size. */
 113 };
 114
 115 /*
 116  * Returns an opaque pointer on success, which must be passed to
 117  * lttng_ust_context_provider_unregister for unregistration. Returns
 118  * NULL on error.
 119  */
 120 struct lttng_ust_registered_context_provider *lttng_ust_context_provider_register(struct lttng_ust_context_provider *provider);
 121
 122 void lttng_ust_context_provider_unregister(struct lttng_ust_registered_context_provider *reg_provider);
 123
 124 #endif /* _LTTNG_UST_CONTEXT_PROVIDER_H */