diff options
Diffstat (limited to 'gcc/doc')
33 files changed, 3068 insertions, 1015 deletions
diff --git a/gcc/doc/analyzer.texi b/gcc/doc/analyzer.texi index 755db7c..87a2a40 100644 --- a/gcc/doc/analyzer.texi +++ b/gcc/doc/analyzer.texi @@ -432,7 +432,7 @@ binop_svalue (mult_expr, initial_svalue(‘size_t’, decl_region(frame_region(â @subsection Analyzer Paths We need to explain to the user what the problem is, and to persuade them -that there really is a problem. Hence having a @code{diagnostic_path} +that there really is a problem. Hence having a @code{diagnostics::paths::path} isn't just an incidental detail of the analyzer; it's required. Paths ought to be: @@ -491,7 +491,7 @@ and notes if it is infeasible. The above gives us a shortest feasible @code{exploded_path} through the @code{exploded_graph} (a list of @code{exploded_edge *}). We use this -@code{exploded_path} to build a @code{diagnostic_path} (a list of +@code{exploded_path} to build a @code{diagnostics::paths::path} (a list of @strong{events} for the diagnostic subsystem) - specifically a @code{checker_path}. @@ -619,6 +619,25 @@ python-xdot) @item @code{-fdump-analyzer-exploded-nodes-2} which dumps a @file{SRC.eg.txt} file containing the full @code{exploded_graph}. +@item @code{-fdiagnostics-add-output=experimental-html:show-state-diagrams=yes} +which writes out the diagnostics in HTML form, and generates SVG state +diagrams visualizing the state of memory at each event (inspired by the +"ddd" debugger). These can be seen by pressing 'j' and 'k' to single-step +forward and backward through events. Note that these SVG diagrams are +created from an intermediate SARIF directed graph representation generated from +@code{program_state} objects. The SARIF representation can be easier to +read - for example, rather than storing the contents of memory via byte +offsets, it uses fields for structs and element indexes for arrays, +recursively. However it is a different representation, and thus bugs could +be hidden by this transformation. Generating the SVG diagrams requires +an invocation of "dot" per event, so it noticeably slows down diagnostic +emission, hence the opt-in command-line flag. The SARIF and ``dot'' +representations can be seen by @code{__analyzer_dump_xml} and +@code{__analyzer_dump_dot} below (writing them to stderr), or by adding +@code{show-state-diagrams-sarif=yes} and +@code{show-state-diagrams-dot-src=yes} to the html sink, which shows +them within the generated HTML next to the generated SVG. + @end itemize Assuming that you have the @@ -688,6 +707,15 @@ extern void __analyzer_dump_capacity (const void *ptr); will emit a warning describing the capacity of the base region of the region pointed to by the 1st argument. +@item __analyzer_dump_dot +@smallexample +__analyzer_dump_dot (); +@end smallexample + +will dump GraphViz .dot source to stderr reaches the call in its +traversal of the source. This .dot source implements a diagram +describing the analyzer’s state. + @item __analyzer_dump_escaped @smallexample extern void __analyzer_dump_escaped (void); @@ -764,6 +792,14 @@ will emit a warning describing the state of the 2nd argument a name matching the 1st argument (which must be a string literal). This is for use when debugging, and may be of use in DejaGnu tests. +@item __analyzer_dump_sarif +@smallexample +__analyzer_dump_sarif (); +@end smallexample + +will dump the copious information about the analyzer's state each time it +reaches the call in its traversal of the source. + @item __analyzer_eval @smallexample __analyzer_eval (expr); diff --git a/gcc/doc/avr-mmcu.texi b/gcc/doc/avr-mmcu.texi index feb7725..5efcc81 100644 --- a/gcc/doc/avr-mmcu.texi +++ b/gcc/doc/avr-mmcu.texi @@ -50,15 +50,15 @@ @item @anchor{avrxmega2}avrxmega2 ``XMEGA'' devices with more than 8@tie{}KiB and up to 64@tie{}KiB of program memory. -@*@var{mcu}@tie{}= @code{atxmega8e5}, @code{atxmega16a4}, @code{atxmega16a4u}, @code{atxmega16c4}, @code{atxmega16d4}, @code{atxmega16e5}, @code{atxmega32a4}, @code{atxmega32a4u}, @code{atxmega32c3}, @code{atxmega32c4}, @code{atxmega32d3}, @code{atxmega32d4}, @code{atxmega32e5}, @code{avr64da28}, @code{avr64da32}, @code{avr64da48}, @code{avr64da64}, @code{avr64db28}, @code{avr64db32}, @code{avr64db48}, @code{avr64db64}, @code{avr64dd14}, @code{avr64dd20}, @code{avr64dd28}, @code{avr64dd32}, @code{avr64du28}, @code{avr64du32}, @code{avr64ea28}, @code{avr64ea32}, @code{avr64ea48}, @code{avr64sd28}, @code{avr64sd32}, @code{avr64sd48}. +@*@var{mcu}@tie{}= @code{atxmega8e5}, @code{atxmega16a4}, @code{atxmega16a4u}, @code{atxmega16c4}, @code{atxmega16d4}, @code{atxmega16e5}, @code{atxmega32a4}, @code{atxmega32a4u}, @code{atxmega32c3}, @code{atxmega32c4}, @code{atxmega32d3}, @code{atxmega32d4}, @code{atxmega32e5}, @code{avr64da28}, @code{avr64da28s}, @code{avr64da32}, @code{avr64da32s}, @code{avr64da48}, @code{avr64da48s}, @code{avr64da64}, @code{avr64da64s}, @code{avr64db28}, @code{avr64db32}, @code{avr64db48}, @code{avr64db64}, @code{avr64dd14}, @code{avr64dd20}, @code{avr64dd28}, @code{avr64dd32}, @code{avr64du28}, @code{avr64du32}, @code{avr64ea28}, @code{avr64ea32}, @code{avr64ea48}, @code{avr64sd28}, @code{avr64sd32}, @code{avr64sd48}. @item @anchor{avrxmega3}avrxmega3 ``XMEGA'' devices with up to 64@tie{}KiB of combined program memory and RAM, and with program memory visible in the RAM address space. -@*@var{mcu}@tie{}= @code{attiny202}, @code{attiny204}, @code{attiny212}, @code{attiny214}, @code{attiny402}, @code{attiny404}, @code{attiny406}, @code{attiny412}, @code{attiny414}, @code{attiny416}, @code{attiny416auto}, @code{attiny417}, @code{attiny424}, @code{attiny426}, @code{attiny427}, @code{attiny804}, @code{attiny806}, @code{attiny807}, @code{attiny814}, @code{attiny816}, @code{attiny817}, @code{attiny824}, @code{attiny826}, @code{attiny827}, @code{attiny1604}, @code{attiny1606}, @code{attiny1607}, @code{attiny1614}, @code{attiny1616}, @code{attiny1617}, @code{attiny1624}, @code{attiny1626}, @code{attiny1627}, @code{attiny3214}, @code{attiny3216}, @code{attiny3217}, @code{attiny3224}, @code{attiny3226}, @code{attiny3227}, @code{atmega808}, @code{atmega809}, @code{atmega1608}, @code{atmega1609}, @code{atmega3208}, @code{atmega3209}, @code{atmega4808}, @code{atmega4809}, @code{avr16dd14}, @code{avr16dd20}, @code{avr16dd28}, @code{avr16dd32}, @code{avr16du14}, @code{avr16du20}, @code{avr16du28}, @code{avr16du32}, @code{avr16ea28}, @code{avr16ea32}, @code{avr16ea48}, @code{avr16eb14}, @code{avr16eb20}, @code{avr16eb28}, @code{avr16eb32}, @code{avr32da28}, @code{avr32da32}, @code{avr32da48}, @code{avr32db28}, @code{avr32db32}, @code{avr32db48}, @code{avr32dd14}, @code{avr32dd20}, @code{avr32dd28}, @code{avr32dd32}, @code{avr32du14}, @code{avr32du20}, @code{avr32du28}, @code{avr32du32}, @code{avr32ea28}, @code{avr32ea32}, @code{avr32ea48}, @code{avr32sd20}, @code{avr32sd28}, @code{avr32sd32}. +@*@var{mcu}@tie{}= @code{attiny202}, @code{attiny204}, @code{attiny212}, @code{attiny214}, @code{attiny402}, @code{attiny404}, @code{attiny406}, @code{attiny412}, @code{attiny414}, @code{attiny416}, @code{attiny416auto}, @code{attiny417}, @code{attiny424}, @code{attiny426}, @code{attiny427}, @code{attiny804}, @code{attiny806}, @code{attiny807}, @code{attiny814}, @code{attiny816}, @code{attiny817}, @code{attiny824}, @code{attiny826}, @code{attiny827}, @code{attiny1604}, @code{attiny1606}, @code{attiny1607}, @code{attiny1614}, @code{attiny1616}, @code{attiny1617}, @code{attiny1624}, @code{attiny1626}, @code{attiny1627}, @code{attiny3214}, @code{attiny3216}, @code{attiny3217}, @code{attiny3224}, @code{attiny3226}, @code{attiny3227}, @code{atmega808}, @code{atmega809}, @code{atmega1608}, @code{atmega1609}, @code{atmega3208}, @code{atmega3209}, @code{atmega4808}, @code{atmega4809}, @code{avr16dd14}, @code{avr16dd20}, @code{avr16dd28}, @code{avr16dd32}, @code{avr16du14}, @code{avr16du20}, @code{avr16du28}, @code{avr16du32}, @code{avr16ea28}, @code{avr16ea32}, @code{avr16ea48}, @code{avr16eb14}, @code{avr16eb20}, @code{avr16eb28}, @code{avr16eb32}, @code{avr32da28}, @code{avr32da28s}, @code{avr32da32}, @code{avr32da32s}, @code{avr32da48}, @code{avr32da48s}, @code{avr32db28}, @code{avr32db32}, @code{avr32db48}, @code{avr32dd14}, @code{avr32dd20}, @code{avr32dd28}, @code{avr32dd32}, @code{avr32du14}, @code{avr32du20}, @code{avr32du28}, @code{avr32du32}, @code{avr32ea28}, @code{avr32ea32}, @code{avr32ea48}, @code{avr32sd20}, @code{avr32sd28}, @code{avr32sd32}. @item @anchor{avrxmega4}avrxmega4 ``XMEGA'' devices with more than 64@tie{}KiB and up to 128@tie{}KiB of program memory. -@*@var{mcu}@tie{}= @code{atxmega64a3}, @code{atxmega64a3u}, @code{atxmega64a4u}, @code{atxmega64b1}, @code{atxmega64b3}, @code{atxmega64c3}, @code{atxmega64d3}, @code{atxmega64d4}, @code{avr128da28}, @code{avr128da32}, @code{avr128da48}, @code{avr128da64}, @code{avr128db28}, @code{avr128db32}, @code{avr128db48}, @code{avr128db64}. +@*@var{mcu}@tie{}= @code{atxmega64a3}, @code{atxmega64a3u}, @code{atxmega64a4u}, @code{atxmega64b1}, @code{atxmega64b3}, @code{atxmega64c3}, @code{atxmega64d3}, @code{atxmega64d4}, @code{avr128da28}, @code{avr128da28s}, @code{avr128da32}, @code{avr128da32s}, @code{avr128da48}, @code{avr128da48s}, @code{avr128da64}, @code{avr128da64s}, @code{avr128db28}, @code{avr128db32}, @code{avr128db48}, @code{avr128db64}. @item @anchor{avrxmega5}avrxmega5 ``XMEGA'' devices with more than 64@tie{}KiB and up to 128@tie{}KiB of program memory and more than 64@tie{}KiB of RAM. diff --git a/gcc/doc/cpp.texi b/gcc/doc/cpp.texi index fc60792..cc1656f 100644 --- a/gcc/doc/cpp.texi +++ b/gcc/doc/cpp.texi @@ -3252,7 +3252,7 @@ helps people match the @samp{#endif} to the corresponding @samp{#ifdef}. Older programs sometimes put @var{MACRO} directly after the @samp{#endif} without enclosing it in a comment. This is invalid code according to the C standard. CPP accepts it with a warning. It -never affects which @samp{#ifndef} the @samp{#endif} matches. +never affects which @samp{#ifdef} the @samp{#endif} matches. @findex #ifndef Sometimes you wish to use some code if a macro is @emph{not} defined. diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 0978c4c..224d619 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -31,6 +31,7 @@ extensions, accepted by GCC in C90 mode and in C++. * Thread-Local:: Per-thread variables. * OpenMP:: Multiprocessing extensions. * OpenACC:: Extensions for offloading code to accelerator devices. +* _Countof:: The number of elements of arrays. * Inline:: Defining inline functions (as fast as macros). * Volatiles:: What constitutes an access to a volatile object. * Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler. @@ -2886,13 +2887,18 @@ my_memcpy (void *dest, const void *src, size_t len) @cindex @code{nonnull_if_nonzero} function attribute @item nonnull_if_nonzero @itemx nonnull_if_nonzero (@var{arg-index}, @var{arg2-index}) +@itemx nonnull_if_nonzero (@var{arg-index}, @var{arg2-index}, @var{arg3-index}) The @code{nonnull_if_nonzero} attribute is a conditional version of the -@code{nonnull} attribute. It has two arguments, the first argument +@code{nonnull} attribute. It has two or three arguments, the first argument shall be argument index of a pointer argument which must be in some cases non-null and the second argument shall be argument index of an integral argument (other than boolean). If the integral argument is zero, the pointer argument can be null, if it is non-zero, the pointer -argument must not be null. +argument must not be null. If three arguments are provided, the third +argument shall be argument index of another integral argument (other than +boolean) and the pointer argument can be null if either of the integral +arguments are zero and if both are non-zero, the pointer argument must not +be null. @smallexample extern void * @@ -2902,12 +2908,21 @@ extern void * my_memcpy2 (void *dest, const void *src, size_t len) __attribute__((nonnull_if_nonzero (1, 3), nonnull_if_nonzero (2, 3))); +extern size_t +my_fread (void *buf, size_t size, size_t count, FILE *stream) + __attribute__((nonnull (4), + nonnull_if_nonzero (1, 2, 3))); @end smallexample With these declarations, it is invalid to call @code{my_memcpy (NULL, NULL, 0);} or to -call @code{my_memcpy2 (NULL, NULL, 4);} but it is valid -to call @code{my_memcpy2 (NULL, NULL, 0);}. This attribute should be +call @code{my_memcpy2 (NULL, NULL, 4);} or to call +@code{my_fread(@var{buf}, 0, 0, NULL);} or to call +@code{my_fread(NULL, 1, 1, @var{stream});} but it is valid +to call @code{my_memcpy2 (NULL, NULL, 0);} or +@code{my_fread(NULL, 0, 0, @var{stream});} or +@code{my_fread(NULL, 0, 1, @var{stream});} or +@code{my_fread(NULL, 1, 0, @var{stream});}. This attribute should be used on declarations which have e.g.@: an exception for zero sizes, in which case null may be passed. @@ -3878,10 +3893,21 @@ behavior and permissible arguments are the same as for the command-line option @cindex @code{outline-atomics} function attribute, AArch64 @item outline-atomics +@itemx no-outline-atomics Enable or disable calls to out-of-line helpers to implement atomic operations. This corresponds to the behavior of the command-line options @option{-moutline-atomics} and @option{-mno-outline-atomics}. +@cindex @code{max-vectorization} function attribute, AArch64 +@item max-vectorization +@itemx no-max-vectorization +@code{max-vectorization} tells GCC's vectorizer to treat all vector +loops as being more profitable than the original scalar loops when +optimizing the current function. @code{no-max-vectorization} disables +this behavior. +This corresponds to the behavior of the command-line options +@option{-mmax-vectorization} and @option{-mno-max-vectorization}. + @cindex @code{indirect_return} function attribute, AArch64 @item indirect_return The @code{indirect_return} attribute can be applied to a function type @@ -5628,12 +5654,12 @@ You can specify the kind of interrupt to be handled by adding an optional parameter to the interrupt attribute like this: @smallexample -void f (void) __attribute__ ((interrupt ("user"))); +void f (void) __attribute__ ((interrupt ("supervisor"))); @end smallexample -Permissible values for this parameter are @code{user}, @code{supervisor}, -and @code{machine}. If there is no parameter, then it defaults to -@code{machine}. +Permissible values for this parameter are @code{supervisor}, +@code{machine}, and @code{rnmi}. If there is no parameter, then it +defaults to @code{machine}. @cindex @code{riscv_vector_cc} function attribute, RISC-V @item riscv_vector_cc @@ -6112,10 +6138,18 @@ pass arguments, unless it takes a variable number of arguments. @cindex @code{no_callee_saved_registers} function attribute, x86 @item no_callee_saved_registers Use this attribute to indicate that the specified function has no -callee-saved registers. That is, all registers can be used as scratch -registers. For example, this attribute can be used for a function -called from the interrupt handler assembly stub which will preserve -all registers and return from interrupt. +callee-saved registers. That is, all registers, except for stack and +frame pointers, can be used as scratch registers. For example, this +attribute can be used for a function called from the interrupt handler +assembly stub which will preserve all registers and return from +interrupt. + +@cindex @code{preserve_none} function attribute, x86 +@item preserve_none +This attribute is similar to @code{no_callee_saved_registers}, except +on x86-64, r12, r13, r14, r15, rdi and rsi registers are used for +integer parameter passing and this calling convention is subject to +change. @cindex @code{no_caller_saved_registers} function attribute, x86 @item no_caller_saved_registers @@ -6124,9 +6158,10 @@ caller-saved registers. That is, all registers are callee-saved. For example, this attribute can be used for a function called from an interrupt handler. The compiler generates proper function entry and exit sequences to save and restore any modified registers, except for -the EFLAGS register. Since GCC doesn't preserve SSE, MMX nor x87 -states, the GCC option @option{-mgeneral-regs-only} should be used to -compile functions with @code{no_caller_saved_registers} attribute. +the EFLAGS register. Since GCC doesn't preserve YMM nor ZMM registers, +@code{no_caller_saved_registers} attribute can't be used on functions +with AVX enabled. Note that MMX and x87 registers aren't preserved by +@code{no_caller_saved_registers} attribute. @cindex @code{interrupt} function attribute, x86 @item interrupt @@ -6684,23 +6719,10 @@ Enable/disable the generation of the USER_MSR instructions. Enable/disable the generation of the APX features, including EGPR, PUSH2POP2, NDD and PPX. -@cindex @code{target("avx10.1-256")} function attribute, x86 -@item avx10.1-256 -@itemx no-avx10.1-256 -Enable the generation of the AVX10.1 instructions with 256 bit support. -Disable the generation of the AVX10.1 instructions. - @cindex @code{target("avx10.1")} function attribute, x86 @item avx10.1 @itemx no-avx10.1 -Enable the generation of the AVX10.1 instructions with 512 bit support. -Disable the generation of the AVX10.1 instructions. - -@cindex @code{target("avx10.1-512")} function attribute, x86 -@item avx10.1-512 -@itemx no-avx10.1-512 -Enable the generation of the AVX10.1 instructions with 512 bit support. -Disable the generation of the AVX10.1 instructions. +Enable/Disable the generation of the AVX10.1 instructions. @cindex @code{target("avx10.2")} function attribute, x86 @item avx10.2 @@ -7336,7 +7358,7 @@ truncate the copy without appending the terminating @code{NUL} character. Using the attribute makes it possible to suppress the warning. However, when the array is declared with the attribute the call to @code{strlen} is diagnosed because when the array doesn't contain a @code{NUL}-terminated -string the call is undefined. To copy, compare, of search non-string +string the call is undefined. To copy, compare, or search non-string character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr}, and other functions that operate on arrays of bytes. In addition, calling @code{strnlen} and @code{strndup} with such arrays is safe @@ -9188,7 +9210,7 @@ NoError: @item unused This feature is intended for program-generated code that may contain unused labels, but which is compiled with @option{-Wall}. It is -not normally appropriate to use in it human-written code, though it +not normally appropriate to use it in human-written code, though it could be useful in cases where the code that jumps to the label is contained within an @code{#ifdef} conditional. @@ -10393,6 +10415,11 @@ loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows. @var{n} is an integer constant expression specifying the unrolling factor. The values of @math{0} and @math{1} block any unrolling of the loop. +If the loop was vectorized the unroll factor specified will be used to seed the +vectorizer unroll factor. Whether the loop is unrolled or not will be +determined by target costing. The resulting vectorized loop may still be +unrolled more in later passes depending on the target costing. + @end table @node Thread-Local @@ -10679,7 +10706,7 @@ and @samp{[[omp::sequence(...)]]} in C and C++, GCC needs to be invoked with the @option{-fopenmp} option. This option also arranges for automatic linking of the OpenMP runtime library. -@xref{,,,libgomp,GNU Offloading and Multi Processing Runtime Library}. +@xref{Top,,,libgomp,GNU Offloading and Multi Processing Runtime Library}. @xref{OpenMP and OpenACC Options}, for additional options useful with @option{-fopenmp}. @@ -10701,11 +10728,41 @@ To enable the processing of OpenACC directives @samp{#pragma acc} in C and C++, GCC needs to be invoked with the @option{-fopenacc} option. This option also arranges for automatic linking of the OpenACC runtime library. -@xref{,,,libgomp,GNU Offloading and Multi Processing Runtime Library}. +@xref{Top,,,libgomp,GNU Offloading and Multi Processing Runtime Library}. @xref{OpenMP and OpenACC Options}, for additional options useful with @option{-fopenacc}. +@node _Countof +@section Determining the Number of Elements of Arrays +@cindex _Countof +@cindex number of elements + +The keyword @code{_Countof} determines +the number of elements of an array operand. +Its syntax is similar to @code{sizeof}. +The operand must be +a parenthesized complete array type name +or an expression of such a type. +For example: + +@smallexample +int a[n]; +_Countof (a); // returns n +_Countof (int [7][3]); // returns 7 +@end smallexample + +The result of this operator is an integer constant expression, +unless the array has a variable number of elements. +The operand is only evaluated +if the array has a variable number of elements. +For example: + +@smallexample +_Countof (int [7][n++]); // integer constant expression +_Countof (int [n++][7]); // run-time value; n++ is evaluated +@end smallexample + @node Inline @section An Inline Function is As Fast As a Macro @cindex inline functions @@ -12585,6 +12642,7 @@ The list below describes the supported modifiers and their effects for RISC-V. @item @code{z} @tab Print ''@code{zero}'' instead of 0 if the operand is an immediate with a value of zero. @item @code{i} @tab Print the character ''@code{i}'' if the operand is an immediate. @item @code{N} @tab Print the register encoding as integer (0 - 31). +@item @code{H} @tab Print the name of the next register for integer. @end multitable @anchor{shOperandmodifiers} @@ -12717,6 +12775,7 @@ the two, as explained in the sections below. @menu * Global Register Variables:: Variables declared at global scope. * Local Register Variables:: Variables declared within a function. +* Hard Register Constraints:: Operands forced into specific machine registers. @end menu @node Global Register Variables @@ -12922,6 +12981,167 @@ with slightly different characteristics (@pxref{MIPS Coprocessors,, Defining coprocessor specifics for MIPS targets, gccint, GNU Compiler Collection (GCC) Internals}). +@node Hard Register Constraints +@subsubsection Hard Register Constraints + +Similar to register @code{asm} but still distinct, hard register constraints +are another way to force operands of inline @code{asm} into specific machine +registers. In contrast to register @code{asm} where a variable is bound to a +machine register, a hard register constraint binds an @code{asm} operand to a +machine register. Assume in the following that @code{r4} is a general-purpose +register, @code{f5} a floating-point register, and @code{v6} a vector register +for some target. + +@smallexample +int x; +int y __attribute__ ((vector_size (16))); +@dots{} +asm ("some instructions" + : "=@{r4@}" (x) + : "@{f5@}" (42.0), "@{v6@}" (y)); +@end smallexample + +For the inline @code{asm}, variable @code{x} is bound to register @code{r4}, +and @code{y} is loaded to @code{v6}. Furthermore, constant @code{42.0} is +loaded into floating-point register @code{f5}. + +A key difference between register @code{asm} and hard register constraints is +that the latter are specified at the point where they are supposed to +materialize, namely at inline @code{asm}, which may lead to more readable code. + +@subsubheading Usage + +Each input operand is loaded into the register specified by its corresponding +hard register constraint. Furthermore, each hard register must be used at most +once among an alternative for inputs. This renders hard register constraints +more strict compared to register @code{asm} where multiple inputs may share a +register as for example in + +@smallexample +int x; +register int y asm ("0") = @dots{}; +asm ("" : "=r" (x) : "r" (y), "r" (y)); +@end smallexample + +or even + +@smallexample +register int x asm ("0") = 42; +register int y asm ("0") = 24; +asm ("" : "=r" (x) : "r" (x), "r" (y)); +@end smallexample + +The analogue for hard register constraints is invalid in order to prevent +subtle bugs. + +Likewise, two outputs must not share a register among an alternative. That +means, the following example is invalid + +@smallexample +int x, y; +asm ("" : "=@{r4@}" (x), "=@{r4@}" (y)); // invalid +@end smallexample + +which also aligns with register @code{asm}. Despite that, each output must +refer to a distinct object if a hard register constraint is involved. For +example, in the following, object @code{x} is assigned two registers. + +@smallexample +int x; +asm ("" : "=r" (x), "=r" (x)); +@end smallexample + +This is not allowed for hard register constraints in order to prevent subtle +bugs. Even if only one output operand has a hard register constraint, the code +is rejected since the allocation for the object is still ambiguous. + +@smallexample +int x; +asm ("" : "=r" (x), "=@{1@}" (x)); // invalid +@end smallexample + +The type of an operand must be supported by the corresponding machine register. + +A hard register constraint may refer to any general, floating-point, or vector +register except a fixed register as e.g.@: the stack-pointer register. The set +of allowed registers is target dependent analogue to register @code{asm}. +Furthermore, the referenced register must be a valid register name of the +target. Note, on some targets, a single register may be referred to by +different names where each name specifies the length of the register. For +example, on x86_64 the register names @code{rcx}, @code{ecx}, and @code{cx} all +refer to the same register but in different sizes. If any of those names is +used for a hard register constraint, the actual size of a register is +determined by its corresponding operand. For example + +@smallexample +long x; +asm ("mov\t$42, %0" : "=@{ecx@}" (x)); +@end smallexample + +Although the hard register constraint refers to register @code{ecx}, the actual +register will be @code{rcx} since on x86_64 a @code{long} is 8 byte in total. +This aligns with register @code{asm} where you could have + +@smallexample +register long x asm ("ecx"); +@end smallexample + +@subsubheading Interaction with Register @code{asm} + +A mixture of both constructs as for example + +@smallexample +register int x asm ("r4") = 42; +int y; +asm ("" : "=@{r5@}" (y) : "r" (x)); +@end smallexample + +is valid. + +If an operand is a register @code{asm} and the corresponding constraint a hard +register, then both must refer to the same register. That means + +@smallexample +register int x asm ("r4"); +asm ("" : "=@{r4@}" (x)); +@end smallexample + +is valid and + +@smallexample +register int x asm ("r4"); +asm ("" : "=@{r5@}" (x)); // invalid +@end smallexample + +is invalid. + +Note, register @code{asm} may not only be clobbered by function calls but also +by inline @code{asm} in conjunction with hard register constraints. For +example, in the following + +@smallexample +register int x asm ("r5") = 42; +int y; +asm ("" : "=@{r5@}" (y)); +asm ("" : "+r" (x)); +@end smallexample + +variable @code{x} materializes before the very first inline @code{asm} which +writes to register @code{r5} and therefore clobbers @code{x} which in turn is +read by the subsequent inline @code{asm}. + +@subsubheading Limitations + +At the moment fixed registers are not supported for hard register constraints. +Thus, idioms like + +@smallexample +register void *x asm ("rsp"); +asm ("" : "=r" (x)); +@end smallexample + +are not supported for hard register constraints. This might be lifted. + @node Size of an asm @subsection Size of an @code{asm} @@ -14373,6 +14593,9 @@ a function call results in a compile-time error. @findex acoshf @findex acoshl @findex acosl +@findex acospi +@findex acospif +@findex acospil @findex alloca @findex asin @findex asinf @@ -14380,15 +14603,24 @@ a function call results in a compile-time error. @findex asinhf @findex asinhl @findex asinl +@findex asinpi +@findex asinpif +@findex asinpil @findex atan @findex atan2 @findex atan2f @findex atan2l +@findex atan2pi +@findex atan2pif +@findex atan2pil @findex atanf @findex atanh @findex atanhf @findex atanhl @findex atanl +@findex atanpi +@findex atanpif +@findex atanpil @findex bcmp @findex bzero @findex cabs @@ -14452,6 +14684,9 @@ a function call results in a compile-time error. @findex coshf @findex coshl @findex cosl +@findex cospi +@findex cospif +@findex cospil @findex cpow @findex cpowf @findex cpowl @@ -14687,6 +14922,9 @@ a function call results in a compile-time error. @findex sinhf @findex sinhl @findex sinl +@findex sinpi +@findex sinpif +@findex sinpil @findex snprintf @findex sprintf @findex sqrt @@ -14721,6 +14959,9 @@ a function call results in a compile-time error. @findex tanhf @findex tanhl @findex tanl +@findex tanpi +@findex tanpif +@findex tanpil @findex tgamma @findex tgammaf @findex tgammal @@ -14763,7 +15004,10 @@ a particular case, a call to the library function is emitted. @opindex std Outside strict ISO C mode (@option{-ansi}, @option{-std=c90}, @option{-std=c99} or @option{-std=c11}), the functions -@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, +@code{_exit}, @code{alloca}, @code{acospi}, @code{acospif}, @code{acospil}, +@code{asinpi}, @code{asinpif}, @code{asinpil}, @code{atan2pi}, @code{atan2pif}, +@code{atan2pil}, @code{atanpi}, @code{atanpif}, @code{atanpil}, @code{bcmp}, +@code{bzero}, @code{cospi}, @code{cospif}, @code{cospil}, @code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, @code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, @code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, @@ -14778,11 +15022,12 @@ Outside strict ISO C mode (@option{-ansi}, @option{-std=c90}, @code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32}, @code{signbitd64}, @code{signbitd128}, @code{significandf}, @code{significandl}, @code{significand}, @code{sincosf}, -@code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy}, -@code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp}, -@code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l}, -@code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and -@code{yn} +@code{sincosl}, @code{sincos}, @code{sinpif}, @code{sinpil}, @code{sinpi}, +@code{stpcpy}, @code{stpncpy}, @code{strcasecmp}, @code{strdup}, +@code{strfmon}, @code{strncasecmp}, @code{strndup}, @code{strnlen}, +@code{tanpif}, @code{tanpil}, @code{tanpi}, @code{toascii}, @code{y0f}, +@code{y0l}, @code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, +@code{ynl} and @code{yn} may be handled as built-in functions. All these functions have corresponding versions prefixed with @code{__builtin_}, which may be used even in strict C90 @@ -15439,7 +15684,7 @@ are 128-bit. Only supported on targets when 128-bit types are supported. Returns the calculated 8-bit bit-reversed CRC using the initial CRC (8-bit), data (8-bit) and the polynomial (8-bit). @var{crc} is the initial CRC, @var{data} is the data and -@var{poly} is the polynomial without leading 1. +@var{poly} is the polynomial without leading 1. @var{poly} is required to be a compile-time constant. Table-based or clmul-based CRC may be used for the calculation, depending on the target architecture. @enddefbuiltin @@ -15494,7 +15739,7 @@ is 32-bit. Returns the calculated 8-bit bit-forward CRC using the initial CRC (8-bit), data (8-bit) and the polynomial (8-bit). @var{crc} is the initial CRC, @var{data} is the data and -@var{poly} is the polynomial without leading 1. +@var{poly} is the polynomial without leading 1. @var{poly} is required to be a compile-time constant. Table-based or clmul-based CRC may be used for the calculation, depending on the target architecture. @enddefbuiltin @@ -17904,7 +18149,6 @@ instructions, but allow the compiler to schedule those calls. * Alpha Built-in Functions:: * ARC Built-in Functions:: * ARC SIMD Built-in Functions:: -* ARM iWMMXt Built-in Functions:: * ARM C Language Extensions (ACLE):: * ARM Floating Point Status and Control Intrinsics:: * ARM ARMv8-M Security Extensions:: @@ -18520,160 +18764,6 @@ _v4hi __builtin_arc_vaddsub4h (__v4hi, __v4hi); _v4hi __builtin_arc_vsubadd4h (__v4hi, __v4hi); @end example -@node ARM iWMMXt Built-in Functions -@subsection ARM iWMMXt Built-in Functions - -These built-in functions are available for the ARM family of -processors when the @option{-mcpu=iwmmxt} switch is used: - -@smallexample -typedef int v2si __attribute__ ((vector_size (8))); -typedef short v4hi __attribute__ ((vector_size (8))); -typedef char v8qi __attribute__ ((vector_size (8))); - -int __builtin_arm_getwcgr0 (void); -void __builtin_arm_setwcgr0 (int); -int __builtin_arm_getwcgr1 (void); -void __builtin_arm_setwcgr1 (int); -int __builtin_arm_getwcgr2 (void); -void __builtin_arm_setwcgr2 (int); -int __builtin_arm_getwcgr3 (void); -void __builtin_arm_setwcgr3 (int); -int __builtin_arm_textrmsb (v8qi, int); -int __builtin_arm_textrmsh (v4hi, int); -int __builtin_arm_textrmsw (v2si, int); -int __builtin_arm_textrmub (v8qi, int); -int __builtin_arm_textrmuh (v4hi, int); -int __builtin_arm_textrmuw (v2si, int); -v8qi __builtin_arm_tinsrb (v8qi, int, int); -v4hi __builtin_arm_tinsrh (v4hi, int, int); -v2si __builtin_arm_tinsrw (v2si, int, int); -long long __builtin_arm_tmia (long long, int, int); -long long __builtin_arm_tmiabb (long long, int, int); -long long __builtin_arm_tmiabt (long long, int, int); -long long __builtin_arm_tmiaph (long long, int, int); -long long __builtin_arm_tmiatb (long long, int, int); -long long __builtin_arm_tmiatt (long long, int, int); -int __builtin_arm_tmovmskb (v8qi); -int __builtin_arm_tmovmskh (v4hi); -int __builtin_arm_tmovmskw (v2si); -long long __builtin_arm_waccb (v8qi); -long long __builtin_arm_wacch (v4hi); -long long __builtin_arm_waccw (v2si); -v8qi __builtin_arm_waddb (v8qi, v8qi); -v8qi __builtin_arm_waddbss (v8qi, v8qi); -v8qi __builtin_arm_waddbus (v8qi, v8qi); -v4hi __builtin_arm_waddh (v4hi, v4hi); -v4hi __builtin_arm_waddhss (v4hi, v4hi); -v4hi __builtin_arm_waddhus (v4hi, v4hi); -v2si __builtin_arm_waddw (v2si, v2si); -v2si __builtin_arm_waddwss (v2si, v2si); -v2si __builtin_arm_waddwus (v2si, v2si); -v8qi __builtin_arm_walign (v8qi, v8qi, int); -long long __builtin_arm_wand(long long, long long); -long long __builtin_arm_wandn (long long, long long); -v8qi __builtin_arm_wavg2b (v8qi, v8qi); -v8qi __builtin_arm_wavg2br (v8qi, v8qi); -v4hi __builtin_arm_wavg2h (v4hi, v4hi); -v4hi __builtin_arm_wavg2hr (v4hi, v4hi); -v8qi __builtin_arm_wcmpeqb (v8qi, v8qi); -v4hi __builtin_arm_wcmpeqh (v4hi, v4hi); -v2si __builtin_arm_wcmpeqw (v2si, v2si); -v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi); -v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi); -v2si __builtin_arm_wcmpgtsw (v2si, v2si); -v8qi __builtin_arm_wcmpgtub (v8qi, v8qi); -v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi); -v2si __builtin_arm_wcmpgtuw (v2si, v2si); -long long __builtin_arm_wmacs (long long, v4hi, v4hi); -long long __builtin_arm_wmacsz (v4hi, v4hi); -long long __builtin_arm_wmacu (long long, v4hi, v4hi); -long long __builtin_arm_wmacuz (v4hi, v4hi); -v4hi __builtin_arm_wmadds (v4hi, v4hi); -v4hi __builtin_arm_wmaddu (v4hi, v4hi); -v8qi __builtin_arm_wmaxsb (v8qi, v8qi); -v4hi __builtin_arm_wmaxsh (v4hi, v4hi); -v2si __builtin_arm_wmaxsw (v2si, v2si); -v8qi __builtin_arm_wmaxub (v8qi, v8qi); -v4hi __builtin_arm_wmaxuh (v4hi, v4hi); -v2si __builtin_arm_wmaxuw (v2si, v2si); -v8qi __builtin_arm_wminsb (v8qi, v8qi); -v4hi __builtin_arm_wminsh (v4hi, v4hi); -v2si __builtin_arm_wminsw (v2si, v2si); -v8qi __builtin_arm_wminub (v8qi, v8qi); -v4hi __builtin_arm_wminuh (v4hi, v4hi); -v2si __builtin_arm_wminuw (v2si, v2si); -v4hi __builtin_arm_wmulsm (v4hi, v4hi); -v4hi __builtin_arm_wmulul (v4hi, v4hi); -v4hi __builtin_arm_wmulum (v4hi, v4hi); -long long __builtin_arm_wor (long long, long long); -v2si __builtin_arm_wpackdss (long long, long long); -v2si __builtin_arm_wpackdus (long long, long long); -v8qi __builtin_arm_wpackhss (v4hi, v4hi); -v8qi __builtin_arm_wpackhus (v4hi, v4hi); -v4hi __builtin_arm_wpackwss (v2si, v2si); -v4hi __builtin_arm_wpackwus (v2si, v2si); -long long __builtin_arm_wrord (long long, long long); -long long __builtin_arm_wrordi (long long, int); -v4hi __builtin_arm_wrorh (v4hi, long long); -v4hi __builtin_arm_wrorhi (v4hi, int); -v2si __builtin_arm_wrorw (v2si, long long); -v2si __builtin_arm_wrorwi (v2si, int); -v2si __builtin_arm_wsadb (v2si, v8qi, v8qi); -v2si __builtin_arm_wsadbz (v8qi, v8qi); -v2si __builtin_arm_wsadh (v2si, v4hi, v4hi); -v2si __builtin_arm_wsadhz (v4hi, v4hi); -v4hi __builtin_arm_wshufh (v4hi, int); -long long __builtin_arm_wslld (long long, long long); -long long __builtin_arm_wslldi (long long, int); -v4hi __builtin_arm_wsllh (v4hi, long long); -v4hi __builtin_arm_wsllhi (v4hi, int); -v2si __builtin_arm_wsllw (v2si, long long); -v2si __builtin_arm_wsllwi (v2si, int); -long long __builtin_arm_wsrad (long long, long long); -long long __builtin_arm_wsradi (long long, int); -v4hi __builtin_arm_wsrah (v4hi, long long); -v4hi __builtin_arm_wsrahi (v4hi, int); -v2si __builtin_arm_wsraw (v2si, long long); -v2si __builtin_arm_wsrawi (v2si, int); -long long __builtin_arm_wsrld (long long, long long); -long long __builtin_arm_wsrldi (long long, int); -v4hi __builtin_arm_wsrlh (v4hi, long long); -v4hi __builtin_arm_wsrlhi (v4hi, int); -v2si __builtin_arm_wsrlw (v2si, long long); -v2si __builtin_arm_wsrlwi (v2si, int); -v8qi __builtin_arm_wsubb (v8qi, v8qi); -v8qi __builtin_arm_wsubbss (v8qi, v8qi); -v8qi __builtin_arm_wsubbus (v8qi, v8qi); -v4hi __builtin_arm_wsubh (v4hi, v4hi); -v4hi __builtin_arm_wsubhss (v4hi, v4hi); -v4hi __builtin_arm_wsubhus (v4hi, v4hi); -v2si __builtin_arm_wsubw (v2si, v2si); -v2si __builtin_arm_wsubwss (v2si, v2si); -v2si __builtin_arm_wsubwus (v2si, v2si); -v4hi __builtin_arm_wunpckehsb (v8qi); -v2si __builtin_arm_wunpckehsh (v4hi); -long long __builtin_arm_wunpckehsw (v2si); -v4hi __builtin_arm_wunpckehub (v8qi); -v2si __builtin_arm_wunpckehuh (v4hi); -long long __builtin_arm_wunpckehuw (v2si); -v4hi __builtin_arm_wunpckelsb (v8qi); -v2si __builtin_arm_wunpckelsh (v4hi); -long long __builtin_arm_wunpckelsw (v2si); -v4hi __builtin_arm_wunpckelub (v8qi); -v2si __builtin_arm_wunpckeluh (v4hi); -long long __builtin_arm_wunpckeluw (v2si); -v8qi __builtin_arm_wunpckihb (v8qi, v8qi); -v4hi __builtin_arm_wunpckihh (v4hi, v4hi); -v2si __builtin_arm_wunpckihw (v2si, v2si); -v8qi __builtin_arm_wunpckilb (v8qi, v8qi); -v4hi __builtin_arm_wunpckilh (v4hi, v4hi); -v2si __builtin_arm_wunpckilw (v2si, v2si); -long long __builtin_arm_wxor (long long, long long); -long long __builtin_arm_wzero (); -@end smallexample - - @node ARM C Language Extensions (ACLE) @subsection ARM C Language Extensions (ACLE) diff --git a/gcc/doc/gcov.texi b/gcc/doc/gcov.texi index 8bf87a2..ecf147a 100644 --- a/gcc/doc/gcov.texi +++ b/gcc/doc/gcov.texi @@ -1077,7 +1077,7 @@ condition 1 not covered (true) -: 12:@} @end smallexample -@anchor {gcov prime paths example} +@anchor{gcov prime paths example} When you compile with @option{--coverage -fpath-coverage} and use the option @option{-e} your output looks like this: diff --git a/gcc/doc/gm2.texi b/gcc/doc/gm2.texi index cb52e8c..9bd0f0d 100644 --- a/gcc/doc/gm2.texi +++ b/gcc/doc/gm2.texi @@ -540,6 +540,9 @@ lines compiled. @item -fm2-strict-type experimental flag to turn on the new strict type checker. +@item -fm2-strict-type-reason +provides more detail why the types are incompatible. + @item -fm2-whole-program compile all implementation modules and program module at once. Notice that you need to take care if you are compiling different dialect @@ -1495,7 +1498,7 @@ from @samp{bad} will cause an overflow to @samp{foo}. If we compile the code with the following options: @example -$ gm2 -g -fsoft-check-all -O2 -c assignvalue.mod +$ gm2 -g -fsoft-check-all -O2 -fm2-plugin -c assignvalue.mod assignvalue.mod:16:0:inevitable that this error will occur at run time, assignment will result in an overflow @end example diff --git a/gcc/doc/implement-c.texi b/gcc/doc/implement-c.texi index a942a12..8f0c2ff 100644 --- a/gcc/doc/implement-c.texi +++ b/gcc/doc/implement-c.texi @@ -10,8 +10,8 @@ A conforming implementation of ISO C is required to document its choice of behavior in each of the areas that are designated ``implementation defined''. The following lists all such areas, along with the section numbers from the ISO/IEC 9899:1990, ISO/IEC -9899:1999 and ISO/IEC 9899:2011 standards. Some areas are only -implementation-defined in one version of the standard. +9899:1999, ISO/IEC 9899:2011 and ISO/IEC 9899:2024 standards. Some +areas are only implementation-defined in one version of the standard. Some choices depend on the externally determined ABI for the platform (including standard character encodings) which GCC follows; these are @@ -30,10 +30,12 @@ a freestanding environment); refer to their documentation for details. * Characters implementation:: * Integers implementation:: * Floating point implementation:: +* Constant expressions implementation:: * Arrays and pointers implementation:: * Hints implementation:: * Structures unions enumerations and bit-fields implementation:: * Qualifiers implementation:: +* Types implementation:: * Declarators implementation:: * Statements implementation:: * Preprocessing directives implementation:: @@ -47,15 +49,15 @@ a freestanding environment); refer to their documentation for details. @itemize @bullet @item -@cite{How a diagnostic is identified (C90 3.7, C99 and C11 3.10, C90, -C99 and C11 5.1.1.3).} +@cite{How a diagnostic is identified (C90 3.7, C99 and C11 3.10, C23 +3.13, C90, C99 and C11 5.1.1.3, C23 5.2.1.3).} Diagnostics consist of all the output sent to stderr by GCC@. @item @cite{Whether each nonempty sequence of white-space characters other than new-line is retained or replaced by one space character in translation -phase 3 (C90, C99 and C11 5.1.1.2).} +phase 3 (C90, C99 and C11 5.1.1.2, C23 5.2.1.2).} @xref{Implementation-defined behavior, , Implementation-defined behavior, cpp, The C Preprocessor}. @@ -72,7 +74,7 @@ of the C library, and are not defined by GCC itself. @item @cite{The mapping between physical source file multibyte characters and the source character set in translation phase 1 (C90, C99 and C11 -5.1.1.2).} +5.1.1.2, C23 5.2.1.2).} @xref{Implementation-defined behavior, , Implementation-defined behavior, cpp, The C Preprocessor}. @@ -85,14 +87,16 @@ behavior, cpp, The C Preprocessor}. @itemize @bullet @item @cite{Which additional multibyte characters may appear in identifiers -and their correspondence to universal character names (C99 and C11 6.4.2).} +and their correspondence to universal character names (C99 and C11 +6.4.2, C23 6.4.3).} @xref{Implementation-defined behavior, , Implementation-defined behavior, cpp, The C Preprocessor}. @item @cite{The number of significant initial characters in an identifier -(C90 6.1.2, C90, C99 and C11 5.2.4.1, C99 and C11 6.4.2).} +(C90 6.1.2, C90, C99 and C11 5.2.4.1, C23 5.3.5.2, C99 and C11 6.4.2, +C23 6.4.3).} For internal names, all characters are significant. For external names, the number of significant characters are defined by the linker; for @@ -102,7 +106,7 @@ almost all targets, all characters are significant. @cite{Whether case distinctions are significant in an identifier with external linkage (C90 6.1.2).} -This is a property of the linker. C99 and C11 require that case distinctions +This is a property of the linker. C99 and later require that case distinctions are always significant in identifiers with external linkage and systems without this property are not supported by GCC@. @@ -113,34 +117,35 @@ systems without this property are not supported by GCC@. @itemize @bullet @item -@cite{The number of bits in a byte (C90 3.4, C99 and C11 3.6).} +@cite{The number of bits in a byte (C90 3.4, C99 and C11 3.6, C23 3.7).} Determined by ABI@. @item @cite{The values of the members of the execution character set (C90, -C99 and C11 5.2.1).} +C99 and C11 5.2.1, C23 5.3.1).} Determined by ABI@. @item @cite{The unique value of the member of the execution character set produced for each of the standard alphabetic escape sequences (C90, C99 and C11 -5.2.2).} +5.2.2, C23 5.3.3).} Determined by ABI@. @item @cite{The value of a @code{char} object into which has been stored any character other than a member of the basic execution character set -(C90 6.1.2.5, C99 and C11 6.2.5).} +(C90 6.1.2.5, C99, C11 and C23 6.2.5).} Determined by ABI@. @item @cite{Which of @code{signed char} or @code{unsigned char} has the same range, representation, and behavior as ``plain'' @code{char} (C90 -6.1.2.5, C90 6.2.1.1, C99 and C11 6.2.5, C99 and C11 6.3.1.1).} +6.1.2.5, C90 6.2.1.1, C99, C11 and C23 6.2.5, C99 and C11 6.3.1.1, C23 +6.3.2.1).} @opindex fsigned-char @opindex funsigned-char @@ -149,16 +154,32 @@ Determined by ABI@. The options @option{-funsigned-char} and Options Controlling C Dialect}. @item +@cite{The literal encoding, which maps of the characters of the +execution character set to the values in a character constant or +string literal (C23 6.2.9, C23 6.4.5.5).} + +Determined by ABI@. + +@item +@cite{The wide literal encoding, of the characters of the execution +character set to the values in a @code{wchar_t} character constant or +@code{wchar_t} string literal (C23 6.2.9, C23 6.4.5.5).} + +Determined by ABI@. + +@item @cite{The mapping of members of the source character set (in character constants and string literals) to members of the execution character -set (C90 6.1.3.4, C99 and C11 6.4.4.4, C90, C99 and C11 5.1.1.2).} +set (C90 6.1.3.4, C99 and C11 6.4.4.4, C23 6.4.5.5, C90, C99 and C11 +5.1.1.2, C23 5.2.1.2).} Determined by ABI@. @item @cite{The value of an integer character constant containing more than one character or containing a character or escape sequence that does not map -to a single-byte execution character (C90 6.1.3.4, C99 and C11 6.4.4.4).} +to a single-byte execution character (C90 6.1.3.4, C99 and C11 +6.4.4.4, C23 6.4.5.5).} @xref{Implementation-defined behavior, , Implementation-defined behavior, cpp, The C Preprocessor}. @@ -169,7 +190,7 @@ multibyte character or a single multibyte character that maps to multiple members of the extended execution character set, or containing a multibyte character or escape sequence not represented in the extended execution character set (C90 6.1.3.4, C99 and C11 -6.4.4.4).} +6.4.4.4, C23 6.4.5.5).} @xref{Implementation-defined behavior, , Implementation-defined behavior, cpp, The C Preprocessor}. @@ -178,7 +199,7 @@ behavior, cpp, The C Preprocessor}. @cite{The current locale used to convert a wide character constant consisting of a single multibyte character that maps to a member of the extended execution character set into a corresponding wide character code (C90 -6.1.3.4, C99 and C11 6.4.4.4).} +6.1.3.4, C99 and C11 6.4.4.4, C23 6.4.5.5).} @xref{Implementation-defined behavior, , Implementation-defined behavior, cpp, The C Preprocessor}. @@ -192,7 +213,7 @@ Such tokens may not be concatenated. @item @cite{The current locale used to convert a wide string literal into -corresponding wide character codes (C90 6.1.4, C99 and C11 6.4.5).} +corresponding wide character codes (C90 6.1.4, C99 and C11 6.4.5, C23 6.4.6).} @xref{Implementation-defined behavior, , Implementation-defined behavior, cpp, The C Preprocessor}. @@ -200,7 +221,7 @@ behavior, cpp, The C Preprocessor}. @item @cite{The value of a string literal containing a multibyte character or escape sequence not represented in the execution character set (C90 6.1.4, -C99 and C11 6.4.5).} +C99 and C11 6.4.5, C23 6.4.6).} @xref{Implementation-defined behavior, , Implementation-defined behavior, cpp, The C Preprocessor}. @@ -209,7 +230,7 @@ behavior, cpp, The C Preprocessor}. @cite{The encoding of any of @code{wchar_t}, @code{char16_t}, and @code{char32_t} where the corresponding standard encoding macro (@code{__STDC_ISO_10646__}, @code{__STDC_UTF_16__}, or -@code{__STDC_UTF_32__}) is not defined (C11 6.10.8.2).} +@code{__STDC_UTF_32__}) is not defined (C11 6.10.8.2, C23 6.10.10.3).} @xref{Implementation-defined behavior, , Implementation-defined behavior, cpp, The C Preprocessor}. @code{char16_t} and @@ -223,8 +244,8 @@ respectively. @itemize @bullet @item -@cite{Any extended integer types that exist in the implementation (C99 -and C11 6.2.5).} +@cite{Any extended integer types that exist in the implementation (C99, +C11 and C23 6.2.5).} GCC does not support any extended integer types. @c The __mode__ attribute might create types of precisions not @@ -240,11 +261,12 @@ two's complement, or one's complement, and whether the extraordinary value is a trap representation or an ordinary value (C99 and C11 6.2.6.2).} GCC supports only two's complement integer types, and all bit patterns -are ordinary values. +are ordinary values. C23 requires signed integer types to be two's +complement. @item @cite{The rank of any extended integer type relative to another extended -integer type with the same precision (C99 and C11 6.3.1.1).} +integer type with the same precision (C99 and C11 6.3.1.1, C23 6.3.2.1).} GCC does not support any extended integer types. @c If it did, there would only be one of each precision and signedness. @@ -252,14 +274,14 @@ GCC does not support any extended integer types. @item @cite{The result of, or the signal raised by, converting an integer to a signed integer type when the value cannot be represented in an object of -that type (C90 6.2.1.2, C99 and C11 6.3.1.3).} +that type (C90 6.2.1.2, C99 and C11 6.3.1.3, C23 6.3.2.3).} For conversion to a type of width @math{N}, the value is reduced modulo @math{2^N} to be within range of the type; no signal is raised. @item @cite{The results of some bitwise operations on signed integers (C90 -6.3, C99 and C11 6.5).} +6.3, C99 and C11 6.5, C23 6.5.1).} Bitwise operators act on the representation of the value including both the sign and value bits, where the sign bit is considered @@ -267,7 +289,7 @@ immediately above the highest-value value bit. Signed @samp{>>} acts on negative numbers by sign extension. As an extension to the C language, GCC does not use the latitude given in -C99 and C11 only to treat certain aspects of signed @samp{<<} as undefined. +C99 and later to treat certain aspects of signed @samp{<<} as undefined. However, @option{-fsanitize=shift} (and @option{-fsanitize=undefined}) will diagnose such cases. They are also diagnosed where constant expressions are required. @@ -275,7 +297,7 @@ expressions are required. @item @cite{The sign of the remainder on integer division (C90 6.3.5).} -GCC always follows the C99 and C11 requirement that the result of division is +GCC always follows the C99 and later requirement that the result of division is truncated towards zero. @end itemize @@ -287,34 +309,46 @@ truncated towards zero. @item @cite{The accuracy of the floating-point operations and of the library functions in @code{<math.h>} and @code{<complex.h>} that return floating-point -results (C90, C99 and C11 5.2.4.2.2).} +results (C90, C99 and C11 5.2.4.2.2, C23 5.3.5.3.3).} The accuracy is unknown. @item @cite{The rounding behaviors characterized by non-standard values of @code{FLT_ROUNDS} -(C90, C99 and C11 5.2.4.2.2).} +(C90, C99 and C11 5.2.4.2.2, C23 5.3.5.3.3).} + +GCC does not use such values. + +@item +@cite{The evaluation methods characterized by non-standard negative +values of @code{FLT_EVAL_METHOD} (C99 and C11 5.2.4.2.2, C23 5.3.5.3.3).} GCC does not use such values. @item @cite{The evaluation methods characterized by non-standard negative -values of @code{FLT_EVAL_METHOD} (C99 and C11 5.2.4.2.2).} +values of @code{DEC_EVAL_METHOD} (C23 5.3.5.3.4).} GCC does not use such values. @item +@cite{If decimal floating types are supported (C23 6.2.5).} + +These are supported for certain AArch64, i386, x86-64, PowerPC and +S/390 targets only. + +@item @cite{The direction of rounding when an integer is converted to a floating-point number that cannot exactly represent the original -value (C90 6.2.1.3, C99 and C11 6.3.1.4).} +value (C90 6.2.1.3, C99 and C11 6.3.1.4, C23 6.3.2.4).} C99 Annex F is followed. @item @cite{The direction of rounding when a floating-point number is converted to a narrower floating-point number (C90 6.2.1.4, C99 and C11 -6.3.1.5).} +6.3.1.5, C23 6.3.2.5).} C99 Annex F is followed. @@ -322,13 +356,14 @@ C99 Annex F is followed. @cite{How the nearest representable value or the larger or smaller representable value immediately adjacent to the nearest representable value is chosen for certain floating constants (C90 6.1.3.1, C99 and C11 -6.4.4.2).} +6.4.4.2, C23 6.4.5.3).} C99 Annex F is followed. @item @cite{Whether and how floating expressions are contracted when not -disallowed by the @code{FP_CONTRACT} pragma (C99 and C11 6.5).} +disallowed by the @code{FP_CONTRACT} pragma (C99 and C11 6.5, C23 +6.5.1).} Expressions are currently only contracted if @option{-ffp-contract=fast}, @option{-funsafe-math-optimizations} or @option{-ffast-math} are used. @@ -336,7 +371,7 @@ This is subject to change. @item @cite{The default state for the @code{FENV_ACCESS} pragma (C99 and C11 -7.6.1).} +7.6.1, C23 7.6.2).} This pragma is not implemented, but the default is to ``off'' unless @option{-frounding-math} is used and @option{-fno-trapping-math} is not @@ -344,15 +379,15 @@ in which case it is ``on''. @item @cite{Additional floating-point exceptions, rounding modes, environments, -and classifications, and their macro names (C99 and C11 7.6, C99 and -C11 7.12).} +and classifications, and their macro names (C99, C11 and C23 7.6, C99, +C11 and C23 7.12).} This is dependent on the implementation of the C library, and is not defined by GCC itself. @item @cite{The default state for the @code{FP_CONTRACT} pragma (C99 and C11 -7.12.2).} +7.12.2, C23 7.12.3).} This pragma is not implemented. Expressions are currently only contracted if @option{-ffp-contract=fast}, @@ -377,13 +412,32 @@ defined by GCC itself. @end itemize +@node Constant expressions implementation +@section Constant expressions + +@itemize @bullet +@item +@cite{Whether or not an expression not explicitly sanctioned by this +document is an extended constant expression, whether or not such +extended constant expressions can be used in the same contexts as this +document, and whether or not such extended constant expressions can +affect potentially detectable semantic changes in the program (C23 +6.6).} + +The only extended constant expressions are those using other GNU +extensions to the C language. Such extended constant expressions +include integer constant expressions and arithmetic constant +expressions. + +@end itemize + @node Arrays and pointers implementation @section Arrays and Pointers @itemize @bullet @item @cite{The result of converting a pointer to an integer or -vice versa (C90 6.3.4, C99 and C11 6.3.2.3).} +vice versa (C90 6.3.4, C99 and C11 6.3.2.3, C23 6.3.3.3).} A cast from pointer to integer discards most-significant bits if the pointer representation is larger than the integer type, @@ -410,7 +464,7 @@ C99 and C11 6.5.6/8. @item @cite{The size of the result of subtracting two pointers to elements -of the same array (C90 6.3.6, C99 and C11 6.5.6).} +of the same array (C90 6.3.6, C99 and C11 6.5.6, C23 6.5.7).} The value is as specified in the standard and the type is determined by the ABI@. @@ -423,7 +477,8 @@ by the ABI@. @itemize @bullet @item @cite{The extent to which suggestions made by using the @code{register} -storage-class specifier are effective (C90 6.5.1, C99 and C11 6.7.1).} +storage-class specifier are effective (C90 6.5.1, C99 and C11 6.7.1, +C23 6.7.2).} The @code{register} specifier affects code generation only in these ways: @@ -448,7 +503,7 @@ in registers unless they are marked @code{register}. @item @cite{The extent to which suggestions made by using the inline function -specifier are effective (C99 and C11 6.7.4).} +specifier are effective (C99 and C11 6.7.4, C23 6.7.5).} GCC will not inline any functions if the @option{-fno-inline} option is used or if @option{-O0} is used. Otherwise, GCC may still be unable to @@ -472,7 +527,8 @@ may be a trap representation. @item @cite{Whether a ``plain'' @code{int} bit-field is treated as a @code{signed int} bit-field or as an @code{unsigned int} bit-field -(C90 6.5.2, C90 6.5.2.1, C99 and C11 6.7.2, C99 and C11 6.7.2.1).} +(C90 6.5.2, C90 6.5.2.1, C99 and C11 6.7.2, C23 6.7.3, C99 and C11 +6.7.2.1, C23 6.7.3.2).} @opindex funsigned-bitfields By default it is treated as @code{signed int} but this may be changed @@ -480,37 +536,38 @@ by the @option{-funsigned-bitfields} option. @item @cite{Allowable bit-field types other than @code{_Bool}, @code{signed int}, -and @code{unsigned int} (C99 and C11 6.7.2.1).} +and @code{unsigned int} (C99 and C11 6.7.2.1, C23 6.7.3.2).} Other integer types, such as @code{long int}, and enumerated types are permitted even in strictly conforming mode. @item -@cite{Whether atomic types are permitted for bit-fields (C11 6.7.2.1).} +@cite{Whether atomic types are permitted for bit-fields (C11 6.7.2.1, +C23 6.7.3.2).} Atomic types are not permitted for bit-fields. @item @cite{Whether a bit-field can straddle a storage-unit boundary (C90 -6.5.2.1, C99 and C11 6.7.2.1).} +6.5.2.1, C99 and C11 6.7.2.1, C23 6.7.3.2).} Determined by ABI@. @item @cite{The order of allocation of bit-fields within a unit (C90 -6.5.2.1, C99 and C11 6.7.2.1).} +6.5.2.1, C99 and C11 6.7.2.1, C23 6.7.3.2).} Determined by ABI@. @item @cite{The alignment of non-bit-field members of structures (C90 -6.5.2.1, C99 and C11 6.7.2.1).} +6.5.2.1, C99 and C11 6.7.2.1, C23 6.7.3.2).} Determined by ABI@. @item @cite{The integer type compatible with each enumerated type (C90 -6.5.2.2, C99 and C11 6.7.2.2).} +6.5.2.2, C99 and C11 6.7.2.2, C23 6.7.3.3).} @opindex fshort-enums Normally, the type is @code{unsigned int} if there are no negative @@ -538,7 +595,7 @@ determined by the ABI@. @itemize @bullet @item @cite{What constitutes an access to an object that has volatile-qualified -type (C90 6.5.3, C99 and C11 6.7.3).} +type (C90 6.5.3, C99 and C11 6.7.3, C23 6.7.4).} Such an object is normally accessed by pointers and used for accessing hardware. In most expressions, it is intuitively obvious what is a read @@ -584,6 +641,32 @@ object's declared type were @code{volatile S}. @end itemize +@node Types implementation +@section Types + +@itemize @bullet +@item +@cite{A program forms the composite type of an enumerated type and a +non-enumeration integer type (C23 6.2.7).} + +The composite type is the enumerated type. + +@item +@cite{Whether or not it is supported for a declaration for which a +type is inferred to contain a pointer, array, or function declarator +(C23 6.7.10).} + +This is not supported. + +@item +@cite{Whether or not it is supported for a declaration for which a +type is inferred to contain no or more than one declarators (C23 +6.7.10).} + +This is not supported. + +@end itemize + @node Declarators implementation @section Declarators @@ -618,48 +701,70 @@ implementation-defined behavior. @itemize @bullet @item @cite{The locations within @code{#pragma} directives where header name -preprocessing tokens are recognized (C11 6.4, C11 6.4.7).} +preprocessing tokens are recognized (C11 and C23 6.4, C11 6.4.7, C23 +6.4.8).} @item @cite{How sequences in both forms of header names are mapped to headers -or external source file names (C90 6.1.7, C99 and C11 6.4.7).} +or external source file names (C90 6.1.7, C99 and C11 6.4.7, C23 +6.4.8).} @item @cite{Whether the value of a character constant in a constant expression that controls conditional inclusion matches the value of the same character -constant in the execution character set (C90 6.8.1, C99 and C11 6.10.1).} +constant in the execution character set (C90 6.8.1, C99 and C11 +6.10.1, C23 6.10.2).} @item @cite{Whether the value of a single-character character constant in a constant expression that controls conditional inclusion may have a -negative value (C90 6.8.1, C99 and C11 6.10.1).} +negative value (C90 6.8.1, C99 and C11 6.10.1, C23 6.10.2).} @item @cite{The places that are searched for an included @samp{<>} delimited header, and how the places are specified or the header is -identified (C90 6.8.2, C99 and C11 6.10.2).} +identified (C90 6.8.2, C99 and C11 6.10.2, C23 6.10.3).} @item @cite{How the named source file is searched for in an included @samp{""} -delimited header (C90 6.8.2, C99 and C11 6.10.2).} +delimited header (C90 6.8.2, C99 and C11 6.10.2, C23 6.10.3).} + +@item +@cite{How the named resource file is searched for in an embedded @samp{""} +delimited resource name (C23 6.10.4).} @item @cite{The method by which preprocessing tokens (possibly resulting from macro expansion) in a @code{#include} directive are combined into a header -name (C90 6.8.2, C99 and C11 6.10.2).} +name (C90 6.8.2, C99 and C11 6.10.2, C23 6.10.3).} @item @cite{The nesting limit for @code{#include} processing (C90 6.8.2, C99 -and C11 6.10.2).} +and C11 6.10.2, C23 6.10.3).} + +@item +@cite{The method by which preprocessing tokens (possibly resulting +from macro expansion) in a @code{#embed} directive are combined into a +resource name (C23 6.10.4).} + +@item +@cite{The mapping between a resource's data and the values of the +integer constant expressions, if any, in the replacement of a +@code{#embed} directive (C23 6.10.4).} + +@item +@cite{The width of a resource located by the @code{#embed} directive +(C23 6.10.4).} @item @cite{Whether the @samp{#} operator inserts a @samp{\} character before the @samp{\} character that begins a universal character name in a -character constant or string literal (C99 and C11 6.10.3.2).} +character constant or string literal (C99 and C11 6.10.3.2, C23 +6.10.5.3).} @item @cite{The behavior on each recognized non-@code{STDC #pragma} -directive (C90 6.8.6, C99 and C11 6.10.6).} +directive (C90 6.8.6, C99 and C11 6.10.6, C23 6.10.8).} @xref{Pragmas, , Pragmas, cpp, The C Preprocessor}, for details of pragmas accepted by GCC on all targets. @xref{Pragmas, , Pragmas @@ -668,7 +773,7 @@ Accepted by GCC}, for details of target-specific pragmas. @item @cite{The definitions for @code{__DATE__} and @code{__TIME__} when respectively, the date and time of translation are not available (C90 -6.8.8, C99 6.10.8, C11 6.10.8.1).} +6.8.8, C99 6.10.8, C11 6.10.8.1, C23 6.10.10.2).} @end itemize @@ -681,7 +786,7 @@ of the C library, and are not defined by GCC itself. @itemize @bullet @item @cite{The null pointer constant to which the macro @code{NULL} expands -(C90 7.1.6, C99 7.17, C11 7.19).} +(C90 7.1.6, C99 7.17, C11 7.19, C23 7.21).} In @code{<stddef.h>}, @code{NULL} expands to @code{((void *)0)}. GCC does not provide the other headers which define @code{NULL} and some @@ -696,14 +801,15 @@ library implementations may use other definitions in those headers. @item @cite{The values or expressions assigned to the macros specified in the headers @code{<float.h>}, @code{<limits.h>}, and @code{<stdint.h>} -(C90, C99 and C11 5.2.4.2, C99 7.18.2, C99 7.18.3, C11 7.20.2, C11 7.20.3).} +(C90, C99 and C11 5.2.4.2, C23 5.3.5.3, C99 7.18.2, C99 7.18.3, C11 +7.20.2, C11 7.20.3, C23 7.22).} Determined by ABI@. @item @cite{The result of attempting to indirectly access an object with automatic or thread storage duration from a thread other than the one -with which it is associated (C11 6.2.4).} +with which it is associated (C11 and C23 6.2.4).} Such accesses are supported, subject to the same requirements for synchronization for concurrent accesses as for concurrent accesses to @@ -711,14 +817,14 @@ any object. @item @cite{The number, order, and encoding of bytes in any object -(when not explicitly specified in this International Standard) (C99 -and C11 6.2.6.1).} +(when not explicitly specified in this International Standard) (C99, +C11 and C23 6.2.6.1).} Determined by ABI@. @item @cite{Whether any extended alignments are supported and the contexts -in which they are supported (C11 6.2.8).} +in which they are supported (C11 and C23 6.2.8).} Extended alignments up to @math{2^{28}} (bytes) are supported for objects of automatic storage duration. Alignments supported for @@ -727,13 +833,13 @@ ABI. @item @cite{Valid alignment values other than those returned by an _Alignof -expression for fundamental types, if any (C11 6.2.8).} +expression for fundamental types, if any (C11 and C23 6.2.8).} Valid alignments are powers of 2 up to and including @math{2^{28}}. @item @cite{The value of the result of the @code{sizeof} and @code{_Alignof} -operators (C90 6.3.3.4, C99 and C11 6.5.3.4).} +operators (C90 6.3.3.4, C99 and C11 6.5.3.4, C23 6.5.4.5).} Determined by ABI@. diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi index 1af0082..7423224 100644 --- a/gcc/doc/install.texi +++ b/gcc/doc/install.texi @@ -302,7 +302,7 @@ released on 2017-05-06. The gcobol documentation is maintained as manpages using troff mdoc. GNU groff is required to convert them to PDF format. Conversion to HTML is done with mandoc, available at -@uref{http://mdocml.bsd.lv/}. +@uref{https://mandoc.bsd.lv}. Because ISO COBOL defines strict requirements for numerical precision, gcobol requires hardware with 128-bit computation instructions. This @@ -393,7 +393,7 @@ Note binutils 2.35 or newer is required for LTO to work correctly with GNU libtool that includes doing a bootstrap with LTO enabled. @item gzip version 1.2.4 (or later) or -@itemx bzip2 version 1.0.2 (or later) +@itemx xz version 5.0 (or later) Necessary to uncompress GCC @command{tar} files when source code is obtained via HTTPS mirror sites. @@ -631,6 +631,9 @@ building the documentation without error, but you may still want to install a newer release to get the best appearance and usability of the generated manuals. +Also note that Texinfo older than version 7.1 may throw incorrect build +warnings, though the generated documentation is correct. + @item @TeX{} (any working version) Necessary for running @command{texi2dvi} and @command{texi2pdf}, which @@ -1342,9 +1345,13 @@ default set of libraries is selected based on the value of @item amdgcn*-*-* @var{list} is a comma separated list of ISA names (allowed values: -@code{gfx900}, @code{gfx906}, @code{gfx908}, @code{gfx90a}, @code{gfx90c}, -@code{gfx1030}, @code{gfx1036}, @code{gfx1100}, @code{gfx1103}). -It ought not include the name of the default +@code{gfx900}, @code{gfx902}, @code{gfx904}, @code{gfx906}, @code{gfx908}, +@code{gfx909}, @code{gfx90a}, @code{gfx90c}, @code{gfx942}, @code{gfx950}, +@code{gfx9-generic}, @code{gfx9-4-generic}, @code{gfx1030}, @code{gfx1031}, +@code{gfx1032}, @code{gfx1033}, @code{gfx1034}, @code{gfx1035}, @code{gfx1036}, +@code{gfx10-3-generic}, @code{gfx1100}, @code{gfx1101}, @code{gfx1102}, +@code{gfx1103}, @code{gfx1150}, @code{gfx1151}, @code{gfx1152}, @code{gfx1153}, +@code{gfx11-generic}). It ought not include the name of the default ISA, specified via @option{--with-arch}. If @var{list} is empty, then there will be no multilibs and only the default run-time library will be built. If @var{list} is @code{default} or @option{--with-multilib-list=} is not @@ -1880,8 +1887,8 @@ Produce code conforming to version 20191213. In the absence of this configuration option the default version is 20191213. @item --enable-__cxa_atexit -Define if you want to use @code{__cxa_atexit}, rather than atexit, to -register C++ destructors for local statics and global objects. +Define if you want to use @code{__cxa_atexit}, rather than @code{atexit}, +to register C++ destructors for local statics and global objects. This is essential for fully standards-compliant handling of destructors, but requires @code{__cxa_atexit} in libc. This option is currently only available on systems with GNU libc. When enabled, this @@ -2660,6 +2667,17 @@ target binutils supports @code{Intel CET} instructions and disabled otherwise. In this case, the target libraries are configured to get additional @option{-fcf-protection} option. +@item --enable-x86-64-mfentry +@itemx --disable-x86-64-mfentry +Enable @option {-mfentry} by default on x86-64 to put the profiling +counter call, @code{__fentry__}, before the prologue so that @option{-pg} +can be used with @option{-fshrink-wrap} which is enabled at @option{-O1}. +This configure option is 64-bit only because @code{__fentry__} doesn't +support PIC in 32-bit mode. + +@option{--enable-x86-64-mfentry=auto} is default. @option{-mfentry} is +enabled on Linux/x86-64 by default. + @item --with-riscv-attribute=@samp{yes}, @samp{no} or @samp{default} Generate RISC-V attribute by default, in order to record extra build information in object. @@ -3144,6 +3162,13 @@ Removes any @option{-O}-started option from @code{BOOT_CFLAGS}, and adds @itemx @samp{bootstrap-Og} Analogous to @code{bootstrap-O1}. +@item @samp{bootstrap-native} +@itemx @samp{bootstrap-native} +Optimize the compiler code for the build host, if supported by the +architecture. Note this only affects the compiler, not the targeted +code. If you want the later, choose options suitable to the target you +are looking for. For example @samp{--with-cpu} would be a good starting point. + @item @samp{bootstrap-lto} Enables Link-Time Optimization for host tools during bootstrapping. @samp{BUILD_CONFIG=bootstrap-lto} is equivalent to adding @@ -4053,9 +4078,10 @@ By default, multilib support is built for @code{gfx900}, @code{gfx906}, requires LLVM 15 or newer. LLVM 13.0.1 or LLVM 14 can be used by specifying a @code{--with-multilib-list=} that does not list any GFX 11 device nor @code{gfx1036}. At least LLVM 16 is required for @code{gfx1150} and -@code{gfx1151}, LLVM 19 for the generic @code{gfx9-generic}, -@code{gfx10-3-generic}, and @code{gfx11-generic} targets and for -@code{gfx1152}, while LLVM 20 is required for @code{gfx1153}. +@code{gfx1151}, LLVM 18 for @code{gfx942}, LLVM 19 for the generic +@code{gfx9-generic}, @code{gfx9-4-generic}, @code{gfx10-3-generic}, and +@code{gfx11-generic} targets and for @code{gfx1152}, while LLVM 20 is required +for @code{gfx950} and @code{gfx1153}. The supported ISA architectures are listed in the GCC manual. The generic ISA targets @code{gfx9-generic}, @code{gfx10-3-generic}, and @@ -5138,13 +5164,6 @@ respects, this target is the same as the @anchor{windows} @heading Microsoft Windows -@subheading Intel 16-bit versions -The 16-bit versions of Microsoft Windows, such as Windows 3.1, are not -supported. - -However, the 32-bit port has limited support for Microsoft -Windows 3.11 in the Win32s environment, as a target only. See below. - @subheading Intel 32-bit versions The 32-bit versions of Windows, including Windows 95, Windows NT, Windows XP, and Windows Vista, are supported by several different target diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 88fb9bd..33ae98c 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -266,7 +266,7 @@ in the following sections. -Wnoexcept -Wnoexcept-type -Wnon-virtual-dtor -Wpessimizing-move -Wno-placement-new -Wplacement-new=@var{n} -Wrange-loop-construct -Wredundant-move -Wredundant-tags --Wreorder -Wregister +-Wreorder -Wregister -Wno-sfinae-incomplete -Wstrict-null-sentinel -Wno-subobject-linkage -Wtemplates -Wno-non-template-friend -Wold-style-cast -Woverloaded-virtual -Wno-pmf-conversions -Wself-move -Wsign-promo @@ -312,7 +312,7 @@ Objective-C and Objective-C++ Dialects}. -fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]} -fdiagnostics-color=@r{[}auto@r{|}never@r{|}always@r{]} -fdiagnostics-urls=@r{[}auto@r{|}never@r{|}always@r{]} --fdiagnostics-format=@r{[}text@r{|}sarif-stderr@r{|}sarif-file@r{|}json@r{|}json-stderr@r{|}json-file@r{]} +-fdiagnostics-format=@r{[}text@r{|}sarif-stderr@r{|}sarif-file@r{]} -fdiagnostics-add-output=@var{DIAGNOSTICS-OUTPUT-SPEC} -fdiagnostics-set-output=@var{DIAGNOSTICS-OUTPUT-SPEC} -fno-diagnostics-json-formatting @@ -340,7 +340,7 @@ Objective-C and Objective-C++ Dialects}. -w -Wextra -Wall -Wabi=@var{n} -Waddress -Wno-address-of-packed-member -Waggregate-return -Walloc-size -Walloc-size-larger-than=@var{byte-size} -Walloc-zero --Walloca -Walloca-larger-than=@var{byte-size} +-Walloca -Walloca-larger-than=@var{byte-size} -Wauto-profile -Wno-aggressive-loop-optimizations -Warith-conversion -Warray-bounds -Warray-bounds=@var{n} -Warray-compare @@ -353,7 +353,7 @@ Objective-C and Objective-C++ Dialects}. -Wno-builtin-macro-redefined -Wc90-c99-compat -Wc99-c11-compat -Wc11-c23-compat -Wc23-c2y-compat -Wc++-compat -Wc++11-compat -Wc++14-compat -Wc++17-compat --Wc++20-compat +-Wc++20-compat -Wc++26-compat -Wno-c++11-extensions -Wno-c++14-extensions -Wno-c++17-extensions -Wno-c++20-extensions -Wno-c++23-extensions -Wcalloc-transposed-args @@ -388,6 +388,7 @@ Objective-C and Objective-C++ Dialects}. -Winit-self -Winline -Wno-int-conversion -Wint-in-bool-context -Wno-int-to-pointer-cast -Wno-invalid-memory-model -Winvalid-pch -Winvalid-utf8 -Wno-unicode -Wjump-misses-init +-Wkeyword-macro -Wlarger-than=@var{byte-size} -Wleading-whitespace=@var{kind} -Wlogical-not-parentheses -Wlogical-op -Wlong-long -Wno-lto-type-mismatch -Wmain -Wmaybe-uninitialized @@ -433,7 +434,8 @@ Objective-C and Objective-C++ Dialects}. -Wunsuffixed-float-constants -Wunterminated-string-initialization -Wunused --Wunused-but-set-parameter -Wunused-but-set-variable +-Wunused-but-set-parameter -Wunused-but-set-parameter=@var{n} +-Wunused-but-set-variable -Wunused-but-set-variable=@var{n} -Wunused-const-variable -Wunused-const-variable=@var{n} -Wunused-function -Wunused-label -Wunused-local-typedefs -Wunused-macros @@ -513,6 +515,7 @@ Objective-C and Objective-C++ Dialects}. -Wno-analyzer-tainted-divisor -Wno-analyzer-tainted-offset -Wno-analyzer-tainted-size +-Wno-analyzer-throw-of-unexpected-type -Wanalyzer-symbol-too-complex -Wanalyzer-too-complex -Wno-analyzer-undefined-behavior-ptrdiff @@ -572,13 +575,13 @@ Objective-C and Objective-C++ Dialects}. -fmin-function-alignment=[@var{n}] -fno-allocation-dce -fallow-store-data-races -fassociative-math -fauto-profile -fauto-profile[=@var{path}] --fauto-inc-dec -fbranch-probabilities +-fauto-profile-inlining -fauto-inc-dec -fbranch-probabilities -fcaller-saves -fcombine-stack-adjustments -fconserve-stack -ffold-mem-offsets -fcompare-elim -fcprop-registers -fcrossjumping -fcse-follow-jumps -fcse-skip-blocks -fcx-fortran-rules --fcx-limited-range +-fcx-limited-range -fcx-method -fdata-sections -fdce -fdelayed-branch -fdelete-null-pointer-checks -fdevirtualize -fdevirtualize-speculatively -fdevirtualize-at-ltrans -fdse @@ -913,7 +916,7 @@ Objective-C and Objective-C++ Dialects}. @emph{AVR Options} (@ref{AVR Options}) @gccoptlist{-mmcu=@var{mcu} -mabsdata -maccumulate-args -mcvt -mbranch-cost=@var{cost} -mfuse-add=@var{level} -mfuse-move=@var{level} --mcall-prologues -mgas-isr-prologues -mint8 -mflmap +-mfuse-move2 -mcall-prologues -mgas-isr-prologues -mint8 -mflmap -mdouble=@var{bits} -mlong-double=@var{bits} -mno-call-main -mn_flash=@var{size} -mfract-convert-truncate -mno-interrupts -mmain-is-OS_task -mrelax -mrmw -mstrict-X -mtiny-stack @@ -1267,7 +1270,7 @@ See RS/6000 and PowerPC Options. -mfence-tso -mno-fence-tso -mdiv -mno-div -misa-spec=@var{ISA-spec-string} --march=@var{ISA-string} +-march=@var{ISA-string|Profiles|Profiles_ISA-string|CPU/processor string} -mtune=@var{processor-string} -mpreferred-stack-boundary=@var{num} -msmall-data-limit=@var{N-bytes} @@ -1495,8 +1498,8 @@ See RS/6000 and PowerPC Options. -mamx-tile -mamx-int8 -mamx-bf16 -muintr -mhreset -mavxvnni -mamx-fp8 -mavx512fp16 -mavxifma -mavxvnniint8 -mavxneconvert -mcmpccxadd -mamx-fp16 -mprefetchi -mraoint -mamx-complex -mavxvnniint16 -msm3 -msha512 -msm4 -mapxf --musermsr -mavx10.1 -mavx10.1-256 -mavx10.1-512 -mevex512 -mavx10.2 --mamx-avx512 -mamx-tf32 -mamx-transpose -mmovrs -mamx-movrs +-musermsr -mavx10.1 -mavx10.2 -mamx-avx512 -mamx-tf32 -mamx-transpose -mmovrs +-mamx-movrs -mcldemote -mms-bitfields -mno-align-stringops -minline-all-stringops -minline-stringops-dynamically -mstringop-strategy=@var{alg} -mkl -mwidekl @@ -2439,8 +2442,8 @@ ISO C99. This standard is substantially completely supported, modulo bugs and floating-point issues (mainly but not entirely relating to optional C99 features from Annexes F and G). See -@w{@uref{https://gcc.gnu.org/c99status.html}} for more information. The -names @samp{c9x} and @samp{iso9899:199x} are deprecated. +@w{@uref{https://gcc.gnu.org/projects/c-status.html}} for more information. +The names @samp{c9x} and @samp{iso9899:199x} are deprecated. @item c11 @itemx c1x @@ -3005,12 +3008,19 @@ in C++14 and up. Version 18, which first appeared in G++ 13, fixes manglings of lambdas that have additional context. -Version 19, which first appeared in G++ 14, fixes manglings of structured -bindings to include ABI tags. +Version 19, which first appeared in G++ 14, fixes manglings of +structured bindings to include ABI tags, handling of cv-qualified +[[no_unique_address]] members, and adds mangling of C++20 constraints +on function templates. Version 20, which first appeared in G++ 15, fixes manglings of lambdas in static data member initializers. +Version 21, which first appeared in G++ 16, fixes unnecessary captures +in noexcept lambdas (c++/119764), layout of a base class with all explicitly +defaulted constructors (c++/120012), and mangling of class and array +objects with implicitly zero-initialized non-trailing subobjects (c++/121231). + See also @option{-Wabi}. @opindex fabi-compat-version @@ -3290,6 +3300,50 @@ Enable support for the C++ coroutines extension (experimental). Permit the C++ front end to note all candidates during overload resolution failure, including when a deleted function is selected. +@item -fdump-lang- +@itemx -fdump-lang-@var{switch} +@itemx -fdump-lang-@var{switch}-@var{options} +@itemx -fdump-lang-@var{switch}-@var{options}=@var{filename} +Control the dumping of C++-specific information. The @var{options} +and @var{filename} portions behave as described in the +@option{-fdump-tree} option. The following @var{switch} values are +accepted: + +@table @samp +@item all +Enable all of the below. + +@opindex fdump-lang-class +@item class +Dump class hierarchy information. Virtual table information is emitted +unless '@option{slim}' is specified. + +@opindex fdump-lang-module +@item module +Dump module information. Options @option{lineno} (locations), +@option{graph} (reachability), @option{blocks} (clusters), +@option{uid} (serialization), @option{alias} (mergeable), +@option{asmname} (Elrond), @option{eh} (mapper) & @option{vops} +(macros) may provide additional information. + +@opindex fdump-lang-raw +@item raw +Dump the raw internal tree data. + +@opindex fdump-lang-tinst +@item tinst +Dump the sequence of template instantiations, indented to show the +depth of recursion. The @option{lineno} option adds the source +location where the instantiation was triggered, and the +@option{details} option also dumps pre-instantiation substitutions +such as those performed during template argument deduction. + +Lines in the .tinst dump start with @samp{I} for an instantiation, +@samp{S} for another substitution, and @samp{R[IS]} for the reopened +context of a deferred instantiation. + +@end table + @opindex fno-elide-constructors @opindex felide-constructors @item -fno-elide-constructors @@ -3341,7 +3395,8 @@ aliases, the default is @option{-fno-extern-tls-init}. @item -ffold-simple-inlines @itemx -fno-fold-simple-inlines Permit the C++ frontend to fold calls to @code{std::move}, @code{std::forward}, -@code{std::addressof} and @code{std::as_const}. In contrast to inlining, this +@code{std::addressof}, @code{std::to_underlying} +and @code{std::as_const}. In contrast to inlining, this means no debug information will be generated for such calls. Since these functions are rarely interesting to debug, this flag is enabled by default unless @option{-fno-inline} is active. @@ -3764,6 +3819,23 @@ Warn when a type with an ABI tag is used in a context that does not have that ABI tag. See @ref{C++ Attributes} for more information about ABI tags. +@opindex Wabbreviated-auto-in-template-arg +@opindex Wno-abbreviated-auto-in-template-arg +@item -Wno-abbreviated-auto-in-template-arg +Disable the error for an @code{auto} placeholder type used within a +template argument list to declare a C++20 abbreviated function +template, e.g. + +@smallexample +void f(S<auto>); +@end smallexample + +This feature was proposed in the Concepts TS, but was not adopted into +C++20; in the standard, a placeholder in a parameter declaration must +appear as a decl-specifier. The error can also be reduced to a +warning by @option{-fpermissive} or +@option{-Wno-error=abbreviated-auto-in-template-arg}. + @opindex Wcomma-subscript @opindex Wno-comma-subscript @item -Wcomma-subscript @r{(C++ and Objective-C++ only)} @@ -4396,6 +4468,20 @@ to filter out those warnings. Disable the warning about the case when an exception handler is shadowed by another handler, which can point out a wrong ordering of exception handlers. +@opindex Wsfinae-incomplete +@opindex Wno-sfinae-incomplete +Warn about a class that is found to be incomplete, or a function with +auto return type that has not yet been deduced, in a context where +that causes substitution failure rather than an error, and then the +class or function is defined later in the translation unit. This is +problematic because template instantiations or concept checks could +have different results if they first occur either before or after the +definition. + +This warning is enabled by default. @option{-Wsfinae-incomplete=2} +adds a warning at the point of substitution failure, to make it easier +to track down problems flagged by the default mode. + @opindex Wstrict-null-sentinel @opindex Wno-strict-null-sentinel @item -Wstrict-null-sentinel @r{(C++ and Objective-C++ only)} @@ -5892,8 +5978,7 @@ column numbers, such as @command{dejagnu}. @opindex fdiagnostics-column-unit @item -fdiagnostics-column-unit=@var{UNIT} Select the units for the column number. This affects traditional diagnostics -(in the absence of @option{-fno-show-column}), as well as JSON format -diagnostics if requested. +(in the absence of @option{-fno-show-column}). The default @var{UNIT}, @samp{display}, considers the number of display columns occupied by each character. This may be larger than the number @@ -5969,8 +6054,7 @@ is set to @samp{C}, in which case the default is @samp{ascii}. @opindex fdiagnostics-format @item -fdiagnostics-format=@var{FORMAT} Select a different format for printing diagnostics. -@var{FORMAT} is @samp{text}, @samp{sarif-stderr}, @samp{sarif-file}, -@samp{json}, @samp{json-stderr}, or @samp{json-file}. +@var{FORMAT} is @samp{text}, @samp{sarif-stderr} or @samp{sarif-file}. Using this option replaces any additional ``output sinks'' added by @option{-fdiagnostics-add-output=}, or that set by @@ -5982,14 +6066,6 @@ The @samp{sarif-stderr} and @samp{sarif-file} formats both emit diagnostics in SARIF Version 2.1.0 format, either to stderr, or to a file named @file{@var{source}.sarif}, respectively. -The various @samp{json}, @samp{json-stderr}, and @samp{json-file} values -are deprecated and refer to a legacy JSON-based output format. -The @samp{json} format is a synonym for @samp{json-stderr}. -The @samp{json-stderr} and @samp{json-file} formats are identical, apart from -where the JSON is emitted to. With @samp{json-stderr}, the JSON is emitted -to stderr, whereas with @samp{json-file} it is written to -@file{@var{source}.gcc.json}. - @opindex fdiagnostics-add-output @item -fdiagnostics-add-output=@var{DIAGNOSTICS-OUTPUT-SPEC} Add an additional ``output sink'' for emitting diagnostics. @@ -6052,6 +6128,11 @@ Specify the filename to write the SARIF output to, potentially with a leading absolute or relative path. If not specified, it defaults to @file{@var{source}.sarif}. +@item serialization=@r{[}json@r{]} +Specify the serialization format to use when writing out the SARIF. +Currently this can only be @code{json}, but is present as an +extension point for experimenting with other serializations. + @item version=@r{[}2.1@r{|}2.2-prerelease@r{]} Specify the version of SARIF to use for the output. If not specified, defaults to 2.1. @code{2.2-prerelease} uses an unofficial draft of the @@ -6060,6 +6141,70 @@ in this release. @end table +There is also this key intended for use by GCC developers, rather than +end-users, and subject to change or removal without notice: + +@table @gcctabopt + +@item state-graphs=@r{[}yes@r{|}no@r{]} +This is a debugging feature and defaults to @code{no}. +If @code{state-graphs=yes}, then attempt to capture detailed state +information from @option{-fanalyzer} in the generated SARIF. + +@end table + +@item experimental-html +Emit diagnostics to a file in HTML format. This scheme is experimental, +and may go away in future GCC releases. The keys and details of the output +are also subject to change. + +Supported keys are: + +@table @gcctabopt + +@item css=@r{[}yes@r{|}no@r{]} +Add an embedded <style> to the generated HTML. Defaults to yes. + +@item file=@var{FILENAME} +Specify the filename to write the HTML output to, potentially with a +leading absolute or relative path. If not specified, it defaults to +@file{@var{source}.html}. + +@item javascript=@r{[}yes@r{|}no@r{]} +Add an embedded <script> to the generated HTML providing a barebones UI +for viewing results. Defaults to yes. + +@end table + +There are also these keys intended for use by GCC developers, rather than +end-users, and subject to change or removal without notice: + +@table @gcctabopt + +@item show-state-diagrams=@r{[}yes@r{|}no@r{]} +This is a debugging feature and defaults to @code{no}. +If @code{show-state-diagrams=yes}, then attempt to use @command{dot} to +generate SVG diagrams in the generated HTML, visualizing the state at each +event in a diagnostic path. +These are visible by pressing ``j'' and ``k'' to single-step forward and +backward through events. Enabling this option will slow down +HTML generation. + +@item show-state-diagrams-dot-src=@r{[}yes@r{|}no@r{]} +This is a debugging feature and defaults to @code{no}. +If @code{show-state-diagrams-dot-src=yes} +then if @code{show-state-diagrams=yes}, +the generated state diagrams will also show the .dot source input to +GraphViz used for the diagram. + +@item show-state-diagrams-sarif=@r{[}yes@r{|}no@r{]} +This is a debugging feature and defaults to @code{no}. +If @code{show-state-diagrams-sarif=yes} +then if @code{show-state-diagrams=yes}, the generated state diagrams will +also show a SARIF representation of the state. + +@end table + @end table For example, @@ -6079,7 +6224,7 @@ In EBNF: @var{diagnostics-output-specifier} = @var{diagnostics-output-name} | @var{diagnostics-output-name}, ":", @var{key-value-pairs}; -@var{diagnostics-output-name} = "text" | "sarif"; +@var{diagnostics-output-name} = "text" | "sarif" | "experimental-html"; @var{key-value-pairs} = @var{key-value-pair} | @var{key-value-pair} "," @var{key-value-pairs}; @@ -6103,11 +6248,8 @@ replaces all existing output sinks, such as from @option{-fdiagnostics-format=}, @opindex fdiagnostics-json-formatting @item -fno-diagnostics-json-formatting By default, when JSON is emitted for diagnostics (via -@option{-fdiagnostics-format=sarif-stderr}, -@option{-fdiagnostics-format=sarif-file}, -@option{-fdiagnostics-format=json}, -@option{-fdiagnostics-format=json-stderr}, -@option{-fdiagnostics-format=json-file}), +@option{-fdiagnostics-format=sarif-stderr} or +@option{-fdiagnostics-format=sarif-file}), GCC will add newlines and indentation to visually emphasize the hierarchical structure of the JSON. @@ -6321,6 +6463,7 @@ only by this flag, but it also downgrades some C and C++ diagnostics that have their own flag: @gccoptlist{ +-Wabbreviated-auto-in-template-arg @r{(C++ and Objective-C++ only)} -Wdeclaration-missing-parameter-type @r{(C and Objective-C only)} -Wimplicit-function-declaration @r{(C and Objective-C only)} -Wimplicit-int @r{(C and Objective-C only)} @@ -6980,14 +7123,14 @@ which is enabled by optimizations in most targets. The precision of the warnings depends on the optimization options used. @opindex Wno-musttail-local-addr -@opindex -Wmusttail-local-addr +@opindex Wmusttail-local-addr @item -Wno-musttail-local-addr Do not warn about passing a pointer (or in C++, a reference) to a local variable or label to argument of a @code{musttail} call. Those variables go out of scope before the tail call instruction. @opindex Wmaybe-musttail-local-addr -@opindex -Wno-maybe-musttail-local-addr +@opindex Wno-maybe-musttail-local-addr @item -Wmaybe-musttail-local-addr Warn when address of a local variable can escape to a @code{musttail} call, unless it goes out of scope already before the @code{musttail} @@ -7781,27 +7924,89 @@ statement. @opindex Wunused-but-set-parameter @opindex Wno-unused-but-set-parameter @item -Wunused-but-set-parameter +@option{-Wunused-but-set-parameter} is the same as +@option{-Wunused-but-set-parameter=3} and +@option{-Wno-unused-but-set-parameter} is the same as +@option{-Wunused-but-set-parameter=0}. + +@opindex Wunused-but-set-parameter= +@item -Wunused-but-set-parameter=@var{n} Warn whenever a function parameter is assigned to, but otherwise unused (aside from its declaration). To suppress this warning use the @code{unused} attribute (@pxref{Variable Attributes}). -This warning is also enabled by @option{-Wunused} together with -@option{-Wextra}. +@option{-Wunused-but-set-parameter=0} disables the warning. +With @option{-Wunused-but-set-parameter=1} all uses except initialization +and left hand side of assignment which is not further used disable the +warning. +With @option{-Wunused-but-set-parameter=2} additionally uses of parameter +in @code{++} and @code{--} operators don't count as uses. +And finally with @option{-Wunused-but-set-parameter=3} additionally +uses in @var{parm} @code{@var{@@}=} @var{rhs} outside of @var{rhs} don't +count as uses. See @option{-Wunused-but-set-variable=@var{n}} option for +examples. + +This @option{-Wunused-but-set-parameter=3} warning is also enabled by +@option{-Wunused} together with @option{-Wextra}. @opindex Wunused-but-set-variable @opindex Wno-unused-but-set-variable @item -Wunused-but-set-variable +@option{-Wunused-but-set-variable} is the same as +@option{-Wunused-but-set-variable=3} and +@option{-Wno-unused-but-set-variable} is the same as +@option{-Wunused-but-set-variable=0}. + +@opindex Wunused-but-set-variable= +@item -Wunused-but-set-variable=@var{n} Warn whenever a local variable is assigned to, but otherwise unused (aside from its declaration). -This warning is enabled by @option{-Wall}. +This @option{-Wunused-but-set-variable=3} warning is enabled by @option{-Wall}. To suppress this warning use the @code{unused} attribute (@pxref{Variable Attributes}). -This warning is also enabled by @option{-Wunused}, which is enabled -by @option{-Wall}. +@option{-Wunused-but-set-variable=0} disables the warning. +With @option{-Wunused-but-set-variable=1} all uses except initialization +and left hand side of assignment which is not further used disable the +warning. +With @option{-Wunused-but-set-variable=2} additionally uses of variable +in @code{++} and @code{--} operators don't count as uses. +And finally with @option{-Wunused-but-set-variable=3} additionally +uses in @var{parm} @code{@var{@@}=} @var{rhs} outside of @var{rhs} don't +count as uses. + +This @option{-Wunused-but-set-variable=3} warning is also enabled by +@option{-Wunused}, which is enabled by @option{-Wall}. + +@smallexample +void foo (void) +@{ + int a = 1; // @option{-Wunused-variable} warning + int b = 0; // Warning for @var{n} >= 1 + b = 1; b = 2; + int c = 0; // Warning for @var{n} >= 2 + ++c; c--; --c; c++; + int d = 0; // Warning for @var{n} >= 3 + d += 4; + int e = 0; // No warning, cast to void + (void) e; + int f = 0; // No warning, f used + int g = f = 5; + (void) g; + int h = 0; // No warning, preincrement used + int i = ++h; + (void) i; + int j = 0; // No warning, postdecrement used + int k = j--; + (void) k; + int l = 0; // No warning, l used + int m = l |= 2; + (void) m; +@} +@end smallexample @opindex Wunused-function @opindex Wno-unused-function @@ -8593,6 +8798,11 @@ larger. @item -Walloca This option warns on all uses of @code{alloca} in the source. +@opindex Wno-auto-profile +@opindex Wauto-profile +@item -Wauto-profile +Output warnings about auto-profile inconsistencies. + @opindex Walloca-larger-than= @opindex Wno-alloca-larger-than @item -Walloca-larger-than=@var{byte-size} @@ -9545,6 +9755,12 @@ and ISO C++ 2017. This warning is enabled by @option{-Wall}. Warn about C++ constructs whose meaning differs between ISO C++ 2017 and ISO C++ 2020. This warning is enabled by @option{-Wall}. +@opindex Wc++26-compat +@opindex Wno-c++26-compat +@item -Wc++26-compat @r{(C++ and Objective-C++ only)} +Warn about C++ constructs whose meaning differs between ISO C++ 2023 +and upcoming ISO C++ 2026. This warning is enabled by @option{-Wall}. + @opindex Wc++11-extensions @opindex Wno-c++11-extensions @item -Wno-c++11-extensions @r{(C++ and Objective-C++ only)} @@ -10184,6 +10400,14 @@ Do not warn if certain built-in macros are redefined. This suppresses warnings for redefinition of @code{__TIMESTAMP__}, @code{__TIME__}, @code{__DATE__}, @code{__FILE__}, and @code{__BASE_FILE__}. +@opindex Wkeyword-macro +@opindex Wno-keyword-macro +@item -Wkeyword-macro +Warn if a keyword is defined as a macro or undefined. +For C++ identifiers with special meaning or standard attribute identifiers +are diagnosed as well. This warning is enabled by default for C++26 +if @code{-Wpedantic} and emits a pedwarn in that case. + @opindex Wfree-labels @opindex Wno-free-labels @item -Wfree-labels @r{(C and Objective-C only)} @@ -11008,6 +11232,7 @@ Enabling this option effectively enables the following warnings: -Wanalyzer-tainted-divisor -Wanalyzer-tainted-offset -Wanalyzer-tainted-size +-Wanalyzer-throw-of-unexpected-type -Wanalyzer-undefined-behavior-ptrdiff -Wanalyzer-undefined-behavior-strtok -Wanalyzer-unsafe-call-within-signal-handler @@ -11659,6 +11884,17 @@ attacker could inject an out-of-bounds access. See @uref{https://cwe.mitre.org/data/definitions/129.html, CWE-129: Improper Validation of Array Index}. +@opindex Wanalyzer-throw-of-unexpected-type +@opindex Wno-analyzer-throw-of-unexpected-type +@item -Wno-analyzer-throw-of-unexpected-type +This warning requires @option{-fanalyzer} which enables it; +use @option{-Wno-analyzer-throw-of-unexpected-type} to disable it. +Dynamic exception specifications are only available in C++14 and earlier. + +This diagnostic warns for paths through the code in which a an exception +is thrown from a function with a dynamic exception specification where +the exception does not comply with the specification. + @opindex Wanalyzer-undefined-behavior-ptrdiff @opindex Wno-analyzer-undefined-behavior-ptrdiff @item -Wno-analyzer-undefined-behavior-ptrdiff @@ -12888,17 +13124,19 @@ It turns off @option{-fsemantic-interposition}. @opindex Og @item -Og -Optimize debugging experience. @option{-Og} should be the optimization +Optimize while keeping in mind debugging experience. +@option{-Og} should be the optimization level of choice for the standard edit-compile-debug cycle, offering -a reasonable level of optimization while maintaining fast compilation -and a good debugging experience. It is a better choice than @option{-O0} -for producing debuggable code because some compiler passes -that collect debug information are disabled at @option{-O0}. +a reasonable blend of optimization, fast compilation and debugging experience +especially for code with a high abstraction penalty. In contrast to +@option{-O0}, this enables @option{-fvar-tracking-assignments} and +@option{-fvar-tracking} which handle debug information in the prologue +and epilogue of functions better than @option{-O0}. -Like @option{-O0}, @option{-Og} completely disables a number of +Like @option{-O0}, @option{-Og} completely skips a number of optimization passes so that individual options controlling them have no effect. Otherwise @option{-Og} enables all @option{-O1} -optimization flags except for those that may interfere with debugging: +optimization flags except for those known to greatly interfere with debugging: @gccoptlist{-fbranch-count-reg -fdelayed-branch -fdse -fif-conversion -fif-conversion2 @@ -15353,6 +15591,12 @@ E.g. create_gcov --binary=your_program.unstripped --profile=perf.data \ --gcov=profile.afdo @end smallexample + +@opindex fauto-profile-inlining +@item -fauto-profile-inlining +When auto-profile is available inline all relevant functions which was +inlined in the tran run before reading the profile feedback. This improves +context sensitivity of the profile. Enabled by default. @end table The following options control compiler behavior regarding floating-point @@ -15603,8 +15847,7 @@ When enabled, this option states that a range reduction step is not needed when performing complex division. Also, there is no checking whether the result of a complex multiplication or division is @code{NaN + I*NaN}, with an attempt to rescue the situation in that case. The -default is @option{-fno-cx-limited-range}, but is enabled by -@option{-ffast-math}. +option is enabled by @option{-ffast-math}. This option controls the default setting of the ISO C99 @code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to @@ -15617,7 +15860,14 @@ reduction is done as part of complex division, but there is no checking whether the result of a complex multiplication or division is @code{NaN + I*NaN}, with an attempt to rescue the situation in that case. -The default is @option{-fno-cx-fortran-rules}. +@opindex fcx-method +@item -fcx-method=@var{method} +Complex multiplication and division follow the stated @var{method}. The +@var{method} argument should be one of @samp{limited-range}, @samp{fortran} +or @samp{stdc}. + +The default is to honor language specific constraints which means +@samp{fortran} for Fortran and @samp{stdc} otherwise. @end table @@ -16897,11 +17147,6 @@ Maximum depth of recursive cloning for self-recursive function. Recursive cloning only when the probability of call being executed exceeds the parameter. -@item ipa-cp-profile-count-base -When using @option{-fprofile-use} option, IPA-CP will consider the measured -execution count of a call graph edge at this percentage position in their -histogram as the basis for its heuristics calculation. - @item ipa-cp-recursive-freq-factor The number of times interprocedural copy propagation expects recursive functions to call themselves. @@ -17230,8 +17475,9 @@ this parameter. The default value of this parameter is 50. @item vect-induction-float Enable loop vectorization of floating point inductions. -@item vect-force-slp -Force the use of SLP when vectorizing, fail if not possible. +@item vect-scalar-cost-multiplier +Apply the given multiplier % to scalar loop costing during vectorization. +Increasing the cost multiplier will make vector loops more profitable. @item vrp-block-limit Maximum number of basic blocks before VRP switches to a lower memory algorithm. @@ -17310,6 +17556,9 @@ predicate chain. @item uninit-max-num-chains Maximum number of predicates ored in the normalized predicate chain. +@item uninit-max-prune-work +Maximum amount of work done to prune paths where the variable is always initialized. + @item sched-autopref-queue-depth Hardware autoprefetcher scheduler model control flag. Number of lookahead cycles the model looks into; at ' @@ -17473,20 +17722,9 @@ The precision of division is proportional to this param when division approximation is enabled. The default value is 2. @item aarch64-autovec-preference -Force an ISA selection strategy for auto-vectorization. -@table @samp -@item default -Use the default heuristics. -@item asimd-only -Use only Advanced SIMD for auto-vectorization. -@item sve-only -Use only SVE for auto-vectorization. -@item prefer-asimd -Use both Advanced SIMD and SVE. Prefer Advanced SIMD when the costs are -deemed equal. -@item prefer-sve -Use both Advanced SIMD and SVE. Prefer SVE when the costs are deemed equal. -@end table +An old alias for @option{-mautovec-preference}. If both +@option{-mautovec-preference} and @option{--param=aarch64-autovec-preference} +are passed, the @option{--param} value will be used. @item aarch64-ldp-policy Fine-grained policy for load pairs. @@ -20384,18 +20622,22 @@ LTO output files. @opindex fdump-rtl-@var{pass} @item -d@var{letters} @itemx -fdump-rtl-@var{pass} -@itemx -fdump-rtl-@var{pass}=@var{filename} +@itemx -fdump-rtl-@var{pass}-@var{options} +@itemx -fdump-rtl-@var{pass}-@var{options}=@var{filename} Says to make debugging dumps during compilation at times specified by -@var{letters}. This is used for debugging the RTL-based passes of the +@var{letters} when using @option{-d} or by @var{pass} when using +@option{-fdump-rtl}. This is used for debugging the RTL-based passes of the compiler. Some @option{-d@var{letters}} switches have different meaning when @option{-E} is used for preprocessing. @xref{Preprocessor Options}, for information about preprocessor-specific dump options. -Debug dumps can be enabled with a @option{-fdump-rtl} switch or some -@option{-d} option @var{letters}. Here are the possible -letters for use in @var{pass} and @var{letters}, and their meanings: +The @samp{-@var{options}} form allows greater control over the details of the +dump. See @option{-fdump-tree}. + +Here are actual instances of command-line options following these patterns and +their meanings: @table @gcctabopt @@ -20750,6 +20992,93 @@ By default, the dump will contain messages about successful optimizations (equivalent to @option{-optimized}) together with low-level details about the analysis. +@opindex fdump-ipa-clones +@item -fdump-ipa-clones + +Create a dump file containing information about creation of call graph +node clones and removals of call graph nodes during inter-procedural +optimizations and transformations. Its main intended use is that tools +that create live-patches can determine the set of functions that need to +be live-patched to completely replace a particular function (see +@option{-flive-patching}). The file name is generated by appending +suffix @code{ipa-clones} to the source file name, and the file is +created in the same directory as the output file. Each entry in the +file is on a separate line containing semicolon separated fields. + +In the case of call graph clone creation, the individual fields are: + +@enumerate +@item +String @code{Callgraph clone}. + +@item +Name of the function being cloned as it is presented to the assembler. + +@item +A number that uniquely represents the function being cloned in the call +graph. Note that the number is unique only within a compilation unit or +within whole-program analysis but is likely to be different in the two +phases. + +@item +The file name of the source file where the function is defined. + +@item +The line on which the function definition is located. + +@item +The column where the function definition is located. + +@item +Name of the new function clone as it is presented to the assembler. + +@item +A number that uniquely represents the new function clone in the call +graph. Note that the number is unique only within a compilation unit or +within whole-program analysis but is likely to be different in the two +phases. + +@item +The file name of the source file where the source code location of the +new clone points to. + +@item +The line to which the source code location of the new clone points to. + +@item +The column to which the source code location of the new clone points to. + +@item +A string that determines the reason for cloning. + +@end enumerate + +In the case of call graph clone removal, the individual fields are: + +@enumerate +@item +String @code{Callgraph removal}. + +@item +Name of the function being removed as it would be presented to the assembler. + +@item +A number that uniquely represents the function being cloned in the call +graph. Note that the number is unique only within a compilation unit or +within whole-program analysis but is likely to be different in the two +phases. + +@item +The file name of the source file where the function is defined. + +@item +The line on which the function definition is located. + +@item +The column where the function definition is located. + +@end enumerate + @opindex fdump-lang @item -fdump-lang Dump language-specific information. The file name is made by appending @@ -20763,30 +21092,10 @@ Dump language-specific information. The file name is made by appending @itemx -fdump-lang-@var{switch}-@var{options}=@var{filename} Control the dumping of language-specific information. The @var{options} and @var{filename} portions behave as described in the -@option{-fdump-tree} option. The following @var{switch} values are -accepted: - -@table @samp -@item all - -Enable all language-specific dumps. - -@item class -Dump class hierarchy information. Virtual table information is emitted -unless '@option{slim}' is specified. This option is applicable to C++ only. - -@item module -Dump module information. Options @option{lineno} (locations), -@option{graph} (reachability), @option{blocks} (clusters), -@option{uid} (serialization), @option{alias} (mergeable), -@option{asmname} (Elrond), @option{eh} (mapper) & @option{vops} -(macros) may provide additional information. This option is -applicable to C++ only. - -@item raw -Dump the raw internal tree data. This option is applicable to C++ only. - -@end table +@option{-fdump-tree} option. @option{-fdump-tree-all} enables all +language-specific dumps; other options vary with the language. For +instance, see @xref{C++ Dialect Options} for the @option{-fdump-lang} +flags supported by the C++ front-end. @opindex fdump-passes @item -fdump-passes @@ -20855,8 +21164,7 @@ GraphViz to @file{@var{file}.@var{passid}.@var{pass}.dot}. Each function in the file is pretty-printed as a subgraph, so that GraphViz can render them all in a single plot. -This option currently only works for RTL dumps, and the RTL is always -dumped in slim form. +RTL is always dumped in slim form. @item vops Enable showing virtual operands for every statement. @item lineno @@ -21853,6 +22161,36 @@ used directly. The same applies when using @option{-mcpu=} when the selected cpu supports the @samp{lse} feature. This option is on by default. +@item -mmax-vectorization +@itemx -mno-max-vectorization +Enable or disable an override to vectorizer cost model making vectorization +always appear profitable. This option can be combined with +@option{-mautovec-preference} allowing precise control over which ISA will be +used for auto-vectorization. Unlike @option{-fno-vect-cost-model} or +@option{-fvect-cost-model=unlimited} this option does not turn off cost +comparison between different vector modes. + +@item -mautovec-preference=@var{name} +Force an ISA selection strategy for auto-vectorization. The possible +values of @var{name} are: +@table @samp +@item default +Use the default heuristics. +@item asimd-only +Use only Advanced SIMD for auto-vectorization. +@item sve-only +Use only SVE for auto-vectorization. +@item prefer-asimd +Use both Advanced SIMD and SVE. Prefer Advanced SIMD when the costs are +deemed equal. +@item prefer-sve +Use both Advanced SIMD and SVE. Prefer SVE when the costs are deemed equal. +@end table + +For best performance it is highly recommended to use @option{-mcpu} or +@option{-mtune} instead. This parameter should only be used for code +exploration. + @opindex march @item -march=@var{name} Specify the name of the target architecture and, optionally, one or @@ -21939,7 +22277,7 @@ performance of the code. Permissible values for this option are: The values @samp{cortex-a57.cortex-a53}, @samp{cortex-a72.cortex-a53}, @samp{cortex-a73.cortex-a35}, @samp{cortex-a73.cortex-a53}, @samp{cortex-a75.cortex-a55}, @samp{cortex-a76.cortex-a55}, -@samp{apple-m1}, @samp{apple-m2}, @samp{apple-m3} specify that GCC +@samp{apple-m1}, @samp{apple-m2}, @samp{apple-m3}, @samp{gb10} specify that GCC should tune for a big.LITTLE system. The value @samp{neoverse-512tvb} specifies that GCC should tune @@ -22228,6 +22566,9 @@ Enable the FlagM2 flag conversion instructions. Enable the Pointer Authentication Extension. @item cssc Enable the Common Short Sequence Compression instructions. +@item cmpbr +Enable the shorter compare and branch instructions, @code{cbb}, @code{cbh} and +@code{cb}. @item sme Enable the Scalable Matrix Extension. This is only supported when SVE2 is also enabled. @@ -22510,10 +22851,20 @@ Compile for CDNA2 Instinct MI200 series devices (gfx90a). @item gfx90c Compile for GCN5 Vega 7 devices (gfx90c). +@item gfx942 +Compile for CDNA3 Instinct MI300 series devices (gfx942). (Experimental) + +@item gfx950 +Compile for the CDNA3 gfx950 devices. (Experimental) + @item gfx9-generic Compile generic code for Vega devices, executable on the following subset of GFX9 devices: gfx900, gfx902, gfx904, gfx906, gfx909 and gfx90c. (Experimental) +@item gfx9-4-generic +Compile generic code for CDNA3 devices, executable on the following subset of +GFX9 devices: gfx942 and gfx950. (Experimental) + @item gfx1030 Compile for RDNA2 gfx1030 devices (GFX10 series). @@ -23393,7 +23744,7 @@ These @samp{-m} options are defined for the ARM port: @opindex mabi @item -mabi=@var{name} Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu}, -@samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}. +@samp{atpcs}, @samp{aapcs} and @samp{aapcs-linux}. @opindex mapcs-frame @item -mapcs-frame @@ -24772,6 +25123,10 @@ Valid values for @var{level} are in the range @code{0} @dots{} @code{23} which is a 3:2:2:2 mixed radix value. Each digit controls some aspect of the optimization. +@opindex mfuse-move2 +@item -mfuse-move2 +Run a post combine optimization pass that tries to fuse move instructions. + @opindex mstrict-X @item -mstrict-X Use address register @code{X} in a way proposed by the hardware. This means @@ -30571,6 +30926,7 @@ Generate code for the specified PTX ISA target architecture. Valid architecture strings are @samp{sm_30}, @samp{sm_35}, @samp{sm_37}, @samp{sm_52}, @samp{sm_53}, +@samp{sm_61}, @samp{sm_70}, @samp{sm_75}, @samp{sm_80}, and @samp{sm_89}. The default depends on how the compiler has been configured, see @@ -30597,6 +30953,7 @@ Generate code for the specified PTX ISA version. Valid version strings are @samp{3.1}, @samp{4.1}, @samp{4.2}, +@samp{5.0}, @samp{6.0}, @samp{6.3}, @samp{7.0}, @samp{7.3}, and @samp{7.8}. The default PTX ISA version is the one that added support for the @@ -30750,12 +31107,13 @@ to store the immediate to a register first. @opindex mcmodel= @opindex mcmodel=small @item -mcmodel=small -Generate OpenRISC code for the small model: The GOT is limited to 64k. This is -the default model. +Generate OpenRISC code for the small model: The GOT is limited to 64k and +function call jumps are limited to 64M offsets. This is the default model. @opindex mcmodel=large @item -mcmodel=large -Generate OpenRISC code for the large model: The GOT may grow up to 4G in size. +Generate OpenRISC code for the large model: The GOT may grow up to 4G in size +and function call jumps can target the full 4G address space. @end table @@ -30988,11 +31346,22 @@ The default is @option{-misa-spec=20191213} unless GCC has been configured with @option{--with-isa-spec=} specifying a different default version. @opindex march -@item -march=@var{ISA-string} -Generate code for given RISC-V ISA (e.g.@: @samp{rv64im}). ISA strings must be -lower-case. Examples include @samp{rv64i}, @samp{rv32g}, @samp{rv32e}, and -@samp{rv32imaf}. Additionally, a special value @option{help} -(@option{-march=help}) is accepted to list all supported extensions. +@item -march=@var{ISA-string|Profiles|Profile_ISA-string|help|unset} +Generate code for given RISC-V ISA or Profiles or a combination of them +(e.g.@: @samp{rv64im} @samp{rvi20u64} @samp{rvi20u64_zbb}). ISA strings and +Profiles must be lower-case. Examples include @samp{rv64i}, @samp{rv32g}, +@samp{rv32e}, @samp{rv32imaf}, @samp{rva22u64} and @samp{rva23u64}. +To combine Profiles and optional RISC-V ISA extention, the profile should start +at the beginning of the option, then use underline connect ISA-string (e.g.@: +@samp{rvi20u64_zca_zcb} @samp{rva23u64_zacas}). Additionally, a special value +@option{help} (@option{-march=help}) is accepted to list all supported +extensions. + +@samp{-march=unset} causes the compiler to ignore any @samp{-march=@dots{}} options +that appear earlier on the command line, behaving as if the option was never +passed. This is useful for ensuring that the architecture is taken from the +@samp{-mcpu} option, and it will result in an error if no @samp{-mcpu} option +is given when @samp{-march=unset} is used. The syntax of the ISA string is defined as follows: @@ -31011,493 +31380,8 @@ syntax @samp{<major>p<minor>} or @samp{<major>}, (e.g.@: @samp{m2p1} or @end table Supported extension are listed below: -@multitable @columnfractions .10 .10 .80 -@headitem Extension Name @tab Supported Version @tab Description -@item i -@tab 2.0, 2.1 -@tab Base integer extension. - -@item e -@tab 2.0 -@tab Reduced base integer extension. - -@item g -@tab - -@tab General-purpose computing base extension, @samp{g} will expand to -@samp{i}, @samp{m}, @samp{a}, @samp{f}, @samp{d}, @samp{zicsr} and -@samp{zifencei}. - -@item m -@tab 2.0 -@tab Integer multiplication and division extension. - -@item a -@tab 2.0, 2.1 -@tab Atomic extension. - -@item f -@tab 2.0, 2.2 -@tab Single-precision floating-point extension. - -@item d -@tab 2.0, 2.2 -@tab Double-precision floating-point extension. - -@item c -@tab 2.0 -@tab Compressed extension. - -@item h -@tab 1.0 -@tab Hypervisor extension. - -@item v -@tab 1.0 -@tab Vector extension. - -@item zicsr -@tab 2.0 -@tab Control and status register access extension. - -@item zifencei -@tab 2.0 -@tab Instruction-fetch fence extension. - -@item zicond -@tab 1.0 -@tab Integer conditional operations extension. - -@item za64rs -@tab 1.0 -@tab Reservation set size of 64 bytes. - -@item za128rs -@tab 1.0 -@tab Reservation set size of 128 bytes. - -@item zawrs -@tab 1.0 -@tab Wait-on-reservation-set extension. - -@item zba -@tab 1.0 -@tab Address calculation extension. - -@item zbb -@tab 1.0 -@tab Basic bit manipulation extension. - -@item zbc -@tab 1.0 -@tab Carry-less multiplication extension. - -@item zbs -@tab 1.0 -@tab Single-bit operation extension. - -@item zfinx -@tab 1.0 -@tab Single-precision floating-point in integer registers extension. - -@item zdinx -@tab 1.0 -@tab Double-precision floating-point in integer registers extension. -@item zhinx -@tab 1.0 -@tab Half-precision floating-point in integer registers extension. - -@item zhinxmin -@tab 1.0 -@tab Minimal half-precision floating-point in integer registers extension. - -@item zbkb -@tab 1.0 -@tab Cryptography bit-manipulation extension. - -@item zbkc -@tab 1.0 -@tab Cryptography carry-less multiply extension. - -@item zbkx -@tab 1.0 -@tab Cryptography crossbar permutation extension. - -@item zkne -@tab 1.0 -@tab AES Encryption extension. - -@item zknd -@tab 1.0 -@tab AES Decryption extension. - -@item zknh -@tab 1.0 -@tab Hash function extension. - -@item zkr -@tab 1.0 -@tab Entropy source extension. - -@item zksed -@tab 1.0 -@tab SM4 block cipher extension. - -@item zksh -@tab 1.0 -@tab SM3 hash function extension. - -@item zkt -@tab 1.0 -@tab Data independent execution latency extension. - -@item zk -@tab 1.0 -@tab Standard scalar cryptography extension. - -@item zkn -@tab 1.0 -@tab NIST algorithm suite extension. - -@item zks -@tab 1.0 -@tab ShangMi algorithm suite extension. - -@item zihintntl -@tab 1.0 -@tab Non-temporal locality hints extension. - -@item zihintpause -@tab 1.0 -@tab Pause hint extension. - -@item zicboz -@tab 1.0 -@tab Cache-block zero extension. - -@item zicbom -@tab 1.0 -@tab Cache-block management extension. - -@item zicbop -@tab 1.0 -@tab Cache-block prefetch extension. - -@item zic64b -@tab 1.0 -@tab Cache block size isf 64 bytes. - -@item ziccamoa -@tab 1.0 -@tab Main memory supports all atomics in A. - -@item ziccif -@tab 1.0 -@tab Main memory supports instruction fetch with atomicity requirement. - -@item zicclsm -@tab 1.0 -@tab Main memory supports misaligned loads/stores. - -@item ziccrse -@tab 1.0 -@tab Main memory supports forward progress on LR/SC sequences. - -@item zicntr -@tab 2.0 -@tab Standard extension for base counters and timers. - -@item zihpm -@tab 2.0 -@tab Standard extension for hardware performance counters. - -@item ztso -@tab 1.0 -@tab Total store ordering extension. - -@item zve32x -@tab 1.0 -@tab Vector extensions for embedded processors. - -@item zve32f -@tab 1.0 -@tab Vector extensions for embedded processors. - -@item zve64x -@tab 1.0 -@tab Vector extensions for embedded processors. - -@item zve64f -@tab 1.0 -@tab Vector extensions for embedded processors. - -@item zve64d -@tab 1.0 -@tab Vector extensions for embedded processors. - -@item zvl32b -@tab 1.0 -@tab Minimum vector length standard extensions - -@item zvl64b -@tab 1.0 -@tab Minimum vector length standard extensions - -@item zvl128b -@tab 1.0 -@tab Minimum vector length standard extensions - -@item zvl256b -@tab 1.0 -@tab Minimum vector length standard extensions - -@item zvl512b -@tab 1.0 -@tab Minimum vector length standard extensions - -@item zvl1024b -@tab 1.0 -@tab Minimum vector length standard extensions - -@item zvl2048b -@tab 1.0 -@tab Minimum vector length standard extensions - -@item zvl4096b -@tab 1.0 -@tab Minimum vector length standard extensions - -@item zvbb -@tab 1.0 -@tab Vector basic bit-manipulation extension. - -@item zvbc -@tab 1.0 -@tab Vector carryless multiplication extension. - -@item zvkb -@tab 1.0 -@tab Vector cryptography bit-manipulation extension. - -@item zvkg -@tab 1.0 -@tab Vector GCM/GMAC extension. - -@item zvkned -@tab 1.0 -@tab Vector AES block cipher extension. - -@item zvknha -@tab 1.0 -@tab Vector SHA-2 secure hash extension. - -@item zvknhb -@tab 1.0 -@tab Vector SHA-2 secure hash extension. - -@item zvksed -@tab 1.0 -@tab Vector SM4 Block Cipher extension. - -@item zvksh -@tab 1.0 -@tab Vector SM3 Secure Hash extension. - -@item zvkn -@tab 1.0 -@tab Vector NIST Algorithm Suite extension, @samp{zvkn} will expand to -@samp{zvkned}, @samp{zvknhb}, @samp{zvkb} and @samp{zvkt}. - -@item zvknc -@tab 1.0 -@tab Vector NIST Algorithm Suite with carryless multiply extension, @samp{zvknc} -will expand to @samp{zvkn} and @samp{zvbc}. - -@item zvkng -@tab 1.0 -@tab Vector NIST Algorithm Suite with GCM extension, @samp{zvkng} will expand -to @samp{zvkn} and @samp{zvkg}. - -@item zvks -@tab 1.0 -@tab Vector ShangMi algorithm suite extension, @samp{zvks} will expand -to @samp{zvksed}, @samp{zvksh}, @samp{zvkb} and @samp{zvkt}. - -@item zvksc -@tab 1.0 -@tab Vector ShangMi algorithm suite with carryless multiplication extension, -@samp{zvksc} will expand to @samp{zvks} and @samp{zvbc}. - -@item zvksg -@tab 1.0 -@tab Vector ShangMi algorithm suite with GCM extension, @samp{zvksg} will expand -to @samp{zvks} and @samp{zvkg}. - -@item zvkt -@tab 1.0 -@tab Vector data independent execution latency extension. - -@item zfh -@tab 1.0 -@tab Half-precision floating-point extension. - -@item zfhmin -@tab 1.0 -@tab Minimal half-precision floating-point extension. - -@item zvfh -@tab 1.0 -@tab Vector half-precision floating-point extension. - -@item zvfhmin -@tab 1.0 -@tab Vector minimal half-precision floating-point extension. - -@item zvfbfmin -@tab 1.0 -@tab Vector BF16 converts extension. - -@item zfa -@tab 1.0 -@tab Additional floating-point extension. - -@item zmmul -@tab 1.0 -@tab Integer multiplication extension. - -@item zca -@tab 1.0 -@tab Integer compressed instruction extension. - -@item zcf -@tab 1.0 -@tab Compressed single-precision floating point loads and stores extension. - -@item zcd -@tab 1.0 -@tab Compressed double-precision floating point loads and stores extension. - -@item zcb -@tab 1.0 -@tab Simple compressed instruction extension. - -@item zce -@tab 1.0 -@tab Compressed instruction extensions for embedded processors. - -@item zcmp -@tab 1.0 -@tab Compressed push pop extension. - -@item zcmt -@tab 1.0 -@tab Table jump instruction extension. - -@item smaia -@tab 1.0 -@tab Advanced interrupt architecture extension. - -@item smepmp -@tab 1.0 -@tab PMP Enhancements for memory access and execution prevention on Machine mode. - -@item smstateen -@tab 1.0 -@tab State enable extension. - -@item ssaia -@tab 1.0 -@tab Advanced interrupt architecture extension for supervisor-mode. - -@item sscofpmf -@tab 1.0 -@tab Count overflow & filtering extension. - -@item ssstateen -@tab 1.0 -@tab State-enable extension for supervisor-mode. - -@item sstc -@tab 1.0 -@tab Supervisor-mode timer interrupts extension. - -@item svinval -@tab 1.0 -@tab Fine-grained address-translation cache invalidation extension. - -@item svnapot -@tab 1.0 -@tab NAPOT translation contiguity extension. - -@item svpbmt -@tab 1.0 -@tab Page-based memory types extension. - -@item xcvmac -@tab 1.0 -@tab Core-V multiply-accumulate extension. - -@item xcvalu -@tab 1.0 -@tab Core-V miscellaneous ALU extension. - -@item xcvelw -@tab 1.0 -@tab Core-V event load word extension. - -@item xtheadba -@tab 1.0 -@tab T-head address calculation extension. - -@item xtheadbb -@tab 1.0 -@tab T-head basic bit-manipulation extension. - -@item xtheadbs -@tab 1.0 -@tab T-head single-bit instructions extension. - -@item xtheadcmo -@tab 1.0 -@tab T-head cache management operations extension. - -@item xtheadcondmov -@tab 1.0 -@tab T-head conditional move extension. - -@item xtheadfmemidx -@tab 1.0 -@tab T-head indexed memory operations for floating-point registers extension. - -@item xtheadfmv -@tab 1.0 -@tab T-head double floating-point high-bit data transmission extension. - -@item xtheadint -@tab 1.0 -@tab T-head acceleration interruption extension. - -@item xtheadmac -@tab 1.0 -@tab T-head multiply-accumulate extension. - -@item xtheadmemidx -@tab 1.0 -@tab T-head indexed memory operation extension. - -@item xtheadmempair -@tab 1.0 -@tab T-head two-GPR memory operation extension. - -@item xtheadsync -@tab 1.0 -@tab T-head multi-core synchronization extension. - -@item xventanacondops -@tab 1.0 -@tab Ventana integer conditional operations extension. - -@end multitable +@include riscv-ext.texi When @option{-march=} is not specified, use the setting from @option{-mcpu}. @@ -31509,31 +31393,14 @@ When the RISC-V specifications define an extension as depending on other extensions, GCC will implicitly add the dependent extensions to the enabled extension set if they weren't added explicitly. -@opindex mcpu -@item -mcpu=@var{processor-string} -Use architecture of and optimize the output for the given processor, specified -by particular CPU name. -Permissible values for this option are: @samp{sifive-e20}, @samp{sifive-e21}, -@samp{sifive-e24}, @samp{sifive-e31}, @samp{sifive-e34}, @samp{sifive-e76}, -@samp{sifive-s21}, @samp{sifive-s51}, @samp{sifive-s54}, @samp{sifive-s76}, -@samp{sifive-u54}, @samp{sifive-u74}, @samp{sifive-x280}, @samp{sifive-xp450}, -@samp{sifive-x670}, @samp{thead-c906}, @samp{tt-ascalon-d8}, @samp{xiangshan-nanhu}, -@samp{xt-c908}, @samp{xt-c908v}, @samp{xt-c910}, @samp{xt-c910v2}, -@samp{xt-c920}, @samp{xt-c920v2}. +@include riscv-mcpu.texi Note that @option{-mcpu} does not override @option{-march} or @option{-mtune}. -@opindex mtune -@item -mtune=@var{processor-string} -Optimize the output for the given processor, specified by microarchitecture or -particular CPU name. Permissible values for this option are: -@samp{generic-ooo}, @samp{rocket}, @samp{sifive-3-series}, -@samp{sifive-5-series}, @samp{sifive-7-series}, @samp{size}, -@samp{sifive-p400-series}, @samp{sifive-p600-series}, and all valid options for -@option{-mcpu=}. +@include riscv-mtune.texi When @option{-mtune=} is not specified, use the setting from @option{-mcpu}, -the default is @samp{rocket} if both are not specified. +the default is @samp{generic} if both are not specified. The @samp{size} choice is not intended for use by end-users. This is used when @option{-Os} is specified. It overrides the instruction cost info @@ -35067,37 +34934,36 @@ VPCLMULQDQ, AVX512BITALG, RDPID and AVX512VPOPCNTDQ instruction set support. Intel Alder Lake/Raptor Lake/Meteor Lake/Gracemont CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, AES, PREFETCHW, PCLMUL, RDRND, XSAVE, XSAVEC, XSAVES, XSAVEOPT, FSGSBASE, PTWRITE, RDPID, SGX, -GFNI-SSE, CLWB, MOVDIRI, MOVDIR64B, CLDEMOTE, WAITPKG, ADCX, AVX, AVX2, BMI, -BMI2, F16C, FMA, LZCNT, PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, -WIDEKL and AVX-VNNI instruction set support. +GFNI-SSE, CLWB, MOVDIRI, MOVDIR64B, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, +FMA, LZCNT, PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL and +AVX-VNNI instruction set support. @item arrowlake Intel Arrow Lake CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, AES, PREFETCHW, PCLMUL, RDRND, XSAVE, XSAVEC, XSAVES, XSAVEOPT, FSGSBASE, PTWRITE, RDPID, SGX, GFNI-SSE, CLWB, MOVDIRI, -MOVDIR64B, CLDEMOTE, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, LZCNT, -PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL, AVX-VNNI, -UINTR, AVXIFMA, AVXVNNIINT8, AVXNECONVERT and CMPCCXADD instruction set -support. +MOVDIR64B, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, LZCNT, PCONFIG, PKU, +VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL, AVX-VNNI, UINTR, AVXIFMA, +AVXVNNIINT8, AVXNECONVERT and CMPCCXADD instruction set support. @item arrowlake-s @itemx lunarlake Intel Arrow Lake S/Lunar Lake CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, AES, PREFETCHW, PCLMUL, RDRND, XSAVE, XSAVEC, XSAVES, XSAVEOPT, FSGSBASE, PTWRITE, RDPID, SGX, GFNI-SSE, CLWB, -MOVDIRI, MOVDIR64B, CLDEMOTE, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, -LZCNT, PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL, AVX-VNNI, -UINTR, AVXIFMA, AVXVNNIINT8, AVXNECONVERT, CMPCCXADD, AVXVNNIINT16, SHA512, -SM3 and SM4 instruction set support. +MOVDIRI, MOVDIR64B, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, LZCNT, +PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL, AVX-VNNI, UINTR, +AVXIFMA, AVXVNNIINT8, AVXNECONVERT, CMPCCXADD, AVXVNNIINT16, SHA512, SM3 and +SM4 instruction set support. @item pantherlake Intel Panther Lake CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, AES, PREFETCHW, PCLMUL, RDRND, XSAVE, XSAVEC, XSAVES, XSAVEOPT, FSGSBASE, PTWRITE, RDPID, SGX, GFNI-SSE, CLWB, MOVDIRI, -MOVDIR64B, CLDEMOTE, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, LZCNT, -PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL, AVX-VNNI, -UINTR, AVXIFMA, AVXVNNIINT8, AVXNECONVERT, CMPCCXADD, AVXVNNIINT16, SHA512, -SM3, SM4 and PREFETCHI instruction set support. +MOVDIR64B, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, LZCNT, PCONFIG, PKU, +VAES, VPCLMULQDQ, SERIALIZE, HRESET, AVX-VNNI, UINTR, AVXIFMA, AVXVNNIINT8, +AVXNECONVERT, CMPCCXADD, AVXVNNIINT16, SHA512, SM3, SM4 and PREFETCHI +instruction set support. @item sapphirerapids @itemx emeraldrapids @@ -35200,9 +35066,9 @@ Intel Clearwater Forest CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, AES, PREFETCHW, PCLMUL, RDRND, XSAVE, XSAVEC, XSAVES, XSAVEOPT, FSGSBASE, PTWRITE, RDPID, SGX, GFNI-SSE, CLWB, MOVDIRI, MOVDIR64B, CLDEMOTE, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, -LZCNT, PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL, AVX-VNNI, -ENQCMD, UINTR, AVXIFMA, AVXVNNIINT8, AVXNECONVERT, CMPCCXADD, AVXVNNIINT16, -SHA512, SM3, SM4, USER_MSR and PREFETCHI instruction set support. +LZCNT, PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, AVX-VNNI, ENQCMD, +UINTR, AVXIFMA, AVXVNNIINT8, AVXNECONVERT, CMPCCXADD, AVXVNNIINT16, SHA512, +SM3, SM4, USER_MSR and PREFETCHI instruction set support. @item k6 AMD K6 CPU with MMX instruction set support. @@ -35449,8 +35315,8 @@ Produce code optimized for the most current Intel processors, which are Haswell and Silvermont for this version of GCC. If you know the CPU on which your code will run, then you should use the corresponding @option{-mtune} or @option{-march} option instead of @option{-mtune=intel}. -But, if you want your application performs better on both Haswell and -Silvermont, then you should use this option. +But, if you want your application performs better on both Diamond Rapids +and Clearwater Forest, then you should use this option. As new Intel processors are deployed in the marketplace, the behavior of this option will change. Therefore, if you upgrade to a newer version of @@ -36092,12 +35958,6 @@ preferred alignment to @option{-mpreferred-stack-boundary=2}. @opindex mavx10.1 @itemx -mavx10.1 @need 200 -@opindex mavx10.1-256 -@itemx -mavx10.1-256 -@need 200 -@opindex mavx10.1-512 -@itemx -mavx10.1-512 -@need 200 @opindex mavx10.2 @itemx -mavx10.2 @need 200 @@ -36886,11 +36746,6 @@ To invoke egpr usage in inline asm, use new compiler option -mapx-inline-asm-use-gpr32 and user should ensure the instruction supports EGPR. -@opindex mevex512 -@item -mevex512 -@itemx -mno-evex512 -Enables/disables 512-bit vector. It will be default on if AVX512F is enabled. - @end table These @samp{-m} switches are supported in addition to the above diff --git a/gcc/doc/libgdiagnostics/topics/compatibility.rst b/gcc/doc/libgdiagnostics/topics/compatibility.rst new file mode 100644 index 0000000..ccf1236 --- /dev/null +++ b/gcc/doc/libgdiagnostics/topics/compatibility.rst @@ -0,0 +1,273 @@ +.. Copyright (C) 2015-2025 Free Software Foundation, Inc. + Originally contributed by David Malcolm <dmalcolm@redhat.com> + + This is free software: you can redistribute it and/or modify it + under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see + <https://www.gnu.org/licenses/>. + +.. default-domain:: c + +ABI and API compatibility +========================= + +The libgdiagnostics developers strive for ABI and API backward-compatibility: +programs built against libgdiagnostics.so stand a good chance of running +without recompilation against newer versions of libgdiagnostics.so, and +ought to recompile without modification against newer versions of +libgdiagnostics.h. + +.. note:: The libgdiagnostics++.h C++ API is more experimental, and less + locked-down at this time. + +API compatibility is achieved by extending the API rather than changing +it. For ABI compatiblity, we avoid bumping the SONAME, and instead use +symbol versioning to tag each symbol, so that a binary linked against +libgdiagnostics.so is tagged according to the symbols that it uses. + +For example, :func:`diagnostic_logical_location_get_kind` was added in +``LIBGDIAGNOSTICS_ABI_1``. If a client program uses it, this can be detected +from metadata by using ``objdump``: + +.. code-block:: bash + + $ objdump -p testsuite/libgdiagnostics/test-logical-location.c.exe | tail -n 7 + + Version References: + required from libc.so.6: + 0x09691a75 0x00 04 GLIBC_2.2.5 + required from libgdiagnostics.so.0: + 0x0ec567d1 0x00 03 LIBGDIAGNOSTICS_ABI_1 + 0x0ec567d0 0x00 02 LIBGDIAGNOSTICS_ABI_0 + +You can see the symbol tags provided by libgdiagnostics.so using ``objdump``: + +.. code-block:: bash + + $ objdump -p libgdiagnostics.so | less + [...snip...] + Version definitions: + 1 0x01 0x099ea4b0 libgdiagnostics.so.0 + 2 0x00 0x0ec567d0 LIBGDIAGNOSTICS_ABI_0 + 3 0x00 0x0ec567d1 LIBGDIAGNOSTICS_ABI_1 + LIBGDIAGNOSTICS_ABI_0 + [...snip...] + +ABI symbol tags +*************** + +.. _LIBGDIAGNOSTICS_ABI_0: + +``LIBGDIAGNOSTICS_ABI_0`` +------------------------- + +All entrypoints in the initial release of libgdiagnostics (in GCC 15) are +tagged with ``LIBGDIAGNOSTICS_ABI_0``; these entrypoints are: + + * :func:`diagnostic_manager_new` + + * :func:`diagnostic_manager_release` + + * :func:`diagnostic_manager_set_tool_name` + + * :func:`diagnostic_manager_set_full_name` + + * :func:`diagnostic_manager_set_version_string` + + * :func:`diagnostic_manager_set_version_url` + + * :func:`diagnostic_manager_add_text_sink` + + * :func:`diagnostic_text_sink_set_source_printing_enabled` + + * :func:`diagnostic_text_sink_set_colorize` + + * :func:`diagnostic_text_sink_set_labelled_source_colorization_enabled` + + * :func:`diagnostic_manager_add_sarif_sink` + + * :func:`diagnostic_manager_write_patch` + + * :func:`diagnostic_manager_new_file` + + * :func:`diagnostic_file_set_buffered_content` + + * :func:`diagnostic_manager_debug_dump_file` + + * :func:`diagnostic_manager_new_location_from_file_and_line` + + * :func:`diagnostic_manager_new_location_from_file_line_column` + + * :func:`diagnostic_manager_new_location_from_range` + + * :func:`diagnostic_manager_debug_dump_location` + + * :func:`diagnostic_manager_new_logical_location` + + * :func:`diagnostic_manager_debug_dump_logical_location` + + * :func:`diagnostic_manager_begin_group` + + * :func:`diagnostic_manager_end_group` + + * :func:`diagnostic_begin` + + * :func:`diagnostic_set_cwe` + + * :func:`diagnostic_add_rule` + + * :func:`diagnostic_set_location` + + * :func:`diagnostic_set_location_with_label` + + * :func:`diagnostic_add_location` + + * :func:`diagnostic_add_location_with_label` + + * :func:`diagnostic_set_logical_location` + + * :func:`diagnostic_add_fix_it_hint_insert_before` + + * :func:`diagnostic_add_fix_it_hint_insert_after` + + * :func:`diagnostic_add_fix_it_hint_replace` + + * :func:`diagnostic_add_fix_it_hint_delete` + + * :func:`diagnostic_add_execution_path` + + * :func:`diagnostic_manager_new_execution_path` + + * :func:`diagnostic_take_execution_path` + + * :func:`diagnostic_execution_path_release` + + * :func:`diagnostic_execution_path_add_event` + + * :func:`diagnostic_execution_path_add_event_va` + + * :func:`diagnostic_finish` + + * :func:`diagnostic_finish_va` + + * :func:`diagnostic_physical_location_get_file` + +.. _LIBGDIAGNOSTICS_ABI_1: + +``LIBGDIAGNOSTICS_ABI_1`` +------------------------- +``LIBGDIAGNOSTICS_ABI_1`` covers the addition of these functions for +acccessing values within a :type:`diagnostic_logical_location`: + + * :func:`diagnostic_logical_location_get_kind` + + * :func:`diagnostic_logical_location_get_parent` + + * :func:`diagnostic_logical_location_get_short_name` + + * :func:`diagnostic_logical_location_get_fully_qualified_name` + + * :func:`diagnostic_logical_location_get_decorated_name` + +.. _LIBGDIAGNOSTICS_ABI_2: + +``LIBGDIAGNOSTICS_ABI_2`` +------------------------- +``LIBGDIAGNOSTICS_ABI_2`` covers the addition of these functions for +supporting command-line options and SARIF playback: + + * :func:`diagnostic_manager_add_sink_from_spec` + + * :func:`diagnostic_manager_set_analysis_target` + +.. _LIBGDIAGNOSTICS_ABI_3: + +``LIBGDIAGNOSTICS_ABI_3`` +------------------------- + +``LIBGDIAGNOSTICS_ABI_3`` covers the addition of these functions for +working with directed graphs: + + * :func:`diagnostic_manager_new_graph` + + * :func:`diagnostic_manager_take_global_graph` + + * :func:`diagnostic_take_graph` + + * :func:`diagnostic_graph_release` + + * :func:`diagnostic_graph_set_description` + + * :func:`diagnostic_graph_add_node` + + * :func:`diagnostic_graph_add_edge` + + * :func:`diagnostic_graph_get_node_by_id` + + * :func:`diagnostic_graph_get_edge_by_id` + + * :func:`diagnostic_node_set_label` + + * :func:`diagnostic_node_set_location` + + * :func:`diagnostic_node_set_logical_location` + +.. _LIBGDIAGNOSTICS_ABI_4: + +``LIBGDIAGNOSTICS_ABI_4`` +------------------------- + +``LIBGDIAGNOSTICS_ABI_4`` covers the addition of these functions for +working with :type:`diagnostic_message_buffer`. + + * :func:`diagnostic_message_buffer_new` + + * :func:`diagnostic_message_buffer_release` + + * :func:`diagnostic_message_buffer_append_str` + + * :func:`diagnostic_message_buffer_append_text` + + * :func:`diagnostic_message_buffer_append_byte` + + * :func:`diagnostic_message_buffer_append_printf` + + * :func:`diagnostic_message_buffer_append_event_id` + + * :func:`diagnostic_message_buffer_begin_url` + + * :func:`diagnostic_message_buffer_end_url` + + * :func:`diagnostic_message_buffer_begin_quote` + + * :func:`diagnostic_message_buffer_end_quote` + + * :func:`diagnostic_message_buffer_begin_color` + + * :func:`diagnostic_message_buffer_end_color` + + * :func:`diagnostic_message_buffer_dump` + + * :func:`diagnostic_finish_via_msg_buf` + + * :func:`diagnostic_add_location_with_label_via_msg_buf` + + * :func:`diagnostic_execution_path_add_event_via_msg_buf` + +.. _LIBGDIAGNOSTICS_ABI_5: + +``LIBGDIAGNOSTICS_ABI_5`` +------------------------- + +``LIBGDIAGNOSTICS_ABI_5`` covers the addition of this function: + + * :func:`diagnostic_manager_set_debug_physical_locations` diff --git a/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst b/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst index d594b260..c94d19e 100644 --- a/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst +++ b/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst @@ -56,3 +56,45 @@ Responsibilities include: This will flush output to all of the output sinks, and clean up. The parameter must be non-NULL. + +.. function:: int diagnostic_manager_add_sink_from_spec (diagnostic_manager *affected_mgr, \ + const char *option_name, \ + const char *spec, \ + diagnostic_manager *control_mgr) + + This function can be used to support option processing similar to GCC's + `-fdiagnostics-add-output= <https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Message-Formatting-Options.html#index-fdiagnostics-add-output>`_. + This allows command-line tools to support the same domain-specific + language for specifying output sinks as GCC does. + + The function will attempt to parse ``spec`` as if it were + an argument to GCC's `-fdiagnostics-add-output= <https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Message-Formatting-Options.html#index-fdiagnostics-add-output>`_. + If successful, it will add an output sink to ``affected_mgr`` and return zero. + Otherwise, it will emit an error diagnostic to ``control_mgr`` and + return non-zero. + + ``affected_mgr`` and ``control_mgr`` can be the same manager, + or be different managers. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_2`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_manager_add_sink_from_spec + +.. function:: void diagnostic_manager_set_analysis_target (diagnostic_manager *mgr, \ + const diagnostic_file *file) + + This function sets the "main input file" of ``mgr`` to be + ``file``. + This affects the :code:`<title>` of generated HTML and + the :code:`role` of the :code:`artifact` in SARIF output + (`SARIF v2.1.0 section 3.24.6 <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790867>`_). + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_2`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_manager_set_analysis_target diff --git a/gcc/doc/libgdiagnostics/topics/diagnostics.rst b/gcc/doc/libgdiagnostics/topics/diagnostics.rst index 3d24da0..7454c6e 100644 --- a/gcc/doc/libgdiagnostics/topics/diagnostics.rst +++ b/gcc/doc/libgdiagnostics/topics/diagnostics.rst @@ -105,6 +105,24 @@ Diagnostics are All three parameters must be non-NULL. +.. function:: void diagnostic_finish_via_msg_buf (diagnostic *diag, \ + diagnostic_message_buffer *msg_buf) + + This is equivalent to :func:`diagnostic_finish`, but using a message + buffer rather than a format string and variadic arguments. + + ``diag`` and ``msg_buf`` must both be non-NULL. + + Calling this function transfers ownership of ``msg_buf`` to the + diagnostic - do not call :func:`diagnostic_message_buffer_release` on + it. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer Diagnostic groups ***************** diff --git a/gcc/doc/libgdiagnostics/topics/execution-paths.rst b/gcc/doc/libgdiagnostics/topics/execution-paths.rst index 321503f..8381c45 100644 --- a/gcc/doc/libgdiagnostics/topics/execution-paths.rst +++ b/gcc/doc/libgdiagnostics/topics/execution-paths.rst @@ -88,6 +88,28 @@ cross-references between events. In particular FIXME Equivalent to :func:`diagnostic_execution_path_add_event`, but using a :type:`va_list` rather than directly taking variadic arguments. +.. function:: diagnostic_event_id diagnostic_execution_path_add_event_via_msg_buf (diagnostic_execution_path *path, \ + const diagnostic_physical_location *physical_loc, \ + const diagnostic_logical_location *logical_loc, \ + unsigned stack_depth, + diagnostic_message_buffer *msg_buf) + + This is equivalent to :func:`diagnostic_execution_path_add_event` but + using a message buffer rather than a format string and variadic + arguments. + + ``path`` and ``msg_buf`` must both be non-NULL. + + Calling this function transfers ownership of ``msg_buf`` to the + path - do not call :func:`diagnostic_message_buffer_release` on it. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer + Paths are printed to text sinks, and for SARIF sinks each path is added as a ``codeFlow`` object (see SARIF 2.1.0 `§3.36 codeFlow object <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790990>`_). diff --git a/gcc/doc/libgdiagnostics/topics/graphs.rst b/gcc/doc/libgdiagnostics/topics/graphs.rst new file mode 100644 index 0000000..b976013 --- /dev/null +++ b/gcc/doc/libgdiagnostics/topics/graphs.rst @@ -0,0 +1,197 @@ +.. Copyright (C) 2025 Free Software Foundation, Inc. + Originally contributed by David Malcolm <dmalcolm@redhat.com> + + This is free software: you can redistribute it and/or modify it + under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see + <https://www.gnu.org/licenses/>. + +.. default-domain:: c + +Graphs +====== + +.. type:: diagnostic_graph + +SARIF has support for capturing directed graphs (such as callgraphs +and control flow graphs), both at the level of the run as a whole, +and at the level of individual results. + +libgdiagnostics supports this with the following entrypoints, allowing +directed graphs to be + +* created (with :func:`diagnostic_manager_new_graph`) + +* reported "globally" (with :func:`diagnostic_manager_take_global_graph`) + +* reported as part of a :type:`diagnostic` (with :func:`diagnostic_take_graph`), or + +* discarded (with :func:`diagnostic_graph_release`). + +.. function:: diagnostic_graph * diagnostic_manager_new_graph (diagnostic_manager *manager) + + Create a new directed graph. + + The resulting graph is owned by the caller and must have one of + :func:`diagnostic_manager_take_global_graph`, + :func:`diagnostic_take_graph`, + or :func:`diagnostic_graph_release` called on it to avoid leaks. + + The parameter ``manager`` must be non-null. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: void diagnostic_manager_take_global_graph (diagnostic_manager *manager, \ + diagnostic_graph *graph) + + Report this graph "globally", taking ownership of it. + This won't appear in text sinks, but in SARIF sinks the graph will be + added to theRun.graphs (SARIF v2.1.0 3.14.20). + + Parameters ``manager`` and ``graph`` must both be non-null. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: void diagnostic_take_graph (diagnostic *diag, \ + diagnostic_graph *graph) + + Add this graph to ``diag``, transferring ownership of it to ``diag``. + This won't appear in text sinks, but in SARIF sinks the graph will be + added to theResult.graphs (SARIF v2.1.0 3.27.19). + + Parameters ``diag`` and ``graph`` must both be non-null. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: void diagnostic_graph_release (diagnostic_graph *graph) + + Release ``graph`` which must still be owned by the caller + i.e. it must *not* have had + :func:`diagnostic_manager_take_global_graph` or + :func:`diagnostic_take_graph` called on it. + + Parameters ``graph`` can be null. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + + +.. function:: void diagnostic_graph_set_description (diagnostic_graph *graph, \ + const char *description) + + Set the description of ``graph`` for use in the value of the + SARIF ``description`` property (SARIF v2.1.0 section 3.39.2). + + The parameter ``graph`` must be non-null. + The parameter ``description`` can be null, for clearing any existing + description. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: diagnostic_node * diagnostic_graph_add_node (diagnostic_graph *graph, \ + const char *node_id, \ + diagnostic_node *parent_node) + + Create and add a new node within ``graph`` with the given `id``. + The id must be unique within nodes in ``graph``. + + The parameters ``graph`` and ``id`` must be non-null. + + ``parent_node`` can be NULL (for a top-level node in the graph), + or non-null for a child node, allowing for arbitrary nesting of + nodes. + + The new node is owned by ``graph``. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: diagnostic_edge * diagnostic_graph_add_edge (diagnostic_graph *graph, \ + const char *edge_id, \ + diagnostic_node *src_node, \ + diagnostic_node *dst_node, \ + const char *label) + + Create and add a new edge within ``graph``. + + The parameters ``graph``, ``src_node`` and ``dest_node`` + must be non-null. + + If non-null, then ``edge_id`` must be unique within ``graph``; + if ``edge_id`` is null then a unique id of the form "edge0", "edge1", + etc will be used automatically. + + If non-null, then ``label`` will be used for the value of the + SARIF ``label`` property (SARIF v2.1.0 section 3.41.3). + + The new edge is owned by ``graph``. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: diagnostic_node *diagnostic_graph_get_node_by_id (diagnostic_graph *graph, \ + const char *node_id) + + Get the node in ``graph`` with the given id, or null. + + The parameters ``graph`` and ``node_id`` must be non-null. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: diagnostic_edge *diagnostic_graph_get_edge_by_id (diagnostic_graph *graph, \ + const char *edge_id) + + Get the edge in ``graph`` with the given id, or null. + + The parameters ``graph`` and ``edge_id`` must be non-null. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + + +.. type:: diagnostic_node + +.. function:: void diagnostic_node_set_label (diagnostic_node *node, \ + const char *label) + + Set the label of ``node`` for use in the value of the + SARIF ``label`` property (SARIF v2.1.0 section 3.40.3). + + The parameter ``node`` must be non-null. + The parameter ``label`` can be null, for clearing any existing + label. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: void diagnostic_node_set_location (diagnostic_node *node, \ + const diagnostic_physical_location *loc) + + Set the physical location of ``node``, if any. + + The parameter ``node`` must be non-null. + The parameter ``loc`` can be null, for clearing any existing + location. + + If set, the value will be used by SARIF sinks within the + ``location`` property (SARIF v2.1.0 section 3.40.4). + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: void diagnostic_node_set_logical_location (diagnostic_node *node, \ + const diagnostic_logical_location *logical_loc) + + Set the logical location of ``node``, if any. + + The parameter ``node`` must be non-null. + The parameter ``logical_loc`` _can be null, for clearing any existing + location. + + If set, the value will be used by SARIF sinks within the + ``location`` property (SARIF v2.1.0 section 3.40.4). + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. diff --git a/gcc/doc/libgdiagnostics/topics/index.rst b/gcc/doc/libgdiagnostics/topics/index.rst index 6e14c0f..437ee05 100644 --- a/gcc/doc/libgdiagnostics/topics/index.rst +++ b/gcc/doc/libgdiagnostics/topics/index.rst @@ -28,6 +28,7 @@ Topic reference diagnostic-manager.rst diagnostics.rst message-formatting.rst + message-buffers.rst physical-locations.rst logical-locations.rst metadata.rst @@ -35,4 +36,6 @@ Topic reference execution-paths.rst text-output.rst sarif.rst + graphs.rst ux.rst + compatibility.rst diff --git a/gcc/doc/libgdiagnostics/topics/logical-locations.rst b/gcc/doc/libgdiagnostics/topics/logical-locations.rst index 3fbee83..294d396 100644 --- a/gcc/doc/libgdiagnostics/topics/logical-locations.rst +++ b/gcc/doc/libgdiagnostics/topics/logical-locations.rst @@ -51,6 +51,8 @@ source location This roughly corresponds to the ``kind`` property in SARIF v2.1.0 (`§3.33.7 <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790976>`_). + Kinds within executable code: + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_FUNCTION .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_MEMBER @@ -67,6 +69,32 @@ source location .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_VARIABLE + Kinds within XML or HTML documents: + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_ELEMENT + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_ATTRIBUTE + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_TEXT + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_COMMENT + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_PROCESSING_INSTRUCTION + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_DTD + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_DECLARATION + + Kinds within JSON documents: + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_OBJECT + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_ARRAY + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_PROPERTY + + .. macro:: DIAGNOSTIC_LOGICAL_LOCATION_KIND_VALUE + ``parent`` can be NULL; if non-NULL it can be used to express tree-like nesting of logical locations, such as in:: @@ -92,7 +120,7 @@ source location "equal" input values on the same :type:`diagnostic_manager` will return the same instance of :type:`diagnostic_logical_location`. "Equal" here includes different string buffers that compare as equal with - :func:``strcmp`. + :func:`strcmp`. .. function:: void diagnostic_manager_debug_dump_logical_location (const diagnostic_manager *diag_mgr, \ const diagnostic_logical_location *loc, \ @@ -113,3 +141,29 @@ Associating diagnostics with locations Set the logical location of ``diag``. ``diag`` must be non-NULL; ``logical_loc`` can be NULL. + +Accessors +********* + +The following functions can be used to access the data that was passed to a +:type:`diagnostic_logical_location` when it was created. In each case, the +``loc`` parameter must be non-NULL. The return values will point +at *copies* of the original buffer owned by the +:type:`diagnostic_logical_location`, or be null. + +.. function:: enum diagnostic_logical_location_kind_t diagnostic_logical_location_get_kind (const diagnostic_logical_location *loc) + +.. function:: const diagnostic_logical_location *diagnostic_logical_location_get_parent (const diagnostic_logical_location *loc) + +.. function:: const char *diagnostic_logical_location_get_short_name (const diagnostic_logical_location *loc) + +.. function:: const char *diagnostic_logical_location_get_fully_qualified_name (const diagnostic_logical_location *loc) + +.. function:: const char *diagnostic_logical_location_get_decorated_name (const diagnostic_logical_location *loc) + +The above accessors were added in :ref:`LIBGDIAGNOSTICS_ABI_1`; you can +test for their presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_LOGICAL_LOCATION_ACCESSORS diff --git a/gcc/doc/libgdiagnostics/topics/message-buffers.rst b/gcc/doc/libgdiagnostics/topics/message-buffers.rst new file mode 100644 index 0000000..c6f5851 --- /dev/null +++ b/gcc/doc/libgdiagnostics/topics/message-buffers.rst @@ -0,0 +1,310 @@ +.. Copyright (C) 2025 Free Software Foundation, Inc. + Originally contributed by David Malcolm <dmalcolm@redhat.com> + + This is free software: you can redistribute it and/or modify it + under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see + <https://www.gnu.org/licenses/>. + +.. default-domain:: c + +Message buffers +=============== + +.. type:: diagnostic_message_buffer + +A :type:`diagnostic_message_buffer` is a buffer into which text can be +accumulated, before being used: + +* as the message of a diagnostic, using :func:`diagnostic_finish_via_msg_buf` + +* as the text of a label for a :type:`diagnostic_physical_location` using + :func:`diagnostic_add_location_with_label_via_msg_buf` + +* as the text of an event within a :type:`diagnostic_execution_path` using + :func:`diagnostic_execution_path_add_event_via_msg_buf` + +This is to allow more flexible creation of messages than a "format string +plus variadic arguments" API. + +.. function:: diagnostic_message_buffer * diagnostic_message_buffer_new (void) + + This function creates a new :type:`diagnostic_message_buffer`. + + The caller is responsible for cleaning it up, either by handing it off + to one of the API entrypoints that takes ownership of it (such as + :func:`diagnostic_finish_via_msg_buf`), or by calling + :func:`diagnostic_message_buffer_release` on it. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_4`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer + +.. function:: void diagnostic_message_buffer_release (diagnostic_message_buffer *msg_buf) + + This function releases ``msg_buf``. + + Typically you don't need to call this, but instead will pass the + buffer to one of the API entrypoints that takes over ownership of + it (such as :func:`diagnostic_finish_via_msg_buf`); calling it + after this would lead to a double-free bug, as you no longer "own" + the buffer. + + ``msg_buf`` must be non-NULL. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_4`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer + +.. function:: void diagnostic_message_buffer_append_str (diagnostic_message_buffer *msg_buf, \ + const char *p) + + This function appends the null-terminated string ``p`` to the buffer. + The string is assumed to be UTF-8 encoded. + + ``msg_buf`` and ``p`` must both be non-NULL. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_4`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer + +.. function:: void diagnostic_message_buffer_append_text (diagnostic_message_buffer *msg_buf, \ + const char *p, \ + size_t len) + + This function appends ``len`` bytes from ``p`` to the buffer. + The bytes are assumed to be UTF-8 encoded. + + ``msg_buf`` and ``p`` must both be non-NULL. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_4`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer + +.. function:: void diagnostic_message_buffer_append_byte (diagnostic_message_buffer *msg_buf,\ + char ch) + + This function appends ``ch`` to the buffer. This should be either + ASCII, or part of UTF-8 encoded text. + + ``msg_buf`` must be non-NULL. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_4`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer + +.. function:: void diagnostic_message_buffer_append_printf (diagnostic_message_buffer *msg_buf, \ + const char *fmt, ...) + + This function appends a formatted string to the buffer, using the + formatting rules for ``printf``. + + The string is assumed to be UTF-8 encoded. + + ``msg_buf`` and ``fmt`` must both be non-NULL. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_4`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer + +.. function:: void diagnostic_message_buffer_append_event_id (diagnostic_message_buffer *msg_buf, \ + diagnostic_event_id event_id) + + This function appends a :type:`diagnostic_event_id` to the buffer. + + ``msg_buf`` must be non-NULL. + + For text output, the event will be printed in the form ``(1)``. + + This is analogous to the + :doc:`%@ message formatting code <message-formatting>`. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_4`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer + +Hyperlink support +***************** + +.. function:: void diagnostic_message_buffer_begin_url (diagnostic_message_buffer *msg_buf, \ + const char *url) + + This function indicates the beginning of a run of text that should be + associated with the given URL. The run of text should be closed with + a matching call to :func:`diagnostic_message_buffer_end_url`. + + ``msg_buf`` and ``url`` must both be non-NULL. + + For text output in a suitably modern terminal, the run of text will + be emitted as a clickable hyperlink to the URL. + + For SARIF sinks, the run of text will be emitted using SARIF's + embedded link syntax. + + This is analogous to the + :doc:`%{ message formatting code <message-formatting>`. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_4`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer + +.. function:: void diagnostic_message_buffer_end_url (diagnostic_message_buffer *msg_buf) + + This function ends a run of text within the buffer started with + :func:`diagnostic_message_buffer_begin_url`. + + ``msg_buf`` must be non-NULL. + + This is analogous to the + :doc:`%} message formatting code <message-formatting>`. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_4`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer + +Quoted text +*********** + +.. function:: void diagnostic_message_buffer_begin_quote (diagnostic_message_buffer *msg_buf) + + This function indicates the beginning of a run of text that should be + printed in quotes. The run of text should be closed with + a matching call to :func:`diagnostic_message_buffer_end_quote`. + + ``msg_buf`` must be non-NULL. + + For text output in a suitably modern terminal, the run of text will + appear in bold. + be emitted as a clickable hyperlink to the URL. + + For SARIF sinks, the run of text will be emitted using SARIF's + embedded link syntax. + + This is analogous to the + ``%<``:doc:`message formatting code <message-formatting>`. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_4`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer + +.. function:: void diagnostic_message_buffer_end_url (diagnostic_message_buffer *msg_buf) + + This function ends a run of text within the buffer started with + :func:`diagnostic_message_buffer_begin_url`. + + ``msg_buf`` must be non-NULL. + + This is analogous to the + :doc:`%> message formatting code <message-formatting>`. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_4`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer + +Color +***** + +.. function:: void diagnostic_message_buffer_begin_color (diagnostic_message_buffer *msg_buf, \ + const char *color) + + This function indicates the beginning of a run of text that should be + colorized as the given color. The run of text should be closed with + a matching call to :func:`diagnostic_message_buffer_end_color`. + + The precise set of available color names is currently undocumented. + + ``msg_buf`` and ``color`` must both be non-NULL. + + For text output in a suitable terminal, the run of text will + be colorized. + + For SARIF sinks, the run of text will be emitted using SARIF's + embedded link syntax. + + This is analogous to the + :doc:`%r message formatting code <message-formatting>`. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_4`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer + +.. function:: void diagnostic_message_buffer_end_color (diagnostic_message_buffer *msg_buf) + + This function ends a run of text within the buffer started with + :func:`diagnostic_message_buffer_begin_color`. + + ``msg_buf`` must be non-NULL. + + This is analogous to the + :doc:`%R message formatting code <message-formatting>`. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_4`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer + +Debugging a message buffer +************************** + +.. function:: void diagnostic_message_buffer_dump (const diagnostic_message_buffer *msg_buf, \ + FILE *outf) + + This function writes a representation of the contents of ``msg_buf`` + to ``outf``, for debugging. + + ``msg_buf`` can be NULL or non-NULL. + ``outf`` must be non-NULL. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_4`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer diff --git a/gcc/doc/libgdiagnostics/topics/message-formatting.rst b/gcc/doc/libgdiagnostics/topics/message-formatting.rst index 7064b70..803feba 100644 --- a/gcc/doc/libgdiagnostics/topics/message-formatting.rst +++ b/gcc/doc/libgdiagnostics/topics/message-formatting.rst @@ -23,6 +23,11 @@ Message formatting Various libgdiagnostics entrypoints take a format string and variadic arguments. +.. note:: + + See also :type:`diagnostic_message_buffer`, which offers an + alternative way to build up messages. + The format strings take codes prefixed by ``%``, or ``%q`` to put the result in quotes. For example:: diff --git a/gcc/doc/libgdiagnostics/topics/physical-locations.rst b/gcc/doc/libgdiagnostics/topics/physical-locations.rst index 099e27e..fcd81a0 100644 --- a/gcc/doc/libgdiagnostics/topics/physical-locations.rst +++ b/gcc/doc/libgdiagnostics/topics/physical-locations.rst @@ -284,3 +284,39 @@ This diagnostic has three locations | ~~ ^ ~~~~~ | | | | int const char * + +.. function:: void diagnostic_add_location_with_label_via_msg_buf (diagnostic *diag, \ + const diagnostic_physical_location *loc, \ + diagnostic_message_buffer *msg_buf) + + This is equivalent to :func:`diagnostic_add_location_with_label` but + using a message buffer rather than a text string. + + ``diag`` and ``msg_buf`` must both be non-NULL. + + Calling this function transfers ownership of ``msg_buf`` to the + diagnostic - do not call :func:`diagnostic_message_buffer_release` on + it. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer + +.. function:: void diagnostic_manager_set_debug_physical_locations (diagnostic_manager *mgr, \ + int value) + + Calling ``diagnostic_manager_set_debug_physical_locations (mgr, 1);`` + will lead to debugging information being printed to ``stderr`` when + creating :type:`diagnostic_physical_location` instances. + + The precise format of these messages is subject to change. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_5`; you can + test for its presence using + + .. code-block:: c + + #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_manager_set_debug_physical_locations diff --git a/gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst b/gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst index 95b95ca..e64b668 100644 --- a/gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst +++ b/gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst @@ -112,10 +112,10 @@ leading to output like this:: foo.c:17: error: can't find 'foo.h'" 17 | #include <foo.h> -where libgdiagnostics will attempt to load the source file and +where libgdiagnostics will attempt to load ``foo.c`` and quote the pertinent line. -If libgdiagnostics cannot open the file, it will merely print:: +If libgdiagnostics cannot open ``foo.c``, it will merely print:: foo.c:17: error: can't find 'foo.h' @@ -160,14 +160,15 @@ On compiling and running the program, we should get this output:: 17 | #include <foo.h> | ^~~~~ -where libgdiagnostics will attempt to load the source file and +where libgdiagnostics will attempt to load ``foo.c`` and underling the pertinent part of the given line. -If libgdiagnostics cannot open the file, it will merely print:: +If libgdiagnostics cannot open ``foo.c``, it will merely print:: foo.c:17:8: error: can't find 'foo.h' -A range can span multiple lines within the same file. +A range can span multiple lines within the same file, but cannot +span multiple files. As before, you can use :func:`diagnostic_manager_debug_dump_location` to dump the locations. For the above example:: diff --git a/gcc/doc/libgdiagnostics/tutorial/07-execution-paths.rst b/gcc/doc/libgdiagnostics/tutorial/07-execution-paths.rst index 0ac8bf0..9147171 100644 --- a/gcc/doc/libgdiagnostics/tutorial/07-execution-paths.rst +++ b/gcc/doc/libgdiagnostics/tutorial/07-execution-paths.rst @@ -134,8 +134,6 @@ Here's the above example in full: :end-before: end full example -Moving on -********* - -That's the end of the tutorial. For more information on libgdiagnostics, see -the :doc:`topic guide <../topics/index>`. +See the :doc:`guide to execution paths <../topics/execution-paths>` +for more information, or go on to +:doc:`the next section of the tutorial <08-message-buffers>`. diff --git a/gcc/doc/libgdiagnostics/tutorial/08-message-buffers.rst b/gcc/doc/libgdiagnostics/tutorial/08-message-buffers.rst new file mode 100644 index 0000000..a83c50c --- /dev/null +++ b/gcc/doc/libgdiagnostics/tutorial/08-message-buffers.rst @@ -0,0 +1,75 @@ +.. Copyright (C) 2025 Free Software Foundation, Inc. + Originally contributed by David Malcolm <dmalcolm@redhat.com> + + This is free software: you can redistribute it and/or modify it + under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see + <https://www.gnu.org/licenses/>. + +.. default-domain:: c + +Tutorial part 8: message buffers +================================ + +In previous examples, we finished a diagnostic with a call to +:func:`diagnostic_finish`, which takes a format string and arguments +to determine the text message of the diagnostic. + +Sometimes this approach is inconvenient, such as where you might want to +build up a message programatically from a series of components. +Additionally, you might have existing code that uses ``fprintf``, whereas +:func:`diagnostic_finish` has its +:doc:`own formatting conventions <../topics/message-formatting>` which are +:strong:`not` the same as printf. + +For this reason libgdiagnostics (from ``LIBGDIAGNOSTICS_ABI_3`` onwards) +supports :type:`diagnostic_message_buffer`, which can be used to accumulate a +message before using it. + +You create a :type:`diagnostic_message_buffer` using +:func:`diagnostic_message_buffer_new`. + +There are various API entrypoints for accumulating text into the buffer. + +For example: + +.. literalinclude:: ../../../testsuite/libgdiagnostics.dg/test-message-buffer.c + :language: c + :start-after: /* begin quoted source */ + :end-before: /* end quoted source */ + +Running this will produce this text output:: + +.. code-block:: console + + $ ./test-message-buffer.c.exe + ./test-message-buffer.c.exe: error: this is a string; foo; int: 42 str: mostly harmless; this is a link 'this is quoted' highlight A highlight B (1). + +where in a suitably-capable terminal if a text sink is directly +connected to a tty: + +* the ``this is a link`` will be a clickable hyperlink + (and the URL will be captured in SARIF output). + +* the quoted text will be in bold + +* the ``highlight A`` and ``highlight B`` text will be colorized + +* the event ID will be colorized (and will be a URL in SARIF output + if used within a :type:`diagnostic_execution_path`). + + +Moving on +********* + +That's the end of the tutorial. For more information on libgdiagnostics, see +the :doc:`topic guide <../topics/index>`. diff --git a/gcc/doc/libgdiagnostics/tutorial/index.rst b/gcc/doc/libgdiagnostics/tutorial/index.rst index 172a28c..09a15e9 100644 --- a/gcc/doc/libgdiagnostics/tutorial/index.rst +++ b/gcc/doc/libgdiagnostics/tutorial/index.rst @@ -30,3 +30,4 @@ The following tutorial gives an overview of how to use libgdiagnostics. 05-warnings.rst 06-fix-it-hints.rst 07-execution-paths.rst + 08-message-buffers.rst diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi index ae7a601..aba93f6 100644 --- a/gcc/doc/md.texi +++ b/gcc/doc/md.texi @@ -1366,6 +1366,12 @@ as for @samp{<} apply. A register operand is allowed provided that it is in a general register. +@cindex hard registers in constraint +@item @samp{@{r@}} +An operand is bound to hard register @samp{r} which may be any general, +floating-point, or vector register except a fixed register like a stack pointer +register. The set of fixed registers is target dependent. + @cindex constants in constraints @cindex @samp{i} in constraint @item @samp{i} @@ -2171,12 +2177,6 @@ VFP floating-point registers @code{d0}-@code{d31} and the appropriate subset @code{d0}-@code{d15} based on command line options. Used for 64 bit values only. Not valid for Thumb1. -@item y -The iWMMX co-processor registers. - -@item z -The iWMMX GR registers. - @item G The floating-point constant 0.0 @@ -2210,9 +2210,6 @@ A symbol in the text segment of the current file @item Uv A memory reference suitable for VFP load/store insns (reg+constant offset) -@item Uy -A memory reference suitable for iWMMXt load/store instructions. - @item Uq A memory reference suitable for the ARMv4 ldrsb instruction. @end table @@ -2927,6 +2924,9 @@ A signed 16-bit constant. A memory operand whose address is formed by a base register and offset that is suitable for use in instructions with the same addressing mode as @code{st.w} and @code{ld.w}. +@item q +A general-purpose register except for $r0 and $r1 (for the csrxchg +instruction) @item I A signed 12-bit constant (for arithmetic instructions). @item K @@ -3703,6 +3703,9 @@ RVC general purpose register (x8-x15). RVC floating-point registers (f8-f15), if available, reuse GPR as FPR when use zfinx. +@item cR +Even-odd RVC general purpose register pair. + @item R Even-odd general purpose register pair. @@ -5000,8 +5003,8 @@ This pattern is not allowed to @code{FAIL}. Like @samp{vec_load_lanes@var{m}@var{n}}, but takes an additional mask operand (operand 2) that specifies which elements of the destination vectors should be loaded. Other elements of the destination vectors are -taken from operand 3, which is an else operand similar to the one in -@code{maskload}. +taken from operand 3, which is an else operand in the subvector mode +@var{n}, similar to the one in @code{maskload}. The operation is equivalent to: @smallexample diff --git a/gcc/doc/riscv-ext.texi b/gcc/doc/riscv-ext.texi new file mode 100644 index 0000000..572b70e --- /dev/null +++ b/gcc/doc/riscv-ext.texi @@ -0,0 +1,721 @@ +@c Copyright (C) 2025 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc/doc/include/fdl.texi. + +@c This file is generated automatically using +@c gcc/config/riscv/gen-riscv-ext-texi.cc from: +@c gcc/config/riscv/riscv-ext.def +@c gcc/config/riscv/riscv-opts.h + +@c Please *DO NOT* edit manually. + +@multitable @columnfractions .10 .10 .80 +@headitem Extension Name @tab Supported Version @tab Description + +@item g +@tab - +@tab General-purpose computing base extension, @samp{g} will expand to +@samp{i}, @samp{m}, @samp{a}, @samp{f}, @samp{d}, @samp{zicsr} and +@samp{zifencei}. + +@item e +@tab 2.0 +@tab Reduced base integer extension + +@item i +@tab 2.0 2.1 +@tab Base integer extension + +@item m +@tab 2.0 +@tab Integer multiplication and division extension + +@item a +@tab 2.0 2.1 +@tab Atomic extension + +@item f +@tab 2.0 2.2 +@tab Single-precision floating-point extension + +@item d +@tab 2.0 2.2 +@tab Double-precision floating-point extension + +@item c +@tab 2.0 +@tab Compressed extension + +@item b +@tab 1.0 +@tab b extension + +@item v +@tab 1.0 +@tab Vector extension + +@item h +@tab 1.0 +@tab Hypervisor extension + +@item zic64b +@tab 1.0 +@tab Cache block size isf 64 bytes + +@item zicbom +@tab 1.0 +@tab Cache-block management extension + +@item zicbop +@tab 1.0 +@tab Cache-block prefetch extension + +@item zicboz +@tab 1.0 +@tab Cache-block zero extension + +@item ziccamoa +@tab 1.0 +@tab Main memory supports all atomics in A + +@item ziccif +@tab 1.0 +@tab Main memory supports instruction fetch with atomicity requirement + +@item zicclsm +@tab 1.0 +@tab Main memory supports misaligned loads/stores + +@item ziccrse +@tab 1.0 +@tab Main memory supports forward progress on LR/SC sequences + +@item zicfilp +@tab 1.0 +@tab zicfilp extension + +@item zicfiss +@tab 1.0 +@tab zicfiss extension + +@item zicntr +@tab 2.0 +@tab Standard extension for base counters and timers + +@item zicond +@tab 1.0 +@tab Integer conditional operations extension + +@item zicsr +@tab 2.0 +@tab Control and status register access extension + +@item zifencei +@tab 2.0 +@tab Instruction-fetch fence extension + +@item zihintntl +@tab 1.0 +@tab Non-temporal locality hints extension + +@item zihintpause +@tab 2.0 +@tab Pause hint extension + +@item zihpm +@tab 2.0 +@tab Standard extension for hardware performance counters + +@item zimop +@tab 1.0 +@tab zimop extension + +@item zilsd +@tab 1.0 +@tab Load/Store pair instructions extension + +@item zmmul +@tab 1.0 +@tab Integer multiplication extension + +@item za128rs +@tab 1.0 +@tab Reservation set size of 128 bytes + +@item za64rs +@tab 1.0 +@tab Reservation set size of 64 bytes + +@item zaamo +@tab 1.0 +@tab zaamo extension + +@item zabha +@tab 1.0 +@tab zabha extension + +@item zacas +@tab 1.0 +@tab zacas extension + +@item zalrsc +@tab 1.0 +@tab zalrsc extension + +@item zawrs +@tab 1.0 +@tab Wait-on-reservation-set extension + +@item zama16b +@tab 1.0 +@tab Zama16b extension, Misaligned loads, stores, and AMOs to main memory regions that do not cross a naturally aligned 16-byte boundary are atomic. + +@item zfa +@tab 1.0 +@tab Additional floating-point extension + +@item zfbfmin +@tab 1.0 +@tab zfbfmin extension + +@item zfh +@tab 1.0 +@tab Half-precision floating-point extension + +@item zfhmin +@tab 1.0 +@tab Minimal half-precision floating-point extension + +@item zfinx +@tab 1.0 +@tab Single-precision floating-point in integer registers extension + +@item zdinx +@tab 1.0 +@tab Double-precision floating-point in integer registers extension + +@item zca +@tab 1.0 +@tab Integer compressed instruction extension + +@item zcb +@tab 1.0 +@tab Simple compressed instruction extension + +@item zcd +@tab 1.0 +@tab Compressed double-precision floating point loads and stores extension + +@item zce +@tab 1.0 +@tab Compressed instruction extensions for embedded processors + +@item zcf +@tab 1.0 +@tab Compressed single-precision floating point loads and stores extension + +@item zcmop +@tab 1.0 +@tab zcmop extension + +@item zcmp +@tab 1.0 +@tab Compressed push pop extension + +@item zcmt +@tab 1.0 +@tab Table jump instruction extension + +@item zclsd +@tab 1.0 +@tab Compressed load/store pair instructions extension + +@item zba +@tab 1.0 +@tab Address calculation extension + +@item zbb +@tab 1.0 +@tab Basic bit manipulation extension + +@item zbc +@tab 1.0 +@tab Carry-less multiplication extension + +@item zbkb +@tab 1.0 +@tab Cryptography bit-manipulation extension + +@item zbkc +@tab 1.0 +@tab Cryptography carry-less multiply extension + +@item zbkx +@tab 1.0 +@tab Cryptography crossbar permutation extension + +@item zbs +@tab 1.0 +@tab Single-bit operation extension + +@item zk +@tab 1.0 +@tab Standard scalar cryptography extension + +@item zkn +@tab 1.0 +@tab NIST algorithm suite extension + +@item zknd +@tab 1.0 +@tab AES Decryption extension + +@item zkne +@tab 1.0 +@tab AES Encryption extension + +@item zknh +@tab 1.0 +@tab Hash function extension + +@item zkr +@tab 1.0 +@tab Entropy source extension + +@item zks +@tab 1.0 +@tab ShangMi algorithm suite extension + +@item zksed +@tab 1.0 +@tab SM4 block cipher extension + +@item zksh +@tab 1.0 +@tab SM3 hash function extension + +@item zkt +@tab 1.0 +@tab Data independent execution latency extension + +@item ztso +@tab 1.0 +@tab Total store ordering extension + +@item zvbb +@tab 1.0 +@tab Vector basic bit-manipulation extension + +@item zvbc +@tab 1.0 +@tab Vector carryless multiplication extension + +@item zve32f +@tab 1.0 +@tab Vector extensions for embedded processors + +@item zve32x +@tab 1.0 +@tab Vector extensions for embedded processors + +@item zve64d +@tab 1.0 +@tab Vector extensions for embedded processors + +@item zve64f +@tab 1.0 +@tab Vector extensions for embedded processors + +@item zve64x +@tab 1.0 +@tab Vector extensions for embedded processors + +@item zvfbfmin +@tab 1.0 +@tab Vector BF16 converts extension + +@item zvfbfwma +@tab 1.0 +@tab zvfbfwma extension + +@item zvfh +@tab 1.0 +@tab Vector half-precision floating-point extension + +@item zvfhmin +@tab 1.0 +@tab Vector minimal half-precision floating-point extension + +@item zvkb +@tab 1.0 +@tab Vector cryptography bit-manipulation extension + +@item zvkg +@tab 1.0 +@tab Vector GCM/GMAC extension + +@item zvkn +@tab 1.0 +@tab Vector NIST Algorithm Suite extension, @samp{zvkn} will expand to + +@item zvknc +@tab 1.0 +@tab Vector NIST Algorithm Suite with carryless multiply extension, @samp{zvknc} + +@item zvkned +@tab 1.0 +@tab Vector AES block cipher extension + +@item zvkng +@tab 1.0 +@tab Vector NIST Algorithm Suite with GCM extension, @samp{zvkng} will expand + +@item zvknha +@tab 1.0 +@tab Vector SHA-2 secure hash extension + +@item zvknhb +@tab 1.0 +@tab Vector SHA-2 secure hash extension + +@item zvks +@tab 1.0 +@tab Vector ShangMi algorithm suite extension, @samp{zvks} will expand + +@item zvksc +@tab 1.0 +@tab Vector ShangMi algorithm suite with carryless multiplication extension, + +@item zvksed +@tab 1.0 +@tab Vector SM4 Block Cipher extension + +@item zvksg +@tab 1.0 +@tab Vector ShangMi algorithm suite with GCM extension, @samp{zvksg} will expand + +@item zvksh +@tab 1.0 +@tab Vector SM3 Secure Hash extension + +@item zvkt +@tab 1.0 +@tab Vector data independent execution latency extension + +@item zvl1024b +@tab 1.0 +@tab Minimum vector length standard extensions + +@item zvl128b +@tab 1.0 +@tab Minimum vector length standard extensions + +@item zvl16384b +@tab 1.0 +@tab zvl16384b extension + +@item zvl2048b +@tab 1.0 +@tab Minimum vector length standard extensions + +@item zvl256b +@tab 1.0 +@tab Minimum vector length standard extensions + +@item zvl32768b +@tab 1.0 +@tab zvl32768b extension + +@item zvl32b +@tab 1.0 +@tab Minimum vector length standard extensions + +@item zvl4096b +@tab 1.0 +@tab Minimum vector length standard extensions + +@item zvl512b +@tab 1.0 +@tab Minimum vector length standard extensions + +@item zvl64b +@tab 1.0 +@tab Minimum vector length standard extensions + +@item zvl65536b +@tab 1.0 +@tab zvl65536b extension + +@item zvl8192b +@tab 1.0 +@tab zvl8192b extension + +@item zhinx +@tab 1.0 +@tab Half-precision floating-point in integer registers extension + +@item zhinxmin +@tab 1.0 +@tab Minimal half-precision floating-point in integer registers extension + +@item sdtrig +@tab 1.0 +@tab sdtrig extension + +@item sha +@tab 1.0 +@tab The augmented hypervisor extension + +@item shcounterenw +@tab 1.0 +@tab Support writeable enables for any supported counter + +@item shgatpa +@tab 1.0 +@tab SvNNx4 mode supported for all modes supported by satp + +@item shlcofideleg +@tab 1.0 +@tab Delegating LCOFI interrupts to VS-mode + +@item shtvala +@tab 1.0 +@tab The htval register provides all needed values + +@item shvstvala +@tab 1.0 +@tab The vstval register provides all needed values + +@item shvstvecd +@tab 1.0 +@tab The vstvec register supports Direct mode + +@item shvsatpa +@tab 1.0 +@tab The vsatp register supports all modes supported by satp + +@item smaia +@tab 1.0 +@tab Advanced interrupt architecture extension + +@item smcntrpmf +@tab 1.0 +@tab Cycle and instret privilege mode filtering + +@item smcsrind +@tab 1.0 +@tab Machine-Level Indirect CSR Access + +@item smepmp +@tab 1.0 +@tab PMP Enhancements for memory access and execution prevention on Machine mode + +@item smmpm +@tab 1.0 +@tab smmpm extension + +@item smnpm +@tab 1.0 +@tab smnpm extension + +@item smrnmi +@tab 1.0 +@tab Resumable non-maskable interrupts + +@item smstateen +@tab 1.0 +@tab State enable extension + +@item smdbltrp +@tab 1.0 +@tab Double Trap Extensions + +@item ssaia +@tab 1.0 +@tab Advanced interrupt architecture extension for supervisor-mode + +@item ssccptr +@tab 1.0 +@tab Main memory supports page table reads + +@item sscofpmf +@tab 1.0 +@tab Count overflow & filtering extension + +@item sscounterenw +@tab 1.0 +@tab Support writeable enables for any supported counter + +@item sscsrind +@tab 1.0 +@tab Supervisor-Level Indirect CSR Access + +@item ssnpm +@tab 1.0 +@tab ssnpm extension + +@item sspm +@tab 1.0 +@tab sspm extension + +@item ssstateen +@tab 1.0 +@tab State-enable extension for supervisor-mode + +@item sstc +@tab 1.0 +@tab Supervisor-mode timer interrupts extension + +@item sstvala +@tab 1.0 +@tab Stval provides all needed values + +@item sstvecd +@tab 1.0 +@tab Stvec supports Direct mode + +@item ssstrict +@tab 1.0 +@tab ssstrict extension + +@item ssdbltrp +@tab 1.0 +@tab Double Trap Extensions + +@item ssu64xl +@tab 1.0 +@tab UXLEN=64 must be supported + +@item supm +@tab 1.0 +@tab supm extension + +@item svinval +@tab 1.0 +@tab Fine-grained address-translation cache invalidation extension + +@item svnapot +@tab 1.0 +@tab NAPOT translation contiguity extension + +@item svpbmt +@tab 1.0 +@tab Page-based memory types extension + +@item svvptc +@tab 1.0 +@tab svvptc extension + +@item svadu +@tab 1.0 +@tab Hardware Updating of A/D Bits extension + +@item svade +@tab 1.0 +@tab Cause exception when hardware updating of A/D bits is disabled + +@item svbare +@tab 1.0 +@tab Satp mode bare is supported + +@item xcvalu +@tab 1.0 +@tab Core-V miscellaneous ALU extension + +@item xcvbi +@tab 1.0 +@tab xcvbi extension + +@item xcvelw +@tab 1.0 +@tab Core-V event load word extension + +@item xcvmac +@tab 1.0 +@tab Core-V multiply-accumulate extension + +@item xcvsimd +@tab 1.0 +@tab xcvsimd extension + +@item xsfcease +@tab 1.0 +@tab xsfcease extension + +@item xsfvcp +@tab 1.0 +@tab xsfvcp extension + +@item xsfvfnrclipxfqf +@tab 1.0 +@tab xsfvfnrclipxfqf extension + +@item xsfvqmaccdod +@tab 1.0 +@tab xsfvqmaccdod extension + +@item xsfvqmaccqoq +@tab 1.0 +@tab xsfvqmaccqoq extension + +@item xtheadba +@tab 1.0 +@tab T-head address calculation extension + +@item xtheadbb +@tab 1.0 +@tab T-head basic bit-manipulation extension + +@item xtheadbs +@tab 1.0 +@tab T-head single-bit instructions extension + +@item xtheadcmo +@tab 1.0 +@tab T-head cache management operations extension + +@item xtheadcondmov +@tab 1.0 +@tab T-head conditional move extension + +@item xtheadfmemidx +@tab 1.0 +@tab T-head indexed memory operations for floating-point registers extension + +@item xtheadfmv +@tab 1.0 +@tab T-head double floating-point high-bit data transmission extension + +@item xtheadint +@tab 1.0 +@tab T-head acceleration interruption extension + +@item xtheadmac +@tab 1.0 +@tab T-head multiply-accumulate extension + +@item xtheadmemidx +@tab 1.0 +@tab T-head indexed memory operation extension + +@item xtheadmempair +@tab 1.0 +@tab T-head two-GPR memory operation extension + +@item xtheadsync +@tab 1.0 +@tab T-head multi-core synchronization extension + +@item xtheadvector +@tab 1.0 +@tab xtheadvector extension + +@item xventanacondops +@tab 1.0 +@tab Ventana integer conditional operations extension + +@item xmipscmov +@tab 1.0 +@tab Mips conditional move extension + +@end multitable diff --git a/gcc/doc/riscv-mcpu.texi b/gcc/doc/riscv-mcpu.texi new file mode 100644 index 0000000..6753e51 --- /dev/null +++ b/gcc/doc/riscv-mcpu.texi @@ -0,0 +1,69 @@ +@c Copyright (C) 2025 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc/doc/include/fdl.texi. + +@c This file is generated automatically using +@c gcc/config/riscv/gen-riscv-mcpu-texi.cc from: +@c gcc/config/riscv/riscv-cores.def + +@c Please *DO NOT* edit manually. + +@samp{Core Name} + +@opindex mcpu +@item -mcpu=@var{processor-string} +Use architecture of and optimize the output for the given processor, specified +by particular CPU name. Permissible values for this option are: + + +@samp{sifive-e20}, + +@samp{sifive-e21}, + +@samp{sifive-e24}, + +@samp{sifive-e31}, + +@samp{sifive-e34}, + +@samp{sifive-e76}, + +@samp{sifive-s21}, + +@samp{sifive-s51}, + +@samp{sifive-s54}, + +@samp{sifive-s76}, + +@samp{sifive-u54}, + +@samp{sifive-u74}, + +@samp{sifive-x280}, + +@samp{sifive-p450}, + +@samp{sifive-p670}, + +@samp{thead-c906}, + +@samp{xt-c908}, + +@samp{xt-c908v}, + +@samp{xt-c910}, + +@samp{xt-c910v2}, + +@samp{xt-c920}, + +@samp{xt-c920v2}, + +@samp{tt-ascalon-d8}, + +@samp{xiangshan-nanhu}, + +@samp{xiangshan-kunminghu}, + +@samp{mips-p8700}. diff --git a/gcc/doc/riscv-mtune.texi b/gcc/doc/riscv-mtune.texi new file mode 100644 index 0000000..a2a4d3e --- /dev/null +++ b/gcc/doc/riscv-mtune.texi @@ -0,0 +1,59 @@ +@c Copyright (C) 2025 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc/doc/include/fdl.texi. + +@c This file is generated automatically using +@c gcc/config/riscv/gen-riscv-mtune-texi.cc from: +@c gcc/config/riscv/riscv-cores.def + +@c Please *DO NOT* edit manually. + +@samp{Tune Name} + +@opindex mtune +@item -mtune=@var{processor-string} +Optimize the output for the given processor, specified by microarchitecture or +particular CPU name. Permissible values for this option are: + + +@samp{generic}, + +@samp{rocket}, + +@samp{sifive-3-series}, + +@samp{sifive-5-series}, + +@samp{sifive-7-series}, + +@samp{sifive-p400-series}, + +@samp{sifive-p600-series}, + +@samp{tt-ascalon-d8}, + +@samp{thead-c906}, + +@samp{xt-c908}, + +@samp{xt-c908v}, + +@samp{xt-c910}, + +@samp{xt-c910v2}, + +@samp{xt-c920}, + +@samp{xt-c920v2}, + +@samp{xiangshan-nanhu}, + +@samp{xiangshan-kunminghu}, + +@samp{generic-ooo}, + +@samp{size}, + +@samp{mips-p8700}, + +and all valid options for @option{-mcpu=}. diff --git a/gcc/doc/sourcebuild.texi b/gcc/doc/sourcebuild.texi index c29cd3f..a919304 100644 --- a/gcc/doc/sourcebuild.texi +++ b/gcc/doc/sourcebuild.texi @@ -215,10 +215,10 @@ man pages and support for converting the installation manual to HTML@. @xref{Documentation}. @item ginclude -System headers installed by GCC, mainly those required by the C -standard of freestanding implementations. @xref{Headers, , Headers -Installed by GCC}, for details of when these and other headers are -installed. +System headers installed by GCC, mainly those defined by the C +standard that do not declare functions with external linkage. +@xref{Headers, , Headers Installed by GCC}, for details of when these +and other headers are installed. @item po Message catalogs with translations of messages produced by GCC into @@ -326,7 +326,8 @@ Headers Installed by GCC}, for more information about the In general, GCC expects the system C library to provide most of the headers to be used with it. However, GCC will fix those headers if necessary to make them work with GCC, and will install some headers -required of freestanding implementations. These headers are installed +of its own, mainly headers that do not declare functions with external +linkage. These headers are installed in @file{@var{libsubdir}/include}. Headers for non-C runtime libraries are also installed by GCC; these are not documented here. (FIXME: document them somewhere.) @@ -351,8 +352,8 @@ representation of floating point numbers. GCC also installs its own version of @code{<limits.h>}; this is generated from @file{glimits.h}, together with @file{limitx.h} and @file{limity.h} if the system also has its own version of -@code{<limits.h>}. (GCC provides its own header because it is -required of ISO C freestanding implementations, but needs to include +@code{<limits.h>}. (GCC provides its own header because it does not +declare functions with external linkage, but needs to include the system header from its own header as well because other standards such as POSIX specify additional values to be defined in @code{<limits.h>}.) The system's @code{<limits.h>} header is used via @@ -1975,6 +1976,9 @@ at plain @option{-O2}. @item tls Target supports thread-local storage. +@item tls_link +Target supports linking TLS executables. + @item tls_native Target supports native (rather than emulated) thread-local storage. @@ -2042,10 +2046,6 @@ ARM target uses emulated floating point operations. ARM target supports @code{-mfpu=vfp -mfloat-abi=hard}. Some multilibs may be incompatible with these options. -@item arm_iwmmxt_ok -ARM target supports @code{-mcpu=iwmmxt}. -Some multilibs may be incompatible with this option. - @item arm_neon ARM target supports generating NEON instructions. @@ -2373,6 +2373,15 @@ whether it does so by default). @itemx aarch64_sve1024_hw @itemx aarch64_sve2048_hw Like @code{aarch64_sve_hw}, but also test for an exact hardware vector length. +@item aarch64_sve2_hw +AArch64 target that is able to generate and execute SVE2 code (regardless of +whether it does so by default). +@item aarch64_sve2p1_hw +AArch64 target that is able to generate and execute SVE2.1 code (regardless of +whether it does so by default). +@item aarch64_sme_hw +AArch64 target that is able to generate and execute SME code (regardless of +whether it does so by default). @item aarch64_fjcvtzs_hw AArch64 target that is able to generate and execute armv8.3-a FJCVTZS @@ -2623,15 +2632,9 @@ Target supports compiling @code{avx} instructions. @item avx_runtime Target supports the execution of @code{avx} instructions. -@item avx10.1-256 -Target supports the execution of @code{avx10.1-256} instructions. - @item avx10.1 Target supports the execution of @code{avx10.1} instructions. -@item avx10.1-512 -Target supports the execution of @code{avx10.1-512} instructions. - @item avx10.2 Target supports the execution of @code{avx10.2} instructions. @@ -2957,6 +2960,9 @@ Target supports @code{sysconf}. @item trampolines Target supports trampolines. +@item variadic_mi_thunk +Target supports C++ virtual variadic function calls with multiple inheritance. + @item two_plus_gigs Target supports linking programs with 2+GiB of data. @@ -3012,6 +3018,9 @@ Note that this is orthogonal to effective-target @code{exceptions_enabled}. Testing configuration has exception handling enabled. Note that this is orthogonal to effective-target @code{exceptions}. +@item using_sjlj_exceptions +Target uses @code{setjmp} and @code{longjmp} for implementing exceptions. + @item fgraphite Target supports Graphite optimizations. diff --git a/gcc/doc/standards.texi b/gcc/doc/standards.texi index bbae350..0d765b1 100644 --- a/gcc/doc/standards.texi +++ b/gcc/doc/standards.texi @@ -96,8 +96,8 @@ A new edition of the ISO C standard was published in 1999 as ISO/IEC development, drafts of this standard version were referred to as @dfn{C9X}.) GCC has substantially complete support for this standard version; see -@uref{https://gcc.gnu.org/c99status.html} for details. To select this -standard, use @option{-std=c99} or @option{-std=iso9899:1999}. +@uref{https://gcc.gnu.org/projects/c-status.html} for details. To select +this standard, use @option{-std=c99} or @option{-std=iso9899:1999}. Errors in the 1999 ISO C standard were corrected in three Technical Corrigenda published in 2001, 2004 and 2007. GCC does not support the @@ -152,7 +152,9 @@ library facilities: those in @code{<float.h>}, @code{<limits.h>}, @code{<iso646.h>}; since C99, also those in @code{<stdbool.h>} and @code{<stdint.h>}; and since C11, also those in @code{<stdalign.h>} and @code{<stdnoreturn.h>}. In addition, complex types, added in C99, are not -required for freestanding implementations. +required for freestanding implementations. Since C23, freestanding +implementations are required to support a larger range of library +facilities, including some functions from other headers. The standard also defines two environments for programs, a @dfn{freestanding environment}, required of all implementations and @@ -167,13 +169,13 @@ a program using the facilities of an operating system is an example of a program running in a hosted environment. @opindex ffreestanding -GCC aims towards being usable as a conforming freestanding -implementation, or as the compiler for a conforming hosted -implementation. By default, it acts as the compiler for a hosted +GCC aims towards being usable as the compiler for a conforming +freestanding or hosted implementation. +By default, it acts as the compiler for a hosted implementation, defining @code{__STDC_HOSTED__} as @code{1} and presuming that when the names of ISO C functions are used, they have -the semantics defined in the standard. To make it act as a conforming -freestanding implementation for a freestanding environment, use the +the semantics defined in the standard. To make it act as the compiler +for a freestanding environment, use the option @option{-ffreestanding}; it then defines @code{__STDC_HOSTED__} to @code{0} and does not make assumptions about the meanings of function names from the standard library, with exceptions @@ -181,12 +183,24 @@ noted below. To build an OS kernel, you may well still need to make your own arrangements for linking and startup. @xref{C Dialect Options,,Options Controlling C Dialect}. -GCC does not provide the library facilities required only of hosted -implementations, nor yet all the facilities required by C99 of -freestanding implementations on all platforms. -To use the facilities of a hosted -environment, you need to find them elsewhere (for example, in the -GNU C library). @xref{Standard Libraries,,Standard Libraries}. +GCC generally provides library facilities in headers that do not +declare functions with external linkage (which includes the headers +required by C11 and before to be provided by freestanding +implementations), but not those included in other headers. +Additionally, GCC provides @code{<stdatomic.h>}, even though it +declares some functions with external linkage (which are provided in +@code{libatomic}). On a few platforms, some of the headers not +declaring functions with external linkage are instead obtained from +the OS's C library, which may mean that they lack support for features +from more recent versions of the C standard that are supported in +GCC's own versions of those headers. On some platforms, GCC provides +@code{<tgmath.h>} (but this implementation does not support interfaces +added in C23). + +To use the facilities of a hosted environment, and some of the +facilities required in a freestanding environment by C23, you need to +find them elsewhere (for example, in the GNU C library). +@xref{Standard Libraries,,Standard Libraries}. Most of the compiler support routines used by GCC are present in @file{libgcc}, but there are a few exceptions. GCC requires the diff --git a/gcc/doc/tm.texi b/gcc/doc/tm.texi index a96700c..4c338c3 100644 --- a/gcc/doc/tm.texi +++ b/gcc/doc/tm.texi @@ -37,6 +37,8 @@ through the macros defined in the @file{.h} file. * Trampolines:: Code set up at run time to enter a nested function. * Library Calls:: Controlling how library routines are implicitly called. * Addressing Modes:: Defining addressing modes valid for memory operands. +* Vectorization:: Controlling how the vectorizer operates. +* OpenMP and OpenACC:: Defining how OpenMP and OpenACC features should work. * Anchored Addresses:: Defining how @option{-fsection-anchors} should work. * Condition Code:: Defining how insns update the condition code. * Costs:: Defining relative costs of different operations. @@ -1424,10 +1426,10 @@ the smaller of @var{computed} and @code{BIGGEST_ALIGNMENT} @defmac MAX_FIXED_MODE_SIZE An integer expression for the size in bits of the largest integer -machine mode that should actually be used. All integer machine modes of -this size or smaller can be used for structures and unions with the -appropriate sizes. If this macro is undefined, @code{GET_MODE_BITSIZE -(DImode)} is assumed. +machine mode that should actually be used by GCC internally. +All integer machine modes of this size or smaller can be used for +structures and unions with the appropriate sizes. If this macro is +undefined, @code{MAX (BITS_PER_WORD * 2, 64)} is assumed. @end defmac @defmac STACK_SAVEAREA_MODE (@var{save_level}) @@ -4774,10 +4776,6 @@ that element as the canonical location and ignore the others. The m68k port uses this type of @code{parallel} to return pointers in both @samp{%a0} (the canonical location) and @samp{%d0}. -If @code{TARGET_PROMOTE_FUNCTION_RETURN} returns true, you must apply -the same promotion rules specified in @code{PROMOTE_MODE} if -@var{valtype} is a scalar type. - If the precise function being called is known, @var{func} is a tree node (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null pointer. This makes it possible to use a different value-returning @@ -6286,6 +6284,10 @@ reciprocal of the machine-specific builtin function @var{fndecl}, or @code{NULL_TREE} if such a function is not available. @end deftypefn +@node Vectorization +@section Vectorization +@cindex Vectorization + @deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_MASK_FOR_LOAD (void) This hook should return the DECL of a function @var{f} that given an address @var{addr} as an argument returns a mask @var{m} that can be @@ -6386,12 +6388,14 @@ return type of the vectorized function shall be of vector type @var{vec_type_out} and the argument types should be @var{vec_type_in}. @end deftypefn -@deftypefn {Target Hook} bool TARGET_VECTORIZE_SUPPORT_VECTOR_MISALIGNMENT (machine_mode @var{mode}, const_tree @var{type}, int @var{misalignment}, bool @var{is_packed}) +@deftypefn {Target Hook} bool TARGET_VECTORIZE_SUPPORT_VECTOR_MISALIGNMENT (machine_mode @var{mode}, const_tree @var{type}, int @var{misalignment}, bool @var{is_packed}, bool @var{is_gather_scatter}) This hook should return true if the target supports misaligned vector store/load of a specific factor denoted in the @var{misalignment} parameter. The vector store/load should be of machine mode @var{mode} and -the elements in the vectors should be of type @var{type}. @var{is_packed} -parameter is true if the memory access is defined in a packed struct. +the elements in the vectors should be of type @var{type}. The +@var{is_packed} parameter is true if the misalignment is unknown and the +memory access is defined in a packed struct. @var{is_gather_scatter} is true +if the load/store is a gather or scatter. @end deftypefn @deftypefn {Target Hook} machine_mode TARGET_VECTORIZE_PREFERRED_SIMD_MODE (scalar_mode @var{mode}) @@ -6515,6 +6519,19 @@ The default is @code{NULL_TREE} which means to not vectorize scatter stores. @end deftypefn +@deftypefn {Target Hook} bool TARGET_VECTORIZE_PREFER_GATHER_SCATTER (machine_mode @var{mode}, int @var{scale}, unsigned int @var{group_size}) +This hook returns TRUE if gather loads or scatter stores are cheaper on +this target than a sequence of elementwise loads or stores. The @var{mode} +and @var{scale} correspond to the @code{gather_load} and +@code{scatter_store} instruction patterns. The @var{group_size} is the +number of scalar elements in each scalar loop iteration that are to be +combined into the vector. +@end deftypefn + +@node OpenMP and OpenACC +@section OpenMP and OpenACC +@cindex OpenMP and OpenACC + @deftypefn {Target Hook} int TARGET_SIMD_CLONE_COMPUTE_VECSIZE_AND_SIMDLEN (struct cgraph_node *@var{}, struct cgraph_simd_clone *@var{}, @var{tree}, @var{int}, @var{bool}) This hook should set @var{vecsize_mangle}, @var{vecsize_int}, @var{vecsize_float} fields in @var{simd_clone} structure pointed by @var{clone_info} argument and also diff --git a/gcc/doc/tm.texi.in b/gcc/doc/tm.texi.in index eccc4d8..12b8ed6 100644 --- a/gcc/doc/tm.texi.in +++ b/gcc/doc/tm.texi.in @@ -37,6 +37,8 @@ through the macros defined in the @file{.h} file. * Trampolines:: Code set up at run time to enter a nested function. * Library Calls:: Controlling how library routines are implicitly called. * Addressing Modes:: Defining addressing modes valid for memory operands. +* Vectorization:: Controlling how the vectorizer operates. +* OpenMP and OpenACC:: Defining how OpenMP and OpenACC features should work. * Anchored Addresses:: Defining how @option{-fsection-anchors} should work. * Condition Code:: Defining how insns update the condition code. * Costs:: Defining relative costs of different operations. @@ -1251,10 +1253,10 @@ the smaller of @var{computed} and @code{BIGGEST_ALIGNMENT} @defmac MAX_FIXED_MODE_SIZE An integer expression for the size in bits of the largest integer -machine mode that should actually be used. All integer machine modes of -this size or smaller can be used for structures and unions with the -appropriate sizes. If this macro is undefined, @code{GET_MODE_BITSIZE -(DImode)} is assumed. +machine mode that should actually be used by GCC internally. +All integer machine modes of this size or smaller can be used for +structures and unions with the appropriate sizes. If this macro is +undefined, @code{MAX (BITS_PER_WORD * 2, 64)} is assumed. @end defmac @defmac STACK_SAVEAREA_MODE (@var{save_level}) @@ -4273,6 +4275,10 @@ address; but often a machine-dependent strategy can generate better code. @hook TARGET_BUILTIN_RECIPROCAL +@node Vectorization +@section Vectorization +@cindex Vectorization + @hook TARGET_VECTORIZE_BUILTIN_MASK_FOR_LOAD @hook TARGET_VECTORIZE_BUILTIN_VECTORIZATION_COST @@ -4311,6 +4317,12 @@ address; but often a machine-dependent strategy can generate better code. @hook TARGET_VECTORIZE_BUILTIN_SCATTER +@hook TARGET_VECTORIZE_PREFER_GATHER_SCATTER + +@node OpenMP and OpenACC +@section OpenMP and OpenACC +@cindex OpenMP and OpenACC + @hook TARGET_SIMD_CLONE_COMPUTE_VECSIZE_AND_SIMDLEN @hook TARGET_SIMD_CLONE_ADJUST diff --git a/gcc/doc/trouble.texi b/gcc/doc/trouble.texi index 15ced5f..a2e6de4 100644 --- a/gcc/doc/trouble.texi +++ b/gcc/doc/trouble.texi @@ -494,10 +494,12 @@ as to use the proper set, but you'll have to do this by hand. @section Standard Libraries @opindex Wall -GCC by itself attempts to be a conforming freestanding implementation. +GCC by itself attempts to provide the compiler part of a conforming +implementation, but only a limited subset of the library part of such +an implementation. @xref{Standards,,Language Standards Supported by GCC}, for details of -what this means. Beyond the library facilities required of such an -implementation, the rest of the C library is supplied by the vendor of +what this means. Beyond the limited library facilities described +there, the rest of the C library is supplied by the vendor of the operating system. If that C library doesn't conform to the C standards, then your programs might get warnings (especially when using @option{-Wall}) that you don't expect. diff --git a/gcc/doc/ux.texi b/gcc/doc/ux.texi index 2428d1a..22df88f 100644 --- a/gcc/doc/ux.texi +++ b/gcc/doc/ux.texi @@ -407,9 +407,12 @@ Use @code{auto_diagnostic_group} when issuing multiple related diagnostics (seen in various examples on this page). This informs the diagnostic subsystem that all diagnostics issued within the lifetime of the @code{auto_diagnostic_group} are related. For example, -@option{-fdiagnostics-format=json} will treat the first diagnostic +@option{-fdiagnostics-add-output=sarif} will treat the first diagnostic emitted within the group as a top-level diagnostic, and all subsequent -diagnostics within the group as its children. +diagnostics within the group as its children. Also, if a warning in the +group is inhibited at nesting depth D, all subsequent notes at that depth +or deeper will be inhibited as well, until an error or another warning +is emitted, the depth decreases below D, or the group is popped. @subsection Quoting Text should be quoted by either using the @samp{q} modifier in a directive |