.. include:: /keyword.rst

=======================
Download Prebuilt Image
=======================

Each release of |IOT-YOCTO| also provides prebuilt images for selected development boards.
You can download prebuilt demo images from :doc:`/sw/yocto/download` page.

Please proceed to the :doc:`Build from Source Code<build-code>` page if you need to build board images from source code.

Please follow the steps below to extract and prepare the downloaded prebuilt image packages.

.. contents:: Use Prebuilt Images
    :local:
    :depth: 1


Extract the Prebuilt Image (Linux)
==================================

Please use ``tar`` tool to extract the downloaded image packages on Linux:

.. prompt:: bash

    mkdir image && tar -zxvf <image-name>.tar.gz -C image/

Please note the tailing ``/`` in the ``image/`` parameter is mandatory.
The extracted image files are located in the ``image`` folder. You can use a different directory name.

Extract the Prebuilt Image (Windows)
====================================

The image archive contains symbolic links.
Please use tools that supports **symbolic links** and **gzipped tarball** (``*.tar.gz``) file format, such as:

* `WinRAR <https://www.win-rar.com/>`_. 

Notes on WinRAR
---------------

Please note that you need to run WinRAR **as administrator** and open the archive from the program to extract it.
Otherwise WinRAR might reports permission error when trying to create symbolic links in the extracted image package.

.. figure:: /_asset/sw_yocto_get-started_prebuilt-image_winrar.png
	:align: center
	:width: 320px

	Run WinRAR as administrator

Notes on Path Length
--------------------

On some Windows file systems there are path length limitations, and the extracted package may be incomplete if the extracted directory path is too long.

* We recommend you to rename the archive to ``image.tar.gz`` before extracting it.
* We also recommend you to extract the image to a directory with short name, such as ``D:\board-image``.


.. _faq-json-decode-error-during-flash:

Notes on Symbolic link
----------------------

If you encounter the following error during ``genio-flash``

.. code:: text

	json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

Please check if both ``partitions.json`` and ``rity.json`` exists.
If one of these files are missing, please use an unarchiving tool that supports symbolic link.


Layout of Extracted Prebuilt Image
==================================

After extracting the image package, a typical image directory should contain at least the following files.

.. code:: text

	└── genio-1200-evk
		├── bl2.img
		├── bootassets.vfat
		├── capsule.vfat
		├── fip.bin
		├── fitImage
		├── lk.bin
		├── partitions.json
		├── rity-demo-image-genio-1200-evk.manifest
		├── rity-demo-image-genio-1200-evk.testdata.json
		├── rity-demo-image-genio-1200-evk.wic.img
		└── u-boot-initial-env

Some of the important files are:

- The ``partitions.json`` files provide meta data for the ``genio-flash`` tool for erasing and flashing the eMMC and UFS storage.
- The ``rity-demo-image-genio-1200-evk.wic.img`` contains the full disk image, including the partition table, for the `mmc0` storage.
- The ``bl2.img`` is the image for BL2 boot loader and is always written to ``mmc0boot0`` storage partition.
- The ``u-boot-initial-env`` is a plain text file that will be convert into binary representation of U-Boot environment variables by
  ``genio-flash`` tool during the image flashing process. The binary is then written into the ``mmc0boot1`` storage partition.

Other files are partition images that could be used to update a single partition in the ``mmc0`` storage. For the definition and layout
of each partition image, please refer to :doc:`/sw/yocto/part-layout`.

In most cases, these files are symbolic links (aliases) to actual files with detail information in the filename,
for example:

- ``fip.bin`` might be an pointing to ``fip-mt8195.bin``.
- ``rity-demo-image-genio-1200-evk.wic.img`` might point to ``rity-demo-image-genio-1200-evk-20230727004733.rootfs.wic.img``.

The exact file names are different for each SoC, board, and image recipe.

Flash the Extracted Image
=========================

Please proceed to :doc:`flash` page to flash this extracted image package with ``genio-flash``.