libgomp.texi: Update "Enabling OpenMP" + OpenACC / invoke.texi: -fopenacc/-fopenmp update (was: Re: [patch] libgomp.texi: Update "Enabling OpenMP")

Message ID 7ad5aa88-5e52-490c-b414-f5d1430e5f18@codesourcery.com
State Unresolved
Headers
Series libgomp.texi: Update "Enabling OpenMP" + OpenACC / invoke.texi: -fopenacc/-fopenmp update (was: Re: [patch] libgomp.texi: Update "Enabling OpenMP") |

Checks

Context Check Description
snail/gcc-patch-check warning Git am fail log

Commit Message

Tobias Burnus Oct. 15, 2023, 10:42 a.m. UTC
  Hi Sandra and Jakub,

I have now updated the patch; on the way, I found an issue in -fopenacc ('!$' is
not OpenACC and no longer supported) and the same @code/@samp.

I also updated invoke.texi for the same @code/@samp - and added both '!$'
and mentioned the 'c$'/'*$' Fortran fixed-form variant. I think the most
important bit is that '!$' is also supported by -fopenmp-simd as that's not
covered by the OpenMP specification.

Otherwise:

On 14.10.23 23:46, Sandra Loosemore wrote:
> On 10/14/23 13:43, Tobias Burnus wrote:
>> The attached patch tries to improve this. Note that it talks about C and
>> C++ attributes, even though C23's [[omp::]] support has not yet landed.
>> (But is expected very soon.)
>
> Is somebody actively working on implementing that, and expecting to
> get it in before Stage 1 closes?  I don't think we should document
> features that don't exist yet.
Yes. But I have now sneaked in an 'in C++' which can also be easily
removed once Jakub's patch is committed or as part of Jakub's patch.
> This syntax for C also isn't even in the draft OpenMP 6.0 document so
> at this point

Well, it is in the git version, which will be released as TR12 in about
a month (in time for SC23). It is very unlikely to get removed before
OpenMP 6.0 as it is an obvious extension to C++11's attribute support,
now that C supports attributes as well.

> Other than that...
> Use @option markup on options, not @command.

Fixed. Was preexisting and I copied it once. I've now checked, the only
other use in libgomp.texi was for an actual command (nvprof).


> And I think all those @code markups should be @samp instead, or you
> could just replace this whole blurb with something like "This flag
> enables recognition of the directive syntax documented in the OpenMP
> specification, and also arranges for automatic linking..."

I think it is more user friendly to document the sentinels. However, I
concur that @samp is better.

> +OpenMP directives, which do not require the linking of neither the
>
> s/, which/ that/

I have now used it, but I think it sound odd:

"enables *a* subset of OpenMP directives *that* do not require the linking"

I concur that with "*the* subset ... *that*" makes sense but I want to
avoid stating that *all* directives that do not require linking of
libgomp/libpthread are supported.

invoke.texi lists all supported directives, but I am not really fond of
repeating that list.

> s/neither/either/

The fun of whether double negation cancels or enforces the negation or
.. ("not .. neither / nor").

Cf. https://en.wikipedia.org/wiki/Double_negative

In German and English, both cancellation and enforcement seem to be
possible, the latter especially with dialects - while the standard
language tends to avoid double negation.

Updated patch attached.

Thanks,

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
  

Comments

Sandra Loosemore Oct. 15, 2023, 9:05 p.m. UTC | #1
On 10/15/23 04:42, Tobias Burnus wrote:
> 
> Updated patch attached.

This version looks OK to me.

-Sandra
  

Patch

libgomp.texi: Update "Enabling OpenMP" + OpenACC / invoke.texi: -fopenacc/-fopenmp update

The OpenACC specification does not mention the '!$ ' sentinel for conditional
compilation and the feature was removed in r11-5572-g1d6f6ac693a860
for PR fortran/98011.

libgomp/
	* libgomp.texi (Enabling OpenMP): Update for C/C++ attributes;
	improve wording especially for Fortran; mention -fopenmp-simd.
	(Enabling OpenACC): Minor cleanup; remove conditional compilation
	sentinel.

gcc/
	* doc/invoke.texi (-fopenacc, -fopenmp, -fopenmp-simd): Use @samp not
	@code; document more completely the supported Fortran sentinels.

gcc/fortran
	* scanner.cc (skip_free_comments, skip_fixed_comments): Remove
	leftover 'OpenACC' from comments about OpenMP's conditional
	compilation sentinel.

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index fee659462ff..eb714d18511 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -2748,9 +2748,10 @@  Typical command lines are
 @opindex fopenacc
 @cindex OpenACC accelerator programming
 @item -fopenacc
-Enable handling of OpenACC directives @code{#pragma acc} in C/C++ and
-@code{!$acc} in Fortran.  When @option{-fopenacc} is specified, the
-compiler generates accelerated code according to the OpenACC Application
+Enable handling of OpenACC directives @samp{#pragma acc} in C/C++ and
+@samp{!$acc} in free-form Fortran and @samp{!$acc}, @samp{c$acc} and
+@samp{*$acc} in fixed-form Fortran.  When @option{-fopenacc} is specified,
+the compiler generates accelerated code according to the OpenACC Application
 Programming Interface v2.6 @w{@uref{https://www.openacc.org}}.  This option
 implies @option{-pthread}, and thus is only supported on targets that
 have support for @option{-pthread}.
@@ -2766,10 +2767,12 @@  can be omitted, to use a target-specific default value.
 @opindex fopenmp
 @cindex OpenMP parallel
 @item -fopenmp
-Enable handling of OpenMP directives @code{#pragma omp} in C/C++,
-@code{[[omp::directive(...)]]}, @code{[[omp::sequence(...)]]} and
-@code{[[omp::decl(...)]]} in C++ and @code{!$omp} in Fortran.
-When @option{-fopenmp} is specified, the
+Enable handling of OpenMP directives @samp{#pragma omp} in C/C++,
+@samp{[[omp::directive(...)]]}, @samp{[[omp::sequence(...)]]} and
+@samp{[[omp::decl(...)]]} in C++ and @samp{!$omp} in Fortran.  It
+additionally enables the conditional compilation sentinel @samp{!$} in
+Fortran.  In fixed source form Fortran, the sentinels can also start with
+@samp{c} or @samp{*}.  When @option{-fopenmp} is specified, the
 compiler generates parallel code according to the OpenMP Application
 Program Interface v4.5 @w{@uref{https://www.openmp.org}}.  This option
 implies @option{-pthread}, and thus is only supported on targets that
@@ -2785,10 +2788,12 @@  Enable handling of OpenMP's @code{simd}, @code{declare simd},
 and @code{loop} directive, and of combined or composite directives with
 @code{simd} as constituent with @code{#pragma omp} in C/C++,
 @code{[[omp::directive(...)]]}, @code{[[omp::sequence(...)]]} and
-@code{[[omp::decl(...)]]} in C++ and @code{!$omp} in Fortran.
-Other OpenMP directives are ignored.  Unless @option{-fopenmp} is
-additionally specified, the @code{loop} region binds to the current
-task region, independent of the specified @code{bind} clause.
+@code{[[omp::decl(...)]]} in C++ and @code{!$omp} in Fortran.  It
+additionally enables the conditional compilation sentinel @samp{!$} in
+Fortran.  In fixed source form Fortran, the sentinels can also start with
+@samp{c} or @samp{*}.  Other OpenMP directives are ignored.  Unless
+@option{-fopenmp} is additionally specified, the @code{loop} region binds
+to the current task region, independent of the specified @code{bind} clause.
 
 @opindex fopenmp-target-simd-clone
 @cindex OpenMP target SIMD clone
diff --git a/gcc/fortran/scanner.cc b/gcc/fortran/scanner.cc
index 9f0d9a7dc5e..e2a25a1d465 100644
--- a/gcc/fortran/scanner.cc
+++ b/gcc/fortran/scanner.cc
@@ -877,7 +877,7 @@  skip_free_comments (void)
 
 	  /* If -fopenmp/-fopenacc, we need to handle here 2 things:
 	     1) don't treat !$omp/!$acc as comments, but directives
-	     2) handle OpenMP/OpenACC conditional compilation, where
+	     2) handle OpenMP conditional compilation, where
 		!$ should be treated as 2 spaces (for initial lines
 		only if followed by space).  */
 	  if (at_bol)
@@ -1106,7 +1106,7 @@  skip_fixed_comments (void)
 	  /* If -fopenmp/-fopenacc, we need to handle here 2 things:
 	     1) don't treat !$omp/!$acc|c$omp/c$acc|*$omp / *$acc as comments, 
 		but directives
-	     2) handle OpenMP/OpenACC conditional compilation, where
+	     2) handle OpenMP conditional compilation, where
 		!$|c$|*$ should be treated as 2 spaces if the characters
 		in columns 3 to 6 are valid fixed form label columns
 		characters.  */
diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi
index 526d1be2955..e83010d378b 100644
--- a/libgomp/libgomp.texi
+++ b/libgomp/libgomp.texi
@@ -136,15 +136,22 @@  changed to GNU Offloading and Multi Processing Runtime Library.
 @node Enabling OpenMP
 @chapter Enabling OpenMP
 
-To activate the OpenMP extensions for C/C++ and Fortran, the compile-time 
-flag @command{-fopenmp} must be specified.  This enables the OpenMP directive
-@code{#pragma omp} in C/C++ and @code{!$omp} directives in free form, 
-@code{c$omp}, @code{*$omp} and @code{!$omp} directives in fixed form, 
-@code{!$} conditional compilation sentinels in free form and @code{c$},
-@code{*$} and @code{!$} sentinels in fixed form, for Fortran.  The flag also
-arranges for automatic linking of the OpenMP runtime library 
+To activate the OpenMP extensions for C/C++ and Fortran, the compile-time
+flag @option{-fopenmp} must be specified.  For C and C++, this enables
+the handling of the OpenMP directives using @code{#pragma omp} and, for C++, the
+@code{[[omp::directive(...)]]}, @code{[[omp::sequence(...)]]} and
+@code{[[omp::decl(...)]]} attributes.  For Fortran, it enables for
+free source form the @code{!$omp} sentinel for directives and the
+@code{!$} conditional compilation sentinel and for fixed source form the
+@code{c$omp}, @code{*$omp} and @code{!$omp} sentinels for directives and
+the @code{c$}, @code{*$} and @code{!$} conditional compilation sentinels.
+The flag also arranges for automatic linking of the OpenMP runtime library
 (@ref{Runtime Library Routines}).
 
+The @option{-fopenmp-simd} flag can be used to enable a subset of
+OpenMP directives that do not require the linking of either the
+OpenMP runtime library or the POSIX threads library.
+
 A complete description of all OpenMP directives may be found in the
 @uref{https://www.openmp.org, OpenMP Application Program Interface} manuals.
 See also @ref{OpenMP Implementation Status}.
@@ -3697,12 +3704,10 @@  pools available and their worker threads run at priority four.
 
 To activate the OpenACC extensions for C/C++ and Fortran, the compile-time 
 flag @option{-fopenacc} must be specified.  This enables the OpenACC directive
-@code{#pragma acc} in C/C++ and @code{!$acc} directives in free form,
-@code{c$acc}, @code{*$acc} and @code{!$acc} directives in fixed form,
-@code{!$} conditional compilation sentinels in free form and @code{c$},
-@code{*$} and @code{!$} sentinels in fixed form, for Fortran.  The flag also
-arranges for automatic linking of the OpenACC runtime library 
-(@ref{OpenACC Runtime Library Routines}).
+@samp{#pragma acc} in C/C++ and, in Fortran, the @samp{!$acc} sentinel in free
+source form and the @samp{c$acc}, @samp{*$acc} and @samp{!$acc} sentinels in
+fixed source form.  The flag also arranges for automatic linking of the OpenACC
+runtime library (@ref{OpenACC Runtime Library Routines}).
 
 See @uref{https://gcc.gnu.org/wiki/OpenACC} for more information.