Commit 6615d3d9 authored by David Boddie's avatar David Boddie

Move flashing info to the How To section

parent e5a1b00b
......@@ -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
......
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 eMMC
=================
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
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
......@@ -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::
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment