《DRM 专栏》| Atomic 接口的应用程序

刘盼

发布于 2022-06-10 16:44:28

3.2K0

发布于 2022-06-10 16:44:28

通过前面的文章，我们学习了如何编写一个最基本的 DRM 应用程序。但是，这些程序所使用的接口，在如今的 DRM 架构中其实早已经被标记为 Legacy（过时的）接口了，而目前 DRM 主要推荐使用的是 Atomic（原子的）接口。让我们进入 Atomic 接口应用程序的介绍。

Property

Property（属性）是 Atomic 操作必须依赖的基本元素。所谓 Property，其实就是把上篇的 legacy 接口传入的参数单独抽出来，做成一个个独立的全局属性。通过设置这些属性参数，即可完成对显示参数的设置。

Property 的结构简单概括主要由3部分组成：name、id 和 value。其中 id 为该 property 在 DRM 框架中全局唯一的标识符。

采用property机制的好处是：

减少上层应用接口的维护工作量。当开发者有新的功能需要添加时，无需增加新的函数名和IOCTL，只需在底层驱动中新增一个property，然后在自己的应用程序中获取/操作该property的值即可。
增强了参数设置的灵活性。一次IOCTL可以同时设置多个property，减少了user space与kernel space切换的次数，同时最大限度的满足了不同硬件对于参数设置的要求，提高了软件效率。

DRM 中的 property 大多以功能进行划分，并且还定义了一组 Standard Properties，这些标准 properties 在任何平台上都会被创建。

下表列出了应用程序开发中，常用的 property：

CRTC

PLANE

CONNECTOR

Property Type

Property 的类型分为如下几种：

enum
bitmask
range
signed range
object
blob

以上类型中需要着重介绍的是 object 和 blob 类型，其它类型看名字就知道什么意思，所以就不做介绍了。

object

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

blob

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

概念图

总结

DRM 的 Property，其实有点类似于 kernel 中的 sysfs 属性节点。DRM 驱动将 kernel 层的重要参数通过 property 机制导出给上层，使得上层应用可以采用统一的接口形式来修改 property 的值，从而实现参数的传递，而无需新增额外的 IOCTL 接口。

atomic-crtc DRM 应用程序

上面我们学习了 Property 的基本概念及作用，现在一起来学习如何操作这些 Property，即 libdrm Atomic 接口的用法。

Atomic

为什么叫“Atomic Commit”？

初学者第一次接触到 DRM 时，总会好奇当初开发者为什么要起 Atomic 这个名字。Wiki 上关于该名词有较详细的解释，如果大家感兴趣可以点击链接查看。我这里用白话简单概括就是：本次 commit 操作，要么成功，要么保持原来的状态不变。即如果中途操作失败了，那些已经生效的配置需要恢复成之前的状态，就像没发生过 commit 操作似的，这就是 Atomic 的含义。

而用 Commit 一词，是因为本次操作可能会修改到多个参数，等修改好这些参数后，再一次性发起操作请求，有点类似与填表后“提交”材料的意思。

如何操作 property？

在上一篇我们了解了 property 的基本组成结构，即 name、id 和 value。因此操作 property 就变得非常简单，通过 name 来获取 property，通过 id 来操作 property，通过 value 来修改 property 的值。而完成这些操作的应用接口，就是 libdrm 提供的 Atomic 接口。

需要记住一点，在libdrm中，所有的操作都是以Object ID来进行访问的，因此要操作property，首先需要获取该property的Object ID。

伪代码：

int main(void)
{
    ...
 drmSetClientCap(DRM_CLIENT_CAP_ATOMIC);

 drmModeObjectGetProperties(...);
 drmModeGetProperty(property_id)
 ...
 drmModeAtomicAlloc();
 drmModeAtomicAddProperty(..., property_id, property_value);
 drmModeAtomicCommit(...);
 drmModeAtomicFree();
    ...
}

首先通过 drmModeGetProperty() 来获取 property 的相关信息，然后通过 drmModeAtomicAddProperty() 来修改 property 的值，最后通过 drmModeAtomicCommit() 来发起真正的修改请求。

为什么要设置 DRM_CLIENT_CAP_ATOMIC ？

凡是被 DRM_MODE_PROP_ATOMIC 修饰过的 property，只有在 drm 应用程序支持 Atomic 操作时才可见，否则该 property 对应用程序不可见。因此通过设置 DRM_CLIENT_CAP_ATOMIC 这个 flag，来告知 DRM 驱动该应用程序支持 Atomic 操作。

基于之前的 plane-test 的参考代码，我们使用 Atomic 接口来替代原来的 drmModeSetCrtc() 接口，从而通过差异对比来学些 Atomic 接口的操作。

#define _GNU_SOURCE
#include <errno.h>
#include <fcntl.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/mman.h>
#include <time.h>
#include <unistd.h>
#include <xf86drm.h>
#include <xf86drmMode.h>

struct buffer_object {
 uint32_t width;
 uint32_t height;
 uint32_t pitch;
 uint32_t handle;
 uint32_t size;
 uint8_t *vaddr;
 uint32_t fb_id;
};

struct buffer_object buf;

static int modeset_create_fb(int fd, struct buffer_object *bo)
{
 struct drm_mode_create_dumb create = {};
  struct drm_mode_map_dumb map = {};

 create.width = bo->width;
 create.height = bo->height;
 create.bpp = 32;
 drmIoctl(fd, DRM_IOCTL_MODE_CREATE_DUMB, &create);

 bo->pitch = create.pitch;
 bo->size = create.size;
 bo->handle = create.handle;
 drmModeAddFB(fd, bo->width, bo->height, 24, 32, bo->pitch,
      bo->handle, &bo->fb_id);

 map.handle = create.handle;
 drmIoctl(fd, DRM_IOCTL_MODE_MAP_DUMB, &map);

 bo->vaddr = mmap(0, create.size, PROT_READ | PROT_WRITE,
   MAP_SHARED, fd, map.offset);

 memset(bo->vaddr, 0xff, bo->size);

 return 0;
}

static void modeset_destroy_fb(int fd, struct buffer_object *bo)
{
 struct drm_mode_destroy_dumb destroy = {};

 drmModeRmFB(fd, bo->fb_id);

 munmap(bo->vaddr, bo->size);

 destroy.handle = bo->handle;
 drmIoctl(fd, DRM_IOCTL_MODE_DESTROY_DUMB, &destroy);
}

static uint32_t get_property_id(int fd, drmModeObjectProperties *props,
    const char *name)
{
 drmModePropertyPtr property;
 uint32_t i, id = 0;

 /* find property according to the name */
 for (i = 0; i < props->count_props; i++) {
  property = drmModeGetProperty(fd, props->props[i]);
  if (!strcmp(property->name, name))
   id = property->prop_id;
  drmModeFreeProperty(property);

  if (id)
   break;
 }

 return id;
}

int main(int argc, char **argv)
{
 int fd;
 drmModeConnector *conn;
 drmModeRes *res;
 drmModePlaneRes *plane_res;
 drmModeObjectProperties *props;
 drmModeAtomicReq *req;
 uint32_t conn_id;
 uint32_t crtc_id;
 uint32_t plane_id;
 uint32_t blob_id;
 uint32_t property_crtc_id;
 uint32_t property_mode_id;
 uint32_t property_active;

 fd = open("/dev/dri/card0", O_RDWR | O_CLOEXEC);

 res = drmModeGetResources(fd);
 crtc_id = res->crtcs[0];
 conn_id = res->connectors[0];

 drmSetClientCap(fd, DRM_CLIENT_CAP_UNIVERSAL_PLANES, 1);
 plane_res = drmModeGetPlaneResources(fd);
 plane_id = plane_res->planes[0];

 conn = drmModeGetConnector(fd, conn_id);
 buf.width = conn->modes[0].hdisplay;
 buf.height = conn->modes[0].vdisplay;

 modeset_create_fb(fd, &buf);

 drmSetClientCap(fd, DRM_CLIENT_CAP_ATOMIC, 1);

 /* get connector properties */
 props = drmModeObjectGetProperties(fd, conn_id, DRM_MODE_OBJECT_CONNECTOR);
 property_crtc_id = get_property_id(fd, props, "CRTC_ID");
 drmModeFreeObjectProperties(props);

 /* get crtc properties */
 props = drmModeObjectGetProperties(fd, crtc_id, DRM_MODE_OBJECT_CRTC);
 property_active = get_property_id(fd, props, "ACTIVE");
 property_mode_id = get_property_id(fd, props, "MODE_ID");
 drmModeFreeObjectProperties(props);

 /* create blob to store current mode, and retun the blob id */
 drmModeCreatePropertyBlob(fd, &conn->modes[0],
    sizeof(conn->modes[0]), &blob_id);

 /* start modeseting */
 req = drmModeAtomicAlloc();
 drmModeAtomicAddProperty(req, crtc_id, property_active, 1);
 drmModeAtomicAddProperty(req, crtc_id, property_mode_id, blob_id);
 drmModeAtomicAddProperty(req, conn_id, property_crtc_id, crtc_id);
 drmModeAtomicCommit(fd, req, DRM_MODE_ATOMIC_ALLOW_MODESET, NULL);
 drmModeAtomicFree(req);

 printf("drmModeAtomicCommit SetCrtc\n");
 getchar();

 drmModeSetPlane(fd, plane_id, crtc_id, buf.fb_id, 0,
   50, 50, 320, 320,
   0, 0, 320 << 16, 320 << 16);

 printf("drmModeSetPlane\n");
 getchar();

 modeset_destroy_fb(fd, &buf);

 drmModeFreeConnector(conn);
 drmModeFreePlaneResources(plane_res);
 drmModeFreeResources(res);

 close(fd);

 return 0;
}

通过上面的代码我们可以看出，原来的 drmModeSetCrtc(crtc_id, fb_id, conn_id, &mode) 被下面这部分代码取代了：

 req = drmModeAtomicAlloc();
 drmModeAtomicAddProperty(req, crtc_id, property_active, 1);
 drmModeAtomicAddProperty(req, crtc_id, property_mode_id, blob_id);
 drmModeAtomicAddProperty(req, conn_id, property_crtc_id, crtc_id);
 drmModeAtomicCommit(fd, req, DRM_MODE_ATOMIC_ALLOW_MODESET, NULL);
 drmModeAtomicFree(req);

虽然代码量增加了，但是应用程序的灵活性和可扩展性也增强了。

由于以上代码没有添加对 fb_id 的操作，因此它的作用只是初始化 CRTC/ENCODER/CONNECTOR 硬件，以及建立硬件链路的连接关系，并不会显示 framebuffer 的内容，即保持黑屏状态。framebuffer 的显示将由后面的 drmModeSetPlane() 操作来完成。

运行结果:

注意：程序运行之前，请确保没有其它应用或服务占用/dev/dri/card0节点，否则将出现 Permission Denied 错误。

描述：

程序运行后，屏幕显示黑色，终端打印“drmModeAtomicCommit”信息，表明当前已经初始化好CRTC/ENCODER/CONNECTOR硬件；
输入回车后，屏幕显示framebuffer的crop区域，同时终端打印“drmModeSetPlane”信息；
再次输入回车，显示黑屏，程序退出。

atomic-plane DRM 应用程序

上面我们学习了如何通过 libdrm 的 atomic 接口实现 modeseting 的操作。这里我们一起来学习如何通过 atomic 接口实现 drmModeSetPlane() 相同的操作。

Atomic Commit

plane update的atomic操作如下：

drmModeAtomicAddProperty(req, plane_id, property_crtc_id, crtc_id);
drmModeAtomicAddProperty(req, plane_id, property_fb_id, fb_id);
drmModeAtomicAddProperty(req, plane_id, property_crtc_x, crtc_x);
drmModeAtomicAddProperty(req, plane_id, property_crtc_y, crtc_y);
drmModeAtomicAddProperty(req, plane_id, property_crtc_w, crtc_w);
drmModeAtomicAddProperty(req, plane_id, property_crtc_h, crtc_h);
drmModeAtomicAddProperty(req, plane_id, property_src_x, src_x);
drmModeAtomicAddProperty(req, plane_id, property_src_y, src_y);
drmModeAtomicAddProperty(req, plane_id, property_src_w, src_w << 16);
drmModeAtomicAddProperty(req, plane_id, property_src_h, src_h << 16);
drmModeAtomicCommit(fd, req, flags, NULL);

以上各项参数与 drmModeSetPlane() 的参数一一对应：

drmModeSetPlane(fd, plane_id, crtc_id, fb_id, flags,
                crtc_x, crtc_y, crtc_w, crtc_h,
                src_x << 16, src_y << 16, src_w << 16, src_h << 16)

其中，参数 flags 可以是如下值的组合：

DRM_MODE_PAGE_FLIP_EVENT: 请求底层驱动发送PAGE_FLIP事件，上层应用需要调用 drmHandleEvent() 来接收并处理相应事件。
DRM_MODE_ATOMIC_TEST_ONLY: 仅用于试探本次commit操作是否能成功，不会操作真正的硬件寄存器。不能和 DRM_MODE_PAGE_FLIP_EVENT 同时使用。
DRM_MODE_ATOMIC_NONBLOCK: 允许本次commit操作异步执行，即无需等待上一次commit操作彻底执行完成，就可以发起本次操作。drmModeAtomicCommit() 默认以BLOCK（同步）方式执行。
DRM_MODE_ATOMIC_ALLOW_MODESET: 告诉底层驱动，本次commit操作修改到了modeseting相关的参数，需要执行一次full modeset动作。

当然，flags 参数为0也是可以的。

drmModeAtomicCommit() 与 drmModeSetPlane() 对比，具有如下优势：

参考代码

基于上面 atomic-crtc 程序，我们使用 atomic 接口替换 drmModeSetPlane() 函数，具体如下：

#define _GNU_SOURCE
#include <errno.h>
#include <fcntl.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/mman.h>
#include <time.h>
#include <unistd.h>
#include <xf86drm.h>
#include <xf86drmMode.h>

struct buffer_object {
 uint32_t width;
 uint32_t height;
 uint32_t pitch;
 uint32_t handle;
 uint32_t size;
 uint8_t *vaddr;
 uint32_t fb_id;
};

struct buffer_object buf;

static int modeset_create_fb(int fd, struct buffer_object *bo)
{
 struct drm_mode_create_dumb create = {};
  struct drm_mode_map_dumb map = {};

 create.width = bo->width;
 create.height = bo->height;
 create.bpp = 32;
 drmIoctl(fd, DRM_IOCTL_MODE_CREATE_DUMB, &create);

 bo->pitch = create.pitch;
 bo->size = create.size;
 bo->handle = create.handle;
 drmModeAddFB(fd, bo->width, bo->height, 24, 32, bo->pitch,
      bo->handle, &bo->fb_id);

 map.handle = create.handle;
 drmIoctl(fd, DRM_IOCTL_MODE_MAP_DUMB, &map);

 bo->vaddr = mmap(0, create.size, PROT_READ | PROT_WRITE,
   MAP_SHARED, fd, map.offset);

 memset(bo->vaddr, 0xff, bo->size);

 return 0;
}

static void modeset_destroy_fb(int fd, struct buffer_object *bo)
{
 struct drm_mode_destroy_dumb destroy = {};

 drmModeRmFB(fd, bo->fb_id);

 munmap(bo->vaddr, bo->size);

 destroy.handle = bo->handle;
 drmIoctl(fd, DRM_IOCTL_MODE_DESTROY_DUMB, &destroy);
}

static uint32_t get_property_id(int fd, drmModeObjectProperties *props,
    const char *name)
{
 drmModePropertyPtr property;
 uint32_t i, id = 0;

 for (i = 0; i < props->count_props; i++) {
  property = drmModeGetProperty(fd, props->props[i]);
  if (!strcmp(property->name, name))
   id = property->prop_id;
  drmModeFreeProperty(property);

  if (id)
   break;
 }

 return id;
}

int main(int argc, char **argv)
{
 int fd;
 drmModeConnector *conn;
 drmModeRes *res;
 drmModePlaneRes *plane_res;
 drmModeObjectProperties *props;
 drmModeAtomicReq *req;
 uint32_t conn_id;
 uint32_t crtc_id;
 uint32_t plane_id;
 uint32_t blob_id;
 uint32_t property_crtc_id;
 uint32_t property_mode_id;
 uint32_t property_active;
 uint32_t property_fb_id;
 uint32_t property_crtc_x;
 uint32_t property_crtc_y;
 uint32_t property_crtc_w;
 uint32_t property_crtc_h;
 uint32_t property_src_x;
 uint32_t property_src_y;
 uint32_t property_src_w;
 uint32_t property_src_h;

 fd = open("/dev/dri/card0", O_RDWR | O_CLOEXEC);

 res = drmModeGetResources(fd);
 crtc_id = res->crtcs[0];
 conn_id = res->connectors[0];

 drmSetClientCap(fd, DRM_CLIENT_CAP_UNIVERSAL_PLANES, 1);
 plane_res = drmModeGetPlaneResources(fd);
 plane_id = plane_res->planes[0];

 conn = drmModeGetConnector(fd, conn_id);
 buf.width = conn->modes[0].hdisplay;
 buf.height = conn->modes[0].vdisplay;

 modeset_create_fb(fd, &buf);

 drmSetClientCap(fd, DRM_CLIENT_CAP_ATOMIC, 1);

 props = drmModeObjectGetProperties(fd, conn_id, DRM_MODE_OBJECT_CONNECTOR);
 property_crtc_id = get_property_id(fd, props, "CRTC_ID");
 drmModeFreeObjectProperties(props);

 props = drmModeObjectGetProperties(fd, crtc_id, DRM_MODE_OBJECT_CRTC);
 property_active = get_property_id(fd, props, "ACTIVE");
 property_mode_id = get_property_id(fd, props, "MODE_ID");
 drmModeFreeObjectProperties(props);

 drmModeCreatePropertyBlob(fd, &conn->modes[0],
    sizeof(conn->modes[0]), &blob_id);

 req = drmModeAtomicAlloc();
 drmModeAtomicAddProperty(req, crtc_id, property_active, 1);
 drmModeAtomicAddProperty(req, crtc_id, property_mode_id, blob_id);
 drmModeAtomicAddProperty(req, conn_id, property_crtc_id, crtc_id);
 drmModeAtomicCommit(fd, req, DRM_MODE_ATOMIC_ALLOW_MODESET, NULL);
 drmModeAtomicFree(req);

 printf("drmModeAtomicCommit SetCrtc\n");
 getchar();

    /* get plane properties */
 props = drmModeObjectGetProperties(fd, plane_id, DRM_MODE_OBJECT_PLANE);
 property_crtc_id = get_property_id(fd, props, "CRTC_ID");
 property_fb_id = get_property_id(fd, props, "FB_ID");
 property_crtc_x = get_property_id(fd, props, "CRTC_X");
 property_crtc_y = get_property_id(fd, props, "CRTC_Y");
 property_crtc_w = get_property_id(fd, props, "CRTC_W");
 property_crtc_h = get_property_id(fd, props, "CRTC_H");
 property_src_x = get_property_id(fd, props, "SRC_X");
 property_src_y = get_property_id(fd, props, "SRC_Y");
 property_src_w = get_property_id(fd, props, "SRC_W");
 property_src_h = get_property_id(fd, props, "SRC_H");
 drmModeFreeObjectProperties(props);

    /* atomic plane update */
 req = drmModeAtomicAlloc();
 drmModeAtomicAddProperty(req, plane_id, property_crtc_id, crtc_id);
 drmModeAtomicAddProperty(req, plane_id, property_fb_id, buf.fb_id);
 drmModeAtomicAddProperty(req, plane_id, property_crtc_x, 50);
 drmModeAtomicAddProperty(req, plane_id, property_crtc_y, 50);
 drmModeAtomicAddProperty(req, plane_id, property_crtc_w, 320);
 drmModeAtomicAddProperty(req, plane_id, property_crtc_h, 320);
 drmModeAtomicAddProperty(req, plane_id, property_src_x, 0);
 drmModeAtomicAddProperty(req, plane_id, property_src_y, 0);
 drmModeAtomicAddProperty(req, plane_id, property_src_w, 320 << 16);
 drmModeAtomicAddProperty(req, plane_id, property_src_h, 320 << 16);
 drmModeAtomicCommit(fd, req, 0, NULL);
 drmModeAtomicFree(req);

 printf("drmModeAtomicCommit SetPlane\n");
 getchar();

 modeset_destroy_fb(fd, &buf);

 drmModeFreeConnector(conn);
 drmModeFreePlaneResources(plane_res);
 drmModeFreeResources(res);

 close(fd);

 return 0;
}

提示：

上面的两次 drmModeAtomicCommit() 操作可以合并成一次；
无需频繁调用 drmModeAtomicAlloc() 、drmModeAtomicFree() ，可以在第一次 commit 之前Alloc，在最后一次 commit 之后 free，也没问题；
plane update操作时，可以只add发生变化的property，其它未发生变化的properties即使没有被add，在commit时底层驱动仍然会取上一次的值来配置硬件寄存器。

运行结果:

注意：程序运行之前，请确保没有其它应用或服务占用/dev/dri/card0节点，否则将出现 Permission Denied 错误。

描述：

程序运行后，屏幕显示黑色，终端打印“drmModeAtomicCommit SetCrtc”信息，表明当前已经初始化好CRTC/ENCODER/CONNECTOR硬件；
输入回车后，屏幕显示framebuffer的crop区域，同时终端打印“drmModeAtomicCommit SetPlane”；
再次输入回车，显示黑屏，程序退出。

5T技术资源大放送！包括但不限于：C/C++，Arm, Linux，Android，人工智能，单片机，树莓派，等等。在上面的【人人都是极客】公众号内回复「peter」，即可免费获取！！

记得点击分享、赞和在看，给我充点儿电吧

本文参与腾讯云自媒体分享计划，分享自微信公众号。

原始发表：2022-06-10，如有侵权请联系 cloudcommunity@tencent.com 删除

tcp/ip

本文分享自人人都是极客微信公众号，前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体分享计划，欢迎热爱写作的你一起参与！

tcp/ip

登录后参与评论

0 条评论

热度