esp_metadata_generated/

lib.rs

// Do NOT edit this file directly. Make your changes to esp-metadata,
// then run `cargo xtask update-metadata`.

//! # (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:
//!
//! ```toml
//! [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:
//!
//! ```toml
//! [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:
//!
//! ```rust, no_run
//! 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.
//!
//! ```rust,no_run
//! 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.
//!
//! ```rust,no_run
//! // 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>,
//!             )*
//!         }
//!     };
//! }
//! ```
#![cfg_attr(docsrs, feature(doc_cfg))]
#![cfg_attr(not(feature = "build-script"), no_std)]
#[cfg(all(not(feature = "build-script"), feature = "esp32"))]
include!("_generated_esp32.rs");
#[cfg(all(not(feature = "build-script"), feature = "esp32c2"))]
include!("_generated_esp32c2.rs");
#[cfg(all(not(feature = "build-script"), feature = "esp32c3"))]
include!("_generated_esp32c3.rs");
#[cfg(all(not(feature = "build-script"), feature = "esp32c6"))]
include!("_generated_esp32c6.rs");
#[cfg(all(not(feature = "build-script"), feature = "esp32h2"))]
include!("_generated_esp32h2.rs");
#[cfg(all(not(feature = "build-script"), feature = "esp32s2"))]
include!("_generated_esp32s2.rs");
#[cfg(all(not(feature = "build-script"), feature = "esp32s3"))]
include!("_generated_esp32s3.rs");
#[cfg(any(feature = "build-script", docsrs))]
include!("_build_script_utils.rs");