Updates on the SysVAD driver sample (#443)104069

* Update SysVAD public sample.
* Add WaveTest public sample.
* Modify the componentized audio samples to include the addComponent directive.
* Dropped the Phone Audio sample.
* Updated README.md.
* Added explanation for the Phone Audio sample.

1 files changed, 70 insertions, 54 deletions

diff --git a/audio/sysvad/README.md b/audio/sysvad/README.md
index 77de39a3..d5af8044 100644
--- a/audio/sysvad/README.md
+++ b/audio/sysvad/README.md
@@ -11,6 +11,12 @@ urlFragment: sysvad-virtual-audio-device-driver-sample
 
 # SysVAD Virtual Audio Device Driver Sample
 
+## Important note
+
+With the [end of support for Windows 10 Mobile](https://support.microsoft.com/en-us/help/4484693/windows-10-mobile-end-of-support), the Phone Audio sample has been also removed from the SysVAD driver sample.
+
+## Introduction
+
 The Microsoft SysVAD Virtual Audio Device Driver (SYSVAD) shows how to develop a WDM audio driver that exposes support for multiple audio devices.
 
 Some of these audio devices are embedded in the system (for example, speakers, microphone arrays) while others are pluggable (like headphones, Bluetooth headsets etc.). The driver uses WaveRT and audio offloading for rendering devices. The driver uses a "virtual audio device" instead of an actual hardware-based adapter, and highlights the different aspects of the audio offloading WDM audio driver architecture.
@@ -25,19 +31,18 @@ The following table shows the features that are implemented in the various subdi
 
 | Directory | Description |
 | --- | --- |
-| TabletAudioSample | Endpoints that are present in TabletAudioSample driver |
-| PhoneAudioSample | Endpoints that are present in PhoneAudioSample driver |
+| TabletAudioSample | Endpoints that are present in TabletAudioSample driver. |
 | EndpointsCommon | Endpoints that are present in both TabletAudioSample and PhoneAudioSample. It also contains other common code shared by both sample drivers. |
-| SwapAPO | Sample APO that installs onto endpoints exposed by the SysVAD sample driver and swaps the left and right channels |
-| DelayAPO | Sample APO that adds a delay to the input samples |
+| SwapAPO | Sample APO that installs onto endpoints exposed by the SysVAD sample driver and swaps the left and right channels. |
+| DelayAPO | Sample APO that adds a delay to the input samples. |
 | KwsAPO | Sample APO that uses KSPROPERTY_INTERLEAVEDAUDIO_FORMATINFORMATION to determine if the keyword spotter pin is interleaving loopback audio with the microphone audio and identify which channels contain loopback audio. If it is interleaved the APO will strip out the loopback audio and deliver only the microphone audio upstream. Because channel data is removed, the APO negotiates an output format which is different than the input format. |
-| KeywordDetectorAdapter | Sample Keyword Detector Adapter |
+| KeywordDetectorAdapter | Sample Keyword Detector Adapter. |
 
 For more information about the Windows audio engine, see [Hardware-Offloaded Audio Processing](https://docs.microsoft.com/windows-hardware/drivers/audio/hardware-offloaded-audio-processing), and note that audio hardware that is offload-capable replicates the architecture that is presented in the diagram shown in the topic.
 
 ## Build the sample
 
-If you simply want to Build this sample driver and don't intend to run or test it, then you do not need a target computer (also called a test computer). If, however, you would like to deploy, run and test this sample driver, then you need a second computer that will server as your target computer. Instructions are provided in the **Run the sample** section to show you how to set up the target computer - also referred to as *provisioning* a target computer.
+If you simply want to Build this sample driver and don't intend to run or test it, then you do not need a target computer (also called a test computer). If, however, you would like to deploy, run and test this sample driver, then you need a second computer that will serve as your target computer. Instructions are provided in the **Run the sample** section to show you how to set up the target computer - also referred to as *provisioning* a target computer.
 
 Perform the following steps to build this sample driver.
 
@@ -45,11 +50,11 @@ Perform the following steps to build this sample driver.
 
 In Microsoft Visual Studio, Click **File** \> **Open** \> **Project/Solution...** and navigate to the folder that contains the sample files (for example, *C:\Windows-driver-samples\audio\sysvad*). Double-click the *sysvad* solution file.
 
-In Visual Studio locate the Solution Explorer. (If this is not already open, choose **Solution Explorer** from the **View** menu.) In Solution Explorer, you can see one solution that has eight projects.
+In Visual Studio locate the Solution Explorer. (If this is not already open, choose **Solution Explorer** from the **View** menu.) In Solution Explorer, you can see one solution that has seven projects.
 
 ### 2. Set the sample's configuration and platform
 
-In Solution Explorer, right-click **Solution 'sysvad' (8 projects)**, and choose **Configuration Manager**. Make sure that the configuration and platform settings are the same for the eight projects. By default, the configuration is set to **Debug**, and the platform is set to **Win32** for all the projects. If you make any configuration and/or platform changes for one project, you must make the same changes for the remaining three projects.
+In Solution Explorer, right-click **Solution 'sysvad' (7 of 7 projects)**, and choose **Configuration Manager**. Make sure that the configuration and platform settings are the same for the seven projects. By default, the configuration is set to **Debug**, and the platform is set to **Win32** for all the projects. If you make any configuration and/or platform changes for one project, you must make the same changes for all the remaining projects.
 
 ### 3. Build the sample using Visual Studio
 
@@ -65,97 +70,108 @@ The package should contain these files:
 
 | File | Description |
 | --- | --- |
-| TabletAudioSample.sys OR PhoneAudioSample.sys| The driver file |
-| SwapAPO.dll | The swap APO |
-| DelayAPO.dll | The delay APO |
-| KWSApo.dll | The KWS APO |
+| TabletAudioSample.sys | The driver file. |
+| DelayAPO.dll | The delay APO. |
+| KeywordDetectorContosoAdapter.dll | Sample Keyword detector adapter. |
+| KWSApo.dll | The KWS APO. |
+| SwapAPO.dll | The swap APO. |
 | sysvad.cat | A signed catalog file, which serves as the signature for the entire package. |
-| TabletAudioSample.inf | An information (INF) file that contains information needed to install the driver. |
-| PhoneAudioSample.inf | An information (INF) file that contains information needed to install the driver. |
-| KeywordDetectorContosoAdapter.dll | Sample Keyword detector adapter |
+| ComponentizedApoSample.inf | A componentized information (INF) file that installs an APO device. |
+| ComponentizedAudioSample.inf | A componentized information (INF) file that contains information needed to install the Tablet Audio Sample driver. |
+| ComponentizedAudioSampleExtension.inf | An extension information (INF) file that extends the Tablet Audio Sample driver functionality by associating an APO device to it. |
+| TabletAudioSample.inf | A non-componentized information (INF) file that contains information needed to install the driver. |
+
+For more information on extension INF files, see [Using an extension INF file](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/using-an-extension-inf-file).
 
 ## 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 the computer on which you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*.
 
-The process of moving the driver package to the target computer and installing the driver is called *deploying* the driver. You can deploy the sample driver, TabletAudioSample or PhoneAudioSample, automatically or manually.
+The process of moving the driver package to the target computer and installing the driver is called *deploying* the driver. You can deploy the TabletAudioSample sample driver automatically or manually.
 
-### Automatic deployment
+### Prepare the target computer
 
-Before you automatically deploy a driver, you must provision the target computer. Verify that the target computer has an ethernet cable connecting it to your local network, and that your host and target computers can ping each other. Then perform the following steps to prepare your host and target computers.
+First of all, install the latest [Windows Driver Kit](https://docs.microsoft.com/windows-hardware/drivers/download-the-wdk) (WDK) on the target computer.
 
-#### 1. Provision the target computer
+Before you manually deploy a driver, you must prepare the target computer by turning on test signing and by installing a certificate. You also need to locate the DevCon tool in your WDK installation. After that you're ready to run the built driver sample.
 
-On the target computer install the latest [Windows Driver Kit](https://docs.microsoft.com/windows-hardware/drivers/download-the-wdk) (WDK), and then when the installation is completed, navigate to the following folder:
+Open a Command Prompt window as Administrator. Then enter the following command:
 
-\\Program Files (x86)\\Windows Kits\\10\\Remote\\<*architecture*>\\
+`bcdedit /set TESTSIGNING ON`
 
-For example, if your target computer is an x64 machine, you would navigate to:
+and reboot the target computer.
 
-\\Program Files (x86)\\Windows Kits\\10\\Remote\\x64\\
+[!IMPORTANT]
+Before using BCDEdit to change boot information you may need to temporarily suspend Windows security features such as BitLocker and Secure Boot on the test PC.
 
-Double-click the *WDK Test Target Setup x64-x64\_en-us.msi* file to run it. This program prepares the target computer for provisioning.
+Re-enable these security features when testing is complete and appropriately manage the test PC, when the security features are disabled.
 
-On the host computer, in Visual Studio click **Driver** \> **Test** \> **Configure Computers...**, and then click **Add a new computer**.
+After rebooting, navigate to the Tools folder in your WDK installation and locate the DevCon tool. For example, look in the following folder:
 
-Type the name of the target computer, select **Provision computer and choose debugger settings**, and click **Next**. In the next window, verify that the **Connection Type** is set to Network. Leave the other (default) settings as they are, and click **Next**. For more information about the settings in this window, see [Setting Up Debugging](https://docs.microsoft.com/windows-hardware/drivers/debugger/getting-set-up-for-debugging).
+C:\\Program Files (x86)\\Windows Kits\\10\\Tools\\x64\\devcon.exe
 
-#### 2. Prepare the host computer
+Copy *devcon.exe* to a folder on the target computer where it is easier to find. For example, create a *C:\\Tools* folder and copy *devcon.exe* to that folder.
 
-If you haven't already done so, then preform the steps in the **Build the sample** section, to build the sample driver.
+Create a folder on the target for the built driver package (for example, *C:\\SysvadDriver*). Copy all the files from the built driver package on the host computer and save them to the folder that you created on the target computer.
 
-In Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties** \> **Driver Install** \> **Deployment**.
+Create a folder on the target computer for the certificate created by the build process. For example, you could create a folder named *C:\\Certificates* on the target computer, and then copy *package.cer* to it from the host computer. You can find this certificate in the same folder on the host computer, as the *package* folder that contains the built driver files. On the target computer, right-click the certificate file, and click **Install**, then follow the prompts to install the test certificate.
 
-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 **Hardware ID Driver Update**, and enter *ROOT\Sysvad_TabletAudioSample* for the hardware ID. Click **OK**.
+If you need more detailed instructions for setting up the target computer, see [Preparing a Computer for Manual Driver Deployment](https://docs.microsoft.com/windows-hardware/drivers/develop/preparing-a-computer-for-manual-driver-deployment).
 
-On the **Build** menu, choose **Deploy Package** or **Build Solution**. This will deploy the sample driver to your target computer.
+#### A note on signatures
 
-On the target computer, perform the steps in the **Test the sample** section to test the sample driver.
+Since most of these binary files are executed in kernel mode, it is important that they are signed and, optionally, to have a kernel debugger attached.
 
-### Manual deployment
+Without any signature or kernel debugger, the driver will not be installed in the target computer. With a kernel debugger attached, the driver can be installed and the driver files (.sys extension) would be loaded, but any user mode files (.dll files) will not be loaded.
 
-Before you manually deploy a driver, you must prepare the target computer by turning on test signing and by installing a certificate. You also need to locate the DevCon tool in your WDK installation. After that you're ready to run the built driver sample.
+The only way of installing and executing the whole driver sample is to have all the files (.sys, .dll and .cat) signed with a trusted certificate. This will allow the entire driver to be loaded even without a kernel debugger attached.
 
-#### 1. Prepare the target computer
+For more information on the subject, see [Driver signing](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/driver-signing).
 
-Open a Command Prompt window as Administrator. Then enter the following command:
+### Install the driver
 
-`bcdedit /set TESTSIGNING ON`
+#### Componentized INF files
 
-Reboot the target computer. Then navigate to the Tools folder in your WDK installation and locate the DevCon tool. For example, look in the following folder:
+The TabletAudioSample driver package contains a sample driver, an extension sample and an APO software component. The following instructions show you how to install and test the sample driver, the APO component and then the extension to apply the software component to the driver.
 
-C:\\Program Files (x86)\\Windows Kits\\10\\Tools\\x64\\devcon.exe
+First, the base INF, *ComponentizedAudioSample.inf*, has to be installed. To install it, open a Command Prompt window as administrator on the target computer, then navigate to your driver package folder and enter the following command:
 
-Copy *devcon.exe* to a folder on the target computer where it is easier to find. For example, create a *C:\\Tools* folder and copy *devcon.exe* to that folder.
+`devcon install ComponentizedAudioSample.inf Root\Sysvad_ComponentizedAudioSample`
 
-Create a folder on the target for the built driver package (for example, *C:\\SysvadDriver*). Copy all the files from the built driver package on the host computer and save them to the folder that you created on the target computer.
+If you get an error message about *devcon* not being recognized, try adding the path to the *devcon* tool. For example, if you copied it to a folder called *C:\\Tools*, then try using the following command:
 
-Create a folder on the target computer for the certificate created by the build process. For example, you could create a folder named *C:\\Certificates* on the target computer, and then copy *package.cer* to it from the host computer. You can find this certificate in the same folder on the host computer, as the *package* folder that contains the built driver files. On the target computer, right-click the certificate file, and click **Install**, then follow the prompts to install the test certificate.
+`C:\\tools\\devcon install ComponentizedAudioSample.inf Root\Sysvad_ComponentizedAudioSample`
 
-If you need more detailed instructions for setting up the target computer, see [Preparing a Computer for Manual Driver Deployment](https://docs.microsoft.com/windows-hardware/drivers/develop/preparing-a-computer-for-manual-driver-deployment).
+This installs the base Tablet Audio Sample driver with a hardware ID of "Root\Sysvad_ComponentizedAudioSample".
 
-#### 2. Install the driver
+Then, either the extension INF (*ComponentizedAudioSampleExtension.inf*) or the APO INF (*ComponentizedApoSample.inf*) can be installed.
 
-The TabletAudioSample or PhoneAudioSample driver package contains a sample driver and 2 driver extension samples. The following instructions show you how to install and test the sample driver.
+If the extension INF is installed first, it will create a new component called *Audio Proxy APO Sample*. Until the APO is installed, this component will appear in Device Manager under the section of Software Components, because it does not have a driver attached yet. The driver is attached by installing the APO INF.
 
-The INF file required for installing this driver is *TabletAudioSample.inf*.
+If the APO is installed first, it will install a driver, but it will not create a device, so the APO will not be visible in Device Manager until the extension INF creates a software component that will then have the APO driver installed.
 
-On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command:
+Both extension and APO INFs can be installed by right-clicking on any of the files and selecting "install" from the menu.
 
-`devcon dp_add TabletAudioSample.inf`
+Once the three componentized INF files are installed, an APO device should appear in Device Manager and the *Microsoft Virtual Audio Device (WDM) - Tablet Audio Sample* device should now be named *SYSVAD (with APO Extensions)*.
 
-If you get an error message about *devcon* not being recognized, try adding the path to the *devcon* tool. For example, if you copied it to a folder called *C:\\Tools*, then try using the following command:
+For more detailed instructions, see [Provision a computer for driver deployment and testing](https://docs.microsoft.com/windows-hardware/drivers/gettingstarted/provision-a-target-computer-wdk-8-1).
 
-`C:\\tools\\devcon dp_add TabletAudioSample.inf`
+#### Single INF files
 
-For more detailed instructions, see [Provision a computer for driver deployment and testing](https://docs.microsoft.com/windows-hardware/drivers/gettingstarted/provision-a-target-computer-wdk-8-1).
+TabletAudioSample also contains an INF file, tabletaudiosample.inf, which install the sample driver using a single INF file.
+
+Componentized driver packages are required since Windows 10 1809 release. However, for backward compatibility, instructions on how to install the TabletAudioSample.inf are provided below.
+
+On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command:
+
+`devcon dp_add TabletAudioSample.inf`
 
 After successfully installing the sample driver, you're now ready to test it.
 
 ### Test the driver
 
-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 *Microsoft Virtual Audio Device (WDM) - Tablet Audio Sample*. This is typically under the **Sound, video and game controllers** node.
+On the target computer, in a Command Prompt window, enter **devmgmt.msc** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate *SYSVAD (with APO Extensions)*. This is typically under the **Sound, video and game controllers** node.
 
-On the target computer, open Control Panel and navigate to **Hardware and Sound** \> **Manage audio devices**. In the Sound dialog box, select the speaker icon labeled as *Microsoft Virtual Audio Device (WDM) - Tablet Audio Sample*, then click **Set Default**, but do not click **OK**. This will keep the Sound dialog box open.
+On the target computer, open Control Panel and navigate to **Hardware and Sound** \> **Manage audio devices**. In the Sound dialog box, select the speaker icon labeled as *SYSVAD (with APO Extensions)*, then click **Set Default**, but do not click **OK**. This will keep the Sound dialog box open.
 
-Locate an MP3 or other audio file on the target computer and double-click to play it. Then in the Sound dialog box, verify that there is activity in the volume level indicator associated with the *Microsoft Virtual Audio Device (WDM) - Tablet Audio Sample* driver.
+Locate an MP3 or other audio file on the target computer and double-click to play it. Then in the Sound dialog box, verify that there is activity in the volume level indicator associated with the *SYSVAD (with APO Extensions)* driver.