8.2.3 Verifying Android targets

You can verify an Android target at both the application level and the graphics software stack integration level.

This section walks you through this verification with the Generic Graphics Accelerator.

Debugging graphics APIs for applications

To show the execution of target graphics APIs, firstly set the configuration file of the Generic Graphics Accelerator, then boot the Android target with the Generic Graphics Accelerator.

Before you begin

Make sure that the Android target boots successfully with the Generic Graphics Accelerator. For more details, see 8.2.1 Booting Android targets for the first time.

Procedure

  1. In the settings.ini configuration file, set LogLevel to either of the following values:

    • 6565: Represents LOG_LEVEL_INFO to show information about the important stages in executing APIs.
    • 6566: Represents LOG_LEVEL_DEBUG to show the names and parameters of each API that is called.

    For more details about settings.ini, see 8.3 The configuration file.

  2. Boot the Android target again to show execution details of the graphics APIs. For the boot command, see Example: Booting an Android target to verify the OS.

    Note:

    If you find issues, try to reproduce them using a different platform model. Report bugs in the Generic Graphics Accelerator to the support team as described in 8.4 Feedback on the Generic Graphics Accelerator.

Debugging graphics software stack integration

The Generic Graphics Accelerator enables integration between the Android graphics software stack and the GPU model. You can also debug this integration using the Generic Graphics Accelerator.

In this section, you will learn how to perform and debug the graphics integration using the Generic Graphics Accelerator.

Integrating the graphics driver with the GPU model

The integration is performed when booting the Android target on a host when the Generic Graphics Accelerator is set for integration test.

About this task

Perform this task to verify the integration of the Mali™ Mali graphics driver with a GPU model on an Android target. After the integration, rendering is performed using the host GPU, because the Mali GPU models only model registers, not the shader core.

For background information, see Graphics integration for Android targets.

Before you begin

Make sure that:

  • The target virtual platform contains one of the GPU models, for example Mali_G71. For details about these models, see Fast Models components in Fast Models Reference Manual.

  • The Android image file contains the Mali graphics driver.
  • The working directory of the virtual platform contains the nomali library. If not, copy the library from the following location to this directory:

    • On Windows, <installation_directory>\lib\Win64_VCxxxx\Release\nomali.dll, where xxxx is the Visual Studio version number.
    • On Linux: <installation_directory>/lib/Linux64_GCC-x.x/libnomali.so, where x.x is the GCC version number.
  • If you are building your own virtual platform, your platform project .sgproj file must contain:
    path="$(PVLIB_HOME)/etc/nomali.sgrepo"
  • In the device tree, GPU is enabled.
  • The Android target has booted successfully with the Generic Graphics Accelerator, see 8.2.1 Booting Android targets for the first time.

Procedure

  1. From the directory in which you booted Android with the Generic Graphics Accelerator, open the settings.ini file.
    For details about settings.ini, see 8.3 The configuration file.
  2. In the file, set callOnTargetAPI to 1.
  3. On the host, boot the target by using the command shown in Example: Booting an Android target to verify graphics drivers.

    Terminals open to emulate the target.

  4. From the host, push Shim libraries to the target with new locations given to the target Mali GLES libraries.
  5. On the host, enter the following commands to disable the OpenGL ES preload feature from the target driver:
    adb remount
    adb shell sed -i '/ro.zygote.disable_gl_preload=/d' /system/build.prop
    adb shell "echo \"ro.zygote.disable_gl_preload=true\" >> /system/build.prop"
  6. On the host, enter the following commands to enable rendering on the host GPU.
    The commands are different for Linaro, and 32-bit and 64-bit Android:
    • 64-bit Android:
      adb remount
      adb shell sed -i '1,/ro.kernel.qemu/s/ro.kernel.qemu/No.kernel.qemu/' /system/lib/libEGL.so
      adb shell sed -i '1,/ro.kernel.qemu/s/ro.kernel.qemu/No.kernel.qemu/' /system/lib64/libEGL.so
    • 32-bit Android:
      adb remount
      adb shell sed -i '1,/ro.kernel.qemu/s/ro.kernel.qemu/No.kernel.qemu/' /system/lib/libEGL.so
    • Some Linaro distributions of 64-bit Android:
      adb remount
      adb shell sed -i '1,/ro.kernel.qemu/s/ro.kernel.qemu/No.kernel.qemu/' /system/lib/libEGL.so
      adb shell sed -i '1,/ro.kernel.qemu/s/ro.kernel.qemu/No.kernel.qemu/' /system/lib64/libEGL.so
      adb shell sed -i 's/ro.nohardwaregfx=true/ro.nohardwaregfx=false/' /system/build.prop
    • Some Linaro distributions of 32-bit Android:
      adb remount
      adb shell sed -i '1,/ro.kernel.qemu/s/ro.kernel.qemu/No.kernel.qemu/' /system/lib/libEGL.so
      adb shell sed -i 's/ro.nohardwaregfx=true/ro.nohardwaregfx=false/' /system/build.prop
  7. On the host, reboot the target:
    adb shell sync
    adb shell reboot

