GDB has a valuable feature consisting of process record and replay. In fact, GDB can record a log of process execution and save it. This record can be loaded later on, and used for debugging. This is called offline debugging. it offers the advantage that you can catch the issue once, and replay it as much as needed to find the root cause and fix it. this is extremely valuable for non reproduce-able or hard to reproduce bugs. you can replay the record either forwards or backwards, which is very convivial for observing and analyzing the software.

To realize this functionality, GDB is in fact executing the software, one assembly instruction after another and recording relevant registers and memory locations. This is a slow operation that can drastically change the timing of process execution, and thus change the conditions that raise the bug. To overcome this limitation, GDB can use available SoC IPs to accelerate the operation. As per today, GDB has support for "Intel Processor Trace" and " Branch Trace Store" IP on Intel processors. 

ARM based SoCs have also IPs that can be used to assist process record, namely CoreSight trace sources (ETM, PTM ..), trace links ( Funnels ...) and trace sinks (ETB, ETR, TPIU...). They are now supported in Linux kernel, through corresponding drivers and the extension of perf. A library for decoding ETM traces (OpenCSD) is also available. The way is now paved to bring acceleration of process record for ARM based SoC to GDB.

I am re-sending RFC and making it available as basis for discussions for implementing this feature. it is also attached as text file

B.R.

Zied Guermazi

                        Non intrusive execution recording
                         for GDB using ARM CoreSight  

Status of this Memo

   This memo provides information for Linaro coresight and toolchain communities.
   Distribution of this memo is unlimited.

Abstract

   A method of realizing execution recording in GDB in a non-intrusive way. This method is based on the use of CoreSight hardware tracing, available on ARM Cortex devices.

Table of Contents

   1 Introduction    
   2 State of the art   
   3 Use cases    
   3.1 Self hosted debug monitor   
   3.2 Remote debug monitor   
   3.3 External debugger    
   4 Implementation needs    
   4.1 Self hosted debug monitor    
   4.2 Remote Debug monitor   
   4.3 External debugger    
   5 Remote protocol execution sequence   
   6 Remote protocol extensions   
   7 Solutions and alternatives .  
   7.1 Scope definition    
   7.2 CoreSight infrastructure exposure to the user    
   7.3 Parameters needed for parsing traces    

1.  Introduction

   CoreSight technology offers a toolset for tracing the execution of a program on a CPU, as well as routing the traces to an external  trace port analyzer or storing it in a dedicated internal memory. Those traces do not affects system performance, and can be used as a record for program execution.
   GDB offers reverse debugging by recording program execution and storing it. GDB offers either full record or program flow (branch) record. Records can be replayed later-on for forwards or backwards debugging.
   This request for comments is about realizing GDB record and replay functionality using CoreSight technology. it presents typical  use cases and discuss different alternatives for realizing above mentioned feature.
   
2.  State of the art

   GDB currently supports two execution recording variants:
   - full record: where registers as well as memory are recorded for each instruction. in this case GDB collects the registers as well as involved memory area after each instruction. currently this has no support for hardware accelerators
   - branch record: where only program flow is recorded. In this case GDB collects program execution flow. currently branch record is implemented either with or without hardware acceleration by using Intel branch trace store "bts" and Intel processor trace "pt" hardware accelerator on supported cpus.

