device_manager.h

Go to the documentation of this file.

#pragma once
 
#include <atomic>
#include <chrono>
#include <concepts>
#include <cstdint>
#include <expected>
#include <format>
#include <iosfwd>
#include <memory>
#include <mutex>
#include <nlohmann/json_fwd.hpp>
#include <optional>
#include <shared_mutex>
#include <span>
#include <string>
#include <type_traits>
#include <utility>
#include <vector>
 
#include "comm/fieldbus_driver.h"
#include "node/device.h"
#include "node/parameter_cache.h"
#include "node/process_data_ring.h"
#include "node/process_image.h"
 
namespace mm::node {
 
struct ProcessData;
 
struct DeviceStateInfo {
  uint16_t slavePosition;  
  uint16_t alStatus;       
  uint16_t alState;  
  bool error;        
  uint16_t alStatusCode;  
};
 
void to_json(nlohmann::json& j, const DeviceStateInfo& info);
 
struct ProcessImageObjectInfo {
  uint16_t slavePosition = 0;  
  uint16_t index = 0;          
  uint8_t subindex = 0;        
  std::string name;            
  uint32_t bitOffset = 0;      
  uint16_t bitLength = 0;      
};
 
struct ProcessImageInfo {
  bool configured = false;   
  uint32_t outputBytes = 0;  
  uint32_t inputBytes = 0;   
  int expectedWkc = 0;       
  int lastWkc = 0;           
  bool healthy = false;      
  uint64_t shortWkcCycles = 0;
  uint64_t firstShortWkcUs = 0;  
  uint64_t lastShortWkcUs = 0;   
  std::size_t generations = 0;   
  std::vector<ProcessImageObjectInfo> outputs;  
  std::vector<ProcessImageObjectInfo> inputs;   
};
 
void to_json(nlohmann::json& j, const ProcessImageObjectInfo& obj);
 
void to_json(nlohmann::json& j, const ProcessImageInfo& info);
 
struct OutputStageRequest {
  uint16_t slavePosition = 0;  
  uint16_t index = 0;          
  uint8_t subindex = 0;        
  DeviceParameterValue value;  
};
 
struct OutputStageResult {
  uint16_t slavePosition = 0;  
  uint16_t index = 0;          
  uint8_t subindex = 0;        
  bool staged = false;         
  std::string error;           
};
 
void to_json(nlohmann::json& j, const OutputStageResult& result);
 
struct SlaveConfigInfo {
  mm::comm::SlaveConfig config;  
  std::string deviceName;        
  std::string productName;       
  // Immutable identity, denormalised from the Device for this slave position (like deviceName) so
  // the Configuration page can show it without a second endpoint. Zero when the slave is unknown.
  uint32_t vendorId = 0;        
  uint32_t productCode = 0;     
  uint32_t revisionNumber = 0;  
  uint32_t serialNumber = 0;    
};
 
void to_json(nlohmann::json& j, const SlaveConfigInfo& info);
 
struct DeviceDiagnosticsInfo {
  mm::comm::SlaveDiagnostics diagnostics;  
  std::string deviceName;  
};
 
void to_json(nlohmann::json& j, const DeviceDiagnosticsInfo& info);
 
struct DcSyncInfo {
  mm::comm::DcSyncDiagnostics dcSync;  
  std::string deviceName;              
};
 
void to_json(nlohmann::json& j, const DcSyncInfo& info);
 
struct DeviceManagerConfig {
  bool readObjectDictionaryOnPreop = true;
  bool useCompleteAccess = true;
  std::string recorderDumpDir;
  uint32_t recorderCapacity = 300000;
};
 
struct DeviceSet {
  std::shared_ptr<mm::comm::FieldbusDriver> driver;
  std::vector<Device> devices;
  uint64_t topologyGeneration = 0;
 
  Device* find(uint16_t slavePosition);
  const Device* find(uint16_t slavePosition) const;
};
 
class DeviceHandle {
 public:
  DeviceHandle() = default;
  DeviceHandle(std::shared_ptr<DeviceSet> set, Device* device)
      : set_(std::move(set)), device_(device) {}
 
  explicit operator bool() const { return device_ != nullptr; }
  Device& operator*() const { return *device_; }
  Device* operator->() const { return device_; }
  Device* get() const { return device_; }
 
 private:
  std::shared_ptr<DeviceSet> set_;
  Device* device_ = nullptr;
};
 
inline std::unexpected<std::string> deviceNotFound(uint16_t slavePosition) {
  return std::unexpected(std::format("device {} not found", slavePosition));
}
 
class DeviceManager {
 public:
  DeviceManager();
 
  ~DeviceManager();
 
  std::expected<void, std::string> init(std::unique_ptr<mm::comm::FieldbusDriver> driver,
                                        const DeviceManagerConfig& config = {});
 
  void configureParameterCache(const ParameterCacheConfig& config);
 
  const ParameterCache& parameterCache() const;
 
  std::expected<int, std::string> scan();
 
  void reset();
 
  bool initialised() const;
 
  bool hasDevice(uint16_t slavePosition) const;
 
  DeviceHandle deviceAt(uint16_t slavePosition) const;
 
  std::shared_ptr<DeviceSet> deviceSet() const;
 
  class CycleGuard {
   public:
    explicit CycleGuard(DeviceManager& deviceManager);
    ~CycleGuard();
 
    CycleGuard(const CycleGuard&) = delete;
    CycleGuard& operator=(const CycleGuard&) = delete;
 
    explicit operator bool() const { return entered_; }
 
   private:
    ProcessData* processData_;
    bool entered_;
  };
 
  Device* findDevice(uint16_t slavePosition);
 
  const Device* findDevice(uint16_t slavePosition) const;
 
  uint64_t topologyGeneration() const;
 
  std::expected<void, std::string> configureProcessData();
 
  void exchangeProcessData();
 
  bool processDataConfigured() const;
 
  uint64_t processImageGeneration() const;
 
  int lastWorkingCounter() const;
 
  int expectedWorkingCounter() const;
 
  bool processDataHealthy() const;
 
  ProcessImageInfo processImageInfo() const;
 
  uint64_t shortWkcCycles() const;
 
  std::expected<std::string, std::string> dumpProcessData();
 
  std::expected<std::string, std::string> dumpProcessDataBuffer();
 
  std::vector<SlaveConfigInfo> busConfig() const;
 
  std::expected<std::vector<DeviceStateInfo>, std::string> transitionToState(
      const std::vector<uint16_t>& positions, mm::comm::EtherCatState targetState,
      std::chrono::steady_clock::duration timeout);
 
  std::expected<std::vector<DeviceStateInfo>, std::string> deviceStates(
      const std::vector<uint16_t>& positions);
 
  std::expected<std::vector<DeviceDiagnosticsInfo>, std::string> deviceDiagnostics(
      const std::vector<uint16_t>& positions);
 
  std::expected<std::vector<DcSyncInfo>, std::string> dcSync(
      const std::vector<uint16_t>& positions);
 
  std::expected<mm::comm::ProcessDataWatchdogConfig, std::string> processDataWatchdog(
      uint16_t slavePosition);
 
  std::expected<mm::comm::ProcessDataWatchdogConfig, std::string> setProcessDataWatchdog(
      uint16_t slavePosition, std::chrono::nanoseconds timeout);
 
  std::expected<void, std::string> initializeDeviceParameters(uint16_t slavePosition,
                                                              bool readValues);
 
  std::expected<void, std::string> readAllDeviceParameters(uint16_t slavePosition);
 
  std::expected<DeviceParameter, std::string> deviceParameterView(uint16_t slavePosition,
                                                                  uint16_t index, uint8_t subindex,
                                                                  bool refreshFromBus);
 
  std::expected<DeviceParameter, std::string> writeDeviceParameter(
      uint16_t slavePosition, uint16_t index, uint8_t subindex,
      const DeviceParameterValue& newValue);
 
  std::expected<void, std::string> writeDevicePdoMapping(uint16_t slavePosition,
                                                         const PdoMapping& mapping);
 
  std::vector<OutputStageResult> stageProcessDataOutputs(
      std::span<const OutputStageRequest> requests);
 
  // --- Off-thread sampling read surface (for monitoring) ---
  //
  // These let the monitoring sampler read live values from its own thread without ever blocking
  // on the bus: SDO objects from the (refresher-fed) cache via value(); PDO objects decoded by
  // the caller from recorder-ring records (recorderHead()/recorderOldestSeq()/readRecord()) using
  // the layout pdoSampleSpec() captures. Thread-safe; they hand back copies, never device pointers.
 
  struct PdoSampleSpec {
    bool isOutput;       
    uint32_t bitOffset;  
    uint16_t bitLength;  
    uint16_t dataType;   
  };
 
  std::optional<PdoSampleSpec> pdoSampleSpec(uint16_t slavePosition, uint16_t index,
                                             uint8_t subindex) const;
 
  uint64_t recorderHead() const;
 
  uint64_t recorderOldestSeq() const;
 
  bool readRecord(uint64_t seq, ProcessDataRing::Record& out) const;
 
  bool deviceExchangesProcessData(uint16_t slavePosition) const;
 
