From cbfdd81cefa1fdd7684fa61238a4949a728860af Mon Sep 17 00:00:00 2001 From: WANG Xuerui Date: Sat, 11 Feb 2023 14:14:58 +0800 Subject: [PATCH 1/3] Clarify the new toolchain conventions revision. * Bump document version. * Add explanatory content to aid the anticipated transition. * Add a revision history similar to those in the ELF psABI docs. It's unfortunately true that LoongArch specification work *can be* behind the doors at times, as the transparency is *expectedly* lower than that of e.g. RISC-V, but at least we could do better in the wording and make readers less confused about the abrupt change to previous agreed-upon content. Fixes: 55dbaad ("Adjust the Multiarch Specifier") --- docs/LoongArch-toolchain-conventions-CN.adoc | 24 ++++++++++++++++- docs/LoongArch-toolchain-conventions-EN.adoc | 28 +++++++++++++++++++- 2 files changed, 50 insertions(+), 2 deletions(-) diff --git a/docs/LoongArch-toolchain-conventions-CN.adoc b/docs/LoongArch-toolchain-conventions-CN.adoc index 696c2de..854a0dc 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,16 @@ ABI 配置的需要。若不能，则应根据下表，在默认可用指令集 基础 ABI 的浮点部分和 ABI 扩展特性则分别由连续附加在 multiarch 标识符 `os` 字段后的两个字符串后缀 (``) 标记。 +本《约定》的 1.00 版本曾规定了基础 ABI 使用 64 位浮点寄存器传参时的 +`` 后缀为 `f64` （意味着类似 `loongarch64-linux-gnuf64` 的 +multiarch 架构标识符取值）。 +为保持兼容，应在见到 `gnuf64` 这一目标元组环境字段取值时，将其视为（标准化为） +`gnu` ，如果这样做具备可行性，且不会带来其他超越近处业务逻辑的外部副作用。 +（例如：如果实现对 `gnuf64` 的兼容性涉及必须添加符号链接或复制文件， +从而将产生文件系统、目录结构等方面的副作用，那么就不再视这样代价的兼容为“可行”。 +一个具体实例是 Python 的原生扩展 `.so` 文件带且只能带唯一的 multiarch 架构标识符， +此时便无法做到兼容本《约定》的 v1.00 了。） + .Multiarch `os` 字段，`` 后缀标记及其含义 [%header,cols="^1,^2"] |=== @@ -512,3 +522,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..0bffbd8 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,20 @@ 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`). +For backwards compatibility, the target tuple environment value `gnuf64` shall +be treated as (canonicalized into) `gnu` if doing so would be feasible and 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 side effects at filesystem / directory layout level, +then the compatibility would be 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 it would be +impossible to accommodate v1.00 of this document.) + .List of possible `` [%header,cols="^1,^2"] |=== @@ -555,3 +569,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. From 2e2613d67efb46c79ad7b03ffcb0209a4c7f6dc0 Mon Sep 17 00:00:00 2001 From: WANG Xuerui Date: Sat, 11 Feb 2023 14:27:44 +0800 Subject: [PATCH 2/3] Tweak wording regarding best-effort compatibility wrt multiarch tuples. It's not possible to maintain 100% backwards compatibility so make it clear. Also slightly reword some sentences. --- docs/LoongArch-toolchain-conventions-CN.adoc | 8 ++++---- docs/LoongArch-toolchain-conventions-EN.adoc | 18 +++++++++--------- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/LoongArch-toolchain-conventions-CN.adoc b/docs/LoongArch-toolchain-conventions-CN.adoc index 854a0dc..371c8a6 100644 --- a/docs/LoongArch-toolchain-conventions-CN.adoc +++ b/docs/LoongArch-toolchain-conventions-CN.adoc @@ -293,10 +293,10 @@ ABI 配置的需要。若不能，则应根据下表，在默认可用指令集 本《约定》的 1.00 版本曾规定了基础 ABI 使用 64 位浮点寄存器传参时的 `` 后缀为 `f64` （意味着类似 `loongarch64-linux-gnuf64` 的 multiarch 架构标识符取值）。 -为保持兼容，应在见到 `gnuf64` 这一目标元组环境字段取值时，将其视为（标准化为） -`gnu` ，如果这样做具备可行性，且不会带来其他超越近处业务逻辑的外部副作用。 -（例如：如果实现对 `gnuf64` 的兼容性涉及必须添加符号链接或复制文件， -从而将产生文件系统、目录结构等方面的副作用，那么就不再视这样代价的兼容为“可行”。 +为尽可能维持向后兼容，应在见到 `gnuf64` 这一目标元组环境字段取值时， +将其视为（标准化为） `gnu` 如果这样做因不会带来其他超越近处业务逻辑的外部副作用而可行。 +（例如：如果维持对 `gnuf64` 的兼容性涉及必须添加符号链接或复制文件， +从而不得不产生文件系统、目录结构等方面的副作用，那么就不再视这样代价的兼容为“可行”。 一个具体实例是 Python 的原生扩展 `.so` 文件带且只能带唯一的 multiarch 架构标识符， 此时便无法做到兼容本《约定》的 v1.00 了。） diff --git a/docs/LoongArch-toolchain-conventions-EN.adoc b/docs/LoongArch-toolchain-conventions-EN.adoc index 0bffbd8..328cdd7 100644 --- a/docs/LoongArch-toolchain-conventions-EN.adoc +++ b/docs/LoongArch-toolchain-conventions-EN.adoc @@ -334,16 +334,16 @@ 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`). -For backwards compatibility, the target tuple environment value `gnuf64` shall -be treated as (canonicalized into) `gnu` if doing so would be feasible and not -bringing any external side effects that goes beyond the local domain-specific -logic (aka "business logic"). +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 side effects at filesystem / directory layout level, -then the compatibility would be 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 it would be -impossible to accommodate v1.00 of this document.) +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"] From c40cbe2c0bd891d32365945c866d0f35464e07fc Mon Sep 17 00:00:00 2001 From: WANG Xuerui Date: Sat, 11 Feb 2023 14:39:57 +0800 Subject: [PATCH 3/3] Add a possible justification for the multiarch specifier change. This is without the commercial reasons (see the linked PR) to hopefully make the change more palatable to the angry mob of unknowing readers. For the record: this is DEFINITELY NOT the full reason behind the closed-door decision. But this is about as close as we community people can get in persuading the depressed ourselves, and about all I can disclose after having multiple private conversations with relevant parties, without inflicting damage to anyone at Loongson or Loongson as a whole (we don't really want to openly criticize Loongson for tweaking a 1-year-old document for primarily commercial reasons, but again it's arguably fair for a privately-controlled ISA to evolve like this). See: https://github.com/loongson/LoongArch-Documentation/pull/80 --- docs/LoongArch-toolchain-conventions-CN.adoc | 2 ++ docs/LoongArch-toolchain-conventions-EN.adoc | 3 +++ 2 files changed, 5 insertions(+) diff --git a/docs/LoongArch-toolchain-conventions-CN.adoc b/docs/LoongArch-toolchain-conventions-CN.adoc index 371c8a6..d260389 100644 --- a/docs/LoongArch-toolchain-conventions-CN.adoc +++ b/docs/LoongArch-toolchain-conventions-CN.adoc @@ -293,6 +293,8 @@ ABI 配置的需要。若不能，则应根据下表，在默认可用指令集 本《约定》的 1.00 版本曾规定了基础 ABI 使用 64 位浮点寄存器传参时的 `` 后缀为 `f64` （意味着类似 `loongarch64-linux-gnuf64` 的 multiarch 架构标识符取值）。 +2.00 版本起将其改为空字符串，是考虑到最常见的组合适合尽量短的名字， +因此不介意文本上的不兼容变更。 为尽可能维持向后兼容，应在见到 `gnuf64` 这一目标元组环境字段取值时， 将其视为（标准化为） `gnu` 如果这样做因不会带来其他超越近处业务逻辑的外部副作用而可行。 （例如：如果维持对 `gnuf64` 的兼容性涉及必须添加符号链接或复制文件， diff --git a/docs/LoongArch-toolchain-conventions-EN.adoc b/docs/LoongArch-toolchain-conventions-EN.adoc index 328cdd7..a5c7dfb 100644 --- a/docs/LoongArch-toolchain-conventions-EN.adoc +++ b/docs/LoongArch-toolchain-conventions-EN.adoc @@ -334,6 +334,9 @@ 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