0001 ==========================
0002 Coresight CPU Debug Module
0003 ==========================
0004
0005 :Author: Leo Yan <leo.yan@linaro.org>
0006 :Date: April 5th, 2017
0007
0008 Introduction
0009 ------------
0010
0011 Coresight CPU debug module is defined in ARMv8-a architecture reference manual
0012 (ARM DDI 0487A.k) Chapter 'Part H: External debug', the CPU can integrate
0013 debug module and it is mainly used for two modes: self-hosted debug and
0014 external debug. Usually the external debug mode is well known as the external
0015 debugger connects with SoC from JTAG port; on the other hand the program can
0016 explore debugging method which rely on self-hosted debug mode, this document
0017 is to focus on this part.
0018
0019 The debug module provides sample-based profiling extension, which can be used
0020 to sample CPU program counter, secure state and exception level, etc; usually
0021 every CPU has one dedicated debug module to be connected. Based on self-hosted
0022 debug mechanism, Linux kernel can access these related registers from mmio
0023 region when the kernel panic happens. The callback notifier for kernel panic
0024 will dump related registers for every CPU; finally this is good for assistant
0025 analysis for panic.
0026
0027
0028 Implementation
0029 --------------
0030
0031 - During driver registration, it uses EDDEVID and EDDEVID1 - two device ID
0032 registers to decide if sample-based profiling is implemented or not. On some
0033 platforms this hardware feature is fully or partially implemented; and if
0034 this feature is not supported then registration will fail.
0035
0036 - At the time this documentation was written, the debug driver mainly relies on
0037 information gathered by the kernel panic callback notifier from three
0038 sampling registers: EDPCSR, EDVIDSR and EDCIDSR: from EDPCSR we can get
0039 program counter; EDVIDSR has information for secure state, exception level,
0040 bit width, etc; EDCIDSR is context ID value which contains the sampled value
0041 of CONTEXTIDR_EL1.
0042
0043 - The driver supports a CPU running in either AArch64 or AArch32 mode. The
0044 registers naming convention is a bit different between them, AArch64 uses
0045 'ED' for register prefix (ARM DDI 0487A.k, chapter H9.1) and AArch32 uses
0046 'DBG' as prefix (ARM DDI 0487A.k, chapter G5.1). The driver is unified to
0047 use AArch64 naming convention.
0048
0049 - ARMv8-a (ARM DDI 0487A.k) and ARMv7-a (ARM DDI 0406C.b) have different
0050 register bits definition. So the driver consolidates two difference:
0051
0052 If PCSROffset=0b0000, on ARMv8-a the feature of EDPCSR is not implemented;
0053 but ARMv7-a defines "PCSR samples are offset by a value that depends on the
0054 instruction set state". For ARMv7-a, the driver checks furthermore if CPU
0055 runs with ARM or thumb instruction set and calibrate PCSR value, the
0056 detailed description for offset is in ARMv7-a ARM (ARM DDI 0406C.b) chapter
0057 C11.11.34 "DBGPCSR, Program Counter Sampling Register".
0058
0059 If PCSROffset=0b0010, ARMv8-a defines "EDPCSR implemented, and samples have
0060 no offset applied and do not sample the instruction set state in AArch32
0061 state". So on ARMv8 if EDDEVID1.PCSROffset is 0b0010 and the CPU operates
0062 in AArch32 state, EDPCSR is not sampled; when the CPU operates in AArch64
0063 state EDPCSR is sampled and no offset are applied.
0064
0065
0066 Clock and power domain
0067 ----------------------
0068
0069 Before accessing debug registers, we should ensure the clock and power domain
0070 have been enabled properly. In ARMv8-a ARM (ARM DDI 0487A.k) chapter 'H9.1
0071 Debug registers', the debug registers are spread into two domains: the debug
0072 domain and the CPU domain.
0073 ::
0074
0075 +---------------+
0076 | |
0077 | |
0078 +----------+--+ |
0079 dbg_clock -->| |**| |<-- cpu_clock
0080 | Debug |**| CPU |
0081 dbg_power_domain -->| |**| |<-- cpu_power_domain
0082 +----------+--+ |
0083 | |
0084 | |
0085 +---------------+
0086
0087 For debug domain, the user uses DT binding "clocks" and "power-domains" to
0088 specify the corresponding clock source and power supply for the debug logic.
0089 The driver calls the pm_runtime_{put|get} operations as needed to handle the
0090 debug power domain.
0091
0092 For CPU domain, the different SoC designs have different power management
0093 schemes and finally this heavily impacts external debug module. So we can
0094 divide into below cases:
0095
0096 - On systems with a sane power controller which can behave correctly with
0097 respect to CPU power domain, the CPU power domain can be controlled by
0098 register EDPRCR in driver. The driver firstly writes bit EDPRCR.COREPURQ
0099 to power up the CPU, and then writes bit EDPRCR.CORENPDRQ for emulation
0100 of CPU power down. As result, this can ensure the CPU power domain is
0101 powered on properly during the period when access debug related registers;
0102
0103 - Some designs will power down an entire cluster if all CPUs on the cluster
0104 are powered down - including the parts of the debug registers that should
0105 remain powered in the debug power domain. The bits in EDPRCR are not
0106 respected in these cases, so these designs do not support debug over
0107 power down in the way that the CoreSight / Debug designers anticipated.
0108 This means that even checking EDPRSR has the potential to cause a bus hang
0109 if the target register is unpowered.
0110
0111 In this case, accessing to the debug registers while they are not powered
0112 is a recipe for disaster; so we need preventing CPU low power states at boot
0113 time or when user enable module at the run time. Please see chapter
0114 "How to use the module" for detailed usage info for this.
0115
0116
0117 Device Tree Bindings
0118 --------------------
0119
0120 See Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt for details.
0121
0122
0123 How to use the module
0124 ---------------------
0125
0126 If you want to enable debugging functionality at boot time, you can add
0127 "coresight_cpu_debug.enable=1" to the kernel command line parameter.
0128
0129 The driver also can work as module, so can enable the debugging when insmod
0130 module::
0131
0132 # insmod coresight_cpu_debug.ko debug=1
0133
0134 When boot time or insmod module you have not enabled the debugging, the driver
0135 uses the debugfs file system to provide a knob to dynamically enable or disable
0136 debugging:
0137
0138 To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable::
0139
0140 # echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable
0141
0142 To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable::
0143
0144 # echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable
0145
0146 As explained in chapter "Clock and power domain", if you are working on one
0147 platform which has idle states to power off debug logic and the power
0148 controller cannot work well for the request from EDPRCR, then you should
0149 firstly constraint CPU idle states before enable CPU debugging feature; so can
0150 ensure the accessing to debug logic.
0151
0152 If you want to limit idle states at boot time, you can use "nohlt" or
0153 "cpuidle.off=1" in the kernel command line.
0154
0155 At the runtime you can disable idle states with below methods:
0156
0157 It is possible to disable CPU idle states by way of the PM QoS
0158 subsystem, more specifically by using the "/dev/cpu_dma_latency"
0159 interface (see Documentation/power/pm_qos_interface.rst for more
0160 details). As specified in the PM QoS documentation the requested
0161 parameter will stay in effect until the file descriptor is released.
0162 For example::
0163
0164 # exec 3<> /dev/cpu_dma_latency; echo 0 >&3
0165 ...
0166 Do some work...
0167 ...
0168 # exec 3<>-
0169
0170 The same can also be done from an application program.
0171
0172 Disable specific CPU's specific idle state from cpuidle sysfs (see
0173 Documentation/admin-guide/pm/cpuidle.rst)::
0174
0175 # echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable
0176
0177 Output format
0178 -------------
0179
0180 Here is an example of the debugging output format::
0181
0182 ARM external debug module:
0183 coresight-cpu-debug 850000.debug: CPU[0]:
0184 coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
0185 coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
0186 coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
0187 coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
0188 coresight-cpu-debug 852000.debug: CPU[1]:
0189 coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
0190 coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
0191 coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
0192 coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
