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=-23.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,MENTIONS_GIT_HOSTING,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 7078BC433B4 for ; Wed, 14 Apr 2021 19:20:24 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 507FB610FC for ; Wed, 14 Apr 2021 19:20:24 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1353354AbhDNTUn (ORCPT ); Wed, 14 Apr 2021 15:20:43 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41434 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1353249AbhDNTTl (ORCPT ); Wed, 14 Apr 2021 15:19:41 -0400 Received: from mail-wm1-x334.google.com (mail-wm1-x334.google.com [IPv6:2a00:1450:4864:20::334]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 72871C061344 for ; Wed, 14 Apr 2021 12:19:15 -0700 (PDT) Received: by mail-wm1-x334.google.com with SMTP id o9-20020a1c41090000b029012c8dac9d47so3887626wma.1 for ; Wed, 14 Apr 2021 12:19:15 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=kWBYmHFzVaAtr0q3DL3loxqYVHyccUJehxRYe/jfvbg=; b=sr4y3Z6Pw8TKurOZzxC55ZM+iTr/0/GOOCxvdvPqLBKHtQoqDlIxtv5mgv72k/1xHb nLXen8CmSxbqkY5rFhUuj+CkjNzVxtb32AwXRWU0MHIX4Chyay5Ja8i5KSkDfwYhJvyy kvTLWWjov5nrUO9nLRHRLP65w4LtdCQarSx+1v1RVEbzq9+k8wrs2Bmu6/hbfiXh2G3P nkjmZbxk3fcusHl+/tmsX7X15pwiRCA2LJqzdYgxZx6LZrrPy1bCTUlCeClMI9P6pVh8 rn5nvDOK3YlYAvViwF7TzO38vzxyOHRtb601R3wu5fI2GNjDfRqz/ITwVpDg4lIMqWNj cGxw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=kWBYmHFzVaAtr0q3DL3loxqYVHyccUJehxRYe/jfvbg=; b=iBerSa8OKQXcXqRtfHT5kCE6g04xXOS+VJbUSGtCmPFiw1y1JLDSu8FXGAnWqeYAZy sNqhz+b7Kc7kDs/57q8YRAN/dBg+opfRsL4C1/1zxFs5iCd1IZlLRVuDPsVr/8i1zQcX P2gNgsj+0VK/DZyfqVQ7qHVvLsOC+m5xklu8Eokiu80nXI2mxgAd+xlc6HLHZnSidgGR XOIT346V+f0Jbe2rQ2ifj0pVfbCQP4iI2A4kzKqYZLi6jwvI2DHLj1kJWYTElQcwEhWD 72HWel18M+zAA9HDPHvCMWe7Zx3SwTz9Hg/wRzakK+9IH9YUC05cgW/yEb5RcYBvbcJs iSww== X-Gm-Message-State: AOAM531c1c/8RqZsHBh4igK3VMgX0e4Yb250K0N1z3NGhacj5JbvRqAc h6bCRjWoCAouutHrikDVrx013g== X-Google-Smtp-Source: ABdhPJwBecVNRTPgiuCqfmZYOcEX+yitgpPPOVZbFO1CUs+HPxXpHMUAr0IUNVZI+1JVn8cwqFw23w== X-Received: by 2002:a1c:e3c3:: with SMTP id a186mr4311506wmh.81.1618427954154; Wed, 14 Apr 2021 12:19:14 -0700 (PDT) Received: from linaro.org ([2a00:23c5:6809:2201:546d:7d59:1703:bf96]) by smtp.gmail.com with ESMTPSA id a3sm327073wru.40.2021.04.14.12.19.13 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 14 Apr 2021 12:19:13 -0700 (PDT) From: Mike Leach To: linux-arm-kernel@lists.infradead.org, coresight@lists.linaro.org, mathieu.poirier@linaro.org, linux-doc@vger.kernel.org, suzuki.poulose@arm.com Cc: yabinc@google.com, corbet@lwn.net, leo.yan@linaro.org, alexander.shishkin@linux.intel.com, tingwei@codeaurora.org, gregkh@linuxfoundation.org, linux-kernel@vger.kernel.org, Mike Leach Subject: [PATCH v7 10/10] Documentation: coresight: Add documentation for CoreSight config Date: Wed, 14 Apr 2021 20:19:03 +0100 Message-Id: <20210414191903.18349-11-mike.leach@linaro.org> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20210414191903.18349-1-mike.leach@linaro.org> References: <20210414191903.18349-1-mike.leach@linaro.org> Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Adds documentation for the CoreSight System configuration manager. Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Signed-off-by: Mike Leach Reviewed-by: Mathieu Poirier --- .../trace/coresight/coresight-config.rst | 244 ++++++++++++++++++ Documentation/trace/coresight/coresight.rst | 16 ++ 2 files changed, 260 insertions(+) create mode 100644 Documentation/trace/coresight/coresight-config.rst diff --git a/Documentation/trace/coresight/coresight-config.rst b/Documentation/trace/coresight/coresight-config.rst new file mode 100644 index 000000000000..a4e3ef295240 --- /dev/null +++ b/Documentation/trace/coresight/coresight-config.rst @@ -0,0 +1,244 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================================== +CoreSight System Configuration Manager +====================================== + + :Author: Mike Leach + :Date: October 2020 + +Introduction +============ + +The CoreSight System Configuration manager is an API that allows the +programming of the CoreSight system with pre-defined configurations that +can then be easily enabled from sysfs or perf. + +Many CoreSight components can be programmed in complex ways - especially ETMs. +In addition, components can interact across the CoreSight system, often via +the cross trigger components such as CTI and CTM. These system settings can +be defined and enabled as named configurations. + + +Basic Concepts +============== + +This section introduces the basic concepts of a CoreSight system configuration. + + +Features +-------- + +A feature is a named set of programming for a CoreSight device. The programming +is device dependent, and can be defined in terms of absolute register values, +resource usage and parameter values. + +The feature is defined using a descriptor. This descriptor is used to load onto +a matching device, either when the feature is loaded into the system, or when the +CoreSight device is registered with the configuration manager. + +The load process involves interpreting the descriptor into a set of register +accesses in the driver - the resource usage and parameter descriptions +translated into appropriate register accesses. This interpretation makes it easy +and efficient for the feature to be programmed onto the device when required. + +The feature will not be active on the device until the feature is enabled, and +the device itself is enabled. When the device is enabled then enabled features +will be programmed into the device hardware. + +A feature is enabled as part of a configuration being enabled on the system. + + +Parameter Value +~~~~~~~~~~~~~~~ + +A parameter value is a named value that may be set by the user prior to the +feature being enabled that can adjust the behaviour of the operation programmed +by the feature. + +For example, this could be a count value in a programmed operation that repeats +at a given rate. When the feature is enabled then the current value of the +parameter is used in programming the device. + +The feature descriptor defines a default value for a parameter, which is used +if the user does not supply a new value. + +Users can update parameter values using the configfs API for the CoreSight +system - which is described below. + +The current value of the parameter is loaded into the device when the feature +is enabled on that device. + + +Configurations +-------------- + +A configuration defines a set of features that are to be used in a trace +session where the configuration is selected. For any trace session only one +configuration may be selected. + +The features defined may be on any type of device that is registered +to support system configuration. A configuration may select features to be +enabled on a class of devices - i.e. any ETMv4, or specific devices, e.g. a +specific CTI on the system. + +As with the feature, a descriptor is used to define the configuration. +This will define the features that must be enabled as part of the configuration +as well as any preset values that can be used to override default parameter +values. + + +Preset Values +~~~~~~~~~~~~~ + +Preset values are easily selectable sets of parameter values for the features +that the configuration uses. The number of values in a single preset set, equals +the sum of parameter values in the features used by the configuration. + +e.g. a configuration consists of 3 features, one has 2 parameters, one has +a single parameter, and another has no parameters. A single preset set will +therefore have 3 values. + +Presets are optionally defined by the configuration, up to 15 can be defined. +If no preset is selected, then the parameter values defined in the feature +are used as normal. + + +Operation +~~~~~~~~~ + +The following steps take place in the operation of a configuration. + +1) In this example, the configuration is 'autofdo', which has an + associated feature 'strobing' that works on ETMv4 CoreSight Devices. + +2) The configuration is enabled. For example 'perf' may select the + configuration as part of its command line:: + + perf record -e cs_etm/autofdo/ myapp + + which will enable the 'autofdo' configuration. + +3) perf starts tracing on the system. As each ETMv4 that perf uses for + trace is enabled, the configuration manager will check if the ETMv4 + has a feature that relates to the currently active configuration. + In this case 'strobing' is enabled & programmed into the ETMv4. + +4) When the ETMv4 is disabled, any registers marked as needing to be + saved will be read back. + +5) At the end of the perf session, the configuration will be disabled. + + +Viewing Configurations and Features +=================================== + +The set of configurations and features that are currently loaded into the +system can be viewed using the configfs API. + +Mount configfs as normal and the 'cs-syscfg' subsystem will appear:: + + $ ls /config + cs-syscfg stp-policy + +This has two sub-directories:: + + $ cd cs-syscfg/ + $ ls + configurations features + +The system has the configuration 'autofdo' built in. It may be examined as +follows:: + + $ cd configurations/ + $ ls + autofdo + $ cd autofdo/ + $ ls + description preset1 preset3 preset5 preset7 preset9 + feature_refs preset2 preset4 preset6 preset8 + $ cat description + Setup ETMs with strobing for autofdo + $ cat feature_refs + strobing + +Each preset declared has a preset subdirectory declared. The values for +the preset can be examined:: + + $ cat preset1/values + strobing.window = 0x1388 strobing.period = 0x2 + $ cat preset2/values + strobing.window = 0x1388 strobing.period = 0x4 + +The features referenced by the configuration can be examined in the features +directory:: + + $ cd ../../features/strobing/ + $ ls + description matches nr_params params + $ cat description + Generate periodic trace capture windows. + parameter 'window': a number of CPU cycles (W) + parameter 'period': trace enabled for W cycles every period x W cycles + $ cat matches + SRC_ETMV4 + $ cat nr_params + 2 + +Move to the params directory to examine and adjust parameters:: + + cd params + $ ls + period window + $ cd period + $ ls + value + $ cat value + 0x2710 + # echo 15000 > value + # cat value + 0x3a98 + +Parameters adjusted in this way are reflected in all device instances that have +loaded the feature. + + +Using Configurations in perf +============================ + +The configurations loaded into the CoreSight configuration management are +also declared in the perf 'cs_etm' event infrastructure so that they can +be selected when running trace under perf:: + + $ ls /sys/devices/cs_etm + configurations format perf_event_mux_interval_ms sinks type + events nr_addr_filters power + +Key directories here are 'configurations' - which lists the loaded +configurations, and 'events' - a generic perf directory which allows +selection on the perf command line.:: + + $ ls configurations/ + autofdo + $ cat configurations/autofdo + 0xa7c3dddd + +As with the sinks entries, this provides a hash of the configuration name. +The entry in the 'events' directory uses perfs built in syntax generator +to substitute the syntax for the name when evaluating the command:: + + $ ls events/ + autofdo + $ cat events/autofdo + configid=0xa7c3dddd + +The 'autofdo' configuration may be selected on the perf command line:: + + $ perf record -e cs_etm/autofdo/u --per-thread + +A preset to override the current parameter values can also be selected:: + + $ perf record -e cs_etm/autofdo,preset=1/u --per-thread + +When configurations are selected in this way, then the trace sink used is +automatically selected. diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst index 169749efd8d1..7ec656c9f0dc 100644 --- a/Documentation/trace/coresight/coresight.rst +++ b/Documentation/trace/coresight/coresight.rst @@ -619,6 +619,20 @@ A separate documentation file is provided to explain the use of these devices. (:doc:`coresight-ect`) [#fourth]_. +CoreSight System Configuration +------------------------------ + +CoreSight components can be complex devices with many programming options. +Furthermore, components can be programmed to interact with each other across the +complete system. + +A CoreSight System Configuration manager is provided to allow these complex programming +configurations to be selected and used easily from perf and sysfs. + +See the separate document for further information. +(:doc:`coresight-config`) [#fifth]_. + + .. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm .. [#second] Documentation/trace/stm.rst @@ -626,3 +640,5 @@ A separate documentation file is provided to explain the use of these devices. .. [#third] https://github.com/Linaro/perf-opencsd .. [#fourth] Documentation/trace/coresight/coresight-ect.rst + +.. [#fifth] Documentation/trace/coresight/coresight-config.rst -- 2.17.1 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=-21.8 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,MENTIONS_GIT_HOSTING,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 96FF4C433B4 for ; Wed, 14 Apr 2021 19:25:36 +0000 (UTC) Received: from desiato.infradead.org (desiato.infradead.org [90.155.92.199]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 1B62661168 for ; Wed, 14 Apr 2021 19:25:36 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 1B62661168 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=desiato.20200630; h=Sender:Content-Transfer-Encoding :Content-Type:MIME-Version:List-Subscribe:List-Help:List-Post:List-Archive: List-Unsubscribe:List-Id:References:In-Reply-To:Message-Id:Date:Subject:Cc:To :From:Reply-To:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Owner; bh=ZrjEWvNkmM3NwmhK1mkhs6N37ltFXwobRMQ62AR5qL8=; b=d8Qi6U1eNYAtILSuBtOleNLyaa FK9u9PeUsXxq5n0Tr6bEympm4hzTWVcAE3gMGEls2JucMgs+PnJaVMhsSzVc1vyQqeq61TQUeg7w+ mckFp/jKduN4QwH+kWc+NVxY0LTGgndHfwvd0loMrKqOwK9NuxXC9QMbseEGuXqJiiLVEOOw5VwEg AZ7VUsDtQUHwR9m6tWrlozLvLtg34t3D4DafyPunr2lORnL8tvWfobeavF1SOPHHEd7cpM1H5/PMv KNwYFy6JDnyDkb/tOQ2k7KJ7+vwzTAjlapeHFz+/tKMUPAJXxyyABeigm+fAXnOaQA3X7P8Z3Mc+I bczxuZMw==; Received: from localhost ([::1] helo=desiato.infradead.org) by desiato.infradead.org with esmtp (Exim 4.94 #2 (Red Hat Linux)) id 1lWl6m-00DXys-Je; Wed, 14 Apr 2021 19:23:29 +0000 Received: from bombadil.infradead.org ([2607:7c80:54:e::133]) by desiato.infradead.org with esmtps (Exim 4.94 #2 (Red Hat Linux)) id 1lWl2l-00DX4n-5A for linux-arm-kernel@desiato.infradead.org; Wed, 14 Apr 2021 19:19:19 +0000 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=References:In-Reply-To:Message-Id: Date:Subject:Cc:To:From:Sender:Reply-To:MIME-Version:Content-Type: Content-Transfer-Encoding:Content-ID:Content-Description; bh=kWBYmHFzVaAtr0q3DL3loxqYVHyccUJehxRYe/jfvbg=; b=X/dUqj6Xa9phRCWR9D4MlJfRNt XRmFF+FM5vN7HYrnm7G9/C6I5xo3r2d/WRfFPRu0be3GomC1TVF0HBzr8DJWrfkA/4S5kFabsc5lc NA0Uv4XN6j/dw0CWTUOa87i/FjEOkDK6AnDPL1P5mI5kUUP/kXu38xg3Vw29/ltlOONJ9kzJNITqD lePMFgaiBA9YefLxGBDtZPsRGIf6EEWEe8K3JRxGPRv22Kvq5E1tNyPIOVazNeX3zc12ZrqgFvFbu jBoWm+m4wvtNmG6f6+cXistyKiJK7LI3coT2PgTO3fwCg6oCbad8b/tkMGxjdGpx2TI3H8b6aC6+U 5/m7ncdQ==; Received: from mail-wm1-x330.google.com ([2a00:1450:4864:20::330]) by bombadil.infradead.org with esmtps (Exim 4.94 #2 (Red Hat Linux)) id 1lWl2h-0082sh-Cn for linux-arm-kernel@lists.infradead.org; Wed, 14 Apr 2021 19:19:17 +0000 Received: by mail-wm1-x330.google.com with SMTP id z24-20020a1cf4180000b029012463a9027fso11099243wma.5 for ; Wed, 14 Apr 2021 12:19:15 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=kWBYmHFzVaAtr0q3DL3loxqYVHyccUJehxRYe/jfvbg=; b=sr4y3Z6Pw8TKurOZzxC55ZM+iTr/0/GOOCxvdvPqLBKHtQoqDlIxtv5mgv72k/1xHb nLXen8CmSxbqkY5rFhUuj+CkjNzVxtb32AwXRWU0MHIX4Chyay5Ja8i5KSkDfwYhJvyy kvTLWWjov5nrUO9nLRHRLP65w4LtdCQarSx+1v1RVEbzq9+k8wrs2Bmu6/hbfiXh2G3P nkjmZbxk3fcusHl+/tmsX7X15pwiRCA2LJqzdYgxZx6LZrrPy1bCTUlCeClMI9P6pVh8 rn5nvDOK3YlYAvViwF7TzO38vzxyOHRtb601R3wu5fI2GNjDfRqz/ITwVpDg4lIMqWNj cGxw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=kWBYmHFzVaAtr0q3DL3loxqYVHyccUJehxRYe/jfvbg=; b=IlA01sZRveQMjMMeksQ77LoOIoyrzu/xmFJnXqgc+m1Z1Q1CLa4CoHV1uCRwP/1jPn IMOr20iJOn+bkExgSptO0xt6lG4EgXbw5/e1q9m0WqAYBbCGa8J+CI80mgoS57RgLqCK 7XpmHhZw/a6S6vAjf77OizAGnnuGjD06E62WaR5SjLnFqMzsUweQgYVsykRBavk0Bv4y qlgXDmz85Zb0kBWyp7dQauAcSEGDCos2hC7tCSiIrRYThiDupmY4PAE9t1+C6TfhnNFj 4P9EP7vLuICJBdLl1rq6lZMq8v1yTAR6VfqyS2Jy3IKaE6Yu3kvZpH1S1DQRd/uDNthT sHhA== X-Gm-Message-State: AOAM530e8cCkkMPhgbj+bqDz0YqCmYa7BgK1nvvtHxO28Tql3pFBBo6v fqSwd8nhMz8HGtVd2jWmEVliKLMkS7xrbw== X-Google-Smtp-Source: ABdhPJwBecVNRTPgiuCqfmZYOcEX+yitgpPPOVZbFO1CUs+HPxXpHMUAr0IUNVZI+1JVn8cwqFw23w== X-Received: by 2002:a1c:e3c3:: with SMTP id a186mr4311506wmh.81.1618427954154; Wed, 14 Apr 2021 12:19:14 -0700 (PDT) Received: from linaro.org ([2a00:23c5:6809:2201:546d:7d59:1703:bf96]) by smtp.gmail.com with ESMTPSA id a3sm327073wru.40.2021.04.14.12.19.13 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 14 Apr 2021 12:19:13 -0700 (PDT) From: Mike Leach To: linux-arm-kernel@lists.infradead.org, coresight@lists.linaro.org, mathieu.poirier@linaro.org, linux-doc@vger.kernel.org, suzuki.poulose@arm.com Cc: yabinc@google.com, corbet@lwn.net, leo.yan@linaro.org, alexander.shishkin@linux.intel.com, tingwei@codeaurora.org, gregkh@linuxfoundation.org, linux-kernel@vger.kernel.org, Mike Leach Subject: [PATCH v7 10/10] Documentation: coresight: Add documentation for CoreSight config Date: Wed, 14 Apr 2021 20:19:03 +0100 Message-Id: <20210414191903.18349-11-mike.leach@linaro.org> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20210414191903.18349-1-mike.leach@linaro.org> References: <20210414191903.18349-1-mike.leach@linaro.org> X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20210414_121915_483901_F19BC7C3 X-CRM114-Status: GOOD ( 35.57 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org Adds documentation for the CoreSight System configuration manager. Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Signed-off-by: Mike Leach Reviewed-by: Mathieu Poirier --- .../trace/coresight/coresight-config.rst | 244 ++++++++++++++++++ Documentation/trace/coresight/coresight.rst | 16 ++ 2 files changed, 260 insertions(+) create mode 100644 Documentation/trace/coresight/coresight-config.rst diff --git a/Documentation/trace/coresight/coresight-config.rst b/Documentation/trace/coresight/coresight-config.rst new file mode 100644 index 000000000000..a4e3ef295240 --- /dev/null +++ b/Documentation/trace/coresight/coresight-config.rst @@ -0,0 +1,244 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================================== +CoreSight System Configuration Manager +====================================== + + :Author: Mike Leach + :Date: October 2020 + +Introduction +============ + +The CoreSight System Configuration manager is an API that allows the +programming of the CoreSight system with pre-defined configurations that +can then be easily enabled from sysfs or perf. + +Many CoreSight components can be programmed in complex ways - especially ETMs. +In addition, components can interact across the CoreSight system, often via +the cross trigger components such as CTI and CTM. These system settings can +be defined and enabled as named configurations. + + +Basic Concepts +============== + +This section introduces the basic concepts of a CoreSight system configuration. + + +Features +-------- + +A feature is a named set of programming for a CoreSight device. The programming +is device dependent, and can be defined in terms of absolute register values, +resource usage and parameter values. + +The feature is defined using a descriptor. This descriptor is used to load onto +a matching device, either when the feature is loaded into the system, or when the +CoreSight device is registered with the configuration manager. + +The load process involves interpreting the descriptor into a set of register +accesses in the driver - the resource usage and parameter descriptions +translated into appropriate register accesses. This interpretation makes it easy +and efficient for the feature to be programmed onto the device when required. + +The feature will not be active on the device until the feature is enabled, and +the device itself is enabled. When the device is enabled then enabled features +will be programmed into the device hardware. + +A feature is enabled as part of a configuration being enabled on the system. + + +Parameter Value +~~~~~~~~~~~~~~~ + +A parameter value is a named value that may be set by the user prior to the +feature being enabled that can adjust the behaviour of the operation programmed +by the feature. + +For example, this could be a count value in a programmed operation that repeats +at a given rate. When the feature is enabled then the current value of the +parameter is used in programming the device. + +The feature descriptor defines a default value for a parameter, which is used +if the user does not supply a new value. + +Users can update parameter values using the configfs API for the CoreSight +system - which is described below. + +The current value of the parameter is loaded into the device when the feature +is enabled on that device. + + +Configurations +-------------- + +A configuration defines a set of features that are to be used in a trace +session where the configuration is selected. For any trace session only one +configuration may be selected. + +The features defined may be on any type of device that is registered +to support system configuration. A configuration may select features to be +enabled on a class of devices - i.e. any ETMv4, or specific devices, e.g. a +specific CTI on the system. + +As with the feature, a descriptor is used to define the configuration. +This will define the features that must be enabled as part of the configuration +as well as any preset values that can be used to override default parameter +values. + + +Preset Values +~~~~~~~~~~~~~ + +Preset values are easily selectable sets of parameter values for the features +that the configuration uses. The number of values in a single preset set, equals +the sum of parameter values in the features used by the configuration. + +e.g. a configuration consists of 3 features, one has 2 parameters, one has +a single parameter, and another has no parameters. A single preset set will +therefore have 3 values. + +Presets are optionally defined by the configuration, up to 15 can be defined. +If no preset is selected, then the parameter values defined in the feature +are used as normal. + + +Operation +~~~~~~~~~ + +The following steps take place in the operation of a configuration. + +1) In this example, the configuration is 'autofdo', which has an + associated feature 'strobing' that works on ETMv4 CoreSight Devices. + +2) The configuration is enabled. For example 'perf' may select the + configuration as part of its command line:: + + perf record -e cs_etm/autofdo/ myapp + + which will enable the 'autofdo' configuration. + +3) perf starts tracing on the system. As each ETMv4 that perf uses for + trace is enabled, the configuration manager will check if the ETMv4 + has a feature that relates to the currently active configuration. + In this case 'strobing' is enabled & programmed into the ETMv4. + +4) When the ETMv4 is disabled, any registers marked as needing to be + saved will be read back. + +5) At the end of the perf session, the configuration will be disabled. + + +Viewing Configurations and Features +=================================== + +The set of configurations and features that are currently loaded into the +system can be viewed using the configfs API. + +Mount configfs as normal and the 'cs-syscfg' subsystem will appear:: + + $ ls /config + cs-syscfg stp-policy + +This has two sub-directories:: + + $ cd cs-syscfg/ + $ ls + configurations features + +The system has the configuration 'autofdo' built in. It may be examined as +follows:: + + $ cd configurations/ + $ ls + autofdo + $ cd autofdo/ + $ ls + description preset1 preset3 preset5 preset7 preset9 + feature_refs preset2 preset4 preset6 preset8 + $ cat description + Setup ETMs with strobing for autofdo + $ cat feature_refs + strobing + +Each preset declared has a preset subdirectory declared. The values for +the preset can be examined:: + + $ cat preset1/values + strobing.window = 0x1388 strobing.period = 0x2 + $ cat preset2/values + strobing.window = 0x1388 strobing.period = 0x4 + +The features referenced by the configuration can be examined in the features +directory:: + + $ cd ../../features/strobing/ + $ ls + description matches nr_params params + $ cat description + Generate periodic trace capture windows. + parameter 'window': a number of CPU cycles (W) + parameter 'period': trace enabled for W cycles every period x W cycles + $ cat matches + SRC_ETMV4 + $ cat nr_params + 2 + +Move to the params directory to examine and adjust parameters:: + + cd params + $ ls + period window + $ cd period + $ ls + value + $ cat value + 0x2710 + # echo 15000 > value + # cat value + 0x3a98 + +Parameters adjusted in this way are reflected in all device instances that have +loaded the feature. + + +Using Configurations in perf +============================ + +The configurations loaded into the CoreSight configuration management are +also declared in the perf 'cs_etm' event infrastructure so that they can +be selected when running trace under perf:: + + $ ls /sys/devices/cs_etm + configurations format perf_event_mux_interval_ms sinks type + events nr_addr_filters power + +Key directories here are 'configurations' - which lists the loaded +configurations, and 'events' - a generic perf directory which allows +selection on the perf command line.:: + + $ ls configurations/ + autofdo + $ cat configurations/autofdo + 0xa7c3dddd + +As with the sinks entries, this provides a hash of the configuration name. +The entry in the 'events' directory uses perfs built in syntax generator +to substitute the syntax for the name when evaluating the command:: + + $ ls events/ + autofdo + $ cat events/autofdo + configid=0xa7c3dddd + +The 'autofdo' configuration may be selected on the perf command line:: + + $ perf record -e cs_etm/autofdo/u --per-thread + +A preset to override the current parameter values can also be selected:: + + $ perf record -e cs_etm/autofdo,preset=1/u --per-thread + +When configurations are selected in this way, then the trace sink used is +automatically selected. diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst index 169749efd8d1..7ec656c9f0dc 100644 --- a/Documentation/trace/coresight/coresight.rst +++ b/Documentation/trace/coresight/coresight.rst @@ -619,6 +619,20 @@ A separate documentation file is provided to explain the use of these devices. (:doc:`coresight-ect`) [#fourth]_. +CoreSight System Configuration +------------------------------ + +CoreSight components can be complex devices with many programming options. +Furthermore, components can be programmed to interact with each other across the +complete system. + +A CoreSight System Configuration manager is provided to allow these complex programming +configurations to be selected and used easily from perf and sysfs. + +See the separate document for further information. +(:doc:`coresight-config`) [#fifth]_. + + .. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm .. [#second] Documentation/trace/stm.rst @@ -626,3 +640,5 @@ A separate documentation file is provided to explain the use of these devices. .. [#third] https://github.com/Linaro/perf-opencsd .. [#fourth] Documentation/trace/coresight/coresight-ect.rst + +.. [#fifth] Documentation/trace/coresight/coresight-config.rst -- 2.17.1 _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel