Introduce HWC_DEVICE_API_VERSION_1_0

The new version adds an acquire and release fence to each layer,
providing explicit producer->hwc and hwc->producer synchronization.

Change-Id: Ibd6e3c7b3515c012c767246e6d6514274fdef01d

1 files changed, 80 insertions, 42 deletions

diff --git a/include/hardware/hwcomposer.h b/include/hardware/hwcomposer.h
index 98e665c..4af5c69 100644
--- a/include/hardware/hwcomposer.h
+++ b/include/hardware/hwcomposer.h
@@ -30,11 +30,25 @@ __BEGIN_DECLS
 
 /*****************************************************************************/
 
-// for compatibility
+/* for compatibility */
 #define HWC_MODULE_API_VERSION      HWC_MODULE_API_VERSION_0_1
 #define HWC_DEVICE_API_VERSION      HWC_DEVICE_API_VERSION_0_1
 #define HWC_API_VERSION             HWC_DEVICE_API_VERSION
 
+/* Users of this header can define HWC_REMOVE_DEPRECATED_VERSIONS to test that
+ * they still work with just the current version declared, before the
+ * deprecated versions are actually removed.
+ *
+ * To find code that still depends on the old versions, set the #define to 1
+ * here. Code that explicitly sets it to zero (rather than simply not defining
+ * it) will still see the old versions.
+ */
+#if !defined(HWC_REMOVE_DEPRECATED_VERSIONS)
+#define HWC_REMOVE_DEPRECATED_VERSIONS 0
+#endif
+
+/*****************************************************************************/
+
 /**
  * The id of this module
  */
@@ -45,21 +59,8 @@ __BEGIN_DECLS
  */
 #define HWC_HARDWARE_COMPOSER   "composer"
 
-
-struct hwc_composer_device;
-
-/*
- * availability: HWC_DEVICE_API_VERSION_0_3
- *
- * struct hwc_methods cannot be embedded in other structures as
- * sizeof(struct hwc_methods) cannot be relied upon.
- *
- */
-typedef struct hwc_methods {
-
-    /*************************************************************************
-     * HWC_DEVICE_API_VERSION_0_3
-     *************************************************************************/
+struct hwc_composer_device_1;
+typedef struct hwc_methods_1 {
 
     /*
      * eventControl(..., event, enabled)
@@ -76,9 +77,9 @@ typedef struct hwc_methods {
      */
 
     int (*eventControl)(
-            struct hwc_composer_device* dev, int event, int enabled);
+            struct hwc_composer_device_1* dev, int event, int enabled);
 
-} hwc_methods_t;
+} hwc_methods_1_t;
 
 typedef struct hwc_rect {
     int left;
@@ -99,7 +100,7 @@ typedef struct hwc_color {
     uint8_t a;
 } hwc_color_t;
 
-typedef struct hwc_layer {
+typedef struct hwc_layer_1 {
     /*
      * initially set to HWC_FRAMEBUFFER or HWC_BACKGROUND.
      * HWC_FRAMEBUFFER
@@ -158,10 +159,46 @@ typedef struct hwc_layer {
              * The visible region INCLUDES areas overlapped by a translucent layer.
              */
             hwc_region_t visibleRegionScreen;
+
+            /* Sync fence object that will be signaled when the buffer's
+             * contents are available. May be -1 if the contents are already
+             * available. This field is only valid during set(), and should be
+             * ignored during prepare(). The set() call must not wait for the
+             * fence to be signaled before returning, but the HWC must wait for
+             * all buffers to be signaled before reading from them.
+             *
+             * The HWC takes ownership of the acquireFenceFd and is responsible
+             * for closing it when no longer needed.
+             */
+            int acquireFenceFd;
+
+            /* During set() the HWC must set this field to a file descriptor for
+             * a sync fence object that will signal after the HWC has finished
+             * reading from the buffer. The field is ignored by prepare(). Each
+             * layer should have a unique file descriptor, even if more than one
+             * refer to the same underlying fence object; this allows each to be
+             * closed independently.
+             *
+             * If buffer reads can complete at significantly different times,
+             * then using independent fences is preferred. For example, if the
+             * HWC handles some layers with a blit engine and others with
+             * overlays, then the blit layers can be reused immediately after
+             * the blit completes, but the overlay layers can't be reused until
+             * a subsequent frame has been displayed.
+             *
+             * The HWC client taks ownership of the releaseFenceFd and is
+             * responsible for closing it when no longer needed.
+             */
+            int releaseFenceFd;
         };
     };
-} hwc_layer_t;
 
+    /* Allow for expansion w/o breaking binary compatibility.
+     * Pad layer to 96 bytes, assuming 32-bit pointers.
+     */
+    int32_t reserved[24 - 18];
+
+} hwc_layer_1_t;
 
 /*
  * hwc_layer_list_t::flags values
@@ -169,7 +206,8 @@ typedef struct hwc_layer {
 enum {
     /*
      * HWC_GEOMETRY_CHANGED is set by SurfaceFlinger to indicate that the list
-     * passed to (*prepare)() has changed by more than just the buffer handles.
+     * passed to (*prepare)() has changed by more than just the buffer handles
+     * and acquire fences.
      */
     HWC_GEOMETRY_CHANGED = 0x00000001,
 };
@@ -178,11 +216,11 @@ enum {
  * List of layers.
  * The handle members of hwLayers elements must be unique.
  */
-typedef struct hwc_layer_list {
+typedef struct hwc_layer_list_1 {
     uint32_t flags;
     size_t numHwLayers;
-    hwc_layer_t hwLayers[0];
-} hwc_layer_list_t;
+    hwc_layer_1_t hwLayers[0];
+} hwc_layer_list_1_t;
 
 /* This represents a display, typically an EGLDisplay object */
 typedef void* hwc_display_t;
@@ -237,8 +275,7 @@ typedef struct hwc_module {
     struct hw_module_t common;
 } hwc_module_t;
 
-
-typedef struct hwc_composer_device {
+typedef struct hwc_composer_device_1 {
     struct hw_device_t common;
 
     /*
@@ -264,8 +301,8 @@ typedef struct hwc_composer_device {
      * returned, SurfaceFlinger will assume that none of the layer will be
      * handled by the HWC.
      */
-    int (*prepare)(struct hwc_composer_device *dev, hwc_layer_list_t* list);
-
+    int (*prepare)(struct hwc_composer_device_1 *dev,
+                    hwc_layer_list_1_t* list);
 
     /*
      * (*set)() is used in place of eglSwapBuffers(), and assumes the same
@@ -309,16 +346,17 @@ typedef struct hwc_composer_device {
      *    Another code for non EGL errors.
      *
      */
-    int (*set)(struct hwc_composer_device *dev,
+    int (*set)(struct hwc_composer_device_1 *dev,
                 hwc_display_t dpy,
                 hwc_surface_t sur,
-                hwc_layer_list_t* list);
+                hwc_layer_list_1_t* list);
+
     /*
      * This field is OPTIONAL and can be NULL.
      *
      * If non NULL it will be called by SurfaceFlinger on dumpsys
      */
-    void (*dump)(struct hwc_composer_device* dev, char *buff, int buff_len);
+    void (*dump)(struct hwc_composer_device_1* dev, char *buff, int buff_len);
 
     /*
      * This field is OPTIONAL and can be NULL.
@@ -333,18 +371,17 @@ typedef struct hwc_composer_device {
      * Any of the callbacks can be NULL, in which case the corresponding
      * functionality is not supported.
      */
-    void (*registerProcs)(struct hwc_composer_device* dev,
+    void (*registerProcs)(struct hwc_composer_device_1* dev,
             hwc_procs_t const* procs);
 
     /*
      * This field is OPTIONAL and can be NULL.
-     * availability: HWC_DEVICE_API_VERSION_0_2
      *
      * Used to retrieve information about the h/w composer
      *
      * Returns 0 on success or -errno on error.
      */
-    int (*query)(struct hwc_composer_device* dev, int what, int* value);
+    int (*query)(struct hwc_composer_device_1* dev, int what, int* value);
 
     /*
      * Reserved for future use. Must be NULL.
@@ -353,28 +390,29 @@ typedef struct hwc_composer_device {
 
     /*
      * This field is OPTIONAL and can be NULL.
-     * availability: HWC_DEVICE_API_VERSION_0_3
      */
-    hwc_methods_t const *methods;
-
-} hwc_composer_device_t;
+    hwc_methods_1_t const *methods;
 
+} hwc_composer_device_1_t;
 
 /** convenience API for opening and closing a device */
 
-static inline int hwc_open(const struct hw_module_t* module,
-        hwc_composer_device_t** device) {
+static inline int hwc_open_1(const struct hw_module_t* module,
+        hwc_composer_device_1_t** device) {
     return module->methods->open(module,
             HWC_HARDWARE_COMPOSER, (struct hw_device_t**)device);
 }
 
-static inline int hwc_close(hwc_composer_device_t* device) {
+static inline int hwc_close_1(hwc_composer_device_1_t* device) {
     return device->common.close(&device->common);
 }
 
-
 /*****************************************************************************/
 
+#if !HWC_REMOVE_DEPRECATED_VERSIONS
+#include <hardware/hwcomposer_v0.h>
+#endif
+
 __END_DECLS
 
 #endif /* ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H */