Importing Your Device Driver into Microsoft Windows CE Platform Builder 3.0

This article describes how to import your device driver into Microsoft Windows CE Platform Builder 3.0. It uses a Windows CE PC-based hardware development platform (CEPC) as an example and assumes that you have already written your device driver and copied the necessary files to the %_WINCEROOT%\Platform\MyBSP directory. The environment variable, %_WINCEROOT%, describes the root directory of the Windows CE operating system (OS) files, for example C:\WINCE300. MyBSP is the name of the board support package (BSP) for which you have written this driver. In this example, the BSP is the CEPC board support package and its related files.

Before importing your device driver into Platform Builder, you must first import a BSP. For more information about importing a BSP, see the Platform Builder documentation. The component file (.cec) file for your BSP should be located in the CEPBDir\CEPB\CEC directory. CEPBDir is the root directory of the Platform Builder installation, for example, C:\Program Files\Windows CE Platform Builder\3.00. Although it is not required that device drivers be added to the BSP .cec file, consider referencing the BSP and its drivers in one .cec file and placing each device driver in its own .cec file.

For this example, you will add the ddi_flat display drivers for the CEPC to the CEPC .cec file. Because Platform Builder considers a display driver to be a component, a component type block, ComponentType, must first be added to the .cec file. This block contains the following information: name, globally unique identifier (GUID), description, and group associated with components of this type.

Because you are adding a display driver, set the name of this component type to "display." To generate a GUID, use Guidgen.exe. Set the description parameter to whatever descriptive text you want. The group parameter determines where in the Catalog hierarchy Platform Builder will place the component. Because this display driver component should appear in the Drivers\CEPC folder in the Catalog, set the group parameter to \Drivers\CEPC. The following code example shows the resulting ComponentType block.

ComponentType( Name( display ) GUID(
{B3509B51-F1E4-11d2-85F6-004005365450} ) Description( "CEPC Video
Driver" ) Group( "\Drivers\CEPC" ) )

Next, describe the implementation of the component by adding the Implementations block to the ComponentType block. The Implementations block contains information about each specific implementation of the component type; multiple implementations may exist for each component type. Each Implementation section within the Implementations block requires a name, description, and a GUID. For this example, the display driver implementation is the ddi_flat display driver. The following code example shows the resulting Implementation block.

ComponentType( Name( display ) GUID(
{B3509B51-F1E4-11d2-85F6-004005365450} ) Description( "CEPC Video
Driver" ) Group( "\Drivers\CEPC" ) Implementations( Implementation(
Name( ddi_flat ) Description( "FLAT Driver" ) GUID(
{E2B049C8-F7DC-45d3-8204-0AA54FB4D4CC} ) ) ) )

The information above is sufficient to allow Platform Builder to display your new component in the Catalog and to allow you to select it and add it to your platform. However, because you have not yet instructed Platform Builder how to build this driver, it will not appear in your binary image. To do so, you must add one or more BuildMethod sections to a BuildMethods block. The following code example shows how to do this.

ComponentType( Name( display ) GUID(
{B3509B51-F1E4-11d2-85F6-004005365450} ) Description( "CEPC Video
Driver" ) Group( "\Drivers\CEPC" ) Implementations( Implementation(
Name( ddi_flat ) Description( "FLAT Driver" ) GUID(
{E2B049C8-F7DC-45d3-8204-0AA54FB4D4CC} ) BuildMethods( BuildMethod(
) BuildMethod( ) ) ) ) )

Each build method is associated with a particular build phase. The following table shows the custom build methods for each build phase that Platform Builder supports.

In this example, a build method is required for the Component Build and Make Image phases. Additional requirements are a GUID, the list of CPUs that this build method supports, any output files that may be generated by this build method, and a list of the build actions that Platform Builder will carry out.

