Re: [Patch] Add 'default' to -foffload=; document that flag [PR67300]

[Sandra Loosemore <sandra@codesourcery.com>]

On 6/17/21 5:05 PM, Tobias Burnus wrote:
> On 17.06.21 23:57, Sandra Loosemore wrote:
> 
>> On 6/17/21 1:40 PM, Jakub Jelinek wrote:
>>> Could we introduce a different option which wouldn't imply enabling that
>>> target:
>>> -foffload-options=<target triplet list>=option
> 
> I think that works – in particular, if we do not document all
> the legacy stuff but just how it should be used.
> 
> That includes not mentioning that disable and default can
> be used in a list and that those can also take arguments.
> 
>> I don't feel qualified to comment on the details of the behavior, but 
>> separating the options and making them more orthogonal to one another 
>> would certainly make things easier to document.  :-)
> 
> I fully concur.
> 
> Probably not fully polished, but I have attached a version for discussion.

Thanks.  The description of the options is a lot easier to follow now, 
so I mostly have only nit-picky Texinfo/grammar/terminology comments 
about the docs now.

> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> index af2ce189fae..82993fa2c1d 100644
> --- a/gcc/doc/invoke.texi
> +++ b/gcc/doc/invoke.texi
> @@ -204,6 +204,7 @@ in the following sections.
>  -fhosted  -ffreestanding @gol
>  -fopenacc  -fopenacc-dim=@var{geom} @gol
>  -fopenmp  -fopenmp-simd @gol
> +-foffload=@var{arg} -foffload-options=@var{arg} @gol
>  -fms-extensions  -fplan9-extensions  -fsso-struct=@var{endianness} @gol
>  -fallow-single-precision  -fcond-mismatch  -flax-vector-conversions @gol
>  -fsigned-bitfields  -fsigned-char @gol

Two spaces instead of one to separate options on the same line in a 
@gccoptlist environment.

The -f options are alphabetized in most of the other @gccoptlist tables 
in the option summary section.  I'm not sure why this group isn't, but 
you get extra credit if you fix that, too.

> @@ -2639,6 +2640,46 @@ Enable handling of OpenMP's SIMD directives with @code{#pragma omp}
>  in C/C++ and @code{!$omp} in Fortran. Other OpenMP directives
>  are ignored.
>  
> +@item -foffload=disable
> +@itemx -foffload=default
> +@itemx -foffload=@var{target-list}
> +@opindex foffload
> +@cindex Offloading
> +@cindex OpenACC
> +@cindex OpenMP

"OpenACC" and "OpenMP" are far too general to be useful for @cindex 
entries.  "Offloading targets", "OpenACC offloading targets", and 
"OpenMP offloading targets" would be more helpful.

> +Specify for which offload targets code should be generated.  By default,
> +code for all supported targets is generated.  Using
> +@option{-foffload=disable} only code for the host fallback is
> +generated, while @option{-foffload=}@var{target-list} generates code
> +only for the specified comma-separated list of offload-targets triplets.
> +To reset the value to the default, @option{-foffload=default} can be
> +used.
> +
> +Note: Running the compiler with @option{-v} shows the list of
> +configured offload targets under @code{OFFLOAD_TARGET_NAMES}.

I'd like to rephrase this a little bit to avoid some awkward sentence 
construction, and also not introduce the term "triplet" without 
explanation in the user documentation (it's only used in the install and 
internals manuals).  So:

Specify for which OpenMP and OpenACC offload targets code should be 
generated.  The default behavior, equivalent to 
@option{-foffload=default}, is to generate code for all supported 
offload targets.  The @option{-foffload=disable} form generates code 
only for the host fallback, while @option{-foffload=@var{target-list}} 
generates code only for the specified comma-separated list of offload 
targets.

Offload targets are specified in GCC's internal target-triplet format. 
You can run the compiler with @option{-v} to show the list of configured 
offload targets under @code{OFFLOAD_TARGET_NAMES}.

> +
> +@item -foffload-options=@var{options}
> +@itemx -foffload-options=@var{target-triplet-list}=@var{options}
> +@opindex foffload
> +@cindex Offloading
> +@cindex OpenACC
> +@cindex OpenMP

Ditto with the overly-general @cindex entries.  I'd list these as 
"Offloading options" etc instead.

Also use @var{target-list} here instead of @var{target-triplet-list} for 
consistency with the previous option and because triplets are not 
otherwise a user-visible thing in GCC.

> +
> +Specify the options passed to the offload-target compiler. While using
> +@option{-foffload-options=}@var{options} passes the options to all enabled
> +offloading compiler,
> +@option{-foffload-options=}@var{target-triplet-list}=@var{options} can
> +be used to pass them only to the specified comma-separated list of
> +target triplets.
> +

Again to fix sentence construction and markup issues:

With @option{-foffload-options=@var{options}}, GCC passes the specified 
@var{options} to the compilers for all enabled offloading targets.  You 
can specify options that apply only to a specific target or targets by 
using the @option{-foffload-options=@var{target-list}=@var{options}}
form.  The @var{target-list} is a comma-separated list in the same 
format as for the @option{-foffload=} option.

> +Typical commandlines are

"command lines", two words.

> +
> +@smallexample
> +-foffload=-lgfortran -foffload=-lm
> +-foffload=-lm -foffload=nvptx-none=-latomic
> +-foffload=amdgcn-amdhsa=-march=gfx906 -foffload=nvptx-none="-latomic -lm"
> +@end smallexample
> +
>  @item -fgnu-tm
>  @opindex fgnu-tm
>  When the option @option{-fgnu-tm} is specified, the compiler

Thanks for working on this!  :-)

-Sandra