How to Create, Customize, and Debug an Image for the Windows CE 5.0 Emulator

 

Mike Hall
Microsoft

January 2005

Applies to:
   Microsoft® Windows® CE version 5.01

Summary: This article provides step-by-step instructions that will enable you to create, customize, build, download, and debug a Windows CE image to the Windows CE 5.0 Emulator. The article is divided into three parts, each containing a number of exercises you can complete. It will take approximately 60 minutes to complete all the steps. (37 printed pages)

Download Windows CE 5.0 Embedded Development Labs.msi from the Microsoft Download Center.

Contents

Part 1: Creating a Platform Image
Part 2: Customizing and Building the Platform
Part 3: Debugging the Platform
Summary

Part 1: Creating a Platform Image

You will use the New Platform Wizard within Platform Builder to create an initial platform workspace that you will then modify by adding applications and updating the registry.

Start Platform Builder by clicking Start | All Programs | Windows CE 5.0 | Platform Builder. You are now ready to create a platform using the Platform Wizard.

For larger illustrations in the procedures, click the thumbnails.

To create a new platform workspace

  1. Select File | New Platform.

    The dialog displayed in the following illustration outlines the process of creating a platform. Now you will step through the wizard and make selections as appropriate.

    Click here for larger image

    Click Next.

    As shown in the following illustration, the next step of the New Platform Wizard prompts for the name and location of the platform you're going to build. In Windows CE 4.2, the custom platforms would be created in the C:\WINCE420\PUBLIC folder. Windows CE 5.0, however, separates custom workspaces into a new folder named C:\WINCE500\PBWorkspaces.

    Click here for larger image

    Enter a name of MyPlatform.

  2. Click Next.

    You will build an operating system for the Windows CE 5.0 emulator by selecting EMULATOR:X86, as shown in the following illustration. If you wanted, you could select more than one reference board. Then, at build time, you could select which platform to build and download. Selecting both the emulator and a reference board may be useful when the hardware is still being developed, because you can configure and test the operating system image in the emulator without needing physical hardware.

    Click here for larger image

  3. Click Next.

    You can now choose from a number of sample platforms, or if none of the options match your needs, you can simply select Custom Device and build the image based on the components you select from the catalog.

    For the purposes of this tutorial, you will select Internet Appliance from the list of platform configurations, as shown in the following illustration.

    Click here for larger image

    Click Next.

    While a number of options can be selected for each of the sample platforms, the Platform Wizard shows only options that are relevant to the platform you are building. For example, it would not make sense to include an Internet Explorer or WordPad application in a headless device such as the Gateway. The Internet Appliance can include applications such as the Internet Browser, Windows Media Player, and Windows Messenger and can optionally include other applications. You can further customize your platform by including components from the catalog or by removing components from your project workspace.

    In this example, as shown in the following illustration, you don't need the .NET Compact Framework or any of the Windows Media components, so you can de-select these items.

    Click here for larger image

    Click Next.

    On the Networking and Communications page, you can see that Windows CE provides support for personal, local, and wide area networking. In this example, as shown in the following illustration, the default options are fine.

    Click here for larger image

    Click Next.

    As shown in the following illustration, the wizard is complete. You've configured the Windows CE platform, and you can now further customize the platform by adding or removing components from the platform.

    Click here for larger image

    Click Finish.

You now have a platform workspace containing all the Windows CE components that have been selected from the Platform Wizard. You could further customize the platform by adding additional technologies and platform specific drivers to your workspace, or you could remove any of the components that have been added by the wizard that are not needed by your platform.

Part 2: Customizing and Building the Platform

In this part of the exercise, you will perform the following procedures:

  • Add applications to the platform.

  • Add source code for an application.

  • Add registry application code.

  • Add registry information to the platform.

  • Enable the profiling kernel and event tracking.

  • Build the platform.

  • The default build option is to generate a Release image of the operating system. As shown in the following illustration, use the toolbar to switch from Release build to Debug build.

    Click here for larger image

    You will now create an application using the Project Wizard.

