Merlin Concepts

Merlin provides a layered userspace driver model for Camelot-OS. The framework centralizes platform services (device discovery, MMIO mapping, GPIO pin configuration, and IRQ routing) so driver code can focus on hardware logic and protocol behavior.

This section documents the architectural contracts that are shared by all Merlin-based drivers:

• the public C interfaces exported from include/merlin;

• the expected probe/init/runtime/release lifecycle;

• the DeviceTree properties required to bind runtime code to generated metadata.

Contents:

• Merlin Principles
  • Design intent
  • Public interface map
  • Driver object model
  • Lifecycle contract
  • Error model
  • MMIO and polling principles
  • IRQ routing principle
  • Portability rule from sample drivers
• Using Merlin in Drivers
  • Integration sequence
  • Bus controller pattern
  • External device over a bus
  • Per-family notes from reference implementations
  • Application event loop integration
  • Driver authoring checklist
• CAN Driver Concepts
  • Scope and goals
  • Unified CAN API
  • Data model
  • Platform integration details
  • DeviceTree expectations
  • Reference implementation
• DTS and dt-bindings
  • Why DTS is a hard contract
  • DTS preprocessing and include paths
  • Controller node example (I2C)
  • External child node example (I2C peripheral)
  • USB controller node example
  • Pinctrl model used by Merlin
  • Runtime binding sequence
  • Configuration prerequisites