Skip to contentSkip to conversation

docs: Improve loongarch documents

PATCH Superseded Yanteng Si 2 participants 5 messages Jun 17, 2022

Subsystems (3)

v2 of 4 Superseded Latest is v4 →

lore
Share & tools
lore

Yanteng Si

author
#0 lore raw

v2 cover docs: Improve loongarch documents

v2:
Fix ``inline literals``.
Delete "注:" of zh_CN patch.
Add fix tag.

v1:
Rewrite all the notes in the loongarch document.
Note is an admonition, let's use the directives implemented in the reference reStructuredText parser. About reStructuredText Directives,
see <https://docutils.sourceforge.io/docs/ref/rst/directives.html>

Yanteng Si (2):
docs: Rewrite all the notes
docs/zh_CN: Rewrite all the notes

 Documentation/loongarch/introduction.rst      | 15 ++++++++-----
 Documentation/loongarch/irq-chip-model.rst    | 22 +++++++++++--------
 .../zh_CN/loongarch/introduction.rst          | 14 +++++++-----
 .../zh_CN/loongarch/irq-chip-model.rst        | 14 +++++++-----
 4 files changed, 38 insertions(+), 27 deletions(-)
Signature · 1 line
2.27.0
author
#1 lore raw

PATCH v2 1/2 docs/LoongArch: Rewrite all the notes

Since 0ea8ce61cb2c ("Documentation: LoongArch: Add basic documentations"), Note is an admonition, But it doesn't show correctly, let's fix it.

---
 Documentation/loongarch/introduction.rst   | 15 +++++++++------
 Documentation/loongarch/irq-chip-model.rst | 22 +++++++++++++---------
 2 files changed, 22 insertions(+), 15 deletions(-)
Documentation/loongarch/introduction.rst +9 -6
index 2bf40ad370df..46e3f8d54067 100644
@@ -45,10 +45,12 @@ Name              Alias           Usage               Preserved
 ``$r23``-``$r31`` ``$s0``-``$s8`` Static registers    Yes
 ================= =============== =================== ============
 
-Note: The register ``$r21`` is reserved in the ELF psABI, but used by the Linux
-kernel for storing the percpu base address. It normally has no ABI name, but is
-called ``$u0`` in the kernel. You may also see ``$v0`` or ``$v1`` in some old code,
-however they are deprecated aliases of ``$a0`` and ``$a1`` respectively.
+.. Note::
+    The register ``$r21`` is reserved in the ELF psABI, but used by the Linux
+    kernel for storing the percpu base address. It normally has no ABI name,
+    but is called ``$u0`` in the kernel. You may also see ``$v0`` or ``$v1``
+    in some old code,however they are deprecated aliases of ``$a0`` and ``$a1``
+    respectively.
 
 FPRs
 ----
@@ -69,8 +71,9 @@ Name              Alias              Usage               Preserved
 ``$f24``-``$f31`` ``$fs0``-``$fs7``  Static registers    Yes
 ================= ================== =================== ============
 
-Note: You may see ``$fv0`` or ``$fv1`` in some old code, however they are deprecated
-aliases of ``$fa0`` and ``$fa1`` respectively.
+.. Note::
+    You may see ``$fv0`` or ``$fv1`` in some old code, however they are
+    deprecated aliases of ``$fa0`` and ``$fa1`` respectively.
 
 VRs
 ----
Documentation/loongarch/irq-chip-model.rst +13 -9
index 8d88f7ab2e5e..7988f4192363 100644
@@ -145,12 +145,16 @@ Documentation of Loongson's LS7A chipset:
 
   https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-7A1000-usermanual-2.00-EN.pdf (in English)
 
