doc: add daily work section about creating new images

Signed-off-by: Michael Olbrich <m.olbrich@pengutronix.de>

4 files changed, 103 insertions, 0 deletions

diff --git a/doc/daily_work_section.rst b/doc/daily_work_section.rst
index 0e4e6e767..42a61e3c4 100644
--- a/doc/daily_work_section.rst
+++ b/doc/daily_work_section.rst
@@ -3,5 +3,6 @@ Various Aspects of Daily Work
 
 .. include:: daily_work.inc
 .. include:: nfsroot.inc
+.. include:: multi_image_platforms.inc
 .. include:: working_with_git_sources.inc
 .. include:: including_bsp_doc.inc
diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst
index 92106fd28..811fad59d 100644
--- a/doc/dev_manual.rst
+++ b/doc/dev_manual.rst
@@ -123,6 +123,8 @@ the local ``./projectroot/etc/fstab``, modify it and we are done. The
 next time PTXdist builds the root filesystem it will use the local
 ``fstab`` instead of the global (default) one.
 
+.. _adding_new_packages:
+
 Adding new Packages
 -------------------
 
diff --git a/doc/multi_image_platforms.inc b/doc/multi_image_platforms.inc
new file mode 100644
index 000000000..951c10779
--- /dev/null
+++ b/doc/multi_image_platforms.inc
@@ -0,0 +1,98 @@
+.. _multi_image_platform:
+
+Supporting Multiple Device Variants in one Platform
+---------------------------------------------------
+
+Many projects have to deal with more than just one hardware and software
+configuration. There may be multiple hardware generations or variants with
+different hardware and software features.
+
+To simplify maintenance, it can be desirable to handle all variants in one
+PTXdist platform. This can be achieved by creating new image rules for each
+supported variant.
+
+Providing a Bootloader for each Variant
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+What needs to be done here depends on the hardware and which bootloader is
+used. For example, for **barebox** on i.MX6, images for all variants can be
+generate from one build tree. In this case the default **barebox** packages
+is sufficient.
+
+If different builds are needed, then a new bootloader package for each
+variant can be created. For **barebox** PTXdist provides a template to
+simplify this. For other bootloaders more work is needed to create the
+package rules manually. See :ref:`adding_new_packages` for more details one
+how to create a new package.
+
+.. note:: PTXdist looks in ``patches/$(<PKG>)`` for the patches. Symlinks
+  can be uses to share the patch stack across multiple bootloader packages.
+
+Creating Individual Root-Filesystems for each Variant
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For each variant, a rootfs image can be created.  The ``image-genimage``
+template for new packages can be used to create these images. See
+:ref:`image_packages` for more details.
+
+In this case, the important part is the ``<PKG>_PKGS`` variable.
+
+There are two ways to mange the package list for the image:
+
+1. Creating the package list manually
+
+   Manually create the package list by listing package names or using **make**
+   macros to manipulate the default package list ``$(PTX_PACKAGES_INSTALL)``.
+
+   To add a single custom package, lazy packages can be uses. A lazy package
+   is not added to ``$(PTX_PACKAGES_INSTALL)``. It is created by modifying the
+   package rule like this:
+
+   .. code-block:: make
+
+     LAZY_PACKAGES-$(PTXCONF_BOARD_A_EXTRA) += board-a-extra
+
+   The resulting package is then added explicitly to on image:
+
+   .. code-block:: make
+
+     IMAGE_ROOT_BOARD_A_PKGS := $(PTX_PACKAGES_INSTALL) board-a-extra
+
+   This is not recommended for larger changes to the packages list. Is is easy
+   to break dependencies this way.
+
+2. Use a collection config to create the package list
+
+   To prepare for this, all packages that are not part of _all_ variants
+   must be set 'M' in menuconfig.
+
+   Then a new collection for the variant is created:
+
+   .. code-block:: text
+
+     $ touch configs/collectionconfig-board-a
+     $ ptxdist ----collectionconfig=configs/collectionconfig-board-a menuconfig collection
+
+   All extra packages for this variant are selected here. Then the
+   collection config is configured for the image:
+
+   .. code-block:: make
+
+     IMAGE_ROOT_BOARD_A_PKGS := $(call ptx/collection, $(PTXDIST_WORKSPACE)/configs/collectionconfig-board-a)
+
+   With a collection PTXdist will take care of all dependencies. This makes
+   it easy to manage multiple root filesystems with significantly different
+   package lists.
+
+Putting it all Together
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The final steps are highly hardware dependent. In some cases a bootloader
+image and a rootfs are all that is needed.
+
+To boot from SD-Card a disk image including bootloader, partition table and
+rootfs is needed. The ``image-genimage`` template can be uses again to
+create such an image for each variant.
+
+.. note:: The genimage config files in ``config/images/`` are good examles
+   when writing genimage for the new images.
diff --git a/doc/ref_manual.rst b/doc/ref_manual.rst
index a316635ed..63b0a9ccf 100644
--- a/doc/ref_manual.rst
+++ b/doc/ref_manual.rst
@@ -354,6 +354,8 @@ Targetinstall Stage
 
 TBD
 
+.. _image_packages:
+
 Image Packages
 ^^^^^^^^^^^^^^