* [PATCH v3] docs/zh_CN: usb: refine translated wording and formatting [not found] <2026053149-flaky-shallow-2460@gregkh> @ 2026-06-01 3:39 ` Kefan Bai 2026-06-01 4:00 ` Alex Shi 2026-06-01 8:26 ` [PATCH v4] " Kefan Bai 0 siblings, 2 replies; 5+ messages in thread From: Kefan Bai @ 2026-06-01 3:39 UTC (permalink / raw) To: linux-usb, si.yanteng, gregkh, seakeel Cc: dzm91, corbet, skhan, linux-doc, linux-kernel, doubled, alexs, Kefan Bai Refine the zh_CN USB translations for clarity and consistency. Improve wording, wrapping, and formatting across the translated USB documents. Link: https://lore.kernel.org/r/2026053149-flaky-shallow-2460@gregkh Suggested-by: Alex Shi <seakeel@gmail.com> Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com> --- v3: - refine the subject and commit message - add a Link trailer to the cleanup request thread - move revision notes below the cut line v2: - replace the obsolete FSF mailing address reference in acm.rst - trim the commit message to satisfy checkpatch Documentation/translations/zh_CN/usb/CREDITS | 146 ++++--- Documentation/translations/zh_CN/usb/acm.rst | 62 ++- .../translations/zh_CN/usb/authorization.rst | 79 ++-- .../translations/zh_CN/usb/chipidea.rst | 58 ++- Documentation/translations/zh_CN/usb/dwc3.rst | 37 +- Documentation/translations/zh_CN/usb/ehci.rst | 247 +++++------- .../translations/zh_CN/usb/index.rst | 18 +- .../translations/zh_CN/usb/usbmon.rst | 363 ++++++++---------- 8 files changed, 442 insertions(+), 568 deletions(-) diff --git a/Documentation/translations/zh_CN/usb/CREDITS b/Documentation/translations/zh_CN/usb/CREDITS index c133b1a5daff..a37958d139cc 100644 --- a/Documentation/translations/zh_CN/usb/CREDITS +++ b/Documentation/translations/zh_CN/usb/CREDITS @@ -10,12 +10,10 @@ :校译: -简易 Linux USB 驱动的致谢名单： +Simple Linux USB 驱动项目致谢名单： -以下人员都为 Linux USB 驱动代码作出了贡献 -（按姓氏字母顺序排列）。我相信这份名单本应 -更长一些，但确实不容易维护。 -如需将自己加入名单，请提交补丁。 +以下人员都为 Linux USB 驱动代码作出过贡献（按姓氏字母顺序排列）。这份名 +单本该更长，只是确实不易维护；如果你也应列名其中，欢迎提交补丁把自己加上。 Georg Acher <acher@informatik.tu-muenchen.de> David Brownell <dbrownell@users.sourceforge.net> @@ -41,123 +39,123 @@ 特别感谢： Inaky Perez Gonzalez <inaky@peloncho.fis.ucm.es> - 感谢他发起了 Linux USB 驱动开发工作，并编写了体量较大的 uusbd - 驱动中的大部分代码。我们从那项工作中学到了很多。 + 感谢他牵头开发 Linux USB 驱动，并编写了 uusbd 驱动的大部分代码，我们 + 从中学到了很多。 NetBSD 和 FreeBSD 的 USB 开发者们 感谢他们加入 Linux USB 邮件列表，提供建议并分享实现经验。 -附加感谢： - 还要感谢以下公司与个人在硬件、支持、时间投入和开发方面提供的捐赠与帮助 - （摘自 Inaky 驱动原始的 THANKS 文件）： +另外还要感谢： - 以下公司曾帮助我们开发 Linux USB / UUSBD： + 以下公司和个人在硬件、支持、时间和开发工作上给予了帮助（摘自 Inaky + 驱动原始的 THANKS 文件）： - - 3Com GmbH 捐赠了一台 ISDN Pro TA，并在技术问题和测试设备方面为我 - 提供支持。没想到能得到这么大的帮助。 + 以下公司曾为 Linux USB / UUSBD 的开发提供帮助： - - USAR Systems 向我们提供了他们出色的 USB 评估套件， - 使我们能够测试 Linux USB 驱动对最新 USB 规范的符合性。 - USAR Systems 认识到保持开放操作系统与时俱进的重要性， - 并以硬件支持这个项目。感谢！ + - 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 实现。 + - CMD Technology, Inc. 慷慨捐赠了一块 CSA-6700 PCI 转 USB 控制卡， + 用于测试 OHCI 实现。 - - 由于他们对我们的支持，Keytronic 可以放心， - 他们的键盘能卖给至少 300 万 Linux 用户中的一部分。 + - 有了他们的支持，Keytronic 至少可以确信，其键盘能够销售给 300 万 + Linux 用户中的一部分。 - - ing büro h doran [http://www.ibhdoran.com]! - 在欧洲，想给主板买一个 PC 背板 USB 连接器几乎是不可能的 - （我自己做的那个相当糟糕 :)）。现在我知道该去哪里买漂亮的 USB - 配件了！ + - 特别感谢 ing büro h doran [http://www.ibhdoran.com]。 + 在欧洲，想给主板配一个 PC 背板 USB 连接器几乎是不可能的（我自己 + 做的那个效果并不好）。现在我知道该去哪里购买合适的 USB 配件了。 - Genius Germany 捐赠了一只 USB 鼠标，用于测试鼠标启动协议； - 他们还捐赠了 F-23 数字摇杆和 NetMouse Pro。感谢！ + 他们还捐赠了 F-23 数字摇杆和 NetMouse Pro，在此致谢。 - - AVM GmbH Berlin 支持我们开发 Linux 下的 AVM ISDN Controller B1 USB 驱动。 - AVM 是领先的 ISDN 控制器制造商，其主动式设计对包括 Linux 在内的 - 所有操作系统平台开放。 + - AVM GmbH Berlin 支持我们开发 Linux 下的 AVM ISDN Controller B1 USB + 驱动。AVM 是领先的 ISDN 控制器制造商，其开放式设计适用于包括 + Linux 在内的所有操作系统平台。 - - 非常感谢 Y-E Data, Inc 捐赠的 FlashBuster-U USB 软驱， - 使我们能够测试批量传输代码。 + - 非常感谢 Y-E Data, Inc 捐赠的 FlashBuster-U USB 软驱，使我们能够测试 + 批量传输代码。 - 感谢 Logitech 捐赠了一只三轴 USB 鼠标。 - Logitech 负责设计、制造并销售各种人机接口设备， - 在键盘、鼠标、轨迹球、摄像头、扬声器，以及面向游戏和专业用途的 - 控制设备方面拥有悠久历史和丰富经验。 + Logitech 负责设计、制造并销售各种人机接口设备，在键盘、鼠标、轨迹球、 + 摄像头、扬声器，以及面向游戏和专业用途的控制设备方面拥有悠久历史和 + 丰富经验。 - 作为这些设备广为人知的供应商和销售商，他们捐赠了 USB 鼠标、 - 摇杆和扫描仪，以表明 Linux 的重要性，也让 Logitech 的客户 - 能在自己喜欢的操作系统上获得支持，并让所有 Linux 用户都能使用 - Logitech 以及其他 USB 硬件。 + 作为这些设备广为人知的供应商和销售商，他们捐赠了 USB 鼠标、摇杆和 + 扫描仪，以表明 Linux 的重要性，也让 Logitech 的客户能在自己偏爱的 + 操作系统上获得支持，并让所有 Linux 用户都能使用 Logitech 及其他 + USB 硬件。 Logitech 也是 1999 年 2 月 11 日维也纳 Linux 大会的官方赞助商， 我们将在会上展示 Linux USB 工作的最新进展。 - - 感谢 CATC 提供 USB Inspector，帮助我们揭开 UHCI 内部实现中 - 那些不为人知的角落。 + - 感谢 CATC 提供 USB Inspector，帮助我们看到 UHCI 内部实现中的那些 + 隐秘角落。 - 感谢 Entrega 为开发工作提供 PCI 转 USB 卡、集线器和转换器产品。 - - 感谢 ConnectTech 提供 WhiteHEAT USB 转串口转换器以及相关文档， - 让这个驱动得以写成。 + - 感谢 ConnectTech 提供 WhiteHEAT USB 转串口转换器以及相关文档，让 + 这个驱动得以写成。 - - 感谢 ADMtek 提供 Pegasus 和 Pegasus II 评估板、规格说明， - 以及驱动开发过程中的宝贵建议。 + - 感谢 ADMtek 提供 Pegasus 和 Pegasus II 评估板、规格说明，以及驱动 + 开发过程中的宝贵建议。 - 另外还要感谢以下个人（嘿，顺序不分先后 :)） + 另外还要感谢以下个人（排名不分先后）： - - Oren Tirosh <orenti@hishome.net>, - 他非常耐心地听我唠叨各种 USB 疑问，还给了很多很酷的想法。 + - Oren Tirosh <orenti@hishome.net> + 他非常耐心地解答我反复提出的各种 USB 问题，并提供了许多有价值的 + 想法。 - - Jochen Karrer <karrer@wpfd25.physik.uni-wuerzburg.de>, - 指出了致命 bug，并给出了宝贵建议。 + - Jochen Karrer <karrer@wpfd25.physik.uni-wuerzburg.de> + 指出了严重问题，并给出了宝贵建议。 - - Edmund Humemberger <ed@atnet.at>，他在公共关系与项目管理方面 - 为 Linux-USB 项目付出了巨大的努力。 + - Edmund Humemberger <ed@atnet.at>，他在公共关系与项目管理方面为 + Linux-USB 项目付出了巨大的努力。 - - Alberto Menegazzi <flash@flash.iol.it> 正在着手编写 UUSBD 文档，加油！ + - Alberto Menegazzi <flash@flash.iol.it> 正在着手编写 UUSBD 文档。 - - Ric Klaren <ia_ric@cs.utwente.nl> 编写了很好的入门文档， - 与 Alberto 的作品形成良性竞争：）。 + - Ric Klaren <ia_ric@cs.utwente.nl> 编写了很好的入门文档，与 + Alberto 的作品形成了良性互补。 - - Christian Groessler <cpg@aladdin.de>，感谢他在那些棘手细节上的帮助。 + - Christian Groessler <cpg@aladdin.de>，感谢他在诸多复杂细节上的帮助。 - - Paul MacKerras 改进了 OHCI 实现，推动了对 iMac 的支持， - 并提供了大量的改进意见。 + - Paul MacKerras 改进了 OHCI 实现，推动了对 iMac 的支持，并提供了 + 大量的改进意见。 - - Fernando Herrera <fherrera@eurielec.etsit.upm.es> - 负责撰写、维护并不断补充那份期待已久、独一无二又精彩的 - UUSBD FAQ！太棒了！ + - Fernando Herrera <fherrera@eurielec.etsit.upm.es> 负责撰写、维护并 + 持续补充那份期待已久、内容翔实的 UUSBD FAQ。 - - Rasca Gmelch <thron@gmx.de> 重新启用了 raw 驱动， - 指出了一些错误，并启动了 uusbd-utils 软件包。 + - Rasca Gmelch <thron@gmx.de> 重新启用了 raw 驱动，指出了一些错误，并 + 启动了 uusbd-utils 软件包。 - - Peter Dettori <dettori@ozy.dec.com>，像疯了一样挖掘 bug， - 还提出了很多很酷的建议，太棒了！ + - Peter Dettori <dettori@ozy.dec.com>，持续发现问题，并提出了许多 + 有价值的建议。 - - 自由软件与 Linux 社区的所有成员，包括 FSF、GNU 项目、 - MIT X 联盟、TeX 社区等等，谢谢你们！ + - 自由软件与 Linux 社区的所有成员，包括 FSF、GNU 项目、MIT X 联盟、 + TeX 社区等，在此一并致谢。 - - 特别感谢 Richard Stallman 创造了 Emacs！ + - 特别感谢 Richard Stallman 创造了 Emacs。 - - 感谢 linux-usb 邮件列表的所有成员，读了那么多邮件——不开玩笑了， - 感谢你们提出的所有建议！ + - 感谢 linux-usb 邮件列表的所有成员阅读了大量邮件，并提出了诸多 + 建议。 - 感谢 USB Implementers Forum 成员们的帮助与支持。 - - Nathan Myers <ncm@cantrip.org>，感谢他的建议！ - （希望你喜欢 Cibeles 的派对。） + - Nathan Myers <ncm@cantrip.org>，感谢他的建议。（也希望你喜欢 + Cibeles 的派对。） - - 感谢 Linus Torvalds 创建、开发并管理 Linux。 + - 感谢 Linus Torvalds 创立、开发并维护 Linux。 - Mike Smith、Craig Keithley、Thierry Giron 和 Janet Schank - 感谢他们让我认识到标准 USB 集线器其实也没那么“标准”， - 这有助于我们在标准集线器驱动中加入厂商特定的特殊处理。 + 感谢他们让我认识到，标准 USB 集线器其实一点也不“标准”；也正因 + 如此，我们才能在标准集线器驱动中加入厂商特定的处理。 diff --git a/Documentation/translations/zh_CN/usb/acm.rst b/Documentation/translations/zh_CN/usb/acm.rst index 51d6eb8f5660..b2e35787af45 100644 --- a/Documentation/translations/zh_CN/usb/acm.rst +++ b/Documentation/translations/zh_CN/usb/acm.rst @@ -20,33 +20,26 @@ Linux ACM 驱动 v0.16 0. 免责声明 ~~~~~~~~~~~ -本程序是自由软件；你可以在自由软件基金会发布的 -GNU 通用公共许可证第 2 版，或者（按你的选择） -任何后续版本的条款下重新发布和/或修改它。 +本程序是自由软件；你可以在自由软件基金会发布的 GNU 通用公共许可证第 2 版， +或者（按你的选择）任何后续版本的条款下重新发布和/或修改它。 -发布本程序是希望它能发挥作用，但它不附带任何担保； -甚至不包括对适销性或特定用途适用性的默示担保。 -详情见 GNU 通用公共许可证。 +发布本程序是希望它能发挥作用，但它不附带任何担保；甚至不包括对适销性或 +特定用途适用性的默示担保。详情见 GNU 通用公共许可证。 -你应该已经随本程序收到了 GNU 通用公共许可证的副本； -如果没有，请致信：Free Software Foundation, Inc., 59 -Temple Place, Suite 330, Boston, MA 02111-1307 USA。 +你应该已经随本程序收到了 GNU 通用公共许可证的副本；如果没有，请参见 +COPYING 文件。 -如需联系作者，可发送电子邮件至 vojtech@suse.cz， -或邮寄至： -Vojtech Pavlik, Ucitelska 1576, Prague 8, -182 00, Czech Republic。 +如需联系作者，可发送电子邮件至 vojtech@suse.cz，或邮寄至： +Vojtech Pavlik, Ucitelska 1576, Prague 8, 182 00, Czech Republic。 -为方便起见，软件包中已附带 GNU 通用公共许可证 -第 2 版：见 COPYING 文件。 +为方便起见，软件包中已附带 GNU 通用公共许可证第 2 版：见 COPYING 文件。 1. 使用方法 ~~~~~~~~~~~ -``drivers/usb/class/cdc-acm.c`` 驱动可用于符合 USB -通信设备类抽象控制模型（USB CDC ACM）规范的 -USB 调制解调器和 USB ISDN 终端适配器。 +``drivers/usb/class/cdc-acm.c`` 驱动适用于符合 USB 通信设备类抽象控制模型 +（USB CDC ACM）规范的 USB 调制解调器和 USB ISDN 终端适配器。 -许多调制解调器支持此驱动，以下是我所知道的一些型号： +已知支持该驱动的调制解调器包括： - 3Com OfficeConnect 56k - 3Com Voice FaxModem Pro @@ -56,17 +49,16 @@ USB 调制解调器和 USB ISDN 终端适配器。 - Compaq 56k FaxModem - ELSA Microlink 56k -我知道有一款 ISDN 终端适配器可以与 ACM 驱动一起使用： +已知有一款 ISDN 终端适配器可以配合 ACM 驱动使用： - 3Com USR ISDN Pro TA -一些手机也可以通过 USB 连接。 -我知道以下机型可以正常工作： +一些手机也可以通过 USB 连接，已知可用的机型有： - SonyEricsson K800i -遗憾的是，许多调制解调器和大多数 ISDN TA -都使用专有接口，因此无法与此驱动配合工作。 +遗憾的是，很多调制解调器和大多数 ISDN TA 都使用专有接口，因此无法配合该 +驱动工作。 购买前请先确认设备是否符合 ACM 规范。 要使用这些调制解调器，需要加载以下模块:: @@ -75,15 +67,13 @@ USB 调制解调器和 USB ISDN 终端适配器。 uhci-hcd.ko ohci-hcd.ko or ehci-hcd.ko cdc-acm.ko -之后就应该可以访问这些调制解调器了。 -应当可以使用 ``minicom``、``ppp`` 和 ``mgetty`` -与它们通信。 +之后就应该能访问这些调制解调器，并用 ``minicom``、``ppp`` 和 +``mgetty`` 与它们通信。 2. 验证驱动是否正常工作 ~~~~~~~~~~~~~~~~~~~~~~~ -第一步是检查 ``/sys/kernel/debug/usb/devices``， -其内容应该类似如下:: +第一步是查看 ``/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 @@ -112,11 +102,10 @@ USB 调制解调器和 USB ISDN 终端适配器。 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.)``，那就无能为力了： -这说明你手上的设备使用的是厂商专有接口:: +关键是看这三行，再结合 ``Cls=`` 字段里出现的 ``comm`` 和 ``data`` 类，就 +能判断这是一台 ACM 设备。``Driver=acm`` 表示该设备正在使用 acm 驱动。如果 +只看到 ``Cls=ff(vend.)``，那就说明这台设备使用的是厂商专有接口，ACM 驱动 +无法处理:: 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 @@ -142,6 +131,5 @@ USB 调制解调器和 USB ISDN 终端适配器。 usb.c: acm driver claimed interface c7b5f3f8 usb.c: acm driver claimed interface c7691fa0 -如果以上都正常，请启动 ``minicom``， -把它配置为连接 ``ttyACM`` 设备，然后 -尝试输入 ``at``。如果返回 ``OK``，说明一切工作正常。 +如果这些都正常，请启动 ``minicom``，把它配置为连接到 ``ttyACM`` 设备，然后 +尝试输入 ``at``。如果返回 ``OK``，说明驱动工作正常。 diff --git a/Documentation/translations/zh_CN/usb/authorization.rst b/Documentation/translations/zh_CN/usb/authorization.rst index 2aa311f6b967..e2ff2282bd03 100644 --- a/Documentation/translations/zh_CN/usb/authorization.rst +++ b/Documentation/translations/zh_CN/usb/authorization.rst @@ -10,34 +10,32 @@ :校译: -============================= -授权或禁止 USB 设备连接到系统 -============================= +=========================== +允许或禁止 USB 设备接入系统 +=========================== 版权 (C) 2007 Inaky Perez-Gonzalez <inaky@linux.intel.com> 英特尔公司 -此功能允许你控制 USB 设备是否可以在系统中使用。 -借助它，你可以完全通过用户空间实现对 USB 设备的锁定。 +有了这项功能，你就可以控制 USB 设备是否允许在系统中使用，并把 USB 设备锁 +定机制完全放在用户空间实现。 -目前，当插入一个 USB 设备时，系统会对其进行配置， -其接口会立即向用户开放。 -有了这项改动，只有在 root 授权设备完成配置后， -设备才可被使用。 +目前，USB 设备一接入系统就会被立即配置，其接口也会立刻向用户开放。引入 +这项机制后，只有在 root 明确授权后，设备才会完成配置并允许使用。 用法 ==== -授权设备接入:: +授权设备接入系统:: $ echo 1 > /sys/bus/usb/devices/DEVICE/authorized -取消对设备的授权:: +取消设备授权:: $ echo 0 > /sys/bus/usb/devices/DEVICE/authorized -将新连接到 ``hostX`` 的设备默认设为未授权（即锁定）:: +将连接到 ``hostX`` 的新设备默认设为未授权（即锁定）:: $ echo 0 > /sys/bus/usb/devices/usbX/authorized_default @@ -45,15 +43,14 @@ $ echo 1 > /sys/bus/usb/devices/usbX/authorized_default -默认情况下，所有 USB 设备都是授权的。 -向 ``authorized_default`` 属性写入 ``2`` 会使内核 -默认只授权连接到内部 USB 端口的设备。 +默认情况下，所有 USB 设备都是授权的。向 ``authorized_default`` 属性写入 +``2`` 会使内核默认只授权连接到内部 USB 端口的设备。 -系统锁定示例（比较粗糙） ------------------------- +系统锁定示例（简化版） +---------------------- -假设你想实现一个锁定功能，只允许类型为 XYZ 的设备接入 -（例如某台带有外露 USB 端口的自助服务终端）:: +假设你想做一个锁定机制，只允许 XYZ 类型的设备接入（例如一台带有外露 USB +端口的自助终端）:: 启动系统 rc.local -> @@ -63,21 +60,18 @@ echo 0 > $host/authorized_default done -给 udev 挂一个脚本，用于处理新插入的 USB 设备:: +为 udev 配置一个脚本，用于处理新插入的 USB 设备:: if device_is_my_type $DEV then echo 1 > $device_path/authorized - done + fi -``device_is_my_type()`` 才是锁定方案真正见功夫的 -地方。仅仅检查 class、type 和 protocol 是否匹配 -某个值，是你能做出的最糟糕的安全验证之一； -对想绕过它的人来说，这反而是最容易利用的方案。 -如果你需要真正安全的办法，那就该使用加密、 -证书认证之类的机制。把 USB 存储设备当作 -“钥匙”的一个简单例子可以是:: +锁定方案是否可靠，关键全在 ``device_is_my_type()`` 的实现。仅仅检查 +class、type 和 protocol 是否匹配，几乎是最差的一种安全校验方式；对想绕过 +它的人来说，这种做法反而最容易伪造。如果你真要做安全控制，就该使用加密、 +证书认证之类的机制。把 USB 存储设备当作“钥匙”的一个简单示例可以写成:: function device_is_my_type() { @@ -87,7 +81,7 @@ sum=$(md5sum /mntpoint/.signature) if [ $sum = $(cat /etc/lockdown/keysum) ] then - echo "We are good, connected" + echo "验证通过，已连接" umount /mntpoint # 再做一些额外处理，让其他人也能使用它 else @@ -96,17 +90,16 @@ } -当然，这个例子很粗糙；真正要做的话， -你会想用基于 PKI 的证书校验，这样就不必依赖 -共享密钥之类的东西。不过你应该已经明白意思了。 -任何拿到设备仿真工具包的人都能伪造描述符和设备信息。 -别信这个。 +当然，这个例子仍然比较简化。真正落地时，更合适的做法是使用基于 PKI 的证 +书校验，这样就不必依赖共享密钥之类的机制了。不过意思已经很清楚：任何拿到 +设备仿真工具包的人，都能伪造描述符和设备信息，所以别把这类检查当成真正 +的安全保障。 接口授权 -------- -也有类似的方法用于允许或拒绝特定 USB 接口。 -这使得你可以只阻止某个 USB 设备中的部分接口。 +也可以用类似的方法允许或拒绝特定的 USB 接口。这样一来，你只需要阻止某个 +USB 设备中的部分接口。 授权接口:: @@ -126,14 +119,12 @@ $ echo 0 > /sys/bus/usb/devices/usbX/interface_authorized_default -默认情况下， -``interface_authorized_default`` 位为 ``1``， -因此所有接口默认都处于已授权状态。 +默认情况下，``interface_authorized_default`` 位为 ``1``，因此所有接口默认 +都会处于授权状态。 注意： - 如果把一个先前未授权的接口改为已授权， - 则必须通过将 ``INTERFACE`` 写入 ``/sys/bus/usb/drivers_probe`` - 来手动触发驱动探测。 + 如果把一个先前未授权的接口改为已授权，则必须通过将 ``INTERFACE`` 写入 + ``/sys/bus/usb/drivers_probe`` 来手动触发驱动探测。 -对于需要多个接口的驱动程序，应先授权所有必需接口， -然后再触发驱动探测。这样做可以避免副作用。 +对于需要多个接口的驱动程序，应先授权所有必需接口，然后再触发驱动探测。 +这样做可以避免副作用。 diff --git a/Documentation/translations/zh_CN/usb/chipidea.rst b/Documentation/translations/zh_CN/usb/chipidea.rst index ea0dc3043189..011fb16f3350 100644 --- a/Documentation/translations/zh_CN/usb/chipidea.rst +++ b/Documentation/translations/zh_CN/usb/chipidea.rst @@ -17,18 +17,17 @@ ChipIdea 高速双角色控制器驱动 1. 如何测试 OTG FSM（HNP 和 SRP） --------------------------------- -下面以两块 Freescale i.MX6Q Sabre SD 开发板为例， -说明如何通过 sysfs 输入文件演示 OTG 的 HNP 和 SRP 功能。 +下面以两块 Freescale i.MX6Q Sabre SD 开发板为例，演示如何通过 sysfs 属性 +测试 OTG 的 HNP 和 SRP 功能。 -1.1 如何使能 OTG FSM +1.1 如何启用 OTG FSM -------------------- 1.1.1 在 ``menuconfig`` 中选择 ``CONFIG_USB_OTG_FSM``，并重新编译内核 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -重新构建内核镜像和模块。如果想查看 OTG FSM 的 -一些内部变量，可以挂载 ``debugfs``；其中有两个文件 -可以显示 OTG FSM 变量以及部分控制器寄存器的值:: +重新构建内核镜像和模块。如果想查看 OTG FSM 的内部变量，可以挂载 +``debugfs``；其中有两个文件，分别显示 OTG FSM 的变量和部分控制器寄存器值:: cat /sys/kernel/debug/ci_hdrc.0/otg cat /sys/kernel/debug/ci_hdrc.0/registers @@ -44,11 +43,10 @@ ChipIdea 高速双角色控制器驱动 1.2 测试步骤 ------------ -1) 给两块 Freescale i.MX6Q Sabre SD 开发板上电， - 并加载 gadget 类驱动（例如 ``g_mass_storage``）。 +1) 给两块 Freescale i.MX6Q Sabre SD 开发板上电，并加载 gadget 类驱动（例如 + ``g_mass_storage``）。 -2) 用 USB 线连接两块开发板： - 一端是 micro A 插头，另一端是 micro B 插头。 +2) 用 USB 线连接两块开发板：一端是 micro A 插头，另一端是 micro B 插头。 插入 micro A 插头的一端是 A 设备，它应枚举另一端的 B 设备。 @@ -66,32 +64,28 @@ ChipIdea 高速双角色控制器驱动 echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req - 或者，通过引入 HNP 轮询，B 端主机可以知道 - A 端外设希望切换为主机角色，因此这次角色切换 - 也可以通过 A 端外设响应 B 端主机的轮询， - 在 A 侧触发。 - 这可以通过在 A 设备上执行下面的命令来完成:: + 或者，也可以借助 HNP 轮询，让 B 端主机知道 A 端外设希望切回主机角色。 + 因此，这次切换也可以由 A 侧触发，也就是由 A 端外设响应 B 端主机的轮询 + 来完成。可在 A 设备上执行下面的命令:: echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req A 设备应切回主机角色并枚举 B 设备。 -5) 拔掉 B 设备（拔掉 micro B 插头）， - 并在 10 秒内重新插入； +5) 拔掉 B 设备（拔掉 micro B 插头），并在 10 秒内重新插入。 A 设备应重新枚举 B 设备。 -6) 拔掉 B 设备（拔掉 micro B 插头）， - 并在 10 秒后重新插入； +6) 拔掉 B 设备（拔掉 micro B 插头），并在 10 秒后重新插入。 A 设备不应重新枚举 B 设备。 - 如果 A 设备希望使用总线： + 如果 A 设备还想继续使用总线： 在 A 设备上执行:: echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req - 如果 B 设备希望使用总线： + 如果 B 设备想使用总线： 在 B 设备上执行:: @@ -111,40 +105,38 @@ ChipIdea 高速双角色控制器驱动 echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req - A 设备应恢复 USB 总线并枚举 B 设备。 + A 设备应恢复 USB 总线，并枚举 B 设备。 1.3 参考文档 ------------ -《On-The-Go and Embedded Host Supplement -to the USB Revision 2.0 Specification +《On-The-Go and Embedded Host Supplement to the USB Revision 2.0 Specification July 27, 2012 Revision 2.0 version 1.1a》 2. 如何将 USB 用作系统唤醒源 ---------------------------- -下面是在 i.MX6 平台上把 USB 用作系统唤醒源的示例。 +下面给出在 i.MX6 平台上将 USB 用作系统唤醒源的示例。 -2.1 使能核心控制器的唤醒功能:: +2.1 启用核心控制器的唤醒功能:: echo enabled > /sys/bus/platform/devices/ci_hdrc.0/power/wakeup -2.2 使能 glue 层的唤醒功能:: +2.2 启用 glue 层的唤醒功能:: echo enabled > /sys/bus/platform/devices/2184000.usb/power/wakeup -2.3 使能 PHY 的唤醒功能（可选）:: +2.3 启用 PHY 的唤醒功能（可选）:: echo enabled > /sys/bus/platform/devices/20c9000.usbphy/power/wakeup -2.4 使能根集线器的唤醒功能:: +2.4 启用根集线器的唤醒功能:: echo enabled > /sys/bus/usb/devices/usb1/power/wakeup -2.5 使能相关设备的唤醒功能:: +2.5 启用相关设备的唤醒功能:: echo enabled > /sys/bus/usb/devices/1-1/power/wakeup -如果系统只有一个 USB 端口， -而你希望在该端口上启用 USB 唤醒功能， -可以使用下面的脚本:: +如果系统只有一个 USB 端口，而你希望在该端口上启用 USB 唤醒功能，可以使用 +下面的脚本:: for i in $(find /sys -name wakeup | grep usb);do echo enabled > $i;done; diff --git a/Documentation/translations/zh_CN/usb/dwc3.rst b/Documentation/translations/zh_CN/usb/dwc3.rst index 3468ce50c5ba..9584cbbf6d03 100644 --- a/Documentation/translations/zh_CN/usb/dwc3.rst +++ b/Documentation/translations/zh_CN/usb/dwc3.rst @@ -18,46 +18,43 @@ DWC3 驱动 待办 ~~~~ -阅读时如果想顺手认领点任务，可以从下面挑一项 :) +如果你愿意接手其中一项任务，可以从下面选择： - 将中断处理程序改为每个端点各自使用线程化 IRQ - 事实证明，有些 DWC3 命令大约需要 ``~1 ms`` 才能完成。 - 当前代码会一直自旋等待命令完成，这种设计并不好。 + 实践表明，某些 DWC3 命令大约需要 ``~1 ms`` 才能完成。当前代码会一直自旋 + 等待命令完成，这并不是好办法。 实现思路： - - DWC 核心实现了一个按端点对中断进行解复用的 IRQ 控制器。 - 中断号在探测（``probe``）阶段分配，并归属于该设备。 - 如果硬件通过 ``MSI`` 为每个端点提供独立中断， - 那么这个“虚拟”IRQ 控制器就可以被真实的端点中断取代。 + - DWC 核心实现了一个按端点分发中断的 IRQ 控制器。中断号在探测 + （``probe``）阶段分配，并归属于该设备。如果硬件通过 ``MSI`` 为每个 + 端点提供独立中断，那么这个“虚拟”IRQ 控制器就可以被真实的端点中断 + 取代。 - - 在调用 ``usb_ep_enable()`` 时请求并分配中断资源， - 在调用 ``usb_ep_disable()`` 时释放中断资源。 - 最坏情况下需要 32 个中断，最少是 ``ep0/1`` 的两个中断。 + - 在调用 ``usb_ep_enable()`` 时请求并分配中断资源，在调用 + ``usb_ep_disable()`` 时释放中断资源。最坏情况下需要 32 个中断，最少是 + ``ep0/1`` 的两个中断。 - ``dwc3_send_gadget_ep_cmd()`` 将在 ``wait_for_completion_timeout()`` 中休眠，直到命令完成。 - 中断处理程序分为以下几个部分： - 设备级主中断处理程序 - 遍历每个事件，并对其调用 ``generic_handle_irq()``。 - 从 ``generic_handle_irq()`` 返回后，确认事件计数器，使中断最终消失。 + 遍历每个事件，并调用 ``generic_handle_irq()`` 处理。返回后再确认 + 事件计数器，让中断最终消失。 - 设备级线程化处理程序 无。 - 端点中断的主处理程序 - 读取事件并尽量处理它。凡是需要睡眠的操作都交给线程处理。 - 事件保存在每个端点的数据结构中。 - 还要注意，一旦把某项工作交给线程处理， - 就不要再在主处理程序里处理它， - 以免出现优先级反转之类的问题。 + 读取事件并尽量处理；凡是需要睡眠的操作都交给线程处理。事件保存在 + 每个端点的数据结构中。一旦某项工作已经交给线程处理，主处理程序里就 + 不要再碰它，以免出现优先级反转之类的问题。 - 端点中断的线程化处理程序 处理剩余的端点工作，这些工作可能会睡眠，例如等待命令完成。 - 延迟: + 延迟： - 不应增加延迟，因为中断线程具有较高优先级， - 会在普通用户态任务之前运行 + 不应增加额外延迟，因为中断线程优先级较高，会在普通用户任务之前运行 （除非用户更改了调度优先级）。 diff --git a/Documentation/translations/zh_CN/usb/ehci.rst b/Documentation/translations/zh_CN/usb/ehci.rst index e05e493a30d3..c4c52303b13e 100644 --- a/Documentation/translations/zh_CN/usb/ehci.rst +++ b/Documentation/translations/zh_CN/usb/ehci.rst @@ -14,45 +14,37 @@ EHCI 驱动 ========= -2002年12月27日 +2002 年 12 月 27 日 -EHCI 驱动用于通过支持 USB 2.0 的主机控制器 -硬件与高速 USB 2.0 设备通信。USB 2.0 兼容 -USB 1.1 标准，它定义了三种传输速率： +EHCI 驱动用于借助支持 USB 2.0 的主机控制器，与高速 USB 2.0 设备通信。USB +2.0 向下兼容 USB 1.1，并定义了三种传输速率： - “高速”（High Speed）480 Mbit/sec（60 MByte/sec） - “全速”（Full Speed）12 Mbit/sec（1.5 MByte/sec） - “低速”（Low Speed）1.5 Mbit/sec -USB 1.1 仅支持全速与低速。 -高速设备可以在 USB 1.1 系统上使用， -但速度会降到 USB 1.1 的速率。 +USB 1.1 仅支持全速与低速。高速设备可以在 USB 1.1 系统上使用，但速度会 +降到 USB 1.1 的速率。 -USB 1.1 设备也可以在 USB 2.0 系统上使用。当它们 -插入 EHCI 控制器时，会被交由 USB 1.1 的伴随 -（companion）控制器处理，该控制器通常是 OHCI 或 UHCI。 +USB 1.1 设备也可以在 USB 2.0 系统上使用。当它们插入 EHCI 控制器时，会交给 +USB 1.1 的伴随（companion）控制器处理，该控制器通常是 OHCI 或 UHCI。 -当 USB 1.1 设备插入 USB 2.0 集线器时，它们通过 -集线器中的事务转换器（Transaction Translator，TT） -与 EHCI 控制器交互，该转换器将低速或全速事务转换为 -高速分割事务，从而避免浪费传输带宽。 +当 USB 1.1 设备插入 USB 2.0 集线器时，它们会通过集线器里的事务转换器 +（Transaction Translator，TT）与 EHCI 控制器通信。该转换器会把低速或全 +速事务转换为高速分割事务，从而避免浪费传输带宽。 -截至本文撰写时，该驱动已在以下 EHCI 实现上成功运行 -（按字母顺序）：Intel、NEC、Philips 和 VIA。 -其他供应商的 EHCI 实现正在陆续问世； -预计该驱动在这些实现上也可正常运行。 +截至本文撰写时，该驱动已在以下 EHCI 实现上成功运行（按字母顺序）： +Intel、NEC、Philips 和 VIA。随着其他供应商的 EHCI 实现陆续问世，预计该 +驱动在那些实现上也能正常运行。 -自 2001 年年中起，usb-storage 设备就已可用 -（在 2.4 版该驱动上速度相当不错）， -集线器则直到 2001 年底才开始可用，而其他类型的高速设备 -似乎要等到更多系统内置 USB 2.0 后才会出现。 -这类新系统从 2002 年初开始上市， -并在 2002 年下半年变得更加常见。 +自 2001 年年中起，usb-storage 设备就已可用（在 2.4 版该驱动上速度表现相当 +不错），集线器则直到 2001 年底才开始可用。其他类型的高速设备似乎要等到 +更多系统内置 USB 2.0 后才会出现。这类新系统从 2002 年初开始上市，并在 +2002 年下半年变得更加常见。 -注意，USB 2.0 支持并不只是 EHCI 本身。 -它还需要对 Linux-USB 核心 API 作出其他修改， -包括 hub 驱动；不过这些修改并不需要真正改变 -暴露给 USB 设备驱动的基本 ``usbcore`` API。 +注意，USB 2.0 的支持并不只靠 EHCI 本身。它还需要对 Linux-USB 核心 API +做其他修改，包括 hub 驱动；不过这些修改并不需要真正改变向 USB 设备驱动 +暴露的基本 ``usbcore`` API。 - David Brownell <dbrownell@users.sourceforge.net> @@ -61,58 +53,46 @@ USB 1.1 设备也可以在 USB 2.0 系统上使用。当它们 功能 ==== -该驱动会定期在 x86 硬件上进行测试， -也已在 PPC 硬件上使用，因此大小端问题应当已经解决。 -因此可以认为，它已经处理好了所有必要的 PCI 细节， -所以即便在 DMA 映射有些特殊的系统上， -I/O 也应能正常运行。 +该驱动长期在 x86 硬件上接受测试，也在 PPC 平台上使用过，因此大小端问题应 +该都已解决。再加上各种必要的 PCI 细节都已处理妥当，即便在 DMA 映射较特 +殊的系统上，I/O 也应能正常工作。 传输类型 -------- -截至本文撰写时，该驱动应当已经能够很好地处理 -所有控制传输、批量传输和中断传输， -包括通过 USB 2.0 集线器中的事务转换器 -与 USB 1.1 设备通信；但仍可能存在 bug。 +截至本文撰写时，该驱动应当已经能够稳定处理所有控制传输、批量传输和中断传 +输，包括经由 USB 2.0 集线器里的事务转换器访问 USB 1.1 设备；不过仍可能 +存在 bug。 -高速等时（ISO）传输支持也已可用，但截至本文撰写时， -还没有 Linux 驱动使用这项支持。 +高速等时（ISO）传输支持也已可用，不过截至本文撰写时，还没有 Linux 驱动真 +正使用它。 -目前尚不支持通过事务转换器实现全速等时传输。 -需要注意，ISO 传输的 split transaction 支持 -与高速 ISO 传输几乎无法共用代码， -因为 EHCI 用不同的数据结构表示它们。 -因此，目前大多数 USB 音频和视频设备 -还不能通过高速总线连接使用。 +目前尚不支持通过事务转换器实现全速等时传输。需要注意，ISO 传输的分割 +事务支持与高速 ISO 传输几乎无法共用代码，因为 EHCI 用不同的数据结构表示 +它们。因此，目前大多数 USB 音频和视频设备还无法在高速总线上使用。 驱动行为 -------- -所有类型的传输都可以排队。 -这意味着来自一个接口驱动的控制传输 -（或通过 usbfs 发出的控制传输）不会干扰 -另一个驱动的控制传输，而且中断传输可以使用 1 帧的周期， -而不必担心中断处理开销导致的数据丢失。 +所有类型的传输都可以排队提交。这意味着某个接口驱动发出的控制传输（或经由 +usbfs 提交的控制传输）不会干扰其他驱动的控制传输，而中断传输可以按 1 帧 +周期运行，不必担心中断处理开销导致数据丢失。 -EHCI 根集线器代码会将 USB 1.1 设备移交给其伴随控制器。 -该驱动不需要了解那些驱动的任何细节； -一个原本就能正常工作的 OHCI 或 UHCI 驱动， -并不会因为 EHCI 驱动也存在而需要更改。 +EHCI 根集线器代码会将 USB 1.1 设备交给其伴随控制器处理。该驱动无需了解 +那些驱动的任何细节；一个原本就能正常工作的 OHCI 或 UHCI 驱动，也不会因为 +EHCI 驱动存在而需要修改。 -电源管理方面还有一些问题； -当前挂起/恢复的行为还不完全正确。 +电源管理方面仍有一些问题；当前挂起/恢复行为还不完全正确。 -此外，在调度周期性事务 -（中断和等时传输）时还采取了一些简化处理。 -这些简化会限制可调度的周期性事务数量， -并且无法使用小于一帧的轮询间隔。 +此外，在调度周期性事务（中断和等时传输）时还采取了一些简化处理。这些 +简化会限制可调度的周期性事务数量，并且无法使用小于一帧的轮询间隔。 使用方式 ======== -假设有一个 EHCI 控制器（位于 PCI 卡或主板上）， -并且已将此驱动编译为模块，可这样加载:: +假设系统中有一个 EHCI 控制器（位于 PCI 卡或主板上），并且此驱动是以模块形 +式编译的，那么可以这样加载:: # modprobe ehci-hcd @@ -120,27 +100,24 @@ EHCI 根集线器代码会将 USB 1.1 设备移交给其伴随控制器。 # rmmod ehci-hcd -还应加载一个伴随控制器驱动， -例如 ``ohci-hcd`` 或 ``uhci-hcd``。 -如果 EHCI 驱动出现任何问题，只需卸载它的模块， -随后该伴随控制器驱动就会接手 -此前由 EHCI 驱动处理的所有设备 -（但速度会降低）。 +还应加载一个伴随控制器驱动，例如 ``ohci-hcd`` 或 ``uhci-hcd``。如果 EHCI +驱动出了问题，只要卸载它的模块，伴随控制器驱动就会接管此前由 EHCI 驱动处 +理的全部设备（只是速度会降低）。 模块参数（传给 ``modprobe``）包括： log2_irq_thresh（默认值 0）： - 默认中断延迟的 log2 值，单位是微帧。默认值 0 表示 1 个微帧 - （125 微秒）。最大值 6 表示 2^6 = 64 个微帧。 + 默认中断延迟的 log2 值，单位为微帧。默认值 0 表示 1 个微帧 + （125 微秒），最大值 6 表示 2^6 = 64 个微帧。 该值控制 EHCI 控制器发出中断的频率。 -如果在 2.5 内核上使用此驱动，并且启用了 USB 调试支持， -则会在任一 EHCI 控制器的 ``sysfs`` 目录中看到三个文件： +如果你在 2.5 内核上使用此驱动，并且启用了 USB 调试支持，那么任一 EHCI 控 +制器对应的 ``sysfs`` 目录下都会看到三个文件： ``async`` 转储异步调度，用于控制传输和批量传输。它会显示每个活动的 ``qh`` 以及待处理的 ``qtd``，通常每个 ``urb`` 对应一个 ``qtd``。 - （可以在 ``usb-storage`` 做磁盘 I/O 时看它；顺便观察请求队列！） + （可以在 ``usb-storage`` 执行磁盘 I/O 时查看；也可顺便观察请求队列。） ``periodic`` 转储周期性调度，用于中断传输和等时传输。不显示 ``qtd``。 @@ -151,111 +128,81 @@ EHCI 根集线器代码会将 USB 1.1 设备移交给其伴随控制器。 这些文件的内容有助于定位驱动问题。 -设备驱动通常不需要关心自己是否运行在 EHCI 之上， -但它们可能想检查 -``usb_device->speed == USB_SPEED_HIGH``。 -高速设备能做到全速（或低速）设备做不到的事， -例如高带宽的周期性传输（中断或 ISO 传输）。 -另外，设备描述符中的某些值 -（例如周期性传输的轮询间隔） -在高速模式下使用不同的编码方式。 +设备驱动通常不需要关心自己是否运行在 EHCI 之上，但有时可能会想检查 +``usb_device->speed == USB_SPEED_HIGH``。高速设备能做到全速（或低速）设备 +做不到的事，例如高带宽的周期性传输（中断或 ISO 传输）。另外，设备描述符 +中的某些值（例如周期性传输的轮询间隔）在高速模式下使用不同的编码方式。 -不过，一定要让设备驱动经过 USB 2.0 集线器的测试。 -当使用事务转换器时，这些集线器报告某些故障 -（例如断开连接）的方式会不同； -已经见过一些驱动在遇到与 OHCI 或 UHCI -所报告的不同故障时表现不佳。 +不过，设备驱动一定要在 USB 2.0 集线器后面测一遍。使用事务转换器时，这些 +集线器报告某些故障（例如断开连接）的方式会有所不同；已经见过一些驱动在 +遇到与 OHCI 或 UHCI 不同的故障时表现不佳。 性能 ==== -USB 2.0 吞吐量主要受两个因素制约： -主机控制器处理请求的速度，以及设备响应这些请求的速度。 -480 Mbit/sec 的“原始传输率”对所有设备都成立， -但总吞吐量还会受到诸如单个高速包之间的延迟、 -驱动是否足够聪明，以及系统整体负载等因素的影响。 -延迟也是性能考量因素。 +USB 2.0 的吞吐量主要受两个因素制约：主机控制器处理请求的速度，以及设备响 +应这些请求的速度。480 Mbit/sec 的“原始传输率”对所有设备都一样，但整体吞 +吐量还会受到诸如高速包之间的间隔、驱动实现是否足够高效以及系统总体负载等 +因素影响。延迟同样是需要考虑的性能指标。 -批量传输最常用于关注吞吐量的场景。 -需要记住的是，批量传输总是以 512 字节包为单位， -而一个 USB 2.0 微帧中最多只能容纳 13 个这样的包。 -8 个 USB 2.0 微帧构成一个 USB 1.1 帧； -一个微帧的时长是 1 毫秒 / 8 = 125 微秒。 +批量传输通常用于看重吞吐量的场景。需要记住的是，批量传输总是以 512 字节包 +为单位，而一个 USB 2.0 微帧中最多只能容纳 13 个这样的包。8 个 USB 2.0 微 +帧构成一个 USB 1.1 帧，因此一个微帧的时长就是 125 微秒。 -因此，只要硬件和设备驱动软件都允许， -批量传输可提供超过 50 MByte/sec 的带宽。 -周期性传输模式（等时和中断）允许使用更大的包大小， -从而可以逼近所宣称的 480 Mbit/sec 传输率。 +因此，只要硬件和驱动实现都足够成熟，批量传输就可以提供 50 MByte/sec 以上 +的带宽。周期性传输模式（等时和中断）允许使用更大的包大小，从而可以逼近所 +宣称的 480 Mbit/sec 传输率。 硬件性能 -------- -截至本文撰写时，单个 USB 2.0 设备的最大传输速率 -通常约为 20 MByte/sec。 -这当然会随着时间改变：一些设备现在更快，一些更慢。 +截至本文撰写时，单个 USB 2.0 设备的最大传输速率通常约为 20 MByte/sec。 +这种情况当然会随时间变化：有些设备现在更快，有些则更慢。 -第一代 NEC EHCI 实现似乎存在 -大约 28 MByte/sec 的硬件瓶颈。 -虽然这对单个 20 MByte/sec 的设备显然已经够用， -但把三个这样的设备挂到同一总线上， -并不能得到 60 MByte/sec。 -问题似乎在于控制器硬件无法并发进行 USB 与 PCI 访问， -因此它每个微帧只会尝试 6 次（也许是 7 次） -USB 事务，而不是 13 次。 -（对一个比其他产品早上市一年的芯片来说， -这是个合理的妥协！） +第一代 NEC EHCI 实现似乎存在大约 28 MByte/sec 的硬件瓶颈。虽然这对单个 +20 MByte/sec 的设备显然已经够用，但把三个这样的设备挂到同一总线上，并不 +能得到 60 MByte/sec。问题似乎在于控制器硬件无法并发进行 USB 与 PCI 访问， +因此它每个微帧只会尝试 6 次（也许是 7 次）USB 事务，而不是 13 次。 +（对一款比其他产品早上市一年的芯片来说，这样的取舍也算合理。） -预计较新的实现会在这方面做得更好， -通过投入更多芯片面积来解决这个问题， -使新的主板芯片组更接近 60 MByte/sec 的目标。 -这既包括 NEC 的更新实现，也包括其他厂商的芯片。 +预计较新的实现会在这方面做得更好，通过投入更多芯片面积来解决这个问题， +使新的主板芯片组更接近 60 MByte/sec 的目标。这既包括 NEC 的更新实现，也 +包括其他厂商的芯片。 -主机从 EHCI 控制器收到“请求已完成”中断的最小延迟 -为一个微帧（125 微秒）。该延迟可以调节； -驱动提供了一个模块选项。默认情况下， -``ehci-hcd`` 使用最小延迟，这意味着当发出一个控制 -或批量请求时，通常可以在不到 250 微秒内得知它已完成 -（具体取决于传输大小）。 +主机从 EHCI 控制器收到“请求已完成”中断的最小延迟为一个微帧 +（125 微秒）。该延迟可以调节；驱动提供了一个模块选项。 +默认情况下，``ehci-hcd`` 使用最小延迟，这意味着发出控制或批量请求后，通 +常不到 250 微秒就能得知它已经完成（具体取决于传输大小）。 软件性能 -------- -即便只是要达到 20 MByte/sec 的传输速率， -Linux-USB 设备驱动也必须让 EHCI 队列始终保持满载。 -这意味着要发出较大的请求， -或者在需要发出一连串小请求时使用批量请求排队。 -如果驱动未做到这一点，那么会直接从性能结果上表现出来。 +即便只是要达到 20 MByte/sec 的传输速率，Linux-USB 设备驱动也必须让 EHCI +队列始终保持满载。这意味着要发出较大的请求，或者在需要发出一连串小请求 +时使用批量请求排队。如果驱动做不到这一点，性能就会明显受影响。 -在典型情况下，使用 ``usb_bulk_msg()`` -以 4 KB 块循环写出， -会浪费超过一半的 USB 2.0 带宽。 -I/O 完成与驱动发出下一次请求之间的延迟， -通常会比一次 I/O 本身耗时更长。 -如果同样的循环改用 16 KB 块，会好一些； -若使用一连串 128 KB 块，则浪费会少得多。 +在典型场景下，如果使用 ``usb_bulk_msg()`` 以 4 KB 块循环写出，会浪费超过 +一半的 USB 2.0 带宽。I/O 完成与驱动发出下一次请求之间的空档，往往比一次 +I/O 本身耗时还长。如果同样的循环改用 16 KB 块，情况会好一些；若使用一连串 +128 KB 块，则浪费会少得多。 +但与其依赖这么大的 I/O 缓冲区来提升同步 I/O 的效率，不如直接向主机控制器 +排队提交多个（批量）请求，然后等待它们全部完成（或在出错时取消）。这种 +URB 排队方式对所有 USB 1.1 主机控制器驱动同样适用。 -但与其依赖这么大的 I/O 缓冲区来让同步 I/O 高效， -不如直接向主机控制器排入多个（批量）请求， -然后等待它们全部完成（或在出错时取消）。 -这种 URB 排队方式对所有 USB 1.1 -主机控制器驱动也同样适用。 - -在 Linux 2.5 内核中，定义了新的 ``usb_sg_*()`` API； -它们会把 scatterlist 中的所有缓冲区都排入队列。 -它们还使用 scatterlist 的 DMA 映射 -（其中可能应用 IOMMU）并减少中断次数， -这些都有助于让高速传输尽可能快地运行。 +在 Linux 2.5 内核中，定义了新的 ``usb_sg_*()`` API；它们会把 scatterlist +中的所有缓冲区都排入队列。它们还使用 scatterlist 的 DMA 映射（其中可能 +应用 IOMMU）并减少中断次数，这些都有助于让高速传输尽可能快地运行。 待办： 中断传输和等时（ISO）传输的性能问题。 - 这些周期性传输都是完全调度的，因此，主要问题可能在于如何触发高带宽模式。 + 这些周期性传输都是完全调度的，因此主要问题可能在于如何触发高带宽模式。 待办： - 通过 ``sysfs`` 中的 ``uframe_periodic_max`` 参数， - 可以分配超过标准 80% 的周期性带宽。 + 通过 ``sysfs`` 中的 ``uframe_periodic_max`` 参数，可以分配超过标准 + 80% 的周期性带宽。 后续将对此进行说明。 diff --git a/Documentation/translations/zh_CN/usb/index.rst b/Documentation/translations/zh_CN/usb/index.rst index eb5aca0c13ec..df99814c6497 100644 --- a/Documentation/translations/zh_CN/usb/index.rst +++ b/Documentation/translations/zh_CN/usb/index.rst @@ -1,4 +1,14 @@ .. SPDX-License-Identifier: GPL-2.0 + +.. only:: subproject and latex + + .. raw:: latex + + \renewcommand{\thesection}{} + \renewcommand{\thesubsection}{} + \kerneldocCJKon + \kerneldocBeginSC{ + .. include:: ../disclaimer-zh_CN.rst :Original: Documentation/usb/index.rst @@ -24,7 +34,7 @@ USB 支持 ehci usbmon -Todolist: +待翻译文档： * functionfs * functionfs-desc @@ -52,3 +62,9 @@ Todolist: ==== * :ref:`genindex` + +.. only:: subproject and latex + + .. raw:: latex + + }\kerneldocEndSC diff --git a/Documentation/translations/zh_CN/usb/usbmon.rst b/Documentation/translations/zh_CN/usb/usbmon.rst index 11b6d5b59dce..bbfcbf875e26 100644 --- a/Documentation/translations/zh_CN/usb/usbmon.rst +++ b/Documentation/translations/zh_CN/usb/usbmon.rst @@ -16,67 +16,56 @@ usbmon 简介 ==== -小写形式的 ``usbmon`` 指的是内核中的一项功能， -用于收集 USB 总线上的 I/O 跟踪信息。它类似于网络监控工具 -``tcpdump(1)`` 或 Ethereal 所使用的数据包套接字。 -类似地，人们希望使用 usbdump 或 USBMon -（首字母大写）之类的工具来检查 -usbmon 生成的原始跟踪数据。 - -usbmon 报告的是各个外设驱动 -向主机控制器驱动（HCD）发出的请求。 -因此，如果 HCD 本身有 bug，那么 usbmon 报告的跟踪信息 -可能无法精确对应实际的总线事务。 -这和 tcpdump 的情况是一样的。 - -目前实现了两种 API: ``text`` 和 ``binary``。 -二进制 API 通过 ``/dev`` 命名空间中的字符设备提供， -并且属于 ABI。文本 API 自内核 2.6.35 起已废弃， -但为了方便仍然可用。 +小写的 ``usbmon`` 指的是内核中的一项功能，用于收集 USB 总线上的 I/O 跟踪 +信息。它类似于网络监控工具 ``tcpdump(1)`` 或 Ethereal 使用的数据包套接 +字。通常会用 usbdump 或 USBMon（首字母大写）之类的工具来查看 usbmon 生成 +的原始跟踪数据。 + +usbmon 记录的是各个设备驱动向主机控制器驱动（HCD）发出的请求。因此，如果 +HCD 自身有 bug，usbmon 输出的跟踪信息就未必能和真实的总线事务一一对应。 +这和 tcpdump 的情况类似。 + +目前实现了两种 API：``text`` 和 ``binary``。二进制 API 通过 ``/dev`` 下的 +字符设备提供，是 ABI 的一部分。文本 API 自内核 2.6.35 起已废弃，但为了 +兼容和使用方便，至今仍然保留。 如何使用 usbmon 收集原始文本跟踪信息 ==================================== -与数据包套接字不同，usbmon 提供了一种接口， -可以输出文本格式的跟踪信息。这样做有两个目的： -第一，在更完善的格式最终确定之前， -它作为工具间通用的跟踪交换格式； -第二，在不使用工具的情况下，人们也可以直接阅读这些信息。 +与数据包套接字不同，usbmon 还提供了一个输出文本格式跟踪信息的接口。这样 +做主要有两个目的：一是在更完善的格式最终确定之前，将其作为工具间通用的跟 +踪交换格式；二是在没有工具时也能直接阅读这些信息。 -要收集原始文本跟踪信息，请按以下步骤进行操作。 +要收集原始文本跟踪信息，按下面的步骤做即可。 1. 准备 ------- -挂载 debugfs（内核配置中必须启用它），并加载 usbmon 模块 -（如果它是作为模块构建的）。如果 usbmon 已经编入内核， -那么第二步可以省略。 +挂载 debugfs（内核配置里必须启用它），并加载 usbmon 模块（如果它是以模块 +方式构建的）。如果 usbmon 已经编译进内核，这一步就可以省略。 命令示例:: - # mount -t debugfs none_debugs /sys/kernel/debug + # mount -t debugfs none /sys/kernel/debug # modprobe usbmon # -确认总线套接字是否存在:: +确认 ``usbmon`` 目录下是否有这些条目:: # ls /sys/kernel/debug/usb/usbmon 0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u # -现在，你可以选择使用 ``0u`` 捕获所有总线上的数据包， -并跳到第 3 步； -也可以先按第 2 步找到目标设备所在的总线。 -这样可以过滤掉那些持续输出数据的烦人设备。 +现在，你可以直接用 ``0u`` 捕获所有总线上的数据包，然后跳到第 3 步；也可 +以先按第 2 步找出目标设备所在的总线。这样可以把那些持续产生流量的设备过 +滤掉。 2. 查找目标设备连接的是哪条总线 ------------------------------- -运行 ``cat /sys/kernel/debug/usb/devices``， -找到对应设备的 T 行。通常可以通过厂商字符串来查找。 -如果有许多类似设备，可以拔掉其中一个， -再比较前后两次 ``/sys/kernel/debug/usb/devices`` -的输出。T 行里会包含总线编号。 +运行 ``cat /sys/kernel/debug/usb/devices``，找到对应设备的 T 行。通常可以通过 +厂商字符串来查找。如果有很多相似设备，可以拔掉其中一个，再比较前后两次 +``/sys/kernel/debug/usb/devices`` 的输出。T 行里会包含总线编号。 示例:: @@ -86,8 +75,8 @@ usbmon 报告的是各个外设驱动 S: Manufacturer=ATEN S: Product=UC100KM V2.00 -``Bus=03`` 表示它位于 3 号总线上。或者， -也可以查看 ``lsusb`` 的输出，并从对应行得到总线编号。 +``Bus=03`` 表示它位于 3 号总线上。或者，也可以查看 ``lsusb`` 的输出，并从 +对应条目里找到总线编号。 示例如下:: @@ -97,133 +86,108 @@ usbmon 报告的是各个外设驱动 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 盘、拷贝文件、操作摄像头等。 +这里做一些会产生 USB 流量的操作即可，比如插入 U 盘、拷贝文件、操作摄像头 +等。 5. 停止 cat ----------- -这一步通常通过键盘中断（Control-C）完成。 +这一步通常按下键盘中断（Control-C）即可完成。 -此时输出文件（本例中为 ``/tmp/1.mon.out``） -可以保存、通过电子邮件发送，或使用文本编辑器查看。 -如果使用最后一种方式，请确保文件不会大到编辑器无法打开。 +此时，输出文件（本例中为 ``/tmp/1.mon.out``）可以保存下来，通过电子邮件发 +送，也可以用文本编辑器查看。如果要用文本编辑器查看，请确保文件大小不会 +大到编辑器无法处理。 原始文本数据格式 ================ -目前支持两种格式：原始格式，也就是 ``1t`` 格式， -以及 ``1u`` 格式。``1t`` 格式在内核 2.6.21 中已被废弃。 -``1u`` 格式增加了一些字段，例如 ISO 帧描述符、 -``interval`` 等。它生成的行会稍长一些， -但在其他方面是 ``1t`` 格式的完整超集。 - -如果程序需要区分上述两种格式， -可以查看 ``address`` 字段（见下文）。 -如果其中有两个冒号，就是 ``1t`` 格式； -否则是 ``1u`` 格式。 - -任何文本格式的数据由一系列事件组成， -如 URB 提交、URB 回调、提交错误等。 -每个事件对应单独的一行文本， -由使用空白符间隔的若干字段组成。 -字段的数量与位置可能取决于事件类型， -但以下字段对所有类型都通用： - -下面按从左到右的顺序列出这些共有字段： - -- URB Tag。用于标识 URB，通常是 URB 结构体在内核中的地址 - （以十六进制表示）， - 但也可能是序号或其他合理的唯一字符串。 - -- 时间戳（微秒），十进制数字。 - 时间戳的精度取决于可用时钟， - 因此可能远差于 - 1 微秒（例如实现使用的是 jiffies）。 - -- 事件类型。它表示的是事件的格式，而不是 URB 的类型。 - 可用值为：``S`` 表示提交，``C`` 表示回调，``E`` 表示提交错误。 - -- ``Address`` 字段（以前称作 ``pipe``）。 - 它包含四个由冒号分隔的字段： - URB 类型及方向、总线号、设备地址和端点号。类型与方向的编码如下： - - == == ========================== - Ci Co 控制输入和输出 - Zi Zo 等时输入和输出 - Ii Io 中断输入和输出 - Bi Bo 批量输入和输出 - == == ========================== - - 总线号、设备地址和端点号使用十进制，但可能有前导零。 - -- URB 状态字段。这个字段要么是一个字母， - 要么是几个由冒号分隔的数字： - URB 状态、``interval``、``start frame`` 和 ``error count``。 - 与 ``address`` 字段不同，除了状态外，其余字段都是可选的。 - ``interval`` 只会为中断和等时 URB 打印；``start frame`` 只会为 - 等时 URB 打印；错误计数只会在等时回调事件中打印。 - - 状态字段是一个十进制数字，有时为负数， - 对应 URB 的 ``status`` 字段。 - 对于提交事件，这个字段本身没有实际意义， - 但为了便于脚本解析，它仍然存在。 - 当发生错误时，该字段包含错误码。 - - 在提交控制包时，这个字段包含的是 ``Setup Tag``， - 而不是一组数字。 - 判断 ``Setup Tag`` 是否存在很容易，因为它从来不是数字。 - 因此，如果脚本在这个字段里发现的是一组数字， - 就会继续读取数据长度（等时 URB 除外）。 - 如果发现的是其他内容，比如一个字母， - 那么脚本会先读取 ``Setup`` 包，再读取数据长度或等时描述符。 - -- ``Setup`` 包由 5 个字段组成： - ``bmRequestType``、``bRequest``、``wValue``、 - ``wIndex`` 和 ``wLength``。这些字段由 USB 2.0 规范定义。 - 如果 ``Setup Tag`` 为 ``s``，就可以安全地解码这些字段。 - 否则，说明 Setup 包虽然存在，但并未被捕获，此时各字段中会填入占位内容。 +目前支持两种格式：原始的 ``1t`` 格式和 ``1u`` 格式。``1t`` 格式在内核 +2.6.21 中已被废弃。``1u`` 格式增加了一些字段，例如 ISO 帧描述符和 +``interval``。它生成的行会稍长一些，但除此之外，它是 ``1t`` 格式的完整 +超集。 + +如果程序需要区分上述两种格式，可以查看 ``address`` 字段（见下文）。如果 +其中有两个冒号，就是 ``1t`` 格式；否则是 ``1u`` 格式。 + +任何文本格式的数据都由一系列事件构成，例如 URB 提交、URB 回调和提交错 +误。每个事件占一行，由若干以空白符分隔的字段组成。字段数量和位置会随事件 +类型变化，但下面这些字段对所有类型都通用： + +下面按从左到右的顺序说明这些通用字段： + +- URB 标识（URB Tag）。用于标识 URB，通常是 URB 结构体在内核中的地址 + （十六进制），也可能是序号或其他足以唯一标识 URB 的字符串。 + +- 时间戳（微秒），十进制数字。时间戳的精度取决于可用时钟，所以可能远低于 + 1 微秒（例如实现使用 jiffies 时）。 + +- 事件类型。它表示的是这一行事件的格式，而不是 URB 的类型。可用值为： + ``S`` 表示提交，``C`` 表示回调，``E`` 表示提交错误。 + +- ``Address`` 字段（以前称为 ``pipe``）。它包含四个由冒号分隔的字段：URB + 类型及方向、总线号、设备地址和端点号。类型与方向的编码如下： + + - ``Ci`` / ``Co``：控制输入 / 输出 + - ``Zi`` / ``Zo``：等时输入 / 输出 + - ``Ii`` / ``Io``：中断输入 / 输出 + - ``Bi`` / ``Bo``：批量输入 / 输出 + + 总线号、设备地址和端点号都是十进制数，但可能有前导零，方便人阅读。 + +- URB 状态字段。这个字段要么是一个字母，要么是几个用冒号分隔的数字，依次 + 表示 URB 状态、``interval``、``start frame`` 和 ``error count``。与 + ``address`` 字段不同，除状态外，其余字段都可能省略。``interval`` 只会在 + 中断和等时 URB 中打印；``start frame`` 只会在等时 URB 中打印；错误计数只 + 会在等时回调事件中打印。 + + 状态字段是一个十进制数，有时为负数，对应 URB 的 ``status`` 字段。对于提 + 交事件，这个字段本身并无实际语义，但为了便于脚本解析仍会保留。发生错误 + 时，这里填的是错误码。 + + 如果是控制包的提交事件，这个字段里放的不是一组数字，而是 ``Setup Tag``。 + 这很容易分辨，因为 ``Setup Tag`` 永远不是数字。所以脚本如果在这里读到一 + 组数字，就会继续读取数据长度（等时 URB 除外）；如果读到的是字母之类的内 + 容，就要先读取 ``Setup`` 包，再读取数据长度或等时描述符。 + +- ``Setup`` 包由 5 个字段组成：``bmRequestType``、``bRequest``、``wValue``、 + ``wIndex`` 和 ``wLength``。这些字段由 USB 2.0 规范定义。如果 ``Setup Tag`` + 是 ``s``，就可以安全解码这些字段。否则，说明 Setup 包虽然存在，但并未被 + 捕获，此时各字段中会填入占位内容。 - 等时传输帧描述符的数量及其内容： - 如果一个等时传输事件带有一组描述符，首先打印该 URB 中描述符的总数， - 然后为每个描述符打印一个字段，最多打印 5 个字段。 - 每个字段由三个用冒号分隔的十进制数字组成， - 分别表示状态（status）、偏移（offset）和长度（length）。 - 对于提交（submission），报告的是初始长度； - 对于回调（callback），报告的是实际长度。 + 如果某个等时传输事件带有描述符，会先打印该 URB 的描述符总数，再为每个描 + 述符打印一个字段，最多 5 个。每个字段由三个用冒号分隔的十进制数组成，依 + 次表示状态（status）、偏移（offset）和长度（length）。对于提交事件，报 + 告的是初始长度；对于回调事件，报告的是实际长度。 -- 数据长度： - 对于提交，表示请求的长度；对于回调，表示实际传输的长度。 +- 数据长度：对于提交，表示请求的长度；对于回调，表示实际传输的长度。 -- 数据标签： - 即使数据长度非零，usbmon 也不一定会捕获数据。 - 仅当标签为 ``=`` 时，才会有数据字段。 +- 数据标签：即使数据长度非零，usbmon 也不一定会捕获数据。只有标签为 + ``=`` 时，才会有数据字段。 -- 数据字段： - 以大端十六进制格式显示。注意，这些并不是真正的机器字， - 而只是把字节流拆成若干“字”以便阅读。因此最后一个字可能只包含 - 1 到 4 个字节。 - 收集的数据长度是有限的，可能小于数据长度字段中报告的值。 - 因为数据长度字段只统计实际接收到的字节，而数据字段包含整个传输缓冲区， - 所以，在等时输入（Zi）完成且缓冲区中接收到的数据稀疏的情况下， - 收集的数据长度可能大于数据长度字段的值。 +- 数据字段：以大端十六进制格式显示。注意，这些并不是真正的机器字，只是为 + 了便于阅读，把字节流按“字”分组显示。因此最后一个字可能只包含 1 到 4 个 + 字节。捕获的数据长度是有限的，可能小于数据长度字段中报告的值。对于等时 + 输入（Zi）完成事件，如果缓冲区里的接收数据比较稀疏，捕获数据的长度甚至 + 可能大于数据长度字段，因为后者只统计实际接收到的字节，而数据字段展示的 + 是整个传输缓冲区。 @@ -234,18 +198,16 @@ usbmon 报告的是各个外设驱动 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``）的输出批量传输:: +向地址为 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 的整体架构与前文大体相同，只是事件以二进制格式传递。 -每个事件都通过下面的结构发送 -（这个名字是为了叙述方便而虚构的）:: +API 的整体架构与前文大体相同，只是事件以二进制格式传递。每个事件都通过 +下面的结构发送（这个结构名只是为了叙述方便而虚构的）:: struct usbmon_packet { @@ -275,29 +237,22 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 unsigned int ndesc; /* 60: 实际 ISO 描述符数量 */ }; /* 64 总长度 */ -可以用 ``read(2)``、``ioctl(2)``， -或者通过 ``mmap`` 访问缓冲区， -从字符设备接收这些事件。 -不过，出于兼容性原因，``read(2)`` -只返回前 48 个字节。 +可以用 ``read(2)``、``ioctl(2)``，或者通过 ``mmap`` 访问缓冲区，从字符设 +备接收这些事件。不过，出于兼容性原因，``read(2)`` 只返回前 48 个字节。 -字符设备通常命名为 ``/dev/usbmonN``， -其中 ``N`` 是 USB 总线号。 -编号为零的设备（``/dev/usbmon0``）比较特殊， -表示“所有总线”。 -请注意，具体命名策略由 Linux 发行版决定。 +字符设备通常命名为 ``/dev/usbmonN``，其中 ``N`` 是 USB 总线号。编号为零的 +设备（``/dev/usbmon0``）比较特殊，表示“所有总线”。具体命名策略由 Linux +发行版决定。 -如果你手动创建 ``/dev/usbmon0``， -请确保它归 root 所有，并且权限为 ``0600``。 -否则，非特权用户将能够窃听键盘流量。 +如果你手动创建 ``/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)`` @@ -309,31 +264,28 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 u32 dropped; }; -成员 ``queued`` 表示当前缓冲区中已经排队的事件数量， -而不是自上次重置以来处理过的事件数量。 +成员 ``queued`` 表示当前缓冲区中已经排队的事件数量，而不是自上次重置以来 +处理过的事件数量。 -成员 ``dropped`` 表示自上次调用 -``MON_IOCG_STATS`` 以来丢失的事件数量。 +成员 ``dropped`` 表示自上次调用 ``MON_IOCG_STATS`` 以来丢失的事件数量。 ``MON_IOCT_RING_SIZE``，定义为 ``_IO(MON_IOC_MAGIC, 4)`` -此调用设置缓冲区大小。参数为以字节为单位的缓冲区大小。 -大小可能会向下取整到下一个块（或页）。 -如果请求的大小超出该内核的 [未指定] 范围， -则调用会失败并返回 ``-EINVAL``。 +此调用设置缓冲区大小。参数是以字节为单位的缓冲区大小。大小可能会向下取整 +到下一个块（或页）。如果请求的大小超出当前内核允许的范围，则调用会失败并 +返回 ``-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)`` +``MON_IOCX_GET`` 和 ``MON_IOCX_GETX`` 的定义分别如下： + +- ``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 { @@ -343,20 +295,18 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 }; -调用前，应填好 ``hdr``、``data`` 和 ``alloc``。 -调用返回后，``hdr`` 指向的区域中包含下一个事件的结构； -如果存在数据，那么数据缓冲区中也会包含相应数据。 -该事件会从内核缓冲区中移除。 +调用前，应填好 ``hdr``、``data`` 和 ``alloc``。调用返回后，``hdr`` 指向的 +内存区域中会写入下一个事件的结构；如果存在数据，数据缓冲区中也会填入相应 +内容。该事件会从内核缓冲区中移除。 -``MON_IOCX_GET`` 会将 48 字节的数据复制到 ``hdr`` 区域， -``MON_IOCX_GETX`` 会复制 64 字节。 +``MON_IOCX_GET`` 会将 48 字节的数据复制到 ``hdr`` 区域，``MON_IOCX_GETX`` +会复制 64 字节。 ``MON_IOCX_MFETCH``，定义为 ``_IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg)`` -当应用程序通过 ``mmap(2)`` 访问缓冲区时， -主要使用这个 ioctl。 -其参数是指向以下结构的指针:: +应用程序通过 ``mmap(2)`` 访问缓冲区时，主要使用这个 ioctl。其参数是指向 +以下结构的指针:: struct mon_mfetch_arg { uint32_t *offvec; /* 获取的事件偏移向量 */ @@ -365,41 +315,36 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 }; -该 ioctl 的操作分为三个阶段： +这个 ioctl 的流程分为三个阶段： -首先，从内核缓冲区移除并丢弃最多 ``nflush`` 个事件。 -实际丢弃的事件数量会写回 ``nflush``。 +首先，从内核缓冲区移除并丢弃最多 ``nflush`` 个事件。实际丢弃的事件数量会 +写回 ``nflush``。 -其次，除非伪设备以 ``O_NONBLOCK`` 打开，否则会一直等待， -直到缓冲区中出现事件。 +其次，除非设备以 ``O_NONBLOCK`` 打开，否则会一直等待，直到缓冲区中出现 +事件。 -第三，将最多 ``nfetch`` 个偏移量提取到 mmap -缓冲区，并存入 ``offvec`` 中。 -实际提取到的事件偏移数量会存回 ``nfetch``。 +第三，将最多 ``nfetch`` 个偏移量提取到 mmap 缓冲区，并存入 ``offvec`` 中。 +实际提取到的事件偏移数量会写回 ``nfetch``。 ``MON_IOCH_MFLUSH``，定义为 ``_IO(MON_IOC_MAGIC, 8)`` -此调用从内核缓冲区移除若干事件。 -其参数为要移除的事件数量。 -如果缓冲区中的事件少于请求数量， -则移除所有事件，且不报告错误。 -当没有事件时也可使用。 +此调用从内核缓冲区移除若干事件。其参数是要移除的事件数量。如果缓冲区中的 +事件少于请求数量，则移除全部现有事件，且不报告错误。即使当前没有事件，也 +可以调用。 ``FIONBIO`` 如果有需要，将来可能会实现 ``FIONBIO`` ioctl。 -除了 ``ioctl(2)`` 和 ``read(2)`` 之外， -二进制 API 的特殊文件也可以用 ``select(2)`` 和 -``poll(2)`` 轮询。 -但 ``lseek(2)`` 不起作用。 +除了 ``ioctl(2)`` 和 ``read(2)`` 之外，二进制 API 对应的特殊文件还可以用 +``select(2)`` 和 ``poll(2)`` 轮询，但 ``lseek(2)`` 不可用。 * 二进制 API 的内核缓冲区内存映射访问 -基本思想很简单： +基本思路很简单： -准备时，先获取当前大小，再用 ``mmap(2)`` 映射缓冲区。 -然后执行类似下面伪代码的循环:: +准备时，先查询当前大小，再用 ``mmap(2)`` 映射缓冲区。之后运行与下面伪代码 +类似的循环:: struct mon_mfetch_arg fetch; struct usbmon_packet *hdr; @@ -411,7 +356,7 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 ioctl(fd, MON_IOCX_MFETCH, &fetch); // 同时处理错误 nflush = fetch.nfetch; // 完成后要刷新这么多包 for (i = 0; i < nflush; i++) { - hdr = (struct ubsmon_packet *) &mmap_area[vec[i]]; + hdr = (struct usbmon_packet *) &mmap_area[vec[i]]; if (hdr->type == '@') // 填充包 continue; caddr_t data = &mmap_area[vec[i]] + 64; @@ -421,7 +366,7 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 -因此，主要思想是每 N 个事件只执行一次 ioctl。 +因此，这里的核心思路就是每 N 个事件只执行一次 ioctl。 -虽然缓冲区是环形的，但返回的头和数据不会跨越缓冲区末端， -因此上面的伪代码无需任何合并操作。 +虽然缓冲区是环形的，但返回的头部和数据不会跨越缓冲区末端，因此上面的伪代 +码无需做任何拼接。 -- 2.34.1 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v3] docs/zh_CN: usb: refine translated wording and formatting 2026-06-01 3:39 ` [PATCH v3] docs/zh_CN: usb: refine translated wording and formatting Kefan Bai @ 2026-06-01 4:00 ` Alex Shi 2026-06-01 6:19 ` Kefan Bai 2026-06-01 8:26 ` [PATCH v4] " Kefan Bai 1 sibling, 1 reply; 5+ messages in thread From: Alex Shi @ 2026-06-01 4:00 UTC (permalink / raw) To: Kefan Bai, linux-usb, si.yanteng, gregkh Cc: dzm91, corbet, skhan, linux-doc, linux-kernel, doubled, alexs Hi Kefan, It looks fine. BTW, like any other kernel patches, document patch also requires a line length limit of either 80 or 100 English characters per line (which corresponds to 40 or 50 Chinese characters). Within the same document, you should keep it consistent by using either the 80-character or the 100-character limit throughout. You should try your best to align your patch accordingly, as this makes it look much cleaner and more readable. To make this easier, you can use a text editor with a column indicator (ruler) to help you align the text, or you can use the command :set cc=80 in Vim to check your formatting. Thanks Alex On 2026/6/1 11:39, Kefan Bai wrote: > Refine the zh_CN USB translations for clarity and consistency. > > Improve wording, wrapping, and formatting across the translated > USB documents. > > Link:https://lore.kernel.org/r/2026053149-flaky-shallow-2460@gregkh > Suggested-by: Alex Shi<seakeel@gmail.com> > Signed-off-by: Kefan Bai<baikefan@leap-io-kernel.com> > --- > v3: > - refine the subject and commit message > - add a Link trailer to the cleanup request thread > - move revision notes below the cut line > > v2: > - replace the obsolete FSF mailing address reference in acm.rst > - trim the commit message to satisfy checkpatch > > Documentation/translations/zh_CN/usb/CREDITS | 146 ++++--- > Documentation/translations/zh_CN/usb/acm.rst | 62 ++- > .../translations/zh_CN/usb/authorization.rst | 79 ++-- > .../translations/zh_CN/usb/chipidea.rst | 58 ++- > Documentation/translations/zh_CN/usb/dwc3.rst | 37 +- > Documentation/translations/zh_CN/usb/ehci.rst | 247 +++++------- > .../translations/zh_CN/usb/index.rst | 18 +- > .../translations/zh_CN/usb/usbmon.rst | 363 ++++++++---------- > 8 files changed, 442 insertions(+), 568 deletions(-) > > diff --git a/Documentation/translations/zh_CN/usb/CREDITS b/Documentation/translations/zh_CN/usb/CREDITS > index c133b1a5daff..a37958d139cc 100644 > --- a/Documentation/translations/zh_CN/usb/CREDITS > +++ b/Documentation/translations/zh_CN/usb/CREDITS > @@ -10,12 +10,10 @@ > :校译: > > > -简易 Linux USB 驱动的致谢名单： > +Simple Linux USB 驱动项目致谢名单： > > -以下人员都为 Linux USB 驱动代码作出了贡献 > -（按姓氏字母顺序排列）。我相信这份名单本应 > -更长一些，但确实不容易维护。 > -如需将自己加入名单，请提交补丁。 > +以下人员都为 Linux USB 驱动代码作出过贡献（按姓氏字母顺序排列）。这份名 > +单本该更长，只是确实不易维护；如果你也应列名其中，欢迎提交补丁把自己加上。 > > Georg Acher<acher@informatik.tu-muenchen.de> > David Brownell<dbrownell@users.sourceforge.net> > @@ -41,123 +39,123 @@ > 特别感谢： > > Inaky Perez Gonzalez<inaky@peloncho.fis.ucm.es> > - 感谢他发起了 Linux USB 驱动开发工作，并编写了体量较大的 uusbd > - 驱动中的大部分代码。我们从那项工作中学到了很多。 > + 感谢他牵头开发 Linux USB 驱动，并编写了 uusbd 驱动的大部分代码，我们 > + 从中学到了很多。 > > NetBSD 和 FreeBSD 的 USB 开发者们 > 感谢他们加入 Linux USB 邮件列表，提供建议并分享实现经验。 > > -附加感谢： > - 还要感谢以下公司与个人在硬件、支持、时间投入和开发方面提供的捐赠与帮助 > - （摘自 Inaky 驱动原始的 THANKS 文件）： > +另外还要感谢： > > - 以下公司曾帮助我们开发 Linux USB / UUSBD： > + 以下公司和个人在硬件、支持、时间和开发工作上给予了帮助（摘自 Inaky > + 驱动原始的 THANKS 文件）： > > - - 3Com GmbH 捐赠了一台 ISDN Pro TA，并在技术问题和测试设备方面为我 > - 提供支持。没想到能得到这么大的帮助。 > + 以下公司曾为 Linux USB / UUSBD 的开发提供帮助： > > - - USAR Systems 向我们提供了他们出色的 USB 评估套件， > - 使我们能够测试 Linux USB 驱动对最新 USB 规范的符合性。 > - USAR Systems 认识到保持开放操作系统与时俱进的重要性， > - 并以硬件支持这个项目。感谢！ > + - 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 实现。 > + - CMD Technology, Inc. 慷慨捐赠了一块 CSA-6700 PCI 转 USB 控制卡， > + 用于测试 OHCI 实现。 > > - - 由于他们对我们的支持，Keytronic 可以放心， > - 他们的键盘能卖给至少 300 万 Linux 用户中的一部分。 > + - 有了他们的支持，Keytronic 至少可以确信，其键盘能够销售给 300 万 > + Linux 用户中的一部分。 > > - - ing büro h doran [http://www.ibhdoran.com]! > - 在欧洲，想给主板买一个 PC 背板 USB 连接器几乎是不可能的 > - （我自己做的那个相当糟糕 :)）。现在我知道该去哪里买漂亮的 USB > - 配件了！ > + - 特别感谢 ing büro h doran [http://www.ibhdoran.com]。 > + 在欧洲，想给主板配一个 PC 背板 USB 连接器几乎是不可能的（我自己 > + 做的那个效果并不好）。现在我知道该去哪里购买合适的 USB 配件了。 > > - Genius Germany 捐赠了一只 USB 鼠标，用于测试鼠标启动协议； > - 他们还捐赠了 F-23 数字摇杆和 NetMouse Pro。感谢！ > + 他们还捐赠了 F-23 数字摇杆和 NetMouse Pro，在此致谢。 > > - - AVM GmbH Berlin 支持我们开发 Linux 下的 AVM ISDN Controller B1 USB 驱动。 > - AVM 是领先的 ISDN 控制器制造商，其主动式设计对包括 Linux 在内的 > - 所有操作系统平台开放。 > + - AVM GmbH Berlin 支持我们开发 Linux 下的 AVM ISDN Controller B1 USB > + 驱动。AVM 是领先的 ISDN 控制器制造商，其开放式设计适用于包括 > + Linux 在内的所有操作系统平台。 > > - - 非常感谢 Y-E Data, Inc 捐赠的 FlashBuster-U USB 软驱， > - 使我们能够测试批量传输代码。 > + - 非常感谢 Y-E Data, Inc 捐赠的 FlashBuster-U USB 软驱，使我们能够测试 > + 批量传输代码。 > > - 感谢 Logitech 捐赠了一只三轴 USB 鼠标。 > > - Logitech 负责设计、制造并销售各种人机接口设备， > - 在键盘、鼠标、轨迹球、摄像头、扬声器，以及面向游戏和专业用途的 > - 控制设备方面拥有悠久历史和丰富经验。 > + Logitech 负责设计、制造并销售各种人机接口设备，在键盘、鼠标、轨迹球、 > + 摄像头、扬声器，以及面向游戏和专业用途的控制设备方面拥有悠久历史和 > + 丰富经验。 > > - 作为这些设备广为人知的供应商和销售商，他们捐赠了 USB 鼠标、 > - 摇杆和扫描仪，以表明 Linux 的重要性，也让 Logitech 的客户 > - 能在自己喜欢的操作系统上获得支持，并让所有 Linux 用户都能使用 > - Logitech 以及其他 USB 硬件。 > + 作为这些设备广为人知的供应商和销售商，他们捐赠了 USB 鼠标、摇杆和 > + 扫描仪，以表明 Linux 的重要性，也让 Logitech 的客户能在自己偏爱的 > + 操作系统上获得支持，并让所有 Linux 用户都能使用 Logitech 及其他 > + USB 硬件。 > > Logitech 也是 1999 年 2 月 11 日维也纳 Linux 大会的官方赞助商， > 我们将在会上展示 Linux USB 工作的最新进展。 > > - - 感谢 CATC 提供 USB Inspector，帮助我们揭开 UHCI 内部实现中 > - 那些不为人知的角落。 > + - 感谢 CATC 提供 USB Inspector，帮助我们看到 UHCI 内部实现中的那些 > + 隐秘角落。 > > - 感谢 Entrega 为开发工作提供 PCI 转 USB 卡、集线器和转换器产品。 > > - - 感谢 ConnectTech 提供 WhiteHEAT USB 转串口转换器以及相关文档， > - 让这个驱动得以写成。 > + - 感谢 ConnectTech 提供 WhiteHEAT USB 转串口转换器以及相关文档，让 > + 这个驱动得以写成。 > > - - 感谢 ADMtek 提供 Pegasus 和 Pegasus II 评估板、规格说明， > - 以及驱动开发过程中的宝贵建议。 > + - 感谢 ADMtek 提供 Pegasus 和 Pegasus II 评估板、规格说明，以及驱动 > + 开发过程中的宝贵建议。 > > - 另外还要感谢以下个人（嘿，顺序不分先后 :)） > + 另外还要感谢以下个人（排名不分先后）： > > - - Oren Tirosh<orenti@hishome.net>, > - 他非常耐心地听我唠叨各种 USB 疑问，还给了很多很酷的想法。 > + - Oren Tirosh<orenti@hishome.net> > + 他非常耐心地解答我反复提出的各种 USB 问题，并提供了许多有价值的 > + 想法。 > > - - Jochen Karrer<karrer@wpfd25.physik.uni-wuerzburg.de>, > - 指出了致命 bug，并给出了宝贵建议。 > + - Jochen Karrer<karrer@wpfd25.physik.uni-wuerzburg.de> > + 指出了严重问题，并给出了宝贵建议。 > > - - Edmund Humemberger<ed@atnet.at>，他在公共关系与项目管理方面 > - 为 Linux-USB 项目付出了巨大的努力。 > + - Edmund Humemberger<ed@atnet.at>，他在公共关系与项目管理方面为 > + Linux-USB 项目付出了巨大的努力。 > > - - Alberto Menegazzi<flash@flash.iol.it> 正在着手编写 UUSBD 文档，加油！ > + - Alberto Menegazzi<flash@flash.iol.it> 正在着手编写 UUSBD 文档。 > > - - Ric Klaren<ia_ric@cs.utwente.nl> 编写了很好的入门文档， > - 与 Alberto 的作品形成良性竞争：）。 > + - Ric Klaren<ia_ric@cs.utwente.nl> 编写了很好的入门文档，与 > + Alberto 的作品形成了良性互补。 > > - - Christian Groessler<cpg@aladdin.de>，感谢他在那些棘手细节上的帮助。 > + - Christian Groessler<cpg@aladdin.de>，感谢他在诸多复杂细节上的帮助。 > > - - Paul MacKerras 改进了 OHCI 实现，推动了对 iMac 的支持， > - 并提供了大量的改进意见。 > + - Paul MacKerras 改进了 OHCI 实现，推动了对 iMac 的支持，并提供了 > + 大量的改进意见。 > > - - Fernando Herrera<fherrera@eurielec.etsit.upm.es> > - 负责撰写、维护并不断补充那份期待已久、独一无二又精彩的 > - UUSBD FAQ！太棒了！ > + - Fernando Herrera<fherrera@eurielec.etsit.upm.es> 负责撰写、维护并 > + 持续补充那份期待已久、内容翔实的 UUSBD FAQ。 > > - - Rasca Gmelch<thron@gmx.de> 重新启用了 raw 驱动， > - 指出了一些错误，并启动了 uusbd-utils 软件包。 > + - Rasca Gmelch<thron@gmx.de> 重新启用了 raw 驱动，指出了一些错误，并 > + 启动了 uusbd-utils 软件包。 > > - - Peter Dettori<dettori@ozy.dec.com>，像疯了一样挖掘 bug， > - 还提出了很多很酷的建议，太棒了！ > + - Peter Dettori<dettori@ozy.dec.com>，持续发现问题，并提出了许多 > + 有价值的建议。 > > - - 自由软件与 Linux 社区的所有成员，包括 FSF、GNU 项目、 > - MIT X 联盟、TeX 社区等等，谢谢你们！ > + - 自由软件与 Linux 社区的所有成员，包括 FSF、GNU 项目、MIT X 联盟、 > + TeX 社区等，在此一并致谢。 > > - - 特别感谢 Richard Stallman 创造了 Emacs！ > + - 特别感谢 Richard Stallman 创造了 Emacs。 > > - - 感谢 linux-usb 邮件列表的所有成员，读了那么多邮件——不开玩笑了， > - 感谢你们提出的所有建议！ > + - 感谢 linux-usb 邮件列表的所有成员阅读了大量邮件，并提出了诸多 > + 建议。 > > - 感谢 USB Implementers Forum 成员们的帮助与支持。 > > - - Nathan Myers<ncm@cantrip.org>，感谢他的建议！ > - （希望你喜欢 Cibeles 的派对。） > + - Nathan Myers<ncm@cantrip.org>，感谢他的建议。（也希望你喜欢 > + Cibeles 的派对。） > > - - 感谢 Linus Torvalds 创建、开发并管理 Linux。 > + - 感谢 Linus Torvalds 创立、开发并维护 Linux。 > > - Mike Smith、Craig Keithley、Thierry Giron 和 Janet Schank > - 感谢他们让我认识到标准 USB 集线器其实也没那么“标准”， > - 这有助于我们在标准集线器驱动中加入厂商特定的特殊处理。 > + 感谢他们让我认识到，标准 USB 集线器其实一点也不“标准”；也正因 > + 如此，我们才能在标准集线器驱动中加入厂商特定的处理。 > diff --git a/Documentation/translations/zh_CN/usb/acm.rst b/Documentation/translations/zh_CN/usb/acm.rst > index 51d6eb8f5660..b2e35787af45 100644 > --- a/Documentation/translations/zh_CN/usb/acm.rst > +++ b/Documentation/translations/zh_CN/usb/acm.rst > @@ -20,33 +20,26 @@ Linux ACM 驱动 v0.16 > > 0. 免责声明 > ~~~~~~~~~~~ > -本程序是自由软件；你可以在自由软件基金会发布的 > -GNU 通用公共许可证第 2 版，或者（按你的选择） > -任何后续版本的条款下重新发布和/或修改它。 > +本程序是自由软件；你可以在自由软件基金会发布的 GNU 通用公共许可证第 2 版， > +或者（按你的选择）任何后续版本的条款下重新发布和/或修改它。 > > -发布本程序是希望它能发挥作用，但它不附带任何担保； > -甚至不包括对适销性或特定用途适用性的默示担保。 > -详情见 GNU 通用公共许可证。 > +发布本程序是希望它能发挥作用，但它不附带任何担保；甚至不包括对适销性或 > +特定用途适用性的默示担保。详情见 GNU 通用公共许可证。 > > -你应该已经随本程序收到了 GNU 通用公共许可证的副本； > -如果没有，请致信：Free Software Foundation, Inc., 59 > -Temple Place, Suite 330, Boston, MA 02111-1307 USA。 > +你应该已经随本程序收到了 GNU 通用公共许可证的副本；如果没有，请参见 > +COPYING 文件。 > > -如需联系作者，可发送电子邮件至vojtech@suse.cz， > -或邮寄至： > -Vojtech Pavlik, Ucitelska 1576, Prague 8, > -182 00, Czech Republic。 > +如需联系作者，可发送电子邮件至vojtech@suse.cz，或邮寄至： > +Vojtech Pavlik, Ucitelska 1576, Prague 8, 182 00, Czech Republic。 > > -为方便起见，软件包中已附带 GNU 通用公共许可证 > -第 2 版：见 COPYING 文件。 > +为方便起见，软件包中已附带 GNU 通用公共许可证第 2 版：见 COPYING 文件。 > > 1. 使用方法 > ~~~~~~~~~~~ > -``drivers/usb/class/cdc-acm.c`` 驱动可用于符合 USB > -通信设备类抽象控制模型（USB CDC ACM）规范的 > -USB 调制解调器和 USB ISDN 终端适配器。 > +``drivers/usb/class/cdc-acm.c`` 驱动适用于符合 USB 通信设备类抽象控制模型 > +（USB CDC ACM）规范的 USB 调制解调器和 USB ISDN 终端适配器。 > > -许多调制解调器支持此驱动，以下是我所知道的一些型号： > +已知支持该驱动的调制解调器包括： > > - 3Com OfficeConnect 56k > - 3Com Voice FaxModem Pro > @@ -56,17 +49,16 @@ USB 调制解调器和 USB ISDN 终端适配器。 > - Compaq 56k FaxModem > - ELSA Microlink 56k > > -我知道有一款 ISDN 终端适配器可以与 ACM 驱动一起使用： > +已知有一款 ISDN 终端适配器可以配合 ACM 驱动使用： > > - 3Com USR ISDN Pro TA > > -一些手机也可以通过 USB 连接。 > -我知道以下机型可以正常工作： > +一些手机也可以通过 USB 连接，已知可用的机型有： > > - SonyEricsson K800i > > -遗憾的是，许多调制解调器和大多数 ISDN TA > -都使用专有接口，因此无法与此驱动配合工作。 > +遗憾的是，很多调制解调器和大多数 ISDN TA 都使用专有接口，因此无法配合该 > +驱动工作。 > 购买前请先确认设备是否符合 ACM 规范。 > > 要使用这些调制解调器，需要加载以下模块:: > @@ -75,15 +67,13 @@ USB 调制解调器和 USB ISDN 终端适配器。 > uhci-hcd.ko ohci-hcd.ko or ehci-hcd.ko > cdc-acm.ko > > -之后就应该可以访问这些调制解调器了。 > -应当可以使用 ``minicom``、``ppp`` 和 ``mgetty`` > -与它们通信。 > +之后就应该能访问这些调制解调器，并用 ``minicom``、``ppp`` 和 > +``mgetty`` 与它们通信。 > > 2. 验证驱动是否正常工作 > ~~~~~~~~~~~~~~~~~~~~~~~ > > -第一步是检查 ``/sys/kernel/debug/usb/devices``， > -其内容应该类似如下:: > +第一步是查看 ``/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 > @@ -112,11 +102,10 @@ USB 调制解调器和 USB ISDN 终端适配器。 > 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.)``，那就无能为力了： > -这说明你手上的设备使用的是厂商专有接口:: > +关键是看这三行，再结合 ``Cls=`` 字段里出现的 ``comm`` 和 ``data`` 类，就 > +能判断这是一台 ACM 设备。``Driver=acm`` 表示该设备正在使用 acm 驱动。如果 > +只看到 ``Cls=ff(vend.)``，那就说明这台设备使用的是厂商专有接口，ACM 驱动 > +无法处理:: > > 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 > @@ -142,6 +131,5 @@ USB 调制解调器和 USB ISDN 终端适配器。 > usb.c: acm driver claimed interface c7b5f3f8 > usb.c: acm driver claimed interface c7691fa0 > > -如果以上都正常，请启动 ``minicom``， > -把它配置为连接 ``ttyACM`` 设备，然后 > -尝试输入 ``at``。如果返回 ``OK``，说明一切工作正常。 > +如果这些都正常，请启动 ``minicom``，把它配置为连接到 ``ttyACM`` 设备，然后 > +尝试输入 ``at``。如果返回 ``OK``，说明驱动工作正常。 > diff --git a/Documentation/translations/zh_CN/usb/authorization.rst b/Documentation/translations/zh_CN/usb/authorization.rst > index 2aa311f6b967..e2ff2282bd03 100644 > --- a/Documentation/translations/zh_CN/usb/authorization.rst > +++ b/Documentation/translations/zh_CN/usb/authorization.rst > @@ -10,34 +10,32 @@ > :校译: > > > -============================= > -授权或禁止 USB 设备连接到系统 > -============================= > +=========================== > +允许或禁止 USB 设备接入系统 > +=========================== > > 版权 (C) 2007 Inaky Perez-Gonzalez > <inaky@linux.intel.com> 英特尔公司 > > -此功能允许你控制 USB 设备是否可以在系统中使用。 > -借助它，你可以完全通过用户空间实现对 USB 设备的锁定。 > +有了这项功能，你就可以控制 USB 设备是否允许在系统中使用，并把 USB 设备锁 > +定机制完全放在用户空间实现。 > > -目前，当插入一个 USB 设备时，系统会对其进行配置， > -其接口会立即向用户开放。 > -有了这项改动，只有在 root 授权设备完成配置后， > -设备才可被使用。 > +目前，USB 设备一接入系统就会被立即配置，其接口也会立刻向用户开放。引入 > +这项机制后，只有在 root 明确授权后，设备才会完成配置并允许使用。 > > > 用法 > ==== > > -授权设备接入:: > +授权设备接入系统:: > > $ echo 1 > /sys/bus/usb/devices/DEVICE/authorized > > -取消对设备的授权:: > +取消设备授权:: > > $ echo 0 > /sys/bus/usb/devices/DEVICE/authorized > > -将新连接到 ``hostX`` 的设备默认设为未授权（即锁定）:: > +将连接到 ``hostX`` 的新设备默认设为未授权（即锁定）:: > > $ echo 0 > /sys/bus/usb/devices/usbX/authorized_default > > @@ -45,15 +43,14 @@ > > $ echo 1 > /sys/bus/usb/devices/usbX/authorized_default > > -默认情况下，所有 USB 设备都是授权的。 > -向 ``authorized_default`` 属性写入 ``2`` 会使内核 > -默认只授权连接到内部 USB 端口的设备。 > +默认情况下，所有 USB 设备都是授权的。向 ``authorized_default`` 属性写入 > +``2`` 会使内核默认只授权连接到内部 USB 端口的设备。 > > -系统锁定示例（比较粗糙） > ------------------------- > +系统锁定示例（简化版） > +---------------------- > > -假设你想实现一个锁定功能，只允许类型为 XYZ 的设备接入 > -（例如某台带有外露 USB 端口的自助服务终端）:: > +假设你想做一个锁定机制，只允许 XYZ 类型的设备接入（例如一台带有外露 USB > +端口的自助终端）:: > > 启动系统 > rc.local -> > @@ -63,21 +60,18 @@ > echo 0 > $host/authorized_default > done > > -给 udev 挂一个脚本，用于处理新插入的 USB 设备:: > +为 udev 配置一个脚本，用于处理新插入的 USB 设备:: > > if device_is_my_type $DEV > then > echo 1 > $device_path/authorized > - done > + fi > > > -``device_is_my_type()`` 才是锁定方案真正见功夫的 > -地方。仅仅检查 class、type 和 protocol 是否匹配 > -某个值，是你能做出的最糟糕的安全验证之一； > -对想绕过它的人来说，这反而是最容易利用的方案。 > -如果你需要真正安全的办法，那就该使用加密、 > -证书认证之类的机制。把 USB 存储设备当作 > -“钥匙”的一个简单例子可以是:: > +锁定方案是否可靠，关键全在 ``device_is_my_type()`` 的实现。仅仅检查 > +class、type 和 protocol 是否匹配，几乎是最差的一种安全校验方式；对想绕过 > +它的人来说，这种做法反而最容易伪造。如果你真要做安全控制，就该使用加密、 > +证书认证之类的机制。把 USB 存储设备当作“钥匙”的一个简单示例可以写成:: > > function device_is_my_type() > { > @@ -87,7 +81,7 @@ > sum=$(md5sum/mntpoint/.signature) > if [ $sum = $(cat /etc/lockdown/keysum) ] > then > - echo "We are good, connected" > + echo "验证通过，已连接" > umount /mntpoint > # 再做一些额外处理，让其他人也能使用它 > else > @@ -96,17 +90,16 @@ > } > > > -当然，这个例子很粗糙；真正要做的话， > -你会想用基于 PKI 的证书校验，这样就不必依赖 > -共享密钥之类的东西。不过你应该已经明白意思了。 > -任何拿到设备仿真工具包的人都能伪造描述符和设备信息。 > -别信这个。 > +当然，这个例子仍然比较简化。真正落地时，更合适的做法是使用基于 PKI 的证 > +书校验，这样就不必依赖共享密钥之类的机制了。不过意思已经很清楚：任何拿到 > +设备仿真工具包的人，都能伪造描述符和设备信息，所以别把这类检查当成真正 > +的安全保障。 > > 接口授权 > -------- > > -也有类似的方法用于允许或拒绝特定 USB 接口。 > -这使得你可以只阻止某个 USB 设备中的部分接口。 > +也可以用类似的方法允许或拒绝特定的 USB 接口。这样一来，你只需要阻止某个 > +USB 设备中的部分接口。 > > 授权接口:: > > @@ -126,14 +119,12 @@ > > $ echo 0 > /sys/bus/usb/devices/usbX/interface_authorized_default > > -默认情况下， > -``interface_authorized_default`` 位为 ``1``， > -因此所有接口默认都处于已授权状态。 > +默认情况下，``interface_authorized_default`` 位为 ``1``，因此所有接口默认 > +都会处于授权状态。 > > 注意： > - 如果把一个先前未授权的接口改为已授权， > - 则必须通过将 ``INTERFACE`` 写入 ``/sys/bus/usb/drivers_probe`` > - 来手动触发驱动探测。 > + 如果把一个先前未授权的接口改为已授权，则必须通过将 ``INTERFACE`` 写入 > + ``/sys/bus/usb/drivers_probe`` 来手动触发驱动探测。 > > -对于需要多个接口的驱动程序，应先授权所有必需接口， > -然后再触发驱动探测。这样做可以避免副作用。 > +对于需要多个接口的驱动程序，应先授权所有必需接口，然后再触发驱动探测。 > +这样做可以避免副作用。 > diff --git a/Documentation/translations/zh_CN/usb/chipidea.rst b/Documentation/translations/zh_CN/usb/chipidea.rst > index ea0dc3043189..011fb16f3350 100644 > --- a/Documentation/translations/zh_CN/usb/chipidea.rst > +++ b/Documentation/translations/zh_CN/usb/chipidea.rst > @@ -17,18 +17,17 @@ ChipIdea 高速双角色控制器驱动 > 1. 如何测试 OTG FSM（HNP 和 SRP） > --------------------------------- > > -下面以两块 Freescale i.MX6Q Sabre SD 开发板为例， > -说明如何通过 sysfs 输入文件演示 OTG 的 HNP 和 SRP 功能。 > +下面以两块 Freescale i.MX6Q Sabre SD 开发板为例，演示如何通过 sysfs 属性 > +测试 OTG 的 HNP 和 SRP 功能。 > > -1.1 如何使能 OTG FSM > +1.1 如何启用 OTG FSM > -------------------- > > 1.1.1 在 ``menuconfig`` 中选择 ``CONFIG_USB_OTG_FSM``，并重新编译内核 > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > > -重新构建内核镜像和模块。如果想查看 OTG FSM 的 > -一些内部变量，可以挂载 ``debugfs``；其中有两个文件 > -可以显示 OTG FSM 变量以及部分控制器寄存器的值:: > +重新构建内核镜像和模块。如果想查看 OTG FSM 的内部变量，可以挂载 > +``debugfs``；其中有两个文件，分别显示 OTG FSM 的变量和部分控制器寄存器值:: > > cat /sys/kernel/debug/ci_hdrc.0/otg > cat /sys/kernel/debug/ci_hdrc.0/registers > @@ -44,11 +43,10 @@ ChipIdea 高速双角色控制器驱动 > 1.2 测试步骤 > ------------ > > -1) 给两块 Freescale i.MX6Q Sabre SD 开发板上电， > - 并加载 gadget 类驱动（例如 ``g_mass_storage``）。 > +1) 给两块 Freescale i.MX6Q Sabre SD 开发板上电，并加载 gadget 类驱动（例如 > + ``g_mass_storage``）。 > > -2) 用 USB 线连接两块开发板： > - 一端是 micro A 插头，另一端是 micro B 插头。 > +2) 用 USB 线连接两块开发板：一端是 micro A 插头，另一端是 micro B 插头。 > > 插入 micro A 插头的一端是 A 设备，它应枚举另一端的 B 设备。 > > @@ -66,32 +64,28 @@ ChipIdea 高速双角色控制器驱动 > > echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req > > - 或者，通过引入 HNP 轮询，B 端主机可以知道 > - A 端外设希望切换为主机角色，因此这次角色切换 > - 也可以通过 A 端外设响应 B 端主机的轮询， > - 在 A 侧触发。 > - 这可以通过在 A 设备上执行下面的命令来完成:: > + 或者，也可以借助 HNP 轮询，让 B 端主机知道 A 端外设希望切回主机角色。 > + 因此，这次切换也可以由 A 侧触发，也就是由 A 端外设响应 B 端主机的轮询 > + 来完成。可在 A 设备上执行下面的命令:: > > echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req > > A 设备应切回主机角色并枚举 B 设备。 > > -5) 拔掉 B 设备（拔掉 micro B 插头）， > - 并在 10 秒内重新插入； > +5) 拔掉 B 设备（拔掉 micro B 插头），并在 10 秒内重新插入。 > A 设备应重新枚举 B 设备。 > > -6) 拔掉 B 设备（拔掉 micro B 插头）， > - 并在 10 秒后重新插入； > +6) 拔掉 B 设备（拔掉 micro B 插头），并在 10 秒后重新插入。 > A 设备不应重新枚举 B 设备。 > > - 如果 A 设备希望使用总线： > + 如果 A 设备还想继续使用总线： > > 在 A 设备上执行:: > > echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop > echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req > > - 如果 B 设备希望使用总线： > + 如果 B 设备想使用总线： > > 在 B 设备上执行:: > > @@ -111,40 +105,38 @@ ChipIdea 高速双角色控制器驱动 > > echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req > > - A 设备应恢复 USB 总线并枚举 B 设备。 > + A 设备应恢复 USB 总线，并枚举 B 设备。 > > 1.3 参考文档 > ------------ > -《On-The-Go and Embedded Host Supplement > -to the USB Revision 2.0 Specification > +《On-The-Go and Embedded Host Supplement to the USB Revision 2.0 Specification > July 27, 2012 Revision 2.0 version 1.1a》 > > 2. 如何将 USB 用作系统唤醒源 > ---------------------------- > -下面是在 i.MX6 平台上把 USB 用作系统唤醒源的示例。 > +下面给出在 i.MX6 平台上将 USB 用作系统唤醒源的示例。 > > -2.1 使能核心控制器的唤醒功能:: > +2.1 启用核心控制器的唤醒功能:: > > echo enabled > /sys/bus/platform/devices/ci_hdrc.0/power/wakeup > > -2.2 使能 glue 层的唤醒功能:: > +2.2 启用 glue 层的唤醒功能:: > > echo enabled > /sys/bus/platform/devices/2184000.usb/power/wakeup > > -2.3 使能 PHY 的唤醒功能（可选）:: > +2.3 启用 PHY 的唤醒功能（可选）:: > > echo enabled > /sys/bus/platform/devices/20c9000.usbphy/power/wakeup > > -2.4 使能根集线器的唤醒功能:: > +2.4 启用根集线器的唤醒功能:: > > echo enabled > /sys/bus/usb/devices/usb1/power/wakeup > > -2.5 使能相关设备的唤醒功能:: > +2.5 启用相关设备的唤醒功能:: > > echo enabled > /sys/bus/usb/devices/1-1/power/wakeup > > -如果系统只有一个 USB 端口， > -而你希望在该端口上启用 USB 唤醒功能， > -可以使用下面的脚本:: > +如果系统只有一个 USB 端口，而你希望在该端口上启用 USB 唤醒功能，可以使用 > +下面的脚本:: > > for i in $(find /sys -name wakeup | grep usb);do echo enabled > $i;done; > diff --git a/Documentation/translations/zh_CN/usb/dwc3.rst b/Documentation/translations/zh_CN/usb/dwc3.rst > index 3468ce50c5ba..9584cbbf6d03 100644 > --- a/Documentation/translations/zh_CN/usb/dwc3.rst > +++ b/Documentation/translations/zh_CN/usb/dwc3.rst > @@ -18,46 +18,43 @@ DWC3 驱动 > 待办 > ~~~~ > > -阅读时如果想顺手认领点任务，可以从下面挑一项 :) > +如果你愿意接手其中一项任务，可以从下面选择： > > - 将中断处理程序改为每个端点各自使用线程化 IRQ > > - 事实证明，有些 DWC3 命令大约需要 ``~1 ms`` 才能完成。 > - 当前代码会一直自旋等待命令完成，这种设计并不好。 > + 实践表明，某些 DWC3 命令大约需要 ``~1 ms`` 才能完成。当前代码会一直自旋 > + 等待命令完成，这并不是好办法。 > > 实现思路： > > - - DWC 核心实现了一个按端点对中断进行解复用的 IRQ 控制器。 > - 中断号在探测（``probe``）阶段分配，并归属于该设备。 > - 如果硬件通过 ``MSI`` 为每个端点提供独立中断， > - 那么这个“虚拟”IRQ 控制器就可以被真实的端点中断取代。 > + - DWC 核心实现了一个按端点分发中断的 IRQ 控制器。中断号在探测 > + （``probe``）阶段分配，并归属于该设备。如果硬件通过 ``MSI`` 为每个 > + 端点提供独立中断，那么这个“虚拟”IRQ 控制器就可以被真实的端点中断 > + 取代。 > > - - 在调用 ``usb_ep_enable()`` 时请求并分配中断资源， > - 在调用 ``usb_ep_disable()`` 时释放中断资源。 > - 最坏情况下需要 32 个中断，最少是 ``ep0/1`` 的两个中断。 > + - 在调用 ``usb_ep_enable()`` 时请求并分配中断资源，在调用 > + ``usb_ep_disable()`` 时释放中断资源。最坏情况下需要 32 个中断，最少是 > + ``ep0/1`` 的两个中断。 > - ``dwc3_send_gadget_ep_cmd()`` 将在 ``wait_for_completion_timeout()`` > 中休眠，直到命令完成。 > - 中断处理程序分为以下几个部分： > > - 设备级主中断处理程序 > - 遍历每个事件，并对其调用 ``generic_handle_irq()``。 > - 从 ``generic_handle_irq()`` 返回后，确认事件计数器，使中断最终消失。 > + 遍历每个事件，并调用 ``generic_handle_irq()`` 处理。返回后再确认 > + 事件计数器，让中断最终消失。 > > - 设备级线程化处理程序 > 无。 > > - 端点中断的主处理程序 > - 读取事件并尽量处理它。凡是需要睡眠的操作都交给线程处理。 > - 事件保存在每个端点的数据结构中。 > - 还要注意，一旦把某项工作交给线程处理， > - 就不要再在主处理程序里处理它， > - 以免出现优先级反转之类的问题。 > + 读取事件并尽量处理；凡是需要睡眠的操作都交给线程处理。事件保存在 > + 每个端点的数据结构中。一旦某项工作已经交给线程处理，主处理程序里就 > + 不要再碰它，以免出现优先级反转之类的问题。 > > - 端点中断的线程化处理程序 > 处理剩余的端点工作，这些工作可能会睡眠，例如等待命令完成。 > > - 延迟: > + 延迟： > > - 不应增加延迟，因为中断线程具有较高优先级， > - 会在普通用户态任务之前运行 > + 不应增加额外延迟，因为中断线程优先级较高，会在普通用户任务之前运行 > （除非用户更改了调度优先级）。 > diff --git a/Documentation/translations/zh_CN/usb/ehci.rst b/Documentation/translations/zh_CN/usb/ehci.rst > index e05e493a30d3..c4c52303b13e 100644 > --- a/Documentation/translations/zh_CN/usb/ehci.rst > +++ b/Documentation/translations/zh_CN/usb/ehci.rst > @@ -14,45 +14,37 @@ > EHCI 驱动 > ========= > > -2002年12月27日 > +2002 年 12 月 27 日 > > -EHCI 驱动用于通过支持 USB 2.0 的主机控制器 > -硬件与高速 USB 2.0 设备通信。USB 2.0 兼容 > -USB 1.1 标准，它定义了三种传输速率： > +EHCI 驱动用于借助支持 USB 2.0 的主机控制器，与高速 USB 2.0 设备通信。USB > +2.0 向下兼容 USB 1.1，并定义了三种传输速率： > > - “高速”（High Speed）480 Mbit/sec（60 MByte/sec） > - “全速”（Full Speed）12 Mbit/sec（1.5 MByte/sec） > - “低速”（Low Speed）1.5 Mbit/sec > > -USB 1.1 仅支持全速与低速。 > -高速设备可以在 USB 1.1 系统上使用， > -但速度会降到 USB 1.1 的速率。 > +USB 1.1 仅支持全速与低速。高速设备可以在 USB 1.1 系统上使用，但速度会 > +降到 USB 1.1 的速率。 > > -USB 1.1 设备也可以在 USB 2.0 系统上使用。当它们 > -插入 EHCI 控制器时，会被交由 USB 1.1 的伴随 > -（companion）控制器处理，该控制器通常是 OHCI 或 UHCI。 > +USB 1.1 设备也可以在 USB 2.0 系统上使用。当它们插入 EHCI 控制器时，会交给 > +USB 1.1 的伴随（companion）控制器处理，该控制器通常是 OHCI 或 UHCI。 > > -当 USB 1.1 设备插入 USB 2.0 集线器时，它们通过 > -集线器中的事务转换器（Transaction Translator，TT） > -与 EHCI 控制器交互，该转换器将低速或全速事务转换为 > -高速分割事务，从而避免浪费传输带宽。 > +当 USB 1.1 设备插入 USB 2.0 集线器时，它们会通过集线器里的事务转换器 > +（Transaction Translator，TT）与 EHCI 控制器通信。该转换器会把低速或全 > +速事务转换为高速分割事务，从而避免浪费传输带宽。 > > -截至本文撰写时，该驱动已在以下 EHCI 实现上成功运行 > -（按字母顺序）：Intel、NEC、Philips 和 VIA。 > -其他供应商的 EHCI 实现正在陆续问世； > -预计该驱动在这些实现上也可正常运行。 > +截至本文撰写时，该驱动已在以下 EHCI 实现上成功运行（按字母顺序）： > +Intel、NEC、Philips 和 VIA。随着其他供应商的 EHCI 实现陆续问世，预计该 > +驱动在那些实现上也能正常运行。 > > -自 2001 年年中起，usb-storage 设备就已可用 > -（在 2.4 版该驱动上速度相当不错）， > -集线器则直到 2001 年底才开始可用，而其他类型的高速设备 > -似乎要等到更多系统内置 USB 2.0 后才会出现。 > -这类新系统从 2002 年初开始上市， > -并在 2002 年下半年变得更加常见。 > +自 2001 年年中起，usb-storage 设备就已可用（在 2.4 版该驱动上速度表现相当 > +不错），集线器则直到 2001 年底才开始可用。其他类型的高速设备似乎要等到 > +更多系统内置 USB 2.0 后才会出现。这类新系统从 2002 年初开始上市，并在 > +2002 年下半年变得更加常见。 > > -注意，USB 2.0 支持并不只是 EHCI 本身。 > -它还需要对 Linux-USB 核心 API 作出其他修改， > -包括 hub 驱动；不过这些修改并不需要真正改变 > -暴露给 USB 设备驱动的基本 ``usbcore`` API。 > +注意，USB 2.0 的支持并不只靠 EHCI 本身。它还需要对 Linux-USB 核心 API > +做其他修改，包括 hub 驱动；不过这些修改并不需要真正改变向 USB 设备驱动 > +暴露的基本 ``usbcore`` API。 > > - David Brownell > <dbrownell@users.sourceforge.net> > @@ -61,58 +53,46 @@ USB 1.1 设备也可以在 USB 2.0 系统上使用。当它们 > 功能 > ==== > > -该驱动会定期在 x86 硬件上进行测试， > -也已在 PPC 硬件上使用，因此大小端问题应当已经解决。 > -因此可以认为，它已经处理好了所有必要的 PCI 细节， > -所以即便在 DMA 映射有些特殊的系统上， > -I/O 也应能正常运行。 > +该驱动长期在 x86 硬件上接受测试，也在 PPC 平台上使用过，因此大小端问题应 > +该都已解决。再加上各种必要的 PCI 细节都已处理妥当，即便在 DMA 映射较特 > +殊的系统上，I/O 也应能正常工作。 > > 传输类型 > -------- > > -截至本文撰写时，该驱动应当已经能够很好地处理 > -所有控制传输、批量传输和中断传输， > -包括通过 USB 2.0 集线器中的事务转换器 > -与 USB 1.1 设备通信；但仍可能存在 bug。 > +截至本文撰写时，该驱动应当已经能够稳定处理所有控制传输、批量传输和中断传 > +输，包括经由 USB 2.0 集线器里的事务转换器访问 USB 1.1 设备；不过仍可能 > +存在 bug。 > > -高速等时（ISO）传输支持也已可用，但截至本文撰写时， > -还没有 Linux 驱动使用这项支持。 > +高速等时（ISO）传输支持也已可用，不过截至本文撰写时，还没有 Linux 驱动真 > +正使用它。 > > -目前尚不支持通过事务转换器实现全速等时传输。 > -需要注意，ISO 传输的 split transaction 支持 > -与高速 ISO 传输几乎无法共用代码， > -因为 EHCI 用不同的数据结构表示它们。 > -因此，目前大多数 USB 音频和视频设备 > -还不能通过高速总线连接使用。 > +目前尚不支持通过事务转换器实现全速等时传输。需要注意，ISO 传输的分割 > +事务支持与高速 ISO 传输几乎无法共用代码，因为 EHCI 用不同的数据结构表示 > +它们。因此，目前大多数 USB 音频和视频设备还无法在高速总线上使用。 > > 驱动行为 > -------- > > -所有类型的传输都可以排队。 > -这意味着来自一个接口驱动的控制传输 > -（或通过 usbfs 发出的控制传输）不会干扰 > -另一个驱动的控制传输，而且中断传输可以使用 1 帧的周期， > -而不必担心中断处理开销导致的数据丢失。 > +所有类型的传输都可以排队提交。这意味着某个接口驱动发出的控制传输（或经由 > +usbfs 提交的控制传输）不会干扰其他驱动的控制传输，而中断传输可以按 1 帧 > +周期运行，不必担心中断处理开销导致数据丢失。 > > > -EHCI 根集线器代码会将 USB 1.1 设备移交给其伴随控制器。 > -该驱动不需要了解那些驱动的任何细节； > -一个原本就能正常工作的 OHCI 或 UHCI 驱动， > -并不会因为 EHCI 驱动也存在而需要更改。 > +EHCI 根集线器代码会将 USB 1.1 设备交给其伴随控制器处理。该驱动无需了解 > +那些驱动的任何细节；一个原本就能正常工作的 OHCI 或 UHCI 驱动，也不会因为 > +EHCI 驱动存在而需要修改。 > > -电源管理方面还有一些问题； > -当前挂起/恢复的行为还不完全正确。 > +电源管理方面仍有一些问题；当前挂起/恢复行为还不完全正确。 > > -此外，在调度周期性事务 > -（中断和等时传输）时还采取了一些简化处理。 > -这些简化会限制可调度的周期性事务数量， > -并且无法使用小于一帧的轮询间隔。 > +此外，在调度周期性事务（中断和等时传输）时还采取了一些简化处理。这些 > +简化会限制可调度的周期性事务数量，并且无法使用小于一帧的轮询间隔。 > > 使用方式 > ======== > > -假设有一个 EHCI 控制器（位于 PCI 卡或主板上）， > -并且已将此驱动编译为模块，可这样加载:: > +假设系统中有一个 EHCI 控制器（位于 PCI 卡或主板上），并且此驱动是以模块形 > +式编译的，那么可以这样加载:: > > # modprobe ehci-hcd > > @@ -120,27 +100,24 @@ EHCI 根集线器代码会将 USB 1.1 设备移交给其伴随控制器。 > > # rmmod ehci-hcd > > -还应加载一个伴随控制器驱动， > -例如 ``ohci-hcd`` 或 ``uhci-hcd``。 > -如果 EHCI 驱动出现任何问题，只需卸载它的模块， > -随后该伴随控制器驱动就会接手 > -此前由 EHCI 驱动处理的所有设备 > -（但速度会降低）。 > +还应加载一个伴随控制器驱动，例如 ``ohci-hcd`` 或 ``uhci-hcd``。如果 EHCI > +驱动出了问题，只要卸载它的模块，伴随控制器驱动就会接管此前由 EHCI 驱动处 > +理的全部设备（只是速度会降低）。 > > 模块参数（传给 ``modprobe``）包括： > > log2_irq_thresh（默认值 0）： > - 默认中断延迟的 log2 值，单位是微帧。默认值 0 表示 1 个微帧 > - （125 微秒）。最大值 6 表示 2^6 = 64 个微帧。 > + 默认中断延迟的 log2 值，单位为微帧。默认值 0 表示 1 个微帧 > + （125 微秒），最大值 6 表示 2^6 = 64 个微帧。 > 该值控制 EHCI 控制器发出中断的频率。 > > -如果在 2.5 内核上使用此驱动，并且启用了 USB 调试支持， > -则会在任一 EHCI 控制器的 ``sysfs`` 目录中看到三个文件： > +如果你在 2.5 内核上使用此驱动，并且启用了 USB 调试支持，那么任一 EHCI 控 > +制器对应的 ``sysfs`` 目录下都会看到三个文件： > > ``async`` > 转储异步调度，用于控制传输和批量传输。它会显示每个活动的 ``qh`` > 以及待处理的 ``qtd``，通常每个 ``urb`` 对应一个 ``qtd``。 > - （可以在 ``usb-storage`` 做磁盘 I/O 时看它；顺便观察请求队列！） > + （可以在 ``usb-storage`` 执行磁盘 I/O 时查看；也可顺便观察请求队列。） > > ``periodic`` > 转储周期性调度，用于中断传输和等时传输。不显示 ``qtd``。 > @@ -151,111 +128,81 @@ EHCI 根集线器代码会将 USB 1.1 设备移交给其伴随控制器。 > 这些文件的内容有助于定位驱动问题。 > > > -设备驱动通常不需要关心自己是否运行在 EHCI 之上， > -但它们可能想检查 > -``usb_device->speed == USB_SPEED_HIGH``。 > -高速设备能做到全速（或低速）设备做不到的事， > -例如高带宽的周期性传输（中断或 ISO 传输）。 > -另外，设备描述符中的某些值 > -（例如周期性传输的轮询间隔） > -在高速模式下使用不同的编码方式。 > +设备驱动通常不需要关心自己是否运行在 EHCI 之上，但有时可能会想检查 > +``usb_device->speed == USB_SPEED_HIGH``。高速设备能做到全速（或低速）设备 > +做不到的事，例如高带宽的周期性传输（中断或 ISO 传输）。另外，设备描述符 > +中的某些值（例如周期性传输的轮询间隔）在高速模式下使用不同的编码方式。 > > -不过，一定要让设备驱动经过 USB 2.0 集线器的测试。 > -当使用事务转换器时，这些集线器报告某些故障 > -（例如断开连接）的方式会不同； > -已经见过一些驱动在遇到与 OHCI 或 UHCI > -所报告的不同故障时表现不佳。 > +不过，设备驱动一定要在 USB 2.0 集线器后面测一遍。使用事务转换器时，这些 > +集线器报告某些故障（例如断开连接）的方式会有所不同；已经见过一些驱动在 > +遇到与 OHCI 或 UHCI 不同的故障时表现不佳。 > > 性能 > ==== > > -USB 2.0 吞吐量主要受两个因素制约： > -主机控制器处理请求的速度，以及设备响应这些请求的速度。 > -480 Mbit/sec 的“原始传输率”对所有设备都成立， > -但总吞吐量还会受到诸如单个高速包之间的延迟、 > -驱动是否足够聪明，以及系统整体负载等因素的影响。 > -延迟也是性能考量因素。 > +USB 2.0 的吞吐量主要受两个因素制约：主机控制器处理请求的速度，以及设备响 > +应这些请求的速度。480 Mbit/sec 的“原始传输率”对所有设备都一样，但整体吞 > +吐量还会受到诸如高速包之间的间隔、驱动实现是否足够高效以及系统总体负载等 > +因素影响。延迟同样是需要考虑的性能指标。 > > -批量传输最常用于关注吞吐量的场景。 > -需要记住的是，批量传输总是以 512 字节包为单位， > -而一个 USB 2.0 微帧中最多只能容纳 13 个这样的包。 > -8 个 USB 2.0 微帧构成一个 USB 1.1 帧； > -一个微帧的时长是 1 毫秒 / 8 = 125 微秒。 > +批量传输通常用于看重吞吐量的场景。需要记住的是，批量传输总是以 512 字节包 > +为单位，而一个 USB 2.0 微帧中最多只能容纳 13 个这样的包。8 个 USB 2.0 微 > +帧构成一个 USB 1.1 帧，因此一个微帧的时长就是 125 微秒。 > > -因此，只要硬件和设备驱动软件都允许， > -批量传输可提供超过 50 MByte/sec 的带宽。 > -周期性传输模式（等时和中断）允许使用更大的包大小， > -从而可以逼近所宣称的 480 Mbit/sec 传输率。 > +因此，只要硬件和驱动实现都足够成熟，批量传输就可以提供 50 MByte/sec 以上 > +的带宽。周期性传输模式（等时和中断）允许使用更大的包大小，从而可以逼近所 > +宣称的 480 Mbit/sec 传输率。 > > 硬件性能 > -------- > > -截至本文撰写时，单个 USB 2.0 设备的最大传输速率 > -通常约为 20 MByte/sec。 > -这当然会随着时间改变：一些设备现在更快，一些更慢。 > +截至本文撰写时，单个 USB 2.0 设备的最大传输速率通常约为 20 MByte/sec。 > +这种情况当然会随时间变化：有些设备现在更快，有些则更慢。 > > -第一代 NEC EHCI 实现似乎存在 > -大约 28 MByte/sec 的硬件瓶颈。 > -虽然这对单个 20 MByte/sec 的设备显然已经够用， > -但把三个这样的设备挂到同一总线上， > -并不能得到 60 MByte/sec。 > -问题似乎在于控制器硬件无法并发进行 USB 与 PCI 访问， > -因此它每个微帧只会尝试 6 次（也许是 7 次） > -USB 事务，而不是 13 次。 > -（对一个比其他产品早上市一年的芯片来说， > -这是个合理的妥协！） > +第一代 NEC EHCI 实现似乎存在大约 28 MByte/sec 的硬件瓶颈。虽然这对单个 > +20 MByte/sec 的设备显然已经够用，但把三个这样的设备挂到同一总线上，并不 > +能得到 60 MByte/sec。问题似乎在于控制器硬件无法并发进行 USB 与 PCI 访问， > +因此它每个微帧只会尝试 6 次（也许是 7 次）USB 事务，而不是 13 次。 > +（对一款比其他产品早上市一年的芯片来说，这样的取舍也算合理。） > > > -预计较新的实现会在这方面做得更好， > -通过投入更多芯片面积来解决这个问题， > -使新的主板芯片组更接近 60 MByte/sec 的目标。 > -这既包括 NEC 的更新实现，也包括其他厂商的芯片。 > +预计较新的实现会在这方面做得更好，通过投入更多芯片面积来解决这个问题， > +使新的主板芯片组更接近 60 MByte/sec 的目标。这既包括 NEC 的更新实现，也 > +包括其他厂商的芯片。 > > > -主机从 EHCI 控制器收到“请求已完成”中断的最小延迟 > -为一个微帧（125 微秒）。该延迟可以调节； > -驱动提供了一个模块选项。默认情况下， > -``ehci-hcd`` 使用最小延迟，这意味着当发出一个控制 > -或批量请求时，通常可以在不到 250 微秒内得知它已完成 > -（具体取决于传输大小）。 > +主机从 EHCI 控制器收到“请求已完成”中断的最小延迟为一个微帧 > +（125 微秒）。该延迟可以调节；驱动提供了一个模块选项。 > +默认情况下，``ehci-hcd`` 使用最小延迟，这意味着发出控制或批量请求后，通 > +常不到 250 微秒就能得知它已经完成（具体取决于传输大小）。 > > 软件性能 > -------- > > -即便只是要达到 20 MByte/sec 的传输速率， > -Linux-USB 设备驱动也必须让 EHCI 队列始终保持满载。 > -这意味着要发出较大的请求， > -或者在需要发出一连串小请求时使用批量请求排队。 > -如果驱动未做到这一点，那么会直接从性能结果上表现出来。 > +即便只是要达到 20 MByte/sec 的传输速率，Linux-USB 设备驱动也必须让 EHCI > +队列始终保持满载。这意味着要发出较大的请求，或者在需要发出一连串小请求 > +时使用批量请求排队。如果驱动做不到这一点，性能就会明显受影响。 > > > -在典型情况下，使用 ``usb_bulk_msg()`` > -以 4 KB 块循环写出， > -会浪费超过一半的 USB 2.0 带宽。 > -I/O 完成与驱动发出下一次请求之间的延迟， > -通常会比一次 I/O 本身耗时更长。 > -如果同样的循环改用 16 KB 块，会好一些； > -若使用一连串 128 KB 块，则浪费会少得多。 > +在典型场景下，如果使用 ``usb_bulk_msg()`` 以 4 KB 块循环写出，会浪费超过 > +一半的 USB 2.0 带宽。I/O 完成与驱动发出下一次请求之间的空档，往往比一次 > +I/O 本身耗时还长。如果同样的循环改用 16 KB 块，情况会好一些；若使用一连串 > +128 KB 块，则浪费会少得多。 > > +但与其依赖这么大的 I/O 缓冲区来提升同步 I/O 的效率，不如直接向主机控制器 > +排队提交多个（批量）请求，然后等待它们全部完成（或在出错时取消）。这种 > +URB 排队方式对所有 USB 1.1 主机控制器驱动同样适用。 > > -但与其依赖这么大的 I/O 缓冲区来让同步 I/O 高效， > -不如直接向主机控制器排入多个（批量）请求， > -然后等待它们全部完成（或在出错时取消）。 > -这种 URB 排队方式对所有 USB 1.1 > -主机控制器驱动也同样适用。 > > - > -在 Linux 2.5 内核中，定义了新的 ``usb_sg_*()`` API； > -它们会把 scatterlist 中的所有缓冲区都排入队列。 > -它们还使用 scatterlist 的 DMA 映射 > -（其中可能应用 IOMMU）并减少中断次数， > -这些都有助于让高速传输尽可能快地运行。 > +在 Linux 2.5 内核中，定义了新的 ``usb_sg_*()`` API；它们会把 scatterlist > +中的所有缓冲区都排入队列。它们还使用 scatterlist 的 DMA 映射（其中可能 > +应用 IOMMU）并减少中断次数，这些都有助于让高速传输尽可能快地运行。 > > 待办： > 中断传输和等时（ISO）传输的性能问题。 > - 这些周期性传输都是完全调度的，因此，主要问题可能在于如何触发高带宽模式。 > + 这些周期性传输都是完全调度的，因此主要问题可能在于如何触发高带宽模式。 > > 待办： > - 通过 ``sysfs`` 中的 ``uframe_periodic_max`` 参数， > - 可以分配超过标准 80% 的周期性带宽。 > + 通过 ``sysfs`` 中的 ``uframe_periodic_max`` 参数，可以分配超过标准 > + 80% 的周期性带宽。 > 后续将对此进行说明。 > diff --git a/Documentation/translations/zh_CN/usb/index.rst b/Documentation/translations/zh_CN/usb/index.rst > index eb5aca0c13ec..df99814c6497 100644 > --- a/Documentation/translations/zh_CN/usb/index.rst > +++ b/Documentation/translations/zh_CN/usb/index.rst > @@ -1,4 +1,14 @@ > .. SPDX-License-Identifier: GPL-2.0 > + > +.. only:: subproject and latex > + > + .. raw:: latex > + > + \renewcommand{\thesection}{} > + \renewcommand{\thesubsection}{} > + \kerneldocCJKon > + \kerneldocBeginSC{ > + > .. include:: ../disclaimer-zh_CN.rst > > :Original: Documentation/usb/index.rst > @@ -24,7 +34,7 @@ USB 支持 > ehci > usbmon > > -Todolist: > +待翻译文档： > > * functionfs > * functionfs-desc > @@ -52,3 +62,9 @@ Todolist: > ==== > > * :ref:`genindex` > + > +.. only:: subproject and latex > + > + .. raw:: latex > + > + }\kerneldocEndSC > diff --git a/Documentation/translations/zh_CN/usb/usbmon.rst b/Documentation/translations/zh_CN/usb/usbmon.rst > index 11b6d5b59dce..bbfcbf875e26 100644 > --- a/Documentation/translations/zh_CN/usb/usbmon.rst > +++ b/Documentation/translations/zh_CN/usb/usbmon.rst > @@ -16,67 +16,56 @@ usbmon > > 简介 > ==== > -小写形式的 ``usbmon`` 指的是内核中的一项功能， > -用于收集 USB 总线上的 I/O 跟踪信息。它类似于网络监控工具 > -``tcpdump(1)`` 或 Ethereal 所使用的数据包套接字。 > -类似地，人们希望使用 usbdump 或 USBMon > -（首字母大写）之类的工具来检查 > -usbmon 生成的原始跟踪数据。 > - > -usbmon 报告的是各个外设驱动 > -向主机控制器驱动（HCD）发出的请求。 > -因此，如果 HCD 本身有 bug，那么 usbmon 报告的跟踪信息 > -可能无法精确对应实际的总线事务。 > -这和 tcpdump 的情况是一样的。 > - > -目前实现了两种 API: ``text`` 和 ``binary``。 > -二进制 API 通过 ``/dev`` 命名空间中的字符设备提供， > -并且属于 ABI。文本 API 自内核 2.6.35 起已废弃， > -但为了方便仍然可用。 > +小写的 ``usbmon`` 指的是内核中的一项功能，用于收集 USB 总线上的 I/O 跟踪 > +信息。它类似于网络监控工具 ``tcpdump(1)`` 或 Ethereal 使用的数据包套接 > +字。通常会用 usbdump 或 USBMon（首字母大写）之类的工具来查看 usbmon 生成 > +的原始跟踪数据。 > + > +usbmon 记录的是各个设备驱动向主机控制器驱动（HCD）发出的请求。因此，如果 > +HCD 自身有 bug，usbmon 输出的跟踪信息就未必能和真实的总线事务一一对应。 > +这和 tcpdump 的情况类似。 > + > +目前实现了两种 API：``text`` 和 ``binary``。二进制 API 通过 ``/dev`` 下的 > +字符设备提供，是 ABI 的一部分。文本 API 自内核 2.6.35 起已废弃，但为了 > +兼容和使用方便，至今仍然保留。 > > 如何使用 usbmon 收集原始文本跟踪信息 > ==================================== > > -与数据包套接字不同，usbmon 提供了一种接口， > -可以输出文本格式的跟踪信息。这样做有两个目的： > -第一，在更完善的格式最终确定之前， > -它作为工具间通用的跟踪交换格式； > -第二，在不使用工具的情况下，人们也可以直接阅读这些信息。 > +与数据包套接字不同，usbmon 还提供了一个输出文本格式跟踪信息的接口。这样 > +做主要有两个目的：一是在更完善的格式最终确定之前，将其作为工具间通用的跟 > +踪交换格式；二是在没有工具时也能直接阅读这些信息。 > > -要收集原始文本跟踪信息，请按以下步骤进行操作。 > +要收集原始文本跟踪信息，按下面的步骤做即可。 > > 1. 准备 > ------- > > -挂载 debugfs（内核配置中必须启用它），并加载 usbmon 模块 > -（如果它是作为模块构建的）。如果 usbmon 已经编入内核， > -那么第二步可以省略。 > +挂载 debugfs（内核配置里必须启用它），并加载 usbmon 模块（如果它是以模块 > +方式构建的）。如果 usbmon 已经编译进内核，这一步就可以省略。 > > 命令示例:: > > - # mount -t debugfs none_debugs /sys/kernel/debug > + # mount -t debugfs none /sys/kernel/debug > # modprobe usbmon > # > > -确认总线套接字是否存在:: > +确认 ``usbmon`` 目录下是否有这些条目:: > > # ls /sys/kernel/debug/usb/usbmon > 0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u > # > > -现在，你可以选择使用 ``0u`` 捕获所有总线上的数据包， > -并跳到第 3 步； > -也可以先按第 2 步找到目标设备所在的总线。 > -这样可以过滤掉那些持续输出数据的烦人设备。 > +现在，你可以直接用 ``0u`` 捕获所有总线上的数据包，然后跳到第 3 步；也可 > +以先按第 2 步找出目标设备所在的总线。这样可以把那些持续产生流量的设备过 > +滤掉。 > > 2. 查找目标设备连接的是哪条总线 > ------------------------------- > > -运行 ``cat /sys/kernel/debug/usb/devices``， > -找到对应设备的 T 行。通常可以通过厂商字符串来查找。 > -如果有许多类似设备，可以拔掉其中一个， > -再比较前后两次 ``/sys/kernel/debug/usb/devices`` > -的输出。T 行里会包含总线编号。 > +运行 ``cat /sys/kernel/debug/usb/devices``，找到对应设备的 T 行。通常可以通过 > +厂商字符串来查找。如果有很多相似设备，可以拔掉其中一个，再比较前后两次 > +``/sys/kernel/debug/usb/devices`` 的输出。T 行里会包含总线编号。 > > 示例:: > > @@ -86,8 +75,8 @@ usbmon 报告的是各个外设驱动 > S: Manufacturer=ATEN > S: Product=UC100KM V2.00 > > -``Bus=03`` 表示它位于 3 号总线上。或者， > -也可以查看 ``lsusb`` 的输出，并从对应行得到总线编号。 > +``Bus=03`` 表示它位于 3 号总线上。或者，也可以查看 ``lsusb`` 的输出，并从 > +对应条目里找到总线编号。 > > 示例如下:: > > @@ -97,133 +86,108 @@ usbmon 报告的是各个外设驱动 > 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 盘、拷贝文件、操作摄像头等。 > +这里做一些会产生 USB 流量的操作即可，比如插入 U 盘、拷贝文件、操作摄像头 > +等。 > > > 5. 停止 cat > ----------- > > -这一步通常通过键盘中断（Control-C）完成。 > +这一步通常按下键盘中断（Control-C）即可完成。 > > -此时输出文件（本例中为 ``/tmp/1.mon.out``） > -可以保存、通过电子邮件发送，或使用文本编辑器查看。 > -如果使用最后一种方式，请确保文件不会大到编辑器无法打开。 > +此时，输出文件（本例中为 ``/tmp/1.mon.out``）可以保存下来，通过电子邮件发 > +送，也可以用文本编辑器查看。如果要用文本编辑器查看，请确保文件大小不会 > +大到编辑器无法处理。 > > > 原始文本数据格式 > ================ > > -目前支持两种格式：原始格式，也就是 ``1t`` 格式， > -以及 ``1u`` 格式。``1t`` 格式在内核 2.6.21 中已被废弃。 > -``1u`` 格式增加了一些字段，例如 ISO 帧描述符、 > -``interval`` 等。它生成的行会稍长一些， > -但在其他方面是 ``1t`` 格式的完整超集。 > - > -如果程序需要区分上述两种格式， > -可以查看 ``address`` 字段（见下文）。 > -如果其中有两个冒号，就是 ``1t`` 格式； > -否则是 ``1u`` 格式。 > - > -任何文本格式的数据由一系列事件组成， > -如 URB 提交、URB 回调、提交错误等。 > -每个事件对应单独的一行文本， > -由使用空白符间隔的若干字段组成。 > -字段的数量与位置可能取决于事件类型， > -但以下字段对所有类型都通用： > - > -下面按从左到右的顺序列出这些共有字段： > - > -- URB Tag。用于标识 URB，通常是 URB 结构体在内核中的地址 > - （以十六进制表示）， > - 但也可能是序号或其他合理的唯一字符串。 > - > -- 时间戳（微秒），十进制数字。 > - 时间戳的精度取决于可用时钟， > - 因此可能远差于 > - 1 微秒（例如实现使用的是 jiffies）。 > - > -- 事件类型。它表示的是事件的格式，而不是 URB 的类型。 > - 可用值为：``S`` 表示提交，``C`` 表示回调，``E`` 表示提交错误。 > - > -- ``Address`` 字段（以前称作 ``pipe``）。 > - 它包含四个由冒号分隔的字段： > - URB 类型及方向、总线号、设备地址和端点号。类型与方向的编码如下： > - > - == == ========================== > - Ci Co 控制输入和输出 > - Zi Zo 等时输入和输出 > - Ii Io 中断输入和输出 > - Bi Bo 批量输入和输出 > - == == ========================== > - > - 总线号、设备地址和端点号使用十进制，但可能有前导零。 > - > -- URB 状态字段。这个字段要么是一个字母， > - 要么是几个由冒号分隔的数字： > - URB 状态、``interval``、``start frame`` 和 ``error count``。 > - 与 ``address`` 字段不同，除了状态外，其余字段都是可选的。 > - ``interval`` 只会为中断和等时 URB 打印；``start frame`` 只会为 > - 等时 URB 打印；错误计数只会在等时回调事件中打印。 > - > - 状态字段是一个十进制数字，有时为负数， > - 对应 URB 的 ``status`` 字段。 > - 对于提交事件，这个字段本身没有实际意义， > - 但为了便于脚本解析，它仍然存在。 > - 当发生错误时，该字段包含错误码。 > - > - 在提交控制包时，这个字段包含的是 ``Setup Tag``， > - 而不是一组数字。 > - 判断 ``Setup Tag`` 是否存在很容易，因为它从来不是数字。 > - 因此，如果脚本在这个字段里发现的是一组数字， > - 就会继续读取数据长度（等时 URB 除外）。 > - 如果发现的是其他内容，比如一个字母， > - 那么脚本会先读取 ``Setup`` 包，再读取数据长度或等时描述符。 > - > -- ``Setup`` 包由 5 个字段组成： > - ``bmRequestType``、``bRequest``、``wValue``、 > - ``wIndex`` 和 ``wLength``。这些字段由 USB 2.0 规范定义。 > - 如果 ``Setup Tag`` 为 ``s``，就可以安全地解码这些字段。 > - 否则，说明 Setup 包虽然存在，但并未被捕获，此时各字段中会填入占位内容。 > +目前支持两种格式：原始的 ``1t`` 格式和 ``1u`` 格式。``1t`` 格式在内核 > +2.6.21 中已被废弃。``1u`` 格式增加了一些字段，例如 ISO 帧描述符和 > +``interval``。它生成的行会稍长一些，但除此之外，它是 ``1t`` 格式的完整 > +超集。 > + > +如果程序需要区分上述两种格式，可以查看 ``address`` 字段（见下文）。如果 > +其中有两个冒号，就是 ``1t`` 格式；否则是 ``1u`` 格式。 > + > +任何文本格式的数据都由一系列事件构成，例如 URB 提交、URB 回调和提交错 > +误。每个事件占一行，由若干以空白符分隔的字段组成。字段数量和位置会随事件 > +类型变化，但下面这些字段对所有类型都通用： > + > +下面按从左到右的顺序说明这些通用字段： > + > +- URB 标识（URB Tag）。用于标识 URB，通常是 URB 结构体在内核中的地址 > + （十六进制），也可能是序号或其他足以唯一标识 URB 的字符串。 > + > +- 时间戳（微秒），十进制数字。时间戳的精度取决于可用时钟，所以可能远低于 > + 1 微秒（例如实现使用 jiffies 时）。 > + > +- 事件类型。它表示的是这一行事件的格式，而不是 URB 的类型。可用值为： > + ``S`` 表示提交，``C`` 表示回调，``E`` 表示提交错误。 > + > +- ``Address`` 字段（以前称为 ``pipe``）。它包含四个由冒号分隔的字段：URB > + 类型及方向、总线号、设备地址和端点号。类型与方向的编码如下： > + > + - ``Ci`` / ``Co``：控制输入 / 输出 > + - ``Zi`` / ``Zo``：等时输入 / 输出 > + - ``Ii`` / ``Io``：中断输入 / 输出 > + - ``Bi`` / ``Bo``：批量输入 / 输出 > + > + 总线号、设备地址和端点号都是十进制数，但可能有前导零，方便人阅读。 > + > +- URB 状态字段。这个字段要么是一个字母，要么是几个用冒号分隔的数字，依次 > + 表示 URB 状态、``interval``、``start frame`` 和 ``error count``。与 > + ``address`` 字段不同，除状态外，其余字段都可能省略。``interval`` 只会在 > + 中断和等时 URB 中打印；``start frame`` 只会在等时 URB 中打印；错误计数只 > + 会在等时回调事件中打印。 > + > + 状态字段是一个十进制数，有时为负数，对应 URB 的 ``status`` 字段。对于提 > + 交事件，这个字段本身并无实际语义，但为了便于脚本解析仍会保留。发生错误 > + 时，这里填的是错误码。 > + > + 如果是控制包的提交事件，这个字段里放的不是一组数字，而是 ``Setup Tag``。 > + 这很容易分辨，因为 ``Setup Tag`` 永远不是数字。所以脚本如果在这里读到一 > + 组数字，就会继续读取数据长度（等时 URB 除外）；如果读到的是字母之类的内 > + 容，就要先读取 ``Setup`` 包，再读取数据长度或等时描述符。 > + > +- ``Setup`` 包由 5 个字段组成：``bmRequestType``、``bRequest``、``wValue``、 > + ``wIndex`` 和 ``wLength``。这些字段由 USB 2.0 规范定义。如果 ``Setup Tag`` > + 是 ``s``，就可以安全解码这些字段。否则，说明 Setup 包虽然存在，但并未被 > + 捕获，此时各字段中会填入占位内容。 > > - 等时传输帧描述符的数量及其内容： > - 如果一个等时传输事件带有一组描述符，首先打印该 URB 中描述符的总数， > - 然后为每个描述符打印一个字段，最多打印 5 个字段。 > - 每个字段由三个用冒号分隔的十进制数字组成， > - 分别表示状态（status）、偏移（offset）和长度（length）。 > - 对于提交（submission），报告的是初始长度； > - 对于回调（callback），报告的是实际长度。 > + 如果某个等时传输事件带有描述符，会先打印该 URB 的描述符总数，再为每个描 > + 述符打印一个字段，最多 5 个。每个字段由三个用冒号分隔的十进制数组成，依 > + 次表示状态（status）、偏移（offset）和长度（length）。对于提交事件，报 > + 告的是初始长度；对于回调事件，报告的是实际长度。 > > -- 数据长度： > - 对于提交，表示请求的长度；对于回调，表示实际传输的长度。 > +- 数据长度：对于提交，表示请求的长度；对于回调，表示实际传输的长度。 > > -- 数据标签： > - 即使数据长度非零，usbmon 也不一定会捕获数据。 > - 仅当标签为 ``=`` 时，才会有数据字段。 > +- 数据标签：即使数据长度非零，usbmon 也不一定会捕获数据。只有标签为 > + ``=`` 时，才会有数据字段。 > > -- 数据字段： > - 以大端十六进制格式显示。注意，这些并不是真正的机器字， > - 而只是把字节流拆成若干“字”以便阅读。因此最后一个字可能只包含 > - 1 到 4 个字节。 > - 收集的数据长度是有限的，可能小于数据长度字段中报告的值。 > - 因为数据长度字段只统计实际接收到的字节，而数据字段包含整个传输缓冲区， > - 所以，在等时输入（Zi）完成且缓冲区中接收到的数据稀疏的情况下， > - 收集的数据长度可能大于数据长度字段的值。 > +- 数据字段：以大端十六进制格式显示。注意，这些并不是真正的机器字，只是为 > + 了便于阅读，把字节流按“字”分组显示。因此最后一个字可能只包含 1 到 4 个 > + 字节。捕获的数据长度是有限的，可能小于数据长度字段中报告的值。对于等时 > + 输入（Zi）完成事件，如果缓冲区里的接收数据比较稀疏，捕获数据的长度甚至 > + 可能大于数据长度字段，因为后者只统计实际接收到的字节，而数据字段展示的 > + 是整个传输缓冲区。 > > > > @@ -234,18 +198,16 @@ usbmon 报告的是各个外设驱动 > d5ea89a0 3575914555 SCi:1:001:0 s a3 00 0000 0003 0004 4 < > d5ea89a0 3575914560 CCi:1:001:0 0 4 = 01050000 > > -向地址为 5 的存储设备发送 > -31 字节 Bulk 包装的 SCSI 命令 ``0x28`` > -（``READ_10``）的输出批量传输:: > +向地址为 5 的存储设备发送一个输出批量传输，其中 31 字节的 Bulk 封装用于承 > +载 SCSI 命令 ``0x28``（``READ_10``）:: > > dd65f0e8 4128379752 SBo:1:005:2 -115 31 = 55534243 ad000000 00800000 80010a28 20000000 20000040 00000000 000000 > dd65f0e8 4128379808 CBo:1:005:2 0 31 > > > 原始二进制格式与 API > ==================== > -API 的整体架构与前文大体相同，只是事件以二进制格式传递。 > -每个事件都通过下面的结构发送 > -（这个名字是为了叙述方便而虚构的）:: > +API 的整体架构与前文大体相同，只是事件以二进制格式传递。每个事件都通过 > +下面的结构发送（这个结构名只是为了叙述方便而虚构的）:: > > > struct usbmon_packet { > @@ -275,29 +237,22 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 > unsigned int ndesc; /* 60: 实际 ISO 描述符数量 */ > }; /* 64 总长度 */ > > -可以用 ``read(2)``、``ioctl(2)``， > -或者通过 ``mmap`` 访问缓冲区， > -从字符设备接收这些事件。 > -不过，出于兼容性原因，``read(2)`` > -只返回前 48 个字节。 > +可以用 ``read(2)``、``ioctl(2)``，或者通过 ``mmap`` 访问缓冲区，从字符设 > +备接收这些事件。不过，出于兼容性原因，``read(2)`` 只返回前 48 个字节。 > > -字符设备通常命名为 ``/dev/usbmonN``， > -其中 ``N`` 是 USB 总线号。 > -编号为零的设备（``/dev/usbmon0``）比较特殊， > -表示“所有总线”。 > -请注意，具体命名策略由 Linux 发行版决定。 > +字符设备通常命名为 ``/dev/usbmonN``，其中 ``N`` 是 USB 总线号。编号为零的 > +设备（``/dev/usbmon0``）比较特殊，表示“所有总线”。具体命名策略由 Linux > +发行版决定。 > > -如果你手动创建 ``/dev/usbmon0``， > -请确保它归 root 所有，并且权限为 ``0600``。 > -否则，非特权用户将能够窃听键盘流量。 > +如果你手动创建 ``/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)`` > @@ -309,31 +264,28 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 > u32 dropped; > }; > > -成员 ``queued`` 表示当前缓冲区中已经排队的事件数量， > -而不是自上次重置以来处理过的事件数量。 > +成员 ``queued`` 表示当前缓冲区中已经排队的事件数量，而不是自上次重置以来 > +处理过的事件数量。 > > -成员 ``dropped`` 表示自上次调用 > -``MON_IOCG_STATS`` 以来丢失的事件数量。 > +成员 ``dropped`` 表示自上次调用 ``MON_IOCG_STATS`` 以来丢失的事件数量。 > > ``MON_IOCT_RING_SIZE``，定义为 ``_IO(MON_IOC_MAGIC, 4)`` > > -此调用设置缓冲区大小。参数为以字节为单位的缓冲区大小。 > -大小可能会向下取整到下一个块（或页）。 > -如果请求的大小超出该内核的 [未指定] 范围， > -则调用会失败并返回 ``-EINVAL``。 > +此调用设置缓冲区大小。参数是以字节为单位的缓冲区大小。大小可能会向下取整 > +到下一个块（或页）。如果请求的大小超出当前内核允许的范围，则调用会失败并 > +返回 ``-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)`` > +``MON_IOCX_GET`` 和 ``MON_IOCX_GETX`` 的定义分别如下： > + > +- ``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 { > @@ -343,20 +295,18 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 > }; > > > -调用前，应填好 ``hdr``、``data`` 和 ``alloc``。 > -调用返回后，``hdr`` 指向的区域中包含下一个事件的结构； > -如果存在数据，那么数据缓冲区中也会包含相应数据。 > -该事件会从内核缓冲区中移除。 > +调用前，应填好 ``hdr``、``data`` 和 ``alloc``。调用返回后，``hdr`` 指向的 > +内存区域中会写入下一个事件的结构；如果存在数据，数据缓冲区中也会填入相应 > +内容。该事件会从内核缓冲区中移除。 > > -``MON_IOCX_GET`` 会将 48 字节的数据复制到 ``hdr`` 区域， > -``MON_IOCX_GETX`` 会复制 64 字节。 > +``MON_IOCX_GET`` 会将 48 字节的数据复制到 ``hdr`` 区域，``MON_IOCX_GETX`` > +会复制 64 字节。 > > ``MON_IOCX_MFETCH``，定义为 > ``_IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg)`` > > -当应用程序通过 ``mmap(2)`` 访问缓冲区时， > -主要使用这个 ioctl。 > -其参数是指向以下结构的指针:: > +应用程序通过 ``mmap(2)`` 访问缓冲区时，主要使用这个 ioctl。其参数是指向 > +以下结构的指针:: > > struct mon_mfetch_arg { > uint32_t *offvec; /* 获取的事件偏移向量 */ > @@ -365,41 +315,36 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 > }; > > > -该 ioctl 的操作分为三个阶段： > +这个 ioctl 的流程分为三个阶段： > > -首先，从内核缓冲区移除并丢弃最多 ``nflush`` 个事件。 > -实际丢弃的事件数量会写回 ``nflush``。 > +首先，从内核缓冲区移除并丢弃最多 ``nflush`` 个事件。实际丢弃的事件数量会 > +写回 ``nflush``。 > > -其次，除非伪设备以 ``O_NONBLOCK`` 打开，否则会一直等待， > -直到缓冲区中出现事件。 > +其次，除非设备以 ``O_NONBLOCK`` 打开，否则会一直等待，直到缓冲区中出现 > +事件。 > > -第三，将最多 ``nfetch`` 个偏移量提取到 mmap > -缓冲区，并存入 ``offvec`` 中。 > -实际提取到的事件偏移数量会存回 ``nfetch``。 > +第三，将最多 ``nfetch`` 个偏移量提取到 mmap 缓冲区，并存入 ``offvec`` 中。 > +实际提取到的事件偏移数量会写回 ``nfetch``。 > > ``MON_IOCH_MFLUSH``，定义为 ``_IO(MON_IOC_MAGIC, 8)`` > > -此调用从内核缓冲区移除若干事件。 > -其参数为要移除的事件数量。 > -如果缓冲区中的事件少于请求数量， > -则移除所有事件，且不报告错误。 > -当没有事件时也可使用。 > +此调用从内核缓冲区移除若干事件。其参数是要移除的事件数量。如果缓冲区中的 > +事件少于请求数量，则移除全部现有事件，且不报告错误。即使当前没有事件，也 > +可以调用。 > > ``FIONBIO`` > > 如果有需要，将来可能会实现 ``FIONBIO`` ioctl。 > > -除了 ``ioctl(2)`` 和 ``read(2)`` 之外， > -二进制 API 的特殊文件也可以用 ``select(2)`` 和 > -``poll(2)`` 轮询。 > -但 ``lseek(2)`` 不起作用。 > +除了 ``ioctl(2)`` 和 ``read(2)`` 之外，二进制 API 对应的特殊文件还可以用 > +``select(2)`` 和 ``poll(2)`` 轮询，但 ``lseek(2)`` 不可用。 > > * 二进制 API 的内核缓冲区内存映射访问 > > -基本思想很简单： > +基本思路很简单： > > -准备时，先获取当前大小，再用 ``mmap(2)`` 映射缓冲区。 > -然后执行类似下面伪代码的循环:: > +准备时，先查询当前大小，再用 ``mmap(2)`` 映射缓冲区。之后运行与下面伪代码 > +类似的循环:: > > struct mon_mfetch_arg fetch; > struct usbmon_packet *hdr; > @@ -411,7 +356,7 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 > ioctl(fd, MON_IOCX_MFETCH, &fetch); // 同时处理错误 > nflush = fetch.nfetch; // 完成后要刷新这么多包 > for (i = 0; i < nflush; i++) { > - hdr = (struct ubsmon_packet *) &mmap_area[vec[i]]; > + hdr = (struct usbmon_packet *) &mmap_area[vec[i]]; > if (hdr->type == '@') // 填充包 > continue; > caddr_t data = &mmap_area[vec[i]] + 64; > @@ -421,7 +366,7 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 > > > > -因此，主要思想是每 N 个事件只执行一次 ioctl。 > +因此，这里的核心思路就是每 N 个事件只执行一次 ioctl。 > > -虽然缓冲区是环形的，但返回的头和数据不会跨越缓冲区末端， > -因此上面的伪代码无需任何合并操作。 > +虽然缓冲区是环形的，但返回的头部和数据不会跨越缓冲区末端，因此上面的伪代 > +码无需做任何拼接。 > -- 2.34.1 > ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v3] docs/zh_CN: usb: refine translated wording and formatting 2026-06-01 4:00 ` Alex Shi @ 2026-06-01 6:19 ` Kefan Bai 0 siblings, 0 replies; 5+ messages in thread From: Kefan Bai @ 2026-06-01 6:19 UTC (permalink / raw) To: Alex Shi Cc: linux-usb, si.yanteng, gregkh, dzm91, corbet, skhan, linux-doc, linux-kernel, doubled, alexs On Mon, 1 Jun 2026 12:00:03 +0800 Alex Shi <seakeel@gmail.com> wrote: > Hi Kefan, > > It looks fine. > > BTW, like any other kernel patches, document patch also requires a > line length limit of either 80 or 100 English characters per line > (which corresponds to 40 or 50 Chinese characters). Within the same > document, you should keep it consistent by using either the > 80-character or the 100-character limit throughout. > > You should try your best to align your patch accordingly, as this > makes it look much cleaner and more readable. To make this easier, > you can use a text editor with a column indicator (ruler) to help you > align the text, or you can use the command :set cc=80 in Vim to check > your formatting. > > Thanks > Alex Hi Alex, Thanks for taking the time to review this patch. I'll rewrap each translated USB document to maintain a consistent 80-column limit and check for any remaining formatting issues before sending v4. Thanks again for the review and the formatting reminder. Thanks, Kefan > > On 2026/6/1 11:39, Kefan Bai wrote: > > Refine the zh_CN USB translations for clarity and consistency. > > > > Improve wording, wrapping, and formatting across the translated > > USB documents. > > > > Link:https://lore.kernel.org/r/2026053149-flaky-shallow-2460@gregkh > > Suggested-by: Alex Shi<seakeel@gmail.com> > > Signed-off-by: Kefan Bai<baikefan@leap-io-kernel.com> > > --- > > v3: > > - refine the subject and commit message > > - add a Link trailer to the cleanup request thread > > - move revision notes below the cut line > > > > v2: > > - replace the obsolete FSF mailing address reference in acm.rst > > - trim the commit message to satisfy checkpatch > > > > Documentation/translations/zh_CN/usb/CREDITS | 146 ++++--- > > Documentation/translations/zh_CN/usb/acm.rst | 62 ++- > > .../translations/zh_CN/usb/authorization.rst | 79 ++-- > > .../translations/zh_CN/usb/chipidea.rst | 58 ++- > > Documentation/translations/zh_CN/usb/dwc3.rst | 37 +- > > Documentation/translations/zh_CN/usb/ehci.rst | 247 +++++------- > > .../translations/zh_CN/usb/index.rst | 18 +- > > .../translations/zh_CN/usb/usbmon.rst | 363 > > ++++++++---------- 8 files changed, 442 insertions(+), 568 > > deletions(-) > > > > diff --git a/Documentation/translations/zh_CN/usb/CREDITS > > b/Documentation/translations/zh_CN/usb/CREDITS index > > c133b1a5daff..a37958d139cc 100644 --- > > a/Documentation/translations/zh_CN/usb/CREDITS +++ > > b/Documentation/translations/zh_CN/usb/CREDITS @@ -10,12 +10,10 @@ > > :校译: > > > > > > -简易 Linux USB 驱动的致谢名单： > > +Simple Linux USB 驱动项目致谢名单： > > > > -以下人员都为 Linux USB 驱动代码作出了贡献 > > -（按姓氏字母顺序排列）。我相信这份名单本应 > > -更长一些，但确实不容易维护。 > > -如需将自己加入名单，请提交补丁。 > > +以下人员都为 Linux USB > > 驱动代码作出过贡献（按姓氏字母顺序排列）。这份名 > > +单本该更长，只是确实不易维护；如果你也应列名其中，欢迎提交补丁把自己加上。 > > Georg Acher<acher@informatik.tu-muenchen.de> > > David Brownell<dbrownell@users.sourceforge.net> > > @@ -41,123 +39,123 @@ > > 特别感谢： > > > > Inaky Perez Gonzalez<inaky@peloncho.fis.ucm.es> > > - 感谢他发起了 Linux USB 驱动开发工作，并编写了体量较大的 uusbd > > - 驱动中的大部分代码。我们从那项工作中学到了很多。 > > + 感谢他牵头开发 Linux USB 驱动，并编写了 uusbd > > 驱动的大部分代码，我们 > > + 从中学到了很多。 > > > > NetBSD 和 FreeBSD 的 USB 开发者们 > > 感谢他们加入 Linux USB 邮件列表，提供建议并分享实现经验。 > > > > -附加感谢： > > - > > 还要感谢以下公司与个人在硬件、支持、时间投入和开发方面提供的捐赠与帮助 > > - （摘自 Inaky 驱动原始的 THANKS 文件）： > > +另外还要感谢： > > > > - 以下公司曾帮助我们开发 Linux USB / UUSBD： > > + 以下公司和个人在硬件、支持、时间和开发工作上给予了帮助（摘自 > > Inaky > > + 驱动原始的 THANKS 文件）： > > > > - - 3Com GmbH 捐赠了一台 ISDN Pro > > TA，并在技术问题和测试设备方面为我 > > - 提供支持。没想到能得到这么大的帮助。 > > + 以下公司曾为 Linux USB / UUSBD 的开发提供帮助： > > > > - - USAR Systems 向我们提供了他们出色的 USB 评估套件， > > - 使我们能够测试 Linux USB 驱动对最新 USB 规范的符合性。 > > - USAR Systems 认识到保持开放操作系统与时俱进的重要性， > > - 并以硬件支持这个项目。感谢！ > > + - 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 实现。 > > + - CMD Technology, Inc. 慷慨捐赠了一块 CSA-6700 PCI 转 USB > > 控制卡， > > + 用于测试 OHCI 实现。 > > > > - - 由于他们对我们的支持，Keytronic 可以放心， > > - 他们的键盘能卖给至少 300 万 Linux 用户中的一部分。 > > + - 有了他们的支持，Keytronic 至少可以确信，其键盘能够销售给 > > 300 万 > > + Linux 用户中的一部分。 > > > > - - ing büro h doran [http://www.ibhdoran.com]! > > - 在欧洲，想给主板买一个 PC 背板 USB 连接器几乎是不可能的 > > - （我自己做的那个相当糟糕 > > :)）。现在我知道该去哪里买漂亮的 USB > > - 配件了！ > > + - 特别感谢 ing büro h doran [http://www.ibhdoran.com]。 > > + 在欧洲，想给主板配一个 PC 背板 USB > > 连接器几乎是不可能的（我自己 > > + 做的那个效果并不好）。现在我知道该去哪里购买合适的 USB > > 配件了。 > > - Genius Germany 捐赠了一只 USB > > 鼠标，用于测试鼠标启动协议； > > - 他们还捐赠了 F-23 数字摇杆和 NetMouse Pro。感谢！ > > + 他们还捐赠了 F-23 数字摇杆和 NetMouse Pro，在此致谢。 > > > > - - AVM GmbH Berlin 支持我们开发 Linux 下的 AVM ISDN > > Controller B1 USB 驱动。 > > - AVM 是领先的 ISDN 控制器制造商，其主动式设计对包括 Linux > > 在内的 > > - 所有操作系统平台开放。 > > + - AVM GmbH Berlin 支持我们开发 Linux 下的 AVM ISDN > > Controller B1 USB > > + 驱动。AVM 是领先的 ISDN > > 控制器制造商，其开放式设计适用于包括 > > + Linux 在内的所有操作系统平台。 > > > > - - 非常感谢 Y-E Data, Inc 捐赠的 FlashBuster-U USB 软驱， > > - 使我们能够测试批量传输代码。 > > + - 非常感谢 Y-E Data, Inc 捐赠的 FlashBuster-U USB > > 软驱，使我们能够测试 > > + 批量传输代码。 > > > > - 感谢 Logitech 捐赠了一只三轴 USB 鼠标。 > > > > - Logitech 负责设计、制造并销售各种人机接口设备， > > - > > 在键盘、鼠标、轨迹球、摄像头、扬声器，以及面向游戏和专业用途的 > > - 控制设备方面拥有悠久历史和丰富经验。 > > + Logitech > > 负责设计、制造并销售各种人机接口设备，在键盘、鼠标、轨迹球、 > > + > > 摄像头、扬声器，以及面向游戏和专业用途的控制设备方面拥有悠久历史和 > > + 丰富经验。 > > > > - 作为这些设备广为人知的供应商和销售商，他们捐赠了 USB > > 鼠标、 > > - 摇杆和扫描仪，以表明 Linux 的重要性，也让 Logitech 的客户 > > - 能在自己喜欢的操作系统上获得支持，并让所有 Linux > > 用户都能使用 > > - Logitech 以及其他 USB 硬件。 > > + 作为这些设备广为人知的供应商和销售商，他们捐赠了 USB > > 鼠标、摇杆和 > > + 扫描仪，以表明 Linux 的重要性，也让 Logitech > > 的客户能在自己偏爱的 > > + 操作系统上获得支持，并让所有 Linux 用户都能使用 Logitech > > 及其他 > > + USB 硬件。 > > > > Logitech 也是 1999 年 2 月 11 日维也纳 Linux > > 大会的官方赞助商，我们将在会上展示 Linux USB 工作的最新进展。 > > > > - - 感谢 CATC 提供 USB Inspector，帮助我们揭开 UHCI > > 内部实现中 > > - 那些不为人知的角落。 > > + - 感谢 CATC 提供 USB Inspector，帮助我们看到 UHCI > > 内部实现中的那些 > > + 隐秘角落。 > > > > - 感谢 Entrega 为开发工作提供 PCI 转 USB > > 卡、集线器和转换器产品。 > > - - 感谢 ConnectTech 提供 WhiteHEAT USB > > 转串口转换器以及相关文档， > > - 让这个驱动得以写成。 > > + - 感谢 ConnectTech 提供 WhiteHEAT USB > > 转串口转换器以及相关文档，让 > > + 这个驱动得以写成。 > > > > - - 感谢 ADMtek 提供 Pegasus 和 Pegasus II 评估板、规格说明， > > - 以及驱动开发过程中的宝贵建议。 > > + - 感谢 ADMtek 提供 Pegasus 和 Pegasus II > > 评估板、规格说明，以及驱动 > > + 开发过程中的宝贵建议。 > > > > - 另外还要感谢以下个人（嘿，顺序不分先后 :)） > > + 另外还要感谢以下个人（排名不分先后）： > > > > - - Oren Tirosh<orenti@hishome.net>, > > - 他非常耐心地听我唠叨各种 USB 疑问，还给了很多很酷的想法。 > > + - Oren Tirosh<orenti@hishome.net> > > + 他非常耐心地解答我反复提出的各种 USB > > 问题，并提供了许多有价值的 > > + 想法。 > > > > - - Jochen Karrer<karrer@wpfd25.physik.uni-wuerzburg.de>, > > - 指出了致命 bug，并给出了宝贵建议。 > > + - Jochen Karrer<karrer@wpfd25.physik.uni-wuerzburg.de> > > + 指出了严重问题，并给出了宝贵建议。 > > > > - - Edmund > > Humemberger<ed@atnet.at>，他在公共关系与项目管理方面 > > - 为 Linux-USB 项目付出了巨大的努力。 > > + - Edmund > > Humemberger<ed@atnet.at>，他在公共关系与项目管理方面为 > > + Linux-USB 项目付出了巨大的努力。 > > > > - - Alberto Menegazzi<flash@flash.iol.it> 正在着手编写 UUSBD > > 文档，加油！ > > + - Alberto Menegazzi<flash@flash.iol.it> 正在着手编写 UUSBD > > 文档。 > > - - Ric Klaren<ia_ric@cs.utwente.nl> 编写了很好的入门文档， > > - 与 Alberto 的作品形成良性竞争：）。 > > + - Ric Klaren<ia_ric@cs.utwente.nl> 编写了很好的入门文档，与 > > + Alberto 的作品形成了良性互补。 > > > > - - Christian > > Groessler<cpg@aladdin.de>，感谢他在那些棘手细节上的帮助。 > > + - Christian > > Groessler<cpg@aladdin.de>，感谢他在诸多复杂细节上的帮助。 > > - - Paul MacKerras 改进了 OHCI 实现，推动了对 iMac 的支持， > > - 并提供了大量的改进意见。 > > + - Paul MacKerras 改进了 OHCI 实现，推动了对 iMac > > 的支持，并提供了 > > + 大量的改进意见。 > > > > - - Fernando Herrera<fherrera@eurielec.etsit.upm.es> > > - 负责撰写、维护并不断补充那份期待已久、独一无二又精彩的 > > - UUSBD FAQ！太棒了！ > > + - Fernando Herrera<fherrera@eurielec.etsit.upm.es> > > 负责撰写、维护并 > > + 持续补充那份期待已久、内容翔实的 UUSBD FAQ。 > > > > - - Rasca Gmelch<thron@gmx.de> 重新启用了 raw 驱动， > > - 指出了一些错误，并启动了 uusbd-utils 软件包。 > > + - Rasca Gmelch<thron@gmx.de> 重新启用了 raw > > 驱动，指出了一些错误，并 > > + 启动了 uusbd-utils 软件包。 > > > > - - Peter Dettori<dettori@ozy.dec.com>，像疯了一样挖掘 bug， > > - 还提出了很多很酷的建议，太棒了！ > > + - Peter > > Dettori<dettori@ozy.dec.com>，持续发现问题，并提出了许多 > > + 有价值的建议。 > > > > - - 自由软件与 Linux 社区的所有成员，包括 FSF、GNU 项目、 > > - MIT X 联盟、TeX 社区等等，谢谢你们！ > > + - 自由软件与 Linux 社区的所有成员，包括 FSF、GNU 项目、MIT > > X 联盟、 > > + TeX 社区等，在此一并致谢。 > > > > - - 特别感谢 Richard Stallman 创造了 Emacs！ > > + - 特别感谢 Richard Stallman 创造了 Emacs。 > > > > - - 感谢 linux-usb > > 邮件列表的所有成员，读了那么多邮件——不开玩笑了， > > - 感谢你们提出的所有建议！ > > + - 感谢 linux-usb > > 邮件列表的所有成员阅读了大量邮件，并提出了诸多 > > + 建议。 > > > > - 感谢 USB Implementers Forum 成员们的帮助与支持。 > > > > - - Nathan Myers<ncm@cantrip.org>，感谢他的建议！ > > - （希望你喜欢 Cibeles 的派对。） > > + - Nathan > > Myers<ncm@cantrip.org>，感谢他的建议。（也希望你喜欢 > > + Cibeles 的派对。） > > > > - - 感谢 Linus Torvalds 创建、开发并管理 Linux。 > > + - 感谢 Linus Torvalds 创立、开发并维护 Linux。 > > > > - Mike Smith、Craig Keithley、Thierry Giron 和 Janet > > Schank > > - 感谢他们让我认识到标准 USB 集线器其实也没那么“标准”， > > - 这有助于我们在标准集线器驱动中加入厂商特定的特殊处理。 > > + 感谢他们让我认识到，标准 USB > > 集线器其实一点也不“标准”；也正因 > > + 如此，我们才能在标准集线器驱动中加入厂商特定的处理。 > > diff --git a/Documentation/translations/zh_CN/usb/acm.rst > > b/Documentation/translations/zh_CN/usb/acm.rst index > > 51d6eb8f5660..b2e35787af45 100644 --- > > a/Documentation/translations/zh_CN/usb/acm.rst +++ > > b/Documentation/translations/zh_CN/usb/acm.rst @@ -20,33 +20,26 @@ > > Linux ACM 驱动 v0.16 > > 0. 免责声明 > > ~~~~~~~~~~~ > > -本程序是自由软件；你可以在自由软件基金会发布的 > > -GNU 通用公共许可证第 2 版，或者（按你的选择） > > -任何后续版本的条款下重新发布和/或修改它。 > > +本程序是自由软件；你可以在自由软件基金会发布的 GNU > > 通用公共许可证第 2 版， > > +或者（按你的选择）任何后续版本的条款下重新发布和/或修改它。 > > -发布本程序是希望它能发挥作用，但它不附带任何担保； > > -甚至不包括对适销性或特定用途适用性的默示担保。 > > -详情见 GNU 通用公共许可证。 > > +发布本程序是希望它能发挥作用，但它不附带任何担保；甚至不包括对适销性或 > > +特定用途适用性的默示担保。详情见 GNU 通用公共许可证。 > > > > -你应该已经随本程序收到了 GNU 通用公共许可证的副本； > > -如果没有，请致信：Free Software Foundation, Inc., 59 > > -Temple Place, Suite 330, Boston, MA 02111-1307 USA。 > > +你应该已经随本程序收到了 GNU 通用公共许可证的副本；如果没有，请参见 > > +COPYING 文件。 > > > > -如需联系作者，可发送电子邮件至vojtech@suse.cz， > > -或邮寄至： > > -Vojtech Pavlik, Ucitelska 1576, Prague 8, > > -182 00, Czech Republic。 > > +如需联系作者，可发送电子邮件至vojtech@suse.cz，或邮寄至： > > +Vojtech Pavlik, Ucitelska 1576, Prague 8, 182 00, Czech Republic。 > > > > -为方便起见，软件包中已附带 GNU 通用公共许可证 > > -第 2 版：见 COPYING 文件。 > > +为方便起见，软件包中已附带 GNU 通用公共许可证第 2 版：见 COPYING > > 文件。 > > 1. 使用方法 > > ~~~~~~~~~~~ > > -``drivers/usb/class/cdc-acm.c`` 驱动可用于符合 USB > > -通信设备类抽象控制模型（USB CDC ACM）规范的 > > -USB 调制解调器和 USB ISDN 终端适配器。 > > +``drivers/usb/class/cdc-acm.c`` 驱动适用于符合 USB > > 通信设备类抽象控制模型 +（USB CDC ACM）规范的 USB 调制解调器和 USB > > ISDN 终端适配器。 > > -许多调制解调器支持此驱动，以下是我所知道的一些型号： > > +已知支持该驱动的调制解调器包括： > > > > - 3Com OfficeConnect 56k > > - 3Com Voice FaxModem Pro > > @@ -56,17 +49,16 @@ USB 调制解调器和 USB ISDN 终端适配器。 > > - Compaq 56k FaxModem > > - ELSA Microlink 56k > > > > -我知道有一款 ISDN 终端适配器可以与 ACM 驱动一起使用： > > +已知有一款 ISDN 终端适配器可以配合 ACM 驱动使用： > > > > - 3Com USR ISDN Pro TA > > > > -一些手机也可以通过 USB 连接。 > > -我知道以下机型可以正常工作： > > +一些手机也可以通过 USB 连接，已知可用的机型有： > > > > - SonyEricsson K800i > > > > -遗憾的是，许多调制解调器和大多数 ISDN TA > > -都使用专有接口，因此无法与此驱动配合工作。 > > +遗憾的是，很多调制解调器和大多数 ISDN TA > > 都使用专有接口，因此无法配合该 +驱动工作。 > > 购买前请先确认设备是否符合 ACM 规范。 > > > > 要使用这些调制解调器，需要加载以下模块:: > > @@ -75,15 +67,13 @@ USB 调制解调器和 USB ISDN 终端适配器。 > > uhci-hcd.ko ohci-hcd.ko or ehci-hcd.ko > > cdc-acm.ko > > > > -之后就应该可以访问这些调制解调器了。 > > -应当可以使用 ``minicom``、``ppp`` 和 ``mgetty`` > > -与它们通信。 > > +之后就应该能访问这些调制解调器，并用 ``minicom``、``ppp`` 和 > > +``mgetty`` 与它们通信。 > > > > 2. 验证驱动是否正常工作 > > ~~~~~~~~~~~~~~~~~~~~~~~ > > > > -第一步是检查 ``/sys/kernel/debug/usb/devices``， > > -其内容应该类似如下:: > > +第一步是查看 > > ``/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 > > @@ -112,11 +102,10 @@ USB 调制解调器和 USB ISDN 终端适配器。 > > 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.)``，那就无能为力了： > > -这说明你手上的设备使用的是厂商专有接口:: > > +关键是看这三行，再结合 ``Cls=`` 字段里出现的 ``comm`` 和 ``data`` > > 类，就 +能判断这是一台 ACM 设备。``Driver=acm`` 表示该设备正在使用 > > acm 驱动。如果 +只看到 > > ``Cls=ff(vend.)``，那就说明这台设备使用的是厂商专有接口，ACM 驱动 > > +无法处理:: > > 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 @@ -142,6 +131,5 @@ USB 调制解调器和 USB ISDN > > 终端适配器。 usb.c: acm driver claimed interface c7b5f3f8 > > usb.c: acm driver claimed interface c7691fa0 > > > > -如果以上都正常，请启动 ``minicom``， > > -把它配置为连接 ``ttyACM`` 设备，然后 > > -尝试输入 ``at``。如果返回 ``OK``，说明一切工作正常。 > > +如果这些都正常，请启动 ``minicom``，把它配置为连接到 ``ttyACM`` > > 设备，然后 +尝试输入 ``at``。如果返回 ``OK``，说明驱动工作正常。 > > diff --git a/Documentation/translations/zh_CN/usb/authorization.rst > > b/Documentation/translations/zh_CN/usb/authorization.rst index > > 2aa311f6b967..e2ff2282bd03 100644 --- > > a/Documentation/translations/zh_CN/usb/authorization.rst +++ > > b/Documentation/translations/zh_CN/usb/authorization.rst @@ -10,34 > > +10,32 @@ :校译: > > > > > > -============================= > > -授权或禁止 USB 设备连接到系统 > > -============================= > > +=========================== > > +允许或禁止 USB 设备接入系统 > > +=========================== > > > > 版权 (C) 2007 Inaky Perez-Gonzalez > > <inaky@linux.intel.com> 英特尔公司 > > > > -此功能允许你控制 USB 设备是否可以在系统中使用。 > > -借助它，你可以完全通过用户空间实现对 USB 设备的锁定。 > > +有了这项功能，你就可以控制 USB 设备是否允许在系统中使用，并把 USB > > 设备锁 +定机制完全放在用户空间实现。 > > > > -目前，当插入一个 USB 设备时，系统会对其进行配置， > > -其接口会立即向用户开放。 > > -有了这项改动，只有在 root 授权设备完成配置后， > > -设备才可被使用。 > > +目前，USB > > 设备一接入系统就会被立即配置，其接口也会立刻向用户开放。引入 > > +这项机制后，只有在 root 明确授权后，设备才会完成配置并允许使用。 > > > > 用法 > > ==== > > > > -授权设备接入:: > > +授权设备接入系统:: > > > > $ echo 1 > /sys/bus/usb/devices/DEVICE/authorized > > > > -取消对设备的授权:: > > +取消设备授权:: > > > > $ echo 0 > /sys/bus/usb/devices/DEVICE/authorized > > > > -将新连接到 ``hostX`` 的设备默认设为未授权（即锁定）:: > > +将连接到 ``hostX`` 的新设备默认设为未授权（即锁定）:: > > > > $ echo 0 > /sys/bus/usb/devices/usbX/authorized_default > > > > @@ -45,15 +43,14 @@ > > > > $ echo 1 > /sys/bus/usb/devices/usbX/authorized_default > > > > -默认情况下，所有 USB 设备都是授权的。 > > -向 ``authorized_default`` 属性写入 ``2`` 会使内核 > > -默认只授权连接到内部 USB 端口的设备。 > > +默认情况下，所有 USB 设备都是授权的。向 ``authorized_default`` > > 属性写入 +``2`` 会使内核默认只授权连接到内部 USB 端口的设备。 > > > > -系统锁定示例（比较粗糙） > > ------------------------- > > +系统锁定示例（简化版） > > +---------------------- > > > > -假设你想实现一个锁定功能，只允许类型为 XYZ 的设备接入 > > -（例如某台带有外露 USB 端口的自助服务终端）:: > > +假设你想做一个锁定机制，只允许 XYZ > > 类型的设备接入（例如一台带有外露 USB +端口的自助终端）:: > > > > 启动系统 > > rc.local -> > > @@ -63,21 +60,18 @@ > > echo 0 > $host/authorized_default > > done > > > > -给 udev 挂一个脚本，用于处理新插入的 USB 设备:: > > +为 udev 配置一个脚本，用于处理新插入的 USB 设备:: > > > > if device_is_my_type $DEV > > then > > echo 1 > $device_path/authorized > > - done > > + fi > > > > > > -``device_is_my_type()`` 才是锁定方案真正见功夫的 > > -地方。仅仅检查 class、type 和 protocol 是否匹配 > > -某个值，是你能做出的最糟糕的安全验证之一； > > -对想绕过它的人来说，这反而是最容易利用的方案。 > > -如果你需要真正安全的办法，那就该使用加密、 > > -证书认证之类的机制。把 USB 存储设备当作 > > -“钥匙”的一个简单例子可以是:: > > +锁定方案是否可靠，关键全在 ``device_is_my_type()`` 的实现。仅仅检查 > > +class、type 和 protocol > > 是否匹配，几乎是最差的一种安全校验方式；对想绕过 > > +它的人来说，这种做法反而最容易伪造。如果你真要做安全控制，就该使用加密、 > > +证书认证之类的机制。把 USB > > 存储设备当作“钥匙”的一个简单示例可以写成:: function > > device_is_my_type() { > > @@ -87,7 +81,7 @@ > > sum=$(md5sum/mntpoint/.signature) > > if [ $sum = $(cat /etc/lockdown/keysum) ] > > then > > - echo "We are good, connected" > > + echo "验证通过，已连接" > > umount /mntpoint > > # 再做一些额外处理，让其他人也能使用它 > > else > > @@ -96,17 +90,16 @@ > > } > > > > > > -当然，这个例子很粗糙；真正要做的话， > > -你会想用基于 PKI 的证书校验，这样就不必依赖 > > -共享密钥之类的东西。不过你应该已经明白意思了。 > > -任何拿到设备仿真工具包的人都能伪造描述符和设备信息。 > > -别信这个。 > > +当然，这个例子仍然比较简化。真正落地时，更合适的做法是使用基于 PKI > > 的证 > > +书校验，这样就不必依赖共享密钥之类的机制了。不过意思已经很清楚：任何拿到 > > +设备仿真工具包的人，都能伪造描述符和设备信息，所以别把这类检查当成真正 > > +的安全保障。 > > 接口授权 > > -------- > > > > -也有类似的方法用于允许或拒绝特定 USB 接口。 > > -这使得你可以只阻止某个 USB 设备中的部分接口。 > > +也可以用类似的方法允许或拒绝特定的 USB > > 接口。这样一来，你只需要阻止某个 +USB 设备中的部分接口。 > > > > 授权接口:: > > > > @@ -126,14 +119,12 @@ > > > > $ echo 0 > > > /sys/bus/usb/devices/usbX/interface_authorized_default > > -默认情况下， > > -``interface_authorized_default`` 位为 ``1``， > > -因此所有接口默认都处于已授权状态。 > > +默认情况下，``interface_authorized_default`` 位为 > > ``1``，因此所有接口默认 +都会处于授权状态。 > > > > 注意： > > - 如果把一个先前未授权的接口改为已授权， > > - 则必须通过将 ``INTERFACE`` 写入 ``/sys/bus/usb/drivers_probe`` > > - 来手动触发驱动探测。 > > + 如果把一个先前未授权的接口改为已授权，则必须通过将 ``INTERFACE`` > > 写入 > > + ``/sys/bus/usb/drivers_probe`` 来手动触发驱动探测。 > > > > -对于需要多个接口的驱动程序，应先授权所有必需接口， > > -然后再触发驱动探测。这样做可以避免副作用。 > > +对于需要多个接口的驱动程序，应先授权所有必需接口，然后再触发驱动探测。 > > +这样做可以避免副作用。 > > diff --git a/Documentation/translations/zh_CN/usb/chipidea.rst > > b/Documentation/translations/zh_CN/usb/chipidea.rst index > > ea0dc3043189..011fb16f3350 100644 --- > > a/Documentation/translations/zh_CN/usb/chipidea.rst +++ > > b/Documentation/translations/zh_CN/usb/chipidea.rst @@ -17,18 > > +17,17 @@ ChipIdea 高速双角色控制器驱动 1. 如何测试 OTG FSM（HNP 和 > > SRP） --------------------------------- > > > > -下面以两块 Freescale i.MX6Q Sabre SD 开发板为例， > > -说明如何通过 sysfs 输入文件演示 OTG 的 HNP 和 SRP 功能。 > > +下面以两块 Freescale i.MX6Q Sabre SD 开发板为例，演示如何通过 > > sysfs 属性 +测试 OTG 的 HNP 和 SRP 功能。 > > > > -1.1 如何使能 OTG FSM > > +1.1 如何启用 OTG FSM > > -------------------- > > > > 1.1.1 在 ``menuconfig`` 中选择 > > ``CONFIG_USB_OTG_FSM``，并重新编译内核 > > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > > -重新构建内核镜像和模块。如果想查看 OTG FSM 的 > > -一些内部变量，可以挂载 ``debugfs``；其中有两个文件 > > -可以显示 OTG FSM 变量以及部分控制器寄存器的值:: > > +重新构建内核镜像和模块。如果想查看 OTG FSM 的内部变量，可以挂载 > > +``debugfs``；其中有两个文件，分别显示 OTG FSM > > 的变量和部分控制器寄存器值:: > > cat /sys/kernel/debug/ci_hdrc.0/otg > > cat /sys/kernel/debug/ci_hdrc.0/registers > > @@ -44,11 +43,10 @@ ChipIdea 高速双角色控制器驱动 > > 1.2 测试步骤 > > ------------ > > > > -1) 给两块 Freescale i.MX6Q Sabre SD 开发板上电， > > - 并加载 gadget 类驱动（例如 ``g_mass_storage``）。 > > +1) 给两块 Freescale i.MX6Q Sabre SD 开发板上电，并加载 gadget > > 类驱动（例如 > > + ``g_mass_storage``）。 > > > > -2) 用 USB 线连接两块开发板： > > - 一端是 micro A 插头，另一端是 micro B 插头。 > > +2) 用 USB 线连接两块开发板：一端是 micro A 插头，另一端是 micro B > > 插头。 > > 插入 micro A 插头的一端是 A 设备，它应枚举另一端的 B 设备。 > > > > @@ -66,32 +64,28 @@ ChipIdea 高速双角色控制器驱动 > > > > echo 0 > > > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req > > - 或者，通过引入 HNP 轮询，B 端主机可以知道 > > - A 端外设希望切换为主机角色，因此这次角色切换 > > - 也可以通过 A 端外设响应 B 端主机的轮询， > > - 在 A 侧触发。 > > - 这可以通过在 A 设备上执行下面的命令来完成:: > > + 或者，也可以借助 HNP 轮询，让 B 端主机知道 A > > 端外设希望切回主机角色。 > > + 因此，这次切换也可以由 A 侧触发，也就是由 A 端外设响应 B > > 端主机的轮询 > > + 来完成。可在 A 设备上执行下面的命令:: > > > > echo 1 > > > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req > > A 设备应切回主机角色并枚举 B 设备。 > > > > -5) 拔掉 B 设备（拔掉 micro B 插头）， > > - 并在 10 秒内重新插入； > > +5) 拔掉 B 设备（拔掉 micro B 插头），并在 10 秒内重新插入。 > > A 设备应重新枚举 B 设备。 > > > > -6) 拔掉 B 设备（拔掉 micro B 插头）， > > - 并在 10 秒后重新插入； > > +6) 拔掉 B 设备（拔掉 micro B 插头），并在 10 秒后重新插入。 > > A 设备不应重新枚举 B 设备。 > > > > - 如果 A 设备希望使用总线： > > + 如果 A 设备还想继续使用总线： > > > > 在 A 设备上执行:: > > > > echo 0 > > > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop echo 1 > > > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req > > - 如果 B 设备希望使用总线： > > + 如果 B 设备想使用总线： > > > > 在 B 设备上执行:: > > > > @@ -111,40 +105,38 @@ ChipIdea 高速双角色控制器驱动 > > > > echo 1 > > > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req > > - A 设备应恢复 USB 总线并枚举 B 设备。 > > + A 设备应恢复 USB 总线，并枚举 B 设备。 > > > > 1.3 参考文档 > > ------------ > > -《On-The-Go and Embedded Host Supplement > > -to the USB Revision 2.0 Specification > > +《On-The-Go and Embedded Host Supplement to the USB Revision 2.0 > > Specification July 27, 2012 Revision 2.0 version 1.1a》 > > > > 2. 如何将 USB 用作系统唤醒源 > > ---------------------------- > > -下面是在 i.MX6 平台上把 USB 用作系统唤醒源的示例。 > > +下面给出在 i.MX6 平台上将 USB 用作系统唤醒源的示例。 > > > > -2.1 使能核心控制器的唤醒功能:: > > +2.1 启用核心控制器的唤醒功能:: > > > > echo enabled > > > /sys/bus/platform/devices/ci_hdrc.0/power/wakeup > > -2.2 使能 glue 层的唤醒功能:: > > +2.2 启用 glue 层的唤醒功能:: > > > > echo enabled > > > /sys/bus/platform/devices/2184000.usb/power/wakeup > > -2.3 使能 PHY 的唤醒功能（可选）:: > > +2.3 启用 PHY 的唤醒功能（可选）:: > > > > echo enabled > > > /sys/bus/platform/devices/20c9000.usbphy/power/wakeup > > -2.4 使能根集线器的唤醒功能:: > > +2.4 启用根集线器的唤醒功能:: > > > > echo enabled > /sys/bus/usb/devices/usb1/power/wakeup > > > > -2.5 使能相关设备的唤醒功能:: > > +2.5 启用相关设备的唤醒功能:: > > > > echo enabled > /sys/bus/usb/devices/1-1/power/wakeup > > > > -如果系统只有一个 USB 端口， > > -而你希望在该端口上启用 USB 唤醒功能， > > -可以使用下面的脚本:: > > +如果系统只有一个 USB 端口，而你希望在该端口上启用 USB > > 唤醒功能，可以使用 +下面的脚本:: > > > > for i in $(find /sys -name wakeup | grep usb);do echo > > enabled > $i;done; diff --git > > a/Documentation/translations/zh_CN/usb/dwc3.rst > > b/Documentation/translations/zh_CN/usb/dwc3.rst index > > 3468ce50c5ba..9584cbbf6d03 100644 --- > > a/Documentation/translations/zh_CN/usb/dwc3.rst +++ > > b/Documentation/translations/zh_CN/usb/dwc3.rst @@ -18,46 +18,43 @@ > > DWC3 驱动待办 ~~~~ > > > > -阅读时如果想顺手认领点任务，可以从下面挑一项 :) > > +如果你愿意接手其中一项任务，可以从下面选择： > > > > - 将中断处理程序改为每个端点各自使用线程化 IRQ > > > > - 事实证明，有些 DWC3 命令大约需要 ``~1 ms`` 才能完成。 > > - 当前代码会一直自旋等待命令完成，这种设计并不好。 > > + 实践表明，某些 DWC3 命令大约需要 ``~1 ms`` > > 才能完成。当前代码会一直自旋 > > + 等待命令完成，这并不是好办法。 > > > > 实现思路： > > > > - - DWC 核心实现了一个按端点对中断进行解复用的 IRQ 控制器。 > > - 中断号在探测（``probe``）阶段分配，并归属于该设备。 > > - 如果硬件通过 ``MSI`` 为每个端点提供独立中断， > > - 那么这个“虚拟”IRQ 控制器就可以被真实的端点中断取代。 > > + - DWC 核心实现了一个按端点分发中断的 IRQ 控制器。中断号在探测 > > + （``probe``）阶段分配，并归属于该设备。如果硬件通过 ``MSI`` > > 为每个 > > + 端点提供独立中断，那么这个“虚拟”IRQ > > 控制器就可以被真实的端点中断 > > + 取代。 > > > > - - 在调用 ``usb_ep_enable()`` 时请求并分配中断资源， > > - 在调用 ``usb_ep_disable()`` 时释放中断资源。 > > - 最坏情况下需要 32 个中断，最少是 ``ep0/1`` 的两个中断。 > > + - 在调用 ``usb_ep_enable()`` 时请求并分配中断资源，在调用 > > + ``usb_ep_disable()`` 时释放中断资源。最坏情况下需要 32 > > 个中断，最少是 > > + ``ep0/1`` 的两个中断。 > > - ``dwc3_send_gadget_ep_cmd()`` 将在 > > ``wait_for_completion_timeout()`` 中休眠，直到命令完成。 > > - 中断处理程序分为以下几个部分： > > > > - 设备级主中断处理程序 > > - 遍历每个事件，并对其调用 ``generic_handle_irq()``。 > > - 从 ``generic_handle_irq()`` > > 返回后，确认事件计数器，使中断最终消失。 > > + 遍历每个事件，并调用 ``generic_handle_irq()`` > > 处理。返回后再确认 > > + 事件计数器，让中断最终消失。 > > > > - 设备级线程化处理程序 > > 无。 > > > > - 端点中断的主处理程序 > > - 读取事件并尽量处理它。凡是需要睡眠的操作都交给线程处理。 > > - 事件保存在每个端点的数据结构中。 > > - 还要注意，一旦把某项工作交给线程处理， > > - 就不要再在主处理程序里处理它， > > - 以免出现优先级反转之类的问题。 > > + > > 读取事件并尽量处理；凡是需要睡眠的操作都交给线程处理。事件保存在 > > + > > 每个端点的数据结构中。一旦某项工作已经交给线程处理，主处理程序里就 > > + 不要再碰它，以免出现优先级反转之类的问题。 > > > > - 端点中断的线程化处理程序 > > 处理剩余的端点工作，这些工作可能会睡眠，例如等待命令完成。 > > > > - 延迟: > > + 延迟： > > > > - 不应增加延迟，因为中断线程具有较高优先级， > > - 会在普通用户态任务之前运行 > > + > > 不应增加额外延迟，因为中断线程优先级较高，会在普通用户任务之前运行（除非用户更改了调度优先级）。 > > diff --git a/Documentation/translations/zh_CN/usb/ehci.rst > > b/Documentation/translations/zh_CN/usb/ehci.rst index > > e05e493a30d3..c4c52303b13e 100644 --- > > a/Documentation/translations/zh_CN/usb/ehci.rst +++ > > b/Documentation/translations/zh_CN/usb/ehci.rst @@ -14,45 +14,37 @@ > > EHCI 驱动 > > ========= > > > > -2002年12月27日 > > +2002 年 12 月 27 日 > > > > -EHCI 驱动用于通过支持 USB 2.0 的主机控制器 > > -硬件与高速 USB 2.0 设备通信。USB 2.0 兼容 > > -USB 1.1 标准，它定义了三种传输速率： > > +EHCI 驱动用于借助支持 USB 2.0 的主机控制器，与高速 USB 2.0 > > 设备通信。USB +2.0 向下兼容 USB 1.1，并定义了三种传输速率： > > > > - “高速”（High Speed）480 Mbit/sec（60 MByte/sec） > > - “全速”（Full Speed）12 Mbit/sec（1.5 MByte/sec） > > - “低速”（Low Speed）1.5 Mbit/sec > > > > -USB 1.1 仅支持全速与低速。 > > -高速设备可以在 USB 1.1 系统上使用， > > -但速度会降到 USB 1.1 的速率。 > > +USB 1.1 仅支持全速与低速。高速设备可以在 USB 1.1 > > 系统上使用，但速度会 +降到 USB 1.1 的速率。 > > > > -USB 1.1 设备也可以在 USB 2.0 系统上使用。当它们 > > -插入 EHCI 控制器时，会被交由 USB 1.1 的伴随 > > -（companion）控制器处理，该控制器通常是 OHCI 或 UHCI。 > > +USB 1.1 设备也可以在 USB 2.0 系统上使用。当它们插入 EHCI > > 控制器时，会交给 +USB 1.1 > > 的伴随（companion）控制器处理，该控制器通常是 OHCI 或 UHCI。 > > -当 USB 1.1 设备插入 USB 2.0 集线器时，它们通过 > > -集线器中的事务转换器（Transaction Translator，TT） > > -与 EHCI 控制器交互，该转换器将低速或全速事务转换为 > > -高速分割事务，从而避免浪费传输带宽。 > > +当 USB 1.1 设备插入 USB 2.0 > > 集线器时，它们会通过集线器里的事务转换器 +（Transaction > > Translator，TT）与 EHCI 控制器通信。该转换器会把低速或全 > > +速事务转换为高速分割事务，从而避免浪费传输带宽。 > > -截至本文撰写时，该驱动已在以下 EHCI 实现上成功运行 > > -（按字母顺序）：Intel、NEC、Philips 和 VIA。 > > -其他供应商的 EHCI 实现正在陆续问世； > > -预计该驱动在这些实现上也可正常运行。 > > +截至本文撰写时，该驱动已在以下 EHCI 实现上成功运行（按字母顺序）： > > +Intel、NEC、Philips 和 VIA。随着其他供应商的 EHCI > > 实现陆续问世，预计该 +驱动在那些实现上也能正常运行。 > > > > -自 2001 年年中起，usb-storage 设备就已可用 > > -（在 2.4 版该驱动上速度相当不错）， > > -集线器则直到 2001 年底才开始可用，而其他类型的高速设备 > > -似乎要等到更多系统内置 USB 2.0 后才会出现。 > > -这类新系统从 2002 年初开始上市， > > -并在 2002 年下半年变得更加常见。 > > +自 2001 年年中起，usb-storage 设备就已可用（在 2.4 > > 版该驱动上速度表现相当 +不错），集线器则直到 2001 > > 年底才开始可用。其他类型的高速设备似乎要等到 +更多系统内置 USB 2.0 > > 后才会出现。这类新系统从 2002 年初开始上市，并在 +2002 > > 年下半年变得更加常见。 > > -注意，USB 2.0 支持并不只是 EHCI 本身。 > > -它还需要对 Linux-USB 核心 API 作出其他修改， > > -包括 hub 驱动；不过这些修改并不需要真正改变 > > -暴露给 USB 设备驱动的基本 ``usbcore`` API。 > > +注意，USB 2.0 的支持并不只靠 EHCI 本身。它还需要对 Linux-USB 核心 > > API +做其他修改，包括 hub 驱动；不过这些修改并不需要真正改变向 USB > > 设备驱动 +暴露的基本 ``usbcore`` API。 > > > > - David Brownell > > <dbrownell@users.sourceforge.net> > > @@ -61,58 +53,46 @@ USB 1.1 设备也可以在 USB 2.0 系统上使用。当它们 > > 功能 > > ==== > > > > -该驱动会定期在 x86 硬件上进行测试， > > -也已在 PPC 硬件上使用，因此大小端问题应当已经解决。 > > -因此可以认为，它已经处理好了所有必要的 PCI 细节， > > -所以即便在 DMA 映射有些特殊的系统上， > > -I/O 也应能正常运行。 > > +该驱动长期在 x86 硬件上接受测试，也在 PPC > > 平台上使用过，因此大小端问题应 +该都已解决。再加上各种必要的 PCI > > 细节都已处理妥当，即便在 DMA 映射较特 +殊的系统上，I/O > > 也应能正常工作。 > > 传输类型 > > -------- > > > > -截至本文撰写时，该驱动应当已经能够很好地处理 > > -所有控制传输、批量传输和中断传输， > > -包括通过 USB 2.0 集线器中的事务转换器 > > -与 USB 1.1 设备通信；但仍可能存在 bug。 > > +截至本文撰写时，该驱动应当已经能够稳定处理所有控制传输、批量传输和中断传 > > +输，包括经由 USB 2.0 集线器里的事务转换器访问 USB 1.1 > > 设备；不过仍可能 +存在 bug。 > > > > -高速等时（ISO）传输支持也已可用，但截至本文撰写时， > > -还没有 Linux 驱动使用这项支持。 > > +高速等时（ISO）传输支持也已可用，不过截至本文撰写时，还没有 Linux > > 驱动真 +正使用它。 > > > > -目前尚不支持通过事务转换器实现全速等时传输。 > > -需要注意，ISO 传输的 split transaction 支持 > > -与高速 ISO 传输几乎无法共用代码， > > -因为 EHCI 用不同的数据结构表示它们。 > > -因此，目前大多数 USB 音频和视频设备 > > -还不能通过高速总线连接使用。 > > +目前尚不支持通过事务转换器实现全速等时传输。需要注意，ISO > > 传输的分割 +事务支持与高速 ISO 传输几乎无法共用代码，因为 EHCI > > 用不同的数据结构表示 +它们。因此，目前大多数 USB > > 音频和视频设备还无法在高速总线上使用。 > > 驱动行为 > > -------- > > > > -所有类型的传输都可以排队。 > > -这意味着来自一个接口驱动的控制传输 > > -（或通过 usbfs 发出的控制传输）不会干扰 > > -另一个驱动的控制传输，而且中断传输可以使用 1 帧的周期， > > -而不必担心中断处理开销导致的数据丢失。 > > +所有类型的传输都可以排队提交。这意味着某个接口驱动发出的控制传输（或经由 > > +usbfs 提交的控制传输）不会干扰其他驱动的控制传输，而中断传输可以按 > > 1 帧 +周期运行，不必担心中断处理开销导致数据丢失。 > > > > > > -EHCI 根集线器代码会将 USB 1.1 设备移交给其伴随控制器。 > > -该驱动不需要了解那些驱动的任何细节； > > -一个原本就能正常工作的 OHCI 或 UHCI 驱动， > > -并不会因为 EHCI 驱动也存在而需要更改。 > > +EHCI 根集线器代码会将 USB 1.1 > > 设备交给其伴随控制器处理。该驱动无需了解 > > +那些驱动的任何细节；一个原本就能正常工作的 OHCI 或 UHCI > > 驱动，也不会因为 +EHCI 驱动存在而需要修改。 > > -电源管理方面还有一些问题； > > -当前挂起/恢复的行为还不完全正确。 > > +电源管理方面仍有一些问题；当前挂起/恢复行为还不完全正确。 > > > > -此外，在调度周期性事务 > > -（中断和等时传输）时还采取了一些简化处理。 > > -这些简化会限制可调度的周期性事务数量， > > -并且无法使用小于一帧的轮询间隔。 > > +此外，在调度周期性事务（中断和等时传输）时还采取了一些简化处理。这些 > > +简化会限制可调度的周期性事务数量，并且无法使用小于一帧的轮询间隔。 > > > > 使用方式 > > ======== > > > > -假设有一个 EHCI 控制器（位于 PCI 卡或主板上）， > > -并且已将此驱动编译为模块，可这样加载:: > > +假设系统中有一个 EHCI 控制器（位于 PCI > > 卡或主板上），并且此驱动是以模块形 +式编译的，那么可以这样加载:: > > > > # modprobe ehci-hcd > > > > @@ -120,27 +100,24 @@ EHCI 根集线器代码会将 USB 1.1 > > 设备移交给其伴随控制器。 > > # rmmod ehci-hcd > > > > -还应加载一个伴随控制器驱动， > > -例如 ``ohci-hcd`` 或 ``uhci-hcd``。 > > -如果 EHCI 驱动出现任何问题，只需卸载它的模块， > > -随后该伴随控制器驱动就会接手 > > -此前由 EHCI 驱动处理的所有设备 > > -（但速度会降低）。 > > +还应加载一个伴随控制器驱动，例如 ``ohci-hcd`` 或 > > ``uhci-hcd``。如果 EHCI > > +驱动出了问题，只要卸载它的模块，伴随控制器驱动就会接管此前由 EHCI > > 驱动处 +理的全部设备（只是速度会降低）。 > > 模块参数（传给 ``modprobe``）包括： > > > > log2_irq_thresh（默认值 0）： > > - 默认中断延迟的 log2 值，单位是微帧。默认值 0 表示 1 个微帧 > > - （125 微秒）。最大值 6 表示 2^6 = 64 个微帧。 > > + 默认中断延迟的 log2 值，单位为微帧。默认值 0 表示 1 个微帧 > > + （125 微秒），最大值 6 表示 2^6 = 64 个微帧。 > > 该值控制 EHCI 控制器发出中断的频率。 > > > > -如果在 2.5 内核上使用此驱动，并且启用了 USB 调试支持， > > -则会在任一 EHCI 控制器的 ``sysfs`` 目录中看到三个文件： > > +如果你在 2.5 内核上使用此驱动，并且启用了 USB 调试支持，那么任一 > > EHCI 控 +制器对应的 ``sysfs`` 目录下都会看到三个文件： > > > > ``async`` > > 转储异步调度，用于控制传输和批量传输。它会显示每个活动的 > > ``qh`` 以及待处理的 ``qtd``，通常每个 ``urb`` 对应一个 ``qtd``。 > > - （可以在 ``usb-storage`` 做磁盘 I/O > > 时看它；顺便观察请求队列！） > > + （可以在 ``usb-storage`` 执行磁盘 I/O > > 时查看；也可顺便观察请求队列。） > > ``periodic`` > > 转储周期性调度，用于中断传输和等时传输。不显示 ``qtd``。 > > @@ -151,111 +128,81 @@ EHCI 根集线器代码会将 USB 1.1 > > 设备移交给其伴随控制器。这些文件的内容有助于定位驱动问题。 > > > > > > -设备驱动通常不需要关心自己是否运行在 EHCI 之上， > > -但它们可能想检查 > > -``usb_device->speed == USB_SPEED_HIGH``。 > > -高速设备能做到全速（或低速）设备做不到的事， > > -例如高带宽的周期性传输（中断或 ISO 传输）。 > > -另外，设备描述符中的某些值 > > -（例如周期性传输的轮询间隔） > > -在高速模式下使用不同的编码方式。 > > +设备驱动通常不需要关心自己是否运行在 EHCI 之上，但有时可能会想检查 > > +``usb_device->speed == > > USB_SPEED_HIGH``。高速设备能做到全速（或低速）设备 > > +做不到的事，例如高带宽的周期性传输（中断或 ISO > > 传输）。另外，设备描述符 > > +中的某些值（例如周期性传输的轮询间隔）在高速模式下使用不同的编码方式。 > > -不过，一定要让设备驱动经过 USB 2.0 集线器的测试。 - > > 当使用事务转换器时，这些集线器报告某些故障 - > > （例如断开连接）的方式会不同； -已经见过一些驱动在遇到与 OHCI 或 > > UHCI -所报告的不同故障时表现不佳。 > > +不过，设备驱动一定要在 USB 2.0 > > 集线器后面测一遍。使用事务转换器时，这些 > > +集线器报告某些故障（例如断开连接）的方式会有所不同；已经见过一些驱动在 > > +遇到与 OHCI 或 UHCI 不同的故障时表现不佳。 > > 性能 > > ==== > > > > -USB 2.0 吞吐量主要受两个因素制约： > > -主机控制器处理请求的速度，以及设备响应这些请求的速度。 > > -480 Mbit/sec 的“原始传输率”对所有设备都成立， > > -但总吞吐量还会受到诸如单个高速包之间的延迟、 > > -驱动是否足够聪明，以及系统整体负载等因素的影响。 > > -延迟也是性能考量因素。 > > +USB 2.0 > > 的吞吐量主要受两个因素制约：主机控制器处理请求的速度，以及设备响 > > +应这些请求的速度。480 Mbit/sec > > 的“原始传输率”对所有设备都一样，但整体吞 > > +吐量还会受到诸如高速包之间的间隔、驱动实现是否足够高效以及系统总体负载等 > > +因素影响。延迟同样是需要考虑的性能指标。 - > > 批量传输最常用于关注吞吐量的场景。 -需要记住的是，批量传输总是以 > > 512 字节包为单位， -而一个 USB 2.0 微帧中最多只能容纳 13 > > 个这样的包。 -8 个 USB 2.0 微帧构成一个 USB 1.1 帧； > > -一个微帧的时长是 1 毫秒 / 8 = 125 微秒。 > > +批量传输通常用于看重吞吐量的场景。需要记住的是，批量传输总是以 512 > > 字节包 +为单位，而一个 USB 2.0 微帧中最多只能容纳 13 个这样的包。8 > > 个 USB 2.0 微 +帧构成一个 USB 1.1 帧，因此一个微帧的时长就是 125 > > 微秒。 > > -因此，只要硬件和设备驱动软件都允许， > > -批量传输可提供超过 50 MByte/sec 的带宽。 > > -周期性传输模式（等时和中断）允许使用更大的包大小， > > -从而可以逼近所宣称的 480 Mbit/sec 传输率。 > > +因此，只要硬件和驱动实现都足够成熟，批量传输就可以提供 50 > > MByte/sec 以上 > > +的带宽。周期性传输模式（等时和中断）允许使用更大的包大小，从而可以逼近所 > > +宣称的 480 Mbit/sec 传输率。 > > 硬件性能 > > -------- > > > > -截至本文撰写时，单个 USB 2.0 设备的最大传输速率 > > -通常约为 20 MByte/sec。 > > -这当然会随着时间改变：一些设备现在更快，一些更慢。 > > +截至本文撰写时，单个 USB 2.0 设备的最大传输速率通常约为 20 > > MByte/sec。 > > +这种情况当然会随时间变化：有些设备现在更快，有些则更慢。 > > -第一代 NEC EHCI 实现似乎存在 > > -大约 28 MByte/sec 的硬件瓶颈。 > > -虽然这对单个 20 MByte/sec 的设备显然已经够用， > > -但把三个这样的设备挂到同一总线上， > > -并不能得到 60 MByte/sec。 > > -问题似乎在于控制器硬件无法并发进行 USB 与 PCI 访问， > > -因此它每个微帧只会尝试 6 次（也许是 7 次） > > -USB 事务，而不是 13 次。 > > -（对一个比其他产品早上市一年的芯片来说， > > -这是个合理的妥协！） > > +第一代 NEC EHCI 实现似乎存在大约 28 MByte/sec > > 的硬件瓶颈。虽然这对单个 +20 MByte/sec > > 的设备显然已经够用，但把三个这样的设备挂到同一总线上，并不 +能得到 > > 60 MByte/sec。问题似乎在于控制器硬件无法并发进行 USB 与 PCI 访问， > > +因此它每个微帧只会尝试 6 次（也许是 7 次）USB 事务，而不是 13 次。 > > +（对一款比其他产品早上市一年的芯片来说，这样的取舍也算合理。） > > > > -预计较新的实现会在这方面做得更好， > > -通过投入更多芯片面积来解决这个问题， > > -使新的主板芯片组更接近 60 MByte/sec 的目标。 > > -这既包括 NEC 的更新实现，也包括其他厂商的芯片。 > > +预计较新的实现会在这方面做得更好，通过投入更多芯片面积来解决这个问题， > > +使新的主板芯片组更接近 60 MByte/sec 的目标。这既包括 NEC > > 的更新实现，也 +包括其他厂商的芯片。 > > > > > > -主机从 EHCI 控制器收到“请求已完成”中断的最小延迟 > > -为一个微帧（125 微秒）。该延迟可以调节； > > -驱动提供了一个模块选项。默认情况下， > > -``ehci-hcd`` 使用最小延迟，这意味着当发出一个控制 > > -或批量请求时，通常可以在不到 250 微秒内得知它已完成 > > -（具体取决于传输大小）。 > > +主机从 EHCI 控制器收到“请求已完成”中断的最小延迟为一个微帧 > > +（125 微秒）。该延迟可以调节；驱动提供了一个模块选项。 > > +默认情况下，``ehci-hcd`` > > 使用最小延迟，这意味着发出控制或批量请求后，通 +常不到 250 > > 微秒就能得知它已经完成（具体取决于传输大小）。 > > 软件性能 > > -------- > > > > -即便只是要达到 20 MByte/sec 的传输速率， > > -Linux-USB 设备驱动也必须让 EHCI 队列始终保持满载。 > > -这意味着要发出较大的请求， > > -或者在需要发出一连串小请求时使用批量请求排队。 > > -如果驱动未做到这一点，那么会直接从性能结果上表现出来。 > > +即便只是要达到 20 MByte/sec 的传输速率，Linux-USB 设备驱动也必须让 > > EHCI > > +队列始终保持满载。这意味着要发出较大的请求，或者在需要发出一连串小请求 > > +时使用批量请求排队。如果驱动做不到这一点，性能就会明显受影响。 > > > > -在典型情况下，使用 ``usb_bulk_msg()`` > > -以 4 KB 块循环写出， > > -会浪费超过一半的 USB 2.0 带宽。 > > -I/O 完成与驱动发出下一次请求之间的延迟， > > -通常会比一次 I/O 本身耗时更长。 > > -如果同样的循环改用 16 KB 块，会好一些； > > -若使用一连串 128 KB 块，则浪费会少得多。 > > +在典型场景下，如果使用 ``usb_bulk_msg()`` 以 4 KB > > 块循环写出，会浪费超过 +一半的 USB 2.0 带宽。I/O > > 完成与驱动发出下一次请求之间的空档，往往比一次 +I/O > > 本身耗时还长。如果同样的循环改用 16 KB > > 块，情况会好一些；若使用一连串 +128 KB 块，则浪费会少得多。 > > +但与其依赖这么大的 I/O 缓冲区来提升同步 I/O > > 的效率，不如直接向主机控制器 > > +排队提交多个（批量）请求，然后等待它们全部完成（或在出错时取消）。这种 > > +URB 排队方式对所有 USB 1.1 主机控制器驱动同样适用。 > > -但与其依赖这么大的 I/O 缓冲区来让同步 I/O 高效， > > -不如直接向主机控制器排入多个（批量）请求， > > -然后等待它们全部完成（或在出错时取消）。 > > -这种 URB 排队方式对所有 USB 1.1 > > -主机控制器驱动也同样适用。 > > > > - > > -在 Linux 2.5 内核中，定义了新的 ``usb_sg_*()`` API； > > -它们会把 scatterlist 中的所有缓冲区都排入队列。 > > -它们还使用 scatterlist 的 DMA 映射 > > -（其中可能应用 IOMMU）并减少中断次数， > > -这些都有助于让高速传输尽可能快地运行。 > > +在 Linux 2.5 内核中，定义了新的 ``usb_sg_*()`` API；它们会把 > > scatterlist +中的所有缓冲区都排入队列。它们还使用 scatterlist 的 > > DMA 映射（其中可能 +应用 > > IOMMU）并减少中断次数，这些都有助于让高速传输尽可能快地运行。 > > 待办： > > 中断传输和等时（ISO）传输的性能问题。 > > - > > 这些周期性传输都是完全调度的，因此，主要问题可能在于如何触发高带宽模式。 > > + > > 这些周期性传输都是完全调度的，因此主要问题可能在于如何触发高带宽模式。 > > 待办： > > - 通过 ``sysfs`` 中的 ``uframe_periodic_max`` 参数， > > - 可以分配超过标准 80% 的周期性带宽。 > > + 通过 ``sysfs`` 中的 ``uframe_periodic_max`` > > 参数，可以分配超过标准 > > + 80% 的周期性带宽。 > > 后续将对此进行说明。 > > diff --git a/Documentation/translations/zh_CN/usb/index.rst > > b/Documentation/translations/zh_CN/usb/index.rst index > > eb5aca0c13ec..df99814c6497 100644 --- > > a/Documentation/translations/zh_CN/usb/index.rst +++ > > b/Documentation/translations/zh_CN/usb/index.rst @@ -1,4 +1,14 @@ > > .. SPDX-License-Identifier: GPL-2.0 > > + > > +.. only:: subproject and latex > > + > > + .. raw:: latex > > + > > + \renewcommand{\thesection}{} > > + \renewcommand{\thesubsection}{} > > + \kerneldocCJKon > > + \kerneldocBeginSC{ > > + > > .. include:: ../disclaimer-zh_CN.rst > > > > :Original: Documentation/usb/index.rst > > @@ -24,7 +34,7 @@ USB 支持 > > ehci > > usbmon > > > > -Todolist: > > +待翻译文档： > > > > * functionfs > > * functionfs-desc > > @@ -52,3 +62,9 @@ Todolist: > > ==== > > > > * :ref:`genindex` > > + > > +.. only:: subproject and latex > > + > > + .. raw:: latex > > + > > + }\kerneldocEndSC > > diff --git a/Documentation/translations/zh_CN/usb/usbmon.rst > > b/Documentation/translations/zh_CN/usb/usbmon.rst index > > 11b6d5b59dce..bbfcbf875e26 100644 --- > > a/Documentation/translations/zh_CN/usb/usbmon.rst +++ > > b/Documentation/translations/zh_CN/usb/usbmon.rst @@ -16,67 +16,56 > > @@ usbmon > > 简介 > > ==== > > -小写形式的 ``usbmon`` 指的是内核中的一项功能， > > -用于收集 USB 总线上的 I/O 跟踪信息。它类似于网络监控工具 > > -``tcpdump(1)`` 或 Ethereal 所使用的数据包套接字。 > > -类似地，人们希望使用 usbdump 或 USBMon > > -（首字母大写）之类的工具来检查 > > -usbmon 生成的原始跟踪数据。 > > - > > -usbmon 报告的是各个外设驱动 > > -向主机控制器驱动（HCD）发出的请求。 > > -因此，如果 HCD 本身有 bug，那么 usbmon 报告的跟踪信息 > > -可能无法精确对应实际的总线事务。 > > -这和 tcpdump 的情况是一样的。 > > - > > -目前实现了两种 API: ``text`` 和 ``binary``。 > > -二进制 API 通过 ``/dev`` 命名空间中的字符设备提供， > > -并且属于 ABI。文本 API 自内核 2.6.35 起已废弃， > > -但为了方便仍然可用。 > > +小写的 ``usbmon`` 指的是内核中的一项功能，用于收集 USB 总线上的 > > I/O 跟踪 +信息。它类似于网络监控工具 ``tcpdump(1)`` 或 Ethereal > > 使用的数据包套接 +字。通常会用 usbdump 或 > > USBMon（首字母大写）之类的工具来查看 usbmon 生成 +的原始跟踪数据。 > > + > > +usbmon > > 记录的是各个设备驱动向主机控制器驱动（HCD）发出的请求。因此，如果 > > +HCD 自身有 bug，usbmon > > 输出的跟踪信息就未必能和真实的总线事务一一对应。 +这和 tcpdump > > 的情况类似。 + +目前实现了两种 API：``text`` 和 ``binary``。二进制 > > API 通过 ``/dev`` 下的 +字符设备提供，是 ABI 的一部分。文本 API > > 自内核 2.6.35 起已废弃，但为了 +兼容和使用方便，至今仍然保留。 > > > > 如何使用 usbmon 收集原始文本跟踪信息 > > ==================================== > > > > -与数据包套接字不同，usbmon 提供了一种接口， > > -可以输出文本格式的跟踪信息。这样做有两个目的： > > -第一，在更完善的格式最终确定之前， > > -它作为工具间通用的跟踪交换格式； > > -第二，在不使用工具的情况下，人们也可以直接阅读这些信息。 > > +与数据包套接字不同，usbmon > > 还提供了一个输出文本格式跟踪信息的接口。这样 > > +做主要有两个目的：一是在更完善的格式最终确定之前，将其作为工具间通用的跟 > > +踪交换格式；二是在没有工具时也能直接阅读这些信息。 > > -要收集原始文本跟踪信息，请按以下步骤进行操作。 > > +要收集原始文本跟踪信息，按下面的步骤做即可。 > > > > 1. 准备 > > ------- > > > > -挂载 debugfs（内核配置中必须启用它），并加载 usbmon 模块 > > -（如果它是作为模块构建的）。如果 usbmon 已经编入内核， > > -那么第二步可以省略。 > > +挂载 debugfs（内核配置里必须启用它），并加载 usbmon > > 模块（如果它是以模块 +方式构建的）。如果 usbmon > > 已经编译进内核，这一步就可以省略。 > > 命令示例:: > > > > - # mount -t debugfs none_debugs /sys/kernel/debug > > + # mount -t debugfs none /sys/kernel/debug > > # modprobe usbmon > > # > > > > -确认总线套接字是否存在:: > > +确认 ``usbmon`` 目录下是否有这些条目:: > > > > # ls /sys/kernel/debug/usb/usbmon > > 0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u > > # > > > > -现在，你可以选择使用 ``0u`` 捕获所有总线上的数据包， > > -并跳到第 3 步； > > -也可以先按第 2 步找到目标设备所在的总线。 > > -这样可以过滤掉那些持续输出数据的烦人设备。 > > +现在，你可以直接用 ``0u`` 捕获所有总线上的数据包，然后跳到第 3 > > 步；也可 +以先按第 2 > > 步找出目标设备所在的总线。这样可以把那些持续产生流量的设备过 +滤掉。 > > > > 2. 查找目标设备连接的是哪条总线 > > ------------------------------- > > > > -运行 ``cat /sys/kernel/debug/usb/devices``， > > -找到对应设备的 T 行。通常可以通过厂商字符串来查找。 > > -如果有许多类似设备，可以拔掉其中一个， > > -再比较前后两次 ``/sys/kernel/debug/usb/devices`` > > -的输出。T 行里会包含总线编号。 > > +运行 ``cat /sys/kernel/debug/usb/devices``，找到对应设备的 T > > 行。通常可以通过 > > +厂商字符串来查找。如果有很多相似设备，可以拔掉其中一个，再比较前后两次 > > +``/sys/kernel/debug/usb/devices`` 的输出。T 行里会包含总线编号。 > > 示例:: > > > > @@ -86,8 +75,8 @@ usbmon 报告的是各个外设驱动 > > S: Manufacturer=ATEN > > S: Product=UC100KM V2.00 > > > > -``Bus=03`` 表示它位于 3 号总线上。或者， > > -也可以查看 ``lsusb`` 的输出，并从对应行得到总线编号。 > > +``Bus=03`` 表示它位于 3 号总线上。或者，也可以查看 ``lsusb`` > > 的输出，并从 +对应条目里找到总线编号。 > > > > 示例如下:: > > > > @@ -97,133 +86,108 @@ usbmon 报告的是各个外设驱动 > > 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 盘、拷贝文件、操作摄像头等。 > > +这里做一些会产生 USB 流量的操作即可，比如插入 U > > 盘、拷贝文件、操作摄像头 +等。 > > > > > > 5. 停止 cat > > ----------- > > > > -这一步通常通过键盘中断（Control-C）完成。 > > +这一步通常按下键盘中断（Control-C）即可完成。 > > > > -此时输出文件（本例中为 ``/tmp/1.mon.out``） > > -可以保存、通过电子邮件发送，或使用文本编辑器查看。 > > -如果使用最后一种方式，请确保文件不会大到编辑器无法打开。 > > +此时，输出文件（本例中为 > > ``/tmp/1.mon.out``）可以保存下来，通过电子邮件发 > > +送，也可以用文本编辑器查看。如果要用文本编辑器查看，请确保文件大小不会 > > +大到编辑器无法处理。 > > > > 原始文本数据格式 > > ================ > > > > -目前支持两种格式：原始格式，也就是 ``1t`` 格式， > > -以及 ``1u`` 格式。``1t`` 格式在内核 2.6.21 中已被废弃。 > > -``1u`` 格式增加了一些字段，例如 ISO 帧描述符、 > > -``interval`` 等。它生成的行会稍长一些， > > -但在其他方面是 ``1t`` 格式的完整超集。 > > - > > -如果程序需要区分上述两种格式， > > -可以查看 ``address`` 字段（见下文）。 > > -如果其中有两个冒号，就是 ``1t`` 格式； > > -否则是 ``1u`` 格式。 > > - > > -任何文本格式的数据由一系列事件组成， > > -如 URB 提交、URB 回调、提交错误等。 > > -每个事件对应单独的一行文本， > > -由使用空白符间隔的若干字段组成。 > > -字段的数量与位置可能取决于事件类型， > > -但以下字段对所有类型都通用： > > - > > -下面按从左到右的顺序列出这些共有字段： > > - > > -- URB Tag。用于标识 URB，通常是 URB 结构体在内核中的地址 > > - （以十六进制表示）， > > - 但也可能是序号或其他合理的唯一字符串。 > > - > > -- 时间戳（微秒），十进制数字。 > > - 时间戳的精度取决于可用时钟， > > - 因此可能远差于 > > - 1 微秒（例如实现使用的是 jiffies）。 > > - > > -- 事件类型。它表示的是事件的格式，而不是 URB 的类型。 > > - 可用值为：``S`` 表示提交，``C`` 表示回调，``E`` 表示提交错误。 > > - > > -- ``Address`` 字段（以前称作 ``pipe``）。 > > - 它包含四个由冒号分隔的字段： > > - URB 类型及方向、总线号、设备地址和端点号。类型与方向的编码如下： > > - > > - == == ========================== > > - Ci Co 控制输入和输出 > > - Zi Zo 等时输入和输出 > > - Ii Io 中断输入和输出 > > - Bi Bo 批量输入和输出 > > - == == ========================== > > - > > - 总线号、设备地址和端点号使用十进制，但可能有前导零。 > > - > > -- URB 状态字段。这个字段要么是一个字母， > > - 要么是几个由冒号分隔的数字： > > - URB 状态、``interval``、``start frame`` 和 ``error count``。 > > - 与 ``address`` 字段不同，除了状态外，其余字段都是可选的。 > > - ``interval`` 只会为中断和等时 URB 打印；``start frame`` 只会为 > > - 等时 URB 打印；错误计数只会在等时回调事件中打印。 > > - > > - 状态字段是一个十进制数字，有时为负数， > > - 对应 URB 的 ``status`` 字段。 > > - 对于提交事件，这个字段本身没有实际意义， > > - 但为了便于脚本解析，它仍然存在。 > > - 当发生错误时，该字段包含错误码。 > > - > > - 在提交控制包时，这个字段包含的是 ``Setup Tag``， > > - 而不是一组数字。 > > - 判断 ``Setup Tag`` 是否存在很容易，因为它从来不是数字。 > > - 因此，如果脚本在这个字段里发现的是一组数字， > > - 就会继续读取数据长度（等时 URB 除外）。 > > - 如果发现的是其他内容，比如一个字母， > > - 那么脚本会先读取 ``Setup`` 包，再读取数据长度或等时描述符。 > > - > > -- ``Setup`` 包由 5 个字段组成： > > - ``bmRequestType``、``bRequest``、``wValue``、 > > - ``wIndex`` 和 ``wLength``。这些字段由 USB 2.0 规范定义。 > > - 如果 ``Setup Tag`` 为 ``s``，就可以安全地解码这些字段。 > > - 否则，说明 Setup > > 包虽然存在，但并未被捕获，此时各字段中会填入占位内容。 > > +目前支持两种格式：原始的 ``1t`` 格式和 ``1u`` 格式。``1t`` > > 格式在内核 +2.6.21 中已被废弃。``1u`` 格式增加了一些字段，例如 ISO > > 帧描述符和 +``interval``。它生成的行会稍长一些，但除此之外，它是 > > ``1t`` 格式的完整 +超集。 + > > +如果程序需要区分上述两种格式，可以查看 ``address`` > > 字段（见下文）。如果 +其中有两个冒号，就是 ``1t`` 格式；否则是 > > ``1u`` 格式。 + > > +任何文本格式的数据都由一系列事件构成，例如 URB 提交、URB > > 回调和提交错 > > +误。每个事件占一行，由若干以空白符分隔的字段组成。字段数量和位置会随事件 > > +类型变化，但下面这些字段对所有类型都通用： + > > +下面按从左到右的顺序说明这些通用字段： > > + > > +- URB 标识（URB Tag）。用于标识 URB，通常是 URB > > 结构体在内核中的地址 > > + （十六进制），也可能是序号或其他足以唯一标识 URB 的字符串。 > > + > > +- > > 时间戳（微秒），十进制数字。时间戳的精度取决于可用时钟，所以可能远低于 > > + 1 微秒（例如实现使用 jiffies 时）。 > > + > > +- 事件类型。它表示的是这一行事件的格式，而不是 URB > > 的类型。可用值为： > > + ``S`` 表示提交，``C`` 表示回调，``E`` 表示提交错误。 > > + > > +- ``Address`` 字段（以前称为 > > ``pipe``）。它包含四个由冒号分隔的字段：URB > > + 类型及方向、总线号、设备地址和端点号。类型与方向的编码如下： > > + > > + - ``Ci`` / ``Co``：控制输入 / 输出 > > + - ``Zi`` / ``Zo``：等时输入 / 输出 > > + - ``Ii`` / ``Io``：中断输入 / 输出 > > + - ``Bi`` / ``Bo``：批量输入 / 输出 > > + > > + > > 总线号、设备地址和端点号都是十进制数，但可能有前导零，方便人阅读。 + > > +- URB > > 状态字段。这个字段要么是一个字母，要么是几个用冒号分隔的数字，依次 > > + 表示 URB 状态、``interval``、``start frame`` 和 ``error > > count``。与 > > + ``address`` 字段不同，除状态外，其余字段都可能省略。``interval`` > > 只会在 > > + 中断和等时 URB 中打印；``start frame`` 只会在等时 URB > > 中打印；错误计数只 > > + 会在等时回调事件中打印。 > > + > > + 状态字段是一个十进制数，有时为负数，对应 URB 的 ``status`` > > 字段。对于提 > > + > > 交事件，这个字段本身并无实际语义，但为了便于脚本解析仍会保留。发生错误 > > + 时，这里填的是错误码。 > > + > > + 如果是控制包的提交事件，这个字段里放的不是一组数字，而是 ``Setup > > Tag``。 > > + 这很容易分辨，因为 ``Setup Tag`` > > 永远不是数字。所以脚本如果在这里读到一 > > + 组数字，就会继续读取数据长度（等时 URB > > 除外）；如果读到的是字母之类的内 > > + 容，就要先读取 ``Setup`` 包，再读取数据长度或等时描述符。 > > + > > +- ``Setup`` 包由 5 > > 个字段组成：``bmRequestType``、``bRequest``、``wValue``、 > > + ``wIndex`` 和 ``wLength``。这些字段由 USB 2.0 规范定义。如果 > > ``Setup Tag`` > > + 是 ``s``，就可以安全解码这些字段。否则，说明 Setup > > 包虽然存在，但并未被 > > + 捕获，此时各字段中会填入占位内容。 > > > > - 等时传输帧描述符的数量及其内容： > > - 如果一个等时传输事件带有一组描述符，首先打印该 URB > > 中描述符的总数， > > - 然后为每个描述符打印一个字段，最多打印 5 个字段。 > > - 每个字段由三个用冒号分隔的十进制数字组成， > > - 分别表示状态（status）、偏移（offset）和长度（length）。 > > - 对于提交（submission），报告的是初始长度； > > - 对于回调（callback），报告的是实际长度。 > > + 如果某个等时传输事件带有描述符，会先打印该 URB > > 的描述符总数，再为每个描 > > + 述符打印一个字段，最多 5 > > 个。每个字段由三个用冒号分隔的十进制数组成，依 > > + > > 次表示状态（status）、偏移（offset）和长度（length）。对于提交事件，报 > > + 告的是初始长度；对于回调事件，报告的是实际长度。 > > > > -- 数据长度： > > - 对于提交，表示请求的长度；对于回调，表示实际传输的长度。 > > +- > > 数据长度：对于提交，表示请求的长度；对于回调，表示实际传输的长度。 > > -- 数据标签： > > - 即使数据长度非零，usbmon 也不一定会捕获数据。 > > - 仅当标签为 ``=`` 时，才会有数据字段。 > > +- 数据标签：即使数据长度非零，usbmon 也不一定会捕获数据。只有标签为 > > + ``=`` 时，才会有数据字段。 > > > > -- 数据字段： > > - 以大端十六进制格式显示。注意，这些并不是真正的机器字， > > - 而只是把字节流拆成若干“字”以便阅读。因此最后一个字可能只包含 > > - 1 到 4 个字节。 > > - 收集的数据长度是有限的，可能小于数据长度字段中报告的值。 > > - > > 因为数据长度字段只统计实际接收到的字节，而数据字段包含整个传输缓冲区， > > - 所以，在等时输入（Zi）完成且缓冲区中接收到的数据稀疏的情况下， > > - 收集的数据长度可能大于数据长度字段的值。 > > +- > > 数据字段：以大端十六进制格式显示。注意，这些并不是真正的机器字，只是为 > > + 了便于阅读，把字节流按“字”分组显示。因此最后一个字可能只包含 1 > > 到 4 个 > > + > > 字节。捕获的数据长度是有限的，可能小于数据长度字段中报告的值。对于等时 > > + > > 输入（Zi）完成事件，如果缓冲区里的接收数据比较稀疏，捕获数据的长度甚至 > > + > > 可能大于数据长度字段，因为后者只统计实际接收到的字节，而数据字段展示的 > > + 是整个传输缓冲区。 > > > > > > > > @@ -234,18 +198,16 @@ usbmon 报告的是各个外设驱动 > > d5ea89a0 3575914555 SCi:1:001:0 s a3 00 0000 0003 0004 4 < > > d5ea89a0 3575914560 CCi:1:001:0 0 4 = 01050000 > > > > -向地址为 5 的存储设备发送 > > -31 字节 Bulk 包装的 SCSI 命令 ``0x28`` > > -（``READ_10``）的输出批量传输:: > > +向地址为 5 的存储设备发送一个输出批量传输，其中 31 字节的 Bulk > > 封装用于承 +载 SCSI 命令 ``0x28``（``READ_10``）:: > > > > dd65f0e8 4128379752 SBo:1:005:2 -115 31 = 55534243 ad000000 > > 00800000 80010a28 20000000 20000040 00000000 000000 dd65f0e8 > > 4128379808 CBo:1:005:2 0 31 > > > 原始二进制格式与 API > > ==================== > > -API 的整体架构与前文大体相同，只是事件以二进制格式传递。 > > -每个事件都通过下面的结构发送 > > -（这个名字是为了叙述方便而虚构的）:: > > +API > > 的整体架构与前文大体相同，只是事件以二进制格式传递。每个事件都通过 > > +下面的结构发送（这个结构名只是为了叙述方便而虚构的）:: > > > > struct usbmon_packet { > > @@ -275,29 +237,22 @@ API > > 的整体架构与前文大体相同，只是事件以二进制格式传递 unsigned int > > ndesc; /* 60: 实际 ISO 描述符数量 */ }; > > /* 64 总长度 */ > > -可以用 ``read(2)``、``ioctl(2)``， > > -或者通过 ``mmap`` 访问缓冲区， > > -从字符设备接收这些事件。 > > -不过，出于兼容性原因，``read(2)`` > > -只返回前 48 个字节。 > > +可以用 ``read(2)``、``ioctl(2)``，或者通过 ``mmap`` > > 访问缓冲区，从字符设 > > +备接收这些事件。不过，出于兼容性原因，``read(2)`` 只返回前 48 > > 个字节。 -字符设备通常命名为 ``/dev/usbmonN``， > > -其中 ``N`` 是 USB 总线号。 > > -编号为零的设备（``/dev/usbmon0``）比较特殊， > > -表示“所有总线”。 > > -请注意，具体命名策略由 Linux 发行版决定。 > > +字符设备通常命名为 ``/dev/usbmonN``，其中 ``N`` 是 USB > > 总线号。编号为零的 > > +设备（``/dev/usbmon0``）比较特殊，表示“所有总线”。具体命名策略由 > > Linux +发行版决定。 > > -如果你手动创建 ``/dev/usbmon0``， > > -请确保它归 root 所有，并且权限为 ``0600``。 > > -否则，非特权用户将能够窃听键盘流量。 > > +如果你手动创建 ``/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)`` > > @@ -309,31 +264,28 @@ API > > 的整体架构与前文大体相同，只是事件以二进制格式传递 u32 dropped; > > }; > > > > -成员 ``queued`` 表示当前缓冲区中已经排队的事件数量， > > -而不是自上次重置以来处理过的事件数量。 > > +成员 ``queued`` > > 表示当前缓冲区中已经排队的事件数量，而不是自上次重置以来 > > +处理过的事件数量。 > > -成员 ``dropped`` 表示自上次调用 > > -``MON_IOCG_STATS`` 以来丢失的事件数量。 > > +成员 ``dropped`` 表示自上次调用 ``MON_IOCG_STATS`` > > 以来丢失的事件数量。 > > ``MON_IOCT_RING_SIZE``，定义为 ``_IO(MON_IOC_MAGIC, 4)`` > > > > -此调用设置缓冲区大小。参数为以字节为单位的缓冲区大小。 > > -大小可能会向下取整到下一个块（或页）。 > > -如果请求的大小超出该内核的 [未指定] 范围， > > -则调用会失败并返回 ``-EINVAL``。 > > +此调用设置缓冲区大小。参数是以字节为单位的缓冲区大小。大小可能会向下取整 > > +到下一个块（或页）。如果请求的大小超出当前内核允许的范围，则调用会失败并 > > +返回 ``-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)`` > > +``MON_IOCX_GET`` 和 ``MON_IOCX_GETX`` 的定义分别如下： > > + > > +- ``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 { > > @@ -343,20 +295,18 @@ API > > 的整体架构与前文大体相同，只是事件以二进制格式传递 }; > > > > > > -调用前，应填好 ``hdr``、``data`` 和 ``alloc``。 > > -调用返回后，``hdr`` 指向的区域中包含下一个事件的结构； > > -如果存在数据，那么数据缓冲区中也会包含相应数据。 > > -该事件会从内核缓冲区中移除。 > > +调用前，应填好 ``hdr``、``data`` 和 ``alloc``。调用返回后，``hdr`` > > 指向的 > > +内存区域中会写入下一个事件的结构；如果存在数据，数据缓冲区中也会填入相应 > > +内容。该事件会从内核缓冲区中移除。 > > -``MON_IOCX_GET`` 会将 48 字节的数据复制到 ``hdr`` 区域， > > -``MON_IOCX_GETX`` 会复制 64 字节。 > > +``MON_IOCX_GET`` 会将 48 字节的数据复制到 ``hdr`` > > 区域，``MON_IOCX_GETX`` +会复制 64 字节。 > > > > ``MON_IOCX_MFETCH``，定义为 > > ``_IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg)`` > > > > -当应用程序通过 ``mmap(2)`` 访问缓冲区时， > > -主要使用这个 ioctl。 > > -其参数是指向以下结构的指针:: > > +应用程序通过 ``mmap(2)`` 访问缓冲区时，主要使用这个 > > ioctl。其参数是指向 +以下结构的指针:: > > > > struct mon_mfetch_arg { > > uint32_t *offvec; /* 获取的事件偏移向量 */ > > @@ -365,41 +315,36 @@ API > > 的整体架构与前文大体相同，只是事件以二进制格式传递 }; > > > > > > -该 ioctl 的操作分为三个阶段： > > +这个 ioctl 的流程分为三个阶段： > > > > -首先，从内核缓冲区移除并丢弃最多 ``nflush`` 个事件。 > > -实际丢弃的事件数量会写回 ``nflush``。 > > +首先，从内核缓冲区移除并丢弃最多 ``nflush`` > > 个事件。实际丢弃的事件数量会 +写回 ``nflush``。 > > > > -其次，除非伪设备以 ``O_NONBLOCK`` 打开，否则会一直等待， > > -直到缓冲区中出现事件。 > > +其次，除非设备以 ``O_NONBLOCK`` > > 打开，否则会一直等待，直到缓冲区中出现 +事件。 > > > > -第三，将最多 ``nfetch`` 个偏移量提取到 mmap > > -缓冲区，并存入 ``offvec`` 中。 > > -实际提取到的事件偏移数量会存回 ``nfetch``。 > > +第三，将最多 ``nfetch`` 个偏移量提取到 mmap 缓冲区，并存入 > > ``offvec`` 中。 +实际提取到的事件偏移数量会写回 ``nfetch``。 > > > > ``MON_IOCH_MFLUSH``，定义为 ``_IO(MON_IOC_MAGIC, 8)`` > > > > -此调用从内核缓冲区移除若干事件。 > > -其参数为要移除的事件数量。 > > -如果缓冲区中的事件少于请求数量， > > -则移除所有事件，且不报告错误。 > > -当没有事件时也可使用。 > > +此调用从内核缓冲区移除若干事件。其参数是要移除的事件数量。如果缓冲区中的 > > +事件少于请求数量，则移除全部现有事件，且不报告错误。即使当前没有事件，也 > > +可以调用。 > > > > ``FIONBIO`` > > > > 如果有需要，将来可能会实现 ``FIONBIO`` ioctl。 > > > > -除了 ``ioctl(2)`` 和 ``read(2)`` 之外， > > -二进制 API 的特殊文件也可以用 ``select(2)`` 和 > > -``poll(2)`` 轮询。 > > -但 ``lseek(2)`` 不起作用。 > > +除了 ``ioctl(2)`` 和 ``read(2)`` 之外，二进制 API > > 对应的特殊文件还可以用 +``select(2)`` 和 ``poll(2)`` 轮询，但 > > ``lseek(2)`` 不可用。 > > * 二进制 API 的内核缓冲区内存映射访问 > > > > -基本思想很简单： > > +基本思路很简单： > > > > -准备时，先获取当前大小，再用 ``mmap(2)`` 映射缓冲区。 > > -然后执行类似下面伪代码的循环:: > > +准备时，先查询当前大小，再用 ``mmap(2)`` > > 映射缓冲区。之后运行与下面伪代码 +类似的循环:: > > > > struct mon_mfetch_arg fetch; > > struct usbmon_packet *hdr; > > @@ -411,7 +356,7 @@ API > > 的整体架构与前文大体相同，只是事件以二进制格式传递 ioctl(fd, > > MON_IOCX_MFETCH, &fetch); // 同时处理错误 nflush = fetch.nfetch; > > // 完成后要刷新这么多包 for (i = 0; i < nflush; i++) { > > - hdr = (struct ubsmon_packet *) &mmap_area[vec[i]]; > > + hdr = (struct usbmon_packet *) &mmap_area[vec[i]]; > > if (hdr->type == '@') // 填充包 > > continue; > > caddr_t data = &mmap_area[vec[i]] + 64; > > @@ -421,7 +366,7 @@ API > > 的整体架构与前文大体相同，只是事件以二进制格式传递 > > > > > > -因此，主要思想是每 N 个事件只执行一次 ioctl。 > > +因此，这里的核心思路就是每 N 个事件只执行一次 ioctl。 > > > > -虽然缓冲区是环形的，但返回的头和数据不会跨越缓冲区末端， > > -因此上面的伪代码无需任何合并操作。 > > +虽然缓冲区是环形的，但返回的头部和数据不会跨越缓冲区末端，因此上面的伪代 > > +码无需做任何拼接。 > > -- 2.34.1 > > > > > ^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH v4] docs/zh_CN: usb: refine translated wording and formatting 2026-06-01 3:39 ` [PATCH v3] docs/zh_CN: usb: refine translated wording and formatting Kefan Bai 2026-06-01 4:00 ` Alex Shi @ 2026-06-01 8:26 ` Kefan Bai 2026-06-01 9:34 ` Alex Shi 1 sibling, 1 reply; 5+ messages in thread From: Kefan Bai @ 2026-06-01 8:26 UTC (permalink / raw) To: linux-usb, si.yanteng, gregkh, seakeel Cc: dzm91, corbet, skhan, linux-doc, linux-kernel, doubled, alexs, Kefan Bai Refine the zh_CN USB translations for clarity and consistency. Improve wording, wrapping, and formatting across the translated USB documents. Link: https://lore.kernel.org/r/2026053149-flaky-shallow-2460@gregkh Suggested-by: Alex Shi <seakeel@gmail.com> Signed-off-by: Kefan Bai <baikefan@leap-io-kernel.com> --- v4: - keep every translated line below 80 columns - reformat usbmon and chipidea examples while keeping the structure aligned with the English originals v3: - refine the subject and commit message - add a Link trailer to the cleanup request thread - move revision notes below the cut line v2: - replace the obsolete FSF mailing address reference in acm.rst - trim the commit message to satisfy checkpatch Documentation/translations/zh_CN/usb/CREDITS | 147 ++++--- Documentation/translations/zh_CN/usb/acm.rst | 62 ++- .../translations/zh_CN/usb/authorization.rst | 79 ++-- .../translations/zh_CN/usb/chipidea.rst | 63 ++- Documentation/translations/zh_CN/usb/dwc3.rst | 37 +- Documentation/translations/zh_CN/usb/ehci.rst | 247 +++++------- .../translations/zh_CN/usb/index.rst | 18 +- .../translations/zh_CN/usb/usbmon.rst | 362 ++++++++---------- 8 files changed, 449 insertions(+), 566 deletions(-) diff --git a/Documentation/translations/zh_CN/usb/CREDITS b/Documentation/translations/zh_CN/usb/CREDITS index c133b1a5daff..ccfeced03ea6 100644 --- a/Documentation/translations/zh_CN/usb/CREDITS +++ b/Documentation/translations/zh_CN/usb/CREDITS @@ -10,12 +10,10 @@ :校译: -简易 Linux USB 驱动的致谢名单： +Simple Linux USB 驱动项目致谢名单： -以下人员都为 Linux USB 驱动代码作出了贡献 -（按姓氏字母顺序排列）。我相信这份名单本应 -更长一些，但确实不容易维护。 -如需将自己加入名单，请提交补丁。 +以下人员都为 Linux USB 驱动代码作出过贡献（按姓氏字母顺序排列）。这份名 +单本该更长，只是确实不易维护；如果你也应列名其中，欢迎提交补丁把自己加上。 Georg Acher <acher@informatik.tu-muenchen.de> David Brownell <dbrownell@users.sourceforge.net> @@ -41,123 +39,124 @@ 特别感谢： Inaky Perez Gonzalez <inaky@peloncho.fis.ucm.es> - 感谢他发起了 Linux USB 驱动开发工作，并编写了体量较大的 uusbd - 驱动中的大部分代码。我们从那项工作中学到了很多。 + 感谢他牵头开发 Linux USB 驱动，并编写了 uusbd 驱动的大部分代码，我们 + 从中学到了很多。 NetBSD 和 FreeBSD 的 USB 开发者们 感谢他们加入 Linux USB 邮件列表，提供建议并分享实现经验。 -附加感谢： - 还要感谢以下公司与个人在硬件、支持、时间投入和开发方面提供的捐赠与帮助 - （摘自 Inaky 驱动原始的 THANKS 文件）： +另外还要感谢： - 以下公司曾帮助我们开发 Linux USB / UUSBD： + 以下公司和个人在硬件、支持、时间和开发工作上给予了帮助（摘自 Inaky + 驱动原始的 THANKS 文件）： - - 3Com GmbH 捐赠了一台 ISDN Pro TA，并在技术问题和测试设备方面为我 - 提供支持。没想到能得到这么大的帮助。 + 以下公司曾为 Linux USB / UUSBD 的开发提供帮助： - - USAR Systems 向我们提供了他们出色的 USB 评估套件， - 使我们能够测试 Linux USB 驱动对最新 USB 规范的符合性。 - USAR Systems 认识到保持开放操作系统与时俱进的重要性， - 并以硬件支持这个项目。感谢！ + - 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 实现。 + - CMD Technology, Inc. 慷慨捐赠了一块 CSA-6700 PCI 转 USB 控制卡， + 用于测试 OHCI 实现。 - - 由于他们对我们的支持，Keytronic 可以放心， - 他们的键盘能卖给至少 300 万 Linux 用户中的一部分。 + - 有了他们的支持，Keytronic 可以确信，其键盘能够销售给至少 300 万 + Linux 用户中的一部分。 - - ing büro h doran [http://www.ibhdoran.com]! - 在欧洲，想给主板买一个 PC 背板 USB 连接器几乎是不可能的 - （我自己做的那个相当糟糕 :)）。现在我知道该去哪里买漂亮的 USB - 配件了！ + - 特别感谢 ing büro h doran [http://www.ibhdoran.com]。 + 在欧洲，想给主板配一个 PC 背板 USB 连接器几乎是不可能的（我自己 + 做的那个效果并不好）。现在我知道该去哪里购买合适的 USB 配件了。 - Genius Germany 捐赠了一只 USB 鼠标，用于测试鼠标启动协议； - 他们还捐赠了 F-23 数字摇杆和 NetMouse Pro。感谢！ + 他们还捐赠了 F-23 数字摇杆和 NetMouse Pro，在此致谢。 - - AVM GmbH Berlin 支持我们开发 Linux 下的 AVM ISDN Controller B1 USB 驱动。 - AVM 是领先的 ISDN 控制器制造商，其主动式设计对包括 Linux 在内的 - 所有操作系统平台开放。 + - AVM GmbH Berlin 支持我们开发 Linux 下的 AVM ISDN Controller B1 USB + 驱动。AVM 是主动式和被动式 ISDN 控制器及基于 CAPI 2.0 软件的领先 + 制造商。AVM B1 的主动式设计对包括 Linux 在内的所有操作系统平台 + 开放。 - - 非常感谢 Y-E Data, Inc 捐赠的 FlashBuster-U USB 软驱， - 使我们能够测试批量传输代码。 + - 非常感谢 Y-E Data, Inc 捐赠的 FlashBuster-U USB 软驱，使我们能够测试 + 批量传输代码。 - 感谢 Logitech 捐赠了一只三轴 USB 鼠标。 - Logitech 负责设计、制造并销售各种人机接口设备， - 在键盘、鼠标、轨迹球、摄像头、扬声器，以及面向游戏和专业用途的 - 控制设备方面拥有悠久历史和丰富经验。 + Logitech 负责设计、制造并销售各种人机接口设备，在键盘、鼠标、轨迹球、 + 摄像头、扬声器，以及面向游戏和专业用途的控制设备方面拥有悠久历史和 + 丰富经验。 - 作为这些设备广为人知的供应商和销售商，他们捐赠了 USB 鼠标、 - 摇杆和扫描仪，以表明 Linux 的重要性，也让 Logitech 的客户 - 能在自己喜欢的操作系统上获得支持，并让所有 Linux 用户都能使用 - Logitech 以及其他 USB 硬件。 + 作为这些设备广为人知的供应商和销售商，他们捐赠了 USB 鼠标、摇杆和 + 扫描仪，以表明 Linux 的重要性，也让 Logitech 的客户能在自己偏爱的 + 操作系统上获得支持，并让所有 Linux 用户都能使用 Logitech 及其他 + USB 硬件。 Logitech 也是 1999 年 2 月 11 日维也纳 Linux 大会的官方赞助商， 我们将在会上展示 Linux USB 工作的最新进展。 - - 感谢 CATC 提供 USB Inspector，帮助我们揭开 UHCI 内部实现中 - 那些不为人知的角落。 + - 感谢 CATC 提供 USB Inspector，帮助我们看到 UHCI 内部实现中的那些 + 隐秘角落。 - 感谢 Entrega 为开发工作提供 PCI 转 USB 卡、集线器和转换器产品。 - - 感谢 ConnectTech 提供 WhiteHEAT USB 转串口转换器以及相关文档， - 让这个驱动得以写成。 + - 感谢 ConnectTech 提供 WhiteHEAT USB 转串口转换器以及相关文档，让 + 这个驱动得以写成。 - - 感谢 ADMtek 提供 Pegasus 和 Pegasus II 评估板、规格说明， - 以及驱动开发过程中的宝贵建议。 + - 感谢 ADMtek 提供 Pegasus 和 Pegasus II 评估板、规格说明，以及驱动 + 开发过程中的宝贵建议。 - 另外还要感谢以下个人（嘿，顺序不分先后 :)） + 另外还要感谢以下个人（排名不分先后）： - - Oren Tirosh <orenti@hishome.net>, - 他非常耐心地听我唠叨各种 USB 疑问，还给了很多很酷的想法。 + - Oren Tirosh <orenti@hishome.net> + 他非常耐心地解答我反复提出的各种 USB 问题，并提供了许多有价值的 + 想法。 - - Jochen Karrer <karrer@wpfd25.physik.uni-wuerzburg.de>, - 指出了致命 bug，并给出了宝贵建议。 + - Jochen Karrer <karrer@wpfd25.physik.uni-wuerzburg.de> + 指出了严重问题，并给出了宝贵建议。 - - Edmund Humemberger <ed@atnet.at>，他在公共关系与项目管理方面 - 为 Linux-USB 项目付出了巨大的努力。 + - Edmund Humemberger <ed@atnet.at>，他在公共关系与项目管理方面为 + Linux-USB 项目付出了巨大的努力。 - - Alberto Menegazzi <flash@flash.iol.it> 正在着手编写 UUSBD 文档，加油！ + - Alberto Menegazzi <flash@flash.iol.it> 正在着手编写 UUSBD 文档。 - - Ric Klaren <ia_ric@cs.utwente.nl> 编写了很好的入门文档， - 与 Alberto 的作品形成良性竞争：）。 + - Ric Klaren <ia_ric@cs.utwente.nl> 编写了很好的入门文档，与 + Alberto 的作品形成了良性互补。 - - Christian Groessler <cpg@aladdin.de>，感谢他在那些棘手细节上的帮助。 + - Christian Groessler <cpg@aladdin.de>，感谢他在诸多复杂细节上的帮助。 - - Paul MacKerras 改进了 OHCI 实现，推动了对 iMac 的支持， - 并提供了大量的改进意见。 + - Paul MacKerras 改进了 OHCI 实现，推动了对 iMac 的支持，并提供了 + 大量的改进意见。 - - Fernando Herrera <fherrera@eurielec.etsit.upm.es> - 负责撰写、维护并不断补充那份期待已久、独一无二又精彩的 - UUSBD FAQ！太棒了！ + - Fernando Herrera <fherrera@eurielec.etsit.upm.es> 负责撰写、维护并 + 持续补充那份期待已久、内容翔实的 UUSBD FAQ。 - - Rasca Gmelch <thron@gmx.de> 重新启用了 raw 驱动， - 指出了一些错误，并启动了 uusbd-utils 软件包。 + - Rasca Gmelch <thron@gmx.de> 重新启用了 raw 驱动，指出了一些错误，并 + 启动了 uusbd-utils 软件包。 - - Peter Dettori <dettori@ozy.dec.com>，像疯了一样挖掘 bug， - 还提出了很多很酷的建议，太棒了！ + - Peter Dettori <dettori@ozy.dec.com>，持续发现问题，并提出了许多 + 有价值的建议。 - - 自由软件与 Linux 社区的所有成员，包括 FSF、GNU 项目、 - MIT X 联盟、TeX 社区等等，谢谢你们！ + - 自由软件与 Linux 社区的所有成员，包括 FSF、GNU 项目、MIT X 联盟、 + TeX 社区等，在此一并致谢。 - - 特别感谢 Richard Stallman 创造了 Emacs！ + - 特别感谢 Richard Stallman 创造了 Emacs。 - - 感谢 linux-usb 邮件列表的所有成员，读了那么多邮件——不开玩笑了， - 感谢你们提出的所有建议！ + - 感谢 linux-usb 邮件列表的所有成员阅读了大量邮件，并提出了诸多 + 建议。 - 感谢 USB Implementers Forum 成员们的帮助与支持。 - - Nathan Myers <ncm@cantrip.org>，感谢他的建议！ - （希望你喜欢 Cibeles 的派对。） + - Nathan Myers <ncm@cantrip.org>，感谢他的建议。（也希望你喜欢 + Cibeles 的派对。） - - 感谢 Linus Torvalds 创建、开发并管理 Linux。 + - 感谢 Linus Torvalds 创立、开发并维护 Linux。 - Mike Smith、Craig Keithley、Thierry Giron 和 Janet Schank - 感谢他们让我认识到标准 USB 集线器其实也没那么“标准”， - 这有助于我们在标准集线器驱动中加入厂商特定的特殊处理。 + 感谢他们让我认识到，标准 USB 集线器其实一点也不“标准”；也正因 + 如此，我们才能在标准集线器驱动中加入厂商特定的处理。 diff --git a/Documentation/translations/zh_CN/usb/acm.rst b/Documentation/translations/zh_CN/usb/acm.rst index 51d6eb8f5660..b2e35787af45 100644 --- a/Documentation/translations/zh_CN/usb/acm.rst +++ b/Documentation/translations/zh_CN/usb/acm.rst @@ -20,33 +20,26 @@ Linux ACM 驱动 v0.16 0. 免责声明 ~~~~~~~~~~~ -本程序是自由软件；你可以在自由软件基金会发布的 -GNU 通用公共许可证第 2 版，或者（按你的选择） -任何后续版本的条款下重新发布和/或修改它。 +本程序是自由软件；你可以在自由软件基金会发布的 GNU 通用公共许可证第 2 版， +或者（按你的选择）任何后续版本的条款下重新发布和/或修改它。 -发布本程序是希望它能发挥作用，但它不附带任何担保； -甚至不包括对适销性或特定用途适用性的默示担保。 -详情见 GNU 通用公共许可证。 +发布本程序是希望它能发挥作用，但它不附带任何担保；甚至不包括对适销性或 +特定用途适用性的默示担保。详情见 GNU 通用公共许可证。 -你应该已经随本程序收到了 GNU 通用公共许可证的副本； -如果没有，请致信：Free Software Foundation, Inc., 59 -Temple Place, Suite 330, Boston, MA 02111-1307 USA。 +你应该已经随本程序收到了 GNU 通用公共许可证的副本；如果没有，请参见 +COPYING 文件。 -如需联系作者，可发送电子邮件至 vojtech@suse.cz， -或邮寄至： -Vojtech Pavlik, Ucitelska 1576, Prague 8, -182 00, Czech Republic。 +如需联系作者，可发送电子邮件至 vojtech@suse.cz，或邮寄至： +Vojtech Pavlik, Ucitelska 1576, Prague 8, 182 00, Czech Republic。 -为方便起见，软件包中已附带 GNU 通用公共许可证 -第 2 版：见 COPYING 文件。 +为方便起见，软件包中已附带 GNU 通用公共许可证第 2 版：见 COPYING 文件。 1. 使用方法 ~~~~~~~~~~~ -``drivers/usb/class/cdc-acm.c`` 驱动可用于符合 USB -通信设备类抽象控制模型（USB CDC ACM）规范的 -USB 调制解调器和 USB ISDN 终端适配器。 +``drivers/usb/class/cdc-acm.c`` 驱动适用于符合 USB 通信设备类抽象控制模型 +（USB CDC ACM）规范的 USB 调制解调器和 USB ISDN 终端适配器。 -许多调制解调器支持此驱动，以下是我所知道的一些型号： +已知支持该驱动的调制解调器包括： - 3Com OfficeConnect 56k - 3Com Voice FaxModem Pro @@ -56,17 +49,16 @@ USB 调制解调器和 USB ISDN 终端适配器。 - Compaq 56k FaxModem - ELSA Microlink 56k -我知道有一款 ISDN 终端适配器可以与 ACM 驱动一起使用： +已知有一款 ISDN 终端适配器可以配合 ACM 驱动使用： - 3Com USR ISDN Pro TA -一些手机也可以通过 USB 连接。 -我知道以下机型可以正常工作： +一些手机也可以通过 USB 连接，已知可用的机型有： - SonyEricsson K800i -遗憾的是，许多调制解调器和大多数 ISDN TA -都使用专有接口，因此无法与此驱动配合工作。 +遗憾的是，很多调制解调器和大多数 ISDN TA 都使用专有接口，因此无法配合该 +驱动工作。 购买前请先确认设备是否符合 ACM 规范。 要使用这些调制解调器，需要加载以下模块:: @@ -75,15 +67,13 @@ USB 调制解调器和 USB ISDN 终端适配器。 uhci-hcd.ko ohci-hcd.ko or ehci-hcd.ko cdc-acm.ko -之后就应该可以访问这些调制解调器了。 -应当可以使用 ``minicom``、``ppp`` 和 ``mgetty`` -与它们通信。 +之后就应该能访问这些调制解调器，并用 ``minicom``、``ppp`` 和 +``mgetty`` 与它们通信。 2. 验证驱动是否正常工作 ~~~~~~~~~~~~~~~~~~~~~~~ -第一步是检查 ``/sys/kernel/debug/usb/devices``， -其内容应该类似如下:: +第一步是查看 ``/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 @@ -112,11 +102,10 @@ USB 调制解调器和 USB ISDN 终端适配器。 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.)``，那就无能为力了： -这说明你手上的设备使用的是厂商专有接口:: +关键是看这三行，再结合 ``Cls=`` 字段里出现的 ``comm`` 和 ``data`` 类，就 +能判断这是一台 ACM 设备。``Driver=acm`` 表示该设备正在使用 acm 驱动。如果 +只看到 ``Cls=ff(vend.)``，那就说明这台设备使用的是厂商专有接口，ACM 驱动 +无法处理:: 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 @@ -142,6 +131,5 @@ USB 调制解调器和 USB ISDN 终端适配器。 usb.c: acm driver claimed interface c7b5f3f8 usb.c: acm driver claimed interface c7691fa0 -如果以上都正常，请启动 ``minicom``， -把它配置为连接 ``ttyACM`` 设备，然后 -尝试输入 ``at``。如果返回 ``OK``，说明一切工作正常。 +如果这些都正常，请启动 ``minicom``，把它配置为连接到 ``ttyACM`` 设备，然后 +尝试输入 ``at``。如果返回 ``OK``，说明驱动工作正常。 diff --git a/Documentation/translations/zh_CN/usb/authorization.rst b/Documentation/translations/zh_CN/usb/authorization.rst index 2aa311f6b967..e2ff2282bd03 100644 --- a/Documentation/translations/zh_CN/usb/authorization.rst +++ b/Documentation/translations/zh_CN/usb/authorization.rst @@ -10,34 +10,32 @@ :校译: -============================= -授权或禁止 USB 设备连接到系统 -============================= +=========================== +允许或禁止 USB 设备接入系统 +=========================== 版权 (C) 2007 Inaky Perez-Gonzalez <inaky@linux.intel.com> 英特尔公司 -此功能允许你控制 USB 设备是否可以在系统中使用。 -借助它，你可以完全通过用户空间实现对 USB 设备的锁定。 +有了这项功能，你就可以控制 USB 设备是否允许在系统中使用，并把 USB 设备锁 +定机制完全放在用户空间实现。 -目前，当插入一个 USB 设备时，系统会对其进行配置， -其接口会立即向用户开放。 -有了这项改动，只有在 root 授权设备完成配置后， -设备才可被使用。 +目前，USB 设备一接入系统就会被立即配置，其接口也会立刻向用户开放。引入 +这项机制后，只有在 root 明确授权后，设备才会完成配置并允许使用。 用法 ==== -授权设备接入:: +授权设备接入系统:: $ echo 1 > /sys/bus/usb/devices/DEVICE/authorized -取消对设备的授权:: +取消设备授权:: $ echo 0 > /sys/bus/usb/devices/DEVICE/authorized -将新连接到 ``hostX`` 的设备默认设为未授权（即锁定）:: +将连接到 ``hostX`` 的新设备默认设为未授权（即锁定）:: $ echo 0 > /sys/bus/usb/devices/usbX/authorized_default @@ -45,15 +43,14 @@ $ echo 1 > /sys/bus/usb/devices/usbX/authorized_default -默认情况下，所有 USB 设备都是授权的。 -向 ``authorized_default`` 属性写入 ``2`` 会使内核 -默认只授权连接到内部 USB 端口的设备。 +默认情况下，所有 USB 设备都是授权的。向 ``authorized_default`` 属性写入 +``2`` 会使内核默认只授权连接到内部 USB 端口的设备。 -系统锁定示例（比较粗糙） ------------------------- +系统锁定示例（简化版） +---------------------- -假设你想实现一个锁定功能，只允许类型为 XYZ 的设备接入 -（例如某台带有外露 USB 端口的自助服务终端）:: +假设你想做一个锁定机制，只允许 XYZ 类型的设备接入（例如一台带有外露 USB +端口的自助终端）:: 启动系统 rc.local -> @@ -63,21 +60,18 @@ echo 0 > $host/authorized_default done -给 udev 挂一个脚本，用于处理新插入的 USB 设备:: +为 udev 配置一个脚本，用于处理新插入的 USB 设备:: if device_is_my_type $DEV then echo 1 > $device_path/authorized - done + fi -``device_is_my_type()`` 才是锁定方案真正见功夫的 -地方。仅仅检查 class、type 和 protocol 是否匹配 -某个值，是你能做出的最糟糕的安全验证之一； -对想绕过它的人来说，这反而是最容易利用的方案。 -如果你需要真正安全的办法，那就该使用加密、 -证书认证之类的机制。把 USB 存储设备当作 -“钥匙”的一个简单例子可以是:: +锁定方案是否可靠，关键全在 ``device_is_my_type()`` 的实现。仅仅检查 +class、type 和 protocol 是否匹配，几乎是最差的一种安全校验方式；对想绕过 +它的人来说，这种做法反而最容易伪造。如果你真要做安全控制，就该使用加密、 +证书认证之类的机制。把 USB 存储设备当作“钥匙”的一个简单示例可以写成:: function device_is_my_type() { @@ -87,7 +81,7 @@ sum=$(md5sum /mntpoint/.signature) if [ $sum = $(cat /etc/lockdown/keysum) ] then - echo "We are good, connected" + echo "验证通过，已连接" umount /mntpoint # 再做一些额外处理，让其他人也能使用它 else @@ -96,17 +90,16 @@ } -当然，这个例子很粗糙；真正要做的话， -你会想用基于 PKI 的证书校验，这样就不必依赖 -共享密钥之类的东西。不过你应该已经明白意思了。 -任何拿到设备仿真工具包的人都能伪造描述符和设备信息。 -别信这个。 +当然，这个例子仍然比较简化。真正落地时，更合适的做法是使用基于 PKI 的证 +书校验，这样就不必依赖共享密钥之类的机制了。不过意思已经很清楚：任何拿到 +设备仿真工具包的人，都能伪造描述符和设备信息，所以别把这类检查当成真正 +的安全保障。 接口授权 -------- -也有类似的方法用于允许或拒绝特定 USB 接口。 -这使得你可以只阻止某个 USB 设备中的部分接口。 +也可以用类似的方法允许或拒绝特定的 USB 接口。这样一来，你只需要阻止某个 +USB 设备中的部分接口。 授权接口:: @@ -126,14 +119,12 @@ $ echo 0 > /sys/bus/usb/devices/usbX/interface_authorized_default -默认情况下， -``interface_authorized_default`` 位为 ``1``， -因此所有接口默认都处于已授权状态。 +默认情况下，``interface_authorized_default`` 位为 ``1``，因此所有接口默认 +都会处于授权状态。 注意： - 如果把一个先前未授权的接口改为已授权， - 则必须通过将 ``INTERFACE`` 写入 ``/sys/bus/usb/drivers_probe`` - 来手动触发驱动探测。 + 如果把一个先前未授权的接口改为已授权，则必须通过将 ``INTERFACE`` 写入 + ``/sys/bus/usb/drivers_probe`` 来手动触发驱动探测。 -对于需要多个接口的驱动程序，应先授权所有必需接口， -然后再触发驱动探测。这样做可以避免副作用。 +对于需要多个接口的驱动程序，应先授权所有必需接口，然后再触发驱动探测。 +这样做可以避免副作用。 diff --git a/Documentation/translations/zh_CN/usb/chipidea.rst b/Documentation/translations/zh_CN/usb/chipidea.rst index ea0dc3043189..ee5407a4ce44 100644 --- a/Documentation/translations/zh_CN/usb/chipidea.rst +++ b/Documentation/translations/zh_CN/usb/chipidea.rst @@ -17,18 +17,17 @@ ChipIdea 高速双角色控制器驱动 1. 如何测试 OTG FSM（HNP 和 SRP） --------------------------------- -下面以两块 Freescale i.MX6Q Sabre SD 开发板为例， -说明如何通过 sysfs 输入文件演示 OTG 的 HNP 和 SRP 功能。 +下面以两块 Freescale i.MX6Q Sabre SD 开发板为例，演示如何通过 sysfs 属性 +测试 OTG 的 HNP 和 SRP 功能。 -1.1 如何使能 OTG FSM +1.1 如何启用 OTG FSM -------------------- 1.1.1 在 ``menuconfig`` 中选择 ``CONFIG_USB_OTG_FSM``，并重新编译内核 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -重新构建内核镜像和模块。如果想查看 OTG FSM 的 -一些内部变量，可以挂载 ``debugfs``；其中有两个文件 -可以显示 OTG FSM 变量以及部分控制器寄存器的值:: +重新构建内核镜像和模块。如果想查看 OTG FSM 的内部变量，可以挂载 +``debugfs``；其中有两个文件，分别显示 OTG FSM 的变量和部分控制器寄存器值:: cat /sys/kernel/debug/ci_hdrc.0/otg cat /sys/kernel/debug/ci_hdrc.0/registers @@ -44,11 +43,10 @@ ChipIdea 高速双角色控制器驱动 1.2 测试步骤 ------------ -1) 给两块 Freescale i.MX6Q Sabre SD 开发板上电， - 并加载 gadget 类驱动（例如 ``g_mass_storage``）。 +1) 给两块 Freescale i.MX6Q Sabre SD 开发板上电，并加载 gadget 类驱动（例如 + ``g_mass_storage``）。 -2) 用 USB 线连接两块开发板： - 一端是 micro A 插头，另一端是 micro B 插头。 +2) 用 USB 线连接两块开发板：一端是 micro A 插头，另一端是 micro B 插头。 插入 micro A 插头的一端是 A 设备，它应枚举另一端的 B 设备。 @@ -66,32 +64,28 @@ ChipIdea 高速双角色控制器驱动 echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req - 或者，通过引入 HNP 轮询，B 端主机可以知道 - A 端外设希望切换为主机角色，因此这次角色切换 - 也可以通过 A 端外设响应 B 端主机的轮询， - 在 A 侧触发。 - 这可以通过在 A 设备上执行下面的命令来完成:: + 或者，也可以借助 HNP 轮询，让 B 端主机知道 A 端外设希望切回主机角色。 + 因此，这次切换也可以由 A 侧触发，也就是由 A 端外设响应 B 端主机的轮询 + 来完成。可在 A 设备上执行下面的命令:: echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req A 设备应切回主机角色并枚举 B 设备。 -5) 拔掉 B 设备（拔掉 micro B 插头）， - 并在 10 秒内重新插入； +5) 拔掉 B 设备（拔掉 micro B 插头），并在 10 秒内重新插入。 A 设备应重新枚举 B 设备。 -6) 拔掉 B 设备（拔掉 micro B 插头）， - 并在 10 秒后重新插入； +6) 拔掉 B 设备（拔掉 micro B 插头），并在 10 秒后重新插入。 A 设备不应重新枚举 B 设备。 - 如果 A 设备希望使用总线： + 如果 A 设备还想继续使用总线： 在 A 设备上执行:: echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req - 如果 B 设备希望使用总线： + 如果 B 设备想使用总线： 在 B 设备上执行:: @@ -111,40 +105,41 @@ ChipIdea 高速双角色控制器驱动 echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req - A 设备应恢复 USB 总线并枚举 B 设备。 + A 设备应恢复 USB 总线，并枚举 B 设备。 1.3 参考文档 ------------ -《On-The-Go and Embedded Host Supplement -to the USB Revision 2.0 Specification +《On-The-Go and Embedded Host Supplement to the USB Revision 2.0 Specification July 27, 2012 Revision 2.0 version 1.1a》 2. 如何将 USB 用作系统唤醒源 ---------------------------- -下面是在 i.MX6 平台上把 USB 用作系统唤醒源的示例。 +下面给出在 i.MX6 平台上将 USB 用作系统唤醒源的示例。 -2.1 使能核心控制器的唤醒功能:: +2.1 启用核心控制器的唤醒功能:: echo enabled > /sys/bus/platform/devices/ci_hdrc.0/power/wakeup -2.2 使能 glue 层的唤醒功能:: +2.2 启用 glue 层的唤醒功能:: echo enabled > /sys/bus/platform/devices/2184000.usb/power/wakeup -2.3 使能 PHY 的唤醒功能（可选）:: +2.3 启用 PHY 的唤醒功能（可选）:: echo enabled > /sys/bus/platform/devices/20c9000.usbphy/power/wakeup -2.4 使能根集线器的唤醒功能:: +2.4 启用根集线器的唤醒功能:: echo enabled > /sys/bus/usb/devices/usb1/power/wakeup -2.5 使能相关设备的唤醒功能:: +2.5 启用相关设备的唤醒功能:: echo enabled > /sys/bus/usb/devices/1-1/power/wakeup -如果系统只有一个 USB 端口， -而你希望在该端口上启用 USB 唤醒功能， -可以使用下面的脚本:: +如果系统只有一个 USB 端口，而你希望在该端口上启用 USB 唤醒功能，可以使用 +下面的脚本:: - for i in $(find /sys -name wakeup | grep usb);do echo enabled > $i;done; + for i in $(find /sys -name wakeup | grep usb) + do + echo enabled > $i + done diff --git a/Documentation/translations/zh_CN/usb/dwc3.rst b/Documentation/translations/zh_CN/usb/dwc3.rst index 3468ce50c5ba..9584cbbf6d03 100644 --- a/Documentation/translations/zh_CN/usb/dwc3.rst +++ b/Documentation/translations/zh_CN/usb/dwc3.rst @@ -18,46 +18,43 @@ DWC3 驱动 待办 ~~~~ -阅读时如果想顺手认领点任务，可以从下面挑一项 :) +如果你愿意接手其中一项任务，可以从下面选择： - 将中断处理程序改为每个端点各自使用线程化 IRQ - 事实证明，有些 DWC3 命令大约需要 ``~1 ms`` 才能完成。 - 当前代码会一直自旋等待命令完成，这种设计并不好。 + 实践表明，某些 DWC3 命令大约需要 ``~1 ms`` 才能完成。当前代码会一直自旋 + 等待命令完成，这并不是好办法。 实现思路： - - DWC 核心实现了一个按端点对中断进行解复用的 IRQ 控制器。 - 中断号在探测（``probe``）阶段分配，并归属于该设备。 - 如果硬件通过 ``MSI`` 为每个端点提供独立中断， - 那么这个“虚拟”IRQ 控制器就可以被真实的端点中断取代。 + - DWC 核心实现了一个按端点分发中断的 IRQ 控制器。中断号在探测 + （``probe``）阶段分配，并归属于该设备。如果硬件通过 ``MSI`` 为每个 + 端点提供独立中断，那么这个“虚拟”IRQ 控制器就可以被真实的端点中断 + 取代。 - - 在调用 ``usb_ep_enable()`` 时请求并分配中断资源， - 在调用 ``usb_ep_disable()`` 时释放中断资源。 - 最坏情况下需要 32 个中断，最少是 ``ep0/1`` 的两个中断。 + - 在调用 ``usb_ep_enable()`` 时请求并分配中断资源，在调用 + ``usb_ep_disable()`` 时释放中断资源。最坏情况下需要 32 个中断，最少是 + ``ep0/1`` 的两个中断。 - ``dwc3_send_gadget_ep_cmd()`` 将在 ``wait_for_completion_timeout()`` 中休眠，直到命令完成。 - 中断处理程序分为以下几个部分： - 设备级主中断处理程序 - 遍历每个事件，并对其调用 ``generic_handle_irq()``。 - 从 ``generic_handle_irq()`` 返回后，确认事件计数器，使中断最终消失。 + 遍历每个事件，并调用 ``generic_handle_irq()`` 处理。返回后再确认 + 事件计数器，让中断最终消失。 - 设备级线程化处理程序 无。 - 端点中断的主处理程序 - 读取事件并尽量处理它。凡是需要睡眠的操作都交给线程处理。 - 事件保存在每个端点的数据结构中。 - 还要注意，一旦把某项工作交给线程处理， - 就不要再在主处理程序里处理它， - 以免出现优先级反转之类的问题。 + 读取事件并尽量处理；凡是需要睡眠的操作都交给线程处理。事件保存在 + 每个端点的数据结构中。一旦某项工作已经交给线程处理，主处理程序里就 + 不要再碰它，以免出现优先级反转之类的问题。 - 端点中断的线程化处理程序 处理剩余的端点工作，这些工作可能会睡眠，例如等待命令完成。 - 延迟: + 延迟： - 不应增加延迟，因为中断线程具有较高优先级， - 会在普通用户态任务之前运行 + 不应增加额外延迟，因为中断线程优先级较高，会在普通用户任务之前运行 （除非用户更改了调度优先级）。 diff --git a/Documentation/translations/zh_CN/usb/ehci.rst b/Documentation/translations/zh_CN/usb/ehci.rst index e05e493a30d3..c4c52303b13e 100644 --- a/Documentation/translations/zh_CN/usb/ehci.rst +++ b/Documentation/translations/zh_CN/usb/ehci.rst @@ -14,45 +14,37 @@ EHCI 驱动 ========= -2002年12月27日 +2002 年 12 月 27 日 -EHCI 驱动用于通过支持 USB 2.0 的主机控制器 -硬件与高速 USB 2.0 设备通信。USB 2.0 兼容 -USB 1.1 标准，它定义了三种传输速率： +EHCI 驱动用于借助支持 USB 2.0 的主机控制器，与高速 USB 2.0 设备通信。USB +2.0 向下兼容 USB 1.1，并定义了三种传输速率： - “高速”（High Speed）480 Mbit/sec（60 MByte/sec） - “全速”（Full Speed）12 Mbit/sec（1.5 MByte/sec） - “低速”（Low Speed）1.5 Mbit/sec -USB 1.1 仅支持全速与低速。 -高速设备可以在 USB 1.1 系统上使用， -但速度会降到 USB 1.1 的速率。 +USB 1.1 仅支持全速与低速。高速设备可以在 USB 1.1 系统上使用，但速度会 +降到 USB 1.1 的速率。 -USB 1.1 设备也可以在 USB 2.0 系统上使用。当它们 -插入 EHCI 控制器时，会被交由 USB 1.1 的伴随 -（companion）控制器处理，该控制器通常是 OHCI 或 UHCI。 +USB 1.1 设备也可以在 USB 2.0 系统上使用。当它们插入 EHCI 控制器时，会交给 +USB 1.1 的伴随（companion）控制器处理，该控制器通常是 OHCI 或 UHCI。 -当 USB 1.1 设备插入 USB 2.0 集线器时，它们通过 -集线器中的事务转换器（Transaction Translator，TT） -与 EHCI 控制器交互，该转换器将低速或全速事务转换为 -高速分割事务，从而避免浪费传输带宽。 +当 USB 1.1 设备插入 USB 2.0 集线器时，它们会通过集线器里的事务转换器 +（Transaction Translator，TT）与 EHCI 控制器通信。该转换器会把低速或全 +速事务转换为高速分割事务，从而避免浪费传输带宽。 -截至本文撰写时，该驱动已在以下 EHCI 实现上成功运行 -（按字母顺序）：Intel、NEC、Philips 和 VIA。 -其他供应商的 EHCI 实现正在陆续问世； -预计该驱动在这些实现上也可正常运行。 +截至本文撰写时，该驱动已在以下 EHCI 实现上成功运行（按字母顺序）： +Intel、NEC、Philips 和 VIA。随着其他供应商的 EHCI 实现陆续问世，预计该 +驱动在那些实现上也能正常运行。 -自 2001 年年中起，usb-storage 设备就已可用 -（在 2.4 版该驱动上速度相当不错）， -集线器则直到 2001 年底才开始可用，而其他类型的高速设备 -似乎要等到更多系统内置 USB 2.0 后才会出现。 -这类新系统从 2002 年初开始上市， -并在 2002 年下半年变得更加常见。 +自 2001 年年中起，usb-storage 设备就已可用（在 2.4 版该驱动上速度表现相当 +不错），集线器则直到 2001 年底才开始可用。其他类型的高速设备似乎要等到 +更多系统内置 USB 2.0 后才会出现。这类新系统从 2002 年初开始上市，并在 +2002 年下半年变得更加常见。 -注意，USB 2.0 支持并不只是 EHCI 本身。 -它还需要对 Linux-USB 核心 API 作出其他修改， -包括 hub 驱动；不过这些修改并不需要真正改变 -暴露给 USB 设备驱动的基本 ``usbcore`` API。 +注意，USB 2.0 的支持并不只靠 EHCI 本身。它还需要对 Linux-USB 核心 API +做其他修改，包括 hub 驱动；不过这些修改并不需要真正改变向 USB 设备驱动 +暴露的基本 ``usbcore`` API。 - David Brownell <dbrownell@users.sourceforge.net> @@ -61,58 +53,46 @@ USB 1.1 设备也可以在 USB 2.0 系统上使用。当它们 功能 ==== -该驱动会定期在 x86 硬件上进行测试， -也已在 PPC 硬件上使用，因此大小端问题应当已经解决。 -因此可以认为，它已经处理好了所有必要的 PCI 细节， -所以即便在 DMA 映射有些特殊的系统上， -I/O 也应能正常运行。 +该驱动长期在 x86 硬件上接受测试，也在 PPC 平台上使用过，因此大小端问题应 +该都已解决。再加上各种必要的 PCI 细节都已处理妥当，即便在 DMA 映射较特 +殊的系统上，I/O 也应能正常工作。 传输类型 -------- -截至本文撰写时，该驱动应当已经能够很好地处理 -所有控制传输、批量传输和中断传输， -包括通过 USB 2.0 集线器中的事务转换器 -与 USB 1.1 设备通信；但仍可能存在 bug。 +截至本文撰写时，该驱动应当已经能够稳定处理所有控制传输、批量传输和中断传 +输，包括经由 USB 2.0 集线器里的事务转换器访问 USB 1.1 设备；不过仍可能 +存在 bug。 -高速等时（ISO）传输支持也已可用，但截至本文撰写时， -还没有 Linux 驱动使用这项支持。 +高速等时（ISO）传输支持也已可用，不过截至本文撰写时，还没有 Linux 驱动真 +正使用它。 -目前尚不支持通过事务转换器实现全速等时传输。 -需要注意，ISO 传输的 split transaction 支持 -与高速 ISO 传输几乎无法共用代码， -因为 EHCI 用不同的数据结构表示它们。 -因此，目前大多数 USB 音频和视频设备 -还不能通过高速总线连接使用。 +目前尚不支持通过事务转换器实现全速等时传输。需要注意，ISO 传输的分割 +事务支持与高速 ISO 传输几乎无法共用代码，因为 EHCI 用不同的数据结构表示 +它们。因此，目前大多数 USB 音频和视频设备还无法在高速总线上使用。 驱动行为 -------- -所有类型的传输都可以排队。 -这意味着来自一个接口驱动的控制传输 -（或通过 usbfs 发出的控制传输）不会干扰 -另一个驱动的控制传输，而且中断传输可以使用 1 帧的周期， -而不必担心中断处理开销导致的数据丢失。 +所有类型的传输都可以排队提交。这意味着某个接口驱动发出的控制传输（或经由 +usbfs 提交的控制传输）不会干扰其他驱动的控制传输，而中断传输可以按 1 帧 +周期运行，不必担心中断处理开销导致数据丢失。 -EHCI 根集线器代码会将 USB 1.1 设备移交给其伴随控制器。 -该驱动不需要了解那些驱动的任何细节； -一个原本就能正常工作的 OHCI 或 UHCI 驱动， -并不会因为 EHCI 驱动也存在而需要更改。 +EHCI 根集线器代码会将 USB 1.1 设备交给其伴随控制器处理。该驱动无需了解 +那些驱动的任何细节；一个原本就能正常工作的 OHCI 或 UHCI 驱动，也不会因为 +EHCI 驱动存在而需要修改。 -电源管理方面还有一些问题； -当前挂起/恢复的行为还不完全正确。 +电源管理方面仍有一些问题；当前挂起/恢复行为还不完全正确。 -此外，在调度周期性事务 -（中断和等时传输）时还采取了一些简化处理。 -这些简化会限制可调度的周期性事务数量， -并且无法使用小于一帧的轮询间隔。 +此外，在调度周期性事务（中断和等时传输）时还采取了一些简化处理。这些 +简化会限制可调度的周期性事务数量，并且无法使用小于一帧的轮询间隔。 使用方式 ======== -假设有一个 EHCI 控制器（位于 PCI 卡或主板上）， -并且已将此驱动编译为模块，可这样加载:: +假设系统中有一个 EHCI 控制器（位于 PCI 卡或主板上），并且此驱动是以模块形 +式编译的，那么可以这样加载:: # modprobe ehci-hcd @@ -120,27 +100,24 @@ EHCI 根集线器代码会将 USB 1.1 设备移交给其伴随控制器。 # rmmod ehci-hcd -还应加载一个伴随控制器驱动， -例如 ``ohci-hcd`` 或 ``uhci-hcd``。 -如果 EHCI 驱动出现任何问题，只需卸载它的模块， -随后该伴随控制器驱动就会接手 -此前由 EHCI 驱动处理的所有设备 -（但速度会降低）。 +还应加载一个伴随控制器驱动，例如 ``ohci-hcd`` 或 ``uhci-hcd``。如果 EHCI +驱动出了问题，只要卸载它的模块，伴随控制器驱动就会接管此前由 EHCI 驱动处 +理的全部设备（只是速度会降低）。 模块参数（传给 ``modprobe``）包括： log2_irq_thresh（默认值 0）： - 默认中断延迟的 log2 值，单位是微帧。默认值 0 表示 1 个微帧 - （125 微秒）。最大值 6 表示 2^6 = 64 个微帧。 + 默认中断延迟的 log2 值，单位为微帧。默认值 0 表示 1 个微帧 + （125 微秒），最大值 6 表示 2^6 = 64 个微帧。 该值控制 EHCI 控制器发出中断的频率。 -如果在 2.5 内核上使用此驱动，并且启用了 USB 调试支持， -则会在任一 EHCI 控制器的 ``sysfs`` 目录中看到三个文件： +如果你在 2.5 内核上使用此驱动，并且启用了 USB 调试支持，那么任一 EHCI 控 +制器对应的 ``sysfs`` 目录下都会看到三个文件： ``async`` 转储异步调度，用于控制传输和批量传输。它会显示每个活动的 ``qh`` 以及待处理的 ``qtd``，通常每个 ``urb`` 对应一个 ``qtd``。 - （可以在 ``usb-storage`` 做磁盘 I/O 时看它；顺便观察请求队列！） + （可以在 ``usb-storage`` 执行磁盘 I/O 时查看；也可顺便观察请求队列。） ``periodic`` 转储周期性调度，用于中断传输和等时传输。不显示 ``qtd``。 @@ -151,111 +128,81 @@ EHCI 根集线器代码会将 USB 1.1 设备移交给其伴随控制器。 这些文件的内容有助于定位驱动问题。 -设备驱动通常不需要关心自己是否运行在 EHCI 之上， -但它们可能想检查 -``usb_device->speed == USB_SPEED_HIGH``。 -高速设备能做到全速（或低速）设备做不到的事， -例如高带宽的周期性传输（中断或 ISO 传输）。 -另外，设备描述符中的某些值 -（例如周期性传输的轮询间隔） -在高速模式下使用不同的编码方式。 +设备驱动通常不需要关心自己是否运行在 EHCI 之上，但有时可能会想检查 +``usb_device->speed == USB_SPEED_HIGH``。高速设备能做到全速（或低速）设备 +做不到的事，例如高带宽的周期性传输（中断或 ISO 传输）。另外，设备描述符 +中的某些值（例如周期性传输的轮询间隔）在高速模式下使用不同的编码方式。 -不过，一定要让设备驱动经过 USB 2.0 集线器的测试。 -当使用事务转换器时，这些集线器报告某些故障 -（例如断开连接）的方式会不同； -已经见过一些驱动在遇到与 OHCI 或 UHCI -所报告的不同故障时表现不佳。 +不过，设备驱动一定要在 USB 2.0 集线器后面测一遍。使用事务转换器时，这些 +集线器报告某些故障（例如断开连接）的方式会有所不同；已经见过一些驱动在 +遇到与 OHCI 或 UHCI 不同的故障时表现不佳。 性能 ==== -USB 2.0 吞吐量主要受两个因素制约： -主机控制器处理请求的速度，以及设备响应这些请求的速度。 -480 Mbit/sec 的“原始传输率”对所有设备都成立， -但总吞吐量还会受到诸如单个高速包之间的延迟、 -驱动是否足够聪明，以及系统整体负载等因素的影响。 -延迟也是性能考量因素。 +USB 2.0 的吞吐量主要受两个因素制约：主机控制器处理请求的速度，以及设备响 +应这些请求的速度。480 Mbit/sec 的“原始传输率”对所有设备都一样，但整体吞 +吐量还会受到诸如高速包之间的间隔、驱动实现是否足够高效以及系统总体负载等 +因素影响。延迟同样是需要考虑的性能指标。 -批量传输最常用于关注吞吐量的场景。 -需要记住的是，批量传输总是以 512 字节包为单位， -而一个 USB 2.0 微帧中最多只能容纳 13 个这样的包。 -8 个 USB 2.0 微帧构成一个 USB 1.1 帧； -一个微帧的时长是 1 毫秒 / 8 = 125 微秒。 +批量传输通常用于看重吞吐量的场景。需要记住的是，批量传输总是以 512 字节包 +为单位，而一个 USB 2.0 微帧中最多只能容纳 13 个这样的包。8 个 USB 2.0 微 +帧构成一个 USB 1.1 帧，因此一个微帧的时长就是 125 微秒。 -因此，只要硬件和设备驱动软件都允许， -批量传输可提供超过 50 MByte/sec 的带宽。 -周期性传输模式（等时和中断）允许使用更大的包大小， -从而可以逼近所宣称的 480 Mbit/sec 传输率。 +因此，只要硬件和驱动实现都足够成熟，批量传输就可以提供 50 MByte/sec 以上 +的带宽。周期性传输模式（等时和中断）允许使用更大的包大小，从而可以逼近所 +宣称的 480 Mbit/sec 传输率。 硬件性能 -------- -截至本文撰写时，单个 USB 2.0 设备的最大传输速率 -通常约为 20 MByte/sec。 -这当然会随着时间改变：一些设备现在更快，一些更慢。 +截至本文撰写时，单个 USB 2.0 设备的最大传输速率通常约为 20 MByte/sec。 +这种情况当然会随时间变化：有些设备现在更快，有些则更慢。 -第一代 NEC EHCI 实现似乎存在 -大约 28 MByte/sec 的硬件瓶颈。 -虽然这对单个 20 MByte/sec 的设备显然已经够用， -但把三个这样的设备挂到同一总线上， -并不能得到 60 MByte/sec。 -问题似乎在于控制器硬件无法并发进行 USB 与 PCI 访问， -因此它每个微帧只会尝试 6 次（也许是 7 次） -USB 事务，而不是 13 次。 -（对一个比其他产品早上市一年的芯片来说， -这是个合理的妥协！） +第一代 NEC EHCI 实现似乎存在大约 28 MByte/sec 的硬件瓶颈。虽然这对单个 +20 MByte/sec 的设备显然已经够用，但把三个这样的设备挂到同一总线上，并不 +能得到 60 MByte/sec。问题似乎在于控制器硬件无法并发进行 USB 与 PCI 访问， +因此它每个微帧只会尝试 6 次（也许是 7 次）USB 事务，而不是 13 次。 +（对一款比其他产品早上市一年的芯片来说，这样的取舍也算合理。） -预计较新的实现会在这方面做得更好， -通过投入更多芯片面积来解决这个问题， -使新的主板芯片组更接近 60 MByte/sec 的目标。 -这既包括 NEC 的更新实现，也包括其他厂商的芯片。 +预计较新的实现会在这方面做得更好，通过投入更多芯片面积来解决这个问题， +使新的主板芯片组更接近 60 MByte/sec 的目标。这既包括 NEC 的更新实现，也 +包括其他厂商的芯片。 -主机从 EHCI 控制器收到“请求已完成”中断的最小延迟 -为一个微帧（125 微秒）。该延迟可以调节； -驱动提供了一个模块选项。默认情况下， -``ehci-hcd`` 使用最小延迟，这意味着当发出一个控制 -或批量请求时，通常可以在不到 250 微秒内得知它已完成 -（具体取决于传输大小）。 +主机从 EHCI 控制器收到“请求已完成”中断的最小延迟为一个微帧 +（125 微秒）。该延迟可以调节；驱动提供了一个模块选项。 +默认情况下，``ehci-hcd`` 使用最小延迟，这意味着发出控制或批量请求后，通 +常不到 250 微秒就能得知它已经完成（具体取决于传输大小）。 软件性能 -------- -即便只是要达到 20 MByte/sec 的传输速率， -Linux-USB 设备驱动也必须让 EHCI 队列始终保持满载。 -这意味着要发出较大的请求， -或者在需要发出一连串小请求时使用批量请求排队。 -如果驱动未做到这一点，那么会直接从性能结果上表现出来。 +即便只是要达到 20 MByte/sec 的传输速率，Linux-USB 设备驱动也必须让 EHCI +队列始终保持满载。这意味着要发出较大的请求，或者在需要发出一连串小请求 +时使用批量请求排队。如果驱动做不到这一点，性能就会明显受影响。 -在典型情况下，使用 ``usb_bulk_msg()`` -以 4 KB 块循环写出， -会浪费超过一半的 USB 2.0 带宽。 -I/O 完成与驱动发出下一次请求之间的延迟， -通常会比一次 I/O 本身耗时更长。 -如果同样的循环改用 16 KB 块，会好一些； -若使用一连串 128 KB 块，则浪费会少得多。 +在典型场景下，如果使用 ``usb_bulk_msg()`` 以 4 KB 块循环写出，会浪费超过 +一半的 USB 2.0 带宽。I/O 完成与驱动发出下一次请求之间的空档，往往比一次 +I/O 本身耗时还长。如果同样的循环改用 16 KB 块，情况会好一些；若使用一连串 +128 KB 块，则浪费会少得多。 +但与其依赖这么大的 I/O 缓冲区来提升同步 I/O 的效率，不如直接向主机控制器 +排队提交多个（批量）请求，然后等待它们全部完成（或在出错时取消）。这种 +URB 排队方式对所有 USB 1.1 主机控制器驱动同样适用。 -但与其依赖这么大的 I/O 缓冲区来让同步 I/O 高效， -不如直接向主机控制器排入多个（批量）请求， -然后等待它们全部完成（或在出错时取消）。 -这种 URB 排队方式对所有 USB 1.1 -主机控制器驱动也同样适用。 - -在 Linux 2.5 内核中，定义了新的 ``usb_sg_*()`` API； -它们会把 scatterlist 中的所有缓冲区都排入队列。 -它们还使用 scatterlist 的 DMA 映射 -（其中可能应用 IOMMU）并减少中断次数， -这些都有助于让高速传输尽可能快地运行。 +在 Linux 2.5 内核中，定义了新的 ``usb_sg_*()`` API；它们会把 scatterlist +中的所有缓冲区都排入队列。它们还使用 scatterlist 的 DMA 映射（其中可能 +应用 IOMMU）并减少中断次数，这些都有助于让高速传输尽可能快地运行。 待办： 中断传输和等时（ISO）传输的性能问题。 - 这些周期性传输都是完全调度的，因此，主要问题可能在于如何触发高带宽模式。 + 这些周期性传输都是完全调度的，因此主要问题可能在于如何触发高带宽模式。 待办： - 通过 ``sysfs`` 中的 ``uframe_periodic_max`` 参数， - 可以分配超过标准 80% 的周期性带宽。 + 通过 ``sysfs`` 中的 ``uframe_periodic_max`` 参数，可以分配超过标准 + 80% 的周期性带宽。 后续将对此进行说明。 diff --git a/Documentation/translations/zh_CN/usb/index.rst b/Documentation/translations/zh_CN/usb/index.rst index eb5aca0c13ec..df99814c6497 100644 --- a/Documentation/translations/zh_CN/usb/index.rst +++ b/Documentation/translations/zh_CN/usb/index.rst @@ -1,4 +1,14 @@ .. SPDX-License-Identifier: GPL-2.0 + +.. only:: subproject and latex + + .. raw:: latex + + \renewcommand{\thesection}{} + \renewcommand{\thesubsection}{} + \kerneldocCJKon + \kerneldocBeginSC{ + .. include:: ../disclaimer-zh_CN.rst :Original: Documentation/usb/index.rst @@ -24,7 +34,7 @@ USB 支持 ehci usbmon -Todolist: +待翻译文档： * functionfs * functionfs-desc @@ -52,3 +62,9 @@ Todolist: ==== * :ref:`genindex` + +.. only:: subproject and latex + + .. raw:: latex + + }\kerneldocEndSC diff --git a/Documentation/translations/zh_CN/usb/usbmon.rst b/Documentation/translations/zh_CN/usb/usbmon.rst index 11b6d5b59dce..db6030cd64a1 100644 --- a/Documentation/translations/zh_CN/usb/usbmon.rst +++ b/Documentation/translations/zh_CN/usb/usbmon.rst @@ -16,67 +16,56 @@ usbmon 简介 ==== -小写形式的 ``usbmon`` 指的是内核中的一项功能， -用于收集 USB 总线上的 I/O 跟踪信息。它类似于网络监控工具 -``tcpdump(1)`` 或 Ethereal 所使用的数据包套接字。 -类似地，人们希望使用 usbdump 或 USBMon -（首字母大写）之类的工具来检查 -usbmon 生成的原始跟踪数据。 - -usbmon 报告的是各个外设驱动 -向主机控制器驱动（HCD）发出的请求。 -因此，如果 HCD 本身有 bug，那么 usbmon 报告的跟踪信息 -可能无法精确对应实际的总线事务。 -这和 tcpdump 的情况是一样的。 - -目前实现了两种 API: ``text`` 和 ``binary``。 -二进制 API 通过 ``/dev`` 命名空间中的字符设备提供， -并且属于 ABI。文本 API 自内核 2.6.35 起已废弃， -但为了方便仍然可用。 +小写的 ``usbmon`` 指的是内核中的一项功能，用于收集 USB 总线上的 I/O 跟踪 +信息。它类似于网络监控工具 ``tcpdump(1)`` 或 Ethereal 使用的数据包套接 +字。通常会用 usbdump 或 USBMon（首字母大写）之类的工具来查看 usbmon 生成 +的原始跟踪数据。 + +usbmon 记录的是各个设备驱动向主机控制器驱动（HCD）发出的请求。因此，如果 +HCD 自身有 bug，usbmon 输出的跟踪信息就未必能和真实的总线事务一一对应。 +这和 tcpdump 的情况类似。 + +目前实现了两种 API：``text`` 和 ``binary``。二进制 API 通过 ``/dev`` 下的 +字符设备提供，是 ABI 的一部分。文本 API 自内核 2.6.35 起已废弃，但为了 +兼容和使用方便，至今仍然保留。 如何使用 usbmon 收集原始文本跟踪信息 ==================================== -与数据包套接字不同，usbmon 提供了一种接口， -可以输出文本格式的跟踪信息。这样做有两个目的： -第一，在更完善的格式最终确定之前， -它作为工具间通用的跟踪交换格式； -第二，在不使用工具的情况下，人们也可以直接阅读这些信息。 +与数据包套接字不同，usbmon 还提供了一个输出文本格式跟踪信息的接口。这样 +做主要有两个目的：一是在更完善的格式最终确定之前，将其作为工具间通用的跟 +踪交换格式；二是在没有工具时也能直接阅读这些信息。 -要收集原始文本跟踪信息，请按以下步骤进行操作。 +要收集原始文本跟踪信息，按下面的步骤做即可。 1. 准备 ------- -挂载 debugfs（内核配置中必须启用它），并加载 usbmon 模块 -（如果它是作为模块构建的）。如果 usbmon 已经编入内核， -那么第二步可以省略。 +挂载 debugfs（内核配置里必须启用它），并加载 usbmon 模块（如果它是以模块 +方式构建的）。如果 usbmon 已经编译进内核，这一步就可以省略。 命令示例:: - # mount -t debugfs none_debugs /sys/kernel/debug + # mount -t debugfs none /sys/kernel/debug # modprobe usbmon # -确认总线套接字是否存在:: +确认 ``usbmon`` 目录下是否有这些条目:: # ls /sys/kernel/debug/usb/usbmon 0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u # -现在，你可以选择使用 ``0u`` 捕获所有总线上的数据包， -并跳到第 3 步； -也可以先按第 2 步找到目标设备所在的总线。 -这样可以过滤掉那些持续输出数据的烦人设备。 +现在，你可以直接用 ``0u`` 捕获所有总线上的数据包，然后跳到第 3 步；也可 +以先按第 2 步找出目标设备所在的总线。这样可以把那些持续产生流量的设备过 +滤掉。 2. 查找目标设备连接的是哪条总线 ------------------------------- -运行 ``cat /sys/kernel/debug/usb/devices``， -找到对应设备的 T 行。通常可以通过厂商字符串来查找。 -如果有许多类似设备，可以拔掉其中一个， -再比较前后两次 ``/sys/kernel/debug/usb/devices`` -的输出。T 行里会包含总线编号。 +运行 ``cat /sys/kernel/debug/usb/devices``，找到对应设备的 T 行。通常可以通过 +厂商字符串来查找。如果有很多相似设备，可以拔掉其中一个，再比较前后两次 +``/sys/kernel/debug/usb/devices`` 的输出。T 行里会包含总线编号。 示例:: @@ -86,8 +75,8 @@ usbmon 报告的是各个外设驱动 S: Manufacturer=ATEN S: Product=UC100KM V2.00 -``Bus=03`` 表示它位于 3 号总线上。或者， -也可以查看 ``lsusb`` 的输出，并从对应行得到总线编号。 +``Bus=03`` 表示它位于 3 号总线上。或者，也可以查看 ``lsusb`` 的输出，并从 +对应条目里找到总线编号。 示例如下:: @@ -97,133 +86,110 @@ usbmon 报告的是各个外设驱动 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 盘、拷贝文件、操作摄像头等。 +这里做一些会产生 USB 流量的操作即可，比如插入 U 盘、拷贝文件、操作摄像头 +等。 5. 停止 cat ----------- -这一步通常通过键盘中断（Control-C）完成。 +这一步通常按下键盘中断（Control-C）即可完成。 -此时输出文件（本例中为 ``/tmp/1.mon.out``） -可以保存、通过电子邮件发送，或使用文本编辑器查看。 -如果使用最后一种方式，请确保文件不会大到编辑器无法打开。 +此时，输出文件（本例中为 ``/tmp/1.mon.out``）可以保存下来，通过电子邮件发 +送，也可以用文本编辑器查看。如果要用文本编辑器查看，请确保文件大小不会 +大到编辑器无法处理。 原始文本数据格式 ================ -目前支持两种格式：原始格式，也就是 ``1t`` 格式， -以及 ``1u`` 格式。``1t`` 格式在内核 2.6.21 中已被废弃。 -``1u`` 格式增加了一些字段，例如 ISO 帧描述符、 -``interval`` 等。它生成的行会稍长一些， -但在其他方面是 ``1t`` 格式的完整超集。 - -如果程序需要区分上述两种格式， -可以查看 ``address`` 字段（见下文）。 -如果其中有两个冒号，就是 ``1t`` 格式； -否则是 ``1u`` 格式。 - -任何文本格式的数据由一系列事件组成， -如 URB 提交、URB 回调、提交错误等。 -每个事件对应单独的一行文本， -由使用空白符间隔的若干字段组成。 -字段的数量与位置可能取决于事件类型， -但以下字段对所有类型都通用： - -下面按从左到右的顺序列出这些共有字段： - -- URB Tag。用于标识 URB，通常是 URB 结构体在内核中的地址 - （以十六进制表示）， - 但也可能是序号或其他合理的唯一字符串。 - -- 时间戳（微秒），十进制数字。 - 时间戳的精度取决于可用时钟， - 因此可能远差于 - 1 微秒（例如实现使用的是 jiffies）。 - -- 事件类型。它表示的是事件的格式，而不是 URB 的类型。 - 可用值为：``S`` 表示提交，``C`` 表示回调，``E`` 表示提交错误。 - -- ``Address`` 字段（以前称作 ``pipe``）。 - 它包含四个由冒号分隔的字段： - URB 类型及方向、总线号、设备地址和端点号。类型与方向的编码如下： - - == == ========================== - Ci Co 控制输入和输出 - Zi Zo 等时输入和输出 - Ii Io 中断输入和输出 - Bi Bo 批量输入和输出 - == == ========================== - - 总线号、设备地址和端点号使用十进制，但可能有前导零。 - -- URB 状态字段。这个字段要么是一个字母， - 要么是几个由冒号分隔的数字： - URB 状态、``interval``、``start frame`` 和 ``error count``。 - 与 ``address`` 字段不同，除了状态外，其余字段都是可选的。 - ``interval`` 只会为中断和等时 URB 打印；``start frame`` 只会为 - 等时 URB 打印；错误计数只会在等时回调事件中打印。 - - 状态字段是一个十进制数字，有时为负数， - 对应 URB 的 ``status`` 字段。 - 对于提交事件，这个字段本身没有实际意义， - 但为了便于脚本解析，它仍然存在。 - 当发生错误时，该字段包含错误码。 - - 在提交控制包时，这个字段包含的是 ``Setup Tag``， - 而不是一组数字。 - 判断 ``Setup Tag`` 是否存在很容易，因为它从来不是数字。 - 因此，如果脚本在这个字段里发现的是一组数字， - 就会继续读取数据长度（等时 URB 除外）。 - 如果发现的是其他内容，比如一个字母， - 那么脚本会先读取 ``Setup`` 包，再读取数据长度或等时描述符。 - -- ``Setup`` 包由 5 个字段组成： - ``bmRequestType``、``bRequest``、``wValue``、 - ``wIndex`` 和 ``wLength``。这些字段由 USB 2.0 规范定义。 - 如果 ``Setup Tag`` 为 ``s``，就可以安全地解码这些字段。 - 否则，说明 Setup 包虽然存在，但并未被捕获，此时各字段中会填入占位内容。 +目前支持两种格式：原始的 ``1t`` 格式和 ``1u`` 格式。``1t`` 格式在内核 +2.6.21 中已被废弃。``1u`` 格式增加了一些字段，例如 ISO 帧描述符和 +``interval``。它生成的行会稍长一些，但除此之外，它是 ``1t`` 格式的完整 +超集。 + +如果程序需要区分上述两种格式，可以查看 ``address`` 字段（见下文）。如果 +其中有两个冒号，就是 ``1t`` 格式；否则是 ``1u`` 格式。 + +任何文本格式的数据都由一系列事件构成，例如 URB 提交、URB 回调和提交错 +误。每个事件占一行，由若干以空白符分隔的字段组成。字段数量和位置会随事件 +类型变化，但下面这些字段对所有类型都通用： + +下面按从左到右的顺序说明这些通用字段： + +- URB 标识（URB Tag）。用于标识 URB，通常是 URB 结构体在内核中的地址 + （十六进制），也可能是序号或其他足以唯一标识 URB 的字符串。 + +- 时间戳（微秒），十进制数字。时间戳的精度取决于可用时钟，所以可能远低于 + 1 微秒（例如实现使用 jiffies 时）。 + +- 事件类型。它表示的是这一行事件的格式，而不是 URB 的类型。可用值为： + ``S`` 表示提交，``C`` 表示回调，``E`` 表示提交错误。 + +- ``Address`` 字段（以前称为 ``pipe``）。它包含四个由冒号分隔的字段：URB + 类型及方向、总线号、设备地址和端点号。类型与方向按下面的方式编码： + + == == ==================== + Ci Co 控制输入与输出 + Zi Zo 等时输入与输出 + Ii Io 中断输入与输出 + Bi Bo 批量输入与输出 + == == ==================== + + 总线号、设备地址和端点号都是十进制数，但可能有前导零，方便人阅读。 + +- URB 状态字段。这个字段要么是一个字母，要么是几个用冒号分隔的数字，依次 + 表示 URB 状态、``interval``、``start frame`` 和 ``error count``。与 + ``address`` 字段不同，除状态外，其余字段都可能省略。``interval`` 只会在 + 中断和等时 URB 中打印；``start frame`` 只会在等时 URB 中打印；错误计数只 + 会在等时回调事件中打印。 + + 状态字段是一个十进制数，有时为负数，对应 URB 的 ``status`` 字段。对于提 + 交事件，这个字段本身并无实际语义，但为了便于脚本解析仍会保留。发生错误 + 时，这里填的是错误码。 + + 如果是控制包的提交事件，这个字段里放的不是一组数字，而是 ``Setup Tag``。 + 这很容易分辨，因为 ``Setup Tag`` 永远不是数字。所以脚本如果在这里读到一 + 组数字，就会继续读取数据长度（等时 URB 除外）；如果读到的是字母之类的内 + 容，就要先读取 ``Setup`` 包，再读取数据长度或等时描述符。 + +- ``Setup`` 包由 5 个字段组成：``bmRequestType``、``bRequest``、``wValue``、 + ``wIndex`` 和 ``wLength``。这些字段由 USB 2.0 规范定义。如果 ``Setup Tag`` + 是 ``s``，就可以安全解码这些字段。否则，说明 Setup 包虽然存在，但并未被 + 捕获，此时各字段中会填入占位内容。 - 等时传输帧描述符的数量及其内容： - 如果一个等时传输事件带有一组描述符，首先打印该 URB 中描述符的总数， - 然后为每个描述符打印一个字段，最多打印 5 个字段。 - 每个字段由三个用冒号分隔的十进制数字组成， - 分别表示状态（status）、偏移（offset）和长度（length）。 - 对于提交（submission），报告的是初始长度； - 对于回调（callback），报告的是实际长度。 + 如果某个等时传输事件带有描述符，会先打印该 URB 的描述符总数，再为每个描 + 述符打印一个字段，最多 5 个。每个字段由三个用冒号分隔的十进制数组成，依 + 次表示状态（status）、偏移（offset）和长度（length）。对于提交事件，报 + 告的是初始长度；对于回调事件，报告的是实际长度。 -- 数据长度： - 对于提交，表示请求的长度；对于回调，表示实际传输的长度。 +- 数据长度：对于提交，表示请求的长度；对于回调，表示实际传输的长度。 -- 数据标签： - 即使数据长度非零，usbmon 也不一定会捕获数据。 - 仅当标签为 ``=`` 时，才会有数据字段。 +- 数据标签：即使数据长度非零，usbmon 也不一定会捕获数据。只有标签为 + ``=`` 时，才会有数据字段。 -- 数据字段： - 以大端十六进制格式显示。注意，这些并不是真正的机器字， - 而只是把字节流拆成若干“字”以便阅读。因此最后一个字可能只包含 - 1 到 4 个字节。 - 收集的数据长度是有限的，可能小于数据长度字段中报告的值。 - 因为数据长度字段只统计实际接收到的字节，而数据字段包含整个传输缓冲区， - 所以，在等时输入（Zi）完成且缓冲区中接收到的数据稀疏的情况下， - 收集的数据长度可能大于数据长度字段的值。 +- 数据字段：以大端十六进制格式显示。注意，这些并不是真正的机器字，只是为 + 了便于阅读，把字节流按“字”分组显示。因此最后一个字可能只包含 1 到 4 个 + 字节。捕获的数据长度是有限的，可能小于数据长度字段中报告的值。对于等时 + 输入（Zi）完成事件，如果缓冲区里的接收数据比较稀疏，捕获数据的长度甚至 + 可能大于数据长度字段，因为后者只统计实际接收到的字节，而数据字段展示的 + 是整个传输缓冲区。 @@ -234,18 +200,19 @@ usbmon 报告的是各个外设驱动 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``）的输出批量传输:: +向地址为 5 的存储设备发送一个输出批量传输，其中 31 字节的 Bulk 封装用于承 +载 SCSI 命令 ``0x28``（``READ_10``）。为便于排版，下面的第一条记录按两行 +显示，但实际 usbmon 输出仍是一行:: - dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 ad000000 00800000 80010a28 20000000 20000040 00000000 000000 + 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 的整体架构与前文大体相同，只是事件以二进制格式传递。 -每个事件都通过下面的结构发送 -（这个名字是为了叙述方便而虚构的）:: +API 的整体架构与前文大体相同，只是事件以二进制格式传递。每个事件都通过 +下面的结构发送（这个结构名只是为了叙述方便而虚构的）:: struct usbmon_packet { @@ -275,29 +242,22 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 unsigned int ndesc; /* 60: 实际 ISO 描述符数量 */ }; /* 64 总长度 */ -可以用 ``read(2)``、``ioctl(2)``， -或者通过 ``mmap`` 访问缓冲区， -从字符设备接收这些事件。 -不过，出于兼容性原因，``read(2)`` -只返回前 48 个字节。 +可以用 ``read(2)``、``ioctl(2)``，或者通过 ``mmap`` 访问缓冲区，从字符设 +备接收这些事件。不过，出于兼容性原因，``read(2)`` 只返回前 48 个字节。 -字符设备通常命名为 ``/dev/usbmonN``， -其中 ``N`` 是 USB 总线号。 -编号为零的设备（``/dev/usbmon0``）比较特殊， -表示“所有总线”。 -请注意，具体命名策略由 Linux 发行版决定。 +字符设备通常命名为 ``/dev/usbmonN``，其中 ``N`` 是 USB 总线号。编号为零的 +设备（``/dev/usbmon0``）比较特殊，表示“所有总线”。具体命名策略由 Linux +发行版决定。 -如果你手动创建 ``/dev/usbmon0``， -请确保它归 root 所有，并且权限为 ``0600``。 -否则，非特权用户将能够窃听键盘流量。 +如果你手动创建 ``/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)`` @@ -309,18 +269,16 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 u32 dropped; }; -成员 ``queued`` 表示当前缓冲区中已经排队的事件数量， -而不是自上次重置以来处理过的事件数量。 +成员 ``queued`` 表示当前缓冲区中已经排队的事件数量，而不是自上次重置以来 +处理过的事件数量。 -成员 ``dropped`` 表示自上次调用 -``MON_IOCG_STATS`` 以来丢失的事件数量。 +成员 ``dropped`` 表示自上次调用 ``MON_IOCG_STATS`` 以来丢失的事件数量。 ``MON_IOCT_RING_SIZE``，定义为 ``_IO(MON_IOC_MAGIC, 4)`` -此调用设置缓冲区大小。参数为以字节为单位的缓冲区大小。 -大小可能会向下取整到下一个块（或页）。 -如果请求的大小超出该内核的 [未指定] 范围， -则调用会失败并返回 ``-EINVAL``。 +此调用设置缓冲区大小。参数是以字节为单位的缓冲区大小。大小可能会向下取整 +到下一个块（或页）。如果请求的大小超出当前内核允许的范围，则调用会失败并 +返回 ``-EINVAL``。 ``MON_IOCQ_RING_SIZE``，定义为 ``_IO(MON_IOC_MAGIC, 5)`` @@ -331,9 +289,8 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 ``MON_IOCX_GETX``，定义为 ``_IOW(MON_IOC_MAGIC, 10, struct mon_get_arg)`` -如果内核缓冲区中没有事件， -这些调用就会一直等待，直到有事件到达， -然后返回第一个事件。 +如果内核缓冲区中没有事件，这些调用就会一直等待，直到有事件到达，然后返回 +第一个事件。 参数是指向以下结构的指针:: struct mon_get_arg { @@ -343,20 +300,18 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 }; -调用前，应填好 ``hdr``、``data`` 和 ``alloc``。 -调用返回后，``hdr`` 指向的区域中包含下一个事件的结构； -如果存在数据，那么数据缓冲区中也会包含相应数据。 -该事件会从内核缓冲区中移除。 +调用前，应填好 ``hdr``、``data`` 和 ``alloc``。调用返回后，``hdr`` 指向的 +内存区域中会写入下一个事件的结构；如果存在数据，数据缓冲区中也会填入相应 +内容。该事件会从内核缓冲区中移除。 -``MON_IOCX_GET`` 会将 48 字节的数据复制到 ``hdr`` 区域， -``MON_IOCX_GETX`` 会复制 64 字节。 +``MON_IOCX_GET`` 会将 48 字节的数据复制到 ``hdr`` 区域，``MON_IOCX_GETX`` +会复制 64 字节。 ``MON_IOCX_MFETCH``，定义为 ``_IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg)`` -当应用程序通过 ``mmap(2)`` 访问缓冲区时， -主要使用这个 ioctl。 -其参数是指向以下结构的指针:: +应用程序通过 ``mmap(2)`` 访问缓冲区时，主要使用这个 ioctl。其参数是指向 +以下结构的指针:: struct mon_mfetch_arg { uint32_t *offvec; /* 获取的事件偏移向量 */ @@ -365,41 +320,36 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 }; -该 ioctl 的操作分为三个阶段： +这个 ioctl 的流程分为三个阶段： -首先，从内核缓冲区移除并丢弃最多 ``nflush`` 个事件。 -实际丢弃的事件数量会写回 ``nflush``。 +首先，从内核缓冲区移除并丢弃最多 ``nflush`` 个事件。实际丢弃的事件数量会 +写回 ``nflush``。 -其次，除非伪设备以 ``O_NONBLOCK`` 打开，否则会一直等待， -直到缓冲区中出现事件。 +其次，除非设备以 ``O_NONBLOCK`` 打开，否则会一直等待，直到缓冲区中出现 +事件。 -第三，将最多 ``nfetch`` 个偏移量提取到 mmap -缓冲区，并存入 ``offvec`` 中。 -实际提取到的事件偏移数量会存回 ``nfetch``。 +第三，将最多 ``nfetch`` 个偏移量提取到 mmap 缓冲区，并存入 ``offvec`` 中。 +实际提取到的事件偏移数量会写回 ``nfetch``。 ``MON_IOCH_MFLUSH``，定义为 ``_IO(MON_IOC_MAGIC, 8)`` -此调用从内核缓冲区移除若干事件。 -其参数为要移除的事件数量。 -如果缓冲区中的事件少于请求数量， -则移除所有事件，且不报告错误。 -当没有事件时也可使用。 +此调用从内核缓冲区移除若干事件。其参数是要移除的事件数量。如果缓冲区中的 +事件少于请求数量，则移除全部现有事件，且不报告错误。即使当前没有事件，也 +可以调用。 ``FIONBIO`` 如果有需要，将来可能会实现 ``FIONBIO`` ioctl。 -除了 ``ioctl(2)`` 和 ``read(2)`` 之外， -二进制 API 的特殊文件也可以用 ``select(2)`` 和 -``poll(2)`` 轮询。 -但 ``lseek(2)`` 不起作用。 +除了 ``ioctl(2)`` 和 ``read(2)`` 之外，二进制 API 对应的特殊文件还可以用 +``select(2)`` 和 ``poll(2)`` 轮询，但 ``lseek(2)`` 不可用。 * 二进制 API 的内核缓冲区内存映射访问 -基本思想很简单： +基本思路很简单： -准备时，先获取当前大小，再用 ``mmap(2)`` 映射缓冲区。 -然后执行类似下面伪代码的循环:: +准备时，先查询当前大小，再用 ``mmap(2)`` 映射缓冲区。之后运行与下面伪代码 +类似的循环:: struct mon_mfetch_arg fetch; struct usbmon_packet *hdr; @@ -411,7 +361,7 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 ioctl(fd, MON_IOCX_MFETCH, &fetch); // 同时处理错误 nflush = fetch.nfetch; // 完成后要刷新这么多包 for (i = 0; i < nflush; i++) { - hdr = (struct ubsmon_packet *) &mmap_area[vec[i]]; + hdr = (struct usbmon_packet *) &mmap_area[vec[i]]; if (hdr->type == '@') // 填充包 continue; caddr_t data = &mmap_area[vec[i]] + 64; @@ -421,7 +371,7 @@ API 的整体架构与前文大体相同，只是事件以二进制格式传递 -因此，主要思想是每 N 个事件只执行一次 ioctl。 +因此，这里的核心思路就是每 N 个事件只执行一次 ioctl。 -虽然缓冲区是环形的，但返回的头和数据不会跨越缓冲区末端， -因此上面的伪代码无需任何合并操作。 +虽然缓冲区是环形的，但返回的头部和数据不会跨越缓冲区末端，因此上面的伪代 +码无需做任何拼接。 -- 2.34.1 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v4] docs/zh_CN: usb: refine translated wording and formatting 2026-06-01 8:26 ` [PATCH v4] " Kefan Bai @ 2026-06-01 9:34 ` Alex Shi 0 siblings, 0 replies; 5+ messages in thread From: Alex Shi @ 2026-06-01 9:34 UTC (permalink / raw) To: Kefan Bai, linux-usb, si.yanteng, gregkh Cc: dzm91, corbet, skhan, linux-doc, linux-kernel, doubled, alexs LGTM. Thanks! On 2026/6/1 16:26, Kefan Bai wrote: > Refine the zh_CN USB translations for clarity and consistency. > > Improve wording, wrapping, and formatting across the translated > USB documents. > > Link:https://lore.kernel.org/r/2026053149-flaky-shallow-2460@gregkh > Suggested-by: Alex Shi<seakeel@gmail.com> > Signed-off-by: Kefan Bai<baikefan@leap-io-kernel.com> > --- > v4: ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2026-06-01 14:16 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
[not found] <2026053149-flaky-shallow-2460@gregkh>
2026-06-01 3:39 ` [PATCH v3] docs/zh_CN: usb: refine translated wording and formatting Kefan Bai
2026-06-01 4:00 ` Alex Shi
2026-06-01 6:19 ` Kefan Bai
2026-06-01 8:26 ` [PATCH v4] " Kefan Bai
2026-06-01 9:34 ` Alex Shi
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox
Powered by JetHome