LNMAccessorPlugin.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: Deutsches Elektronen-Synchrotron DESY, MSK, ChimeraTK Project <chimeratk-support@desy.de>
// SPDX-License-Identifier: LGPL-3.0-or-later
#pragma once
 
#include "LNMBackendRegisterInfo.h"
#include "LogicalNameMappingBackend.h"
#include "VirtualFunctionTemplate.h"
 
#include <optional>
#include <utility>
 
namespace ChimeraTK::LNMBackend {
 
  struct UndecoratedParams {
    UndecoratedParams(const std::string& name, size_t numberOfWords, size_t wordOffsetInRegister, AccessModeFlags flags)
    : _name(name), _numberOfWords(numberOfWords), _wordOffsetInRegister(wordOffsetInRegister),
      _flags(std::move(flags)) {}
    std::string _name;
    size_t _numberOfWords;
    size_t _wordOffsetInRegister;
    AccessModeFlags _flags;
  };
 
  class AccessorPluginBase {
   public:
    explicit AccessorPluginBase(const LNMBackendRegisterInfo& info);
    virtual ~AccessorPluginBase() = default;
 
    template<typename UserType>
    boost::shared_ptr<NDRegisterAccessor<UserType>> getAccessor(boost::shared_ptr<LogicalNameMappingBackend> backend,
        size_t numberOfWords, size_t wordOffsetInRegister, AccessModeFlags flags, size_t pluginIndex) {
      return CALL_VIRTUAL_FUNCTION_TEMPLATE(
          getAccessor_impl, UserType, backend, numberOfWords, wordOffsetInRegister, flags, pluginIndex);
    }
    DEFINE_VIRTUAL_FUNCTION_TEMPLATE_VTABLE(getAccessor_impl,
        boost::shared_ptr<NDRegisterAccessor<T>>(
            boost::shared_ptr<LogicalNameMappingBackend>, size_t, size_t, AccessModeFlags, size_t));
 
    void updateRegisterInfo(BackendRegisterCatalogue<LNMBackendRegisterInfo>&);
 
    virtual void doRegisterInfoUpdate() = 0;
 
    virtual void openHook(const boost::shared_ptr<LogicalNameMappingBackend>& backend) { std::ignore = backend; }
 
    virtual void postParsingHook([[maybe_unused]] const boost::shared_ptr<const LogicalNameMappingBackend>& backend) {}
 
    virtual void closeHook() {}
 
    virtual void exceptionHook() {}
 
   protected:
    LNMBackendRegisterInfo _info;
  };
 
  template<typename Derived>
  class AccessorPlugin : public AccessorPluginBase {
   public:
    explicit AccessorPlugin(const LNMBackendRegisterInfo& info, size_t pluginIndex);
 
   private:
    // we make our destructor private and add Derived as a friend to enforce the correct CRTP
    ~AccessorPlugin() override = default;
    friend Derived;
 
   public:
    virtual DataType getTargetDataType(DataType userType) const { return userType; }
 
    template<typename UserType, typename TargetType>
    boost::shared_ptr<NDRegisterAccessor<UserType>> decorateAccessor(
        boost::shared_ptr<LogicalNameMappingBackend>& backend,
        boost::shared_ptr<NDRegisterAccessor<TargetType>>& target, const UndecoratedParams& accessorParams);
 
    template<typename UserType>
    boost::shared_ptr<NDRegisterAccessor<UserType>> getAccessor_impl(
        boost::shared_ptr<LogicalNameMappingBackend>& backend, size_t numberOfWords, size_t wordOffsetInRegister,
        AccessModeFlags flags, size_t pluginIndex);
 
    size_t _pluginIndex;
  };
 
  /********************************************************************************************************************/
 
  boost::shared_ptr<AccessorPluginBase> makePlugin(LNMBackendRegisterInfo info, size_t pluginIndex,
      const std::string& name, const std::map<std::string, std::string>& parameters);
 
  /********************************************************************************************************************/
  /* Known plugins are defined below (implementations should go to a separate .cc file)                               */
  /********************************************************************************************************************/
 
  class MultiplierPlugin : public AccessorPlugin<MultiplierPlugin> {
   public:
    MultiplierPlugin(
        const LNMBackendRegisterInfo& info, size_t pluginIndex, const std::map<std::string, std::string>& parameters);
 
    void doRegisterInfoUpdate() override;
    DataType getTargetDataType(DataType) const override { return DataType::float64; }
 
