Welcome to Merlin documentation!

This is the Merlin driver framework architecture and API documentation. The Merlin framework is an efficient userspace driver helper library made in order to help with Camelot-OS userspace driver implementation.

Its goal is to simplify the way drivers developper interact with the Operating System, so that only the device-related implementation is required when writing a device driver.

In order to achieve that, all the platform generic function are hold by Merlin itself. This, for example, include the probing system, the device-tree related informations manipulation, or the way IRQ events are dispatch toward the (potentially various) userspace ISRs implementations.

The Merlin driver framework is a part of the Camelot Operating System, built to deploy a high level security upto the micro-controller, ensuring secure manipulation of complex or performance critical I/O the SE is not able to handle.

Contents:

• Merlin Concepts
  • 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
• Merlin Build system
  • Basics and targets
    • Dependencies
    • About Merlin sources hierarchy
  • Device tree usage
    • Overview
    • Sample Input artifacts
• Writing Merlin Drivers
  • Merlin-based USART driver
    • Public API contract
    • Status model
    • Driver structure and platform integration
    • Probe/init/runtime/release pseudo-code
    • Alias pattern (recommended)
  • Merlin-based SPI driver
    • Public API contract
    • Status model
    • Platform descriptor pattern
    • Probe/init/xfer/release pseudo-code
    • Chip-select handling
    • Alias pattern (recommended)
  • Merlin-based I2C driver
    • Public API contract
    • Status model
    • Platform descriptor pattern
    • Probe/init/release pseudo-code
    • Read/write operations
    • Alias pattern (recommended)
  • Merlin-based USB driver
    • Current API status
    • Recommended transition model
    • Status mapping guidelines
    • Platform integration pattern
    • Note on existing examples
• Merlin Tests
  • Device driver examples