Chapter 196. Bundle overview

196.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.

196.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

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.