Merge pull request #1705 from labrinea/fmv-updates-in-llvm20

[FMV] Updates for the LLVM 20 release.

Author: jasonrandrews

content/learning-paths/cross-platform/function-multiversioning/_index.md

@@ -17,7 +17,7 @@ prerequisites:
     - Familiarity with indirect functions (ifuncs).
     - Basic knowledge of loop vectorization.
     - Familiarity with Arm assembly.
-    - A LLVM 19 compiler with runtime library support or GCC 14.
+    - A LLVM 20 compiler with runtime library support or GCC 14.
 
 author: Alexandros Lamprineas
 

content/learning-paths/cross-platform/function-multiversioning/changes-from-past-releases.md

@@ -0,0 +1,48 @@
+---
+title: Changes from released compilers
+weight: 8
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+#### ACLE specification changes
+
+- The set of supported features has changed as indicated by the [ACLE Q3 change log](https://arm-software.github.io/acle/main/acle.html#changes-between-acle-q2-2024-and-acle-q3-2024) and the [ACLE Q4 change log](https://arm-software.github.io/acle/main/acle.html#changes-between-acle-q3-2024-and-acle-q4-2024).
+- The runtime detection of features has changed. Dependent-on features get detected as indicated by the [dependencies table](https://arm-software.github.io/acle/main/acle.html#dependencies).
+- The most appropriate version of a function is determined as indicated by the new [selection rules](https://arm-software.github.io/acle/main/acle.html#selection). Previously, the most specific version (the one with most features) was favored over any other version.
+- A new predefined macro `__FUNCTION_MULTI_VERSIONING_SUPPORT_LEVEL` has been added to indicate which ACLE version is implemented by the compiler.
+
+#### Semantic changes between LLVM 19 and LLVM 20
+
+With LLVM 19 at least one more version other than the default is needed to trigger function multiversioning. With LLVM 20 a header file declaration:
+
+```c
+__attribute__((target_version("default"))) void f(void);
+```
+
+guarantees that there will be a mangled version `f.default`. Conversely, LLVM 19 would generate an unmangled symbol here since function multiversioning does not trigger when compiling this code in the absence of other versions.
+
+#### Static resolution in LLVM 20
+
+LLVM can optimize calls to versioned functions when they can be statically resolved. For example:
+
+```c
+__attribute__((target_version("mops"))) int f(void);
+__attribute__((target_version("sve2"))) int f(void);
+__attribute__((target_version("sve"))) int f(void);
+__attribute__((target_version("default"))) int f(void) { return 0; }
+
+__attribute__((target_version("mops+sve2"))) int caller(void) {
+  return f(); // f._Mmops is called directly
+}
+__attribute__((target_version("mops"))) int caller(void) {
+  return f(); // f._Mmops is called directly
+}
+__attribute__((target_version("sve"))) int caller(void) {
+  return f(); // cannot be optimized since SVE2 may be available on target
+}
+__attribute__((target_version("default"))) int caller(void) {
+  return f(); // f.default is called directly
+}
+```

content/learning-paths/cross-platform/function-multiversioning/implementation-details.md

@@ -1,24 +1,74 @@
 ---
 title: Further information on implementation 
-weight: 6
+weight: 7
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
 To select the most appropriate version of a function, each call to a versioned function is routed through an indirect function resolver which is pointed by the called symbol (ifunc). 
 
-The compiler generates a resolver based on the function versions declared in the translation unit. A typical resolver implementation uses a runtime library to detect the presence of the architectural features on which the function versions depend and returns a pointer to the correct version. 
+The compiler generates a resolver based on the function versions declared in the translation unit. A typical resolver implementation uses a runtime library to detect the presence of the architectural features on which the function versions depend and returns a pointer to the correct version. Features implied by the command line are not exempt from runtime detection.
 
 The resolution of the called symbol is delayed until runtime, when the dynamic loader runs the resolver and updates the procedure linkage table (PLT) with a pointer to the chosen implementation. The resolver function is run only once and its returned value remains unchanged for the lifetime of the process. 
 
 Relocations handle references to the called symbol, which return the cached PLT entry.
 
-#### Differences between GCC 14 and LLVM 19 implementations
+#### Feature detection at runtime
+
+Some architectural features depend on others as indicated by the [dependencies table](https://arm-software.github.io/acle/main/acle.html#dependencies). Those are detected transitively and they are not exempt from runtime detection if implied by the command line. For example `rcpc3` depends on `rcpc2` which depends on `rcpc`. All three are detected in the following example.
+
+Use a text editor to create a file named `rcpc.c` with the code below:
+
+```c
+__attribute__((target_clones("rcpc3", "default"))) int f(void) { return 0; }
+```
+
+{{% notice Note %}}
+The depended-on features (rcpc2, rcpc) *need not* be specified in the attribute, but they *may* well be (there is no functional difference):
+```c
+__attribute__((target_clones("rcpc3+rcpc2+rcpc", "default")))
+```
+{{% /notice %}}
+
+To compile with Clang, run:
+
+```console
+clang --target=aarch64-linux-gnu -march=armv8-a+rcpc -O3 --rtlib=compiler-rt -S -o - rcpc.c
+```
+
+Here is the generated resolver function containing the runtime detection of features:
+
+```output
+       .section        .text.f.resolver,"axG",@progbits,f.resolver,comdat
+       .weak   f.resolver
+       .p2align        2
+       .type   f.resolver,@function
+f.resolver:
+       str     x30, [sp, #-16]!
+       bl      __init_cpu_features_resolver
+       adrp    x8, __aarch64_cpu_features
+       mov     x9, #12582912
+       adrp    x10, f.default
+       add     x10, x10, :lo12:f.default
+       ldr     x8, [x8, :lo12:__aarch64_cpu_features]
+       movk    x9, #1024, lsl #48
+       bics    xzr, x9, x8
+       adrp    x8, f._Mrcpc3
+       add     x8, x8, :lo12:f._Mrcpc3
+       csel    x0, x8, x10, eq
+       ldr     x30, [sp], #16
+       ret
+```
+{{% notice Note %}}
+The immediate value `#12582912` in this assembly is used to construct a bitmask for materializing the runtime detection of `rcpc3`.
+{{% /notice %}}
+
+#### Differences between GCC 14 and LLVM 20 implementations
 
 - The attribute `target_version` in GCC is only supported for C++, not for C.
 - The set of features as indicated by the [mapping table](https://arm-software.github.io/acle/main/acle.html#mapping) differs in support between the two compilers.
-- GCC can statically resolve calls to versioned functions, whereas LLVM cannot.
+- LLVM supports mixing `target_version` with `target_clones` whereas GCC does not yet support this.
 
 #### Resolver emission with LLVM
 
@@ -47,12 +97,10 @@ The compilation of `file1.c` yields normal code generation since no version of `
 
 When compiling `file2.c` a resolver is emitted for `func1` due to the presence of its default definition. GCC does not currently support multiversioning for this example as it only generates a resolver when a function is called.
 
-#### Static resolution with GCC
-
-The GCC compiler optimizes calls to versioned functions when they can be statically resolved. 
+#### Static resolution of calls
 
-Such calls would otherwise be routed through the resolver, but instead they become direct which allows them to be inlined. 
+Normally the called symbol is resolved at runtime (dynamically), however it may be possible to determine which function version to call at compile time (statically).
 
-This might be possible whenever a function is compiled with a sufficiently high set of architecture features (so including `target`/`target_version`/`target_clones` attributes, and command line options). 
+This may be possible when the caller function is compiled with a sufficiently high set of architecture features (explicitly by using the `target` attribute as an optimization hint, or the multiversioning attributes `target_version`/`target_clones`, and implicitly via command line options). See [the example](/learning-paths/cross-platform/function-multiversioning/changes-from-past-releases).
 
-LLVM is not yet able to perform this optimization.
+The compiler optimizes calls to versioned functions which can be statically resolved into direct calls. As a result the versioned function may be inlined into the call site.

content/learning-paths/cross-platform/function-multiversioning/semantics.md

@@ -18,9 +18,8 @@ A hardware platform is able to support multiple architectural features from the
 
 Function multiversioning provides a convenient way to select the most appropriate version of a function at runtime. The selection is permanent for the lifetime of the process and works as follows:
 
-1. Select the most specific version (the one with most features), else
-2. Select the version with the highest priority, as indicated by the [mapping table](https://arm-software.github.io/acle/main/acle.html#mapping), else
-3. Select a default version if no other versions are suitable.
+1. Select the version with the highest priority, as indicated by the [selection rules](https://arm-software.github.io/acle/main/acle.html#selection), else
+2. Select a default version if no other versions are suitable.
 
 The `default` version is the version of the function that is generated without these attributes.
 

content/learning-paths/cross-platform/function-multiversioning/streaming-mode.md

@@ -0,0 +1,83 @@
+---
+title: Compatibility with streaming mode
+weight: 6
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+Function Multi Versioning is compatible with Arm streaming mode as long as the same calling convention is used across all function versions.
+
+Use a text editor to create a file named `streaming.c` with the code below:
+
+```c
+__attribute__((target_clones("sve", "simd")))
+void ok_arm_streaming(void) __arm_streaming {}
+
+__arm_locally_streaming __attribute__((target_version("sme2")))
+void ok_arm_streaming(void) __arm_streaming {}
+
+__attribute__((target_version("default")))
+void ok_arm_streaming(void) __arm_streaming {}
+
+
+__attribute__((target_clones("sve", "simd")))
+void ok_arm_streaming_compatible(void) __arm_streaming_compatible {}
+
+__arm_locally_streaming __attribute__((target_version("sme2")))
+void ok_arm_streaming_compatible(void) __arm_streaming_compatible {}
+
+__attribute__((target_version("default")))
+void ok_arm_streaming_compatible(void) __arm_streaming_compatible {}
+
+
+__arm_locally_streaming __attribute__((target_clones("sve", "simd")))
+void ok_no_streaming(void) {}
+
+__attribute__((target_version("sme2")))
+void ok_no_streaming(void) {}
+
+__attribute__((target_version("default")))
+void ok_no_streaming(void) {}
+
+
+__attribute__((target_clones("sve", "simd")))
+void bad_mixed_streaming(void) {}
+
+__attribute__((target_version("sme2")))
+void bad_mixed_streaming(void) __arm_streaming {} // expected-error: declaration has a different calling convention
+
+__attribute__((target_version("default")))
+void bad_mixed_streaming(void) __arm_streaming_compatible {} // expected-error: declaration has a different calling convention
+
+__arm_locally_streaming __attribute__((target_version("dotprod")))
+void bad_mixed_streaming(void) __arm_streaming {} // expected-error: declaration has a different calling convention
+
+
+void n_caller(void) {
+  ok_arm_streaming();
+  ok_arm_streaming_compatible();
+  ok_no_streaming();
+  bad_mixed_streaming();
+}
+
+void s_caller(void) __arm_streaming {
+  ok_arm_streaming();
+  ok_arm_streaming_compatible();
+  ok_no_streaming();
+  bad_mixed_streaming();
+}
+
+void sc_caller(void) __arm_streaming_compatible {
+  ok_arm_streaming();
+  ok_arm_streaming_compatible();
+  ok_no_streaming();
+  bad_mixed_streaming();
+}
+```
+
+To compile with Clang, run:
+
+```console
+clang --target=aarch64-linux-gnu -march=armv8-a+sme --rtlib=compiler-rt -c streaming.c
+```