Crate rtic_core

This is a re-usable crate that captures the hardware agnostic proc-macro logic for RTIC’s tasks and resources syntax model (both single and multicore syntax). I.e the user code parsing, analysis and generation for hardware tasks, local resources, shared resources and their locking mechanism, system init and idle tasks.

In addition, this crate provides utilities for building the actual RTIC crate (known as an RTIC distribution) that exports the RTIC framework attribute procedural macro for a specific target hardware architecture. Further more, the same utilizes allow extending the core syntax provided by this crate through the concept of Compilation passes. As a result, this crate is not meant to be used directly by users who want to write RTIC applications, instead it is used by RTIC distribution implementors.

RTIC Compilation passes

An rtic compilation pass is is represented in rust by a type that implements the RticPass trait:

use proc_macro2::TokenStream as TokenStream2;
pub trait RticPass {
    fn run_pass(
        self, args: TokenStream2, app_mod: ItemMod,
    ) -> syn::Result<(TokenStream2, ItemMod)>;
}

The trait has one method that is quite similar to an attribute proc macro definition. It takes a tokenstream representing the #[rtic::app(..)] attribute and the second argument represent the user RTIC application. The returned value represents the expanded inputs.

The idea here is that a compilation pass does’t expand the entire rtic application, but instead it implements a specific feature-set of the RTIC framework. Then multiple (compatible) passes are chained together to form the whole proc-macro logic for expanding a user application.

For example, a compilation pass may only understand how to expand monotonics, then the output is provided to the next pass which understand how to describe software tasks interms of hardware tasks and message queues. Finally, the output is fed to the lowest level pass which knows how to generate the SRP model from hardware tasks and resources.

This approach allows developing compilation passes contained within their own crates and maintain them separately, then an RTIC distribution crate, can select and integrate a set of passes to form an rtic proc-macro crate with a given set of features provided by the combined passes.

Compilation passes are usually written in a hardware agnostic fashion, and the target specific details can be provided through what we call Backend traits implementations. Each pass may have an associated Backend trait that list some functions which a distribution implements to guide the pass on how to generate code that is directly related to the target hardware. One example of a compilation pass and its associated Backend trait is the core compilation pass provided by rtic-core crate. The backend trait for that pass is called rtic_core::CorePassBackend.

RTIC distributions

Definition

An RTIC distribution is a rust crate that exposes the RTIC attribute proc-macro implemented for a specific hardware architecture, or for a specific micro-controller, or even for a specific target use case (with non-standard syntax). For example, we could have a distribution for single core cortex-m devices, another distribution specifically tailored for the multicore RP2040, a distribution for risc-v architecture … etc.

The responsibility for a distribution crate is to:

1. Implement the low level hardware specific details and provide/bind that to the hardware agnostic RTIC compilation passes.
2. Integrate a selection of compatible Compilation passes and optionally expose them to the user as a set of features which the user can select to enable.
3. Expose the RTIC proc macro generated by RticMacroBuilder after performing the previous two steps

Distributions allow the RTIC code-base growth more controllable and provides an alternative approach to the older approach in which all the hardware specific details all belong to a single crate maintained by the RTIC team, and users choose an implementation for some specific hardware is chosen by enabling a corresponding rust feature for their target hardware.

How to implement a distribution using rtic_core::RticMacroBuilder?

todo: provide short example and link to template distro

Guidelines for implementing new distributions, links, and link to template distribution

TODO…

Modules

• errors
• multibin
• parse_utils
  Provides a utility to streamline parsing and manipulating and reconstructing the tokenstream representation of the #[app(arg1=“val1”, …)] attribute
• rtic_functions
• rtic_traits

Structs

• Analysis
• App
• AppArgs
  Arguments provided to the #[app(…)] macro attribute, this includes paths to PACs, number of cores, and peripherals option.
• RticMacroBuilder
  This should be used to compose an RTIC distribution. In other words, it allows building the RTIC app macro By providing the necessary low-level hardware bindings and binding additional Compilation Passes in the case syntax extensions are desired.
• SubAnalysis
• SubApp

Traits

• CorePassBackend
  Interface for providing the low-level hardware bindings specific for a target(s) (A.k.a The Backend) to be used during code generation phase of the *Core Compilation Pass.
• RticPass
  A trait that allows defining a Compilation Pass.