path: root/transport/token/1.0/utils/include/hidl/HybridInterface.h

/*
 * Copyright (C) 2017 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.
 */

#ifndef ANDROID_HYBRIDINTERFACE_H
#define ANDROID_HYBRIDINTERFACE_H

#include <vector>
#include <mutex>

#include <binder/Parcel.h>
#include <hidl/HidlSupport.h>

#include <cinttypes>
#include <variant>

/**
 * Hybrid Interfaces
 * =================
 *
 * A hybrid interface is a binder interface that
 * 1. is implemented both traditionally and as a wrapper around a hidl
 *    interface, and allows querying whether the underlying instance comes from
 *    a hidl interface or not; and
 * 2. allows efficient calls to a hidl interface (if the underlying instance
 *    comes from a hidl interface) by automatically creating the wrapper in the
 *    process that calls it.
 *
 * Terminology:
 * - `HalToken`: The type for a "token" of a hidl interface. This is defined to
 *   be compatible with `ITokenManager.hal`.
 * - `HInterface`: The base type for a hidl interface. Currently, it is defined
 *   as `::android::hidl::base::V1_0::IBase`.
 * - `HALINTERFACE`: The hidl interface that will be sent through binders.
 * - `INTERFACE`: The binder interface that will be the wrapper of
 *   `HALINTERFACE`. `INTERFACE` is supposed to be somewhat similar to
 *   `HALINTERFACE`.
 *
 * To demonstrate how this is done, here is an example. Suppose `INTERFACE` is
 * `IFoo` and `HALINTERFACE` is `HFoo`. The required steps are:
 * 1. Use `DECLARE_HYBRID_META_INTERFACE` instead of `DECLARE_META_INTERFACE` in
 *    the declaration of `IFoo`. `DECLARE_HYBRID_META_INTERFACE` takes an
 *    additional argument that is the hidl interface to be converted into a
 *    binder interface. Example:
 *        Change from `DECLARE_META_INTERFACE(Foo)`
 *                 to `DECLARE_HYBRID_META_INTERFACE(Foo, HFoo)`
 * 2. Create a converter class that derives from
 *    `H2BConverter<HFoo, BnFoo>`. Let us call this `H2BFoo`.
 * 3. Add the following constructor in `H2BFoo` that call the corresponding
 *    constructors in `H2BConverter`:
 *        `H2BFoo(const sp<HalInterface>& base) : CBase(base) {}`
 *    Note: `CBase = H2BConverter<HFoo, BnFoo>` and `HalInterface = HFoo` are
 *    member typedefs of `H2BConverter<HFoo, BnFoo>`, so the above line can be
 *    copied verbatim into `H2BFoo`.
 * 4. Implement `IFoo` in `H2BFoo` on top of `HFoo`. `H2BConverter` provides a
 *    protected `mBase` of type `sp<HFoo>` that can be used to access the `HFoo`
 *    instance. (There is also a public function named `getBase()` that returns
 *    `mBase`.)
 * 5. Create a hardware proxy class that derives from
 *    `HpInterface<BpFoo, H2BFoo>`. Name this class `HpFoo`. (This name cannot
 *    deviate. See step 8 below.)
 * 6. Add the following constructor to `HpFoo`:
 *        `HpFoo(const sp<IBinder>& base): PBase(base) {}`
 *    Note: `PBase` a member typedef of `HpInterface<BpFoo, H2BFoo>` that is
 *    equal to `HpInterface<BpFoo, H2BFoo>` itself, so the above line can be
 *    copied verbatim into `HpFoo`.
 * 7. Delegate all functions in `HpFoo` that come from `IFoo` (except those that
 *    are defined by the macro `DECLARE_HYBRID_META_INTERFACE`) to the protected
 *    member `mBase`. `mBase` is defined in `HpInterface<BpFoo, H2BFoo>` (hence
 *    in `HpFoo`) with type `IFoo`. There is also a public function named
 *    `getBase()` that returns `mBase`.
 * 8. Replace the existing `IMPLEMENT_META_INTERFACE` for `IFoo` by
 *    `IMPLEMENT_HYBRID_META_INTERFACE`. This macro assumes that the subclass of
 *    `HpInterface` for `IFoo` is named `HpFoo`.
 *
 * After the hybrid interface has been put in place properly, it can be used to
 * do the following tasks:
 * 1. Create an `IFoo` instance from an `HFoo` by passing `sp<HFoo>` to
 *    the constructor of `H2BFoo`.
 * 2. Retrieve an `HFoo` from an `HpFoo` instance by calling
 *    `HpFoo::getHalInterface<HFoo>()`. This function may return `nullptr` if
 *    the `HpFoo` object is not backed by `HFoo`. The template parameter is
 *    required because `HpFoo` in fact may be backed by multiple H2B converter
 *    classes.
 *
 * Multiple H2B Converters
 * =======================
 *
 * Because the system may support multiple versions of hidl interfaces for the
 * same object, one binder interface may correspond to multiple H2B converters.
 * The hybrid interface is designed to handle this as
 * well---`DECLARE_HYBRID_META_INTERFACE` and `HpInterface` can take a variable
 * number of arguments.
 *
 * As a concrete example, suppose `IFoo` is a binder interface that corresponds
 * to two hidl interfaces `HFoo1` and `HFoo2`. That means `HpFoo`, the hybrid
 * interface presenting `IFoo`, may be backed by `HFoo1` or `HFoo2`. This is
 * achievable by
 *
 *   - Replacing `DECLARE_META_INTERFACE(Foo)` by
 *     `DECLARE_HYBRID_META_INTERFACE(Foo, HFoo1, HFoo2)` in the declaration of
 *     `IFoo`.
 *   - Creating `H2BFoo1` as a subclass of `H2BConverter<HFoo1, BnFoo>`;
 *   - Creating `H2BFoo2` as a subclass of `H2BConverter<HFoo2, BnFoo>`; and
 *   - Creating `HpFoo` as a subclass of `HpInterface<BpFoo, H2BFoo1, H2BFoo2>`.
 *
 * It is important that `HFoo1` and `HFoo2` are different hidl interfaces. [The
 * actual requirement is that for each pair `<HFoo, IFoo>`, there can be only
 * one subclass of `H2BConverter<HFoo, BnFoo>`.]
 *
 * As mentioned in the previous section, `HpFoo::getHalInterface` requires a
 * template argument because it must be able to return different hidl
 * interface types based on which hidl interface is being used. The user of
 * `HpFoo` can query the type of the underlying hidl interface by calling
 * `HpFoo::getHalIndex()`. The return value is a 1-based index into the list of
 * all the supported hidl interfaces. In the example with 2 hidl interfaces
 * `HFoo1` and `HFoo2`, index 1 corresponds to `HFoo1` and index 2 corresponds
 * to `HFoo2`. A typical code block that accesses the underlying hidl interface
 * of would look like this:
 *
 * void someFunction(const sp<IFoo> &foo) {
 *
 *     switch (foo->getHalIndex()) {
 *     case 1: {
 *             sp<HFoo1> hFoo1 = foo->getHalInterface<HFoo1>();
 *             ...
 *             break;
 *         }
 *     case 2: {
 *             sp<HFoo2> hFoo2 = foo->getHalInterface<HFoo2>();
 *             ...
 *             break;
 *         }
 *     default: // Not backed by a hidl interface.
 *              // Alternatively, "case 0:" can be used.
 *     }
 *
 * }
 *
 * Error State
 * ===========
 *
 * A corrupted transaction may cause an `HpInterface` to be in an error state.
 * This could cause `getHalInterface<ExpectedHalInterface>()` to return
 * `nullptr` even though `getHalIndex()` returns a non-zero index and
 * `ExpectedHalInterface` is the corresponding hidl interface. It is therefore
 * recommended that a null check be performed on the return value of
 * `getHalInterface` before using it.
 *
 * DECLARE_HYBRID_META_INTERFACE_WITH_CODE
 * =======================================
 *
 * `H2BConverter` and `HpInterface` use `transact()` to send over tokens with
 * the transaction code (the first argument of `transact()`) equal to `_GHT`,
 * which is defined as a global constant named
 * `DEFAULT_GET_HAL_TOKEN_TRANSACTION_CODE`.
 *
 * In the rare occasion that this value clashes with other values already used
 * by the `Bp` class and modifying the `Bp` class is difficult, the
 * "GET_HAL_TOKEN" transaction code can be changed to a different value simply
 * by replacing `DECLARE_HYBRID_META_INTERFACE` with
 * `DECLARE_HYBRID_META_INTERFACE_WITH_CODE` in the declaration of the base
 * interface and supplying the new transaction code in the first argument of
 * this macro.
 *
 */

namespace android {

typedef ::android::hardware::hidl_vec<uint8_t> HalToken;
typedef ::android::hidl::base::V1_0::IBase HInterface;

constexpr uint32_t DEFAULT_GET_HAL_TOKEN_TRANSACTION_CODE =
        B_PACK_CHARS('_', 'G', 'H', 'T');

sp<HInterface> retrieveHalInterface(const HalToken& token);
bool createHalToken(const sp<HInterface>& interface, HalToken* token);
bool deleteHalToken(const HalToken& token);

template <typename HINTERFACE,
          typename BNINTERFACE>
class H2BConverter : public BNINTERFACE {
public:
    typedef H2BConverter<HINTERFACE, BNINTERFACE> CBase; // Converter Base
    typedef typename BNINTERFACE::BaseInterface BaseInterface;
    typedef HINTERFACE HalInterface;
    typedef typename BaseInterface::HalVariant HalVariant;
    using BaseInterface::sGetHalTokenTransactionCode;

    H2BConverter(const sp<HalInterface>& base) : mBase{base} {}
    virtual status_t onTransact(uint32_t code,
            const Parcel& data, Parcel* reply, uint32_t flags = 0);
    virtual status_t linkToDeath(
            const sp<IBinder::DeathRecipient>& recipient,
            void* cookie = nullptr,
            uint32_t flags = 0);
    virtual status_t unlinkToDeath(
            const wp<IBinder::DeathRecipient>& recipient,
            void* cookie = nullptr,
            uint32_t flags = 0,
            wp<IBinder::DeathRecipient>* outRecipient = nullptr);
    virtual HalVariant getHalVariant() const override { return { mBase }; }
    HalInterface* getBase() { return mBase.get(); }

protected:
    sp<HalInterface> mBase;

private:
    struct Obituary : public hardware::hidl_death_recipient {
        wp<IBinder::DeathRecipient> recipient;
        void* cookie;
        uint32_t flags;
        wp<IBinder> who;
        Obituary(
                const wp<IBinder::DeathRecipient>& r,
                void* c, uint32_t f,
                const wp<IBinder>& w) :
            recipient(r), cookie(c), flags(f), who(w) {
        }
        Obituary(const Obituary& o) :
            recipient(o.recipient),
            cookie(o.cookie),
            flags(o.flags),
            who(o.who) {
        }
        Obituary& operator=(const Obituary& o) {
            recipient = o.recipient;
            cookie = o.cookie;
            flags = o.flags;
            who = o.who;
            return *this;
        }
        void serviceDied(uint64_t, const wp<HInterface>&) override {
            sp<IBinder::DeathRecipient> dr = recipient.promote();
            if (dr != nullptr) {
                dr->binderDied(who);
            }
        }
    };
    std::mutex mObituariesLock;
    std::vector<sp<Obituary> > mObituaries;

    template <size_t Index = std::variant_size_v<HalVariant> - 1>
    static constexpr size_t _findIndex() {
        if constexpr (Index == 0) {
            return Index;
        } else if constexpr (
                std::is_same_v<
                    std::variant_alternative_t<Index, HalVariant>,
                    sp<HalInterface>>) {
            return Index;
        } else {
            return _findIndex<Index - 1>();
        }
    }

    static constexpr size_t sHalIndex = _findIndex<>();
    static_assert(sHalIndex != 0,
                  "H2BConverter from an unrecognized HAL interface.");
};

template <typename BPINTERFACE, typename CONVERTER, typename... CONVERTERS>
class HpInterface : public CONVERTER::BaseInterface {
public:
    typedef HpInterface<BPINTERFACE, CONVERTER, CONVERTERS...> PBase; // Proxy Base
    typedef typename CONVERTER::BaseInterface BaseInterface;
    typedef typename BaseInterface::HalVariant HalVariant;
    using BaseInterface::sGetHalTokenTransactionCode;

    explicit HpInterface(const sp<IBinder>& impl);
    BaseInterface* getBase() { return mBase.get(); }
    virtual HalVariant getHalVariant() const override { return mHalVariant; }

protected:
    IBinder* mBpBinder;
    sp<BPINTERFACE> mBp;
    sp<BaseInterface> mBase;
    HalVariant mHalVariant;
    bool mHasConverter{false};
    IBinder* onAsBinder() override { return mBpBinder; }

private:
    typedef std::variant<std::monostate,
            CONVERTER, CONVERTERS...> _ConverterVar;
    typedef std::variant<std::monostate,
            typename CONVERTER::HalInterface,
            typename CONVERTERS::HalInterface...> _ConverterHalVar;
    typedef std::variant<std::monostate,
            sp<typename CONVERTER::HalInterface>,
            sp<typename CONVERTERS::HalInterface>...> _ConverterHalPointerVar;

