+2015-07-01 David Malcolm <dmalcolm@redhat.com>
+
+ * docs/topics/contexts.rst (gcc_jit_context_set_bool_option):
+ Clarify lack of lifetime requirements on (const char *) parameter.
+ * docs/topics/expressions.rst
+ (gcc_jit_context_new_string_literal): Likewise.
+ (gcc_jit_context_new_global): Likewise.
+ * docs/topics/functions.rst (gcc_jit_context_new_param): Likewise.
+ (gcc_jit_context_new_function): Likewise.
+ (gcc_jit_function_new_block): Likewise.
+ (gcc_jit_block_add_comment): Likewise.
+ * docs/topics/locations.rst (gcc_jit_context_new_location):
+ Likewise.
+ * docs/topics/types.rst (gcc_jit_context_new_field): Likewise.
+ (gcc_jit_context_new_struct_type): Likewise.
+ * docs/_build/texinfo/libgccjit.texi: Regenerate.
+
2015-06-30 David Malcolm <dmalcolm@redhat.com>
* docs/cp/topics/functions.rst (Blocks): Add switch statements to
@copying
@quotation
-libgccjit 6.0.0 (experimental 20150630), June 30, 2015
+libgccjit 6.0.0 (experimental 20150701), July 01, 2015
David Malcolm
@deffn {C Type} enum gcc_jit_str_option
@end deffn
+The parameter @code{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:
@geindex GCC_JIT_STR_OPTION_PROGNAME (C macro)
@deffn {C Function} gcc_jit_field * gcc_jit_context_new_field (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*type, const char@w{ }*name)
Construct a new field, with the given type and name.
+
+The parameter @code{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.
@end deffn
@geindex gcc_jit_field_as_object (C function)
@quotation
Construct a new struct type, with the given name and fields.
+
+The parameter @code{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.
@end quotation
@end deffn
specifying the fields. The fields can be omitted (in which case the
size of the struct is not known), or later specified using
@pxref{85,,gcc_jit_struct_set_fields()}.
+
+The parameter @code{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.
@end deffn
@geindex gcc_jit_struct_as_type (C function)
Generate an rvalue for the given NIL-terminated string, of type
@code{GCC_JIT_TYPE_CONST_CHAR_PTR}.
+
+The parameter @code{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.
@end deffn
@node Unary Operations,Binary Operations,Simple expressions,Rvalues
Add a new global variable of the given type and name to the context.
+The parameter @code{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 @pxref{16,,gcc_jit_result}:
In preparation for creating a function, create a new parameter of the
given type and name.
+
+The parameter @code{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.
@end deffn
Parameters are lvalues, and thus are also rvalues (and objects), so the
same as GCC_JIT_FUNCTION_INTERNAL.
@end deffn
@end quotation
+
+The parameter @code{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.
@end deffn
@geindex gcc_jit_context_get_builtin_function (C function)
Create a new local variable within the function, of the given type and
name.
+
+The parameter @code{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.
@end deffn
@node Blocks,Statements,Functions,Creating and using functions
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.:
+
+@example
+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);
+ @}
+@end example
+
+@noindent
@end deffn
@geindex gcc_jit_block_as_object (C function)
and @pxref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE},
and thus may be of use when debugging how your project's internal
representation gets converted to the libgccjit IR.
+
+The parameter @code{text} must be non-NULL. It is copied, so the input
+buffer does not need to outlive the call. For example:
+
+@example
+char buf[100];
+snprintf (buf, sizeof (buf),
+ "op%i: %s",
+ pc, opcode_names[op->op_opcode]);
+gcc_jit_block_add_comment (block, loc, buf);
+@end example
+
+@noindent
@end deffn
@geindex gcc_jit_block_end_with_conditional (C function)
Create a @cite{gcc_jit_location} instance representing the given source
location.
+
+The parameter @code{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.
@end deffn
@menu
.. type:: enum gcc_jit_str_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
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
****************
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`:
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:
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)
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
------
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)
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,\
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
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)
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,\
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)
projects / gcc.git / commitdiff