Merge branch 'move-flashing-info' into 'master'

Move flashing info to the How To section

See merge request Librem5/developer.puri.sm!322

Development_Environment/Boards/HowTo.rst

@@ -15,6 +15,7 @@ how to perform routine tasks.
    HowTo/Ethernet_over_USB
    HowTo/Flashing_an_Image_by_Hand
    HowTo/Flashing_eMMC
+   HowTo/Flashing_uBoot
    HowTo/HDMI
    HowTo/Install_Plasma_Mobile
    HowTo/Inertial_Module

Development_Environment/Boards/HowTo/Flashing_eMMC.rst

-Flash U-Boot
-------------
+.. _imx8_devkit_flashing_emmc:
 
-If you only need to flash a new version of U-Boot onto the eMMC then follow
-these instructions instead of running the ``librem5-devkit-flash-image`` script.
+Flashing the System Image
+=========================
 
-Using SDP
-~~~~~~~~~
+The main purpose of the image included on the eMMC is factory testing, therefore it's strongly recommended to flash an up-to-date one immediately.
 
-The version of U-Boot that gets flashed is ``files/u-boot-devkit-recovery.imx``.
-Put the "Boot Mode" switch in the USB position::
+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".
+
+You can obtain a ``uuu`` package for Debian-based systems from `the Purism CI
+server`_ or :ref:`build uuu from source <imx8_devkit_howto_building_uuu>`.
+
+To install the package, run the ``dpkg`` tool in the following way::
+
+   sudo dpkg -i uuu_1.2.91_amd64.deb
+
+The precise ``.deb`` package file name may differ from the one given above. Version 1.2.91 or later is recommended.
+
+.. _`the Purism CI server`: https://arm01.puri.sm/job/debs/job/deb-mfgtools-buster-amd64/
+
+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 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::
+
+   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.
+
+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
+current. The HID device should appear in the output of the ``lsusb`` command,
+like this::
+
+   Bus 001 Device 005: ID 1fc9:012b NXP Semiconductors
+
+The ``librem5-devkit-flash-image`` script will download and flash the newest
+available rootfs and U-Boot images. You may need to install some Python modules
+before running the script. On Debian 9 (Stretch), Ubuntu 18.04 LTS (Bionic
+Beaver) and later, this command should install these modules::
+
+   sudo apt-get -y install python3-jenkins python3-tqdm python3-yaml
+
+Now you can proceed with the flashing, using the script as shown below to
+download temporary copies of U-Boot, kernel and the base system, before
+flashing them on the board. Use the ``--skip-cleanup`` and ``--dir`` command
+line options to keep the downloaded files after flashing.
+
+**This will erase everything on the board's eMMC:**
+
+.. code:: bash
 
    cd librem5-devkit-tools
    export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/
-   uuu uuu_scripts/u-boot_flash_librem5-devkit.lst
+   ./scripts/librem5-devkit-flash-image
+
+If you use the ``--dir`` option to download the files into a directory and
+``--skip-cleanup`` to keep them after flashing, you can re-flash the eMMC using
+the same files by entering the download directory and running ``uuu``.
+For example, this is how you would download the files to the ``/tmp/devkit``
+directory and flash the eMMC, then re-flash it later as required.
 
-You can also just boot to U-Boot without flashing anything::
+**This will erase everything on the board's eMMC:**
+
+.. code:: bash
 
    cd librem5-devkit-tools
    export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/
-   uuu uuu_scripts/u-boot_librem5-devkit.lst
+   ./scripts/librem5-devkit-flash-image --dir /tmp/devkit --skip-cleanup
+
+   # Re-flash the eMMC later:
+   cd /tmp/devkit
+   uuu flash_devkit.lst
+
+It can also be useful to use the ``--skip-flash`` if you only want to download
+the files without flashing the eMMC.
+
+Next Steps
+----------
+
+Go to the :ref:`imx8_devkit_booting` section to prepare the board for booting.
 
 .. include:: /links.txt

Development_Environment/Boards/HowTo/Flashing_uBoot.rst

