Skip to content

add interface operating ESP32 internal flash - #448

Open
jinwjinl wants to merge 6 commits into
vivoblueos:mainfrom
jinwjinl:esp32c3-internal-flash
Open

add interface operating ESP32 internal flash#448
jinwjinl wants to merge 6 commits into
vivoblueos:mainfrom
jinwjinl:esp32c3-internal-flash

Conversation

@jinwjinl

@jinwjinl jinwjinl commented Aug 17, 2026

Copy link
Copy Markdown
Contributor

Description

This branch adds ESP32-C3 on-chip Flash access and executable XIP mapping support. A reserved Flash region is exposed as /dev/esp32-flash0, allowing userspace loaders to erase, read, write, map, and unmap executable images without embedding ELF or image-management logic in the kernel.

Main changes

Internal Flash driver

  • Adds an ESP32-C3 internal Flash driver based on the ROM SPI Flash APIs.
  • Supports bounded read, aligned programming, and sector erase operations.
  • Splits unaligned writes into page-sized operations and preserves unaffected bytes.
  • Serializes Flash operations to prevent concurrent access.
  • Validates alignment, capacity, protected ranges, and integer overflow.

Device registration

  • Registers the reserved internal Flash region as the misc device:

    /dev/esp32-flash0

  • Provides standard device operations for reading, writing, querying capacity, and synchronization.

  • Adds versioned ioctl requests for:

    • erasing a Flash range;
    • mapping an executable image;
    • unmapping an executable image;
    • querying the safe DRAM boundary for loadable applications.

XIP mapping

  • Adds ESP32-C3 Flash MMU mapping support.
  • Maps the reserved physical Flash region into the corresponding IROM and DROM address spaces.
  • Handles 64-KiB MMU page alignment and multi-page mappings.
  • Invalidates the instruction cache and executes fence.i after mapping changes.
  • Tracks the active mapping and rejects concurrent or stale mapping operations.

Configuration

The following parameters are defined through Kconfig:

  • ESP32_LOADABLE_REGION_BASE
  • ESP32_LOADABLE_REGION_SIZE
  • ESP32_FLASH_READ_CHUNK_SIZE

The default loadable region is:

Physical Flash offset: 0x00200000
Size:                  0x00100000
Mapped IROM address:   0x42200000

Board integration

  • Includes the ESP32-C3 ROM linker definitions required by the Flash ROM APIs.
  • Initializes the internal Flash driver during ESP32-C3 boot.
  • Registers /dev/esp32-flash0 before VFS initialization.
  • Keeps image metadata, ELF parsing, verification, and recovery policies in userspace.

@jinwjinl

jinwjinl commented Aug 17, 2026

Copy link
Copy Markdown
Contributor Author

build_prs

@github-actions

github-actions Bot commented Aug 17, 2026

Copy link
Copy Markdown

Job is started, see https://github.com/vivoblueos/kernel/actions/runs/31996190597.

@github-actions

github-actions Bot commented Aug 17, 2026

Copy link
Copy Markdown

❌ Job failed. Failed jobs: check_format (failure), build_and_check_boards (failure), see https://github.com/vivoblueos/kernel/actions/runs/31996190597.

@jinwjinl

jinwjinl commented Aug 17, 2026

Copy link
Copy Markdown
Contributor Author

build_prs

@github-actions

github-actions Bot commented Aug 17, 2026

Copy link
Copy Markdown

Job is started, see https://github.com/vivoblueos/kernel/actions/runs/31997822155.

@github-actions

github-actions Bot commented Aug 17, 2026

Copy link
Copy Markdown

❌ Job failed. Failed jobs: build_and_check_boards (failure), see https://github.com/vivoblueos/kernel/actions/runs/31997822155.

@jinwjinl

jinwjinl commented Aug 17, 2026

Copy link
Copy Markdown
Contributor Author

build_prs

@github-actions

github-actions Bot commented Aug 17, 2026

Copy link
Copy Markdown

Job is started, see https://github.com/vivoblueos/kernel/actions/runs/32010087294.

@github-actions

github-actions Bot commented Aug 17, 2026

Copy link
Copy Markdown

❌ Job failed. Failed jobs: build_and_check_boards (failure), see https://github.com/vivoblueos/kernel/actions/runs/32010087294.

@jinwjinl
jinwjinl force-pushed the esp32c3-internal-flash branch from ef2e172 to dc6ebc8 Compare August 17, 2026 08:40
@jinwjinl

jinwjinl commented Aug 17, 2026

Copy link
Copy Markdown
Contributor Author

build_prs

@github-actions

github-actions Bot commented Aug 17, 2026

Copy link
Copy Markdown

Job is started, see https://github.com/vivoblueos/kernel/actions/runs/32011541569.

@github-actions

github-actions Bot commented Aug 17, 2026

Copy link
Copy Markdown

✅ All jobs completed successfully, see https://github.com/vivoblueos/kernel/actions/runs/32011541569.

xuchang-vivo
xuchang-vivo reviewed Aug 17, 2026
View reviewed changes
Comment thread kernel/src/drivers/flash/mod.rs
mod esp32_rom;

#[cfg(soc_esp32c3)]
pub(crate) mod internal_flash;

@xuchang-vivo xuchang-vivo Aug 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

prefix esp32

xuchang-vivo
xuchang-vivo reviewed Aug 17, 2026
View reviewed changes
Comment thread kernel/src/drivers/flash/mod.rs
#[cfg(soc_esp32c3)]
mod esp32_rom;

#[cfg(soc_esp32c3)]

@xuchang-vivo xuchang-vivo Aug 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do not use soc_esp32c3; instead, use a more generic gate, such as cfg(esp32_internal_flash).

@jinwjinl
jinwjinl force-pushed the esp32c3-internal-flash branch from dc6ebc8 to 8bf9443 Compare August 26, 2026 11:44
jinwjinl and others added 6 commits August 27, 2026 16:20
@jinwjinl
add interface operating ESP32 internal flash
4d2c3ba
@jinwjinl
fix flash module formatting
b25b971
@jinwjinl
test:
811be09
@jinwjinl @claude
flash: tune ESP32-C3 internal flash driver
8a3a835 
internal_flash: cross-erase-block write loop + bounded wait.
boards/seeed_xiao_esp32c3: board-level flash wiring.
boot: init internal flash + esp32-flash0 device before init_vfs
  (TODO: move this init into the board, out of boot).
BUILD.gn: add mipidsi dep for the board LCD stack.

(spi_flash_cmd NOR-flash wait_busy tuning moved to a separate branch.)

Co-Authored-By: Claude <[email protected]>
@jinwjinl
Add Drom and change erase logic to accelerate velocity of writing.
118bf1a
@jinwjinl
change order of internal flash init
5d3939f
@jinwjinl
jinwjinl force-pushed the esp32c3-internal-flash branch from 8bf9443 to 5d3939f Compare August 27, 2026 08:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer
@xuchang-vivo xuchang-vivo xuchang-vivo left review comments
Reviewers whose approvals may not affect merge requirements

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@jinwjinl @xuchang-vivo