From 618188fac879a6bfc36586b96e778c157dc40158 Mon Sep 17 00:00:00 2001 From: Katrina Prosise Date: Tue, 5 Dec 2023 08:08:28 -0500 Subject: [PATCH] Cleanup reference manual lmp section `reference-manual/linux` pages were checked and edited for grammar, spelling, and style. Pages which were a better fit for the user-guide were relocated under lmP Customization; an index page for that section was also added. Cleanup and possible relocation of linux-updating was skipped to avoid merge conflicts. Redirects added for moved pages. QA steps: checked rendered html. Ran linter within editor. Ran linkcheck. No issues to report, however this is a relatively large commit. This commit addresses FFTK 2791 This commit addresses FFTK 1887 This commit addresses FFTK 1741 This commit addresses FFTK 1681 This commit applies to FFTK 1687 This commit applies to FFTK 2730 This commit applies to FFTK 2732 This commit applies to FFTK 2731 This commit applies to FFTK 1702 This commit applies to FFTK 988 This commit applies to FFTK 2733 Signed-off-by: Katrina Prosise --- source/conf.py | 2 + source/index.rst | 2 +- .../reference-manual/linux/building-sdk.rst | 55 ++-- .../linux/development-tags.rst | 27 +- .../linux/factory-device-reset.rst | 24 +- .../reference-manual/linux/linux-building.rst | 238 ------------------ .../linux/linux-dev-container.rst | 18 +- .../reference-manual/linux/linux-dev-mode.rst | 15 +- .../linux/linux-disk-encryption.rst | 82 +++--- .../reference-manual/linux/linux-distro.rst | 43 ++-- .../reference-manual/linux/linux-kernel.rst | 138 +++++----- .../reference-manual/linux/linux-layers.rst | 66 ++--- .../reference-manual/linux/linux-lmp-fs.rst | 40 +-- .../linux/linux-net-debug.rst | 51 ++-- .../linux/linux-oss-compliance.rst | 155 +++++------- .../linux/linux-persistent-log.rst | 63 ++--- source/reference-manual/linux/linux-repo.rst | 30 +-- .../linux/linux-supported.rst | 20 +- .../linux/linux-wic-installer.rst | 50 ++-- source/reference-manual/linux/linux.rst | 28 +-- source/reference-manual/linux/toolchain.rst | 55 ++-- source/user-guide/lmp-customization/index.rst | 16 ++ .../lmp-customization/linux-building.rst | 189 ++++++++++++++ .../lmp-customization}/linux-extending.rst | 77 +++--- .../lmp-customization/lmp-customization.rst | 2 +- 25 files changed, 643 insertions(+), 843 deletions(-) delete mode 100644 source/reference-manual/linux/linux-building.rst create mode 100644 source/user-guide/lmp-customization/index.rst create mode 100644 source/user-guide/lmp-customization/linux-building.rst rename source/{reference-manual/linux => user-guide/lmp-customization}/linux-extending.rst (73%) diff --git a/source/conf.py b/source/conf.py index f43381f41..0b7725386 100644 --- a/source/conf.py +++ b/source/conf.py @@ -415,6 +415,8 @@ "community-factory/create-factory": "../getting-started/signup/index.html", "community-factory/": "index.html", "getting-started/git-config/index": "../install-fioctl/index.html#configuring-git", + "reference-manual/linux/linux-building": "../../user-guide/lmp-customization/linux-building.html", + "reference-manual/linux/linux-extending": "../../user-guide/lmp-customization/linux-extending.html", } # Make external links open in a new tab. diff --git a/source/index.rst b/source/index.rst index b81efd08f..103e1d88b 100644 --- a/source/index.rst +++ b/source/index.rst @@ -40,7 +40,7 @@ OE/Yocto Project, the Linux microPlatform™ and Docker®. user-guide/account-management/account-management user-guide/containers-and-docker/index user-guide/custom-ci/custom-ci - user-guide/lmp-customization/lmp-customization + user-guide/lmp-customization/index user-guide/lmp-auto-hostname/lmp-auto-hostname user-guide/lmp-device-auto-register/lmp-device-auto-register user-guide/foundriesio-rest-api/foundriesio-rest-api diff --git a/source/reference-manual/linux/building-sdk.rst b/source/reference-manual/linux/building-sdk.rst index 7c58c5733..f756564ed 100644 --- a/source/reference-manual/linux/building-sdk.rst +++ b/source/reference-manual/linux/building-sdk.rst @@ -1,7 +1,7 @@ .. _ref-building-sdk: -Building SDK -============ +Building The Yocto Project Standard SDK +======================================= The Yocto Project Standard SDK is a development environment composed by: @@ -11,36 +11,25 @@ The Yocto Project Standard SDK is a development environment composed by: The SDK is used to replicate the tools and files from the target image, but without depending on BitBake. -For details on what the SDK is -and a complete description of how to work with it, -visit -`Yocto Project Application Development and the Extensible Software Development Kit `_. - -The LmP can be configured to -create an SDK install script of the same rootfs image -built by the CI. -The SDK install script is created by -``bitbake -c populate_sdk``. - -When the ``lmp:params:BUILD_SDK`` is set -and a new target is created, +For details on what the SDK is, and a complete description of how to work with it, +visit `Yocto Project Application Development and the Extensible Software Development Kit `_. + +The LmP can be configured to create an SDK install script of the same rootfs image built by the CI. +The SDK install script is created by ``bitbake -c populate_sdk``. + +When the ``lmp:params:BUILD_SDK`` is set and a new target is created, the SDK install script is also built. -This configuration increases the build time, -so enable the variable -only when a new SDK install script is needed. +This configuration increases the build time, so enable it only when a new SDK install script is needed. -Change the file -``ci-scripts/factory-config.yml`` -to include the variable ``BUILD_SDK: "1"`` -whenever a new SDK install script is needed, -as the following example. +Change ``ci-scripts/factory-config.yml`` to include the variable ``BUILD_SDK: "1"``. +Do this whenever a new SDK install script is needed: .. prompt:: text - lmp: - params: - BUILD_SDK: "1" + lmp: + params: + BUILD_SDK: "1" The SDK image is available under the ``SDK`` folder. @@ -52,8 +41,7 @@ The SDK image is available under the ``SDK`` folder. Installation ------------ -After downloading the SDK install script, -you can install it in any folder. +After downloading the SDK install script, you can install it in any folder. In this example, we use ``/usr/local/cortexa53-crypto``. .. prompt:: text @@ -68,7 +56,7 @@ In this example, we use ``/usr/local/cortexa53-crypto``. SDK has been successfully set up and is ready to be used. Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. -After the installation, the resultant folder has the ``sysroots`` for the host and target architecture. +After installation, the resultant folder has the ``sysroots`` for the host and target architecture. It also contains the script used to setup the environment to work with the SDK: .. prompt:: text @@ -97,12 +85,11 @@ source the script as in the following instructions: $ file helloworld helloworld: ELF 64-bit LSB pie executable, ARM aarch64, version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-aarch64.so.1, BuildID[sha1]=80e241327bd3412b91c2035cbacb73e87797e0b5, for GNU/Linux 3.14.0, with debug_info, not stripped -With the exported environment variable, -it is possible to build using the toolchain +With the exported environment variable, it is possible to build using the toolchain and, when needed, to use the header or other files from the ``sysroots``. -In the example, we see that the generated file can not be executed on the host machine. -Using ``file``, we learn this is because the binary is for ``ARM aarch64`` architecture. +In the example, we saw that the generated file can not be executed on the host machine. +Using ``file``, we learned that this is because the binary is for ``ARM aarch64`` architecture. -For more information regarding Standard SDK, follow the Yocto Project +For more information regarding the Standard SDK, follow the Yocto Project `instructions `_. diff --git a/source/reference-manual/linux/development-tags.rst b/source/reference-manual/linux/development-tags.rst index 7f97ed851..112ef558f 100644 --- a/source/reference-manual/linux/development-tags.rst +++ b/source/reference-manual/linux/development-tags.rst @@ -1,31 +1,34 @@ .. _ref-development-tags: -Understanding Development FIO Tags +Understanding FIO Development Tags ================================== -When Foundries.io adds a patch to a repository with an upstream, we add an ``FIO`` -tag in the Git shortlog to make the commit easy to see. For example, in -Foundries.io U-Boot tree:: +When Foundries.io™ adds a patch to a repository with an upstream, we add a ``FIO`` tag in the Git shortlog. +This makes the commit easier to see. +For example, in our U-Boot tree:: [FIO internal] common: foundries.io verified boot utility -The most common used tags through the Foundries.io repositories are: +The most common tags used throughout the repositories are: * ``[FIO fromtree]``: patches cherry-picked, rather than merged, from upstream (mainline) * ``[FIO fromlist]``: patches submitted to upstream for review (in mailing lists, pending PRs etc.), and revisions to them * ``[FIO toup]``: patches that want to go upstream -* ``[FIO temphack]`` or ``[FIO hack]``: temporary patches that keep things working for now but need a better solution later for upstreaming -* ``[FIO extras]``: patches pulled in for specific functionality that are useful for subscribers, but not critical +* ``[FIO temphack]`` or ``[FIO hack]``: temporary patches that keep things working for now, but need a better solution later for upstreaming +* ``[FIO extras]``: non-critical patches pulled in for extra, potentially useful functionality * ``[FIO internal]``: patches needed by the LmP, not intended for upstream use -* ``[FIO squash]``: patch should be squashed with an original patch, fixing possible issues in that patch. This tag requires a commit message tag "Fixes:" filled out properly +* ``[FIO squash]``: patch should be squashed with an original patch, fixing possible issues in that patch. + This tag requires a commit message tag ``Fixes:`` to be filled out properly There are also exceptional tags for patches that were cherry-picked/sent from/to SoC vendor forks: * ``[FIO from]``: patches cherry-picked from ```` forked tree, for example ``[FIO fromnxp]`` * ``[FIO to]``: patches, that want to go to SoC vendor forked tree, for example ``[FIO tostm]`` -* ``[FIO to-altered]``: exceptional case, when not a whole patch was cherry-picked, but rather some parts or it was completely reimplemented. In this case ``-altered`` is added, for example ``[FIO fromnxp-altered]`` +* ``[FIO to-altered]``: exceptional case, when not a whole patch was cherry-picked, but rather some parts or it was completely reimplemented. + In this case ``-altered`` is added, for example ``[FIO fromnxp-altered]`` -.. important:: When a patch is cherry-picked, the Git cherry-pick command should be invoked with ``-x`` (append commit name) parameter, so - the original commit hash is added to the new commit message (for example ``(cherry-picked from commit 1e24c2671acdbcf81207c43da39e09846f404dc3)``). - With a hash, tracking the original commit in a mainline/SoC vendor tree is much easier. +.. important:: When a patch is cherry-picked, the Git cherry-pick command should be invoked with ``-x`` (append commit name) parameter. + This is so that the original commit hash is added to the new commit message. + For example, ``cherry-picked from commit 1e24c2671acdbcf81207c43da39e09846f404dc3``. + With a hash, tracking the original commit in a mainline/SoC vendor tree is easier. diff --git a/source/reference-manual/linux/factory-device-reset.rst b/source/reference-manual/linux/factory-device-reset.rst index 08f806998..e4d8883b2 100644 --- a/source/reference-manual/linux/factory-device-reset.rst +++ b/source/reference-manual/linux/factory-device-reset.rst @@ -3,10 +3,10 @@ Factory Reset ============= -In this context, factory reset means restoring the device to the original state. -This is a feature of LmP rather than FoundriesFactory. -Reset is performed as a script in ramdisk during boot. -It is triggered by presence of specific files. +In this context, Factory reset means restoring a device to the original state. +This is a feature of LmP, rather than of FoundriesFactory®. +A reset is performed as a script in ramdisk during boot. +It is triggered by the presence of specific files. Presence of the files is specified in the following order: #. ``/var/.factory_reset`` @@ -16,18 +16,18 @@ Presence of the files is specified in the following order: Each file has specific meaning. When a higher priority file is detected, remaining files are ignored. -Full factory reset +Full Factory Reset ------------------ -When the file ``/var/.factory_reset`` is present, the script performs full reset. -Full reset means restoring contents of ``/etc/`` and ``/var/`` from :ref:`ostree`. +When the file ``/var/.factory_reset`` is present, the script performs a full reset. +A full reset means restoring contents of ``/etc/`` and ``/var/`` from :ref:`ostree`. All contents created in these directories at runtime will be erased. -Partial factory reset +Partial Factory Reset --------------------- There are currently two options in partial reset. -The main difference with full reset is that the device remains connected to the FoundriesFactory®. +The main difference with full reset is that the device remains connected to your Factory. Keep SOTA ~~~~~~~~~ @@ -38,7 +38,7 @@ Contents of ``/var/`` are partially removed. ``/var/sota/`` contents are kept to allow aktualizr-lite to be preserved. Docker images and compose apps are deleted. -Keep SOTA and docker +Keep SOTA and Docker ~~~~~~~~~~~~~~~~~~~~ When the file ``/var/.factory_reset_keep_sota_docker`` is present, @@ -46,9 +46,9 @@ contents of ``/etc/`` are restored from ostree. Contents of ``/var/`` are partially removed. ``/var/sota/`` contents are kept to allow aktualizr-lite and compose-apps to be preserved. -``/var/lib/`` is preserved as the docker objects are stored there. +``/var/lib/`` is preserved as the Docker objects are stored there. RPMB ~~~~ -Currently ``RPMB`` is not cleared in either reset procedures. +Currently, ``RPMB`` is not cleared in either reset procedures. diff --git a/source/reference-manual/linux/linux-building.rst b/source/reference-manual/linux/linux-building.rst deleted file mode 100644 index 10afe1a62..000000000 --- a/source/reference-manual/linux/linux-building.rst +++ /dev/null @@ -1,238 +0,0 @@ -.. highlight:: sh - -.. _ref-linux-building: - -Building from Source -==================== - -This is a guide for building the base Linux microPlatform (LmP) from source -for Raspberry Pi 3 (64-bit). Additional information specific to other -targets is provided in :ref:`ref-linux-supported`. - -This guide assumes the reader is familiar with basic concepts of -OpenEmbedded. It is not meant to be an introduction to the -OpenEmbedded / Yocto Project. If you're just getting started, it's -strongly recommended to begin with the documentation provided in -:ref:`ref-linux-building-ref`. - - .. note:: - - Locally built images are useful for local development, testing and - for hardware enablement, but are not meant to be updated via OTA. - For OTA support we recommend creating your own Factory and using - our continuous integration system. - -.. _ref-linux-building-hw: - -Get Hardware ------------- - -You will need a x86 computer to develop on; Linux is currently -natively supported. On macOS and Windows, see -:ref:`ref-linux-dev-container` for information on setting up a -containerized Linux build environment. - -You will also require at least 50GB of storage for a complete Linux -microPlatform build. - -Set Up Build Environment ------------------------- - -On Debian-based Linux distributions, including Ubuntu, run:: - - $ sudo apt-get install coreutils gawk wget git-core diffstat unzip \ - texinfo g++ gcc-multilib build-essential chrpath socat cpio \ - openjdk-11-jre python2.7 python3 python3-pip python3-pexpect xz-utils \ - debianutils iputils-ping libsdl1.2-dev xterm libssl-dev libelf-dev \ - android-tools-fsutils ca-certificates repo whiptail - -.. note:: - - If you are running Ubuntu 18.04, make sure to enable the universe - repository by adding following line to your - :file:`/etc/apt/sources.list`: - - .. code-block:: none - - deb http://archive.ubuntu.com/ubuntu/ bionic universe - -On other Linux distributions, please check the `Yocto Project Quick -Start Guide`_ for additional guidance. - -.. _ref-linux-building-install: - -Install the Linux microPlatform -------------------------------- - -Download the meta layers -^^^^^^^^^^^^^^^^^^^^^^^^ - -The Linux microPlatform sources can be placed in any directory on your -workstation, as long it provides enough disk space for the complete -build. This uses the `Google Repo`_ tool to fetch a variety of Git repositories -at known-good revisions, and keep them in sync as time goes on. - -#. Make an installation directory for the Linux microPlatform, and - change into its directory:: - - mkdir lmp && cd lmp - - (You can also reuse an existing installation directory, or ``/build/lmp`` - if building inside the lmp-sdk container, as described at :ref:`ref-linux-dev-container`) - -#. Install update |version| using repo: - - .. parsed-literal:: - - repo init -u https://github.com/foundriesio/lmp-manifest -b |manifest_tag| - repo sync - -Set up Work Environment -^^^^^^^^^^^^^^^^^^^^^^^ - -Next, set up your work environment for building the source. - -The supported ``MACHINE`` target used by this guide is -``raspberrypi3-64``. (For information on other hardware platforms, see -:ref:`ref-linux-supported`.) - -The default distribution (``DISTRO``) is automatically set to ``lmp``, -which is provided by the meta-lmp-base layer (see -:ref:`ref-linux-layers` for more details). - -Set up your work environment using the ``setup-environment`` script:: - - MACHINE=raspberrypi3-64 source setup-environment [BUILDDIR] - -If ``MACHINE`` is not provided, the script will list all possible -machines found in every enabled OpenEmbedded / Yocto Project layer, -and force one to be selected. - -``BUILDDIR`` is optional; if it is not specified, the script will default to -``build-lmp``. Keep in mind that ``BUILDDIR`` must be within the ``lmp`` -directory, otherwise your build will fail. - -Build the lmp-base-console Image -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You can build the Linux microPlatform base-console image by running:: - - bitbake lmp-base-console-image - -.. note:: - - Depending on the amount of RAM and number of processors and cores - in your system, the speed of your Internet connection, and other - factors, the first build could take several hours. Subsequent - builds run much faster since some artifacts are cached. - -At the end of the build, your build artifacts will be found under -``deploy/images/raspberrypi3-64``. The artifact you will -use to flash your board is -``lmp-base-console-image-raspberrypi3-64.wic.gz``. - -Install the lmp-base-console Image -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you're using a Raspberry Pi 3, you can use the same procedure outlined in -:ref:`gs-flash-image`. See :ref:`ref-linux-supported` for additional information -on other targets. - -.. _ref-linux-building-ref: - -Install the LmP for your FoundriesFactory ------------------------------------------ - -In case you are already working with a FoundriesFactory, -you can instead download the source code for that factory -with the following steps. - -1. Make an installation directory for the LmP for that ````, - and change into its directory:: - - mkdir && cd - -2. Install the ```` meta layers using repo: - - .. parsed-literal:: - - repo init -u https://source.foundries.io/factories//lmp-manifest.git -b main -m .xml - repo sync - - The manifest ``.xml`` refers to all the LmP meta layers - and also to the ```` specific repositories - as described :ref:`ref-factory-sources`. - -3. Build the image for ````: - - .. parsed-literal:: - - MACHINE= source setup-environment [BUILDDIR] - bitbake lmp-factory-image - - The variable ``MACHINE`` should - be set to a supported machine. - see the current available option - in :ref:`ref-linux-supported`.) - - ``BUILDDIR`` is optional; - in case it is not provided, - script default is ``build-lmp``. - - ``lmp-factory-image`` is the suggested default image, - and can be customized with the steps from :ref:`ref-adding-packages-image`. - - It is worth remembering that the ``bitbake`` step can take a while. - - At the end of the build, - your build artifacts is found under - ``deploy/images/``. - The artifact you use to - flash your board is - ``lmp-base-console-image-.wic.gz``. - -.. warning:: - - The local build of your FoundriesFactory is great for - developing and debugging - and the results can be used on the host machine - or deployed to a hardware board. - - However, the image created locally is - not yet visible for the OTA system, - and is only available for local use. - - When you push the changes to the - FoundriesFactory git repositories - and trigger a new build - you can flash and register your device - following the instructions of - :ref:`gs-flash-device` - and :ref:`gs-register`. - This way you can take full advantage of OTA system. - -References ----------- - -The following reference material on OpenEmbedded and Yocto Project is -recommended for those new to either project. - -- `OpenEmbedded wiki`_ -- `Yocto Project main page`_ -- `Yocto Project Quick Start Guide`_ -- `Yocto Project Reference Manual`_ -- `BitBake Manual`_ - -.. _OpenEmbedded wiki: - https://www.openembedded.org/wiki/Main_Page -.. _Yocto Project main page: - https://www.yoctoproject.org/ -.. _Yocto Project Quick Start Guide: - https://docs.yoctoproject.org/kirkstone/brief-yoctoprojectqs/ -.. _Yocto Project Reference Manual: - https://docs.yoctoproject.org/kirkstone/ref-manual/ -.. _BitBake Manual: - https://docs.yoctoproject.org/bitbake/ - -.. _Google Repo: - https://source.android.com/docs/setup/create/repo diff --git a/source/reference-manual/linux/linux-dev-container.rst b/source/reference-manual/linux/linux-dev-container.rst index 2173e1714..aa2ae99b5 100644 --- a/source/reference-manual/linux/linux-dev-container.rst +++ b/source/reference-manual/linux/linux-dev-container.rst @@ -5,17 +5,15 @@ Development Container ===================== -You can install a Docker container based on Ubuntu 20.04 which -provides a Linux microPlatform build environment (this is the same -container image as used by our own CI). This is the recommended work -environment for building Linux microPlatform images on macOS and Windows. +You can install a Docker container based on Ubuntu which provides a Linux® microPlatform (LmP) build environment. +This is the same container image used by our own CI. +This is the recommended environment for building LmP images on macOS and Windows. #. `Install Docker`_. -#. Create local folders for ``sstate-cache``, ``downloads`` and ``build``, - as a way to save the build environment outside the container: +#. Create local folders for ``sstate-cache``, ``downloads`` and ``build``, as a way to save the build environment outside the container: - .. parsed-literal:: + :: mkdir -p ~/lmp/sstate-cache ~/lmp/downloads ~/lmp/build @@ -25,14 +23,12 @@ environment for building Linux microPlatform images on macOS and Windows. docker run --rm -u builder --name lmp-sdk -v ~/lmp/build:/build/lmp -v ~/lmp/sstate-cache:/build/lmp/sstate-cache -v ~/lmp/downloads:/build/lmp/downloads -it hub.foundries.io/lmp-sdk:|docker_tag| -#. Set up Git inside the container (required by ``repo``):: +#. Setup Git inside the container (required by ``repo``):: git config --global user.name "Your Full Name" git config --global user.email "your-email-address@example.com" -You can now follow instructions in :ref:`ref-linux-building-install` to -build the Linux microPlatform inside the running container, using -``/build/lmp`` as your main work folder. +You can now follow the instructions in :ref:`ref-linux-building-install` to build the LmP inside the running container, using ``/build/lmp`` as your main work folder. .. _Install Docker: https://docs.docker.com/get-docker/ diff --git a/source/reference-manual/linux/linux-dev-mode.rst b/source/reference-manual/linux/linux-dev-mode.rst index 90f8be363..722deaa07 100644 --- a/source/reference-manual/linux/linux-dev-mode.rst +++ b/source/reference-manual/linux/linux-dev-mode.rst @@ -3,11 +3,10 @@ Development Mode ================================= -LmP provides the variable ``DEV_MODE`` that enables a development mode -defined by the factory source code. +LmP provides the variable ``DEV_MODE`` that enables a development mode defined by the Factory source code. -The variable is defined as ``lmp:params:DEV_MODE`` and can be configured by updating a Factory's -:ref:`factory-config.yml ` in ``ci-scripts.git`` with:: +The variable is defined as ``lmp:params:DEV_MODE``, +and can be configured by updating the :ref:`factory-config.yml ` in ``ci-scripts.git`` with:: lmp: params: @@ -21,10 +20,8 @@ For example, if trying to enable systemd coredump:: $ cat meta-subscriber-overrides/meta-subrecipes-core/systemd/systemd_%.bbappend PACKAGECONFIG += "${@bb.utils.contains('DEV_MODE', '1', 'coredump', '', d)}" -Another example is to enable the Yocto Project ``IMAGE_FEATURES`` to include -some development and debug artifacts in the final image, -as defined by `Yocto Project image features`_, -the following line can be added to the file +Another example is to enable the Yocto Project ``IMAGE_FEATURES`` to include some development and debug artifacts in the final image, as defined by `Yocto Project image features`_. +The following can be added to the file, ``meta-subscriber-overrides/recipes-samples/images/lmp-factory-image.bb``:: IMAGE_FEATURES += "${@bb.utils.contains('DEV_MODE', '1', '', 'debug-tweaks tools-sdk', d)}" @@ -44,4 +41,4 @@ the following line can be added to the file fully supported by the customer. .. _Yocto Project image features: - https://docs.yoctoproject.org/kirkstone/ref-manual/features.html#image-features \ No newline at end of file + https://docs.yoctoproject.org/kirkstone/ref-manual/features.html#image-features diff --git a/source/reference-manual/linux/linux-disk-encryption.rst b/source/reference-manual/linux/linux-disk-encryption.rst index 4f11ee733..8ded5cb34 100644 --- a/source/reference-manual/linux/linux-disk-encryption.rst +++ b/source/reference-manual/linux/linux-disk-encryption.rst @@ -3,62 +3,49 @@ Disk Encryption Support ======================= -LmP currently supports encrypting the disk used by the root file system -on first boot, as a way to guarantee a unique LUKS2 master key per device. +LmP supports encrypting the disk used by the root file system on first boot. +This is to guarantee a unique LUKS2 master key per device. -The effort for creating an encrypted root file system during image creation -in CI (and required logic for online re-encryption during first boot) can be -tracked at https://github.com/foundriesio/meta-lmp/pull/868. +The effort for creating an encrypted root file system via CI (and required logic for online re-encryption during first boot) is part of ``meta-lmp`` `pull request 868 `. Prerequisites ------------- -As the process for decrypting the disk needs to be unattended, LmP requires -either PKCS#11 (e.g. OP-TEE with RPMB as secure storage) or TPM 2.0 to be -available by the target hardware, as they can be leveraged for securely -storing the Key Encryption Key (KEK) used for later decrypting the disk during -the boot process (via LUKS2 tokens, leveraging systemd-pkcs11 or systemd-tpm2, -see `systemd-cryptenroll`_ for more information). +As the process for decrypting the disk needs to be unattended, LmP requires either PKCS#11 (e.g. OP-TEE with RPMB as secure storage) or TPM 2.0 to be available by the target hardware. +These are leveraged for securely storing the Key Encryption Key (KEK) used for decrypting the disk during the boot process. +This is done via LUKS2 tokens, leveraging systemd-pkcs11 or systemd-tpm2, see `systemd-cryptenroll`_ for more information. -For better security, TPM 2.0 support also requires UEFI secure boot to be -enabled, as the key is bound to the Platform Configuration Register (PCR) 7, -which tracks the secure boot state of the machine. +For enhanced security, TPM 2.0 support also requires UEFI secure boot to be enabled. +This is because the key is bound to the Platform Configuration Register (PCR) 7, which tracks the secure boot state of the machine. Enabling Support for Disk Encryption ------------------------------------ The following options require customizations for disk encryption support: -For adding the required ``initramfs-module-cryptfs`` module to the initramfs -(based on what gets provided by ``MACHINE_FEATURES``, like ``tpm2`` or ``optee``): +For adding the required ``initramfs-module-cryptfs`` module to the initramfs (based on what gets provided by ``MACHINE_FEATURES``, like ``tpm2`` or ``optee``): .. code-block:: none DISTRO_FEATURES:append = " luks" -For splitting the ``/boot`` content from the ostree deployment in a separated -partition (where kernel/initramfs gets stored, unencrypted). This option is -enabled by default on systems booting with UEFI support. +For splitting the ``/boot`` content from the ostree deployment in a separated partition (where kernel/initramfs gets stored, unencrypted). +This option is enabled by default on systems booting with UEFI support: .. code-block:: none OSTREE_SPLIT_BOOT = "1" -For supporting copying content from ``/usr/lib/ostree-boot`` (used for -boot firmware updates) into ``/boot`` as part of the ostree deployment step (OTA). -This is required for supporting boot firmware updates on devices with encrypted -root file systems. +For supporting the copying of content from ``/usr/lib/ostree-boot`` (used for boot firmware updates) to ``/boot``, as part of the ostree deployment step (OTA). +This is required for supporting boot firmware updates on devices with encrypted root file systems: .. code-block:: none OSTREE_DEPLOY_USR_OSTREE_BOOT = "1" -For supporting ``/boot`` in a separated partition at the final image the selected -``WKS_FILE`` needs to support split boot. UEFI based devices already have such -setup by default, but on most ARM/ARM64 devices a custom WKS might be -required. As an example, iMX8-based devices should use -``sdimage-imx8-spl-split-boot-sota.wks.in`` instead of the default -``sdimage-imx8-spl-sota.wks.ini`` file: +For supporting ``/boot`` being in a separated partition at the final image the selected ``WKS_FILE`` needs to support split boot. +UEFI based devices already have such setup by default, but on most ARM/ARM64 devices a custom WKS might be required. +As an example, iMX8-based devices should use ``sdimage-imx8-spl-split-boot-sota.wks.in`` instead of the default ``sdimage-imx8-spl-sota.wks.ini`` file: .. code-block:: none @@ -66,31 +53,25 @@ required. As an example, iMX8-based devices should use .. note:: - Besides a custom ``WKS_FILE`` for split boot support, make sure to also update - the target fstab to automatically mount ``/boot`` (from the first partition) - at the root file system ``/boot`` folder. - This is not required with UEFI-based systems as systemd is capable of - automatically identifying and mounting the ESP partition during boot. + Along with a custom ``WKS_FILE`` for split boot support, also update the target fstab to automatically mount ``/boot`` (from the first partition). + This is not required with UEFI-based systems, as systemd is capable of automatically identifying and mounting the ESP partition during boot. Implementation Details for OP-TEE PKCS#11 Support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A dedicated slot is required to avoid conflicts with the PKCS#11 token slot -normally used by ``aktualizr-lite``. This dedicated slot is currently hardcoded -to slot 1, with the label ``lmp``. +A dedicated slot is required to avoid conflicts with the PKCS#11 token slot normally used by ``aktualizr-lite``. +This dedicated slot is currently hardcoded to slot 1, with the label ``lmp``. -During the encryption process the token slot is initialized and a RSA 2048 key -is generated, which is later used by `systemd-cryptenroll`_. +During the encryption process the token slot is initialized and a RSA 2048 key is generated, which is later used by `systemd-cryptenroll`_. -Make sure to **not** erase the token slot or the key during the lifetime of the -image, otherwise the system will fail to boot (a recovery key can be created and -provided manually if required, but it won't be an unattended boot). +Make sure to **not** erase the token slot or the key during the lifetime of the image. +Doing so would cause the system to fail at boot. +A recovery key can be created and provided manually if required, but it will not be an unattended boot. Testing TPM 2.0 Support With Qemu (x86) and swtpm ------------------------------------------------- -It is possible to test the disk encryption support with TPM 2.0 with Qemu and -`swtpm`_. +It is possible to test the disk encryption support with TPM 2.0 with QEMU and `swtpm`_. Make sure LUKS support is enabled for your x86 target: @@ -99,19 +80,18 @@ Make sure LUKS support is enabled for your x86 target: $ cat meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc DISTRO_FEATURES:append:intel-corei7-64 = " luks" -Then make sure to enroll the :ref:`UEFI Secure Boot Certificates ` -to enable secure boot support. This is required as the LUKS2 TPM 2.0 token -leverages PCR 7, which tracks the secure boot state. +Then enroll the :ref:`UEFI Secure Boot Certificates ` to enable secure boot support. +This is required as the LUKS2 TPM 2.0 token leverages PCR 7, which tracks the secure boot state. -Now install ``swtpm`` in the host machine (if not already installed), and start the ``swtpm`` -daemon, which will be later consumed by Qemu and act as the hardware TPM. +Now install ``swtpm`` on the host machine, and start the ``swtpm`` daemon. +This will be consumed by QEMU and act as the hardware TPM. .. code-block:: console $ mkdir -p /tmp/mytpm $ while true; do swtpm socket --tpmstate dir=/tmp/mytpm --ctrl type=unixio,path=/tmp/mytpm/swtpm-sock --tpm2; done; -Run Qemu with the required extra TPM 2.0 related commands: +Run QEMU with the required extra TPM 2.0 related commands: .. code-block:: console @@ -125,7 +105,7 @@ Run Qemu with the required extra TPM 2.0 related commands: -chardev socket,id=chrtpm,path=/tmp/mytpm/swtpm-sock \ -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0 -Now during boot you should see the following during the first boot: +You should see the following during the first boot: .. code-block:: none diff --git a/source/reference-manual/linux/linux-distro.rst b/source/reference-manual/linux/linux-distro.rst index 0e4d748c1..9a86a36f6 100644 --- a/source/reference-manual/linux/linux-distro.rst +++ b/source/reference-manual/linux/linux-distro.rst @@ -3,11 +3,14 @@ LmP Distros =========== -LmP provides reference distros to be used in different use cases. They state the default configuration for the tools used on a FoundriesFactory. The distro definition files are under ``meta-lmp/meta-lmp-base/conf/distro``. +LmP provides reference distros for different use cases. +These state the default configuration for the tools used by an image. +The distro definition files are under ``meta-lmp/meta-lmp-base/conf/distro``. -If you are not familiar with the concept of Distro, the Yocto Project definition can help (`term-DISTRO`_), another good document is the `Poky`_ description, which is the default distro reference used by the Yocto Project. +If you are not familiar with the concept of a *distro*, see the Yocto Project variable definition for `DISTRO`_. +Also helpful is the description of `Poky`_ , the default reference distro used by the Yocto Project. -LmP supported distros are: +The LmP supported distros are: * ``lmp`` * ``lmp-base`` @@ -16,48 +19,52 @@ LmP supported distros are: * ``lmp-xwayland`` .. note:: - For guidance on building new targets with a different distro and customizations, see: :ref:`Customizing the Distro `. + For guidance on building Targets with a different distro and customizations, read :ref:`Customizing the Distro `. lmp -*** +--- -The ``lmp`` is the default distro for a FoundriesFactory. The main point of this distro is to configure the packages for working with OTA, and to organize the boot sequence, including the image architecture using OSTree and installing the needed artifacts. +The ``lmp`` is the default distro for a Factory. +The main point of this distro is to configure the packages for working with OTA, and to organize the boot sequence. +This includes the image architecture using OSTree, and installing the needed artifacts. -This is the default distro used when a FoundriesFactory is created. +This is the default distro used when a Factory is created. lmp-base -******** +-------- -The ``lmp-base`` is the distro recommended for bring up and low level development (when the platform system is being developed or adjusted, for example). +``lmp-base`` is the recommended distro for bring up and low level development. +An example use case would be when the platform system is being developed or adjusted. It overrides some configurations from ``lmp`` to generate a friendly system for development, such as: -* It does not support OSTree. +* No support for OSTree. -* The rootfs is read-writable (as the Poky's default) and as a consequence, OTA is disabled on this distro. +* The rootfs is read-writable, and as a consequence, OTA is disabled. -* The image architecture is different, there are two directories: ``boot`` and ``root``, for the boot files and the rootfs, respectively. +* The image architecture is different. There are two directories: ``boot`` and ``root``, for the boot files and the rootfs, respectively. * The U-Boot configuration is defined apart from ``lmp`` which provides flexibility. * The U-Boot scripts are provided as a package and can be easily changed. -* The Linux Kernel binary, along with the required DTB files, are provided as separate files, instead of inside a boot image. This way the binaries can be replaced for testing purposes. +* The Linux Kernel binary, along with the required DTB files, are provided as separate files, instead of inside a boot image. + This lets the binaries be replaced for testing purposes. .. _ref-lmp-mfgtool: lmp-mfgtool -*********** +----------- -The distro used to generate the ``mfgtool-files`` artifacts which provide the deploy and update tool for some machines. +The distro used to generate the ``mfgtool-files`` which provide the deploy and update tool for some machines. .. _ref-lmp-wayland-xwayland: lmp-wayland/lmp-xwayland -************************ +------------------------ -The distros which provide Wayland and XWayland support on top of ``lmp`` distro. +These distros provide Wayland and XWayland support on top of the ``lmp`` distro. -.. _term-DISTRO: https://docs.yoctoproject.org/kirkstone/ref-manual/variables.html#term-DISTRO +.. _DISTRO: https://docs.yoctoproject.org/kirkstone/ref-manual/variables.html#term-DISTRO .. _Poky: https://www.yoctoproject.org/software-overview/reference-distribution/ diff --git a/source/reference-manual/linux/linux-kernel.rst b/source/reference-manual/linux/linux-kernel.rst index 5d4851256..df783463a 100644 --- a/source/reference-manual/linux/linux-kernel.rst +++ b/source/reference-manual/linux/linux-kernel.rst @@ -3,137 +3,115 @@ Linux Kernel ============ -A common and unified Linux® Kernel source tree is provided and used by -the Linux microPlatform. The latest continuous release is available -at `github.com/foundriesio/linux`_. +A common and unified Linux® Kernel source tree is provided and used by the Linux microPlatform (LmP). +The latest continuous release is available on the `Foundries.io™ GitHub `_. -The Linux Kernel recipe can be found in the :ref:`Meta-LMP layer -`, under the -``meta-lmp-base/recipes-kernel/linux`` directory. +The kernel recipe can be found within the :ref:`meta-lmp layer `, under ``meta-lmp-base/recipes-kernel/linux``. .. _ref-linux-fragments: -Linux microPlatform Kernel Configuration Fragments --------------------------------------------------- +LmP Kernel Configuration Fragments +---------------------------------- -Together with the unified Linux Kernel tree, the Linux microPlatform also -provides an additional repository for the kernel configuration fragments. -The latest continuous release for the kernel configuration fragments is -available at `github.com/foundriesio/lmp-kernel-cache`_. +Together with the unified Linux Kernel tree, the LmP provides an additional repository for kernel configuration fragments. +The latest continuous release of the kernel configuration fragments is available at `lmp-kernel-cache `_. -You can find the list of supported BSP definitions and configuration fragments -used under the ``lmp-kernel-cache/bsp`` directory. +You can find the list of supported BSP definitions and the configuration fragments used under ``lmp-kernel-cache/bsp``. -The fragments repository works similarly to the upstream ``yocto-kernel-cache`` -repository, so the same development workflow and documentation applies. -See the `Yocto Project Linux Kernel Development Manual`_ for more information -on how to work and manage the kernel metadata and configuration fragments. +The fragments repository works similarly to the upstream ``yocto-kernel-cache`` repository. +As such, the same development workflow and documentation applies. +See the `Yocto Project Linux Kernel Development Manual`_ on how to work with the kernel metadata and configuration fragments. -The Porting Guide includes the section :ref:`ref-pg-how-to-configure-linux` on -on how to add a custom Linux Kernel configuration which can be used to add: +The Porting Guide includes :ref:`ref-pg-how-to-configure-linux`. +This details how to add a custom Linux Kernel configuration, which can be used to add: * the complete machine configuration. * fragments: a set of ``CONFIG_`` variables working to change a default machine configuration. -.. _github.com/foundriesio/linux: https://github.com/foundriesio/linux -.. _github.com/foundriesio/lmp-kernel-cache: https://github.com/foundriesio/lmp-kernel-cache .. _Yocto Project Linux Kernel Development Manual: https://docs.yoctoproject.org/4.0.6/kernel-dev/advanced.html -Linux microPlatform with Real-Time Linux Kernel ------------------------------------------------ +LmP With Real-Time Linux Kernel +-------------------------------- -The recipe ``meta-lmp/meta-lmp-base/recipes-kernel/linux/linux-lmp-rt_git.bb`` -or ``meta-lmp/meta-lmp-base/recipes-kernel/linux/linux-lmp-fslc-imx-rt_git.bb`` -can be used for real-time Linux. -This is based on the ``linux-lmp`` recipe, -but extended to include the ``PREEMPT_RT`` patch-set -(updated along with stable kernel updates). +The recipes that can be used for real-time Linux are either: -The instructions to change the default Linux kernel to real-time are -described in the following sections. -After the changes, -build the Linux microPlatform image as usual. +* ``meta-lmp/meta-lmp-base/recipes-kernel/linux/linux-lmp-rt_git.bb`` +* ``meta-lmp/meta-lmp-base/recipes-kernel/linux/linux-lmp-fslc-imx-rt_git.bb`` -Building Linux microPlatform with linux-lmp-rt -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Theses are based on the ``linux-lmp`` recipe, extended to include the ``PREEMPT_RT`` patch-set (updated along with stable kernel updates). -Set ``PREFERRED_PROVIDER_virtual/kernel`` -to ``linux-lmp-rt`` -in ``meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc``:: +The instructions to change the default Linux kernel to real-time are described in the following sections. +After making the changes, build the LmP image as usual. + +Building LmP with linux-lmp-rt +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In ``meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc``, +set ``PREFERRED_PROVIDER_virtual/kernel`` to ``linux-lmp-rt`` :: $ cat meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc PREFERRED_PROVIDER_virtual/kernel:intel-corei7-64 = "linux-lmp-rt" -Building Linux microPlatform with linux-lmp-fslc-imx-rt -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Building LmP With linux-lmp-fslc-imx-rt +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Set ``PREFERRED_PROVIDER_virtual/kernel`` -to ``linux-lmp-fslc-imx-rt`` -in ``meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc``:: +In ``meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc``, +set ``PREFERRED_PROVIDER_virtual/kernel`` to ``linux-lmp-fslc-imx-rt`` :: $ cat meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc PREFERRED_PROVIDER_virtual/kernel:mx6ull-nxp-bsp = "linux-lmp-fslc-imx-rt" -Linux microPlatform with the Real-Time Xenomai4 Core ----------------------------------------------------- - -The recipe -``meta-lmp/meta-lmp-base/recipes-kernel/linux/linux-lmp-fslc-imx-xeno4_git.bb`` -can be used to enable the Xenomai4 co-kernel on iMX boards. +LmP With the Real-Time Xenomai4 Core +------------------------------------- - Like its predecessors in the Xenomai core series, `Xenomai4`_ with the - `EVL core`_ brings real-time capabilities to Linux by embedding a - companion core into the kernel, which specifically deals with tasks - requiring ultra low and bounded response time to events. +The recipe ``meta-lmp/meta-lmp-base/recipes-kernel/linux/linux-lmp-fslc-imx-xeno4_git.bb`` can be used to enable the Xenomai4 co-kernel on iMX boards. - In this model, the general purpose kernel and the real-time core operate - almost asynchronously, both serving their own set of tasks, always - giving the latter precedence over the former. + Like its predecessors in the Xenomai core series, + `Xenomai4`_ with the `EVL core`_ brings real-time capabilities to Linux by embedding a companion core into the kernel, + which specifically deals with tasks requiring ultra low and bounded response time to events. + + In this model, the general purpose kernel and the real-time core operate almost asynchronously, + both serving their own set of tasks, always giving the latter precedence over the former. .. _Xenomai4: https://evlproject.org/overview/ .. _EVL core: https://evlproject.org/core/ -Building Linux microPlatform with linux-lmp-fslc-imx-xeno4 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Building LmP With linux-lmp-fslc-imx-xeno4 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Set ``PREFERRED_PROVIDER_virtual/kernel`` to -``linux-lmp-fslc-imx-xeno4`` and ``MACHINE_FEATURES:append`` to ``xeno4`` -in ``meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc``:: +In ``meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc``, +Set ``PREFERRED_PROVIDER_virtual/kernel`` to ``linux-lmp-fslc-imx-xeno4``, +and ``MACHINE_FEATURES:append`` to ``xeno4`` :: $ cat meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc PREFERRED_PROVIDER_virtual/kernel:mx8mm-nxp-bsp = "linux-lmp-fslc-imx-xeno4" MACHINE_FEATURES:append = " xeno4" -Linux microPlatform with Linux upstream ---------------------------------------- +LmP With Linux Upstream +------------------------ -The recipe ``meta-lmp/meta-lmp-base/recipes-kernel/linux/linux-lmp-dev.bb`` -can be used to build the Linux microPlatform with the upstream kernel tree -instead of the LmP unified tree. ``linux-lmp-dev`` also uses the Linux -microPlatform Kernel Configuration Fragments repository for a compatible -configuration. +The recipe ``meta-lmp/meta-lmp-base/recipes-kernel/linux/linux-lmp-dev.bb`` can be used to build the LmP with the upstream kernel tree instead of the LmP unified tree. +``linux-lmp-dev`` also uses the LmP Kernel Configuration Fragments repository for a compatible configuration. -Building Linux microPlatform with linux-lmp-dev -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Building LmP With linux-lmp-dev +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Set the ``PREFERRED_PROVIDER_virtual/kernel`` to ``linux-lmp-dev`` in -``meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc``:: +In ``meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc``, +set ``PREFERRED_PROVIDER_virtual/kernel`` to ``linux-lmp-dev`` :: $ cat meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc PREFERRED_PROVIDER_virtual/kernel = "linux-lmp-dev" -Now just build any of the supported Linux microPlatform images. +Now build any of the supported LmP images. -Specifying Linux Git Tree, Branch and Commit Revision -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Specifying Linux Git Tree, Branch, and Commit Revision +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following variables can be also set in -``meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc`` -in order to build ``linux-lmp-dev`` using a specific Linux tree, branch or -commit revision:: +The following can be also set in ``meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc``, +in order to build ``linux-lmp-dev`` using a specific Linux tree, branch, or commit revision:: KERNEL_REPO = "git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git" # Kernel git repository KERNEL_BRANCH = "master" # Git kernel branch (default: master) diff --git a/source/reference-manual/linux/linux-layers.rst b/source/reference-manual/linux/linux-layers.rst index 98e024804..bb9eba985 100644 --- a/source/reference-manual/linux/linux-layers.rst +++ b/source/reference-manual/linux/linux-layers.rst @@ -3,9 +3,8 @@ OpenEmbedded / Yocto Project Layers =================================== -The Linux microPlatform (LmP) is composed of several OpenEmbedded and Yocto -Project layers, including the core build system, distribution, images, -and Board Support Packages (BSPs). +The Linux® microPlatform (LmP) is composed of several OpenEmbedded and Yocto Project layers, +including the core build system, distribution, images, and Board Support Packages (BSPs). .. _ref-linux-layers-meta-lmp-base-layers: @@ -22,7 +21,7 @@ Layer Description distribution. `meta-openembedded`_ A collection of layers and recipes for the OE-core universe. Since the reduction in recipes to the core, - meta-openembedded was created for everything else. There are + ``meta-openembedded`` was created for everything else. There are currently approximately 650 recipes in this layer. It is used by the LmP for additional utilities and network support. @@ -53,13 +52,13 @@ Layer Description `meta-arm`_ Provides support for general recipes for the ARM architecture and BSP support for ARM reference platforms. `meta-intel`_ Board support layer for Intel based devices. -`meta-raspberrypi`_ Board support layer for the Raspberry Pi boards. +`meta-raspberrypi`_ Board support layer for the Raspberry Pi board based devices. `meta-yocto`_ Board support layer for the Yocto Project hardware references, such as BeagleBone Black. `meta-freescale`_ Board support layer for the Freescale platforms. `meta-freescale-3rdparty`_ Additional board support layer for Freescale platforms - (not officially supported by meta-Freescale maintainers). + (not officially supported by ``meta-freescale`` maintainers). `meta-st-stm32mp`_ Board support layer for STMicroelectronics based devices. `meta-tegra`_ Board support layer for NVIDIA based devices. `meta-ti`_ Board support layer for Texas Instruments based devices. @@ -74,34 +73,26 @@ Layer Description The meta-lmp Base Layer --------------------------------------- -The ``meta-lmp-base`` layer provides the LmP distribution -configuration and a base set of recipes and config files, such as a unified -Linux kernel and a set of standard images. +The ``meta-lmp-base`` layer provides the LmP distribution configuration and a base set of recipes and config files, +such as a unified Linux kernel and a set of standard images. -Configuration for the LmP distro can be found at -``conf/distro/lmp.conf`` and ``conf/distro/include/lmp.inc``. +Configuration for the LmP distro can be found at ``conf/distro/lmp.conf`` and ``conf/distro/include/lmp.inc``. -The ``lmp-base-console-image`` recipe can be found at -``recipes-samples/images/lmp-base-console-image.bb``. You can find the -default set of packages used by the image via the -``CORE_IMAGE_BASE_INSTALL`` variable. +The ``lmp-base-console-image`` recipe can be found at ``recipes-samples/images/lmp-base-console-image.bb``. +You can find the default set of packages used by the image via the ``CORE_IMAGE_BASE_INSTALL`` variable. The meta-lmp-bsp Layer -------------------------------------- -``meta-lmp-bsp`` provides the kernel recipes, u-boot configuration -fragments, WIC files, and so on for supported targets. +``meta-lmp-bsp`` provides the kernel recipes, u-boot configuration fragments, WIC files, and so on for supported targets. While primarily used as an extension of the vendor BSP layers (e.g. meta-freescale), -it can also handle board configuration for cases where the vendor layer -is not easily compatible with LmP (e.g. a layer based on an older Yocto Project release). +it can also handle board configuration for cases where the vendor layer is not easily compatible with LmP (e.g. a layer based on an older Yocto Project release). The main configuration can be found at ``conf/machine/include/lmp-machine-custom.inc``. -This gets included by ``meta-lmp-base/classes/lmp.bbclass`` if available (users can decide -to use ``meta-lmp-base`` only). +This gets included by ``meta-lmp-base/classes/lmp.bbclass`` if available (you can decide to use ``meta-lmp-base`` only). -Here is an example of how a BSP configuration gets extended from the -vendor BSP layer:: +Here is an example of how a BSP configuration gets extended from the vendor BSP layer:: # Beaglebone PREFERRED_PROVIDER_virtual/bootloader:beaglebone-yocto = "u-boot-fio" @@ -115,31 +106,24 @@ vendor BSP layer:: KERNEL_IMAGETYPE:beaglebone-yocto = "fitImage" KERNEL_CLASSES:beaglebone-yocto = " kernel-lmp-fitimage " -When adding or changing the LmP BSP configuration values, please use -``meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc`` -instead, which gets parsed after ``lmp-machine-custom.inc`` and is -factory specific. +When adding or changing the LmP BSP configuration values, please use ``meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc`` instead. +This gets parsed after ``lmp-machine-custom.inc`` and is factory specific. -``lmp-machine-custom.inc`` should be used for LmP upstream BSP support -only. +``lmp-machine-custom.inc`` should be used for LmP upstream BSP support only. Customizing the LmP BSP Layers List ------------------------------------------------ +----------------------------------- -LmP is composed of a set of base layers plus an extensive -list of BSP layers that are all enabled by default -(see :ref:`ref-linux-layers-meta-lmp-bsp-layers`). +LmP is composed of a set of base layers plus an extensive list of BSP layers that are all enabled by default. +See :ref:`ref-linux-layers-meta-lmp-bsp-layers`. -As this is not desired by everyone, any -FoundriesFactory user can easily customize the BSP layers enabled and used -by a Factory. +As this is not desired by everyone, any Factory can easily customize the BSP layers enabled. -To define your own set of BSP layers (used by Bitbake), modify (or -create if your Factory was created before LmP v76) the -``lmp-manifest/conf/bblayers-factory.inc`` bblayers include fragment, -replacing the ``BSPLAYERS`` variable with your own list of BSP layers. -Make sure ``meta-lmp-bsp`` is also included by default, unless you +To define your own set of BSP layers, +modify (create if your Factory was created before LmP v76) the ``lmp-manifest/conf/bblayers-factory.inc`` bblayers include fragment. +Replace the ``BSPLAYERS`` variable with your own list of BSP layers. +Make sure ``meta-lmp-bsp`` is also included, unless you want to completely define your own BSP configuration. An example for enabling only the ``meta-intel`` BSP layer:: diff --git a/source/reference-manual/linux/linux-lmp-fs.rst b/source/reference-manual/linux/linux-lmp-fs.rst index 4e4bf4318..72746c70d 100644 --- a/source/reference-manual/linux/linux-lmp-fs.rst +++ b/source/reference-manual/linux/linux-lmp-fs.rst @@ -3,7 +3,9 @@ LmP File Structure ================== -LmP uses the `OSTree`_ upgrade system to cover platform updates. It brings a modified file system structure, the details for which are covered on this page, along with some tips about the LmP structure and OTA behavior. +LmP uses the `OSTree`_ upgrade system to cover platform updates. +This brings a modified file system structure, which is detailed on this page. +Also covered here are some related tips about LmP structure, and OTA behavior. OSTree File System Structure ---------------------------- @@ -33,9 +35,12 @@ OSTree File System Structure drwxr-xr-x 12 root root 4096 Jan 1 1970 usr drwxr-xr-x 13 root root 4096 Aug 1 15:46 var -OSTree brings a **read-only** file system, where the disk partition is ``/sysroot`` and the root that mounted at ``/`` (as above) is ``/sysroot/ostree/deploy/lmp/deploy/``. +OSTree brings a **read-only** file system, where the disk partition is ``/sysroot``. +The root that mounted at ``/`` (as above) is ``/sysroot/ostree/deploy/lmp/deploy/``. -Some folders should not be manipulated in order to ensure proper behavior of OTA. The ``/usr`` path is an example of a critical folder that is mounted as read-only and should not be touched—this is covered by LmP OTA. +.. warning:: + Some folders should not be manipulated in order to ensure proper behavior of OTA. + The ``/usr`` path is an example of a critical folder that is mounted as read-only and should not be touched—this is handled by the LmP OTA. Persistent Storage ------------------ @@ -54,7 +59,8 @@ These folders are treated like persistent storage on the device and have particu * Covered by OTA if untouched. - * As soon as OSTree detects a change in this directory, it performs a 3-way merge using the old default configuration, the active system's ``/etc``, and the new default configuration. This is then not covered by OTA anymore. + * As soon as OSTree detects a change in this directory, it performs a 3-way merge using the old default configuration, the active system's ``/etc``, and the new default configuration. + This is then no longer covered by OTA. * For the reason above, we do not recommend nor support setting system configurations in this directory. It is more reliable to set critical configurations under ``/usr/lib`` as that is always covered by OTA. @@ -79,13 +85,15 @@ Important Files and Folders -rw-r--r-- 1 root root 885 Aug 1 15:41 sota.toml -rw-r--r-- 1 root root 180224 Aug 1 15:49 sql.db -**/var/sota/sota.toml**: Stores relevant OTA information, like Tag, Apps, custom configurations, certificates location and server address. +``/var/sota/sota.toml``: Stores relevant OTA information, like Tag, Apps, custom configurations, certificates location and server address. -**/var/sota/reset-apps**: Holds preloaded apps if :ref:`ug-restorable-apps` are used (default since LmP **v85**). +``/var/sota/reset-apps``: Holds preloaded apps if :ref:`ug-restorable-apps` are used (default since LmP **v85**). -**/var/sota/compose-apps**: Apps are extracted to this location during app loading. It holds preloaded apps if Compose Apps are used. +``/var/sota/compose-apps``: Apps are extracted to this location during app loading. +It holds preloaded apps if Compose Apps are used. -**/var/sota/current-target**: Brings valuable information about the current Target running on the device, including LmP and containers information. This is populated after the first OTA. +``/var/sota/current-target``: Brings valuable information about the current Target running on the device, including LmP and containers information. +This is populated after the first OTA. .. prompt:: @@ -97,15 +105,17 @@ Important Files and Folders CONTAINERS_SHA="459e19cde44e17b17054b0cd972f0520cd214f58" TAG="" -**/var/sota/sql.db**: Device registration database. +``/var/sota/sql.db``: Device registration database. -**/var/sota/client.pem**, **/var/sota/pkey.pem** and **/var/sota/root.crt**: Device registration certificates. If available, ``client.pem`` and ``pkey.pem`` can be stored in an HSM rather than on files. +``/var/sota/client.pem``, ``/var/sota/pkey.pem``, and ``/var/sota/root.crt``: Device registration certificates. +If available, ``client.pem`` and ``pkey.pem`` can be stored in an HSM rather than on files. * ``/var/lib/docker``: Stores Docker images and containers. * ``/var/rootdirs/home/fio/``: Home directory. -* ``/etc/os-release``: Brings valuable LmP information, including LmP Target, Tag and LmP release. It does not include information on containers Target. +* ``/etc/os-release``: Brings valuable LmP information, including LmP Target, Tag, and LmP release. + It does not include information on Target containers. .. prompt:: @@ -127,9 +137,10 @@ Important Files and Folders Tips and Suggestions -------------------- -* A :ref:`systemd service ` can be used in case a file in a directory not covered by OTA needs to be updated. +* A :ref:`systemd service ` can be used if case a file in a directory not covered by OTA needs to be updated. -* It is recommended to store custom user files under ``/var/local``. Keep any custom files location in mind when implementing a :ref:`ref-factory-device-reset`. +* It is recommended to store custom user files under ``/var/local``. + Keep any custom files location in mind when implementing a :ref:`ref-factory-device-reset`. * The full initial Target information (includes containers and LmP) just after the provisioning of a device can be checked with: @@ -140,6 +151,7 @@ Tips and Suggestions After the first OTA, it can be read in ``/var/sota/current-target`` as discussed previously. -* If enabling :ref:`ref-linux-persistent-log`, ``/var/log`` is used to store system logs. It is recommended to mount it in an additional storage so it does not take valuable internal storage space which could impact the OTA behavior. +* If enabling :ref:`ref-linux-persistent-log`, ``/var/log`` is used to store system logs. + It is recommended to mount it in an additional storage so it does not take valuable internal storage space which could impact the OTA behavior. .. _OSTree: https://ostreedev.github.io/ostree/introduction/ diff --git a/source/reference-manual/linux/linux-net-debug.rst b/source/reference-manual/linux/linux-net-debug.rst index 1fa2077d4..2ded7528f 100644 --- a/source/reference-manual/linux/linux-net-debug.rst +++ b/source/reference-manual/linux/linux-net-debug.rst @@ -7,23 +7,19 @@ Network Debugging ================= -This page provides information on debugging network related issues on -the Linux microPlatform. +This page provides information on debugging network related issues on the Linux® microPlatform (LmP). -Using ``tcpdump`` ------------------ +Using tcpdump +------------- -The Linux microPlatform base image includes a ``tcpdump`` binary at -``/usr/sbin/tcpdump`` for use capturing traffic and diagnosing issues. -Note that ``/usr/sbin`` is not part of the :envvar:`PATH` environment -variable for the base image user, and you must run ``tcpdump`` as root. +The LmP base image includes a ``tcpdump`` binary at ``/usr/sbin/tcpdump``. +This is used for capturing traffic and diagnosing issues. +Note that ``/usr/sbin`` is not part of the :envvar:`PATH` environment for the base image user, and you must run ``tcpdump`` as root. Capturing Bluetooth 6lo Network Traffic ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If your Linux microPlatform device is acting as a gateway to IoT -devices connected via a Bluetooth link, you may want to restrict your -capture to just the traffic exchanged with those IoT devices. +If your LmP device is acting as a gateway to IoT devices connected via a Bluetooth link, you may want to restrict the capture to the traffic exchanged between those IoT devices. To do this, use ``-i bt0`` when invoking ``tcpdump``: @@ -31,24 +27,20 @@ To do this, use ``-i bt0`` when invoking ``tcpdump``: $ sudo /usr/sbin/tcpdump -i bt0 -Note that if you only have one such device, the network interface -will be torn down by the kernel if the Bluetooth link is lost. When -that happens, you'll see a message like this from tcpdump: +Note that if you only have one such device, the network interface will be torn down by the kernel if the Bluetooth link is lost. +When that happens, you'll see a message like this from ``tcpdump``: .. code-block:: none tcpdump: pcap_loop: The interface went down -The best workaround for this if you want to continue to capture -traffic on ``bt0`` for a Bluetooth device that resets and reconnects -is to have another device remain connected to your Linux microPlatform -gateway for the duration of the capture. +If you want to continue to capture traffic on ``bt0`` for a Bluetooth device that resets and reconnects, +have another device remain connected to your LmP gateway for the duration of the capture. Capturing LAN Network Traffic ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you're using Ethernet, use ``-i eth0`` to view traffic exchanged -with the rest of the LAN: +If you're using Ethernet, use ``-i eth0`` to view traffic exchanged with the rest of the LAN: .. code-block:: console @@ -59,33 +51,26 @@ You can use ``-i wlan0`` for wireless traffic. Other Network Interfaces ~~~~~~~~~~~~~~~~~~~~~~~~ -To view a complete list of network interfaces you can use with the -``-i`` option, run: +To view a complete list of network interfaces you can use with the ``-i`` option, run: .. code-block:: console $ ip link show -One of these may be useful, for example, if you need to capture -traffic on a network device created for use with containers. +One of these may be useful to capture traffic on a network device created for use with containers. Capturing to a File ~~~~~~~~~~~~~~~~~~~ -It is often convenient to capture traffic in a file for later -analysis, for example with tools such as Wireshark. Use ``-w -file.pcap`` when invoking ``tcpdump`` to save to a file named -``file.pcap``. For example, to capture traffic exchanged over the -``bt0`` interface to a file ``bt0.pcap``: +It can be convenient to capture traffic in a file for later analysis, such as with Wireshark. +Using ``-w file.pcap`` when invoking ``tcpdump`` will save to a file named ``file.pcap``. +For example, to capture traffic exchanged over the ``bt0`` interface to a file ``bt0.pcap``: .. code-block:: console $ sudo /usr/sbin/tcpdump -i bt0 -w bt0.pcap -At time of writing, the version of tcpdump present in the Linux -microPlatform does not support the ``--print`` option. To capture to -file and view the text representation simultaneously, you can use a -pipeline like this: +To capture to file and view the text simultaneously, use a pipeline like this: .. code-block:: console diff --git a/source/reference-manual/linux/linux-oss-compliance.rst b/source/reference-manual/linux/linux-oss-compliance.rst index 215d57602..20755e7a8 100644 --- a/source/reference-manual/linux/linux-oss-compliance.rst +++ b/source/reference-manual/linux/linux-oss-compliance.rst @@ -1,39 +1,33 @@ -OSS Compliance with FoundriesFactory +OSS Compliance With FoundriesFactory ==================================== -The Yocto Project provides a set of tools to help with Open Source Software -compliance. The FoundriesFactory is configured to use some of them by default -and provides a good starting point when working with license requirements. +The Yocto Project provides a set of tools to help with Open Source Software (OSS) compliance. +FoundriesFactory® is configured to use some of them by default. +These provide a good starting point when working with license requirements. -There are several different licenses. The focus in this document is to detail -some technical aspects needed when handling the GPLv2 and GPLv3 license family, -however the content here can be extended the same way for other licenses which -require the same. +There are several OSS licenses. +This document details technical aspects for handling the GPLv2 and GPLv3 license family. +However, the content here can be extended to other licenses. -.. warning:: This document focus on some technical aspects and must not be - considered a legal advice. Always consult a lawyer. +.. warning:: This document focus on some technical aspects and must not be considered a legal advice. + Always consult a lawyer. -Providing source code, and license manifest -------------------------------------------- +Providing Source Code and License Manifest +------------------------------------------ -A common requirement for some of the OSS licenses, such as GPLv2 and others, -is to provide: +Common requirements for many OSS licenses, such as GPLv2 and others, are to provide: -* A license manifest: all the projects used and their license -* The source code: some licenses, such as GPLv2, require that all source - code, including scripts and changes be available (accessible) to the user -* The license text and the copyright information: a copy of the license for each - project (required by some licenses such as GPLv2 and others) and the copyright - information for attribution. +* A **license manifest**: all the projects used and their license +* The **source code**: all source code, including scripts and any changes, to be made available (accessible) to the user +* The **license text** and **copyright information**: a copy of the license for each project and the copyright information for attribution. -FoundriesFactory configures the LmP to provide a license manifest and source -code tarball by default. +FoundriesFactory configures the LmP to provide a license manifest and source code tarball by default. -The license manifest can be found at +The license manifest for a given Target can be found at: ``https://app.foundries.io/factories//targets//artifacts//other/-.license.manifest`` -All the package's source code under GPLv2 or GPLv3 license family can be found at +All the image's packages source code under the GPLv2 or GPLv3 license family can be found at: ``https://app.foundries.io/factories//targets//artifacts//other/-source-release.tar`` @@ -42,33 +36,25 @@ All the package's source code under GPLv2 or GPLv3 license family can be found a Where: * ```` is the FoundriesFactory name -* ```` is the target version (and can be found in the first column of - :guilabel:`Targets`). +* ```` is the target version (and can be found in the first column of :guilabel:`Targets`). * ```` is the machine name as in the ``factory-config.yml``. * ```` is the image name as in the ``factory-config.yml``. -How to avoid using packages depending on the license +How to Avoid Using Packages Depending on the License ---------------------------------------------------- -When using FoundriesFactory with hardware configured with secure boot, depending -on the use case, it might be necessary to avoid installing packages under certain -licenses. +When using FoundriesFactory with hardware configured with secure boot, it may be necessary to avoid installing packages under certain licenses. -One example is GPLv3 which requires that hardware restrictions not limit or -disallow variations of the software from being executed on the hardware. When -using secure boot, the hardware is configured only to execute a complete boot -and run unmodified software signed with a private key. +For example, GPLv3 requires that hardware restrictions *not limit or disallow variations of the software from being executed on the hardware*. +When using secure boot, the hardware is configured only to execute a complete boot and run unmodified software signed with a private key. -.. warning:: There are other examples on why a license should be avoided or - chosen. Advice from a lawyer is recommended. +.. warning:: There are other examples on why a license should be avoided or chosen. Advice from a lawyer is recommended. -.. note:: Another option to meet the GPLv3 requirement when using a hardware - configured with secure boot is to provide a way to disable secure boot or to - provide the keys when requested. +.. note:: Another option to meet the GPLv3 requirement when using hardware configured with secure boot, + is providing either a way of disabling secure boot, or the keys when requested. -When using LmP there are two variables that can be used for blocking licenses, -``INCOMPATIBLE_LICENSE`` and ``IMAGE_LICENSE_CHECKER_ROOTFS_DENYLIST`` [1]_. Both -of these variables list the licenses by SPDX identifier. +When using LmP there are two variables that can be used for blocking licenses, ``INCOMPATIBLE_LICENSE`` and ``IMAGE_LICENSE_CHECKER_ROOTFS_DENYLIST`` [1]_. +Both of these variables list the licenses by SPDX identifier. INCOMPATIBLE_LICENSE """""""""""""""""""" @@ -77,59 +63,46 @@ Add to the ``build/conf/local.conf`` or to the distro the following line [2]_: .. prompt:: text - INCOMPATIBLE_LICENSE = "GPL-3.0* LGPL-3.0* AGPL-3.0*" + INCOMPATIBLE_LICENSE = "GPL-3.0* LGPL-3.0* AGPL-3.0*" -Using this configuration to build ``lmp-factory-image`` results in the following -error: +Using this configuration to build ``lmp-factory-image`` results in the following error: .. prompt:: text - ERROR: lmp-factory-image-1.0-r0 do_rootfs: Package bash cannot be installed into the image because it has incompatible license(s): GPL-3.0+ + ERROR: lmp-factory-image-1.0-r0 do_rootfs: Package bash cannot be installed into the image because it has incompatible license(s): GPL-3.0+ -In this example, the package `bash` cannot be installed because it is licensed -under GPLv3. +In this example, the package `bash` cannot be installed because it is licensed under GPLv3. +This is the default approach from the Yocto Project. +An error is raised when a package under one of the listed licenses is used during build time. +This is true even if the package is not to be installed to the final image. -This approach is default from the Yocto Project. This raises an error when a -package under one of the listed licenses during the build time, even if the -package is not going to be installed to the final image. - -If a package is released under multi-license, this error is raised if -any of the incompatible licenses are included in the list. - -This strategy can be used when there is a need to verify build time dependencies -between packages. +If a package is released under multi-license, this error is raised if any of the incompatible licenses are included. +This strategy can be used when there is a need to verify build time dependencies between packages. IMAGE_LICENSE_CHECKER_ROOTFS_DENYLIST """"""""""""""""""""""""""""""""""""" -This variable is introduced by the ``image-license-checker`` class and, in the -same way as ``INCOMPATIBLE_LICENSE``, it lists the licenses to be avoided, by -SPDX identifier. +This variable is introduced by the ``image-license-checker`` class. +In the same way as with ``INCOMPATIBLE_LICENSE``, it lists the licenses to be avoided, by SPDX identifier. -When using this class, the package under the avoided license is built, when -brought as a dependency. When creating the rootfs, the licenses are checked and -If a package is released under multi-license, this error is raised if -any of the incompatible licenses are included in the list. +With this class, the package under the avoided license is built—when brought as a dependency. +When creating the rootfs, the licenses are checked, and if a package is under multi-license, a error is raised if any of the incompatible licenses are included. -Another important difference is that this class prevents the installation of the -avoided license package even for multi-licensed packages. +Another important difference is that this class prevents the installation of the avoided license package, even for multi-licensed packages. This class can be reviewed at `image-license-checker`_. -Add to the LmP factory customization file -``meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc`` the -following lines: +Add to the LmP Factory customization file— ``meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc`` —the following lines: .. prompt:: text - IMAGE_LICENSE_CHECKER_ROOTFS_DENYLIST = "GPL-3.0* LGPL-3.0* AGPL-3.0*" - IMAGE_LICENSE_CHECKER_NON_ROOTFS_DENYLIST = "GPL-3.0* LGPL-3.0* AGPL-3.0*" - inherit image-license-checker + IMAGE_LICENSE_CHECKER_ROOTFS_DENYLIST = "GPL-3.0* LGPL-3.0* AGPL-3.0*" + IMAGE_LICENSE_CHECKER_NON_ROOTFS_DENYLIST = "GPL-3.0* LGPL-3.0* AGPL-3.0*" + inherit image-license-checker -Using this configuration to build ``lmp-factory-image`` results in the following -error: +Using this configuration to build ``lmp-factory-image`` results in the following error: -.. prompt:: text +:: ERROR: lmp-factory-image-1.0-r0 do_rootfs: Packages have denylisted licenses: libunistring (LGPLv3+ | GPLv2), bash (GPLv3+), time (GPLv3), mc (GPLv3), @@ -140,21 +113,19 @@ error: (GPLv3+), findutils (GPLv3+), bc (GPLv3+), cpio (GPLv3), gzip (GPLv3+), ed (GPLv3+), mc-helpers-perl (GPLv3) -This error means, for image `lmp-factory-image`, a long list of packages under -GPLv3 are being installed, for example ``bash``. The goal now to clear the image -from those dependencies. +This error means, for image ``lmp-factory-image``, a long list of packages under GPLv3 are being installed, such as ``bash``. +The goal here to clear the image from those dependencies. .. _ref-remove-gplv3: -How to remove packages under GPLv3 family license +How to Remove Packages Under GPLv3 Family License ------------------------------------------------- -FoundriesFactory uses the `image-license-checker`_ approach. The only change -needed to configure the LmP to avoid using packages under GPL-3.0, LGPL-3.0 or -AGPL-3.0 license in final image. +FoundriesFactory uses the `image-license-checker`_ approach. +Only a single change is needed to avoid using packages under GPL-3.0, LGPL-3.0 or AGPL-3.0 license in final image. -Change the file ``ci-scripts/factory-config.yml`` to include the variable -``DISABLE_GPLV3: "1"`` to the branches with the goal to disable GPLv3 packages. +Change the file ``ci-scripts/factory-config.yml`` to include the variable ``DISABLE_GPLV3: "1"`` in the desired branches, +with the goal of disabling the GPLv3 packages. .. prompt:: text @@ -175,15 +146,17 @@ Change the file ``ci-scripts/factory-config.yml`` to include the variable IMAGE: mfgtool-files DISABLE_GPLV3: "0" -.. tip:: it is possible to enable or disable `DISABLE_GPLV3` on `mfgtool` - targets as shown above. +.. tip:: it is possible to enable or disable `DISABLE_GPLV3` on `mfgtool` targets, as shown above. + +This is the only change needed, the meta-layers are handled in respect to the ``DISABLE_GPLV3`` variable. + +It is important to note that when using an image different than ``lmp-factory-image``, other packages might be used. +In this case, the error message guides on which package to target. -This is the only change needed, the meta-layers are configured to react to -``DISABLE_GPLV3`` variable. +.. seealso:: + + :ref:`sbom` -It is important to note that, when using an image different than -``lmp-factory-image``, other packages might be used. In this case, the error -message guides on which package to target. .. _image-license-checker: https://github.com/foundriesio/meta-lmp/blob/main/meta-lmp-base/classes/image-license-checker.bbclass diff --git a/source/reference-manual/linux/linux-persistent-log.rst b/source/reference-manual/linux/linux-persistent-log.rst index d3c27b712..95894bbba 100644 --- a/source/reference-manual/linux/linux-persistent-log.rst +++ b/source/reference-manual/linux/linux-persistent-log.rst @@ -5,65 +5,47 @@ Persistent Log Support ====================== -By default all the system logs generated by the Linux microPlatform are -stored in a tmpfs mount point (``/var/volatile``), without persistent -support across reboots. +By default, system logs generated by the Linux® microPlatform (LmP) are stored in a tmpfs mount point (``/var/volatile``), +without persistent support across reboots. -This is done as a way to minimize the amount of write operations to the -disk (as is stored in memory), and to help reducing the amount of disk -space utilized by the system. +This is done to minimize both the number of write operations to the disk (stored in memory), and the amount of disk space used. -While storing the system log in memory can reduce the load on the disk, it -might not always be desired, specially during development, as being able to -restore the log from previous recorded boots can provide useful information -about the system. +While storing the system log in memory can reduce the load on the disk, this may not always be desired. +Especially during development, being able to restore the log from previous boots can provide useful information. -Follow the instructions below to change the default LmP behavior and enable -persistent logging support. +Follow the instructions below to enable persistent logging support. Disable OpenEmbedded VOLATILE_LOG_DIR ------------------------------------- -OpenEmbedded controls the ``/var/log`` behavior via the ``VOLATILE_LOG_DIR`` -variable, which is enabled by default. +OpenEmbedded controls the ``/var/log`` behavior via the variable ``VOLATILE_LOG_DIR``, which is enabled by default. +This links ``/var/log`` to ``/var/volatile/log`` (``/var/volatile`` is a tmpfs mount point). +When disabled, ``/var/log`` is set as a normal directory, making it persistent. -When enabled, OpenEmbedded links ``/var/log`` to ``/var/volatile/log`` -(``/var/volatile`` is a tmpfs mount point), and when disabled it sets -``/var/log`` as a normal directory, making it persistent. - -Add the following to -``meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc`` -in order to disable ``VOLATILE_LOG_DIR``:: +Add the following to ``meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc`` to disable ``VOLATILE_LOG_DIR``:: VOLATILE_LOG_DIR = "no" -Add systemd-journald-persistent to your image +Add systemd-journald-persistent to Your Image --------------------------------------------- -The recipe ``systemd-journald-persistent`` (in meta-updater) provides a default -configuration file for **systemd-journald** that enables persistent logging -support. The default configuration sets a limit to **64M**, which is safe for -most deployments. +The recipe ``systemd-journald-persistent`` (in ``meta-updater``) provides a default configuration file for ``systemd-journald``. +This enables persistent logging support. +The default limit is set at **64M**, which is safe for most deployments. -Add ``systemd-journald-persistent`` to -``meta-subscriber-overrides/recipes-samples/images/lmp-factory-image.bb`` -(or any other image used by your meta-subscriber-overrides layer), as -described at :ref:`ref-adding-packages-image`. +Add ``systemd-journald-persistent`` to ``meta-subscriber-overrides/recipes-samples/images/lmp-factory-image.bb`` (or any other image used by your meta-subscriber-overrides layer), as described in :ref:`ref-adding-packages-image`. -Optional: customize systemd-journald options +Optional: Customize systemd-journald Options -------------------------------------------- .. note:: - Special attention is required when defining your own **systemd-journald** - configuration file, as a high **SystemMaxUse** value might cause the - logging to consume a substantial amount of disk space. - -Create your own **systemd-journald** configuration file by overriding -the ``10-persistent-journal.conf`` file used by the -``systemd-journald-persistent`` recipe. + Special attention is required when defining your own ``systemd-journald`` configuration file. + A high ``SystemMaxUse`` value may cause the logging to consume a substantial amount of disk space. -At your meta-subscriber-overrides layer:: +Create your own ``systemd-journald`` configuration file by overriding ``10-persistent-journal.conf``. +This is used by the ``systemd-journald-persistent`` recipe. +Within your ``meta-subscriber-overrides`` layer:: $ cat recipes-support/systemd-journald-persistent/systemd-journald-persistent.bbappend FILESEXTRAPATHS:prepend := "${THISDIR}/files:" @@ -77,7 +59,6 @@ And:: SystemMaxFiles=10 SyncIntervalSec=60 -For the complete list of options supported by journald please check the -`journald.conf manual`_. +For the complete list of options supported by journald please check the `journald.conf manual`_. .. _journald.conf manual: https://www.freedesktop.org/software/systemd/man/journald.conf.html diff --git a/source/reference-manual/linux/linux-repo.rst b/source/reference-manual/linux/linux-repo.rst index c7c6429c0..50b520b18 100644 --- a/source/reference-manual/linux/linux-repo.rst +++ b/source/reference-manual/linux/linux-repo.rst @@ -3,31 +3,23 @@ Repo Source Control Tool ======================== -This section describes `Repo`_ and how the Linux microPlatform uses -it. If you're unfamiliar with Repo, it may make things clearer. +This section describes `Repo`_ and how the Linux® microPlatform uses it. -A Linux microPlatform build tree installation contains multiple Git -repositories, which are managed by a *manifest file* in a Repo -*manifest repository*. +A Linux microPlatform (LmP) build tree installation contains multiple Git repositories. +These are managed by a *manifest file* in a *Repo manifest repository*. -The manifest repository's name is ``lmp-manifest``. It's a Git -repository, just like any of the source code repositories. In -:ref:`ref-linux-building`, `repo init`_ is given the URL for the -manifest repository. +Your Factory's manifest repository's name is ``lmp-manifest``. +In :ref:`ref-linux-building`, `repo init`_ is given the URL for the manifest repository. -The manifest repository contains a manifest file, named -``default.xml``. This file describes the other Git repositories in -the Linux microPlatform installation, and their metadata. During -installation, `repo sync`_ is run after ``repo init``. This clones the -other repositories according to the contents of the manifest. +The manifest repository contains a manifest file, named ``default.xml``. +This file describes the other Git repositories in the Linux microPlatform installation, and their metadata. +During installation, `repo sync`_ is run after ``repo init``. +This clones the other repositories according to the contents of the manifest. Roughly speaking, the manifest file contains: -- *remotes*, which specify where Linux microPlatform repositories are - hosted. -- *projects*, which specify the Git repositories that make up the - microPlatform, along with the remotes to fetch them from, and Git - branches to check out. +- *remotes*, which specify where Linux microPlatform repositories are hosted. +- *projects*, which specify the Git repositories that make up the microPlatform, along with the remotes to fetch them from, and Git branches to check out. .. _Repo: https://gerrit.googlesource.com/git-repo/ diff --git a/source/reference-manual/linux/linux-supported.rst b/source/reference-manual/linux/linux-supported.rst index ff0e3a448..28f0f797a 100644 --- a/source/reference-manual/linux/linux-supported.rst +++ b/source/reference-manual/linux/linux-supported.rst @@ -1,21 +1,15 @@ .. _ref-linux-supported: -Supported Machines -================== +Board Machine Names +=================== -The :ref:`ref-factory-definition` (``ci-scripts.git``) contains a ``machines:`` -key value pair in the ``factory-config.yml`` file. When the value is changed, -the next build you perform by pushing to the ``lmp-manifest.git`` or -``meta-subscriber-overrides.git`` repositories will pass the updated value to -the Yocto Project's tools -and begin producing targets for the ``MACHINE`` you have set. +The :ref:`ref-factory-definition` (``ci-scripts.git``) contains a ``machines:`` key value pair in the ``factory-config.yml`` file. +The table below shows the corresponding ``MACHINE`` for a device. -.. note:: +.. warning:: + Do not change this value, as it will be declined by the FoundriesFactory® CI. + If needed, please ask a `support engineer `_. - If you are switching machines and your new machine has a different - architecture, you will need to adjust the value of ``containers.platforms`` - in your ``factory-config.yml`` accordingly, otherwise Docker containers will - continue to be built for the previous architecture. .. csv-table:: **Supported Boards** :file: ../../_static/csv/supported-boards.csv diff --git a/source/reference-manual/linux/linux-wic-installer.rst b/source/reference-manual/linux/linux-wic-installer.rst index 44240ab7c..3ec841c9d 100644 --- a/source/reference-manual/linux/linux-wic-installer.rst +++ b/source/reference-manual/linux/linux-wic-installer.rst @@ -5,13 +5,11 @@ WIC Image Installer =================== - .. note:: +.. note:: - Only EFI compatible systems are currently supported by the image - installer (e.g. intel-corei7-64, generic-arm64). + Only EFI compatible systems are currently supported by the image installer (e.g. ``intel-corei7-64``, ``generic-arm64``). -To generate a WIC based image installer, switch the default ``WKS_FILE:sota`` -definition for your target machine to ``image-efi-installer.wks``:: +To generate a WIC based image installer, switch the default ``WKS_FILE:sota`` definition for your target machine to ``image-efi-installer.wks``:: $ cat meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc # WIC-based installer for the intel-corei7-64 target @@ -20,35 +18,29 @@ definition for your target machine to ``image-efi-installer.wks``:: # WIC-based installer for the generic-arm64 target WKS_FILE:generic-arm64:sota = "image-efi-installer.wks.in" -As WIC is only capable of consuming one single WKS file (even if multiple are -defined via WKS_FILES), this will force the build system to only generate -installer images by default. +WIC is only capable of consuming a single WKS file (even if multiple are defined via ``WKS_FILES``). +Doing this forces the build system to only generate installer images. -Remove the custom ``WKS_FILE:sota`` override to restore back to the default -behavior and generate normal bootable WIC images. +Remove the custom ``WKS_FILE:sota`` override to restore the default behavior and generate normal bootable WIC images. -Testing WIC Image Installer with Qemu (x86) +Testing WIC Image Installer With QEMU (x86) ------------------------------------------- -It is possible to test the WIC image installer with Qemu, all that is -required is an additional block device with enough disk space for the -LmP rootfs image. +It is possible to test the WIC image installer with QEMU. +All that is required is an additional block device with enough disk space for the LmP rootfs image. -If running Qemu without graphics support, make sure that the default console -is set to ``ttyS0,115200``, which can be done manually in grub (by editing -the boot arguments before booting the ``install`` target) or by removing -``console=tty0`` from the image installer by changing -``lmp-factory-custom.inc``:: +If running QEMU without graphics support, make sure that the default console is set to ``ttyS0,115200``. +This can be done manually in GRUB by editing the boot arguments before booting the ``install`` target. +It can also be done by removing ``console=tty0`` from the image installer by appending ``lmp-factory-custom.inc`` with:: - $ cat meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc - APPEND:remove:intel-corei7-64 = "console=tty0" + APPEND:remove:intel-corei7-64 = "console=tty0" -Create the virtual disk device that will be used as target with ``qemu-img``:: +Create the virtual disk device that will be used as the target with ``qemu-img``:: $ qemu-img create -f raw disk.img 4G -Download ``lmp-factory-image-intel-corei7-64.wic`` and ``ovmf.secboot.qcow2`` -from your own Factory CI run, then run Qemu with the following arguments:: +Download ``lmp-factory-image-intel-corei7-64.wic`` and ``ovmf.secboot.qcow2`` from your Factory CI run. +Run QEMU with the following arguments:: $ qemu-system-x86_64 -device virtio-net-pci,netdev=net0,mac=52:54:00:12:35:02 \ -netdev user,id=net0,hostfwd=tcp::2222-:22 \ @@ -59,11 +51,9 @@ from your own Factory CI run, then run Qemu with the following arguments:: -drive if=pflash,format=qcow2,file=ovmf.secboot.qcow2 -no-reboot \ -nographic -m 1024 -serial mon:stdio -serial null -cpu host -enable-kvm -Now just follow the instructions provided by the installer in order to -install the actual LmP image into ``disk.img``. - -After completed, hit enter to stop the current Qemu execution and start it -up again, but using ``disk.img`` as the primary block device:: +Follow the instructions provided by the installer to install the LmP image into ``disk.img``. +After completed, hit enter to stop QEMU. +Restart using ``disk.img`` as the primary block device:: $ qemu-system-x86_64 -device virtio-net-pci,netdev=net0,mac=52:54:00:12:35:02 \ -netdev user,id=net0,hostfwd=tcp::2222-:22 \ @@ -74,4 +64,4 @@ up again, but using ``disk.img`` as the primary block device:: -nographic -m 1024 -serial mon:stdio -serial null -cpu host -enable-kvm .. note:: - If running qemu on a macOS (x86) host, replace ``-enable-kvm`` with ``-M accel=hvf``. + If running QEMU on a macOS (x86) host, replace ``-enable-kvm`` with ``-M accel=hvf``. diff --git a/source/reference-manual/linux/linux.rst b/source/reference-manual/linux/linux.rst index 0080f5202..9f7602d67 100644 --- a/source/reference-manual/linux/linux.rst +++ b/source/reference-manual/linux/linux.rst @@ -2,23 +2,20 @@ Linux microPlatform =================== -The Foundries.io Linux microPlatform is an extensible -software and hardware platform that makes it easier to develop, -secure, and maintain Internet-connected Linux-based embedded devices. +The Foundries.io™ Linux® microPlatform (LmP) is an extensible software and hardware platform. +The LmP makes it easier to develop, secure, and maintain Internet-connected, Linux-based embedded devices. -The Linux microPlatform is based on `OpenEmbedded`_ / `Yocto Project`_, and adds a -select set of board support package layers to enable popular -development boards. +The LmP is based on `OpenEmbedded`_ / `Yocto Project`_, +adding a select set of board support package layers to enable popular development boards. -Though the `Linux kernel`_ and software used for -any of the microPlatform builds may contain out-of-tree patches or -features, a fundamental goal is to run as close to the tip, or latest -software, as possible so that users of the Linux microPlatform can -benefit from the latest changes. +Though the `Linux kernel`_ and software used for LmP builds may contain out-of-tree patches or features, +a fundamental goal is to run as close to the latest software as possible so that you can benefit from the latest changes. -In a FoundriesFactory, the Linux microPlatform is the baseline software -stack which is meant to be extended by the user. It is open source software, -and maintained by Foundries.io on `GitHub`_. +In a Factory, the LmP is the baseline software stack, meant to be extended by you. +The LmP is open source software, and maintained by Foundries.io on `GitHub`_. + +.. seealso:: + :ref:`lmp-customization` introduces ways it can be tailored to your needs. .. toctree:: :maxdepth: 1 @@ -27,7 +24,6 @@ and maintained by Foundries.io on `GitHub`_. linux-repo development-tags linux-dev-container - linux-building linux-kernel linux-lmp-fs linux-layers @@ -37,7 +33,6 @@ and maintained by Foundries.io on `GitHub`_. linux-net-debug linux-disk-encryption linux-update - linux-extending linux-dev-mode linux-oss-compliance factory-device-reset @@ -47,5 +42,4 @@ and maintained by Foundries.io on `GitHub`_. .. _OpenEmbedded: https://www.openembedded.org/wiki/Main_Page .. _Yocto Project: https://www.yoctoproject.org .. _Linux kernel: https://www.kernel.org -.. _Docker containers: https://www.docker.com .. _GitHub: https://github.com/foundriesio diff --git a/source/reference-manual/linux/toolchain.rst b/source/reference-manual/linux/toolchain.rst index b5e0e31ed..8afb144fe 100644 --- a/source/reference-manual/linux/toolchain.rst +++ b/source/reference-manual/linux/toolchain.rst @@ -3,50 +3,43 @@ Toolchain ========= -The default toolchain used in ``openembedded-core`` is ``gcc`` but this is configurable. +The default toolchain used in ``openembedded-core`` is ``gcc``, but this is configurable. The ``clang`` toolchain is provided by ``meta-clang``, and can be set globally or per recipe. -Since version **v89**, LmP uses ``clang`` as the default compiler and ``llvm`` as the default runtime. +Since version **v89**, the LmP uses ``clang`` as the default compiler, and ``llvm`` as the default runtime. -.. prompt:: text +.. code-block:: - TOOLCHAIN ?= "clang" - RUNTIME = "llvm" + TOOLCHAIN ?= "clang" + RUNTIME = "llvm" -However, some issues exist when using clang/llvm as the default, -as some recipes are not prepared to be built with this toolchain. -To address these issues is recomendend to add a new file where these -tweeks will be made to build sucessfully. +However, some issues exist when using clang/llvm as the default. +Namely, some recipes are not prepared to be built with this toolchain. +To address this, add a new file where the tweaks to build successfully will be made. -In the public LmP layer ``meta-lmp`` we use the -``meta-lmp-base/conf/distro/include/non-clangable.inc`` -for that propuse. -Adding another ``non-clangable.inc`` on the factory layer ``meta-subscriber-overrides`` -can be a solution, where we will collect all the ``clang`` tweeks needed. +In the public LmP layer ``meta-lmp``, we use the ``meta-lmp-base/conf/distro/include/non-clangable.inc`` for that propose. +We will add another ``non-clangable.inc`` in the Factory layer ``meta-subscriber-overrides``, where we will collect all the ``clang`` tweaks needed. -This configuration can be added in the factory global configurations file -``conf/machine/include/lmp-factory-custom.inc`` +This configuration can be added in the Factory global configurations file, ``conf/machine/include/lmp-factory-custom.inc`` -.. prompt:: text +.. code-block:: - require conf/machine/include/non-clangable.inc + require conf/machine/include/non-clangable.inc -**So we will use the factory file ``conf/machine/include/non-clangable.inc``** -to customize everything ``clang`` related. +**So we will use the Factory file**, ``conf/machine/include/non-clangable.inc`` to customize everything ``clang`` related. -Changing the toolchain +Changing the Toolchain ---------------------- -To change the default values disabling the ``clang`` compiler globaly and use the ``gcc`` -we need to change the ``TOOLCHAIN`` value. +To change the default values, disable the ``clang`` compiler globally. +Instead, use ``gcc`` by changing the ``TOOLCHAIN`` value: .. prompt:: text TOOLCHAIN = "gcc" -Changing the compiler per recipe is also possible. To do that we add the -line above in a `.bbappend` for the recipe. -This can also be done in the factory, changing the file -``conf/machine/include/non-clangable.inc``, from ``meta-subscriber-overrides``. +Changing the compiler per recipe is also possible. +To do this, we add the line above in a recipe ``.bbappend``. +This can also be done in the Factory, changing the file ``conf/machine/include/non-clangable.inc``, in ``meta-subscriber-overrides``: .. prompt:: text @@ -56,10 +49,10 @@ This can also be done in the factory, changing the file Customizing the Default Toolchain --------------------------------- -When using the clang toolchain we have the ``toolchain-clang`` override that can be used -to do the customization and this will only take effect when clang is in use. -All of these customizations can be placed in the factory by changing the file -``conf/machine/include/non-clangable.inc``, from ``meta-subscriber-overrides``. +When using the clang toolchain, we have the ``toolchain-clang`` override. +This can be used to do the customization, and will only take effect when clang is in use. +All of these customizations can be placed in the Factory. +Once again, do this by changing the file ``conf/machine/include/non-clangable.inc``, in ``meta-subscriber-overrides``: .. prompt:: text diff --git a/source/user-guide/lmp-customization/index.rst b/source/user-guide/lmp-customization/index.rst new file mode 100644 index 000000000..8366eb49c --- /dev/null +++ b/source/user-guide/lmp-customization/index.rst @@ -0,0 +1,16 @@ +.. _customization: + +Customizing the LmP +=================== + +Common ways to customize the Linux® microPlatform (LmP) are covered in :ref:`lmp-customization`. + +The :ref:`ref-linux-building` guide goes over building the LmP locally from source. + +Further ways of :ref:`extending-lmp` details adding packages to an image, and adding private Git repositories over SSH. + +.. toctree:: + :maxdepth: 1 + :glob: + + * diff --git a/source/user-guide/lmp-customization/linux-building.rst b/source/user-guide/lmp-customization/linux-building.rst new file mode 100644 index 000000000..4bfbc979e --- /dev/null +++ b/source/user-guide/lmp-customization/linux-building.rst @@ -0,0 +1,189 @@ +.. highlight:: sh + +.. _ref-linux-building: + +Building From Source +==================== + +This is a guide for building the base Linux® microPlatform (LmP) from source for QEMU AARCH64 (Arm® 64). +Information specific to other targets is provided in :ref:`ref-linux-supported`. + +This guide assumes familiarity with OpenEmbedded concepts. +If you are just getting started with OpenEmbedded/the Yocto Project, it is strongly recommended to begin with the documentation provided under :ref:`ref-linux-building-ref`. + + .. important:: + + Locally built images are useful for testing and hardware enablement, but are not meant to be updated via OTA. + For OTA support we recommend creating your own Factory and using our CI system. + +.. _ref-linux-building-hw: + +Hardware Requirements +--------------------- + +You will need a x86 computer to develop on; +Linux is currently natively supported. +On macOS and Windows, see :ref:`ref-linux-dev-container` on setting up a containerized Linux build environment. + +You will also require at least 50GB of storage for a complete LmP build. + +Setup the Build Environment +--------------------------- + +On Debian-based Linux distributions, including Ubuntu, run:: + + $ sudo apt install coreutils gawk wget git diffstat unzip \ + texinfo g++ gcc-multilib build-essential chrpath socat cpio \ + openjdk-11-jre python2.7 python3 python3-pip python3-pexpect xz-utils \ + debianutils iputils-ping libsdl1.2-dev xterm libssl-dev libelf-dev \ + android-tools-fsutils ca-certificates repo whiptail + +.. note:: + + If you are running Ubuntu, make sure to enable the universe repository: + + .. code-block:: none + + sudo add-apt-repository universe + +On other Linux distributions, please check the `Yocto Project Quick Start Guide`_ for guidance. + +.. _ref-linux-building-install: + +Install the LmP +--------------- + +Download the Layers +^^^^^^^^^^^^^^^^^^^^ + +The LmP sources can be placed in any directory on your workstation, as long it provides enough disk space for the complete build. +The `Google Repo`_ tool is used to fetch Git repos at known-good revisions, and keeps them in sync. + +#. Make and enter an installation directory for the LmP:: + + mkdir lmp && cd lmp + + .. note:: + + You can also reuse an existing installation directory, or ``/build/lmp`` + if building inside the ``lmp-sdk`` container, as described at :ref:`ref-linux-dev-container`. + +#. Install update |version| using repo: + + .. parsed-literal:: + + repo init -u https://github.com/foundriesio/lmp-manifest -b |manifest_tag| + repo sync + +Setup Work Environment +^^^^^^^^^^^^^^^^^^^^^^ + +Next, set up your work environment for building the source. + +The supported ``MACHINE`` target used by this guide is ``qemuarm64-secureboot``. +For information on other hardware platforms, see:ref:`ref-linux-supported`. + +The default distribution variable, ``DISTRO``, is automatically set to ``lmp``. +This distro is provided by the `meta-lmp-base` layer (see :ref:`ref-linux-layers` for more details). + +Set up your work environment using the ``setup-environment`` script:: + + MACHINE=qemuarm64-secureboot source setup-environment [BUILDDIR] + +If ``MACHINE`` is not provided, the script will list all machines from every enabled OpenEmbedded / Yocto Project layer, and force one to be selected. + +``BUILDDIR`` is optional; if it is not specified, the script will default to ``build-lmp``. +Keep in mind that ``BUILDDIR`` must be within the ``lmp`` directory, otherwise your build will fail. + +Build the Image +^^^^^^^^^^^^^^^ + +You can build the LmP base-console image by running:: + + bitbake lmp-base-console-image + +.. note:: + + Depending on the resources available on your system, the speed of your internet connection, and other factors, the first build could take several hours. + Subsequent builds run much faster since some artifacts are cached. + +At the end of the build, your build artifacts will be found under ``deploy/images/raspberrypi3-64``. +The artifact you will use to flash your board is ``lmp-base-console-image-raspberrypi3-64.wic.gz``. + +Install the Image +^^^^^^^^^^^^^^^^^ + +If you are using QEMU, follow the procedure outlined in the :ref:`ref-rm_qemu_arm64` flashing instructions. +See :ref:`ref-linux-supported` for additional information on other targets. + +.. _ref-linux-building-ref: + +Build and Install the LmP for your Factory +------------------------------------------ + +If you are already working with a Factory, you can instead download the source code for that factory with the following steps. + +1. Make and enter an installation directory for the LmP for your ````:: + + mkdir && cd + +2. Install the ```` meta-layers using repo: + + .. parsed-literal:: + + repo init -u https://source.foundries.io/factories//lmp-manifest.git -b main -m .xml + repo sync + + The manifest ``.xml`` refers to all the LmP meta-layers and also to the ```` specific repositories as described :ref:`ref-factory-sources`. + +3. Build the image for ````: + + .. parsed-literal:: + + MACHINE= source setup-environment [BUILDDIR] + bitbake lmp-factory-image + + The variable ``MACHINE`` should be set to a supported machine. + See the current available option in :ref:`ref-linux-supported`. + + ``BUILDDIR`` is optional; in case it is not provided, the script default is ``build-lmp``. + + ``lmp-factory-image`` is the suggested default image, and can be customized with the steps from :ref:`ref-adding-packages-image`. + +It is worth remembering that the ``bitbake`` step can take a while. +At the end of the build, your build artifacts is found under ``deploy/images/``. +The artifact you use to flash your board is ``lmp-base-console-image-.wic.gz``. + +.. important:: + + The local build of your Factory is great for developing and debugging and the results can be used on the host machine or deployed to a hardware board. + However, the image created locally is not yet visible for the OTA system, and is only available for local use. + + When you push the changes to your Factory Git repos, it will trigger a new build. + You can then flash and register your device following the instructions of :ref:`gs-flash-device` and :ref:`gs-register`. + Then, you can take advantage of the OTA system. + +References +---------- + +The following reference material on OpenEmbedded and the Yocto Project is recommended for those unfamiliar. + +- `OpenEmbedded wiki`_ +- `Yocto Project main page`_ +- `Yocto Project Quick Start Guide`_ +- `Yocto Project Reference Manual`_ +- `BitBake Manual`_ + +.. _OpenEmbedded wiki: + https://www.openembedded.org/wiki/Main_Page +.. _Yocto Project main page: + https://www.yoctoproject.org/ +.. _Yocto Project Quick Start Guide: + https://docs.yoctoproject.org/kirkstone/brief-yoctoprojectqs/ +.. _Yocto Project Reference Manual: + https://docs.yoctoproject.org/kirkstone/ref-manual/ +.. _BitBake Manual: + https://docs.yoctoproject.org/bitbake/ + +.. _Google Repo: + https://source.android.com/docs/setup/create/repo diff --git a/source/reference-manual/linux/linux-extending.rst b/source/user-guide/lmp-customization/linux-extending.rst similarity index 73% rename from source/reference-manual/linux/linux-extending.rst rename to source/user-guide/lmp-customization/linux-extending.rst index c3b324667..8d25da55e 100644 --- a/source/reference-manual/linux/linux-extending.rst +++ b/source/user-guide/lmp-customization/linux-extending.rst @@ -1,3 +1,5 @@ +.. _extending-lmp: + Extending the Linux microPlatform ================================= @@ -5,21 +7,16 @@ Extending the Linux microPlatform Adding Packages to the Image ---------------------------- -The **meta-subscriber-overrides.git** repo allows you to customize the -packages included in your factory image. -Add packages to the list for ``CORE_IMAGE_BASE_INSTALL`` located in -**recipes-samples/images/lmp-factory-image.bb**. +The ``meta-subscriber-overrides.git`` repo allows you to customize the packages included in your factory image. +To do this, you add packages as a list to the variable ``CORE_IMAGE_BASE_INSTALL`` in ``recipes-samples/images/lmp-factory-image.bb``. +For a quick example let us add the ``stress-ng`` utility package to the build: -For a quick example let’s add the "stress-ng" utility package to the build.:: +.. code-block:: bash git clone https://source.foundries.io/factories//meta-subscriber-overrides.git vi meta-subscriber-overrides/recipes-samples/images/lmp-factory-image.bb -If the git clone fails with an unable to access error then check you have a -valid token in your ``.netrc`` file. You can look at -:ref:`sec-learn` for instructions. - Add "stress-ng" to the package list.:: vim \ @@ -32,22 +29,21 @@ Then:: git commit -m "add stress-ng package to device image" git push -Go and get a coffee - your Factory is generating a new image with this package. -This will take at least half an hour (and maybe longer depending on current Factory capacity). +Go and get a coffee—your Factory is generating a new image with this package. +This can take a half an hour or more. You can check the status at: - https://ci.foundries.io/projects//lmp/ + ``https://ci.foundries.io/projects//lmp/`` -Once completed, the device will reboot after the update is applied. This -behavior is customizable so that you can apply rules to determine when -devices should be restarted. Once restarted the stress-ng command will -be available. +Once completed, the device will reboot after the update is applied. +This behavior is customizable so that you can apply rules to determine when devices should be restarted. +Once restarted the stress-ng command will be available. List of Available Recipes ------------------------- -OE provides a tool_ to search layers and recipes. Remember to set the same branch -name used by the current factory version. +OE provides a tool_ to search layers and recipes. +Remember to set the same branch name used by the current factory version. .. _tool: https://layers.openembedded.org/layerindex/branch/master/layers/ @@ -55,11 +51,9 @@ name used by the current factory version. Creating a Python3 Package from PyPi ------------------------------------ There are Python packages that do not yet have a recipe for python3 in OE. -If this is the case with a desired package, use this template below to add a -new package from PyPi. +If this is the case with a desired package, use this template below to add a new package from PyPi. -Create a recipe in the **meta-subscriber-overrides.git** repository using the -following naming scheme: +Create a recipe in the **meta-subscriber-overrides.git** repository using the following naming scheme: ``recipes-devtools/python/python3-_.bb`` @@ -109,9 +103,8 @@ Update the following variables to reflect the details from the package you wish Using FEATURES to configure LmP ------------------------------- -There are three features variable we can use to control and configure the build -system: ``DISTRO_FEATURES``, ``IMAGE_FEATURES`` and ``MACHINE_FEATURES``. Each -one of them takes effect in one aspect of the build system. +There are three features variable we can use to control and configure the build system: ``DISTRO_FEATURES``, ``IMAGE_FEATURES`` and ``MACHINE_FEATURES``. +Each one of them takes effect in one aspect of the build system. .. important:: @@ -126,22 +119,18 @@ one of them takes effect in one aspect of the build system. Make sure to understand what will be the result in case of any change. -DISTRO_FEATURES is a list of configurations from a distro that reflects how -some packages are built or installed. There is a list of `Yocto Project distro features`_ -supported. However, the list can be expanded by other meta layers. +DISTRO_FEATURES is a list of configurations from a distro that reflects how some packages are built or installed. +There is a list of `Yocto Project distro features`_ supported. +However, the list can be expanded by other meta layers. -For example, the distro feature ``systemd`` or ``wayland`` are used to define the -list of packages to be installed, and to configure how some packages build. The -distro feature ``modsign`` is used along with certificates to sign the kernel modules. +For example, the distro feature ``systemd`` or ``wayland`` are used to define the list of packages to be installed, and to configure how some packages build. +The distro feature ``modsign`` is used along with certificates to sign the kernel modules. -The default value used by LmP is defined in the ``meta-lmp/meta-lmp-base/conf/distro/include/lmp.inc`` -and can be customized by architecture, machine, or any other override. To customize -it, use ``DISTRO_FEATURES:append = `` to add a feature to the list, and -``DISTRO_FEATURES:remove = `` to remove a feature from the list. To remove -a feature from an override list, use ``DISTRO_FEATURES:remove: = ``. +The default value used by LmP is defined in the ``meta-lmp/meta-lmp-base/conf/distro/include/lmp.inc`` and can be customized by architecture, machine, or any other override. +To customize it, use ``DISTRO_FEATURES:append = `` to add a feature to the list, and ``DISTRO_FEATURES:remove = `` to remove a feature from the list. +To remove a feature from an override list, use ``DISTRO_FEATURES:remove: = ``. -The command ``bitbake-getvar`` can be used to see the value of some variables, and -all the intermediate values:: +The command ``bitbake-getvar`` can be used to see the value of some variables, and all the intermediate values:: $ bitbake-getvar DISTRO_FEATURES NOTE: Starting bitbake server... @@ -166,20 +155,16 @@ all the intermediate values:: DISTRO_FEATURES="acl argp bluetooth ext2 ipv4 ipv6 largefile usbgadget usbhost wifi xattr zeroconf pci vfat modsign efi security tpm integrity seccomp pam usrmerge virtualization ptest alsa sota systemd" -The log is generated using ``DISTRO="lmp"``. The ``DISTRO_FEATURES`` changed with -seven operations and only one of them is for an override (``tegra``). +The log is generated using ``DISTRO="lmp"``. The ``DISTRO_FEATURES`` changed with seven operations and only one of them is for an override (``tegra``). The log also shows the file path and line for each operation. The line starting with ``DISTRO_FEATURES=`` show the variable value. -The Yocto Project also provides ``IMAGE_FEATURES`` and ``MACHINE_FEATURES``, -a list of features for the image and to describe the machine. There is a list of -`Yocto Project image features`_ and `Yocto Project machine features`_ supported -by the project. +The Yocto Project also provides ``IMAGE_FEATURES`` and ``MACHINE_FEATURES``, a list of features for the image and to describe the machine. +There is a list of `Yocto Project image features`_ and `Yocto Project machine features`_ supported by the project. The LmP uses the ``MACHINE_FEATURES`` from a machine to define if a package is included. -For example, the OP-Tee package is only included in an image if the target machine -includes the feature ``optee`` in ``MACHINE_FEATURE``. +For example, the OP-Tee package is only included in an image if the target machine includes the feature ``optee`` in ``MACHINE_FEATURE``. .. _Yocto Project distro features: https://docs.yoctoproject.org/kirkstone/ref-manual/features.html#distro-features diff --git a/source/user-guide/lmp-customization/lmp-customization.rst b/source/user-guide/lmp-customization/lmp-customization.rst index 7b0615f42..a764ddc57 100644 --- a/source/user-guide/lmp-customization/lmp-customization.rst +++ b/source/user-guide/lmp-customization/lmp-customization.rst @@ -15,7 +15,7 @@ and other options related to the platform build. .. _ref-customizing-the-distro: Customizing the Distro ------------------------------ +----------------------- This section shows how to build new targets with other Distro. Following an example on how to build a new targets with :ref:`LmP XWayland `.