If your component and build method are supported by all of the CPUs that are shipped with Platform Builder, the CPU parameter should be set to default. Otherwise, the CPU parameter must contain a list of CPUs, separated by spaces, that are supported. Because the CEPC display driver only supports the x86 CPU in this example, the CPU parameter is set to x86.

The OutputFiles build method parameter is optional. If the build method sets only an environment variable, no output file will be generated. However, if the build method instructs Platform Builder to build a dynamic-link library (DLL), you must provide the name and location of the DLL to be copied to the flat release directory and to be included in the OS image. If you omit this parameter, Platform Builder will build the DLL, but it will not be included in your final image.

In the Component Build phase of this example, you must set an environment variable and build the source files for the ddi_flat display driver. To set an environment variable, use the #ENV build action. To instruct Platform Builder how to build this driver, use the #BUILD build action.

The #ENV build action command takes two parameters: the variable to set and its value. In this example, the ODO_NODISPLAY variable is set to an empty value so that it will not be set during the Component Build phase.

The #BUILD build action takes two or more parameters, depending on the type of build selected. In this example, the DLL is built with a SOURCES file located in the CEPC\Drivers\Display\Flat directory. The following table shows the available build types and their parameters.

Putting all of the above information together, you can now create the first build method. This build method is for the Component Build, or BSP, step. It supports the x86 CPU, generates the ddi_flat.dll file, and contains two build actions. This build method is shown in the following code example.

