Merge branch 'main' into luks

source/conf.py

@@ -336,6 +336,12 @@
 # Config for sphinx-reredirects, maps source: target, target path is relative to source.
 # TODO: troubleshooting sections redirecting to lmp-customization do not appear to be functional
 redirects = {
+     "user-guide/cert-rotation": "rotating-cert.html",
+     "reference-manual/docker/compose-apps": "../../user-guide/containers-and-docker/compose-apps.html",
+     "reference-manual/docker/configure-docker-helper": "../../user-guide/containers-and-docker/configure-docker-helper.html",
+     "reference-manual/docker/containers": "../../user-guide/containers-and-docker/containers.html",
+     "user-guide/containers-preloading/container-preloading": "../containers-and-docker/container-preloading.html",
+     "user-guide/multi-stage-container/multi-stage-container": "../containers-and-docker/multi-stage-container",
      "reference-manual/factory/team-based-access": "../../user-guide/account-management/team-based-access.html",
      "reference-manual/factory/factory-keys": "../../reference-manual/security/factory-keys.html",
      "reference-manual/security/secure-boot": "security.html#secure-boot-hardware-root-of-trust",
@@ -409,6 +415,8 @@
      "community-factory/create-factory": "../getting-started/signup/index.html",
      "community-factory/": "index.html",
      "getting-started/git-config/index": "../install-fioctl/index.html#configuring-git",
+     "reference-manual/linux/linux-building": "../../user-guide/lmp-customization/linux-building.html",
+     "reference-manual/linux/linux-extending": "../../user-guide/lmp-customization/linux-extending.html",
       }
 
 # Make external links open in a new tab.

source/getting-started/install-fioctl/index.rst

@@ -3,7 +3,7 @@
 Installing Fioctl
 =================
 
-:ref:`Fioctl™ <ref-fioctl>` is a simple tool for interacting with the Foundries.io REST API.
+:ref:`Fioctl™ <ref-fioctl>` is a simple tool for interacting with the Foundries.io™ REST API.
 
 .. seealso::
    Fioctl is based on Foundries.io's  `ota-lite API <https://api.foundries.io/ota/>`_.
@@ -27,10 +27,12 @@ Installation
 Manual Installation
 ^^^^^^^^^^^^^^^^^^^
 
-We use `Github Releases`_ to distribute static golang binaries.
+We use `GitHub Releases`_ to distribute static golang binaries.
 
 .. tip::
-   Repeating the following steps will overwrite an existing binary, useful for updating or changing version.
+   Fioctl v0.36 and later has an auto-update feature.
+   Run ``fioctl version`` to check for an update, then run ``fioctl version --update-to <version>``.
+   For more details checkout the :ref:`Fioctl user guide <ug-fioctl>`.
 
 .. tabs::
 
@@ -64,7 +66,7 @@ We use `Github Releases`_ to distribute static golang binaries.
       .. attention::
         Make sure you have ``curl`` installed.
 
-      1. Download a Darwin binary from the `Github Releases`_ page to a directory on your ``PATH``.
+      1. Download a Darwin binary from the `GitHub Releases`_ page to a directory on your ``PATH``.
 
          For example, to download version |fioctl_version| on macOS, define the version:
 
@@ -91,7 +93,7 @@ We use `Github Releases`_ to distribute static golang binaries.
 
    .. group-tab:: Windows
 
-      1. Download a Windows binary from the `Github Releases`_ page.
+      1. Download a Windows binary from the `GitHub Releases`_ page.
       2. Put it in a folder of your choosing and rename it to ``fioctl.exe``
       3. Press ``Win + R`` and type ``SystemPropertiesAdvanced``
       4. Press ``enter`` or click ``OK``.
@@ -112,7 +114,7 @@ Authenticating Fioctl
 #####################
 
 With :ref:`ref-fioctl` installed, authenticate it with our backend.
-For this, you will generate OAuth2 application credentials for interacting with the FoundriesFactory API:
+For this, you will generate OAuth2 application credentials for interacting with the FoundriesFactory® API:
 
 .. prompt:: bash host:~$, auto
 
@@ -190,7 +192,7 @@ The following command can be used to test the ``fioctl`` configuration.
 .. seealso::
    :ref:`ref-fioctl` documentation.
 
-.. _Github Releases: https://github.com/foundriesio/fioctl/releases
+.. _GitHub Releases: https://github.com/foundriesio/fioctl/releases
 
 .. _gs-git-config:
 
@@ -213,11 +215,7 @@ Run the following command to add the relevant entries to the Git configuration:
    This is because it needs to have privileges to create a symlink in the same directory as where ``git`` is located.
 
 .. warning::
-   * If for some reason the command fails with an error, the following manual steps can be taken to get the exact same result::
-
-      git config --global credential.https://source.foundries.io.username fio-oauth2
-      git config --global credential.https://source.foundries.io.helper fio
-      ln -s /usr/local/bin/fioctl /usr/bin/git-credential-fio
+   * If for some reason the command ``sudo fioctl configure-git`` fails with an error, manual steps can be taken to get the exact same result. For comprehensive instructions, please see the :ref:`Fioctl™ Errors <ref-ts-errors>` section.
 
    * Existing users reconfiguring Git access may need to remove the following lines from ``.gitconfig`` to use ``fioctl configure-git`` utility::
 

source/index.rst

@@ -38,18 +38,17 @@ OE/Yocto Project, the Linux microPlatform™ and Docker®.
    :name: sec-user-guide
 
    user-guide/account-management/account-management
-   user-guide/container-preloading/container-preloading
+   user-guide/containers-and-docker/index
    user-guide/custom-ci/custom-ci
-   user-guide/lmp-customization/lmp-customization
+   user-guide/lmp-customization/index
    user-guide/lmp-auto-hostname/lmp-auto-hostname
    user-guide/lmp-device-auto-register/lmp-device-auto-register
    user-guide/foundriesio-rest-api/foundriesio-rest-api
    user-guide/mirror-action/mirror-action
    user-guide/submodule/submodule
    user-guide/custom-sota-client
-   user-guide/multi-stage-container/multi-stage-container
    user-guide/fioctl/index
-   user-guide/cert-rotation
+   user-guide/rotating-cert
    user-guide/device-gateway-pki/device-gateway-pki
    user-guide/offline-update/offline-update
    user-guide/el2g

source/porting-guide/pg.rst

@@ -1,3 +1,5 @@
+.. _ref-pg:
+
 FoundriesFactory Porting Guide
 ==============================
 

source/reference-manual/boards/am62xx-sk-prepare.rst

@@ -1,67 +1,49 @@
 Building
 --------
 
-When building the Cortex R5 u-boot, it builds for all different variants:
+When building the Cortex R5 U-Boot, all variants are built:
 
-* ``hs-fs`` (High Security/Field Securable) also known as `SK-AM62B`_: This is a SoC/board state before a customer has blown the keys in the device. i.e. the state at which HS device leaves TI factory. In this state, the device protects the ROM code, TI keys and certain security peripherals. In this state, device do not force authentication for booting, however DMSC is locked.
+* ``hs-fs`` (High Security/Field Securable), also known as `SK-AM62B`_: The SoC/board state before blowing the keys on the device,
+  i.e., the state at which the HS device leaves the TI factory.
+  The device protects the ROM code, TI keys, and certain security peripherals.
+  In this state, devices do not force authentication for booting, however DMSC is locked.
 
-* ``hs`` (High Security/Security Enforced) also known as `SK-AM62B`_: This is a SoC/board state after a customer has successfully blown the keys and set “customer keys enable”. In HS-SE device all security features are enabled. All secrets within the device are fully protected and all of the security goals are fully enforced. The device also enforces secure booting.
+* ``hs`` (High Security/Security Enforced), also known as `SK-AM62B`_: This is the SoC/board state after successfully blowing the keys and setting “customer keys enable”.
+  In HS-SE, all security features are enabled.
+  Secrets within the device are fully protected and all security goals are enforced.
+  The device enforces secure booting.
 
-* ``gp`` (General Purpose) variant also known as `SK-AM62`_: This is a SoC/board state where there is no device protection and authentication is not enabled for booting the device.
+* ``gp`` (General Purpose), also known as `SK-AM62`_: This is a SoC/board state with no device protection and authentication is not enabled for booting the device.
 
-The default variant is the ``hs-fs``. To boot an image on the others variants without pre-flash files manipulations
-on the target file-system we need to change the ``SYSFW_SUFFIX`` variable.
-The following changes the default to ``gp`` so the image produced boots on that variant:
+The default variant is  ``hs-fs``.
+To boot an image on other variants without pre-flash files manipulations on the target file-system, we need to change the ``SYSFW_SUFFIX`` variable.
+The following changes the default to ``gp``, so that the image produced boots that variant:
 
 .. code-block:: shell
 
    echo 'SYSFW_SUFFIX:am62xx-evm-k3r5 = "gp"' >> meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc
 
-Preparation
------------
+.. include:: generic-prepare.rst
 
-Ensure you replace the ``<factory>`` placeholder below with the name of your
-Factory.
-
-Download necessary files from ``https://app.foundries.io/factories/<factory>/targets``
-
-#. Click the latest Target with the :guilabel:`platform-devel` trigger.
-
-   .. figure:: /_static/boards/generic-steps-1.png
-      :align: center
-      :width: 300
-
-#. Expand the **run** in the :guilabel:`Runs` section (by clicking on the ``+`` sign) which corresponds
-   with the name of the board and **download the Factory image for that
-   machine.**
-
-   | E.g: ``lmp-factory-image-am62xx-evm.wic.gz``
-
-   .. figure:: /_static/boards/am62xx-sk-steps-2.png
-      :align: center
-      :width: 600
-#. Extract the file ``lmp-factory-image-am62xx-evm.wic.gz``::
+#. Extract the file::
 
       gunzip lmp-factory-image-am62xx-evm.wic.gz
 
-#. Expand the **run** in the :guilabel:`Runs` section which corresponds
-   with the name of the board ti-mfgtool-files and **download the tools for that
-   machine.**
-
-   E.g: ``ti-mfgtool-files-am62xx-evm.tar.gz``
+#. Expand the **run** in the :guilabel:`Runs` section corresponding with the name of the board.
+   Download ``ti-mfgtool-files-am62xx-evm.tar.gz``.
 
-#. Download and extract the file ``ti-mfgtool-files-am62xx-evm.tar.gz``::
+#. Extract the file::
 
       tar -zxvf ti-mfgtool-files-am62xx-evm.tar.gz
 
-#. Organize all the files like the tree below::
+#. Organize the files as in the tree below::
 
       ├── lmp-factory-image-am62xx-evm.wic
       └── ti-mfgtool-files-am62xx-evm
-          ├── flash.sh
-          ├── tiboot3.bin
-          ├── tispl.bin
-          └── uboot.img
+          ├── flash.sh
+          ├── tiboot3.bin
+          ├── tispl.bin
+          └── uboot.img
 
 .. _SK-AM62B:
    https://www.ti.com/tool/SK-AM62B

source/reference-manual/boards/am62xx-sk.rst

@@ -8,60 +8,35 @@ Texas Instruments AM62x SKEVM
 Hardware Preparation
 --------------------
 
-Set up the board for booting from USB DFU mode:
+Set up the board for booting from MMC1-SDCard:
 
-#. Ensure that the power is off (remove cable from J11)
+#. Ensure that the power is off (remove cable from **J11**):
 
 .. figure:: /_static/boards/am62xx-sk-top.png
      :width: 600
      :align: center
 
      AM62xx-sk top view
 
-2. Put the am62xx-sk into boot from USB DFU Mode,
-   changing boot switches to: ``00000000 11001010``
+#. Put the am62xx-sk into boot from SDCard Mode:
+
+.. figure:: /_static/boards/am62xx-sk-switches.png
+     :width: 300
+     :align: center
+
+     Switch settings
+
 
 Flashing
 --------
 
-#. Power on the board and flash the board using ``flash.sh`` script from
-   ``ti-mfgtool-files-am62xx-evm`` directory, it copies the
-   ``lmp-factory-image-am62xx-evm.wic`` image.
-   The wic image contains the :term:`system image` that the device will boot.
-
-.. prompt:: bash host:~$, auto
-
-    host:~$ sudo ./ti-mfgtool-files-am62xx-evm/flash.sh --wic lmp-factory-image-am62xx-evm.wic
-     Load U-Boot via DFU...
-     ------------------------------------------
-     DFU BOOT TIBOOT3: TIFS and R5
-     ------------------------------------------
-     ------------------------------------------
-     DFU BOOT TISPL: TFA/OPTEE/ and A53 SPL
-     ------------------------------------------
-     ------------------------------------------
-     DFU BOOT UBOOT: A53 UBOOT
-     ------------------------------------------
-     ------------------------------------------
-     Exposing eMMC via USB using UMS
-     ------------------------------------------
-     Detected device: /dev/sda
-     Confirm flashing lmp-factory-image-am62xx-evm.wic to /dev/sda (y/N) >y
-     ------------------------------------------
-     Flashing /dev/sda via UMS
-     ------------------------------------------
-     844103680 bytes (844 MB, 805 MiB) copied, 57 s, 14,8 MB/s
-     814+1 records in
-     814+1 records out
-     854511616 bytes (855 MB, 815 MiB) copied, 57,7472 s, 14,8 MB/s
-     Flashing is finished
-
-2. Power off the board.
-
-Configure eMMC UDA Boot
------------------------
-
-#. Put the am62xx-sk into boot from eMMC UDA mode,
-   changing boot switches to: ``00000000 11000010``.
-
-#. Power on a board.
+Flash ``lmp-factory-image-am62xx-evm.wic.gz`` to an SD Card.
+This contains the bootable :term:`system image`.
+
+.. include:: generic-flashing.rst
+
+.. figure:: /_static/boards/am62xx-sk-bottom.png
+     :width: 600
+     :align: center
+
+     SDCard location

