apple,sio.yaml

# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/dma/apple,sio.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Apple SIO Coprocessor

description:
  SIO is a coprocessor on Apple M1 and later chips (and maybe also on earlier
  chips). Its role is to offload SPI, UART and DisplayPort audio transfers,
  being a pretend DMA controller.

maintainers:
  - Martin Povišer <povik+lin@cutebit.org>

allOf:
  - $ref: dma-controller.yaml#

properties:
  compatible:
    items:
      - enum:
          - apple,t6000-sio
          - apple,t8103-sio
      - const: apple,sio

  reg:
    maxItems: 1

  '#dma-cells':
    const: 1
    description:
      DMA clients specify a single cell that corresponds to the RTKit endpoint
      number used for arranging the transfers in question

  dma-channels:
    maximum: 128

  mboxes:
    maxItems: 1

  iommus:
    maxItems: 1

  power-domains:
    maxItems: 1

  memory-region:
    minItems: 2
    maxItems: 8
    description:
      A number of references to reserved memory regions among which are the DATA/TEXT
      sections of coprocessor executable firmware and also auxiliary firmware data
      describing the available DMA-enabled peripherals

  apple,sio-firmware-params:
    $ref: /schemas/types.yaml#/definitions/uint32-array
    description: |
      Parameters in the form of opaque key/value pairs that are to be sent to the SIO
      coprocesssor once it boots. These parameters can point into the reserved memory
      regions (in device address space).

      Note that unlike Apple's firmware, we treat the parameters, and the data they
      refer to, as opaque. Apple embed short data blobs into their SIO devicetree node
      that describe the DMA-enabled peripherals (presumably with defined semantics).
      Their driver processes those blobs and sets up data structure in mapped device
      memory, then references this memory in the parameters sent to the SIO. At the
      level of description we are opting for in this binding, we assume the job of
      constructing those data structures has been done in advance, leaving behind an
      opaque list of key/value parameter pairs to be sent by a prospective driver.

      This approach is chosen for two reasons:

       - It means we don't need to try to understand the semantics of Apple's blobs
         as long as we know the transformation we need to do from Apple's devicetree
         data to SIO data (which can be shoved away into a loader). It also means the
         semantics of Apple's blobs (or of something to replace them) need not be part
         of the binding and be kept up with Apple's firmware changes in the future.

       - It leaves less work for the driver attaching on this binding. Instead the work
         is done upfront in the loader which can be better suited for keeping up with
         Apple's firmware changes.

required:
  - compatible
  - reg
  - '#dma-cells'
  - dma-channels
  - mboxes
  - iommus
  - power-domains

additionalProperties: false

examples:
  - |
    sio: dma-controller@36400000 {
      compatible = "apple,t8103-sio", "apple,sio";
      reg = <0x36400000 0x8000>;
      dma-channels = <128>;
      #dma-cells = <1>;
      mboxes = <&sio_mbox>;
      iommus = <&sio_dart 0>;
      power-domains = <&ps_sio_cpu>;
      memory-region = <&sio_text>, <&sio_data>,
                      <&sio_auxdata1>, <&sio_auxdata2>; /* Filled by loader */
      apple,sio-firmware-params = <0xb 0x10>, <0xc 0x1b80>, <0xf 0x14>,
                                  <0x10 0x1e000>, <0x30d 0x34>, <0x30e 0x4000>,
                                  <0x1a 0x38>, <0x1b 0x50>; /* Filled by loader */
    };