Contents of /trunk/linterm_tools/fw_builder/bundle-tools/FORMAT

Firmware bundle format "specification"

This is by no means a full specification. It's what I know after studying some existing firmware files. The format isn't that complex at all, and it seems it's really just an image/archive. When upgrading the firmware, the machine most likely extracts all files and puts them in the flash file system one by one.

The first 0x59 (89, but I'll try to specify all offsets in hex in this document) bytes are headers. After that, there's an index, and then you have the files. Interesting detail is that files are aligned on 4-byte boundaries in a slightly unusual way. Instead of using the beginning of the image for alignment, they use the end of the index. So if the index ends at offset 0x25ad, files will start at 0xxx1, 0xxx5, 0xxx9 or 0xxxxd.

Some notes before we start:

- In these files, multibyte numbers are always little-endian.
- I try to specify all numbers in hex, including offsets. Even if the 0x prefix is missing, it's hex.
- I try to avoid to duplicate any data from original bundle files, so just keep a hex-dump of an original image open while reading this.
- Especially in the header, there are a lot of zero-bytes. I won't mention them, so you can just assume everything I skip should be 0.

Okay, let's start with the header format now.

Bytes 0-7:
Some magic bytes. Easy to recognize is "BndL" (which is why I call the images "bundles" these days) at offset 3. These bytes seem to be the same in every image.

Byte f:
This byte is zero for add-on images and 06 for complete firmware files.

Bytes 13-16
The size of the whole bundle file, including headers, index, the checksum at the end, etc.

Bytes 17-36
Unknown, and mostly 0.

Bytes 37-3e
I used to think this was the filename of the file that should be flashed into the BIOS-chip. This isn't the case, however, since for example the mid.bin image that you need to flash into old devices before you flash them with a recent version of WinCE, has "k" (which is a thing I'll tell more about soon) here, instead of "mid_code". So apparently this is the name of the first file in the image. It'll be repeated in the index, so I don't know what's the use of it.

Bytes 3f-52
These bytes are some sort of "platform magic code". Compare this with the contents of the file "k" in the image, it should be the same. Both the BIOS and WinCE check these bytes before flashing the image, so make sure they're right. (Although setting them wrong won't harm anything, you'll just have to create a new image.)

This file is also present in add-on bundles. I don't know what their purpose is there exactly, maybe something about OS compatibility. Note that the the bytes that are set to ff in the firmware bundles, are set to 00 in add-on bundles.

Bytes 55-58
Unknown, but if you just set this to ffffffff (or probably anything else) the flasher software will accept it.

