[PATCH 0/2] LoongArch syscall ABI documentation

[PATCH 0/2] LoongArch syscall ABI documentation

[WANG Xuerui]

From: WANG Xuerui <git@xen0n.name>

Hi,

Due to popular demand [1] (even Loongson employees can get lost), the
current LoongArch syscall ABI is now documented. A Simplified Chinese
translation is included too.

[1]: https://github.com/loongson/LoongArch-Documentation/issues/66

WANG Xuerui (2):
  Documentation: LoongArch: Document the syscall ABI
  docs/zh_CN: LoongArch: Translate the syscall ABI doc

 Documentation/loongarch/index.rst             |  1 +
 Documentation/loongarch/syscall-abi.rst       | 36 ++++++++++++++++++
 .../translations/zh_CN/loongarch/index.rst    |  1 +
 .../zh_CN/loongarch/syscall-abi.rst           | 37 +++++++++++++++++++
 4 files changed, 75 insertions(+)
 create mode 100644 Documentation/loongarch/syscall-abi.rst
 create mode 100644 Documentation/translations/zh_CN/loongarch/syscall-abi.rst

-- 
2.38.0

[PATCH 1/2] Documentation: LoongArch: Document the syscall ABI

[WANG Xuerui]

From: WANG Xuerui <git@xen0n.name>

Signed-off-by: WANG Xuerui <git@xen0n.name>
Cc: Huacai Chen <chenhuacai@kernel.org>
Cc: Alex Shi <alexs@kernel.org>
Cc: Yanteng Si <siyanteng@loongson.cn>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: loongarch@lists.linux.dev
---
 Documentation/loongarch/index.rst       |  1 +
 Documentation/loongarch/syscall-abi.rst | 36 +++++++++++++++++++++++++
 2 files changed, 37 insertions(+)
 create mode 100644 Documentation/loongarch/syscall-abi.rst

diff --git a/Documentation/loongarch/index.rst b/Documentation/loongarch/index.rst
index aaba648db907..5dacd7143d2f 100644
--- a/Documentation/loongarch/index.rst
+++ b/Documentation/loongarch/index.rst
@@ -10,6 +10,7 @@ LoongArch Architecture
 
    introduction
    irq-chip-model
+   syscall-abi
 
    features
 
diff --git a/Documentation/loongarch/syscall-abi.rst b/Documentation/loongarch/syscall-abi.rst
new file mode 100644
index 000000000000..6f63aa3cfc64
--- /dev/null
+++ b/Documentation/loongarch/syscall-abi.rst
@@ -0,0 +1,36 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============================
+Linux/LoongArch system call ABI
+===============================
+
+This document describes the system call ABI of Linux/LoongArch.
+As the kernel is 64-bit only for now, the description below assumes an LP64\*
+calling convention.
+
+Syscall numbers and parameters
+==============================
+
+Like with other recent architecture ports, for the most part Linux/LoongArch
+reuses the asm-generic syscall numbers and parameters.
+There are a few points worth mentioning though.
+
+* There is no ``renameat``. Use ``renameat2`` instead.
+* There is no ``getrlimit`` or ``setrlimit``. Use ``prlimit64`` instead.
+* There is no ``fstat`` or ``newfstatat``. Only ``statx`` is provided, and
+  low-level components making their own syscalls are expected to be aware of
+  this (and provide their own shims if necessary).
+
+Invocation
+==========
+
+System calls are currently made with the ``syscall 0`` instruction.
+Although the immediate field in the instruction is not checked at present,
+it is strongly advised to keep it zeroed in case it is to be made meaningful
+in the future.
+
+The system call number is placed in the register ``a7``.
+Parameters, if present, are placed from ``a0`` through ``a6`` as needed,
+as if calling a function with the respective arguments.
+Upon return, ``a0`` contains the return value, and ``t0-t8`` should be
+considered clobbered; all other registers are preserved.
-- 
2.38.0

Re: [PATCH 1/2] Documentation: LoongArch: Document the syscall ABI

[Xi Ruoyao]

On Tue, 2022-10-18 at 18:04 +0800, WANG Xuerui wrote:

/* snip */


> +The system call number is placed in the register ``a7``.
> +Parameters, if present, are placed from ``a0`` through ``a6`` as needed,
> +as if calling a function with the respective arguments.
> +Upon return, ``a0`` contains the return value, and ``t0-t8`` should be
> +considered clobbered; all other registers are preserved.

