GCC

https://gcc.gnu.org/onlinedocs/gcc
Admin
GCC is the GNU Compiler Collection, a free and open-source compiler suite that supports multiple...
Tokens:1,668,999
Snippets:14,449
Trust Score:10
Update:8 hours ago
Show doc for...
Tokens:
Raw
### Example: Handling Retry and Fallback

Source: https://gcc.gnu.org/onlinedocs/gcc/x86-transactional-memory-intrinsics.html

Example code showing how to handle _XABORT_RETRY and a fallback path for other failures.

```APIDOC
## Example: Handling Retry and Fallback

### Description
Example code demonstrating the use of `_xbegin`, `_xend`, and the `_XABORT_RETRY` macro with a fallback path.

### Code
```c
#include <immintrin.h>

int n_tries, max_tries;
unsigned status = _XABORT_EXPLICIT;
...

for (n_tries = 0; n_tries < max_tries; n_tries++) 
  {
    status = _xbegin ();
    if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY))
      break;
  }
if (status == _XBEGIN_STARTED) 
  {
    ... transaction code...
    _xend ();
  } 
else 
  {
    ... non-transactional fallback path...
  }
```

### Remarks
In most cases, the transactional and non-transactional code must synchronize together to ensure consistency.
```

--------------------------------

### Example using define_enum and define_enum_attr

Source: https://gcc.gnu.org/onlinedocs/gccint/Defining-Attributes.html

Example that defines a processor enumeration and uses it for arch and tune attributes.

```lisp
(define_enum "processor" [
  model_a
  model_b
  …
])
(define_enum_attr "arch" "processor"
  (const (symbol_ref "target_arch")))
(define_enum_attr "tune" "processor"
  (const (symbol_ref "target_tune")))
```

--------------------------------

### MULTILIB_EXCEPTIONS example for ARM

Source: https://gcc.gnu.org/onlinedocs/gccint/Target-Fragment.html

Example of setting MULTILIB_EXCEPTIONS to exclude combinations that should not be built, such as ARM with both THUMB and hardware floating point.

```makefile
*mthumb/*mhard-float*
```

--------------------------------

### MULTILIB_REQUIRED example for ARMv7-M and ARMv7-R

Source: https://gcc.gnu.org/onlinedocs/gccint/Target-Fragment.html

Example of setting MULTILIB_REQUIRED to specify only the required multilib combinations, using the same syntax as MULTILIB_EXCEPTIONS.

```makefile
MULTILIB_REQUIRED =  mthumb/march=armv7-m
MULTILIB_REQUIRED += march=armv7-r/mfloat-abi=hard/mfpu=vfpv3-d16
```

--------------------------------

### Typical -foffload-options command line

Source: https://gcc.gnu.org/onlinedocs/gcc/OpenMP-and-OpenACC-Options.html

Shows how to pass options to all offloading targets and to specific targets using the -foffload-options=target-list=options form. The example passes -fno-math-errno and -ffinite-math-only to all targets, -latomic to nvptx-none, and -march=gfx906 to amdgcn-amdhsa.

```bash
-foffload-options='-fno-math-errno -ffinite-math-only' \
        -foffload-options=nvptx-none=-latomic
-foffload-options=amdgcn-amdhsa=-march=gfx906
```

--------------------------------

### define_bypass example

Source: https://gcc.gnu.org/onlinedocs/gccint/Processor-pipeline-description.html

Defines a bypass between instructions starting with 'cpu1_load_' or 'cpu1_store_' and those starting with 'cpu1_load_'. The guard is optional and can be a C function that returns zero to ignore the bypass.

```lisp
(define_bypass 1 "cpu1_load_*, cpu1_store_*" "cpu1_load_*")
```

--------------------------------

### Compile with --coverage and -fprofile-info-section, then inspect sections

Source: https://gcc.gnu.org/onlinedocs/gcc/Freestanding-Environments.html

Compiles main.c and app.c with coverage and profile info section, then uses objdump to show the .gcov_info section in app.o.

```bash
$ gcc --coverage -fprofile-info-section -c main.c
$ gcc --coverage -fprofile-info-section -c app.c
$ objdump -h app.o

app.o:     file format elf64-x86-64

Sections:
Idx Name          Size      VMA               LMA               File off  Algn
  0 .text         00000151  0000000000000000  0000000000000000  00000040  2**0
                  CONTENTS, ALLOC, LOAD, RELOC, READONLY, CODE
  1 .data         00000100  0000000000000000  0000000000000000  000001a0  2**5
                  CONTENTS, ALLOC, LOAD, RELOC, DATA
  2 .bss          00000040  0000000000000000  0000000000000000  000002a0  2**5
                  ALLOC
  3 .rodata       0000003c  0000000000000000  0000000000000000  000002a0  2**3
                  CONTENTS, ALLOC, LOAD, READONLY, DATA
  4 .gcov_info    00000008  0000000000000000  0000000000000000  000002e0  2**3
                  CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA
  5 .comment      0000004e  0000000000000000  0000000000000000  000002e8  2**0
                  CONTENTS, READONLY
  6 .note.GNU-stack 00000000  0000000000000000  0000000000000000  00000336  2**0
                  CONTENTS, READONLY
  7 .eh_frame     00000058  0000000000000000  0000000000000000  00000338  2**3
                  CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA
```

--------------------------------

### Parseable fix-it hint output

Source: https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Message-Formatting-Options.html

Example output of a fix-it hint in machine-parseable format, starting with the string "fix-it:". The location is expressed as a half-open range, counted in bytes starting at byte 1 for the initial column. In this example, bytes 3 through 20 of line 45 of "test.c" are to be replaced with the given string.

```plaintext
fix-it:"test.c":{45:3-45:21}:"gtk_widget_show_all"

```

--------------------------------

### PowerPC HTM low-level transaction example with __builtin_tbegin

Source: https://gcc.gnu.org/onlinedocs/gcc/PowerPC-Hardware-Transactional-Memory-Built-in-Functions.html

Example of using low-level HTM built-ins to start a transaction, abort if the lock is held, and fall back to locking on persistent failure or after retries. Requires including <htmintrin.h>.

```c
#include <htmintrin.h>

int num_retries = 10;

while (1)
  {
    if (__builtin_tbegin (0))
      {
        /* Transaction State Initiated.  */
        if (is_locked (lock))
          __builtin_tabort (0);
        ... transaction code...
        __builtin_tend (0);
        break;
      }
    else
      {
        /* Transaction State Failed.  Use locks if the transaction
           failure is "persistent" or we've tried too many times.  */
        if (num_retries-- <= 0
            || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ()))
          {
            acquire_lock (lock);
            ... non transactional fallback path...
            release_lock (lock);
            break;
          }
      }
  }
```

--------------------------------

### Explicit instantiation file for Foo

Source: https://gcc.gnu.org/onlinedocs/gcc/Template-Instantiation.html

Create small files like this for each needed instance to build a template instantiation library. Includes the header and implementation, then explicitly instantiates the class and operator.

```cpp
#include "Foo.h"
#include "Foo.cc"

template class Foo<int>;
template ostream& operator <<
                (ostream&, const Foo<int>&);
```

--------------------------------

### define_c_enum syntax example

Source: https://gcc.gnu.org/onlinedocs/gccint/Constant-Definitions.html

Shows the syntax for defining an enumeration with define_c_enum. The values are automatically assigned sequential numbers starting from 0, unless explicitly specified as in (value32 32).

```MD
(define_c_enum "name" [
  value0
  value1
  (value32 32)
  value33
  …
  valuen
])
```

--------------------------------

### Show option status with -Q and --help=target

Source: https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html

When -Q appears before --help=, the descriptive text is replaced with an indication of whether each option is enabled, disabled, or set to a specific value. This truncated example from the ARM port shows the output format.

```bash
  % gcc -Q -mabi=2 --help=target -c
  The following options are target specific:
  -mabi=                                2
  -mabort-on-noreturn                   [disabled]
  -mapcs                                [disabled]
```

--------------------------------

### symver attribute: multiple versions example

Source: https://gcc.gnu.org/onlinedocs/gcc/Common-Attributes.html

Defines multiple versions for a given symbol (starting from binutils 2.35). Creates symbol symver_foo_v1 which will be version VERS_2 and VERS_3 of foo.

```c
[[gnu::__symver__ ("foo@VERS_2"), gnu::__symver__ ("foo@VERS_3")]]
int symver_foo_v1 (void)
{
}
```

--------------------------------

### Display target-specific optimization options with --help=target,optimizers

Source: https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html

Combining classes with 'target' can work; this displays all target-specific optimization options.

```bash
--help=target,optimizers
```

--------------------------------

### Using __builtin_FUNCTION to get function name

Source: https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html

Shows how __builtin_FUNCTION can be used as a default argument to return the name of the calling function. The example prints a line similar to "file.c:123: foo: message" with the file name, line number, and function name.

```c
const char*
function (const char *func = __builtin_FUNCTION ())
{
  return func;
}

void foo (void)
{
  printf ("%s:%i: %s: message\n", file (), line (), function ());
}
```

--------------------------------

### callback_only attribute usage example

Source: https://gcc.gnu.org/onlinedocs/gcc/Common-Attributes.html

Annotates a function to specify the callback function index and argument indices. Here, foo calls bar(x, y) where bar is the first parameter, and arguments are passed in order (x, y). All indices start from 1; index 0 marks an argument not present or modified before the call.

```cpp
[[gnu::callback_only(1, 3, 2)]]
void foo(void (*bar)(int*, double*), double* y, int* x);
```

--------------------------------

### Array index designator example

Source: https://gcc.gnu.org/onlinedocs/gcc/Designated-Inits.html

Shows how to initialize specific array elements using [index] = value syntax. The example initializes indices 4 and 2, equivalent to a fully specified initializer.

```c
int a[6] = { [4] = 29, [2] = 15 };
```

```c
int a[6] = { 0, 0, 15, 0, 29, 0 };
```

--------------------------------

### genrecog with -I options

Source: https://gcc.gnu.org/onlinedocs/gccint/Including-Patterns.html

Command line example showing how to use the `-I` option to add directories to the search path for machine description files. Directories are searched in left-to-right order before the default directories.

```bash
genrecog -I/p1/abc/proc1 -I/p2/abcd/pro2 target.md
```

--------------------------------

### Pointer and array access in nested loop

Source: https://gcc.gnu.org/onlinedocs/gccint/Dependency-analysis.html

Example of a nested loop with a pointer access and an array access. The pointer access is represented as a one-dimensional access starting from the first location accessed in the loop, with access function {0, + 4B}_for2 relative to p + i. The array access functions are {i_init, + i_step}_for1 and {j_init, +, j_step}_for2 relative to a.

```c
for1 i
   for2 j
    *((int *)p + i + j) = a[i][j];
```

--------------------------------

### Basic gcov invocation example

Source: https://gcc.gnu.org/onlinedocs/gcc/Invoking-Gcov.html

Shows the basic steps to compile with --coverage, run the program, and invoke gcov. The output shows the file name, lines executed percentage, and the generated .gcov file.

```bash
$ g++ --coverage tmp.cpp -c
$ g++ --coverage tmp.o
$ a.out
$ gcov tmp.cpp -m
File 'tmp.cpp'
Lines executed:92.86% of 14
Creating 'tmp.cpp.gcov'
```

--------------------------------

### Example define_attr for type attribute

Source: https://gcc.gnu.org/onlinedocs/gccint/Defining-Attributes.html

Example definition of a 'type' attribute with a list of possible values.

```lisp
(define_attr "type" "branch,fp,load,store,arith" …)
```

--------------------------------

### remove-outfile spec function example

Source: https://gcc.gnu.org/onlinedocs/gccint/Spec-Files.html

Removes the first argument from the outfiles array. The example removes -lm.

```spec
%:remove-outfile(-lm)
```

--------------------------------

### asm goto example for i386

Source: https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html

Shows basic asm goto syntax for i386, jumping to a C label 'carry'. The asm has no outputs, two inputs, and uses the 'cc' clobber. The label is referenced by position '%l2'.

```c
asm goto (
    "btl %1, %0\n\t"
    "jc %l2"
    : /* No outputs. */
    : "r" (p1), "r" (p2) 
    : "cc" 
    : carry);

return 0;

carry:
return 1;
```

--------------------------------

### Compile and link with -flto

Source: https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html

Shows the recommended way to use link-time optimization: compile each source file with -flto and optimization options, then link with the same options. The first two commands save GIMPLE bytecode into the object files, and the final command merges them for interprocedural optimization.

```bash
gcc -c -O2 -flto foo.c
gcc -c -O2 -flto bar.c
gcc -o myprog -flto -O2 foo.o bar.o
```

--------------------------------

### Export plugin_is_GPL_compatible and plugin_init on Windows

Source: https://gcc.gnu.org/onlinedocs/gccint/Plugins-building.html

C/C++ code showing how to decorate the required symbols with __declspec(dllexport) on Windows to export them from the plugin library.

