Add support for metadata in barebox images

It's often useful to get some information about a barebox image
before starting or flashing it. This patch introduces barebox
Image MetaData (IMD). When enabled a barebox image will contain
a list of tags containing the desired information. We have tags
for:

- the barebox release (2014.07.0-00160-g035de50-dirty)
- the build timestamp (#741 Mon Jul 28 15:08:54 CEST 2014)
- the board model the image is intended for
- the device tree toplevel compatible property

Also there is an additional generic key-value store which stores
parameters for which no dedicated tag exists. In this patch it
is used for the memory size an image supports.

Since there is no fixed offset in a barebox image which can be
used for storing the information, the metadata is stored somewhere
in the image and found by iterating over the image. This works
for most image types, but obviously not for SoC images which are
encoded or encrypted in some way.

There is a 'imd' tool compiled from the same sources for barebox,
for the compile host and for the target, so the metadata information
is available whereever needed.

For device tree boards the model and of_compatible tags are automatically
generated.

Example output of the imd tool for a Phytec phyFLEX image:

build: #889 Wed Jul 30 16:08:54 CEST 2014
release: 2014.07.0-00167-g6b2070d-dirty
parameter: memsize=1024
of_compatible: phytec,imx6x-pbab01 phytec,imx6dl-pfla02 fsl,imx6dl
model: Phytec phyFLEX-i.MX6 Duallite Carrier-Board

Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>

3 files changed, 58 insertions, 0 deletions

diff --git a/Documentation/user/imd.rst b/Documentation/user/imd.rst
new file mode 100644
index 0000000000..e0251d644e
--- /dev/null
+++ b/Documentation/user/imd.rst
@@ -0,0 +1,54 @@
+
+.. _imd:
+
+Image MetaData (IMD)
+====================
+
+barebox images can be enriched with metadata. This is useful to get information
+the board an image is compiled for and which barebox version an image contains.
+
+There are predefined tags for:
+
+- The build timestamp
+- The barebox release version
+- The model (board) the image is compiled for
+- The toplevel device tree compatible properties the image can handle
+
+Additionally there is a generic key/value tag to add information which does not
+fit into the above categories, for example the memory size for boards which come
+with different memory sizes which can't be automatically detected.
+
+The informations can be extracted with the ``bareboximd`` tool which lives under
+``scripts/`` in the barebox sourcecode. If enabled it is compiled for the compile
+host and also for the target architecture. barebox itself has the :ref:`command_imd`
+command to extract the informations. Here is an example output of the tool called
+without additional options::
+
+  # imd barebox-phytec-pbab01dl-1gib.img
+  build: #890 Wed Jul 30 16:15:24 CEST 2014
+  release: 2014.07.0-00167-ge6632a9-dirty
+  parameter: memsize=1024
+  of_compatible: phytec,imx6x-pbab01 phytec,imx6dl-pfla02 fsl,imx6dl
+  model: Phytec phyFLEX-i.MX6 Duallite Carrier-Board
+
+Single informations can be extracted with the ``-t <type>`` option::
+
+  # imd barebox-phytec-pbab01dl-1gib.img -t release
+  2014.07.0-00167-ge6632a9-dirty
+
+Since the barebox hush does not have output redirection the barebox too has the
+``-s <var>`` option to assign the output to a variable for later evaluation.
+
+Limitations
+-----------
+
+The IMD tags are generated in the barebox binary before a SoC specific image is
+generated. Some SoCs encrypt or otherwise manipulate the images in a way that the
+IMD information is lost. The IMD mechanism does not work on these SoCs. A known
+example is the Freescale i.MX28.
+
+IMD and barebox_update
+----------------------
+
+The IMD informations could well be used to check if an image is suitable for updating
+barebox for a particular board. Support for such a check is planned but not yet implemented.
diff --git a/Documentation/user/updating.rst b/Documentation/user/updating.rst
index 2a963b6200..6a1a73348c 100644
--- a/Documentation/user/updating.rst
+++ b/Documentation/user/updating.rst
@@ -27,3 +27,6 @@ barebox has been started from is registered as default (marked with a ``*``)::
 available for your board. It is recommended to implement it, but you can also
 update barebox manually using :ref:`command_erase` and :ref:`command_cp`
 commands. The exact commands are board specific.
+
+**NOTE** barebox images can be enriched with metadata which can be used to check
+if a given image is suitable for updating barebox, see :ref:`imd`.
diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
index 0eac0aadc7..3d68bbb9ae 100644
--- a/Documentation/user/user-manual.rst
+++ b/Documentation/user/user-manual.rst
@@ -19,6 +19,7 @@ Contents:
    hush
    defaultenv-2
    updating
+   imd
    devicetree
    pbl
    multi-image