diff --git a/docs/LoongArch-toolchain-conventions-CN.adoc b/docs/LoongArch-toolchain-conventions-CN.adoc index 696c2de..d260389 100644 --- a/docs/LoongArch-toolchain-conventions-CN.adoc +++ b/docs/LoongArch-toolchain-conventions-CN.adoc @@ -1,6 +1,6 @@ = 龙芯架构工具链约定 龙芯中科技术股份有限公司 -v1.00 +v2.00 :docinfodir: ../themes :docinfo: shared :doctype: book @@ -290,6 +290,18 @@ ABI 配置的需要。若不能,则应根据下表,在默认可用指令集 基础 ABI 的浮点部分和 ABI 扩展特性则分别由连续附加在 multiarch 标识符 `os` 字段后的两个字符串后缀 (``) 标记。 +本《约定》的 1.00 版本曾规定了基础 ABI 使用 64 位浮点寄存器传参时的 +`` 后缀为 `f64` (意味着类似 `loongarch64-linux-gnuf64` 的 +multiarch 架构标识符取值)。 +2.00 版本起将其改为空字符串,是考虑到最常见的组合适合尽量短的名字, +因此不介意文本上的不兼容变更。 +为尽可能维持向后兼容,应在见到 `gnuf64` 这一目标元组环境字段取值时, +将其视为(标准化为) `gnu` 如果这样做因不会带来其他超越近处业务逻辑的外部副作用而可行。 +(例如:如果维持对 `gnuf64` 的兼容性涉及必须添加符号链接或复制文件, +从而不得不产生文件系统、目录结构等方面的副作用,那么就不再视这样代价的兼容为“可行”。 +一个具体实例是 Python 的原生扩展 `.so` 文件带且只能带唯一的 multiarch 架构标识符, +此时便无法做到兼容本《约定》的 v1.00 了。) + .Multiarch `os` 字段,`` 后缀标记及其含义 [%header,cols="^1,^2"] |=== @@ -512,3 +524,15 @@ LoongArch 平台特有的预处理器内建宏。下表列举了这些架构相 |`\\__SIZEOF_POINTER__` 乘以 8 |(无) |=== + +== 附录:版本修订历史 + +- **v1.00** + + * 初始版本。 + +- **v2.00** + + * 不兼容地修订 multiarch 架构标识符的相关内容: + ** 移除为 ILP32 ABIs 预留的 multiarch 架构标识符。 + ** 修改浮点 ABI 后缀 `f64` 为空值。 diff --git a/docs/LoongArch-toolchain-conventions-EN.adoc b/docs/LoongArch-toolchain-conventions-EN.adoc index 9d29841..a5c7dfb 100644 --- a/docs/LoongArch-toolchain-conventions-EN.adoc +++ b/docs/LoongArch-toolchain-conventions-EN.adoc @@ -1,6 +1,6 @@ = LoongArch Toolchain Conventions Loongson Technology Corporation Limited -v1.00 +v2.00 :docinfodir: ../themes :docinfo: shared :doctype: book @@ -331,6 +331,23 @@ the floating-point base ABI and the ABI extension type are encoded with two string suffices (``) to the `os` field of the specifier, respectively. +Version 1.00 of this document mandated that a `` of `f64` shall +be used for cases where the base ABI used 64-bit FPRs for parameter passing +(meaning multiarch architecture specifier values resembling `loongarch64-linux-gnuf64`). +From version 2.00 onwards it was changed into the empty string; +the incompatible textual change is justified by the rationale that shorter +names are preferred for the more ubiquitous combinations. +For maintaining best-effort backwards compatibility, the target tuple environment +value `gnuf64` shall be treated as (canonicalized into) `gnu` if doing so +would be feasible by not bringing any external side effects that goes beyond +the local domain-specific logic (aka "business logic"). +(For example: if one must symlink and/or copy files to maintain compatibility +with `gnuf64`, incurring necessary side effects at the filesystem / directory +layout level, then the compatibility would be deemed too costly to be "feasible". +A concrete case would be Python, whose native extensions' file names contain +exactly one multiarch architecture specifier. In this case there is unfortunately +no way to accommodate v1.00 of this document.) + .List of possible `` [%header,cols="^1,^2"] |=== @@ -555,3 +572,15 @@ portable code should not assume existence of these macros, nor use them. |`\\__SIZEOF_POINTER__` multiplied by 8 |n/a |=== + +== Appendix: Revision History + +- **v1.00** + + * Initial version of the specification. + +- **v2.00** + + * Incompatibly revise the multiarch architecture specifiers: + ** Remove multiarch architecture specifiers reserved for the ILP32 ABIs. + ** Change the floating-point ABI suffix `f64` into the empty string.