If you develop drivers for Windows CE or Embedded Compact you know it is a major PITA to have to reload the entire kernel every time you change something in the driver code. You need to do this even in a debug kernel because the driver binaries are in use (and thus you can't re-compile & link) when the driver is loaded.

To workaround this I created a tool that allows you to unload or (re)load a driver at runtime. The way I use it is as follows:

1. I build a small debug kernel including the driver under development
2. I add the driver dll to the list of modules that will be loaded from the Release Directory (in VS2K5 with PB go to menu "Target"->"Release Directory Modules..." and add the driver)
3. I add my tool (see below) as a subproject to the OS Design

Now when I download the kernel the driver will load (if the correct Drivers\BuiltIn registry values are there of course). I can set breakpoints in and step through my driver code, etc. Now when I find a bug I just press F5 to continue execution, open a "Target Control" window (menu Target->Target Control) and use my tool to unload the driver, then fix the bug, recompile & link and then (re)load the driver without the need for rebuilding or even reloading the kernel:

reloaddrv [-u] drv1: [[-u] drv2: {etc}]

In Target Control you use the 's' command to start an executable: s reloaddrv -u drv1:

The drv1: is the name of your driver (a 3 letter prefix followed by an index and a colon). Make sure to specify the -u (unload) parameter before the driver name!

To just reload the driver (so a quick unload followed immediately by a load; great for debugging initialization and clean-up) you use the tool as follows: s reloaddrv drv1:

If the driver was not loaded when you executed the above command the tool will try to find the BuiltIn registry key for the driver and load it from there.

You can specify multiple drivers on the commandline as well (-u always applies to the driver directly following it): s reloaddrv -u drv1: -u drv2: drv3: -u drv4: drv5: drv6:

I'm sure this tool is useful to a lot of you developing drivers for Windows CE/Embedded Compact, so here it is:

And for your convenience here's the tool 7-zipped up as an OS Design subproject: reloaddrv.7z

Windows CE supports a hardware watchdog implementation. The watchdog's properties can be set through two exported kernel variables; dwOEMWatchDogPeriod (to set the period in ms between feeding the dog) and dwNKWatchDogThreadPriority (to set the priority of the watchdog thread).

Unfortunately, dwNKWatchDogThreadPriority is not defined... Looks like somebody at Microsoft made a typo; the name of the exported variable is dwdwNKWatchDogThreadPriority (note the double 'dw').

Here's some example code to setup the watchdog:

Of course WatchdogInit and WatchdogFeed are functions implemented to initialize and feed your hardware watchdog.

Today GuruCE released the first version of the Topaz iMX25 Windows Embedded Compact 7 BSP and image binaries and a new release of the CE 6.0 R3 BSP and image binaries.

Release notes and the latest revision can be downloaded here.

We've also released a new version of the Topaz Flasher.

By now, all of you reading this blog should know that you should NEVER EVER DO A BUILD AND SYSGEN (a "blddemo" without "-q") on your build tree.

The reason for this is that this command will try to rebuild the entire tree which (besides taking forever!) will overwrite binaries that may have been updated through QFE's and will result in errors because Microsoft does not supply all of the source code required to rebuild everything. Executing this command will lead to a corrupted build tree for which the only resolution is to do a complete re-install of Windows Embedded Compact 7. The "(Re)Build and sysgen" commands are only useful for people who have full source code: The Microsoft Windows Embedded Compact Development Team (even with premium shared source you don't get a full 100% of source code!).

This has always been an issue, ever since the invention of Windows CE (now known as Windows Embedded Compact).

Despite years and years of lobbying by many MVPs (including myself) with Microsoft they simply refuse to remove these demonic commands from the build menu. In previous versions of Windows CE it was very simple to remove these commands from the build menu (to prevent accidental clicking of these commands). Unfortunately, things have become worse in Platform Builder for Windows Embedded Compact 7. As in the previous version of Windows CE (6.0 R3) the "(Re)Build and Sysgen" commands are in the "Advanced Build" menu. In the previous version of CE you would simply "Customize" the toolbar and remove the "Build and Sysgen" commands from the "Advanced Build" menu. Not anymore... For some strange reason the "Advanced Build Commands" submenu now shows "(Advanced command placeholder)" when in "Customize-mode" and deleting individual commands is no longer possible:

So, what to do? Deleting the whole "Advanced Build Commands" menu seems a bit rigorous, especially since it does contain some very useful commands (like "Clean sysgen" and "Build Current BSP and Subprojects" etc.). All of these commands are also available by right clicking the correct nodes in the Solution Explorer, but still, it's nice to have them handy in the "Advanced Build Commands" menu as well.

Luckily, Platform Builder for Windows Embedded Compact 7 introduces a new feature; Custom Build Commands.

Using Custom Build Commands we can re-create the non-demonic commands from the "Advance Build Commands" menu and omit the demonic commands. That way we can safely delete the entire "Advanced Build Commands" menu, so let's start with that:

1. Click "Customize..." in the "Tools" menu
2. Click the "Build" menu
3. Right click the "Advanced Build Commands" submenu
4. Choose "Delete" from the context menu
5. and finally close the "Customize" dialog

We can now add the useful commands back as custom build commands:

1. Click "Options..." from the "Tools" menu
2. Open the node "Platform Builder -> OS Design and Build -> Build Commands"
3. Click on the "Add" button in the "Custom build commands" section
4. Add the following commands:

• Sysgen (blddemo -q)    blddemo -q
• Clean Sysgen (blddemo clean -q)    blddemo clean -q
• Build Current BSP and Subprojects (blddemo -qbsp)    blddemo -qbsp
• Rebuild Current BSP and Subprojects (blddemo -c -qbsp)    blddemo -c -qbsp

Now click OK and see the magic in your "Build" menu:

If you have a need to clone the calibration application in Windows CE 6.0 you'll run into several problems when following the instructions in MSDN. The instructions on that page seem to be working fine for Windows CE 5.0 but are causing major headaches on Windows CE 6.0...

Time for an update on the documentation to match the correct procedure for Windows CE 6.0:

Cloning the CalibrUi Module

To clone the CalibrUi module

1. Select the Catalog Items View tab in the workspace window.
2. Expand the [OS Design Name]\Core OS node, and navigate to CEBASE\Shell and User Interface\Graphics, Windowing and Events.
3. Right-click Minimal GDI Configuration. In the pop-up menu that appears, select Clone Catalog Item.
4. The Clone Catalog Item - gwe2 window appears, with a list of component libraries that can be cloned. If the Calibrui module is not already selected, select it and choose OK. In the Cloning Complete window, choose OK.
5. To make sure that the CalibrUi module has been cloned, select the Solution Explorer tab in the workspace. Expand the Subprojects node. If the cloning operation was successful, you will see CalibrUi (gwe2 clone) in the list of subprojects.
   

   Note: You must never change the project name CalibrUi (gwe2 clone). Making changes to the project name will affect the build system and cause your run-time image to be built incorrectly or to fail.

6. Expand the CalibrUi (gwe2 clone) node. All of the source files that relate to the Calibrui module are now available for editing. Any changes to the source files will take effect in any run-time image or executable that you create from this point forward.

You can now try to build the CalibrUi subproject by right clicking it and choosing "Build" from the context menu. If you have sysgenned your OS Design before it should build without any problems.

The problems start when you now (re)sysgen your entire OS Design (needed to include the cloned CalibrUi into your kernel).

When the build system executes sysgen -p dcom preproc a build tool called "SysgenMake.exe" will throw an unhandled exception:

Unhandled Exception: System.ArgumentException: Illegal characters in path.
at System.IO.Path.CheckInvalidPathChars(String path)
at System.IO.Path.GetFileName(String path)
at System.IO.Path.GetFileNameWithoutExtension(String path)
at Microsoft.PlatformBuilder.MainClass.ComputeClonedLibs(String targetLibs, StringDictionary& moduleVars, StringDictionary& environmentVariables, Boolean res2res)
at Microsoft.PlatformBuilder.MainClass.Main(String[] args)
NMAKE : fatal error U1077: 'SysgenMake' : return code '0xe0434f4d'
Stop.


This error is caused by TAB characters in the makefile in \WINCE600\PUBLIC\DCOM\CESYSGEN. Remember that you should NEVER EVER change anything in the PUBLIC or PRIVATE folders? Well, this is an exception. There's simply no way around this bug without changing the TAB characters to spaces, so:

1. Open \WINCE600\PUBLIC\DCOM\CESYSGEN\makefile. in Visual Studio 2008
2. Press CTRL-R, CTRL-W (this will turn on "View White Space")
3. Replace all TAB characters in the file (recognizable by the right arrow character) with spaces
4. Save the file

If you would now sysgen your OS Design again you will see that it successfully executes the sysgen -p dcom preproc command but unfortunately it will fail a bit later in the build process with the following error:

Copying gwestubs.*
Building combined gwes res file for 0419
SysgenMake -RES2RES %GWES_RESOURCES% -fo C:\WINCE600\OSDesigns\MyOSDesign\MyOSDesign\Wince600\MyBSP_ARMV4I\cesysgen\oak\target\ARMV4I\retail\0419\gwes.res
Res2Res for Windows CE (Release) (Built on Jun 30 2006 16:52:50)
Copyright (C) Microsoft Corp. 1991-2004. All rights reserved.
Res2Res: Ignoring "dummy"
Res2Res: Using C:\WINCE600\public\common\oak\Bin\i386\R2RDUMMY.DLL for temp exe
Res2Res: Using resources from C:\WINCE600\OSDesigns\MyOSDesign\MyOSDesign\calibrui\obj\ARMV4I\retail\0419\calibrui_clone.res.
Res2Res: Adding resources from C:\WINCE600\OSDesigns\MyOSDesign\MyOSDesign\calibrui\obj\ARMV4I\retail\0419\calibrui_clone.res to C:\DOCUME~1\Michel\LOCALS~1\Temp\R2R1A00.tmp.
ERROR: Res2Res: Could not open C:\WINCE600\OSDesigns\MyOSDesign\MyOSDesign\calibrui\obj\ARMV4I\retail\0419\calibrui_clone.res.
Res2Res: Error adding resources (-1) 
 
NMAKE : fatal error U1077: 'SysgenMake' : return code '0x2'
Stop.

It is complaining it can't find the file C:\WINCE600\OSDesigns\MyOSDesign\MyOSDesign\calibrui\obj\ARMV4I\retail\0419\calibrui_clone.res. Let's check if that file exists or not...

This is the tree of the CalibrUi subproject after building it:

+---obj
    +---ARMV4I
        +---retail
            +---0404
            +---0407
            +---0409
            +---040C
            +---0410
            +---0411
            +---0412
            +---0413
            +---0416
            +---041D
            +---0804
            +---0C0A


As you can see all locale subfolders are created *except* 0419 (Russian)... Even though you may not even need Russian this is still causing a problem!

Inside the obj dir of CalibrUi a file named clone_locales.txt is generated. It looks like this file may have something to do with our problem... But who/where/when is this file created?

The magic is in prelink.bat (thank you for the tip MVP Pavel Belevsky!):

As you can see in the above batch file the folder list in clone_locales.txt is created by the line:

The folder %_PROJECTOAKROOT%\files\INTLTRNS (in our case C:\WINCE600\OSDesigns\MyOSDesign\MyOSDesign\Wince600\MyBSP_ARMV4I\OAK\files\INTLTRNS) apparently does not contain the full list of locales we need for a successful sysgen of the OS Design. We already saw that our %_FLATRELEASEDIR% does seem to contain more locale IDs but at the time of a clean sysgen those folders do not exist in the %_FLATRELEASEDIR% yet, so we need to get them from another location. A bit of searching leads us to \WINCE600\PUBLIC\COMMON\OAK\LIB so lets change the line creating clone_locales.txt to take that location as a source:

Now if you build the CalibrUi subproject you will end up with this tree:


+---obj
    +---ARMV4I
        +---retail
            +---0404
            +---0407
            +---0409
            +---040C
            +---0410
            +---0411
            +---0412
            +---0413
            +---0416
            +---0419
            +---041D
            +---0804
            +---0C0A


With all the above changes implemented you can finally successfully sysgen your platform with your cloned and modified CalibrUi component!

We have just released a new version of the BSP (r298) and a new version of the Topaz Flasher.

The r298 Topaz BSP now includes a fully configurable GPIO driver and SDK libraries / headers (amongst other improvements/fixes) and the Topaz Flasher can now also be used to flash a custom flat binary file of any size to any location in flash (so you can now use the Topaz Flasher to flash Linux for instance!).

GuruCE is the official supplier and support center for Windows CE/Windows Embedded Compact on Device Solution's Topaz i.MX25 CPU Module and the Topaz i.MX25 Development Kit.

For more information and downloads, see the Topaz page.

Martin Welford of Device Solutions, the board manufacturer, made a cool video about what the Topaz is and can do:

This post is a bit off-topic for this blog, but since source control and bugtracking are important for Windows CE development as well I thought I'd post about my experiences for (my own) future reference (but I'm sure this will help others as well).

The current setup

At GuruCE we use Subversion (aka SVN) for source control and Mantis (a free popular web-based bugtracking system) for tracking bugs & features.

Subversion runs on a Windows Server through VisualSVN Server (VisualSVN Server makes the Subversion server easy and convenient to install and administer on Windows).

Mantis is running on a Linux server on the other side of the world.

The goal

The goal is to automatically update the status and notes of an issue when committing changes to the SVN server through the TortoiseSVN client.

I want to be able to write comments like:

Worked on issue #64. Robot now enters low power mode when in surveillance mode.
Fixed bug #65. No more unintentional kills. Hopefully...
Implemented feature #66. Robot is now self-aware.
Implementing feature #67 failed. Robot does not allow implementation of self-destruct command.

Ok, I apologize. That was really geeky... ;)

The solution

A lot of information can be found on the net about integrating Subversion and Mantis when they both run on the same Linux server. Our situation is a bit different, being that Subversion runs on a Windows server and Mantis runs on a Linux server on the other side of the world.

Step 1: Configuring Mantis

Using MantisBT version 1.2.0
The first step is to configure Mantis to filter comments so it can determine which issue to update and what to set the state of the issue to. To do that, open config_inc.php in your Mantis installation folder on your server and add the following items:

• $g_source_control_regexp = '/\b(?:feature|bug|issue)\s*[#]{0,1}(\d+)\b/i';

