[PATCH v6 0/8] Add Chinese translation for USB subsystem

[PATCH v6 0/8] Add Chinese translation for USB subsystem

[Kefan Bai]

This patch set adds Chinese translations for the USB documentation.

Apologies for the long delay in revisiting this series. I have now
  rebased it onto the latest docs-next tree, rechecked and polished the
  translations, retested it, and resent it.

Changes in v6:
  - Rebased the series onto the latest docs-next branch in Jon's tree
    (git://git.lwn.net/linux.git), as suggested by Alex Shi.
  - Added the USB maintainers to the Cc list.
  - Rechecked and polished the Chinese translations throughout the series.

Changes in v5:
  - Moved the index.rst entries for acm, authorization, chipidea, dwc3,
    ehci, and usbmon into the corresponding patches so the series builds
    cleanly when applied patch by patch.
  - Removed extra spaces in chipidea.rst.
  - Sent the series to linux-usb@vger.kernel.org for review by
    Chinese-speaking developers, as suggested by Alex Shi and Yanteng Si.
  - Link to v5: https://lore.kernel.org/linux-usb/cover.1765180570.git.baikefan@leap-io-kernel.com/

Changes in v4:
  - Shortened overlong title underline and overline markers.
  - Removed the CREDITS entry from index.rst.
  - Link to v4: https://lore.kernel.org/all/cover.1764674650.git.baikefan@leap-io-kernel.com/

Changes in v3:
  - Updated my sign-off to use my full legal name, as requested by
    Jonathan Corbet.
  - Reviewed and fixed the RST syntax issues noted by Alex Shi.
  - Kept the number of translated files to eight to make submission and
    review more manageable.
  - Link to v3: https://lore.kernel.org/all/cover.1763984424.git.baikefan@leap-io-kernel.com/

Changes in v2:
  - Updated [PATCH 01/25] docs/zh_CN: Add index.rst translation to include
    the corresponding changes to
    Documentation/translations/zh_CN/subsystem-apis.rst.
  - Link to v2: https://lore.kernel.org/all/cover.1763897036.git.baikefan@leap-io-kernel.com/

v1:
  - Link: https://lore.kernel.org/all/20251123074540.34161-1-baikefan@leap-io-kernel.com/

Kefan Bai (8):
  docs/zh_CN: Add index.rst translation
  docs/zh_CN: Add acm.rst translation
  docs/zh_CN: Add authorization.rst translation
  docs/zh_CN: Add chipidea.rst translation
  docs/zh_CN: Add dwc3.rst translation
  docs/zh_CN: Add ehci.rst translation
  docs/zh_CN: Add usbmon.rst translation
  docs/zh_CN: Add CREDITS translation

 .../translations/zh_CN/subsystem-apis.rst     |   2 +-
 Documentation/translations/zh_CN/usb/CREDITS  | 162 ++++++++
 Documentation/translations/zh_CN/usb/acm.rst  | 136 +++++++
 .../translations/zh_CN/usb/authorization.rst  | 132 ++++++
 .../translations/zh_CN/usb/chipidea.rst       | 142 +++++++
 Documentation/translations/zh_CN/usb/dwc3.rst |  60 +++
 Documentation/translations/zh_CN/usb/ehci.rst | 230 +++++++++++
 .../translations/zh_CN/usb/index.rst          |  54 +++
 .../translations/zh_CN/usb/usbmon.rst         | 384 ++++++++++++++++++
 9 files changed, 1301 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/usb/CREDITS
 create mode 100644 Documentation/translations/zh_CN/usb/acm.rst
 create mode 100644 Documentation/translations/zh_CN/usb/authorization.rst
 create mode 100644 Documentation/translations/zh_CN/usb/chipidea.rst
 create mode 100644 Documentation/translations/zh_CN/usb/dwc3.rst
 create mode 100644 Documentation/translations/zh_CN/usb/ehci.rst
 create mode 100644 Documentation/translations/zh_CN/usb/index.rst
 create mode 100644 Documentation/translations/zh_CN/usb/usbmon.rst

--
2.54.0

[PATCH v6 1/8] docs/zh_CN: Add index.rst translation

[Kefan Bai]

Translate .../usb/index.rst into Chinese and update subsystem-apis.rst

Update the translation through commit a592a36e4937
("Documentation: use a source-read extension for the index link boilerplate")

Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn>
Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
---
 .../translations/zh_CN/subsystem-apis.rst     |  2 +-
 .../translations/zh_CN/usb/index.rst          | 54 +++++++++++++++++++
 2 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/usb/index.rst

diff --git a/Documentation/translations/zh_CN/subsystem-apis.rst b/Documentation/translations/zh_CN/subsystem-apis.rst
index 830217140fb6..b52e1feb0167 100644
--- a/Documentation/translations/zh_CN/subsystem-apis.rst
+++ b/Documentation/translations/zh_CN/subsystem-apis.rst
@@ -90,6 +90,7 @@ TODOList:
    security/index
    PCI/index
    peci/index
+   usb/index

 TODOList:

@@ -104,6 +105,5 @@ TODOList:
 * accel/index
 * crypto/index
 * bpf/index
-* usb/index
 * misc-devices/index
 * wmi/index
diff --git a/Documentation/translations/zh_CN/usb/index.rst b/Documentation/translations/zh_CN/usb/index.rst
new file mode 100644
index 000000000000..7cfe99a4dc0a
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/index.rst
@@ -0,0 +1,54 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/index.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+===========
+USB 支持
+===========
+
+.. toctree::
+    :maxdepth: 1
+
+
+Todolist:
+
+* acm
+* authorization
+* chipidea
+* dwc3
+* ehci
+* usbmon
+* functionfs
+* functionfs-desc
+* gadget_configfs
+* gadget_hid
+* gadget_multi
+* gadget_printer
+* gadget_serial
+* gadget_uvc
+* gadget-testing
+* iuu_phoenix
+* mass-storage
+* misc_usbsevseg
+* mtouchusb
+* ohci
+* raw-gadget
+* usbip_protocol
+* usb-serial
+* usb-help
+* text_files
+
+.. only::  subproject and html
+
+   索引
+   =======
+
+   * :ref:`genindex`
--
2.54.0

[PATCH v6 2/8] docs/zh_CN: Add acm.rst translation

[Kefan Bai]

Translate .../usb/acm.rst into Chinese

Update the translation through commit ecefae6db042
("docs: usb: rename files to .rst and add them to drivers-api")

Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn>
Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
---
 Documentation/translations/zh_CN/usb/acm.rst  | 136 ++++++++++++++++++
 .../translations/zh_CN/usb/index.rst          |   2 +-
 2 files changed, 137 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/usb/acm.rst

diff --git a/Documentation/translations/zh_CN/usb/acm.rst b/Documentation/translations/zh_CN/usb/acm.rst
new file mode 100644
index 000000000000..25ec83afd25f
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/acm.rst
@@ -0,0 +1,136 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/acm.rst
+
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+=======================
+Linux ACM 驱动 v0.16
+=======================
+
+版权所有 (c) 1999 Vojtech Pavlik <vojtech@suse.cz>
+
+由 SuSE 赞助
+
+0. 免责声明
+~~~~~~~~~~~~~
+本程序是自由软件；你可以在自由软件基金会发布的 GNU 通用公共许可证第 2 版，
+或者（按你的选择）任何后续版本的条款下重新发布和/或修改它。
+
+发布本程序是希望它能发挥作用，但它不附带任何担保；甚至不包括对适销性
+或特定用途适用性的默示担保。详情见 GNU 通用公共许可证。
+
+你应该已经随本程序收到了 GNU 通用公共许可证的副本；
+如果没有，请致信：Free Software Foundation, Inc., 59
+Temple Place, Suite 330, Boston, MA 02111-1307 USA。
+
+如需联系作者，可发送电子邮件至 vojtech@suse.cz，
+或邮寄至：
+Vojtech Pavlik, Ucitelska 1576, Prague 8, 182 00, Czech Republic。
+
+为方便起见，软件包中已附带 GNU 通用公共许可证第 2 版：见 COPYING 文件。
+
+1. 使用方法
+~~~~~~~~~~~~~
+``drivers/usb/class/cdc-acm.c`` 驱动可用于符合 USB 通信设备类抽象控制模型
+（USB CDC ACM）规范的 USB 调制解调器和 USB ISDN 终端适配器。
+
+许多调制解调器支持此驱动，以下是我所知道的一些型号：
+
+	- 3Com OfficeConnect 56k
+	- 3Com Voice FaxModem Pro
+	- 3Com Sportster
+	- MultiTech MultiModem 56k
+	- Zoom 2986L FaxModem
+	- Compaq 56k FaxModem
+	- ELSA Microlink 56k
+
+我知道有一款 ISDN 终端适配器可以与 ACM 驱动一起使用：
+
+	- 3Com USR ISDN Pro TA
+
+一些手机也可以通过 USB 连接。我知道以下机型可以正常工作：
+
+	- SonyEricsson K800i
+
+遗憾的是，许多调制解调器和大多数 ISDN TA 都使用专有接口，
+因此无法与此驱动配合工作。购买前请先确认设备是否符合 ACM 规范。
+
+要使用这些调制解调器，需要加载以下模块::
+
+	usbcore.ko
+	uhci-hcd.ko ohci-hcd.ko or ehci-hcd.ko
+	cdc-acm.ko
+
+之后就应该可以访问这些调制解调器了。
+应当可以使用 ``minicom``、``ppp`` 和 ``mgetty`` 与它们通信。
+
+2. 验证驱动是否正常工作
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+第一步是检查 ``/sys/kernel/debug/usb/devices``，其内容应该类似如下::
+
+  T:  Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#=  1 Spd=12  MxCh= 2
+  B:  Alloc=  0/900 us ( 0%), #Int=  0, #Iso=  0
+  D:  Ver= 1.00 Cls=09(hub  ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
+  P:  Vendor=0000 ProdID=0000 Rev= 0.00
+  S:  Product=USB UHCI Root Hub
+  S:  SerialNumber=6800
+  C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr=  0mA
+  I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
+  E:  Ad=81(I) Atr=03(Int.) MxPS=   8 Ivl=255ms
+  T:  Bus=01 Lev=01 Prnt=01 Port=01 Cnt=01 Dev#=  2 Spd=12  MxCh= 0
+  D:  Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs=  2
+  P:  Vendor=04c1 ProdID=008f Rev= 2.07
+  S:  Manufacturer=3Com Inc.
+  S:  Product=3Com U.S. Robotics Pro ISDN TA
+  S:  SerialNumber=UFT53A49BVT7
+  C:  #Ifs= 1 Cfg#= 1 Atr=60 MxPwr=  0mA
+  I:  If#= 0 Alt= 0 #EPs= 3 Cls=ff(vend.) Sub=ff Prot=ff Driver=acm
+  E:  Ad=85(I) Atr=02(Bulk) MxPS=  64 Ivl=  0ms
+  E:  Ad=04(O) Atr=02(Bulk) MxPS=  64 Ivl=  0ms
+  E:  Ad=81(I) Atr=03(Int.) MxPS=  16 Ivl=128ms
+  C:* #Ifs= 2 Cfg#= 2 Atr=60 MxPwr=  0mA
+  I:  If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm
+  E:  Ad=81(I) Atr=03(Int.) MxPS=  16 Ivl=128ms
+  I:  If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm
+  E:  Ad=85(I) Atr=02(Bulk) MxPS=  64 Ivl=  0ms
+  E:  Ad=04(O) Atr=02(Bulk) MxPS=  64 Ivl=  0ms
+
+这三行的存在很关键（以及 ``Cls=`` 字段里出现的 ``comm`` 和 ``data`` 类）；
+它说明这是一个 ACM 设备。``Driver=acm`` 表示该设备正在使用 acm 驱动。
+如果只看到 ``Cls=ff(vend.)``，那就无能为力了：这说明你手上的设备使用的是
+厂商专有接口::
+
+    D:  Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs=  2
+    I:  If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm
+    I:  If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm
+
+在系统日志中应该可以看到::
+
+  usb.c: USB new device connect, assigned device number 2
+  usb.c: kmalloc IF c7691fa0, numif 1
+  usb.c: kmalloc IF c7b5f3e0, numif 2
+  usb.c: skipped 4 class/vendor specific interface descriptors
+  usb.c: new device strings: Mfr=1, Product=2, SerialNumber=3
+  usb.c: USB device number 2 default language ID 0x409
+  Manufacturer: 3Com Inc.
+  Product: 3Com U.S. Robotics Pro ISDN TA
+  SerialNumber: UFT53A49BVT7
+  acm.c: probing config 1
+  acm.c: probing config 2
+  ttyACM0: USB ACM device
+  acm.c: acm_control_msg: rq: 0x22 val: 0x0 len: 0x0 result: 0
+  acm.c: acm_control_msg: rq: 0x20 val: 0x0 len: 0x7 result: 7
+  usb.c: acm driver claimed interface c7b5f3e0
+  usb.c: acm driver claimed interface c7b5f3f8
+  usb.c: acm driver claimed interface c7691fa0
+
+如果以上都正常，请启动 ``minicom``，把它配置为连接 ``ttyACM`` 设备，
+然后尝试输入 ``at``。如果返回 ``OK``，说明一切工作正常。
diff --git a/Documentation/translations/zh_CN/usb/index.rst b/Documentation/translations/zh_CN/usb/index.rst
index 7cfe99a4dc0a..449e8ac2dff0 100644
--- a/Documentation/translations/zh_CN/usb/index.rst
+++ b/Documentation/translations/zh_CN/usb/index.rst
@@ -17,10 +17,10 @@ USB 支持
 .. toctree::
     :maxdepth: 1

+    acm

 Todolist:

-* acm
 * authorization
 * chipidea
 * dwc3
--
2.54.0

[PATCH v6 3/8] docs/zh_CN: Add authorization.rst translation

[Kefan Bai]

Translate .../usb/authorization.rst into Chinese

Update the translation through commit f176638af476
("USB: Remove Wireless USB and UWB documentation")

Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn>
Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
---
 .../translations/zh_CN/usb/authorization.rst  | 132 ++++++++++++++++++
 .../translations/zh_CN/usb/index.rst          |   2 +-
 2 files changed, 133 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/usb/authorization.rst

diff --git a/Documentation/translations/zh_CN/usb/authorization.rst b/Documentation/translations/zh_CN/usb/authorization.rst
new file mode 100644
index 000000000000..71153cded526
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/authorization.rst
@@ -0,0 +1,132 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/authorization.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+=============================
+授权或禁止 USB 设备连接到系统
+=============================
+
+版权 (C) 2007 Inaky Perez-Gonzalez <inaky@linux.intel.com> 英特尔公司
+
+此功能允许你控制 USB 设备是否可以在系统中使用。
+借助它，你可以完全通过用户空间实现对 USB 设备的锁定。
+
+目前，当插入一个 USB 设备时，系统会对其进行配置，其接口会立即向用户开放。
+有了这项改动，只有在 root 授权设备完成配置后，设备才可被使用。
+
+
+用法
+====
+
+授权设备接入::
+
+	$ echo 1 > /sys/bus/usb/devices/DEVICE/authorized
+
+取消对设备的授权::
+
+	$ echo 0 > /sys/bus/usb/devices/DEVICE/authorized
+
+将新连接到 ``hostX`` 的设备默认设为未授权（即锁定）::
+
+	$ echo 0 > /sys/bus/usb/devices/usbX/authorized_default
+
+解除锁定::
+
+	$ echo 1 > /sys/bus/usb/devices/usbX/authorized_default
+
+默认情况下，所有 USB 设备都是授权的。
+向 ``authorized_default`` 属性写入 ``2`` 会使内核默认只授权连接到内部
+USB 端口的设备。
+
+系统锁定示例（比较粗糙）
+------------------------
+
+假设你想实现一个锁定功能，只允许类型为 XYZ 的设备接入
+（例如某台带有外露 USB 端口的自助服务终端）::
+
+  启动系统
+  rc.local ->
+
+   for host in /sys/bus/usb/devices/usb*
+   do
+      echo 0 > $host/authorized_default
+   done
+
+给 udev 挂一个脚本，用于处理新插入的 USB 设备::
+
+ if device_is_my_type $DEV
+ then
+   echo 1 > $device_path/authorized
+ done
+
+
+``device_is_my_type()`` 才是锁定方案真正见功夫的地方。
+仅仅检查 class、type 和 protocol 是否匹配某个值，
+是你能做出的最糟糕的安全验证之一；对想绕过它的人来说，
+这反而是最容易利用的方案。如果你需要真正安全的办法，
+那就该使用加密、证书认证之类的机制。把 USB 存储设备当作
+“钥匙”的一个简单例子可以是::
+
+ function device_is_my_type()
+ {
+   echo 1 > authorized		# 暂时授权它
+                                # FIXME: 确保没人能挂载它
+   mount DEVICENODE /mntpoint
+   sum=$(md5sum /mntpoint/.signature)
+   if [ $sum = $(cat /etc/lockdown/keysum) ]
+   then
+        echo "We are good, connected"
+        umount /mntpoint
+        # 再做一些额外处理，让其他人也能使用它
+   else
+        echo 0 > authorized
+   fi
+ }
+
+
+当然，这个例子很粗糙；真正要做的话，你会想用基于 PKI 的证书校验，
+这样就不必依赖共享密钥之类的东西。不过你应该已经明白意思了。
+任何拿到设备仿真工具包的人都能伪造描述符和设备信息。
+别信这个。
+
+接口授权
+--------
+
+也有类似的方法用于允许或拒绝特定 USB 接口。
+这使得你可以只阻止某个 USB 设备中的部分接口。
+
+授权接口::
+
+	$ echo 1 > /sys/bus/usb/devices/INTERFACE/authorized
+
+取消接口授权::
+
+	$ echo 0 > /sys/bus/usb/devices/INTERFACE/authorized
+
+也可以更改特定 USB 总线上新接口的默认授权值。
+
+默认允许接口::
+
+	$ echo 1 > /sys/bus/usb/devices/usbX/interface_authorized_default
+
+默认拒绝接口::
+
+	$ echo 0 > /sys/bus/usb/devices/usbX/interface_authorized_default
+
+默认情况下，``interface_authorized_default`` 位为 ``1``，
+因此所有接口默认都处于已授权状态。
+
+注意：
+  如果把一个先前未授权的接口改为已授权，
+  则必须通过将 ``INTERFACE`` 写入 ``/sys/bus/usb/drivers_probe``
+  来手动触发驱动探测。
+
+对于需要多个接口的驱动程序，应先授权所有必需接口，
+然后再触发驱动探测。这样做可以避免副作用。
diff --git a/Documentation/translations/zh_CN/usb/index.rst b/Documentation/translations/zh_CN/usb/index.rst
index 449e8ac2dff0..a63ece18302d 100644
--- a/Documentation/translations/zh_CN/usb/index.rst
+++ b/Documentation/translations/zh_CN/usb/index.rst
@@ -18,10 +18,10 @@ USB 支持
     :maxdepth: 1

     acm
+    authorization

 Todolist:

-* authorization
 * chipidea
 * dwc3
 * ehci
--
2.54.0

[PATCH v6 4/8] docs/zh_CN: Add chipidea.rst translation

[Kefan Bai]

Translate .../usb/chipidea.rst into Chinese

Update the translation through commit e4157519ad46
("Documentation: usb: correct spelling")

Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn>
Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
---
 .../translations/zh_CN/usb/chipidea.rst       | 142 ++++++++++++++++++
 .../translations/zh_CN/usb/index.rst          |   2 +-
 2 files changed, 143 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/usb/chipidea.rst

diff --git a/Documentation/translations/zh_CN/usb/chipidea.rst b/Documentation/translations/zh_CN/usb/chipidea.rst
new file mode 100644
index 000000000000..433b3fc411fc
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/chipidea.rst
@@ -0,0 +1,142 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/chipidea.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+==============================
+ChipIdea 高速双角色控制器驱动
+==============================
+
+1. 如何测试 OTG FSM（HNP 和 SRP）
+---------------------------------
+
+下面以两块 Freescale i.MX6Q Sabre SD 开发板为例，说明如何通过
+sysfs 输入文件演示 OTG 的 HNP 和 SRP 功能。
+
+1.1 如何使能 OTG FSM
+---------------------
+
+1.1.1 在 ``menuconfig`` 中选择 ``CONFIG_USB_OTG_FSM``，并重新编译内核
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+重新构建内核镜像和模块。如果想查看 OTG FSM 的一些内部变量，可以挂载
+``debugfs``；其中有两个文件可以显示 OTG FSM 变量以及部分控制器寄存器的值::
+
+	cat /sys/kernel/debug/ci_hdrc.0/otg
+	cat /sys/kernel/debug/ci_hdrc.0/registers
+
+1.1.2 在控制器节点对应的 ``dts`` 文件中添加以下条目
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+	otg-rev = <0x0200>;
+	adp-disable;
+
+1.2 测试步骤
+-------------
+
+1) 给两块 Freescale i.MX6Q Sabre SD 开发板上电，
+   并加载 gadget 类驱动（例如 ``g_mass_storage``）。
+
+2) 用 USB 线连接两块开发板：一端是 micro A 插头，另一端是 micro B 插头。
+
+   插入 micro A 插头的一端是 A 设备，它应枚举另一端的 B 设备。
+
+3) 角色切换
+
+   在 B 设备上执行::
+
+	echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req
+
+   B 设备应接管主机角色并枚举 A 设备。
+
+4) A 设备切回主机角色
+
+   在 B 设备上执行::
+
+	echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req
+
+   或者，通过引入 HNP 轮询，B 端主机可以知道 A 端外设希望切换为主机角色，
+   因而这次角色切换也可以通过 A 端外设响应 B 端主机的轮询，在 A 侧触发。
+   这可以通过在 A 设备上执行下面的命令来完成::
+
+	echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req
+
+   A 设备应切回主机角色并枚举 B 设备。
+
+5) 拔掉 B 设备（拔掉 micro B 插头），并在 10 秒内重新插入；
+   A 设备应重新枚举 B 设备。
+
+6) 拔掉 B 设备（拔掉 micro B 插头），并在 10 秒后重新插入；
+   A 设备不应重新枚举 B 设备。
+
+   如果 A 设备希望使用总线：
+
+   在 A 设备上执行::
+
+	echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop
+	echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req
+
+   如果 B 设备希望使用总线：
+
+   在 B 设备上执行::
+
+	echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req
+
+7) A 设备关闭总线供电
+
+   在 A 设备上执行::
+
+	echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop
+
+   A 设备应断开与 B 设备的连接，并关闭总线供电。
+
+8) B 设备发出 SRP 数据脉冲
+
+   在 B 设备上执行::
+
+	echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req
+
+   A 设备应恢复 USB 总线并枚举 B 设备。
+
+1.3 参考文档
+-------------
+《On-The-Go and Embedded Host Supplement to the USB Revision 2.0 Specification
+July 27, 2012 Revision 2.0 version 1.1a》
+
+2. 如何将 USB 用作系统唤醒源
+----------------------------
+下面是在 i.MX6 平台上把 USB 用作系统唤醒源的示例。
+
+2.1 使能核心控制器的唤醒功能::
+
+	echo enabled > /sys/bus/platform/devices/ci_hdrc.0/power/wakeup
+
+2.2 使能 glue 层的唤醒功能::
+
+	echo enabled > /sys/bus/platform/devices/2184000.usb/power/wakeup
+
+2.3 使能 PHY 的唤醒功能（可选）::
+
+	echo enabled > /sys/bus/platform/devices/20c9000.usbphy/power/wakeup
+
+2.4 使能根集线器的唤醒功能::
+
+	echo enabled > /sys/bus/usb/devices/usb1/power/wakeup
+
+2.5 使能相关设备的唤醒功能::
+
+	echo enabled > /sys/bus/usb/devices/1-1/power/wakeup
+
+如果系统只有一个 USB 端口，而你希望在该端口上启用 USB 唤醒功能，
+可以使用下面的脚本::
+
+	for i in $(find /sys -name wakeup | grep usb);do echo enabled > $i;done;
diff --git a/Documentation/translations/zh_CN/usb/index.rst b/Documentation/translations/zh_CN/usb/index.rst
index a63ece18302d..70fe33fc37d9 100644
--- a/Documentation/translations/zh_CN/usb/index.rst
+++ b/Documentation/translations/zh_CN/usb/index.rst
@@ -19,10 +19,10 @@ USB 支持

     acm
     authorization
