Documentation/devicetree/bindings/firmware/google,gs101-acpm-ipc.yaml

# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
# Copyright 2024 Linaro Ltd.
%YAML 1.2
---
$id: http://devicetree.org/schemas/firmware/google,gs101-acpm-ipc.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Samsung Exynos ACPM mailbox protocol

maintainers:
  - Tudor Ambarus <tudor.ambarus@linaro.org>

description: |
  ACPM (Alive Clock and Power Manager) is a firmware that operates on the
  APM (Active Power Management) module that handles overall power management
  activities. ACPM and masters regard each other as independent hardware
  component and communicate with each other using mailbox messages and
  shared memory.

  This binding is intended to define the interface the firmware implementing
  ACPM provides for OSPM in the device tree.

properties:
  compatible:
    const: google,gs101-acpm-ipc

  "#clock-cells":
    const: 1
    description:
      Clocks that are variable and index based. These clocks don't provide
      an entire range of values between the limits but only discrete points
      within the range. The firmware also manages the voltage scaling
      appropriately with the clock scaling. The argument is the ID of the
      clock contained by the firmware messages.

  mboxes:
    maxItems: 1

  pmic:
    description: Child node describing the main PMIC.
    type: object
    additionalProperties: true

    properties:
      compatible:
        const: samsung,s2mpg10-pmic

  shmem:
    description:
      List of phandle pointing to the shared memory (SHM) area. The memory
      contains channels configuration data and the TX/RX ring buffers that
      are used for passing messages to/from the ACPM firmware.
    maxItems: 1

required:
  - compatible
  - "#clock-cells"
  - mboxes
  - shmem

additionalProperties: false

examples:
  - |
    #include <dt-bindings/interrupt-controller/irq.h>

    power-management {
        compatible = "google,gs101-acpm-ipc";
        #clock-cells = <1>;
        mboxes = <&ap2apm_mailbox>;
        shmem = <&apm_sram>;

        pmic {
            compatible = "samsung,s2mpg10-pmic";
            interrupts-extended = <&gpa0 6 IRQ_TYPE_LEVEL_LOW>;

            regulators {
                ldo1m {
                    regulator-name = "vdd_ldo1";
                    regulator-min-microvolt = <700000>;
                    regulator-max-microvolt = <1300000>;
                    regulator-always-on;
                };

                // ...

                buck8m {
                    regulator-name = "vdd_mif";
                    regulator-min-microvolt = <450000>;
                    regulator-max-microvolt = <1300000>;
                    regulator-always-on;
                    regulator-boot-on;
                };
            };
        };
    };