.. -*- coding: utf-8 -*-

.. /*=============================================================================
     Readme file for Image FV feature
   
     Copyright (c) 2016-2019 Qualcomm Technologies, Inc. All rights reserved.
   
                                 EDIT HISTORY
   
    when       who     what, where, why
    --------   ---     -----------------------------------------------------------
    04/04/19   bd      Updated to refer to PIL API's
    10/11/17   bd      Initial version
   =============================================================================*/


.. _ImageFv:

=======
ImageFv
=======


Introduction
------------

UEFI supports display of Boot logo.
For different reasons there may be requirements to display different logo.
That means adding multiple image files to main FV.
This leads to increase in size of main FV and increase in Boot time.

To address this a new FV - imagefv - is created.
Whenever required, larger/multiple images can go into the imagefv.

It is advised to keep the first static boot image (QcomPkg/Logo/[LA|WP]/logo1.bmp)
inside mainfv for faster boot time.

Any additional boot logo animations and non-standard boot path logos can go inside the imagefv.



Adding images to ImageFv
------------------------

In file boot_images\QcomPkg\SDMPkg\<ChipId>\<variant>\ImageFv.fdf.inc add the entry for the image file under section "[FV.ImageFv]"
Like any other UEFI file, entry should contain a unique GUID, filename and relative path as shown below
 
Example ::

  FILE FREEFORM = 3E5584ED-05D4-4267-9048-0D47F76F4248 {
    SECTION UI = "battery_symbol_Soc10.bmp"
    SECTION RAW = QcomPkg/Drivers/QcomChargerDxe/battery_symbol_Soc10.bmp
  }


icrease size of ImageFv
-----------------------

In file boot_images\QcomPkg\SDMPkg\<ChipId>\<variant>\ImageFv.fdf.inc modify below entry and make sure it is 4K aligned.
as TZ expects 4K aligned address::

  [FV.IMAGEFV_COMPACT]
  BlockSize          = 0x200
  NumBlocks          = 0x400


Build and flashing of ImageFv
-----------------------------

ImageFv gets built along with xbl.elf for both DEBUG and RELEASE variants.
There is no separate build command for ImageFv.

Generated binary will be available in the same path as xbl.elf; 
i.e boot_images\QcomPkg\SDMPkg\<ChipId>\Bin\[WP|LA]\<build_variant>\

Flash the imageFv as shown below

Example : fastboot.exe flash ImageFv imagefv.elf



OEM image in ImageFv RETAIL
---------------------------

PIL configuration, contains the list of images which is allowed 
to be loaded by PIL. PIL does not support loading imagefv by default
uefipil.cfg must be modified in order to load image files from ImageFv in RETAIL::

  /BOOT.XF.3.1/QcomPkg/SDMPkg/<ChipId>\<variant>/uefipil.cfg
  
  [RETAIL]
  ABL
  +ImageFv


Loading and authenticating the ImageFv at runtime
-------------------------------------------------

Call below API's to load, authenticate and decompress the ImageFv::

  //Check if Image fv is already mounted
  if (GuidedFvIsMounted(&gEfiImageFvNameGuid))
    return EFI_SUCCESS;

  Status = gBS->LocateProtocol (&gEfiPilProtocolGuid,NULL, (VOID **) &PILProtocol);
  if ((EFI_SUCCESS != Status) || (NULL == PILProtocol))
  {
    DEBUG(( EFI_D_ERROR, "BmpTest:: %a %r \r\n", __FUNCTION__, Status));
    return Status;
  }

  Status = PILProtocol->ProcessPilImage(L"ImageFv");
  if ((EFI_SUCCESS != Status))
  {
    DEBUG(( EFI_D_ERROR, "BmpTest:: %a %r \r\n", __FUNCTION__, Status));
    return Status;
  } 
 
  Once above API is successful, images can be loaded as below.
  Status = LoadFileFromGuidedFv (&gEfiImageFvNameGuid,
                                  FileName,
                                  &FileBuffer,
                                  &FileSize);    


Limitations
-----------

Current partition size of ImageFv in Napali/Poipu is 2MB.
 
Example partition file entry::

  <partition label="ImageFv" size_in_kb="2048" type="17911177-C9E6-4372-933C-804B678E666F" bootable="false" readonly="false" filename=""/>

