* [PATCH v2 01/25] docs/zh_CN: Add index.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
@ 2025-11-23 11:55 ` macrofun
2025-11-23 15:38 ` Jonathan Corbet
2025-11-23 11:56 ` [PATCH v2 02/25] docs/zh_CN: Add acm.rst translation macrofun
` (23 subsequent siblings)
24 siblings, 1 reply; 32+ messages in thread
From: macrofun @ 2025-11-23 11:55 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
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: macrofun <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/subsystem-apis.rst | 2 +-
.../translations/zh_CN/usb/index.rst | 50 +++++++++++++++++++
2 files changed, 51 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 0f121f9b0f70..6649114b818f 100644
--- a/Documentation/translations/zh_CN/subsystem-apis.rst
+++ b/Documentation/translations/zh_CN/subsystem-apis.rst
@@ -91,6 +91,7 @@ TODOList:
security/index
PCI/index
peci/index
+ usb/index
TODOList:
@@ -105,6 +106,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..2ef1311a7043
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/index.rst
@@ -0,0 +1,50 @@
+.. 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
+ 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
+ usbmon
+ usb-serial
+ usb-help
+
+
+.. only:: subproject and html
+
+ 索引
+ =======
+
+ * :ref:`genindex`
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* Re: [PATCH v2 01/25] docs/zh_CN: Add index.rst translation
2025-11-23 11:55 ` [PATCH v2 01/25] docs/zh_CN: Add index.rst translation macrofun
@ 2025-11-23 15:38 ` Jonathan Corbet
2025-11-24 13:25 ` Kefan Bai
0 siblings, 1 reply; 32+ messages in thread
From: Jonathan Corbet @ 2025-11-23 15:38 UTC (permalink / raw)
To: macrofun, alexs, si.yanteng; +Cc: dzm91, linux-doc
macrofun <baikefan@leap-io-kernel.com> writes:
> 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: macrofun <baikefan@leap-io-kernel.com>
Please use your real, legal name in the signoff line.
Out of curiosity, are these translations machine-generated?
Thanks,
jon
^ permalink raw reply [flat|nested] 32+ messages in thread* Re: [PATCH v2 01/25] docs/zh_CN: Add index.rst translation
2025-11-23 15:38 ` Jonathan Corbet
@ 2025-11-24 13:25 ` Kefan Bai
2025-11-26 5:38 ` Alex Shi
0 siblings, 1 reply; 32+ messages in thread
From: Kefan Bai @ 2025-11-24 13:25 UTC (permalink / raw)
To: corbet; +Cc: alexs, baikefan, dzm91, linux-doc, si.yanteng
Hi Jonathan,
Thanks for your review.
I've updated the signoff to include my full legal name.
All translations were done manually.
To improve submission and review efficiency, the number of translation documents
in this series has been reduced to 8 in v3 patch series.
Thanks,
BaiKefan
On Sun, Nov 23, 2025 at 08:38:21AM -0700, Jonathan Corbet wrote:
> macrofun <baikefan@leap-io-kernel.com> writes:
>
> > 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: macrofun <baikefan@leap-io-kernel.com>
>
> Please use your real, legal name in the signoff line.
>
> Out of curiosity, are these translations machine-generated?
>
> Thanks,
>
> jon
^ permalink raw reply [flat|nested] 32+ messages in thread* Re: [PATCH v2 01/25] docs/zh_CN: Add index.rst translation
2025-11-24 13:25 ` Kefan Bai
@ 2025-11-26 5:38 ` Alex Shi
2025-11-26 8:25 ` BaiKefan
0 siblings, 1 reply; 32+ messages in thread
From: Alex Shi @ 2025-11-26 5:38 UTC (permalink / raw)
To: Kefan Bai, corbet; +Cc: alexs, dzm91, linux-doc, si.yanteng
On 2025/11/24 21:25, Kefan Bai wrote:
> Hi Jonathan,
>
> Thanks for your review.
>
> I've updated the signoff to include my full legal name.
>
> All translations were done manually.
> To improve submission and review efficiency, the number of translation documents
> in this series has been reduced to 8 in v3 patch series.
>
> Thanks,
> BaiKefan
>
> On Sun, Nov 23, 2025 at 08:38:21AM -0700, Jonathan Corbet wrote:
>> macrofun<baikefan@leap-io-kernel.com> writes:
It would be better if you use your real name to replace 'macrofun'
>>
>>> 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: macrofun<baikefan@leap-io-kernel.com>
>> Please use your real, legal name in the signoff line.
>>
>> Out of curiosity, are these translations machine-generated?
>>
>> Thanks,
^ permalink raw reply [flat|nested] 32+ messages in thread* Re: [PATCH v2 01/25] docs/zh_CN: Add index.rst translation
2025-11-26 5:38 ` Alex Shi
@ 2025-11-26 8:25 ` BaiKefan
0 siblings, 0 replies; 32+ messages in thread
From: BaiKefan @ 2025-11-26 8:25 UTC (permalink / raw)
To: Alex Shi; +Cc: corbet, alexs, dzm91, linux-doc, si.yanteng
Hi Alex, thank you for your feedback.
On Wed, 26 Nov 2025 13:38:12 +0800
Alex Shi <seakeel@gmail.com> wrote:
>
>
> On 2025/11/24 21:25, Kefan Bai wrote:
> > Hi Jonathan,
> >
> > Thanks for your review.
> >
> > I've updated the signoff to include my full legal name.
> >
> > All translations were done manually.
> > To improve submission and review efficiency, the number of
> > translation documents in this series has been reduced to 8 in v3
> > patch series.
> >
> > Thanks,
> > BaiKefan
> >
> > On Sun, Nov 23, 2025 at 08:38:21AM -0700, Jonathan Corbet wrote:
> >> macrofun<baikefan@leap-io-kernel.com> writes:
>
> It would be better if you use your real name to replace 'macrofun'
I have replaced 'macrofun' with my real name in the v3 patch
series as requested.
>
>
> >>
> >>> 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: macrofun<baikefan@leap-io-kernel.com>
> >> Please use your real, legal name in the signoff line.
> >>
> >> Out of curiosity, are these translations machine-generated?
> >>
> >> Thanks,
>
>
>
Thanks again for your guidance.
Please let me know if any more changes are needed.
Thanks,
BaiKefan
^ permalink raw reply [flat|nested] 32+ messages in thread
* [PATCH v2 02/25] docs/zh_CN: Add acm.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
2025-11-23 11:55 ` [PATCH v2 01/25] docs/zh_CN: Add index.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-24 6:17 ` Alex Shi
2025-11-23 11:56 ` [PATCH v2 03/25] docs/zh_CN: Add authorization.rst translation macrofun
` (22 subsequent siblings)
24 siblings, 1 reply; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/acm.rst into Chinese.
Update the translation through commit ecefae6db042
("docs: usb: rename files to .rst and add them to drivers-api")
Signed-off-by: macrofun <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..974654410344
--- /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. 免责声明
+~~~~~~~~~~~~~
+本程序是自由软件；您可以依据自由软件基金会发布的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 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] 32+ messages in thread* Re: [PATCH v2 02/25] docs/zh_CN: Add acm.rst translation
2025-11-23 11:56 ` [PATCH v2 02/25] docs/zh_CN: Add acm.rst translation macrofun
@ 2025-11-24 6:17 ` Alex Shi
2025-11-24 12:46 ` Kefan Bai
0 siblings, 1 reply; 32+ messages in thread
From: Alex Shi @ 2025-11-24 6:17 UTC (permalink / raw)
To: macrofun, alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
On 2025/11/23 19:56, macrofun 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")
>
> Signed-off-by: macrofun<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..974654410344
> --- /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
> +======================
Hi Macrofun,
Please check and follow the RST syntax to fix your patch problems.
https://en.wikipedia.org/wiki/ReStructuredText
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
Thanks
Alex
> +
> +版权所有(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 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 [flat|nested] 32+ messages in thread
* [PATCH v2 03/25] docs/zh_CN: Add authorization.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
2025-11-23 11:55 ` [PATCH v2 01/25] docs/zh_CN: Add index.rst translation macrofun
2025-11-23 11:56 ` [PATCH v2 02/25] docs/zh_CN: Add acm.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 04/25] docs/zh_CN: Add chipidea.rst translation macrofun
` (21 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/authorization.rst into Chinese.
Update the translation through commit f176638af476
("USB: Remove Wireless USB and UWB documentation")
Signed-off-by: macrofun <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..6d5569f3f419
--- /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设备连接时，它会被配置，其接口会立即对用户开放。
+通过此修改，只有在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 # temporarily authorize it
+ # FIXME: make sure none can mount it
+ mount DEVICENODE /mntpoint
+ sum=$(md5sum /mntpoint/.signature)
+ if [ $sum = $(cat /etc/lockdown/keysum) ]
+ then
+ echo "We are good, connected"
+ umount /mntpoint
+ # Other stuff so others can use it
+ 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] 32+ messages in thread* [PATCH v2 04/25] docs/zh_CN: Add chipidea.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (2 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 03/25] docs/zh_CN: Add authorization.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 05/25] docs/zh_CN: Add dwc3.rst translation macrofun
` (20 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/chipidea.rst into Chinese.
Update the translation through commit e4157519ad46
("Documentation: usb: correct spelling")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/chipidea.rst | 143 ++++++++++++++++++
1 file changed, 143 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..226f1f90c0d0
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/chipidea.rst
@@ -0,0 +1,143 @@
+.. 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）
+-----------------------------------
+
+To show how to demo OTG HNP and SRP functions via sys input files
+with 2 Freescale i.MX6Q sabre SD boards.
+演示如何在两块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-device，应当枚举另一端的B-device。
+
+3) 角色切换
+
+ 在B设备上执行::
+
+ echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req
+
+ B-device应切换为host并枚举A设备。
+
+4) 把A设备切换为host
+
+ 在B设备上执行::
+
+ echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req
+
+ 或者通过HNP轮询机制：B主机可以检测到A外设想成为host的意愿，
+ 从而由A外设触发角色切换。在 A-device上执行::
+ 或者通过HNP轮询机制：B-Host可以检测到A-peripheral想切换为host角色的意愿，
+ 并通过A-peripheral对轮询的响应来触发角色切换。
+ 这可以通过在A-device上执行::
+
+ echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req
+
+ A-device应切换回host并枚举B-device。
+
+5) 拔掉 B-device（拔掉 micro B 插头），在10秒内重新插入；
+ A-device 应重新枚举 B-device。
+
+6) 拔掉 B-device（拔掉 micro B 插头），在10秒后重新插入；
+ A-device 不应重新枚举 B-device。
+
+ 若A-device想使用总线：
+
+ 在A-device上::
+
+ 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-device想使用总线：
+
+ 在B-device上::
+
+ echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req
+
+7) A-device关闭总线供电
+
+ 在A-device上::
+
+ echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop
+
+ A-device应断开与B-device的连接并关闭总线供电。
+
+8) B-device 进行SRP数据脉冲唤醒
+
+ 在B-device上::
+
+ echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req
+
+ A-device应恢复usb总线并枚举B-device。
+
+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] 32+ messages in thread* [PATCH v2 05/25] docs/zh_CN: Add dwc3.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (3 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 04/25] docs/zh_CN: Add chipidea.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 06/25] docs/zh_CN: Add ehci.rst translation macrofun
` (19 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
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: macrofun <baikefan@leap-io-kernel.com>
---
Documentation/translations/zh_CN/usb/dwc3.rst | 59 +++++++++++++++++++
1 file changed, 59 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..63ee43278ffe
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/dwc3.rst
@@ -0,0 +1,59 @@
+.. 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中断的处理主程序
+ 读取事件并尝试处理它。所有需要休眠的操作都交给线程处理。
+ 事件保存在每个端点的数据结构中。
+ 需要注意：一旦将某些处理交给线程，就不要在这里继续处理事件，
+ 避免出现处理事件X优先级高于Y而X > Y的情况。
+
+ - EP中断的处理线程
+ 处理剩余的EP工作，这些工作可能会休眠，例如等待命令完成。
+
+ 延迟:
+
+ 延迟不应该增加，因为中断线程具有较高优先级，会在用户空间普通任务之前运行
+ （除非用户更改了调度优先级）。
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 06/25] docs/zh_CN: Add ehci.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (4 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 05/25] docs/zh_CN: Add dwc3.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 07/25] docs/zh_CN: Add functionfs.rst translation macrofun
` (18 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/ehci.rst into Chinese.
Update the translation through commit 570eb861243c
("docs: usb: replace some characters")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
Documentation/translations/zh_CN/usb/ehci.rst | 217 ++++++++++++++++++
1 file changed, 217 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..1853e531261f
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/ehci.rst
@@ -0,0 +1,217 @@
+.. 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驱动程序使用该支持。
+
+通过事务转换器实现的全速等时（Isochronous）传输目前尚未支持。
+需要注意的是，用于全速设备的等时拆分事务（split ISO）与高速
+等时传输在EHCI中采用完全不同的数据结构，因此相关代码几乎无
+法共用。因此，目前大多数USB音频和视频类设备即使连接到高速
+总线，也无法正常使用等时传输功能。
+
+驱动行为
+--------
+
+所有类型的传输都可以排队。
+这意味着来自不同接口（或通过 usbfs）的控制传输不会互相干扰，
+并且中断传输可以使用1帧的周期，而无需担心由于中断处理成本导致的数据丢失。
+
+
+EHCI根集线器代码会将USB 1.1设备交给其伴随控制器处理。
+EHCI驱动无需了解其他控制器的驱动程序；
+已经正常工作的OHCI或UHCI驱动，无需因为EHCI的存在而做任何修改。
+
+存在一些电源管理相关的问题；挂起/恢复行为目前不太正确。
+
+此外，在调度周期性事务（中断和等时传输）时采用了一些简化处理。
+这些简化会限制可调度的周期性传输数量，并且无法使用小于1帧的轮询间隔。
+
+使用方式
+=========
+
+假设你有一个EHCI控制器（PCI 卡或主板上），并且已将此驱动编译为模块，可如下加载::
+
+ # 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-storage 做磁盘 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() 以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）并减少中断（IRQ）次数，
+这些都有助于高速传输尽可能高效地运行。
+
+待办：
+ 中断传输和等时（ISO）传输的性能问题。
+ 这些周期性传输都是完全调度的，因此，主要问题可能在于如何触发高带宽模式。
+
+待办：
+ 通过sysfs的uframe_periodic_max参数，可以分配超过标准80%的周期性带宽。
+ 以下将对此进行说明。
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 07/25] docs/zh_CN: Add functionfs.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (5 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 06/25] docs/zh_CN: Add ehci.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 08/25] docs/zh_CN: Add functionfs-desc.rst translation macrofun
` (17 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/functionfs.rst into Chinese.
Update the translation through commit c26cee817f8b
("usb: gadget: f_fs: add capability for dfu functional descriptor")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/functionfs.rst | 94 +++++++++++++++++++
1 file changed, 94 insertions(+)
create mode 100644 Documentation/translations/zh_CN/usb/functionfs.rst
diff --git a/Documentation/translations/zh_CN/usb/functionfs.rst b/Documentation/translations/zh_CN/usb/functionfs.rst
new file mode 100644
index 000000000000..64e50272f9ae
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/functionfs.rst
@@ -0,0 +1,94 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/functionfs.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+====================
+FunctionFS的工作原理
+====================
+
+概述
+====
+
+从内核角度来看，它只是一个具有特定行为的复合功能。
+只有在用户空间驱动通过写入描述符和字符串完成注册之后，
+它才能被添加到USB配置中（用户空间程序必须提供与
+内核级复合函数在添加到配置时提供的相同信息）。
+
+这尤其意味着复合初始化函数不能放在init段中（即不能使用__init标签）。
+
+
+从用户空间的角度来看，它是一个文件系统，挂载后会提供一个ep0文件。
+用户空间驱动需要向该文件写入描述符和字符串。
+无需关心端点、接口或字符串编号，只需提供描述符，
+就像该函数是唯一函数一样（端点和字符串编号从 1 开始，接口编号从 0 开始）。
+FunctionFS会根据需要自动修改编号，同时处理不同配置中编号不一致的情况。
+
+有关 FunctionFS 描述符的更多信息，请参见 :doc:`functionfs-desc`
+
+当描述符和字符串写入后，会出现"ep#"文件（每个声明的端点对应一个文件），
+用于单个端点的通信处理。
+同样，FunctionFS会处理实际端点编号及配置变更
+（这意味着ep1文件可能实际映射到端点3，例如，当配置变化时可能映射到端点2）。
+ep0用于接收事件和处理setup请求。
+
+当所有文件关闭时，该函数会自动禁用自身。
+
+此外，FunctionFS 的设计允许多次挂载，因此一个 gadget 可以使用多个 FunctionFS 函数。
+每个 FunctionFS 实例通过挂载时使用的设备名称进行标识。
+
+例如，一个gadget具有以太网（Ethernet）、MTP和HID接口，其中后两个通过FunctionFS实现。
+在用户空间层面，操作可能如下所示::
+
+ $ insmod g_ffs.ko idVendor=<ID> iSerialNumber=<string> functions=mtp,hid
+ $ mkdir /dev/ffs-mtp && mount -t functionfs mtp /dev/ffs-mtp
+ $ ( cd /dev/ffs-mtp && mtp-daemon ) &
+ $ mkdir /dev/ffs-hid && mount -t functionfs hid /dev/ffs-hid
+ $ ( cd /dev/ffs-hid && hid-daemon ) &
+
+在内核层面，gadget会检查ffs_data->dev_name来识别其FunctionFS是为
+MTP（"mtp"还是 HID（"hid"）设计的。
+
+如果未提供 "functions" 模块参数，驱动只接受一个任意名称的函数。
+
+当提供functions模块参数时，只接受列出的名称函数。
+特别是，如果"functions"参数的值只有一个元素，
+则行为类似于未提供 "functions" 时；但只接受具有指定名称的函数。
+
+只有在所有声明的函数文件系统都已挂载，
+并且所有函数的USB描述符都已写入各自的ep0后，gadget才会注册。
+
+相反，当第一个 USB 函数关闭其端点时，gadget 会注销。
+
+DMABUF接口
+==========
+
+FunctionFS还支持基于DMABUF的接口，用户空间可以将外部创建的DMABUF对象附加到端点，
+并随后使用它们进行数据传输。
+
+用户空间应用程序可以使用此接口在多个接口之间共享DMABUF对象，
+允许它以零拷贝的方式传输数据，例如在IIO和USB栈之间。
+作为该接口的一部分，添加了三个新的IOCTL。这三个
+IOCTL必须在数据端点（即非ep0）上执行。它们是：
+
+ ``FUNCTIONFS_DMABUF_ATTACH(int)``
+ 将由文件描述符标识的DMABUF对象附加到数据端点。
+ 成功返回0，失败返回负errno值。
+
+ ``FUNCTIONFS_DMABUF_DETACH(int)``
+ 从数据端点分离给定的DMABUF对象（由文件描述符标识）。
+ 成功返回0，失败返回负errno值。
+ 注意，关闭端点的文件描述符会自动分离所有已附加的DMABUF。
+
+ ``FUNCTIONFS_DMABUF_TRANSFER(struct usb_ffs_dmabuf_transfer_req *)``
+ 将之前附加的DMABUF排入传输队列。
+ 参数是一个结构体，其中封装DMABUF的文件描述符、要传输的字节大小
+ （通常应与DMABUF的大小相对应），以及一个当前未使用的'flags'字段。
+ 返回0表示成功，返回负errno值表示失败。
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 08/25] docs/zh_CN: Add functionfs-desc.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (6 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 07/25] docs/zh_CN: Add functionfs.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 09/25] docs/zh_CN: Add gadget_configfs.rst translation macrofun
` (16 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/functionfs-desc.rst into Chinese.
Update the translation through commit c26cee817f8b
("usb: gadget: f_fs: add capability for dfu functional descriptor")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
.../zh_CN/usb/functionfs-desc.rst | 43 +++++++++++++++++++
1 file changed, 43 insertions(+)
create mode 100644 Documentation/translations/zh_CN/usb/functionfs-desc.rst
diff --git a/Documentation/translations/zh_CN/usb/functionfs-desc.rst b/Documentation/translations/zh_CN/usb/functionfs-desc.rst
new file mode 100644
index 000000000000..cc6d94e5452f
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/functionfs-desc.rst
@@ -0,0 +1,43 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/functionfs-desc.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+=====================
+FunctionFS 描述符
+=====================
+
+以下介绍了可以写入FFS gadget的部分描述符。
+设备和配置描述符由复合gadget处理，用户不需要向FFS gadget写入这些描述符。
+
+描述符写入FFS gadget的ep0文件中，紧跟描述符头之后。
+
+.. kernel-doc:: include/uapi/linux/usb/functionfs.h
+ :doc: descriptors
+
+接口描述符
+----------
+
+可以写入标准USB接口描述符。
+最近写入的接口描述符的类/子类决定了可接受哪种类型的类特定描述符。
+
+类特定描述符
+------------
+
+类特定描述符仅接受最近写入的接口描述符所指定的类/子类。
+以下是部分受支持的类特定描述符示例。
+
+DFU功能描述符
+~~~~~~~~~~~~~~
+
+当接口类为USB_CLASS_APP_SPEC且接口子类为USB_SUBCLASS_DFU时，
+可以提供DFU功能描述符。
+DFU功能描述符在USB设备固件升级（DFU）规范中有描述，版本为 1.1。
+
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 09/25] docs/zh_CN: Add gadget_configfs.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (7 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 08/25] docs/zh_CN: Add functionfs-desc.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 10/25] docs/zh_CN: Add gadget_hid.rst translation macrofun
` (15 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/gadget_configfs.rst into Chinese.
Update the translation through commit 58992bf32830
("Documentation: usb: gadget: Wrap remaining usage snippets in literal code block")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
.../zh_CN/usb/gadget_configfs.rst | 383 ++++++++++++++++++
1 file changed, 383 insertions(+)
create mode 100644 Documentation/translations/zh_CN/usb/gadget_configfs.rst
diff --git a/Documentation/translations/zh_CN/usb/gadget_configfs.rst b/Documentation/translations/zh_CN/usb/gadget_configfs.rst
new file mode 100644
index 000000000000..6001020f89ca
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/gadget_configfs.rst
@@ -0,0 +1,383 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/gadget_configfs.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+=====================================
+通过configfs配置的Linux USB gadget
+=====================================
+
+2013年4月25日
+
+概述
+====
+
+USB Linux Gadget是一种拥有UDC（USB设备控制器）的设备，
+可以连接到USB主机，为其扩展附加功能，例如串口或大容量存储功能。
+
+从主机的角度来看，一个gadget表现为一组配置，每个配置包含若干接口，
+从gadget的角度来看，这些接口被称为函数（function），
+每个函数代表例如一个串行连接或一个SCSI磁盘。
+
+Linux为gadget提供了若干可用函数。
+
+创建一个gadget意味着要决定将有哪些配置，以及每个配置将提供哪些函数。
+
+Configfs（请参见 `Documentation/filesystems/configfs.rst`）非常适合用于
+告诉内核上述决策。本文档介绍了如何实现这一操作。
+
+同时，它还描述了configfs与gadget集成的设计方式。
+
+
+
+要求
+=====
+
+为了使其工作，configfs必须可用，因此在.config中CONFIGFS_FS必须为'y' 或 'm'。
+截至本文撰写时，USB_LIBCOMPOSITE会选择CONFIGFS_FS。
+
+
+
+使用方法
+========
+
+::
+
+ $ modprobe libcomposite
+ $ mount none $CONFIGFS_HOME -t configfs
+
+其中CONFIGFS_HOME是configfs的挂载点
+
+1. 创建gadget
+-------------
+
+对于每个要创建的gadget，必须创建其对应的目录::
+
+ $ mkdir $CONFIGFS_HOME/usb_gadget/<gadget name>
+
+例如::
+
+ $ mkdir $CONFIGFS_HOME/usb_gadget/g1
+
+ ...
+ ...
+ ...
+
+ $ cd $CONFIGFS_HOME/usb_gadget/g1
+
+每个gadget需要指定其厂商ID <VID>和产品ID <PID>::
+
+ $ echo <VID> > idVendor
+ $ echo <PID> > idProduct
+
+gadget还需要其序列号、厂商和产品字符串。
+为了有地方存放它们，需要为每种语言创建一个 strings 子目录，例如::
+
+ $ mkdir strings/0x409
+
+然后可以指定这些字符串::
+
+ $ echo <serial number> > strings/0x409/serialnumber
+ $ echo <manufacturer> > strings/0x409/manufacturer
+ $ echo <product> > strings/0x409/product
+
+进一步的自定义字符串描述符可以作为语言目录下的子目录创建，
+字符串文本写入该字符串目录下的"s"属性::
+
+ $ mkdir strings/0x409/xu.0
+ $ echo <string text> > strings/0x409/xu.0/s
+
+在函数驱动支持的情况下，函数可能允许这些自定义字符串描述符的符号链接，
+用以将这些字符串与类描述符关联。
+
+2. 创建配置
+-----------
+
+每个gadget将由多个配置组成，必须创建其对应的目录::
+
+ $ mkdir configs/<name>.<number>
+
+其中 <name> 可以是任何在文件系统中合法的字符串，
+<number> 是该配置的编号，例如::
+
+ $ mkdir configs/c.1
+
+ ...
+ ...
+ ...
+
+每个配置也需要字符串，因此必须为每种语言创建一个子目录，例如::
+
+ $ mkdir configs/c.1/strings/0x409
+
+然后可以指定配置字符串::
+ $ echo <configuration> > configs/c.1/strings/0x409/configuration
+
+某些属性也可以为配置设置，例如::
+
+ $ echo 120 > configs/c.1/MaxPower
+
+3. 创建函数
+-----------
+
+gadget 将提供若干函数，为每个函数必须创建其对应的目录::
+
+ $ mkdir functions/<name>.<instance name>
+
+其中 <name> 对应于允许的函数名称之一，而 instance name
+是一个在文件系统中允许的任意字符串，例如::
+
+ $ mkdir functions/ncm.usb0 # usb_f_ncm.ko gets loaded with request_module()
+
+ ...
+ ...
+ ...
+
+每个函数提供其特定的一组属性，可读或可写。
+在适用的情况下，需要根据具体情况对其进行写入。
+更多信息请参考 Documentation/ABI/testing/configfs-usb-gadget。
+
+4. 将函数与其配置关联
+----------------------
+
+此时已创建若干 gadget，每个 gadget 都指定了若干配置并具有若干可用函数。
+接下来需要指定哪些函数在何种配置中可用（同一个函数可用于多个配置）。
+这是通过创建符号链接实现的::
+
+ $ ln -s functions/<name>.<instance name> configs/<name>.<number>
+
+例如::
+
+ $ ln -s functions/ncm.usb0 configs/c.1
+
+ ...
+ ...
+ ...
+
+5. 启用 gadget
+--------------
+
+以上所有步骤的目的是组合 gadget 的配置和函数。
+
+一个示例目录结构可能如下所示::
+
+ .
+ ./strings
+ ./strings/0x409
+ ./strings/0x409/serialnumber
+ ./strings/0x409/product
+ ./strings/0x409/manufacturer
+ ./configs
+ ./configs/c.1
+ ./configs/c.1/ncm.usb0 -> ../../../../usb_gadget/g1/functions/ncm.usb0
+ ./configs/c.1/strings
+ ./configs/c.1/strings/0x409
+ ./configs/c.1/strings/0x409/configuration
+ ./configs/c.1/bmAttributes
+ ./configs/c.1/MaxPower
+ ./functions
+ ./functions/ncm.usb0
+ ./functions/ncm.usb0/ifname
+ ./functions/ncm.usb0/qmult
+ ./functions/ncm.usb0/host_addr
+ ./functions/ncm.usb0/dev_addr
+ ./UDC
+ ./bcdUSB
+ ./bcdDevice
+ ./idProduct
+ ./idVendor
+ ./bMaxPacketSize0
+ ./bDeviceProtocol
+ ./bDeviceSubClass
+ ./bDeviceClass
+
+
+这样的gadget必须最终被启用，以便USB主机能够枚举它。
+
+为了启用gadget，必须将其绑定到一个UDC（USB Device Controller）::
+
+ $ echo <udc name> > UDC
+
+其中 <udc name> 是 /sys/class/udc/* 中的一个，例如::
+
+ $ echo s3c-hsotg > UDC
+
+
+6. 禁用 gadget
+--------------
+
+::
+
+ $ echo "" > UDC
+
+7. 清理
+-------
+
+从配置中移除函数::
+
+ $ rm configs/<config name>.<number>/<function>
+
+其中 <config name>.<number> 指定配置，
+<function> 是从配置中移除的函数的符号链接，例如::
+
+ $ rm configs/c.1/ncm.usb0
+
+ ...
+ ...
+ ...
+
+移除配置中的strings目录::
+
+ $ rmdir configs/<config name>.<number>/strings/<lang>
+
+例如::
+
+ $ rmdir configs/c.1/strings/0x409
+
+ ...
+ ...
+ ...
+
+然后移除配置::
+
+ $ rmdir configs/<config name>.<number>
+
+例如::
+
+ $ rmdir configs/c.1
+
+ ...
+ ...
+ ...
+
+移除函数（函数模块不会被卸载）::
+
+ $ rmdir functions/<name>.<instance name>
+
+例如::
+
+ $ rmdir functions/ncm.usb0
+
+ ...
+ ...
+ ...
+
+移除 gadget 中的 strings 目录::
+
+ $ rmdir strings/<lang>
+
+例如::
+ $ rmdir strings/0x409
+
+最后移除 gadget::
+
+ $ cd ..
+ $ rmdir <gadget name>
+
+例如::
+
+ $ rmdir g1
+
+
+
+
+实现设计
+===========
+
+下面介绍configfs的工作原理。
+在configfs中，有items和groups，二者都以目录的形式呈现。
+它们的区别在于group可以包含其他groups。
+下面的图中只展示了一个item。items和groups均可具有attributes，
+这些属性以文件的形式呈现。
+用户可以创建和删除目录，但不能删除文件；
+这些文件可能是只读或可读写的，具体取决于其代表的内容。
+
+configfs 的文件系统部分操作的是 config_items/groups 和
+configfs_attributes，它们是通用的，对于所有配置的元素类型相同。
+然而，它们被嵌入到用途特定的更大结构中。
+在下面的图中，有一个包含 config_item 的 “cs”，
+以及一个包含 configfs_attribute 的 “sa”。
+
+文件系统视图如下所示::
+
+ ./
+ ./cs (directory)
+ |
+ +--sa (file)
+ |
+ .
+ .
+ .
+
+每当用户读/写 “sa” 文件时，就会调用一个函数，
+该函数接收一个 struct config_item 和一个 struct configfs_attribute。
+在该函数中，使用众所周知的 container_of 技巧获取 “cs” 和 “sa”，
+然后调用适当的 sa 的函数（show 或 store），
+并传入 “cs” 和一个字符缓冲区。
+“show” 用于显示文件内容（将数据从 cs 复制到缓冲区），
+而 “store” 用于修改文件内容（将数据从缓冲区复制到 cs），
+但具体执行内容由实现者自行决定。
+
+::
+
+ typedef struct configured_structure cs;
+ typedef struct specific_attribute sa;
+
+ sa
+ +----------------------------------+
+ cs | (*show)(cs *, buffer); |
+ +-----------------+ | (*store)(cs *, buffer, length); |
+ | | | |
+ | +-------------+ | | +------------------+ |
+ | | struct |-|----|------>|struct | |
+ | | config_item | | | |configfs_attribute| |
+ | +-------------+ | | +------------------+ |
+ | | +----------------------------------+
+ | data to be set | .
+ | | .
+ +-----------------+ .
+
+文件名由 config item/group 的设计者决定，
+而目录一般可以任意命名。
+一个group可以拥有若干其默认子group，由系统自动创建。
+
+有关configfs的更多信息请参阅
+`Documentation/filesystems/configfs.rst`.
+
+上述概念应用到USB gadgets时对应如下：
+
+1. 一个 gadget 有其 config group，其中包含一些属性（idVendor、
+ idProduct 等）和默认子 group（configs、functions、strings）。
+ 向这些属性写入会导致信息被存储到合适的位置。
+ 在 configs、functions 和 strings 子 group 中，用户可以创建
+ 其子 group 以表示配置、功能以及某种语言下的一组字符串。
+
+2. 用户创建 configurations 和 functions，并在 configurations 中
+ 创建指向 functions 的符号链接。
+ 当 gadget 的 UDC 属性被写入时，也就是将 gadget 绑定到 UDC 时，
+ 这些信息将被使用。
+ drivers/usb/gadget/configfs.c 中的代码会遍历所有 configurations，
+ 并在每个 configuration 中遍历所有 functions 并绑定它们。
+ 这样整个 gadget 就被绑定了。
+
+3. 文件 drivers/usb/gadget/configfs.c 包含以下代码：
+
+ - gadget的config_group
+ - gadget的默认 groups (configs, functions, strings)
+ - 将 functions 与 configurations 关联（符号链接）
+
+4. 每个 USB function 自然拥有其希望被配置的视图，
+ 因此特定 functions 的 config_groups 定义在各自的
+ functions 实现文件 drivers/usb/gadget/f_*.c 中。
+
+5. function 的代码是这样编写的：它使用 usb_get_function_instance()，
+ 该函数会调用 request_module。
+ 因此，只要 modprobe 可以正常工作，特定 function 的模块就会自动加载。
+ 请注意反向并不成立：在 gadget 被禁用并拆除之后，这些模块仍然保持加载状态。
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 10/25] docs/zh_CN: Add gadget_hid.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (8 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 09/25] docs/zh_CN: Add gadget_configfs.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 11/25] docs/zh_CN: Add gadget_multi.rst translation macrofun
` (14 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/gadget_hid.rst into Chinese.
Update the translation through commit ffeb1e9e897b
("USB: Replace HTTP links with HTTPS ones")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/gadget_hid.rst | 462 ++++++++++++++++++
1 file changed, 462 insertions(+)
create mode 100644 Documentation/translations/zh_CN/usb/gadget_hid.rst
diff --git a/Documentation/translations/zh_CN/usb/gadget_hid.rst b/Documentation/translations/zh_CN/usb/gadget_hid.rst
new file mode 100644
index 000000000000..3c1fa8ed3979
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/gadget_hid.rst
@@ -0,0 +1,462 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/gadget_hid.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+===========================
+Linux USB HID gadget驱动
+===========================
+
+简介
+====
+HID Gadget驱动提供USB人机接口设备（HID）的模拟实现。
+基础的HID处理由内核完成，
+HID报告可以通过对 /dev/hidgX 字符设备进行I/O来发送/接收。
+
+关于HID的更多细节请参考开发者页面：
+https://www.usb.org/developers/hidpage/
+
+配置
+====
+g_hid是一个 platform driver，因此要使用它，
+你需要在平台代码中添加 struct platform_device，
+定义你想要使用的HID功能描述符 —— 例如如下代码：::
+
+ #include <linux/platform_device.h>
+ #include <linux/usb/g_hid.h>
+
+ /* hid descriptor for a keyboard */
+ static struct hidg_func_descriptor my_hid_data = {
+ .subclass = 0, /* 无子类 */
+ .protocol = 1, /* 键盘 */
+ .report_length = 8,
+ .report_desc_length = 63,
+ .report_desc = {
+ 0x05, 0x01, /* USAGE_PAGE (Generic Desktop) */
+ 0x09, 0x06, /* USAGE (Keyboard) */
+ 0xa1, 0x01, /* COLLECTION (Application) */
+ 0x05, 0x07, /* USAGE_PAGE (Keyboard) */
+ 0x19, 0xe0, /* USAGE_MINIMUM (Keyboard LeftControl) */
+ 0x29, 0xe7, /* USAGE_MAXIMUM (Keyboard Right GUI) */
+ 0x15, 0x00, /* LOGICAL_MINIMUM (0) */
+ 0x25, 0x01, /* LOGICAL_MAXIMUM (1) */
+ 0x75, 0x01, /* REPORT_SIZE (1) */
+ 0x95, 0x08, /* REPORT_COUNT (8) */
+ 0x81, 0x02, /* INPUT (Data,Var,Abs) */
+ 0x95, 0x01, /* REPORT_COUNT (1) */
+ 0x75, 0x08, /* REPORT_SIZE (8) */
+ 0x81, 0x03, /* INPUT (Cnst,Var,Abs) */
+ 0x95, 0x05, /* REPORT_COUNT (5) */
+ 0x75, 0x01, /* REPORT_SIZE (1) */
+ 0x05, 0x08, /* USAGE_PAGE (LEDs) */
+ 0x19, 0x01, /* USAGE_MINIMUM (Num Lock) */
+ 0x29, 0x05, /* USAGE_MAXIMUM (Kana) */
+ 0x91, 0x02, /* OUTPUT (Data,Var,Abs) */
+ 0x95, 0x01, /* REPORT_COUNT (1) */
+ 0x75, 0x03, /* REPORT_SIZE (3) */
+ 0x91, 0x03, /* OUTPUT (Cnst,Var,Abs) */
+ 0x95, 0x06, /* REPORT_COUNT (6) */
+ 0x75, 0x08, /* REPORT_SIZE (8) */
+ 0x15, 0x00, /* LOGICAL_MINIMUM (0) */
+ 0x25, 0x65, /* LOGICAL_MAXIMUM (101) */
+ 0x05, 0x07, /* USAGE_PAGE (Keyboard) */
+ 0x19, 0x00, /* USAGE_MINIMUM (Reserved) */
+ 0x29, 0x65, /* USAGE_MAXIMUM (Keyboard Application) */
+ 0x81, 0x00, /* INPUT (Data,Ary,Abs) */
+ 0xc0 /* END_COLLECTION */
+ }
+ };
+
+ static struct platform_device my_hid = {
+ .name = "hidg",
+ .id = 0,
+ .num_resources = 0,
+ .resource = 0,
+ .dev.platform_data = &my_hid_data,
+ };
+
+你可以添加任意数量的HID功能，
+唯一的限制是gadget驱动所支持的中断端点数量。
+
+使用configfs进行配置
+======================
+
+与其通过添加虚拟的platform device和driver来向内核传递数据，不如这样做：
+如果HID是由configfs组成的gadget的一部分，
+hidg_func_descriptor.report_desc可以直接通过
+向configfs属性写入相应的字节流来传递给内核。
+
+发送和接收HID报告
+====================
+
+HID报告可以通过对/dev/hidgX字符设备执行
+read/write来发送或接收。下面是一个示例程序展示如何实现。
+
+hid_gadget_test是一个用于测试HID gadget驱动的小型交互程序。
+使用方式是指定一个hidg设备并设置设备类型（keyboard / mouse / joystick）
+—— 例如::
+
+ # hid_gadget_test /dev/hidg0 keyboard
+
+现在你进入了hid_gadget_test的提示界面。
+你可以输入任意组合的选项和值。
+可用的选项和值会在程序启动时列出。
+在键盘模式下，你最多可以发送六个值。
+
+例如输入： g i s t r --left-shift
+
+按回车后，会由HID gadget发送对应的报告。
+
+另一个有趣的例子是大小写锁定（caps lock）测试。
+输入--caps-lock 然后回车，gadget 会发送一个报告，
+并且你将收到主机端的回应，对应于 caps lock LED 的状态::
+
+ --caps-lock
+ recv report:2
+
+使用以下命令::
+
+ # hid_gadget_test /dev/hidg1 mouse
+
+你可以测试鼠标模拟。数值是两个有符号数。
+
+
+示例代码::
+
+ /* hid_gadget_test */
+
+ #include <pthread.h>
+ #include <string.h>
+ #include <stdio.h>
+ #include <ctype.h>
+ #include <fcntl.h>
+ #include <errno.h>
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <unistd.h>
+
+ #define BUF_LEN 512
+
+ struct options {
+ const char *opt;
+ unsigned char val;
+ };
+
+ static struct options kmod[] = {
+ {.opt = "--left-ctrl", .val = 0x01},
+ {.opt = "--right-ctrl", .val = 0x10},
+ {.opt = "--left-shift", .val = 0x02},
+ {.opt = "--right-shift", .val = 0x20},
+ {.opt = "--left-alt", .val = 0x04},
+ {.opt = "--right-alt", .val = 0x40},
+ {.opt = "--left-meta", .val = 0x08},
+ {.opt = "--right-meta", .val = 0x80},
+ {.opt = NULL}
+ };
+
+ static struct options kval[] = {
+ {.opt = "--return", .val = 0x28},
+ {.opt = "--esc", .val = 0x29},
+ {.opt = "--bckspc", .val = 0x2a},
+ {.opt = "--tab", .val = 0x2b},
+ {.opt = "--spacebar", .val = 0x2c},
+ {.opt = "--caps-lock", .val = 0x39},
+ {.opt = "--f1", .val = 0x3a},
+ {.opt = "--f2", .val = 0x3b},
+ {.opt = "--f3", .val = 0x3c},
+ {.opt = "--f4", .val = 0x3d},
+ {.opt = "--f5", .val = 0x3e},
+ {.opt = "--f6", .val = 0x3f},
+ {.opt = "--f7", .val = 0x40},
+ {.opt = "--f8", .val = 0x41},
+ {.opt = "--f9", .val = 0x42},
+ {.opt = "--f10", .val = 0x43},
+ {.opt = "--f11", .val = 0x44},
+ {.opt = "--f12", .val = 0x45},
+ {.opt = "--insert", .val = 0x49},
+ {.opt = "--home", .val = 0x4a},
+ {.opt = "--pageup", .val = 0x4b},
+ {.opt = "--del", .val = 0x4c},
+ {.opt = "--end", .val = 0x4d},
+ {.opt = "--pagedown", .val = 0x4e},
+ {.opt = "--right", .val = 0x4f},
+ {.opt = "--left", .val = 0x50},
+ {.opt = "--down", .val = 0x51},
+ {.opt = "--kp-enter", .val = 0x58},
+ {.opt = "--up", .val = 0x52},
+ {.opt = "--num-lock", .val = 0x53},
+ {.opt = NULL}
+ };
+
+ int keyboard_fill_report(char report[8], char buf[BUF_LEN], int *hold)
+ {
+ char *tok = strtok(buf, " ");
+ int key = 0;
+ int i = 0;
+
+ for (; tok != NULL; tok = strtok(NULL, " ")) {
+
+ if (strcmp(tok, "--quit") == 0)
+ return -1;
+
+ if (strcmp(tok, "--hold") == 0) {
+ *hold = 1;
+ continue;
+ }
+
+ if (key < 6) {
+ for (i = 0; kval[i].opt != NULL; i++)
+ if (strcmp(tok, kval[i].opt) == 0) {
+ report[2 + key++] = kval[i].val;
+ break;
+ }
+ if (kval[i].opt != NULL)
+ continue;
+ }
+
+ if (key < 6)
+ if (islower(tok[0])) {
+ report[2 + key++] = (tok[0] - ('a' - 0x04));
+ continue;
+ }
+
+ for (i = 0; kmod[i].opt != NULL; i++)
+ if (strcmp(tok, kmod[i].opt) == 0) {
+ report[0] = report[0] | kmod[i].val;
+ break;
+ }
+ if (kmod[i].opt != NULL)
+ continue;
+
+ if (key < 6)
+ fprintf(stderr, "unknown option: %s\n", tok);
+ }
+ return 8;
+ }
+
+ static struct options mmod[] = {
+ {.opt = "--b1", .val = 0x01},
+ {.opt = "--b2", .val = 0x02},
+ {.opt = "--b3", .val = 0x04},
+ {.opt = NULL}
+ };
+
+ int mouse_fill_report(char report[8], char buf[BUF_LEN], int *hold)
+ {
+ char *tok = strtok(buf, " ");
+ int mvt = 0;
+ int i = 0;
+ for (; tok != NULL; tok = strtok(NULL, " ")) {
+
+ if (strcmp(tok, "--quit") == 0)
+ return -1;
+
+ if (strcmp(tok, "--hold") == 0) {
+ *hold = 1;
+ continue;
+ }
+
+ for (i = 0; mmod[i].opt != NULL; i++)
+ if (strcmp(tok, mmod[i].opt) == 0) {
+ report[0] = report[0] | mmod[i].val;
+ break;
+ }
+ if (mmod[i].opt != NULL)
+ continue;
+
+ if (!(tok[0] == '-' && tok[1] == '-') && mvt < 2) {
+ errno = 0;
+ report[1 + mvt++] = (char)strtol(tok, NULL, 0);
+ if (errno != 0) {
+ fprintf(stderr, "Bad value:'%s'\n", tok);
+ report[1 + mvt--] = 0;
+ }
+ continue;
+ }
+
+ fprintf(stderr, "unknown option: %s\n", tok);
+ }
+ return 3;
+ }
+
+ static struct options jmod[] = {
+ {.opt = "--b1", .val = 0x10},
+ {.opt = "--b2", .val = 0x20},
+ {.opt = "--b3", .val = 0x40},
+ {.opt = "--b4", .val = 0x80},
+ {.opt = "--hat1", .val = 0x00},
+ {.opt = "--hat2", .val = 0x01},
+ {.opt = "--hat3", .val = 0x02},
+ {.opt = "--hat4", .val = 0x03},
+ {.opt = "--hatneutral", .val = 0x04},
+ {.opt = NULL}
+ };
+
+ int joystick_fill_report(char report[8], char buf[BUF_LEN], int *hold)
+ {
+ char *tok = strtok(buf, " ");
+ int mvt = 0;
+ int i = 0;
+
+ *hold = 1;
+
+ /* set default hat position: neutral */
+ report[3] = 0x04;
+
+ for (; tok != NULL; tok = strtok(NULL, " ")) {
+
+ if (strcmp(tok, "--quit") == 0)
+ return -1;
+
+ for (i = 0; jmod[i].opt != NULL; i++)
+ if (strcmp(tok, jmod[i].opt) == 0) {
+ report[3] = (report[3] & 0xF0) | jmod[i].val;
+ break;
+ }
+ if (jmod[i].opt != NULL)
+ continue;
+
+ if (!(tok[0] == '-' && tok[1] == '-') && mvt < 3) {
+ errno = 0;
+ report[mvt++] = (char)strtol(tok, NULL, 0);
+ if (errno != 0) {
+ fprintf(stderr, "Bad value:'%s'\n", tok);
+ report[mvt--] = 0;
+ }
+ continue;
+ }
+
+ fprintf(stderr, "unknown option: %s\n", tok);
+ }
+ return 4;
+ }
+
+ void print_options(char c)
+ {
+ int i = 0;
+
+ if (c == 'k') {
+ printf(" keyboard options:\n"
+ " --hold\n");
+ for (i = 0; kmod[i].opt != NULL; i++)
+ printf("\t\t%s\n", kmod[i].opt);
+ printf("\n keyboard values:\n"
+ " [a-z] or\n");
+ for (i = 0; kval[i].opt != NULL; i++)
+ printf("\t\t%-8s%s", kval[i].opt, i % 2 ? "\n" : "");
+ printf("\n");
+ } else if (c == 'm') {
+ printf(" mouse options:\n"
+ " --hold\n");
+ for (i = 0; mmod[i].opt != NULL; i++)
+ printf("\t\t%s\n", mmod[i].opt);
+ printf("\n mouse values:\n"
+ " Two signed numbers\n"
+ "--quit to close\n");
+ } else {
+ printf(" joystick options:\n");
+ for (i = 0; jmod[i].opt != NULL; i++)
+ printf("\t\t%s\n", jmod[i].opt);
+ printf("\n joystick values:\n"
+ " three signed numbers\n"
+ "--quit to close\n");
+ }
+ }
+
+ int main(int argc, const char *argv[])
+ {
+ const char *filename = NULL;
+ int fd = 0;
+ char buf[BUF_LEN];
+ int cmd_len;
+ char report[8];
+ int to_send = 8;
+ int hold = 0;
+ fd_set rfds;
+ int retval, i;
+
+ if (argc < 3) {
+ fprintf(stderr, "Usage: %s devname mouse|keyboard|joystick\n",
+ argv[0]);
+ return 1;
+ }
+
+ if (argv[2][0] != 'k' && argv[2][0] != 'm' && argv[2][0] != 'j')
+ return 2;
+
+ filename = argv[1];
+
+ if ((fd = open(filename, O_RDWR, 0666)) == -1) {
+ perror(filename);
+ return 3;
+ }
+
+ print_options(argv[2][0]);
+
+ while (42) {
+
+ FD_ZERO(&rfds);
+ FD_SET(STDIN_FILENO, &rfds);
+ FD_SET(fd, &rfds);
+
+ retval = select(fd + 1, &rfds, NULL, NULL, NULL);
+ if (retval == -1 && errno == EINTR)
+ continue;
+ if (retval < 0) {
+ perror("select()");
+ return 4;
+ }
+
+ if (FD_ISSET(fd, &rfds)) {
+ cmd_len = read(fd, buf, BUF_LEN - 1);
+ printf("recv report:");
+ for (i = 0; i < cmd_len; i++)
+ printf(" %02x", buf[i]);
+ printf("\n");
+ }
+
+ if (FD_ISSET(STDIN_FILENO, &rfds)) {
+ memset(report, 0x0, sizeof(report));
+ cmd_len = read(STDIN_FILENO, buf, BUF_LEN - 1);
+
+ if (cmd_len == 0)
+ break;
+
+ buf[cmd_len - 1] = '\0';
+ hold = 0;
+
+ memset(report, 0x0, sizeof(report));
+ if (argv[2][0] == 'k')
+ to_send = keyboard_fill_report(report, buf, &hold);
+ else if (argv[2][0] == 'm')
+ to_send = mouse_fill_report(report, buf, &hold);
+ else
+ to_send = joystick_fill_report(report, buf, &hold);
+
+ if (to_send == -1)
+ break;
+
+ if (write(fd, report, to_send) != to_send) {
+ perror(filename);
+ return 5;
+ }
+ if (!hold) {
+ memset(report, 0x0, sizeof(report));
+ if (write(fd, report, to_send) != to_send) {
+ perror(filename);
+ return 6;
+ }
+ }
+ }
+ }
+
+ close(fd);
+ return 0;
+ }
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 11/25] docs/zh_CN: Add gadget_multi.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (9 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 10/25] docs/zh_CN: Add gadget_hid.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 12/25] docs/zh_CN: Add gadget_printer.rst translation macrofun
` (13 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/gadget_multi.rst into Chinese.
Translate .../usb/gadget_multi.rst into Chinese.
("Documentation: USB: correct possessive "its" usage")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/gadget_multi.rst | 154 ++++++++++++++++++
1 file changed, 154 insertions(+)
create mode 100644 Documentation/translations/zh_CN/usb/gadget_multi.rst
diff --git a/Documentation/translations/zh_CN/usb/gadget_multi.rst b/Documentation/translations/zh_CN/usb/gadget_multi.rst
new file mode 100644
index 000000000000..cff16e89b9b4
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/gadget_multi.rst
@@ -0,0 +1,154 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/gadget_multi.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+======================
+多功能复合 Gadget
+======================
+
+概述
+====
+
+多功能复合 Gadget（或称 g_multi）是一个复合 Gadget，
+它充分利用复合框架来提供多功能设备。
+
+在其标准配置中，它提供一个 USB 配置，包含 RNDIS[1]（即以太网）、
+USB CDC[2] ACM（即串口）以及 USB 大容量存储功能。
+
+通过 Kconfig 选项，可以启用 CDC ECM（以太网）功能，同时可关闭 RNDIS。
+如果两者都启用，则 Gadget 将有两个配置——一个带 RNDIS，另一个带 CDC ECM[3]。
+
+请注意，如果使用非标准配置（即启用 CDC ECM），可能需要更改厂商 ID 和/或产品 ID。
+
+主机驱动
+========
+
+要使用该 Gadget，需要在主机端让它正常工作——
+否则 Gadget 无法发挥作用。
+如预期的那样，具体操作因系统而异。
+
+Linux 主机驱动
+--------------
+由于该 Gadget 使用标准复合框架并在 Linux 主机上显示为复合设备，
+Linux 主机端无需额外驱动。所有功能均由各自的驱动处理。
+
+对于两个配置的设置（以 RNDIS 配置为第一个配置）也是如此。
+Linux 主机会使用带 CDC ECM 的第二个配置，在 Linux 下通常效果更好。
+
+Windows 主机驱动
+--------------------
+
+要在 Windows 下使用该 Gadget，需要满足两个条件：
+
+作为复合 Gadget 检测
+^^^^^^^^^^^^^^^^^^^^^^^^
+首先，Windows 需要将 Gadget 检测为 USB 复合设备，这本身有一些条件[4]。
+满足这些条件后，Windows 会使用 USB 通用父驱动（USB Generic Parent Driver）[5] 处理设备，
+然后尝试为每个接口匹配相应的驱动（大致如此，不必深入细节）。
+
+好消息是：大部分条件你无需担心！
+
+唯一需要注意的是 Gadget 必须只有一个配置，因此双 RNDIS 和 CDC ECM 的 Gadget
+除非创建合适的 INF 文件，否则无法工作——当然，如果你提交了 INF 文件的话！
+
+为每个功能安装驱动
+^^^^^^^^^^^^^^^^^^^^
+
+另一个更棘手的问题是让 Windows 为每个独立功能安装驱动。
+
+对于大容量存储，这是简单的，因为 Windows 会检测它是 USB 大容量存储类接口，
+并选择合适的驱动。
+
+RNDIS 和 CDC ACM 则比较复杂。
+
+RNDIS
+.....
+
+为了让 Windows 为 Gadget 的第一个功能选择 RNDIS 驱动，
+需要使用本文档提供的 [[file:linux.inf]] 文件。
+它将 Windows 的 RNDIS 驱动“绑定”到 Gadget 的第一个接口。
+
+请注意，在测试过程中，如果 RNDIS 不是第一个接口，可能会遇到一些问题[6]。
+除非你在开发自己的 Gadget，否则无需担心此问题。
+
+CDC ACM
+.......
+
+同样，[[file:linux-cdc-acm.inf]] 文件用于 CDC ACM。
+
+自定义 Gadget
+................
+
+如果你打算修改 g_multi Gadget，请注意重新排列功能会改变每个功能的接口号。
+因此提供的 INF 文件将无法使用，因为接口号已硬编码（不过修改并不困难[7]）。
+
+这也意味着，在实验 g_multi 并修改提供的功能后，
+应更改 Gadget 的厂商 ID 和/或产品 ID，
+以避免与其他自定义 Gadget 或原始 Gadget 冲突。
+
+不遵循此建议可能会导致长时间调试无果，最终发现 Windows 缓存了某些驱动信息
+（更换 USB 端口有时有帮助，或者使用 USBDeview[8] 删除虚拟设备）。
+
+INF 测试
+........
+
+提供的 INF 文件已在 Windows XP SP3、
+Windows Vista 和 Windows 7（32 位版本）测试过。
+应能在 64 位版本上工作。
+在 Windows XP SP2 之前的系统上可能无法使用。
+
+其他系统
+--------
+
+目前尚未测试其他系统的驱动。
+考虑到 macOS 基于 BSD，BSD 是开源系统，
+理论上应能直接工作（读作：“我不确定是否能”）。
+
+对于其他较为小众的系统，我更无可奉告……
+
+任何测试和驱动都欢迎贡献！
+
+Authors
+=======
+
+本文档由 Michal Nazarewicz 编写
+([[mailto:mina86@mina86.com]])。
+INF 文件在 Marek Szyprowski ([[mailto:m.szyprowski@samsung.com
+]])
+和 Xiaofan Chen ([[mailto:xiaofanc@gmail.com]]) 的支持下修改，
+基于 MS RNDIS 模板[9]、Microchip 的 CDC ACM INF 文件以及
+David Brownell ([[mailto:dbrownell@users.sourceforge.net]]) 的原始 INF 文件。
+
+脚注
+====
+
+[1] 远程网络驱动接口规范（Remote Network Driver Interface Specification），
+[[https://msdn.microsoft.com/en-us/library/ee484414.aspx]].
+
+[2] 通信设备类抽象控制模型（Communications Device Class Abstract Control Model），
+该 USB 类及其他类规范可查阅
+[[http://www.usb.org/developers/devclass_docs/]].
+
+[3] CDC 以太网控制模型（CDC Ethernet Control Model），
+[[https://msdn.microsoft.com/en-us/library/ff537008(v=VS.85).aspx]].
+
+[4] [[https://msdn.microsoft.com/en-us/library/ff537109(v=VS.85).aspx]]
+
+[5] [[https://msdn.microsoft.com/en-us/library/ff539234(v=VS.85).aspx]]
+
+[6] 换句话说，Windows 对任何用户输入都未作响应。
+
+[7] 你可能会发现 [[http://www.cygnal.org/ubb/Forum9/HTML/001050.html]]
+有用。
+
+[8] https://www.nirsoft.net/utils/usb_devices_view.html
+
+[9] [[https://msdn.microsoft.com/en-us/library/ff570620.aspx]]
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 12/25] docs/zh_CN: Add gadget_printer.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (10 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 11/25] docs/zh_CN: Add gadget_multi.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 13/25] docs/zh_CN: Add gadget_serial.rst translation macrofun
` (12 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/gadget_printer.rst into Chinese.
Update the translation through commit 570eb861243c
("docs: usb: replace some characters")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/gadget_printer.rst | 535 ++++++++++++++++++
1 file changed, 535 insertions(+)
create mode 100644 Documentation/translations/zh_CN/usb/gadget_printer.rst
diff --git a/Documentation/translations/zh_CN/usb/gadget_printer.rst b/Documentation/translations/zh_CN/usb/gadget_printer.rst
new file mode 100644
index 000000000000..c4bbbb013d2d
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/gadget_printer.rst
@@ -0,0 +1,535 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/gadget_printer.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+============================
+Linux USB 打印机 Gadget 驱动
+============================
+
+2007年06月04日
+
+版权所有 (C) 2007 Craig W. Nadler <craig@nadler.us>
+
+
+
+概述
+====
+
+该驱动可用于在 Linux 嵌入式系统中开发打印机固件。
+请注意，它与在 Linux 主机上使用打印机无关。
+
+你需要一个 USB 设备控制器以及其对应的 Linux 驱动，
+该驱动支持使用 Linux USB Gadget API 的 gadget / 设备类驱动。
+加载 USB 设备控制器驱动后，再加载打印机 gadget 驱动。
+这样，连接到 USB 设备端口的主机将看到一个打印机接口。
+
+该驱动针对运行在用户态的打印机固件设计。
+用户态固件通过设备文件与内核态打印机 gadget 驱动读写数据。
+当 USB 主机发送获取打印机状态的请求时，打印机会返回状态字节。
+用户态固件可以通过设备文件 /dev/g_printer 读取或写入该状态字节。
+支持阻塞和非阻塞的读/写操作。
+
+
+
+
+使用方法
+========
+
+要加载 USB 设备控制器驱动和打印机 gadget 驱动。
+以下示例使用 Netchip 2280 USB 设备控制器驱动::
+
+ modprobe net2280
+ modprobe g_printer
+
+
+加载打印机 gadget 时，可指定以下命令行参数
+（例如：modprobe g_printer idVendor=0x0525 idProduct=0xa4a8）：
+
+idVendor
+ 设备描述符中的厂商 ID。默认值为 Netchip 的 0x0525。
+ 发布产品前必须更改为自己的厂商 ID。
+ 如果需要申请厂商 ID，请参考 www.usb.org
+
+idProduct
+ 设备描述符中的产品 ID。默认值为 0xa4a8。
+ 建议更改为其他未使用的 ID，产品编号可从 0x0001 开始。
+
+bcdDevice
+ 产品版本号，建议填写固件版本。
+
+iManufacturer
+ 厂商名称字符串。
+
+iProduct
+ 产品名称字符串。
+
+iSerialNum
+ 序列号字符串，每个产品单元应不同。
+
+iPNPstring
+ 打印机使用的 PNP ID 字符串，可在命令行指定或硬编码。
+
+qlen
+ 每个端点使用的 8k 缓冲区数量。默认值为 10，
+ 你应该根据你的产品进行调整。你也可能想调整
+ 每个缓冲区的大小以适应你的产品。
+
+
+
+
+示例代码使用
+============
+
+该示例代码将打印机数据发送到标准输出，而不是打印机引擎。
+
+要编译下面的测试代码：
+
+1) 将其保存为名为 prn_example.c 的文件
+2) 使用以下命令编译代码::
+
+ gcc prn_example.c -o prn_example
+
+
+
+从主机读取打印机数据到 stdout::
+
+ # prn_example -read_data
+
+
+将打印机数据从文件 (data_file) 写入主机::
+
+ # cat data_file | prn_example -write_data
+
+
+要获取 gadget 驱动的当前打印机状态::
+
+ # prn_example -get_status
+
+ Printer status is:
+ Printer is NOT Selected
+ Paper is Out
+ Printer OK
+
+
+设置打印机为选中/在线::
+
+ # prn_example -selected
+
+
+设置打印机为未选中/离线::
+
+ # prn_example -not_selected
+
+
+设置纸张状态为缺纸::
+
+ # prn_example -paper_out
+
+ # prn_example -paper_out
+
+
+设置纸张状态为有纸::
+
+ # prn_example -paper_loaded
+
+ # prn_example -paper_loaded
+
+
+设置错误状态为打印机正常::
+
+ # prn_example -no_error
+
+
+设置错误状态为错误::
+
+ # prn_example -error
+
+ # prn_example -no_error
+
+
+要设置错误状态为错误::
+
+ # prn_example -error
+
+
+
+
+示例代码
+========
+
+::
+
+
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <fcntl.h>
+ #include <linux/poll.h>
+ #include <sys/ioctl.h>
+ #include <linux/usb/g_printer.h>
+
+ #define PRINTER_FILE "/dev/g_printer"
+ #define BUF_SIZE 512
+
+
+ /*
+ * 'usage()' - Show program usage.
+ */
+
+ static void
+ usage(const char *option) /* I - Option string or NULL */
+ {
+ if (option) {
+ fprintf(stderr,"prn_example: Unknown option \"%s\"!\n",
+ option);
+ }
+
+ fputs("\n", stderr);
+ fputs("Usage: prn_example -[options]\n", stderr);
+ fputs("Options:\n", stderr);
+ fputs("\n", stderr);
+ fputs("-get_status Get the current printer status.\n", stderr);
+ fputs("-selected Set the selected status to selected.\n", stderr);
+ fputs("-not_selected Set the selected status to NOT selected.\n",
+ stderr);
+ fputs("-error Set the error status to error.\n", stderr);
+ fputs("-no_error Set the error status to NO error.\n", stderr);
+ fputs("-paper_out Set the paper status to paper out.\n", stderr);
+ fputs("-paper_loaded Set the paper status to paper loaded.\n",
+ stderr);
+ fputs("-read_data Read printer data from driver.\n", stderr);
+ fputs("-write_data Write printer sata to driver.\n", stderr);
+ fputs("-NB_read_data (Non-Blocking) Read printer data from driver.\n",
+ stderr);
+ fputs("\n\n", stderr);
+
+ exit(1);
+ }
+
+
+ static int
+ read_printer_data()
+ {
+ struct pollfd fd[1];
+
+ /* Open device file for printer gadget. */
+ fd[0].fd = open(PRINTER_FILE, O_RDWR);
+ if (fd[0].fd < 0) {
+ printf("Error %d opening %s\n", fd[0].fd, PRINTER_FILE);
+ close(fd[0].fd);
+ return(-1);
+ }
+
+ fd[0].events = POLLIN | POLLRDNORM;
+
+ while (1) {
+ static char buf[BUF_SIZE];
+ int bytes_read;
+ int retval;
+
+ /* Wait for up to 1 second for data. */
+ retval = poll(fd, 1, 1000);
+
+ if (retval && (fd[0].revents & POLLRDNORM)) {
+
+ /* Read data from printer gadget driver. */
+ bytes_read = read(fd[0].fd, buf, BUF_SIZE);
+
+ if (bytes_read < 0) {
+ printf("Error %d reading from %s\n",
+ fd[0].fd, PRINTER_FILE);
+ close(fd[0].fd);
+ return(-1);
+ } else if (bytes_read > 0) {
+ /* Write data to standard OUTPUT (stdout). */
+ fwrite(buf, 1, bytes_read, stdout);
+ fflush(stdout);
+ }
+
+ }
+
+ }
+
+ /* Close the device file. */
+ close(fd[0].fd);
+
+ return 0;
+ }
+
+
+ static int
+ write_printer_data()
+ {
+ struct pollfd fd[1];
+
+ /* Open device file for printer gadget. */
+ fd[0].fd = open (PRINTER_FILE, O_RDWR);
+ if (fd[0].fd < 0) {
+ printf("Error %d opening %s\n", fd[0].fd, PRINTER_FILE);
+ close(fd[0].fd);
+ return(-1);
+ }
+
+ fd[0].events = POLLOUT | POLLWRNORM;
+
+ while (1) {
+ int retval;
+ static char buf[BUF_SIZE];
+ /* Read data from standard INPUT (stdin). */
+ int bytes_read = fread(buf, 1, BUF_SIZE, stdin);
+
+ if (!bytes_read) {
+ break;
+ }
+
+ while (bytes_read) {
+
+ /* Wait for up to 1 second to sent data. */
+ retval = poll(fd, 1, 1000);
+
+ /* Write data to printer gadget driver. */
+ if (retval && (fd[0].revents & POLLWRNORM)) {
+ retval = write(fd[0].fd, buf, bytes_read);
+ if (retval < 0) {
+ printf("Error %d writing to %s\n",
+ fd[0].fd,
+ PRINTER_FILE);
+ close(fd[0].fd);
+ return(-1);
+ } else {
+ bytes_read -= retval;
+ }
+
+ }
+
+ }
+
+ }
+
+ /* Wait until the data has been sent. */
+ fsync(fd[0].fd);
+
+ /* Close the device file. */
+ close(fd[0].fd);
+
+ return 0;
+ }
+
+
+ static int
+ read_NB_printer_data()
+ {
+ int fd;
+ static char buf[BUF_SIZE];
+ int bytes_read;
+
+ /* Open device file for printer gadget. */
+ fd = open(PRINTER_FILE, O_RDWR|O_NONBLOCK);
+ if (fd < 0) {
+ printf("Error %d opening %s\n", fd, PRINTER_FILE);
+ close(fd);
+ return(-1);
+ }
+
+ while (1) {
+ /* Read data from printer gadget driver. */
+ bytes_read = read(fd, buf, BUF_SIZE);
+ if (bytes_read <= 0) {
+ break;
+ }
+
+ /* Write data to standard OUTPUT (stdout). */
+ fwrite(buf, 1, bytes_read, stdout);
+ fflush(stdout);
+ }
+
+ /* Close the device file. */
+ close(fd);
+
+ return 0;
+ }
+
+
+ static int
+ get_printer_status()
+ {
+ int retval;
+ int fd;
+
+ /* Open device file for printer gadget. */
+ fd = open(PRINTER_FILE, O_RDWR);
+ if (fd < 0) {
+ printf("Error %d opening %s\n", fd, PRINTER_FILE);
+ close(fd);
+ return(-1);
+ }
+
+ /* Make the IOCTL call. */
+ retval = ioctl(fd, GADGET_GET_PRINTER_STATUS);
+ if (retval < 0) {
+ fprintf(stderr, "ERROR: Failed to set printer status\n");
+ return(-1);
+ }
+
+ /* Close the device file. */
+ close(fd);
+
+ return(retval);
+ }
+
+
+ static int
+ set_printer_status(unsigned char buf, int clear_printer_status_bit)
+ {
+ int retval;
+ int fd;
+
+ retval = get_printer_status();
+ if (retval < 0) {
+ fprintf(stderr, "ERROR: Failed to get printer status\n");
+ return(-1);
+ }
+
+ /* Open device file for printer gadget. */
+ fd = open(PRINTER_FILE, O_RDWR);
+
+ if (fd < 0) {
+ printf("Error %d opening %s\n", fd, PRINTER_FILE);
+ close(fd);
+ return(-1);
+ }
+
+ if (clear_printer_status_bit) {
+ retval &= ~buf;
+ } else {
+ retval |= buf;
+ }
+
+ /* Make the IOCTL call. */
+ if (ioctl(fd, GADGET_SET_PRINTER_STATUS, (unsigned char)retval)) {
+ fprintf(stderr, "ERROR: Failed to set printer status\n");
+ return(-1);
+ }
+
+ /* Close the device file. */
+ close(fd);
+
+ return 0;
+ }
+
+
+ static int
+ display_printer_status()
+ {
+ char printer_status;
+
+ printer_status = get_printer_status();
+ if (printer_status < 0) {
+ fprintf(stderr, "ERROR: Failed to get printer status\n");
+ return(-1);
+ }
+
+ printf("Printer status is:\n");
+ if (printer_status & PRINTER_SELECTED) {
+ printf(" Printer is Selected\n");
+ } else {
+ printf(" Printer is NOT Selected\n");
+ }
+ if (printer_status & PRINTER_PAPER_EMPTY) {
+ printf(" Paper is Out\n");
+ } else {
+ printf(" Paper is Loaded\n");
+ }
+ if (printer_status & PRINTER_NOT_ERROR) {
+ printf(" Printer OK\n");
+ } else {
+ printf(" Printer ERROR\n");
+ }
+
+ return(0);
+ }
+
+
+ int
+ main(int argc, char *argv[])
+ {
+ int i; /* Looping var */
+ int retval = 0;
+
+ /* No Args */
+ if (argc == 1) {
+ usage(0);
+ exit(0);
+ }
+
+ for (i = 1; i < argc && !retval; i ++) {
+
+ if (argv[i][0] != '-') {
+ continue;
+ }
+
+ if (!strcmp(argv[i], "-get_status")) {
+ if (display_printer_status()) {
+ retval = 1;
+ }
+
+ } else if (!strcmp(argv[i], "-paper_loaded")) {
+ if (set_printer_status(PRINTER_PAPER_EMPTY, 1)) {
+ retval = 1;
+ }
+
+ } else if (!strcmp(argv[i], "-paper_out")) {
+ if (set_printer_status(PRINTER_PAPER_EMPTY, 0)) {
+ retval = 1;
+ }
+
+ } else if (!strcmp(argv[i], "-selected")) {
+ if (set_printer_status(PRINTER_SELECTED, 0)) {
+ retval = 1;
+ }
+
+ } else if (!strcmp(argv[i], "-not_selected")) {
+ if (set_printer_status(PRINTER_SELECTED, 1)) {
+ retval = 1;
+ }
+
+ } else if (!strcmp(argv[i], "-error")) {
+ if (set_printer_status(PRINTER_NOT_ERROR, 1)) {
+ retval = 1;
+ }
+
+ } else if (!strcmp(argv[i], "-no_error")) {
+ if (set_printer_status(PRINTER_NOT_ERROR, 0)) {
+ retval = 1;
+ }
+
+ } else if (!strcmp(argv[i], "-read_data")) {
+ if (read_printer_data()) {
+ retval = 1;
+ }
+
+ } else if (!strcmp(argv[i], "-write_data")) {
+ if (write_printer_data()) {
+ retval = 1;
+ }
+
+ } else if (!strcmp(argv[i], "-NB_read_data")) {
+ if (read_NB_printer_data()) {
+ retval = 1;
+ }
+
+ } else {
+ usage(argv[i]);
+ retval = 1;
+ }
+ }
+
+ exit(retval);
+ }
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 13/25] docs/zh_CN: Add gadget_serial.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (11 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 12/25] docs/zh_CN: Add gadget_printer.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 14/25] docs/zh_CN: Add gadget_uvc.rst translation macrofun
` (11 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/gadget_serial.rst into Chinese.
Update the translation through commit ecefae6db042
("docs: usb: rename files to .rst and add them to drivers-api")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/gadget_serial.rst | 259 ++++++++++++++++++
1 file changed, 259 insertions(+)
create mode 100644 Documentation/translations/zh_CN/usb/gadget_serial.rst
diff --git a/Documentation/translations/zh_CN/usb/gadget_serial.rst b/Documentation/translations/zh_CN/usb/gadget_serial.rst
new file mode 100644
index 000000000000..9d49d535b0b2
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/gadget_serial.rst
@@ -0,0 +1,259 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/gadget_serial.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+==========================
+Linux Gadget 串口驱动 v2.0
+==========================
+
+2004/11/20
+
+(v2.3 更新于 2008/05/08)
+
+
+许可证与免责声明
+-------------------
+本程序是自由软件；您可以依据自由软件基金会发布的GNU通用公共许可证第2版，
+或（由您选择的）任何更高版本的规定，对本程序进行再发布和/或修改。
+
+我们希望本程序有用，但不提供任何担保；甚至不包含对适销性或适用于特定目的的默示性担保。
+更多细节请参阅GNU通用公共许可证。
+
+您应该已经随本程序收到GNU通用公共许可证副本；
+如果没有，请写信至：Free Software Foundation, Inc., 59
+Temple Place, Suite 330, Boston, MA 02111-1307 USA。
+
+本文档及Gadget串口驱动版权所有
+ (C) 2004 Al Borchers (alborchers@steinerpoint.com)。
+
+如有问题或建议，请联系Al Borchers（邮箱 alborchers@steinerpoint.com）。
+
+
+前提条件
+--------
+Gadget 串口驱动可用于 2.4 Linux 内核版本，
+但本文档假定使用 2.6 内核上的 2.3 或更高版本。
+
+本文档假设你熟悉Linux与Windows，
+了解如何配置与编译Linux内核、运行标准工具、
+使用minicom或HyperTerminal，并操作 USB 与串口设备。
+还假设你将Linux gadget和USB驱动配置为模块。
+
+在v2.3版本中，设备节点的主次设备号不再静态定义。
+基于Linux的系统应挂载sysfs到/sys，
+并使用mdev（Busybox）或udev来创建匹配/sys/class/tty的/dev节点。
+
+
+
+概述
+----
+Gadget 串口驱动是 Linux USB gadget 驱动，即 USB 设备端驱动。
+它运行在具有 USB 设备端硬件的 Linux 系统上，
+例如 PDA、嵌入式 Linux 系统或带 USB 开发卡的 PC。
+
+驱动通过 USB 与主机上的 CDC ACM 驱动或通用 USB 串口驱动通信：::
+
+ 主机端
+ --------------------------------------
+ | Host-Side CDC ACM USB Host |
+ | Operating | or | Controller | USB
+ | System | Generic USB | Driver |--------
+ | (Linux or | Serial | and | |
+ | Windows) Driver USB Stack | |
+ -------------------------------------- |
+ |
+ |
+ |
+ Gadget 端 |
+ -------------------------------------- |
+ | Gadget USB Periph. | |
+ | Device-Side | Gadget | Controller | |
+ | Linux | Serial | Driver |--------
+ | Operating | Driver | and |
+ | System USB Stack |
+ --------------------------------------
+
+在设备端，Gadget 串口驱动表现为一个串口设备。
+在主机端，它表现为 CDC ACM 兼容类设备或
+具有 Bulk 输入/输出端点的厂商特定设备，可像普通串口设备一样使用。
+
+在主机端系统上，Gadget 串口设备看起来像一个
+CDC ACM 兼容类设备或一个简单的厂商特定设备，
+具有 Bulk 输入和输出端点，并且它的处理方式类似
+于其他串口设备。
+
+通过 Gadget 串口驱动和主机端 ACM/通用串口驱动，
+你可以像使用串口线一样在主机与设备端系统间通信。
+
+Gadget 串口驱动只提供简单、不可靠的数据通信，
+目前不支持流控及常规串口的其他高级功能。
+
+
+安装 Gadget 串口驱动
+--------------------
+要使用 Gadget 串口驱动，
+您必须为 Linux gadget 端内核配置“支持 USB Gadgets”，
+为“USB 外设控制器”（例如 net2280）以及“串口 Gadget”驱动程序。
+所有这些都列在配置内核时的“USB Gadget 支持”下。
+然后重新构建并安装内核或模块.
+
+然后，你必须加载 Gadget 串口驱动。
+要将其作为 ACM 设备（推荐以提高兼容性）加载，请执行以下命令::
+
+ modprobe g_serial
+
+要将其作为厂商特定的 Bulk 输入/输出设备加载，请执行以下命令::
+
+ modprobe g_serial use_acm=0
+
+此操作也会自动加载底层的 Gadget 外设控制器驱动。
+每次重启 Gadget 端 Linux 系统时都必须执行此操作。
+如果需要，可以将其添加到启动脚本中。
+
+你的系统应使用 mdev（来自 Busybox）或 udev 来创建设备节点。
+在设置好该 Gadget 驱动后，你应能看到 /dev/ttyGS0 节点::
+
+ # ls -l /dev/ttyGS0 | cat
+ crw-rw---- 1 root root 253, 0 May 8 14:10 /dev/ttyGS0
+ #
+
+注意，上述主设备号（253）依系统而异。
+如果需要手动创建 /dev 节点，
+正确的主/次设备号可在 /sys/class/tty/ttyGS0/dev 文件中找到。
+
+如果你希望较早（甚至静态地）链接此 Gadget 驱动，
+可能需要在 /etc/inittab 中设置一条记录以在该设备上运行 getty。
+/dev/ttyGS0 行应像其他串口端口一样工作。
+
+
+如果 Gadget 串口以 ACM 设备方式加载，
+你需要在主机端使用 Windows 或 Linux 的 ACM 驱动。
+如果 Gadget 串口以 Bulk 输入/输出设备方式加载，
+你需要在主机端使用 Linux 通用串口驱动。
+请按照下面的说明安装主机端驱动。
+
+
+安装 Windows 主机 ACM 驱动
+--------------------------
+要使用 Windows ACM 驱动，你必须拥有 linux-cdc-acm.inf 文件（随本文件提供），
+支持所有近期版本的 Windows。
+
+当加载 Gadget 串口驱动并用 USB 数据线连接设备到 Windows 主机时，
+Windows 应识别该设备并提示安装驱动。
+告诉 Windows 在包含 linux-cdc-acm.inf 文件的文件夹中查找驱动。
+
+例如，在 Windows XP 上，首次插入 Gadget 串口设备时，会启动“新硬件向导”。
+选择“从列表或指定位置安装（高级）”，然后在下一屏选择“包括此位置进行搜索”，
+并输入或浏览到包含 linux-cdc-acm.inf 文件的文件夹。
+Windows 会提示 Gadget Serial 驱动未通过 Windows Logo 测试，
+但选择“继续安装”，完成驱动安装。
+
+在 Windows XP 的“设备管理器”（控制面板 → 系统 → 硬件）
+中展开“端口（COM & LPT）”条目，
+你应看到“Gadget Serial”列为某个 COM 端口的驱动。
+
+要卸载 Windows XP 上的 Gadget Serial 驱动：
+右键单击设备管理器中的“Gadget Serial”条目，选择“卸载”。
+
+
+安装 Linux 主机 ACM 驱动
+------------------------
+要使用 Linux ACM 驱动，必须在 Linux 主机内核中启用：
+“Host-side USB 支持”以及“USB Modem (CDC ACM) 支持”。
+
+当 Gadget 串口驱动加载且设备通过 USB 连接到 Linux 主机后，
+主机系统应能识别 Gadget 串口设备。
+例如，执行命令::
+
+ cat /sys/kernel/debug/usb/devices
+
+输出应类似:::
+
+ T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 5 Spd=480 MxCh= 0
+ D: Ver= 2.00 Cls=02(comm.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1
+ P: Vendor=0525 ProdID=a4a7 Rev= 2.01
+ S: Manufacturer=Linux 2.6.8.1 with net2280
+ S: Product=Gadget Serial
+ S: SerialNumber=0
+ C:* #Ifs= 2 Cfg#= 2 Atr=c0 MxPwr= 2mA
+ I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm
+ E: Ad=83(I) Atr=03(Int.) MxPS= 8 Ivl=32ms
+ I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm
+ E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms
+ E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms
+
+如果主机 Linux 系统配置正确，ACM 驱动应自动加载。
+执行 lsmod 命令应显示 acm 模块已加载。
+
+
+安装 Linux 主机通用 USB 串口驱动
+-------------------------------------
+要使用 Linux 通用 USB 串口驱动，必须在 Linux 主机内核中启用：
+“Host-side USB 支持”、“USB 串口转换器支持”以及“USB 通用串口驱动”。
+
+当 Gadget 串口驱动加载且设备通过 USB 连接到 Linux 主机后，
+主机系统应能识别 Gadget 串口设备。
+例如，执行命令::
+
+ cat /sys/kernel/debug/usb/devices
+
+输出应类似:::
+ T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 6 Spd=480 MxCh= 0
+ D: Ver= 2.00 Cls=ff(vend.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1
+ P: Vendor=0525 ProdID=a4a6 Rev= 2.01
+ S: Manufacturer=Linux 2.6.8.1 with net2280
+ S: Product=Gadget Serial
+ S: SerialNumber=0
+ C:* #Ifs= 1 Cfg#= 1 Atr=c0 MxPwr= 2mA
+ I: If#= 0 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=serial
+ E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms
+ E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms
+
+你必须加载 usbserial 驱动并显式设置其参数
+以配置其识别 Gadget 串口设备，如下所示::
+
+ echo 0x0525 0xA4A6 >/sys/bus/usb-serial/drivers/generic/new_id
+
+传统方法是使用模块参数::
+
+ modprobe usbserial vendor=0x0525 product=0xA4A6
+
+如果一切正常，usbserial 会在系统日志中打印一条消息，
+类似于 "Gadget Serial converter now attached to ttyUSB0"。
+
+
+使用Minicom或HyperTerminal测试
+------------------------------
+一旦 Gadget 串口驱动和主机驱动都安装完成，
+并且通过 USB 数据线将 Gadget 设备连接到主机，
+你应该能够在 Gadget 和主机系统之间通过 USB 进行通信。
+你可以使用 minicom 或 HyperTerminal 来尝试这一点。
+在 Gadget 端运行 "minicom -s" 来配置一个新的 minicom 会话。
+在“串口设置”中，将“串口设备”设置为 "/dev/ttygserial"。
+设置波特率、数据位、校验位和停止位为 9600、8、无和 1——这些设置大多无关紧要。
+在“调制解调器和拨号”中，清除所有调制解调器和拨号字符串。
+
+在运行 ACM 驱动的 Linux 主机上，类似地配置 minicom，
+但将“串口设备”设置为 "/dev/ttyACM0"。（如果连接了其他
+ACM 设备，请相应地更改设备名称。）
+
+在运行 USB 通用串口驱动的 Linux 主机上，类似地配置 minicom，
+但将“串口设备”设置为 "/dev/ttyUSB0"。（如果连接了其他
+USB 串口设备，请相应地更改设备名称。）
+
+在 Windows 主机上，配置一个新的 HyperTerminal 会话，
+使用分配给 Gadget Serial 的 COM 端口。
+当 HyperTerminal 连接到 Gadget Serial 设备时，
+“端口设置”将自动设置，因此你可以保持默认值不变——这些设置大多无关紧要。
+
+当 Gadget 端的 minicom 和主机端的 minicom 或 HyperTerminal 都配置并运行时，
+你应该能够在 Gadget 端和主机端系统之间通过 USB 发送和接收数据。
+你在 Gadget 端终端窗口中输入的任何内容都应出现在主机端的终端窗口中，反之亦然。
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 14/25] docs/zh_CN: Add gadget_uvc.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (12 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 13/25] docs/zh_CN: Add gadget_serial.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 15/25] docs/zh_CN: Add gadget-testing.rst translation macrofun
` (10 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/gadget_uvc.rst into Chinese.
Update the translation through commit 16794ed32de9
("docs: usb: fix reference to nonexistent file in UVC Gadget")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/gadget_uvc.rst | 372 ++++++++++++++++++
1 file changed, 372 insertions(+)
create mode 100644 Documentation/translations/zh_CN/usb/gadget_uvc.rst
diff --git a/Documentation/translations/zh_CN/usb/gadget_uvc.rst b/Documentation/translations/zh_CN/usb/gadget_uvc.rst
new file mode 100644
index 000000000000..de53a05a2c76
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/gadget_uvc.rst
@@ -0,0 +1,372 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/gadget_uvc.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+======================
+Linux UVC Gadget 驱动
+======================
+
+概述
+------
+UVC Gadget 驱动是针对 USB 设备端硬件的驱动，
+适用于在具有 USB 设备端硬件（例如带 OTG 接口的开发板）的 Linux 系统上运行。
+
+在设备系统上，一旦驱动绑定成功，它会以 V4L2 设备的形式出现，并具有输出能力。
+
+在主机端（通过 USB 连接后），
+运行 UVC Gadget 驱动的设备（由相应用户空间程序控制）
+应表现为符合 UVC 规范的摄像头，并能与任何支持 UVC 的程序正常工作。
+设备端的用户空间程序可以将来自各种源的图像缓冲区排入队列，
+通过 USB 传输。通常，这意味着转发来自摄像头传感器的缓冲区，
+但缓冲区的来源完全由用户空间程序决定。
+
+配置设备内核
+--------------
+要启用 UVC Gadget 支持，必须在内核 Kconfig 中选择以下选项:
+USB_CONFIGFS, USB_LIBCOMPOSITE, USB_CONFIGFS_F_UVC和
+USB_F_UVC。
+
+通过 configfs 配置 Gadget
+---------------------------
+UVC Gadget 通过 configfs 使用 UVC 功能进行配置。
+这种方式提供了很大灵活性，因为 UVC 设备的许多设置可以通过它控制。
+
+并非所有可用的属性都在此处描述。有关完整的枚举，
+请参阅 Documentation/ABI/testing/configfs-usb-gadget-uvc
+
+前提条件
+~~~~~~~~~~~
+假设你已将 configfs 挂载到 `/sys/kernel/config` 并
+创建了一个 gadget，路径为 `/sys/kernel/config/usb_gadget/g1`。
+
+UVC 功能
+~~~~~~~~~~~
+第一步是创建 UVC 功能：
+
+.. code-block:: bash
+
+ # These variables will be assumed throughout the rest of the document
+ CONFIGFS="/sys/kernel/config"
+ GADGET="$CONFIGFS/usb_gadget/g1"
+ FUNCTION="$GADGET/functions/uvc.0"
+
+ mkdir -p $FUNCTION
+
+格式与帧
+~~~~~~~~~~
+
+必须告诉 gadget 支持哪些格式，以及每种格式支持的帧大小和帧间隔。
+当前实现中，gadget 无法拒绝主机要求设置的格式，
+因此必须准确配置，以确保主机不会请求无法提供的格式。
+
+格式在 streaming/uncompressed 和 streaming/mjpeg configfs 分组下创建，
+帧大小在格式下创建，结构如下：
+
+::
+
+ uvc.0 +
+ |
+ + streaming +
+ |
+ + mjpeg +
+ | |
+ | + mjpeg +
+ | |
+ | + 720p
+ | |
+ | + 1080p
+ |
+ + uncompressed +
+ |
+ + yuyv +
+ |
+ + 720p
+ |
+ + 1080p
+
+每个帧都可以配置宽度和高度，以及存储单个帧所需的最大缓冲区大小，
+最后还可以配置该格式和帧大小所支持的帧间隔。
+宽度和高度以像素为单位枚举，
+帧间隔以 100ns 为单位。
+例如，要为每个帧大小创建上面结构中 2、15 和 100 fps 的帧间隔，
+可以这样操作：
+
+.. code-block:: bash
+
+ create_frame() {
+ # 示例用法:
+ # create_frame <width> <height> <group> <format name>
+
+ WIDTH=$1
+ HEIGHT=$2
+ FORMAT=$3
+ NAME=$4
+
+ wdir=$FUNCTION/streaming/$FORMAT/$NAME/${HEIGHT}p
+
+ mkdir -p $wdir
+ echo $WIDTH > $wdir/wWidth
+ echo $HEIGHT > $wdir/wHeight
+ echo $(( $WIDTH * $HEIGHT * 2 )) > $wdir/dwMaxVideoFrameBufferSize
+ cat <<EOF > $wdir/dwFrameInterval
+ 666666
+ 100000
+ 5000000
+ EOF
+ }
+
+ create_frame 1280 720 uncompressed yuyv
+ create_frame 1920 1080 uncompressed yuyv
+
+目前唯一支持的未压缩格式是YUYV，
+详细说明请参见Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst。
+
+颜色匹配描述符
+~~~~~~~~~~~~~~
+可以为你创建的每种格式指定一些色彩信息。
+此步骤为可选操作，如果跳过该步骤，
+将使用默认信息；
+这些默认值遵循UVC规范中Color Matching Descriptor部分的定义。
+
+要创建颜色匹配描述符，需要先创建一个configfs item，
+并将其三个属性设置为你期望的值，然后从希望关联的格式中链接到该item：
+
+.. code-block:: bash
+
+ # Create a new Color Matching Descriptor
+
+ mkdir $FUNCTION/streaming/color_matching/yuyv
+ pushd $FUNCTION/streaming/color_matching/yuyv
+
+ echo 1 > bColorPrimaries
+ echo 1 > bTransferCharacteristics
+ echo 4 > bMatrixCoefficients
+
+ popd
+
+ # Create a symlink to the Color Matching Descriptor from the format's config item
+ ln -s $FUNCTION/streaming/color_matching/yuyv $FUNCTION/streaming/uncompressed/yuyv
+
+有关有效值的详细信息，请参阅UVC规范。
+请注意，存在一个默认的Color Matching Descriptor，
+任何没有链接到其他Color Matching Descriptor的格式都会使用它。
+可以修改默认描述符的属性设置，但请注意，
+如果你这样做，就会改变所有未链接到其他描述符的格式的默认设置。
+
+
+头部链接
+~~~~~~~~~~~~~~~
+
+UVC规范要求Format和Frame描述符之前必须有头部（Header），
+用于描述随后不同Format描述符的数量和累计大小等信息。
+在configfs中，这类操作是通过将表示头部的
+configfs item与表示其他描述符的config item进行链接来实现的，方式如下：
+
+.. code-block:: bash
+
+ mkdir $FUNCTION/streaming/header/h
+
+ # This section links the format descriptors and their associated frames
+ # to the header
+ cd $FUNCTION/streaming/header/h
+ ln -s ../../uncompressed/yuyv
+ ln -s ../../mjpeg/mjpeg
+
+ # This section ensures that the header will be transmitted for each
+ # speed's set of descriptors. If support for a particular speed is not
+ # needed then it can be skipped here.
+ cd ../../class/fs
+ ln -s ../../header/h
+ cd ../../class/hs
+ ln -s ../../header/h
+ cd ../../class/ss
+ ln -s ../../header/h
+ cd ../../../control
+ mkdir header/h
+ ln -s header/h class/fs
+ ln -s header/h class/ss
+
+
+扩展单元支持
+~~~~~~~~~~~~~~~
+
+UVC扩展单元（XU）基本上提供了一个独立的单元，
+可以向其发送控制的set和get请求。
+这些控制请求的含义完全依赖于具体实现，
+但可用于控制UVC规范之外的设置（例如启用或禁用视频效果）。
+XU可以插入到UVC单元链中，也可以保持独立悬挂。
+
+配置扩展单元涉及在相应目录中创建一个条目，并适当地设置其属性，如下所示：
+
+.. code-block:: bash
+
+ mkdir $FUNCTION/control/extensions/xu.0
+ pushd $FUNCTION/control/extensions/xu.0
+
+ # Set the bUnitID of the Processing Unit as the source for this
+ # Extension Unit
+ echo 2 > baSourceID
+
+ # Set this XU as the source of the default output terminal. This inserts
+ # the XU into the UVC chain between the PU and OT such that the final
+ # chain is IT > PU > XU.0 > OT
+ cat bUnitID > ../../terminal/output/default/baSourceID
+
+ # Flag some controls as being available for use. The bmControl field is
+ # a bitmap with each bit denoting the availability of a particular
+ # control. For example to flag the 0th, 2nd and 3rd controls available:
+ echo 0x0d > bmControls
+
+ # Set the GUID; this is a vendor-specific code identifying the XU.
+ echo -e -n "\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f\x10" > guidExtensionCode
+
+ popd
+
+bmControls属性和baSourceID属性是多值属性。
+这意味着你可以向它们写入多个以换行符分隔的值。
+例如，要标记第1、第2、第9和第10个控制可用，
+你需要向bmControls写入两个值，如下所示：
+
+.. code-block:: bash
+
+ cat << EOF > bmControls
+ 0x03
+ 0x03
+ EOF
+
+baSourceID属性的多值特性暗示了XU可以有多个输入，但请注意，这目前没有显著影响。
+
+bControlSize属性表示bmControls属性的大小，
+类似地，bNrInPins表示baSourceID属性的大小。
+随着你设置bmControls和baSourceID，这两个属性会自动增减。
+也可以手动增加或减少bControlSize，
+这会导致条目被截断到新的大小，或者用0x00填充条目，例如：
+
+::
+
+ $ cat bmControls
+ 0x03
+ 0x05
+
+ $ cat bControlSize
+ 2
+
+ $ echo 1 > bControlSize
+ $ cat bmControls
+ 0x03
+
+ $ echo 2 > bControlSize
+ $ cat bmControls
+ 0x03
+ 0x00
+
+bNrInPins和baSourceID的功能相同。
+
+配置摄像头终端和处理单元的支持控制
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+UVC链中的摄像头终端（Camera Terminal）和处理单元（Processing Unit）
+也具有bmControls属性，其功能与扩展单元（XU）中的相同字段类似。
+然而，与XU不同的是，这些单元的位标志含义在UVC规范中已有定义；
+有关标志的枚举，请参阅“Camera Terminal Descriptor”和
+“Processing Unit Descriptor”部分。
+
+.. code-block:: bash
+
+ # Set the Processing Unit's bmControls, flagging Brightness, Contrast
+ # and Hue as available controls:
+ echo 0x05 > $FUNCTION/control/processing/default/bmControls
+
+ # Set the Camera Terminal's bmControls, flagging Focus Absolute and
+ # Focus Relative as available controls:
+ echo 0x60 > $FUNCTION/control/terminal/camera/default/bmControls
+
+如果你不设置这些字段，则默认情况下摄像头终端（Camera Terminal）
+的自动曝光模式（Auto-Exposure Mode）控制
+和处理单元（Processing Unit）的亮度（Brightness）控制
+会被标记为可用；
+如果不支持这些功能，你应将字段设置为0x00。
+
+请注意，摄像头终端或处理单元的bmControls字段大小由UVC规范固定，
+因此此处的bControlSize属性为只读。
+
+自定义字符串支持
+~~~~~~~~~~~~~~~~~~~~~~~
+
+为USB设备各部分提供文本描述的字符串描述符（String Descriptor）
+可以在USB configfs的常规位置定义，
+然后可以从UVC功能根（UVC function root）或
+扩展单元（Extension Unit）目录中链接这些字符串，
+以将其作为描述符分配：
+
+.. code-block:: bash
+
+ # 在us-EN中创建一个字符串描述符，并从function root链接到它。
+ # 链接的名称在这里很重要，因为它声明该描述符用于Interface Association Descriptor。
+ # function root中其他重要的链接名称包括vs0_desc和vs1_desc，
+ # 用于VideoStreaming接口0/1描述符。
+
+ mkdir -p $GADGET/strings/0x409/iad_desc
+ echo -n "Interface Associaton Descriptor" > $GADGET/strings/0x409/iad_desc/s
+ ln -s $GADGET/strings/0x409/iad_desc $FUNCTION/iad_desc
+
+ # 由于从Extension Unit链接到String Descriptor会明确关联两者，
+ # 因此该链接的名称不重要，可以自由设置。
+
+ mkdir -p $GADGET/strings/0x409/xu.0
+ echo -n "A Very Useful Extension Unit" > $GADGET/strings/0x409/xu.0/s
+ ln -s $GADGET/strings/0x409/xu.0 $FUNCTION/control/extensions/xu.0
+
+中断端点
+~~~~~~~~
+
+VideoControl接口具有一个可选的中断端点，默认情况下处于禁用状态。
+该端点用于支持UVC的延迟响应控制设置请求
+（这些请求应通过中断端点响应，而不是占用端点0）。
+目前尚不支持通过该端点发送数据，因此默认禁用以避免混淆。
+如果你希望启用它，可以通过configfs属性进行设置：
+
+.. code-block:: bash
+
+ echo 1 > $FUNCTION/control/enable_interrupt_ep
+
+带宽配置
+~~~~~~~~
+
+有三个属性控制USB连接的带宽。
+这些属性位于功能根目录中，可以在限制范围内设置：
+.. code-block:: bash
+
+ # streaming_interval sets bInterval. Values range from 1..255
+ echo 1 > $FUNCTION/streaming_interval
+
+ # streaming_maxpacket sets wMaxPacketSize. Valid values are 1024/2048/3072
+ echo 3072 > $FUNCTION/streaming_maxpacket
+
+ # streaming_maxburst sets bMaxBurst. Valid values are 1..15
+ echo 1 > $FUNCTION/streaming_maxburst
+
+
+这里传入的值会根据UVC规范限制在有效范围内（其取值依赖于USB连接速度）。
+要了解这些设置如何影响带宽，应查阅UVC规范，
+但经验法则是：增加streaming_maxpacket设置将提高带宽（从而提高最大可能的帧率），
+如果USB连接运行在SuperSpeed模式下，
+增加streaming_maxburst也有相同效果；
+增加streaming_interval则会降低带宽和帧率。
+
+用户空间应用程序
+---------------------
+单独来看，UVC Gadget驱动本身并没有特别有趣的功能。
+它必须与一个用户空间程序配合使用，该程序负责响应UVC控制请求，
+并向驱动创建的V4L2设备填充待排队的缓冲区。
+这些操作的实现方式依赖具体实现，并超出了本文档的范围，
+但可以在以下位置找到参考应用程序：
+https://gitlab.freedesktop.org/camera/uvc-gadget
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 15/25] docs/zh_CN: Add gadget-testing.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (13 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 14/25] docs/zh_CN: Add gadget_uvc.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 16/25] docs/zh_CN: Add iuu_phoenix.rst translation macrofun
` (9 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/gadget-testing.rst into Chinese.
Update the translation through commit 5194439d70ba
("Documentation: treewide: Replace remaining spinics links with lore")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/gadget-testing.rst | 1068 +++++++++++++++++
1 file changed, 1068 insertions(+)
create mode 100644 Documentation/translations/zh_CN/usb/gadget-testing.rst
diff --git a/Documentation/translations/zh_CN/usb/gadget-testing.rst b/Documentation/translations/zh_CN/usb/gadget-testing.rst
new file mode 100644
index 000000000000..a8ee597d0d37
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/gadget-testing.rst
@@ -0,0 +1,1068 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/gadget-testing.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+===========
+Gadget 测试
+===========
+
+本文件总结了关于USB gadget提供的基本功能测试的信息。
+
+.. contents
+
+ 1. ACM功能
+ 2. ECM功能
+ 3. ECM子集功能
+ 4. EEM功能
+ 5. FFS功能
+ 6. HID功能
+ 7. LOOPBACK功能
+ 8. MASS STORAGE功能
+ 9. MIDI功能
+ 10. NCM功能
+ 11. OBEX功能
+ 12. PHONET功能
+ 13. RNDIS功能
+ 14. SERIAL功能
+ 15. SOURCESINK功能
+ 16. UAC1功能 (旧版实现)
+ 17. UAC2功能
+ 18. UVC功能
+ 19. PRINTER功能
+ 20. UAC1功能 (新API)
+ 21. MIDI2功能
+
+
+1. ACM功能
+===============
+
+该功能由usb_f_acm.ko模块提供。
+
+功能专用的configfs接口
+-------------------------
+
+创建功能目录时使用的功能名称为"acm"。
+ACM功能在其功能目录中仅提供一个属性：
+
+ port_num
+
+该属性是只读的。
+系统中最多可以有4个ACM/通用串口/OBEX端口。
+
+
+测试ACM功能
+-----------
+
+在主机上::
+
+ cat > /dev/ttyACM<X>
+
+在设备上::
+
+ cat /dev/ttyGS<Y>
+
+然后反过来
+
+在设备上::
+
+ cat > /dev/ttyGS<Y>
+
+在主机上::
+ cat /dev/ttyACM<X>
+
+2. ECM功能
+===============
+
+该功能由usb_f_ecm.ko模块提供。
+
+功能专用的configfs接口
+------------------------------------
+
+创建功能目录时使用的功能名称为"ecm"。
+ECM功能在其功能目录中提供以下属性：
+=============== ==================================================
+ifname 与此功能实例关联的网络设备接口名称
+qmult 高速和超高速的队列长度乘数
+host_addr 主机端的MAC地址（USB以太网链接）
+dev_addr 设备端的MAC地址（USB以太网链接）
+=============== ==================================================
+
+创建 functions/ecm.<实例名> 后，
+这些属性包含默认值：qmult 为 5，dev_addr 和 host_addr 随机选择。
+如果功能尚未绑定，可以写入 ifname。
+写入必须是接口模式，如 "usb%d"，
+这将使网络核心选择下一个可用的 usbX 接口。默认设置为 "usb%d"。
+
+测试ECM功能
+-----------
+
+配置设备和主机的IP地址。然后：
+
+在设备上::
+
+ ping <host's IP>
+
+在主机上::
+ ping <device's IP>
+
+3. ECM子集功能
+======================
+
+该功能由usb_f_ecm_subset.ko模块提供。
+
+功能专用的configfs接口
+------------------------------------
+
+创建功能目录时使用的功能名称为"geth"。
+ECM子集功能在其功能目录中提供以下属性：
+
+ =============== ==================================================
+ ifname 与此功能实例关联的网络设备接口名称
+ qmult 高速和超高速的队列长度乘数
+ host_addr 主机端的MAC地址（USB以太网链接）
+ dev_addr 设备端的MAC地址（USB以太网链接）
+ =============== ==================================================
+
+创建 functions/ecm.<实例名> 后，
+这些属性包含默认值：qmult 为 5，dev_addr 和 host_addr 随机选择。
+如果功能尚未绑定，可以写入 ifname。
+写入必须是接口模式，如 "usb%d"，
+这将使网络核心选择下一个可用的 usbX 接口。
+默认设置为 "usb%d"。
+
+测试ECM子集功能
+----------------
+
+配置设备和主机的IP地址。然后：
+
+在设备上::
+
+ ping <host's IP>
+
+在主机上::
+ ping <device's IP>
+
+4. EEM功能
+===============
+
+该功能由usb_f_eem.ko模块提供。
+
+功能专用的configfs接口
+------------------------------------
+
+创建功能目录时使用的功能名称为 "eem"。
+EEM 功能在其功能目录中提供以下属性：
+
+ =============== ==================================================
+ ifname 与该功能实例关联的网络设备接口名称
+ qmult 高速和超高速的队列长度乘数
+ host_addr 主机端的MAC地址（USB以太网链接）
+ dev_addr 设备端的MAC地址（USB以太网链接）
+ =============== ==================================================
+
+创建 functions/eem.<实例名> 后，
+这些属性包含默认值：qmult 为 5，dev_addr 和 host_addr 随机选择。
+如果功能尚未绑定，可以写入 ifname。
+写入必须是接口模式，如 "usb%d"，这将使网络核心选择下一个可用的 usbX 接口。
+默认设置为 "usb%d"。
+
+测试EEM功能
+-----------
+
+配置设备和主机的IP地址。然后：
+
+在设备上::
+
+ ping <host's IP>
+
+在主机上::
+ ping <device's IP>
+
+5. FFS功能
+===============
+
+该功能由usb_f_fs.ko模块提供。
+
+功能专用的configfs接口
+------------------------------------
+
+创建功能目录时使用的功能名称为"ffs"。
+功能目录为空且不可修改。
+
+创建目录后，系统中会出现一个新的FunctionFS实例（一个“设备”）。
+一旦可用，用户应遵循FunctionFS的标准使用流程（挂载它，运行实现功能的用户空间进程）。
+通过向usb_gadget/<gadget>/UDC 写入合适的字符串即可启用gadget。
+
+FFS 功能在其功能目录中仅提供一个属性：
+
+ ready
+
+该属性为只读，用于指示功能是否准备好（1）被使用，
+例如用户空间已向 ep0 写入描述符和字符串，从而可以启用 gadget。
+
+测试FFS功能
+-----------
+
+在设备上：启动功能的用户空间守护进程，启用gadget
+
+在主机上：使用设备提供的USB功能
+
+6. HID功能
+===============
+
+该功能由usb_f_hid.ko模块提供。
+
+功能专用的configfs接口
+------------------------------------
+
+创建功能目录时使用的功能名称为"hid"。
+HID功能在其功能目录中提供以下属性：
+=============== ===========================================
+protocol HID 使用的协议
+report_desc 用于 HID 报告的数据，除了通过 /dev/hidg<X> 传递的数据
+report_length HID 报告长度
+subclass HID 使用的子类
+=============== ===========================================
+
+对于键盘，protocol 和 subclass 为 1，report_length 为 8，report_desc 如下::
+
+ $ hd my_report_desc
+ 00000000 05 01 09 06 a1 01 05 07 19 e0 29 e7 15 00 25 01 |..........)...%.|
+ 00000010 75 01 95 08 81 02 95 01 75 08 81 03 95 05 75 01 |u.......u.....u.|
+ 00000020 05 08 19 01 29 05 91 02 95 01 75 03 91 03 95 06 |....).....u.....|
+ 00000030 75 08 15 00 25 65 05 07 19 00 29 65 81 00 c0 |u...%e....)e...|
+ 0000003f
+
+可以通过 echo 将该字节序列存储到属性中::
+
+ $ echo -ne \\x05\\x01\\x09\\x06\\xa1.....
+
+测试 HID 功能
+--------------
+
+设备端：
+
+- 创建 gadget
+- 将 gadget 连接到主机，最好不是用于控制 gadget 的主机
+- 运行一个向 /dev/hidg<N> 写入数据的程序，例如
+ Documentation/usb/gadget_hid.rst 中的一个用户空间程序::
+
+ $ ./hid_gadget_test /dev/hidg0 keyboard
+
+主机端：
+
+- 观察来自 gadget 的按键
+
+7. LOOPBACK 功能
+====================
+
+该功能由usb_f_ss_lb.ko模块提供。
+
+功能专用的 configfs 接口
+------------------------
+
+创建功能目录时使用的功能名称为 "Loopback"。
+LOOPBACK 功能在其功能目录中提供以下属性：
+
+ =============== =======================
+ qlen 回环队列深度
+ bulk_buflen 缓冲区长度
+ =============== =======================
+
+测试 LOOPBACK 功能
+-------------------
+
+设备端：运行 gadget
+
+主机端：test-usb (tools/usb/testusb.c)
+8. MASS STORAGE 功能
+====================
+
+该功能由usb_f_mass_storage.ko模块提供。
+
+功能专用的configfs接口
+------------------------------------
+
+创建功能目录时使用的功能名称为 "mass_storage"。
+MASS STORAGE 功能在其功能目录中提供以下属性：
+
+ =============== ==============================================
+ stall 设置是否允许功能暂停 bulk 端点。
+ 在某些已知无法正常工作的 USB 设备上被禁用。
+ 建议设置为 true。
+ num_buffers 管道缓冲区的数量。有效数字为 2..4。仅当
+ CONFIG_USB_GADGET_DEBUG_FILES 被设置时可用。
+ =============== ==============================================
+
+目录中有默认的 lun.0，对应 SCSI LUN #0。
+
+可以通过 mkdir 添加新的 LUN::
+
+ $ mkdir functions/mass_storage.0/partition.5
+
+LUN 编号不必连续，但默认创建的 lun #0 必须存在。
+最多可指定 8 个 LUN，名称必须遵循 <name>.<number> 格式，
+数字可为 0..8。推荐命名约定为 "lun.<number>"，但非强制。
+
+每个 LUN 目录中包含以下属性文件：
+
+ =============== ==============================================
+ file 指向 LUN 的后备文件的路径。
+ 如果 LUN 未标记为可移动，则为必需。
+ ro 指定对 LUN 的访问应为只读的标志。
+ 如果启用了 CD-ROM 仿真，
+ 或者无法以读写模式打开 "filename"，则隐含为只读。
+ removable 指定 LUN 应被标记为可移动的标志。
+ cdrom 指定 LUN 应被报告为 CD-ROM 的标志。
+ nofua 指定 SCSI WRITE(10,12) 中的 FUA 标志。
+ forced_eject 仅在功能激活时有用。
+ 写入非零字节会强制将后端文件从 LUN 分离，不管主机是否允许
+ =============== ==============================================
+
+测试 MASS STORAGE 功能
+----------------------
+
+设备端：连接 gadget 并启用
+主机端：dmesg，查看 USB 驱动器是否出现（如果系统配置为自动挂载）
+
+9. MIDI 功能
+================
+
+该功能由usb_f_midi.ko模块提供。
+
+功能专用的 configfs 接口
+------------------------------------
+
+创建功能目录时使用的功能名称为 "midi"。
+MIDI 功能在其功能目录中提供以下属性：
+
+ =============== ====================================
+ buflen MIDI 缓冲区长度
+ id USB MIDI 适配器的 ID 字符串
+ in_ports MIDI 输入端口数量
+ index USB MIDI 适配器的索引值
+ out_ports MIDI 输出端口数量
+ qlen USB 读取请求队列长度
+ =============== ====================================
+
+测试 MIDI 功能
+--------------
+有两种情况：从 gadget 播放 mid 到主机，以及从主机播放 mid 到 gadget。
+
+1) 从 gadget 播放 mid 到主机：
+
+主机端::
+
+ $ arecordmidi -l
+ Port Client name Port name
+ 14:0 Midi Through Midi Through Port-0
+ 24:0 MIDI Gadget MIDI Gadget MIDI 1
+ $ arecordmidi -p 24:0 from_gadget.mid
+
+gadget::
+
+ $ aplaymidi -l
+ Port Client name Port name
+ 20:0 f_midi f_midi
+
+ $ aplaymidi -p 20:0 to_host.mid
+
+2) 从主机到gadget播放mid
+
+gadget::
+
+ $ arecordmidi -l
+ Port Client name Port name
+ 20:0 f_midi f_midi
+
+ $ arecordmidi -p 20:0 from_host.mid
+
+主机端::
+
+ $ aplaymidi -l
+ Port Client name Port name
+ 14:0 Midi Through Midi Through Port-0
+ 24:0 MIDI Gadget MIDI Gadget MIDI 1
+
+ $ aplaymidi -p24:0 to_gadget.mid
+
+from_gadget.mid 应与 to_host.mid 听起来完全相同。
+from_host.mid 应与 to_gadget.mid 听起来完全相同。
+MIDI 文件可以通过例如安装了 timidity 的方式播放到扬声器或耳机::
+
+ $ aplaymidi -l
+ Port Client name Port name
+ 14:0 Midi Through Midi Through Port-0
+ 24:0 MIDI Gadget MIDI Gadget MIDI 1
+ 128:0 TiMidity TiMidity port 0
+ 128:1 TiMidity TiMidity port 1
+ 128:2 TiMidity TiMidity port 2
+ 128:3 TiMidity TiMidity port 3
+
+ $ aplaymidi -p 128:0 file.mid
+
+MIDI 端口可以使用 aconnect 工具逻辑连接::::
+
+ $ aconnect 24:0 128:0 # 在主机上尝试
+
+连接后，gadget 端播放的内容可在主机扬声器/耳机中听到。
+
+10. NCM 功能
+============
+
+该功能由 usb_f_ncm.ko 模块提供。
+
+功能专用的 configfs 接口
+--------------------------
+
+创建功能目录时使用的功能名称为 "ncm"。
+NCM 功能在其功能目录中提供以下属性：
+
+ ======================= ==================================================
+ ifname 与该功能实例关联的网络设备接口名称
+ qmult 高速度和超级速度的队列长度乘数
+ host_addr 主机端的MAC地址（USB以太网链接）
+ dev_addr 设备端的MAC地址（USB以太网链接）
+ max_segment_size 点对点连接所需的分段大小。将MTU设置为14字节
+ ======================= ==================================================
+
+创建 functions/ncm.<实例名> 后，
+这些属性包含默认值：qmult 为 5，dev_addr 和 host_addr 随机选择。
+如果功能尚未绑定，可以写入 ifname。
+写入必须是接口模式，如 "usb%d"，
+这将使网络核心选择下一个可用的 usbX 接口。
+默认设置为 "usb%d"。
+
+测试NCM功能
+-----------
+
+配置设备和主机的 IP 地址，然后：
+
+在设备上::
+
+ ping <host's IP>
+
+在主机上::
+ ping <device's IP>
+
+11. OBEX 功能
+=============
+
+该功能由 usb_f_obex.ko 模块提供。
+
+功能专用的 configfs 接口
+--------------------------
+
+创建功能目录时使用的功能名称为 "obex"。
+OBEX 功能在其功能目录中仅提供一个属性：
+
+ port_num
+
+该属性为只读。
+
+系统中最多可以有 4 个 ACM/通用串口/OBEX 端口。
+
+测试 OBEX 功能
+--------------
+
+在设备上::
+
+ seriald -f /dev/ttyGS<Y> -s 1024
+
+在主机上::
+
+ serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
+ -t<out endpoint addr> -r<in endpoint addr>
+
+seriald和serialc是Felipe提供的工具，可在此获取：
+
+ https://github.com/felipebalbi/usb-tools.git master
+
+12. PHONET功能
+==============
+
+该功能由 usb_f_phonet.ko 模块提供。
+
+功能专用的 configfs 接口
+--------------------------
+
+创建功能目录时使用的功能名称为 "phonet"。
+PHONET 功能在其功能目录中仅提供一个属性：
+
+ =============== ==================================================
+ ifname 与该功能实例关联的网络设备接口名称
+ =============== ==================================================
+
+测试 PHONET 功能
+--------------------------
+在没有特定硬件的情况下无法测试 SOCK_STREAM 协议，因此仅测试了 SOCK_DGRAM。
+为使其工作，过去必须应用相应补丁。
+
+这些工具是必需的：
+
+git://git.gitorious.org/meego-cellular/phonet-utils.git
+
+在主机上::
+
+ $ ./phonet -a 0x10 -i usbpn0
+ $ ./pnroute add 0x6c usbpn0
+ $./pnroute add 0x10 usbpn0
+ $ ifconfig usbpn0 up
+
+在设备上::
+
+ $ ./phonet -a 0x6c -i upnlink0
+ $ ./pnroute add 0x10 upnlink0
+ $ ifconfig upnlink0 up
+
+
+在设备上::
+ $ ./pnxmit -a 0x6c -r
+
+在主机上::
+
+ $ ./pnxmit -a 0x10 -s 0x6c
+
+作为结果，一些数据应该从主机发送到设备。
+然后反过来：
+
+在主机上::
+
+ $ ./pnxmit -a 0x10 -r
+
+在设备上::
+ $ ./pnxmit -a 0x6c -s 0x10
+
+13. RNDIS功能
+=============
+
+该功能由usb_f_rndis.ko模块提供。
+
+功能特定的configfs接口
+--------------------------
+
+创建功能目录时使用的功能名为"rndis"。
+RNDIS功能在其功能目录中提供以下属性：
+
+ =============== ==================================================
+ ifname 与该功能实例关联的网络设备接口名称
+ qmult 高速和超高速模式的队列长度倍增器
+ host_addr 主机端的MAC地址（USB以太网链接）
+ dev_addr 设备端的MAC地址（USB以太网链接）
+ =============== ==================================================
+
+创建functions/rndis.<实例名>后，
+它们包含默认值：qmult为5，dev_addr和host_addr随机选择。
+如果功能尚未绑定，可以写入ifname。
+写入必须是类似"usb%d"的接口模式，
+这将使网络核心选择下一个空闲的usbX接口。
+默认值为"usb%d"。
+
+测试 RNDIS 功能
+------------------
+
+配置设备和主机的IP地址。然后：
+
+在设备上::
+
+ ping <host's IP>
+
+在主机上::
+ ping <device's IP>
+
+14. SERIAL功能
+===================
+
+该功能由usb_f_gser.ko模块提供。
+
+功能专用的configfs接口
+------------------------
+
+创建功能目录时使用的功能名为"gser"。
+SERIAL功能在其功能目录中仅提供一个属性：
+
+ port_num
+
+该属性为只读。
+
+系统中最多可以有4个ACM/通用串口/OBEX端口。
+
+测试 SERIAL 功能
+--------------------
+
+在主机上::
+
+ insmod usbserial
+ echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
+
+在主机上::
+
+ cat > /dev/ttyUSB<X>
+
+在设备上::
+ cat /dev/ttyGS<Y>
+
+then the other way round
+
+在目标端::
+
+ cat > /dev/ttyGS<Y>
+
+在主机上::
+ cat /dev/ttyUSB<X>
+
+15. SOURCESINK功能
+=======================
+
+该功能由usb_f_ss_lb.ko模块提供。
+
+功能专用的configfs接口
+------------------------------------
+
+创建功能目录时使用的功能名为"SourceSink"。
+SOURCESINK功能在其功能目录中提供以下属性：
+
+ =============== ==================================
+ pattern 0 (全零), 1 (mod63), 2 (无)
+ isoc_interval 1..16
+ isoc_maxpacket 0 - 1023 (fs), 0 - 1024 (hs/ss)
+ isoc_mult 0..2 (hs/ss only)
+ isoc_maxburst 0..15 (ss only)
+ bulk_buflen 缓冲区长度
+ bulk_qlen 块传输队列深度
+ iso_qlen 等时传输队列深度
+ =============== ==================================
+
+测试SOURCESINK功能
+------------------
+
+设备端：运行gadget
+
+主机端：test-usb (tools/usb/testusb.c)
+
+
+16. UAC1功能 (legacy实现)
+=========================
+
+该功能由usb_f_uac1_legacy.ko模块提供。
+
+功能特定的configfs接口
+------------------------
+
+创建功能目录时使用的功能名为"uac1_legacy"。
+uac1功能在其功能目录中提供以下属性：
+
+ =============== ====================================
+ audio_buf_size audio缓冲区大小
+ fn_cap 捕获pcm设备文件名
+ fn_cntl 控制设备文件名
+ fn_play 播放pcm设备文件名
+ req_buf_size ISO OUT端点请求缓冲区大小
+ req_count ISO OUT端点请求计数
+ =============== ====================================
+
+这些属性具有合理的默认值。
+
+测试UAC1功能
+------------
+
+设备端：运行gadget
+
+主机端::
+
+ aplay -l # should list our USB Audio Gadget
+
+17. UAC2功能
+============
+
+该功能由usb_f_uac2.ko模块提供。
+
+功能特定的configfs接口
+------------------------------------
+
+创建功能目录时使用的功能名为"uac2"。
+uac2功能在其功能目录中提供以下属性：
+================ ====================================================
+c_chmask 捕获通道掩码
+c_srate 捕获采样率列表（逗号分隔）
+c_ssize 捕获样本大小（字节）
+c_sync 捕获同步类型（异步/自适应）
+c_mute_present 捕获静音控制启用
+c_volume_present 捕获音量控制启用
+c_volume_min 捕获音量控制最小值（以1/256 dB为单位）
+c_volume_max 捕获音量控制最大值（以1/256 dB为单位）
+c_volume_res 捕获音量控制分辨率（以1/256 dB为单位）
+c_hs_bint 捕获HS/SS的bInterval（1-4：固定，0：自动）
+fb_max 异步模式下的最大额外带宽
+p_chmask 播放通道掩码
+p_srate 播放采样率列表（逗号分隔）
+p_ssize 播放样本大小（字节）
+p_mute_present 播放静音控制启用
+p_volume_present 播放音量控制启用
+p_volume_min 播放音量控制最小值（以1/256 dB为单位）
+p_volume_max 播放音量控制最大值（以1/256 dB为单位）
+p_volume_res 播放音量控制分辨率（以1/256 dB为单位）
+p_hs_bint 播放HS/SS的bInterval（1-4：固定，0：自动）
+req_number 捕获和播放的预分配请求数
+function_name 接口名称
+if_ctrl_name 拓扑控制名称
+clksrc_in_name 输入时钟名称
+clksrc_out_name 输出时钟名称
+p_it_name 播放输入终端名称
+p_it_ch_name 播放输入第一个通道名称
+p_ot_name 播放输出终端名称
+p_fu_vol_name 播放功能单元名称
+c_it_name 捕获输入终端名称
+c_it_ch_name 捕获输入第一个通道名称
+c_ot_name 捕获输出终端名称
+c_fu_vol_name 捕获功能单元名称
+c_terminal_type 捕获终端类型代码
+p_terminal_type 播放终端类型代码
+================ ====================================================
+
+这些属性具有合理的默认值。
+
+测试UAC2功能
+------------
+
+设备端：运行gadget
+主机端：aplay -l # 应列出我们的USB音频Gadget
+
+此功能不需要真实硬件支持，它仅发送音频流到/从主机。
+若要在设备端实际听到声音，可使用类似如下命令::
+
+ $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
+
+例如::
+
+ $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
+ aplay -D default:CARD=OdroidU3
+
+18. UVC功能
+===========
+
+该功能由usb_f_uvc.ko模块提供。
+
+功能特定的configfs接口
+----------------------
+
+创建功能目录时使用的功能名为"uvc"。
+uvc功能在其功能目录中提供以下属性：
+=================== ================================================
+streaming_interval 数据传输轮询端点的间隔
+streaming_maxburst 超速伴随描述符的bMaxBurst
+streaming_maxpacket 端点可发送或接收的最大包大小（选中此配置时）
+function_name 接口名称
+=================== ================================================
+
+还有"control"和"streaming"子目录，每个子目录包含若干子目录。提供了一些合理的默认值，但用户必须提供：
+
+================== ====================================================
+control header 在control/header创建，并从control/class/fs
+ 和/或control/class/ss链接
+streaming header 在streaming/header创建，并从streaming/class/fs和/或streaming/class/hs和/或
+ streaming/class/ss链接
+format description 在streaming/mjpeg和/或
+ streaming/uncompressed创建
+frame description 在streaming/mjpeg/<format>和/或在
+ streaming/uncompressed/<format>创建
+================== ====================================================
+
+每个frame description包含帧间隔规范，每个规范由若干行间隔值组成。上述规则示例::
+
+ # mkdir functions/uvc.usb0/control/header/h
+ # cd functions/uvc.usb0/control/
+ # ln -s header/h class/fs
+ # ln -s header/h class/ss
+ # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p
+ # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval
+ 666666
+ 1000000
+ 5000000
+ EOF
+ # cd $GADGET_CONFIGFS_ROOT
+ # mkdir functions/uvc.usb0/streaming/header/h
+ # cd functions/uvc.usb0/streaming/header/h
+ # ln -s ../../uncompressed/u
+ # cd ../../class/fs
+ # ln -s ../../header/h
+ # cd ../../class/hs
+ # ln -s ../../header/h
+ # cd ../../class/ss
+ # ln -s ../../header/h
+
+
+测试UVC功能
+-----------
+
+设备端：运行gadget，modprobe vivid::
+
+ # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
+
+其中uvc-gadget程序位于：
+ http://git.ideasonboard.org/uvc-gadget.git
+
+并应用以下补丁：
+
+ https://lore.kernel.org/r/1386675637-18243-1-git-send-email-r.baldyga@samsung.com/
+
+主机端::
+
+ luvcview -f yuv
+
+19. PRINTER功能
+================
+
+该功能由usb_f_printer.ko模块提供。
+
+功能特定的configfs接口
+-------------------------
+
+创建功能目录时使用的功能名为"printer"。
+printer功能在其功能目录中提供以下属性：
+
+========== ===========================================
+pnp_string 传递给主机的即插即用字符串
+q_len 每个端点的请求数
+========== ===========================================
+
+测试PRINTER功能
+------------------
+
+最基本的测试：
+
+设备端：运行gadget::
+
+ # ls -l /devices/virtual/usb_printer_gadget/
+
+应该显示 g_printer<number>。
+
+如果 udev 处于活动状态，则应自动出现 /dev/g_printer<number>。
+
+主机端：
+如果 udev 处于活动状态，则应自动出现例如 /dev/usb/lp0。
+
+主机->设备传输：
+
+设备端：
+
+ # cat /dev/g_printer<number>
+
+主机端：
+ # cat > /dev/usb/lp0
+
+设备->主机传输::
+
+ # cat > /dev/g_printer<number>
+
+主机端::
+ # cat /dev/usb/lp0
+
+更高级的测试可以使用Documentation/usb/gadget_printer.rst中描述的prn_example进行。
+
+
+20. UAC1功能（虚拟ALSA卡，使用u_audio API）
+=============================================
+
+该功能由usb_f_uac1.ko模块提供。
+它将创建一个虚拟ALSA卡，音频流仅仅是
+发送到和接收自它。
+
+功能特定的configfs接口
+-------------------------
+
+创建功能目录时使用的功能名为"uac1"。
+uac1功能在其功能目录中提供以下属性：
+================ ====================================================
+c_chmask 捕获通道掩码
+c_srate 捕获采样率列表（逗号分隔）
+c_ssize 捕获样本大小（字节）
+c_mute_present 捕获静音控制启用
+c_volume_present 捕获音量控制启用
+c_volume_min 捕获音量控制最小值（以1/256 dB为单位）
+c_volume_max 捕获音量控制最大值（以1/256 dB为单位）
+c_volume_res 捕获音量控制分辨率（以1/256 dB为单位）
+p_chmask 播放通道掩码
+p_srate 播放采样率列表（逗号分隔）
+p_ssize 播放样本大小（字节）
+p_mute_present 播放静音控制启用
+p_volume_present 播放音量控制启用
+p_volume_min 播放音量控制最小值（以1/256 dB为单位）
+p_volume_max 播放音量控制最大值（以1/256 dB为单位）
+p_volume_res 播放音量控制分辨率（以1/256 dB为单位）
+req_number 捕获和播放的预分配请求数
+function_name 接口名称
+p_it_name 播放输入端名称
+p_it_ch_name 播放通道名称
+p_ot_name 播放输出端名称
+p_fu_vol_name 播放静音/音量功能单元名称
+c_it_name 捕获输入端名称
+c_it_ch_name 捕获通道名称
+c_ot_name 捕获输出端名称
+c_fu_vol_name 捕获静音/音量功能单元名称
+================ ====================================================
+
+这些属性具有合理的默认值。
+
+测试UAC1功能
+----------------
+
+设备端：运行gadget
+主机端：aplay -l # 应该列出我们的USB音频设备
+
+该功能不需要真实的硬件支持，它只是
+向主机发送和接收音频数据流。为了
+实际上在设备端听到声音，必须在设备端使用类似的命令：
+
+ $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
+
+例如::
+
+ $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
+ aplay -D default:CARD=OdroidU3
+
+
+21. MIDI2功能
+================
+
+该功能由usb_f_midi2.ko模块提供。
+它将创建一个虚拟ALSA卡，其中包含一个UMP rawmidi设备，
+UMP数据包被回环。
+此外，还会创建一个传统的rawmidi设备。
+UMP rawmidi还绑定了ALSA sequencer客户端。
+
+功能特定的configfs接口
+------------------------
+
+创建功能目录时使用的功能名为"midi2"。
+midi2功能在其功能目录中提供以下属性（作为卡顶层信息）：
+
+============= =================================================
+process_ump 布尔标志，处理UMP Stream消息（0或1）
+static_block 静态块的布尔标志（0或1）
+iface_name 可选的接口名称字符串
+============= =================================================
+
+目录包含一个子目录"ep.0"，提供UMP端点（USB MIDI端点对）的属性：
+
+============= =================================================
+protocol_caps MIDI协议能力；
+ 1：MIDI 1.0，2：MIDI 2.0，或3：两者
+protocol 默认MIDI协议（1或2）
+ep_name UMP Endpoint名称字符串
+product_id Product ID字符串
+manufacturer 制造商ID号（24位）
+family 设备系列ID号（16位）
+model 设备型号ID号（16位）
+sw_revision 软件版本号（32位）
+============= =================================================
+
+每个端点子目录包含子目录"block.0"，表示功能块0的信息，其属性为：
+
+================= ===============================================
+name 功能块名称字符串
+direction 该功能块的方向
+ 1：输入，2：输出，或3：双向
+first_group 第一个UMP组号（0-15）
+num_groups 该功能块中的组数（1-16）
+midi1_first_group 第一个UMP组号，用于MIDI 1.0（0-15）
+midi1_num_groups MIDI 1.0的组数（0-16）
+ui_hint 该功能块的UI提示
+ 0：未知，1：接收器，2：发送器，3：两者
+midi_ci_version 支持的MIDI-CI版本号（8位）
+is_midi1 传统MIDI 1.0设备（0-2）
+ 0：MIDI 2.0设备，
+ 1：无限制的MIDI 1.0，或
+ 2：低速的MIDI 1.0
+sysex8_streams 最大SysEx8流数（8位）
+active 功能块活动的布尔标志（0或1）
+================= ===============================================
+
+如需多个功能块，可创建"block.<num>"子目录（1,2,…），且编号必须连续。
+功能块子目录也可动态删除。
+
+同样，如需多个UMP端点，可创建"ep.<num>"子目录，编号必须连续。
+
+若模拟不支持UMP v1.1的旧MIDI 2.0设备，可将`process_ump`设置为0，
+忽略所有UMP v1.1请求。
+
+测试MIDI2功能
+--------------
+
+在设备端：运行gadget，并执行::
+
+ $ cat /proc/asound/cards
+
+将显示包含MIDI2设备的新声卡。
+
+在主机端::
+
+ $ cat /proc/asound/cards
+
+将显示包含MIDI1或MIDI2设备的新声卡，具体取决于USB音频驱动程序的配置。
+
+在两者上，当主机启用ALSA sequencer时，可以找到
+UMP MIDI客户端，如"MIDI 2.0 Gadget"。
+
+由于驱动程序只是简单地回环数据，因此不需要真实设备进行测试。
+
+要测试从gadget到主机的MIDI输入（例如模拟MIDI键盘），可以发送如下的MIDI流。
+
+在设备端::
+
+ $ aconnect -o
+ ....
+ client 20: 'MIDI 2.0 Gadget' [type=kernel,card=1]
+ 0 'MIDI 2.0 '
+ 1 'Group 1 (MIDI 2.0 Gadget I/O)'
+ $ aplaymidi -p 20:1 to_host.mid
+
+在主机端::
+
+ $ aconnect -i
+ ....
+ client 24: 'MIDI 2.0 Gadget' [type=kernel,card=2]
+ 0 'MIDI 2.0 '
+ 1 'Group 1 (MIDI 2.0 Gadget I/O)'
+ $ arecordmidi -p 24:1 from_gadget.mid
+
+如果你有支持UMP的应用程序，也可以使用UMP端口
+发送/接收原始UMP数据包。例如，支持UMP的aseqdump程序
+可以从UMP端口接收数据。在主机端::
+
+ $ aseqdump -u 2 -p 24:1
+ Waiting for data. Press Ctrl+C to end.
+ Source Group Event Ch Data
+ 24:1 Group 0, Program change 0, program 0, Bank select 0:0
+ 24:1 Group 0, Channel pressure 0, value 0x80000000
+
+要测试从主机到gadget的MIDI输出（例如模拟MIDI合成器），则相反。
+
+在设备端::
+
+ $ arecordmidi -p 20:1 from_host.mid
+
+在主机端::
+ $ aplaymidi -p 24:1 to_gadget.mid
+
+在主机端支持对altset 0上的MIDI 1.0的访问，
+并且它在gadget上被翻译为UMP数据包。该功能仅绑定到功能块0。
+
+当前操作模式可通过ALSA控制元素"SND_CTL_IFACE_RAWMIDI"的“Operation Mode”查看。
+例如::
+
+ $ amixer -c1 contents
+ numid=1,iface=RAWMIDI,name='Operation Mode'
+ ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0
+ : values=2
+
+其中0 = 未使用，1 = MIDI 1.0（altset 0），2 = MIDI 2.0（altset 1）。
+上述示例显示当前运行模式为2，即MIDI 2.0。
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 16/25] docs/zh_CN: Add iuu_phoenix.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (14 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 15/25] docs/zh_CN: Add gadget-testing.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 17/25] docs/zh_CN: Add mass-storage.rst translation macrofun
` (8 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/iuu_phoenix.rst into Chinese.
Update the translation through commit ecefae6db042
("docs: usb: rename files to .rst and add them to drivers-api")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/iuu_phoenix.rst | 100 ++++++++++++++++++
1 file changed, 100 insertions(+)
create mode 100644 Documentation/translations/zh_CN/usb/iuu_phoenix.rst
diff --git a/Documentation/translations/zh_CN/usb/iuu_phoenix.rst b/Documentation/translations/zh_CN/usb/iuu_phoenix.rst
new file mode 100644
index 000000000000..f86eef3f16d6
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/iuu_phoenix.rst
@@ -0,0 +1,100 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/iuu_phoenix.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+====================================
+Infinity Usb Unlimited 说明文档
+====================================
+
+大家好，
+
+该模块提供一个串行接口，用于在Phoenix模式下使用你的IUU设备。
+加载此模块后，会生成一个ttyUSB[0-x]接口。
+你需要使用自己喜欢的应用程序来控制IUU设备。
+
+该驱动仍处于测试阶段，因此可能存在漏洞，你的系统可能会冻结。
+据我所知，我自己使用时从未遇到问题，但我并不是专家，
+因此如果你的系统不稳定，请不要责怪我。
+
+你可以连接多个IUU设备，
+每个设备都有自己的设备文件（/dev/ttyUSB0、/dev/ttyUSB1……）。
+
+
+
+如何调节读卡器速度？
+======================
+
+可以在加载模块时使用一些参数。
+要使用参数，请先卸载已加载的模块，然后使用以下命令::
+
+ modprobe iuu_phoenix param=value
+
+如果是预编译模块，可以使用::
+
+ insmod iuu_phoenix param=value
+
+示例：::
+
+ modprobe iuu_phoenix clockmode=3
+
+ 参数包括：
+
+clockmode:
+ 1=3Mhz579,2=3Mhz680,3=6Mhz (int)
+boost:
+ 超频提升百分比 100 到 500 (int)
+cdmode:
+ 卡检测模式
+ 0=none, 1=CD, 2=!CD, 3=DSR, 4=!DSR, 5=CTS, 6=!CTS, 7=RING, 8=!RING (int)
+xmas:
+ 是否启用xmas彩色 (bool)
+debug:
+ 是否启用调试 (bool)
+
+- clockmode 提供三种不同的基础设置，通常由不同软件采用：
+
+ 1. 3Mhz579
+ 2. 3Mhz680
+ 3. 6Mhz
+
+- boost 提供了一种超频读卡器的方式（我的最爱 :-)）。
+ 例如，要比单纯的clockmode=3获得更高性能，可以使用：
+
+ modprobe boost=195
+
+ 这会将读卡器基频设置为3Mhz579，但提升195%！
+ 实际频率将为6979050 Hz（6Mhz979），速度比单纯的clockmode=3提高约10-20%！
+
+
+- cdmode 可设置用于通知用户空间（ioctl响应）卡是否存在的信号。有八种信号可选。
+
+- xmas 完全无用，只是为了你的视觉效果。这是我的一个朋友，
+ 他很难过拥有像iuu这样好的设备却看不到所有可用的颜色范围。
+ 所以我添加了这个选项，允许他看到很多颜色（每次活动都会随机改变颜色
+ 和频率）
+
+- debug 会生成大量调试信息。
+
+
+最后说明
+========
+
+无需担心串口设置，串口模拟是抽象的，
+因此任何速度或奇偶校验设置都可以工作（不会改变任何行为）。
+以后我可能会利用这些设置来计算boost，但这个功能真的有必要吗？
+
+自动检测功能使用串口CD。如果软件不支持该功能，请在软件中禁用检测机制。
+
+祝你使用愉快！
+
+ Alain Degreffe
+
+ eczema(at)ecze.com
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 17/25] docs/zh_CN: Add mass-storage.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (15 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 16/25] docs/zh_CN: Add iuu_phoenix.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 18/25] docs/zh_CN: Add misc_usbsevseg.rst translation macrofun
` (7 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
docs/zh_CN: Add mass-storage.rst translation
Update the translation through commit e4157519ad46
("Documentation: usb: correct spelling")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/mass-storage.rst | 196 ++++++++++++++++++
1 file changed, 196 insertions(+)
create mode 100644 Documentation/translations/zh_CN/usb/mass-storage.rst
diff --git a/Documentation/translations/zh_CN/usb/mass-storage.rst b/Documentation/translations/zh_CN/usb/mass-storage.rst
new file mode 100644
index 000000000000..2e258ff27af1
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/mass-storage.rst
@@ -0,0 +1,196 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/mass-storage.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+=========================
+大容量存储Gadget (MSG)
+=========================
+
+概述
+====
+
+ 大容量存储Gadget（或MSG）作为USB大容量存储设备，对主机表现为磁盘或CD-ROM驱动器。
+ 它支持多个逻辑单元(LUN)。
+ 每个LUN的后端存储由普通文件或块设备提供，
+ 可以限制为只读，
+ 并且Gadget可以指示其可移动和/或为CD-ROM（后者意味着只读访问）。
+
+ 它的需求较低；
+ 仅需一个bulk-in和一个bulk-out端点。
+ 内存需求为两个16K缓冲区。
+ 支持全速、高速和超高速操作。
+
+ 注意，该驱动程序在某种程度上具有非移植性，因为它假设
+ 一个内存/DMA缓冲区将可用于bulk-in和bulk-out
+ 端点。对于大多数设备控制器来说，这不是问题，但
+ 可能存在一些硬件限制，一个缓冲区不能
+ 被多个端点使用。
+
+ 本文档描述了如何从用户态使用该Gadget，
+ 它与大容量存储功能(MSF)及使用它的不同Gadget的关系，
+ 以及与文件存储Gadget(FSG，
+ 已不再包含于Linux)的区别。
+ 仅会简要说明如何在复合Gadget中使用MSF。
+
+模块参数
+========
+
+ 大容量存储Gadget接受以下大容量存储特定模块参数：
+
+ - file=filename[,filename...]
+
+ 此参数列出用于每个逻辑单元后端存储的文件或块设备路径。
+ 最多可设置FSG_MAX_LUNS(8)个LUN。
+ 如果指定更多文件，将被静默忽略。另见“luns”参数。
+
+ 注意 如果使用文件作为后端存储，则该文件不得被其他进程修改。
+ 这是因为主机假定数据不会在其不知情的情况下改变。
+ 可以读取，但如果逻辑单元可写，由于主机端缓冲，内容未定义。
+
+ 逻辑单元大小将向下舍入为完整逻辑块。
+ 逻辑块大小为：模拟CD-ROM的LUN为2048字节，
+ 后端文件为块设备则为设备块大小，否则为512字节。
+
+ - removable=b[,b...]
+
+ 指定每个逻辑单元是否可移动。b为“y”“Y”“1”为真，“n”“N”“0”为假。
+
+ 如果逻辑单元可移动，Gadget将接受“弹出”SCSI请求(Start/Stop Unit)。
+ 发送时，将关闭后端文件以模拟弹出，
+ 在用户态为设备指定新后端文件之前，该逻辑单元不可被主机挂载。
+
+ 如果逻辑单元不可移动(默认)，必须在加载模块时通过“file”参数指定后端文件。
+ 内置模块同理，无例外。
+
+ 默认值为false，但历史上曾为true。
+ 现改为false以更好匹配FSG，并且更合理。
+ 为了兼容旧内核，最好显式指定默认值。
+ 如果依赖旧默认，现在需要显式指定“n”。
+
+ 注意，“removable”表示逻辑单元的介质可被弹出或移除（如CD-ROM或读卡器），
+ 不表示整个Gadget可从主机拔出；后者正确术语为“hot-unpluggable”。
+
+ - cdrom=b[,b...]
+
+ 指定每个逻辑单元是否模拟CD-ROM，默认false。
+
+ - ro=b[,b...]
+
+ 指定每个逻辑单元是否只读。防止主机修改后端文件。
+
+ 如果标志为false但后端文件无法以读写模式打开，Gadget仍会回退为只读模式。
+
+ 非CD-ROM逻辑单元默认false；模拟CD-ROM的逻辑单元强制为true。
+
+ - nofua=b[,b...]
+
+ 指定是否在给定逻辑单元的SCSI Write10和Write12命令中忽略FUA标志。
+
+ Windows默认在“优化移除模式”挂载可移动存储。
+ 所有写入为同步写，
+ 通过在SCSI Write(10,12)命令中设置FUA(Force Unit Access)位实现。
+ 这会强制每次写入等待数据实际写出，阻止块层聚合I/O请求，显著降低性能。
+
+ 注意，如果设备从USB供电且用户未卸载就拔出设备，数据可能丢失。
+
+ 默认值为false。
+
+ - luns=N
+
+ 指定Gadget拥有的逻辑单元数，受FSG_MAX_LUNS(8)限制，超出值将被截断。
+
+ 如果提供此参数，且“file”参数指定的文件数大于luns值，多余文件将被忽略。
+
+ 若未指定，则逻辑单元数根据“file”参数指定的文件数推断；
+ 若file参数也缺失，则假定为1。
+
+ - stall=b
+
+ 指定是否允许Gadget停止bulk端点。
+ 默认值根据USB设备控制器类型确定，但通常为true。
+
+ 除上述参数外，Gadget还接受复合框架定义的参数（所有复合Gadget通用，列出如下）：
+
+ - idVendor -- USB Vendor ID (16 bit integer)
+ - idProduct -- USB Product ID (16 bit integer)
+ - bcdDevice -- USB Device version (BCD) (16 bit integer)
+ - iManufacturer -- USB Manufacturer string (string)
+ - iProduct -- USB Product string (string)
+ - iSerialNumber -- SerialNumber string (string)
+
+sysfs entries
+=============
+
+ 对于每个逻辑单元，Gadget在sysfs层级创建目录。目录内创建以下文件：
+
+ - file
+
+ 读取返回逻辑单元的后端文件路径。
+ 若无后端文件(仅在逻辑单元可移动时可能)，内容为空。
+
+ 写入可更改逻辑单元的后端文件。
+ 即使逻辑单元不可移动，也可执行此操作（主机可能认为奇怪）。
+ 若主机通过Prevent-Allow Medium Removal SCSI命令禁止介质移除，可能失败。
+
+ - ro
+
+ 反映逻辑单元的ro标志状态。随时可读，若逻辑单元无后端文件打开，也可写入。
+
+ - nofua
+
+ 反映逻辑单元nofua标志状态，可读可写。
+
+ - forced_eject
+
+写入后，将强制从LUN分离后端文件，无论主机是否允许。
+写入内容无关，写入任意非零字节均会导致弹出。
+不可读取。
+
+ 其他参数值可从/sys/module/g_mass_storage/parameters/* 读取。
+
+使用大容量存储功能的其他Gadget设备
+========================================
+
+ 大容量存储Gadget使用大容量存储功能(MSF)处理存储协议。
+ 作为复合功能，MSF也可被其他Gadget使用（如g_multi和acm_ms）。
+
+ 前述信息对使用MSF的其他Gadget有效，但可能不支持大容量存储相关模块参数，
+ 或参数带前缀。是否适用需查看Gadget文档或源代码。
+
+ 想了解如何在Gadget中包含MSF，
+ 可参考mass_storage.c、acm_ms.c和multi.c（按复杂度排序）。
+
+与文件存储 Gadget 的关系
+========================
+
+ 大容量存储功能(Mass Storage Function)，从而大容量存储Gadget(MSG)，
+ 是基于文件存储Gadget(File Storage Gadget)的。
+ 两者的区别在于，MSG是复合Gadget（即使用复合框架），而文件存储Gadget是传统Gadget。
+ 从用户态的角度来看，这一区别并不重要，
+ 但从内核开发者的角度来看，这意味着：
+ (i) MSG不重复处理基本USB协议命令所需的代码
+ (ii) MSF可以在任何其他复合Gadget中使用。
+
+ 因此，文件存储Gadget已在Linux 3.8中被移除。
+ 所有用户都需要迁移到大容量存储Gadget。
+ 两者从外部行为来看大体相同，唯一的区别如下：
+
+ 1. 在FSG中，“removable”和“cdrom”模块参数会对所有逻辑单元统一设置标志，
+ 而在MSG中，它们接受每个逻辑单元的y/n值列表。
+ 如果只使用单个逻辑单元，这无关紧要；
+ 但如果有多个逻辑单元，y/n值需要为每个逻辑单元重复指定。
+ 2. FSG的“serial”“vendor”“product”和“release”模块参数，
+ 在MSG中由复合层的参数分别处理，
+ 对应名称为：“iSerialNumber”“idVendor”“idProduct”和“bcdDevice”。
+
+ 3. MSG不支持FSG的测试模式，
+ 因此FSG的“transport”“protocol”和“buflen”模块参数不被支持。
+ MSG始终使用SCSI协议，采用仅bulk传输模式和16 KiB缓冲区。
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 18/25] docs/zh_CN: Add misc_usbsevseg.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (16 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 17/25] docs/zh_CN: Add mass-storage.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 19/25] docs/zh_CN: Add mtouchusb.rst translation macrofun
` (6 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/misc_usbsevseg.rst into Chinese.
Update the translation through commit ecefae6db042
("docs: usb: rename files to .rst and add them to drivers-api")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/misc_usbsevseg.rst | 61 +++++++++++++++++++
1 file changed, 61 insertions(+)
create mode 100644 Documentation/translations/zh_CN/usb/misc_usbsevseg.rst
diff --git a/Documentation/translations/zh_CN/usb/misc_usbsevseg.rst b/Documentation/translations/zh_CN/usb/misc_usbsevseg.rst
new file mode 100644
index 000000000000..4920e690a6ed
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/misc_usbsevseg.rst
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/misc_usbsevseg.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+=================
+USB 7段数字显示器
+=================
+
+由Delcom Engineering制造
+
+设备信息
+--------
+USB VENDOR_ID 0x0fc5
+USB PRODUCT_ID 0x1227
+6字符和8字符显示器均有PRODUCT_ID，
+根据Delcom Engineering的说法，无法通过设备查询信息来区分它们。
+
+设备模式
+--------
+默认情况下，驱动假设显示器只有6个字符
+6个字符的模式是：
+
+ MSB 0x06; LSB 0x3f
+
+对于8字符显示器：
+ MSB 0x08; LSB 0xff
+
+该设备可以接受“文本”，无论是原始、十六进制还是ASCII文本模式。
+原始模式手动控制每个段，
+十六进制模式期望每个字符的值在0-15之间，
+ascii模式期望每个字符的值在'0'-'9'和'A'-'F'之间。
+默认是ascii。
+
+设备操作
+--------
+1. 打开设备：
+ echo 1 > /sys/bus/usb/.../powered
+2. 设置设备模式：
+ echo $mode_msb > /sys/bus/usb/.../mode_msb
+ echo $mode_lsb > /sys/bus/usb/.../mode_lsb
+3. 设置文本模式：
+ echo $textmode > /sys/bus/usb/.../textmode
+4. 设置文本（例如）：
+ echo "123ABC" > /sys/bus/usb/.../text (ascii)
+ echo "A1B2" > /sys/bus/usb/.../text (ascii)
+ echo -ne "\x01\x02\x03" > /sys/bus/usb/.../text (hex)
+5. 设置小数点位置。
+ 该设备有6个或8个小数点。
+ 要设置第n个小数点，请计算10的n次方
+ 并将其写入/sys/bus/usb/.../decimals
+ 要设置多个小数点，请将每个幂相加。
+ 例如，要设置第0和第3个小数点
+ echo 1001 > /sys/bus/usb/.../decimals
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 19/25] docs/zh_CN: Add mtouchusb.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (17 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 18/25] docs/zh_CN: Add misc_usbsevseg.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 20/25] docs/zh_CN: Add ohci.rst translation macrofun
` (5 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/mtouchusb.rst into Chinese.
Update the translation through commit 9e255e2b9afe
("Documentation: drop optional BOMs")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/mtouchusb.rst | 89 +++++++++++++++++++
1 file changed, 89 insertions(+)
create mode 100644 Documentation/translations/zh_CN/usb/mtouchusb.rst
diff --git a/Documentation/translations/zh_CN/usb/mtouchusb.rst b/Documentation/translations/zh_CN/usb/mtouchusb.rst
new file mode 100644
index 000000000000..11f847a6b428
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/mtouchusb.rst
@@ -0,0 +1,89 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/mtouchusb.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+=================
+mtouchusb驱动
+=================
+
+变更记录
+=============
+
+- 0.3 - 基于原始触摸屏驱动的scanner和INSTALL创建
+ （来源：freecode http://freecode.com/projects/3mtouchscreendriver）
+
+- 针对 linux-2.4.18 进行了修改，然后是 2.4.19
+
+- 使用 Linux Input 在 2.6.3 下完全重写
+ 不幸的是，目前不支持校准功能
+
+- 1.4 - 为支持 EXII 5000UC 进行了多项修改并进行清理工作
+ 将复位方式从标准 USB 设备复位改为厂商复位
+ 将发送到主机的数据从补偿坐标改为原始坐标
+ 删除了 vendor/product 模块参数
+ 使用 EXII-5010UC 进行了多次成功测试
+
+所支持的硬件
+==============
+
+::
+
+ 所有VendorID是0x0596，ProductID是0x0001的控制器
+
+
+ 控制器描述 零件编号
+ ------------------------------------------------------
+
+ USB Capacitive - 珍珠外壳 14-205 (已停产)
+ USB Capacitive - 黑色外壳 14-124 (已停产)
+ USB Capacitive - 无外壳 14-206 (已停产)
+
+ USB Capacitive - 珍珠外壳 EXII-5010UC
+ USB Capacitive - 黑色外壳 EXII-5030UC
+ USB Capacitive - 无外壳 EXII-5050UC
+
+驱动说明
+========
+
+安装很简单，只需将Linux Input、Linux USB和驱动添加到内核即可。
+该驱动也可以选择构建为模块。
+
+该驱动似乎是可能存在的两个Linux USB Input触摸屏驱动之一。
+虽然3M提供了一个仅二进制可下载的驱动，但我坚持更新此驱动，
+因为我希望在嵌入式应用中使用触摸屏，例如使用QTEmbedded、DirectFB等。
+因此，我认为逻辑选择是使用Linux Input。
+
+目前无法通过此驱动校准设备。即使设备可以校准，驱动也会从控制器获取原始坐标数据。
+这意味着校准必须在用户态完成。
+
+控制器的屏幕分辨率现在为X和Y均为0到16384，用于报告原始触摸数据。
+对于旧的和新的电容式USB控制器均相同。
+
+也许将来会在evdev中放置一个抽象函数，
+以便可以从用户态请求通用功能，如校准、复位和厂商信息（驱动程序将处理厂商特定任务）。
+
+待办事项
+========
+
+一旦可用，再次实现control urb以处理与设备的请求，例如校准等。
+
+免责声明
+========
+
+我不是MicroTouch/3M员工，也从未是。
+3M不支持此驱动！如果只想使用X中支持的触摸驱动，请访问：
+
+http://www.3m.com/3MTouchSystems/
+
+感谢
+====
+
+非常感谢3M Touch Systems提供的EXII-5010UC控制器进行测试！
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 20/25] docs/zh_CN: Add ohci.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (18 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 19/25] docs/zh_CN: Add mtouchusb.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 21/25] docs/zh_CN: Add raw-gadget.rst translation macrofun
` (4 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/ohci.rst into Chinese.
Update the translation through commit ecefae6db042
("docs: usb: rename files to .rst and add them to drivers-api")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
Documentation/translations/zh_CN/usb/ohci.rst | 46 +++++++++++++++++++
1 file changed, 46 insertions(+)
create mode 100644 Documentation/translations/zh_CN/usb/ohci.rst
diff --git a/Documentation/translations/zh_CN/usb/ohci.rst b/Documentation/translations/zh_CN/usb/ohci.rst
new file mode 100644
index 000000000000..62bd8070a25e
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/ohci.rst
@@ -0,0 +1,46 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/ohci.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+====
+OHCI
+====
+
+2002年08月23日
+
+“ohci-hcd”驱动是一个USB主控制器驱动（HCD），
+源自2.4内核系列中的“usb-ohci”驱动。
+“usb-ohci”代码主要由Roman Weissgaerber weissg@vienna.at
+编写，但也有许多其他人的贡献（详见其版权/许可头）。
+
+它支持“开放主机控制器接口”（OHCI），
+该接口标准化了用于与USB 1.1主控制器通信的硬件寄存器协议。
+与早期的英特尔“通用主机控制器接口”（UHCI）相比，它将更多智能推入硬件。
+除Intel和VIA之外的USB 1.1控制器通常使用OHCI。
+
+自2.4内核以来的改进包括：
+
+ - 提高了稳定性；修复了漏洞；降低了开销
+ - 支持更新和简化的usbcore API
+ - 中断传输可以更大，并且可以排队
+ - 通过使用上层的"hcd"框架，代码更少
+ - 支持某些非PCI实现的OHCI
+ - ... 更多
+
+“ohci-hcd”驱动处理所有类型的USB 1.1传输。
+所有类型的传输都可以排队。
+这在“usb-ohci”中也适用，但中断传输除外。
+以前，如果使用一个帧周期，会因IRQ处理的开销而有数据丢失的风险。
+当中断传输排队时，
+可以通过确保硬件在操作系统处理相关IRQ时始终有传输任务来最小化这些风险。
+
+- David Brownell
+ <dbrownell@users.sourceforge.net>
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 21/25] docs/zh_CN: Add raw-gadget.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (19 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 20/25] docs/zh_CN: Add ohci.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 22/25] docs/zh_CN: Add usbmon.rst translation macrofun
` (3 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/raw-gadget.rst into Chinese.
Update the translation through commit 68a1317412e1
("usb: raw-gadget: update documentation")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/raw-gadget.rst | 91 +++++++++++++++++++
1 file changed, 91 insertions(+)
create mode 100644 Documentation/translations/zh_CN/usb/raw-gadget.rst
diff --git a/Documentation/translations/zh_CN/usb/raw-gadget.rst b/Documentation/translations/zh_CN/usb/raw-gadget.rst
new file mode 100644
index 000000000000..33ef5e10c27f
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/raw-gadget.rst
@@ -0,0 +1,91 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/raw-gadget.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+==============
+USB Raw Gadget
+==============
+
+USB Raw Gadget 是一个gadget驱动，允许用户态对gadget的通信过程进行低级控制。
+
+与其他gadget驱动一样，Raw Gadget通过USB gadget API实现USB设备。
+与大多数gadget驱动不同，Raw Gadget本身不实现任何具体USB功能，
+而是由用户态来实现这些功能。
+
+Raw Gadget目前严格用于调试，不应在生产环境中使用，可改用GadgetFS。
+
+通过配置选项 CONFIG_USB_RAW_GADGET 启用。
+
+和GadgetFS对比
+~~~~~~~~~~~~~~~~~~
+
+RawGadget与GadgetFS类似，但为用户态提供了更直接访问USBgadget层的能力。
+主要区别如下：
+
+1. RawGadget会将每一个USB请求都传递到用户态以获取响应，
+ 而GadgetFS会根据所提供的描述符对部分USB请求进行内部响应。
+ 注意，UDC驱动可能会自行响应某些请求并且永远不会将它们转发到gadget层。
+
+2. RawGadget允许对USB请求提供任意数据作为响应，
+ 而GadgetFS会对所提供的USB描述符执行合理性检查。
+ 这使得RawGadget适用于通过向USB请求提供畸形数据来进行模糊测试。
+
+3. RawGadget提供选择要绑定的UDC设备/驱动的方式，
+ 而GadgetFS当前会绑定到第一个可用的UDC。
+ 这允许多个RawGadget实例绑定到不同的UDC。
+
+4. RawGadget明确暴露关于端点地址和能力的信息。
+ 这允许用户编写与UDC无关的gadgets。
+
+5. RawGadget使用ioctl作为接口，而不是基于文件系统的接口。
+
+用户空间接口
+~~~~~~~~~~~~~~~~~~~
+
+用户可以通过打开``/dev/raw-gadget``并发起ioctl调用来与RawGadget交互；
+详细内容请参考include/uapi/linux/usb/raw_gadget.h中的注释。
+多个RawGadget实例（绑定到不同的UDC）可以同时使用。
+
+RawGadget的典型使用场景：
+
+1. 通过打开``/dev/raw-gadget``创建一个RawGadget实例。
+2. 通过``USB_RAW_IOCTL_INIT``初始化该实例。
+3. 使用``USB_RAW_IOCTL_RUN``启动该实例。
+4. 在循环中发出``USB_RAW_IOCTL_EVENT_FETCH``以接收来自RawGadget的事件，
+ 并根据需要实现的USB gadget类型对这些事件作出反应。
+
+注意，一些UDC驱动为端点分配了固定地址，因此不能在描述符中使用任意端点地址。
+然而，RawGadget提供了一种与UDC无关的方式来编写USBgadgets。
+一旦通过``USB_RAW_EVENT_CONNECT``（
+通过``USB_RAW_IOCTL_EVENT_FETCH``获取）收到连接事件，
+可以使用``USB_RAW_IOCTL_EPS_INFO``获取UDC驱动所具备的端点信息。
+在此基础上，用户态必须为gadget选择UDC的端点，并在端点描述符中相应地分配地址。
+
+RawGadget的使用示例和测试套件：
+
+https://github.com/xairy/raw-gadget
+
+内部实现细节
+~~~~~~~~~~~~~~~
+
+每一次RawGadget的端点读/写ioctl都会提交一个USB请求并等待其完成。
+这样设计是为了在覆盖率引导的模糊测试中，让一次系统调用完整处理一个USB请求。
+此特性必须在实现中保持。
+
+潜在的未来改进
+~~~~~~~~~~~~~~~~
+
+- 支持``O_NONBLOCK`` I/O。这将是另一种工作模式，
+ 在该模式下RawGadget不会等待每个USB请求的完成。
+
+- 支持USB 3特性（启用端点时接受SS端点伴随描述符；允许为批量传输提供``stream_id``）。
+
+- 支持ISO传输特性（为已完成的请求暴露``frame_number``）。
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 22/25] docs/zh_CN: Add usbmon.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (20 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 21/25] docs/zh_CN: Add raw-gadget.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 23/25] docs/zh_CN: Add usb-serial.rst translation macrofun
` (2 subsequent siblings)
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
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: macrofun <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/usbmon.rst | 379 ++++++++++++++++++
1 file changed, 379 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..a3ae68373e12
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/usbmon.rst
@@ -0,0 +1,379 @@
+.. 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] 32+ messages in thread* [PATCH v2 23/25] docs/zh_CN: Add usb-serial.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (21 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 22/25] docs/zh_CN: Add usbmon.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 24/25] docs/zh_CN: Add usb-help.rst translation macrofun
2025-11-23 11:56 ` [PATCH v2 25/25] docs/zh_CN: Add CREDITS.rst translation macrofun
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/usb-serial.rst into Chinese.
Update the translation through commit 9e255e2b9afe
("Documentation: drop optional BOMs")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/usb-serial.rst | 451 ++++++++++++++++++
1 file changed, 451 insertions(+)
create mode 100644 Documentation/translations/zh_CN/usb/usb-serial.rst
diff --git a/Documentation/translations/zh_CN/usb/usb-serial.rst b/Documentation/translations/zh_CN/usb/usb-serial.rst
new file mode 100644
index 000000000000..480032530e11
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/usb-serial.rst
@@ -0,0 +1,451 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/usb-serial.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+==========
+USB 串口
+==========
+
+简介
+====
+
+USB 串口驱动目前支持多种 USB 转串口转换器产品，以及一些通过用户空间串口接口与设备通信的设备。
+
+具体设备的信息请参阅下文各产品部分。
+
+
+配置
+====
+
+ 当前驱动可以同时处理最多 256 个不同的串口接口。
+
+ 驱动使用的主设备号是 188，因此要使用该驱动，需要创建如下设备节点：::
+
+ mknod /dev/ttyUSB0 c 188 0
+ mknod /dev/ttyUSB1 c 188 1
+ mknod /dev/ttyUSB2 c 188 2
+ mknod /dev/ttyUSB3 c 188 3
+ .
+ .
+ .
+ mknod /dev/ttyUSB254 c 188 254
+ mknod /dev/ttyUSB255 c 188 255
+
+ 当设备连接并被驱动识别后，驱动会打印到系统日志，显示设备绑定到了哪个节点。
+
+
+支持的具体设备
+===================
+
+
+ConnectTech WhiteHEAT 四口转换器
+-------------------------------------------
+
+ ConnectTech 提供了该设备的详细信息和测试用设备。
+
+ 该驱动由 Connect Tech Inc. 官方支持：
+ http://www.connecttech.com
+
+ 如有问题，请联系 Connect Tech 技术支持：support@connecttech.com
+
+
+HandSpring Visor, Palm USB, 和 Clié USB驱动
+-------------------------------------------
+
+ 该驱动适用于所有 HandSpring USB、Palm USB 及 Sony Clié USB 设备。
+
+ 设备尝试连接主机时，才会显示为有效 USB 设备。
+ 此时设备会被正确枚举、分配端口，然后通信才可能进行。
+ 设备移除或取消连接时，驱动会正确清理。
+
+ 注意：
+ 要与设备通信，必须在尝试与设备交互前按下同步按钮。
+ 这与现有的 pilot-xfer 等文档描述不同，但这是由于硬件原因的唯一方法。
+
+ 设备连接后，如果系统中没有其他 USB-串口设备）进行通信，
+ 通常通过第二个端口（通常是 /dev/ttyUSB1，。
+ 系统日志会显示用于 HotSync 的端口，
+ “Generic”端口可用于其他通信，例如 PPP 链接。
+
+ 对于部分 Sony Clié 设备，必须使用 /dev/ttyUSB0，
+ 尤其是 OS 版本 3.5 或升级过的设备。
+ 系统日志会显示正确端口。
+
+ 如果按下同步按钮后系统日志没有输出，尝试先热复位，再冷复位。部分设备必须这样才能正常与 USB 通信。
+
+ 未编译进内核的设备可以通过模块参数指定，例如：
+ modprobe visor vendor=0x54c product=0x66
+
+ 更多信息及邮件列表请访问：http://sourceforge.net/projects/usbvisor/
+
+ 如有问题，请联系 Greg Kroah-Hartman：greg@kroah.com
+
+PocketPC PDA驱动
+----------------
+
+ 该驱动通过 USB 数据线或底座，用于连接 Compaq iPAQ、HP Jornada、Casio EM500
+ 等运行 Windows CE 3.0 或 PocketPC 2002 的 PDA。
+
+ 支持 ActiveSync 的大多数设备开箱即用。
+ 对于其他设备，可通过模块参数指定产品和厂商 ID，
+ 例如： modprobe ipaq vendor=0x3f0 product=0x1125
+
+ 驱动提供串口接口（通常为 /dev/ttyUSB0），可通过 PPP 建立 TCP/IP 链接与 PDA 通信，
+ 进行文件传输、备份、邮件下载等。USB 的优势是速度快，可达 73~113 kB/s。
+
+ 使用 USB 连接还需要其他组件，详情见：http://synce.sourceforge.net
+
+ 连接后，可在 PDA 上使用 ftpView、Pocket Outlook，
+ 在 Linux 上使用 xcerdisp、synce 工具。
+
+ 使用 Pocket IE 可参考：http://www.tekguru.co.uk/EM500/usbtonet.htm，Linux
+ 可直接转发数据包，无需代理。
+ iPAQ 用户需在菜单关闭自动同步，然后启动 usbdial 建立连接。
+
+ 若遇问题，可加载 usbserial 和 ipaq 模块并开启调试参数 debug=1，
+ 检查系统日志；也可尝试软复位 PDA 后再连接。
+
+ 其他功能取决于 PDA。部分设备可进入 bootloader 模式，
+ 通过 /dev/ttyUSB0 终端进行 USB Reflash。
+ 此方法未测试，风险自负。
+
+ 问题请联系 Ganesh Varadarajan：ganesh@veritas.com
+
+
+Keyspan PDA串口适配器
+------------------------------
+
+ 单端口 DB-9 串口适配器，多用于 iMac PDA，固件为自制。
+ 也适用于 Xircom/Entrega 单口适配器。
+
+ 当前状态：
+
+ 支持功能：
+ - 基本 I/O（可用 'cu' 测试）
+ - 串口阻塞写
+ - 波特率切换（最高 115200）
+ - 调制解调器控制引脚操作（TIOCM{GET,SET,BIS,BIC}）
+
+发送 break（时长可能不准确）
+
+ 不支持功能：
+ - 设备字符串（内核日志中记录）带有尾随的二进制垃圾
+ - 设备 ID 不正确，可能与其他 Keyspan 产品冲突
+ - 切换波特率时应刷新发送/接收缓冲区以避免字符混乱
+
+ 重要待办事项：
+ - 奇偶校验，7 位与 8 位字符，1 或 2 个停止位
+ - 硬件流控制
+ - 并非所有标准 USB 描述符都被处理：
+ Get_Status, Set_Feature, O_NONBLOCK, select()
+
+ 如有问题，请联系 Brian Warner：warner@lothar.com
+
+
+Keyspan USA-系列串口适配器
+-------------------------------------------
+
+ 单、双及四端口适配器，使用 Keyspan 官方固件。
+
+ 支持设备：USA-18X、USA-28X、USA-19、USA-19W、USA-49W，测试良好。USA-28 尚未支持。
+
+ 更多信息： http://www.carnationsoftware.com/carnation/Keyspan.html
+
+ 问题请联系 Hugh Blemings：hugh@misc.nu
+
+
+FTDI 单口串口驱动
+-----------------------------------------
+
+ 支持设备：TripNav TN-200 USB GPS、Navis Engineering CH-4711 USB GPS
+
+ 问题请联系 Bill Ryder。
+
+
+ZyXEL omni.net lcd plus ISDN TA
+-----------------------------------------------
+
+ 请将使用情况和问题报告给 azummo@towertech.it
+
+
+Cypress M8 CY4601 系列串口驱动
+-----------------------------------------
+
+ 该驱动在很大程度上由 Neil “koyama” Whelchel 开发。
+ 自之前的版本以来，该驱动已得到改进，以支持动态串口设置并改善线路处理。
+ 该驱动总体上是稳定的，并已在 SMP 机器（双 P2）上进行测试。
+
+ CY4601 系列支持的芯片组：
+
+ CY7C63723, CY7C63742, CY7C63743, CY7C64013
+
+ 支持的设备：
+
+ - DeLorme 的 USB Earthmate GPS（SiRF Star II lp 架构）
+ - Cypress HID->COM RS232 适配器
+
+ 注意：
+ Cypress Semiconductor 声明与该 HID 转 COM 设备无任何关联。
+
+ 大多数使用 CY4601 系列芯片的设备都应该可以使用该驱动，
+ 只要它们遵循 CY4601 的 USB 串口规范。
+
+ 技术说明：
+
+ Earthmate 默认的初始设置是
+ 4800 波特率、8 数据位、无校验、1 停止位（4800 8N1）……
+ 驱动启动时会以此设置初始化。
+ usbserial 核心负责其余的 termios 配置，
+ 并提供一些自定义的 termios 设置，
+ 以保证输出格式正确且可解析。
+
+ 设备可以通过发送 NMEA 命令进入 sirf 模式::
+
+ $PSRF100,<protocol>,<baud>,<databits>,<stopbits>,<parity>*CHECKSUM
+ $PSRF100,0,9600,8,1,0*0C
+
+ 之后只需将串口的termios设置改为与之匹配，即可开始通信。
+
+ 据我所知，它几乎支持所有在线文档中列出的 Sirf 命令（适用于固件版本 2.31），
+ 但有一些消息 ID 未知。
+
+ hid->com 适配器的最高波特率为 115200 bps。
+ 请注意，该设备在提升线路电压方面存在问题，或者无法正确提升线路电压。
+ 在使用 null modem 链接时不会有问题，
+ 只要不要尝试将两个设备直接连接在一起而不改装适配器以提升线路电压。
+
+ 该驱动支持 SMP（对称多处理器）环境。
+ 在使用该驱动进行文件传输时，性能相对较低。
+ 目前正在改进中，但我也愿意接受补丁。
+ 这里使用 URB 队列或数据包缓冲区可能是一个可行的解决方案。
+
+ 如果你有任何问题、遇到的故障、补丁或功能请求等，可以通过电子邮件联系我：
+ dignome@gmail.com（你的问题或补丁也可以提交到 usb-devel 邮件列表）。
+
+
+Digi AccelePort驱动
+--------------------------
+
+ 该驱动支持 Digi AccelePort USB 2 和 4 端口设备，
+ 包括 2 端口（外加一个并口）和 4 端口的 USB 串口转换器。
+ 该驱动 尚不支持 Digi AccelePort USB 8。
+
+ 该驱动在使用 usb-uhci 驱动的 SMP 系统下可以正常工作，
+ 但在使用 uhci 驱动的 SMP 系统下无法工作。
+
+ 总体来说，该驱动功能基本可用，
+ 但仍有一些 ioctl 需要实现，并且最终测试和调试尚未完成。
+ USB 2 上的并口被支持为串口到并口的转换器；
+ 换句话说，它在 Linux 上表现为另一个 USB 串口，
+ 虽然实际上它是一个并口。
+ Digi AccelePort USB 8 尚未支持。
+
+ 如对该驱动有任何问题或疑问，请联系 Peter Berger（pberger@brimson.com）或
+ Al Borchers（alborchers@steinerpoint.com）。
+
+Belkin USB 串口适配器F5U103
+-------------------------------------------
+
+ 这是 Belkin 出品的单端口 DB-9/PS-2 串口适配器，固件由 eTEK Labs 提供。
+ Peracom 的单端口串口适配器以及 GoHubs 适配器也可使用该驱动。
+
+ 当前状态：
+
+ 经过测试，以下功能可用：
+
+ - 波特率 300-230400
+ - 数据位 5-8
+ - 停止位 1-2
+ - 校验 N,E,O,M,S
+ - 握手 无，软件 (XON/XOFF)，硬件 (CTSRTS,CTSDTR) [1]_
+ - 断开 设置和清除
+ - 行控制 输入/输出查询和控制 [2]_
+
+ .. [1]
+ 硬件输入流控仅在固件版本高于 2.06 时启用。
+ 可阅读源码注释了解 Belkin 固件的已知问题。
+ 硬件输出流控在所有固件版本中均可使用。
+
+ .. [2]
+ 输入查询（CTS、DSR、CD、RI）显示最后报告的状态。
+ 输出查询（DTR、RTS）显示最后请求的状态，
+ 可能与自动硬件流控设置的当前状态不一致。
+
+ 待办事项：
+ - 添加真正的调制解调器控制线查询功能。目前跟踪中断报告的状态和请求的状态。
+ - 添加 UART 错误条件的错误报告回应用程序。
+ - 添加对刷新 ioctl 的支持。
+ - 添加所有其他缺失的功能。
+
+ 如对该驱动有任何问题或疑问，请联系 William
+ Greathouse，邮箱：wgreathouse@smva.com
+
+Empeg empeg-car Mark I/II驱动
+------------------------------
+
+ 这是一个实验性驱动，用于为 Empeg empeg-car MP3 播放器提供客户端同步工具的连接支持。
+
+ 使用提示：
+ * 不要忘记为 ttyUSB{0,1,2,...} 创建设备节点
+ * modprobe empeg (modprobe 是你的朋友)
+ * emptool --usb /dev/ttyUSB0 (或者你为设备节点命名的其他名称)
+
+ 如对该驱动有任何问题或疑问，请联系 Gary
+ Brubaker，邮箱：xavyer@ix.netcom.com
+
+
+MCT USB 单端口串口适配器 U232
+-------------------------------------------
+
+ 该驱动用于 Magic Control Technology Corp 生产的 MCT USB-RS232 转换器
+ （25 针型号 U232-P25，也有 9 针型号 U232-P9）。
+ 更多信息请访问制造商网站：http://www.mct.com.tw。
+
+ 该驱动总体上是可用的，尽管仍需进行更多测试。
+ 它是从 Belkin USB 串口适配器 F5U103 驱动派生而来，其
+ 待办事项列表同样适用于该驱动。
+ 该驱动也被发现适用于其他产品，这些产品具有相同的供应商 ID 但产品 ID 不同。
+ Sitecom 的 U232-P25 串口转换器使用产品 ID 0x230 和供应商 ID 0x711，
+ 并且可以使用该驱动。
+ D-Link 的 DU-H3SP USB BAY 也可以使用该驱动。
+ 如对该驱动有任何问题或疑问，请联系 Wolfgang
+ Grandegger，邮箱：wolfgang@ces.ch
+
+
+Inside Out Networks Edgeport驱动
+-----------------------------------
+
+ 该驱动支持 Inside Out Networks 公司生产的所有设备，具体型号如下：
+
+ - Edgeport/4
+ - Rapidport/4
+ - Edgeport/4t
+ - Edgeport/2
+ - Edgeport/4i
+ - Edgeport/2i
+ - Edgeport/421
+ - Edgeport/21
+ - Edgeport/8
+ - Edgeport/8 Dual
+ - Edgeport/2D8
+ - Edgeport/4D8
+ - Edgeport/8i
+ - Edgeport/2 DIN
+ - Edgeport/4 DIN
+ - Edgeport/16 Dual
+
+ 如对本驱动有任何问题或疑问，请联系 Greg Kroah-Hartman（greg@kroah.com）。
+
+
+REINER SCT cyberJack pinpad/e-com USB 智能卡读卡器
+--------------------------------------------------
+
+ 该设备用于与 ISO 7816 兼容的接触式芯片卡通信，例如 GSM SIM 卡。
+
+ 当前状态：
+
+ 这是该 USB 智能卡读卡器的内核部分驱动。
+ 同时，还提供了用户空间的 CT-API 驱动。
+ 下载地址待定，目前可以向维护者（linux-usb@sii.li）请求获取。
+
+ 如对本驱动有任何问题或疑问，请联系 linux-usb@sii.li。
+
+
+Prolific PL2303驱动
+----------------------
+
+ 该驱动支持任何使用 Prolific PL2303 芯片的设备。
+ 这包括多个单口 USB 转串口转换器、2010 年约 70% 的 USB GPS 设备，
+ 以及一些 USB UPS。Aten（UC-232）和 IO-Data 的设备也能使用此驱动，
+ DCU-11 手机数据线也支持。
+
+ 如对本驱动有任何问题或疑问，
+ 请联系 Greg Kroah-Hartman（greg@kroah.com）。
+
+
+KL5KUSB105芯片组 / PalmConnect USB单端口适配器
+--------------------------------------------------------
+
+当前状态：
+
+ 该驱动是通过分析 Palm 在 Windows 下的 USB 总线交互而开发的，
+ 因此仍有许多功能缺失。
+ 特别是串口 ioctl 有时是模拟的，
+ 或者尚未实现。
+ 不过，对 DSR 和 CTS 线路状态的支持已经实现（虽然不够完美），
+ 所以常用的 autopilot 和 pilot-manager 守护程序调用可以正常工作。
+ 驱动支持最高 115200 的波特率，
+ 但握手（软件或硬件）尚不支持，
+ 因此在进行大数据传输时，建议降低波特率以保证稳定性。
+
+ 最新的驱动信息请访问：http://www.uuhaus.de/linux/palmconnect.html
+
+Winchiphead CH341 驱动
+------------------------
+
+ 该驱动用于 Winchiphead CH341 USB-RS232 转换器。
+ 该芯片还支持 IEEE 1284 并口、I2C 和 SPI，但驱动不支持这些功能。
+ 协议是通过分析 Windows 驱动的行为得到的，目前没有公开的数据手册。
+
+ 厂商官网：http://www.winchiphead.com/
+
+ 如对本驱动有任何问题或疑问，请联系 frank@kingswood-consulting.co.uk
+
+Moschip MCS7720, MCS7715 驱动
+-------------------------------
+
+ 这些芯片存在于多家厂商销售的设备中，
+ 例如 Syba 和 Cables Unlimited，可能还有其他厂商。
+ MCS7720 提供两个串口，MCS7715 提供一个串口和一个标准 PC 并口。
+ 对 7715 并口的支持需要通过单独选项启用，
+ 该选项只有在设备驱动顶层配置菜单中先启用并口支持时才会出现。
+ 目前并口仅支持兼容模式（不支持 ECP/EPP）。
+
+待办事项：
+
+ - 实现并口的 ECP/EPP 模式。
+ - 目前超过 115200 波特率的支持存在问题。
+ - 基于 Moschip MCS7703 的单串口设备可能可以通过在 usb_device_id 表中添加条目来支持该驱动。
+ 但我手头没有这些设备，所以无法确认。
+
+通用串口驱动
+-------------------------------------------
+
+ 如果你的设备不属于上面列出的型号，或者不兼容这些型号，
+ 可以尝试使用“通用”接口。该接口不会向设备发送任何控制消息，
+ 也不支持任何设备流控制。
+ 你的设备只需至少有一个 bulk 输入端点或一个 bulk 输出端点即可。
+
+ 要让通用驱动识别你的设备，可以执行::
+
+ echo <vid> <pid> >/sys/bus/usb-serial/drivers/generic/new_id
+
+ 其中 <vid> 和 <pid> 替换为设备厂商 ID 和产品 ID 的十六进制表示。
+ 如果驱动是作为模块编译的，也可以在加载模块时提供一个 ID：::
+
+ insmod usbserial vendor=0x#### product=0x####
+
+ 该驱动已成功用于连接 NetChip USB 开发板，
+ 提供了一种开发 USB 固件而无需编写自定义驱动的方法。
+
+ 如对该驱动有任何问题或疑问，请联系 Greg Kroah-Hartman，邮箱：greg@kroah.com。
+
+
+联系信息
+=====================
+
+ 如果在使用上述驱动或任何指定设备时遇到问题，
+ 请联系对应驱动的作者（联系方式已在上文列出），
+ 或者加入 Linux-USB 邮件列表。
+ 邮件列表的加入方式及可搜索的归档链接请见：http://www.linux-usb.org/。
+
+Greg Kroah-Hartman
+greg@kroah.com
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 24/25] docs/zh_CN: Add usb-help.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (22 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 23/25] docs/zh_CN: Add usb-serial.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
2025-11-23 11:56 ` [PATCH v2 25/25] docs/zh_CN: Add CREDITS.rst translation macrofun
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/usb-help.rst into Chinese.
Update the translation through commit ecefae6db042
("docs: usb: rename files to .rst and add them to drivers-api")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
.../translations/zh_CN/usb/usb-help.rst | 28 +++++++++++++++++++
1 file changed, 28 insertions(+)
create mode 100644 Documentation/translations/zh_CN/usb/usb-help.rst
diff --git a/Documentation/translations/zh_CN/usb/usb-help.rst b/Documentation/translations/zh_CN/usb/usb-help.rst
new file mode 100644
index 000000000000..29ca3fbdc276
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/usb-help.rst
@@ -0,0 +1,28 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/usb-help.rst
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+============
+USB 参考资料
+============
+
+2008年3月7日
+
+除了位于 `Documentation/usb/*` 的说明文件外，如需 USB 相关帮助，请参考以下资源：
+
+- Linux-USB 项目： http://www.linux-usb.org
+ 镜像站点： http://usb.in.tum.de/linux-usb/
+ 以及： http://it.linux-usb.org
+- Linux USB 指南： http://linux-usb.sourceforge.net
+- Linux-USB 设备概览（工作设备及驱动）：
+ http://www.qbik.ch/usb/devices/
+
+Linux-USB 邮件列表： linux-usb@vger.kernel.org
--
2.52.0
^ permalink raw reply related [flat|nested] 32+ messages in thread* [PATCH v2 25/25] docs/zh_CN: Add CREDITS.rst translation
2025-11-23 11:55 [PATCH v2 00/25] Add Chinese translation for USB subsystem macrofun
` (23 preceding siblings ...)
2025-11-23 11:56 ` [PATCH v2 24/25] docs/zh_CN: Add usb-help.rst translation macrofun
@ 2025-11-23 11:56 ` macrofun
24 siblings, 0 replies; 32+ messages in thread
From: macrofun @ 2025-11-23 11:56 UTC (permalink / raw)
To: alexs, si.yanteng; +Cc: dzm91, corbet, linux-doc
Translate .../usb/CREDITS.rst into Chinese.
Update the translation through commit 7b2328c5a009
("docs: Fix typo in usb/CREDITS")
Signed-off-by: macrofun <baikefan@leap-io-kernel.com>
---
Documentation/translations/zh_CN/usb/CREDITS | 152 +++++++++++++++++++
1 file changed, 152 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..bff8b72e3b82
--- /dev/null
+++ b/Documentation/translations/zh_CN/usb/CREDITS
@@ -0,0 +1,152 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/usb/CREDITS
+:翻译:
+
+ 白钶凡 Kefan Bai <baikefan@leap-io-kernel.com>
+
+:校译:
+
+
+
+简易版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 驱动。我们从那项工作中学到
+ 了很多东西。
+
+ 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在内的
+ 所有操作系统开放。
+
+ - Thanks to 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 Forum成员们的帮助与支持。
+
+ - 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] 32+ messages in thread