[clang] cd1489b - Clarify documentation of cpu_dispatch/cpu_specific

[Erich Keane via cfe-commits]

Author: Erich Keane
Date: 2022-02-28T07:03:55-08:00
New Revision: cd1489bb58bb61276e73c91ff42dcf6a3febe650

URL: https://github.com/llvm/llvm-project/commit/cd1489bb58bb61276e73c91ff42dcf6a3febe650
DIFF: https://github.com/llvm/llvm-project/commit/cd1489bb58bb61276e73c91ff42dcf6a3febe650.diff

LOG: Clarify documentation of cpu_dispatch/cpu_specific

There has been some internal confusion lately as to how cpu_dispatch and
cpu_specific dispatch to processors, so this patch clarifies the
documentation to make it more clear that:

1- Unlike ICC, we do not consider the vendor string (that is, an AMD
processor might result in something other than generic)

2- there are some processors that aren't really distinguishable thanks
to the library limitation, so the variant being selected is unspecified.

In reality, I believe the 'stable_sort' makes it so the 1st one that
meets the requirements is the one that is selected (and that matches my
experimented result), but I don't want to limit our implementation.

Added: 
    

Modified: 
    clang/include/clang/Basic/AttrDocs.td

Removed: 
    


################################################################################
diff  --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index f61c9d00c4440..784e30f04cf52 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -285,6 +285,17 @@ features that are required for the function to be called. The result of this is
 that future processors execute the most restrictive version of the function the
 new processor can execute.
 
+In addition, unlike the ICC implementation of this feature, the selection of the
+version does not consider the manufacturer or microarchitecture of the processor.
+It tests solely the list of features that are both supported by the specified
+processor and present in the compiler-rt library. This can be surprising at times,
+as the runtime processor may be from a completely 
diff erent manufacturer, as long
+as it supports the same feature set.
+
+This can additionally be surprising, as some processors are indistringuishable from
+others based on the list of testable features. When this happens, the variant
+is selected in an unspecified manner.
+
 Function versions are defined with ``cpu_specific``, which takes one or more CPU
 names as a parameter. For example: