.. _os-supported-hardware:

###########################################
Supported Hardware
###########################################

OrchestraOS hardware support is provided by the ``meta-orchestraos-bsp``
layer. The layer currently provides machine configurations for the following
targets:

.. list-table:: Supported hardware targets
   :header-rows: 1

   * - Name
     - MACHINE
     - CPU
     - Link
     - Picture
   * - EIG-M (Edge IoT Gateway M)
     - ``eigm``
     - NXP i.MX8M Plus
     - https://cthings.co/products/edge-iot-gateways
     - .. image:: /chapters/orchestra-os/images/eigm.png
          :alt: EIG-M
          :height: 110px
          :width: 160px
          :align: center
          :target: https://cthings.co/products/edge-iot-gateways
   * - EIG-M-DIN (Edge IoT Gateway M DIN Rail Version)
     - ``eigmdin``
     - NXP i.MX8M Plus
     - https://cthings.co/products/edge-iot-gateways
     - .. image:: /chapters/orchestra-os/images/eigmdin.png
          :alt: EIG-M-DIN
          :width: 80px
          :align: center
          :target: https://cthings.co/products/edge-iot-gateways
   * - EIG-MA (Edge IoT Gateway MA)
     - ``eigma``
     - NXP i.MX8M Quad
     - https://cthings.co/hardware/asusiot
     - .. image:: /chapters/orchestra-os/images/eigma.png
          :alt: EIG-MA
          :width: 160px
          :align: center
          :target: https://cthings.co/hardware/asusiot
   * - EIG-XS (Edge IoT Gateway XS)
     - ``eigxs``
     - NXP i.MX93
     - https://cthings.co/products/edge-iot-gateways
     - .. image:: /chapters/orchestra-os/images/eigxs.png
          :alt: EIG-XS
          :width: 220px
          :align: center
          :target: https://cthings.co/products/edge-iot-gateways

The machine configuration files are stored under
``layers/meta-orchestraos-bsp/conf/machine``. Hardware-specific kernel,
bootloader, firmware, and signing integration live in the same
``meta-orchestraos-bsp`` layer.

.. _os-platform-integration-details:

Platform Integration Details
============================

Kernel And Bootloader Sources
-----------------------------

All listed machines select the NXP BSP path and use ``linux-imx`` as the
``IMX_DEFAULT_KERNEL`` provider. The BSP layer then overrides the upstream
``linux-imx`` source URI for selected machines to use board-vendor forks.
U-Boot is built through ``u-boot-imx`` version ``2024.04`` with
machine-specific source overrides.

.. list-table:: Platform sources
   :header-rows: 1

   * - MACHINE
     - SoC
     - Kernel source
     - Kernel version / branch
     - Bootloader source
     - Bootloader version / branch
   * - ``eigm``
     - i.MX8M Plus
     - ``linux-imx`` provider, Compulab ``linux-compulab`` source
     - ``linux-compulab_v6.6.52``
     - ``u-boot-imx`` provider, Compulab ``u-boot-compulab`` source
     - ``2024.04``, branch ``u-boot-compulab_v2024.04-2.2.0``
   * - ``eigmdin``
     - i.MX8M Plus
     - ``linux-imx`` provider, Compulab ``linux-compulab`` source
     - ``linux-compulab_v6.6.52``
     - ``u-boot-imx`` provider, Compulab ``u-boot-compulab`` source
     - ``2024.04``, branch ``u-boot-compulab_v2024.04-2.2.0``
   * - ``eigma``
     - i.MX8M Quad
     - ``linux-imx`` provider, ASUS ``linux-imx`` source
     - branch/SRCREV ``yocto-5.0-imx_8m``
     - ``u-boot-imx`` provider, ASUS ``uboot-imx`` source
     - ``2024.04``, branch ``yocto-5.0-imx_8m``
   * - ``eigxs``
     - i.MX93
     - ``linux-imx`` provider, Compulab ``linux-compulab`` source
     - ``linux-compulab_v6.6.52-rt-iot-link-1.0.1``
     - ``u-boot-imx`` provider, Compulab ``u-boot-compulab`` source
     - ``2024.04``, branch ``u-boot-compulab_v2024.04``

Secure Boot Type
----------------

Secure-boot signing is enabled through machine features. The supported BSP
machines append both ``imx-boot-signature`` and ``linux-imx-signature`` to
``MACHINE_FEATURES``. Those features select signed bootloader and signed kernel
artifacts during the build.

.. list-table:: Secure boot family
   :header-rows: 1

   * - MACHINE
     - SoC family
     - Secure boot type
     - Signing features
   * - ``eigm``
     - i.MX8M Plus
     - HAB4
     - ``imx-boot-signature``, ``linux-imx-signature``
   * - ``eigmdin``
     - i.MX8M Plus
     - HAB4
     - ``imx-boot-signature``, ``linux-imx-signature``
   * - ``eigma``
     - i.MX8M Quad
     - HAB4
     - ``imx-boot-signature``, ``linux-imx-signature``
   * - ``eigxs``
     - i.MX93
     - AHAB
     - ``imx-boot-signature``, ``linux-imx-signature``

The HAB4/AHAB selection follows the NXP SoC family. i.MX8M-family targets use
HAB4, while i.MX93 targets use AHAB. For key generation and signing-data
layout, see :ref:`os-signing-keys`.

Device Tree Selection
---------------------

Each machine defines a ``KERNEL_DEVICETREE_BASENAME`` and installs the device
trees needed by that machine. The common ``eig.inc`` include derives
``KERNEL_DEVICETREE_DEFAULT`` from:

.. code-block:: text

   ${KERNEL_DEVICETREE_BASENAME}${KERNEL_DEVICETREE_SUFFIX}

For most machines, the suffix is empty and the base device tree is selected.
The EIG-M machine also supports add-on-module based selection through
``MACHINE_FEATURES``:

.. list-table:: EIG-M device-tree suffix selection
   :header-rows: 1

   * - MACHINE_FEATURES
     - KERNEL_DEVICETREE_SUFFIX
     - Selected default device tree
   * - ``m2tpm-module-present``
     - ``-m2tpm``
     - ``compulab/iot-gate-imx8plus-m2tpm.dtb``
   * - ``usbdev-module-present``
     - ``-usbdev``
     - ``compulab/iot-gate-imx8plus-usbdev.dtb``
   * - neither feature present
     - empty
     - ``compulab/iot-gate-imx8plus.dtb``

If both EIG-M module features are present, ``m2tpm-module-present`` takes
priority because it is checked first in ``eigm.conf``.

Other machines currently use fixed default device trees:

.. list-table:: Fixed default device trees
   :header-rows: 1

   * - MACHINE
     - Default device tree
   * - ``eigmdin``
     - ``compulab/iotdin-imx8p.dtb``
   * - ``eigma``
     - ``freescale/imx8mq-pe100a.dtb``
   * - ``eigxs``
     - ``compulab/iot-link.dtb``