DRM应用程序进阶 （atomic-crtc）

前言

在上一篇《DRM应用程序进阶（Property）》中，我们学习了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应用程序进阶（Property）》中有介绍过，凡是被DRM_MODE_PROP_ATOMIC修饰过的property，只有在drm应用程序支持Atomic操作时才可见，否则该property对应用程序不可见。因此通过设置DRM_CLIENT_CAP_ATOMIC这个flag，来告知DRM驱动该应用程序支持Atomic操作。

参考代码

基于之前的《最简单的DRM应用程序（plane-test）》的参考代码，我们使用Atomic接口来替代原来的drmModeSetCrtc()接口，从而通过差异对比来学些Atomic接口的操作。

modeset-atomic-crtc.c

#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 错误。

描述：

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

在《最简单的DRM应用程序（plane-test）》文章中曾强调过，drmModeSetPlane() 调用之前，必须先调用drmModeSetCrtc() 初始化底层硬件，否则plane设置将无效。而通过上面的程序运行结果可以证明，drmModeAtomicCommit() 操作同样可以初始化底层硬件。

源码下载

modeset-atomic-crtc

参考资料

Wiki: Atomic Commit
LWN: Atomic mode setting design overview, part 1, part2
Android libdrm: modeset.c

文章汇总： DRM (Direct Rendering Manager) 学习简介