Results

  • During booting:
    • The host terminal shows the interaction between the Reconciler and the OpenGL ES Emulator.
    • A graphical window opens to display the target system desktop.
    • From the target terminal, enter the logcat command to view more details from the target, such as:

      • The interaction between the Shim Layer and applications.
      • The interaction between the Shim Layer and the Reconciler.
  • After the target has booted, you see:

    • The message, mali 2d000000.gpu: Probed as mali0, on the target terminal. It implies that the driver has recognized the GPU model and starts the control.
    • The default Android desktop for this target. You can operate it using the mouse.

  • If the boot fails, study the output messages carefully and debug the driver.

    To view more log information, modify the log settings in settings.ini. For details, see 8.3 The configuration file.

What to do next

You can:

  • Run the test applications, such as Cube.

    For installation information, see Installing applications on Android targets.

  • Debug the integration.

    You can use the Generic Graphics Accelerator to debug the graphics driver's execution of the graphics APIs and accesses to the GPU register model, as described in the following sections.

  • Quit the boot by using the kill command from the host.
Pushing the Shim libraries to the Android target for the driver integration

Use the adb command to push the Shim libraries to the target.

About this task

This task transfers the OpenGL ES API data from both the Shim libraries and the graphics driver to the host and the GPU register model respectively. The host GPU is used to perform fast rendering for the Android target.

Before you begin

Make sure that the Android SDK is installed.

Procedure

  1. From the host, enter the following commands:
    Example:

    On Linux:

    export PATH=$PATH:<path of android-sdk-linux>/platform-tools/
    adb connect localhost:6901

    On Windows:

    set PATH=%PATH%;<installation_directory>\<path of android-sdk-windows>\platform-tools
    adb connect localhost:6901

    Note:

    The port number here must be identical to the first value of the option board.hostbridge.userNetPorts in the boot command that is shown in Example: Booting an Android target to verify graphics drivers.
  2. From the host, connect to the target using:
    adb connect localhost:6901
  3. From the host, change the Mali GLES library directories on the target using:
    adb shell mv /system/vendor/lib64/egl/libGLES_mali.so /system/lib64/libmali.so
    adb shell mv /system/vendor/lib/egl/libGLES_mali.so /system/lib/libmali.so
  4. Remove libEGL*.so and libGLES*.so from the target.

    Note:

    Back up the files before removal.

    The commands are:

    adb shell rm /system/vendor/lib/egl/libEGL*.so
    adb shell rm /system/vendor/lib/egl/libGLES*.so
    adb shell rm /system/vendor/lib64/egl/libEGL*.so
    adb shell rm /system/vendor/lib64/egl/libGLES*.so
  5. If Android uses customized native window handles, create a customized libnwhal.so file as described in Generating libnwhal.so.

    Note:

    Skip this step if Android follows the standard Android Open Source Project, or uses the default Gralloc module provided at https://developer.arm.com/products/software/mali-drivers/android-gralloc-module.
  6. On the host, change to the $PVLIB_HOME directory that contains the Generic Graphics Accelerator package.
  7. Enter the following command to push the Shim libraries from the host to the target.
    Commands are different for 32-bit and 64-bit Android.
    Example:

    For 64-bit:

    • The Linux commands are:

      adb remount
      
      adb push  GGA/shim/linux-armv7sfl/rel/libGLES.so   /system/vendor/lib/egl/libGLES_vimpl.so
      adb push  GGA/shim/linux-armv7sfl/rel/<HAL>/libnwhal.so       /system/lib/libnwhal.so
      
      adb push  GGA/shim/linux-armv8l_64/rel/libGLES.so  /system/vendor/lib64/egl/libGLES_vimpl.so
      adb push  GGA/shim/linux-armv8l_64/rel/<HAL>/libnwhal.so      /system/lib64/libnwhal.so
      
      adb shell chmod 0644 /system/lib/libnwhal.so
      adb shell chmod 0644 /system/vendor/lib/egl/libGLES_vimpl.so
      adb shell chmod 0644 /system/lib64/libnwhal.so
      adb shell chmod 0644 /system/vendor/lib64/egl/libGLES_vimpl.so
      
    • The Windows commands are:

      adb remount
      
      adb push  GGA\shim\linux-armv7sfl\rel\libGLES.so   /system/vendor/lib/egl/libGLES_vimpl.so
      adb push  GGA\shim\linux-armv7sfl\rel\<HAL>\libnwhal.so       /system/lib/libnwhal.so
      
      adb push  GGA\shim\linux-armv8l_64\rel\libGLES.so  /system/vendor/lib64/egl/libGLES_vimpl.so
      adb push  GGA\shim\linux-armv8l_64/rel\<HAL>\libnwhal.so      /system/lib64/libnwhal.so
      
      adb shell chmod 0644 /system/lib/libnwhal.so
      adb shell chmod 0644 /system/vendor/lib/egl/libGLES_vimpl.so
      adb shell chmod 0644 /system/lib64/libnwhal.so
      adb shell chmod 0644 /system/vendor/lib64/egl/libGLES_vimpl.so
      

    For 32-bit:

    • The Linux commands are:

      adb remount
      
      adb push  GGA/shim/linux-armv7sfl/rel/libGLES.so /system/vendor/lib/egl/libGLES_vimpl.so
      adb push  GGA/shim/linux-armv7sfl/rel/<HAL>/libnwhal.so     /system/lib/libnwhal.so
      
      adb shell chmod 0644 /system/vendor/lib/egl/libGLES_vimpl.so
      adb shell chmod 0644 /system/lib/libnwhal.so
      
    • The Windows commands are:

      adb remount
      
      adb push  GGA\shim\linux-armv7sfl\rel\libGLES.so /system/vendor/lib/egl/libGLES_vimpl.so
      adb push  GGA\shim\linux-armv7sfl\rel\<HAL>\libnwhal.so     /system/lib/libnwhal.so
      
      adb shell chmod 0644 /system/vendor/lib/egl/libGLES_vimpl.so
      adb shell chmod 0644 /system/lib/libnwhal.so
      

    Note:

    In these commands, the folder name <HAL> can be either of the following:

    • stock, if the Android version follows the standard Android Open Source Project.
    • The Gralloc version number used, such as bfst-r7p0-01rel0, if the Android version uses a published Gralloc module.

