CE5.0 - Building a Run-Time Image for a CEPC

Tutorial: Building a Run-Time Image for a CEPC

This guide helps you become familiar with Platform Builder and the new functionality of Windows CE. It provides a step-by-step tutorial for building and debugging a custom run-time image. The tutorial also shows you how to run the OS on a CEPC.

In this tutorial you build a run-time image for an Enterprise Web Pad, add a Hello World application to the run-time image, and then boot the run-time image on a CEPC.

This tutorial makes the following assumptions:

• You installed Platform Builder and Windows CE as described in the installation instructions
• You selected x86 as one of the CPUs to install on a CEPC that meets the following minimum system requirements.
  • 64 MB RAM

    Run-time images based on Debug configurations require at least 64 MB of RAM to run.

    Run-time images based on Release configurations require at least 32 MB of RAM.

  • A mouse
  • An Ethernet card

    Note   Microsoft recommends that the CEPC Ethernet card be a NE2000 compatible network adapter. For information on additional configuration if the CEPC Ethernet card has a DMA-capable Ethernet controller, see article Q317432 at this .

• You are familiar with the terms defined in .

In this tutorial, which takes approximately 90 minutes to complete, you complete the following steps:

• Tutorial Step 1: Creating a Custom OS Design for a CEPC
• Tutorial Step 2: Building the Custom Run-Time Image for the CEPC
• Tutorial Step 4: Setting Up a Connection to the CEPC and Downloading the Run-Time Image
• Tutorial Step 5: Debugging the OS on the CEPC Using the Kernel Debugger
• Tutorial Step 6: Localizing the Run-Time Image for the CEPC

General Tips

Use a null modem cable to connect the COM1 port of the target CEPC to your development workstation.

Keep a Microsoft HyperTerminal window open and connected at 38400 baud and 8-N-1. This allows you to see the debug information sent during boot, which is useful for troubleshooting. For more information, see Configuring HyperTerminal for BSPs.

Tutorial Step 1: Creating a Custom OS Design for a CEPC

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

After you create an OS design, you can build a run-time image based on the OS design that runs on a CEPC.

To create a custom OS design for a CEPC

1. On the development workstation, start 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 MyCEPCOSDesign as the name for your OS design.
4. In the Location field, enter or select the path to the root directory where you want your OS design to be located, and then choose Next.

   By default, your OS design is in %_WINCEROOT%\PBWorkspaces\MyOSDesign. For this tutorial, accept the default location and choose Next.

5. From the list of available board support packages (BSPs) installed on your development workstation, select CEPC: X86, and then choose Next.
6. From the list of available OS design templates, select Enterprise Web Pad.
7. To accept the default selections for Applications & Media, choose Next.
8. To accept the default selections for Networking & Communications, choose Next.
9. To acknowledge the Special Notifications, select the Notification Acknowledged check box for each notification, and then choose Next.
10. To close the New Platform Wizard, choose Finish.

Platform Builder generates the initial files for Debug and Release configurations of your OS design. When these files are created, control returns to Platform Builder, and you can continue modification of the OS design.

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

After you create an OS design, you can build a run-time image based on that OS design.

In this step, you build a run-time image from the MyCEPCOSDesign OS design you created.

Before building the custom run-time image, you must choose a Debug configuration for your OS design. When you choose a Debug configuration, you can later debug your run-time image.

You must also change the value of an environment variable to accommodate the larger run-time image. The size of a run-time image based on a Debug configuration of an OS design is greater than the size of a run-time image based on a Release configuration.

To build the custom run-time image for the CEPC

1. On the development workstation, from the Platform Builder Build OS menu, choose Set Active Configuration.
2. From the list of configurations, select CEPC: X86_Debug and then choose OK.
3. From the Platform menu, choose Settings.
4. From the Configuration list, select CEPC: x86_Debug.
5. Choose the Build Options tab and verify that the following check boxes are selected:
   • Enable CE Target Control Support
   • Enable Eboot Space in Memory
   • Enable Full Kernel Mode
   • Enable KITL
   • Run-Time Image Can be Larger than 32 MB

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

6. To close the Platform Settings dialog box and save your changes, choose OK.
7. From the Build OS menu, verify that Copy Files to Release Directory after Build and Make Run-Time Image After Build are selected.

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

8. From the Build OS menu, choose Build and Sysgen.

   Select this option if you want to build all the files in your OS design.

The time required by Platform Builder to build the run-time image depends on the number of Catalog items that are included in the OS design. In this example, you are building a large run-time image based on an OS design which contains many items, so it may take as long as 20 minutes to build the run-time image.

You can observe the build process in Platform Builder. The progress of the build process is displayed on the Build tab of the Output window. When the build is complete, you see the following message: MyCEPCOSDesign - 0 error(s), XX warning(s).

