About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / trace / coresight-cpu-debug.txt




Custom Search

Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

1			Coresight CPU Debug Module
2			==========================
3	
4	   Author:   Leo Yan <leo.yan@linaro.org>
5	   Date:     April 5th, 2017
6	
7	Introduction
8	------------
9	
10	Coresight CPU debug module is defined in ARMv8-a architecture reference manual
11	(ARM DDI 0487A.k) Chapter 'Part H: External debug', the CPU can integrate
12	debug module and it is mainly used for two modes: self-hosted debug and
13	external debug. Usually the external debug mode is well known as the external
14	debugger connects with SoC from JTAG port; on the other hand the program can
15	explore debugging method which rely on self-hosted debug mode, this document
16	is to focus on this part.
17	
18	The debug module provides sample-based profiling extension, which can be used
19	to sample CPU program counter, secure state and exception level, etc; usually
20	every CPU has one dedicated debug module to be connected. Based on self-hosted
21	debug mechanism, Linux kernel can access these related registers from mmio
22	region when the kernel panic happens. The callback notifier for kernel panic
23	will dump related registers for every CPU; finally this is good for assistant
24	analysis for panic.
25	
26	
27	Implementation
28	--------------
29	
30	- During driver registration, it uses EDDEVID and EDDEVID1 - two device ID
31	  registers to decide if sample-based profiling is implemented or not. On some
32	  platforms this hardware feature is fully or partially implemented; and if
33	  this feature is not supported then registration will fail.
34	
35	- At the time this documentation was written, the debug driver mainly relies on
36	  information gathered by the kernel panic callback notifier from three
37	  sampling registers: EDPCSR, EDVIDSR and EDCIDSR: from EDPCSR we can get
38	  program counter; EDVIDSR has information for secure state, exception level,
39	  bit width, etc; EDCIDSR is context ID value which contains the sampled value
40	  of CONTEXTIDR_EL1.
41	
42	- The driver supports a CPU running in either AArch64 or AArch32 mode. The
43	  registers naming convention is a bit different between them, AArch64 uses
44	  'ED' for register prefix (ARM DDI 0487A.k, chapter H9.1) and AArch32 uses
45	  'DBG' as prefix (ARM DDI 0487A.k, chapter G5.1). The driver is unified to
46	  use AArch64 naming convention.
47	
48	- ARMv8-a (ARM DDI 0487A.k) and ARMv7-a (ARM DDI 0406C.b) have different
49	  register bits definition. So the driver consolidates two difference:
50	
51	  If PCSROffset=0b0000, on ARMv8-a the feature of EDPCSR is not implemented;
52	  but ARMv7-a defines "PCSR samples are offset by a value that depends on the
53	  instruction set state". For ARMv7-a, the driver checks furthermore if CPU
54	  runs with ARM or thumb instruction set and calibrate PCSR value, the
55	  detailed description for offset is in ARMv7-a ARM (ARM DDI 0406C.b) chapter
56	  C11.11.34 "DBGPCSR, Program Counter Sampling Register".
57	
58	  If PCSROffset=0b0010, ARMv8-a defines "EDPCSR implemented, and samples have
59	  no offset applied and do not sample the instruction set state in AArch32
60	  state". So on ARMv8 if EDDEVID1.PCSROffset is 0b0010 and the CPU operates
61	  in AArch32 state, EDPCSR is not sampled; when the CPU operates in AArch64
62	  state EDPCSR is sampled and no offset are applied.
63	
64	
65	Clock and power domain
66	----------------------
67	
68	Before accessing debug registers, we should ensure the clock and power domain
69	have been enabled properly. In ARMv8-a ARM (ARM DDI 0487A.k) chapter 'H9.1
70	Debug registers', the debug registers are spread into two domains: the debug
71	domain and the CPU domain.
72	
73	                                +---------------+
74	                                |               |
75	                                |               |
76	                     +----------+--+            |
77	        dbg_clock -->|          |**|            |<-- cpu_clock
78	                     |    Debug |**|   CPU      |
79	 dbg_power_domain -->|          |**|            |<-- cpu_power_domain
80	                     +----------+--+            |
81	                                |               |
82	                                |               |
83	                                +---------------+
84	
85	For debug domain, the user uses DT binding "clocks" and "power-domains" to
86	specify the corresponding clock source and power supply for the debug logic.
87	The driver calls the pm_runtime_{put|get} operations as needed to handle the
88	debug power domain.
89	
90	For CPU domain, the different SoC designs have different power management
91	schemes and finally this heavily impacts external debug module. So we can
92	divide into below cases:
93	
94	- On systems with a sane power controller which can behave correctly with
95	  respect to CPU power domain, the CPU power domain can be controlled by
96	  register EDPRCR in driver. The driver firstly writes bit EDPRCR.COREPURQ
97	  to power up the CPU, and then writes bit EDPRCR.CORENPDRQ for emulation
98	  of CPU power down. As result, this can ensure the CPU power domain is
99	  powered on properly during the period when access debug related registers;
100	
101	- Some designs will power down an entire cluster if all CPUs on the cluster
102	  are powered down - including the parts of the debug registers that should
103	  remain powered in the debug power domain. The bits in EDPRCR are not
104	  respected in these cases, so these designs do not support debug over
105	  power down in the way that the CoreSight / Debug designers anticipated.
106	  This means that even checking EDPRSR has the potential to cause a bus hang
107	  if the target register is unpowered.
108	
109	  In this case, accessing to the debug registers while they are not powered
110	  is a recipe for disaster; so we need preventing CPU low power states at boot
111	  time or when user enable module at the run time. Please see chapter
112	  "How to use the module" for detailed usage info for this.
113	
114	
115	Device Tree Bindings
116	--------------------
117	
118	See Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt for details.
119	
120	
121	How to use the module
122	---------------------
123	
124	If you want to enable debugging functionality at boot time, you can add
125	"coresight_cpu_debug.enable=1" to the kernel command line parameter.
126	
127	The driver also can work as module, so can enable the debugging when insmod
128	module:
129	# insmod coresight_cpu_debug.ko debug=1
130	
131	When boot time or insmod module you have not enabled the debugging, the driver
132	uses the debugfs file system to provide a knob to dynamically enable or disable
133	debugging:
134	
135	To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable:
136	# echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable
137	
138	To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable:
139	# echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable
140	
141	As explained in chapter "Clock and power domain", if you are working on one
142	platform which has idle states to power off debug logic and the power
143	controller cannot work well for the request from EDPRCR, then you should
144	firstly constraint CPU idle states before enable CPU debugging feature; so can
145	ensure the accessing to debug logic.
146	
147	If you want to limit idle states at boot time, you can use "nohlt" or
148	"cpuidle.off=1" in the kernel command line.
149	
150	At the runtime you can disable idle states with below methods:
151	
152	It is possible to disable CPU idle states by way of the PM QoS
153	subsystem, more specifically by using the "/dev/cpu_dma_latency"
154	interface (see Documentation/power/pm_qos_interface.txt for more
155	details).  As specified in the PM QoS documentation the requested
156	parameter will stay in effect until the file descriptor is released.
157	For example:
158	
159	# exec 3<> /dev/cpu_dma_latency; echo 0 >&3
160	...
161	Do some work...
162	...
163	# exec 3<>-
164	
165	The same can also be done from an application program.
166	
167	Disable specific CPU's specific idle state from cpuidle sysfs (see
168	Documentation/cpuidle/sysfs.txt):
169	# echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable
170	
171	
172	Output format
173	-------------
174	
175	Here is an example of the debugging output format:
176	
177	ARM external debug module:
178	coresight-cpu-debug 850000.debug: CPU[0]:
179	coresight-cpu-debug 850000.debug:  EDPRSR:  00000001 (Power:On DLK:Unlock)
180	coresight-cpu-debug 850000.debug:  EDPCSR:  [<ffff00000808e9bc>] handle_IPI+0x174/0x1d8
181	coresight-cpu-debug 850000.debug:  EDCIDSR: 00000000
182	coresight-cpu-debug 850000.debug:  EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
183	coresight-cpu-debug 852000.debug: CPU[1]:
184	coresight-cpu-debug 852000.debug:  EDPRSR:  00000001 (Power:On DLK:Unlock)
185	coresight-cpu-debug 852000.debug:  EDPCSR:  [<ffff0000087fab34>] debug_notifier_call+0x23c/0x358
186	coresight-cpu-debug 852000.debug:  EDCIDSR: 00000000
187	coresight-cpu-debug 852000.debug:  EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.