From 494fb1867b2a16348f3ddde0058b4db29b492a9c Mon Sep 17 00:00:00 2001 From: Michael Olbrich Date: Fri, 15 Jun 2018 19:31:36 +0200 Subject: doc: add daily work section about creating new images Signed-off-by: Michael Olbrich --- doc/multi_image_platforms.inc | 98 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 doc/multi_image_platforms.inc (limited to 'doc/multi_image_platforms.inc') 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/$()`` 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 ``_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. -- cgit v1.2.3