Tutorial Step 3: Creating a Boot Floppy Disk for the CEPC

To use your CEPC for the first time, you must first install an application that creates a boot floppy disk for the CEPC, and then run the application to create the boot floppy disk.

To create a boot floppy disk for the CEPC

1. On the development workstation, open Windows Explorer, navigate to \Cepb\Utilities, and run the utility Websetup.exe.

   The Setup Webimage dialog window appears.

2. Install WebImage in the Windows directory of your development workstation by choosing Install.
3. In \Cepb\Utilities, locate and run the disk image file Cepcboot.144.

   The Web Image NT dialog window appears.

4. On the development workstation, insert a floppy disk into a floppy disk drive.

   If you want to format the floppy disk before creating the boot floppy disk, select the Format before making disk check box.

5. Start the creation process by choosing A Drive or B Drive, depending on which floppy disk drive contains the floppy disk.
6. Close the Web Image NT window after the boot floppy disk is created by choosing Cancel.
7. Verify that the boot floppy disk contains the correct files.

   The following table shows the files the boot floppy disk should contain.

   Note   To view all files created, be sure your browser settings allow the display of hidden and system files.

   File	Description
   Autoexec.bat	Batch file that Microsoft MS-DOS requires.
   Command.com	Command file that MS-DOS requires.
   Config.sys	System file that MS-DOS requires.
   Drvspace.bin	Binary file that adjusts the settings in the Drvspace.ini file to mount a drive.
   Eboot.bin	Binary file that constitutes the Ethernet boot loader.
   Himem.sys	System file that MS-DOS requires.
   Io.sys	System file that MS-DOS requires.
   Loadcepc.exe	Executable file that loads the Eboot.bin boot loader image.
   Msdos.sys	System file that MS-DOS requires.
   Readme.txt	Text file that contains instructions.
   Sboot.bin	Binary file that constitutes the serial boot loader.
   Sys.com	MS-DOS application file.
   Vesatest.exe	MS-DOS file that tests the VGA BIOS on the video card to ensure compatibility with the Windows CE–based default display driver. The Readme.txt file provides additional information about this file.

8. Edit the Autoexec.bat file on the boot floppy disk, which uses the settings for a PCI Ethernet card by default, to match the settings for your Ethernet card:
   • If you have a PCI Ethernet card, verify that NET_IRQ is set equal to 0 and NET_IOBASE is set equal to 0.
   • If you have an ISA Ethernet card, set NET_IRQ equal to the setting for your NIC IRQ and NET_IOBASE equal to the setting for your NIC I/O base.

   If you do not know what type of Ethernet card you have, use the settings for PCI.

   If you cannot complete the next step of the tutorial with the settings for PCI, use the settings for ISA instead.

Tutorial Step 4: Setting Up a Connection to the CEPC and Downloading the Run-Time Image

In this step, you set up and configure an Ethernet connection to the CEPC, and then you download the custom run-time image to the CEPC.

Note   Before you start the following procedure, verify that you have connected the development workstation and CEPC to the same subnet. This might prevent problems with successfully downloading the run-time image to your CEPC.

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

1. On the development workstation, from the Platform Builder Target menu, choose Target Device Connectivity Options.
2. Choose Kernel Service Map.
3. From the Download list box, choose Ethernet.
4. Choose the associated Settings button, insert the boot floppy disk you created in the previous step into the floppy disk drive of the CEPC, and start the CEPC.

   After the CEPC boots, its screen is blank and the name of the CEPC appears in the Available Devices list.

   Note   If the name of the CEPC does not appear in the Available Devices list, reboot the CEPC. If the name of the CEPC still does not appear, verify that you made the correct changes to the Autoexec.bat file on the boot floppy disk as described in . If you still have a problem, see How to Set up a CEPC to troubleshoot the CEPC.

5. From the Available Devices list, select the name of the CEPC and choose OK.
6. From the Transport list box, choose Ethernet.
7. Choose Core Service Settings.
8. Under Download Image, verify that Always is selected and choose OK.
9. 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
10. 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 CEPC. You can now establish a connection to the CEPC and download the run-time image.

11. From the Target menu, choose Attach Device.
12. Restart the CEPC.

    You must restart the CEPC because the run-time image does not download until it receives a BOOTME message from the CEPC. The CEPC sends BOOTME messages for only a short period of time.

13. Wait until the run-time image downloads to the CEPC.

    The length of time required to download a run-time image depends on the size of the run-time image being downloaded and the speed of the Ethernet connection.

    The run-time image in this example can take several minutes to download. While the run-time image downloads, a dialog box in Platform Builder displays the progress of the download.

After the run-time image downloads and the OS boots, the desktop for the Windows CE OS appears on the display for the CEPC. You can now debug the OS.

Tutorial Step 5: Debugging the OS on the CEPC Using the Kernel Debugger

