diff options
Diffstat (limited to 'gcc/jit/docs/topics')
| -rw-r--r-- | gcc/jit/docs/topics/compatibility.rst | 109 | ||||
| -rw-r--r-- | gcc/jit/docs/topics/contexts.rst | 69 | ||||
| -rw-r--r-- | gcc/jit/docs/topics/expressions.rst | 7 | ||||
| -rw-r--r-- | gcc/jit/docs/topics/functions.rst | 130 | ||||
| -rw-r--r-- | gcc/jit/docs/topics/index.rst | 1 | ||||
| -rw-r--r-- | gcc/jit/docs/topics/locations.rst | 4 | ||||
| -rw-r--r-- | gcc/jit/docs/topics/objects.rst | 1 | ||||
| -rw-r--r-- | gcc/jit/docs/topics/types.rst | 31 |
8 files changed, 348 insertions, 4 deletions
diff --git a/gcc/jit/docs/topics/compatibility.rst b/gcc/jit/docs/topics/compatibility.rst new file mode 100644 index 0000000000..37e28665e7 --- /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` diff --git a/gcc/jit/docs/topics/contexts.rst b/gcc/jit/docs/topics/contexts.rst index b7f281a5e6..78bcb71fac 100644 --- a/gcc/jit/docs/topics/contexts.rst +++ b/gcc/jit/docs/topics/contexts.rst @@ -293,6 +293,15 @@ future activies on a context to the given `FILE *`. Options ------- +Options present in the initial release of libgccjit were handled using +enums, whereas those added subsequently have their own per-option API +entrypoints. + +Adding entrypoints for each new option means that client code that use +the new options can be identified directly from binary metadata, which +would not be possible if we instead extended the various +``enum gcc_jit_*_option``. + String Options ************** @@ -304,7 +313,11 @@ String Options .. type:: enum gcc_jit_str_option - There is currently just one string option: + The parameter ``value`` can be NULL. If non-NULL, the call takes a + copy of the underlying string, so it is valid to pass in a pointer to + an on-stack buffer. + + There is just one string option specified this way: .. macro:: GCC_JIT_STR_OPTION_PROGNAME @@ -441,6 +454,22 @@ Boolean options If true, the :type:`gcc_jit_context` will not clean up intermediate files written to the filesystem, and will display their location on stderr. +.. function:: void \ + gcc_jit_context_set_bool_allow_unreachable_blocks (gcc_jit_context *ctxt, \ + int bool_value) + + By default, libgccjit will issue an error about unreachable blocks + within a function. + + This entrypoint can be used to disable that error. + + This entrypoint was added in :ref:`LIBGCCJIT_ABI_2`; you can test for + its presence using + + .. code-block:: c + + #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks + Integer options *************** @@ -452,7 +481,7 @@ Integer options .. type:: enum gcc_jit_int_option - There is currently just one integer option: + There is just one integer option specified this way: .. macro:: GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL @@ -462,3 +491,39 @@ Integer options -O0 through -O3. The default value is 0 (unoptimized). + +Additional command-line options +******************************* + +.. function:: void gcc_jit_context_add_command_line_option (gcc_jit_context *ctxt,\ + const char *optname) + + Add an arbitrary gcc command-line option to the context, for use + by :func:`gcc_jit_context_compile` and + :func:`gcc_jit_context_compile_to_file`. + + The parameter ``optname`` must be non-NULL. The underlying buffer is + copied, so that it does not need to outlive the call. + + Extra options added by `gcc_jit_context_add_command_line_option` are + applied *after* the regular options above, potentially overriding them. + Options from parent contexts are inherited by child contexts; options + from the parent are applied *before* those from the child. + + For example: + + .. code-block:: c + + gcc_jit_context_add_command_line_option (ctxt, "-ffast-math"); + gcc_jit_context_add_command_line_option (ctxt, "-fverbose-asm"); + + Note that only some options are likely to be meaningful; there is no + "frontend" within libgccjit, so typically only those affecting + optimization and code-generation are likely to be useful. + + This entrypoint was added in :ref:`LIBGCCJIT_ABI_1`; you can test for + its presence using + + .. code-block:: c + + #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_command_line_option diff --git a/gcc/jit/docs/topics/expressions.rst b/gcc/jit/docs/topics/expressions.rst index 621991fcc7..c12a3780a9 100644 --- a/gcc/jit/docs/topics/expressions.rst +++ b/gcc/jit/docs/topics/expressions.rst @@ -122,6 +122,9 @@ Simple expressions Generate an rvalue for the given NIL-terminated string, of type :c:data:`GCC_JIT_TYPE_CONST_CHAR_PTR`. + The parameter ``value`` must be non-NULL. The call takes a copy of the + underlying string, so it is valid to pass in a pointer to an on-stack + buffer. Unary Operations **************** @@ -466,6 +469,10 @@ Global variables Add a new global variable of the given type and name to the context. + The parameter ``name`` must be non-NULL. The call takes a copy of the + underlying string, so it is valid to pass in a pointer to an on-stack + buffer. + The "kind" parameter determines the visibility of the "global" outside of the :c:type:`gcc_jit_result`: diff --git a/gcc/jit/docs/topics/functions.rst b/gcc/jit/docs/topics/functions.rst index 774a556574..f2f8f34970 100644 --- a/gcc/jit/docs/topics/functions.rst +++ b/gcc/jit/docs/topics/functions.rst @@ -35,6 +35,10 @@ Params In preparation for creating a function, create a new parameter of the given type and name. + The parameter ``name`` must be non-NULL. The call takes a copy of the + underlying string, so it is valid to pass in a pointer to an on-stack + buffer. + Parameters are lvalues, and thus are also rvalues (and objects), so the following upcasts are available: @@ -111,6 +115,10 @@ Functions above 0; when optimization is off, this is essentially the same as GCC_JIT_FUNCTION_INTERNAL. + The parameter ``name`` must be non-NULL. The call takes a copy of the + underlying string, so it is valid to pass in a pointer to an on-stack + buffer. + .. function:: gcc_jit_function *\ gcc_jit_context_get_builtin_function (gcc_jit_context *ctxt,\ const char *name) @@ -140,6 +148,9 @@ Functions Create a new local variable within the function, of the given type and name. + The parameter ``name`` must be non-NULL. The call takes a copy of the + underlying string, so it is valid to pass in a pointer to an on-stack + buffer. Blocks ------ @@ -153,7 +164,8 @@ Blocks be the entrypoint. Each basic block that you create within a function must be - terminated, either with a conditional, a jump, or a return. + terminated, either with a conditional, a jump, a return, or a + switch. It's legal to have multiple basic blocks that return within one function. @@ -165,7 +177,17 @@ Blocks Create a basic block of the given name. The name may be NULL, but providing meaningful names is often helpful when debugging: it may show up in dumps of the internal representation, and in error - messages. + messages. It is copied, so the input buffer does not need to outlive + the call; you can pass in a pointer to an on-stack buffer, e.g.: + + .. code-block:: c + + for (pc = 0; pc < fn->fn_num_ops; pc++) + { + char buf[16]; + sprintf (buf, "instr%i", pc); + state.op_blocks[pc] = gcc_jit_function_new_block (state.fn, buf); + } .. function:: gcc_jit_object *\ gcc_jit_block_as_object (gcc_jit_block *block) @@ -251,6 +273,17 @@ Statements and thus may be of use when debugging how your project's internal representation gets converted to the libgccjit IR. + The parameter ``text`` must be non-NULL. It is copied, so the input + buffer does not need to outlive the call. For example: + + .. code-block:: c + + char buf[100]; + snprintf (buf, sizeof (buf), + "op%i: %s", + pc, opcode_names[op->op_opcode]); + gcc_jit_block_add_comment (block, loc, buf); + .. function:: void\ gcc_jit_block_end_with_conditional (gcc_jit_block *block,\ gcc_jit_location *loc,\ @@ -313,3 +346,96 @@ Statements .. code-block:: c return; + +.. function:: void\ + gcc_jit_block_end_with_switch (gcc_jit_block *block,\ + gcc_jit_location *loc,\ + gcc_jit_rvalue *expr,\ + gcc_jit_block *default_block,\ + int num_cases,\ + gcc_jit_case **cases) + + Terminate a block by adding evalation of an rvalue, then performing + a multiway branch. + + This is roughly equivalent to this C code: + + .. code-block:: c + + switch (expr) + { + default: + goto default_block; + + case C0.min_value ... C0.max_value: + goto C0.dest_block; + + case C1.min_value ... C1.max_value: + goto C1.dest_block; + + ...etc... + + case C[N - 1].min_value ... C[N - 1].max_value: + goto C[N - 1].dest_block; + } + + ``block``, ``expr``, ``default_block`` and ``cases`` must all be + non-NULL. + + ``expr`` must be of the same integer type as all of the ``min_value`` + and ``max_value`` within the cases. + + ``num_cases`` must be >= 0. + + The ranges of the cases must not overlap (or have duplicate + values). + + The API entrypoints relating to switch statements and cases: + + * :c:func:`gcc_jit_block_end_with_switch` + + * :c:func:`gcc_jit_case_as_object` + + * :c:func:`gcc_jit_context_new_case` + + were added in :ref:`LIBGCCJIT_ABI_3`; you can test for their presence + using + + .. code-block:: c + + #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS + + .. type:: gcc_jit_case + + A `gcc_jit_case` represents a case within a switch statement, and + is created within a particular :c:type:`gcc_jit_context` using + :c:func:`gcc_jit_context_new_case`. + + Each case expresses a multivalued range of integer values. You + can express single-valued cases by passing in the same value for + both `min_value` and `max_value`. + + .. function:: gcc_jit_case *\ + gcc_jit_context_new_case (gcc_jit_context *ctxt,\ + gcc_jit_rvalue *min_value,\ + gcc_jit_rvalue *max_value,\ + gcc_jit_block *dest_block) + + Create a new gcc_jit_case instance for use in a switch statement. + `min_value` and `max_value` must be constants of an integer type, + which must match that of the expression of the switch statement. + + `dest_block` must be within the same function as the switch + statement. + + .. function:: gcc_jit_object *\ + gcc_jit_case_as_object (gcc_jit_case *case_) + + Upcast from a case to an object. + + Here's an example of creating a switch statement: + + .. literalinclude:: ../../../testsuite/jit.dg/test-switch.c + :start-after: /* Quote from here in docs/topics/functions.rst. */ + :end-before: /* Quote up to here in docs/topics/functions.rst. */ + :language: c diff --git a/gcc/jit/docs/topics/index.rst b/gcc/jit/docs/topics/index.rst index 4ebb623de0..76b3d0b9b5 100644 --- a/gcc/jit/docs/topics/index.rst +++ b/gcc/jit/docs/topics/index.rst @@ -28,3 +28,4 @@ Topic Reference functions.rst locations.rst compilation.rst + compatibility.rst diff --git a/gcc/jit/docs/topics/locations.rst b/gcc/jit/docs/topics/locations.rst index 58a76b675f..e5e9273868 100644 --- a/gcc/jit/docs/topics/locations.rst +++ b/gcc/jit/docs/topics/locations.rst @@ -52,6 +52,10 @@ Source Locations Create a `gcc_jit_location` instance representing the given source location. + The parameter ``filename`` must be non-NULL. The call takes a copy of + the underlying string, so it is valid to pass in a pointer to an + on-stack buffer. + Faking it --------- If you don't have source code for your internal representation, but need diff --git a/gcc/jit/docs/topics/objects.rst b/gcc/jit/docs/topics/objects.rst index 3ae63097ed..85c783ca2b 100644 --- a/gcc/jit/docs/topics/objects.rst +++ b/gcc/jit/docs/topics/objects.rst @@ -47,6 +47,7 @@ looks like this:: +- gcc_jit_rvalue +- gcc_jit_lvalue +- gcc_jit_param + +- gcc_jit_case There are casting methods for upcasting from subclasses to parent classes. For example, :c:func:`gcc_jit_type_as_object`: diff --git a/gcc/jit/docs/topics/types.rst b/gcc/jit/docs/topics/types.rst index fa7aea677c..41fa40ef7d 100644 --- a/gcc/jit/docs/topics/types.rst +++ b/gcc/jit/docs/topics/types.rst @@ -180,6 +180,10 @@ You can model C `struct` types by creating :c:type:`gcc_jit_struct *` and Construct a new field, with the given type and name. + The parameter ``name`` must be non-NULL. The call takes a copy of the + underlying string, so it is valid to pass in a pointer to an on-stack + buffer. + .. function:: gcc_jit_object *\ gcc_jit_field_as_object (gcc_jit_field *field) @@ -194,6 +198,10 @@ You can model C `struct` types by creating :c:type:`gcc_jit_struct *` and Construct a new struct type, with the given name and fields. + The parameter ``name`` must be non-NULL. The call takes a copy of + the underlying string, so it is valid to pass in a pointer to an + on-stack buffer. + .. function:: gcc_jit_struct *\ gcc_jit_context_new_opaque_struct (gcc_jit_context *ctxt,\ gcc_jit_location *loc,\ @@ -204,6 +212,10 @@ You can model C `struct` types by creating :c:type:`gcc_jit_struct *` and size of the struct is not known), or later specified using :c:func:`gcc_jit_struct_set_fields`. + The parameter ``name`` must be non-NULL. The call takes a copy of + the underlying string, so it is valid to pass in a pointer to an + on-stack buffer. + .. function:: gcc_jit_type *\ gcc_jit_struct_as_type (gcc_jit_struct *struct_type) @@ -218,3 +230,22 @@ You can model C `struct` types by creating :c:type:`gcc_jit_struct *` and Populate the fields of a formerly-opaque struct type. This can only be called once on a given struct type. + +.. function:: gcc_jit_type *\ + gcc_jit_context_new_union_type (gcc_jit_context *ctxt,\ + gcc_jit_location *loc,\ + const char *name,\ + int num_fields,\ + gcc_jit_field **fields) + + Construct a new union type, with the given name and fields. + + The parameter ``name`` must be non-NULL. It is copied, so the input + buffer does not need to outlive the call. + + Example of use: + + .. literalinclude:: ../../../testsuite/jit.dg/test-accessing-union.c + :start-after: /* Quote from here in docs/topics/types.rst. */ + :end-before: /* Quote up to here in docs/topics/types.rst. */ + :language: c |