So long for the image header. Now we got the index, it starts immediately at byte 0x59, with an entry for every file in the image (plus a short entry to mark the end of the list. Let's just continue right away! I'll put the names I use for these fields in fwstruct.h in the descriptions too, in case I want to refer to them later.

Bytes 0-1 hsize
The length of this index item.

Byte 2 flen
The length of the filename. Slightly redundant, you can derive it from hsize.

Bytes 3-6 bios_flag
This is probably a bit field, but the only thing I saw in it so far is that it's set to a special value for the file that contains the BIOS (10000, other files have this one set to 20000).

Bytes 7-a offset
This is the offset where the file starts, relative to the beginning of the bundle.

Bytes b-e fsize
This is the size of the file.

Bytes f-12 time
The timestamp of the file, in Unix time format.

Bytes 13-16 checksum
This is the checksum of this file, I'll describe the checksum algorithm later.

Bytes 17-19 sys_flags
This is probably also a bit field, here I've only seen 10000 for system files and 50000 for other files. Don't know where to draw the line exactly, but then again, is there any logic in the difference between c:/windows and c:/windows/system?

Bytes 1a-(19+fnlen)
Here's the filename. Length of this field depends on the value of fnlen. Remember that this field isn't \0-terminated!

The index ends with an entry with only the hsize field, set to 0. Right after this (without any 0-padding), the first file starts. Every file is aligned on 4-byte boundaries, but, as explained before, relative to the end of the index.

At the end of the bundle, there's a checksum (this one is, for understandable reasons, aligned to 4-byte boundaries relative to the beginning of the whole file). This checksum is reasonably simple. To calculate it, sum up all the 32-bit integers in the file, i.e. bytes 0..3, 4..7, 8..b, ... until the end of the file (obviously not counting the checksum). If the data length is not a multiple of four, pad it with zeroes. Remember that these are also little-endian bytes. Subtract the result from 0xfffe1000 and you got the checksum.

So if you calculate the checksum of a while image bundle, including the checksum, the result should always be 0.

I hope this explanation is clear enough. Just mail me if you got any questions and I'll try to clarify the document. Note that some of the rules in this description don't apply to the images created by fwpack. Biggest difference is that fwpack does align all files to a 4-byte boundary relative to the beginning of the bundle. Have fun!


Wilmer van der Gaast <wilmer@gaast.net>
http://winterm.gaast.net/
1	Firmware bundle format "specification"
2
3	This is by no means a full specification. It's what I know after studying some existing firmware files. The format isn't that complex at all, and it seems it's really just an image/archive. When upgrading the firmware, the machine most likely extracts all files and puts them in the flash file system one by one.
4
5	The first 0x59 (89, but I'll try to specify all offsets in hex in this document) bytes are headers. After that, there's an index, and then you have the files. Interesting detail is that files are aligned on 4-byte boundaries in a slightly unusual way. Instead of using the beginning of the image for alignment, they use the end of the index. So if the index ends at offset 0x25ad, files will start at 0xxx1, 0xxx5, 0xxx9 or 0xxxxd.
6
7	Some notes before we start:
8
9	- In these files, multibyte numbers are always little-endian.
10	- I try to specify all numbers in hex, including offsets. Even if the 0x prefix is missing, it's hex.
11	- I try to avoid to duplicate any data from original bundle files, so just keep a hex-dump of an original image open while reading this.
12	- Especially in the header, there are a lot of zero-bytes. I won't mention them, so you can just assume everything I skip should be 0.
13
14	Okay, let's start with the header format now.
15
16	Bytes 0-7:
17	Some magic bytes. Easy to recognize is "BndL" (which is why I call the images "bundles" these days) at offset 3. These bytes seem to be the same in every image.
18
19	Byte f:
20	This byte is zero for add-on images and 06 for complete firmware files.
21
22	Bytes 13-16
23	The size of the whole bundle file, including headers, index, the checksum at the end, etc.
24
25	Bytes 17-36
26	Unknown, and mostly 0.
27
28	Bytes 37-3e
29	I used to think this was the filename of the file that should be flashed into the BIOS-chip. This isn't the case, however, since for example the mid.bin image that you need to flash into old devices before you flash them with a recent version of WinCE, has "k" (which is a thing I'll tell more about soon) here, instead of "mid_code". So apparently this is the name of the first file in the image. It'll be repeated in the index, so I don't know what's the use of it.
30
31	Bytes 3f-52
32	These bytes are some sort of "platform magic code". Compare this with the contents of the file "k" in the image, it should be the same. Both the BIOS and WinCE check these bytes before flashing the image, so make sure they're right. (Although setting them wrong won't harm anything, you'll just have to create a new image.)
33
34	This file is also present in add-on bundles. I don't know what their purpose is there exactly, maybe something about OS compatibility. Note that the the bytes that are set to ff in the firmware bundles, are set to 00 in add-on bundles.
35
36	Bytes 55-58
37	Unknown, but if you just set this to ffffffff (or probably anything else) the flasher software will accept it.
38
39	So long for the image header. Now we got the index, it starts immediately at byte 0x59, with an entry for every file in the image (plus a short entry to mark the end of the list. Let's just continue right away! I'll put the names I use for these fields in fwstruct.h in the descriptions too, in case I want to refer to them later.
40
41	Bytes 0-1 hsize
42	The length of this index item.
43
44	Byte 2 flen
45	The length of the filename. Slightly redundant, you can derive it from hsize.
46
47	Bytes 3-6 bios_flag
48	This is probably a bit field, but the only thing I saw in it so far is that it's set to a special value for the file that contains the BIOS (10000, other files have this one set to 20000).
49
50	Bytes 7-a offset
51	This is the offset where the file starts, relative to the beginning of the bundle.
52
53	Bytes b-e fsize
54	This is the size of the file.
55
56	Bytes f-12 time
57	The timestamp of the file, in Unix time format.
58
59	Bytes 13-16 checksum
60	This is the checksum of this file, I'll describe the checksum algorithm later.
61
62	Bytes 17-19 sys_flags
63	This is probably also a bit field, here I've only seen 10000 for system files and 50000 for other files. Don't know where to draw the line exactly, but then again, is there any logic in the difference between c:/windows and c:/windows/system?
64
65	Bytes 1a-(19+fnlen)
66	Here's the filename. Length of this field depends on the value of fnlen. Remember that this field isn't \0-terminated!
67
68	The index ends with an entry with only the hsize field, set to 0. Right after this (without any 0-padding), the first file starts. Every file is aligned on 4-byte boundaries, but, as explained before, relative to the end of the index.
69
70	At the end of the bundle, there's a checksum (this one is, for understandable reasons, aligned to 4-byte boundaries relative to the beginning of the whole file). This checksum is reasonably simple. To calculate it, sum up all the 32-bit integers in the file, i.e. bytes 0..3, 4..7, 8..b, ... until the end of the file (obviously not counting the checksum). If the data length is not a multiple of four, pad it with zeroes. Remember that these are also little-endian bytes. Subtract the result from 0xfffe1000 and you got the checksum.
71
72	So if you calculate the checksum of a while image bundle, including the checksum, the result should always be 0.
73
74	I hope this explanation is clear enough. Just mail me if you got any questions and I'll try to clarify the document. Note that some of the rules in this description don't apply to the images created by fwpack. Biggest difference is that fwpack does align all files to a 4-byte boundary relative to the beginning of the bundle. Have fun!
75
76
77	Wilmer van der Gaast <wilmer@gaast.net>
78	http://winterm.gaast.net/