AVStream 模拟硬件示例驱动（Avshws）深度解析：Pin-Centric 捕获驱动与散聚 DMA 的实现范式-北京尧图网络

示例工程【免费下载链接】Windows-driver-samplesThis repo contains driver samples prepared for use with Microsoft Visual Studio and the Windows Driver Kit (WDK). It contains both Universal Windows Driver and desktop-only driver samples.项目地址https://gitcode.com/gh_mirrors/wi/Windows-driver-samples点击查看免费下载导读AvshwsAVStream Simulated Hardware Sample是 Windows 驱动示例仓库中一个专门用于演示pin-centric AVStream 迷你驱动编写方法的视频捕获驱动示例。它通过软件仿真一块真实的视频捕获硬件以 320×240 分辨率输出 RGB24 或 YUV422YUY2格式的视频流并演示如何借助 AVStream 类驱动提供的 DMA 相关功能将合成画面直接 DMA 到捕获缓冲区中。阅读本文后你将掌握 AVStream 驱动从 DriverEntry、设备/过滤器/引脚描述符布局到 scatter/gather 映射编程、stream pointer 克隆与 DMA 完成回调的完整实现脉络并可在装有 WDK 的机器上完成构建、部署、安装与 GraphEdit 可视化验证。一、示例整体定位与核心特性根据 avstream/avshws/README.md 的定义该示例提供的是一个pin-centric 捕获驱动用于模拟一块捕获硬件。它的两个核心演示目标是如何编写 pin-centric AVStream 迷你驱动与 filter-centric 不同pin-centric 驱动将数据处理process dispatch放在引脚pin上由 AVStream 在合适的时机调用。如何基于 AVStream 类驱动实现 DMA示例执行的是直接写入捕获缓冲区direct-to-capture-buffer的 DMA而不是公共缓冲区common buffer 拷贝策略因此需要调用KsDeviceRegisterAdapterObject将 DMA 适配器注册进 AVStream并使用 scatter/gather 映射。同时该示例特别强调其具备增强的参数校验与溢出检测能力enhanced parameter validation and overflow detection这一点在 capture.cpp 的DispatchSetFormat与IntersectHandler中有明确体现详见后文第六节。二、代码层级从 DriverEntry 到图像合成的四层架构README 的 Sample code hierarchy 一节给出了代码组织路线结合源码可以还原出完整的层级关系主头文件见 avshws.h其中按序包含 image.h、hwsim.h、device.h、filter.h、capture.h。1. 设备层Device.cpp / Device.h入口与 PnP 生命周期Device.cpp 中的DriverEntry是驱动入口点。它不做任何初始化工作而是将控制权直接移交给 AVStreamreturn KsInitializeDriver ( DriverObject, RegistryPath, CaptureDeviceDescriptor );CaptureDeviceDescriptorKSDEVICE_DESCRIPTOR指向CaptureDeviceDispatch分发表并携带过滤器描述符列表。README 指出这是 AVStream 迷你驱动的常见行为通过设备描述符递归定义整个 AVStream 对象层级随后 AVStream 在 Add Device / Start 时依据这些描述符建立过滤器工厂。设备层其余关键职责均位于 device.cppDispatchCreateAdd Device创建CCaptureDevice对象并通过KsAddItemToObjectBag放入设备对象包object bag对象包在设备移除时自动清理。PnpStart创建设备的虚拟硬件——实例化CHardwareSimulation即 README 所说的模拟捕获硬件类并调用KsCreateFilterFactory动态创建 KS Filter 工厂KSCREATE_ITEM_FREEONSTOP标志指示过滤器工厂在停止时释放。这里还预留了真实驱动解析资源列表、连接中断的位置。PnpStop通过DmaOperations-PutDmaAdapter归还先前在 PnP Start 时经IoGetDmaAdapter获取的 DMA 适配器该适配器在 README 中说明已通过KsDeviceRegisterAdapterObject注册给 AVStream这正是直接 DMA 进捕获缓冲区而非公共缓冲区 DMA的前提。AcquireHardwareResources/ReleaseHardwareResources以m_PinsWithResources做互斥锁模拟单捕获设备的资源占用语义。它还根据KS_VIDEOINFOHEADER中的biBitCount与biCompression选择合成器24 位 RGBKS_BI_RGB创建CRGB24Synthesizer注意biHeight为负表示底左原点需翻转16 位 YUY2FOURCC_YUY2创建CYUVSynthesizer其他格式一律返回STATUS_INVALID_PARAMETER。Start / Pause / Stop将 AVStream 的状态变化传递给硬件仿真其中Start时把AvgTimePerFrame、biWidth、ABS(biHeight)、biSizeImage作为仿真参数传入。ProgramScatterGatherMappings把 AVStream 提供的KSMAPPING数组交给硬件仿真编程fake DMA 表。Interrupt仿真 ISR。它读取硬件仿真完成映射数并通过ICaptureSink::CompleteMappings通知捕获引脚本次完成的映射数量。设备上下文结构可参见 device.hm_DmaAdapterObject、m_NumberOfMapRegisters、m_CaptureSink、m_VideoInfoHeader等成员注释明确说明m_VideoInfoHeader的稳定性必须由调用方引脚保证直到资源释放。2. 过滤器层Filter.cpp / Filter.h描述符与引脚布局Filter.cpp 是 README 所说单视频引脚KSPIN_DESCRIPTOR_EX布局的位置同时定义了KSFILTER_DISPATCH与KSFILTER_DESCRIPTOR过滤器分发表只提供create dispatchCCaptureFilter::DispatchCreate没有 filter process——因为这是 pin-centric 示例处理逻辑在引脚上README 原话The process dispatch is provided on the pin because this is a pin-centric sample。捕获过滤器的分类 GUID 有三个KSCATEGORY_VIDEO、KSCATEGORY_CAPTURE、KSCATEGORY_VIDEO_CAMERA。引脚描述符要点CaptureFilterPinDescriptors数据流方向KSPIN_DATAFLOW_OUT输出引脚通信方式KSPIN_COMMUNICATION_BOTH引脚分类PIN_CATEGORY_CAPTURE名称PINNAME_VIDEO_CAPTURE标志KSPIN_FLAG_PROCESS_IN_RUN_STATE_ONLY仅在 RUN 状态处理实例数 1/1指定CapturePinAllocatorFraming与交集处理函数CCapturePin::IntersectHandler。过滤器描述符未定义拓扑仅一个引脚无需跨条等拓扑关系版本使用KSFILTER_DESCRIPTOR_VERSION。3. 引脚层Capture.cpp / Capture.h处理回调与 DMA 完成Capture.cpp 是 README 重点强调的两个演示 DMA 的关键例程所在文件例程一CCapturePin::Process处理回调这是引脚分发表KSPIN_DISPATCH中指定的 Process 回调负责 stream pointer 操作与克隆流程如下用KsPinGetLeadingEdgeStreamPointerKSSTREAM_POINTER_STATE_LOCKED锁定前缘leading edgestream pointer若前缘无数据则KsStreamPointerAdvance前进到下一帧若尚无m_PreviousStreamPointer用KsStreamPointerClone克隆前缘并分配STREAM_POINTER_CONTEXT该上下文只含一个PUCHAR BufferVirtual用于把缓冲区按散聚映射尺寸切块见 capture.h同时把ClonePointer-StreamHeader-DataUsed置 0DMA 队列必须自行更新该字段调用m_Device-ProgramScatterGatherMappings把Leading-OffsetOut.Mappings / Remaining编程进假硬件若映射被全部用完则m_PreviousStreamPointer NULL否则保留克隆指针以便后续续接用KsStreamPointerAdvanceOffsets按已用映射数前进前缘若硬件 S/G 表已满无法加入更多项返回STATUS_PENDING并置m_PendIo等待 DMA 完成 DPC 通过KsPinAttemptProcessing重新踢起处理见CompleteMappings末尾。例程二CCapturePin::CompleteMappings映射完成回调该例程由设备层CCaptureDevice::Interrupt在DPC 级调用传入本次完成的映射数量。它遍历克隆指针链表KsPinGetFirstCloneStreamPointer对完成全部映射的克隆设置Duration m_VideoInfoHeader-AvgTimePerFrame若引脚分配了时钟通过KsPinGetReferenceClockInterface获取见 SetState 的 ACQUIRE 分支则以m_Clock-GetTime()打时间戳并置KSSTREAM_HEADER_OPTIONSF_TIMEVALID | KSSTREAM_HEADER_OPTIONSF_DURATIONVALID否则时间戳为 0递增帧号并在 StreamHeader 尺寸足够时填充扩展头KS_FRAME_INFOdwFrameFlags KS_VIDEO_FLAG_FRAME、PictureNumber、DropCount删除已完成克隆对部分完成的克隆用KsStreamPointerAdvanceOffsets推进偏移并停止遍历。此外 capture.cpp 还包含DispatchCreate创建引脚、用KsEdit修改描述符与 allocator framing帧数固定为 2Min/MaxFrameSize 与 biSizeImage 一致、Stepping 为 0并设置Pin-StreamHeaderSize sizeof(KSSTREAM_HEADER) sizeof(KS_FRAME_INFO)、CaptureVideoInfoHeader把连接格式中的 VIDEOINFOHEADER 拷贝到私有分配并放入对象包、SetStateKSSTATE_STOP/ACQUIRE/PAUSE/RUN 与硬件的 Stop/Acquire/Start/Pause 联动注释中特别说明了为兼容 DirectX 8.0 在 ACQUIRE 时提前停硬件的做法、DispatchSetFormat与IntersectHandler。引脚支持的数据格式同文件末尾的FormatRGB24Bpp_Capture与FormatYUY2_Capture两个KS_DATARANGE_VIDEO静态实例RGB24320×240、24 bpp、KS_BI_RGBAvgTimePerFrame 333667100ns 单位约 29.97fpsMin/MaxFrameInterval 为 333667 ~ 640000000YUY2320×240、16 bpp、FOURCC_YUY2mmioFOURCC(Y,U,Y,2)定义于 avshws.h引脚数据范围列表CapturePinDataRanges共两项YUY2 在前、RGB24 在后数量常量CAPTURE_PIN_DATA_RANGE_COUNT 2allocator framing 使用DECLARE_SIMPLE_FRAMING_EXKSMEMORY_TYPE_KERNEL_NONPAGED、要求系统内存、默认 2 帧、单帧大小 2*PAGE_SIZE创建后会被KsEdit按实际 biSizeImage 修正。4. 硬件仿真层HWSim.cpp / HWSim.h假 DMA、假 ISR、假 DPChwSim.cpp 实现了 README 文件清单中描述的硬件仿真包括假 DMA 传输、散聚映射处理、ISR 等。核心机制假中断节拍Start用KeQuerySystemTime记录起始时间按m_TimePerFrame用KeSetTimer设置定时器到期触发SimulatedInterruptDPCDPC 中调用CHardwareSimulation::FakeHardwareFakeHardware内首先合成一帧图像然后调用硬件 sink 的Interrupt()即设备层 ISR最后按下一帧时间重新KeSetTimer除非m_StopHardware被置位此时置事件让 Stop 等待方退出。帧合成FakeHardware调用m_ImageSynth-SynthesizeBars()生成 EIA-189-A 标准彩条随后用OverlayText在图像中下部叠加走时时钟格式MINUTES:SECONDS.HUNDREDTHS由PtsRel换算而来并在左上角叠加跳帧计数Skipped: %ld——这正是 README Run the sample 一节描述的输出画面。假 DMA 传输ProgramScatterGatherMappings在自旋锁保护下把SCATTER_GATHER_ENTRY含虚拟地址、字节数、克隆指针链入m_ScatterGatherMappings列表最大 128 项常量SCATTER_GATHER_MAPPINGS_MAX见 hwsim.hFillScatterGatherBuffers在每次假中断时把合成缓冲区按行拷贝到这些映射指向的虚拟地址中——若排队映射不足一帧则跳过该帧并递增m_NumFramesSkipped即跳帧/饥饿计数。注意FillScatterGatherBuffers中还会读取KS_FRAME_INFO的lSurfacePitch来支持带 pitch 的 RGB 表面行距。生命周期Pause/Stop通过m_StopHardware标志 m_HardwareEvent事件实现与假 DPC 的同步Stop释放合成缓冲区、清空并释放 S/G 列表S/G 条目内存来自ExInitializeNPagedLookasideList创建的非分页 lookasideReadNumberOfMappingsCompleted返回累计完成映射数。5. 图像合成层Image.cpp / Image.h彩条、文字叠加与两种格式image.h 定义了CImageSynthesizer抽象基类及其两个派生类CRGB24Synthesizer每像素 3 字节BGR 顺序GetBytesPerPixel返回 3通过m_FlipVertical支持上下翻转对应biHeight 0的底左原点。CYUVSynthesizer每像素 2 字节的 UYVY 打包格式GetBytesPerPixel返回 2PutPixel依据像素奇偶性分别写入 1 或 3 字节以维持 UYVY 采样结构并在 DBG 版本用NT_ASSERT校验像素位置奇偶性。基类提供SetImageSize、SetBuffer、SynthesizeBarsEIA-189-A 标准彩条与OverlayText软件字符串叠加支持POSITION_CENTER居中、背景/前景色、TRANSPARENT透明色等。COLOR枚举从BLACK到MAX_COLOR另含TRANSPARENT。三、在 Visual Studio 中配置并构建示例README 的 Provision a target computer 一节给出了标准构建流程可归纳为三步打开工程在装有示例的主机上启动 Visual Studio从File → Open → Project/Solution...导航到 Avshws 示例所在目录选择 VC 工程文件avshws.vcxproj解决方案文件为 avshws.sln工程文件为 avshws.vcxproj。配置解决方案平台在Solution Explorer顶部右键解决方案 Solution avshws选择Configuration Manager按照 WDK 文档中使用 Visual Studio 和 WDK 构建驱动的说明设置目标平台、操作系统与调试配置并构建。该示例工程会自动为驱动包签名This sample project will automatically sign the driver package。准备目标机按照 WDK 文档中为驱动部署与测试配置目标计算机的说明配置目标机并确认目标机的Network and Sharing Center控制面板中已启用Network Discovery网络发现与File and Printer Sharing文件和打印机共享。四、部署驱动到目标机构建完成后按 README 的 Deploy the driver to the target computer 一节执行在解决方案的Package文件夹下找到包工程package右键选择Properties在Configuration Properties → Driver install → Deployment下勾选Enable deployment点击Configure Computer...按钮在弹出的对话框中填写Target Computer Name主机可自动完成目标机的预配置与调试器选项设置从Build菜单选择Deploy Solution部署。部署完成后可在目标机的%Systemdrive%\drivertest\drivers文件夹中看到部署的驱动包。五、安装驱动Add Legacy Hardware 向导README 的 Install the driver 一节给出了在目标机上通过设备管理器安装的完整步骤打开Device Manager在Action菜单中选择Add Legacy Hardware出现 Add Hardware Wizard 后连续点击Next在 Add Hardware 窗口选择Show All Devices在左侧Manufacturer列表中选择Microsoft右侧Model列表中出现AVStream Simulated Hardware Sample选中并点击Next再次点击Next安装驱动最后点击Finish退出向导。安装完成后示例驱动会出现在设备管理器控制台树Sound, video and game controllers分类下。驱动对应的 INF 文件为 avshws.inx构建时转换生成 .inf安装后位于系统盘 *windows\System32\DriverStore\FileRepository*目录下。六、运行示例GraphEdit 可视化验证README 的 Run the sample 一节提供了用 GraphEdit 观察驱动输出的方法这也是验证本文前述 DMA/合成逻辑是否生效的最直观途径安装完成后通过 WDK 的tools目录下的Graphedt.exe访问驱动先用管理员权限打开提升的命令行窗口导航到 WDK 或 SDKtools目录其中包含 proppage.dll执行regsvr32 proppage.dll注册成功会提示 DllRegisterServer in proppage.dll succeeded点击OK——这用于让 GraphEdit 能显示部分内置 Microsoft DirectShow 过滤器的属性页在 GraphEdit 中点击Graph → Insert Filters示例会出现在WDM Streaming Capture Devices分类下名为avshws Source点击Insert Filter图中出现单一过滤器 avshws Source带有一个输出引脚视频捕获引脚该引脚以YUY2格式发射视频对应 capture.cpp 中CapturePinDataRanges首个条目即默认 YUY2 数据范围将该过滤器连接到DirectShow Video Renderer或VMR 默认视频渲染器然后点击Play。预期输出效果也是 README 的原文描述输出为320×240 像素的标准 EIA-189-A 彩条图像由CImageSynthesizer::SynthesizeBars生成图像中下部靠近底边处有一个时钟显示从图上一次进入运行状态起的已运行时间格式为MINUTES:SECONDS.HUNDREDTHS对应 hwsim.cpp 中%ld:%02ld.%02ld的格式化逻辑基于m_TimePerFrame推算的PtsRel图像左上角有一个计数器统计自上次停止后进入运行状态以来被丢弃跳帧的帧数对应FillScatterGatherBuffers因 S/G 映射不足而跳过帧时递增的m_NumFramesSkipped并以Skipped: %ld叠加显示。七、示例的增强参数校验与溢出防护源码佐证README 强调该示例features enhanced parameter validation and overflow detection。结合源码可以定位到具体实现这正是把示例当作教科书而非玩具的关键乘法溢出检测capture.cpp 中的MultiplyCheckOverflow(a, b, pab)执行 32 位无符号乘法并验证(*pab / a) b防止计算biWidth × |biHeight|、再乘biBitCount/8时发生算术溢出。数据结构边界校验DispatchSetFormat与IntersectHandler都先校验KS_SIZE_VIDEOHEADER不小于bmiHeader.biSize、DataFormatSize不溢出且不超过DataFormat.FormatSize防止恶意或错误的biSize导致越界读取注释明确指出(ab a)即无符号算术溢出。格式匹配严格性DispatchSetFormat逐一比对biWidth、biHeight、biCompression与数据范围一致否则返回STATUS_NO_MATCHbiSizeImage必须不小于按像素计算的最小图像尺寸否则STATUS_INVALID_PARAMETER。动态格式更改OldFormat ! NULL仅在KSSTATE_STOP下允许运行中更改返回STATUS_INVALID_DEVICE_STATE。交集语义完整IntersectHandler对尺寸查询返回STATUS_BUFFER_OVERFLOW、缓冲区过小返回STATUS_BUFFER_TOO_SMALL、范围不匹配返回STATUS_NO_MATCH并对调用方的bFixedSizeSamples、bTemporalCompression、ConfigCaps等字段逐一比对成功时用KS_DIBSIZE计算biSizeImage并同时写入SampleSize。C 对象内存管理device.cpp 顶部重载了 placementnew/new[]/delete运算符族统一走ExAllocatePoolZero/ExFreePool并带_When_(NonPagedPoolMustSucceed...)静态注解对象包清理回调Cleanup保证对构造的 C 对象正确调用析构而非裸ExFreePool。八、文件清单File ManifestREADME 的文件清单如下表各文件均位于 avstream/avshws/ 目录下文件说明avshws.h示例主头文件含 IHardwareSink/ICaptureSink 接口、HARDWARE_STATE 枚举、常量与各类 extern 声明avshws.inx示例安装文件构建时生成 INFcapture.cpp捕获过滤器上所有捕获引脚的引脚实现含 Process、CompleteMappings、SetState、DispatchSetFormat、IntersectHandler 与数据范围定义capture.h捕获引脚的引脚级头文件device.cpp模拟硬件的设备级实现DriverEntry、PnP 生命周期、资源获取/释放、S/G 编程入口与设备 ISRdevice.h模拟硬件的设备级头文件filter.cpp捕获过滤器实现含过滤器描述符、引脚描述符与过滤器分发表不含帧合成filter.hfilter-centric 捕获过滤器的过滤器级头文件hwsim.cpp硬件仿真实现包括假 DMA 传输、散聚映射处理、ISR 等hwsim.h硬件仿真头文件image.cpp图像合成与叠加代码彩条、像素合成、RGB24/UYVY 缓冲写入与字符串叠加image.h图像合成与叠加头文件purecall.c驱动中使用虚函数所必需的_purecall桩实现工程配套文件还包括 avshws.vcxproj、avshws.vcxproj.Filters、avshws.sln、avshws.rc 与 makefile。九、进一步阅读建议深入每个 .cpp 文件的头部注释README 建议For more information, see the comments in all .cpp files——这些注释详细解释了 stream pointer 克隆的动机、公共缓冲区 DMA 与直接 DMA 的差异、DirectX 8.0 兼容性处理等设计决策。对比仓库中的 filter-centric 示例 avssamp可直观理解 pin-centric本示例与 filter-centric 在处理回调位置、stream pointer 使用方式上的差异。若想观察更完整的 AVStream 捕获链路含设备 MFT可参考同仓库 avstream 目录下的 sampledevicemft 与 samplemft0 等配套示例。总而言之Avshws 用约 1500 行源码完整呈现了一条描述符驱动仿真硬件散聚 DMA的 pin-centric 捕获驱动实现路径从DriverEntry的KsInitializeDriver交接到设备 PnP 时KsCreateFilterFactory建过滤器、KsDeviceRegisterAdapterObject注册 DMA 适配器再到引脚 Process 回调中克隆 stream pointer、编程 S/G 表最终由假 ISR/DPC 驱动CompleteMappings完成帧递交与时间戳标注。无论你是要编写真实的 USB/PCI 视频捕获驱动还是想透彻理解 AVStream 的 DMA 对象模型这份示例都值得逐行研读。赞分享示例工程【免费下载链接】Windows-driver-samplesThis repo contains driver samples prepared for use with Microsoft Visual Studio and the Windows Driver Kit (WDK). It contains both Universal Windows Driver and desktop-only driver samples.项目地址https://gitcode.com/gh_mirrors/wi/Windows-driver-samples点击查看免费下载相关推荐gpui-kit VirtualList 虚拟列表完全指南可变尺寸大数据集渲染与滚动控制gpui kit VirtualList 虚拟列表完全指南可变尺寸大数据集渲染与滚动控制 VirtualList 是 gpui kit 面向大规模数据集的高性示例工程ST7789-STM32驱动方案硬件SPI与DMA技术深度解析ST7789 STM32驱动方案硬件SPI与DMA技术深度解析 ST7789 STM32是一款专为STM32微控制器设计的高效显示驱动方案通过硬件SPI接口嵌入式驱动开发Linux 内核 amdxdna 驱动深度解析AMD NPU 硬件架构、调度机制与驱动实现Linux 内核 amdxdna 驱动深度解析AMD NPU 硬件架构、调度机制与驱动实现本文围绕 Linux 内核中 Documentation/acce操作系统内核驱动驱动开发虚拟化嵌入式网络存储上一篇React Native AdMob部署指南生产环境广告集成的完整流程下一篇StartBootstrap Clean Blog Jekyll 项目常见问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

