1# IMapper "stable-c" HAL 2 3Starting with gralloc version 5, IMapper is now exposed as a C API instead of through HIDL or AIDL. 4This is due to HIDL being deprecated, and AIDL not wanting to support a pass-through mode & pointers 5for just a couple of clients such as IMapper. So instead a stable C API is used to fill this gap. 6 7## Implementing 8 9To provide an implementation a library implementing the AIMapper API interface should be provided 10in `/vendor/lib[64]/hw/mapper.<imapper_suffix>.so`. The `<imapper_suffix>` should be specified 11as the `<instance>` in the VINTF manifest `<interface>` section. For example: 12```xml 13<manifest version="1.0" type="device"> 14 <hal format="native"> 15 <name>mapper</name> 16 <version>5.0</version> 17 <interface> 18 <instance>minigbm</instance> 19 </interface> 20 </hal> 21</manifest> 22``` 23defines that the IMapper 5.0 library is provided by `/vendor/lib[64]/hw/mapper.minigbm.so`. 24 25This library must export the following `extern "C"` symbols: 26 27### `ANDROID_HAL_STABLEC_VERSION` 28 29This is a uint32_t that should simply be set to the exported AIMapper version. For example: 30```c++ 31extern "C" uint32_t ANDROID_HAL_STABLEC_VERSION = AIMAPPER_VERSION_5; 32``` 33 34### `AIMapper_loadIMapper` 35 36This is what should actually load the HAL interface. The full type signature is 37```c++ 38extern "C" AIMapper_Error AIMapper_loadIMapper(AIMapper* _Nullable* _Nonnull outImplementation) 39``` 40 41See `include/android/hardware/graphics/mapper/IMapper.h` for complete documentation on what 42this function must return. 43 44To make it easier to implement this C API, a header-only helper library is provided called 45`libimapper_providerutils`. This library handles mapping from the C API struct to a C++ class 46as well as provides helpers for encoding & decoding metadata, largely replacing the role that 47`libgralloctypes` filled with IMapper 4. 48 49To use this library, create a class that extends from `IMapperV5Impl` and use `IMapperProvider` to 50implement `AIMapper_loadIMapper`: 51 52```c++ 53// The IMapper interface itself 54#include <android/hardware/graphics/mapper/IMapper.h> 55// Helpers for reading & writing metadata 56#include <android/hardware/graphics/mapper/utils/IMapperMetadataTypes.h> 57// Helper for providing the implementation interface 58#include <android/hardware/graphics/mapper/utils/IMapperProvider.h> 59 60// Define an IMapperV5 implementation 61class CrosGrallocMapperV5 final : public vendor::mapper::IMapperV5Impl { 62 // Override all the methods of IMapperV5Impl 63 AIMapper_Error importBuffer(const native_handle_t* _Nonnull handle, 64 buffer_handle_t _Nullable* _Nonnull outBufferHandle) override; 65 [etc...] 66}; 67 68// Expose the required C symbols 69 70extern "C" uint32_t ANDROID_HAL_STABLEC_VERSION = AIMAPPER_VERSION_5; 71 72extern "C" AIMapper_Error AIMapper_loadIMapper(AIMapper* _Nullable* _Nonnull outImplementation) { 73 // Define an IMapperProvider for our V5 implementation 74 static vendor::mapper::IMapperProvider<CrosGrallocMapperV5> provider; 75 return provider.load(outImplementation); 76} 77``` 78 79A complete example, including using IMapperMetadataTypes, can be found in the cuttlefish 80implementation in `//external/minigbm/cros_gralloc/mapper_stablec` 81 82### Testing 83 84As with HIDL & AIDL HALs, a VTS test is provided to validate the implementation. It is found in the 85`vts` folder and may be run using `$ atest VtsHalGraphicsMapperStableC_TargetTest` 86 87## Using 88 89It is strongly recommended that clients use either the `AHardwareBuffer` (preferred) or 90`GraphicBufferMapper` (from libui) APIs to use the mapper HAL rather than attempting to use 91`AIMapper` directly. 92 93## Version changes 94 95### Version 5 96 97* Initial introduction of this HAL interface 98* Largely feature-equivalent to IMapper4 99* Requires allocator-V2 100* Removes `BufferDescriptorInfo`; 101* IsSupported has moved to IAllocator 102* Removes `validateBufferSize`, validation is instead handled by clients using metadata queries 103* Getting the following StandardMetadataType is now mandatory: 104 * STRIDE 105* Setting the following StandardMetadataTypes is now mandatory: 106 * DATASPACE 107 * SMPTE2086 108 * CTA861_3 109 * BLEND_MODE 110