Insyde Variable Editor Utility for Linux (Support Linux kernel > 2.6.18)

-------------------------------------------------------------------------
Note:
- The first time to modify strings may get unexpected remaining space because of the filtered unexpected characters.
- The -gbd command may not work as we expected even H2OUVE return success on the legacy system because of boot device must obey boot type order.
- Currently, Console Redirection can't be modified.
-------------------------------------------------------------------------

Install
-------------------

  First of all, extract RPM package from the Insyde*_x86_*-xxx.xx.xx.xx.tar.bz2.
  If you would like to install H2OUVE on RedHat Linux, please go to section "Install on RedHat"

  a) RPM
    Install kernel-header, gcc and make first then run following command
    $ sudo rpm -ivh Insyde*_x86_*-xxx.xx.xx.xx.rpm
    
  b) Debian
    Install linux-headers, gcc and make first then run following command
    $ sudo dpkg -i Insyde*_x86_*-xxx.xx.xx.xx.deb

  c) Portable
    If your system does NOT have package control manager like YUM or APT, the portable version allows users to run H2OUVE without installation, please refer section(Build Driver) to compile driver.

Execute Application
-------------------

  You need root privilege to execute the program.
  Please make sure that normal user has been added into 
  '/etc/sudoers' or run visudo to edit it.

  Run GUI mode:
    Open a terminal and type:
    $ 32bit: sudo h2ouve-l -g
    $ 64bit: sudo h2ouve-lx64 -g

  Console mode & help:
    Open a terminal and type:
    $ 32bit: sudo h2ouve-l -h
    $ 64bit: sudo h2ouve-lx64 -h

Build Driver
-------------------

  1) Install compiler:
    a) Fedora/Red Hat:
      $ su -c "yum -y install gcc kernel-devel make"
    b) Suse:
      $ su -c "zypper install -y gcc kernel-devel make"
    c) Ubuntu: 
      $ sudo apt-get install -y build-essential
    d) Others:
      You have to download related build tools if the system contain no package manager.

  2) Building & install the driver
    Please install kernel source header manually, then
    $ cd /var/local/insyde/H2OUVE/driver/ or ./driver (portable version)

    a) Fedora/Red Hat/Suse
      $ su -c "make"
      $ su -c "make install"

    c) Ubuntu: 
      $ sudo -E make 
      $ sudo -E make install


Error handling
-------------------

  1) Missing libexpat.so.0
    When encountering the following error:
    "Error while loading shared libraries: libexpat.so.0: cannot open shared object file: No such file or directory"
  
    Try to install libexpat and check if there libexpat.so.0 under /lib
    If there is a libexpat.so.1 under /lib, create a soft link to it and named libexpat.so.0

  2) Autorun failed for the ITB feature
    When returning to OS, H2OUVE doesn't run automatically

    a) Modify /etc/sudoers with root privilege
      sudo visudo

    b) If your username is "user", add below settings without double quotes
      "user ALL=(ALL:ALL) NOPASSWD: /usr/bin/h2ouve-xxx"
      "user ALL=(ALL:ALL) NOPASSWD: /usr/bin/H2OUVE-xxx"

  3) When you get an error "Unable to find DISPLAY" on Wayland, switch back to Xorg to fix this issue.
    Try google "switch Wayland to Xorg" to find more answers.

  4) Fail to run on Fedora 28: Mapping over 1M address is not allowed by default, following the steps to workaround

    a) Press 'e' in the grub menu during boot.

    b) add "iomem=relaxed" at the end of "linux16 /vmlinuz" or "linux /vmlinuz"

  5) Could not insert module phy_alloc.ko: Required key not available
    When SecureBoot is enabled, phy_alloc.ko has to be signed before using.
    Sign that with command below:
    sign-file sha256 <private_key> <public_key> phy_alloc.ko

    Note: sign-file could be found in /lib/modules/`uname -r`/build/scripts/

If there is any setting that can not work after modification, please contact BIOS for support.


