graphics: revise gralloc interfaces
Revise IAllocator and IMapper to reduce IPC and to support gralloc0
devices.
Specifically, IAllocator is trimmed down to have essentially only
allocate(BufferDescriptor descriptor, uint32_t count)
generates (Error error,
uint32_t stride,
vec<handle> buffers);
The ability to allocate buffers with shared backing store is
removed. ProducerUsage and ConsumerUsage are moved to the
graphics.common package and are merged and renamed to BufferUsage.
BufferUsage's bits follow gralloc0.
IMapper gains
typedef vec<uint32_t> BufferDescriptor;
createDescriptor(BufferDescriptorInfo descriptorInfo)
generates (Error error,
BufferDescriptor descriptor);
where BufferDescriptor is an implementation-defined blob. lockFlex
is replaced by lockYCbCr. All getters are removed.
Reference counting with retain/release is replaced by
importBuffer/freeBuffer.
Most if not all gralloc1 features are not used by the runtime yet.
There is also not too much test written for them. As such, they
tend to behave differently between implementations and cannot be
used reliably.
Bug: 36481301
Test: builds and boots on Pixel
Change-Id: I1d31105120517ea2c128c7a19297acf3bfd312bb
diff --git a/graphics/mapper/2.0/IMapper.hal b/graphics/mapper/2.0/IMapper.hal
index 573dcd0..246be24 100644
--- a/graphics/mapper/2.0/IMapper.hal
+++ b/graphics/mapper/2.0/IMapper.hal
@@ -16,10 +16,39 @@
package android.hardware.graphics.mapper@2.0;
-import android.hardware.graphics.common@1.0::PixelFormat;
-import android.hardware.graphics.allocator@2.0;
+import android.hardware.graphics.common@1.0;
interface IMapper {
+ struct BufferDescriptorInfo {
+ /**
+ * The width specifies how many columns of pixels must 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 must be in the
+ * allocated buffer.
+ */
+ uint32_t height;
+
+ /**
+ * The number of image layers that must be in the allocated buffer.
+ */
+ uint32_t layerCount;
+
+ /** Buffer pixel format. */
+ PixelFormat format;
+
+ /**
+ * Buffer usage mask; valid flags can be found in the definition of
+ * BufferUsage.
+ */
+ bitfield<BufferUsage> usage;
+ };
+
struct Rect {
int32_t left;
int32_t top;
@@ -28,170 +57,76 @@
};
/**
- * Adds a reference to the given buffer handle.
+ * Creates a buffer descriptor. The descriptor can be used with IAllocator
+ * to allocate buffers.
*
- * A buffer handle received from a remote process or exported by
- * IAllocator::exportHandle is unknown to the mapper. There is also no
- * guarantee that the buffer's backing store will stay alive. This
- * function must be called at least once in both cases to intrdouce the
- * buffer handle to the mapper and to secure the backing store. It may
- * also be called more than once to increase the reference count if two
- * components in the same process want to interact with the buffer
- * independently.
+ * Since the buffer descriptor fully describes a buffer, any device
+ * dependent or device independent checks must be performed here whenever
+ * possible. Specifically, when layered buffers are not supported, this
+ * function must return UNSUPPORTED if layerCount is great than 1.
*
- * @param bufferHandle is the buffer to which a reference must be added.
+ * @param descriptorInfo specifies the attributes of the descriptor.
* @return error is NONE upon success. Otherwise,
- * BAD_BUFFER when the buffer handle is invalid
- * NO_RESOURCES when it is not possible to add a
- * reference to this buffer at this time
+ * BAD_VALUE when any of the specified attributes is
+ * invalid or conflicting.
+ * NO_RESOURCES when the creation cannot be fullfilled at
+ * this time.
+ * UNSUPPORTED when any of the specified attributes is
+ * not supported.
+ * @return descriptor is the newly created buffer descriptor.
*/
@entry
@callflow(next="*")
- retain(handle bufferHandle) generates (Error error);
+ createDescriptor(BufferDescriptorInfo descriptorInfo)
+ generates (Error error,
+ BufferDescriptor descriptor);
/**
- * Removes a reference from the given buffer buffer.
+ * Imports a raw buffer handle to create an imported buffer handle for use
+ * with the rest of the mapper or with other in-process libraries.
*
- * If no references remain, the buffer handle must be freed with
- * native_handle_close/native_handle_delete by the mapper. When the last
- * buffer handle referring to a particular backing store is freed, that
- * backing store must also be freed.
+ * A buffer handle is considered raw when it is cloned or when it is
+ * received from another HAL or another process. A raw buffer handle must
+ * not be used to access the underlying graphics buffer. It must be
+ * imported to create an imported handle first.
*
- * @param bufferHandle is the buffer from which a reference must be
- * removed.
+ * This function must at least validate the raw handle before creating the
+ * imported handle. It must also support importing the same raw handle
+ * multiple times to create multiple imported handles. The imported handle
+ * must be considered valid everywhere in the process, including in
+ * another instance of the mapper.
+ *
+ * @param rawHandle is the raw buffer handle to import.
* @return error is NONE upon success. Otherwise,
- * BAD_BUFFER when the buffer handle is invalid.
+ * BAD_BUFFER when the raw handle is invalid.
+ * NO_RESOURCES when the raw handle cannot be imported at
+ * this time.
+ * @return buffer is the imported buffer handle and has the type
+ * buffer_handle_t.
+ */
+ @entry
+ @callflow(next="*")
+ importBuffer(handle rawHandle) generates (Error error, pointer buffer);
+
+ /**
+ * Frees a buffer handle. Buffer handles returned by importBuffer must be
+ * freed with this function when no longer needed.
+ *
+ * This function must free up all resources allocated by importBuffer for
+ * the imported handle. For example, if the imported handle was created
+ * with native_handle_create, this function must call native_handle_close
+ * and native_handle_delete.
+ *
+ * @return error is NONE upon success. Otherwise,
+ * BAD_BUFFER when the buffer is invalid.
*/
@exit
- release(handle bufferHandle) generates (Error error);
-
- /**
- * Gets the width and height of the buffer in pixels.
- *
- * See IAllocator::BufferDescriptorInfo for more information.
- *
- * @param bufferHandle is the buffer from which to get the dimensions.
- * @return error is NONE upon success. Otherwise,
- * BAD_BUFFER when the buffer handle is invalid.
- * @return width is the width of the buffer in pixels.
- * @return height is the height of the buffer in pixels.
- */
@callflow(next="*")
- getDimensions(handle bufferHandle)
- generates (Error error,
- uint32_t width,
- uint32_t height);
-
- /**
- * Gets the format of the buffer.
- *
- * See IAllocator::BufferDescriptorInfo for more information.
- *
- * @param bufferHandle is the buffer from which to get format.
- * @return error is NONE upon success. Otherwise,
- * BAD_BUFFER when the buffer handle is invalid.
- * @return format is the format of the buffer.
- */
- @callflow(next="*")
- getFormat(handle bufferHandle)
- generates (Error error,
- PixelFormat format);
-
- /**
- * Gets the number of layers of the buffer.
- *
- * See IAllocator::BufferDescriptorInfo for more information.
- *
- * @param bufferHandle is the buffer from which to get format.
- * @return error is NONE upon success. Otherwise,
- * BAD_BUFFER when the buffer handle is invalid.
- * @return layerCount is the number of layers of the buffer.
- */
- @callflow(next="*")
- getLayerCount(handle bufferHandle)
- generates (Error error,
- uint32_t layerCount);
-
- /**
- * Gets the producer usage flags which were used to allocate this buffer.
- *
- * See IAllocator::BufferDescriptorInfo for more information.
- *
- * @param bufferHandle is the buffer from which to get the producer usage
- * flags.
- * @return error is NONE upon success. Otherwise,
- * BAD_BUFFER when the buffer handle is invalid.
- * @return usageMask contains the producer usage flags of the buffer.
- */
- @callflow(next="*")
- getProducerUsageMask(handle bufferHandle)
- generates (Error error,
- uint64_t usageMask);
-
- /**
- * Gets the consumer usage flags which were used to allocate this buffer.
- *
- * See IAllocator::BufferDescriptorInfo for more information.
- *
- * @param bufferHandle is the buffer from which to get the consumer usage
- * flags.
- * @return error is NONE upon success. Otherwise,
- * BAD_BUFFER when the buffer handle is invalid.
- * @return usageMask contains the consumer usage flags of the buffer.
- */
- @callflow(next="*")
- getConsumerUsageMask(handle bufferHandle)
- generates (Error error,
- uint64_t usageMask);
-
- /**
- * Gets a value that uniquely identifies the backing store of the given
- * buffer.
- *
- * Buffers which share a backing store should return the same value from
- * this function. If the buffer is present in more than one process, the
- * backing store value for that buffer is not required to be the same in
- * every process.
- *
- * @param device is the mapper device.
- * @param bufferHandle is the buffer from which to get the backing store
- * identifier.
- * @return error is NONE upon success. Otherwise,
- * BAD_BUFFER when the buffer handle is invalid.
- * @return store is the backing store identifier for this buffer.
- */
- @callflow(next="*")
- getBackingStore(handle bufferHandle)
- generates (Error error,
- BackingStore store);
-
- /**
- * Gets the stride of the buffer in pixels.
- *
- * The stride is the offset in pixel-sized elements between the same
- * column in two adjacent rows of pixels. This may not be equal to the
- * width of the buffer.
- *
- * @param device is the mapper device.
- * @param bufferHandle is the buffer from which to get the stride.
- * @return error is NONE upon success. Otherwise,
- * BAD_BUFFER when the buffer handle is invalid.
- * UNDEFINED when the notion of a stride is not
- * meaningful for the buffer format.
- * @return store is the stride in pixels.
- */
- @callflow(next="*")
- getStride(handle bufferHandle)
- generates (Error error,
- uint32_t stride);
+ freeBuffer(pointer buffer) generates (Error error);
/**
* Locks the given buffer for the specified CPU usage.
*
- * Exactly one of producerUsageMask and consumerUsageMask must be 0. The
- * usage which is not 0 must be one of the *Usage::CPU* values, as
- * applicable. Locking a buffer for a non-CPU usage is not supported.
- *
* Locking the same buffer simultaneously from multiple threads is
* permitted, but if any of the threads attempt to lock the buffer for
* writing, the behavior is undefined, except that it must not cause
@@ -209,39 +144,27 @@
* address will represent the top-left corner of the entire buffer, even
* if accessRegion does not begin at the top-left corner.
*
- * acquireFence is a file descriptor referring to a acquire sync fence
- * object, which will be signaled when it is safe for the device to access
- * the contents of the buffer (prior to locking). If it is already safe to
- * access the buffer contents, -1 may be passed instead.
- *
- * @param bufferHandle is the buffer to lock.
- * @param producerUsageMask contains the producer usage flags to request;
- * either this or consumerUsagemask must be 0, and the other must
- * be a CPU usage.
- * @param consumerUsageMask contains the consumer usage flags to request;
- * either this or producerUsageMask must be 0, and the other must
- * be a CPU usage.
+ * @param buffer is the buffer to lock.
+ * @param cpuUsage specifies one or more CPU usage flags to request.
* @param accessRegion is the portion of the buffer that the client
* intends to access.
- * @param acquireFence is a sync fence file descriptor as described above.
+ * @param acquireFence, when non-empty, is a handle containing a file
+ * descriptor referring to a sync fence object, which will be
+ * signaled when it is safe for the mapper to lock the buffer. If
+ * it is already safe to lock, acquireFence is empty.
* @return error is NONE upon success. Otherwise,
- * BAD_BUFFER when the buffer handle is invalid.
- * BAD_VALUE when neither or both of producerUsageMask
- * and consumerUsageMask were 0, or the usage
- * which was not 0 was not a CPU usage.
+ * BAD_BUFFER when the buffer is invalid or is
+ * incompatible with this function.
+ * BAD_VALUE when cpuUsage is 0, contains non-CPU usage
+ * flags, or is incompatible with the buffer.
* NO_RESOURCES when the buffer cannot be locked at this
* time, but locking may succeed at a future
* time.
- * UNSUPPORTED when the buffer cannot be locked with the
- * given usage, and any future attempts at
- * locking will also fail.
- * @return data will be filled with a CPU-accessible pointer to the buffer
- * data.
+ * @return data is a CPU-accessible pointer to the buffer data.
*/
@callflow(next="unlock")
- lock(handle bufferHandle,
- uint64_t producerUsageMask,
- uint64_t consumerUsageMask,
+ lock(pointer buffer,
+ bitfield<BufferUsage> cpuUsage,
Rect accessRegion,
handle acquireFence)
generates (Error error,
@@ -249,7 +172,7 @@
/**
* This is largely the same as lock(), except that instead of returning a
- * pointer directly to the buffer data, it returns an FlexLayout struct
+ * pointer directly to the buffer data, it returns an YCbCrLayout struct
* describing how to access the data planes.
*
* This function must work on buffers with PixelFormat::YCbCr_*_888 if
@@ -257,67 +180,46 @@
* multimedia codecs when they are configured with a
* flexible-YUV-compatible color format.
*
- * This function may also be called on buffers of other formats, including
- * non-YUV formats, but if the buffer format is not compatible with a
- * flexible representation, it may return UNSUPPORTED.
- *
- * @param device is the mapper device.
- * @param bufferHandle is the buffer to lock.
- * @param producerUsageMask contains the producer usage flags to request;
- * either this or consumerUsagemask must be 0, and the other must
- * be a CPU usage.
- * @param consumerUsageMask contains the consumer usage flags to request;
- * either this or producerUsageMask must be 0, and the other must
- * be a CPU usage.
+ * @param buffer is the buffer to lock.
+ * @param cpuUsage specifies one or more CPU usage flags to request.
* @param accessRegion is the portion of the buffer that the client
* intends to access.
- * @param acquireFence is a sync fence file descriptor as described in
- * lock().
+ * @param acquireFence, when non-empty, is a handle containing a file
+ * descriptor referring to a sync fence object, which will be
+ * signaled when it is safe for the mapper to lock the buffer. If
+ * it is already safe to lock, acquireFence is empty.
* @return error is NONE upon success. Otherwise,
- * BAD_BUFFER when the buffer handle is invalid.
- * BAD_VALUE when neither or both of producerUsageMask
- * and consumerUsageMask were 0, or the usage
- * which was not 0 was not a CPU usage.
+ * BAD_BUFFER when the buffer is invalid or is
+ * incompatible with this function.
+ * BAD_VALUE when cpuUsage is 0, contains non-CPU usage
+ * flags, or is incompatible with the buffer.
* NO_RESOURCES when the buffer cannot be locked at this
* time, but locking may succeed at a future
* time.
- * UNSUPPORTED when the buffer cannot be locked with the
- * given usage, and any future attempts at
- * locking will also fail.
- * @return flexLayout will be filled with the description of the planes in
- * the buffer.
+ * @return layout is the data layout of the buffer.
*/
@callflow(next="unlock")
- lockFlex(handle bufferHandle,
- uint64_t producerUsageMask,
- uint64_t consumerUsageMask,
- Rect accessRegion,
- handle acquireFence)
+ lockYCbCr(pointer buffer,
+ bitfield<BufferUsage> cpuUsage,
+ Rect accessRegion,
+ handle acquireFence)
generates (Error error,
- FlexLayout layout);
+ YCbCrLayout layout);
/**
- * This function indicates to the device that the client will be done with
- * the buffer when releaseFence signals.
+ * Unlocks a buffer to indicate all CPU accesses to the buffer have
+ * completed.
*
- * releaseFence will be filled with a file descriptor referring to a
- * release sync fence object, which will be signaled when it is safe to
- * access the contents of the buffer (after the buffer has been unlocked).
- * If it is already safe to access the buffer contents, then -1 may be
- * returned instead.
- *
- * This function is used to unlock both buffers locked by lock() and those
- * locked by lockFlex().
- *
- * @param device is the mapper device.
- * @param bufferHandle is the buffer to unlock.
+ * @param buffer is the buffer to unlock.
* @return error is NONE upon success. Otherwise,
- * BAD_BUFFER when the buffer handle is invalid.
- * @return releaseFence is a sync fence file descriptor as described
- * above.
+ * BAD_BUFFER when the buffer is invalid or not locked.
+ * @return releaseFence, when non-empty, is a handle containing a file
+ * descriptor referring to a sync fence object. The sync fence
+ * object will be signaled when the mapper has completed any
+ * pending work.
*/
@callflow(next="*")
- unlock(handle bufferHandle)
+ unlock(pointer buffer)
generates (Error error,
handle releaseFence);
};