Merge #767

767: allow #[init] and #[idle] to be externed r=korken89 a=wiktorwieclaw

I updated `rtic-macros` to a allow init and idle to be externally defined.

## Design notes
* Updated `extern_binds` example to include external #[init] and #[idle] functions.
* Added docs to Local and Shared structs. The `extern_binds` example has a `#![deny(missing_docs)]` which caused some issues.

## Testing
Apart from building the example, I also used this feature in one of my projects and ran it on a MCU [here](https://github.com/grupacosmo/cansat/blob/98ca7bd42e737adfb140a548da1ade01beb495da/crates/cansat-stm32f4/src/main.rs#L59-L74)

## Related issues
* https://github.com/rtic-rs/rtic/issues/505

## Related PRs
* https://github.com/rtic-rs/rtic-syntax/pull/71

Co-authored-by: Vixu <lonevixu@gmail.com>

4 files changed, 113 insertions, 3 deletions

diff --git a/rtic-macros/src/syntax/ast.rs b/rtic-macros/src/syntax/ast.rs
index 3f4956c..f0067b8 100644
--- a/rtic-macros/src/syntax/ast.rs
+++ b/rtic-macros/src/syntax/ast.rs
@@ -91,6 +91,9 @@ pub struct Init {
 
     /// The name of the user provided local resources struct
     pub user_local_struct: Ident,
+
+    /// The init function is declared externally
+    pub is_extern: bool,
 }
 
 /// `init` context metadata
@@ -127,6 +130,9 @@ pub struct Idle {
 
     /// The statements that make up this `idle` function
     pub stmts: Vec<Stmt>,
+
+    /// The idle function is declared externally
+    pub is_extern: bool,
 }
 
 /// `idle` context metadata
diff --git a/rtic-macros/src/syntax/parse/app.rs b/rtic-macros/src/syntax/parse/app.rs
index 2f2d816..d75c8c6 100644
--- a/rtic-macros/src/syntax/parse/app.rs
+++ b/rtic-macros/src/syntax/parse/app.rs
@@ -367,6 +367,42 @@ impl App {
                             if let Some(pos) = item
                                 .attrs
                                 .iter()
+                                .position(|attr| util::attr_eq(attr, "init"))
+                            {
+                                let args = InitArgs::parse(item.attrs.remove(pos).tokens)?;
+
+                                // If an init function already exists, error
+                                if init.is_some() {
+                                    return Err(parse::Error::new(
+                                        span,
+                                        "`#[init]` function must appear at most once",
+                                    ));
+                                }
+
+                                check_ident(&item.sig.ident)?;
+
+                                init = Some(Init::parse_foreign(args, item)?);
+                            } else if let Some(pos) = item
+                                .attrs
+                                .iter()
+                                .position(|attr| util::attr_eq(attr, "idle"))
+                            {
+                                let args = IdleArgs::parse(item.attrs.remove(pos).tokens)?;
+
+                                // If an idle function already exists, error
+                                if idle.is_some() {
+                                    return Err(parse::Error::new(
+                                        span,
+                                        "`#[idle]` function must appear at most once",
+                                    ));
+                                }
+
+                                check_ident(&item.sig.ident)?;
+
+                                idle = Some(Idle::parse_foreign(args, item)?);
+                            } else if let Some(pos) = item
+                                .attrs
+                                .iter()
                                 .position(|attr| util::attr_eq(attr, "task"))
                             {
                                 if hardware_tasks.contains_key(&item.sig.ident)
@@ -408,7 +444,8 @@ impl App {
                             } else {
                                 return Err(parse::Error::new(
                                     span,
-                                    "`extern` task required `#[task(..)]` attribute",
+                                    "`extern` task, init or idle must have either `#[task(..)]`,
+                                    `#[init(..)]` or `#[idle(..)]` attribute",
                                 ));
                             }
                         } else {
diff --git a/rtic-macros/src/syntax/parse/idle.rs b/rtic-macros/src/syntax/parse/idle.rs
index 124c136..a3d9715 100644
--- a/rtic-macros/src/syntax/parse/idle.rs
+++ b/rtic-macros/src/syntax/parse/idle.rs
@@ -1,5 +1,5 @@
 use proc_macro2::TokenStream as TokenStream2;
-use syn::{parse, ItemFn};
+use syn::{parse, ForeignItemFn, ItemFn, Stmt};
 
 use crate::syntax::{
     ast::{Idle, IdleArgs},
@@ -29,6 +29,35 @@ impl Idle {
                         context,
                         name: item.sig.ident,
                         stmts: item.block.stmts,
+                        is_extern: false,
+                    });
+                }
+            }
+        }
+
+        Err(parse::Error::new(
+            item.sig.ident.span(),
+            format!("this `#[idle]` function must have signature `fn({name}::Context) -> !`"),
+        ))
+    }
+
+    pub(crate) fn parse_foreign(args: IdleArgs, item: ForeignItemFn) -> parse::Result<Self> {
+        let valid_signature = util::check_foreign_fn_signature(&item, false)
+            && item.sig.inputs.len() == 1
+            && util::type_is_bottom(&item.sig.output);
+
+        let name = item.sig.ident.to_string();
+
+        if valid_signature {
+            if let Some((context, Ok(rest))) = util::parse_inputs(item.sig.inputs, &name) {
+                if rest.is_empty() {
+                    return Ok(Idle {
+                        args,
+                        attrs: item.attrs,
+                        context,
+                        name: item.sig.ident,
+                        stmts: Vec::<Stmt>::new(),
+                        is_extern: true,
                     });
                 }
             }
diff --git a/rtic-macros/src/syntax/parse/init.rs b/rtic-macros/src/syntax/parse/init.rs
index 0aea20b..59d0093 100644
--- a/rtic-macros/src/syntax/parse/init.rs
+++ b/rtic-macros/src/syntax/parse/init.rs
@@ -1,6 +1,6 @@
 use proc_macro2::TokenStream as TokenStream2;
 
-use syn::{parse, ItemFn};
+use syn::{parse, ForeignItemFn, ItemFn, Stmt};
 
 use crate::syntax::{
     ast::{Init, InitArgs},
@@ -35,6 +35,44 @@ impl Init {
                             stmts: item.block.stmts,
                             user_shared_struct,
                             user_local_struct,
+                            is_extern: false,
+                        });
+                    }
+                }
+            }
+        }
+
+        Err(parse::Error::new(
+            span,
+            format!(
+                "the `#[init]` function must have signature `fn({name}::Context) -> (Shared resources struct, Local resources struct)`"
+            ),
+        ))
+    }
+
+    pub(crate) fn parse_foreign(args: InitArgs, item: ForeignItemFn) -> parse::Result<Self> {
+        let valid_signature =
+            util::check_foreign_fn_signature(&item, false) && item.sig.inputs.len() == 1;
+
+        let span = item.sig.ident.span();
+
+        let name = item.sig.ident.to_string();
+
+        if valid_signature {
+            if let Ok((user_shared_struct, user_local_struct)) =
+                util::type_is_init_return(&item.sig.output)
+            {
+                if let Some((context, Ok(rest))) = util::parse_inputs(item.sig.inputs, &name) {
+                    if rest.is_empty() {
+                        return Ok(Init {
+                            args,
+                            attrs: item.attrs,
+                            context,
+                            name: item.sig.ident,
+                            stmts: Vec::<Stmt>::new(),
+                            user_shared_struct,
+                            user_local_struct,
+                            is_extern: true,
                         });
                     }
                 }