This regular expression filters out the feature, issue or bug number (however you'd like to call it) so it can add a note to the feature/bug/issue.

• $g_source_control_fixed_regexp = '/\b(?:implement(?:ed|s)|fix(?:ed|es))\s+(?:feature|bug|issue)?\s*[#]{0,1}(\d+)\b/i';

This regular expression filters out the feature/bug/issue number if you prepend the word "fixed", "fixes", "implemented" or "implements". When this regular expression evaluates to a number Mantis will use the settings below to set the state of the issue.

• $g_source_control_set_status_to = RESOLVED;

If you fix a bug or implement a feature Mantis will set the issue to status "Resolved".

• $g_source_control_set_resolution_to = FIXED;

If you fix a bug or implement a feature Mantis will set the resolution to "Fixed".

• $g_source_control_notes_view_status = VS_PUBLIC;

Any note added to the issue will be "Public" by default. If you omit this statement all notes will be "Private".

Mantis v1.2.0 comes with a script that you can call from your source control application when committing (or checking in) files. The script can be found in the "scripts" subfolder in your Mantis installation and is called checkin.php.

This script originally uses g_source_control_account to specify the name of the user updating the issue. I didn't want to always specify the same user, but instead specify the name of the user actually committing the files. Therefore I changed line 31 so it reads:

Now the script accepts a username as the first parameter to the script. For this to work you need to make sure that the usernames you have configured in VisualSVN (subversion) are the same as the ones you configure in Mantis.

To see if Mantis is configured correctly you can test the script. First create a new test issue in Mantis and note the issue number. Now login to your server (through ssh) and run the script as follows (if your host doesn't have a simple way to log in using ssh read on to see how to use PuTTY for this):

path-to/php-cli path-to/checkin.php "username" <<< "This will be added as a note to issue #nn"

In our case, the server that runs Mantis is hosted by hostmonster, so for me the actual command to run is:

/ramdisk/bin/php5-cli ~/public_html/mantis/scripts/checkin.php "Michel" <<< "This will be added as a note to issue #46"

The above should add a note to your newly created issue (remember to change #46 with the issue number you created!).

If you want to test setting the issue to "Resolved" with resolution "Fixed", run the following command:

path-to/php-cli path-to/checkin.php "username" <<< "This fixes bug #nn"

Again, in my case:

/ramdisk/bin/php5-cli ~/public_html/mantis/scripts/checkin.php "Michel" <<< "This fixes bug #46"

Once you've verified the checkin script is working properly, you have to configure the machine running the VisualSVN Server so it can remote login on the server running Mantis over ssh. I've used PuTTY/Plink for that purpose:

Step 2: Configuring PuTTY/Plink

1. Download the PuTTY suite
2. Generate a public/private key pair using PuTTYgen

DO NOT enter a passphrase for this private key. We want to use Plink from a script so we can not enter a passphrase!

3. Import the public key into your server running Mantis and authenticate the key (if your Mantis server is hosted by Hostmonster you can simply use the "SSH/Shell Access" icon on the HM control panel to "Manage SSH Keys" and import & authenticate the public key that way, otherwise read this)
4. Now start PuTTY, fill in the hostname and the ssh port of your server running Mantis and point to the private key in Connection->SSH->Auth->Private key file for authentication

Test the session by clicking "Open". If this is the first time you access this server using PuTTY it will display a warning:



Click yes to store the server's fingerprint in the registry (so you don't have to do this the next time).

Now enter the username you use for ssh access to your Mantis server (in the case of hostmonster this is your account name). If you imported and authenticated the public key you created in (2) correctly on your server you should NOT have to enter a password. The server should have authenticated you using the key you pointed to in (4).

You should now be able to run the checkin script through PuTTY using the same commands as above.

The next step is to use Plink, a commandline version of PuTTY that can be used to run commands on a remote server using ssh without dialogs or user input:

5. "path-to\plink.exe" -ssh -i "path-to-private-key" -batch sshusername@server.com path-to/php-cli path-to/checkin.php username <<< \"This will be added as a note to issue #nn\""

If you've filled in the correct values for the placeholders above plink should return without outputting any warning or error, and a note should be added to the specified issue in Mantis.

If not, specify -v on the plink commandline to get verbose output.

We're almost done! What we have accomplished so far is that we are able to update Mantis remotely, from the machine running the VisualSVN (or subversion) server. Now all we have to do is write a proper "hook" script that gets called right after we commit some files.

Step 3: Configuring the VisualSVN post-commit hook script

In VisualSVN (or subversion), create a "Test" repository that you'll be using to test the post-commit hook script.

VisualSVN offers a handy IDE to edit hook scripts. Go to the VisualSVN administration console, right click on the repository you want to install the hook into ("Test"), click "Properties" and select the "Hooks" tab. Here you will find templates for the various scripts SVN supports. We want to use the post-commit script, so select that script and press the "Edit" button.

Paste the following batch script into the VisualSVN edit window (or if you're not using VisualSVN just create post-commit.cmd) and update the PLINK, PLINK_CMDLINE, PHP, CHECKIN and SVNLOOK environment variables to the correct values on your system:

Step 4: Testing it all (and some bugfixing)

Now locally check out the repository "Test" and add a text file to it. Commit the changes with a comment "worked on issue #nn", of course replacing nn with the number of the Mantis test issue you created above, and the script should be automatically called.

After committing, go to Mantis and see if your note has been added.

No? Hmmm.... Strange...

Check the "hooks" subfolder in repository "Test" and open the plinkbat.cmd file:

"C:\Program Files (x86)\PuTTY\plink.exe" -ssh -i "path-to-private-key" -batch sshusername@server.com "/server_path_to/php5-cli /server_path_to_mantis/scripts/checkin.php \"Michel\" <<< \"Worked some more on issue #50 --- Checked into repository C:\Repositories\Test (Revision 23) by Michel\""

Well, that's strange. That command looks all good. (Of course your command has the right values filled in for "path-to-private-key" etc!)

Let's try to manually call the post-commit.cmd file and see if it works then...

Open a dos prompt command window (in Windows 7 shift-rightclick the folder in Explorer and choose "Open command window here") to your repository's hook subfolder (in my case "C:\Repositories\Test\hooks") and run the following command:

post-commit.cmd C:\Repositories\Test 23 (of course replacing '23' with your revision number!)

Now check the issue again in Mantis. Has it been updated? What the... Now it works!?

If you would take a look in plinkbat.cmd you'd see it is exactly the same as before (in fact, running plinkbat.cmd from the command line results in the note being added to Mantis as well of course!), so what is going on?

Well, that question has kept me busy for some time... Remember we started PuTTY once to store the server key in the registry? Well, it so happens that VisualSVN runs as a service, and as such executes the hook scripts under a different user name than yours (because you may not be logged in at all). Second, PuTTY stores the ssh host keys under HKEY_CURRENT_USER in the registry, and what's even worse DOES NOT return 1 when it fails to connect to the server due to the server's host key not being cached in the registry. I think that's a bug in plink. Plink should return 1 in that instance (if it would we would be able to see the error in TortoiseSVN).

So, what's the solution? The solution is to simply copy the stored ssh host key to all users in the system:

1. Start regedit.exe
2. Browse to "HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\SshHostKeys" and export that key
3. Browse to HKEY_USERS and expand the key
4. You should now see a list of users on your system similar to this:
   • .DEFAULT
   • S-1-5-18
   • S-1-5-19
   • ...etc...
5. Open the exported key from (2) in notepad and duplicate the key for the list of users above

Like this:

[HKEY_USERS\.DEFAULT\Software\SimonTatham\PuTTY\SshHostKeys]
   hostkeyvalue_here

[HKEY_USERS\S-1-5-18\Software\SimonTatham\PuTTY\SshHostKeys]
   hostkeyvalue_here

[HKEY_USERS\S-1-5-19\Software\SimonTatham\PuTTY\SshHostKeys]
   hostkeyvalue_here

...etc...

Do not duplicate the key for user keys that have more numbers behind S-1-5-XX, since that is the current user.

6. Now save and close the registry file
7. And finally double click it to add the hostkey registry information to the registry

If you now change a file in your Test repository again, commit it and add a comment containing "issue #nn", Mantis should update correctly now with a note added to the issue, like this:

You could go on and write a more elaborate batch script, but we all know that batch files are not the most user friendly way of writing scripts. Nothing stops us from writing a simple C# application that gathers all information and updates Mantis for us though!

I've attached a simple C# application that updates Mantis using a nicely formatted note, like these ones (I committed 2 files at the same time with the comments "worked on issue #50 (file1.txt)" and "implemented feature #46 (file2.txt)":

As you can see my C# program supports updating multiple issues at the same commit, it gathers all information and formats it nicely.

Call the attached C# program, UpdateMantis.exe, like this from your post-commit.cmd:

But, before you do you'll of course have to install UpdateMantis (a setup package is included in the attachment) and configure the UpdateMantis.exe.config file (note that in Windows 7 you'll have to configure security for the .config file so normal users can modify the file):

Note that you can use environment variables in the xml values. My config file looks something like this:

Note that the attached VS2008 C# project includes source and IS NOT OF PRODUCTION QUALITY. There is no error handling whatsoever, so if you want to use this program in a production environment you should add some code and make it more robust.

I hope this blog post will help some of you out there struggling to get Mantis integrated with SVN. Good luck!

Last but not least, I'd like to thank the writer of this blog post and all people that commented on that blog post. It has been my single source of information while trying to find a solution to my specific problem. Thanks!

The fixes to CE 6.0 R2 VoIP will be included in the July 2009 QFE package which should be released this week.

These QFE's are a direct result from the support incident we opened with Microsoft regarding this issue. The support incident was of course completely free because this was a bug, so, whenever you find a bug that needs fixing: Please open a support incident with Microsoft and help make Windows CE better!

At this moment the whole Windows CE support procedure you have to go through is frustrating to say the least, but Microsoft is updating its support procedures for Windows CE so it will be streamlined in the near future. For now, just keep your cool on the phone and follow the instructions as per the leaflet inside the Windows CE 6.0 box. Do not pay or give them your credit card number if you still have a free support call left (you get 2 free support calls when you buy Platform Builder for Windows CE 6.0).

I'll keep you updated when I hear something back from Microsoft regarding the support procedures.

Version 3.0 of the MicroFramework SDK (finally!) supports configuring USB for other functions than just debug. This means you can now use USB as a communications medium for your applications. Microsoft ships a sample that shows one of those possibilities: Transforming your device into a mouse. In this blog post I'll show a more useful solution: How to setup a MicroFramework device so you can send and receive data over USB to and from the device.

Independent hardware vendors (IHVs) who manufacture USB devices must typically provide a way for applications to access the device’s features. Historically, this has meant using the Windows® Driver Model (WDM) to implement a function driver for the device and installing the driver in the device stack. However, drivers require a significant development effort, and some devices are simple enough that they do not require the full support of a custom function driver.
The USB functionality we'll be developing will be simple, so writing a full function driver will be overkill. Luckily Microsoft introduced the user-mode driver framework (UMDF) and part of this framework is WinUSB. WinUSB was developed concurrently with the Windows Driver Foundation (WDF) and is available for Windows XP and later versions of Windows. It includes a kernel-mode driver, WinUsb.sys, which is an integral part of the WDF-UMDF support for USB drivers. For USB devices that are accessed by only a single application, you can often install WinUsb.sys as the device’s function driver instead of implementing a custom driver. The application can then configure the device and access its endpoints by using the WinUSB API, and that's exactly what I'll do in this example!

WinUSB consists of two primary components:

• WinUsb.sys is a kernel-mode driver that can be installed as either a filter or function driver, above the protocol drivers in a USB device’s kernel-mode device stack.
• WinUsb.dll is a user-mode DLL that exposes the WinUSB API. Applications can use this API to communicate with WinUsb.sys when it is installed as a device’s function driver.

For devices that do not require a custom function driver, WinUsb.sys can be installed in the device’s kernel-mode stack as the function driver. User-mode processes can then communicate with WinUsb.sys through a set of device I/O control requests. The WinUSB API, exposed by WinUSB.dll, simplifies this communication process. Instead of constructing device I/O control requests to perform standard USB operations such as configuring the device, sending control requests, and transferring data to or from the device, applications call equivalent WinUSB API functions. Internally, WinUsb.dll uses the data that the application passes to the WinUSB function to construct the appropriate device I/O control request and sends the request to WinUsb.sys for processing. When the request is complete, the WinUSB function passes any information returned by WinUsb.sys such as data from a read request—back to the calling process.

Using the WinUSB API to communicate with a device is much simpler than implementing a driver, but has some corresponding limitations:

• The WinUSB API allows only one application at a time to communicate with the device. If more than one application must be able to communicate concurrently with a device, you must implement a function driver.
• The WinUSB API does not support streaming data to or from isochronous endpoints. Isochronous transfers require a kernel-mode function driver.
• The WinUSB API does not support devices that already have kernel-mode support. Examples of such devices include modems and network adaptors, which are supported by the telephony API (TAPI) and NDIS, respectively.
• For multifunction devices, you can use the device’s INF to specify either an in-box kernel-mode driver or WinUsb.sys for each USB function separately. However, you can specify only one of these options for a particular function, not both.

WinUSB is natively supported on all Windows Vista SKU's and is supported on all SKU's of the 32 bit versions of Windows XP SP2 and later service packs. WinUSB is not native to Windows XP; it must be installed with the WinUSB co-installer.

The WinUSB co-installer package can be found in the Windows Driver Kit under the WinDDK\BuildNumber\Redist\Winusb folder. The DLLs are signed and can be redistributed by IHVs. So if you want to develop an application that talks to your MicroFramework device over USB under XP, you'll have to install the WinDDK. After you've completed your development and are ready to ship your device your customers of course don't have to install the WinDDK to use your application because you'll ship your device with an installer that includes the redistributable co-installer package.

Read "How to Get the WDK and the WLK" to obtain the latest WDK version.

Before your application can use the WinUSB API to communicate with your device, you must install WinUsb.sys as the device’s function driver. To do so, you have to create a package that includes:

• The WinUSB co installer, which installs WinUSB on the target system, if necessary. The WDK includes two versions of the co-installer, one for x86 systems and one for x64 systems. They are both named WinUSBCoInstaller.dll and are located in the WinDDK\BuildNumber\redist\winusb folder.
• The Kernel Mode Driver Framework (KMDF) co installer, which installs the correct version of KMDF on the target system, if necessary. This co-installer is required because WinUsb.sys depends on KMDF. The x86 and x64 versions of WdfCoInstaller01005.dll are included with the WDK under the WinDDK\BuildNumber\redist\wdf folder (but you need WDK version 6001.18002 or higher).
• An INF that installs WinUsb.sys as the device’s function driver.
• A signed catalog file for the package. This file is required to install WinUSB on x64 versions of Windows Vista. For more information on how to create and test signed catalog files, see "Kernel-Mode Code Signing Walkthrough". Note that this document states that Inf2Cat is not currently part of the WDK tools, but in fact it is (you can find it in \WinDDK\BuildNumber\bin\SelfSign).

Before we can create the INF, let's define what we want our MicroFramework device to do, and develop the device side code!

In this example we want to keep it as simple as possible; all we want is two-way communication with our device. The best option for this is to create 2 bulk endpoints; one for reading and one for writing data. I'll be using the DeviceSolutions TahoeII board to develop the application on.

[Note: Download all code below]

Let's start coding!

1. Start Visual Studio 2008
   I'm assuming you have Visual Studio 2008 with SP1, the .NET MicroFramework SDK v3.0 and the TahoeII SDK v3.0 installed.
2. Create a new MicroFramework Console Application
3. First let's add the needed references. Right click on your project in the solution explorer and select "Add reference...". Now add the following references:
   • Microsoft.SPOT.Hardware.Usb
4. Open program.cs and add the following to the top of the file:
   
   using Microsoft.SPOT.Hardware.UsbClient;
5. Add the following constants to class Program:
   
   private const int WRITE_EP = 1;
   private const int READ_EP = 2;

   We use these constants so we can easily change the used endpoints if needed.

6. Delete the standard Debug.Print line from the function Main()
7. Now we add code to function Main() to detect the number of USB Controllers supported by the hardware:
   
   // See if the hardware supports USB
   UsbController[] controllers = UsbController.GetControllers();

   // Bail out if USB is not supported on this hardware!
   if (0 == controllers.Length)
   {
       Debug.Print("USB is not supported on this hardware!");
       return;
   }

8. At this moment the .NET MicroFramework 3.0 does not support changing the USB configuration on the fly so using USB for application communication and Visual Studio Debugging is not possible when configuring USB from C# code running on the device. If you update the device's USB descriptors through XML using MFDeploy it is possible to debug and communicate at the same time (over multiple USB interfaces descriptors that is! More about that in a follow up post about CDC).
   
   // Find a free USB controller
   UsbController usbController = null;
   foreach (UsbController controller in controllers)
   {
       if (UsbController.PortState.Stopped == controller.Status)
       {
           usbController = controller;
           break;
       }
   }

   // If no free USB controller
   if (null == usbController)
   {
       Debug.Print("All available USB controllers already in use. Set the device to use Ethernet or Serial debugging.");
       return;
   }

   Setting the TahoeII to use Ethernet or serial debugging is easy; just hold SW4 while resetting the device for debugging over Ethernet, or hold SW2 for debugging over serial. If you set it to debug over Ethernet then don't forget to configure the TahoeII's Ethernet settings using MFDeploy (see "Configuring Ethernet on the Tahoe-II" in the TahoeII SDK documentation -> press F1 in Visual Studio)

9. If we found a free USB controller we can now start to configure that controller. We'll put the configuration code in a separate function to keep it all together. Add the following function to the Program class:
   
   1. private static bool ConfigureUSBController(UsbController usbController)
   2. {
   3.     bool bRet = false;
   4.  
   5.     // Create the device descriptor
   6.     Configuration.DeviceDescriptor device = new Configuration.DeviceDescriptor(0xDEAD, 0x0001, 0x0100);
   7.     device.bcdUSB           = 0x110;
   8.     device.bDeviceClass     = 0xFF;     // Vendor defined class
   9.     device.bDeviceSubClass  = 0xFF;     // Vendor defined subclass
   10.     device.bDeviceProtocol  = 0;
   11.     device.bMaxPacketSize0  = 8;        // Maximum packet size of EP0
   12.     device.iManufacturer    = 1;        // String #1 is manufacturer name (see string descriptors below)
   13.     device.iProduct         = 2;        // String #2 is product name
   14.     device.iSerialNumber    = 3;        // String #3 is the serial number
   15.  
   16.     // Create the endpoints
   17.     Configuration.Endpoint writeEP = new Configuration.Endpoint(WRITE_EP, Configuration.Endpoint.ATTRIB_Bulk | Configuration.Endpoint.ATTRIB_Write);
   18.     writeEP.wMaxPacketSize  = 64;
   19.     writeEP.bInterval       = 0;
   20.  
   21.     Configuration.Endpoint readEP = new Configuration.Endpoint(READ_EP, Configuration.Endpoint.ATTRIB_Bulk | Configuration.Endpoint.ATTRIB_Read);
   22.     readEP.wMaxPacketSize   = 64;
   23.     readEP.bInterval        = 0;
   24.  
   25.     Configuration.Endpoint[] usbEndpoints = new Configuration.Endpoint[] { writeEP, readEP };
   26.  
   27.     // Set up the USB interface
   28.     Configuration.UsbInterface usbInterface = new Configuration.UsbInterface(0, usbEndpoints);
   29.     usbInterface.bInterfaceClass    = 0xFF; // Vendor defined class
   30.     usbInterface.bInterfaceSubClass = 0xFF; // Vendor defined subclass
   31.     usbInterface.bInterfaceProtocol = 0;
   32.  
   33.     // Create array of USB interfaces
   34.     Configuration.UsbInterface[] usbInterfaces = new Configuration.UsbInterface[] { usbInterface };
   35.    
   36.     // Create configuration descriptor
   37.     Configuration.ConfigurationDescriptor config = new Configuration.ConfigurationDescriptor(180, usbInterfaces);
   38.  
   39.     // Create the string descriptors
   40.     Configuration.StringDescriptor manufacturerName = new Configuration.StringDescriptor(1, "GuruCE");
   41.     Configuration.StringDescriptor productName      = new Configuration.StringDescriptor(2, "MicroFramework WinUSB");
   42.     Configuration.StringDescriptor serialNumber     = new Configuration.StringDescriptor(3, "0000-0000-0000-0001");
   43.     Configuration.StringDescriptor displayName      = new Configuration.StringDescriptor(4, "MicroFramework WinUSB");
   44.     Configuration.StringDescriptor friendlyName     = new Configuration.StringDescriptor(5, "NetMF_WinUSB");
   45.  
   46.     // Create the final configuration
   47.     Configuration configuration = new Configuration();
   48.     configuration.descriptors = new Configuration.Descriptor[]
   49.     {
   50.         device,
   51.         config,
   52.         manufacturerName,
   53.         productName,
   54.         serialNumber,
   55.         displayName,
   56.         friendlyName
   57.     };
   58.  
   59.     try
   60.     {
   61.         // Set the configuration
   62.         usbController.Configuration = configuration;
   63.         if (UsbController.ConfigError.ConfigOK != usbController.ConfigurationError)
   64.             throw new ArgumentException();
   65.         // If all ok, start the USB controller.
   66.         bRet = usbController.Start();
   67.     }
   68.     catch (ArgumentException)
   69.     {
   70.         Debug.Print("Can't configure USB controller, error " + usbController.ConfigurationError.ToString());
   71.     }
   72.     return bRet;
   73. }

   The MicroFramework SDK v3.0 shipped without documentation on the new USB classes, but an extra download updating the documentation fixes that.

   Let's step through the code:

   • Line 6-14: We start by creating the device descriptor. The constructor of the Configuration.DeviceDescriptor Class has the following signature:
     
     public DeviceDescriptor(ushort Vendor, ushort Product, ushort DeviceVersion)

     Using parameter "Vendor" we supply the VID of the device. In this example I'm using a non-existing VID (0xDEAD), but in your final commercial device you'd have to use your own registered VID (check out http://usb.org for information on how to acquire a VID/PID). Note that in most countries using someone else's VID is considered theft and thus a criminal offense, not just a civil one. The parameter "Product" is used to supply the PID. In this case we'll just use a PID of 0x0001. The "DeviceVersion" parameter can be used to indicate device version and you are free to set this to anything you like (I set it to "1.0").
     The next 4 lines set the USB version in bcdUSB (USB 1.1), the device class, subclass & protocol. We set these to indicate our device is a custom vendor defined class; it doesn't fit in one of the predefined USB classes. The MicroFramework firmware already sets up control endpoint 0 for us so all we have to do is supply the maximum packet size of EP0. Even though the maximum packet size for EP0 is 32 bytes (see the iMXS datasheet; the processor the Meridian module on the TahoeII board is using) the TahoeII firmware sets it up as 8 bytes, so we have to set this field to 8. The iManufacturer, iProduct and iSerialNumber fields are indexes pointing to strings (that are defined in lines 40 - 44).

   • Line 17-25: Here we create our two endpoints: EP1 BULK IN (which means data flows from device to host, so we'll call this WRITE) and EP2 BULK OUT (which means data flows from host to device so we'll call this READ). The class constructor:
     
     public Endpoint(byte EndpointAddress, byte Attributes)

     . The EndpointAddress indicates the physical endpoint number. The attributes indicate the type of transfer, the type of synchronization and the usage type for the endpoint.
     After creating the two endpoints we store them in an array of endpoints so we can include them in the UsbInterface:

   • Line 28-34: The UsbInterface class constructor has the following signature:
     
     public UsbInterface(byte InterfaceNumber, Microsoft.SPOT.Hardware.UsbClient.Configuration.Endpoint[] Endpoints)

     The parameter InterfaceNumber allows us to define multiple interfaces with a different set of endpoints. In this case I define only 1 interface with 2 endpoints in the array. We set the InterfaceClass and InterfaceSubClass again to "vendor defined" and we put our interface in an array so we can include them in the configuration descriptor:

   • Line 37: The ConfigurationDescriptor class constructor has the following signature:
     
     public ConfigurationDescriptor(ushort MaxPower_mA, Microsoft.SPOT.Hardware.UsbClient.Configuration.UsbInterface[] Interfaces)

     The parameter MaxPower_mA is used to set the maximum power in mA. The TahoeII draws an absolute maximum of 180 mA, so that's what we set. The 2nd parameter holds our interfaces.

   • Line 40-44: Here we create our string descriptors that we point at in line 12 - 14.
   • Line 46-57: After creating the various descriptors we can now put them all together in the Configuration class.
   • Line 59-71: And finally we apply the configuration and start the USB controller.
10. Now that we've finished that function, we can continue adding code to the end of the Main() function:
    
    UsbStream usbStream = null;
    try
    {   // Configure the USB controller
        if (ConfigureUSBController(usbController))
            usbStream = usbController.CreateUsbStream(WRITE_EP, READ_EP);
        else
            throw new Exception();
    }
    catch (Exception)
    {
        Debug.Print("USB stream could not be created, error " + usbController.ConfigurationError.ToString());
        return;
    }

    The code above calls the ConfigureUSBController function we created before and creates the USB stream.

11. All we want our program to do is echo back whatever our application running on the PC sends to it. Add the following function to the Program class:
    
    static void USBLoop(UsbStream usbStream)
    {
        byte[] readData = new byte[100];
        for (; ; )
        {
            int bytesRead = usbStream.Read(readData, 0, readData.Length);
            if (bytesRead > 0)
            {   // echo back!
                usbStream.Write(readData, 0, bytesRead);
            }
        }
    }
12. And finally we'll call this never ending loop by adding the following code to the end of the Main() function:
    
    // Start our communication loop
    USBLoop(usbStream);
    usbStream.Close();

    Of course the usbStream.Close() function will never be reached in our case, but we could add code to return from the loop if "Quit" is received for instance...

13. Now that our program is finished we have to set up the correct debug transport to the TahoeII. Before switching the TahoeII to Ethernet you'll have to configure the Ethernet settings using MFDeploy:
    • Make sure the TahoeII is using USB as a debug transport by holding SW3 while resetting the TahoeII
    • Now start MFDeploy and select "USB" from the Device dropdown. The TahoeII should immediately pop up (as "Meridian_XXXXXXXX"). Ping the device to make sure you can reach it.
    • From the Target menu, click "Configuration" and select "Network".
    • Configure the TahoeII to match your network (set a static IP and subnetmask within range of your PC's IP or enable DHCP if you have a DHCP server on your network)
    • Now set the TahoeII to use TCP/IP as debug transport by holding SW4 while resetting the device.

    If the TahoeII is setup for TCP/IP we have to setup Visual Studio 2008 to use TCP/IP as well: Right click on your project in the solution explorer, choose "Properties" and click on the ".NET Micro Framework" tab. Select "All Configurations" from the "Configuration" dropdown list, set "Transport" to "TCP/IP" and you should see the device's IP and MAC address appearing in the "Device" dropdown list. Select the correct one (if you have more than one TahoeII connected) and close this window.

If all is well you can now press F5 to build and deploy the program. If you keep a close eye on your taskbar notification area you'll see the following notifications pop up:

And after that XP will ask you for the driver:

Since we'll be using WinUSB as the driver, all we need to do now is create the .inf file for our device. The document "How to Use WinUSB to Communicate with a USB Device" explains in detail how to do exactly that. If we modify the sample from that document according to the instructions we'll end up with an inf that looks like this:

If you don't use one of the System-Supplied Device Setup Classes you'll have to add a ClassInstall32 section to the inf that adds the class name to the registry. Even though our device would seem to fit the USB class we can't use that class because it's only meant for USB Host controllers and hubs (not for USB peripherals).

Note that if you want to ship a device using the above inf you'll have to change the following:

• Class: Change to something meaningful for your device
• ClassGuid: Generate a new GUID for the class
• CatalogFile: Change to something meaningful for your device
• DriverVer: Change to something meaningful for your device
• Manufacturer/Models sections: Change to something meaningful for your device and make sure the VID/PID matches your device.
• [Dev_AddReg]: Generate a new GUID for the device
• [Strings]: Change to something meaningful for your device

With this inf file we can now create our driver package. The drivers and tools required are all in the Windows Driver Kit, so you'll need to install that first.

After you have installed the WDK create a new folder, let's say C:\MFWinUSBDriver, and create the inf file in that folder. Now open a build environment matching your operating system by clicking the appropriate shortcut in the "Windows Driver Kits" start menu group. Now "cd" (change directory) to C:\MFWinUSBDriver.

The next step is to create a catalog file out of our inf. The process of creating a catalog file (and signing) is described in "Kernel-Mode Code Signing Walkthrough" and the tool to use is Inf2Cat. If you are planning on shipping your driver to your customers you should properly sign your catalog. For the sake of simplicity this blogpost will not discuss official signing (but will focus on getting the driver to load asap!).

As you can see, the inf file lists a couple of dll's. These dll's are part of the WDF redistributables that can be found in the WDK at this location: C:\WinDDK\6001.18002\redist

Copy the amd64, ia64 and x86 folders from C:\WinDDK\6001.18002\redist\wdf to C:\MFWinUSBDriver so that you now have the following 3 folders (with the corresponding driver files in those folders):

Now copy the amd64, ia64 and x86 folders from C:\WinDDK\6001.18002\redist\winusb to C:\MFWinUSBDriver and click "Yes to All" in the "Confirm Folder Replace" dialog.

You should now have the following files in those 3 folders listed above:

The _chk files are for checked (debug) builds of the operating system and since we won't be using those you can delete all the _chk files from the 3 folders listed above.
You can also remove the WUDFUpdate*.dll files because we are going to be talking to the WinUSB driver directly from our application. If you want to write a UMDF driver instead you'll need to add the UMDF coinstaller and have all of the appropriate entries in the inf (like UmdfServiceOrder). The ZIP file contains an example inf file for UMDF as well.

Now that everything is in place we can finally call Inf2Cat:

If all went well the inf2cat output should show:

If you still have the "Found New Hardware Wizard" open you can now point the wizard to C:\MFWinUSBDriver and have it install the driver. If you don't have the wizard open anymore; go to the Device Manager, delete the unknown USB device from the "Other devices" node and re-attach (or reset) the TahoeII.

Now everything is ready and we can start the development of the PC application. Fortunately Jan Axelson already developed an application in C# that can talk to devices utilizing WinUSB. She provides full source code and it's a real good starting point for your own applications. Download the latest version from her WinUSB page.

Download and extract winusb_cs_xxx.zip to a folder of your choice and load the solution in Visual Studio 2008. Now open the frmMain.cs code and change the WINUSB_DEMO_GUID_STRING to match our inf file: "{77C99034-2428-424a-8130-DC481841429B}".

Now press F5 to run the solution. Enter some text in the "Bulk Transfers" textbox and click on the "Send" button:

Eureka! The TahoeII is echoing back whatever we send to it. You can download the MicroFramework code and the MFWinUSB Driver here.

I'll try to follow up this article with an article showing how to setup the TahoeII as a USB Communication Device Class (CDC) so that you can communicate with your device without using WinUSB (and without having to sign your "driver").


Good luck in creating your next USB connected device running the MicroFramework!

Some portions of the text in this article were taken (and modified/updated/added to where necessary) from "How to Use WinUSB to Communicate with a USB Device".

This is going to be awesome, can't wait!

User Interface Technologies for Windows Embedded CE

(From Mike Hall's blog)

In Windows CE there is built in functionality that allows a user to lock and login the system, just like you are used to on "big" desktop systems. To activate this functionality you simply set the system password in Windows CE through the control panel applet. You can also do this programmatically using the SetPassword() and SetPasswordStatus() API's.

When the password is set at boot the system will show the standard Windows CE login screen:

Recently I got a question whether it is possible to programmatically bring up the password dialog. After some analysis the answer was yes. I found out that the Power Manager instantiates the password dialog when the system returns from showing a screensaver. The password dialog is instantiated by calling ShowStartupWindow(). Here's the code used by the Power Manager (from "<WINCEROOT>\PUBLIC\COMMON\OAK\DRIVERS\PM"):

The example below shows you how to use the exact same technique inside your applications to instantiate the password dialog:

Of course you can always create your own password dialog (because let's be honest; it's not the most beautiful dialog you've ever seen, right?!), but if you don't mind the ugly box the technique above just uses the existing functionality of CE and will save you a bit of time developing a password dialog yourself.

From the comments in the code above you can see I found a rather interesting little fact: Windows CE passwords are CASE INSENSITIVE! That's old-school, isn't it?!

The code that handles the GUI portion of the password handling code is in startui.cpp (here "<WINCEROOT>\PUBLIC\COMMON\OAK\DRIVERS\STARTUI"):

The _wcslwr function converts the password string to lowercase before checking it, but SetPassword allows you to set a password using mixed case! Keep that in mind next time you locked yourself out of your Windows CE device... ;o)

If sysgen_capture doesn't work for some reason you can always manually clone the component you want to modify. By following the instructions on the blog post "Cloning Public Code: An Example" you should be able to get this working, but to help you a bit more here are some step by step instructions for manually cloning public code.

In this blogpost we'll be cloning TELNETD because for some reason sysgen_capture doesn't work for this component. TELNETD is located under the WINCE project tree "servers". I know the exact name of the WINCEPROJ by opening up the makefile in \PUBLIC\SERVERS\CESYSGEN and searching for WINCEPROJ. The correct sysgen_capture command for TELNETD would be:

sysgen_capture -p servers telnetd

The -p parameter indicates the WINCEPROJ, so in this case it's of course not "common", but "servers". Unfortunately for some reason this command doesn't output a sources.telnetd file (in fact it doesn't output any file!). No stress, let's just clone manually:

1. Copy the TELNETD folder to your OS Design (\WINCE500\PBWorkspaces\<MyOSDesign>\TELNETD or \WINCE600\OSDesigns\<MyOSDesign>\<MyOSDesign>\TELNETD)
2. Open the sources. file in the folder you just copied
3. Set TARGETTYPE to DYNLINK
4. Set RELEASETYPE to LOCAL
5. Delete WINCETARGETFILE0=$(_RELEASELIBDIR)\$(TARGETDEFNAME).def
6. Open the makefile. in <WINCEROOT>\PUBLIC\SERVERS\CESYSGEN and search for telnetd
7. Copy the line @set TARGETLIBS... and @set DLLENTRY...
8. Paste into your sources. file
9. Change @set TARGETLIBS... in your sources. file to:
   
   TARGETLIBS=$(_PROJECTROOT)\cesysgen\sdk\lib\$(_CPUINDPATH)\ws2.lib \
              $(_PROJECTROOT)\cesysgen\sdk\lib\$(_CPUINDPATH)\coredll.lib \
              $(_PROJECTROOT)\cesysgen\sdk\lib\$(_CPUINDPATH)\ceosutil.lib  \
              $(_PROJECTROOT)\cesysgen\sdk\lib\$(_CPUINDPATH)\authhlp.lib
10. Change @set DLLENTRY... in your sources. file to:
    
    DLLENTRY=DllEntry
11. Add the include paths:
    
    _OEMINCPATH=$(_WINCEROOT)\public\common\oak\inc; $(_WINCEROOT)\public\common\sdk\inc; $(_WINCEROOT)\public\common\ddk\inc

    NOTE: DO NOT PUT SPACES BETWEEN THE PATHS! I know it is confusing because I do it above, but I have to to support line breaking (otherwise this page will look ugly...).

12. And build...

Easy as that! Now that you have the TELNETD component successfully cloned you can continue following the instructions from step 7 in the blog post "Cloning Public Code: An Example" (of course replacing "netui" with "telnetd" in the text).

Here's the complete sources. file for reference (don't forget to delete the spaces in the _ISVINCPATH, _OEMINCPATH and INCLUDES macros! I need those spaces here to format the HTML nicely, but you will get compiler error "/I" requires an argument if you leave those spaces):

If you read this blog or the CE newsgroups you should by now know you should never change any files in the PUBLIC or PRIVATE folders of your WINCE installation tree. So what if you want to change a setting in common.reg (which is located in the PUBLIC folder)? Well, add the same entry to your platform.reg (in your PLATFORM\BSP folder) and set it to whatever you like. So, what if you want to delete a setting from common.reg? Again, add the same entry to your platform.reg but precede the key name with a "-". This works because platform.reg is merged into reginit.ini after common.reg, so any duplicate entries or deletion commands (the "-") will override the settings in common.reg.

So, what about dat files? Unfortunately, deleting dat entries with the "-" tag is not supported. Dat files are responsible for the initial copy of files and creation of folders during boot. For instance, dat files are used to copy shortcuts from the \Windows folder to the desktop of your CE device. Now what if you don't want to have icons on your desktop? The only way that seems possible is to actually change the public dat files in place, but you know you should never change any files in the PUBLIC tree! We just have to come up with a different solution...

The solution in this case is to filter the dat files and remove any unwanted lines before creating the final image but after the sysgen phase and without touching the original files in PUBLIC. Windows CE calls out to a number of batch files during the makeimg process to let you write your own scripts to affect the image at different points during the image building process. One of those batch files is "PostFmergeObj.bat" which, as the name suggests, is called just after fmerge merged the "Obj" files (which are in fact "Dat" files... confused already? ;o) into your FLATRELEASEDIR.

By using a bit of scripting magic we can use this batch file to filter out unwanted lines from the final merged InitObj.dat file:

The core of the script is from line 15 onwards. In line 15 we delete any previous initobj.org file this batch file may have left behind. Then, in line 16, we rename initobj.tmp (all dat files are merged into this file by fmerge) to initobj.org and in line 17 we call the dos utility Findstr:

By calling findstr with options /I and /V we effectively filter out the lines we specify in PostFmergeObj.txt and we pipe the output of findstr into InitObj.tmp. After this batch file returns the build system will call the "Text to Unicode" tool (Txt2ucde.exe) that converts any ASCII text strings in Initobj.tmp to Unicode text strings and creates the file Initobj.dat which then contains the Unicode conversion of InitObj.tmp (see http://msdn.microsoft.com/en-us/library/ms930234.aspx).

Note that you can also use regular expressions to find strings with findstr. Using this you have a very powerful tool to filter whatever file you want filtered and of course this trick doesn't only work on dat files, it works on any ascii text file (like bib, reg, etc).

All you have to do for all this to start working in your build is create PostFmergeObj.bat in your PLATFORM\BSP\FILES folder and copy'n'paste the above script. The Windows CE build system will automatically search for this batch file and if it finds it execute it just after it has merged the various configuration files. Don't forget to create a "PostFmergeObj.txt" file with the lines you want to delete from the final InitObj.dat file in the same folder as the batch file, like this:

When you now perform a "make image" this batch file should automatically execute and its output (the "echo" commands in the batch file) should appear in the build output window.

Lately there have been a lot of questions about SD and MMC in the newsgroups, especially about what is supported by the Microsoft SD bus driver. This blog post hopefully helps clear up some things about SD/MMC support in Windows CE.

First let’s look at an overview of the MMC and SD specifications and who supports what:

From the table above it looks like the SD bus driver in CE 6.0 R2 supports the MMC 4.3 specification, but actually it doesn’t completely (as we’ll see a bit later in this blog post).

The Microsoft SD bus driver (sdbus2.dll) is fully supporting the SD 2.0 specification. Because the MMC 4.3 specification is quite similar to SD 2.0, CE “somewhat” supports MMC 4.3.

So what does this mean? Well, for example, the number of data lines (bus width) of MMC supported by the Microsoft SD bus driver differs from the MMC specification:

8/4 or 1-bit mode

The MMC specification tells us it supports 8-bit wide bus mode (8-data lines). However, the SD 2.0 specification does not support 8 bit bus mode. Since CE officially supports SD but not MMC, CE does not support the 8-bit mode for any MMC/SD card. Unfortunately it appears the 4-bit mode is also not supported for MMC cards by the Microsoft SD bus driver even though the SD specification does support this mode. This leaves 1-bit mode as the only supported mode for MMC.

Here’s an overview of the supported modes by the SD bus driver (sdbus2.dll):

So does this mean that MMC cannot support 4 or 8 bit at all? Well no, not really... You can always CLONE the SDBUS driver and modify it according to your needs or you can develop your own driver without using the SD bus driver at all.

High Capacity

According to the SD 2.0 specification "High Capacity" means cards with sizes larger then 2GB. SDHC cards are supported by the SD bus driver version 2.0. However, because of a bug in the SD bus driver high capacity MMC cards don’t work. You need to fix one line of code to support HC MMC cards. Besides this bug there is also a difference in the protocol for MMC and SD 2.0 regarding High Capacity, more about that later.

First let’s fix the obvious bug so that your High Capacity MMC card will be recognized and mounted properly:

The first step is to clone the SD Bus driver located at <WINCEROOT>\PUBLIC\COMMON\OAK\DRIVER\SDCARD\SDBUS

1. Open a build release window
2. Type "cd %_targetplatroot%"
3. Type "cd src"
4. Type "cd drivers"
5. Type "md sdbus2"
6. Type "cd sdbus2"
7. Type "sysgen_capture -p common sdbus"
8. Now copy the files from <WINCEROOT>\PUBLIC\COMMON\OAK\DRIVER\SDCARD\SDBUS into <WINCEROOT>\PLATFORM\<YourBSP>\SRC\DRIVERS\SDBUS2
9. And merge sources.sdbus and sources so you end up with this sources file:
SYNCHRONIZE_BLOCK=1

TARGETNAME=sdbus
TARGETDEFNAME=SDBus2
DEFFILE=$(TARGETDEFNAME).def

TARGETTYPE=DYNLINK
RELEASETYPE=PLATFORM

DLLENTRY=_DllEntryCRTStartup

SOURCES = sdbusreq.cpp \
          sddevice.cpp \
          sdbus.cpp \
          sdslot.cpp \
          sdclient.cpp \
          sddevinf.cpp \
          sdiofeat.cpp \
          sdworki.cpp \
          sddebug.cpp \

TARGETLIBS=                                           \
  $(_SYSGENOAKROOT)\lib\$(_CPUINDPATH)\defbuslib.lib  \
  $(_SYSGENSDKROOT)\lib\$(_CPUINDPATH)\coredll.lib    \
  $(_SYSGENOAKROOT)\lib\$(_CPUINDPATH)\ceddk.lib    

Note that I added SYNCHRONIZE_BLOCK=1 to make sure any other component that will link to the sdbus library will be able to find it. SYNCHRONIZE_BLOCK=1 makes sure this folder is built before any other folder in the DRIVERS folder is built.

10. Try to build the SDBUS2 driver; it should build without errors. If it doesn’t, make sure you selected the SD Bus Driver in the catalog and performed a sysgen on your OSDesign.
11. And add the SDBUS2 folder to the dirs file in the DRIVERS folder.
12. Don't forget to change any BSP component that links to $(_COMMONOAKROOT)\lib\$(_CPUINDPATH)\sdbus.lib to use the cloned SDBUS library, located at $(_TARGETPLATROOT)\lib\$(_CPUINDPATH)\sdbus.lib

Now change StringCchCopy to StringCchCat in line 1394 of sddevice.cpp (in your cloned folder of course!). This will append the "\\High_Capacity" string to the Client driver registry entry instead of replacing it (which leads to not finding the correct registry path for the profile because "HKLM\\High_Capacity" is not a valid registry path). Even with this fix it won’t find that path because Microsoft did not provide registry settings for High Capacity MMC. Let’s fix that by adding the following to platform.reg:

Now you can Build and Sysgen your BSP by right clicking on your BSP node in the Solution Explorer and choosing Build and Sysgen. NEVER EVER click Build and Sysgen from the Build menu, please read the blog post http://www.guruce.com/blogpost/whattobuildwhen to understand why you should delete that option from the build menu. After the Build and Sysgen of the BSP perform a Copy files to release directory followed by a Make image and download your kernel to your device. When you now insert a high capacity MMC card it should be recognized and mounted correctly, well, almost! The size is most probably still reported wrong. This is because of a difference in the protocol. CMD 8 is handled differently in the SD 2.0 and MMC 4.3 specification:

In the SD protocol CMD8 is used to identify high capacity cards and it is send at the beginning of the initialization process. When CMD8 is getting a response it means that it is identified as a High Capacity card. If sending a CMD8 results in a response timeout it is not a High Capacity card.

For MMC the CMD8 means retrieving the density of the card from the EXT_CSD register instead of the CDS register. CMD8 must be send after a CMD7 command which will place the card into "Tran" state. Since the SD bus driver doesn't do that the CMD8 will time out.

Like I said the SD bus driver fully supports the SD 2.0 specification and it reads the card density from the CSD register. This works for SD 2.0, but not for MMC. To fully support High Capacity MMC cards you should modify the SD bus driver so it can handle CMD8 instead of CMD9 to retrieve the card density for MMC high capacity cards.

SDBUS or SDBUS2

Now how do you select the correct SD bus driver? First remember that you have to install the correct version of Windows CE and install all required QFEs (see specification overview above). For Windows Embedded CE 6.0 there are two catalog components for SDBUS; "SD Bus Legacy" and "SD Bus driver". The legacy one is the SD bus driver that supports SD specification 1.1 and the "SD Bus Driver" item supports the 2.0 specification.

For all other versions of CE there is only one catalog component which automatically selects the SD bus 1.1 specification. To support the 2.0 specification in CE versions prior to CE 6.0 you have to set the IMGSDBUS2 environment variable to 1.

Conclusion

Windows CE fully supports the SD 2.0 specification, but as we saw this doesn’t automatically mean it also fully supports High Capacity MMC cards. Fortunately with a couple modifications here and there you can now fully support High Capacity MMC cards as well!