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=-18.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 autolearn=ham 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 8A8BBC433E0 for ; Thu, 24 Dec 2020 19:24:04 +0000 (UTC) Received: from merlin.infradead.org (merlin.infradead.org [205.233.59.134]) (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 3A3B9207CF for ; Thu, 24 Dec 2020 19:24:04 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 3A3B9207CF 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=merlin.20170209; h=Sender:Content-Transfer-Encoding: Content-Type:Cc:List-Subscribe:List-Help:List-Post:List-Archive: List-Unsubscribe:List-Id:To:Subject:Message-ID:Date:From:In-Reply-To: References:MIME-Version:Reply-To:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Owner; bh=7CpyWy11YeA+CPxgur0hezULF41Rlb5RII/QzgYUnG0=; b=TXnhneGyhTka3lEHGXrbfz55Y 7Mdt319bKHBF7QXBCM4t7H77RMp13Sm8KakIzXZ0LTph6IqEpJ6aj0J/SKUU7AKASVwDyR8Pa48yI d0v1zS2wyrc2i0Rf43+1B5+uooe0a6Zas9mDRenZ/zB/ZG562XO33ldC1Lc+ovLd+qpcbeXw7SPuP lyGPTUxAza3vR/RW+FJx1zSxaU0yoIvTwg8clONgg7No0i8aK9lzduS0TTFDSN+g1E2m2jc04BK9X nTf3OiQ5GCeCycFiHs197GM3oVKmLYQnieENKrRVQVw1p0pk9qxKYEKY7sD73JYDYGoyPILm9ZxJT /b+RxZuDQ==; Received: from localhost ([::1] helo=merlin.infradead.org) by merlin.infradead.org with esmtp (Exim 4.92.3 #3 (Red Hat Linux)) id 1ksWCA-0000SN-Cd; Thu, 24 Dec 2020 19:22:42 +0000 Received: from mail-yb1-xb34.google.com ([2607:f8b0:4864:20::b34]) by merlin.infradead.org with esmtps (Exim 4.92.3 #3 (Red Hat Linux)) id 1ksWBf-0000AP-Ie for linux-arm-kernel@lists.infradead.org; Thu, 24 Dec 2020 19:22:13 +0000 Received: by mail-yb1-xb34.google.com with SMTP id y4so2922267ybn.3 for ; Thu, 24 Dec 2020 11:22:11 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=1tTSREa7gHxj9k2RKFGmCIAhaA6GdyriBt6FtrKaU5k=; b=wO3xREhwRhKBvj7pitCGgTVQNulcXekcXK1xUFTZkYKraUeA7F3pzwegWP5NEmgYK4 TGNXc/hZpN/L6EzS6ZoMfIA/C4q3zGAFMID8TmG6qiOmBRqHbcA+ADLHhM7brVi4C+Ff cbPtiNuCJB3hN6z2vZ6U7l2ngtrF8JzA4lxNl8Kn5RuQD3uzUgK/aJzSubTHSmSm86EF L9mbb5twPup4fYAfb1ZV5/Owu7dBqXOwFI5h28NIPrUNsm7tvTLy1BLXLzJRQKNqYI4e b/A8Lr+6u/vcqJRVGrzjSvaTlzK9XXIcd7FkYmchPxksRpTglW1YcKfwQfu4YXOh+1wx wFvA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=1tTSREa7gHxj9k2RKFGmCIAhaA6GdyriBt6FtrKaU5k=; b=I6Bg3ftqSTxDSSPTLD6I3JDjW9FrxKurhNV1CaTrtH9t+EZxt+J/8ifwhAwEeC4agR 6VuMUMjypB66xsfYneljuHopjXehe5K46ZGKiehB070Rf2akY557vSB41BUBsRc8T86Y j3UVWRW23XVOivnI3x2Gn7nJz4kv4+hqFOdfMyrcvDU2yUWzZN6MC582O9rEAzvWBFnk ZDZpz9Be1kLNCoHbVDIEQbCY6undlxKG3nxhsD4XzFSH1yOtncmzZLKGxK8nvDxkM5fC Ml+7kF0bvDPUzhbYte8CmEssUroatBKo8mbIt6ECYra7alz8I19jrdfo6mu5ksmNW5bx W9dg== X-Gm-Message-State: AOAM5312ElqdVrm9yGNv8toLwK/JnCZGz33a1vmLufWTL0CEYbBRsfac fsktXoHa06AbBvInCXFyKLN3weLbxX2jHvVClUPLDQ== X-Google-Smtp-Source: ABdhPJwwSJLrfPh4t+lKZvPkCeArq+cqbLPWRmlzNTyloMlfvnRZ8yNs7OwCfpwUvmGMKQRaRTSTijuEAgM27rgYX7M= X-Received: by 2002:a25:48f:: with SMTP id 137mr17436847ybe.256.1608837729826; Thu, 24 Dec 2020 11:22:09 -0800 (PST) MIME-Version: 1.0 References: <20201030175655.30126-1-mike.leach@linaro.org> <20201030175655.30126-10-mike.leach@linaro.org> <20201126175214.GC757228@xps15> In-Reply-To: <20201126175214.GC757228@xps15> From: Mike Leach Date: Thu, 24 Dec 2020 19:21:59 +0000 Message-ID: Subject: Re: [RFC PATCH v3 9/9] coresight: docs: Add documentation for CoreSight config. To: Mathieu Poirier X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20201224_142211_749827_58362EAD X-CRM114-Status: GOOD ( 49.47 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Yabin Cui , Coresight ML , linux-arm-kernel , "Suzuki K. Poulose" 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 Hi Mathieu, On Thu, 26 Nov 2020 at 17:52, Mathieu Poirier wrote: > > On Fri, Oct 30, 2020 at 05:56:55PM +0000, Mike Leach wrote: > > Adds documentation for the CoreSight System configuration manager. > > > > Signed-off-by: Mike Leach > > --- > > .../trace/coresight/coresight-config.rst | 230 ++++++++++++++++++ > > Documentation/trace/coresight/coresight.rst | 16 ++ > > 2 files changed, 246 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..8afcf18c090c > > --- /dev/null > > +++ b/Documentation/trace/coresight/coresight-config.rst > > @@ -0,0 +1,230 @@ > > +.. 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 complex 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 > > +device is registered with the configuration manager. > > In the above paragraph I would explicitly write "coresight device" when > referring to a device. That way there is no doubt as to what is happening. > > > + > > +The load process involves interpreting the descriptor into a the set of register > > s/into a the set/into a set/ > > > +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. > > If I understand correctly the above paragraph is for the sysfs and configfs > interfaces. From perf enabling feature and devices doesn't apply. > No - this also applies to perf. The principle is that perf will enable a config. But it will only be programmed on to the devices that the perf event is enabled on. Thanks Mike > > + > > +A feature can be enabled either as part of a configuration being enabled on the > > +system, or individually on a device instance using the configfs API. > > + > > + > > +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. > > + > > + > > +Virtual Device > > +-------------- > > + > > +The CoreSight System Configuration manager also includes a virtual CoreSight > > +device. This provides the system with access to kernel objects and device > > +management to own elements such as the sysfs entries used to expose the > > +configurations into the cs_etm event in perf. > > + > > +This device 'system_cfg' appears on a custom bus - 'coresight-config' - > > +rather than the normal 'coresight' bus to avoid complications when the > > +coresight system is searching for real devices on the bus. > > + > > + > > +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 'coresight-syscfg' subsystem will appear:: > > + > > + $ ls /config > > + coresight-syscfg stp-policy > > + > > +This has two sub-directories:: > > + > > + $ cd coresight-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 nr_presets preset_values refs > > + $ cat description > > + Setup ETMs with strobing for autofdo > > + $ cat refs > > + references 1 features:- > > + strobing > > + $ cat nr_presets > > + 2 > > + $ cat preset_values > > + 2 presets, 2 parameters per preset > > + preset[1]: strobing.window = 0x2710 strobing.period = 0x1388 > > + preset[2]: strobing.window = 0x1388 strobing.period = 0x1388 > > + > > +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 0b73acb44efa..0122d9bebf35 100644 > > --- a/Documentation/trace/coresight/coresight.rst > > +++ b/Documentation/trace/coresight/coresight.rst > > @@ -587,6 +587,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 > > @@ -594,3 +608,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 > > -- Mike Leach Principal Engineer, ARM Ltd. Manchester Design Centre. UK _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel