* [PATCH v4 0/8] Add Chinese translation for USB subsystem
@ 2025-12-02 11:56 Kefan Bai
2025-12-02 11:56 ` [PATCH v4 1/8] docs/zh_CN: Add index.rst translation Kefan Bai
` (8 more replies)
0 siblings, 9 replies; 20+ messages in thread
From: Kefan Bai @ 2025-12-02 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc, doubled
This patch set adds Chinese translations for the USB documentation.
Changes in v4:
- shorten those overlong title underline/overline symbols
- Remove CREDITS section from index.rst
Changes in v3:
- Updated the signoff to my full legal name,
as requested by Jonathan Corbet.
- Reviewed and fixed the RST syntax to resolve the patch issues
noted by Alex Shi.
- Kept the number of translated files to eight
to make submission and review smoother.
- Link to v3: https://lore.kernel.org/all/cover.1763984424.git.baikefan@leap-io-kernel.com/
Changes in v2:
- Update [PATCH 01/25] docs/zh_CN: Add index.rst translation
to include corresponding updates in
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 | 153 +++++++
Documentation/translations/zh_CN/usb/acm.rst | 137 +++++++
.../translations/zh_CN/usb/authorization.rst | 125 ++++++
.../translations/zh_CN/usb/chipidea.rst | 142 +++++++
Documentation/translations/zh_CN/usb/dwc3.rst | 60 +++
Documentation/translations/zh_CN/usb/ehci.rst | 216 ++++++++++
.../translations/zh_CN/usb/index.rst | 54 +++
.../translations/zh_CN/usb/usbmon.rst | 380 ++++++++++++++++++
9 files changed, 1268 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.52.0
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH v4 1/8] docs/zh_CN: Add index.rst translation
2025-12-02 11:56 [PATCH v4 0/8] Add Chinese translation for USB subsystem Kefan Bai
@ 2025-12-02 11:56 ` Kefan Bai
2025-12-03 2:34 ` Yanteng Si
2025-12-02 11:56 ` [PATCH v4 2/8] docs/zh_CN: Add acm.rst translation Kefan Bai
` (7 subsequent siblings)
8 siblings, 1 reply; 20+ messages in thread
From: Kefan Bai @ 2025-12-02 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc, doubled
Translate .../usb/index.rst into Chinese and update subsystem-apis.rst
Update the translation through commit c26cee817f8b
("usb: gadget: f_fs: add capability for dfu functional descriptor")
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..71e822e464d4
--- /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
+
+ acm
+ authorization
+ chipidea
+ dwc3
+ ehci
+ usbmon
+
+Todolist:
+
+* 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.52.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH v4 2/8] docs/zh_CN: Add acm.rst translation
2025-12-02 11:56 [PATCH v4 0/8] Add Chinese translation for USB subsystem Kefan Bai
2025-12-02 11:56 ` [PATCH v4 1/8] docs/zh_CN: Add index.rst translation Kefan Bai
@ 2025-12-02 11:56 ` Kefan Bai
2025-12-02 11:56 ` [PATCH v4 3/8] docs/zh_CN: Add authorization.rst translation Kefan Bai
` (6 subsequent siblings)
8 siblings, 0 replies; 20+ messages in thread
From: Kefan Bai @ 2025-12-02 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc, doubled
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 | 137 +++++++++++++++++++
1 file changed, 137 insertions(+)
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..62299f62f947
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/acm.rst
@@ -0,0 +1,137 @@
+.. 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. 免责声明
+~~~~~~~~~~~~~
+本程序是自由软件；您可以使用自由软件基金会发布的第2版GNU通用公共许可证，
+或由您选择任何更高版本的许可证，对本程序进行再发布和/或修改。
+
+我们希望本程序有用，但不提供任何担保；甚至不包含对适销性或适用于特定目的的默示性担保。
+更多细节请参阅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 ISDN终端适配器，
+这些设备符合USB通用串行总线通信设备类（Universal Serial Bus
+Communication Device Class）的抽象控制模型（Abstract Control Model，
+USB CDC ACM）规范。
+
+许多调制解调器支持此驱动，以下是我所知道的一些型号：
+
+ - 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终端适配器使用专有接口，
+因此无法与此驱动兼容。购买前请确认设备是否符合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"，则说明一切工作正常。
--
2.52.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH v4 3/8] docs/zh_CN: Add authorization.rst translation
2025-12-02 11:56 [PATCH v4 0/8] Add Chinese translation for USB subsystem Kefan Bai
2025-12-02 11:56 ` [PATCH v4 1/8] docs/zh_CN: Add index.rst translation Kefan Bai
2025-12-02 11:56 ` [PATCH v4 2/8] docs/zh_CN: Add acm.rst translation Kefan Bai
@ 2025-12-02 11:56 ` Kefan Bai
2025-12-03 2:29 ` Yanteng Si
2025-12-02 11:56 ` [PATCH v4 4/8] docs/zh_CN: Add chipidea.rst translation Kefan Bai
` (5 subsequent siblings)
8 siblings, 1 reply; 20+ messages in thread
From: Kefan Bai @ 2025-12-02 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc, doubled
Translate .../usb/authorization.rst into Chinese
Update the translation through commit f176638af476
("USB: Remove Wireless USB and UWB documentation")
Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/authorization.rst | 125 ++++++++++++++++++
1 file changed, 125 insertions(+)
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..4a8b743480ae
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/authorization.rst
@@ -0,0 +1,125 @@
+.. 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设备时，系统会配置该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是否匹配某个值，
+是最差的安全验证方式（但对于想要破解的人却是最容易的）。
+如果你需要真正安全的方案，应使用加密、证书认证等手段。
+一个针对存储密钥的简单示例::
+
+ 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来手动触发驱动程序进行探测。
+ 对于使用多个接口的驱动程序，需要先对所有使用的接口进行授权。
+ 之后应探测驱动程序。这样做可以避免副作用。
--
2.52.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH v4 4/8] docs/zh_CN: Add chipidea.rst translation
2025-12-02 11:56 [PATCH v4 0/8] Add Chinese translation for USB subsystem Kefan Bai
` (2 preceding siblings ...)
2025-12-02 11:56 ` [PATCH v4 3/8] docs/zh_CN: Add authorization.rst translation Kefan Bai
@ 2025-12-02 11:56 ` Kefan Bai
2025-12-03 5:31 ` Yanteng Si
2025-12-02 11:56 ` [PATCH v4 5/8] docs/zh_CN: Add dwc3.rst translation Kefan Bai
` (4 subsequent siblings)
8 siblings, 1 reply; 20+ messages in thread
From: Kefan Bai @ 2025-12-02 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc, doubled
Translate .../usb/chipidea.rst into Chinese
Update the translation through commit e4157519ad46
("Documentation: usb: correct spelling")
Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/chipidea.rst | 142 ++++++++++++++++++
1 file changed, 142 insertions(+)
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..88f80489fe57
--- /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开发板上，演示如何通过sys输入文件
+来测试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设备应切换为host并枚举A设备。
+
+4) 把A设备切换为host
+
+ 在B设备上执行::
+
+ echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req
+
+ 或者通过HNP轮询机制：B-Host可以检测到A外设想成为host的意愿，
+ 从而由A外设触发角色切换。在A设备上执行::
+ 或者通过HNP轮询机制：B-Host可以检测到A外设想切换为host角色的意愿，
+ 并通过A外设对轮询的响应来触发角色切换。
+ 这可以通过在A设备上执行::
+
+ echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req
+
+ A设备应切换回host并枚举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作为系统唤醒源
+----------------------------
+下面是在imx6平台上使能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唤醒，
+你可以使用下面的脚本来启用USB唤醒::
+
+ for i in $(find /sys -name wakeup | grep usb);do echo enabled > $i;done;
--
2.52.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH v4 5/8] docs/zh_CN: Add dwc3.rst translation
2025-12-02 11:56 [PATCH v4 0/8] Add Chinese translation for USB subsystem Kefan Bai
` (3 preceding siblings ...)
2025-12-02 11:56 ` [PATCH v4 4/8] docs/zh_CN: Add chipidea.rst translation Kefan Bai
@ 2025-12-02 11:56 ` Kefan Bai
2025-12-04 2:28 ` Yanteng Si
2025-12-02 11:56 ` [PATCH v4 6/8] docs/zh_CN: Add ehci.rst translation Kefan Bai
` (3 subsequent siblings)
8 siblings, 1 reply; 20+ messages in thread
From: Kefan Bai @ 2025-12-02 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc, doubled
Translate .../usb/dwc3.rst into Chinese
Update the translation through commit ecefae6db042
("docs: usb: rename files to .rst and add them to drivers-api")
Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
---
Documentation/translations/zh_CN/usb/dwc3.rst | 60 +++++++++++++++++++
1 file changed, 60 insertions(+)
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..700aee545559
--- /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命令大约需要~1ms才能完成。
+ 当前代码会一直自旋等待命令完成，这是不好的设计。
+
+ 实现思路：
+
+ - DWC core实现了一个用于按端点解复用中断的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()返回后，确认事件计数器，最终完成中断处理。
+
+ - 设备的中断处理线程
+ 无
+
+ - EP中断的处理主程序
+ 读取事件并尝试处理它。所有需要休眠的操作都交给线程处理。
+ 事件保存在每个端点的数据结构中。
+ 需要注意：一旦把事件交给线程去处理，就要注意不要自己再去处理它，
+ 否则可能会导致低优先级的事件先于高优先级事件被处理。
+
+ - EP中断的处理线程
+ 处理剩余的EP工作，这些工作可能会导致休眠，例如等待命令完成。
+
+ 延迟:
+
+ 不应该增加延迟，因为中断线程具有较高优先级，会在用户空间普通任务之前运行
+ （除非用户更改了调度优先级）。
--
2.52.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH v4 6/8] docs/zh_CN: Add ehci.rst translation
2025-12-02 11:56 [PATCH v4 0/8] Add Chinese translation for USB subsystem Kefan Bai
` (4 preceding siblings ...)
2025-12-02 11:56 ` [PATCH v4 5/8] docs/zh_CN: Add dwc3.rst translation Kefan Bai
@ 2025-12-02 11:56 ` Kefan Bai
2025-12-04 2:35 ` Yanteng Si
2025-12-02 11:56 ` [PATCH v4 7/8] docs/zh_CN: Add usbmon.rst translation Kefan Bai
` (2 subsequent siblings)
8 siblings, 1 reply; 20+ messages in thread
From: Kefan Bai @ 2025-12-02 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc, doubled
Translate .../usb/ehci.rst into Chinese
Update the translation through commit 570eb861243c
("docs: usb: replace some characters")
Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
---
Documentation/translations/zh_CN/usb/ehci.rst | 216 ++++++++++++++++++
1 file changed, 216 insertions(+)
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..492fc45341f4
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/ehci.rst
@@ -0,0 +1,216 @@
+.. 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标准，它定义了三种传输速率：
+
+ - 高速 480 Mbit/sec (60 MByte/sec)
+ - 全速 12 Mbit/sec (1.5 MByte/sec)
+ - 低速 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存储设备已可使用（在2.4版EHCI驱动下性能良好），
+集线器从2001年底开始可用，而其他类型的高速设备似乎因USB 2.0原生硬件
+普及较慢而推迟上市。从2002年初开始，带USB 2.0的系统陆续上市，
+并在2002年下半年变得更加普及。
+
+注意：USB 2.0的支持不仅仅包含EHCI，还需要对Linux-USB核心API进行一些修改，
+包括Hub驱动，但这些修改通常不会影响USB核心对USB设备驱动暴露的基本API。
+
+- David Brownell
+ <dbrownell@users.sourceforge.net>
+
+
+功能性
+======
+
+该驱动会定期在x86硬件上进行测试，并已在PPC硬件上使用，因此大小端问题应已解决。
+相信它已经处理好所有PCI相关的细节，
+因此在具有特殊DMA映射问题的系统上I/O也应能正常运行。
+
+传输类型
+--------
+
+截至本文撰写时，该驱动应该已经可以很好地处理所有的控制传输、批量传输和中断传输，
+包括通过USB 2.0 Hub中的事务转换器与USB 1.1设备的通信，但仍可能存在bug。
+
+已经实现对高速等时ISO传输的支持，但截至本文撰写时，还没有Linux驱动程序使用该支持。
+
+通过事务转换器实现的全速等时传输目前尚未支持。
+需要注意的是，用于全速设备的等时拆分事务与高速等时传输
+在EHCI中采用完全不同的数据结构，因此相关代码几乎无
+法共用。因此，即使连接到高速总线，目前大多数USB音频和视频类设备
+也无法正常使用等时传输功能。
+
+驱动行为
+--------
+
+所有类型的传输都可以排队。
+这意味着来自不同接口（或通过 usbfs）的控制传输不会互相干扰，
+并且中断传输可以使用1帧的周期，而无需担心由于中断处理成本导致的数据丢失。
+
+
+EHCI根集线器代码会将USB 1.1设备交给其伴随控制器处理。
+EHCI驱动无需了解其他控制器的驱动程序；
+已经正常工作的OHCI或UHCI驱动，无需因为EHCI的存在而做任何修改。
+
+存在一些电源管理相关的问题；挂起/恢复行为目前不太正确。
+
+此外，在调度周期性事务（中断和等时传输）时采用了一些简化处理。
+这些简化会限制可调度的周期性传输数量，并且无法使用小于1帧的轮询间隔。
+
+使用方式
+=========
+
+假设你有一个EHCI控制器，并且已将此驱动编译为模块，可如下加载::
+
+ # modprobe ehci-hcd
+
+卸载方式::
+
+ # rmmod ehci-hcd
+
+你还应加载一个伴随控制器的驱动，例如ohci-hcd或uhci-hcd。
+如果EHCI驱动出现问题，只需卸载对应模块，
+伴随控制器驱动就会接手之前EHCI处理的所有设备（但速度更慢）。
+
+传递给modprobe的模块参数：
+
+ log2_irq_thresh (默认 0):
+ 控制默认中断延迟的对数值（以微帧为单位）。
+ 默认值0表示1个微帧（125 微秒）。
+ 最大值6表示2^6=64个微帧。
+ 该值控制EHCI控制器发出中断的频率。
+
+如果你在2.5内核上使用此驱动，并且启用了USB调试支持，
+你将在任何EHCI控制器的sysfs目录中看到三个文件：
+
+"async"
+输出异步调度队列，用于控制传输和批量传输。
+显示每个活动的qh和挂起的qtd，通常每个urb一个qtd。
+（对usb存储进行磁盘I/O时看看，可看到请求队列！）
+
+"periodic"
+输出周期性调度队列，用于中断传输和等时传输。不显示qtd。
+
+"registers"
+显示控制器寄存器状态。
+
+
+设备驱动程序通常不需要关心自己是否运行在EHCI上，
+但可能需要检查usb_device->speed是否是USB_SPEED_HIGH。
+高速设备可以执行全速（或低速）设备无法完成的操作，
+例如高带宽的周期性传输（中断传输或等时传输）。
+此外，设备描述符中的某些值（如周期性传输的轮询间隔）在高速模式下使用不同的编码方式。
+
+务必通过USB 2.0集线器测试设备驱动。
+当使用事务转换器时，这些集线器会以不同方式报告某些故障（如断开连接）。
+一些驱动在遇到与OHCI或UHCI报告不同的故障时可能会表现异常。
+
+软件性能
+========
+
+USB 2.0吞吐量受两个主要因素制约：主机控制器处理请求的速度，以及设备响应请求的速度。
+所有设备都遵循480Mbit/sec的原始传输速率，
+但总吞吐量还会受到诸如单个高速数据包之间的延迟、驱动程序调度策略，
+以及系统整体负载等因素的影响。
+延迟也是性能考量因素。
+
+批量传输通常用于对吞吐量有严格要求的场景。
+需要注意的是，批量传输总是以512字节的数据包为单位，
+并且在一个USB 2.0微帧中最多可容纳13个这样的数据包。
+八个USB 2.0微帧构成一个USB 1.1帧；
+一个微帧的时间为1毫秒 ÷ 8 = 125微秒。
+
+因此，当硬件和设备驱动软件都允许时，
+批量传输可提供超过50 MByte/sec的带宽。
+周期性传输模式（等时传输和中断传输）允许使用更大的数据包，
+从而使传输速率接近标称的480MBit/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队列满。
+这意味着发出较大的请求，或在需要发出一系列小请求时，使用批量排队（bulk queuing）。
+如果驱动未做到这一点，那么会直接从性能结果上表现出来。
+
+
+在典型场景下，使用usb_bulk_msg() 以4KB块循环写入，
+会浪费超过一半的USB 2.0带宽。
+I/O完成与驱动发出下一次请求之间的延迟通常比一次I/O操作所需的时间更长。
+如果同样的循环改用16KB块，会有所改善；使用128KB块的序列则能大幅减少浪费。
+
+
+与其依赖如此大的I/O缓冲区来提高同步I/O的效率，
+不如直接向主机控制器队列多个（批量）请求，并等待它们全部完成，或在出错时取消。
+这种URB排队方式对所有USB 1.1主机控制器驱动也适用。
+
+
+在Linux 2.5内核中，定义了新的 usb_sg_*() API 调用；
+它们会将scatterlist中的所有缓冲区排入队列。
+它们还使用scatterlist的DMA映射（可能会使用IOMMU）并减少中断次数，
+这些都有助于高速传输尽可能高效地运行。
+
+待办：
+ 中断传输和等时（ISO）传输的性能问题。
+ 这些周期性传输都是完全调度的，因此，主要问题可能在于如何触发高带宽模式。
+
+待办：
+ 通过sysfs的uframe_periodic_max参数，可以分配超过标准80%的周期性带宽。
+ 后续将对此进行说明。
--
2.52.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH v4 7/8] docs/zh_CN: Add usbmon.rst translation
2025-12-02 11:56 [PATCH v4 0/8] Add Chinese translation for USB subsystem Kefan Bai
` (5 preceding siblings ...)
2025-12-02 11:56 ` [PATCH v4 6/8] docs/zh_CN: Add ehci.rst translation Kefan Bai
@ 2025-12-02 11:56 ` Kefan Bai
2025-12-04 2:47 ` Yanteng Si
2025-12-02 11:56 ` [PATCH v4 8/8] docs/zh_CN: Add CREDITS translation Kefan Bai
2025-12-04 2:41 ` [PATCH v4 0/8] Add Chinese translation for USB subsystem Yanteng Si
8 siblings, 1 reply; 20+ messages in thread
From: Kefan Bai @ 2025-12-02 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc, doubled
Translate .../usb/usbmon.rst into Chinese
Update the translation through commit 788183a6e8b0
("docs: usb: fix literal block marker in usbmon verification example")
Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/usbmon.rst | 380 ++++++++++++++++++
1 file changed, 380 insertions(+)
create mode 100644 Documentation/translations/zh_CN/usb/usbmon.rst
diff --git a/Documentation/translations/zh_CN/usb/usbmon.rst b/Documentation/translations/zh_CN/usb/usbmon.rst
new file mode 100644
index 000000000000..c2eebaef67ff
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/usbmon.rst
@@ -0,0 +1,380 @@
+.. 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：文本和二进制。二进制API通过/dev命名空间中的字符设备提供，
+并且是一个ABI。文本API自内核2.6.35起废弃，但为了兼容仍然可用。
+
+如何使用usbmon收集原始文本追踪信息
+==================================
+
+与数据包套接字不同，usbmon提供了一种接口，可以输出文本格式的追踪信息。
+这样做有两个目的：
+第一，在更完善的格式最终确定之前，它作为工具间通用的追踪交换格式；
+第二，在不使用工具的情况下，人们也可以直接阅读这些信息。
+
+要收集原始文本追踪信息，请按以下步骤进行操作。
+
+1. 准备
+--------
+
+首先必须在你的内核配置中启用debugfs，之后挂载debugfs。
+如果usbmon是作为模块构建的，那么还要加载usbmon模块。
+如果usbmon已经编入内核，则无需加载usbmon模块。
+
+命令示例::
+
+ # mount -t debugfs none_debugs /sys/kernel/debug
+ # modprobe usbmon
+ #
+
+确认总线socket是否存在::
+ # 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行。
+通常你可以通过vendor字符串来查找。如果你有许多类似设备，
+可以拔掉其中一个设备，并比较前后两次
+/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微秒更差。
+
+- 事件类型。表示事件的格式，而不是URB的类型。
+ 有效类型包括：S - 提交，C - 回调，E - 提交错误。
+
+- Address字段（以前称为pipe）。包含四个冒号分隔的字段：
+ URB类型与方向，总线号，设备地址，端点号。
+ 类型与方向的编码如下：
+
+ == == =====================
+ Ci Co 控制input/output
+ Zi Zo 等时input/output
+ Ii Io 中断input/output
+ Bi Bo 批量input/output
+ == == =====================
+
+ 总线号、设备地址和端点号使用十进制，但可能有前导零。
+
+- URB状态字。这个字段可以是一个字母，也可以是由冒号分隔的几个数字：
+ URB状态、间隔（interval）、起始帧（start frame）以及错误计数（error count）。
+ 与地址字段不同，除了状态之外，其余所有字段都是可选的。
+ interval仅在中断和等时URB中打印；
+ 起始帧仅在等时URB中打印；
+ 错误数量仅在等时回调事件中打印。
+
+ 状态字段是一个十进制数字，有时为负数，对应URB的状态字段。
+ 对于提交（submission），这个字段没有实际意义，
+ 但是为了便于脚本解析，所以依然存在。
+ 当发生错误时，该字段包含错误码。
+
+ 在提交控制数据包的情况下，该字段包含一个Setup Tag，而不是一组数字。
+ 判断是否存在Setup Tag很容易，因为它从来不是数字。
+ 因此，如果脚本在该字段中发现一组数字，
+ 它们会继续读取数据长度（等时URB除外）。
+ 如果发现的是其他内容，比如一个字母，
+ 那么脚本会在读取数据长度或等时描述符之前，会先读取Setup包。
+
+- Setup包由5个字段构成：bmRequestType, bRequest, wValue, wIndex, wLength。
+ 符合USB 2.0 规范。如果Setup标签为'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
+
+如有需要，将来可能实现ioctl FIONBIO。
+
+除了ioctl(2)和read(2)，可以使用
+select(2)和poll(2)轮询二进制API的特殊文件。
+但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.52.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH v4 8/8] docs/zh_CN: Add CREDITS translation
2025-12-02 11:56 [PATCH v4 0/8] Add Chinese translation for USB subsystem Kefan Bai
` (6 preceding siblings ...)
2025-12-02 11:56 ` [PATCH v4 7/8] docs/zh_CN: Add usbmon.rst translation Kefan Bai
@ 2025-12-02 11:56 ` Kefan Bai
2025-12-04 2:51 ` Yanteng Si
2025-12-04 2:41 ` [PATCH v4 0/8] Add Chinese translation for USB subsystem Yanteng Si
8 siblings, 1 reply; 20+ messages in thread
From: Kefan Bai @ 2025-12-02 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc, doubled
Translate .../usb/CREDITS into Chinese
Update the translation through commit 7b2328c5a009
("docs: Fix typo in usb/CREDITS")
Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
---
Documentation/translations/zh_CN/usb/CREDITS | 153 +++++++++++++++++++
1 file changed, 153 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..ae8d489e62ff
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/CREDITS
@@ -0,0 +1,153 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/CREDITS
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+简易版Linux USB驱动致谢名单：
+
+以下人员为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驱动。我们从那项工作中学到
+ 了很多东西。
+
+ The 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的支持，使其键盘能够被数百万Linux用户使用。
+
+ - ing büro h doran [http://www.ibhdoran.com]!
+ 在欧洲几乎买不到后置USB接口面板的主板，而我自制的版本很糟糕 ：）。
+ 感谢他们提供了漂亮的USB配件！
+
+ - Genius Germany捐赠了一只USB鼠标用于测试鼠标启动协议，并提供了
+ F-23数字摇杆和NetMouse Pro。感谢！
+
+ - AVM GmbH Berlin支持我们开发Linux下的AVM ISDN控制器B1 USB驱动。
+ AVM是领先的ISDN控制器制造商，其主动式设计对包括Linux在内的
+ 所有操作系统开放。
+
+ - 非常感谢Y-E Data, Inc捐赠的FlashBuster-U USB软驱，
+ 使我们能够测试bulk传输代码。
+
+ - 感谢Logitech捐赠了一只三轴USB鼠标。
+
+ Logitech设计、制造并销售各种人机接口设备，
+ 如键盘、鼠标、轨迹球、摄像头、扬声器及游戏控制设备。
+
+ 感谢他们捐赠了USB鼠标、摇杆和扫描仪，
+ 以支持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论坛成员们的帮助与支持。
+
+ - Nathan Myers <ncm@cantrip.org>，感谢他的建议！（希望你喜欢Cibeles的派对）
+
+ - 感谢Linus Torvalds创建、开发并管理Linux。
+
+ - Mike Smith, Craig Keithley, Thierry Giron和Janet Schank
+ 感谢他们让我明白标准USB集线器其实并没有那么标准，
+ 这有助于我们在标准集线器驱动中加入厂商特定的特性。
--
2.52.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* Re: [PATCH v4 3/8] docs/zh_CN: Add authorization.rst translation
2025-12-02 11:56 ` [PATCH v4 3/8] docs/zh_CN: Add authorization.rst translation Kefan Bai
@ 2025-12-03 2:29 ` Yanteng Si
0 siblings, 0 replies; 20+ messages in thread
From: Yanteng Si @ 2025-12-03 2:29 UTC (permalink / raw)
To: Kefan Bai, alexs; +Cc: dzm91, corbet, linux-doc, doubled
在 2025/12/2 19:56, Kefan Bai 写道:
> Translate .../usb/authorization.rst into Chinese
>
> Update the translation through commit f176638af476
> ("USB: Remove Wireless USB and UWB documentation")
>
> Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn>
Thanks,
Yanteng
> ---
> .../translations/zh_CN/usb/authorization.rst | 125 ++++++++++++++++++
> 1 file changed, 125 insertions(+)
> 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..4a8b743480ae
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/usb/authorization.rst
> @@ -0,0 +1,125 @@
> +.. 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设备时，系统会配置该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是否匹配某个值，
> +是最差的安全验证方式（但对于想要破解的人却是最容易的）。
> +如果你需要真正安全的方案，应使用加密、证书认证等手段。
> +一个针对存储密钥的简单示例::
> +
> + 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来手动触发驱动程序进行探测。
> + 对于使用多个接口的驱动程序，需要先对所有使用的接口进行授权。
> + 之后应探测驱动程序。这样做可以避免副作用。
> --
> 2.52.0
>
>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH v4 1/8] docs/zh_CN: Add index.rst translation
2025-12-02 11:56 ` [PATCH v4 1/8] docs/zh_CN: Add index.rst translation Kefan Bai
@ 2025-12-03 2:34 ` Yanteng Si
2025-12-05 7:24 ` BaiKefan
0 siblings, 1 reply; 20+ messages in thread
From: Yanteng Si @ 2025-12-03 2:34 UTC (permalink / raw)
To: Kefan Bai, alexs; +Cc: dzm91, corbet, linux-doc, doubled
在 2025/12/2 19:56, Kefan Bai 写道:
> Translate .../usb/index.rst into Chinese and update subsystem-apis.rst
>
> Update the translation through commit c26cee817f8b
> ("usb: gadget: f_fs: add capability for dfu functional descriptor")
>
> 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..71e822e464d4
> --- /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
> +
> + acm
> + authorization
> + chipidea
> + dwc3
> + ehci
> + usbmon
They shouldn't appear here right now; instead, they should be scattered across the translation patches. If only this patch is applied, a compilation error will occur.
Thanks,
Yanteng
> +
> +Todolist:
> +
> +* 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.52.0
>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH v4 4/8] docs/zh_CN: Add chipidea.rst translation
2025-12-02 11:56 ` [PATCH v4 4/8] docs/zh_CN: Add chipidea.rst translation Kefan Bai
@ 2025-12-03 5:31 ` Yanteng Si
0 siblings, 0 replies; 20+ messages in thread
From: Yanteng Si @ 2025-12-03 5:31 UTC (permalink / raw)
To: Kefan Bai, alexs; +Cc: dzm91, corbet, linux-doc, doubled
在 2025/12/2 19:56, Kefan Bai 写道:
> Translate .../usb/chipidea.rst into Chinese
>
> Update the translation through commit e4157519ad46
> ("Documentation: usb: correct spelling")
>
> Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
> ---
> .../translations/zh_CN/usb/chipidea.rst | 142 ++++++++++++++++++
> 1 file changed, 142 insertions(+)
> 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..88f80489fe57
> --- /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开发板上，演示如何通过sys输入文件
> +来测试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设备应切换为host并枚举A设备。
> +
> +4) 把A设备切换为host
> +
> + 在B设备上执行::
> +
> + echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req
> +
> + 或者通过HNP轮询机制：B-Host可以检测到A外设想成为host的意愿，
> + 从而由A外设触发角色切换。在A设备上执行::
> + 或者通过HNP轮询机制：B-Host可以检测到A外设想切换为host角色的意愿，
> + 并通过A外设对轮询的响应来触发角色切换。
> + 这可以通过在A设备上执行::
> +
> + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req
> +
> + A设备应切换回host并枚举B设备。
> +
> +5) 拔掉 B设备（拔掉 micro B 插头），在10秒内重新插入；
> + A设备 应重新枚举B设备。
Del space?
Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn>
Thanks,
Yanteng
> +
> +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作为系统唤醒源
> +----------------------------
> +下面是在imx6平台上使能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唤醒，
> +你可以使用下面的脚本来启用USB唤醒::
> +
> + for i in $(find /sys -name wakeup | grep usb);do echo enabled > $i;done;
> --
> 2.52.0
>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH v4 5/8] docs/zh_CN: Add dwc3.rst translation
2025-12-02 11:56 ` [PATCH v4 5/8] docs/zh_CN: Add dwc3.rst translation Kefan Bai
@ 2025-12-04 2:28 ` Yanteng Si
0 siblings, 0 replies; 20+ messages in thread
From: Yanteng Si @ 2025-12-04 2:28 UTC (permalink / raw)
To: Kefan Bai, alexs; +Cc: dzm91, corbet, linux-doc, doubled
在 2025/12/2 19:56, 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")
>
> Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>、
Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn>
Thanks,
Yanteng
> ---
> Documentation/translations/zh_CN/usb/dwc3.rst | 60 +++++++++++++++++++
> 1 file changed, 60 insertions(+)
> 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..700aee545559
> --- /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命令大约需要~1ms才能完成。
> + 当前代码会一直自旋等待命令完成，这是不好的设计。
> +
> + 实现思路：
> +
> + - DWC core实现了一个用于按端点解复用中断的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()返回后，确认事件计数器，最终完成中断处理。
> +
> + - 设备的中断处理线程
> + 无
> +
> + - EP中断的处理主程序
> + 读取事件并尝试处理它。所有需要休眠的操作都交给线程处理。
> + 事件保存在每个端点的数据结构中。
> + 需要注意：一旦把事件交给线程去处理，就要注意不要自己再去处理它，
> + 否则可能会导致低优先级的事件先于高优先级事件被处理。
> +
> + - EP中断的处理线程
> + 处理剩余的EP工作，这些工作可能会导致休眠，例如等待命令完成。
> +
> + 延迟:
> +
> + 不应该增加延迟，因为中断线程具有较高优先级，会在用户空间普通任务之前运行
> + （除非用户更改了调度优先级）。
> --
> 2.52.0
>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH v4 6/8] docs/zh_CN: Add ehci.rst translation
2025-12-02 11:56 ` [PATCH v4 6/8] docs/zh_CN: Add ehci.rst translation Kefan Bai
@ 2025-12-04 2:35 ` Yanteng Si
0 siblings, 0 replies; 20+ messages in thread
From: Yanteng Si @ 2025-12-04 2:35 UTC (permalink / raw)
To: Kefan Bai, alexs; +Cc: dzm91, corbet, linux-doc, doubled
在 2025/12/2 19:56, Kefan Bai 写道:
> Translate .../usb/ehci.rst into Chinese
>
> Update the translation through commit 570eb861243c
> ("docs: usb: replace some characters")
>
> Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn>
Thanks,
Yanteng
> ---
> Documentation/translations/zh_CN/usb/ehci.rst | 216 ++++++++++++++++++
> 1 file changed, 216 insertions(+)
> 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..492fc45341f4
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/usb/ehci.rst
> @@ -0,0 +1,216 @@
> +.. 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标准，它定义了三种传输速率：
> +
> + - 高速 480 Mbit/sec (60 MByte/sec)
> + - 全速 12 Mbit/sec (1.5 MByte/sec)
> + - 低速 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存储设备已可使用（在2.4版EHCI驱动下性能良好），
> +集线器从2001年底开始可用，而其他类型的高速设备似乎因USB 2.0原生硬件
> +普及较慢而推迟上市。从2002年初开始，带USB 2.0的系统陆续上市，
> +并在2002年下半年变得更加普及。
> +
> +注意：USB 2.0的支持不仅仅包含EHCI，还需要对Linux-USB核心API进行一些修改，
> +包括Hub驱动，但这些修改通常不会影响USB核心对USB设备驱动暴露的基本API。
> +
> +- David Brownell
> + <dbrownell@users.sourceforge.net>
> +
> +
> +功能性
> +======
> +
> +该驱动会定期在x86硬件上进行测试，并已在PPC硬件上使用，因此大小端问题应已解决。
> +相信它已经处理好所有PCI相关的细节，
> +因此在具有特殊DMA映射问题的系统上I/O也应能正常运行。
> +
> +传输类型
> +--------
> +
> +截至本文撰写时，该驱动应该已经可以很好地处理所有的控制传输、批量传输和中断传输，
> +包括通过USB 2.0 Hub中的事务转换器与USB 1.1设备的通信，但仍可能存在bug。
> +
> +已经实现对高速等时ISO传输的支持，但截至本文撰写时，还没有Linux驱动程序使用该支持。
> +
> +通过事务转换器实现的全速等时传输目前尚未支持。
> +需要注意的是，用于全速设备的等时拆分事务与高速等时传输
> +在EHCI中采用完全不同的数据结构，因此相关代码几乎无
> +法共用。因此，即使连接到高速总线，目前大多数USB音频和视频类设备
> +也无法正常使用等时传输功能。
> +
> +驱动行为
> +--------
> +
> +所有类型的传输都可以排队。
> +这意味着来自不同接口（或通过 usbfs）的控制传输不会互相干扰，
> +并且中断传输可以使用1帧的周期，而无需担心由于中断处理成本导致的数据丢失。
> +
> +
> +EHCI根集线器代码会将USB 1.1设备交给其伴随控制器处理。
> +EHCI驱动无需了解其他控制器的驱动程序；
> +已经正常工作的OHCI或UHCI驱动，无需因为EHCI的存在而做任何修改。
> +
> +存在一些电源管理相关的问题；挂起/恢复行为目前不太正确。
> +
> +此外，在调度周期性事务（中断和等时传输）时采用了一些简化处理。
> +这些简化会限制可调度的周期性传输数量，并且无法使用小于1帧的轮询间隔。
> +
> +使用方式
> +=========
> +
> +假设你有一个EHCI控制器，并且已将此驱动编译为模块，可如下加载::
> +
> + # modprobe ehci-hcd
> +
> +卸载方式::
> +
> + # rmmod ehci-hcd
> +
> +你还应加载一个伴随控制器的驱动，例如ohci-hcd或uhci-hcd。
> +如果EHCI驱动出现问题，只需卸载对应模块，
> +伴随控制器驱动就会接手之前EHCI处理的所有设备（但速度更慢）。
> +
> +传递给modprobe的模块参数：
> +
> + log2_irq_thresh (默认 0):
> + 控制默认中断延迟的对数值（以微帧为单位）。
> + 默认值0表示1个微帧（125 微秒）。
> + 最大值6表示2^6=64个微帧。
> + 该值控制EHCI控制器发出中断的频率。
> +
> +如果你在2.5内核上使用此驱动，并且启用了USB调试支持，
> +你将在任何EHCI控制器的sysfs目录中看到三个文件：
> +
> +"async"
> +输出异步调度队列，用于控制传输和批量传输。
> +显示每个活动的qh和挂起的qtd，通常每个urb一个qtd。
> +（对usb存储进行磁盘I/O时看看，可看到请求队列！）
> +
> +"periodic"
> +输出周期性调度队列，用于中断传输和等时传输。不显示qtd。
> +
> +"registers"
> +显示控制器寄存器状态。
> +
> +
> +设备驱动程序通常不需要关心自己是否运行在EHCI上，
> +但可能需要检查usb_device->speed是否是USB_SPEED_HIGH。
> +高速设备可以执行全速（或低速）设备无法完成的操作，
> +例如高带宽的周期性传输（中断传输或等时传输）。
> +此外，设备描述符中的某些值（如周期性传输的轮询间隔）在高速模式下使用不同的编码方式。
> +
> +务必通过USB 2.0集线器测试设备驱动。
> +当使用事务转换器时，这些集线器会以不同方式报告某些故障（如断开连接）。
> +一些驱动在遇到与OHCI或UHCI报告不同的故障时可能会表现异常。
> +
> +软件性能
> +========
> +
> +USB 2.0吞吐量受两个主要因素制约：主机控制器处理请求的速度，以及设备响应请求的速度。
> +所有设备都遵循480Mbit/sec的原始传输速率，
> +但总吞吐量还会受到诸如单个高速数据包之间的延迟、驱动程序调度策略，
> +以及系统整体负载等因素的影响。
> +延迟也是性能考量因素。
> +
> +批量传输通常用于对吞吐量有严格要求的场景。
> +需要注意的是，批量传输总是以512字节的数据包为单位，
> +并且在一个USB 2.0微帧中最多可容纳13个这样的数据包。
> +八个USB 2.0微帧构成一个USB 1.1帧；
> +一个微帧的时间为1毫秒 ÷ 8 = 125微秒。
> +
> +因此，当硬件和设备驱动软件都允许时，
> +批量传输可提供超过50 MByte/sec的带宽。
> +周期性传输模式（等时传输和中断传输）允许使用更大的数据包，
> +从而使传输速率接近标称的480MBit/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队列满。
> +这意味着发出较大的请求，或在需要发出一系列小请求时，使用批量排队（bulk queuing）。
> +如果驱动未做到这一点，那么会直接从性能结果上表现出来。
> +
> +
> +在典型场景下，使用usb_bulk_msg() 以4KB块循环写入，
> +会浪费超过一半的USB 2.0带宽。
> +I/O完成与驱动发出下一次请求之间的延迟通常比一次I/O操作所需的时间更长。
> +如果同样的循环改用16KB块，会有所改善；使用128KB块的序列则能大幅减少浪费。
> +
> +
> +与其依赖如此大的I/O缓冲区来提高同步I/O的效率，
> +不如直接向主机控制器队列多个（批量）请求，并等待它们全部完成，或在出错时取消。
> +这种URB排队方式对所有USB 1.1主机控制器驱动也适用。
> +
> +
> +在Linux 2.5内核中，定义了新的 usb_sg_*() API 调用；
> +它们会将scatterlist中的所有缓冲区排入队列。
> +它们还使用scatterlist的DMA映射（可能会使用IOMMU）并减少中断次数，
> +这些都有助于高速传输尽可能高效地运行。
> +
> +待办：
> + 中断传输和等时（ISO）传输的性能问题。
> + 这些周期性传输都是完全调度的，因此，主要问题可能在于如何触发高带宽模式。
> +
> +待办：
> + 通过sysfs的uframe_periodic_max参数，可以分配超过标准80%的周期性带宽。
> + 后续将对此进行说明。
> --
> 2.52.0
>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH v4 0/8] Add Chinese translation for USB subsystem
2025-12-02 11:56 [PATCH v4 0/8] Add Chinese translation for USB subsystem Kefan Bai
` (7 preceding siblings ...)
2025-12-02 11:56 ` [PATCH v4 8/8] docs/zh_CN: Add CREDITS translation Kefan Bai
@ 2025-12-04 2:41 ` Yanteng Si
2025-12-05 10:01 ` BaiKefan
8 siblings, 1 reply; 20+ messages in thread
From: Yanteng Si @ 2025-12-04 2:41 UTC (permalink / raw)
To: Kefan Bai, alexs; +Cc: dzm91, corbet, linux-doc, doubled
在 2025/12/2 19:56, Kefan Bai 写道:
> This patch set adds Chinese translations for the USB documentation.
>
> Changes in v4:
> - shorten those overlong title underline/overline symbols
> - Remove CREDITS section from index.rst
>
> Changes in v3:
> - Updated the signoff to my full legal name,
> as requested by Jonathan Corbet.
> - Reviewed and fixed the RST syntax to resolve the patch issues
> noted by Alex Shi.
> - Kept the number of translated files to eight
> to make submission and review smoother.
> - Link to v3: https://lore.kernel.org/all/cover.1763984424.git.baikefan@leap-io-kernel.com/
>
> Changes in v2:
> - Update [PATCH 01/25] docs/zh_CN: Add index.rst translation
> to include corresponding updates in
> 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 | 153 +++++++
> Documentation/translations/zh_CN/usb/acm.rst | 137 +++++++
> .../translations/zh_CN/usb/authorization.rst | 125 ++++++
> .../translations/zh_CN/usb/chipidea.rst | 142 +++++++
> Documentation/translations/zh_CN/usb/dwc3.rst | 60 +++
> Documentation/translations/zh_CN/usb/ehci.rst | 216 ++++++++++
> .../translations/zh_CN/usb/index.rst | 54 +++
> .../translations/zh_CN/usb/usbmon.rst | 380 ++++++++++++++++++
Actually, I don't know much about USB. I would rather suggest you copy these patch sets to the USB mailing list, where Chinese developers might help review them.
Thanks,
Yanteng
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH v4 7/8] docs/zh_CN: Add usbmon.rst translation
2025-12-02 11:56 ` [PATCH v4 7/8] docs/zh_CN: Add usbmon.rst translation Kefan Bai
@ 2025-12-04 2:47 ` Yanteng Si
0 siblings, 0 replies; 20+ messages in thread
From: Yanteng Si @ 2025-12-04 2:47 UTC (permalink / raw)
To: Kefan Bai, alexs; +Cc: dzm91, corbet, linux-doc, doubled
在 2025/12/2 19:56, Kefan Bai 写道:
> Translate .../usb/usbmon.rst into Chinese
>
> Update the translation through commit 788183a6e8b0
> ("docs: usb: fix literal block marker in usbmon verification example")
>
> Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn>
Thanks,
Yanteng
> ---
> .../translations/zh_CN/usb/usbmon.rst | 380 ++++++++++++++++++
> 1 file changed, 380 insertions(+)
> create mode 100644 Documentation/translations/zh_CN/usb/usbmon.rst
>
> diff --git a/Documentation/translations/zh_CN/usb/usbmon.rst b/Documentation/translations/zh_CN/usb/usbmon.rst
> new file mode 100644
> index 000000000000..c2eebaef67ff
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/usb/usbmon.rst
> @@ -0,0 +1,380 @@
> +.. 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：文本和二进制。二进制API通过/dev命名空间中的字符设备提供，
> +并且是一个ABI。文本API自内核2.6.35起废弃，但为了兼容仍然可用。
> +
> +如何使用usbmon收集原始文本追踪信息
> +==================================
> +
> +与数据包套接字不同，usbmon提供了一种接口，可以输出文本格式的追踪信息。
> +这样做有两个目的：
> +第一，在更完善的格式最终确定之前，它作为工具间通用的追踪交换格式；
> +第二，在不使用工具的情况下，人们也可以直接阅读这些信息。
> +
> +要收集原始文本追踪信息，请按以下步骤进行操作。
> +
> +1. 准备
> +--------
> +
> +首先必须在你的内核配置中启用debugfs，之后挂载debugfs。
> +如果usbmon是作为模块构建的，那么还要加载usbmon模块。
> +如果usbmon已经编入内核，则无需加载usbmon模块。
> +
> +命令示例::
> +
> + # mount -t debugfs none_debugs /sys/kernel/debug
> + # modprobe usbmon
> + #
> +
> +确认总线socket是否存在::
> + # 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行。
> +通常你可以通过vendor字符串来查找。如果你有许多类似设备，
> +可以拔掉其中一个设备，并比较前后两次
> +/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微秒更差。
> +
> +- 事件类型。表示事件的格式，而不是URB的类型。
> + 有效类型包括：S - 提交，C - 回调，E - 提交错误。
> +
> +- Address字段（以前称为pipe）。包含四个冒号分隔的字段：
> + URB类型与方向，总线号，设备地址，端点号。
> + 类型与方向的编码如下：
> +
> + == == =====================
> + Ci Co 控制input/output
> + Zi Zo 等时input/output
> + Ii Io 中断input/output
> + Bi Bo 批量input/output
> + == == =====================
> +
> + 总线号、设备地址和端点号使用十进制，但可能有前导零。
> +
> +- URB状态字。这个字段可以是一个字母，也可以是由冒号分隔的几个数字：
> + URB状态、间隔（interval）、起始帧（start frame）以及错误计数（error count）。
> + 与地址字段不同，除了状态之外，其余所有字段都是可选的。
> + interval仅在中断和等时URB中打印；
> + 起始帧仅在等时URB中打印；
> + 错误数量仅在等时回调事件中打印。
> +
> + 状态字段是一个十进制数字，有时为负数，对应URB的状态字段。
> + 对于提交（submission），这个字段没有实际意义，
> + 但是为了便于脚本解析，所以依然存在。
> + 当发生错误时，该字段包含错误码。
> +
> + 在提交控制数据包的情况下，该字段包含一个Setup Tag，而不是一组数字。
> + 判断是否存在Setup Tag很容易，因为它从来不是数字。
> + 因此，如果脚本在该字段中发现一组数字，
> + 它们会继续读取数据长度（等时URB除外）。
> + 如果发现的是其他内容，比如一个字母，
> + 那么脚本会在读取数据长度或等时描述符之前，会先读取Setup包。
> +
> +- Setup包由5个字段构成：bmRequestType, bRequest, wValue, wIndex, wLength。
> + 符合USB 2.0 规范。如果Setup标签为'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
> +
> +如有需要，将来可能实现ioctl FIONBIO。
> +
> +除了ioctl(2)和read(2)，可以使用
> +select(2)和poll(2)轮询二进制API的特殊文件。
> +但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.52.0
>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH v4 8/8] docs/zh_CN: Add CREDITS translation
2025-12-02 11:56 ` [PATCH v4 8/8] docs/zh_CN: Add CREDITS translation Kefan Bai
@ 2025-12-04 2:51 ` Yanteng Si
0 siblings, 0 replies; 20+ messages in thread
From: Yanteng Si @ 2025-12-04 2:51 UTC (permalink / raw)
To: Kefan Bai, alexs; +Cc: dzm91, corbet, linux-doc, doubled
在 2025/12/2 19:56, Kefan Bai 写道:
> Translate .../usb/CREDITS into Chinese
>
> Update the translation through commit 7b2328c5a009
> ("docs: Fix typo in usb/CREDITS")
>
> Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com>
Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn>
Thanks,
Yanteng
> ---
> Documentation/translations/zh_CN/usb/CREDITS | 153 +++++++++++++++++++
> 1 file changed, 153 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..ae8d489e62ff
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/usb/CREDITS
> @@ -0,0 +1,153 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/usb/CREDITS
> +:翻译:
> +
> + 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
> +
> +:校译:
> +
> +
> +
> +简易版Linux USB驱动致谢名单：
> +
> +以下人员为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驱动。我们从那项工作中学到
> + 了很多东西。
> +
> + The 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的支持，使其键盘能够被数百万Linux用户使用。
> +
> + - ing büro h doran [http://www.ibhdoran.com]!
> + 在欧洲几乎买不到后置USB接口面板的主板，而我自制的版本很糟糕 ：）。
> + 感谢他们提供了漂亮的USB配件！
> +
> + - Genius Germany捐赠了一只USB鼠标用于测试鼠标启动协议，并提供了
> + F-23数字摇杆和NetMouse Pro。感谢！
> +
> + - AVM GmbH Berlin支持我们开发Linux下的AVM ISDN控制器B1 USB驱动。
> + AVM是领先的ISDN控制器制造商，其主动式设计对包括Linux在内的
> + 所有操作系统开放。
> +
> + - 非常感谢Y-E Data, Inc捐赠的FlashBuster-U USB软驱，
> + 使我们能够测试bulk传输代码。
> +
> + - 感谢Logitech捐赠了一只三轴USB鼠标。
> +
> + Logitech设计、制造并销售各种人机接口设备，
> + 如键盘、鼠标、轨迹球、摄像头、扬声器及游戏控制设备。
> +
> + 感谢他们捐赠了USB鼠标、摇杆和扫描仪，
> + 以支持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论坛成员们的帮助与支持。
> +
> + - Nathan Myers <ncm@cantrip.org>，感谢他的建议！（希望你喜欢Cibeles的派对）
> +
> + - 感谢Linus Torvalds创建、开发并管理Linux。
> +
> + - Mike Smith, Craig Keithley, Thierry Giron和Janet Schank
> + 感谢他们让我明白标准USB集线器其实并没有那么标准，
> + 这有助于我们在标准集线器驱动中加入厂商特定的特性。
> --
> 2.52.0
>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH v4 1/8] docs/zh_CN: Add index.rst translation
2025-12-03 2:34 ` Yanteng Si
@ 2025-12-05 7:24 ` BaiKefan
0 siblings, 0 replies; 20+ messages in thread
From: BaiKefan @ 2025-12-05 7:24 UTC (permalink / raw)
To: Yanteng Si, seakeel; +Cc: alexs, dzm91, corbet, linux-doc, doubled
On Wed, 3 Dec 2025 10:34:20 +0800
Yanteng Si <si.yanteng@linux.dev> wrote:
>
> 在 2025/12/2 19:56, Kefan Bai 写道:
> > Translate .../usb/index.rst into Chinese and update
> > subsystem-apis.rst
> >
> > Update the translation through commit c26cee817f8b
> > ("usb: gadget: f_fs: add capability for dfu functional descriptor")
> >
> > 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..71e822e464d4
> > --- /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
> > +
> > + acm
> > + authorization
> > + chipidea
> > + dwc3
> > + ehci
> > + usbmon
>
> They shouldn't appear here right now; instead, they should be
> scattered across the translation patches. If only this patch is
> applied, a compilation error will occur.
>
>
> Thanks,
>
> Yanteng
>
Hi Yanteng,
I’ll update the content as you suggested, ensuring the entries in
index.rst—such as acm, authorization, chipidea, dwc3, ehci, and
usbmon—are properly split across the relevant patches.
This should fix the compilation issue when only some of the patches are
applied.
Let me know if any further changes are needed.
Thanks,
Kefan
> > +
> > +Todolist:
> > +
> > +* 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.52.0
> >
>
>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH v4 0/8] Add Chinese translation for USB subsystem
2025-12-04 2:41 ` [PATCH v4 0/8] Add Chinese translation for USB subsystem Yanteng Si
@ 2025-12-05 10:01 ` BaiKefan
2025-12-05 12:10 ` Alex Shi
0 siblings, 1 reply; 20+ messages in thread
From: BaiKefan @ 2025-12-05 10:01 UTC (permalink / raw)
To: Yanteng Si; +Cc: seakeel, dzm91, corbet, linux-doc, doubled, alexs
On Thu, 4 Dec 2025 10:41:20 +0800
Yanteng Si <si.yanteng@linux.dev> wrote:
>
> 在 2025/12/2 19:56, Kefan Bai 写道:
> > This patch set adds Chinese translations for the USB documentation.
> >
> > Changes in v4:
> > - shorten those overlong title underline/overline symbols
> > - Remove CREDITS section from index.rst
> >
> > Changes in v3:
> > - Updated the signoff to my full legal name,
> > as requested by Jonathan Corbet.
> > - Reviewed and fixed the RST syntax to resolve the patch issues
> > noted by Alex Shi.
> > - Kept the number of translated files to eight
> > to make submission and review smoother.
> > - Link to v3:
> > https://lore.kernel.org/all/cover.1763984424.git.baikefan@leap-io-kernel.com/
> >
> > Changes in v2:
> > - Update [PATCH 01/25] docs/zh_CN: Add index.rst translation
> > to include corresponding updates in
> > 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 | 153 +++++++
> > Documentation/translations/zh_CN/usb/acm.rst | 137 +++++++
> > .../translations/zh_CN/usb/authorization.rst | 125 ++++++
> > .../translations/zh_CN/usb/chipidea.rst | 142 +++++++
> > Documentation/translations/zh_CN/usb/dwc3.rst | 60 +++
> > Documentation/translations/zh_CN/usb/ehci.rst | 216 ++++++++++
> > .../translations/zh_CN/usb/index.rst | 54 +++
> > .../translations/zh_CN/usb/usbmon.rst | 380
> > ++++++++++++++++++
>
> Actually, I don't know much about USB. I would rather suggest you
> copy these patch sets to the USB mailing list, where Chinese
> developers might help review them.
>
Hi Yanteng,
I checked who maintains the USB code and got the following output:
Greg Kroah-Hartman <gregkh@linuxfoundation.org> (maintainer:USB
SUBSYSTEM)
linux-usb@vger.kernel.org (open list:USB SUBSYSTEM)
linux-kernel@vger.kernel.org (open list)
Would it be appropriate to send my USB documentation translation
patches directly to the USB mailing list (linux-usb@vger.kernel.org),
or would you suggest another way to reach the appropriate maintainers?
Thanks,
Kefan
>
> Thanks,
>
> Yanteng
>
>
>
>
>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH v4 0/8] Add Chinese translation for USB subsystem
2025-12-05 10:01 ` BaiKefan
@ 2025-12-05 12:10 ` Alex Shi
0 siblings, 0 replies; 20+ messages in thread
From: Alex Shi @ 2025-12-05 12:10 UTC (permalink / raw)
To: BaiKefan, Yanteng Si; +Cc: dzm91, corbet, linux-doc, doubled, alexs
On 2025/12/5 18:01, BaiKefan wrote:
>>> .../translations/zh_CN/subsystem-apis.rst | 2 +-
>>> Documentation/translations/zh_CN/usb/CREDITS | 153 +++++++
>>> Documentation/translations/zh_CN/usb/acm.rst | 137 +++++++
>>> .../translations/zh_CN/usb/authorization.rst | 125 ++++++
>>> .../translations/zh_CN/usb/chipidea.rst | 142 +++++++
>>> Documentation/translations/zh_CN/usb/dwc3.rst | 60 +++
>>> Documentation/translations/zh_CN/usb/ehci.rst | 216 ++++++++++
>>> .../translations/zh_CN/usb/index.rst | 54 +++
>>> .../translations/zh_CN/usb/usbmon.rst | 380
>>> ++++++++++++++++++
>> Actually, I don't know much about USB. I would rather suggest you
>> copy these patch sets to the USB mailing list, where Chinese
>> developers might help review them.
>>
> Hi Yanteng,
>
> I checked who maintains the USB code and got the following output:
>
> Greg Kroah-Hartman<gregkh@linuxfoundation.org> (maintainer:USB
> SUBSYSTEM)
> linux-usb@vger.kernel.org (openlist:USB SUBSYSTEM)
> linux-kernel@vger.kernel.org (open list)
>
> Would it be appropriate to send my USB documentation translation
> patches directly to the USB mailing list (linux-usb@vger.kernel.org),
> or would you suggest another way to reach the appropriate maintainers?
>
> Thanks,
> Kefan
Greg doesn't know Chinese, send to mailing list linux-usb if fine.
^ permalink raw reply [flat|nested] 20+ messages in thread
end of thread, other threads:[~2025-12-05 12:10 UTC | newest]
Thread overview: 20+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2025-12-02 11:56 [PATCH v4 0/8] Add Chinese translation for USB subsystem Kefan Bai
2025-12-02 11:56 ` [PATCH v4 1/8] docs/zh_CN: Add index.rst translation Kefan Bai
2025-12-03 2:34 ` Yanteng Si
2025-12-05 7:24 ` BaiKefan
2025-12-02 11:56 ` [PATCH v4 2/8] docs/zh_CN: Add acm.rst translation Kefan Bai
2025-12-02 11:56 ` [PATCH v4 3/8] docs/zh_CN: Add authorization.rst translation Kefan Bai
2025-12-03 2:29 ` Yanteng Si
2025-12-02 11:56 ` [PATCH v4 4/8] docs/zh_CN: Add chipidea.rst translation Kefan Bai
2025-12-03 5:31 ` Yanteng Si
2025-12-02 11:56 ` [PATCH v4 5/8] docs/zh_CN: Add dwc3.rst translation Kefan Bai
2025-12-04 2:28 ` Yanteng Si
2025-12-02 11:56 ` [PATCH v4 6/8] docs/zh_CN: Add ehci.rst translation Kefan Bai
2025-12-04 2:35 ` Yanteng Si
2025-12-02 11:56 ` [PATCH v4 7/8] docs/zh_CN: Add usbmon.rst translation Kefan Bai
2025-12-04 2:47 ` Yanteng Si
2025-12-02 11:56 ` [PATCH v4 8/8] docs/zh_CN: Add CREDITS translation Kefan Bai
2025-12-04 2:51 ` Yanteng Si
2025-12-04 2:41 ` [PATCH v4 0/8] Add Chinese translation for USB subsystem Yanteng Si
2025-12-05 10:01 ` BaiKefan
2025-12-05 12:10 ` Alex Shi
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).