To add an application to the platform

  1. Select the File menu.

  2. Click New Project or File.

    The New Project or File dialog is displayed, as shown in the following illustration, and this shows that a number of different projects could be created, including a WCE Application (a Win32 based Windows CE application), a WCE Console Application, a WCE Dynamic Link Library (DLL), a WCE Static Library, and a WCE Transport Layer. Each of these options is described in the Platform Builder online help.

    Click here for larger image

    Select WCE Console Application.

  3. In the Project name box, enter Walktree.

  4. Click OK.

    New to Windows CE 5.0 is the New Project Wizard project information page, shown in the following illustration. This page prompts for information about the project, including feature name, date, version, and contact information. The content entered on this page will be stored in the projects readme.txt file, and updates or changes to a project should also be updated in the readme.txt file.

    Click here for larger image

    Enter your feature information as shown in the preceding illustration, and click Next.

    As shown in the following illustration, you are prompted for the type of console application you want to add. There are three optional types of console application: An empty project assumes that you will add all the source files needed to the project; A simple Windows CE console application creates the core source files needed to build the project and will have an entry point of _tmain; and finally, A typical "Hello World" application, which outputs the string "Hello World" when executed.

    Click here for larger image

    Select A simple Windows CE console application.

  5. Click Next.

    Also new to Windows CE 5.0 is the NEW PROJECT--ADVANCED SETTINGS page, shown in the following illustration, which allows you to set the release type for this project. The default options are fine.

    Click here for larger image

    Click Finish.

    The Walktree application has now been added to your workspace, as shown in the following illustration. You could build the operating system at this point and run the application. However, the current application doesn't do anything, so you need to add some source code to the application.

    Click here for larger image

    To add source code to the application, you will use a utility named CodeSnip. If this utility isn't already running (you should see a blue bar at the top right of the screen with the words Code Clip if the application is running), you can run the CodeSnip utility from the shortcut on the Windows desktop.

To add source code to the Walktree project

  1. Select FileView in the Workspace window.
  2. Expand the workspace to C:\WINCE500 | Projects | Walktree | Source Files.
  3. Double-click Walktree.cpp.
  4. Select all the code in the existing Walktree application.

To select code from the CodeSnip tool

  1. Go to Code Clip at the top right of your monitor.

  2. Click Code Clip to display the Code Clip interface.

  3. Expand Platform Builder Lab, as shown in the following illustration.

    Click here for larger image

    Select Walktree.

  4. Either click Copy or double-click Walktree to copy the Walktree source to the clipboard.

  5. Click Code Clip to hide the Code Clip interface.

  6. In Platform Builder, select Edit | Paste, or right-click Paste. The Walktree code has now been added to your application.

Walktree is an application that walks through each of the files and folders on your Windows CE device. This includes a shared folder, named Release, that is between your Windows CE image and the desktop development PC. When Walktree enumerates the files in this folder, you will be able to run the Remote Kernel Tracker to view the interaction between the application and the KITL (Kernel Independent Transport Layer) thread running in the kernel.

You're now ready to add your second application, which will be a Windows application with a user interface. You will add a custom registry key to the platform, which will be read by the application at startup. If the key is successfully added to the platform, the contents of the key will be displayed to the user in a message box.

  1. Select File | New Project or File.

  2. Choose WCE Application.

  3. Type the name of your application, RegApp. , as shown in the following illustration.

    Click here for larger image

    Click OK.

  4. Enter your feature information as shown in the following illustration.

    Click here for larger image

    Click Next.

    Again, as shown in the following illustration, you have the following options: An empty project, A Simple Windows CE application, and A typical "HelloWorld" application.

    Click here for larger image

    Select A typical "Hello World!" application.

  5. Click Finish.

    You now have a fully featured "Hello World" application. You could build and deploy the application with no further changes to the code. However, you will want to modify the application to include some code to read a registry key and display the results to the user.

  6. Switch to Class View within your platform workspace.

  7. Expand RegApp Classes to expose the functions within the RegApp application, as shown in the following illustration; this includes the function that deals with Windows Messages, the Windows Procedure, or WndProc.

    Click here for larger image

    Double-click the WndProc function to open the source for this function.

  8. Locate the switch (message) that is just before case WM_PAINT within the Window procedure, and place your cursor immediately after the open curly brace.

Now you're ready to add the registry application code to the application.

To add the registry application code to the application

  1. Go to Code Clip at the top right of your monitor.
  2. Click Code Clip to display the Code Clip interface.
  3. Expand Platform Builder Lab.
  4. Select RegApp.
  5. Either click Copy or double-click RegApp to copy the RegApp source to the clipboard.
  6. Click Code Clip to hide the Code Clip interface.
  7. In Platform Builder, select Edit | Paste, or right-click | Paste.

The code that you have just added to the RegApp application is used to read a custom registry key on your Windows CE platform. You will now add this key to the platform.

To add registry information to the platform

  1. Switch to File View.

  2. Expand File View to reveal Projects | RegApp | Parameterfiles | RegApp.reg, as shown in the following illustration.

    Click here for larger image

    Double-click RegApp.reg to open this file for editing.

  3. Add the following registry content to your RegApp.reg file (you may want to change "Your Name Goes Here" to match your name, but be careful to match the number of quotes and brackets when typing the registry information.) Alternatively, you may want to copy the registry information from Code Clip.

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\DemoApp]

"Name"="Your Name Goes Here"

  1. Select File | Save to save the registry changes.

  2. Switch back to OS Design View, as shown in the following illustration.

    Click here for larger image

    You're now about ready to build the platform. But first, since you'll need to use the Kernel Tracker in the next section of this article, Part 3: Debugging the Platform, you'll need to enable the Profiling kernel.

To enable the Profiling kernel and event tracking

  1. Select Platform | Settings.

  2. Select the Build Options tab on the Platform Settings dialog, as shown in the following illustration.

    Click here for larger image

    You will notice in the preceding illustration that the tools are currently set to build a Debug image of the platform. You have kernel debugging enabled, but to use the Kernel Tracker tool, you also need to enable the Profiling kernel and event tracking.

  3. Select Enable Profiling.

  4. Select Enable Event Tracking During Boot.

  5. Click OK.

You're now ready to build the platform.

To build the platform

  • Select Build OS | Sysgen.

**Note   **The build process will take approximately 10 minutes to complete.

Part 3: Debugging the Platform

You are now ready to download and debug the Windows CE operating system image. In this section, you will be performing the following exercises:

  • Confirming that the debug and kernel transports are configured.
  • Setting breakpoints in some of the shared source that ships with Windows CE and making use of some of the Windows CE remote tools.
  • Downloading the Windows CE image.
  • Using the Call Stack interface.
  • Running the RegApp application on the Emulator.
  • Starting, using, and closing the Kernel Tracker utility from within Platform Builder.
  • Rebuilding and debugging your application.
  • Uploading a bitmap to your application.
  • Building a dummy application
  • Re-making the Windows CE operating system image.

To confirm that debug and kernel transports are configured

  1. Select Target | Connectivity Options to display the following dialog.

    Click here for larger image

    Confirm that Emulator has been configured for Download and Transport.

  2. Click Settings for the Download service.

    The following dialog is used to set download options for the Windows CE Emulator. The emulator runs as a fully functioning x86 CEPC reference board and includes support for networking, serial, and parallel devices by using your development PC's hardware devices.

    Click here for larger image

    Confirm that you have 64MB memory configured for the Emulator.

  3. Click OK.

  4. Click Close to close the Target Device Connectivity Options dialog.

You will now set some breakpoints that will be hit when the Windows CE image has been downloaded. The platform has a file system driver, so you can use the Platform Builder IDE to locate the code that's loading the driver and set a breakpoint on this code.

To set debug breakpoints

  1. Within the Platform Builder OS Design View, open the following folders:

    • Internet Appliance
    • File Systems and Data Store
    • Storage Manager

    Double-click FSDMGR Helper Functions to jump over to File View and onto the node in the source tree that contains the FSDMGR source.

  2. Expand Source Files.

  3. Locate fsdalloc.cpp.

  4. Double-click fsdalloc.cpp to open the source file.

    As shown in the following illustration, you're now looking at some of the private (shared) source that ships with Windows CE.

    Click here for larger image

    Locate the AllocFSD function within the source window.

  5. Set a breakpoint on the following line (by clicking on the line and hitting F9).

    pFSD = dlFSDList.pFSDNext
    

    Click here for larger image

    Now you're ready to download the operating system image.

