Binary Image Builder File (Windows Embedded CE 6.0)

Article
01/05/2012

1/5/2010

A binary image builder (.bib) file defines which modules and files are included in a run-time image.

During the build process, Makeimg.exe uses several .bib files to generate ce.bib, a merged initialization file. Then, Romimage.exe uses ce.bib to determine which binaries and files will be included in the run-time image. It also uses ce.bib to determine how to load modules and files into the memory of the run-time image that is downloaded to target device.

Sections in a BIB File

The following table shows the major sections that a .bib file can contain.

Section	Description
MEMORY	Defines the physical memory that is available, including starting address, size, and type of memory. This section is in the Config.bib file, located in the %_PLATFORMROOT%\<MYBSP>\Files directory.
CONFIG	Defines configuration options for Romimage.exe to customize its output. By default, this section is in the Config.bib file. However, you are not required to include a CONFIG section in a .bib file.
MODULES	Specifies the object modules to be loaded into areas of memory by Romimage.exe. Object modules that are not compressed in the MODULE section will execute in place.
FILES	Reserves a section of memory for .lib files.

Types of BIB Files

There are several different types of .bib files, described as follows.

Platform.bib

The Platform.bib file defines:

The hardware-dependent modules and files, such as driver files, for the target device
The modules and file entries for the run-time image, such as .exe files and waveform audio (.wav) files

Platform.bib is located in the %_PLATFORMROOT%\<MYBSP>\Files directory.

Project.bib

The Project.bib file defines the modules to include in the run-time image that are project-specific. When you create your own modules and applications, you must add them to the MODULES section in Project.bib.

Project.bib is located in the %_WINCEROOT%\PUBLIC\CEBASE\OAK\FILES directory.

Common.bib

The Common.bib file defines the common display drivers and core system modules to include in the run-time image.

Common.bib is located in the %_WINCEROOT%\PUBLIC\COMMON\OAK\FILES directory.

Config.bib

The Config.bib file defines configuration information for ROM and RAM. It also contains the MEMORY and CONFIG sections for the run-time image.

The MEMORY section of Config.bib defines the memory table for the run-time image by specifying the name, address, size, and type of the MEMORY regions that are within the run-time image.

Config.bib is located in the %_PLATFORMROOT%\<MYBSP>\Files directory.

BIB File Modifications

When you update either Platform.bib or Project.bib to include a file, specify the following items:

Name: The source file name to add to the run-time image
Path: The location of the file after the build process copies it to the flat release directory
Memory: The region listed in the MEMORY section that is defined as RAMIMAGE type

Note

Each run-time image has only one RAMIMAGE region.
Type: The file attributes to set for the file in the run-time image

In the MEMORY section of the .bib file, use the Address and Size parameters to define the section of memory devoted to RAM and also ROM. The Address parameter specifies the address where the RAM section starts. Together, the Address and the Size parameters indicate the address where the RAM section ends.

In the MEMORY section, the run-time image must be defined as RAMIMAGE type by using the Type parameter. The RAM memory region must be defined as RAM type.

For more information, see MEMORY Section.

To configure the .bib files, you must specify a data format for the run-time image. After you decide on a data format for your run-time image, define this format in the CONFIG section of the Config.bib file by setting values for ROMSIZE, ROMSTART, and ROMWIDTH. For more information about data formats, see Run-Time Image Files and CONFIG Section.

The following illustration shows the relationships among the ROMSTART value, the ROMSIZE value, and the memory table parameters for the run-time image memory sections.

Memory regions of run-time image

Romimage.exe outputs a binary image (.bin) file. The .bin files contain information about the run-time image that the boot loader uses to start the run-time image. The .bin files are organized into logical units, which are known as records, and exist only in the RAMIMAGE section of memory.

BIB Entry Example #1

The following code example shows an entry in Project.bib.

MODULES
; Name        Path                           Memory Type
; --------------  --------------------------------------
IF IMGINCLUDEAPPS
  myapp.exe   $(_FLATRELEASEDIR)\myapp1.exe  NK   SH
ENDIF

In this example, if you set a user-defined environment variable, IMGINCLUDEAPPS, before you run Makeimg.exe, Makeimg.exe processes this entry by including the MyApp1.exe input file as the MyApp.exe output file. Then it loads the MyApp.exe output file into a MEMORY region named NK as a file. The S and H flags are set to indicate that myapp.exe is both a system file and a hidden file.

