Microsoft Windows CE Platform Builder 2.12 Getting Started Guide

Microsoft Corporation

June 1999

Summary: Provides an overview of how to use Platform Builder to build a custom Microsoft® Windows CE® operating system (OS) for a hardware development platform. Includes instructions for installing Platform Builder, information about building a Windows CE PC-based hardware development platform (CEPC), and a tutorial that demonstrates how to adapt the Windows CE OS for a CEPC. Also includes information about Microsoft Technical Support resources for Platform Builder. (15 printed pages)

Contents

Hardware and Software Requirements
Installing Platform Builder
Building a CEPC
Building and Running an OS Image
For More Information

Hardware and Software Requirements

The following are the hardware and software requirements for Platform Builder:

• A desktop computer with an x86-based central processing unit (CPU) supported by Microsoft Windows NT®.
  
  
• Microsoft Windows NT Workstation version 4.0 OS with Service Pack 3 or later.
  
  
• 64 MB of RAM is recommended.
  
  
• 830 MB of available hard disk space for a typical, single CPU installation or 4.9 GB for installation of the entire Platform Builder product.
  
  
• A CD-ROM drive that is compatible with the multimedia desktop computer specification.
  
  
• A monitor with video graphics adapter (VGA) or higher resolution. Super VGA is recommended.
  
  
• A Microsoft Mouse pointing device or compatible pointing device.
  
  
• A bidirectional parallel port is recommended.
  
  
• A serial port or Ethernet network card for debugging support. A local area network (LAN) hub is recommended.

Installing Platform Builder

Platform Builder is distributed on multiple compact discs (CDs).

The Platform Builder Setup application, Setup.exe, performs the following tasks:

• Defines the system environment variables WINCEROOT and _FLATRELEASEDIR, which are required for the build process.
  
  
• Copies the Platform Builder files to the installation directory defined by the environment variable _WINCEROOT. The default directory is C:\WINCE212.
  
  
• Adds the program group Microsoft Windows CE Platform Builder 2.12. Setup.exe copies the files from the CDs to the development workstation.

To install Platform Builder

1. Log onto the development workstation with Windows NT administrator privileges.
   
   
2. Run Setup.exe from the root directory on the Platform Builder CD number 1.
   
   
3. When the Welcome dialog box is displayed, follow the on-screen instructions.

Note   To reduce the installation size of Platform Builder, you can deselect the CPUs you do not need in the CPU Selection dialog box and deselect options in the Custom Options dialog box. To access the Custom Options dialog box, choose the Options button in the CPU Selection dialog box.

To verify that Platform Builder is installed correctly, open a command prompt window and type "set _winceroot." The _winceroot environment variable specifies the fully qualified path of the directory in which Platform Builder is installed. The following table explains the messages returned by the Set command.

Building a CEPC

The CEPC is one of two hardware development platforms supported by Platform Builder. This guide provides information for setting up and using only a CEPC. This information is also available on the Microsoft Windows CE Web site at http://www.microsoft.com/windowsce/.

This section recommends specific hardware components and configurations for the CEPC. Other basic input/output systems (BIOS), motherboards, and configurations can be used to build a CEPC; however, because Windows CE is not a Plug and Play system, it requires plug-in cards that live at fixed slots and use fixed resources such as interrupt request lines (IRQs) and I/O base addresses. Therefore, if you use different hardware, you must set up the BIOS and hardware configuration to match the Windows CE operating system. For this reason, we strongly suggest that you use the recommended CEPC hardware components and configurations described in this section.

Hardware Requirements for a CEPC

The hardware required to build a CEPC is the CPU, display card, and other peripherals. The following is a list of recommended CEPC components. These components are off-the-shelf products. The typical cost of building a CEPC based on this configuration ranges from $300 to $400, depending on the number of peripheral cards.

The following table lists the essential hardware for the CEPC.

The following list provides additional information about essential hardware for the CEPC:

• The difference between Asus P5A and P5A-B is that the P5A-B motherboard supports the Baby AT form factor.
  
  
• Any CPU supported by the motherboard is acceptable. These include the AMD K5, K6-2, and Pentium P5.
  
  
• Any type of system memory supported by the motherboard is acceptable.
  
  
• Any floppy disk controller is acceptable.
  
  
• Any S3 Virge chipset-based video card is acceptable. An example is the Genoa Phantom 3D Virge DX card.
  
  
• For the debug or product Ethernet network card, any PCI- or ISA-based NE2000 compatible network card is acceptable. An example of an ISA-based NE2000 card is LinkSys LNE2000 model, and an example of the PCI-based NE2000 card is the Kingston KNE30T model. The configuration that is recommended in the next section uses an ISA-based Ethernet card for the debug Ethernet card.

