From patchwork Sun Jan 19 22:10:05 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Enrico_J=C3=B6rns?= X-Patchwork-Id: 55787 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 25133C02187 for ; Sun, 19 Jan 2025 22:10:38 +0000 (UTC) Received: from metis.whiteo.stw.pengutronix.de (metis.whiteo.stw.pengutronix.de [185.203.201.7]) by mx.groups.io with SMTP id smtpd.web11.24833.1737324628158439543 for ; Sun, 19 Jan 2025 14:10:28 -0800 Authentication-Results: mx.groups.io; dkim=none (message not signed); spf=pass (domain: pengutronix.de, ip: 185.203.201.7, mailfrom: ejo@pengutronix.de) Received: from drehscheibe.grey.stw.pengutronix.de ([2a0a:edc0:0:c01:1d::a2]) by metis.whiteo.stw.pengutronix.de with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1tZdUv-0000vO-Ui; Sun, 19 Jan 2025 23:10:25 +0100 Received: from ptz.office.stw.pengutronix.de ([2a0a:edc0:0:900:1d::77]) by drehscheibe.grey.stw.pengutronix.de with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.96) (envelope-from ) id 1tZdUu-000phP-2i; Sun, 19 Jan 2025 23:10:24 +0100 Received: from ejo by ptz.office.stw.pengutronix.de with local (Exim 4.96) (envelope-from ) id 1tZdUu-006elp-2S; Sun, 19 Jan 2025 23:10:24 +0100 From: =?utf-8?q?Enrico_J=C3=B6rns?= To: docs@lists.yoctoproject.org Cc: yocto@pengutronix.de Subject: [PATCH v3] ref-manual: add documentation for the barebox class Date: Sun, 19 Jan 2025 23:10:05 +0100 Message-Id: <20250119221005.1586540-1-ejo@pengutronix.de> X-Mailer: git-send-email 2.39.5 MIME-Version: 1.0 X-SA-Exim-Connect-IP: 2a0a:edc0:0:c01:1d::a2 X-SA-Exim-Mail-From: ejo@pengutronix.de X-SA-Exim-Scanned: No (on metis.whiteo.stw.pengutronix.de); SAEximRunCond expanded to false X-PTX-Original-Recipient: docs@lists.yoctoproject.org 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 ; Sun, 19 Jan 2025 22:10:38 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/6145 This adds the initial documentation for the newly added barebox.bbclass to the Reference Manual's class list. It also adds the two most notable variables to the variable list. Signed-off-by: Enrico Jörns Reviewed-by: Antonin Godard --- v2 -> v3: - use three spaces for code block indentation - start barebox class variable descriptions with "When using the :ref:`ref-classes-barebox` class, .." and adapt paragraphs accordingly. documentation/ref-manual/classes.rst | 37 ++++++++++++++++++++++++++ documentation/ref-manual/variables.rst | 29 ++++++++++++++++++++ 2 files changed, 66 insertions(+) diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index 22c4301a4..8ad77319e 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst @@ -128,6 +128,43 @@ It's useful to have some idea of how the tasks defined by the - :ref:`ref-tasks-install` --- runs ``make install`` and passes in ``${``\ :term:`D`\ ``}`` as ``DESTDIR``. +.. _ref-classes-barebox: + +``barebox`` +=========== + +The :ref:`ref-classes-barebox` class manages building the barebox bootloader. + +If a file named ``defconfig`` is included in the :term:`SRC_URI`, it will be +copied to ``.config`` in the build directory and used as the barebox +configuration. +Instead of providing a ``defconfig`` file, you can set :term:`BAREBOX_CONFIG` +to a defconfig provided by the barebox source tree. +If neither ``defconfig`` nor :term:`BAREBOX_CONFIG` is specified, the class +will raise an error. + +The :ref:`ref-classes-barebox` class supports config fragments and internally +includes the :ref:`ref-classes-cml1` class to provide `Kconfig +`__ support for +barebox, enabling tasks such as :ref:`ref-tasks-menuconfig` and +:ref:`ref-tasks-diffconfig`. + +The generated barebox binaries are deployed to +:term:`DEPLOY_DIR_IMAGE` as well as installed to ``BAREBOX_INSTALL_PATH`` +(``/boot`` by default) making them part of the recipe’s base package. +This setup supports both using the barebox binaries as independent artifacts +and installing them into a rootfs. +:term:`BAREBOX_BINARY` can be used to select a distinct binary to deploy and +install. +If ``barebox`` is set as the :term:`EFI_PROVIDER`, the class will leverage +:oe_git:`conf/image-uefi.conf ` +to define the default installation paths and naming conventions. + +The compiled-in barebox environment can be extended by adding environment files +to the ``BAREBOX_ENV_DIR``. +The ``BAREBOX_FIRMWARE_DIR`` variable allows you to specify the firmware blob +search directory, enabling loading of additional firmware like TF-A or OP-TEE. + .. _ref-classes-base: ``base`` diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index 702a6caf8..8b996f216 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -293,6 +293,35 @@ system and gives an overview of their function and contents. :term:`PACKAGE_EXCLUDE` variables for related information. + :term:`BAREBOX_BINARY` + When using the :ref:`ref-classes-barebox` class, this variable allows you + to specify a particular binary that should be deployed and installed. + + The barebox build system can build multiple barebox binaries at once. + By default, all built binaries will be deployed and installed under their + original name. + + Here is an example usage of this variable:: + + BAREBOX_BINARY = "barebox-boundarydevices-imx6dl-nitrogen6x-1g.img" + + :term:`BAREBOX_CONFIG` + When using the :ref:`ref-classes-barebox` class, this variable allows you + to specify the name of the barebox defconfig to build. + The name must be a defconfig file known to the barebox build environment. + This variable is mainly useful for generic use cases where a dedicated + configuration is not required. + The :ref:`ref-classes-barebox` class itself already sets it for some QEMU + machines:: + + BAREBOX_CONFIG:qemuarm = "multi_v7_defconfig" + BAREBOX_CONFIG:qemuarm64 = "multi_v8_defconfig" + BAREBOX_CONFIG:qemux86-64 = "efi_defconfig" + + Except for these, the default value of :term:`BAREBOX_CONFIG` is empty. + For more information on how to provide a barebox configuration, see the + :ref:`ref-classes-barebox` class. + :term:`BASE_LIB` The library directory name for the CPU or Application Binary Interface (ABI) tune. The :term:`BASE_LIB` applies only in the Multilib