Merge pull request #32 from espressif/dependency_inversion

Dependency inverted as common to target.

Author: erhankur

CMakeLists.txt

@@ -7,11 +7,13 @@ if(NOT ESP_STUB_LIB)
 endif()
 
 if(NOT STUB_COMMAND)
-    set(ESP_TARGET_LIB ${ESP_TARGET})
+    set(ESP_BASE_LIB base)
     set(ESP_COMMON_LIB common)
+    set(ESP_TARGET_LIB ${ESP_TARGET})
 else()
-    set(ESP_TARGET_LIB ${ESP_TARGET}-${STUB_COMMAND})
+    set(ESP_BASE_LIB base-${STUB_COMMAND})
     set(ESP_COMMON_LIB common-${STUB_COMMAND})
+    set(ESP_TARGET_LIB ${ESP_TARGET}-${STUB_COMMAND})
 endif()
 
 set(srcs
@@ -47,8 +49,20 @@ include_directories(include/esp-stub-lib)
 # STUB_COMPILE_DEFS is optional definitions coming from the parent CMakeLists.txt
 add_compile_definitions(${STUB_COMPILE_DEFS})
 
+# Three-layer architecture:
+# - entry: Main stub code (src/)
+# - common: Generic implementations using base headers + target's soc.h  + (weak functions)
+# - target: Target-specific code + soc.h + overrides (weak functions)
+# - base: Interface headers (target/*.h, private/*.h) - serves to common and target
+#
+# Dependency flow: entry → common → target
+#                            ↓         ↓
+#                           base      base
+
+add_subdirectory(src/target/base ${ESP_BASE_LIB})
 add_subdirectory(src/target/${ESP_TARGET} ${ESP_TARGET_LIB})
 add_subdirectory(src/target/common ${ESP_COMMON_LIB})
-target_link_libraries(${ESP_TARGET_LIB} PRIVATE ${ESP_COMMON_LIB})
 
-target_link_libraries(${ESP_STUB_LIB} PUBLIC ${ESP_TARGET_LIB} ${ESP_COMMON_LIB})
+target_link_libraries(${ESP_TARGET_LIB} PUBLIC ${ESP_BASE_LIB})
+target_link_libraries(${ESP_COMMON_LIB} PUBLIC ${ESP_BASE_LIB} ${ESP_TARGET_LIB})
+target_link_libraries(${ESP_STUB_LIB} PUBLIC ${ESP_COMMON_LIB})

README.md

@@ -16,6 +16,7 @@ This project is experimental and not yet ready for production use.
 - ESP32-C6
 - ESP32-C61
 - ESP32-H2
+- ESP32-H4
 - ESP32-P4
 
 ## How to use
@@ -30,6 +31,71 @@ A complete example project is provided in the [example](example/) directory. It
 
 See the [example README](example/README.md) for build instructions.
 
+## Project Structure
+
+The library uses a three-layer architecture to eliminate circular dependencies and maximize code reuse:
+
+```
+esp-stub-lib/
+├── include/esp-stub-lib/         # Public API - used by library clients
+│   ├── flash.h                   # (stub_lib_flash_init, stub_lib_flash_read, etc.)
+│   ├── log.h
+│   ├── mem_utils.h
+│   └── ...
+│
+├── src/                          # Implementation layer
+│   ├── flash.c
+│   ├── mem_utils.c
+│   └── ...
+│
+└── src/target/                   # Internal abstraction layers
+    ├── base/                     # Interface layer (headers only)
+    │   └── include/
+    │       ├── target/           # Internal API between common/target layers
+    │       └── private/          # Internal ROM/hardware details
+    │
+    ├── common/                   # Generic implementations
+    │   ├── src/                  # Weak functions using SOC_* macros
+    │   │   ├── mem_utils.c       # Default implementations
+    │   │   ├── uart.c
+    │   │   └── flash.c
+    │   └── CMakeLists.txt
+    │
+    └── esp32*/                   # Target-specific implementations
+        ├── include/
+        │   └── soc/
+        │       └── soc.h         # SOC_* macro definitions
+        ├── src/
+        │   ├── mem_utils.c       # Strong overrides (optional)
+        │   ├── uart.c
+        │   └── ...
+        └── CMakeLists.txt
+```
+
+**Dependency Flow:**
+```
+Public API (include/esp-stub-lib/)  ← Library clients use this
+    ↓
+Implementation (src/)
+    ↓
+Common (generic implementations with weak functions)
+    ↓
+Target (overridden weak functions for target-specific implementations)
+    ↓
+Base (interface headers only - serves both common and target)
+```
+
+**Layer Purposes:**
+- **include/esp-stub-lib/**: Public API for library clients (e.g., `stub_lib_flash_init()`)
+- **src/**: Implementation layer that uses the target abstraction below
+- **base/**: Internal interface layer - shared by both common and target implementations
+  - `target/`: Internal API between common/target layers (e.g., `stub_target_flash_init()`)
+  - `private/`: Internal headers to be used from target implementations. (e.g., `esp_rom_spiflash_read()`)
+- **common/**: Provides reusable weak implementations that work across targets
+- **target/esp32***: Target-specific constants (`soc.h`) and strong function overrides when needed
+
+> **Note**: Library clients should only include headers from `include/esp-stub-lib/`. The `src/target/base/` folder (both `target/` and `private/`) contains internal implementation details used by the library itself.
+
 ## Contributing
 
 Please install the [pre-commit](https://pre-commit.com/) hooks to ensure that your commits are properly formatted:

src/target/base/CMakeLists.txt

@@ -0,0 +1,6 @@
+# Base layer: Interface library with headers only (no implementation)
+add_library(${ESP_BASE_LIB} INTERFACE)
+
+target_include_directories(${ESP_BASE_LIB}
+    INTERFACE include
+)