gsdml.cpp

Go to the documentation of this file.

 
 
#include "profinet/gsdml.h"
 
#include <libxml/parser.h>
#include <libxml/tree.h>
#include <libxml/xpath.h>
#include <libxml/xpathInternals.h>
 
#include <algorithm>
#include <map>
#include <sstream>
#include <stdexcept>
 
namespace profinet::gsdml
{
 
namespace
{
 
// =============================================================================
// libxml2 RAII wrappers
// =============================================================================
 
struct XmlDocGuard
{
  xmlDocPtr doc = nullptr;
  ~XmlDocGuard()
  {
    if (doc != nullptr)
    {
      xmlFreeDoc(doc);
    }
  }
};
 
struct XPathContextGuard
{
  xmlXPathContextPtr ctx = nullptr;
  ~XPathContextGuard()
  {
    if (ctx != nullptr)
    {
      xmlXPathFreeContext(ctx);
    }
  }
};
 
struct XPathObjectGuard
{
  xmlXPathObjectPtr obj = nullptr;
  ~XPathObjectGuard()
  {
    if (obj != nullptr)
    {
      xmlXPathFreeObject(obj);
    }
  }
};
 
// =============================================================================
// Namespace-agnostic query helpers (GSDML files declare a default
// namespace that varies by vendor/profile version, so we match on
// local-name() throughout, exactly like gsdml.py's _find/_findall do with
// ElementTree's `{*}Tag` wildcard).
// =============================================================================
 
std::string EscapeXPathLiteral(const std::string& s)
{
  // XPath 1.0 has no literal-escaping, so build via concat() if the
  // string itself contains a quote. GSDML attribute values here (IDs,
  // TextIds) never contain quotes in practice, so this is a defensive
  // fallback rather than a load-bearing path.
  if (s.find('\'') == std::string::npos)
  {
    return "'" + s + "'";
  }
  std::ostringstream oss;
  oss << "concat(";
  bool first = true;
  std::string cur;
  for (char c : s)
  {
    if (c == '\'')
    {
      if (!first)
      {
        oss << ", ";
      }
      oss << "'" << cur << "'";
      cur.clear();
      oss << ", \"'\"";
      first = false;
    }
    else
    {
      cur.push_back(c);
    }
  }
  if (!cur.empty())
  {
    if (!first)
    {
      oss << ", ";
    }
    oss << "'" << cur << "'";
  }
  oss << ")";
  return oss.str();
}
 
std::vector<xmlNodePtr> XPathFind(xmlXPathContextPtr ctx, xmlNodePtr node, const std::string& expr)
{
  xmlXPathContextPtr currentCtx = ctx;
  xmlNodePtr savedNode = currentCtx->node;
  if (node != nullptr)
  {
    currentCtx->node = node;
  }
 
  XPathObjectGuard guard;
  guard.obj = xmlXPathEvalExpression(reinterpret_cast<const xmlChar*>(expr.c_str()), currentCtx);
  currentCtx->node = savedNode;
 
  std::vector<xmlNodePtr> result;
  if ((guard.obj == nullptr) || (guard.obj->nodesetval == nullptr))
  {
    return result;
  }
  for (int i = 0; i < guard.obj->nodesetval->nodeNr; ++i)
  {
    result.push_back(guard.obj->nodesetval->nodeTab[i]);
  }
  return result;
}
 
xmlNodePtr FindFirst(xmlXPathContextPtr ctx, xmlNodePtr node, const std::string& tag)
{
  auto results = XPathFind(ctx, node, ".//*[local-name()='" + tag + "']");
  return results.empty() ? nullptr : results.front();
}
 
std::vector<xmlNodePtr> FindAll(xmlXPathContextPtr ctx, xmlNodePtr node, const std::string& tag)
{
  return XPathFind(ctx, node, ".//*[local-name()='" + tag + "']");
}
 
std::vector<xmlNodePtr> FindChildren(xmlXPathContextPtr ctx, xmlNodePtr node, const std::string& tag)
{
  return XPathFind(ctx, node, "./*[local-name()='" + tag + "']");
}
 
std::string GetAttr(xmlNodePtr node, const std::string& name, const std::string& Default = "")
{
  if (node == nullptr)
  {
    return Default;
  }
  xmlChar* val = xmlGetProp(node, reinterpret_cast<const xmlChar*>(name.c_str()));
  if (val == nullptr)
  {
    return Default;
  }
  std::string result(reinterpret_cast<const char*>(val));
  xmlFree(val);
  return result;
}
 
std::optional<std::string> GetAttrOpt(xmlNodePtr node, const std::string& name)
{
  if (node == nullptr)
  {
    return std::nullopt;
  }
  xmlChar* val = xmlGetProp(node, reinterpret_cast<const xmlChar*>(name.c_str()));
  if (val == nullptr)
  {
    return std::nullopt;
  }
  std::string result(reinterpret_cast<const char*>(val));
  xmlFree(val);
  return result;
}
 
// =============================================================================
// Value parsing helpers
// =============================================================================
 
std::uint32_t ParseInt(const std::optional<std::string>& spec)
{
  if (!spec)
  {
    return 0;
  }
  const std::string& s = *spec;
  if (s.empty())
  {
    return 0;
  }
 
  if (s.size() > 3 && s[0] == '#' && s[1] == '1' && s[2] == '6' && s[3] == '#')
  {
    return static_cast<std::uint32_t>(std::stoul(s.substr(4), nullptr, 16));
  }
  if (s.size() > 2 && s[0] == '0' && (s[1] == 'x' || s[1] == 'X'))
  {
    return static_cast<std::uint32_t>(std::stoul(s.substr(2), nullptr, 16));
  }
  try
  {
    return static_cast<std::uint32_t>(std::stoul(s, nullptr, 10));
  }
  catch (const std::exception&)
  {
    return 0;
  }
}
 
std::vector<int> ParseSlotSpec(const std::optional<std::string>& spec)
{
  std::vector<int> result;
  if (!spec || spec->empty())
  {
    return result;
  }
 
  std::string s = *spec;
  std::ranges::replace(s, ',', ' ');
  std::istringstream iss(s);
  std::string part;
  while (iss >> part)
  {
    auto dotdot = part.find("..");
    if (dotdot != std::string::npos)
    {
      int start = std::stoi(part.substr(0, dotdot));
      int end = std::stoi(part.substr(dotdot + 2));
      for (int i = start; i <= end; ++i)
      {
        result.push_back(i);
      }
    }
    else
    {
      result.push_back(std::stoi(part));
    }
  }
  return result;
}
 
const std::map<std::string, int>& TypeSizeTable()
{
  static const std::map<std::string, int> table = {
      {"Bit", 1},
      {"BitArea", 1},
      {"Boolean", 1},
      {"Integer8", 1},
      {"Unsigned8", 1},
      {"Integer16", 2},
      {"Unsigned16", 2},
      {"Integer32", 4},
      {"Unsigned32", 4},
      {"Integer64", 8},
      {"Unsigned64", 8},
      {"Float32", 4},
      {"Float64", 8},
      {"Date", 2},
      {"Time", 4},
      {"TimeOfDay", 4},
      {"TimeDifference", 4},
      {"F_MessageTrailer4Byte", 4},
      {"F_MessageTrailer5Byte", 5},
  };
  return table;
}
 
int DataItemLength(const std::string& dataType, const std::optional<std::string>& lengthAttr)
{
  if (dataType == "OctetString" || dataType == "VisibleString")
  {
    return lengthAttr ? static_cast<int>(ParseInt(lengthAttr)) : 0;
  }
  auto it = TypeSizeTable().find(dataType);
  return it != TypeSizeTable().end() ? it->second : 1;
}
 
// =============================================================================
// ExternalTextList resolution
// =============================================================================
 
std::map<std::string, std::string> BuildTextTable(xmlXPathContextPtr ctx, xmlNodePtr root)
{
  std::map<std::string, std::string> table;
  for (auto* textNode : FindAll(ctx, root, "Text"))
  {
    auto id = GetAttrOpt(textNode, "TextId");
    auto value = GetAttrOpt(textNode, "Value");
    if (id && value)
    {
      table[*id] = *value;
    }
  }
  return table;
}
 
std::string ResolveName(xmlXPathContextPtr ctx, xmlNodePtr parent, const std::map<std::string, std::string>& textTable,
                        const std::string& fallback)
{
  xmlNodePtr nameNode = FindFirst(ctx, parent, "Name");
  if (nameNode == nullptr)
  {
    return fallback;
  }
 
  if (auto textId = GetAttrOpt(nameNode, "TextId"))
  {
    auto it = textTable.find(*textId);
    if (it != textTable.end())
    {
      return it->second;
    }
  }
  if (auto value = GetAttrOpt(nameNode, "Value"))
  {
    return *value;
  }
  return fallback;
}
 
// =============================================================================
// Submodule / module parsing
// =============================================================================
 
GSDMLSubmodule ParseSubmoduleNode(xmlXPathContextPtr ctx, xmlNodePtr submoduleNode,
                                  const std::map<std::string, std::string>& textTable)
{
  GSDMLSubmodule sm;
  sm.id = GetAttr(submoduleNode, "ID");
  sm.submoduleIdentNumber = ParseInt(GetAttrOpt(submoduleNode, "SubmoduleIdentNumber"));
  sm.name = ResolveName(ctx, submoduleNode, textTable, sm.id);
  sm.allowedSubslots = ParseSlotSpec(GetAttrOpt(submoduleNode, "AllowedInSubslots"));
  sm.fixedSubslots = ParseSlotSpec(GetAttrOpt(submoduleNode, "FixedInSubslots"));
  sm.usedSubslots = ParseSlotSpec(GetAttrOpt(submoduleNode, "UsedInSubslots"));
 
  xmlNodePtr ioData = FindFirst(ctx, submoduleNode, "IOData");
  if (ioData != nullptr)
  {
    for (auto* input : FindChildren(ctx, ioData, "Input"))
    {
      for (auto* item : FindChildren(ctx, input, "DataItem"))
      {
        GSDMLDataItem di;
        di.dataType = GetAttr(item, "DataType");
        di.textId = GetAttr(item, "TextId");
        di.length = DataItemLength(di.dataType, GetAttrOpt(item, "Length"));
        sm.inputLength += di.length;
        sm.inputItems.push_back(di);
      }
    }
    for (auto* output : FindChildren(ctx, ioData, "Output"))
    {
      for (auto* item : FindChildren(ctx, output, "DataItem"))
      {
        GSDMLDataItem di;
        di.dataType = GetAttr(item, "DataType");
        di.textId = GetAttr(item, "TextId");
        di.length = DataItemLength(di.dataType, GetAttrOpt(item, "Length"));
        sm.outputLength += di.length;
        sm.outputItems.push_back(di);
      }
    }
  }
 
  return sm;
}
 
} // namespace
 
// =============================================================================
// GSDMLDevice
// =============================================================================
 
const GSDMLModule* GSDMLDevice::FindModule(const std::string& moduleId) const
{
  auto it = modules.find(moduleId);
  return it != modules.end() ? &it->second : nullptr;
}
const GSDMLSubmodule* GSDMLDevice::FindSubmodule(const std::string& submoduleId) const
{
  const auto it = submodules.find(submoduleId);
 
  return it != submodules.end()
             ? &it->second
             : nullptr;
}
/*
std::vector<rpc::IOSlot> GSDMLDevice::BuildIoSlots(
    const std::vector<std::tuple<int, std::string, int, std::string>>& plugged) const
{
  std::vector<rpc::IOSlot> slots;
 
  // System-defined submodules (interface, port) always occupy their
  // configured subslots on the DAP's slot (slot 0 by convention).
  for (const auto& sys : systemSubmodules)
  {
    rpc::IOSlot slot;
    slot.slot = 0;
    slot.subslot = sys.subslot;
    slot.inputLength = 0;
    slot.outputLength = 0;
    slot.moduleIdent = dapModuleIdentNumber;
    slot.submoduleIdent = sys.submoduleIdentNumber;
    slots.push_back(slot);
  }
 
  auto addModuleSubmodule = [&](int slot, const std::string& moduleId, int subslot,
                                const std::string& submoduleId)
  {
    const GSDMLModule* module = FindModule(moduleId);
    if (!module)
    {
      throw std::invalid_argument("Unknown module ID: " + moduleId);
    }
 
    auto allowedIt = allowedSlots.find(moduleId);
    if (allowedIt != allowedSlots.end() && !allowedIt->second.empty())
    {
      if (std::find(allowedIt->second.begin(), allowedIt->second.end(), slot) ==
          allowedIt->second.end())
      {
        throw std::invalid_argument("Module '" + moduleId + "' is not allowed in slot " +
                                    std::to_string(slot));
      }
    }
 
    auto subIt = module->submodules.find(submoduleId);
    if (subIt == module->submodules.end())
    {
      throw std::invalid_argument("Unknown submodule ID '" + submoduleId + "' in module '" + moduleId + "'");
    }
    const GSDMLSubmodule& sm = subIt->second;
 
    rpc::IOSlot ioSlot;
    ioSlot.slot = static_cast<std::uint16_t>(slot);
    ioSlot.subslot = static_cast<std::uint16_t>(subslot);
    ioSlot.inputLength = static_cast<std::uint16_t>(sm.inputLength);
    ioSlot.outputLength = static_cast<std::uint16_t>(sm.outputLength);
    ioSlot.moduleIdent = module->moduleIdentNumber;
    ioSlot.submoduleIdent = sm.submoduleIdentNumber;
    slots.push_back(ioSlot);
  };
 
  if (!plugged.empty())
  {
    for (const auto& [Slot, ModuleId, Subslot, SubmoduleId] : plugged)
    {
      addModuleSubmodule(Slot, ModuleId, Subslot, SubmoduleId);
    }
  }
  else
  {
    // No explicit plan given -- fall back to whatever the GSDML marks
    // as fixed (pre-plugged) modules, using each module's first
    // declared submodule at subslot 1 (matches gsdml.py's default).
    for (const auto& [slot, moduleId] : fixedModules)
    {
      const GSDMLModule* module = FindModule(moduleId);
      if ((module == nullptr) || module->submodules.empty())
      {
        continue;
      }
      addModuleSubmodule(slot, moduleId, 1, module->submodules.begin()->first);
    }
  }
 
  return slots;
}
*/
 
std::vector<rpc::IOSlot> GSDMLDevice::BuildIoSlots(const std::vector<std::tuple<int, std::string, int, std::string>>& plugged) const
{
  std::vector<rpc::IOSlot> slots;
 
  // ========================================================================
  // Configure IOCR participation.
  // ========================================================================
  //
  // A slot with input data participates as an IODataObject in the INPUT CR.
  // A slot with output data participates as an IODataObject in the OUTPUT CR.
  //
  // The opposite CR carries the corresponding IOCS object.
  //
  // Zero-length DAP/PDEV submodules are special: they do not have process
  // data, but they still participate in both IOCRs as required by the
  // configured device layout.
  //
  auto configureIocrParticipation = [](rpc::IOSlot& slot, bool includeZeroIoInCyclicConfiguration = false)
  {
    const bool hasInputData = slot.inputLength > 0;
    const bool hasOutputData = slot.outputLength > 0;
    const bool isZeroIo = !hasInputData && !hasOutputData;
 
    if (isZeroIo && includeZeroIoInCyclicConfiguration)
    {
      // DAP/PDEV cyclic objects:
      //
      //   INPUT CR  -> IOData
      //   OUTPUT CR -> IOCS
      //
      slot.inputIoData = true;
      slot.outputIoData = false;
 
      slot.inputIocs = false;
      slot.outputIocs = true;
 
      return;
    }
 
    // Normal process-data modules.
    //
    // Input-producing module:
    //
    //   INPUT CR  -> IOData
    //   OUTPUT CR -> IOCS
    //
    slot.inputIoData = hasInputData;
    slot.outputIocs = hasInputData;
 
    // Output-producing module:
    //
    //   OUTPUT CR -> IOData
    //   INPUT CR  -> IOCS
    //
    slot.outputIoData = hasOutputData;
    slot.inputIocs = hasOutputData;
  };
 
  // ========================================================================
  // DAP virtual submodules
  // ========================================================================
  //
  // Python:
  //
  //   for i, sub in enumerate(dap.submodules):
  //       IOSlot(
  //           slot=0,
  //           subslot=i + 1,
  //           ...
  //       )
  //
  // DAP virtual submodules are different from the system-defined interface
  // and port submodules. Their subslot numbers are assigned sequentially
  // starting at 1.
  //
  for (std::size_t i = 0; i < dapSubmodules.size(); ++i)
  {
    const GSDMLSubmodule& sub = dapSubmodules[i];
 
    rpc::IOSlot slot;
    slot.slot = 0;
    slot.subslot = static_cast<std::uint16_t>(i + 1);
    slot.inputLength = static_cast<std::uint16_t>(sub.inputLength);
    slot.outputLength = static_cast<std::uint16_t>(sub.outputLength);
    slot.moduleIdent = dapModuleIdentNumber;
    slot.submoduleIdent = sub.submoduleIdentNumber;
 
    configureIocrParticipation(slot, true);
 
    slots.push_back(slot);
  }
 
  // ========================================================================
  // DAP system-defined submodules
  // ========================================================================
  //
  // Interface and port submodules retain the subslot numbers specified by
  // the GSDML. They do not carry cyclic I/O data.
  //
  for (const GSDMLSystemSubmodule& sys : systemSubmodules)
  {
    rpc::IOSlot slot;
    slot.slot = 0;
    slot.subslot = sys.subslot;
    slot.inputLength = 0;
    slot.outputLength = 0;
    slot.moduleIdent = dapModuleIdentNumber;
    slot.submoduleIdent = sys.submoduleIdentNumber;
 
    configureIocrParticipation(slot, true);
 
    slots.push_back(slot);
  }
 
  // ========================================================================
  // Helper for first resolve a submodule
  // ========================================================================
  auto resolveSubmodule = [&](const GSDMLModule& module, const std::string& submoduleId) -> const GSDMLSubmodule*
  {
    // Inline submodule.
    const auto inlineIt = module.submodules.find(submoduleId);
 
    if (inlineIt != module.submodules.end())
    {
      return &inlineIt->second;
    }
 
    const auto refIt = std::ranges::find_if(module.submoduleReferences, [&](const GSDMLSubmoduleReference& ref)
    {
      return ref.submoduleId == submoduleId;
    });
 
    if (refIt == module.submoduleReferences.end())
    {
      return nullptr;
    }
 
    // Globally defined submodule.
    return FindSubmodule(submoduleId);
  };
 
  // ========================================================================
  // Helper for validating module in slots
  // ========================================================================
  auto isModuleAllowedInSlot = [&](const std::string& moduleId, int slotNumber)
  {
    bool hasRestrictions = false;
 
    for (const auto& ref : moduleReferences)
    {
      if (ref.moduleId != moduleId)
      {
        continue;
      }
 
      if (!ref.allowedSlots.empty())
      {
        hasRestrictions = true;
 
        if (std::ranges::find(
                ref.allowedSlots,
                slotNumber) != ref.allowedSlots.end())
        {
          return true;
        }
      }
 
      if (std::ranges::find(
              ref.fixedSlots,
              slotNumber) != ref.fixedSlots.end())
      {
        return true;
      }
 
      if (std::ranges::find(
              ref.usedSlots,
              slotNumber) != ref.usedSlots.end())
      {
        return true;
      }
    }
 
    return !hasRestrictions;
  };
  // ========================================================================
  // Helper for valid subslot
  // ========================================================================
  auto validateSubslot = [&](const GSDMLModule& module, const std::string& submoduleId, int subslotNumber)
  {
    const auto refIt = std::ranges::find_if(module.submoduleReferences, [&](const GSDMLSubmoduleReference& ref)
    {
      return ref.submoduleId == submoduleId;
    });
 
    if (refIt == module.submoduleReferences.end())
    {
      return;
    }
 
    if (!refIt->allowedSubslots.empty() &&
        std::ranges::find(refIt->allowedSubslots, subslotNumber) == refIt->allowedSubslots.end())
    {
      throw std::invalid_argument("Submodule '" + submoduleId + "' is not allowed in subslot " + std::to_string(subslotNumber) + " of module '" + module.id + "'");
    }
  };
  // ========================================================================
  // Helper for adding one module submodule
  // ========================================================================
  auto addModuleSubmodule = [&](int slotNumber, const std::string& moduleId, int subslotNumber, const std::string& submoduleId)
  {
    const GSDMLModule* module = FindModule(moduleId);
 
    if (module == nullptr)
    {
      throw std::invalid_argument("Unknown module ID: " + moduleId);
    }
    /*
    const GSDMLModuleReference* moduleRef = nullptr;
 
    for (const auto& ref : moduleReferences)
    {
      if (ref.moduleId == moduleId)
      {
        moduleRef = &ref;
        break;
      }
    }
    */
    // if (moduleRef != nullptr && !moduleRef->allowedSlots.empty() && std::ranges::find(moduleRef->allowedSlots, slotNumber) == moduleRef->allowedSlots.end())
    if (!isModuleAllowedInSlot(moduleId, slotNumber))
    {
      throw std::invalid_argument("Module '" + moduleId + "' is not allowed in slot " + std::to_string(slotNumber));
    }
 
    validateSubslot(*module, submoduleId, subslotNumber);
 
    const GSDMLSubmodule* submodule = resolveSubmodule(*module, submoduleId);
 
    if (submodule == nullptr)
    {
      throw std::invalid_argument("Unknown submodule ID '" + submoduleId + "' in module '" + moduleId + "'");
    }
    /*
    // Validate the requested slot against AllowedInSlots / UseableModules.
    const auto allowedIt = allowedSlots.find(moduleId);
 
    if (allowedIt != allowedSlots.end() && !allowedIt->second.empty())
    {
      const auto slotIt =
          std::find(allowedIt->second.begin(),
                    allowedIt->second.end(),
                    slotNumber);
 
      if (slotIt == allowedIt->second.end())
      {
        throw std::invalid_argument(
            "Module '" + moduleId + "' is not allowed in slot " +
            std::to_string(slotNumber));
      }
    }
 
    const auto submoduleIt = module->submodules.find(submoduleId);
 
    if (submoduleIt == module->submodules.end())
    {
      throw std::invalid_argument(
          "Unknown submodule ID '" + submoduleId +
          "' in module '" + moduleId + "'");
    }
 
    const GSDMLSubmodule& submodule = submoduleIt->second;
*/
    rpc::IOSlot ioSlot;
    ioSlot.slot = static_cast<std::uint16_t>(slotNumber);
    ioSlot.subslot = static_cast<std::uint16_t>(subslotNumber);
    ioSlot.inputLength = static_cast<std::uint16_t>(submodule->inputLength);
    ioSlot.outputLength = static_cast<std::uint16_t>(submodule->outputLength);
    ioSlot.moduleIdent = module->moduleIdentNumber;
    ioSlot.submoduleIdent = submodule->submoduleIdentNumber;
 
    configureIocrParticipation(ioSlot);
 
    slots.push_back(ioSlot);
  };
 
  // ========================================================================
  // Explicit module/submodule assignment
  // ========================================================================
  //
  // This corresponds to the Python implementation receiving an explicit
  // slot_assignment/submodule_assignment.
  //
  if (!plugged.empty())
  {
    for (const auto& [slotNumber, moduleId, subslotNumber, submoduleId] : plugged)
    {
      addModuleSubmodule(
          slotNumber,
          moduleId,
          subslotNumber,
          submoduleId);
    }
    return slots;
  }
  /*
    // ========================================================================
    // Default: use fixed modules from the GSDML
    // ========================================================================
    //
    // Python:
    //
    //   if slot_assignment is None:
    //       assignment = {}
    //       for mod_id, fixed in dap.fixed_slots.items():
    //           for slot_num in fixed:
    //               assignment[slot_num] = mod_id
    //
    // `fixedModules` currently represents:
    //
    //   slot number -> module ID
    //
    for (const auto& [slotNumber, moduleId] : fixedModules)
    {
      const GSDMLModule* module = FindModule(moduleId);
 
      if (module == nullptr)
      {
        throw std::invalid_argument(
            "Unknown fixed module ID: " + moduleId);
      }
 
      // ----------------------------------------------------------------------
      // Module with inline VirtualSubmoduleList
      // ----------------------------------------------------------------------
      //
      // Python:
      //
      //   if mod.submodules:
      //       for i, sub in enumerate(mod.submodules):
      //           IOSlot(
      //               slot=slot_num,
      //               subslot=i + 1,
      //               ...
      //           )
      //
      // Therefore all inline submodules must be added, not just the first one.
      //
      if (!module->submodules.empty())
      {
        std::uint16_t subslotNumber = 1;
 
        for (const auto& [submoduleId, submodule] : module->submodules)
        {
          (void)submodule;
 
          addModuleSubmodule(
              slotNumber,
              moduleId,
              subslotNumber,
              submoduleId);
 
          ++subslotNumber;
        }
      }
 
      // ----------------------------------------------------------------------
      // Module with referenced UseableSubmodules
      // ----------------------------------------------------------------------
      //
      // The Python implementation handles these through:
      //
      //   self._add_useable_submodule_slots(...)
      //
      // The current C++ GSDMLModule representation does not yet contain the
      // equivalent useable_submodules/submodule catalog information, so there
      // is nothing further to add here.
      //
      // Once that representation exists, this branch should resolve the
      // selected submodules in the same way as the Python implementation.
 
  }
  return slots;
  */
 
  // ========================================================================
  // Default configuration from GSDML
  // ========================================================================
 
  for (const GSDMLModuleReference& moduleRef : moduleReferences)
  {
    const GSDMLModule* module = FindModule(moduleRef.moduleId);
 
    if (module == nullptr)
    {
      throw std::invalid_argument("Unknown referenced module ID: " + moduleRef.moduleId);
    }
 
    std::vector<int> selectedSlots;
 
    if (!moduleRef.fixedSlots.empty())
    {
      selectedSlots = moduleRef.fixedSlots;
    }
    else if (!moduleRef.usedSlots.empty())
    {
      selectedSlots = moduleRef.usedSlots;
    }
    else
    {
      // AllowedInSlots only describes capability, not actual selection.
      continue;
    }
 
    for (const int slotNumber : selectedSlots)
    {
      // ================================================================
      // Referenced SubmoduleItem definitions
      // ================================================================
 
      if (!module->submoduleReferences.empty())
      {
        for (const auto& submoduleRef : module->submoduleReferences)
        {
          std::vector<int> selectedSubslots;
 
          if (!submoduleRef.fixedSubslots.empty())
          {
            selectedSubslots = submoduleRef.fixedSubslots;
          }
          else if (!submoduleRef.usedSubslots.empty())
          {
            selectedSubslots = submoduleRef.usedSubslots;
          }
          else
          {
            continue;
          }
 
          for (const int subslotNumber : selectedSubslots)
          {
            addModuleSubmodule(
                slotNumber,
                moduleRef.moduleId,
                subslotNumber,
                submoduleRef.submoduleId);
          }
        }
 
        continue;
      }
 
      // ================================================================
      // Inline VirtualSubmoduleItem definitions
      // ================================================================
 
      for (const auto& [submoduleId, submodule] : module->submodules)
      {
        std::vector<int> selectedSubslots;
 
        if (!submodule.fixedSubslots.empty())
        {
          selectedSubslots = submodule.fixedSubslots;
        }
        else if (!submodule.usedSubslots.empty())
        {
          selectedSubslots = submodule.usedSubslots;
        }
        else if (module->submodules.size() == 1U)
        {
          // Compatibility fallback for simple GSDML files where a
          // single virtual submodule has no explicit placement.
          selectedSubslots = {1};
        }
 
        for (const int subslotNumber : selectedSubslots)
        {
          addModuleSubmodule(
              slotNumber,
              moduleRef.moduleId,
              subslotNumber,
              submoduleId);
        }
      }
    }
  }
  return slots;
}
 
// =============================================================================
// Parsing
// =============================================================================
 
GSDMLDevice ParseGsdmlString(const std::string& xml)
{
  XmlDocGuard docGuard;
  docGuard.doc = xmlReadMemory(xml.data(), static_cast<int>(xml.size()), "gsdml.xml", nullptr,
                               XML_PARSE_NOBLANKS);
  if (docGuard.doc == nullptr)
  {
    throw std::runtime_error("Failed to parse GSDML: not well-formed XML");
  }
 
  xmlNodePtr root = xmlDocGetRootElement(docGuard.doc);
  if (root == nullptr)
  {
    throw std::runtime_error("Failed to parse GSDML: empty document");
  }
 
  XPathContextGuard ctxGuard;
  ctxGuard.ctx = xmlXPathNewContext(docGuard.doc);
  if (ctxGuard.ctx == nullptr)
  {
    throw std::runtime_error("Failed to create XPath context");
  }
  xmlXPathContextPtr ctx = ctxGuard.ctx;
 
  GSDMLDevice device;
 
  auto textTable = BuildTextTable(ctx, root);
 
  xmlNodePtr deviceIdentity = FindFirst(ctx, root, "DeviceIdentity");
  if (deviceIdentity == nullptr)
  {
    // throw std::runtime_error("Failed to parse GSDML: no DeviceIdentity element found");
  }
  else
  {
    device.vendorId = static_cast<std::uint16_t>(ParseInt(GetAttrOpt(deviceIdentity, "VendorID")));
    device.deviceId = static_cast<std::uint16_t>(ParseInt(GetAttrOpt(deviceIdentity, "DeviceID")));
    device.vendorName = ResolveName(ctx, deviceIdentity, textTable, "");
  }
  xmlNodePtr deviceFunction = FindFirst(ctx, root, "DeviceFunction");
  device.deviceName = (deviceFunction != nullptr) ? ResolveName(ctx, deviceFunction, textTable, "") : device.vendorName;
 
  // Device Access Point (DAP): the device's own built-in module/submodule.
  xmlNodePtr dap = FindFirst(ctx, root, "DeviceAccessPointItem");
  if (dap != nullptr)
  {
    device.dapModuleId = GetAttr(dap, "ID");
    device.dapModuleIdentNumber = ParseInt(GetAttrOpt(dap, "ModuleIdentNumber"));
 
    // xmlNodePtr dapSubmodule = dap; // DAP's own submodule ident is on the DAP item itself.
    // device.dapSubmoduleIdentNumber = ParseInt(GetAttrOpt(dapSubmodule, "SubmoduleIdentNumber"));
 
    device.dapSlots = ParseSlotSpec(GetAttrOpt(dap, "PhysicalSlots"));
 
    xmlNodePtr sysList = FindFirst(ctx, dap, "SystemDefinedSubmoduleList");
    if (sysList != nullptr)
    {
      for (auto* subNode : FindChildren(ctx, sysList, "InterfaceSubmoduleItem"))
      {
        GSDMLSystemSubmodule sys;
        sys.submoduleIdentNumber = ParseInt(GetAttrOpt(subNode, "SubmoduleIdentNumber"));
        // sys.subslot = static_cast<std::uint16_t>(ParseInt(GetAttrOpt(subNode, "Subslot")));
        sys.subslot = static_cast<std::uint16_t>(ParseInt(GetAttrOpt(subNode, "SubslotNumber")));
        device.systemSubmodules.push_back(sys);
      }
      for (auto* subNode : FindChildren(ctx, sysList, "PortSubmoduleItem"))
      {
        GSDMLSystemSubmodule sys;
        sys.submoduleIdentNumber = ParseInt(GetAttrOpt(subNode, "SubmoduleIdentNumber"));
        // sys.subslot = static_cast<std::uint16_t>(ParseInt(GetAttrOpt(subNode, "Subslot")));
        sys.subslot = static_cast<std::uint16_t>(ParseInt(GetAttrOpt(subNode, "SubslotNumber")));
        device.systemSubmodules.push_back(sys);
      }
    }
 
    // Modules the DAP itself provides directly (VirtualSubmoduleList on the DAP).
    xmlNodePtr dapVsl = FindFirst(ctx, dap, "VirtualSubmoduleList");
    if (dapVsl != nullptr)
    {
      // Also expose the DAP virtual submodule through the module catalogue.
      GSDMLModule dapModule;
      dapModule.id = device.dapModuleId;
      dapModule.moduleIdentNumber = device.dapModuleIdentNumber;
      dapModule.name = device.deviceName;
 
      for (auto* subNode : FindChildren(ctx, dapVsl, "VirtualSubmoduleItem"))
      {
        GSDMLSubmodule sm = ParseSubmoduleNode(ctx, subNode, textTable);
 
        // Keep DAP virtual submodules separately so BuildIoSlots() can reproduce
        // the Python implementation's DAP slot-0 entries.
        device.dapSubmodules.push_back(sm);
 
        if (device.dapModuleId == sm.id)
        {
          device.dapSubmoduleIdentNumber = sm.submoduleIdentNumber;
        }
        dapModule.submodules[sm.id.empty() ? "dap" : sm.id] = sm;
      }
      // if (sm.submoduleIdentNumber == 0)
      //         {
      //           // hier moet een fix
      //           sm.submoduleIdentNumber = device.dapSubmoduleIdentNumber;
      //         }
      if (device.dapSubmoduleIdentNumber == 0 && !device.dapSubmodules.empty())
      {
        device.dapSubmoduleIdentNumber = device.dapSubmodules.front().submoduleIdentNumber;
      }
      device.modules[dapModule.id] = std::move(dapModule);
    }
  }
 
  // ModuleList: every pluggable module and its virtual submodules.
  xmlNodePtr moduleList = FindFirst(ctx, root, "ModuleList");
  if (moduleList != nullptr)
  {
    for (auto* moduleNode : FindChildren(ctx, moduleList, "ModuleItem"))
    {
      GSDMLModule mod;
      mod.id = GetAttr(moduleNode, "ID");
      mod.moduleIdentNumber = ParseInt(GetAttrOpt(moduleNode, "ModuleIdentNumber"));
      mod.name = ResolveName(ctx, moduleNode, textTable, mod.id);
      mod.physicalSubslots = ParseSlotSpec(GetAttrOpt(moduleNode, "PhysicalSubslots"));
 
      xmlNodePtr vsl = FindFirst(ctx, moduleNode, "VirtualSubmoduleList");
      if (vsl != nullptr)
      {
        for (auto* subNode : FindChildren(ctx, vsl, "VirtualSubmoduleItem"))
        {
          GSDMLSubmodule sm = ParseSubmoduleNode(ctx, subNode, textTable);
          mod.submodules[sm.id] = std::move(sm);
        }
      }
 
      // ----------------------------------------------------------------------
      // Module with referenced UseableSubmodules
      // ----------------------------------------------------------------------
      //
      // The Python implementation handles these through:
      //
      //   self._add_useable_submodule_slots(...)
      //
      // The current C++ GSDMLModule representation does not yet contain the
      // equivalent useable_submodules/submodule catalog information, so there
      // is nothing further to add here.
      //
      // Once that representation exists, this branch should resolve the
      // selected submodules in the same way as the Python implementation.
      xmlNodePtr usableSubmodules = FindFirst(ctx, moduleNode, "UseableSubmodules");
 
      if (usableSubmodules != nullptr)
      {
        for (auto* refNode : FindChildren(ctx, usableSubmodules, "SubmoduleItemRef"))
        {
          GSDMLSubmoduleReference ref;
          ref.submoduleId = GetAttr(refNode, "SubmoduleItemTarget");
          ref.allowedSubslots = ParseSlotSpec(GetAttrOpt(refNode, "AllowedInSubslots"));
          ref.fixedSubslots = ParseSlotSpec(GetAttrOpt(refNode, "FixedInSubslots"));
          ref.usedSubslots = ParseSlotSpec(GetAttrOpt(refNode, "UsedInSubslots"));
          mod.submoduleReferences.push_back(std::move(ref));
        }
      }
 
      device.modules[mod.id] = std::move(mod);
    }
  }
 
  // ========================================================================
  // Global SubmoduleList
  // ========================================================================
  //
  // Some GSDML files define submodules inline inside a ModuleItem using
  // VirtualSubmoduleList. Others, such as Phoenix Contact GSDMLs, define
  // SubmoduleItem objects globally and reference them through
  // UseableSubmodules/SubmoduleItemRef.
  //
  xmlNodePtr submoduleList = FindFirst(ctx, root, "SubmoduleList");
 
  if (submoduleList != nullptr)
  {
    for (auto* submoduleNode :
         FindChildren(ctx, submoduleList, "SubmoduleItem"))
    {
      GSDMLSubmodule submodule =
          ParseSubmoduleNode(ctx, submoduleNode, textTable);
 
      device.submodules[submodule.id] = std::move(submodule);
    }
  }
 
  // UseableModules: which slots each module may be plugged into, and
  // which modules are fixed (pre-plugged) at a given slot.
  xmlNodePtr useList = FindFirst(ctx, (dap != nullptr) ? dap : root, "UseableModules");
  if (useList != nullptr)
  {
    for (auto* useNode : FindChildren(ctx, useList, "ModuleItemRef"))
    {
      /*
      std::string moduleId = GetAttr(useNode, "ModuleItemTarget");
      device.allowedSlots[moduleId] = ParseSlotSpec(GetAttrOpt(useNode, "AllowedInSlots"));
*/
      GSDMLModuleReference ref;
      ref.moduleId = GetAttr(useNode, "ModuleItemTarget");
      ref.allowedSlots = ParseSlotSpec(GetAttrOpt(useNode, "AllowedInSlots"));
      ref.fixedSlots = ParseSlotSpec(GetAttrOpt(useNode, "FixedInSlots"));
      ref.usedSlots = ParseSlotSpec(GetAttrOpt(useNode, "UsedInSlots"));
      device.moduleReferences.push_back(std::move(ref));
    }
  }
  // PredefinedPnioModules:
  //
  xmlNodePtr fixedList = FindFirst(ctx, (dap != nullptr) ? dap : root, "PredefinedPnioModules");
  if (fixedList != nullptr)
  {
    for (auto* fixedNode : FindChildren(ctx, fixedList, "PnioModuleItemRef"))
    {
      GSDMLModuleReference ref;
      ref.moduleId = GetAttr(fixedNode, "ModuleItemTarget");
      ref.fixedSlots = ParseSlotSpec(GetAttrOpt(fixedNode, "FixedInSlots"));
      device.moduleReferences.push_back(std::move(ref));
 
      /*
      for (int slot : ParseSlotSpec(GetAttrOpt(fixedNode, "FixedInSlots")))
      {
        device.fixedModules.emplace_back(slot, moduleId);
      }
      */
    }
  }
  return device;
}
 
GSDMLDevice ParseGsdml(const std::string& path)
{
  XmlDocGuard docGuard;
  docGuard.doc = xmlReadFile(path.c_str(), nullptr, XML_PARSE_NOBLANKS);
  if (docGuard.doc == nullptr)
  {
    throw std::runtime_error("Failed to open or parse GSDML file: " + path);
  }
 
  // Re-serialize and re-parse via ParseGsdmlString to keep a single
  // parsing code path (xmlReadFile already validated well-formedness,
  // so this second pass is cheap and keeps the implementation simple).
  xmlChar* buf = nullptr;
  int size = 0;
  xmlDocDumpMemory(docGuard.doc, &buf, &size);
  std::string xml(reinterpret_cast<const char*>(buf), static_cast<std::size_t>(size));
  xmlFree(buf);
 
  return ParseGsdmlString(xml);
}
 
} // namespace profinet::gsdml