[Bug other/97309] New: Improve documentation of -fallow-store-data-races

["qinzhao at gcc dot gnu.org" <gcc-bugzilla@gcc.gnu.org>]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=97309

            Bug ID: 97309
           Summary: Improve documentation of -fallow-store-data-races
           Product: gcc
           Version: 11.0
            Status: UNCONFIRMED
          Severity: normal
          Priority: P3
         Component: other
          Assignee: unassigned at gcc dot gnu.org
          Reporter: qinzhao at gcc dot gnu.org
  Target Milestone: ---

As of GCC 10, the former --param allow-store-data-races is now 
-fallow-store-data-races.  The default, in both cases, is not to allow them.   

For releases prior to GCC 10, the --param is documented as 

           allow-store-data-races 
               Allow optimizers to introduce new data races on stores.  Set 
to 1 to allow, otherwise to 0. 

The description for GCC 10 is simply: 

       -fallow-store-data-races 
           Allow the compiler to introduce new data races on stores. 
           Enabled at level -Ofast. 

There are three problems with this description. 

(1) The explanation is sparse - basically it just repeats the name of the 
switch.   

(2) It provides no context to explain the circumstances under which it may or 
may not be safe to use. 

(3) Because of the lack of clarity regarding safety, it may be questionable 
as to whether a SPEC CPU user is allowed to use -Ofast 
(http://www.spec.org/cpu2017/Docs/runrules.html#safe) 

Suggested improvement: 

Allow the compiler to perform optimizations that may introduce new data races 
on stores, without proving that the variable cannot be concurrently accessed 
by other threads. Does not affect optimization of local data. It is safe to 
use this option if it is known that global data will not be accessed by 
multiple threads. 

Examples of optimizations enabled by -fallow-store-data-races include 
hoisting or if-conversions that may cause a value that was already in memory 
to be re-written with that same value. Such re-writing is safe in a single 
threaded context but may be unsafe in a multi-threaded context. Note that on 
some processors, if-conversions may be  required in order to enable 
vectorization.