- Table of Contents
The host-based command-line bundle tool is used to create bundle format images, as well as add and delete items, list and verify the contents, extract data, and other relevant commands.
Usage: bundle [option(s)] <bundlefilename> [cmds]
For a full list of the bundle tool's options and commands use the --help option:
$ bundle --help
The <bundlefilename> should always be supplied. The default behaviour if no operations are specified is to verify the <bundlefilename> and list its contents.
Explicit parameter options are case-insensitive. e.g. When providing
hash value either MD5
or md5 are acceptable and identical in their result.
The command-line bundle parameters are processed left to right, with parameters for operations following the command. The following examples are identical in the result produced:
$ bundle testbundle_minimum_md5.bin create hash md5
$ bundle testbundle_minimum_md5.bin hash md5 create
Both examples would create a bundle file testbundle_minimum_md5.bin that incorporates an md5 hash.
The following example creates a bundle called egbundle.bin. The bundle has a signature of 0x1 and includes bundle metadata from the manifest.txt. The entire bundle's contents will be covered by an sha256-based hash. The bundle would contain a single compressed item identified by a tag of 0x2. The item's data comes from short.bin and its metadata from itemarb.txt. The item's contents including the tag, metadata, and compressed data will be covered by an md5 hash. Note that as the item includes compressed data an additional md5 hash for the uncompressed data would also be incorporated.
$ bundle egbundle.bin create hash sha256 signature 0x01 arbitrary manifest.txt add 0x0002:short.bin:compress:md5:itemarb.txt
The bundle tool's
command is quite flexible in its usage.
It has a single parameter describing the item to be added,
with multiple fields separated by ':' characters. Only
required, with other optional fields specifying whether the source
file should be compressed, whether or not a hash should be added and
finally what metadata, if any, is to be included with the item.
tag value of 0x0000 is
reserved for the system, with all other tag values being available for
application use. This gives a maximum possible bundle item count
of 65635 items, which is unlikely to be a
limitation for embedded targets. Most bundles will contain a small
(<10) number of items, e.g. the main target
application, FPGA initialisation data, device initialisation tables,
add command examples:
Uncompressed, no hash
Compressed, no hash
Compressed, MD5 hash
Uncompressed, CRC-32 hash with arbitrary data
Compressed, no hash with arbitrary data
The --commands option allows for a fixed set of bundle operations to be held in a file, rather than being passed individually as command line options to the tool. Individual operations (e.g. command name and its required arguments) should NOT be split across lines, but multiple lines are allowed. Lines that start with '#' as the first non-whitespace character are treated as comments, and ignored.
Note: No item metadata add commands are included since we can use “extract” to get data and then “delete” and re-“add” with the required arbitrary file if required.
Filenames in commands cannot contain ':' since it is used as a field delimiter in the <item> description.
The bundle package includes the complete sources for the host tool. eCosPro releases include a pre-built version of the tool for either Linux or Windows as appropriate. If needed the tool can be built from the supplied source, with the only non-standard-library dependency being the “zlib” library. Linux systems will normally provide “zlib” as standard, though it is easily built if required for other host systems.