    template<typename UserType, typename TargetType>
    boost::shared_ptr<NDRegisterAccessor<UserType>> decorateAccessor(
        boost::shared_ptr<LogicalNameMappingBackend>& backend,
        boost::shared_ptr<NDRegisterAccessor<TargetType>>& target, const UndecoratedParams& accessorParams);
 
    double _factor;
  };
 
  /********************************************************************************************************************/
 
  class MonostableTriggerPlugin : public AccessorPlugin<MonostableTriggerPlugin> {
   public:
    MonostableTriggerPlugin(
        LNMBackendRegisterInfo info, size_t pluginIndex, const std::map<std::string, std::string>& parameters);
 
    void doRegisterInfoUpdate() override;
    DataType getTargetDataType(DataType) const override { return DataType::uint32; }
 
    template<typename UserType, typename TargetType>
    boost::shared_ptr<NDRegisterAccessor<UserType>> decorateAccessor(
        boost::shared_ptr<LogicalNameMappingBackend>& backend,
        boost::shared_ptr<NDRegisterAccessor<TargetType>>& target, const UndecoratedParams& accessorParams);
 
    double _milliseconds;
    uint32_t _active{1};
    uint32_t _inactive{0};
  };
 
  class ForceReadOnlyPlugin : public AccessorPlugin<ForceReadOnlyPlugin> {
   public:
    ForceReadOnlyPlugin(
        const LNMBackendRegisterInfo& info, size_t pluginIndex, const std::map<std::string, std::string>& parameters);
 
    void doRegisterInfoUpdate() override;
 
    template<typename UserType, typename TargetType>
    boost::shared_ptr<NDRegisterAccessor<UserType>> decorateAccessor(
        boost::shared_ptr<LogicalNameMappingBackend>& backend,
        boost::shared_ptr<NDRegisterAccessor<TargetType>>& target, const UndecoratedParams& accessorParams);
  };
 
  class ForcePollingReadPlugin : public AccessorPlugin<ForcePollingReadPlugin> {
   public:
    ForcePollingReadPlugin(
        const LNMBackendRegisterInfo& info, size_t pluginIndex, const std::map<std::string, std::string>& parameters);
 
    void doRegisterInfoUpdate() override;
 
    template<typename UserType, typename TargetType>
    boost::shared_ptr<NDRegisterAccessor<UserType>> decorateAccessor(
        boost::shared_ptr<LogicalNameMappingBackend>& backend,
        boost::shared_ptr<NDRegisterAccessor<TargetType>>& target, const UndecoratedParams& accessorParams);
  };
 
  class SetDescriptionPlugin : public AccessorPlugin<SetDescriptionPlugin> {
   public:
    SetDescriptionPlugin(
        const LNMBackendRegisterInfo& info, size_t pluginIndex, const std::map<std::string, std::string>& parameters);
 
    void doRegisterInfoUpdate() override;
 
    template<typename UserType, typename TargetType>
    boost::shared_ptr<NDRegisterAccessor<UserType>> decorateAccessor(
        boost::shared_ptr<LogicalNameMappingBackend>& backend,
        boost::shared_ptr<NDRegisterAccessor<TargetType>>& target, const UndecoratedParams& accessorParams);
 
   private:
    std::optional<std::string> _engineeringUnit;
    std::optional<std::string> _description;
  };
 
  class TypeHintModifierPlugin : public AccessorPlugin<TypeHintModifierPlugin> {
   public:
    TypeHintModifierPlugin(
        const LNMBackendRegisterInfo& info, size_t pluginIndex, const std::map<std::string, std::string>& parameters);
 
    void doRegisterInfoUpdate() override;
 
   private:
    DataType _dataType{DataType::none};
  };
 
  class BitRangeAccessPlugin : public AccessorPlugin<BitRangeAccessPlugin> {
   public:
    BitRangeAccessPlugin(
        const LNMBackendRegisterInfo& info, size_t pluginIndex, const std::map<std::string, std::string>& parameters);
 
    template<typename UserType, typename TargetType>
    boost::shared_ptr<NDRegisterAccessor<UserType>> decorateAccessor(
        boost::shared_ptr<LogicalNameMappingBackend>& backend,
        boost::shared_ptr<NDRegisterAccessor<TargetType>>& target, const UndecoratedParams& accessorParams);
 
    void doRegisterInfoUpdate() override;
    DataType getTargetDataType(DataType /*userType*/) const override { return DataType::uint64; }
    uint32_t _shift{0};
    uint32_t _numberOfBits{0};
    bool _writeable{true};
    int32_t dataInterpretationFractionalBits{0};
    bool dataInterpretationIsSigned{false};
  };
 
