Update copyright years.

[thirdparty/gcc.git] / gcc / jit / docs / topics / expressions.rst

diff --git a/gcc/jit/docs/topics/expressions.rst b/gcc/jit/docs/topics/expressions.rst
index 49317b9d55a8be5d81c51fa5f9d60c5db8f204fc..db2f2ca2e9c6cb295a57dd83aad6d483777a4dd0 100644 (file)
--- a/gcc/jit/docs/topics/expressions.rst
+++ b/gcc/jit/docs/topics/expressions.rst
@@ -1,4 +1,4 @@
-.. Copyright (C) 2014-2015 Free Software Foundation, Inc.
+.. Copyright (C) 2014-2020 Free Software Foundation, Inc.
    Originally contributed by David Malcolm <dmalcolm@redhat.com>
 
    This is free software: you can redistribute it and/or modify it
@@ -84,7 +84,7 @@ Simple expressions
                                                     gcc_jit_type *numeric_type)
 
    Given a numeric type (integer or floating point), get the rvalue for
-   zero.  Essentially this is just a shortcut for:
+   one.  Essentially this is just a shortcut for:
 
    .. code-block:: c
 
@@ -122,6 +122,33 @@ 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.
+
+Vector expressions
+******************
+
+.. function:: gcc_jit_rvalue * \
+              gcc_jit_context_new_rvalue_from_vector (gcc_jit_context *ctxt, \
+                                                      gcc_jit_location *loc, \
+                                                      gcc_jit_type *vec_type, \
+                                                      size_t num_elements, \
+                                                      gcc_jit_rvalue **elements)
+
+   Build a vector rvalue from an array of elements.
+
+   "vec_type" should be a vector type, created using
+   :func:`gcc_jit_type_get_vector`.
+
+   "num_elements" should match that of the vector type.
+
+   This entrypoint was added in :ref:`LIBGCCJIT_ABI_10`; you can test for
+   its presence using
+
+   .. code-block:: c
+
+      #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_rvalue_from_vector
 
 Unary Operations
 ****************
@@ -406,6 +433,60 @@ Function calls
              printf_func,
              2, args));
 
+.. function:: gcc_jit_rvalue *\
+              gcc_jit_context_new_call_through_ptr (gcc_jit_context *ctxt,\
+                                                    gcc_jit_location *loc,\
+                                                    gcc_jit_rvalue *fn_ptr,\
+                                                    int numargs, \
+                                                    gcc_jit_rvalue **args)
+
+   Given an rvalue of function pointer type (e.g. from
+   :c:func:`gcc_jit_context_new_function_ptr_type`), and the given table of
+   argument rvalues, construct a call to the function pointer, with the
+   result as an rvalue.
+
+   .. note::
+
+      The same caveat as for :c:func:`gcc_jit_context_new_call` applies.
+
+.. function:: void\
+              gcc_jit_rvalue_set_bool_require_tail_call (gcc_jit_rvalue *call,\
+                                                         int require_tail_call)
+
+   Given an :c:type:`gcc_jit_rvalue *` for a call created through
+   :c:func:`gcc_jit_context_new_call` or
+   :c:func:`gcc_jit_context_new_call_through_ptr`, mark/clear the
+   call as needing tail-call optimization.  The optimizer will
+   attempt to optimize the call into a jump instruction; if it is
+   unable to do do, an error will be emitted.
+
+   This may be useful when implementing functions that use the
+   continuation-passing style (e.g. for functional programming
+   languages), in which every function "returns" by calling a
+   "continuation" function pointer.  This call must be
+   guaranteed to be implemented as a jump, otherwise the program
+   could consume an arbitrary amount of stack space as it executed.
+
+   This entrypoint was added in :ref:`LIBGCCJIT_ABI_6`; you can test for
+   its presence using
+
+   .. code-block:: c
+
+      #ifdef LIBGCCJIT_HAVE_gcc_jit_rvalue_set_bool_require_tail_call
+
+Function pointers
+*****************
+
+Function pointers can be obtained:
+
+  * from a :c:type:`gcc_jit_function` using
+    :c:func:`gcc_jit_function_get_address`, or
+
+  * from an existing function using
+    :c:func:`gcc_jit_context_new_rvalue_from_ptr`,
+    using a function pointer type obtained using
+    :c:func:`gcc_jit_context_new_function_ptr_type`.
+
 Type-coercion
 *************
 
@@ -466,6 +547,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`: