ManagedPort.hpp

Go to the documentation of this file.

 
//
// Notice
// ALL NVIDIA DESIGN SPECIFICATIONS AND CODE ("MATERIALS") ARE PROVIDED "AS IS" NVIDIA MAKES
// NO REPRESENTATIONS, WARRANTIES, EXPRESSED, IMPLIED, STATUTORY, OR OTHERWISE WITH RESPECT TO
// THE MATERIALS, AND EXPRESSLY DISCLAIMS ANY IMPLIED WARRANTIES OF NONINFRINGEMENT,
// MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
//
// NVIDIA CORPORATION & AFFILIATES assumes no responsibility for the consequences of use of such
// information or for any infringement of patents or other rights of third parties that may
// result from its use. No license is granted by implication or otherwise under any patent
// or patent rights of NVIDIA CORPORATION & AFFILIATES. No third party distribution is allowed unless
// expressly authorized by NVIDIA. Details are subject to change without notice.
// This code supersedes and replaces all information previously supplied.
// NVIDIA CORPORATION & AFFILIATES products are not authorized for use as critical
// components in life support devices or systems without express written approval of
// NVIDIA CORPORATION & AFFILIATES.
//
// SPDX-FileCopyrightText: Copyright (c) 2021-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: LicenseRef-NvidiaProprietary
//
// NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
// property and proprietary rights in and to this material, related
// documentation and any modifications thereto. Any use, reproduction,
// disclosure or distribution of this material and related documentation
// without an express license agreement from NVIDIA CORPORATION or
// its affiliates is strictly prohibited.
//
 
#ifndef DW_FRAMEWORK_MANAGEDPORT_HPP_
#define DW_FRAMEWORK_MANAGEDPORT_HPP_
 
#include <dwcgf/channel/Channel.hpp>
#include <dwcgf/port/Port.hpp>
#include <dwcgf/port/PortDescriptor.hpp>
#include <dwcgf/port/MetadataHelper.hpp>
#include <dwcgf/lockstep/ILockstepSyncClient.hpp>
#include <dwshared/dwfoundation/dw/core/language/Optional.hpp>
#include <dwshared/dwfoundation/dw/core/container/RingBuffer.hpp>
#include <dwshared/dwfoundation/dw/core/container/StringView.hpp>
#include <dwshared/dwfoundation/dw/core/language/Function.hpp>
#include <type_traits>
#include <utility>
 
namespace dw
{
namespace framework
{
 
class ManagedPortBase : public PortBase
{
public:
    ManagedPortBase(const dw::core::StringView& name);
 
    virtual ~ManagedPortBase() = default;
 
    ManagedPortBase(const ManagedPortBase& other) = delete;
    ManagedPortBase& operator=(const ManagedPortBase& other) = delete;
    ManagedPortBase(ManagedPortBase&& other)                 = delete;
    ManagedPortBase& operator=(ManagedPortBase&& other) = delete;
 
    virtual void bindChannel(ChannelObject* channel) = 0;
 
    void bindLockstepSyncClient(dw::framework::lockstep::ILockstepSyncClient* syncClient);
 
    virtual bool isBound() const noexcept = 0;
 
    const dw::core::StringView& getName() const;
 
    const dw::core::StringView& getNodeName() const;
 
    void setNodeName(const dw::core::StringView& nodeName) noexcept;
 
    void setCycleCount(uint32_t cycleCount);
 
    void setPeriod(uint32_t period);
 
    virtual void reset();
 
    ChannelObject* getChannel();
 
protected:
    dw::core::StringView m_name;
    dw::core::StringView m_nodeName;
    uint32_t m_cycleCount;
    uint32_t m_period;
    ChannelObject* m_channel;
    dw::framework::lockstep::ILockstepSyncClient* m_lockstepSyncClient;
};
 
class ManagedPortOutputBase : public ManagedPortBase
{
public:
    // Due to single TU checking
    // coverity[autosar_cpp14_a0_1_1_violation]
    static constexpr char LOG_TAG[]{"ManagedPortOutputBase"};
 
    struct ConstructProperties
    {
    };
 
    struct BoundProperties
    {
        bool syncEnabled = false;
    };
 
    struct Properties
    {
        ConstructProperties constructProperties;
        BoundProperties boundProperties;
    };
    bool isBufferAvailable() const noexcept;
 
