From 436f21ac2d934f5b1f11393e86bd140a72ecfb71 Mon Sep 17 00:00:00 2001 From: Yang Yujie Date: Thu, 4 Nov 2021 17:20:02 +0800 Subject: [PATCH] Fix toolchain conventions and psABI document. --- docs/LoongArch-ELF-ABI-CN.adoc | 90 +++++++------ docs/LoongArch-ELF-ABI-EN.adoc | 91 +++++++------- docs/LoongArch-toolchain-conventions-CN.adoc | 120 ++++++++++-------- docs/LoongArch-toolchain-conventions-EN.adoc | 126 +++++++++++-------- images/compiler-isa-config-model-EN.svg | 2 +- 5 files changed, 232 insertions(+), 197 deletions(-) diff --git a/docs/LoongArch-ELF-ABI-CN.adoc b/docs/LoongArch-ELF-ABI-CN.adoc index 9180411..0cb3c7f 100644 --- a/docs/LoongArch-ELF-ABI-CN.adoc +++ b/docs/LoongArch-ELF-ABI-CN.adoc @@ -103,7 +103,7 @@ v1.00 == C 语言数据类型规格 -.lp64 数据模型 （对应基础 ABI 类型：`lp64d` `lp64f` `lp64s`） +.LP64 数据模型 （对应基础 ABI 类型：`lp64d` `lp64f` `lp64s`） [%header,cols="3,^1,^1"] |=== |标量类型 @@ -139,7 +139,7 @@ v1.00 |8 |=== -.ilp32 数据模型 （对应基础 ABI 类型：`ilp32d` `ilp32f` `ilp32s`） +.ILP32 数据模型 （对应基础 ABI 类型：`ilp32d` `ilp32f` `ilp32s`） [%header,cols="3,^1,^1"] |=== |标量类型 @@ -223,39 +223,43 @@ v1.00 |枚举值 (`e_flags[2:0]`) |含义 -|lp64d -|`0x3` -|使用 64 位通用寄存器，64位浮点寄存器和栈传参， -数据模型为 "lp64"（`long` 和指针类型宽度为64位，`int` 为32位） - -|lp64f -|`0x2` -|使用 64 位通用寄存器，32位浮点寄存器和栈传参， -数据模型为 "lp64"（`long` 和指针类型宽度为64位，`int` 为32位） +| +|`0x0` +|保留值 |lp64s |`0x1` |使用 64 位通用寄存器和栈传参， -数据模型为 "lp64"（`long` 和指针类型宽度为64位，`int` 为32位） +数据模型为 LP64（`long` 和指针类型宽度为64位，`int` 为32位） -|ilp32d -|`0x7` -|使用 32 位通用寄存器，64位浮点寄存器和栈传参， -数据模型为 "ilp32"（`int`，`long` 和指针类型宽度为32位） +|lp64f +|`0x2` +|使用 64 位通用寄存器，32位浮点寄存器和栈传参， +数据模型为 LP64（`long` 和指针类型宽度为64位，`int` 为32位） -|ilp32f -|`0x6` -|使用 32 位通用寄存器，32位浮点寄存器和栈传参， -数据模型为 "ilp32"（`int`，`long` 和指针类型宽度为32位） +|lp64d +|`0x3` +|使用 64 位通用寄存器，64位浮点寄存器和栈传参， +数据模型为 LP64（`long` 和指针类型宽度为64位，`int` 为32位） + +| +|`0x4` +|保留值 |ilp32s |`0x5` |使用 32 位通用寄存器和栈传参， -数据模型为 "ilp32"（`int`，`long` 和指针类型宽度为32位） +数据模型为 ILP32（`int`，`long` 和指针类型宽度为32位） -| -|`0x4` `0x0` -|保留值 +|ilp32f +|`0x6` +|使用 32 位通用寄存器，32位浮点寄存器和栈传参， +数据模型为 ILP32（`int`，`long` 和指针类型宽度为32位） + +|ilp32d +|`0x7` +|使用 32 位通用寄存器，64位浮点寄存器和栈传参， +数据模型为 ILP32（`int`，`long` 和指针类型宽度为32位） |=== .ABI 扩展特性标记 @@ -265,7 +269,7 @@ v1.00 |枚举值 (`e_flags[5:3]`) |含义 -|default +|base |`0x0` |默认，无扩展特性 @@ -275,31 +279,26 @@ v1.00 |=== [[abi-versioning]] -`e_flags[7:6]` 标记了 ELF 目标文件使用的 ABI 版本， -它和动态链接器标准文件名 (`ld-*.so`) 的版本后缀一一对应。 +`e_flags[7:6]` 标记了 ELF 目标文件使用的 ABI 版本。 .ABI 版本标记 -[%header,cols="2,^1,^5,^1"] +[%header,cols="2,^1,^5"] |=== |ABI 版本 |枚举值 |描述 -|动态链接器版本后缀 |`v0` |`0x0` |支持具有栈操作语义的重定位类型 -|`.0` |`v1` |`0x1` |按需保留 -|`.1` | |`0x2` `0x3` |保留值 -|`.2` `.3` |=== @@ -608,30 +607,27 @@ v1.00 |操作系统 / C 库 |Glibc 动态链接器路径 -|lp64d |default +|lp64d |base |Linux, Glibc -|/lib64/ld-linux-loongarch-lp64d.so. +|/lib64/ld-linux-loongarch-lp64d.so.1 -|lp64f |default +|lp64f |base |Linux, Glibc -|/lib64/ld-linux-loongarch-lp64f.so. +|/lib64/ld-linux-loongarch-lp64f.so.1 -|lp64s |default +|lp64s |base |Linux, Glibc -|/lib64/ld-linux-loongarch-lp64s.so. +|/lib64/ld-linux-loongarch-lp64s.so.1 -|ilp32d |default +|ilp32d |base |Linux, Glibc -|/lib32/ld-linux-loongarch-ilp32d.so. +|/lib32/ld-linux-loongarch-ilp32d.so.1 -|ilp32f |default +|ilp32f |base |Linux, Glibc -|/lib32/ld-linux-loongarch-ilp32f.so. +|/lib32/ld-linux-loongarch-ilp32f.so.1 -|ilp32s |default +|ilp32s |base |Linux, Glibc -|/lib32/ld-linux-loongarch-ilp32s.so. +|/lib32/ld-linux-loongarch-ilp32s.so.1 |=== - -表中 `` 与 ELF文件编码的 `e_flags[7:6]` 一一对应， -参见 <> 。 diff --git a/docs/LoongArch-ELF-ABI-EN.adoc b/docs/LoongArch-ELF-ABI-EN.adoc index 873a57c..d9b1b8f 100644 --- a/docs/LoongArch-ELF-ABI-EN.adoc +++ b/docs/LoongArch-ELF-ABI-EN.adoc @@ -102,7 +102,7 @@ Static registers are also known as callee-saved registers. == Type Size and Alignment -.lp64 Data Model (base ABI types: `lp64d` `lp64f` `lp64s`) +.LP64 Data Model (base ABI types: `lp64d` `lp64f` `lp64s`) [%header,cols="3,^1,^1"] |=== |Scalar type @@ -138,7 +138,7 @@ Static registers are also known as callee-saved registers. |8 |=== -.ilp32 Data Model (base ABI types: `ilp32d` `ilp32f` `ilp32s`) +.ILP32 Data Model (base ABI types: `ilp32d` `ilp32f` `ilp32s`) [%header,cols="3,^1,^1"] |=== |Scalar type @@ -220,39 +220,43 @@ The ABI type of an ELF object is uniquely identified by `e_flags[7:0]` in its he |Value of `e_flags[2:0]` |Description -|lp64d -|`0x3` -|Uses 64-bit GPRs, 64-bit FPRs and the stack for parameter passing. -Data model is "lp64", where `long` and pointers are 64-bit while `int` is 32-bit. - -|lp64f -|`0x2` -|Uses 64-bit GPRs, 32-bit FPRs and the stack for parameter passing. -Data model is "lp64", where `long` and pointers are 64-bit while `int` is 32-bit. +| +|`0x0` +|(reserved) |lp64s |`0x1` |Uses 64-bit GPRs and the stack for parameter passing. -Data model is "lp64", where `long` and pointers are 64-bit while `int` is 32-bit. +Data model is LP64, where `long` and pointers are 64-bit while `int` is 32-bit. -|ilp32d -|`0x7` -|Uses 32-bit GPRs, 64-bit FPRs and the stack for parameter passing. -Data model is "ilp32", where `int`, `long` and pointers are 32-bit. +|lp64f +|`0x2` +|Uses 64-bit GPRs, 32-bit FPRs and the stack for parameter passing. +Data model is LP64, where `long` and pointers are 64-bit while `int` is 32-bit. -|ilp32f -|`0x6` -|Uses 32-bit GPRs, 32-bit FPRs and the stack for parameter passing. -Data model is "ilp32", where `int`, `long` and pointers are 32-bit. +|lp64d +|`0x3` +|Uses 64-bit GPRs, 64-bit FPRs and the stack for parameter passing. +Data model is LP64, where `long` and pointers are 64-bit while `int` is 32-bit. + +| +|`0x4` +|(reserved) |ilp32s |`0x5` |Uses 32-bit GPRs and the stack for parameter passing. -Data model is "ilp32", where `int`, `long` and pointers are 32-bit. +Data model is ILP32, where `int`, `long` and pointers are 32-bit. -| -|`0x4` `0x0` -|(reserved) +|ilp32f +|`0x6` +|Uses 32-bit GPRs, 32-bit FPRs and the stack for parameter passing. +Data model is ILP32, where `int`, `long` and pointers are 32-bit. + +|ilp32d +|`0x7` +|Uses 32-bit GPRs, 64-bit FPRs and the stack for parameter passing. +Data model is ILP32, where `int`, `long` and pointers are 32-bit. |=== .ABI Extension types @@ -262,7 +266,7 @@ Data model is "ilp32", where `int`, `long` and pointers are 32-bit. |Value of `e_flags[5:3]` |Description -|default +|base |`0x0` |No extra ABI features. @@ -272,32 +276,26 @@ Data model is "ilp32", where `int`, `long` and pointers are 32-bit. |=== [[abi-versioning]] -`e_flags[7:6]` marks the ABI version of an ELF object, -it also corresponds to the version suffix of standard -program interpreters (`ld-*.so`). +`e_flags[7:6]` marks the ABI version of an ELF object. .ABI Version -[%header,cols="2,^1,^5,^1"] +[%header,cols="2,^1,^5"] |=== |ABI version |Value |Description -|Suffix of program interpreter filenames |`v0` |`0x0` |Stack operands base relocation type. -|`.0` |`v1` |`0x1` |Another relocation type IF needed. -|`.1` | |`0x2` `0x3` |Reserved. -|`.2` `.3` |=== @@ -606,30 +604,27 @@ with check 32-bit unsigned overflow |Operating system / C library |Program interpreter path -|lp64d |default +|lp64d |base |Linux, Glibc -|/lib64/ld-linux-loongarch-lp64d.so. +|/lib64/ld-linux-loongarch-lp64d.so.1 -|lp64f |default +|lp64f |base |Linux, Glibc -|/lib64/ld-linux-loongarch-lp64f.so. +|/lib64/ld-linux-loongarch-lp64f.so.1 -|lp64s |default +|lp64s |base |Linux, Glibc -|/lib64/ld-linux-loongarch-lp64s.so. +|/lib64/ld-linux-loongarch-lp64s.so.1 -|ilp64d |default +|ilp32d |base |Linux, Glibc -|/lib32/ld-linux-loongarch-ilp32d.so. +|/lib32/ld-linux-loongarch-ilp32d.so.1 -|ilp64f |default +|ilp32f |base |Linux, Glibc -|/lib32/ld-linux-loongarch-ilp32f.so. +|/lib32/ld-linux-loongarch-ilp32f.so.1 -|ilp64s |default +|ilp32s |base |Linux, Glibc -|/lib32/ld-linux-loongarch-ilp32s.so. +|/lib32/ld-linux-loongarch-ilp32s.so.1 |=== - -Note: Each ABI version listed in <> corresponds -to a unique ``. diff --git a/docs/LoongArch-toolchain-conventions-CN.adoc b/docs/LoongArch-toolchain-conventions-CN.adoc index e0d2cc1..3ea650a 100644 --- a/docs/LoongArch-toolchain-conventions-CN.adoc +++ b/docs/LoongArch-toolchain-conventions-CN.adoc @@ -4,6 +4,7 @@ v1.00 :docinfodir: ../themes :docinfo: shared :doctype: book +:imagesdir: ../images :toc: left :toc-title: 目录 :scripts: cjk @@ -17,17 +18,17 @@ __注：在本文档中，"架构"、"指令集架构"、"ISA" 均表示某一 与龙芯架构相关的编译器选项含义包括以下三方面： -1. *配置目标架构*：允许使用的指令集和寄存器范围； +- *配置目标架构*：允许使用的指令集和寄存器范围； -2. *配置目标 ABI*：标准数据类型的表示方法，函数调用传参、返回的实现方式； +- *配置目标 ABI*：标准数据类型的表示方法，函数调用传参、返回的实现方式； -3. *配置优化参数*：用于指导编译器优化的微架构特性。 +- *配置优化参数*：用于指导编译器优化的微架构特性。 为此，编译器应实现以下两类命令行选项： -1. *基础选项*：选择编译目标的基本配置，包括 `-march` `-mabi` `-mtune`； +- *基础选项*：选择编译目标的基本配置，包括 `-march` `-mabi` `-mtune`； -2. *扩展选项*：对基础选项或基础选项默认值的配置进行增量调整。 +- *扩展选项*：对基础选项或基础选项默认值的配置进行增量调整。 .基础选项 [%header,cols="^1m,^2,^7"] @@ -51,6 +52,10 @@ __注：在本文档中，"架构"、"指令集架构"、"ISA" 均表示某一 取值范围是 `-march` 选项的超集，默认值与 `-march` 值相同 |=== +- `-march` 和 `-mtune` 参数的取值应代表实现龙芯架构的处理器或产品系列。 + +- 原则上，不同 `-march` 取值所代表的默认指令集互不相同。 + .扩展选项 [%header,cols="^1m,^2,^7"] |=== @@ -167,17 +172,20 @@ v1.00 定义的指令集架构 [%header,cols="^1,^1,^1"] |=== |标准名称 |数据模型 |可用于传参、返回的通用/浮点寄存器宽度 -|`lp64d` |lp64 |64 / 64 -|`lp64f` |lp64 |64 / 32 -|`lp64s` |lp64 |64 / （无） -|`ilp32d` |ilp32 |32 / 64 -|`ilp32f` |ilp32 |32 / 32 -|`ilp32s` |ilp32 |32 / （无） +|`lp64d` |LP64 |64 / 64 +|`lp64f` |LP64 |64 / 32 +|`lp64s` |LP64 |64 / （无） +|`ilp32d` |ILP32 |32 / 64 +|`ilp32f` |ILP32 |32 / 32 +|`ilp32s` |ILP32 |32 / （无） |=== -下表列举了全体 ABI 扩展特性类型及其相关命令行选项，除 `default` 必须实现之外， +下表列举了全体 ABI 扩展特性类型及其相关命令行选项，除 `base` 必须实现之外， 编译器可选择实现或不实现其中任何一种。 +当引述一种 ABI 名称时，若仅给出基础 ABI 类型， +则 ABI 扩展特性类型默认为 `base` 。 + .ABI 扩展特性类型 [%header,cols="^1,^1,^1"] |=== @@ -185,45 +193,53 @@ v1.00 定义的指令集架构 |编译器选项 |含义 -|`default` +|`base` |（无） |符合 https://loongson.github.io/LoongArch-Documentation/LoongArch-ELF-ABI-CN.html[龙芯架构 ELF psABI 规范] |=== [[default-arch-abi]] -编译器的默认 ABI 应在构建时确定。此时若未明确配置 ABI 扩展类型， -则默认采用 `default` 。 - -若运行编译器时未给出 `-mabi` 或 ABI 扩展类型相关选项， -则应当使用构建时确定的基础 ABI 类型或 ABI 扩展类型。 +编译器的默认 ABI 应在构建时确定。此时若未明确配置 ABI 扩展特性类型， +则采用 `base` 。 原则上，实际配置的目标架构不应该对目标 ABI 的确定造成影响， -除非构建时配置或命令行选项对 ABI 的约束导致实现它所需的指令集特性 -超出了编译选项对 ISA 配置的约束范围。此时编译器应报错退出。 - -当编译选项不能唯一确定目标架构时， -在选择默认值之前，编译器应根据下表，从命令行显式给出的 ABI 配置 -推断 *基础架构* 和 *ISA 扩展特性* 的默认配置， -但不违反已给出编译选项对目标架构的明确约束。 - -.目标架构和默认 ABI 类型对应关系 +当命令行选项对 ABI 的明确约束导致实现它所需的指令集特性 +超出了编译选项对 ISA 配置的约束范围。编译器应报错退出。 + +若命令行选项未声明或未完整声明目标 ABI 类型， +缺失的部分（基础 ABI 或 ABI 扩展类型）应当取构建时确定的默认值。 +当编译选项中明确约束的 ISA 范围不足以实现该默认 ABI 配置时， +编译器的实际行为 *不确定* ，因为在缩减默认可用指令集范围的同时， +用户应该通过命令行选项明确表示使用何种 ABI 。 + +对于编译器实现来说，此时推荐的行为是报错退出，但出于易用性的考量， +也可以在默认配置允许的范围内谨慎地选择一种当前可用指令集能够实现的 +"降级"。对于这种情况，建议编译器输出提示或警告信息以通知用户。 +例如，对于默认 ABI 为 `lp64d` / `base` 的编译器， +若编译选项为 `-mfpu=none` ，则可能自动调整 ABI 到 `lp64s` / `base` 。 + +当编译选项不能唯一确定目标架构时，编译器应当首先检查默认值是否能满足 +ABI 配置的需要。若不能，则应根据下表，在默认可用指令集基础上增加选用 +缺失的模块，但不违反已给出编译选项对目标架构的明确约束。 + +.实现各 ABI 类型所需的最小目标架构 [%header,cols="^1,^1,^1"] |=== -|目标架构包含的 ISA 模块 -|基础 ABI -|ABI 扩展特性 +|基础 ABI 类型 +|ABI 扩展特性类型 +|最小目标架构包含的 ISA 模块 -|`la64v100` [`fpu64`] |`lp64d` -|`default` +|`base` +|`la64v100` [`fpu64`] -|`la64v100` `fpu32` |`lp64f` -|`default` +|`base` +|`la64v100` `fpu32` -|`la64v100` `fpunone` |`lp64s` -|`default` +|`base` +|`la64v100` `fpunone` |=== @@ -277,14 +293,14 @@ v1.00 定义的指令集架构 |`` 字符串 |含义 |`f64` |基础 ABI 使用 64 位浮点寄存器传参 (`lp64d` `ilp32d`) |`f32` |基础 ABI 使用 32 位浮点寄存器传参 (`lp64f` `ilp32f`) -|`sfp` |基础 ABI 不使用浮点寄存器传参 (`lp64s` `ilp32s`) +|`sf` |基础 ABI 不使用浮点寄存器传参 (`lp64s` `ilp32s`) |=== .Multiarch `os` 字段，`` 后缀标记及其对应的 ABI 扩展特性 [%header,cols="^1,^2"] |=== |`` 字符串 |ABI 扩展特性 -|（空） |`default` +|（空） |`base` |=== .全体 Mulitarch 标识符列表 @@ -294,29 +310,29 @@ v1.00 定义的指令集架构 |操作系统类型 |Multiarch 架构标识符 -|`lp64d` / `default` +|`lp64d` / `base` |GNU/Linux |`loongarch64-linux-gnuf64` -|`lp64f` / `default` +|`lp64f` / `base` |GNU/Linux |`loongarch64-linux-gnuf32` -|`lp64s` / `default` +|`lp64s` / `base` |GNU/Linux -|`loongarch64-linux-gnusfp` +|`loongarch64-linux-gnusf` -|`ilp32d` / `default` +|`ilp32d` / `base` |GNU/Linux |`loongarch32-linux-gnuf64` -|`ilp32f` / `default` +|`ilp32f` / `base` |GNU/Linux |`loongarch32-linux-gnuf32` -|`ilp32s` / `default` +|`ilp32s` / `base` |GNU/Linux -|`loongarch32-linux-gnusfp` +|`loongarch32-linux-gnusf` |=== @@ -330,7 +346,7 @@ v1.00 定义的指令集架构 |描述 |`\\__loongarch__` -|（无） +|`1` |目标为龙芯架构 |`__loongarch_grlen` @@ -339,19 +355,21 @@ v1.00 定义的指令集架构 |`__loongarch_frlen` |`0` `32` `64` -|浮点寄存器位宽（无 fpu 则为 `0` ） +|浮点寄存器位宽（无 FPU 则为 `0` ） |`_LOONGARCH_ARCH` |`"loongarch64"` `"la464"` -|相当于 `--with-arch` / `-march` 指定的目标 CPU 名称 +|`-march` 指定的目标 CPU 名称， +若未指定则为编译器构建时指定的默认值 |`_LOONGARCH_TUNE` |`"loongarch64"` `"la464"` -|相当于 `-mtune` 指定的目标 CPU 名称 +|`-mtune` 指定的目标 CPU 名称， +若未指定则为编译器构建时指定的默认值 |`__loongarch_lp64` |（无） -|ABI 使用 64 位通用寄存器传参，采用 `lp64` 数据模型 +|ABI 使用 64 位通用寄存器传参，采用 LP64 数据模型 |`__loongarch_hard_float` |（无） diff --git a/docs/LoongArch-toolchain-conventions-EN.adoc b/docs/LoongArch-toolchain-conventions-EN.adoc index 3fbc491..8d5cd4d 100644 --- a/docs/LoongArch-toolchain-conventions-EN.adoc +++ b/docs/LoongArch-toolchain-conventions-EN.adoc @@ -4,6 +4,7 @@ v1.00 :docinfodir: ../themes :docinfo: shared :doctype: book +:imagesdir: ../images :toc: left __Note: In this document, the terms "architecture", "instruction set architecture" and "ISA" @@ -18,21 +19,21 @@ they can operate upon.__ Compiler options that are specific to LoongArch should denote a change in the following compiler settings: -1. *Target architecture*: the allowed set of instructions and registers +- *Target architecture*: the allowed set of instructions and registers to be used by the compiler. -2. *Target ABI type*: the data model and calling conventions. +- *Target ABI type*: the data model and calling conventions. -3. *Target microarchitecture*: microarchitectural features that guides +- *Target microarchitecture*: microarchitectural features that guides compiler optimizations. For this model, two categories of LoongArch-specific compiler options should be implemented： -1. *Basic options*: select the base configuration of the compilation target. +- *Basic options*: select the base configuration of the compilation target. (include only `-march` `-mabi` and `-mtune`) -2. *Extended options*: make incremental changes to the target configuration. +- *Extended options*: make incremental changes to the target configuration. .Basic Options [%header,cols="^1m,^3,^6"] @@ -56,6 +57,12 @@ the basic set of <> to be enabled. The set of possible values should be a superset of `-march` values. |=== +- Valid parameter values of `-march` and `-mtune` options should correspond to +actual LoongArch processor implementations / families. + +- In principle, different `-march` values should not imply the same set +of ISA modules. + .Extended Options [%header,cols="^1m,^3,^6"] |=== @@ -86,6 +93,7 @@ The LoongArch ISA is organized in a "base-extension" manner. For future updates, each component in the __base__ or __extened__ part of the ISA may evolve independently while keeping compatibility with previous versions of itself. +[[isa-modules]] For this purpose, the compiler should make a modular abstraction about the target ISA. The ISA modules are divided into two categories： *base architectures* and *ISA extensions*. A *base architecture* is the core component of the target ISA, which defines the __base__ @@ -186,17 +194,20 @@ implemented target ISA variants. |=== |Standard name |Data model |Bit-width of argument / return value GPRs / FPRs -|`lp64d` |lp64 |64 / 64 -|`lp64f` |lp64 |64 / 32 -|`lp64s` |lp64 |64 / (none) -|`ilp32d` |ilp32 |32 / 64 -|`ilp32f` |ilp32 |32 / 32 -|`ilp32s` |ilp32 |32 / (none) +|`lp64d` |LP64 |64 / 64 +|`lp64f` |LP64 |64 / 32 +|`lp64s` |LP64 |64 / (none) +|`ilp32d` |ILP32 |32 / 64 +|`ilp32f` |ILP32 |32 / 32 +|`ilp32s` |ILP32 |32 / (none) |=== The following table lists all ABI extension types and related compiler options. A compiler may choose to implement -any subset of these extensions that contains `default`. +any subset of these extensions that contains `base`. + +The default ABI extension type is `base` when referring to +an ABI type with only the "base" component. .ABI Extension Types [%header,cols="^1,^1,^1"] @@ -205,7 +216,7 @@ any subset of these extensions that contains `default`. |Compiler options |Description -|`default` +|`base` |(none) |conforms to the https://loongson.github.io/LoongArch-Documentation/LoongArch-ELF-ABI-EN.html[LoongArch ELF psABI] |=== @@ -213,42 +224,55 @@ any subset of these extensions that contains `default`. [[default-arch-abi]] The compiler should know the default ABI to use during its build time. If the ABI extension type is not explicitly configured, -`default` should be used. - -If none of `-mabi` or other ABI-extension-related options is given on -the command line. The build-time default ABI should be selected. - -In principle, the configured target ISA should not affect the decision -of the target ABI. When certain ISA feature requirement that comes from -the ABI breaks the explicit (i.e. from the compiler options) -constraints on the target ISA, the compiler should abort with an error -message to complain about the conflict. +`base` should be used. + +In principle, the target ISA configuration should not affect the decision +of the target ABI. When certain ISA feature required by explicit +(i.e. from the compiler's command-line arguments) ABI configuration +cannot be met due constraints imposed by ISA options, the compiler should +abort with an error message to complain about the conflict. + +When the ABI is not fully constrained by the compiler options, the default +configuration of either the base ABI or the ABI extension, whichever is missing +from the command line, should be attempted. If this default ABI setting +cannot be implemented by the explicitly configured target ISA, the expected +behavior is *undefined* since the user is encouraged to specify which +ABI to use when choosing a smaller instruction set than the default. + +In this case, it is suggested that the compiler should abort with +an error message, however, for user-friendliness, it may also choose +to ignore the default base ABI or ABI extension and select a viable, +"downgraded" ABI for the currently enabled ISA modules with caution. +It is also recommended that the compiler should notify the user about the +ABI change, optionally with a compiler warning. +For example, passing `-mfpu=none` as the only command-line argument +may cause a compiler configured with `lp64d` / `base` default ABI +to automatically select `lp64s` / `base` instead. When the target ISA configuration cannot be uniquely decided from the given -compiler options, the compiler should first try inferring the -*base architecture* and *ISA extensions* from the explicit ABI configuration -(if any) before resorting to the build-time default values. -The result of this inference should not break any explicit constraints -on the target ISA imposed by other command-line options. +compiler options, the build-time default should be consulted first. +If the default ISA setting is insufficient for implementing the ABI configuration, +the compiler should try enabling the missing ISA modules according to the following +table, as long as they are not explicitly disabled or excluded from usage. -.Default correspondence between target ISA and ABI types +.Minimal architecture requirements for implementing each ABI type. [%header,cols="^1,^1,^1"] |=== -|Enabled ISA modules |Base ABI type -|ABI Extension type +|ABI extension type +|Minimal required ISA modules -|`la64v100` [`fpu64`] |`lp64d` -|`default` +|`base` +|`la64v100` [`fpu64`] -|`la64v100` `fpu32` |`lp64f` -|`default` +|`base` +|`la64v100` `fpu32` -|`la64v100` `fpunone` |`lp64s` -|`default` +|`base` +|`la64v100` `fpunone` |=== == GNU Target Triplets and Multiarch Specifiers @@ -295,14 +319,14 @@ specifier, respectively. |`` |Description |`f64` |The base ABI uses 64-bit FPRs for parameter passing. (`lp64d` `ilp32d`) |`f32` |The base ABI uses 32-bit FPRs for parameter passing. (`lp64f` `ilp32f`) -|`sfp` |The base ABI uses no FPR for parameter passing. (`lp64s` `ilp32s`) +|`sf` |The base ABI uses no FPR for parameter passing. (`lp64s` `ilp32s`) |=== .List of possible `` [%header,cols="^1,^2"] |=== |`` |ABI extension type -|(empty string) |`default` +|(empty string) |`base` |=== __(Note: Since in principle, <> @@ -316,29 +340,29 @@ multiple multiarch specifiers for one OS / ABI combination.)__ |OS type |Multiarch specifier -|`lp64d` / `default` +|`lp64d` / `base` |GNU/Linux |`loongarch64-linux-gnuf64` -|`lp64f` / `default` +|`lp64f` / `base` |GNU/Linux |`loongarch64-linux-gnuf32` -|`lp64s` / `default` +|`lp64s` / `base` |GNU/Linux -|`loongarch64-linux-gnusfp` +|`loongarch64-linux-gnusf` -|`ilp32d` / `default` +|`ilp32d` / `base` |GNU/Linux |`loongarch32-linux-gnuf64` -|`ilp32f` / `default` +|`ilp32f` / `base` |GNU/Linux |`loongarch32-linux-gnuf32` -|`ilp32s` / `default` +|`ilp32s` / `base` |GNU/Linux -|`loongarch32-linux-gnusfp` +|`loongarch32-linux-gnusf` |=== == C/C++ Preprocessor Definitions @@ -351,7 +375,7 @@ multiple multiarch specifiers for one OS / ABI combination.)__ |Description |`\\__loongarch__` -|(none) +|`1` |Defined if the target is LoongArch. |`__loongarch_grlen` @@ -364,15 +388,17 @@ multiple multiarch specifiers for one OS / ABI combination.)__ |`_LOONGARCH_ARCH` |`"loongarch64"` `"la464"` -|Processor model as specified by `--with-arch` / `-march`. +|Processor model as specified by `-march`. +If `-march` is not present, the build-time default should be used. |`_LOONGARCH_TUNE` |`"loongarch64"` `"la464"` |Processor model as specified by `-mtune`. +If `-mtune` is not present, the build-time default should be used. |`__loongarch_lp64` |(none) -|Defined if integer ABI type is `lp64`. +|Defined if ABI uses the LP64 data model and 64-bit GPRs for parameter passing. |`__loongarch_hard_float` |(none) diff --git a/images/compiler-isa-config-model-EN.svg b/images/compiler-isa-config-model-EN.svg index 1f19ca4..ab96ddd 100644 --- a/images/compiler-isa-config-model-EN.svg +++ b/images/compiler-isa-config-model-EN.svg @@ -820,7 +820,7 @@ style="stroke-width:0.079375" y="106.24174" x="112.1204" - sodipodi:role="line">extended options that alters the range of enable ISAextended options that alters the range of enabled ISA