To download the Windows CE image

  • Select Target | Attach Device.

The operating system image will be downloaded, and the emulator will be displayed. You will see a number of debug messages being displayed in the Platform Builder debug output window. Note that the Emulator image will hit the breakpoint in the file system driver before the shell of the operating system has loaded. Once the breakpoint has been hit, you can do a number of things, including View memory, View Registers, Call Stack, Single Step Code, and View local variables.

The breakpoint will get hit in the File System Driver loading code. At this point in the code, you can't determine which driver is getting loaded, but you can use Call Stack to step to a point where you can retrieve the name of the driver that is being loaded.

Click here for larger image

As shown in the preceding example, you can tell that a breakpoint has been hit because you have a yellow Current Instruction pointer displayed over the breakpoint and the word [break] on Platform Builder's caption bar.

To review the Call Stack interface

  1. Select View | Debug Windows | Call Stack.

    The Call Stack window, as shown in the following illustration, shows the function chain that brought you to the current breakpoint. You can use this to step to a point where the name of the driver is visible.

    Click here for larger image

    Double-click FSDMGR!FSDLoad within the Call Stack window (second line of the call stack). This will take you to the FSDLoad function, which contains a variable pInitData, which in turn contains the name of the driver that is being loaded. You can clearly see the call to AllocFSD((HMODULE)pInitData->hFSD). This is the function that contains the breakpoint, as shown in the following example.

    Click here for larger image

    You can use the Quick Watch window to view the contents of pInitData, as shown in the following example.

    Click here for larger image

    Right-click the variable pInitData.

  2. Select QuickWatch from the popup menu.

    The following data will be displayed, including the name of the driver that is stored in the string "szFileSysName"; the driver is "Relfsd".

    Click here for larger image

    Select Close.

    This clearly shows that the driver Relfsd.dll is loading. At this point, you could, if needed, single-step through the lines of code. However, for the purposes of this exercise, you should remove all breakpoints and allow the operating system to continue loading.

  3. Select Edit | Breakpoints (or press ALT+F9) to open the following dialog.

    Aa446910.windowsce5_basic31(en-us,MSDN.10).gif

  4. Click the Clear All Breakpoints toolbar button.

  5. Close the Breakpoint List dialog.

  6. Select Debug | Go to allow the Windows CE operating system image to finish loading.

The following illustration shows how the Windows CE operating system looks when running in the Emulator. Note that this is a fully functioning Windows CE operating system image, not using Microsoft Windows XP as a shim to pass calls down to the underlying operating system but is running as a full x86 CEPC.

Click here for larger image

Now you'll need to use the RegApp application.

To run the RegApp application on the Emulator

  1. Open My Device.

  2. Browse to the \Windows folder.

    All operating system files are hidden by default, so first you need to show the hidden files.

  3. Select View | Options.

  4. Disable the Do not show hidden files and folders and Hide protected operating system files (Recommended) options as shown in the following illutstration.

    Click here for larger image

    Click OK.

  5. Locate the RegApp application, as shown in the following illustration.

    Click here for larger image

    Run RegApp.exe.

    The contents of the registry key you added to the platform will be displayed in a message box as shown in the preceding illustration.

  6. Click OK to close the message box.

You have successfully modified the registry before building the operating system. In this case, you were looking for a specific key from the registry that is not part of the default operating system image. With Windows CE 5.0, user-created projects wrap up all the information needed to build in a stand-alone atomic project, and each project can define its own folders, registry information, files, databases, and platform dependencies.

Click here for larger image

In the next exercise, you will use the Kernel Tracker tool. Kernel Tracker is a graphical tool that provides a visual representation of a remote Windows CE system on a development workstation. The Kernel Tracker tool enables you to view thread interactions, internal dependencies, and system state information in a real-time environment. Kernel Tracker enables you to track down bugs related to thread interactions that are difficult to track with traditional development tools, including deadlock, missed deadline, or race conditions.

To start Kernel Tracker within Platform Builder

  • Select Tools | Remote Kernel Tracker.

    The Kernel Tracker program starts and will look similar to the window shown in the following illustration.

    Click here for larger image

    After the Kernel Tracker program has started, you need to attach the Kernel Tracker to your reference platform.

