[RFC] internal documentation for OMP_FOR

[RFC] internal documentation for OMP_FOR

[Sandra Loosemore]

[-- Attachment #1: Type: text/plain, Size: 763 bytes --]

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

[-- Attachment #2: 0001-Fix-internal-documentation-for-OMP_FOR.patch --]
[-- Type: text/x-patch, Size: 3814 bytes --]

From d374c9a95db3bab1691be264af51e4298b3811b2 Mon Sep 17 00:00:00 2001
From: Sandra Loosemore <sandra@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

PING Re: [RFC] internal documentation for OMP_FOR

[Sandra Loosemore]

Ping!

https://gcc.gnu.org/pipermail/gcc-patches/2023-February/612298.html
On 2/18/23 22:21, Sandra Loosemore wrote:
> 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

Re: [RFC] internal documentation for OMP_FOR

[Tobias Burnus]

Hi Sandra,

https://gcc.gnu.org/pipermail/gcc-patches/2023-February/612298.html

On 19.02.23 06:21, Sandra Loosemore wrote:
> Here is a patch I put together for the internals manual; can other
> people familiar with this functionality review it for technical
> correctness?

Glancing at it,  it seems to be okay. (I have not cross checked by looking at the code.)


However, you may want to add something related to non-rectangular loops. For those, the
'N1' in OMP_FOR_INIT's @code{VAR = N1} and the
'N2' in OMP_FOR_COND's @code{VAR @{<,>,<=,>=@} N2}
have a special form; namely, the N1 and/or N2 are not normal expressions
but are TREE_VEC with three elements:
The outer loop variable (TREE_CODE_CLASS == tcc_declaration),
a multiplication factor,
and an offset.

Example: For the loop initialization 'i = j - 5', the result to be put into the
OMP_FOR_INIT vector is: 'MODIFY_EXPR (i, TREE_VEC<j, 1, -5>)'

You could then also mention that OMP_FOR_NON_RECTANGULAR is/must be set
on the OMP_FOR statement in that case. (This flag is currently not mentioned in the .texi.)


Additionally, the doc/generic.texi could also mention that not only OMP_FOR
takes those operands but also OMP_SIMD, OMP_DISTRIBUTE, OMP_TASKLOOP, OMP_LOOP,
and OACC_LOOP (cf. tree.def or the actual code using it).

Tobias

-----------------
Siemens Electronic Design Automation GmbH; Anschrift: Arnulfstraße 201, 80634 München; Gesellschaft mit beschränkter Haftung; Geschäftsführer: Thomas Heurung, Frank Thürauf; Sitz der Gesellschaft: München; Registergericht München, HRB 106955