Pull request #186: Various small changes

Merge in ICO/coreos from various_small_changes to master

* commit 'a0910ef3ff70a53ea410ba205e36a2f5620481b3':
  chore(submodules): update third-party submodules
  feat(coreos-supportd-pkgs): create list of CoreOS supported packages
  chore(belden-coreos): move the initial timestamp to a generic file
  fix(swupdate): add libgcc as a dependency to terminate swupdate correctly
  feat(eagle40-03): strip out unused MACHINE_FEATURES for eagle40-03

.gitignore

@@ -1,2 +1,7 @@
 build/
 vscode-bitbake-build/
+documentation/_build/
+documentation/oe-logs
+documentation/oe-workdir
+__pycache__
+.venv/

.gitmodules

@@ -2,7 +2,35 @@
 	path = bitbake
 	url = ssh://git@bitbucket.gad.local:7999/ico/bitbake.git
 	branch = 2.0
-[submodule "layers/openembedded-core"]
+[submodule "openembedded-core"]
-	path = layers/openembedded-core
+	path = external-layers/openembedded-core
 	url = ssh://git@bitbucket.gad.local:7999/ico/openembedded-core.git
 	branch = kirkstone
+[submodule "meta-openembedded"]
+	path = external-layers/meta-openembedded
+	url = ssh://git@bitbucket.gad.local:7999/ico/meta-openembedded.git
+	branch = kirkstone
+[submodule "meta-virtualization"]
+	path = external-layers/meta-virtualization
+	url = ssh://git@bitbucket.gad.local:7999/ico/meta-virtualization.git
+	branch = kirkstone
+[submodule "meta-efibootguard"]
+	path = external-layers/meta-efibootguard
+	url = ssh://git@bitbucket.gad.local:7999/ico/meta-efibootguard.git
+	branch = master
+[submodule "meta-swupdate"]
+	path = external-layers/meta-swupdate
+	url = ssh://git@bitbucket.gad.local:7999/ico/meta-swupdate.git
+	branch = kirkstone
+[submodule "meta-arm"]
+	path = external-layers/meta-arm
+	url = ssh://git@bitbucket.gad.local:7999/ico/meta-arm.git
+	branch = kirkstone
+[submodule "meta-ti"]
+	path = external-layers/meta-ti
+	url = ssh://git@bitbucket.gad.local:7999/ico/meta-ti.git
+	branch = kirkstone
+[submodule "meta-lts-kernel-mixin"]
+	path = external-layers/meta-lts-kernel-mixin
+	url = ssh://git@bitbucket.gad.local:7999/ico/meta-lts-mixins.git
+	branch = coreos/kirkstone/kernel

.vscode/extensions.json

@@ -0,0 +1,10 @@
+{
+    "recommendations": [
+        "ms-vscode.makefile-tools",
+        "timonwong.shellcheck",
+        "kweihmann.oelint-vscode",
+        "lextudio.restructuredtext",
+        "trond-snekvik.simple-rst",
+        "yocto-project.yocto-bitbake"
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,47 @@
+{
+    "files.watcherExclude": {
+        "**/build/**": true,
+        "**/_build/**": true,
+    },
+    "search.exclude": {
+        "**/build/**": true,
+        "**/_build/**": true,
+    },
+    "C_Cpp.files.exclude": {
+        "**/build": true,
+        "**/_build": true,
+    },
+    "python.analysis.exclude": [
+        "**/build/**",
+        "**/_build/**",
+    ],
+    "python.formatting.provider": "black",
+    "editor.rulers": [80,100,120],
+    "bitbake.pathToBuildFolder": "${workspaceFolder}/build",
+    "bitbake.pathToEnvScript": "${workspaceFolder}/coreos-init-build-env",
+    "bitbake.pathToBitbakeFolder": "${workspaceFolder}/bitbake",
+    "python.autoComplete.extraPaths": [
+        "${workspaceFolder}/bitbake/lib",
+        "${workspaceFolder}/meta/lib"
+    ],
+    "python.analysis.extraPaths": [
+        "${workspaceFolder}/bitbake/lib",
+        "${workspaceFolder}/meta/lib"
+    ],
+    "[python]": {
+        "diffEditor.ignoreTrimWhitespace": false,
+        "gitlens.codeLens.symbolScopes": [
+            "!Module"
+        ],
+        "editor.formatOnType": true,
+        "editor.wordBasedSuggestions": "off",
+        "files.trimTrailingWhitespace": false
+    },
+    "[shellscript]": {
+        "files.eol": "\n",
+        "files.trimTrailingWhitespace": false
+    },
+    "bitbake.sdkImage": "coreos-image-minimal",
+    "bitbake.workingDirectory": "${workspaceFolder}",
+    "task.saveBeforeRun": "always",
+}

bitbake

@@ -1 +1 @@
-Subproject commit ac576d6fad6bba0cfea931883f25264ea83747ca
+Subproject commit 40fd5f4eef7460ca67f32cfce8e229e67e1ff607

coreos-init-build-env

@@ -0,0 +1,94 @@
+#!/bin/sh
+
+# This script is used to setup the OE Build Envrionment
+# Normally this is called as '. ./core-init-build-env <builddir>'
+
+# Configuration variables
+# ------------------------------------------------------------------------------
+# We only set default value, so all configuration variable can be overriden
+# if already set when sourcing this script
+
+# On some shell, we can get the path of this script when sources. Otherwise we
+# use the current directory as a fallback
+if [ -z "$COREOS_ROOT" ]; then
+    if [ -n "$BASH_SOURCE" ]; then
+        COREOS_ROOT=$(dirname "$BASH_SOURCE")
+    elif [ -n "$ZSH_NAME" ]; then
+        COREOS_ROOT=$(dirname "$0")
+    else
+        COREOS_ROOT="$(pwd)"
+    fi
+fi
+
+# Get a non relative path to the root directory
+COREOS_ROOT=$(readlink -f "${COREOS_ROOT}")
+
+# Set the path to bitbake, openembedded-core and the template directory
+# All theses values can be overriden by the caller of coreos-init-build-env
+BITBAKEDIR="${BITBAKEDIR:-${COREOS_ROOT}/bitbake}"
+OEROOT="${OEROOT:-${COREOS_ROOT}/external-layers/openembedded-core}"
+TEMPLATECONF="${TEMPLATECONF:-${COREOS_ROOT}/templates}"
+
+# Sanity checks
+# ------------------------------------------------------------------------------
+
+# BITBAKEDIR, OEROOT, TEMPLATECONF and COREOS_ROOT can be overridden by our user
+# so let's check that they have valid value
+
+if [ ! -f "${COREOS_ROOT}/coreos-init-build-env" ]; then
+    echo "Error: COREOS_ROOT ($COREOS_ROOT) isn't valid" >&2
+    echo "If you are using CoreOS directly, try using this script from CoreOS root directory." >&2
+    echo "If you are embedding coreos-init-build-env in another script, set COREOS_ROOT correctly there." >&2
+    return 1
+fi
+
+if [ ! -d "$TEMPLATECONF" ]; then
+    echo "Error: TEMPLATECONF (${TEMPLATECONF}) doesn't exist!" >&2
+    echo "Please check your TEMPLATECONF configuration." >&2
+    return 1
+fi
+
+if [ ! -f "${BITBAKEDIR}/bin/bitbake" ]; then
+    echo "Error: BITBAKEDIR (${BITBAKEDIR}) isn't valid!" >&2
+    echo "Please ensure all git submodule are fetched." >&2
+    echo "And check your BITBAKEDIR configuration." >&2
+    return 1
+fi
+
+if [ ! -f "${OEROOT}/oe-init-build-env" ]; then
+    echo "Error: OEROOT (${OEROOT}) isn't valid!" >&2
+    echo "Please ensure all git submodule are fetched." >&2
+    echo "And check your OEROOT configuration." >&2
+    return 1
+fi
+
+# Build environmnet setup
+# ------------------------------------------------------------------------------
+
+# Call the oe-init-build-env scripts of openembedded-core
+. "${OEROOT}/oe-init-build-env" "${1:-$COREOS_ROOT/build}"
+
+# Add the first argument of the function to the path
+coreos_path_add() {
+    # Make sure our paths are at the beginning of $PATH
+    # Remove any existences of $1 from $PATH
+    PATH=$(echo "$PATH" | sed -re "s#(^|:)$1(:|$)#\2#g;s#^:##")
+
+    # Add $1 to the PATH
+    PATH="$1:$PATH"
+    export PATH
+}
+
+coreos_path_add "${COREOS_ROOT}/scripts"
+
+# Add support for ##COREOS_LAYERSDIR## inside of bblayer template
+coreos-bblayers-envsub COREOS_LAYERSDIR "${COREOS_ROOT}/layers"
+
+# Add support for ##COREOS_EXTLAYERSDIR## inside of bblayer template
+coreos-bblayers-envsub COREOS_EXTLAYERSDIR "${COREOS_ROOT}/external-layers"
+
+# Generate the ${BUILDDIR}/key directory. The scripts doesn't generate anything
+# if the directory already exist so it's safe to call it everytime
+# stdout is redirected to reduce the amount of output but not stderr
+#
+#Note: if a final build is detected all the dev keys are deleted

documentation/.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+    "recommendations": [
+        "ms-vscode.makefile-tools",
+        "lextudio.restructuredtext",
+        "trond-snekvik.simple-rst"
+    ]
+}

documentation/.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+    "files.watcherExclude": {
+        "**/_build/**": true,
+    },
+    "python.formatting.provider": "black",
+    "editor.rulers": [
+        80,
+        100,
+        120
+    ],
+    "esbonio.sphinx.confDir": ""
+}

documentation/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

documentation/_static/css/coreos.css

@@ -0,0 +1,6 @@
+
+/* Make tables more convenient by wrapping line instead of using an
+   horizontal scrollbar */
+.wy-table-responsive table td, .wy-table-responsive table th {
+    white-space: normal;
+}

documentation/best_practices/cmake.rst

@@ -0,0 +1,101 @@
+***************************
+CMake with Bitbake recipes
+***************************
+
+Example of using CMake with Bitbake recipes. 
+
+Please find the example here:
+`CMake Yocto Example <https://bitbucket.gad.local/projects/ICO/repos/coreos/browse/layers/meta-belden-coreos-demo/recipes-demo/cmake-demo/cmake-demo_0.1.bb>`_.
+
+.. warning::
+   This simple example has the code in the same repo as the recipe. However, it is recommended to have the code in a separate git repo.
+   To use remote git repo, it's necessary to have settings as follows:
+   
+   * SRC_URI = "git://github.com/<link to your repo>"
+   * S="${WORKDIR}/git
+
+
+BitBake recipe
+===============
+
+Bitbake recipe inherits the cmake class and then ``CMakeLists.txt`` file can be used for building and installing.
+``CMakeLists.txt`` is expected at top of the sources tree pointed by ``SRC_URI``. 
+Usually this file is fetched using git or by downloading a tarball (.tar.gz).
+If this file is created locally it should be placed somewhere in path (usually ``<Package Name>/files``). Files that are going to be used in 
+package need to be included using ``SRC_URI +=``, files need to be included with paths relative to files directory.
+Installation of generated files can also be done using native CMake install command (which is recommended), 
+but in case something specific is needed, developer can override CMake installation with a BitBake ``do_install`` function.
+
+.. warning::
+   When using CMake for installation of some files, and using Bitbake recipe 
+   for installing other files. Bitbake's ``do_install`` will override the CMake 
+   installation, therefore, one should use ``do_install:append``.
+
+
+
+``CMakeLists.txt`` file
+========================
+When building binaries and libraries in the same package, it's a good idea to keep ``CMakeLists.txt`` 
+files split up over all source directories with top ``CMakeLists.txt`` to keep common info:
+
+* ``cmake_minimum_required`` - Defines minimum version of CMake required for desired build. Please check what version is supported by installed Yocto.
+* ``project`` - Defines project name and version.
+* ``add_subdirectory`` - If the package uses multiple ``CMakeLists.txt`` files, their directories should be included using this command.
+
+optional: ``set(CMAKE_VERBOSE_MAKEFILE ON)`` - can be used for debugging
+
+
+
+Helloworld - Simple binary example
+===================================
+
+This method shows a simple "Hello world" program written in C, 
+that uses CMake for building and installing the binary in Yocto.
+
+Additional information about this topic can be found in official 
+documentation: :external:ref:`Yocto Project - CMake
+<ref-classes-cmake>`. 
+
+
+
+CMake file - explanation
+-------------------------
+``CMakeLists.txt`` inherits top ``CMakeLists.txt``, so only minimal information is defined in this file:
+
+* ``add_executable`` - Creating binary file
+* ``install`` - Installing binary file
+
+
+
+
+Hello service - Simple binary is started in systemd
+====================================================
+
+A simple service that starts binary on boot is created. Service 
+file is installed using Bitbake method, as using CMake can be 
+avoided in this case (no need to build).
+
+
+
+
+Libdemo - Simple library example
+=================================
+
+Demo library with one function is built and installed using CMake.
+An include file is also installed.
+
+Further information about building different types of libraries can 
+be found on official CMake page: :external:ref:`Yocto Project Library documentation 
+<dev-manual/common-tasks:working with libraries>`.
+
+
+
+CMake file - explanation
+-------------------------
+
+``CMakeLists.txt`` inherits top ``CMakeLists.txt``, but this ``CMakeLists.txt`` is somewhat different compared to Helloworld:
+
+* ``add_library`` - declare the library target.
+* ``set_target_properties`` - define different properties that are useful for creating library (e.g. defining include files)
+* ``set_target_properties`` - installing files to desired locations
+

documentation/best_practices/index.rst

@@ -0,0 +1,13 @@
+
+==============================
+Belden CoreOS Best Practices
+==============================
+
+|
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+
+   overview
+   cmake

documentation/best_practices/overview.rst

@@ -0,0 +1,6 @@
+************************
+Best Practices Overview
+************************
+
+To ease the support and developement of CoreOS on multiple plateform,
+some examples were made to show developers good practices when working with yocto.

documentation/boot/bootflow-generic.dot

@@ -0,0 +1,9 @@
+digraph G {
+    fw [label = "Firmware";shape = rect;];
+    
+    btl [label = "Bootloader";shape = rect;];
+    
+    os [label = "Operating System";shape = rect;];
+    
+    fw -> btl -> os;
+}

documentation/boot/bootflow-uboot.dot

@@ -0,0 +1,11 @@
+digraph G {
+    rom [label = "CPU Rom Code";shape = rect;];
+    
+    uboot [label = "u-boot with EFI/EBBR support";shape = rect;];
+    
+    btl [label = "EFIBootGuard";shape = rect;];
+
+    kernel [label = "OS (EFI Stub + Kernel + Initramfs";shape = rect;];
+    
+    rom -> uboot -> btl -> kernel;
+}

documentation/boot/index.rst

@@ -0,0 +1,14 @@
+
+==============================
+Belden CoreOS Boot Concepts
+==============================
+
+|
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+
+   overview
+   uboot
+   secure-boot

documentation/boot/overview.rst

@@ -0,0 +1,116 @@
+******************
+Boot Flow Overview
+******************
+
+To ease the support and developement of CoreOS on multiple plateform,
+we use the same boot flow mechanisums on all our supported machine.
+
+Glossary
+========
+
+In this document, the following terms have specific meanings:
+
+.. glossary::
+
+    Firmware
+      Program that implement the boot and runtime services as defined by the
+      :ext+uefi:ref:`UEFI specifications <maincontent>`.
+
+    Application
+      Program written according to the UEFI specification that can be started 
+      by the firmware. See :ext:ref:`UEFI Applications <uefi-applications>`.
+    
+    Bootloader
+      Application that allow to start other application based on user selection,
+      configuration or autodetection.
+    
+    Operating system
+      Application that include at least the Linux Kernel and the initial RAM
+      disk.
+
+
+Generic Boot Flow
+=================
+
+.. graphviz:: bootflow-generic.dot
+
+CoreOS use a standardized workflow: the firmware can start either an
+optional bootloader or an operating system as an UEFI application.
+
+Firmware
+========
+
+CoreOS support two different use case:
+
+Using a CoreOS provided firmware
+--------------------------------
+
+The most common use case is to use a firmware image provided by CoreOS as part
+of the board support package.
+
+Currently, the CoreOS provided firmware functionality is provided by `u-boot`
+
+Using CoreOS on third party machine
+-----------------------------------
+
+As the interface between the firmware and the rest of the system is clearly
+defined, we also support to run CoreOS on top of any standard UEFI complient
+system. 
+
+As an example, this is the case when using a CoreOS image inside a virtual
+machine.
+
+Firmware requirements
+---------------------
+
+.. warning::
+
+  CoreOS support at the moment only hardware that contains a block storage
+  device (SD Card, eMMC, ...) formatted with GPT. MBR disk or MTD device are
+  not supported.
+
+ARM32 / AArch32 based machine
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The firmware for ARM32 should implement a subset of the UEFI specification, as
+defined by the EBBR Specification. As this architecure is used on old hardware,
+it's ok to use the part of the specification that are marked as deprecated or
+legacy.
+
+We require the firmware to provide a DeviceTree based system description and not
+an ACPI based table (as allowed by the specification).
+
+We also require the firmware to implement the UEFI Secure Boot functionality.
+
+ARM64 / AArch64 based machine
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The firmware for ARM64 should implement a subset of the UEFI specification, as
+defined by the EBBR Specification.
+
+We require the firmware to provide a DeviceTree based system description and not
+an ACPI based table (as allowed by the specification). The DeviceTree provided
+by the firmware can be very minimal as it can be replaced at boot time
+by a device-tree contained inside the Operating System Image.
+
+We also require the firmware to implement the UEFI Secure Boot functionality.
+
+
+AMD64 / x86_64 based machine
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The firmware for AMD64 should implement the UEFI specification.
+
+Bootloader
+==========
+
+CoreOS only support `efibootguard` as bootloader. The usage of the bootloader
+is mandated.
+
+
+Operating system
+================
+
+The operating system image is an UEFI application that contain the kernel. It's
+a Unified Kernel Image generated by tools from the EFIBootGuard project.
+

documentation/boot/secure-boot.rst

@@ -0,0 +1,268 @@
+*******************
+Secure Boot Concept
+*******************
+
+Currently CoreOS provide a Proof Of Concept of some of the secure boot element that we want to 
+implement a full secure-boot solution based on UEFI secure boot.
+
+The current proof of concept is structured as follows:
+
+Hardware Requirements
+=====================
+   
+   - The device must have an `eMMC`.
+   - The architecture of the device must be either `ARM32` or `AARCH64`.
+
+
+eMMC Embedded MultiMediaCard
+============================
+
+eMMC, or Embedded MultiMediaCard, represents a prevalent storage format in devices such as 
+smartphones, tablets, and other embedded systems. It encapsulates NAND flash memory and a dedicated
+controller within one package. This structure not only eases integration for device manufacturers
+but also ensures a compact, efficient storage medium.
+
+Within eMMC's architecture, distinct hardware partitions cater to diverse operational demands:
+
+.. graphviz::
+
+    digraph emmcStructure {
+        rankdir=TB;
+        node [shape=box, style=filled, fillcolor="#e6f2ff"];
+        edge [color="#0099cc", fontsize=12];
+
+        compound=true;
+
+        subgraph cluster_eMMC {
+            label="eMMC";
+            color="#0099cc";
+
+            Boot0 [label="Boot0"];
+            Boot1 [label="Boot1"];
+            RPMB [label="RPMB"];
+
+            subgraph cluster_User {
+                label="User";
+                color="#00cc99";
+                GPT [label="GPT Table"];
+
+                subgraph cluster_GPT {
+                    label="Software Partitions (GPT)";
+                    color="#99e6e6";
+
+                    SoftwarePartition1 [label="Partition 1"];
+                    SoftwarePartition2 [label="Partition 2"];
+                    SoftwarePartitionN [label="Partition N"];
+                }
+            }
+        }
+    }
+
+
+#. **Boot0 and Boot1**: The boot partitions cater to device start-up requirements, typically hosting
+   the firmware. Boot0 predominantly initiates the boot-up, while Boot1 stands as a secondary guard 
+   or backup, ensuring booting is resilient and failsafe.
+
+#. **RPMB (Replay Protected Memory Block)**: As a secure partition, RPMB shelters data against
+   potential tampering. It's tailored for sensitive information storage, such as cryptographic keys.
+   Its design counters data replays or rollbacks, fortifying against particular attack types.
+
+#. **User**: The primary storage domain, the User partition accommodates the OS, applications,
+   and user-centric data. It's reminiscent of the primary storage drive in larger computing devices.
+   Importantly, the User partition has a layered structure. Using the GPT (GUID Partition Table), it
+   is further divided into multiple software partitions, which can house diverse datasets or file
+   systems.
+
+The boot concept of CoreOS rely on the presence of an eMMC to implement the following feature:
+
+- Storage of two copy of the firmware with a way to switch from a copy to another using the eMMC
+  boot0 and boot1 hardware partition
+- Storage of keys used by the UEFI Secure Key specification inside the secure RPMB hardware
+  partition.
+- Storage of the bootloader, kernel and rootfs inside the user hardware partition using multiple
+  software partition in the GPT format.
+
+Firmware
+========
+
+The firmware of the device should implement a subset of the UEFI specification as defined in the
+ARM Base Boot Requirements (EBBR) and should implement the optional UEFI Secure Boot part of the
+EBBR specifications.
+
+This is done in CoreOS by levering the built-in EBBR and UEFI Secure Boot present into the u-boot
+project.
+
+The hardware should verify the validity of the firmware using a hardware specific way. Then the
+generic secure boot concept explained here can be used to valide all the following component of
+CoreOS.
+
+UEFI Key used by UEFI Secure Boot
+=================================
+
+
+- **PK (Platform Key)**: This top-tier key shoulders the responsibility of KEK verification and its
+  potential revocation. PK holders have the exclusive privilege to configure the KEK and the `db`
+  database. It's the gatekeeper ensuring only authorized software can touch the firmware or
+  bootloader.
+
+- **KEK (Key Exchange Key)**: As a medium for data exchange, the KEK is pivotal for signing the `db`
+  and `dbx` databases.
+  
+- **db (Allowed Database)**: This is the white list. It houses the keys or hashes of permitted
+  firmware and OS loaders. Execution is only granted to software with a signature that resonates
+  with the keys/hashes in this database.
+  
+- **dbx (Forbidden Database)**: The black sheep are here. Housing keys or hashes of known
+  unauthorized software, it ensures any associated software is prohibited from executing.
+
+Currently all theses public keys are built-in into u-boot at build time and are read only. In the
+future we will use the OP-TEE support into u-boot to use OP-TEE to manage the keys.
+
+OP-TEE and RPMB as key manager
+==============================
+
+OP-TEE, or Open Portable Trusted Execution Environment, is an open-source implementation of the
+Trusted Execution Environment (TEE) designed for ARM-powered platforms. In essence, a TEE is a
+secure enclave that provides a separated, isolated environment where specific applications and their
+data can run independently from the regular operating system, ensuring they are protected against
+potential tampering or unauthorized access.
+
+OP-TEE guarantees confidentiality, integrity, and authenticity for critical applications by
+executing them in this secure space. It offers a wide range of security features, including secure
+storage of cryptographic keys, secure boot, and hardware-backed crypto operations.
+
+In the context of UEFI secure boot, OP-TEE becomes instrumental. UEFI's secure boot mechanism
+ensures that only trusted, signed firmware, OS loaders, and OS kernels are executed during the boot
+process. To enforce this level of trust, UEFI relies on a set of cryptographic keys, including PK
+(Platform Key), KEK (Key Exchange Key), and db/dbx (allowed and forbidden signature databases).
+Safeguarding these keys is paramount to maintain the security and integrity of the boot process.
+
+By leveraging OP-TEE, these UEFI secure boot keys can be securely stored in the RPMB (Replay
+Protected Memory Block) partition of the eMMC. The RPMB is a write-protected, secure area of the
+eMMC designed to hold sensitive data and protect it against tampering and replay attacks.
+Since OP-TEE manages secure access to the RPMB partition, it ensures that the UEFI secure boot keys
+are not only safely stored but are also accessible only by authorized firmware components.
+
+eMMC User Partition
+===================
+
+The user partition of the eMMC must be structured using the GPT (GUID Partition Table) format.
+
+Within the GPT-formatted user partition, specific partitions should be established for efficient
+booting and system operation:
+
+1. **EFI**: This is the Essential Firmware Interface partition. It holds the `efibootguard`
+   os-loader binary, responsible for the boot sequence's initial steps and the kernel's selection
+   based on its configuration. This binary is signed with a key present in the `dbx` database
+
+2. **EBG0 - Efibootguard Config 0**: This partition houses the `efibootguard` configuration for the
+   first kernel option. Alongside the configuration file, it also contains a Unified Kernel Image
+   (UKI), a bundled package comprising the Linux kernel, device trees, and associated boot
+   components. The UKI is signed with a key present in the `dbx` database
+
+3. **EBG1 - Efibootguard Config 1**: Similar to EBG0, this partition carries the `efibootguard`
+   configuration for the second kernel option. It too holds a Unified Kernel Image tailored for this
+   alternate boot choice.
+
+4. **rootfs0**: This partition stores the CoreOS root filesystem designed to complement and operate
+   with the kernel embedded in the EBG0 partition. It provides the essential system files and 
+   structures required for the operating system's functioning when the kernel from EBG0 is booted. 
+   Integrety of this rootfs is assured by storing an hash of the rootfs inside the UKI image.
+
+5. **rootfs1**: Analogous to `rootfs0`, this partition houses the CoreOS root filesystem tailored
+   for the kernel within the EBG1 partition. It ensures that, should the system boot from the kernel
+   in EBG1, the appropriate file structures and system components are readily available.
+
+EFIBootGuard Configuration
+==========================
+
+Efibootguard, as a part of its design, employs a configuration system to determine the appropriate
+kernel and associated resources to boot from. This configuration is stored in distinct partitions, 
+EBG0 and EBG1, each holding its configuration file.
+
+The configuration file itself comprises several fields, but most crucially, it contains a revision
+field. This field is a numerical identifier indicating the version or update level of the contained
+kernel and resources. When the system initiates its boot sequence, Efibootguard assesses the
+revision values in both the EBG0 and EBG1 configuration files.
+
+The selection process is straightforward yet robust: Efibootguard chooses the partition with the
+higher revision value. By doing so, it inherently opts for the most recent or updated kernel version
+available. However, this system also supports failover mechanisms. In case the kernel in the
+partition with the higher revision encounters issues during boot, Efibootguard can revert to the
+other partition, ensuring resilience and continuity in system operations.
+
+Moreover, the choice isn't rigidly fixed. When the system undergoes updates, the configuration files
+can be rewritten, and the revision values adjusted, allowing for dynamic and flexible booting in
+line with system evolutions and updates. In essence, Efibootguard, with its configuration-based
+approach, ensures a blend of up-to-date system booting and built-in fail-safes for dependable
+operation.
+
+Unified Kernel Image
+====================
+
+After having choosen the right configuration file, Efibootguard takes on the responsibility of
+launching the Unified Kernel Image (UKI) linked with the active configuration. This image bundle
+together essential boot components like the Linux kernel, device trees, and the kernel command
+line. The secure initiation of this image is paramount, and Efibootguard ensures this by leveraging
+UEFI's start_image system call.
+
+The UEFI start_image system call  verifies the image's signature against the Secure Boot keys
+(PK, KEK, db, and potentially dbx). If the signature matches, indicating that the image is trusted
+and hasn't been tampered with, the image is permitted to execute. If not, the booting halts,
+preventing any unauthorized or potentially malicious code from running.
+
+Once the UKI has been securely initiated, it undertakes multiple tasks. It first extracts the
+necessary components from the bundled package, identifying and utilizing the appropriate device
+trees based on `compatible` node, by matching with the `compatible` node of the `device-tree` that
+is built into the firmware. These device trees inform the system about the hardware configuration,
+ensuring the kernel interacts correctly with the system's components. 
+
+The UKI os-launcher also has CoreOS specialized patches, enabling dynamic rootfs switching without
+requiring an initramfs by changing the `root=` part of the kernel command line at run time to
+point to the right rootfs partition.
+
+RootFS and dm-verity
+====================
+
+dm-verity is a Linux kernel feature designed to provide transparent integrity checking of block
+devices, particularly for read-only file systems. Rooted in cryptographic principles, dm-verity
+employs a hash-based approach to ensure and validate the integrity of the root filesystem (rootfs).
+
+The way dm-verity operates is by building a Merkle tree, a structure where each leaf node contains a
+hash of a block of the underlying data, while each non-leaf node is a hash of its children. The
+topmost node, the root of the Merkle tree, provides a cumulative hash representing the entirety of
+the data. This top hash, known as the root hash, serves as a concise, cryptographic representation
+of the entire filesystem's state.
+
+When integrating dm-verity with the Unified Kernel Image (UKI), an additional layer of security is
+established. By embedding the root hash into the signed UKI, any tampering or modification in the
+rootfs can be swiftly detected. When the system boots, the UKI, being signed, ensures that the
+embedded root hash is legitimate and untampered. As the OS accesses the rootfs, dm-verity
+recalculates the hash values in real-time and compares them to the values in the original Merkle
+tree, referenced by the embedded root hash.
+
+If any discrepancies are found – that is, if the recalculated hash doesn't match the stored value –
+it indicates potential tampering, and the OS can halt access or take appropriate measures. 
+
+.. graphviz::
+
+    digraph SecureBootFlow {
+        rankdir=TB;
+
+        node [shape=box, style=filled, fillcolor="#e6f2ff"];
+        edge [color="#0099cc", fontsize=12];
+
+        Hardware [label="Hardware\n(ARM32/AARCH64 with eMMC)"];
+        Firmware [label="u-boot Firmware\n(UEFI EBRR subset)"];
+        eMMCConfig [label="eMMC Configuration\n(GPT with EFI partition)"];
+        EFIBootGuard [label="EFIBootGuard\n(A/B Kernel Switching)"];
+        UnifiedKernel [label="Unified Kernel Image\n(Kernel, cmd line, DTB)"];
+        KernelAndRootFS [label="Kernel & RootFS\n(dm-verity validation)"];
+
+        Hardware -> Firmware [label="Flashed with u-boot\n+ Built-in keys"];
+        Firmware -> eMMCConfig [label="eMMC boot"];
+        eMMCConfig -> EFIBootGuard [label="Boots from EFI partition"];
+        EFIBootGuard -> UnifiedKernel [label="Selects kernel A/B"];
+        UnifiedKernel -> KernelAndRootFS [label="Kernel boot\n+ RootFS verification"];
+
+    }

documentation/boot/uboot.rst

@@ -0,0 +1,46 @@
+************************
+Using U-Boot as Firmware
+************************
+
+U-boot can be configured to support the EBBR specification. This can be
+enabled by enabling both `CONFIG_EFI_LOADER` and
+`CONFIG_EFI_EBBR_2_0_CONFORMANCE`.
+
+As UEFI Secure Boot is optional in EBBR, that has to be activated seperatly with
+`CONFIG_EFI_SECURE_BOOT`
+
+.. graphviz:: bootflow-uboot.dot
+
+UEFI Secure Boot
+================
+
+CoreOS build system bundle all the needed public key for secure boot inside the
+u-boot binary at buildtime. UEFI variables needed by secure boot are not allowed
+to be changed at runtime.
+
+Device tree handling
+====================
+
+As per the EBBR specification, the firmware is responsible to provide a
+device tree to the kernel. Not that it's OK to export the device tree used by
+U-Boot internally as it will be replaced by a propper device tree at a later
+stage. This avoid the need to load the device tree from a boot partition.
+
+Features to implement per machine
+=================================
+
+The u-boot provided by CoreOS should implement the following features for each
+supported machine:
+
+extension_board_scan
+--------------------
+
+The extension_board_scan function has to be implemented. This function should
+return the list of add-ons board detected.
+
+DT Fixup
+--------
+
+U-Boot can create, modify and remove node from the device tree dynamically
+before starting the kernel. This can be used to pass dynamic information stored
+inside a "board descriptor" eeprom or CPLD to the Kernel.

documentation/components/core/efibootguard.rst

@@ -0,0 +1,104 @@
+.. index:: EFIBOOTGUARD
+
+Bootloader: EFIBootGuard
+************************
+
+CoreOS use `EFIBootGuard <https://github.com/siemens/efibootguard>`_ as a
+bootloader. EFIBootGuard is the components responsible to find and load the
+right Unified Kernel Image (UKI).
+
+Installation
+------------
+
+EFIBootGuard is an UEFI application. It's installed inside the EFI System
+Partition at:
+
+.. list-table::
+   :widths: 25 25
+   :header-rows: 1
+
+   * - Platform Architecture
+     - Path
+   * - ARM32
+     - /EFI/BOOT/bootarm.efi
+   * - ARM64
+     - /EFI/BOOT/bootaa64.efi
+   * - x86_64
+     - /EFI/BOOT/bootax64.efi
+
+Workflow
+--------
+
+Configuration lookup
+~~~~~~~~~~~~~~~~~~~~
+
+When started, EFIBootGuard will scan all vFAT partition to list all the valid 
+boot partition.
+
+A valid boot partition is a vFAT partition that contain a valid BGENV.DAT file.
+
+This file contains the following parameters:
+
+- Path to a Kernel file
+- Parameter to pass to the kernel
+- Flag for in progress update
+- Update Status (OK, INSTALLED, TESTING, FAILED)
+- Watchdog timeout
+- Revision numbers
+- User data (not used)
+
+Consistency of the configuration is guaranteed by a CRC check.
+
+.. hint::
+   CoreOS use a signed Unified Kernel Image that embed the parameters to pass
+   to the Linux Kernel. Parameters from the UKI always override parameters
+   set inside the EFIBootGuard configuration file.
+
+   This is a security measure to ensure that only a signed kernel parameters is
+   used (secure boot).
+
+Booting
+~~~~~~~
+
+EFIBootGuard will try to load a kernel using the parameters from the
+configuration with the higher revision number.
+
+Update Handling
+~~~~~~~~~~~~~~~
+
+Before booting, EFIBootGuard will check the state flags inside the configuration
+file.
+
+If it's OK it means that it's a valid configuration.
+
+If the state is INSTALLED, it's mean that a new image was flash but was never
+booted. EFIBootGuard will change the state to TESTING then boot the kernel.
+
+If the state is TESTING, it's mean that the kernel was already booted one time,
+but the running system has not marked the update as working. EFIBootGuard will
+set the status to FAILED and set the revision number to 0 and boot another 
+configuration.
+
+.. hint::
+   To mark the update as working from a running system, you can use the
+   following command::
+
+    bg_setenv --confirm
+
+   This should be done after an update to tell the bootloader that the new
+   system image is working. CoreOS doesn't do it automatically for now.
+
+Known Issues
+------------
+
+.. list-table::
+   :widths: 15 85
+   :header-rows: 1
+
+   * - Bugs
+     - Description
+   * - `#370558 <https://tp.gad.local/entity/370558>`_
+     - On machine use a Marvel CN913x CPU like the cn9130-cf-pro machine, the version
+       of U-Boot provided don't provide the UEFI api needed by EFIBootGuard to update
+       his configuration file at boot time. EFIBootGuard is not able to detect
+       a failed update.

documentation/components/core/index.rst

@@ -0,0 +1,15 @@
+
+======================
+CoreOS Core Components
+======================
+
+|
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+
+   Firmware: U-Boot <u-boot>
+   Bootloader: EFIBootGuard <efibootguard>
+   Kernel: Unified Kernel Image <kernel>
+   Init System: SystemD <systemd>

documentation/components/core/kernel.rst

@@ -0,0 +1,27 @@
+.. index:: UKI
+
+Kernel: Unified Kernel Image
+*****************************
+
+CoreOS use by default a `Unified Kernel Image (UKI) <https://github.com/siemens/efibootguard/blob/master/docs/UNIFIED-KERNEL.md>`_
+generated by tools from the EFIBootGuard project.
+
+An UKI is a EFI app that load in memory multiple artifacts needed by the Linux
+Kernel before loading and booting the Linux Kernel itself:
+
+* The kernel commands line is always loaded from the UKI
+* A device-tree file: UKI can contain multiple UKI and will load the one
+  matching the device-tree file passed by the firmware. 
+
+Known Issues and unimplemented feature
+--------------------------------------
+
+.. note::
+
+   Bundling an INITRD image into the UKI is not implemented yet.
+
+.. danger::
+
+   The Unified Kernel Image is signed but CoreOS currently provide no way to
+   verify the integrity of the choosed ROOTFS partition as CoreOS doesn't
+   provide an end-to-end secure boot solution yet.

documentation/components/core/systemd.rst

@@ -0,0 +1,7 @@
+.. index:: SYSTEMD
+
+Init System: SystemD
+********************
+
+`SystemD <https://www.freedesktop.org/wiki/Software/systemd/>`_ is used as
+init system in CoreOS.

documentation/components/core/u-boot.rst

@@ -0,0 +1,46 @@
+.. index:: UBOOT
+
+Firmware: U-Boot
+****************
+
+.. hint::
+   CoreOS should work with any UEFI compliant firmware. Using U-Boot is not 
+   mandatory.
+
+`U-Boot <https://u-boot.readthedocs.io/en/latest/>`_ is built by default with
+UEFI enabled and secure boot enabled. UEFI secure boot related keys are
+installed at build time and can't be changed from the U-Boot command line.
+
+Workflow
+--------
+
+U-Boot will boot the default UEFI application from the EFI System Partition.
+
+The path to the default UEFI application is architecture dependent:
+
+.. list-table::
+   :widths: 25 25
+   :header-rows: 1
+
+   * - Platform Architecture
+     - Path
+   * - ARM32
+     - /EFI/BOOT/bootarm.efi
+   * - ARM64
+     - /EFI/BOOT/bootaa64.efi
+   * - x86_64
+     - /EFI/BOOT/bootax64.efi
+
+Known Issues
+------------
+
+.. danger::
+
+   The U-Boot configuration used by CoreOS currently was not reviewed for
+   security issue and is not safe (access to u-boot command line is allowed).
+
+.. danger::
+
+   CoreOS U-Boot configuration enable UEFI Secure Boot but the U-Boot binary
+   itself is not validated. Thus we don't provide a full end-to-end secure boot
+   solution yet.

documentation/components/optional/index.rst

@@ -0,0 +1,15 @@
+
+==========================
+CoreOS Optional Components
+==========================
+
+|
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+
+   Network Manager: NetworkManager <networkmanager>
+   SSH Server: OpenSSH <openssh>
+   Container: Podman <podman>
+   CoreOS Installer <installer>

documentation/components/optional/installer.rst

@@ -0,0 +1,37 @@
+.. index:: COREOS_INSTALLER
+
+CoreOS Installer
+****************
+
+The CoreOS installer is a set of scripts running on the target and a
+corresponding bitbake image that is used into the bootstrap process of CoreOS.
+
+coreos-image-installer
+======================
+
+The CoreOS image installer results in an image contairing only a single binary
+EFI file. This EFI file includes a kernel, a device tree and an initramfs with
+all (and only) the tools needed to install CoreOS.
+
+The installer image is not automatically built in parallel of a normal image.
+This can be changed by setting `COREOS_IMAGE_GENERATE_INSTALLER` to 1 in the
+image file (as it is done for example in coreos-image-all-features.bb).
+
+The installer image build by default only a single EFI binary named
+coreos-installer-MACHINE.efi. An SDCard or USB image can be generated if
+`COREOS_INSTALLER_WKS_FILE` is set to a wks file.
+
+coreos-installer
+================
+
+The coreos-installer recipe installs scripts that are used at startup to
+automatically format the internal emmc of the device. The recipe also contains
+a swupdate configuration file to setup swupdate correctly for that use case.
+
+coreos-installer-config
+=======================
+
+The coreos-installer-config recipe installs device specific configuration file
+used by the coreos-installer. This includes the partitioner config file. Distros
+and projects based on CoreOS can change the partioning scheme or partition size
+by installing their own version of this package using a `bbappend file`.

documentation/components/optional/networkmanager.rst

@@ -0,0 +1,10 @@
+.. index:: NETWORKMANAGER
+
+Network Manager: NetworkManager
+*******************************
+
+You can add `NetworkManager <https://networkmanager.dev/>`_ to an image that
+inherit from `coreos-image` by adding::
+
+    IMAGE_FEATURES += "networkmanager"
+

documentation/components/optional/openssh.rst

@@ -0,0 +1,9 @@
+.. index:: OPENSSH
+
+SSH Server: OpenSSH
+*******************
+
+You can add an `OpenSSH <https://www.openssh.com/>`_ based ssh server to an
+image that inherit from `coreos-image` by adding::
+
+    IMAGE_FEATURES += "ssh-server"

documentation/components/optional/podman.rst

@@ -0,0 +1,9 @@
+.. index:: PODMAN
+
+Container: Podman
+*****************
+
+You can add `Podman <https://podman.io/>`_ to an image that inherit from
+`coreos-image` by adding::
+
+    IMAGE_FEATURES += "podman"

documentation/conf.py

@@ -0,0 +1,122 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Belden CoreOS'
+copyright = '2022, Belden CoreOS Team'
+author = 'CoreOS Team'
+
+# The full version, including alpha/beta/rc tags
+try:
+    git_describe = os.popen('git describe --tags --always').read().strip()
+except all:
+    git_describe = ""
+
+release = f'0.0.1 ({git_describe})'
+version = release
+
+
+# -- General configuration ---------------------------------------------------
+
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.extlinks',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.graphviz',
+]
+#    'sphinxcontrib.plantuml',
+
+
+# external links and substitutions
+extlinks = {
+    'cve': ('https://nvd.nist.gov/vuln/detail/CVE-%s', 'CVE-%s'),
+    'yocto_home': ('https://www.yoctoproject.org%s', None),
+    'yocto_wiki': ('https://wiki.yoctoproject.org/wiki%s', None),
+    'yocto_dl': ('https://downloads.yoctoproject.org%s', None),
+    'yocto_lists': ('https://lists.yoctoproject.org%s', None),
+    'yocto_bugs': ('https://bugzilla.yoctoproject.org%s', None),
+    'yocto_ab': ('https://autobuilder.yoctoproject.org%s', None),
+    'yocto_docs': ('https://docs.yoctoproject.org%s', None),
+    'yocto_git': ('https://git.yoctoproject.org%s', None),
+    'yocto_sstate': ('http://sstate.yoctoproject.org%s', None),
+    'oe_home': ('https://www.openembedded.org%s', None),
+    'oe_lists': ('https://lists.openembedded.org%s', None),
+    'oe_git': ('https://git.openembedded.org%s', None),
+    'oe_wiki': ('https://www.openembedded.org/wiki%s', None),
+    'oe_layerindex': ('https://layers.openembedded.org%s', None),
+    'oe_layer': ('https://layers.openembedded.org/layerindex/branch/master/layer%s', None),
+}
+
+bitbake_version = "2.0"
+yocto_version = "4.0.4"
+
+# Intersphinx config to use cross reference with BitBake user manual
+intersphinx_mapping = {
+    'bitbake': ('https://docs.yoctoproject.org/bitbake/' + bitbake_version, None),
+    'yocto': ('https://docs.yoctoproject.org/' + yocto_version, None),
+    'uefi': ('https://uefi.org/specs/UEFI/2.10/', None),
+    'ebbr': ('https://arm-software.github.io/ebbr/', None),
+}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'oe-workdir', 'oe-logs']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+try:
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_options = {
+        'sticky_navigation': False,
+        'collapse_navigation': False,
+        'display_version': True
+    }
+except ImportError:
+    sys.stderr.write("The Sphinx sphinx_rtd_theme HTML theme was not found.\
+    \nPlease make sure to install the sphinx_rtd_theme Python package.\n")
+    sys.exit(1)
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+html_css_files = [
+    'css/coreos.css',
+]
+
+# Hide 'Created using Sphinx' text
+html_show_sphinx = False
+
+html_logo = "_static/logo.png"

documentation/genindex.rst

@@ -0,0 +1,3 @@
+=====
+Index
+=====

documentation/hardware/beaglebone.rst

@@ -0,0 +1,61 @@
+..  _beaglebone:
+
+**********
+BeagleBone
+**********
+
+.. important::
+
+    The BeagleBone target uses an old TI AM3358 ARM 32 BIT CPU. This processor
+    of the AM335x family is used in a lot of current and legacy device at 
+    Hirschmann and NetModule. Thus we only support this target to ensure
+    that our architecture is working on older architecture too.
+
+CoreOS build instruction
+========================
+
+.. code-block:: 
+
+   MACHINE=beaglebone bitbake coreos-image-all-features
+   cd tmp/deploy/images/beaglebone
+
+.. list-table:: Image artifacts for BeagleBone
+   :widths: 25 75
+   :header-rows: 1
+
+   * - Filename
+     - Description
+   * - <IMAGE>-beaglebone.swu
+     - System image bundle used by the CoreOS installer or the CoreOS updater
+   * - <IMAGE>-beaglebone.wic.xz
+     - System image for SDCard
+   * - coreos-image-installer-beaglebone.wic.xz
+     - CoreOS installer image for SD Card
+
+.. hint:: 
+
+   Only the .swu image is need if you have already a working installation of CoreOS
+   running on the board that you want to update.
+
+CoreOS Pre-installation guide
+=============================
+
+If you want to use the internal emmc storage as boot target, you will need to
+flash coreos-image-installer-beaglebone.wic.xz to your SDCard using bmaptool.
+
+If you want to use the sdcard as boot target, you will need to flash
+<IMAGE>-beaglebone.wic.xz to your SDCard using bmaptool.
+
+By default the board boot on the internal emmc storage. To boot with a SDCard
+instead, you will need to push the S2 button (boot switch) while powering up the
+board.
+
+.. image:: beaglebone/beaglebone-s2-switch.png
+
+Serial access is available on the 5-pin header. See
+`this page <https://elinux.org/Beagleboard:BeagleBone_Black_Serial>`_ for
+more info on the serial connector.
+
+Now that you have the installer running, CoreOS can be installed by following
+the :ref:`generic installation manual<Installation Manual>` using the SDCard
+mehtod.

documentation/hardware/netmodule-hw34.rst

