docs: Improve loongarch documents
Subsystems (3)
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
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
@@ -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
@@ -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
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
Signed-off-by Yanteng Si <[email protected]>--- 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@@ -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@@ -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:
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
Signed-off-by Yanteng Si <[email protected]>---
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@@ -45,10 +45,12 @@ Name Alias UsagePreserved
``$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@@ -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:
Reviewed-by WANG Xuerui <[email protected]>
PATCH v2 2/2 docs/zh_CN: Rewrite all the notes
In reply to Yanteng SiSince 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
@@ -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
@@ -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