From d351f55e1c8e60a9bbd69b40b84a39dab5d20051 Mon Sep 17 00:00:00 2001 From: Emil Fresk Date: Thu, 25 Feb 2021 19:05:39 +0100 Subject: [PATCH] Documentation generation fixes Test fixes --- macros/src/codegen.rs | 42 +++++++++----------------- macros/src/codegen/dispatchers.rs | 24 +++++++++------ macros/src/codegen/locals.rs | 1 + macros/src/codegen/module.rs | 28 ++++++++++++++--- macros/src/codegen/post_init.rs | 3 +- macros/src/codegen/pre_init.rs | 22 ++++++++------ macros/src/codegen/resources.rs | 3 +- macros/src/codegen/resources_struct.rs | 3 +- macros/src/codegen/software_tasks.rs | 21 +++++++------ macros/src/codegen/timer_queue.rs | 24 +++++++++------ macros/src/codegen/util.rs | 9 ++---- ui/single/resources-cfg.stderr | 30 +++++++++--------- 12 files changed, 114 insertions(+), 96 deletions(-) diff --git a/macros/src/codegen.rs b/macros/src/codegen.rs index 7885a4a994..c5d956877b 100644 --- a/macros/src/codegen.rs +++ b/macros/src/codegen.rs @@ -57,6 +57,7 @@ pub fn app(app: &App, analysis: &Analysis, extra: &Extra) -> TokenStream2 { let main = util::suffixed("main"); mains.push(quote!( + #[doc(hidden)] mod rtic_ext { use super::*; #[no_mangle] @@ -88,22 +89,6 @@ pub fn app(app: &App, analysis: &Analysis, extra: &Extra) -> TokenStream2 { let user_code = &app.user_code; let name = &app.name; let device = &extra.device; - - // Get the list of all tasks - // Currently unused, might be useful - let task_list = analysis.tasks.clone(); - - let mut tasks = vec![]; - - if !task_list.is_empty() { - tasks.push(quote!( - #[allow(non_camel_case_types)] - pub enum Tasks { - #(#task_list),* - } - )); - } - let app_name = &app.name; let app_path = quote! {crate::#app_name}; @@ -114,25 +99,31 @@ pub fn app(app: &App, analysis: &Analysis, extra: &Extra) -> TokenStream2 { let name = &monotonic.ident; let name_str = &name.to_string(); let ty = &monotonic.ty; - let mangled_name = util::mangle_monotonic_type(&name_str); let ident = util::monotonic_ident(&name_str); + let ident = util::mark_internal_ident(&ident); let panic_str = &format!( "Use of monotonic '{}' before it was passed to the runtime", name_str ); + let doc = &format!( + "This module holds the static implementation for `{}::now()`", + name_str + ); + let user_imports = &app.user_imports; quote! { pub use rtic::Monotonic as _; - #[doc(hidden)] - pub type #mangled_name = #ty; - - /// This module holds the static implementation for `#name::now()` + #[doc = #doc] #[allow(non_snake_case)] pub mod #name { - /// Access the global `Monotonic` implementation, not that this will panic - /// before the this `Monotonic` has been passed to the RTIC runtime. - pub fn now() -> rtic::time::Instant<#app_path::#mangled_name> { + #( + #[allow(unused_imports)] + #user_imports + )* + + /// Read the current time from this monotonic + pub fn now() -> rtic::time::Instant<#ty> { rtic::export::interrupt::free(|_| { use rtic::Monotonic as _; use rtic::time::Clock as _; @@ -182,9 +173,6 @@ pub fn app(app: &App, analysis: &Analysis, extra: &Extra) -> TokenStream2 { #(#root_software_tasks)* - /// Unused - #(#tasks)* - /// app module #(#mod_app)* diff --git a/macros/src/codegen/dispatchers.rs b/macros/src/codegen/dispatchers.rs index d3adee0d42..dc33b1af60 100644 --- a/macros/src/codegen/dispatchers.rs +++ b/macros/src/codegen/dispatchers.rs @@ -26,15 +26,16 @@ pub fn codegen(app: &App, analysis: &Analysis, _extra: &Extra) -> Vec>(); - let doc = format!( - "Software tasks to be dispatched at priority level {}", - level, - ); + // let doc = format!( + // "Software tasks to be dispatched at priority level {}", + // level, + // ); let t = util::spawn_t_ident(level); items.push(quote!( #[allow(non_camel_case_types)] #[derive(Clone, Copy)] - #[doc = #doc] + // #[doc = #doc] + #[doc(hidden)] pub enum #t { #(#variants,)* } @@ -42,6 +43,7 @@ pub fn codegen(app: &App, analysis: &Analysis, _extra: &Extra) -> Vec), @@ -51,12 +53,12 @@ pub fn codegen(app: &App, analysis: &Analysis, _extra: &Extra) -> Vec Vec Result<(), #ty> { let input = #tupled; @@ -226,13 +231,16 @@ pub fn codegen( // Schedule caller for (_, monotonic) in &app.monotonics { let instants = util::monotonic_instants_ident(name, &monotonic.ident); + let instants = util::mark_internal_ident(&instants); let monotonic_name = monotonic.ident.to_string(); let tq = util::tq_ident(&monotonic.ident.to_string()); + let tq = util::mark_internal_ident(&tq); let t = util::schedule_t_ident(); let m = &monotonic.ident; - let m_mangled = util::mangle_monotonic_type(&monotonic_name); + let mono_type = &monotonic.ty; let m_ident = util::monotonic_ident(&monotonic_name); + let m_ident = util::mark_internal_ident(&m_ident); let m_isr = &monotonic.args.binds; let enum_ = util::interrupt_ident(); @@ -255,15 +263,24 @@ pub fn codegen( ) }; + let user_imports = &app.user_imports; + items.push(quote!( + /// Holds methods related to this monotonic pub mod #m { + #( + #[allow(unused_imports)] + #user_imports + )* + #(#cfgs)* + /// Spawns the task after a set duration relative to the current time pub fn spawn_after( duration: D #(,#args)* ) -> Result<(), #ty> where D: rtic::time::duration::Duration + rtic::time::fixed_point::FixedPoint, - D::T: Into<<#app_path::#m_mangled as rtic::time::Clock>::T>, + D::T: Into<<#app_path::#mono_type as rtic::time::Clock>::T>, { let instant = if rtic::export::interrupt::free(|_| unsafe { #app_path::#m_ident.is_none() }) { @@ -276,8 +293,9 @@ pub fn codegen( } #(#cfgs)* + /// Spawns the task at a fixed time instant pub fn spawn_at( - instant: rtic::time::Instant<#app_path::#m_mangled> + instant: rtic::time::Instant<#app_path::#mono_type> #(,#args)* ) -> Result<(), #ty> { unsafe { diff --git a/macros/src/codegen/post_init.rs b/macros/src/codegen/post_init.rs index 8ebcb12b19..96c5df80f9 100644 --- a/macros/src/codegen/post_init.rs +++ b/macros/src/codegen/post_init.rs @@ -13,7 +13,7 @@ pub fn codegen(app: &App, analysis: &Analysis) -> Vec { if !analysis.late_resources.is_empty() { // BTreeSet wrapped in a vector for name in analysis.late_resources.first().unwrap() { - let mangled_name = util::mangle_ident(&name); + let mangled_name = util::mark_internal_ident(&name); // If it's live let cfgs = app.late_resources[name].cfgs.clone(); if analysis.locations.get(name).is_some() { @@ -35,6 +35,7 @@ pub fn codegen(app: &App, analysis: &Analysis) -> Vec { // Store the monotonic let name = util::monotonic_ident(&monotonic.to_string()); + let name = util::mark_internal_ident(&name); stmts.push(quote!(#name = Some(monotonics.#idx);)); } diff --git a/macros/src/codegen/pre_init.rs b/macros/src/codegen/pre_init.rs index fbfff3b56e..d5105445dd 100644 --- a/macros/src/codegen/pre_init.rs +++ b/macros/src/codegen/pre_init.rs @@ -17,6 +17,7 @@ pub fn codegen(app: &App, analysis: &Analysis, extra: &Extra) -> Vec Vec Vec::DISABLE_INTERRUPT_ON_EMPTY_QUEUE { core::mem::transmute::<_, cortex_m::peripheral::SYST>(()) .enable_interrupt(); } @@ -107,13 +109,13 @@ pub fn codegen(app: &App, analysis: &Analysis, extra: &Extra) -> Vec::DISABLE_INTERRUPT_ON_EMPTY_QUEUE { + rtic::export::NVIC::unmask(#app_path::#rt_err::#interrupt::#binds); } )); } diff --git a/macros/src/codegen/resources.rs b/macros/src/codegen/resources.rs index 76871e598a..fa52b86db6 100644 --- a/macros/src/codegen/resources.rs +++ b/macros/src/codegen/resources.rs @@ -21,7 +21,7 @@ pub fn codegen( for (name, res, expr, _) in app.resources(analysis) { let cfgs = &res.cfgs; let ty = &res.ty; - let mangled_name = util::mangle_ident(&name); + let mangled_name = util::mark_internal_ident(&name); { let section = if expr.is_none() { @@ -42,6 +42,7 @@ pub fn codegen( let attrs = &res.attrs; mod_app.push(quote!( #[allow(non_upper_case_globals)] + #[doc(hidden)] #(#attrs)* #(#cfgs)* #section diff --git a/macros/src/codegen/resources_struct.rs b/macros/src/codegen/resources_struct.rs index bffe9431a5..8ed8a2912c 100644 --- a/macros/src/codegen/resources_struct.rs +++ b/macros/src/codegen/resources_struct.rs @@ -31,7 +31,7 @@ pub fn codegen(ctxt: Context, needs_lt: &mut bool, app: &App) -> (TokenStream2, None }; let ty = &res.ty; - let mangled_name = util::mangle_ident(&name); + let mangled_name = util::mark_internal_ident(&name); // let ownership = &analysis.ownerships[name]; let r_prop = &res.properties; @@ -112,6 +112,7 @@ pub fn codegen(ctxt: Context, needs_lt: &mut bool, app: &App) -> (TokenStream2, let doc = format!("Resources `{}` has access to", ctxt.ident(app)); let ident = util::resources_ident(ctxt, app); + let ident = util::mark_internal_ident(&ident); let item = quote!( #[allow(non_snake_case)] #[doc = #doc] diff --git a/macros/src/codegen/software_tasks.rs b/macros/src/codegen/software_tasks.rs index a760b06747..a39fe4cc2e 100644 --- a/macros/src/codegen/software_tasks.rs +++ b/macros/src/codegen/software_tasks.rs @@ -37,6 +37,7 @@ pub fn codegen( // Create free queues and inputs / instants buffers let fq = util::fq_ident(name); + let fq = util::mark_internal_ident(&fq); let (fq_ty, fq_expr, mk_uninit): (_, _, Box Option<_>>) = { ( @@ -48,8 +49,9 @@ pub fn codegen( ) }; mod_app.push(quote!( - /// Queue version of a free-list that keeps track of empty slots in - /// the following buffers + // /// Queue version of a free-list that keeps track of empty slots in + // /// the following buffers + #[doc(hidden)] static mut #fq: #fq_ty = #fq_expr; )); @@ -57,28 +59,29 @@ pub fn codegen( .map(|_| quote!(core::mem::MaybeUninit::uninit())) .collect::>(); - let app_name = &app.name; - let app_path = quote! {crate::#app_name}; - for (_, monotonic) in &app.monotonics { let instants = util::monotonic_instants_ident(name, &monotonic.ident); - let m = util::mangle_monotonic_type(&monotonic.ident.to_string()); + let instants = util::mark_internal_ident(&instants); + let mono_type = &monotonic.ty; let uninit = mk_uninit(); mod_app.push(quote!( #uninit - /// Buffer that holds the instants associated to the inputs of a task + // /// Buffer that holds the instants associated to the inputs of a task + #[doc(hidden)] static mut #instants: - [core::mem::MaybeUninit>; #cap_lit] = + [core::mem::MaybeUninit>; #cap_lit] = [#(#elems,)*]; )); } let uninit = mk_uninit(); let inputs_ident = util::inputs_ident(name); + let inputs_ident = util::mark_internal_ident(&inputs_ident); mod_app.push(quote!( #uninit - /// Buffer that holds the inputs of a task + // /// Buffer that holds the inputs of a task + #[doc(hidden)] static mut #inputs_ident: [core::mem::MaybeUninit<#input_ty>; #cap_lit] = [#(#elems,)*]; )); diff --git a/macros/src/codegen/timer_queue.rs b/macros/src/codegen/timer_queue.rs index ea2fee6635..82d0ac981e 100644 --- a/macros/src/codegen/timer_queue.rs +++ b/macros/src/codegen/timer_queue.rs @@ -26,9 +26,10 @@ pub fn codegen(app: &App, analysis: &Analysis, _extra: &Extra) -> Vec>(); - let doc = "Tasks that can be scheduled".to_string(); + // let doc = "Tasks that can be scheduled".to_string(); items.push(quote!( - #[doc = #doc] + // #[doc = #doc] + #[doc(hidden)] #[allow(non_camel_case_types)] #[derive(Clone, Copy)] enum #t { @@ -41,25 +42,27 @@ pub fn codegen(app: &App, analysis: &Analysis, _extra: &Extra) -> Vec); + let tq_ty = quote!(rtic::export::TimerQueue<#mono_type, #t, #n>); items.push(quote!( - #[doc = #doc] + #[doc(hidden)] static mut #tq: #tq_ty = rtic::export::TimerQueue( rtic::export::BinaryHeap( rtic::export::iBinaryHeap::new() @@ -68,12 +71,12 @@ pub fn codegen(app: &App, analysis: &Analysis, _extra: &Extra) -> Vec); + let mono = util::mark_internal_ident(&mono); + // let doc = &format!("Storage for {}", monotonic_name); items.push(quote!( - #[doc = #doc] - static mut #mono: #mono_ty = None; + #[doc(hidden)] + static mut #mono: Option<#mono_type> = None; )); } @@ -89,6 +92,7 @@ pub fn codegen(app: &App, analysis: &Analysis, _extra: &Extra) -> Vec bool { ) } -/// Mangle an ident -pub fn mangle_ident(ident: &Ident) -> Ident { +/// Mark an ident as internal +pub fn mark_internal_ident(ident: &Ident) -> Ident { Ident::new( &format!("__rtic_internal_{}", ident.to_string()), Span::call_site(), @@ -244,11 +244,6 @@ pub fn monotonic_ident(name: &str) -> Ident { Ident::new(&format!("MONOTONIC_STORAGE_{}", name), Span::call_site()) } -/// Generates an identifier for monotonic timer storage -pub fn mangle_monotonic_type(name: &str) -> Ident { - Ident::new(&format!("MonotonicMangled{}", name), Span::call_site()) -} - /// The name to get better RT flag errors pub fn rt_err_ident() -> Ident { Ident::new( diff --git a/ui/single/resources-cfg.stderr b/ui/single/resources-cfg.stderr index e367c51904..3bbbd2d9a8 100644 --- a/ui/single/resources-cfg.stderr +++ b/ui/single/resources-cfg.stderr @@ -4,7 +4,7 @@ error: duplicate lang item in crate `panic_halt` (which `$CRATE` depends on): `p = note: first definition in `std` loaded from /usr/share/rust/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/lib/libstd-6f77337c1826707d.rlib = note: second definition in `panic_halt` loaded from $DIR/target/tests/target/x86_64-unknown-linux-gnu/debug/deps/libpanic_halt-ad4cf7fac73711f1.rmeta -error[E0609]: no field `o1` on type `initResources<'_>` +error[E0609]: no field `o1` on type `__rtic_internal_initResources<'_>` --> $DIR/resources-cfg.rs:47:21 | 47 | c.resources.o1; @@ -12,7 +12,7 @@ error[E0609]: no field `o1` on type `initResources<'_>` | = note: available fields are: `__marker__` -error[E0609]: no field `o4` on type `initResources<'_>` +error[E0609]: no field `o4` on type `__rtic_internal_initResources<'_>` --> $DIR/resources-cfg.rs:48:21 | 48 | c.resources.o4; @@ -20,7 +20,7 @@ error[E0609]: no field `o4` on type `initResources<'_>` | = note: available fields are: `__marker__` -error[E0609]: no field `o5` on type `initResources<'_>` +error[E0609]: no field `o5` on type `__rtic_internal_initResources<'_>` --> $DIR/resources-cfg.rs:49:21 | 49 | c.resources.o5; @@ -28,7 +28,7 @@ error[E0609]: no field `o5` on type `initResources<'_>` | = note: available fields are: `__marker__` -error[E0609]: no field `o6` on type `initResources<'_>` +error[E0609]: no field `o6` on type `__rtic_internal_initResources<'_>` --> $DIR/resources-cfg.rs:50:21 | 50 | c.resources.o6; @@ -36,7 +36,7 @@ error[E0609]: no field `o6` on type `initResources<'_>` | = note: available fields are: `__marker__` -error[E0609]: no field `s3` on type `initResources<'_>` +error[E0609]: no field `s3` on type `__rtic_internal_initResources<'_>` --> $DIR/resources-cfg.rs:51:21 | 51 | c.resources.s3; @@ -44,7 +44,7 @@ error[E0609]: no field `s3` on type `initResources<'_>` | = note: available fields are: `__marker__` -error[E0609]: no field `o2` on type `idleResources<'_>` +error[E0609]: no field `o2` on type `__rtic_internal_idleResources<'_>` --> $DIR/resources-cfg.rs:58:21 | 58 | c.resources.o2; @@ -52,7 +52,7 @@ error[E0609]: no field `o2` on type `idleResources<'_>` | = note: available fields are: `__marker__` -error[E0609]: no field `o4` on type `idleResources<'_>` +error[E0609]: no field `o4` on type `__rtic_internal_idleResources<'_>` --> $DIR/resources-cfg.rs:59:21 | 59 | c.resources.o4; @@ -60,7 +60,7 @@ error[E0609]: no field `o4` on type `idleResources<'_>` | = note: available fields are: `__marker__` -error[E0609]: no field `s1` on type `idleResources<'_>` +error[E0609]: no field `s1` on type `__rtic_internal_idleResources<'_>` --> $DIR/resources-cfg.rs:60:21 | 60 | c.resources.s1; @@ -68,7 +68,7 @@ error[E0609]: no field `s1` on type `idleResources<'_>` | = note: available fields are: `__marker__` -error[E0609]: no field `s3` on type `idleResources<'_>` +error[E0609]: no field `s3` on type `__rtic_internal_idleResources<'_>` --> $DIR/resources-cfg.rs:61:21 | 61 | c.resources.s3; @@ -76,7 +76,7 @@ error[E0609]: no field `s3` on type `idleResources<'_>` | = note: available fields are: `__marker__` -error[E0609]: no field `o3` on type `uart0Resources<'_>` +error[E0609]: no field `o3` on type `__rtic_internal_uart0Resources<'_>` --> $DIR/resources-cfg.rs:68:21 | 68 | c.resources.o3; @@ -84,7 +84,7 @@ error[E0609]: no field `o3` on type `uart0Resources<'_>` | = note: available fields are: `__marker__` -error[E0609]: no field `s1` on type `uart0Resources<'_>` +error[E0609]: no field `s1` on type `__rtic_internal_uart0Resources<'_>` --> $DIR/resources-cfg.rs:69:21 | 69 | c.resources.s1; @@ -92,7 +92,7 @@ error[E0609]: no field `s1` on type `uart0Resources<'_>` | = note: available fields are: `__marker__` -error[E0609]: no field `s2` on type `uart0Resources<'_>` +error[E0609]: no field `s2` on type `__rtic_internal_uart0Resources<'_>` --> $DIR/resources-cfg.rs:70:21 | 70 | c.resources.s2; @@ -100,7 +100,7 @@ error[E0609]: no field `s2` on type `uart0Resources<'_>` | = note: available fields are: `__marker__` -error[E0609]: no field `s3` on type `uart0Resources<'_>` +error[E0609]: no field `s3` on type `__rtic_internal_uart0Resources<'_>` --> $DIR/resources-cfg.rs:71:21 | 71 | c.resources.s3; @@ -108,7 +108,7 @@ error[E0609]: no field `s3` on type `uart0Resources<'_>` | = note: available fields are: `__marker__` -error[E0609]: no field `s2` on type `uart1Resources<'_>` +error[E0609]: no field `s2` on type `__rtic_internal_uart1Resources<'_>` --> $DIR/resources-cfg.rs:76:21 | 76 | c.resources.s2; @@ -116,7 +116,7 @@ error[E0609]: no field `s2` on type `uart1Resources<'_>` | = note: available fields are: `__marker__` -error[E0609]: no field `o5` on type `uart1Resources<'_>` +error[E0609]: no field `o5` on type `__rtic_internal_uart1Resources<'_>` --> $DIR/resources-cfg.rs:77:21 | 77 | c.resources.o5;