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

.. /*=============================================================================
     Guideline for comparing UEFI/Kernel display registers and DSI init sequence
     
     Copyright (c) 2022 Qualcomm Technologies, Inc.
     All Rights Reserved.
     Confidential and Proprietary - Qualcomm Technologies, Inc.
   =============================================================================*/


.. _DisRegCompare:

=============
DisRegCompare
=============


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

DispRegCompare is a tool that can dump and compare the programmed value of display HW registers between 
UEFI and Kernel display driver. It will also compare the panel initialization sequence commands 
between UEFI and Kernel display driver. The programming differences will help to debug any 
continuous splash screen feature issues.


Hardware/Software requirements
------------------------------

1) Hardware requirement

   - DUT (Device Under Test) connected to host PC through USB

2) Host PC Software requirement

   a) adb
   
   b) fastboot
   
   c) Python3.x
   
   d) pyfatfs
      
      - Pyfatfs can be installed by command: pip install pyfatfs


Usage
-----

To capture register values and generate programming difference report, please execute following steps in order.

1) Capture programming values in UEFI.

   a) Flash displayFat16.img for the list the register address the script will dump and compare.
   
      Boot DUT to fastboot mode, and run below command from host PC to flash displayFat16.img onto imagefv_b partition::
      
        fastboot flash imagefv_b displayFat16.img
        
      DisplayFat16.img can be found from BOOT image release path::
      
        <BOOT_ROOT>/QcomPkg/SocPkg/<TargetName>/Settings/Display/displayFat16.img
        
      DisplayFat16.img stores display_regs.txt, which contains a list of display register addresses that will need to be compared, 
      UEFI display driver will read from the file for the registers to be captured.
      This remains persistent until the partition is cleared or re-flashed.

   b) Enable display register capture in UEFI
   
      Boot DUT to fastboot when register compare work is done, run below command to stop register capture in UEFI
      mode and run below command from host PC to enable display registers capture in UEFI::
      
        fastboot oem select-display-panel log1
        
      This command will save the configuation as persistent variable "DisplayLogEnable".
      
   c) Capture display register values and panel initialization sequence commands on UEFI.
   
      Power cycle or run below command from host PC  to reboot the DUT to Android home screen::
      
        fastboot reboot
        
      During reboot after display hardware have been configured, UEFI display driver will update the display_reg.txt file in the imagefv_b partition
      with the value of the registers read at boot. UEFI panel initialization sequence will also be saved.
      UFEI display driver will disable continuous splash, so that kernel will re-programming the hw.
      
2) Capture kernel programming and compare programming

   Execute python script to generate report from host PC when DUT boot to home screen::
   
     Python DispRegCompare.py
     
   The script will enable debugfs, and trigger a display register dump. The register dump will be compared with UEFI register values saved in display_reg.txt.
   
   The script will abstract kernel panel initialization sequence from device tree node based on the panel name string, and compare it with UEFI panel initialization sequence.
   
   The script will generate html report for compare differences.

3) Stop display register capture in UEFI

   When the register compare work is done, to reduce the boot up time overhead (about 250ms) by register capture,
   run below command from host PC to stop register capture in UEFI::
   
     fastboot oem select-display-panel log0
     
   Step 1.b needs to be run if we need to do the comparation again.
   
   
Display programming difference report
-------------------------------------

Report.html will be generated by display register compare tool in the same folder of the compare tool.
It contains the table of registers with register address, which are different in value programmed in UEFI vs Kernel display driver. 
The report also contains the table panel initialization sequence, highlighting any differences in red.

