Merge branch 'lower-level-image-instructions' into 'master'

Add low-level flashing instructions

See merge request !317

Development_Environment/Boards/HowTo.rst

@@ -13,6 +13,7 @@ how to perform routine tasks.
    HowTo/Building_uuu
    HowTo/Data_Connections
    HowTo/Ethernet_over_USB
+   HowTo/Flashing_an_Image_by_Hand
    HowTo/Flashing_eMMC
    HowTo/HDMI
    HowTo/Install_Plasma_Mobile

Development_Environment/Boards/HowTo/Flashing_an_Image_by_Hand.rst

+.. _imx8_devkit_howto_flash_with_uuu:
+
+Flashing an Image by Hand
+=========================
+
+We recommend :ref:`using a script <imx8_devkit_flash_test_image>` to download and flash the latest image onto the development board. However, if you want to perform the steps by hand, the following information should be helpful.
+
+You should have already :ref:`installed uuu <imx8_devkit_install_uuu>` before proceeding.
+
+Download uuu Scripts
+--------------------
+
+Clone the `librem5-devkit-tools`_ repository and enter the working directory:
+
+.. code:: bash
+
+   git clone https://source.puri.sm/Librem5/librem5-devkit-tools.git
+   cd librem5-devkit-tools
+
+You will only need some of the files in this repository.
+
+Download the Recovery Image
+---------------------------
+
+Open the `Recovery U-Boot Build <recovery_image_>`_ page in a web browser and find the latest job with a successful build. Open the page for the build -- it should have a ``u-boot-devkit-recovery.imx`` download link in the list of Build Artifacts. Download this file into the ``files`` directory.
+
+.. _recovery_image: https://arm01.puri.sm/job/u-boot_builds/job/devkit-recovery_uboot_build/
+
+Download the Latest Image
+-------------------------
+
+Open the `Image Build <image_build_>`_ page in a web browser and find the latest "current devkit buster+ci image" job with a successful build. Open the page for the build -- it should have a ``devkit.img.xz`` download link in the list of Build Artifacts. Download this file into the ``files`` directory and check that the SHA256 sum matches the value contained in the ``meta.yml`` download to ensure that it was downloaded successfully.
+
+.. _image_build: https://arm01.puri.sm/job/Images/job/Image%20Build/
+
+Unpack the Image
+----------------
+
+Using the ``xz`` tool, unpack the image:
+
+.. code:: bash
+
+   xz -d files/devkit.img.xz
+
+Change the Boot Mode
+--------------------
+
+Put the "Boot Mode" switch on the development board in the USB position. Attach the development board to a USB C or USB 3 port on the host that is capable of providing 900mA of current. The HID device should appear in the output of the ``lsusb`` command, like this::
+
+   Bus 001 Device 005: ID 1fc9:012b NXP Semiconductors
+
+Now you can proceed with flashing.
+
+Run uuu with a Flashing Script
+------------------------------
+
+Ensure that the ``uuu`` tool is on the ``PATH``. Enter the ``uuu_scripts`` directory and run ``uuu`` on the ``flash_librem5-devkit.lst`` file.
+
+**This will erase everything on the board's eMMC:**
+
+.. code:: bash
+
+   cd uuu_scripts
+   uuu flash_librem5-devkit.lst
+
+This should cause the U-Boot and disk images to be written to the board's eMMC storage.
+
+Booting
+-------
+
+Return to the :ref:`imx8_devkit_booting` section for further instructions.
+
+.. include:: /links.txt

Development_Environment/Boards/imx8.rst

@@ -102,9 +102,13 @@ The main purpose of the image included on the eMMC is factory testing, therefore
 
 The scripts mentioned in this section can be obtained from the `librem5-devkit-tools`_ repository.
 
+.. _imx8_devkit_install_uuu:
+
 Install uuu
 ~~~~~~~~~~~
 
+.. note:: The ``uuu`` tool requires a 64-bit host to run and is packaged as an ``amd64`` binary.
+
 The NXP mfgtool ``uuu`` is required to boot a board that has no bootloader
 or is otherwise "bricked".
 
@@ -122,18 +126,20 @@ The precise ``.deb`` package file name may differ from the one given above. Vers
 Downloading Flashing Scripts
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Files from the `librem5-devkit-tools`_ repository are responsible for the downloading of the image files, and for coordinating their transfers to the dev kit.
+Files from the `librem5-devkit-tools`_ repository are responsible for the downloading of the image files, and for coordinating their transfers to the devkit. If you want to flash an image by hand instead of using the scripts, please consult the :ref:`imx8_devkit_howto_flash_with_uuu` guide.
+
+Clone the `librem5-devkit-tools`_ repository before proceeding::
 
-Check out the repository before proceeding.
+   git clone https://source.puri.sm/Librem5/librem5-devkit-tools.git
+
+You should now have everything you need to download and flash a new image.
 
 .. _imx8_devkit_flash_test_image:
 
 Flash the Image
 ~~~~~~~~~~~~~~~
 
-**Note:** If your workstation cannot provide the necessary power for this
-process you may need a USB 3 powered hub between the host and the development
-board.
+.. note:: If your workstation cannot provide the necessary power for this process you may need a USB 3 powered hub between the host and the development board.
 
 Put the "Boot Mode" switch in the USB position. Attach the development board
 to a USB C or USB 3 port on the host that is capable of providing 900mA of
@@ -183,6 +189,8 @@ directory and flash the eMMC, then re-flash it later as required.
 It can also be useful to use the ``--skip-flash`` if you only want to download
 the files without flashing the eMMC.
 
+.. _imx8_devkit_booting:
+
 Booting for the First Time
 ~~~~~~~~~~~~~~~~~~~~~~~~~~