+Flashing U-Boot
+===============
+
+If you only need to flash a new version of U-Boot onto the eMMC, instead of
+:ref:`flashing a complete image <imx8_devkit_flashing_emmc>`, then follow these
+instructions instead of running the ``librem5-devkit-flash-image`` script.
+
+Using SDP
+---------
+
+The version of U-Boot that gets flashed is ``files/u-boot-devkit-recovery.imx``.
+Put the "Boot Mode" switch in the USB position::
+
+   cd librem5-devkit-tools
+   export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/
+   uuu uuu_scripts/u-boot_flash_librem5-devkit.lst
+
+You can also just boot to U-Boot without flashing anything::
+
+   cd librem5-devkit-tools
+   export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/
+   uuu uuu_scripts/u-boot_librem5-devkit.lst
+
+.. include:: /links.txt

Development_Environment/Boards/imx8.rst

@@ -84,7 +84,7 @@ See :ref:`hardware_reference` for information about the specific parts used
 for the sockets, buttons and switches.
 
 Setting up the Board
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 In its original factory state, the board is lacking some essential features. We
 recommend that you consider :ref:`imx8_devkit_flashing_emmc` before using the
@@ -93,106 +93,10 @@ board for development.
 It may also be useful to consult the :ref:`imx8_devkit_known_issues` page and
 :ref:`imx8_devkit_troubleshooting` guide if problems occur.
 
-.. _imx8_devkit_flashing_emmc:
-
-Flashing the eMMC
------------------
-
-The main purpose of the image included on the eMMC is factory testing, therefore it's strongly recommended to flash an up-to-date one immediately.
-
-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".
-
-You can obtain a ``uuu`` package for Debian-based systems from `the Purism CI
-server`_ or :ref:`build uuu from source <imx8_devkit_howto_building_uuu>`.
-
-To install the package, run the ``dpkg`` tool in the following way::
-
-   sudo dpkg -i uuu_1.2.91_amd64.deb
-
-The precise ``.deb`` package file name may differ from the one given above. Version 1.2.91 or later is recommended.
-
-.. _`the Purism CI server`: https://arm01.puri.sm/job/debs/job/deb-mfgtools-buster-amd64/
-
-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 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::
-
-   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.
-
-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
-current. The HID device should appear in the output of the ``lsusb`` command,
-like this::
-
-   Bus 001 Device 005: ID 1fc9:012b NXP Semiconductors
-
-The ``librem5-devkit-flash-image`` script will download and flash the newest
-available rootfs and U-Boot images. You may need to install some Python modules
-before running the script. On Debian 9 (Stretch), Ubuntu 18.04 LTS (Bionic
-Beaver) and later, this command should install these modules::
-
-   sudo apt-get -y install python3-jenkins python3-tqdm python3-yaml
-
-Now you can proceed with the flashing, using the script as shown below to
-download temporary copies of U-Boot, kernel and the base system, before
-flashing them on the board. Use the ``--skip-cleanup`` and ``--dir`` command
-line options to keep the downloaded files after flashing.
-
-**This will erase everything on the board's eMMC:**
-
-.. code:: bash
-
-   cd librem5-devkit-tools
-   export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/
-   ./scripts/librem5-devkit-flash-image
-
-If you use the ``--dir`` option to download the files into a directory and
-``--skip-cleanup`` to keep them after flashing, you can re-flash the eMMC using
-the same files by entering the download directory and running ``uuu``.
-For example, this is how you would download the files to the ``/tmp/devkit``
-directory and flash the eMMC, then re-flash it later as required.
-
-**This will erase everything on the board's eMMC:**
-
-.. code:: bash
-
-   cd librem5-devkit-tools
-   export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/
-   ./scripts/librem5-devkit-flash-image --dir /tmp/devkit --skip-cleanup
-   
-   # Re-flash the eMMC later:
-   cd /tmp/devkit
-   uuu flash_devkit.lst
-
-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
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 Flip the boot switch back to eMMC position and press the reboot button. The
 output of the ``lsusb`` command should show a multifunction gadget, like this::