source/reference-manual/boards/am64xx-sk-prepare.rst

@@ -1,46 +1,31 @@
 Building
 --------
 
-When building the Cortex R5 u-boot, it builds for all different variants:
+When building the Cortex R5 U-Boot, all variants are built:
 
-* ``hs-fs`` (High Security/Field Securable) also known as `SK-AM64B`_: This is a SoC/board state before a customer has blown the keys in the device. i.e. the state at which HS device leaves TI factory. In this state, the device protects the ROM code, TI keys and certain security peripherals. In this state, device do not force authentication for booting, however DMSC is locked.
+* ``hs-fs`` (High Security/Field Securable), also known as `SK-AM64B`_: This is a SoC/board state before a customer has blown the keys in the device,
+  i.e., the state at which the HS device leaves TI factory.
+  The device protects the ROM code, TI keys and certain security peripherals.
+  In this state, devices do not force authentication for booting, however DMSC is locked.
 
-* ``hs`` (High Security/Security Enforced) also known as `SK-AM64B`_: This is a SoC/board state after a customer has successfully blown the keys and set “customer keys enable”. In HS-SE device all security features are enabled. All secrets within the device are fully protected and all of the security goals are fully enforced. The device also enforces secure booting.
+* ``hs`` (High Security/Security Enforced), also known as `SK-AM64B`_: This is a SoC/board state after successfully blowning the keys and set “customer keys enable”.
+  In HS-SE device all security features are enabled.
+  All secrets within the device are fully protected and all of the security goals are fully enforced.
+  The device also enforces secure booting.
 
-* ``gp`` (General Purpose) variant also known as `SK-AM64`_: This is a SoC/board state where there is no device protection and authentication is not enabled for booting the device.
+* ``gp`` (General Purpose), also known as `SK-AM64`_: This is a SoC/board state with no device protection and authentication is not enabled for booting the device.
 
-The default variant is the ``hs-fs``. To boot an image on the others variants without pre-flash files manipulations
-on the target file-system we need to change the ``SYSFW_SUFFIX`` variable.
-The following changes the default to ``gp`` so the image produced boots on that variant:
+The default variant is  ``hs-fs``.
+To boot an image on other variants without pre-flash files manipulations on the target file-system, we need to change the ``SYSFW_SUFFIX`` variable.
+The following changes the default to ``gp``, so that the image produced boots that variant:
 
 .. code-block:: shell
 
    echo 'SYSFW_SUFFIX:am64xx-evm-k3r5 = "gp"' >> meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc
 
-Preparation
------------
+.. include:: generic-prepare.rst
 
-Ensure you replace the ``<factory>`` placeholder below with the name of your
-Factory.
-
-Download necessary files from ``https://app.foundries.io/factories/<factory>/targets``
-
-#. Click the latest Target with the :guilabel:`platform-devel` trigger.
-
-   .. figure:: /_static/boards/generic-steps-1.png
-      :align: center
-      :width: 300
-
-#. Expand the **run** in the :guilabel:`Runs` section (by clicking on the ``+`` sign) which corresponds
-   with the name of the board and **download the Factory image for that
-   machine.**
-
-   | E.g: ``lmp-factory-image-am64xx-evm.wic.gz``
-   
-   .. figure:: /_static/boards/am64xx-sk-steps-2.png
-      :align: center
-      :width: 600
-#. Extract the file ``lmp-factory-image-am64xx-evm.wic.gz``::
+#. Extract the file::
 
       gunzip lmp-factory-image-am64xx-evm.wic.gz
 

source/reference-manual/boards/am64xx-sk.rst

@@ -8,9 +8,9 @@ Texas Instruments AM64x SKEVM
 Hardware Preparation
 --------------------
 
-Set up the board for booting from MMC1 - SDCard:
+Set up the board for booting from MMC1–SDCard:
 
-#. Ensure that the power is off (remove cable from J8)
+#. Ensure that the power is off (remove cable from **J8**):
 
 .. figure:: /_static/boards/am64xx-sk-top.png
      :width: 600
@@ -30,9 +30,8 @@ Set up the board for booting from MMC1 - SDCard:
 Flashing
 --------
 
-Now, flash the ``lmp-factory-image-am64xx-evm.wic.gz`` retrieved from the
-previous section to an SD Card. This contains the :term:`system image` that the
-device will boot.
+Flash ``lmp-factory-image-am64xx-evm.wic.gz`` to an SD Card.
+This contains the bootable :term:`system image`.
 
 .. include:: generic-flashing.rst