摘抄------Creating a Board Support Package Using the Windows CE .NET CEC Editor

Creating a Board Support Package Using the Windows CE .NET CEC Editor

Bruce Eitman
Windows Embedded MVP
Accelent Systems Inc.

January 2003

Applies to:
    Microsoft® Windows® CE .NET with Microsoft Platform Builder 4.0
    CEC Editor

Summary: This article discusses how to create a CEC file for a Board Support Package (BSP) by using the CEC Editor. The concepts used here also apply to other types of CEC files including adding new features to a BSP and adding platform independent drivers to the Catalog. To keep the CEC file simple, the BSP will include a boot loader and two drivers: one for a device called My Device and a USB OHCI Driver. (10 printed pages)

Contents

Introduction
Overview of CEC Files
Getting Started
Adding BSP Information
Adding a Driver
Adding the Boot Loader
Putting the CEC into the Catalog
Making Changes
Summary

Introduction

The CEC Editor is one of the many new features of Platform Builder for Microsoft® Windows® CE .NET. The CEC Editor enables Windows CE .NET developers to create and modify Catalog Feature Files (CEC) by using graphical tools. CEC files are used to communicate the contents of a Board Support Package (BSP) from a vendor to Platform Builder.

Prior to Windows CE .NET, BSP developers used a text editor to modify CEC files. This required intimate knowledge of CEC files, which most people did not have. The only way to graphically see the results of a CEC file was to import the CEC file into the Platform Builder Catalog. These restrictions prevented some Platform Builder users from modifying the catalog.

In Windows CE .NET, the CEC Editor contains the intimate knowledge, enforces the CEC file rules and graphically displays changes as you make them. This tool breaks down the barriers to using CEC files.

Overview of CEC Files

The purpose of this article is to discuss the use of the CEC Editor, not to discuss the details of CEC files. For readers familiar with CEC files, the CEC file is correlated to the editor when it is important. For users new to CEC files, there is an introduction consisting of key words used in CEC files.

What do you need to know about CEC files to use the CEC Editor? The simple answer is not much. You need to know that CEC files describe a set of features and their relationships. If you understand CEC files, you will also need to know what the CEC Editor calls the blocks in a CEC file. Table 1 shows the blocks make up a CEC file, as defined in Platform Builder Help.

CEC Editor Name Block Name Content
File Properties CECInfo Basic information about the .CEC file, such as the name, description, vendor, and version.
Feature Group
Child Node\Feature Group 		ComponentType Feature Groups or a generalized feature that may have many different implementations.
Feature Implementation Definition of an implementation for a component type.
Build Method BuildMethod Information needed for the build system to build and deploy this feature to an operating system (OS) image.
BIB Information BIBInfo Description of the Project.bib file entries for an implementation.

Table 1. CEC File Blocks

The Platform Builder Help was augmented in the table by adding the first column, which defines the names that the CEC Editor uses for the CEC Blocks. Use the table to cross-reference between the CEC Editor and CEC files.

Other CEC file topics will be discussed later in the context of the CEC Editor.

Getting Started

To get started developing the CEC file, start the CEC Editor, on the Platform Builder menu, click Tools and then click CEC Editor. The CEC Editor opens, with a new blank CEC file opened, as shown in Figure 1. Changes that you make to the CEC file are displayed as children of the Catalog.

Figure 1. The CEC Editor with new CEC file

The CEC Editor uses several icons as buttons, and also uses them in the Catalog view. The Feature Group and Feature icons are familiar from Platform Builder 3.0. Other icons used in the editor are new to Windows CE .NET. Table 2 describes the icons used by the CEC Editor.

Icon Description
Inserts a Feature Group
Inserts a Feature
Inserts a Build Method
Inserts a Build Action
Inserts a Copy Action
Inserts a Custom Action
Inserts an Environment Action
Inserts a Source Action
Inserts a Documentation Setting
Inserts a .bib file
Inserts a BIB Record
Adds the CEC file to the Catalog
Removes the CEC file from the Catalog
Updates the CEC file in the Catalog

Table 2. CEC Editor icons

The new file created when you open the CEC Editor is a good starting point, but you can also click New on the File menu. To get started, identify the CEC file by clicking CEC Properties on the File menu. This will open the CEC File Properties dialog box. You use this dialog box to modify the CEC file's CECInfo block.