ITB feature
-------------------

  Before running the ITB feature, make sure you can log in to the system automatically and the user account has administrator privilege for all operations without forwarding authentication.
  
  NOTE:
  This tool calls the IHISI function 0h to get boot order sequences from the "BootOrder" variable. 
  Ex: 0400 0300 0000 0100

  After getting the order sequence, we get the device name in the "Boot####" variables. 
  Ex: Boot0004
  The device name starts from offset 6 in its variable data. 
  But the name of the USB starts from byte 6 with 0x20. This tool will skip those 
  0x20 before getting other numbers.

  3. CMOS Area Verify
    InsydeH2O has reserved some non-sequential areas of CMOS for OEM use. Therefore, 
    Kernel or Chipset code should not touch these areas. To prevent OEM areas from 
    being destroyed by anyone besides OEMs, we need software that can verify 
    Kernel code and Chipset code.

  4. Variable Verification Command-List

    a. -cnvs
     - Clean NV SPARE data and then reboot.

    b. -cvhc
     - Check the variable header
     - If the variable header has no checksum then the tool will show pass. (without -s)
     
    c. -dvfi -i <ImageFile>
     - Variable reclamation check on DXE.
     - If the variable size is not full, H2OUVE will continue to write the variable by SMI, but it will reserve about 0x600 bytes space.
       The entire left area is 0xFF. The tool writes one dirty byte 0x99 to the left area and reboots the system to implicitly invoke 
       BIOS's reclaim event. (BIOS will do reclamation if any byte in the free space is not 0xff)
     - -Count: test times, if there is no input, perform test for 1 time.

    d. -cvrs [-count N]
     - Variable reclamation check on SMM.
     - Tool will write variable by SMI until reclaim reaches the number specified by -count, and then reboot.
     - If the [-Count] input is not specified, the default is 500 times.
     - Does not support the long run.

    e. -cvsf [-count N] [-bc]
     - Do Variable rebuild check, which will overwrite all variables and FV header with fill data 0xFF.
     - -COUNT: test times, if there is no input, perform test once.
     
    f. -cvs0 [-count N] [-bc]
     - Same as -VB, but will erase all variable and FV header and fill with data 0x00.
     - -COUNT: test times, if there is no input, perform test for 1 time. 
     
    g. -vorv [-count N]
     - Fill in the full variable store region, and explicitly make the following two test cases 
       @ Case1: The data size of the last variable exceeds the variable store region range
       @ Case2: The variable header of the last variable is incomplete (only 8 bytes) and then reaches the end
                of the variable store region
           
    Note:
    The command -vor is to verify issue #22949. Its solution is added in Kernel-week 49 (03.72.49/05.02.49)
          
    h. -cvur [-count N]
     - Check variable usage condition during POST time (reset by warm-reboot) 
     - In the first run, the tool will record the NV used bytes and then reboot. During the POST time, BIOS may update or add variables. So in the second run, the tool will compare the NV used bytes to detect this situation.
     - This test is to detect that BIOS meaninglessly updates the variables during the POST time. 

    i. -cvus [-count N] [-w SECONDS]
     - Check variable usage condition during POST time (reset by the shutdown) 
     - In the first run, the tool will record the NV-used bytes, set wakeup time, and then shutdown. During the POST time, BIOS may update or add variables. So in the second run, the tool will compare the NV used bytes to detect this situation.
     - This test is to detect that BIOS meaninglessly updates the variables during the POST time.
     - "S5 long run test function in Power page in SCU must be enabled.
     - -w: Set RTC alarm to wake up system, default is 120 seconds for Windows and Linux.
             
    j. -cvax [-COUNT]
     - Long-run test command, the testing items includes
      #1.do -cvhc command.
      #2.do -cnvs command.
      #3.do -dvfi command.
      #4.do -vorv command (2 test cases).
      #5.do -cvur command.
      #6.do -cvus command.
      #7.do -cvsf command.
      #8.do -cvs0 command.
      
     - -COUNT: test times, if there is no input, perform test once.

    k. -cvsd 
     - Check variable state in SMM Variable Service.

    l. -cbov
     - Test if bios hang after BootOrder variable is maliciously changed
     
  5. Misc. Commands
    a. -BC
     - Used together with -vb command
     - Do partial erase. Erase size = Number * block size(0x1000)
     
    b. -n 
     - Disable auto rebooting for the commands: -cnvs, -cvrd, -cvsf, -cvs0

    c. -count 
     - Used together with some commands to specify the test times or the reclamation times (-vrs).
     
    d. -del   
     - explicitly delete the tool-created temp files
       
  6. SINI Testing
     -sipi
     Verify system hang problem after sending SINI command for QA.

Install on RedHat
-------------------

  Note: If you have not configured the package repository, please reference section "Config Repository"
  Run "sudo ./RH_installer.sh" to install H2OUVE on 7.x/8.x


Config Repository
-------------------

  1. mount/insert the install media
  2. add file "iso.repo" with the following content under /etc/yum.repo.d/
  
  Note: /mnt is the install media location, change it if your location is not /mnt.

  RedHat 7.x
  [Iso]
  name=ISO
  gpgcheck=0
  enabled=1
  baseurl=file:///mnt

  RedHat 8.x
  [BaseOS]
  name=ISO BaseOS
  gpgcheck=0
  enabled=1
  baseurl=file:///mnt/BaseOS
  
  [AppStream]
  name=ISO AppStream
  gpgcheck=0
  enabled=1
  baseurl=file:///mnt/AppStream
