diff --git a/source/_static/boards/apalis-imx-jp2.png b/source/_static/boards/apalis-imx-jp2.png deleted file mode 100644 index 596cf6c41..000000000 Binary files a/source/_static/boards/apalis-imx-jp2.png and /dev/null differ diff --git a/source/_static/boards/apalis-imx-jp4-close.jpeg b/source/_static/boards/apalis-imx-jp4-close.jpeg deleted file mode 100644 index 9f8e162db..000000000 Binary files a/source/_static/boards/apalis-imx-jp4-close.jpeg and /dev/null differ diff --git a/source/_static/boards/apalis-imx-jp4.png b/source/_static/boards/apalis-imx-jp4.png deleted file mode 100644 index 8175af4a7..000000000 Binary files a/source/_static/boards/apalis-imx-jp4.png and /dev/null differ diff --git a/source/_static/boards/apalis-imx-usb.png b/source/_static/boards/apalis-imx-usb.png deleted file mode 100644 index 5d36d2390..000000000 Binary files a/source/_static/boards/apalis-imx-usb.png and /dev/null differ diff --git a/source/_static/boards/imx6_sw601.png b/source/_static/boards/imx6_sw601.png deleted file mode 100644 index 367c6e57f..000000000 Binary files a/source/_static/boards/imx6_sw601.png and /dev/null differ diff --git a/source/_static/boards/imx6_windows.png b/source/_static/boards/imx6_windows.png deleted file mode 100644 index 7899a647e..000000000 Binary files a/source/_static/boards/imx6_windows.png and /dev/null differ diff --git a/source/_static/boards/imx6ulevk.png b/source/_static/boards/imx6ulevk.png deleted file mode 100644 index 9046d3c4d..000000000 Binary files a/source/_static/boards/imx6ulevk.png and /dev/null differ diff --git a/source/_static/boards/imx6ullevk.png b/source/_static/boards/imx6ullevk.png deleted file mode 100644 index b0fab4b7f..000000000 Binary files a/source/_static/boards/imx6ullevk.png and /dev/null differ diff --git a/source/_static/boards/imx6ullevk_SW1.png b/source/_static/boards/imx6ullevk_SW1.png deleted file mode 100644 index 4061d112d..000000000 Binary files a/source/_static/boards/imx6ullevk_SW1.png and /dev/null differ diff --git a/source/_static/boards/imx8mmevk.png b/source/_static/boards/imx8mmevk.png deleted file mode 100644 index 5f4403b40..000000000 Binary files a/source/_static/boards/imx8mmevk.png and /dev/null differ diff --git a/source/_static/boards/imx8mmevk_J1004.png b/source/_static/boards/imx8mmevk_J1004.png deleted file mode 100644 index c784c8405..000000000 Binary files a/source/_static/boards/imx8mmevk_J1004.png and /dev/null differ diff --git a/source/_static/boards/imx8mmevk_J1004_pinout.png b/source/_static/boards/imx8mmevk_J1004_pinout.png deleted file mode 100644 index 24d47151d..000000000 Binary files a/source/_static/boards/imx8mmevk_J1004_pinout.png and /dev/null differ diff --git a/source/_static/boards/imx8mmevk_SW.png b/source/_static/boards/imx8mmevk_SW.png deleted file mode 100644 index 0998a3e1c..000000000 Binary files a/source/_static/boards/imx8mmevk_SW.png and /dev/null differ diff --git a/source/_static/boards/imx8mn-ddr4-evk.png b/source/_static/boards/imx8mn-ddr4-evk.png deleted file mode 100644 index a21367dce..000000000 Binary files a/source/_static/boards/imx8mn-ddr4-evk.png and /dev/null differ diff --git a/source/_static/boards/imx8mp-lpddr4-evk.png b/source/_static/boards/imx8mp-lpddr4-evk.png deleted file mode 100644 index e1e27313a..000000000 Binary files a/source/_static/boards/imx8mp-lpddr4-evk.png and /dev/null differ diff --git a/source/_static/boards/imx8mp-lpddr4-evk_J22.png b/source/_static/boards/imx8mp-lpddr4-evk_J22.png deleted file mode 100644 index 12a566a6b..000000000 Binary files a/source/_static/boards/imx8mp-lpddr4-evk_J22.png and /dev/null differ diff --git a/source/_static/boards/imx8mp-lpddr4-evk_J22_pinout.png b/source/_static/boards/imx8mp-lpddr4-evk_J22_pinout.png deleted file mode 100644 index 8ec216ae1..000000000 Binary files a/source/_static/boards/imx8mp-lpddr4-evk_J22_pinout.png and /dev/null differ diff --git a/source/_static/boards/imx8mp-lpddr4-evk_SW.png b/source/_static/boards/imx8mp-lpddr4-evk_SW.png deleted file mode 100644 index 848810f4b..000000000 Binary files a/source/_static/boards/imx8mp-lpddr4-evk_SW.png and /dev/null differ diff --git a/source/_static/boards/imx8mqevk.png b/source/_static/boards/imx8mqevk.png deleted file mode 100644 index 478f11c4f..000000000 Binary files a/source/_static/boards/imx8mqevk.png and /dev/null differ diff --git a/source/_static/boards/imx8mqevk_J801.png b/source/_static/boards/imx8mqevk_J801.png deleted file mode 100644 index e50117db6..000000000 Binary files a/source/_static/boards/imx8mqevk_J801.png and /dev/null differ diff --git a/source/_static/boards/imx8mqevk_J801_pinout.png b/source/_static/boards/imx8mqevk_J801_pinout.png deleted file mode 100644 index 53de6c2be..000000000 Binary files a/source/_static/boards/imx8mqevk_J801_pinout.png and /dev/null differ diff --git a/source/_static/boards/imx8mqevk_SW2.png b/source/_static/boards/imx8mqevk_SW2.png deleted file mode 100644 index 94f322792..000000000 Binary files a/source/_static/boards/imx8mqevk_SW2.png and /dev/null differ diff --git a/source/_static/boards/imx8qm-mek-bootswitches.png b/source/_static/boards/imx8qm-mek-bootswitches.png deleted file mode 100644 index b6b9c637f..000000000 Binary files a/source/_static/boards/imx8qm-mek-bootswitches.png and /dev/null differ diff --git a/source/_static/boards/imx93evk.png b/source/_static/boards/imx93evk.png deleted file mode 100644 index 66ee945b0..000000000 Binary files a/source/_static/boards/imx93evk.png and /dev/null differ diff --git a/source/_static/boards/imx93evk_SW.png b/source/_static/boards/imx93evk_SW.png deleted file mode 100644 index 02e52d46f..000000000 Binary files a/source/_static/boards/imx93evk_SW.png and /dev/null differ diff --git a/source/_static/boards/portenta-x8-boot.png b/source/_static/boards/portenta-x8-boot.png deleted file mode 100644 index 43189fe30..000000000 Binary files a/source/_static/boards/portenta-x8-boot.png and /dev/null differ diff --git a/source/_static/boards/portenta-x8-uart.png b/source/_static/boards/portenta-x8-uart.png deleted file mode 100644 index e2165cecf..000000000 Binary files a/source/_static/boards/portenta-x8-uart.png and /dev/null differ diff --git a/source/_static/boards/portenta-x8.png b/source/_static/boards/portenta-x8.png deleted file mode 100644 index 0920de05a..000000000 Binary files a/source/_static/boards/portenta-x8.png and /dev/null differ diff --git a/source/_static/boards/se050ard_imx6ull.jpg b/source/_static/boards/se050ard_imx6ull.jpg deleted file mode 100644 index a09b55ed7..000000000 Binary files a/source/_static/boards/se050ard_imx6ull.jpg and /dev/null differ diff --git a/source/_static/boards/se050ard_imx8mm.png b/source/_static/boards/se050ard_imx8mm.png deleted file mode 100644 index 331b10cef..000000000 Binary files a/source/_static/boards/se050ard_imx8mm.png and /dev/null differ diff --git a/source/_static/boards/se050ard_imx8mp.jpg b/source/_static/boards/se050ard_imx8mp.jpg deleted file mode 100644 index b206606a1..000000000 Binary files a/source/_static/boards/se050ard_imx8mp.jpg and /dev/null differ diff --git a/source/_static/boards/se050ard_imx8mq.png b/source/_static/boards/se050ard_imx8mq.png deleted file mode 100644 index 0a316b8c6..000000000 Binary files a/source/_static/boards/se050ard_imx8mq.png and /dev/null differ diff --git a/source/_static/csv/revoke_imx.csv b/source/_static/csv/revoke_imx.csv deleted file mode 100644 index 3500f3f7f..000000000 --- a/source/_static/csv/revoke_imx.csv +++ /dev/null @@ -1,5 +0,0 @@ -SRK key,Source index,`SRK_REVOKE[3:0]`,`SRK_REVOKE[hex]`,`srk-index` -SRK0,0,0001,0x1,1 -SRK1,1,0010,0x2,2 -SRK2,2,0100,0x4,3 -SRK3,3,1000,0x8,4 \ No newline at end of file diff --git a/source/_static/csv/supported-boards.csv b/source/_static/csv/supported-boards.csv index 17b911e7f..33a64be81 100644 --- a/source/_static/csv/supported-boards.csv +++ b/source/_static/csv/supported-boards.csv @@ -1,16 +1,6 @@ Device Name,MACHINE :ref:`Intel NUC8 `,intel-corei7-64 :ref:`Intel x86-64 UEFI `,intel-corei7-64 -:ref:`NXP i.MX6 UL EVK `,imx6ulevk -:ref:`NXP i.MX6 ULL EVK `,imx6ullevk -:ref:`NXP i.MX6 ULL EVK with secure boot enabled `,imx6ullevk-sec -:ref:`NXP i.MX 8M Mini EVK `,imx8mm-lpddr4-evk -:ref:`NXP i.MX 8M Mini EVK with secure boot enabled `,imx8mm-lpddr4-evk-sec -:ref:`NXP i.MX 8M Quad EVK `,imx8mq-evk -:ref:`NXP i.MX 8M Plus EVK `,imx8mp-lpddr4-evk -:ref:`NXP i.MX 8M Plus EVK with secure boot enabled `,imx8mp-lpddr4-evk-sec -:ref:`NXP i.MX 8M Nano EVK `,imx8mn-ddr4-evk -:ref:`NXP i.MX 93 EVK `,imx93-11x11-lpddr4x-evk :ref:`QEMU AARCH32 `,qemuarm :ref:`QEMU AARCH64 `,qemuarm64-secureboot `Qualcomm RB3 Gen 2 `_,qcs6490-rb3gen2-vision-kit @@ -18,6 +8,3 @@ Device Name,MACHINE :ref:`Raspberry Pi5 (and CM) `,raspberrypi5 :ref:`TI Beaglebone Black `,beaglebone-yocto :ref:`TI Beaglebone Black Wireless `,beaglebone-yocto -:ref:`Toradex Apalis iMX6 `,apalis-imx6 -:ref:`Toradex Apalis iMX6 with secure boot enabled `,apalis-imx6-sec -:ref:`Toradex Apalis iMX8QM `,apalis-imx8 diff --git a/source/_static/reference-manual/security/imx8-secure-boot.png b/source/_static/reference-manual/security/imx8-secure-boot.png deleted file mode 100644 index fad9ea84c..000000000 Binary files a/source/_static/reference-manual/security/imx8-secure-boot.png and /dev/null differ diff --git a/source/conf.py b/source/conf.py index 1173e538f..a2926a584 100644 --- a/source/conf.py +++ b/source/conf.py @@ -213,8 +213,7 @@ # directories to ignore when looking for source files. exclude_patterns = ['user-guide/flashing/*-flashing.rst', 'user-guide/flashing/*-prepare.rst', - 'user-guide/flashing/*note.rst', - 'reference-manual/security/imx-generic-custom-keys.rst'] + 'user-guide/flashing/*note.rst'] # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] diff --git a/source/getting-started/flash-device/index.rst b/source/getting-started/flash-device/index.rst index 968974ea7..2cb1f4622 100644 --- a/source/getting-started/flash-device/index.rst +++ b/source/getting-started/flash-device/index.rst @@ -125,7 +125,6 @@ By default, your device hostname is set to a unique string that specify the plat | ``raspberrypi4-64.local`` | ``intel-corei7-64.local`` - | ``imx8mm-lpddr4-evk.local`` .. note:: For this to work, your PC needs to support zeroconf_. The hostname must be unclaimed. diff --git a/source/glossary/index.rst b/source/glossary/index.rst index 4482a630f..e4d057c5d 100644 --- a/source/glossary/index.rst +++ b/source/glossary/index.rst @@ -48,7 +48,6 @@ Glossary * :ref:`Updating, LmP ` * :ref:`Test plan, LmP ` * :ref:`Customizing, LmP ` - * :ref:`Porting, LmP ` Target A description of the software a device should run. @@ -113,8 +112,6 @@ Glossary An approach in public-key cryptography based on elliptic curves over finite fields. This allows for smaller keys than otherwise, but with an equivalent security level. - * :ref:`Security, Secure Element ` - ECIES Elliptic Curve Integrated Encryption Scheme Protocol to securely encrypt data using an EC public key that can only be decrypted by the private key owner. @@ -155,7 +152,6 @@ Glossary Supported for Factory PKI and storage of device keys. * :ref:`Secure Element TPM Reference Manual, PKCS #11 Support ` - * :ref:`EdgeLock™ SE05x Reference Manual, Importing Secure Objects into PKCS #11 Tokens ` * :ref:`Linux Disk Encryption Reference Manual, PKCS #11 Tokens ` * `TEE PKCS #11 Implementation (external) `_ @@ -171,7 +167,6 @@ Glossary * :ref:`Device Gateway PKI User Guide, Device Gateway PKI ` * :ref:`Factory Account Roles User Guide, Factory PKI Management ` - * :ref:`iMX Secure Boot Reference Manual, PKI tree ` * :ref:`Factory Registration Reference Manual, Device Gateway PKI ` Secure Boot @@ -179,7 +174,6 @@ Glossary * :ref:`Security, Secure Boot ` * :ref:`Security, UEFI Secure Boot ` - * :ref:`Security, Machines With Secure Boot ` Secure World Trusted Execution Environment (:term:`TEE`) on ARM. @@ -189,8 +183,6 @@ Glossary Trusted Execution Environment. In general, a hardware based component where code can run. - * :ref:`Porting Guide, including OP-TEE ` - * :ref:`EdgeLock SE05x Reference Manual ,OP-TEE Use ` * :ref:`Factory Keys, OP-TEE Keys ` TF-A @@ -248,7 +240,6 @@ Glossary * :ref:`OTA Reference Manual, Fleet Wide Configuration ` * :ref:`OTA Production Devices Reference Manual, Fleet Production Targets ` - * :ref:`Revoke Secure Boot Keys on i.MX, Revoke a Key for Devices in a Fleet ` Device Tag Instructs the Device Gateway to return the corresponding set of TUF metadata. @@ -362,7 +353,6 @@ Glossary These generally follow the convention of ``meta-``. You can read more about BSP layers in the Yocto Project's `BSP developer guide `_ - * :ref:`FoundriesFactory Porting Guide ` * :ref:`Linux Layers Reference Manual, LmP BSP Layers ` Distro @@ -481,21 +471,6 @@ Glossary * :ref:`Building From Source Reference Manual, Setup Work Environment; MACHINE target ` * :ref:`Factory Definition Reference Manual, Machine Name ` - UUU - Universal Update Utility - A manufacturing tool designed to flash i.MX boards with a given image. - :term:`mfgtools` uses configuration files with the ``.uuu`` extension. - - * `UUU GitHub Repository `_ - * :ref:`i.MX HABv4 Secure Boot Security Reference Manual, Programming the A7 fuses with UUU ` - * :ref:`i.MX AHAB Secure Boot Security Reference Manual, Closing the board Using UUU ` - - SE050 - The EdgeLock SE05x Secure Element. - - * :ref:`ref-secure-element` - * :ref:`Security Reference Manual, SE05x Enablement ` - EVK Evaluation kit. A board/hardware used for evaluating and developing before production. @@ -532,15 +507,3 @@ Glossary * :ref:`LmP Linux Kernel Reference Manual, LmP Kernel Configuration Fragments ` - RPMB - Replay Protected Memory Block. - Used as secure storage. - - * :ref:`Machines with Secure Aspects Enabled Reference Manual, Accessing RPMB Secure Storage ` - - mfgtools - Freescale/NXP® I.MX Chip tools. - Also see :term:`UUU`. - - * `mfgtools GitHub Repository `_ - diff --git a/source/index.rst b/source/index.rst index 3a4496baf..b742e7573 100644 --- a/source/index.rst +++ b/source/index.rst @@ -25,9 +25,6 @@ Documentation Overview * Advanced use cases and technical details are in the :ref:`Reference Manual `. -* For adding support for a machine not already supported by the FoundriesFactory platform, - see the :ref:`ref-pg`. - .. toctree:: :maxdepth: 2 :caption: Getting Started @@ -57,13 +54,6 @@ Documentation Overview reference-manual/index -.. toctree:: - :maxdepth: 2 - :caption: Porting Guide - :name: sec-porting-guide - - porting-guide/pg.rst - .. toctree:: :caption: Appendix :name: sec-appendix diff --git a/source/porting-guide/pg-distro-lmp-base.rst b/source/porting-guide/pg-distro-lmp-base.rst deleted file mode 100644 index b305c92c6..000000000 --- a/source/porting-guide/pg-distro-lmp-base.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _ref-pg-lmp-base: - -``DISTRO lmp-base`` for Easy Kernel Image Access ---------------------------------------------------- - -The default :term:`distro` used by a Factory is ``lmp``. -It is designed to provide the secure and updatable environment needed for the operation of an end product. -However, this distro configuration is not ideal during the porting process. -Therefore we also support another distro configuration: ``lmp-base``. -This provides an easier development environment, -as it has a boot directory which includes the Linux Kernel image and the DTB file, and a read-writable :term:`rootfs`. -See detailed information on how lmp and lmp-base differ under :ref:`ref-linux-distro`. - -In the following sections, the focus is on the boot flow (1) shown previous on :numref:`ref-pg-boot-flow-diagram`. -This boot flow is common on the i.MX8 and i.MX8M SoC families. -It is also common for i.MX6 and i.MX7 SoC families, however TF-A is not supported for these SoC families, -and is excluded from the boot flow. diff --git a/source/porting-guide/pg-how-to-plan.rst b/source/porting-guide/pg-how-to-plan.rst deleted file mode 100644 index dd611fe06..000000000 --- a/source/porting-guide/pg-how-to-plan.rst +++ /dev/null @@ -1,25 +0,0 @@ -How to Plan the Porting ------------------------ - -According to the boot flow described in :numref:`ref-pg-boot-flow-diagram`, some required packages are clear: -U-Boot, OP-TEE, TF-A, and the Linux® Kernel. -The recommendation is to start with the porting of these packages directly after creating a machine configuration file. - -Once the basic integration is complete, you will want to enable additional features. -This includes firmware not critical for boot, such as Bluetooth or Wi-Fi firmware. -Next, port any applications, and continue development as needed. - -In short, the recommended order is: - -1. Machine configuration file -2. SPL and U-Boot proper -3. OP-TEE and TF-A -4. Linux Kernel - -.. note:: - - Remember, it is recommended to use ``DISTRO=lmp-base`` during the porting task. - -Next in this guide, each of the steps listed are detailed, focusing on the recommendations to work with each package. -It is important to note that there are use cases when a board has peculiarities which may not be listed here. -You will need to understand and cover them during the port. diff --git a/source/porting-guide/pg-lmp-factory-custom.rst b/source/porting-guide/pg-lmp-factory-custom.rst deleted file mode 100644 index 960cb29cc..000000000 --- a/source/porting-guide/pg-lmp-factory-custom.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _ref-pg-lmp-factory-custom: - -``lmp-factory-custom`` -^^^^^^^^^^^^^^^^^^^^^^ - -Your Factory includes a file, ``conf/machine/include/lmp-factory-custom.inc``. -This can be used to replace or extend options as defined by ``meta-lmp``. -It works to customize the overall behavior of LmP, focusing on the target machine. - -This applies to cases when the porting does not create a new machine configuration file, -and only overrides the definition from an existing machine. diff --git a/source/porting-guide/pg-machine-conf.rst b/source/porting-guide/pg-machine-conf.rst deleted file mode 100644 index dc4417777..000000000 --- a/source/porting-guide/pg-machine-conf.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. _ref-pg-machine-conf: - -Machine Configuration File -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The machine configuration file describes hardware in terms of variables such as: - -.. Glossary:: - - SERIAL_CONSOLES - Describe the serial console used on this machine - - MACHINE_EXTRA_RRECOMMENDS - List the packages recommended during run time for this machine - - UBOOT_DTB_NAME - Set the DTB file name used by U-Boot - - UBOOT_CONFIG - Describe the configuration used for U-Boot on this machine - - MACHINE_FEATURES - List the machine features for this machine used to configure the - Yocto Project packages and tools - - IMXBOOT_TARGETS - State the target name to be used with imx-boot, a - critical package to the bring up of i.MX8 SoC family boards - -The machine configuration file from a reference board can serve as a reminder on what variable set is important to define. - -It is possible that the porting task targets a new machine configuration file. -In this case, any machine related configuration should be placed in the new machine configuration file. diff --git a/source/porting-guide/pg-new-machine.rst b/source/porting-guide/pg-new-machine.rst deleted file mode 100644 index 12c813d77..000000000 --- a/source/porting-guide/pg-new-machine.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. _ref-pg-description: - -Requirements Before Porting to the LmP -====================================== - -It is out of the scope of this guide to detail the steps of creating a BSP with -bootloader, operating system support, and other critical packages. -The recommendation is to search for the SoC vendor porting guide. -This usually details how to port the default BSP to another board. - -LmP provides a set of bootloaders and operating systems updated with the latest known vulnerability fixes. -The recommendation is to use these packages as a base for creating the new BSP. -This leads to the creation of append files (`.bbappend``) for the recipes of the packages. - -LmP supports a wide variety of SoC families—from different vendors with different boot flows. -The following image shows three examples of boot flow currently supported by LmP: - -.. _ref-pg-boot-flow-diagram: - -.. figure:: /_static/porting-guide/boot-flow-diagram.jpg - :align: center - :width: 300 - - Different boot flow being executed by machines supported by LmP diff --git a/source/porting-guide/pg-reference.rst b/source/porting-guide/pg-reference.rst deleted file mode 100644 index bac4133fb..000000000 --- a/source/porting-guide/pg-reference.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _ref-pg-reference-board: - -Finding a Similar Supported Reference Board -------------------------------------------- - -For some projects, it is easy to understand which reference board is closest to the one being ported. -It is common that in early stages, the project starts with a reference board. -When that is the case, the reference board is obvious; is only a matter of searching :ref:`ref-linux-supported` to check if this is supported. - -The other case is when it is not an obvious answer. -The task of searching for the closest reference board requires looking for one which shares the same SoC. -This is usually described in the machine configuration file by the tag ``@SOC``. - -When searching for ``@SOC`` through the meta-layers, you may find more than one machine with the same SoC. -The suggestion here is to prefer the machine from the SoC vendor. - -The SoC vendor is usually present on the tag ``@NAME`` in the machine configuration file. - -In this document, there are several examples where i.MX8M Mini :term:`EVK` is used as a reference board. diff --git a/source/porting-guide/pg-spl-checklist.rst b/source/porting-guide/pg-spl-checklist.rst deleted file mode 100644 index f11ca18e6..000000000 --- a/source/porting-guide/pg-spl-checklist.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. _ref-pg-spl-flow-index: - -Checklist -========= - -The checklist goal is to make sure everything needed is in place: - -1. Find the similar reference board (:ref:`ref-pg-reference-board`) -2. Change distro from ``lmp`` to ``lmp-base`` (:ref:`ref-pg-lmp-base`) -3. Create the machine configuration file (:ref:`ref-pg-machine-conf`) -4. Port u-boot (:ref:`ref-pg-spl-uboot`) - - a. Enable SPL - -5. Enable MFGTool (:ref:`ref-pg-spl-mfgtool`) -6. Port OP-TEE (:ref:`ref-pg-spl-optee`) -7. Configure TF-A (:ref:`ref-pg-spl-uboot`) -8. Test the first boot, check the images being loaded -9. Port the Linux Kernel (:ref:`ref-pg-spl-kernel`) -10. Port the Device tree (:ref:`ref-pg-spl-kernel`) -11. Port the Linux Kernel BSP configuration fragment (:ref:`ref-pg-spl-kernel`) -12. When the port is done, go back to ``lmp`` distro and start to configure the platform as needed diff --git a/source/porting-guide/pg-spl-kernel.rst b/source/porting-guide/pg-spl-kernel.rst deleted file mode 100644 index 8d1a6a4f8..000000000 --- a/source/porting-guide/pg-spl-kernel.rst +++ /dev/null @@ -1,124 +0,0 @@ -.. _ref-pg-spl-kernel: - -Kernel and Device Tree -====================== - -A goal of the LmP is to be as close as possible to the mainline kernel when possible, -or to use the community kernel support, depending on the board vendor. -See `supported kernel trees `_. - -Unlike U-Boot, not all patches need to be appended to the kernel recipe. -You need to append patches only to include features or drivers that are not upstreamed to the mainline kernel. -The device tree files can be deployed to the ``lmp-device-tree`` directory in ``meta-subscriber-overrides``. -The build generates the output ``.dtb`` file. - -.. code-block:: none - - recipes-bsp/device-tree/ - ├── lmp-device-tree - │ └── .dts - └── lmp-device-tree.bbappend - -The strategy of using the dts file separate from the Linux® Kernel source helps to avoid forking the kernel when including any new dtb. -For this, LmP relies on ``lmp-device-tree``, which is based on the Yocto Project device-tree class. - - -For the kernel configuration, LmP makes use of the kernel fragments, using the Yocto Project mechanism also present in ``linux-yocto``. -This is different from the also common “in-tree” configuration, which uses the file ``defconfig`` to configure the kernel. - -.. _ref-pg-how-to-configure-linux: - -How To Configure the Linux Kernel ---------------------------------- - -The kernel configuration files are part of the ``lmp-kernel-cache`` repo, which have a helpful ``README`` file, and is also described in the :ref:`ref-linux-fragments`. - - -In short, there are several well known kernel features defined in fragment files (such as the bluetooth feature) alongside other configurations. -The ``bsp`` directory is where fragments related to the BSP are stored. - -The goal is to create a ``.bbappend`` to include the fragments which define the target machine. -The set of files should look like the following: - -.. code-block:: none - - ├── linux- - │ ├── patch-file.patch - │ ├── another-patch-file.patch - │ └── kernel-meta - │ └── bsp - │ └── - │ ├── .cfg - │ ├── .scc - │ └── -standard.scc - └── linux-_%.bbappend - -Where ```` is the kernel name for the particular kernel recipe being used. -The patch files are potential patches applied by the ``.bbappend`` file on top of the kernel source code. -```` is the machine name. - -The ```` is a BSP subgroup, following the lmp-kernel-cache directory organization. -For example, ``imx`` or ``raspberrypi``, depending on -the target machine. - -It is common that the BSP fragment is defined in a ``-standard.scc`` file, -with features and configurations being organized between the other files. - -The ``linux-_%.bbappend`` looks like: - -.. code-block:: none - - FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" - SRC_URI += " \ - file://kernel-meta/bsp//.cfg \ - file://kernel-meta/bsp//.scc \ - file://kernel-meta/bsp//-standard.scc \ - “ - -Start from the BSP kernel fragment from a close reference board, copy over those files relevant to the board. -Change the file name, and review the content configurations while reviewing the schematics or a list of needed configurations. - -.. _ref-pg-new-driver: - -Adding a New Kernel Driver --------------------------- - -.. note:: - Out of tree kernel drivers are not supported by Foundries.io™. New modules should be fully supported by the customer. - -The recommended way to add a driver or module to the Linux kernel source is by creating a recipe file under ``recipes-kernel/kernel-modules/``: - -.. code-block:: none - - recipes-kernel/kernel-modules/ - └── - ├── - │  ├── COPYING - │  ├── Makefile - │  ├── .c - │  └── .h - └── _.bb - -Where ``_.bb`` is: - -.. code-block:: none - - SUMMARY = "Module summary" - LICENSE = "GPLv2" - LIC_FILES_CHKSUM = "file://COPYING;md5=12f884d2ae1ff87c09e5b7ccc2c4ca7e" - - inherit module - - SRC_URI = " \ - file://Makefile \ - file://.c \ - file://.h \ - file://COPYING \ - " - - S = "${WORKDIR}" - - KERNEL_MODULE_AUTOLOAD:append = "" - -Make sure to provide the source code and header for the new module, as well as the license and Makefile. -Also make sure to adjust the provided values as needed by the recipe (``LICENSE``, ``PV``). diff --git a/source/porting-guide/pg-spl-mfgtool.rst b/source/porting-guide/pg-spl-mfgtool.rst deleted file mode 100644 index 6e86b1c25..000000000 --- a/source/porting-guide/pg-spl-mfgtool.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _ref-pg-spl-mfgtool: - -MFGTool For i.MX Boards -======================= - -MFGTool is the NXP® tool to deploy images to an i.MX-based board. -LmP provides two scripts to deploy the build artifacts using this tool: - -- ``bootloader.uuu``: used to deploy SPL and U-Boot FIT image (u-boot.itb) -- ``full_image.uuu``: used to deploy the entire image, from SPL to rootfs - -This support can be extended to support other features, such as fusing and closing a board for secure boot. -Note that this case is not covered in this document. - -The ``mfgtool-files`` package is built by the CI when the ``mfg_tools`` node is included in ``factory-config.yml`` :ref:`ref-factory-definition`. -It is built locally when ``DISTRO=lmp-mfgtool`` is set. - -To enable a custom ``mfgtool-files`` package, you must provide the following configuration: - -- **U-Boot**: you to provide a configuration file (``lmp.cfg``) to be used for the ``mfgtool-files`` U-Boot build (``u-boot-fio-mfgtool``). - This is similar to the configuration file used by ``DISTRO=lmp``, but should include SDP, USB and fastboot support. - -- **OP-TEE**: Same for the standard ``u-boot-fio support``. - You need to provide machine-specific configuration to OP-TEE for the ``mfgtool-files`` building (``optee-os-fio-mfgtool``). - This includes OP-TEE machine name, UART address, and overlay address. - -- ``mfgtool-files``: The ``bootloader.uuu.in`` and ``full_image.uuu.in`` input files to generate the MFGTool scripts. - You can provide the same files as the reference board support in LmP. - -.. code-block:: none - - ├── recipes-bsp - │ └── u-boot - │ ├── u-boot-fio-mfgtool - │ │ └── - │ │ └── lmp.cfg - │ └── u-boot-fio-mfgtool_%.bbappend - ├── recipes-security - │ └── optee - │ └── optee-os-fio-mfgtool_3.10.0.bbappend - └── recipes-support - └── mfgtool-files - ├── mfgtool-files - │ └── - │ ├── bootloader.uuu.in - │ └── full_image.uuu.in - └── mfgtool-files_%.bbappend diff --git a/source/porting-guide/pg-spl-optee.rst b/source/porting-guide/pg-spl-optee.rst deleted file mode 100644 index 85351ad6a..000000000 --- a/source/porting-guide/pg-spl-optee.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _ref-pg-spl-optee: - -OP-TEE (When Applicable) -======================== - -OP-TEE is deployed as part of the FIT image. -Foundries.io has its own OP-TEE recipes. -You will need to provide machine-specific configuration in ``meta-subscriber-overrides`` for the OP-TEE build, e.g. -OP-TEE machine name, UART address, and overlay address. -The recommendation is to use the reference board OP-TEE support for the ``OPTEEMACHINE``. - -``recipes-security/optee/optee-os-fio_3.10.0.bbappend``: - -.. code-block:: none - - OPTEEMACHINE: = "imx-mx8mmevk" - EXTRA_OEMAKE:append: = " \ - CFG_UART_BASE=UART4_BASE \ - CFG_NXP_CAAM=y CFG_RNG_PTA=y \ - CFG_DT=y CFG_EXTERNAL_DTB_OVERLAY=y CFG_DT_ADDR=0x43200000 \ - " - -.. note:: - - If you choose to not use the reference board as the ``OPTEEMACHINE``, - further considerations are needed to integrate OP-TEE support into LmP. - See :ref:`ref-sec-tfa-optee`. diff --git a/source/porting-guide/pg-spl-uboot-env.rst b/source/porting-guide/pg-spl-uboot-env.rst deleted file mode 100644 index adf9f74a6..000000000 --- a/source/porting-guide/pg-spl-uboot-env.rst +++ /dev/null @@ -1,101 +0,0 @@ -.. _ref-pg-uboot-env: - -U-Boot Environment and Boot Script -================================== - -The last step to configure U-Boot in LmP is to provide the boot environment (for ``lmp-base``) and the boot command. -You can start by using the reference board support, adjusting the files accordingly for the target board. - -For the ``lmp-base`` distro, provide the boot environment input file ``uEnv.txt.in``, which sets the needed variables for booting: - -``u-boot-base-scr/imx8mmevk/uEnv.txt.in``: - -.. code-block:: none - - devnum=2 - devtype=mmc - bootcmd_args=setenv bootargs console=tty1 console=${console} root=/dev/mmcblk2p2 rootfstype=ext4 rootwait rw - bootcmd_dtb=fatload ${devtype} ${devnum}:1 ${fdt_addr} ${fdt_file} - bootcmd_load_k=fatload ${devtype} ${devnum}:1 ${loadaddr} ${image} - bootcmd_run=booti ${loadaddr} - ${fdt_addr} - bootcmd=run bootcmd_args; run bootcmd_dtb; run bootcmd_load_k; run bootcmd_run - -You will need to define the ``devnum`` and ``bootcmd_args`` root parameters to meet the eMMC index on your board. -Other board specific variables can be set in this file if needed, like ``fdt_file`` or console configurations. - -After ``uEnv.txt.in`` is in place, provide ``boot.cmd``. -This loads this environment and boots to kernel: - -``u-boot-base-scr/imx8mmevk/boot.cmd``: - -.. code-block:: console - - fatload mmc ${emmc_dev}:1 ${loadaddr} /uEnv.txt - env import -t ${loadaddr} ${filesize} - run bootcmd - -For the ``lmp-base`` distro, these files live in ``u-boot-base-scr``: - -.. code-block:: none - - recipes-bsp/u-boot/ - ├── u-boot-base-scr - │ └── - │ ├── boot.cmd - │ └── uEnv.txt.in - └── u-boot-base-scr.bbappend - -Also for the ``lmp`` distro, the only file that needs to be provided is ``boot.cmd``. -Note that in this case, it handles both the environment and the boot command: - -``u-boot-ostree-scr-fit/imx8mmevk/boot.cmd``: - -.. code-block:: shell - - echo "Using freescale_${fdt_file}" - - # Default boot type and device - setenv bootlimit 3 - setenv devtype mmc - setenv devnum 2 - setenv bootpart 1 - setenv rootpart 2 - - # Boot image files - setenv fdt_file_final freescale_${fdt_file} - setenv fit_addr ${initrd_addr} - - # Boot firmware updates - setenv bootloader 42 - setenv bootloader2 300 - setenv bootloader_s 1042 - setenv bootloader2_s 1300 - setenv bootloader_image "imx-boot" - setenv bootloader_s_image ${bootloader_image} - setenv bootloader2_image "u-boot.itb" - setenv bootloader2_s_image ${bootloader2_image} - setenv uboot_hwpart 1 - - @@INCLUDE_COMMON@@ - -You will need to define ``devnum`` as expected by the board. -Make sure the ``initrd_addr`` is set in U-Boot correctly. -Otherwise you may need to set the ``initrd_addr`` (as well as any other missing addresses) in this file. - - -.. note:: - - If porting to a new SoC not supported in LmP, - the boot firmware offsets also need to be calculated and adjusted as described under :ref:`ref-sec-tfa-optee`. - -The boot.cmd for the ``lmp`` distro lives in: - -.. code-block:: none - - recipes-bsp/u-boot/ - ├── u-boot-ostree-scr-fit - │ └── - │ └── boot.cmd - └── u-boot-ostree-scr-fit.bbappend - -After providing these files, LmP has all the needed configuration to boot U-Boot and get to the kernel. diff --git a/source/porting-guide/pg-spl-uboot-fragments.rst b/source/porting-guide/pg-spl-uboot-fragments.rst deleted file mode 100644 index 501ad7bf9..000000000 --- a/source/porting-guide/pg-spl-uboot-fragments.rst +++ /dev/null @@ -1,66 +0,0 @@ -Creating the U-Boot Configuration Fragments -=========================================== - -The two fragments are: - -* ``lmp-base-cfg`` -* ``lmp.cfg`` - -The ``meta-lmp`` layer uses ``.cfg`` configuration fragments to append and override configurations in the board ``defconfig`` file. - -``lmp-base.cfg`` is used for ``DISTRO=lmp-base``, while ``lmp.cfg`` is used for ``DISTRO=lmp``. - -The ``.cfg`` file enables the features required for SPL and U-Boot proper to support LmP. -This includes booting SPL, verifying the signature of the consequent loaded images, enabling eMMC secure storage, and custom boot command. - -To create this file, use the reference board support in LmP and modify the configuration files as needed. -The list of supported boards and their ``.cfg`` files can be found in the ``meta-lmp`` -`repo `_. - -For example, see ``imx8mmevk/lmp-base.cfg``: - -.. code-block:: shell - - CONFIG_SPL_DM=y - CONFIG_SPL_OF_CONTROL=y - CONFIG_SPL_FIT=y - CONFIG_SPL_LOAD_FIT=y - # CONFIG_SPL_FIT_IMAGE_TINY is not set - # CONFIG_CMD_DEKBLOB is not set - # CONFIG_SPL_DM_USB is not set - CONFIG_OF_LIBFDT_OVERLAY=y - CONFIG_FIT=y - CONFIG_FIT_SIGNATURE=y - CONFIG_FIT_VERBOSE=y - CONFIG_LEGACY_IMAGE_FORMAT=y - CONFIG_PARTITION_UUIDS=y - CONFIG_CMD_XIMG=y - CONFIG_SUPPORT_EMMC_RPMB=y - CONFIG_SUPPORT_EMMC_BOOT=y - # CONFIG_ENV_IS_IN_MMC is not set - CONFIG_ENV_IS_IN_FAT=y - CONFIG_ENV_FAT_INTERFACE="mmc" - CONFIG_ENV_FAT_DEVICE_AND_PART="2:1" - CONFIG_ENV_SIZE=0x4000 - CONFIG_CMD_IMPORTENV=y - CONFIG_CMD_EDITENV=y - CONFIG_CMD_SAVEENV=y - CONFIG_USE_BOOTCOMMAND=y - CONFIG_BOOTCOMMAND="fatload mmc ${emmc_dev}:1 ${loadaddr} /boot.scr; - source ${loadaddr}; reset" - -Most of the configuration is generic to all boards. -You will need to pay attention to board-specific configuration. -In this case: - -.. code-block:: shell - - CONFIG_ENV_FAT_DEVICE_AND_PART="2:1" - -Where ``2`` represents the uSDHC index for the eMMC device in imx8mmevk. -You should align this with what is expected for your board. - -.. note:: - - It is recommended to set an eMMC device as the boot target if applicable. - In i.MX targets, ``lmp-base`` distro does not support SD card boot at this time. diff --git a/source/porting-guide/pg-spl-uboot.rst b/source/porting-guide/pg-spl-uboot.rst deleted file mode 100644 index 7a8c8c4eb..000000000 --- a/source/porting-guide/pg-spl-uboot.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _ref-pg-spl-uboot: - -U-Boot -====== - -You can get the latest U-Boot support from either the board vendor, or the community. -The current U-Boot versions supported in ``meta-lmp`` (``u-boot-fio``) -can be found `in the repo `_. - -It is possible that there is no U-Boot support for the target board, or there is only support for an old U-Boot version. -In this case, you should update/port to a newer U-Boot version, as supported in ``u-boot-fio``. - -.. toctree:: - :maxdepth: 2 - - pg-spl - pg-spl-optee - pg-spl-uboot-fragments - pg-spl-uboot-env diff --git a/source/porting-guide/pg-spl.rst b/source/porting-guide/pg-spl.rst deleted file mode 100644 index 002df3f07..000000000 --- a/source/porting-guide/pg-spl.rst +++ /dev/null @@ -1,55 +0,0 @@ -SPL -=== - -In boards using SPL as the second stage bootloader, -like the supported i.MX targets, SPL is used to load and verify the integrity of the FIT image (i.e. ``u-boot.itb`` file). -The FIT image includes U-Boot proper, DTB, OP-TEE, and Arm Trusted Firmware (ARMv8), and possibly other firmware. -SPL verifies the signature of these sequentially loaded images, signed as part of FoundriesFactory CI. -It checks to make sure they were generated with the expected keys. - -.. note:: - - At this moment, Secure Boot is only supported on SPL-based targets, as LmP relies on a signed SPL as the root of trust. - -U-Boot should support SPL, so ``meta-lmp`` handles the SPL and FIT image generation and signing of the FIT image components. -If SPL is not yet supported, you can enable it by following the -`U-Boot documentation and guidelines `_. -Append it to their U-Boot porting, or `contact support `_ for guidance. - -Next, review the board-specific U-Boot patches and align them with the respective u-boot-fio version. -Commits can be applied with ``git rebase`` or ``git cherry-pick`` on top of the ``u-boot-fio`` branch. -The patches can be copied to the appropriate directory under ``meta-subscriber-overrides`` and included in a ``u-boot-fio`` .bbappend file. -`Devtool `_ can be used during the process. -As described in the Yocto Project documentation: - -.. code-block:: console - - $ devtool modify u-boot-fio - $ devtool finish --force-patch-refresh u-boot-fio - -The resultant source code from the merge of ``u-boot-fio`` and board-specific patches can now be compiled and tested on a target. -In some cases, the user may need to create additional patches in order to align their board support with the ``u-boot-fio`` tree. - -For example: - -.. code-block:: none - - recipes-bsp/u-boot/ - ├── u-boot-fio - │ └── - │ ├── 0001-add--support.patch - │ ├── 0002-add-feature.patch - │ ├── 0003-fix-bug.patch - │ └── 0004-align-with-u-boot-fio.patch - └── u-boot-fio_%.bbappend - -If applicable, you may need to do the same procedure for TF-A patches. -This would be the case for ARMv8 targets that have additional implementations by the vendor. -Some considerations on TF-A to comply with LmP can be found in :ref:`ref-sec-tfa-optee`. - -.. note:: - - If the target is based on imx8m*, you may also want to pay attention to the provided firmwares. - This includes the likes of DDR and HDMI (when applicable), and the vendor ``imx-mkimage`` implementation. - The vendor changes applied to ``u-boot-fio`` should match with the related projects (``imx-atf``, ``imx-mkimage``). - Otherwise the ``u-boot-fio`` porting will not work. diff --git a/source/porting-guide/pg.rst b/source/porting-guide/pg.rst deleted file mode 100644 index 2fcebd2e7..000000000 --- a/source/porting-guide/pg.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. _ref-pg: - -Factory Porting Guide -====================== - -Introduction ------------- - -This section provides guidelines and suggestions on how to add support for a machine not already supported by the FoundriesFactory™ Platform. -The list of currently supported machines can be found under :ref:`ref-linux-supported`. - -Needing to port a board could be due to: - -* A new project bringing new hardware to their Factory, -* An existing project that is migrating -* Adding new hardware. - -Another possible reason is to customize hardware aspects of well known hardware, but with another machine file. - -The strategy used in this guide is to add support on top of the existing structure provided by the Linux® microPlatform (LmP). -The LmP provides the needed configuration for the packages, images, and classes. -Also provided is the container runtime and OTA infrastructure integration. - -As the LmP uses the Yocto Project tools, the packages and configuration files follow the Yocto Project concepts, -and are used in this guide. -Some knowledge of the Yocto Project and embedded Linux development are required. - -.. tip:: - - A `support request `_ can be submitted in case help is needed. - - -In the next section, there is a description on how to find a similar reference board to base the porting work. -After that, there is a list of what is needed before starting, and how to plan the porting. -This is followed by the list of the needed packages and configurations, with suggestions on how to proceed with each one. -Lastly, a checklist is provided to help ensure all required steps have been taken. - -.. toctree:: - :maxdepth: 3 - - pg-reference - pg-new-machine - pg-distro-lmp-base - pg-how-to-plan - pg-machine-conf - pg-lmp-factory-custom - pg-spl-uboot - pg-spl-kernel - pg-spl-mfgtool - pg-spl-checklist - - diff --git a/source/reference-manual/factory/factory-definition.rst b/source/reference-manual/factory/factory-definition.rst index 434bdcd41..85feb4496 100644 --- a/source/reference-manual/factory/factory-definition.rst +++ b/source/reference-manual/factory/factory-definition.rst @@ -86,7 +86,7 @@ Variables to be used with metadata and artifacts. params: EXAMPLE_VARIABLE_1: hello_world machines: - - imx8mm-lpddr4-evk + - qemuarm64 image_type: lmp-factory-image ref_options: refs/heads/main: @@ -100,12 +100,6 @@ Variables to be used with metadata and artifacts. - tag: postmerge refs/heads/feature1: - tag: feature1 - mfg_tools: - - machine: imx8mm-lpddr4-evk - image_type: mfgtool-files - params: - DISTRO: lmp-mfgtool - EXTRA_ARTIFACTS: "mfgtool-files.tar.gz" lmp: preloaded_images: @@ -165,11 +159,11 @@ ref_options: params: IMAGE: lmp-factory-image machines: - - imx8mn-ddr4-evk + - qemuarm64 ref_options: refs/heads/feature1: machines: - - imx8mn-ddr4-evk + - qemuarm64 params: IMAGE: lmp-mini-image @@ -178,18 +172,6 @@ ref_options: **Optional:** Control how OTA_LITE tags are handled. See :ref:`ref-advanced-tagging` for more details. - mfg_tools:|br| ``- machine: `` - **Optional:** Do an OE build to produce manufacturing tooling for a given ``MACHINE``. - This is used to facilitate the manufacturing process, and to ensure secure boot on devices. - Currently, only NXP® tools are supported. - - **Default:** None - - image_type: ```` - **Optional:** Sets the name of the recipe to use to build mfg_tools. - - **Default:** ``mfgtool-files`` |br| (from `meta-lmp-base/recipes-support/mfgtool-files/mfgtool-files_0.1.bb `_) - Variables ^^^^^^^^^ diff --git a/source/reference-manual/linux/factory-device-reset.rst b/source/reference-manual/linux/factory-device-reset.rst index a850f99ae..900dbbd55 100644 --- a/source/reference-manual/linux/factory-device-reset.rst +++ b/source/reference-manual/linux/factory-device-reset.rst @@ -48,7 +48,3 @@ Contents of ``/var/`` are partially removed. compose-apps to be preserved. ``/var/lib/`` is preserved as the Docker objects are stored there. -RPMB -~~~~ - -Currently, :term:`RPMB` is not cleared in either reset procedures. diff --git a/source/reference-manual/linux/linux-disk-encryption.rst b/source/reference-manual/linux/linux-disk-encryption.rst index c69755185..fd23346a7 100644 --- a/source/reference-manual/linux/linux-disk-encryption.rst +++ b/source/reference-manual/linux/linux-disk-encryption.rst @@ -119,11 +119,11 @@ This is required for supporting boot firmware updates on devices with encrypted For supporting ``/boot`` being in a separated partition at the final image the selected ``WKS_FILE`` needs to support split boot. UEFI based devices already have such setup by default, but on most ARM/ARM64 devices a custom WKS might be required. -As an example, iMX8-based devices should use ``sdimage-imx8-spl-split-boot-sota.wks.in`` instead of the default ``sdimage-imx8-spl-sota.wks.ini`` file: +As an example, ``sdimage-split-boot-sota.wks.in`` instead of the default ``sdimage-sota.wks.ini`` file: .. code-block:: none - WKS_FILE:sota:mx8mm-nxp-bsp = "sdimage-imx8-spl-split-boot-sota.wks.in" + WKS_FILE:sota = "sdimage-split-boot-sota.wks.in" .. note:: diff --git a/source/reference-manual/linux/linux-distro.rst b/source/reference-manual/linux/linux-distro.rst index 56b16c264..6f91f7d71 100644 --- a/source/reference-manual/linux/linux-distro.rst +++ b/source/reference-manual/linux/linux-distro.rst @@ -14,7 +14,6 @@ The LmP supported distros are: * ``lmp`` * ``lmp-base`` -* ``lmp-mfgtool`` * ``lmp-wayland`` * ``lmp-xwayland`` @@ -51,13 +50,6 @@ It overrides some configurations from ``lmp`` to generate a friendly system for * The Linux Kernel binary, along with the required DTB files, are provided as separate files, instead of inside a boot image. This lets the binaries be replaced for testing purposes. -.. _ref-lmp-mfgtool: - -lmp-mfgtool ------------ - -The distro used to generate the ``mfgtool-files`` which provide the deploy and update tool for some machines. - .. _ref-lmp-wayland-xwayland: lmp-wayland/lmp-xwayland diff --git a/source/reference-manual/linux/linux-kernel.rst b/source/reference-manual/linux/linux-kernel.rst index 00fbd26bf..0d0d6391b 100644 --- a/source/reference-manual/linux/linux-kernel.rst +++ b/source/reference-manual/linux/linux-kernel.rst @@ -22,27 +22,18 @@ The fragments repository works similarly to the upstream ``yocto-kernel-cache`` As such, the same development workflow and documentation applies. See the `Yocto Project Linux Kernel Development Manual`_ on how to work with the kernel metadata and configuration fragments. -The Porting Guide includes :ref:`ref-pg-how-to-configure-linux`. -This details how to add a custom Linux Kernel configuration, which can be used to add: - -* the complete machine configuration. - -* fragments: a set of ``CONFIG_`` variables working to change - a default machine configuration. - .. _Yocto Project Linux Kernel Development Manual: https://docs.yoctoproject.org/4.0.6/kernel-dev/advanced.html LmP With Real-Time Linux Kernel -------------------------------- -The recipes that can be used for real-time Linux are either: +The recipe that can be used for real-time Linux is: * ``meta-lmp/meta-lmp-base/recipes-kernel/linux/linux-lmp-rt_git.bb`` -* ``meta-lmp/meta-lmp-base/recipes-kernel/linux/linux-lmp-fslc-imx-rt_git.bb`` -Theses are based on the ``linux-lmp`` recipe, extended to include the ``PREEMPT_RT`` patch-set (updated along with stable kernel updates). +This is based on the ``linux-lmp`` recipe, extended to include the ``PREEMPT_RT`` patch-set (updated along with stable kernel updates). -The instructions to change the default Linux kernel to real-time are described in the following sections. +The instructions to change the default Linux kernel to real-time are described in the following section. After making the changes, build the LmP image as usual. Building LmP with linux-lmp-rt @@ -56,17 +47,6 @@ set ``PREFERRED_PROVIDER_virtual/kernel`` to ``linux-lmp-rt`` : $ cat meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc PREFERRED_PROVIDER_virtual/kernel:intel-corei7-64 = "linux-lmp-rt" -Building LmP With linux-lmp-fslc-imx-rt -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In ``meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc``, -set ``PREFERRED_PROVIDER_virtual/kernel`` to ``linux-lmp-fslc-imx-rt`` : - -.. code-block:: console - - $ cat meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc - PREFERRED_PROVIDER_virtual/kernel:mx6ull-nxp-bsp = "linux-lmp-fslc-imx-rt" - LmP With Linux Upstream ------------------------ diff --git a/source/reference-manual/linux/linux-oss-compliance.rst b/source/reference-manual/linux/linux-oss-compliance.rst index 403457aa2..d0828a1b0 100644 --- a/source/reference-manual/linux/linux-oss-compliance.rst +++ b/source/reference-manual/linux/linux-oss-compliance.rst @@ -130,16 +130,6 @@ with the goal of disabling the GPLv3 packages. params: DISABLE_GPLV3: "1" - mfg_tools: - - machine: - params: - DISTRO: lmp-mfgtool - EXTRA_ARTIFACTS: mfgtool-files.tar.gz - IMAGE: mfgtool-files - DISABLE_GPLV3: "0" - -.. tip:: it is possible to enable or disable `DISABLE_GPLV3` on `mfgtool` targets, as shown above. - This is the only change needed, the meta-layers are handled in respect to the ``DISABLE_GPLV3`` variable. It is important to note that when using an image different than ``lmp-factory-image``, other packages might be used. diff --git a/source/reference-manual/linux/linux-update.rst b/source/reference-manual/linux/linux-update.rst index 103807ade..ab595d311 100644 --- a/source/reference-manual/linux/linux-update.rst +++ b/source/reference-manual/linux/linux-update.rst @@ -346,34 +346,6 @@ OP-TEE config differences can be spotted by diffing the two releases: Bring relevant changes from the reference machine to your machine code. -* **Mfgtool** (if applicable) - -.. note:: - Not all machines require/support ``mfgtool`` build. Currently, i.MX boards are supported. - -Check if the ``mfgtool-files`` from your reference machine have changed between the two releases. Mirror the changes to your machine. - -For i.MX: - - * Mfgtool scripts in v88: https://github.com/foundriesio/meta-lmp/tree/mp-88/meta-lmp-bsp/recipes-support/mfgtool-files/mfgtool-files/imx8mm-lpddr4-evk - - * Mfgtool scripts in v91: https://github.com/foundriesio/meta-lmp/tree/mp-91/meta-lmp-bsp/recipes-support/mfgtool-files/mfgtool-files/imx8mm-lpddr4-evk - -.. code-block:: console - - $ cd meta-lmp - $ git diff mp-88 mp-91 meta-lmp-bsp/recipes-support/mfgtool-files/mfgtool-files/imx8mm-lpddr4-evk/ - - -For the i.MX SoCs, the update process of ``mfgtool`` hardware support recipes like ``u-boot-fio-mfgtool``, ``linux-lmp-dev-mfgtool`` and ``optee-os-fio-mfgtool`` is the same for each component as described in the previous sections. - -.. tip:: - For Factory sources synced locally, the command line to set the build environment to enable ``bitbake -e`` commands for ``lmp-mfgtool`` is: - - .. code-block:: console - - MACHINE= DISTRO=lmp-mfgtool source setup-environment - Verifying Your Work ~~~~~~~~~~~~~~~~~~~ @@ -448,14 +420,11 @@ Here, the development branch is called ``devel``. Common Errors and Tips ~~~~~~~~~~~~~~~~~~~~~~ -* A good practice when debugging migration issues is to compare the reference machine changes from one LmP version to the other. Likely, the changes from the reference machine should be mirrored to your custom machine. +* A good practice when debugging migration issues is to compare the reference machine changes from one LmP version to the other. + Likely, the changes from the reference machine should be mirrored to your custom machine. * Working on the LmP update in a separate branch is highly recommended so it does not block your development branches. -* For machines that support :ref:`lmp-mfgtool distro `, use that for a quick debug iteration: there is no need to flash the whole image to verify U-Boot, for example. - -* Also for machines that support :ref:`lmp-mfgtool distro `, the suggestion is to keep a single source of patches for hardware support (for ``u-boot-fio``/``u-boot-fio-mfgtool`` and ``linux-lmp-fslc-imx``/``linux-lmp-dev-mfgtool``). This avoids duplicated code in the Factory. - For example: .. code-block:: console @@ -469,10 +438,8 @@ For example: │   └── lmp.cfg ├── u-boot-fio-.inc ├── u-boot-fio_%.bbappend - ├── u-boot-fio-mfgtool │   └── │   └── lmp.cfg - └── u-boot-fio-mfgtool_%.bbappend $ cat recipes-bsp/u-boot/u-boot-fio-.inc # common vendor u-boot-fio code @@ -487,9 +454,6 @@ For example: require u-boot-fio-.inc - $ cat recipes-bsp/u-boot/u-boot-fio-mfgtool_%.bbappend - FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:${THISDIR}/u-boot-fio:" - require u-boot-fio-.inc * You can find the list of patches appended to the sources by grepping ``SRC_URI``, for example Linux kernel: @@ -531,7 +495,3 @@ The previous recipe ``linux-lmp-dev-mfgtool.bb`` is now called ``linux-lmp-dev-m To avoid a build error, the ``meta-subscriber-overrides`` `.bbappend` should now be ``linux-lmp-dev-mfgtool_%.bbappend``. * Getting through these steps is not an easy task! Do not hesitate to contact `Foundries.io support `_ during your LmP update cycle. - -.. seealso:: - - :ref:`ref-pg` diff --git a/source/reference-manual/security/boot-software-updates-imx.rst b/source/reference-manual/security/boot-software-updates-imx.rst deleted file mode 100644 index 13bca9fc8..000000000 --- a/source/reference-manual/security/boot-software-updates-imx.rst +++ /dev/null @@ -1,436 +0,0 @@ -.. highlight:: sh - -.. _ref-boot-software-updates-imx: - -Boot Software Updates on iMX -============================ - -Boot Artifacts --------------- - -SPL -~~~ - -SPL is the first software loader generated by the i.MX U-Boot build. -It is signed via the NXP® CST tool, filling in various IVT header fields. -SPL binaries from CI **cannot** be added directly to OTA due to missing signature data, which must be added by you. - -In some cases, an SoC may require additional firmware to be loaded (such as DDR firmware for i.MX 8M). -This firmware is loaded prior to the load/verification of U-Boot FIT-image. - -U-Boot FIT Image -~~~~~~~~~~~~~~~~ - -"U-boot FIT-image" is a generic name for the signed FIT-image containing U-Boot proper (``u-boot.bin``) and a host of other firmware. -This file is verified by SPL via a public key stored in SPL’s dtb. -This artifact may be signed—on closed boards—as a part of CI, and can be included automatically in a boot software OTA package. - -- ``U-boot-nodtb.bin`` -- ``U-boot.dtb`` -- OP-TEE -- Arm Trusted Firmware (ARMv8) -- Possibly other firmwares - -If the CI signing key has been rotated since the last OTA, then the SPL.dtb verification data needs to be updated prior to booting the new U-Boot FIT-image. - -MMC Boot Image Layout ---------------------- - -|image of iMX6 layout| |image of iMX8M layout| - -The Secondary Image Table (SIT) is a 20 byte long structure containing 5 32-bit words. -These encode the bootloader B-copy area offset (``firstSectorNumber``), the magic value (``tag``) which is always ``0x00112233``, and three unused words set to ``0``. -Example SIT: - -:: - - $ hexdump -vC sit-mx8mm.bin - 00000000 00 00 00 00 - 00000004 00 00 00 00 - 00000008 33 22 11 00 <--- This is the "tag" - 0000000c 00 10 00 00 <--- This is the "firstSectorNumber" - 00000010 00 00 00 00 - -Boot Flow ---------- - -SPL -~~~ - -#. Initialize DDR -#. Load U-Boot FIT-image -#. Perform verification -#. Extract components -#. Jump to ATF / OP-TEE - -ATF (ARMv8) -~~~~~~~~~~~ - -#. Perform memory permission setup -#. Drop to EL-2 non-secure -#. Jump to OP-TEE - -OP-TEE -~~~~~~ - -#. Perform secure world setup -#. Driver init -#. Load TAs -#. Drop to EL-2 secure world -#. Jump to ``u-boot.bin`` - -U-Boot -~~~~~~ - -#. Driver init -#. Boot script -#. Load kernel FIT-image -#. Perform verification -#. Extract components -#. Jump to Linux kernel - -Update Procedure ----------------- - -Primary vs Secondary Boot Paths -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -There are some i.MX SoCs which can be configured to have two copies of the bootloader in SD/eMMC, and switch between them. -The switch can be triggered either by the BootROM—in case the bootloader image is faulty—or can be enforced by the user. - -The bootloader A-copy must be placed at a predetermined offset in SD/eMMC. -The bootloader B-copy area offset is determined by an offset stored in The Secondary Image Table (SIT). -The SIT must be placed at the predetermined offset in SD/eMMC. - -To enforce BootROM to boot the secondary boot image, ``PERSIST\_SECONDARY\_BOOT`` must be set in the ``SRC\_GPR10`` register, and a warm reset performed. -After reboot, BootROM will boot the image using the offset specified in the SIT table. -For additional details about the SIT format and SIT offsets, please refer to your the SoC Reference Manual, section *Redundant boot support for expansion device*. - -``libaktualizr`` and ``aktualizr-lite`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Aktualizr-lite decides if boot firmware needs to be updated based on ``${ostree\_root}/usr/lib/firmware/version.txt``, where ``ostree\_root`` is the root of newly deployed ostree sysroot. - Example of contents: ``bootfirmware\_version=10`` -2. After parsing ``bootfirmware\_version``, it compares the new version number with the existing one. - This is obtained via ``fiovb`` or ``ubootenv``. -3. If ``bootfirmware\_version`` from ``version.txt`` is higher than the existing one, aktualizr-lite sets ``bootupgrade\_available`` via ``fiovb`` or ``ubootenv``. -4. Reboot should be performed. - -U-Boot ``boot.cmd`` Script -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. figure:: boot-software-updates/upgrade-flow.png - :alt: Boot firmware upgrade flow - - Boot firmware upgrade flow - -1. Actual update is done via U-Boot ``boot.cmd`` script (``boot.scr``). -2. ``boot.cmd`` checks if the booting secondary path is booted. -3. In case ``upgrade\_available`` is set, check if boot firmware upgrade is needed is by checking the ``bootupgrade\_available`` flag. - If both are true, obtain boot firmware images from the newly deployed ostree sysroot and write them to secondary boot path offsets. - After the secondary boot bit is set, warm reset is performed to enforce BootROM to boot secondary boot path. -4. After executing rebooting secondary boot path, perform condition verification from step 2. - It should evaluate as false, so regular booting of Linux having taken place. -5. After Linux is booted, aktualizr-lite confirms a successful update by clearing the **upgrade\_available** flag. - At this point, new boot firmware images are validated and need to be flashed to the stable primary path. - Additional reboot is needed after this step. -6. Regular POR cold reset is performed. - -Add a New Board ---------------- - -.. _ref-sec-tfa-optee: - -TF-A/OP-TEE -~~~~~~~~~~~ - -TF-A on ARMv8, or OP-TEE on ARMv7, provides PSCI services to the Linux® OS and should support the ``SYSTEM\_RESET2``. -This implements a internal warm reset, resetting only the CPU. -This is needed for retaining the values of special registers after reboot. -This behavior differs from a regular ``SYSTEM\_RESET``, which causes ``POR``, removing power for the whole board (resets CPU, DDR and peripherals, on some boards it also resets external PMIC). - -U-Boot -~~~~~~ - -SPL: FIT Image Offset Calculation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -U-Boot SPL automatically detects which image to boot next based on the SECONDARY\_BOOT value. -Every board has the configuration ``CONFIG\_SYS\_MMCSD\_RAW\_MODE\_U\_BOOT\_SECTOR``. -This contains the offset of the U-Boot FIT image, beginning from the boot media sectors (512 bytes each). -Below is an example of how the final offset is calculated on iMX SoCs (extract from ``./arch/arm/mach-imx/spl.c``): - -:: - - #if defined(CONFIG_SECONDARY_BOOT_RUNTIME_DETECTION) && \ - defined(CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_USE_SECTOR) - unsigned long spl_mmc_get_uboot_raw_sector(struct mmc *mmc, - unsigned long raw_sect) - { - int boot_secondary = boot_mode_getprisec(); - unsigned long offset = CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_SECTOR; - - if (boot_secondary) { - offset += CONFIG_SECONDARY_BOOT_SECTOR_OFFSET; - printf("SPL: Booting secondary boot path: using 0x%lx offset " - "for next boot image\n", offset); - } else { - printf("SPL: Booting primary boot path: using 0x%lx offset " - "for next boot image\n", offset); - } - - return offset; - } - #endif - -Fastboot: Support of Secondary Boot Image Offsets -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The required offsets for the secondary boot images (**SPL**, **U-Boot.itb**, and **SIT**) for iMX6, iMX6ULL, iMX7, and iMX8M SoCs are defined by the FSL fastboot driver. -To change the SIT offset used for an SoC, -adjust the ``secondary\_image\_table\_mmc\_offset()`` and ``bootloader\_mmc\_offset()`` functions within the U-Boot fastboot driver source (``drivers/fastboot/fb\_fsl/fb\_fsl\_partitions.c``). - -Secondary Image Table Generation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -SIT image binary is generated automatically if U-Boot is being built with the correct value for the ``CONFIG\_SECONDARY\_BOOT\_SECTOR\_OFFSET`` config option. - -Watchdog -^^^^^^^^ - -The secondary boot path is mainly used for boot firmware update image validation. -In exceptional cases it will behave incorrectly, such as the system not responding. -To address such cases, watchdog support has to be enabled in SPL. -This is done by adding the following config options to ``lmp.cfg``: - -:: - - CONFIG_IMX_WATCHDOG=y - CONFIG_SPL_HW_WATCHDOG=y - # CONFIG_SPL_WDT is not set - CONFIG_SPL_WATCHDOG_SUPPORT=y - -``meta-lmp`` -~~~~~~~~~~~~ - -MfgTool Scripts -^^^^^^^^^^^^^^^ - -To deploy boot images to the destination board, the :term:`mfgtools` package is used. -It uses a special configuration file with ``uuu`` extensions, which contains all instructions needed for the deployment of boot images. -Default :term:`uuu` files do not support flashing images for secondary boot path. -Doing so requires the following adjustments: adding SIT image, secondary SPL, and U-Boot FIT deployment steps: - -:: - - +FB: flash bootloader_s ../imx-boot-@@MACHINE@@ - +FB: flash bootloader2_s ../u-boot-@@MACHINE@@.itb - +FB: flash sit ../sit-@@MACHINE@@.bin - -The final uuu script looks like: - -:: - - uuu_version 1.2.39 - SDP: boot -f imx-boot-mfgtool - SDPS: boot -f imx-boot-mfgtool - - SDPV: delay 1000 - SDPV: write -f u-boot-mfgtool.itb - SDPV: jump - - FB: ucmd setenv fastboot_dev mmc - FB: ucmd setenv mmcdev ${emmc_dev} - FB: ucmd mmc dev ${mmcdev} 1; mmc erase 0 0x2000 - FB: flash bootloader ../imx-boot-@@MACHINE@@ - FB: flash bootloader2 ../u-boot-@@MACHINE@@.itb - FB: flash bootloader_s ../imx-boot-@@MACHINE@@ - FB: flash bootloader2_s ../u-boot-@@MACHINE@@.itb - FB: flash sit ../sit-@@MACHINE@@.bin - FB: ucmd if env exists emmc_ack; then ; else setenv emmc_ack 0; fi; - FB: ucmd mmc partconf ${mmcdev} ${emmc_ack} 1 0 - FB: done - -``lmp.cfg`` Files -^^^^^^^^^^^^^^^^^ - -To enable support for flashing/booting secondary boot images, adjust both the default ``lmp.cfg``, and the one for mfgtools. -The following config options need to be added to the default ``lmp.cfg``: - -:: - - CONFIG_SECONDARY_BOOT_RUNTIME_DETECTION=y - CONFIG_SECONDARY_BOOT_SECTOR_OFFSET=0x1000 - CONFIG_CMD_SECONDARY_BOOT=y - -And to mfgtool ``lmp.cfg``: - -:: - - CONFIG_FSL_FASTBOOT_BOOTLOADER_SECONDARY=y - CONFIG_SECONDARY_BOOT_SECTOR_OFFSET=0x1000 - -Pre-Load ``boot.cmd`` by SPL -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -As ``boot.cmd`` depends on U-Boot commands for booting Linux, it should be aligned with the U-Boot version. -By default, in setups without boot firmware update support, ``boot.cmd`` is stored in the first FAT partition in eMMC/SD. -To get ``boot.cmd`` updates—together with other boot software images—it should be moved from the FAT partition, to the U-Boot FIT image. -To do this, edit ``lmp-machine-custom.inc``, adding this line for your board (imx8mqevk used as an example): - -:: - - BOOTSCR_LOAD_ADDR_imx8mqevk = "0x44800000" - -This change will include Linux ``boot.cmd`` into the U-Boot FIT image, alongside TF-A/OP-TEE/U-Boot proper/U-Boot dtb images. -When SPL parses the U-Boot FIT image (``u-boot.itb``) it will pre-load ``boot.itb`` (compiled and wrapped ``boot.cmd``) to the address specified in ``BOOTSCR\_LOAD\_ADDR`` variable. - -To let U-Boot know where to get the boot script from, you should also adjust ``CONFIG\_BOOTCOMMAND`` in the U-Boot ``lmp.cfg`` of your board. - -:: - - CONFIG_BOOTCOMMAND="setenv verify 1; source 0x44800000; reset" - -Test Basic API -~~~~~~~~~~~~~~ - -After applying all the updates from previous steps, we should validate that everything is in place. -This consists of two steps: - -- Cold/Warm resets from U-Boot are functional -- Obtain board security state (open/closed states) - -To test cold/warm resets and booting primary/secondary boot path, use these two U-Boot commands ``imx\_secondary\_boot`` and ``reset``\ ``reset -w`` (warm reset). - -.. tip:: - For regular reset, usually it does ``POR``. - -Example of test: - -:: - - U-Boot SPL 2020.04+fio+gee4483499f (Jan 01 1970 - 00:00:00 +0000) - Trying to boot from MMC1 - SPL: Booting primary boot path: using 0x300 offset for next boot image - ... - Hit any key to stop autoboot: 0 - u-boot => imx_secondary_boot 1 - u-boot => reset -w - Resetting... - - U-Boot SPL 2020.04+fio+gee4483499f (Jan 01 1970 - 00:00:00 +0000) - Trying to boot from MMC1 - SPL: Booting secondary boot path: using 0x1300 offset for next boot image - ... - Hit any key to stop autoboot: 0 - -From the output, you can see that after setting secondary boot and performing warm reset, -BootROM boots images from secondary boot path (``SPL: Booting secondary boot path: using 0x1300 offset for next boot image``). - -To check if the security status of your board is detected correctly, use the ``imx\_is\_closed`` command: - -:: - - u-boot=> imx_is_closed - Board is in open state - -``boot.cmd`` -~~~~~~~~~~~~ - -Currently, LmP uses template-based generation for the final ``boot.cmd``. -It is constructed from common boot files (``./meta-lmp-base/recipes-bsp/u-boot/u-boot-ostree-scr-fit``), -which contains all SoC agnostic ``DEFINE`` statements and common functionality, and board specific ``boot.cmd``, which includes the common scripts. - -Example of board ``boot.cmd`` -(``./meta-lmp-bsp/recipes-bsp/u-boot/u-boot-ostree-scr-fit/imx8mm-lpddr4-evk/boot.cmd``): - -.. code-block:: shell - - echo "Using freescale_${fdt_file}" - - # Default boot type and device - setenv bootlimit 3 - setenv devtype mmc - setenv devnum 2 - setenv bootpart 1 - setenv rootpart 2 - - # Boot image files - setenv fdt_file_final freescale_${fdt_file} - setenv fit_addr ${initrd_addr} - - # Boot firmware updates - - # Offsets are in blocks (512KB each) - setenv bootloader 0x42 - setenv bootloader2 0x300 - setenv bootloader_s 0x1042 - setenv bootloader2_s 0x1300 - - setenv bootloader_image "imx-boot" - setenv bootloader_s_image ${bootloader_image} - setenv bootloader2_image "u-boot.itb" - setenv bootloader2_s_image ${bootloader2_image} - setenv uboot_hwpart 1 - - @@INCLUDE_COMMON_IMX@@ - @@INCLUDE_COMMON@@ - -Above you can find that the only needed variables that should be defined are: boot/root partition indexes, mmc device index, and ``fdt\_file``. -For boot firmware update functionality, bootloader image offsets and names should also be provided. - -Sysroot and Signed Boot Artifacts -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -All boot artifacts (SPL/imx-boot and U-Boot FIT) are automatically deployed to sysroot during build time. -However, on closed boards where the initial boot image has to be signed in advance by a subscriber private key, -there is way to add a signed binary instead of automatic inclusion of unsigned boot artifacts. - -To do this, add ``lmp-boot-firmware.bbappend`` to your ``meta-subscriber-overrides`` layer, adding the path to the signed binary and the signed binary itself. -Next, define the boot firmware version by setting the ``LMP_BOOT_FIRMWARE_VERSION`` global variable in your ``lmp-factory-custom.inc``. -Boot firmware version information will be automatically added to ``${osroot}/usr/lib/firmware/version.txt`` and the U-Boot Device Tree Blob. - -.. note:: - - The signed binary is called ``SPL`` for i.MX 6/7, and ``imx-boot`` for i.MX 8* platforms. - No need to append ``.signed`` to the binary name. - -Example: - -.. code-block:: diff - - diff --git a/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware.bbappend b/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware.bbappend - new file mode 100644 - index 0000000..6c11380 - --- /dev/null - +++ b/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware.bbappend - @@ -0,0 +1,7 @@ - +FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" - + - +SRC_URI = " \ - + file://SPL \ - +" - diff --git a/conf/machine/include/lmp-factory-custom.inc b/conf/machine/include/lmp-factory-custom.inc - index 0fe26b8..2a9815d 100644 - --- a/conf/machine/include/lmp-factory-custom.inc - +++ b/conf/machine/include/lmp-factory-custom.inc - @@ -22,4 +22,4 @@ UEFI_SIGN_KEYDIR = "${TOPDIR}/conf/factory-keys/uefi" - # TF-A Trusted Boot - TF_A_SIGN_KEY_PATH = "${TOPDIR}/conf/factory-keys/tf-a/privkey_ec_prime256v1.pem" - - +LMP_BOOT_FIRMWARE_VERSION:imx8mm-lpddr4-evk = "3" - diff --git a/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware/SPL b/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware/SPL - new file mode 100644 - index 0000000..50f5013 - Binary files /dev/null and b/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware/SPL differ - -.. note:: - - As ``LMP_BOOT_FIRMWARE_VERSION`` is now the preferred way to set boot firmware version, defining ``PV`` in ``lmp-boot-firmware.bbappend`` is deprecated and should not be used. - To switch to the new approach, remove ``PV = ""`` from ``lmp-boot-firmware.bbappend``, and define ``LMP_BOOT_FIRMWARE_VERSION`` with the appropriate version value as shown above in the example. - -.. seealso:: - * :ref:`ref-secure-boot-imx-habv4` - -.. |image of iMX6 layout| image:: boot-software-updates/imx6-layout.png -.. |image of iMX8M layout| image:: boot-software-updates/imx8m-layout.png diff --git a/source/reference-manual/security/boot-software-updates-imx8qm.rst b/source/reference-manual/security/boot-software-updates-imx8qm.rst deleted file mode 100644 index 417f5bafd..000000000 --- a/source/reference-manual/security/boot-software-updates-imx8qm.rst +++ /dev/null @@ -1,373 +0,0 @@ -.. highlight:: sh - -.. _ref-boot-software-updates-imx8qm: - -Boot Software Updates on iMX8QM -=============================== - -Boot Artifacts --------------- - -``imx-boot`` Image -~~~~~~~~~~~~~~~~~~ - -The ``imx-boot`` image is the first boot image container set by CSU ROM. -It consists of two containers: - -- SECO container for SECO FW -- SCU container for SCU FW, and optional AP IPL (Cortex A processing domain), - CM4 FW and DDR init images - -By default, U-Boot SPL is used as the main AP IPL image. -The SECO container is always signed, and is provided by NXP®. -The SCU container can be signed by you or the OEM vendor. - -Here is an example of typical boot image container set layout: - -:: - - --------------------------- - | 1st Container Header | - --------------------------- - | 1st Signature Block | - --------------------------- - | Padding for 1KB alignment | - --------------------------- - | 2nd Container Header | - --------------------------- - | 2nd Signature Block | - --------------------------- - | SECO FW | - --------------------------- - | SCU FW with DDR init | - --------------------------- - | CM4 Image | - --------------------------- - | Cortex-A FW (AP IPL) | - --------------------------- - -U-Boot FIT Image -~~~~~~~~~~~~~~~~ - -"U-boot FIT-image" is a generic name for the signed FIT-image containing U-Boot proper (``u-boot.bin``) and a host of other firmware. -This file is verified by SPL via a public key stored in SPL’s dtb. -This artifact may be signed—on closed boards—as a part of CI, and can be included automatically in a boot software OTA package. - -- ``U-boot-nodtb.bin`` -- ``U-boot.dtb`` -- OP-TEE -- Arm Trusted Firmware (ARMv8) - -If the CI signing key has been rotated since the last OTA, then the SPL.dtb verification data needs to be updated prior to booting the new U-Boot FIT-image. - -MMC Boot Image Layout ---------------------- - -According to the *5.8.2.2.1 High Level eMMC Boot Flow Note* (iMX8QM Reference manual), for the eMMC boot scenarios where the images are located in the boot partition, the boot image set selection is done based on ``BOOT_PARTITION_ENABLE`` eMMC ``ECSD`` register values. -This means that the secondary boot image set should be flashed to the ``boot1`` hw partition from the same offset (``0x0``) as the primary one. - -Update Procedure ----------------- - -Primary vs Secondary Boot Paths -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -iMX8QM SoC supports two different container sets of boot images: - -- Primary Boot Container set (Set0) -- Secondary Boot Container set (Set1) (optional) - -SCU ROM reads the headers for both, then selects the container set with the newer SW version for Primary boot path. -The container set with the older SW vesion becomes the Secondary boot path. - -In the case where the versions are equal, SCU ROM picks Set0. - -Unfortunately, the SoC does not provide mechanisms for the user to control in runtime what container set to boot, such as setting the ``PERSIST\_SECONDARY\_BOOT`` bit ``SRC\_GPR10``. -In response to this, in our setup we do not rely on different SW versions of Image Container Sets. -Instead we use Set0 as the Primary boot path, and Set1 as a recovery path (Secondary boot path). - -Libaktualizr and Aktualizr-Lite -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Aktualizr-lite decides if boot firmware needs to be updated based on ``${ostree\_root}/usr/lib/firmware/version.txt``, where ``ostree\_root`` is the root of newly deployed ostree sysroot. - Example of contents: ``bootfirmware\_version=10`` -2. After parsing ``bootfirmware\_version``, it compares the new version number with the existing one. - This is obtained via ``fiovb`` or ``ubootenv``. -3. If ``bootfirmware\_version`` from ``version.txt`` is higher than the existing one, aktualizr-lite sets ``bootupgrade\_available`` via ``fiovb`` or ``ubootenv``. -4. Reboot should be performed. - -U-Boot ``boot.cmd`` Script -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. figure:: boot-software-updates/upgrade-flow-imx8qm.png - :alt: Boot firmware upgrade flow for iMX8QM - - Boot firmware upgrade flow for iMX8QM - -1. Actual update is done via U-Boot ``boot.cmd`` (``boot.scr``) script. -2. ``boot.cmd`` checks if primary path is booted. -3. In case ``upgrade\_available`` is set, check if boot firmware upgrade is needed by checking the ``bootupgrade\_available`` flag. - If both are true, obtain boot firmware images from the newly deployed ostree sysroot and write them to the primary boot path offsets. - Next ``bootupgrade\_primary\_updated`` is set, and regular reset is issued. -4. After reboot, SCU ROM tries to boot the newly updated images from the primary boot path (Set0). - If image verification fails, automatically fall back to Set1. - If Set1 is booted—meaning verification of Set0 failed—the rollback procedure will be issued, and the previous version of Set0 will be restored. - Conversely, if Set0 is booted but ``bootcount`` hits ``bootlimit`` (meaning the boot procedure did not finish successfully), the rollback procedure will be also issued. -5. After Linux boots, aktualizr-lite confirms a successful update by clearing ``upgrade\_available``. - At this point new boot firmware images are already validated. - An additional reboot is needed after this step. -6. After reboot, U-Boot checks if ``bootupgrade\_primary\_updated`` is set and ``upgrade\_available`` is cleared. - This means aktualizr-lite has confirmed a successful boot, and U-Boot clears ``bootupgrade\_primary\_updated``. - Otherwise ``bootcount`` is incremented. - -Add a New Board ---------------- - -``meta-lmp`` -~~~~~~~~~~~~ - -``mfgtool`` Scripts -^^^^^^^^^^^^^^^^^^^ - -To deploy boot images to the destination board, the mfgtools package is used. -It uses a special configuration file with uuu extensions -This contains all the instructions need for the correct deployment of boot images. -Default uuu files do not support flashing images for secondary boot path. -The appropriate adjustments should be made: adding secondary imx-boot, and U-Boot FIT deployment steps: - -:: - - +FB: flash bootloader2 ../u-boot-@@MACHINE@@.itb - +FB: flash bootloader2_s ../u-boot-@@MACHINE@@.itb - -The final uuu script looks like: - -:: - - uuu_version 1.3.102 - - SDPS: boot -f imx-boot-mfgtool - CFG: FB: -vid 0x0525 -pid 0x4000 - CFG: FB: -vid 0x0525 -pid 0x4025 - CFG: FB: -vid 0x0525 -pid 0x402F - CFG: FB: -vid 0x0525 -pid 0x4030 - CFG: FB: -vid 0x0525 -pid 0x4031 - - SDPU: delay 1000 - SDPU: write -f imx-boot-mfgtool -offset 0x57c00 - SDPU: jump - - # These commands will be run when use SPL and will be skipped if no spl - # if (SPL support SDPV) - # { - SDPV: delay 1000 - SDPV: write -f u-boot-mfgtool.itb - SDPV: jump - # } - - FB: ucmd setenv fastboot_dev mmc - FB: ucmd setenv mmcdev 0 - FB: ucmd mmc dev ${mmcdev} 1; mmc erase 0 0x3FFE - FB: flash -raw2sparse all ../@@MFGTOOL_FLASH_IMAGE@@-@@MACHINE@@.wic - FB: flash bootloader ../imx-boot-@@MACHINE@@ - FB: flash bootloader_s ../imx-boot-@@MACHINE@@ - FB: flash bootloader2 ../u-boot-@@MACHINE@@.itb - FB: flash bootloader2_s ../u-boot-@@MACHINE@@.itb - FB: ucmd mmc partconf 0 0 1 0 - FB: done - - -``lmp.cfg`` Files -^^^^^^^^^^^^^^^^^ - -To enable support for flashing/booting secondary boot images, adjust both the default ``lmp.cfg``, and the one for mfgtools. -The following config options need to be added to the default ``lmp.cfg``: - -:: - - CONFIG_CMD_SECONDARY_BOOT=y - CONFIG_SECONDARY_BOOT_SECTOR_OFFSET=0x0 - CONFIG_SECONDARY_BOOT_RUNTIME_DETECTION=y - -And to mfgtool ``lmp.cfg``: - -:: - - CONFIG_FSL_FASTBOOT_BOOTLOADER_SECONDARY=y - CONFIG_SECONDARY_BOOT_SECTOR_OFFSET=0x0 - -The secondary boot path is primarily used for boot firmware update image validation. -In exceptional cases, it can behave incorrectly, causing hangs and other issues. -To cover such cases, watchdog support has to be enabled in SPL by adding config options to ``lmp.cfg``: - -:: - - CONFIG_IMX_WATCHDOG=y - CONFIG_SPL_HW_WATCHDOG=y - # CONFIG_SPL_WDT is not set - CONFIG_SPL_WATCHDOG_SUPPORT=y - - -Pre-Load ``boot.cmd`` by SPL -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -As ``boot.cmd`` depends on U-Boot commands for booting Linux®, it should be aligned with the U-Boot version. -By default, in setups without boot firmware update support, ``boot.cmd`` is stored in the first FAT partition in eMMC/SD. -To get ``boot.cmd`` updates—together with other boot software images—it should be moved from the FAT partition, to the U-Boot FIT image. -To do this, edit ``lmp-machine-custom.inc``, adding this line for your board (imx8mqevk used as an example): - -:: - - BOOTSCR_LOAD_ADDR_imx8qmmek = "0x44800000" - -This change will include Linux ``boot.cmd`` into the U-Boot FIT image, alongside TF-A/OP-TEE/U-Boot proper/U-Boot dtb images. -When SPL parses the U-Boot FIT image (``u-boot.itb``) it will pre-load ``boot.itb`` (compiled and wrapped ``boot.cmd``) to the address specified in ``BOOTSCR\_LOAD\_ADDR`` variable. - -To let U-Boot know where to get the boot script from, you should also adjust ``CONFIG\_BOOTCOMMAND`` in the U-Boot ``lmp.cfg`` of your board. - -:: - - CONFIG_BOOTCOMMAND="setenv verify 1; source 0x44800000; reset" - - -Test Basic API -~~~~~~~~~~~~~~ - -After applying all the updates from previous steps, we should validate that everything is in place. -This consists of two basic steps: - -- Boot container set detection (primary or secondary) -- Obtain board security state (open/closed states) - -To test Boot container set detection, use the U-Boot command ``imx\_secondary\_boot``. - -Example of test: - -:: - - u-boot=> imx_secondary_boot - Secondary boot bit = 0 - -To check if the security status of your board is detected correctly, use the ``imx\_is\_closed`` command: - -:: - - u-boot=> imx_is_closed - Board is in open state - -``boot.cmd`` -~~~~~~~~~~~~ - -Currently, LmP uses template-based generation for the final ``boot.cmd``. -It is constructed from common boot files (``./meta-lmp-base/recipes-bsp/u-boot/u-boot-ostree-scr-fit``), -which contains all SoC agnostic ``DEFINE`` statements and common functionality, and board specific ``boot.cmd``, which includes the common scripts. - -Example of board ``boot.cmd`` -(``./meta-lmp-bsp/recipes-bsp/u-boot/u-boot-ostree-scr-fit/imx8qm-mek/boot.cmd``): - -:: - - setenv fdt_file imx8qm-mek.dtb - echo "Using freescale_${fdt_file}" - - # Default boot type and device - setenv bootlimit 3 - setenv devtype mmc - setenv devnum 0 - setenv bootpart 1 - setenv rootpart 2 - setenv hdmi_image hdmitxfw.bin - setenv m4_0_image core0_m4_image.bin - setenv m4_1_image core1_m4_image.bin - setenv ramdisk_addr_r 0x8a000000 - # enable relocation of ramdisk - setenv initrd_high - - # Boot image files - setenv fit_addr ${ramdisk_addr_r} - setenv fdt_file_final freescale_${fdt_file} - - setenv bootcmd_boot_hdmi 'hdp load ${loadaddr}' - setenv bootcmd_boot_m4_0 'dcache flush; bootaux ${loadaddr} 0' - setenv bootcmd_boot_m4_1 'dcache flush; bootaux ${loadaddr} 1' - setenv bootcmd_load_hdmi 'if imxtract ${ramdisk_addr_r}#conf-freescale_${fdt_file} loadable-${hdmi_image} ${loadaddr}; then run bootcmd_boot_hdmi; fi' - setenv bootcmd_load_m4_0 'if imxtract ${ramdisk_addr_r}#conf-freescale_${fdt_file} loadable-${m4_0_image} ${loadaddr}; then run bootcmd_boot_m4_0; fi;' - setenv bootcmd_load_m4_1 'if imxtract ${ramdisk_addr_r}#conf-freescale_${fdt_file} loadable-${m4_1_image} ${loadaddr}; then run bootcmd_boot_m4_1; fi;' - setenv bootcmd_load_fw 'run bootcmd_load_hdmi; run bootcmd_load_m4_0; run bootcmd_load_m4_1;' - - # Boot firmware updates - - # Offsets are in blocks (512 bytes each) - setenv bootloader 0x0 - setenv bootloader2 0x400 - setenv bootloader_s ${bootloader} - setenv bootloader2_s ${bootloader2} - setenv bootloader_image "imx-boot" - setenv bootloader_s_image ${bootloader_image} - setenv bootloader2_image "u-boot.itb" - setenv bootloader2_s_image ${bootloader2_image} - - setenv update_image_boot0 'echo "${fio_msg} writing ${image_path} ..."; run set_blkcnt && mmc dev ${devnum} 1 && mmc write ${loadaddr} ${start_blk} ${blkcnt}' - - setenv backup_primary_image 'echo "${fio_msg} backing up primary boot image set ..."; mmc dev ${devnum} 1 && mmc read ${loadaddr} 0x0 0x3FFE && mmc dev ${devnum} 2 && mmc write ${loadaddr} 0x0 0x3FFE' - setenv restore_primary_image 'echo "${fio_msg} restore primary boot image set ..."; mmc dev ${devnum} 2 && mmc read ${loadaddr} 0x0 0x3FFE && mmc dev ${devnum} 1 && mmc write ${loadaddr} 0x0 0x3FFE' - - setenv update_primary_image1 'if test "${ostree_deploy_usr}" = "1"; then setenv image_path "${bootdir}/${bootloader_s_image}"; else setenv image_path "${ostree_root}/usr/lib/firmware/${bootloader_s_image}"; fi; setenv start_blk "${bootloader_s}"; run load_image; run update_image_boot0' - setenv update_primary_image2 'if test "${ostree_deploy_usr}" = "1"; then setenv image_path "${bootdir}/${bootloader2_s_image}"; else setenv image_path "${ostree_root}/usr/lib/firmware/${bootloader2_s_image}"; fi; setenv start_blk "${bootloader2_s}"; run load_image; run update_image_boot0' - - setenv update_primary_image 'run update_primary_image1; run update_primary_image2' - - setenv do_reboot "reboot" - - @@INCLUDE_COMMON_IMX@@ - @@INCLUDE_COMMON_ALTERNATIVE@@ - - -Sysroot and Signed Boot Artifacts -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -All boot artifacts (SPL/imx-boot and U-Boot FIT) are automatically deployed to sysroot during build time. -However, on closed boards where the initial boot image has to be signed in advance by a subscriber private key, -there is way to add a signed binary instead of automatic inclusion of unsigned boot artifacts. - -To do this, add ``lmp-boot-firmware.bbappend`` to your ``meta-subscriber-overrides`` layer, adding the path to the signed binary and the signed binary itself. -Next, define the boot firmware version by setting the ``LMP_BOOT_FIRMWARE_VERSION`` global variable in your ``lmp-factory-custom.inc``. -Boot firmware version information will be automatically added to ``${osroot}/usr/lib/firmware/version.txt`` and the U-Boot Device Tree Blob. - -Example: - -.. code-block:: diff - - diff --git a/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware.bbappend b/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware.bbappend - new file mode 100644 - index 0000000..6c11380 - --- /dev/null - +++ b/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware.bbappend - @@ -0,0 +1,7 @@ - +FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" - + - +SRC_URI = " \ - + file://imx-boot \ - +" - diff --git a/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware/imx-boot b/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware/imx-boot - new file mode 100644 - index 0000000..50f5013 - Binary files /dev/null and b/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware/imx-boot differ - --- a/conf/machine/include/lmp-factory-custom.inc - +++ b/conf/machine/include/lmp-factory-custom.inc - @@ -22,4 +22,4 @@ UEFI_SIGN_KEYDIR = "${TOPDIR}/conf/factory-keys/uefi" - # TF-A Trusted Boot - TF_A_SIGN_KEY_PATH = "${TOPDIR}/conf/factory-keys/tf-a/privkey_ec_prime256v1.pem" - - +LMP_BOOT_FIRMWARE_VERSION:imx8qm-mek = "3" - -.. note:: - As ``LMP_BOOT_FIRMWARE_VERSION`` is now the preferred way to set boot firmware version, - defining ``PV`` in ``lmp-boot-firmware.bbappend`` is deprecated and should not be used. - To switch to the new approach, remove ``PV = ""`` from ``lmp-boot-firmware.bbappend``, - and define ``LMP_BOOT_FIRMWARE_VERSION`` with the appropriate version value as shown above in the example. - - -.. seealso:: - * :ref:`ref-secure-boot-imx-ahab` diff --git a/source/reference-manual/security/boot-software-updates/upgrade-flow-imx8qm.png b/source/reference-manual/security/boot-software-updates/upgrade-flow-imx8qm.png deleted file mode 100644 index 46c04688d..000000000 Binary files a/source/reference-manual/security/boot-software-updates/upgrade-flow-imx8qm.png and /dev/null differ diff --git a/source/reference-manual/security/factory-keys.rst b/source/reference-manual/security/factory-keys.rst index 79b492d92..3a252ba48 100644 --- a/source/reference-manual/security/factory-keys.rst +++ b/source/reference-manual/security/factory-keys.rst @@ -29,37 +29,6 @@ to configure the keys used by the Yocto Project. The device RoT key (the key used for secure boot, for example) is shown in the diagrams. However it is not an online key and is not used during the Factory build. -i.MX Secure Boot Flow -""""""""""""""""""""" - -The following diagram shows the Secure Boot flow for i.MX machines (TF-A is present only for arm64 devices): - -.. graphviz:: - - digraph { - graph [ - label = "Secure Boot flow for i.MX machines" - ]; - node [ - shape=box - ]; - edge [ - arrowhead=none - ]; - "Boot ROM" -> "SPL" [label = "RoT key"]; - "SPL" -> "uboot.itb" [label = "UBOOT_SPL_SIGN_KEYNAME"]; - "uboot.itb" -> "bootscr" [label = "UBOOT_SPL_SIGN_KEYNAME"]; - "uboot.itb" -> "TF-A (BL31, EL3 Runtime Firmware)" [label = "UBOOT_SPL_SIGN_KEYNAME"]; - "uboot.itb" -> "OP-TEE" [label = "UBOOT_SPL_SIGN_KEYNAME"]; - "OP-TEE" -> "OP-TEE TAs" [label = "OPTEE_TA_SIGN_KEY"]; - "uboot.itb" -> "U-Boot proper" [label = "UBOOT_SPL_SIGN_KEYNAME"]; - "U-Boot proper" -> "kernel fitImage" [label = "UBOOT_SIGN_KEYNAME"]; - "kernel fitImage" -> "DTB files" [label = "UBOOT_SIGN_KEYNAME"]; - "kernel fitImage" -> "initrd" [label = "UBOOT_SIGN_KEYNAME"]; - "kernel fitImage" -> "Linux kernel" [label = "UBOOT_SIGN_KEYNAME"]; - "Linux kernel" -> "Linux kernel modules" [label = "MODSIGN_PRIVKEY"]; - } - UEFI Secure Boot Flow """"""""""""""""""""" diff --git a/source/reference-manual/security/imx-generic-custom-keys.rst b/source/reference-manual/security/imx-generic-custom-keys.rst deleted file mode 100644 index b56ad6edc..000000000 --- a/source/reference-manual/security/imx-generic-custom-keys.rst +++ /dev/null @@ -1,103 +0,0 @@ - -Using Custom Keys ------------------ - -Creating the Keys -^^^^^^^^^^^^^^^^^ - -There are different ways to create and store the keys needed for Secure Boot. -One reference for learning how to generate the PKI tree is the `i.MX Secure Boot on HABv4 Supported Devices`_ application note from NXP. - -In addition, the U-Boot project also includes documentation on `Generating a fast authentication PKI tree`_. - -.. warning:: - It is critical that the keys created in this process be stored in a secure and safe place. - Once the keys are fused to the board and it is closed, only signed images will boot. - The keys are required in future steps. - -Generate the MfgTools Scripts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -There are scripts to help with creating the commands to fuse the key into the fuse banks of ````, and to close the board. -This will configure the board to only boot signed images. - -1. Clone ``lmp-tools`` from GitHub - - .. code-block:: console - - $ git clone git://github.com/foundriesio/lmp-tools.git - -2. Export the path to where keys are stored - - .. code-block:: console - - $ export KEY_FILE=/path-to-key-files/ - -3. Generate the scripts to fuse and close the board - - .. code-block:: console - - $ ./lmp-tools/security//gen_fuse.sh -s $KEY_FILE -d ./fuse.uuu - $ ./lmp-tools/security//gen_close.sh -s $KEY_FILE -d ./close.uuu - -Where ```` can be found in the table below: - -.. list-table:: SoCs covered by each ```` folder - :header-rows: 1 - :align: center - - * - SoC - - folder - * - imx6qdl and variants - - imx6 - * - imx6ul, imx6ull - - imx6ul - * - imx8mq, imx8mm - - imx8m - * - imx8mn, imx8mp - - imx8mn_imx8mp - -.. note:: - For Toradex devices ``apalis-imx6-sec`` and ``apalis-imx8-sec``, provide the additional ``-t`` parameter so the Toradex PIDs are included in the output scripts. - -4. Install the scripts to the ``meta-subscriber-overrides``: - -.. code-block:: console - - $ mkdir -p /meta-subscriber-overrides/recipes-support/mfgtool-files/mfgtool-files/ - $ cp fuse.uuu /meta-subscriber-overrides/recipes-support/mfgtool-files/mfgtool-files/ - $ cp close.uuu /meta-subscriber-overrides/recipes-support/mfgtool-files/mfgtool-files/ - $ cat /meta-subscriber-overrides/recipes-support/mfgtool-files/mfgtool-files_%.bbappend - -The content of ``mfgtool-files_%.bbappend`` should be:: - - FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" - -5. Inspect the changes, and push accordingly… - -.. code-block:: console - - $ git status - -The result of ``git status`` should look like: - -.. code-block:: console - - On branch devel - Your branch is up to date with 'origin/devel'. - - Changes to be committed: - (use "git restore --staged ..." to unstage) - new file: recipes-support/mfgtool-files/mfgtool-files//close.uuu - new file: recipes-support/mfgtool-files/mfgtool-files//fuse.uuu - new file: recipes-support/mfgtool-files/mfgtool-files_%.bbappend - -The changes add the :term:`UUU` scripts to the ``mfgtool-files`` artifacts of next targets. -Run the ``fuse.uuu`` and ``close.uuu`` to fuse the custom keys and close the board, respectively. - -.. warning:: - The scripts ``fuse.uuu`` and ``close.uuu`` include commands which result is irreversible. - The scripts should be executed with caution and only after understanding its critical implications. - -.. _i.MX Secure Boot on HABv4 Supported Devices: https://www.nxp.com/webapp/Download?colCode=AN4581&location=null -.. _Generating a fast authentication PKI tree: https://github.com/nxp-imx/uboot-imx/blob/lf_v2022.04/doc/imx/habv4/introduction_habv4.txt diff --git a/source/reference-manual/security/revoke-imx-keys.rst b/source/reference-manual/security/revoke-imx-keys.rst deleted file mode 100644 index 3ac1d38ea..000000000 --- a/source/reference-manual/security/revoke-imx-keys.rst +++ /dev/null @@ -1,155 +0,0 @@ -.. highlight:: sh - -.. _ref-revoke-imx-keys: - -Revoke Secure Boot Keys on i.MX -=============================== - -This page covers how to revoke a SRK key on i.MX SoC boards. -This includes the purpose of revocations, and where to find more information on this topic. - -Revocation of a Key: Overview ------------------------------ - -Revoking a SRK key should be done when one or more SRK keys become compromised. -The SRK keys are keys permanently copied to the hardware and are used during boot to unsure the Root of Trust. - -When a SRK key is revoked, the key is considered unreliable. -Thus, any image signed with that key will not be executed during boot. -This is a permanent change to the hardware. - -The example used on this page is a root of trust with 4 SRK keys fused to an i.MX machine. -For different architectures, some commands may differ. -Details on how to setup Secure Boot on i.MX machines can be found under :ref:`ref-secure-boot`. - -The following table lists the values for each SRK key. -The value for ``SRK_REVOKE`` mask is used for the revocation command line, and is detailed in the following sections. -The value for ``srk-index`` is a parameter for ``sign-file.sh``, used to sign the boot artifacts. - -.. _srk-revoke-imx: - -.. csv-table:: **SRK Revoke i.MX** - :file: ../../_static/csv/revoke_imx.csv - :widths: 30, 30, 30, 30, 30 - :header-rows: 1 - -``srk-index`` is a ``sign-file.sh`` parameter that defines a SRK key to be used to sign the SPL. - -Columns 1, 2 and 3 are from Table 4 from the `Secure Boot Using HABv4 Guide`_. - -.. note:: - - In a HABv4 environment, only the first 3 SRK keys can be revoked. - In a AHAB environment, all 4 SRK can be revoked. - For more details, check the `Code-Signing Tool User's Guide`_. - When there is no available SRK key, the board cannot boot! - -How to Sign the Boot Image for Revoking a Key ---------------------------------------------- - -The first step is to make sure there are other SRK keys available for the boot. -A key can only be revoked after a secure boot with a different key is executed, with the permission to unlock ``SRK_REVOKE`` write access. -After that a fuse is burned. In short: - -* boot with an available SRK key, different from the one to revoke -* unlock ``SRK_REVOKE`` -* fuse a register according to the SRK key being revoked. - -The signing process is based on the commands from :ref:`ref-secure-boot`, adding two parameters: - - ``--srk-index = `` to choose the SRK key to be used on that boot sequence. - For the right value, consult :ref:`srk-revoke-imx`. - - ``--enable-revoke`` to unlock the key revocation register write access. - -Write access to register ``SRK_REVOKE`` is protected by the bit ``SRK_REVOKE_LOCK``. -This can be configured by CST. -The parameter ``--enable-revoke`` brings the configuration needed by CST to unlock write access to ``SRK_REVOKE``, making revocation possible. - -.. warning:: - After revoking a SRK key, it cannot be used to boot the board again. - A board with no remaining reliable SRK keys does not boot. - -For example, for a ``imx6ullevk-sec`` SPL image to be signed with SRK1, use the following command: - -.. code-block:: console - - #Sign the MFGTool SPL file - ./sign-file.sh --engine SW --key-dir $KEY_PATH \ - --cst $CST_PATH \ - --spl $SPL_PATH/mfgtool-files-imx6ullevk-sec/SPL-mfgtool \ - --fix-sdp-dcd \ - --srk-index 2 \ - --enable-revoke - - #Sign the SPL file - ./sign-file.sh --engine SW --key-dir $KEY_PATH \ - --cst $CST_PATH \ - --spl $SPL_PATH/SPL-imx6ullevk-sec \ - --srk-index 2 - -.. warning:: - - In the example, only the SPL from MFGtool has write access to revoke the key. - The suggestion is to use ``bootloader.uuu`` to load the MFGTool SPL, and then U-Boot prompt to perform the fuse programming command. - For other boot scripts,you may be required to include ``--enable-revoke`` to the SPL file signing process (second command). - -How to Revoke a Key -------------------- - -The suggestion is to use ``bootloader.uuu`` to access U-Boot prompt for executing the following command:: - - fuse prog - -The values for ```` and ```` for the register ``SRK_REVOKE`` can be found on the SoC Reference Manual. -The value for ```` is from :ref:`srk-revoke-imx`. - -For example, to revoke SRK2 for ``imx6ullevk-sec``:: - - fuse prog 5 7 0x4 - Programming bank 5 word 0x00000007 to 0x00000004... - Warning: Programming fuses is an irreversible operation! - This may brick your system. - Use this command only if you are sure of what you are doing! - - Really perform this fuse programming? - y - -The following error happens when the key revocation write access is not available (``SRK_REVOKE`` is not unlocked). -This can be fixed by adding ``--enable-revoke`` during the signing of the boot image:: - - mxc_ocotp fuse_prog(): Access protect error - ERROR - -After the revocation of SRK2, it can never be used to boot that board again. -Test it by signing again using this SRK key and the boot must fail. - -How to Revoke a Key for Devices in a Fleet ------------------------------------------- - -The method suggested here describes the commands needed to revoke a key from the SoC perspective. -It requires serial download and console and bootloader access, which are not always accessible on devices in the field. -However, this is the base procedure to be used on a fleet. - -The process can be automated in a Factory by creating a signed SPL using another SRK key and enabling the ``SRK_REVOKE`` write access. -While on this, the ``bootcmd`` can be customized to perform the fusing command needed to revoke the compromised key. - -The fusing can be performed in Linux® Kernel mode instead, when the system is configured to allow this kind of execution. - -Then the firmware update is performed in a Wave—described in detail under :ref:`ref-production-targets`. - -After the revocation wave, another firmware update wave is required. -This time, with the bootloader configured to disable write access to the ``SRK_REVOKE``, and still using the reliable SRK key. - -This is a two-steps process which is highly dependent on the device configuration and access, and requires caution. -The revoke fusing command can make the device unavailable if not executed properly. - -To get help with the revocation automatization, open a `support ticket `_. - -.. i.MX Secure Boot on HABv4 Supported Devices (Rev. 4 — June 2020) -.. _Secure Boot Using HABv4 Guide: - https://www.nxp.com/webapp/Download?colCode=AN4581&location=null - -.. Code-Signing Tool User's Guide, Rev. 3.3.1 -.. _Code-Signing Tool User's Guide: - https://cache.nxp.com/secured/bsps/cst-3.3.1.tgz?fileExt=.tgz diff --git a/source/reference-manual/security/secure-boot-imx-ahab.rst b/source/reference-manual/security/secure-boot-imx-ahab.rst deleted file mode 100644 index 5b8a172b1..000000000 --- a/source/reference-manual/security/secure-boot-imx-ahab.rst +++ /dev/null @@ -1,271 +0,0 @@ -.. highlight:: sh - -.. _ref-secure-boot-imx-ahab: - -Secure Boot on i.MX 8/8X Families Using AHAB Including 8QM -========================================================== - -The i.MX 8 and i.MX 8X families of application processors introduce a Secure Boot concept which differs from HABv4 used on the i.MX 6/7/8M families. -Due to the multi-core architecture, the Security Controller (SECO) and System Control Unit (SCU) are heavily involved in the secure boot process. -This is in contrast to HABv4, where BootROM (running on A-core) is fully responsible. - -AHAB Architecture Overview --------------------------- - -The Advanced High Assurance Boot (AHAB) feature, as well as HABv4, relies on digital signatures to prevent unauthorized software execution during the device boot sequence. - -In the i.MX 8 and i.MX 8X families, the System Control Unit (SCU) is responsible for interfacing with the boot media. -It manages the process of loading firmware and software images in different partitions of the SoC. -The Security Controller (SECO) is responsible for authenticating images and authorizing their execution. - -How to Secure the Platform --------------------------- - -.. note:: - This page illustrates how the AHAB Secure Boot process works. - It provides background information for our :ref:`ref-secure-machines` implementation, for better understanding. - - We recommend fusing and closing a board following our :ref:`ref-secure-machines` guide. - In the guide, some steps described here are omitted, and handled in our code for simpler and safer operations. - -The first step is to generate the PKI tree and commit the fuse table to the hardware. - -.. warning:: - Once the fuses have been programmed they can not be modified. - -Please refer to NXP's `AN12312 Secure Boot on i.MX 8 and i.MX 8X Families using AHAB—Application Note`_ for a detailed description on generating the PKI tree. - -For development purposes, we keep i.MX AHAB sample keys and certificates at `lmp-tools/security/imx_ahab`_. -The fuse table can be inspected by executing the ``print_fuses`` script in that same directory. -The output should be:: - - 0x7E90F8D6 - 0xE1020512 - 0x4FF77EB2 - 0x1D964702 - 0x5ED61C06 - 0x14139AB9 - 0x0A57872C - 0xF367F432 - 0xE8153815 - 0xA804967A - 0xDC14638B - 0xB3A914F7 - 0x211FD529 - 0x8273EBD2 - 0x6E0B791C - 0x6A558134 - -The Security Reference Manual for your specific SoC indicates which fuses need to be programmed with the SRK fuse information. - -i.MX 8QM Fusing ---------------- - -.. warning:: - The values shown in this section are just examples of our standard LmP AHAB keys, and are not meant for production. - Fuses cannot be changed after the first write. - -On the i.MX 8QM SoC fuses are stored in fuse bank 0, words 722 to 737:: - - => fuse prog -y 0 722 0x7E90F8D6 - => fuse prog -y 0 723 0xE1020512 - => fuse prog -y 0 724 0x4FF77EB2 - => fuse prog -y 0 725 0x1D964702 - => fuse prog -y 0 726 0x5ED61C06 - => fuse prog -y 0 727 0x14139AB9 - => fuse prog -y 0 728 0x0A57872C - => fuse prog -y 0 729 0xF367F432 - => fuse prog -y 0 730 0xE8153815 - => fuse prog -y 0 731 0xA804967A - => fuse prog -y 0 732 0xDC14638B - => fuse prog -y 0 733 0xB3A914F7 - => fuse prog -y 0 734 0x211FD529 - => fuse prog -y 0 735 0x8273EBD2 - => fuse prog -y 0 736 0x6E0B791C - => fuse prog -y 0 737 0x6A558134 - -Alternatively, you can program SoC fuses via SDP by using the NXP® Universal Update Utility. -This is shown in the following script:: - - uuu_version 1.3.102 - - SDPS: boot -f imx-boot-mfgtool.signed - CFG: FB: -vid 0x0525 -pid 0x4000 - CFG: FB: -vid 0x0525 -pid 0x4025 - CFG: FB: -vid 0x0525 -pid 0x402F - CFG: FB: -vid 0x0525 -pid 0x4030 - CFG: FB: -vid 0x0525 -pid 0x4031 - - SDPU: delay 1000 - SDPU: write -f u-boot-mfgtool.itb - SDPU: jump - - # These commands will be run when use SPL and will be skipped if no spl - # if (SPL support SDPV) - # { - SDPV: delay 1000 - SDPV: write -f u-boot-mfgtool.itb - SDPV: jump - # } - - FB: ucmd fuse prog -y 0 722 0x7E90F8D6 - FB: ucmd fuse prog -y 0 723 0xE1020512 - FB: ucmd fuse prog -y 0 724 0x4FF77EB2 - FB: ucmd fuse prog -y 0 725 0x1D964702 - FB: ucmd fuse prog -y 0 726 0x5ED61C06 - FB: ucmd fuse prog -y 0 727 0x14139AB9 - FB: ucmd fuse prog -y 0 728 0x0A57872C - FB: ucmd fuse prog -y 0 729 0xF367F432 - FB: ucmd fuse prog -y 0 730 0xE8153815 - FB: ucmd fuse prog -y 0 731 0xA804967A - FB: ucmd fuse prog -y 0 732 0xDC14638B - FB: ucmd fuse prog -y 0 733 0xB3A914F7 - FB: ucmd fuse prog -y 0 734 0x211FD529 - FB: ucmd fuse prog -y 0 735 0x8273EBD2 - FB: ucmd fuse prog -y 0 736 0x6E0B791C - FB: ucmd fuse prog -y 0 737 0x6A558134 - - FB: acmd reset - FB: done - -Upon reboot, if ``CONFIG_AHAB_BOOT`` is set, AHAB will raise events to indicate that an **unsigned imx-boot image** has been executed. -Those events can be inspected by running U-Boot's command ``ahab_status`` for i.MX8/i.MX8x:: - - => ahab_status - Lifecycle: 0x0020, NXP closed - - SECO Event[0] = 0x0087EE00 - CMD = AHAB_AUTH_CONTAINER_REQ (0x87) - IND = AHAB_NO_AUTHENTICATION_IND (0xEE) - -To secure the platform, there is an extra step that needs to be done: -we will only take that step once we are sure that we can successfully sign and boot a signed boot image with a matching set of keys (containing the same public key hashes as those stored in the SRK fuses). - -How to Sign an i.MX Boot Image ------------------------------- - -To build a signed image, you need to create a Command Sequence File (CSF) describing the commands that the CSU executes during secure boot. -These commands instruct AHAB on which memory areas to authenticate, which keys to install and use, what data to write to a register, and so on. -In addition, the necessary certificates and signatures involved in the verification of the image are attached to the CSF generated binary output. - -We keep a template at ``lmp-tools/security/imx_ahab/u-boot-spl-sign.csf-template``. - -This template is used by ``lmp-tools/security/imx_ahab/sign-file.sh`` which dynamically generates the authenticate data command "Offsets" line, based on imx-boot image. -The "Offset" line contains two values: - -* Container header: offset to header of container, which contains the set of binary images that should be signed -* Signature block: offset to the signature block header. - -.. warning:: - Once the security fuses have been programmed, we recommend that all your UUU scripts be modified to use only **signed imx-boot** images. - Some of those scripts might depend on the occurrence of AHAB events. - -``lmp-tools/security/imx_ahab/sign-file.sh`` executes NXP's Code Signing Tool after preparing the CSF information based on the template:: - - $ cd security/imx_ahab/ - $ ./sign-file.sh --cst ./cst --spl imx-boot-apalis-imx8 - SETTINGS FOR : ./sign-file.sh - --------------: - CST BINARY : cst - CSF TEMPLATE : u-boot-spl-sign.csf-template - BINARY FILE : imx-boot-apalis-imx8 - KEYS DIRECTORY: . - KEYS INDEX : 1 - - Invoking CST to sign the binary - Process completed successfully and signed file is .imx-boot-apalis-imx8.signed - - -Booting this signed imx-boot image, and inspecting the HAB status should give no HAB events. -This indicates that the image was correctly signed:: - - => ahab_status - Lifecycle: 0x0020, NXP closed - - sc_seco_get_event: idx: 0, res:3 - No SECO Events Found! - - -.. warning:: - The next fuse instruction will close the board for unsigned images: make sure you can rebuild the signed images before running this command. - -How to Close the Board ----------------------- - -.. warning:: - This section describes the manual process of closing a board. - It is preferable to use the UUU script from the next section. - The script is considered to be less error-prone, as it contains implicit checks for SRK values. - -Now we can close the device so that from here on only signed images can be booted on the platform. -For this we run ``ahab_close``:: - - => ahab_close - -Rebooting the board and checking the AHAB status should give lifecycle value ``0x80 OEM closed``. - -.. warning:: - A production device should also "lock" the SRK values to prevent bricking a closed device. - Refer to the Security Reference Manual for the location and values of these fuses. - -How to Close the Board Using UUU Script ---------------------------------------- - -To avoid mistakes, the board securing procedure can be automated using SDP via NXP's Universal Update Utility, with a script as follows:: - - uuu_version 1.3.102 - - SDPS: boot -f imx-boot-mfgtool.signed - CFG: FB: -vid 0x0525 -pid 0x4000 - CFG: FB: -vid 0x0525 -pid 0x4025 - CFG: FB: -vid 0x0525 -pid 0x402F - CFG: FB: -vid 0x0525 -pid 0x4030 - CFG: FB: -vid 0x0525 -pid 0x4031 - - SDPU: delay 1000 - SDPU: write -f u-boot-mfgtool.itb - SDPU: jump - - # These commands will be run when use SPL and will be skipped if no spl - # if (SPL support SDPV) - # { - SDPV: delay 1000 - SDPV: write -f u-boot-mfgtool.itb - SDPV: jump - # } - - FB: ucmd if mmc dev 0; then setenv fiohab_dev 0; else setenv fiohab_dev 1; fi; - - FB: ucmd setenv srk_0 0x7E90F8D6 - FB: ucmd setenv srk_1 0xE1020512 - FB: ucmd setenv srk_2 0x4FF77EB2 - FB: ucmd setenv srk_3 0x1D964702 - FB: ucmd setenv srk_4 0x5ED61C06 - FB: ucmd setenv srk_5 0x14139AB9 - FB: ucmd setenv srk_6 0x0A57872C - FB: ucmd setenv srk_7 0xF367F432 - FB: ucmd setenv srk_8 0xE8153815 - FB: ucmd setenv srk_9 0xA804967A - FB: ucmd setenv srk_10 0xDC14638B - FB: ucmd setenv srk_11 0xB3A914F7 - FB: ucmd setenv srk_12 0x211FD529 - FB: ucmd setenv srk_13 0x8273EBD2 - FB: ucmd setenv srk_14 0x6E0B791C - FB: ucmd setenv srk_15 0x6A558134 - - FB[-t 1000]: ucmd if fiohab_close; then echo Platform Secured; else echo Error, Can Not Secure the Platform; sleep 2; fi - FB: acmd reset - - FB: done - -U-Boot ``fiohab_close`` will automatically validate that all SRK fuses have the correct values. -It will then close the board if the values are correct, otherwise it will print an error message. - -.. seealso:: - * :ref:`ref-boot-software-updates-imx8qm` - -.. _AN12312 Secure Boot on i.MX 8 and i.MX 8X Families using AHAB—Application Note: - https://www.nxp.com/docs/en/application-note/AN12312.pdf - -.. _lmp-tools/security/imx_ahab: - https://github.com/foundriesio/lmp-tools/tree/master/security/imx_ahab diff --git a/source/reference-manual/security/secure-boot-imx-habv4.rst b/source/reference-manual/security/secure-boot-imx-habv4.rst deleted file mode 100644 index e79a1fd26..000000000 --- a/source/reference-manual/security/secure-boot-imx-habv4.rst +++ /dev/null @@ -1,352 +0,0 @@ -.. highlight:: sh - -.. _ref-secure-boot-imx-habv4: - -Secure Boot on i.MX 6/8M Using HABv4 -====================================== - -On the i.MX 6/8M platforms, Secure Boot is implemented via the High Availability Boot (HABv4) component of the on-chip ROM. -The ROM is responsible for loading the initial program image, the bootloader; HABv4 then enables the ROM to authenticate it using digital signatures. - -HABv4 also provides a mechanism to establish a root of trust for the remaining software components and establishes a secure state—the close state—on the i.MX IC secure state machine in hardware. - -Our Implementation ------------------- - -The LmP uses U-Boot as the bootloader, with SPL being its first stage loader. -Our Secure Boot implementation will put the IC in a secure state, accepting only signed SPL firmware. - -SPL then boots the trusted execution environment—OP-TEE—where we run an 'early' trusted application, ``fiovb`` (Foundries.io™ Verified Boot). -This trusted application provides secure access to the Replay Protected Memory Block (RPMB) partition in eMMC. -This is used to store keys, firmware, and rollback information. - -OP-TEE also prepares the next stage bootloader—U-Boot—and generates an overlay DTS for the Linux® kernel consumption. -U-Boot implements the ``fiovb`` command to validate the trusted application functionality. - -U-Boot then jumps to the kernel entry point. - -A system which boots without TF-A would look as follows: - -.. figure:: /_static/reference-manual/security/imx-secure-boot.png - :align: center - :width: 6in - -Systems using TF-A (ie, i.MX 8M*) are slightly different. -The following diagrams describes the secure boot sequence with a succinct description of the Yocto Project meta-layer's configuration for i.MX 8MM based platforms with TF-A: - -.. figure:: /_static/reference-manual/security/imx8-secure-boot.png - :align: left - :width: 8in - -The communication path to gain access from userland to RPMB via the pseudo trusted application (PTA) follows the OP-TEE standard convention for PTAs (as the image below describes). -Userland uses ``libteec`` to issue an ioctl call to the Linux TEE driver, which in turn transitions the processor to its secure state and calls the application entrypoint. - -With this in mind, ``fiovb`` is implemented as a secured user application instead of a PTA. - -.. figure:: /_static/reference-manual/security/optee-pta-access.png - :align: center - :width: 6in - -HABv4 Architecture Overview ---------------------------- - -HABv4 authentication is based on public key cryptography using the RSA algorithm, in which image data is signed offline using a series of private keys. -The resulting signed image data is then verified on the i.MX processor using the corresponding public keys. - -This key structure is known as a PKI tree; super root keys, or SRK, are components of the PKI tree: HAB relies on a table of the public SRKs to be hashed and placed in fuses on the target. -The i.MX Code Signing Tool (CST) is used to generate the HABv4 signatures for images using the PKI tree data and SRK table. - -On the target, HAB evaluates the SRK table included in the signature by hashing it and comparing the result to the SRK fuse values: if the SRK verification is successful, this establishes the root of trust, and the remainder of the signature can be processed to authenticate the image. - -How to Secure the Platform --------------------------- - -.. note:: - This page illustrates how the HABv4 Secure Boot process works. - It provides background information for our :ref:`ref-secure-machines` implementation for better understanding. - - We recommend fusing and closing a board following our :ref:`ref-secure-machines` guide. - In the guide, some steps described here are omitted, and handled in our code for simpler and safer operations. - -The first step is to generate the PKI tree, and commit the fuse table to the hardware. - -.. warning:: - Once the fuses have been programmed they can not be modified. - -Please refer to the NXP® `Secure Boot Using HABv4 Guide`_ for a detailed description on how to generate the PKI tree. - -For development purposes, we keep i.MX HABv4 sample keys and certificates at `lmp-tools/security/imx_hab4`_. -The fuse table can be inspected by executing the ``print_fuses`` script in that same directory. -The output should be:: - - 0xEA2F0B50 - 0x871167F7 - 0xF5CECF5D - 0x364727C3 - 0x8DD52832 - 0xF158F65F - 0xA71BBE78 - 0xA3AD024A - -The Security Reference Manual for your specific SoC will indicate which fuses need to be programmed with the SRK fuse information. - -i.MX 8MM Fusing -^^^^^^^^^^^^^^^ - -.. warning:: - The values shown in this section are just examples of our standard LmP HABv4 keys and are not meant for production. - Fuses cannot be changed after the first write. - -On the i.MX 8MM the A-core fuses are stored in fuse banks 6-7, words 0 to 3:: - - => fuse prog -y 6 0 0xEA2F0B50 - => fuse prog -y 6 1 0x871167F7 - => fuse prog -y 6 2 0xF5CECF5D - => fuse prog -y 6 3 0x364727C3 - => fuse prog -y 7 0 0x8DD52832 - => fuse prog -y 7 1 0xF158F65F - => fuse prog -y 7 2 0xA71BBE78 - => fuse prog -y 7 3 0xA3AD024A - -Alternatively, you can use the kernel to program the A-core fuses via SDP by using NXP's Universal Update Utility. -This is shown in the following script:: - - uuu_version 1.2.39 - - SDP: boot -f imx-boot-mfgtool.signed - - SDPU: delay 1000 - SDPV: write -f u-boot-mfgtool.itb - SDPV: jump - - FB: ucmd fuse prog -y 6 0 0xEA2F0B50 - FB: ucmd fuse prog -y 6 1 0x871167F7 - FB: ucmd fuse prog -y 6 2 0xF5CECF5D - FB: ucmd fuse prog -y 6 3 0x364727C3 - FB: ucmd fuse prog -y 7 0 0x8DD52832 - FB: ucmd fuse prog -y 7 1 0xF158F65F - FB: ucmd fuse prog -y 7 2 0xA71BBE78 - FB: ucmd fuse prog -y 7 3 0xA3AD024A - - FB: acmd reset - - FB: DONE - - -Upon reboot, if ``CONFIG_IMX_HAB`` is enabled in U-Boot, HABv4 will raise events indicating that an **unsigned SPL image** has been executed. -Host events can be inspected by running U-Boot's ``hab_status`` command. - -.. important:: - - Once the security fuses have been programmed, modify all your UUU scripts to use only **signed SPL** images. - Some of those scripts might depend on the occurrence of HABv4 events. - This is already covered in our :ref:`ref-secure-machines` implementations. - -To secure the platform, there is an extra fuse that needs to be programmed. -We will only take this step once we are sure that we can successfully sign and boot a signed SPL image with a matching set of keys (containing the same public key hashes as those stored in the SRK fuses). - -How to Sign an SPL Image ------------------------- - -.. note:: - - We provide a ``readme.md`` file with straight forward instructions on signing the SPL and mfgtool/SDP SPL for each board in our :ref:`ref-secure-machines` implementations. - This is part of the ``mfgtool-files`` artifact for the secure machines. - -To build a signed image, you need to create a Command Sequence File (CSF) describing all the commands that the ROM will execute during Secure Boot. -These commands instruct HABv4 on which memory areas to authenticate, which keys to install and use, what data to write to a register, and so on. -In addition, the necessary certificates and signatures involved in the verification of the image are attached to the CSF generated binary output. - -We keep a template at ``lmp-tools/security/imx_hab4/u-boot-spl-sign.csf-template``. - -This template is used by ``lmp-tools/security/imx_hab4/sign-file.sh`` script which dynamically generates the authenticate data command "blocks" line(s) based on your binary. The command "blocks" line contains three values: - -* The first value is the address on the target where HAB expects the signed image data to begin. -* The second value is the offset into the file where CST will begin signing. -* The third value is length in bytes of the data to sign starting from the offset. - - -It is also required that the IVT and DCD regions are signed. HAB will verify the DCD and IVT fall in an authenticated region: The CSF will not successfully authenticate unless all commands are successful and all required regions are signed. - -In the case of the SPL, you must enable **CONFIG_IMX_HAB** to include the IVT and DCD information. - -The ``lmp-tools/security/imx_hab4/sign-file.sh`` script executes NXP's Code Signing Tool after preparing the CSF information based on the template: - -.. code-block:: shell - - $ cd security/imx_hab4/ - $ ./sign-file.sh --cst ./cst --spl SPL - - SETTINGS FOR : ./sign-file.sh - --------------: - CST BINARY : ./cst - CSF TEMPLATE : u-boot-spl-sign.csf-template - BINARY FILE : SPL - KEYS DIRECTORY: . - FIX-SDP-DCD : no - - FOUND HAB Blocks 0x2f010400 0x00000000 0x00018c00 - CSF Processed successfully and signed data available in SPL_csf.bin - $ ls SPL.signed - SPL.signed - -All intermediate files generated during the signing process are removed by the script. - -Booting this signed SPL image and inspecting the HAB status should give no HAB events therefore indicating that the image was correctly signed:: - - => hab_status - Secure boot disabled - HAB Configuration: 0xf0, HAB State: 0x66 - No HAB Events Found! - -.. warning:: - The next fuse instruction will close the board for unsigned images: make sure you can rebuild the signed images before programming that fuse. - - -Now we can close the device — From here on only signed images can be booted on the platform:: - - => fuse prog 29 6 0x80000000 - -For i.MX 8MM you have to fuse bit25 of word 3 from bank 1 (SEC_CONFIG[1] in the documentation):: - - => fuse prog 1 3 0x2000000 - - -Rebooting the board and checking the HAB status should give:: - - => hab_status - Secure boot enabled - HAB Configuration: 0xcc, HAB State: 0x99 - No HAB Events Found! - -.. warning:: - A production device should also "lock" the SRK values to prevent bricking a closed device. Refer to the Security Reference Manual for the location and values of these fuses. - - -How to Sign an SPL Image for SDP -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Once the device has been closed, only signed images will be able to run on the processor: this means that injections via UUU/SDP will stop working unless the SPL it uses is properly signed. - -1. On i.MX 6UL/6ULL families, the SDP imposes the following restrictions: - -* SDP requires that the CSF is modified to include a check for the DCD table -* SDP requires that the DCD address of the image is cleared from the header - -To comply with these requirements we need to sign the image adding the ``--fix-sdp-dcd`` parameter: - -.. code-block:: console - - $ cd security/imx_hab4/ - $ ./sign-file.sh --cst ./cst --spl SPL --fix-sdp-dcd - - SETTINGS FOR : ./sign-file.sh - --------------: - CST BINARY : ./cst - CSF TEMPLATE : u-boot-spl-sign.csf-template - BINARY FILE : SPL - KEYS DIRECTORY: . - FIX-SDP-DCD : yes - - 4+0 records in - 4+0 records out - 4 bytes copied, 8.3445e-05 s, 47.9 kB/s - 4+0 records in - 4+0 records out - 4 bytes copied, 6.6832e-05 s, 59.9 kB/s - FOUND DCD Blocks 0x2f010000 0x0000002c 0x00000258 - FOUND HAB Blocks 0x2f010400 0x00000000 0x00021c00 - CSF Processed successfully and signed data available in SPL_csf.bin - $ ls SPL.signed - SPL.signed - -2. On i.MX 8M and i.MX 6 families, using the ``--fix-sdp-dcd`` parameter is not required. - - -.. note:: - Which SoCs fall in which category can be identified by inspecting the `Universal Update Utility`_ g_RomInfo. - If the option ``ROM_INFO_HID_SKIP_DCD`` is configured, then the DCD does **not** need to be fixed for that SoC. - - -Booting Signed Images With the `Universal Update Utility`_ -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. note:: - These steps are covered in our mfgtool implementation of :ref:`ref-secure-machines`. - -1. For i.MX 6UL/6ULL, we need to let SDP know the DCD location, as well as inform it that the DCD has been cleared. -A typical UUU boot script would be (replace ``@@MACHINE@@`` with your machine configuration name): - -.. code-block:: console - :emphasize-lines: 3 - - uuu_version 1.0.1 - - SDP: boot -f SPL.signed-@@MACHINE@@ -dcdaddr 0x2f010000 -cleardcd - - SDPU: delay 1000 - SDPU: write -f u-boot-@@MACHINE@@.itb - -2) On i.MX 8M and i.MX 6 families — those where SDP does not impose DCD restrictions — the UUU boot script will look like: - -.. code-block:: none - - uuu_version 1.0.1 - - SDP: boot -f SPL.signed-@@MACHINE@@ - - SDPU: delay 1000 - SDPU: write -f u-boot-@@MACHINE@@.itb - -In both cases, if the device has been closed and is only accepting signed images, **it is recommended that UUU be started before powering the board, and before connecting it to the host PC, so that UUU polls for the connection and responds to it as soon as possible**. -To that effect we need to make sure of UUU's polling period flag: - -.. code-block:: console - - $ uuu -pp 1 file.uuu - -.. note:: - - The flags `-dcdaddr`_, `-cleardcd`_, and `-pp`_ are required for SDP on older SoCs. - These have been contributed to the Universal Update Utility by Foundries.io. - Make sure your UUU version is up-to-date with these changes. - -Booting a Closed System With a CAAM Device ------------------------------------------- - -If you are running with a *Cryptographic Acceleration and Assurance Module* device, notice that in the closed configuration—and for devices with HAB 4.4.0 (or lower)—the HAB code locks the job ring and DECO master ID registers. - -If the user-specific application requires any changes in the CAAM MID registers, it is necessary to add the “Unlock CAAM MID” command into the CSF file. -Not doing so, since the CAAM will not have been configured for the proper MIDs, leaves some of the CAAM registers not accessible for writing. -Thus, any attempt to write to them will cause system **core fails**. - -.. note:: - The current NXP BSP implementation expects the CAAM registers to be unlocked when configuring the CAAM to operate in the non-secure TrustZone world. - This applies when OP-TEE is enabled on the i.MX 6 processor. - -Our ``u-boot-spl-sign.csf-template`` takes care of supporting CAAM on closed platforms by adding the following section:: - - [Authenticate CSF] - - [Unlock] - Engine = CAAM - Features = MID, RNG - -.. seealso:: - * :ref:`ref-boot-software-updates-imx` - -.. _Secure Boot Using HABv4 Guide: - https://www.nxp.com/webapp/Download?colCode=AN4581&location=null - -.. _Universal Update Utility: - https://github.com/nxp-imx/mfgtools - -.. _-dcdaddr: - https://github.com/nxp-imx/mfgtools/commit/003b6cb7a98ba36d78d591b5c1ef8e42423f1b90 -.. _-cleardcd: - https://github.com/nxp-imx/mfgtools/commit/a3e9f5b84d28666d53f565abecf59996b7810aca - -.. _-pp: - https://github.com/nxp-imx/mfgtools/commit/5a790eae0a0f424e145171681e1a3a4f3fa47904 - -.. _lmp-tools/security/imx_hab4: - https://github.com/foundriesio/lmp-tools/tree/master/security/imx_hab4 diff --git a/source/reference-manual/security/secure-elements/se050-enablement.rst b/source/reference-manual/security/secure-elements/se050-enablement.rst deleted file mode 100644 index ebe0fa93e..000000000 --- a/source/reference-manual/security/secure-elements/se050-enablement.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. _ref-security_se05x_enablement: - -Enabling SE05X -============== - -This section demonstrates how to enable the SE05X middleware in ``meta-subscriber-overrides``. - -.. note:: - This procedure is valid for boards running OP-TEE 3.15.0 or newer. - -Enable the ``se05x`` ``MACHINE_FEATURES`` for the target machine and provide the correct OEFID in ``lmp-factory-custom``. -The OEFID value can be found in `SE050 configurations`_. - -``conf/machine/include/lmp-factory-custom.inc``: - -.. code-block:: none - - SE05X_OEFID: = "0xA1F4" - MACHINE_FEATURES:append: = " se05x" - -.. note:: - If set incorrectly, the *correct* OEFID value can be checked in the boot log: - - .. code-block:: none - - I/TC: OP-TEE version: 3.15.0-84-gf0446cdb3 (gcc version 10.2.0 (GCC)) #1 Sat 11 Dec 2021 02:11:09 AM UTC aarch64 - I/TC: Primary CPU initializing - I/TC: se050: Info: Applet ID - ... - I/TC: se050: Info: OEF ID - I/TC: se050: Info: a1.f4 - -This step is enough to enable SE05X for the supported machines for Factories created since LmP v85. - -Push the changes to the ``meta-subscriber-overrides``, triggering a new build with SE05X support enabled. -Be aware that an image created with SE05X enabled does not boot on boards without the SE05X properly attached. - -.. note:: - Please be aware that at this moment only: - - * ``imx6ullevk`` - * ``imx8mn-ddr4-evk`` - * ``imx8mm-lpddr4-evk`` - * ``imx8mp-lpddr4-evk`` - - support SE05X integration without extra changes in LmP. - -.. _SE050 configurations: - https://www.nxp.com/docs/en/application-note/AN12436.pdf diff --git a/source/reference-manual/security/secure-elements/secure-element.050.rst b/source/reference-manual/security/secure-elements/secure-element.050.rst deleted file mode 100644 index 0b40a95d8..000000000 --- a/source/reference-manual/security/secure-elements/secure-element.050.rst +++ /dev/null @@ -1,330 +0,0 @@ -.. highlight:: sh - -.. _ref-secure-element: - -EdgeLock™ SE05x: Plug & Trust Secure Element -============================================ - -There is extensive documentation online about the EdgeLock™ SE05x Secure Element. -It will not be duplicated here. -However, for reference we recommend the following: - -**Data Sheet**: -`SE05x Plug & Trust Secure Element`_ - -**Application Notes**: -`User Guidelines`_, -`SE05x APDU Specification`_, -`Ease ISA/IEC 62443 compliance with EdgeLock`_ - -**User Manuals**: -`NXP SE05x T=1 Over I2C Specification`_ - -The EdgeLock™ SE05x follows the Global Platform Card Specification. -In addition to the product documentation above, we advise awareness of the specification by reading the following documents: - -**Global Platform Specifications**: `Card Specification 2.3.1`_, `Secure Channel Protocol 03`_ - -NXP SE05x Plug & Trust MW --------------------------- - -NXP® provides a software stack, the SE05x Plug&Trust Middleware, to support this device in a number of environments. - -There is also extensive documentation in the form of PDF and HTML browsable documents -within the freely downloadable `NXP SE05x Plug & Trust MW`_ software package. -We recommend downloading and reading them indepth to better understand what the product has to offer. - -A reduced open source version of this middleware is the Plug-and-Trust `mini package`_ used in our OP-TEE integration. -We forked the repository and maintain it on our public GitHub server. - -Support for the SE05x exists in OP-TEE upstream. -OP-TEE references this project in order to run its Azure CI pipeline and avoid build regressions. - -.. note:: - The support for the SE05x in OP-TEE is generic and not platform dependent. - It only requires an OP-TEE native I2C driver to enable SCP03 early during boot. - - -NXP SE05x Plug & Trust TEE Integration --------------------------------------- - -At Foundries.io, we believe in securing systems by extending the perimeter of the **hardware root of trust** to as many operational phases as possible: -secure monitoring, secure authentication, storage protection, and secure communication and key management. - -For those targeting the NXP SE05x in their designs, we chose to integrate the NXP middleware with our ROT (root of trust). -We did this by bringing it under the umbrella of our Trusted Execution Environment: OP-TEE. - -The SE05x middleware is a behemoth of a software stack: highly configurable, highly flexible and therefore sometimes difficult to navigate. -From its flexibility comes complexity and size—well over half a million lines of code. - -Fortunately, most of the functionality provided by the TEE overlaps with that provided by the SE05x. -In particular, all cryptographic operations have a software mirror implementation in OP-TEE: ECC, RSA, MAC, HASH, AES, 3DES and so forth. - -This meant that we could validate our integration using the OP-TEE crypto regression test suite from the `OP-TEE tests`_ - -The main advantage of using the SE05x in a product design which already runs a TEE -is that all private keys programmed in the device's non volatile memory will never be leaked to the outside world. - -The SE05x also provides a real random number generator which can be exported to the REE (normal world) to improve its entropy requirements. - -Because the TEE is its only client, the TEE SE05x stack only requires a single global session and key store. -Policies are configured so only the SCP03 enabled session can access its objects for creation or deletion. - -OP-TEE Integration -------------------- - -The SE05x standard physical interface is I2C typically configured as a target running in high speed mode (3.4Mbps). -Since the SE05x could replace the OP-TEE default crypto operations (software), we chose to implement a native I2C driver. -This is so the SE05x could be accessed as early as possible. - -OP-TEE's cryptographic providers are not runtime configurable. -This means the user must choose at compile time where to execute its cryptographic functions: -whether in libmbedtls, libtomcrypt or now in the SE05x. -But this is **not** an all or nothing configuration, and operations can be routed to one service or another. -For instance, on an iMX platform the Hardware Unique Key (HUK) could be retrieved from the CAAM, AES ECB, -and HASH operations implemented in libtomcrypt, and also RNG, ECC, and RSA in the SE05x. - -.. note:: - In a typical scenario, choosing to run AES ECB and HASH on the SE05x might be a bad idea due to its performance implications. - Those operations are heavily used to verify the trusted filesystem in OP-TEE, and would dramatically slow down the opening of trusted applications. - -Serial Communications to the SE05x ----------------------------------- - -The first step taken during integration work was to develop and upstream a native I2C driver (imx_i2c). -But since this driver could not be used once the REE started executing—as it would not protect against I2C bus collisions or power management -implementations controlled from the REE—we needed a second driver. -This would serve as a i2c trampoline service, capable of routing I2C read and write operations from OP-TEE to the REE driver (Linux® in particular). - -.. note:: - These drivers are configurable using the following build options:: - - CFG_CORE_SE05X_I2C_BUS= : the I2C bus where the SE05x sits - CFG_CORE_SE05X_BAUDRATE= : the SE05x baud-rate in mbps - -Secure Communication Protocol 03 ---------------------------------- - -The SE05x has native support for Global Platform Secure Communication Protocol 03. -This allows us to protect the integrity of end-to-end communications between the processor and the SE05x. -All data sent to the SE05x is software encrypted. -All data received is decrypted in the TEE, using a set of session specific keys. -These keys are derived from predefined keys which are shipped with the devices. - -.. note:: - You can select whether to enable SCP03 during the secure world initialization, - or at a later time, using the `scp03`_ command:: - - CFG_CORE_SE05X_SCP03_EARLY=y : enables SCP03 before the Normal World has booted - CFG_SCP03_PTA=y : allows SCP03 to be enabled from the Normal World. - -The predefined factory keys stored on the SE05X NVM (**static keys** from here on) are public. -Therefore, they should be rotated to a secret set from which session keys can be derived. - -Avoiding the need to store new static keys reduces attack surface and simplifies the firmware upgrade process. -To this end, the new set of keys will be derived in OP-TEE from its core secret: the Hardware Unique Key (HUK) - -.. warning:: - Once the static SCP03 keys have been derived from the HUK and programmed into the device's NVM, the **HUK must not change**. - It is equally critical that the HUK remains a **secret**. - -There are two different ways of rotating the SCP03 key: with and without user intervention from the Normal World. - -To rotate the static SCP03 keys from the Trust Zone before the Normal World is executed, -enable ``CFG_CORE_SE05X_SCP03_PROVISION_ON_INIT=y``. - -To rotate the static SCP03 keys from the Normal World, -enable ``CFG_CORE_SE05X_SCP03_PROVISION=y`` and then use the `scp03`_ command. - -SE05x Non Volatile Memory -------------------------- - -The current implementation of the SE05x TEE driver only allows for permanent storage of the ECC and RSA keys. -These keys can be managed using the cryptoki API implementing the pkcs#11 standard. -External keys used by the SE05x to perform other cryptographic operations are not stored in the SE05x NVM. - -.. note:: - The SE05x NVM can be cleared by setting the following configuration option:: - - CFG_CORE_SE05X_INIT_NVM=y - - Alternatively, the SE05x NVM can also be cleared by issuing the following command on the target: - - .. code-block:: console - - $ ssscli se05x reset - - The ssscli tool will be discussed in the next section. - - -Be aware that initializing the NVM would cause all keys and objects to be deleted from permanent storage. -This would not affect any handles that the PKCS#11 TA might have stored in its database, which would now point nowhere. -However, this configuration option has no impact on the SCP03 set of static keys which will remain unchanged. - - -Importing Secure Objects to PKCS#11 Tokens ------------------------------------------- - -After manufacturing, the NXP SE05x will contain pre-provisioned keys and certificates. -These secure objects can be known through their product specific internal documentation. -They will also be accessible from the TEE by their 32 bit identifiers. - -To import those objects into PKCS#11 tokens, we have extended the `TEE pkcs#11 implementation`_. -This allows the user to call standard tools like pkcs11-tool to import keys into the database. -As previously noted, private keys can not be exposed outside the secure element. -Therefore, these calls only import the handles to access those keys. -The SE05x OP-TEE driver is prepared to work with either keys or key handles. -Storing handles in the pkcs#11 database does not impose restrictions. - -.. note:: - The private key will be a handle to the actual key in the element NVM. - Private keys are **never** exposed outside the NXP SE05x. - For example, to import the data-sheet documented 32 bit 0xF7000001 RSA 4096 bit key into the pkcs#11 database, - issue the following command: - - .. code-block:: console - - $ pkcs11-tool --module /usr/lib/libckteec.so.0.1 --keypairgen --key-type RSA:4096 --id 01 --token-label fio --pin 87654321 --label SE_7F000001 - - -We have also developed a tool, the `SE05x Object Import Application`_. -This tool interfaces with the TEE and gains access to the SE05x to import keys *and* certificates. -It can also list and remove objects from the secure element non-volatile memory. - -The *certificates* are retrieved in DER format using the APDU interface presented by the driver, and are then written to the pkcs#11 token. - -The tool uses `libseteec`_ to send the APDUs to the secure element. -and `libckteec`_ to interface with the PKCS#11 implementation. - -The `apdu`_ based interface enables privileged user applications to access the Secure Element. -It does this by allowing the normal world to send APDU frames. -These encode data and operations to the SE05x using OP-TEE's SCP03 enabled secure session. - -Find usage examples in the note below. -Be aware that in OP-TEE's PKCS#11 implementation, **each** PKCS#11 slot is indeed a token. - -.. note:: - Import NXP SE051 Certficate with the id 0xf0000123 into OP-TEE pkcs#11'aktualizr' token storage: - - .. code-block:: console - - $ fio-se05x-cli --token-label aktualizr --import-cert 0xf0000123 --id 45 --label fio - - Show NXP SE050 Certficate with the id 0xf0000123 on the console: - - .. code-block:: console - - $ fio-se05x-cli --show-cert 0xf0000123 --se050 - - Import NXP SE051 RSA:2048 bits key with the id 0xf0000123 into OP-TEE pkcs#11 'aktualizr' token storage: - - .. code-block:: console - - $ fio-se05x-cli --token-label aktualizr --import-key 0xf0000123 --id 45 --key-type RSA:2048 --pin 87654321 - - List all objects in the device's Non Volatile Memory: - - .. code-block:: console - - $ fio-se05x-cli --list-objects - - Delete OP-TEE created objects from the device's Non Volatile Memory (one specific object or all): - - .. code-block:: console - - $ fio-se05x-cli --delete-object 0x123456a1 - $ fio-se05x-cli --delete-object all - - -The following diagram succinctly details the overall design: - -.. figure:: /_static/reference-manual/security/se050-import-keys.png - :align: center - :width: 6in - - -A python application that also uses the APDU interface is `ssscli`_. -This tool developed by NXP to provide direct access to its secure element. -While it can serve a purpose during development, it is not required on a deployed product. -We advise deploying with ``fio-se05x-cli`` and the standard pkcs#11 tools instead. - - -.. code-block:: console - - fio@imx8mm-lpddr4-evk:~/$ ssscli - Usage: ssscli [OPTIONS] COMMAND [ARGS]... - - Command line interface for SE05x - - Options: - -v, --verbose Enables verbose mode. - --version Show the version and exit. - --help Show this message and exit. - - Commands: - a71ch A71CH specific commands - cloud (Not Implemented) Cloud Specific utilities. - connect Open Session. - decrypt Decrypt Operation - disconnect Close session. - encrypt Encrypt Operation - erase Erase ECC/RSA/AES Keys or Certificate (contents) - generate Generate ECC/RSA Key pair - get Get ECC/RSA/AES Keys or certificates - policy Create/Dump Object Policy - refpem Create Reference PEM/DER files (For OpenSSL Engine). - se05x SE05X specific commands - set Set ECC/RSA/AES Keys or certificates - sign Sign Operation - verify verify Operation - - -.. _TEE pkcs#11 implementation: - https://github.com/OP-TEE/optee_os/tree/master/ta/pkcs11 - -.. _SE05x Plug & Trust Secure Element: - https://www.nxp.com/docs/en/data-sheet/SE050-DATASHEET.pdf - -.. _User Guidelines: - https://www.nxp.com/webapp/Download?colCode=AN12514 - -.. _SE05x APDU Specification: - https://www.nxp.com/docs/en/application-note/AN12413.pdf - -.. _Ease ISA/IEC 62443 compliance with EdgeLock: - https://www.nxp.com.cn/docs/en/application-note/AN12660.pdf - -.. _NXP SE05x T=1 Over I2C Specification: - https://www.nxp.com/webapp/Download?colCode=UM11225&location=null - -.. _Card Specification 2.3.1: - https://globalplatform.org/specs-library/card-specification-v2-3-1/ - -.. _Secure Channel Protocol 03: - https://globalplatform.org/wp-content/uploads/2014/07/GPC_2.3_D_SCP03_v1.1.2_PublicRelease.pdf - -.. _NXP SE05x Plug & Trust MW: - https://www.nxp.com/products/security-and-authentication/authentication/edgelock-se050-plug-and-trust-secure-element-family-enhanced-iot-security-with-high-flexibility:SE050#design-resources -.. _scp03: - https://u-boot.readthedocs.io/en/latest/usage/cmd/scp03.html - -.. _OP-TEE tests: - https://optee.readthedocs.io/en/latest/building/gits/optee_test.html - -.. _mini package: - https://github.com/NXP/plug-and-trust - -.. _libseteec: - https://github.com/OP-TEE/optee_client/commit/f4f54e5a76641fda22a49f00294771f948cd4c92 - -.. _libckteec: - https://github.com/OP-TEE/optee_client/tree/master/libckteec - -.. _ssscli: - https://github.com/foundriesio/plug-and-trust-ssscli - -.. _SE05x Object Import Application: - https://github.com/foundriesio/fio-se05x-cli - -.. _apdu: - https://github.com/OP-TEE/optee_client/blob/master/libseteec/src/pta_apdu.h diff --git a/source/reference-manual/security/secure-machines.rst b/source/reference-manual/security/secure-machines.rst deleted file mode 100644 index 513f60a4e..000000000 --- a/source/reference-manual/security/secure-machines.rst +++ /dev/null @@ -1,126 +0,0 @@ -.. highlight:: sh - -.. _ref-secure-machines: - -Machines with Secure Aspects Enabled by FoundriesFactory -======================================================== - -The Linux® microPlatform (LmP) provides machines with secure aspects enabled by default. - -These machines obtain the configuration needed to enable Secure Boot and other security aspects. -They provide a set of artifacts to help in the process of getting hardware set to Secure Boot. - -.. warning:: - - It is recommended to read :ref:`ref-secure-boot-imx-habv4` (for i.MX8, :ref:`ref-secure-boot-imx-ahab`) before proceeding with the following steps. - -Supported Machines ------------------- - -* NXP iMX6ULL-EVK Secure: ``imx6ullevk-sec`` is the ``imx6ullevk`` machine configured to have Secure Boot enabled by default. -* NXP iMX8MMINILPD4 EVK Secure: ``imx8mm-lpddr4-evk-sec`` is the ``imx8mm-lpddr4-evk`` machine configured to have Secure Boot and secure storage enabled by default. -* NXP iMX8MNANOD4 EVK Secure: ``imx8mn-ddr4-evk-sec`` is the ``imx8mn-ddr4-evk`` machine configured to have Secure Boot and secure storage enabled by default. -* NXP iMX8MPLUSLPD4 EVK Secure: ``imx8mp-lpddr4-evk-sec`` is the ``imx8mp-lpddr4-evk`` machine configured to have Secure Boot and secure storage enabled by default. -* NXP Toradex Apalis-iMX6 Secure: ``apalis-imx6-sec`` is the ``apalis-imx6`` machine configured to have Secure Boot and secure storage enabled by default. -* NXP Toradex Apalis-iMX8 Secure: ``apalis-imx8-sec`` is the ``apalis-imx8`` machine configured to have Secure Boot and secure storage enabled by default. - -Enabling --------- - -The suggested way to enable a secure machine is to select the correct platform when creating your Factory. -However, this may not be ideal for evaluating your setup in an open state for easier development. - -The platform definition comes from ``ci-scripts``, but due to computation limits, the CI is configured to decline changes in the ``machines:`` parameter. -When attempting to replace or add a new machine in a Factory, you will likely encounter something like:: - - remote: A new machine is being added: {''} - remote: ERROR: Please contact support to update machines - remote: error: hook declined to update refs/heads/master - To https://source.foundries.io/factories//ci-scripts.git - ! [remote rejected] master -> master (hook declined) - -In this case, you should open a support ticket. - -Using the Secure Machine ------------------------- - -Trigger a platform build and wait until the Target is created. - -Follow the steps from :ref:`ug-flashing` to prepare the hardware and download the same artifacts. - -The list of artifacts downloaded should be: - -* ``mfgtool-files-.tar.gz`` -* ``lmp-factory-image-.wic.gz`` -* ``SPL-`` -* ``sit-.bin`` -* ``u-boot-.itb`` - -.. note:: - For i.MX8* based machines, the ``SPL`` binary is included in ``imx-boot``. - Refer to ``imx-boot-`` through this document. - -Expand the tarballs: - -.. code-block:: console - - $ gunzip lmp-factory-image-.wic.gz - $ tar -zxvf mfgtool-files-.tar.gz - -The resultant directory tree should look like the following:: - - ├── lmp-factory-image-.wic - ├── mfgtool-files- - │   ├── bootloader.uuu - │   ├── close.uuu - │   ├── full_image.uuu - │   ├── fuse.uuu - │   ├── readme.md - │   ├── SPL-mfgtool - │   ├── u-boot-mfgtool.itb - │   ├── uuu - │   └── uuu.exe - ├── mfgtool-files-.tar.gz - ├── SPL- - ├── sit-.bin - └── u-boot-.itb - - -Follow the ``readme.md`` under ``mfgtool-files-`` for instructions to sign the SPL images, to fuse, and close the board. - -.. warning:: - - The **fuse** and **close** procedures are irreversible. - The instructions from the ``readme.md`` file should be followed and executed with caution and only after understanding the critical implication of those commands. - -.. include:: imx-generic-custom-keys.rst - -Accessing Secure Storage ------------------------- - -.. note:: - The LmP leverages the eMMC Replay Protected Memory Block (RPMB) as secure storage. This section is only applicable for devices that provide this feature. - -Once a device has been successfully fused and closed, the secure storage RPMB becomes available. -This is accessed through ``fiovb`` (Foundries.io™ Verified Boot) early trusted application from Open Portable-Trusted Execution Environment (OP-TEE). - -By default, the secure storage only holds the variables used by ``aktualizr-lite`` to handle the updates, previously stored in ``uboot-env`` for non-fused boards. -You can extend this to store custom variables that need to be made secure, like mac addresses, serial numbers and other critical device information. - -Writing to Secure Storage -^^^^^^^^^^^^^^^^^^^^^^^^^ - -From the device: - -.. code-block:: console - - device:~# fiovb_setenv - -Reading From Secure Storage -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -From the device: - -.. code-block:: console - - device:~# fiovb_printenv diff --git a/source/reference-manual/security/security.rst b/source/reference-manual/security/security.rst index 7c1d62907..cbafbb5f7 100644 --- a/source/reference-manual/security/security.rst +++ b/source/reference-manual/security/security.rst @@ -74,18 +74,8 @@ Secure Boot specifics of select hardware platforms are described below. .. toctree:: :maxdepth: 1 - secure-boot-imx-habv4 - secure-boot-imx-ahab secure-boot-uefi -More information around the Secure Boot aspects supported by LmP can be found in: - -.. toctree:: - :maxdepth: 1 - - secure-machines - revoke-imx-keys - See how to implement the `Secure Boot Firmware Updates`_ further below. Secure Online Keys for Boot Stack @@ -128,13 +118,6 @@ Secure Boot Firmware Updates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ FoundriesFactory uses OTA_ to deliver secure boot firmware updates to your devices. -Secure Boot Firmware update specifics for select hardware platforms are described below. - -.. toctree:: - :maxdepth: 1 - - boot-software-updates-imx - boot-software-updates-imx8qm Anti-rollback protection, which prevents downgrading of boot firmware, can be enabled by following the guide below. @@ -157,6 +140,4 @@ Hardware Secure Module (Secure Element) specifics for select hardware platforms .. toctree:: :maxdepth: 1 - secure-elements/secure-element.050 - secure-elements/se050-enablement secure-elements/secure-element.tpm diff --git a/source/reference-manual/testing/lmp-testplan.rst b/source/reference-manual/testing/lmp-testplan.rst index df34dc420..ae8982978 100644 --- a/source/reference-manual/testing/lmp-testplan.rst +++ b/source/reference-manual/testing/lmp-testplan.rst @@ -1,6 +1,5 @@ .. _ref-lmp-testplan: - Test Plan ######### @@ -183,7 +182,7 @@ There are 2 scenarios for boot testing: provisioning has to be done in some other way. This is strongly dependent on hardware limitations and boot source. For example, RaspberryPi can boot from an SD card, and works well with available SDMux devices. - Conversely, iMX8MM should boot from eMMC, and requires UUU for initial flashing. + Conversely, some boards may boot from eMMC and require SoC-specific tooling for initial flashing. Both of these provisioning methods are supported by LAVA. Therefore, it is proposed to use LAVA for initial provisioning, boot, and reboot testing in this scenario. diff --git a/source/user-guide/developer-workflow/developer-workflow.rst b/source/user-guide/developer-workflow/developer-workflow.rst index 17a0f0c96..0ae2df5fb 100644 --- a/source/user-guide/developer-workflow/developer-workflow.rst +++ b/source/user-guide/developer-workflow/developer-workflow.rst @@ -106,8 +106,6 @@ If a custom board is used, it is also expected that customers provide the board :ref:`lmp-customization` - :ref:`ref-pg` - Some tips for this stage of the development: * :ref:`Local builds ` diff --git a/source/user-guide/flashing/apalis-imx6-prepare.rst b/source/user-guide/flashing/apalis-imx6-prepare.rst deleted file mode 100644 index 62a8e1855..000000000 --- a/source/user-guide/flashing/apalis-imx6-prepare.rst +++ /dev/null @@ -1,47 +0,0 @@ -Preparation ------------ - -.. important:: - Ensure you replace the ```` placeholder below with the name of your Factory. - -#. Download necessary files from ``https://app.foundries.io/factories//targets``: - - a. Click the latest Target with a ``platform`` trigger. - - b. Expand **run** in the :guilabel:`Runs` section corresponding with the name of the board. - **Download the Factory image for that machine.** - - For example:: - - lmp-factory-image-.wic.gz - u-boot-.itb - sit-.bin - SPL- - -#. Extract the file ``lmp-factory-image-apalis-imx6.wic.gz``:: - - gunzip lmp-factory-image-apalis-imx6.wic.gz - -#. Expand the **run** in the :guilabel:`Runs` section which corresponds with the board's mfgtool-files. - **Download the tools for that machine.** - - -#. Extract ``mfgtool-files-apalis-imx6.tar.gz``: - - .. code-block:: console - - $ tar -zxvf mfgtool-files-apalis-imx6.tar.gz - -#. Organize the files as in the tree below:: - - ├── lmp-factory-image-.wic.gz - ├── u-boot-.itb - ├── sit-.bin - ├── SPL- - └── mfgtool-files- -    ├── bootloader.uuu -    ├── full_image.uuu -    ├── SPL-mfgtool -    ├── u-boot-mfgtool.itb -    ├── uuu -    └── uuu.exe diff --git a/source/user-guide/flashing/apalis-imx6.rst b/source/user-guide/flashing/apalis-imx6.rst deleted file mode 100644 index c7f00b143..000000000 --- a/source/user-guide/flashing/apalis-imx6.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _ref-rm_boards_apalis-imx6: - -Apalis iMX6 with the Ixora Carrier Board -======================================== - -.. include:: secure-boot-note.rst - -.. include:: apalis-imx6-prepare.rst - -.. include:: apalis-ixora-recovery.rst - -Flashing --------- - -Once in serial downloader mode and connected to your PC, the evaluation board should show up as a Freescale USB device. - -.. note:: Device names and IDs can slightly differ from the steps below. - -.. include:: secure-boot-pre-flash-note.rst - -.. include:: imx6-flashing.rst - -To return to run mode, disconnect the jumper from the recovery pads (JP4) and reconnect the JP2 jumper. - -Power on the board to boot the new image. diff --git a/source/user-guide/flashing/apalis-imx8.rst b/source/user-guide/flashing/apalis-imx8.rst deleted file mode 100644 index 3bbcb427e..000000000 --- a/source/user-guide/flashing/apalis-imx8.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _ref-rm_boards_apalis-imx8: - -Apalis iMX8 with the Ixora Carrier Board -======================================== - -.. include:: imx8-prepare.rst - -.. include:: apalis-ixora-recovery.rst - -Flashing --------- - -Once in serial downloader mode and connected to your PC, the evaluation board should show up as a Freescale USB device. - -.. note:: Device names and IDs can slightly differ from the steps below. - -.. include:: imx8-flashing.rst - -To return to run mode, disconnect the jumper from the recovery pads (**JP4**) and reconnect the **JP2** jumper. - -Power on the board to boot the new image. diff --git a/source/user-guide/flashing/apalis-ixora-recovery.rst b/source/user-guide/flashing/apalis-ixora-recovery.rst deleted file mode 100644 index 1c93fb720..000000000 --- a/source/user-guide/flashing/apalis-ixora-recovery.rst +++ /dev/null @@ -1,40 +0,0 @@ -Hardware Preparation --------------------- - -Set up the board for updating using the manufacturing tools: - -#. Ensure that the power is off (**SW1**) - -#. Put the apalis-imx into Recovery Mode: - - a. Remove the **JP2** jumper from the board - - .. figure:: /_static/boards/apalis-imx-jp2.png - :width: 300 - :align: center - - JP2 location - - b. Connect the Micro-USB cable to the **X9** connector - - .. figure:: /_static/boards/apalis-imx-usb.png - :width: 300 - :align: center - - USB location - - c. Connect the two bottom pads of **JP4** as in the following images - - .. figure:: /_static/boards/apalis-imx-jp4.png - :width: 300 - :align: center - - Recovery jumper location - - .. figure:: /_static/boards/apalis-imx-jp4-close.jpeg - :width: 300 - :align: center - - Recovery jumper setup - -#. Power on the board by pressing the **SW1** button. diff --git a/source/user-guide/flashing/flashing.rst b/source/user-guide/flashing/flashing.rst index c2a55b230..039639c31 100644 --- a/source/user-guide/flashing/flashing.rst +++ b/source/user-guide/flashing/flashing.rst @@ -11,19 +11,4 @@ Select your board below to view flashing instructions. rb3gen2 beagleboneblack raspberrypi - portenta-x8 - imx8mn - imx8mm - se050_imx8mm - imx8mq - se050_imx8mq - imx8mp - se050_imx8mp - imx6ul - imx6ull - se050_imx6ull - apalis-imx6 - apalis-imx8 - imx8qm-mek - imx93evk x86 diff --git a/source/user-guide/flashing/imx-common-board.inc b/source/user-guide/flashing/imx-common-board.inc deleted file mode 100644 index 9234691dd..000000000 --- a/source/user-guide/flashing/imx-common-board.inc +++ /dev/null @@ -1,152 +0,0 @@ -Preparation ------------ - -|secure_boot_preparation_note| - -.. important:: - Ensure you replace ```` placeholder below with the name of your Factory. - -#. Download the necessary files from ``https://app.foundries.io/factories//targets``: - - a. Click the latest Target with the :guilabel:`platform` trigger. - b. Expand the **run** in the :guilabel:`Runs` section which corresponds with the name of the board. - **Download the Factory image for that machine.** - For example: - - .. code-block:: none - - lmp-factory-image-.wic.gz - u-boot-.itb - imx-boot- - - .. note:: - The compressed image (``.wic.gz``) is used since LmP **v92**. - Before, the scripts required a compressed file image (``.wic``). - -#. Download and extract the file ``mfgtool-files-.tar.gz``: - - .. parsed-literal:: - - tar -zxvf mfgtool-files-|machine_name|.tar.gz - - Contents of mfgtool-files-|machine_name| : - - .. parsed-literal:: - - |imx_mfgtool_file_list| - -#. You should now have the following: - - .. parsed-literal:: - - |imx_file_list| - - -Hardware Preparation --------------------- - -Set up the board for updating using the manufacturing tools: - -|image_board_top| - -Top view of |board_name| - -#. **OPTIONAL**. Only required if you have problems or want to see the boot console output. - - Connect the |imx_usb_type_debug| end of the USB cable into debug port |debug_port|. - Connect the other end of the cable to a PC acting as a host terminal. - |imx_n_consoles| UART connections will appear on the PC. For example, on a Linux host: - - .. parsed literal:: - - |imx_tty_list| - - Using a serial terminal program like `minicom `_, - connect to the port with |imx_tty_port| in the name (in this example |imx_tty_device|). - Apply the following configuration: - - - Baud rate: 115200 - - Data bits: 8 - - Stop bit: 1 - - Parity: None - - Flow control: None - -#. Ensure that the power is off (|power_switch|) - -#. Put the |board_name| into programing mode: - - Switch |boot_mode_switch| to |boot_mode_sdp| (from |boot_mode_bits| bit) to Download Mode. - - |image_board_SW| - - Location of |boot_mode_switch| dip switch on |board_name| - -#. Connect your computer to the |board_name| board via the |imx_usb_type_sdp| port 1 ``Download`` |download_port| jack. - -#. Connect the |imx_power_jack_type| power plug to the port 2 ``Power`` |power_jack| jack. - -#. Power on the |board_name| board by sliding power switch |power_switch| to ON. - -Flashing --------- - -Once in serial downloader mode and connected to your PC, the evaluation board should show up as an NXP® USB device. - -|secure_boot_pre_flash_note| - -.. tab-set:: - :sync-group: os - - .. tab-item:: Linux - :sync: linux - - #. Verify target is present: - - .. parsed-literal:: - - |imx_lsusb| - - In this mode you will use the ``uuu`` tools to program the images to the eMMC. - The ``USB ID`` may differ if a different SoC is used. - - #. To program the LmP to the EMMC run - - .. parsed-literal:: - - $ sudo mfgtool-files-|machine_name|/uuu mfgtool-files-|machine_name|/full_image.uuu - uuu (Universal Update Utility) for nxp imx chips -- libuuu_1.4.243-0-ged48c51 - - Success 1 Failure 0 - - - 1:92 6/ 6 [Done ] FB: done - - #. Turn off the power - #. Put the board into run mode - - .. tab-item:: Windows - :sync: windows - - #. Start the ``Device Manager`` - #. Select ``View`` - #. Select ``Devices by container`` - #. Verify a device like the following: |usb_device_windows| - #. Run the command below to program the LmP to the EMMC: - - .. parsed-literal:: - - PS C:\\Users\\Someone> mfgtool-files-|machine_name|\\uuu.exe mfgtool-files-|machine_name|\\full_image.uuu - uuu (Universal Update Utility) for nxp imx chips -- libuuu_1.4.243-0-ged48c51 - - Success 1 Failure 0 - - - 1:92 6/ 6 [Done ] FB: done - - #. Turn off the power - #. Put the board into run mode. - -Put the |board_name| into run mode by switching |boot_mode_switch| -to |boot_mode_emmc| to set the board to boot from eMMC. - -Power on the |board_name| board by sliding the power switch |power_switch| to ON. diff --git a/source/user-guide/flashing/imx6-flashing.rst b/source/user-guide/flashing/imx6-flashing.rst deleted file mode 100644 index 426c9ac2e..000000000 --- a/source/user-guide/flashing/imx6-flashing.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. tab-set:: - :sync-group: os - - .. tab-item:: Linux - :sync: linux - - #. Verify target is present: - - .. code-block:: console - - $ lsusb | grep Freescale - Bus 002 Device 052: ID 15a2:0080 Freescale Semiconductor, Inc. - - In this mode, you will use the ``uuu`` tools to program the images to the eMMC. - - #. Run the command below to program the LmP to the EMMC: - - .. code-block:: console - - $ sudo mfgtool-files-/uuu -pp 1 mfgtool-files-/full_image.uuu - uuu (Universal Update Utility) for nxp imx chips -- libuuu_1.4.43-0-ga9c099a - - Success 1 Failure 0 - - - 1:31 3/ 3 [=================100%=================] SDPV: jump - 2:31 8/ 8 [Done ] FB: done - - #. Turn off the power. - #. Put the board into run mode - - .. tab-item:: Windows - :sync: windows - - #. Start the ``Device Manager`` - #. Select ``View`` - #. Select ``Devices by container`` - #. Verify a device like the following: - - .. figure:: /_static/boards/imx6_windows.png - :width: 600 - :align: center - - #. Run the command below to program the LmP to the EMMC: - - .. code-block:: powershell - - PS C:\Users\Someone> mfgtool-files-\uuu.exe -pp 1 mfgtool-files-\full_image.uuu - uuu (Universal Update Utility) for nxp imx chips -- libuuu_1.4.43-0-ga9c099a - - Success 1 Failure 0 - - - 1:31 3/ 3 [=================100%=================] SDPV: jump - 2:31 8/ 8 [Done ] FB: done - - #. Turn off the power. - #. Put the board into run mode diff --git a/source/user-guide/flashing/imx6ul.rst b/source/user-guide/flashing/imx6ul.rst deleted file mode 100644 index be4491afc..000000000 --- a/source/user-guide/flashing/imx6ul.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. _ref-rm_board_imx6ulevk: - -i.MX 6UL Evaluation Kit -======================== - -.. |board_name| replace:: imx6ulevk -.. |machine_name| replace:: imx6ulevk -.. |debug_port| replace:: **J1901** -.. |download_port| replace:: **USB OTG** -.. |power_jack| replace:: **J2001** -.. |power_switch| replace:: **SW2001** -.. |boot_mode_switch| replace:: **SW602** -.. |boot_mode_sdp| replace:: OFF, ON -.. |boot_mode_emmc| replace:: ON, OFF -.. |boot_mode_bits| replace:: 1-2 -.. |imx_usb_type| replace:: micro-B -.. |imx_n_consoles| replace:: One -.. |imx_tty_device| replace:: ``ttyUSB2`` -.. |imx_tty_port| replace:: ``if00`` -.. |imx_usb_type_debug| replace:: micro-B -.. |imx_usb_type_sdp| replace:: micro-B -.. |imx_power_jack_type| replace:: 5V - -.. |imx_lsusb| replace:: - - $ lsusb | grep NXP - Bus 002 Device 052: ID 15a2:0080 Freescale Semiconductor, Inc. - -.. |image_board_top| image:: /_static/boards/imx6ulevk.png - :width: 600 - :align: middle - -.. |image_board_SW| image:: /_static/boards/imx6ullevk_SW1.png - :width: 600 - :align: middle - -.. |imx_tty_list| replace:: - - $ ls -l /dev/serial/by-id/ - total 0 - lrwxrwxrwx 1 root root 13 Dec 3 13:09 usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 -> ../../ttyUSB2 - -.. |usb_device_windows| image:: /_static/boards/imx6_windows.png - :width: 600 - :align: middle - -.. |imx_file_list| replace:: - - ├── lmp-factory-image-imx6ulevk.wic.gz - ├── u-boot-imx6ulevk.itb - ├── sit-imx6ulevk.bin - ├── SPL-imx6ulevk - └── mfgtool-files-imx6ulevk - -.. |imx_mfgtool_file_list| replace:: - - ├── bootloader.uuu - ├── full_image.uuu - ├── SPL-mfgtool - ├── u-boot-mfgtool.itb - ├── uuu - └── uuu.exe - -.. |secure_boot_preparation_note| replace:: The instructions in this section - show the preparation needed before the flashing procedure. - -.. |secure_boot_pre_flash_note| replace:: Follow the instructions below. - - -Pre-Preparation ---------------- - -Before starting to work with |board_name|, -switch **SW601** to device microSD by setting to OFF, OFF, ON, OFF (from 1–4 bit) - - .. figure:: /_static/boards/imx6_sw601.png - :width: 300 - :align: center - - **SW601** settings - -.. include:: imx-common-board.inc diff --git a/source/user-guide/flashing/imx6ull.rst b/source/user-guide/flashing/imx6ull.rst deleted file mode 100644 index e719bb54c..000000000 --- a/source/user-guide/flashing/imx6ull.rst +++ /dev/null @@ -1,84 +0,0 @@ -.. _ref-rm_board_imx6ullevk: - -i.MX 6ULL Evaluation Kit -======================== - -.. |board_name| replace:: imx6ullevk -.. |machine_name| replace:: imx6ullevk -.. |debug_port| replace:: **J1901** -.. |download_port| replace:: **USB OTG** -.. |power_jack| replace:: **J2001** -.. |power_switch| replace:: **SW2001** -.. |boot_mode_switch| replace:: **SW602** -.. |boot_mode_sdp| replace:: OFF, ON -.. |boot_mode_emmc| replace:: ON, OFF -.. |boot_mode_bits| replace:: 1-2 -.. |imx_n_consoles| replace:: One -.. |imx_tty_device| replace:: ``ttyUSB2`` -.. |imx_tty_port| replace:: ``if00`` -.. |imx_usb_type_debug| replace:: micro-B -.. |imx_usb_type_sdp| replace:: micro-B -.. |imx_power_jack_type| replace:: 5V - -.. |imx_lsusb| replace:: - - $ lsusb | grep NXP - Bus 002 Device 052: ID 15a2:0080 Freescale Semiconductor, Inc. - -.. |image_board_top| image:: /_static/boards/imx6ullevk.png - :width: 600 - :align: middle - -.. |image_board_SW| image:: /_static/boards/imx6ullevk_SW1.png - :width: 600 - :align: middle - -.. |imx_tty_list| replace:: - - $ ls -l /dev/serial/by-id/ - total 0 - lrwxrwxrwx 1 root root 13 Dec 3 13:09 usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 -> ../../ttyUSB2 - -.. |usb_device_windows| image:: /_static/boards/imx6_windows.png - :width: 600 - :align: middle - -.. |imx_file_list| replace:: - - ├── lmp-factory-image-imx6ullevk.wic.gz - ├── u-boot-imx6ullevk.itb - ├── sit-imx6ullevk.bin - ├── SPL-imx6ullevk - └── mfgtool-files-imx6ullevk - -.. |imx_mfgtool_file_list| replace:: - - ├── bootloader.uuu - ├── full_image.uuu - ├── SPL-mfgtool - ├── u-boot-mfgtool.itb - ├── uuu - └── uuu.exe - -.. |secure_boot_preparation_note| replace:: - The instructions in this section also applies to those boards with secure boot enabled. - There are references on how to perform common instructions along with the flow. - :ref:`ref-security` details the required background for secure boot. - -.. |secure_boot_pre_flash_note| replace:: For instructions on how to sign the - required images before flashing them to the board with secure boot enabled, - see :ref:`ref-secure-machines`. - -Pre-Preparation ---------------- - -Before starting to work with |board_name|, -switch **SW601** to device microSD by setting to OFF, OFF, ON, OFF (from 1–4 bit) - - .. figure:: /_static/boards/imx6_sw601.png - :width: 300 - :align: center - - **SW601** settings - -.. include:: imx-common-board.inc diff --git a/source/user-guide/flashing/imx8-flashing.rst b/source/user-guide/flashing/imx8-flashing.rst deleted file mode 100644 index bfd4af189..000000000 --- a/source/user-guide/flashing/imx8-flashing.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. tab-set:: - :sync-group: os - - .. tab-item:: Linux - :sync: linux - - #. Verify target is present: - - .. code-block:: console - - $ lsusb | grep NXP - Bus 001 Device 023: ID 1fc9:012b NXP Semiconductors i.MX 8M Dual/8M QuadLite/8M Quad Serial Downloader - - - In this mode, you will use the ``uuu`` tools to program the images to the eMMC. - The ``USB ID`` may differ if a different SoC is used. - - #. To program the LmP to the EMMC, run: - - .. code-block:: console - - $ sudo mfgtool-files-/uuu -pp 1 mfgtool-files-/full_image.uuu - uuu (Universal Update Utility) for nxp imx chips -- libuuu_1.4.43-0-ga9c099a - - Success 1 Failure 0 - - - 1:31 3/ 3 [=================100%=================] SDPV: jump - 2:31 8/ 8 [Done ] FB: done - - #. Turn off the power - #. Put the board into run mode. - - .. tab-item:: Windows - :sync: windows - - #. Start the ``Device Manager`` - #. Select ``View`` - #. Select ``Devices by container`` - #. Verify a device as in the following: - - .. figure:: /_static/boards/windows_verify.png - :width: 600 - :align: center - - #. To program the LmP to the EMMC, run: - - .. code-block:: powershell - - PS C:\Users\Someone> mfgtool-files-\uuu.exe -pp 1 mfgtool-files-\full_image.uuu - uuu (Universal Update Utility) for nxp imx chips -- libuuu_1.4.43-0-ga9c099a - - Success 1 Failure 0 - - - 1:31 3/ 3 [=================100%=================] SDPV: jump - 2:31 8/ 8 [Done ] FB: done - - #. Turn off the power - #. Put the board into run mode. diff --git a/source/user-guide/flashing/imx8-prepare.rst b/source/user-guide/flashing/imx8-prepare.rst deleted file mode 100644 index b1e3f4388..000000000 --- a/source/user-guide/flashing/imx8-prepare.rst +++ /dev/null @@ -1,43 +0,0 @@ -Preparation ------------ - -.. important:: - Ensure you replace the ```` placeholder below with the name of your Factory. - -#. Download necessary files from ``https://app.foundries.io/factories//targets`` - - a. Click the latest Target with the :guilabel:`platform` trigger. - - b. Expand the **run** in the :guilabel:`Runs` section which corresponds with the name of the board. - **Download the Factory image for that machine.** - For example:: - - lmp-factory-image-.wic.gz - u-boot-.itb - imx-boot- - -#. Extract the file ``lmp-factory-image-.wic.gz``:: - - gunzip lmp-factory-image-.wic.gz - -#. Expand the **run** in the :guilabel:`Runs` section which corresponds with the name of the board. - Download the **mfgtools** for that machine, e.g., ``mfgtool-files-.tar.gz``. - -#. Extract the file - - .. code-block:: console - - $ tar -zxvf mfgtool-files-.tar.gz - -#. Organize all the files, mirroring the tree below:: - - ├── lmp-factory-image-.wic.gz - ├── u-boot-.itb - ├── imx-boot- - └── mfgtool-files- -    ├── bootloader.uuu -    ├── full_image.uuu -    ├── SPL-mfgtool -    ├── u-boot-mfgtool.itb -    ├── uuu -    └── uuu.exe diff --git a/source/user-guide/flashing/imx8mm.rst b/source/user-guide/flashing/imx8mm.rst deleted file mode 100644 index 04edf768f..000000000 --- a/source/user-guide/flashing/imx8mm.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. _ref-rm_board_imx8mmevk: - -i.MX 8M Mini Evaluation Kit -=========================== - -.. |board_name| replace:: i.MX 8 M Mini EVK -.. |machine_name| replace:: imx8mm-lpddr4-evk -.. |debug_port| replace:: **J901** -.. |download_port| replace:: **J301** -.. |power_jack| replace:: **J302** -.. |power_switch| replace:: **SW101** -.. |boot_mode_switch| replace:: **SW1101** -.. |boot_mode_sdp| replace:: ON, OFF, ON, OFF -.. |boot_mode_emmc| replace:: OFF, ON, ON, OFF -.. |boot_mode_bits| replace:: **1-4** -.. |imx_n_consoles| replace:: Two -.. |imx_tty_device| replace:: ``ttyUSB1`` -.. |imx_tty_port| replace:: ``if01`` -.. |imx_usb_type_debug| replace:: micro-B -.. |imx_usb_type_sdp| replace:: USB-C -.. |imx_power_jack_type| replace:: USB-C - -.. |imx_lsusb| replace:: - - $ lsusb | grep NXP - Bus 001 Device 023: ID 1fc9:012b NXP Semiconductors i.MX 8M Dual/8M QuadLite/8M Quad Serial Downloader - -.. |image_board_top| image:: /_static/boards/imx8mmevk.png - :width: 600 - :align: middle - -.. |image_board_SW| image:: /_static/boards/imx8mmevk_SW.png - :width: 600 - :align: middle - -.. |imx_tty_list| replace:: - - $ ls -l /dev/serial/by-id/ - total 0 - lrwxrwxrwx 1 root root 13 Dec 18 11:09 usb-FTDI_Dual_RS232-if00-port0 -> ../../ttyUSB0 - lrwxrwxrwx 1 root root 13 Dec 18 11:09 usb-FTDI_Dual_RS232-if01-port0 -> ../../ttyUSB1 - - -.. |usb_device_windows| image:: /_static/boards/windows_verify.png - :width: 600 - :align: middle - -.. |imx_file_list| replace:: - - ├── lmp-factory-image-imx8mm-lpddr4-evk.wic.gz - ├── u-boot-imx8mm-lpddr4-evk.itb - ├── sit-imx8mm-lpddr4-evk.bin - ├── imx-boot-imx8mm-lpddr4-evk - └── mfgtool-files-imx8mm-lpddr4-evk - -.. |imx_mfgtool_file_list| replace:: - - ├── bootloader.uuu - ├── full_image.uuu - ├── imx-boot-mfgtool - ├── uuu - └── uuu.exe - -.. |secure_boot_preparation_note| replace:: - The instructions in this section also apply to those boards with secure boot enabled. - There are references on how to perform common instructions along with the flow. - :ref:`ref-security` details the required background for secure boot. - -.. |secure_boot_pre_flash_note| replace:: For instructions on how to sign the - required images before flashing them to the board with secure boot enabled, - see :ref:`ref-secure-machines`. - -.. include:: imx-common-board.inc diff --git a/source/user-guide/flashing/imx8mn.rst b/source/user-guide/flashing/imx8mn.rst deleted file mode 100644 index d4e62dcd2..000000000 --- a/source/user-guide/flashing/imx8mn.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. _ref-rm_board_imx8mn-ddr4-evk: - -i.MX 8M Nano Evaluation Kit -=========================== - -.. |board_name| replace:: i.MX 8M Nano EVK -.. |machine_name| replace:: imx8mn-ddr4-evk -.. |debug_port| replace:: **J901** -.. |download_port| replace:: **J301** -.. |power_jack| replace:: **J302** -.. |power_switch| replace:: **SW101** -.. |boot_mode_switch| replace:: **SW1101** -.. |boot_mode_sdp| replace:: ON, OFF, OFF, OFF -.. |boot_mode_emmc| replace:: OFF, ON, OFF, OFF -.. |boot_mode_bits| replace:: **1-4** -.. |imx_n_consoles| replace:: Two -.. |imx_tty_device| replace:: ``ttyUSB1`` -.. |imx_tty_port| replace:: ``if01`` -.. |imx_usb_type_debug| replace:: micro-B -.. |imx_usb_type_sdp| replace:: USB-C -.. |imx_power_jack_type| replace:: USB-C - -.. |imx_lsusb| replace:: - - $ lsusb | grep NXP - Bus 001 Device 023: ID 1fc9:012b NXP Semiconductors i.MX 8M Dual/8M QuadLite/8M Quad Serial Downloader - -.. |image_board_top| image:: /_static/boards/imx8mn-ddr4-evk.png - :width: 600 - :align: middle - -.. |image_board_SW| image:: /_static/boards/imx8mmevk_SW.png - :width: 600 - :align: middle - -.. |imx_tty_list| replace:: - - $ ls -l /dev/serial/by-id/ - total 0 - lrwxrwxrwx 1 root root 13 Dec 18 11:09 usb-FTDI_Dual_RS232-if00-port0 -> ../../ttyUSB0 - lrwxrwxrwx 1 root root 13 Dec 18 11:09 usb-FTDI_Dual_RS232-if01-port0 -> ../../ttyUSB1 - -.. |usb_device_windows| image:: /_static/boards/windows_verify.png - :width: 600 - :align: middle - -.. |imx_file_list| replace:: - - ├── lmp-factory-image-imx8mn-ddr4-evk.wic.gz - ├── u-boot-imx8mn-ddr4-evk.itb - ├── sit-imx8mn-ddr4-evk.bin - ├── imx-boot-imx8mn-ddr4-evk - └── mfgtool-files-imx8mn-ddr4-evk - -.. |imx_mfgtool_file_list| replace:: - - ├── bootloader.uuu - ├── full_image.uuu - ├── imx-boot-mfgtool - ├── uuu - └── uuu.exe - -.. |secure_boot_preparation_note| replace:: - The instructions in this section also apply to those boards with secure boot enabled. - There are references on how to perform common instructions along with the flow. - The :ref:`ref-security` section details the required background for secure boot. - -.. |secure_boot_pre_flash_note| replace:: - For instructions on how to sign the - required images before flashing them to the board with secure boot enabled, - see :ref:`ref-secure-machines`. - -.. include:: imx-common-board.inc diff --git a/source/user-guide/flashing/imx8mp.rst b/source/user-guide/flashing/imx8mp.rst deleted file mode 100644 index fec5f4588..000000000 --- a/source/user-guide/flashing/imx8mp.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. _ref-rm_board_imx8mp-lpddr4-evk: - -i.MX 8M Plus Evaluation Kit -=========================== - -.. |board_name| replace:: i.MX 8M Plus EVK -.. |machine_name| replace:: imx8mp-lpddr4-evk -.. |debug_port| replace:: **J23** -.. |download_port| replace:: **J6** -.. |power_jack| replace:: **J5** -.. |power_switch| replace:: **SW3** -.. |boot_mode_switch| replace:: **SW4** -.. |boot_mode_sdp| replace:: OFF, OFF, OFF, ON -.. |boot_mode_emmc| replace:: OFF, ON, OFF, OFF -.. |boot_mode_bits| replace:: **1-4** -.. |imx_n_consoles| replace:: Four -.. |imx_tty_device| replace:: ``ttyUSB2`` -.. |imx_tty_port| replace:: ``if02`` -.. |imx_usb_type_debug| replace:: micro-B -.. |imx_usb_type_sdp| replace:: USB-C -.. |imx_power_jack_type| replace:: USB-C - -.. |imx_lsusb| replace:: - - $ lsusb | grep NXP - Bus 001 Device 023: ID 1fc9:012b NXP Semiconductors i.MX 8M Dual/8M QuadLite/8M Quad Serial Downloader - -.. |image_board_top| image:: /_static/boards/imx8mp-lpddr4-evk.png - :width: 600 - :align: middle - -.. |image_board_SW| image:: /_static/boards/imx8mp-lpddr4-evk_SW.png - :width: 600 - :align: middle - -.. |imx_tty_list| replace:: - - $ ls -l /dev/serial/by-id/ - total 0 - lrwxrwxrwx 1 root root 13 jan 24 10:24 usb-FTDI_Quad_RS232-HS-if00-port0 -> ../../ttyUSB0 - lrwxrwxrwx 1 root root 13 jan 24 10:24 usb-FTDI_Quad_RS232-HS-if01-port0 -> ../../ttyUSB1 - lrwxrwxrwx 1 root root 13 jan 24 10:24 usb-FTDI_Quad_RS232-HS-if02-port0 -> ../../ttyUSB2 - lrwxrwxrwx 1 root root 13 jan 24 10:24 usb-FTDI_Quad_RS232-HS-if03-port0 -> ../../ttyUSB3 - -.. |usb_device_windows| image:: /_static/boards/windows_verify.png - :width: 600 - :align: middle - -.. |imx_file_list| replace:: - - ├── lmp-factory-image-imx8mp-lpddr4-evk.wic.gz - ├── u-boot-imx8mp-lpddr4-evk.itb - ├── sit-imx8mp-lpddr4-evk.bin - ├── imx-boot-imx8mp-lpddr4-evk - └── mfgtool-files-imx8mp-lpddr4-evk - -.. |imx_mfgtool_file_list| replace:: - - ├── bootloader.uuu - ├── full_image.uuu - ├── imx-boot-mfgtool - ├── uuu - └── uuu.exe - -.. |secure_boot_preparation_note| replace:: - The instructions in this section also applies to those boards with secure boot enabled. - There are references on how to perform common instructions along with the flow. - :ref:`ref-security` details the required background for secure boot. - -.. |secure_boot_pre_flash_note| replace:: For instructions on how to sign the - required images before flashing them to the board with secure boot enabled, - see :ref:`ref-secure-machines` - -.. include:: imx-common-board.inc diff --git a/source/user-guide/flashing/imx8mq.rst b/source/user-guide/flashing/imx8mq.rst deleted file mode 100644 index 8da2fed24..000000000 --- a/source/user-guide/flashing/imx8mq.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. _ref-rm_board_imx8mqevk: - -i.MX 8M Quad Evaluation Kit -=========================== - -.. |board_name| replace:: i.MX 8M Quad EVK -.. |machine_name| replace:: imx8mq-evk -.. |debug_port| replace:: **J1701** -.. |download_port| replace:: **J901** -.. |power_jack| replace:: **J902** -.. |power_switch| replace:: **SW701** -.. |boot_mode_switch| replace:: **SW802** -.. |boot_mode_sdp| replace:: OFF, ON -.. |boot_mode_emmc| replace:: ON, OFF -.. |boot_mode_bits| replace:: 1-2 -.. |imx_n_consoles| replace:: Two -.. |imx_tty_device| replace:: ``ttyUSB0`` -.. |imx_tty_port| replace:: ``if00`` -.. |imx_usb_type_debug| replace:: micro-B -.. |imx_usb_type_sdp| replace:: USB-C -.. |imx_power_jack_type| replace:: 12V - -.. |imx_lsusb| replace:: - - $ lsusb | grep NXP - Bus 001 Device 023: ID 1fc9:012b NXP Semiconductors i.MX 8M Dual/8M QuadLite/8M Quad Serial Downloader - -.. |image_board_top| image:: /_static/boards/imx8mqevk.png - :width: 600 - :align: middle - -.. |image_board_SW| image:: /_static/boards/imx8mqevk_SW2.png - :align: middle - -.. |imx_tty_list| replace:: - - $ ls -l /dev/serial/by-id/ - total 0 - lrwxrwxrwx 1 root root 13 Nov 16 23:45 usb-Silicon_Labs_CP2105_Dual_USB_to_UART_Bridge_Controller_007FC3F4-if00-port0 -> ../../ttyUSB0 - lrwxrwxrwx 1 root root 13 Nov 16 23:45 usb-Silicon_Labs_CP2105_Dual_USB_to_UART_Bridge_Controller_007FC3F4-if01-port0 -> ../../ttyUSB2 - -.. |usb_device_windows| image:: /_static/boards/windows_verify.png - :width: 600 - :align: middle - -.. |imx_file_list| replace:: - - ├── lmp-factory-image-imx8mq-evk.wic.gz - ├── u-boot-imx8mq-evk.itb - ├── sit-imx8mq-evk.bin - ├── imx-boot-imx8mq-evk or imx-boot-imx8mq-evk-nohdmi - └── mfgtool-files-imx8mq-evk - -.. |imx_mfgtool_file_list| replace:: - - ├── bootloader.uuu - ├── full_image.uuu - ├── imx-boot-mfgtool - ├── uuu - └── uuu.exe - -.. |secure_boot_preparation_note| replace:: - The instructions in this section also applies to those boards with secure boot enabled. - There are references on how to perform common instructions along with the flow. - :ref:`ref-security` details the required background for secure boot. - -.. |secure_boot_pre_flash_note| replace:: For instructions on how to sign the - required images before flashing them to the board with secure boot enabled, - see :ref:`ref-secure-machines` - -.. include:: imx-common-board.inc diff --git a/source/user-guide/flashing/imx8qm-mek.rst b/source/user-guide/flashing/imx8qm-mek.rst deleted file mode 100644 index c23001605..000000000 --- a/source/user-guide/flashing/imx8qm-mek.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. _ref-rm_boards_imx8qm-mek: - -NXP i.MX 8QuadMax Multisensory Enablement Kit (MEK) -=================================================== - -.. include:: imx8-prepare.rst - -Hardware Preparation --------------------- - -Set up the board for updating using the manufacturing tools: - -#. Connect the micro-B end of the supplied USB cable into Debug UART port **J18**. - Connect the other end of the cable to a host computer. - -#. Connect Type-C into USB Type-C port **J17**. - Connect the other end of the cable to a host computer. - -#. Use boot switch (**SW2**) to configure to boot from SDP (``[D1-D6]: 000100``). - - .. figure:: /_static/boards/imx8qm-mek-bootswitches.png - :width: 300 - :align: center - - Boot switches - -#. Power the board by flipping the switch (**SW1**). - -Flashing --------- - -Once in serial downloader mode and connected to your PC, the evaluation board should show up as a Freescale USB device. - -.. note:: Device names and IDs can slightly differ from the steps below. - -.. include:: imx6-flashing.rst - -Configure the boot switch (**SW2**) to boot from eMMC (``[D1-D6]: 001000``). -Power on the board to boot the new image. diff --git a/source/user-guide/flashing/imx9-flashing.rst b/source/user-guide/flashing/imx9-flashing.rst deleted file mode 100644 index 798f47dc9..000000000 --- a/source/user-guide/flashing/imx9-flashing.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. tab-set:: - :sync-group: os - - .. tab-item:: Linux - :sync: linux - - #. Verify target is present: - - .. code-block:: console - - $ lsusb | grep NXP - Bus 001 Device 018: ID 1fc9:014e NXP Semiconductors OO Blank 93 - - In this mode you will use the ``uuu`` tools to program the images to the eMMC. - The ``USB ID`` may differ if a different SoC is used. - - #. To program the LmP to the EMMC, run: - - .. code-block:: console - - $ sudo mfgtool-files-/uuu mfgtool-files-/full_image.uuu - uuu (Universal Update Utility) for nxp imx chips -- libuuu_1.4.243-0-ged48c51 - - Success 1 Failure 0 - - - 1:92 6/ 6 [Done ] FB: done - - #. Turn off the power - #. Put the board into run mode. - - .. tab-item:: Windows - :sync: windows - - #. Start the ``Device Manager`` - #. Select ``View`` - #. Select ``Devices by container`` - #. Verify a device like the following: - - .. figure:: /_static/boards/windows_verify.png - :width: 600 - :align: center - - #. To program the LmP to the EMMC, run: - - .. code-block:: powershell - - PS C:\Users\Someone> mfgtool-files-\uuu.exe mfgtool-files-\full_image.uuu - uuu (Universal Update Utility) for nxp imx chips -- libuuu_1.4.243-0-ged48c51 - - Success 1 Failure 0 - - - 1:92 6/ 6 [Done ] FB: done - - #. Turn off the power - #. Put the board into run mode. diff --git a/source/user-guide/flashing/imx93evk.rst b/source/user-guide/flashing/imx93evk.rst deleted file mode 100644 index 964fe0dce..000000000 --- a/source/user-guide/flashing/imx93evk.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. _ref-rm_board_imx93evk: - -i.MX 93 Evaluation Kit -====================== - -.. |board_name| replace:: i.MX 93 EVK -.. |machine_name| replace:: imx93-11x11-lpddr4x-evk -.. |debug_port| replace:: **J1401** -.. |download_port| replace:: **J401** -.. |power_jack| replace:: **J301** -.. |power_switch| replace:: **SW301** -.. |boot_mode_switch| replace:: **SW1301** -.. |boot_mode_sdp| replace:: OFF, OFF, ON, ON -.. |boot_mode_emmc| replace:: ON, ON, ON, ON -.. |boot_mode_bits| replace:: 1-4 -.. |imx_n_consoles| replace:: Four -.. |imx_tty_device| replace:: ``ttyUSB2`` -.. |imx_tty_port| replace:: ``if02`` -.. |imx_usb_type_debug| replace:: USB-C -.. |imx_usb_type_sdp| replace:: USB-C -.. |imx_power_jack_type| replace:: USB-C - -.. |imx_lsusb| replace:: - - $ lsusb | grep NXP - Bus 001 Device 018: ID 1fc9:014e NXP Semiconductors OO Blank 93 - -.. |image_board_top| image:: /_static/boards/imx93evk.png - :width: 600 - :align: middle - -.. |image_board_SW| image:: /_static/boards/imx93evk_SW.png - :width: 600 - :align: middle - -.. |imx_tty_list| replace:: - - ls -l /dev/serial/by-id/ - total 0 - lrwxrwxrwx 1 root root 13 abr 20 16:20 usb-FTDI_Quad_RS232-HS-if00-port0 -> ../../ttyUSB0 - lrwxrwxrwx 1 root root 13 abr 20 16:20 usb-FTDI_Quad_RS232-HS-if01-port0 -> ../../ttyUSB1 - lrwxrwxrwx 1 root root 13 abr 20 16:20 usb-FTDI_Quad_RS232-HS-if02-port0 -> ../../ttyUSB2 - lrwxrwxrwx 1 root root 13 abr 20 16:20 usb-FTDI_Quad_RS232-HS-if03-port0 -> ../../ttyUSB3 - -.. |usb_device_windows| image:: /_static/boards/windows_verify.png - :width: 600 - :align: middle - -.. |imx_file_list| replace:: - - ├── lmp-factory-image-imx93-11x11-lpddr4x-evk.wic.gz - ├── u-boot-imx93-11x11-lpddr4x-evk.itb - ├── imx-boot-imx93-11x11-lpddr4x-evk - └── mfgtool-files-imx93-11x11-lpddr4x-evk - -.. |imx_mfgtool_file_list| replace:: - - ├── bootloader.uuu - ├── full_image.uuu - ├── SPL-mfgtool - ├── u-boot-mfgtool.itb - ├── uuu - └── uuu.exe - -.. |secure_boot_preparation_note| replace:: The instructions in this section - show the preparation before the flashing procedure. - -.. |secure_boot_pre_flash_note| replace:: Follow the instructions below. - -.. include:: imx-common-board.inc diff --git a/source/user-guide/flashing/portenta-x8-prepare.rst b/source/user-guide/flashing/portenta-x8-prepare.rst deleted file mode 100644 index 874d3c072..000000000 --- a/source/user-guide/flashing/portenta-x8-prepare.rst +++ /dev/null @@ -1,46 +0,0 @@ -Preparation ------------ - -.. important:: - - Ensure you replace ```` With the name of your Factory. - -#. Download the necessary files from ``https://app.foundries.io/factories//targets`` - - a. Click the latest Target with the ``platform`` Trigger. - - b. Expand the :guilabel:`Runs` section which corresponds with the board. - **Download the Factory image for that machine**:: - - lmp-partner-arduino-image-.wic.gz - u-boot-.itb - sit-.bin - imx-boot- - -#. Extract ``lmp-partner-arduino-image-.wic.gz``: - - .. code-block:: console - - $ gunzip lmp-partner-arduino-image-.wic.gz - -#. Expand the :guilabel:`Runs` section which corresponds with the board. - **Download the corresponding mfgtool files**, e.g., ``mfgtool-files-.tar.gz``. - -#. Extract the files: - - .. code-block:: console - - $ tar -zxvf mfgtool-files-.tar.gz - -#. Organize the files, mirroring the tree below:: - - ├── lmp-partner-arduino-image-.wic - ├── u-boot-.itb - ├── sit-.bin - ├── imx-boot- - └── mfgtool-files- - ├── bootloader.uuu - ├── full_image.uuu - ├── imx-boot-mfgtool - ├── uuu - └── uuu.exe diff --git a/source/user-guide/flashing/portenta-x8.rst b/source/user-guide/flashing/portenta-x8.rst deleted file mode 100644 index d67e9b963..000000000 --- a/source/user-guide/flashing/portenta-x8.rst +++ /dev/null @@ -1,85 +0,0 @@ -.. _ref-rm_board_portenta-x8: - -Arduino Portenta X8 -=================== - -.. include:: secure-boot-note.rst - -.. include:: portenta-x8-prepare.rst - -Hardware Preparation --------------------- - -Set up the board for updating using the manufacturing tools: - -.. figure:: /_static/boards/portenta-x8.png - :width: 600 - :align: center - - portenta-x8 - -#. **OPTIONAL**: Only required if you have problems and/or want to see the boot console output. - - .. figure:: /_static/boards/portenta-x8-uart.png - :width: 600 - :align: center - - UART 2 Pins - -#. You may need to solder a six pin header to the **UART2** pad. - -#. Connect a TTL USB to UART 3v3 adapter to the corresponding UART 2 pins on the breakout board. - -#. Connect the other end of the cable to a PC acting as a host terminal. - -#. A UART connection will appear on the PC. - - On a Linux host for example: - - .. code-block:: console - - $ ls -l /dev/serial/by-id/ - total 0 - lrwxrwxrwx 1 root root 13 Dec 18 11:09 usb-FTDI_TTL_RS232-if00-port0 -> ../../ttyUSB0 - - Using a serial terminal program like minicom, connect to the port - with ``if00`` in the name (in this example ttyUSB0) and apply the - following configuration: - - - Baud rate: 115200 - - Data bits: 8 - - Stop bit: 1 - - Parity: None - - Flow control: None - - .. tip:: - If you are not receiving console output to swap the TX and RX pins. Most TTL - USB to UART adaptors do not provide the cross over function. - -#. Ensure that the power is off—no power input connected. - -#. Put the Portenta x8 into programming mode: - - Switch **BT_SEL** to **ON** and switch **BOOT** to **ON** as shown below. - - .. figure:: /_static/boards/portenta-x8-boot.png - :width: 600 - :align: center - - BT_SEL and BOOT programming settings - -#. Connect your computer to the Portenta X8 board via either USB-C® to USB-A or USB-C® to USB-C®. - This connection will power your board ON. It is best to use 5V supply with at least 2A via - a USB-C® connector. Negotiating power supplies do not always work and frequent reboots - can be detected. - -Flashing --------- - -Once in serial downloader mode and connected to your PC the evaluation board should show up as an NXP® USB device. - -.. include:: secure-boot-pre-flash-note.rst - -.. include:: imx8-flashing.rst - -To put the Portenta X8 into run mode, switch **BT_SEL** and **BOOT** to **OFF**. diff --git a/source/user-guide/flashing/se050_imx6ull.rst b/source/user-guide/flashing/se050_imx6ull.rst deleted file mode 100644 index 2ccd8129d..000000000 --- a/source/user-guide/flashing/se050_imx6ull.rst +++ /dev/null @@ -1,67 +0,0 @@ -i.MX 6ULL Evaluation kit With SE050ARD -======================================= - -This page walks through installing a FoundriesFactory™ Platform image with SE050 hardware enabled onto the NXP® ``imx6ullevk``, -connected to the NXP OM-SE050ARD development platform. - -.. note:: - An image created in a Factory with SE050 enabled will not boot on boards without the SE050 properly attached. - -Attaching the SE050 -------------------- - -Using four male to male jumper wires (Arduino Compatible Pin size), connect the two boards as shown: - -.. figure:: /_static/boards/imx6ullevk.png - :width: 400 - :align: center - - imx6ullevk - -.. figure:: /_static/boards/se050ard.png - :width: 400 - :align: center - - SE050ARD - -Connect the signals as follows: - -+----------+--------------+-------------+ -| Signal | imx6ullevk | OM-SE050ARD | -+==========+==============+=============+ -| SCL | J1704 pin 10 | J2 pin 10 | -+----------+--------------+-------------+ -| SDA | J1704 pin 9 | J2 pin 9 | -+----------+--------------+-------------+ -| VDD_3V3 | J1705 pin 4 | J8 pin 4 | -+----------+--------------+-------------+ -| GND | J1704 pin 7 | J2 pin 7 | -+----------+--------------+-------------+ - -.. note:: - The ``J1704`` and ``J1705`` headers are located in the center of the imx6ullevk board (Arduino headers). - -Be sure that the jumpers on the SE050 evaluation board are set as shown: - -.. figure:: /_static/boards/se050ard_jumpers.png - :width: 400 - :align: center - - SE050 Jumper Settings - -The connected boards should look like this: - -.. figure:: /_static/boards/se050ard_imx6ull.jpg - :width: 400 - :align: center - - Wire Connections Between Boards - -Installing the FoundriesFactory Image -------------------------------------- - -Download the images that have the SE050 enabled from the Factory. -Follow the instructions in :ref:`ref-rm_board_imx6ullevk`. - -.. note:: - A reference on the needed changes to enable the SE050 middleware can be found in :ref:`ref-security_se05x_enablement`. diff --git a/source/user-guide/flashing/se050_imx8mm.rst b/source/user-guide/flashing/se050_imx8mm.rst deleted file mode 100644 index 641975875..000000000 --- a/source/user-guide/flashing/se050_imx8mm.rst +++ /dev/null @@ -1,85 +0,0 @@ -i.MX 8M Mini/Nano Evaluation Kit with SE050ARD -============================================== - -This page walks through installing a SE050 hardware enabled FoundriesFactory™ Platform image onto an NXP® ``imx8mm-lpddr4-evk`` or ``imx8mn-ddr4-evk``, -connected to the NXP OM-SE050ARD development platform. - -.. note:: - An image created in a Factory with the SE050 enabled will not boot on boards without the SE050 properly attached. - -Attaching the SE050 -------------------- - -Using four male to male jumper wires (Arduino Compatible Pin size), connect the two boards as shown: - -.. figure:: /_static/boards/imx8mmevk_J1004.png - :width: 400 - :align: center - - 8MMINI-BB - -.. figure:: /_static/boards/imx8mmevk_J1004_pinout.png - :width: 400 - :align: center - - 8MMINI-BB I2C pinout - -.. figure:: /_static/boards/se050ard.png - :width: 400 - :align: center - - SE050ARD - -Connect the signals as follows: - -+----------+--------------+-------------+ -| Signal | 8MMINI-BB | OM-SE050ARD | -+==========+==============+=============+ -| SCL | J1004 pin 3 | J2 pin 10 | -+----------+--------------+-------------+ -| SDA | J1004 pin 5 | J2 pin 9 | -+----------+--------------+-------------+ -| VDD_3V3 | J1004 pin 1 | J8 pin 4 | -+----------+--------------+-------------+ -| GND | J1004 pin 7 | J2 pin 7 | -+----------+--------------+-------------+ - -Alternatively, use J22 on OM-SE050ARD: - -+---------+-------------+-------------+ -| Signal | 8MMINI-BB | OM-SE050ARD | -+=========+=============+=============+ -| SCL | J1004 pin 3 | J22 pin 4 | -+---------+-------------+-------------+ -| SDA | J1004 pin 5 | J22 pin 1 | -+---------+-------------+-------------+ -| VDD_3V3 | J1004 pin 1 | J22 pin 2 | -+---------+-------------+-------------+ -| GND | J1004 pin 7 | J22 pin 3 | -+---------+-------------+-------------+ - -Be sure that the jumpers on the SE050 evaluation board are set as shown: - -.. figure:: /_static/boards/se050ard_jumpers.png - :width: 400 - :align: center - - SE050 Jumper Settings - -The connected boards should look like this: - -.. figure:: /_static/boards/se050ard_imx8mm.png - :width: 400 - :align: center - - Wire Connections Between Boards - -Installing the FoundriesFactory Image -------------------------------------- - -Download the images that have the SE050 enabled from the Factory. -Follow the instructions in :ref:`ref-rm_board_imx8mmevk` or :ref:`ref-rm_board_imx8mn-ddr4-evk` -—depending on the hardware used. - -.. note:: - A reference on the needed changes to enable the SE050 middleware can be found in :ref:`ref-security_se05x_enablement`. diff --git a/source/user-guide/flashing/se050_imx8mp.rst b/source/user-guide/flashing/se050_imx8mp.rst deleted file mode 100644 index e58688e0a..000000000 --- a/source/user-guide/flashing/se050_imx8mp.rst +++ /dev/null @@ -1,70 +0,0 @@ -i.MX 8M Plus Evaluation Kit With SE050ARD -========================================= - -This document walks through the steps of installing a FoundriesFactory™ Platform image with SE050 hardware enabled onto the NXP® ``imx8mp-lpddr4-evk``, -connected to the NXP OM-SE050ARD development platform. - -.. note:: - An image created in a Factory with SE050 enabled does not boot on boards without the SE050 properly attached. - -Attaching the SE050 -------------------- - -Using four male to male jumper wires (Arduino Compatible Pin size) connect the two boards as shown: - -.. figure:: /_static/boards/imx8mp-lpddr4-evk_J22.png - :width: 400 - :align: center - - imx8mp-lpddr4-evk - -.. figure:: /_static/boards/imx8mp-lpddr4-evk_J22_pinout.png - :width: 400 - :align: center - - imx8mp-lpddr4-evk i2c pinout - -.. figure:: /_static/boards/se050ard.png - :width: 400 - :align: center - - SE050ARD - -Connect the signals as follows: - -+----------+----------------------+-------------+ -| Signal | imx8mp-lpddr4-evk | OM-SE050ARD | -+==========+======================+=============+ -| SCL | J22 pin 3 | J2 pin 10 | -+----------+----------------------+-------------+ -| SDA | J22 pin 5 | J2 pin 9 | -+----------+----------------------+-------------+ -| VDD_3V3 | J22 pin 1 | J8 pin 4 | -+----------+----------------------+-------------+ -| GND | J22 pin 7 | J2 pin 7 | -+----------+----------------------+-------------+ - -Be sure that the jumpers on the SE050 evaluation board are set as shown: - -.. figure:: /_static/boards/se050ard_jumpers.png - :width: 400 - :align: center - - SE050 Jumper Settings - -The connected boards should look like this: - -.. figure:: /_static/boards/se050ard_imx8mp.jpg - :width: 400 - :align: center - - Wire Connections Between Boards - -Installing the FoundriesFactory Image -------------------------------------- - -Download the images that have the SE050 enabled from the Factory. -Follow the instructions in :ref:`ref-rm_board_imx8mp-lpddr4-evk`. - -.. note:: - A reference on the needed changes to enable the SE050 middleware can be found in :ref:`ref-security_se05x_enablement`. diff --git a/source/user-guide/flashing/se050_imx8mq.rst b/source/user-guide/flashing/se050_imx8mq.rst deleted file mode 100644 index 008b5c742..000000000 --- a/source/user-guide/flashing/se050_imx8mq.rst +++ /dev/null @@ -1,70 +0,0 @@ -i.MX 8M Quad Evaluation Kit with SE050ARD -========================================= - -This page walks through walk installing a FoundriesFactory™ Platform image with SE050 hardware enabled onto the NXP® ``imx8mqevk``, -connected to the NXP OM-SE050ARD development platform. - -.. note:: - An image created in the Factory with SE050 enabled will not boot on boards without the SE050 properly attached. - -Attaching the SE050 -------------------- - -Using four male to male jumper wires (Arduino Compatible Pin size) connect the two boards as shown: - -.. figure:: /_static/boards/imx8mqevk_J801.png - :width: 400 - :align: center - - imx8mqevk - -.. figure:: /_static/boards/imx8mqevk_J801_pinout.png - :width: 400 - :align: center - - imx8mqevk i2c pinout - -.. figure:: /_static/boards/se050ard.png - :width: 400 - :align: center - - SE050ARD - -Connect the signals as follows: - -+----------+-------------+-------------+ -| Signal | imx8mqevk | OM-SE050ARD | -+==========+=============+=============+ -| SCL | J801 pin 1 | J2 pin 10 | -+----------+-------------+-------------+ -| SDA | J801 pin 3 | J2 pin 9 | -+----------+-------------+-------------+ -| VDD_3V3 | J801 pin 5 | J8 pin 4 | -+----------+-------------+-------------+ -| GND | J801 pin 2 | J2 pin 7 | -+----------+-------------+-------------+ - -Be sure that the jumpers on the SE050 evaluation board are set as shown: - -.. figure:: /_static/boards/se050ard_jumpers.png - :width: 400 - :align: center - - SE050 Jumper Settings - -The connected boards should look like this: - -.. figure:: /_static/boards/se050ard_imx8mq.png - :width: 400 - :align: center - - Wire Connections Between Boards - -Installing the FoundriesFactory Image -------------------------------------- - -Download the images that have the SE050 enabled from the Factory. -Following the instructions in :ref:`ref-rm_board_imx8mqevk`. - -.. note:: - A reference on the needed changes to enable the SE050 middleware can be found in :ref:`ref-security_se05x_enablement`. diff --git a/source/user-guide/index.rst b/source/user-guide/index.rst index 66c66a4e5..25c55eeac 100644 --- a/source/user-guide/index.rst +++ b/source/user-guide/index.rst @@ -34,7 +34,6 @@ For in depth details and specific use cases, see the :ref:`Reference Manual = "i2c-dev" -.. note:: - To autoload an out of tree kernel module, please refer to :ref:`ref-pg-new-driver`. - .. _ref-troubleshooting_systemd-service: Adding a new Systemd Startup Service