+    chipidea

 Todolist:

-* chipidea
 * dwc3
 * ehci
 * usbmon
--
2.54.0

[PATCH v6 5/8] docs/zh_CN: Add dwc3.rst translation

[Kefan Bai]

Translate .../usb/dwc3.rst into Chinese

Update the translation through commit ecefae6db042
("docs: usb: rename files to .rst and add them to drivers-api")

Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn>
Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
---
 Documentation/translations/zh_CN/usb/dwc3.rst | 60 +++++++++++++++++++
 .../translations/zh_CN/usb/index.rst          |  2 +-
 2 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/usb/dwc3.rst

diff --git a/Documentation/translations/zh_CN/usb/dwc3.rst b/Documentation/translations/zh_CN/usb/dwc3.rst
new file mode 100644
index 000000000000..92108ff8cc80
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/dwc3.rst
@@ -0,0 +1,60 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/dwc3.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+===========
+DWC3 驱动
+===========
+
+
+待办
+~~~~~~
+
+阅读时如果想顺手认领点任务，可以从下面挑一项 :)
+
+- 将中断处理程序改为每个端点各自使用线程化 IRQ
+
+  事实证明，有些 DWC3 命令大约需要 ``~1 ms`` 才能完成。
+  当前代码会一直自旋等待命令完成，这种设计并不好。
+
+  实现思路：
+
+  - DWC 核心实现了一个按端点对中断进行解复用的 IRQ 控制器。中断号在
+    探测（``probe``）阶段分配，并归属于该设备。如果硬件通过 ``MSI`` 为每个端点
+    提供独立中断，那么这个“虚拟”IRQ 控制器就可以被真实的端点中断取代。
+
+  - 在调用 ``usb_ep_enable()`` 时请求并分配中断资源，
+    在调用 ``usb_ep_disable()`` 时释放中断资源。
+    最坏情况下需要 32 个中断，最少是 ``ep0/1`` 的两个中断。
+  - ``dwc3_send_gadget_ep_cmd()`` 将在 ``wait_for_completion_timeout()``
+    中休眠，直到命令完成。
+  - 中断处理程序分为以下几个部分：
+
+    - 设备级主中断处理程序
+      遍历每个事件，并对其调用 ``generic_handle_irq()``。
+      从 ``generic_handle_irq()`` 返回后，确认事件计数器，使中断最终消失。
+
+    - 设备级线程化处理程序
+      无。
+
+    - 端点中断的主处理程序
+      读取事件并尽量处理它。凡是需要睡眠的操作都交给线程处理。
+      事件保存在每个端点的数据结构中。
+      还要注意，一旦把某项工作交给线程处理，就不要再在主处理程序里处理它，
+      以免出现优先级反转之类的问题。
+
+    - 端点中断的线程化处理程序
+      处理剩余的端点工作，这些工作可能会睡眠，例如等待命令完成。
+
+  延迟:
+
+   不应增加延迟，因为中断线程具有较高优先级，会在普通用户态任务之前运行
+   （除非用户更改了调度优先级）。
diff --git a/Documentation/translations/zh_CN/usb/index.rst b/Documentation/translations/zh_CN/usb/index.rst
index 70fe33fc37d9..6d669c41d1cd 100644
--- a/Documentation/translations/zh_CN/usb/index.rst
+++ b/Documentation/translations/zh_CN/usb/index.rst
@@ -20,10 +20,10 @@ USB 支持
     acm
     authorization
     chipidea
+    dwc3

 Todolist:

-* dwc3
 * ehci
 * usbmon
 * functionfs
--
2.54.0

[PATCH v6 6/8] docs/zh_CN: Add ehci.rst translation

[Kefan Bai]

Translate .../usb/ehci.rst into Chinese

Update the translation through commit 570eb861243c
("docs: usb: replace some characters")

Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn>
Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
---
 Documentation/translations/zh_CN/usb/ehci.rst | 230 ++++++++++++++++++
 .../translations/zh_CN/usb/index.rst          |   2 +-
 2 files changed, 231 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/usb/ehci.rst

diff --git a/Documentation/translations/zh_CN/usb/ehci.rst b/Documentation/translations/zh_CN/usb/ehci.rst
new file mode 100644
index 000000000000..ea1d72f52efd
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/ehci.rst
@@ -0,0 +1,230 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/ehci.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+=========
+EHCI 驱动
+=========
+
+2002年12月27日
+
+EHCI 驱动用于通过支持 USB 2.0 的主机控制器硬件与高速 USB 2.0 设备通信。
+USB 2.0 兼容 USB 1.1 标准，它定义了三种传输速率：
+
+    - “高速”（High Speed）480 Mbit/sec（60 MByte/sec）
+    - “全速”（Full Speed）12 Mbit/sec（1.5 MByte/sec）
+    - “低速”（Low Speed）1.5 Mbit/sec
+
+USB 1.1 仅支持全速与低速。高速设备可以在 USB 1.1 系统上使用，
+但速度会降到 USB 1.1 的速率。
+
+USB 1.1 设备也可以在 USB 2.0 系统上使用。
+当它们插入 EHCI 控制器时，会被交由 USB 1.1 的伴随（companion）控制器处理，
+该控制器通常是 OHCI 或 UHCI。
+
+当 USB 1.1 设备插入 USB 2.0 集线器时，
+它们通过集线器中的事务转换器（Transaction Translator，TT）与 EHCI 控制器交互，
+该转换器将低速或全速事务转换为高速分割事务，从而避免浪费传输带宽。
+
+截至本文撰写时，该驱动已在以下 EHCI 实现上成功运行（按字母顺序）：
+Intel、NEC、Philips 和 VIA。
+其他供应商的 EHCI 实现正在陆续问世；
+预计该驱动在这些实现上也可正常运行。
+
+自 2001 年年中起，usb-storage 设备就已可用
+（在 2.4 版该驱动上速度相当不错），
+集线器则直到 2001 年底才开始可用，而其他类型的高速设备
+似乎要等到更多系统内置 USB 2.0 后才会出现。
+这类新系统从 2002 年初开始上市，并在 2002 年下半年变得更加常见。
+
+注意，USB 2.0 支持并不只是 EHCI 本身。它还需要对 Linux-USB
+核心 API 作出其他修改，包括 hub 驱动；不过这些修改并不需要真正改变
+暴露给 USB 设备驱动的基本 ``usbcore`` API。
+
+- David Brownell
+  <dbrownell@users.sourceforge.net>
+
+
+功能
+====
+
+该驱动会定期在 x86 硬件上进行测试，也已在 PPC 硬件上使用，
+因此大小端问题应当已经解决。
+因此可以认为，它已经处理好了所有必要的 PCI 细节，
+所以即便在 DMA 映射有些特殊的系统上，I/O 也应能正常运行。
+
+传输类型
+--------
+
+截至本文撰写时，该驱动应当已经能够很好地处理所有控制传输、批量传输
+和中断传输，包括通过 USB 2.0 集线器中的事务转换器与 USB 1.1 设备通信；
+但仍可能存在 bug。
+
+高速等时（ISO）传输支持也已可用，但截至本文撰写时，
+还没有 Linux 驱动使用这项支持。
+
+目前尚不支持通过事务转换器实现全速等时传输。
+需要注意，ISO 传输的 split transaction 支持与高速 ISO 传输
+几乎无法共用代码，因为 EHCI 用不同的数据结构表示它们。
+因此，目前大多数 USB 音频和视频设备还不能通过高速总线连接使用。
+
+驱动行为
+--------
+
+所有类型的传输都可以排队。
+这意味着来自一个接口驱动的控制传输（或通过 usbfs 发出的控制传输）
+不会干扰另一个驱动的控制传输，而且中断传输可以使用 1 帧的周期，
+而不必担心中断处理开销导致的数据丢失。
+
+
+EHCI 根集线器代码会将 USB 1.1 设备移交给其伴随控制器。
+该驱动不需要了解那些驱动的任何细节；
+一个原本就能正常工作的 OHCI 或 UHCI 驱动，并不会因为 EHCI 驱动也存在而需要更改。
+
+电源管理方面还有一些问题；当前挂起/恢复的行为还不完全正确。
+
+此外，在调度周期性事务（中断和等时传输）时还采取了一些简化处理。
+这些简化会限制可调度的周期性事务数量，
+并且无法使用小于一帧的轮询间隔。
+
+使用方式
+=========
+
+假设有一个 EHCI 控制器（位于 PCI 卡或主板上），并且已将此驱动编译为模块，
+可这样加载::
+
+    # modprobe ehci-hcd
+
+卸载方式::
+
+    # rmmod ehci-hcd
+
+还应加载一个伴随控制器驱动，例如 ``ohci-hcd`` 或 ``uhci-hcd``。
+如果 EHCI 驱动出现任何问题，只需卸载它的模块，
+随后该伴随控制器驱动就会接手此前由 EHCI 驱动处理的所有设备
+（但速度会降低）。
+
+模块参数（传给 ``modprobe``）包括：
+
+    log2_irq_thresh（默认值 0）：
+        默认中断延迟的 log2 值，单位是微帧。默认值 0 表示 1 个微帧
+        （125 微秒）。最大值 6 表示 2^6 = 64 个微帧。
+        该值控制 EHCI 控制器发出中断的频率。
+
+如果在 2.5 内核上使用此驱动，并且启用了 USB 调试支持，
+则会在任一 EHCI 控制器的 ``sysfs`` 目录中看到三个文件：
+
+    ``async``
+        转储异步调度，用于控制传输和批量传输。它会显示每个活动的 ``qh``
+        以及待处理的 ``qtd``，通常每个 ``urb`` 对应一个 ``qtd``。
+        （可以在 ``usb-storage`` 做磁盘 I/O 时看它；顺便观察请求队列！）
+
+    ``periodic``
+        转储周期性调度，用于中断传输和等时传输。不显示 ``qtd``。
+
+    ``registers``
+        显示控制器寄存器状态。
+
+这些文件的内容有助于定位驱动问题。
+
+
+设备驱动通常不需要关心自己是否运行在 EHCI 之上，
+但它们可能想检查 ``usb_device->speed == USB_SPEED_HIGH``。
+高速设备能做到全速（或低速）设备做不到的事，
+例如高带宽的周期性传输（中断或 ISO 传输）。
+另外，设备描述符中的某些值
+（例如周期性传输的轮询间隔）在高速模式下使用不同的编码方式。
+
+不过，一定要让设备驱动经过 USB 2.0 集线器的测试。
+当使用事务转换器时，这些集线器报告某些故障（例如断开连接）的方式会不同；
+已经见过一些驱动在遇到与 OHCI 或 UHCI 所报告的不同故障时表现不佳。
+
+性能
+====
+
+USB 2.0 吞吐量主要受两个因素制约：主机控制器处理请求的速度，
+以及设备响应这些请求的速度。480 Mbit/sec 的“原始传输率”
+对所有设备都成立，但总吞吐量还会受到诸如单个高速包之间的延迟、
+驱动是否足够聪明，以及系统整体负载等因素的影响。
+延迟也是性能考量因素。
+
+批量传输最常用于关注吞吐量的场景。
+需要记住的是，批量传输总是以 512 字节包为单位，
+而一个 USB 2.0 微帧中最多只能容纳 13 个这样的包。
+8 个 USB 2.0 微帧构成一个 USB 1.1 帧；
+一个微帧的时长是 1 毫秒 / 8 = 125 微秒。
+
+因此，只要硬件和设备驱动软件都允许，
+批量传输可提供超过 50 MByte/sec 的带宽。
+周期性传输模式（等时和中断）允许使用更大的包大小，
+从而可以逼近所宣称的 480 Mbit/sec 传输率。
+
+硬件性能
+--------
+
+截至本文撰写时，单个 USB 2.0 设备的最大传输速率通常约为 20 MByte/sec。
+这当然会随着时间改变：一些设备现在更快，一些更慢。
+
+第一代 NEC EHCI 实现似乎存在大约 28 MByte/sec 的硬件瓶颈。
+虽然这对单个 20 MByte/sec 的设备显然已经够用，
+但把三个这样的设备挂到同一总线上，并不能得到 60 MByte/sec。
+问题似乎在于控制器硬件无法并发进行 USB 与 PCI 访问，
+因此它每个微帧只会尝试 6 次（也许是 7 次）USB 事务，而不是 13 次。
+（对一个比其他产品早上市一年的芯片来说，这是个合理的妥协！）
+
+
+预计较新的实现会在这方面做得更好，
+通过投入更多芯片面积来解决这个问题，
+使新的主板芯片组更接近 60 MByte/sec 的目标。
+这既包括 NEC 的更新实现，也包括其他厂商的芯片。
+
+
+主机从 EHCI 控制器收到“请求已完成”中断的最小延迟为一个微帧
+（125 微秒）。该延迟可以调节；驱动提供了一个模块选项。
+默认情况下，``ehci-hcd`` 使用最小延迟，
+这意味着当发出一个控制或批量请求时，
+通常可以在不到 250 微秒内得知它已完成
+（具体取决于传输大小）。
+
+软件性能
+--------
+
+即便只是要达到 20 MByte/sec 的传输速率，Linux-USB 设备驱动
+也必须让 EHCI 队列始终保持满载。
+这意味着要发出较大的请求，或者在需要发出一连串小请求时使用批量请求排队。
+如果驱动未做到这一点，那么会直接从性能结果上表现出来。
+
+
+在典型情况下，使用 ``usb_bulk_msg()`` 以 4 KB 块循环写出，
+会浪费超过一半的 USB 2.0 带宽。
+I/O 完成与驱动发出下一次请求之间的延迟，通常会比一次 I/O 本身耗时更长。
+如果同样的循环改用 16 KB 块，会好一些；若使用一连串 128 KB 块，则浪费会少得多。
+
+
+但与其依赖这么大的 I/O 缓冲区来让同步 I/O 高效，
+不如直接向主机控制器排入多个（批量）请求，然后等待它们全部完成
+（或在出错时取消）。
+这种 URB 排队方式对所有 USB 1.1 主机控制器驱动也同样适用。
+
+
+在 Linux 2.5 内核中，定义了新的 ``usb_sg_*()`` API；
+它们会把 scatterlist 中的所有缓冲区都排入队列。
+它们还使用 scatterlist 的 DMA 映射（其中可能应用 IOMMU）并减少中断次数，
+这些都有助于让高速传输尽可能快地运行。
+
+待办：
+   中断传输和等时（ISO）传输的性能问题。
+   这些周期性传输都是完全调度的，因此，主要问题可能在于如何触发高带宽模式。
+
+待办：
+   通过 ``sysfs`` 中的 ``uframe_periodic_max`` 参数，
+   可以分配超过标准 80% 的周期性带宽。
+   后续将对此进行说明。
diff --git a/Documentation/translations/zh_CN/usb/index.rst b/Documentation/translations/zh_CN/usb/index.rst
index 6d669c41d1cd..6c8e75d8cfc9 100644
--- a/Documentation/translations/zh_CN/usb/index.rst
+++ b/Documentation/translations/zh_CN/usb/index.rst
@@ -21,10 +21,10 @@ USB 支持
     authorization
     chipidea
     dwc3
+    ehci

 Todolist:

-* ehci
 * usbmon
 * functionfs
 * functionfs-desc
--
2.54.0

[PATCH v6 7/8] docs/zh_CN: Add usbmon.rst translation

[Kefan Bai]

Translate .../usb/usbmon.rst into Chinese

Update the translation through commit 788183a6e8b0
("docs: usb: fix literal block marker in usbmon verification example")

Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn>
Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
---
 .../translations/zh_CN/usb/index.rst          |   2 +-
 .../translations/zh_CN/usb/usbmon.rst         | 384 ++++++++++++++++++
 2 files changed, 385 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/usb/usbmon.rst

diff --git a/Documentation/translations/zh_CN/usb/index.rst b/Documentation/translations/zh_CN/usb/index.rst
index 6c8e75d8cfc9..9df11bd4721c 100644
--- a/Documentation/translations/zh_CN/usb/index.rst
+++ b/Documentation/translations/zh_CN/usb/index.rst
@@ -22,10 +22,10 @@ USB 支持
     chipidea
     dwc3
     ehci
+    usbmon

 Todolist:

-* usbmon
 * functionfs
 * functionfs-desc
 * gadget_configfs
diff --git a/Documentation/translations/zh_CN/usb/usbmon.rst b/Documentation/translations/zh_CN/usb/usbmon.rst
new file mode 100644
index 000000000000..8142e00e353e
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/usbmon.rst
@@ -0,0 +1,384 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/usbmon.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+======
+usbmon
+======
+
+简介
+====
+小写形式的 ``usbmon`` 指的是内核中的一项功能，用于收集 USB 总线上的
+I/O 跟踪信息。它类似于网络监控工具 ``tcpdump(1)`` 或 Ethereal 所使用的
+数据包套接字。类似地，人们希望使用 usbdump 或 USBMon
+（首字母大写）之类的工具来检查 usbmon 生成的原始跟踪数据。
+
+usbmon 报告的是各个外设驱动向主机控制器驱动（HCD）发出的请求。
+因此，如果 HCD 本身有 bug，那么 usbmon 报告的跟踪信息可能无法精确对应
+实际的总线事务。这和 tcpdump 的情况是一样的。
+
+目前实现了两种 API: ``text`` 和 ``binary``。二进制 API 通过 ``/dev``
+命名空间中的字符设备提供，并且属于 ABI。文本 API 自内核 2.6.35 起
+已废弃，但为了方便仍然可用。
+
+如何使用 usbmon 收集原始文本跟踪信息
+====================================
+
+与数据包套接字不同，usbmon 提供了一种接口，可以输出文本格式的跟踪信息。
+这样做有两个目的：
+第一，在更完善的格式最终确定之前，它作为工具间通用的跟踪交换格式；
+第二，在不使用工具的情况下，人们也可以直接阅读这些信息。
+
+要收集原始文本跟踪信息，请按以下步骤进行操作。
+
+1. 准备
+--------
+
+挂载 debugfs（内核配置中必须启用它），并加载 usbmon 模块
+（如果它是作为模块构建的）。如果 usbmon 已经编入内核，
+那么第二步可以省略。
+
+命令示例::
+
+    # mount -t debugfs none_debugs /sys/kernel/debug
+    # modprobe usbmon
+    #
+
+确认总线套接字是否存在::
+
+    # ls /sys/kernel/debug/usb/usbmon
+    0s  0u  1s  1t  1u  2s  2t  2u  3s  3t  3u  4s  4t  4u
+    #
+
+现在，你可以选择使用 ``0u`` 捕获所有总线上的数据包，并跳到第 3 步；
+也可以先按第 2 步找到目标设备所在的总线。
+这样可以过滤掉那些持续输出数据的烦人设备。
+
+2. 查找目标设备连接的是哪条总线
+-------------------------------
+
+运行 ``cat /sys/kernel/debug/usb/devices``，找到对应设备的 T 行。
+通常可以通过厂商字符串来查找。如果有许多类似设备，
+可以拔掉其中一个，再比较前后两次 ``/sys/kernel/debug/usb/devices``
+的输出。T 行里会包含总线编号。
+
+示例::
+
+  T:  Bus=03 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  2 Spd=12  MxCh= 0
+  D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
+  P:  Vendor=0557 ProdID=2004 Rev= 1.00
+  S:  Manufacturer=ATEN
+  S:  Product=UC100KM V2.00
+
+``Bus=03`` 表示它位于 3 号总线上。或者，也可以查看 ``lsusb`` 的输出，
+并从对应行得到总线编号。
+
+示例如下::
+
+  Bus 003 Device 002: ID 0557:2004 ATEN UC100KM V2.00
+
+
+3. 启动 cat 命令
+--------------------
+
+如果只监听单条总线，可执行::
+
+    # cat /sys/kernel/debug/usb/usbmon/3u > /tmp/1.mon.out
+
+否则，如果要监听所有总线，则执行::
+
+    # cat /sys/kernel/debug/usb/usbmon/0u > /tmp/1.mon.out
+
+此进程会一直读取，直到被终止。
+由于输出通常会很长，因此更推荐将输出重定向到某个位置。
+
+
+4. 在 USB 总线上执行期望的操作
+------------------------------
+
+此处需要执行一些会产生 USB 流量的动作，比如插入 U 盘、拷贝文件、操作摄像头等。
+
+
+5. 停止 cat
+-----------
+
+这一步通常通过键盘中断（Control-C）完成。
+
+此时输出文件（本例中为 ``/tmp/1.mon.out``）可以保存、通过电子邮件发送，
+或使用文本编辑器查看。
+如果使用最后一种方式，请确保文件不会大到编辑器无法打开。
+
+
+原始文本数据格式
+================
+
+目前支持两种格式：原始格式，也就是 ``1t`` 格式，以及 ``1u`` 格式。
+``1t`` 格式在内核 2.6.21 中已被废弃。``1u`` 格式增加了一些字段，
+例如 ISO 帧描述符、``interval`` 等。它生成的行会稍长一些，
+但在其他方面是 ``1t`` 格式的完整超集。
+
+如果程序需要区分上述两种格式，可以查看 ``address`` 字段（见下文）。
+如果其中有两个冒号，就是 ``1t`` 格式；否则是 ``1u`` 格式。
+
+任何文本格式的数据由一系列事件组成，如 URB 提交、URB 回调、提交错误等。
+每个事件对应单独的一行文本，由使用空白符间隔的若干字段组成。
+字段的数量与位置可能取决于事件类型，但以下字段对所有类型都通用：
+
+下面按从左到右的顺序列出这些共有字段：
+
+- URB Tag。用于标识 URB，通常是 URB 结构体在内核中的地址（以十六进制表示），
+  但也可能是序号或其他合理的唯一字符串。
+
+- 时间戳（微秒），十进制数字。时间戳的精度取决于可用时钟，因此可能远差于
+  1 微秒（例如实现使用的是 jiffies）。
+
+- 事件类型。它表示的是事件的格式，而不是 URB 的类型。
+  可用值为：``S`` 表示提交，``C`` 表示回调，``E`` 表示提交错误。
+
+- ``Address`` 字段（以前称作 ``pipe``）。它包含四个由冒号分隔的字段：
+  URB 类型及方向、总线号、设备地址和端点号。类型与方向的编码如下：
+
+    == ==   ==========================
+    Ci Co   控制输入和输出
+    Zi Zo   等时输入和输出
+    Ii Io   中断输入和输出
+    Bi Bo   批量输入和输出
+    == ==   ==========================
+
+  总线号、设备地址和端点号使用十进制，但可能有前导零。
+
+- URB 状态字段。这个字段要么是一个字母，要么是几个由冒号分隔的数字：
+  URB 状态、``interval``、``start frame`` 和 ``error count``。
+  与 ``address`` 字段不同，除了状态外，其余字段都是可选的。
+  ``interval`` 只会为中断和等时 URB 打印；``start frame`` 只会为
+  等时 URB 打印；错误计数只会在等时回调事件中打印。
+
+  状态字段是一个十进制数字，有时为负数，对应 URB 的 ``status`` 字段。
+  对于提交事件，这个字段本身没有实际意义，但为了便于脚本解析，它仍然存在。
+  当发生错误时，该字段包含错误码。
+
+  在提交控制包时，这个字段包含的是 ``Setup Tag``，而不是一组数字。
+  判断 ``Setup Tag`` 是否存在很容易，因为它从来不是数字。
+  因此，如果脚本在这个字段里发现的是一组数字，
+  就会继续读取数据长度（等时 URB 除外）。
+  如果发现的是其他内容，比如一个字母，
+  那么脚本会先读取 ``Setup`` 包，再读取数据长度或等时描述符。
+
+- ``Setup`` 包由 5 个字段组成：``bmRequestType``、``bRequest``、``wValue``、
+  ``wIndex`` 和 ``wLength``。这些字段由 USB 2.0 规范定义。
+  如果 ``Setup Tag`` 为 ``s``，就可以安全地解码这些字段。
+  否则，说明 Setup 包虽然存在，但并未被捕获，此时各字段中会填入占位内容。
+
+- 等时传输帧描述符的数量及其内容：
+  如果一个等时传输事件带有一组描述符，首先打印该 URB 中描述符的总数，
+  然后为每个描述符打印一个字段，最多打印 5 个字段。
+  每个字段由三个用冒号分隔的十进制数字组成，
+  分别表示状态（status）、偏移（offset）和长度（length）。
+  对于提交（submission），报告的是初始长度；
+  对于回调（callback），报告的是实际长度。
+
+- 数据长度：
+  对于提交，表示请求的长度；对于回调，表示实际传输的长度。
+
+- 数据标签：
+  即使数据长度非零，usbmon 也不一定会捕获数据。仅当标签为 ``=`` 时，才会有数据字段。
+
+- 数据字段：
+  以大端十六进制格式显示。注意，这些并不是真正的机器字，
+  而只是把字节流拆成若干“字”以便阅读。因此最后一个字可能只包含
+  1 到 4 个字节。
+  收集的数据长度是有限的，可能小于数据长度字段中报告的值。
+  因为数据长度字段只统计实际接收到的字节，而数据字段包含整个传输缓冲区，
+  所以，在等时输入（Zi）完成且缓冲区中接收到的数据稀疏的情况下，
+  收集的数据长度可能大于数据长度字段的值。
+
+
+
+示例：
+
+获取端口状态的输入控制传输::
+
+    d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 <
+    d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000
+
+向地址为 5 的存储设备发送 31 字节 Bulk 包装的 SCSI 命令 ``0x28``
+（``READ_10``）的输出批量传输::
+
+    dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 ad000000 00800000 80010a28 20000000 20000040 00000000 000000
+    dd65f0e8 4128379808 C Bo:1:005:2 0 31 >
+
+原始二进制格式与 API
+=====================
+API 的整体架构与前文大体相同，只是事件以二进制格式传递。
+每个事件都通过下面的结构发送（这个名字是为了叙述方便而虚构的）::
+
+
+  struct usbmon_packet {
+	u64 id;			/*  0: URB ID - 从提交到回调 */
+	unsigned char type;	/*  8: 与文本相同；可扩展 */
+	unsigned char xfer_type; /*    ISO (0)、中断、控制、批量 (3) */
+	unsigned char epnum;	/*     端点号和传输方向 */
+	unsigned char devnum;	/*     设备地址 */
+	u16 busnum;		/* 12: 总线号 */
+	char flag_setup;	/* 14: 与文本相同 */
+	char flag_data;		/* 15: 与文本相同；二进制零也可 */
+	s64 ts_sec;		/* 16: gettimeofday */
+	s32 ts_usec;		/* 24: gettimeofday */
+	int status;		/* 28: */
+	unsigned int length;	/* 32: 数据长度（提交或实际） */
+	unsigned int len_cap;	/* 36: 已捕获的数据长度 */
+	union {			/* 40: */
+		unsigned char setup[SETUP_LEN];	/* 仅用于控制类 S 事件 */
+		struct iso_rec {		/* 仅用于 ISO */
+			int error_count;
+			int numdesc;
+		} iso;
+	} s;
+	int interval;		/* 48: 仅用于中断和 ISO */
+	int start_frame;	/* 52: 仅用于 ISO */
+	unsigned int xfer_flags; /* 56: URB 的 transfer_flags 副本 */
+	unsigned int ndesc;	/* 60: 实际 ISO 描述符数量 */
+  };				/* 64 总长度 */
+
+可以用 ``read(2)``、``ioctl(2)``，或者通过 ``mmap`` 访问缓冲区，
+从字符设备接收这些事件。不过，出于兼容性原因，``read(2)``
+只返回前 48 个字节。
+
+字符设备通常命名为 ``/dev/usbmonN``，其中 ``N`` 是 USB 总线号。
+编号为零的设备（``/dev/usbmon0``）比较特殊，表示“所有总线”。
+请注意，具体命名策略由 Linux 发行版决定。
+
+如果你手动创建 ``/dev/usbmon0``，请确保它归 root 所有，并且权限为 ``0600``。
+否则，非特权用户将能够窃听键盘流量。
+
+以下 ``MON_IOC_MAGIC`` 为 ``0x92`` 的 ioctl 调用可用：
+
+``MON_IOCQ_URB_LEN``，定义为 ``_IO(MON_IOC_MAGIC, 1)``
+
+该调用返回下一个事件的数据长度。注意大多数事件不包含数据，
+因此如果该调用返回零，并不意味着没有事件。
+
+``MON_IOCG_STATS``，定义为
+``_IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats)``
+
+参数是指向以下结构的指针::
+
+  struct mon_bin_stats {
+	u32 queued;
+	u32 dropped;
+  };
+
+成员 ``queued`` 表示当前缓冲区中已经排队的事件数量，
+而不是自上次重置以来处理过的事件数量。
+
+成员 ``dropped`` 表示自上次调用 ``MON_IOCG_STATS`` 以来丢失的事件数量。
+
+``MON_IOCT_RING_SIZE``，定义为 ``_IO(MON_IOC_MAGIC, 4)``
+
+此调用设置缓冲区大小。参数为以字节为单位的缓冲区大小。
+大小可能会向下取整到下一个块（或页）。
+如果请求的大小超出该内核的 [未指定] 范围，则调用会失败并返回 ``-EINVAL``。
+
+``MON_IOCQ_RING_SIZE``，定义为 ``_IO(MON_IOC_MAGIC, 5)``
+
+该调用返回缓冲区当前大小（以字节为单位）。
+
+``MON_IOCX_GET``，定义为 ``_IOW(MON_IOC_MAGIC, 6, struct mon_get_arg)``
+``MON_IOCX_GETX``，定义为 ``_IOW(MON_IOC_MAGIC, 10, struct mon_get_arg)``
+
+如果内核缓冲区中没有事件，这些调用就会一直等待，直到有事件到达，
+然后返回第一个事件。
+参数是指向以下结构的指针::
+
+  struct mon_get_arg {
+	struct usbmon_packet *hdr;
+	void *data;
+	size_t alloc;		/* 数据长度可以为零 */
+  };
+
+
+调用前，应填好 ``hdr``、``data`` 和 ``alloc``。
+调用返回后，``hdr`` 指向的区域中包含下一个事件的结构；
+如果存在数据，那么数据缓冲区中也会包含相应数据。
+该事件会从内核缓冲区中移除。
+
+``MON_IOCX_GET`` 会将 48 字节的数据复制到 ``hdr`` 区域，
+``MON_IOCX_GETX`` 会复制 64 字节。
+
+``MON_IOCX_MFETCH``，定义为
+``_IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg)``
+
+当应用程序通过 ``mmap(2)`` 访问缓冲区时，主要使用这个 ioctl。
+其参数是指向以下结构的指针::
+
+  struct mon_mfetch_arg {
+	uint32_t *offvec;	/* 获取的事件偏移向量 */
+	uint32_t nfetch;	/* 要获取的事件数量（输出：已获取） */
+	uint32_t nflush;	/* 要刷新的事件数量 */
+  };
+
+
+该 ioctl 的操作分为三个阶段：
+
+首先，从内核缓冲区移除并丢弃最多 ``nflush`` 个事件。
+实际丢弃的事件数量会写回 ``nflush``。
+
+其次，除非伪设备以 ``O_NONBLOCK`` 打开，否则会一直等待，
+直到缓冲区中出现事件。
+
+第三，将最多 ``nfetch`` 个偏移量提取到 mmap 缓冲区，并存入
+``offvec`` 中。实际提取到的事件偏移数量会存回 ``nfetch``。
+
+``MON_IOCH_MFLUSH``，定义为 ``_IO(MON_IOC_MAGIC, 8)``
+
+此调用从内核缓冲区移除若干事件。其参数为要移除的事件数量。
+如果缓冲区中的事件少于请求数量，则移除所有事件，且不报告错误。
+当没有事件时也可使用。
+
+``FIONBIO``
+
+如果有需要，将来可能会实现 ``FIONBIO`` ioctl。
+
+除了 ``ioctl(2)`` 和 ``read(2)`` 之外，
+二进制 API 的特殊文件也可以用 ``select(2)`` 和 ``poll(2)`` 轮询。
+但 ``lseek(2)`` 不起作用。
+
+* 二进制 API 的内核缓冲区内存映射访问
+
+基本思想很简单：
+
+准备时，先获取当前大小，再用 ``mmap(2)`` 映射缓冲区。
+然后执行类似下面伪代码的循环::
+
+   struct mon_mfetch_arg fetch;
+   struct usbmon_packet *hdr;
+   int nflush = 0;
+   for (;;) {
+      fetch.offvec = vec; // 有 N 个 32 位字
+      fetch.nfetch = N;   // 或者少于 N
+      fetch.nflush = nflush;
+      ioctl(fd, MON_IOCX_MFETCH, &fetch);   // 同时处理错误
+      nflush = fetch.nfetch;       // 完成后要刷新这么多包
+      for (i = 0; i < nflush; i++) {
+         hdr = (struct ubsmon_packet *) &mmap_area[vec[i]];
+         if (hdr->type == '@')     // 填充包
+            continue;
+         caddr_t data = &mmap_area[vec[i]] + 64;
+         process_packet(hdr, data);
+      }
+   }
+
+
+
+因此，主要思想是每 N 个事件只执行一次 ioctl。
+
+虽然缓冲区是环形的，但返回的头和数据不会跨越缓冲区末端，
+因此上面的伪代码无需任何合并操作。
--
2.54.0

