1 files changed, 109 insertions, 0 deletions
diff --git a/gcc/jit/docs/topics/compatibility.rst b/gcc/jit/docs/topics/compatibility.rst
new file mode 100644
index 00000000000..37e28665e70
--- /dev/null
+++ b/gcc/jit/docs/topics/compatibility.rst
@@ -0,0 +1,109 @@
+.. Copyright (C) 2015 Free Software Foundation, Inc.
+   Originally contributed by David Malcolm <dmalcolm@redhat.com>
+
+   This is free software: you can redistribute it and/or modify it
+   under the terms of the GNU General Public License as published by
+   the Free Software Foundation, either version 3 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful, but
+   WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+   General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program.  If not, see
+   <http://www.gnu.org/licenses/>.
+
+.. default-domain:: c
+
+ABI and API compatibility
+=========================
+
+The libgccjit developers strive for ABI and API backward-compatibility:
+programs built against libgccjit.so stand a good chance of running
+without recompilation against newer versions of libgccjit.so, and
+ought to recompile without modification against newer versions of
+libgccjit.h.
+
+.. note:: The libgccjit++.h C++ API is more experimental, and less
+          locked-down at this time.
+
+API compatibility is achieved by extending the API rather than changing
+it.  For ABI compatiblity, we avoid bumping the SONAME, and instead use
+symbol versioning to tag each symbol, so that a binary linked against
+libgccjit.so is tagged according to the symbols that it uses.
+
+For example, :func:`gcc_jit_context_add_command_line_option` was added in
+``LIBGCCJIT_ABI_1``.  If a client program uses it, this can be detected
+from metadata by using ``objdump``:
+
+.. code-block:: bash
+
+   $ objdump -p testsuite/jit/test-extra-options.c.exe | tail -n 8
+
+   Version References:
+     required from libgccjit.so.0:
+       0x00824161 0x00 04 LIBGCCJIT_ABI_1
+       0x00824160 0x00 03 LIBGCCJIT_ABI_0
+     required from libc.so.6:
+
+You can see the symbol tags provided by libgccjit.so using ``objdump``:
+
+.. code-block:: bash
+
+   $ objdump -p libgccjit.so | less
+   [...snip...]
+   Version definitions:
+   1 0x01 0x0ff81f20 libgccjit.so.0
+   2 0x00 0x00824160 LIBGCCJIT_ABI_0
+   3 0x00 0x00824161 LIBGCCJIT_ABI_1
+           LIBGCCJIT_ABI_0
+   [...snip...]
+
+ABI symbol tags
+***************
+
+The initial release of libgccjit (in gcc 5.1) did not use symbol versioning.
+
+Newer releases use the following tags.
+
+.. _LIBGCCJIT_ABI_0:
+
+``LIBGCCJIT_ABI_0``
+-------------------
+
+All entrypoints in the initial release of libgccjit are tagged with
+``LIBGCCJIT_ABI_0``, to signify the transition to symbol versioning.
+
+Binaries built against older copies of ``libgccjit.so`` should
+continue to work, with this being handled transparently by the linker
+(see `this post
+<https://gcc.gnu.org/ml/gcc-patches/2015-06/msg02126.html>`_)
+
+.. _LIBGCCJIT_ABI_1:
+
+``LIBGCCJIT_ABI_1``
+-------------------
+``LIBGCCJIT_ABI_1`` covers the addition of
+:func:`gcc_jit_context_add_command_line_option`
+
+.. _LIBGCCJIT_ABI_2:
+
+``LIBGCCJIT_ABI_2``
+-------------------
+``LIBGCCJIT_ABI_2`` covers the addition of
+:func:`gcc_jit_context_set_bool_allow_unreachable_blocks`
+
+.. _LIBGCCJIT_ABI_3:
+
+``LIBGCCJIT_ABI_3``
+-------------------
+``LIBGCCJIT_ABI_3`` covers the addition of switch statements via API
+entrypoints:
+
+  * :func:`gcc_jit_block_end_with_switch`
+
+  * :func:`gcc_jit_case_as_object`
+
+  * :func:`gcc_jit_context_new_case`