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, URIBL_BLOCKED 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 4002AC56202 for ; Thu, 26 Nov 2020 17:53:53 +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 A560A207BC for ; Thu, 26 Nov 2020 17:53:52 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=lists.infradead.org header.i=@lists.infradead.org header.b="hTFmPkyv"; dkim=fail reason="signature verification failed" (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="hEBC5fCp" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org A560A207BC 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:In-Reply-To:MIME-Version:References:Message-ID: Subject:To:From:Date:Reply-To:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Owner; bh=OoQZ8G/Fj6PkFOSWzUWVV/fA7qawVakiy23hzam1Esg=; b=hTFmPkyvn8uVH2DotHP2j+0lp 81oikv8f19ldcWf1XZSHPhmD7XTMo3+bPwry05JLX0dVNI3OBxn5XOESZMFnopvc/379GvGL+fPA+ gyzxAlntsagWNHt/f9OPRxD4GNexAAAOMwuzfWPaAUNOxjh3b1NbZmTR/RbikjQfg6FR2AWeVtnv7 0N6/7DEdm15HPzbTPVPSdj+nqScfUeiunp3eaOoQ7csatzr66gh8WqPgk8RDdI/4jflevtw/rbBfd CX2KIhtr1kQlJyOUVG8zBqATH0q9lX9D5aS90Kk2WhLYBINmzw8m4rRD6QxJpZ22ADgrU4v4mcbjb KDhP5u8Vg==; Received: from localhost ([::1] helo=merlin.infradead.org) by merlin.infradead.org with esmtp (Exim 4.92.3 #3 (Red Hat Linux)) id 1kiLRO-0003Jt-LO; Thu, 26 Nov 2020 17:52:22 +0000 Received: from mail-pf1-x443.google.com ([2607:f8b0:4864:20::443]) by merlin.infradead.org with esmtps (Exim 4.92.3 #3 (Red Hat Linux)) id 1kiLRL-0003II-9r for linux-arm-kernel@lists.infradead.org; Thu, 26 Nov 2020 17:52:21 +0000 Received: by mail-pf1-x443.google.com with SMTP id b6so2231383pfp.7 for ; Thu, 26 Nov 2020 09:52:18 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to; bh=Pv2Ekdb0xeo8E8IAfm0fYURhsLlRm9hkVttPqruRYpM=; b=hEBC5fCpaEwOAk4NA7FeOgyaadn1Tv/Q16is7GZl52FhUt0XYH2FVxSeZdA19b5lf/ +eDh+OfCfFgvt+Noic20Lnmtj4LTZ84QfUuAFNMUB0RgyDPJsb7/vq6KaOR5SjXCxllW KR+L+xasW5OPM9XjR5yX42OtAhVrL1RfHXNOy1dPRrZw0tCQKRkzps5qUj3nNrBuwLWY SA0ZPmi4dMHn4Bee+WYrn0z4/1fLLYnIx4mvx4ELkwejcFWhe6SpR+hom8T3TKG/pI6q EVZrwTPbSgT6hbBrPVPyWxZsZC97zN+xofaaYzesK954DEBQqQvTTNLurw0Ty5ha6prA E2Wg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to; bh=Pv2Ekdb0xeo8E8IAfm0fYURhsLlRm9hkVttPqruRYpM=; b=CNsLfSVVK8C6a38k45caql2hjV0IXaZJ0ACD2r1snEXG3IlGAXBwLrMERIOF8S16j5 mROq4l2nknT6bnCsQyUDLrwxoPSHXr2nEx3PiKtBkd3jS7MtwcK5PhvhQpIX3e7sTnlf xOWy+8Q6IAhO7jiJdxug6Vo3wYL3xxBV2rgXxZ43G+RCHts4d1mIklwqazgnikpY8pdW GpqRRC88mBVWyyeBZKErRGwav9cVo3AviUqhO7W86ohcADNZeGw+MAMwrhnOzatEn2nt 6mndhSFGluDD+f1rEzw9aqajyCIdylgiiOth80MT3uF7cKYOyEQrvqUwLwpfxiyOeheD RtrQ== X-Gm-Message-State: AOAM531QCXwrm/ze5PjV5B/VxWA/c1WyizRInQ0fUKgydoXSjUwOS7gF khbmSel7C2FTX4ZPHLwyTW6quptVOaCn1eLN X-Google-Smtp-Source: ABdhPJz2f0TV7whYwP+NEqDj9F4PhKnvipCnsvXie3IIQmk9oCZLgCQ8BcMDuPyr3YbS8dEGU3LZGw== X-Received: by 2002:a17:90a:d3d3:: with SMTP id d19mr5008606pjw.0.1606413136838; Thu, 26 Nov 2020 09:52:16 -0800 (PST) Received: from xps15 (S0106889e681aac74.cg.shawcable.net. [68.147.0.187]) by smtp.gmail.com with ESMTPSA id i4sm4820872pgg.67.2020.11.26.09.52.15 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 26 Nov 2020 09:52:16 -0800 (PST) Date: Thu, 26 Nov 2020 10:52:14 -0700 From: Mathieu Poirier To: Mike Leach Subject: Re: [RFC PATCH v3 9/9] coresight: docs: Add documentation for CoreSight config. Message-ID: <20201126175214.GC757228@xps15> References: <20201030175655.30126-1-mike.leach@linaro.org> <20201030175655.30126-10-mike.leach@linaro.org> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <20201030175655.30126-10-mike.leach@linaro.org> X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20201126_125219_701845_352F617F X-CRM114-Status: GOOD ( 44.66 ) 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: yabinc@google.com, coresight@lists.linaro.org, linux-arm-kernel@lists.infradead.org, suzuki.poulose@arm.com 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 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. > + > +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 > _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel