git.ipfire.org Git - thirdparty/gcc.git/blob

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. _s-390-system-z-built-in-functions:
   7
   8 S/390 System z Built-in Functions
   9 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  10
  11 .. function:: int __builtin_tbegin (void*)
  12
  13   Generates the ``tbegin`` machine instruction starting a
  14   non-constrained hardware transaction.  If the parameter is non-NULL the
  15   memory area is used to store the transaction diagnostic buffer and
  16   will be passed as first operand to ``tbegin``.  This buffer can be
  17   defined using the ``struct __htm_tdb`` C struct defined in
  18   ``htmintrin.h`` and must reside on a double-word boundary.  The
  19   second tbegin operand is set to ``0xff0c``. This enables
  20   save/restore of all GPRs and disables aborts for FPR and AR
  21   manipulations inside the transaction body.  The condition code set by
  22   the tbegin instruction is returned as integer value.  The tbegin
  23   instruction by definition overwrites the content of all FPRs.  The
  24   compiler will generate code which saves and restores the FPRs.  For
  25   soft-float code it is recommended to used the ``*_nofloat``
  26   variant.  In order to prevent a TDB from being written it is required
  27   to pass a constant zero value as parameter.  Passing a zero value
  28   through a variable is not sufficient.  Although modifications of
  29   access registers inside the transaction will not trigger an
  30   transaction abort it is not supported to actually modify them.  Access
  31   registers do not get saved when entering a transaction. They will have
  32   undefined state when reaching the abort code.
  33
  34 Macros for the possible return codes of tbegin are defined in the
  35 ``htmintrin.h`` header file:
  36
  37 ``_HTM_TBEGIN_STARTED``
  38   ``tbegin`` has been executed as part of normal processing.  The
  39   transaction body is supposed to be executed.
  40
  41 ``_HTM_TBEGIN_INDETERMINATE``
  42   The transaction was aborted due to an indeterminate condition which
  43   might be persistent.
  44
  45 ``_HTM_TBEGIN_TRANSIENT``
  46   The transaction aborted due to a transient failure.  The transaction
  47   should be re-executed in that case.
  48
  49 ``_HTM_TBEGIN_PERSISTENT``
  50   The transaction aborted due to a persistent failure.  Re-execution
  51   under same circumstances will not be productive.
  52
  53 .. c:macro:: _HTM_FIRST_USER_ABORT_CODE
  54
  55   The ``_HTM_FIRST_USER_ABORT_CODE`` defined in ``htmintrin.h``
  56   specifies the first abort code which can be used for
  57   ``__builtin_tabort``.  Values below this threshold are reserved for
  58   machine use.
  59
  60 .. index:: struct __htm_tdb
  61
  62 Data type struct __htm_tdbThe ``struct __htm_tdb`` defined in ``htmintrin.h`` describes
  63 the structure of the transaction diagnostic block as specified in the
  64 Principles of Operation manual chapter 5-91.
  65
  66 .. function:: int __builtin_tbegin_nofloat (void*)
  67
  68   Same as ``__builtin_tbegin`` but without FPR saves and restores.
  69   Using this variant in code making use of FPRs will leave the FPRs in
  70   undefined state when entering the transaction abort handler code.
  71
  72 .. function:: int __builtin_tbegin_retry (void*, int)
  73
  74   In addition to ``__builtin_tbegin`` a loop for transient failures
  75   is generated.  If tbegin returns a condition code of 2 the transaction
  76   will be retried as often as specified in the second argument.  The
  77   perform processor assist instruction is used to tell the CPU about the
  78   number of fails so far.
  79
  80 .. function:: int __builtin_tbegin_retry_nofloat (void*, int)
  81
  82   Same as ``__builtin_tbegin_retry`` but without FPR saves and
  83   restores.  Using this variant in code making use of FPRs will leave
  84   the FPRs in undefined state when entering the transaction abort
  85   handler code.
  86
  87 .. function:: void __builtin_tbeginc (void)
  88
  89   Generates the ``tbeginc`` machine instruction starting a constrained
  90   hardware transaction.  The second operand is set to ``0xff08``.
  91
  92 .. function:: int __builtin_tend (void)
  93
  94   Generates the ``tend`` machine instruction finishing a transaction
  95   and making the changes visible to other threads.  The condition code
  96   generated by tend is returned as integer value.
  97
  98 .. function:: void __builtin_tabort (int)
  99
 100   Generates the ``tabort`` machine instruction with the specified
 101   abort code.  Abort codes from 0 through 255 are reserved and will
 102   result in an error message.
 103
 104 .. function:: void __builtin_tx_assist (int)
 105
 106   Generates the ``ppa rX,rY,1`` machine instruction.  Where the
 107   integer parameter is loaded into rX and a value of zero is loaded into
 108   rY.  The integer parameter specifies the number of times the
 109   transaction repeatedly aborted.
 110
 111 .. function:: int __builtin_tx_nesting_depth (void)
 112
 113   Generates the ``etnd`` machine instruction.  The current nesting
 114   depth is returned as integer value.  For a nesting depth of 0 the code
 115   is not executed as part of an transaction.
 116
 117 .. function:: void __builtin_non_tx_store (uint64_t *, uint64_t)
 118
 119   Generates the ``ntstg`` machine instruction.  The second argument
 120   is written to the first arguments location.  The store operation will
 121   not be rolled-back in case of an transaction abort.