AVStream 模拟硬件示例驱动（Avshws）深度解析：Pin-Centric 捕获驱动与散聚 DMA 的实现范式

相关推荐

做网站推广怎么做？3个实操步骤+源码下载避坑指南

Vue 3 实现图片裁剪框：拖动、缩放与固定宽高比

PaddleNLP ERNIE 全字符中文词表制作指南：从语料统计到 Vocab 生成与预训练应用

更多资讯

如何 30 分钟跑通：WeKnora RAG 知识库本地部署完整指南

TradingAgents-CN 部署指南：三条命令拉起一套多智能体股票分析平台

大模型推理网关的会话粘滞与全局负载均衡实战

使用 AWS Device Farm 浏览器测试特性在 CI 中运行 Selenium 测试：PyTest 实战指南

2026最新专做耐克阿迪鞋网站SEO全案

个人备案网站可以做商城吗详细步骤

今日更新

如何彻底离线使用 Laya-CoreML：Hugging Face 下载、缓存机制与 local_files_only 详解

基于1Panel 部署MySQL MCP 服务：TaoToken 统一 Key 接入与 config.toml 配置实战

崇州园区营销网站建设避坑指南：5大注意事项保备案安全

本周精选

如何彻底离线使用 Laya-CoreML：Hugging Face 下载、缓存机制与 local_files_only 详解

基于1Panel 部署MySQL MCP 服务：TaoToken 统一 Key 接入与 config.toml 配置实战

崇州园区营销网站建设避坑指南：5大注意事项保备案安全

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？