IOCTL_MIPI_DSI_TRANSMISSION IOCTL (ntddvdeo.h)
发出IOCTL_MIPI_DSI_TRANSMISSION 以将一系列 MIPI DSI 数据包发送到外围设备。
主要代码
输入缓冲区
N/A
输入缓冲区长度
N/A
输出缓冲区
N/A
输出缓冲区长度
N/A
输入/输出缓冲区
一个DXGK_DSI_TRANSMISSION结构，后跟包含数据包的DXGK_DSI_PACKET结构。
输入/输出缓冲区长度
至少 sizeof(DXGK_DSI_TRANSMISSION) + ((PacketCount - 1) * sizeof(DXGK_DSI_PACKET)) + FinalPacketExtraPayload。 有关详细信息，请参阅“备注”。
状态块
Irp->如果请求成功，IoStatus.Status 设置为 STATUS_SUCCESS。 否则， 状态 设置为 NTSTATUS 代码中的相应错误条件。 有关详细信息，请参阅 NTSTATUS 值。
注解
监视器、oem 面板和显示端口/微型端口驱动程序必须处理移动行业处理器接口 (MIPI) 数字串行接口 (DSI) IOCTL。
执行传输
若要允许面板驱动程序通过图形适配器和面板硬件之间的此专用接口进行交互，事务必须不具有图形驱动程序效果（除了占用总线的时间之外），或者必须完全定义这些事务，以便图形驱动程序处于控制状态。 由于允许面板驱动程序交互的要点是提供对图形驱动程序不透明的自定义面板功能的支持，因此完全定义的操作旨在仅限于面板驱动程序需要执行标准化操作的事务，而这种操作在没有图形驱动程序参与的情况下无法执行。 此类事务将被视为显式路由的异常，而不是传输。
每个传输请求由 OEM 面板驱动程序填充的单个缓冲区组成，该缓冲区向下传递监视器堆栈，并返回传输结果（如果有）。 缓冲区包含有关传输的总体信息，包括输入和输出字段，后跟一个大小可变的 DXGK_DSI_PACKET 结构数组。 数据包以 DSI 术语进行描述，以便可以描述任何 DSI 数据包，但 OS 将分析数据包并拒绝包含不允许的数据包的任何传输。 根据 DSI 定义，除最后一个数据包之外的所有数据包都是写入数据包，这些数据包可能是短写入（在这种情况下 有效负载 缓冲区未使用）或适合 有效负载 缓冲区的长写入。 传输中的最后一个数据包（可以是读取或写入）可以通过分配和描述更大的缓冲区来使用扩展有效负载，该缓冲区将允许空间用于读取或写入任意大小的数据包，最大为 64K-1 数据字节的 DSI 长数据包数据限制。 这允许在单个调用中将小型写入数据包的序列排队到驱动程序，但确实需要单独发送较大的数据包。 FinalPacketExtraPayload 字段的值指示已分配的额外字节数，但还必须在 TotalBufferSize 字段中考虑这一点。
OEM 面板驱动程序负责确保它请求的传输不冲突或干扰图形驱动程序用于与面板正常交互的其他传输，因为过多的请求或请求操作会导致处理其他传输的延迟。 面板驱动程序不得更改任何会导致图形驱动程序后续故障的状态，例如通过 MCS 命令更改面板计时。 同样，如果 OS 通过图形驱动程序（例如亮度增加）请求了显示更改，则面板驱动程序不得使用 DSI 命令撤消该更改，无论是为了响应还是出于其他目的。
IOCTL_MIPI_DSI_TRANSMISSION 用于请求传输到包含一个或多个 DSI 数据包的外围设备。 面板驱动程序必须始终初始化 TotalBufferSize、 PacketCount 和每个数据包的前三个字节。 面板驱动程序可以使用 TransmissionMode、ReportMipiErrors、ClearMipiErrors、SecondaryPort、ManufacturingMode 和 FinalCommandExtraPayload 的非零值替代默认行为。 所有未初始化的值都必须设置为零。
OS 将确保 DSI 数据包序列格式正确，在所有已定义的字段中包含有效信息以及正确的缓冲区大小。 OS 负责初始化 FailedPacket 字段以DXGK_DSI_INVALID_PACKET_INDEX，以便仅在发现特定数据包出现问题时，OS 或驱动程序中的进一步验证才需要设置 字段。 如果 DXGK_DSI_TRANSMISSION 结构格式不正确，OS 将在 HostErrors 字段中设置DXGK_HOST_DSI_INVALID_TRANSMISSION标志，以将此错误与其他无效参数错误区分开来。
若要被视为格式正确，必须满足以下所有条件：
- TotalBufferSize >= sizeof (DXGK_DSI_TRANSMISSION) + ( (PacketCount - 1) * sizeof (DXGK_DSI_PACKET) ) + FinalPacketExtraPayload
- FinalPacketExtraPayload <= 64K-1-DXGK_DSI_PACKET_EMBEDDED_PAYLOAD_SIZE (0xFFF7)
- TotalBufferSize <= ROUND_TO_PAGES ( sizeof (DXGK_DSI_TRANSMISSION) + (0xFE * sizeof (DXGK_DSI_PACKET) ) + 0xFFF7 )
- PacketCount ！= 0
- 仅允许最后一个数据包为读取
- 只有最终的长写入数据包的 LongWriteWordCount 值可以大于 DXGK_DSI_PACKET_EMBEDDED_PAYLOAD_SIZE
数据包验证
尽管 OS 不会尝试完全验证所有数据包的内容，但它会拒绝包含除以下内容以外的任何 DSI 命令的传输，无需调用图形驱动程序即可完成 IOCTL：
| 数据类型值 | 说明 |
|---|---|
| 0x03 | 泛型短写，无参数 |
| 0x13 | 泛型短写，1 个参数 |
| 0x23 | 泛型短写，2 个参数 |
| 0x04 | 泛型 READ，无参数 |
| 0x14 | 泛型 READ，1 个参数 |
| 0x24 | 泛型 READ，2 个参数 |
| 0x05 | DCS 短写入，无参数 |
| 0x15 | DCS 短写，1 个参数 |
| 0x06 | DCS READ，无参数 |
| 0x29 | 一般长写入 |
| 0x39 | DCS 长写入/write_LUT |
一般读取和写入命令需要了解面板规范，因此，只要不过度使用总线，面板驱动程序就可以自由使用这些命令，而不会给图形驱动程序带来问题。 同样，DCS MCS 命令明确定义供制造商使用，因此图形驱动程序和面板驱动程序之间的干扰应该没有问题。
对于 DCS UCS，图形驱动程序不应使用未定义的命令，因此 OS 将允许面板驱动程序使用它们，尽管未来 MIPI-DCS 规范更改显然存在定义命令的风险，因此首选 MCS 命令。
标准化的 DCS UCS 命令将在正常操作期间由图形驱动程序使用，并且可能由面板驱动程序使用，因此需要降低 OEM 面板驱动程序发送的命令导致后续图形驱动程序命令出现问题的风险。 为此，OS 将分析 DCS 命令并拒绝预期会导致冲突的数据包，除非 OEM 面板驱动程序设置 ManufacturingMode 标志，并且 OS 确认系统处于制造模式。 如果设置了标志，但系统未处于制造模式，则传输 IOCTL 将在字段中设置HostErrorsDXGK_HOST_DSI_INVALID_TRANSMISSION标志完成，而无需调用图形驱动程序。
需要完全定义的事务而不是使用传输的条件是：
- 在之前或之后需要计时空闲期，例如 DCS soft_reset
- 更改帧输出的操作环境，例如 DCS set_vsync_timing和enter_sleep_mode
- 使用具有开始/继续语义的事务，其中图形驱动程序可能还需要访问相同的数据，例如 DCS write_memory_start/write_memory_continue
此外，还有一些类的 DCS 命令在作为传输发送时会被 OS 拒绝：
- 需要完全定义的任何命令，如上所述
- 读取可用于屏幕抓取的像素数据
- 写入像素数据
OS 将传递给图形驱动程序的 UCS 命令
| Hex | 命令 |
|---|---|
| 00h | nop |
| 26h | set_gamma_curve |
| 2Dh | write_LUT |
| 51h | set_display_brightness |
| 52h | get_display_brightness |
| 53h | write_control_display |
| 54h | get_control_display |
| 55h | write_power_save |
| 56h | get_power_save |
| 5Eh | set_CABC_min_brightness |
| 5Fh | get_CABC_min_brightness |
| 03h | get_compression_mode |
| 05h | get_error_count_on_DSI |
| 06h | get_red_channel |
| 07h | get_green_channel |
| 08h | get_blue_channel |
| 0Ah | get_power_mode |
| 0Bh | get_address_mode |
| 0Ch | get_pixel_format |
| 0Dh | get_display_mode |
| 0Eh | get_signal_mode |
| 0Fh | get_diagnostic_result |
| 14h | get_image_checksum_rgb |
| 15h | get_image_checksum_ct |
| 3Fh | get_3D_control |
| 45h | get_scanline |
OS 将拒绝的 UCS 命令
| Hex | 命令 |
|---|---|
| 01h | soft_reset - 注意，必须通过IOCTL_MIPI_DSI_RESET发送 |
| 10h | enter_sleep_mode |
| 11h | exit_sleep_mode |
| 12h | enter_partial_mode |
| 13h | enter_normal_mode |
| 20h | exit_invert_mode |
| 21h | enter_invert_mode |
| 28h | set_display_off |
| 29h | set_display_on |
| 2Ah | set_column_address |
| 2Bh | set_page_address |
| 2Ch | write_memory_start |
| 2Eh | read_memory_start |
| 30h | set_partial_rows |
| 31h | set_partial_columns |
| 33h | set_scroll_area |
| 34h | set_tear_off |
| 35h | set_tear_on |
| 36h | set_address_mode |
| 37h | set_scroll_start |
| 38h | exit_idle_mode |
| 39h | enter_idle_mode |
| 3Ah | set_pixel_format |
| 3Ch | write_memory_continue |
| 3Dh | set_3D_control |
| 3Eh | read_memory_continue |
| 40h | set_vsync_timing |
| 44h | set_tear_scanline |
| A1h | read_DDB_start |
| A2h | read_PPS_start |
| A8h | read_DDB_continue |
| A9h | read_PPS_continue |
注意
将来的版本中可能会修改 OS 验证策略。
图形驱动程序实现
如果传输通过 OS 验证，OS 将使用 DsiTransmission 将缓冲区传递到图形驱动程序。
将 OEM 传输添加到接口中，该接口已用于根据 OS 请求和外围控制需求发送像素和控制数据，这不可避免地意味着图形驱动程序需要增强其内部排序，以确保可以正确合并此附加的数据包流。 图形驱动程序不得对 OEM 面板驱动程序的传输中的数据包重新排序，并且必须不间断地发送整个序列，且不会交错其他数据包。 图形驱动程序不需要根据 OEM 面板传输请求的到达时间维护其数据包的顺序，因此可以选择在 (之前或) 发送 OEM 面板传输之后发送数据包来设置以下帧。 如果完成已启动的 OEM 面板传输可能导致关键数据包错过其时间范围，则驱动程序应将传输报告为已取消。 如果传输尚未启动，但驱动程序预期它会导致关键数据包错过其时间范围，则驱动程序应推迟开始传输，直到下一个空白期。 如果延迟 OEM 面板传输会导致它等待两个以上的帧启动，驱动程序应报告传输已丢弃。
图形驱动程序无法确保它代表面板驱动程序发送的传输不与其控制的传输发生冲突。 驱动程序可以选择检查传输中的数据包，如果它们会导致问题，则拒绝传输，但任何被视为不安全的数据包都应标记为 OS 级别拒绝，因此驱动程序级别拒绝在理想情况下应由图形供应商特定问题引起。 驱动程序不得尝试缓存或优化读取或写入，即使数据包似乎是标准化命令。
如果图形驱动程序由于数据包问题而拒绝传输，则必须使用导致传输被拒绝的第一个数据包的索引更新 FailedPacket 字段，并在返回之前设置 HostErrors DXGK_HOST_DSI_DRIVER_REJECTED_PACKET标志。 如果提供了传输模式替代，驱动程序应验证替代是否与其硬件约束兼容，如果不符合，请在返回之前设置 HostErrors DXGK_HOST_DSI_BAD_TRANSMISSION_MODE标志。
如果在通信期间发生故障，图形驱动程序应使用失败数据包的索引更新 FailedPacket 字段，但驱动程序不可能在所有情况下都标识数据包，因此驱动程序应保留默认值（DXGK_DSI_INVALID_PACKET_INDEX）。在这种情况下，驱动程序应保留默认值（DXGK_DSI_INVALID_PACKET_INDEX）。
图形驱动程序负责数据包的通信，因此必须确保计算和验证任何检查总和。 以读取结尾的任何传输都将是短数据包，因此 Data0 和 Data1 字段包含任何参数，响应可以是短数据包或长数据包。 图形驱动程序可能不知道返回的数据的格式和时长，但最大大小是最终数据包的有效负载的完整大小，包括 FinalPacketExtraPayload。 OS 将验证此值是否不大于 TargetMaximumReturnPacketSize 驱动程序针对目标报告的值，但驱动程序必须确保此缓冲区不会因外设报告更多数据而溢出，并且不会因为当前应用于外设的 MaximumReturnPacketSize 而截断来自外围设备的数据。 驱动程序将读取到缓冲区 ReadWordCount 的字节数写入描述传输的字段。
在某些情况下，由于与 OEM 面板驱动程序无关且无法观察到的错误，图形驱动程序可能被迫重置到面板或整个面板的通信接口。 若要解决此问题，驱动程序必须报告重置后第一次传输尝试时在字段中设置 HostErrors DXGK_HOST_DSI_INTERFACE_RESET或DXGK_HOST_DSI_DEVICE_RESET，以便 OEM 面板驱动程序能够检测情况并恢复。 驱动程序不得将此传输发送到硬件，但如果不需要恢复，OEM 面板驱动程序可能只需重试相同的命令，在这种情况下，驱动程序应像往常一样继续处理传输。
完成传输
当 IOCTL 完成FailedPacket读取的 、ReadWordCount、 MipiErrorsHostErrors 和 有效负载 (最终) 数据包可能已更新，具体取决于结果。 如果在处理传输时发现错误，OEM 面板驱动程序需要使用 MipiErrors 和 HostErrors 输出值来确定如何恢复并继续。
为了确保输出返回到调用方以提供任何错误的详细信息，IOCTL 和 DDI 调用需要报告成功，即使发现错误也是如此。 成功并不表示事务成功，它表示对处理事务的调用按预期进行，并且已设置错误标志（如果适用）。 对于不受支持的 DDI 调用 (可能是由于驱动程序不匹配) 、内存分配失败或传递了完全错误的参数（例如传递 NULL 缓冲区）等情况，仍可能会报告失败。 如果未报告成功调用的错误，则调用方应假定事务成功。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows 10 版本 2004 |
| 标头 | ntddvdeo.h |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