- Platform Builder Basics
- Creating a New Platform with the Platform Wizard
- Building and Executing the Platform
- Creating Applications for Your Platform
- Running Windows CE on a CEPC
- Integrating New Components into the Image
- Customizing the Build Using Environment Variables
- Extending the Platform Builder Catalog
- Creating a New Board Support Package
- Summary
Integrating New Components into the Image
We can use the rapid development scenario described in earlier sections until we finish all basic development of welcome.exe. We made changes to the Welcome application so that it displays a message greeting on startup. We also added a caption and a system menu so that the window can be conveniently closed. The text now appropriately welcomes users to the first Windows CE platform in this book. Welcome will be started every time Adam boots so that the welcome message is the first message users see. Let's see how to add this somewhat concocted example to the image and automatically start Welcome on startup.
To add welcome.exe to the operating system image, we will need to modify a file in the parameter view of the platform workspace. Figure 3.14 shows the parameters view window for Adam. The files displayed in this window are used to specify how the operating system image will be built.
){kind=link}
Figure 3.14 Parameter view
We'll delve into the specifics of each file elsewhere throughout the book, so a brief overview will suffice for now. The parameter view is organized into a set of files in three different categories. The option Common Files refers to files that are provided by Microsoft to specify how the operating system must be built with Microsoft-supplied components. You should not modify these files. Any modifications you make will affect all platforms and projects you create.
Note - To make sure that the compiler can find the file windev.h, you must add the include path in the CESYSGEN directory of Adam to the list of additional include directories in which the compiler may find included header files. CESYSGEN is the directory in which header files generated for the specific platform are placed. To add this directory to the include path for the compiler, you must click on the Project | Settings... menu item and then click on the C/C++ tab. Next, select Preprocessor in the Category: combobox. In the Additional include directories: edit box, type in "$(_WINCEROOT)\PUBLIC\ADAM\CESYSGEN\OAK\INC". This directory path will be passed to the compiler with the /I flag, which instructs the compiler to search the specified directory for the include path after looking in the standard include paths.
Different types of files contain different types of information:
-
BIB files contain information about which files, executables, and libraries should be included in the operating system image.
-
DAT files contain a directory map for the file system on Windows CE.
-
DB files contain information on how the Windows CE database should be initialized.
-
REG files contain a map of the system registry on startup.
The option Hardware Specific Files refers to files that specify configuration and initialization when you're building the platform.
Files specified by the option Project Specific Files contain additional information in each of these categories that is specific to the project being created. The word project in this case does not refer to Welcome, although that's what we've been telling you all along. Here the term project is a confusing throwback to the old days of the EDK. Under the terminology used then (and still reflected in the Platform Builder directory and file structure), CEPC is our platform and Adam is our project. This clarifies the role of these categories. Platform-specific files typically contain information regarding platform-specific drivers and modules. Project-specific files contain information about platform-independent modules. All the files are used by the set of Windows CE build tools when the image is being created.
If you have been following along closely, you might have already identified the BIB file as the one we must modify to integrate welcome.exe in the final operating system image. The first question, of course, is, To which BIB file should we add welcome.exe? The answer is simple enough: Since welcome.exe is platform-independent, it should be added to the BIB file project.bib in the Project Specific Files category.
Listing 3.3 shows the line that needs to be added to the BIB file to integrate the executable in the image. This line instructs the appropriate build tool to add the file $(_FLATRELEASEDIR)\welcome.exe to the image, where it will be called welcome.exe. The file must be loaded into the NK section of memory in ROM and must be uncompressed (type U). Sections of memory are set up in the file config.bib. We'll say more about this later in the book. Leaving the executable uncompressed gives the operating system the option of running the program in place in ROM. This avoids the work that the loader would normally do of uncompressing a file from ROM into RAM before executing it. In addition to the time gained because the file does not need to be uncompressed, precious RAM is made available for other programs.
Listing 3.3 Adding welcome.exe to project.bib
MODULES ; Name Path Memory Type ; -------------- --------------------------------------------- ----------- welcome.exe $(_FLATRELEASEDIR)\Welcome.exe NK U
Now that Welcome is part of the operating system image, it will be transferred to the target platform by CESH. PPFS will no longer be required to load it on demand because the loader will find the file in the local file system on the target platform.
We still need to make Welcome execute automatically on startup. The kernel looks for a special registry entry after starting the file system to look for modules to load during startup. Since the REG file allows us to specify the contents of the system registry when the target platform is initialized, we can zero in on the platform-independent registry file project.reg. To automatically execute Welcome on startup, we must add the following lines to the registry initialization file project.reg:
[HKEY_LOCAL_MACHINE]\Init "Launch80"="Welcome.exe" "Depends80"=hex:1E,00
The Launch80 registry entry tells the kernel to launch the program welcome.exe. The function performed by the Depends80 line is not immediately obvious. This registry entry lists a hex number (001E) as its value. To discover the significance of this number, we must take a peek at the common registry file, common.reg. This file has its own init section that is used to specify programs to launch on startup. An excerpt of this file is shown in Listing 3.4.
Listing 3.4 The init registry key in common.reg
[HKEY_LOCAL_MACHINE\init] ; @CESYSGEN IF CE_MODULES_SHELL "Launch10"="shell.exe" ; @CESYSGEN ENDIF ; @CESYSGEN IF CE_MODULES_DEVICE 'Launch20"="device.exe" ; @CESYSGEN ENDIF ; @CESYSGEN IF CE_MODULES_GWES IF NOGUI ! "Launch30"="gwes.exe" "Depend30"=hex:14,00 ENDIF ; @CESYSGEN ENDIF
The hex number 001E corresponds to 30. The Launch30 registry item in the listing is the module gwes.exe. The entries related to gwes.exe instruct the kernel to launch gwes.exe on startup. The Depends80 line simply tells the kernel to wait until gwes.exe has been launched before launching welcome.exe, because welcome.exe uses the windows and message support made available by gwes.exe. Finally, the number 80 was chosen at random from among numbers higher than 30. This number indicates the sequence in which the registry entries must be processed. We need a number higher than that corresponding to the last entry in the common.reg file.
However, this dependency only synchronizes the launch sequence of different modules. It does not guarantee that gwes.exe will have fully initialized its services before welcome.exe is executed. To make sure that the window manager is available, Welcome must call IsAPIReady with its lone argument set to the constant SH_WMGR.
...
#include "windev.h"
...
While (!IsAPIReady (SH_WMGR))
Sleep (1000);
The IsAPIReady call will return a value of TRUE if the API specified by the constant is available. If a value of FALSE is returned, the API is not yet ready for use and Welcome must wait in a loop for the API to initialize before it executes the remainder of its code.
Note the inclusion of the header file windev.h. This file contains the function prototype for IsAPIReady. Welcome loops and checks the value returned by this call to see if the window manager API is available. If the API is not available, Welcome sleeps for one second before checking again.
Now that we are ready with all the changes, we can test out the build by selecting the Platform | Build | Build Platform menu item after switching to the platform view. To confirm that welcome.exe has been included in the image, sift through the final output of the build process that lists all the files included in the image. The entry for welcome.exe, if included in the image, should look like Listing 3.5.
Listing 3.5 Output from the build process
MODULES Section Module Section Start Length psize vsize Filler ------------ -------- --------- ------- ------- ------- ------ ... welcome.exe .text 80a6f000h 8192 5632 5508 o32_rva=1000h welcome.exe .rdata 80a71000h 4096 512 289 o32_rva=3000h welcome.exe .idata 80a72000h 4096 1024 565 o32_rva=5000h welcome.exe .rsrc 80a73000h 4096 2560 2254 o32_rva=6000h ... welcome.exe .data 8024ffdbh 0 0 2584 FILLER ... welcome.exe E32 8052b55ch 100 FILLER welcome.exe O32 8052b5c0h 120 FILLER
The next time you download the new image and boot the CEPC, Welcome should pop up as it did before on startup, welcoming the user to our new platform, Adam.