Crate esp_metadata_generated

Source
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 and OutputSignal 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§

Chipbuild-script