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

Source file repositories/reference/linux-study-clean/Documentation/trace/coresight/coresight-cpu-debug.rst

File Facts

System
Linux kernel
Corpus path
Documentation/trace/coresight/coresight-cpu-debug.rst
Extension
.rst
Size
8601 bytes
Lines
194
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

==========================
Coresight CPU Debug Module
==========================

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

Introduction
------------

Coresight CPU debug module is defined in ARMv8-a architecture reference manual
(ARM DDI 0487A.k) Chapter 'Part H: External debug', the CPU can integrate
debug module and it is mainly used for two modes: self-hosted debug and
external debug. Usually the external debug mode is well known as the external
debugger connects with SoC from JTAG port; on the other hand the program can
explore debugging method which rely on self-hosted debug mode, this document
is to focus on this part.

The debug module provides sample-based profiling extension, which can be used
to sample CPU program counter, secure state and exception level, etc; usually
every CPU has one dedicated debug module to be connected. Based on self-hosted
debug mechanism, Linux kernel can access these related registers from mmio
region when the kernel panic happens. The callback notifier for kernel panic
will dump related registers for every CPU; finally this is good for assistant
analysis for panic.


Implementation
--------------

- During driver registration, it uses EDDEVID and EDDEVID1 - two device ID
  registers to decide if sample-based profiling is implemented or not. On some
  platforms this hardware feature is fully or partially implemented; and if
  this feature is not supported then registration will fail.

- At the time this documentation was written, the debug driver mainly relies on
  information gathered by the kernel panic callback notifier from three
  sampling registers: EDPCSR, EDVIDSR and EDCIDSR: from EDPCSR we can get
  program counter; EDVIDSR has information for secure state, exception level,
  bit width, etc; EDCIDSR is context ID value which contains the sampled value
  of CONTEXTIDR_EL1.

- The driver supports a CPU running in either AArch64 or AArch32 mode. The
  registers naming convention is a bit different between them, AArch64 uses
  'ED' for register prefix (ARM DDI 0487A.k, chapter H9.1) and AArch32 uses
  'DBG' as prefix (ARM DDI 0487A.k, chapter G5.1). The driver is unified to
  use AArch64 naming convention.

- ARMv8-a (ARM DDI 0487A.k) and ARMv7-a (ARM DDI 0406C.b) have different
  register bits definition. So the driver consolidates two difference:

  If PCSROffset=0b0000, on ARMv8-a the feature of EDPCSR is not implemented;
  but ARMv7-a defines "PCSR samples are offset by a value that depends on the
  instruction set state". For ARMv7-a, the driver checks furthermore if CPU
  runs with ARM or thumb instruction set and calibrate PCSR value, the
  detailed description for offset is in ARMv7-a ARM (ARM DDI 0406C.b) chapter
  C11.11.34 "DBGPCSR, Program Counter Sampling Register".

  If PCSROffset=0b0010, ARMv8-a defines "EDPCSR implemented, and samples have
  no offset applied and do not sample the instruction set state in AArch32
  state". So on ARMv8 if EDDEVID1.PCSROffset is 0b0010 and the CPU operates
  in AArch32 state, EDPCSR is not sampled; when the CPU operates in AArch64
  state EDPCSR is sampled and no offset are applied.


Clock and power domain
----------------------

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

Annotation

Implementation Notes