@@ -0,0 +1,126 @@
+..  _netmodule-hw34:
+
+*******************************
+NetModule HW34 (XG900 A-Sample)
+*******************************
+
+.. important::
+
+  netmodule-hw34 support is currently only available on the features branch
+  feat/netmodule-bsp
+
+.. image:: netmodule-hw34/hw34.png
+
+CoreOS build instruction
+========================
+
+.. code-block:: 
+
+   MACHINE=netmodule-hw34 bitbake coreos-image-all-features
+   cd tmp/deploy/images/netmodule-hw34
+
+.. list-table:: Image artifacts for NetModule HW32
+   :widths: 25 75
+   :header-rows: 1
+
+   * - Filename
+     - Description
+   * - <IMAGE>-netmodule-hw34.swu
+     - System image bundle used by the CoreOS installer or the CoreOS updater
+   * - coreos-installer-netmodule-hw34.efi
+     - CoreOS installer bundled in a single EFI binary
+   * - tiboot3.bin
+     - SPL Bootloader for the wakeup domain (arm32 R5 core)
+   * - tispl.bin
+     - SPL bootloader for the main domain (aarch64 main core)
+   * - u-boot.bin
+     - Third stage bootloader the main domain (aarch64 main core)
+
+.. hint:: 
+
+   Only the .swu image is need if you have already a working installation of CoreOS
+   running on the board that you want to update.
+
+CoreOS Pre-installation guide
+=============================
+
+The CoreOS installation process expect a working EFI firmware based on u-boot
+running on the board.
+
+For board that have no firmware or a defect firmware, we can provide the firmware by
+booting over USB.
+
+First, we need to put the board in USB Boot mode by modifying the dip-switch
+on the back of the board:
+
+.. code-block::
+
+            ON
+      S500  ▄ ▀ ▄ ▀ ▄ ▄ ▄ ▄
+            1 2 3 4 5 6 7 8
+
+.. hint::
+
+  Unflashed board or board without a valid tiboot3.bin image will default to
+  USB boot mode, so settings the dip-switch may be skipped in this case.
+
+Then you need to populate the jumper X600 near the USB port:
+
+.. image:: netmodule-hw34/hw34-usb-device.png
+
+Then power-up the board by first apply 12V throug the main connector, then
+connect a USB-C cable. Console access to the board can be accessed using the
+serial port on the main connector.
+
+
+.. important:: 
+
+   When removing the power, ensure that the USB cable is removed first. Otherwise
+   the processor will not get shutdown properly
+
+
+Now you should see the board from you computer:
+
+.. code-block:: sh
+
+   lsusb | grep DFU
+   Bus 003 Device 048: ID 0451:6165 Texas Instruments, Inc. AM64x DFU
+
+Now we start downloading the bootloaders into RAM by using dfu-utils:
+
+.. code-block:: sh
+
+   dfu-util -D tiboot3.bin -a 0
+   dfu-util -D tispl.bin -a 0
+
+   # Eject and start execution of tispl
+   dfu-util -e -a 0
+   dfu-util -D u-boot.img -a 1
+
+   # Eject ans tart of u-boot.img
+   dfu-util -e -a 1
+
+.. hint::
+
+    The firmware was uploaded to the RAM, thus will not survice a reboot.
+    
+
+Now that we have a firmware running, CoreOS can be installed by following
+the :ref:`generic installation manual<Installation Manual>`.
+
+
+CoreOS Post-Installation
+========================
+
+When the installation of CoreOS is done, power down the board by first
+removing the USB-C cable then the main power.
+
+Now, put the board back in emmc boot mode:
+
+.. code-block::
+
+            ON
+      S500  ▀ ▄ ▄ ▀ ▄ ▄ ▄ ▄
+            1 2 3 4 5 6 7 8
+
+Then power-up the board again and CoreOS should boot.

documentation/hardware/overview.rst

@@ -0,0 +1,33 @@
+******************
+Supported Hardware
+******************
+
+..  _Hardware Overview:
+.. list-table:: Supported BitBake MACHINE
+   :widths: 25 75 25
+   :header-rows: 1
+
+   * - BitBake MACHINE
+     - Compatible hardware
+     - Documentation
+   * - cn9131-bldn-mbv
+     - Falcon A3 Sample
+     - 
+   * - netmodule-hw34
+     - NetModule HW34 (XG900 Sample)
+     - :ref:`🔗 links <netmodule-hw34>`
+   * - cn9130-cf-pro
+     - Solidrun cn9130-cf-pro
+     - 
+   * - beaglebone
+     - Beaglebone, Beaglebone Black, Beaglebone Green
+     - :ref:`🔗 links <beaglebone>`
+   * - vm-x64
+     - Virtual Machine
+     - 
+
+.. hint:: 
+
+   Please contact the CoreOS team when starting a new project based on CoreOS
+   or want to contribute the hardware support for an existing Hardware.
+

documentation/index.rst

