Chapter 211. Bundle overview

211.1. Introduction

The CYGPKG_BUNDLE package implements support for a simple, compact, multi-element, binary distribution format, referred to as a “bundle”. The bundle format is primarily designed to be used for in-field system updates in conjunction with the BootUp lightweight BootROM package.

The format can be easily parsed and processed by deeply embedded systems, and is used to encapsulate multiple discrete binary data blobs and optional metadata. Bundles can therefore incorporate all the elements that may be required for a system update, including application executables, FPGA bitfiles, DSP firmware, application data and so forth.

The bundle package implements an API to parse and extract data from a bundle and an associated host tool used to create and manage bundle images.

The STM324X9i-Eval platform includes an example implementation of the BootUp bootROM package that uses the bundle package format as the distribution format underpinning its system update mechanism.

A bundle is normally expected to be used as a matched collection of binaries, and is treated as a whole with regards to production and in-field updates. It is NOT expected that in-field operations will ever split and re-combine elements of a deployment package in the field. As such the format is read-only for eCos applications.

Although the bundle format is designed to be flexible and allow modification and extensions, it is vital that for a given target platform that the host-based creation tool and runtime code share a common format and set of expected features. For example the use of MD5 as a “hash” and zlib as a compressor.

211.2. Configuration

This section shows how to include the bundle support into an eCos configuration, and how to configure it once installed.

The bundle support is contained in a single eCos package CYGPKG_BUNDLE. However, it depends on the services of a collection of other packages for complete functionality.

Incorporating the bundle support into your application is straightforward. The essential starting point is to incorporate the bundle eCos package (CYGPKG_BUNDLE) into your configuration.

This may be achieved directly using ecosconfig add on the command line, or the Build->Packages… menu item within the eCos Configuration Tool.

CYGFUN_BUNDLE_COMPRESS
If the eCos zlib package CYGPKG_COMPRESS_ZLIB is configured then, when enabled, this option provides support for decompressing items. If the CYGPKG_COMPRESS_ZLIB package is not available, or this option is disabled, then only uncompressed items within a bundle can be read.
CYGIMP_BUNDLE_HASH_MD5
This option can be enabled to include support for the RFC 1321 MD5 Message-Digest Algorithm as a valid hash used to verify data integrity.
CYGIMP_BUNDLE_HASH_SHA256
This option can be enabled to include support for the FIPS PUB 180-2 SHA-256 hash as a valid hash used to verify data integrity.
CYGIMP_BUNDLE_HASH_CRC32
This option when enabled implements support for the standard IEEE 802.3 (Ethernet) CRC-32 as a valid hash used to verify data integrity.
CYGNUM_BUNDLE_BUFSIZE
This option defines the size of the internal buffer used for decompressing data. Currently it makes use of a dynamic memory allocation and so may need to be tuned appropriately for target systems with a small dynamic heap.
CYGBLD_BUNDLE_BUNDLE

This option allows the host-side bundle tool to be automatically built on suitably capable systems.

[Note]Note

This option is disabled by default, since normally only a Linux system with a standard zlib library installation would automatically succeed. The package supplied host/Makefile provides an example of cross-building (under Linux) the host tool for Windows.

CYGDBG_BUNDLE_DEBUG
If this option is enabled then it provides access to individually controlled CDL debug options for various sub-systems or package features. This allows the detail and amount of debug information to be controlled. Normally such diagnostic output would only need to be enabled for developers working on the internals of the bundle processing.
CYGTST_BUNDLE_BUILD_TESTS
This option enables the building of any bundle run-time verification tests included in the package.