bsp: Introduce bsp manual for i.MX 93 (#156)

This PR introduces the BSP manual for the i.MX 93.

That is accomplished with the two steps below:

**Step 1:**
Copy files from `bsp/imx8/` and `bsp/imx8/imx8mp/` as templates to a new
folder `bsp/imx93/`, and adapt them for purpose of i.MX 93. Whenever
justifiable from "i.MX 93" work-scope, apply adaptions in a general
manner (e.g. with reST substitutions), to encourage re-use across
various i.MX platforms.

**Step 2:**
Move files that could be used across various i.MX platforms from
`bsp/imx93/` to a new folder `bsp/imx-common`, and potentially apply
further generalization.

--

After that PR was merged i.MX 8 platform can also make use of the
"imx-common" files, can add further generalization as needed, and can
drop their local duplicates from `imx8/*` folders.

---------

Signed-off-by: Christoph Stoidner <c.stoidner@phytec.de>
Co-authored-by: Christoph Stoidner <c.stoidner@phytec.de>

.codespellignore

@@ -1,3 +1,4 @@
 som
 synopsys
 msdos
+nd

source/bsp/building-bsp.rsti

@@ -1,8 +1,8 @@
 Building the BSP
 ================
 
-This section will guide you through the general build process of the i.MX 8M
-Plus BSP using Yocto and the phyLinux script. For more information about our
+This section will guide you through the general build process of the |soc| BSP
+using Yocto and the phyLinux script. For more information about our
 meta-layer or Yocto in general visit: |yocto-ref-manual|_.
 
 Basic Set-Up
@@ -16,8 +16,9 @@ Get the BSP
 -----------
 
 There are two ways to get the BSP sources. You can download the complete BSP
-sources from our download page: |yocto-bsp-name|_; or you can build it yourself
-with Yocto. This is particularly useful if you want to make customizations.
+sources from our download page: |yocto-bsp-name|_; or you can fetch and build it
+yourself with Yocto. This is particularly useful if you want to make
+customizations.
 
 The phyLinux script is a basic management tool for PHYTEC Yocto BSP releases
 written in Python. It is mainly a helper to get started with the BSP structure.
@@ -67,7 +68,8 @@ written in Python. It is mainly a helper to get started with the BSP structure.
       host:~/yocto$ DISTRO=|yocto-distro| MACHINE=|yocto-machinename| ./phyLinux init -p |kernel-socname| -r |yocto-manifestname|
 
 After the execution of the init command, phyLinux will print a few important
-notes as well as information for the next steps in the build process.
+notes. For example, it will print your git identify, SOC and BSP release which
+was selected as well as information for the next steps in the build process.
 
 Starting the Build Process
 ..........................
@@ -84,7 +86,7 @@ Starting the Build Process
 
 *  The current working directory of the shell should change to build/.
 *  Open the main configuration file and accept the GPU and VPU binary license
-   agreements. You have to uncomment the corresponding line.
+   agreements. Do this by uncommenting the corresponding line, as below.
 
    .. code-block:: console
 
@@ -101,11 +103,17 @@ Starting the Build Process
       host:~/yocto/build$ bitbake |yocto-imagename|
 
    .. note::
+      For the first build we suggest starting with our smaller non-graphical
+      image phytec-headless-image to see if everything is working correctly.
 
-      We suggest starting with our smaller non-graphical
-      image phytec-headless-image to see if everything is working correctly. The
-      first compile process takes about 40 minutes on a modern Intel Core i7. All
-      subsequent builds will use the filled caches and should take about 3 minutes.
+      .. code-block:: console
+         :substitutions:
+
+         host:~/yocto/build$ bitbake phytec-headless-image
+
+      The first compile process takes about 40 minutes on a modern Intel
+      Core i7. All subsequent builds will use the filled caches and should take
+      about 3 minutes.
 
 BSP Images
 ..........

source/bsp/getting-started.rsti

@@ -20,7 +20,7 @@ Get the Image
 -------------
 
 The image contains all necessary files and makes sure partitions and any raw
-data are correctly writing. Both the partup package and the WIC image, which can
+data are correctly written. Both the partup package and the WIC image, which can
 be flashed using ``dd``, can be downloaded from the `PHYTEC download server
 <dl-server_>`_.
 
@@ -41,19 +41,19 @@ Write the Image to SD Card
 --------------------------
 
 .. warning::
-   To create your bootable SD card, you must have root privileges. Be very
-   careful when specifying the destination device! All files on the selected
-   device will be erased immediately without any further query!
+   To create your bootable SD card, you must have root privileges on your Linux
+   host PC. Be very careful when specifying the destination device! All files
+   on the selected device will be erased immediately without any further query!
 
    Selecting the wrong device may result in **data loss** and e.g. could erase
-   your currently running system!
+   your currently running system on your host PC!
 
 Finding the Correct Device
 ..........................
 
 To create your bootable SD card, you must first find the correct device name
-of your SD card and possible partitions. Unmount any mounted partitions before
-you start copying the image to the SD card.
+of your SD card and possible partitions. If any partitions of the SD cards are
+mounted, unmount those before you start copying the image to the SD card.
 
 #. In order to get the correct device name, remove your SD card and
    execute:
@@ -87,11 +87,12 @@ In this case, you will also find the device name with an appended number
 distributions automatically mount partitions when the device gets plugged in.
 Before writing, however, these need to be unmounted to avoid data corruption.
 
-Unmount all partitions, e.g.:
+Unmount all those partitions, e.g.:
 
 .. code-block:: console
 
    host:~$ sudo umount /dev/sde1
+   host:~$ sudo umount /dev/sde2
 
 Now, the SD card is ready to be flashed with an image, using either ``partup``,
 ``dd`` or ``bmap-tools``.
@@ -140,10 +141,12 @@ Flash a WIC image to SD card by calling:
 .. code-block:: console
    :substitutions:
 
-   host:~$ bmaptool copy |yocto-imagename|-|yocto-machinename|.wic /dev/<your_device>
+   host:~$ bmaptool copy |yocto-imagename|-|yocto-machinename|.|yocto-imageext| /dev/<your_device>
 
-Make sure to place the ``<IMAGENAME>-<MACHINE>.wic.bmap`` alongside the regular
-WIC image, so bmaptool knows which blocks to write and which to skip.
+Replace <your_device> with your actual SD card's device name found previously,
+and make sure to place the file ``<IMAGENAME>-<MACHINE>.wic.bmap`` alongside
+the regular WIC image file, so bmaptool knows which blocks to write and which
+to skip.
 
 .. warning::
    *bmaptool* only overwrites the areas of an SD card where image data is
@@ -153,13 +156,25 @@ WIC image, so bmaptool knows which blocks to write and which to skip.
 Using ``dd``
 ............
 
-After having unmounted all partitions, you can create your bootable SD card:
+After having unmounted all SD card's partitions, you can create your bootable SD card.
+
+Some PHYTEC BSPs produce uncompressed images (with filename-extension \*.wic),
+and some others produce compressed images (with filename-extension \*.wic.xz).
+
+To flash an uncompressed images (\*.wic) use command below:
 
 .. code-block:: console
    :substitutions:
 
    host:~$ sudo dd if=|yocto-imagename|-|yocto-machinename|.wic of=/dev/<your_device> bs=1M conv=fsync status=progress
 
+Or to flash a compressed images (\*.wic.xz) use that command:
+
+.. code-block:: console
+   :substitutions:
+
+   host:~$ xzcat |yocto-imagename|-|yocto-machinename|.wic.xz | sudo dd of=/dev/<your_device> bs=1M conv=fsync status=progress
+
 Again, make sure to replace <your_device> with your actual device name found
 previously.
 

source/bsp/imx-common/development/format_sd-card.rsti

@@ -0,0 +1,91 @@
+Format SD-Card
+--------------
+
+Most images are larger than the default root partition. To flash any storage
+device with SD Card, the rootfs needs to be expanded or a separate partition
+needs to be created. There are some different ways to format the SD Card.  The
+easiest way to do this is to use the UI program Gparted.
+
+Gparted
+.......
+
+*  Get GParted:
+
+   .. code-block:: console
+
+      host:~$ sudo apt install gparted
+
+*  Insert the SD Card into your host and get the device name:
+
+   .. code-block:: console
+
+      host:~$ dmesg | tail
+      ...
+      [30436.175412] sd 4:0:0:0: [sdb] 62453760 512-byte logical blocks: (32.0 GB/29.8 GiB)
+      [30436.179846]  sdb: sdb1 sdb2
+      ...
+
+*  Unmount all SD Card partitions.
+*  Launch GParted:
+
+   .. code-block:: console
+
+      host:~$ sudo gparted
+
+.. image:: /bsp/imx-common/images/gparted1.png
+
+Expand rootfs
+~~~~~~~~~~~~~
+
+*  Choose your SD Card device at the drop-down menu on the top right
+*  Choose the ext4 root partition and click on resize:
+
+.. image:: /bsp/imx-common/images/gparted5.png
+.. image:: /bsp/imx-common/images/gparted2.png
+
+*  Drag the slider as far as you like or enter the size manually.
+
+.. image:: /bsp/imx-common/images/gparted3.png
+
+*  Confirm your entry by clicking on the "Change size" button.
+
+.. image:: /bsp/imx-common/images/gparted4.png
+
+*  To apply your changes, press the green tick.
+*  Now you can mount the root partition and copy e.g. the
+   |yocto-imagename|-|yocto-machinename|.wic image to it. Then unmount it again:
+
+   .. code-block:: console
+      :substitutions:
+
+      host:~$ sudo cp |yocto-imagename|-|yocto-machinename|.wic /mnt/ ; sync
+      host:~$ umount /mnt
+
+Create the Third Partition
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*  Choose your SD Card device at the drop-down menu on the top right
+
+.. image:: /bsp/imx-common/images/gparted1.png
+
+*  Choose the bigger unallocated  area and press "New":
+
+.. image:: /bsp/imx-common/images/gparted6.png
+
+*  Click "Add"
+
+.. image:: /bsp/imx-common/images/gparted7.png
+
+*  Confirm your changes by pressing the green tick.
+
+.. image:: /bsp/imx-common/images/gparted8.png
+
+*  Now you can mount the new partition and copy e.g.
+   |yocto-imagename|-|yocto-machinename|.wic image to it. Then unmount it again:
+
+   .. code-block:: console
+      :substitutions:
+
+      host:~$ sudo mount /dev/sde3 /mnt
+      host:~$ sudo cp |yocto-imagename|-|yocto-machinename|.wic /mnt/ ; sync
+      host:~$ umount /mnt