From 0124abc1e9a95fbacb0600b75d63fe0ac22c6053 Mon Sep 17 00:00:00 2001 From: John Reck Date: Wed, 4 Jan 2023 16:06:06 -0500 Subject: [PATCH] Add a README and a standardizable VERSION * Changes the compatbility matrix version to 5.0 & marks optional * Tweaks the interface name in case it doesn't get removed soon (otherwise readme looks silly) * Adds a README.md to mapper/stable-c * Adds VTS test to validate versions match Test: build + mapper VTS Change-Id: I9b1256e07aaf2876d579a5487d2051c60097fb70 --- .../compatibility_matrix.current.xml | 6 +- graphics/mapper/stable-c/README.md | 110 ++++++++++++++++++ ...VtsHalGraphicsMapperStableC_TargetTest.cpp | 12 ++ 3 files changed, 126 insertions(+), 2 deletions(-) create mode 100644 graphics/mapper/stable-c/README.md diff --git a/compatibility_matrices/compatibility_matrix.current.xml b/compatibility_matrices/compatibility_matrix.current.xml index 71afee3ac1..c665799b43 100644 --- a/compatibility_matrices/compatibility_matrix.current.xml +++ b/compatibility_matrices/compatibility_matrix.current.xml @@ -359,6 +359,7 @@ default + android.hardware.graphics.mapper @@ -846,9 +847,10 @@ default - + + mapper - 1.0 + 5.0 I .* diff --git a/graphics/mapper/stable-c/README.md b/graphics/mapper/stable-c/README.md new file mode 100644 index 0000000000..30f3ccc8f1 --- /dev/null +++ b/graphics/mapper/stable-c/README.md @@ -0,0 +1,110 @@ +# 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..so`. The `` should be specified +as the `` in the VINTF manifest `` section. For example: +```xml + + + mapper + 5.0 + + I + minigbm + + + +``` +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: +```c++ +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 +```c++ +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`: + +```c++ +// The IMapper interface itself +#include +// Helpers for reading & writing metadata +#include +// Helper for providing the implementation interface +#include + +// 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 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 diff --git a/graphics/mapper/stable-c/vts/VtsHalGraphicsMapperStableC_TargetTest.cpp b/graphics/mapper/stable-c/vts/VtsHalGraphicsMapperStableC_TargetTest.cpp index e29d16e637..2c0635346d 100644 --- a/graphics/mapper/stable-c/vts/VtsHalGraphicsMapperStableC_TargetTest.cpp +++ b/graphics/mapper/stable-c/vts/VtsHalGraphicsMapperStableC_TargetTest.cpp @@ -154,6 +154,7 @@ class GraphicsTestsBase { std::shared_ptr mAllocator; AIMapper* mIMapper = nullptr; AIMapper_loadIMapperFn mIMapperLoader; + int32_t* mIMapperHALVersion = nullptr; protected: void Initialize(std::shared_ptr allocator) { @@ -171,10 +172,12 @@ class GraphicsTestsBase { ASSERT_NE(nullptr, mIMapperLoader) << "AIMapper_locaIMapper missing from " << lib_name; ASSERT_EQ(AIMAPPER_ERROR_NONE, mIMapperLoader(&mIMapper)); ASSERT_NE(mIMapper, nullptr); + mIMapperHALVersion = (int32_t*)dlsym(so, "ANDROID_HAL_MAPPER_VERSION"); } public: AIMapper_loadIMapperFn getIMapperLoader() const { return mIMapperLoader; } + int32_t* getHalVersion() const { return mIMapperHALVersion; } std::unique_ptr allocate(const BufferDescriptorInfo& descriptorInfo) { AllocationResult result; @@ -557,6 +560,15 @@ class GraphicsMapperStableCTests void TearDown() override {} }; +TEST_P(GraphicsMapperStableCTests, VersionChecks) { + ASSERT_NE(nullptr, getHalVersion()) << "Resolving ANDROID_HAL_MAPPER_VERSION symbol failed"; + int32_t halVersion = *getHalVersion(); + EXPECT_EQ(halVersion, AIMAPPER_VERSION_5) << "Unrecognized ANDROID_HAL_MAPPER_VERSION"; + EXPECT_EQ(mapper()->version, AIMAPPER_VERSION_5) << "Unrecognized AIMapper::version"; + EXPECT_EQ(halVersion, mapper()->version) + << "AIMapper version & ANDROID_HAL_MAPPER_VERSION don't agree"; +} + TEST_P(GraphicsMapperStableCTests, AllV5CallbacksDefined) { ASSERT_GE(mapper()->version, AIMAPPER_VERSION_5);