Debian Codegraph @

gcc/jit/docs/topics/compatibility.rst

raw
1 .. Copyright (C) 2015-2022 Free Software Foundation, Inc.
2 Originally contributed by David Malcolm <[email protected]>
3
4 This is free software: you can redistribute it and/or modify it
5 under the terms of the GNU General Public License as published by
6 the Free Software Foundation, either version 3 of the License, or
7 (at your option) any later version.
8
9 This program is distributed in the hope that it will be useful, but
10 WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 General Public License for more details.
13
14 You should have received a copy of the GNU General Public License
15 along with this program. If not, see
16 <https://www.gnu.org/licenses/>.
17
18 .. default-domain:: c
19
20 ABI and API compatibility
21 =========================
22
23 The libgccjit developers strive for ABI and API backward-compatibility:
24 programs built against libgccjit.so stand a good chance of running
25 without recompilation against newer versions of libgccjit.so, and
26 ought to recompile without modification against newer versions of
27 libgccjit.h.
28
29 .. note:: The libgccjit++.h C++ API is more experimental, and less
30 locked-down at this time.
31
32 API compatibility is achieved by extending the API rather than changing
33 it. For ABI compatiblity, we avoid bumping the SONAME, and instead use
34 symbol versioning to tag each symbol, so that a binary linked against
35 libgccjit.so is tagged according to the symbols that it uses.
36
37 For example, :func:`gcc_jit_context_add_command_line_option` was added in
38 ``LIBGCCJIT_ABI_1``. If a client program uses it, this can be detected
39 from metadata by using ``objdump``:
40
41 .. code-block:: bash
42
43 $ objdump -p testsuite/jit/test-extra-options.c.exe | tail -n 8
44
45 Version References:
46 required from libgccjit.so.0:
47 0x00824161 0x00 04 LIBGCCJIT_ABI_1
48 0x00824160 0x00 03 LIBGCCJIT_ABI_0
49 required from libc.so.6:
50
51 You can see the symbol tags provided by libgccjit.so using ``objdump``:
52
53 .. code-block:: bash
54
55 $ objdump -p libgccjit.so | less
56 [...snip...]
57 Version definitions:
58 1 0x01 0x0ff81f20 libgccjit.so.0
59 2 0x00 0x00824160 LIBGCCJIT_ABI_0
60 3 0x00 0x00824161 LIBGCCJIT_ABI_1
61 LIBGCCJIT_ABI_0
62 [...snip...]
63
64 Programmatically checking version
65 *********************************
66
67 Client code can programmatically check libgccjit version using:
68
69 .. function:: int gcc_jit_version_major (void)
70
71 Return libgccjit major version. This is analogous to __GNUC__ in C code.
72
73 .. function:: int gcc_jit_version_minor (void)
74
75 Return libgccjit minor version. This is analogous to
76 __GNUC_MINOR__ in C code.
77
78 .. function:: int gcc_jit_version_patchlevel (void)
79
80 Return libgccjit patchlevel version. This is analogous to
81 __GNUC_PATCHLEVEL__ in C code.
82
83 .. note:: These entry points has been added with ``LIBGCCJIT_ABI_13``
84 (see below).
85
86 ABI symbol tags
87 ***************
88
89 The initial release of libgccjit (in gcc 5.1) did not use symbol versioning.
90
91 Newer releases use the following tags.
92
93 .. _LIBGCCJIT_ABI_0:
94
95 ``LIBGCCJIT_ABI_0``
96 -------------------
97
98 All entrypoints in the initial release of libgccjit are tagged with
99 ``LIBGCCJIT_ABI_0``, to signify the transition to symbol versioning.
100
101 Binaries built against older copies of ``libgccjit.so`` should
102 continue to work, with this being handled transparently by the linker
103 (see `this post
104 <https://gcc.gnu.org/ml/gcc-patches/2015-06/msg02126.html>`_)
105
106 .. _LIBGCCJIT_ABI_1:
107
108 ``LIBGCCJIT_ABI_1``
109 -------------------
110 ``LIBGCCJIT_ABI_1`` covers the addition of
111 :func:`gcc_jit_context_add_command_line_option`
112
113 .. _LIBGCCJIT_ABI_2:
114
115 ``LIBGCCJIT_ABI_2``
116 -------------------
117 ``LIBGCCJIT_ABI_2`` covers the addition of
118 :func:`gcc_jit_context_set_bool_allow_unreachable_blocks`
119
120 .. _LIBGCCJIT_ABI_3:
121
122 ``LIBGCCJIT_ABI_3``
123 -------------------
124 ``LIBGCCJIT_ABI_3`` covers the addition of switch statements via API
125 entrypoints:
126
127 * :func:`gcc_jit_block_end_with_switch`
128
129 * :func:`gcc_jit_case_as_object`
130
131 * :func:`gcc_jit_context_new_case`
132
133 .. _LIBGCCJIT_ABI_4:
134
135 ``LIBGCCJIT_ABI_4``
136 -------------------
137 ``LIBGCCJIT_ABI_4`` covers the addition of timers via API
138 entrypoints:
139
140 * :func:`gcc_jit_context_get_timer`
141
142 * :func:`gcc_jit_context_set_timer`
143
144 * :func:`gcc_jit_timer_new`
145
146 * :func:`gcc_jit_timer_release`
147
148 * :func:`gcc_jit_timer_push`
149
150 * :func:`gcc_jit_timer_pop`
151
152 * :func:`gcc_jit_timer_print`
153
154 .. _LIBGCCJIT_ABI_5:
155
156 ``LIBGCCJIT_ABI_5``
157 -------------------
158 ``LIBGCCJIT_ABI_5`` covers the addition of
159 :func:`gcc_jit_context_set_bool_use_external_driver`
160
161 .. _LIBGCCJIT_ABI_6:
162
163 ``LIBGCCJIT_ABI_6``
164 -------------------
165 ``LIBGCCJIT_ABI_6`` covers the addition of
166 :func:`gcc_jit_rvalue_set_bool_require_tail_call`
167
168 .. _LIBGCCJIT_ABI_7:
169
170 ``LIBGCCJIT_ABI_7``
171 -------------------
172 ``LIBGCCJIT_ABI_7`` covers the addition of
173 :func:`gcc_jit_type_get_aligned`
174
175 .. _LIBGCCJIT_ABI_8:
176
177 ``LIBGCCJIT_ABI_8``
178 -------------------
179 ``LIBGCCJIT_ABI_8`` covers the addition of
180 :func:`gcc_jit_type_get_vector`
181
182 .. _LIBGCCJIT_ABI_9:
183
184 ``LIBGCCJIT_ABI_9``
185 -------------------
186 ``LIBGCCJIT_ABI_9`` covers the addition of
187 :func:`gcc_jit_function_get_address`
188
189 .. _LIBGCCJIT_ABI_10:
190
191 ``LIBGCCJIT_ABI_10``
192 --------------------
193 ``LIBGCCJIT_ABI_10`` covers the addition of
194 :func:`gcc_jit_context_new_rvalue_from_vector`
195
196 .. _LIBGCCJIT_ABI_11:
197
198 ``LIBGCCJIT_ABI_11``
199 --------------------
200 ``LIBGCCJIT_ABI_11`` covers the addition of
201 :func:`gcc_jit_context_add_driver_option`
202
203 .. _LIBGCCJIT_ABI_12:
204
205 ``LIBGCCJIT_ABI_12``
206 --------------------
207 ``LIBGCCJIT_ABI_12`` covers the addition of
208 :func:`gcc_jit_context_new_bitfield`
209
210 .. _LIBGCCJIT_ABI_13:
211
212 ``LIBGCCJIT_ABI_13``
213 --------------------
214 ``LIBGCCJIT_ABI_13`` covers the addition of version functions via API
215 entrypoints:
216
217 * :func:`gcc_jit_version_major`
218
219 * :func:`gcc_jit_version_minor`
220
221 * :func:`gcc_jit_version_patchlevel`
222
223 .. _LIBGCCJIT_ABI_14:
224
225 ``LIBGCCJIT_ABI_14``
226 --------------------
227 ``LIBGCCJIT_ABI_14`` covers the addition of
228 :func:`gcc_jit_global_set_initializer`
229
230 .. _LIBGCCJIT_ABI_15:
231
232 ``LIBGCCJIT_ABI_15``
233 --------------------
234 ``LIBGCCJIT_ABI_15`` covers the addition of API entrypoints for directly
235 embedding assembler instructions:
236
237 * :func:`gcc_jit_block_add_extended_asm`
238 * :func:`gcc_jit_block_end_with_extended_asm_goto`
239 * :func:`gcc_jit_extended_asm_as_object`
240 * :func:`gcc_jit_extended_asm_set_volatile_flag`
241 * :func:`gcc_jit_extended_asm_set_inline_flag`
242 * :func:`gcc_jit_extended_asm_add_output_operand`
243 * :func:`gcc_jit_extended_asm_add_input_operand`
244 * :func:`gcc_jit_extended_asm_add_clobber`
245 * :func:`gcc_jit_context_add_top_level_asm`
246
247 .. _LIBGCCJIT_ABI_16:
248
249 ``LIBGCCJIT_ABI_16``
250 --------------------
251 ``LIBGCCJIT_ABI_16`` covers the addition of reflection functions via API
252 entrypoints:
253
254 * :func:`gcc_jit_function_get_return_type`
255
256 * :func:`gcc_jit_function_get_param_count`
257
258 * :func:`gcc_jit_type_dyncast_array`
259
260 * :func:`gcc_jit_type_is_bool`
261
262 * :func:`gcc_jit_type_is_integral`
263
264 * :func:`gcc_jit_type_is_pointer`
265
266 * :func:`gcc_jit_type_is_struct`
267
268 * :func:`gcc_jit_type_dyncast_vector`
269
270 * :func:`gcc_jit_type_unqualified`
271
272 * :func:`gcc_jit_type_dyncast_function_ptr_type`
273
274 * :func:`gcc_jit_function_type_get_return_type`
275
276 * :func:`gcc_jit_function_type_get_param_count`
277
278 * :func:`gcc_jit_function_type_get_param_type`
279
280 * :func:`gcc_jit_vector_type_get_num_units`
281
282 * :func:`gcc_jit_vector_type_get_element_type`
283
284 * :func:`gcc_jit_struct_get_field`
285
286 * :func:`gcc_jit_struct_get_field_count`
287
288 .. _LIBGCCJIT_ABI_17:
289
290 ``LIBGCCJIT_ABI_17``
291 -----------------------
292 ``LIBGCCJIT_ABI_17`` covers the addition of an API entrypoint to set the
293 thread-local storage model of a variable:
294
295 * :func:`gcc_jit_lvalue_set_tls_model`
296
297 .. _LIBGCCJIT_ABI_18:
298
299 ``LIBGCCJIT_ABI_18``
300 -----------------------
301 ``LIBGCCJIT_ABI_18`` covers the addition of an API entrypoint to set the link
302 section of a variable:
303
304 * :func:`gcc_jit_lvalue_set_link_section`
305
306 .. _LIBGCCJIT_ABI_19:
307
308 ``LIBGCCJIT_ABI_19``
309 -----------------------
310 ``LIBGCCJIT_ABI_19`` covers the addition of API entrypoints to set the initial value
311 of a global with an rvalue and to use constructors:
312
313 * :func:`gcc_jit_context_new_array_constructor`
314 * :func:`gcc_jit_context_new_struct_constructor`
315 * :func:`gcc_jit_context_new_union_constructor`
316 * :func:`gcc_jit_global_set_initializer_rvalue`
317
318 .. _LIBGCCJIT_ABI_20:
319
320 ``LIBGCCJIT_ABI_20``
321 -----------------------
322 ``LIBGCCJIT_ABI_20`` covers the addition of sized integer types, including
323 128-bit integers and helper functions for types:
324
325 * :func:`gcc_jit_compatible_types`
326 * :func:`gcc_jit_type_get_size`
327 * :c:macro:`GCC_JIT_TYPE_UINT8_T`
328 * :c:macro:`GCC_JIT_TYPE_UINT16_T`
329 * :c:macro:`GCC_JIT_TYPE_UINT32_T`
330 * :c:macro:`GCC_JIT_TYPE_UINT64_T`
331 * :c:macro:`GCC_JIT_TYPE_UINT128_T`
332 * :c:macro:`GCC_JIT_TYPE_INT8_T`
333 * :c:macro:`GCC_JIT_TYPE_INT16_T`
334 * :c:macro:`GCC_JIT_TYPE_INT32_T`
335 * :c:macro:`GCC_JIT_TYPE_INT64_T`
336 * :c:macro:`GCC_JIT_TYPE_INT128_T`
337
338 .. _LIBGCCJIT_ABI_21:
339
340 ``LIBGCCJIT_ABI_21``
341 --------------------
342 ``LIBGCCJIT_ABI_21`` covers the addition of an API entrypoint to bitcast a
343 value from one type to another:
344
345 * :func:`gcc_jit_context_new_bitcast`
346
347 .. _LIBGCCJIT_ABI_22:
348
349 ``LIBGCCJIT_ABI_22``
350 --------------------
351 ``LIBGCCJIT_ABI_22`` covers the addition of an API entrypoint to set the
352 register name of a variable:
353
354 * :func:`gcc_jit_lvalue_set_register_name`
355
356 .. _LIBGCCJIT_ABI_23:
357
358 ``LIBGCCJIT_ABI_23``
359 --------------------
360 ``LIBGCCJIT_ABI_23`` covers the addition of an API entrypoint to hide stderr
361 logs:
362
363 * :func:`gcc_jit_context_set_bool_print_errors_to_stderr`
364
365 .. _LIBGCCJIT_ABI_24:
366
367 ``LIBGCCJIT_ABI_24``
368 --------------------
369 ``LIBGCCJIT_ABI_24`` covers the addition of functions to get and set the
370 alignment of a variable:
371
372 * :func:`gcc_jit_lvalue_set_alignment`
373 * :func:`gcc_jit_lvalue_get_alignment`