Adding Board Support Packages to Microsoft Windows CE Platform Builder 3.0

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
Microsoft Corporation
June 2000
Summary:This document describes how to create a platform using your own board support package with Microsoft Windows CE Platform Builder 3.0. (9 printed pages)
Introduction IDE Procedures
`Introduction`


A 
board support packagecontains an OEM adaptation layer (OAL),
device drivers, and a default component list for your custom
hardware. Platform Builder includes board support packages for the
Windows CE PC–based hardware development platform (CEPC) and the
Hitachi D9000 hardware development platform (ODO).
To create a platform using your own board support package, you
must first create and import a component file (.cec) and create a
board support package file (.bsp). Platform Builder uses these
files to recognize your board support package.
The .bsp file indicates which drivers or components are needed
for your board support package for each predefined configuration of
the Windows CE OS. For example, for a CEPC board support package,
the MINKERN OS configuration includes only the OAL and the Eboot
components while the MAXALL OS configuration includes additional
components, such as a display driver, a keyboard driver, and a
PCMCIA driver.
The .cec file contains a description of new components for your
board support package, including the OAL. This component
description includes the name of the component, instructions on how
to build it, and what files to copy to the %_FLATRELEASEDIR%
directory. For a component to be accessible in the Platform Builder
IDE, it must first be imported into the Platform Builder
catalog.

Note   When the data for a field
in a .cec file contains a space, the data must be enclosed by
quotes. If the data is not enclosed by quotes, Platform Builder
will only read the first word. Note tokens are separated by space,
and lines are ignored. If you enter a comment line, you need to
include a space after // in order to avoid a syntax
error.
In this tutorial you will create and import a Mycepc.cec and
create a Mycepc.bsp file. As a result, you add the MyCEPC board
support package to Platform Builder. This board support package is
based on the CEPC board support package. The tutorial assumes that
you have already created your own OAL and supporting device
drivers.

IDE Procedures

To create and import a .cec file for your board support
package

