graphics/mapper/4.0/IMapper.hal

/*
 * Copyright 2019 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.mapper@4.0;

import android.hardware.graphics.common@1.2::BufferUsage;
import android.hardware.graphics.common@1.2::PixelFormat;
import android.hardware.graphics.common@1.2::Rect;

interface IMapper {
    struct BufferDescriptorInfo {
        /**
         * The name of the buffer. Useful for debugging/tracing.
         */
        string name;

        /**
         * 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;
        int32_t width;
        int32_t height;
    };

    /**
     * Creates a buffer descriptor. The descriptor can be used with IAllocator
     * to allocate buffers.
     *
     * 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 `description.layers` is great than
     * 1.
     *
     * @param description Attributes of the descriptor.
     * @return error Error status of the call, which may be
     *     - `NONE` upon success.
     *     - `BAD_VALUE` if any of the specified attributes are invalid or
     *       inconsistent.
     *     - `NO_RESOURCES` if the creation cannot be fullfilled due to
     *       unavailability of resources.
     *     - `UNSUPPORTED` when any of the specified attributes are not
     *       supported.
     * @return descriptor Newly created buffer descriptor.
     */
    createDescriptor(BufferDescriptorInfo description)
            generates (Error error,
                       BufferDescriptor descriptor);

    /**
     * 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.
     *
     * A buffer handle is considered raw when it is cloned (e.g., with
     * `native_handle_clone()`) from another buffer handle locally, or when it
     * is received from another HAL server/client or another process. A raw
     * buffer handle must not be used to access the underlying graphic
     * buffer. It must be imported to create an imported handle first.
     *
     * 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.
     *
     * Because of passthrough HALs, a raw buffer handle received from a HAL
     * may actually have been imported in the process. importBuffer() must treat
     * such a handle as if it is raw and must not return `BAD_BUFFER`. The
     * returned handle is independent from the input handle as usual, and
     * freeBuffer() must be called on it when it is no longer needed.
     *
     * @param rawHandle Raw buffer handle to import.
     * @return error Error status of the call, which may be
     *     - `NONE` upon success.
     *     - `BAD_BUFFER` if the raw handle is invalid.
     *     - `NO_RESOURCES` if the raw handle cannot be imported due to
     *       unavailability of resources.
     * @return buffer Imported buffer handle that has the type
     *     `buffer_handle_t` which is a handle type.
     */
    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()`.
     *
     * @param buffer Imported buffer handle.
     * @return error Error status of the call, which may be
     *     - `NONE` upon success.
     *     - `BAD_BUFFER` if the buffer is invalid.
     */
    freeBuffer(pointer buffer) generates (Error error);

    /**
     * Validates that the buffer can be safely accessed by a caller who assumes
     * the specified @p description and @p stride. This must at least validate
     * that the buffer size is large enough. Validating the buffer against
     * individual buffer attributes is optional.
     *
     * @param buffer Buffer to validate against.
     * @param description Attributes of the buffer.
     * @param stride Stride returned by IAllocator::allocate().
     * @return error Error status of the call, which may be
     *     - `NONE` upon success.
     *     - `BAD_BUFFER` if the buffer is invalid.
     *     - `BAD_VALUE` if the buffer cannot be safely accessed.
     */
    validateBufferSize(pointer buffer,
                       BufferDescriptorInfo description,
                       uint32_t stride)
            generates (Error error);

    /**
     * Calculates the transport size of a buffer. An imported buffer handle is a
     * raw buffer handle with the process-local runtime data appended. This
     * function, for example, allows a caller to omit the process-local runtime
     * data at the tail when serializing the imported buffer handle.
     *
     * Note that a client might or might not omit the process-local runtime data
     * when sending an imported buffer handle. The mapper must support both
     * cases on the receiving end.
     *
     * @param buffer Buffer to get the transport size from.
     * @return error Error status of the call, which may be
     *     - `NONE` upon success.
     *     - `BAD_BUFFER` if the buffer is invalid.
     * @return numFds The number of file descriptors needed for transport.
     * @return numInts The number of integers needed for transport.
     */
    getTransportSize(pointer buffer)
            generates (Error error,
                       uint32_t numFds,
                       uint32_t numInts);

    /**
     * Locks the given buffer for the specified CPU usage.
     *
     * 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
     * process termination or block the client indefinitely. Leaving the
     * buffer content in an indeterminate state or returning an error are both
     * acceptable.
     *
     * 1D buffers (width = size in bytes, height = 1, pixel_format = BLOB) must
     * "lock in place". The buffers must be directly accessible via mapping.
     *
     * The client must not modify the content of the buffer outside of
     * @p accessRegion, and the device need not guarantee that content outside
     * of @p accessRegion is valid for reading. The result of reading or writing
     * outside of @p accessRegion is undefined, except that it must not cause
     * process termination.
     *
     * On success, @p data must be filled with a pointer to the locked buffer
     * memory. This address will represent the top-left corner of the entire
     * buffer, even if @p accessRegion does not begin at the top-left corner.
     *
     * On success, bytesPerPixel must contain the number of bytes per pixel in
     * the buffer. If the bytesPerPixel is unknown or variable, a value of -1
     * should be returned. bytesPerStride must contain the bytes per stride of
     * the buffer. If the bytesPerStride is unknown or variable, a value of -1
     * should be returned.
     *
     * The locked buffer must adhere to the format requested at allocation time
     * in the BufferDescriptorInfo.
     *
     * @param buffer Buffer to lock.
     * @param cpuUsage CPU usage flags to request. See +ndk
     *     libnativewindow#AHardwareBuffer_UsageFlags for possible values.
     * @param accessRegion Portion of the buffer that the client intends to
     *     access.
     * @param acquireFence 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. @p acquireFence may be an empty fence if
     *     it is already safe to lock.
     * @return error Error status of the call, which may be
     *     - `NONE` upon success.
     *     - `BAD_BUFFER` if the buffer is invalid or is incompatible with this
     *       function.
     *     - `BAD_VALUE` if @p cpuUsage is 0, contains non-CPU usage flags, or
     *       is incompatible with the buffer. Also if the @p accessRegion is
     *       outside the bounds of the buffer or the accessRegion is invalid.
     *     - `NO_RESOURCES` if the buffer cannot be locked at this time. Note
     *       that locking may succeed at a later time.
     * @return data CPU-accessible pointer to the buffer data.
     * @return bytesPerPixel the number of bytes per pixel in the buffer
     * @return bytesPerStride the number of bytes per stride of the buffer
     */
    lock(pointer buffer,
         uint64_t cpuUsage,
         Rect accessRegion,
         handle acquireFence)
            generates (Error error,
                       pointer data,
                       int32_t bytesPerPixel,
                       int32_t bytesPerStride);

    /**
     * Locks a YCbCr buffer for the specified CPU usage.
     *
     * This is largely the same as lock(), except that instead of returning a
     * pointer directly to the buffer data, it returns a `YCbCrLayout` struct
     * describing how to access the data planes.
     *
     * This function must work on buffers with
     * `AHARDWAREBUFFER_FORMAT_Y8Cb8Cr8_*` if supported by the device, as well
     * as with any other formats requested by multimedia codecs when they are
     * configured with a flexible-YUV-compatible color format.
     *
     * @param buffer Buffer to lock.
     * @param cpuUsage CPU usage flags to request. See +ndk
     *     libnativewindow#AHardwareBuffer_UsageFlags for possible values.
     * @param accessRegion Portion of the buffer that the client intends to
     *     access.
     * @param acquireFence 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. @p acquireFence may be empty if it is
     *     already safe to lock.
     * @return error Error status of the call, which may be
     *     - `NONE` upon success.
     *     - `BAD_BUFFER` if the buffer is invalid or is incompatible with this
     *       function.
     *     - `BAD_VALUE` if @p cpuUsage is 0, contains non-CPU usage flags, or
     *       is incompatible with the buffer.
     *     - `NO_RESOURCES` if the buffer cannot be locked at this time. Note
     *       that locking may succeed at a later time.
     * @return layout Data layout of the locked buffer.
     */
    lockYCbCr(pointer buffer,
              uint64_t cpuUsage,
              Rect accessRegion,
              handle acquireFence)
            generates (Error error,
                       YCbCrLayout layout);

    /**
     * Unlocks a buffer to indicate all CPU accesses to the buffer have
     * completed.
     *
     * @param buffer Buffer to unlock.
     * @return error Error status of the call, which may be
     *     - `NONE` upon success.
     *     - `BAD_BUFFER` if the buffer is invalid or not locked.
     * @return releaseFence 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. @p releaseFence may be an
     *     empty fence.
     */
    unlock(pointer buffer) generates (Error error, handle releaseFence);

    /**
     * Test whether the given BufferDescriptorInfo is allocatable.
     *
     * If this function returns true, it means that a buffer with the given
     * description can be allocated on this implementation, unless resource
     * exhaustion occurs. If this function returns false, it means that the
     * allocation of the given description will never succeed.
     *
     * @param description the description of the buffer
     * @return supported whether the description is supported
     */
    isSupported(BufferDescriptorInfo description)
            generates (Error error,
                       bool supported);


    /**
     * Description for get(...), set(...) and getFromBufferDescriptorInfo(...)
     *
     * ------------ Overview -----------------------------------
     * Gralloc 4 adds support for getting and setting buffer metadata on a buffer.
     *
     * To get buffer metadata, the client passes in a buffer handle and a token that
     * represents the type of buffer metadata they would like to get. IMapper returns
     * a byte stream that contains the buffer metadata. To set the buffer metadata, the
     * client passes in a buffer handle and a token that represents the type of buffer
     * metadata they would like to set and a byte stream that contains the buffer metadata
     * they are setting.
     *
     * Buffer metadata is global for a buffer. When the metadata is set on the buffer
     * in a process, the updated metadata should be available to all other processes.
     * Please see "Storing and Propagating Metadata" below for more details.
     *
     * The getter and setter functions have been optimized for easy vendor extension.
     * They do not require a formal HIDL extension to add support for getting and setting
     * vendor defined buffer metadata. In order to allow easy extension, the types used
     * here are not typical HIDL types. See "Buffer Metadata Token" and
     * "Buffer Metadata Stream" below for more details.
     *
     * ------------ Storing and Propagating Metadata -----------
     * Buffer metadata must be global. Any changes to the metadata must be propagated
     * to all other processes immediately. Vendors may chose how they would like support
     * this functionality.
     *
     * We recommend supporting this functionality by allocating an extra page of shared
     * memory and storing it in the buffer's native_handle_t. The buffer metadata can
     * be stored in the extra page of shared memory. Set operations are automatically
     * propagated to all other processes.
     *
     * ------------ Buffer Metadata Synchronization ------------
     * There are no explicit buffer metadata synchronization primitives. Many devices
     * before gralloc 4 already support getting and setting of global buffer metadata
     * with no explicit synchronization primitives. Adding synchronization primitives
     * would just add unnecessary complexity.
     *
     * The general rule is if a process has permission to write to a buffer, they
     * have permission to write to the buffer's metadata. If a process has permission
     * to read from a buffer, they have permission to read the buffer's metadata.
     *
     * There is one exception to this rule. Fences CANNOT be used to protect a buffer's
     * metadata. A process should finish writing to a buffer's metadata before sending
     * sending the buffer to another process that will read or write to the buffer.
     * This exception is needed because sometimes userspace needs to read the
     * buffer's metadata before the buffer's contents are ready.
     *
     * As a simple example: an app renders to a buffer and then displays the buffer.
     * In this example when the app renders to the buffer, both the buffer and its
     * metadata need to be updated. The app's process queues up its work on the GPU
     * and gets back an acquire fence. The app's process must update the buffer's
     * metadata before enqueuing the buffer to SurfaceFlinger. The app process CANNOT
     * update the buffer's metadata after enqueuing the buffer. When HardwareComposer
     * receives the buffer, it is immediately safe to read the buffer's metadata
     * and use it to program the display driver. To read the buffer's contents,
     * display driver must still wait on the acquire fence.
     *
     * ------------ Buffer Metadata Token ----------------------
     * In order to allow arbitrary vendor defined metadata, we could not use a
     * HIDL enum as the buffer metadata token. Extending a HIDL enum requires a full
     * HIDL extension. We also could not use a simple non-HIDL enum because vendor
     * defined enums from different vendors could collide. Instead we have defined
     * a struct that has a string representing the enum type and an int that
     * represents the enum value. The string protects different enum values from
     * colliding.
     *
     * The token struct (MetadataType) is defined as a HIDL struct since it
     * is passed into a HIDL function. The standard buffer metadata types are NOT
     * defined as a HIDL enum because it would have required a new IMapper version
     * just to add future standard buffer metadata types. By putting the enum in the
     * stable AIDL (hardware/interfaces/graphics/common/aidl/android/hardware/
     * graphics/common/StandardMetadataType.aidl), vendors will be able to optionally
     * choose to support future standard buffer metadata types without upgrading
     * HIDL versions. For more information see the description of "struct MetadataType".
     *
     * ------------ Buffer Metadata Stream ---------------------
     * The buffer metadata is get and set as a byte stream (vec<uint8_t>). By getting
     * and setting buffer metadata as a byte stream, vendors can use the standard
     * getters and setter functions defined here. Vendors do NOT need to add their own
     * getters and setter functions for each new type of buffer metadata.
     *
     * Converting buffer metadata into a byte stream can be non-trivial. For the standard
     * buffer metadata types defined in StandardMetadataType.aidl, there are also
     * support functions that will encode the buffer metadata into a byte stream
     * and decode the buffer metadata from a byte stream. We STRONGLY recommend using
     * these support functions. The framework will use them when getting and setting
     * metadata. The support functions are defined in
     * frameworks/native/libs/gralloc/types/include/gralloctypes/Gralloc4.h.
     */

    /**
     * MetadataType represents the different types of buffer metadata that could be
     * associated with a buffer. It is used by IMapper to help get and set buffer metadata
     * on the buffer's native handle.
     *
     * Standard buffer metadata will have the name field set to
     * "android.hardware.graphics.common.StandardMetadataType" and will contain values
     * from StandardMetadataType.aidl.
     *
     * This struct should be "extended" by devices that use a proprietary or non-standard
     * buffer metadata. To extend the struct, first create a custom @VendorStability vendor
     * AIDL interface that defines the new type(s) you would like to support. Set the
     * struct's name field to the custom aidl interface's name
     * (eg. "vendor.mycompanyname.graphics.common.MetadataType"). Set the struct's value
     * field to the custom @VendorStabilty vendor AIDL interface.
     *
     * Each company should create their own StandardMetadataType.aidl extension. The name
     * field prevents values from different companies from colliding.
     */
    struct MetadataType {
        string name;
        int64_t value;
    };

    /**
     * Gets the buffer metadata for a given MetadataType.
     *
     * Buffer metadata can be changed after allocation so clients should avoid "caching"
     * the buffer metadata. For example, if the video resolution changes and the buffers
     * are not reallocated, several buffer metadata values may change without warning.
     * Clients should not expect the values to be constant. They should requery them every
     * frame. The only exception is buffer metadata that is determined at allocation
     * time. For StandardMetadataType values, only BUFFER_ID, NAME, WIDTH,
     * HEIGHT, LAYER_COUNT, PIXEL_FORMAT_REQUESTED and USAGE are safe to cache because
     * they are determined at allocation time.
     *
     * @param buffer Buffer containing desired metadata
     * @param metadataType MetadataType for the metadata value being queried
     * @return error Error status of the call, which may be
     *     - `NONE` upon success.
     *     - `BAD_BUFFER` if the raw handle is invalid.
     *     - `NO_RESOURCES` if the get cannot be fullfilled due to unavailability of
     *        resources.
     *     - `UNSUPPORTED` when metadataType is unknown/unsupported.
     *        IMapper must support getting all StandardMetadataType.aidl values defined
     *        at the time the device first launches.
     * @return metadata Vector of bytes representing the buffer metadata associated with
     *  the MetadataType.
     */
    get(pointer buffer, MetadataType metadataType)
            generates (Error error,
                       vec<uint8_t> metadata);

    /**
     * Sets the global value for a given MetadataType.
     *
     * Metadata fields are not required to be settable. This function can
     * return Error::UNSUPPORTED whenever it doesn't support setting a
     * particular Metadata field.
     *
     * The framework may attempt to set the following StandardMetadataType
     * values: DATASPACE, PER_FRAME_METADATA, PER_FRAME_METADATA_BLOB and BLEND_MODE.
     * We strongly encourage everyone to support setting as many of those fields as
     * possible. If a device's Composer implementation supports a field, it should be
     * supported here. Over time these metadata fields will be moved out of
     * Composer/BufferQueue/etc. and into the buffer's Metadata fields.
     * If a device's IMapper doesn't support setting those Metadata fields,
     * eventually the device may not longer be able to support these fields.
     *
     * @param buffer Buffer receiving desired metadata
     * @param metadataType MetadataType for the metadata value being set
     * @param metadata Vector of bytes representing the value associated with
     * @return error Error status of the call, which may be
     *     - `NONE` upon success.
     *     - `BAD_BUFFER` if the raw handle is invalid.
     *     - `BAD_VALUE` when the field is constant and can never be set (such as
     *       BUFFER_ID, NAME, WIDTH, HEIGHT, LAYER_COUNT, PIXEL_FORMAT_REQUESTED and
     *       USAGE)
     *     - `NO_RESOURCES` if the set cannot be fullfilled due to unavailability of
     *        resources.
     *     - `UNSUPPORTED` when metadataType is unknown/unsupported or setting
     *       it is unsupported. Unsupported should also be returned if the metadata
     *       is malformed.
     */
    set(pointer buffer, MetadataType metadataType, vec<uint8_t> metadata)
            generates (Error error);

    /**
     * Given a BufferDescriptorInfo, gets the starting value of a given
     * MetadataType. This can be used to query basic information about a buffer
     * before the buffer is allocated.
     *
     * @param description Attributes of the descriptor.
     * @param metadataType MetadataType for the metadata value being queried
     * @return error Error status of the call, which may be
     *     - `NONE` upon success.
     *     - `BAD_VALUE` if any of the specified BufferDescriptorInfo attributes
     *       are invalid.
     *     - `NO_RESOURCES` if the get cannot be fullfilled due to unavailability of
     *       resources.
     *     - `UNSUPPORTED` when any of the description attributes are unsupported or
     *       if the metadataType is unknown/unsupported. This should also be
     *       returned if the requested metadata is not defined until a buffer has been
     *       allocated.
     * @return metadata Vector of bytes representing the value associated with
     *  the MetadataType value.
     */
    getFromBufferDescriptorInfo(BufferDescriptorInfo description,
                                MetadataType metadataType)
            generates (Error error,
                       vec<uint8_t> metadata);
};