mediatek,mt8196-sys-clock.yaml

  1# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
  2%YAML 1.2
  3---
  4$id: http://devicetree.org/schemas/clock/mediatek,mt8196-sys-clock.yaml#
  5$schema: http://devicetree.org/meta-schemas/core.yaml#
  6
  7title: MediaTek System Clock Controller for MT8196
  8
  9maintainers:
 10  - Guangjie Song <guangjie.song@mediatek.com>
 11  - Laura Nao <laura.nao@collabora.com>
 12
 13description: |
 14  The clock architecture in MediaTek SoCs is structured like below:
 15  PLLs -->
 16          dividers -->
 17                      muxes
 18                           -->
 19                              clock gate
 20
 21  The apmixedsys, apmixedsys_gp2, vlpckgen, armpll, ccipll, mfgpll and ptppll
 22  provide most of the PLLs which are generated from the SoC's 26MHZ crystal oscillator.
 23  The topckgen, topckgen_gp2 and vlpckgen provide dividers and muxes which
 24  provide the clock source to other IP blocks.
 25
 26properties:
 27  compatible:
 28    items:
 29      - enum:
 30          - mediatek,mt8196-apmixedsys
 31          - mediatek,mt8196-armpll-b-pll-ctrl
 32          - mediatek,mt8196-armpll-bl-pll-ctrl
 33          - mediatek,mt8196-armpll-ll-pll-ctrl
 34          - mediatek,mt8196-apmixedsys-gp2
 35          - mediatek,mt8196-ccipll-pll-ctrl
 36          - mediatek,mt8196-mfgpll-pll-ctrl
 37          - mediatek,mt8196-mfgpll-sc0-pll-ctrl
 38          - mediatek,mt8196-mfgpll-sc1-pll-ctrl
 39          - mediatek,mt8196-ptppll-pll-ctrl
 40          - mediatek,mt8196-topckgen
 41          - mediatek,mt8196-topckgen-gp2
 42          - mediatek,mt8196-vlpckgen
 43      - const: syscon
 44
 45  reg:
 46    maxItems: 1
 47
 48  '#clock-cells':
 49    const: 1
 50
 51  mediatek,hardware-voter:
 52    $ref: /schemas/types.yaml#/definitions/phandle
 53    description: |
 54      Phandle to the "Hardware Voter" (HWV), as named in the vendor
 55      documentation for MT8196/MT6991.
 56
 57      The HWV is a SoC-internal fixed-function MCU used to collect votes from
 58      both the Application Processor and other remote processors within the SoC.
 59      It is intended to transparently enable or disable hardware resources (such
 60      as power domains or clocks) based on internal vote aggregation handled by
 61      the MCU's internal state machine.
 62
 63      However, in practice, this design is incomplete. While the HWV performs
 64      some internal vote aggregation,software is still required to
 65      - Manually enable power supplies externally, if present and if required
 66      - Manually enable parent clocks via direct MMIO writes to clock controllers
 67      - Enable the FENC after the clock has been ungated via direct MMIO
 68      writes to clock controllers
 69
 70      As such, the HWV behaves more like a hardware-managed clock reference
 71      counter than a true voter. Furthermore, it is not a separate
 72      controller. It merely serves as an alternative interface to the same
 73      underlying clock or power controller. Actual control still requires
 74      direct access to the controller's own MMIO register space, in
 75      addition to writing to the HWV's MMIO region.
 76
 77      For this reason, a custom phandle is used here - drivers need to directly
 78      access the HWV MMIO region in a syscon-like fashion, due to how the
 79      hardware is wired. This differs from true hardware voting systems, which
 80      typically do not require custom phandles and rely instead on generic APIs
 81      (clocks, power domains, interconnects).
 82
 83      The name "hardware-voter" is retained to match vendor documentation, but
 84      this should not be reused or misunderstood as a proper voting mechanism.
 85
 86required:
 87  - compatible
 88  - reg
 89  - '#clock-cells'
 90
 91additionalProperties: false
 92
 93examples:
 94  - |
 95    apmixedsys_clk: syscon@10000800 {
 96        compatible = "mediatek,mt8196-apmixedsys", "syscon";
 97        reg = <0x10000800 0x1000>;
 98        #clock-cells = <1>;
 99    };
100  - |
101    topckgen: syscon@10000000 {
102        compatible = "mediatek,mt8196-topckgen", "syscon";
103        reg = <0x10000000 0x800>;
104        mediatek,hardware-voter = <&scp_hwv>;
105        #clock-cells = <1>;
106    };
107