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
