示例工程【免费下载链接】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点击查看免费下载本指南以 gnss/ReadMe.md 为主线深入解析本仓库中基于 Windows 用户模式驱动框架UMDF 2实现的 GNSS 示例驱动覆盖其总体设计、GNSS DDI 强制要求的具体实现、可自定义扩展点FIX ME 清单、Trace Logging 采集流程以及三类验证测试方法。读完本文你将掌握该示例驱动的代码结构与 IOCTL 分发逻辑并能据此定制出符合 Windows 10 位置服务要求的自有 GNSS 驱动。一、项目概览这是一个怎样的 GNSS 示例驱动gnss目录下的 GNSS UMDF Sample DriverUMDF Version 2是一个提供给 IHV独立硬件供应商与合作伙伴的基础样板驱动其定位是作为模板和指引帮助厂商扩展构建自己的 Windows GPS/GNSS 驱动。解决方案文件为 gnss/gnssUmdf.sln驱动工程源码位于 gnss/gnssUmdf/ 目录。1.1 示例覆盖的内容What is covered遵循 Windows 10 GNSS 驱动设计规范驱动设计对齐 Windows 10 的 GNSS 驱动设计指南与 GNSS 驱动 DDI设备驱动接口要求。作为可扩展模板可作为 IHVs 和合作伙伴定制自有 Windows GNSS 驱动的基础。遵循 WDF 最佳实践围绕 PnP 设备到达/移除、电源管理以及驱动安装/卸载完整遵循 WDF 规范。满足 GNSS DDI 强制性要求实现了 GNSS DDI 中强制要求的功能子集。通过基础测试该驱动成功通过 Visual Studio 提供的 HLK 测试与 WDF 测试见测试计划章节。1.2 示例未覆盖的内容What is not coveredGeofence地理围栏、SUPL、AGNSS 暂不支持这些并非 GNSS DDI 强制功能。SUPL/AGNSS 的可选性SUPL 与 AGNSS 仅在移动运营商要求时才成为强制项当前示例不支持。非生产级驱动本示例是教学/定制样板并非可直接量产上线的生产驱动。二、总体设计与源码结构示例实现的是一个纯软件驱动满足 GNSS DDI 的最低要求它当前始终返回一个硬编码的假定位。驱动开发者可以通过扩展改从文件读取假位置、通过自定义 IOCTL 注入位置或真正对接 GNSS 硬件获取真实定位。从源码结构看驱动采用 C 类 WDF 事件回调的方式组织各文件职责清晰文件职责Driver.cppDriverEntry驱动入口初始化 WPP Tracing 并创建 WDF 驱动对象Device.cpp设备添加OnDeviceAdd、PnP/电源回调、设备接口注册Queue.cpp默认 IO 队列创建、GNSS IOCTL 分发、驱动命令处理FixHandler.cppFix 会话管理开始/停止/修改/获取定位FixSession.cpp单次 Fix 会话的具体实现后台线程获取并上报定位Defaults.h默认版本号、常量与默认假定位数据gnssUmdf.infUMDF 驱动安装配置GnssUmdfSampleDriver.wprpWPR 追踪日志配置文件2.1 驱动入口DriverEntryDriver.cpp 中的DriverEntry完成三件事调用WPP_INIT_TRACING初始化 WPP 软件追踪注册驱动对象清理回调卸载时调用WPP_CLEANUP通过WdfDriverCreate创建设备并指定CDevice::OnDeviceAdd作为EvtDriverDeviceAdd回调。三、核心实现拆解3.1 设备对象与 PnP 电源管理Device.cppDevice.cpp 的CDevice::OnDeviceAdd是设备生命周期的入口注册EvtDeviceD0Entry/EvtDeviceD0Exit电源回调通过WdfDeviceCreate创建设备并设置WdfSynchronizationScopeNone与WdfExecutionLevelPassive在Initialize()中调用CQueue::AddQueueToDevice创建 IO 队列并通过WdfDeviceCreateDeviceInterface注册GUID_DEVINTERFACE_GNSS设备接口注意示例未发布符号链接见 Device.cpp。OnD0Entry/OnD0Exit当前为空实现源码中留有FIX ME注释提示开发者依据 GNSS 驱动的功耗要求补充 D0 进入/退出时的功能如开启/关闭硬件电源。3.2 IO 队列与 GNSS DDI IOCTL 分发Queue.cppQueue.cpp 的AddQueueToDevice创建了一个顺序分发的默认队列WdfIoQueueDispatchSequential并设置PowerManaged WdfFalse所有 IOCTL 请求串行进入设备。OnIoDeviceControl是核心分发入口见 Queue.cpp按 GNSS DDI 分类处理以下 IOCTL能力交换Capability ExchangeIOCTL行为IOCTL_GNSS_SEND_PLATFORM_CAPABILITY接收平台能力示例为空实现仅 breakIOCTL_GNSS_GET_DEVICE_CAPABILITY返回设备能力结构GNSS_DEVICE_CAPABILITYIOCTL_GNSS_GET_CHIPSETINFO返回芯片组信息GNSS_CHIPSETINFO在GetDeviceCapabilityQueue.cpp中示例将连续追踪、距离追踪、Geofence、AGNSS、SUPL、面包屑等能力全部置为FALSE/0版本号则返回_ForcedDriverVersion默认GNSS_DRIVER_DDK_VERSION即GNSS_DRIVER_VERSION_4见 Defaults.h。GetChipsetInfoQueue.cpp返回示例值ManufacturerID Microsoft TestHardwareID UMDF GnssFirmwareVersion 1.0.0.0并明确标注FIX ME替换为实际厂商信息。Fix 会话IOCTL行为IOCTL_GNSS_START_FIXSESSION委托_FixHandler.StartFix传入位置服务开关状态IOCTL_GNSS_STOP_FIXSESSION委托_FixHandler.StopFixIOCTL_GNSS_MODIFY_FIXSESSION委托_FixHandler.ModifyFixIOCTL_GNSS_GET_FIXDATA委托_FixHandler.GetFixRequest驱动命令Driver CommandIOCTL_GNSS_SEND_DRIVERCOMMAND进入HandleDriverCommandQueue.cpp按GNSS_DRIVERCOMMAND_PARAM.CommandType分发GNSS_ClearAgnssData→ClearAgnssData将对应 AGNSS 请求类型标记为需要注入GNSS_ResetEngine→ResetEngine将时间/位置/Blob 三类 AGNSS 注入需求全部置TRUE示意性实现GNSS_SetLocationServiceEnabled→SetLocationServiceStatus更新内部状态当用户关闭位置总开关时会调用_FixHandler.StopExistingSinglsShotFix()停止进行中的单次 Fix 会话GNSS_ForceOperationMode→SetOperationMode记录操作模式仅 SUPL 支持时才强制要求。其余高级命令GNSS_SetLocationNIRequestAllowed、GNSS_ResetGeofencesTracking、GNSS_SetNiTimeoutInterval、GNSS_SetSuplVersion、GNSS_SetUplServerAccessInterval以及 AGNSS、SUPL、NI、Geofence、Breadcrumbing、NMEA 等可选 IOCTL统一返回STATUS_NOT_IMPLEMENTED见 Queue.cpp这与 ReadMe 中不支持 Geofence、SUPL、AGNSS的说明一致。请求处理完成后除STATUS_PENDING异步场景外统一通过WdfRequestComplete完成请求。3.3 Fix 会话与假定位生成FixHandler / FixSessionFixHandler.cpp 的CFixHandler持有单个CFixSession _SingleShotSession与当前会话 ID。StartFix会先检查位置服务总开关再校验会话类型必须为GNSS_FixSession_SingleShot单次定位随后调用_SingleShotSession.StartAcquiringFix。FixSession.cpp 是定位数据的核心生产者初始化Initialize创建 Windows 线程池工作项CreateThreadpoolWork、停止事件_StopFixEvent以及一个手动分发队列_FixAcquisitionRequestQueue用于挂起等待定位的IOCTL_GNSS_GET_FIXDATA请求。开始定位StartAcquiringFix校验状态后记录会话 ID、置状态为ACQUIRING、SubmitThreadpoolWork提交后台工作并启动 GetFix 队列。后台获取循环AcquireSingleFixwhile(true)中以DEFAULT_FIX_INTERVAL_SECONDS * 1000即 1 秒见 Defaults.h为超时等待停止事件超时则调用RetrievePosition获取位置并通过ReportGnssFix上报若上报时没有挂起的 GetFix 请求则缓存定位_HasCachedFix true下次GetFix到达时直接返回缓存。停止定位StopAcquiringFix校验会话 ID 后设置停止事件、等待线程池回调结束并通过WdfIoQueuePurgeSynchronously排空 GetFix 队列。获取定位GetFix校验会话 ID 后若有缓存定位立即完成请求否则将请求转发WdfRequestForwardToIoQueue到手动队列等待上报线程取走。上报定位CompleteRequestWithGnssFix构造GNSS_EVENTEventType GNSS_Event_FixAvailable携带GNSS_FIXDATA与会话 ID写入输出缓冲并完成请求。关键扩展点RetrievePositionFixSession.cpp当前调用RetrievePositionFromPredefinedValue返回硬编码假定位——即美国雷尼尔山国家公园坐标纬度 46.852273、经度 -121.757468精度 10 米时间戳为 2018-12-01 示例值见 Defaults.h 与 FixSession.cpp。源码注释给出了三条定制路线从预定义位置文件读取假定位通过自定义 IOCTL 在CQueue中直接更新_GnssPosition并把该调用改为 no-op对接真实 GNSS 硬件建立并枚举硬件接口如串口、蓝牙读取并解析 NMEA 报文替换RetrievePosition实现。四、合作伙伴需要完成的自定义工作FIX ME 清单ReadMe 明确指出示例代码中的FIX ME注释是厂商必须逐项落实的定制点同时伙伴需自行负责安装驱动、添加证书并完成驱动签名、更新制造商名称与驱动版本号。结合源码核心定制清单如下位置定制内容gnssUmdf.infClassGuid、DriverVer日期版本、硬件 IDRoot\gnssUmdf、ManufacturerName等安装信息Queue.cppGetChipsetInfo替换为真实的制造商、硬件 ID、固件版本Queue.cppGetDeviceCapability按硬件真实能力开启连续追踪、Geofence、AGNSS、SUPL 等支持位FixSession.cppRetrievePosition接入真实 GNSS 数据源或自定义注入方式Device.cppOnD0Entry/OnD0Exit补充电源管理如硬件上电/下电逻辑Queue.cppResetEngine等驱动命令按厂商硬件语义实现引擎复位、AGNSS 数据清除建议验证流程客户安装 WDK 后运行 Location HLK 测试验证自有驱动所有测试用例应通过pass或跳过skip不允许出现失败fail。另外注意由于示例暂不支持 AGNSS、SUPL、GeofenceHLK 会根据驱动能力声明自动跳过对应用例。五、Trace Logging 追踪日志采集示例随解决方案提供 WPRP 追踪配置文件 gnss/GnssUmdfSampleDriver.wprp。该文件定义了一个事件收集器缓冲区 128KB、40 个缓冲、循环文件模式、单文件上限 5MB、最多 3 个文件并注册了示例驱动的 ETW ProviderGUIDCEB3BF01-80E4-4DC7-B3BF-F6B5279EB8C4Level 5全部关键字使能。采集步骤将GnssUmdfSampleDriver.wprp复制到被测设备然后在命令行执行MyLog.etl为示例输出文件名wpr -start GnssUmdfSampleDriver.wprp -filemode 复现问题 wpr -stop MyLog.etl之后用 Trace 分析工具如 Windows Performance Analyzer检查MyLog.etl。注意需要配套的 PDB 符号文件才能解码日志信息——驱动源码中大量使用TraceEvents(TRACE_LEVEL_*, TRACE_DRIVER/TRACE_DEVICE/TRACE_QUEUE/TRACE_FIX, ...)输出关键事件如WdfDeviceCreate failed with Status %!STATUS!配合 PDB 可还原为可读的函数与状态信息。六、测试计划客户定制驱动后ReadMe 建议按三种方法验证方法 1WDF 运行时测试基础功能该测试验证 WDF 基础功能PnP 等而非 Location 特有功能。运行 Visual Studio 内置的WDF 运行时测试驱动测试管理器 / 运行测试预期结果 / 通过标准通过率 100%。方法 2HLK Location 测试位置功能该测试验证位置相关功能如获取定位。运行HLKWindows 硬件实验室工具包中现有的标准 GNSS 驱动测试具体命令TE.exe GNSSDriverTest.dll预期结果 / 通过标准通过率 100%。如前所述示例不支持 AGNSS、SUPL、GeofenceHLK 将依据驱动能力自动跳过对应测试。方法 3Windows Geolocation API 应用层验证真实应用在真实应用上验证 Geolocation 层打开 Windows 内置Maps地图应用点击显示我的位置确认能获取当前位置运行Geolocation Sample 应用中的跟踪tracking场景在 Windows 商店的GPS Satellite 应用中点击Start获取当前位置。通过上述应用场景可以端到端验证驱动返回的定位数据是否被位置服务正常消费。七、参考资料与延伸学习围绕本示例可进一步研读的仓库资源GNSS DDI 参考源码中使用的GNSS_DEVICE_CAPABILITY、GNSS_CHIPSETINFO、GNSS_FIXSESSION_PARAM、GNSS_FIXDATA、GNSS_EVENT、GNSS_DRIVERCOMMAND_PARAM等结构即来自 GNSS DDI 定义gnss/ReadMe.md官方使用说明全文GnssUmdfSampleDriver.wprp追踪配置可直接复用对应 GNSS 驱动设计指南、GNSS DDI 参考文档、Windows 驱动入门文档、NMEA 格式文档等微软官方资料可结合 WDK 文档体系查阅本文不再列外部链接。小结该 GNSS UMDF2 示例驱动以最小可用实现演示了WDF 设备生命周期 顺序 IO 队列 GNSS DDI 强制 IOCTL 后台 Fix 线程上报定位的完整驱动骨架。对开发者而言最有价值的不是它返回的假定位而是每个环节预留的FIX ME扩展点——从能力上报、芯片组信息、驱动命令到定位数据源均给出了清晰的定制接口与替换路径是构建生产级 Windows GNSS 驱动的理想起点。赞分享示例工程【免费下载链接】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点击查看免费下载相关推荐NocoBase Trace 追踪 API 详解Trace 类、SpanProcessor 注册与 OpenTelemetry 分布式追踪实战NocoBase Trace 追踪 API 详解Trace 类、SpanProcessor 注册与 OpenTelemetry 分布式追踪实战 NocoBas低代码后端前端人工智能AI 应用工作流自动化Slang 硬件光线追踪实战ray-tracing 示例的 RayQuery 内联追踪与 BLAS/TLAS 构建全解析Slang 硬件光线追踪实战ray tracing 示例的 RayQuery 内联追踪与 BLAS/TLAS 构建全解析 本指南以 examples/ray编译器图形学编程语言深入解析 bsc 的 evm t8n 追踪测试用例用 testdata/31 验证 Tracer 与 Trace 输出深入解析 bsc 的 evm t8n 追踪测试用例用 testdata/31 验证 Tracer 与 Trace 输出 导读 本文以 bsc 仓库基于 go区块链Web3上一篇深入理解PhoGPT架构为什么3.7B参数能实现8192上下文长度下一篇OceanBase存储引擎日志延迟监控终极指南工具与告警配置方法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
