Skip to content

Sneakily document size of dram2_uninit #4360

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Sneakily document size of dram2_uninit #4360

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3c94d76
Make the memory map less special
bugadani Oct 15, 2025
9d13ce0
Add dram2_uninit to metadata
bugadani Oct 15, 2025
4997631
Make ram(reclaimed) depend on the idf bootloader
bugadani Oct 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 9 additions & 7 deletions esp-bootloader-esp-idf/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ cfg-if = "1"
defmt = { version = "1.0.1", optional = true }
document-features = "0.2"
esp-config = { version = "0.6.0", path = "../esp-config" }
esp-hal-procmacros = { version = "0.20.0", path = "../esp-hal-procmacros", features = ["__esp_idf_bootloader"] }
esp-metadata-generated = { version = "0.2.0", path = "../esp-metadata-generated" }
esp-rom-sys = { version = "0.1.2", path = "../esp-rom-sys", optional = true }
embedded-storage = "0.3.1"
log-04 = { package = "log", version = "0.4", optional = true }
Expand Down Expand Up @@ -64,19 +66,19 @@ std = ["dep:crc", "dep:md-5"]
#! One of the following features must be enabled to select the target chip:

##
esp32c2 = ["esp-rom-sys/esp32c2"]
esp32c2 = ["esp-rom-sys/esp32c2", "esp-metadata-generated/esp32c2"]
##
esp32c3 = ["esp-rom-sys/esp32c3"]
esp32c3 = ["esp-rom-sys/esp32c3", "esp-metadata-generated/esp32c3"]
##
esp32c6 = ["esp-rom-sys/esp32c6"]
esp32c6 = ["esp-rom-sys/esp32c6", "esp-metadata-generated/esp32c6"]
##
esp32h2 = ["esp-rom-sys/esp32h2"]
esp32h2 = ["esp-rom-sys/esp32h2", "esp-metadata-generated/esp32h2"]
##
esp32 = ["esp-rom-sys/esp32"]
esp32 = ["esp-rom-sys/esp32", "esp-metadata-generated/esp32"]
##
esp32s2 = ["esp-rom-sys/esp32s2"]
esp32s2 = ["esp-rom-sys/esp32s2", "esp-metadata-generated/esp32s2"]
##
esp32s3 = ["esp-rom-sys/esp32s3"]
esp32s3 = ["esp-rom-sys/esp32s3", "esp-metadata-generated/esp32s3"]

# "md-5" is hidden behind `std` feature and `cargo machete` incorrectly marks it as unused.
[package.metadata.cargo-machete]
Expand Down
10 changes: 10 additions & 0 deletions esp-bootloader-esp-idf/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,16 @@
//! }
//! ```
//!
//! ## Reclaimed memory
//!
//! After the bootloader has started the application, the `.dram2_uninit` region becomes available
//! for use. This region can be used for dynamic memory allocation or other purposes, but the data
//! placed there cannot be initialized (i.e. it must be `MaybeUninit<T>`). For convenience, you can
//! use the `#[esp_hal::ram(reclaimed)]` attribute, which will also check that the variable can be
//! placed in the reclaimed memory.
#![doc = ""]
#![cfg_attr(not(feature = "std"), doc = concat!("For ", esp_metadata_generated::chip!(), " the size of the reclaimed memory is ", esp_metadata_generated::memory_range!(size as str, "DRAM2_UNINIT")," bytes."))]
#![doc = ""]
//! ## Additional configuration
//!
//! We've exposed some configuration options that don't fit into cargo
Expand Down
3 changes: 3 additions & 0 deletions esp-hal-procmacros/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,3 +47,6 @@ is-lp-core = []
## Provide an `#[entry]` macro for running applications on the ESP32-S2/S3's
## ULP core.
is-ulp-core = []

# Enables `ram(reclaimed)`
__esp_idf_bootloader = []
13 changes: 12 additions & 1 deletion esp-hal-procmacros/src/ram.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,18 @@ pub fn ram(args: TokenStream, input: TokenStream) -> TokenStream {
.into();
};
let arg = match ident {
i if i == "reclaimed" => &mut dram2_uninit,
i if i == "reclaimed" => {
if !cfg!(feature = "__esp_idf_bootloader") {
return syn::Error::new(
ident.span(),
"`ram(reclaimed)` requires the esp-idf bootloader",
)
.into_compile_error()
.into();
}

&mut dram2_uninit
}
_ => {
return syn::Error::new(
ident.span(),
Expand Down
2 changes: 1 addition & 1 deletion esp-hal/ld/esp32/memory.x
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ MEMORY
reserved_rom_stack_pro : ORIGIN = 0x3ffe1320, len = 11264
reserved_rom_stack_app : ORIGIN = 0x3ffe5230, len = 11264

dram2_seg : ORIGIN = 0x3ffe7e30, len = 98767 /* the rest of DRAM after the rom data segments and rom stacks in the middle */
dram2_seg : ORIGIN = 0x3ffe7e30, len = 98768 /* the rest of DRAM after the rom data segments and rom stacks in the middle */
Copy link
Contributor Author

Choose a reason for hiding this comment

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

Off by one, new length now places the end at exactly 0x40000000


/* external flash
The 0x20 offset is a convenience for the app binary image generation.
Expand Down
44 changes: 30 additions & 14 deletions esp-metadata-generated/src/_build_script_utils.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -270,6 +270,8 @@ impl Chip {
"soc_rc_fast_clk_default_is_set",
"soc_rc_slow_clock=\"150000\"",
"soc_rc_slow_clock_is_set",
"has_dram_region",
"has_dram2_uninit_region",
"soc_has_multiple_xtal_options",
"aes_endianness_configurable",
"gpio_has_bank_1",
Expand Down Expand Up @@ -299,7 +301,6 @@ impl Chip {
"uart_ram_size=\"128\"",
"bt_controller=\"btdm\"",
"phy_combo_module",
"has_dram_region",
],
cfgs: &[
"cargo:rustc-cfg=esp32",
Expand Down Expand Up @@ -432,6 +433,8 @@ impl Chip {
"cargo:rustc-cfg=soc_rc_fast_clk_default_is_set",
"cargo:rustc-cfg=soc_rc_slow_clock=\"150000\"",
"cargo:rustc-cfg=soc_rc_slow_clock_is_set",
"cargo:rustc-cfg=has_dram_region",
"cargo:rustc-cfg=has_dram2_uninit_region",
"cargo:rustc-cfg=soc_has_multiple_xtal_options",
"cargo:rustc-cfg=aes_endianness_configurable",
"cargo:rustc-cfg=gpio_has_bank_1",
Expand Down Expand Up @@ -461,7 +464,6 @@ impl Chip {
"cargo:rustc-cfg=uart_ram_size=\"128\"",
"cargo:rustc-cfg=bt_controller=\"btdm\"",
"cargo:rustc-cfg=phy_combo_module",
"cargo:rustc-cfg=has_dram_region",
],
},
Self::Esp32c2 => Config {
Expand Down Expand Up @@ -557,6 +559,8 @@ impl Chip {
"soc_rc_fast_clk_default_is_set",
"soc_rc_slow_clock=\"136000\"",
"soc_rc_slow_clock_is_set",
"has_dram_region",
"has_dram2_uninit_region",
"soc_has_multiple_xtal_options",
"assist_debug_has_sp_monitor",
"gpio_gpio_function=\"1\"",
Expand Down Expand Up @@ -586,7 +590,6 @@ impl Chip {
"uart_ram_size=\"128\"",
"bt_controller=\"npl\"",
"phy_combo_module",
"has_dram_region",
],
cfgs: &[
"cargo:rustc-cfg=esp32c2",
Expand Down Expand Up @@ -678,6 +681,8 @@ impl Chip {
"cargo:rustc-cfg=soc_rc_fast_clk_default_is_set",
"cargo:rustc-cfg=soc_rc_slow_clock=\"136000\"",
"cargo:rustc-cfg=soc_rc_slow_clock_is_set",
"cargo:rustc-cfg=has_dram_region",
"cargo:rustc-cfg=has_dram2_uninit_region",
"cargo:rustc-cfg=soc_has_multiple_xtal_options",
"cargo:rustc-cfg=assist_debug_has_sp_monitor",
"cargo:rustc-cfg=gpio_gpio_function=\"1\"",
Expand Down Expand Up @@ -707,7 +712,6 @@ impl Chip {
"cargo:rustc-cfg=uart_ram_size=\"128\"",
"cargo:rustc-cfg=bt_controller=\"npl\"",
"cargo:rustc-cfg=phy_combo_module",
"cargo:rustc-cfg=has_dram_region",
],
},
Self::Esp32c3 => Config {
Expand Down Expand Up @@ -819,6 +823,8 @@ impl Chip {
"soc_rc_fast_clk_default_is_set",
"soc_rc_slow_clock=\"136000\"",
"soc_rc_slow_clock_is_set",
"has_dram_region",
"has_dram2_uninit_region",
"soc_xtal_frequency=\"40\"",
"aes_dma",
"aes_dma_mode_ecb",
Expand Down Expand Up @@ -873,7 +879,6 @@ impl Chip {
"phy_combo_module",
"phy_backed_up_digital_register_count=\"21\"",
"phy_backed_up_digital_register_count_is_set",
"has_dram_region",
],
cfgs: &[
"cargo:rustc-cfg=esp32c3",
Expand Down Expand Up @@ -981,6 +986,8 @@ impl Chip {
"cargo:rustc-cfg=soc_rc_fast_clk_default_is_set",
"cargo:rustc-cfg=soc_rc_slow_clock=\"136000\"",
"cargo:rustc-cfg=soc_rc_slow_clock_is_set",
"cargo:rustc-cfg=has_dram_region",
"cargo:rustc-cfg=has_dram2_uninit_region",
"cargo:rustc-cfg=soc_xtal_frequency=\"40\"",
"cargo:rustc-cfg=aes_dma",
"cargo:rustc-cfg=aes_dma_mode_ecb",
Expand Down Expand Up @@ -1035,7 +1042,6 @@ impl Chip {
"cargo:rustc-cfg=phy_combo_module",
"cargo:rustc-cfg=phy_backed_up_digital_register_count=\"21\"",
"cargo:rustc-cfg=phy_backed_up_digital_register_count_is_set",
"cargo:rustc-cfg=has_dram_region",
],
},
Self::Esp32c6 => Config {
Expand Down Expand Up @@ -1199,6 +1205,8 @@ impl Chip {
"soc_rc_fast_clk_default_is_set",
"soc_rc_slow_clock=\"136000\"",
"soc_rc_slow_clock_is_set",
"has_dram_region",
"has_dram2_uninit_region",
"soc_xtal_frequency=\"40\"",
"aes_dma",
"aes_dma_mode_ecb",
Expand Down Expand Up @@ -1258,7 +1266,6 @@ impl Chip {
"wifi_has_wifi6",
"bt_controller=\"npl\"",
"phy_combo_module",
"has_dram_region",
],
cfgs: &[
"cargo:rustc-cfg=esp32c6",
Expand Down Expand Up @@ -1418,6 +1425,8 @@ impl Chip {
"cargo:rustc-cfg=soc_rc_fast_clk_default_is_set",
"cargo:rustc-cfg=soc_rc_slow_clock=\"136000\"",
"cargo:rustc-cfg=soc_rc_slow_clock_is_set",
"cargo:rustc-cfg=has_dram_region",
"cargo:rustc-cfg=has_dram2_uninit_region",
"cargo:rustc-cfg=soc_xtal_frequency=\"40\"",
"cargo:rustc-cfg=aes_dma",
"cargo:rustc-cfg=aes_dma_mode_ecb",
Expand Down Expand Up @@ -1477,7 +1486,6 @@ impl Chip {
"cargo:rustc-cfg=wifi_has_wifi6",
"cargo:rustc-cfg=bt_controller=\"npl\"",
"cargo:rustc-cfg=phy_combo_module",
"cargo:rustc-cfg=has_dram_region",
],
},
Self::Esp32h2 => Config {
Expand Down Expand Up @@ -1618,6 +1626,8 @@ impl Chip {
"soc_rc_fast_clk_default_is_set",
"soc_rc_slow_clock=\"136000\"",
"soc_rc_slow_clock_is_set",
"has_dram_region",
"has_dram2_uninit_region",
"soc_xtal_frequency=\"32\"",
"aes_dma",
"aes_dma_mode_ecb",
Expand Down Expand Up @@ -1671,7 +1681,6 @@ impl Chip {
"uart_ram_size=\"128\"",
"uart_peripheral_controls_mem_clk",
"bt_controller=\"npl\"",
"has_dram_region",
],
cfgs: &[
"cargo:rustc-cfg=esp32h2",
Expand Down Expand Up @@ -1808,6 +1817,8 @@ impl Chip {
"cargo:rustc-cfg=soc_rc_fast_clk_default_is_set",
"cargo:rustc-cfg=soc_rc_slow_clock=\"136000\"",
"cargo:rustc-cfg=soc_rc_slow_clock_is_set",
"cargo:rustc-cfg=has_dram_region",
"cargo:rustc-cfg=has_dram2_uninit_region",
"cargo:rustc-cfg=soc_xtal_frequency=\"32\"",
"cargo:rustc-cfg=aes_dma",
"cargo:rustc-cfg=aes_dma_mode_ecb",
Expand Down Expand Up @@ -1861,7 +1872,6 @@ impl Chip {
"cargo:rustc-cfg=uart_ram_size=\"128\"",
"cargo:rustc-cfg=uart_peripheral_controls_mem_clk",
"cargo:rustc-cfg=bt_controller=\"npl\"",
"cargo:rustc-cfg=has_dram_region",
],
},
Self::Esp32s2 => Config {
Expand Down Expand Up @@ -1997,6 +2007,8 @@ impl Chip {
"soc_rc_fast_clk_default_is_set",
"soc_rc_slow_clock=\"90000\"",
"soc_rc_slow_clock_is_set",
"has_dram_region",
"has_dram2_uninit_region",
"soc_xtal_frequency=\"40\"",
"aes_dma",
"aes_dma_mode_ecb",
Expand Down Expand Up @@ -2043,7 +2055,6 @@ impl Chip {
"timergroup_default_clock_source=\"0\"",
"timergroup_default_clock_source_is_set",
"uart_ram_size=\"128\"",
"has_dram_region",
],
cfgs: &[
"cargo:rustc-cfg=esp32s2",
Expand Down Expand Up @@ -2175,6 +2186,8 @@ impl Chip {
"cargo:rustc-cfg=soc_rc_fast_clk_default_is_set",
"cargo:rustc-cfg=soc_rc_slow_clock=\"90000\"",
"cargo:rustc-cfg=soc_rc_slow_clock_is_set",
"cargo:rustc-cfg=has_dram_region",
"cargo:rustc-cfg=has_dram2_uninit_region",
"cargo:rustc-cfg=soc_xtal_frequency=\"40\"",
"cargo:rustc-cfg=aes_dma",
"cargo:rustc-cfg=aes_dma_mode_ecb",
Expand Down Expand Up @@ -2221,7 +2234,6 @@ impl Chip {
"cargo:rustc-cfg=timergroup_default_clock_source=\"0\"",
"cargo:rustc-cfg=timergroup_default_clock_source_is_set",
"cargo:rustc-cfg=uart_ram_size=\"128\"",
"cargo:rustc-cfg=has_dram_region",
],
},
Self::Esp32s3 => Config {
Expand Down Expand Up @@ -2370,6 +2382,8 @@ impl Chip {
"soc_rc_fast_clk_default_is_set",
"soc_rc_slow_clock=\"136000\"",
"soc_rc_slow_clock_is_set",
"has_dram_region",
"has_dram2_uninit_region",
"soc_xtal_frequency=\"40\"",
"aes_dma",
"aes_dma_mode_ecb",
Expand Down Expand Up @@ -2425,7 +2439,6 @@ impl Chip {
"phy_combo_module",
"phy_backed_up_digital_register_count=\"21\"",
"phy_backed_up_digital_register_count_is_set",
"has_dram_region",
],
cfgs: &[
"cargo:rustc-cfg=esp32s3",
Expand Down Expand Up @@ -2570,6 +2583,8 @@ impl Chip {
"cargo:rustc-cfg=soc_rc_fast_clk_default_is_set",
"cargo:rustc-cfg=soc_rc_slow_clock=\"136000\"",
"cargo:rustc-cfg=soc_rc_slow_clock_is_set",
"cargo:rustc-cfg=has_dram_region",
"cargo:rustc-cfg=has_dram2_uninit_region",
"cargo:rustc-cfg=soc_xtal_frequency=\"40\"",
"cargo:rustc-cfg=aes_dma",
"cargo:rustc-cfg=aes_dma_mode_ecb",
Expand Down Expand Up @@ -2625,7 +2640,6 @@ impl Chip {
"cargo:rustc-cfg=phy_combo_module",
"cargo:rustc-cfg=phy_backed_up_digital_register_count=\"21\"",
"cargo:rustc-cfg=phy_backed_up_digital_register_count_is_set",
"cargo:rustc-cfg=has_dram_region",
],
},
}
Expand Down Expand Up @@ -2773,6 +2787,8 @@ pub fn emit_check_cfg_directives() {
println!("cargo:rustc-check-cfg=cfg(soc_ref_tick_hz_is_set)");
println!("cargo:rustc-check-cfg=cfg(soc_rc_fast_clk_default_is_set)");
println!("cargo:rustc-check-cfg=cfg(soc_rc_slow_clock_is_set)");
println!("cargo:rustc-check-cfg=cfg(has_dram_region)");
println!("cargo:rustc-check-cfg=cfg(has_dram2_uninit_region)");
println!("cargo:rustc-check-cfg=cfg(soc_has_multiple_xtal_options)");
println!("cargo:rustc-check-cfg=cfg(aes_endianness_configurable)");
println!("cargo:rustc-check-cfg=cfg(gpio_has_bank_1)");
Expand Down
25 changes: 17 additions & 8 deletions esp-metadata-generated/src/_generated_esp32.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -262,14 +262,6 @@ macro_rules! property {
true
};
}
/// Macro to get the address range of the given memory region.
#[macro_export]
#[cfg_attr(docsrs, doc(cfg(feature = "_device-selected")))]
macro_rules! memory_range {
("DRAM") => {
1073405952..1073741824
};
}
#[macro_export]
#[cfg_attr(docsrs, doc(cfg(feature = "_device-selected")))]
macro_rules! for_each_soc_xtal_options {
Expand Down Expand Up @@ -620,6 +612,23 @@ macro_rules! implement_peripheral_clocks {
}
};
}
/// Macro to get the address range of the given memory region.
#[macro_export]
#[cfg_attr(docsrs, doc(cfg(feature = "_device-selected")))]
macro_rules! memory_range {
("DRAM") => {
1073405952..1073741824
};
(size as str, "DRAM") => {
"335872"
};
("DRAM2_UNINIT") => {
1073643056..1073741824
};
(size as str, "DRAM2_UNINIT") => {
"98768"
};
}
#[macro_export]
#[cfg_attr(docsrs, doc(cfg(feature = "_device-selected")))]
macro_rules! for_each_aes_key_length {
Expand Down
Loading
Loading