Binary Image Builder (.bib) File (Compact 2013)

Article
11/04/2015

3/26/2014

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 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 below.

Platform.bib

The Platform.bib file defines the following:

The hardware-dependent modules and files, such as driver files, for the 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 project-specific modules to include in the run-time image. 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 ROM. The Address parameter specifies the address where the RAM section starts. The Sizeparameter is added to the Address parameter to indicate 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 Remarks in Romimage Tool (romimage.exe) 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 a 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 Remarks in Romimage Tool (romimage.exe).

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

BIB File Flags

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 to execute from a specific address at run-time when they are loaded. Therefore, performance will be slower when those modules are loaded.

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

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 loads in only 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 flag and one without. For example, add both k.mydll.dll with a K flag and mydll.dll without a K flag. The naming modification means that both kernel-mode and user-mode code can link to mydll.dll and achieve the correct result. Be aware that splitting DLLs in this manner uses both ROM and RAM. 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 you have a DLL that has to be loaded 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.

Whenever possible, we recommend that you load a DLL only into user mode. If you think a DLL may need to load in kernel mode, you may be able to move it to servicesd.exe or udevice.exe. Alternatively, you may be able to break the DLL into separate kernel-mode and user-mode parts.

When you remove 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 CeCallUserProc.

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

H Flag

The H flag applies the hidden attribute to a file, which prevents execution of the program. When you use the H flag for a program specified in a BIB file, the program will no longer execute by using the Run option on the Start menu, or by double-clicking the file in File Explorer.

Z Flag

The Z flag specifies versions of Windows Embedded Compact earlier than Windows Embedded CE 6.0. Z cannot be combined with C, the compression flag, but there are no similar restrictions on K or Q.

Conditional Statements

You can use Romimage conditional statements to selectively compile source code during the Make Image phase of the build process.

Platform Builder uses these statements to control options in the run-time image and to control variations between similar hardware. For example, you can choose to enable or disable profiling in the run-time image based on the conditional statements that you add to the source files.

The following code example shows the syntax for Romimage conditional statements:

IF <environment variable>[!]
...
ENDIF

Note that the IF and ENDIF conditionals don't support the || operator. To create a conditional statement that uses the || operator, use the #if and #endif statements instead. The following code example shows the syntax for a conditional statement that combines two variables using the || operator:

#if defined <environment variable 1> || defined <environment variable 2>
...
#endif