gcc/jit/docs/topics/asm.rst

   1 .. Copyright (C) 2020-2021 Free Software Foundation, Inc.
   2    Originally contributed by David Malcolm <dmalcolm@redhat.com>
   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    <http://www.gnu.org/licenses/>.
  17
  18 .. default-domain:: c
  19
  20 Using Assembly Language with libgccjit
  21 ======================================
  22
  23 libgccjit has some support for directly embedding assembler instructions.
  24 This is based on GCC's support for inline ``asm`` in C code, and the
  25 following assumes a familiarity with that functionality.  See
  26 `How to Use Inline Assembly Language in C Code <https://gcc.gnu.org/onlinedocs/gcc/Using-Assembly-Language-with-C.html>`_
  27 in GCC's documentation, the "Extended Asm" section in particular.
  28
  29 These entrypoints were added in :ref:`LIBGCCJIT_ABI_15`; you can test
  30 for their presence using
  31
  32    .. code-block:: c
  33
  34       #ifdef LIBGCCJIT_HAVE_ASM_STATEMENTS
  35
  36 Adding assembler instructions within a function
  37 ***********************************************
  38
  39 .. type:: gcc_jit_extended_asm
  40
  41    A `gcc_jit_extended_asm` represents an extended ``asm`` statement: a
  42    series of low-level instructions inside a function that convert inputs
  43    to outputs.
  44
  45    To avoid having an API entrypoint with a very large number of
  46    parameters, an extended ``asm`` statement is made in stages:
  47    an initial call to create the :type:`gcc_jit_extended_asm`,
  48    followed by calls to add operands and set other properties of the
  49    statement.
  50
  51    There are two API entrypoints for creating a :type:`gcc_jit_extended_asm`:
  52
  53    * :func:`gcc_jit_block_add_extended_asm` for an ``asm`` statement with
  54      no control flow, and
  55
  56    * :func:`gcc_jit_block_end_with_extended_asm_goto` for an ``asm goto``.
  57
  58    For example, to create the equivalent of:
  59
  60    .. literalinclude:: ../../../testsuite/jit.dg/test-asm.c
  61       :start-after: // Quote from here in docs/topics/asm.rst: example 1: C
  62       :end-before: // Quote up to here in docs/topics/asm.rst: example 1: C
  63       :language: c
  64
  65    the following API calls could be used:
  66
  67    .. literalinclude:: ../../../testsuite/jit.dg/test-asm.c
  68       :start-after: /* Quote from here in docs/topics/asm.rst: example 1: jit.  */
  69       :end-before: /* Quote up to here in docs/topics/asm.rst: example 1: jit.  */
  70       :language: c
  71
  72    .. warning::  When considering the numbering of operands within an
  73                  extended ``asm`` statement (e.g. the ``%0`` and ``%1``
  74                  above), the equivalent to the C syntax is followed i.e. all
  75                  output operands, then all input operands, regardless of
  76                  what order the calls to
  77                  :func:`gcc_jit_extended_asm_add_output_operand` and
  78                  :func:`gcc_jit_extended_asm_add_input_operand` were made in.
  79
  80    As in the C syntax, operands can be given symbolic names to avoid having
  81    to number them.  For example, to create the equivalent of:
  82
  83    .. literalinclude:: ../../../testsuite/jit.dg/test-asm.c
  84       :start-after: // Quote from here in docs/topics/asm.rst: example 2: C
  85       :end-before: // Quote up to here in docs/topics/asm.rst: example 2: C
  86       :language: c
  87
  88    the following API calls could be used:
  89
  90    .. literalinclude:: ../../../testsuite/jit.dg/test-asm.c
  91       :start-after: /* Quote from here in docs/topics/asm.rst: example 2: jit.  */
  92       :end-before: /* Quote up to here in docs/topics/asm.rst: example 2: jit.  */
  93       :language: c
  94
  95 .. function:: gcc_jit_extended_asm *\
  96               gcc_jit_block_add_extended_asm (gcc_jit_block *block,\
  97                                               gcc_jit_location *loc,\
  98                                               const char *asm_template)
  99
 100    Create a :type:`gcc_jit_extended_asm` for an extended ``asm`` statement
 101    with no control flow (i.e. without the ``goto`` qualifier).
 102
 103    The parameter ``asm_template`` corresponds to the `AssemblerTemplate`
 104    within C's extended ``asm`` syntax.  It must be non-NULL.  The call takes
 105    a copy of the underlying string, so it is valid to pass in a pointer to
 106    an on-stack buffer.
 107
 108 .. function:: gcc_jit_extended_asm *\
 109               gcc_jit_block_end_with_extended_asm_goto (gcc_jit_block *block,\
 110                                                         gcc_jit_location *loc,\
 111                                                         const char *asm_template,\
 112                                                         int num_goto_blocks,\
 113                                                         gcc_jit_block **goto_blocks,\
 114                                                         gcc_jit_block *fallthrough_block)
 115
 116    Create a :type:`gcc_jit_extended_asm` for an extended ``asm`` statement
 117    that may perform jumps, and use it to terminate the given block.
 118    This is equivalent to the ``goto`` qualifier in C's extended ``asm``
 119    syntax.
 120
 121    For example, to create the equivalent of:
 122
 123    .. literalinclude:: ../../../testsuite/jit.dg/test-asm.c
 124       :start-after: // Quote from here in docs/topics/asm.rst: example 3b: C
 125       :end-before: // Quote up to here in docs/topics/asm.rst: example 3b: C
 126       :language: c
 127
 128    the following API calls could be used:
 129
 130    .. literalinclude:: ../../../testsuite/jit.dg/test-asm.c
 131       :start-after: /* Quote from here in docs/topics/asm.rst: example 3: jit.  */
 132       :end-before: /* Quote up to here in docs/topics/asm.rst: example 3: jit.  */
 133       :language: c
 134
 135    here referencing a :type:`gcc_jit_block` named "carry".
 136
 137    ``num_goto_blocks`` must be >= 0.
 138
 139    ``goto_blocks`` must be non-NULL.  This corresponds to the ``GotoLabels``
 140    parameter within C's extended ``asm`` syntax.  The block names can be
 141    referenced within the assembler template.
 142
 143    ``fallthrough_block`` can be NULL.  If non-NULL, it specifies the block
 144    to fall through to after the statement.
 145
 146    .. note:: This is needed since each :type:`gcc_jit_block` must have a
 147              single exit point, as a basic block: you can't jump from the
 148              middle of a block.  A "goto" is implicitly added after the
 149              asm to handle the fallthrough case, which is equivalent to what
 150              would have happened in the C case.
 151
 152 .. function:: void\
 153               gcc_jit_extended_asm_set_volatile_flag (gcc_jit_extended_asm *ext_asm,\
 154                                                       int flag)
 155
 156    Set whether the :type:`gcc_jit_extended_asm` has side-effects, equivalent to the
 157    `volatile <https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html#Volatile>`_
 158    qualifier in C's extended asm syntax.
 159
 160    For example, to create the equivalent of:
 161
 162    .. code-block:: c
 163
 164       asm volatile ("rdtsc\n\t"    // Returns the time in EDX:EAX.
 165                      "shl $32, %%rdx\n\t"  // Shift the upper bits left.
 166                      "or %%rdx, %0"        // 'Or' in the lower bits.
 167                      : "=a" (msr)
 168                      :
 169                      : "rdx");
 170
 171    the following API calls could be used:
 172
 173    .. literalinclude:: ../../../testsuite/jit.dg/test-asm.c
 174       :start-after: /* Quote from here in docs/topics/asm.rst: example 4: jit.  */
 175       :end-before: /* Quote up to here in docs/topics/asm.rst: example 4: jit.  */
 176       :language: c
 177
 178    where the :type:`gcc_jit_extended_asm` is flagged as volatile.
 179
 180 .. function:: void\
 181               gcc_jit_extended_asm_set_inline_flag (gcc_jit_extended_asm *ext_asm,\
 182                                                     int flag)
 183
 184    Set the equivalent of the
 185    `inline <https://gcc.gnu.org/onlinedocs/gcc/Size-of-an-asm.html#Size-of-an-asm>`_
 186    qualifier in C's extended ``asm`` syntax.
 187
 188 .. function:: void\
 189               gcc_jit_extended_asm_add_output_operand (gcc_jit_extended_asm *ext_asm,\
 190                                                        const char *asm_symbolic_name,\
 191                                                        const char *constraint,\
 192                                                        gcc_jit_lvalue *dest)
 193
 194    Add an output operand to the extended ``asm`` statement.  See the
 195    `Output Operands <https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html#OutputOperands>`_
 196    section of the documentation of the C syntax.
 197
 198    ``asm_symbolic_name`` corresponds to the ``asmSymbolicName`` component of C's
 199    extended ``asm`` syntax.  It can be NULL.  If non-NULL it specifies the
 200    symbolic name for the operand.
 201
 202    ``constraint`` corresponds to the ``constraint`` component of C's extended
 203    ``asm`` syntax.  It must be non-NULL.
 204
 205    ``dest`` corresponds to the ``cvariablename`` component of C's extended
 206    ``asm`` syntax.  It must be non-NULL.
 207
 208    .. code-block:: c
 209
 210       // Example with a NULL symbolic name, the equivalent of:
 211       //   : "=r" (dst)
 212       gcc_jit_extended_asm_add_output_operand (ext_asm, NULL, "=r", dst);
 213
 214       // Example with a symbolic name ("aIndex"), the equivalent of:
 215       //   : [aIndex] "=r" (index)
 216       gcc_jit_extended_asm_add_output_operand (ext_asm, "aIndex", "=r", index);
 217
 218    This function can't be called on an ``asm goto`` as such instructions can't
 219    have outputs; see the
 220    `Goto Labels <https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html#GotoLabels>`_
 221    section of GCC's "Extended Asm" documentation.
 222
 223 .. function:: void\
 224               gcc_jit_extended_asm_add_input_operand (gcc_jit_extended_asm *ext_asm,\
 225                                                       const char *asm_symbolic_name,\
 226                                                       const char *constraint,\
 227                                                       gcc_jit_rvalue *src)
 228
 229    Add an input operand to the extended ``asm`` statement.  See the
 230    `Input Operands <https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html#InputOperands>`_
 231    section of the documentation of the C syntax.
 232
 233    ``asm_symbolic_name`` corresponds to the ``asmSymbolicName`` component of C's
 234    extended ``asm`` syntax.  It can be NULL.  If non-NULL it specifies the
 235    symbolic name for the operand.
 236
 237    ``constraint`` corresponds to the ``constraint`` component of C's extended
 238    ``asm`` syntax.  It must be non-NULL.
 239
 240    ``src`` corresponds to the ``cexpression`` component of C's extended
 241    ``asm`` syntax.  It must be non-NULL.
 242
 243    .. code-block:: c
 244
 245       // Example with a NULL symbolic name, the equivalent of:
 246       //   : "r" (src)
 247       gcc_jit_extended_asm_add_input_operand (ext_asm, NULL, "r",
 248                                               gcc_jit_lvalue_as_rvalue (src));
 249
 250       // Example with a symbolic name ("aMask"), the equivalent of:
 251       //   : [aMask] "r" (Mask)
 252       gcc_jit_extended_asm_add_input_operand (ext_asm, "aMask", "r",
 253                                               gcc_jit_lvalue_as_rvalue (mask));
 254
 255 .. function:: void\
 256               gcc_jit_extended_asm_add_clobber (gcc_jit_extended_asm *ext_asm,\
 257                                                 const char *victim)
 258
 259    Add `victim` to the list of registers clobbered by the extended ``asm``
 260    statement.  It must be non-NULL.  See the
 261    `Clobbers and Scratch Registers <https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html#Clobbers-and-Scratch-Registers#>`_
 262    section of the documentation of the C syntax.
 263
 264    Statements with multiple clobbers will require multiple calls, one per
 265    clobber.
 266
 267    For example:
 268
 269    .. code-block:: c
 270
 271      gcc_jit_extended_asm_add_clobber (ext_asm, "r0");
 272      gcc_jit_extended_asm_add_clobber (ext_asm, "cc");
 273      gcc_jit_extended_asm_add_clobber (ext_asm, "memory");
 274
 275 A :type:`gcc_jit_extended_asm` is a :type:`gcc_jit_object` "owned" by
 276 the block's context.  The following upcast is available:
 277
 278 .. function:: gcc_jit_object *\
 279               gcc_jit_extended_asm_as_object (gcc_jit_extended_asm *ext_asm)
 280
 281    Upcast from extended ``asm`` to object.
 282
 283
 284 Adding top-level assembler statements
 285 *************************************
 286
 287 In addition to creating extended ``asm`` instructions within a function,
 288 there is support for creating "top-level" assembler statements, outside
 289 of any function.
 290
 291 .. function:: void \
 292               gcc_jit_context_add_top_level_asm (gcc_jit_context *ctxt,\
 293                                                  gcc_jit_location *loc,\
 294                                                  const char *asm_stmts)
 295
 296    Create a set of top-level asm statements, analogous to those created
 297    by GCC's "basic" ``asm`` syntax in C at file scope.
 298
 299    For example, to create the equivalent of:
 300
 301    .. literalinclude:: ../../../testsuite/jit.dg/test-asm.c
 302       :start-after: // Quote from here in docs/topics/asm.rst: example 5: C
 303       :end-before: // Quote up to here in docs/topics/asm.rst: example 5: C
 304       :language: c
 305
 306    the following API calls could be used:
 307
 308    .. literalinclude:: ../../../testsuite/jit.dg/test-asm.c
 309       :start-after: /* Quote from here in docs/topics/asm.rst: example 5: jit.  */
 310       :end-before: /* Quote up to here in docs/topics/asm.rst: example 5: jit.  */
 311       :language: c