  class TagModifierPlugin : public AccessorPlugin<TagModifierPlugin> {
   public:
    TagModifierPlugin(
        const LNMBackendRegisterInfo& info, size_t pluginIndex, const std::map<std::string, std::string>& parameters);
 
    void doRegisterInfoUpdate() override;
 
   private:
    std::set<std::string> _tagsToAdd;
    std::set<std::string> _tagsToRemove;
    std::set<std::string> _tagsToSet;
  };
 
  template<auto Tag>
  class FixedTagModifierPlugin : public TagModifierPlugin {
   public:
    FixedTagModifierPlugin(const LNMBackendRegisterInfo& info, size_t pluginIndex,
        [[maybe_unused]] const std::map<std::string, std::string>& parameters)
    : TagModifierPlugin(info, pluginIndex, {{"add", Tag}}) {}
 
    using TagModifierPlugin::doRegisterInfoUpdate;
  };
 
  class FanOutPlugin : public AccessorPlugin<FanOutPlugin> {
   public:
    FanOutPlugin(
        const LNMBackendRegisterInfo& info, size_t pluginIndex, const std::map<std::string, std::string>& parameters);
 
    template<typename UserType, typename TargetType>
    boost::shared_ptr<NDRegisterAccessor<UserType>> decorateAccessor(
        boost::shared_ptr<LogicalNameMappingBackend>& backend,
        boost::shared_ptr<NDRegisterAccessor<TargetType>>& target, const UndecoratedParams& accessorParams);
 
    void doRegisterInfoUpdate() override;
 
   private:
    std::list<std::string> _targets;
  };
 
  /********************************************************************************************************************/
 
  /********************************************************************************************************************/
  /* Implementations follow here                                                                                      */
  /********************************************************************************************************************/
 
  template<typename Derived>
  AccessorPlugin<Derived>::AccessorPlugin(const LNMBackendRegisterInfo& info, size_t pluginIndex)
  : AccessorPluginBase(info), _pluginIndex(pluginIndex) {
    FILL_VIRTUAL_FUNCTION_TEMPLATE_VTABLE(getAccessor_impl);
  }
 
  /********************************************************************************************************************/
 
  template<typename Derived>
  template<typename UserType, typename TargetType>
  boost::shared_ptr<NDRegisterAccessor<UserType>> AccessorPlugin<Derived>::decorateAccessor(
      boost::shared_ptr<LogicalNameMappingBackend>&, boost::shared_ptr<NDRegisterAccessor<TargetType>>& target,
      const UndecoratedParams&) {
    if constexpr(std::is_same<UserType, TargetType>::value) {
      return target;
    }
 
    assert(false); // When overriding getTargetDataType(), also decorateAccessor()
                   // must be overridden!
 
    return {};
  }
 
  /********************************************************************************************************************/
 
  template<typename Derived>
  template<typename UserType>
  boost::shared_ptr<NDRegisterAccessor<UserType>> AccessorPlugin<Derived>::getAccessor_impl(
      boost::shared_ptr<LogicalNameMappingBackend>& backend, size_t numberOfWords, size_t wordOffsetInRegister,
      AccessModeFlags flags, size_t pluginIndex) {
    boost::shared_ptr<NDRegisterAccessor<UserType>> decorated;
 
    assert(_pluginIndex == pluginIndex);
 
    // obtain desired target type from plugin implementation
    auto type = getTargetDataType(typeid(UserType));
    if((_info._dataDescriptor.rawDataType() == DataType::none) && flags.has(AccessMode::raw)) {
      throw ChimeraTK::logic_error(
          "Access mode 'raw' is not supported for register '" + std::string(_info.getRegisterName()) + "'");
    }
 
    callForType(type, [&](auto T) {
      boost::shared_ptr<ChimeraTK::NDRegisterAccessor<decltype(T)>> target;
 
      target = backend->getRegisterAccessor_impl<decltype(T)>(
          _info.getRegisterName(), numberOfWords, wordOffsetInRegister, flags, pluginIndex + 1);
 
      // double buffering plugin needs numberOfWords, wordOffsetInRegister of already existing accessor
      UndecoratedParams accessorParams(_info.registerName, numberOfWords, wordOffsetInRegister, flags);
      decorated = static_cast<Derived*>(this)->template decorateAccessor<UserType>(backend, target, accessorParams);
    });
 
    decorated->setExceptionBackend(backend);
    return decorated;
  }
 
} // namespace ChimeraTK::LNMBackend