-Note: CPUINTC is CSR.ECFG/CSR.ESTAT and its interrupt controller described
-in Section 7.4 of "LoongArch Reference Manual, Vol 1"; LIOINTC is "Legacy I/O
-Interrupts" described in Section 11.1 of "Loongson 3A5000 Processor Reference
-Manual"; EIOINTC is "Extended I/O Interrupts" described in Section 11.2 of
-"Loongson 3A5000 Processor Reference Manual"; HTVECINTC is "HyperTransport
-Interrupts" described in Section 14.3 of "Loongson 3A5000 Processor Reference
-Manual"; PCH-PIC/PCH-MSI is "Interrupt Controller" described in Section 5 of
-"Loongson 7A1000 Bridge User Manual"; PCH-LPC is "LPC Interrupts" described in
-Section 24.3 of "Loongson 7A1000 Bridge User Manual".
+.. Note::
+    - CPUINTC is CSR.ECFG/CSR.ESTAT and its interrupt controller described
+      in Section 7.4 of "LoongArch Reference Manual, Vol 1";
+    - LIOINTC is "Legacy I/OInterrupts" described in Section 11.1 of
+      "Loongson 3A5000 Processor Reference Manual";
+    - EIOINTC is "Extended I/O Interrupts" described in Section 11.2 of
+      "Loongson 3A5000 Processor Reference Manual";
+    - HTVECINTC is "HyperTransport Interrupts" described in Section 14.3 of
+      "Loongson 3A5000 Processor Reference Manual";
+    - PCH-PIC/PCH-MSI is "Interrupt Controller" described in Section 5 of
+      "Loongson 7A1000 Bridge User Manual";
+    - PCH-LPC is "LPC Interrupts" described in Section 24.3 of
+      "Loongson 7A1000 Bridge User Manual".
Signature · 1 line
2.27.0
reviewer Reviewed-by on v2 1/2
#2 lore raw

Re: [PATCH v2 1/2] docs/LoongArch: Rewrite all the notes

Quoted 3 lines · Yanteng Si

Since 0ea8ce61cb2c ("Documentation: LoongArch: Add basic documentations"), Note is an admonition, But it doesn't show correctly, let's fix it.

The commit subject is a bit ambiguous: it sounds like some kind of -- hmm, rewrite -- of the original sentences, while it's actually only a migration to the reST note directive.

I'd suggest re-phrasing the commit message to highlight the "migration" nature instead.

Quoted 14 lines
---
  Documentation/loongarch/introduction.rst   | 15 +++++++++------
  Documentation/loongarch/irq-chip-model.rst | 22 +++++++++++++---------
  2 files changed, 22 insertions(+), 15 deletions(-)
Documentation/loongarch/introduction.rst +0 -0
index 2bf40ad370df..46e3f8d54067 100644
@@ -45,10 +45,12 @@ Name              Alias           Usage               Preserved
  ``$r23``-``$r31`` ``$s0``-``$s8`` Static registers    Yes
  ================= =============== =================== ============

Documentation/loongarch/introduction.rst Name Alias Usage Preserved · line 52

Quoted 10 lines
Documentation/loongarch/introduction.rst +5 -4
 
-Note: The register ``$r21`` is reserved in the ELF psABI, but used by the Linux
-kernel for storing the percpu base address. It normally has no ABI name, but is
-called ``$u0`` in the kernel. You may also see ``$v0`` or ``$v1`` in some old code,
-however they are deprecated aliases of ``$a0`` and ``$a1`` respectively.
+.. Note::
+    The register ``$r21`` is reserved in the ELF psABI, but used by the Linux
+    kernel for storing the percpu base address. It normally has no ABI name,
+    but is called ``$u0`` in the kernel. You may also see ``$v0`` or ``$v1``
+    in some old code,however they are deprecated aliases of ``$a0`` and ``$a1``

Nit: space after "code,".

Quoted 36 lines
Documentation/loongarch/introduction.rst +4 -2
+    respectively.
 
  FPRs
  ----
@@ -69,8 +71,9 @@ Name              Alias              Usage               Preserved
  ``$f24``-``$f31`` ``$fs0``-``$fs7``  Static registers    Yes
  ================= ================== =================== ============
 
-Note: You may see ``$fv0`` or ``$fv1`` in some old code, however they are deprecated
-aliases of ``$fa0`` and ``$fa1`` respectively.
+.. Note::
+    You may see ``$fv0`` or ``$fv1`` in some old code, however they are
+    deprecated aliases of ``$fa0`` and ``$fa1`` respectively.
 
  VRs
  ----
Documentation/loongarch/irq-chip-model.rst +3 -9
index 8d88f7ab2e5e..7988f4192363 100644
@@ -145,12 +145,16 @@ Documentation of Loongson's LS7A chipset:
 
    https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-7A1000-usermanual-2.00-EN.pdf (in English)
 
-Note: CPUINTC is CSR.ECFG/CSR.ESTAT and its interrupt controller described
-in Section 7.4 of "LoongArch Reference Manual, Vol 1"; LIOINTC is "Legacy I/O
-Interrupts" described in Section 11.1 of "Loongson 3A5000 Processor Reference
-Manual"; EIOINTC is "Extended I/O Interrupts" described in Section 11.2 of
-"Loongson 3A5000 Processor Reference Manual"; HTVECINTC is "HyperTransport
-Interrupts" described in Section 14.3 of "Loongson 3A5000 Processor Reference
-Manual"; PCH-PIC/PCH-MSI is "Interrupt Controller" described in Section 5 of
-"Loongson 7A1000 Bridge User Manual"; PCH-LPC is "LPC Interrupts" described in
-Section 24.3 of "Loongson 7A1000 Bridge User Manual".
+.. Note::
+    - CPUINTC is CSR.ECFG/CSR.ESTAT and its interrupt controller described
+      in Section 7.4 of "LoongArch Reference Manual, Vol 1";

Documentation/loongarch/irq-chip-model.rst Documentation of Loongson's LS7A chipset: · line 160

Quoted 10 lines
Documentation/loongarch/irq-chip-model.rst +10 -0
+    - LIOINTC is "Legacy I/OInterrupts" described in Section 11.1 of
+      "Loongson 3A5000 Processor Reference Manual";
+    - EIOINTC is "Extended I/O Interrupts" described in Section 11.2 of
+      "Loongson 3A5000 Processor Reference Manual";
+    - HTVECINTC is "HyperTransport Interrupts" described in Section 14.3 of
+      "Loongson 3A5000 Processor Reference Manual";
+    - PCH-PIC/PCH-MSI is "Interrupt Controller" described in Section 5 of
+      "Loongson 7A1000 Bridge User Manual";
+    - PCH-LPC is "LPC Interrupts" described in Section 24.3 of
+      "Loongson 7A1000 Bridge User Manual".

This seems like tabular content disguised as a list, but I don't have strong preferences here. You may try using a table for this relationship between kernel-speak and manual-speak.

With the nits addressed:

author
#3 lore raw

Re: [PATCH v2 1/2] docs/LoongArch: Rewrite all the notes

Quoted 8 lines · WANG Xuerui
Quoted 3 lines · Yanteng Si

Since 0ea8ce61cb2c ("Documentation: LoongArch: Add basic documentations"), Note is an admonition, But it doesn't show correctly, let's fix it.

The commit subject is a bit ambiguous: it sounds like some kind of -- hmm, rewrite -- of the original sentences, while it's actually only a migration to the reST note directive.

I'd suggest re-phrasing the commit message to highlight the "migration" nature instead.

OK! how about:

Fix notes rendering by using reST directives?

Thanks,

Yanteng

Quoted 90 lines
Quoted 24 lines

---
  Documentation/loongarch/introduction.rst   | 15 +++++++++------ Documentation/loongarch/irq-chip-model.rst | 22 +++++++++++++---------

  2 files changed, 22 insertions(+), 15 deletions(-)
Documentation/loongarch/introduction.rst +0 -0
index 2bf40ad370df..46e3f8d54067 100644
@@ -45,10 +45,12 @@ Name              Alias Usage               

Preserved
  ``$r23``-``$r31`` ``$s0``-``$s8`` Static registers    Yes ================= =============== =================== ============ -Note: The register ``$r21`` is reserved in the ELF psABI, but used by the Linux -kernel for storing the percpu base address. It normally has no ABI name, but is
