# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/ata/ahci-common.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Common Properties for Serial ATA AHCI controllers

maintainers:
  - Hans de Goede <hdegoede@redhat.com>
  - Damien Le Moal <damien.lemoal@opensource.wdc.com>

description:
  This document defines device tree properties for a common AHCI SATA
  controller implementation. It's hardware interface is supposed to
  conform to the technical standard defined by Intel (see Serial ATA
  Advanced Host Controller Interface specification for details). The
  document doesn't constitute a DT-node binding by itself but merely
  defines a set of common properties for the AHCI-compatible devices.

select: false

allOf:
  - $ref: sata-common.yaml#

properties:
  reg:
    description:
      Generic AHCI registers space conforming to the Serial ATA AHCI
      specification.

  reg-names:
    description: CSR space IDs
    contains:
      const: ahci

  interrupts:
    description:
      Generic AHCI state change interrupt. Can be implemented either as a
      single line attached to the controller or as a set of the signals
      indicating the particular port events.
    minItems: 1
    maxItems: 32

  ahci-supply:
    description: Power regulator for AHCI controller

  target-supply:
    description: Power regulator for SATA target device

  phy-supply:
    description: Power regulator for SATA PHY

  phys:
    description: Reference to the SATA PHY node
    maxItems: 1

  phy-names:
    const: sata-phy

  hba-cap:
    $ref: '/schemas/types.yaml#/definitions/uint32'
    description:
      Bitfield of the HBA generic platform capabilities like Staggered
      Spin-up or Mechanical Presence Switch support. It can be used to
      appropriately initialize the HWinit fields of the HBA CAP register
      in case if the system firmware hasn't done it.

  ports-implemented:
    $ref: '/schemas/types.yaml#/definitions/uint32'
    description:
      Mask that indicates which ports the HBA supports. Useful if PI is not
      programmed by the BIOS, which is true for some embedded SoC's.

patternProperties:
  "^sata-port@[0-9a-f]+$":
    $ref: '#/$defs/ahci-port'
    description:
      It is optionally possible to describe the ports as sub-nodes so
      to enable each port independently when dealing with multiple PHYs.

required:
  - reg
  - interrupts

additionalProperties: true

$defs:
  ahci-port:
    $ref: /schemas/ata/sata-common.yaml#/$defs/sata-port

    properties:
      reg:
        description:
          AHCI SATA port identifier. By design AHCI controller can't have
          more than 32 ports due to the CAP.NP fields and PI register size
          constraints.
        minimum: 0
        maximum: 31

      phys:
        description: Individual AHCI SATA port PHY
        maxItems: 1

      phy-names:
        description: AHCI SATA port PHY ID
        const: sata-phy

      target-supply:
        description: Power regulator for SATA port target device

      hba-port-cap:
        $ref: '/schemas/types.yaml#/definitions/uint32'
        description:
          Bitfield of the HBA port-specific platform capabilities like Hot
          plugging, eSATA, FIS-based Switching, etc (see AHCI specification
          for details). It can be used to initialize the HWinit fields of
          the PxCMD register in case if the system firmware hasn't done it.

    required:
      - reg

...