The CEC Editor creates a Globally Unique Identifier (GUID) for the file when you create a new file. One of the new features of the CEC Editor is the New button next to all GUID edit fields. The New button allows you to update the GUID. This is a very handy feature when using an existing CEC file as a base for a new file. Prior to Windows CE .NET, you had to run GUIDGEN to generate a new GUID and then copy it to a text editor.

An asterisk (*) precedes the Name field, indicating that the field is required. Choose an appropriate name that describes your project.

You have now identified the file. If you are familiar with the CECInfo block, you will notice that the CEC File Properties dialog box does not allow you to edit the version number. The Editor automatically sets it to 4.00, which is the version of Platform Builder.

Adding BSP Information

The next step is to insert the new BSP into the BSPs folder in the Catalog, so you need to see the BSPs folder.

To show the BSPs folder and the current Platform Builder Catalog

  1. On the menu, click View/CEC Only. This will clear CEC Only and show the Platform Builder Catalog with your new CEC file, as shown in Figure 2. With the BSPs folder visible, you can add the new BSP to it.

    One of the benefits of the CEC Editor is that it enforces CEC rules. The editor does this by graying out icons in the tool bar when they cannot be used. When you select the BSPs folder, you will see that the only icon that can be selected is the Feature icon, so you can only insert a Feature.

    The CEC file inserts the Feature as a BSP because the Feature is a child of the BSPs folder. The Feature is a BSP because the BSP Info tab is selectable. The Default Drivers list is empty now. After you insert a driver, you will learn about the BSP Info tab.

  2. On the General tab, type My BSP: ARMV4 as the name of the BSP. You are not required to include the processor type in the name, but it makes it easier for your customers to identify the correct BSP to use. You should not use parenthesis in the name. After importing the CEC file into Platform Builder and creating a new platform, parenthesis cause an error that states, "This CPU is not supported by your installation of the Windows CE .NET Development Tools."
  3. Use the GUID created by the editor. You can choose any version number, but 4.0.0.0 is the standard. The other fields identify your company and the BSP, so you should enter logical information, except for the Feature Size information, which is given to you.

    The Feature Size Information makes it easier for the users of the BSP to predict the amount of ROM space that used by the feature. In the case of the BSP Feature, the amount of additional ROM space that the OAL and default files use determines the size. Your customers will appreciate this information if you provide it.

  4. On the Advanced tab, fill in the BSP Directory. The BSP Directory tells the Catalog which directory contains the BSP source files. Set this to your BSP directory name, as it is in C:\Wince400\Platform\<BSP Directory>. In this case, the <BSP Directory> is MyBSP.

    Note that the directory name does not have spaces. The build tools do not work well when there are spaces in directory names.

  5. It is now important to identify which CPUs are supported by your BSP. To do this, insert a Build Method to the My BSP: ARMV4 BSP Feature. Change the step to BSP and set the CPUs to the CPU that your BSP supports In this case select ARMV4. If the BSP is specific to either Headless or Display based devices, you should also specify that here. If neither is specified, leave both blank.

Adding a Driver

Now that the Catalog contains My BSP, it is time to add some content to My BSP. To demonstrate all of the steps for adding a driver, this example uses an imaginary driver called My Device. A later example will add a USB OHCI driver, which has an existing Feature Group in the Platform Builder Catalog.

Some things to know before you begin:

  • Features always have a parent that is a Feature Group
  • Device drivers are Features
  • Device drivers always support some device type or standard
  • The device type or standard is the Feature Group
  • The Feature Group for device drivers belongs in a folder named Device Drivers

With that information, you know that you must define the device type for My Device. This means you must add a Feature Group and add it to the Device Drivers folder. There is no Device Drivers folder yet, and there is no option in the menu to insert a folder. The solution to adding a folder is that when you add the Feature Group, you can add the folder at the same time. There are two ways to add the Feature Group:

  • Option 1: add the Feature Group to My BSP. This works but you must manually add the folder at the end of the process.
  • Option 2: add the Feature Group to the Device Driver folder in the Platform Builder Catalog. This works, and the folder is added automatically at the end.

Using either method will give the same result. This example uses option 1 and explains out the differences between option 1 and option 2 throughout.