[PATCH v6 8/8] docs/zh_CN: Add CREDITS translation

[Kefan Bai]

Translate .../usb/CREDITS into Chinese

Update the translation through commit 7b2328c5a009
("docs: Fix typo in usb/CREDITS")

Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn>
Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
---
 Documentation/translations/zh_CN/usb/CREDITS | 162 +++++++++++++++++++
 1 file changed, 162 insertions(+)
 create mode 100644 Documentation/translations/zh_CN/usb/CREDITS

diff --git a/Documentation/translations/zh_CN/usb/CREDITS b/Documentation/translations/zh_CN/usb/CREDITS
new file mode 100644
index 000000000000..9df5e311d211
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/CREDITS
@@ -0,0 +1,162 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/CREDITS
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+简易 Linux USB 驱动的致谢名单：
+
+以下人员都为 Linux USB 驱动代码作出了贡献（按姓氏字母顺序排列）。
+我相信这份名单本应更长一些，但确实不容易维护。
+如需将自己加入名单，请提交补丁。
+
+  Georg Acher <acher@informatik.tu-muenchen.de>
+  David Brownell <dbrownell@users.sourceforge.net>
+  Alan Cox <alan@lxorguk.ukuu.org.uk>
+  Randy Dunlap <randy.dunlap@intel.com>
+  Johannes Erdfelt <johannes@erdfelt.com>
+  Deti Fliegl <deti@fliegl.de>
+  ham <ham@unsuave.com>
+  Bradley M Keryan <keryan@andrew.cmu.edu>
+  Greg Kroah-Hartman <greg@kroah.com>
+  Pavel Machek <pavel@suse.cz>
+  Paul Mackerras <paulus@cs.anu.edu.au>
+  Petko Manlolov <petkan@dce.bg>
+  David E. Nelson <dnelson@jump.net>
+  Vojtech Pavlik <vojtech@suse.cz>
+  Bill Ryder <bryder@sgi.com>
+  Thomas Sailer <sailer@ife.ee.ethz.ch>
+  Gregory P. Smith <greg@electricrain.com>
+  Linus Torvalds <torvalds@linux-foundation.org>
+  Roman Weissgaerber <weissg@vienna.at>
+  <Kazuki.Yasumatsu@fujixerox.co.jp>
+
+特别感谢：
+
+  Inaky Perez Gonzalez <inaky@peloncho.fis.ucm.es>
+  感谢他发起了 Linux USB 驱动开发工作，并编写了体量较大的 uusbd
+  驱动中的大部分代码。我们从那项工作中学到了很多。
+
+  NetBSD 和 FreeBSD 的 USB 开发者们
+  感谢他们加入 Linux USB 邮件列表，提供建议并分享实现经验。
+
+附加感谢：
+  还要感谢以下公司与个人在硬件、支持、时间投入和开发方面提供的捐赠与帮助
+  （摘自 Inaky 驱动原始的 THANKS 文件）：
+
+    以下公司曾帮助我们开发 Linux USB / UUSBD：
+
+        - 3Com GmbH 捐赠了一台 ISDN Pro TA，并在技术问题和测试设备方面为我
+          提供支持。没想到能得到这么大的帮助。
+
+        - USAR Systems 向我们提供了他们出色的 USB 评估套件，
+          使我们能够测试 Linux USB 驱动对最新 USB 规范的符合性。
+          USAR Systems 认识到保持开放操作系统与时俱进的重要性，
+          并以硬件支持这个项目。感谢！
+
+        - 感谢英特尔提供的宝贵帮助。
+
+        - 我们与 Cherry 合作，使 Linux 成为首个内置 USB 支持的操作系统。
+          Cherry 是全球最大的键盘制造商之一。
+
+        - CMD Technology, Inc. 慷慨捐赠了一块 CSA-6700 PCI-to-USB
+          控制卡，用于测试 OHCI 实现。
+
+        - 由于他们对我们的支持，Keytronic 可以放心，
+          他们的键盘能卖给至少 300 万 Linux 用户中的一部分。
+
+        - ing büro h doran [http://www.ibhdoran.com]!
+          在欧洲，想给主板买一个 PC 背板 USB 连接器几乎是不可能的
+          （我自己做的那个相当糟糕 :)）。现在我知道该去哪里买漂亮的 USB
+          配件了！
+
+        - Genius Germany 捐赠了一只 USB 鼠标，用于测试鼠标启动协议；
+          他们还捐赠了 F-23 数字摇杆和 NetMouse Pro。感谢！
+
+        - AVM GmbH Berlin 支持我们开发 Linux 下的 AVM ISDN Controller B1 USB 驱动。
+          AVM 是领先的 ISDN 控制器制造商，其主动式设计对包括 Linux 在内的
+          所有操作系统平台开放。
+
+        - 非常感谢 Y-E Data, Inc 捐赠的 FlashBuster-U USB 软驱，
+          使我们能够测试批量传输代码。
+
+        - 感谢 Logitech 捐赠了一只三轴 USB 鼠标。
+
+          Logitech 负责设计、制造并销售各种人机接口设备，
+          在键盘、鼠标、轨迹球、摄像头、扬声器，以及面向游戏和专业用途的
+          控制设备方面拥有悠久历史和丰富经验。
+
+          作为这些设备广为人知的供应商和销售商，他们捐赠了 USB 鼠标、
+          摇杆和扫描仪，以表明 Linux 的重要性，也让 Logitech 的客户
+          能在自己喜欢的操作系统上获得支持，并让所有 Linux 用户都能使用
+          Logitech 以及其他 USB 硬件。
+
+          Logitech 也是 1999 年 2 月 11 日维也纳 Linux 大会的官方赞助商，
+          我们将在会上展示 Linux USB 工作的最新进展。
+
+        - 感谢 CATC 提供 USB Inspector，帮助我们揭开 UHCI 内部实现中
+          那些不为人知的角落。
+
+        - 感谢 Entrega 为开发工作提供 PCI 转 USB 卡、集线器和转换器产品。
+
+        - 感谢 ConnectTech 提供 WhiteHEAT USB 转串口转换器以及相关文档，
+          让这个驱动得以写成。
+
+        - 感谢 ADMtek 提供 Pegasus 和 Pegasus II 评估板、规格说明，
+          以及驱动开发过程中的宝贵建议。
+
+    另外还要感谢以下个人（嘿，顺序不分先后 :)）
+
+        - Oren Tirosh <orenti@hishome.net>,
+          他非常耐心地听我唠叨各种 USB 疑问，还给了很多很酷的想法。
+
+        - Jochen Karrer <karrer@wpfd25.physik.uni-wuerzburg.de>,
+          指出了致命 bug，并给出了宝贵建议。
+
+        - Edmund Humemberger <ed@atnet.at>，他在公共关系与项目管理方面
+          为 Linux-USB 项目付出了巨大的努力。
+
+        - Alberto Menegazzi <flash@flash.iol.it> 正在着手编写 UUSBD 文档，加油！
+
+        - Ric Klaren <ia_ric@cs.utwente.nl> 编写了很好的入门文档，
+          与 Alberto 的作品形成良性竞争：）。
+
+        - Christian Groessler <cpg@aladdin.de>，感谢他在那些棘手细节上的帮助。
+
+        - Paul MacKerras 改进了 OHCI 实现，推动了对 iMac 的支持，
+          并提供了大量的改进意见。
+
+        - Fernando Herrera <fherrera@eurielec.etsit.upm.es>
+          负责撰写、维护并不断补充那份期待已久、独一无二又精彩的
+          UUSBD FAQ！太棒了！
+
+        - Rasca Gmelch <thron@gmx.de> 重新启用了 raw 驱动，
+          指出了一些错误，并启动了 uusbd-utils 软件包。
+
+        - Peter Dettori <dettori@ozy.dec.com>，像疯了一样挖掘 bug，
+          还提出了很多很酷的建议，太棒了！
+
+        - 自由软件与 Linux 社区的所有成员，包括 FSF、GNU 项目、
+          MIT X 联盟、TeX 社区等等，谢谢你们！
+
+        - 特别感谢 Richard Stallman 创造了 Emacs！
+
+        - 感谢 linux-usb 邮件列表的所有成员，读了那么多邮件——不开玩笑了，
+          感谢你们提出的所有建议！
+
+        - 感谢 USB Implementers Forum 成员们的帮助与支持。
+
+        - Nathan Myers <ncm@cantrip.org>，感谢他的建议！
+          （希望你喜欢 Cibeles 的派对。）
+
+        - 感谢 Linus Torvalds 创建、开发并管理 Linux。
+
+        - Mike Smith、Craig Keithley、Thierry Giron 和 Janet Schank
+          感谢他们让我认识到标准 USB 集线器其实也没那么“标准”，
+          这有助于我们在标准集线器驱动中加入厂商特定的特殊处理。
--
2.54.0

Re: [PATCH v6 2/8] docs/zh_CN: Add acm.rst translation

[Alex Shi]

On 2026/5/10 15:53, Kefan Bai wrote:
> Translate .../usb/acm.rst into Chinese
> 
> Update the translation through commit ecefae6db042
> ("docs: usb: rename files to .rst and add them to drivers-api")
> 
> Reviewed-by: Yanteng Si<siyanteng@cqsoftware.com.cn>
> Signed-off-by: Kefan Bai<baikefan@leap-io-kernel.com>
> ---
>   Documentation/translations/zh_CN/usb/acm.rst  | 136 ++++++++++++++++++
>   .../translations/zh_CN/usb/index.rst          |   2 +-
>   2 files changed, 137 insertions(+), 1 deletion(-)
>   create mode 100644 Documentation/translations/zh_CN/usb/acm.rst
> 
> diff --git a/Documentation/translations/zh_CN/usb/acm.rst b/Documentation/translations/zh_CN/usb/acm.rst
> new file mode 100644
> index 000000000000..25ec83afd25f
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/usb/acm.rst
> @@ -0,0 +1,136 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/usb/acm.rst
> +
> +:翻译:
> +
> + 白钶凡 Kefan Bai<baikefan@leap-io-kernel.com>
> +
> +:校译:
> +
> +
> +=======================
> +Linux ACM 驱动 v0.16
> +=======================
> +
> +版权所有 (c) 1999 Vojtech Pavlik<vojtech@suse.cz>
> +
> +由 SuSE 赞助
> +
> +0. 免责声明
> +~~~~~~~~~~~~~
> +本程序是自由软件；你可以在自由软件基金会发布的 GNU 通用公共许可证第 2 版，
> +或者（按你的选择）任何后续版本的条款下重新发布和/或修改它。
> +
> +发布本程序是希望它能发挥作用，但它不附带任何担保；甚至不包括对适销性
> +或特定用途适用性的默示担保。详情见 GNU 通用公共许可证。
> +
Hi Kefan,

Please align the lines above to make them look a bit cleaner. They don't 
need to be aligned perfectly, but the current formatting could be 
improved. Please apply this same standard to all patches.

Thanks
Alex

> +你应该已经随本程序收到了 GNU 通用公共许可证的副本；
> +如果没有，请致信：Free Software Foundation, Inc., 59
> +Temple Place, Suite 330, Boston, MA 02111-1307 USA。
> +
> +如需联系作者，可发送电子邮件至vojtech@suse.cz，
> +或邮寄至：
> +Vojtech Pavlik, Ucitelska 1576, Prague 8, 182 00, Czech Republic。
> +
> +为方便起见，软件包中已附带 GNU 通用公共许可证第 2 版：见 COPYING 文件。
> +
> +1. 使用方法
> +~~~~~~~~~~~~~
> +``drivers/usb/class/cdc-acm.c`` 驱动可用于符合 USB 通信设备类抽象控制模型
> +（USB CDC ACM）规范的 USB 调制解调器和 USB ISDN 终端适配器。
> +
> +许多调制解调器支持此驱动，以下是我所知道的一些型号：
> +
> +	- 3Com OfficeConnect 56k
> +	- 3Com Voice FaxModem Pro
> +	- 3Com Sportster
> +	- MultiTech MultiModem 56k
> +	- Zoom 2986L FaxModem
> +	- Compaq 56k FaxModem
> +	- ELSA Microlink 56k
> +
> +我知道有一款 ISDN 终端适配器可以与 ACM 驱动一起使用：
> +
> +	- 3Com USR ISDN Pro TA
> +
> +一些手机也可以通过 USB 连接。我知道以下机型可以正常工作：
> +
> +	- SonyEricsson K800i
> +
> +遗憾的是，许多调制解调器和大多数 ISDN TA 都使用专有接口，
> +因此无法与此驱动配合工作。购买前请先确认设备是否符合 ACM 规范。
> +
> +要使用这些调制解调器，需要加载以下模块::
> +
> +	usbcore.ko
> +	uhci-hcd.ko ohci-hcd.ko or ehci-hcd.ko
> +	cdc-acm.ko
> +
> +之后就应该可以访问这些调制解调器了。
> +应当可以使用 ``minicom``、``ppp`` 和 ``mgetty`` 与它们通信。
> +
> +2. 验证驱动是否正常工作
> +~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +第一步是检查 ``/sys/kernel/debug/usb/devices``，其内容应该类似如下::
> +
> +  T:  Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#=  1 Spd=12  MxCh= 2
> +  B:  Alloc=  0/900 us ( 0%), #Int=  0, #Iso=  0
> +  D:  Ver= 1.00 Cls=09(hub  ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
> +  P:  Vendor=0000 ProdID=0000 Rev= 0.00
> +  S:  Product=USB UHCI Root Hub
> +  S:  SerialNumber=6800
> +C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr=  0mA
> +  I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
> +  E:  Ad=81(I) Atr=03(Int.) MxPS=   8 Ivl=255ms
> +  T:  Bus=01 Lev=01 Prnt=01 Port=01 Cnt=01 Dev#=  2 Spd=12  MxCh= 0
> +  D:  Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs=  2
> +  P:  Vendor=04c1 ProdID=008f Rev= 2.07
> +  S:  Manufacturer=3Com Inc.
> +  S:  Product=3Com U.S. Robotics Pro ISDN TA
> +  S:  SerialNumber=UFT53A49BVT7
> +  C:  #Ifs= 1 Cfg#= 1 Atr=60 MxPwr=  0mA
> +  I:  If#= 0 Alt= 0 #EPs= 3 Cls=ff(vend.) Sub=ff Prot=ff Driver=acm
> +  E:  Ad=85(I) Atr=02(Bulk) MxPS=  64 Ivl=  0ms
> +  E:  Ad=04(O) Atr=02(Bulk) MxPS=  64 Ivl=  0ms
> +  E:  Ad=81(I) Atr=03(Int.) MxPS=  16 Ivl=128ms
> +C:* #Ifs= 2 Cfg#= 2 Atr=60 MxPwr=  0mA
> +  I:  If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm
> +  E:  Ad=81(I) Atr=03(Int.) MxPS=  16 Ivl=128ms
> +  I:  If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm
> +  E:  Ad=85(I) Atr=02(Bulk) MxPS=  64 Ivl=  0ms
> +  E:  Ad=04(O) Atr=02(Bulk) MxPS=  64 Ivl=  0ms
> +
> +这三行的存在很关键（以及 ``Cls=`` 字段里出现的 ``comm`` 和 ``data`` 类）；
> +它说明这是一个 ACM 设备。``Driver=acm`` 表示该设备正在使用 acm 驱动。
> +如果只看到 ``Cls=ff(vend.)``，那就无能为力了：这说明你手上的设备使用的是
> +厂商专有接口::
> +
> +    D:  Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs=  2
> +    I:  If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm
> +    I:  If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm
> +
> +在系统日志中应该可以看到::
> +
> +  usb.c: USB new device connect, assigned device number 2
> +  usb.c: kmalloc IF c7691fa0, numif 1
> +  usb.c: kmalloc IF c7b5f3e0, numif 2
> +  usb.c: skipped 4 class/vendor specific interface descriptors
> +  usb.c: new device strings: Mfr=1, Product=2, SerialNumber=3
> +  usb.c: USB device number 2 default language ID 0x409
> +  Manufacturer: 3Com Inc.
> +  Product: 3Com U.S. Robotics Pro ISDN TA
> +  SerialNumber: UFT53A49BVT7
> +  acm.c: probing config 1
> +  acm.c: probing config 2
> +  ttyACM0: USB ACM device
> +  acm.c: acm_control_msg: rq: 0x22 val: 0x0 len: 0x0 result: 0
> +  acm.c: acm_control_msg: rq: 0x20 val: 0x0 len: 0x7 result: 7
> +  usb.c: acm driver claimed interface c7b5f3e0
> +  usb.c: acm driver claimed interface c7b5f3f8
> +  usb.c: acm driver claimed interface c7691fa0
> +
> +如果以上都正常，请启动 ``minicom``，把它配置为连接 ``ttyACM`` 设备，
> +然后尝试输入 ``at``。如果返回 ``OK``，说明一切工作正常。
> diff --git a/Documentation/translations/zh_CN/usb/index.rst b/Documentation/translations/zh_CN/usb/index.rst
> index 7cfe99a4dc0a..449e8ac2dff0 100644
> --- a/Documentation/translations/zh_CN/usb/index.rst
> +++ b/Documentation/translations/zh_CN/usb/index.rst
> @@ -17,10 +17,10 @@ USB 支持
>   .. toctree::
>       :maxdepth: 1
> 
> +    acm
> 
>   Todolist:
> 
> -* acm
>   * authorization
>   * chipidea
>   * dwc3
> --
> 2.54.0
>