Cleanup porting guide

Applied style guidelines where possible. Moved the introduction page to
the index/ToC page, so as to provide an overview for the section up
front.

Checked rendered output in browser, focusing on visual elements. No
issues spotted.

This commit addresses FFTK-2995

Signed-off-by: Katrina Prosise <[email protected]>

source/porting-guide/pg-distro-lmp-base.rst

@@ -1,19 +1,17 @@
 .. _ref-pg-lmp-base:
 
-DISTRO lmp-base for easy Kernel Image access
---------------------------------------------
+``DISTRO lmp-base`` for Easy Kernel Image Access
+---------------------------------------------------
 
-The default distro used by a FoundriesFactory is ``lmp``, designed to
-provide a secure and updatable environment needed during 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``, which 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 rootfs. See detailed
-information on how lmp and lmp-base differ :ref:`ref-linux-distro`.
+The default 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 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) show
-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.
+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.

source/porting-guide/pg-how-to-plan.rst

@@ -1,14 +1,13 @@
-How to plan the porting
+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.
+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, make sure to enable additional
-features, including the firmware not critical for boot, such as
-Bluetooth or Wi-Fi firmware. Next, port any applications, and
-continue development as needed.
+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:
 
@@ -19,10 +18,8 @@ In short, the recommended order is:
 
 .. note::
 
-   It is recommended to use ``DISTRO=lmp-base`` during the porting task.
+   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, but it is important to understand and cover them during the
-port.
+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.

source/porting-guide/pg-lmp-factory-custom.rst

@@ -1,13 +1,11 @@
 .. _ref-pg-lmp-factory-custom:
 
-Lmp-factory-custom
-^^^^^^^^^^^^^^^^^^
+``lmp-factory-custom``
+^^^^^^^^^^^^^^^^^^^^^^
 
-A FoundriesFactory includes a file
-(``conf/machine/include/lmp-factory-custom.inc``) which 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.
+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.
+This applies to cases when the porting does not create a new machine configuration file,
+and only overrides the definition from an existing machine.

source/porting-guide/pg-machine-conf.rst

@@ -1,10 +1,9 @@
 .. _ref-pg-machine-conf:
 
-Machine configuration file
+Machine Configuration File
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The machine configuration file is where the hardware is described in
-terms of variables such as:
+The machine configuration file describes hardware in terms of variables such as:
 
 .. Glossary::
 
@@ -28,9 +27,7 @@ terms of variables such as:
      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.
+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.
+In this case, any machine related configuration should be placed in the new machine configuration file.

source/porting-guide/pg-new-machine.rst

@@ -1,27 +1,24 @@
 .. _ref-pg-description:
 
-What is needed before porting the board to the LmP
-==================================================
+Requirements Before Porting to the LmP
+======================================
 
-It is out of the scope of this guide to detail the steps of creating a
-BSP including the bootloader or the operating system support and other
-critical packages - the recommendation is to search for the SoC vendor
-porting guide which usually details how to port the default BSP to
-another board.
+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 have those
-packages as a base for creating the new needed BSP which leads to the
-creation of append files for the recipes of those packages.
+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:
+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
+   Different boot flow being executed by machines supported by LmP

source/porting-guide/pg-reference.rst

@@ -1,25 +1,19 @@
 .. _ref-pg-reference-board:
 
-Finding a similar reference board already supported
----------------------------------------------------
+Finding a Similar Supported Reference Board
+-------------------------------------------
 
-For some projects, it is easy to understand which reference board is
-closest to the one being included. It is common that in early stages,
-the project starts using a reference board, and 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.
+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.
 
-In the other case when it is not an obvious answer, the task of
-searching for the closest reference board is looking for what
-reference board shares the same SoC which is usually described in the
-machine configuration file by the tag ``@SOC``.
+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``.
 
-If searching for ``@SOC`` through the meta-layers brings more than one
-machine with the same SoC used on the project, the suggestion here is to
-prefer the machine from the SoC vendor.
+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.
+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 EVK is
-used as a reference board.
+In this document, there are several examples where i.MX8M Mini EVK is used as a reference board.

source/porting-guide/pg-spl-kernel.rst

@@ -3,15 +3,14 @@
 Kernel and Device Tree
 ======================
 
-The LmP goal 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. Supported kernel trees can be found `here <https://github.com/foundriesio/meta-lmp/tree/main/meta-lmp-bsp/recipes-kernel/linux>`_.
+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 <https://github.com/foundriesio/meta-lmp/tree/main/meta-lmp-bsp/recipes-kernel/linux>`_.
 
 Unlike U-Boot, not all patches need to be appended to the kernel recipe.
-The user needs 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 so the build generates the output ``.dtb`` file.
+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.
 
 .. prompt:: text
 
@@ -20,32 +19,26 @@ meta-subscriber-overrides so the build generates the output ``.dtb`` file.
     │   └── <board>.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, so LmP relies on ``lmp-device-tree`` which is based on the Yocto Project
-device-tree class.
+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 on ``linux-yocto``. This is
-different from the also common “in-tree” configuration, which uses the
-file ``defconfig`` to configure the kernel.
+
+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``
-repository which have a helpful ``README`` file, and is also described in
-the :ref:`ref-linux-fragments`.
+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.
+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:
+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:
 
 .. prompt:: text
 
@@ -60,16 +53,16 @@ the target machine. The set of files should look like the following:
     │               └── <machine>-standard.scc
     └── linux-<name>_%.bbappend
 
-Where ``<name>`` 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 and ``<machine>`` is the machine name.
-The ``<sub-group>`` is a BSP subgroup, following the lmp-kernel-cache
-directory organization. For example, ``imx`` or ``raspberrypi``, depending on
+Where ``<name>`` 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. 
+``<machine>`` is the machine name.
+
+The ``<sub-group>`` 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
-``<machine>-standard.scc`` file, with features and configurations being
-organized between the other files.
+It is common that the BSP fragment is defined in a ``<machine>-standard.scc`` file,
+with features and configurations being organized between the other files.
 
 The ``linux-<name>_%.bbappend`` looks like:
 
@@ -82,10 +75,8 @@ The ``linux-<name>_%.bbappend`` looks like:
        file://kernel-meta/bsp/<sub-group>/<machine>-standard.scc \
     “
 
-Start from the BSP kernel fragment from a close reference board, copy
-over those files relevant to the reference board, change the file name,
-and review the content configurations while reviewing the schematics or
-a list of needed configurations.
+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:
 
@@ -95,9 +86,7 @@ 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 new driver or module to the Linux kernel source
-code is by creating a recipe file for this module under
-``recipes-kernel/kernel-modules/``:
+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/``:
 
 .. prompt:: text
 
@@ -131,6 +120,5 @@ Where ``<module>_<pv>.bb`` is:
 
     KERNEL_MODULE_AUTOLOAD:append = "<module>"
 
-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``).
+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``).