feat: Add initial chip structure

[Dzarda7]

Description

This PR creates initial chip structure. It tries to utilize a bit more data driven structure than esp-stub-lib as I believe there will not be big differences when using each peripheral, so if it is supported, common function can be used. Aim is to have as much common function as possible, but if it cannot be done, there can be per chip function in the structure.

I am open to suggestions, this was my first idea how this can be done compared to esp-stub-lib, I believe it is even a bit more comparable and better when it comes to avoiding #ifdefs, even though there has to be NULL checks for unsupported features.

Checklist

Before submitting a Pull Request, please ensure the following:

• [x ] 🚨 This PR does not introduce breaking changes.
• [x ] All CI checks (GH Actions) pass.
• [x ] Documentation is updated as needed.
• [x ] Tests are updated or added as necessary.
• [x ] Code is well-commented, especially in complex areas.
• [x ] Git history is clean — commits are squashed to the minimum necessary.

[github-actions]

	Messages
📖	🎉 Good Job! All checks are passing!

👋 Hello Dzarda7, we appreciate your contribution to this project!

---

Click to see more instructions ...

This automated output is generated by the PR linter DangerJS, which checks if your Pull Request meets the project's requirements and helps you fix potential issues.

DangerJS is triggered with each push event to a Pull Request and modify the contents of this comment.

Please consider the following:
- Danger mainly focuses on the PR structure and formatting and can't understand the meaning behind your code or changes.
- Danger is not a substitute for human code reviews; it's still important to request a code review from your colleagues.
- To manually retry these Danger checks, please navigate to the Actions tab and re-run last Danger workflow.

Review and merge process you can expect ...

We do welcome contributions in the form of bug reports, feature requests and pull requests.

1. An internal issue has been created for the PR, we assign it to the relevant engineer.
2. They review the PR and either approve it or ask you for changes or clarifications.
3. 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.
- At this point we may do some adjustments to the proposed change, or extend it by adding tests or documentation.
4. If the change is approved and passes the tests it is merged into the default branch.

Generated by 🚫 dangerJS against 6ad3c90

[dobairoland]

@Dzarda7 Very nice work, I like it!

[Copilot]

Pull Request Overview

This PR introduces a data-driven SoC structure to replace compile-time #ifdefs for handling differences between ESP chip variants. The new architecture uses a unified SoC information structure containing capabilities and peripheral definitions for each chip, aiming to provide better maintainability compared to the existing esp-stub-lib approach.

• Implements a unified SoC abstraction layer with chip-specific peripheral configurations
• Provides common functions for watchdog and UART operations that work across all chips
• Replaces conditional compilation with runtime NULL checks for unsupported features

Reviewed Changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
soc/include/soc.h	Main SoC structure definitions and accessor functions
soc/include/peripherals/*.h	Peripheral structure definitions for UART, USB, RTC, and system peripherals
soc/targets/*.c	Chip-specific SoC configuration files for all ESP variants
soc/common/*.c	Common peripheral functions using the unified SoC structure
soc/CMakeLists.txt	Build configuration for SoC library
CMakeLists.txt	Integration of SoC library into main build

Comments suppressed due to low confidence (1)

soc/targets/esp32s3.c:1

• The esp32s3_capabilities structure is missing the config_efuse_spi field initialization that appears in other chip configurations. This inconsistency could lead to undefined behavior.

/*

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[erhankur]

@dobairoland Do you still plan to improve esp-stub-lib with the common features such as flash support? After this structure it seems to me you changed your direction. Am I wrong?

[Dzarda7]

@erhankur we do. There are just things that are different across chips and have no use for others to be in esp-stub-lib. I have to say, I probably missed some communication about what should be in esp-stub-lib, so I considered only flashing and ROM functions (and UART? But not sure what plan is with that). So I might have created more dedinitions than necessary. Sorry for confusion.

[dobairoland]

@erhankur I'm sorry for the misunderstanding. We are not deviating from the original plan.

[erhankur]

@Dzarda7 @dobairoland Thanks. Good to know. Some notes:

• OpenOCD will also need rtc functions to boost clock frequency. @Dzarda7 You can see the OpenOCD requirements here. https://gitlab.espressif.cn:6688/idf/openocd-esp32/-/wikis/Flasher-Stub-Requirements#requirements-for-the-new-openocd-flasher-stub
• esp-stub-lib has the same register access macros in the private include folder. We can make them public.
• Regarding the structure of esp-stub-lib: to me, it still primitive and can be reorganized in the way you think will be easier to maintain. Currently, #ifdef makes our job much simpler, but it’s not the kind of tool we want to distribute. On the other hand, target based implementations require duplicated code. We also have a common folder for the generic implementations. By combining the changes in this PR, we can make that common part easier to maintain.

[jedi7]

From an architectural standpoint, I think it would be better to avoid exposing internal registers and hardware details to the common stub. Instead, we could define a set of function pointers for essential operations, like init_uart(), read_byte, etc.

This approach abstracts the target-specific implementation. The initialization style and register layouts are likely to change across different platforms, and encapsulating them within the target-specific file would make the common code more robust and easier to maintain.

[Dzarda7]

Yes @jedi7, ideal plan is to expose these structures only to the functions in common, but we will see how it goes.

[Copilot]

Pull Request Overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Dzarda7]

@dobairoland @jedi7 @radimkarnis PTAL again. I removed functions that will be used in esp-stub-lib, also helper macros will be taken from esp-stub-lib. As @fhrbata pointed out it might be better use structures instead of typedef for better readability. In this case I am okay with both variants.

[jedi7]

LGTM thanks!

[dobairoland]

LGTM. But please check with @erhankur before merging so we won't go against the principles of esp-stub-lib.

[Dzarda7]

I will modify this PR to contain bare minimum structure and keep it open as a draft (or just in a branch) as we might find use for it, but for now it is not necessary and all chip specific code will be in esp-stub-lib. Merge conflict should not be an issue as this is separate from the rest of the code.