From 77026a9f172b2791606bec617905b45b2d7442df Mon Sep 17 00:00:00 2001 From: Yang Yujie Date: Thu, 21 Oct 2021 20:41:55 +0800 Subject: [PATCH] Update LoongArch psABI and toolchain conventions. --- docs/LoongArch-ELF-ABI-CN.adoc | 279 ++++-- docs/LoongArch-ELF-ABI-EN.adoc | 285 +++++-- docs/LoongArch-toolchain-conventions-CN.adoc | 383 +++++++++ docs/LoongArch-toolchain-conventions-EN.adoc | 404 +++++++++ docs/README-CN.adoc | 6 +- docs/README-EN.adoc | 6 +- images/compiler-isa-config-model-CN.svg | 840 +++++++++++++++++++ images/compiler-isa-config-model-EN.svg | 836 ++++++++++++++++++ 8 files changed, 2866 insertions(+), 173 deletions(-) create mode 100644 docs/LoongArch-toolchain-conventions-CN.adoc create mode 100644 docs/LoongArch-toolchain-conventions-EN.adoc create mode 100644 images/compiler-isa-config-model-CN.svg create mode 100644 images/compiler-isa-config-model-EN.svg diff --git a/docs/LoongArch-ELF-ABI-CN.adoc b/docs/LoongArch-ELF-ABI-CN.adoc index 3ed2f55..9180411 100644 --- a/docs/LoongArch-ELF-ABI-CN.adoc +++ b/docs/LoongArch-ELF-ABI-CN.adoc @@ -11,89 +11,89 @@ v1.00 == 寄存器使用约定 .通用寄存器使用约定 -[%header,cols="2m,2m,^5,^3"] +[%header,cols="2,2,^5,^3"] |=== |名称 |别名 |用途 |在调用中是否保留 -|$r0 -|$zero -|常数 0 -|-- +|`$r0` +|`$zero` +|常数 `0` +|（常数） -|$r1 -|$ra +|`$r1` +|`$ra` |返回地址 |否 -|$r2 -|$tp +|`$r2` +|`$tp` |线程指针 -|-- （不可分配） +|（不可分配） -|$r3 -|$sp +|`$r3` +|`$sp` |栈指针 |是 -|$r4-$r11 -|$a0-$a7 +|`$r4` - `$r11` +|`$a0` - `$a7` |传参寄存器 |否 -|$r4-$r5 -|$v0-$v1 +|`$r4` - `$r5` +|`$v0` - `$v1` |返回值 |否 -|$r12-$r20 -|$t0-$t8 +|`$r12` - `$r20` +|`$t0` - `$t8` |临时寄存器 |否 -|$r21 -|-- +|`$r21` +| |保留 -|-- （不可分配） +|（不可分配） -|$r22 -|$fp/$s9 +|`$r22` +|`$fp` / `$s9` |栈帧指针 / 静态寄存器 |是 -|$r23-$r31 -|$s0-$s8 +|`$r23` - `$r31` +|`$s0` - `$s8` |静态寄存器 |是 |=== .浮点寄存器使用约定 -[%header,cols="2m,2m,^5,^3"] +[%header,cols="2,2,^5,^3"] |=== |名称 |别名 |用途 |在调用中是否保留 -|$f0-$f7 -|$fa0-$fa7 +|`$f0` - `$f7` +|`$fa0` - `$fa7` |传参寄存器 |否 -|$f0-$f1 -|$fv0-$fv7 +|`$f0` - `$f1` +|`$fv0` - `$fv1` |返回值 |否 -|$f8-$f23 -|$ft0-$ft15 +|`$f8` - `$f23` +|`$ft0` - `$ft15` |临时寄存器 |否 -|$f24-$f31 -|$fs0-$fs7 +|`$f24` - `$f31` +|`$fs0` - `$fs7` |静态寄存器 |是 |=== @@ -103,61 +103,89 @@ v1.00 == C 语言数据类型规格 -.LP64 ABI -[%header,cols="3m,^1,^1"] +.lp64 数据模型 （对应基础 ABI 类型：`lp64d` `lp64f` `lp64s`） +[%header,cols="3,^1,^1"] |=== |标量类型 |大小（字节） |对齐（字节） -|bool/_Bool +|`bool` / `_Bool` |1 |1 -|unsigned/signed char +|`unsigned char` / `char` |1 |1 -|unsigned/signed short +|`unsigned short` / `short` |2 |2 -|unsigned/signed int +|`unsigned int` / `int` |4 |4 -|unsigned/signed long +|`unsigned long` / `long` |8 |8 -|unsigned/signed long long +|`unsigned long long` / `long long` |8 |8 |指针类型 |8 |8 +|=== + +.ilp32 数据模型 （对应基础 ABI 类型：`ilp32d` `ilp32f` `ilp32s`） +[%header,cols="3,^1,^1"] +|=== +|标量类型 +|大小（字节） +|对齐（字节） -|float +|`bool` / `_Bool` +|1 +|1 + +|`unsigned char` / `char` +|1 +|1 + +|`unsigned short` / `short` +|2 +|2 + +|`unsigned int` / `int` +|4 +|4 + +|`unsigned long` / `long` |4 |4 -|double +|`unsigned long long` / `long long` |8 |8 -|long double -|16 -|16 +|指针类型 +|4 +|4 |=== -`char` 是有符号类型。 +对于任何<>，`char` 默认是有符号类型。 + == ELF 目标文件 -=== EI_CLASS: ELF 文件格式 +本节内容中关于 ELF 目标文件的通用格式定义 +均参考 http://sco.com/developers/gabi/latest/contents.html[最新版本的 SysV gABI]。 -[%header,cols="2m,^1,^3"] +=== `EI_CLASS`: ELF 文件格式 + +[%header,cols="2m,^1m,^3"] |=== |EI_CLASS |枚举值 @@ -172,64 +200,109 @@ v1.00 |64 位 ELF 格式 |=== -=== e_machine: 体系结构 ID +=== `e_machine`: 体系结构 ID + +`LoongArch (258)` + +=== `e_flags`: ABI 类型和版本标记 + +[%header,cols="1,1,1,1"] +|=== +|`[31:8]` 位 | `[7:6]` 位 | `[5:3]` 位 | `[2:0]` 位 -LoongArch (258) +|（保留） | ABI 版本 | ABI 扩展特性 | 基础 ABI 类型 +|=== -=== e_flags: ABI 变体标记 +`e_flags[7:0]` 完整标记了 ELF 目标文件使用的 ABI 类型。 +[[base-abi-type-marks]] +.基础 ABI 类型标记 [%header,cols="2m,^1,^3"] |=== -|ABIs -|枚举值 +|基础 ABI 名称 +|枚举值 (`e_flags[2:0]`) |含义 -|lp32 -|0x1 -|32 位整型 ABI，仅支持软件浮点数 +|lp64d +|`0x3` +|使用 64 位通用寄存器，64位浮点寄存器和栈传参， +数据模型为 "lp64"（`long` 和指针类型宽度为64位，`int` 为32位） + +|lp64f +|`0x2` +|使用 64 位通用寄存器，32位浮点寄存器和栈传参， +数据模型为 "lp64"（`long` 和指针类型宽度为64位，`int` 为32位） + +|lp64s +|`0x1` +|使用 64 位通用寄存器和栈传参， +数据模型为 "lp64"（`long` 和指针类型宽度为64位，`int` 为32位） -|（保留值） -|0x2 -|-- +|ilp32d +|`0x7` +|使用 32 位通用寄存器，64位浮点寄存器和栈传参， +数据模型为 "ilp32"（`int`，`long` 和指针类型宽度为32位） -|lp64 -|0x3 -|64 位整型 ABI，支持双精度硬件浮点数 +|ilp32f +|`0x6` +|使用 32 位通用寄存器，32位浮点寄存器和栈传参， +数据模型为 "ilp32"（`int`，`long` 和指针类型宽度为32位） -|lp32f -|0x4 -|32 位整型 ABI，支持单精度硬件浮点数 +|ilp32s +|`0x5` +|使用 32 位通用寄存器和栈传参， +数据模型为 "ilp32"（`int`，`long` 和指针类型宽度为32位） -|lp32d -|0x5 -|32 位整型 ABI，支持双精度硬件浮点数 +| +|`0x4` `0x0` +|保留值 +|=== -|（保留值） -|0x6 -- -|-- +.ABI 扩展特性标记 +[%header,cols="2m,^1,^3"] |=== +|ABI 扩展特性名称 +|枚举值 (`e_flags[5:3]`) +|含义 -=== ABI 版本 +|default +|`0x0` +|默认，无扩展特性 -[%header,cols="2m,^1,^5"] +| +|`0x1` - `0x7` +|保留值 +|=== + +[[abi-versioning]] +`e_flags[7:6]` 标记了 ELF 目标文件使用的 ABI 版本， +它和动态链接器标准文件名 (`ld-*.so`) 的版本后缀一一对应。 + +.ABI 版本标记 +[%header,cols="2,^1,^5,^1"] |=== |ABI 版本 |枚举值 |描述 +|动态链接器版本后缀 -|v0 -|0 -|支持具有栈操作语义的重定位类型（旧版兼容） +|`v0` +|`0x0` +|支持具有栈操作语义的重定位类型 +|`.0` -|v1 -|1 -|新版重定位类型 +|`v1` +|`0x1` +|按需保留 +|`.1` -|-- -|2 -- -|保留 +| +|`0x2` `0x3` +|保留值 +|`.2` `.3` |=== + == 重定位类型 .ELF 重定位类型 @@ -524,3 +597,41 @@ LoongArch (258) |GNU C++ vtable 支持 | |=== + + +== 动态链接器路径 + +.标准动态链接器路径列表： +[%header,cols="^1m,^1m,^2,^3m"] +|=== +|基础 ABI 类型 |ABI 扩展特性 +|操作系统 / C 库 +|Glibc 动态链接器路径 + +|lp64d |default +|Linux, Glibc +|/lib64/ld-linux-loongarch-lp64d.so. + +|lp64f |default +|Linux, Glibc +|/lib64/ld-linux-loongarch-lp64f.so. + +|lp64s |default +|Linux, Glibc +|/lib64/ld-linux-loongarch-lp64s.so. + +|ilp32d |default +|Linux, Glibc +|/lib32/ld-linux-loongarch-ilp32d.so. + +|ilp32f |default +|Linux, Glibc +|/lib32/ld-linux-loongarch-ilp32f.so. + +|ilp32s |default +|Linux, Glibc +|/lib32/ld-linux-loongarch-ilp32s.so. +|=== + +表中 `` 与 ELF文件编码的 `e_flags[7:6]` 一一对应， +参见 <> 。 diff --git a/docs/LoongArch-ELF-ABI-EN.adoc b/docs/LoongArch-ELF-ABI-EN.adoc index 3e54b6a..873a57c 100644 --- a/docs/LoongArch-ELF-ABI-EN.adoc +++ b/docs/LoongArch-ELF-ABI-EN.adoc @@ -9,89 +9,89 @@ v1.00 == Register Convention .Integer Register Convention -[%header,cols="2m,2m,^5,^3"] +[%header,cols="2,2,^5,^3"] |=== |Name |Alias |Meaning |Preserved across calls -|$r0 -|$zero +|`$r0` +|`$zero` |Constant zero -|-- +|(Constant) -|$r1 -|$ra +|`$r1` +|`$ra` |Return address |No -|$r2 -|$tp +|`$r2` +|`$tp` |Thread pointer -|-- (Unallocatable) +|(Non-allocatable) -|$r3 -|$sp +|`$r3` +|`$sp` |Stack pointer |Yes -|$r4-$r11 -|$a0-$a7 +|`$r4` - `$r11` +|`$a0` - `$a7` |Argument registers |No -|$r4-$r5 -|$v0-$v1 +|`$r4` - `$r5` +|`$v0` - `$v1` |Return value |No -|$r12-$r20 -|$t0-$t8 +|`$r12` - `$r20` +|`$t0` - `$t8` |Temporary registers |No -|$r21 -|-- +|`$r21` +| |Reserved -|-- (Unallocatable) +|(Non-allocatable) -|$r22 -|$fp/$s9 -|Frame pointer/Static register +|`$r22` +|`$fp` / `$s9` +|Frame pointer / Static register |Yes -|$r23-$r31 -|$s0-$s8 +|`$r23` - `$r31` +|`$s0` - `$s8` |Static registers |Yes |=== .Floating-point Register Convention -[%header,cols="2m,2m,^5,^3"] +[%header,cols="2,2,^5,^3"] |=== |Name |Alias |Meaning |Preserved across calls -|$f0-$f7 -|$fa0-$fa7 +|`$f0` - `$f7` +|`$fa0` - `$fa7` |Argument registers |No -|$f0-$f1 -|$fv0-$fv7 +|`$f0` - `$f1` +|`$fv0` - `$fv1` |Return value |No -|$f8-$f23 -|$ft0-$ft15 +|`$f8` - `$f23` +|`$ft0` - `$ft15` |Temporary registers |No -|$f24-$f31 -|$fs0-$fs7 +|`$f24` - `$f31` +|`$fs0` - `$fs7` |Static registers |Yes |=== @@ -99,63 +99,92 @@ v1.00 Temporary registers are also known as caller-saved registers. Static registers are also known as callee-saved registers. + == Type Size and Alignment -.LP64 ABI -[%header,cols="3m,^1,^1"] +.lp64 Data Model (base ABI types: `lp64d` `lp64f` `lp64s`) +[%header,cols="3,^1,^1"] |=== |Scalar type -|Size(Bytes) -|Alignment(Bytes) +|Size (Bytes) +|Alignment (Bytes) -|bool/_Bool +|`bool` / `_Bool` |1 |1 -|unsigned/signed char +|`unsigned char` / `char` |1 |1 -|unsigned/signed short +|`unsigned short` / `short` |2 |2 -|unsigned/signed int +|`unsigned int` / `int` |4 |4 -|unsigned/signed long +|`unsigned long` / `long` |8 |8 -|unsigned/signed long long +|`unsigned long long` / `long long` |8 |8 -|pointer +|pointer types |8 |8 +|=== + +.ilp32 Data Model (base ABI types: `ilp32d` `ilp32f` `ilp32s`) +[%header,cols="3,^1,^1"] +|=== +|Scalar type +|Size (Bytes) +|Alignment (Bytes) + +|`bool` / `_Bool` +|1 +|1 + +|`unsigned char` / `char` +|1 +|1 + +|`unsigned short` / `short` +|2 +|2 + +|`unsigned int` / `int` +|4 +|4 -|float +|`unsigned long` / `long` |4 |4 -|double +|`unsigned long long` / `long long` |8 |8 -|long double -|16 -|16 +|pointer types +|4 +|4 |=== -`char` is signed. +For all base ABI types of LoongArch, the `char` datatype is signed by default. + == ELF Object Files -=== EI_CLASS: File class +All common ELF definitions referenced in this section +can be found in http://sco.com/developers/gabi/latest/contents.html[the latest SysV gABI specification]. -[%header,cols="2m,^1,^3"] +=== `EI_CLASS`: File class + +[%header,cols="2m,^1m,^3"] |=== |EI_CLASS |Value @@ -163,71 +192,115 @@ Static registers are also known as callee-saved registers. |ELFCLASS32 |1 -|32-bit objects +|ELF32 object file |ELFCLASS64 |2 -|64-bit objects +|ELF64 object file |=== -=== e_machine: Identifies the machine +=== `e_machine`: Identifies the machine + +`LoongArch (258)` + +=== `e_flags`: Identifies ABI type and version -LoongArch (258) +[%header,cols="1,1,1,1"] +|==== +| Bit 31 - 8 | Bit 7 - 6 | Bit 5 - 3 | Bit 2 - 0 +| (reserved) | ABI version | ABI extension | Base ABI +|==== -=== e_flags: Identifies the ABIs of this ELF file +The ABI type of an ELF object is uniquely identified by `e_flags[7:0]` in its header. +.Base ABI Types [%header,cols="2m,^1,^3"] |=== -|ABIs -|Value +|Name +|Value of `e_flags[2:0]` |Description -|lp32 -|0x1 -|soft float +|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. -|Reserved -|0x2 -|-- +|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. -|lp64 -|0x3 -|64bit default ABI +|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. -|lp32f -|0x4 -|single float +|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. -|lp32d -|0x5 -|double float +|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. -|Reserved -|0x6 -- -|-- +|ilp32s +|`0x5` +|Uses 32-bit GPRs and the stack for parameter passing. +Data model is "ilp32", where `int`, `long` and pointers are 32-bit. + +| +|`0x4` `0x0` +|(reserved) +|=== + +.ABI Extension types +[%header,cols="2m,^1,^3"] +|=== +|Name +|Value of `e_flags[5:3]` +|Description + +|default +|`0x0` +|No extra ABI features. + +| +|`0x1` - `0x7` +|(reserved) |=== -=== ABI Version +[[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`). -[%header,cols="2m,^1,^5"] +.ABI Version +[%header,cols="2,^1,^5,^1"] |=== -|ABI Version: +|ABI version |Value |Description +|Suffix of program interpreter filenames -|v0 -|0 +|`v0` +|`0x0` |Stack operands base relocation type. +|`.0` -|v1 -|1 +|`v1` +|`0x1` |Another relocation type IF needed. +|`.1` -|-- -|2 -- +| +|`0x2` `0x3` |Reserved. +|`.2` `.3` |=== + == Relocations .ELF Relocation types @@ -522,3 +595,41 @@ with check 32-bit unsigned overflow |GNU C++ vtable member usage | |=== + + +== Program Interpreter Path + +.Standard Program Interpreter Paths +[%header,cols="^1m,^1m,^2,^3m"] +|=== +|Base ABI type |ABI extension type +|Operating system / C library +|Program interpreter path + +|lp64d |default +|Linux, Glibc +|/lib64/ld-linux-loongarch-lp64d.so. + +|lp64f |default +|Linux, Glibc +|/lib64/ld-linux-loongarch-lp64f.so. + +|lp64s |default +|Linux, Glibc +|/lib64/ld-linux-loongarch-lp64s.so. + +|ilp64d |default +|Linux, Glibc +|/lib32/ld-linux-loongarch-ilp32d.so. + +|ilp64f |default +|Linux, Glibc +|/lib32/ld-linux-loongarch-ilp32f.so. + +|ilp64s |default +|Linux, Glibc +|/lib32/ld-linux-loongarch-ilp32s.so. +|=== + +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 new file mode 100644 index 0000000..e0d2cc1 --- /dev/null +++ b/docs/LoongArch-toolchain-conventions-CN.adoc @@ -0,0 +1,383 @@ += 龙芯架构工具链约定 +龙芯中科技术股份有限公司 +v1.00 +:docinfodir: ../themes +:docinfo: shared +:doctype: book +:toc: left +:toc-title: 目录 +:scripts: cjk + +__注：在本文档中，"架构"、"指令集架构"、"ISA" 均表示某一指令集和可操作的寄存器集合。__ + + +== 编译器命令行选项 + +=== 概述 + +与龙芯架构相关的编译器选项含义包括以下三方面： + +1. *配置目标架构*：允许使用的指令集和寄存器范围； + +2. *配置目标 ABI*：标准数据类型的表示方法，函数调用传参、返回的实现方式； + +3. *配置优化参数*：用于指导编译器优化的微架构特性。 + +为此，编译器应实现以下两类命令行选项： + +1. *基础选项*：选择编译目标的基本配置，包括 `-march` `-mabi` `-mtune`； + +2. *扩展选项*：对基础选项或基础选项默认值的配置进行增量调整。 + +.基础选项 +[%header,cols="^1m,^2,^7"] +|=== +|选项 +|可用值 +|描述 + +|-march= +|`native` `loongarch64` `la464` +|选择目标架构：设定默认可用的指令集和寄存器范围 +（即默认使用的 <> 集合） + +|-mabi= +|`lp64d` `lp64f` `lp64s` `ilp32d` `ilp32f` `ilp32s` +|选择基础 ABI 类型 + +|-mtune= +|`native` `loongarch64` `la464` +|选择目标微架构：设定微架构相关的性能调优参数； +取值范围是 `-march` 选项的超集，默认值与 `-march` 值相同 +|=== + +.扩展选项 +[%header,cols="^1m,^2,^7"] +|=== +|选项 +|可用值 +|描述 + +|-mfpu= +|`64` `32` `none` (等同于 `0`) +|选择可用的基础浮点数指令和寄存器范围 + +|-msoft-float +| +|`-mfpu=none` 的别名 + +|-msingle-float +| +|`-mfpu=32` 的别名 + +|-mdouble-float +| +|`-mfpu=64` 的别名 +|=== + +=== 目标指令集架构 (ISA) 的构成 + +龙芯架构采用 *基础部分* 加 *扩展部分* 的组织形式， +在后续更新过程中，基础部分或扩展部分中的各功能子集都可以独立地演进， +并保证高版本总是二进制兼容低版本。 + +[[isa-modules]] +针对这一特点，编译器应当对目标 ISA 进行模块化抽象。 +约定 ISA 模块分为两类： *基础架构* 和 *ISA 扩展特性* 。 + +其中，*基础架构* 为目标 ISA 的核心部分，包含基础整数指令、基础浮点数指令等功能， +由 `-march` 选项的取值唯一确定。*ISA 扩展特性* 可能对应一种单独的指令集扩展， +也可能对应基础架构或指令集扩展的增量/演进部分，由扩展选项控制是否开启。 + +在确定目标 ISA 配置时，应以 *基础架构* 隐含的 ISA 模块为基础， +再根据选用 / 关闭 ISA 扩展的命令行选项进行调整，得出结果。 + +image::compiler-isa-config-model-CN.svg[] + +在以下列举的所有的 ISA 模块中，编译器必须至少实现一种基础架构。 + +.基础架构 +[%header,cols="^1,^3,^2"] +|=== +|名称 +|选择该基础架构的 `-march` 值 +|描述 + +|LA64 基础架构 v1.00 (`la64v100`) +|`loongarch64` `la464` +|由 https://loongson.github.io/LoongArch-Documentation/LoongArch-Vol1-CN.html[《龙芯架构参考手册 - 卷1 - 基础架构》] +v1.00 定义的指令集架构 +|=== + +下表列举了由编译器抽象的全体 ISA 扩展特性，以及选用/关闭这些特性的命令行选项。 + +.ISA 扩展特性 +[%header,cols="^1,^3,^2"] +|=== +|名称 +|编译器选项 +|描述 + +|基础浮点运算单元 (`fpu*`) +|`-mfpu=\*` (`*` 可能取值为 `none` `32` `64`) +|选择编译器可用的基础浮点数指令和浮点寄存器，属于基础架构的一部分， +默认值由基础架构决定。 +|=== + +下表列举了所有可同时作为 `-march` 和 `-mtune` 选项参数的目标 CPU 类型 +及其相关属性。 + +.目标 CPU +[%header,cols="^1,^3,^2"] +|=== +|名称 / 选项值 +|默认选择的 ISA 模块 +|性能调优目标 + +|`native` +|由 `cpucfg` 指令自动检测（仅适用于本地编译器） +|由 `cpucfg` 自动检测的处理器类型 + +|`loongarch64` +|`la64v100` [`fpu64`] +|通用 64 位龙芯架构 (LA64) 处理器 + +|`la464` +|`la64v100` [`fpu64`] +|LA464 处理器核 +|=== + +[[abi-types]] +=== 应用二进制接口 (ABI) 的构成 + +对于龙芯架构编译器，完整的 ABI 配置应包含两个部分： +*基础 ABI* 和 *ABI 扩展特性* 。前者描述了 ABI 中整型和浮点数据的表示、 +传参和返回方式，后者则代表对基础 ABI 进行的总体调整，可能需要特定 ISA 扩展支持。 + +需要注意的是，不同 ABI 扩展特性之间是 *互斥* 的，不能相互叠加； +具有不同扩展特性的 ABI 配置之间也 *互不兼容* 。 + +原则上本文档不会增加新的 ABI 扩展特性，除非它能提供 +其他编译器优化技术不能单独实现的功能或性能优势。 + +基础 ABI 共有六种，编译器可根据实现的目标架构范围，选择实现其中的一种或多种， +其标准名称和对应的 `-mabi` 选项值一致。 + +.基础 ABI 类型 +[%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 / （无） +|=== + +下表列举了全体 ABI 扩展特性类型及其相关命令行选项，除 `default` 必须实现之外， +编译器可选择实现或不实现其中任何一种。 + +.ABI 扩展特性类型 +[%header,cols="^1,^1,^1"] +|=== +|名称 +|编译器选项 +|含义 + +|`default` +|（无） +|符合 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 的约束导致实现它所需的指令集特性 +超出了编译选项对 ISA 配置的约束范围。此时编译器应报错退出。 + +当编译选项不能唯一确定目标架构时， +在选择默认值之前，编译器应根据下表，从命令行显式给出的 ABI 配置 +推断 *基础架构* 和 *ISA 扩展特性* 的默认配置， +但不违反已给出编译选项对目标架构的明确约束。 + +.目标架构和默认 ABI 类型对应关系 +[%header,cols="^1,^1,^1"] +|=== +|目标架构包含的 ISA 模块 +|基础 ABI +|ABI 扩展特性 + +|`la64v100` [`fpu64`] +|`lp64d` +|`default` + +|`la64v100` `fpu32` +|`lp64f` +|`default` + +|`la64v100` `fpunone` +|`lp64s` +|`default` +|=== + + +== GNU 目标三元组和 Multiarch 架构标识符 + +*GNU 目标三元组* (target triplet) 是 GNU 构建系统用于描述目标平台的字符串， +一般包含三个字段：处理器类型 (`machine`) ，系统厂商 (`vendor`)，操作系统 (`os`)。 + +*Multiarch 架构标识符* 是用于 multiarch 库安装路径的目录名称， +可以看作规范的 GNU 目标三元组，参见 https://wiki.debian.org/Multiarch/Tuples[Debian 文档] 。 + +对于龙芯架构的合法 GNU 目标三元组，约定 `machine` 字段的取值范围及其含义如下： + +[[machine-strings]] +.龙芯架构 `machine` 字符串 +[%header,cols="^1,^2"] +|=== +|`machine` 字符串 +|含义 + +|`loongarch64` +|LA64 基础架构，基础 ABI 为 `lp64*` + +|`loongarch32` +|LA32 基础架构，基础 ABI 为 `ilp32*` +|=== + +作为标准的库路径名称，龙芯架构的标准 multiarch 架构标识符至少应该反映 +发行到对应目录的二进制库 <>。 + +原则上，在编译以二进制形式发行的库时，应当采用 +<>， +因此 multiarch 架构标识符应与目标 ABI 配置一一对应。 +其中，关于整型 ABI 的部分由 `machine` 字段隐含， +基础 ABI 的浮点部分和 ABI 扩展特性则分别由连续附加在 multiarch 标识符 +`os` 字段后的两个字符串后缀 (``) 标记。 + +.龙芯架构 Mulitarch 架构标识符 +[%header,cols="^1,^2"] +|=== +|Multiarch 架构标识符 +|含义 + +|`-linux-gnu` +|GNU/Linux 系统，使用 GNU C Library (glibc) 作为标准 C 库，系统内核为 Linux +|=== + +.Multiarch `os` 字段，`` 后缀标记及其含义 +[%header,cols="^1,^2"] +|=== +|`` 字符串 |含义 +|`f64` |基础 ABI 使用 64 位浮点寄存器传参 (`lp64d` `ilp32d`) +|`f32` |基础 ABI 使用 32 位浮点寄存器传参 (`lp64f` `ilp32f`) +|`sfp` |基础 ABI 不使用浮点寄存器传参 (`lp64s` `ilp32s`) +|=== + +.Multiarch `os` 字段，`` 后缀标记及其对应的 ABI 扩展特性 +[%header,cols="^1,^2"] +|=== +|`` 字符串 |ABI 扩展特性 +|（空） |`default` +|=== + +.全体 Mulitarch 标识符列表 +[%header,cols="^1,^1,^1"] +|=== +|ABI 类型（基础 ABI / ABI 扩展特性） +|操作系统类型 +|Multiarch 架构标识符 + +|`lp64d` / `default` +|GNU/Linux +|`loongarch64-linux-gnuf64` + +|`lp64f` / `default` +|GNU/Linux +|`loongarch64-linux-gnuf32` + +|`lp64s` / `default` +|GNU/Linux +|`loongarch64-linux-gnusfp` + +|`ilp32d` / `default` +|GNU/Linux +|`loongarch32-linux-gnuf64` + +|`ilp32f` / `default` +|GNU/Linux +|`loongarch32-linux-gnuf32` + +|`ilp32s` / `default` +|GNU/Linux +|`loongarch32-linux-gnusfp` +|=== + + +== C/C++ 预处理器内建宏定义 + +.龙芯架构相关 C/C++ 预处理器内建宏 +[%header,cols="^1,^3,^3"] +|=== +|名称 +|值 +|描述 + +|`\\__loongarch__` +|（无） +|目标为龙芯架构 + +|`__loongarch_grlen` +|`64` `32` +|通用寄存器位宽 + +|`__loongarch_frlen` +|`0` `32` `64` +|浮点寄存器位宽（无 fpu 则为 `0` ） + +|`_LOONGARCH_ARCH` +|`"loongarch64"` `"la464"` +|相当于 `--with-arch` / `-march` 指定的目标 CPU 名称 + +|`_LOONGARCH_TUNE` +|`"loongarch64"` `"la464"` +|相当于 `-mtune` 指定的目标 CPU 名称 + +|`__loongarch_lp64` +|（无） +|ABI 使用 64 位通用寄存器传参，采用 `lp64` 数据模型 + +|`__loongarch_hard_float` +|（无） +|ABI 使用浮点寄存器传参 + +|`__loongarch_soft_float` +|（无） +|ABI 不使用浮点寄存器传参 + +|`__loongarch_single_float` +|（无） +|ABI 仅使用 32 位浮点寄存器传参 + +|`__loongarch_double_float` +|（无） +|ABI 使用 64 位浮点寄存器传参 + +|`_LOONGARCH_SZINT` +|（略） +|C/C++ `int` 类型位宽 + +|`_LOONGARCH_SZLONG` +|（略） +|C/C++ `long int` 类型位宽 + +|`_LOONGARCH_SZPTR` +|（略） +|C/C++ 指针类型位宽 +|=== diff --git a/docs/LoongArch-toolchain-conventions-EN.adoc b/docs/LoongArch-toolchain-conventions-EN.adoc new file mode 100644 index 0000000..3fbc491 --- /dev/null +++ b/docs/LoongArch-toolchain-conventions-EN.adoc @@ -0,0 +1,404 @@ += LoongArch Toolchain Conventions +Loongson Technology Corporation Limited +v1.00 +:docinfodir: ../themes +:docinfo: shared +:doctype: book +:toc: left + +__Note: In this document, the terms "architecture", "instruction set architecture" and "ISA" +are used synonymously and refer to a certain set of instructions and the set of registers +they can operate upon.__ + + +== Compiler Options + +=== Rationale + +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 +to be used by the compiler. + +2. *Target ABI type*: the data model and calling conventions. + +3. *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. +(include only `-march` `-mabi` and `-mtune`) + +2. *Extended options*: make incremental changes to the target configuration. + +.Basic Options +[%header,cols="^1m,^3,^6"] +|=== +|Option +|Possible values +|Description + +|-march= +|`native` `loongarch64` `la464` +|Selects the target architecture, i.e. +the basic set of <> to be enabled. + +|-mabi= +|`lp64d` `lp64f` `lp64s` `ilp32d` `ilp32f` `ilp32s` +|Selects the base ABI type. + +|-mtune= +|`native` `loongarch64` `la464` +|Selects the type of target microarchitecture, defaults to the value of `-march`. +The set of possible values should be a superset of `-march` values. +|=== + +.Extended Options +[%header,cols="^1m,^3,^6"] +|=== +|Option +|Possible values +|Description + +|-mfpu= +|`64` `32` `none` (equivalent to `0`) +|Selects the allowed set of basic floating-point instructions and registers. + +|-msoft-float +| +|Alias to `-mfpu=none` + +|-msingle-float +| +|Alias to `-mfpu=32` + +|-mdouble-float +| +|Alias to `-mfpu=64` +|=== + +=== Configuring Target ISA + +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. + +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__ +set of functionalities like integer and floating-point operations, and is decided +by the value of `-march`. An *ISA extension* may represent either the base of a certain +__extended__ ISA component or an incremental update to it, and is enabled / disabled by +extended options. + +For a complier, the final ISA configuration should be derived by applying various +ISA extension configurations from extended options to the base ISA, +which is selected via the `-march` option and consists of the base +architecture and the set of default ISA extensions. + +image::compiler-isa-config-model-EN.svg[] + +Among all ISA modules listed below, the compiler should at least implement +one base architecture. + +.Base Architecture +[%header,cols="^1,^3,^2"] +|=== +|Name +|`-march` values that selects this module +|Description + +|LA64 basic architecture v1.00 (`la64v100`) +|`loongarch64` `la464` +|ISA defined in https://loongson.github.io/LoongArch-Documentation/LoongArch-Vol1-CN.html[ +__LoongArch Reference Manual - Volume 1: Basic Architecture__] v1.00. +|=== + +The following table lists all ISA extensions that should be abstracted by the compiler +and the compiler options to enable / disable them. + +.ISA extensions +[%header,cols="^1,^3,^2"] +|=== +|Name +|Related compiler options +|Description + +|Basic Floating-Point Processing Unit (`fpu*`) +|`-mfpu=\*` (Possible values of `*`: `none` `32` `64`) +|Selects the allowed set of basic floating-point instructions +and floating-point registers. This is a constituent part of +the base architecture, where it gets its default value. +|=== + +The following table lists the properties of all target CPU models +that can serve as arguments to `-march` and `-mtune` options +at the same time. + +.Target CPU Models (`-march=` and `-mtune=`) +[%header,cols="^1,^3,^2"] +|=== +|Name / Value +|ISA modules that are enabled by default +|Target of optimization + +|`native` +|auto-detected with `cpucfg` (only on native and cross-native compilers) +|auto-detected microarchitecture model / features + +|`loongarch64` +|`la64v100` [`fpu64`] +|generic LoongArch LA64 processors + +|`la464` +|`la64v100` [`fpu64`] +|LA464 processor core +|=== + +[[abi-types]] +=== Configuring Target ABI + +Like configuring the target ISA, a complete ABI configuration of LoongArch +consists of two parts, the *base ABI* and the *ABI extension*. The former +describes the data model and calling convention in general, while the latter +denotes an overall adjustment to the base ABI, which may require support +from certain ISA extensions. + +Please be noted that there is only ONE ABI extension slot in an ABI +configuration. They do not combine with one another, +and are, in principle, mutually incompatible. + +A new ABI extension type will not be added to this document unless +it implies certain significant performance / functional advantage +that no compiler optimization techniques can provide without +altering the ABI. + +There are six base ABI types, whose standard names are the same as +the `-mabi` values that select them. The compiler may choose to implement +one or more of these base ABI types, possibly according to the range of +implemented target ISA variants. + +.Base ABI Types +[%header,cols="^1,^1,^1"] +|=== +|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) +|=== + +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`. + +.ABI Extension Types +[%header,cols="^1,^1,^1"] +|=== +|Name +|Compiler options +|Description + +|`default` +|(none) +|conforms to the https://loongson.github.io/LoongArch-Documentation/LoongArch-ELF-ABI-EN.html[LoongArch ELF psABI] +|=== + +[[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. + +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. + +.Default correspondence between target ISA and ABI types +[%header,cols="^1,^1,^1"] +|=== +|Enabled ISA modules +|Base ABI type +|ABI Extension type + +|`la64v100` [`fpu64`] +|`lp64d` +|`default` + +|`la64v100` `fpu32` +|`lp64f` +|`default` + +|`la64v100` `fpunone` +|`lp64s` +|`default` +|=== + +== GNU Target Triplets and Multiarch Specifiers + +*Target triplet* is a core concept in the GNU build system. +It describes a platform on which the code runs and mostly consists of three fields: +the CPU family / model (`machine`), the vendor (`vendor`), and the operating +system name (`os`). + +*Multiarch architecture apecifiers* are essentially standard directory names +where libraries are installed on a multiarch-flavored filesystem. +These strings are normalized GNU target triplets. See +https://wiki.debian.org/Multiarch/Tuples[debian documentation] for details. + +This document recognizes the following `machine` strings +for the GNU triplets of LoongArch: + +[[machine-strings]] +.LoongArch `machine` strings： +[%header,cols="^1,^2"] +|=== +|`machine` +|Description + +|`loongarch64` +|LA64 base architecture (implies `lp64*` ABI) + +|`loongarch32` +|LA32 base architecture (implies `ilp32*` ABI) +|=== + +As standard library directory names, the canonical multiarch architecture specifiers +of LoongArch should contain information about the ABI type of the libraries +that are meant to be released in the binary form and installed there. + +While the integer base ABI is <>, +the floating-point base ABI and the ABI extension type are encoded +with two string suffices (``) to the `os` field of the +specifier, respectively. + +.List of possible `` +[%header,cols="^1,^2"] +|=== +|`` |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`) +|=== + +.List of possible `` +[%header,cols="^1,^2"] +|=== +|`` |ABI extension type +|(empty string) |`default` +|=== + +__(Note: Since in principle, <> +should be used in this binary-release scenario, it is not necessary to reserve +multiple multiarch specifiers for one OS / ABI combination.)__ + +.List of LoongArch mulitarch specifiers +[%header,cols="^1,^1,^1"] +|=== +|ABI type (Base ABI / ABI extension) +|OS type +|Multiarch specifier + +|`lp64d` / `default` +|GNU/Linux +|`loongarch64-linux-gnuf64` + +|`lp64f` / `default` +|GNU/Linux +|`loongarch64-linux-gnuf32` + +|`lp64s` / `default` +|GNU/Linux +|`loongarch64-linux-gnusfp` + +|`ilp32d` / `default` +|GNU/Linux +|`loongarch32-linux-gnuf64` + +|`ilp32f` / `default` +|GNU/Linux +|`loongarch32-linux-gnuf32` + +|`ilp32s` / `default` +|GNU/Linux +|`loongarch32-linux-gnusfp` +|=== + +== C/C++ Preprocessor Definitions + +.LoongArch-specific C/C++ Built-in Macros： +[%header,cols="^1,^3,^3"] +|=== +|Name +|Possible Values +|Description + +|`\\__loongarch__` +|(none) +|Defined if the target is LoongArch. + +|`__loongarch_grlen` +|`64` +|Bit-width of general purpose registers. + +|`__loongarch_frlen` +|`0` `32` `64` +|Bit-width of floating-point registers (`0` if there is no FPU). + +|`_LOONGARCH_ARCH` +|`"loongarch64"` `"la464"` +|Processor model as specified by `--with-arch` / `-march`. + +|`_LOONGARCH_TUNE` +|`"loongarch64"` `"la464"` +|Processor model as specified by `-mtune`. + +|`__loongarch_lp64` +|(none) +|Defined if integer ABI type is `lp64`. + +|`__loongarch_hard_float` +|(none) +|Defined if floating-point/extended ABI type is `single` or `double`. + +|`__loongarch_soft_float` +|(none) +|Defined if floating-point/extended ABI type is `soft`. + +|`__loongarch_single_float` +|(none) +|Defined if floating-point/extended ABI type is `single`. + +|`__loongarch_double_float` +|(none) +|Defined if floating-point/extended ABI type is `double`. + +|`_LOONGARCH_SZINT` +|(omitted) +|Bit-width of C/C++ `int` type. + +|`_LOONGARCH_SZLONG` +|(omitted) +|Bit-width of C/C++ `long int` type. + +|`_LOONGARCH_SZPTR` +|(omitted) +|Bit-width of C/C++ pointer types. +|=== diff --git a/docs/README-CN.adoc b/docs/README-CN.adoc index 373b46e..524933b 100644 --- a/docs/README-CN.adoc +++ b/docs/README-CN.adoc @@ -35,10 +35,14 @@ * 龙芯 7A1000 桥片用户手册：该手册介绍了桥片总体架构、时钟结构、地址空间、配置寄存器以及各个功能接口，主要供 BIOS 和内核开发人员使用。 ** https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-7A1000-usermanual-v2.00-CN.pdf[原始文档] 。 -* LoongArch ELF ABI：该手册介绍了 LoongArch ELF ABI。 +* 龙芯架构 ELF psABI：该手册介绍了龙芯架构 ELF psABI。 ** link:LoongArch-ELF-ABI-CN.html[HTML 版本]。 ** link:LoongArch-ELF-ABI-CN.pdf[PDF 版本]。 +* 龙芯架构工具链约定：该手册介绍了龙芯架构工具链的命令行界面和操作系统相关惯例。 +** link:LoongArch-toolchain-conventions-CN.html[HTML 版本]。 +** link:LoongArch-toolchain-conventions-CN.pdf[PDF 版本]。 + [[getting-start]] == 开始 diff --git a/docs/README-EN.adoc b/docs/README-EN.adoc index 7a7e351..0fde813 100644 --- a/docs/README-EN.adoc +++ b/docs/README-EN.adoc @@ -43,10 +43,14 @@ To make it easier to download, each HTML page contains embedded CSS and images. ** link:Loongson-7A1000-usermanual-EN.pdf[PDF version]. ** https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-7A1000-usermanual-v2.00-CN.pdf[Original document]. -* LoongArch ELF ABI: This manual describes the LoongArch ELF ABI. +* LoongArch ELF psABI: This manual describes the LoongArch ELF psABI. ** link:LoongArch-ELF-ABI-EN.html[HTML version]. ** link:LoongArch-ELF-ABI-EN.pdf[PDF version]. +* LoongArch toolchain conventions: This document describes the command-line interface and relevant OS conventions of LoongArch toolchains. +** link:LoongArch-toolchain-conventions-EN.html[HTML version]. +** link:LoongArch-toolchain-conventions-EN.pdf[PDF version]. + == Translator`'s Note Due to the limited knowledge of the translators, there are some inevitable errors and omissions existing in this document, please feel free to correct. diff --git a/images/compiler-isa-config-model-CN.svg b/images/compiler-isa-config-model-CN.svg new file mode 100644 index 0000000..8e2d84c --- /dev/null +++ b/images/compiler-isa-config-model-CN.svg @@ -0,0 +1,840 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + LA32 Lite + LA32 + + + + LA64 + + 指令集增量更新部分 + + + + + + + FPU64 + + + 版本 1.00 + + 版本 ? + + + + 基础架构 + + 更新 + 指令集扩展 + + + + + LSX + LASX + + SIMD 版本 1.00 + + + FPU32 + + + + + + SIMD 扩展 + + + -march=la464 + -mfpu=none + + + -mfpu=32 + + 由 -march=* 选择的初始 ISA 模块范围（包括基础架构和 ISA 扩展） + 扩展选项（如 -mfpu=*）对目标 ISA 的增量调整 + + + + + * 编译器不需要特别区分 ISA 扩展和增量更新。然而，对于后续加入的 ISA 扩展选项，它们表达的“增量调整”语义可能仅在上述两个增长维度之一上体现。 + + + diff --git a/images/compiler-isa-config-model-EN.svg b/images/compiler-isa-config-model-EN.svg new file mode 100644 index 0000000..1f19ca4 --- /dev/null +++ b/images/compiler-isa-config-model-EN.svg @@ -0,0 +1,836 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + LA32 Lite + LA32 + + + + LA64 + + Possible Incremental ISA updates + + + + + + + FPU64 + + + Ver 1.00 + + Ver ? + + + + Base Architecture + + Updates + Instruction Set Extensions + + + + + LSX + LASX + + SIMD Ver 1.00 + + + FPU32 + + + + + + SIMD Extension + + + -march=la464 + -mfpu=none + + + -mfpu=32 + + Range of ISA modules (base and extensions) initially enabled by -march=* + Incremental changes to the target ISA made by extended options, such as -mfpu=* + + + + + * In this configuration model, there is no essentialdifference between new ISA extensions and incrementalupdates to existing ISA components. However, newextended options that alters the range of enable ISAmodules may be added in future updates, and theirsemantics may be specific to one of these two dimensions. + + +