gralloc: Add asynchronous lock/unlock API

The existing API exposed to clients for software lock/unlock forces the gralloc
implementation to complete these operations synchronously. This change adds new
entry points for lock/unlock functionality that is suited for use with Android's
explicit synchronisation concept. This provides scope for the gralloc module
to internally optimise the work it must do for lock/unlock and to hide this cost
from the client.

Change-Id: If4b1bb5490ab2b20d796214a7da8a96427cfe52d

1 files changed, 50 insertions, 1 deletions

diff --git a/include/hardware/gralloc.h b/include/hardware/gralloc.h
index 0dbebcf..e7d0103 100644
--- a/include/hardware/gralloc.h
+++ b/include/hardware/gralloc.h
@@ -44,10 +44,14 @@ __BEGIN_DECLS
  *
  * GRALLOC_MODULE_API_VERSION_0_2:
  * Add support for flexible YCbCr format with (*lock_ycbcr)() method.
+ *
+ * GRALLOC_MODULE_API_VERSION_0_3:
+ * Add support for fence passing to/from lock/unlock.
  */
 
 #define GRALLOC_MODULE_API_VERSION_0_1  HARDWARE_MODULE_API_VERSION(0, 1)
 #define GRALLOC_MODULE_API_VERSION_0_2  HARDWARE_MODULE_API_VERSION(0, 2)
+#define GRALLOC_MODULE_API_VERSION_0_3  HARDWARE_MODULE_API_VERSION(0, 3)
 
 #define GRALLOC_DEVICE_API_VERSION_0_1  HARDWARE_DEVICE_API_VERSION(0, 1)
 
@@ -241,8 +245,53 @@ typedef struct gralloc_module_t {
             int l, int t, int w, int h,
             struct android_ycbcr *ycbcr);
 
+    /*
+     * The (*lockAsync)() method is like the (*lock)() method except
+     * that the buffer's sync fence object is passed into the lock
+     * call instead of requiring the caller to wait for completion.
+     *
+     * The gralloc implementation takes ownership of the fenceFd and
+     * is responsible for closing it when no longer needed.
+     *
+     * Added in GRALLOC_MODULE_API_VERSION_0_3.
+     */
+    int (*lockAsync)(struct gralloc_module_t const* module,
+            buffer_handle_t handle, int usage,
+            int l, int t, int w, int h,
+            void** vaddr, int fenceFd);
+
+    /*
+     * The (*unlockAsync)() method is like the (*unlock)() method
+     * except that a buffer sync fence object is returned from the
+     * lock call, representing the completion of any pending work
+     * performed by the gralloc implementation.
+     *
+     * The caller takes ownership of the fenceFd and is responsible
+     * for closing it when no longer needed.
+     *
+     * Added in GRALLOC_MODULE_API_VERSION_0_3.
+     */
+    int (*unlockAsync)(struct gralloc_module_t const* module,
+            buffer_handle_t handle, int* fenceFd);
+
+    /*
+     * The (*lockAsync_ycbcr)() method is like the (*lock_ycbcr)()
+     * method except that the buffer's sync fence object is passed
+     * into the lock call instead of requiring the caller to wait for
+     * completion.
+     *
+     * The gralloc implementation takes ownership of the fenceFd and
+     * is responsible for closing it when no longer needed.
+     *
+     * Added in GRALLOC_MODULE_API_VERSION_0_3.
+     */
+    int (*lockAsync_ycbcr)(struct gralloc_module_t const* module,
+            buffer_handle_t handle, int usage,
+            int l, int t, int w, int h,
+            struct android_ycbcr *ycbcr, int fenceFd);
+
     /* reserved for future use */
-    void* reserved_proc[6];
+    void* reserved_proc[3];
 } gralloc_module_t;
 
 /*****************************************************************************/