To connect to the reference platform

  1. Select Default Device, as shown in the following illustration.

    Click here for larger image

    Click OK.

    As shown in the following illustration, Kernel Tracker now displays each of the operating system components and the thread interaction between processes.

    Click here for larger image

    Launch Walktree either by using the Windows CE Command Window (s walktree) or by using Target | Run Program and selecting Walktree.

The following illustration shows how the Walktree application looks in the Remote Kernel Tracker. You can clearly see the interaction between the Walktree application and the KITL (Kernel Independent Transport Layer). Platform Manager uses the Kernel Independent Transport Layer (KITL) transport for communication between the development workstation and the target device over any hardware for which the OEM supplies an appropriate transport.

This example shows Kernel Tracker at 100-ms resolution. If you were to drop to a finer resolution, you could trace the flow from Walktree through KITL and back to the Walktree application.

Click here for larger image

The Remote Kernel Tracker displays information about known events, which could include synchronization events, threads, and process state. It can be useful to also display custom information from your application at runtime. For example, in the Walktree application, you might want to output the number of files enumerated into the Kernel Tracker stream. This would then be useful to compare the use of the KITL thread for enumeration of folders local to the Windows CE device and \Release folders.

This is extremely simple. You just use the CeLogData function. The following example shows how you can use CeLogData to output the current memory load.

MEMORYSTATUS g_MemStatus;

