Expand description
§(Generated) metadata for Espressif MCUs.
This crate provides properties that are specific to various Espressif microcontrollers, and provides macros to work with peripherals, pins, and various other parts of the chips.
This crate can be used both in firmware, as well as in build scripts, but the usage is different.
§Usage in build scripts
To use the Chip
enum, add the crate to your Cargo.toml
build
dependencies, with the build-script
feature:
[build-dependencies]
esp-metadata-generated = { version = "...", features = ["build-script"] }
§Usage in firmware
To use the various macros, add the crate to your Cargo.toml
dependencies.
A device-specific feature needs to be enabled in order to use the crate, usually
picked by the user:
[dependencies]
esp-metadata-generated = { version = "..." }
# ...
[features]
esp32 = ["esp-metadata-generated/esp32"]
esp32c2 = ["esp-metadata-generated/esp32c2"]
# ...
§for_each
macros
The basic syntax of this macro looks like a macro definition with two distinct syntax options:
for_each_peripherals! {
// Individual matcher, invoked separately for each peripheral instance
( <individual match syntax> ) => { /* some code */ };
// Repeated matcher, invoked once with all peripheral instances
( all $( (<individual match syntax>) ),* ) => { /* some code */ };
}
You can specify any number of matchers in the same invocation.
The way code is generated, you will need to use the full
return
syntax to return any values from code generated with these macros.
§Using the individual matcher
In this use case, each item’s data is individually passed through the macro. This can be used to generate code for each item separately, allowing specializing the implementation where needed.
for_each_gpio! {
// Example data: `(0, GPIO0 (_5 => EMAC_TX_CLK) (_1 => CLK_OUT1 _5 => EMAC_TX_CLK) ([Input] [Output]))`
($n:literal, $gpio:ident ($($digital_input_function:ident => $digital_input_signal:ident)*) ($($digital_output_function:ident => $digital_output_signal:ident)*) ($($pin_attribute:ident)*)) => { /* some code */ };
// You can create matchers with data filled in. This example will specifically match GPIO2
($n:literal, GPIO2 $input_af:tt $output_af:tt $attributes:tt) => { /* Additional case only for GPIO2 */ };
}
Different macros can have multiple different syntax options for their individual matchers, usually to provide more detailed information, while preserving simpler syntax for more basic use cases. Consult each macro’s documentation for available options.
§Repeated matcher
With this option, all data is passed through the macro all at once. This form can be used to, for example, generate struct fields. If the macro has multiple individual matcher options, there are separate repeated matchers for each of the options.
To use this option, start the match pattern with the name of the individual matcher option. When
there is only a single individual matcher option, its repeated matcher is named all
unless
otherwise specified by the macro.
// Example usage to create a struct containing all GPIOs:
for_each_gpio! {
(all $( ($n:literal, $gpio:ident $_af_ins:tt $_af_outs:tt $_attrs:tt) ),*) => {
struct Gpios {
$(
#[doc = concat!(" The ", stringify!($n), "th GPIO pin")]
pub $gpio: Gpio<$n>,
)*
}
};
}
Macros§
- chip
_device-selected
- The name of the chip as
&str
- define_
io_ mux_ reg _device-selected
- Defines and implements the
io_mux_reg
function. - define_
io_ mux_ signals _device-selected
- Defines the
InputSignal
andOutputSignal
enums. - for_
each_ analog_ function _device-selected
- This macro can be used to generate code for each analog function of each GPIO.
- for_
each_ gpio _device-selected
- This macro can be used to generate code for each
GPIOn
instance. - for_
each_ i2c_ master _device-selected
- This macro can be used to generate code for each peripheral instance of the I2C master driver.
- for_
each_ lp_ function _device-selected
- This macro can be used to generate code for each LP/RTC function of each GPIO.
- for_
each_ peripheral _device-selected
- for_
each_ spi_ master _device-selected
- This macro can be used to generate code for each peripheral instance of the SPI master driver.
- for_
each_ spi_ slave _device-selected
- This macro can be used to generate code for each peripheral instance of the SPI slave driver.
- for_
each_ uart _device-selected
- This macro can be used to generate code for each peripheral instance of the UART driver.
- memory_
range _device-selected
- Macro to get the address range of the given memory region.
- property
_device-selected
- The properties of this chip and its drivers.
Enums§
- Chip
build-script