gralloc: Add foreign buffer usage flag

Adds GRALLOC_USAGE_FOREIGN_BUFFERS, which a consumer may set as a usage
flag if it intends to attach buffers that it has not detached from the
BufferQueue. It provides a hint to the producer (who may query the
consumer usage bits) that it may receive a buffer from another
BufferQueue, so that it can exit during initialization, hopefully with a
meaningful error message, if such buffers are not supported.

Also adds GRALLOC_USAGE_ALLOC_MASK, which is applied to usage bits
before calling alloc on the gralloc module, and prevents the module from
seeing GRALLOC_USAGE_FOREIGN_BUFFERS, since that usage flag is of no use
while allocating buffers.

Bug: 19801661
Change-Id: I17b927de94245f4df7cfd3f4483b544da3e9cd35

include/hardware/gralloc.h

@@ -127,6 +127,17 @@ enum {
     /* buffer may be used as a cursor */
     GRALLOC_USAGE_CURSOR                = 0x00008000,
 
+    /* Set by the consumer to indicate to the producer that they may attach a
+     * buffer that they did not detach from the BufferQueue. Will be filtered
+     * out by GRALLOC_USAGE_ALLOC_MASK, so gralloc modules will not need to
+     * handle this flag. */
+    GRALLOC_USAGE_FOREIGN_BUFFERS       = 0x00010000,
+
+    /* Mask of all flags which could be passed to a gralloc module for buffer
+     * allocation. Any flags not in this mask do not need to be handled by
+     * gralloc modules. */
+    GRALLOC_USAGE_ALLOC_MASK            = ~(GRALLOC_USAGE_FOREIGN_BUFFERS),
+
     /* implementation-specific private usage flags */
     GRALLOC_USAGE_PRIVATE_0             = 0x10000000,
     GRALLOC_USAGE_PRIVATE_1             = 0x20000000,