3.  Use cases

   Programs running on ARM processors can be be debugged in many configurations. three of them are selected in this RFC as base for discussion :
   
   3.1.  Self hosted debug monitor
   
   Those are systems where the debugger program runs on the same cpu as the debugged program and monitors it. user interacts with the debugging session on the target host itself.
   Linux GDB is an example of such systems. in such a system following setup is considered
      - Target: a process running on an ARM cortex A
      - Debugger: gnu GDB via ptrace API (arm-linux-gnueabihf-gdb)

                  +-----------------------------------+                    
                  |             Target                |                    
                  |                    +------------+ |                    
                  | +------+           | Coresight  | |                    
                  | |      |           | components:| |                    
                  | | GDB  |<--------->|            | |                    
                  | |      |     ^     | DWT, ETM,  | |                    
                  | +------+     |     | ITM, TPIU  | |                    
                  |    ^         |     | TMC, ETB   | |                    
                  |    |         |     +------------+ |                    
                  +----|---------|--------------------+                    
                       |         |                                          
                       |         |                                          
                   arm-linux-    |                                          
                   gnueabihf-    |                                          
                   gdb           |                                          
                           debug: ptrace                                    
                   trace: perf/CoreSight drivers                            

   3.2. Remote debug monitor

   Those are systems where the debugger program runs on the same cpu as the debugged program and monitors it. user interacts with the debugging session remotely from a PC
   Linux GDB is an example of such systems. in such a system following setup is considered
      - Target: a process running on an ARM cortex A
      - GDB server: gnu gdbserver (arm-linux-gnueabihf-gdbserver)
      - GDB client: gnu GDB (arm-linux-gnueabihf-gdb)
      - UI: eclipse with needed plugins, MI interface is used.

+--------------------------+     +---------------------------------------+  
|                Host      |     |               Target                  |  
|                          |     |                        +------------+ |  
| +-----+     +------+     |     |     +------+           | Coresight  | |  
| |     |     | GDB  |     |     |     | GDB  |           | components:| |  
| | UI  |<--->|      |<--->|<--->|<--->|      |<--------->|            | |  
| |     |  ^  |Client|  ^  |  ^  |     |Server|     ^     | DWT, ETM,  | |  
| +-----+  |  +------+  |  |  |  |     +------+     |     | ITM, TPIU  | |  
|    ^     |     ^      |  |  |  |        ^         |     | TMC, ETB   | |  
|    |     |     |      |  |  |  |        |         |     +------------+ |  
+----|-----|-----|------|--+  |  +--------|---------|--------------------+  
     |     |     |      |     |           |         |                      
     |     |     |      |     |           |         |                      
  Eclipse  | arm-linux- |     |       arm-linux-    |                      
           | gnueabihf- |   TCP/IP    gnueabihf-    |                      
           |    gdb     |    UART     gdbserver     |                      
         GDB MI      GDB remote               debug: ptrace                
                      protocol          trace: perf/CoreSight drivers      

   3.3.  External debugger

   Those are systems where an external debugger is used. It accesses the target using JTAG or SWD. Target is usually a bare metal embedded systems or systems with an rtos.
   as an example, following setup is considered:
      - Target: firmware running on ARM cortex M.
      - Debugger: external debug and trace device.
      - GDB server: OpenOcd.
      - GDB Client: arm-none-eabi-gdb.
      - UI: eclipse with needed plugins, MI interface is used.

+--------------------------------------+     +-------+     +-------------+  
|                Host                  |     | dbggr |     |    Target   |  
|                                      |     |       |     |             |  
| +-----+     +------+     +------+    |     |       |     | Coresight   |  
| |     |     | GDB  |     | GDB  |    |     | Debug |     | components: |  
| | UI  |<--->|      |<--->|      |<-->|<--->|   +   |<--->|             |  
| |     |  ^  |Client|  ^  |Server|    |  ^  | Trace |  ^  | DWT, ETM,   |  
| +-----+  |  +------+  |  +------+    |  |  |       |  |  | ITM, TPIU   |  
|    ^     |     ^      |     ^        |  |  |       |  |  |             |  
|    |     |     |      |     |        |  |  |       |  |  |             |  
+----|-----|-----|------|-----|--------+  |  +-------+  |  +-------------+  
     |     |     |      |     |           |             |                  
     |     |     |      |     |           |             |                  
  Eclipse  |  arm-none- |  OpenOcd        |             |                  
           |  eabi-gdb  |   PyOcd         |             |                  
           |            |                 |             |                  
         GDB MI      GDB remote        Ethernet    debug: JTAG/SWD          
                     protocol            USB   trace: Serial/Parallel      

