Re: [PATCH] libgomp: Add Controls For Runtime USM

On 8/6/26 12:53, Gio T wrote:

> @@ -5240,6 +5241,42 @@ This is currently not specified in more detail, and subject to change.
>  
>  
>  
> +@node GOMP_RUNTIME_USM
> +@section @env{GOMP_RUNTIME_USM} -- Control runtime Unified Shared Memory application
> +@cindex Environment Variable
> +@table @asis
> +@item @emph{Description}:
> +Control the behavior of the runtime in using Unified Shared Memory in
> +offloading.  Setting the environment variable to @code{DISABLED} will
> +not make use of Unified Shared Memory by default.  Setting it to
> +@code{AUTO} will conditionally enable unified shared memory on specific
> +integrated GPUs (APUs, in the verbiage of AMD).  Lastly, setting it to
> +@code{ENABLED} will unconditionally attempt to make use of Unified
> +Shared Memory if the device claims to support it.  Note, some devices

Writing tip: do not use the future tense ("will") to describe current 
behavior or enduring truths.  That's what the present tense is for, e.g. 
write "x controls y" instead of "x will control y".

There are pervasive issues with this throughout the rest of the 
documentation part of the patch as well, not just in the text quoted 
above.  Please rewrite everything in your new text that uses "will".

I think the list of permitted values (embedded in the quoted text above) 
would be better be presented in a nested @table environment instead of 
in running text, though.

> +will indicate support for Unified Shared Memory despite not having the
> +capabilitiy, such as the gfx902, or may lack XNACK support, and as a

s/capabilitiy/capability/

> +result, stability cannot be guaranteed in this mode of operation.  Of
> +additional note, a user specifying behavior with the @code{requires}
> +directive in-code will override this setting unconditionally.

The GNU documentation style is not to talk about "a user" or "the user". 
  Users are "you", the audience to whom the documentation is addressed. 
Here I think it would be more natural and less verbose just to say that 
"code using the @code{requires} directive overrides this setting 
unconditionally", though, without using either "a user" or "you".

> +
> +When Unified Shared Memory is enabled, global static variables that
> +appear in a @code{declare target} directive will not be updated
> +between device and host.  That is, data copying under this model
> +for global static variables is ignored.
> +
> +OpenACC is unaffected by the value of this environment variable,
> +however, hybrid usage of OpenMP and OpenACC offloading will result
> +in the first used framework taking precedent.  As an example, if one
> +uses OpenMP offloading and then later OpenACC offloading, the
> +capabilities the device possesses will reflect the original OpenMP
> +model.
> +
> +@item @emph{See also}:
> +@ref{Offload-Target Specifics}, @ref{AMD Radeon}
> +@end table
> +
> +
> +
>  @node GOMP_STACKSIZE
>  @section @env{GOMP_STACKSIZE} -- Set default thread stack size
>  @cindex Environment Variable

-Sandra