From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,INCLUDES_PATCH,MAILING_LIST_MULTI,SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 66FB0C4321A for ; Fri, 28 Jun 2019 12:22:43 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 30341214AF for ; Fri, 28 Jun 2019 12:22:43 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1561724563; bh=EzcQQQQFcxyDCnY3jKQbZmmht+sxOrxVfI2EFo0JdLw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=fApXPMnyZZKbgxHaqtM3OLSvB1wQ3kuNFKRB+3FoPBYHOfQHPwpMt+V0PnHHxkWD9 //h+rLCe5uKLSPzlJkK+5HlswgjnygLr9MH5voKQvC2Kuh5d2tkP9wzfiwoqqDOc2J FItbGaJNRgiqy2Gb4QbHCF+ZSp9Os/nl3rkWV25k= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727300AbfF1MWl (ORCPT ); Fri, 28 Jun 2019 08:22:41 -0400 Received: from bombadil.infradead.org ([198.137.202.133]:58856 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726835AbfF1MUr (ORCPT ); Fri, 28 Jun 2019 08:20:47 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=o7CYzJHzCZGLgrtE5snQRdRbRXFwiHaLdDaG2tN6uwM=; b=pNElJl4qAmPj8SOPr/FiDFM74J GLJ1HsGIbIzdUyGCsaNs27pGFlNrFotuAErcGh4PU8r1VcB9njx18KbrQJtsJgFMWfN1kK+Og1nr+ iN6o9Ml6npnEbzrKw0wBdcrlAIDwZCyFNIufHHv5P9KrjjNNPfe5tTtC8SDBITba71Y4Kj6/aIwbI gViaQlrQT/TScSZFcEGNJ5Ye5JiLbN9Q9ZY8RYA6QPfSMz8y3DGoy8RQ7maOGBXQpnym/Lf136j3/ mjunqrGcYhOXtC6I7eQxBADClBU9HxH5CSP8ClKQPniEA2FQjbIU47OEnc8ssAfBlpjgigB5YidyN rOW0RURA==; Received: from [186.213.242.156] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92 #3 (Red Hat Linux)) id 1hgprw-0000AQ-1F; Fri, 28 Jun 2019 12:20:44 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92) (envelope-from ) id 1hgpru-00059r-3y; Fri, 28 Jun 2019 09:20:42 -0300 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Andy Gross , Will Deacon , Mark Rutland , linux-arm-msm@vger.kernel.org, linux-arm-kernel@lists.infradead.org Subject: [PATCH 38/43] docs: perf: convert to ReST Date: Fri, 28 Jun 2019 09:20:34 -0300 Message-Id: X-Mailer: git-send-email 2.21.0 In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Sender: linux-arm-msm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-arm-msm@vger.kernel.org Rename the perf documentation files to ReST, add an index for them and adjust in order to produce a nice html output via the Sphinx build system. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab --- .../perf/{arm-ccn.txt => arm-ccn.rst} | 18 +++++----- .../perf/{arm_dsu_pmu.txt => arm_dsu_pmu.rst} | 5 +-- .../perf/{hisi-pmu.txt => hisi-pmu.rst} | 35 +++++++++++-------- Documentation/perf/index.rst | 16 +++++++++ .../perf/{qcom_l2_pmu.txt => qcom_l2_pmu.rst} | 3 +- .../perf/{qcom_l3_pmu.txt => qcom_l3_pmu.rst} | 3 +- .../{thunderx2-pmu.txt => thunderx2-pmu.rst} | 25 ++++++------- .../perf/{xgene-pmu.txt => xgene-pmu.rst} | 3 +- MAINTAINERS | 4 +-- drivers/perf/qcom_l3_pmu.c | 2 +- 10 files changed, 72 insertions(+), 42 deletions(-) rename Documentation/perf/{arm-ccn.txt => arm-ccn.rst} (86%) rename Documentation/perf/{arm_dsu_pmu.txt => arm_dsu_pmu.rst} (92%) rename Documentation/perf/{hisi-pmu.txt => hisi-pmu.rst} (73%) create mode 100644 Documentation/perf/index.rst rename Documentation/perf/{qcom_l2_pmu.txt => qcom_l2_pmu.rst} (94%) rename Documentation/perf/{qcom_l3_pmu.txt => qcom_l3_pmu.rst} (93%) rename Documentation/perf/{thunderx2-pmu.txt => thunderx2-pmu.rst} (73%) rename Documentation/perf/{xgene-pmu.txt => xgene-pmu.rst} (96%) diff --git a/Documentation/perf/arm-ccn.txt b/Documentation/perf/arm-ccn.rst similarity index 86% rename from Documentation/perf/arm-ccn.txt rename to Documentation/perf/arm-ccn.rst index 15cdb7bc57c3..832b0c64023a 100644 --- a/Documentation/perf/arm-ccn.txt +++ b/Documentation/perf/arm-ccn.rst @@ -1,3 +1,4 @@ +========================== ARM Cache Coherent Network ========================== @@ -29,6 +30,7 @@ Crosspoint watchpoint-based events (special "event" value 0xfe) require "xp" and "vc" as as above plus "port" (device port index), "dir" (transmit/receive direction), comparator values ("cmp_l" and "cmp_h") and "mask", being index of the comparator mask. + Masks are defined separately from the event description (due to limited number of the config values) in the "cmp_mask" directory, with first 8 configurable by user and additional @@ -44,16 +46,16 @@ request the events on this processor (if not, the perf_event->cpu value will be overwritten anyway). In case of this processor being offlined, the events are migrated to another one and the attribute is updated. -Example of perf tool use: +Example of perf tool use:: -/ # perf list | grep ccn - ccn/cycles/ [Kernel PMU event] -<...> - ccn/xp_valid_flit,xp=?,port=?,vc=?,dir=?/ [Kernel PMU event] -<...> + / # perf list | grep ccn + ccn/cycles/ [Kernel PMU event] + <...> + ccn/xp_valid_flit,xp=?,port=?,vc=?,dir=?/ [Kernel PMU event] + <...> -/ # perf stat -a -e ccn/cycles/,ccn/xp_valid_flit,xp=1,port=0,vc=1,dir=1/ \ - sleep 1 + / # perf stat -a -e ccn/cycles/,ccn/xp_valid_flit,xp=1,port=0,vc=1,dir=1/ \ + sleep 1 The driver does not support sampling, therefore "perf record" will not work. Per-task (without "-a") perf sessions are not supported. diff --git a/Documentation/perf/arm_dsu_pmu.txt b/Documentation/perf/arm_dsu_pmu.rst similarity index 92% rename from Documentation/perf/arm_dsu_pmu.txt rename to Documentation/perf/arm_dsu_pmu.rst index d611e15f5add..7fd34db75d13 100644 --- a/Documentation/perf/arm_dsu_pmu.txt +++ b/Documentation/perf/arm_dsu_pmu.rst @@ -1,3 +1,4 @@ +================================== ARM DynamIQ Shared Unit (DSU) PMU ================================== @@ -13,7 +14,7 @@ PMU doesn't support process specific events and cannot be used in sampling mode. The DSU provides a bitmap for a subset of implemented events via hardware registers. There is no way for the driver to determine if the other events are available or not. Hence the driver exposes only those events advertised -by the DSU, in "events" directory under : +by the DSU, in "events" directory under:: /sys/bus/event_sources/devices/arm_dsu_/ @@ -23,6 +24,6 @@ and use the raw event code for the unlisted events. The driver also exposes the CPUs connected to the DSU instance in "associated_cpus". -e.g usage : +e.g usage:: perf stat -a -e arm_dsu_0/cycles/ diff --git a/Documentation/perf/hisi-pmu.txt b/Documentation/perf/hisi-pmu.rst similarity index 73% rename from Documentation/perf/hisi-pmu.txt rename to Documentation/perf/hisi-pmu.rst index 267a028b2741..404a5c3d9d00 100644 --- a/Documentation/perf/hisi-pmu.txt +++ b/Documentation/perf/hisi-pmu.rst @@ -1,5 +1,7 @@ +====================================================== HiSilicon SoC uncore Performance Monitoring Unit (PMU) ====================================================== + The HiSilicon SoC chip includes various independent system device PMUs such as L3 cache (L3C), Hydra Home Agent (HHA) and DDRC. These PMUs are independent and have hardware logic to gather statistics and performance @@ -11,11 +13,13 @@ called Super CPU cluster (SCCL) and is made up of 6 CCLs. Each SCCL has two HHAs (0 - 1) and four DDRCs (0 - 3), respectively. HiSilicon SoC uncore PMU driver ---------------------------------------- +------------------------------- + Each device PMU has separate registers for event counting, control and interrupt, and the PMU driver shall register perf PMU drivers like L3C, HHA and DDRC etc. The available events and configuration options shall -be described in the sysfs, see : +be described in the sysfs, see: + /sys/devices/hisi_sccl{X}_/, or /sys/bus/event_source/devices/hisi_sccl{X}_. The "perf list" command shall list the available events from sysfs. @@ -24,27 +28,30 @@ Each L3C, HHA and DDRC is registered as a separate PMU with perf. The PMU name will appear in event listing as hisi_sccl_module. where "sccl-id" is the identifier of the SCCL and "index-id" is the index of module. + e.g. hisi_sccl3_l3c0/rd_hit_cpipe is READ_HIT_CPIPE event of L3C index #0 in SCCL ID #3. + e.g. hisi_sccl1_hha0/rx_operations is RX_OPERATIONS event of HHA index #0 in SCCL ID #1. The driver also provides a "cpumask" sysfs attribute, which shows the CPU core ID used to count the uncore PMU event. -Example usage of perf: -$# perf list -hisi_sccl3_l3c0/rd_hit_cpipe/ [kernel PMU event] ------------------------------------------- -hisi_sccl3_l3c0/wr_hit_cpipe/ [kernel PMU event] ------------------------------------------- -hisi_sccl1_l3c0/rd_hit_cpipe/ [kernel PMU event] ------------------------------------------- -hisi_sccl1_l3c0/wr_hit_cpipe/ [kernel PMU event] ------------------------------------------- +Example usage of perf:: -$# perf stat -a -e hisi_sccl3_l3c0/rd_hit_cpipe/ sleep 5 -$# perf stat -a -e hisi_sccl3_l3c0/config=0x02/ sleep 5 + $# perf list + hisi_sccl3_l3c0/rd_hit_cpipe/ [kernel PMU event] + ------------------------------------------ + hisi_sccl3_l3c0/wr_hit_cpipe/ [kernel PMU event] + ------------------------------------------ + hisi_sccl1_l3c0/rd_hit_cpipe/ [kernel PMU event] + ------------------------------------------ + hisi_sccl1_l3c0/wr_hit_cpipe/ [kernel PMU event] + ------------------------------------------ + + $# perf stat -a -e hisi_sccl3_l3c0/rd_hit_cpipe/ sleep 5 + $# perf stat -a -e hisi_sccl3_l3c0/config=0x02/ sleep 5 The current driver does not support sampling. So "perf record" is unsupported. Also attach to a task is unsupported as the events are all uncore. diff --git a/Documentation/perf/index.rst b/Documentation/perf/index.rst new file mode 100644 index 000000000000..4bf848e27f26 --- /dev/null +++ b/Documentation/perf/index.rst @@ -0,0 +1,16 @@ +:orphan: + +=========================== +Performance monitor support +=========================== + +.. toctree:: + :maxdepth: 1 + + hisi-pmu + qcom_l2_pmu + qcom_l3_pmu + arm-ccn + xgene-pmu + arm_dsu_pmu + thunderx2-pmu diff --git a/Documentation/perf/qcom_l2_pmu.txt b/Documentation/perf/qcom_l2_pmu.rst similarity index 94% rename from Documentation/perf/qcom_l2_pmu.txt rename to Documentation/perf/qcom_l2_pmu.rst index b25b97659ab9..c130178a4a55 100644 --- a/Documentation/perf/qcom_l2_pmu.txt +++ b/Documentation/perf/qcom_l2_pmu.rst @@ -1,3 +1,4 @@ +===================================================================== Qualcomm Technologies Level-2 Cache Performance Monitoring Unit (PMU) ===================================================================== @@ -28,7 +29,7 @@ The driver provides a "cpumask" sysfs attribute which contains a mask consisting of one CPU per cluster which will be used to handle all the PMU events on that cluster. -Examples for use with perf: +Examples for use with perf:: perf stat -e l2cache_0/config=0x001/,l2cache_0/config=0x042/ -a sleep 1 diff --git a/Documentation/perf/qcom_l3_pmu.txt b/Documentation/perf/qcom_l3_pmu.rst similarity index 93% rename from Documentation/perf/qcom_l3_pmu.txt rename to Documentation/perf/qcom_l3_pmu.rst index 96b3a9444a0d..a3d014a46bfd 100644 --- a/Documentation/perf/qcom_l3_pmu.txt +++ b/Documentation/perf/qcom_l3_pmu.rst @@ -1,3 +1,4 @@ +=========================================================================== Qualcomm Datacenter Technologies L3 Cache Performance Monitoring Unit (PMU) =========================================================================== @@ -17,7 +18,7 @@ The hardware implements 32bit event counters and has a flat 8bit event space exposed via the "event" format attribute. In addition to the 32bit physical counters the driver supports virtual 64bit hardware counters by using hardware counter chaining. This feature is exposed via the "lc" (long counter) format -flag. E.g.: +flag. E.g.:: perf stat -e l3cache_0_0/read-miss,lc/ diff --git a/Documentation/perf/thunderx2-pmu.txt b/Documentation/perf/thunderx2-pmu.rst similarity index 73% rename from Documentation/perf/thunderx2-pmu.txt rename to Documentation/perf/thunderx2-pmu.rst index dffc57143736..08e33675853a 100644 --- a/Documentation/perf/thunderx2-pmu.txt +++ b/Documentation/perf/thunderx2-pmu.rst @@ -1,3 +1,4 @@ +============================================================= Cavium ThunderX2 SoC Performance Monitoring Unit (PMU UNCORE) ============================================================= @@ -24,18 +25,18 @@ and configuration options under sysfs, see The driver does not support sampling, therefore "perf record" will not work. Per-task perf sessions are also not supported. -Examples: +Examples:: -# perf stat -a -e uncore_dmc_0/cnt_cycles/ sleep 1 + # perf stat -a -e uncore_dmc_0/cnt_cycles/ sleep 1 -# perf stat -a -e \ -uncore_dmc_0/cnt_cycles/,\ -uncore_dmc_0/data_transfers/,\ -uncore_dmc_0/read_txns/,\ -uncore_dmc_0/write_txns/ sleep 1 + # perf stat -a -e \ + uncore_dmc_0/cnt_cycles/,\ + uncore_dmc_0/data_transfers/,\ + uncore_dmc_0/read_txns/,\ + uncore_dmc_0/write_txns/ sleep 1 -# perf stat -a -e \ -uncore_l3c_0/read_request/,\ -uncore_l3c_0/read_hit/,\ -uncore_l3c_0/inv_request/,\ -uncore_l3c_0/inv_hit/ sleep 1 + # perf stat -a -e \ + uncore_l3c_0/read_request/,\ + uncore_l3c_0/read_hit/,\ + uncore_l3c_0/inv_request/,\ + uncore_l3c_0/inv_hit/ sleep 1 diff --git a/Documentation/perf/xgene-pmu.txt b/Documentation/perf/xgene-pmu.rst similarity index 96% rename from Documentation/perf/xgene-pmu.txt rename to Documentation/perf/xgene-pmu.rst index d7cff4454e5b..644f8ed89152 100644 --- a/Documentation/perf/xgene-pmu.txt +++ b/Documentation/perf/xgene-pmu.rst @@ -1,3 +1,4 @@ +================================================ APM X-Gene SoC Performance Monitoring Unit (PMU) ================================================ @@ -33,7 +34,7 @@ each PMU, please refer to APM X-Gene User Manual. Each perf driver also provides a "cpumask" sysfs attribute, which contains a single CPU ID of the processor which will be used to handle all the PMU events. -Example for perf tool use: +Example for perf tool use:: / # perf list | grep -e l3c -e iob -e mcb -e mc l3c0/ackq-full/ [Kernel PMU event] diff --git a/MAINTAINERS b/MAINTAINERS index 808f65e06ad8..f5a2121294b3 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1139,7 +1139,7 @@ APPLIED MICRO (APM) X-GENE SOC PMU M: Khuong Dinh S: Supported F: drivers/perf/xgene_pmu.c -F: Documentation/perf/xgene-pmu.txt +F: Documentation/perf/xgene-pmu.rst F: Documentation/devicetree/bindings/perf/apm-xgene-pmu.txt APTINA CAMERA SENSOR PLL @@ -7207,7 +7207,7 @@ M: Shaokun Zhang W: http://www.hisilicon.com S: Supported F: drivers/perf/hisilicon -F: Documentation/perf/hisi-pmu.txt +F: Documentation/perf/hisi-pmu.rst HISILICON ROCE DRIVER M: Lijun Ou diff --git a/drivers/perf/qcom_l3_pmu.c b/drivers/perf/qcom_l3_pmu.c index 15b8c10c2b2b..90f88ce5192b 100644 --- a/drivers/perf/qcom_l3_pmu.c +++ b/drivers/perf/qcom_l3_pmu.c @@ -8,7 +8,7 @@ * the slices. User space needs to aggregate to individual counts to provide * a global picture. * - * See Documentation/perf/qcom_l3_pmu.txt for more details. + * See Documentation/perf/qcom_l3_pmu.rst for more details. * * Copyright (c) 2015-2017, The Linux Foundation. All rights reserved. */ -- 2.21.0