NumericAddressedBackend.cc

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
 
#include "NumericAddressedBackend.h"
 
#include "async/DomainImpl.h"
#include "async/DomainsContainer.h"
#include "BackendFactory.h"
#include "BitRangeAccessorDecorator.h"
#include "DoubleBufferAccessor.h"
#include "Exception.h"
#include "MapFileParser.h"
#include "NumericAddress.h"
#include "NumericAddressedBackendASCIIAccessor.h"
#include "NumericAddressedBackendMuxedRegisterAccessor.h"
#include "NumericAddressedBackendRegisterAccessor.h"
#include "parserUtilities.h"
#include "SupportedUserTypes.h"
 
#include <nlohmann/json.hpp>
 
#include <filesystem>
 
using json = nlohmann::json;
 
namespace ChimeraTK {
 
  /********************************************************************************************************************/
 
  NumericAddressedBackend::NumericAddressedBackend(const std::string& mapFileName,
      std::unique_ptr<NumericAddressedRegisterCatalogue> registerMapPointer,
      const std::string& dataConsistencyKeyDescriptor)
  : _registerMapPointer(std::move(registerMapPointer)), _registerMap(*_registerMapPointer) {
    FILL_VIRTUAL_FUNCTION_TEMPLATE_VTABLE(getRegisterAccessor_impl);
    if(!mapFileName.empty()) {
      _resolvedMapFileName = resolveMapFileName(mapFileName);
      MapFileParser parser;
      std::tie(_registerMap, _metadataCatalogue) = parser.parse(_resolvedMapFileName);
    }
    if(!dataConsistencyKeyDescriptor.empty()) {
      // parse as JSON
      try {
        auto jdescr = nlohmann::json::parse(dataConsistencyKeyDescriptor);
        for(const auto& el : jdescr.items()) {
          _registerMap.addDataConsistencyRealm(el.key(), el.value());
        }
      }
      catch(json::parse_error& e) {
        throw ChimeraTK::logic_error(std::format("Parsing DataConsistencyKeys parameter '{}' results in JSON error: {}",
            dataConsistencyKeyDescriptor, e.what()));
      }
    }
  }
 
  /********************************************************************************************************************/
 
  std::string NumericAddressedBackend::resolveMapFileName(const std::string& mapFileName) {
    // an absolute path is used directly, legacy DMAP entries are already delivered as absolute paths
    if(mapFileName[0] == '/') {
      if(std::filesystem::exists(mapFileName)) {
        return std::filesystem::canonical(mapFileName).string();
      }
      throw ChimeraTK::logic_error("Cannot open map file \"" + mapFileName + "\": file not found.");
    }
 
    // relative path candidate: relative to the directory of the DMAP file (if a DMAP path is set)
    std::string dmapFilePath = BackendFactory::getInstance().getDMapFilePath();
    std::string dmapDir = parserUtilities::extractDirectory(dmapFilePath);
    std::string candidateA = parserUtilities::concatenatePaths(dmapDir, mapFileName);
    // a relative DMAP path is itself relative to the cwd; an unset DMAP path yields "./" as directory,
    // so candidateA collapses to the cwd-relative path, which is the desired fallback anyway
    if(std::filesystem::exists(candidateA)) {
      return std::filesystem::canonical(candidateA).string();
    }
 
    // fallback candidate: relative to the current working directory
    std::string candidateB = parserUtilities::convertToAbsolutePath(mapFileName);
    if(std::filesystem::exists(candidateB)) {
      return std::filesystem::canonical(candidateB).string();
    }
 
    throw ChimeraTK::logic_error("Cannot open map file \"" + mapFileName + "\": file not found.");
  }
 
  /********************************************************************************************************************/
 
  NumericAddressedRegisterInfo NumericAddressedBackend::getRegisterInfo(const RegisterPath& registerPathName) {
    return _registerMap.getBackendRegister(registerPathName);
  }
 
  /********************************************************************************************************************/
 
  /* Throw exception if called directly and not implemented by backend */
  void NumericAddressedBackend::read([[maybe_unused]] uint8_t bar, [[maybe_unused]] uint32_t address,
      [[maybe_unused]] int32_t* data, [[maybe_unused]] size_t sizeInBytes) {
    throw ChimeraTK::logic_error("NumericAddressedBackend: internal error: interface read() called w/ 32bit address");
  }
 
  /********************************************************************************************************************/
 
  void NumericAddressedBackend::write([[maybe_unused]] uint8_t bar, [[maybe_unused]] uint32_t address,
      [[maybe_unused]] int32_t const* data, [[maybe_unused]] size_t sizeInBytes) {
    throw ChimeraTK::logic_error("NumericAddressedBackend: internal error: interface write() called w/ 32bit address");
  }
 
  /********************************************************************************************************************/
 
