src/target/xtensa/xtensa_debug_module.h

   1 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2
   3 /***************************************************************************
   4  *   Xtensa debug module API                                               *
   5  *   Copyright (C) 2019 Espressif Systems Ltd.                             *
   6  *   <alexey@espressif.com>                                                *
   7  *                                                                         *
   8  *   Derived from original ESP8266 target.                                 *
   9  *   Copyright (C) 2015 by Angus Gratton                                   *
  10  *   gus@projectgus.com                                                    *
  11  ***************************************************************************/
  12
  13 #ifndef OPENOCD_TARGET_XTENSA_DEBUG_MODULE_H
  14 #define OPENOCD_TARGET_XTENSA_DEBUG_MODULE_H
  15
  16 #include <jtag/jtag.h>
  17 #include <helper/bits.h>
  18 #include <target/target.h>
  19
  20 /* Virtual IDs for using with xtensa_power_ops API */
  21 #define DMREG_PWRCTL       0x00
  22 #define DMREG_PWRSTAT      0x01
  23
  24 /*
  25  From the manual:
  26  To properly use Debug registers through JTAG, software must ensure that:
  27  - Tap is out of reset
  28  - Xtensa Debug Module is out of reset
  29  - Other bits of PWRCTL are set to their desired values, and finally
  30  - JtagDebugUse transitions from 0 to 1
  31  The bit must continue to be 1 in order for JTAG accesses to the Debug
  32  Module to happen correctly. When it is set, any write to this bit clears it.
  33  Either don't access it, or re-write it to 1 so JTAG accesses continue.
  34 */
  35 #define PWRCTL_JTAGDEBUGUSE     BIT(7)
  36 #define PWRCTL_DEBUGRESET       BIT(6)
  37 #define PWRCTL_CORERESET        BIT(4)
  38 #define PWRCTL_DEBUGWAKEUP      BIT(2)
  39 #define PWRCTL_MEMWAKEUP        BIT(1)
  40 #define PWRCTL_COREWAKEUP       BIT(0)
  41
  42 #define PWRSTAT_DEBUGWASRESET   BIT(6)
  43 #define PWRSTAT_COREWASRESET    BIT(4)
  44 #define PWRSTAT_CORESTILLNEEDED BIT(3)
  45 #define PWRSTAT_DEBUGDOMAINON   BIT(2)
  46 #define PWRSTAT_MEMDOMAINON     BIT(1)
  47 #define PWRSTAT_COREDOMAINON    BIT(0)
  48
  49 /* *** NAR addresses (also used as IDs for debug registers in xtensa_debug_ops API) ***
  50  *TRAX registers */
  51 #define NARADR_TRAXID       0x00
  52 #define NARADR_TRAXCTRL     0x01
  53 #define NARADR_TRAXSTAT     0x02
  54 #define NARADR_TRAXDATA     0x03
  55 #define NARADR_TRAXADDR     0x04
  56 #define NARADR_TRIGGERPC    0x05
  57 #define NARADR_PCMATCHCTRL  0x06
  58 #define NARADR_DELAYCNT     0x07
  59 #define NARADR_MEMADDRSTART 0x08
  60 #define NARADR_MEMADDREND   0x09
  61 /*Performance monitor registers */
  62 #define NARADR_PMG          0x20
  63 #define NARADR_INTPC        0x24
  64 #define NARADR_PM0          0x28
  65 /*... */
  66 #define NARADR_PM7          0x2F
  67 #define NARADR_PMCTRL0      0x30
  68 /*... */
  69 #define NARADR_PMCTRL7      0x37
  70 #define NARADR_PMSTAT0      0x38
  71 /*... */
  72 #define NARADR_PMSTAT7      0x3F
  73 /*OCD registers */
  74 #define NARADR_OCDID        0x40
  75 #define NARADR_DCRCLR       0x42
  76 #define NARADR_DCRSET       0x43
  77 #define NARADR_DSR          0x44
  78 #define NARADR_DDR          0x45
  79 #define NARADR_DDREXEC      0x46
  80 #define NARADR_DIR0EXEC     0x47
  81 #define NARADR_DIR0         0x48
  82 #define NARADR_DIR1         0x49
  83 /*... */
  84 #define NARADR_DIR7         0x4F
  85 /*Misc registers */
  86 #define NARADR_PWRCTL       0x58
  87 #define NARADR_PWRSTAT      0x59
  88 #define NARADR_ERISTAT      0x5A
  89 /*CoreSight registers */
  90 #define NARADR_ITCTRL       0x60
  91 #define NARADR_CLAIMSET     0x68
  92 #define NARADR_CLAIMCLR     0x69
  93 #define NARADR_LOCKACCESS   0x6c
  94 #define NARADR_LOCKSTATUS   0x6d
  95 #define NARADR_AUTHSTATUS   0x6e
  96 #define NARADR_DEVID        0x72
  97 #define NARADR_DEVTYPE      0x73
  98 #define NARADR_PERID4       0x74
  99 /*... */
 100 #define NARADR_PERID7       0x77
 101 #define NARADR_PERID0       0x78
 102 /*... */
 103 #define NARADR_PERID3       0x7b
 104 #define NARADR_COMPID0      0x7c
 105 /*... */
 106 #define NARADR_COMPID3      0x7f
 107 #define NARADR_MAX          NARADR_COMPID3
 108
 109 /*OCD registers, bit definitions */
 110 #define OCDDCR_ENABLEOCD            BIT(0)
 111 #define OCDDCR_DEBUGINTERRUPT       BIT(1)
 112 #define OCDDCR_INTERRUPTALLCONDS    BIT(2)
 113 #define OCDDCR_BREAKINEN            BIT(16)
 114 #define OCDDCR_BREAKOUTEN           BIT(17)
 115 #define OCDDCR_DEBUGSWACTIVE        BIT(20)
 116 #define OCDDCR_RUNSTALLINEN         BIT(21)
 117 #define OCDDCR_DEBUGMODEOUTEN       BIT(22)
 118 #define OCDDCR_BREAKOUTITO          BIT(24)
 119 #define OCDDCR_BREAKACKITO          BIT(25)
 120
 121 #define OCDDSR_EXECDONE             BIT(0)
 122 #define OCDDSR_EXECEXCEPTION        BIT(1)
 123 #define OCDDSR_EXECBUSY             BIT(2)
 124 #define OCDDSR_EXECOVERRUN          BIT(3)
 125 #define OCDDSR_STOPPED              BIT(4)
 126 #define OCDDSR_COREWROTEDDR         BIT(10)
 127 #define OCDDSR_COREREADDDR          BIT(11)
 128 #define OCDDSR_HOSTWROTEDDR         BIT(14)
 129 #define OCDDSR_HOSTREADDDR          BIT(15)
 130 #define OCDDSR_DEBUGPENDBREAK       BIT(16)
 131 #define OCDDSR_DEBUGPENDHOST        BIT(17)
 132 #define OCDDSR_DEBUGPENDTRAX        BIT(18)
 133 #define OCDDSR_DEBUGINTBREAK        BIT(20)
 134 #define OCDDSR_DEBUGINTHOST         BIT(21)
 135 #define OCDDSR_DEBUGINTTRAX         BIT(22)
 136 #define OCDDSR_RUNSTALLTOGGLE       BIT(23)
 137 #define OCDDSR_RUNSTALLSAMPLE       BIT(24)
 138 #define OCDDSR_BREACKOUTACKITI      BIT(25)
 139 #define OCDDSR_BREAKINITI           BIT(26)
 140 #define OCDDSR_DBGMODPOWERON        BIT(31)
 141
 142 #define DEBUGCAUSE_IC               BIT(0)      /* ICOUNT exception */
 143 #define DEBUGCAUSE_IB               BIT(1)      /* IBREAK exception */
 144 #define DEBUGCAUSE_DB               BIT(2)      /* DBREAK exception */
 145 #define DEBUGCAUSE_BI               BIT(3)      /* BREAK instruction encountered */
 146 #define DEBUGCAUSE_BN               BIT(4)      /* BREAK.N instruction encountered */
 147 #define DEBUGCAUSE_DI               BIT(5)      /* Debug Interrupt */
 148
 149 #define TRAXCTRL_TREN               BIT(0)      /* Trace enable. Tracing starts on 0->1 */
 150 #define TRAXCTRL_TRSTP              BIT(1)      /* Trace Stop. Make 1 to stop trace. */
 151 #define TRAXCTRL_PCMEN              BIT(2)      /* PC match enable */
 152 #define TRAXCTRL_PTIEN              BIT(4)      /* Processor-trigger enable */
 153 #define TRAXCTRL_CTIEN              BIT(5)      /* Cross-trigger enable */
 154 #define TRAXCTRL_TMEN               BIT(7)      /* Tracemem Enable. Always set. */
 155 #define TRAXCTRL_CNTU               BIT(9)      /* Post-stop-trigger countdown units; selects when DelayCount-- happens.
 156                                                  *0 - every 32-bit word written to tracemem, 1 - every cpu instruction */
 157 #define TRAXCTRL_TSEN               BIT(11)     /* Undocumented/deprecated? */
 158 #define TRAXCTRL_SMPER_SHIFT        12          /* Send sync every 2^(9-smper) messages. 7=reserved, 0=no sync msg */
 159 #define TRAXCTRL_SMPER_MASK         0x07        /* Synchronization message period */
 160 #define TRAXCTRL_PTOWT              BIT(16)     /* Processor Trigger Out (OCD halt) enabled when stop triggered */
 161 #define TRAXCTRL_PTOWS              BIT(17)     /* Processor Trigger Out (OCD halt) enabled when trace stop completes */
 162 #define TRAXCTRL_CTOWT              BIT(20)     /* Cross-trigger Out enabled when stop triggered */
 163 #define TRAXCTRL_CTOWS              BIT(21)     /* Cross-trigger Out enabled when trace stop completes */
 164 #define TRAXCTRL_ITCTO              BIT(22)     /* Integration mode: cross-trigger output */
 165 #define TRAXCTRL_ITCTIA             BIT(23)     /* Integration mode: cross-trigger ack */
 166 #define TRAXCTRL_ITATV              BIT(24)     /* replaces ATID when in integration mode: ATVALID output */
 167 #define TRAXCTRL_ATID_MASK          0x7F        /* ARB source ID */
 168 #define TRAXCTRL_ATID_SHIFT         24
 169 #define TRAXCTRL_ATEN               BIT(31)     /* ATB interface enable */
 170
 171 #define TRAXSTAT_TRACT              BIT(0)      /* Trace active flag. */
 172 #define TRAXSTAT_TRIG               BIT(1)      /* Trace stop trigger. Clears on TREN 1->0 */
 173 #define TRAXSTAT_PCMTG              BIT(2)      /* Stop trigger caused by PC match. Clears on TREN 1->0 */
 174 #define TRAXSTAT_PJTR               BIT(3)      /* JTAG transaction result. 1=err in preceding jtag transaction. */
 175 #define TRAXSTAT_PTITG              BIT(4)      /* Stop trigger caused by Processor Trigger Input.Clears on TREN 1->0 */
 176 #define TRAXSTAT_CTITG              BIT(5)      /* Stop trigger caused by Cross-Trigger Input. Clears on TREN 1->0 */
 177 #define TRAXSTAT_MEMSZ_SHIFT        8           /* Traceram size inducator. Usable trace ram is 2^MEMSZ bytes. */
 178 #define TRAXSTAT_MEMSZ_MASK         0x1F
 179 #define TRAXSTAT_PTO                BIT(16)     /* Processor Trigger Output: current value */
 180 #define TRAXSTAT_CTO                BIT(17)     /* Cross-Trigger Output: current value */
 181 #define TRAXSTAT_ITCTOA             BIT(22)     /* Cross-Trigger Out Ack: current value */
 182 #define TRAXSTAT_ITCTI              BIT(23)     /* Cross-Trigger Input: current value */
 183 #define TRAXSTAT_ITATR              BIT(24)     /* ATREADY Input: current value */
 184
 185 #define TRAXADDR_TADDR_SHIFT        0           /* Trax memory address, in 32-bit words. */
 186 #define TRAXADDR_TADDR_MASK         0x1FFFFF    /* Actually is only as big as the trace buffer size max addr. */
 187 #define TRAXADDR_TWRAP_SHIFT        21          /* Amount of times TADDR has overflown */
 188 #define TRAXADDR_TWRAP_MASK         0x3FF
 189 #define TRAXADDR_TWSAT              BIT(31)     /* 1 if TWRAP has overflown, clear by disabling tren.*/
 190
 191 #define PCMATCHCTRL_PCML_SHIFT      0           /* Amount of lower bits to ignore in pc trigger register */
 192 #define PCMATCHCTRL_PCML_MASK       0x1F
 193 #define PCMATCHCTRL_PCMS            BIT(31)     /* PC Match Sense, 0-match when procs PC is in-range, 1-match when
 194                                                  *out-of-range */
 195
 196 #define XTENSA_MAX_PERF_COUNTERS    2
 197 #define XTENSA_MAX_PERF_SELECT      32
 198 #define XTENSA_MAX_PERF_MASK        0xffff
 199
 200 #define XTENSA_STOPMASK_DISABLED    UINT32_MAX
 201
 202 struct xtensa_debug_module;
 203
 204 struct xtensa_debug_ops {
 205         /** enable operation */
 206         int (*queue_enable)(struct xtensa_debug_module *dm);
 207         /** register read. */
 208         int (*queue_reg_read)(struct xtensa_debug_module *dm, unsigned int reg, uint8_t *data);
 209         /** register write. */
 210         int (*queue_reg_write)(struct xtensa_debug_module *dm, unsigned int reg, uint32_t data);
 211 };
 212
 213 struct xtensa_power_ops {
 214         /** register read. */
 215         int (*queue_reg_read)(struct xtensa_debug_module *dm, unsigned int reg, uint8_t *data,
 216                 uint8_t clear);
 217         /** register write. */
 218         int (*queue_reg_write)(struct xtensa_debug_module *dm, unsigned int reg, uint8_t data);
 219 };
 220
 221 typedef uint8_t xtensa_pwrstat_t;
 222 typedef uint32_t xtensa_ocdid_t;
 223 typedef uint32_t xtensa_dsr_t;
 224 typedef uint32_t xtensa_traxstat_t;
 225
 226 struct xtensa_power_status {
 227         xtensa_pwrstat_t stat;
 228         xtensa_pwrstat_t stath;
 229         /* TODO: do not need to keep previous status to detect that core or debug module has been
 230          * reset, */
 231         /*       we can clear PWRSTAT_DEBUGWASRESET and PWRSTAT_COREWASRESET after reading will do
 232          * the job; */
 233         /*       upon next reet those bits will be set again. So we can get rid of
 234          *       xtensa_dm_power_status_cache_reset() and xtensa_dm_power_status_cache(). */
 235         xtensa_pwrstat_t prev_stat;
 236 };
 237
 238 struct xtensa_core_status {
 239         xtensa_dsr_t dsr;
 240 };
 241
 242 struct xtensa_trace_config {
 243         uint32_t ctrl;
 244         uint32_t memaddr_start;
 245         uint32_t memaddr_end;
 246         uint32_t addr;
 247 };
 248
 249 struct xtensa_trace_status {
 250         xtensa_traxstat_t stat;
 251 };
 252
 253 struct xtensa_trace_start_config {
 254         uint32_t stoppc;
 255         bool after_is_words;
 256         uint32_t after;
 257         uint32_t stopmask;      /* UINT32_MAX: disable PC match option */
 258 };
 259
 260 struct xtensa_perfmon_config {
 261         int select;
 262         uint32_t mask;
 263         int kernelcnt;
 264         int tracelevel;
 265 };
 266
 267 struct xtensa_perfmon_result {
 268         uint64_t value;
 269         bool overflow;
 270 };
 271
 272 struct xtensa_debug_module_config {
 273         const struct xtensa_power_ops *pwr_ops;
 274         const struct xtensa_debug_ops *dbg_ops;
 275         struct jtag_tap *tap;
 276         void (*queue_tdi_idle)(struct target *target);
 277         void *queue_tdi_idle_arg;
 278 };
 279
 280 struct xtensa_debug_module {
 281         const struct xtensa_power_ops *pwr_ops;
 282         const struct xtensa_debug_ops *dbg_ops;
 283         struct jtag_tap *tap;
 284         void (*queue_tdi_idle)(struct target *target);
 285         void *queue_tdi_idle_arg;
 286
 287         struct xtensa_power_status power_status;
 288         struct xtensa_core_status core_status;
 289         xtensa_ocdid_t device_id;
 290 };
 291
 292 int xtensa_dm_init(struct xtensa_debug_module *dm, const struct xtensa_debug_module_config *cfg);
 293 int xtensa_dm_queue_enable(struct xtensa_debug_module *dm);
 294 int xtensa_dm_queue_reg_read(struct xtensa_debug_module *dm, unsigned int reg, uint8_t *value);
 295 int xtensa_dm_queue_reg_write(struct xtensa_debug_module *dm, unsigned int reg, uint32_t value);
 296 int xtensa_dm_queue_pwr_reg_read(struct xtensa_debug_module *dm, unsigned int reg, uint8_t *data, uint8_t clear);
 297 int xtensa_dm_queue_pwr_reg_write(struct xtensa_debug_module *dm, unsigned int reg, uint8_t data);
 298
 299 static inline void xtensa_dm_queue_tdi_idle(struct xtensa_debug_module *dm)
 300 {
 301         if (dm->queue_tdi_idle)
 302                 dm->queue_tdi_idle(dm->queue_tdi_idle_arg);
 303 }
 304
 305 int xtensa_dm_power_status_read(struct xtensa_debug_module *dm, uint32_t clear);
 306 static inline void xtensa_dm_power_status_cache_reset(struct xtensa_debug_module *dm)
 307 {
 308         dm->power_status.prev_stat = 0;
 309 }
 310 static inline void xtensa_dm_power_status_cache(struct xtensa_debug_module *dm)
 311 {
 312         dm->power_status.prev_stat = dm->power_status.stath;
 313 }
 314 static inline xtensa_pwrstat_t xtensa_dm_power_status_get(struct xtensa_debug_module *dm)
 315 {
 316         return dm->power_status.stat;
 317 }
 318
 319 int xtensa_dm_core_status_read(struct xtensa_debug_module *dm);
 320 int xtensa_dm_core_status_clear(struct xtensa_debug_module *dm, xtensa_dsr_t bits);
 321 int xtensa_dm_core_status_check(struct xtensa_debug_module *dm);
 322 static inline xtensa_dsr_t xtensa_dm_core_status_get(struct xtensa_debug_module *dm)
 323 {
 324         return dm->core_status.dsr;
 325 }
 326
 327 int xtensa_dm_device_id_read(struct xtensa_debug_module *dm);
 328 static inline xtensa_ocdid_t xtensa_dm_device_id_get(struct xtensa_debug_module *dm)
 329 {
 330         return dm->device_id;
 331 }
 332
 333 int xtensa_dm_trace_start(struct xtensa_debug_module *dm, struct xtensa_trace_start_config *cfg);
 334 int xtensa_dm_trace_stop(struct xtensa_debug_module *dm, bool pto_enable);
 335 int xtensa_dm_trace_config_read(struct xtensa_debug_module *dm, struct xtensa_trace_config *config);
 336 int xtensa_dm_trace_status_read(struct xtensa_debug_module *dm, struct xtensa_trace_status *status);
 337 int xtensa_dm_trace_data_read(struct xtensa_debug_module *dm, uint8_t *dest, uint32_t size);
 338
 339 static inline bool xtensa_dm_is_online(struct xtensa_debug_module *dm)
 340 {
 341         int res = xtensa_dm_device_id_read(dm);
 342         if (res != ERROR_OK)
 343                 return false;
 344         return (dm->device_id != 0xffffffff && dm->device_id != 0);
 345 }
 346
 347 static inline bool xtensa_dm_tap_was_reset(struct xtensa_debug_module *dm)
 348 {
 349         return !(dm->power_status.prev_stat & PWRSTAT_DEBUGWASRESET) &&
 350                dm->power_status.stat & PWRSTAT_DEBUGWASRESET;
 351 }
 352
 353 static inline bool xtensa_dm_core_was_reset(struct xtensa_debug_module *dm)
 354 {
 355         return !(dm->power_status.prev_stat & PWRSTAT_COREWASRESET) &&
 356                dm->power_status.stat & PWRSTAT_COREWASRESET;
 357 }
 358
 359 static inline bool xtensa_dm_core_is_stalled(struct xtensa_debug_module *dm)
 360 {
 361         return dm->core_status.dsr & OCDDSR_RUNSTALLSAMPLE;
 362 }
 363
 364 static inline bool xtensa_dm_is_powered(struct xtensa_debug_module *dm)
 365 {
 366         return dm->core_status.dsr & OCDDSR_DBGMODPOWERON;
 367 }
 368
 369 int xtensa_dm_perfmon_enable(struct xtensa_debug_module *dm, int counter_id,
 370         const struct xtensa_perfmon_config *config);
 371 int xtensa_dm_perfmon_dump(struct xtensa_debug_module *dm, int counter_id,
 372         struct xtensa_perfmon_result *out_result);
 373
 374 #endif  /* OPENOCD_TARGET_XTENSA_DEBUG_MODULE_H */