@@ -0,0 +1,60 @@
+.. Belden CoreOS documentation master file, created by
+   sphinx-quickstart on Fri Sep 30 08:54:14 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Belden CoreOS's documentation!
+=========================================
+
+.. image:: _static/logo2.png
+  :alt: CoreOS Logo
+
+CoreOS is a Linux distribution based on OpenEmbedded-Core.
+
+The CoreOS's documentation complement the :external:ref:`Yocto Project
+Documentation <index:Welcome to the Yocto Project Documentation>` and use the
+same structures.
+
+|
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Introduction and Overview
+
+   Quick Build <quick-build>
+   Features Showcase <showcase/index>
+   Setting up a CoreOS based distro <using-coreos>
+   Building and using a Container Image <using-container>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Supported Hardware
+
+   Overview <hardware/overview>
+   NetModule HW34 (XG900 Sample) <hardware/netmodule-hw34>
+   BeagleBone <hardware/beaglebone>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Manuals
+
+   Installation Manual <installation/index>
+   Reference Manual <ref-manual/index>
+   Testing Manual <testing/index>
+   Boot Concepts <boot/index>
+   Best Practices <best_practices/index>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Software Components
+
+   Core Components <components/core/index>
+   Optional Components <components/optional/index>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Indexes
+   :hidden:
+
+   Releases <migration-guides/index>
+   Glossary <genindex>

documentation/installation/index.rst

@@ -0,0 +1,22 @@
+
+.. _Installation Manual:
+
+======================================
+Belden CoreOS EMMC Installation Manual
+======================================
+
+.. important:: 
+
+    This manual expect that the board you want to install CoreOS on have a
+    running UEFI firmware based on u-boot. Information about how to get console
+    access and a running firmware can be found for your hardware in the
+    :ref:`Hardware Overview <Hardware Overview>`
+
+|
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+
+   starting
+   partitionning

documentation/installation/partitionning.rst

@@ -0,0 +1,50 @@
+************
+Installation
+************
+
+The installer automatically creates all the needed partitions when starting up.
+
+Now you have to upload the .swu file to start the flashing process.
+
+Choose one of these methods to upload the system image to the installer:
+
+Upload the .swu file over the network using a browser
+=====================================================
+
+
+Now you can install the desired CoreOS version by uploading the desired
+.swu file to the board using a browser, by going to http://<TARGET_IP>:8080
+
+Upload the .swu file over the network using devtool
+===================================================
+
+If you have a working build environement, you can upload the image using
+the devtool command:
+
+.. code-block::
+
+    MACHINE=<MACHINE> devtool swupdate-www-push <IMAGE> <TARGET_IP>
+
+
+.. hint:: 
+    Replace <IMAGE> with the image recipe name, eg: coreos-image-all-features
+    Replace <MACHINE> by the machine name (if not set in local.conf)
+    Replace <TARGET_IP> by the IP adress of the board
+
+Upload the .swu file over the network using coreos-device
+=========================================================
+
+If you don't have a working build environement, you can upload the image using
+the coreos-device python script:
+
+.. code-block::
+
+    ./coreos-device swupdate-www-push <SWU_PATH> <TARGET_IP>
+
+.. hint:: 
+    Replace <SWU_PATH> with the the path to the SWU, eg: ./coreos-image-all-features-<MACHINE>.swu
+    Replace <TARGET_IP> by the IP adress of the board
+
+.. hint::
+    You will find the coreos-device script under the scripts directory inside
+    the CoreOS repository.

documentation/installation/starting.rst

@@ -0,0 +1,64 @@
+**********************
+Starting the installer
+**********************
+
+Choose one of these methods to start the bootloader:
+
+Starting the installer over the network with TFTP
+=================================================
+
+Put the coreos-installer EFI bundle (coreos-installer-<MACHINE>.efi) into an
+accessible TFTP server, then enter the following command into u-boot:
+
+.. code-block::
+
+   setenv ipaddr <TARGET_IP>; setenv serverip <SERVER_IP>;
+   tftp $loadaddr coreos-installer-<MACHINE>.efi
+   bootefi $loadaddr
+
+.. hint:: 
+
+    Replace <TARGET_IP> by a valid IP adress for the target, eg: 192.168.1.1
+    Replace <SERVER_IP> by the IP adress of the server, eg: 192.168.1.254
+    Replace <MACHINE> by the name of the machine set in bitbake
+
+Starting the installer over the network with DHCP/BOOTP/TFTP
+============================================================
+
+Use a DHCP/BOOTP/TFTP server to configure automatically the device. You can
+use dnsmasq for this task.
+
+
+.. code-block: ini
+
+    interface=<INTERFACE>
+    
+    dhcp-range=<INTERFACE>,10.237.30.2,10.237.30.100,4h
+    dhcp-range=<INTERFACE>,10.237.40.2,10.237.40.100,4h
+    
+    enable-tftp
+    dhcp-boot=tag:<INTERFACE>,coreos-installer-<MACHINE>.efi
+    tftp-root=/var/lib/tftpboot
+
+.. hint:: 
+
+    Replace <INTERFACE> by the name of the network interface that is connected
+    to the target. Eg: enp3s0
+    Replace <MACHINE> by the name of the machine set in bitbake
+
+Put the coreos-installer EFI bundle (coreos-installer-<MACHINE>.efi) into the
+/var/lib/tftpboot folder then enter the following command into u-boot:
+
+.. code-block::
+
+   setenv autoload yes
+   setenv autostart no
+   dhcp
+   bootefi $loadaddr
+
+Starting the installer using an SD Card
+=======================================
+
+Flash the coreos-image-installer.wic.xz into an SDCard and put the board
+in SDCard boot mode. Insert the SDCard and power up the board. The CoreOS
+installer should start automatically.

documentation/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

documentation/migration-guides/index.rst

@@ -0,0 +1,14 @@
+====================
+ Release Information
+====================
+
+|
+
+Each document in this chapter provides release notes and information about how
+to move to one release of the CoreOS Project from the previous one.
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+
+   release-master

documentation/migration-guides/release-master.rst

@@ -0,0 +1,8 @@
+Master branch
+=============
+
+The master branch of CoreOS is based on the `kirkstone` branch of
+OpenEmbedded-Core.
+
+More info about this release of OpenEmbedded-Core can be found in the
+:external:ref:`upstream documentation <migration-guides/migration-4.0:Release 4.0 (kirkstone)>`

documentation/quick-build.rst

@@ -0,0 +1,172 @@
+*******************
+Core OS Quick Build
+*******************
+
+Welcome!
+########
+
+This short document will help you generate your first image for any device
+supported by CoreOS. If you are familiar with Yocto, this chapiter was
+inspired and is structured in the same way as the `Yocto Project Quick Build
+documentation <https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html>`_.
+
+Compatible Build Machine
+########################
+
+Building a whole operating system from scratch takes a long time and requires
+a powerful build machine.
+
+We recommend to have at least:
+
+* A modern CPU with at least 6-cores (Intel i7 9th generation or equivalent)
+* A fast SSD for the operating system
+* 32GB of RAM
+
+Optionally, for better performance you should use a separate SSD used only by
+the Yocto build system.
+
+Compatible Linux Distribution
+#############################
+
+At this moment, the CoreOS system is only tested on `Debian 11` build
+machines and it's the recommended operating system for new user. This
+documentation assumes that you have a machine running natively with it.
+
+Before starting, you should ensure that you have at least 250GB of free disk
+space.
+
+Package needed on the build machine
+###################################
+
+Theses packages are needed on your build machine:
+
+.. code-block:: sh
+
+   ~$ sudo apt install gawk wget git diffstat unzip texinfo gcc build-essential \
+      chrpath socat cpio python3 python3-pip python3-pexpect xz-utils \
+      debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa \
+      libsdl1.2-dev pylint3 xterm python3-subunit mesa-common-dev zstd \
+      liblz4-tool bmap-tools efitools openssl sbsigntool python3-click \
+      python3-aiohttp
+
+Use Git to clone CoreOS
+########################
+
+.. hint::
+
+   If you read this documentation, you probably already have an account on
+   `BitBucket <bitbucket.gad.local>`_ and you can access `the core-os repository
+   <https://bitbucket.gad.local/projects/ICO/repos/coreos/browse>`_. Otherwise you should
+   ask the person who sent you a copy of this document.
+
+To clone the repository, you have to add an SSH key to your BitBucket account via
+`the BitBucket SSH Key configuration page <https://bitbucket.gad.local/plugins/servlet/ssh/account/keys>`_
+first.
+
+.. code-block:: sh
+
+   ~$ git clone --recurse-submodules ssh://git@bitbucket.gad.local:7999/ico/coreos.git
+   ~$ cd coreos
+
+Building an image
+#################
+
+Before building an image, we have to first configure the build.
+
+To create a build folder with our default configuration, you can run the
+`coreos-init-build-env` script:
+
+.. code-block:: sh
+
+   ~/core-os$ source coreos-init-build-env
+
+.. note::
+
+    The inilization script has created a `build` directory inside the `core-os` directory and
+    copied some default configuration in the `build/conf` folder. The current working directory
+    was changed and we are now inside `~/coreos/build`
+
+You can open the `build/conf/local.conf` file to change the build configuration. You probably
+want to change the current `MACHINE` to one that is compatible with the hardware that you want
+to build an image for.
+
+Now that you have configured the build, we can build an `image`. Building an `image` will
+generate a bootable disk image that can be used to boot the system. This document assume that
+the machine is set to `cn9130-cf-pro` but you can use any other MACHINE listed in local.conf.
+
+.. hint::
+
+    If you use another machine that `cn9130-cf-pro`, you will have to replace each
+    occurrences of `cn9130-cf-pro` to your machine when executing a command.
+
+For an image that contains a lot of developer tools, the best image to build
+is `coreos-image-all-features`.
+
+.. code-block:: sh
+
+   ~/img-build/build$ bitbake coreos-image-all-features
+
+After a long time, the build system will return. You can list all the artifacts
+produced by `bitbake` using `ls`:
+
+.. code-block:: sh
+
+   ~/coreos/build$ ls tmp/deploy/images/*/
+
+A lot of file was generated, but the file that you can flash to your SD Card can
+be found with this command:
+
+.. code-block:: sh
+
+   ~/coreos/build$ find tmp/deploy/images/${MACHINE} -type l -name "*.wic.xz"
+   tmp/deploy/images/cn9130-cf-pro/coreos-image-all-features-cn9130-cf-pro.wic.xz
+
+.. hint::
+
+   Note that `bitbake` generates a lof of symlinks so that the same file can be
+   accessed using multiple filenames.
+
+Flashing an image to a SD Card
+##############################
+
+.. warning::
+
+   Flashing an image to the wrong disk can remove all your file
+
+The safest way to get the name of your SD card disk is to first run this
+command before inserting the SD Card into your computer:
+
+.. code-block:: sh
+
+   ~/coreos/build$ lsblk | grep disk | grep mmc
+
+This command should return nothing. If it does, do not use any of the disk name
+listed.
+
+Now insert the SD card in your computer and rerun the same command:
+
+.. code-block:: sh
+
+   ~/coreos/build$ lsblk | grep disk | grep mmc
+   mmcblk0            179:0    0  14.8G  0 disk
+
+You should have a single line printed. The name of your SD card device is the
+first word printed, here `mmcblk0`. If you have multiple printed, take the name
+from the single line that was not present the first time you have run the
+command.
+
+.. hint::
+
+   If you are unsure, you can also check that the disk size match the one of
+   your SD Card. I have inserted a 16GB sdcard, and the command report a size of
+   of 14.8G, so this is a match. The command report the size in GiB, you can use
+   google to convert GiB to GB, just search "14.8GiB in GB" and expect some
+   rounding error.
+
+Now, flash the image file to the your card:
+
+.. code-block:: sh
+
+   ~/coreos/build$ bmaptool copy tmp/deploy/images/cn9130-cf-pro/coreos-image-all-features-cn9130-cf-pro.wic.xz /dev/<DISKNAME>
+
+You have to replace `<DISKNAME>` by the name of your SD Card device.

documentation/ref-manual/classes.rst

@@ -0,0 +1,71 @@
+*******
+Classes
+*******
+
+This chapter document the classes that are provided by Belden CoreOS. Classes
+provided by OpenEmbedded-Core are documented in the
+:external:doc:`Yocto Reference Manual <ref-manual/classes>`.
+
+.. _ref-classes-coreos-efi-secureboot:
+.. index:: coreos-efi-secureboot.bbclass
+
+
+``coreos-efi-secureboot.bbclass``
+=================================
+
+The ``coreos-efi-secureboot`` class is a class made to be inherited in a global
+configuration file. On the CoreOS distribution, this class is inherited inside
+the CoreOS distrubtion configuration file.
+
+This class define the location of the Secure Boot keys directory and regroup
+in one file all settings that are related to both secure boot and the machine
+configuration.
+
+.. _ref-classes-coreos-efi-sbsign:
+.. index:: coreos-efi-sbsign.bbclass
+
+``coreos-efi-sbsign.bbclass``
+=================================
+
+The ``coreos-efi-sbsign`` class provide helpers functions to sign an EFI
+application. 
+
+
+.. _ref-classes-coreos-metadata-scm:
+.. index:: coreos_metadata_scm.bbclass
+
+``coreos_metadata_scm.bbclass``
+===============================
+
+The ``coreos_metadata_scm`` class is used inside the CoreOS distribution
+configuration file to set the variables ``COREOS_METADATA_BRANCH`` and
+``COREOS_METADATA_REVISION`` to the current Git branch and revision of the main
+CoreOS repository.
+
+The ``coreos_metadata_scm`` is automatically inherited if ``DISTRO`` is set to
+``belden-coreos`` or to any distro based on ``belden-coreos``.
+
+.. _ref-classes-coreos-image:
+.. index:: coreos-image.bbclass
+
+``coreos-image.bbclass``
+========================
+
+The ``coreos-image`` class provides common definitions for the
+``coreos-image-*`` image recipes, such as support for additional
+:extern:ref:`IMAGE_FEATURE <ref-features-image>`.
+
+.. _ref-classes-coreos-sanity:
+.. index:: coreos-sanity.class
+
+``coreos-sanity.bbclass``
+=========================
+
+The ``coreos-sanity`` class is inherited inside the CoreOS layer
+configuration file to add some sanity checks. Theses check ensure that the 
+policies of CoreOS are followed.
+
+Currently, this add check to ensure:
+  - that the distro is based on CoreOS
+  - that SystemD is used as ``INIT_MANAGER``
+  - that glibc is used as the default C library

documentation/ref-manual/distro.rst

@@ -0,0 +1,54 @@
+.. index:: DISTRO
+
+******
+Distro
+******
+
+The CoreOS layer provide the following :term:`DISTRO`:
+
+.. _ref-distro-belden-coreos:
+.. index:: belden-coreos.conf
+
+``belden-coreos.conf``
+==================================
+
+This distro is the base distribution of the CoreOS project.
+
+This distro is automatically selected in the default ``build/conf/local.conf``
+created by the ``oe-init-build-env`` script. It is set in this file as follow::
+
+    DISTRO ?= "belden-coreos"
+
+This distribution is similar to Poky, the reference distribution of the Yocto
+Project. But with some change:
+
+
+:term:`SANITY_TESTED_DISTROS` is set to Debian 11, as it's the only host 
+operating system supported.
+
+The init system was changed to `SystemD` by setting `INIT_MANAGER` to
+`systemd`.
+
+Theses default :external:ref:`DISTRO_FEATURES <ref-features-distro>` are enabled:: 
+
+    bluetooth usbhost pci ipv4 ipv6 wifi multiarch usrmerge ptest
+
+.. note::
+
+    Distribution based on CoreOS must extend the CoreOS distro by having the
+    following line at the beginning of the distro configuration file::
+
+        require conf/distro/belden-coreos.conf
+
+    Example for ``conf/distro/custom-distro.conf``::
+
+        require conf/distro/belden-coreos.conf
+        DISTRO = "custom-distro"
+        DISTRO_NAME = "CustomDistro OS (Based on Belden CoreOS)"
+        MAINTAINER = "CustomDistro OS Team"
+
+    .. warning::
+
+        The ``belden-coreos`` distro define a sane set of default policies.
+        Distribution based on CoreOS can only be supported by the CoreOS team if
+        theses default policies and choices are not changed.

documentation/ref-manual/features.rst

@@ -0,0 +1,57 @@
+********
+Features
+********
+
+This chapter document the machine, distro and image feature that are specific
+to Belden CoreOS. 
+
+.. index:: MACHINE_FEATURES
+    
+Machine Features
+================
+
+:external:ref:`MACHINE_FEATURES <ref-features-machine>` of OpenEmbedded-Core
+can be used with CoreOS.
+
+In addition, those CoreOS specific MACHINE_FEATURES can be used too:
+
+-  *sdcard:* the machine as an internal SD Card or MicroSD Slot. 
+-  *emmc:* the machine as an internal emmc based storage
+
+
+.. index:: DISTRO_FEATURES
+
+Distro Features
+===============
+
+CoreOS doesn't define any custom distro feature for now, but the 
+:external:ref:`DISTRO_FEATURES <ref-features-distro>` of OpenEmbedded-Core
+can be used.
+
+.. index:: IMAGE_FEATURES
+.. _ref-features-image:
+
+Image Features
+==============
+
+Some image features are available when you inherit the
+:ref:`coreos-image <ref-classes-coreos-image>` class. The current list of
+these features is as follows:
+
+-  *hwcodecs:* Installs hardware acceleration codecs.
+-  *tools-debug:* Installs debugging tools such as ``strace`` and ``gdb``.
+-  *tools-profile:* Installs profiling tools such as ``valgrind`` and ``perf``.
+-  *ssh-server:* Installs the Dropbear minimal SSH server.
+-  *podman:*: Installs the Podman container runtime
+-  *networkmanager:* Installs the NetworkManager daemon and command line client
+-  *cockpit:* Installs the cockpit web interface
+-  *dev-tools:* Install some developer command line tools
+
+The *cockpit* and *dev-tools* feature are special, as they will automatically
+add package based on the other image feature that are enabled.
+
+:external:ref:`IMAGE_FEATURES <ref-features-image>` defined in OpenEmbedded-Core
+are also available, but note that the
+:ref:`coreos-image <ref-classes-coreos-image>` class don't inherit from the
+:external:ref:`core-image <ref-classes-core-image>` class, thus `core-image`
+specific features are not available.

documentation/ref-manual/images.rst

@@ -0,0 +1,46 @@
+******
+Images
+******
+
+The CoreOS build system provides several examples image:
+
+.. index:: coreos-image-all-features
+
+``coreos-image-all-features``
+=============================
+
+ An image with most of the optional feature of CoreOS.
+
+ .. index:: coreos-image-demo
+
+``coreos-image-demo``
+=============================
+
+ An image based on `coreos-image-all-features`` that has additional demo
+ features activated.
+
+.. index:: coreos-image-minimal
+
+``coreos-image-minimal``
+========================
+
+A small image just capable of allowing a device to boot.
+
+
+.. index:: coreos-image-minimal-dev
+
+``coreos-image-minimal-dev``
+============================
+
+A ``coreos-image-minimal`` image suitable for development work using the host.
+The image includes headers and libraries you can use in a host development
+environment.
+
+.. note::
+
+   :external:ref:`ref-manual/images:images` defined in OpenEmbedded-Core are also
+   available, but are not based on the :ref:`coreos-image
+   <ref-classes-coreos-image>` classes.
+
+   Custom image based on the :ref:`coreos-image <ref-classes-coreos-image>` classes
+   can be made in an application layers.

documentation/ref-manual/index.rst

@@ -0,0 +1,17 @@
+
+==============================
+Belden CoreOS Reference Manual
+==============================
+
+|
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+
+   classes
+   distro
+   machines
+   images
+   features
+   variables

documentation/ref-manual/machines.rst

@@ -0,0 +1,76 @@
+********
+Machines
+********
+
+The CoreOS build system provides several machines:
+
+Generic Architecture
+====================
+
+Some machines generate code that are generic over a wide range of architecture.
+
+When this is the case, the machine name end with a CoreOS specific architecture
+suffix:
+
+x64
+---
+
+The x64 suffix is used for machine that generate code that can run on any modern
+AMD64 computer. This need at least to be a Core2 Duo processor.
+
+arm32
+-----
+
+The arm32 suffix is used to generate code that is compatible with any ARM
+processor that is compatible with the ARMv7a Architecture and both the NEON
+and VFPv3-D32 extension set.
+
+arm64
+-----
+
+The arm64 suffix is used to generate code that is compatible with any ARM
+processor that is compatible with the AArch64 architecture.
+
+.. _ref-machine-vm:
+
+Virtual Machines
+================
+
+Virtual machines can be used to boot an image on any UEFI compatible virtual
+machine hypervisor. The build system generates a virtual machine disk in the 
+`.vmdk` format by default.
+
+The following virtual machines are available:
+
+- vm-x64
+
+The `vm` machine override can be used on all these machines.
+
+.. hint::
+
+    When installing using the ISO file, UEFI secure boot should be desactived.
+    After the installation, or when using the `.vmdk` file directly, it is
+    recommanded to activate the UEFI Secure Boot on the (virtual) machine
+    firmware.
+
+    Public key needed by the firmware are available on the EFI partition of the
+    image.
+
+
+.. _ref-machine-container:
+
+Containers
+==========
+
+Container machine generate an OCI archive that can be imported on tools like
+Podman or Docker. The generate archive doesn't contain a kernel, neither an
+init system.
+
+The following container machines are available:
+
+- container-x64
+- container-arm32
+- container-arm64
+
+The `container` machine override can be used on all these machines.
+

documentation/ref-manual/variables.rst

@@ -0,0 +1,54 @@
+
+******************
+Variables Glossary
+******************
+
+This chapter lists common variables used in the CoreOS build
+system and gives an overview of their function and contents.
+
+Variables provided by OpenEmbedded-Core are documented in the
+:external:doc:`Yocto Reference Manual <ref-manual/variables>`.
+
+
+.. glossary::
+    :sorted:
+
+    :term:`COREOS_ROOT`
+
+        Specifies the root directory of CoreOS.
+
+        It is an important distinction that :term:`COREOS_ROOT` points to root of
+        the Git repository of CoreOS, and not to a layer.
+
+    :term:`COREOS_METADATA_BRANCH`
+
+        The branch currently checked out for the CoreOS project (path
+        determined by :term:`COREOS_ROOT`).
+    
+    :term:`COREOS_METADATA_REVISION`
+
+        The revision currently checked out for the CoreOS project (path
+        determined by :term:`COREOS_ROOT`).
+    
+    :term:`COREOS_EFI_SECUREBOOT__KEYDIR`
+
+        Path to the directory containing the private and public key used for
+        signing and authenticating UEFI binary.
+        
+        The `coreos-init-buildenv` will automatically generate the keys in
+        `build/keys`. The default variables of `COREOS_EFI_SECUREBOOT__KEYDIR`
+        default to use this directory.
+
+    :term:`COREOS_EFI_SECUREBOOT_INSTALL_PUBKEY_IN_EFIDIR`
+
+        If the distro or the machine configuration ihnerit the
+        `coreos-efi-secureboot` class, settings this variables to `"1"` inside
+        the machine configuration will automatically install all the public key
+        needed for secure boot in the EFI partition.
+
+        This is intended to be use when using CoreOS on machine that already
+        come with a built-in EFI compliant firmware, to ease the import of 
+        the needed certificate into the firmware.
+        
+        For machine that use a CoreOS provided firmware (u-boot), the public key
+        are already shipped inside the firmware binary.

documentation/showcase/cockpit.rst

@@ -0,0 +1,89 @@
+.. _ref-cockpit:
+
+Cockpit Web Interface
+=====================
+
+The Cockpit Web Interface is an easy-to-use web based interface made to manage
+a Linux based server. It intentionally uses standard system API like `systemd`,
+`pam`, `networkmanager` making it easily integrable and interoperable on 
+any Linux operating system using these programs.
+
+.. image:: cockpit/overview.png
+
+.. important::
+
+    Providing and supporting a web management interface is out of the scope of
+    CoreOS. We provide some facilities to install this web interface as it's
+    available in `meta-openembedded` and we find it useful for developer.
+
+The Cockpit Web Interface can be installed on an image by adding `cockpit` to
+the :ref:`IMAGE_FEATURES <ref-features-image>` variable. You can then access
+the web interface on the port 9090: `https://TARGET_IP:9090`
+
+.. hint::
+    Cockpit use standard Linux authentification method. The simplest way to
+    get a login is to enable the `debug-tweak`
+    :ref:`IMAGE_FEATURES <ref-features-image>`, then login with `root` as 
+    username and an empty password.
+
+    See https://cockpit-project.org/guide/latest/authentication for more info
+
+When the `cockpit` `IMAGE_FEATURES`` is used, the following feature of are
+availabe:
+
+Dashboard
+---------
+
+The dashboard allows seeing some system statistic in real time.
+
+.. image:: cockpit/dashboard.png
+
+.. hint::
+    The statistics are not stored, so they are only available when the dashboard
+    page is open
+
+Logs Viewer
+-----------
+
+The log viewer allows seeing the log from `journalctl`.
+
+.. image:: cockpit/log.png
+
+Accounts management
+-------------------
+
+The account management allow creating and managing users. For existing user, the
+account can be locked, the password changed and SSH public key can be added.
+
+
+.. image:: cockpit/accounts.png
+
+Services management
+-------------------
+
+The services page allows managing `systemd` service. Service can be started,
+restarted, stopped, enabled or disabled. Logs related to the service can also be
+viewed easily.
+
+.. image:: cockpit/services.png
+
+Web Terminal
+------------
+
+The terminal page gives access to a web terminal, allowing to interact with the
+shell of the device.
+
+.. image:: cockpit/terminal.png
+
+Additional plugins
+------------------
+
+Additional plugin can be installed for `cockpit`, like `podman-cockpit` that
+allow to manage podman container from the cockpit web interface. When possible,
+CoreOS automatically add the corresponding `cockpit` plugin when additional
+features are added via :ref:`IMAGE_FEATURES <ref-features-image>`. 
+
+As an example, the `cockpit-podman` package is automatically installed if 
+:ref:`IMAGE_FEATURES <ref-features-image>` contains both `cockpit` and `podman`.
+
+These plugins are documented in the corresponding features showcase page.

documentation/showcase/index.rst

@@ -0,0 +1,15 @@
+
+=================
+Features Showcase
+=================
+
+|
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+   :maxdepth: 1
+
+   cockpit
+   networkmanager
+   podman

documentation/showcase/networkmanager.rst

@@ -0,0 +1,50 @@
+.. _ref-networkmanager:
+
+NetworkManager
+==============
+
+    NetworkManager is the standard Linux network configuration tool suite. It
+    supports large range of networking setups, from desktop to servers and
+    mobile and integrates well with popular desktop environments and server
+    configuration management tools.
+
+    https://networkmanager.dev/
+
+NetworkManager can be installed on an image by adding `networkmanager` to
+the :ref:`IMAGE_FEATURES <ref-features-image>` variable. This provide the 
+NetworManager daemon and the `nmcli` tools.
+
+nmtui
+-----
+
+The `nmtui` package provide a terminal user interface for NetworkManager.
+
+.. only:: html
+
+    .. image:: networkmanager/nmtui.gif
+
+.. only:: latex
+
+    .. image:: networkmanager/nmtui.png
+
+
+This package is automatically installed if both `networkmanager` and `dev-tools`
+:ref:`IMAGE_FEATURES <ref-features-image>` are enabled.
+
+cockpit-networkmanager
+----------------------
+
+The `cockpit-networkmanager` package provide a :ref:`cockpit <ref-cockpit>`
+plugin that allow to manage NetworkManager from the
+:ref:`cockpit <ref-cockpit>` web interface.
+
+.. only:: html
+
+    .. image:: networkmanager/cockpit-networkmanager.gif
+
+.. only:: latex
+
+    .. image:: networkmanager/cockpit-networkmanager.png
+
+This package is automatically installed if both `networkmanager` and `cockpit`
+:ref:`IMAGE_FEATURES <ref-features-image>` are enabled.

documentation/showcase/podman.rst

@@ -0,0 +1,64 @@
+
+Podman Container Manager
+=========================
+
+Podman is a tool to manage pods and containers. Pods come from Kubernetes, that
+define a pod this way:
+
+    A Pod (as in a pod of whales or pea pod) is a group of one or more
+    containers, with shared storage and network resources, and a specification
+    for how to run the containers.
+
+.. important::
+
+    CoreOS doesn't mandate the use of `podman` for running container.
+
+    But as we can't support every existing container runtime, `podman` is the
+    only documented/supported way to run container.
+
+    Other container runtimes are available inside the open source
+    `meta-virtualization` layer that is available inside CoreOS.
+
+Podman can be installed on an image by adding `podman` to the 
+:ref:`IMAGE_FEATURES <ref-features-image>` variable.
+
+By default, this will just provide the `podman` command. The `podman` command
+is similar to the `docker` one, and most command should work by replacing 
+`docker` by `podman`. See https://docs.podman.io/en/latest/Commands.html for
+more info.
+
+podman-tui
+----------
+
+The `podman-tui` package provide a terminal user interface for `podman`. This
+package is automatically installed if both `podman` and `dev-tools`
+:ref:`IMAGE_FEATURES <ref-features-image>` are enabled.
+
+.. only:: html
+    
+    .. image:: podman/podman-tui.gif
+
+.. only:: latex
+    
+    .. image:: podman/podman-tui.png
+
+The above image was copied from https://github.com/containers/podman-tui/blob/e29e47fd392647033dc1c0cc0eaefa1f62661b98/docs/podman-tui.gif
+
+cockpit-podman
+--------------
+
+The `cockpit-podman` package provide a :ref:`cockpit <ref-cockpit>` plugin that
+allow to manage `podman` from the :ref:`cockpit <ref-cockpit>` web interface.
+
+This package is automatically installed if both `podman` and `cockpit`
+:ref:`IMAGE_FEATURES <ref-features-image>` are enabled.
+
+
+.. only:: html
+
+    .. image:: podman/cockpit-podman.gif
+
+.. only:: latex
+
+    .. image:: podman/cockpit-podman.png
+

documentation/testing/bats.rst

@@ -0,0 +1,354 @@
+.. index:: BATS
+
+************************************
+BATS - Bash Automated Testing System
+************************************
+
+The CoreOS distribution supports writing tests using shell syntax by providing the `bats` command.
+
+If you want to use `bats`, you will need the following CoreOS packages:
+
+- bats
+- bats-file
+- bats-assert
+
+Overview of BATS
+================
+
+A BATS test can be as simple as a single .bats file. For example:
+
+.. code-block:: bash
+
+    #!/usr/bin/env bats
+   
+    bats_load_library bats-support
+    bats_load_library bats-assert
+
+    @test "can output to stdout" {
+        run echo hello
+        assert_output 'hello'
+    }
+
+You can run it using the command `bats <filename>.bats`
+
+This will give you the following output:
+
+.. code-block:: bash
+
+    sam@SAVE:~/Projects/tests$ bats <filename>.bats 
+    <filename>.bats
+    ✓ can output to stdout
+
+    1 test, 0 failures
+
+The run command
+================
+
+In shell tests, you often need to run commands and capture their output, exit
+status, and error messages. The run command provided by `bats` allows you to
+execute commands within your test cases and collect this information for later
+assertion and validation.
+
+The run command will make the following variables available:
+
+- `${status}`: exit code of the command run by `run`
+- `${output}`: combined content of `stdout` and `stderr`
+- `${lines[@]}`: array of lines of the output
+- `${BATS_RUN_COMMAND}`: command run by the `run` command
+
+.. code-block:: bash
+
+    @test "invoking foo with a nonexistent file prints an error" {
+        run foo nonexistent_filename
+        [ "$status" -eq 1 ]
+        [ "$output" = "foo: no such file 'nonexistent_filename'" ]
+        [ "$BATS_RUN_COMMAND" = "foo nonexistent_filename" ]
+
+    }
+
+The `run` command accepts some parameters:
+
+- `-N`: Expect N as exit status and fail otherwise
+- `-!`: Expect non-zero exit status and fail if the command succeeds.
+- `--keep-empty-lines`: don't remove empty lines from `${lines}`
+- `--separate-stderr`: Use separate variables for stderr `${stderr}` and `${stderr_lines[@]}`
+
+.. code-block:: bash
+
+    @test "invoking foo without arguments prints usage" {
+        run -1 foo
+        [ "${lines[0]}" = "usage: foo <filename>" ]
+    }
+
+The bats-assert helper
+======================
+
+The `bats-assert` helper provides some functions to create more readable tests.
+These assertions use the variables created by the `run` command and can be used
+as follows:
+
+.. code-block:: bash
+
+    @test 'assert_output()' {
+        run echo 'have'
+        assert_output 'want'
+    }
+
+The following functions are provided:
+
+- `assert` and `refute`: Assert that a given expression evaluates to true or false.
+- `assert_equal`: Assert that two parameters are equal.
+- `assert_not_equal`: Assert that two parameters are not equal.
+- `assert_success` and `assert_failure`: Assert that the exit status is 0 or 1.
+- `assert_output` and `refute_output`: Assert that the output does (or does not) contain the given content.
+- `assert_line` and `refute_line`: Assert that a specific line of the output does (or does not) contain the given content.
+- `assert_regex` and `refute_regex`: Assert that a parameter matches (or does not match) the given pattern.
+
+The bats-file helper
+====================
+
+The `bats-file` helper provides functions to help work with files in tests:
+
+**Test File Types:**
+
+- `assert_exists` and `assert_not_exists`: Check if a file or directory exists.
+- `assert_file_exists` and `assert_file_not_exists`: Check if a file exists.
+- `assert_dir_exists` and `assert_dir_not_exists`: Check if a directory exists.
+- `assert_link_exists` and `assert_link_not_exists`: Check if a link exists.
+- `assert_block_exists` and `assert_block_not_exists`: Check if a block special file exists.
+- `assert_character_exists` and `assert_character_not_exists`: Check if a character special file exists.
+- `assert_socket_exists` and `assert_socket_not_exists`: Check if a socket exists.
+- `assert_fifo_exists` and `assert_fifo_not_exists`: Check if a fifo special file exists.
+
+**Test File Attributes:**
+
+- `assert_file_executable` and `assert_file_not_executable`
+- `assert_file_owner` and `assert_file_not_owner`
+- `assert_file_permission` and `assert_not_file_permission`
+- `assert_file_size_equals`
+- `assert_size_zero` and `assert_size_not_zero`
+- `assert_file_group_id_set` and `assert_file_not_group_id_set`
+- `assert_file_user_id_set` and `assert_file_not_user_id_set`
+- `assert_sticky_bit` and `assert_no_sticky_bit`
+
+**Test File Content:**
+
+- `assert_file_empty` and `assert_file_not_empty`
+- `assert_file_contains` and `assert_file_not_contains`
+- `assert_symlink_to` and `assert_not_symlink_to`
+
+**Working with a temporary directory:**
+
+- `temp_make` and `temp_del`
+
+Pre- and Post-test case hooks
+==============================
+
+In some cases, it's useful to have a function that runs before or after each test
+case in a bats file.
+
+A function named `setup` will run before each test case, and a function
+named `teardown` will run after each test case.
+
+This example creates a directory in the setup function but lacks a teardown
+that removes the directory. The second time the setup function is run, the
+setup will fail as the directory already exists:
+
+.. code-block:: bash
+
+    #!/usr/bin/env bats
+
+    bats_load_library bats-support
+    bats_load_library bats-assert
+    bats_load_library bats-file
+
+    setup() {
+        mkdir tmp
+        echo 'a' >> ./tmp/test
+    }
+
+    @test "test contains a single a I" {
+        assert_file_contains ./tmp/test '^a$'
+    }
+
+    @test "test contains a single a II" {
+        assert_file_contains ./tmp/test '^a$'
+    }
+
+.. code-block:: bash
+
+    sam@SAVE:~/Projects/tests$ bats test.bats 
+    test.bats
+    ✓ test contains a single a I
+    ✗ test contains a single a II
+    (from function `setup' in test file test.bats, line 8)
+        `mkdir tmp' failed
+    mkdir: cannot create directory ‘tmp’: File exists
+
+    2 tests, 1 failure
+
+This can be easily fixed by adding a teardown function:
+
+.. code-block:: bash
+
+    #!/usr/bin/env bats
+
+    bats_load_library bats-support
+    bats_load_library bats-assert
+    bats_load_library bats-file
+
+    setup() {
+        mkdir tmp
+        echo 'a' >> ./tmp/test
+    }
+
+    teardown() {
+        rm -rf ./tmp
+    }
+
+
+
+    @test "test contains a single a I" {
+        assert_file_contains ./tmp/test '^a$'
+    }
+
+    @test "test contains a single a II" {
+        assert_file_contains ./tmp/test '^a$'
+    }
+
+.. code-block:: bash
+
+    sam@SAVE:~/Projects/tests$ bats test.bats 
+    test.bats
+     ✓ test contains a single a I
+     ✓ test contains a single a II
+
+    2 tests, 0 failures
+
+Pre- and Post-test file hooks
+=============================
+
+To run some code before executing a test file or after executing it, the
+functions `setup_file` and `teardown_file` can be used.
+
+The last example could be refactored to only create the tmp directory once:
+
+.. code-block:: bash
+
+    #!/usr/bin/env bats
+
+    bats_load_library bats-support
+    bats_load_library bats-assert
+    bats_load_library bats-file
+
+    setup_file() {
+        export DIR="./tmp"
+        export FILE="${DIR}/test"
+        mkdir "${DIR}"
+    }
+
+    teardown_file() {
+        rm -rf "${DIR}"
+    }
+
+    setup() {
+        echo 'a' >> "${FILE}"
+    }
+
+    teardown() {
+        rm "${FILE}"
+    }
+
+    @test "test contains a single a I" {
+        assert_file_contains "${FILE}" '^a$'
+    }
+
+    @test "test contains a single a II" {
+        assert_file_contains "${FILE}" '^a$'
+    }
+
+Multiple files
+==============
+
+With `bats`, a file is a test suite. If you have multiple `bats` files in a
+directory and you provide the directory in the `bats` command line, `bats`
+will execute all the test suites.
+
+Example: `bats .` 
+
+.. code-block:: bash
+
+    sam@SAVE:~/Projects/tests$ bats .
+    ./first.bats
+    ✓ can run our script
+    ✗ second test
+    (in test file ./first.bats, line 27)
+        `false' failed
+    ./second.bats
+    ✓ multi file
+    ./test.bats
+    ✓ test contains a single a I
+    ✓ test contains a single a II
+
+    5 tests, 1 failure
+
+Pre- and Post-suite hooks
+=========================
+
+If you want to execute the same function before each test suite or after
+each test suite, create a file named `setup_suite.bash`. In this file,
+create a function named `setup_suite()` and another named `teardown_suite()`.
+
+Exporting the test results
+==========================
+
+Test results can be exported using the JUnit XML format. This can then be
+used in other tools and merged with other JUnit XML formats to generate a final
+test report.
+
+Example:
+
+.. code-block:: bash
+
+    sam@SAVE:~/Projects/tests$ bats . -F junit
+
+This will produce the following XML content on stdout:
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <testsuites time="0.048">
+    <testsuite name="./first.bats" tests="2" failures="1" errors="0" skipped="0" time="0.025" timestamp="2023-08-16T14:22:15" hostname="SAVE">
+        <testcase classname="./first.bats" name="can run our script" time="0.013" />
+        <testcase classname="./first.bats" name="second test" time="0.012">
+            <failure type="failure">(in test file ./first.bats, line 27)
+    `false&#39; failed</failure>
+        </testcase>
+
+    </testsuite>
+    <testsuite name="./second.bats" tests="1" failures="0" errors="0" skipped="0" time="0.008" timestamp="2023-08-16T14:22:15" hostname="SAVE">
+        <testcase classname="./second.bats" name="multi file" time="0.008" />
+
+    </testsuite>
+    <testsuite name="./test.bats" tests="2" failures="0" errors="0" skipped="0" time="0.015" timestamp="2023-08-16T14:22:15" hostname="SAVE">
+        <testcase classname="./test.bats" name="test contains a single a I" time="0.008" />
+        <testcase classname="./test.bats" name="test contains a single a II" time="0.007" />
+
+    </testsuite>
+    </testsuites>
+
+Going further
+=============
+
+`bats` scripts can be checked with shellcheck for common mistakes.
+
+The `bats-assert` add-on provides many helper functions to perform
+assertions with a more readable syntax than the shell's built-in syntax.
+
+See https://github.com/bats-core/bats-assert
+
+The `bats-file` add-on provides helper functions to check for files. See
+https://github.com/bats-core/bats-file/
+
+You can find a list of projects using `bats` on this page:
+https://github.com/bats-core/bats-core/wiki/Projects-Using-Bats

documentation/testing/index.rst

@@ -0,0 +1,15 @@
+
+==============================
+Belden CoreOS Testing Manual
+==============================
+
+This manual is a work on progress on how to test and how to write test for
+CoreOS or CoreOS based distribution.
+
+|
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+
+   bats

documentation/using-container.rst

@@ -0,0 +1,84 @@
+************************************
+Building and Using a Container Image
+************************************
+
+Building a container image based on CoreOS is really easy. You have to set
+the machine to either of the following value in the `local.conf` file:
+
+- container-x64
+- container-arm64
+- container-arm32
+
+.. hint::
+
+    The machine can also be overwriting from the shell using
+    `MACHINE=<machine> bitbake`
+
+Then you can generate any image by running:
+
+.. code-block:: sh
+
+    $ bitbake <image>
+
+As an example, you can build the `coreos-image-minimal` as an OCI container
+for AMD64 machine with the following command:
+
+.. code-block:: sh
+
+    $ MACHINE=container-x64 bitbake coreos-image-minimal
+
+
+This will generate a container tarball in the tar.gz format.
+
+If you are using `podman`, you can import the container with:
+
+.. code-block:: sh
+
+    $ cd $BUILDDIR/tmp/deploy/images/container-x64
+    $ podman import coreos-image-container-container-x64.tar.bz2
+    Getting image source signatures
+    Copying blob 46c0b1c53d42 [--------------------------------------] 0.0b / 0.0b
+    Copying config 051856498a done  
+    Writing manifest to image destination
+    Storing signatures
+    051856498a59e0ae6349492539efaf915a33dd73e7a54ce9683b0414d1481fae
+
+Then you can use start any program included in the image with:
+
+.. code-block:: sh
+
+    $ podman run <PODMAN_ARGS> <IMAGE_ID> <COMMAND> <COMMAND_ARGS>
+
+To run an interactive shell, you can use:
+
+.. code-block:: sh
+
+    $ podman run -i <IMAGE_ID> ash --i
+    / # 
+
+The `<IMAGE_ID>` should be copied from the output of `podman import`. In this
+example, it was
+`051856498a59e0ae6349492539efaf915a33dd73e7a54ce9683b0414d1481fae`.
+
+You are now inside the container, try the following command:
+
+.. code-block:: sh
+
+    / # cat /etc/os-release
+    ID=belden-coreos
+    NAME="Belden CoreOS"
+    VERSION="0.0.1-feat/oci-image+75cf54e4b54b713d8ebeafddd122aeb615715ef9 (kirkstone)"
+    VERSION_ID=0.0.1-feat/oci-image-75cf54e4b54b713d8ebeafddd122aeb615715ef9
+    PRETTY_NAME="Belden CoreOS 0.0.1-feat/oci-image+75cf54e4b54b713d8ebeafddd122aeb615715ef9 (kirkstone)"
+    DISTRO_CODENAME="kirkstone"
+
+.. note::
+
+    Image generated using any container machines doesn't include the Linux
+    kernel neither many system component that are usually not used on a container
+    like SystemD or udev. This is done inside the machine configuration by
+    settings all the `VIRTUAL_RUNTIME_<component>` to an empty string.
+
+    Any of these system component can be added to the image if needed, by adding
+    them by their real name (instead of using any `VIRTUAL_RUNTIME_` variables)
+    in the `IMAGE_INSTALL` variables.

documentation/using-coreos.rst

@@ -0,0 +1,382 @@
+********************************
+Setting up a CoreOS based distro
+********************************
+
+This chapter explains how to setup a distro based on CoreOS.
+
+Repository structures
+#####################
+
+OpenEmbedded is a flexible tool, but we encourage each of our users to adopt
+the same structure as CoreOS. In this chapter, replace each usage of `PRODUCT`
+or `product` by a unique name related to your product.
+
+.. code-block::
+
+    product/
+    ├── build/ (ignored by git)
+    ├── documentation/
+    ├── layers/
+    |   └── coreos/ (submodule)
+    |   |   └── bitbake/ (submodule)
+    |   |   └── layers/
+    |   |   |   ├── openembedded-core (submodule)
+    |   |   |   ├── meta-belden-coreos
+    |   |   |   ├── meta-belden-coreos-bsp
+    |   |   |   └── ...
+    |   |   └── ...
+    |   ├── meta-product/
+    |   ├── meta-other-layers/
+    |   └── ...
+    ├── scripts/
+    ├── templates/
+    ├── product-init-build-env
+    ├── .gitignore
+
+Creating the structures
+#######################
+
+.. code-block:: sh
+
+    ~$  mkdir product
+    ~$  cd product
+    ~/product$ git init
+    ~/product$ git submodule init
+
+    ~/product$ mkdir layers
+    ~/product$ mkdir scripts
+
+    ~/product$ git submodule add -b <branch> ssh://git@bitbucket.gad.local:7999/ico/coreos.git layers/coreos
+    ~/product$ git submodule update --init --recursive
+
+    ~/product$ cp -r layers/coreos/templates ./templates
+    ~/product$ cp layers/coreos/.gitignore ./.gitignore
+
+    ~/product$ touch product-init-build-env
+    ~/product$ chmod +x product-init-build-env
+    ~/product$ nano product-init-build-env
+
+.. note::
+
+    By copying the .gitignore file of CoreOS, the build directory in the the product
+    repository will not be tracked by Git, which is the recommended approach as using
+    `devtool modify` modifies the local `bblayers.conf`. Instead we recommend to
+    keep the template directory up to date so that a sane configuration can be
+    created when fetching the repository for the first time.
+
+Then you can enter the following inside the product-init-build-env file:
+
+.. code-block:: sh
+
+    #!/bin/sh
+
+    # This script is used to setup the OE Build Environment
+    # Normally this is called as '. ./product-init-build-env <builddir>'
+
+    # On some shell, we can get the path of this script when sources. Otherwise we
+    # use the current directory as a fallback
+    if [ -z "$PRODUCT_ROOT" ]; then
+        if [ -n "$BASH_SOURCE" ]; then
+            PRODUCT_ROOT=$(dirname "$BASH_SOURCE")
+        elif [ -n "$ZSH_NAME" ]; then
+            PRODUCT_ROOT=$(dirname "$0")
+        else
+            PRODUCT_ROOT="$(pwd)"
+        fi
+    fi
+
+    # Get a non relative path to the root directory
+    PRODUCT_ROOT=$(readlink -f "${PRODUCT_ROOT}")
+
+    # CoreOS init settings
+    COREOS_ROOT="${PRODUCT_ROOT}/layers/coreos"
+    TEMPLATECONF="${PRODUCT_ROOT}/templates"
+
+    # Call the coreos-init-build-env scripts of CoreOS
+    . "${COREOS_ROOT}/coreos-init-build-env" "${1:-$PRODUCT_ROOT/build}"
+
+    # From here the scripts and functions defined by CoreOS and
+    # OpenEmbedded-Core are available
+
+    # Add support for ##PRODUCTS_LAYERSDIR## inside of bblayer template
+    coreos-bblayers-envsub PRODUCT_LAYERSDIR "${PRODUCT_ROOT}/layers"
+
+    # Add the scripts directory of the product to the path
+    coreos_path_add "${PRODUCT_ROOT}/scripts"
+
+Using your new project
+######################
+
+.. code-block:: sh
+
+    ~product$  source product-init-build-env
+
+Creating your product layers
+############################
+
+You can create a new layer and add it to your active bblayers.conf file like
+this:
+
+.. code-block:: sh
+
+    ~product/build$ bitbake-layers create-layer ../layers/meta-belden-bsp
+    ~product/build$ bitbake-layers add-layer ../layers/meta-product
+
+Don't forget to update your templates `projects/templates/bblayers.conf.sample`
+file. Inside this file use `##PRODUCT_LAYERSDIR##/meta-product` to have a
+machine agnostic path.
+
+Optional: Change some git settings
+##################################
+
+If you want to always `--recurse-submodules` when using `git pull`, you can
+change your `submodule.recurse` git setting, either locally or globally
+
+.. code-block:: sh
+
+    ~/product$ git config submodule.recurse true # Only inside of product repo
+    ~/product$ git config --global submodule.recurse true # Set it for all repos
+
+
+Create your own distro based on CoreOS
+######################################
+
+Create a new file inside configuration file inside
+`product/layers/meta-product/conf/distro`. For a distro named `product`, you will create
+`product/layers/meta-product/conf/distro/product.conf`.
+
+Open this file and enter the following:
+
+.. code-block:: ini
+
+    # This should come at the beginning of the file, to ensure that you use
+    # CoreOS defaults
+    require conf/distro/belden-coreos.conf
+
+    # This should always be set in your own configuration file, to not use the
+    # values of CoreOS
+    DISTRO = "product"
+    DISTRO_NAME = "Product Linux Distribution"
+    MAINTAINER = "Belden Product Team"
+
+    # You may want to add a version and a codename to your distro instead of
+    # using the version and codename of CoreOS
+    DISTRO_VERSION = "2022.05"
+    DISTRO_CODENAME = "ProductOS Summer 2022 Edition"
+
+    # Here you can override settings from the CoreOS distro or from
+    # OpenEmbedded-core. But keep in mind that the CoreOS team doesn't support
+    # all the features of OpenEmbedded-Core. We have added some checks for some
+    # of the settings that we don't allow to change or that we don't support.
+    # See the coreos-sanity.bbclass file for more info.
+
+Then you can activate the distro by setting the `DISTRO` to `product` inside
+your `product/build/conf/local.conf` file. You should also set it in the 
+`product/templates/local.conf.sample` file so that it will be set as the default
+when create the build environment for the first time.
+
+What to do next
+###############
+
+How do I...
+############
+
+...add a PRODUCT_ROOT variable usable in recipes files?
+*******************************************************
+
+Add this line inside your meta-product layer configuration file at 
+`product/layers/meta-product/conf/layer.conf`:
+
+.. code-block:: ini
+
+    # Set a variable to get to the top of the metadata location
+    PRODUCT_ROOT = '${@os.path.normpath("${LAYERDIR}/../../")}'
+
+... add PRODUCT_METADATA_BRANCH and PRODUCT_METADATA_REVISION variables to get the current git branch and git sha of the PRODUCT repository?
+*********************************************************************************************************************************************
+
+Create the file `product/layers/meta-product/classes/product_metadata_scm.bbclass`
+and copy the content of the coreos_metadata_scm.bbclass file. Replacing all
+reference to COREOS by PRODUCT should works.
+
+... start fast and easy development
+***********************************
+
+By adding `debug-tweaks` to `EXTRA_IMAGE_FEATURES` the image is made suitable
+for development. This allows for example root login with no password.
+For a complete list of the functionality that is added or removed by using
+`debug-tweaks` have a look at the official documentation.
+
+Following CoreOS specific functionality was added to `debug-tweaks`:
+
+* disables the read-only filesystem.
+
+.. warning::
+
+    This is for development only and must not be used for production images.
+
+... set a root password
+***********************
+
+If you have `debug-tweaks` set in `EXTRA_IMAGE_FEATURES` you will not be asked for
+a root password when logging in. If `debug-tweaks` is not set (should not be set in
+the final product) you cannot login with root anymore. Therefore you need to set a
+root password with:
+
+.. code-block:: ini
+
+    IMAGE_CLASSES += "extrausers"
+
+    PASSWD='\$5\$sj6q14XssP2LRRFr\$U1EcE5DS/viWXWGdK1eRseoPzX6bSe5C9kWlKUXibl.'
+    EXTRA_USERS_PARAMS = "\
+        usermod -p '${PASSWD}' root; \
+        "
+
+The password needs to be provided as a hash and can be created on the host with
+following command:
+
+.. code-block:: bash
+
+    printf "%q\n" $(mkpasswd -m sha256crypt root)
+
+.. warning::
+
+    This is for development only if you do not use `debug-tweaks`. For releases
+    this would be a real security problem.
+
+... configure a overlay filesystem
+**********************************
+
+Especially when you have a read-only filesystem you might want to have some
+directories to be writeable. This can be achieved by using a overlay filesystem.
+It is distinguished between two scenarios:
+
+1. The directory is located somewhere under `/etc`
+2. The directory is located under all other directories (except `/etc`)
+
+The main difference for directories located under `/etc` is that they are mostly
+config files that are used during the init process. However the init process
+itself usually mounts the overlay filesystem. Therefore another mechanism is
+needed which mounts the overlay before the actual init. This is solved by
+replacing the actual init with a script that mounts the overlay filesystem and
+then starts the actual init binary. But don't worry Yocto handles this for you.
+
+Following are the steps to easily add a overlay filesystem:
+
+**Overlay filesystem for directories under `/etc`**
+
+1. Create a partition (in the wic file) and specify the mount point.
+
+.. code-block:: bash
+
+    part /mnt/overlay --fstype=ext4 --rootfs-dir=${IMAGE_ROOTFS}/mnt/overlay --label overlay --align 1024 --ondisk mmcblk1 --size 128M
+
+2. Add `overlayfs-etc` to your `IMAGE_FEATURES` in the image file (e.g. coreos-image-minimal.bb)
+
+.. code-block:: bash
+
+    IMAGE_FEATURES += "overlayfs-etc"
+
+3. Provide overlay filesystem details in the machine config file (e.g. cn9130-cex7.conf)
+
+.. code-block:: bash
+
+    OVERLAYFS_ETC_MOUNT_POINT = "/mnt/overlay"
+    OVERLAYFS_ETC_DEVICE = "/dev/mmcblk1p5"
+    OVERLAYFS_ETC_FSTYPE ?= "ext4"
+
+4. Specify the directory that will be provided through the overlay filesystem in a recipe or bbappend file
+
+.. code-block:: bash
+
+    OVERLAYFS_WRITABLE_PATHS[overlay] += "/etc/ssh"
+
+More detailed information is available under the official Yocto Project
+documentation under `overlayfs-etc <https://docs.yoctoproject.org/4.0.4/ref-manual/classes.html#overlayfs-etc-bbclass>`_.
+
+**Overlay filesystem for other directories**
+
+1. Create a partition (in the wic file) and specify the mount point.
+
+.. code-block:: bash
+
+    part /mnt/overlay --fstype=ext4 --rootfs-dir=${IMAGE_ROOTFS}/mnt/overlay --label overlay --align 1024 --ondisk mmcblk1 --size 128M
+
+2. Add `overlayfs` to your `DISTRO_FEATURES` in the distro configuration file (e.g. belden-coreos.conf)
+
+.. code-block:: bash
+
+    DISTRO_FEATURES += "overlayfs"
+
+3. Specify the mount points in the machine configuration (e.g. cn9130-cex7.conf)
+
+.. code-block:: bash
+
+    OVERLAYFS_MOUNT_POINT[overlay] = "/mnt/overlay"
+
+4. Specify the directory that will be provided through the overlay filesystem in a recipe or bbappend file
+
+.. code-block:: bash
+
+    inherit overlayfs
+    OVERLAYFS_WRITABLE_PATHS[overlay] += "/etc/ssh"
+
+More detailed information is available under the official Yocto Project
+documentation under `overlayfs <https://docs.yoctoproject.org/4.0.4/ref-manual/classes.html#overlayfs-bbclass>`_.
+
+.. note::
+    The overlayfs QA check is looking for a systemd mount unit which is not
+    needed if you use wic. Therefore just disable the QA check with:
+
+    .. code-block:: bash
+
+        OVERLAYFS_QA_SKIP[overlay] = "mount-configured"
+
+Alternative repository structure
+################################
+
+It's also possible but not recommended to clone CoreOS without any submodule, to
+create a more flat structure. But then you have to ensure and manage the 
+Bitbake et OpenEmbedded-Core version by yourself.
+
+.. important::
+
+    CoreOS is only tested with the version of Bitbake and OpenEmbedded-Core used
+    in the CoreOS repository as submodule. By doing this you have to ensure that
+    you project stay in sync with CoreOS regarding CoreOS version and
+    corresponding Bitbake and OpenEmbedded-Core version.
+
+
+.. code-block::
+
+    product/
+    ├── build/ (ignored by git)
+    ├── bitbake/ (submodule)
+    ├── documentation/
+    ├── layers/
+    |   ├── openembedded-core (submodule)
+    |   └── coreos/ (cloned without submodule)
+    |   |   ├── layers/
+    |   |   |   ├── meta-belden-coreos
+    |   |   |   ├── meta-belden-coreos-bsp
+    |   |   |   └── ...
+    |   |   └── ...
+    |   ├── meta-product/
+    |   ├── meta-other-layers/
+    |   └── ...
+    ├── scripts/
+    ├── templates/
+    ├── product-init-build-env
+    ├── .gitignore
+
+Setting this structure is out of the scope for this documentation, but as a
+hint, to implement it you have to set in `product-init-build-env`:
+
+- `BITBAKEDIR` to the path of the Bitbake repository
+- `OEROOT` to the path of the OpenEmbedded-Core repository
+
+.. important::
+
+    Calling directly oe-init-build-env from OpenEmbedded-Core is not supported!
+    Ensure that your product-init-build-env call coreos-init-build-env egal if
+    you use the recommended or alternative repository structures.

external-layers/meta-arm

@@ -0,0 +1 @@
+Subproject commit d7b7b6fb6c7c5545e718e44f38853d1718ce5446

external-layers/meta-efibootguard

@@ -0,0 +1 @@
+Subproject commit e3581b11d30d91d0363acb48a6aee47043b7e0bc

external-layers/meta-lts-kernel-mixin

@@ -0,0 +1 @@
+Subproject commit 09d2f9391813674627ec53cb222da6c7a51221e6

external-layers/meta-openembedded

@@ -0,0 +1 @@
+Subproject commit 8bb16533532b6abc2eded7d9961ab2a108fd7a5b

external-layers/meta-swupdate

@@ -0,0 +1 @@
+Subproject commit 3d12b2788a45d86efcb1ad3e01f209558c54795c

external-layers/meta-ti

@@ -0,0 +1 @@
+Subproject commit bae3658ac0bc1c9adac7a882439cabb385cae720

external-layers/meta-virtualization

@@ -0,0 +1 @@
+Subproject commit cb2bc17e96552cdfc141d27bd9f4dbd95a872846

external-layers/openembedded-core

@@ -0,0 +1 @@
+Subproject commit 1b5405955c7c2579ed1f52522e2e177d0281fa33

layers/meta-belden-coreos-bsp/COPYING.MIT

@@ -0,0 +1,17 @@
+Permission is hereby granted, free of charge, to any person obtaining a copy 
+of this software and associated documentation files (the "Software"), to deal 
+in the Software without restriction, including without limitation the rights 
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
+copies of the Software, and to permit persons to whom the Software is 
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in 
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 
+THE SOFTWARE.

layers/meta-belden-coreos-bsp/README

@@ -0,0 +1,41 @@
+This README file contains information on the contents of the meta-belden-bsp layer.
+
+Please see the corresponding sections below for details.
+
+Dependencies
+============
+
+  URI: <first dependency>
+  branch: <branch name>
+
+  URI: <second dependency>
+  branch: <branch name>
+
+  .
+  .
+  .
+
+Patches
+=======
+
+Please submit any patches against the meta-belden-bsp layer to the xxxx mailing list (xxxx@zzzz.org)
+and cc: the maintainer:
+
+Maintainer: XXX YYYYYY <xxx.yyyyyy@zzzzz.com>
+
+Table of Contents
+=================
+
+  I. Adding the meta-belden-bsp layer to your build
+ II. Misc
+
+
+I. Adding the meta-belden-bsp layer to your build
+=================================================
+
+Run 'bitbake-layers add-layer meta-belden-bsp'
+
+II. Misc
+========
+
+--- replace with specific information about the meta-belden-bsp layer ---

layers/meta-belden-coreos-bsp/classes/coreos-efi-sbsign.bbclass

@@ -0,0 +1,12 @@
+# This class contains the part of coreos-efi-secureboot.bbclass that shouldn't
+# be included globally, but only on the recipes that need to sign binary
+
+# Normaly, coreos-efi-secureboot should be ihnerited globally, but we 
+# ihnerit it again here to be sure that it's included
+inherit coreos-efi-secureboot
+
+coreos_efi_secureboot_sign_app() {
+    # Helper function to sign an UEFI binary in place
+    sbsign --key "${COREOS_EFI_SECUREBOOT_KEYDIR}/db.key" --cert "${COREOS_EFI_SECUREBOOT_KEYDIR}/db.crt" "$1" --output "$1"
+}
+

layers/meta-belden-coreos-bsp/classes/coreos-efi-secureboot.bbclass

@@ -0,0 +1,34 @@
+# This class is ihnerited globally in the CoreOS distro
+
+# UEFI Secure boot configuration
+# ==============================================================================
+
+COREOS_EFI_SECUREBOOT_KEYDIR ??= "${RECIPE_SYSROOT_NATIVE}/${datadir}/keys"
+COREOS_EFI_SECUREBOOT_INSTALL_PUBKEY_IN_EFIDIR ??= "0"
+
+# UEFI Secure boot helpers
+# ==============================================================================
+
+# Image are signed with sbsign, but sbsign is not availabe in OE-Core, let's
+# use from the host. This only work if this class is inherited in a global
+# configuration file, like it's the case in the CoreOS distro
+HOSTTOOLS += "sbsign"
+
+# Ensure that the public keys are always deployed to the deploy directory
+# before running wic
+do_image_wic[depends] += "cos-certificates-and-keys-native:do_deploy"
+
+COREOS_EFI_SECUREBOOT_INSTALL_PUBKEY_IN_EFIDIR ??= "0"
+def get_coreos_secureboot_efi_boot_files(d):
+    """
+        Return the list of pubkey file inside deploy if
+        COREOS_EFI_SECUREBOOT_INSTALL_PUBKEY_IN_EFIDIR is set or an empty string
+        otherwise
+    """
+    if d.getVar('COREOS_EFI_SECUREBOOT_INSTALL_PUBKEY_IN_EFIDIR') == '1':
+        return "db.auth KEK.auth PK.auth db.esl KEK.esl PK.esl db.crt KEK.crt PK.crt db.der KEK.der PK.der"
+    return ""
+
+IMAGE_EFI_BOOT_FILES:append = " ${@get_coreos_secureboot_efi_boot_files(d)}"
+
+

layers/meta-belden-coreos-bsp/classes/coreos-image-swupdate-beaglebone.bbclass

@@ -0,0 +1,26 @@
+
+SWUPDATE_IMAGES += "MLO"
+SWUPDATE_IMAGES += "u-boot-beaglebone"
+SWUPDATE_IMAGES_FSTYPES[MLO] = ""
+SWUPDATE_IMAGES_FSTYPES[u-boot-beaglebone] = ".img"
+
+COREOS_SWUPDATE_EXTENDS_FOR:append = "beaglebone"
+
+def coreos_swupdate_extends_images_for_beaglebone(d,s):
+    mlo = {
+        "filename" : "MLO",
+        "installed-directly" : "true",
+        "device" : "/dev/disk/by-partlabel/mlo",
+        "type" : "raw",
+        "sha256" : swupdate_get_sha256(d, s, "MLO"),
+    }
+
+    uboot = {
+        "filename" : "u-boot-beaglebone.img",
+        "installed-directly" : "true",
+        "device" : "/dev/disk/by-partlabel/uboot",
+        "type" : "raw",
+        "sha256" : swupdate_get_sha256(d, s, "u-boot-beaglebone.img"),
+    }
+
+    return [mlo, uboot]

layers/meta-belden-coreos-bsp/conf/layer.conf

@@ -0,0 +1,13 @@
+# We have a conf and classes directory, add to BBPATH
+BBPATH .= ":${LAYERDIR}"
+
+# We have recipes-* directories, add to BBFILES
+BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
+            ${LAYERDIR}/recipes-*/*/*.bbappend"
+
+BBFILE_COLLECTIONS += "meta-belden-coreos-bsp"
+BBFILE_PATTERN_meta-belden-coreos-bsp = "^${LAYERDIR}/"
+BBFILE_PRIORITY_meta-belden-coreos-bsp = "6"
+
+LAYERDEPENDS_meta-belden-coreos-bsp = "core meta-belden-coreos"
+LAYERSERIES_COMPAT_meta-belden-coreos-bsp = "kirkstone"

layers/meta-belden-coreos-bsp/conf/machine/beaglebone.conf

@@ -0,0 +1,63 @@
+#@TYPE: Machine
+#@NAME: Beaglebone-yocto machine
+#@DESCRIPTION: Reference machine configuration for http://beagleboard.org/bone and http://beagleboard.org/black boards
+
+MACHINE_EXTRA_RRECOMMENDS = "kernel-modules kernel-devicetree"
+EXTRA_IMAGEDEPENDS += "virtual/bootloader"
+
+
+DEFAULTTUNE ?= "cortexa8hf-neon"
+include conf/machine/include/arm/armv7a/tune-cortexa8.inc
+
+IMAGE_FSTYPES += "wic wic.xz wic.bmap"
+WKS_FILE ?= "beaglebone-sdcard.wks.in"
+COREOS_INSTALLER_WKS_FILE ?= "beaglebone-sdcard-installer.wks"
+MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "kernel-image"
+do_image_wic[depends] += "mtools-native:do_populate_sysroot dosfstools-native:do_populate_sysroot gptfdisk-native:do_populate_sysroot virtual/bootloader:do_deploy"
+do_image_wic[recrdeptask] += "do_bootimg"
+
+SERIAL_CONSOLES ?= "115200;ttyS0 115200;ttyO0 115200;ttyAMA0"
+SERIAL_CONSOLES_CHECK = "${SERIAL_CONSOLES}"
+APPEND:append = " console=ttyS0,115200"
+
+PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
+PREFERRED_VERSION_linux-yocto ?= "6.6%"
+
+KERNEL_IMAGETYPE = "zImage"
+DTB_FILES = "ti/omap/am335x-bone.dtb ti/omap/am335x-boneblack.dtb ti/omap/am335x-bonegreen.dtb"
+KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}"
+
+PREFERRED_PROVIDER_virtual/bootloader ?= "u-boot"
+
+SPL_BINARY = "MLO"
+UBOOT_SUFFIX = "img"
+UBOOT_MACHINE = "am335x_evm_defconfig"
+UBOOT_ENTRYPOINT = "0x80008000"
+UBOOT_LOADADDRESS = "0x80008000"
+
+MACHINE_FEATURES = "usbgadget usbhost vfat alsa"
+
+# support runqemu
+EXTRA_IMAGEDEPENDS += "qemu-native qemu-helper-native"
+IMAGE_CLASSES += "qemuboot"
+QB_DEFAULT_FSTYPE = "wic"
+QB_FSINFO = "wic:no-kernel-in-fs"
+QB_KERNEL_ROOT = "/dev/vda3"
+QB_SYSTEM_NAME = "qemu-system-arm"
+QB_MACHINE = "-machine virt"
+QB_CPU = "-cpu cortex-a15"
+QB_KERNEL_CMDLINE_APPEND = "console=ttyAMA0 systemd.mask=systemd-networkd"
+QB_OPT_APPEND = "-device virtio-rng-device"
+QB_TAP_OPT = "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no"
+QB_NETWORK_DEVICE = "-device virtio-net-device,netdev=net0,mac=@MAC@"
+QB_ROOTFS_OPT = "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0"
+QB_SERIAL_OPT = ""
+QB_TCPSERIAL_OPT = "-device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon"
+
+# No watchdog available yet
+EFIBOOTGUARD_TIMEOUT ?= "0"
+
+COREOS_IMAGE_SWUPDATE_EXTRACLASSES += "coreos-image-swupdate-beaglebone"
+
+require conf/machine/include/coreos-generic-features/efi.inc
+require conf/machine/include/coreos-generic-features/partitions.inc

layers/meta-belden-coreos-bsp/conf/machine/container-arm32.conf

@@ -0,0 +1,2 @@
+require include/coreos-generic-arch/arm32.inc
+require include/coreos-generic-machine/container.inc

layers/meta-belden-coreos-bsp/conf/machine/container-arm64.conf

@@ -0,0 +1,2 @@
+require include/coreos-generic-arch/arm64.inc
+require include/coreos-generic-machine/container.inc

layers/meta-belden-coreos-bsp/conf/machine/container-x64.conf

@@ -0,0 +1,2 @@
+require include/coreos-generic-arch/x64.inc
+require include/coreos-generic-machine/container.inc

layers/meta-belden-coreos-bsp/conf/machine/eagle40-03.conf

@@ -0,0 +1,39 @@
+#@TYPE: Machine
+#@NAME: eagle40-03
+#@DESCRIPTION: Machine support for EAGLE40-03
+#
+
+require include/coreos-generic-arch/x64.inc
+
+MACHINE_FEATURES += "pci usbhost x86 serial efi"
+
+# Kernel configuration
+# ******************************************************************************
+
+PREFERRED_VERSION_linux-yocto ?= "6.6%"
+PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
+
+KERNEL_IMAGETYPE = "bzImage"
+
+#  getty configuration
+# ******************************************************************************
+
+SERIAL_CONSOLES = "115200;ttyS0"
+SERIAL_CONSOLES_CHECK = "ttyS0"
+APPEND += "console=ttyS0,115200"
+
+# Image generation
+# ******************************************************************************
+
+# Ensure that both flash-image.bin and boot.scr are generated as they are needed
+# for a wic image
+WKS_FILE = "generic-uefi.wks.in"
+COREOS_INSTALLER_WKS_FILE ?= "generic-uefi-usb-installer.wks"
+IMAGE_FSTYPES += "wic.xz wic.bmap"
+
+MACHINE_ESSENTIAL_EXTRA_RDEPENDS += " kernel-modules"
+
+# No watchdog available yet
+EFIBOOTGUARD_TIMEOUT ?= "0"
+require conf/machine/include/coreos-generic-features/efi.inc
+require conf/machine/include/coreos-generic-features/partitions.inc

layers/meta-belden-coreos-bsp/conf/machine/include/coreos-generic-arch/arm32.inc

@@ -0,0 +1,3 @@
+# Container will require a host with at least an Armv7 CPU with VFPv3 and Neon. 
+DEFAULTTUNE ?= "armv7athf-neon"
+require conf/machine/include/arm/arch-armv7a.inc

layers/meta-belden-coreos-bsp/conf/machine/include/coreos-generic-arch/arm64.inc

@@ -0,0 +1,2 @@
+DEFAULTTUNE ?= "aarch64"
+require conf/machine/include/arm/arch-arm64.inc

layers/meta-belden-coreos-bsp/conf/machine/include/coreos-generic-arch/x64.inc

@@ -0,0 +1,2 @@
+DEFAULTTUNE ?= "core2-64"
+require conf/machine/include/x86/tune-core2.inc

layers/meta-belden-coreos-bsp/conf/machine/include/coreos-generic-features/efi.inc

@@ -0,0 +1,6 @@
+# EFI Configuration
+# ==============================================================================
+
+MACHINE_FEATURES:append = " efi"
+
+do_image_wic[depends] += "efibootguard-native:do_populate_sysroot efibootguard:do_deploy"

layers/meta-belden-coreos-bsp/conf/machine/include/coreos-generic-features/partitions.inc

@@ -0,0 +1,20 @@
+# Variables used in WKS file
+WKS_PART_EFI ??= 'part --source efibootguard-efi --label efi --part-type=EF00'
+WKS_PART_EFIBOOTGUARD_A ??= 'part --source efibootguard-boot --label ebg0 --part-type=0700 --sourceparams "args=coreos.root=rootfs0,watchdog=${EFIBOOTGUARD_TIMEOUT},revision=2,kernel=${COREOS_KERNEL_FILENAME};KERNEL.EFI"'
+WKS_PART_EFIBOOTGUARD_B ??= 'part --source efibootguard-boot --label ebg1 --part-type=0700 --sourceparams "args=coreos.root=rootfs1,watchdog=${EFIBOOTGUARD_TIMEOUT},revision=1,kernel=${COREOS_KERNEL_FILENAME};KERNEL.EFI"'
+WKS_PART_ROOT_A ??= 'part / --source rootfs --fstype=ext4 --label rootfs0'
+WKS_PART_ROOT_B ??= 'part --fstype=ext4 --label rootfs1'
+WKS_PART_USERDATA ??= 'part /usr/local/data --fstype=btrfs --label userdata'
+
+PART_EFI_SIZE ??= '64M'
+PART_ROOT_SIZE ??= '1G'
+PART_EFIBG_SIZE ??= '128M'
+PART_USERDATA_SIZE ??= '1G'
+
+# Variables used in SFDISK file
+SFDISK_PART_EFI ??= 'type=C12A7328-F81F-11D2-BA4B-00A0C93EC93B, name="efi"'
+SFDISK_PART_EFIBOOTGUARD_A ??= 'type=EBD0A0A2-B9E5-4433-87C0-68B6B72699C7, name="ebg0"'
+SFDISK_PART_EFIBOOTGUARD_B ??= 'type=EBD0A0A2-B9E5-4433-87C0-68B6B72699C7, name="ebg1"'
+SFDISK_PART_ROOT_A ??= 'type=0FC63DAF-8483-4772-8E79-3D69D8477DE4, name="rootfs0"'
+SFDISK_PART_ROOT_B ??= 'type=0FC63DAF-8483-4772-8E79-3D69D8477DE4, name="rootfs1"'
+SFDISK_PART_USERDATA ??= 'type=0FC63DAF-8483-4772-8E79-3D69D8477DE4, name="userdata"'