Chapter 214. Host tool
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
$ bundle --help
The <bundlefilename> should always be supplied. The default
behaviour if no operations are specified is
verify the <bundlefilename>
list its contents.
Explicit parameter options are case-insensitive. e.g. When providing
hash value either
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
incorporates an md5 hash.
The following example creates a bundle called
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
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
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
reserved for the system, with all other tag values being available for
application use. This gives a maximum possible bundle item count
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
--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.
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.
|2023-08-15||eCosPro Non-Commercial Public License|