diff options
Diffstat (limited to 'gcc/doc')
| -rw-r--r-- | gcc/doc/analyzer.texi | 12 | ||||
| -rw-r--r-- | gcc/doc/invoke.texi | 20 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/topics/compatibility.rst | 33 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst | 26 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/topics/graphs.rst | 197 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/topics/index.rst | 1 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/topics/logical-locations.rst | 7 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst | 11 | ||||
| -rw-r--r-- | gcc/doc/sourcebuild.texi | 6 |
9 files changed, 279 insertions, 34 deletions
diff --git a/gcc/doc/analyzer.texi b/gcc/doc/analyzer.texi index 4dd14c8..4efba4d 100644 --- a/gcc/doc/analyzer.texi +++ b/gcc/doc/analyzer.texi @@ -624,17 +624,17 @@ 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 XML representation generated from -@code{program_state} objects. The XML representation can be easier to +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 XML and ``dot'' +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-xml=yes} and +@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. @@ -792,9 +792,9 @@ 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_xml +@item __analyzer_dump_sarif @smallexample -__analyzer_dump_xml (); +__analyzer_dump_sarif (); @end smallexample will dump the copious information about the analyzer's state each time it diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 74f5ee2..9a1aa37 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -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 @@ -6143,10 +6143,10 @@ end-users, and subject to change or removal without notice: @table @gcctabopt -@item xml-state=@r{[}yes@r{|}no@r{]} +@item state-graphs=@r{[}yes@r{|}no@r{]} This is a debugging feature and defaults to @code{no}. -If @code{xml-state=yes}, then attempt to capture detailed state information -from @option{-fanalyzer} in the generated SARIF. +If @code{state-graphs=yes}, then attempt to capture detailed state +information from @option{-fanalyzer} in the generated SARIF. @end table @@ -6194,11 +6194,11 @@ 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-xml=@r{[}yes@r{|}no@r{]} +@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-xml=yes} +If @code{show-state-diagrams-sarif=yes} then if @code{show-state-diagrams=yes}, the generated state diagrams will -also show an XML representation of the state. +also show a SARIF representation of the state. @end table @@ -9690,6 +9690,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)} diff --git a/gcc/doc/libgdiagnostics/topics/compatibility.rst b/gcc/doc/libgdiagnostics/topics/compatibility.rst index 10adcc5..0e078d0 100644 --- a/gcc/doc/libgdiagnostics/topics/compatibility.rst +++ b/gcc/doc/libgdiagnostics/topics/compatibility.rst @@ -178,6 +178,8 @@ acccessing values within a :type:`diagnostic_logical_location`: * :func:`diagnostic_logical_location_get_decorated_name` +.. _LIBGDIAGNOSTICS_ABI_2: + ``LIBGDIAGNOSTICS_ABI_2`` ------------------------- ``LIBGDIAGNOSTICS_ABI_2`` covers the addition of these functions for @@ -186,3 +188,34 @@ 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` diff --git a/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst b/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst index 0390704..c94d19e 100644 --- a/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst +++ b/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst @@ -63,17 +63,17 @@ Responsibilities include: diagnostic_manager *control_mgr) This function can be used to support option processing similar to GCC's - :option:`-fdiagnostics-add-output=`. This allows command-line tools to - support the same domain-specific language for specifying output sink - as GCC does. - - The function will attempt to parse :param:`spec` as if it were - an argument to GCC's :option:`-fdiagnostics-add-output=OUTPUT-SPEC`. - If successful, it will add an output sink to :param:`affected_mgr` and return zero. - Otherwise, it will emit an error diagnostic to :param:`control_mgr` and + `-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. - :param:`affected_mgr` and :param:`control_mgr` can be the same manager, + ``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 @@ -83,14 +83,14 @@ Responsibilities include: #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 :param:`mgr` to be - :param:`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 artifact in SARIF output (SARIF v2.1.0 section 3.24.6). + 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 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 6eb3ed6..966f5ef 100644 --- a/gcc/doc/libgdiagnostics/topics/index.rst +++ b/gcc/doc/libgdiagnostics/topics/index.rst @@ -35,5 +35,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 184b563..294d396 100644 --- a/gcc/doc/libgdiagnostics/topics/logical-locations.rst +++ b/gcc/doc/libgdiagnostics/topics/logical-locations.rst @@ -120,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, \ @@ -147,8 +147,9 @@ 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. :type:`const char *` values will point -at copies of the original buffer. +``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) 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/sourcebuild.texi b/gcc/doc/sourcebuild.texi index 6c5586e..85fb810 100644 --- a/gcc/doc/sourcebuild.texi +++ b/gcc/doc/sourcebuild.texi @@ -2373,6 +2373,12 @@ 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_fjcvtzs_hw AArch64 target that is able to generate and execute armv8.3-a FJCVTZS |