    dw::core::VectorFixed<GenericData> getAllBuffers();
 
    void acquire();
 
    void send();
 
    const Properties& getProperties() const noexcept;
 
    void setCallbackBeforeSend(dw::core::Function<dwStatus()> callback);
 
    // Implemented inherited methods
    void bindChannel(ChannelObject* channel) override;
    bool isBound() const noexcept override;
 
    void reset() override;
 
    ChannelMetadata& getMetadata();
 
    void sendAdvTimestamp();
 
protected:
    explicit ManagedPortOutputBase(const dw::core::StringView& name, ConstructProperties props, GenericDataReference&& ref);
    GenericData getBufferGeneric();
 
private:
    static BoundProperties getBoundProperties(const ChannelObject& channel);
    void populateDefaultMetadata(ChannelMetadata& header);
    GenericDataReference m_ref;
    ChannelObject::Producer* m_channelProducer;
    Properties m_props;
    dw::core::Optional<GenericData> m_buffer;
    dw::core::Function<dwStatus()> m_callbackBeforeSend;
    uint32_t m_sendSeqNum;
};
 
class ManagedPortInputBase : public ManagedPortBase
{
public:
    using RingBuffer = dw::core::RingBuffer<GenericData>;
 
    struct ConstructProperties
    {
        uint32_t maxBuffers = 1U;
        dwTime_t waitTime = 0;
    };
 
    struct BoundProperties
    {
        bool enableReuse = false;
 
        bool syncEnabled = false;
        uint32_t dataOffset = 0U;
    };
 
    struct Properties
    {
        ConstructProperties constructProperties;
        BoundProperties boundProperties;
    };
 
    const Properties& getProperties() const noexcept;
 
    void recv();
 
    void release();
 
    void reset() override;
 
    bool isBufferAvailable() const noexcept;
 
    dw::core::VectorFixed<GenericData> getAllBuffers();
 
    // Implemented inherited methods
    void bindChannel(ChannelObject* channel) override;
    bool isBound() const noexcept override;
 
    void setCallbackAfterRecv(dw::core::Function<dwStatus()> callback);
 
    const ChannelMetadata& getMetadata();
 
    void sendAdvTimestamp();
 
protected:
    ManagedPortInputBase(const dw::core::StringView& name, ConstructProperties props, GenericDataReference&& ref);
    GenericData getBufferGeneric() const;
    GenericData popBufferGeneric();
    void releaseToChannel(void* data);
 
private:
    static BoundProperties getBoundProperties(const ChannelObject& channel);
    bool recvSingle(dwTime_t waitTime);
    bool stashConsumed();
    bool packetStashed(GenericData packet);
    void handleReuseDrop();
 
    void releaseSingle();
    bool postProcessLockstepReplayData(GenericData packet);
    dwTime_t getWaitTime();
    bool recvData();
    bool waitForData();
    void handleWaitFailure(dwStatus status);
    void handleCallbackAfterRecv();
 
    Properties m_props;
    GenericDataReference m_ref;
    ChannelObject::Consumer* m_channelConsumer;
    bool m_shouldDropFirstBuffer;
    dw::core::Function<dwStatus()> m_callbackAfterRecv;
 
protected:
    RingBuffer m_buffers;
    GenericData m_stashedFuturePacket;
    bool m_stashValid;
};
 
namespace detail
{
 
template <typename T>
// coverity[autosar_cpp14_a2_10_5_violation] FP: nvbugs/3907242
T* getBufferTyped(GenericData buffer)
{
    MetadataPayload* metadataPacket{extractMetadata(buffer)};
    T* ptr{metadataPacket->data.template getData<T>()};
 
    if (ptr == nullptr)
    {
        throw ExceptionWithStatus(DW_INVALID_ARGUMENT, "getBufferTyped: type mismatch");
    }
    return ptr;
}
 
// coverity[autosar_cpp14_a14_1_1_violation]
template <typename T>
struct vectorIterable
{
    explicit vectorIterable(dw::core::VectorFixed<GenericData> allBuffers)
        : m_allBuffers(std::move(allBuffers))
    {
    }
 
    // There are no specific requirements on the template type
    // coverity[autosar_cpp14_a14_1_1_violation]
    template <class TT>
    class iterator : public dw::core::VectorFixed<GenericData>::iterator
    {
    public:
        using Base = dw::core::VectorFixed<GenericData>::iterator;
        // Same naming is used in dwshared, hence keeping the iterator name and its accessors for now
        // coverity[cert_dcl51_cpp_violation]
        iterator(Base&& base)
            : Base(base)
        {
        }
 
        const Base& baseFromThis() const
        {
            return *this;
        }
 
        auto operator*() const
        {
            GenericData buffer = *baseFromThis();
            return getBufferTyped<TT>(buffer);
        }
    };
 
    // coverity[cert_dcl51_cpp_violation]
    iterator<T> begin() { return iterator<T>(m_allBuffers.begin()); }
 
    // coverity[cert_dcl51_cpp_violation]
    iterator<T> end() { return iterator<T>(m_allBuffers.end()); }
 
    // coverity[cert_dcl51_cpp_violation]
    iterator<const T> begin() const { return iterator<const T>(m_allBuffers.begin()); }
 
    // coverity[cert_dcl51_cpp_violation]
    iterator<const T> end() const { return iterator<const T>(m_allBuffers.end()); }
 
private:
    dw::core::VectorFixed<GenericData> m_allBuffers;
};
 
} // namespace detail
 
template <typename T>
class ManagedPortOutput : public ManagedPortOutputBase
{
    static_assert(parameter_traits<T>::IsDeclared,
                  "Channel packet type not declared. Ensure channel packet type "
                  "handling is declared with DWFRAMEWORK_DECLARE_PACKET_TYPE_POD "
                  "or DWFRAMEWORK_DECLARE_PACKET_TYPE_RELATION");
 
    using SpecimenT = typename parameter_traits<T>::SpecimenT;
 
public:
    template <typename T2 = T, typename std::enable_if_t<parameter_traits<T2>::PacketTID != DWFRAMEWORK_PACKET_ID_DEFAULT, void>* = nullptr>
    ManagedPortOutput(const dw::core::StringView& name, ConstructProperties props, SpecimenT& ref)
        : ManagedPortOutputBase(name, std::move(props), make_specimen<T>(&ref))
    {
    }
 
    template <typename T2 = T, typename std::enable_if_t<parameter_traits<T2>::PacketTID != DWFRAMEWORK_PACKET_ID_DEFAULT, void>* = nullptr>
    ManagedPortOutput(const dw::core::StringView& name, SpecimenT& ref)
        : ManagedPortOutputBase(name, {}, make_specimen<T>(&ref))
    {
    }
 
    template <typename T2 = T, typename std::enable_if_t<parameter_traits<T2>::PacketTID == DWFRAMEWORK_PACKET_ID_DEFAULT, void>* = nullptr>
    ManagedPortOutput(const dw::core::StringView& name, ConstructProperties props)
        : ManagedPortOutputBase(name, std::move(props), make_specimen<T>(nullptr))
    {
    }
 
    template <typename T2 = T, typename std::enable_if_t<parameter_traits<T2>::PacketTID == DWFRAMEWORK_PACKET_ID_DEFAULT, void>* = nullptr>
    ManagedPortOutput(const dw::core::StringView& name)
        : ManagedPortOutputBase(name, {}, make_specimen<T>(nullptr))
    {
    }
 
    // coverity[autosar_cpp14_a7_1_5_violation]
    auto getAllBufferIter()
    {
        return detail::vectorIterable<T>(getAllBuffers());
    }
 
    auto getBuffer() -> T*
    {
        return detail::getBufferTyped<T>(getBufferGeneric());
    }
};
 
template <typename T>
class ManagedPortInput : public ManagedPortInputBase
{
    static_assert(parameter_traits<T>::IsDeclared,
                  "Channel packet type not declared. Ensure channel packet type "
                  "handling is declared with DWFRAMEWORK_DECLARE_PACKET_TYPE_POD "
                  "or DWFRAMEWORK_DECLARE_PACKET_TYPE_RELATION");
    // coverity[autosar_cpp14_a0_1_6_violation]
    using SpecimenT = typename parameter_traits<T>::SpecimenT;
 
    struct PacketDeleter;
 
public:
    struct iterable;
 
    ManagedPortInput(const dw::core::StringView& name, ConstructProperties props)
        : ManagedPortInputBase(name, std::move(props), make_specimen<T>(nullptr))
    {
    }
 
