.. include:: /keyword.rst

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

.. note::

   You do not need to download prebuilt images if you wish to build board images from source code.
   Please proceed to the :doc:`build-code` page.

Prebuilt images are provided for each release of |IOT-YOCTO| for selected development boards.
You can download prebuilt demo images from the :doc:`download </sw/yocto/download>` page.


Extracting Prebuilt Images
==========================

.. tabs::

   .. group-tab:: 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.

   .. group-tab:: 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/>`_. 
      
      .. note::
      
         You need to run WinRAR **as administrator** and open the archive from the program to extract it.
         Otherwise WinRAR might report a 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
      
      .. note::
         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 that you:

         * Rename the archive to ``image.tar.gz`` before extracting it.
         * Extract the image to a directory with short name, such as ``D:\board-image``.
      
      
      .. note::
         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 extraction tool that supports symbolic links.


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.

.. note::
   Please proceed the :doc:`connect` page to continue this guide with a prebuilt image.