SSU_DRM使用参考

1. DRM基本概念

1.1. 基本元素

Direct Rendering Manager(DRM)是linux内核子系统，负责管理显示设备。DRM架构将图显系统按照crtc、plane、encoder、connector等进行抽象，用户程序通过框架提供的IOCTL接口将适当的参数设置到各个模块中以完成pipeline的创建，最终将指定的图像显示到指定的显示设备上，基本结构如下图：

模块 描述 sstar
CRTC 对显示buffer进行扫描，并产生时序信号的硬件模块，通常指Display Controller DISP Deivce
ENCODER 负责将CRTC输出的timing时序转换成外部设备所需要的信号的模块，如HDMI转换器或DSI Controller
CONNECTOR 连接物理显示设备的连接器，如HDMI、DisplayPort、DSI总线，通常和Encoder驱动绑定在一起 panel/hdmi ...
PLANE 硬件图层，有的Display硬件支持多层合成显示，但所有的Display Controller至少要有1个plane GWIN（in GOP/MOP layer)
FB Framebuffer，单个图层的显示内容，唯一一个和硬件无关的基本元素
VBLANK 同步机制，通常使用硬件VSYNC来实现
property 任何你想设置的参数，都可以做成property，是DRM驱动中最灵活、最方便的Mode setting机制
DUMB Buffer 只支持连续物理内存，基于kernel中通用CMA API实现，多用于小分辨率简单场景
PRIME Buffer 基于DMA-BUF机制，可以实现buffer共享，多用于大内存复杂场景
fence buffer同步机制，基于内核dma_fence机制实现，用于防止显示内容出现异步问题

1.2. GEM

Graphics Execution Manager（GEM）是用于内核内部管理图形缓冲区的方法之一，GEM为APP提供了显式的内存管理原语。通过GEM用户空间程序可以创建、处理和销毁内存中的内存对象（Bo）。此部分并不涉及具体的硬件实现，在当前的sstar drm中使用的是kernel原生基于CMA的helper接口实现的。

1.3. DRM-Master和DRM-Auth

DRM中有几个ioctl由于并发问题仅限于用户空间单个进程使用，为了实现这种限制，将DRM设备分为Master和Auth。进程也可以通过SET/DROP_MASTER ioctl获取或放弃Master角色，以便其他进程获取Master。参考kernel中drm_ioctl.c文件中drm_ioctls的定义，如：

static const struct drm_ioctl_desc drm_ioctls[] = {
    ...
    DRM_IOCTL_DEF(DRM_IOCTL_SET_MASTER, drm_setmaster_ioctl, 0),
    DRM_IOCTL_DEF(DRM_IOCTL_DROP_MASTER, drm_dropmaster_ioctl, 0),
    ...
    DRM_IOCTL_DEF(DRM_IOCTL_MODE_SETCRTC, drm_mode_setcrtc, DRM_MASTER),
    DRM_IOCTL_DEF(DRM_IOCTL_MODE_GETPLANE, drm_mode_getplane, 0),
    DRM_IOCTL_DEF(DRM_IOCTL_MODE_SETPLANE, drm_mode_setplane, DRM_MASTER),
    ...
    DRM_IOCTL_DEF(DRM_IOCTL_MODE_ATOMIC, drm_mode_atomic_ioctl, DRM_MASTER),
    ...
}

2. libdrm接口说明

DRM驱动加载成功后将生成设备节点/dev/dri/cardX（X为0-15的数），目前所有的ioctl均通过此节点下发到驱动层（暂不考虑/dev/dri/renderX）。在应用程序中通过调用libdrm库的接口可以方便的与驱动程序交互，基本架构如下图：

目前DRM中存在两套接口。

2.1. legacy接口

传统的legacy接口，不同的参数通过不通的ioctl实现。这套接口不能单独修改某一个参数且不易于拓展，在sstar_drm中没有专门对接过，可能实现不完全，不推荐使用。

2.2. atomic接口

atomic接口允许用户只针对某一个特定的参数进行修改且具有原子性，在实现中还可根据实际需要定义客制化的property，使用上较为灵活。

在描述接口的使用之前先介绍使用中最基本的两个元素：property及framebuffer

2.2.1. property描述

所谓Property就是一个个独立的全局属性，通过设置这些属性参数即可完成对显示参数的设置。它主要包括三部分：name、id和value，其中id作为property在DRM框架中全局唯一的标识符，对property的操作均是基于ID来完成的。

有以下几类property：enum/bitmask/range/object/blob

  • Object类型的property，它的值用 drm_mode_object ID来表示。目前的DRM架构中仅用到2个Object Property，它们分别是 "FB_ID" 和 "CRTC_ID" ，它们的property值分别表示framebuffer object ID和crtc object ID。

  • Blob类型的property，它的值用blob object ID来表示。所谓blob，说白了就是一个自定义长度的内存块，用来存放自定义的结构体数据。典型的Blob Property，如 "MODE_ID" ，它的值为blob object ID，drm驱动可以根据该ID找到对应的drm_property_blob结构体，该结构体中存放着modeinfo的相关信息。

property的两种属性：IMMUTABLE/ATOMIC

DRM中的property大多以功能进行划分，kernel框架中定义了一组Standard Properties，这些标准properties在任何正常工作的驱动实现中都会被创建。常见的property有：

CRTC Mandatory

Name Description
ACTIVE CRTC当前的使能状态，一般用于控制CRTC上下电
MODE_ID CRTC当前所使用的display mode ID，通过该ID可以找到具体的display mode配置参数
OUT_FENCE_PTR 输出fence指针，指向当前正在显示的buffer所对应的fence fd，该fence由DRM驱动创建，供上层应用程序使用，用来表示当前buffer CRTC是否还在占用

CRTC Optional

Name Description
DEGAMMA_LUT de-gamma查找表参数
DEGAMMA_LUT_SIZE de-gamma查找表参数长度
GAMMA_LUT gamma查找表参数
GAMMA_LUT_SIZE gamma查找表参数长度
CTM Color Transformation Matrix，颜色矩阵转换参数，3x3的矩阵

PLANE Mandatory

Name Description
type plane的类型，CURSOR、PRIMARY或者OVERLAY
FB_ID 与当前plane绑定的framebuffer object ID
IN_FENCE_FD 与当前plane相关联的input fence fd，由buffer的生产者创建，供DRM底层驱动使用，用来标识当前传下来的buffer是否可以开始访问
CRTC_ID 当前plane所关联的CRTC object ID，与CONNECTOR中的CRTC_ID属性是同一个property
SRC_X 当前framebuffer crop区域的起始偏移x坐标(in 16.16 fixed point)
SRC_Y 当前framebuffer crop区域的起始偏移y坐标(in 16.16 fixed point)
SRC_W 当前framebuffer crop区域的宽度(in 16.16 fixed point)
SRC_H 当前framebuffer crop区域的高度(in 16.16 fixed point)
CRTC_X 屏幕显示区域的起始偏移x坐标
CRTC_Y 屏幕显示区域的起始偏移y坐标
CRTC_W 屏幕显示区域的宽度
CRTC_H 屏幕显示区域的高度

PLANE Optional

Name Description
IN_FORMATS 用于标识特殊的颜色存储格式，如AFBC、IFBC存储格式，该属性为只读
rotation 当前图层的旋转角度
zpos 当前图层在所有图层中的Z轴顺序
alpha 当前图层的global alpha（非pixel alpha），用于多层合成
pixel blend mode 当前图层的合成方式，如Pre-multiplied/Coverage等

CONNECTOR Mandatory

Name Description
CRTC_ID 当前connector所连接的CRTC object ID，与PLANE中CRTC_ID属性是同一个property
link-status 用于标识当前connector的连接状态，如Good/Bad
EDID Extended Display Identification Data，标识显示器的参数信息，是一种VESA标准数据格式
DPMS Display Power Management Signaling，用于控制显示器的电源状态，如休眠唤醒。也是一种VESA标准

2.2.2. framebuffer描述

在 1.1. 基本元素 中有涉及到framebuffer的部分，这部分内容完全由DRM core实现并管理，在sstar drm中没有相应的实现。应用程序中通过addfb接口将bo_handles转换为DRM中可用的framebuffer ID。framebuffer中关键的元素描述如下：

在PLANE的属性中，当SRC_X/Y和CRTC_X/Y不相等时就实现了平移的效果；当SRC_W/H和CRTC_W/H不相等时就实现了缩放的效果；当SRC_W/H和framebuffer的width/height不相等时就实现了裁剪效果。

2.2.3. 应用程序基本流程

在应用程序中通过调用libdrm的接口与驱动层交互，下面将以libdrm自带的modetest测试程序描述应用程序使用的基本流程：

其中legacy flow部分如下：

atomic flow部分如下：

3. PQ设置

  • 编译前更新PQ.bin

    1. Pure linux环境下更新PQ.bin 在Pure linux源码环境下，PQ.bin及相应的QMap文件默认存放于project/board/p5/pqfile目录；调试好的PQ替换到此目录即可

    2. Android源码环境下更新PQ.bin 在Android源码环境下linux的源码位于vendor/sigmastar/alkaid目录，与purelinux类似，将调试好的PQ替换到vendor/sigmastar/alkaid/project/board/p5/pqfile目录即可； 使用sstar_make.sh脚本编译image时会自动将linux源码下的PQ.bin拷贝到device/sigmastar/pioneer5/sdk目录下

  • 替换板端PQ.bin

    DRM驱动将按顺序查找以下文件，直到获取到一个PQ.bin为止，以下路径的PQ.bin均不存在则不加载

    /system/etc/PQ.bin
/vendor/etc/PQ.bin  # Android默认使用此文件
/mnt/logo/PQ.bin
/misc/PQ.bin
/config/PQ.bin
/customer/PQ.bin

    调试时需更新当前设备上使用的PQ.bin的话，只需手动将调试好的PQ文件替换以上路径的文件然后重启即可。如：当前运行Android系统的设备要更新PQ.bin，可在PC机上

    adb root
adb remount
adb push PQ.bin /vendor/etc/PQ.bin

    为确保PQ.bin有写到存储设备中，最好在重启之前执行adb shell sync，之后重启设备。

4. procfs接口说明

4.1. cat

  • 版本信息

    # cat /proc/sstar_drm/version

  • 调试信息

    # cat /proc/sstar_drm/info

  • 调试信息分析

    记录当前scaler的使用状况以及相关属性、可以动态地获取到这些信息，方便调试和测试。

  • 参数说明

    参数 描述
    module info DISP 編號為某DISP ID的CRTC info
    GOP_UI UI device info
    GOP_CURSOR Cursor device info
    MOPG video device info
    MOPS pip video device info
    icfd video decompress device info
    SCL image device info
    BUFFER buffer list info
    DISP Info intf output interface
    start already be commit
    fence device fence ID
    stable intr continue stable interval
    vs last time vsync timestamp
    diff vsync timestamp interval
    Htt H total
    Hsize H active
    Hfb H front porch
    Hpw Hsync width
    Hback H back porch
    Vtt V total
    Vsize V active
    Vfb V front porch
    Vpw Vsync width
    Vback V back porch
    Fps frame per second
    Dclk dot clock
    window Info WinId video window id
    Enable window on/off
    Src_X source image crop in horizontal x point
    Src_Y source image crop in vertical y point
    Src_W source image width (crop)
    Src_H source image height (crop)
    Dst_X image in display layer horizontal x point
    Dst_Y image in display layer vertical y point
    Dst_W Display width
    Dst_H Display height
    Buf_W image width in buffer
    Buf_H image height in buffer
    Stride buffer pitch
    Offset buffer start offset
    compress buffer is compress image
    Format image pixel format
    Tile buffer is tile format image
    Pixel_blend pixel blend type
    Alpha pixel alpha value
    Zpos Z-order value, if -1 means default.
    Plane plane ctx id
    Rotate image rotate degree
    Ifcd Info Enable enable Ifcd
    HalfBlock use half block mode
    SplitBlock use Split block mode
    ColorTrans color format transform
    Format pixel format
    Buf_W buffer width
    Buf_H buffer height
    Scl Info WinId scl Bind disp window Id
    Type scl type (for rotate or others)
    Handler Channel ID
    OutTo Output image bind to disp ID
    Fence scl process count / drop frame count
    Buf_R input buffer address
    Buf_W output buffer address
    Stride buffer pitch (input/output)
    Width Image width(input/output)
    Height Image height(input/output)
    sclsem in scl mutex section
    ch_cnt total scl channel create count
    RotSupport support rotate function or not
    ScSupport support scaling function or not
    RotBindPort Rot need to bind sc port Id
    ScBindPort Scaling need to bind sc port Id
    RotInDevId Use which Rotate Hw Device Id
    ScInDevId Use which RDMA Hw Device Id
    RotIrqEn Rot Isr request count
    ScIrqEn Rdma Isr request count
    BUFFER Info Dev Buffer bind DISP device ID or SCL Id (0x8|scl type)
    Addr buffer address
    Size buffer size
    FenceId buffer fence Id, it's depend on bind target.
    Stm buffer status, with UNBIND/ BIND/ FIRE/ DONE/ READ/ DROP .0 means idle, 1 means act, 2 means wait.
    Plane bind to plane and show plane Id
    Scl bind to scl and show scl Id
    kickTs kick off buffer time stamp
    dmabuf use dmabuf or not
    List buffer bind to list, Write/Read/Plane/Destory

4.2. echo

功能 设置不同DISP_ID，以获取不同的procfs info
命令 echo disp_id > /proc/sstar_drm/info
参数说明 disp_id: disp id
举例 echo 1 > /proc/sstar_drm/info