Documentation: coresight: convert txt to rst (fe13225f) · Commits · EulixOS / Software / Kernel

Documentation/trace/coresight-cpu-debug.txt→Documentation/trace/coresight-cpu-debug.rst

+36 −31

Original line number	Original line	Diff line number	Diff line
			==========================
	Coresight CPU Debug Module		Coresight CPU Debug Module
	==========================		==========================

	Author: Leo Yan <leo.yan@linaro.org>		:Author: Leo Yan <leo.yan@linaro.org>
	Date: April 5th, 2017		:Date: April 5th, 2017

	Introduction		Introduction
	------------		------------
	@@ -69,6 +70,7 @@ Before accessing debug registers, we should ensure the clock and power domain
	have been enabled properly. In ARMv8-a ARM (ARM DDI 0487A.k) chapter 'H9.1		have been enabled properly. In ARMv8-a ARM (ARM DDI 0487A.k) chapter 'H9.1
	Debug registers', the debug registers are spread into two domains: the debug		Debug registers', the debug registers are spread into two domains: the debug
	domain and the CPU domain.		domain and the CPU domain.
			::

	+---------------+		+---------------+
	\| \|		\| \|
	@@ -125,17 +127,20 @@ If you want to enable debugging functionality at boot time, you can add
	"coresight_cpu_debug.enable=1" to the kernel command line parameter.		"coresight_cpu_debug.enable=1" to the kernel command line parameter.

	The driver also can work as module, so can enable the debugging when insmod		The driver also can work as module, so can enable the debugging when insmod
	module:		module::

	# insmod coresight_cpu_debug.ko debug=1		# insmod coresight_cpu_debug.ko debug=1

	When boot time or insmod module you have not enabled the debugging, the driver		When boot time or insmod module you have not enabled the debugging, the driver
	uses the debugfs file system to provide a knob to dynamically enable or disable		uses the debugfs file system to provide a knob to dynamically enable or disable
	debugging:		debugging:

	To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable:		To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable::

	# echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable		# echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable

	To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable:		To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable::

	# echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable		# echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable

	As explained in chapter "Clock and power domain", if you are working on one		As explained in chapter "Clock and power domain", if you are working on one
	@@ -154,7 +159,7 @@ subsystem, more specifically by using the "/dev/cpu_dma_latency"
	interface (see Documentation/power/pm_qos_interface.rst for more		interface (see Documentation/power/pm_qos_interface.rst for more
	details). As specified in the PM QoS documentation the requested		details). As specified in the PM QoS documentation the requested
	parameter will stay in effect until the file descriptor is released.		parameter will stay in effect until the file descriptor is released.
	For example:		For example::

	# exec 3<> /dev/cpu_dma_latency; echo 0 >&3		# exec 3<> /dev/cpu_dma_latency; echo 0 >&3
	...		...
	@@ -165,14 +170,14 @@ Do some work...
	The same can also be done from an application program.		The same can also be done from an application program.

	Disable specific CPU's specific idle state from cpuidle sysfs (see		Disable specific CPU's specific idle state from cpuidle sysfs (see
	Documentation/admin-guide/pm/cpuidle.rst):		Documentation/admin-guide/pm/cpuidle.rst)::
	# echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable

			# echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable

	Output format		Output format
	-------------		-------------

	Here is an example of the debugging output format:		Here is an example of the debugging output format::

	ARM external debug module:		ARM external debug module:
	coresight-cpu-debug 850000.debug: CPU[0]:		coresight-cpu-debug 850000.debug: CPU[0]:

Documentation/trace/coresight.txt→Documentation/trace/coresight.rst

+194 −178

