implement #552

Author: Luro02

Cargo.toml

@@ -1,3 +1,6 @@
+[workspace]
+members = ["esp-idf-macros"]
+
 [package]
 name = "esp-idf-hal"
 version = "0.45.2"
@@ -25,7 +28,7 @@ harness = false
 default = ["std", "binstart"]
 std = ["alloc", "esp-idf-sys/std"]
 alloc = []
-nightly = []
+nightly = ["esp-idf-macros/doc-cfg"]
 experimental = []
 wake-from-isr = [] # Only enable if you plan to use the `edge-executor` crate
 embassy-sync = [] # For now, the dependecy on the `embassy-sync` crate is non-optional, but this might change in future
@@ -62,6 +65,7 @@ enumset = { version = "1.1.4", default-features = false }
 log = { version = "0.4", default-features = false }
 atomic-waker = { version = "1.1.1", default-features = false }
 embassy-sync = "0.7"
+esp-idf-macros = { path = "esp-idf-macros" }
 
 [build-dependencies]
 embuild = "0.33"

esp-idf-macros/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "esp-idf-macros"
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.79"
+
+[lib]
+proc-macro = true
+
+[features]
+default = []
+doc-cfg = []
+
+[dependencies]
+proc-macro2 = "1"
+quote = "1"
+syn = { version = "2", features = ["extra-traits", "full", "fold"] }

esp-idf-macros/src/dcfg.rs

@@ -0,0 +1,24 @@
+use proc_macro2::TokenStream;
+use quote::{quote, quote_spanned};
+use syn::spanned::Spanned;
+
+pub fn dcfg(args: TokenStream, input: TokenStream) -> syn::Result<TokenStream> {
+    // This will either emit #[cfg(...)] or #[cfg(...)] #[doc(cfg(...))] depending on whether
+    // the "doc-cfg" feature is enabled.
+
+    let attrs = {
+        #[cfg(feature = "doc-cfg")]
+        {
+            quote_spanned!(args.span() => #[cfg(#args)] #[doc(cfg(#args))])
+        }
+        #[cfg(not(feature = "doc-cfg"))]
+        {
+            quote_spanned!(args.span() => #[cfg(#args)])
+        }
+    };
+
+    Ok(quote! {
+        #attrs
+        #input
+    })
+}

esp-idf-macros/src/lib.rs

@@ -0,0 +1,136 @@
+use proc_macro::TokenStream;
+
+mod dcfg;
+mod ram;
+
+/// This attribute places the annotated function or static variable into the internal RAM
+/// of the ESP32 chip.
+///
+/// # Possible issues with functions
+///
+/// If a function is placed into RAM, the literals are not automatically placed into RAM as well:
+///
+/// ```rust,ignore
+/// #[ram]
+/// fn gpio_isr_handler() -> usize {
+///     let s = "I am string still stored in flash";
+/// }
+/// ```
+///
+/// To store the literal in flash, one could do
+/// ```rust,ignore
+/// #[ram]
+/// fn gpio_isr_handler() -> usize {
+///     #[ram]
+///     static _S: &str = "I am string still stored in flash";
+///     let s = _S;
+/// }
+/// ```
+///
+/// # Possible issues with statics that reference data
+///
+/// If the attribute is applied to a static variable that references some data, for example
+/// `#[ram] static MESSAGE: &str = "Error, invalid argument";` or `#[ram] static BUFFER: &[u8] = &[0]`
+/// the referenced data might not be placed into RAM.
+///
+/// For byte string and string literals, the attribute will ensure that the referenced data is placed in
+/// RAM, but for arbitrary slices or references it is unable to do so.
+///
+/// The first option is to declare an owned static array that is then referenced by the static variable,
+/// applying the ram attribute to both:
+///
+/// ```rust,ignore
+/// #[ram]
+/// static BUFFER_DATA: [u8; 3] = [0, 1, 2];
+/// #[ram]
+/// static BUFFER: &[u8] = &BUFFER_DATA;
+/// ```
+///
+/// or like this:
+///
+/// ```rust,ignore
+/// #[ram]
+/// static BUFFER: &[u8] = {
+///     #[ram]
+///     static DATA: [u8; 3] = [0, 1, 2];
+///     DATA.as_slice()
+/// };
+/// ```
+///
+/// If the slice value is [`Copy`], the attribute can do this automatically:
+/// ```rust,ignore
+/// #[ram(copy)]
+/// static BUFFER: [u8; 3] = &[0, 1, 2];
+/// ```
+#[proc_macro_attribute]
+pub fn ram(args: TokenStream, input: TokenStream) -> TokenStream {
+    ram::ram(args.into(), input.into())
+        .unwrap_or_else(|err| err.to_compile_error().into())
+        .into()
+}
+
+/// This attribute forwards its arguments to `cfg`, and if the `doc-cfg` feature of this
+/// crate is enabled, it will emit a `doc(cfg(...))` attribute as well.
+///
+/// # Example
+///
+/// For rustdoc to document that a piece of code is only available when a specific condition is met,
+/// one would have to write (because it is nightly-only):
+///
+/// ```rust,ignore
+/// pub enum ZeroCrossMode {
+//      PositionZero,
+//      NegativeZero,
+//      NegativePosition,
+//      PositiveNegative,
+//      #[cfg(esp_idf_version_at_least_5_4_0)]
+//      #[cfg_attr(feature = "nightly", doc(cfg(esp_idf_version_at_least_5_4_0)))]
+//      Invalid,
+//  }
+/// ```
+///
+/// with this attribute, one can shorten it to:
+///
+/// ```rust,ignore
+/// pub enum ZeroCrossMode {
+//      PositionZero,
+//      NegativeZero,
+//      NegativePosition,
+//      PositiveNegative,
+//      #[dcfg(esp_idf_version_at_least_5_4_0)]
+//      Invalid,
+//  }
+/// ```
+///
+/// The macro will then expand to the following if the `doc-cfg` feature is enabled:
+///
+/// ```rust,ignore
+/// pub enum ZeroCrossMode {
+///     PositionZero,
+///     NegativeZero,
+///     NegativePosition,
+///     PositiveNegative,
+///     #[cfg(esp_idf_version_at_least_5_4_0)]
+///     #[doc(cfg(esp_idf_version_at_least_5_4_0))]
+///     Invalid,
+/// }
+/// ```
+///
+/// and to the following if the `doc-cfg` feature is not enabled:
+///
+/// ```rust,ignore
+/// pub enum ZeroCrossMode {
+///     PositionZero,
+///     NegativeZero,
+///     NegativePosition,
+///     PositiveNegative,
+///     #[cfg(esp_idf_version_at_least_5_4_0)]
+///     Invalid,
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn dcfg(args: TokenStream, input: TokenStream) -> TokenStream {
+    dcfg::dcfg(args.into(), input.into())
+        .unwrap_or_else(|err| err.to_compile_error().into())
+        .into()
+}