.. _manual-install:

Manual Installation
===================

.. note:: The description in this doc implies that you have U-Boot with *UMS* support running on your module.

.. hint:: This guide does only apply for modules with *eMMC* storage types.


Files
-----

After a Yocto compile, regardless of which BSP you used, you can find all necessary files inside the **<image>** sub-folder of ``tmp/deploy/images``.

**<image>** is the bitbake target you built, e.g. *karo-image-minimal*.

Detailed deploy directory descriptions:

.. list-table::
   :header-rows: 1

   * - NXP BSP
     - Mainline BSP
   * - :ref:`yocto-guide/nxp/build:Image Deployment`
     - :ref:`yocto-guide/mainline/build:Image Deployment`


Partitioning
------------

First you have to create the desired GPT partitions.

1. Write the desired partitions using the ``gpt`` command. You can copy this from the ``uuu.auto`` file generated inside image dir.

   **Partition layouts depend on the module used**. The *fip* partition for STM32MP1 requires a specific type-UUID which is listed below.
   For other modules the fip partition can be removed.

.. prompt::
   :prompts: U-Boot>

   gpt write mmc 0 'start=1MiB,name=fip,type=19D5DF83-11B0-457b-BE2C-7559C13142A5,size=2MiB;name=boot,size=64MiB;name=rootfs,size=2GiB;name=userfs,size=MAX;'

.. note:: If the partition layout - or a single partition - stays the same, no data will be lost.

2. View the partitions created:

.. prompt::
   :prompts: U-Boot>

   mmc part

.. code-block:: text

   Partition Map for MMC device 0  --   Partition Type: EFI

   Part  Start LBA       End LBA         Name
         Attributes
         Type GUID
         Partition GUID
   1     0x00000800      0x000017ff      "fip"
         attrs:  0x0000000000000000
         type:   19d5df83-11b0-457b-be2c-7559c13142a5
         guid:   15e87f49-4b57-4f3b-90a5-fdf7130ab72b
   2     0x00001800      0x000217ff      "boot"
         attrs:  0x0000000000000000
         type:   ebd0a0a2-b9e5-4433-87c0-68b6b72699c7
         type:   data
         guid:   5363c5d2-84bc-48ab-a83f-d4277c9004a5
   3     0x00021800      0x004217ff      "rootfs"
         attrs:  0x0000000000000000
         type:   ebd0a0a2-b9e5-4433-87c0-68b6b72699c7
         type:   data
         guid:   ffc805d4-32d0-49ce-bda9-a27f17823678
   4     0x00421800      0x0075fbff      "userfs"
         attrs:  0x0000000000000000
         type:   ebd0a0a2-b9e5-4433-87c0-68b6b72699c7
         type:   data
         guid:   0bc3b9aa-87a6-45c9-ad79-badfaaac7d81


USB Mass Storage
----------------

You can use the ``ums`` command in U-Boot to turn the module into a USB
mass storage device. This will export all partitions from eMMC user area to your host.

Make sure the module is connected to your host via USB.

.. prompt::
   :prompts: U-Boot>

   ums 0 mmc 0

You can also export single partitions using their ``:index`` or ``#partlabel``.

E.g.:

.. prompt::
   :prompts: U-Boot>

   ums 0 mmc 0:2

This does the same:

.. prompt::
   :prompts: U-Boot>

   ums 0 mmc 0#boot


Host Computer
-------------

On your host computer you have to figure out, as which ``/dev/*`` the module storage was enumerated.

One way is to use the ``lsblk`` command:

.. prompt::
   :prompts: $

   lsblk -o name,mountpoint,partlabel,size

The output should look something like this:

.. code-block:: text

   NAME        MOUNTPOINT                 PARTLABEL   SIZE
   ...
   sdb                                                3,7G 
   ├─sdb1                                 fip           2M 
   ├─sdb2                                 boot         64M 
   ├─sdb3                                 rootfs        2G 
   └─sdb4                                 userfs      1,6G 
   ...


.. warning:: */dev/sdb3* is just valid for the examples on this page. Not knowing what you're doing can lead to **data loss** on your host!

Copying a Filesystem
~~~~~~~~~~~~~~~~~~~~

.. note:: When you'd try mounting a single partition on your host now, you'd get something like:

   .. code-block:: text
      
      mount: /mnt: wrong fs type, bad option, bad superblock on /dev/sdb3, missing codepage or helper program, or other error.

Luckily Yocto already creates ready-to-use **.ext4** filesystems. You can directly *dd* them to the target.

.. prompt::
   :prompts: $

   sudo dd if=tmp/deploy/images/txmp-1570/karo-image-minimal/karo-image-minimal-txmp-1570.ext4 of=/dev/sdb3

The result should look like this:

.. code-block:: text

   262144+0 records in
   262144+0 records out
   134217728 bytes (134 MB, 128 MiB) copied, 32,6599 s, 4,1 MB/s


Copying single Files
~~~~~~~~~~~~~~~~~~~~

Copying single files requires the partitions to contain a filesystem. The best way to achieve this, is to copy the **.ext4** files like mentioned above.

What will also work is creating the filesystem by hand, e.g.:

.. prompt::
   :prompts: $

   sudo mkfs.ext4 /dev/sdb3

Then you can mount the partition:

.. prompt::
   :prompts: $

   sudo mount /dev/sdb3 /mnt

.. note:: For accessing single files inside the **.ext4** files, you can also mount them:

   .. prompt::
      :prompts: $

      sudo mount -o loop karo-image-minimal-txmp-1570.ext4 /tmp/mountpoint

Copy a file:

.. prompt::
   :prompts: $

   sudo cp /tmp/mountpoint/etc/hostname /mnt/etc/

.. tip:: To sync data and prevent data-loss always **unmount** the target partition!

.. prompt::
   :prompts: $

   sudo umount /mnt


Target Configuration
--------------------

To correctly boot the data you just copied, you might have to fit the U-Boot environment accordingly.

Refer to :ref:`uboot-environment`.