MI FB DEBUG SOP

REVISION HISTORY

Revision No.
Description
 Date
1.00
  • Initial release
    		•  12/08/2023
    1.01
  • 添加 Pattern模式、带宽调试 及 “水线值”介绍
    		•  12/10/2024

    1. 名词解释

    • disp_path

      MI_FB直接在DISP模块上显示UI和硬件鼠标的方式，FB的图像能够直接通过DISP模块输出到屏幕上，该方式适用于DISP支持GOP硬件的芯片。

    • video_path

      MI_FB通过MI_RGN将FB的画面间接叠加到RGN支持贴OSD的模块上(SCL/VENC/DISP等)，该方式适用于用户想以Framebuffer的方式叠加画面到视频流上或者DISP不支持GOP硬件的芯片。

    • 像素alpha值

      不同颜色格式的像素的alpha分量计算方式不同。MI_FB中的alpha值越小代表越透明，0代表完全透明，最大值代表完全不透明(ARGB1555格式需要是例外)。

      • RGB格式(例如RGB565)像素所有的alpha值默认为255。

      • ARGB格式(例如ARGB8888、ARGB4444、ARGB1555)像素alpha值需要参考像素中alpha分量的bits。ARGB8888像素的alpha分量占bit[24:31]共8bits，取值范围是0-255；ARGB4444像素的alpha分量占bit[12:15]共4bits，取值范围是0-15；ARGB1555像素的alpha分量占bit[15]共1bit，取值范围是0-1，bit[15] = 0的像素实际像素alpha值等于alpha属性中"alpha0"的值，bit[15] = 1的像素实际像素alpha值等于alpha属性中"alpha1"的值。

      • Index格式(例如I2、I4、I8)像素值只存储了Index，具体的ARGB值需要查表"Cmap"("video_path"时，FB 的Cmap不能设置，用户需要设置MI_RGN的palette table来替代)来确定，"Cmap"中的格式为ARGB8888，其中alpha分量有8bits，取值范围是0-255。

    • 水线值

      GOP硬件使用DMA FIFO来缓存MIU返回的数据，并从DMA FIFO中读数据去显示。FIFO中缓存的数据默认有一个阈值，称为“水线值”。 当FIFO中剩余的数据小于等于“水线值”时，GOP硬件会再次向MIU发请求，获得新的数据。正常显示情况下无需调整“水线值”。

      • “水线值”越大，FIFO 中数据不易被取空，UI不易显示错位/闪烁。

      • “水线值”越小，FIFO 中数据容易被取空，UI容易显示错位/闪烁。

    2. FB常见问题

    2.1. mi_fb.ko加载失败

    • 确认问题步骤：

      1. 查看加载mi_fb.ko失败的日志，确认失败类型：

        (1). 日志：insmod: can't insert '/xxx/mi_fb.ko': unknown symbol in module or invalid parameter

        (2). 日志：Must support at least one disp path, please check memuconfig config

        (3). 日志：parsing ini config failed

    • 出现"unknown symbol"日志的原因

      缺少mi_fb.ko依赖，需要进一步获取Linux的kmsg的log才能知道具体缺少那些依赖。cat /proc/kmsg

      缺少symbol类型 示例 原因 解决方式
      Linux framebuffer框架 register_framebuffer、framebuffer_alloc ... Linux framebuffer框架被编译成模块(fb.ko)并且fb.ko没有在mi_fb.ko之前加载。 加载mi_fb.ko之前先加载fb.ko或者把Linux framebuffer框架编译进内核里。
      DISP MHAL_DISP_DeviceGetInstance、MHAL_DISP_DeviceGetDisplayInfo ... 没有先加载mi_disp.ko。 加载mi_fb.ko之前先加载mi_disp.ko；或者关闭fb的"disp_path"(如果用户不需要在DISP模块上显示FB UI)。
      RGN mi_rgn_GetWinInstance、MHAL_RGN_GetInternalApis 没有先加载mi_rgn.ko。 加载mi_fb.ko之前先加载mi_rgn.ko；如果只提示缺少mi_rgn_GetWinInstance且用户不需要在DISP以外的模块上显示FB UI，可以选择关闭fb的"video_path"。

    • 出现"please check menuconfig config"日志的原因

      编译MI_FB时"disp_path"和"video_path"都没有打开。MI_FB要求编译时必须至少打开"disp_path"或"video_path"中的一个选项。

    • 出现"parsing ini config failed"日志的原因

      MI_FB的配置文件config.json不存在或者配置失败。请用户检查配置文件，如有需要可联系FAE协助.

    2.2. FB UI不显示

    • 确认问题步骤：

      EXP：MI_FB /dev/fb0 UI没有显示出来。

      1. 获取FB proc信息(cat /proc/mi_modules/mi_fb/mi_fbX "X即fb设备的副设备号")，以下是部分内容。

        从以上proc信息可以看出：

        (1). "xres"、"yres"、"xres_virtual"、"yres_virtual"、"xoffset"、"yoffset"等属性确认UI的宽高分别为512x300，且UI显示的内容在整张framebuffer的[0, 0]位置。

        (2). "Show"属性为TRUE，如果该属性为FALSE时FB UI不会显示。

        (3). "colorFmt"属性为ARGB8888，代表UI的颜色格式为ARGB8888格式。注：Pcupid 不支持 I8/I4/I2 格式

        (4). "Alpha Info"中"Channel"属性为1，代表透明模式为像素模式；"Invert"为0，代没有打开透明反转。如果像素的alpha分量为0，FB UI就不会显示。

        (5). "ColorKey Info"属性的"Enable"为0，代表没有使能ColorKey功能。如果使能了ColorKey且指定的颜色与FB UI像素的颜色一致，那部分像素就不会显示。

      2. 保存framebuffer到文件

        cmd cp /dev/fbX [path]/[file name]

        执行完后会在指定的[path]路径下生成名为[file name]的文件，推荐使用软件《7yuv》打开文件查看画面。如果用户没有把UI画到framebuffer的正确区域UI是无法正常显示的，如果UI像素对应的alpha分量最后表达的透明值为0(透明值接近0是UI也可能看不清楚)，那么UI就不会显示出来。

      3. 设置 UI PATTERN 模式

        (1). 查看 PATTERN 支持情况

        cat /proc/mi_modules/mi_rgn/debug_hal/gop_patgen

        (2). 设置 PATTERN 模式

        如：echo 3 0 1 0 0xc 0xff > /proc/mi_modules/mi_rgn/debug_hal/gop_patgen

        参数介绍请参阅 PATTERN

        (3). 设置(2)中PATTERN，将会看到如下的UI图像

    • 出现UI不显示的原因

      proc信息 原因 解决方式
      "xres"、"yres"、"xres_virtual"、"yres_virtual" 框定的区域尺寸不符合用户预期。 如果用户不会调用ioctl FBIOPAN_DISPLAY、FBIOPUT_VSCREENINFO或FBIOSET_DISPLAYLAYER_ATTRIBUTES去修改framebuffer屏幕尺寸，那么需要用户去修改MI_FB的配置文件config.json中的"fb_width"和"fb_height"("xres"和"xres_virtual"的默认值为"fb_width"，"yres"的默认值为"fb_height"，"yres_virtual"不小于"yres")；如果用户会在打开fb之后去修改屏幕尺寸，需要用户去检查参数是否有误。
      "xoffset"、"yoffset" 可见屏幕偏移位置不在用户更新framebuffer的位置。 需要用户确认调用ioctl FBIOPAN_DISPLAY的参数是否有误。
      "Show" UI显示属性为FALSE。 需要用户确认调用ioctl FBIOSET_SHOW的参数是否有误。可以通过echo命令快捷修改(cmd echo SHOW GUI [enable] > /proc/mi_modules/mi_fb/mi_fbX)
      "colorFmt"和"Alpha Info" 像素alpha属性最终表达值接近0。 这类情况需要结合用户保存的framebuffer文件一起分析(参考步骤2)。"Channel"属性为1时，透明模式为像素模式，该模式下用户需要确认每个像素的像素alpha值(参考本文"1. 名词解释"中"像素alpha值")；"Channel"为0时，透明模式为全局模式，该模式下用户需要确认"GlobalAlphaValue"的值。然后确定透明反转的属性，如果"Invert"属性为1，代表打开了透明反转，实际透明值 = 255 - 当前透明值。最后计算出的实际透明值如果接近0，FB UI将不显示。如果确定是该原因，用户需要调整alpha属性(全局模式 cmd echo GLOBAL_ALPHA GUI [GlobalAlpha] > /proc/mi_modules/mi_fb/mi_fbx。像素模式且颜色格式为ARGB1555时 cmd echo ALPHA01 GUI [alpha0] [alpha1] > /proc/mi_modules/mi_fb/mi_fbX)或者UI的alpha分量。
      "ColorKey Info" ColorKey使能且指定的颜色与用户UI的颜色一致(一般是UI部分消失)。 关闭colorkey功能(cmd echo COLORKEY GUI 0 0 0 0 > /proc/mi_modules/mi_fb/mi_fbX)，或者调整colorkey指定的颜色(cmd echo COLORKEY GUI 1 [R] [G] [B] > /proc/mi_modules/mi_fb/mi_fbX)或者UI的颜色。

    2.3. FB UI颜色异常

    • 确认问题步骤：

      1. 获取FB proc信息(cat /proc/mi_modules/mi_fb/mi_fbX "X即fb设备的副设备号")，以下是部分内容。

    • 出现问题的原因

      1. 用户没有使用正确颜色格式的UI。

      2. cmap设定没有成功。("video_path"时，FB 的Cmap不能设置，用户需要设置MI_RGN的palette table来替代)

      3. config.json 配置项中 "fb_hwlayer_dst" 和 "fb_hwlayer_outputcolor" 不匹配。

        (1). 默认 DISP 视频层只开启第一个颜色空间转换单元，此时需确认 "fb_hwlayer_outputcolor = 0" 即可。

        (2). 若 DISP 视频层只开启第二个颜色空间转换单元，此时需满足条件:

        a. "fb_hwlayer_dst = 3" 且 "fb_hwlayer_outputcolor = 1"

        b. "fb_hwlayer_dst = 12" 且 "fb_hwlayer_outputcolor = 0"

    2.4. FB UI 出现错位/闪烁异常

    • 问题现象：

      从屏幕中可以看到 UI 出现错位/闪烁现象。

      如 UI 出现错位

    • 确认问题步骤：

      1. 针对UI： cp /dev/fbX [path]/[file name] 保存ui图像到文件。

      2. 确认保存的图像文件是否符合预期。（无错位/撕裂）

      3. 打开 PATTERN ，切换不同的 MODE，选择受带宽影响(with-bw)和不受带宽影响(no-bw)两种模式进行测试。若 with-bw 模式和 no-bw 模式，UI 均显示异常，则可暂时排除带宽问题；若 with-bw 模式 UI 显示异常，no-bw 模式 UI 显示正常，则可确认是带宽问题。PATTERN 使用方法可参考FB UI不显示 部分。

    • 出现问题原因：

      1. 带宽不足，GOP 抢不到带宽。

      2. GOP硬件 DMA FIFO 中数据被取空，MIU 返回的数据还未存入 DMA FIFO 中，导致没有足够的数据用来显示。

    • 解决方法：

      1. 可尝试使用更加单一的场景来调试确认是否带宽问题，如有需要可寻求FAE的协助

      2. 修改 GOP DMA Threshold

        (1). 查看当前 “水线值”

        cat /proc/mi_modules/mi_rgn/debug_hal/gop_waterline

        (2). 修改“水线值”

        当前UI默认水线值都为 0xc0，可适当增大水线值。若尝试多个更大的“水线值”仍无效，可排除 DMA FIFO 问题。

        UI 修改示例: echo 3 0 1 0 0x3c0 > /proc/mi_modules/mi_rgn/debug_hal/gop_waterline

        参数介绍请参阅 水线值

    3. 相关参数介绍

    3.1 PATTERN

    TARGET: 目标模块，Pcupid 只支持 DISP_UI，取值: 3

    ID: GOP id， DISP_UI 只有1个GOP，取值: 0

    ENABLE: 是否开启 PATTERN 模式。取值: [0,1]，0表示关闭，1示开启

    MODE: 是否受带宽影响。取值: [0,1]，0表示受带宽影响(with-bw)，1表示不受带宽影响 (no-bw)

    SELECT: 图案模式 id，取值: [0-f]

    ALPHA_VALUE: 透明度，取值: [0-ff]

    3.2 “水线值”

    TARGET: 目标模块，Pcupid 只支持DISP_UI，取值: 3

    ID: GOP id， DISP_UI 只有1个GOP，取值：0

    ENABLE: 是否显示配置信息，取值：[0/1]，0表示不显示，1表示

    URGENT: 是否拉高 GOP urgent 信号，取值：[0/1]，0表示未urgent信号，1表示拉高urgent信号

    DMA_THRESHOLD_VALUE: 水线值，取值：[0-0x3ff]