CE5.0 - Building a Run-Time Image for the Emulator

Tutorial: Building a Run-Time Image for the Emulator

This guide helps you become familiar with Platform Builder and the new functionality of the Windows CE operating system (OS). It provides a step-by-step tutorial for creating and debugging a custom run-time image and a simple application that runs in the Emulator.

In this tutorial you create an Enterprise Web Pad running the Hello World application that runs in the Emulator.

This tutorial makes the following assumptions:

• You have installed Platform Builder and Windows CE as described in the installation instructions.
• You have selected the Emulator as one of the installed CPUs.
• You are familiar with the terms defined in .

This tutorial takes approximately 50 minutes to complete.

In this tutorial, you complete the following steps:

• Tutorial Step 1: Creating a Custom OS Design for the Emulator
• Tutorial Step 2: Building the Custom Run-Time Image for the Emulator
• Tutorial Step 3: Setting Up a Connection to the Emulator and Downloading the Run-Time Image
• Tutorial Step 5: Localizing the Run-Time Image for the Emulator
• Tutorial Step 7: Running the Application in the Emulator on the Custom Run-Time Image

Tutorial Step 1: Creating a Custom OS Design for the Emulator

In this step, you use the New Platform Wizard to create a custom OS design.

To create a custom OS design for the Emulator

1. On the development workstation, launch the Platform Builder application.
2. From the File menu, choose New Platform, and when the New Platform Wizard appears, choose Next.
3. In the Name box, enter MyOSDesign as the name for your OS design.
4. In the Path box, enter or select the path to the root directory where you want your OS design to be located; then choose Next.

   For this tutorial, accept the default location, which is %_WINCEROOT%\PBWorkspaces\MyOSDesign.

5. From the list of available board support packages (BSPs) installed on your development workstation, select EMULATOR: X86 and choose Next.
6. From the list of available OS design templates, select Enterprise Web Pad and choose Next.
7. Accept the default selections for Applications & Media by choosing Next.
8. Accept the default selections for Networking & Communications by choosing Next.
9. Acknowledge the Special Notifications by choosing Next.
10. Save your settings and close the New Platform Wizard by choosing Finish.

    Platform Builder creates two configurations for your OS design:

    • A Debug configuration
    • A Release configuration

After these files are created, you now build a custom run-time image.

Tutorial Step 2: Building the Custom Run-Time Image for the Emulator

After you create an OS design, you can build a run-time image based on that OS design. In this step, you build a custom run-time image from the OS design you created in Tutorial Step 1.

For this tutorial, when you build the custom run-time image, choose a Debug configuration for your OS design. By building a run-time image based on the default Debug configuration, you can later debug your run-time image on the target device from Platform Builder.

In addition, because the size of a run-time image based on a Debug configuration is greater than the size of a run-time image based on a Release configuration, you must also change the value of an environment variable to accommodate a larger run-time image.

To build the custom run-time image for the Emulator

1. From the Platform Builder Build OS menu, choose Set Active Configuration.
2. From the list of configurations, select EMULATOR: X86_Debug and choose OK.

   Platform Builder updates the list of Catalog items in your OS design.

3. From the Platform menu, choose Settings.
4. In the Configuration list, be sure EMULATOR: x86_Debug is selected.
5. Choose the Build Options tab and verify that the following check boxes are selected:
   • Enable CE Target Control Support (SYSGEN_SHELL=1)
   • Enable Eboot Space in Memory (IMGEBOOT=1)
   • Enable Full Kernel Mode (no IMGNOTALLKMODE=1)

     Enabling full kernel-mode for your OS design increases system performance in the run-time image. For more information, see Full-Kernel Mode

   • Enable KITL (no IMGNOKITL=1)
   • Run-Time Image Can be Larger than 32 MB (IMGRAM64=1)
6. Close the Platform Settings dialog box and save your changes by choosing OK.
7. Choose the Build OS menu and verify that the following are selected:
   • Copy Files to Release Directory after Build
   • Make Run-Time Image After Build

   By default, these are selected when you create a workspace in Platform Builder.

8. To build a run-time image based on your OS design, from the Build OS menu, choose Build and Sysgen.

   For information about other build options you can choose, see Build OS Menu Options.

   The time required by Platform Builder to build the run-time image depends on the number of Catalog items in the OS design.

   In this example, you are building a run-time image based on a large OS design that contains many items, so it can take up to 20 minutes to build the OS image.

9. Observe the build process in Platform Builder by viewing the output on the Build tab of the Output window.

   When the build is complete, you see the following message: MyOSDesign - 0 error(s), XX warning(s).

You can now set up a connection to the Emulator and download the run-time image.

Tutorial Step 3: Setting Up a Connection to the Emulator and Downloading the Run-Time Image

In this step, you set up and configure a connection to the Emulator; then you download the custom run-time image to the Emulator.