After you download and boot the run-time image on the CEPC, you can debug the OS.

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

To debug the run-time image, you must halt the running OS. Breakpoints cannot be set while the OS is still running.

In this step, you use the kernel debugger to debug your custom OS.

To debug the OS on the CEPC using the kernel debugger

1. On the development workstation, from the Platform Builder Debug menu, choose Break.

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

2. From the File menu, choose Open.
3. Browse to %_WINCEROOT%\Public\Common\Oak\DRIVERS\KEYBD\PS2_8042, select ps2mouse.cpp, and 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 have jumped to a section of code in the Ps2mouse.cpp file that handles a mouse move event.

6. At the mouse move event, set a breakpoint in the source code by pressing the F9 key.

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

7. From the Debug menu, choose Go.
8. Move the mouse for the CEPC.
9. Switch to the Platform Builder window.

   The breakpoint activates. A yellow instruction point or current instruction arrow appears on the breakpoint symbol.

10. To remove the breakpoint that you set, do 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 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.

    Control returns to Platform Builder.

13. From the Target menu, choose Detach Device and then choose OK.

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

Tutorial Step 6: Localizing the Run-Time Image for the CEPC

In Windows CE, you can localize a run-time image by selecting from several foreign languages.

In this step, you localize the custom Enterprise Web Pad OS design into German for the locale of Germany and then build the run-time image based on that OS design.

To build a localized run-time image for the CEPC

1. On the development workstation, from the Platform Builder Platform menu, choose Settings.
2. In the Configurations box, verify that CEPC: X86_Debug is selected.
3. Choose the Locale tab.
4. From the Default Language box, choose German (Germany) and 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.

   Selecting this option builds the changed files in your OS design.

   It can take up to 20 minutes to build the run-time image.

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

8. Reboot the CEPC.
9. On the development workstation, from the Platform Builder Target menu, choose Attach Device.

   When the localized run-time image finishes downloading to the CEPC, the CEPC initializes and displays the OS.

10. Verify that the icons in the CEPC OS user interface (UI) are labeled in German.
11. On the development workstation, from the Platform Builder Target menu, choose Detach Device and then choose OK.

    Control returns to Platform Builder.

You have successfully created, built, and downloaded a localized run-time image. You can now create and build an application.

Tutorial Step 7: Creating and Building an Application for the CEPC

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

To create and build an application for the CEPC

1. From the Platform Builder File menu, choose New Project or File.
2. Choose the Projects tab and then select WCE Application.
3. In the Project name box, type Hello, choose Workspace project, and then 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, on the FileView tab, from the Workspace Projects node, select your application.
7. From the Build Project menu, verify that the following are selected:
   • 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 successfully created an application by completing this step. You can now run the application on the CEPC.

Tutorial Step 8: Running the Application on the CEPC

In this step, you run the newly created Hello.exe application on the CEPC.

By default, the Hello.exe application 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 each time you change the application.

To run the application on the CEPC

1. Reboot the CEPC.
2. On the development workstation, from the Platform Builder Target menu, choose Attach Device.
3. From the Target menu, choose Run Programs.
4. In the Available Programs list, select Hello.exe and then choose Run.

   The Hello.exe application downloads from the development workstation to the CEPC. The application then runs on the CEPC.

5. Verify that the Hello.exe application has successfully run and that it appears on the CEPC display.

   You have successfully run a custom application on the CEPC.

6. Disconnect Platform Builder from the CEPC at the development workstation by using the Platform Builder Target menu to choose Detach Device; then choose OK.

   This is so you can create and export a software development kit (SDK).

   You can now create and export an SDK.

Tutorial Step 9: Creating an SDK

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

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

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

To create and build an SDK

1. From the Platform menu, choose SDK and then choose New SDK.
2. When the SDK Wizard appears, choose Next.
3. In the Product name that appears when .msi file runs box, type MyCEPCOSDesignSDK.
4. In the Manufacturer name box, type MyCompany and choose Next.
5. Verify that the eMbedded Visual C++ 4.0 support check box is selected and 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 End-user license agreement check box.
8. In the End-user license agreement path box, enter the location and name of an .rtf file you want to use as a sample custom End-User License Agreement (EULA).

   - or -

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

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

9. Choose the CPU tab.
10. In the Configuration box, verify that you have selected a Debug configuration for your SDK; if not, choose Edit and select a Debug configuration for your SDK.

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

11. Close the dialog box and apply the settings to your SDK by choosing OK.
12. From the Platform menu, choose SDK and then choose Build SDK.

    While the SDK is being built, the SDK Wizard dialog box displays build information.

13. Close the dialog box by choosing OK.
14. When the build is complete, choose Done.

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

You have completed this tutorial, created and debugged a custom run-time image and a simple application that runs on a CEPC, and created an SDK for your run-time image.