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
  21 /*
  22  * Context value
  23  *
  24  * IMPORTANT: this structure is part of the ABI between the probe and
  25  * UST. Additional selectors may be added in the future, mapping to new
  26  * union fields, which means the overall size of this structure may
  27  * increase. This means this structure should never be nested within a
  28  * public structure interface, nor embedded in an array.
  29  */
  30
  31 struct lttng_ust_ctx_value {
  32         enum lttng_ust_dynamic_type sel;        /* Type selector */
  33         union {
  34                 int64_t s64;
  35                 uint64_t u64;
  36                 const char *str;
  37                 double d;
  38         } u;
  39 };
  40
  41 /*
  42  * Context provider
  43  *
  44  * IMPORTANT: this structure is part of the ABI between the probe and
  45  * UST. Fields need to be only added at the end, never reordered, never
  46  * removed.
  47  *
  48  * The field @struct_size should be used to determine the size of the
  49  * structure. It should be queried before using additional fields added
  50  * at the end of the structure.
  51  */
  52
  53 struct lttng_ust_context_provider {
  54         uint32_t struct_size;
  55
  56         const char *name;
  57         size_t (*get_size)(void *priv, size_t offset);
  58         void (*record)(void *priv, struct lttng_ust_ring_buffer_ctx *ctx,
  59                        struct lttng_ust_channel_buffer *chan);
  60         void (*get_value)(void *priv, struct lttng_ust_ctx_value *value);
  61         void *priv;
  62
  63         /* End of base ABI. Fields below should be used after checking struct_size. */
  64 };
  65
  66 /*
  67  * Returns an opaque pointer on success, which must be passed to
  68  * lttng_ust_context_provider_unregister for unregistration. Returns
  69  * NULL on error.
  70  */
  71 struct lttng_ust_registered_context_provider *lttng_ust_context_provider_register(struct lttng_ust_context_provider *provider);
  72
  73 void lttng_ust_context_provider_unregister(struct lttng_ust_registered_context_provider *reg_provider);
  74
  75 #endif /* _LTTNG_UST_CONTEXT_PROVIDER_H */