Original line number	Original line	Diff line number	Diff line
			======================================
	Coresight - HW Assisted Tracing on ARM		Coresight - HW Assisted Tracing on ARM
	======================================		======================================

	Author: Mathieu Poirier <mathieu.poirier@linaro.org>		:Author: Mathieu Poirier <mathieu.poirier@linaro.org>
	Date: September 11th, 2014		:Date: September 11th, 2014

	Introduction		Introduction
	------------		------------
	@@ -26,7 +27,7 @@ implementation, either storing the compressed stream in a memory buffer or
	creating an interface to the outside world where data can be transferred to a		creating an interface to the outside world where data can be transferred to a
	host without fear of filling up the onboard coresight memory buffer.		host without fear of filling up the onboard coresight memory buffer.

	At typical coresight system would look like this:		At typical coresight system would look like this::

	*****************************************************************		*****************************************************************
	************************** AMBA AXI **************************===\|\|		************************** AMBA AXI **************************===\|\|
	@@ -95,15 +96,24 @@ Acronyms and Classification

	Acronyms:		Acronyms:

	PTM: Program Trace Macrocell		PTM:
	ETM: Embedded Trace Macrocell		Program Trace Macrocell
	STM: System trace Macrocell		ETM:
	ETB: Embedded Trace Buffer		Embedded Trace Macrocell
	ITM: Instrumentation Trace Macrocell		STM:
	TPIU: Trace Port Interface Unit		System trace Macrocell
	TMC-ETR: Trace Memory Controller, configured as Embedded Trace Router		ETB:
	TMC-ETF: Trace Memory Controller, configured as Embedded Trace FIFO		Embedded Trace Buffer
	CTI: Cross Trigger Interface		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:		Classification:

	@@ -118,7 +128,7 @@ Misc:


	Device Tree Bindings		Device Tree Bindings
	----------------------		--------------------

	See Documentation/devicetree/bindings/arm/coresight.txt for details.		See Documentation/devicetree/bindings/arm/coresight.txt for details.

	@@ -133,22 +143,22 @@ The coresight framework provides a central point to represent, configure and
	manage coresight devices on a platform. Any coresight compliant device can		manage coresight devices on a platform. Any coresight compliant device can
	register with the framework for as long as they use the right APIs:		register with the framework for as long as they use the right APIs:

	struct coresight_device coresight_register(struct coresight_desc desc);		.. c:function:: struct coresight_device coresight_register(struct coresight_desc desc);
	void coresight_unregister(struct coresight_device *csdev);		.. c:function:: void coresight_unregister(struct coresight_device *csdev);

	The registering function is taking a "struct coresight_device *csdev" and		The registering function is taking a ``struct coresight_desc *desc`` and
	register the device with the core framework. The unregister function takes		register the device with the core framework. The unregister function takes
	a reference to a "struct coresight_device", obtained at registration time.		a reference to a ``struct coresight_device *csdev`` obtained at registration time.

	If everything goes well during the registration process the new devices will		If everything goes well during the registration process the new devices will
	show up under /sys/bus/coresight/devices, as showns here for a TC2 platform:		show up under /sys/bus/coresight/devices, as showns here for a TC2 platform::

	root:~# ls /sys/bus/coresight/devices/		root:~# ls /sys/bus/coresight/devices/
	replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm		replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
	20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm		20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
	root:~#		root:~#

	The functions take a "struct coresight_device", which looks like this:		The functions take a ``struct coresight_device``, which looks like this::

	struct coresight_desc {		struct coresight_desc {
	enum coresight_dev_type type;		enum coresight_dev_type type;
	@@ -163,15 +173,15 @@ struct coresight_desc {
	The "coresight_dev_type" identifies what the device is, i.e, source link or		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.		sink while the "coresight_dev_subtype" will characterise that type further.

	The "struct coresight_ops" is mandatory and will tell the framework how to		The ``struct coresight_ops`` is mandatory and will tell the framework how to
	perform base operations related to the components, each component having		perform base operations related to the components, each component having
	a different set of requirement. For that "struct coresight_ops_sink",		a different set of requirement. For that ``struct coresight_ops_sink``,
	"struct coresight_ops_link" and "struct coresight_ops_source" have been		``struct coresight_ops_link`` and ``struct coresight_ops_source`` have been
	provided.		provided.

	The next field, "struct coresight_platform_data *pdata" is acquired by calling		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		``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":		``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)		static int etm_probe(struct amba_device adev, const struct amba_id id)
	{		{
	@@ -182,19 +192,19 @@ static int etm_probe(struct amba_device adev, const struct amba_id id)
	}		}

	Specific class of device (source, link, or sink) have generic operations		Specific class of device (source, link, or sink) have generic operations
	that can be performed on them (see "struct coresight_ops"). The		that can be performed on them (see ``struct coresight_ops``). The ``**groups``
	"**groups" is a list of sysfs entries pertaining to operations		is a list of sysfs entries pertaining to operations
	specific to that component only. "Implementation defined" customisations are		specific to that component only. "Implementation defined" customisations are
	expected to be accessed and controlled using those entries.		expected to be accessed and controlled using those entries.


	Device Naming scheme		Device Naming scheme
	------------------------		--------------------

	The devices that appear on the "coresight" bus were named the same as their		The devices that appear on the "coresight" bus were named the same as their
	parent devices, i.e, the real devices that appears on AMBA bus or the platform bus.		parent devices, i.e, the real devices that appears on AMBA bus or the platform bus.
	Thus the names were based on the Linux Open Firmware layer naming convention,		Thus the names were based on the Linux Open Firmware layer naming convention,
	which follows the base physical address of the device followed by the device		which follows the base physical address of the device followed by the device
	type. e.g:		type. e.g::

	root:~# ls /sys/bus/coresight/devices/		root:~# ls /sys/bus/coresight/devices/
	20010000.etf 20040000.funnel 20100000.stm 22040000.etm		20010000.etf 20040000.funnel 20100000.stm 22040000.etm
	@@ -205,7 +215,7 @@ root:~# ls /sys/bus/coresight/devices/
	However, with the introduction of ACPI support, the names of the real		However, with the introduction of ACPI support, the names of the real
	devices are a bit cryptic and non-obvious. Thus, a new naming scheme was		devices are a bit cryptic and non-obvious. Thus, a new naming scheme was
	introduced to use more generic names based on the type of the device. The		introduced to use more generic names based on the type of the device. The
	following rules apply:		following rules apply::

	1) Devices that are bound to CPUs, are named based on the CPU logical		1) Devices that are bound to CPUs, are named based on the CPU logical
	number.		number.
	@@ -220,7 +230,7 @@ following rules apply:

	e.g, tmc_etf0, tmc_etr0, funnel0, funnel1		e.g, tmc_etf0, tmc_etr0, funnel0, funnel1

	Thus, with the new scheme the devices could appear as :		Thus, with the new scheme the devices could appear as ::

	root:~# ls /sys/bus/coresight/devices/		root:~# ls /sys/bus/coresight/devices/
	etm0 etm1 etm2 etm3 etm4 etm5 funnel0		etm0 etm1 etm2 etm3 etm4 etm5 funnel0
	@@ -234,9 +244,12 @@ the system under specified locations.
	How to use the tracer modules		How to use the tracer modules
	-----------------------------		-----------------------------

	There are two ways to use the Coresight framework: 1) using the perf cmd line		There are two ways to use the Coresight framework:
	tools and 2) interacting directly with the Coresight devices using the sysFS
	interface. Preference is given to the former as using the sysFS interface		1. using the perf cmd line tools.
			2. interacting directly with the Coresight devices using the sysFS interface.

			Preference is given to the former as using the sysFS interface
	requires a deep understanding of the Coresight HW. The following sections		requires a deep understanding of the Coresight HW. The following sections
	provide details on using both methods.		provide details on using both methods.

	@@ -245,7 +258,7 @@ provide details on using both methods.
	Before trace collection can start, a coresight sink needs to be identified.		Before trace collection can start, a coresight sink needs to be identified.
	There is no limit on the amount of sinks (nor sources) that can be enabled at		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		any given moment. As a generic operation, all device pertaining to the sink
	class will have an "active" entry in sysfs:		class will have an "active" entry in sysfs::

	root:/sys/bus/coresight/devices# ls		root:/sys/bus/coresight/devices# ls
	replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm		replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
	@@ -260,7 +273,7 @@ root:/sys/bus/coresight/devices#
	At boot time the current etm3x driver will configure the first address		At boot time the current etm3x driver will configure the first address
	comparator with "_stext" and "_etext", essentially tracing any instruction		comparator with "_stext" and "_etext", essentially tracing any instruction
	that falls within that range. As such "enabling" a source will immediately		that falls within that range. As such "enabling" a source will immediately
	trigger a trace capture:		trigger a trace capture::

	root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source		root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
	root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source		root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
	@@ -276,16 +289,15 @@ Flush status: 0x0
	Flush ctrl: 0x2001		Flush ctrl: 0x2001
	root:/sys/bus/coresight/devices#		root:/sys/bus/coresight/devices#

	Trace collection is stopped the same way:		Trace collection is stopped the same way::

	root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source		root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source
	root:/sys/bus/coresight/devices#		root:/sys/bus/coresight/devices#

	The content of the ETB buffer can be harvested directly from /dev:		The content of the ETB buffer can be harvested directly from /dev::

	root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \		root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \
	of=~/cstrace.bin		of=~/cstrace.bin

	64+0 records in		64+0 records in
	64+0 records out		64+0 records out
	32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s		32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s
	@@ -296,6 +308,7 @@ 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		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		to a certain value. The example is simple and yet provides a glimpse of the
	wealth of possibilities that coresight provides.		wealth of possibilities that coresight provides.
			::

	Info Tracing enabled		Info Tracing enabled
	Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr}		Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr}
	@@ -370,19 +383,18 @@ A Coresight PMU works the same way as any other PMU, i.e the name of the PMU is
	listed along with configuration options within forward slashes '/'. Since a		listed along with configuration options within forward slashes '/'. Since a
	Coresight system will typically have more than one sink, the name of the sink to		Coresight system will typically have more than one sink, the name of the sink to
	work with needs to be specified as an event option.		work with needs to be specified as an event option.
	On newer kernels the available sinks are listed in sysFS under:		On newer kernels the available sinks are listed in sysFS under
	($SYSFS)/bus/event_source/devices/cs_etm/sinks/		($SYSFS)/bus/event_source/devices/cs_etm/sinks/::

	root@localhost:/sys/bus/event_source/devices/cs_etm/sinks# ls		root@localhost:/sys/bus/event_source/devices/cs_etm/sinks# ls
	tmc_etf0 tmc_etr0 tpiu0		tmc_etf0 tmc_etr0 tpiu0

	On older kernels, this may need to be found from the list of coresight devices,		On older kernels, this may need to be found from the list of coresight devices,
	available under ($SYSFS)/bus/coresight/devices/:		available under ($SYSFS)/bus/coresight/devices/::

	root:~# ls /sys/bus/coresight/devices/		root:~# ls /sys/bus/coresight/devices/
	etm0 etm1 etm2 etm3 etm4 etm5 funnel0		etm0 etm1 etm2 etm3 etm4 etm5 funnel0
	funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0		funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0

	root@linaro-nano:~# perf record -e cs_etm/@tmc_etr0/u --per-thread program		root@linaro-nano:~# perf record -e cs_etm/@tmc_etr0/u --per-thread program

	As mentioned above in section "Device Naming scheme", the names of the devices could		As mentioned above in section "Device Naming scheme", the names of the devices could
	@@ -395,14 +407,14 @@ to use for the trace session.

	More information on the above and other example on how to use Coresight with		More information on the above and other example on how to use Coresight with
	the perf tools can be found in the "HOWTO.md" file of the openCSD gitHub		the perf tools can be found in the "HOWTO.md" file of the openCSD gitHub
	repository [3].		repository [#third]_.

	2.1) AutoFDO analysis using the perf tools:		2.1) AutoFDO analysis using the perf tools:

	perf can be used to record and analyze trace of programs.		perf can be used to record and analyze trace of programs.

	Execution can be recorded using 'perf record' with the cs_etm event,		Execution can be recorded using 'perf record' with the cs_etm event,
	specifying the name of the sink to record to, e.g:		specifying the name of the sink to record to, e.g::

	perf record -e cs_etm/@tmc_etr0/u --per-thread		perf record -e cs_etm/@tmc_etr0/u --per-thread

	@@ -421,12 +433,14 @@ Generating coverage files for Feedback Directed Optimization: AutoFDO

	'perf inject' accepts the --itrace option in which case tracing data is		'perf inject' accepts the --itrace option in which case tracing data is
	removed and replaced with the synthesized events. e.g.		removed and replaced with the synthesized events. e.g.
			::

	perf inject --itrace --strip -i perf.data -o perf.data.new		perf inject --itrace --strip -i perf.data -o perf.data.new

	Below is an example of using ARM ETM for autoFDO. It requires autofdo		Below is an example of using ARM ETM for autoFDO. It requires autofdo
	(https://github.com/google/autofdo) and gcc version 5. The bubble		(https://github.com/google/autofdo) and gcc version 5. The bubble
	sort example is from the AutoFDO tutorial (https://gcc.gnu.org/wiki/AutoFDO/Tutorial).		sort example is from the AutoFDO tutorial (https://gcc.gnu.org/wiki/AutoFDO/Tutorial).
			::

	$ gcc-5 -O3 sort.c -o sort		$ gcc-5 -O3 sort.c -o sort
	$ taskset -c 2 ./sort		$ taskset -c 2 ./sort
	@@ -455,7 +469,7 @@ difference is that clients are driving the trace capture rather
	than the program flow through the code.		than the program flow through the code.

	As with any other CoreSight component, specifics about the STM tracer can be		As with any other CoreSight component, specifics about the STM tracer can be
	found in sysfs with more information on each entry being found in [1]:		found in sysfs with more information on each entry being found in [#first]_::

	root@genericarmv8:~# ls /sys/bus/coresight/devices/stm0		root@genericarmv8:~# ls /sys/bus/coresight/devices/stm0
	enable_source hwevent_select port_enable subsystem uevent		enable_source hwevent_select port_enable subsystem uevent
	@@ -463,20 +477,22 @@ hwevent_enable mgmt port_select traceid
	root@genericarmv8:~#		root@genericarmv8:~#

	Like any other source a sink needs to be identified and the STM enabled before		Like any other source a sink needs to be identified and the STM enabled before
	being used:		being used::

	root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/tmc_etf0/enable_sink		root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/tmc_etf0/enable_sink
	root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/stm0/enable_source		root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/stm0/enable_source

	From there user space applications can request and use channels using the devfs		From there user space applications can request and use channels using the devfs
	interface provided for that purpose by the generic STM API:		interface provided for that purpose by the generic STM API::

	root@genericarmv8:~# ls -l /dev/stm0		root@genericarmv8:~# ls -l /dev/stm0
	crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0		crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0
	root@genericarmv8:~#		root@genericarmv8:~#

	Details on how to use the generic STM API can be found here [2].		Details on how to use the generic STM API can be found here [#second]_.

			.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm

			.. [#second] Documentation/trace/stm.rst

	[1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm		.. [#third] https://github.com/Linaro/perf-opencsd
	[2]. Documentation/trace/stm.rst
	[3]. https://github.com/Linaro/perf-opencsd

Documentation/trace/index.rst

+2 −0

Original line number	Original line	Diff line number	Diff line
	@@ -23,3 +23,5 @@ Linux Tracing Technologies
	intel_th		intel_th
	stm		stm
	sys-t		sys-t
			coresight
			coresight-cpu-debug

MAINTAINERS

+2 −2

Original line number	Original line	Diff line number	Diff line
	@@ -1582,8 +1582,8 @@ R: Suzuki K Poulose <suzuki.poulose@arm.com>
	L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)		L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
	S: Maintained		S: Maintained
	F: drivers/hwtracing/coresight/*		F: drivers/hwtracing/coresight/*
	F: Documentation/trace/coresight.txt		F: Documentation/trace/coresight.rst
	F: Documentation/trace/coresight-cpu-debug.txt		F: Documentation/trace/coresight-cpu-debug.rst
	F: Documentation/devicetree/bindings/arm/coresight.txt		F: Documentation/devicetree/bindings/arm/coresight.txt
	F: Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt		F: Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt
	F: Documentation/ABI/testing/sysfs-bus-coresight-devices-*		F: Documentation/ABI/testing/sysfs-bus-coresight-devices-*