platform_hardware_interfaces/graphics/mapper/stable-c

IMapper "stable-c" HAL

Starting with gralloc version 5, IMapper is now exposed as a C API instead of through HIDL or AIDL. This is due to HIDL being deprecated, and AIDL not wanting to support a pass-through mode & pointers for just a couple of clients such as IMapper. So instead a stable C API is used to fill this gap.

Implementing

To provide an implementation a library implementing the AIMapper API interface should be provided in /vendor/lib[64]/hw/mapper.<imapper_suffix>.so. The <imapper_suffix> should be specified as the <instance> in the VINTF manifest <interface> section. For example:

<manifest version="1.0" type="device">
    <hal format="native">
        <name>mapper</name>
        <version>5.0</version>
        <interface>
            <instance>minigbm</instance>
        </interface>
    </hal>
</manifest>

defines that the IMapper 5.0 library is provided by /vendor/lib[64]/hw/mapper.minigbm.so.

This library must export the following extern "C" symbols:

ANDROID_HAL_STABLEC_VERSION

This is a uint32_t that should simply be set to the exported AIMapper version. For example:

extern "C" uint32_t ANDROID_HAL_STABLEC_VERSION = AIMAPPER_VERSION_5;

AIMapper_loadIMapper

This is what should actually load the HAL interface. The full type signature is

extern "C" AIMapper_Error AIMapper_loadIMapper(AIMapper* _Nullable* _Nonnull outImplementation)

See include/android/hardware/graphics/mapper/IMapper.h for complete documentation on what this function must return.

To make it easier to implement this C API, a header-only helper library is provided called libimapper_providerutils. This library handles mapping from the C API struct to a C++ class as well as provides helpers for encoding & decoding metadata, largely replacing the role that libgralloctypes filled with IMapper 4.

To use this library, create a class that extends from IMapperV5Impl and use IMapperProvider to implement AIMapper_loadIMapper:

// The IMapper interface itself
#include <android/hardware/graphics/mapper/IMapper.h>
// Helpers for reading & writing metadata
#include <android/hardware/graphics/mapper/utils/IMapperMetadataTypes.h>
// Helper for providing the implementation interface
#include <android/hardware/graphics/mapper/utils/IMapperProvider.h>

// Define an IMapperV5 implementation
class CrosGrallocMapperV5 final : public vendor::mapper::IMapperV5Impl {
    // Override all the methods of IMapperV5Impl
      AIMapper_Error importBuffer(const native_handle_t* _Nonnull handle,
                              buffer_handle_t _Nullable* _Nonnull outBufferHandle) override;
      [etc...]
};

// Expose the required C symbols

extern "C" uint32_t ANDROID_HAL_STABLEC_VERSION = AIMAPPER_VERSION_5;

extern "C" AIMapper_Error AIMapper_loadIMapper(AIMapper* _Nullable* _Nonnull outImplementation) {
    // Define an IMapperProvider for our V5 implementation
    static vendor::mapper::IMapperProvider<CrosGrallocMapperV5> provider;
    return provider.load(outImplementation);
}

A complete example, including using IMapperMetadataTypes, can be found in the cuttlefish implementation in //external/minigbm/cros_gralloc/mapper_stablec

Testing

As with HIDL & AIDL HALs, a VTS test is provided to validate the implementation. It is found in the vts folder and may be run using $ atest VtsHalGraphicsMapperStableC_TargetTest

Using

It is strongly recommended that clients use either the AHardwareBuffer (preferred) or GraphicBufferMapper (from libui) APIs to use the mapper HAL rather than attempting to use AIMapper directly.

Version changes

Version 5

• Initial introduction of this HAL interface
• Largely feature-equivalent to IMapper4
• Requires allocator-V2
• Removes BufferDescriptorInfo;
• IsSupported has moved to IAllocator
• Removes validateBufferSize, validation is instead handled by clients using metadata queries
• Getting the following StandardMetadataType is now mandatory:
  • STRIDE
• Setting the following StandardMetadataTypes is now mandatory:
  • DATASPACE
  • SMPTE2086
  • CTA861_3
  • BLEND_MODE