include/side/abi/attribute.h

   1 // SPDX-License-Identifier: MIT
   2 /*
   3  * Copyright 2022-2023 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
   4  */
   5
   6 #ifndef SIDE_ABI_ATTRIBUTE_H
   7 #define SIDE_ABI_ATTRIBUTE_H
   8
   9 #include <stdint.h>
  10 #include <side/macros.h>
  11 #include <side/endian.h>
  12
  13 #include <side/abi/type-value.h>
  14
  15 /*
  16  * SIDE ABI for description of event and type attributes.
  17  * Event and type attributes are an optional array of { key, value }
  18  * pairs which can be associated with either an event or a type.
  19  *
  20  * The extensibility scheme for the SIDE ABI for description of event
  21  * and type attributes is as follows:
  22  *
  23  * * Existing attribute types are never changed nor extended. Attribute
  24  *   types can be added to the ABI by reserving a label within
  25  *   enum side_attr_type.
  26  * * Each union part of the ABI has an explicit size defined by a
  27  *   side_padding() member. Each structure and union have a static
  28  *   assert validating its size.
  29  * * Changing the semantic of the existing attribute type fields is a
  30  *   breaking ABI change.
  31  *
  32  * Handling of unknown attribute types by the tracers:
  33  *
  34  * * A tracer may choose to support only a subset of the types supported
  35  *   by libside. When encountering an unknown or unsupported attribute
  36  *   type, the tracer has the option to either disallow the entire
  37  *   event, skip over the field containing the unknown attribute, or
  38  *   skip over the unknown attribute, both at event registration and
  39  *   when receiving the side_call arguments.
  40  */
  41
  42 enum side_attr_type {
  43         SIDE_ATTR_TYPE_NULL,
  44         SIDE_ATTR_TYPE_BOOL,
  45         SIDE_ATTR_TYPE_U8,
  46         SIDE_ATTR_TYPE_U16,
  47         SIDE_ATTR_TYPE_U32,
  48         SIDE_ATTR_TYPE_U64,
  49         SIDE_ATTR_TYPE_S8,
  50         SIDE_ATTR_TYPE_S16,
  51         SIDE_ATTR_TYPE_S32,
  52         SIDE_ATTR_TYPE_S64,
  53         SIDE_ATTR_TYPE_FLOAT_BINARY16,
  54         SIDE_ATTR_TYPE_FLOAT_BINARY32,
  55         SIDE_ATTR_TYPE_FLOAT_BINARY64,
  56         SIDE_ATTR_TYPE_FLOAT_BINARY128,
  57         SIDE_ATTR_TYPE_STRING,
  58
  59         _NR_SIDE_ATTR_TYPE,     /* Last entry. */
  60 };
  61
  62 struct side_attr_value {
  63         side_enum_t(enum side_attr_type, uint32_t) type;
  64         union {
  65                 uint8_t bool_value;
  66                 struct side_type_raw_string string_value;
  67                 union side_integer_value integer_value;
  68                 union side_float_value float_value;
  69                 side_padding(32);
  70         } SIDE_PACKED u;
  71 };
  72 side_check_size(struct side_attr_value, 36);
  73
  74 struct side_attr {
  75         const struct side_type_raw_string key;
  76         const struct side_attr_value value;
  77 } SIDE_PACKED;
  78 side_check_size(struct side_attr, 54);
  79
  80 #endif /* SIDE_ABI_ATTRIBUTE_H */