From patchwork Mon Feb 17 14:50:25 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Antonin Godard X-Patchwork-Id: 57468 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 89996C021AB for ; Mon, 17 Feb 2025 14:50:40 +0000 (UTC) Received: from relay5-d.mail.gandi.net (relay5-d.mail.gandi.net [217.70.183.197]) by mx.groups.io with SMTP id smtpd.web10.53284.1739803836764961718 for ; Mon, 17 Feb 2025 06:50:37 -0800 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=LeoR+kfG; spf=pass (domain: bootlin.com, ip: 217.70.183.197, mailfrom: antonin.godard@bootlin.com) Received: by mail.gandi.net (Postfix) with ESMTPSA id 514FC44312; Mon, 17 Feb 2025 14:50:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1739803835; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=DpG3iFhTVowhVxpYPf5AKMKI/854ODe4Hb3sElrTQg4=; b=LeoR+kfGA2PWnLDS0XReI4E2ZEis9nSFO6q/Q/vw1EN8mjVjq5j5XS6MKwZFlu2hvl7X9Z 5Z4QKCW02w85A+7+sS5MtUUVMOLAI53qPbmtI0Zn+SpCxwPMDXxzu5NGHPvsbg4ZnyttDR 2hnNrh5juQPq+WS8n66zVHhs1g9z0u/dWnzEUy4g/uhHPBDtsVPy79YTVDVLAh8P2zsObG 2VXt4TNMBOMIMPo42yG7yqUvHO+HJhg4I84ZZrrLC/gW9dt8JjbXvW8Mg7sM3SMvqZ7zFx B7g91cagjdPlh1q3yGRb4kMc0lnoRaLySd3HQIZx7CoADaNZhiPGoAtK/xUYCA== From: Antonin Godard Date: Mon, 17 Feb 2025 15:50:25 +0100 Subject: [PATCH v3 6/6] dev-manual/multiconfig: add suggested best practices and baremetal sections MIME-Version: 1.0 Message-Id: <20250217-multiconfig-doc-v3-6-027a9fb282c3@bootlin.com> References: <20250217-multiconfig-doc-v3-0-027a9fb282c3@bootlin.com> In-Reply-To: <20250217-multiconfig-doc-v3-0-027a9fb282c3@bootlin.com> To: docs@lists.yoctoproject.org Cc: Thomas Petazzoni , Quentin Schulz X-Mailer: b4 0.14.2 X-Developer-Signature: v=1; a=openpgp-sha256; l=7690; i=antonin.godard@bootlin.com; h=from:subject:message-id; bh=b8ulFqEaS2FWYXCrbi+TE5GQBuFhWt0MDCYzrTn8mbM=; b=owEBbQKS/ZANAwAIAdGAQUApo6g2AcsmYgBns0y5BdG8AM8NePY8lGbA1FEWambS1/+BL0Rm0 Rw5wytdbuiJAjMEAAEIAB0WIQSGSHJRiN1AG7mg0//RgEFAKaOoNgUCZ7NMuQAKCRDRgEFAKaOo NvyCEACtN7Yc55AujicTXTgw20RCkMVVVSrSM18IHyy8yvmy0Pg1C0w0WZv89/7UxDCOqn99kcP yRBx5WTS12VCoUOCW2pMy0tmSCpQfxpiBAtPIZIcGZiaJZ3zj/sYC330IamP2DDduYT/MLs8uBs I7U5bBTnrgK6XVnWMm6Ksf0TIYp3JoPQzxm5itCsl1XVNjAnfaYizf/igVUErTuHgnUT/6i/nnR fd6bqfL70AfwQtUScCf/aGyXRqFVg0bpNiiXvjtU6qCleBSEX205U1yO6E0Tb+3GDBThLYo7iVx VesNQi1jgG5h1Fxq4e5+Hv+Yn6+gFyZp6OXyPGvbTBKua7bHOqeIFvgVuIUDwIwGigR6Q25juJk ca9FgmUw6u+rVcb7ulOnE+p9CiY3z/Erf5IvPpU58kbqST9nCJSyUU03KHD6hPEjjfrZeKgVYg8 TyfipeGnuIerEU5u3k2mZzuNEEWmAt/3GLNbd9uE6R88v3NOVVGP7/xCKPhvjsqGK9nuf/gqe8V xYxSWUKSec5p+/lcYgqnR4kDR0d5nbuLJl7Zg7iq2Tsrp7vP0XKFIpYw6eY7guYZPO2dRFSW1fy RG/a9PbLlHzWq5cMwvq/QRiurSTEB+STKyrzntSvRIVHET4lPY63ganlp7bbSXzlVSFFVAs+v7I s3s05wUk5rT61dA== X-Developer-Key: i=antonin.godard@bootlin.com; a=openpgp; fpr=8648725188DD401BB9A0D3FFD180414029A3A836 X-GND-State: clean X-GND-Score: -100 X-GND-Cause: gggruggvucftvghtrhhoucdtuddrgeefvddrtddtgdehkeeikecutefuodetggdotefrodftvfcurfhrohhfihhlvgemucfitefpfffkpdcuggftfghnshhusghstghrihgsvgenuceurghilhhouhhtmecufedtudenucesvcftvggtihhpihgvnhhtshculddquddttddmnecujfgurhephfffufggtgfgkfhfjgfvvefosehtjeertdertdejnecuhfhrohhmpeetnhhtohhnihhnucfiohgurghrugcuoegrnhhtohhnihhnrdhgohgurghrugessghoohhtlhhinhdrtghomheqnecuggftrfgrthhtvghrnhepuefhleelueehveefjeehgeeviedtieeljeeiudffhfeuveejtedvteeigfejteevnecuffhomhgrihhnpeihohgtthhophhrohhjvggtthdrohhrghdpshhouhhrtggvfigrrhgvrdhorhhgnecukfhppedvrgdtudemtggsudegmeehheeimeejrgdttdemjegthegtmeeirgguvgemjeelgeekmeegtdehleenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepihhnvghtpedvrgdtudemtggsudegmeehheeimeejrgdttdemjegthegtmeeirgguvgemjeelgeekmeegtdehledphhgvlhhopegluddvjedrtddruddrudgnpdhmrghilhhfrhhomheprghnthhonhhinhdrghhouggrrhgusegsohhothhlihhnrdgtohhmpdhnsggprhgtphhtthhopeefpdhrtghpthhtohepqhhuvghnthhinhdrshgthhhulhiisegthhgvrhhrhidruggvpdhrtghpthhtohepughotghssehlihhsthhsrdihohgtthhop hhrohhjvggtthdrohhrghdprhgtphhtthhopehthhhomhgrshdrphgvthgriiiiohhnihessghoohhtlhhinhdrtghomh X-GND-Sasl: antonin.godard@bootlin.com List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Mon, 17 Feb 2025 14:50:40 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/6400 After the suggestions from Mark Hatle on the list (https://lists.yoctoproject.org/g/docs/topic/110487932), add two sections to the multiconfig doc: - Suggested best practices: suggestion for better design of multiconfig builds. - Common use case: baremetal build. This section applies the guidelines from the first sections and apply it to a real-life example of how to use multiconfig. This one to build some baremetal firmware alongside a regular Linux build. Suggested-by: Mark Hatle Signed-off-by: Antonin Godard Reviewed-by: Quentin Schulz --- documentation/dev-manual/multiconfig.rst | 136 +++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) diff --git a/documentation/dev-manual/multiconfig.rst b/documentation/dev-manual/multiconfig.rst index 8371cf0e464bbd09f80a2ba0fbe700a911774fa9..71fe542efbbd074a737a7dc6db301de1ac087f20 100644 --- a/documentation/dev-manual/multiconfig.rst +++ b/documentation/dev-manual/multiconfig.rst @@ -174,3 +174,139 @@ and have separate configuration files, BitBake places the artifacts for each build in the respective temporary build directories (i.e. :term:`TMPDIR`). +Suggested best practices +======================== + +- :term:`TMPDIR` (other than the default set in bitbake.conf) is only set in + ``local.conf`` by the user. This means that we should **not** manipulate + :term:`TMPDIR` in any way within the Machine or Distro :term:`configuration + file`. + +- A multiconfig should specify a :term:`TMPDIR`, and should specify it by + appending the multiconfig name with :term:`BB_CURRENT_MC`. + +- Recipes that are used to transfer the output from a multiconfig build to + another should use ``do_task[mcdepends]`` to trigger the build of the + component, and then transfer the item to the current configuration in + :ref:`ref-tasks-install` and :ref:`ref-tasks-deploy`, assuming the value of + the deployed item based on :term:`TMPDIR`. + + The :ref:`ref-tasks-install` and :ref:`ref-tasks-deploy` tasks should look + like this:: + + do_install() { + install -m 0644 ${TMPDIR}-/tmp/deploy/images//somefile ${D}/some/path + } + + do_deploy() { + install -m 0644 ${TMPDIR}-/tmp/deploy/images//somefile ${DEPLOYDIR}/somefile + } + + In the example above: + + - ```` is the multiconfig name as set by the multiconfig + :term:`configuration file` (see the :ref:`dev-manual/multiconfig:Setting + Up and Running a Multiple Configuration Build` section above). + + - ```` must be the :term:`MACHINE` for which ``somefile`` was built + and deployed. This value may differ from the current :term:`MACHINE` if + the multiconfig :term:`configuration file` overrides it. + +- Firmware recipes can set the :term:`INHIBIT_DEFAULT_DEPS` variable to ``1`` + if they don't rely on default dependencies such as the standard C library. + +Common use case: building baremetal firmware alongside a Linux build +==================================================================== + +A common use case for multiconfig is to use the default configuration as the +regular Linux build, while one or more multiconfigs can be used to build special +components, such as baremetal firmware. It would also apply to a scenario where +a microcontroller, for example, is companion to a main processor where Linux is +running. This section details how one can achieve these kinds of scenarios with +a multiconfig build. + +Adding a multiconfig configuration file and recipe for a baremetal firmware +--------------------------------------------------------------------------- + +As described in :ref:`dev-manual/multiconfig:Setting Up and Running a Multiple +Configuration Build`, each multiconfig will require a separate +:term:`Configuration File`. In addition, we will define a separate +:term:`TMPDIR` for our baremetal firmware build configuration. + +For example, we will define a new ``conf/multiconfig/baremetal-firmware.conf`` +as follows:: + + TMPDIR .= "-${BB_CURRENT_MC}" + TCLIBC = "newlib" + +The ``baremetal-firmware.conf`` file configures a separate :term:`TMPDIR` for +holding binaries compiled with the `newlib `__ +toolchain (see :term:`TCLIBC`). + +.. note:: + + Here, the default :term:`MACHINE` is not overridden by the multiconfig + configuration file. As a consequence, the architecture of the built baremetal + binaries will be the same. In other cases, where the firmware runs on a + completely different architecture, the :term:`MACHINE` must be overridden. + +We then create a recipe ``my-firmware.bb`` that defines how the baremetal +firmware is built. The recipe should contain enough information for the +:term:`OpenEmbedded build system` to properly compile the firmware with our +toolchain. The building tasks may vary depending on the nature of the firmware. +However, the recipe should define a :ref:`ref-classes-deploy` task that deploys +the output into the :term:`DEPLOYDIR` directory. We will consider in the +following that the file is named ``my-firmware.elf``. + +Building the firmware +--------------------- + +The firmware can be built with BitBake with the following command:: + + $ bitbake mc:baremetal-firmware:my-firmware + +However, we would prefer for ``my-firmware`` to be automatically built when +triggering a normal Linux build. + +Using a ``mcdepend``, a recipe belonging to the Linux build can trigger the +build of ``my-firmware``. For example, let's consider that our Linux build needs +to assemble a "special" firmware that uses the output of our ``my-firmware`` +recipe - let's call it ``my-parent-firmware.bb``. Then, we should specify this +dependency in ``my-parent-firmware.bb`` with:: + + do_compile[mcdepends] = "mc::baremetal-firmware:my-firmware:do_deploy" + +The above will ensure that when the :ref:`ref-tasks-compile` task of +``my-parent-firmware`` is triggered, the :ref:`ref-tasks-deploy` task of +``my-firmware`` will already have run successfully. + +Using the output of ``my-firmware`` +----------------------------------- + +After ``my-firmware`` recipe has deployed ``my-firmware.elf``, we need to use +the output in some way. We can make a series of assumptions, based on the +default Yocto Project variables in order to get the binary for packaging. + +First, we can set the following in ``my-parent-firmware.bb``:: + + FIRMWARE_FILE ??= "${TMPDIR}-baremetal-firmware/deploy/images//my-firmware.elf" + FIRMWARE_FILE[vardepsexclude] += "TMPDIR" + +The first assignment stores the value of the path to the firmware built and +deployed by the ``my-firmware.bb`` recipe. The second assignment excludes the +:term:`TMPDIR` variable from being part of ``FIRMWARE_FILE``'s dependencies --- +meaning that changing the value of :term:`TMPDIR` (for example, changing the +host on which the firmware is built) will not invalidate the :ref:`shared state +cache `. + +Additionally, ```` should be replaced by the :term:`MACHINE` for which +we are building in the baremetal-firmware context. + +We can then add a :ref:`ref-tasks-install` task to ``my-parent-firmware``:: + + do_install() { + install -Dm 0644 ${FIRMWARE_FILE} ${D}/lib/firmware/my-firmware.elf + } + +Doing the above will allow the firmware binary to be transferred and packaged +into the Linux context and rootfs.