Documentation/devicetree/bindings/net/wireless/qcom,ath12k-wsi.yaml

# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
# Copyright (c) 2024 Qualcomm Innovation Center, Inc. All rights reserved.
%YAML 1.2
---
$id: http://devicetree.org/schemas/net/wireless/qcom,ath12k-wsi.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Qualcomm Technologies ath12k wireless devices (PCIe) with WSI interface

maintainers:
  - Jeff Johnson <jjohnson@kernel.org>

description: |
  Qualcomm Technologies IEEE 802.11be PCIe devices with WSI interface.

  The ath12k devices (QCN9274) feature WSI support. WSI stands for
  WLAN Serial Interface. It is used for the exchange of specific
  control information across radios based on the doorbell mechanism.
  This WSI connection is essential to exchange control information
  among these devices.

  The WSI interface includes TX and RX ports, which are used to connect
  multiple WSI-supported devices together, forming a WSI group.

  Diagram to represent one WSI connection (one WSI group) among
  three devices.

           +-------+        +-------+        +-------+
           | pcie1 |        | pcie2 |        | pcie3 |
           |       |        |       |        |       |
    +----->|  wsi  |------->|  wsi  |------->|  wsi  |-----+
    |      | grp 0 |        | grp 0 |        | grp 0 |     |
    |      +-------+        +-------+        +-------+     |
    +------------------------------------------------------+

  Diagram to represent two WSI connections (two separate WSI groups)
  among four devices.

       +-------+    +-------+          +-------+    +-------+
       | pcie0 |    | pcie1 |          | pcie2 |    | pcie3 |
       |       |    |       |          |       |    |       |
   +-->|  wsi  |--->|  wsi  |--+   +-->|  wsi  |--->|  wsi  |--+
   |   | grp 0 |    | grp 0 |  |   |   | grp 1 |    | grp 1 |  |
   |   +-------+    +-------+  |   |   +-------+    +-------+  |
   +---------------------------+   +---------------------------+

properties:
  compatible:
    enum:
      - pci17cb,1109  # QCN9274

  reg:
    maxItems: 1

  qcom,calibration-variant:
    $ref: /schemas/types.yaml#/definitions/string
    description:
      String to uniquely identify variant of the calibration data for designs
      with colliding bus and device ids

  qcom,ath12k-calibration-variant:
    $ref: /schemas/types.yaml#/definitions/string
    deprecated: true
    description:
      String to uniquely identify variant of the calibration data for designs
      with colliding bus and device ids

  qcom,wsi-controller:
    $ref: /schemas/types.yaml#/definitions/flag
    description:
      The WSI controller device in the WSI group aids (is capable) to
      synchronize the Timing Synchronization Function (TSF) clock across
      all devices in the WSI group.

  ports:
    $ref: /schemas/graph.yaml#/properties/ports
    properties:
      port@0:
        $ref: /schemas/graph.yaml#/properties/port
        description:
          This is the TX port of WSI interface. It is attached to the RX
          port of the next device in the WSI connection.

      port@1:
        $ref: /schemas/graph.yaml#/properties/port
        description:
          This is the RX port of WSI interface. It is attached to the TX
          port of the previous device in the WSI connection.

required:
  - compatible
  - reg

additionalProperties: false

examples:
  - |
    pcie {
        #address-cells = <3>;
        #size-cells = <2>;

        pcie@0 {
            device_type = "pci";
            reg = <0x0 0x0 0x0 0x0 0x0>;
            #address-cells = <3>;
            #size-cells = <2>;
            ranges;

            wifi@0 {
                compatible = "pci17cb,1109";
                reg = <0x0 0x0 0x0 0x0 0x0>;

                qcom,calibration-variant = "RDP433_1";

                ports {
                    #address-cells = <1>;
                    #size-cells = <0>;

                    port@0 {
                        reg = <0>;

                        wifi1_wsi_tx: endpoint {
                            remote-endpoint = <&wifi2_wsi_rx>;
                        };
                    };

                    port@1 {
                        reg = <1>;

                        wifi1_wsi_rx: endpoint {
                            remote-endpoint = <&wifi3_wsi_tx>;
                        };
                    };
                };
            };
        };

        pcie@1 {
            device_type = "pci";
            reg = <0x0 0x0 0x1 0x0 0x0>;
            #address-cells = <3>;
            #size-cells = <2>;
            ranges;

            wifi@0 {
                compatible = "pci17cb,1109";
                reg = <0x0 0x0 0x0 0x0 0x0>;

                qcom,calibration-variant = "RDP433_2";
                qcom,wsi-controller;

                ports {
                    #address-cells = <1>;
                    #size-cells = <0>;

                    port@0 {
                        reg = <0>;

                        wifi2_wsi_tx: endpoint {
                            remote-endpoint = <&wifi3_wsi_rx>;
                        };
                    };

                    port@1 {
                        reg = <1>;

                        wifi2_wsi_rx: endpoint {
                            remote-endpoint = <&wifi1_wsi_tx>;
                        };
                    };
                };
            };
        };

        pcie@2 {
            device_type = "pci";
            reg = <0x0 0x0 0x2 0x0 0x0>;
            #address-cells = <3>;
            #size-cells = <2>;
            ranges;

            wifi@0 {
                compatible = "pci17cb,1109";
                reg = <0x0 0x0 0x0 0x0 0x0>;

                qcom,calibration-variant = "RDP433_3";

                ports {
                    #address-cells = <1>;
                    #size-cells = <0>;

                    port@0 {
                        reg = <0>;

                        wifi3_wsi_tx: endpoint {
                            remote-endpoint = <&wifi1_wsi_rx>;
                        };
                    };

                    port@1 {
                        reg = <1>;

                        wifi3_wsi_rx: endpoint {
                            remote-endpoint = <&wifi2_wsi_tx>;
                        };
                    };
                };
            };
        };
    };