Repository: espressif/esp-stub-lib
Pull request #12: Add traxmem helpers
Author: login: erhankur
Created: 2025-05-05T15:53:46Z | Merged: 2025-05-22T22:46:33Z

- Add Xtensa TRAX memory helpers to be used in the AppTrace module of the OpenOCD stub.
- Add `soc_utils.h` private to the library codes.
- Add `bit_utils.h` public to the library and client codes.

Will be merged after #11 


Diff:
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 36581dca..128f91a7 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -34,7 +34,9 @@ target_include_directories(${ESP_STUB_LIB}
     INTERFACE include
     PRIVATE include/esp-stub-lib
 )
+# Public within the library
 include_directories(include)
+include_directories(include/esp-stub-lib)
 
 # STUB_COMPILE_DEFS is optional definitions coming from the parent CMakeLists.txt
 target_compile_definitions(${ESP_STUB_LIB} PRIVATE ${STUB_COMPILE_DEFS})
diff --git a/include/esp-stub-lib/bit_utils.h b/include/esp-stub-lib/bit_utils.h
new file mode 100644
index 00000000..8e2a4722
--- /dev/null
+++ b/include/esp-stub-lib/bit_utils.h
@@ -0,0 +1,51 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef BIT
+#define BIT(nr)                 (1UL << (nr))
+#endif
+
+#ifndef BIT64
+#define BIT64(nr)               (1ULL << (nr))
+#endif
+
+#ifndef ALIGN_MASK
+#define ALIGN_MASK(x, mask)             \
+({                                      \
+    typeof(mask) _mask = (mask);        \
+    ((x) + _mask) & ~_mask;             \
+})
+#endif
+
+#ifndef ALIGN_UP
+#define ALIGN_UP(x, a)          ALIGN_MASK(x, (typeof(x))(a) - 1)
+#endif
+
+#ifndef ALIGN_DOWN
+#define ALIGN_DOWN(x, a)        ((x) & ~((typeof(x))(a) - 1))
+#endif
+
+#ifndef IS_ALIGNED
+#define IS_ALIGNED(x, a)        (((x) & ((typeof(x))(a) - 1)) == 0)
+#endif
+
+#ifndef MIN
+#define MIN(a, b)               ((a) < (b) ? (a) : (b))
+#endif
+
+#ifndef MAX
+#define MAX(a, b)               ((a) > (b) ? (a) : (b))
+#endif
+
+#ifdef __cplusplus
+}
+#endif
diff --git a/include/esp-stub-lib/trax_mem.h b/include/esp-stub-lib/trax_mem.h
new file mode 100644
index 00000000..5a8517b3
--- /dev/null
+++ b/include/esp-stub-lib/trax_mem.h
@@ -0,0 +1,82 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+#include <stdint.h>
+
+#include <target/trax.h>
+#include "bit_utils.h"
+
+#define ERI_DEBUG_OFFSET        0x100000
+#define ERI_TRAX_OFFSET         (ERI_DEBUG_OFFSET + 0x0)
+#define ERI_PERFMON_OFFSET      (ERI_DEBUG_OFFSET + 0x1000)
+#define ERI_TRAX_TRAXCTRL       (ERI_TRAX_OFFSET + 0x4)
+#define ERI_TRAX_TRIGGERPC      (ERI_TRAX_OFFSET + 0x14)
+#define ERI_TRAX_DELAYCNT       (ERI_TRAX_OFFSET + 0x1C)
+
+#define ERI_PERFMON_PM1         (ERI_PERFMON_OFFSET + 0x84) /* used in apptrace module to store CRC16 */
+
+#define TRAXCTRL_TRSTP          BIT(1)  // Trace Stop. Make 1 to stop trace.
+#define TRAXCTRL_TMEN           BIT(7)  // Trace Memory Enable. Always set.
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+static inline uint32_t eri_read(int addr)
+{
+    uint32_t ret;
+    asm volatile(
+        "RER %0,%1"
+        :"=r"(ret):"r"(addr)
+    );
+    return ret;
+}
+
+static inline void eri_write(int addr, uint32_t data)
+{
+    asm volatile(
+        "WER %0,%1"
+        ::"r"(data), "r"(addr)
+    );
+}
+
+/*
+ * Enable the TRAX memory. For ESP32 only.
+ */
+static inline void esp_stub_lib_trax_mem_enable(void)
+{
+    stub_target_trax_mem_enable();
+}
+
+/*
+ * Select the memory block (0 or 1) to use.
+ */
+static inline void esp_stub_lib_trax_select_mem_block(int block)
+{
+    stub_target_trax_select_mem_block(block);
+}
+
+/*
+ * Read a TRAX register using ERI.
+ */
+static inline uint32_t esp_stub_lib_trax_reg_read(int addr)
+{
+    return eri_read(addr);
+}
+
+/*
+ * Write a TRAX register using ERI.
+ */
+static inline void esp_stub_lib_trax_reg_write(int addr, uint32_t data)
+{
+    eri_write(addr, data);
+}
+
+#ifdef __cplusplus
+}
+#endif
diff --git a/include/private/soc_utils.h b/include/private/soc_utils.h
new file mode 100644
index 00000000..66a74ec3
--- /dev/null
+++ b/include/private/soc_utils.h
@@ -0,0 +1,88 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+#define ETS_UNCACHED_ADDR(addr) (addr)
+#define ETS_CACHED_ADDR(addr) (addr)
+
+// Base register read/write macros
+#define REG_READ(_r) ({                                                                                                \
+            (*(volatile uint32_t *)(_r));                                                                              \
+        })
+
+#define REG_WRITE(_r, _v)  do {                                                                                        \
+            (*(volatile uint32_t *)(_r)) = (_v);                                                                       \
+        } while(0)
+
+// Bit manipulation macros
+#define REG_GET_BIT(_r, _b)  ({                                                                                        \
+            (REG_READ(_r) & (_b));                                                                                     \
+        })
+
+#define REG_SET_BIT(_r, _b)  do {                                                                                      \
+            REG_WRITE(_r, REG_READ(_r) | (_b));                                                                        \
+        } while(0)
+
+#define REG_CLR_BIT(_r, _b)  do {                                                                                      \
+            REG_WRITE(_r, REG_READ(_r) & (~(_b)));                                                                     \
+        } while(0)
+
+#define REG_SET_BITS(_r, _b, _m) do {                                                                                  \
+            REG_WRITE(_r, (REG_READ(_r) & ~(_m)) | ((_b) & (_m)));                                                     \
+        } while(0)
+
+// Field manipulation macros
+#define REG_GET_FIELD(_r, _f) ({                                                                                       \
+            ((REG_READ(_r) >> (_f##_S)) & (_f##_V));                                                                   \
+        })
+
+#define REG_SET_FIELD(_r, _f, _v) do {                                                                                 \
+            REG_WRITE(_r, (REG_READ(_r) & ~((_f##_V) << (_f##_S))) | (((_v) & (_f##_V)) << (_f##_S)));                 \
+        } while(0)
+
+// Value field manipulation macros
+#define VALUE_GET_FIELD(_r, _f) (((_r) >> (_f##_S)) & (_f))
+
+#define VALUE_GET_FIELD2(_r, _f) (((_r) & (_f)) >> (_f##_S))
+
+#define VALUE_SET_FIELD(_r, _f, _v) ((_r) = ((_r) & ~((_f) << (_f##_S))) | ((_v) << (_f##_S)))
+
+#define VALUE_SET_FIELD2(_r, _f, _v) ((_r) = ((_r) & ~(_f)) | ((_v) << (_f##_S)))
+
+// Field to value conversion macros
+#define FIELD_TO_VALUE(_f, _v) (((_v) & (_f)) << _f##_S)
+
+#define FIELD_TO_VALUE2(_f, _v) (((_v) << _f##_S) & (_f))
+
+// Peripheral register macros
+#define READ_PERI_REG(addr) REG_READ(ETS_UNCACHED_ADDR(addr))
+
+#define WRITE_PERI_REG(addr, val) REG_WRITE(ETS_UNCACHED_ADDR(addr), (uint32_t)(val))
+
+#define CLEAR_PERI_REG_MASK(reg, mask) do {                                                                            \
+            WRITE_PERI_REG(reg, READ_PERI_REG(reg) & (~(mask)));                                                       \
+        } while(0)
+
+#define SET_PERI_REG_MASK(reg, mask) do {                                                                              \
+            WRITE_PERI_REG(reg, READ_PERI_REG(reg) | (mask));                                                          \
+        } while(0)
+
+#define GET_PERI_REG_MASK(reg, mask) ({                                                                                \
+            (READ_PERI_REG(reg) & (mask));                                                                             \
+        })
+
+#define GET_PERI_REG_BITS(reg, hipos, lowpos) ({                                                                       \
+            ((READ_PERI_REG(reg) >> (lowpos)) & ((1 << ((hipos) - (lowpos) + 1)) - 1));                                \
+        })
+
+#define SET_PERI_REG_BITS(reg, bit_map, value, shift) do {                                                             \
+            WRITE_PERI_REG(reg, (READ_PERI_REG(reg) & (~((bit_map) << (shift)))) | (((value) & (bit_map)) << (shift))); \
+        } while(0)
+
+#define GET_PERI_REG_BITS2(reg, mask, shift) ({                                                                        \
+            ((READ_PERI_REG(reg) >> (shift)) & (mask));                                                                \
+        })
diff --git a/include/target/trax.h b/include/target/trax.h
new file mode 100644
index 00000000..dab218ef
--- /dev/null
+++ b/include/target/trax.h
@@ -0,0 +1,10 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+void stub_target_trax_mem_enable(void);
+void stub_target_trax_select_mem_block(int block);
diff --git a/src/esp32/CMakeLists.txt b/src/esp32/CMakeLists.txt
index d67d3dd5..98df4255 100644
--- a/src/esp32/CMakeLists.txt
+++ b/src/esp32/CMakeLists.txt
@@ -1,6 +1,7 @@
 set(srcs
     src/uart.c
     src/flash.c
+    src/trax.c
 )
 
 add_library(${ESP_TARGET_LIB} STATIC ${srcs})
diff --git a/src/esp32/src/trax.c b/src/esp32/src/trax.c
new file mode 100644
index 00000000..b671f9a8
--- /dev/null
+++ b/src/esp32/src/trax.c
@@ -0,0 +1,28 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#include <stdint.h>
+
+#include <private/soc_utils.h>
+
+#include "soc/reg_base.h"
+
+#define TRACEMEM_MUX_MODE_REG           (DR_REG_DPORT_BASE + 0x070)
+#define TRACEMEM_ENA_REG                (DR_REG_DPORT_BASE + 0x074)
+#define TRACEMEM_ENA_M                  (0x1)
+
+#define TRACEMEM_MUX_BLK0_ONLY          1
+#define TRACEMEM_MUX_BLK1_ONLY          2
+
+void stub_target_trax_mem_enable(void)
+{
+    WRITE_PERI_REG(TRACEMEM_ENA_REG, TRACEMEM_ENA_M);
+}
+
+void stub_target_trax_select_mem_block(int block)
+{
+    WRITE_PERI_REG(TRACEMEM_MUX_MODE_REG, block ? TRACEMEM_MUX_BLK0_ONLY : TRACEMEM_MUX_BLK1_ONLY);
+}
diff --git a/src/esp32s2/CMakeLists.txt b/src/esp32s2/CMakeLists.txt
index 78e85f2a..93adcc4c 100644
--- a/src/esp32s2/CMakeLists.txt
+++ b/src/esp32s2/CMakeLists.txt
@@ -1,6 +1,7 @@
 set(srcs
     src/uart.c
     src/flash.c
+    src/trax.c
 )
 
 add_library(${ESP_TARGET_LIB} STATIC ${srcs})
diff --git a/src/esp32s2/src/trax.c b/src/esp32s2/src/trax.c
new file mode 100644
index 00000000..0fecf987
--- /dev/null
+++ b/src/esp32s2/src/trax.c
@@ -0,0 +1,27 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#include <stdint.h>
+
+#include <bit_utils.h>
+#include <private/soc_utils.h>
+
+#include "soc/reg_base.h"
+
+#define PMS_OCCUPY_3_REG                (DR_REG_SENSITIVE_BASE + 0x0E0)
+
+#define TRACEMEM_MUX_BLK0_NUM           19
+#define TRACEMEM_MUX_BLK1_NUM           20
+
+void stub_target_trax_mem_enable(void)
+{
+    /* nothing to do for ESP32S2 */
+}
+
+void stub_target_trax_select_mem_block(int block)
+{
+    WRITE_PERI_REG(PMS_OCCUPY_3_REG, block ? BIT(TRACEMEM_MUX_BLK0_NUM - 4) : BIT(TRACEMEM_MUX_BLK1_NUM - 4));
+}
diff --git a/src/esp32s3/CMakeLists.txt b/src/esp32s3/CMakeLists.txt
index 0f57f595..112ea07a 100644
--- a/src/esp32s3/CMakeLists.txt
+++ b/src/esp32s3/CMakeLists.txt
@@ -1,6 +1,7 @@
 set(srcs
     src/uart.c
     src/flash.c
+    src/trax.c
 )
 
 add_library(${ESP_TARGET_LIB} STATIC ${srcs})
diff --git a/src/esp32s3/src/trax.c b/src/esp32s3/src/trax.c
new file mode 100644
index 00000000..13aeecea
--- /dev/null
+++ b/src/esp32s3/src/trax.c
@@ -0,0 +1,35 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#include <stdint.h>
+
+#include <bit_utils.h>
+#include <private/soc_utils.h>
+
+#include "soc/reg_base.h"
+
+#define SENSITIVE_INTERNAL_SRAM_USAGE_2_REG (DR_REG_SENSITIVE_BASE + 0x18)
+
+#define TRACEMEM_MUX_BLK0_NUM               22
+#define TRACEMEM_MUX_BLK1_NUM               26
+
+#define TRACEMEM_MUX_BLK_ALLOC(_n_)         (((_n_) - 2UL) % 4UL)
+#define TRACEMEM_CORE0_MUX_BLK_BITS(_n_)    (BIT(((_n_) - 2UL) / 4UL) | (TRACEMEM_MUX_BLK_ALLOC(_n_) << 14))
+#define TRACEMEM_CORE1_MUX_BLK_BITS(_n_)    (BIT(7UL + ((_n_) - 2UL) / 4UL) | (TRACEMEM_MUX_BLK_ALLOC(_n_) << 16))
+
+void stub_target_trax_mem_enable(void)
+{
+    /* nothing to do for ESP32S3 */
+}
+
+void stub_target_trax_select_mem_block(int block)
+{
+    uint32_t block_bits = block ? TRACEMEM_CORE0_MUX_BLK_BITS(TRACEMEM_MUX_BLK0_NUM)
+                          : TRACEMEM_CORE0_MUX_BLK_BITS(TRACEMEM_MUX_BLK1_NUM);
+    block_bits |= block ? TRACEMEM_CORE1_MUX_BLK_BITS(TRACEMEM_MUX_BLK0_NUM)
+                  : TRACEMEM_CORE1_MUX_BLK_BITS(TRACEMEM_MUX_BLK1_NUM);
+    WRITE_PERI_REG(SENSITIVE_INTERNAL_SRAM_USAGE_2_REG, block_bits);
+}


Reviews:
user: login: gerekon
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-06T09:52:17Z
user: login: antmak
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-06T10:45:32Z
user: login: gerekon
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-06T12:32:56Z
user: login: erhankur
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-06T14:09:54Z
user: login: erhankur
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-06T14:29:56Z
user: login: antmak
body: .
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-05-07T02:12:42Z
user: login: gerekon
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-13T09:33:42Z
user: login: gerekon
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-05-13T09:35:17Z
user: login: erhankur
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-15T10:32:37Z

Review comments:
diff_hunk: @@ -0,0 +1,79 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+#include <stdint.h>
+
+#define ERI_DEBUG_OFFSET        0x100000
path: include/esp-stub-lib/trax_mem.h
user: login: gerekon
body: Not sure that we need to expose such low-level Xtensa specific things outside the lib. 
Will they be used directly by the stub? 

What do you think about exposing higher level API to work with `apptrace` control block for either Xtensa or RISCV chips? The purpose of control memory block is to provide control over apptrace data transfer.
- For Xtensa control block is a set of TRAX registers. For apptrace TRAX regs do not do any HW operations. They are used just to expose control bits between the host and target. Works like a trivial `data containers` accessible from both sides.  
- For RISCV control block is a struct in memory with the special fields which do the same thing as TRAX regs for Xtensa.
created_at: 2025-05-06T09:21:38Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,79 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+#include <stdint.h>
+
+#define ERI_DEBUG_OFFSET        0x100000
+#define ERI_TRAX_OFFSET         (ERI_DEBUG_OFFSET + 0x0)
+#define ERI_TRAX_TRAXCTRL       (ERI_TRAX_OFFSET + 0x4)
+#define ERI_TRAX_TRIGGERPC      (ERI_TRAX_OFFSET + 0x14)
+#define ERI_TRAX_DELAYCNT       (ERI_TRAX_OFFSET + 0x1C)
+
+#define TRAXCTRL_TRSTP          (1 << 1)  // Trace Stop. Make 1 to stop trace.
+#define TRAXCTRL_TMEN           (1 << 7)  // Trace Memory Enable. Always set.
path: include/esp-stub-lib/trax_mem.h
user: login: gerekon
body: Can use `BIT` macro here
created_at: 2025-05-06T09:23:29Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,108 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+#define ETS_UNCACHED_ADDR(addr) (addr)
+#define ETS_CACHED_ADDR(addr) (addr)
+
+//write value to register
+#define REG_WRITE(_r, _v)  do {                                                                                        \
+            (*(volatile uint32_t *)(_r)) = (_v);                                                                       \
+        } while(0)
+
+//read value from register
+#define REG_READ(_r) ({                                                                                                \
+            (*(volatile uint32_t *)(_r));                                                                              \
+        })
+
+//get bit or get bits from register
+#define REG_GET_BIT(_r, _b)  ({                                                                                        \
+            (*(volatile uint32_t*)(_r) & (_b));                                                                        \
path: include/private/soc_utils.h
user: login: gerekon
body: ```suggestion
            (REG_READ(_r) & (_b));                                                                        \
```
created_at: 2025-05-06T09:27:58Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,108 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+#define ETS_UNCACHED_ADDR(addr) (addr)
+#define ETS_CACHED_ADDR(addr) (addr)
+
+//write value to register
+#define REG_WRITE(_r, _v)  do {                                                                                        \
+            (*(volatile uint32_t *)(_r)) = (_v);                                                                       \
+        } while(0)
+
+//read value from register
+#define REG_READ(_r) ({                                                                                                \
+            (*(volatile uint32_t *)(_r));                                                                              \
+        })
+
+//get bit or get bits from register
+#define REG_GET_BIT(_r, _b)  ({                                                                                        \
+            (*(volatile uint32_t*)(_r) & (_b));                                                                        \
+        })
+
+//set bit or set bits to register
+#define REG_SET_BIT(_r, _b)  do {                                                                                      \
+            *(volatile uint32_t*)(_r) = (*(volatile uint32_t*)(_r)) | (_b);                                            \
path: include/private/soc_utils.h
user: login: gerekon
body: ```suggestion
            REG_WRITE(REG_READ(_r) | (_b));                                            \
```
Also in other places below
created_at: 2025-05-06T09:29:47Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,51 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef BIT
+#define BIT(nr)                 (1UL << (nr))
path: include/esp-stub-lib/bit_utils.h
user: login: antmak
body: about code style, should we comply some space standard here: alignment by the defined value, or just a space? Or stick to the same style only within one file?

created_at: 2025-05-06T10:45:32Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,79 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+#include <stdint.h>
+
+#define ERI_DEBUG_OFFSET        0x100000
path: include/esp-stub-lib/trax_mem.h
user: login: gerekon
body: > Will they be used directly by the stub?

Ok. I see stub use them.
created_at: 2025-05-06T12:32:55Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,79 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+#include <stdint.h>
+
+#define ERI_DEBUG_OFFSET        0x100000
path: include/esp-stub-lib/trax_mem.h
user: login: erhankur
body: We could expose an API like `esp_stub_lib_ctrl_reg_read` and `esp_stub_lib_ctrl_reg_write`, but the apptrace design is specific to OpenOCD and not intended for general use. So, I preferred to expose only the register_read/write APIs. OpenOCD can do whatever it wants with them. 
created_at: 2025-05-06T14:09:54Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,51 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef BIT
+#define BIT(nr)                 (1UL << (nr))
path: include/esp-stub-lib/bit_utils.h
user: login: erhankur
body: I usually follow the alignment within the file. 
created_at: 2025-05-06T14:29:56Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,79 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+#include <stdint.h>
+
+#define ERI_DEBUG_OFFSET        0x100000
path: include/esp-stub-lib/trax_mem.h
user: login: gerekon
body: I am ok to have them like this. But if nobody use it except for OpenOCD. Does it make big sense to keep them here? Just a question...
created_at: 2025-05-13T09:33:42Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,79 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+#include <stdint.h>
+
+#define ERI_DEBUG_OFFSET        0x100000
path: include/esp-stub-lib/trax_mem.h
user: login: erhankur
body: This is more like a design decision. While setting up the base structure, my initial strategy was to keep the hardware related definitions in `esp-stub-lib`  same as we avoid calling ROM functions directly from the stub code. We can change this later, but for now let’s leave it here. 
created_at: 2025-05-15T10:32:37Z
author_association: COLLABORATOR

PR comments:
user: login: github-actions[bot]
created_at: 2025-05-05T15:54:21Z
body: 
<!--
  0 failure: 
  0 warning: 
  1 messages
  1 markdown notices
  DangerID: danger-id-Danger;
-->



<table>
  <thead>
    <tr>
      <th width="50"></th>
      <th width="100%" data-danger-table="true">Messages</th>
    </tr>
  </thead>
  <tbody><tr>
      <td>:book:</td>
      <td>🎉 Good Job! All checks are passing!</td>
    </tr>
  </tbody>
</table>

👋 <strong>Hello erhankur</strong>, we appreciate your contribution to this project!<br><hr><details><summary>Click to see more instructions ...</summary><p><br>This automated output is generated by the <a href="https://github.com/espressif/shared-github-dangerjs">PR linter DangerJS</a>, which checks if your Pull Request meets the project's requirements and helps you fix potential issues.<br><br>DangerJS is triggered with each `push` event to a Pull Request and modify the contents of this comment.<br><br><strong>Please consider the following:</strong><br>- Danger mainly focuses on the PR structure and formatting and can't understand the meaning behind your code or changes.<br>- Danger is <strong>not a substitute for human code reviews</strong>; it's still important to request a code review from your colleagues.<br>- To manually <a href="https://github.com/espressif/esp-stub-lib/actions">retry these Danger checks</a>, please navigate to the <kbd>Actions</kbd> tab and re-run last Danger workflow.<br></p></details><details><summary>Review and merge process you can expect ...</summary><p><br><strong>We do welcome contributions in the form of bug reports, feature requests and pull requests.</strong><br><br><strong>1.</strong> An internal issue has been created for the PR, we assign it to the relevant engineer.<br><strong>2.</strong> They review the PR and either approve it or ask you for changes or clarifications.<br><strong>3.</strong> Once the GitHub PR is approved we do the final review, collect approvals from core owners and make sure all the automated tests are passing.<br>    - At this point we may do some adjustments to the proposed change, or extend it by adding tests or documentation.<br><strong>4.</strong> If the change is approved and passes the tests it is merged into the default branch.<br></p></details>

<p align="right">
  Generated by :no_entry_sign: <a href="https://danger.systems/js">dangerJS</a> against 3c8a527cb6ef1b5cf712dcc68a753776242e23aa
</p>

author_association: NONE
user: login: erhankur
created_at: 2025-05-05T15:55:59Z
body: @antmak structure is close to your suggestion now. `soc_utils.h` taken from the #9  PTAL
author_association: COLLABORATOR
user: login: antmak
created_at: 2025-05-07T02:09:30Z
body: LGTM, thank you Erhan!
author_association: COLLABORATOR