> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/man/man4/usb_quirk.4.md).

# usb\_quirk.4

`usb_quirk` — USB quirks 模块

## 名称

`usb_quirk`

## 概要

要将此模块编译进内核，请将以下行加入你的内核配置文件：

> device usb

或者，要在引导时以模块方式加载该模块，请将以下行加入 loader.conf(5)：

```sh
usb_quirk_load="YES"
```

## 描述

`usb_quirk` 模块提供对使用 usbconfig(8) 动态添加和删除 USB 设备 quirks 的支持。

## 通用 quirks：

**UQ\_AUDIO\_SWAP\_LR** 交换左右声道

**UQ\_AU\_INP\_ASYNC** 尽管声称是自适应的，输入实际上是异步的

**UQ\_AU\_NO\_FRAC** 不对分数样本进行调整

**UQ\_AU\_NO\_XU** 音频设备的扩展单元损坏

**UQ\_AU\_VENDOR\_CLASS** 音频设备使用厂商类来标识自身

**UQ\_AU\_SET\_SPDIF\_CM6206** 音频设备需要特殊编程才能启用 S/PDIF 音频输出

**UQ\_BAD\_ADC** 错误的音频规范版本号

**UQ\_BAD\_AUDIO** 设备声称是音频类，但实际不是

**UQ\_BROKEN\_BIDIR** 打印机的双向模式损坏

**UQ\_BUS\_POWERED** 设备实际是总线供电的，尽管声称不是

**UQ\_HID\_IGNORE** 设备应被 hid 类忽略

**UQ\_KBD\_IGNORE** 设备应被 kbd 类忽略

**UQ\_KBD\_BOOTPROTO** 设备应设置引导协议

**UQ\_UMS\_IGNORE** 设备应被 ums 类忽略

**UQ\_MS\_BAD\_CLASS** 标识不正确

**UQ\_MS\_LEADING\_BYTE** 鼠标发送一个未知的前导字节

**UQ\_MS\_REVZ** 鼠标的 Z 轴反向

**UQ\_MS\_VENDOR\_BTN** 鼠标的按钮在厂商用法页中

**UQ\_NO\_STRINGS** 字符串描述符损坏

**UQ\_POWER\_CLAIM** 集线器对电源状态撒谎

**UQ\_SPUR\_BUT\_UP** 虚假的鼠标按钮释放事件

**UQ\_SWAP\_UNICODE** 某些 Unicode 字符串被交换

**UQ\_CFG\_INDEX\_1** 默认选择配置索引 1

**UQ\_CFG\_INDEX\_2** 默认选择配置索引 2

**UQ\_CFG\_INDEX\_3** 默认选择配置索引 3

**UQ\_CFG\_INDEX\_4** 默认选择配置索引 4

**UQ\_CFG\_INDEX\_0** 默认选择配置索引 0

**UQ\_ASSUME\_CM\_OVER\_DATA** 假定 cm over data 特性

**UQ\_IGNORE\_CDC\_CM** 忽略 cm 描述符

**UQ\_WMT\_IGNORE** 设备应被 wmt 驱动忽略

## USB 大容量存储 quirks：

**UQ\_MSC\_NO\_TEST\_UNIT\_READY** 发送 start/stop 而非 TUR

**UQ\_MSC\_NO\_RS\_CLEAR\_UA** 不重置单元注意

**UQ\_MSC\_NO\_START\_STOP** 不支持 start/stop

**UQ\_MSC\_NO\_GETMAXLUN** 不支持 get max LUN

**UQ\_MSC\_NO\_INQUIRY** 伪造通用查询响应

**UQ\_MSC\_NO\_INQUIRY\_EVPD** 不支持查询 EVPD

**UQ\_MSC\_NO\_SYNC\_CACHE** 不支持同步缓存

**UQ\_MSC\_SHUTTLE\_INIT** 需要 Shuttle 初始化序列

**UQ\_MSC\_ALT\_IFACE\_1** 切换到备用接口 1

**UQ\_MSC\_FLOPPY\_SPEED** 使用软盘速度（20kb/s）

**UQ\_MSC\_IGNORE\_RESIDUE** 残留值计算错误

**UQ\_MSC\_WRONG\_CSWSIG** 使用错误的 CSW 签名

**UQ\_MSC\_RBC\_PAD\_TO\_12** 将 RBC 请求填充至 12 字节

**UQ\_MSC\_READ\_CAP\_OFFBY1** 报告扇区数，而非最大扇区