  /* Call 32-bit address implementation by default, for backends that don't implement 64-bit */
  void NumericAddressedBackend::read(uint64_t bar, uint64_t address, int32_t* data, size_t sizeInBytes) {
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
    read(static_cast<uint8_t>(bar), static_cast<uint32_t>(address), data, sizeInBytes);
#pragma GCC diagnostic pop
  }
 
  /********************************************************************************************************************/
 
  void NumericAddressedBackend::write(uint64_t bar, uint64_t address, int32_t const* data, size_t sizeInBytes) {
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
    write(static_cast<uint8_t>(bar), static_cast<uint32_t>(address), data, sizeInBytes);
#pragma GCC diagnostic pop
  }
 
  /********************************************************************************************************************/
 
  // Default range of valid BARs
  bool NumericAddressedBackend::barIndexValid(uint64_t bar) {
    return bar <= 5 || bar == 13;
  }
 
  /********************************************************************************************************************/
 
  template<typename UserType>
  boost::shared_ptr<NDRegisterAccessor<UserType>> NumericAddressedBackend::getRegisterAccessor_impl(
      const RegisterPath& registerPathName, size_t numberOfWords, size_t wordOffsetInRegister, AccessModeFlags flags) {
    if(flags.has(AccessMode::wait_for_new_data)) {
      // get the interrupt information from the map file
      auto registerInfo = _registerMap.getBackendRegister(registerPathName);
      if(!registerInfo.getSupportedAccessModes().has(AccessMode::wait_for_new_data)) {
        throw ChimeraTK::logic_error(
            "Register " + registerPathName + " does not support AccessMode::wait_for_new_data.");
      }
 
      return _asyncDomainsContainer.subscribe<NumericAddressedBackend, std::nullptr_t, UserType>(
          boost::static_pointer_cast<NumericAddressedBackend>(shared_from_this()),
          registerInfo.getQualifiedAsyncId().front(), _asyncIsActive, registerPathName, numberOfWords,
          wordOffsetInRegister, flags);
    }
    return getSyncRegisterAccessor<UserType>(registerPathName, numberOfWords, wordOffsetInRegister, flags);
  }
 
  /********************************************************************************************************************/
 
  template<typename UserType>
  boost::shared_ptr<NDRegisterAccessor<UserType>> NumericAddressedBackend::getSyncRegisterAccessor(
      const RegisterPath& registerPathName, size_t numberOfWords, size_t wordOffsetInRegister, AccessModeFlags flags) {
    boost::shared_ptr<NDRegisterAccessor<UserType>> accessor;
    // obtain register info
    auto registerInfo = getRegisterInfo(registerPathName);
    if(registerInfo.doubleBuffer == std::nullopt) {
      // 1D or scalar register
      if(registerInfo.getNumberOfDimensions() <= 1) {
        if(registerInfo.isBitRange) {
          if(numberOfWords == 0) {
            numberOfWords = registerInfo.nElements == 0 ? 1 : registerInfo.nElements;
          }
          size_t nParentElements = registerInfo.nElements == 0 ? 1 : registerInfo.nElements;
          if(numberOfWords + wordOffsetInRegister > nParentElements) {
            throw ChimeraTK::logic_error("Error in '" + registerPathName + "': Requested number of words+offset " +
                std::to_string(numberOfWords + wordOffsetInRegister) + " exceeds register size of " +
                std::to_string(nParentElements) + ".");
          }
          // Target must point to the full parent register (all elements). The element data width of the slice's
          // sample word is derived from the channel raw type via DataType::getNumberOfBytes(), so the 'u<width>'
          // marker in the target path matches the sample word width (which may differ from the element pitch for
          // strided slices) instead of being hardcoded to 64 as before.
          uint64_t targetSizeBytes = nParentElements * registerInfo.elementPitchBits / 8;
          uint32_t wordWidth = registerInfo.channels.front().getRawType().getNumberOfBytes() * 8;
          RegisterPath targetRegisterPath = numeric_address::BAR() / std::to_string(registerInfo.bar) /
              (std::to_string(registerInfo.address) + "*" + std::to_string(targetSizeBytes) + "u" +
                  std::to_string(wordWidth) + "p" + std::to_string(registerInfo.elementPitchBits));
          auto target = getSyncRegisterAccessor<uint64_t>(targetRegisterPath, nParentElements, 0, {});
 
          if(flags.has(AccessMode::raw)) {
            return boost::make_shared<detail::BitRangeAccessorDecorator<UserType, true>>(
                shared_from_this(), targetRegisterPath, target, registerInfo, numberOfWords, wordOffsetInRegister);
          }
          return boost::make_shared<detail::BitRangeAccessorDecorator<UserType, false>>(
              shared_from_this(), targetRegisterPath, target, registerInfo, numberOfWords, wordOffsetInRegister);
        }
        if(registerInfo.channels.front().dataType == NumericAddressedRegisterInfo::Type::FIXED_POINT ||
            registerInfo.channels.front().dataType == NumericAddressedRegisterInfo::Type::VOID ||
            registerInfo.channels.front().dataType == NumericAddressedRegisterInfo::Type::IEEE754) {
          if(flags.has(AccessMode::raw)) {
            accessor = boost::shared_ptr<NDRegisterAccessor<UserType>>(
                new NumericAddressedBackendRegisterAccessor<UserType, true>(
                    shared_from_this(), registerPathName, numberOfWords, wordOffsetInRegister, flags));
          }
          else {
            accessor = boost::shared_ptr<NDRegisterAccessor<UserType>>(
                new NumericAddressedBackendRegisterAccessor<UserType, false>(
                    shared_from_this(), registerPathName, numberOfWords, wordOffsetInRegister, flags));
          }
        }
        else if(registerInfo.channels.front().dataType == NumericAddressedRegisterInfo::Type::ASCII) {
          if constexpr(!std::is_same<UserType, std::string>::value) {
            throw ChimeraTK::logic_error("NumericAddressedBackend: ASCII data must be read with std::string UserType.");
          }
          else {
            accessor = boost::shared_ptr<NDRegisterAccessor<UserType>>(new NumericAddressedBackendASCIIAccessor(
                shared_from_this(), registerPathName, numberOfWords, wordOffsetInRegister, flags));
          }
        }
        else {
          throw ChimeraTK::logic_error("NumericAddressedBackend: trying to get accessor for unsupported data type");
        }
      }
      // 2D multiplexed register
      else {
        flags.checkForUnknownFlags({});
        accessor =
            boost::shared_ptr<NDRegisterAccessor<UserType>>(new NumericAddressedBackendMuxedRegisterAccessor<UserType>(
                registerPathName, numberOfWords, wordOffsetInRegister, shared_from_this()));
      }
    }
    // double buffer register
    else {
      if(numberOfWords == 0) {
        numberOfWords = registerInfo.getNumberOfElements();
      }
      const auto& enableRegPath = registerInfo.doubleBuffer->enableRegisterPath;
      auto& controlState = _doubleBufferMutexMap[enableRegPath];
      if(!controlState) {
        controlState = std::make_shared<detail::CountedRecursiveMutex>();
      }
      accessor = boost::make_shared<DoubleBufferAccessor<UserType>>(*registerInfo.doubleBuffer, shared_from_this(),
          controlState, registerPathName, numberOfWords, wordOffsetInRegister, flags);
    }
    accessor->setExceptionBackend(shared_from_this());
    return accessor;
  }
 
  /********************************************************************************************************************/
 
  void NumericAddressedBackend::activateAsyncRead() noexcept {
    _asyncIsActive = true;
    // Iterating all async domains must happen under the container lock. We prepare a lambda that is executed via
    // DomainsContainer::forEach().
    auto activateDomain = [this](size_t key, boost::shared_ptr<async::Domain>& domain) {
      auto domainImpl = boost::dynamic_pointer_cast<async::DomainImpl<std::nullptr_t>>(domain);
      assert(domainImpl);
      auto subscriptionDone = this->activateSubscription(key, domainImpl);
      // Wait until the backends reports that the subscription is complete (typically set from inside another thread)
      // before polling the initial values when activating the async domain. This is necessary to make sure we don't
      // miss an update that came in after polling the initial value.
      subscriptionDone.wait();
      domainImpl->activate(nullptr);
    };
 
    _asyncDomainsContainer.forEach(activateDomain);
  }
 
  /********************************************************************************************************************/
 
  // The default implementation just returns a ready future.
  std::future<void> NumericAddressedBackend::activateSubscription([[maybe_unused]] unsigned int interruptNumber,
      [[maybe_unused]] boost::shared_ptr<async::DomainImpl<std::nullptr_t>> asyncDomain) {
    std::promise<void> subscriptionDonePromise;
    subscriptionDonePromise.set_value();
    return subscriptionDonePromise.get_future();
  }
 
  /********************************************************************************************************************/
 
  void NumericAddressedBackend::close() {
    _asyncIsActive = false;
 
    _asyncDomainsContainer.forEach([](size_t, boost::shared_ptr<async::Domain>& domain) { domain->deactivate(); });
 
    closeImpl();
  }
 
  /********************************************************************************************************************/
 
  RegisterCatalogue NumericAddressedBackend::getRegisterCatalogue() const {
    return RegisterCatalogue(_registerMap.clone());
  }
 
  /********************************************************************************************************************/
 
  MetadataCatalogue NumericAddressedBackend::getMetadataCatalogue() const {
    return _metadataCatalogue;
  }
 
  /********************************************************************************************************************/
 
  void NumericAddressedBackend::setExceptionImpl() noexcept {
    _asyncIsActive = false;
  }
 
  /********************************************************************************************************************/
 
} // namespace ChimeraTK