The following table lists optional hardware for the CEPC that can be used depending on the type of development and testing that is done.

The following list provides additional information about optional hardware for the CEPC:

• Two examples of PC card adapters are Simple Technology's Simple Station and the SCM Systems' SwapBox.
  
  
• For the USB controller, the OHCI controller is built into both the Asus P5A and P5A-B motherboards.
  
  
• Examples of the Fast IR controllers are the ActiSys FIR card, Model ACT-IR2000B, and the Temic Fast IR board, Model TFDU6100E or TFDS6500E.

The hardware just listed does not include an audio controller, because we have not yet tested the audio portion of this specification on the CEPC. Once the appropriate audio hardware has been tested and verified, the CEPC specification will be updated on the Windows CE Web site. The audio card that has been tested and verified on Windows CE operating system version 2.10 and later is the Sound Blaster AWE64 Plug and Play card.

Assembling the CEPC

This section provides detailed step-by-step instructions on how to assemble and/or set up the CEPC.

Motherboard and card configuration

Please consult the motherboard documentation for information on installing the motherboard, the jumper settings for the CPU, system memory, and other system configurations. The following table lists the recommended motherboard and peripheral card configuration for the CEPC.

BIOS settings

This section provides the exact BIOS settings that need to be set on the CEPC for the motherboard and card configuration listed in the preceding table.

For the Standard CMOS Setup choose the default CMOS settings in the BIOS. The following table lists the recommended settings for the Features Setup in the BIOS.

The following table lists the recommended settings for the Chipset Features Setup in the BIOS.

For the Power Management Setup choose the default Power Management settings in the BIOS. The following table lists the recommended settings for the PNP and PCI Setup in the BIOS.

Building and Running an OS Image

The following illustration shows the process of building a custom Windows CE OS for a hardware development platform.

This section provides a tutorial that demonstrates how to use Platform Builder to build a custom Windows CE OS for a CEPC. In this tutorial, the Windows CE OS image is built using the Maxall configuration. Maxall builds a fully configured version of Windows CE. Once the Windows CE OS image is built, this tutorial also demonstrates how to boot the CEPC (assembled in the previous section) using this Maxall image.

In this tutorial, you complete the following tasks:

• Create a new platform and build the Windows CE OS image.
  
  
• Create a boot disk for the CEPC.
  
  
• Create a Command Prompt Build window on the development workstation.
  
  
• Transfer the Windows CE OS image to the CEPC using an Ethernet connection.
  
  
• Build a sample application.
  
  
• Start the kernel debugger function.

Note   This tutorial assumes you selected the x86 CPU during the installation of Platform Builder and installed Platform Builder in the default directory provided by Setup.exe.

To create a new platform and build the Windows CE OS image

1. Choose the New command from the File menu.
   
   
2. Type a name in the Platform name box. For this example, type MyProj.
   
   
3. Choose OK. The WCE Platform—Step 1 of 3 dialog box is displayed.
   
   
4. Select CEPC from the list and choose Next. The WCE Platform—Step 2 of 2 dialog box is displayed.
   
   
5. Select Maximum OS (Maxall) for the Maxall configuration.
   
   
6. Choose Finish. The New Project Information dialog box is displayed. The location of the platform is listed at the bottom of the dialog box.
   
   
7. Choose OK to close the New Project Information dialog box. The platform components, including the Maxall configuration components, are now displayed in the Component View window.
   
   
8. On the Platform Builder View menu, select Catalog. The Catalog Browser will open.
   
   
9. Add the ddi_vga8 display component to the platform by selecting the ddi_vga8 implementation in the Catalog Browser and holding the left mouse button down while dragging the implementation into the Component View window. When an implementation is added to a platform, the implementation automatically changes to a component.
   
   
10. Select Build Platform from the Build menu to build the Windows CE OS image.

Once a valid Windows CE OS image is built, an Ethernet connection and the appropriate Ethernet tools are used to transfer the OS image from the development workstation to the CEPC platform. The Ethernet connection method requires that the following files on the development workstation are run in a Command Prompt Build window for the OS configuration.

• Eshell.exe
  
  
• Edbg.dll
  
  
• Ceterm.exe
  
  
• Cesh.exe

The recommended hardware configuration for the CEPC does not include a hard drive. Instead, the specification assumes that the CEPC is booted using a boot floppy program. Typically, the CEPC is connected to the development workstation via an Ethernet connection and the Windows CE OS image is downloaded from the development workstation to the CEPC using the Ethernet connection. After the image is transferred into CEPC's system memory, a bootloader program on the boot floppy disk boots the Windows CE OS image.

For more information about the CEPC hardware configuration, see the section "Building a CEPC" earlier in this article.

To create a boot disk for the CEPC

