Add HAL definition for graphics buffer allocator
It differs from gralloc1.h in that
- buffer descriptors are created from a struct, BufferDescriptorInfo, to
reduce round trips
- testAllocate is a function of its own
- buffer allocation and export are two different steps
- reference counting and buffer mapping are moved to gralloc-mapper
- BAD_HANDLE is renamed to BAD_BUFFER
- GRALLOC1_CONSUMER_USAGE_FOREIGN_BUFFERS is removed
- CPU_{READ,WRITE}_OFTEN no longer implies CPU_{READ,WRITE}
Test: make android.hardware.graphics.allocator@2.0
Change-Id: Ibe9367d5b1701c0e1009da829f27fed0f7d98828
diff --git a/graphics/allocator/2.0/IAllocator.hal b/graphics/allocator/2.0/IAllocator.hal
new file mode 100644
index 0000000..8accb82
--- /dev/null
+++ b/graphics/allocator/2.0/IAllocator.hal
@@ -0,0 +1,177 @@
+/*
+ * Copyright (C) 2016 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.hardware.graphics.allocator@2.0;
+
+interface IAllocator {
+ enum Capability : int32_t {
+ /* reserved */
+ INVALID = 0,
+
+ /*
+ * testAllocate will always return UNDEFINED unless this capability
+ * is supported.
+ */
+ TEST_ALLOCATE = 1,
+ };
+
+ struct BufferDescriptorInfo {
+ /*
+ * The width specifies how many columns of pixels should be in the
+ * allocated buffer, but does not necessarily represent the offset in
+ * columns between the same column in adjacent rows. The rows may be
+ * padded.
+ */
+ uint32_t width;
+
+ /*
+ * The height specifies how many rows of pixels should be in the
+ * allocated buffer.
+ */
+ uint32_t height;
+
+ /* Buffer pixel format. */
+ PixelFormat format;
+
+ /*
+ * Buffer producer usage mask; valid flags can be found in the
+ * definition of ProducerUsage.
+ */
+ uint64_t producerUsageMask;
+
+ /*
+ * Buffer consumer usage mask; valid flags can be found in the
+ * definition of ConsumerUsage.
+ */
+ uint64_t consumerUsageMask;
+ };
+
+ /*
+ * Provides a list of supported capabilities (as described in the
+ * definition of Capability above). This list must not change after
+ * initialization.
+ *
+ * @return capabilities is a list of supported capabilities.
+ */
+ getCapabilities() generates (vec<Capability> capabilities);
+
+ /*
+ * Retrieves implementation-defined debug information, which will be
+ * displayed during, for example, `dumpsys SurfaceFlinger`.
+ *
+ * @return debugInfo is a string of debug information.
+ */
+ dumpDebugInfo() generates (string debugInfo);
+
+ /*
+ * Creates a new, opaque buffer descriptor.
+ *
+ * @param descriptorInfo specifies the attributes of the buffer
+ * descriptor.
+ * @return error is NONE upon success. Otherwise,
+ * BAD_VALUE when any attribute in descriptorInfo is invalid.
+ * NO_RESOURCES when no more descriptors can currently be created.
+ * @return descriptor is the newly created buffer descriptor.
+ */
+ createDescriptor(BufferDescriptorInfo descriptorInfo)
+ generates (Error error,
+ BufferDescriptor descriptor);
+
+ /*
+ * Destroys an existing buffer descriptor.
+ *
+ * @param descriptor is the descriptor to destroy.
+ * @return error is either NONE or BAD_DESCRIPTOR.
+ */
+ destroyDescriptor(BufferDescriptor descriptor) generates (Error error);
+
+ /*
+ * Tests whether a buffer allocation can succeed, ignoring potential
+ * resource contention which might lead to a NO_RESOURCES error.
+ *
+ * @param descriptors is a list of buffer descriptors.
+ * @return error is NONE or NOT_SHARED upon success;
+ * NONE when buffers can be created and share a backing store.
+ * NOT_SHARED when buffers can be created but require more than a
+ * backing store.
+ * Otherwise,
+ * BAD_DESCRIPTOR when any of the descriptors is invalid.
+ * UNSUPPORTED when any of the descriptors can never be satisfied.
+ * UNDEFINED when TEST_ALLOCATE is not listed in getCapabilities.
+ */
+ testAllocate(vec<BufferDescriptor> descriptors) generates (Error error);
+
+ /*
+ * Attempts to allocate a list of buffers sharing a backing store.
+ *
+ * Each buffer will correspond to one of the descriptors passed into the
+ * function and will hold a reference to its backing store. If the device
+ * is unable to share the backing store between the buffers, it must
+ * attempt to allocate the buffers with different backing stores and
+ * return NOT_SHARED if it is successful.
+ *
+ * @param descriptors is the buffer descriptors to attempt to allocate.
+ * @return error is NONE or NOT_SHARED upon success;
+ * NONE when buffers can be created and share a backing store.
+ * NOT_SHARED when buffers can be created but require more than a
+ * backing store.
+ * Otherwise,
+ * BAD_DESCRIPTOR when any of the descriptors is invalid.
+ * UNSUPPORTED when any of the descriptors can never be satisfied.
+ * NO_RESOURCES when any of the buffers cannot be created at this
+ * time.
+ * @return buffers is the allocated buffers.
+ */
+ allocate(vec<BufferDescriptor> descriptors)
+ generates (Error error,
+ vec<Buffer> buffers);
+
+ /*
+ * Frees a buffer.
+ *
+ * @param buffer is the buffer to be freed.
+ * @return error is NONE upon success. Otherwise,
+ * BAD_BUFFER when the buffer is invalid.
+ */
+ free(Buffer buffer) generates (Error error);
+
+ /*
+ * Exports a buffer for use in other client libraries or for cross-process
+ * sharing.
+ *
+ * The exported handle is a handle to the backing store of the buffer, not
+ * to the buffer itself. It however may not hold any reference to the
+ * backing store and may be considered invalid by client libraries. To use
+ * it and, in most cases, to save it for later use, a client must make a
+ * clone of the handle and have the cloned handle hold a reference to the
+ * backing store. Such a cloned handle will stay valid even after the
+ * original buffer is freed. Refer to native_handle_clone and IMapper for
+ * how a handle is cloned and how a reference is added.
+ *
+ * @param descriptor is the descriptor used to allocate the buffer.
+ * @param buffer is the buffer to be exported.
+ * @return error is NONE upon success. Otherwise,
+ * BAD_DESCRIPTOR when the descriptor is invalid.
+ * BAD_BUFFER when the buffer is invalid.
+ * BAD_VALUE when descriptor and buffer do not match.
+ * NO_RESOURCES when the buffer cannot be exported at this time.
+ * @return bufferHandle is the exported handle.
+ */
+ exportHandle(BufferDescriptor descriptor,
+ Buffer buffer)
+ generates (Error error,
+ handle bufferHandle);
+};