NumericAddressedRegisterCatalogue.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 "BackendRegisterCatalogue.h"
#include "BackendRegisterInfoBase.h"
 
#include <cstdint>
#include <limits>
#include <string>
 
namespace ChimeraTK {
 
  /********************************************************************************************************************/
 
  class NumericAddressedRegisterInfo : public BackendRegisterInfoBase {
   public:
    enum class Access { READ_ONLY = 0, WRITE_ONLY = 1, READ_WRITE = 2, INTERRUPT = 3 };
 
    enum class Type { VOID = 0, FIXED_POINT = 1, IEEE754 = 2, ASCII = 3 };
 
    /* Unfortunately, register is a reserved keyword so we use regPath.
     * And since this is used as a std::optional, which has a value() method would make "value" a weird name
     */
    struct SelectedBy {
      RegisterPath regPath; 
      int64_t val;          
    };
 
    struct ChannelInfo {
      uint32_t bitOffset;      
      Type dataType;           
      uint32_t width;          
      int32_t nFractionalBits; 
      bool signedFlag;         
      DataType rawType;
      std::optional<SelectedBy> selectedBy{std::nullopt};
      bool operator==(const ChannelInfo& rhs) const;
      bool operator!=(const ChannelInfo& rhs) const;
      [[nodiscard]] DataType getRawType() const;
    };
 
    struct DoubleBufferInfo {
      uint64_t address;                        
      RegisterPath enableRegisterPath;         
      RegisterPath inactiveBufferRegisterPath; 
      uint32_t index;                          
    };
 
    explicit NumericAddressedRegisterInfo(RegisterPath const& pathName_ = {}, uint32_t nElements_ = 0,
        uint64_t address_ = 0, uint32_t nBytes_ = 0, uint64_t bar_ = 0, uint32_t width_ = 32,
        int32_t nFractionalBits_ = 0, bool signedFlag_ = true, Access dataAccess_ = Access::READ_WRITE,
        Type dataType_ = Type::FIXED_POINT, std::vector<size_t> interruptId_ = {},
        std::optional<DoubleBufferInfo> doubleBuffer_ = std::nullopt, bool isBitRange_ = false);
 
    NumericAddressedRegisterInfo(RegisterPath const& pathName_, uint64_t bar_, uint64_t address_, uint32_t nElements_,
        uint32_t elementPitchBits_, std::vector<ChannelInfo> channelInfo_, Access dataAccess_,
        std::vector<size_t> interruptId_, std::optional<DoubleBufferInfo> doubleBuffer_ = std::nullopt);
 
    NumericAddressedRegisterInfo(const NumericAddressedRegisterInfo&) = default;
 
    NumericAddressedRegisterInfo& operator=(const NumericAddressedRegisterInfo& other) = default;
 
    bool operator==(const ChimeraTK::NumericAddressedRegisterInfo& rhs) const;
 
    bool operator!=(const ChimeraTK::NumericAddressedRegisterInfo& rhs) const;
 
    [[nodiscard]] RegisterPath getRegisterName() const override { return pathName; }
 
    [[nodiscard]] unsigned int getNumberOfElements() const override { return nElements; }
 
    [[nodiscard]] unsigned int getNumberOfChannels() const override { return channels.size(); }
 
    [[nodiscard]] const DataDescriptor& getDataDescriptor() const override { return dataDescriptor; }
 
    [[nodiscard]] bool isReadable() const override {
      return (registerAccess == Access::READ_ONLY) || (registerAccess == Access::READ_WRITE) ||
          (registerAccess == Access::INTERRUPT);
    }
 
    [[nodiscard]] bool isWriteable() const override {
      return (registerAccess == Access::WRITE_ONLY) || (registerAccess == Access::READ_WRITE);
    }
 
    [[nodiscard]] AccessModeFlags getSupportedAccessModes() const override {
      AccessModeFlags flags;
 
      if(registerAccess == Access::INTERRUPT) {
        flags.add(AccessMode::wait_for_new_data);
      }
 
      if(channels.size() == 1 && channels.front().dataType != Type::VOID && channels.front().dataType != Type::ASCII) {
        flags.add(AccessMode::raw);
      }
 
      return flags;
    }
 
    RegisterPath pathName;
 
    uint32_t nElements;        
    uint32_t elementPitchBits; 
    uint64_t bar;     
    uint64_t address; 
    Access registerAccess; 
    std::vector<size_t> interruptId;
    std::optional<DoubleBufferInfo> doubleBuffer;
    bool isBitRange; // A (sub) bit range of a bit field.
 
    std::vector<ChannelInfo> channels;
 
    DataDescriptor dataDescriptor;
 
    bool hidden{false};
 
    [[nodiscard]] std::unique_ptr<BackendRegisterInfoBase> clone() const override {
      return std::unique_ptr<BackendRegisterInfoBase>(new NumericAddressedRegisterInfo(*this));
    }
 
    [[nodiscard]] std::vector<size_t> getQualifiedAsyncId() const override;
 
    void computeDataDescriptor();
 
    [[nodiscard]] bool isHidden() const override { return hidden; }
 
    std::string description;
 
    std::string engineeringUnit;
 
    [[nodiscard]] std::string getUnit() const override { return engineeringUnit; }
 
    [[nodiscard]] std::string getDescription() const override { return description; }
  };
 
  /********************************************************************************************************************/
 
  class NumericAddressedRegisterCatalogue : public BackendRegisterCatalogue<NumericAddressedRegisterInfo> {
   public:
    [[nodiscard]] NumericAddressedRegisterInfo getBackendRegister(const RegisterPath& registerPathName) const override;
 
    [[nodiscard]] bool hasRegister(const RegisterPath& registerPathName) const override;
 
    [[nodiscard]] const std::set<std::vector<size_t>>& getListOfInterrupts() const;
 
    void addRegister(const NumericAddressedRegisterInfo& registerInfo);
 
    [[nodiscard]] std::unique_ptr<BackendRegisterCatalogueBase> clone() const override;
 
    [[nodiscard]] std::shared_ptr<async::DataConsistencyRealm> getDataConsistencyRealm(
        const std::vector<size_t>& qualifiedAsyncDomainId) const override;
 
    [[nodiscard]] RegisterPath getDataConsistencyKeyRegisterPath(
        const std::vector<size_t>& qualifiedAsyncDomainId) const override;
 
    void addDataConsistencyRealm(const RegisterPath& registerPath, const std::string& realmName);
 
   protected:
    void fillFromThis(NumericAddressedRegisterCatalogue* target) const;
 
    std::set<std::vector<size_t>> _listOfInterrupts;
 
    std::map<RegisterPath, std::vector<size_t>> _canonicalInterrupts;
 
    std::map<RegisterPath, std::string> _dataConsistencyRealms;
  };
 
  /********************************************************************************************************************/
 
} // namespace ChimeraTK