1. Copy Websetup.exe and CepcBoot.144 from the Platform Builder CD number 1, located in CEPCBoot directory, to the development workstation.
   
   
2. Run Websetup.exe. This application installs Webimgnt.exe in the \Winnt directory, by default.
   
   
3. Run CepcBoot.144. The Web Image NT dialog box is displayed.
   
   
4. Select the floppy drive used to create the boot disk.

After you create the boot floppy disk, it should contain the following important files:

• Eboot.bin

  This file is an Ethernet bootloader component.

• Loadcepc.exe

  This file loads the bootloader image Eboot.bin.

• Autoexec.bat, Config.sys, Himem.sys, Command.com.

  These files are required MS-DOS files.

• Readme.txt

  This file contains instructions to boot the CEPC, which are also provided later in this article.

The Eboot.bin and Loadcepc.exe files are updated in this release of Windows CE version 2.12. The new Loadcepc.exe and Eboot.bin files provide the ability to use static IP addresses to boot the CEPC when a Dynamic Host Configuration Protocol (DHCP) server is not available to automatically serve up Internet Protocol (IP) addresses. In addition, these tools can also be used to download a Windows CE OS image from version 2.11 release.

Editing Autoexec.bat

Depending on which debug/download network card you are using, ISA or PCI, verify that Autoexec.bat on the boot disk is setup correctly for the network card.

The following examples are for an ISA-based Ethernet network card. If you are using the Linksys LNE2000 ISA card, verify that Autoexec.bat contains one of the following lines.

The file should contain the following line if you are using a DHCP Server:

loadcepc /b:38400 /v/e:1:340:5 eboot.bin

The file should contain the following line if you are using a static IP address:

loadcepc /b:38400 /v /e:1:340:5:<IP Address> eboot.bin

The first line is used when a DHCP server is available to serve up IP addresses automatically in the network environment. If you do not have a DHCP server, use the second line, which specifies a static IP address to the Loadcepc tool. In both examples the IRQ parameter is set to 5 and the I/O base address is set to 340, therefore you must manually set these parameters on the ISA network card by using the network utilities provided by the card manufacturer.

The following examples are for a PCI-based Ethernet network card. If you are using the Kingston KNE30T PCI card, verify that Autoexec.bat contains one of the following lines.

The file should contain the following line if you are using a DHCP server:

loadcepc /b:38400 /v/e:1: 0:9 eboot.bin

The file should contain the following line if you are using a static IP address:

loadcepc /b:38400 /v /e:1: 0:9:<IP Address> eboot.bin

The first line is used when a DHCP server is available to serve up IP addresses automatically in the network environment. If you do not have a DHCP server, use the second line that specifies a static IP address to the Loadcepc tool. In both examples, the IRQ parameter is set to 9 and the I/O base address is set to 0. The Eboot.bin image provided on the boot floppy will automatically ping the network card using IRQ:9, read the card's I/O base address, and then use the correct address for network operation. Therefore, it is not necessary to manually set the configuration parameters on the network card as in the case when an ISA-based Ethernet network card is used.

The parameter 1 in /e:1 in the previous command line signifies the type of network card used for the CEPC.  Because only the NE2000 compatible card is supported, this parameter must always be set to 1.

Note   When Autoexec.bat is created on the boot floppy disk, it is configured by default to be used with the Linksys ISA network card. This configuration assumes that a DHCP server is available.

To create a Command Prompt Build window on the development workstation

1. Right-click the Start button, and then select Windows NT Explorer to open Microsoft Windows Explorer.
   
   
2. Select the rootdirectory\Profiles\All Users\Start Menu\Programs\Microsoft Windows CE Platform Builder 2.12\x86 Tools directory where rootdirectory is the directory in which the Windows NT profiles are stored, for example C.
   
   
3. Select the x86 Minshell shortcut. Right-click, and then choose Copy to create a copy of the shortcut.
   
   
4. Right-click the x86 Tools directory, and then choose Paste to paste the copied shortcut in the current window.
   
   
5. Right-click the new shortcut, and then choose Rename. Type the name of the platform created in this tutorial, MyProj.

To Transfer the Windows CE OS image to the CEPC using an Ethernet connection

