请点击以下链接下载 WinHEC 的演讲材料 Download WinHEC presentations here: - PowerPoint Presentation

请点击以下链接下载 WinHEC 的演讲材料 Download WinHEC presentations here: http://channel9.msdn.com/Events/WinHEC/2015

Accessing GPIO, I2C, and UART Devices Devin Wong (Chinese Presenter) Fred Bhesania ( English Presenter)

Windows provides a simplistic framework to communicate with devices on Low Power Buses (LPB).

Introduction and Agenda Session introduction Modern devices and sensors use a combination of low power buses (e.g. GPIO, SPI, I2C, UART, etc.) to connect and interact with each other. This session will introduce you to the different frameworks that Windows provides for you to write a sensor or device client driver on these low power buses. Session agenda An overview of Windows’ low power buses Walkthrough of an accelerometer sensor driver over the I2C bus Best Practices and Tips to Avoid Common Errors References and Call to Action

Overview of Windows Low Power Buses Architecture

Low power buses on Windows

Device connections with low power buses System Chipset I 2 C 1 I 2 C 2 UART Accelerometer Touchpad Bluetooth Radio Ambient Light Sensor GPIO

Resource Hub Connects the Pieces Together Firmware ACPI I 2 C GPIO UART I 2 C Microsoft SoC Vendor Firmware IHV Accelerometer Ambient Light Sensor Touchpad Bluetooth Radio Resource Hub

Device manager representation Resource Hub is the key piece that ties the right controllers with peripherals. Developers, IT Managers and enthusiasts can clearly identify the topology and manage the device just like any other Plug&Play device.

Typical device d river a rchitecture UMDF Class Extension Driver (e.g. Sensor Class Extension) Peripheral Device Driver KMDF Class Extension Bus Driver Bus Controller Driver KMDF Class Extension Bus Driver Bus Controller Driver Peripheral Hardware Microsoft SoC Vendor IHV KMDF UMDF

GPIO framework GPIO components GPIO controller driver : Manages hardware-specific operations for a GPIO controller. Driver provided by SoC silicon partner. GPIO class extension driver : P rovides hardware-agnostic GPIO functionality for the device driver. P rovided by Microsoft. GPIO framework benefitsDevice driver can use GPIO pins as I/O resources or interrupts.Framework abstracts GPIO physical interrupts as ordinary interrupts and helps route them to their respective interrupt service routines.Framework manages the I/O callbacks to the hardware on reads and writes. Device Driver GPIO Class Extension Driver (GpioClx.sys) GPIO Controller Driver Physical Hardware

SPB (I 2 C, SPI) framework SPB components SPB c ontroller driver : Manages hardware-specific operations for an I2C or SPI controller . Driver provided by SoC silicon partner. SPB framework extension : Abstracts bus-specific and controller-specific I/O handling from the device driver. Provided by Microsoft.SPB device driver: The driver that communicates with the peripheral attached to I2C/SPI. Driver provided by peripheral IHV or Microsoft.SPB framework benefitsSingle device driver can be used for different bus types (e.g. I2C, SPI)The framework is scalable to support other simple buses in the futureFramework manages I/O requests to the hardware on reads and writes. Frameworks allows client drivers to perform complicated sequences via an atomic Sequence IOCTL. Handled by the Framework, not each client driver.Support for complex I/O requests, such as connection or controller locks. Full-duplex I/O operations are supported by controllers for buses such as SPI that can simultaneously read and write data. Device Driver SPB Framework Extension (SpbCx.sys) I2C or SPI Controller Driver Physical Hardware

SPB Client Driver - HID over I2C Microsoft’s peripherals class driver over I 2 C. Industry standard supported by over 100 hardware partners. Common peripherals include touch, sensors, HID, etc. Characteristics Supports any I 2 C Speed (100K-1M recommended) Requires out-of-band interrupt mechanism (e.g. GPIO line) Supports wakeup from low power statesDebugability (ETW & WPP) enabled in the driver.

Serial framework – SerCX V2 Serial components Serial controller driver : Manages hardware-specific operations for an serial controller (UART ). Driver provided by SoC silicon partner. Serial framework extension : Abstracts controller-specific I/O handling from the device driver. Provided by Microsoft . Serial device driver : The driver that communicates with the peripheral attached to the UART. Driver provided by peripheral IHV or Microsoft.Serial framework benefitsVersion 2.0 provided in Windows 8.1. Simplifies controller driver creation, diagnosability and power management. Standardized client driver interface for V1 and V2. Hardware flowcontrol recommended/supported to prevent FIFO overflow. Device Driver Serial Framework Extension (SerCx2.sys) Serial (UART) Controller Driver Physical Hardware

Example: Accelerometer sample driver lower edge and how it communicates over I 2 C & GPIO

Example: Accelerometer sensor ADXL345Acc accelerometer Simple low-power 3-axis accelerometer. UMDF V2.0 sensors driver Steps to success: Select and setup your development environments Adapt the driver to your Hardware Install the driver (via Plug&Play) Validate using the tools provided UMDF V2 Sensors Class Extension ADXL345Acc Driver (UMDF V2.0) SpbCx.sys I2C Controller Driver GpioClx.sys GPIO Controller Driver ADXL345Acc Peripheral

1. Setting up your E nvironments Hardware Capabilities on Development Platforms Sharkscove Minnowboard Max Qualcomm Reference Board Raspberry Pi 2 OS Architecture X86 X86, x64 ARM ARM Operating System SKU Supported Desktop, IOT Desktop, IOTMobile, IOT IOTGPIO Capabilities- # available GPIO Lines2 dedicated GPIO, 6 assigned 1.8-4.2V 3 dedicated GPIO @ 3.3VSupported40 PinsI2C Capabilities(# Controllers; Max Speed) 5 shared controllers100Kbps - 3.4Mb/s @1.8V2Mb/s @3.3 VSupportedSupported(Bitbang )SPI Capabilities(# Controllers; Max Speed)N/A 2 controllers15Mb/s @ 3.3V SupportedSupported(low speed bitbang)UART Capabilities- Max BAUD Rates2 controllers, 1 header3,686,400 2 controllers 3,686,400 @ 3.3VSupportedSupported (1Mbps)

2 . Adapt the Driver to Hardware Goal Build a driver from a sample and adapt it to your specific hardware Key Tasks to perform Set up your Device Object / hardware Configure the device from driver Start the device activity Stop the device activity (standby) Disconnect hardware resources Resource Lists List of hardware resources the driver should use to communicate with the deviceIO TargetWDF object used to send IO requests to another driver Device Power States (D0 – D3)D0 is powered. D1 – D3 are sleep statesIRQLDPCs & Workitems

Visual Studio – I 2 C Accelerometer Code Sample

3. Install the driver Goal Load the driver on the ADXL345 accelerometer sensor. Required Steps Disable Secure Boot and turn on test signing (Done by WDK) Specify the hardware resources in ACPI Create an INF to match on the declared resource Secure Boot Leverages UEFI specification’s secure boot functionality to help prevent malicious software applications/OS from loading during the system start-up process.Test SigningAllows the driver developer to load test-signed kernel mode code/drivers. AutoACPINew in Windows 10 to enable developers to update ACPI using simple software constructs. Builds on ACPIGen and reduces the tax to developers to learn

3. Install the driver Specifying the hardware r esources in ACPI Device(SPBA)  { Name (_HID, "ADXL0345")   Name(_CRS, ResourceTemplate () { I2CSerialBus(0x53 , ControllerInitiated, 400000, AddressingMode7Bit , "\\_SB.I2C3", 0, ResourceConsumer) GpioInt(Edge, ActiveHigh, Exclusive, PullDown, 0 , "\\_SB.GPO2") {0x17} }) } I2C3, Address 0x53, 400kHz Hardware ID: “ADXL0345”. ACPI.sys will use this information GPIO2, Edge interrupt on #17

3. Install the driver ACPI Generation Framework (ACPIGenFx) Step 4: Add a GPIO interrupt line Pin 1 on GPIO controller 2 Active high, level triggered interrupt Enable pull-down resistors for line No debouncing var platform = Platforms .Createx86Platform( "PWIE" , "EDK2" , "PWIE", 1, "SSDT");var sensor = platform.AddGenericDevice( "ADXL", @"ADXL0345" , 1);sensor.AddI2CSerialBus( SlaveAddress: 0x53, Mode: SlaveMode .ControllerInitiated, ConnectionSpeed: 400 * 1000, addressmode: AddressMode._7Bit, controllername: @"\_SB_. I2C3"); sensor.AddGPIOInterrupt( Type: InterruptType.Level, ActiveLevel: InterruptActiveLevel.ActiveHigh, Shared: SharingLevel .Exclusive, PinConfiguration: PinConfiguration.Down, DebounceTimeout: 0, PinNumber: 1, Source: @"\_SB_. GPO2");platform.WriteAsl(); Step 2 : Add device’s HWID Step 3: Add an I2C serial bus resource address 0x53 on I2C controller 3 400 KHz clock Step 1: Start with an x86 default platform Step 5: Write the source code for the ACPI table New in Win10

C# library used to generate ACPI firmware tables for HW-reduced SoC-based platforms. Advantages: Software developer friendly – Devices, resources, and dependencies are descried as C# objects . Visual Studio’s Intellisense to make it easier to code. Framework is aware of Windows specific requirements. Catches errors at build time via static analysis of the platform. Samples and templates available to get started quickly. 3. Install the driver Value proposition of ACPI Generation Framework ASL is difficult to debug, but with ACPIGenFx developers will experience fewer bugs at runtime.

3. Install the driver Create an INF to match on the declared resources [Version] Signature = "$Windows NT$" Class = Sensor ClassGuid= {5175D334-C371-4806-B3BA-71FD53C9258D} Provider=%ManufacturerName% CatalogFile=ADXL345Acc.cat DriverVer= [Manufacturer] %ManufacturerName%=Standard,NT$ARCH$ [Standard.NT$ARCH$] %DeviceName%=MyDevice_Install, ACPI\ADXL0345… [Strings] ManufacturerName="Me" DeviceName="ADXL345Acc Device" Step1: Set Device Setup Class for embedded device.

3. Install the driver Create an INF to match on the declared resources [Version] Signature = "$Windows NT$" Class = Sensor ClassGuid= {5175D334-C371-4806-B3BA-71FD53C9258D} Provider=%ManufacturerName% CatalogFile=ADXL345Acc.cat DriverVer= [Manufacturer] %ManufacturerName%=Standard,NT$ARCH$ [Standard.NT$ARCH$] %DeviceName%=MyDevice_Install, ACPI\ADXL0345 … [Strings] ManufacturerName="Me" DeviceName="ADXL345Acc Device" Step 2: Set Hardware ID Must match value from ACPI table entry

3. Install the driver Create an INF to match on the declared resources [Version] Signature = "$Windows NT$" Class = Sensor ClassGuid= {5175D334-C371-4806-B3BA-71FD53C9258D} Provider=%ManufacturerName% CatalogFile=ADXL345Acc.cat DriverVer= [Manufacturer] %ManufacturerName%=Standard,NT$ARCH$ [Standard.NT$ARCH$] %DeviceName%=MyDevice_Install, ACPI\ADXL0345 … [Strings] ManufacturerName="Me" DeviceName="ADXL345Acc Device" Step 3: Set manufacturer & device name

Recap of What we Learnt So far, we successfully did the following: Select and setup the development environment Adapted the driver to your d evice Install the driver (via Plug&Play) Validate using the tools provided

Best Practices and Tips to Avoid Common Errors

Samples and Tools To Get Started Start with a pertinent MSDN samples GPIO: SimDevice – a sample driver that consumes GPIO interrupt and IO resources SPB: SpbTestTool driver and app for I 2 C, SPI; SpbAccelerometer sample sensor driver on I 2CUART: UART controller driver for PCs; Bluetooth UART bus driver sampleValidate with these test toolsSpbTestTool driver and app for I2C, SPI – validates the resources are defined properly in ACPIMITT and HLK (controller testing only)

