CE5.0 - Building a Device Driver from the Command

Building a Device Driver from the Command Line

From the Platform Builder command line, you can build a device driver as a part of the larger process of creating a driver for use with the Windows CE operating system (OS). For information about building a device driver in the integrated development environment (IDE), see Building a Device Driver in the IDE.

To build a device driver from the command line

1. From the Build OS menu in the IDE, choose Open Release Directory.
2. Navigate to the location of your device driver.
3. Type sysgen and press ENTER.

   Wait a few minutes for the Sysgen phase to finish. For more information, see Build Phases and Sysgen Tool.

4. Type build -c and press ENTER to build your driver.

   For more information about Build tool options, see Build Tool.

If your driver builds with zero errors, you have successfully built your device driver. If errors occur in the build process, you must debug the source code for your driver. For more information, see How to Debug a Device Driver.

Command-Line Tools

Platform Builder for Microsoft® Windows® CE includes a set of tools for doing the following:

• Defining a development environment
• Building source code
• Making a run-time image
• Transferring files to a target device

If you build a run-time image from the command prompt build window, you call many of these tools directly. If you build a run-time image from the Platform Builder integrated development environment (IDE), the IDE uses these tools to create, download, and debug your run-time image.

Note   The IDE and command-line environments are independent of each other. Environment variables that you set in one environment might have a different setting in the other environment. Do not combine IDE and command-line methods when you build a run-time image.

The following table shows the command-line tools and their functions.

Tool	Description
(Blddemo.bat)	Calls all tools necessary to create Microsoft Windows CE–based OS functionality, generate source code, copy files to a release directory, and make a run-time image.
(Buildrel.bat)	Copies all modules and files required to build the run-time image to a common release directory.
(Build.exe)	Creates executable files for the target device.
(Pbcec.exe)	Adds and removes Catalog item (.cec) files from the Catalog, and lists the Catalog contents.
(Cebackup.exe)	Creates backup copies of Windows CE–based libraries.
(Cesysgen.bat)	Specifies the Windows CE–based modules and functionality for the target device.
(Createmui.bat)	Creates resource files for the Multilingual User Interface.
(Cvrtbin.exe)	Converts read-only memory (ROM) files from binary (.bin) format to SRE or NBX (.nb0) format.
(fmerge.exe)	Combines all existing binary image builder (.bib) files into one .bib file, and all registry (.reg) files into one .ini file.
(Kbdgen.exe)	Produces Windows CE Input Language and Device Layout source files from a Windows XP keyboard layout dynamic-link library (.dll) file.
(Loadcepc.exe)	Loads a run-time image onto an x86-based target device, such as a Windows CE PC-based hardware platform (CEPC).
Make Binary Image tool (Makeimg.exe)	Creates a run-time image.
(Cebuild.bat)	Creates the Windows CE–based modules and functionality and builds source code for each project in an OS design.
(Memtool.exe)	Displays information on kernel memory usage.
(Readlog.exe)	Converts CELog (.clg) files into text (.txt) format.
(Setenv.bat)	Sets customized developer environment variables. Used by Wince.bat; do not call this tool directly.
(Sysgen.bat)	Creates the Windows CE–based modules selected in Cesysgen.bat by linking the functionality specified in Cesysgen.bat.
(Sysgenplatform.bat)	Links the files in your run-time image during the Sysgen phase of the build process.
(Viewbin.exe)	Displays information about the contents of a run-time image.
(Wince.bat)	Sets up the Windows CE build environment.
(Cesh.exe)	Downloads raw binary format (.rbf) files to a target device.
(Guidgen.exe)	Creates a globally unique identifier (GUID).

Windows CE Build Environment Tool

Wince.bat prepares the development workstation build environment by using three input parameters to determine the build environment, the location of the source files used during the build process, and the files created during the build process.

When Wince.bat is executed in the command prompt build window, it uses the following three input parameters to set the environment variables specific to the Windows CE project.

• %_TGTCPU%
• %_TGTPROJ%
• %_TGTPLAT%

These variables are used throughout the build process to build the appropriate targets.

Note   If Setdrive.exe or Setdrv.bat fails, Wince.bat fails.

If the following environment variables are not set before Wince.bat is run, Wince.bat sets them to their default values.

set _FLATRELEASEDIR=%_WINCEROOT%\release
set _PROJECTROOT=%_PUBLICROOT%\%_TGTPROJ%

%_WINCEROOT% must be set before running Wince.bat. Otherwise, Wince.bat reports an error and exits.

Wince.bat continues to set a series of environment variables. In addition, Wince.bat calls several batch files, which can also contain environment variables. The following table shows the batch files that Wince.bat calls.

Batch file	Description
Setenv.bat	Sets private environment variables for the build window. This must be in the %_WINCEROOT%\Developr\%USERNAME% directory.
%_TGTPLAT%.bat	Sets OS design-dependent environment variables related to the OS design. This must be in the %_WINCEROOT%\Platform\%_TGTPLAT% directory.
%_TGTPROJ%.bat	Sets project-dependent environment variables. Each configuration and demonstration project folder in the Public directory contains a batch file named after the corresponding project. This must be in the %_PROJECTROOT% directory.
%_WINCEROOT%\Setdrv.bat	Sets the development workstation drive for the Windows CE project.
%_WINCEROOT%\Public\Common\Oak\Misc\Etkenv.bat	Unconditionally sets IMGNODEBUGGER to 1.

These optional batch files allow further customization of the build process independent of the default settings in Wince.bat. Wince.bat validates individual environment variables, but does not ensure that the combination of parameters matches.

Before modifying Wince.bat or the local batch files that are used by Wince.bat, for more information, see Environment Variables.

After the environment variables are set, Wince.bat creates the %_FLATRELEASEDIR% directory. Wince.bat then checks for the presence of certain .bif files in the %_FLATRELEASEDIR% directory that contain the current parameters of your Windows CE project.

The following table shows the .bif files and their location.

Build information file	Location
%_TGTPROJ%.bif	%_FLATRELEASEDIR%
%_TGTPLAT%.bif	%_FLATRELEASEDIR%
%_TGTCPU%.bif	%_FLATRELEASEDIR%
%_TGTPROJ%.bif	Platform\%_TGTPLAT%

If these .bif files are not present, Wince.bat creates the .bif files in the %_FLATRELEASEDIR% directory and continues setting the build environment.

If these .bif files exist, Wince.bat uses their presence as a flag to indicate that a %_FLATRELEASEDIR% directory exists.

Wince.bat checks that the current build variables, %_TGTCPU%, %_TGTPROJ%, and %_TGTPLAT%, are compatible with the current build process. If they are not compatible, Wince.bat displays a warning message and does not automatically copy build results to the %_FLATRELEASEDIR% directory.

wince [] [] [] [] []

Note   The parameters for wince are case sensitive.

Parameters

-h

Displays a Help file for Wince.bat.

_TGTCPU

The specific CPU that the build targets. The following list contains the valid parameters:

• ARMV4I
• MIPS16
• MIPSII
• MIPSII_FP
• MIPSIV
• MIPSIV_FP
• SH4
• X86
• NT
• NTANSI

_TGTPROJ

The OS design directory name that the build uses.

_TGTPLAT

The board support package (BSP) that the OS design is based on and which the build process targets. Available BSPs on your development workstation are installed in the %_WINCEROOT%\Platform directory.

The following list contains the valid parameters:

• NOPLAT
• <BSP_Name>

If set, NOPLAT causes the OS tree to be built without building the run-time image. This enables you to optimize the development process when you work with multiple BSPs that use the same CPU.

You build source code in the OS tree once, and then build only BSP-specific code by changing the target directory to the BSP directory you want and running build commands from a command-line prompt.

PRIVATE_OPTIONS

Any additional parameters are passed without interpretation to Setenv.bat.

Error Messages

This build window is incompatible with your current release directory. The WINCEREL variable is being forced off to prevent releasing any binaries automatically. You must do a "buildrel" to reinitialize the release directory for the current configuration.

If one type of binary is copied into the release directory and Wince.bat is run with parameters that are not compatible with the existing binaries, Wince.bat issues this error message and terminates the build process.

To have multiple active release directories, either modify Setenv.bat to assign a different directory to the %_FLATRELEASEDIR% environment variable or delete the existing directory, %_WINCEROOT%\Release.

Example

The following code example shows how to use Wince.bat to set up a project environment for a member of the x86 CPU family. The project directory is Myproj and is targeted for the CEPC hardware platform.

wince x86 MYPROJ CEPC

Remarks

Wince.bat sets many environment variables for the Windows CE build environment.

Before running Wince.bat, verify that the three input parameters have valid names and are presented in their correct order. The input parameters are case sensitive.

Run the command prompt build windows to verify that the environment variables are valid. Be sure that _WINCEROOT is set.

Run Wince.bat from a command prompt window that executes from %_WINCEROOT%\Public\Common\Oak\Misc.