4.  Implementation needs

4.1  Self hosted debug monitor

   GDB : arm-linux-gnueabihf-gdb
      the interface defined in btrace.h for capturing and processing traces has to be implemented for arm CoreSight.
      needed actions:
         - in btrace-common.h: add needed structures for capturing and handling etm traces
         - in linux-btrace.h:
            - add btrace_tinfo_etm
            - amend btrace_target_info
         - in linux-btrace.c: change following functions to support etm traces
            - linux_enable_btrace
            - linux_disable_btrace
            - linux_read_btrace
            - linux_btrace_conf
         - in arm-linux-nat.c:add an api to
            - configure btrace
            - enable btrace
            - disable btrace
            - read btrace
         - in btrace.c
            - btrace_add_pc btrace_fetch has to be implemented for Coresight this means using opencsd library to parse etms and then reconstruct executed instructions accordingly (btrace_compute_ftrace_1)
         - in record-btrace.c
            - add command for showing record btrace etm options
            - add command for starting tracing with CoreSight and its handler (cmd_record_btrace_etm_start)
            - adapt cmd_show_record_btrace_cpu
            ...
   perf:
      needed actions:
         - make sure that perf can start/stop tracing a process with its threads, collect etm traces and deliver them to the user

4.2  Remote Debug monitor

   changes described in 7.1 are needed. in addition, and to support remote protocol following changes are needed
   GDB server: arm-linux-gnueabihf-gdbserver
      needed actions:
         - in linux-low
            - linux_low_read_btrace: add support for etm traces formatting.
            - linux_low_btrace_conf: :add support for etm configuration formatting.
     
   GDB client: arm-linux-gnueabihf-gdb
      needed actions:
         - in remote.c
            - adapt enable_btrace
            - adapt disable_btrace
           
         - in btrace.c
            - parse_xml_btrace: update btrace.dtd [2] and related data structures btrace_xxx
            - parse_xml_btrace_conf: update btrace-conf.dtd [3] and related data structures btrace_conf_xxx
         - extend Remote protocol handling to support coresight etm traces

   UI: eclipse
      needed actions
         make sure that the plugin for recoding execution and replaying it is coping well in case of arm-linux

   Remote protocol needs to be extended by  
     -1- Adding Qbtrace:CoreSight (or etm) to start collecting etm traces
     -2- Amending 'Branch Trace Format' xml specification to consider etm traces transfer
     -3- Amending 'Branch Trace Configuration Format' xml specification to consider parameters needed for etm

4.3  External debugger

   changes described in 7.2 are needed. in addition, and to support tracing a remote dealing with an external debugger (bare metal embedded system) following changes are needed
   GDB server: OpenOcd
      needed actions:
         - rework etm driver to make it up to date.
         - add a driver for configuring trace interconnect IPs
         - rework the driver for TPIU.
         - integrate support for a Trace port analyzer.
         - extend remote protocol implementation to support recording
     
      Coresight infrastructure of the SoC is to be set in OpenOcd through configuration files. Parameters that are not relevant for GDB are also specified in configuration files (trace sink, trace protocol, port size, trace synch frequency, cycle accurate tracing etc ...)
   
   GDB client: arm-none-eabi-gdb
      needed actions:
         - extend Remote protocol to support coresight etm traces
         - integrate etm trace parsing library
         - interface the parser to record_btrace_target
     
      Remote protocol needs -in addition to 7.2- to be extended by  
         
         - Adding Qbtrace-conf:CoreSight:core=value to support multicore SoC
         - Adding btrace-conf:CoreSight:id=value to support demultiplexing multiple trace sources
         - Adding Qbtrace-conf:CoreSight:filter:context=value to support filtering traces belonging to a given process/thread
         - Adding Qbtrace-conf:CoreSight:filter:start-address=value
              and Qbtrace-conf:CoreSight:filter:end-address=value to support filtering traces for given functions/blocks/lib
         - Adding Qbtrace-conf:CoreSight:trigger:on-address=value
               and Qbtrace-conf:CoreSight:trigger:off-address=value to support triggering tracing or stop tracing if a certain function/block/lib is executed
      alternatively some of configurations related to filtering and triggering can be delegated to the GDB server.
           
   UI: eclipse
      test and verify that existing plugins cope well with GDB extensions

5.  Remote protocol execution sequence

   GDB and gdbserver are communicating using the GDB remote protocol.
   on a semantic level a tracing session runs though following sequence
   (1)   GDB client queries gdb server support for branch trace
   (2)   GDB server answers with
         - qXfer:btrace:read
         - qXfer:btrace-conf:read
         - Qbtrace:off
         - Qbtrace:CoreSight
         - Qbtrace-conf:CoreSight:xxx where xxx is the parameter name
   (3)  GDB client sends command to let start emitting and collecting traces (Qbtrace:CoreSight)
   (4)  GDB server executes the commands
   (5)  GDB client sends command to stop emitting and collecting traces (Qbtrace:off)
   (6)  GDB server exectues the command
   (7)  GDB client sends command to get collected traces from trace sink (qXfer:btrace:read:annex:offset,length)
   (8)  GDB server executes the command and sends back collected traces
   (9)  GDB client parses the traces and reconstructs target states

6.  Remote protocol extensions

   the remote protocol needs be extended with following primitives to support CoreSight tracing
   - start tracing and traces capture using CoreSight (Qbtrace:CoreSight)
   
   the remote protocol can be extended with following primitives to take advantages of etm functionalities.
   
   - select the core to trace on in the case of a multicore system
     GDB client sends command to select the core to trace (Qbtrace-conf:CoreSight:core=value)
   - set the trace id for the traces
     GDB client sends command to set trace id (Qbtrace-conf:CoreSight:id=value)
   - select the context to trace
     GDB client sends command to select the context to trace (Qbtrace-conf:CoreSight:filter:context=value)
   - select the address range to trace
     GDB client sends command to select the address range to trace (Qbtrace-conf:CoreSight:filter:start-address=value) (Qbtrace-conf:CoreSight:filter:end-address=value)
   - set triggers for starting and stopping tracing
     GDB client sends command to select the address to trigger tracing (Qbtrace-conf:CoreSight:trigger:on-address=value) (Qbtrace-conf:CoreSight:trigger:off-address=value)

7.  alternatives and discussions

7.1.  Scope definition

   Coresight ETM IP comes in many versions and many implementations. According to its capabilities, it can trace instructions only or instructions and involved data/data address. All ETMs variants support instructions tracing and can therefore be used for for branch tracing.
   

7.2.  CoreSight infrastructure exposure to the user

   it is here about assigning the responsibility of configuring Coresight infrastructure to generate and route traces. two alternatives are possible:
      - coresight infrastructure exposed to GDB client (and UI):
        in this alternative the user or the UI is responsible for  configuring coresight IPs in the SoC, by accessing their registers directly or via coresigh driver. Remote protocol is used to configure trace sink (ETB or TPA) to start/stop collecting traces
      - coresight infrastructure is not exposed outside of gdbserver.
        in this case high level commands can be provided by gdbserver remote protocol to setup and configure coresight IPs in the SoC.
   
   My recommendation is to extend remote protocol to provide high level commands to setup and configure coresight IPs in the SoC, or to use a different channel to pass configuration parameters to GDB server

7.3.  Parameters needed for parsing traces
   Some configuration parameters like etm version, trace id ... (content of registers ETMCR, ETMIDR, ETMCCER, ETMTRACEIDR) are needed for extracting and parsing etm trace, those parameters needs to be exchanged between GDB server and client. following alternatives are possible:
      - extend the remote protocol to get those params with explicit queries
      - add them to the content of the response to qXfer:btrace-conf:read
      - add them to the content of the response to qXfer:btrace:read