Create a directory in %_WINCEROOT%\Platform for the board
support package. For this tutorial the directory is called Mycepc,
which is the name of your board support package. Mycepc contains
all of the kernel and driver files for the board support package,
as well as component build instructions 
%_WINCEROOT% refers to the root directory of the OS files, such
as C:\Wince300. 
Copy the OAL and driver files for the board support package to
the board support package directory. For this tutorial, copy all of
the files from %_WINCEROOT%\Platform\Cepc to
%_WINCEROOT%\Platform\Mycepc. 
For this tutorial, rename the Cepc.bat file located in the
MYCEPC directory to Mycepc.bat. 
Create a new text file called 
Mybsp.cec, in %CEPBDir%\Cepb\Cec. %CEPBDir% refers to the
root directory of Platform Builder, such as C:\Program
files\Windows CE Platform Builder\3.00. For this tutorial, create a
file called Mycepc.cec. For example: 
%CEPBDir%\Cepb\Cec\Mycepc.CEC
Open the new .cec file in a text editor, and create the CECInfo
block in the Mycepc.cec file. For example: 
CECInfo ( Name (MyCepc) GUID
({C0803B90-2205-11D4-8453-00500498479D}) CECVersion (3.00) Vendor
("My Company name") Description ("MyCepc OAL and Drivers") )
The following code example shows a general CECInfo block. 
CECInfo ( Name (<.cec file name>) GUID
(<GUID value>) CECVersion (3.00) Vendor (<company
name>) Description (<.cec file description>) )
This block uniquely identifies the .cec file when it is imported
into the Platform Builder catalog. The Name field must be name of
the .cec file without the .cec extension, for example MyCEPC. You
can use Guidgen.exe to create a new globally unique identifier
(GUID). 
Create the ComponentType, Implementation, and BuildMethod block
for the OAL component in the Mycepc.cec file. For example: 
// MyCEPC OAL component ComponentType ( Name
(OAL) GUID ({B3509B99-F1E4-11d2-85F6-004005365450}) Description
("OEM Adaptation Layer") Implementations ( Implementation ( Name
(MyCEPC) GUID ({C0803B91-2205-11D4-8453-00500498479D}) Description
("MyCEPC OAL") BuildMethods ( BuildMethod ( Step (BSP) GUID
({C0803B92-2205-11D4-8453-00500498479D}) CPU ("x86") Action
('#BUILD(DIRS, "$(_WINCEROOT)\platform\MYCEPC\kernel")') Action
('#BUILD(DIRS, "$(_WINCEROOT)\platform\MYCEPC\gwe")') ) ) ) )
)
The following code example shows general ComponentType,
Implementation, and BuildMethod blocks for an OAL component. 
// MyCEPC OAL component ComponentType ( Name
(OAL) // Component type GUID (<GUID value>) Description
(<component description>) Implementations ( Implementation (
Name (<specific implementation>) GUID (<GUID value>)
Description (<description of component implementation>)
BuildMethods ( BuildMethod ( Step (<build step>) GUID
(<GUID value>) CPU (<supported microprocessors>) Action
(<actions performed during platform build>) ) ) ) ) )
Use Guidgen.exe to create GUIDs for the Implementation and
BuildMethod blocks. You must reference the same OAL GUID as defined
in the Extras.cec file: {B3509B99-F1E4-11d2-85F6-004005365450}.
Extras.cec is in the same directory as Mycepc.cec,
%CEPBDir%\Cepb\Cec. Platform Builder uses this GUID to identify the
component as an OAL component. 
For your board support package to appear in the Platform Wizard,
the value for the CPU field in the BuildMethod block must be either
"default" or the microprocessors that you will select in the
Platform Wizard. If the value is "default", your board support
package will appear as an option in the wizard whenever any of the
microprocessors that are included with Platform Builder are
selected. The following microprocessors are supported by
default:SH3, SH4, SA1100, ARM720, ARM720T, R3912, R4102, R4111.16,
R4111.32, R4300, PPC403, PPC821, and x86. If the value is a list of
microprocessors, the board support package will only appear in the
wizard if one of these microprocessors is selected in the wizard. 
For this tutorial, your board support package, MyCEPC, only
supports the x86 microprocessor. Therefore, the value for the CPU
field is "x86". If MyCEPC supported more microprocessors, such as
the x86 and SH3 microprocessors, the value for the CPU field would
be both microprocessors separated by a space. For example: 
CPU ("x86 SH3")
Create the ComponentType, Implementation, and Method blocks in
the Mycepc.cec file for each of the other components supported by
your board support package, if desired, such as display, keyboard,
mouse, and universal serial bus (USB) drivers. Use Guidgen.exe to
create new GUIDs. 
For this tutorial, change Drivers\Cepc to Drivers\Mycepc for the
Group field value. You do not need to redefine the CEPC driver
components in the Mycepc.cec file because they are already defined
in the Cepc.cec file. When you create a .bsp file you will
reference these components in that file. 
The following code example defines Eboot2.bin as a new component
in the Mycepc.cec file in order to illustrate how to add a new
component. For example: 
// EBOOT2 component ComponentType ( Name (EBOOT2)
GUID ({17E1AF73-2212-11D4-8456-00500498479D}) Description ("MyCEPC
Eboot2.bin") Group("\Drivers\MyCEPC") Implementations (
Implementation ( Name (Eboot2) GUID
({17E1AF74-2212-11D4-8456-00500498479D}) Description ("MyCEPC
Eboot2.bin") BuildMethods ( BuildMethod ( Step (BSP) GUID
({17E1AF75-2212-11D4-8456-00500498479D}) CPU ("x86") Action
('#BUILD(DIRS, "$(_WINCEROOT)\platform\MYCEPC\EBOOT")') ) ) ) )
)
Once you have defined all of the components for your board
support package in the .cec file, you are ready to import the .cec
file into the Platform Builder catalog. 
Open the Platform Builder application, and then select 
Manage Platform Builder Componentsfrom the 
Filemenu.
Select 
Import New. The 
Import Platform Builder Componentdialog box is displayed.
Select the .cec file for your board support package, and then
choose 
Open. For this tutorial, select the Mycepc.cec file located
in %CEPBDir%\Cepb\Cec. 
If there is a syntax error in the .cec file, you will not be
able to import it. An error message is displayed that briefly
describes the syntax error. 
Select the 
Refreshbutton to update the catalog, and ensure that the OAL
and other components in your .cec file will be displayed in the
catalog.
If the catalog is not open, choose 
Catalogfrom the 
Viewmenu to display the catalog. 

orClick the 
Catalogbutton on the 
Standardtoolbar to display the catalog. 
Click to expand the entries in the 
Catalogwindow that correspond to the values you specified in
the 
Groupfields in your .cec file.
The components for your board support package should appear
under the corresponding entries. In this tutorial, for example,
Eboot2.bin should appear under the 
Driversentry in the 
MyCEPCfolder, and Mycepc should appear under the 
OALfolder. 

To create a .bsp file

When you create a new platform, the Platform Wizard uses the
.bsp file to determine which components to insert by default into a
new platform, depending on the OS configuration you select in the
wizard. 

