A “bundle” file has a custom format, designed to minimise the code overhead of supporting the bundle on the target platform.

Note

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.

A bundle is a contiguous binary image containing a set of uniquely tagged items. Individual items may be compressed (using the standard 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> terminator 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> block.

Figure 216.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:

Version=1.02_B02;Required-HW-Version=rev1b;Development;

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 216.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 special 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 216.3. <hash> chunk

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 mappings: 0x0001==HostMCU, 0x0401==MotorDSP, 0x0812==LineDSP, 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 216.4. Uncompressed <item>

For compressed items a seperate <hash> object is maintained provided the hash value for the original, uncompressed, source data.

Figure 216.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.

	Note
	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 bundle application provides the --little-endian and --big-endian options which can be used to override the host default selection if needed.

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.

Notes

The “customer specific” field (currently 8-bits) can be used to provide a mechanism to restrict <bundle> images to specific platforms (or revisions of a platform) as required. The bundle host executable provided within your eCosPro installation is required to construct, and examine, “bundle” binaries. This executable must be on your path, and will normally be copied into eCosPro host tools bin directory. Under Windows this is typically C:\eCosPro\ecoshosttools\bin and on Linux hosts /opt/ecospro/ecoshosttools/bin. The above bin directory will be on your path if you use the eCos GUI configuration tool or the eCos CLI Shell environment. The bundle <header> and item <header> descriptors contain a flags field that can be extended as required to have any extension settings as needed to add extra information blocks into a bundle or item respectively. This allows for future extensions to the format to be added without affecting software (e.g. the BootUp firmware or the BootUp loaded main application) already in the field, since they will not interpret or be affected by any extra data that may be provided.