From de8a46fd6d5ee74507a92a4a6a95e2316e877707 Mon Sep 17 00:00:00 2001
From: Boram Park <boram1288.park@samsung.com>
Date: Fri, 8 Jan 2016 20:56:47 +0900
Subject: [PATCH] doc: add tdm_helper.h to doxygen

Change-Id: I7b972dc4a3ef24238d37212d4e1fbc9720b8721d
---
 doc/Doxyfile         |  1 +
 include/tdm_helper.h | 45 ++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/doc/Doxyfile b/doc/Doxyfile
index 47f90d0..cd3a6a7 100644
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -101,6 +101,7 @@ INPUT                  = \
     doc/tdm_doc.h \
     include/tdm.h \
     include/tdm_backend.h \
+    include/tdm_helper.h \
     include/tdm_list.h \
     include/tdm_log.h \
     include/tdm_types.h
diff --git a/include/tdm_helper.h b/include/tdm_helper.h
index 53955b3..245b7b0 100644
--- a/include/tdm_helper.h
+++ b/include/tdm_helper.h
@@ -52,7 +52,50 @@ extern "C" {
  * be removed.
  * @warning
  * If tdm_helper_drm_fd is more than -1, a tdm backend module @b SHOULDN't call
- * drmWaitVBlank by itself. Moreover, drm events will be handled by ecore_drm.
+ * drmWaitVBlank by itself because a DRM vblank event will be handled in ecore_drm
+ * internally. In this case, a tdm backend module NEVER get a DRM vblank event.
+ * If a tdm backend module need to handle a vendor specific DRM event,
+ * drmAddUserHandler() of libdrm makes possible that a tdm backend module handle
+ * it.
+ * @par Example
+ * @code
+    static int
+    _tdm_drm_user_handler(struct drm_event *event)
+    {
+        if (event->type != DRM_VENDOR_XXX_EVENT)
+            return -1;
+
+        //handling a vendor event
+
+        return 0;
+    }
+
+    ...
+
+    drm_data->drm_fd = -1;
+    if (tdm_helper_drm_fd >= 0)
+    {
+        drm_data->drm_fd = tdm_helper_drm_fd;
+        drmAddUserHandler(tdm_helper_drm_fd, _tdm_drm_user_handler);
+    }
+
+    if (drm_data->drm_fd < 0)
+        drm_data->drm_fd = _tdm_drm_open_drm();
+
+    ...
+
+    drmRemoveUserHandler(tdm_helper_drm_fd, _tdm_drm_user_handler);
+ * @endcode
+ * @code
+    if (tdm_helper_drm_fd == -1)
+    {
+        ...
+        if (drmWaitVBlank(fd, &vbl))
+            return TDM_ERROR_OPERATION_FAILED;
+        ...
+    }
+ * @endcode
+ * @endcode
  * @todo
  */
 extern int tdm_helper_drm_fd;
-- 
2.7.4