diff --git a/src/c-api.adoc b/src/c-api.adoc index 1c8219b..bdd1b3e 100644 --- a/src/c-api.adoc +++ b/src/c-api.adoc @@ -328,8 +328,21 @@ The syntax of `` describes below: [source, C] ---- -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 := ',' | @@ -350,7 +363,7 @@ same function signature. [source, 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; @@ -362,6 +375,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 <>, when there exist more than one version for the same function signature. @@ -376,38 +391,19 @@ 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: - -[source, C] ----- -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. [source, 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; @@ -425,6 +421,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 <> when there exist more than one version for the same function signature. @@ -946,3 +946,17 @@ Each queryable extension must have an associated `groupid` and `bitmask` that in | zcmop | 1 | 6 | zawrs | 1 | 7 |==== + +=== 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.