MI FB DEBUG SOP

REVISION HISTORY¶

Revision No.	Description	Date
1.00	Initial release	12/08/2023
1.01	Added Pattern mode, bandwidth debugging, and "waterline value" introduction	12/10/2024

1. Glossary¶

disp_path

The method by which MI_FB directly displays the UI and hardware mouse on the DISP module, allowing the FB image to be directly output to the screen through the DISP module. This method is suitable for chips that support GOP hardware.
video_path

MI_FB indirectly overlays the FB image onto modules that support OSD (SCL/VENC/DISP, etc.) through MI_RGN. This method is suitable for users who want to overlay images onto video streams in a framebuffer manner or for chips that do not support GOP hardware.
Pixel alpha value

The calculation method for the alpha component of pixels in different color formats varies. A smaller alpha value in MI_FB represents more transparency, with 0 being completely transparent and the maximum value being completely opaque (ARGB1555 format is an exception).
- For RGB formats (e.g., RGB565), all pixel alpha values default to 255.
- For ARGB formats (e.g., ARGB8888, ARGB4444, ARGB1555), the pixel alpha values need to reference the bits of the alpha component in the pixel. The alpha component of ARGB8888 pixels occupies bits [24:31] for a total of 8 bits, with a range of 0-255; the alpha component of ARGB4444 pixels occupies bits [12:15] for a total of 4 bits, with a range of 0-15; the alpha component of ARGB1555 pixels occupies bit [15] for a total of 1 bit, with a range of 0-1. For pixels where bit [15] = 0, the actual pixel alpha value equals the value of "alpha0" in the alpha attribute, and for pixels where bit [15] = 1, the actual pixel alpha value equals the value of "alpha1" in the alpha attribute.
- For Index formats (e.g., I2, I4, I8), the pixel value only stores the Index, and the specific ARGB value needs to be looked up in the "Cmap" table (when using "video_path," the FB's Cmap cannot be set; the user needs to set the MI_RGN's palette table instead). The format in "Cmap" is ARGB8888, where the alpha component has 8 bits, with a range of 0-255.
Waterline value

GOP hardware uses DMA FIFO to cache data returned from MIU and reads data from the DMA FIFO for display. The data cached in the FIFO has a default threshold known as the "waterline value." When the remaining data in the FIFO is less than or equal to the "waterline value," the GOP hardware will request new data from MIU. There is no need to adjust the "waterline value" under normal display conditions.
- A larger "waterline value" makes it less likely for the data in the FIFO to be depleted, reducing the chances of UI misalignment or flickering.
- A smaller "waterline value" makes it easier for the data in the FIFO to be depleted, increasing the chances of UI misalignment or flickering.

2. Common FB Issues¶

2.1. mi_fb.ko Load Failure¶

Confirmation Steps:
1. Check the log for the failure of loading mi_fb.ko to confirm the type of failure:
  
  (1). Log: insmod: can't insert '/xxx/mi_fb.ko': unknown symbol in module or invalid parameter
  
  (2). Log: Must support at least one disp path, please check menuconfig config
  
  (3). Log: parsing ini config failed

Reasons for "unknown symbol" log

Missing dependencies for mi_fb.ko; further retrieval of Linux kmsg logs is needed to know which dependencies are missing. cat /proc/kmsg

Missing symbol type	Example	Reason	Solution
Linux framebuffer framework	`register_framebuffer`, `framebuffer_alloc`, ...	The Linux framebuffer framework is compiled as a module (fb.ko) and fb.ko has not been loaded before mi_fb.ko.	Load fb.ko before mi_fb.ko or compile the Linux framebuffer framework into the kernel.
DISP	`MHAL_DISP_DeviceGetInstance`, `MHAL_DISP_DeviceGetDisplayInfo`, ...	mi_disp.ko has not been loaded first.	Load mi_disp.ko before mi_fb.ko; or disable fb's "disp_path" (if the user does not need to display FB UI on the DISP module).
RGN	`mi_rgn_GetWinInstance`, `MHAL_RGN_GetInternalApis`	mi_rgn.ko has not been loaded first.	Load mi_rgn.ko before mi_fb.ko; if only `mi_rgn_GetWinInstance` is missing and the user does not need to display FB UI outside of DISP, they can choose to disable fb's "video_path".

Reasons for "please check menuconfig config" log