Hmm, are a1-a7 guaranteed to be preserved?

-- 
Xi Ruoyao <xry111@xry111.site>
School of Aerospace Science and Technology, Xidian University

Re: [PATCH 1/2] Documentation: LoongArch: Document the syscall ABI

[Qi Hu]

On 2022/10/18 18:12, Xi Ruoyao wrote:
> On Tue, 2022-10-18 at 18:04 +0800, WANG Xuerui wrote:
>
> /* snip */
>
>
>> +The system call number is placed in the register ``a7``.
>> +Parameters, if present, are placed from ``a0`` through ``a6`` as needed,
>> +as if calling a function with the respective arguments.
>> +Upon return, ``a0`` contains the return value, and ``t0-t8`` should be
>> +considered clobbered; all other registers are preserved.
> Hmm, are a1-a7 guaranteed to be preserved?
>
Yes, you can find the relevant code here: [1] [2].

Thanks.


[1]: 
https://github.com/torvalds/linux/blob/master/arch/loongarch/kernel/entry.S#L43-L50

[2]: 
https://github.com/torvalds/linux/blob/master/arch/loongarch/kernel/entry.S#L68

Re: [PATCH 1/2] Documentation: LoongArch: Document the syscall ABI

[Huacai Chen]

On Tue, Oct 18, 2022 at 6:05 PM WANG Xuerui <kernel@xen0n.name> wrote:
>
> From: WANG Xuerui <git@xen0n.name>
>
> Signed-off-by: WANG Xuerui <git@xen0n.name>
> Cc: Huacai Chen <chenhuacai@kernel.org>
> Cc: Alex Shi <alexs@kernel.org>
> Cc: Yanteng Si <siyanteng@loongson.cn>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: loongarch@lists.linux.dev
> ---
>  Documentation/loongarch/index.rst       |  1 +
>  Documentation/loongarch/syscall-abi.rst | 36 +++++++++++++++++++++++++
>  2 files changed, 37 insertions(+)
>  create mode 100644 Documentation/loongarch/syscall-abi.rst
>
> diff --git a/Documentation/loongarch/index.rst b/Documentation/loongarch/index.rst
> index aaba648db907..5dacd7143d2f 100644
> --- a/Documentation/loongarch/index.rst
> +++ b/Documentation/loongarch/index.rst
> @@ -10,6 +10,7 @@ LoongArch Architecture
>
>     introduction
>     irq-chip-model
> +   syscall-abi
>
>     features
>
> diff --git a/Documentation/loongarch/syscall-abi.rst b/Documentation/loongarch/syscall-abi.rst
> new file mode 100644
> index 000000000000..6f63aa3cfc64
> --- /dev/null
> +++ b/Documentation/loongarch/syscall-abi.rst
> @@ -0,0 +1,36 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===============================
> +Linux/LoongArch system call ABI
> +===============================
> +
> +This document describes the system call ABI of Linux/LoongArch.
> +As the kernel is 64-bit only for now, the description below assumes an LP64\*
> +calling convention.
> +
> +Syscall numbers and parameters
> +==============================
> +
> +Like with other recent architecture ports, for the most part Linux/LoongArch
> +reuses the asm-generic syscall numbers and parameters.
> +There are a few points worth mentioning though.
> +
> +* There is no ``renameat``. Use ``renameat2`` instead.
> +* There is no ``getrlimit`` or ``setrlimit``. Use ``prlimit64`` instead.
> +* There is no ``fstat`` or ``newfstatat``. Only ``statx`` is provided, and
You may need list more syscalls:
Controlled by __ARCH_WANT_OLD_STAT:
sys_stat()/sys_lstat()/sys_fstat()/sys_fstatat()
Controlled by __ARCH_WANT_NEW_STAT:
sys_newstat()/sys_newlstat()/sys_newfstat()/sys_newfstatat()
Controlled by __ARCH_WANT_STAT64:
sys_stat64()/sys_lstat64()/sys_fstat64()/sys_fstatat64()

Huacai

