Ce.bib File and the ROM Image (Compact 2013)
3/26/2014
The Makeimg build phase combines all binary image builder (.bib) files into one file called ce.bib, which it stores in the flat release directory. Ce.bib defines all of the modules and files to include in the OS image, and where to place them within ROM on the device. This topic provides an overview of ce.bib, and discusses the relationship between ce.bib and the final ROM image.
The build system uses .bib files to determine which files and modules go into the final run-time image. The ce.bib file is the concatenation of the .bib files in the OS project. For more information about the .bib file format, see Binary Image Builder (.bib) File.
Ce.bib File Sections
Each .bib file contains the following four sections:
- MEMORY: Specifies and names regions for memory usage on the device.
- CONFIG: Specifies output options.
- MODULES: Specifies binary executable files to include in nk.bin, the single image file that contains all modules in the image.
- FILES: Specifies non-executable files to include in nk.bin.
The following code example shows the structure of ce.bib, along with entries for memory regions, configuration, modules, and files. (For readability, many lines have been removed and the paths simplified.) Subsequent sections in this topic explain the MEMORY, CONFIG, MODULES, and FILES sections in more detail.
MEMORY
DMA 80100000 00030000 RESERVED ; DMA, see platform.reg for 8237 driver
BLDR 80130000 00050000 RESERVED ; boot loader loads here - see bldr.bib
BLDRRAM1 80180000 0007C000 RESERVED ; boot loader uses this as RAM - see bldr.bib
NK 80220000 009E0000 RAMIMAGE
RAM 80C00000 00400000 RAM
...
CONFIG
AUTOSIZE=ON
ROMOFFSET=80000000
KERNELFIXUPS=ON...
FSRAMPERCENT=0x00000010
ROMFLAGS=10
...
MODULES
; Name Path Memory Type
; -------------- --------------------------------------------- -----------
nk.exe C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\oal.exe NK SHZ
kitl.dll C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\kitl.dll NK SHZ
kernel.dll C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\kernprof.dll NK SHZ
coredll.dll C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\coredll.dll NK SHM
oalioctl.dll C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\oalioctl.dll NK SHK
k.coredll.dll C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\k.coredll.dll NK SHMK
locale.dll C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\nlslocale.dll NK SHQ
...
FILES
; Name Path Memory Type
; -------------- --------------------------------------------- -----------
ceconfig.h C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\ceconfig.h NK
wince.nls C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\wince.nls NK SHU
initobj.dat C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\initobj.dat NK SH
boot.hv C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\boot.hv NK SH
default.hv C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\default.hv NK SH
tahoma.ttf C:\WINCE800\public\common\oak\files\tahoma.ttf NK SHU
...
MEMORY Section
The memory section defines named memory regions on the target platform. The following code example from the previous section shows five named regions: DMA, BLDR, BLDRRAM1, NK, and RAM. The first three regions are reserved. The NK region is designated as a RAMIMAGE, which the build system uses to create a corresponding .bin file (in this case, nk.bin). The last region, RAM, designates a range of RAM to use for a file system or for some other use. (The contents of this region are specified in the MODULES and FILES sections.)
MEMORY
DMA 80100000 00030000 RESERVED ; DMA, see platform.reg for 8237 driver
BLDR 80130000 00050000 RESERVED ; boot loader loads here - see bldr.bib
BLDRRAM1 80180000 0007C000 RESERVED ; boot loader uses this as RAM - see bldr.bib
NK 80220000 009E0000 RAMIMAGE
RAM 80C00000 00400000 RAM
In the above code, the MEMORY section reserves 16 MB for RAM: physical RAM on the device starts at address 0x800000, and the RAM section starts at address 0x80C00000 with a length of 0x0040000 bytes, for a total of 16 MB (0x00C00000 + 0x0040000 = 0x01000000 or 16 MB). It also reserves two regions for a boot loader. The boot loader itself has a .bib file (bldr.bib) that defines its regions as shown in the following code example:
MEMORY
; Name Start Size Type
; ------- -------- -------- ----
BLDRS 00130000 00050000 RAMIMAGE
RAM 00180000 0007EF00 RAM
IVT 001FEF00 00000100 RESERVED ; See pIVT
BOOTARGS 001FF000 00001000 RESERVED ; Boot arguments, see also BOOT_ARG_PTR_LOCATION, BOOT_ARG_LOCATION_NP, BOOT_ARG_PTR_LOCATION_NP
The BLDRS memory region address and size corresponds to the BLDR region in the config.bib file, after the build system applies the ROMOFFSET of 0x8000000. The same rule applies to the RAM for the boot loader, which in turn also specifies RESERVED memory. (The OS uses RESERVED memory, but RESERVED regions are not included in the run-time image or RAM space.) Because the MEMORY section entry specifies BLDRS as RAMIMAGE, the build system creates a corresponding .bin file, in this case bldrs.bin.
CONFIG Section
The optional CONFIG section defines configuration settings that allow Romimage.exe to customize its output.
For example, FSRAMPERCENT specifies the amount of RAM the kernel allocates for use by the file system or object store, if you selected these features. For more information, including a complete list of configuration options, see CONFIG Section.
MODULES Section
The MODULES Section specifies binary executable files to include in the .bin file. The Makeimg build step “fixes up” executable files; that is, the Romimage Tool (romimage.exe) modifies the executable files to use the run-time virtual addresses.
Important
Do not include non-executable files in the MODULES section, because Romimage cannot fix these up. This prohibition includes managed .dll or .exe files, which are not executable binary files, but instead consist of intermediate code. Including non-executable files in the MODULES section can cause build errors in the Makeimg phase.
The following code example from the above config.bib file shows a partial listing of the modules to include in nk.bin. The Memory column specifies the memory region in which the build system places the module (in this case, the NK memory regions defined in the config.bib MEMORY section).
MODULES
; Name Path Memory Type
; -------------- --------------------------------------------- -----------
nk.exe C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\oal.exe NK SHZ
kitl.dll C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\kitl.dll NK SHZ
kernel.dll C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\kernprof.dll NK SHZ
coredll.dll C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\coredll.dll NK SHM
oalioctl.dll C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\oalioctl.dll NK SHK
k.coredll.dll C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\k.coredll.dll NK SHMK
locale.dll C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\nlslocale.dll NK SHQ
...
For the boot loader, the MODULES section of bldr.bib specifies that you place the module in the BLDRS memory region and, because BLDRS is defined as RAMIMAGE, into a corresponding bldrs.bin file as well. This is shown in the following code example:
MODULES
; Name Path Memory Flags
; -------- --------------------------------------------------------------------------------------- ------- ------
nk.exe $(SG_OUTPUT_ROOT)\platform\$(_TGTPLAT)\target\$(_TGTCPU)\$(WINCEDEBUG)\bldrS.exe bldrS
By default, Makeimg does not compress files specified in the MODULES section. To compress files in this section, add the ‘C’ flag. For information about setting flags, see Read and Interpret MODULES and FILES Entries.
DLL Module Processing. DLL files consist of a portable executable (PE) header, a section table, and various sections. If the MODULES section includes a DLL, Makeimg parses it to strip off the PE header and the section table before it fixes up the remaining DLL sections and adds them to the ROM image, as shown in the following figure.
Note
Because of the 4 KB-page alignment in ROM, information in ROM might not have exactly the same arrangement as the DLL file.
.png "Analyzing ROM Size - DLL")
FILES Section
The FILES Section specifies non-executable files — such as data files, resource DLLs, audio files, and bitmap files — to include in nk.bin. The FILES section also specifies managed code files, which are not considered executable because they consist of intermediate code, not native code. The following code example from config.sys shows a partial list of the files to add to the NK memory region, which in turn instructs the build to include these in nk.bin.
FILES
; Name Path Memory Type
; -------------- --------------------------------------------- -----------
ceconfig.h C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\ceconfig.h NK
wince.nls C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\wince.nls NK SHU
initobj.dat C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\initobj.dat NK SH
boot.hv C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\boot.hv NK SH
default.hv C:\WINCE800\OSDesigns\RelDir\VirtualPC_x86_Release\default.hv NK SH
tahoma.ttf C:\WINCE800\public\common\oak\files\tahoma.ttf NK SHU
...
By default, Makeimg compresses files specified in the FILES section. To leave a file uncompressed, add the ‘U’ flag.
See Also
Concepts
Understand ROM Size and Structure
Read and Interpret MODULES and FILES Entries