PbcXml: Metadata in PB

  • Article

When Platform Builder interacts with a CE OS build tree ("winceroot", i.e. C:\WINCE600), it needs to know a little bit about the contents of that build tree. For example, it needs to know what SYSGEN variables are available and what they mean. It needs to know what BSPs are available and what options they provide. It needs to know what CPUs have been installed. We refer to this information as the winceroot metadata.

This data is either hardcoded into PB, or encoded into the "catalog". The catalog was historically used when data changed so often that code changes for the data got to be annoying. In any case, the data was still essentially hardcoded into PB since the catalog lived in PB's Program Files directory.

As PB has matured, we've tried to move in the direction of decoupling PB from the winceroot. One consequence of this is that we try to move as much metadata out of PB and into the winceroot itself. The first step was to move the catalog from PB's Program Files directory into the winceroot. Then we moved some of the hardcoded information into various metadata files in the winceroot or figured out some way to dynamically infer that metadata from existing files in the winceroot. Finally, in PB 6.0, we rewrote the "catalog" system using XML instead of "CEC" files. One of the goals was to make it usable with all kinds of new metadata. We consolidated a few of the other metadata files into the catalog as well as including all of the metadata from the old catalog. The next version of PB will have many additional metadata types in the catalog.

One immediate disadvantage of this is that while we want PB to be decoupled from the winceroot, we have immediately created a hard break between PB 5.0's metadata format and PB 6.0's metadata format. This is why PB 6.0 doesn't work with the CE 5.0 build tree as shipped. Since PB n had never really worked well with the CE n-1 build tree before, we didn't consider this to be a particularly significant problem. (PB 6.0 includes a tool called "CecImport.exe" that can be used to extract the bare-bones 5.0-format metadata from a CE 5.0 build tree and write it in the 6.0 format. This is unsupported, but it may work if you really want to use PB 6.0 tools with a CE 5.0 tree. Additional tweaking beyond the automatic conversion may be required for best results.)

Another disadvantage is that PB n will choke on the metadata from PB n+1. This probably could have been avoided had we used a somewhat more relaxed mechanism for parsing the metadata files. We decided that we wanted the schema to be as tight as possible so that catalog authoring errors would show up quickly. Instead of ignoring unrecognized metadata, we raise an error.

The new format brings several advantages. As XML, it is a lot easier to manipulate with general development tools (Visual Studio's XML editor, XmlSpy, or even Notepad) than the old catalog database. The schema (PbcXml600.xsd, which may or may not be renamed for future versions) contains documentation for each element and attribute type (aka "what in the world was Doug thinking when he invented this element?"). Adding new data to the catalog is as easy as dropping a new XML file into the appropriate Catalog directory in the winceroot.

The manipulation of the catalog is managed by a C# assembly named "Microsoft.PlatformBuilder.Catalog.dll". This includes the object model for the catalog (classes corresponding to each XML element), helper functions for loading and querying the data, a system for determining where a catalog element should show up if the catalog "tree" is shown, a "catalog control" displaying the catalog as a tree view, and classes that know how to parse some of the CE 5.0 metadata and turn it into PB 6.0 catalog data. (While we don't publish this object model, we might do so in the future if there is sufficient demand. In the meantime, you are welcome to examine it with ILdasm or Reflector.)

We also included a rudimentary catalog editor with PB. This editor does not allow editing of the full range of metadata supported by the catalog, but it hopefully handles the most common tasks for component and BSP developers. To be honest, I never use it -- I just open the catalog files in Visual Studio's XML editor. Visual Studio finds the PbcXml600.xsd schema and that provides all the editing help I need.

When loading the catalog, the catalog's client generally requests "please give me a catalog for this winceroot". The catalog loader then enumerates all *.PbcXml files from the following locations and all subdirectories:

  • PB's Program Files "catalog" folder. This folder contains metadata about the current PB installation that is specific to PB and not winceroot-dependent.
  • winceroot\PUBLIC\*\Catalog
  • winceroot\PLATFORM\*\Catalog

I think there are actually one or two more places that the system checks for catalog files, but the exact list escapes me at the moment, and the locations listed above are the ones most commonly containing catalog files.

All subdirectories of the listed location are checked. If there is a "Catalog" directory, then all *.PbcXml files from that directory and all subdirectories are loaded. For example, if there is a C:\WINCE600\public\ie\catalog folder with subdirectories 1033 and 1041, then the loader will load catalog\*.pbcxml, catalog\1033\*.pbcxml, and catalog\1041\*.pbcxml.

The CE 6.0 catalog includes metadata for the following (as far as I remember -- I don't have access to the schema right now):

  • WinceRoot. Basic metadata about the current winceroot, such as the version of CE it contains. 
  • Core OSes. There is one CoreOS element for each Core OS (_TGTPLAT) supported by the winceroot.
  • BSPs. There is one Bsp element for each BSP installed in the winceroot. The PB catalog editor contains support for editing BSPs.
  • CPUs. There is once Cpu element for each CPU supported by PB. There is one CpuInstalled element for each CPU for which support has been installed.
  • OS Design Templates. There is one element for each OS Design Template. The OS Design Template is what drives the "New OS Design Wizard". It contains information about what features should be enabled by default for the new OS Design and what features should be shown in the series of option screens in the wizard.
  • Catalog Items. There is one Item element for each independent "feature" or "driver" in the catalog. The PB catalog editor contains support for editing catalog items.

Let me know if you have specific questions about the catalog or if there are areas you would like me to blog about.