    ManagedPortInput(const dw::core::StringView& name)
        : ManagedPortInputBase(name, {}, make_specimen<T>(nullptr))
    {
    }
 
    ManagedPortInput(const dw::core::StringView& name, ConstructProperties props, SpecimenT specimen)
        : ManagedPortInputBase(name, std::move(props), make_specimen<T>(&specimen))
    {
    }
 
    detail::vectorIterable<T> getAllBufferIter()
    {
        return detail::vectorIterable<T>(getAllBuffers());
    }
 
    iterable getBufferIter()
    {
        return iterable(*this);
    }
 
    auto getBuffer() -> T*
    {
        return detail::getBufferTyped<T>(getBufferGeneric());
    }
 
    auto getBufferIfAvailableAndValid() -> T*
    {
        if (isBufferAvailable())
        {
            const dw::core::Optional<dwValidityStatus> valid{getValidityStatus(getMetadata())};
            // At the moment if validity is not set it counts as valid
            // Once all the publishers set the validity signal it can be changed
            const bool isValid{!valid.has_value() || (valid->validity == DW_VALIDITY_VALID)};
            if (isValid)
            {
                return getBuffer();
            }
        }
        return nullptr;
    }
 
    auto getOptionalBuffer() -> T*
    {
        return isBufferAvailable() ? getBuffer() : nullptr;
    }
 
    using UniquePacketPtr = std::unique_ptr<T, PacketDeleter>;
 
    UniquePacketPtr takeOwnership()
    {
        GenericData packet{popBufferGeneric()};
        T* ptr{detail::getBufferTyped<T>(packet)};
        void* releasePtr{packet.getPointer()};
        return UniquePacketPtr(ptr, PacketDeleter{this, releasePtr});
    }
 
    struct iterable
    {
        explicit iterable(ManagedPortInput<T>& port)
            : m_port(port)
        {
        }
 
        // There are no specific requirements on the template type
        // coverity[autosar_cpp14_a14_1_1_violation]
        template <class TT>
        class iterator : public ManagedPortInputBase::RingBuffer::iterator
        {
            using Base = ManagedPortInputBase::RingBuffer::iterator;
 
        public:
            // Same naming is used in dwshared, hence keeping the iterator name and its accessors for now
            // coverity[cert_dcl51_cpp_violation]
            iterator(Base&& base, ManagedPortInput<T>& port)
                : Base(std::move(base))
                , m_port(port)
            {
            }
 
            const Base& baseFromThis() const
            {
                return *this;
            }
 
            auto operator*() const -> TT*
            {
                GenericData buffer{*baseFromThis()};
                return detail::getBufferTyped<TT>(buffer);
            }
 
        private:
            ManagedPortInput<T>& m_port;
        };
 
        // coverity[cert_dcl51_cpp_violation]
        iterator<T> begin() { return iterator<T>(m_port.m_buffers.begin(), m_port); }
 
        // coverity[cert_dcl51_cpp_violation]
        iterator<T> end() { return iterator<T>(m_port.m_buffers.end(), m_port); }
 
        // coverity[cert_dcl51_cpp_violation]
        iterator<const T> begin() const { return iterator<const T>(m_port.m_buffers.begin(), m_port); }
 
        // coverity[cert_dcl51_cpp_violation]
        iterator<const T> end() const { return iterator<const T>(m_port.m_buffers.end(), m_port); }
 
    private:
        ManagedPortInput<T>& m_port;
    };
 
private:
    struct PacketDeleter
    {
        void operator()(T* p)
        {
            static_cast<void>(p);
            port->releaseToChannel(releasePtr);
        }
        ManagedPortInput* port;
        void* releasePtr;
    };
};
 
template <typename T>
using UniquePacketPtr = typename ManagedPortInput<T>::UniquePacketPtr;
 
// Create a port type specimen for a given port index
namespace detail
{
template <
    typename NodeT,
    PortDirection Direction,
    uint64_t DescriptorIndex>
struct IsOutputNonPOD : std::integral_constant<bool, Direction == PortDirection::OUTPUT && parameter_traits<decltype(portDescriptorType<NodeT, Direction, DescriptorIndex>())>::PacketTID != DWFRAMEWORK_PACKET_ID_DEFAULT>
{
    static_assert(DescriptorIndex < portDescriptorSize<NodeT, Direction>(), "Invalid PortIndex.");
};
 
template <
    typename NodeT,
    PortDirection Direction,
    uint64_t DescriptorIndex>
typename std::enable_if<
    !IsOutputNonPOD<NodeT, Direction, DescriptorIndex>::value,
    GenericDataReference>::type
    // coverity[autosar_cpp14_a2_10_5_violation] FP: nvbugs/3907242
    createPortSpecimenByStaticIndex()
{
    GenericDataReference ref{make_specimen<decltype(portDescriptorType<NodeT, Direction, DescriptorIndex>())>(nullptr)};
    ref.packetTypeID = dw::core::safeAdd(static_cast<dw::framework::ChannelPacketTypeID>(DWFRAMEWORK_METADATA_PACKET_TYPE_ID_OFFSET), static_cast<uint32_t>(ref.packetTypeID)).value();
    return ref;
}
 
template <
    typename NodeT,
    PortDirection Direction,
    uint64_t DescriptorIndex>
typename std::enable_if<
    IsOutputNonPOD<NodeT, Direction, DescriptorIndex>::value,
    GenericDataReference>::type
    // coverity[autosar_cpp14_a2_10_5_violation] FP: nvbugs/3907242
    createPortSpecimenByStaticIndex()
{
    throw ExceptionWithStatus(DW_NOT_SUPPORTED, "createPortSpecimenByStaticIndex: Non POD output port is not supported");
}
 
template <
    typename NodeT,
    PortDirection Direction,
    uint64_t... Idx>
typename std::enable_if<(sizeof...(Idx) > 1), GenericDataReference>::type
    // coverity[autosar_cpp14_a2_10_5_violation] FP: nvbugs/4040101
    createPortSpecimenImpl(size_t descriptorIndex, std::index_sequence<Idx...>)
{
    constexpr size_t ArraySize{sizeof...(Idx)};
    if (descriptorIndex < ArraySize)
    {
        std::array<GenericDataReference, ArraySize> specimens{
            (Idx == descriptorIndex ? createPortSpecimenByStaticIndex<NodeT, Direction, Idx>() : GenericDataReference{})...};
        return specimens[descriptorIndex];
    }
    throw ExceptionWithStatus(DW_OUT_OF_BOUNDS, "createPortSpecimenImpl: index out of bound.");
}
 
// Above createPortSpecimenImpl actually covers correctly for all sizeof...(Idx)
// but AutoSAR complaining about dead code and unreachable code branch when sizeof...(Idx) == 1.
// Thus split it into three different implementations.
template <
    typename NodeT,
    PortDirection Direction,
    uint64_t... Idx>
typename std::enable_if<(sizeof...(Idx) == 1), GenericDataReference>::type
    // coverity[autosar_cpp14_a2_10_5_violation] FP: nvbugs/4040101
    createPortSpecimenImpl(size_t descriptorIndex, std::index_sequence<Idx...>)
{
    constexpr size_t ArraySize{sizeof...(Idx)};
    if (descriptorIndex < ArraySize)
    {
        return createPortSpecimenByStaticIndex<NodeT, Direction, 0>();
    }
    throw ExceptionWithStatus(DW_OUT_OF_BOUNDS, "createPortSpecimenImpl: index out of bound.");
}
 
template <
    typename NodeT,
    PortDirection Direction,
    uint64_t... Idx>
typename std::enable_if<(sizeof...(Idx) == 0), GenericDataReference>::type
    // coverity[autosar_cpp14_a2_10_5_violation] FP: nvbugs/4040101
    createPortSpecimenImpl(size_t, std::index_sequence<Idx...>)
{
    throw ExceptionWithStatus(DW_OUT_OF_BOUNDS, "createPortSpecimenImpl: index out of bound.");
}
 
template <
    typename NodeT,
    PortDirection Direction>
// coverity[autosar_cpp14_a2_10_5_violation] FP: nvbugs/4040101
GenericDataReference createPortSpecimen(size_t descriptorIndex)
{
    return detail::createPortSpecimenImpl<NodeT, Direction>(
        descriptorIndex,
        std::make_index_sequence<portDescriptorSize<NodeT, Direction>()>{});
}
} // namespace detail
 
} // namespace framework
} // namespace dw
 
#endif // DW_FRAMEWORK_MANAGEDPORT_HPP_