Device.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 "AccessMode.h"
#include "DeviceBackend.h"
#include "ForwardDeclarations.h"
#include "OneDRegisterAccessor.h"
#include "ScalarRegisterAccessor.h"
#include "TwoDRegisterAccessor.h"
#include "VoidRegisterAccessor.h"
 
#include <boost/algorithm/string.hpp>
#include <boost/shared_ptr.hpp>
 
// These headers are added for convenience of application programmers:
#include "BackendFactory.h" // IWYU pragma: keep
#include "Exception.h"      // IWYU pragma: keep
#include "Utilities.h"      // IWYU pragma: keep (for setDMapFilePath())
 
namespace ChimeraTK {
 
  class Device {
   public:
    Device() = default;
 
    explicit Device(const std::string& aliasName);
 
    void open(std::string const& aliasName);
 
    void open();
 
    void close();
 
    template<typename UserType>
    [[nodiscard]] ScalarRegisterAccessor<UserType> getScalarRegisterAccessor(const RegisterPath& registerPathName,
        size_t wordOffsetInRegister = 0, const AccessModeFlags& flags = AccessModeFlags({})) const;
 
    [[nodiscard]] VoidRegisterAccessor getVoidRegisterAccessor(
        const RegisterPath& registerPathName, const AccessModeFlags& flags = AccessModeFlags({})) const;
 
    template<typename UserType>
    [[nodiscard]] OneDRegisterAccessor<UserType> getOneDRegisterAccessor(const RegisterPath& registerPathName,
        size_t numberOfWords = 0, size_t wordOffsetInRegister = 0,
        const AccessModeFlags& flags = AccessModeFlags({})) const;
 
    template<typename UserType>
    TwoDRegisterAccessor<UserType> getTwoDRegisterAccessor(const RegisterPath& registerPathName,
        size_t numberOfElements = 0, size_t elementsOffset = 0,
        const AccessModeFlags& flags = AccessModeFlags({})) const;
 
    [[nodiscard]] RegisterCatalogue getRegisterCatalogue() const;
 
    [[nodiscard]] MetadataCatalogue getMetadataCatalogue() const;
 
    [[nodiscard]] std::string readDeviceInfo() const;
 
    [[nodiscard]] bool isOpened() const;
 
    [[nodiscard]] bool isFunctional() const;
 
    void activateAsyncRead() noexcept;
 
    void setException(const std::string& message);
 
    [[nodiscard]] boost::shared_ptr<DeviceBackend> getBackend();
 
    template<typename UserType>
    [[nodiscard]] UserType read(
        const RegisterPath& registerPathName, const AccessModeFlags& flags = AccessModeFlags({})) const;
 
    template<typename UserType>
    [[nodiscard]] std::vector<UserType> read(const RegisterPath& registerPathName, size_t numberOfWords,
        size_t wordOffsetInRegister = 0, const AccessModeFlags& flags = AccessModeFlags({})) const;
 
    template<typename UserType>
    void write(
        const RegisterPath& registerPathName, UserType value, const AccessModeFlags& flags = AccessModeFlags({}));
 
    template<typename UserType>
    void write(const RegisterPath& registerPathName, const std::vector<UserType>& vector,
        size_t wordOffsetInRegister = 0, const AccessModeFlags& flags = AccessModeFlags({}));
 
   protected:
    boost::shared_ptr<DeviceBackend> _deviceBackendPointer;
 
    void checkPointersAreNotNull() const;
  };
 
  /********************************************************************************************************************/
 
  template<typename UserType>
  ScalarRegisterAccessor<UserType> Device::getScalarRegisterAccessor(
      const RegisterPath& registerPathName, size_t wordOffsetInRegister, const AccessModeFlags& flags) const {
    checkPointersAreNotNull();
    return ScalarRegisterAccessor<UserType>(
        _deviceBackendPointer->getRegisterAccessor<UserType>(registerPathName, 1, wordOffsetInRegister, flags));
  }
 
  /********************************************************************************************************************/
 
  template<typename UserType>
  OneDRegisterAccessor<UserType> Device::getOneDRegisterAccessor(const RegisterPath& registerPathName,
      size_t numberOfWords, size_t wordOffsetInRegister, const AccessModeFlags& flags) const {
    checkPointersAreNotNull();
    return OneDRegisterAccessor<UserType>(_deviceBackendPointer->getRegisterAccessor<UserType>(
        registerPathName, numberOfWords, wordOffsetInRegister, flags));
  }
 
  /********************************************************************************************************************/
 
  template<typename UserType>
  TwoDRegisterAccessor<UserType> Device::getTwoDRegisterAccessor(const RegisterPath& registerPathName,
      size_t numberOfElements, size_t elementsOffset, const AccessModeFlags& flags) const {
    checkPointersAreNotNull();
    return TwoDRegisterAccessor<UserType>(_deviceBackendPointer->getRegisterAccessor<UserType>(
        registerPathName, numberOfElements, elementsOffset, flags));
  }
 
  /********************************************************************************************************************/
 
  template<typename UserType>
  UserType Device::read(const RegisterPath& registerPathName, const AccessModeFlags& flags) const {
    auto acc = getScalarRegisterAccessor<UserType>(registerPathName, 0, flags);
    acc.read();
    return acc;
  }
 
  /********************************************************************************************************************/
 
  template<typename UserType>
  std::vector<UserType> Device::read(const RegisterPath& registerPathName, size_t numberOfWords,
      size_t wordOffsetInRegister, const AccessModeFlags& flags) const {
    auto acc = getOneDRegisterAccessor<UserType>(registerPathName, numberOfWords, wordOffsetInRegister, flags);
    acc.read();
    std::vector<UserType> vector(acc.getNElements());
    acc.swap(vector);
    return vector;
  }
 
  /********************************************************************************************************************/
 
  template<typename UserType>
  void Device::write(const RegisterPath& registerPathName, UserType value, const AccessModeFlags& flags) {
    auto acc = getScalarRegisterAccessor<UserType>(registerPathName, 0, flags);
    acc = value;
    acc.write();
  }
 
  /********************************************************************************************************************/
 
  template<typename UserType>
  void Device::write(const RegisterPath& registerPathName, const std::vector<UserType>& vector,
      size_t wordOffsetInRegister, const AccessModeFlags& flags) {
    auto acc = getOneDRegisterAccessor<UserType>(registerPathName, vector.size(), wordOffsetInRegister, flags);
    // the vector stays constant, but we have to work around so we can swap it and
    // later swap it back...
    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
    auto& mutable_vector = const_cast<std::vector<UserType>&>(vector);
    acc.swap(mutable_vector);
    acc.write();
    acc.swap(mutable_vector);
  }
 
  /********************************************************************************************************************/
 
} // namespace ChimeraTK