* [PATCH v1 1/5] docs/zh_CN: add PCI acpi-info translation
2022-09-01 11:15 [PATCH v1 0/5] docs/zh_CN: Add some dt and PCI Chinese translation Yanteng Si
@ 2022-09-01 11:15 ` Yanteng Si
2022-09-02 12:56 ` Wu XiangCheng
2022-09-01 11:15 ` [PATCH v1 2/5] docs/zh_CN: add dt changesets translation Yanteng Si
` (3 subsequent siblings)
4 siblings, 1 reply; 16+ messages in thread
From: Yanteng Si @ 2022-09-01 11:15 UTC (permalink / raw)
To: alexs, bobwxc, seakeel
Cc: Yanteng Si, corbet, chenhuacai, jiaxun.yang, linux-doc, siyanteng01
Translate .../PCI/acpi-info.rst into Chinese.
Add PCI into .../zh_CN/index.rst.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
.../translations/zh_CN/PCI/acpi-info.rst | 139 ++++++++++++++++++
.../translations/zh_CN/PCI/index.rst | 13 +-
Documentation/translations/zh_CN/index.rst | 2 +-
3 files changed, 145 insertions(+), 9 deletions(-)
create mode 100644 Documentation/translations/zh_CN/PCI/acpi-info.rst
diff --git a/Documentation/translations/zh_CN/PCI/acpi-info.rst b/Documentation/translations/zh_CN/PCI/acpi-info.rst
new file mode 100644
index 000000000000..74405a0360dc
--- /dev/null
+++ b/Documentation/translations/zh_CN/PCI/acpi-info.rst
@@ -0,0 +1,139 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/PCI/acpi-info.rst
+
+:翻译:
+
+ 司延腾 Yanteng Si <siyanteng@loongson.cn>
+
+:校译:
+
+
+=====================
+PCI主桥的ACPI注意事项
+=====================
+
+一般的规则是，ACPI命名空间应该描述操作系统可能使用的所有东西，除非有其他方法让操作系
+统找到它[1, 2]。
+
+例如，没有标准的硬件机制来枚举PCI主桥，所以ACPI命名空间必须描述每个主桥、访问它
+下面的PCI配置空间的方法、主桥转发到PCI的地址空间窗口（使用_CRS）以及传统的INTx
+中断的路由（使用_PRT）。
+
+PCI设备，在主桥下面，通常不需要通过ACPI描述。操作系统可以通过标准的PCI枚举机制来
+发现它们，使用配置访问来发现和识别设备，并读取和测量它们的BAR。然而，如果ACPI为它们
+提供电源管理或热插拔功能，或者如果设备有INTx中断，由平台中断控制器连接，需要一个_PRT
+来描述这些连接，这种情况下ACPI可以描述PCI设备。
+
+ACPI资源描述是通过ACPI命名空间中设备的_CRS对象完成的[2]。_CRS就像一个通用的PCI BAR：
+操作系统可以读取_CRS并找出正在消耗的资源，即使它没有该设备的驱动程序[3]。这一点很重要，
+因为它意味着一个旧的操作系统可以正确地工作，即使是在操作系统不知道的新设备的系统上。新设
+备可能什么都不做，但操作系统至少可以确保没有资源与它们冲突。
+
+像MCFG、HPET、ECDT等静态表，不是保留地址空间的机制。静态表是在操作系统在启动初期且在它
+能够解析ACPI命名空间之前需要知道的东西。如果定义了一个新的表，即使旧的操作系统忽略了这
+个表，它也需要正常运行。_CRS允许这样做，因为它是通用的，可以被旧的操作系统解析；而静态表
+则不允许。
+
+如果操作系统要管理一个通过ACPI描述的不可发现的设备，该设备将有一个特定的_HID/_CID，操
+作系统将其告诉与之绑定的驱动程序，并且_CRS告诉操作系统和驱动程序该设备的寄存器在哪里。
+
+PCI主桥是PNP0A03或PNP0A08设备。它们的_CRS应该描述它们所消耗的所有地址空间。这包括它
+们转发到PCI总线上的所有窗口，以及不转发到PCI的主桥本身的寄存器。主桥的寄存器包括次要/下
+级总线寄存器，决定了桥下面的总线范围，窗口寄存器描述了桥洞，等等。这些都是设备相关的，非
+架构相关的东西，所以PNP0A03/PNP0A08驱动可以管理它们的唯一方法是通过_PRS/_CRS/_SRS，
+它包含了特定于设备的细节。主桥寄存器也包括ECAM空间，因为它是由主桥消耗的。
+
+ACPI 定义了一个 Consumer/Producer 位来区分桥寄存器（“Consumer”下文译作消费者）和
+桥洞（“Producer”下文译作生产者）[4, 5]，但是早期的 BIOS 没有正确使用这个位。其结果
+是，目前的ACPI规范只为扩展地址空间描述符定义了消费者/生产者；在旧的QWord/Word/Word地
+址空间描述符中，该位应该被忽略。因此，操作系统必须假定所有的QWord/Word/Word描述符都是
+窗口。
+
+在增加扩展地址空间描述符之前，消费者/生产者的失败意味着没有办法描述PNP0A03/PNP0A08设
+备本身的桥寄存器。解决办法是在 PNP0C02 捕捉器中描述桥寄存器（包括 ECAM 空间）[6]。
+除了 ECAM 之外，桥寄存器空间反正是特定于设备的，所以通用的 PNP0A03/PNP0A08 驱动程
+序 (pci_root.c) 没有必要了解它。
+
+新的架构应该能够在 PNP0A03 设备中使用“消费者”扩展地址空间描述符，用于桥寄存器，包括
+ECAM，尽管对 [6] 的严格解释可能禁止这样做。旧的 x86 和 ia64 内核假定所有的地址空间
+描述符，包括“消费者”扩展地址空间的描述符，都是窗口，所以在这些架构上以这种方式描述桥寄
+存器是不安全的。
+
+PNP0C02 “主板”设备基本上是万能的。除了“不要将这些资源用于其他用途”之外，没有其他的编
+程模型。因此，PNP0C02 _CRS应该声明ACPI命名空间中(1)没有被_CRS声明的任何其他设备对
+象的地址空间，(2)不应该被OS分配给其他东西。
+
+除非有一个标准的固件接口用于配置访问，例如ia64 SAL接口[7], 否则PCIe规范要求使用增强
+型配置访问方法（ECAM）。主桥消耗ECAM内存地址空间并将内存访问转换为PCI配置访问。该规范
+定义了ECAM地址空间的布局和功能；只有地址空间的基础是特定于设备的。ACPI操作系统从静态
+MCFG表或PNP0A03设备中的_CBA方法中了解基础地址。
+
+MCFG表必须描述非热插拔主桥的ECAM空间[8]。由于MCFG是一个静态表，不能通过热插拔更新，
+PNP0A03设备中的_CBA方法描述了可热插拔主桥的ECAM空间[9]。请注意，对于 MCFG 和 _CBA，
+基址总是对应于总线 0，即使桥器下面的总线范围（通过 _CRS 报告）不从 0 开始。
+
+
+[1] ACPI 6.2, sec 6.1:
+ 对于任何在非枚举类型的总线上的设备（例如，ISA总线），OSPM会枚举设备的标识符，ACPI
+ 系统固件必须为每个设备提供一个_HID对象...以使OSPM能够做到这一点。
+
+[2] ACPI 6.2, sec 3.7:
+ 操作系统枚举主板设备时，只需通过读取ACPI命名空间来寻找具有硬件ID的设备。
+
+ ACPI枚举的每个设备都包括ACPI命名空间中ACPI定义的对象，该对象报告设备可能占用的硬
+ 件资源[_PRS]，报告设备当前使用的资源[_CRS]的对象，以及配置这些资源的对象[_SRS]。
+ 这些信息被即插即用操作系统（OSPM）用来配置设备。
+
+[3] ACPI 6.2, sec 6.2:
+ OSPM使用设备配置对象来配置通过ACPI列举的设备的硬件资源。设备配置对象提供了关于当前
+ 和可能的资源需求的信息，共享资源之间的关系，以及配置硬件资源的方法。
+
+ 当OSPM枚举一个设备时，它调用_PRS来确定该设备的资源需求。它也可以调用_CRS来找到该设
+ 备的当前资源设置。利用这些信息，即插即用系统决定设备应该消耗什么资源，并通过调用设备
+ 的_SRS控制方法来设置这些资源。
+
+ 在ACPI中，设备可以消耗资源（例如，传统的键盘），提供资源（例如，一个专有的PCI桥），
+ 或者两者都做。除非另有规定，设备的资源被假定为来自设备层次结构中设备上方最近的匹配资
+ 源。
+
+[4] ACPI 6.2, sec 6.4.3.5.1, 2, 3, 4:
+ QWord/DWord/Word 地址空间描述符 (.1, .2, .3)
+ 常规标志: Bit [0] 被忽略。
+
+ 扩展地址空间描述符 (.4)
+ 常规标志: Bit [0] 消费者/生产者:
+
+ * 1 – 这个设备消费这个资源
+ * 0 – 该设备生产和消费该资源
+
+[5] ACPI 6.2, sec 19.6.43:
+ ResourceUsage指定内存范围是由这个设备（ResourceConsumer）消费还是传递给子设备
+ （ResourceProducer）。如果没有指定，那么就假定是ResourceConsumer。
+
+[6] PCI Firmware 3.2, sec 4.1.2:
+ 如果操作系统不能原生的懂得保留MMCFG区域，MMCFG区域必须由固件保留。在MCFG表中或通
+ 过_CBA方法（见第4.1.3节）报告的地址范围必须通过声明主板资源来保留。对于大多数系统，
+ 主板资源将出现在ACPI命名空间的根部（在_SB下），在一个节点的_HID为EISAID（PNP0C0
+ 2），在这种情况下的资源不应该要求在根PCI总线的_CRS。这些资源可以选择在Int15 E820
+ 或EFIGetMemoryMap中作为保留内存返回，但必须始终通过ACPI作为主板资源报告。
+
+[7] PCI Express 4.0, sec 7.2.2:
+ 对于PC兼容的系统，或者没有实现允许访问配置空间的处理器架构特定固件接口标准的系统，需
+ 要使用本节中定义的ECAM。
+
+[8] PCI Firmware 3.2, sec 4.1.2:
+ MCFG表是一个ACPI表，用于沟通的基础地址对应的非热的可移动的PCI段组范围内的PCI段组在
+ 启动时提供给操作系统。这对PC兼容系统来说是必需的。
+
+ MCFG表仅用于通信的基地址对应的PCI段组可用的系统在启动。
+
+[9] PCI Firmware 3.2, sec 4.1.3:
+ _CBA (Memory mapped Configuration Base Address) 控制方法是一个可选的ACPI对
+ 象，用于返回热插拔主桥的64位内存映射的配置基址。_CBA 返回的基址是与处理器相关的地址。
+ _CBA 控制方法被评估为一个整数。
+
+ 这个控制方法出现在主桥对象下。当_CBA方法出现在一个活动的主桥对象下时，操作系统会评
+ 估这个结构，以确定内存映射的配置基址，对应于_CRS方法中指定的总线编号范围的PCI段组。
+ 一个包含_CBA方法的ACPI命名空间对象也必须包含一个相应的_SEG方法。
diff --git a/Documentation/translations/zh_CN/PCI/index.rst b/Documentation/translations/zh_CN/PCI/index.rst
index 16acb2bd9b58..cbeb33c34a98 100644
--- a/Documentation/translations/zh_CN/PCI/index.rst
+++ b/Documentation/translations/zh_CN/PCI/index.rst
@@ -10,9 +10,6 @@
:校译:
-
-.. _cn_PCI_index.rst:
-
===================
Linux PCI总线子系统
===================
@@ -26,12 +23,12 @@ Linux PCI总线子系统
pci-iov-howto
msi-howto
sysfs-pci
+ acpi-info
Todolist:
- acpi-info
- pci-error-recovery
- pcieaer-howto
- endpoint/index
- boot-interrupts
+* pci-error-recovery
+* pcieaer-howto
+* endpoint/index
+* boot-interrupts
diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst
index 4f04367a4c5e..2fc60e60feb4 100644
--- a/Documentation/translations/zh_CN/index.rst
+++ b/Documentation/translations/zh_CN/index.rst
@@ -121,6 +121,7 @@ TODOList:
scheduler/index
mm/index
peci/index
+ PCI/index
TODOList:
@@ -148,7 +149,6 @@ TODOList:
* crypto/index
* bpf/index
* usb/index
-* PCI/index
* scsi/index
* misc-devices/index
* mhi/index
--
2.31.1
^ permalink raw reply related [flat|nested] 16+ messages in thread* Re: [PATCH v1 1/5] docs/zh_CN: add PCI acpi-info translation
2022-09-01 11:15 ` [PATCH v1 1/5] docs/zh_CN: add PCI acpi-info translation Yanteng Si
@ 2022-09-02 12:56 ` Wu XiangCheng
2022-09-05 12:27 ` YanTeng Si
0 siblings, 1 reply; 16+ messages in thread
From: Wu XiangCheng @ 2022-09-02 12:56 UTC (permalink / raw)
To: Yanteng Si
Cc: alexs, bobwxc, seakeel, corbet, chenhuacai, jiaxun.yang,
linux-doc, siyanteng01
2022-09-01 (四) 19:15:42 +0800 Yanteng Si 曰：
> Translate .../PCI/acpi-info.rst into Chinese.
> Add PCI into .../zh_CN/index.rst.
>
> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> ---
> .../translations/zh_CN/PCI/acpi-info.rst | 139 ++++++++++++++++++
> .../translations/zh_CN/PCI/index.rst | 13 +-
> Documentation/translations/zh_CN/index.rst | 2 +-
> 3 files changed, 145 insertions(+), 9 deletions(-)
> create mode 100644 Documentation/translations/zh_CN/PCI/acpi-info.rst
>
> diff --git a/Documentation/translations/zh_CN/PCI/acpi-info.rst b/Documentation/translations/zh_CN/PCI/acpi-info.rst
> new file mode 100644
> index 000000000000..74405a0360dc
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/PCI/acpi-info.rst
@@ -0,0 +1,24 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/PCI/acpi-info.rst
> +
> +:翻译:
> +
> + 司延腾 Yanteng Si <siyanteng@loongson.cn>
> +
> +:校译:
> +
> +
> +=====================
> +PCI主桥的ACPI注意事项
> +=====================
> +
> +一般的规则是，ACPI命名空间应该描述操作系统可能使用的所有东西，除非有其他方法让操作系
> +统找到它[1, 2]。
> +
> +例如，没有标准的硬件机制来枚举PCI主桥，所以ACPI命名空间必须描述每个主桥、访问它
> +下面的PCI配置空间的方法、主桥转发到PCI的地址空间窗口（使用_CRS）以及传统的INTx
> +中断的路由（使用_PRT）。
> +
> +PCI设备，在主桥下面，通常不需要通过ACPI描述。操作系统可以通过标准的PCI枚举机制来
在主桥下面的PCI设备
> +发现它们，使用配置访问来发现和识别设备，并读取和测量它们的BAR。然而，如果ACPI为它们
> +提供电源管理或热插拔功能，或者如果设备有INTx中断，由平台中断控制器连接，需要一个_PRT
设备有由平台中断控制器连接的INTx中断
> +来描述这些连接，这种情况下ACPI可以描述PCI设备。
> +
> +ACPI资源描述是通过ACPI命名空间中设备的_CRS对象完成的[2]。_CRS就像一个通用的PCI BAR：
> +操作系统可以读取_CRS并找出正在消耗的资源，即使它没有该设备的驱动程序[3]。这一点很重要，
> +因为它意味着一个旧的操作系统可以正确地工作，即使是在操作系统不知道的新设备的系统上。新设
> +备可能什么都不做，但操作系统至少可以确保没有资源与它们冲突。
> +
> +像MCFG、HPET、ECDT等静态表，不是保留地址空间的机制。静态表是在操作系统在启动初期且在它
> +能够解析ACPI命名空间之前需要知道的东西。如果定义了一个新的表，即使旧的操作系统忽略了这
> +个表，它也需要正常运行。_CRS允许这样做，因为它是通用的，可以被旧的操作系统解析；而静态表
> +则不允许。
> +
> +如果操作系统要管理一个通过ACPI描述的不可发现的设备，该设备将有一个特定的_HID/_CID，操
> +作系统将其告诉与之绑定的驱动程序，并且_CRS告诉操作系统和驱动程序该设备的寄存器在哪里。
以告诉操作系统与之绑定的驱动程序
> +
> +PCI主桥是PNP0A03或PNP0A08设备。它们的_CRS应该描述它们所消耗的所有地址空间。这包括它
> +们转发到PCI总线上的所有窗口，以及不转发到PCI的主桥本身的寄存器。主桥的寄存器包括次要/下
> +级总线寄存器，决定了桥下面的总线范围，窗口寄存器描述了桥洞，等等。这些都是设备相关的，非
> +架构相关的东西，所以PNP0A03/PNP0A08驱动可以管理它们的唯一方法是通过_PRS/_CRS/_SRS，
> +它包含了特定于设备的细节。主桥寄存器也包括ECAM空间，因为它是由主桥消耗的。
> +
以下6段，检查多余的空格
> +ACPI 定义了一个 Consumer/Producer 位来区分桥寄存器（“Consumer”下文译作消费者）和
> +桥洞（“Producer”下文译作生产者）[4, 5]，但是早期的 BIOS 没有正确使用这个位。其结果
> +是，目前的ACPI规范只为扩展地址空间描述符定义了消费者/生产者；在旧的QWord/Word/Word地
> +址空间描述符中，该位应该被忽略。因此，操作系统必须假定所有的QWord/Word/Word描述符都是
> +窗口。
> +
> +在增加扩展地址空间描述符之前，消费者/生产者的失败意味着没有办法描述PNP0A03/PNP0A08设
> +备本身的桥寄存器。解决办法是在 PNP0C02 捕捉器中描述桥寄存器（包括 ECAM 空间）[6]。
> +除了 ECAM 之外，桥寄存器空间反正是特定于设备的，所以通用的 PNP0A03/PNP0A08 驱动程
> +序 (pci_root.c) 没有必要了解它。
> +
> +新的架构应该能够在 PNP0A03 设备中使用“消费者”扩展地址空间描述符，用于桥寄存器，包括
> +ECAM，尽管对 [6] 的严格解释可能禁止这样做。旧的 x86 和 ia64 内核假定所有的地址空间
> +描述符，包括“消费者”扩展地址空间的描述符，都是窗口，所以在这些架构上以这种方式描述桥寄
> +存器是不安全的。
> +
> +PNP0C02 “主板”设备基本上是万能的。除了“不要将这些资源用于其他用途”之外，没有其他的编
> +程模型。因此，PNP0C02 _CRS应该声明ACPI命名空间中(1)没有被_CRS声明的任何其他设备对
> +象的地址空间，(2)不应该被OS分配给其他东西。
> +
> +除非有一个标准的固件接口用于配置访问，例如ia64 SAL接口[7], 否则PCIe规范要求使用增强
> +型配置访问方法（ECAM）。主桥消耗ECAM内存地址空间并将内存访问转换为PCI配置访问。该规范
> +定义了ECAM地址空间的布局和功能；只有地址空间的基础是特定于设备的。ACPI操作系统从静态
> +MCFG表或PNP0A03设备中的_CBA方法中了解基础地址。
> +
> +MCFG表必须描述非热插拔主桥的ECAM空间[8]。由于MCFG是一个静态表，不能通过热插拔更新，
> +PNP0A03设备中的_CBA方法描述了可热插拔主桥的ECAM空间[9]。请注意，对于 MCFG 和 _CBA，
> +基址总是对应于总线 0，即使桥器下面的总线范围（通过 _CRS 报告）不从 0 开始。
> +
> +
> +[1] ACPI 6.2, sec 6.1:
> + 对于任何在非枚举类型的总线上的设备（例如，ISA总线），OSPM会枚举设备的标识符，ACPI
> + 系统固件必须为每个设备提供一个_HID对象...以使OSPM能够做到这一点。
> +
> +[2] ACPI 6.2, sec 3.7:
> + 操作系统枚举主板设备时，只需通过读取ACPI命名空间来寻找具有硬件ID的设备。
> +
> + ACPI枚举的每个设备都包括ACPI命名空间中ACPI定义的对象，该对象报告设备可能占用的硬
> + 件资源[_PRS]，报告设备当前使用的资源[_CRS]的对象，以及配置这些资源的对象[_SRS]。
> + 这些信息被即插即用操作系统（OSPM）用来配置设备。
> +
> +[3] ACPI 6.2, sec 6.2:
> + OSPM使用设备配置对象来配置通过ACPI列举的设备的硬件资源。设备配置对象提供了关于当前
> + 和可能的资源需求的信息，共享资源之间的关系，以及配置硬件资源的方法。
> +
> + 当OSPM枚举一个设备时，它调用_PRS来确定该设备的资源需求。它也可以调用_CRS来找到该设
> + 备的当前资源设置。利用这些信息，即插即用系统决定设备应该消耗什么资源，并通过调用设备
> + 的_SRS控制方法来设置这些资源。
> +
> + 在ACPI中，设备可以消耗资源（例如，传统的键盘），提供资源（例如，一个专有的PCI桥），
> + 或者两者都做。除非另有规定，设备的资源被假定为来自设备层次结构中设备上方最近的匹配资
> + 源。
> +
> +[4] ACPI 6.2, sec 6.4.3.5.1, 2, 3, 4:
> + QWord/DWord/Word 地址空间描述符 (.1, .2, .3)
> + 常规标志: Bit [0] 被忽略。
> +
> + 扩展地址空间描述符 (.4)
> + 常规标志: Bit [0] 消费者/生产者:
> +
> + * 1 – 这个设备消费这个资源
> + * 0 – 该设备生产和消费该资源
> +
> +[5] ACPI 6.2, sec 19.6.43:
> + ResourceUsage指定内存范围是由这个设备（ResourceConsumer）消费还是传递给子设备
> + （ResourceProducer）。如果没有指定，那么就假定是ResourceConsumer。
> +
> +[6] PCI Firmware 3.2, sec 4.1.2:
> + 如果操作系统不能原生的懂得保留MMCFG区域，MMCFG区域必须由固件保留。在MCFG表中或通
> + 过_CBA方法（见第4.1.3节）报告的地址范围必须通过声明主板资源来保留。对于大多数系统，
> + 主板资源将出现在ACPI命名空间的根部（在_SB下），在一个节点的_HID为EISAID（PNP0C0
> + 2），在这种情况下的资源不应该要求在根PCI总线的_CRS。这些资源可以选择在Int15 E820
> + 或EFIGetMemoryMap中作为保留内存返回，但必须始终通过ACPI作为主板资源报告。
> +
> +[7] PCI Express 4.0, sec 7.2.2:
> + 对于PC兼容的系统，或者没有实现允许访问配置空间的处理器架构特定固件接口标准的系统，需
> + 要使用本节中定义的ECAM。
> +
> +[8] PCI Firmware 3.2, sec 4.1.2:
> + MCFG表是一个ACPI表，用于沟通的基础地址对应的非热的可移动的PCI段组范围内的PCI段组在
> + 启动时提供给操作系统。这对PC兼容系统来说是必需的。
> +
> + MCFG表仅用于通信的基地址对应的PCI段组可用的系统在启动。
MCFG表仅用于沟通在启动时系统可用的PCI段组对应的基址。
> +
> +[9] PCI Firmware 3.2, sec 4.1.3:
> + _CBA (Memory mapped Configuration Base Address) 控制方法是一个可选的ACPI对
> + 象，用于返回热插拔主桥的64位内存映射的配置基址。_CBA 返回的基址是与处理器相关的地址。
> + _CBA 控制方法被评估为一个整数。
> +
> + 这个控制方法出现在主桥对象下。当_CBA方法出现在一个活动的主桥对象下时，操作系统会评
> + 估这个结构，以确定内存映射的配置基址，对应于_CRS方法中指定的总线编号范围的PCI段组。
> + 一个包含_CBA方法的ACPI命名空间对象也必须包含一个相应的_SEG方法。
> diff --git a/Documentation/translations/zh_CN/PCI/index.rst b/Documentation/translations/zh_CN/PCI/index.rst
> index 16acb2bd9b58..cbeb33c34a98 100644
> --- a/Documentation/translations/zh_CN/PCI/index.rst
> +++ b/Documentation/translations/zh_CN/PCI/index.rst
> @@ -10,9 +10,6 @@
> :校译:
>
>
> -
> -.. _cn_PCI_index.rst:
> -
> ===================
> Linux PCI总线子系统
> ===================
> @@ -26,12 +23,12 @@ Linux PCI总线子系统
> pci-iov-howto
> msi-howto
> sysfs-pci
> + acpi-info
>
>
> Todolist:
>
> - acpi-info
> - pci-error-recovery
> - pcieaer-howto
> - endpoint/index
> - boot-interrupts
> +* pci-error-recovery
> +* pcieaer-howto
> +* endpoint/index
> +* boot-interrupts
> diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst
> index 4f04367a4c5e..2fc60e60feb4 100644
> --- a/Documentation/translations/zh_CN/index.rst
> +++ b/Documentation/translations/zh_CN/index.rst
> @@ -121,6 +121,7 @@ TODOList:
> scheduler/index
> mm/index
> peci/index
> + PCI/index
>
> TODOList:
>
> @@ -148,7 +149,6 @@ TODOList:
> * crypto/index
> * bpf/index
> * usb/index
> -* PCI/index
> * scsi/index
> * misc-devices/index
> * mhi/index
> --
> 2.31.1
>
Thanks,
--
Wu XiangCheng 0x32684A40BCA7AEA7
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [PATCH v1 1/5] docs/zh_CN: add PCI acpi-info translation
2022-09-02 12:56 ` Wu XiangCheng
@ 2022-09-05 12:27 ` YanTeng Si
2022-09-05 16:41 ` Wu XiangCheng
0 siblings, 1 reply; 16+ messages in thread
From: YanTeng Si @ 2022-09-05 12:27 UTC (permalink / raw)
To: Wu XiangCheng
Cc: alexs, bobwxc, seakeel, corbet, chenhuacai, jiaxun.yang,
linux-doc, siyanteng01
在 2022/9/2 20:56, Wu XiangCheng 写道:
> 2022-09-01 (四) 19:15:42 +0800 Yanteng Si 曰：
>> Translate .../PCI/acpi-info.rst into Chinese.
>> Add PCI into .../zh_CN/index.rst.
>>
>> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
>> ---
>> .../translations/zh_CN/PCI/acpi-info.rst | 139 ++++++++++++++++++
>> .../translations/zh_CN/PCI/index.rst | 13 +-
>> Documentation/translations/zh_CN/index.rst | 2 +-
>> 3 files changed, 145 insertions(+), 9 deletions(-)
>> create mode 100644 Documentation/translations/zh_CN/PCI/acpi-info.rst
>>
>> diff --git a/Documentation/translations/zh_CN/PCI/acpi-info.rst b/Documentation/translations/zh_CN/PCI/acpi-info.rst
>> new file mode 100644
>> index 000000000000..74405a0360dc
>> --- /dev/null
>> +++ b/Documentation/translations/zh_CN/PCI/acpi-info.rst
> @@ -0,0 +1,24 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +.. include:: ../disclaimer-zh_CN.rst
>> +
>> +:Original: Documentation/PCI/acpi-info.rst
>> +
>> +:翻译:
>> +
>> + 司延腾 Yanteng Si <siyanteng@loongson.cn>
>> +
>> +:校译:
>> +
>> +
>> +=====================
>> +PCI主桥的ACPI注意事项
>> +=====================
>> +
>> +一般的规则是，ACPI命名空间应该描述操作系统可能使用的所有东西，除非有其他方法让操作系
>> +统找到它[1, 2]。
>> +
>> +例如，没有标准的硬件机制来枚举PCI主桥，所以ACPI命名空间必须描述每个主桥、访问它
>> +下面的PCI配置空间的方法、主桥转发到PCI的地址空间窗口（使用_CRS）以及传统的INTx
>> +中断的路由（使用_PRT）。
>> +
>> +PCI设备，在主桥下面，通常不需要通过ACPI描述。操作系统可以通过标准的PCI枚举机制来
> 在主桥下面的PCI设备
OK!
>
>> +发现它们，使用配置访问来发现和识别设备，并读取和测量它们的BAR。然而，如果ACPI为它们
>> +提供电源管理或热插拔功能，或者如果设备有INTx中断，由平台中断控制器连接，需要一个_PRT
> 设备有由平台中断控制器连接的INTx中断
OK!
>
>> +来描述这些连接，这种情况下ACPI可以描述PCI设备。
>> +
>> +ACPI资源描述是通过ACPI命名空间中设备的_CRS对象完成的[2]。_CRS就像一个通用的PCI BAR：
>> +操作系统可以读取_CRS并找出正在消耗的资源，即使它没有该设备的驱动程序[3]。这一点很重要，
>> +因为它意味着一个旧的操作系统可以正确地工作，即使是在操作系统不知道的新设备的系统上。新设
>> +备可能什么都不做，但操作系统至少可以确保没有资源与它们冲突。
>> +
>> +像MCFG、HPET、ECDT等静态表，不是保留地址空间的机制。静态表是在操作系统在启动初期且在它
>> +能够解析ACPI命名空间之前需要知道的东西。如果定义了一个新的表，即使旧的操作系统忽略了这
>> +个表，它也需要正常运行。_CRS允许这样做，因为它是通用的，可以被旧的操作系统解析；而静态表
>> +则不允许。
>> +
>> +如果操作系统要管理一个通过ACPI描述的不可发现的设备，该设备将有一个特定的_HID/_CID，操
>> +作系统将其告诉与之绑定的驱动程序，并且_CRS告诉操作系统和驱动程序该设备的寄存器在哪里。
> 以告诉操作系统与之绑定的驱动程序
OK!
>
>> +
>> +PCI主桥是PNP0A03或PNP0A08设备。它们的_CRS应该描述它们所消耗的所有地址空间。这包括它
>> +们转发到PCI总线上的所有窗口，以及不转发到PCI的主桥本身的寄存器。主桥的寄存器包括次要/下
>> +级总线寄存器，决定了桥下面的总线范围，窗口寄存器描述了桥洞，等等。这些都是设备相关的，非
>> +架构相关的东西，所以PNP0A03/PNP0A08驱动可以管理它们的唯一方法是通过_PRS/_CRS/_SRS，
>> +它包含了特定于设备的细节。主桥寄存器也包括ECAM空间，因为它是由主桥消耗的。
>> +
> 以下6段，检查多余的空格
OK!
BTW:
I have received some feedback from readers that
They are used to writing with spaces between Chinese and English, and I
found that some of the documents we translated have spaces and some do not.
As the number of documents rises, do we need to follow some conventions
to make the documents look better?
Readers gave me this link
<https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.zh-Hans.md>
.
>
>> +ACPI 定义了一个 Consumer/Producer 位来区分桥寄存器（“Consumer”下文译作消费者）和
>> +桥洞（“Producer”下文译作生产者）[4, 5]，但是早期的 BIOS 没有正确使用这个位。其结果
>> +是，目前的ACPI规范只为扩展地址空间描述符定义了消费者/生产者；在旧的QWord/Word/Word地
>> +址空间描述符中，该位应该被忽略。因此，操作系统必须假定所有的QWord/Word/Word描述符都是
>> +窗口。
>> +
>> +在增加扩展地址空间描述符之前，消费者/生产者的失败意味着没有办法描述PNP0A03/PNP0A08设
>> +备本身的桥寄存器。解决办法是在 PNP0C02 捕捉器中描述桥寄存器（包括 ECAM 空间）[6]。
>> +除了 ECAM 之外，桥寄存器空间反正是特定于设备的，所以通用的 PNP0A03/PNP0A08 驱动程
>> +序 (pci_root.c) 没有必要了解它。
>> +
>> +新的架构应该能够在 PNP0A03 设备中使用“消费者”扩展地址空间描述符，用于桥寄存器，包括
>> +ECAM，尽管对 [6] 的严格解释可能禁止这样做。旧的 x86 和 ia64 内核假定所有的地址空间
>> +描述符，包括“消费者”扩展地址空间的描述符，都是窗口，所以在这些架构上以这种方式描述桥寄
>> +存器是不安全的。
>> +
>> +PNP0C02 “主板”设备基本上是万能的。除了“不要将这些资源用于其他用途”之外，没有其他的编
>> +程模型。因此，PNP0C02 _CRS应该声明ACPI命名空间中(1)没有被_CRS声明的任何其他设备对
>> +象的地址空间，(2)不应该被OS分配给其他东西。
>> +
>> +除非有一个标准的固件接口用于配置访问，例如ia64 SAL接口[7], 否则PCIe规范要求使用增强
>> +型配置访问方法（ECAM）。主桥消耗ECAM内存地址空间并将内存访问转换为PCI配置访问。该规范
>> +定义了ECAM地址空间的布局和功能；只有地址空间的基础是特定于设备的。ACPI操作系统从静态
>> +MCFG表或PNP0A03设备中的_CBA方法中了解基础地址。
>> +
>> +MCFG表必须描述非热插拔主桥的ECAM空间[8]。由于MCFG是一个静态表，不能通过热插拔更新，
>> +PNP0A03设备中的_CBA方法描述了可热插拔主桥的ECAM空间[9]。请注意，对于 MCFG 和 _CBA，
>> +基址总是对应于总线 0，即使桥器下面的总线范围（通过 _CRS 报告）不从 0 开始。
>> +
>> +
>> +[1] ACPI 6.2, sec 6.1:
>> + 对于任何在非枚举类型的总线上的设备（例如，ISA总线），OSPM会枚举设备的标识符，ACPI
>> + 系统固件必须为每个设备提供一个_HID对象...以使OSPM能够做到这一点。
>> +
>> +[2] ACPI 6.2, sec 3.7:
>> + 操作系统枚举主板设备时，只需通过读取ACPI命名空间来寻找具有硬件ID的设备。
>> +
>> + ACPI枚举的每个设备都包括ACPI命名空间中ACPI定义的对象，该对象报告设备可能占用的硬
>> + 件资源[_PRS]，报告设备当前使用的资源[_CRS]的对象，以及配置这些资源的对象[_SRS]。
>> + 这些信息被即插即用操作系统（OSPM）用来配置设备。
>> +
>> +[3] ACPI 6.2, sec 6.2:
>> + OSPM使用设备配置对象来配置通过ACPI列举的设备的硬件资源。设备配置对象提供了关于当前
>> + 和可能的资源需求的信息，共享资源之间的关系，以及配置硬件资源的方法。
>> +
>> + 当OSPM枚举一个设备时，它调用_PRS来确定该设备的资源需求。它也可以调用_CRS来找到该设
>> + 备的当前资源设置。利用这些信息，即插即用系统决定设备应该消耗什么资源，并通过调用设备
>> + 的_SRS控制方法来设置这些资源。
>> +
>> + 在ACPI中，设备可以消耗资源（例如，传统的键盘），提供资源（例如，一个专有的PCI桥），
>> + 或者两者都做。除非另有规定，设备的资源被假定为来自设备层次结构中设备上方最近的匹配资
>> + 源。
>> +
>> +[4] ACPI 6.2, sec 6.4.3.5.1, 2, 3, 4:
>> + QWord/DWord/Word 地址空间描述符 (.1, .2, .3)
>> + 常规标志: Bit [0] 被忽略。
>> +
>> + 扩展地址空间描述符 (.4)
>> + 常规标志: Bit [0] 消费者/生产者:
>> +
>> + * 1 – 这个设备消费这个资源
>> + * 0 – 该设备生产和消费该资源
>> +
>> +[5] ACPI 6.2, sec 19.6.43:
>> + ResourceUsage指定内存范围是由这个设备（ResourceConsumer）消费还是传递给子设备
>> + （ResourceProducer）。如果没有指定，那么就假定是ResourceConsumer。
>> +
>> +[6] PCI Firmware 3.2, sec 4.1.2:
>> + 如果操作系统不能原生的懂得保留MMCFG区域，MMCFG区域必须由固件保留。在MCFG表中或通
>> + 过_CBA方法（见第4.1.3节）报告的地址范围必须通过声明主板资源来保留。对于大多数系统，
>> + 主板资源将出现在ACPI命名空间的根部（在_SB下），在一个节点的_HID为EISAID（PNP0C0
>> + 2），在这种情况下的资源不应该要求在根PCI总线的_CRS。这些资源可以选择在Int15 E820
>> + 或EFIGetMemoryMap中作为保留内存返回，但必须始终通过ACPI作为主板资源报告。
>> +
>> +[7] PCI Express 4.0, sec 7.2.2:
>> + 对于PC兼容的系统，或者没有实现允许访问配置空间的处理器架构特定固件接口标准的系统，需
>> + 要使用本节中定义的ECAM。
>> +
>> +[8] PCI Firmware 3.2, sec 4.1.2:
>> + MCFG表是一个ACPI表，用于沟通的基础地址对应的非热的可移动的PCI段组范围内的PCI段组在
>> + 启动时提供给操作系统。这对PC兼容系统来说是必需的。
>> +
>> + MCFG表仅用于通信的基地址对应的PCI段组可用的系统在启动。
> MCFG表仅用于沟通在启动时系统可用的PCI段组对应的基址。
OK!
Thanks,
Yanteng
>
>> +
>> +[9] PCI Firmware 3.2, sec 4.1.3:
>> + _CBA (Memory mapped Configuration Base Address) 控制方法是一个可选的ACPI对
>> + 象，用于返回热插拔主桥的64位内存映射的配置基址。_CBA 返回的基址是与处理器相关的地址。
>> + _CBA 控制方法被评估为一个整数。
>> +
>> + 这个控制方法出现在主桥对象下。当_CBA方法出现在一个活动的主桥对象下时，操作系统会评
>> + 估这个结构，以确定内存映射的配置基址，对应于_CRS方法中指定的总线编号范围的PCI段组。
>> + 一个包含_CBA方法的ACPI命名空间对象也必须包含一个相应的_SEG方法。
>> diff --git a/Documentation/translations/zh_CN/PCI/index.rst b/Documentation/translations/zh_CN/PCI/index.rst
>> index 16acb2bd9b58..cbeb33c34a98 100644
>> --- a/Documentation/translations/zh_CN/PCI/index.rst
>> +++ b/Documentation/translations/zh_CN/PCI/index.rst
>> @@ -10,9 +10,6 @@
>> :校译:
>>
>>
>> -
>> -.. _cn_PCI_index.rst:
>> -
>> ===================
>> Linux PCI总线子系统
>> ===================
>> @@ -26,12 +23,12 @@ Linux PCI总线子系统
>> pci-iov-howto
>> msi-howto
>> sysfs-pci
>> + acpi-info
>>
>>
>> Todolist:
>>
>> - acpi-info
>> - pci-error-recovery
>> - pcieaer-howto
>> - endpoint/index
>> - boot-interrupts
>> +* pci-error-recovery
>> +* pcieaer-howto
>> +* endpoint/index
>> +* boot-interrupts
>> diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst
>> index 4f04367a4c5e..2fc60e60feb4 100644
>> --- a/Documentation/translations/zh_CN/index.rst
>> +++ b/Documentation/translations/zh_CN/index.rst
>> @@ -121,6 +121,7 @@ TODOList:
>> scheduler/index
>> mm/index
>> peci/index
>> + PCI/index
>>
>> TODOList:
>>
>> @@ -148,7 +149,6 @@ TODOList:
>> * crypto/index
>> * bpf/index
>> * usb/index
>> -* PCI/index
>> * scsi/index
>> * misc-devices/index
>> * mhi/index
>> --
>> 2.31.1
>>
> Thanks,
>
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [PATCH v1 1/5] docs/zh_CN: add PCI acpi-info translation
2022-09-05 12:27 ` YanTeng Si
@ 2022-09-05 16:41 ` Wu XiangCheng
2022-09-06 2:19 ` Alex Shi
0 siblings, 1 reply; 16+ messages in thread
From: Wu XiangCheng @ 2022-09-05 16:41 UTC (permalink / raw)
To: YanTeng Si
Cc: alexs, bobwxc, seakeel, corbet, chenhuacai, jiaxun.yang,
linux-doc, siyanteng01
2022-09-05 (一) 20:27:42 +0800 YanTeng Si 曰：
> BTW:
>
>
> I have received some feedback from readers that
>
>
> They are used to writing with spaces between Chinese and English, and I
> found that some of the documents we translated have spaces and some do not.
>
>
> As the number of documents rises, do we need to follow some conventions to
> make the documents look better?
"spaces between Chinese and English" are not actual document
informations. Such style/display issue should be implemented by
rendering software rather than add space manually. If someone want a
perfect view experience, they might try Word, Latex or something else
and generate a pdf, those tools will auto add proper spaces. Or they may
improve the sphinx to get a better html.
And one more important, these spaces are easy to add automatically by
the tools, but difficult to remove later.
Existing documents, let it go. New documents, should not go back to this
outdated rule.
>
> Readers gave me this link <https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.zh-Hans.md>
> .
以及我本来不想说的一点，把“「有研究显示，打字的时候不喜欢在中文和英文之间加空
格的人，感情路都走得很辛苦，有七成的比例会在 34 岁的时候跟自己不爱的人结婚，
而其余三成的人最后只能把遗产留给自己的猫。毕竟爱情跟书写都需要适时地留白。
与大家共勉之。」——vinta/paranoid-auto-spacing”这种东西放在教程开头，实在不
是什么好主意，我建议给出参考文献。否则我就得说“有研究显示，打字的时候喜欢乱加
空格的人，一般大脑都比较空白，有七成的比例会在34岁的时候被公司优化，而其余的
三成最后只能去当产品经理。毕竟思考这种东西是不能在空白基础上展开的。与大家
共勉”，权当博各位一笑。
Thanks,
--
Wu XiangCheng 0x32684A40BCA7AEA7
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [PATCH v1 1/5] docs/zh_CN: add PCI acpi-info translation
2022-09-05 16:41 ` Wu XiangCheng
@ 2022-09-06 2:19 ` Alex Shi
0 siblings, 0 replies; 16+ messages in thread
From: Alex Shi @ 2022-09-06 2:19 UTC (permalink / raw)
To: Wu XiangCheng
Cc: YanTeng Si, Alex Shi, Wu X.C.,
Jonathan Corbet, Huacai Chen, Jiaxun Yang,
Linux Doc Mailing List, yanteng si
On Tue, Sep 6, 2022 at 12:41 AM Wu XiangCheng <wu.xiangcheng@linux.dev> wrote:
>
.
>
> 以及我本来不想说的一点，把“「有研究显示，打字的时候不喜欢在中文和英文之间加空
> 格的人，感情路都走得很辛苦，有七成的比例会在 34 岁的时候跟自己不爱的人结婚，
> 而其余三成的人最后只能把遗产留给自己的猫。毕竟爱情跟书写都需要适时地留白。
> 与大家共勉之。」——vinta/paranoid-auto-spacing”这种东西放在教程开头，实在不
> 是什么好主意，我建议给出参考文献。否则我就得说“有研究显示，打字的时候喜欢乱加
> 空格的人，一般大脑都比较空白，有七成的比例会在34岁的时候被公司优化，而其余的
> 三成最后只能去当产品经理。毕竟思考这种东西是不能在空白基础上展开的。与大家
> 共勉”，权当博各位一笑。
>
哈哈 笑死我了
^ permalink raw reply [flat|nested] 16+ messages in thread
* [PATCH v1 2/5] docs/zh_CN: add dt changesets translation
2022-09-01 11:15 [PATCH v1 0/5] docs/zh_CN: Add some dt and PCI Chinese translation Yanteng Si
2022-09-01 11:15 ` [PATCH v1 1/5] docs/zh_CN: add PCI acpi-info translation Yanteng Si
@ 2022-09-01 11:15 ` Yanteng Si
2022-09-02 6:56 ` Alex Shi
2022-09-01 11:15 ` [PATCH v1 3/5] docs/zh_CN: add dt dynamic-resolution-notes translation Yanteng Si
` (2 subsequent siblings)
4 siblings, 1 reply; 16+ messages in thread
From: Yanteng Si @ 2022-09-01 11:15 UTC (permalink / raw)
To: alexs, bobwxc, seakeel
Cc: Yanteng Si, corbet, chenhuacai, jiaxun.yang, linux-doc, siyanteng01
Translate .../devicetree/changesets.rst into Chinese.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
.../zh_CN/devicetree/changesets.rst | 37 +++++++++++++++++++
.../translations/zh_CN/devicetree/index.rst | 3 +-
2 files changed, 39 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_CN/devicetree/changesets.rst
diff --git a/Documentation/translations/zh_CN/devicetree/changesets.rst b/Documentation/translations/zh_CN/devicetree/changesets.rst
new file mode 100644
index 000000000000..88b2075f1ea0
--- /dev/null
+++ b/Documentation/translations/zh_CN/devicetree/changesets.rst
@@ -0,0 +1,37 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/Devicetree/changesets.rst
+
+:翻译:
+
+ 司延腾 Yanteng Si <siyanteng@loongson.cn>
+
+:校译:
+
+
+============
+设备树变更集
+============
+
+设备树变更集是一种方法，它允许人们以这样一种方式在实时树中应用变化，即要么应用全部的
+变化，要么不应用。如果在应用变更集的过程中发生错误，那么树将被回滚到之前的状态。一个
+变更集也可以在应用后被删除。
+
+当一个变更集被应用时，所有的改变在发出OF_RECONFIG通知器之前被一次性应用到树上。这是
+为了让接收者在收到通知时看到一个完整的、一致的树的状态。
+
+一个变化集的顺序如下。
+
+1. of_changeset_init() - 初始化一个变更集。
+
+2. 一些DT树变化的调用，of_changeset_attach_node(), of_changeset_detach_node(),
+ of_changeset_add_property(), of_changeset_remove_property,
+ of_changeset_update_property()来准备一组变更。此时不会对活动树做任何变更。所有
+ 的变更操作都记录在of_changeset的 `entries` 列表中。
+
+3. of_changeset_apply() - 将变更应用到树上。要么整个变更集被应用，要么如果有错误，
+ 树会被恢复到之前的状态。核心通过锁确保正确的顺序。如果需要的话，可以使用一个解锁的
+ __of_changeset_apply版本。
+
+如果一个成功应用的变更集需要被删除，可以用of_changeset_revert()来完成。
diff --git a/Documentation/translations/zh_CN/devicetree/index.rst b/Documentation/translations/zh_CN/devicetree/index.rst
index 3fc355fe0037..e9aff2ccc579 100644
--- a/Documentation/translations/zh_CN/devicetree/index.rst
+++ b/Documentation/translations/zh_CN/devicetree/index.rst
@@ -34,9 +34,10 @@ Devicetree Overlays
.. toctree::
:maxdepth: 1
+ changesets
+
Todolist:
-* changesets
* dynamic-resolution-notes
* overlay-notes
--
2.31.1
^ permalink raw reply related [flat|nested] 16+ messages in thread* Re: [PATCH v1 2/5] docs/zh_CN: add dt changesets translation
2022-09-01 11:15 ` [PATCH v1 2/5] docs/zh_CN: add dt changesets translation Yanteng Si
@ 2022-09-02 6:56 ` Alex Shi
2022-09-05 11:58 ` YanTeng Si
0 siblings, 1 reply; 16+ messages in thread
From: Alex Shi @ 2022-09-02 6:56 UTC (permalink / raw)
To: Yanteng Si
Cc: Alex Shi, Wu X.C.,
Jonathan Corbet, Huacai Chen, Jiaxun Yang,
Linux Doc Mailing List, yanteng si
On Thu, Sep 1, 2022 at 7:16 PM Yanteng Si <siyanteng@loongson.cn> wrote:
>
> Translate .../devicetree/changesets.rst into Chinese.
>
> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> ---
> .../zh_CN/devicetree/changesets.rst | 37 +++++++++++++++++++
> .../translations/zh_CN/devicetree/index.rst | 3 +-
> 2 files changed, 39 insertions(+), 1 deletion(-)
> create mode 100644 Documentation/translations/zh_CN/devicetree/changesets.rst
>
> diff --git a/Documentation/translations/zh_CN/devicetree/changesets.rst b/Documentation/translations/zh_CN/devicetree/changesets.rst
> new file mode 100644
> index 000000000000..88b2075f1ea0
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/devicetree/changesets.rst
> @@ -0,0 +1,37 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/Devicetree/changesets.rst
> +
> +:翻译:
> +
> + 司延腾 Yanteng Si <siyanteng@loongson.cn>
> +
> +:校译:
> +
> +
> +============
> +设备树变更集
> +============
> +
> +设备树变更集是一种方法，它允许人们以这样一种方式在实时树中应用变化，即要么应用全部的
> +变化，要么不应用。如果在应用变更集的过程中发生错误，那么树将被回滚到之前的状态。一个
> +变更集也可以在应用后被删除。
‘应用’ translation is correct, but maynot fit into Chinese habits, maybe
使用/实现 is better?
> +
> +当一个变更集被应用时，所有的改变在发出OF_RECONFIG通知器之前被一次性应用到树上。这是
> +为了让接收者在收到通知时看到一个完整的、一致的树的状态。
> +
> +一个变化集的顺序如下。
> +
> +1. of_changeset_init() - 初始化一个变更集。
> +
> +2. 一些DT树变化的调用，of_changeset_attach_node(), of_changeset_detach_node(),
> + of_changeset_add_property(), of_changeset_remove_property,
> + of_changeset_update_property()来准备一组变更。此时不会对活动树做任何变更。所有
> + 的变更操作都记录在of_changeset的 `entries` 列表中。
> +
> +3. of_changeset_apply() - 将变更应用到树上。要么整个变更集被应用，要么如果有错误，
> + 树会被恢复到之前的状态。核心通过锁确保正确的顺序。如果需要的话，可以使用一个解锁的
> + __of_changeset_apply版本。
> +
> +如果一个成功应用的变更集需要被删除，可以用of_changeset_revert()来完成。
> diff --git a/Documentation/translations/zh_CN/devicetree/index.rst b/Documentation/translations/zh_CN/devicetree/index.rst
> index 3fc355fe0037..e9aff2ccc579 100644
> --- a/Documentation/translations/zh_CN/devicetree/index.rst
> +++ b/Documentation/translations/zh_CN/devicetree/index.rst
> @@ -34,9 +34,10 @@ Devicetree Overlays
> .. toctree::
> :maxdepth: 1
>
> + changesets
> +
> Todolist:
>
> -* changesets
> * dynamic-resolution-notes
> * overlay-notes
>
> --
> 2.31.1
>
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [PATCH v1 2/5] docs/zh_CN: add dt changesets translation
2022-09-02 6:56 ` Alex Shi
@ 2022-09-05 11:58 ` YanTeng Si
0 siblings, 0 replies; 16+ messages in thread
From: YanTeng Si @ 2022-09-05 11:58 UTC (permalink / raw)
To: Alex Shi
Cc: Alex Shi, Wu X.C.,
Jonathan Corbet, Huacai Chen, Jiaxun Yang,
Linux Doc Mailing List, yanteng si
在 2022/9/2 14:56, Alex Shi 写道:
> On Thu, Sep 1, 2022 at 7:16 PM Yanteng Si <siyanteng@loongson.cn> wrote:
>> Translate .../devicetree/changesets.rst into Chinese.
>>
>> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
>> ---
>> .../zh_CN/devicetree/changesets.rst | 37 +++++++++++++++++++
>> .../translations/zh_CN/devicetree/index.rst | 3 +-
>> 2 files changed, 39 insertions(+), 1 deletion(-)
>> create mode 100644 Documentation/translations/zh_CN/devicetree/changesets.rst
>>
>> diff --git a/Documentation/translations/zh_CN/devicetree/changesets.rst b/Documentation/translations/zh_CN/devicetree/changesets.rst
>> new file mode 100644
>> index 000000000000..88b2075f1ea0
>> --- /dev/null
>> +++ b/Documentation/translations/zh_CN/devicetree/changesets.rst
>> @@ -0,0 +1,37 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +.. include:: ../disclaimer-zh_CN.rst
>> +
>> +:Original: Documentation/Devicetree/changesets.rst
>> +
>> +:翻译:
>> +
>> + 司延腾 Yanteng Si <siyanteng@loongson.cn>
>> +
>> +:校译:
>> +
>> +
>> +============
>> +设备树变更集
>> +============
>> +
>> +设备树变更集是一种方法，它允许人们以这样一种方式在实时树中应用变化，即要么应用全部的
>> +变化，要么不应用。如果在应用变更集的过程中发生错误，那么树将被回滚到之前的状态。一个
>> +变更集也可以在应用后被删除。
> ‘应用’ translation is correct, but maynot fit into Chinese habits, maybe
> 使用/实现 is better?
OK, use 使用。
>
>> +
>> +当一个变更集被应用时，所有的改变在发出OF_RECONFIG通知器之前被一次性应用到树上。这是
>> +为了让接收者在收到通知时看到一个完整的、一致的树的状态。
>> +
>> +一个变化集的顺序如下。
>> +
>> +1. of_changeset_init() - 初始化一个变更集。
>> +
>> +2. 一些DT树变化的调用，of_changeset_attach_node(), of_changeset_detach_node(),
>> + of_changeset_add_property(), of_changeset_remove_property,
>> + of_changeset_update_property()来准备一组变更。此时不会对活动树做任何变更。所有
>> + 的变更操作都记录在of_changeset的 `entries` 列表中。
>> +
>> +3. of_changeset_apply() - 将变更应用到树上。要么整个变更集被应用，要么如果有错误，
>> + 树会被恢复到之前的状态。核心通过锁确保正确的顺序。如果需要的话，可以使用一个解锁的
>> + __of_changeset_apply版本。
>> +
>> +如果一个成功应用的变更集需要被删除，可以用of_changeset_revert()来完成。
>> diff --git a/Documentation/translations/zh_CN/devicetree/index.rst b/Documentation/translations/zh_CN/devicetree/index.rst
>> index 3fc355fe0037..e9aff2ccc579 100644
>> --- a/Documentation/translations/zh_CN/devicetree/index.rst
>> +++ b/Documentation/translations/zh_CN/devicetree/index.rst
>> @@ -34,9 +34,10 @@ Devicetree Overlays
>> .. toctree::
>> :maxdepth: 1
>>
>> + changesets
>> +
>> Todolist:
>>
>> -* changesets
>> * dynamic-resolution-notes
>> * overlay-notes
>>
>> --
>> 2.31.1
>>
^ permalink raw reply [flat|nested] 16+ messages in thread
* [PATCH v1 3/5] docs/zh_CN: add dt dynamic-resolution-notes translation
2022-09-01 11:15 [PATCH v1 0/5] docs/zh_CN: Add some dt and PCI Chinese translation Yanteng Si
2022-09-01 11:15 ` [PATCH v1 1/5] docs/zh_CN: add PCI acpi-info translation Yanteng Si
2022-09-01 11:15 ` [PATCH v1 2/5] docs/zh_CN: add dt changesets translation Yanteng Si
@ 2022-09-01 11:15 ` Yanteng Si
2022-09-02 8:13 ` Alex Shi
2022-09-01 11:15 ` [PATCH v1 4/5] docs/zh_CN: add dt overlay-notes translation Yanteng Si
2022-09-01 11:15 ` [PATCH v1 5/5] docs/zh_CN: add dt kernel-api translation Yanteng Si
4 siblings, 1 reply; 16+ messages in thread
From: Yanteng Si @ 2022-09-01 11:15 UTC (permalink / raw)
To: alexs, bobwxc, seakeel
Cc: Yanteng Si, corbet, chenhuacai, jiaxun.yang, linux-doc, siyanteng01
Translate .../devicetree/dynamic-resolution-notes.rst into Chinese.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
.../devicetree/dynamic-resolution-notes.rst | 31 +++++++++++++++++++
.../translations/zh_CN/devicetree/index.rst | 2 +-
2 files changed, 32 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_CN/devicetree/dynamic-resolution-notes.rst
diff --git a/Documentation/translations/zh_CN/devicetree/dynamic-resolution-notes.rst b/Documentation/translations/zh_CN/devicetree/dynamic-resolution-notes.rst
new file mode 100644
index 000000000000..115190341305
--- /dev/null
+++ b/Documentation/translations/zh_CN/devicetree/dynamic-resolution-notes.rst
@@ -0,0 +1,31 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/Devicetree/dynamic-resolution-notes.rst
+
+:翻译:
+
+ 司延腾 Yanteng Si <siyanteng@loongson.cn>
+
+:校译:
+
+========================
+Devicetree动态解析器说明
+========================
+
+本文描述了内核内DeviceTree解析器的实现，它位于drivers/of/resolver.c中。
+
+解析器如何工作？
+----------------
+
+解析器被赋予一个任意的树作为输入，该树用适当的dtc选项编译，并有一个/plugin/标签。这就产
+生了适当的__fixups__和__local_fixups__节点。
+
+解析器依次通过以下步骤工作:
+
+1. 从实时树中获取最大的设备树phandle值 + 1.
+2. 调整树的所有本地 phandles，以解决这个量。
+3. 使用 __local__fixups__ 节点信息以相同的量调整所有本地引用。
+4. 对于__fixups__节点中的每个属性，找到它在实时树中引用的节点。这是用来标记该节点的标签。
+5. 检索fixup的目标的phandle。
+6. 对于属性中的每个fixup，找到节点:属性:偏移的位置，并用phandle值替换它。
diff --git a/Documentation/translations/zh_CN/devicetree/index.rst b/Documentation/translations/zh_CN/devicetree/index.rst
index e9aff2ccc579..be5b974c6e68 100644
--- a/Documentation/translations/zh_CN/devicetree/index.rst
+++ b/Documentation/translations/zh_CN/devicetree/index.rst
@@ -35,10 +35,10 @@ Devicetree Overlays
:maxdepth: 1
changesets
+ dynamic-resolution-notes
Todolist:
-* dynamic-resolution-notes
* overlay-notes
Devicetree Bindings
--
2.31.1
^ permalink raw reply related [flat|nested] 16+ messages in thread* Re: [PATCH v1 3/5] docs/zh_CN: add dt dynamic-resolution-notes translation
2022-09-01 11:15 ` [PATCH v1 3/5] docs/zh_CN: add dt dynamic-resolution-notes translation Yanteng Si
@ 2022-09-02 8:13 ` Alex Shi
0 siblings, 0 replies; 16+ messages in thread
From: Alex Shi @ 2022-09-02 8:13 UTC (permalink / raw)
To: Yanteng Si
Cc: Alex Shi, Wu X.C.,
Jonathan Corbet, Huacai Chen, Jiaxun Yang,
Linux Doc Mailing List, yanteng si
On Thu, Sep 1, 2022 at 7:16 PM Yanteng Si <siyanteng@loongson.cn> wrote:
>
> Translate .../devicetree/dynamic-resolution-notes.rst into Chinese.
>
> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
> ---
> .../devicetree/dynamic-resolution-notes.rst | 31 +++++++++++++++++++
> .../translations/zh_CN/devicetree/index.rst | 2 +-
> 2 files changed, 32 insertions(+), 1 deletion(-)
> create mode 100644 Documentation/translations/zh_CN/devicetree/dynamic-resolution-notes.rst
>
> diff --git a/Documentation/translations/zh_CN/devicetree/dynamic-resolution-notes.rst b/Documentation/translations/zh_CN/devicetree/dynamic-resolution-notes.rst
> new file mode 100644
> index 000000000000..115190341305
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/devicetree/dynamic-resolution-notes.rst
> @@ -0,0 +1,31 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/Devicetree/dynamic-resolution-notes.rst
> +
> +:翻译:
> +
> + 司延腾 Yanteng Si <siyanteng@loongson.cn>
> +
> +:校译:
> +
> +========================
> +Devicetree动态解析器说明
> +========================
> +
> +本文描述了内核内DeviceTree解析器的实现，它位于drivers/of/resolver.c中。
> +
> +解析器如何工作？
> +----------------
> +
> +解析器被赋予一个任意的树作为输入，该树用适当的dtc选项编译，并有一个/plugin/标签。这就产
> +生了适当的__fixups__和__local_fixups__节点。
> +
> +解析器依次通过以下步骤工作:
> +
> +1. 从实时树中获取最大的设备树phandle值 + 1.
> +2. 调整树的所有本地 phandles，以解决这个量。
> +3. 使用 __local__fixups__ 节点信息以相同的量调整所有本地引用。
> +4. 对于__fixups__节点中的每个属性，找到它在实时树中引用的节点。这是用来标记该节点的标签。
> +5. 检索fixup的目标的phandle。
> +6. 对于属性中的每个fixup，找到节点:属性:偏移的位置，并用phandle值替换它。
> diff --git a/Documentation/translations/zh_CN/devicetree/index.rst b/Documentation/translations/zh_CN/devicetree/index.rst
> index e9aff2ccc579..be5b974c6e68 100644
> --- a/Documentation/translations/zh_CN/devicetree/index.rst
> +++ b/Documentation/translations/zh_CN/devicetree/index.rst
> @@ -35,10 +35,10 @@ Devicetree Overlays
> :maxdepth: 1
>
> changesets
> + dynamic-resolution-notes
>
> Todolist:
>
> -* dynamic-resolution-notes
> * overlay-notes
>
> Devicetree Bindings
> --
> 2.31.1
>
^ permalink raw reply [flat|nested] 16+ messages in thread
* [PATCH v1 4/5] docs/zh_CN: add dt overlay-notes translation
2022-09-01 11:15 [PATCH v1 0/5] docs/zh_CN: Add some dt and PCI Chinese translation Yanteng Si
` (2 preceding siblings ...)
2022-09-01 11:15 ` [PATCH v1 3/5] docs/zh_CN: add dt dynamic-resolution-notes translation Yanteng Si
@ 2022-09-01 11:15 ` Yanteng Si
2022-09-02 8:23 ` Alex Shi
2022-09-01 11:15 ` [PATCH v1 5/5] docs/zh_CN: add dt kernel-api translation Yanteng Si
4 siblings, 1 reply; 16+ messages in thread
From: Yanteng Si @ 2022-09-01 11:15 UTC (permalink / raw)
To: alexs, bobwxc, seakeel
Cc: Yanteng Si, corbet, chenhuacai, jiaxun.yang, linux-doc, siyanteng01
Translate .../devicetree/overlay-notes.rst into Chinese.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
.../translations/zh_CN/devicetree/index.rst | 5 +-
.../zh_CN/devicetree/overlay-notes.rst | 140 ++++++++++++++++++
2 files changed, 141 insertions(+), 4 deletions(-)
create mode 100644 Documentation/translations/zh_CN/devicetree/overlay-notes.rst
diff --git a/Documentation/translations/zh_CN/devicetree/index.rst b/Documentation/translations/zh_CN/devicetree/index.rst
index be5b974c6e68..9d95d2629b38 100644
--- a/Documentation/translations/zh_CN/devicetree/index.rst
+++ b/Documentation/translations/zh_CN/devicetree/index.rst
@@ -36,10 +36,7 @@ Devicetree Overlays
changesets
dynamic-resolution-notes
-
-Todolist:
-
-* overlay-notes
+ overlay-notes
Devicetree Bindings
===================
diff --git a/Documentation/translations/zh_CN/devicetree/overlay-notes.rst b/Documentation/translations/zh_CN/devicetree/overlay-notes.rst
new file mode 100644
index 000000000000..572ddaf729a8
--- /dev/null
+++ b/Documentation/translations/zh_CN/devicetree/overlay-notes.rst
@@ -0,0 +1,140 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/Devicetree/overlay-notes.rst
+
+:翻译:
+
+ 司延腾 Yanteng Si <siyanteng@loongson.cn>
+
+:校译:
+
+==============
+设备树覆盖说明
+==============
+
+本文档描述了drivers/of/overlay.c中的内核内设备树覆盖功能的实现，是
+Documentation/devicetree/dynamic-resolution-notes.rst[1]的配套文档。
+
+覆盖如何工作
+------------
+
+设备树的覆盖目的是修改内核的实时树，并让修改影响内核的状态，以反映变化的方式。
+由于内核主要处理的是设备，任何新的设备节点如果导致一个活动的设备，就应该创建它，
+而如果设备节点被禁用或被全部删除，受影响的设备应该被取消注册。
+
+让我们举个例子，我们有一个foo板，它的基本树形图如下::
+
+ ---- foo.dts ---------------------------------------------------------------
+ /* FOO平台 */
+ /dts-v1/;
+ / {
+ compatible = "corp,foo";
+
+ /* 共享的资源 */
+ res: res {
+ };
+
+ /* 芯片上的外围设备 */
+ ocp: ocp {
+ /* 总是被实例化的外围设备 */
+ peripheral1 { ... };
+ };
+ };
+ ---- foo.dts ---------------------------------------------------------------
+
+覆盖bar.dts,
+::
+
+ ---- bar.dts - 按标签覆盖目标位置 ----------------------------
+ /dts-v1/;
+ /插件/;
+ &ocp {
+ /* bar外围 */
+ bar {
+ compatible = "corp,bar";
+ ... /* 各种属性和子节点 */
+ };
+ };
+ ---- bar.dts ---------------------------------------------------------------
+
+当加载（并按照[1]中描述的方式解决）时，应该产生foo+bar.dts::
+
+ ---- foo+bar.dts -----------------------------------------------------------
+ /* FOO平台 + bar外围 */
+ / {
+ compatible = "corp,foo";
+
+ /* 共享资源 */
+ res: res {
+ };
+
+ /* 芯片上的外围设备 */
+ ocp: ocp {
+ /* 总是被实例化的外围设备 */
+ peripheral1 { ... };
+
+ /* bar外围 */
+ bar {
+ compatible = "corp,bar";
+ ... /* 各种属性和子节点 */
+ };
+ };
+ };
+ ---- foo+bar.dts -----------------------------------------------------------
+
+作为覆盖的结果，已经创建了一个新的设备节点（bar），因此将注册一个bar平台设备，
+如果加载了匹配的设备驱动程序，将按预期创建设备。
+
+如果基础DT不是用-@选项编译的，那么“&ocp”标签将不能用于将覆盖节点解析到基础
+DT中的适当位置。在这种情况下，可以提供目标路径。通过标签的目标位置的语法是比
+较好的，因为不管标签在DT中出现在哪里，覆盖都可以被应用到任何包含标签的基础DT上。
+
+上面的bar.dts例子被修改为使用目标路径语法，即为::
+
+ ---- bar.dts - 通过明确的路径覆盖目标位置 --------------------
+ /dts-v1/;
+ /插件/;
+ &{/ocp} {
+ /* bar外围 */
+ bar {
+ compatible = "corp,bar";
+ ... /* 各种外围设备和子节点 */
+ }
+ };
+ ---- bar.dts ---------------------------------------------------------------
+
+
+内核中关于覆盖的API
+-------------------
+
+该API相当容易使用。
+
+1) 调用of_overlay_fdt_apply()来创建和应用一个覆盖的变更集。返回值是一个
+ 错误或一个识别这个覆盖的cookie。
+
+2) 调用of_overlay_remove()来删除和清理先前通过调用of_overlay_fdt_apply()
+ 而创建的覆盖变更集。不允许删除一个被另一个覆盖的覆盖变化集。
+
+最后，如果你需要一次性删除所有的覆盖，只需调用of_overlay_remove_all()，
+它将以正确的顺序删除每一个覆盖。
+
+你可以选择注册在覆盖操作中被调用的通知器。详见
+of_overlay_notifier_register/unregister和enum of_overlay_notify_action。
+
+OF_OVERLAY_PRE_APPLY、OF_OVERLAY_POST_APPLY或OF_OVERLAY_PRE_REMOVE
+的通知器回调可以存储指向覆盖层中的设备树节点或其内容的指针，但这些指针不能持
+续到OF_OVERLAY_POST_REMOVE的通知器回调。在OF_OVERLAY_POST_REMOVE通
+知器被调用后，包含覆盖层的内存将被kfree()ed。请注意，即使OF_OVERLAY_POST_REMOVE
+的通知器返回错误，内存也会被kfree()ed。
+
+drivers/of/dynamic.c中的变更集通知器是第二种类型的通知器，可以通过应用或移除
+覆盖层来触发。这些通知器不允许在覆盖层或其内容中存储指向设备树节点的指针。当包含
+覆盖层的内存因移除覆盖层而被释放时，覆盖层代码并不能防止这类指针仍然有效。
+
+任何其他保留指向覆盖层节点或数据的指针的代码都被认为是一个错误，因为在移除覆盖层
+后，该指针将指向已释放的内存。
+
+覆盖层的用户必须特别注意系统上发生的整体操作，以确保其他内核代码不保留任何指向覆
+盖层节点或数据的指针。任何无意中使用这种指针的例子是，如果一个驱动或子系统模块在
+应用了覆盖后被加载，并且该驱动或子系统扫描了整个设备树或其大部分，包括覆盖节点。
--
2.31.1
^ permalink raw reply related [flat|nested] 16+ messages in thread* Re: [PATCH v1 4/5] docs/zh_CN: add dt overlay-notes translation
2022-09-01 11:15 ` [PATCH v1 4/5] docs/zh_CN: add dt overlay-notes translation Yanteng Si
@ 2022-09-02 8:23 ` Alex Shi
2022-09-05 12:05 ` YanTeng Si
0 siblings, 1 reply; 16+ messages in thread
From: Alex Shi @ 2022-09-02 8:23 UTC (permalink / raw)
To: Yanteng Si
Cc: Alex Shi, Wu X.C.,
Jonathan Corbet, Huacai Chen, Jiaxun Yang,
Linux Doc Mailing List, yanteng si
On Thu, Sep 1, 2022 at 7:16 PM Yanteng Si <siyanteng@loongson.cn> wrote:
>
> Translate .../devicetree/overlay-notes.rst into Chinese.
>
> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> ---
> .../translations/zh_CN/devicetree/index.rst | 5 +-
> .../zh_CN/devicetree/overlay-notes.rst | 140 ++++++++++++++++++
> 2 files changed, 141 insertions(+), 4 deletions(-)
> create mode 100644 Documentation/translations/zh_CN/devicetree/overlay-notes.rst
>
> diff --git a/Documentation/translations/zh_CN/devicetree/index.rst b/Documentation/translations/zh_CN/devicetree/index.rst
> index be5b974c6e68..9d95d2629b38 100644
> --- a/Documentation/translations/zh_CN/devicetree/index.rst
> +++ b/Documentation/translations/zh_CN/devicetree/index.rst
> @@ -36,10 +36,7 @@ Devicetree Overlays
>
> changesets
> dynamic-resolution-notes
> -
> -Todolist:
> -
> -* overlay-notes
> + overlay-notes
>
> Devicetree Bindings
> ===================
> diff --git a/Documentation/translations/zh_CN/devicetree/overlay-notes.rst b/Documentation/translations/zh_CN/devicetree/overlay-notes.rst
> new file mode 100644
> index 000000000000..572ddaf729a8
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/devicetree/overlay-notes.rst
> @@ -0,0 +1,140 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/Devicetree/overlay-notes.rst
> +
> +:翻译:
> +
> + 司延腾 Yanteng Si <siyanteng@loongson.cn>
> +
> +:校译:
> +
> +==============
> +设备树覆盖说明
> +==============
> +
> +本文档描述了drivers/of/overlay.c中的内核内设备树覆盖功能的实现，是
> +Documentation/devicetree/dynamic-resolution-notes.rst[1]的配套文档。
> +
> +覆盖如何工作
> +------------
> +
> +设备树的覆盖目的是修改内核的实时树，并让修改影响内核的状态，以反映变化的方式。
xxx 目的是 xxx 方式？
> +由于内核主要处理的是设备，任何新的设备节点如果导致一个活动的设备，就应该创建它，
> +而如果设备节点被禁用或被全部删除，受影响的设备应该被取消注册。
> +
> +让我们举个例子，我们有一个foo板，它的基本树形图如下::
> +
> + ---- foo.dts ---------------------------------------------------------------
> + /* FOO平台 */
> + /dts-v1/;
> + / {
> + compatible = "corp,foo";
> +
> + /* 共享的资源 */
> + res: res {
> + };
> +
> + /* 芯片上的外围设备 */
> + ocp: ocp {
> + /* 总是被实例化的外围设备 */
> + peripheral1 { ... };
> + };
> + };
> + ---- foo.dts ---------------------------------------------------------------
> +
> +覆盖bar.dts,
> +::
> +
> + ---- bar.dts - 按标签覆盖目标位置 ----------------------------
> + /dts-v1/;
> + /插件/;
> + &ocp {
> + /* bar外围 */
> + bar {
> + compatible = "corp,bar";
> + ... /* 各种属性和子节点 */
> + };
> + };
> + ---- bar.dts ---------------------------------------------------------------
> +
> +当加载（并按照[1]中描述的方式解决）时，应该产生foo+bar.dts::
> +
> + ---- foo+bar.dts -----------------------------------------------------------
> + /* FOO平台 + bar外围 */
> + / {
> + compatible = "corp,foo";
> +
> + /* 共享资源 */
> + res: res {
> + };
> +
> + /* 芯片上的外围设备 */
> + ocp: ocp {
> + /* 总是被实例化的外围设备 */
> + peripheral1 { ... };
> +
> + /* bar外围 */
> + bar {
> + compatible = "corp,bar";
> + ... /* 各种属性和子节点 */
> + };
> + };
> + };
> + ---- foo+bar.dts -----------------------------------------------------------
> +
> +作为覆盖的结果，已经创建了一个新的设备节点（bar），因此将注册一个bar平台设备，
> +如果加载了匹配的设备驱动程序，将按预期创建设备。
> +
> +如果基础DT不是用-@选项编译的，那么“&ocp”标签将不能用于将覆盖节点解析到基础
> +DT中的适当位置。在这种情况下，可以提供目标路径。通过标签的目标位置的语法是比
> +较好的，因为不管标签在DT中出现在哪里，覆盖都可以被应用到任何包含标签的基础DT上。
> +
> +上面的bar.dts例子被修改为使用目标路径语法，即为::
> +
> + ---- bar.dts - 通过明确的路径覆盖目标位置 --------------------
> + /dts-v1/;
> + /插件/;
> + &{/ocp} {
> + /* bar外围 */
> + bar {
> + compatible = "corp,bar";
> + ... /* 各种外围设备和子节点 */
> + }
> + };
> + ---- bar.dts ---------------------------------------------------------------
> +
> +
> +内核中关于覆盖的API
> +-------------------
> +
> +该API相当容易使用。
> +
> +1) 调用of_overlay_fdt_apply()来创建和应用一个覆盖的变更集。返回值是一个
> + 错误或一个识别这个覆盖的cookie。
> +
> +2) 调用of_overlay_remove()来删除和清理先前通过调用of_overlay_fdt_apply()
> + 而创建的覆盖变更集。不允许删除一个被另一个覆盖的覆盖变化集。
变化集 ==> 变更集？ although, still hard to understand in Chinese for the sentense.
> +
> +最后，如果你需要一次性删除所有的覆盖，只需调用of_overlay_remove_all()，
> +它将以正确的顺序删除每一个覆盖。
覆盖 ==> 覆盖层 ？
> +
> +你可以选择注册在覆盖操作中被调用的通知器。详见
> +of_overlay_notifier_register/unregister和enum of_overlay_notify_action。
> +
> +OF_OVERLAY_PRE_APPLY、OF_OVERLAY_POST_APPLY或OF_OVERLAY_PRE_REMOVE
> +的通知器回调可以存储指向覆盖层中的设备树节点或其内容的指针，但这些指针不能持
> +续到OF_OVERLAY_POST_REMOVE的通知器回调。在OF_OVERLAY_POST_REMOVE通
指针持续 => 指针存活？
Thanks
Alex
> +知器被调用后，包含覆盖层的内存将被kfree()ed。请注意，即使OF_OVERLAY_POST_REMOVE
> +的通知器返回错误，内存也会被kfree()ed。
> +
> +drivers/of/dynamic.c中的变更集通知器是第二种类型的通知器，可以通过应用或移除
> +覆盖层来触发。这些通知器不允许在覆盖层或其内容中存储指向设备树节点的指针。当包含
> +覆盖层的内存因移除覆盖层而被释放时，覆盖层代码并不能防止这类指针仍然有效。
> +
> +任何其他保留指向覆盖层节点或数据的指针的代码都被认为是一个错误，因为在移除覆盖层
> +后，该指针将指向已释放的内存。
> +
> +覆盖层的用户必须特别注意系统上发生的整体操作，以确保其他内核代码不保留任何指向覆
> +盖层节点或数据的指针。任何无意中使用这种指针的例子是，如果一个驱动或子系统模块在
> +应用了覆盖后被加载，并且该驱动或子系统扫描了整个设备树或其大部分，包括覆盖节点。
> --
> 2.31.1
>
^ permalink raw reply [flat|nested] 16+ messages in thread* Re: [PATCH v1 4/5] docs/zh_CN: add dt overlay-notes translation
2022-09-02 8:23 ` Alex Shi
@ 2022-09-05 12:05 ` YanTeng Si
0 siblings, 0 replies; 16+ messages in thread
From: YanTeng Si @ 2022-09-05 12:05 UTC (permalink / raw)
To: Alex Shi
Cc: Alex Shi, Wu X.C.,
Jonathan Corbet, Huacai Chen, Jiaxun Yang,
Linux Doc Mailing List, yanteng si
在 2022/9/2 16:23, Alex Shi 写道:
> On Thu, Sep 1, 2022 at 7:16 PM Yanteng Si <siyanteng@loongson.cn> wrote:
>> Translate .../devicetree/overlay-notes.rst into Chinese.
>>
>> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
>> ---
>> .../translations/zh_CN/devicetree/index.rst | 5 +-
>> .../zh_CN/devicetree/overlay-notes.rst | 140 ++++++++++++++++++
>> 2 files changed, 141 insertions(+), 4 deletions(-)
>> create mode 100644 Documentation/translations/zh_CN/devicetree/overlay-notes.rst
>>
>> diff --git a/Documentation/translations/zh_CN/devicetree/index.rst b/Documentation/translations/zh_CN/devicetree/index.rst
>> index be5b974c6e68..9d95d2629b38 100644
>> --- a/Documentation/translations/zh_CN/devicetree/index.rst
>> +++ b/Documentation/translations/zh_CN/devicetree/index.rst
>> @@ -36,10 +36,7 @@ Devicetree Overlays
>>
>> changesets
>> dynamic-resolution-notes
>> -
>> -Todolist:
>> -
>> -* overlay-notes
>> + overlay-notes
>>
>> Devicetree Bindings
>> ===================
>> diff --git a/Documentation/translations/zh_CN/devicetree/overlay-notes.rst b/Documentation/translations/zh_CN/devicetree/overlay-notes.rst
>> new file mode 100644
>> index 000000000000..572ddaf729a8
>> --- /dev/null
>> +++ b/Documentation/translations/zh_CN/devicetree/overlay-notes.rst
>> @@ -0,0 +1,140 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +.. include:: ../disclaimer-zh_CN.rst
>> +
>> +:Original: Documentation/Devicetree/overlay-notes.rst
>> +
>> +:翻译:
>> +
>> + 司延腾 Yanteng Si <siyanteng@loongson.cn>
>> +
>> +:校译:
>> +
>> +==============
>> +设备树覆盖说明
>> +==============
>> +
>> +本文档描述了drivers/of/overlay.c中的内核内设备树覆盖功能的实现，是
>> +Documentation/devicetree/dynamic-resolution-notes.rst[1]的配套文档。
>> +
>> +覆盖如何工作
>> +------------
>> +
>> +设备树的覆盖目的是修改内核的实时树，并让修改影响内核的状态，以反映变化的方式。
> xxx 目的是 xxx 方式？
设备树覆盖的目的是修改内核的实时树，并使修改以反映变化的方式影响内核的状态。
Thanks,
Yanteng
>
>> +由于内核主要处理的是设备，任何新的设备节点如果导致一个活动的设备，就应该创建它，
>> +而如果设备节点被禁用或被全部删除，受影响的设备应该被取消注册。
>> +
>> +让我们举个例子，我们有一个foo板，它的基本树形图如下::
>> +
>> + ---- foo.dts ---------------------------------------------------------------
>> + /* FOO平台 */
>> + /dts-v1/;
>> + / {
>> + compatible = "corp,foo";
>> +
>> + /* 共享的资源 */
>> + res: res {
>> + };
>> +
>> + /* 芯片上的外围设备 */
>> + ocp: ocp {
>> + /* 总是被实例化的外围设备 */
>> + peripheral1 { ... };
>> + };
>> + };
>> + ---- foo.dts ---------------------------------------------------------------
>> +
>> +覆盖bar.dts,
>> +::
>> +
>> + ---- bar.dts - 按标签覆盖目标位置 ----------------------------
>> + /dts-v1/;
>> + /插件/;
>> + &ocp {
>> + /* bar外围 */
>> + bar {
>> + compatible = "corp,bar";
>> + ... /* 各种属性和子节点 */
>> + };
>> + };
>> + ---- bar.dts ---------------------------------------------------------------
>> +
>> +当加载（并按照[1]中描述的方式解决）时，应该产生foo+bar.dts::
>> +
>> + ---- foo+bar.dts -----------------------------------------------------------
>> + /* FOO平台 + bar外围 */
>> + / {
>> + compatible = "corp,foo";
>> +
>> + /* 共享资源 */
>> + res: res {
>> + };
>> +
>> + /* 芯片上的外围设备 */
>> + ocp: ocp {
>> + /* 总是被实例化的外围设备 */
>> + peripheral1 { ... };
>> +
>> + /* bar外围 */
>> + bar {
>> + compatible = "corp,bar";
>> + ... /* 各种属性和子节点 */
>> + };
>> + };
>> + };
>> + ---- foo+bar.dts -----------------------------------------------------------
>> +
>> +作为覆盖的结果，已经创建了一个新的设备节点（bar），因此将注册一个bar平台设备，
>> +如果加载了匹配的设备驱动程序，将按预期创建设备。
>> +
>> +如果基础DT不是用-@选项编译的，那么“&ocp”标签将不能用于将覆盖节点解析到基础
>> +DT中的适当位置。在这种情况下，可以提供目标路径。通过标签的目标位置的语法是比
>> +较好的，因为不管标签在DT中出现在哪里，覆盖都可以被应用到任何包含标签的基础DT上。
>> +
>> +上面的bar.dts例子被修改为使用目标路径语法，即为::
>> +
>> + ---- bar.dts - 通过明确的路径覆盖目标位置 --------------------
>> + /dts-v1/;
>> + /插件/;
>> + &{/ocp} {
>> + /* bar外围 */
>> + bar {
>> + compatible = "corp,bar";
>> + ... /* 各种外围设备和子节点 */
>> + }
>> + };
>> + ---- bar.dts ---------------------------------------------------------------
>> +
>> +
>> +内核中关于覆盖的API
>> +-------------------
>> +
>> +该API相当容易使用。
>> +
>> +1) 调用of_overlay_fdt_apply()来创建和应用一个覆盖的变更集。返回值是一个
>> + 错误或一个识别这个覆盖的cookie。
>> +
>> +2) 调用of_overlay_remove()来删除和清理先前通过调用of_overlay_fdt_apply()
>> + 而创建的覆盖变更集。不允许删除一个被另一个覆盖的覆盖变化集。
> 变化集 ==> 变更集？ although, still hard to understand in Chinese for the sentense.
>
>> +
>> +最后，如果你需要一次性删除所有的覆盖，只需调用of_overlay_remove_all()，
>> +它将以正确的顺序删除每一个覆盖。
> 覆盖 ==> 覆盖层 ？
>
>> +
>> +你可以选择注册在覆盖操作中被调用的通知器。详见
>> +of_overlay_notifier_register/unregister和enum of_overlay_notify_action。
>> +
>> +OF_OVERLAY_PRE_APPLY、OF_OVERLAY_POST_APPLY或OF_OVERLAY_PRE_REMOVE
>> +的通知器回调可以存储指向覆盖层中的设备树节点或其内容的指针，但这些指针不能持
>> +续到OF_OVERLAY_POST_REMOVE的通知器回调。在OF_OVERLAY_POST_REMOVE通
> 指针持续 => 指针存活？
>
> Thanks
> Alex
>
>> +知器被调用后，包含覆盖层的内存将被kfree()ed。请注意，即使OF_OVERLAY_POST_REMOVE
>> +的通知器返回错误，内存也会被kfree()ed。
>> +
>> +drivers/of/dynamic.c中的变更集通知器是第二种类型的通知器，可以通过应用或移除
>> +覆盖层来触发。这些通知器不允许在覆盖层或其内容中存储指向设备树节点的指针。当包含
>> +覆盖层的内存因移除覆盖层而被释放时，覆盖层代码并不能防止这类指针仍然有效。
>> +
>> +任何其他保留指向覆盖层节点或数据的指针的代码都被认为是一个错误，因为在移除覆盖层
>> +后，该指针将指向已释放的内存。
>> +
>> +覆盖层的用户必须特别注意系统上发生的整体操作，以确保其他内核代码不保留任何指向覆
>> +盖层节点或数据的指针。任何无意中使用这种指针的例子是，如果一个驱动或子系统模块在
>> +应用了覆盖后被加载，并且该驱动或子系统扫描了整个设备树或其大部分，包括覆盖节点。
>> --
>> 2.31.1
>>
^ permalink raw reply [flat|nested] 16+ messages in thread
* [PATCH v1 5/5] docs/zh_CN: add dt kernel-api translation
2022-09-01 11:15 [PATCH v1 0/5] docs/zh_CN: Add some dt and PCI Chinese translation Yanteng Si
` (3 preceding siblings ...)
2022-09-01 11:15 ` [PATCH v1 4/5] docs/zh_CN: add dt overlay-notes translation Yanteng Si
@ 2022-09-01 11:15 ` Yanteng Si
2022-09-02 8:29 ` Alex Shi
4 siblings, 1 reply; 16+ messages in thread
From: Yanteng Si @ 2022-09-01 11:15 UTC (permalink / raw)
To: alexs, bobwxc, seakeel
Cc: Yanteng Si, corbet, chenhuacai, jiaxun.yang, linux-doc, siyanteng01
Translte .../devicetree/kernel-api.rst into Chinese.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
.../translations/zh_CN/devicetree/index.rst | 5 +-
.../zh_CN/devicetree/kernel-api.rst | 58 +++++++++++++++++++
2 files changed, 59 insertions(+), 4 deletions(-)
create mode 100644 Documentation/translations/zh_CN/devicetree/kernel-api.rst
diff --git a/Documentation/translations/zh_CN/devicetree/index.rst b/Documentation/translations/zh_CN/devicetree/index.rst
index 9d95d2629b38..7451dbfdd3e5 100644
--- a/Documentation/translations/zh_CN/devicetree/index.rst
+++ b/Documentation/translations/zh_CN/devicetree/index.rst
@@ -24,10 +24,7 @@ Open Firmware 和 Devicetree
usage-model
of_unittest
-
-Todolist:
-
-* kernel-api
+ kernel-api
Devicetree Overlays
===================
diff --git a/Documentation/translations/zh_CN/devicetree/kernel-api.rst b/Documentation/translations/zh_CN/devicetree/kernel-api.rst
new file mode 100644
index 000000000000..6aa3b685494e
--- /dev/null
+++ b/Documentation/translations/zh_CN/devicetree/kernel-api.rst
@@ -0,0 +1,58 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/Devicetree/kernel-api.rst
+
+:翻译:
+
+ 司延腾 Yanteng Si <siyanteng@loongson.cn>
+
+:校译:
+
+
+=================
+内核中的设备树API
+=================
+
+核心函数
+--------
+
+该API在以下内核代码中:
+
+drivers/of/base.c
+
+include/linux/of.h
+
+drivers/of/property.c
+
+include/linux/of_graph.h
+
+drivers/of/address.c
+
+drivers/of/irq.c
+
+drivers/of/fdt.c
+
+驱动模型函数
+------------
+
+该API在以下内核代码中:
+
+include/linux/of_device.h
+
+drivers/of/device.c
+
+include/linux/of_platform.h
+
+drivers/of/platform.c
+
+覆盖和动态DT函数
+----------------
+
+该API在以下内核代码中:
+
+drivers/of/resolver.c
+
+drivers/of/dynamic.c
+
+drivers/of/overlay.c
--
2.31.1
^ permalink raw reply related [flat|nested] 16+ messages in thread* Re: [PATCH v1 5/5] docs/zh_CN: add dt kernel-api translation
2022-09-01 11:15 ` [PATCH v1 5/5] docs/zh_CN: add dt kernel-api translation Yanteng Si
@ 2022-09-02 8:29 ` Alex Shi
0 siblings, 0 replies; 16+ messages in thread
From: Alex Shi @ 2022-09-02 8:29 UTC (permalink / raw)
To: Yanteng Si
Cc: Alex Shi, Wu X.C.,
Jonathan Corbet, Huacai Chen, Jiaxun Yang,
Linux Doc Mailing List, yanteng si
On Thu, Sep 1, 2022 at 7:16 PM Yanteng Si <siyanteng@loongson.cn> wrote:
>
> Translte .../devicetree/kernel-api.rst into Chinese.
>
> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Uh, no much useful info.
Reviewed-by: Alex Shi <alexs@kernel.org>
> ---
> .../translations/zh_CN/devicetree/index.rst | 5 +-
> .../zh_CN/devicetree/kernel-api.rst | 58 +++++++++++++++++++
> 2 files changed, 59 insertions(+), 4 deletions(-)
> create mode 100644 Documentation/translations/zh_CN/devicetree/kernel-api.rst
>
> diff --git a/Documentation/translations/zh_CN/devicetree/index.rst b/Documentation/translations/zh_CN/devicetree/index.rst
> index 9d95d2629b38..7451dbfdd3e5 100644
> --- a/Documentation/translations/zh_CN/devicetree/index.rst
> +++ b/Documentation/translations/zh_CN/devicetree/index.rst
> @@ -24,10 +24,7 @@ Open Firmware 和 Devicetree
>
> usage-model
> of_unittest
> -
> -Todolist:
> -
> -* kernel-api
> + kernel-api
>
> Devicetree Overlays
> ===================
> diff --git a/Documentation/translations/zh_CN/devicetree/kernel-api.rst b/Documentation/translations/zh_CN/devicetree/kernel-api.rst
> new file mode 100644
> index 000000000000..6aa3b685494e
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/devicetree/kernel-api.rst
> @@ -0,0 +1,58 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/Devicetree/kernel-api.rst
> +
> +:翻译:
> +
> + 司延腾 Yanteng Si <siyanteng@loongson.cn>
> +
> +:校译:
> +
> +
> +=================
> +内核中的设备树API
> +=================
> +
> +核心函数
> +--------
> +
> +该API在以下内核代码中:
> +
> +drivers/of/base.c
> +
> +include/linux/of.h
> +
> +drivers/of/property.c
> +
> +include/linux/of_graph.h
> +
> +drivers/of/address.c
> +
> +drivers/of/irq.c
> +
> +drivers/of/fdt.c
> +
> +驱动模型函数
> +------------
> +
> +该API在以下内核代码中:
> +
> +include/linux/of_device.h
> +
> +drivers/of/device.c
> +
> +include/linux/of_platform.h
> +
> +drivers/of/platform.c
> +
> +覆盖和动态DT函数
> +----------------
> +
> +该API在以下内核代码中:
> +
> +drivers/of/resolver.c
> +
> +drivers/of/dynamic.c
> +
> +drivers/of/overlay.c
> --
> 2.31.1
>
^ permalink raw reply [flat|nested] 16+ messages in thread