diff --git a/docs/LoongArch-toolchain-conventions-CN.adoc b/docs/LoongArch-toolchain-conventions-CN.adoc new file mode 100644 index 0000000..0a2c243 --- /dev/null +++ b/docs/LoongArch-toolchain-conventions-CN.adoc @@ -0,0 +1,161 @@ += 龙芯架构编译器约定 +龙芯中科技术股份有限公司 +v1.00 +:docinfodir: ../themes +:docinfo: shared +:doctype: book +:toc: left +:toc-title: 目录 +:scripts: cjk + +== 编译器命令行选项界面 + +以下编译器选项的最终效应包括: + +1. 配置使用的 ABI 类型 + +2. 配置使用的 ISA 扩展 + +3. 配置处理器型号相关的调优参数 + +.编译器选项列表: +[%header,cols="^1m,^2,^7"] +|=== +|选项 +|可用值 +|描述 + +|-march= +|`native` `loongarch64` `la464` +|选择目标 CPU (隐含默认 ABI 类型、ISA 扩展和调优参数) + +|-mtune= +|`native` `loongarch64` `la464` +|选择目标 CPU 的性能调优参数 + +|-mabi= +|`lp64` `ilp32` +|选择整型 ABI 类型 + +|-mfloat-abi= +|`double` `single` `soft` +|选择浮点 / 扩展 ABI 类型 + +|-mfpu= +|`double` `single` `none` +|选择编译器可用的浮点 / 扩展指令集 + +|-msoft-float +|`--` +|`-mfloat-abi=soft -mfpu=none` 的简写 + +|-msingle-float +|`--` +|`-mfloat-abi=single -mfpu=single` 的简写 + +|-mdouble-float +|`--` +|`-mfloat-abi=double -mfpu=double` 的简写 +|=== + + +== GNU 目标三元组和 Multiarch 架构标识符 + +GNU 目标三元组是 GNU 构建系统用于描述目标平台的字符串, +一般包含三个字段:处理器类型 (`machine`) ,系统厂商 (`vendor`),操作系统 (`os`)。 + +.龙芯架构 `machine` 字符串列表: +[%header,cols="^1,^2"] +|=== +|`machine` 字符串 +|含义 + +|`loongarch64` +|默认使用 la64 指令集,双精度浮点单元,ABI 类型 `lp64/double` + +|`loongarch64nf` +|默认使用 la64 指令集,无硬件浮点单元,ABI 类型 `lp64/soft` + +|`loongarch64sf` +|默认使用 la64 指令集,单精度浮点单元,ABI 类型 `lp64/single` +|=== + +Multiarch 架构标识符是用于 multiarch 库安装路径的目录名称, +可以看作规范的 GNU 目标三元组,参见 https://wiki.debian.org/Multiarch/Tuples[Debian 文档] 。 + +.龙芯架构 Mulitarch 架构标识符列表: +[%header,cols="^1,^2"] +|=== +|Multiarch 架构标识符 +|含义 + +|`-linux-gnu` +|GNU/Linux 系统,使用 GNU C Library (glibc) 作为标准 C 库,系统内核为 Linux +|=== + + +== C/C++ 预处理器内建宏定义 + +.龙芯架构相关 C/C++ 预处理器内建宏列表: +[%header,cols="^1,^3,^3"] +|=== +|名称 +|值 +|描述 + +|`\\__loongarch__` +|(无) +|目标为龙芯架构 + +|`__loongarch_gpr` +|`64` +|通用寄存器位宽 + +|`__loongarch_fpr` +|`0` `32` `64` +|浮点寄存器位宽(无 fpu 则为 `0` ) + +|`_LOONGARCH_ARCH` +|`"loongarch64"` `"la464"` +|相当于 `--with-arch` / `-march` 指定的处理器型号 + +|`_LOONGARCH_TUNE` +|`loongarch64` `la464` +|相当于 `-mtune` 指定的处理器型号 + +|`__loongarch_lp64` +|(无) +|整型 ABI 类型为 `lp64` + +|`__loongarch_hard_float` +|(无) +|浮点/扩展 ABI 类型为 `single` 或 `double` + +|`__loongarch_soft_float` +|(无) +|浮点/扩展 ABI 类型为 `soft` + +|`__loongarch_single_float` +|(无) +|浮点/扩展 ABI 类型为 `single` + +|`__loongarch_double_float` +|(无) +|浮点/扩展 ABI 类型为 `double` + +|`_LOONGARCH_SZINT` +|(略) +|C/C++ `int` 类型位宽 + +|`_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..a1bcf24 --- /dev/null +++ b/docs/LoongArch-toolchain-conventions-EN.adoc @@ -0,0 +1,160 @@ += LoongArch ELF ABI specification +Loongson Technology Corporation Limited +v1.00 +:docinfodir: ../themes +:docinfo: shared +:doctype: book +:toc: left + +== Compiler Options + +The command-line options listed below should denote a change +in the following compiler settings: + +1. ABI type of compiled subroutines + +2. Available ISA extensions + +3. Processor-model-specific tuning parameters + +.Compiler Options: +[%header,cols="^1m,^2,^7"] +|=== +|Option +|Possible Values +|Description + +|-march= +|`native` `loongarch64` `la464` +|Target CPU model (implies default ABI type, ISA extension and tuning parameters) + +|-mtune= +|`native` `loongarch64` `la464` +|Target CPU model (tuning parameters) + +|-mabi= +|`lp64` `ilp32` +|Integer ABI type + +|-mfloat-abi= +|`double` `single` `soft` +|Floating-point / extended ABI type + +|-mfpu= +|`double` `single` `none` +|Floating-point ISA / SIMD extensions + +|-msoft-float +|`--` +|alias for `-mfloat-abi=soft -mfpu=none` + +|-msingle-float +|`--` +|alias for `-mfloat-abi=single -mfpu=single` + +|-mdouble-float +|`--` +|alias for `-mfloat-abi=double -mfpu=double` +|=== + + +== 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, primarily with three fields: +the CPU family/model (`machine`), the vendor (`vendor`), and the operating +system name (`os`)。 + +.List of LoongArch `machine` strings: +[%header,cols="^1,^2"] +|=== +|`machine` +|Description + +|`loongarch64` +|Processors that support la64 ISA and 64-bit FPU. (ABI: `lp64/double`) + +|`loongarch64nf` +|Processors that support la64 ISA without FPU. (ABI: `lp64/soft`) + +|`loongarch64sf` +|Processors that support la64 ISA and 32-bit FPU. (ABI: `lp64/single`) +|=== + +Multiarch Architecture Specifiers 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. + +.LoongArch Mulitarch Architecture Specifiers: +[%header,cols="^1,^2"] +|=== +|Multiarch Specifier +|Description + +|`-linux-gnu` +|GNU/Linux on LoongArch (with Glibc as standard C library and Linux as OS kernel) +|=== + + +== 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_gpr` +|`64` +|Bit-width of general purpose registers. + +|`__loongarch_fpr` +|`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. +|===