前言
在上一篇《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() 操作來完成。
運行結果
以上代碼運行的效果如下（模擬效果）：
描述：
- 程序運行後，屏幕顯示黑色，終端打印“drmModeAtomicCommit”信息，表明當前已經初始化好CRTC/ENCODER/CONNECTOR硬件；
- 輸入回車後，屏幕顯示framebuffer的crop區域，同時終端打印“drmModeSetPlane”信息；
- 再次輸入回車，顯示黑屏，程序退出。
在《最簡單的DRM應用程序（plane-test）》文章中曾強調過，drmModeSetPlane() 調用之前，必須先調用drmModeSetCrtc() 初始化底層硬件，否則plane設置將無效。而通過上面的程序運行結果可以證明，drmModeAtomicCommit() 操作同樣可以初始化底層硬件。
源碼下載
參考資料
Wiki: Atomic Commit
LWN: Atomic mode setting design overview, part 1, part2
Android libdrm: modeset.c