To set up a connection to the Emulator and download the run-time image

1. From the Target menu, choose Connectivity Options.
2. Under Service Configuration, choose Kernel Service Map.
3. From the Download list box, choose Emulator.
4. Choose the associated Settings button.
5. Be sure the settings for Display are set to 640x480x16; otherwise, the Emulator window might not appear properly on your display.
6. In the Memory (MB) box, be sure memory is set to 64 and then choose OK.
7. From the Transport list box, select Emulator.
8. From the Debugger list box, be sure KdStub is selected.
9. Under Service Configuration, choose Core Service Settings.
10. Under Download Image, verify that Always is selected.
11. Under KITL Settings, verify that the following check boxes are selected:
    • Enable KITL on device boot
    • Clear memory on soft reset
    • Enable access to desktop files
12. To save your changes and close the dialog box, choose Close.

    - or -

    To save your changes and keep the dialog box open, choose Apply.

    You have configured the services that allow you to connect to the Emulator.

    Now you can establish a connection to the Emulator and download the run-time image.

13. From the Target menu, choose Attach Device.

    A window appears, displaying the progress of the download to the Emulator. Then the MyOSDesign - Emulator for Windows CE window appears.

14. Wait until the OS appears in the MyOSDesign - Emulator for Windows CE window.

    The length of time required to display the OS depends on the size of the run-time image being downloaded.

    For this tutorial, the OS appears in about a minute.

    While the run-time image is being downloaded, in Platform Builder, you can see intermittent activity in the Debug tab of the Output window.

    When the OS boots successfully, the Windows CE OS appears in the MyOSDesign - Emulator for Windows CE window.

You can now debug the OS.

Tutorial Step 4: Debugging the OS on the Emulator Using the Kernel Debugger

After you download and boot the run-time image in the Emulator, you can debug the OS.

By default, when the OS boots, Platform Builder starts the kernel debugger and displays the Debug toolbar.

To debug the run-time image, you must halt the running OS, because breakpoints cannot be set while the OS is running. You then use the kernel debugger to debug your custom OS.

To debug the OS on the Emulator using the kernel debugger

1. From the Platform Builder Debug menu, choose Break.

   This halts the running OS on the Emulator, which does not respond to user input while in this state.

2. From the File menu, choose Open.
3. Browse to %_WINCEROOT%\Platform\Emulator\Src\Drivers\Kbdmouse\Emulkbms, select ps2mouse.cpp, and then choose Open.

   You have opened the Ps2mouse.cpp file, which contains source code for the mouse driver.

4. From the Edit menu, choose Find.
5. In the Find what box, type _move and choose Find Next.

   You jump to a section of code in the Ps2mouse.cpp file that handles a mouse move event.

6. Set a breakpoint in the source code at the mouse move event by pressing the F9 key.

   A red dot in the margin shows that the breakpoint has been set.

7. From the Debug menu, choose Go.
8. In the MyOSDesign - Emulator for Windows CE window, move the cursor over the window.

   The breakpoint activates.

9. Switch to the Platform Builder window.

   A yellow instruction point or current instruction arrow on the breakpoint symbol appears in the source code.

10. Remove the breakpoint you set by doing one of the following:
    • From the Debug toolbar, choose Breakpoints and then choose Clear All Breakpoints.
    • In the source code, right-click the line where you set the breakpoint; then from the context menu, choose Remove Breakpoint.
    • Use the ALT+9 keyboard shortcut to access the Breakpoint List window; then choose Clear All Breakpoints.
11. From the Debug menu, choose Go.

    You have successfully halted the OS, set and activated a breakpoint in one of the drivers, and then removed the breakpoint.

    Follow the remaining steps to stop debugging the OS.

12. From the Debug menu, choose Stop Debugging.
13. From the Target menu, choose Detach Device.
14. Shut down the Emulator by accessing the window for the Emulator; then from the Emulator menu, choose Shut Down.

    The Emulator window closes.

After you finish debugging, you can localize your run-time image.

Tutorial Step 5: Localizing the Run-Time Image for the Emulator

Windows CE offers the ability to localize a run-time image into several languages. In this step, you localize the custom Enterprise Web Pad OS design into German for the locale of Germany.

To localize the OS design for the Emulator

1. From the Platform Builder Platform menu, choose Settings.
2. In the Configuration box, select EMULATOR: x86_Release.
3. Choose the Locale tab.
4. From the Default Language list, select German (Germany); then verify that the Localize the build check box is selected.
5. Close the Platform Settings dialog box by choosing OK.
6. From the Build OS menu, verify that the following options are selected:
   • Copy Files to Release Directory After Build
   • Make Run-Time Image After Build
7. From the Build OS menu, choose Build and Sysgen.

   It can take up to 20 minutes to rebuild the run-time image with the changed build options you selected.

   When the build process is complete, you see the following message: MyOSDesign - 0 error(s), XX warning(s).

8. From the Target menu, choose Attach Device.

   In approximately one minute, the localized run-time image finishes downloading to the Emulator.

9. In the MyOSDesign - Emulator for Windows CE window, verify that the icons in the displayed OS are labeled in German.
10. From the Platform Builder Target menu, choose Detach Device and then choose OK.
11. In the window for the Emulator, from the Emulator menu, choose Shut Down.

You have created, built, and downloaded a localized run-time image.

You can now create and build an application based on your run-time image.

Tutorial Step 6: Creating and Building an Application for the Emulator

In this step, you create and build a simple application using Platform Builder.

To create and build an application for the Emulator

1. From the Platform Builder File menu, choose New Project or File.
2. Choose the Projects tab and select WCE Application.
3. In the Project name box, type Hello, verify that Workspace project is selected, and choose OK.
4. In the Feature name box, for the purposes of this tutorial, name your application Hello and choose Next.

   This name is used in the Readme.txt file that Platform Builder creates, and is optional.

5. Choose A typical "Hello World!" application and then choose Finish.
6. In the Workspace window, select the FileView tab; then from the Projects node, select your application.
7. From the Build Project menu, select the following:
   • Clean Before Building
   • Make Run-Time Image After Build
8. Build the application by choosing Build Current Project from the Build Project menu.

   When the build is complete, in the Build window, you see the following message: Hello.exe - 0 error(s), 0 warning(s).

   To see this message, you might need to jump to the end of the output by pressing the CTRL and END keys simultaneously.

   You have created an application.

You can now run the application in the Emulator.

Tutorial Step 7: Running the Application in the Emulator on the Custom Run-Time Image

In this step, you run the newly created Hello.exe application in the Emulator.

By default, Hello.exe is not included in the run-time image. It is downloaded to the target device from the development workstation at run time. This allows you to further develop the application without rebuilding the run-time image after each change you make to the application.

To run the application in the Emulator on the custom run-time image

1. From the Platform Builder Target menu, choose Attach Device.

   In approximately two minutes, your localized OS appears in the MyOSDesign - Emulator for Windows CE window.

2. From the Target menu, choose Run Programs.
3. In the Available Programs list, select Hello.exe and choose Run.

   The Hello.exe application downloads from the development workstation to the Emulator. The application then runs in the Emulator.

4. In the MyOSDesign - Emulator for Windows CE window, verify that the Hello.exe application has run successfully..

   You have run a custom application on the Emulator.

5. Shut down the Emulator so you can create and export a software development kit (SDK):
   1. From the Platform Builder Target menu, choose Detach Device.
   2. In the window for the Emulator, from the Emulator menu, choose Shut Down.

You can now create and export an SDK.

Tutorial Step 8: Creating an SDK for eMbedded Visual C++

After you customize your OS design and boot and debug the run-time image, you can use Platform Builder to create, configure, and build an SDK for the run-time image.

Developers can use this SDK to create applications based on the run-time image you created.

In this step, you create an SDK for Microsoft® eMbedded Visual C++®.

To create and build an SDK for eMbedded Visual C++

1. From the Platform Builder Platform menu, choose SDK and then choose New SDK.
2. When the SDK Wizard appears, choose Next.
3. In the Product name that is displayed when .msi file runs box, type MyOSDesignSDK.
4. In the Manufacturer name box, type MyCompany, and then choose Next.
5. Verify that the eMbedded Visual C++ 4.0 support check box is selected, and then choose Next.
6. On the final page, choose Close this wizard and continue configuring your SDK.

   The wizard closes and the SDK Settings dialog box opens.

7. In the SDK Settings dialog box, choose the EULA/Readme tab and select the Include custom end-user license agreement check box.
8. In the End-user license agreement path box, enter the location and name of a file as a Rich Text Format (.rtf) file that you want to use as a sample custom End User License Agreement (EULA).

   - or -

   Choose Browse, select an .rtf file that you want to use as a sample EULA, and then choose Open.

   The custom EULA you include is displayed in a separate dialog box when the SDK is installed.

9. Choose the Emulation tab, and then, in the Configuration field, verify that you have selected a build configuration for your SDK.

   For this tutorial, select a Debug configuration.

   Selecting a Debug configuration may help prevent errors from occurring when you build your SDK.

10. Choose OK to close the window and apply the settings to your SDK.
11. From the Platform menu, choose SDK and then choose Build SDK.

    The SDK Wizard dialog box displays information while the SDK is being built.

12. When the build is complete, to close the dialog box, choose Done.

    Your SDK is in the MyOSDesign_SDK.msi file in the %_WINCEROOT%\PBWorkspaces\MyOSDesign\SDK directory.

You have completed this tutorial and successfully created and debugged a custom run-time image and a simple application that runs in the Emulator. You have also successfully created an SDK for your run-time image.