terminal: add graphics interface

The grdev layer provides graphics-device access via the
libsystemd-terminal library. It will be used by all terminal helpers to
actually access display hardware.

Like idev, the grdev layer is built around session objects. On each
session object you add/remove graphics devices as they appear and vanish.
Any device type can be supported via specific card-backends. The exported
grdev API hides any device details.

Graphics devices are represented by "cards". Those are hidden in the
session and any pipe-configuration is automatically applied. Out of those,
we configure displays which are then exported to the API user. Displays
are meant as lowest hardware entity available outside of grdev. The
underlying pipe configuration is fully hidden and not accessible from the
outside. The grdev tiling layer allows almost arbitrary setups out of
multiple pipes, but so far we only use a small subset of this. More will
follow.

A grdev-display is meant to represent real connected displays/monitors.
The upper level screen arrangements are user policy and not controlled by
grdev. Applications are free to apply any policy they want.

Real card-backends will follow in later patches.

1 files changed, 182 insertions, 0 deletions

diff --git a/src/libsystemd-terminal/grdev.h b/src/libsystemd-terminal/grdev.h
new file mode 100644
index 0000000000..2645b12113
--- /dev/null
+++ b/src/libsystemd-terminal/grdev.h
@@ -0,0 +1,182 @@
+/*-*- Mode: C; c-basic-offset: 8; indent-tabs-mode: nil -*-*/
+
+/***
+  This file is part of systemd.
+
+  Copyright (C) 2014 David Herrmann <dh.herrmann@gmail.com>
+
+  systemd is free software; you can redistribute it and/or modify it
+  under the terms of the GNU Lesser General Public License as published by
+  the Free Software Foundation; either version 2.1 of the License, or
+  (at your option) any later version.
+
+  systemd is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  Lesser General Public License for more details.
+
+  You should have received a copy of the GNU Lesser General Public License
+  along with systemd; If not, see <http://www.gnu.org/licenses/>.
+***/
+
+/*
+ * Graphics Devices
+ * The grdev layer provides generic access to graphics devices. The device
+ * types are hidden in the implementation and exported in a generic way. The
+ * grdev_session object forms the base layer. It loads, configures and prepares
+ * any graphics devices associated with that session. Each session is totally
+ * independent of other sessions and can be controlled separately.
+ * The target devices on a session are called display. A display always
+ * corresponds to a real display regardless how many pipes are needed to drive
+ * that display. That is, an exported display might internally be created out
+ * of arbitrary combinations of target pipes. However, this is meant as
+ * implementation detail and API users must never assume details below the
+ * display-level. That is, a display is the most low-level object exported.
+ * Therefore, pipe-configuration and any low-level modesetting is hidden from
+ * the public API. It is provided by the implementation, and it is the
+ * implementation that decides how pipes are driven.
+ *
+ * The API users are free to ignore specific displays or combine them to create
+ * larger screens. This often requires user-configuration so is dictated by
+ * policy. The underlying pipe-configuration might be affected by these
+ * high-level policies, but is never directly controlled by those. That means,
+ * depending on the displays you use, it might affect how underlying resources
+ * are assigned. However, users can never directly apply policies to the pipes,
+ * but only to displays. In case specific hardware needs quirks on the pipe
+ * level, we support that via hwdb, not via public user configuration.
+ *
+ * Right now, displays are limited to rgb32 memory-mapped framebuffers on the
+ * primary plane. However, the grdev implementation can be easily extended to
+ * allow more powerful access (including hardware-acceleration for 2D and 3D
+ * compositing). So far, this wasn't needed so it is not exposed.
+ */
+
+#pragma once
+
+#include <drm_fourcc.h>
+#include <inttypes.h>
+#include <stdbool.h>
+#include <stdlib.h>
+#include <systemd/sd-bus.h>
+#include <systemd/sd-event.h>
+#include "util.h"
+
+typedef struct grdev_fb                 grdev_fb;
+typedef struct grdev_display_target     grdev_display_target;
+typedef struct grdev_display            grdev_display;
+
+typedef struct grdev_event              grdev_event;
+typedef struct grdev_session            grdev_session;
+typedef struct grdev_context            grdev_context;
+
+enum {
+        /* clockwise rotation; we treat this is abelian group Z4 with ADD */
+        GRDEV_ROTATE_0                  = 0,
+        GRDEV_ROTATE_90                 = 1,
+        GRDEV_ROTATE_180                = 2,
+        GRDEV_ROTATE_270                = 3,
+};
+
+enum {
+        /* flip states; we treat this as abelian group V4 with XOR */
+        GRDEV_FLIP_NONE                 = 0x0,
+        GRDEV_FLIP_HORIZONTAL           = 0x1,
+        GRDEV_FLIP_VERTICAL             = 0x2,
+};
+
+/*
+ * Displays
+ */
+
+struct grdev_fb {
+        uint32_t width;
+        uint32_t height;
+        uint32_t format;
+        uint64_t age;
+        int32_t strides[4];
+        void *maps[4];
+};
+
+struct grdev_display_target {
+        uint32_t x;
+        uint32_t y;
+        uint32_t width;
+        uint32_t height;
+        unsigned int rotate;
+        unsigned int flip;
+        const grdev_fb *fb;
+};
+
+bool grdev_display_is_enabled(grdev_display *display);
+void grdev_display_enable(grdev_display *display);
+void grdev_display_disable(grdev_display *display);
+
+const grdev_display_target *grdev_display_next_target(grdev_display *display, const grdev_display_target *prev, uint64_t minage);
+void grdev_display_flip_target(grdev_display *display, const grdev_display_target *target, uint64_t age);
+
+#define GRDEV_DISPLAY_FOREACH_TARGET(_display, _t, _minage)                     \
+        for ((_t) = grdev_display_next_target((_display), NULL, (_minage));     \
+             (_t);                                                              \
+             (_t) = grdev_display_next_target((_display), (_t), (_minage)))
+
+/*
+ * Events
+ */
+
+enum {
+        GRDEV_EVENT_DISPLAY_ADD,
+        GRDEV_EVENT_DISPLAY_REMOVE,
+        GRDEV_EVENT_DISPLAY_CHANGE,
+        GRDEV_EVENT_DISPLAY_FRAME,
+};
+
+typedef void (*grdev_event_fn) (grdev_session *session, void *userdata, grdev_event *ev);
+
+struct grdev_event {
+        unsigned int type;
+        union {
+                struct {
+                        grdev_display *display;
+                } display_add, display_remove, display_change;
+
+                struct {
+                        grdev_display *display;
+                } display_frame;
+        };
+};
+
+/*
+ * Sessions
+ */
+
+enum {
+        GRDEV_SESSION_CUSTOM                    = (1 << 0),
+        GRDEV_SESSION_MANAGED                   = (1 << 1),
+};
+
+int grdev_session_new(grdev_session **out,
+                      grdev_context *context,
+                      unsigned int flags,
+                      const char *name,
+                      grdev_event_fn event_fn,
+                      void *userdata);
+grdev_session *grdev_session_free(grdev_session *session);
+
+DEFINE_TRIVIAL_CLEANUP_FUNC(grdev_session*, grdev_session_free);
+
+bool grdev_session_is_enabled(grdev_session *session);
+void grdev_session_enable(grdev_session *session);
+void grdev_session_disable(grdev_session *session);
+
+void grdev_session_commit(grdev_session *session);
+void grdev_session_restore(grdev_session *session);
+
+/*
+ * Contexts
+ */
+
+int grdev_context_new(grdev_context **out, sd_event *event, sd_bus *sysbus);
+grdev_context *grdev_context_ref(grdev_context *context);
+grdev_context *grdev_context_unref(grdev_context *context);
+
+DEFINE_TRIVIAL_CLEANUP_FUNC(grdev_context*, grdev_context_unref);