From patchwork Wed Aug 27 17:17:29 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mathieu Poirier X-Patchwork-Id: 36128 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-yk0-f197.google.com (mail-yk0-f197.google.com [209.85.160.197]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id 55824203C5 for ; Wed, 27 Aug 2014 17:18:23 +0000 (UTC) Received: by mail-yk0-f197.google.com with SMTP id 142sf1503702ykq.4 for ; Wed, 27 Aug 2014 10:18:23 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:delivered-to:from:to:cc:subject :date:message-id:in-reply-to:references:x-original-sender :x-original-authentication-results:precedence:mailing-list:list-id :list-post:list-help:list-archive:list-unsubscribe; bh=LHcTDggNxz99ndpjrZYLf+aySCcZGb5xYnBBb19wTeA=; b=iu8Jhv/6Uy/A8b7MFdSuW9Ujv2x6rdSwweMdpQUYvOfwgrxY6j0Mz0eEbOa+yDS9Lq A25amXm5iGztr2/FK17zqiiWAnuWfViN76iKE3oAES04F2/l12mABwzs6WWMGr6oMI7A JjS/2nva/4MRIN0vRGX2uL9fiuCOIQk7i6qwK35Q15UaGPPTTLNw9fHvib0kVddBOM86 6vYRcxB91J7pX574wFysgsMK1Qls10IzITyWKW3XZoUiA9xlEJr5f8a8EGB0e4ZtIMsE mDjGzSpoDbu8YIk2mxWaV0Us5uO5N4LmxrIzPlneKm/hCVqH3mJfOo4/+FCqBbKvi8BT 3e5w== X-Gm-Message-State: ALoCoQlWES/CcTQTt39OoP0ewdxhvGwR21+0O1020yXxcjgBX69QzNg/8kcnqOMIPS9slcrwBNIm X-Received: by 10.236.143.2 with SMTP id k2mr22472028yhj.18.1409159903183; Wed, 27 Aug 2014 10:18:23 -0700 (PDT) MIME-Version: 1.0 X-BeenThere: patchwork-forward@linaro.org Received: by 10.140.104.130 with SMTP id a2ls192141qgf.90.gmail; Wed, 27 Aug 2014 10:18:23 -0700 (PDT) X-Received: by 10.236.129.3 with SMTP id g3mr36784641yhi.67.1409159903080; Wed, 27 Aug 2014 10:18:23 -0700 (PDT) Received: from mail-yh0-f46.google.com (mail-yh0-f46.google.com [209.85.213.46]) by mx.google.com with ESMTPS id l91si1180769yhq.6.2014.08.27.10.18.23 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Wed, 27 Aug 2014 10:18:23 -0700 (PDT) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.213.46 as permitted sender) client-ip=209.85.213.46; Received: by mail-yh0-f46.google.com with SMTP id a41so548999yho.5 for ; Wed, 27 Aug 2014 10:18:23 -0700 (PDT) X-Received: by 10.52.3.40 with SMTP id 8mr25686508vdz.24.1409159902985; Wed, 27 Aug 2014 10:18:22 -0700 (PDT) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patches@linaro.org Received: by 10.221.45.67 with SMTP id uj3csp113800vcb; Wed, 27 Aug 2014 10:18:22 -0700 (PDT) X-Received: by 10.70.7.1 with SMTP id f1mr35657700pda.22.1409159902010; Wed, 27 Aug 2014 10:18:22 -0700 (PDT) Received: from mail-pd0-f180.google.com (mail-pd0-f180.google.com [209.85.192.180]) by mx.google.com with ESMTPS id 10si1721147pdl.110.2014.08.27.10.18.16 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Wed, 27 Aug 2014 10:18:17 -0700 (PDT) Received-SPF: pass (google.com: domain of mathieu.poirier@linaro.org designates 209.85.192.180 as permitted sender) client-ip=209.85.192.180; Received: by mail-pd0-f180.google.com with SMTP id v10so625071pde.11 for ; Wed, 27 Aug 2014 10:18:16 -0700 (PDT) X-Received: by 10.66.141.197 with SMTP id rq5mr30463372pab.124.1409159896769; Wed, 27 Aug 2014 10:18:16 -0700 (PDT) Received: from t430.cg.shawcable.net (S0106002369de4dac.cg.shawcable.net. [70.73.24.112]) by mx.google.com with ESMTPSA id j15sm1356689pdm.86.2014.08.27.10.18.14 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 27 Aug 2014 10:18:16 -0700 (PDT) From: mathieu.poirier@linaro.org To: thomas.petazzoni@free-electrons.com, will.deacon@arm.com, linux@arm.linux.org.uk, gregkh@linuxfoundation.org, arnd@linaro.org Cc: john.stultz@linaro.org, pratikp@codeaurora.org, varshney@ti.com, Al.Grant@arm.com, jonas.svennebring@avagotech.com, james.king@linaro.org, panchaxari.prasannamurthy@linaro.org, kaixu.xia@linaro.org, marcin.jabrzyk@gmail.com, r.sengupta@samsung.com, robbelibobban@gmail.com, Tony.Armitstead@arm.com, patches@linaro.org, linux-arm-kernel@lists.infradead.org, linux-kernel@vger.kernel.org, mathieu.poirier@linaro.org Subject: [PATCH 08/11 v5] coresight: adding documentation for coresight Date: Wed, 27 Aug 2014 11:17:29 -0600 Message-Id: <1409159852-7249-9-git-send-email-mathieu.poirier@linaro.org> X-Mailer: git-send-email 1.9.1 In-Reply-To: <1409159852-7249-1-git-send-email-mathieu.poirier@linaro.org> References: <1409159852-7249-1-git-send-email-mathieu.poirier@linaro.org> X-Removed-Original-Auth: Dkim didn't pass. X-Original-Sender: mathieu.poirier@linaro.org X-Original-Authentication-Results: mx.google.com; spf=pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.213.46 as permitted sender) smtp.mail=patch+caf_=patchwork-forward=linaro.org@linaro.org Precedence: list Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org List-ID: X-Google-Group-Id: 836684582541 List-Post: , List-Help: , List-Archive: List-Unsubscribe: , From: Mathieu Poirier Documentation for the coresight framework and drivers. Signed-off-by: Mathieu Poirier --- Documentation/trace/coresight.txt | 237 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 237 insertions(+) create mode 100644 Documentation/trace/coresight.txt diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.txt new file mode 100644 index 0000000..ee852a0 --- /dev/null +++ b/Documentation/trace/coresight.txt @@ -0,0 +1,237 @@ + Coresight - HW Assisted Tracing on ARM + ====================================== + + Author: Mathieu Poirier + Date: August 27th 2014 + +Introduction +------------ + +Coresight is an umbrella of technologies allowing for the debugging of ARM +based SoC. It includes solutions for JTAG and HW assisted tracing. This +document is concerned with the latter. + +HW assisted tracing is becoming increasingly useful when dealing with systems +that have many SoCs and other components like GPU and DMA engines. ARM has +developed a HW assisted tracing solution by means of different components, each +being added to a design at systhesis time to cater to specific tracing needs. +Compoments are generally categorised as source, link and sinks and are +(usually) discovered using the AMBA bus. + +"Sources" generate a compressed stream representing the processor instruction +path based on tracing scenarios as configured by users. From there the stream +flows through the coresight system (via ATB bus) using links that are connecting +the emanating source to a sink(s). Sinks serve as endpoints to the coresight +implementation, either storing the compressed stream in a memory buffer or +creating an interface to the outside world where data can be transfered to a +host without fear of filling up the onboard coresight memory buffer. + + +Acronyms and Classification +--------------------------- + +Acronyms: + +PTM: Program Trace Macrocell +ETM: Embedded Trace Macrocell +STM: System trace Macrocell +ETB: Embedded Trace Buffer +ITM: Instrumentation Trace Macrocell +TPIU: Trace Port Interface Unit +TMC-ETR: Trace Memory Controller, configured as Embedded Trace Router +TMC-ETF: Trace Memory Controller, configured as Embedded Trace FIFO +CTI: Cross Trigger Interface + +Classification: + +Source: + ETMv3.x ETMv4, PTMv1.0, PTMv1.1, STM, STM500, ITM +Link: + Funnel, replicator (intelligent or not), TMC-ETR +Sinks: + ETBv1.0, ETB1.1, TPIU, TMC-ETF +Misc: + CTI + + +Device Tree Bindings +---------------------- + +See Documentation/devicetree/bindings/arm/coresight.txt for details. + +As of this writing drivers for ITM, STMs and CTIs are not provided but are +expected to be added as the solution matures. + + +Framework and implementation +---------------------------- + +The coresight framework provides a central point to represent, configure and +manage coresight devices on a platform. Any coresight compliant device can +register with the framework for as long as they use the right APIs: + +struct coresight_device *coresight_register(struct coresight_desc *desc); +void coresight_unregister(struct coresight_device *csdev); + +The registering function is taking a "struct coresight_device *csdev" and +register the device with the core framework. The unregister function takes +a reference to a "strut coresight_device", obtained at registration time. + +If everything goes well during the registration process the new devices will +show up under /sys/kernel/debug/coresight/, as showns here for a TC2 platform: + +root@linaro-developer:~# ls /sys/kernel/debug/coresight/ +00000000.replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm +20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm +root@linaro-developer:~# + +The functions take a "struct coresight_device", which looks like this: + +struct coresight_desc { + enum coresight_dev_type type; + struct coresight_dev_subtype subtype; + const struct coresight_ops *ops; + struct coresight_platform_data *pdata; + struct device *dev; + const struct coresight_ops_entry **debugfs_ops; + struct module *owner; +}; + + +The "coresight_dev_type" identifies what the device is, i.e, source link or +sink while the "coresight_dev_subtype" will characterise that type further. + +The "struct coresight_ops" is mandatory and will tell the framework how to +perform base operations related to the components, each component having +a different set of requirement. For that "struct coresight_ops_sink", +"struct coresight_ops_link" and "struct coresight_ops_source" have been +provided. + +The next field, "struct coresight_platform_data *pdata" is acquired by calling +"of_get_coresight_platform_data()", as part of the driver's _probe routine and +"struct device *dev" gets the device reference embedded in the "amba_device": + +static int etm_probe(struct amba_device *adev, const struct amba_id *id) +{ + ... + ... + drvdata->dev = &adev->dev; + ... +} + +Specific class of device (source, link, or sink) have generic operations +that can be performed on them (see "struct coresight_ops"). The +"**debugfs_ops" is a list of debugfs entries pertaining to operations +specific to that component only. "Implementation defined" customisations are +expected to be accessed and controlled using those entries. + +Last but not least, "struct module *owner" is expected to be set to reflect +the information carried in "THIS_MODULE". + +How to use +---------- + +Before trace collection can start, a coresight sink needs to be identify. +There is no limit on the amount of sinks (nor sources) that can be enabled at +any given moment. As a generic operation, all device pertaining to the sink +class will have an "active" entry in debugfs: + +root@linaro-developer:/sys/kernel/debug/coresight# ls +00000000.replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm +20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm +root@linaro-developer:/sys/kernel/debug/coresight# ls 20010000.etb +active status trigger_cntr +root@linaro-developer:/sys/kernel/debug/coresight# echo 1 > 20010000.etb/active +root@linaro-developer:/sys/kernel/debug/coresight# cat 20010000.etb/active +1 +root@linaro-developer:/sys/kernel/debug/coresight# + +At boot time the current etm3x driver will configure the first address +comparator with "_stext" and "_etext", essentially tracing any instruction +that falls within that range. As such "enabling" a source will immediately +trigger a trace capture: + +root@linaro-developer:/sys/kernel/debug/coresight# echo 1 > 2201c000.ptm/enable +root@linaro-developer:/sys/kernel/debug/coresight# cat 2201c000.ptm/enable +1 +root@linaro-developer:/sys/kernel/debug/coresight# cat 20010000.etb/status +Depth: 0x2000 +Status: 0x1 +RAM read ptr: 0x0 +RAM wrt ptr: 0x19d3 <----- The write pointer is moving +Trigger cnt: 0x0 +Control: 0x1 +Flush status: 0x0 +Flush ctrl: 0x2001 +root@linaro-developer:/sys/kernel/debug/coresight# + +Trace collection is stopped the same way: + +root@linaro-developer:/sys/kernel/debug/coresight# echo 0 > 2201c000.ptm/enable +root@linaro-developer:/sys/kernel/debug/coresight# + +The content of the ETB buffer can be harvested directly from /dev: + +root@linaro-developer:/sys/kernel/debug/coresight# dd if=/dev/20010000.etb \ +of=~/cstrace.bin + +64+0 records in +64+0 records out +32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s +root@linaro-developer:/sys/kernel/debug/coresight# + +The file cstrace.bin can be decompressed using "ptm2human", DS-5 or Trace32. + +Following is a DS-5 output of an experimental loop that increments a variable up +to a certain value. The example is simple and yet provides a glimpse of the +wealth of possibilities that coresight provides. + +Info Tracing enabled +Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr} +Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc +Instruction 0 0x8026B544 E3A03000 false MOV r3,#0 +Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4] +Instruction 0 0x8026B550 E3530004 false CMP r3,#4 +Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 +Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c +Timestamp Timestamp: 17106715833 +Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4] +Instruction 0 0x8026B550 E3530004 false CMP r3,#4 +Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 +Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c +Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4] +Instruction 0 0x8026B550 E3530004 false CMP r3,#4 +Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 +Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c +Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4] +Instruction 0 0x8026B550 E3530004 false CMP r3,#4 +Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 +Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c +Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4] +Instruction 0 0x8026B550 E3530004 false CMP r3,#4 +Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 +Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c +Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4] +Instruction 0 0x8026B550 E3530004 false CMP r3,#4 +Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 +Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c +Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1 +Instruction 0 0x8026B564 E1A0100D false MOV r1,sp +Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0 +Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f +Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4] +Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368 +Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc] +Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0] +Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4 +Info Tracing enabled +Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc +Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc} +Timestamp Timestamp: 17107041535