Installing and Debugging Drivers with Sharks Cove Hardware development board

  • Article

We asked our talented intern, Steven, to work on several hardware projects this summer and he agreed to share some of his experiences with Windows hardware development using Sharks Cove hardware development board through a series of blog posts. Below is his first blog detailing his experience installing and debugging a driver using Sharks Cove.

Sharks Cove is a hardware development board that you can use to develop hardware and drivers for Windows. The Intel Sharks Cove board supports driver development for devices that use a variety of interfaces, including GPIO, I2C, I2S, UART, SDIO, and USB. You can also use the Sharks Cove board to develop drivers for cameras and touch screens.

For information about the Sharks Cove board, see www.sharkscove.org.  

For details about Windows compatible hardware development boards, see www.msdn.microsoft.com/hardwaredevboard

Here’s the blog in his own words.

 

In this post, I wanted to provide more of a walkthrough on the process of setting up a Sharks Cove for installing and debugging a driver. This post is a direct result of my experience working with the board. Currently, there is a step-by-step guide to setting up and using Sharks Cove on MSDN, so I will not cover everything in detail. Instead, I’d like to look at each of the steps and provide the details of my experience.

Sharks Cove setup

You can absolutely skip this section if you have the board already setup and provisioned or the link above is sufficient. This section is merely to provide clarification from my experience setting up the board. Starting from the top, you will need to gather your hardware. My setup was as follows:

  • A monitor accepting DVI input
  • An HDMI cable and HDMI-DVI adapter
  • A powered USB hub
  • USB Mouse\Keyboard
  • USB Ethernet adapter for network access
  • USB to micro USB cable for kernel debugging

After initial setup, it is possible to get away without a monitor for the Sharks Cove as you can simply remote into the machine from your host machine. The next step involves setting up your host machine. I think the documentation for this section covers it. You simply need Visual Studio Express, which is free, if you don’t already have it. Then, you’ll need to download and install the WDK 8.1 Update. This kit installs all of the necessary files to write drivers for Windows 8.1 Update, 8.1, 8, and 7. The kit is integrated into Visual Studio so you can develop and deploy drivers from within Visual Studio. My experience with this integration was positive. In general, the workflow is very fluid when compared to debugging separately through WinDbg or KD.

Now, we have arrived at setting up the Windows Image and installing it onto the dev board. To me, this step looks overwhelming, but I assure you that it is fairly simple and the documentation has you covered. Once you have successfully created an image, keep it around on a USB in case you ever need to reimage the board. The documentation directs users to download Windows Embedded 8.1 Industry Pro Evaluation. This is a trial OS option for available to developers, but in my experience, the board can run any version of Windows client image you want to install.

Next we need to provision the target system. In this scenario, your host machine is the machine you set up earlier with the WDK and Visual Studio. The target machine is the dev board. The documentation has a link for setting up a target, and that should be enough because provisioning for the Sharks Cove is just like any other target. Here’s a short version of this process, explicitly stating what is happening on each machine.

  • Get the WDK Test Target Setup msi from the host (development) machine and bring it to the target (Sharks Cove) via USB or network if that is setup.
  • Run this on the target.
  • Once that is run, you can finish provisioning in Visual Studio on the host machine. I’d recommend reading through both the provisioning steps and setting up kernel debugging links provided in this section before doing either. That’s because
    you’ll want to select Provision computer and choose debugger settings the first time through so you don’t have to do the process twice.

Attaching a component

The documentation gives an example of the ASL entry for an ADXL345 accelerometer. This is the part that I worked with to test the board, so I’ll talk about using that part through the remainder of this post. To attach the part, I used a breadboard,
but with the proper cables, you can just connect it directly. The pin mappings can be found in this guide (SpbAccelerometer driver cookbook). Once connected, just follow the steps detailed in Step 6 from the Sharks Cove guide we’ve been following. The ASL entry I used during development looked slightly different: Device(ADXL) instead of Device(SPBA) and Name(_HID, “ADXL345”) instead of Name(_HID, “SpbAccelerometer”).  Pay attention to these fields in whatever
version of the ASL entry you see available at the time of reading this. It will be important when installing your driver.

Installing and debugging a driver

Using the sample driver linked at the bottom of the page, you can test your part. After opening the solution, be sure to set the configuration platform in Visual Studio. The instructions are on the sample’s documentation page. Be sure to set it to a
debug configuration or you may encounter signing issues. The simplest method of building and testing the driver is through Visual Studio itself.  Right click the package project and select properties. Under Driver Install > Deployment, enable deployment, set your target machine to Sharks Cove, and select Install and Verify. Click OK, and you can begin debugging by clicking Debug > Start Debugging. This should build the driver, connect to Sharks Cove, copy over the driver files, install it, and finally attach to it for debugging. If the build is successful, you should see various cmd windows popping up and closing on the Sharks Cove. After they are finished, if successful, a Debugger Immediate Window will appear in
Visual Studio already broken into upon driver load. You can then set break points, continue, break, and step through code like normal with Visual Studio.

The alternative to using Visual Studio to deploy and debug is manual deployment and debugging with WinDbg (included in the WDK). Instructions for manual deployment can be found on the sample’s documentation page. Before you install the driver with devcon, you will need to do some setup so that you can attached to the driver on load with WinDbg. First, you need to copy wdfverifier.exe from …\Windows Kits\8.1\Tools\x86\ on the host to your Sharks Cove. This tool will allow you to set WUDFHost.exe, the process that hosts the driver, to break when your driver is loaded. Run it on the Sharks Cove. Go to the Global WDF Settings tab. Where it says, “At [driver load\start], Host Process will wait [0] seconds for user-mode debugger,” set the dropdown to driver load and the time to 10 or more seconds. You should check the kernel debugger checkbox below this if you plan on kernel debugging. When you install your driver, WUDFHost.exe will break upon you driver loading and wait as long as you specified. At this point you need to attach a debugger. For user-mode debugging, you need to run WinDbg as an administrator on the Sharks Cove. Click File > Attach to process. Find WUDFHost.exe and attach. If you have multiple WUDFHost.exe processes, use tasklist /M SpbAccelerometer.dll from the command line to get the PID of the correct WUDFHost.exe. You can now attach a remote WinDbg session to this one from your host machine if you
prefer. To do this simply run .server npipe:pipe=<pipename> in the WinDbg session on your Sharkscovewhere pipename is whatever you prefer. Next, start a WinDbg session on your host and click File > Connect to a Remote Session. You will need to type the output of the .server command after –remote (e.g. npipe:pipe=examplepipe,server=examplehost). Lastly, you can kernel debug through USB if it is setup. Simply start WinDbg on your host and click File > Kernel Debug. Select the COM tab and change the port to comX where X is the number you found for the target when provisioning.Once attached in all cases, you will need the symbols for your driver, the pdb file in the binary output of your Visual Studio project. You can either copy it to your Sharks Cove for local debugging or keep it in place and attach remotely to the Sharks Cove. Whichever method you choose, in WinDbg, on the host unless using the first option, select File > Symbol File Path. Add the full path to the directory containing the pdb file. If you’d like to look at or step through source code, add the full path to the directory containing the source files for the driver in File > Source File Path. Paths are separated by a semicolon. Links to debugging with WinDbg can be found in the Sharks Cove documentation.

Tips and Tricks

I wanted to close with a few things that I did to make my life easier when working with Sharks Cove. There’s nothing fancy here, just stuff that you may or may not find useful or already thought of yourself.

  • Pinning things to the taskbar can save you a bit of time. I pinned cmd as admin to the taskbar. If you don’t know how to make it launch as admin by default, pin it, right click the pinned icon, right click the program name, click properties, click Advanced, and then check Run as Administrator. I also pinned WinDbg. I also pinned File Explorer.
  • Speaking of pinning, I pinned C:\DriverTest to my favorites in File Explorer. This is the folder on the target where your driver is deployed to by the WDK.
  • I adjusted the power options on the Sharks Cove to keep it from going to sleep.
  • Two options if you aren’t kernel debugging and don’t have a second keyboard\mouse setup:
    • Mouse without borders: a program that allows you to use one set of mouse and keyboard over multiple devices
    • Remote desktop (also doesn’t require a second monitor)
    • In WinDbg, you can create workspaces in the File menu. I used these to save the paths to symbols and source file for my driver, so I didn’t have to do it every time.

So there it is, pretty much my knowledge and experience on the Sharks Cove. I hope this is helpful to those getting started, because I want to be able to help those who are having similar experiences as me.