diff --git a/docs/common/ai/cubie/_g2d-usage-guide.mdx b/docs/common/ai/cubie/_g2d-usage-guide.mdx
index 53d1ce237..5fc9c6f58 100644
--- a/docs/common/ai/cubie/_g2d-usage-guide.mdx
+++ b/docs/common/ai/cubie/_g2d-usage-guide.mdx
@@ -261,3 +261,9 @@ gcc -o g2d_rotation g2d_rotation.c
 - **目标分辨率应与源配合**，旋转 90° 时宽高互换
 - **格式转换**（如 RGB → YUV）由 G2D 硬件完成，源和目标 format 字段分别设置即可
 - **调试时**，失败返回 `-1`，`errno` 记录具体原因，用 `perror()` 打印
+
+### 关于 2.0 接口与 1.0 接口
+
+本文档示例默认使用 G2D 2.0 接口（`G2D_CMD_BITBLT_H`，结构体 `g2d_blt_h`）。部分系统（如某些旧版镜像或特定内核配置）下，2.0 接口可能返回 "Operation not permitted" 或 "G2D irq pending flag timeout" 错误。
+
+如遇此情况，可尝试改用 G2D 1.0 接口（`G2D_CMD_BITBLT`，结构体 `g2d_blt`）作为兼容方案。两者的主要区别在于结构体字段命名（`flag_h`/`src_image_h` 等 2.0 专用字段在 1.0 结构体中对应名称不同），请参考头文件 `/usr/include/bsp/linux/sunxi-g2d.h` 中 `g2d_blt` 的定义。
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/common/ai/cubie/_g2d-usage-guide.mdx b/i18n/en/docusaurus-plugin-content-docs/current/common/ai/cubie/_g2d-usage-guide.mdx
index 86ce04c01..84ae6b153 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/common/ai/cubie/_g2d-usage-guide.mdx
+++ b/i18n/en/docusaurus-plugin-content-docs/current/common/ai/cubie/_g2d-usage-guide.mdx
@@ -263,3 +263,9 @@ Rotation flags: `G2D_ROT_0` / `G2D_ROT_90` / `G2D_ROT_180` / `G2D_ROT_270` / `G2
 - **Target resolution should match source**, width and height swap when rotating 90°
 - **Format conversion** (e.g. RGB → YUV) is done by G2D hardware, just set source and destination format fields separately
 - **For debugging**, failure returns `-1`, `errno` records specific reason, use `perror()` to print
+
+### About 2.0 Interface vs 1.0 Interface
+
+The examples in this guide use the G2D 2.0 interface by default (`G2D_CMD_BITBLT_H`, struct `g2d_blt_h`). On some systems (such as certain older images or specific kernel configurations), the 2.0 interface may return "Operation not permitted" or "G2D irq pending flag timeout" errors.
+
+If you encounter this situation, you can try using the G2D 1.0 interface (`G2D_CMD_BITBLT`, struct `g2d_blt`) as a compatible fallback. The main difference between the two is the struct field naming (`flag_h`/`src_image_h` etc. are 2.0-specific fields that have different names in the 1.0 struct). Refer to the header file `/usr/include/bsp/linux/sunxi-g2d.h` for the `g2d_blt` definition.