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 25ServiceManager should be able to `find` the instance. The instance should be labelled in 26`service_contexts` as follows: 27``` 28mapper/minigbm u:object_r:hal_graphics_mapper_service:s0 29``` 30 31This library must export the following `extern "C"` symbols: 32 33### `ANDROID_HAL_STABLEC_VERSION` 34 35This is a uint32_t that should simply be set to the exported AIMapper version. For example: 36```c++ 37extern "C" uint32_t ANDROID_HAL_STABLEC_VERSION = AIMAPPER_VERSION_5; 38``` 39 40### `AIMapper_loadIMapper` 41 42This is what should actually load the HAL interface. The full type signature is 43```c++ 44extern "C" AIMapper_Error AIMapper_loadIMapper(AIMapper* _Nullable* _Nonnull outImplementation) 45``` 46 47See `include/android/hardware/graphics/mapper/IMapper.h` for complete documentation on what 48this function must return. 49 50To make it easier to implement this C API, a header-only helper library is provided called 51`libimapper_providerutils`. This library handles mapping from the C API struct to a C++ class 52as well as provides helpers for encoding & decoding metadata, largely replacing the role that 53`libgralloctypes` filled with IMapper 4. 54 55To use this library, create a class that extends from `IMapperV5Impl` and use `IMapperProvider` to 56implement `AIMapper_loadIMapper`: 57 58```c++ 59// The IMapper interface itself 60#include <android/hardware/graphics/mapper/IMapper.h> 61// Helpers for reading & writing metadata 62#include <android/hardware/graphics/mapper/utils/IMapperMetadataTypes.h> 63// Helper for providing the implementation interface 64#include <android/hardware/graphics/mapper/utils/IMapperProvider.h> 65 66// Define an IMapperV5 implementation 67class CrosGrallocMapperV5 final : public vendor::mapper::IMapperV5Impl { 68 // Override all the methods of IMapperV5Impl 69 AIMapper_Error importBuffer(const native_handle_t* _Nonnull handle, 70 buffer_handle_t _Nullable* _Nonnull outBufferHandle) override; 71 [etc...] 72}; 73 74// Expose the required C symbols 75 76extern "C" uint32_t ANDROID_HAL_STABLEC_VERSION = AIMAPPER_VERSION_5; 77 78extern "C" AIMapper_Error AIMapper_loadIMapper(AIMapper* _Nullable* _Nonnull outImplementation) { 79 // Define an IMapperProvider for our V5 implementation 80 static vendor::mapper::IMapperProvider<CrosGrallocMapperV5> provider; 81 return provider.load(outImplementation); 82} 83``` 84 85A complete example, including using IMapperMetadataTypes, can be found in the cuttlefish 86implementation in `//external/minigbm/cros_gralloc/mapper_stablec` 87 88### Testing 89 90As with HIDL & AIDL HALs, a VTS test is provided to validate the implementation. It is found in the 91`vts` folder and may be run using `$ atest VtsHalGraphicsMapperStableC_TargetTest` 92 93## Using 94 95It is strongly recommended that clients use either the `AHardwareBuffer` (preferred) or 96`GraphicBufferMapper` (from libui) APIs to use the mapper HAL rather than attempting to use 97`AIMapper` directly. 98 99## Version changes 100 101### Version 5 102 103* Initial introduction of this HAL interface 104* Largely feature-equivalent to IMapper4 105* Requires allocator-V2 106* Removes `BufferDescriptorInfo`; 107* IsSupported has moved to IAllocator 108* Removes `validateBufferSize`, validation is instead handled by clients using metadata queries 109* Getting the following StandardMetadataType is now mandatory: 110 * STRIDE 111* Setting the following StandardMetadataTypes is now mandatory: 112 * DATASPACE 113 * SMPTE2086 114 * CTA861_3 115 * BLEND_MODE 116