BIB Entry Example #2

The following code example shows an entry in Project.bib.

MODULES
; Name        Path                           Memory Type
; --------------  --------------------------------------
IF IMGNODEBUGGER !
   myproj.exe  $(_FLATRELEASEDIR)\myproj.exe  NK  S
ENDIF

In this example, if you did not define IMGNODEBUGGER, Makeimg.exe processes this entry by including the Myproj.exe file and loading it into the NK MEMORY region. The "S" flag is set to indicate that myproj.exe is a system file.

For more information on the syntax of the IF statements in the previous examples, see Preprocessing Using Romimage Conditionals.

The remainder of this topic describes the flags that you can use in the MODULES and FILES sections.

BIB File "K" Flag

The executables that are listed in the FILES Section – or those that arrive onto your device some other way, such as loading from the release directory or from a storage card – are fixed up at run-time when they are loaded. Therefore, there is an impact on performance when those modules are loaded.

The executables that are listed in the MODULES Section of ROM are fixed up at makeimg-time. Romimage.exe chooses which virtual addresses all those DLLs and EXEs will run from, and sets them up to always run from there.

The “K” flag indicates whether the DLL will run in the kernel space, which is above 0x80000000, or user space, which is below 0x80000000. If you try to load a kernel DLL into user mode or a user mode DLL into the kernel, you will not load the DLL and will receive a debug message that resembles the following:

RETAILMSG (1, (L"!!!ERROR! Trying to load DLL '%s' fixed-up to user address into Kernel.\r\n", lpszFileName));
RETAILMSG (1, (L"!!!ERROR! MUST SPECIFY 'K' FLAG BIB FILE.\r\n"));
RETAILMSG (1, (L"!!!ERROR! Trying to load DLL '%s' fixed-up to kernel address into user app.\r\n", lpszFileName));
RETAILMSG (1, (L"!!!ERROR! CANNOT SPECIFY 'K' FLAG BIB FILE.\r\n"));

You can fix this error in several different ways:

In the .bib file entry, add or remove the “K” flag so that your DLL only loads in one location. If you must load it in kernel mode, add the "K" flag. If you must load it in user mode, remove the "K" flag.
If you must run the DLL in user mode and kernel mode concurrently at any time, put two copies of the DLL in ROM. One with the “K” and one without the "K". For example, add both k.mydll.dll with a “K” and mydll.dll without a "K". The naming modification means that both kernel-mode and user-mode code can link against “mydll.dll” and achieve the correct result. Be aware that splitting DLLs in this manner costs ROM and RAM space. Even if the same code was arranged to run two times from ROM, the run-time code would still take double as much RAM because it would have to be fixed up in two locations.
If for some reason you have a DLL that has to be ab le to load in both locations but never concurrently, you can put it into the FILES section or load it from your release directory. We do not recommend this because you will receive load failures if you try to load the DLL in both kernel and user mode at the same time. The same file can only be loaded one location at a time.

Best Practices for Adding or Removing the “K” Flag

When you add a DLL to the kernel, or load it in both kernel and user mode, determine whether it really has to be able to load in both kernel and user mode. Investigate moving it, and anything that depends on it, into user mode. For example, move it to services.exe or udevice.exe. Or, investigate breaking up the DLL into separate kernel-mode and user-mode parts.
When removing the “K” flag, check whether anything in the kernel ever tries to load the DLL, because you could break some functionality by moving it. Similarly, when you add the "K" flag to a DLL, make sure that no user-mode code loads the DLL.

User interface (UI) elements cannot be loaded into the kernel. The kernel provides a mechanism for redirecting a UI to a user-mode process.

For more information, see Displaying a User Interface from a Kernel-Mode Device Driver.

Other BIB File Flags

"Q" Flag

If you put a DLL into the MODULES section and want it to load in both user mode and kernel mode, you can use the "Q" flag. For example, the following line of code:

    Sample.dll             $(_FLATRELEASEDIR)\Sample.dll   NK  SHQ

is equivalent to the following two lines of code:

    Sample.dll             $(_FLATRELEASEDIR)\Sample.dll   NK  SH
    k.Sample.dll           $(_FLATRELEASEDIR)\Sample.dll   NK  SHK

"Z" Flag

There is also a “Z” flag which corresponds to the “K” flag from earlier versions of Windows Embedded CE. “Z” cannot be combined with “C”, the compression flag, but there are no similar restrictions on “K” or “Q.”

Share via