```cpp
#ifdef _WIN32
__declspec(dllexport)
#endif
int plugin_is_GPL_compatible;

#ifdef _WIN32
__declspec(dllexport)
#endif
int plugin_init (plugin_name_args *, plugin_gcc_version *)
```

--------------------------------

### FOR_EACH_EDGE macro usage example

Source: https://gcc.gnu.org/onlinedocs/gccint/Edges.html

Example of using the FOR_EACH_EDGE macro to iterate over successor edges of a basic block. The macro must not be used if an element might be removed during traversal, as elements would be missed. The example breaks when an EDGE_FALLTHRU edge is found.

```c
edge e;
edge_iterator ei;

FOR_EACH_EDGE (e, ei, bb->succs)
  {
     if (e->flags & EDGE_FALLTHRU)
       break;
  }
```

--------------------------------

### Simple i386 extended asm example

Source: https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html

Copies src to dst and adds 1 to dst using extended asm. Demonstrates output and input operands with constraints.

```c
int src = 1;
int dst;   

asm ("mov %1, %0\n\t"
    "add $1, %0"
    : "=r" (dst) 
    : "r" (src));

printf("%d\n", dst);
```

--------------------------------

### Sample plugin code that registers a new pass

Source: https://gcc.gnu.org/onlinedocs/gccint/Plugins-pass.html

Shows a plugin_init function that fills a register_pass_info object and calls register_callback with the PLUGIN_PASS_MANAGER_SETUP event to register a new pass. The ellipses indicate omitted code for filling the pass_info object.

```c
/* Sample plugin code that registers a new pass.  */
int
plugin_init (struct plugin_name_args *plugin_info,
             struct plugin_gcc_version *version)
{
  struct register_pass_info pass_info;

  ...

  /* Code to fill in the pass_info object with new pass information.  */

  ...

  /* Register the new pass.  */
  register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);

  ...
}
```

--------------------------------

### Using #pragma GCC diagnostic push and pop

Source: https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Pragmas.html

Demonstrates how to save and restore diagnostic state using push and pop. If a pop has no matching push, command-line options are restored. The example shows that diagnostics are issued based on the state at each line.

```C
#pragma GCC diagnostic error "-Wuninitialized"
  foo(a);                       /* error is given for this one */
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wuninitialized"
  foo(b);                       /* no diagnostic for this one */
#pragma GCC diagnostic pop
  foo(c);                       /* error is given for this one */
#pragma GCC diagnostic pop
  foo(d);                       /* depends on command-line options */
```

--------------------------------

### version-compare spec function example

Source: https://gcc.gnu.org/onlinedocs/gccint/Spec-Files.html

Adds -lmx if the -mmacosx-version-min switch is 10.3 or later. The example uses the >= comparison operator.

```spec
%:version-compare(>= 10.3 mmacosx-version-min= -lmx)
```

--------------------------------

### _xbegin

Source: https://gcc.gnu.org/onlinedocs/gcc/x86-transactional-memory-intrinsics.html

Starts an RTM transaction. Returns _XBEGIN_STARTED on success, or an abort code bit mask on failure.

```APIDOC
## _xbegin

### Description
Starts a Restricted Transactional Memory (RTM) transaction. Returns `_XBEGIN_STARTED` when the transaction started successfully. If the transaction aborts, all side effects are undone and an abort code encoded as a bit mask is returned.

### Function Signature
`unsigned _xbegin()`

### Return Value
- `_XBEGIN_STARTED` - Transaction started successfully (note: this is not 0, so the constant has to be explicitly tested).
- Abort code (bit mask) - Transaction aborted; use the `_XABORT_*` macros to interpret the status.

### Remarks
There is no guarantee that a memory transaction ever succeeds; suitable fallback code always needs to be supplied.
```

--------------------------------

### Enum-float conversion example

Source: https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Dialect-Options.html

Example that triggers -Wdeprecated-enum-float-conversion, enabled by default with -std=c++20. In pre-C++20 dialects, enable with -Wenum-conversion or -Wdeprecated.

```cpp
enum E1 { e };
enum E2 { f };
bool b = e <= 3.7;
```

--------------------------------

### Pragma with preprocessor expansion example

Source: https://gcc.gnu.org/onlinedocs/gccint/Plugins-attr.html

Shows a pragma that uses a preprocessor macro in its argument, demonstrating support for expansions when registered with c_register_pragma_with_expansion or c_register_pragma_with_expansion_and_data.

```c
#define NUMBER 10
#pragma GCCPLUGIN foothreshold (NUMBER)
```
Tokens:
Raw