    static_assert(std::is_same_v<_ConverterHalPointerVar, HalVariant>,
                  "Converter classes do not match HAL interfaces.");

    template <size_t Index = std::variant_size_v<HalVariant> - 1>
    bool _castFromHalBaseAndConvert(size_t halIndex,
                                    const sp<HInterface>& halBase) {
        if constexpr (Index == 0) {
            return false;
        } else {
            if (halIndex != Index) {
                return _castFromHalBaseAndConvert<Index - 1>(halIndex, halBase);
            }
            typedef std::variant_alternative_t<Index, _ConverterHalVar>
                    HalInterface;
            sp<HalInterface> halInterface = HalInterface::castFrom(halBase);
            mHalVariant.template emplace<Index>(halInterface);
            if (!halInterface) {
                return false;
            }
            if (mHasConverter) {
                typedef std::variant_alternative_t<Index, _ConverterVar>
                        Converter;
                sp<Converter> converter = new Converter(halInterface);
                if (converter) {
                    mBase = converter;
                } else {
                    ALOGW("HpInterface: Failed to create an H2B converter -- "
                          "index = %zu.", Index);
                }
            }
            return true;
        }
    }

    bool castFromHalBaseAndConvert(size_t halIndex,
                                   const sp<HInterface>& halBase) {
        if (!_castFromHalBaseAndConvert<>(halIndex, halBase)) {
            return false;
        }
        return true;
    }

};

// ----------------------------------------------------------------------

#define DECLARE_HYBRID_META_INTERFACE(INTERFACE, ...)                     \
        DECLARE_HYBRID_META_INTERFACE_WITH_CODE(                          \
            ::android::DEFAULT_GET_HAL_TOKEN_TRANSACTION_CODE,            \
            INTERFACE, __VA_ARGS__)                                       \


#define DECLARE_HYBRID_META_INTERFACE_WITH_CODE(GTKCODE, INTERFACE, ...)  \
private:                                                                  \
    typedef ::std::variant<::std::monostate, __VA_ARGS__> _HalVariant;    \
    template <typename... Types>                                          \
    using _SpVariant =                                                    \
            ::std::variant<::std::monostate, ::android::sp<Types>...>;    \
public:                                                                   \
    typedef _SpVariant<__VA_ARGS__> HalVariant;                           \
    virtual HalVariant getHalVariant() const;                             \
    size_t getHalIndex() const;                                           \
    template <size_t Index>                                               \
    using HalInterface = ::std::variant_alternative_t<Index, _HalVariant>;\
    template <typename HAL>                                               \
    sp<HAL> getHalInterface() const {                                     \
        HalVariant halVariant = getHalVariant();                          \
        const sp<HAL>* hal = std::get_if<sp<HAL>>(&halVariant);           \
        return hal ? *hal : nullptr;                                      \
    }                                                                     \
                                                                          \
    static const ::android::String16 descriptor;                          \
    static ::android::sp<I##INTERFACE> asInterface(                       \
            const ::android::sp<::android::IBinder>& obj);                \
    virtual const ::android::String16& getInterfaceDescriptor() const;    \
    I##INTERFACE();                                                       \
    virtual ~I##INTERFACE();                                              \
    static constexpr uint32_t sGetHalTokenTransactionCode = GTKCODE;      \


#define IMPLEMENT_HYBRID_META_INTERFACE(INTERFACE, NAME)                  \
    I##INTERFACE::HalVariant I##INTERFACE::getHalVariant() const {        \
        return HalVariant{std::in_place_index<0>};                        \
    }                                                                     \
    size_t I##INTERFACE::getHalIndex() const {                            \
        return getHalVariant().index();                                   \
    }                                                                     \
    constexpr uint32_t I##INTERFACE::sGetHalTokenTransactionCode;         \
    const ::android::String16 I##INTERFACE::descriptor(NAME);             \
    const ::android::String16&                                            \
            I##INTERFACE::getInterfaceDescriptor() const {                \
        return I##INTERFACE::descriptor;                                  \
    }                                                                     \
    ::android::sp<I##INTERFACE> I##INTERFACE::asInterface(                \
            const ::android::sp<::android::IBinder>& obj)                 \
    {                                                                     \
        ::android::sp<I##INTERFACE> intr;                                 \
        if (obj != nullptr) {                                             \
            intr = static_cast<I##INTERFACE*>(                            \
                obj->queryLocalInterface(                                 \
                        I##INTERFACE::descriptor).get());                 \
            if (intr == nullptr) {                                        \
                intr = new Hp##INTERFACE(obj);                            \
            }                                                             \
        }                                                                 \
        return intr;                                                      \
    }                                                                     \
    I##INTERFACE::I##INTERFACE() { }                                      \
    I##INTERFACE::~I##INTERFACE() { }                                     \

// ----------------------------------------------------------------------

template <typename HINTERFACE,
          typename BNINTERFACE>
status_t H2BConverter<HINTERFACE, BNINTERFACE>::
        onTransact(
        uint32_t code, const Parcel& data, Parcel* reply, uint32_t flags) {
    if (code == sGetHalTokenTransactionCode) {
        if (!data.enforceInterface(BaseInterface::getInterfaceDescriptor())) {
            return BAD_TYPE;
        }

        HalToken token;
        bool result;
        result = createHalToken(mBase, &token);
        // Write whether a HAL token is present.
        reply->writeBool(result);
        if (!result) {
            ALOGE("H2BConverter: Failed to create HAL token.");
            return NO_ERROR;
        }

        // Write the HAL token.
        reply->writeByteArray(token.size(), token.data());

        // Write the HAL index.
        reply->writeUint32(static_cast<uint32_t>(sHalIndex));

        // Write a flag indicating that a converter needs to be created.
        reply->writeBool(true);

        return NO_ERROR;
    }
    return BNINTERFACE::onTransact(code, data, reply, flags);
}

template <typename HINTERFACE,
          typename BNINTERFACE>
status_t H2BConverter<HINTERFACE, BNINTERFACE>::linkToDeath(
        const sp<IBinder::DeathRecipient>& recipient,
        void* cookie, uint32_t flags) {
    LOG_ALWAYS_FATAL_IF(
            recipient == nullptr,
            "linkToDeath(): recipient must not be null.");
    {
        std::lock_guard<std::mutex> lock(mObituariesLock);
        mObituaries.push_back(new Obituary(recipient, cookie, flags, this));
        if (!mBase->linkToDeath(mObituaries.back(), 0)) {
           return DEAD_OBJECT;
        }
    }
    return NO_ERROR;
}

template <typename HINTERFACE,
          typename BNINTERFACE>
status_t H2BConverter<HINTERFACE, BNINTERFACE>::unlinkToDeath(
        const wp<IBinder::DeathRecipient>& recipient,
        void* cookie, uint32_t flags,
        wp<IBinder::DeathRecipient>* outRecipient) {
    std::lock_guard<std::mutex> lock(mObituariesLock);
    for (auto i = mObituaries.begin(); i != mObituaries.end(); ++i) {
        if ((flags = (*i)->flags) && (
                (recipient == (*i)->recipient) ||
                ((recipient == nullptr) && (cookie == (*i)->cookie)))) {
            if (outRecipient != nullptr) {
                *outRecipient = (*i)->recipient;
            }
            bool success = mBase->unlinkToDeath(*i);
            mObituaries.erase(i);
            return success ? NO_ERROR : DEAD_OBJECT;
        }
    }
    return NAME_NOT_FOUND;
}

template <typename BPINTERFACE, typename CONVERTER, typename... CONVERTERS>
HpInterface<BPINTERFACE, CONVERTER, CONVERTERS...>::HpInterface(
        const sp<IBinder>& impl)
      : mBpBinder{impl.get()},
        mBp{new BPINTERFACE(impl)} {
    mBase = mBp;
    if (!mBpBinder->remoteBinder()) {
        return;
    }
    Parcel data, reply;
    data.writeInterfaceToken(BaseInterface::getInterfaceDescriptor());
    if (mBpBinder->transact(sGetHalTokenTransactionCode,
                            data, &reply) == NO_ERROR) {
        // Read whether a HAL token is present.
        bool tokenCreated;
        if (reply.readBool(&tokenCreated) != OK) {
            ALOGW("HpInterface: Corrupted parcel from GET_HAL_TOKEN "
                  "(tokenCreated).");
        }

        if (!tokenCreated) {
            ALOGW("HpInterface: No HAL token was created.");
            return;
        }

        // Read the HAL token.
        std::vector<uint8_t> tokenVector;
        if (reply.readByteVector(&tokenVector) != OK) {
            ALOGW("HpInterface: Corrupted parcel from GET_HAL_TOKEN "
                  "(halToken).");
            return;
        }

        // Retrieve the HAL interface from the token.
        HalToken token{tokenVector};
        sp<HInterface> halBase = retrieveHalInterface(token);
        deleteHalToken(token);

        if (!halBase) {
            ALOGW("HpInterface: Failed to retrieve HAL interface.");
            return;
        }

        uint32_t halIndex;
        // Read the hal index.
        if (reply.readUint32(&halIndex) != OK) {
            ALOGW("HpInterface: Corrupted parcel from GET_HAL_TOKEN "
                  "(halIndex).");
            return;
        }

        // Read the converter flag.
        if (reply.readBool(&mHasConverter) != OK) {
            ALOGW("HpInterface: Corrupted parcel from GET_HAL_TOKEN "
                  "(hasConverter).");
            return;
        }

        // Call castFrom from the right HAL interface and create a converter if
        // needed.
        if (!castFromHalBaseAndConvert(static_cast<size_t>(halIndex),
                                       halBase)) {
            ALOGW("HpInterface: Failed to cast to the correct HAL interface -- "
                  "HAL index = %" PRIu32 ".", halIndex);
        }
    }
}

// ----------------------------------------------------------------------

}; // namespace android

#endif // ANDROID_HYBRIDINTERFACE_H