Both "disp_path" and "video_path" were not enabled during the compilation of MI_FB. MI_FB requires that at least one of the "disp_path" or "video_path" options be enabled during compilation.
Reasons for "parsing ini config failed" log

The configuration file for MI_FB, config.json, does not exist or has failed. Please check the configuration file, and if necessary, contact FAE for assistance.

2.2. FB UI Not Displaying¶

Confirmation Steps:

EXP: MI_FB /dev/fb0 UI is not displayed.
1. Obtain FB proc information (cat /proc/mi_modules/mi_fb/mi_fbX where "X is the minor device number of the fb device"), here is some content.
  
  From the above proc information, it can be seen that:
  
  (1). The attributes "xres", "yres", "xres_virtual", "yres_virtual", "xoffset", "yoffset", etc., confirm that the UI width and height are 512x300, and the content displayed by the UI is at the [0, 0] position of the entire framebuffer.
  
  (2). The "Show" attribute is TRUE; if this attribute is FALSE, the FB UI will not display.
  
  (3). The "colorFmt" attribute is ARGB8888, indicating that the UI color format is ARGB8888 format. Note: Pcupid does not support I8/I4/I2 formats.
  
  (4). In "Alpha Info," the "Channel" attribute is 1, indicating that the transparency mode is pixel mode; "Invert" is 0, indicating that transparency inversion is not enabled. If the alpha component of the pixel is 0, the FB UI will not display.
  
  (5). The "ColorKey Info" attribute's "Enable" is 0, indicating that the ColorKey function is not enabled. If ColorKey is enabled and the specified color matches the FB UI pixel color, that portion of the pixel will not display.
2. Save framebuffer to file
  
  cmd cp /dev/fbX [path]/[file name]
  
  After execution, a file named [file name] will be generated in the specified [path]. It is recommended to use the software "7yuv" to open the file and view the image. If the user has not drawn the UI in the correct area of the framebuffer, the UI will not display correctly. If the final expressed transparency value of the UI pixel's corresponding alpha component is 0 (a transparency value close to 0 may also make the UI difficult to see), then the UI will not display.
3. Set UI PATTERN mode
  
  (1). Check PATTERN support
  
  cat /proc/mi_modules/mi_rgn/debug_hal/gop_patgen
  
  (2). Set PATTERN mode
  
  For example: echo 3 0 1 0 0xc 0xff > /proc/mi_modules/mi_rgn/debug_hal/gop_patgen
  
  For parameter introduction, please refer to PATTERN
  
  (3). Setting the PATTERN in (2) will show the following UI image

Reasons for UI not displaying

proc information	Reason	Solution
"xres", "yres", "xres_virtual", "yres_virtual"	The defined area size does not meet user expectations.	If the user does not call ioctl `FBIOPAN_DISPLAY`, `FBIOPUT_VSCREENINFO`, or `FBIOSET_DISPLAYLAYER_ATTRIBUTES` to modify the framebuffer screen size, the user needs to modify the "fb_width" and "fb_height" in MI_FB's configuration file `config.json` ("xres" and "xres_virtual" default to "fb_width", "yres" defaults to "fb_height", "yres_virtual" must be greater than or equal to "yres"); if the user modifies the screen size after opening fb, they need to check if the parameters are incorrect.
"xoffset", "yoffset"	The visible screen offset position is not at the user's updated framebuffer position.	The user needs to confirm whether the parameters for calling ioctl `FBIOPAN_DISPLAY` are incorrect.
"Show"	UI display attribute is FALSE.	The user needs to confirm whether the parameters for calling ioctl `FBIOSET_SHOW` are incorrect. This can be quickly modified using the echo command (cmd `echo SHOW GUI [enable] > /proc/mi_modules/mi_fb/mi_fbX`)
"colorFmt" and "Alpha Info"	The final expressed value of the pixel alpha attribute is close to 0.	This situation needs to be analyzed in conjunction with the framebuffer file saved by the user (refer to step 2). When the "Channel" attribute is 1, the transparency mode is pixel mode, and in this mode, the user needs to confirm the pixel alpha value of each pixel (refer to "Pixel alpha value" in "1. Glossary" of this document); when "Channel" is 0, the transparency mode is global mode, and in this mode, the user needs to confirm the value of "GlobalAlphaValue." Then determine the transparency inversion attribute; if the "Invert" attribute is 1, it indicates that transparency inversion is enabled, and the actual transparency value = 255 - current transparency value. Finally, if the calculated actual transparency value is close to 0, the FB UI will not display. If this is confirmed to be the reason, the user needs to adjust the alpha attribute (for global mode cmd `echo GLOBAL_ALPHA GUI [GlobalAlpha] > /proc/mi_modules/mi_fb/mi_fbx`. For pixel mode and color format ARGB1555 cmd `echo ALPHA01 GUI [alpha0] [alpha1] > /proc/mi_modules/mi_fb/mi_fbX`) or the UI's alpha component.
"ColorKey Info"	ColorKey is enabled and the specified color matches the user's UI color (usually part of the UI disappears).	Disable the colorkey function (cmd `echo COLORKEY GUI 0 0 0 0 > /proc/mi_modules/mi_fb/mi_fbX`), or adjust the color specified by the colorkey (cmd `echo COLORKEY GUI 1 [R] [G] [B] > /proc/mi_modules/mi_fb/mi_fbX`) or the UI color.

2.3. FB UI Color Abnormalities¶

Confirmation Steps:
1. Obtain FB proc information (cat /proc/mi_modules/mi_fb/mi_fbX where "X is the minor device number of the fb device"), here is some content.
Reasons for the issue
1. The user did not use the UI with the correct color format.
2. The cmap setting was not successful. (When using "video_path," the FB's Cmap cannot be set; the user needs to set the MI_RGN's palette table instead)
3. The configuration items "fb_hwlayer_dst" and "fb_hwlayer_outputcolor" in config.json do not match.
  
  (1). By default, the DISP video layer only enables the first color space conversion unit, at which point "fb_hwlayer_outputcolor = 0" must be confirmed.
  
  (2). If the DISP video layer only enables the second color space conversion unit, the following conditions must be met:
  
  a. "fb_hwlayer_dst = 3" and "fb_hwlayer_outputcolor = 1"
  
  b. "fb_hwlayer_dst = 12" and "fb_hwlayer_outputcolor = 0"

2.4. FB UI Misalignment/Flickering Issues¶

Problem Phenomenon:

The UI appears misaligned/flickering on the screen.

For example, if the UI appears misaligned
Confirmation Steps:
1. For the UI: cp /dev/fbX [path]/[file name] save the UI image to a file.
2. Confirm whether the saved image file meets expectations. (No misalignment/tearing)
3. Open PATTERN, switch between different MODES, and test both bandwidth-affected (with-bw) and unaffected (no-bw) modes. If both with-bw and no-bw modes show UI abnormalities, bandwidth issues can be temporarily ruled out; if the with-bw mode shows UI abnormalities while the no-bw mode displays normally, it can be confirmed as a bandwidth issue. For the usage of PATTERN, please refer to the FB UI Not Displaying section.
Reasons for the issue:
1. Insufficient bandwidth, GOP cannot obtain bandwidth.
2. Data in the GOP hardware DMA FIFO has been depleted, and the data returned from MIU has not yet been stored in the DMA FIFO, resulting in insufficient data for display.
Solutions:
1. Try using a simpler scenario to debug and confirm whether it is a bandwidth issue; if necessary, seek assistance from FAE.
2. Modify the GOP DMA Threshold
  
  (1). Check the current "waterline value"
  
  cat /proc/mi_modules/mi_rgn/debug_hal/gop_waterline
  
  (2). Modify the "waterline value"
  
  The current default waterline value for the UI is 0xc; it can be appropriately increased. If trying several larger "waterline values" still does not work, the DMA FIFO issue can be ruled out.
  
  Example of modifying UI: echo 3 0 1 0 0x3c0 > /proc/mi_modules/mi_rgn/debug_hal/gop_waterline
  
  For parameter introduction, please refer to Waterline Value

3.1 PATTERN¶

TARGET: Target module, Pcupid only supports DISP_UI, value: 3

ID: GOP id, DISP_UI has only one GOP, value: 0

ENABLE: Whether to enable PATTERN mode. Value: [0,1], 0 means off, 1 means on

MODE: Whether affected by bandwidth. Value: [0,1], 0 means affected by bandwidth (with-bw), 1 means not affected by bandwidth (no-bw)

SELECT: Pattern mode id, value: [0-f]

ALPHA_VALUE: Transparency, value: [0-ff]

3.2 "Waterline Value"¶