Cleanup board flashing pages

Style and grammar fixes across a number of pages. Markup had semantic newlines applied. Removed images already covered in the getting started page, such as the screenshots of the UI—this will make maintaining easier. Switches/pins/hardware components are now in bold rather than inline or plain. Ran vale linter within editor. Checked output in browser, which initially lead to a number of revisions. At this point all looks without issue, however there is a lot of content to go over multiple times. This commit addresses to FFTK-2788 Signed-off-by: Katrina Prosise <[email protected]>
foundriesio · Nov 9, 2023 · 2fd9fbb · 2fd9fbb
1 parent b26edc1
commit 2fd9fbb
Show file tree

Hide file tree

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

diff --git a/source/reference-manual/boards/am62xx-sk.rst b/source/reference-manual/boards/am62xx-sk.rst
@@ -8,60 +8,35 @@ Texas Instruments AM62x SKEVM
 Hardware Preparation
 --------------------
 
-Set up the board for booting from USB DFU mode:
+Set up the board for booting from MMC1-SDCard:
 
-#. Ensure that the power is off (remove cable from J11)
+#. Ensure that the power is off (remove cable from **J11**):
 
 .. figure:: /_static/boards/am62xx-sk-top.png
      :width: 600
      :align: center
 
      AM62xx-sk top view
 
-2. Put the am62xx-sk into boot from USB DFU Mode,
-   changing boot switches to: ``00000000 11001010``
+#. Put the am62xx-sk into boot from SDCard Mode:
+
+.. figure:: /_static/boards/am62xx-sk-switches.png
+     :width: 300
+     :align: center
+
+     Switch settings
+
 
 Flashing
 --------
 
-#. Power on the board and flash the board using ``flash.sh`` script from
-   ``ti-mfgtool-files-am62xx-evm`` directory, it copies the
-   ``lmp-factory-image-am62xx-evm.wic`` image.
-   The wic image contains the :term:`system image` that the device will boot.
-
-.. prompt:: bash host:~$, auto
-
-    host:~$ sudo ./ti-mfgtool-files-am62xx-evm/flash.sh --wic lmp-factory-image-am62xx-evm.wic
-     Load U-Boot via DFU...
-     ------------------------------------------
-     DFU BOOT TIBOOT3: TIFS and R5
-     ------------------------------------------
-     ------------------------------------------
-     DFU BOOT TISPL: TFA/OPTEE/ and A53 SPL
-     ------------------------------------------
-     ------------------------------------------
-     DFU BOOT UBOOT: A53 UBOOT
-     ------------------------------------------
-     ------------------------------------------
-     Exposing eMMC via USB using UMS
-     ------------------------------------------
-     Detected device: /dev/sda
-     Confirm flashing lmp-factory-image-am62xx-evm.wic to /dev/sda (y/N) >y
-     ------------------------------------------
-     Flashing /dev/sda via UMS
-     ------------------------------------------
-     844103680 bytes (844 MB, 805 MiB) copied, 57 s, 14,8 MB/s
-     814+1 records in
-     814+1 records out
-     854511616 bytes (855 MB, 815 MiB) copied, 57,7472 s, 14,8 MB/s
-     Flashing is finished
-
-2. Power off the board.
-
-Configure eMMC UDA Boot
------------------------
-
-#. Put the am62xx-sk into boot from eMMC UDA mode,
-   changing boot switches to: ``00000000 11000010``.
-
-#. Power on a board.
+Flash ``lmp-factory-image-am62xx-evm.wic.gz`` to an SD Card.
+This contains the bootable :term:`system image`.
+
+.. include:: generic-flashing.rst
+
+.. figure:: /_static/boards/am62xx-sk-bottom.png
+     :width: 600
+     :align: center
+
+     SDCard location
diff --git a/source/reference-manual/boards/am64xx-sk-prepare.rst b/source/reference-manual/boards/am64xx-sk-prepare.rst
@@ -1,46 +1,31 @@
 Building
 --------
 
-When building the Cortex R5 u-boot, it builds for all different variants:
+When building the Cortex R5 U-Boot, all variants are built:
 
-* ``hs-fs`` (High Security/Field Securable) also known as `SK-AM64B`_: This is a SoC/board state before a customer has blown the keys in the device. i.e. the state at which HS device leaves TI factory. In this state, the device protects the ROM code, TI keys and certain security peripherals. In this state, device do not force authentication for booting, however DMSC is locked.
+* ``hs-fs`` (High Security/Field Securable), also known as `SK-AM64B`_: This is a SoC/board state before a customer has blown the keys in the device,
+  i.e., the state at which the HS device leaves TI factory.
+  The device protects the ROM code, TI keys and certain security peripherals.
+  In this state, devices do not force authentication for booting, however DMSC is locked.
 
-* ``hs`` (High Security/Security Enforced) also known as `SK-AM64B`_: This is a SoC/board state after a customer has successfully blown the keys and set “customer keys enable”. In HS-SE device all security features are enabled. All secrets within the device are fully protected and all of the security goals are fully enforced. The device also enforces secure booting.
+* ``hs`` (High Security/Security Enforced), also known as `SK-AM64B`_: This is a SoC/board state after successfully blowning the keys and set “customer keys enable”.
+  In HS-SE device all security features are enabled.
+  All secrets within the device are fully protected and all of the security goals are fully enforced.
+  The device also enforces secure booting.
 