SpbTestTool Windows Sample Driver enabling the following developer scenarios: Opens a handle to the SPB controller , use the SPB interface from a KMDF driver, and employ GPIO passive-level interrupts . It implements a set of commands for communicating with a peripheral device to aid in debugging. References: https://code.msdn.microsoft.com/windowshardware/SpbTestTool-adda6d71#content Tips and TricksDevice you intend to load SpbTestTool driver on must be defined in ACPI (e.g ACPI\HWID1234).See spbtesttool.asl in the source code for a complete example.

Windows Apps and Low Power Buses Provide Windows Apps access to low level I 2 C, SPI and GPIO devices for IOT scenarios and diagnosability. WinRT APIs in the Windows.Devices namespace that provide easy access to these devices to Windows Apps . Available first on Windows “Athens” (IoT) OS editions and then on other editions too.

WinRT APIs Details Windows.Devices .[GPIO|SPI|I 2 C] APIs follow existing “ Windows.Devices ” API patterns and give direct access to these busses either in shared or exclusive access mode Samples available identifying the common use-cases.                 // Blink the LED 10 times.                 for (int i = 0; i < 10; ++i)                 {                     pin.Write(GpioPinValue.Low);                     await Task.Delay(200);                     pin.Write(GpioPinValue.High);                     await Task.Delay(200);                 }

Hardware Lab Kit Content Device Testing – IHVs No LPB specific assessments needed. Each Device Class has its own requirements and associated assessments in HLK to exercise the code Controller testing – OEMs Primarily targeted for SOC silicon Vendors OEMs can optionally run the tests but need open chassis systemsTips and Tricks for OEMsHLK version targeted at SoC Vendors QA team. Simpler UI and streamlined MSDN provides headless versions (no UI / command line).Richer command line options Tests can be run individuallyNo need for HLK server

Multiple Interface Test Tool (MITT) Microsoft developed test tool for validating Hardware/Software Supported buses : I 2 C, GPIO, UART , SPI . Firmware and software provided by Microsoft Framework for additional development by the hardware developer available.Available at Diligent and JJG TechnologiesReferences: https://msdn.microsoft.com/en-us/library/windows/hardware/dn919874%28v=vs.85%29.aspx I 2C SPI New in Win10 GPIO

Troubleshooting INF Errors Topic: Driver not loading correctly on hardware Design SetupAPI logs information about device installation. Use it to verify or troubleshoot device installation Filename: SetupAPI.dev.log (in %SystemRoot%\inf)References:https://msdn.microsoft.com/en-us/library/windows/hardware/ff547657(v=vs.85).aspx

Troubleshooting I2C Removable Devices ACPI tables must identify devices that may be “attached” in future. Device present at boot? Set _STA == 0x0F; else Set _STA == 0x00 Device removed/connected after boot: the platform triggers a Platform Event (GPIO interrupt or GPE Event). The handler (_ Lxx /_ Exx /_EVT) must: Change accordingly the value of _STA for each device that arrived/disappeared Signal the OS that a BUS CHECK event has occurred using the Notify() operator. Send the notification to the lowest parent of ALL CHANGED DEVICES in the table. ACPI will re-enumerate devices below the notified device (e.g. ALS ,), removing or adding Windows device nodes as appropriate.Windows will load drivers, or ADD_DEVICE to already loaded drivers.

Troubleshooting WPP Tracing Topic: How to debug loading and runtime errors in your driver Design Trace GUID (in SensorsTrace.h) Sensor device unique GUID (in device.cpp ) Traceview : configures and controls trace sessions and displays formatted trace messages from real-time trace sessions

Demo : Debugging an issue in the SPB Peripheral Driver Code 10 , why?

