diff options
| author | Barry Golden <[email protected]> | 2019-03-12 14:02:43 -0700 |
|---|---|---|
| committer | Adonais Romero González <[email protected]> | 2019-03-12 14:02:43 -0700 |
| commit | ef7ec4ec9ff7ce3c53d60e1c8906915966e17e01 (patch) | |
| tree | 3017523a73c6552c27947d402afa6062f4df2706 /usb | |
| parent | 35bff356ac249057f4d673d39c7f28ed348cbf0f (diff) | |
Update README.md for samples portal (#358)
* Update README.md for samples portal
* Update README.md for samples portal
* Removed installwdf
* Update fork (#2)
* Fix typo
ture -> true
* Remove InstallWdf sample
* Fix typo (#340)
ture -> true
* Readme typo fix (#349)
* Update langid
Diffstat (limited to 'usb')
26 files changed, 428 insertions, 508 deletions
diff --git a/usb/UcmCxUcsi/README.md b/usb/UcmCxUcsi/README.md index 3ebd5d5d..46fac17e 100644 --- a/usb/UcmCxUcsi/README.md +++ b/usb/UcmCxUcsi/README.md @@ -1,3 +1,13 @@ +--- +topic: sample +name: UcmTcpciCx Port Controller Client Driver +description: Demonstrates how to create a Windows USB Type-C port controller driver using the USB Connector Manager class extension driver (UcmCx). +languages: + - cpp +products: + - windows +--- + <!--- name: UcmTcpciCx Port Controller Client Driver platform: KMDF @@ -7,7 +17,6 @@ samplefwlink: https://go.microsoft.com/fwlink/p/?linkid=856744 ---> - # 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). @@ -22,38 +31,41 @@ Microsoft already provides an inbox UCSI driver, UcmUcsi.sys. This UcmCxUcsi sam 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. +- 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 + This sample is specific to UCSI systems. You may choose to structure your driver in a similar way for your own hardware. Understand the requirements and specification of your own system prior to writing a new UcmCx client driver. In addition to making the logic and functionality suit your specific port controller hardware, you will need to modify the .inf such that it matches your device's information. -### UcmCxUcsi structure +## UcmCxUcsi structure In this sample, UCM-specific interactions are split apart from most of the UCSI-specific operations. -#### UcmCx Interactions +### UcmCx interactions + 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. -- 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). +- 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. +- 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). - 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. + - 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 -#### UCSI and WDF Interactions The remainder of the files perform operations for UCSI and WDF, non-specific to UCM. - Acpi.cpp - - ACPI method evaluation helper routines. + - ACPI method evaluation helper routines. - Driver.cpp - - Entry point to the driver. Initializes the driver with WDF. + - 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. - + - 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://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. diff --git a/usb/UcmCxUcsi/usb-ucmcxucsi.yml b/usb/UcmCxUcsi/usb-ucmcxucsi.yml deleted file mode 100644 index 3b169724..00000000 --- a/usb/UcmCxUcsi/usb-ucmcxucsi.yml +++ /dev/null @@ -1,12 +0,0 @@ -### YamlMime:Sample -sample: -- name: UcmTcpciCx Port Controller Client Driver - description: Demonstrates how to create a Windows USB Type-C port controller driver using the USB Connector Manager class extension driver (UcmCx). - generateZip: true - preserveParentHierarchy: true - author: windows-driver-samples - languages: - - cpp - technologies: - - windows - vssolution: /usb/UcmCxUcsi/UcmCxUcsi.sln diff --git a/usb/UcmTcpciCxClientSample/README.md b/usb/UcmTcpciCxClientSample/README.md index 02d043bf..3f00573c 100644 --- a/usb/UcmTcpciCxClientSample/README.md +++ b/usb/UcmTcpciCxClientSample/README.md @@ -1,3 +1,13 @@ +--- +topic: sample +name: UcmTcpciCx Port Controller Client Driver +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). +languages: + - cpp +products: + - windows +--- + <!--- name: UcmTcpciCx Port Controller Client Driver platform: KMDF @@ -7,48 +17,50 @@ 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 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 + The sample contains a number of comments prefaced with `// TODO` - review them and modify the code as necessary as you are writing your driver. ## 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. 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 + The USB Type-C Port Controller Interface specification defines I2C to be the channel by which software communicates with the port controller hardware. If your port controller hardware is not compliant with the specification and does not use I2C as the communications channel, you will need to make additional modifications to the sample. ## 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://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. -# Testing Your Type-C Port Controller (TCPC) Implementation on Windows 10 with Raspberry Pi +## Testing Your Type-C Port Controller (TCPC) Implementation on Windows 10 with Raspberry Pi -## Pre-requisites +### Pre-requisites 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. -## Setup +### Setup -### Operating System +#### Operating System Download the latest available Windows 10 IoT Core Insider Preview image here: @@ -60,25 +72,25 @@ Install on your Raspberry Pi 2 or 3 per the following instructions: 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 +#### 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> -### Windows Device Portal +#### 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> -### Kernel Debugger +#### 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> -## Connect TCPC Hardware +#### 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. @@ -90,27 +102,27 @@ First, shutdown and remove power from both the Raspberry Pi and your TCPC hardwa Connect the following pins between your TCPC and the Raspberry Pi: -- GND: many options +- GND: many options -- SDA: pin 3 +- SDA: pin 3 -- SCL: pin 5 +- SCL: pin 5 -- ALERT: can be any GPIO but the sample ACPI is setup to use GPIO 5 (pull-up) which is pin 29 on the RPi2 +- ALERT: can be any GPIO but the sample ACPI is setup to use GPIO 5 (pull-up) which is pin 29 on the RPi2 Note the ACPI sample assumes GPIO5 (pin 29). If you use a different bus or interrupt you will need to update the sample ASL file to reflect the selected configuration. Once these pins are connected, both boards may be powered on. You will not see any changes to the device manager view of the Device Portal yet. -## UcmTcpciCx Client Driver +### UcmTcpciCx Client Driver -### Customize and Build the Driver +#### Customize and Build the Driver Edit the driver source files to add any customizations that your hardware may require. For example, the sample is designed against TCPCI Revision 1.0 Version 1.0, but if your hardware conforms to a later version that repurposes register fields that were reserved in version 1.0 you will need to update the alert handler to recognize and clear those bits accordingly. Edit the INF to set the device path and strings to desired custom values. Build your driver in Visual Studio and copy the INF and the SYS file from the build output. -### Install Driver Package +#### 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: @@ -118,15 +130,15 @@ Follow the instructions at the link below to create a driver package in the form 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. -## Update ACPI +### Update ACPI Open sample.asl provided in the UcmTcpciCxClientSample driver sample and modify the following sections as necessary: -- Ensure that the device name matches the device path specified in your INF +- Ensure that the device name matches the device path specified in your INF -- Update the resources section to reflect the actual I2C and Interrupt resources on which your TCPC is connected, default is I2C1 and GPIO5. Specify the I2C address your TCPC uses. +- Update the resources section to reflect the actual I2C and Interrupt resources on which your TCPC is connected, default is I2C1 and GPIO5. Specify the I2C address your TCPC uses. -- Update the connector capabilities section to reflect the capabilities of the connector on your TCPC. +- Update the connector capabilities section to reflect the capabilities of the connector on your TCPC. On a PC with the Windows 10 WDK installed run the following command on your updated ASL file: @@ -138,9 +150,9 @@ This will produce output file ACPITABL.dat. Copy this file to *C:\\Windows\\Syst Once the Raspberry Pi has rebooted, your driver will load on the newly enumerated ACPI device node. -## Testing +### Testing -### USB Type-C Connection Exerciser +#### 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: @@ -152,23 +164,27 @@ The tools and instructions for deploying testing with this device are available Suggested testing with the Connection Exerciser device is randomized connect/disconnect for long periods of time. -## Debugging +### Debugging The sample driver includes standard WDF logging which can be extracted via the kernel debugger with the following debugger command: -> !wdfkd.wdflogdump <driver name> -d +```cmd +!wdfkd.wdflogdump <driver name> -d +``` Other useful driver traces are available from *UcmTcpciCx* and *UcmCx*. Driver logs may also be captured via tracelog which is included in the IoT image. Sample trace capture commands using the GUID included by default in the client sample driver is as follows: -> *Tracelog -start ClientSampleTrace -guid* *\#1dc982f3-068f-4577-bcdf-1bc844e457b2 -flags 0x7fffffff -level 0xff -f clientsampletrace.etl -ft 3* -> -> *<reproduce issue of interest>* -> -> *Tracelog -stop ClientSampleTrace* -> -> *Tracelog -remove ClientSampleTrace* +```cmd +Tracelog -start ClientSampleTrace -guid #1dc982f3-068f-4577-bcdf-1bc844e457b2 -flags 0x7fffffff -level 0xff -f clientsampletrace.etl -ft 3 + +<reproduce issue of interest> + +Tracelog -stop ClientSampleTrace + +Tracelog -remove ClientSampleTrace +``` Other useful driver trace guids: @@ -176,7 +192,7 @@ UcmCx: C5964C90-1824-4835-857A-5E95F8AA33B2 UcmTcpciCx: 8DEAEA72-4C63-49A4-9B8B-25DA24DAE056 -## Resources +### Resources USB Type-C Port Controller Interface Specification (TCPCI), download as part of USB 3.1 Specification: @@ -204,4 +220,4 @@ Microsoft USB Test Tools Tracelog Command Syntax -https://msdn.microsoft.com/en-us/library/windows/hardware/ff553012(v=vs.85).aspx +<https://msdn.microsoft.com/en-us/library/windows/hardware/ff553012(v=vs.85).aspx> diff --git a/usb/UcmTcpciCxClientSample/usb-ucmtcpcicxclientsample.yml b/usb/UcmTcpciCxClientSample/usb-ucmtcpcicxclientsample.yml deleted file mode 100644 index f65285df..00000000 --- a/usb/UcmTcpciCxClientSample/usb-ucmtcpcicxclientsample.yml +++ /dev/null @@ -1,12 +0,0 @@ -### YamlMime:Sample -sample: -- name: UcmTcpciCx Port Controller Client Driver - 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). - generateZip: true - preserveParentHierarchy: true - author: windows-driver-samples - languages: - - cpp - technologies: - - windows - vssolution: /usb/UcmTcpciCxClientSample/UcmTcpciCxClientSample.sln diff --git a/usb/UcmUcsiAcpiSample/README.md b/usb/UcmUcsiAcpiSample/README.md index 592926be..970da954 100644 --- a/usb/UcmUcsiAcpiSample/README.md +++ b/usb/UcmUcsiAcpiSample/README.md @@ -1,3 +1,13 @@ +--- +topic: sample +name: UcmUcsiCx ACPI Client Driver +description: Demonstrates how to create a Windows USB Type-C port controller driver using the USB Connector Manager class extension driver (UcmCx). +languages: + - cpp +products: + - windows +--- + <!--- name: UcmUcsiCx Client Driver platform: KMDF @@ -11,18 +21,19 @@ 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). - ## Note on UCM UCSI -Microsoft already provides an inbox UCSI Class extension (UcmUcsiCx.sys) and ACPI client driver (UcmUcsiAcpiClient.sys) . This UcmUcsi ACPI sample driver is not to a very large extent identical to and functionally replaceable with UcmUcsiAcpiClient.sys. Microsoft recommends that you use this sample to bring up your UcmUcsiCx Client driver that is interfaced over a non ACPI transport. +Microsoft already provides an inbox UCSI Class extension (UcmUcsiCx.sys) and ACPI client driver (UcmUcsiAcpiClient.sys) . This UcmUcsi ACPI sample driver is not to a very large extent identical to and functionally replaceable with UcmUcsiAcpiClient.sys. Microsoft recommends that you use this sample to bring up your UcmUcsiCx Client driver that is interfaced over a non ACPI transport. 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 + +- 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 + This sample is specific to ACPI based UCSI systems. You may choose to structure your driver in a similar way for your own hardware. Understand the requirements and specification of your own system prior to writing a new UcmUcsiCx client driver. In addition to making the logic and functionality suit your specific UCSI transport, you will need to modify the .inf such that it matches your device's information. ### UcmUcsiCx structure @@ -30,22 +41,25 @@ This sample is specific to ACPI based UCSI systems. You may choose to structure In this sample, UCMUCSI-specific interactions are split apart from most of the UCSI-specific operations. #### UcmUcsiCx Interactions + 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. +- 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. + - 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 + The remainder of the files perform operations for UCSI and WDF, non-specific to UCM. - Acpi.cpp - - ACPI method evaluation helper routines. + - ACPI method evaluation helper routines. - Driver.cpp - - Entry point to the driver. Initializes the driver with WDF. + - 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). + - 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. diff --git a/usb/UcmUcsiAcpiSample/usb-ucmucsiacpisample.yml b/usb/UcmUcsiAcpiSample/usb-ucmucsiacpisample.yml deleted file mode 100644 index 0b2b419d..00000000 --- a/usb/UcmUcsiAcpiSample/usb-ucmucsiacpisample.yml +++ /dev/null @@ -1,12 +0,0 @@ -### YamlMime:Sample -sample: -- name: UcmUcsiCx ACPI Client Driver - description: Demonstrates how to create a Windows USB Type-C port controller driver using the USB Connector Manager class extension driver (UcmCx). - generateZip: true - preserveParentHierarchy: true - author: windows-driver-samples - languages: - - cpp - technologies: - - windows - vssolution: /usb/UcmUcsiAcpiSample/UcmUcsiAcpiSample.sln diff --git a/usb/kmdf_enumswitches/README.md b/usb/kmdf_enumswitches/README.md index dda67616..56a07d08 100644 --- a/usb/kmdf_enumswitches/README.md +++ b/usb/kmdf_enumswitches/README.md @@ -1,3 +1,13 @@ +--- +topic: sample +name: Sample KMDF Bus Driver for OSR USB-FX2 +description: Demonstrates how to use KMDF as a bus driver using the OSR USB-FX2 device. +languages: + - cpp +products: + - windows +--- + <!--- name: Sample KMDF Bus Driver for OSR USB-FX2 platform: KMDF @@ -7,51 +17,46 @@ samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=618000 ---> - -Sample KMDF Bus Driver for OSR USB-FX2 -====================================== +# 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>. -Testing the Device ------------------- +## 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. -2. Plug in the OSR USB-FX-2 Learning Kit (must be version 2.00 or later). -3. 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. -4. After the driver installs, verify that the device appears under the **Sample Device** node in Device Manager. -5. 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. -6. 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: +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. -Hardware Overview ------------------ +## Hardware Overview 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 +- 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 - E.g. bit 0x80 is labeled 1 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). +- 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). diff --git a/usb/kmdf_enumswitches/usb-kmdf-enumswitches.yml b/usb/kmdf_enumswitches/usb-kmdf-enumswitches.yml deleted file mode 100644 index 251db0e4..00000000 --- a/usb/kmdf_enumswitches/usb-kmdf-enumswitches.yml +++ /dev/null @@ -1,12 +0,0 @@ -### YamlMime:Sample -sample: -- name: Sample KMDF Bus Driver for OSR USB-FX2 - description: Demonstrates how to use KMDF as a bus driver using the OSR USB-FX2 device. - generateZip: true - preserveParentHierarchy: true - author: windows-driver-samples - languages: - - cpp - technologies: - - windows - vssolution: /usb/kmdf_enumswitches/kmdf_enumswitches.sln diff --git a/usb/kmdf_fx2/README.md b/usb/kmdf_fx2/README.md index dbab6c16..cf4b7c4a 100644 --- a/usb/kmdf_fx2/README.md +++ b/usb/kmdf_fx2/README.md @@ -1,3 +1,13 @@ +--- +topic: sample +name: Sample KMDF Function Driver for OSR USB-FX2 +description: Demonstrates how to use KMDF to perform bulk and interrupt data transfers to a USB device. +languages: + - cpp +products: + - windows +--- + <!--- name: Sample KMDF Function Driver for OSR USB-FX2 platform: KMDF @@ -7,9 +17,7 @@ samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=620313 ---> - -Sample KMDF Function Driver for OSR USB-FX2 -=========================================== +# 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. @@ -18,6 +26,7 @@ In the Windows Driver Kit (WDK), the osrusbfx2 sample demonstrated how to perfor 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. ## Universal Windows Driver Compliant + This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. Overview diff --git a/usb/kmdf_fx2/usb-kmdf-fx2.yml b/usb/kmdf_fx2/usb-kmdf-fx2.yml deleted file mode 100644 index dcbf9021..00000000 --- a/usb/kmdf_fx2/usb-kmdf-fx2.yml +++ /dev/null @@ -1,12 +0,0 @@ -### YamlMime:Sample -sample: -- name: Sample KMDF Function Driver for OSR USB-FX2 - description: Demonstrates how to use KMDF to perform bulk and interrupt data transfers to a USB device. - generateZip: true - preserveParentHierarchy: true - author: windows-driver-samples - languages: - - cpp - technologies: - - windows - vssolution: /usb/kmdf_fx2/kmdf_fx2.sln diff --git a/usb/ufxclientsample/README.md b/usb/ufxclientsample/README.md index 54a2f69f..f7d224aa 100644 --- a/usb/ufxclientsample/README.md +++ b/usb/ufxclientsample/README.md @@ -1,4 +1,14 @@ -<!--- +--- +topic: sample +name: USB Function Client Driver +description: Demonstrates how to create a Windows USB function controller driver using the USB function class extension driver (UFX). +languages: + - cpp +products: + - windows +--- + +<!--- name: USB Function Client Driver platform: KMDF language: cpp @@ -7,32 +17,27 @@ samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=620315 ---> - -USB Function Client Driver -========================== +# 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). 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 +- 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 ------------------------------ +## Operating system requirements -Windows 10 Mobile +Windows 10 Mobile -Customizing the sample for your device --------------------------------------- +## Customizing the sample for your device This sample is not a functional driver. It is a skeleton driver intended to illustrate the general design of a UFX client driver. The sample contains a number of comments prefaced with " #### TODO ", which indicates where code will need to be added to perform the controller operation as described in the comment. -Installation Note ------------------ +## 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. diff --git a/usb/ufxclientsample/usb-ufxclientsample.yml b/usb/ufxclientsample/usb-ufxclientsample.yml deleted file mode 100644 index 54c5eea7..00000000 --- a/usb/ufxclientsample/usb-ufxclientsample.yml +++ /dev/null @@ -1,12 +0,0 @@ -### YamlMime:Sample -sample: -- name: USB Function Client Driver - description: Demonstrates how to create a Windows USB function controller driver using the USB function class extension driver (UFX). - generateZip: true - preserveParentHierarchy: true - author: windows-driver-samples - languages: - - cpp - technologies: - - windows - vssolution: /usb/ufxclientsample/ufxclientsample.sln diff --git a/usb/umdf2_fx2/README.md b/usb/umdf2_fx2/README.md index 4200dc73..dccce968 100644 --- a/usb/umdf2_fx2/README.md +++ b/usb/umdf2_fx2/README.md @@ -1,3 +1,13 @@ +--- +topic: sample +name: Sample Function Driver for OSR USB-FX2 (UMDF Version 2) +description: Demonstrates a UMDF version 2 driver for the OSR USB-FX2 device. +languages: + - cpp +products: + - windows +--- + <!--- name: Sample Function Driver for OSR USB-FX2 (UMDF Version 2) platform: UMDF2 @@ -7,22 +17,17 @@ samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=618003 ---> -Sample Function Driver for OSR USB-FX2 (UMDF Version 2) -======================================================= +# 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. - -Related technologies --------------------- +## Related technologies [User-Mode Driver Framework](http://msdn.microsoft.com/en-us/library/windows/hardware/ff560456) - -Run the sample --------------- +## Run the sample The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. @@ -32,19 +37,18 @@ The process of moving the driver package to the target computer and installing t 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/). -1. Plug in the OSR USB-FX2 board to the target computer. -2. 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**. -3. 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**. -4. On the **Build** menu, choose **Deploy Package** or **Build Solution**. +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](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). -1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\umdf2\_fx2). -2. 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. - -3. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter this command: +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***"** @@ -52,19 +56,16 @@ Before you manually deploy a driver, you must turn on test signing and install a **devcon update osrusbfx2um.inf "USB\\VID\_0547&PID\_1002"** -View the driver for the OSR USB-FX2 board in Device Manager ------------------------------------------------------------ +## View the driver for the OSR USB-FX2 board in Device Manager On the target computer, in your Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate **UMDF 2.0 Sample Driver for OSR Fx2 Learning Kit** (for example, this might be under the **Sample Device** node). In Device Manager, on the **View** menu, choose **Devices by connection**. Locate **UMDF 2.0 Sample Driver for OSR Fx2 Learning Kit** as a child of a USB hub node, which may be contained with the **ACPI x64-based PC** node. -Build the sample using MSBuild ------------------------------- +## Build the sample using MSBuild 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). - diff --git a/usb/umdf2_fx2/usb-umdf2-fx2.yml b/usb/umdf2_fx2/usb-umdf2-fx2.yml deleted file mode 100644 index dd64a682..00000000 --- a/usb/umdf2_fx2/usb-umdf2-fx2.yml +++ /dev/null @@ -1,12 +0,0 @@ -### YamlMime:Sample -sample: -- name: Sample Function Driver for OSR USB-FX2 (UMDF Version 2) - description: Demonstrates a UMDF version 2 driver for the OSR USB-FX2 device. - generateZip: true - preserveParentHierarchy: true - author: windows-driver-samples - languages: - - cpp - technologies: - - windows - vssolution: /usb/umdf2_fx2/umdf2_fx2.sln diff --git a/usb/umdf_filter_kmdf/README.md b/usb/umdf_filter_kmdf/README.md index 5eaf3347..117d32c8 100644 --- a/usb/umdf_filter_kmdf/README.md +++ b/usb/umdf_filter_kmdf/README.md @@ -1,3 +1,13 @@ +--- +topic: sample +name: Sample UMDF Filter above KMDF Function Driver for OSR USB-FX2 (UMDF Version 1) +description: Demonstrates how to load a UMDF filter driver as an upper filter driver above the kmdf_fx2 sample driver. +languages: + - cpp +products: + - windows +--- + <!--- name: Sample UMDF Filter above KMDF Function Driver for OSR USB-FX2 (UMDF Version 1) platform: KMDF @@ -7,64 +17,52 @@ samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=620316 ---> - -Sample UMDF Filter above KMDF Function Driver for OSR USB-FX2 (UMDF Version 1) -============================================================================== +# 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>. -Build the sample ----------------- +## Build the sample The default Solution build configuration is **Debug** and **Win32**. -**To select a configuration and build a driver** - -1. Open the driver project or solution in Visual Studio (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, Debug or Release) and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. -4. From the **Build** menu, click **Build Solution** (Ctrl+Shift+B). +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 --------- +## 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). +- 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. -- 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). -- 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. - -Testing the driver ------------------- +## 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. -Code tour ---------------- - -Folder | Description ------|------------ -usb\umdf_filter_kmdf\kmdf_driver | This directory contains source code for the kmdf_fx2 sample driver. -usb\umdf_filter_kmdf\umdf_filter | This directory contains the UMDF filter driver. - +## Code tour +| Folder | Description | +| --- | --- | +| usb\umdf_filter_kmdf\kmdf_driver | This directory contains source code for the kmdf_fx2 sample driver. | +| usb\umdf_filter_kmdf\umdf_filter | This directory contains the UMDF filter driver. |
\ No newline at end of file diff --git a/usb/umdf_filter_kmdf/usb-umdf-filter-kmdf.yml b/usb/umdf_filter_kmdf/usb-umdf-filter-kmdf.yml deleted file mode 100644 index 00a33b2b..00000000 --- a/usb/umdf_filter_kmdf/usb-umdf-filter-kmdf.yml +++ /dev/null @@ -1,12 +0,0 @@ -### YamlMime:Sample -sample: -- name: Sample UMDF Filter above KMDF Function Driver for OSR USB-FX2 (UMDF Version 1) - description: Demonstrates how to load a UMDF filter driver as an upper filter driver above the kmdf_fx2 sample driver. - generateZip: true - preserveParentHierarchy: true - author: windows-driver-samples - languages: - - cpp - technologies: - - windows - vssolution: /usb/umdf_filter_kmdf/umdf_filter_kmdf.sln diff --git a/usb/umdf_filter_umdf/README.md b/usb/umdf_filter_umdf/README.md index f4d3dc26..da3d05f7 100644 --- a/usb/umdf_filter_umdf/README.md +++ b/usb/umdf_filter_umdf/README.md @@ -1,3 +1,13 @@ +--- +topic: sample +name: Sample UMDF Filter above UMDF Function Driver for OSR USB-FX2 (UMDF Version 1) +description: Demonstrates how to load a UMDF filter driver as an upper filter driver above the umdf_fx2 sample driver. +languages: + - cpp +products: + - windows +--- + <!--- name: Sample UMDF Filter above UMDF Function Driver for OSR USB-FX2 (UMDF Version 1) platform: UMDF1 @@ -7,43 +17,36 @@ samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=618001 ---> - -Sample UMDF Filter above UMDF Function Driver for OSR USB-FX2 (UMDF Version 1) -============================================================================== +# 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>. -### 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). - -### Testing the driver +## 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. -### 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. - +## 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. | diff --git a/usb/umdf_filter_umdf/usb-umdf-filter-umdf.yml b/usb/umdf_filter_umdf/usb-umdf-filter-umdf.yml deleted file mode 100644 index 987a1355..00000000 --- a/usb/umdf_filter_umdf/usb-umdf-filter-umdf.yml +++ /dev/null @@ -1,12 +0,0 @@ -### YamlMime:Sample -sample: -- name: Sample UMDF Filter above UMDF Function Driver for OSR USB-FX2 (UMDF Version 1) - description: Demonstrates how to load a UMDF filter driver as an upper filter driver above the umdf_fx2 sample driver. - generateZip: true - preserveParentHierarchy: true - author: windows-driver-samples - languages: - - cpp - technologies: - - windows - vssolution: /usb/umdf_filter_umdf/umdf_filter_umdf.sln diff --git a/usb/umdf_fx2/README.md b/usb/umdf_fx2/README.md index 4b707cbe..81ba1692 100644 --- a/usb/umdf_fx2/README.md +++ b/usb/umdf_fx2/README.md @@ -1,3 +1,13 @@ +--- +topic: sample +name: Sample UMDF Function Driver for OSR USB-FX2 (UMDF version 1) +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. +languages: + - cpp +products: + - windows +--- + <!--- name: Sample UMDF Function Driver for OSR USB-FX2 (UMDF version 1) platform: UMDF1 @@ -7,9 +17,7 @@ samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=618002 ---> - -Sample UMDF Function Driver for OSR USB-FX2 (UMDF Version 1) -============================================================ +# 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. @@ -17,46 +25,39 @@ The sample can also be used with the CustomDeviceAccess MSDK sample. The sample The osrusbfx2 sample is divided into three 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. - -- **kmdf\_fx2**: This sample is the final version of kernel-mode **wdf\_osrfx2** driver. The sample demonstrates KMDF methods. - -- **umdf\_fx2**: This sample is the final version of the user-mode driver **wdf\_osrfx2**. The sample demonstrates UMDF methods. +- **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. -Build the sample ----------------- +- **kmdf\_fx2**: This sample is the final version of kernel-mode **wdf\_osrfx2** driver. The sample demonstrates KMDF methods. -The default Solution build configuration is Debug and Win32. +- **umdf\_fx2**: This sample is the final version of the user-mode driver **wdf\_osrfx2**. The sample demonstrates UMDF methods. -**To select a configuration and build a driver** +## Build the sample -1. Open the driver project or solution in Visual Studio 2015 (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** and the **Active Solution Platform** (for example, Win32) that correspond to the type of build you are interested in. -4. From the **Build** menu, click **Build Solution** (Ctrl+Shift+B). +The default Solution build configuration is Debug and Win32. -Overview --------- +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). -Here is the overview of the device: +## 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). -- 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). -Testing the driver ------------------- +## 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. @@ -64,14 +65,14 @@ This sample also includes a test application, osrusbfx2.exe, that you can use to 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) +- -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** diff --git a/usb/umdf_fx2/usb-umdf-fx2.yml b/usb/umdf_fx2/usb-umdf-fx2.yml deleted file mode 100644 index e802c6f5..00000000 --- a/usb/umdf_fx2/usb-umdf-fx2.yml +++ /dev/null @@ -1,12 +0,0 @@ -### YamlMime:Sample -sample: -- name: Sample UMDF Function Driver for OSR USB-FX2 (UMDF version 1) - 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. - generateZip: true - preserveParentHierarchy: true - author: windows-driver-samples - languages: - - cpp - technologies: - - windows - vssolution: /usb/umdf_fx2/umdf_fx2.sln diff --git a/usb/usbsamp/README.md b/usb/usbsamp/README.md index 30f46c17..91f950d3 100644 --- a/usb/usbsamp/README.md +++ b/usb/usbsamp/README.md @@ -1,3 +1,13 @@ +--- +topic: sample +name: Usbsamp Generic USB Driver +description: Demonstrates how to perform full speed, high speed, and SuperSpeed transfers to and from bulk and isochronous endpoints of a generic USB device. +languages: + - cpp +products: + - windows +--- + <!--- name: Usbsamp Generic USB Driver platform: KMDF @@ -7,9 +17,7 @@ samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=618938 ---> - -Usbsamp Generic USB Driver -========================== +# 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. @@ -18,46 +26,42 @@ The sample also contains a console test application that initiates bulk (includi For information about USB, see [Universal Serial Bus (USB) Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff538930). ## Universal Windows Driver Compliant + This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP. -Hardware requirements ---------------------- +## Hardware requirements 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). -- Intel 82930 USB test board. +- 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). +- 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. -Set the configuration and platform in Visual Studio ---------------------------------------------------- +## Set the configuration and platform in Visual Studio -In Visual Studio, in Solution Explorer, right click **Solution 'usbsamp' (3 projects)**, and choose **Configuration Manager**. Set the configuration and the platform. Make sure that the configuration and platform are the same for both the driver project and the package project. Do not check the **Deploy** boxes. +In Visual Studio, in Solution Explorer, right click **Solution 'usbsamp' (3 projects)**, and choose **Configuration Manager**. Set the configuration and the platform. Make sure that the configuration and platform are the same for both the driver project and the package project. Do not check the **Deploy** boxes. -Build the sample using Visual Studio ------------------------------------- +## Build the sample using Visual Studio 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). -Locate the built driver ------------------------ +## Locate the built driver In File Explorer, navigate to the folder that contains your built driver package. The location of this folder varies depending on what you set for configuration and platform. For example, if your settings are Debug and x64, the driver is in your solution folder under sys\\driver\\Debug\\usbsamp. The driver folder contains these files: -File | Description ------|------------ -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. +| File | Description | +| --- | --- | +| 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. | -Run the sample --------------- +## Run the sample The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. @@ -67,57 +71,54 @@ The process of moving the driver package to the target computer and installing t 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/). -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**. -2. 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**. -3. On the **Build** menu, choose **Deploy Package** or **Build Solution**. +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](http://msdn.microsoft.com/en-us/library/windows/hardware/dn265571). -1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\Usbsamp). -2. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command: +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** -View the device in Device Manager ---------------------------------- +## View the device in Device Manager On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate the device. For example the device name might be **WDF Sample for FX2 MUTT device** under the**Sample Device** node. -Build the sample using MSBuild ------------------------------- +## Build the sample using MSBuild 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). -Testing the sample ------------------- +## 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. -2. 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. -3. Run the executable on the target machine. +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. +- To view all descriptors and endpoint information, use the following command. **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. +- To send a Read-Write request, use the following command. **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. +- 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** @@ -135,7 +136,7 @@ The sample includes a test application, usbsamp.exe. This console application en 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. +- 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** @@ -149,8 +150,6 @@ The sample includes a test application, usbsamp.exe. This console application en 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: +- 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** - - diff --git a/usb/usbsamp/usb-usbsamp.yml b/usb/usbsamp/usb-usbsamp.yml deleted file mode 100644 index f6c894a8..00000000 --- a/usb/usbsamp/usb-usbsamp.yml +++ /dev/null @@ -1,12 +0,0 @@ -### YamlMime:Sample -sample: -- name: Usbsamp Generic USB Driver - description: Demonstrates how to perform full speed, high speed, and SuperSpeed transfers to and from bulk and isochronous endpoints of a generic USB device. - generateZip: true - preserveParentHierarchy: true - author: windows-driver-samples - languages: - - cpp - technologies: - - windows - vssolution: /usb/usbsamp/usbsamp.sln diff --git a/usb/usbview/README.md b/usb/usbview/README.md index 7321146d..abee2cef 100644 --- a/usb/usbview/README.md +++ b/usb/usbview/README.md @@ -1,3 +1,13 @@ +--- +topic: sample +name: USBView sample application +description: Provides an application that allows you to browse all USB controllers and connected USB devices on your system. +languages: + - cpp +products: + - windows +--- + <!--- name: USBView sample application platform: WDM @@ -7,9 +17,7 @@ samplefwlink: http://go.microsoft.com/fwlink/p/?LinkId=618004 ---> - -USBView sample application -========================== +# 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. @@ -17,59 +25,57 @@ 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**](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) For information about USB, see [Universal Serial Bus (USB) Drivers](http://msdn.microsoft.com/en-us/library/windows/hardware/ff538930). -Run the sample --------------- +## Run the sample ### Local debugging -1. Change **Debugger** to launch to **Local Windows Debugger**. -2. On the **Debug** menu, select **Start debugging** or hit **F5**. +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 If you want to debug the sample app on a remote computer, -1. Copy the executable to a folder on the remote computer. -2. 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). -3. Change **Debugger** to launch to **Remote Windows Debugger**. -4. On the **Debug** menu, select **Start debugging** or hit **F5**. +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. 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. -2. 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. -3. View host controller and port properties on the right pane. +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 ---------- +## Code tour -File manifest | Description ---------------|------------ -Resource.h | ID definitions for GUI controls -Usbdesc.h | USB descriptor type definitions -Usbview.h | Main header file for this sample -Vndrlist.h | List of USB Vendor IDs and vendor names -Debug.c | Assertion routines for the checked build -Devnode.c | Routines for accessing DevNode information -Dispaud.c | Routines for displaying USB audio class device information -Enum.c | Routines for displaying USB device information -Usbview.c | Entry point and GUI handling routines +| File manifest | Description | +| --- | --- | +| Resource.h | ID definitions for GUI controls | +| Usbdesc.h | USB descriptor type definitions | +| Usbview.h | Main header file for this sample | +| Vndrlist.h | List of USB Vendor IDs and vendor names | +| Debug.c | Assertion routines for the checked build | +| Devnode.c | Routines for accessing DevNode information | +| Dispaud.c | Routines for displaying USB audio class device information | +| Enum.c | Routines for displaying USB device information | +| Usbview.c | Entry point and GUI handling routines | The major topics covered in this tour are: -- GUI handling routines -- Device enumeration routines -- Device information display routines +- 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. @@ -77,9 +83,8 @@ 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. -2. 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. -3. 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. +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. - diff --git a/usb/usbview/usb-usbview.yml b/usb/usbview/usb-usbview.yml deleted file mode 100644 index 9cd8ed94..00000000 --- a/usb/usbview/usb-usbview.yml +++ /dev/null @@ -1,12 +0,0 @@ -### YamlMime:Sample -sample: -- name: USBView sample application - description: Provides an application that allows you to browse all USB controllers and connected USB devices on your system. - generateZip: true - preserveParentHierarchy: true - author: windows-driver-samples - languages: - - cpp - technologies: - - windows - vssolution: /usb/usbview/usbview.sln diff --git a/usb/wdf_osrfx2_lab/README.md b/usb/wdf_osrfx2_lab/README.md index 14cb90e8..768e0dc1 100644 --- a/usb/wdf_osrfx2_lab/README.md +++ b/usb/wdf_osrfx2_lab/README.md @@ -1,3 +1,13 @@ +--- +topic: sample +name: WDF Sample Driver Learning Lab for OSR USB-FX2 +description: Contains a console test application and a series of iterative drivers for both KMDF and UMDF version 1. +languages: + - cpp +products: + - windows +--- + <!--- name: WDF Sample Driver Learning Lab for OSR USB-FX2 platform: UMDF1 KMDF @@ -7,9 +17,7 @@ samplefwlink: https://go.microsoft.com/fwlink/?linkid=856746 ---> - -WDF Sample Driver Learning Lab for OSR USB-FX2 -============================================== +# 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. diff --git a/usb/wdf_osrfx2_lab/usb-wdf-osrfx2-lab.yml b/usb/wdf_osrfx2_lab/usb-wdf-osrfx2-lab.yml deleted file mode 100644 index 8604f630..00000000 --- a/usb/wdf_osrfx2_lab/usb-wdf-osrfx2-lab.yml +++ /dev/null @@ -1,12 +0,0 @@ -### YamlMime:Sample -sample: -- name: WDF Sample Driver Learning Lab for OSR USB-FX2 - description: Contains a console test application and a series of iterative drivers for both KMDF and UMDF version 1. - generateZip: true - preserveParentHierarchy: true - author: windows-driver-samples - languages: - - cpp - technologies: - - windows - vssolution: /usb/wdf_osrfx2_lab/wdf_osrfx2_lab.sln |