Re: [PATCH] docs/zh_CN: Add driver-api phy translation

[si.yanteng@linux.dev]

2024年6月18日 22:32, "Dongliang Mu" <mudongliangabcd@gmail.com> 写到:



> 
> On Tue, Jun 18, 2024 at 10:13 PM Yanteng Si <siyanteng@loongson.cn> wrote:
> 
> > 
> > Translate driver-api/phy.rst into Chinese.
> > 
> >  commit d02aa181ee59 ("phy: Add devm_of_phy_optional_get() helper")
> > 
> >  Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> > 
> >  ---
> > 
> >  .../translations/zh_CN/driver-api/index.rst | 2 +-
> > 
> >  .../zh_CN/driver-api/phy/index.rst | 21 ++
> > 
> >  .../translations/zh_CN/driver-api/phy/phy.rst | 213 ++++++++++++++++++
> > 
> >  3 files changed, 235 insertions(+), 1 deletion(-)
> > 
> >  create mode 100644 Documentation/translations/zh_CN/driver-api/phy/index.rst
> > 
> >  create mode 100644 Documentation/translations/zh_CN/driver-api/phy/phy.rst
> > 
> >  diff --git a/Documentation/translations/zh_CN/driver-api/index.rst b/Documentation/translations/zh_CN/driver-api/index.rst
> > 
> >  index 92ff1b7fc3d3..4050a2fb51c6 100644
> > 
> >  --- a/Documentation/translations/zh_CN/driver-api/index.rst
> > 
> >  +++ b/Documentation/translations/zh_CN/driver-api/index.rst
> > 
> >  @@ -23,6 +23,7 @@ Linux驱动实现者的API指南
> > 
> >  gpio/index
> > 
> >  io_ordering
> > 
> >  + phy/index
> > 
> >  Todolist:
> > 
> >  @@ -103,7 +104,6 @@ Todolist:
> > 
> >  * parport-lowlevel
> > 
> >  * pps
> > 
> >  * ptp
> > 
> >  -* phy/index
> > 
> >  * pwm
> > 
> >  * pldmfw/index
> > 
> >  * rfkill
> > 
> >  diff --git a/Documentation/translations/zh_CN/driver-api/phy/index.rst b/Documentation/translations/zh_CN/driver-api/phy/index.rst
> > 
> >  new file mode 100644
> > 
> >  index 000000000000..ba3f570e894f
> > 
> >  --- /dev/null
> > 
> >  +++ b/Documentation/translations/zh_CN/driver-api/phy/index.rst
> > 
> >  @@ -0,0 +1,21 @@
> > 
> >  +.. SPDX-License-Identifier: GPL-2.0
> > 
> >  +
> > 
> >  +============
> > 
> >  +PHY 公共框架
> > 
> >  +============
> > 
> 
> 这里是不是翻译为 PHY通用框架更好些？
OK.
> 
> > 
> > +
> > 
> >  +.. toctree::
> > 
> >  +
> > 
> >  + phy
> > 
> >  +
> > 
> >  +Todolist:
> > 
> >  +
> > 
> >  +* samsung-usb2
> > 
> >  +
> > 
> >  +.. only:: subproject and html
> > 
> >  +
> > 
> >  + Indices
> > 
> >  + =======
> > 
> >  +
> > 
> >  + * :ref:`genindex`
> > 
> >  +
> > 
> >  diff --git a/Documentation/translations/zh_CN/driver-api/phy/phy.rst b/Documentation/translations/zh_CN/driver-api/phy/phy.rst
> > 
> >  new file mode 100644
> > 
> >  index 000000000000..ed13b53182c4
> > 
> >  --- /dev/null
> > 
> >  +++ b/Documentation/translations/zh_CN/driver-api/phy/phy.rst
> > 
> >  @@ -0,0 +1,213 @@
> > 
> >  +.. SPDX-License-Identifier: GPL-2.0
> > 
> >  +.. include:: ../../disclaimer-zh_CN.rst
> > 
> >  +
> > 
> >  +:Original: Documentation/driver-api/phy/phy.rst
> > 
> >  +
> > 
> >  +:翻译:
> > 
> >  +
> > 
> >  + 司延腾 Yanteng Si <siyanteng@loongson.cn>
> > 
> >  +
> > 
> >  +=========
> > 
> >  +PHY子系统
> > 
> >  +=========
> > 
> >  +
> > 
> >  +:作者: Kishon Vijay Abraham I <kishon@ti.com>
> > 
> >  +
> > 
> >  +本文档解释了 PHY 的公共框架和提供的api，以及如何使用。
> > 
> 
> ditto
> 
> 同时，建议 API 都用大写，全文保持一致。
> 
> how-to-use 建议翻译为 “使用方法”，否则不太通顺。
OK.
> 
> > 
> > +
> > 
> >  +简介
> > 
> >  +====
> > 
> >  +
> > 
> >  +*PHY* 是物理层的缩写，它被用来把设备连接到一个物理媒介，例如USB控制器
> > 
> >  +有一个提供序列化、反序列化、编码、解码和负责获取所需的数据传输速率的 PHY。
> > 
> >  +注意，有些USB控制器内嵌了 PHY 的功能，其它的则使用了一个外置的PHY，此外
> > 
> >  +使用 PHY 的设备还有无线网、以太网、SATA等（控制器）。
> > 
> >  +
> > 
> >  +创建这个框架的目的是将遍布 Linux 内核的 PHY 驱动程序融入到 drivers/phy，
> > 
> >  +以增加代码复用性，进而提高代码的可维护性。
> > 
> 
> "复用性" -> "可复用性"
ok.
以增加代码的可复用性,
> 
> > 
> > +
> > 
> >  +该框架仅适用于使用外部 PHY（PHY 功能未嵌入控制器内）的设备。
> > 
> >  +
> > 
> >  +注册/注销PHY provider
> > 
> >  +=====================
> > 
> >  +
> > 
> >  +PHY provider是指实现一个或多个 PHY 实例的实体。对于 PHY provider 仅
> > 
> >  +实现单个 PHY 实例的简单情况，框架在 of_phy_simple_xlate 中提供其自己
> > 
> >  +的 of_xlate 实现。如果 PHY provider 实现多个实例，则应提供其自己的
> > 
> >  +of_xlate 实现。of_xlate 仅用于 dt 启动情况。
> > 
> >  +
> > 
> >  +::
> > 
> >  +
> > 
> >  + #define of_phy_provider_register(dev, xlate) \
> > 
> >  + __of_phy_provider_register((dev), NULL, THIS_MODULE, (xlate))
> > 
> >  +
> > 
> >  + #define devm_of_phy_provider_register(dev, xlate) \
> > 
> >  + __devm_of_phy_provider_register((dev), NULL, THIS_MODULE,
> > 
> >  + (xlate))
> > 
> >  +
> > 
> >  +of_phy_provider_register 和 devm_of_phy_provider_register 宏
> > 
> >  +可用于注册 phy_provider，它以 device 和 of_xlate 作为参数。对于 dt
> > 
> >  +启动情况，所有 PHY provider 都应使用上述两个宏之一来注册 PHY provider。
> > 
> >  +
> > 
> >  +与 PHY provider 关联的设备树节点通常包含一组子节点，每个子节点代表一个
> > 
> >  +PHY。某些绑定可能会为了上下文和可扩展性将子节点嵌套在特别的层级中，在这种
> > 
> >  +情况下，可以使用低级别的 of_phy_provider_register_full() 和
> > 
> >  +devm_of_phy_provider_register_full() 宏来覆盖包含子节点的节点。
> > 
> >  +
> > 
> >  +::
> > 
> >  +
> > 
> >  + #define of_phy_provider_register_full(dev, children, xlate) \
> > 
> >  + __of_phy_provider_register(dev, children, THIS_MODULE, xlate)
> > 
> >  +
> > 
> >  + #define devm_of_phy_provider_register_full(dev, children, xlate) \
> > 
> >  + __devm_of_phy_provider_register_full(dev, children,
> > 
> >  + THIS_MODULE, xlate)
> > 
> >  +
> > 
> >  + void devm_of_phy_provider_unregister(struct device *dev,
> > 
> >  + struct phy_provider *phy_provider);
> > 
> >  + void of_phy_provider_unregister(struct phy_provider *phy_provider);
> > 
> >  +
> > 
> >  +devm_of_phy_provider_unregister 和 of_phy_provider_unregister
> > 
> >  +可以被用来注销PHY.
> > 
> >  +
> > 
> >  +创建PHY
> > 
> >  +=======
> > 
> >  +
> > 
> >  +PHY 驱动程序应创建 PHY，以便其他外围（芯片）控制器能够使用它。PHY 框架
> > 
> >  +提供了 2 个 API 来创建 PHY。
> > 
> >  +
> > 
> >  +::
> > 
> >  +
> > 
> >  + struct phy *phy_create(struct device *dev, struct device_node *node,
> > 
> >  + const struct phy_ops *ops);
> > 
> >  + struct phy *devm_phy_create(struct device *dev,
> > 
> >  + struct device_node *node,
> > 
> >  + const struct phy_ops *ops);
> > 
> >  +
> > 
> >  +PHY 驱动程序可以使用上述两个 API 之一，通过传递设备指针和 phy ops
> > 
> >  +来创建 PHY。
> > 
> 
> From the context, I think "phy ops" should be "phy_ops".
OK.

> 
> > 
> > +
> > 
> >  +phy_ops 是一组用于执行 PHY 操作（例如 init、exit、power_on 和
> > 
> >  +power_off）的函数指针。
> > 
> >  +
> > 
> >  +为了取消引用私有数据（在 phy_ops 中），phy provider驱动程序可以在创建
> > 
> 
> 此处应该使用PHY保持全文一致。
OK.


Thanks,
Yanteng