diff --git a/riscv-c-api.md b/riscv-c-api.md index 0b4129b..763ef2b 100644 --- a/riscv-c-api.md +++ b/riscv-c-api.md @@ -299,8 +299,21 @@ Each `TARGET-CLONES-ATTR-STRING` defines a distinguished version of the function The syntax of `` describes below: ``` -TARGET-CLONES-ATTR-STRING := 'arch=' EXTENSIONS - | 'default' +TARGET-CLONES-ATTR-STRING := 'default' + | ATTR-STRINGS + +ATTR-STRINGS := ATTR-STRING + | ';' ATTR-STRINGS + +ATTR-STRING := ARCH-ATTR ';' PRIORITY-ATTR + | PRIORITY-ATTR ';' ARCH-ATTR + | ARCH-ATTR + +ARCH-ATTR := 'arch=' EXTENSIONS + +PRIORITY-ATTR := 'priority=' DIGITS + +DIGITS := [0-9]+ EXTENSIONS := ',' | @@ -319,7 +332,7 @@ EXTENSION-NAME := Naming rule is defined in RISC-V ISA manual For example, the following `foo` function will have three versions but share the same function signature. ```c -__attribute__((target_clones("arch=+v", "default", "arch=+zbb"))) +__attribute__((target_clones("arch=+v;priority=2", "default", "arch=+zbb;priority=1"))) int foo(int a) { return a + 5; @@ -331,6 +344,8 @@ int bar() { } ``` +The `priority` accepts a digit as the version priority during [Version Selection](#version-selection). If `priority` isn't specified, then the priority of version defaults to zero. + It makes the compiler trigger the [function multi-version](#function-multi-version) when there exist more than one version for the same function signature. ### `__attribute__((target_version("")))` @@ -339,36 +354,18 @@ The `target_version` attribute is used to create one version of a function. Func Each `TARGET-VERSION-ATTR-STRING` defines a distinguished version of the function. If there is more than one version for the same function, it must have `default` one that indicating the translation unit scope build attributes. -The syntax of `` describes below: - -``` -TARGET-VERSION-ATTR-STRING := 'arch=' EXTENSIONS - | 'default' - -EXTENSIONS := ',' - | - -EXTENSION := - -OP := '+' - -VERSION := [0-9]+ 'p' [0-9]+ - | [1-9][0-9]* - | - -EXTENSION-NAME := Naming rule is defined in RISC-V ISA manual -``` +The syntax of `` is the same as described above for ``. For example, the following foo function has three versions. ```c -__attribute__((target_version("arch=+v"))) +__attribute__((target_version("arch=+v;priority=1"))) int foo(int a) { return a + 5; } -__attribute__((target_version("arch=+zbb"))) +__attribute__((target_version("arch=+zbb;priority=2"))) int foo(int a) { return a + 5; @@ -386,6 +383,10 @@ int bar() { } ``` +The `priority` accepts a digit as the version priority during [Version Selection](#version-selection). If `priority` isn't specified, then the priority of version defaults to zero. + +The `default` version does not accept the priority. + It makes the compiler trigger the [function multi-version](#function-multi-version) when there exist more than one version for the same function signature. ### riscv_vector_cc @@ -708,3 +709,17 @@ statements, including both RISC-V specific and common operand modifiers. Function multi-versioning(FMV) provides an approach to selecting the appropriate function according to the runtime environment. The final binary may contain all versions of the function, with the compiler generating all supported versions and the runtime selecting the appropriate one. This feature is triggered by `target_version/target_clones` function attribute. + +### Version Selection + +The process of selecting the appropriate function version during function multi-versioning follows these guidelines: + +1. The implementation of the selection algorithm is implementation-specific. +2. Once a version is selected, it remains in use for the entire duration of the process. +3. Only versions whose required features are all available in the runtime environment are eligible for selection. + +The version selection process applies the following rules in order: + +1. Among the eligible versions, select the one with the highest priority. +2. If multiple versions have equal priority, select one based on an implementation-defined heuristic. +3. If no other suitable versions are found, fall back to the "default" version.