# SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note
#
# (C) COPYRIGHT 2023 ARM Limited. All rights reserved.
#
# This program is free software and is provided to you under the terms of the
# GNU General Public License version 2 as published by the Free Software
# Foundation, and any use by you of this program is subject to the terms
# of such GNU license.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, you can access it online at
# http://www.gnu.org/licenses/gpl-2.0.html.
#
#
=====================================
ARM CoreSight Mali Source integration
=====================================

See Documentation/trace/coresight/coresight.rst for detailed information
about Coresight.

This documentation will cover Mali specific devicetree integration.

References to Sink ports are given as examples. Access to Sink is specific
to an implementation and would require dedicated kernel modules.

ARM Coresight Mali Source ITM
=============================

Required properties
-------------------

- compatible: Has to be "arm,coresight-mali-source-itm"
- gpu : phandle to a Mali GPU definition
- port:
  - endpoint:
    - remote-endpoint: phandle to a Coresight sink port

Example
-------

mali-source-itm {
  compatible = "arm,coresight-mali-source-itm";
  gpu = <&gpu>;
  port {
    mali_source_itm_out_port0: endpoint {
      remote-endpoint = <&mali_sink_in_port0>;
    };
  };
};

ARM Coresight Mali Source ETM
=============================

Required properties
-------------------

- compatible: Has to be "arm,coresight-mali-source-etm"
- gpu : phandle to a Mali GPU definition
- port:
  - endpoint:
    - remote-endpoint: phandle to a Coresight sink port

Example
-------

mali-source-etm {
  compatible = "arm,coresight-mali-source-etm";
  gpu = <&gpu>;
  port {
    mali_source_etm_out_port0: endpoint {
      remote-endpoint = <&mali_sink_in_port1>;
    };
  };
};

ARM Coresight Mali Source ELA
=============================

Required properties
-------------------

- compatible: Has to be "arm,coresight-mali-source-ela"
- gpu : phandle to a Mali GPU definition
- port:
  - endpoint:
    - remote-endpoint: phandle to a Coresight sink port

Example: Split JCN request/response channel
--------------------------------------------

This examples applies to implementations with a total of 5 signal groups,
where JCN request and response are assigned to independent or shared
channels depending on the GPU model.

mali-source-ela {
  compatible = "arm,coresight-mali-source-ela";
  gpu = <&gpu>;
  port {
    mali_source_ela_out_port0: endpoint {
      remote-endpoint = <&mali_sink_in_port2>;
    };
  };
};

SysFS Configuration
--------------------------------------------

The register values used by CoreSight for ELA can be configured using SysFS
interfaces. This implicitly includes configuring the ELA for independent or
shared JCN request and response channels.