To add the Feature Group

  1. Click My BSP and then insert a Feature Group.
  2. Give the device type the name My Device Type.
  3. The device type for My Device is new to Windows CE, so you will use the new GUID. Set the Group to \Device Drivers, which defines the Device Drivers folder.

    The Group is automatically filled in for you if you use option 2.

  4. On the Advanced tab, add device to All Required.
    Note   When you start typing in the small text box, the Add button will become active.
  5. After you select Add, the text is added to the larger list box. The All Required and Any Required boxes are passes to sysgen when building the driver using the Build Selected Feature. These are lists of targets from the public\common\CESYSGEN\makefile.

    Now you are ready to add the device driver to My Device Type. Recall that device drivers are Features.

  6. Insert a Feature into the My Device Type Feature Group.
  7. Name the Feature My Device, and set the Version to 4.0.0.0.
  8. On the Advanced tab, set the BSP Directory to MyBSPDir, which is the directory you are using for the BSP.

    The directory name must match the directory name of the platform described by the CEC file. It should not include any spaces, because the build tools do not handle spaces in directory names very well.

  9. Next you will add the Device Driver folder. Click OK, click My Device Type and then press the DELETE key.
  10. The Catalog will refresh and when it finishes the Device Drivers folder will appear with My Device Type in it.
    Note   The reason the folder is added is that when you added My Device Type, it was added as a child to of My BSP (specifically it was added with a Children() setting). When you press DELETE, the Children() setting is deleted, but not the Feature Group.

    If you are using option 2, which involves adding My Device Type to the Device Drivers folder after selecting OK, the Device Driver folder, including the new Feature Group and Feature, move to become children of the BSP, as shown in Figure 2. This happens because in the Feature Group, you set the Group field to Device Drivers and in the Feature, you set the BSP Directory to MyBSPDir. This tells the Catalog to put the driver in the BSP's Device Drivers folder.

    Figure 2. My Device as child of the BSP

As with the BSP earlier, the new driver needs to tell the Catalog which CPUs it supports. Do this just as you did for the BSP. First you need to add a Build Method.

To set a Build Method

  1. Set the Step to BSP and select the correct CPU. Now the CEC Editor has enough information to know that the driver is available for use with the BSP. You can now set the driver to be a default driver for the BSP.

    On the BSP Info tab, you will see other drivers in the Platform Builder Catalog in addition to the drivers in your BSP. When your customers create a new platform using the BSP, the platform will include the default drivers. Drivers not listed as default drivers are available for adding to the platform.

  2. You now must include the driver in the ROM image so that your customers can use it. You do this by adding a .bib file entry. Insert a .bib file into the My Device driver.
    Note   A .bib file is a container for BIB records.
  3. After adding the .bib file, add a BIB record. If you are familiar with editing .bib files, you know that you would normally add some text to the .bib file, such as the following: 
    MODULES
IF !BSP_NOMYDRV
MyDrv.dll   %_FLATRELEASEDIR%\MyDrv.dll    NK   SHC
ENDIF

    Instead, by using the CEC Editor you will use the dialog box in Figure 3 to fill in the blanks. You will not need the IF !BSP_NOMYDRV condition because the BIB Info will only be inserted into the final ROM image if the My Device driver is included in the workspace and built.

  4. Specify that the MyDrv.dll, in the $(_FLATRELEASEDIR), should be included in the NK memory section as MyDrv.dll.
  5. To match the .bib file segment above, set the File Attributes to System, Compressed, and Hidden.
  6. Leave the DLL in the Modules section.

    Figure 3. The Insert BIB Info (BIB Record) dialog box

There are some registry entries that must be added for My Device Driver.