Demo Script Load Accelerometer driver in VS14 Show the device registers in the .h files and sending the custom I 2 C commands during device initialization Show how to add IHV side errors ETW logging Throw a programmatic error Load the dump in VS (pre-recorded) Show the associated tracing

Common Errors & Best Practices HID I 2 C Specific Errors : Hid I 2 C Class driver Code 10 –Errors in HID or Report Descriptor. Hid I 2 C Class driver Code 28 –Device failed the Set_power HID I 2C command.Turn on ETW/WPP Tracing in HIDI2C to debug specifics issues.Best Practices for LPB drivers:Test your peripheral on a development board first.LPB Peripherals drivers should start with UMDF (ensure that Major Version is 2). Try to have dedicated GPIO line for peripheral reset. This helps “hard reset” a stuck device.

Call to action Get a jump-start on writing LPB peripheral drivers Visit the sensors talk and lab at WinHEC to practice what you learned today. Attend the sensors booth to review our custom sensors demo Review our samples and documentation on MSDN. Send us feedback / questions Run HLK and validation tools

More information MSDN references GPIO - https://msdn.microsoft.com/en-us/library/windows/hardware/hh439509(v=vs.85). aspx SPB - https://msdn.microsoft.com/en-us/library/windows/hardware/hh450906(v=vs.85). aspx UART - https://msdn.microsoft.com/en-us/library/windows/hardware/ff547453(v=vs.85).aspx Spb cookbook - https://msdn.microsoft.com/en-us/library/windows/hardware/dn760712(v=vs.85).aspx MITT - https://msdn.microsoft.com/en-us/library/windows/hardware/dn919874%28v=vs.85%29.aspxWPP Tracing - https://msdn.microsoft.com/en-us/library/windows/hardware/ff547657(v=vs.85).aspx Support AliasesDeveloper support alias for Low Power Buses: SimpleBus @ microsoft.com Questions on MITT or HLK tools: MITTSupport @ microsoft.com

Grand Ballroom III Mansion VIII 12:30 Introduction to Hardware Lifecycle 13:40 Tools for Windows Driver Development 15:00 Intro to Windows Driver Development 16:10 Writing Drivers with the WDF <Day 2> 10:30 Lab: Getting Started with Driver Dev 11:30 Lunch Lunch 12:30 Accessing GPIO, I2C, and UART devices Lab: Driver Testing and Debugging 13:40 Driver Testing and Debugging Lab: Sensor Driver on Sharks Cove 15:00 Testing with the Hardware Lab Kit Lab: Sensor Driver on Sharks Cove 16:10 Intro to Driver Signing, Distribution, Servicing Lab: Testing with the Hardware Lab Kit 17:20 Lab: Testing with the Hardware Lab Kit <Day 3> 09:00 Lab: Getting Started with Driver Dev 10:10 Lab: Driver Testing and Debugging

请对本会议进行评价 您的反馈对我们至关重要 ! Please Complete an Evaluation. Your input is important! 请通过以下链接访问评价表 : Access Evaluation Forms: 加入 Windows 硬件社区 扫一扫，通过 微信 关注 WinHEC

(c) 2015 Microsoft Corporation.  All rights reserved.  This document is provided "as-is." Information and views expressed in this document, including URL and other Internet Web site references, may change without notice. You bear the risk of using it.  This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.   Some information relates to pre-released product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Appendix

ISSUE: HIDI2C driver is not loaded in Device Manager for the DEVICE (I2C Peripheral), but I2C Controller driver is loaded REASON: I nvalid ASL Code for HOST or DEVICE. Errors in ASL manifest as: The HIDI2C driver will not load (INF match failed - see setupapi.dev.log) The HIDI2C driver will load with Error Code 10 . (More details to follow). OEM must ensure highlighted items are valid _HID (Vendor specific) and _CID ( fixed to “ PNP0C50 ”)I2C Controller and Device characteristics are accurateHID Descriptor Address is correctly Identified for that specific DEVICEPlease pay special attention to the followingGPIO Interrupt is correctly identified and marked as Exclusive, Level, ActiveLowTop 3 Most Common Errors for HID I2C: Driver Does Not LoadPlease refer to Section 13 (Example Section) in the HID over I2C Specification for more details

ISSUE: HIDI2C driver is Error Code 10 in Device Manager REASON: If the DEVICE has an invalid HID Descriptor, the HIDI2C driver loads with Error Code 10 . Did the HOST retrieve correct HID Descriptor from DEVICE. If not, focus on the following Validate HID Descriptor Address entry in ASL. Observe I2C traffic to DEVICE to see if HOST is requesting correctly. Did the HOST retrieve correct response to Reset (HIR) from the DEVICE. If not, focus on the following Validate entries in Byte Offset 16 and 18 of HID Descriptor Validate the DEVICE responded correctly to HIR request (asserted GPIO Interrupt + 0x00 0x00 in Input Register)<Continued on next page> Byte OffsetFieldVALUE (HEX)Notes 0wHIDDescLength 00 18 Fixed 2bcdVersion 01 00Fixed4 wReportDescLengthTBD Device IHV must set correctly 6 wReportDescRegisterTBD Device IHV must set correctly8 wInputRegisterTBD Device IHV must set correctly10 wMaxInputLength TBD Device IHV must set correctly 12wOutputRegister TBDDevice IHV must set correctly 14wMaxOutputLength TBD Device IHV must set correctly 16wCommandRegister TBDDevice IHV must set correctly 18 wDataRegisterTBD Device IHV must set correctly20 RESERVED00 00 00 00Fixed Top 3 Most Common Errors for HID I2C: Driver comes up “Code 10”

Did the HOST retrieve correct Report Descriptor from DEVICE and did HIDPARSE succeed in parsing the Report Descriptor. If not, focus on the following If Report Descriptor is NOT retrieved from the DEVICE, Ensure enumeration sequence has passed all steps before Report Descriptor retrieval. Ensure Byte Offset 4 and 6 in HID Descriptor are valid and correct ( especially length).If the Report Descriptor is retrieved from the DEVICE but still failsValidate the wReportDescLength field to ensure that the entire Report Descriptor was retrieved.Validate HID Report is correctly formatted based on the device class driver specifications. Test on an alternative bus like USB to validate conformance.Top 3 Most Common Errors for HID I2C: Driver Comes up “Code 10” SAMPLE ACCELEROMETER REPORT DESCRIPTOR ====================================== USAGE_PAGE (Sensors) 05 15USAGE (Motion: Accelerometer 3D) 09 73 COLLECTION (Physical) A1 00 //<FEATURES> USAGE (Property: Connection Type) 0A 09 03 LOGICAL_MINIMUM (0) 15 00 LOGICAL_MAXIMUM (255) 26 FF 00 REPORT_SIZE (16) 75 10 REPORT_COUNT (1) 95 01 FEATURE ( Data,Var,Abs) B1 02 … …//Shake Event Notification USAGE (Data: Motion Intensity) 0A 51 04 LOGICAL_MINIMUM (0) 15 00 LOGICAL_MAXIMUM (64) 25 40 REPORT_SIZE (8) 75 08 INPUT (Data,Var,Abs ) 81 02 //</INPUT>END_COLLECTION C0

ISSUE: HIDI2C driver is not receiving any input reports when device has data REASON: Please review the following in order Incorrect values in Byte Offset 8 and 10 of HID Descriptor. GPIO line not being asserted by the DEVICE or being acknowledged by the HOST driver. The Input Report is malformed (doesn’t conform to the Report Descriptor) and is being discarded by the operating system’s HID Parser The Input Report is not is accordance with the requirements of the class driver for that HID device class and hence is not being utilized. Top 3 Most Common Errors for HID I2C: No Input Reports

Please Complete an Evaluation. Your input is important! Access Evaluation Forms:

(c) 2015 Microsoft Corporation.  All rights reserved.  This document is provided "as-is." Information and views expressed in this document, including URL and other Internet Web site references, may change without notice. You bear the risk of using it.  This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.   Some information relates to pre-released product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.