Writing-DRI-Engine-Driver-for-Your-GPU.md

-_Writing a driver of the DRI engine for your GPU._
\ No newline at end of file
+_Writing a driver of the DRI engine for your GPU._
+
+Table of Contents
+
+- [Overview](#overview)
+  * [Compile-time configuration](#compile-time-configuration)
+  * [Run-time configuration](#run-time-configuration)
+  * [Implement DRI driver](#implement-dri-driver)
+  * [Restrictions](#restrictions)
+- [Example](#example)
+
+## Overview
+
+In order to support modern graphics card or GPU, we introduced a
+new NEWGAL engine of `dri`. The developer can use this engine to
+run MiniGUI apps on a Linux box on which the DRI
+(Direct Rendering Infrastructure) is enabled.
+
+The `dri` engine uses `libdrm` developed by Free Desktop project:
+
+https://dri.freedesktop.org/wiki/
+
+Libdrm is a user-space library implements the Direct Rendering Manager.
+MiniGUI mainly uses this library to support the dumb frame buffer
+(no hardware acceleration). However, you can write a driver for your
+graphics card or GPU to implement the hardware accelerated features.
+
+To avoid modifying the MiniGUI source code when supporting a new GPU,
+the `dri` engine has adopted a scalable design:
+
+* You can directly use the `dri` engine to run MiniGUI on a GPU
+which supports dumb frame buffer.
+* When you want to take advantage of the hardware acceleration of
+your GPU, you can write some code for your GPU as a sub driver
+of `dri` engine outside MiniGUI.
+
+This document describes how to enable `dri` engine and write a
+hardware-accelerated driver for your own GPU.
+
+Note that, generally, the driver will be implemented by the GPU
+or SoC vendors. The MiniGUI app developers do not need to
+care about this.
+
+### Compile-time configuration
+
+There are two configure options related to the `dri` engine:
+
+* `--enable-videodri` enables the `dri` engine, and `--disable-videodri`
+  disables the `dri` engine. Note that the `dri` engine is only
+  available on Linux, and you need to install the `libdrm` 2.4 or later
+  first.
+* `--with-targetname=external`. When you configure MiniGUI with this
+  option. MiniGUI will use the external function `__dri_ex_driver_get`
+  to initialize the DRI driver. If you do not implement this function,
+  the link will fail.
+
+### Run-time configuration
+
+For `dri` engine, we introduce a new section in MiniGUI runtime
+configuration:
+
+```
+[dri]
+defaultmode=1024x768-32bpp
+dpi=96
+pixelformat=XR24
+device=/dev/dri/card0
+```
+
+You can use the key `dri.device` to specify your DRI device.
+
+You can use the key `dri.pixelformat` to specify the DRM pixel format for the
+screen. We use DRM fourcc code to defined the pixel format of the screen
+surface. For more information, please see `<drm/drm_fourcc.h>` header file.
+Note that only 8/16/24/32 bpp RGB formats are supported. For example, `XR24`
+means `X8R8G8B8` pixel format.
+
+### Implement DRI driver
+
+The header file `<minigui/exstubs.h>` defines the operators (a set of
+callback functions) you need to implement for your GPU externally.
+
+To exploit the GPU's accelerated rendering capabilities, a MiniGUI app
+can use `cairo` and/or `OpenGL ES` to assist in rendering 2D/3D graphics
+when using the `dri` engine. We will provide some samples in `mg-tests`
+or `mg-samples` for this purpose.
+
+### Restrictions
+
+In version 4.0.0, the `dri` NEWGAL engine does not provide support for
+MiniGUI-Processes run-time mode. We will enhance this in the subsequent
+version of MiniGUI.
+
+Also note that when you use the hardware accelerated sub driver, MiniGUI app
+may need the root privilege to call `drmSetMaster` to set the video mode.
+However, under MiniGUI-Processes run-time mode, only the server (`mginit`) will
+need this privilege when you use the future `dri` engine.
+
+## Example
+
+As an example, we implement the sub driver for `i915` graphics chard
+in `mg-tests/dri-engine/`. Please refer to `mg-tests` repository:
+
+https://github.com/VincentWei/mg-tests/tree/master/dri-engine
+