-called ``$u0`` in the kernel. You may also see ``$v0`` or ``$v1`` in some old code,
-however they are deprecated aliases of ``$a0`` and ``$a1`` respectively.
+.. Note::

Quoted 8 lines

+    The register ``$r21`` is reserved in the ELF psABI, but used by the Linux
+    kernel for storing the percpu base address. It normally has no ABI name,
+    but is called ``$u0`` in the kernel. You may also see ``$v0`` or ``$v1``
+    in some old code,however they are deprecated aliases of ``$a0`` and ``$a1``

Nit: space after "code,".

Quoted 43 lines

+    respectively.
    FPRs
  ----

Documentation/loongarch/introduction.rst +0 -0
@@ -69,8 +71,9 @@ Name              Alias Usage               Preserved

  ``$f24``-``$f31`` ``$fs0``-``$fs7``  Static registers    Yes ================= ================== =================== ============ -Note: You may see ``$fv0`` or ``$fv1`` in some old code, however they are deprecated -aliases of ``$fa0`` and ``$fa1`` respectively.
+.. Note::
+    You may see ``$fv0`` or ``$fv1`` in some old code, however they are +    deprecated aliases of ``$fa0`` and ``$fa1`` respectively.
    VRs
  ----

Documentation/loongarch/irq-chip-model.rst +0 -0
index 8d88f7ab2e5e..7988f4192363 100644
@@ -145,12 +145,16 @@ Documentation of Loongson's LS7A chipset:
 https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-7A1000-usermanual-2.00-EN.pdf (in English)

  -Note: CPUINTC is CSR.ECFG/CSR.ESTAT and its interrupt controller described -in Section 7.4 of "LoongArch Reference Manual, Vol 1"; LIOINTC is "Legacy I/O
-Interrupts" described in Section 11.1 of "Loongson 3A5000 Processor Reference
-Manual"; EIOINTC is "Extended I/O Interrupts" described in Section 11.2 of
-"Loongson 3A5000 Processor Reference Manual"; HTVECINTC is "HyperTransport
-Interrupts" described in Section 14.3 of "Loongson 3A5000 Processor Reference
-Manual"; PCH-PIC/PCH-MSI is "Interrupt Controller" described in Section 5 of
-"Loongson 7A1000 Bridge User Manual"; PCH-LPC is "LPC Interrupts" described in
-Section 24.3 of "Loongson 7A1000 Bridge User Manual".
+.. Note::
+    - CPUINTC is CSR.ECFG/CSR.ESTAT and its interrupt controller described
+      in Section 7.4 of "LoongArch Reference Manual, Vol 1";
+    - LIOINTC is "Legacy I/OInterrupts" described in Section 11.1 of +      "Loongson 3A5000 Processor Reference Manual";
+    - EIOINTC is "Extended I/O Interrupts" described in Section 11.2 of +      "Loongson 3A5000 Processor Reference Manual";

Quoted 8 lines

+    - HTVECINTC is "HyperTransport Interrupts" described in Section 14.3 of
+      "Loongson 3A5000 Processor Reference Manual";
+    - PCH-PIC/PCH-MSI is "Interrupt Controller" described in Section 5 of
+      "Loongson 7A1000 Bridge User Manual";
+    - PCH-LPC is "LPC Interrupts" described in Section 24.3 of +      "Loongson 7A1000 Bridge User Manual".

This seems like tabular content disguised as a list, but I don't have strong preferences here. You may try using a table for this relationship between kernel-speak and manual-speak.

With the nits addressed:

author
#4 lore raw

PATCH v2 2/2 docs/zh_CN: Rewrite all the notes

In reply to Yanteng Si

Since f23b22599f8e ("Documentation/zh_CN: Add basic LoongArch documentations"), Note is an admonition, But it doesn't show correctly, let's fix it.