> +  low-level components making their own syscalls are expected to be aware of
> +  this (and provide their own shims if necessary).
> +
> +Invocation
> +==========
> +
> +System calls are currently made with the ``syscall 0`` instruction.
> +Although the immediate field in the instruction is not checked at present,
> +it is strongly advised to keep it zeroed in case it is to be made meaningful
> +in the future.
> +
> +The system call number is placed in the register ``a7``.
> +Parameters, if present, are placed from ``a0`` through ``a6`` as needed,
> +as if calling a function with the respective arguments.
> +Upon return, ``a0`` contains the return value, and ``t0-t8`` should be
> +considered clobbered; all other registers are preserved.
> --
> 2.38.0
>

Re: [PATCH 1/2] Documentation: LoongArch: Document the syscall ABI

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 4717 bytes --]

On Tue, Oct 18, 2022 at 06:04:56PM +0800, WANG Xuerui wrote:
> From: WANG Xuerui <git@xen0n.name>
> 

What description?

> diff --git a/Documentation/loongarch/syscall-abi.rst b/Documentation/loongarch/syscall-abi.rst
> new file mode 100644
> index 000000000000..6f63aa3cfc64
> --- /dev/null
> +++ b/Documentation/loongarch/syscall-abi.rst
> @@ -0,0 +1,36 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===============================
> +Linux/LoongArch system call ABI
> +===============================
> +
> +This document describes the system call ABI of Linux/LoongArch.
> +As the kernel is 64-bit only for now, the description below assumes an LP64\*
> +calling convention.
> +
> +Syscall numbers and parameters
> +==============================
> +
> +Like with other recent architecture ports, for the most part Linux/LoongArch
> +reuses the asm-generic syscall numbers and parameters.
> +There are a few points worth mentioning though.
> +
> +* There is no ``renameat``. Use ``renameat2`` instead.
> +* There is no ``getrlimit`` or ``setrlimit``. Use ``prlimit64`` instead.
> +* There is no ``fstat`` or ``newfstatat``. Only ``statx`` is provided, and
> +  low-level components making their own syscalls are expected to be aware of
> +  this (and provide their own shims if necessary).
> +
> +Invocation
> +==========
> +
> +System calls are currently made with the ``syscall 0`` instruction.
> +Although the immediate field in the instruction is not checked at present,
> +it is strongly advised to keep it zeroed in case it is to be made meaningful
> +in the future.
> +
> +The system call number is placed in the register ``a7``.
> +Parameters, if present, are placed from ``a0`` through ``a6`` as needed,
> +as if calling a function with the respective arguments.
> +Upon return, ``a0`` contains the return value, and ``t0-t8`` should be
> +considered clobbered; all other registers are preserved.

The wording can be improved:

---- >8 ----

diff --git a/Documentation/loongarch/syscall-abi.rst b/Documentation/loongarch/syscall-abi.rst
index 6f63aa3cfc64e5..d05fa2e0211bbf 100644
--- a/Documentation/loongarch/syscall-abi.rst
+++ b/Documentation/loongarch/syscall-abi.rst
@@ -5,32 +5,32 @@ Linux/LoongArch system call ABI
 ===============================
 
 This document describes the system call ABI of Linux/LoongArch.
-As the kernel is 64-bit only for now, the description below assumes an LP64\*
-calling convention.
+As the kernel currently only supports 64-bit LoongArch architecture, the
+description below assumes LP64\* calling convention.
 
 Syscall numbers and parameters
 ==============================
 
-Like with other recent architecture ports, for the most part Linux/LoongArch
+Like ther recent architecture ports, for the most part Linux/LoongArch
 reuses the asm-generic syscall numbers and parameters.
-There are a few points worth mentioning though.
+There are a few limitations worth mentioning though.
 
 * There is no ``renameat``. Use ``renameat2`` instead.
 * There is no ``getrlimit`` or ``setrlimit``. Use ``prlimit64`` instead.
-* There is no ``fstat`` or ``newfstatat``. Only ``statx`` is provided, and
-  low-level components making their own syscalls are expected to be aware of
-  this (and provide their own shims if necessary).
+* There is no ``fstat`` or ``newfstatat``. Only ``statx`` is provided and
+  low-level components invoking their own syscalls are expected to be aware
+  of this (and provide their own shims if necessary).
 
 Invocation
 ==========
 
-System calls are currently made with the ``syscall 0`` instruction.
+System calls are currently invoked with the ``syscall 0`` instruction.
 Although the immediate field in the instruction is not checked at present,
-it is strongly advised to keep it zeroed in case it is to be made meaningful
+it is strongly advised to keep it zeroed in case the field has purposes
 in the future.
 
-The system call number is placed in the register ``a7``.
-Parameters, if present, are placed from ``a0`` through ``a6`` as needed,
-as if calling a function with the respective arguments.
-Upon return, ``a0`` contains the return value, and ``t0-t8`` should be
-considered clobbered; all other registers are preserved.
+The system call number is placed in the register ``a7``. Parameters, if
+present, are placed from ``a0`` through ``a6`` as needed, as if calling
+a function with respective arguments. Upon return, the return value is placed
+in ``a0`` and ``t0-t8`` should be considered clobbered; all other registers
+are preserved.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

[PATCH 2/2] docs/zh_CN: LoongArch: Translate the syscall ABI doc

[WANG Xuerui]

From: WANG Xuerui <git@xen0n.name>

Signed-off-by: WANG Xuerui <git@xen0n.name>
Cc: Huacai Chen <chenhuacai@kernel.org>
Cc: Alex Shi <alexs@kernel.org>
Cc: Yanteng Si <siyanteng@loongson.cn>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: loongarch@lists.linux.dev
---
 .../translations/zh_CN/loongarch/index.rst    |  1 +
 .../zh_CN/loongarch/syscall-abi.rst           | 37 +++++++++++++++++++
 2 files changed, 38 insertions(+)
 create mode 100644 Documentation/translations/zh_CN/loongarch/syscall-abi.rst

diff --git a/Documentation/translations/zh_CN/loongarch/index.rst b/Documentation/translations/zh_CN/loongarch/index.rst
index 7d23eb78379d..6edcc382492f 100644
--- a/Documentation/translations/zh_CN/loongarch/index.rst
+++ b/Documentation/translations/zh_CN/loongarch/index.rst
@@ -15,6 +15,7 @@ LoongArch体系结构
 
    introduction
    irq-chip-model
+   syscall-abi
 
    features
 
diff --git a/Documentation/translations/zh_CN/loongarch/syscall-abi.rst b/Documentation/translations/zh_CN/loongarch/syscall-abi.rst
new file mode 100644
index 000000000000..9089c9f6e9c1
--- /dev/null
+++ b/Documentation/translations/zh_CN/loongarch/syscall-abi.rst
@@ -0,0 +1,37 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/loongarch/syscall-abi.rst
+:Translator: WANG Xuerui <kernel@xen0n.name>
+
+============================
+Linux/LoongArch 系统调用 ABI
+============================
+
+本文档描述了 Linux/LoongArch 的系统调用 ABI。
+由于当前内核仅有 64 位版本，以下的描述均视为遵循 LP64\* 的过程调用约定。
+
+系统调用号与参数
+================
+
+正如其他新近的架构移植，绝大部分 Linux/LoongArch 系统调用号和参数都复用
+asm-generic 的定义。
+倒是有些值得一提的点。
+
+* 没有 ``renameat`` ，请使用 ``renameat2`` 。
+* 没有 ``getrlimit`` 或者 ``setrlimit`` ，请使用 ``prlimit64`` 。
+* 没有 ``fstat`` 或者 ``newfstatat`` ，只有 ``statx`` 。
+  自己进行系统调用的底层组件应当感知这一事实，如有必要，应自带兼容逻辑。
+
+调用方式
+========
+
+目前都通过 ``syscall 0`` 指令进行系统调用。
+尽管当下内核并不检查指令字中的立即数域，我们仍然强烈建议保持其为零，
+这是为了防止未来它被赋予其他语义而造成您的程序产生非预期结果。
+
+系统调用号应被存放于寄存器 ``a7`` 。
+如系统调用有参数，这些参数应如函数调用一般，从 ``a0`` 到 ``a6`` 按顺序存放。
+系统调用返回时， ``a0`` 存放返回值， ``t0-t8`` 则应被视作被破坏（clobbered）；
+其他寄存器的值都保持不变。
-- 
2.38.0

Re: [PATCH 0/2] LoongArch syscall ABI documentation

[Jonathan Corbet]

WANG Xuerui <kernel@xen0n.name> writes:

> From: WANG Xuerui <git@xen0n.name>
>
> Hi,
>
> Due to popular demand [1] (even Loongson employees can get lost), the
> current LoongArch syscall ABI is now documented. A Simplified Chinese
> translation is included too.
>
> [1]: https://github.com/loongson/LoongArch-Documentation/issues/66
>
> WANG Xuerui (2):
>   Documentation: LoongArch: Document the syscall ABI
>   docs/zh_CN: LoongArch: Translate the syscall ABI doc
>
>  Documentation/loongarch/index.rst             |  1 +
>  Documentation/loongarch/syscall-abi.rst       | 36 ++++++++++++++++++
>  .../translations/zh_CN/loongarch/index.rst    |  1 +
>  .../zh_CN/loongarch/syscall-abi.rst           | 37 +++++++++++++++++++
>  4 files changed, 75 insertions(+)
>  create mode 100644 Documentation/loongarch/syscall-abi.rst
>  create mode 100644 Documentation/translations/zh_CN/loongarch/syscall-abi.rst

Would you like me to take these through the docs tree?

Thanks,

jon

Re: [PATCH 0/2] LoongArch syscall ABI documentation

[WANG Xuerui]

On 10/29/22 02:39, Jonathan Corbet wrote:
> WANG Xuerui <kernel@xen0n.name> writes:
>
>> From: WANG Xuerui <git@xen0n.name>
>>
>> Hi,
>>
>> Due to popular demand [1] (even Loongson employees can get lost), the
>> current LoongArch syscall ABI is now documented. A Simplified Chinese
>> translation is included too.
>>
>> [1]: https://github.com/loongson/LoongArch-Documentation/issues/66
>>
>> WANG Xuerui (2):
>>    Documentation: LoongArch: Document the syscall ABI
>>    docs/zh_CN: LoongArch: Translate the syscall ABI doc
>>
>>   Documentation/loongarch/index.rst             |  1 +
>>   Documentation/loongarch/syscall-abi.rst       | 36 ++++++++++++++++++
>>   .../translations/zh_CN/loongarch/index.rst    |  1 +
>>   .../zh_CN/loongarch/syscall-abi.rst           | 37 +++++++++++++++++++
>>   4 files changed, 75 insertions(+)
>>   create mode 100644 Documentation/loongarch/syscall-abi.rst
>>   create mode 100644 Documentation/translations/zh_CN/loongarch/syscall-abi.rst
> Would you like me to take these through the docs tree?
That's fine by me, thanks. I'll send a v2 in the weekend (likely 
tomorrow) for the people who have commented to give their R-b's.
>
> Thanks,
>
> jon

-- 
WANG "xen0n" Xuerui

Linux/LoongArch mailing list: https://lore.kernel.org/loongarch/

Re: [PATCH 0/2] LoongArch syscall ABI documentation

[Xi Ruoyao]

On Sat, 2022-10-29 at 17:14 +0800, WANG Xuerui wrote:
> On 10/29/22 02:39, Jonathan Corbet wrote:
> > WANG Xuerui <kernel@xen0n.name> writes:
> > 
> > > From: WANG Xuerui <git@xen0n.name>
> > > 
> > > Hi,
> > > 
> > > Due to popular demand [1] (even Loongson employees can get lost),
> > > the
> > > current LoongArch syscall ABI is now documented. A Simplified
> > > Chinese
> > > translation is included too.
> > > 
> > > [1]: https://github.com/loongson/LoongArch-Documentation/issues/66
> > > 
> > > WANG Xuerui (2):
> > >    Documentation: LoongArch: Document the syscall ABI
> > >    docs/zh_CN: LoongArch: Translate the syscall ABI doc
> > > 
> > >   Documentation/loongarch/index.rst             |  1 +
> > >   Documentation/loongarch/syscall-abi.rst       | 36
> > > ++++++++++++++++++
> > >   .../translations/zh_CN/loongarch/index.rst    |  1 +
> > >   .../zh_CN/loongarch/syscall-abi.rst           | 37
> > > +++++++++++++++++++
> > >   4 files changed, 75 insertions(+)
> > >   create mode 100644 Documentation/loongarch/syscall-abi.rst
> > >   create mode 100644
> > > Documentation/translations/zh_CN/loongarch/syscall-abi.rst
> > Would you like me to take these through the docs tree?
> That's fine by me, thanks. I'll send a v2 in the weekend (likely 
> tomorrow) for the people who have commented to give their R-b's.

Ping ? :)

-- 
Xi Ruoyao <xry111@xry111.site>
School of Aerospace Science and Technology, Xidian University