diff options
| author | Dipannita Shaw <[email protected]> | 2021-04-27 14:26:21 -0700 |
|---|---|---|
| committer | Dipannita Shaw <[email protected]> | 2021-04-27 14:26:21 -0700 |
| commit | 78a1795995814a0bac43042f7ca68e83ab525bd5 (patch) | |
| tree | 8e2eb0e8c3a11220f2f119964c6c6e3674eda0da /usb | |
| parent | 465e27457dd3b47cf64e4b7274705cc6acc011a6 (diff) | |
| parent | 672fafbcc455cd97172b2df78040c7c405e32d00 (diff) | |
Merge remote-tracking branch 'upstream/master'
Diffstat (limited to 'usb')
27 files changed, 777 insertions, 742 deletions
diff --git a/usb/UcmCxUcsi/Acpi.cpp b/usb/UcmCxUcsi/Acpi.cpp index ed90260d..33dec487 100644 --- a/usb/UcmCxUcsi/Acpi.cpp +++ b/usb/UcmCxUcsi/Acpi.cpp @@ -554,9 +554,9 @@ Acpi_EvaluateUcsiDsm ( FIELD_OFFSET(ACPI_EVAL_OUTPUT_BUFFER, Argument) + outputArgumentBufferSize; - outputBuffer = (PACPI_EVAL_OUTPUT_BUFFER) ExAllocatePoolWithTag(NonPagedPoolNx, - outputBufferSize, - TAG_UCSI); + outputBuffer = (PACPI_EVAL_OUTPUT_BUFFER) ExAllocatePool2(POOL_FLAG_NON_PAGED, + outputBufferSize, + TAG_UCSI); if (outputBuffer == nullptr) { @@ -565,8 +565,6 @@ Acpi_EvaluateUcsiDsm ( goto Exit; } - RtlZeroMemory(outputBuffer, outputBufferSize); - WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&inputMemDesc, inputMemory, NULL); WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&outputMemDesc, outputBuffer, (ULONG) outputBufferSize); diff --git a/usb/UcmCxUcsi/README.md b/usb/UcmCxUcsi/README.md index 9d7cc638..9def204e 100644 --- a/usb/UcmCxUcsi/README.md +++ b/usb/UcmCxUcsi/README.md @@ -5,35 +5,30 @@ languages: - cpp products: - windows +- windows-wdk urlFragment: ucmtcpcicx-port-controller-client-driver-v2 --- -<!--- - name: UcmTcpciCx Port Controller Client Driver - platform: KMDF - language: cpp - category: USB - description: Demonstrates how to create a Windows USB Type-C port controller driver using the USB Connector Manager class extension driver (UcmCx). - samplefwlink: https://go.microsoft.com/fwlink/p/?linkid=856744 ----> +# UcmCxUcsi Port Controller Client Driver -# UcmTcpciCx Port Controller Client Driver - -This is a sample driver that shows how to create a Windows USB Type-C port controller driver using the USB Connector Manager class extension driver (UcmCx). The sample is a driver for an embedded controller which is complient with the [USB Type-C Connector System Software Interface (UCSI)](http://www.intel.com/content/www/us/en/io/universal-serial-bus/usb-type-c-ucsi-spec.html). +This is a sample driver that shows how to create a Windows USB Type-C port controller driver using the USB Connector Manager class extension driver (UcmCx). The sample is a driver for an embedded controller which is compliant with the [USB Type-C Connector System Software Interface (UCSI)](https://www.intel.com/content/www/us/en/io/universal-serial-bus/usb-type-c-ucsi-spec.html). ## Background reading - UcmCx documentation -Start at the UcmCx documentation at [USB Type-C connector driver programming reference](https://msdn.microsoft.com/en-us/library/windows/hardware/mt188011(v=vs.85).aspx). +Start at the UcmCx documentation at [USB Type-C connector driver programming reference](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/_usbref/#type-c-driver-reference). ## Note on UCSI -Microsoft already provides an inbox UCSI driver, UcmUcsi.sys. This UcmCxUcsi sample driver is not identical to the inbox UCSI driver. Microsoft recommends that you use the inbox UcmUcsi.sys for your UCSI-compliant system rather than writing your own. This sample driver is meant for developers bringing up a UcmCx driver for their own non-UCSI platforms. For more information about the UCSI driver, reference [USB Type-C Connector System Software Interface (UCSI) driver](https://msdn.microsoft.com/en-us/library/windows/hardware/mt710944(v=vs.85).aspx). +Microsoft already provides an inbox UCSI driver, UcmUcsi.sys. This UcmCxUcsi sample driver is not identical to the inbox UCSI driver. Microsoft recommends that you use the inbox UcmUcsi.sys for your UCSI-compliant system rather than writing your own. This sample driver is meant for developers bringing up a UcmCx driver for their own non-UCSI platforms. For more information about the UCSI driver, reference [USB Type-C Connector System Software Interface (UCSI) driver](https://docs.microsoft.com/windows-hardware/drivers/usbcon/ucsi). This sample demonstrates the following: - Registration with the USB Connector Manager (UCM) class extension driver. + - Initializing the port controller's Type-C and Power Delivery capabilities. + - Performing data and power role swaps requested by UCM + - Notifying UCM of Type-C and Power Delivery events on the connector. ## Customizing the sample for your port controller @@ -49,10 +44,15 @@ In this sample, UCM-specific interactions are split apart from most of the UCSI- The following files contain methods that interface with UcmCx. - UcmCallbacks.cpp - - Contains the implementations [EVT_UCM_CONNECTOR_SET_DATA_ROLE](https://msdn.microsoft.com/en-us/library/windows/hardware/mt187818(v=vs.85).aspx) and [EVT_UCM_CONNECTOR_SET_POWER_ROLE](https://msdn.microsoft.com/en-us/library/windows/hardware/mt187818(v=vs.85).aspx). These are callbacks from UCM which ask the client driver to perform role swaps. + + - Contains the implementations [EVT_UCM_CONNECTOR_SET_DATA_ROLE](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/ucmmanager/nc-ucmmanager-evt_ucm_connector_set_data_role) and [EVT_UCM_CONNECTOR_SET_POWER_ROLE](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/ucmmanager/nc-ucmmanager-evt_ucm_connector_set_power_role). These are callbacks from UCM which ask the client driver to perform role swaps. + - UcmNotifications.cpp - - Contains methods that communicate with UcmCx using the client driver support methods described in the [USB Type-C connector driver programming reference](https://msdn.microsoft.com/en-us/library/windows/hardware/mt188011(v=vs.85).aspx). + + - Contains methods that communicate with UcmCx using the client driver support methods described in the [USB Type-C connector driver programming reference](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/_usbref/#type-c-driver-reference). + - Fdo.cpp + - FDO callbacks, functions, and types, most of which do not interface with UCM. However, the method `Fdo_EvtDeviceSelfManagedIoInit` contains the code segment which initializes the device with UCM. ### UCSI and WDF Interactions @@ -60,12 +60,17 @@ The following files contain methods that interface with UcmCx. The remainder of the files perform operations for UCSI and WDF, non-specific to UCM. - Acpi.cpp + - ACPI method evaluation helper routines. + - Driver.cpp + - Entry point to the driver. Initializes the driver with WDF. + - Ppm.cpp + - Type-C Platform Policy Manager. Main interface to talk to the UCSI-compliant hardware. ## When to write a UcmCx client driver -UcmCx is intended for system port controller drivers. If you are bringing up a USB Type-C peripheral, you do not need to write a USB Type-C specific driver; a regular USB client driver will suffice. Refer to [Developing Windows client drivers for USB devices](https://msdn.microsoft.com/en-us/library/windows/hardware/hh406260(v=vs.85).aspx) to determine what type of driver, if any, you need to write to make your USB device work with Windows. You may look at [Do I need to write a driver for my USB Type-C hardware?](https://blogs.msdn.microsoft.com/usbcoreblog/2016/06/20/do-i-need-to-write-a-driver-for-my-usb-type-c-hardware/) for a more detailed overview.
\ No newline at end of file +UcmCx is intended for system port controller drivers. If you are bringing up a USB Type-C peripheral, you do not need to write a USB Type-C specific driver; a regular USB client driver will suffice. Refer to [Developing Windows client drivers for USB devices](https://docs.microsoft.com/windows-hardware/drivers/usbcon/usb-driver-development-guide) to determine what type of driver, if any, you need to write to make your USB device work with Windows. You may look at [Do I need to write a driver for my USB Type-C hardware?](https://techcommunity.microsoft.com/t5/Microsoft-USB-Blog/Do-I-need-to-write-a-driver-for-my-USB-Type-C-hardware/ba-p/270876) for a more detailed overview. diff --git a/usb/UcmCxUcsi/UcmCxUcsi.vcxproj b/usb/UcmCxUcsi/UcmCxUcsi.vcxproj index c7371dd5..5245ee5d 100644 --- a/usb/UcmCxUcsi/UcmCxUcsi.vcxproj +++ b/usb/UcmCxUcsi/UcmCxUcsi.vcxproj @@ -90,13 +90,12 @@ <ItemDefinitionGroup> <ClCompile> <PrecompiledHeaderFile>pch.h</PrecompiledHeaderFile> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);.</AdditionalIncludeDirectories> <WppEnabled>true</WppEnabled> <WppRecorderEnabled>true</WppRecorderEnabled> <WppScanConfigurationData>trace.h</WppScanConfigurationData> <WppAlternateConfigurationFile> </WppAlternateConfigurationFile> - <WppAdditionalOptions>-scan:"$(UCM_INC_PATH)\$(UCM_VER_PATH)\UcmTraceEnums.h" -scan:"$(KMDF_INC_PATH)\$(KMDF_VER_PATH)\wdftraceenums.h" %(WppAdditionalOptions)</WppAdditionalOptions> + <WppAdditionalOptions>-scan:"$(UCM_INC_PATH)\$(UCM_VER_PATH)\UcmTraceEnums.h" -scan:"$(KMDF_INC_PATH_L)\$(KMDF_VER_PATH)\wdftraceenums.h" %(WppAdditionalOptions)</WppAdditionalOptions> </ClCompile> <DriverSign> <FileDigestAlgorithm>sha256</FileDigestAlgorithm> diff --git a/usb/UcmTcpciCxClientSample/README.md b/usb/UcmTcpciCxClientSample/README.md index 8856e77f..6b0b602a 100644 --- a/usb/UcmTcpciCxClientSample/README.md +++ b/usb/UcmTcpciCxClientSample/README.md @@ -5,31 +5,30 @@ languages: - cpp products: - windows +- windows-wdk --- -<!--- - name: UcmTcpciCx Port Controller Client Driver - platform: KMDF - language: cpp - category: USB - description: Demonstrates how to create a Windows USB Type-C port controller driver using the USB Connector Manager Type-C Port Controller Interface class extension driver (UcmTcpciCx). - samplefwlink: https://go.microsoft.com/fwlink/p/?linkid=856745 ----> - # UcmTcpciCx Port Controller Client Driver -This is a skeleton sample driver that shows how to create a Windows USB Type-C port controller driver using the USB Connector Manager Type-C Port Controller Interface class extension driver (UcmTcpciCx). UcmTcpciCx is currently only availble using the Windows Insider program - documentation for UcmTcpciCx will be available at the next release of Windows. +This is a skeleton sample driver that shows how to create a Windows USB Type-C port controller driver using the USB Connector Manager Type-C Port Controller Interface class extension driver (UcmTcpciCx). UcmTcpciCx is currently only available using the Windows Insider program - documentation for UcmTcpciCx will be available at the next release of Windows. This sample demonstrates the following: -- Registration with the UcmTcpci class extension driver (UcmTcpciCx). -- Initializing the port controller's Type-C and Power Delivery capabilities. -- Initializing the I2C communications channel to the port controller hardware. -- Performing reads/writes over I2C. -- Handling hardware requests from UcmTcpciCx. -- Handling alerts from the port controller hardware and notifying UcmTcpciCx of the alert. -- Power management. -- Platform-level device reset in the case of an unresponsive I2C controller. +- Registration with the UcmTcpci class extension driver (UcmTcpciCx) + +- Initializing the port controller's Type-C and Power Delivery capabilities + +- Initializing the I2C communications channel to the port controller hardware + +- Performing reads/writes over I2C + +- Handling hardware requests from UcmTcpciCx + +- Handling alerts from the port controller hardware and notifying UcmTcpciCx of the alert + +- Power management + +- Platform-level device reset in the case of an unresponsive I2C controller ## Customizing the sample for your port controller @@ -37,7 +36,7 @@ The sample contains a number of comments prefaced with `// TODO` - review them a ## Note regarding Type-C port controller hardware -This sample assumes a device that complies with the USB Type-C Port Controller Interface specification, Revision 1.0 (part of the [USB 3.1 specification download](http://usb.org/developers/docs)). Such a device uses a predefined register layout and an I2C communications channel. +This sample assumes a device that complies with the USB Type-C Port Controller Interface specification, Revision 1.0 (part of the [USB 3.1 specification download](https://usb.org/documents)). Such a device uses a predefined register layout and an I2C communications channel. If your port controller hardware is not exactly compliant with the specification, you will need to make additional modifications to the sample. ## Performing read/writes over I2C @@ -47,7 +46,7 @@ If your port controller hardware is not compliant with the specification and doe ## When to write a UcmTcpciCx client driver -UcmTcpciCx is intended for system port controller drivers. If you are bringing up a USB Type-C peripheral, you do not need to write a USB Type-C specific driver; a regular USB client driver will suffice. Refer to [Developing Windows client drivers for USB devices](https://msdn.microsoft.com/en-us/library/windows/hardware/hh406260(v=vs.85).aspx) to determine what type of driver, if any, you need to write to make your USB device work with Windows. +UcmTcpciCx is intended for system port controller drivers. If you are bringing up a USB Type-C peripheral, you do not need to write a USB Type-C specific driver; a regular USB client driver will suffice. Refer to [Developing Windows client drivers for USB devices](https://docs.microsoft.com/windows-hardware/drivers/usbcon/usb-driver-development-guide) to determine what type of driver, if any, you need to write to make your USB device work with Windows. ## Testing Your Type-C Port Controller (TCPC) Implementation on Windows 10 with Raspberry Pi @@ -55,49 +54,33 @@ UcmTcpciCx is intended for system port controller drivers. If you are bringing u This section outlines a procedure for installing and testing a TCPCI implementation for Windows 10 on a Raspberry Pi computer running Windows 10 IoT Core. You will need a Raspberry Pi 2 or 3, your TCPC device, a USB-to-Serial converter for debugging, and 7 jumper wires to connect your TCPC to the Raspberry Pi (3 for the debug board, 4 for the TCPC). -You will also need the Windows 10 IoT Core Insider Preview builds, the IoT tool set and WDK available for download on MSDN, and the UcmTcpciCxClientSample source code. +You will also need the Windows 10 IoT Core Insider Preview builds, the IoT tool set, the [Windows Driver Kit (WDK)](https://docs.microsoft.com/windows-hardware/drivers/download-the-wdk), and the UcmTcpciCxClientSample source code. ### Setup #### Operating System -Download the latest available Windows 10 IoT Core Insider Preview image here: - -<https://www.microsoft.com/en-us/software-download/windowsiot> - -Install on your Raspberry Pi 2 or 3 per the following instructions: - -<https://developer.microsoft.com/en-us/windows/iot/GetStarted> +Download the latest available [Windows 10 IoT Core Insider Preview](https://www.microsoft.com/software-download/windowsiot) and install on your Raspberry Pi 2 or 3 per the instructions at [Windows for Internet of Things](https://developer.microsoft.com/windows/iot). Note, you will only need to complete the first two steps, “1 Get the tools” and “2 Setup your device” to proceed with the TCPC validation described here. #### PowerShell Connection -Connect to your Raspberry Pi via a PowerShell remote session. You will use this connection to setup the debugger and install your TCPCI driver package. - -<https://developer.microsoft.com/en-us/windows/iot/docs/powershell> +Connect to your Raspberry Pi via a [PowerShell](https://docs.microsoft.com/windows/iot-core/connect-your-device/powershell) remote session. You will use this connection to setup the debugger and install your TCPCI driver package. #### Windows Device Portal -Open a connection to the Raspberry Pi via the Windows Device Portal. The portal provides a Device Manager view in which you will be able to inspect your TCPC device, as well as remote shutdown and reboot controls. - -<https://developer.microsoft.com/en-us/windows/iot/docs/deviceportal> +Open a connection to the Raspberry Pi via the Windows [Device Portal](https://docs.microsoft.com/windows/iot-core/manage-your-device/DevicePortal). The portal provides a Device Manager view in which you will be able to inspect your TCPC device, as well as remote shutdown and reboot controls. #### Kernel Debugger -Setup the kernel debugger for your Raspberry Pi according to the instructions at the following location: - -<https://developer.microsoft.com/en-us/windows/iot/docs/windbg> +Setup the kernel debugger for your Raspberry Pi according to the instructions at the [Windows Debugger (WinDbg)](https://docs.microsoft.com/windows/iot-core/manage-your-device/windowsdebugger) for IoT. #### Connect TCPC Hardware The following assumes an I2C implementation of your TCPC; if your device uses a different transport, ignore the I2C specific references and connect the transport as appropriate. -First, shutdown and remove power from both the Raspberry Pi and your TCPC hardware. Once both boards are powered down, connect the four pins outlined below. Please refer to the GPIO pinout specification for the version of the Raspberry Pi platform you are using for the specific locations. Pin numbers referenced below are for the Raspberry Pi 2 Model B v1.1. - -<img src="https://az835927.vo.msecnd.net/sites/iot/Resources/images/PinMappings/RP2_Pinout.png" width="447" height="305" /> - -**Figure 1:** Raspberry Pi 2 Model B v1.1 Pinout +First, shutdown and remove power from both the Raspberry Pi and your TCPC hardware. Once both boards are powered down, connect the four pins outlined below. Please refer to the GPIO pinout specification for the version of the Raspberry Pi platform you are using for the specific locations. Connect the following pins between your TCPC and the Raspberry Pi: @@ -123,9 +106,7 @@ Edit the INF to set the device path and strings to desired custom values. Build #### Install Driver Package -Follow the instructions at the link below to create a driver package in the form of a CAB file for your custom UcmTcpciCx client driver: - -<https://developer.microsoft.com/en-us/windows/iot/docs/installpackage> +[Create a driver package for IoT](https://docs.microsoft.com/windows-hardware/manufacture/iot/create-install-package) in the form of a CAB file for your custom UcmTcpciCx client driver. Once you have generated the CAB file, see step 3 for instructions on installing the driver package on your Raspberry Pi via the PowerShell connection established earlier. After the package has been installed and the system has rebooted, there is still one more step to getting your driver to load: updating the ACPI tables to describe the device to the platform. @@ -141,11 +122,9 @@ Open sample.asl provided in the UcmTcpciCxClientSample driver sample and modify On a PC with the Windows 10 WDK installed run the following command on your updated ASL file: -asl.exe sample.asl +`asl.exe sample.asl` -This will produce output file ACPITABL.dat. Copy this file to *C:\\Windows\\System32* on your Raspberry Pi device, and reboot. See the “Verification” section in the following link for more information on merging ACPI updates into an IoT image without a full UEFI build: - -<https://msdn.microsoft.com/en-us/windows/uwp/devices-sensors/enable-usermode-access> +This will produce output file ACPITABL.dat. Copy this file to *C:\\Windows\\System32* on your Raspberry Pi device, and reboot. See the [Verification](https://docs.microsoft.com/windows/uwp/devices-sensors/enable-usermode-access#verification) section in *Enable usermode access to GPIO, I2C, and SPI* for more information on merging ACPI updates into an IoT image without a full UEFI build. Once the Raspberry Pi has rebooted, your driver will load on the newly enumerated ACPI device node. @@ -153,13 +132,9 @@ Once the Raspberry Pi has rebooted, your driver will load on the newly enumerate #### USB Type-C Connection Exerciser -The USB Type-C Connection Exerciser is a tool designed by Microsoft and manufactured by MCCI available for purchase at the link below: - -<http://www.mcci.com/mcci-v5/devtools/exerciser-type-c.html> +The [MCCI Model 3101 Type-C Connection Exerciser](https://www.mcci.com/mcci-v5/devtools/exerciser-type-c.html) is a tool designed by Microsoft and manufactured by MCCI. -The tools and instructions for deploying testing with this device are available for download on MSDN: - -<https://msdn.microsoft.com/en-us/library/windows/hardware/dn376875(v=vs.85).aspx> +The tools and instructions for deploying testing with this device are available at [Testing USB hardware, drivers, and apps in Windows](https://docs.microsoft.com/windows-hardware/drivers/usbcon/usb-driver-testing-guide). Suggested testing with the Connection Exerciser device is randomized connect/disconnect for long periods of time. @@ -167,9 +142,7 @@ Suggested testing with the Connection Exerciser device is randomized connect/dis The sample driver includes standard WDF logging which can be extracted via the kernel debugger with the following debugger command: -```cmd -!wdfkd.wdflogdump <driver name> -d -``` +`!wdfkd.wdflogdump <driver name> -d` Other useful driver traces are available from *UcmTcpciCx* and *UcmCx*. @@ -193,30 +166,14 @@ UcmTcpciCx: 8DEAEA72-4C63-49A4-9B8B-25DA24DAE056 ### Resources -USB Type-C Port Controller Interface Specification (TCPCI), download as part of USB 3.1 Specification: - -<http://www.usb.org/developers/docs/> - -Raspberry Pi - -<https://www.raspberrypi.org/> - -<https://developer.microsoft.com/en-us/windows/iot/Docs/PinMappingsRPi.htm> - -Windows 10 IoT - -<https://www.microsoft.com/en-us/software-download/windowsiot> - -<https://developer.microsoft.com/en-us/windows/iot/> - -Windows Insider Preview WDK +[USB Type-C Port Controller Interface Specification (TCPCI)](https://www.usb.org/documents) (download as part of USB 3.1 Specification) -<https://www.microsoft.com/en-us/software-download/windowsinsiderpreviewWDK> +[Raspberry Pi](https://www.raspberrypi.org) -Microsoft USB Test Tools +[Windows 10 IoT Core Insider Preview](https://www.microsoft.com/software-download/windowsiot) -<https://msdn.microsoft.com/en-us/library/windows/hardware/dn376873(v=vs.85).aspx> +[Windows for Internet of Things](https://developer.microsoft.com/windows/iot) -Tracelog Command Syntax +[Windows Insider Preview WDK](https://www.microsoft.com/software-download/windowsinsiderpreviewWDK) -<https://msdn.microsoft.com/en-us/library/windows/hardware/ff553012(v=vs.85).aspx>
\ No newline at end of file +[Tracelog Command Syntax](https://docs.microsoft.com/windows-hardware/drivers/devtest/tracelog-command-syntax) diff --git a/usb/UcmUcsiAcpiSample/README.md b/usb/UcmUcsiAcpiSample/README.md index 442ccdd8..a3686133 100644 --- a/usb/UcmUcsiAcpiSample/README.md +++ b/usb/UcmUcsiAcpiSample/README.md @@ -5,20 +5,12 @@ languages: - cpp products: - windows +- windows-wdk --- -<!--- - name: UcmUcsiCx Client Driver - platform: KMDF - language: cpp - category: USB - description: Demonstrates how to create a Windows UCSI client UCSI class extension driver (UcmUcsiCx). - samplefwlink: https://github.com/Microsoft/Windows-driver-samples/tree/master/usb/UcmUcsiAcpiSample ----> - # UcmUcsiCx ACPI Client Driver -This is a sample driver that shows how to create a Windows USB Type-C port controller driver using the USB Connector Manager class extension driver (UcmCx). The sample is a driver for an embedded controller which is compliant with the [USB Type-C Connector System Software Interface (UCSI)](http://www.intel.com/content/www/us/en/io/universal-serial-bus/usb-type-c-ucsi-spec.html). +This is a sample driver that shows how to create a Windows USB Type-C port controller driver using the USB Connector Manager class extension driver (UcmCx). The sample is a driver for an embedded controller which is compliant with the [USB Type-C Connector System Software Interface (UCSI)](https://www.intel.com/content/www/us/en/io/universal-serial-bus/usb-type-c-ucsi-spec.html). ## Note on UCM UCSI @@ -27,8 +19,11 @@ Microsoft already provides an inbox UCSI Class extension (UcmUcsiCx.sys) and ACP This sample demonstrates the following: - Preparing connector collection with UcmUcsiCx + - Initializing Platform Policy Manager (or PPM) object with UcmUcsiCx + - Handling IOCTLs from UcmUcsiCx to send or get UCSI block + - Delivering PPM notifications to UcmUcsiCx ## Customizing the sample for your UCSI transport @@ -44,8 +39,11 @@ In this sample, UCMUCSI-specific interactions are split apart from most of the U The following files contain methods that interface with UcmUcsiCx. - Ppm.cpp + - Contains bulk of interactions with UcmUcsiCx. Ppm::CreateAndInitialize which is called in the context of PrepareHardware PnP callback, creates connector collection with UcmUcsiCx by calling DDI UcmUcsiConnectorCollectionCreate and UcmUcsiConnectorCollectionAddConnector. The collection serves as a parameter to initialize PPM object with the class extension when the DDI UcmUcsiPpmCreate is called. Ppm::PpmNotificationCallback function calls DDI on the event of a PPM notification. Ppm::EvtIoDeviceControl contains the logic of handling IOCTLs from UcmUcsiCx. + - Fdo.cpp + - FDO callbacks, functions, and types, most of which do not interface with UcmUcsiCx. However, the method Fdo::CreateAndInitialize calls to UcmUcsiCx DDIs UcmUcsiDeviceInitInitialize and UcmUcsiDeviceInitialize. #### UCSI and WDF Interactions @@ -53,12 +51,17 @@ The following files contain methods that interface with UcmUcsiCx. The remainder of the files perform operations for UCSI and WDF, non-specific to UCM. - Acpi.cpp + - ACPI method evaluation helper routines. + - Driver.cpp + - Entry point to the driver. Initializes the driver with WDF. + - Ppm.cpp + - Type-C Platform Policy Manager. Main interface to talk to the UCSI-compliant hardware (via ACPI transport in this case). ## When to write a UcmUcsiCx client driver -UcmUcsiCx is intended to abstract UCSI protocol from UCSI based driver support. If you have a system that implements PPM logic in an Embedded controller which is connected to the system over a non ACPI transport - e.g. USB, PCI, I2C or UART, it is advised that you write a UcmUcsiCx client driver that implements the necessary transport. Ideally, you would just need to replace Acpi class and implement your way to talk to the PPM. Please note, UcmUcsiCx client is the power policy owner. The class extension does handle S0 idling if you chose to enable it in the client driver.
\ No newline at end of file +UcmUcsiCx is intended to abstract UCSI protocol from UCSI based driver support. If you have a system that implements PPM logic in an Embedded controller which is connected to the system over a non ACPI transport - e.g. USB, PCI, I2C or UART, it is advised that you write a UcmUcsiCx client driver that implements the necessary transport. Ideally, you would just need to replace Acpi class and implement your way to talk to the PPM. Please note, UcmUcsiCx client is the power policy owner. The class extension does handle S0 idling if you chose to enable it in the client driver. diff --git a/usb/UcmUcsiAcpiSample/UcmUcsiAcpiSample/UcmUcsiAcpiSample.vcxproj b/usb/UcmUcsiAcpiSample/UcmUcsiAcpiSample/UcmUcsiAcpiSample.vcxproj index 879dc85b..d08edaa3 100644 --- a/usb/UcmUcsiAcpiSample/UcmUcsiAcpiSample/UcmUcsiAcpiSample.vcxproj +++ b/usb/UcmUcsiAcpiSample/UcmUcsiAcpiSample/UcmUcsiAcpiSample.vcxproj @@ -84,7 +84,7 @@ <ClCompile> <WppEnabled>true</WppEnabled> <PrecompiledHeaderFile>pch.h</PrecompiledHeaderFile> - <DisableSpecificWarnings>4100;4189;%(DisableSpecificWarnings)</DisableSpecificWarnings> + <DisableSpecificWarnings>4100;4189;5208;%(DisableSpecificWarnings)</DisableSpecificWarnings> <SupportJustMyCode>false</SupportJustMyCode> </ClCompile> <Link> @@ -97,7 +97,7 @@ <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'"> <ClCompile> <WppEnabled>true</WppEnabled> - <DisableSpecificWarnings>4100;4189;%(DisableSpecificWarnings)</DisableSpecificWarnings> + <DisableSpecificWarnings>4100;4189;5208;%(DisableSpecificWarnings)</DisableSpecificWarnings> <SupportJustMyCode>false</SupportJustMyCode> </ClCompile> <Link> @@ -110,7 +110,7 @@ <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'"> <ClCompile> <WppEnabled>true</WppEnabled> - <DisableSpecificWarnings>4100;4189;%(DisableSpecificWarnings)</DisableSpecificWarnings> + <DisableSpecificWarnings>4100;4189;5208;%(DisableSpecificWarnings)</DisableSpecificWarnings> </ClCompile> <Link> <AdditionalDependencies>$(DDK_LIB_PATH)\UcmUcsi\1.0\UcmUcsiCxStub.lib;%(AdditionalDependencies)</AdditionalDependencies> @@ -122,7 +122,7 @@ <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|Win32'"> <ClCompile> <WppEnabled>true</WppEnabled> - <DisableSpecificWarnings>4100;4189;%(DisableSpecificWarnings)</DisableSpecificWarnings> + <DisableSpecificWarnings>4100;4189;5208;%(DisableSpecificWarnings)</DisableSpecificWarnings> </ClCompile> <Link> <AdditionalDependencies>$(DDK_LIB_PATH)\UcmUcsi\1.0\UcmUcsiCxStub.lib;%(AdditionalDependencies)</AdditionalDependencies> diff --git a/usb/kmdf_enumswitches/README.md b/usb/kmdf_enumswitches/README.md index f196e2b4..21b460e6 100644 --- a/usb/kmdf_enumswitches/README.md +++ b/usb/kmdf_enumswitches/README.md @@ -5,35 +5,32 @@ languages: - cpp products: - windows +- windows-wdk --- -<!--- - name: Sample KMDF Bus Driver for OSR USB-FX2 - platform: KMDF - language: cpp - category: USB - description: Demonstrates how to use KMDF as a bus driver using the OSR USB-FX2 device. - samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=618000 ----> - # Sample KMDF Bus Driver for OSR USB-FX2 The kmdf\_enumswitches sample demonstrates how to use Kernel-Mode Driver Framework (KMDF) as a bus driver using the OSR USB-FX2 device. -This sample is written for the OSR USB-FX2 Learning Kit. The specification for the device is at <http://www.osronline.com/hardware/OSRFX2_32.pdf>. +This sample is written for the [OSR USB-FX2 Learning Kit](https://www.osronline.com/hardware/OSRFX2_32.pdf). ## Testing the Device To test the device, follow these steps: 1. If you test signed your driver package, you must enable installation of test signed drivers on the target machine. To do so, either press F8 as the target machine comes up from a reboot, or specify **Bcdedit.exe -set TESTSIGNING ON** and reboot. If you use F8, the change only applies until the next reboot. + 1. Plug in the OSR USB-FX-2 Learning Kit (must be version 2.00 or later). + 1. In Device Manager, select **Update Driver Software**, **Browse my computer for driver software**, **Let me pick from a list of device drivers on my computer**, **Have Disk**. Navigate to the directory that contains your driver package and select the INF file. + 1. After the driver installs, verify that the device appears under the **Sample Device** node in Device Manager. + 1. Flip the switches on the OSR USB-FX-2 hardware board and watch the raw PDO entries appear and disappear under **Sample Device** in Device Manager. + 1. Right-click a raw PDO entry, select **Properties**, and then click the **Events** tab. Under **Information**, examine the hardware ID for the PDO. It should be something like this: - **6FDE7521-1B65-48ae-B628-80BE62016026}\OsrUsbFxRawPdo\6&227995e2&0&08** + `6FDE7521-1B65-48ae-B628-80BE62016026}\OsrUsbFxRawPdo\6&227995e2&0&08` The last digit matches the number of the switch that you toggled. @@ -42,20 +39,31 @@ To test the device, follow these steps: Here is the overview of the device: - Device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). + - Contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). + - Firmware supports vendor commands to query or set LED Bar graph display, 7-segment LED display and query toggle switch states. + - Interrupt Endpoint: - Sends an 8-bit value that represents the state of the switches. + - Sent on startup, resume from suspend, and whenever the switch pack setting changes. + - Firmware does not de-bounce the switch pack. + - One switch change can result in multiple bytes being sent. + - Bits are in the reverse order of the labels on the pack For example, bit 0x80 is labeled 1 on the pack - Bulk Endpoints are configured for loopback: + - Device moves data from IN endpoint to OUT endpoint. + - Device does not change the values of the data it receives nor does it internally create any data. + - Endpoints are always double buffered. - - Maximum packet size depends on speed (64 Full speed, 512 High speed).
\ No newline at end of file + + - Maximum packet size depends on speed (64 Full speed, 512 High speed). diff --git a/usb/kmdf_enumswitches/sys/driver.c b/usb/kmdf_enumswitches/sys/driver.c index 275803e6..e9e99054 100644 --- a/usb/kmdf_enumswitches/sys/driver.c +++ b/usb/kmdf_enumswitches/sys/driver.c @@ -107,7 +107,7 @@ Return Value: "OSRUSBFX2 Driver Sample - Driver Framework Edition.\n"); // - // Initiialize driver config to control the attributes that + // Initialize driver config to control the attributes that // are global to the driver. Note that framework by default // provides a driver unload routine. If you create any resources // in the DriverEntry and want to be cleaned in driver unload, diff --git a/usb/kmdf_enumswitches/sys/kmdf_enumswitches.vcxproj b/usb/kmdf_enumswitches/sys/kmdf_enumswitches.vcxproj index 883f548c..f8b0392d 100644 --- a/usb/kmdf_enumswitches/sys/kmdf_enumswitches.vcxproj +++ b/usb/kmdf_enumswitches/sys/kmdf_enumswitches.vcxproj @@ -99,18 +99,18 @@ <ClCompile> <TreatWarningAsError>true</TreatWarningAsError> <WarningLevel>Level4</WarningLevel> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </ClCompile> <Link> <AdditionalDependencies>%(AdditionalDependencies);$(DDK_LIB_PATH)\ntstrsafe.lib;$(DDK_LIB_PATH)\wdmsec.lib</AdditionalDependencies> </Link> <ResourceCompile> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </ResourceCompile> <Midl> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </Midl> <DriverSign> @@ -121,18 +121,18 @@ <ClCompile> <TreatWarningAsError>true</TreatWarningAsError> <WarningLevel>Level4</WarningLevel> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </ClCompile> <Link> <AdditionalDependencies>%(AdditionalDependencies);$(DDK_LIB_PATH)\ntstrsafe.lib;$(DDK_LIB_PATH)\wdmsec.lib</AdditionalDependencies> </Link> <ResourceCompile> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </ResourceCompile> <Midl> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </Midl> <DriverSign> @@ -143,18 +143,18 @@ <ClCompile> <TreatWarningAsError>true</TreatWarningAsError> <WarningLevel>Level4</WarningLevel> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </ClCompile> <Link> <AdditionalDependencies>%(AdditionalDependencies);$(DDK_LIB_PATH)\ntstrsafe.lib;$(DDK_LIB_PATH)\wdmsec.lib</AdditionalDependencies> </Link> <ResourceCompile> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </ResourceCompile> <Midl> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </Midl> <DriverSign> @@ -165,18 +165,18 @@ <ClCompile> <TreatWarningAsError>true</TreatWarningAsError> <WarningLevel>Level4</WarningLevel> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </ClCompile> <Link> <AdditionalDependencies>%(AdditionalDependencies);$(DDK_LIB_PATH)\ntstrsafe.lib;$(DDK_LIB_PATH)\wdmsec.lib</AdditionalDependencies> </Link> <ResourceCompile> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </ResourceCompile> <Midl> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </Midl> <DriverSign> diff --git a/usb/kmdf_fx2/README.md b/usb/kmdf_fx2/README.md index d01e41ee..492cc8cf 100644 --- a/usb/kmdf_fx2/README.md +++ b/usb/kmdf_fx2/README.md @@ -5,109 +5,138 @@ languages: - cpp products: - windows +- windows-wdk --- -<!--- - name: Sample KMDF Function Driver for OSR USB-FX2 - platform: KMDF - language: cpp - category: USB - description: Demonstrates how to use KMDF to perform bulk and interrupt data transfers to a USB device. - samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=620313 ----> - # Sample KMDF Function Driver for OSR USB-FX2 The kmdf\_fx2 sample is a Kernel-Mode Driver Framework (KMDF) driver for the OSR USB-FX2 device. It includes a test app and sample device metadata. -In the Windows Driver Kit (WDK), the osrusbfx2 sample demonstrated how to perform bulk and interrupt data transfers to an USB device. The sample was written for the OSR USB-FX2 Learning Kit. +In the Windows Driver Kit (WDK), the osrusbfx2 sample demonstrates how to perform bulk and interrupt data transfers to an USB device. The sample was written for the [OSR USB-FX2 Learning Kit](https://www.osronline.com/hardware/OSRFX2_32.pdf). -The specification for the device is at <http://www.osronline.com/hardware/OSRFX2_32.pdf>. The driver and sample device metadata also work with the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample. +The driver and sample device metadata also works with the [Custom driver access](https://go.microsoft.com/fwlink/p/?linkid=2114373) sample. ## Universal Windows Driver Compliant This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. -Overview --------- +## Overview Here is the overview of the device: -- The device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). -- It contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). -- Firmware supports vendor commands to query or set LED Bar graph display and 7-segment LED display, and to query toggle switch states. -- Interrupt endpoint: - - Sends an 8-bit value that represents the state of the switches. - - Sent on startup, resume from suspend, and whenever the switch pack setting changes. - - Firmware does not de-bounce the switch pack. - - One switch change can result in multiple bytes being sent. - - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). -- Bulk endpoints are configured for loopback: - - The device moves data from IN endpoint to OUT endpoint. - - The device does not change the values of the data it receives nor does it internally create any data. - - Endpoints are always double buffered. - - Maximum packet size depends on speed (64 full speed, 512 high speed). -- Event Tracing for Windows (ETW) events: - - Included osrusbfx2.man, which describes events added. - - Three events are targeted to the event log: - - Failure during the add device routine. - - Failure to start the OSR device on a USB 1.1 controller. - - Invocation of the "re-enumerate device" IOCTL. - - Read/write start/stop events can be used to measure the time taken. - - For more information, see Unified Tracing later in this document. +- The device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). + +- It contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). + +- Firmware supports vendor commands to query or set LED Bar graph display and 7-segment LED display, and to query toggle switch states. + +- Interrupt endpoint: + + - Sends an 8-bit value that represents the state of the switches. + + - Sent on startup, resume from suspend, and whenever the switch pack setting changes. + + - Firmware does not de-bounce the switch pack. + + - One switch change can result in multiple bytes being sent. + + - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). + +- Bulk endpoints are configured for loopback: + + - The device moves data from IN endpoint to OUT endpoint. + + - The device does not change the values of the data it receives nor does it internally create any data. -Code tour ---------------- + - Endpoints are always double buffered. -**usb\\kmdf\_fx2\\driver** + - Maximum packet size depends on speed (64 full speed, 512 high speed). + +- Event Tracing for Windows (ETW) events: + + - Included osrusbfx2.man, which describes events added. + + - Three events are targeted to the event log: + + - Failure during the add device routine. + + - Failure to start the OSR device on a USB 1.1 controller. + + - Invocation of the "re-enumerate device" IOCTL. + + - Read/write start/stop events can be used to measure the time taken. + + - For more information, see Unified Tracing later in this document. + +## Code tour + +### usb\\kmdf\_fx2\\driver This directory contains driver code that demonstrates the following functionality: -- Loads the driver and responds to PnP and Power events. You can install, uninstall, disable, enable, suspend, and resume the system. -- Creates a context with the WDFDEVICE object. -- Initializes the USB device by registering a *EvtPrepareHardware* callback. -- Marks the interface restricted so that it can be accessed by a privileged UWP device app. -- Creates a default parallel queue to receive an IOCTL request to set bar graph display. -- Retrieves memory handle from the requests and uses it to send a vendor command to the USB device. -- Registers read and write events on the default queue. -- Retrieves memory from read and write requests, formats the requests, and sends it to a USB target. -- Creates two separate sequential queues and configures them to dispatch read and write requests directly. (*\*kmdf\_fx2 only*) -- Enables wait-wake and selective suspend support. (*\*kmdf\_fx2 only*) -- Configures a USB target continuous reader to read toggle switch states asynchronously from the interrupt endpoint. (*\*kmdf\_fx2 only*) -- Supports additional IOCTLs to get and set the 7-segment display and toggle switches, and to reset and re-enumerate the device. (*\*kmdf\_fx2 only*) -- Creates ETW provider to log two events to the event log, and read/write start stop events. (*\*kmdf\_fx2 only*) -- WPP tracing. +- Loads the driver and responds to PnP and Power events. You can install, uninstall, disable, enable, suspend, and resume the system. + +- Creates a context with the WDFDEVICE object. -**usb\\kmdf\_fx2\\exe** +- Initializes the USB device by registering a *EvtPrepareHardware* callback. + +- Marks the interface restricted so that it can be accessed by a privileged UWP device app. + +- Creates a default parallel queue to receive an IOCTL request to set bar graph display. + +- Retrieves memory handle from the requests and uses it to send a vendor command to the USB device. + +- Registers read and write events on the default queue. + +- Retrieves memory from read and write requests, formats the requests, and sends it to a USB target. + +- Creates two separate sequential queues and configures them to dispatch read and write requests directly. (*\*kmdf\_fx2 only*) + +- Enables wait-wake and selective suspend support. (*\*kmdf\_fx2 only*) + +- Configures a USB target continuous reader to read toggle switch states asynchronously from the interrupt endpoint. (*\*kmdf\_fx2 only*) + +- Supports additional IOCTLs to get and set the 7-segment display and toggle switches, and to reset and re-enumerate the device. (*\*kmdf\_fx2 only*) + +- Creates ETW provider to log two events to the event log, and read/write start stop events. (*\*kmdf\_fx2 only*) + +- WPP tracing + +### usb\\kmdf\_fx2\\exe This directory contains a test application that can be used to drive the KMDF driver and FX2 device. -**usb\\kmdf\_fx2\\deviceMetadata** +### usb\\kmdf\_fx2\\deviceMetadata -This directory contains the device metadata package for the sample. You must copy the device metadata to the system before installing the device. For information on how to update and deploy device metadata, see the [Custom driver access sample](http://go.microsoft.com/fwlink/p/?LinkID=248288). +This directory contains the device metadata package for the sample. You must copy the device metadata to the system before installing the device. For information on how to update and deploy device metadata, see the [Custom driver access](https://go.microsoft.com/fwlink/p/?linkid=2114373) sample. -Testing the driver ------------------- +## Testing the driver -You can use the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample as a testing method. +You can use the [Custom driver access](https://go.microsoft.com/fwlink/p/?linkid=2114373) sample as a testing method. The sample also includes a test application, osrusbfx2.exe, that you can use to test the device. This console application enumerates the interface registered by the driver and opens the device to send read, write, or IOCTL requests based on the command line options. Usage for Read/Write test: -- -r [*n*], where *n* is number of bytes to read. -- -w [*n*], where *n* is number of bytes to write. -- -c [*n*], where *n* is number of iterations (default = 1). -- -v, shows verbose read data. -- -p, plays with Bar Display, Dip Switch, 7-Segment Display. -- -a, performs asynchronous I/O operation. -- -u, dumps USB configuration and pipe information. +- -r [*n*], where *n* is number of bytes to read. -**Playing with the 7 segment display, toggle switches, and bar graph display** +- -w [*n*], where *n* is number of bytes to write. + +- -c [*n*], where *n* is number of iterations (default = 1). + +- -v, shows verbose read data. + +- -p, plays with Bar Display, Dip Switch, 7-Segment Display. + +- -a, performs asynchronous I/O operation. + +- -u, dumps USB configuration and pipe information. + +### Playing with the 7 segment display, toggle switches, and bar graph display Use the command, **osrusbfx2.exe -p** options 1-9, to set and clear bar graph display, set and get 7 segment state, and read the toggle switch states. The following shows the function options: -``` +```cmd 1. Light bar 2. Clear bar 3. Light entire bar graph @@ -125,41 +154,41 @@ Use the command, **osrusbfx2.exe -p** options 1-9, to set and clear bar graph di Selection: ``` -**Reset and re-enumerate the device** +### Reset and re-enumerate the device Use the command, osrusbfx2.exe -p with option 10 and 11, to either reset the device or re-enumerate the device. -**Read and write to bulk endpoints** +### Read and write to bulk endpoints The following commands send read and write requests to the device's bulk endpoint. -- `osrusbfx2.exe -r 64` +- `osrusbfx2.exe -r 64` The preceding command reads 64 bytes to the bulk IN endpoint. -- `osrusbfx2.exe -w 64 ` +- `osrusbfx2.exe -w 64` The preceding command writes 64 bytes to the bulk OUT endpoint. -- `osrusbfx2.exe -r 64 -w 64 -c 100 -v` +- `osrusbfx2.exe -r 64 -w 64 -c 100 -v` The preceding command first writes 64 bytes of data to bulk OUT endpoint (Pipe 1), then reads 64 bytes from bulk IN endpoint (Pipe 2), and then compares the read buffer with write buffer to see if they match. If the buffer contents match, it repeats this operation 100 times. -- `osrusbfx2.exe -a` +- `osrusbfx2.exe -a` The preceding command reads and writes to the device asynchronously in an infinite loop. The bulk endpoints are double buffered. Depending on the operational speed (full or high), the buffer size is either 64 bytes or 512 bytes, respectively. A request to read data does not complete if the buffers are empty. If the buffers are full, a request to write data does not complete until the buffers are emptied. When you are doing a synchronous read, make sure the endpoint buffer has data (for example, when you send a 512 bytes write request to the device operating in full speed mode). Because the endpoints are double buffered, the total buffer capacity is 256 bytes. The first 256 bytes fills the buffer, and the write request waits in the USB stack until the buffers are emptied. If you run another instance of the application to read 512 bytes of data, both write and read requests complete successfully. -**Displaying descriptors** +### Displaying descriptors The following command displays all the descriptors and endpoint information. -**osrusbfx2.exe -u** +`osrusbfx2.exe -u` If the device is operating in high speed mode, you will get the following information: -``` +```cmd =================== USB_CONFIGURATION_DESCRIPTOR @@ -230,9 +259,9 @@ bEndpointAddress= 0x6 ( OUTPUT ) bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK ) -wMaxPacketSize= 0x200, +wMaxPacketSize= 0x200, -decimal 512 bInterval = 0x0, +decimal 512 bInterval = 0x0, decimal 0 @@ -272,7 +301,7 @@ iConfiguration = 0x3, decimal 3 bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED ) -MaxPower = 0x32, decimal 50 +MaxPower = 0x32, decimal 50 ----------------------------- @@ -343,8 +372,7 @@ wMaxPacketSize= 0x40, decimal 64 bInterval = 0x0, decimal 0 ``` -Unified tracing ---------------- +## Unified tracing To view events the provider manifest must be installed. As part of the installation, from an elevated prompt run the following: `wevtutil im osrusbfx2.man` @@ -352,34 +380,36 @@ Registering the manifest sets up the appropriate paths where the system can find To trace, you can use the in-box tools, logman and tracerpt, or download XPerf (Windows Performance Toolkit) from Microsoft. -**Using in-box tools** +### Using in-box tools + +#### To start/stop the trace by using logman + +1. Start tracing by using the following command: -**To start/stop the trace by using logman:** + `logman start sample -o osrusbfx2.etl -ets -p OSRUSBFX2` -1. Start tracing by using the following command: +1. Generate activity through the osrusbfx2 test application, such as `osrusbfx2.exe -a`. - `logman start sample -o osrusbfx2.etl -ets -p OSRUSBFX2` +1. Stop tracing by using the following command: -2. Generate activity through the osrusbfx2 test application, such as `osrusbfx2.exe -a`. -3. Stop tracing by using the following command: + `Logman stop sample` - `Logman stop sample` +1. View the trace file using tracerpt: -4. View the trace file using tracerpt: + `tracerpt -of csv OSRUSBFX2.etl` - `tracerpt -of csv OSRUSBFX2.etl ` +#### To start/stop the trace by using Xperf (Windows Performance Toolkit) -**To start/stop the trace by using Xperf (Windows Performance Toolkit):** +1. Start tracing by using the following command: -1. Start tracing by using the following command: + `xperf -start sample -f osrusbfx2.etl -on OSRUSBFX2` - `xperf -start sample -f osrusbfx2.etl -on OSRUSBFX2` +1. Generate activity through the osrusbfx2 test application, such as `osrusbfx2.exe -a`. -2. Generate activity through the osrusbfx2 test application, such as `osrusbfx2.exe -a`. -3. Stop tracing by using the following command: +1. Stop tracing by using the following command: - `xperf -stop sample` + `xperf -stop sample` -4. View the trace file using Xperf: +1. View the trace file using Xperf: - `xperfview OSRUSBFX2.etl` + `xperfview OSRUSBFX2.etl` diff --git a/usb/kmdf_fx2/driver/driver.c b/usb/kmdf_fx2/driver/driver.c index 2c73cab2..25be851e 100644 --- a/usb/kmdf_fx2/driver/driver.c +++ b/usb/kmdf_fx2/driver/driver.c @@ -136,7 +136,7 @@ Return Value: EventRegisterOSRUSBFX2(); // - // Initiialize driver config to control the attributes that + // Initialize driver config to control the attributes that // are global to the driver. Note that framework by default // provides a driver unload routine. If you create any resources // in the DriverEntry and want to be cleaned in driver unload, diff --git a/usb/kmdf_fx2/driver/osrusbfx2.vcxproj b/usb/kmdf_fx2/driver/osrusbfx2.vcxproj index 747de89e..3195fa9e 100644 --- a/usb/kmdf_fx2/driver/osrusbfx2.vcxproj +++ b/usb/kmdf_fx2/driver/osrusbfx2.vcxproj @@ -115,17 +115,17 @@ </PropertyGroup> <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'"> <ResourceCompile> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </ResourceCompile> <ClCompile> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> <WarningLevel>Level4</WarningLevel> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </ClCompile> <Midl> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </Midl> <Link> @@ -137,17 +137,17 @@ </ItemDefinitionGroup> <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'"> <ResourceCompile> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </ResourceCompile> <ClCompile> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> <WarningLevel>Level4</WarningLevel> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </ClCompile> <Midl> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </Midl> <Link> @@ -159,17 +159,17 @@ </ItemDefinitionGroup> <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|Win32'"> <ResourceCompile> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </ResourceCompile> <ClCompile> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> <WarningLevel>Level4</WarningLevel> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </ClCompile> <Midl> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </Midl> <Link> @@ -181,17 +181,17 @@ </ItemDefinitionGroup> <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'"> <ResourceCompile> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </ResourceCompile> <ClCompile> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> <WarningLevel>Level4</WarningLevel> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </ClCompile> <Midl> - <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc;.</AdditionalIncludeDirectories> + <AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);..\inc</AdditionalIncludeDirectories> <PreprocessorDefinitions>%(PreprocessorDefinitions);EVENT_TRACING</PreprocessorDefinitions> </Midl> <Link> diff --git a/usb/ufxclientsample/README.md b/usb/ufxclientsample/README.md index a19fc454..1030135c 100644 --- a/usb/ufxclientsample/README.md +++ b/usb/ufxclientsample/README.md @@ -5,17 +5,9 @@ languages: - cpp products: - windows +- windows-wdk --- -<!--- - name: USB Function Client Driver - platform: KMDF - language: cpp - category: USB - description: Demonstrates how to create a Windows USB function controller driver using the USB function class extension driver (UFX). - samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=620315 ----> - # USB Function Client Driver This is a skeleton sample driver that shows how to create a Windows USB function controller driver using the USB function class extension driver (UFX). @@ -23,10 +15,15 @@ This is a skeleton sample driver that shows how to create a Windows USB function This sample demonstrates the following: - Registration with the UFX class extension driver + - Handling USB transfers + - Handling function controller events + - Handling attach and detach notifications + - Handling charger/port detection + - Power management ## Operating system requirements @@ -39,4 +36,4 @@ This sample is not a functional driver. It is a skeleton driver intended to illu ## Installation Note -Installation on Windows 10 Mobile requires the creation of a package. To properly interact with the USB UI on Windows 10 Mobile, the package must include a Security Element that specifies the ID_CAP_USB capability with DEVICE_READ and DEVICE_WRITE rights.
\ No newline at end of file +Installation on Windows 10 Mobile requires the creation of a package. To properly interact with the USB UI on Windows 10 Mobile, the package must include a Security Element that specifies the ID_CAP_USB capability with DEVICE_READ and DEVICE_WRITE rights. diff --git a/usb/ufxclientsample/device.c b/usb/ufxclientsample/device.c index 3aa46c4c..8a7580bf 100644 --- a/usb/ufxclientsample/device.c +++ b/usb/ufxclientsample/device.c @@ -535,8 +535,8 @@ Arguments: DeviceContext = UfxDeviceGetContext(ControllerContext->UfxDevice); #pragma prefast(suppress:6014, "Memory allocation is expected") - HardwareFailureContext = ExAllocatePoolWithTag( - NonPagedPoolNx, + HardwareFailureContext = ExAllocatePool2( + POOL_FLAG_NON_PAGED, sizeof(HARDWARE_FAILURE_CONTEXT), UFX_CLIENT_TAG); diff --git a/usb/umdf2_fx2/README.md b/usb/umdf2_fx2/README.md index 9868d69e..d93a311a 100644 --- a/usb/umdf2_fx2/README.md +++ b/usb/umdf2_fx2/README.md @@ -5,26 +5,18 @@ languages: - cpp products: - windows +- windows-wdk --- -<!--- - name: Sample Function Driver for OSR USB-FX2 (UMDF Version 2) - platform: UMDF2 - language: cpp - category: USB - description: Demonstrates a UMDF version 2 driver for the OSR USB-FX2 device. - samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=618003 ----> - # Sample Function Driver for OSR USB-FX2 (UMDF Version 2) The umdf2\_fx2 sample is a User-Mode Driver Framework (UMDF) version 2 driver for the OSR USB-FX2 device. -The specification for the device can be found at <http://www.osronline.com/hardware/OSRFX2_32.pdf>. The driver and sample device metadata also work with the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample. + For more information, see the specification for the [OSR USB FX-2 Learning Kit](https://www.osronline.com/hardware/OSRFX2_32.pdf). The driver and sample device metadata also work with the [Custom driver access](https://go.microsoft.com/fwlink/p/?linkid=2114373) sample. ## Related technologies -[User-Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560456) +[User-Mode Driver Framework](https://docs.microsoft.com/windows-hardware/drivers/wdf/getting-started-with-umdf-version-2) ## Run the sample @@ -34,26 +26,31 @@ The process of moving the driver package to the target computer and installing t ### Automatic deployment (FX2 board) -Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). +Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Provision a computer for driver deployment and testing (WDK 10)](https://docs.microsoft.com/windows-hardware/drivers/gettingstarted/provision-a-target-computer-wdk-8-1). 1. Plug in the OSR USB-FX2 board to the target computer. + 1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. + 1. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Install and Verify**. Click **OK**. + 1. On the **Build** menu, choose **Deploy Package** or **Build Solution**. ### Manual deployment (FX2 board) -Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](https://docs.microsoft.com/en-us/windows-hardware/drivers/develop/preparing-a-computer-for-manual-driver-deployment). +Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](https://docs.microsoft.com/windows-hardware/drivers/devtest/devcon) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](https://docs.microsoft.com/windows-hardware/drivers/develop/preparing-a-computer-for-manual-driver-deployment). 1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\umdf2\_fx2). + 1. Plug in the OSR USB-FX2 board to the target computer. Open a Command Prompt window and enter **dvmgmt** to open Device Manager. In Device Manager, locate the node for the OSR USB-FX2 board. Right click the node, and choose **Properties**. In the **Details** tab, under **Properties**, choose **Hardware Ids**. Note the hardware IDs listed for your FX2 board. One of these IDs should match one of the IDs in the osrusbfx2um.inf file. For example, Device Manager might show an ID of USB\\VID\_0547&PID\_1002, which matches one of the IDs in the [Microsoft.*xxx*] section of osrusbfx2um.inf. + 1. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter this command: - **devcon update osrusbfx2um.inf"***HardwareID***"** + `devcon update osrusbfx2um.inf"***HardwareID***"` where *HardwareID* is the hardware ID of your FX2 board. Here is an example: - **devcon update osrusbfx2um.inf "USB\\VID\_0547&PID\_1002"** + `devcon update osrusbfx2um.inf "USB\VID_0547&PID_1002"` ## View the driver for the OSR USB-FX2 board in Device Manager @@ -65,6 +62,6 @@ In Device Manager, on the **View** menu, choose **Devices by connection**. Locat As an alternative to building the driver sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, umdf2echo.sln. Use the MSBuild command to build the solution. Here is an example: - **msbuild /p:configuration=Win8 Release /p:platform=Win32 umdf2\_fx2.sln** +`msbuild /p:configuration=Win8 Release /p:platform=Win32 umdf2_fx2.sln` -For more information about using MSBuild to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644).
\ No newline at end of file +For more information about using MSBuild to build a driver package, see [Building a Driver with Visual Studio and the WDK](https://docs.microsoft.com/windows-hardware/drivers/develop/building-a-driver). diff --git a/usb/umdf2_fx2/driver/driver.c b/usb/umdf2_fx2/driver/driver.c index fb00f9de..7ec5f5df 100644 --- a/usb/umdf2_fx2/driver/driver.c +++ b/usb/umdf2_fx2/driver/driver.c @@ -116,7 +116,7 @@ Return Value: EventRegisterOSRUSBFX2(); // - // Initiialize driver config to control the attributes that + // Initialize driver config to control the attributes that // are global to the driver. Note that framework by default // provides a driver unload routine. If you create any resources // in the DriverEntry and want to be cleaned in driver unload, diff --git a/usb/umdf2_fx2/driver/osrusbfx2um.vcxproj b/usb/umdf2_fx2/driver/osrusbfx2um.vcxproj index a4209763..ac9dc9b7 100644 --- a/usb/umdf2_fx2/driver/osrusbfx2um.vcxproj +++ b/usb/umdf2_fx2/driver/osrusbfx2um.vcxproj @@ -130,6 +130,9 @@ <Link> <AdditionalDependencies>%(AdditionalDependencies);$(SDK_LIB_PATH)\mincore.lib;$(SDK_LIB_PATH)\WppRecorderUM.lib</AdditionalDependencies> </Link> + <DriverSign> + <FileDigestAlgorithm>sha256</FileDigestAlgorithm> + </DriverSign> </ItemDefinitionGroup> <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'"> <ClCompile> @@ -151,6 +154,9 @@ <Link> <AdditionalDependencies>%(AdditionalDependencies);$(SDK_LIB_PATH)\mincore.lib;$(SDK_LIB_PATH)\WppRecorderUM.lib</AdditionalDependencies> </Link> + <DriverSign> + <FileDigestAlgorithm>sha256</FileDigestAlgorithm> + </DriverSign> </ItemDefinitionGroup> <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|Win32'"> <ClCompile> @@ -172,6 +178,9 @@ <Link> <AdditionalDependencies>%(AdditionalDependencies);$(SDK_LIB_PATH)\mincore.lib;$(SDK_LIB_PATH)\WppRecorderUM.lib</AdditionalDependencies> </Link> + <DriverSign> + <FileDigestAlgorithm>sha256</FileDigestAlgorithm> + </DriverSign> </ItemDefinitionGroup> <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'"> <ClCompile> @@ -193,6 +202,9 @@ <Link> <AdditionalDependencies>%(AdditionalDependencies);$(SDK_LIB_PATH)\mincore.lib;$(SDK_LIB_PATH)\WppRecorderUM.lib</AdditionalDependencies> </Link> + <DriverSign> + <FileDigestAlgorithm>sha256</FileDigestAlgorithm> + </DriverSign> </ItemDefinitionGroup> <ItemGroup> <Inf Include="osrusbfx2um.inx" /> @@ -207,4 +219,4 @@ <ClInclude Exclude="@(ClInclude)" Include="*.h;*.hpp;*.hxx;*.hm;*.inl;*.xsd" /> </ItemGroup> <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" /> -</Project> +</Project>
\ No newline at end of file diff --git a/usb/umdf_filter_kmdf/README.md b/usb/umdf_filter_kmdf/README.md index 3ae7dba5..4f7d0e41 100644 --- a/usb/umdf_filter_kmdf/README.md +++ b/usb/umdf_filter_kmdf/README.md @@ -5,59 +5,74 @@ languages: - cpp products: - windows +- windows-wdk --- -<!--- - name: Sample UMDF Filter above KMDF Function Driver for OSR USB-FX2 (UMDF Version 1) - platform: KMDF - language: cpp - category: USB - description: Demonstrates how to load a UMDF filter driver as an upper filter driver above the kmdf_fx2 sample driver. - samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=620316 ----> - # Sample UMDF Filter above KMDF Function Driver for OSR USB-FX2 (UMDF Version 1) The umdf\_filter\_kmdf sample demonstrates how to load a UMDF filter driver as an upper filter driver above the kmdf\_fx2 sample driver. -The sample includes Event Tracing for Windows (ETW) tracing support, and is written for the OSR USB-FX2 Learning Kit. The specification for the device is at <http://www.osronline.com/hardware/OSRFX2_32.pdf>. +The sample includes Event Tracing for Windows (ETW) tracing support, and is written for the [OSR USB-FX2 Learning Kit](https://www.osronline.com/hardware/OSRFX2_32.pdf0. ## Build the sample The default Solution build configuration is **Debug** and **Win32**. 1. Open the driver project or solution in Visual Studio (find *filtername*.sln or *filtername*.vcxproj). + 1. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. + 1. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Debug or Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. + 1. From the **Build** menu, click **Build Solution** (Ctrl+Shift+B). ## Overview - The device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). + - It contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). + - Firmware supports vendor commands to query or set LED Bar graph display and 7-segment LED display, and to query toggle switch states. + - Interrupt Endpoint: -- Sends an 8-bit value that represents the state of the switches. - - Sent on startup, resume from suspend, and whenever the switch pack setting changes. - - Firmware does not de-bounce the switch pack. - - One switch change can result in multiple bytes being sent. - - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). + + - Sends an 8-bit value that represents the state of the switches. + + - Sent on startup, resume from suspend, and whenever the switch pack setting changes. + + - Firmware does not de-bounce the switch pack. + + - One switch change can result in multiple bytes being sent. + + - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). + - Bulk Endpoints are configured for loopback: -- The device moves data from IN endpoint to OUT endpoint. - - The device does not change the values of the data it receives nor does it internally create any data. - - Endpoints are always double buffered. - - Maximum packet size depends on speed (64 full speed, 512 high speed). + + - The device moves data from IN endpoint to OUT endpoint. + + - The device does not change the values of the data it receives nor does it internally create any data. + + - Endpoints are always double buffered. + + - Maximum packet size depends on speed (64 full speed, 512 high speed). + - ETW events: -- Included osrusbfx2.man, which describes events added. - - Three events are targeted to the event log: - - Failure during the add device routine. - - Failure to start the OSR device on a USB 1.1 controller. - - Invocation of the "re-enumerate device" IOCTL. - - Read/write start/stop events can be used to measure the time taken. + + - Included osrusbfx2.man, which describes events added. + + - Three events are targeted to the event log: + + - Failure during the add device routine. + + - Failure to start the OSR device on a USB 1.1 controller. + + - Invocation of the "re-enumerate device" IOCTL. + + - Read/write start/stop events can be used to measure the time taken. ## Testing the driver -You can test this sample either by using the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample application, or by using the osrusbfx2.exe test application. For information on how to build and use the osrusbfx2.exe application, see the test instructions for the [kmdf\_fx2](http://msdn.microsoft.com/en-us/library/windows/hardware/) sample. +You can test this sample either by using the [Custom driver access](https://go.microsoft.com/fwlink/p/?linkid=2114373) sample application, or by using the osrusbfx2.exe test application. For information on how to build and use the osrusbfx2.exe application, see the test instructions for the [kmdf\_fx2](https://docs.microsoft.com/samples/microsoft/windows-driver-samples/sample-kmdf-function-driver-for-osr-usb-fx2/) sample. ## Code tour diff --git a/usb/umdf_filter_kmdf/kmdf_driver/driver.c b/usb/umdf_filter_kmdf/kmdf_driver/driver.c index 2c73cab2..25be851e 100644 --- a/usb/umdf_filter_kmdf/kmdf_driver/driver.c +++ b/usb/umdf_filter_kmdf/kmdf_driver/driver.c @@ -136,7 +136,7 @@ Return Value: EventRegisterOSRUSBFX2(); // - // Initiialize driver config to control the attributes that + // Initialize driver config to control the attributes that // are global to the driver. Note that framework by default // provides a driver unload routine. If you create any resources // in the DriverEntry and want to be cleaned in driver unload, diff --git a/usb/umdf_filter_umdf/README.md b/usb/umdf_filter_umdf/README.md index 5d49b79d..b16d8686 100644 --- a/usb/umdf_filter_umdf/README.md +++ b/usb/umdf_filter_umdf/README.md @@ -5,47 +5,52 @@ languages: - cpp products: - windows +- windows-wdk --- -<!--- - name: Sample UMDF Filter above UMDF Function Driver for OSR USB-FX2 (UMDF Version 1) - platform: UMDF1 - language: cpp - category: USB - description: Demonstrates how to load a UMDF filter driver as an upper filter driver above the umdf_fx2 sample driver. - samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=618001 ----> - # Sample UMDF Filter above UMDF Function Driver for OSR USB-FX2 (UMDF Version 1) The umdf\_filter\_umdf sample demonstrates how to load a User-Mode Driver Framework (UMDF) filter driver as an upper filter driver above the umdf\_fx2 sample driver. -This sample is written for the OSR USB-FX2 Learning Kit. The specification for the device is at <http://www.osronline.com/hardware/OSRFX2_32.pdf>. +This sample is written for the [OSR USB-FX2 Learning Kit](https://www.osronline.com/hardware/OSRFX2_32.pdf). ## Overview - The device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). + - It contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). + - Firmware supports vendor commands to query or set LED Bar graph display and 7-segment LED display, and to query toggle switch states. + - Interrupt Endpoint: -- Sends an 8-bit value that represents the state of the switches. - - Sent on startup, resume from suspend, and whenever the switch pack setting changes. - - Firmware does not de-bounce the switch pack. - - One switch change can result in multiple bytes being sent. - - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). + + - Sends an 8-bit value that represents the state of the switches. + + - Sent on startup, resume from suspend, and whenever the switch pack setting changes. + + - Firmware does not de-bounce the switch pack. + + - One switch change can result in multiple bytes being sent. + + - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). + - Bulk Endpoints are configured for loopback: -- The device moves data from IN endpoint to OUT endpoint. - - The device does not change the values of the data it receives nor does it internally create any data. - - Endpoints are always double buffered. - - Maximum packet size depends on speed (64 full speed, 512 high speed). + + - The device moves data from IN endpoint to OUT endpoint. + + - The device does not change the values of the data it receives nor does it internally create any data. + + - Endpoints are always double buffered. + + - Maximum packet size depends on speed (64 full speed, 512 high speed). ## Testing the driver -You can test this sample either by using the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample application, or by using the osrusbfx2.exe test application. For information on how to build and use the osrusbfx2.exe application, see the test instructions for the [umdf\_fx2](http://msdn.microsoft.com/en-us/library/windows/hardware/) sample. +You can test this sample either by using the [Custom driver access](https://go.microsoft.com/fwlink/p/?linkid=2114373) sample application, or by using the osrusbfx2.exe test application. For information on how to build and use the osrusbfx2.exe application, see the test instructions for the [umdf\_fx2](https://docs.microsoft.com/samples/microsoft/windows-driver-samples/sample-umdf-filter-above-umdf-function-driver-for-osr-usb-fx2-umdf-version-1/) sample. ## Sample Contents | Folder | Description | | --- | --- | | usb\umdf_filter_umdf\umdf_driver | This directory contains source code for the umdf_fx2 sample driver. | -| usb\umdf_filter_umdf\umdf_filter | This directory contains the UMDF filter driver. |
\ No newline at end of file +| usb\umdf_filter_umdf\umdf_filter | This directory contains the UMDF filter driver. | diff --git a/usb/umdf_fx2/README.md b/usb/umdf_fx2/README.md index f653a27c..f95374f2 100644 --- a/usb/umdf_fx2/README.md +++ b/usb/umdf_fx2/README.md @@ -5,22 +5,14 @@ languages: - cpp products: - windows +- windows-wdk --- -<!--- - name: Sample UMDF Function Driver for OSR USB-FX2 (UMDF version 1) - platform: UMDF1 - language: cpp - category: USB - description: A UMDF driver for the OSR USB-FX2 device that includes a test application, sample device metadata, and supports impersonation and idle power down. - samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=618002 ----> - # Sample UMDF Function Driver for OSR USB-FX2 (UMDF Version 1) The umdf\_fx2 sample is a User-Mode Driver Framework (UMDF) driver for the OSR USB-FX2 device. It includes a test app and sample device metadata, and supports impersonation and idle power down. -The sample can also be used with the CustomDeviceAccess MSDK sample. The sample demonstrates how to perform bulk and interrupt data transfers to an USB device. The specification for the device is at <http://www.osronline.com/hardware/OSRFX2_32.pdf>. The driver and sample device metadata also work with the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample. +The sample can also be used with the CustomDeviceAccess SDK sample. The sample demonstrates how to perform bulk and interrupt data transfers to an USB device. For more information, see the specification for the [OSR USB FX-2 Learning Kit](https://www.osronline.com/hardware/OSRFX2_32.pdf). The driver and sample device metadata also work with the [Custom driver access](https://go.microsoft.com/fwlink/p/?linkid=2114373) sample. The osrusbfx2 sample is divided into three samples: @@ -35,48 +27,72 @@ The osrusbfx2 sample is divided into three samples: The default Solution build configuration is Debug and Win32. 1. Open the driver project or solution in Visual Studio 2015 (find *filtername*.sln or *filtername*.vcxproj). + 1. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. + 1. From the **Configuration Manager**, select the **Active Solution Configuration** and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. + 1. From the **Build** menu, click **Build Solution** (Ctrl+Shift+B). ## Overview - The device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). + - It contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). + - Firmware supports vendor commands to query or set LED Bar graph display and 7-segment LED display, and to query toggle switch states. + - Interrupt Endpoint: -- Sends an 8-bit value that represents the state of the switches. + + - Sends an 8-bit value that represents the state of the switches. + - Sent on startup, resume from suspend, and whenever the switch pack setting changes. + - Firmware does not de-bounce the switch pack. + - One switch change can result in multiple bytes being sent. + - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). + - Bulk Endpoints are configured for loopback: -- The device moves data from IN endpoint to OUT endpoint. + + - The device moves data from IN endpoint to OUT endpoint. + - The device does not change the values of the data it receives nor does it internally create any data. + - Endpoints are always double buffered. + - Maximum packet size depends on speed (64 full speed, 512 high speed). ## Testing the driver -You can use the [Custom driver access](http://go.microsoft.com/fwlink/p/?LinkID=248288) sample to test the umdf\_fx2 sample. +You can use the [Custom driver access](https://go.microsoft.com/fwlink/p/?linkid=2114373) sample to test the umdf\_fx2 sample. This sample also includes a test application, osrusbfx2.exe, that you can use to test the device. This console application enumerates the interface registered by the driver and opens the device to send read, write, or IOCTL requests based on the command line options. Usage for Read/Write test: - -r [*n*], where *n* is number of bytes to read. + - -w [*n*], where *n* is number of bytes to write. + - -c [*n*], where *n* is number of iterations (default = 1). + - -v, shows verbose read data. + - -p, plays with Bar Display, Dip Switch, 7-Segment Display. + - -a, performs asynchronous I/O operation. + - -u, dumps USB configuration and pipe information. + - -f \<*filename*\> [*interval-seconds*], where *interval-seconds* is a delay in milliseconds, to send a text file to the seven-segment display (UMDF only) -**Playing with the 7 segment display, toggle switches, and bar graph display** +### Playing with the 7 segment display, toggle switches, and bar graph display -Use the command **osrusbfx2.exe -p** with options 1 through 9 to set and clear bar graph display, set and get 7 segment state, and read the toggle switch states. The following shows the function options: +Use the command `osrusbfx2.exe -p` with options 1 through 9 to set and clear bar graph display, set and get 7 segment state, and read the toggle switch states. The following shows the function options: +```cmd 1. Light Bar 2. Clear Bar 3. Light entire Bar graph @@ -92,253 +108,266 @@ Use the command **osrusbfx2.exe -p** with options 1 through 9 to set and clear b 0. Exit Selection: +``` -**Reset and re-enumerate the device** +### Reset and re-enumerate the device -Use the command **osrusbfx2.exe -p** with options 10 and 11 to either reset the device or re-enumerate the device. +Use the command `osrusbfx2.exe -p` with options 10 and 11 to either reset the device or re-enumerate the device. -**Read and write to bulk endpoints** +### Read and write to bulk endpoints The following commands send read and write requests to the device's bulk endpoint. -- `osrusbfx2.exe -r 64` +- `osrusbfx2.exe -r 64` The preceding command reads 64 bytes to the bulk IN endpoint. -- `osrusbfx2.exe -w 64 ` +- `osrusbfx2.exe -w 64` The preceding command writes 64 bytes to the bulk OUT endpoint. -- `osrusbfx2.exe -r 64 -w 64 -c 100 -v` +- `osrusbfx2.exe -r 64 -w 64 -c 100 -v` The preceding command first writes 64 bytes of data to bulk OUT endpoint (Pipe 1), then reads 64 bytes from bulk IN endpoint (Pipe 2), and then compares the read buffer with write buffer to see if they match. If the buffer contents match, it repeats this operation 100 times. -- `osrusbfx2.exe -a` +- `osrusbfx2.exe -a` The preceding command reads and writes to the device asynchronously in an infinite loop. The bulk endpoints are double buffered. Depending on the operational speed (full or high), the buffer size is either 64 bytes or 512 bytes, respectively. A request to read data does not complete if the buffers are empty. If the buffers are full, a request to write data does not complete until the buffers are emptied. When you are doing a synchronous read, make sure the endpoint buffer has data (for example, when you send 512 bytes write request to the device operating in full speed mode). Because the endpoints are double buffered, the total buffer capacity is 256 bytes. The first 256 bytes fills the buffer and the write request waits in the USB stack until the buffers are emptied. If you run another instance of the application to read 512 bytes of data, both write and read requests complete successfully. -**Displaying descriptors** +### Displaying descriptors The following command displays all the descriptors and endpoint information. -**osrusbfx2.exe -u** +`osrusbfx2.exe -u` If the device is operating in high speed mode, you get the following information: -`===================` +```cmd +=================== -`USB_CONFIGURATION_DESCRIPTOR` +USB_CONFIGURATION_DESCRIPTOR -`bLength = 0x9, decimal 9` +bLength = 0x9, decimal 9 -`bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE )` +bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE ) -`wTotalLength = 0x27, decimal 39` +wTotalLength = 0x27, decimal 39 -`bNumInterfaces = 0x1, decimal 1` +bNumInterfaces = 0x1, decimal 1 -`bConfigurationValue = 0x1, decimal 1` +bConfigurationValue = 0x1, decimal 1 -`iConfiguration = 0x4, decimal 4` +iConfiguration = 0x4, decimal 4 -`bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED )` +bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED ) -`MaxPower = 0x32, decimal 50` +MaxPower = 0x32, decimal 50 -`-----------------------------` +----------------------------- -`USB_INTERFACE_DESCRIPTOR #0` +USB_INTERFACE_DESCRIPTOR #0 -`bLength = 0x9` +bLength = 0x9 -`bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE )` +bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE ) -`bInterfaceNumber = 0x0` +bInterfaceNumber = 0x0 -`bAlternateSetting = 0x0` +bAlternateSetting = 0x0 -`bNumEndpoints = 0x3` +bNumEndpoints = 0x3 -`bInterfaceClass = 0xff` +bInterfaceClass = 0xff -`bInterfaceSubClass = 0x0` +bInterfaceSubClass = 0x0 -`bInterfaceProtocol = 0x0` +bInterfaceProtocol = 0x0 -`bInterface = 0x0` +bInterface = 0x0 -`------------------------------` +------------------------------ -`USB_ENDPOINT_DESCRIPTOR for Pipe00` +USB_ENDPOINT_DESCRIPTOR for Pipe00 -`bLength = 0x7` +bLength = 0x7 -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` +bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) -`bEndpointAddress= 0x81 ( INPUT )` +bEndpointAddress= 0x81 ( INPUT ) -`bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT )` +bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT ) -`wMaxPacketSize= 0x49, decimal 73` +wMaxPacketSize= 0x49, decimal 73 -`bInterval = 0x1, decimal 1` +bInterval = 0x1, decimal 1 -`------------------------------` +------------------------------ -`USB_ENDPOINT_DESCRIPTOR for Pipe01` +USB_ENDPOINT_DESCRIPTOR for Pipe01 -`bLength = 0x7` +bLength = 0x7 -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` +bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) -`bEndpointAddress= 0x6 ( OUTPUT )` +bEndpointAddress= 0x6 ( OUTPUT ) -`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` +bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK ) -`wMaxPacketSize= 0x200, ` +wMaxPacketSize= 0x200, -`decimal 512 bInterval = 0x0, ` +decimal 512 bInterval = 0x0, -`decimal 0` +decimal 0 -`------------------------------` +------------------------------ -`USB_ENDPOINT_DESCRIPTOR for Pipe02` +USB_ENDPOINT_DESCRIPTOR for Pipe02 -`bLength = 0x7` +bLength = 0x7 -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` +bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) -`bEndpointAddress= 0x88 ( INPUT )` +bEndpointAddress= 0x88 ( INPUT ) -`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` +bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK ) -`wMaxPacketSize= 0x200, decimal 512` +wMaxPacketSize= 0x200, decimal 512 -`bInterval = 0x0, decimal 0` +bInterval = 0x0, decimal 0 +``` If the device is operating in low speed mode, you will get the following information: -`===================` +```cmd +=================== -`USB_CONFIGURATION_DESCRIPTOR` +USB_CONFIGURATION_DESCRIPTOR -`bLength = 0x9, decimal 9` +bLength = 0x9, decimal 9 -`bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE )` +bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE ) -`wTotalLength = 0x27, decimal 39` +wTotalLength = 0x27, decimal 39 -`bNumInterfaces = 0x1, decimal 1` +bNumInterfaces = 0x1, decimal 1 -`bConfigurationValue = 0x1, decimal 1` +bConfigurationValue = 0x1, decimal 1 -`iConfiguration = 0x3, decimal 3` +iConfiguration = 0x3, decimal 3 -`bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED )` +bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED ) -`MaxPower = 0x32, decimal 50 ` +MaxPower = 0x32, decimal 50 -`-----------------------------` +----------------------------- -`USB_INTERFACE_DESCRIPTOR #0` +USB_INTERFACE_DESCRIPTOR #0 -`bLength = 0x9` +bLength = 0x9 -`bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE )` +bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE ) -`bInterfaceNumber = 0x0 bAlternateSetting = 0x0` +bInterfaceNumber = 0x0 bAlternateSetting = 0x0 -`bNumEndpoints = 0x3` +bNumEndpoints = 0x3 -`bInterfaceClass = 0xff` +bInterfaceClass = 0xff -`bInterfaceSubClass = 0x0` +bInterfaceSubClass = 0x0 -`bInterfaceProtocol = 0x0` +bInterfaceProtocol = 0x0 -`bInterface = 0x0` +bInterface = 0x0 -`------------------------------` +------------------------------ -`USB_ENDPOINT_DESCRIPTOR for Pipe00` +USB_ENDPOINT_DESCRIPTOR for Pipe00 -`bLength = 0x7` +bLength = 0x7 -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` +bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) -`bEndpointAddress= 0x81 ( INPUT )` +bEndpointAddress= 0x81 ( INPUT ) -`bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT )` +bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT ) -`wMaxPacketSize= 0x49, decimal 73` +wMaxPacketSize= 0x49, decimal 73 -`bInterval = 0x1, decimal 1` +bInterval = 0x1, decimal 1 -`------- -----------------------` +------- ----------------------- -`USB_ENDPOINT_DESCRIPTOR for Pipe01` +USB_ENDPOINT_DESCRIPTOR for Pipe01 -`bLength = 0x7` +bLength = 0x7 -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` +bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) -`bEndpointAddress= 0x6 ( OUTPUT )` +bEndpointAddress= 0x6 ( OUTPUT ) -`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` +bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK ) -`wMaxPacketSize= 0x40, decimal 64` +wMaxPacketSize= 0x40, decimal 64 -`bInterval = 0x0, decimal 0` +bInterval = 0x0, decimal 0 -`------------------------------` +------------------------------ -`USB_ENDPOINT_DESCRIPTOR for Pipe02` +USB_ENDPOINT_DESCRIPTOR for Pipe02 -`bLength = 0x7` +bLength = 0x7 -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` +bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) -`bEndpointAddress= 0x88 ( INPUT )` +bEndpointAddress= 0x88 ( INPUT ) -`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` +bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK ) -`wMaxPacketSize= 0x40, decimal 64` +wMaxPacketSize= 0x40, decimal 64 -`bInterval = 0x0, decimal 0 ` +bInterval = 0x0, decimal 0 +``` -Sample Contents ---------------- +## Sample Contents -Folder +### usb\\umdf\_fx2\\driver -Description +This directory contains driver code that demonstrates the following functionality: -usb\\umdf\_fx2\\driver +- Loads the driver and responds to PnP and Power events. You can install, uninstall, disable, enable, suspend, and resume the system. -This directory contains driver code that demonstrates the following functionality: +- Registers a PnP device interface so that application can open a handle to the device. + +- Implements **IPnpCallbackHardware** interface and initializes USB I/O targets in **IPnpCallbackHardware::OnPrepareHardware** method. + +- Creates a sequential queue for handling IOCTL requests. + +- Adds code to handle the IOCTL to set bar graph display. + +- Creates a parallel queue for handling read and write requests. + +- Retrieves memory from read and write requests, format the requests, and sends them to a USB target. + +- Supports additional IOCTLs to get and set the 7-segment display, get bar graph display, and get config descriptor. + +- Sets power policy for the device. + +- Adds code to indicate that the device is ready by lighting up the period on 7-segment display. + +- Calls **SetupDi** functions to determine the "BusTypeGUID" of the device, and uses impersonation to access resources that only the caller has access to. + +- Shows how to implement idle and wake functionality to make the driver the power policy owner (PPO). The sample achieves this using power-managed queues and UMDF DDIs, AssignS0IdleSettings, and AssignSxWakeSettings. + +- Demonstrates implementation of a continuous reader. -- Loads the driver and responds to PnP and Power events. You can install, uninstall, disable, enable, suspend, and resume the system. -- Registers a PnP device interface so that application can open a handle to the device. -- Implements **IPnpCallbackHardware** interface and initializes USB I/O targets in **IPnpCallbackHardware::OnPrepareHardware** method. -- Creates a sequential queue for handling IOCTL requests. -- Adds code to handle the IOCTL to set bar graph display. -- Creates a parallel queue for handling read and write requests. -- Retrieves memory from read and write requests, format the requests, and sends them to a USB target. -- Supports additional IOCTLs to get and set the 7-segment display, get bar graph display, and get config descriptor. -- Sets power policy for the device. -- Adds code to indicate that the device is ready by lighting up the period on 7-segment display. -- Calls **SetupDi** functions to determine the "BusTypeGUID" of the device, and uses impersonation to access resources that only the caller has access to. -- Shows how to implement idle and wake functionality to make the driver the power policy owner (PPO). The sample achieves this using power-managed queues and UMDF DDIs, AssignS0IdleSettings, and AssignSxWakeSettings. -- Demonstrates implementation of a continuous reader. -- Demonstrates the use of impersonation. +- Demonstrates the use of impersonation. -usb\\umdf\_fx2\\exe +### usb\\umdf\_fx2\\exe This directory contains a test application that can be used to drive the UMDF driver and FX2 device. This is a modified version of the test application for the KMDF Fx2 driver. -usb\\umdf\_fx2\\deviceMetadata +### usb\\umdf\_fx2\\deviceMetadata -This directory contains the device metadata package for the sample. You must copy the device metadata to the system before installing the device. For information on how to update and deploy device metadata, see [Custom driver access sample](http://go.microsoft.com/fwlink/p/?LinkID=248288).
\ No newline at end of file +This directory contains the device metadata package for the sample. You must copy the device metadata to the system before installing the device. For information on how to update and deploy device metadata, see [Custom driver access sample](https://go.microsoft.com/fwlink/p/?linkid=2114373). diff --git a/usb/usbsamp/README.md b/usb/usbsamp/README.md index ac5fb259..7c695eba 100644 --- a/usb/usbsamp/README.md +++ b/usb/usbsamp/README.md @@ -5,24 +5,16 @@ languages: - cpp products: - windows +- windows-wdk --- -<!--- - name: Usbsamp Generic USB Driver - platform: KMDF - language: cpp - category: USB - description: Demonstrates how to perform full speed, high speed, and SuperSpeed transfers to and from bulk and isochronous endpoints of a generic USB device. - samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=618938 ----> - # Usbsamp Generic USB Driver -The USBSAMP sample demonstrates how to perform full speed, high speed, and SuperSpeed transfers to and from bulk and isochronous endpoints of a generic USB device. USBSAMP is based on the [Kernel Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff557405) (KMDF). Superspeed bulk and isochronous transfers only work when the Microsoft USB 3.0 stack is loaded. +The USBSAMP sample demonstrates how to perform full speed, high speed, and SuperSpeed transfers to and from bulk and isochronous endpoints of a generic USB device. USBSAMP is based on the [Kernel Mode Driver Framework](https://docs.microsoft.com/windows-hardware/drivers/kernel/) (KMDF). Superspeed bulk and isochronous transfers only work when the Microsoft USB 3.0 stack is loaded. The sample also contains a console test application that initiates bulk (including stream) and isochronous transfers and obtains data from the device's I/O endpoints. The application also demonstrates how to use GUID-based device names and pipe names generated by the operating system using the **SetupDiXXX** user-mode APIs. -For information about USB, see [Universal Serial Bus (USB) Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff538930). +For information about USB, see [Universal Serial Bus (USB) Drivers](https://docs.microsoft.com/windows-hardware/drivers/usbcon/). ## Universal Windows Driver Compliant @@ -32,8 +24,8 @@ This sample builds a Universal Windows Driver. It uses only APIs and DDIs that a The sample driver can be loaded as the function driver for any of these devices: -- OSR FX2 learning kit. You can get the kit from [OSR Online](http://www.osronline.com/). -- [MUTT devices](http://msdn.microsoft.com/en-us/library/windows/hardware/dn376873). To order those devices, see [How to get MUTT devices](buses.microsoft_usb_test_tool__mutt__devices#howto). +- OSR FX2 learning kit. You can get the kit from [OSR Online](https://www.osronline.com/). For more information, see the specification for the [OSR USB FX-2 Learning Kit](https://www.osronline.com/hardware/OSRFX2_32.pdf) +- [MUTT devices](https://docs.microsoft.com/windows-hardware/drivers/usbcon/microsoft-usb-test-tool--mutt--devices). To order those devices, see [How to get MUTT devices](https://docs.microsoft.com/windows-hardware/drivers/usbcon/microsoft-usb-test-tool--mutt--devices#how-to-get-mutt-devices). - Intel 82930 USB test board. If you have a different USB device, you can still use the driver by adding the device's hardware ID to the INX file. Note that the data transfer scenarios will work only with the endpoints supported by the device. @@ -46,7 +38,7 @@ In Visual Studio, in Solution Explorer, right click **Solution 'usbsamp' (3 proj In Visual Studio, on the **Build** menu, choose **Build Solution**. -For more information about using Visual Studio to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). +For more information about using Visual Studio to build a driver package, see [Building a Driver with Visual Studio and the WDK](https://docs.microsoft.com/windows-hardware/drivers/develop/building-a-driver). ## Locate the built driver @@ -56,7 +48,7 @@ The driver folder contains these files: | File | Description | | --- | --- | -| usbsamp.sys | The driver file. | +| usbsamp.sys | The driver file | | usbsamp.inf | An information (INF) file that contains information needed to install the driver. | | kmdfsamples.cat | A signed catalog file, which serves as the signature for the entire package. | @@ -68,20 +60,23 @@ The process of moving the driver package to the target computer and installing t ### Automatic deployment -Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/en-us/library/windows/hardware/). +Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Provision a computer for driver deployment and testing (WDK 10)](https://docs.microsoft.com/windows-hardware/drivers/gettingstarted/provision-a-target-computer-wdk-8-1). 1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**. + 1. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Install and Verify**. Click **OK**. + 1. On the **Build** menu, choose **Deploy Package** or **Build Solution**. ### Manual deployment -Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](http://msdn.microsoft.com/en-us/library/windows/hardware/ff544707) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](https://docs.microsoft.com/en-us/windows-hardware/drivers/develop/preparing-a-computer-for-manual-driver-deployment). +Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](https://docs.microsoft.com/windows-hardware/drivers/devtest/devcon) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](https://docs.microsoft.com/windows-hardware/drivers/develop/preparing-a-computer-for-manual-driver-deployment). 1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\Usbsamp). + 1. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command: - **devcon install usbsamp.inf USB\\VID\_045E&PID\_078F** + `devcon install usbsamp.inf USB\VID_045E&PID_078F` ## View the device in Device Manager @@ -91,64 +86,66 @@ On the target computer, in a Command Prompt window, enter **devmgmt** to open De As an alternative to building the USBSAMP sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, Usbsamp.sln. Use the MSBuild command to build the solution. Here are some examples: - **msbuild /p:configuration="Debug" /p:platform="x64" Usbsamp.sln** + `msbuild /p:configuration="Debug" /p:platform="x64" Usbsamp.sln` - **msbuild /p:configuration="Release" /p:platform="Win32" Usbsamp.sln** + `msbuild /p:configuration="Release" /p:platform="Win32" Usbsamp.sln` -For more information about using MSBuild to build a driver package, see [Building a Driver](http://msdn.microsoft.com/en-us/library/windows/hardware/ff554644). +For more information about using MSBuild to build a driver package, see [Building a Driver with Visual Studio and the WDK](https://docs.microsoft.com/windows-hardware/drivers/develop/building-a-driver). ## Testing the sample The sample includes a test application, usbsamp.exe. This console application enumerates the interface registered by the driver and opens the device to send Read, Write, or DeviceIoControl requests based on the command line options. To test the sample, 1. In Visual Studio, choose **Solution Explorer** from the **View** menu. Locate the application project named **usbsamp**, under the **Exe** folder. + 1. Right-click and choose **Build**. For example, if your settings are Debug and x64, the application executable is in your solution folder under the exe\\Debug\\usbsamp.exe. + 1. Run the executable on the target machine. - To view all descriptors and endpoint information, use the following command. - **usbsamp.exe -u** + `usbsamp.exe -u` You can use the preceding command to view pipe numbers for read and write requests. - To send a Read-Write request, use the following command. - **usbsamp.exe -r 1024 -w 1024 -c 100 -v** + `usbsamp.exe -r 1024 -w 1024 -c 100 -v` The preceding command first writes 1024 bytes of data to bulk out endpoint (pipe 1), then reads 1024 bytes from bulk in endpoint (pipe 0), and compares the read buffer with write buffer to see if they match. If the buffer contents match, it performs this operation 100 times. - To send Read-Write requests to bulk endpoints, use any of the following commands, simultaneously. If Read-Write requests are sent to a SuperSpeed bulk endpoint with streams, the sample driver always uses the first underlying stream associated with that endpoint. The driver is multi-thread safe so it can handle multiple requests at a time. - **usbsamp.exe -r 65536** + `usbsamp.exe -r 65536` The preceding command reads 65536 bytes from pipe 0. - **usbsamp.exe -w 65536** + `usbsamp.exe -w 65536` The preceding command writes 65536 bytes to pipe 1. - **usbsamp.exe -r 65536 -i pipe02** + `usbsamp.exe -r 65536 -i pipe02` The preceding command reads 65536 bytes from pipe 2. - **usbsamp.exe -w 65536 -o pipe03** + `usbsamp.exe -w 65536 -o pipe03` The preceding command writes 65536 bytes to pipe 3. - To send Read and Write requests to isochronous endpoints you can use one or more of these commands simultaneously. - **usbsamp.exe -r 512 -i pipe04** + `usbsamp.exe -r 512 -i pipe04` The preceding command reads 512 bytes from pipe 4. - **usbsamp.exe -w 512 -o pipe05** + `usbsamp.exe -w 512 -o pipe05` The preceding command writes 512 bytes to pipe 5. - **usbsamp.exe -w 1024 -o pipe05 -r 1024 -i pipe04 -c 100 -v** + `usbsamp.exe -w 1024 -o pipe05 -r 1024 -i pipe04 -c 100 -v` The preceding command writes 1024 bytes to pipe 5, then reads 1024 bytes from pipe 4, and compares the buffers to see if they match. If the buffer contents match, it performs this operation 100 times. - To skip validation of the data to be read or written in a particular request, use the command with **-x** option as follows: - **usbsamp.exe -r 1024 -w 1024 -c 100 -x**
\ No newline at end of file + usbsamp.exe -r 1024 -w 1024 -c 100 -x diff --git a/usb/usbsamp/sys/driver.c b/usb/usbsamp/sys/driver.c index 26d61477..68b717e4 100644 --- a/usb/usbsamp/sys/driver.c +++ b/usb/usbsamp/sys/driver.c @@ -72,7 +72,7 @@ Return Value: UsbSamp_DbgPrint(3, ("Built %s %s\n", __DATE__, __TIME__)); // - // Initiialize driver config to control the attributes that + // Initialize driver config to control the attributes that // are global to the driver. Note that framework by default // provides a driver unload routine. If you create any resources // in the DriverEntry and want to be cleaned in driver unload, diff --git a/usb/usbsamp/sys/private.h b/usb/usbsamp/sys/private.h index d6d7898b..def503f5 100644 --- a/usb/usbsamp/sys/private.h +++ b/usb/usbsamp/sys/private.h @@ -52,11 +52,6 @@ Environment: #define DISPATCH_LATENCY_IN_MS 10 - -#undef ExAllocatePool -#define ExAllocatePool(type, size) \ - ExAllocatePoolWithTag(type, size, POOL_TAG); - #if DBG #define UsbSamp_DbgPrint(level, _x_) \ diff --git a/usb/usbsamp/sys/stream.c b/usb/usbsamp/sys/stream.c index ee434b35..d8cc05d9 100644 --- a/usb/usbsamp/sys/stream.c +++ b/usb/usbsamp/sys/stream.c @@ -199,8 +199,8 @@ Return Value: pStreamInfo->NumberOfStreams = supportedStreams; - pStreamInfo->StreamList = ExAllocatePoolWithTag( - NonPagedPoolNx, + pStreamInfo->StreamList = ExAllocatePool2( + POOL_FLAG_NON_PAGED, supportedStreams * sizeof(USBD_STREAM_INFORMATION), POOL_TAG); diff --git a/usb/usbview/README.md b/usb/usbview/README.md index 7876d9e3..b4bdd2bf 100644 --- a/usb/usbview/README.md +++ b/usb/usbview/README.md @@ -5,17 +5,9 @@ languages: - cpp products: - windows +- windows-wdk --- -<!--- - name: USBView sample application - platform: WDM - language: cpp - category: USB - description: Provides an application that allows you to browse all USB controllers and connected USB devices on your system. - samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=618004 ----> - # USBView sample application Usbview.exe is a Windows GUI application that allows you to browse all USB controllers and connected USB devices on your system. The left pane in the main application window displays a connection-oriented tree view, and the right pane displays the USB data structures pertaining to the selected USB device, such as the Device, Configuration, Interface, and Endpoint Descriptors, as well as the current device configuration. @@ -24,21 +16,28 @@ This functional application sample demonstrates how a user-mode application can The IOCTL calls (see the system include file USBIOCTL.H) demonstrated by this sample include: -- [**IOCTL\_GET\_HCD\_DRIVERKEY\_NAME**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537236) -- [**IOCTL\_USB\_GET\_DESCRIPTOR\_FROM\_NODE\_CONNECTION**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537310) -- [**IOCTL\_USB\_GET\_NODE\_CONNECTION\_DRIVERKEY\_NAME**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537317) -- [**IOCTL\_USB\_GET\_NODE\_CONNECTION\_INFORMATION**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537319) -- [**IOCTL\_USB\_GET\_NODE\_CONNECTION\_NAME**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537323) -- [**IOCTL\_USB\_GET\_NODE\_INFORMATION**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537324) -- [**IOCTL\_USB\_GET\_ROOT\_HUB\_NAME**](http://msdn.microsoft.com/en-us/library/windows/hardware/ff537326) +- [**IOCTL\_GET\_HCD\_DRIVERKEY\_NAME**](https://docs.microsoft.com/windows/win32/api/usbuser/ni-usbuser-ioctl_get_hcd_driverkey_name) + +- [**IOCTL\_USB\_GET\_DESCRIPTOR\_FROM\_NODE\_CONNECTION**](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/usbioctl/ni-usbioctl-ioctl_usb_get_descriptor_from_node_connection) + +- [**IOCTL\_USB\_GET\_NODE\_CONNECTION\_DRIVERKEY\_NAME**](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/usbioctl/ni-usbioctl-ioctl_usb_get_node_connection_driverkey_name) + +- [**IOCTL\_USB\_GET\_NODE\_CONNECTION\_INFORMATION**](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/usbioctl/ni-usbioctl-ioctl_usb_get_node_connection_information) + +- [**IOCTL\_USB\_GET\_NODE\_CONNECTION\_NAME**](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/usbioctl/ni-usbioctl-ioctl_usb_get_node_connection_name) -For information about USB, see [Universal Serial Bus (USB) Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff538930). +- [**IOCTL\_USB\_GET\_NODE\_INFORMATION**](https://docs.microsoft.com/windows-hardware/drivers/ddi/content/usbioctl/ni-usbioctl-ioctl_usb_get_node_information) + +- [**IOCTL\_USB\_GET\_ROOT\_HUB\_NAME**](https://docs.microsoft.com/windows/win32/api/usbuser/ni-usbuser-ioctl_usb_get_root_hub_name) + +For information about USB, see [Universal Serial Bus (USB) Drivers](https://docs.microsoft.com/windows-hardware/drivers/usbcon/). ## Run the sample ### Local debugging 1. Change **Debugger** to launch to **Local Windows Debugger**. + 1. On the **Debug** menu, select **Start debugging** or hit **F5**. ### Manual deployment to a remote target computer @@ -46,14 +45,19 @@ For information about USB, see [Universal Serial Bus (USB) Drivers](http://msdn. If you want to debug the sample app on a remote computer, 1. Copy the executable to a folder on the remote computer. -1. Specify project properties as per the instructions given in [Set Up Remote Debugging for a Visual Studio Project](http://msdn.microsoft.com/en-us/library/8x6by8d2.aspx). + +1. Specify project properties as per the instructions given in [Remote Debugging](https://docs.microsoft.com/visualstudio/debugger/remote-debugging?view=vs-2015). + 1. Change **Debugger** to launch to **Remote Windows Debugger**. + 1. On the **Debug** menu, select **Start debugging** or hit **F5**. ### View a USB device in Usbview 1. Attach a USB device to one of USB ports on the computer that has Usbview running. + 1. In the device tree, locate the device. For example the device might be under the Intel(R) ICH10 Family USB Universal Host Controller - 3A34 \> Root Hub node. + 1. View host controller and port properties on the right pane. ## Code tour @@ -73,7 +77,9 @@ If you want to debug the sample app on a remote computer, The major topics covered in this tour are: - GUI handling routines + - Device enumeration routines + - Device information display routines The file Usbview.c contains the sample application entry point and GUI handling routines. On entry, the main application window is created, which is actually a dialog box as defined in Usbview.rc. The dialog box consists of a split window with a tree view control on the left side and an edit control on the right side. @@ -83,7 +89,9 @@ The routine RefreshTree() is called to enumerate USB host controller, hubs, and The file Enum.c contains the routines that enumerate the USB bus and populate the tree view control. The USB device enumeration and information collection process is the main point of this sample application. The enumeration process starts at EnumerateHostControllers() and goes like this: 1. Enumerate Host Controllers and Root Hubs. Host controllers have symbolic link names of the form HCDx, where x starts at 0. Use CreateFile() to open each host controller symbolic link. Create a node in the tree view to represent each host controller. After a host controller has been opened, send the host controller an IOCTL\_USB\_GET\_ROOT\_HUB\_NAME request to get the symbolic link name of the root hub that is part of the host controller. + 1. Enumerate Hubs (Root Hubs and External Hubs). Given the name of a hub, use CreateFile() to open the hub. Send the hub an IOCTL\_USB\_GET\_NODE\_INFORMATION request to get info about the hub, such as the number of downstream ports. Create a node in the tree view to represent each hub. + 1. Enumerate Downstream Ports. Given a handle to an open hub and the number of downstream ports on the hub, send the hub an IOCTL\_USB\_GET\_NODE\_CONNECTION\_INFORMATION request for each downstream port of the hub to get info about the device (if any) attached to each port. If there is a device attached to a port, send the hub an IOCTL\_USB\_GET\_NODE\_CONNECTION\_NAME request to get the symbolic link name of the hub attached to the downstream port. If there is a hub attached to the downstream port, recurse to step (2). Create a node in the tree view to represent each hub port and attached device. USB configuration and string descriptors are retrieved from attached devices in GetConfigDescriptor() and GetStringDescriptor() by sending an IOCTL\_USB\_GET\_DESCRIPTOR\_FROM\_NODE\_CONNECTION() to the hub to which the device is attached. -The file Display.c contains routines that display information about selected devices in the application edit control. Information about the device was collected during the enumeration of the device tree. This information includes USB device, configuration, and string descriptors and connection and configuration information that is maintained by the USB stack. The routines in this file simply parse and print the data structures for the device that were collected when it was enumerated. The file Dispaud.c parses and prints data structures that are specific to USB audio class devices.
\ No newline at end of file +The file Display.c contains routines that display information about selected devices in the application edit control. Information about the device was collected during the enumeration of the device tree. This information includes USB device, configuration, and string descriptors and connection and configuration information that is maintained by the USB stack. The routines in this file simply parse and print the data structures for the device that were collected when it was enumerated. The file Dispaud.c parses and prints data structures that are specific to USB audio class devices. diff --git a/usb/wdf_osrfx2_lab/README.md b/usb/wdf_osrfx2_lab/README.md index bb565a5d..aee7a886 100644 --- a/usb/wdf_osrfx2_lab/README.md +++ b/usb/wdf_osrfx2_lab/README.md @@ -5,17 +5,9 @@ languages: - cpp products: - windows +- windows-wdk --- -<!--- - name: WDF Sample Driver Learning Lab for OSR USB-FX2 - platform: UMDF1 KMDF - language: cpp - category: USB - description: Contains a console test application and a series of iterative drivers for both KMDF and UMDF version 1. - samplefwlink: https://go.microsoft.com/fwlink/?linkid=856746 ----> - # WDF Sample Driver Learning Lab for OSR USB-FX2 The wdf\_osrfx2\_lab sample contains a console test application and a series of iterative drivers for both Kernel-Mode Driver Framework (KMDF) and User-Mode Driver Framework (UMDF) version 1. @@ -24,362 +16,350 @@ In the Windows Driver Kit (WDK) for Windows 7 and earlier versions of Windows, t Starting in Windows 8.1, the osrusbfx2 sample has been divided into these samples: -- wdf\_osrfx2: This sample is a series of iterative drivers that demonstrate how to write a "Hello World" driver and adds additional features in each step. - -- [kmdf\_fx2](gallery_samples.123a_gallery#1): This sample is the final version of kernel-mode wdf\_osrfx2 driver. The sample demonstrates KMDF methods. +- [wdf\_osrfx2](https://docs.microsoft.com/samples/microsoft/windows-driver-samples/wdf-sample-driver-learning-lab-for-osr-usb-fx2/): This sample is a series of iterative drivers that demonstrate how to write a "Hello World" driver and adds additional features in each step. -- [umdf\_fx2](http://msdn.microsoft.com/en-us/library/windows/hardware/): This sample is the final version of the user-mode driver wdf\_osrfx2. The sample demonstrates UMDF methods. +- [kmdf\_fx2](https://docs.microsoft.com/samples/microsoft/windows-driver-samples/sample-kmdf-bus-driver-for-osr-usb-fx2/): This sample is the final version of kernel-mode wdf\_osrfx2 driver. The sample demonstrates KMDF methods. -This sample is written for the OSR USB-FX2 Learning Kit. The specification for the device is at <http://www.osronline.com/hardware/OSRFX2_32.pdf>. +- [umdf\_fx2](https://docs.microsoft.com/samples/microsoft/windows-driver-samples/sample-umdf-function-driver-for-osr-usb-fx2-umdf-version-1/): This sample is the final version of the user-mode driver wdf\_osrfx2. The sample demonstrates UMDF methods. +This sample is written for the OSR USB-FX2 Learning Kit. For more information, see the specification for the [OSR USB FX-2 Learning Kit](https://www.osronline.com/hardware/OSRFX2_32.pdf). -Related topics --------------- +## Build the sample -[kmdf\_fx2](http://msdn.microsoft.com/en-us/library/windows/hardware/) +The default Solution build configuration is Windows 8.1 Debug and Win32. You can change the default configuration to build for Windows 8 or Windows 7 version of the operating system. -[umdf\_fx2](http://msdn.microsoft.com/en-us/library/windows/hardware/) +### To select a configuration and build a driver +1. Open the driver project or solution in Visual Studio 2013 (find *filtername*.sln or *filtername*.vcxproj). -Build the sample ----------------- +1. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. -The default Solution build configuration is Windows 8.1 Debug and Win32. You can change the default configuration to build for Windows 8 or Windows 7 version of the operating system. +1. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Windows 8.1 Debug or Windows 8.1 Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. -**To select a configuration and build a driver** +1. Each driver project in this iterative sample creates a binary with the same name, osrusbfx2.sys. As a result, you can build only the single project you're currently working on, as well as the package project. You can do this by selecting only these two projects in **Configuration Manager**. -1. Open the driver project or solution in Visual Studio 2013 (find *filtername*.sln or *filtername*.vcxproj). -2. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. -3. From the **Configuration Manager**, select the **Active Solution Configuration** (for example, Windows 8.1 Debug or Windows 8.1 Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. -4. Each driver project in this iterative sample creates a binary with the same name, osrusbfx2.sys. As a result, you can build only the single project you're currently working on, as well as the package project. You can do this by selecting only these two projects in **Configuration Manager**. -5. From the **Build** menu, click **Build Solution** (Ctrl+Shift+B). +1. From the **Build** menu, click **Build Solution** (Ctrl+Shift+B). -Overview --------- +## Overview Here is the overview of the device: -- The device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). -- It contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). -- Firmware supports vendor commands to query or set LED Bar graph display and 7-segment LED display, and to query toggle switch states. -- Interrupt Endpoint: - - Sends an 8-bit value that represents the state of the switches. - - Sent on startup, resume from suspend, and whenever the switch pack setting changes. - - Firmware does not de-bounce the switch pack. - - One switch change can result in multiple bytes being sent. - - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). -- Bulk Endpoints are configured for loopback: - - The device moves data from IN endpoint to OUT endpoint. - - The device does not change the values of the data it receives nor does it internally create any data. - - Endpoints are always double buffered. - - Maximum packet size depends on speed (64 full speed, 512 high speed). +- The device is based on the development board supplied with the Cypress EZ-USB FX2 Development Kit (CY3681). + +- It contains 1 interface and 3 endpoints (Interrupt IN, Bulk Out, Bulk IN). + +- Firmware supports vendor commands to query or set LED Bar graph display and 7-segment LED display, and to query toggle switch states. + +- Interrupt Endpoint: + + - Sends an 8-bit value that represents the state of the switches. + + - Sent on startup, resume from suspend, and whenever the switch pack setting changes. + + - Firmware does not de-bounce the switch pack. + + - One switch change can result in multiple bytes being sent. + + - Bits are in the reverse order of the labels on the pack (for example, bit 0x80 is labeled 1 on the pack). + +- Bulk Endpoints are configured for loopback: + + - The device moves data from IN endpoint to OUT endpoint. + + - The device does not change the values of the data it receives nor does it internally create any data. + + - Endpoints are always double buffered. + + - Maximum packet size depends on speed (64 full speed, 512 high speed). + +## Sample Contents for KMDF + +The KMDF sample contains a console test application and a series of drivers. The driver is iterative as a series of steps, starting with a basic "Hello World" driver. + +### usb\wdf_osrfx2_lab\kmdf\step1 + +The most basic step. The source file contains a minimal amount of code to get the driver loaded in memory and respond to PnP and Power events. You can install, uninstall, disable, enable, suspend, and resume the system. -Sample Contents for KMDF ------------------------- +### usb\wdf_osrfx2_lab\kmdf\step2 -The KMDF sample contains a console test application and a series of drivers. The driver is iterative as a series of steps, starting with a basic "Hello World" driver. Each step is describe in the following table. +- Creates a context with the WDFDEVICE object -<table> -<colgroup> -<col width="50%" /> -<col width="50%" /> -</colgroup> -<thead> -<tr class="header"> -<th align="left">Folder -Description</th> -</tr> -</thead> -<tbody> -<tr class="odd"> -<td align="left">usb\wdf_osrfx2_lab\kmdf\step1 -The most basic step. The source file contains a minimal amount of code to get the driver loaded in memory and respond to PnP and Power events. You can install, uninstall, disable, enable, suspend, and resume the system.</td> -<td align="left">usb\wdf_osrfx2_lab\kmdf\step2 -<ol> -<li>Creates a context with the WDFDEVICE object.</li> -<li>Initializes the USB device by registering a <em>EvtPrepareHardware</em> callback.</li> -<li>Registers an interface so that application can open a handle to the device.</li> -</ol></td> -</tr> -</tbody> -</table> +- Initializes the USB device by registering a **EvtPrepareHardware** callback -Testing the driver ------------------- +- Registers an interface so that application can open a handle to the device + +## Testing the driver The sample includes a test application, osrusbfx2.exe, that you can use to test the device. This console application enumerates the interface registered by the driver and opens the device to send read, write, or IOCTL requests based on the command line options. Usage for Read/Write test: -- -r [*n*], where *n* is number of bytes to read. -- -w [*n*], where *n* is number of bytes to write. -- -c [*n*], where *n* is number of iterations (default = 1). -- -v, shows verbose read data. -- -p, plays with Bar Display, Dip Switch, 7-Segment Display. -- -a, performs asynchronous I/O operation. -- -u, dumps USB configuration and pipe information. +- -r [*n*], where *n* is number of bytes to read. + +- -w [*n*], where *n* is number of bytes to write. + +- -c [*n*], where *n* is number of iterations (default = 1). + +- -v, shows verbose read data. + +- -p, plays with Bar Display, Dip Switch, 7-Segment Display. + +- -a, performs asynchronous I/O operation. -**Playing with the 7 segment display, toggle switches and bar graph display** +- -u, dumps USB configuration and pipe information. -Use the command **osrusbfx2.exe -p** with options 1-9 to set and clear bar graph display, set and get 7-segment state, and read the toggle switch states. The following list shows the function options: +### Playing with the 7 segment display, toggle switches and bar graph display -1. Light bar -2. Clear bar -3. Light entire bar graph -4. Clear entire bar graph -5. Get bar graph state -6. Get switch state -7. Get switch interrupt message -8. Get 7-segment state -9. Set 7-segment state +Use the command `osrusbfx2.exe -p` with options 1-9 to set and clear bar graph display, set and get 7-segment state, and read the toggle switch states. The following list shows the function options: + +```cmd +1. Light bar +2. Clear bar +3. Light entire bar graph +4. Clear entire bar graph +5. Get bar graph state +6. Get switch state +7. Get switch interrupt message +8. Get 7-segment state +9. Set 7-segment state 10. Reset the device 11. Re-enumerate the device 0. Exit Selection: +``` -**Reset and re-enumerate the device** +### Reset and re-enumerate the device Use the command **osrusbfx2.exe -p** with option 10 and 11 to either reset the device or re-enumerate the device. -**Read and write to bulk endpoints** +### Read and write to bulk endpoints The following commands send read and write requests to the device's bulk endpoint. -- `osrusbfx2.exe -r 64` +- `osrusbfx2.exe -r 64` The preceding command reads 64 bytes to the bulk IN endpoint. -- `osrusbfx2.exe -w 64 ` +- `osrusbfx2.exe -w 64` The preceding command writes 64 bytes to the bulk OUT endpoint. -- `osrusbfx2.exe -r 64 -w 64 -c 100 -v` +- `osrusbfx2.exe -r 64 -w 64 -c 100 -v` The preceding command first writes 64 bytes of data to bulk OUT endpoint (Pipe 1), then reads 64 bytes from bulk IN endpoint (Pipe 2), and then compares the read buffer with write buffer to see if they match. If the buffer contents match, it repeats this operation 100 times. -- `osrusbfx2.exe -a` +- `osrusbfx2.exe -a` The preceding command reads and writes to the device asynchronously in an infinite loop. The bulk endpoints are double buffered. Depending on the operational speed (full or high), the buffer size is either 64 bytes or 512 bytes, respectively. A request to read data doesn't complete if the buffers are empty. If the buffers are full, a request to write data does not complete until the buffers are emptied. When you are doing a synchronous read, make sure the endpoint buffer has data (for example, when you send 512 bytes write request to the device operating in full speed mode). Because the endpoints are double buffered, the total buffer capacity is 256 bytes. The first 256 bytes fills the buffer and the write request waits in the USB stack until the buffers are emptied. If you run another instance of the application to read 512 bytes of data, both write and read requests complete successfully. -**Displaying descriptors** +### Displaying descriptors The following command displays all the descriptors and endpoint information. -**osrusbfx2.exe -u** +`osrusbfx2.exe -u` If the device is operating in high speed mode, you get the following information: -`===================` +```cmd +=================== -`USB_CONFIGURATION_DESCRIPTOR` +USB_CONFIGURATION_DESCRIPTOR -`bLength = 0x9, decimal 9` +bLength = 0x9, decimal 9 -`bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE )` +bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE ) -`wTotalLength = 0x27, decimal 39` +wTotalLength = 0x27, decimal 39 -`bNumInterfaces = 0x1, decimal 1` +bNumInterfaces = 0x1, decimal 1 -`bConfigurationValue = 0x1, decimal 1` +bConfigurationValue = 0x1, decimal 1 -`iConfiguration = 0x4, decimal 4` +iConfiguration = 0x4, decimal 4 -`bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED )` +bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED ) -`MaxPower = 0x32, decimal 50` +MaxPower = 0x32, decimal 50 -`-----------------------------` +----------------------------- -`USB_INTERFACE_DESCRIPTOR #0` +USB_INTERFACE_DESCRIPTOR #0 -`bLength = 0x9` +bLength = 0x9 -`bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE )` +bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE ) -`bInterfaceNumber = 0x0` +bInterfaceNumber = 0x0 -`bAlternateSetting = 0x0` +bAlternateSetting = 0x0 -`bNumEndpoints = 0x3` +bNumEndpoints = 0x3 -`bInterfaceClass = 0xff` +bInterfaceClass = 0xff -`bInterfaceSubClass = 0x0` +bInterfaceSubClass = 0x0 -`bInterfaceProtocol = 0x0` +bInterfaceProtocol = 0x0 -`bInterface = 0x0` +bInterface = 0x0 -`------------------------------` +------------------------------ -`USB_ENDPOINT_DESCRIPTOR for Pipe00` +USB_ENDPOINT_DESCRIPTOR for Pipe00 -`bLength = 0x7` +bLength = 0x7 -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` +bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) -`bEndpointAddress= 0x81 ( INPUT )` +bEndpointAddress= 0x81 ( INPUT ) -`bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT )` +bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT ) -`wMaxPacketSize= 0x49, decimal 73` +wMaxPacketSize= 0x49, decimal 73 -`bInterval = 0x1, decimal 1` +bInterval = 0x1, decimal 1 -`------------------------------` +------------------------------ -`USB_ENDPOINT_DESCRIPTOR for Pipe01` +USB_ENDPOINT_DESCRIPTOR for Pipe01 -`bLength = 0x7` +bLength = 0x7 -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` +bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) -`bEndpointAddress= 0x6 ( OUTPUT )` +bEndpointAddress= 0x6 ( OUTPUT ) -`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` +bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK ) -`wMaxPacketSize= 0x200, ` +wMaxPacketSize= 0x200, -`decimal 512 bInterval = 0x0, ` +decimal 512 bInterval = 0x0, -`decimal 0` +decimal 0 -`------------------------------` +------------------------------ -`USB_ENDPOINT_DESCRIPTOR for Pipe02` +USB_ENDPOINT_DESCRIPTOR for Pipe02 -`bLength = 0x7` +bLength = 0x7 -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` +bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) -`bEndpointAddress= 0x88 ( INPUT )` +bEndpointAddress= 0x88 ( INPUT ) -`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` +bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK ) -`wMaxPacketSize= 0x200, decimal 512` +wMaxPacketSize= 0x200, decimal 512 -`bInterval = 0x0, decimal 0` +bInterval = 0x0, decimal 0 +``` If the device is operating in low speed mode, you will get the following information: -`===================` +```txt +=================== + +USB_CONFIGURATION_DESCRIPTOR + +bLength = 0x9, decimal 9 + +bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE ) + +wTotalLength = 0x27, decimal 39 -`USB_CONFIGURATION_DESCRIPTOR` +bNumInterfaces = 0x1, decimal 1 -`bLength = 0x9, decimal 9` +bConfigurationValue = 0x1, decimal 1 -`bDescriptorType = 0x2 ( USB_CONFIGURATION_DESCRIPTOR_TYPE )` +iConfiguration = 0x3, decimal 3 -`wTotalLength = 0x27, decimal 39` +bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED ) -`bNumInterfaces = 0x1, decimal 1` +MaxPower = 0x32, decimal 50 -`bConfigurationValue = 0x1, decimal 1` +----------------------------- -`iConfiguration = 0x3, decimal 3` +USB_INTERFACE_DESCRIPTOR #0 -`bmAttributes = 0xa0 ( USB_CONFIG_BUS_POWERED )` +bLength = 0x9 -`MaxPower = 0x32, decimal 50 ` +bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE ) -`-----------------------------` +bInterfaceNumber = 0x0 bAlternateSetting = 0x0 -`USB_INTERFACE_DESCRIPTOR #0` +bNumEndpoints = 0x3 -`bLength = 0x9` +bInterfaceClass = 0xff -`bDescriptorType = 0x4 ( USB_INTERFACE_DESCRIPTOR_TYPE )` +bInterfaceSubClass = 0x0 -`bInterfaceNumber = 0x0 bAlternateSetting = 0x0` +bInterfaceProtocol = 0x0 -`bNumEndpoints = 0x3` +bInterface = 0x0 -`bInterfaceClass = 0xff` +------------------------------ -`bInterfaceSubClass = 0x0` +USB_ENDPOINT_DESCRIPTOR for Pipe00 -`bInterfaceProtocol = 0x0` +bLength = 0x7 -`bInterface = 0x0` +bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) -`------------------------------` +bEndpointAddress= 0x81 ( INPUT ) -`USB_ENDPOINT_DESCRIPTOR for Pipe00` +bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT ) -`bLength = 0x7` +wMaxPacketSize= 0x49, decimal 73 -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` +bInterval = 0x1, decimal 1 -`bEndpointAddress= 0x81 ( INPUT )` +------------------------------ -`bmAttributes= 0x3 ( USB_ENDPOINT_TYPE_INTERRUPT )` +USB_ENDPOINT_DESCRIPTOR for Pipe01 -`wMaxPacketSize= 0x49, decimal 73` +bLength = 0x7 -`bInterval = 0x1, decimal 1` +bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) -`------- -----------------------` +bEndpointAddress= 0x6 ( OUTPUT ) -`USB_ENDPOINT_DESCRIPTOR for Pipe01` +bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK ) -`bLength = 0x7` +wMaxPacketSize= 0x40, decimal 64 -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` +bInterval = 0x0, decimal 0 -`bEndpointAddress= 0x6 ( OUTPUT )` +------------------------------ -`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` +USB_ENDPOINT_DESCRIPTOR for Pipe02 -`wMaxPacketSize= 0x40, decimal 64` +bLength = 0x7 -`bInterval = 0x0, decimal 0` +bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE ) -`------------------------------` +bEndpointAddress= 0x88 ( INPUT ) -`USB_ENDPOINT_DESCRIPTOR for Pipe02` +bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK ) -`bLength = 0x7` +wMaxPacketSize= 0x40, decimal 64 -`bDescriptorType = 0x5 ( USB_ENDPOINT_DESCRIPTOR_TYPE )` +bInterval = 0x0, decimal 0 +``` -`bEndpointAddress= 0x88 ( INPUT )` +## Sample Contents for UMDF -`bmAttributes= 0x2 ( USB_ENDPOINT_TYPE_BULK )` +The UMDF sample driver is developed as a series of steps, starting with a basic "Hello World" driver. Each step progressively adds functionality to the previous step. -`wMaxPacketSize= 0x40, decimal 64` +### usb\wdf_osrfx2_lab\umdf\step1 -`bInterval = 0x0, decimal 0 ` +The most basic step. The source file contains a minimal amount of code to get the driver loaded in memory and respond to PnP and Power events. You can install, uninstall, disable, enable, suspend, and resume the system. -Sample Contents for UMDF ------------------------- +### usb\wdf_osrfx2_lab\umdf\step2 -The UMDF sample driver is developed as a series of steps, starting with a basic "Hello World" driver. Each step progressively adds functionality to the previous step. Each step is described in the following table. +- The device registers a PnP device interface so that application can open a handle to the device. -<table> -<colgroup> -<col width="50%" /> -<col width="50%" /> -</colgroup> -<thead> -<tr class="header"> -<th align="left">Folder -Description</th> -</tr> -</thead> -<tbody> -<tr class="odd"> -<td align="left">usb\wdf_osrfx2_lab\umdf\step1 -The most basic step. The source file contains a minimal amount of code to get the driver loaded in memory and respond to PnP and Power events. You can install, uninstall, disable, enable, suspend, and resume the system.</td> -<td align="left">usb\wdf_osrfx2_lab\umdf\step2 -<ol> -<li>The device registers a PnP device interface so that application can open a handle to the device.</li> -<li>The device object implements <strong>IPnpCallbackHardware</strong> interface and initializes USB I/O targets in <strong>IPnpCallbackHardware::OnPrepareHardware</strong> method.</li> -</ol></td> -</tr> -</tbody> -</table>
\ No newline at end of file +- The device object implements **IPnpCallbackHardware** interface and initializes USB I/O targets in **IPnpCallbackHardware::OnPrepareHardware** method. |