memset(&g_MemStatus,0x00,sizeof(g_MemStatus));
g_MemStatus.dwLength=sizeof(g_MemStatus);
GlobalMemoryStatus(&g_MemStatus);
DEBUGMSG (ZONE_MEMORY, (TEXT("Memory Load 
%d%%\n"),g_MemStatus.dwMemoryLoad));

CeLogData(TRUE, CELID_RAW_LONG, &g_MemStatus.dwMemoryLoad, (WORD) 
 (sizeof(DWORD)), 1, CELZONE_MISC);

In the preceding code example, you obtain the current memory load by calling GlobalMemoryStatus. You then call CeLogData by using the memory load as one of the parameters. In this case, you're outputting memory load whenever you allocate memory. Of course, you could output any useful information, including handles to events, threads, memory allocation, and so forth.

The following illustration shows how the CELOG data appears in the Remote Kernel Tracker tool. Note that memory load was at 14%.

Aa446910.windowsce5_basic40(en-us,MSDN.10).gif

You're now finished with the Walktree application and the Kernel Tracker.

To close the Remote Kernel Tracker application

  1. Switch to Remote Kernel Tracker.

  2. Select File | Exit.

    You will be prompted about whether you want to save the collected data, as shown in the following illustration.

    Aa446910.windowsce5_basic41(en-us,MSDN.10).gif

  3. Select No.

You can also disconnect Platform Builder from the target.

To disconnect from the target from within Platform Builder

  1. Select Target | Detach Device.
  2. Click OK to stop all running services.
  3. Click Yes to stop the debugger.
  4. To close the Remote Display application, simply hit the X in the top-right corner of the application.

Up to this point, you've used Platform Builder to create an application and then add it to your operating system image. However, sometimes you may have external files that need to be added to the Windows CE image, such as a .NET Compact Framework application, an eMbedded Visual C++ application (Win32, MFC, ATL), or bitmaps and audio files.

Following are the two ways you can add a custom file into the operating system:

  • Modify BIB files by hand.
  • Create a component to host the file or application.

In following exercise, you will use the CEFileWiz tool to wrap up a file and examine the output from this process.

First you will modify the RegApp application to load a bitmap from the Windows CE Object Store. You can use the Remote File Viewer to upload the bitmap file to the Emulator to test your program. Then you will modify the platform to include the application.

To load a bitmap from the Windows CE Object Store

  1. Switch to the FileView.

  2. Expand the RegApp application and Source Files.

  3. Open RegApp.cpp.

  4. Before the WinMain function, drop the GlobalVariable from CodeClip, as follows:

    // Global for the Bitmap...
    HBITMAP hAutumnBitmap;
    
  5. Locate the WM_CREATE handler in the WndProc (Windows Procedure).

  6. Immediately after the RegCloseKey(hKey) (before the end of the function), drop the LoadBitmap code from CodeClip, as follows:

       hAutumnBitmap=SHLoadDIBitmap(L"\\windows\\autumn.bmp");
    

    This function loads a bitmap from the \Windows folder.

Next you will rebuild the application, remake the operating system, and debug the application.

To rebuild and debug the application

  1. Right-click the RegApp project in Platform Builder File View, as shown in the following illustration.

    Click here for larger image

    Select Build Current Project.

    This rebuilds the application and copies the executable to the build release folder.

  2. Select Build OS | Make Run-Time Image.

    Once the operating system is built, you need to test the application without having the bitmap in the operating system image.

  3. Locate the SHLoadDIBitmap line in the WM_CREATE message handler.

  4. Click on this line, and press F9 to set a breakpoint.

  5. Download the operating system Target | Attach Device.

    The operating system will download, but the application won't start. You need to start this from Platform Builder or from the Emulator user interface.

You will use Windows CE Target Control to start and stop the application.

To start and stop the application by using Target Control

  1. Make sure Windows CE Target Control is visible (Target | CE Target Control), as shown in the following illustration.

    Aa446910.windowsce5_basic43(en-us,MSDN.10).gif

  2. Start the RegApp application by typing s regapp.

    The registry application should start, and you should hit the breakpoint on the call to SHLoadDIBitmap.

  3. Single-step the code (using F10) to move over the call to load the bitmap.

  4. Use your cursor to look at the data tip for hAutumnBitmap.

    The value of the HBITMAP variable should be 0x00000000, which shows that the bitmap has not been loaded (the expected behavior).

  5. Allow the application to continue running by pressing F5.

To end the process

  1. In the Target Control window, type gi proc to display a list of the current running processes. RegApp is listed as process #7 (P07) in the list of running processes, as shown in the following illustration.

    Click here for larger image

    Terminate the RegApp process by typing KP 7 into the CE Target Control window.

To upload the Autumn bitmap to the Emulator and retest the application

  1. In Platform Builder, select Tools | RemoteFileViewer.

  2. Select the DefaultDevice, and then click OK.

    This connects the Remote File Viewer to the currently downloaded Windows CE operating system image.

  3. Select the WindowsFolder in the Remote File Viewer window, as shown in the following illustration.

    Click here for larger image

    Select File | ExportFile.

  4. Browse to the CodeSnip folder (C:\CodeSnip\Bitmap).

  5. Select Autumn.bmp and click OK to upload the bitmap to the Windows folder on the Emulator.

  6. Start the RegApp application by typing s regapp.

    The registry application should start, and you should hit the breakpoint on the call to SHLoadDIBitmap.

  7. Single-step the code (using F10) to move over the call to load bitmap.

  8. Use your cursor to look at the data tip for hAutumnBitmap.

    The value of the HBITMAP variable should now have an assigned value, which shows that the bitmap has now been loaded (the expected behavior).

  9. Select Target | DetachDevice to detach Platform Builder from the Emulator.

The application behaves as expected. You can now add the bitmap to the operating system image. This operation is controlled by a BIB file.

To add the bitmap into the operating system

  1. Copy the bitmap to the build release folder.
  2. Modify the project.bib file to include the bitmap into the final operating system image (nk.bin).

To add the bitmap

  1. Run the CEFileWiz application. (There should be a shortcut on your desktop or in the C:\CodeSnip folder).

  2. Select AddFiles, and browse to the C:\CodeSnip\Bitmap.

  3. Select Autumn.bmp and click Open.

    Note that the bitmap will be added to the "FILES" section of the operating system.

  4. In CEFileWiz, enter a Component Name of AutumnBitmap.

  5. Select the MyPlatform platform from the list of available platforms.

  6. Select Build.

    You've now generated all the files needed to wrap up the Autumn Bitmap into your operating system. One of the files created is a .CEC (CE Component) file. You can add this component to your catalog and from there add the catalog component to your operating system image.

    The following illustration shows the files that have just been created. (Notice the AutumnBitmap.cec file [top right].)

    Click here for larger image

    Close CEFileWiz.

  7. In Platform Builder, select File | ManageCatalogItems.

  8. Select Import.

  9. Browse to C:\wince500\PBWorkspaces\MyPlatform\AutumnBitmap.

  10. Select AutumnBitmap.cec.

  11. Select Open and click OK.

    You now have an AutumnBitmap Files Component in the catalog, as shown in the following illustration.

    Click here for larger image

    Right-click AutumnBitmapFilesComponent, and select AddToOSDesign.

The project list for the MyPlatform workspace has now been updated to include a new project, the AutumnBitmap project. You can see an expanded view of this project in the following illustration.

Click here for larger image

Now you can examine some of the interesting files that make up this project by taking the following steps:

  1. Double-click the AutumnBitmap.bib file.

    ;
    ; Copyright (c) 2004 Microsoft Corporation.  All rights reserved.
    ;
    ;
    ; NOTE: If any of the .EXEs included in this component are .NETCF,
    ; you will need to move them to the FILES section.
    ;
    MODULES
    ;  Name            Path                                           
    Memory Type
    ;  --------------  ---------------------------------------------  --
    ---------
    
    FILES
    ;  Name            Path                                           
    Memory Type
    ;  --------------  ---------------------------------------------  --
    ---------
    Autumn.bmp    $(_FLATRELEASEDIR)\Autumn.bmp            NK
    

    The BIB file contains two sections, MODULES and FILES. The modules section is reserved for executable code (applications, and drivers), with one exception: .NET Compact Framework applications must be in the FILES section. FILES are non-executable code (with the exception of .NET Compact Framework applications); this is where your bitmap lives.

  2. Double-click the AutumnBitmap.dat file.

    In CEFileWiz, you left the default location for the file to be the \Windows folder. You could have moved this to another location, but the RegApp application expects to load the bitmap from the \Windows folder. The .DAT file is used to map applications and files out of the \Windows Folder and into another location.

    root:-Directory("\"):-Directory("Windows")
    Directory("\Windows"):-File("Autumn.bmp","\windows\Autumn.bmp")
    

The .DAT file creates the \Windows folder (even though this is already part of the operating system image) and then maps the autumn.bmp file from \Windows to \Windows (which has no effect on the file in this case).

  1. Double-click the postlink.bat file.

    copy "C:\CodeSnip\Bitmap\Autumn.bmp" "%_FLATRELEASEDIR%"
    

    This is where you copy the Autumn.bmp file from it's home folder to the build release directory.

In the next two exercises, you will build the dummy application, which will force the bitmap to be copied to the build release folder. You will then re-make the operating system.

To build the dummy application

  1. Right-click the AutumnBitmap project in the Platform Builder File View.

  2. Select Build Current Project.

    At this point, you could confirm that the bitmap is in your build release folder.

  3. Select Build | Open Release Directory.

  4. Type dir A*.bmp.

    The following illustration indicates what should now be displayed.

    Click here for larger image

    To re-make the operating system image

  5. Select Build OS | Make Run-time Image.

  6. Select Target | Attach Device.

    After the operating system has been downloaded to the Emulator, run the RegApp application. Note that your breakpoint should still be in place.

  7. Using the Target Control window, start the RegApp application by typing s regapp.

    The registry application should start, and you should hit the breakpoint on the call to SHLoadDIBitmap.

  8. Single-step the code (using F10) to move over the call to load the bitmap.

  9. Use your cursor to look at the data tip for hAutumnBitmap.

    The value of the HBITMAP variable should now have an assigned value. This shows that the bitmap has now been loaded (the expected behavior).

Summary

Following is a summary of the exercises provided in this article:

  • Created a Platform Workspace
  • Customized the platform by adding drivers and applications
  • Added custom Registry information to the Platform
  • Enabled Profiling and Kernel Tracking
  • Built an operating system image
  • Set Kernel (Shared) source breakpoints
  • Downloaded an operating system to hardware
  • Worked with breakpoints and call stacks
  • Examined the target registry with your own custom application
  • Used the Remote Kernel Tracker to examine thread activity in an application
  • Included an external file into the operating system image

Congratulations! You've completed all the steps.