> 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/pass.4.md).

# pass.4

`pass` — CAM 应用程序直通驱动

## 名称

`pass`

## 概要

`device pass`

## 描述

`pass` 驱动让用户态应用程序能向内核发送 CAM CCB。

由于 `pass` 驱动允许直接访问 CAM 子系统，系统管理员在授予对此驱动的访问权限时应格外谨慎。如果使用不当，此驱动可能允许用户态应用程序使机器崩溃或导致数据丢失。

`pass` 驱动附加到系统中找到的每个 SCSI 和 ATA 设备。由于它附加到每个设备，因此能通用访问 SCSI 和 ATA 设备，并允许用户访问没有关联“标准”外设驱动程序的设备。

## 内核配置

内核中只需配置一个 `pass` 设备；`pass` 设备会在发现 SCSI 和 ATA 设备时自动分配。

## IOCTLS

**CAMIOCOMMAND** union ccb \* 此 ioctl 接受大多数类型的 CAM CCB，并将它们传递给 CAM 传输层执行。注意，某些 CCB 类型不允许通过直通设备，必须通过 [xpt(4)](/man/man4/xpt.4.md) 设备发送。一些仅限 xpt 的 CCB 例子包括 XPT\_SCAN\_BUS、XPT\_DEV\_MATCH、XPT\_RESET\_BUS、XPT\_SCAN\_LUN、XPT\_ENG\_INQ 和 XPT\_ENG\_EXEC。这些 CCB 类型具有各种属性，使得通过直通接口为它们提供服务不合逻辑或不可能。如果用户希望内核进行错误恢复，必须在 CCB 上设置 `CAM_PASS_ERR_RECOVER` 标志，并将 retry\_count 字段设置为重试次数。

**CAMGETPASSTHRU** union ccb \* 此 ioctl 接受一个 XPT\_GDEVLIST CCB，并返回与讨论的设备对应的直通设备。虽然此 ioctl 可通过 `pass` 驱动使用，但用途有限，因为如果调用者发出此 ioctl，他们必须已经知道讨论的设备是直通设备。通过 [xpt(4)](/man/man4/xpt.4.md) 设备发出此 ioctl 可能更有用。

**CAMIOQUEUE** union ccb \* 将 CCB 排队到 `pass` 驱动以异步执行。调用者可使用 select(2)、poll(2) 或 kevent(2) 在 CCB 完成时接收通知。此 ioctl 接受大多数 CAM CCB，但某些 CCB 类型不允许通过 pass 设备，必须通过 [xpt(4)](/man/man4/xpt.4.md) 设备发送。一些仅限 xpt 的 CCB 例子包括 XPT\_SCAN\_BUS、XPT\_DEV\_MATCH、XPT\_RESET\_BUS、XPT\_SCAN\_LUN、XPT\_ENG\_INQ 和 XPT\_ENG\_EXEC。这些 CCB 类型具有各种属性，使得通过直通接口为它们提供服务不合逻辑或不可能。虽然 `CAMIOQUEUE` ioctl 未定义为接受参数，但它确实需要一个指向 union ccb 的指针。不定义为接受参数是为了避免在通用 ioctl(2) 处理程序中进行额外的 malloc 和复制。已完成的 CCB 将通过 `CAMIOGET` ioctl 返回。仅当为请求分配内存或从用户态复制内存出错时，才会从 `CAMIOQUEUE` ioctl 返回错误。所有其他错误将作为标准 CAM CCB 状态错误报告。由于在 `CAMIOQUEUE` ioctl 中 CCB 不会从 pass 驱动复制回用户进程，因此用户传入的 CCB 不会被修改。即使对于立即 CCB 也是如此。相反，必须通过 `CAMIOGET` ioctl 检索已完成的 CCB 并检查其状态。任意时刻都可以通过 `CAMIOQUEUE` ioctl 排队多个 CCB，它们的完成顺序可能与提交顺序不同。调用者必须设法识别已排队和已完成的 CCB。struct ccb\_hdr 内的 `periph_priv` 结构可供用户态在 `CAMIOQUEUE` 和 `CAMIOGET` ioctl 中使用，并会在调用间保留。此外，struct ccb\_hdr 内的 periph\_links 链表指针可供用户态在 `CAMIOQUEUE` 和 `CAMIOGET` ioctl 中使用，并会在调用间保留。如果用户希望内核进行错误恢复，必须在 CCB 上设置 `CAM_PASS_ERR_RECOVER` 标志，并将 retry\_count 字段设置为重试次数。

**CAMIOGET** union ccb \* 检索通过 `CAMIOQUEUE` ioctl 排队的已完成 CAM CCB。仅当 `pass` 驱动无法将数据复制到用户进程或没有可检索的已完成 CCB 时，才会从 `CAMIOGET` ioctl 返回错误。如果没有可检索的 CCB，errno 将设为 `ENOENT`。所有其他错误将作为标准 CAM CCB 状态错误报告。虽然 `CAMIOGET` ioctl 未定义为接受参数，但它确实需要一个指向 union ccb 的指针。不定义为接受参数是为了避免在通用 ioctl(2) 处理程序中进行额外的 malloc 和复制。当 CCB 完成时，pass 驱动将通过 select(2)、poll(2) 或 kevent(2) 报告。每次 `CAMIOGET` 调用可检索一个 CCB。CCB 的返回顺序可能与提交顺序不同。因此，调用者应使用 CCB 头中的 `periph_priv` 区域存储指向标识信息的指针。

## 文件

**`/dev/pass`** `n` `pass` 驱动的字符设备节点。通过 CAM 子系统访问的每个设备都应有一个对应的节点。

## 诊断

无。

## 参见

kqueue(2), poll(2), select(2), cam(3), cam\_cdbparse(3), cam(4), [cd(4)](/man/man4/cd.4.md), [ctl(4)](/man/man4/ctl.4.md), [da(4)](/man/man4/da.4.md), [sa(4)](/man/man4/sa.4.md), [xpt(4)](/man/man4/xpt.4.md), [camcontrol(8)](/man/man8/camcontrol.8.md), camdd(8)

## 历史

CAM 直通驱动最早出现于 FreeBSD 3.0。

## 作者

Kenneth Merry <ken@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/pass.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.