soem_fieldbus_driver.h

Go to the documentation of this file.

#pragma once
 
#include <atomic>
#include <cstddef>
#include <cstdint>
#include <memory>
#include <set>
#include <span>
#include <string>
#include <vector>
 
#include "comm/control_plane_locks.h"
#include "comm/fieldbus_driver.h"
 
struct ecx_context;
 
namespace mm::comm::soem {
 
struct SoemFieldbusDriverConfig {
  std::string ifname;
  bool mailboxStatusFmmu = false;
};
 
class SoemFieldbusDriver : public FieldbusDriver {
 public:
  explicit SoemFieldbusDriver(SoemFieldbusDriverConfig config);
 
  ~SoemFieldbusDriver() override;
 
  SoemFieldbusDriver(const SoemFieldbusDriver&) = delete;
  SoemFieldbusDriver& operator=(const SoemFieldbusDriver&) = delete;
 
  std::expected<void, std::string> init() override;
 
  std::expected<int, std::string> scan() override;
 
  SlaveInfo slaveInfo(uint16_t position) const override;
 
  uint16_t slaveState(uint16_t position) const override;
 
  uint16_t mailboxProtocols(uint16_t position) const override;
 
  std::expected<void, std::string> configureProcessData() override;
 
  PdoLayout processDataLayout() override;
 
  std::vector<SlaveConfig> busConfig() const override;
 
  int exchangeProcessData(std::span<const uint8_t> outputs, std::span<uint8_t> inputs) override;
 
  void stop() override;
 
  std::optional<int> readDevicesOnWire() override;
 
  std::expected<std::vector<FieldbusDriver::SlaveStateRaw>, std::string> readStates(
      const std::vector<uint16_t>& positions) override;
 
  std::expected<std::vector<SlaveDiagnostics>, std::string> readDiagnostics(
      const std::vector<uint16_t>& positions) override;
 
  std::expected<std::vector<DcSyncDiagnostics>, std::string> readDcSync(
      const std::vector<uint16_t>& positions) override;
 
  std::string adapter() const override { return ifname_; }
 
  std::expected<std::vector<uint8_t>, std::string> readSdo(uint16_t slavePosition, uint16_t index,
                                                           uint8_t subindex) override;
 
  std::expected<std::vector<uint8_t>, std::string> readSdoComplete(uint16_t slavePosition,
                                                                   uint16_t index) override;
 
  std::expected<void, std::string> writeSdo(uint16_t slavePosition, uint16_t index,
                                            uint8_t subindex,
                                            std::span<const uint8_t> data) override;
 
  std::expected<OdRead, std::string> readObjectDictionary(uint16_t slavePosition) override;
 
  std::expected<std::vector<uint8_t>, std::string> readSii(uint16_t slavePosition) override;
 
  std::expected<void, std::string> writeSii(uint16_t slavePosition,
                                            std::span<const uint8_t> data) override;
 
  std::expected<std::vector<uint8_t>, FoeError> readFile(
      uint16_t slavePosition, const std::string& filename,
      std::chrono::milliseconds timeout) override;
 
  std::expected<void, FoeError> writeFile(uint16_t slavePosition, const std::string& filename,
                                          std::span<const uint8_t> data) override;
 
  std::expected<void, std::string> readRegister(uint16_t slavePosition, uint16_t address,
                                                std::span<uint8_t> data) override;
 
  std::expected<void, std::string> writeRegister(uint16_t slavePosition, uint16_t address,
                                                 std::span<const uint8_t> data) override;
 
  std::expected<ProcessDataWatchdogConfig, std::string> processDataWatchdog(
      uint16_t slavePosition) override;
 
  std::expected<ProcessDataWatchdogConfig, std::string> setProcessDataWatchdog(
      uint16_t slavePosition, std::chrono::nanoseconds timeout) override;
 
  int slaveCount() const;
 
  void transitionToState(
      const std::vector<uint16_t>& positions, std::optional<EtherCatState> requiredState,
      EtherCatState targetState, std::chrono::steady_clock::duration timeout,
      std::chrono::steady_clock::duration resendInterval = std::chrono::seconds(2),
      std::function<void()> tick = nullptr, std::function<bool()> shouldAbort = nullptr) override;
 
 private:
  std::expected<void, std::string> deactivateMailboxStatusFmmus();
 
  std::expected<void, std::string> blockLrwOnPruIcssSlaves();
 
  void closeContext();
 
  void publishSlaveStates();
 
  std::string ifname_;
  // One lock for the bus and one per position. Sized to slavelist in the constructor, so every
  // position the driver accepts has a lock.
  mutable ControlPlaneLocks controlPlane_;
  // Keep SOEM 2.0's mailbox-status FMMU active (see the constructor). Default false: the FMMU is
  // deactivated after every map by deactivateMailboxStatusFmmus().
  bool mailboxStatusFmmu_ = false;
  // ecx_contextt is several hundred KB (EC_MAXSLAVE slave entries) — heap-
  // allocated and null until init() succeeds.
  std::unique_ptr<ecx_context> ctx_;
  // EtherCAT IOmap: ecx_config_map_group lays the whole bus's process data out here as
  // [all outputs | all inputs]. Sized to kMaxProcessImageBytes so it matches the cap
  // configureProcessData() enforces and the ProcessBuffer scratch layered on top — the
  // three must agree, or a bus the rest of the stack accepts would overflow or be rejected
  // here. At ~100 bytes per axis across both directions this holds ~320 axes — far beyond the
  // ~50 the stack targets.
  uint8_t map_[kMaxProcessImageBytes]{};
  // Lock-free mirror of every slave's cached AL status, indexed by position exactly as SOEM's
  // slavelist is (index 0 being the master). This exists so slaveState() can honour the
  // "must not block" contract on FieldbusDriver::slaveState: the value it serves lives in SOEM's
  // slavelist, which is only safe to touch under the drive's lock, and an FoE transfer holds that
  // lock for the whole transfer. Rather than make every reader wait on a flash write to learn an AL
  // state, the writers publish here at the end of each locked scope and readers take it without a
  // lock.
  //
  // Allocated once in the constructor at SOEM's compile-time maximum and never reallocated, so a
  // reader may index it for the driver's whole lifetime with nothing to synchronise against — the
  // reason it is not a vector<atomic>, whose reallocation paths are ill-formed on libc++ and MSVC.
  // Sized from the .cc so this header keeps SOEM out of its includes.
  std::unique_ptr<std::atomic<uint16_t>[]> slaveStates_;
  // Immutable after construction, so it needs no synchronisation of its own.
  std::size_t slaveStatesSize_ = 0;
  // 1-based positions whose context currently holds BOOT-sized mailbox sync
  // managers (set when we drive a slave into BOOT). ecx_config_init programs the
  // correct PRE-OP mailbox SMs for every slave during scan(), so a fresh-scan
  // INIT→PRE-OP needs no reprogramming; only a slave returning from BOOT (e.g.
  // after a firmware download) carries stale BOOT SMs that must be reset.
  // Guarded by the bus lock held exclusive. Cleared by scan() (which re-runs ecx_config_init).
  std::set<uint16_t> bootMailboxSlaves_;
  // The low byte of ESC register 0x0000 of each slave, 1-based like the slave list, read by scan()
  // and empty where the read failed. Guarded by the bus lock like the slave list.
  std::vector<std::optional<uint8_t>> escTypes_;
};
 
}  // namespace mm::comm::soem