1 // SPDX-License-Identifier: MIT
3 * Copyright 2022-2023 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
6 #ifndef SIDE_ABI_TYPE_ARGUMENT_H
7 #define SIDE_ABI_TYPE_ARGUMENT_H
10 #include <side/macros.h>
11 #include <side/endian.h>
13 #include <side/abi/type-value.h>
14 #include <side/abi/attribute.h>
15 #include <side/abi/type-description.h>
16 #include <side/abi/visitor.h>
19 * SIDE ABI for arguments passed to instrumentation call site.
21 * The extensibility scheme for the SIDE ABI for call site arguments is
24 * * Existing argument types are never changed nor extended. Argument
25 * types can be added to the ABI by reserving a label within
26 * enum side_type_label.
27 * * Each union part of the ABI has an explicit size defined by a
28 * side_padding() member. Each structure and union have a static
29 * assert validating its size.
30 * * Changing the semantic of the existing argument type fields is a
31 * breaking ABI change.
33 * Handling of unknown argument types by the tracers:
35 * * A tracer may choose to support only a subset of the types supported
36 * by libside. When encountering an unknown or unsupported type, the
37 * tracer has the option to either disallow the entire event or skip
38 * over the unknown type, both at event registration and when
39 * receiving the side_call arguments.
42 #if (SIDE_BYTE_ORDER == SIDE_LITTLE_ENDIAN)
43 # define SIDE_TYPE_BYTE_ORDER_HOST SIDE_TYPE_BYTE_ORDER_LE
45 # define SIDE_TYPE_BYTE_ORDER_HOST SIDE_TYPE_BYTE_ORDER_BE
48 #if (SIDE_FLOAT_WORD_ORDER == SIDE_LITTLE_ENDIAN)
49 # define SIDE_TYPE_FLOAT_WORD_ORDER_HOST SIDE_TYPE_BYTE_ORDER_LE
51 # define SIDE_TYPE_FLOAT_WORD_ORDER_HOST SIDE_TYPE_BYTE_ORDER_BE
54 union side_arg_static
{
55 /* Stack-copy basic types */
56 union side_bool_value bool_value
;
58 side_ptr_t(const void) string_value
; /* const {uint8_t, uint16_t, uint32_t} * */
59 union side_integer_value integer_value
;
60 union side_float_value float_value
;
62 /* Stack-copy compound types */
63 side_ptr_t(const struct side_arg_vec
) side_struct
;
64 side_ptr_t(const struct side_arg_variant
) side_variant
;
65 side_ptr_t(const struct side_arg_vec
) side_array
;
66 side_ptr_t(const struct side_arg_vec
) side_vla
;
67 void *side_vla_app_visitor_ctx
;
69 /* Gather basic types */
70 side_ptr_t(const void) side_bool_gather_ptr
;
71 side_ptr_t(const void) side_byte_gather_ptr
;
72 side_ptr_t(const void) side_integer_gather_ptr
;
73 side_ptr_t(const void) side_float_gather_ptr
;
74 side_ptr_t(const void) side_string_gather_ptr
;
76 /* Gather compound types */
77 side_ptr_t(const void) side_array_gather_ptr
;
78 side_ptr_t(const void) side_struct_gather_ptr
;
80 side_ptr_t(const void) ptr
;
81 side_ptr_t(const void) length_ptr
;
82 } SIDE_PACKED side_vla_gather
;
85 side_check_size(union side_arg_static
, 32);
87 struct side_arg_dynamic_vla
{
88 side_ptr_t(const struct side_arg
) sav
;
89 side_ptr_t(const struct side_attr
) attr
;
93 side_check_size(struct side_arg_dynamic_vla
, 40);
95 struct side_arg_dynamic_struct
{
96 side_ptr_t(const struct side_arg_dynamic_field
) fields
;
97 side_ptr_t(const struct side_attr
) attr
;
101 side_check_size(struct side_arg_dynamic_struct
, 40);
103 struct side_dynamic_struct_visitor
{
104 side_func_ptr_t(side_dynamic_struct_visitor_func
) visitor
;
105 side_ptr_t(void) app_ctx
;
106 side_ptr_t(const struct side_attr
) attr
;
109 side_check_size(struct side_dynamic_struct_visitor
, 52);
111 struct side_dynamic_vla_visitor
{
112 side_func_ptr_t(side_visitor_func
) visitor
;
113 side_ptr_t(void) app_ctx
;
114 side_ptr_t(const struct side_attr
) attr
;
117 side_check_size(struct side_dynamic_vla_visitor
, 52);
119 union side_arg_dynamic
{
120 /* Dynamic basic types */
121 struct side_type_null side_null
;
123 struct side_type_bool type
;
124 union side_bool_value value
;
125 } SIDE_PACKED side_bool
;
127 struct side_type_byte type
;
129 } SIDE_PACKED side_byte
;
131 struct side_type_string type
;
132 uint64_t value
; /* const char * */
133 } SIDE_PACKED side_string
;
135 struct side_type_integer type
;
136 union side_integer_value value
;
137 } SIDE_PACKED side_integer
;
139 struct side_type_float type
;
140 union side_float_value value
;
141 } SIDE_PACKED side_float
;
143 /* Dynamic compound types */
144 side_ptr_t(const struct side_arg_dynamic_struct
) side_dynamic_struct
;
145 side_ptr_t(const struct side_arg_dynamic_vla
) side_dynamic_vla
;
147 struct side_dynamic_struct_visitor side_dynamic_struct_visitor
;
148 struct side_dynamic_vla_visitor side_dynamic_vla_visitor
;
152 side_check_size(union side_arg_dynamic
, 58);
155 side_enum_t(enum side_type_label
, uint16_t) type
;
157 union side_arg_static side_static
;
158 union side_arg_dynamic side_dynamic
;
162 side_check_size(struct side_arg
, 64);
164 struct side_arg_variant
{
165 struct side_arg selector
;
166 struct side_arg option
;
168 side_check_size(struct side_arg_variant
, 128);
170 struct side_arg_vec
{
171 side_ptr_t(const struct side_arg
) sav
;
174 side_check_size(struct side_arg_vec
, 20);
176 struct side_arg_dynamic_field
{
177 side_ptr_t(const char) field_name
;
178 const struct side_arg elem
;
180 side_check_size(struct side_arg_dynamic_field
, 16 + sizeof(const struct side_arg
));
182 #endif /* SIDE_ABI_TYPE_ARGUMENT_H */