---
 .../translations/zh_CN/loongarch/introduction.rst  | 14 ++++++++------
 .../zh_CN/loongarch/irq-chip-model.rst             | 14 ++++++++------
 2 files changed, 16 insertions(+), 12 deletions(-)
Documentation/translations/zh_CN/loongarch/introduction.rst +8 -6
index e31a1a928c48..11686ee0caeb 100644
@@ -46,10 +46,11 @@ LA64中每个寄存器为64位宽。 ``$r0`` 的内容总是固定为0,而其
 ``$r23``-``$r31`` ``$s0``-``$s8`` 静态寄存器          是
 ================= =============== =================== ==========
 
-注意:``$r21``寄存器在ELF psABI中保留未使用,但是在Linux内核用于保存每CPU
-变量基地址。该寄存器没有ABI命名,不过在内核中称为``$u0``。在一些遗留代码
-中有时可能见到``$v0``和``$v1``,它们是``$a0``和``$a1``的别名,属于已经废弃
-的用法。
+.. note::
+    注意: ``$r21`` 寄存器在ELF psABI中保留未使用,但是在Linux内核用于保
+    存每CPU变量基地址。该寄存器没有ABI命名,不过在内核中称为 ``$u0`` 。在
+    一些遗留代码中有时可能见到 ``$v0`` 和 ``$v1`` ,它们是 ``$a0`` 和
+    ``$a1`` 的别名,属于已经废弃的用法。
 
 浮点寄存器
 ----------
@@ -68,8 +69,9 @@ LA64中每个寄存器为64位宽。 ``$r0`` 的内容总是固定为0,而其
 ``$f24``-``$f31`` ``$fs0``-``$fs7``  静态寄存器          是
 ================= ================== =================== ==========
 
-注意:在一些遗留代码中有时可能见到 ``$v0`` 和 ``$v1`` ,它们是 ``$a0``
-和 ``$a1`` 的别名,属于已经废弃的用法。
+.. note::
+    注意:在一些遗留代码中有时可能见到 ``$v0`` 和 ``$v1`` ,它们是
+    ``$a0`` 和 ``$a1`` 的别名,属于已经废弃的用法。
 
 
 向量寄存器
Documentation/translations/zh_CN/loongarch/irq-chip-model.rst +8 -6
index 2a4c3ad38be4..fb5d23b49ed5 100644
@@ -147,9 +147,11 @@ PCH-LPC::
 
   https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-7A1000-usermanual-2.00-EN.pdf (英文版)
 
-注:CPUINTC即《龙芯架构参考手册卷一》第7.4节所描述的CSR.ECFG/CSR.ESTAT寄存器及其中断
-控制逻辑;LIOINTC即《龙芯3A5000处理器使用手册》第11.1节所描述的“传统I/O中断”;EIOINTC
-即《龙芯3A5000处理器使用手册》第11.2节所描述的“扩展I/O中断”;HTVECINTC即《龙芯3A5000
-处理器使用手册》第14.3节所描述的“HyperTransport中断”;PCH-PIC/PCH-MSI即《龙芯7A1000桥
-片用户手册》第5章所描述的“中断控制器”;PCH-LPC即《龙芯7A1000桥片用户手册》第24.3节所
-描述的“LPC中断”。
+.. note::
+    - CPUINTC:即《龙芯架构参考手册卷一》第7.4节所描述的CSR.ECFG/CSR.ESTAT寄存器及其
+      中断控制逻辑;
+    - LIOINTC:即《龙芯3A5000处理器使用手册》第11.1节所描述的“传统I/O中断”;
+    - EIOINTC:即《龙芯3A5000处理器使用手册》第11.2节所描述的“扩展I/O中断”;
+    - HTVECINTC:即《龙芯3A5000处理器使用手册》第14.3节所描述的“HyperTransport中断”;
+    - PCH-PIC/PCH-MSI:即《龙芯7A1000桥片用户手册》第5章所描述的“中断控制器”;
+    - PCH-LPC:即《龙芯7A1000桥片用户手册》第24.3节所描述的“LPC中断”。
Signature · 1 line
2.27.0