I've been working on support for OpenMP imperfectly-nested loops. In
the process I have gone astray multiple times because of
incorrect/inadequate internal documentation for the OMP_FOR tree
structure. The code changes I've been working on are Stage 1 material,
but the documentation improvements are independent and can be fixed now.
Here is a patch I put together for the internals manual; can other
people familiar with this functionality review it for technical
correctness? Even after working with this code for months, I'm still
not sure I understand all the nuances. :-P The comments in tree.def
are also wrong, but once we get the content right in the manual I can
just copy the changes there for the final version of the patch.
-Sandra
From d374c9a95db3bab1691be264af51e4298b3811b2 Mon Sep 17 00:00:00 2001
From: Sandra Loosemore <san...@codesourcery.com>
Date: Sun, 19 Feb 2023 05:15:43 +0000
Subject: [PATCH] Fix internal documentation for OMP_FOR.
gcc/ChangeLog:
* doc/generic.texi (OMP_FOR): Correct description.
---
gcc/doc/generic.texi | 45 ++++++++++++++++++++++++++++++++------------
1 file changed, 33 insertions(+), 12 deletions(-)
diff --git a/gcc/doc/generic.texi b/gcc/doc/generic.texi
index 3f52d3042b8..63337bd6f6e 100644
--- a/gcc/doc/generic.texi
+++ b/gcc/doc/generic.texi
@@ -2295,35 +2295,56 @@ variables.
@item OMP_FOR
-Represents @code{#pragma omp for [clause1 @dots{} clauseN]}. It has
-six operands:
+Represents @code{#pragma omp for [clause1 @dots{} clauseN]}.
+A single @code{OMP_FOR} node represents an entire nest of collapsed loops;
+as noted below, some of its arguments are vectors of length equal to the
+collapse depth, and the corresponding elements holding data specific to a
+particular loop in the nest. These vectors are numbered so that the
+outermost loop is element 0.
+
+@code{OMP_FOR} has seven operands:
Operand @code{OMP_FOR_BODY} contains the loop body.
Operand @code{OMP_FOR_CLAUSES} is the list of clauses
associated with the directive.
-Operand @code{OMP_FOR_INIT} is the loop initialization code of
-the form @code{VAR = N1}.
+Operand @code{OMP_FOR_INIT} is a vector containing iteration variable
+initializations of the form @code{VAR = N1}.
-Operand @code{OMP_FOR_COND} is the loop conditional expression
+Operand @code{OMP_FOR_COND} is vector containing loop conditional expressions
of the form @code{VAR @{<,>,<=,>=@} N2}.
-Operand @code{OMP_FOR_INCR} is the loop index increment of the
-form @code{VAR @{+=,-=@} INCR}.
+Operand @code{OMP_FOR_INCR} is a vector containing loop index increment
+expressions of the form @code{VAR @{+=,-=@} INCR}.
Operand @code{OMP_FOR_PRE_BODY} contains side effect code from
operands @code{OMP_FOR_INIT}, @code{OMP_FOR_COND} and
-@code{OMP_FOR_INC}. These side effects are part of the
+@code{OMP_FOR_INCR}. These side effects are part of the
@code{OMP_FOR} block but must be evaluated before the start of
-loop body.
+loop body. @code{OMP_FOR_PRE_BODY} specifically
+includes @code{DECL_EXPR}s for iteration variables that are declared
+in the nested @code{for} expressions. Note this field is not a vector;
+it may be null, but otherwise is usually a statement list collecting the
+side effect code from all the collapsed loops.
+
+Operand @code{OMP_FOR_ORIG_DECLS} holds @code{VAR_DECLS} for the
+original user-specified iterator variables in the source code.
+In some cases, like C++ class iterators or range for with decomposition,
+the @code{for} loop is rewritten by the front end to use a temporary
+iteration variable. The purpose of this field is to make the original
+variables available to the gimplifier so it can adjust their data-sharing
+attributes and diagnose errors. @code{OMP_FOR_ORIG_DECLS} is a vector
+field, with each element holding a list of @code{VAR_DECLS} for the
+corresponding collapse level.
The loop index variable @code{VAR} must be a signed integer variable,
which is implicitly private to each thread. Bounds
@code{N1} and @code{N2} and the increment expression
-@code{INCR} are required to be loop invariant integer
-expressions that are evaluated without any synchronization. The
-evaluation order, frequency of evaluation and side effects are
+@code{INCR} are required to be loop-invariant integer
+expressions that are evaluated without any synchronization, except for
+the forms of non-rectangular loops permitted by the OpenMP standard. The
+evaluation order, frequency of evaluation and side effects are otherwise
unspecified by the standard.
@item OMP_SECTIONS
--
2.31.1