1. Open the MyProj Command Prompt Build window on the development workstation and change to the Release directory. Type Eshell.exe to run the Windows CE EShell application.
   
   
2. Select Manage Device List from the Tools menu in Windows CE Eshell.
   
   
3. Boot the hardware development platform using the boot disk. You should see your device name listed in the Non Controlled Devices dialog box. Record your device name. Please ignore any other device names that may already be listed.

   If you do not see your device name listed in the dialog box or if you are running into other problems, connect a null serial cable between the CEPC and the development workstation.  Then, run a terminal program on the development workstation (with the appropriate terminal settings) before booting the CEPC. When the CEPC boots, you will see debug serial output on the terminal window. The following is an example of the debug serial output that is displayed:

   >Microsoft Windows CE Ethernet Bootloader 2.2 for CE/PC… 
   > …
   >Using device name: CEPCLS54334
   

   Included in the debug serial output is the device name for the CEPC. In the preceding example the device name is CEPCLS54334. The device name includes the Ethernet address of the CEPC and a two-letter suffix indicating the type of Ethernet network card being used. In the example the suffix is LS, which refers to the ISA LinkSys card. The only other suffix that is currently supported for the Ethernet network card is KS, which refers to the PCI Kingston card. However, you can use an NE2000-compatible card from any manufacturer.

4. Double-click the device name that appears in the Non Controlled Devices dialog box in the Manage Windows CE Device List dialog box. The device name is now displayed in the Controlled Devices dialog box.

   Use this device name as arguments for Cesh.exe and Ceterm.exe in steps 9 and 10 of this procedure.

5. Choose the Done button.
   
   
6. Select Automatically Download Images from the Options menu.

   This must be selected because images are not persistent after the hardware development platform is rebooted.

7. From the File menu, choose Select Image File. Select the Windows CE binary image file, for example C:\Wince212\Release\RAM.bin.
   
   
8. Set up the registry entries before starting the Ethernet debug tools. Type the following in the Command Prompt Build window:

       cd \<%Wince_Root%>\public\common\oak\bin\i386
       regini ppsh.ini    
   

9. Type ceterm -e DeviceName in the Command Prompt Build window from the Release directory to run the Ceterm application and monitor Ethernet debug messages.
   
   
10. Type cesh -e DeviceName in the Command Prompt Build window from the Release directory to run the Cesh application.

    Note   If you do not run Cesh.exe and Ceterm.exe before beginning the image download, the image will not boot on the hardware development platform.

11. Reboot the CEPC platform.

    Allow all Ethernet applications to remain running on the development workstation. The CEPC platform will broadcast a BOOTME message to Eshell.exe, and the Eshell application will download the named image file and begin execution.

    When the download is complete, the prompt Windows CE> is displayed in the build window. The Windows CE OS image should have booted on the CEPC machine.

To build a sample application on the development workstation

1. Select the New command from the File menu.
   
   
2. In the New dialog box, choose the Projects tab.
   
   
3. In the Projects tab, select WCE Application and type Hello in the Project Name box.
   
   
4. Choose OK. The WCE Application—Step 1 of 1 dialog box is displayed.
   
   
5. Select A typical "Hello World!" application and then choose the Finish button.
   
   
6. The New Project Information dialog box is displayed. Choose OK to close the dialog box.
   
   
7. Select Build from the Build menu to build the sample application. The Hello.exe file is copied to the directory %_FLATRELEASEDIR_%.

To start kernel debugger

1. Choose the Debugger Remote Connection command from the Build menu. The Remote Connection dialog box is displayed.
   
   
2. If not already selected, select the processor for the active project from the Processor list. In this example the processor for the active project, Hello, is the Win32 (WCE x86).
   
   
3. Choose the Settings button. The Kernel Debugger Settings dialog box is displayed.
   
   
4. Select the Network UDP option. This is the protocol used with the Ethernet connection.
   
   
5. Type the device name in the Machine box.
   
   
6. Choose OK to close the Kernel Debugger Settings dialog box.
   
   
7. Choose OK again.
   
   
8. Choose the Go command from the Start Debug submenu of the Build menu.

   The Go command executes code from the current statement until a breakpoint or the end of the program is reached, or until the application pauses for user input.

For More Information

The online documentation and context-sensitive help included with Platform Builder provide comprehensive background information and instructions for using Platform Builder.

To access the online documentation for Platform Builder

1. Start Platform Builder.
   
   
2. Select the Contents option from the Help menu to view the documentation.

You can find updates to the documentation and technical information in the Readme file on one of the Platform Builder CDs.

In addition, Microsoft offers technical support and services ranging from self-help tools to direct assistance from a Microsoft technical engineer.

To view technical support in online Help

• Select Technical Support from the Platform Builder Help menu.

  A Help page titled "Getting Help from Microsoft Technical Support" is displayed. This page contains links to a variety of technical support topics.

To view technical support information on the Web

1. Navigate to the Microsoft Personal Support Center Web page http://support.microsoft.com/support/.
   
   
2. Select Phone Numbers.
   
   
3. Select Windows CE Platform Builder from the Select Your Product list.
   
   
4. Choose the Go button. The support page for the Platform Builder opens.

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication. This document is for informational purposes only.

This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS DOCUMENT.

© 1999 Microsoft Corporation. All rights reserved.

Microsoft, Win32, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Other product and company names mentioned herein may be the trademarks of their respective owners.