Examining OpenGL ES execution in the graphics driver

The Error Code Check function in the Generic Graphics Accelerator examines the execution of OpenGL ES API in the target graphics driver.

About the task

Error Code Check reports APIs for which the host driver and the target driver return different error codes. For the error report that it generates, see Error messages from Error Code Check.

Before you begin

Make sure:

Procedure

  1. Open the settings.ini file.
  2. In the file, assign a value to LogLevel other than 0 or 1.
    For the allowed values for LogLevel, see 8.3 The configuration file.
  3. Set checkErrorCode to 1 to enable the Error Code Check function.
    #1:Enable. 0:Disable.
    checkErrorCode 1
  4. If you want to examine all OpenGL ES APIs, set:
    #1:Enable. 0:Disable.
    enableErrorCheckWhiteList 0
  5. If you want to examine only specific APIs:
    1. Set enableErrorCheckWhiteList to 1.
    2. Open the checkerrcode.ini file, and set the APIs you are interested in to 1.

    Note:

    checkerrcode.ini is located in the same directory as settings.ini, which is <installation_directory>/GGA/reconciler/linux-x86_64/gcc-x.x.x/rel/ on Linux, or <installation_directory>\GGA\reconciler\win_32-x86_64\cl-18.00.31101\rel\ on Windows.
  6. Boot Android to show the API execution in the driver.
    You can use the boot command as shown in Example: Booting an Android target to verify graphics drivers.
Results

If abnormal APIs are detected, the host shows errors like the following:

ERROR [RECONCILER] gles20_glCopyTexSubImage2D Inconsistent error code detected. host=0x0501, target=0x0502

For more details about this and other error messages, see Error messages from Error Code Check.

Error messages from Error Code Check

The error messages show problematic OpenGL ES APIs for which the host driver and the target driver have returned different error codes.

The following examples show errors that are generated by the target GPU drivers, the Generic Graphics Accelerator, and the Mali OpenGL ES Emulator:

  • Errors from the target graphics driver:

    ERROR [RECONCILER] gles20_glCopyTexSubImage2D Inconsistent error code detected. host=0x0501, target=0x0502

    Here:

    • gles20_glCopyTexSubImage2D is the problematic API.
    • 0x0501 and 0x0502 are the error codes retrieved from the host driver and the target driver respectively.

      Note:

      API error codes are defined in the OpenGL ES header file.
  • Errors from the Generic Graphics Accelerator:

    FATAL [RECONCILER] glProgramParameteri() Could not find program object descriptor for target-side program id [0]

    Here, glProgramParameteri() is the problematic API.

    Note:

    Report Generic Graphics Accelerator bugs directly to the Arm account team. For more details, see 8.4 Feedback on the Generic Graphics Accelerator.
  • Errors from the Mali OpenGL ES Emulator:

    FATAL-Exception thrown in GLES32Api::glUniformMatrix4fv -> Underlying OpenGL error in GL33Backend.
    See Fatal error logs for full details. This is probably a programming error, please report it.

    Note:

    Report Mali emulator errors directly to the Arm account team.

    For information about the Mali OpenGL ES Emulator, see Mali OpenGL ES Emulator User Guide.

Tracing the driver accesses to the GPU registers

You can use the Trace and Dump function provided by the Generic Graphics Accelerator to trace the modeled GPU register accesses to the graphics driver.

Before you begin

  • You must have integrated the graphics driver with the GPU model for your Android target. For details, see Integrating the graphics driver with the GPU model.

  • You require the ListTraceSources and GenericTrace plug-ins. These plug-ins list the available trace sources and specify which events should be traced, respectively. They are located in $PVLIB_HOME/plugins/<OS_compiler>/.

Procedure

  1. On the host, execute the following command to list the trace sources that are provided by the GPU model:
    ${PATH_Model} --plugin $PVLIB_HOME/plugins/Linux64_GCC-5.4/ListTraceSources.so
    Results: The terminal shows:
    • The GPU model:

      Component (292) providing trace: Kits3_Subsys.css.gpu
    • Trace sources provided by the Mali GPU model:
      INFO_ReadRegister
      Outputs the access time, addresses, data, and names of the read registers.
      INFO_Reset
      Outputs the GPU reset data.
      INFO_WriteRegister
      Outputs the access time, addresses, and names of the write registers, and the data before and after write actions.
      INFO_IrqGpuControl
      Outputs the ID, name, and the state of the IRQ signal from the GPU. The state can be Y for Set, or N for Clear.
      INFO_IrqJobControl
      Outputs the ID, the name, and the state of the IRQ signal from the Job Manager on the GPU. The state can be Y for Set, or N for Clear.
      INFO_IrqMmuControl
      Outputs the ID, the name, and the state of the IRQ signal from the MMU on the GPU. The state can be Y for Set, or N for Clear.
      WARN_ReadToWriteOnlyRegister
      Outputs warning messages and addresses for the write-only registers that have been read by the graphics driver.
      WARN_WriteToReadOnlyRegister
      Outputs warning messages and addresses for the read-only registers that have been written by the graphics driver.
      WARN_AccessToUnimplementedRegister
      Outputs warning messages and addresses for the invalid registers that have been accessed by the graphics driver.
  2. Boot the Android target with the command shown in Example: Booting an Android target to verify graphics drivers.
    When you enter the command, add the following options:
    --plugin $PVLIB_HOME/plugins/Linux64_GCC-5.4/GenericTrace.so \
    -C TRACE.GenericTrace.trace-sources=Kits3_Subsys.css.gpu.* \
    -C TRACE.GenericTrace.enabled=1 \
    -C TRACE.GenericTrace.verbose=1 \
    -C TRACE.GenericTrace.print-timestamp=1 \
    -C TRACE.GenericTrace.trace-file=dp-trace-generic.log

    In these options:

    • Kits3_Subsys.css.gpu is the GPU model obtained from Step 1.

      • To trace all the GPU-supported registers, add the suffix '*' to this GPU. For instance, Kits3_Subsys.css.gpu.*.

      • To trace one type of register, add the register type name as a suffix to this GPU. For instance, Kits3_Subsys.css.gpu.INFO_ReadRegister.

      • To trace different types of registers, separate each type with ','. For instance, Kits3_Subsys.css.gpu.INFO_ReadRegister, Kits3_Subsys.css.gpu.INFO_WriteRegister

    • dp-trace-generic.log is the log file used in this example to save the trace results.

      Note:

      If the trace-file option is not used, the trace results are shown on the host terminal.

    For more details about these trace options, see GenericTrace in the Fast Models Reference Manual.

  3. (Optional) Run test applications to continue examining the driver accesses to the GPU.
    For how to install an application, see Installing applications on Android targets.
Results:

The host terminal or the log file shows details about the driver-accessed registers, such as the register addresses, contained data, and the access time, as shown in the following output:

HOST_TIME=1557460.545195s INFO_ReadRegister: REG_OFFSET=0x0000000000000000 VALUE=0x60000000 REG_NAME="GPU_ID"
HOST_TIME=1557460.545266s INFO_ReadRegister: REG_OFFSET=0x0000000000000004 VALUE=0x07130206 REG_NAME="L2_FEATURES"
HOST_TIME=1557460.545279s INFO_ReadRegister: REG_OFFSET=0x0000000000000008 VALUE=0x00000000 REG_NAME="SUSPEND_SIZE"
HOST_TIME=1557460.545291s INFO_ReadRegister: REG_OFFSET=0x000000000000000c VALUE=0x00000809 REG_NAME="TILER_FEATURES"
HOST_TIME=1557460.545303s INFO_ReadRegister: REG_OFFSET=0x0000000000000010 VALUE=0x00000001 REG_NAME="MEM_FEATURES"
HOST_TIME=1557460.545316s INFO_ReadRegister: REG_OFFSET=0x0000000000000014 VALUE=0x00002830 REG_NAME="MMU_FEATURES"
HOST_TIME=1557460.545325s INFO_ReadRegister: REG_OFFSET=0x0000000000000018 VALUE=0x000000ff REG_NAME="AS_PRESENT"
HOST_TIME=1557460.545334s INFO_ReadRegister: REG_OFFSET=0x000000000000001c VALUE=0x00000007 REG_NAME="JS_PRESENT"
HOST_TIME=1557460.545345s INFO_ReadRegister: REG_OFFSET=0x00000000000000c0 VALUE=0x0000020e REG_NAME="JS0_FEATURES"
HOST_TIME=1557460.545362s INFO_ReadRegister: REG_OFFSET=0x00000000000000c4 VALUE=0x000001fe REG_NAME="JS1_FEATURES"
HOST_TIME=1557460.545364s INFO_ReadRegister: REG_OFFSET=0x00000000000000c8 VALUE=0x0000007e REG_NAME="JS2_FEATURES"
HOST_TIME=1515565849.690948s gpu.INFO_WriteRegister: REG_OFFSET=0x0000000000001870 VALUE=0x00000000 UPDATED_VALUE=0x00000000 REG_NAME="JOB_SLOT0_JS_FLUSH_ID_NEXT"
HOST_TIME=1515565849.691304s gpu.INFO_WriteRegister: REG_OFFSET=0x0000000000001860 VALUE=0x00000000 UPDATED_VALUE=0x00000001 REG_NAME="JOB_SLOT0_JS_COMMAND_NEXT"
HOST_TIME=1515565849.691322s gpu.INFO_IrqJobControl: IRQ_ID=0x01 IRQ_NAME="JOB Control" IRQ_STATE=Y
HOST_TIME=1515565849.691561s gpu.INFO_ReadRegister:  REG_OFFSET=0x000000000000100c VALUE=0x00000001 REG_NAME="JOB_IRQ_STATUS"
HOST_TIME=1515565849.691643s gpu.INFO_WriteRegister: REG_OFFSET=0x0000000000001004 VALUE=0x00000000 UPDATED_VALUE=0x00000001 REG_NAME="JOB_IRQ_CLEAR"
HOST_TIME=1515565849.691647s gpu.INFO_IrqJobControl: IRQ_ID=0x01 IRQ_NAME="JOB Control" IRQ_STATE=N
Migrating the target graphics software stack to real hardware

This migration directly integrates the graphics software stack with the GPU register model without deploying the host GPU for rendering the Android graphics. This minimizes the relevance of the host to the target integration and yields a more reliable integration test.

About this task

This is the final integration check. The Generic Graphics Accelerator is disabled so the host GPU is not used. The migration test can expose sequence issues in the target graphics driver.

Before you begin

Make sure that the Android target:

  • Booted with a successful integration between the graphics driver and the GPU model.

  • Passed the other tests as described in this chapter.

  • In the device tree, the GPU is enabled.

Procedure

  1. Use the kill command to quit the current process.
  2. Boot the target with the graphics integration. For details, see Integrating the graphics driver with the GPU model.

    Note:

    When using the boot command, remove --plugin <filepath>/Sidechannel.so to disable the Generic Graphics Accelerator.

    For the command details, see Example: Booting an Android target to verify graphics drivers.

  3. Resolve all issues.
  4. Repeat the above steps until no issue is found.

What to next

Integrate the Android graphics software stack with the real hardware.

Non-ConfidentialPDF file icon PDF version100965_1180_00_en
Copyright © 2014–2019 Arm Limited or its affiliates. All rights reserved.