diff options
Diffstat (limited to 'usb/UcmTcpciCxClientSample/README.md')
| -rw-r--r-- | usb/UcmTcpciCxClientSample/README.md | 105 |
1 files changed, 35 insertions, 70 deletions
diff --git a/usb/UcmTcpciCxClientSample/README.md b/usb/UcmTcpciCxClientSample/README.md index a9a2edba..a59bf2bb 100644 --- a/usb/UcmTcpciCxClientSample/README.md +++ b/usb/UcmTcpciCxClientSample/README.md @@ -10,18 +10,25 @@ products: # 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 @@ -29,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 @@ -39,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 @@ -53,43 +60,27 @@ You will also need the Windows 10 IoT Core Insider Preview builds, the IoT tool #### 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: @@ -115,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. @@ -133,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 - -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: +`asl.exe sample.asl` -<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. @@ -145,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 tools and instructions for deploying testing with this device are available for download on MSDN: +The [MCCI Model 3101 Type-C Connection Exerciser](http://www.mcci.com/mcci-v5/devtools/exerciser-type-c.html) is a tool designed by Microsoft and manufactured by MCCI. -<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. @@ -159,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*. @@ -185,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> +[Tracelog Command Syntax](https://docs.microsoft.com/windows-hardware/drivers/devtest/tracelog-command-syntax) |