Skip to content

Commit

Permalink
Update description of FP-related compiler options.
Browse files Browse the repository at this point in the history
  • Loading branch information
scylaac authored and FreeFlyingSheep committed Mar 17, 2022
1 parent a2ffe1e commit 57bb244
Show file tree
Hide file tree
Showing 2 changed files with 48 additions and 17 deletions.
29 changes: 21 additions & 8 deletions docs/LoongArch-toolchain-conventions-CN.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -63,23 +63,35 @@ __注:在本文档中,"架构"、"指令集架构"、"ISA" 均表示某一
|可用值
|描述

|-mfpu=
|`64` `32` `none` (等同于 `0`)
|选择可用的基础浮点数指令和寄存器范围

|-msoft-float
|
|`-mfpu=none` 的别名
|禁止使用浮点数指令,
并对当前选择的基础 ABI 进行调整,以采用软浮点调用惯例。
(调整后的基础 ABI 名称后缀为 `s`)

|-msingle-float
|
|`-mfpu=32` 的别名
|允许使用 32 位浮点数指令,
并对当前选择的基础 ABI 进行调整,以采用 32 位浮点调用惯例。
(调整后的基础 ABI 名称后缀为 `f`)

|-mdouble-float
|
|`-mfpu=64` 的别名
|允许使用 32 位和 64 位浮点数指令,
并对当前选择的基础 ABI 进行调整,以采用 64 位浮点调用惯例。
(调整后的基础 ABI 名称后缀为 `d`)

|-mfpu=
|`64` `32` `0` `none` (等同于 `0`)
|(可选实现) 选择可用的基础浮点数指令和寄存器范围,非<<abi-fallback,必要>>不调整浮点调用惯例。
(在软件项目或脚本中,建议直接使用 `-m*-float'。)
|===

在一条编译命令中,各龙芯架构相关选项的总体配置效果等同于它们按先后顺序依次生效的结果。
唯一的例外是 `-m*-float` :它们对浮点指令集和调用惯例的配置不会被除 `-m*-float` 之外
其他类型的后续选项改变。


=== 目标指令集架构 (ISA) 的构成

龙芯架构采用 *基础部分* 加 *扩展部分* 的组织形式,
Expand Down Expand Up @@ -212,9 +224,10 @@ v1.00 定义的指令集架构
编译器的实际行为 *不确定* ,因为在缩减默认可用指令集范围的同时,
用户应该通过命令行选项明确表示使用何种 ABI 。

[[abi-fallback]]
对于编译器实现来说,此时推荐的行为是报错退出,但出于易用性的考量,
也可以在默认配置允许的范围内谨慎地选择一种当前可用指令集能够实现的
"降级"。对于这种情况,建议编译器输出提示或警告信息以通知用户。
备选 ABI。对于这种情况,建议编译器输出提示或警告信息以通知用户。
例如,对于默认 ABI 为 `lp64d` / `base` 的编译器,
若编译选项为 `-mfpu=none` ,则可能自动调整 ABI 到 `lp64s` / `base` 。

Expand Down
36 changes: 27 additions & 9 deletions docs/LoongArch-toolchain-conventions-EN.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -70,23 +70,40 @@ of ISA modules.
|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`
|Prevent the compiler from generating hardware floating-point instructions,
and adjust the selected base ABI type to use soft-float calling convention.
(The adjusted base ABI identifier should have suffix `s`.)

|-msingle-float
|
|Alias to `-mfpu=32`
|Allow generating 32-bit floating-point instructions,
and adjust the selected base ABI type to use 32-bit FP calling convention.
(The adjusted base ABI identifier should have suffix `f`.)

|-mdouble-float
|
|Alias to `-mfpu=64`
|Allow generating 32- and 64-bit floating-point instructions.
and adjust the selected base ABI type to use 64-bit FP calling convention.
(The adjusted base ABI identifier should have suffix `d`.)

|-mfpu=
|`64` `32` `0` `none` (equivalent to `0`)
|Selects the allowed set of basic floating-point instructions and registers.
This option should not change the FP calling convention unless it's <<abi-fallback,necessary>>.
(The implementation of this option is not mandatory. It is recommended to use
`-m*-float` options in software projects and scripts.)
|===

As a general rule, the effect of all LoongArch-specific compiler options
that are given for one compiler invocation should be as if they are
processed in the order they appear on the command line.
The only exception to this rule is `-m*-float`: their configuration of
floating-point instruction set and calling convention will not be changed
by subsequent options other than `-m*-float`.


=== Configuring Target ISA

The LoongArch ISA is organized in a "base-extension" manner.
Expand Down Expand Up @@ -239,10 +256,11 @@ 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.

[[abi-fallback]]
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.
to ignore the default base ABI or ABI extension and select a viable
fallback 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
Expand Down

0 comments on commit 57bb244

Please sign in to comment.