BuildMethod( Step( BSP )
GUID({99570FD8-F205-4ca2-A8AE-84BC7F7DAA7D} ) CPU( "x86" )
OutputFiles( ddi_flat.dll ) Action( '#ENV( ODO_NODISPLAY, "" )' )
Action( '#BUILD( SOURCES,
"$(_WINCEROOT)\platform\CEPC\Drivers\DISPLAY\FLAT" )' ) )

In this case, a second build method is required for the Make Image build phase. This build method sets two environment variables; because there are no output files generated, the OuputFiles parameter is omitted. The following code example shows this build method.

BuildMethod( Step( makeimg )
GUID({F7E9BEC3-1644-11d4-99D1-00105AC7264F} ) CPU( "x86" ) Action(
'#ENV( ODO_NODISPLAY, "" )' ) Action( '#ENV( CEPC_DDI_FLAT, 1 )' )
)

The following code example shows the completed component block.

ComponentType( Name( display ) GUID(
{B3509B51-F1E4-11d2-85F6-004005365450} ) Description( "CEPC Video
Driver" ) Group( "\Drivers\CEPC" ) Implementations( Implementation(
Name( ddi_flat ) Description( "FLAT Driver" ) GUID(
{E2B049C8-F7DC-45d3-8204-0AA54FB4D4CC} ) BuildMethods( BuildMethod(
Step( BSP ) GUID({99570FD8-F205-4ca2-A8AE-84BC7F7DAA7D} ) CPU(
"x86" ) OutputFiles( ddi_flat.dll ) Action( '#ENV( ODO_NODISPLAY,
"" )' ) Action('#BUILD(SOURCES,
$(_WINCEROOT)\platform\CEPC\Drivers\DISPLAY\FLAT")') ) BuildMethod(
Step( makeimg ) GUID({F7E9BEC3-1644-11d4-99D1-00105AC7264F} ) CPU(
"x86" ) Action( '#ENV( ODO_NODISPLAY, "" )' ) Action( '#ENV(
CEPC_DDI_FLAT, 1 )' ) ) ) ) ) )

Once you have finished modifying the .cec file, you can import it into the Platform Builder Catalog by choosing Manage Platform Builder Componentsfrom the Filemenu. From the Manage Platform Builder Componentsdialog box, select Import New. Browse to the location of your new .cec file and select it. After you have imported the .cec file, you can drag the driver from the Catalog and insert it into your current platform.

Adding an Additional Device Driver to Platform Builder Using an Existing .cec File

This section describes how to import a second device driver implementation into Platform Builder by merging it into an existing .cec file. It uses a CEPC as an example and assumes that you have already written your device driver and copied the necessary files to the %_WINCEROOT%\Platform\MyBSP directory. The environment variable, %_WINCEROOT%, describes the root directory of the Windows CE OS files, for example, C:\WINCE300. MyBSP is the name of the BSP for which you have written this driver. In this example, the BSP is the CEPC board support package and its related files.

Before importing your second device driver into Platform Builder, you must first import a BSP and follow the earlier procedures for importing a device driver. For more information about importing a BSP, see the Platform Builder documentation. You can add this second device driver to an existing .cec file or you can create a new .cec file.

In this example, you will add the ddi_vga8 display driver to an existing .cec file. Because the necessary component type has already been created, you can insert your new display driver into the existing ComponentType block.

The following code example shows the display driver component for the CEPC that you created in the previous section.

ComponentType( Name( display ) GUID(
{B3509B51-F1E4-11d2-85F6-004005365450} ) Description( "CEPC Video
Driver" ) Group( "\Drivers\CEPC" ) Implementations( Implementation(
Name( ddi_flat ) Description( "FLAT Driver" ) GUID(
{E2B049C8-F7DC-45d3-8204-0AA54FB4D4CC} ) BuildMethods( BuildMethod(
Step( BSP ) GUID({99570FD8-F205-4ca2-A8AE-84BC7F7DAA7D} ) CPU(
"x86" ) OutputFiles( ddi_flat.dll ) Action( '#ENV( ODO_NODISPLAY,
"" )' ) Action('#BUILD(SOURCES,
$(_WINCEROOT)\platform\CEPC\Drivers\DISPLAY\FLAT")') ) BuildMethod(
Step( makeimg ) GUID({F7E9BEC3-1644-11d4-99D1-00105AC7264F} ) CPU(
"x86" ) Action( '#ENV( ODO_NODISPLAY, "" )' ) Action( '#ENV(
CEPC_DDI_FLAT, 1 )' ) ) ) ) ) )

As you import a second device driver implementation into Platform Builder, you will use the existing component type rather than creating a new one. Accordingly, you will leave the above information as is and will insert your new display driver into the existing ComponentType as an additional Implementation.

As in the case of the ddi_flat display driver, you need the name, description, GUID, and appropriate build methods for the new ddi_vga8 display driver.

The following code example shows the implementation for the ddi_vga8 driver.

Implementation( Name( ddi_vga8 ) Description(
"VGA 8BPP Driver" ) GUID( {B3509B59-F1E4-11d2-85F6-004005365450} )
BuildMethods( BuildMethod( ) BuildMethod( ) ) )

The build methods for this new display driver are identical to those of the display driver you previously added. The build method for the Component Build phase sets an environment variable and builds the display driver DLL. The build method for the Make Image phase sets two environment variables. The following code example shows the two build methods.

BuildMethod( Step( BSP ) GUID(
{B3509B5A-F1E4-11d2-85F6-004005365450} ) CPU( "x86" ) OutputFiles(
ddi_vga8.dll ) Action( '#ENV( ODO_NODISPLAY, "" )' ) Action(
'#BUILD( SOURCES,
"$(_WINCEROOT)\platform\CEPC\Drivers\DISPLAY\VGA8BPP" )' ) )
BuildMethod( Step( makeimg ) GUID(
{F7E9BEC5-1644-11d4-99D1-00105AC7264F} ) CPU( "x86" ) Action(
'#ENV( ODO_NODISPLAY, "" )' ) Action( '#ENV( CEPC_DDI_VGA8BPP, 1 )'
) )

Once the .cec file has been modified, you are ready to import it into the Platform Builder Catalog. After successfully importing the file, you can drag either of these CEPC display implementations from the Catalog and insert them into your current platform. The following code example shows the resulting display component block in the .cec file.

ComponentType( Name( display ) GUID(
{B3509B51-F1E4-11d2-85F6-004005365450} ) Description( "CEPC Video
Driver" ) Group( "\Drivers\CEPC" ) Implementations( Implementation(
Name( ddi_vga8 ) Description( "VGA 8BPP Driver" ) GUID(
{B3509B59-F1E4-11d2-85F6-004005365450} ) BuildMethods( BuildMethod(
Step( BSP ) GUID( {B3509B5A-F1E4-11d2-85F6-004005365450} ) CPU(
"x86" ) OutputFiles( ddi_vga8.dll ) Action( '#ENV( ODO_NODISPLAY,
"" )' ) Action( '#BUILD( SOURCES,
"$(_WINCEROOT)\platform\CEPC\Drivers\DISPLAY\VGA8BPP" )' ) )
BuildMethod( Step( makeimg ) GUID(
{F7E9BEC5-1644-11d4-99D1-00105AC7264F} ) CPU( "x86" ) Action(
'#ENV( ODO_NODISPLAY, "" )' ) Action( '#ENV( CEPC_DDI_VGA8BPP, 1 )'
) ) ) ) Implementation( Name( ddi_flat ) Description( "FLAT Driver"
) GUID( {E2B049C8-F7DC-45d3-8204-0AA54FB4D4CC} ) BuildMethods(
BuildMethod( Step( BSP )
GUID({99570FD8-F205-4ca2-A8AE-84BC7F7DAA7D} ) CPU( "x86" )
OutputFiles( ddi_flat.dll ) Action( '#ENV( ODO_NODISPLAY, "" )' )
Action('#BUILD(SOURCES,
$(_WINCEROOT)\platform\CEPC\Drivers\DISPLAY\FLAT")') ) BuildMethod(
Step( makeimg ) GUID({F7E9BEC3-1644-11d4-99D1-00105AC7264F} ) CPU(
"x86" ) Action( '#ENV( ODO_NODISPLAY, "" )' ) Action( '#ENV(
CEPC_DDI_FLAT, 1 )' ) ) ) ) ) )

Once you have finished modifying the .cec file, you can import it into the Platform Builder Catalog by choosing Manage Platform Builder Componentsfrom the Filemenu. From the Manage Platform Builder Componentsdialog box, select Import New. Browse to the location of your new .cec file and select it. After you have imported the .cec file, you can drag the driver from the Catalog and insert it into your current platform.

Adding an Additional Device Driver to Platform Builder Using a Separate .cec File

This section describes how to import a second device driver implementation into Platform Builder using a separate .cec file. It uses a CEPC as an example and assumes that you have already written your device driver and copied the necessary files to the %_WINCEROOT%\Platform\MyBSP directory. The environment variable, %_WINCEROOT%, describes the root directory of the Windows CE OS files, for example, C:\WINCE300. MyBSP is the name of the BSP for which you have written this driver. In this example, the BSP is the CEPC board support package and its related files.

Before importing your second device driver into Platform Builder, you must first import a BSP and follow the earlier procedures for importing a device driver. For more information about importing a BSP, see the Platform Builder documentation. You can add this second device driver to an existing .cec file or you can create a new .cec file.

In this example, you will add the ddi_ati display driver to a separate .cec file. Because you are creating a new .cec file, a CECInfo block must be created. The CECInfo block requires the following parameters: name, GUID, CECVersion, vendor, and description. The name parameter should be set to the name of the file, minus the file extension, which is Mycec.cec, for this example. Guidgen.exe is used to generate a new GUID. The CECVersion parameter is set to the current Platform Builder version, which is 3.0, the vendor parameter is set to your company name, and the description parameter is set to an appropriate description for the .cec file contents.

The following code example shows the new CECInfo block.

CECInfo ( Name( mycec ) GUID(
{C948CDAC-45BE-43fb-B7A2-6A8B300AF906} ) CECVersion( 3.00 ) Vendor(
"MyCompany" ) Description( "CEPC ATI Display Driver" ) )

Because you are adding this driver to an existing component type rather than creating a new one, you must copy the information from the ComponentType block of the existing CEPC .cec file. The only required parameters are name and GUID. However, Microsoft recommends that you also include the description and group parameters to allow the .cec files to be imported in any order. Otherwise, you will have to import the original .cec file first, followed by the new .cec file. Once you have copied the ComponentType block from the existing .cec file, you can then add the new display driver Implementation block. The following code example shows the ComponentType block for the display driver, copied from the existing .cec file to the new .cec file.

ComponentType( Name( display ) GUID(
{B3509B51-F1E4-11d2-85F6-004005365450} ) Description( "CEPC Video
Driver" ) Group( "\Drivers\CEPC" ) Implementations( Implementation(
) ) )

As in the case of the ddi_flat display driver, you must supply the name, description, GUID, and appropriate build methods for the new ddi_ati display driver.

The following code example shows the implementation for the ddi_ati driver.

Implementation( Name( ddi_ati ) Description( "ATI
Driver" ) GUID( {5F64D01D-F72A-43fd-AB89-D7C4B9BE1BD7} )
BuildMethods( BuildMethod( ) BuildMethod( ) ) )

The build methods for this new display driver are identical to those of the display driver you previously added. The build method for the Component Build phase sets an environment variable and builds the display driver DLL. The build method for the Make Image phase sets two environment variables. The following code example shows the two build methods.

BuildMethod( Step( BSP )
GUID({B463BCE8-AB3E-459e-AD4B-542498F835CB} ) CPU( "x86" )
OutputFiles( ddi_ati.dll ) Action( '#ENV( ODO_NODISPLAY, "" )' )
Action( '#BUILD( SOURCES,
"$(_WINCEROOT)\platform\CEPC\Drivers\DISPLAY\ATI" )' ) )
BuildMethod( Step( makeimg ) GUID( {
F7E9BEC2-1644-11d4-99D1-00105AC7264F } ) CPU( "x86" ) Action(
'#ENV( ODO_NODISPLAY, "" )' ) Action( '#ENV( CEPC_DDI_ATI, 1 )' )
)

The following code example shows the resulting display component block in the .cec file. When Platform Builder imports this .cec file, it matches the ComponentType GUID with the matching GUID for the other display driver or drivers and adds this implementation to that list. In the Catalog, you will then have access to the ATI display driver in addition to any display drivers previously added.

ComponentType( Name( display ) GUID(
{B3509B51-F1E4-11d2-85F6-004005365450} ) Description( "CEPC Video
Driver" ) Group( "\Drivers\CEPC" ) Implementations( Implementation(
Name( ddi_ati ) Description( "ATI Driver" ) GUID(
{5F64d01D-F72a-43fd-AB89-D7C4B9BE1BD7} ) BuildMethods( BuildMethod(
Step( BSP ) GUID( {B463BCE8-AB3E-459e-AD4B-542498F835CB} ) CPU(
"x86" ) OutputFiles( ddi_ati.dll ) Action( '#ENV( ODO_NODISPLAY,
"")' ) Action( '#BUILD(SOURCES,
"$(_WINCEROOT)\platform\CEPC\Drivers\DISPLAY\ATI")' ) )
BuildMethod( Step( makeimg ) GUID(
{F7E9BEC2-1644-11d$-99D1-00105AC7264F} ) CPU( "x86" ) Action(
'#ENV( ODO_NODISPLAY, "")' ) Action( '#ENV( CEPC_DDI_ATI, 1 )' ) )
) ) ) )

Once you have finished modifying the .cec file, you can import it into the Platform Builder Catalog by choosing Manage Platform Builder Componentsfrom the Filemenu. From the Manage Platform Builder Componentsdialog box, select Import New. Browse to the location of your new .cec file and select it. After you have imported the .cec file, you can drag the driver from the Catalog and insert it into your current platform.