To add registry entries for My Device Driver

  1. Use a Copy action prior to running Makeimg to copy the registry file to the release directory.
  2. Use the CEC Editor and a driver specific registry file. The registry file is MyDrv.reg, which resides in the Drivers\MyDrv directory of the BSP directory.
  3. Insert a Build Method, and select the PreMakeImg Step and the ARMV4 CPU.

    Platform Builder performs this Build Method after the Post Buildrel step and before running makeimg.

  4. Insert an Action\Copy to the Build Method. Set the Source file to $(_TARGETPLATROOT)\Drivers\MyDrv\MyDrv.reg and the Target Directory to $(_FLATRELEASEDIR).
  5. Platform Builder copies the driver's registry file to the release directory just before running makeimg. The fmerge utility will merge the driver registry file and project.reg. When makeimg runs, the registry will include settings for this driver.
  6. The driver will be built and included in the ROM image with the correct registry settings. Users will want to be able to browse the source code. To allow them to browse source, you can add either a Build action or a Source Code action.

    Adding a Build Method with a source file will give you the most control. This will allow you to both browse the source and perform a Feature Build on the source.

  7. Set the file to $(_TARGETPLATROOT)\Drivers\MyDrv\sources. Your customers can now browse the source and you can use the sources file to control the build. Platform Builder will display the files listed as SOURCES from the sources file.

Adding the Boot Loader

Another common component of BSPs is the boot loader. It is not a driver, so it will not be added to the Device Drivers' folder. Instead, the boot loader is a child of the BSP.

To add the boot loader

  1. Insert a Child Node\New Feature Group.
  2. Give the Feature Group a name, for example Boot Loader.
  3. Select the Optional Child check box at the bottom of the dialog box.

    If you select the Optional Child check box, the Boot Loader is not automatically added when the New Platform Wizard creates a platform based on the BSP. If it is not selected, Platform Builder automatically adds the Boot Loader to the platform and it cannot be deleted. Because most users of your BSP will not build the boot loader, it is recommended that you select Optional Child.

  4. Insert a Feature into the boot loader Feature Group. You must fill in the BSP Directory.
  5. After you add the Feature, add a Build Method just as you did to My Device.
  6. Insert an Action\Source Browsing to the Build Method. You can add one Action for each source file, or set the Build File to the sources file for the boot loader. For example, you can use $(_TARGETPLATROOT)\bootloader\SOURCES. This Action will allow users of the BSP to browse the source files from the Workspace window.

Putting the CEC into the Catalog

The last step is putting the CEC file into the Platform Builder Catalog.

To put the CEC file into the Platform Builder Catalog

  1. Save the CEC file. This is important because saving the file makes the Add to Catalog feature available, and you have not saved it yet. After it has been saved for the first time, the file is auto-saved when you add to or update the catalog.
  2. On the menu, slick Catalog\Add to Catalog.
  3. Look in the Platform Builder Catalog for the new BSP, called My BSP: ARMV4. It is there because the CEC Editor does not notify Platform Builder that it updated the Catalog.
  4. To notify the Platform Builder that it updated the Catalog, right-click the Catalog and then click Refresh Catalog. The BSP is now in the Catalog.

Making Changes

For the first driver, you chose a new type of device. Now you have a driver to support the USB OHCI on an SA1111 chip. This will require that the Feature Group be the existing USB Feature Group. The USB Feature Group can be found in the Catalog at Catalog\Device Drivers\USB.

  1. Add the driver Feature to the USB Feature Group. This may not make sense now, but after you have completed all of the steps, the driver will be in the My BSP\Device Drivers folder.
  2. Add these in the same way that you did for the My Driver Feature. Name it SA1111 OHCI and fill in vendor-specific information.
  3. Set the BSP Directory to the MyBSPDir directory. This step is important because otherwise the driver will be added to the common Device Drivers' folder. Fortunately, when the BSP Directory is missing, the error will show up graphically in the CEC Editor. The driver shows up as a child of the Catalog, instead of the BSP.
    Note   This is easy to fix, just add the BSP Directory to the driver, right-click any of the components, and then click Refresh.
  4. Add a Build Method and .bib file as you did for My Device.
  5. Updating the Catalog by selecting Catalog\Update in Catalog, and then refresh the catalog in Platform Builder so that you can see the changes.

Summary

The CEC Editor is a great new feature of Platform Builder for Windows CE .NET. This tool takes some of the mystery out of creating and maintaining CEC files. There are still some quirks to using it, but these are caused by the simplicity of the underlying CEC file structure.

This article describes how to use the CEC Editor from the point of view of creating a full BSP. However, the techniques applied are the same that you could use to add a new feature to the Catalog

posted @ 2004-12-07 20:04  nasiry  阅读(3105)  评论(6)  编辑  收藏  举报