-* ``gp`` (General Purpose) variant also known as `SK-AM64`_: This is a SoC/board state where there is no device protection and authentication is not enabled for booting the device.
+* ``gp`` (General Purpose), also known as `SK-AM64`_: This is a SoC/board state with no device protection and authentication is not enabled for booting the device.
 
-The default variant is the ``hs-fs``. To boot an image on the others variants without pre-flash files manipulations
-on the target file-system we need to change the ``SYSFW_SUFFIX`` variable.
-The following changes the default to ``gp`` so the image produced boots on that variant:
+The default variant is  ``hs-fs``.
+To boot an image on other variants without pre-flash files manipulations on the target file-system, we need to change the ``SYSFW_SUFFIX`` variable.
+The following changes the default to ``gp``, so that the image produced boots that variant:
 
 .. code-block:: shell
 
    echo 'SYSFW_SUFFIX:am64xx-evm-k3r5 = "gp"' >> meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc
 
-Preparation
------------
+.. include:: generic-prepare.rst
 
-Ensure you replace the ``<factory>`` placeholder below with the name of your
-Factory.
-
-Download necessary files from ``https://app.foundries.io/factories/<factory>/targets``
-
-#. Click the latest Target with the :guilabel:`platform-devel` trigger.
-
-   .. figure:: /_static/boards/generic-steps-1.png
-      :align: center
-      :width: 300
-
-#. Expand the **run** in the :guilabel:`Runs` section (by clicking on the ``+`` sign) which corresponds
-   with the name of the board and **download the Factory image for that
-   machine.**
-
-   | E.g: ``lmp-factory-image-am64xx-evm.wic.gz``
-   
-   .. figure:: /_static/boards/am64xx-sk-steps-2.png
-      :align: center
-      :width: 600
-#. Extract the file ``lmp-factory-image-am64xx-evm.wic.gz``::
+#. Extract the file::
 
       gunzip lmp-factory-image-am64xx-evm.wic.gz
 

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

diff --git a/source/reference-manual/boards/apalis-imx6-prepare.rst b/source/reference-manual/boards/apalis-imx6-prepare.rst
@@ -1,46 +1,38 @@
 Preparation
 -----------
 
-Ensure you replace the ``<factory>`` placeholder below with the name of your
-Factory.
+.. important:: 
+   Ensure you replace the ``<factory>`` placeholder below with the name of your Factory.
 
-#. Download necessary files from ``https://app.foundries.io/factories/<factory>/targets``
+#. Download necessary files from ``https://app.foundries.io/factories/<factory>/targets``:
 
-     a. Click the latest :guilabel:`Target` with the ``platform-devel`` :guilabel:`Trigger`.
+   a. Click the latest Target with a ``platform`` trigger.
 
-          .. figure:: /_static/boards/generic-steps-1.png
-            :width: 769
-            :align: center
+   b. Expand **run** in the :guilabel:`Runs` section corresponding with the name of the board.
+   **Download the Factory image for that machine.**
 
-     #. Expand the **run** in the :guilabel:`Runs` section which corresponds
-        with the name of the board and **download the Factory image for that
-        machine.**
+   For example::
 
-        | E.g: 
-        |     ``lmp-factory-image-<machine-name>.wic.gz``
-        |     ``u-boot-<machine-name>.itb``
-        |     ``sit-<machine-name>.bin``
-        |     ``SPL-<machine-name>``
-
-          .. figure:: /_static/boards/apalis-imx6-steps-2.png
-            :width: 769
-            :align: center
+        lmp-factory-image-<machine-name>.wic.gz
+        u-boot-<machine-name>.itb
+        sit-<machine-name>.bin
+        SPL-<machine-name>
 
 #. 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 name of the board mfgtool-files and **download the tools for that
-   machine.**
+#. Expand the **run** in the :guilabel:`Runs` section which corresponds with the board's mfgtool-files.
+   **Download the tools for that machine.**
+
 
-   E.g: ``mfgtool-files-<machine-name>.tar.gz``
+#. Extract ``mfgtool-files-apalis-imx6.tar.gz``:
 
-#. Download and extract the file ``mfgtool-files-apalis-imx6.tar.gz``::
+   .. prompt::
 
-      tar -zxvf mfgtool-files-apalis-imx6.tar.gz
+         tar -zxvf mfgtool-files-apalis-imx6.tar.gz
 
-#. Organize all the files like the tree below::
+#. Organize the files as in the tree below::
 
       ├── lmp-factory-image-<machine-name>.wic.gz
       ├── u-boot-<machine-name>.itb

diff --git a/source/reference-manual/boards/apalis-imx6.rst b/source/reference-manual/boards/apalis-imx6.rst
@@ -12,16 +12,14 @@ Apalis iMX6 with the Ixora Carrier Board
 Flashing
 --------
 
-Once in serial downloader mode and connected to your PC, the evaluation board
-should show up as a Freescale USB device.
+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 go back to run mode, disconnect the jumper from the recovery pads (JP4) and
-reconnect the JP2 jumper.
+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/reference-manual/boards/apalis-imx8.rst b/source/reference-manual/boards/apalis-imx8.rst
@@ -10,14 +10,12 @@ Apalis iMX8 with the Ixora Carrier Board
 Flashing
 --------
 
-Once in serial downloader mode and connected to your PC, the evaluation board
-should show up as a Freescale USB device.
+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
+.. include:: imx8-flashing.rst
 
-To go back to run mode, disconnect the jumper from the recovery pads (JP4) and
-reconnect the JP2 jumper.
+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.