 private:
  void decodeInputsIntoCells(const ProcessImage& image);
 
  struct DumpSpan {
    uint64_t rows = 0;
    uint64_t startSeq = 0;
    uint64_t endSeq = 0;
  };
 
  std::expected<DumpSpan, std::string> serializeDump(std::ostream& out);
 
  std::expected<void, std::string> remapProcessImage();
 
  std::expected<std::vector<uint16_t>, std::string> resolveTargets(
      const std::vector<uint16_t>& positions) const;
 
  int expectedWkcDuring(std::span<const uint16_t> transitioning,
                        std::optional<mm::comm::EtherCatState> target) const;
 
  void updateExpectedWkc();
 
  void lowerExpectedWkc(std::span<const uint16_t> positions, mm::comm::EtherCatState target);
 
  [[nodiscard]] bool stopExchange();
 
  void publishDeviceSet(std::shared_ptr<DeviceSet> set);
 
  // busOperationMutex_ — "one control-plane operation drives the bus at a time". It guards no
  // member: it is a mutual-exclusion token over an *activity*, which is what distinguishes it from
  // the driver's controlPlaneMutex_ (that one serialises a single socket transaction; this one
  // serialises a whole multi-transaction operation). Held for their entire duration by
  // init/scan/reset/configureProcessData/transitionToState/writeDevicePdoMapping, the only
  // operations that publish a device set, re-map the process image, drive AL state, or rewrite a
  // device's PDO mapping. No reader ever takes it, so a multi-second AL transition excludes only
  // other control-plane callers — never the monitoring sampler, and never a procedure that is
  // already running.
  mutable std::mutex busOperationMutex_;
 
  // currentSetMutex_ — guards the shared_ptr below, and nothing it points to. Held for exactly one
  // pointer copy, which is why a reader can never be delayed by an operation: a shared_ptr copy is
  // not atomic against an assignment to the same object, and std::atomic<std::shared_ptr<T>> is not
  // lock-free (libc++ does not implement it at all). Device *lifetime* is the refcount's job, not
  // this lock's.
  mutable std::mutex currentSetMutex_;
  // The published generation of the bus, and the reference that keeps it alive. Never null: an
  // empty set stands in before the first init(), so every reader can dereference the pointer it
  // gets without a check.
  //
  // A retired set is freed as soon as that is safe, and not retained beyond it: the last
  // DeviceHandle holding it frees it, so memory does not grow with rescans. The RT side is covered
  // by the drain — every publisher calls stopExchange() first, so no cyclic task is inside a cycle
  // body holding a pointer into the set being dropped. A task must therefore resolve its devices
  // each cycle and never cache one across cycles.
  std::shared_ptr<DeviceSet> currentSet_;
 
  // What a failed drain held back. When @c stopExchange times out, the RT thread is still inside a
  // cycle and may be reading a device set, a process image or a parameter map that the operation
  // was about to release — so the operation keeps it here instead of freeing it, and the next
  // successful drain clears the list. Empty unless a drain failed, which is an emergency and is
  // logged.
  std::vector<std::shared_ptr<const void>> abandoned_;
 
  // The same set as a raw pointer, for the RT thread, which must not touch a shared_ptr. It carries
  // no reference of its own: currentSet_ owns the object it names, and publishDeviceSet writes both
  // with the cycle drained.
  std::atomic<DeviceSet*> publishedSet_{nullptr};
 
  // processDataMutex_ — the two non-atomic members of ProcessData: the recorder ring's storage and
  // the retained image generations. The ring is lock-free for one writer and many readers, but
  // ProcessDataRing::allocate and ::clear are a third kind of writer: they free the buffer, which
  // no sequence check on the reader side can survive. The generations vector has the same shape — a
  // re-map appends, scan/reset clear. Readers take this shared, those writers exclusively. A leaf:
  // nothing is ever acquired while it is held.
  mutable std::shared_mutex processDataMutex_;
 
  // Bumped on every scan()/reset(); see topologyGeneration().
  std::atomic<uint64_t> topologyGeneration_{0};
  // Bumped every time remapProcessImage() publishes a new image; see processImageGeneration().
  std::atomic<uint64_t> processImageGeneration_{0};
  std::unique_ptr<ProcessData> pd_;
  // On-disk parameter-definition cache, shared by every Device (handed to each by pointer at
  // scan()). Outlives every device set. Configured at init().
  ParameterCache parameterCache_;
  // Runtime tuning captured at init(); drives recorder-ring sizing at configureProcessData.
  DeviceManagerConfig config_;
};
 
void to_json(nlohmann::json& j, const DeviceManager& dm);
 
}  // namespace mm::node