Chapter 211. Bundle format
Table of Contents
A “bundle” file has a custom format, designed to minimise the code overhead of supporting the bundle on the target platform.
An advantage of a custom binary format over, for example, the use of a tar-file, is that the binary image held on an SD card for update delivery would be IDENTICAL to the version installed in the target's SPI flash.
With the tar-file format there is an overhead associated with individual entries (e.g. 512-byte header, per-item padding) that would mean for (the limited space) target SPI flash storage the processing code would need to extract the individual items for efficient storage in the SPI flash. This process can be avoided by a simple binary structure that is copied unchanged.
A host-based command-line tool is provided to create a correctly formatted bundle binary image. The binary image can then be used in manufacturing and in-field update processes to distribute the main target application and all associated target data.
211.2. Internal Structure
A bundle is a contiguous binary image containing a set of uniquely
tagged items. Individual items may be compressed (using the
zlib compression library). The bundle, and
each item within a bundle, can optionally have “arbitrary”
metadata attached. An overall hash object is used as a verification of
the data integrity of the complete bundle image, but individual items
also have the option of hashes covering their specific item data, and
in the case of compressed items, a hash that can be used to validate
the decompressed data.
The following figure highlights the underlying bundle format. The
<header> block provides the basic bundle identification and
description information. As previously discussed the bundle
<arbitrary> block is optional and may not be present in all
bundle images. It is perfectly valid for a bundle to contain no items,
though a valid bundle always contains the <item>
0x00000000 marker. The bundle is
completed with a <hash> object providing the verification code
for the complete bundle up to (but not including) the <hash>
Figure 211.1. <bundle> image
The optional <arbitrary> data that may be attached to the complete <bundle>, or to individual <item>s, is just a contiguous, uncompressed (as far as the bundle processing code is concerned), block of metadata. This metadata is not interpreted by the host-tool or bundle API code, but may be used by the target application as required. For example it could be used to hold a set of “key[=value];” pairs to provide “Identification” data for human-readable or programmatic access as required. e.g. it could encode tags like:
This arbitrary metadata could also be used as a mechanism for “Manifest” style information, which may be needed to support an organization's release process requirements.
Figure 211.2. <arbitrary> chunk
A <hash> object is used to hold a validation hash which can be
used to ensure data integrity. Support is provided for avoiding the
overhead of data verification by the
CYG_BUNDLE_HASH_NONE signature. However, in
most situations (especially when the bundle format is being used as an
in-field update delivery mechanism for example) some level of hash
verification should be considered.
Figure 211.3. <hash> chunk
Table 211.1. HASH signatures
||This is used when no data validation hash support is required. The <hash> object does not contain a “hash result”.|
||A standard 4-byte IEEE 802.3 (Ethernet) CRC-32 value.|
A 16-byte |
||A 32-byte FIPS PUB 180-2 SHA-256 hash value is held.|
A <bundle> comprises a set of items, each of which has a simple
fixed “enum”-style tag rather than using fixed
“ASCII filenames” to identify its specific
purpose or use. This tag “namespace” is managed by the
platform/customer and is not interpreted by the tools or bundle
package API. For example, the customer may have the following
0x8003==MotorTable, etc. The tag is used as both
the name and filetype as required by the target application. This
approach saves some binary space in the bundle format, plus the
run-time overhead of string parsing when dealing with bundle items.
Data items are held either uncompressed or compressed, and may contain an optional <arbitrary> metadata block.
For uncompressed items a single <hash> object is appended covering the validation of the complete <item> chunk.
Figure 211.4. Uncompressed <item>
For compressed items a seperate <hash> object is maintained provided the hash value for the original, uncompressed, source data.
Figure 211.5. Compressed <item>
All <bundle> and <item> descriptor fields are held in the binary image in the target native endianess, and it is the responsibility of the host tool used to create the bundle to ensure the correct target endianness is selected. This ensures that the deeply embedded target does not need to swap bytes, as might be the case if a single fixed endianness was chosen for the bundle format. The bundle header 32-bit signature is designed to allow the endianness of the bundle to be detected at run-time, providing a simple validity check on the target that the bundle is valid.
The host tool creating the bundle may need to be explicitly told the
target endianness, which may be different from the build host native
order. The provided example host
As discussed, a bundle is identified by a fixed header 32-bit signature. This signature is used to identify the binary as containing a bundle. At its simplest this signature is used to identify the platform/hardware that will accept the bundle (since the platform based applications will only recognise a valid matching signature value). The system support allows for a MASK/VALUE pair to be defined to allow (if required) a subset of the 32-bit signature to be used for “bundle is valid for this run-time” acceptance.
|2023-01-12||eCosPro Non-Commercial Public License|