**UQ\_MSC\_FORCE\_SHORT\_INQ** 不支持完整查询

**UQ\_MSC\_FORCE\_WIRE\_BBB** 强制使用 BBB 线协议

**UQ\_MSC\_FORCE\_WIRE\_CBI** 强制使用 CBI 线协议

**UQ\_MSC\_FORCE\_WIRE\_CBI\_I** 强制使用带中断的 CBI 线协议

**UQ\_MSC\_FORCE\_PROTO\_SCSI** 强制使用 SCSI 命令协议

**UQ\_MSC\_FORCE\_PROTO\_ATAPI** 强制使用 ATAPI 命令协议

**UQ\_MSC\_FORCE\_PROTO\_UFI** 强制使用 UFI 命令协议

**UQ\_MSC\_FORCE\_PROTO\_RBC** 强制使用 RBC 命令协议

## 3G 数据卡（u3g）quirks：

**UQ\_MSC\_EJECT\_HUAWEI** 在 Huawei USB 命令后弹出

**UQ\_MSC\_EJECT\_SIERRA** 在 Sierra USB 命令后弹出

**UQ\_MSC\_EJECT\_SCSIEJECT** 在 SCSI 弹出命令 `0x1b0000000200` 后弹出

**UQ\_MSC\_EJECT\_REZERO** 在 SCSI rezero 命令 `0x010000000000` 后弹出

**UQ\_MSC\_EJECT\_ZTESTOR** 在 ZTE SCSI 命令 `0x850101011801010101010000` 后弹出

**UQ\_MSC\_EJECT\_CMOTECH** 在 C-motech SCSI 命令 `0xff52444556434847` 后弹出

**UQ\_MSC\_EJECT\_WAIT** 等待设备弹出

**UQ\_MSC\_EJECT\_SAEL\_M460** 在 Sael USB 命令后弹出

**UQ\_MSC\_EJECT\_HUAWEISCSI** 在 Huawei SCSI 命令 `0x11060000000000000000000000000000` 后弹出

**UQ\_MSC\_EJECT\_TCT** 在 TCT SCSI 命令 `0x06f504025270` 后弹出

**UQ\_MSC\_DYMO\_EJECT** 在 HID 命令 `0x1b5a01` 后弹出

有关受支持 quirks 的完整列表，请参见 **`/sys/dev/usb/quirk/usb_quirk.h`** 或运行 "usbconfig dump\_quirk\_names"。

## LOADER 可调参数

以下可调参数可在引导内核前于 [loader(8)](/man/man8/loader.8.md) 提示符下设置，或存储在 loader.conf(5) 中。

```sh
“VendorId ProductId LowRevision HighRevision UQ_QUIRK,... ”
```

**`hw.usb.quirk.%d`** 该值为一个字符串，格式为：为所有匹配 `VendorId` 和 `ProductId` 且硬件版本在 `LowRevision` 和 `HighRevision` 之间（含边界）的 USB 设备安装 quirks `UQ_QUIRK,...`。`VendorId`、`ProductId`、`LowRevision` 和 `HighRevision` 均为 16 位数字，可为十进制或十六进制。最多可定义 100 个变量 `hw.usb.quirk.0, .1, ..., .99`。如果在内核内部 quirks 表中找到匹配条目，则替换为新定义。否则，若 quirks 表未满，则创建新条目。内核从 `N = 0` 开始迭代 `hw.usb.quirk.N` 变量，直到 `N = 99` 或第一个不存在的变量为止。

## 实例

在附加了显示为 `ugen0.3` 上 USB 设备的 `u3g` 设备后：

```sh
usbconfig -d ugen0.3 add_quirk UQ_MSC_EJECT_WAIT
```

在 `ugen1.4` 上启用 Holtec/Keep Out F85 游戏键盘：

```sh
usbconfig -d ugen1.4 add_quirk UQ_KBD_BOOTPROTO
```

若要在引导时安装 quirk，请在 loader.conf(5) 中加入一行或多行如下内容：

```sh
hw.usb.quirk.0="0x04d9 0xfa50 0 0xffff UQ_KBD_IGNORE"
```

## 参见

usbconfig(8)

## 历史

`u3g` 模块出现于 FreeBSD 8.0，由 Hans Petter Selasky <hselasky@FreeBSD.org> 编写。本手册页由 Nick Hibma <n_hibma@FreeBSD.org> 编写。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://book.bsdcn.org/man/man4/usb_quirk.4.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.