Internal Structure

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 188-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 188-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 188-3. <hash> chunk

Table 188-1. HASH signatures

HASH Signature Description
CYG_BUNDLE_HASH_NONE This is used when no data validation hash support is required. The <hash> object does not contain a “hash result”.
CYG_BUNDLE_HASH_CRC32 A standard 4-byte IEEE 802.3 (Ethernet) CRC-32 value.
CYG_BUNDLE_HASH_MD5 A 16-byte RFC 1321 MD5 Message-Digest Algorithm value is held. Though the use of MD5 is deprecated for cryptographic security purposes, its use as a <hash> for “data validity” checks is perfectly acceptable.
CYG_BUNDLE_HASH_SHA256 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 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 188-4. Uncompressed <item>

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

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

Note: 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.

Note: 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.

Note: 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.

Documentation license for this page: eCosPro License