Create a new file called Mybsp.bsp in %CEPBDir%\Cepb\Bin\Ide.
%CEPBDir% refers to the root directory of Platform Builder, such as
C:\Program Files\Windows CE platform builder\3.00. Platform Wizard
searches for .bsp files in this directory. 
For this tutorial, create Mycepc.bsp in %CEPBDir%\Cepb\Bin\Ide. 
Open the .bsp file in a text editor, and list any components
that should be part of the default board support package for all OS
configurations. List the components by GUID, using the
#ADD_COMPONENT_BY_GUID_TO_ROOT directive. 
The OAL component for your board support package will always be
included in this section, in addition to any other components that
are always required to be part of the board support package. Each
of the components must already have been defined in a .cec file and
must have been imported into the catalog. The GUIDs listed in the
.bsp file must match the GUIDs listed in the .cec file(s). 
For this tutorial list the OAL and Eboot2 components in the
Mycepc.bsp file, which you defined in the Mycepc.cec file. For
example: 
// MyCEPC.BSP // *** Global components (for all
configs) *** // MyCEPC uses the MyCEPC OAL implementation GUID
#ADD_COMPONENT_BY_GUID_TO_ROOT
("{C0803B91-2205-11D4-8453-00500498479D}") // Eboot2 uses the
Eboot2 implementation GUID #ADD_COMPONENT_BY_GUID_TO_ROOT
("{17E1AF74-2212-11D4-8456-00500498479D}")
In the .bsp file for each of the eight OS configurations, list
the implementation GUID for each component that is required for a
configuration, using the #ADD_COMPONENT_BY_GUID_TO_ROOT directive.
Components can be listed for more than one OS configuration. For
this tutorial, copy the eight #IF blocks from Cepc.bsp, located in
%CEPBDIR%\Cepb\Bin\Ide, to Mycepc.bsp. 
As described in step 2, each of the components must already have
been defined in a .cec file and must have been imported into the
catalog. The GUIDs listed in the .bsp file must match the
implementation GUIDs listed in the .cec file or files. 
The following code example shows the default components for the
Minkern and IEsample OS configurations. 
// *** CoreOS specific components *** // ***
MINKERN *** #IF ("COREOS", "MINKERN") // ceddk
#ADD_COMPONENT_BY_GUID_TO_ROOT
("{B3509B75-F1E4-11D2-85F6-004005365450}") #ENDIF // *** IESAMPLE
*** #IF ("COREOS", "IESAMPLE") // ceddk
#ADD_COMPONENT_BY_GUID_TO_ROOT
("{B3509B75-F1E4-11D2-85F6-004005365450}") // ddi_flat
#ADD_COMPONENT_BY_GUID_TO_ROOT
("{E2B049C8-F7DC-45d3-8204-0AA54FB4D4CC}") // serial
#ADD_COMPONENT_BY_GUID_TO_ROOT
("{35E70441-EEA9-11D2-A092-0060085C1833}") // pcmcia
#ADD_COMPONENT_BY_GUID_TO_ROOT
("{35E70445-EEA9-11D2-A092-0060085C1833}") // Keyboard driver:
depends on language setting #IF ("COUNTRY, "JAPAN") // kbdmsjpn2
(Japanese) #ADD_COMPONENT_BY_GUID_TO_ROOT
("{B3509B6C-F1E4-11D2-85F6-004005365450}") #ELSE // kbdmsengus1
(English – USA) #ADD_COMPONENT_BY_GUID_TO_ROOT
("{B3509B65-F1E4-11D2-85F6-004005365450}") #ENDIF

Note   You can use the COUNTRY
environment variable setting to determine which components to
include. In this example, we use the COUNTRY setting to determine
which keyboard driver to include in the IEsample OS configuration.
By default, the Platform Wizard uses the language setting
established for the development workstation.

To use a .bsp file

Open the Platform Builder application, and then choose 
Newfrom the 
Filemenu.
Type a name for your platform in the 
Platform namebox. For this tutorial, type 
MyTestPlat.
You can type a new path for the platform in the 
Locationbox, or use the browse button to select a platform
directory. The path cannot be longer than 32 characters.
Select one or more microprocessors that your platform will
support in the 
Processorsbox, and then choose 
OK. The 
Processorsbox lists only the microprocessors you installed. 
For this tutorial, you need to select 
Win32 (WCE x86)in order for MyCEPC to appear as an option in
step 5 below. The MyCEPC board support package only supports the
x86 microprocessor, as indicated by the value listed for the 
CPUfield in the Mycepc.cec file. 
Select your board support package, and then choose 
Next. 
If MyCEPC does not appear in the list of board support packages,
verify that the Mycepc.bsp file is in %CEPBDir%\Cepb\Bin\Ide and
that Mycepc.cec has been imported into the catalog. 
Select an OS configuration. For this tutorial select 
Maximum OS (Maxall)for the Maxall OS configuration.
Choose 
Finish
A dialog box containing information about your configuration
appears. This information includes the language setting for the
platform. By default, the Platform Wizard uses the language setting
established for the development workstation. 
Choose 
OK, and then verify that the global components and core OS
component defined in the Mycepc.bsp file appears in the 
ComponentViewwindow. For this tutorial, verify that the OAL
and Eboot2 components appear in this window. 
Choose 
Build Platformfrom the 
Buildmenu to build an OS image based on the platform. It may
take five to ten minutes to complete the build, depending on which
OS configuration you select. Build messages appear in the 
Buildwindow. 
Verify that no build errors occurred. Error messages are
displayed in the 
Buildwindow. If you receive an error message similar to the
following message, verify that the Mycepc directory is located in
the %_WINCEROOT%\Platform directory: 
Error spawning
#(e:\WINCE300\platform\MyCEPC\kernel)build.exe.








© 2004 Microsoft Corporation. All
rights reserved.
Adding Board Support Packages to Microsoft Windows CE Platform Builder 3.0

Contents

Introduction

IDE Procedures

`Introduction`
