[][src]Attribute Macro cortex_m_rtfm_macros::app

#[app]

Attribute used to declare a RTFM application

This attribute must be applied to a const item of type (). The const item is effectively used as a mod item: its value must be a block that contains items commonly found in modules, like functions and static variables.

The app attribute has one mandatory argument:

and a few optional arguments:

The items allowed in the block value of the const item are specified below:

1. struct Resources

This structure contains the declaration of all the resources used by the application. Each field in this structure corresponds to a different resource. Each resource may optionally be given an initial value using the #[init(<value>)] attribute. Resources with no compile-time initial value as referred to as late resources.

2. fn

Functions must contain one of the following attributes: init, idle or task. The attribute defines the role of the function in the application.

a. #[init]

This attribute indicates that the function is to be used as the initialization function. There must be exactly one instance of the init attribute inside the app pseudo-module. The signature of the init function must be fn (<fn-name>::Context) [-> <fn-name>::LateResources] where <fn-name> is the name of the function adorned with the #[init] attribute.

The init function runs after memory (RAM) is initialized and runs with interrupts disabled. Interrupts are re-enabled after init returns.

The init attribute accepts the following optional arguments:

The first argument of the function, <fn-name>::Context, is a structure that contains the following fields:

The return type <fn-name>::LateResources must only be specified when late resources, resources with no initial value declared at compile time, are used. <fn-name>::LateResources is a structure where each field corresponds to a different late resource. The <fn-name>::LateResources value returned by the #[init] function is used to initialize the late resources before idle or any task can start.

Other properties:

b. #[idle]

This attribute indicates that the function is to be used as the idle task. There can be at most once instance of the idle attribute inside the app pseudo-module. The signature of the idle function must be fn(<fn-name>::Context) -> ! where <fn-name> is the name of the function adorned with the #[idle] attribute.

The idle task is a special task that always runs in the background. The idle task runs at the lowest priority of 0. If the idle task is not defined then the runtime sets the SLEEPONEXIT bit after executing init.

The idle attribute accepts the following optional arguments:

The first argument of the function, idle::Context, is a structure that contains the following fields:

Other properties:

c. #[task]

This attribute indicates that the function is either a hardware task or a software task. The signature of hardware tasks must be fn(<fn-name>::Context) whereas the signature of software tasks must be fn(<fn-name>::Context, <inputs>). <fn-name> refers to the name of the function adorned with the #[task] attribute.

The task attribute accepts the following optional arguments.

The first argument of the function, <fn-name>::Context, is a structure that contains the following fields:

Other properties / constraints:

3. extern block

This extern block contains a list of interrupts which are not used by the application as hardware tasks. These interrupts will be used to dispatch software tasks. Each interrupt will be used to dispatch multiple software tasks at the same priority level.

This extern block must only contain functions with signature fn (). The names of these functions must match the names of the target device interrupts.

Attributes can be applied to the functions inside this block. These attributes will be forwarded to the interrupt handlers generated by the app attribute.